Add V_zeta schema version with Brainstorm I architecture

README.md

@@ -19,6 +19,8 @@ Each field definition object contains: `name`, `type`, `blank_value`, `default_v
 
 See [schemas/V_alpha_SPEC.md](schemas/V_alpha_SPEC.md) for the V_alpha specification and [schemas/V_beta_SPEC.md](schemas/V_beta_SPEC.md) for the V_beta specification (V_alpha plus snake_case naming requirements).
 
+The current sandbox iteration is **V_zeta** (see [schemas/V_zeta_SPEC.md](schemas/V_zeta_SPEC.md)), which implements **Brainstorm I** from the `ndi-next-steps` "Summer 2026 / 1_Ingestion" thread: a single `subject_interaction` spine (`subject_id`, a shaped `time_reference`, `method`, `variable`, `target_structure`), direction carried by the empty `observation` / `manipulation` classes, observation leaves named by data-type (shape) with identity on the `variable` ontology term, and the `dataseries_observation` branch. V_zeta supersedes V_epsilon (Brainstorm E, retained as an archived reference). Within each `V_*` directory, `index.json` is the resolution source of truth.
+
 ## Directory layout
 
 Each document type is a directory under `schemas/` containing its schema definition:

schemas/V_zeta/conversions/from_did_v1/_TEMPLATE.md

@@ -0,0 +1,92 @@
+# Conversion: did_v1 → V_zeta — `<class_name>`
+
+> Copy this file to `<class_name>.md` (one file per V_zeta document type that
+> has a `did_v1` analog) and fill in every section. Sections that genuinely do
+> not apply should be retained with the text `N/A` so reviewers can see they
+> were considered, not skipped.
+
+## Identity
+
+- **V_zeta `class_name`:** `<class_name>`
+- **V_zeta tier:** `stable` | `draft` | `deprecated`
+- **V_zeta schema path:** `schemas/V_zeta/<tier>/<class_name>.json`
+- **did_v1 source:** repo + path (or "synthesized from MATLAB class
+  `<...>`")
+- **Status:** `drafted` | `reviewed` | `applied-in-tooling` | `frozen`
+
+## Summary
+
+One or two sentences. What is this document type, and what is the
+high-level shape of the change between did_v1 and V_zeta? If there is no
+change, say so.
+
+## Field mapping
+
+Use one row per field. Cover every field in both the did_v1 source and the
+V_zeta target — including dropped fields (V_zeta column blank) and new
+fields (did_v1 column blank).
+
+| did_v1 field | V_zeta field | Transformation | Notes |
+|---|---|---|---|
+| `<old>` | `<new>` | rename | |
+| `<old>` | `<new>` | type change: `<from>` → `<to>` | Validation rules below |
+| `<old>` | — | dropped | Reason |
+| — | `<new>` | new field | Default value: `<...>` |
+| `<old>` | `<new>` | identity | |
+
+## Transformations in detail
+
+For any row above whose transformation is non-trivial (type change, unit
+conversion, structural reshape, value mapping), describe the rule here in
+enough detail that a reader could implement it without consulting the
+author. Cite the relevant spec section if applicable.
+
+## Default values for new fields
+
+If V_zeta introduces required fields that did_v1 documents do not carry,
+list the default each migrated document gets, and the reasoning. Distinguish
+between "constant default" and "computed from other fields."
+
+## Worked example
+
+A minimal but realistic did_v1 document and the V_zeta document it converts
+to. These pairs double as unit-test fixtures — keep them small enough to
+read by eye.
+
+### Before (did_v1)
+
+```json
+{
+  "document_class": { "class_name": "<class_name>", "schema_version": "did_v1", ... },
+  ...
+}
+```
+
+### After (V_zeta)
+
+```json
+{
+  "document_class": { "class_name": "<class_name>", "class_version": "...", "schema_version": "V_zeta", ... },
+  ...
+}
+```
+
+## File handling
+
+If this document type carries or references files (binary blobs, external
+paths, hash-addressed content), describe how those are handled on migration.
+For anything that follows the generic rules, link to `_files.md` instead of
+restating them here. Document only the type-specific behavior.
+
+## Open questions
+
+Anything still undecided. Pose as concrete questions, not vague concerns.
+Each question should be resolvable by a domain owner without needing to
+re-read this whole doc.
+
+## Cross-references
+
+- Related document types whose conversions interact with this one:
+- did_v1 source-of-truth path(s):
+- V_zeta schema file:
+- General file-handling rules: [`_files.md`](_files.md)

schemas/V_zeta/conversions/from_did_v1/_files.md

@@ -0,0 +1,71 @@
+# File handling: did_v1 → V_zeta
+
+> This is the **generalized** file-handling specification for the
+> did_v1 → V_zeta migration. Per-document-type conversion docs should
+> link here for anything that follows these generic rules, and only
+> document type-specific behavior locally.
+
+This file is a **skeleton**. Sections marked `TODO` need domain input
+before the migration engine can be implemented.
+
+## Scope
+
+What counts as a "file" in this document? In DID terminology, any binary
+blob, external path, or hash-addressed content that a document instance
+references (rather than embeds inline). Examples to consider:
+
+- TODO: enumerate the file-reference fields that appear across did_v1
+  document types (e.g., raw recording files, processed outputs, image
+  stacks, zarr archives).
+
+## did_v1 file-reference shape
+
+TODO: describe how did_v1 documents reference files today — field names,
+path formats (absolute? relative? hash-addressed?), whether integrity is
+verified, and what container/database layout assumptions exist.
+
+## V_zeta file-reference shape
+
+TODO: describe the target file-reference shape under V_zeta. Anchor
+choices in `V_zeta_SPEC.md` once finalized.
+
+## Migration rules
+
+For each migration scenario, specify the rule. Stubs follow.
+
+### Path rewriting
+
+TODO: when did_v1 paths are absolute and the V_zeta layout requires
+relative or hash-addressed paths, how are old paths translated? What
+happens if the original file is no longer on disk?
+
+### Integrity verification
+
+TODO: does V_zeta require a hash on file references? If so, how is it
+computed during migration, and what happens on hash mismatch (fail,
+warn, or annotate)?
+
+### Orphan files
+
+TODO: files that are on disk but no document references them, and
+references that point at files no longer on disk. Specify the policy
+for each.
+
+### Large file handling
+
+TODO: any size-based branching (e.g., inline vs. external) at the
+V_zeta layer.
+
+### Container/database boundaries
+
+TODO: when a document is migrated across databases (or out of one and
+into a fresh V_zeta container), how are file references rewritten?
+
+## Open questions
+
+- Are file references stored on the document instance itself, or on a
+  side index?
+- Should the migration engine ever copy file content, or only update
+  references?
+- What is the policy for files referenced by both a did_v1 document and
+  a V_zeta document during a transitional period?

schemas/V_zeta/conversions/from_did_v1/_index.md

@@ -0,0 +1,75 @@
+# did_v1 → V_zeta conversion index
+
+This file enumerates every V_zeta document type that needs a conversion
+doc from `did_v1`, and tracks its status. Update this index whenever a
+new conversion doc is added or its status changes.
+
+The corresponding template is [`_TEMPLATE.md`](_TEMPLATE.md). The shared
+file-handling rules are in [`_files.md`](_files.md). Cross-cutting renames
+that apply to **every** did_v1 → V_zeta migration (underscore-prefix
+removal, snake_case, ontology-annotation reshape, superclass-reference
+reshape, class-scoped property blocks, maturity-level enum) are in
+[`_universal_renames.md`](_universal_renames.md). Per-class markdowns
+assume those renames have been applied and document only the per-class
+field-level changes on top.
+
+## Status legend
+
+- **none** — no conversion doc exists yet
+- **drafted** — markdown exists, awaiting domain review
+- **reviewed** — domain-reviewed, awaiting implementation
+- **applied-in-tooling** — implemented in the migration engine in
+  `DID-matlab`, but not yet locked
+- **frozen** — implemented, tested against real datasets, locked for
+  V_zeta
+- **no-conversion-needed** — explicitly marked as having no did_v1
+  predecessor
+
+## Conversions
+
+| V_zeta class_name | did_v1 source | Status | Doc |
+|---|---|---|---|
+| `contrast_tuning` | NDIcalc-vis-matlab `vision/contrast_tuning` | drafted | [contrast_tuning.md](contrast_tuning.md) |
+| `contrast_tuning_calc` | NDIcalc-vis-matlab `calc/contrasttuning_calc` (renamed) | drafted | [contrast_tuning_calc.md](contrast_tuning_calc.md) |
+| `contrast_sensitivity_calc` | NDIcalc-vis-matlab `calc/contrastsensitivity_calc` (renamed) | drafted | [contrast_sensitivity_calc.md](contrast_sensitivity_calc.md) |
+| `spatial_frequency_tuning` | NDIcalc-vis-matlab `vision/spatial_frequency_tuning` | drafted | [spatial_frequency_tuning.md](spatial_frequency_tuning.md) |
+| `spatial_frequency_tuning_calc` | NDIcalc-vis-matlab `calc/spatial_frequency_tuning_calc` | drafted | [spatial_frequency_tuning_calc.md](spatial_frequency_tuning_calc.md) |
+| `temporal_frequency_tuning` | NDIcalc-vis-matlab `vision/temporal_frequency_tuning` | drafted | [temporal_frequency_tuning.md](temporal_frequency_tuning.md) |
+| `temporal_frequency_tuning_calc` | NDIcalc-vis-matlab `calc/temporal_frequency_tuning_calc` | drafted | [temporal_frequency_tuning_calc.md](temporal_frequency_tuning_calc.md) |
+| `speed_tuning` | NDIcalc-vis-matlab `vision/speed_tuning` | drafted | [speed_tuning.md](speed_tuning.md) |
+| `speed_tuning_calc` | NDIcalc-vis-matlab `calc/speedtuning_calc` (renamed) | drafted | [speed_tuning_calc.md](speed_tuning_calc.md) |
+| `orientation_direction_tuning` | NDIcalc-vis-matlab `stimulus/vision/oridir/orientation_direction_tuning` | drafted | [orientation_direction_tuning.md](orientation_direction_tuning.md) |
+| `oridirtuning_calc` | NDIcalc-vis-matlab `calc/oridirtuning_calc` | drafted | [oridirtuning_calc.md](oridirtuning_calc.md) |
+| `reverse_correlation` | NDIcalc-vis-matlab `neuro/reverse_correlation` | drafted | [reverse_correlation.md](reverse_correlation.md) |
+| `hartley_reverse_correlation` | NDIcalc-vis-matlab `neuro/hartley_reverse_correlation` | drafted | [hartley_reverse_correlation.md](hartley_reverse_correlation.md) |
+| `hartley_calc` | NDIcalc-vis-matlab `calc/hartley_calc` | drafted | [hartley_calc.md](hartley_calc.md) |
+| `probe_location` | legacy NDI/DID `probe_location` (V_alpha shape) | drafted | [probe_location.md](probe_location.md) |
+| `treatment` → manipulation tiers (Brainstorm I **split**) | legacy `treatment` → `injection`/`bath`/`temperature_manipulation` (typed) / `generic_manipulation` (procedures & regimes) (+ out-of-tier) | drafted | [treatment.md](treatment.md) |
+| `ontology_table_row` → observation tiers (Brainstorm I **split**, 1→N) | legacy `ontology_table_row` → shape-typed scalar/categorical observation classes (+ out-of-tier) | drafted | [ontology_table_row.md](ontology_table_row.md) |
+| `subject_group` → `subject` (`is_group`) (Brainstorm I **fold**) | legacy `subject_group` → `subject` flagged `is_group` (+ `group_assignment` in NDI layer) | drafted | [subject_group.md](subject_group.md) |
+| `treatment_drug` → `injection` (`kind: drug`) (Brainstorm I **fold**) | legacy `treatment_drug` → `injection` (mixture from `mixture_table`) | drafted | [treatment_drug.md](treatment_drug.md) |
+| `virus_injection` → `injection` (`kind: virus`) (Brainstorm I **fold**) | legacy `virus_injection` → `injection` (virus+dilution in mixture) | drafted | [virus_injection.md](virus_injection.md) |
+| `treatment_transfer` → `biological_transfer` (Brainstorm I **fold**) | legacy `treatment_transfer` → `biological_transfer` (recipient→subject, donor carried) | drafted | [treatment_transfer.md](treatment_transfer.md) |
+| `ontology_image` | legacy NDI/DID `ontologyImage` (V_alpha shape) | drafted | [ontology_image.md](ontology_image.md) |
+| `ontology_label` | legacy NDI/DID `ontologyLabel` (V_alpha shape) | drafted | [ontology_label.md](ontology_label.md) |
+
+## Notes
+
+- **Not migrated:** `stimloopsplitter_calc` (deprecated per domain owner
+  decision; not added to V_zeta).
+- **Already in V_zeta from earlier set versions** (no `did_v1` conversion
+  added in this PR): `tuningcurve_calc`, `stimulus_tuningcurve`, `ngrid`.
+  These have no NDIcalc-vis-matlab v1 predecessor in `ndi_common/`; if any
+  need a separate `did_v1` source resurrected later, add their conversions
+  then.
+
+## Conventions
+
+- One conversion markdown per V_zeta document type. If a V_zeta class
+  has multiple did_v1 sources, document the merge in a single file
+  rather than splitting.
+- If a V_zeta class is genuinely new (no did_v1 ancestor), create
+  `<class_name>_no_conversion_needed.md` with a one-line reason and add
+  the row with status `no-conversion-needed`.
+- File-handling behavior that follows the generic rules in `_files.md`
+  should be linked, not restated.