Add per-field placement attribute (declaring_class / concrete_class)

[stevevanhooser]

Summary

Introduce a per-field placement attribute on field definitions, with values "declaring_class" (default; current behavior preserved) and "concrete_class" (route the field into the concrete subclass's body block on instance documents, only valid on fields declared by an abstract class). Apply it to V_delta calculator.input_parameters.

This captures intent that was always implicit in V_gamma's abstract-class design but was never articulated. The schema-author phrase "every calculator subclass instance must supply input_parameters" naturally describes a field that lives in the concrete subclass's block — exactly where did_v1 documents already store it (<calc_class>.input_parameters), and where every NDI calculator writer (ndi.element.addepoch, ndi.element.oneepoch, the mocks) puts it. The previous spec text mandated the field live in calculator.input_parameters (a parent-named block), which forced the migrator to perform a move and produced shape drift between the calc's in-memory output and the gate-normalized read-back of expected-doc JSON. That mismatch is the proximate cause of testCalcTuningCurve failing on the NDI-matlab claude/776-flip-did2-normalize-gate branch.

Design

placement is per-field, not per-class. Different fields on the same abstract class can choose differently. Allowed values:

placement value	Where the field lives on a document instance
"declaring_class" (default)	In the property block named after the declaring class — current V_gamma rule.
"concrete_class"	In the property block named after the document's concrete class (document_class.class_name). The declaring abstract class does not host the field on the instance body.

Restrictions:

• "concrete_class" is only valid when the declaring class has document_class.abstract: true. A concrete class with placement: "concrete_class" on one of its own fields is a schema error.
• Field-name collisions on the concrete-class block (two ancestors place the same name, or a concrete class redeclares an ancestor-placed name) are detected at class-cache build time as a hard schema error. No silent precedence rule.
• An abstract class whose declared fields are all "concrete_class"-placed contributes no property block on instance bodies.

Changes

V_gamma_SPEC.md (the authoritative spec; V_delta inherits):

• "Abstract Classes": note the placement-driven body-block omission.
• "Field Definition Object": add placement row to the field-definition key table; add new "Field placement (new in V_gamma)" subsection covering values, restrictions, multi-inheritance collision rules, and the effect on instance body shape.
• "JSON Format: Document Instances": relax "exactly one block per chain class" to "one block per chain class that contributes a block"; update the "Provenance is structural", "Required vs. empty blocks", and "No cross-block field movement" rules to reflect placement-driven exceptions.

V_delta_SPEC.md: new differences-from-V_gamma section noting that V_delta is the first set to exercise placement, applied to calculator.input_parameters.

Schemas:

• schemas/V_delta/stable/calculator.json: add "placement": "concrete_class" to the input_parameters field with documentation pointing at the spec section.
• schemas/V_delta/stable/did_schema_meta.json and schemas/V_gamma/did_schema_meta.json: register placement as an allowed optional field-definition property (enum: ["declaring_class", "concrete_class"]). Required because additionalProperties: false on the field-definition object would otherwise reject the new key.

What this does not change

• No DID-matlab implementation changes are in this PR. The corresponding calcCommon / ensureClassBlocks / class-cache updates will follow in a separate PR against vh-lab/did-matlab@claude/lucid-heisenberg-fSrVB, gated on this spec landing.
• No V_gamma or V_delta concrete *_calc schemas change; simple_calc, tuningcurve_calc, etc. continue to declare their own non-inherited fields in the concrete class block. The input_parameters field is inherited from the abstract calculator parent and now lives in the same per-subclass block via placement routing, matching the on-disk layout of legacy did_v1 documents and removing the need for the calc migrator to perform a move.

Test plan

• CI on this PR: schema set parses; meta-schema accepts placement on the calculator.input_parameters field and rejects it on a concrete-class field (if a meta-schema test fixture exercises that path).
• After merge: follow-up DID-matlab PR (claude/lucid-heisenberg-fSrVB) lands the cache / migrator / ensureClassBlocks side; once that merges to V2, NDI-matlab testCalcTuningCurve on claude/776-flip-did2-normalize-gate goes green and we clean up the diagnostic dumps.

Background

• NDI-matlab issue: [did2 #3] Route v1→V_delta normalization through ndi.database (not session/dataset) VH-Lab/NDI-matlab#776 (flip did2 read-normalization gate).
• Diagnostic trace that surfaced this issue: the gate-flipped tuningcurve test fails because expected docs carry calculator.input_parameters.X (post-migrator) while actual in-memory calc output carries <class>.input_parameters.X, and the comparison config uses the latter path. Root cause is the spec/migrator combination forcing the move; correct semantics is to keep the field in the concrete subclass block where every legacy and live writer already places it.

---

Generated by Claude Code