You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Per-user notes on builtin templates were added in #204 (cloud) and extended to local mode + L1 CLI in #209. The two paths ended up with structurally different data models for the same concept:
Cloud (L3/L4)
Local (L1/L2/local Web UI)
Storage
DDB item BUILTIN_NOTE#<name> per user — first-class entity
state.json → template_metadata["builtin:<name>"].description — field inside the analysis-cache entry
Engine (sdpm.api.list_templates_with_metadata knows the builtin: key convention)
Why this is debt
User data and regenerable cache share one entry in local state.json. Clearing the analysis cache risks wiping user notes; every writer must carefully preserve description (see the PATCH /api/templates/builtin/[name] route).
Inverted dependency: the builtin: key convention originated in the local Web UI listing route; the engine now follows a consumer's convention (vs. "Engine is source of truth").
Asymmetry trap: the cloud path does not use list_templates_with_metadata at all. Anyone consolidating L3 onto the engine could silently break note resolution. (Documented in the engine docstring since feat: template notes in local mode + L1 CLI descriptions #209, but documentation is a mitigation, not a fix.)
Proposed direction
Move local notes to a dedicated template_notes section in state.json (mirroring the cloud separation), with a one-time migration from template_metadata["builtin:<name>"].description.
Have consumers merge notes at their layer (like cloud does), or pass notes to the engine as an explicit parameter — removing the builtin:/plain dual-key lookup from list_templates_with_metadata.
Keep the legacy fallback for one minor version, then drop it (pre-1.0).
Non-goals
No cloud-side changes — the DDB BUILTIN_NOTE# model is the reference design.
Background
Per-user notes on builtin templates were added in #204 (cloud) and extended to local mode + L1 CLI in #209. The two paths ended up with structurally different data models for the same concept:
BUILTIN_NOTE#<name>per user — first-class entitystate.json→template_metadata["builtin:<name>"].description— field inside the analysis-cache entrymcp-server/tools/template.py+storage.get_builtin_template_notes())sdpm.api.list_templates_with_metadataknows thebuiltin:key convention)Why this is debt
description(see thePATCH /api/templates/builtin/[name]route).builtin:key convention originated in the local Web UI listing route; the engine now follows a consumer's convention (vs. "Engine is source of truth").list_templates_with_metadataat all. Anyone consolidating L3 onto the engine could silently break note resolution. (Documented in the engine docstring since feat: template notes in local mode + L1 CLI descriptions #209, but documentation is a mitigation, not a fix.)Proposed direction
template_notessection instate.json(mirroring the cloud separation), with a one-time migration fromtemplate_metadata["builtin:<name>"].description.builtin:/plain dual-key lookup fromlist_templates_with_metadata.Non-goals
BUILTIN_NOTE#model is the reference design.Refs: #166, #204, #209