R3 source and migration integration

Status: source/persistence integration implemented and verified, 2026-09-06. Worktree: D:/CodexBuilds/Capella2-semantic-review, branch codex/semantic-review, base ab661f2. This plan owns only source/persistence integration; it does not claim overall R3 acceptance. The adapter uses the published core facet types and typed historical slot visitor.

Ownership and fixed boundary

The source worker owns persistence.rs, a new strict schema4 adapter, language.rs and its source submodules, source_project/source_files, and focused source/migration tests. Core owns model.rs, lib.rs, the semantic review module, transition preparation, historical-reference remapping and semantic admission. Desktop/server integration belongs to the lead. Cargo target ownership is coordinated before any invocation.

The stable outer shape is TraceBaseline { oa, sa, semantic: Option<SemanticBaseline> }: existing prose pairs remain exact; absent semantic review means Unreviewed. SemanticBaseline contains closed, self-tagged typed reviewed pairs. Whole typed records exist only as review candidates, never as persisted carriers, masks or checkpoints. TraceBaseline and Trace become PartialEq because reviewed data includes finite real values.

Explicit compatibility

Current JSON and authored source become schema/source5. Preserve real schema4/source4 fixtures before updating any tests intended to describe current syntax. Existing V1/V2 goldens and real V3 fixtures remain unchanged.
Add frozen Trace4/TraceBaseline4 with denied unknown fields and exact old prose values. Reuse unchanged typed elements, relations, diagrams and artifacts in an explicit Project4 envelope with duplicate-map rejection. Do not copy the full metamodel. A schema4 input containing a semantic baseline must reject instead of silently accepting a future payload.
Adapt frozen schema3 trace decoding to use the same old trace shape; schema2 already has a frozen model. Ensure V1/V2/V3 paths enter the explicit review upgrade before returning current5, preserving their existing data/port migration report details. The original reported from_schema remains unchanged and to_schema is 5.
A migrated trace keeps IDs, aliases, rationale, endpoints and exact prose baselines; it receives semantic=None. Do not construct reviewed semantic observations from today's model. No file write, hosted revision advance or history entry occurs during decode.
Source3/source4 bundle compilation passes through resolve_declarations, bypassing parse_document; apply the same strict legacy trace decoding there. Upgrade authored4 with a version-token edit only, plus UUID stabilization when actually missing. Authored3 retains its existing targeted data edits and finishes at source5. Preserve includes, lexical ownership, comments, line endings and file layout; no canonical-bundle fallback.

Typed historical source context

Add an explicit uuid "..." AST atom. It is permitted only in reference slots of a typed semantic facet under a trace baseline. Ordinary live references continue to require @alias; trace endpoints, parents, ports, payload paths and other live fields do not gain a quoted-UUID escape hatch. Historical references never require a current alias or live object.

Coordinate a closed source-shape/reference-slot catalog with the core facet types. oa, sa and Value wrappers cannot use the existing leaf-name reference heuristic: the same spelling can wrap a bound, enum, string, optional UUID, keyed row or order vector. Reject a historical UUID atom in text/numeric/enum slots and reject @alias or a plain quoted UUID in historical reference slots. Typed serde admission remains responsible for exact payload shape; the source adapter preserves the token category distinction. No public generic SemanticPath/SemanticValue tree or escaped JSON blob is introduced.

Canonical output prints historical UUID atoms even when the object currently exists, making the historical meaning stable across deletion. Live aliases remain canonical for live references. Source analysis/indexing treats both-token UUID atoms as one value span. The targeted updater compares keyed facet rows by their closed selector identity, preserves comments on retained rows, and updates all historical UUID tokens when core reidentifies an identity. A UUID-looking ordinary text annotation must stay ordinary text.

Verification required for handoff

Strict schema4 JSON and source4 migration preserves existing trace prose, IDs, aliases, ports and unrelated records, with semantic=None and no fabricated acknowledgement. Unknown schema5 semantic data under a version4 header rejects. Duplicate maps/fields remain rejected.
Current5 canonical source and JSON roundtrip a representative typed review baseline with optional/unbounded values, NotApplicable constructor branches, ordered membership, complete (path, field) annotation keys, bindings and deleted historical UUIDs. Historical UUID syntax is rejected in live fields, and live aliases/plain strings are rejected in historical ID slots.
Apply and format a real reviewed change, retain an intentionally different target value, delete a previously referenced object, then roundtrip and reidentify without losing history. Confirm core deletion does not prune historical values and real reidentification changes the exact corresponding tokens.
A multi-file authored4 bundle with nested declarations and commented trace fields upgrades via targeted edits; a later facet-row update/reidentify preserves includes, comments and unrelated bytes. Exercise disk save/reload through existing source-file behavior where it adds evidence beyond the pure bundle test.
Exercise the actual compile_bundle path as well as single-document parse. Preserve original V1/V2/V3 compatibility coverage and current source writer/identity/nesting regressions. Report test names and actual results only after the coordinated Cargo turn.

Recorded evidence

The completed regression run passed 127 tests: 20 library tests, 16 language, 8 port migration, 3 authored4 port source, 5 R3 migration, 7 R3 source, 7 R6 migration, 5 R6 source, 8 source files, 3 identity updates, 12 nested updates, and 33 source project tests. These cover explicit original1/2/3 and frozen4 upgrade, strict older-header rejection of semantic data, unchanged reviewed prose, authored4 include/nesting/comment preservation, typed semantic source/JSON roundtrips with absent historical IDs, token context admission, row comment ownership through reordering and reidentification, and deletion retaining historical review. cargo check -p oa-core --lib also passed with the new dispatch and source adapter.

The R3 source tests also pass actual included-review disk load, targeted edit, save and reopen, plus a real prepared semantic review transaction that takes the source name while retaining the intentionally different target unit and original prose baseline. The source regression suite's prior future-header rejection was updated from 5 to 6, and current-syntax test templates now use 5. The real source4 typed-port tests intentionally remain authored4 and assert their explicit migration report; frozen V1/V2/V3 inputs remain unchanged. Strict Clippy passed for the library and all eleven selected integration suites with -D warnings, using the shared vendored config and dedicated target. Later planner changes remain the core worker's responsibility to recheck against r3_source.

7.4 KiB Raw Permalink Blame History