[V_delta] Rename depends_on(k).value → document_id#52
Merged
Conversation
Closes #49. V_delta's earlier draft used `value` for the cross-document reference key inside depends_on entries. Surfaced in NDI-matlab #801 (compat layer audit blocking the gate flip): `value` is generic but uninformative -- in practice every entry's value always is a did_uid referring to another document. `document_id` names what the field is, with the `document_` prefix disambiguating against any future id-shaped fields V_delta might add. Resulting V_delta depends_on entry shape: { "name": "<role>", "document_id": "<did_uid>" } Changes: - schemas/V_delta/stable/ndi_reserved_keys.json: the document_instance_keys entry renames "value" to "document_id" and rewords the description to call out the field's did_uid nature and the rename history. - schemas/V_delta/conversions/from_did_v1/_universal_renames.md: new section #9 documenting the `id -> document_id` rename (and `version` drop) as part of the cross-cutting universal-rename pass. The previous "Planned: schema_version" section renumbered from #9 to #10. - schemas/V_delta_notes.md: open-follow-ups "Schema content" list now records the rename and points at the registry entry. - schemas/V_delta/conversions/from_did_v1/{ontology_label, probe_location, ontology_image, treatment}.md: worked examples updated to use "document_id" in their depends_on blocks (both the V_alpha-after-universal-renames "before" and the V_delta "after" -- both show post-universal-renames depends_on shape per the _index.md convention). - schemas/V_delta/conversions/from_did_v1/{contrast_tuning, orientation_direction_tuning,probe_location}.md: descriptive prose ("value carried on document instances", "the value travels with each document") rewritten to use "document_id". Cross-repo follow-ons: - vh-lab/did-matlab: did2.convert.universalRenames.renameDependsOnEntries needs to produce `document_id` (currently produces `value`) and accept the earlier `value` key as a synonym during the transition. did2.query / compileQuery / validate/references and the corpus tests follow. - waltham-data-science/ndi-cloud-node: V_delta-aware query/index code learns the new path. - vh-lab/ndi-matlab: ndi.compat.fieldAliases.dependsOn vKey becomes `document_id` (currently `value`); augmentRead / reconcileWrite / translateQueryPaths / dependsOnAppend follow. This is the schema decision; the consumer changes go on separate PRs in their respective repos and reference this one.
stevevanhooser
pushed a commit
to VH-Lab/DID-matlab
that referenced
this pull request
May 21, 2026
Closes #N/A (companion to Waltham-Data-Science/DID-schema#52, which made the V_delta-side rename and merged to did-schema main). V_delta's canonical depends_on entry shape is now {name, document_id}. did-schema#52 settled the rename rationale (`value` was generic but uninformative; every entry's value is always a did_uid referring to another document). This PR carries the rename through every did2 surface: the universal-rename pass, the on-disk SQL sidecar table, the query/validator/cache code, and the test corpora. Compat strategy: each on-the-wire reader/parser tolerates the earlier draft key `value` and the raw v1 key `id` as synonyms for `document_id`, so a body at any stage of the migration pipeline still finds its references. The writer always produces `document_id`. Changes: - src/did/+did2/+convert/universalRenames.m::renameDependsOnEntries rewritten to accept document_id / value / id on input (precedence document_id > value > id), produces document_id, drops legacy keys. - src/did/+did2/+database/sqlitedb.m: * createSchema: depends_on table now declares `document_id` column (was `value`) and the index is renamed accordingly. * INSERT INTO depends_on writes the `document_id` column. * dependsOnEntries iterator (the sidecar-row builder used at write time) reads document_id / value / id synonyms. * assertSchema gained migrateDependsOnValueToDocumentId: one-shot introspect-and-ALTER on existing databases that still carry the old `value` column. Wrapped in BEGIN/COMMIT so a torn migration rolls back; idempotent on already-migrated DBs (early-returns if document_id is already present). - src/did/+did2/+database/compileQuery.m: compileDependsOn now emits `d.document_id = ?` predicates against the renamed sidecar column. Top-of-file SQL signature comment updated. - src/did/+did2/query.m: opDependsOn (in-memory evaluator) reads document_id / value / id synonyms. - src/did/+did2/+validate/references.m: documentation, orphan report field `edge_value` -> `edge_document_id`, dependsOnEntries iterator reads synonyms. - src/did/+did2/+schema/cache.m::buildBlankDocument: the empty depends_on struct array now carries field `document_id`. - Tests: testConvertV1ToV2 (universal-rename behaviour), testFromV1Database, testMigrators (calcCommon depends_on drop), testQuery (depends_on op), testReaders, testSchemaCache (blank doc), testSqliteDb (search by depends_on), testValidateReferences (orphan field + setDependsOn helper) all updated. Names like testUniversalRenamesPromotesDependsOnIdToDocumentId reflect the new canonical name. Existing sqlite databases on disk: on first open after this PR lands, the depends_on table's value column is renamed in place via ALTER TABLE RENAME COLUMN (SQLite >= 3.25, satisfied by mksqlite's bundled SQLite). The index is dropped + recreated so queries keep using it. No JSON re-write needed since the doc bodies in the documents.body column are kept in sync by did2.convert.v1_to_v2 on read normalization.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #49.
Summary
V_delta's earlier draft used
valuefor the cross-document reference key insidedepends_onentries. Surfaced in NDI-matlab #801 (the compat-layer audit blocking the gate flip):valueis generic but uninformative — in practice every entry's value always is adid_uidreferring to another document.document_idnames what the field is, with thedocument_prefix disambiguating against any future id-shaped fields V_delta might add.Resulting V_delta
depends_onentry shape:{ "name": "<role>", "document_id": "<did_uid>" }What changed
schemas/V_delta/stable/ndi_reserved_keys.json—document_instance_keysentry renamesvalue→document_idwith a description that names the did_uid nature and the rename history.schemas/V_delta/conversions/from_did_v1/_universal_renames.md— new section Remove legacy V_alpha document types and add V_alpha notes #9 documenting theid → document_idrename (andversiondrop) as part of the cross-cutting universal-rename pass. The previous "Planned: schema_version" section renumbered Remove legacy V_alpha document types and add V_alpha notes #9 → Add V_beta schema directory with snake_case normalized schemas #10.schemas/V_delta_notes.md— open-follow-ups "Schema content" list now records the rename and points at the registry entry.conversions/from_did_v1/{ontology_label,probe_location,ontology_image,treatment}.md— worked-example JSON blocks updated to use"document_id".conversions/from_did_v1/{contrast_tuning,orientation_direction_tuning,probe_location}.md— descriptive prose rewritten ("value carried on document instances" → "document_id carried on document instances", etc.).What did NOT change
id,session_id,name,datestampfields onbase(unchanged — those are on the document itself, not on cross-document references).depends_ondeclarations name dependency roles, not entry keys, so no per-class schema changes needed).Cross-repo follow-ons (separate PRs, will reference this one)
vh-lab/did-matlab—did2.convert.universalRenames.renameDependsOnEntriesneeds to producedocument_id(currently producesvalue) and accept the earliervaluekey as a synonym during the transition.did2.query/compileQuery/validate/referencesand the corpus tests follow.waltham-data-science/ndi-cloud-node— V_delta-aware query/index code learns the new path.vh-lab/ndi-matlab—ndi.compat.fieldAliases.dependsOnvKey becomesdocument_id(currentlyvalue);augmentRead/reconcileWrite/translateQueryPaths/dependsOnAppendfollow. This unblocks NDI-matlab #801.Test plan
JSON syntax validated locally. Markdown is descriptive; CI will catch any link-rot. The actual roundtrip-against-corpora tests live in
did-matlab'stests/+did2/+unittest/testCorpus*.m; the companion did-matlab PR exercises them with the new key.Coordination
Merge order: this PR first, then the cross-repo PRs once they're up.
did-matlabtests use this repo'smainbranch as schema source (perdid-matlab/.github/workflows/test-code.yml), so the did-matlab PR's CI will fail until this lands. Plan to merge here, then quickly land the did-matlab consumer change.Generated by Claude Code