did.document should mint the shape it was asked for, not always V_delta canonical (V2)

Start with src/did/+did/document.m, focusing on i_normalizeDependsOn, set_dependency_value, and add_dependency_value_n. Read the class definition from did.document.readblankdefinition to understand how class_version and schema determine the requested shape, then inspect tests under tests/+did/+unittest/ for depends_on key assertions. Done means V1, V_delta draft, and V_zeta documents write their matching dependency keys without changing the read path.

Background

did.document on V2 is the reads-both-writes-canonical bridge between V1/V_alpha documents and V_delta/V_zeta canonical documents. The did2. namespace holds the native V_zeta class.

Reads: i_readDependencyTarget accepts depends_on entries in three shapes, with precedence document_id > value > id:

• document_id — V_delta/V_zeta canonical
• value — V_delta draft (transitional)
• id — V_alpha legacy (V1)

Writes: The constructor's i_normalizeDependsOn and set_dependency_value both write only document_id. So a document constructed from a V1 struct is silently canonicalized to V_delta on the way in, and any subsequent write path emits document_id.

Concern

A V1 dataset opened through did.document and re-saved comes back V_delta-shaped on disk. That is a silent migration on touch — nothing in the caller's request said "convert this to V2." External tools that expected V1 exact-shape (Python readers, other MATLAB clients, existing test fixtures) may break, and there's no explicit migrator invocation surface for users who want migration to be a deliberate step.

Proposed direction

Make the WRITE path schema-aware:

1. Derive the requested "dependency shape" from the document's class definition (which itself came from a versioned schema — V_alpha, V_delta draft, V_delta canonical / V_zeta).
2. set_dependency_value writes to the matching key (id, value, or document_id).
3. add_dependency_value_n inherits the same shape choice.
4. Constructor's i_normalizeDependsOn becomes a no-op when the requested shape matches the input shape; it only converts when the caller has explicitly asked for a different shape.
5. Read path is unchanged — i_readDependencyTarget already handles all three.

Roundtrip fidelity: read V1 → write V1; read V_zeta → write V_zeta. Migration becomes an explicit action.

Where the shape decision lives

The class definition (loaded via did.document.readblankdefinition) carries a class_version and a schema. That is the natural place to record the dependency shape convention for the class, either as a schema attribute or by inference from the schema's class_version. Adding a small helper did.document.i_dependencyShape(document_properties) that returns 'id' | 'value' | 'document_id' and using it at every write site is a plausible shape for the refactor.

Non-goals

• Not changing the read path (already accepts all three).
• Not touching the did2. namespace — that remains the native V_zeta path.
• Not converting existing V1 datasets — this issue is about mint-time behavior, not stored data.

Scope of change

The write sites in src/did/+did/document.m (per V2 head at time of filing):

• Constructor's i_normalizeDependsOn call
• set_dependency_value
• add_dependency_value_n (indirectly via set_dependency_value)

Plus any test fixtures under tests/+did/+unittest/ that assert on the depends_on key name.

Origin

Raised during the main → V2_Update merge review (PR #203), when we noticed V2's set_dependency_value writes .document_id while main still writes .value. Taking V2's version wins on V_delta correctness but formalizes the silent-migration behavior. This issue tracks the design work to make writes match the requested schema shape instead.