Skip to content

refactor: unify builtin template note storage between local and cloud #222

Description

@ShotaroKataoka

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:

Cloud (L3/L4) Local (L1/L2/local Web UI)
Storage DDB item BUILTIN_NOTE#<name> per user — first-class entity state.jsontemplate_metadata["builtin:<name>"].description — field inside the analysis-cache entry
Merge point Tool layer (mcp-server/tools/template.py + storage.get_builtin_template_notes()) Engine (sdpm.api.list_templates_with_metadata knows the builtin: key convention)

Why this is debt

  1. 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).
  2. 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").
  3. 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.
  • No behavior change for end users.

Refs: #166, #204, #209

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions