Add time_reference and timeref_epochset composite types to V_gamma

[stevevanhooser]

Summary

Adds two new V_gamma named composite types so any field can carry a time value expressed relative to a chosen origin — the existing schemas only supported per-epoch acquisition-clock offsets via the ad-hoc timeref_struct* shape on valid_interval.

• timeref_epochset — the four-tuple that names an acquisition-clock origin (epochsetname, classname, epoch, clocktype).
• time_reference — a (origin, offset_seconds) pair where origin is selected by referent_kind:
  • document — anchors on a depended-on document with anchor_point (start or end); the actual did_uid lives in the containing schema's _depends_on array, so cascading delete is inherited rather than re-implemented.
  • acquisition_clock — nests a timeref_epochset.
  • utc — carries an ISO 8601 utc_timestamp; no offset applies.
  • ontology_stage — nests an ontology_term (e.g. mmusdv:0000037); optional offset_seconds within the stage.
  • unknown — explicit placeholder for wild-caught DOB, unrecorded treatment times, etc.

This is also the first V_gamma composite that nests other composites (epochset → timeref_epochset; stage → ontology_term); the validator looks up nested shapes from the spec by type name.

Schema changes

File	Change	_class_version
schemas/V_gamma/did_schema_meta.json	Add timeref_epochset and time_reference to the type enum	n/a (meta-schema)
schemas/V_gamma/valid_interval.json	Replace timeref_structt0, t0, timeref_structt1, t1 with t0_reference, t1_reference (time_reference); add t0_referent_id, t1_referent_id depends_on entries	1.0.0 → 2.0.0
schemas/V_gamma/treatment.json	Add optional administered_at + administered_at_referent_id	2.0.0 → 2.1.0
schemas/V_gamma/virus_injection.json	Add optional injected_at + injected_at_referent_id	1.0.0 → 1.1.0
schemas/V_gamma/session_occurrence.json	New tag-style companion doc (depends on session, carries optional started_at / ended_at)	1.0.0
schemas/V_gamma/subject_birth_event.json	New tag-style companion doc (depends on subject, carries required occurred_at)	1.0.0
schemas/V_gamma/CURIE_lookups_meta.json	Register mmusdv and hsapdv developmental-stage prefixes	_format_version 1.0.0 → 1.1.0

session.json and subject.json are intentionally not modified — they remain identifier-only tag documents that other documents can _depends_on before time / DOB are known. Time-of-occurrence and birth events live on the new companion docs.

Spec / docs

• schemas/V_gamma_SPEC.md: add timeref_epochset and time_reference to the Valid Types table, semantics-of-flags table, type-enum allow-list, and Phase-1 validation list; add full sub-section under Named Composite Types covering required-by-kind table, depends_on_name cross-field invariant, _constraints keys, and example values for every kind; relax the "sub-field types are primitive" rule to permit nested composites.
• schemas/V_gamma_notes.md: changelog entries for the new types, the valid_interval 2.0.0 migration, the MINOR bumps on treatment / virus_injection, the two new tag-style docs, and the CURIE registry bump.

Test plan

• python3 -m pytest — all 96 tests pass (parametrized across V_beta and V_gamma)
• tests/test_schemas.py VALID_TYPES_BY_VERSION["V_gamma"] updated to include timeref_epochset and time_reference, so test_all_field_types_are_valid accepts the new types
• All ten touched JSON files parse as valid JSON
• All schema files (including the two new ones) pass meta-validation against the updated did_schema_meta.json

https://claude.ai/code/session_017KhpqmYndDHqzA9UZcUk1Q

---

Generated by Claude Code