Integrate semantic review core source API and scalar desktop workflow

harness/DECISIONS.md

@@ -14,6 +14,21 @@
 - **Evidence governs completion.** Original Capella was operated in an isolated example and its useful nesting/navigation/transition patterns informed the UI. Independent reviews, real native workflows and automated invariants complement each other. Platform and feature boundaries remain explicit in validation/scope documents.
 # First-release decisions (supersede narrower V2 exclusions below)
 
+- R3 production adopts closed typed per-facet reviews (C), selected after the
+  11-case proof in b2ab2b1 and independent adversarial review. Each self-tagged
+  fact stores independently reviewed OA/SA typed values; absent facts remain
+  Unreviewed, and NotApplicable distinguishes an absent constructor branch from
+  an absent optional value. This supersedes recursive SemanticValue/string paths
+  and typed-body carrier/mask/order-shadow baselines. Extra finite adapter code
+  is accepted for fewer persisted-state invariants, not as a generic metamodel.
+  Atomic keyed rows, target-only preserving member deltas, independent order,
+  exact constructor groups, explicit mapping resets/canonical target agreement
+  and actual prepared-impact review remain required. Keep the existing Command
+  and transition planner boundaries. Artifact reviews attach to semantic traces.
+  Schema/source5 is explicit, with unchanged data4 compatibility. The authoritative
+  implementation/ownership/evidence contract is release-semantic-review-implementation.md;
+  production implementation and release acceptance are still pending.
+
 - OA/SA semantic scope follows `release-semantics-audit.md` R1–R6 and actual Capella workflow evidence. Later Arcadia layers remain future work; missing OA/SA reuse, topology, state/data contracts and semantic transition review do not become release limitations.
 - Preserve one typed Rust core and atomic validated model commands. Mission/capability links and process topology are independent of containment and diagram placement. Work/chain reuse uses stable reference occurrences rather than copied semantic objects; sequence guards belong to contextual links rather than global exchanges.
 - Desktop lint uses one background parser plus the latest queued source version. Accepted model checks are cached separately from draft diagnostics. Stale results cannot enter a different document or overwrite newer edits. The REST service prepares bounded candidates outside its global store lock and rechecks ETags during commit.
@@ -69,3 +84,35 @@ the leak and native Windows/Linux tests verified the correction in316dc55.
   paths were proven ambiguous in native recursive/reused data. Browsing does not
   change the selected field or expression; choosing a field remains an explicit
   draft edit through the ordinary validated command. No persistent browser schema.
+## Semantic review proposals and historical admission (2026-09-06)
+
+R3 stores closed, typed, independently reviewed OA/SA facet pairs. Constructor
+facts store discriminators only; explicit group decisions enumerate and retire
+their exact branch facts. No persisted recursive value tree, own-record carrier,
+review mask or order shadow is introduced. The complete contract is
+release-semantic-review-implementation.md.
+
+Derive every source proposal from the same immutable initial project. Reset old
+mapping selectors before deriving scopes; compare all desired canonical target
+slots, including constructor removals, before one materialization. Audit selected
+values against both that result and the ordinarily prepared project. This prevents
+sequential last-write wins, even when one source introduces a member another
+constructor removes. Preserve target-only members during same-target-constructor
+reconciliation. Artifact attachment and explicit owner changes share the actual
+artifact's owner slot; child/incident operations similarly share actual parent or
+endpoint slots. Exact prepared cleanup impacts require explicit acknowledgement
+and may not contradict a selected Keep/Take.
+
+Artifact metadata is observed by identified record after authorization against
+its initial attachment. An owner move therefore retains the actual resulting
+Owner/Name facts, including target-only links; Presence remains owner-relative.
+New metadata decisions require the current attached owner trace. Historical paired
+selectors survive disappearance of one side and suppress redundant one-sided
+projections. A new pairing cannot suppress prior one-sided history without reset.
+
+Current resolution applicability and historical baseline admission are separate.
+New decisions require a compatible current family and an applicable side; historical
+typed facts can outlive former constructors/families and deleted references. Their
+typed reference visitor supports explicit reidentification but does not add live
+deletion dependencies. Derived linked-definition drift remains bounded and exposes
+missing review coverage instead of copying a shared definition into every baseline.

harness/release-constructor-acknowledgement.md

@@ -0,0 +1,59 @@
+# First review of equal constructor discriminators
+
+The review planner previously rejected every unchanged-constructor decision even
+when that discriminator had never been reviewed. The catalog correctly retained
+it as Unreviewed. An isolated executable against core346fb24 reproduced an ordinary
+DataType review that acknowledged all seven other facets but could not complete
+its own baseline. The same result occurred with no outer baseline, semantic=None,
+an empty semantic baseline, and a schema4 trace migrated to schema5. KeepTarget,
+TakeSource and an unchanged Candidate all returned "No constructor switch".
+Explicitly inserting only the valid discriminator fact made own drift Unchanged.
+This was a material completion defect for existing and migrated review workflows,
+without evidence of model corruption. Direct source editing of a valid baseline
+or an actual constructor switch were possible workarounds, not normal initial
+review behavior.
+
+The agreed fix preserves the public request and stored schema. After explicit
+resets, a constructor with no historical fact has scalar scope if both current
+sides are applicable and equal and the proposed target discriminator is unchanged.
+KeepTarget, equal TakeSource and an unchanged-discriminator Candidate then record
+only that discriminator. They do not copy a constructor payload, expand descendants,
+retire historical branch facts or change model records.
+
+Resolution overlap checks use this effective scope, so separately chosen leaves
+can accompany the first discriminator acknowledgement. Its exact canonical target
+slot enters the existing agreement map and both final-value audits. A different
+source may independently change a descendant, but cannot contradict the retained
+discriminator with a constructor switch. Final Candidate record equality still
+rejects changes to unselected fields.
+
+Real proposals and historical discriminator changes retain the existing grouped
+scope. Repeated requests after the first acknowledgement or a completed switch
+still reject when no switch remains. Repeated Keep on a reviewed unequal pair
+cannot hide new bound/default drift. One-sided applicability stays on the group
+path; a discriminator inapplicable on both sides cannot be acknowledged, even
+after resetting its old fact. This avoids automatic history fabrication and does
+not suppress missing facts from the drift rollup.
+
+Normative source5 text and its HTML copy now distinguish the first scalar
+acknowledgement from grouped constructor decisions. No source syntax, persisted
+baseline type, API request shape, migration rule or desktop code changed here.
+
+Verification uses D:/CodexBuilds/Capella2-semantic-target exclusively. The eight
+new regressions cover all constructor families (valid Legacy OA/SA ports), both
+directions and all decisions; missing/empty/migrated history; simultaneous complete
+review; untouched and later changed descendants; reset; Candidate scope; canonical
+agreement in either source order; one-sided/disappeared MessageKind; and repeated
+unequal Keep/completed-switch rejection. The focused run passed all eight new
+tests and all 28 existing r3_semantic tests. Final verification passed all 353 core
+tests (33 test summaries, including doc tests) and strict Clippy for every core
+target:
+
+```
+cargo test -p oa-core --locked --offline --target-dir D:/CodexBuilds/Capella2-semantic-target
+cargo clippy -p oa-core --all-targets --locked --offline --target-dir D:/CodexBuilds/Capella2-semantic-target -- -D warnings
+```
+
+Logs are in C:/Users/sorok/AppData/Local/Temp/capella2-constructor-ack-review/
+as full-core.log and strict-clippy.log. Native/API release acceptance is outside
+this bounded fix.

harness/release-semantic-gui.md

@@ -0,0 +1,82 @@
+# Semantic desktop review — milestones 1 and 2
+
+Status: milestones 1–2 implemented and desktop tests/build verified; not full GUI
+parity, native acceptance or release acceptance.
+Base: `d130013`. Dedicated build target:
+`D:/CodexBuilds/Capella2-semantic-desktop-target`. Native verification is root-owned.
+
+## Scope and decisions
+
+- Add an explicit Review semantics action for existing traced counterparts, with
+  canonical Operational/System comparisons in either application direction.
+  Preserve the existing counterpart creation and prose workflow with clear labels.
+- Review one explicitly selected trace per dialog. Display grouped current and
+  historical facts, own/linked drift and incomplete review. Names never infer
+  reference correspondence; provide explicit reference and trace choices.
+- Support every applicable scalar leaf through Keep, Take and typed final-value
+  forms. Candidate records contain the complete combined selected result. Identity,
+  alias and layer are protected. The closed core remains the validation boundary.
+- State.Kind is a single structural scalar. Other constructor switches, keyed
+  membership/order/annotation/binding/attachment decisions and pairing resets belong
+  to milestone 3; show them read-only with an honest explanation.
+- Core `6bb2583` permits first equal constructor acknowledgment without descendant
+  expansion. The GUI exposes **Acknowledge equal kind only** when applicable;
+  previously reviewed constructors remain governed by the core's switch rules.
+- Show exact additional prepared impacts and require explicit acceptance. Apply
+  validates the stored semantic plan and executes its exact command batch through
+  Document, preserving source, baselines and one-step undo/redo. Do not place or
+  reveal diagram objects by mutating the model after preview.
+- Retain typed drafts and review choices on invalid input, planning conflicts,
+  stale plans and failed source writeback. Display actionable errors in the dialog.
+
+## Milestones and acceptance
+
+1. Grouped read-only review, named trace/reference choices, exact comparisons and
+   honest traceability rollups; compact layout usable at 1100 by 700.
+2. Scalar decisions and typed candidates; immutable initial observations; combined
+   final records; exact impact acceptance; atomic document/source commit. Focused
+   App event/source/history tests, strict Clippy and a dedicated desktop build.
+3. Constructor closure, keyed and ordered facts, reset, complete artifact lifecycle,
+   multi-source review and remaining source/REST parity cases. Still outstanding.
+4. Root-owned native review, cross-surface fixtures, package/release acceptance.
+
+## Verification
+
+Verified against core `6bb2583`, using only the dedicated desktop target:
+
+```powershell
+$env:CARGO_TARGET_DIR='D:/CodexBuilds/Capella2-semantic-desktop-target'
+cargo test --locked -p oa-desktop --quiet
+cargo clippy --locked -p oa-desktop --all-targets -- -D warnings
+cargo build --locked -p oa-desktop
+```
+
+All **272 desktop tests passed**, including **11 new semantic review tests**.
+Strict Clippy and the desktop build passed. The existing migration test's header
+assertion now follows `SCHEMA_VERSION` instead of expecting schema 4.
+
+Coverage includes both-direction Keep/Take/Candidate with exact comments and
+source/model/baseline undo/redo; independent selected trace semantic histories;
+invalid numeric and protected-property edits; stale-plan and source-writeback
+rejection; typed reference mapping mixed with candidates; honest partial rollups;
+equal-kind acknowledgment without implicit descendants; State.Kind candidates;
+relationship role/bound candidates with retained identity/endpoints; and exact
+inherited-annotation cleanup approval, cleared when decisions change. Unselected
+invalid scalar drafts remain retained without contaminating another candidate.
+
+Built executable:
+`D:/CodexBuilds/Capella2-semantic-desktop-target/debug/arcadia-studio.exe`.
+The build target is idle. No native application was launched by this task.
+
+## Remaining work
+
+Milestone 3 must add explicit constructor closure/replacement, keyed and ordered
+decisions, historical pairing reset, complete artifact lifecycle and multi-source
+review. These facts are currently inspectable, with unsupported writes visibly
+identified. The reference table supplies explicit mappings for scalar reference
+Take; it does not claim to complete a reset or establish keyed acknowledgments.
+
+Fresh independent scalar GUI review and root-owned native verification are still
+required before merging this milestone into release acceptance. In particular,
+validate the 1100×700 layout, keyboard/focus continuity, long historical values,
+reference selection, source reopening and prepared-impact inspection in the app.

harness/release-semantic-review-implementation.md

@@ -0,0 +1,267 @@
+# R3 semantic review implementation freeze — schema/source 5
+
+Status: production implementation authorized; not accepted or complete. Isolated
+worktree `D:/CodexBuilds/Capella2-semantic-review`, branch `codex/semantic-review`,
+base `ab661f2d332f540673ee0e2003b454c1765332bc`; dedicated target
+`D:/CodexBuilds/Capella2-semantic-target`. R6 native work remains root-owned in DATA.
+
+## Decision and evidence
+
+Adopt C: a closed, typed, self-tagged review value per semantic facet. The
+throwaway C proof is `b2ab2b1feb9b0ada03cd9d0974749bd7fd28c7f8` in the separate
+transition-probe worktree. Its 11 passing tests comprise three B1 comparison
+cases and eight C cases, including an independent adversarial review's concrete
+counterexamples. Additional type/adapter code is accepted for fewer persisted
+state invariants; this is not a claim that C uses fewer lines.
+
+This supersedes the recursive `SemanticValue`/string-path recommendation in
+release-transition-contract.md and the interim typed-carrier/mask/order-shadow
+recommendation. Keep its engineering requirements: partial deliberate review,
+explicit mapping, target-only preservation, honest unreviewed state, source/JSON
+parity, and one stale-checked validated transaction. No generic metamodel, graph
+synchronization service, runtime value tree, or second mutation engine is added.
+
+Compiled core catalog: `semantic/types.rs` contains 84 scalar selectors across 13
+families, nine reference collections, two ordered collections, and the closed
+Literal/Annotation/Binding/Child/Incident/Artifact facts. The catalog coverage test
+enumerates every current element payload, constructor branch and relation kind;
+an unrepresented payload field fails that gate. Serialization paths used by the
+private adapter are fixed implementation details, never accepted user selectors.
+
+## Persisted shape and granularity
+
+`TraceBaseline` retains existing `oa`/`sa: TracedProperties` and adds
+`#[serde(default)] semantic: Option<SemanticBaseline>`. Old absence is Unreviewed;
+never synthesize historical semantic values from today's project. Baseline and
+Trace use PartialEq, because typed semantic values include finite f64.
+
+`SemanticBaseline { facets: Vec<FacetReview> }` stores only independently reviewed
+facts. `FacetReview` is a closed self-tagged enum, nested by actual model family;
+each leaf carries `Reviewed<T> { oa: Observed<T>, sa: Observed<T> }`.
+`Observed<T>` is `NotApplicable | Value(T)`. T is fixed by the enum variant, reusing
+existing model types (DataValue, TypeRef, MessageValue, LifelineBinding, port/state
+enums and artifact metadata). No entry means Unreviewed. `Value(None)` is a real
+absent optional value, distinct from a missing constructor branch. Reject leaves
+inapplicable on both sides and selectors outside the compared record family.
+
+Historical keys use `KeyPair<K> { oa: Option<K>, sa: Option<K> }` in canonical
+OA/SA coordinates. Annotation keys are the entire `(path, field)`; binding keys
+are the referenced lifeline. An annotation or binding is one atomic optional row;
+retargeting its key is explicit removal/addition, with no heuristic rename.
+Other rows remain independently reviewable. Scalar field defaults are one atomic
+optional vector because their repeated values have no stable identity.
+
+Reference collection members and enum literals are individually reviewed facts.
+Enum keys are exact case-sensitive strings, not list indexes. Source collection
+Take applies additions/removals, preserving independently added target members.
+Ordering is its own typed Vec<Id> fact; membership acknowledgement never refreshes
+it. InterfaceItemAllocation order/protocols remain fields of the identified
+relation, not a second writable Interface.items list.
+
+Constructor groups are explicit, narrow semantic scopes. Data definition owns
+its variant fields and coupled default; PortContract owns contract plus Legacy
+payload; Event owns its variant payload; Occurrence owns its variant payload but
+not common pre/postconditions. Nested MessageKind/Timer changes expose dependent
+exchange/reply/value changes. StateKind is a semantic structural choice even
+though it changes Element::kind(). Accept a discriminator switch and its whole
+introduced/removed group atomically, retiring obsolete branch facts. Unchanged
+kind cannot acknowledge unrelated bound/default drift by a Keep shortcut. An
+explicit actual target switch may reconsider an earlier deliberate Keep.
+
+Persist only `DataConstructor`, `PortConstructor`, `OccurrenceConstructor`,
+`EventConstructor` and `MessageConstructor` discriminator enums (State uses the
+existing StateKind). A grouped decision uses a transient typed record, retires
+obsolete branch facts and stores each resulting descendant independently. A
+constructor payload snapshot must never overlap later independently reviewed
+leaves. Repeating Keep on an already acknowledged unequal discriminator pair
+cannot acknowledge newly changed bounds/defaults. Constructor retirement writes
+explicit NotApplicable target slots for agreement checking against other reviews.
+
+Artifact reviews are attached facts of the owning semantic trace; they do not
+widen ordinary Trace endpoint compatibility. Cover artifact membership and
+name/description/owner/relation/URI/revision/fragment, preserving target-only links.
+Do not fetch artifact content. Historical UUIDs remain after ordinary deletion,
+and explicit identity remapping visits keys and typed values without treating
+them as live graph edges.
+
+## Complete field catalog
+
+- Headers: existing name/description review; element parent. Identity, alias,
+  layer and placements are not incidental semantic edits.
+- OA/SA primitive bodies have no payload; Process/FunctionalChain have step
+  membership/order. Shared Machine/Region have no own payload.
+- ExchangeItem nature/mechanism/supertype; Interface supertype and independently
+  identified allocation relations.
+- DataType constructor, integer/real bounds, string lengths, enum members,
+  Record supertype, default and unit. DataField TypeRef, multiplicity bounds,
+  unit, direction, storage and optional default vector.
+- Port constructor, function input/output item membership, component
+  kind/orientation and Legacy direction/interface. Existing typed port generation,
+  explicit resolution/split and unsupported OA mappings remain authoritative.
+- Scenario viewpoint/context/pre/postconditions/steps; Lifeline represented ref.
+- Occurrence constructor/common pre/postconditions; Exchange endpoints/reference,
+  message kind/Timer expression, reply correlation and qualified annotations;
+  Action refs; Control kind; SequenceReference; ScenarioUse ref/bindings; State
+  refs; Fragment operator/branches; Branch guard/ordered occurrences.
+- Event Signal item membership, Time kind/expression, Change expression; State
+  kind and entry/exit/do prose.
+- All relation source/target endpoints; interface allocation order/protocols;
+  association roles/multiplicities/navigation; exchange item sets/ports/orientation;
+  capability-extend condition; sequence guard; state-transition kind, trigger/effect
+  sets and separate prose; StateAction phase. Other relation variants are endpoint-only.
+- Direct owned-child membership, incident relation identity with endpoint role,
+  and attached artifact membership/properties. Rollups distinguish own drift from
+  linked impact; shared referenced definitions are not copied into every baseline.
+
+## Review and command boundary
+
+Use the existing transition selection/dependency/mapping planner and ordinary
+Command preparation. Keep the prose request/API compatible; add sibling typed
+semantic request/preview/apply helpers. Whole existing typed records may appear
+as transient candidates or impact snapshots, never as persisted baseline carriers.
+
+The implemented sibling boundary is `SemanticTransitionRequest { transition,
+traces, references, reviews, candidates, accepted_impacts }`.
+`traces` selects a particular trace by source UUID when one endpoint pair has
+several traces; `references` is canonical OA→SA correspondence, including old
+deleted IDs. `SemanticReviewRequest { source, resolutions, reset }` and
+`FacetResolution { facet, decision }` use KeepTarget/TakeSource/Candidate.
+Candidates are full existing typed Element/Relation/Artifact records with identity
+and aliases protected; they must equal the result of selected facets exactly.
+`plan_semantic_transition`, `prepare_semantic_transition` and
+`apply_semantic_transition` reuse the existing mapping planner and Command batch.
+Previews expose typed current/drift facts, acknowledged and retired selectors,
+exact typed prepared impacts, conflicts, and a stale-check fingerprint.
+
+Artifact metadata slots are keyed by the actual artifact UUID, independent of
+which owning trace reaches them. Presence and owner share the ownership slot;
+metadata selection requires the currently attached owner. An explicit Owner
+candidate can move that link to another valid owner; its canonical owner slot
+must agree with any selected attachment decision. Creating a link
+requires a complete candidate and explicit review of every introduced metadata
+field. Removing a link retires its metadata and checks those removed slots against
+other decisions. Historical artifact keys/owners are visited only by explicit
+identity remapping, alongside all other historical UUIDs.
+
+Attachment authorization uses the immutable initial snapshot; metadata observations
+use the identified artifact record. Thus a target-only Owner or Owner+Name candidate
+records the actual resulting owner/metadata after a move, independent of facet
+order. Presence remains relative to the trace owner. A subsequent metadata decision
+through the former owner trace is rejected, while its historical observation remains
+available for drift. This avoids replacing an explicit owner value with both-side NA.
+
+Freeze mappings before proposals. Resolve all live and historical reference
+members through explicit correspondence; no display-name matching. Many sources
+may affect a target only when resolved deltas agree for each canonical target
+slot. A source/key-pair collision or contradictory target delta is a conflict,
+independent of request order. Mapping changes require explicit invalidation/reset
+of affected old reviews; never silently replace or accumulate overlapping pairs.
+
+An established paired selector remains the identity when one side's member or
+constructor branch disappears. It suppresses the redundant generated one-sided
+projection, preserving an NA/remaining-value observation. The reverse case is
+different: a newly appearing pair does not suppress old one-sided history and
+requires an explicit reset. Apply this rule to the closed keyed selector catalog,
+not only enumeration or constructor special cases.
+
+Every selected source derives desired values from the same immutable initial
+project. Apply explicit baseline resets before deriving its current catalog or
+constructor scope. Union all selected canonical slots across constructor scopes,
+including introduced members and removals, and reject disagreement before applying
+any writes. Materialize the agreed result once and compare every selected desired
+slot against it, then repeat that audit after ordinary command preparation.
+An exact approved cleanup impact still cannot contradict a selected Keep/Take.
+This invariant replaces sequential proposal mutation and order-dependent audits.
+When the target already has the proposed constructor, preserve target-only members
+while reconciling its group; a source constructor change is not whole-list deletion
+authority. Independently inferred orders must agree; commuting member removals
+filter those orders to surviving members without refreshing order history.
+
+Compare each side against its own reviewed value, retaining intentionally unequal
+pairs. Keep acknowledges only the selected current source/retained target fact.
+Take or a typed candidate acknowledges only the selected resulting fact. Untouched
+changes remain drift. Preview unreviewed differences rather than falsely claiming
+unchanged semantics. A selected constructor group names every fact it acknowledges.
+
+New resolution admission requires the appropriate current record family and at
+least one applicable current side. Persisted historical facts are different: their
+typed former family/constructor and deleted UUIDs remain valid history even after
+the live endpoints change. Validate their closed types, keys, duplicate slots,
+finite values, text and work limits without requiring present-day live references
+or present-day family applicability. Historical observations are never live edges.
+
+Linked shared-definition drift is derived, not copied into each referring baseline.
+The bounded walk follows reusable data fields/types, exchange items, interfaces,
+events and interface allocation declarations, stopping at 4096 objects per side
+or 32768 edges with an observable diagnostic. Parent edges and arbitrary architecture
+neighborhoods do not expand that walk. Missing pairs/reviews remain Unreviewed;
+own and linked rollups explicitly retain their unreviewed counts.
+
+Preserve target-only members and records. Removing source membership proposes
+unlinking, not deletion of target semantic objects. Ordered insertion is automatic
+only with a unique unchanged mapped anchor; ambiguous insertion/reorder requires
+an explicit final target order containing every surviving member once. Parent and
+relation endpoint edits remain explicit canonical operations, with aggregate
+membership effects linked to those same operations rather than competing commands.
+
+Prepare one complete candidate, then compare the actual prepared project against
+the explicitly reviewed result. Existing cleanup (including inherited annotation
+pruning) can cause additional changes: expose their exact typed before/after
+impact and require explicit review. Cancellation, stale fingerprint/ETag, missing
+resolution or invalid candidate leaves model, baseline, revision/history and disk
+unchanged. Baseline updates join the same ordinary atomic transaction. Repeated
+application is idempotent. The plan is still a client candidate, not a security
+receipt; ordinary validation is never bypassed.
+
+## Source/schema handoff and ownership
+
+Core owns model/types, the closed semantic catalog/helpers, transition integration,
+reference/remap/admission validation, lib registration and semantic core tests.
+Source worker owns persistence.rs version dispatch, language/source_project/source
+files, V4 compatibility migration and source/migration tests. Desktop/server are
+later separate integrations. Communicate compiled public types before dependent
+source edits. Coordinate the dedicated target; no concurrent Cargo mutations.
+
+Agreed internal helper, rooted at SemanticBaseline's serde tree:
+
+```rust
+pub(crate) enum HistoricalSourceKind { Reference, Enum }
+pub(crate) fn historical_source_slots(
+    baseline: &SemanticBaseline,
+) -> Vec<(Vec<String>, HistoricalSourceKind)>;
+```
+
+Paths are internal field names/list indexes, never persisted or public SemanticPath.
+Core derives slots from the same finite typed leaf catalog, including nested Id,
+model enums, Option/Vec, annotations/bindings and NotApplicable observations.
+Source can normalize historical AST leaves to temporary JSON, deserialize the
+existing typed SemanticBaseline, then check original token classes with this map.
+References require an explicit historical `uuid "..."`; enum leaves require bare
+words; other string leaves require quotes. Historical @alias is rejected. This
+handles Reviewed oa/sa text fields without weakening existing live @alias rules.
+Formatting and token/comment identity use the same slot metadata.
+
+Schema/source5 is explicit. V4 migration freezes only changed Trace/TraceBaseline
+shapes plus the closed old constructor catalog, reusing unchanged typed model
+records; retain V1/V2/V3 adapters and real compatibility fixtures. No public
+intermediate5 acceptance before full catalog, baseline roundtrip, source/JSON/API
+agreement and coupled persistence are verified. Earlier source/data4 remains real
+compatibility input, not a silently mutable contract.
+
+## Verification gates
+
+First close pure types/catalog/drift and typed source admission, then mapped review
+and complete atomic preparation. Cover every listed field family with observed
+mutations, including both directions and same-kind counterparts. Required focused
+cases: partial Keep/Take; constructors/defaults/units; row identity and changed old
+deleted references; target-only fields/triggers/literals/bindings/artifacts; order
+ambiguity; mapping reset and agreeing/conflicting many-to-one slots; wrong-family
+and both-side-NA admission; old semantic absence; prepared cleanup impacts; stale
+plan; duplicate decisions; no-op acknowledgement; repeat apply; undo/redo and invalid
+rollback. Test finite bounds and bounded nested/historical reference work.
+
+Then source/JSON historical UUID and mixed-constructor roundtrip, explicit migration,
+comment/identity preservation, actual REST ETag/disk/restart, native compact/normal
+review UI, independent semantics/correctness review and Windows/Linux verification.
+Do not quietly reduce this to scalar-only reconciliation. Incremental commits are
+implementation checkpoints, not release acceptance.

harness/release-semantic-source-plan.md

@@ -0,0 +1,39 @@
+# 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
+
+1. 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.
+2. 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.
+3. 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.
+4. 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.
+5. 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`.

harness/release-transition-contract.md

@@ -1,6 +1,6 @@
-# R3 semantic transition review contract proposal
+# R3 semantic transition review — historical proposal
 
-Status: read-only integration design, 2026-09-05; not implemented. The lead requested this while R5 topology was finishing. R5 final source/API verification takes precedence. R6 properties below refer to the proposed `release-data-contract.md` shapes and must follow the lead's final R6 freeze.
+Status: the representation recommendation below is superseded by `release-semantic-review-implementation.md`. Root selected closed typed per-facet reviews (C) after the 11-case executable comparison and independent critique. Recursive SemanticValue/string paths and typed-carrier/mask storage are not the production choice. The engineering requirements below remain design context where consistent with that authoritative implementation contract. Production R3 is not yet accepted.
 
 ## Current boundary and concrete outcome
 
@@ -8,7 +8,7 @@ Status: read-only integration design, 2026-09-05; not implemented. The lead requ
 
 An engineer must see a changed range, item list, parent, guard, occurrence, event trigger or interface contract; inspect its mapped proposal; accept selected changes or preserve intentional target differences; apply once, undo, and repeat without overwriting independent work. Neither direction is an automatic inverse. The original Capella iterative transition reference already linked in `release-semantics-audit.md` motivates conservative target comparison; the detailed decisions here are Studio's own contract.
 
-## Recommended exact public types
+## Rejected historical representation proposal
 
 Keep Name/Description unchanged for existing callers. Add a closed-catalog semantic field selector and typed values: