Improve behavior authoring and typed trace history (untested checkpoint)

docs/language.html

@@ -667,7 +667,7 @@ Actual verification evidence is separate from this contract.</p>
 </section>
 <section id="one-authoritative-model">
 <h2>2. One authoritative model</h2>
-<p>A Project stores <span class="docutils literal">schema_version</span> (6), <span class="docutils literal">id</span>, <span class="docutils literal">alias</span>, <span class="docutils literal">name</span>,
+<p>A Project stores <span class="docutils literal">schema_version</span> (7), <span class="docutils literal">id</span>, <span class="docutils literal">alias</span>, <span class="docutils literal">name</span>,
 <span class="docutils literal">description</span>, and maps named <span class="docutils literal">elements</span>, <span class="docutils literal">relations</span>, <span class="docutils literal">diagrams</span>,
 <span class="docutils literal">artifact_links</span>, and <span class="docutils literal">traces</span>. Each map is keyed by the UUID contained in
 its record. Duplicate map keys and mismatching keys/identities are errors.</p>
@@ -730,6 +730,10 @@ lists all additional fields. <span class="docutils literal">ref</span> means <sp
 <td><p><span class="docutils literal">kind</span>: Information, Material, Energy; <span class="docutils literal">mechanism</span>: ExchangeMechanism; <span class="docutils literal">supertype</span>: item ref?</p></td>
 <td><p>Information; Unspecified; none</p></td>
 </tr>
+<tr><td><p><span class="docutils literal">oa_exchange_category</span>, <span class="docutils literal">sa_exchange_category</span></p></td>
+<td><p><span class="docutils literal">family</span>: Work or Participant; <span class="docutils literal">exchanges</span>: same-layer exchange refs</p></td>
+<td><p>Work; <span class="docutils literal">[]</span>; root-level only</p></td>
+</tr>
 <tr><td><p><span class="docutils literal">oa_data_type</span>, <span class="docutils literal">sa_data_type</span></p></td>
 <td><p><span class="docutils literal">definition</span>: DataTypeDefinition; <span class="docutils literal">default</span>: DataValue?; <span class="docutils literal">unit</span>: string</p></td>
 <td><p>String with minimum_length 0 / maximum_length none; none; <span class="docutils literal">&quot;&quot;</span></p></td>
@@ -869,7 +873,9 @@ work and produces a warning. The System cannot own internal components.
 The present Studio profile does not decompose SA Actors.</p>
 <p>All relations have a header identity, alias, display name, optional
 <span class="docutils literal">description</span> (default <span class="docutils literal">&quot;&quot;</span>), and required <span class="docutils literal">source</span> and <span class="docutils literal">target</span>
-references. Their kind is the declaration keyword:</p>
+endpoints. Ordinary endpoints are semantic references; ContextualLink endpoints
+are qualified OccurrenceEndpoint records resolved from its required <span class="docutils literal">owner</span>.
+Their kind is the declaration keyword:</p>
 <table>
 <caption>Relation catalog</caption>
 <colgroup>
@@ -956,6 +962,10 @@ references. Their kind is the declaration keyword:</p>
 <td><p>Preceding contribution → following contribution in one process/chain</p></td>
 <td><p><span class="docutils literal">guard</span> string / &quot;&quot;</p></td>
 </tr>
+<tr><td><p><span class="docutils literal">contextual_link</span></p></td>
+<td><p>Qualified occurrence endpoints resolved from an explicit owner Process/FunctionalChain; section 4.2.1</p></td>
+<td><p>Required <span class="docutils literal">owner</span>, <span class="docutils literal">source</span> and <span class="docutils literal">target</span> OccurrenceEndpoint records, and typed <span class="docutils literal">purpose</span>: Precedence, Exchange or CommonWork</p></td>
+</tr>
 <tr><td><p><span class="docutils literal">state_transition</span></p></td>
 <td><p>State vertices in one machine, subject to section 4.4</p></td>
 <td><p><span class="docutils literal">trigger</span>, <span class="docutils literal">guard</span>, <span class="docutils literal">effect</span> strings / &quot;&quot;; <span class="docutils literal">transition_kind</span> External; <span class="docutils literal">triggers</span>, <span class="docutils literal">effects</span> reference lists / []</p></td>
@@ -1811,7 +1821,7 @@ are invalid.</p>
 <td><p>Operational Mission → System Mission</p></td>
 </tr>
 <tr><td><p>Exchange</p></td>
-<td><p>Interaction relation → FunctionalExchange relation</p></td>
+<td><p>Interaction → FunctionalExchange, or CommunicationMean → BoundaryExchange</p></td>
 </tr>
 <tr><td><p>Sequence</p></td>
 <td><p>Process → FunctionalChain, or paired occurrence contributions directly owned by Process / FunctionalChain</p></td>
@@ -2261,7 +2271,7 @@ deeply nested drafts produce a diagnostic instead of exhausting the parser stack
 <h3>6.1. Modular source projects</h3>
 <p>The pure <span class="docutils literal">source_project</span> core API compiles a virtual source bundle, containing
 <span class="docutils literal">entry</span> and a <span class="docutils literal">files</span> map from logical paths to UTF-8 strings. Its entry is a
-root-level <span class="docutils literal">.arcadia</span> file with the source5 project header above. A project entry
+root-level <span class="docutils literal">.arcadia</span> file with the source7 project header above. A project entry
 MAY also be <span class="docutils literal">include string &quot;;&quot;</span>. An included fragment consists only of ordinary
 declarations and include statements; it MUST NOT contain another version header,
 project wrapper, or project description. Includes MUST occur at document level,
@@ -2324,15 +2334,15 @@ the source index. Columns remain one-based Unicode scalars within the real file;
 spans never refer to concatenated or synthetic source.</p>
 <p>Single-string parse/lint APIs remain filesystem-free and reject include
 statements with an explicit source-bundle requirement. V1/V2 single-file imports
-continue through explicit migration. Modular projects accept source3, source4 and
-source5. Source3 is upgraded as one project, preserving file paths, includes, nested
+continue through explicit migration. Modular projects accept source3 through
+source7. Older bundles are upgraded as one project, preserving file paths, includes, nested
 ownership and comments through targeted token edits. Generated allocation
 declarations stay in their interface's existing file. Individual include fragments
 are not independently migrated. Missing UUIDs stabilize before migration so new
 allocation identities are deterministic on subsequent compilation.
 An authored source4 bundle upgrades through the strict prose-only baseline
 adapter; after any missing UUID stabilization, the version token alone changes
-to 5. Existing prose, comments, includes and nested ownership remain intact.
+to 7. Existing prose, comments, includes and nested ownership remain intact.
 Source5 semantic facet comments follow their closed selector identity through
 row reordering and reidentification; UUID-looking text does not act as an Id.</p>
 </section>
@@ -2654,7 +2664,7 @@ defaults without changing any prior identity, name, reference, order, geometry,
 artifact or trace field. The original V2 golden source/JSON in
 <span class="docutils literal"><span class="pre">crates/oa-core/tests/fixtures</span></span> MUST NOT be regenerated from the newer demo;
 they verify that every old persistent field survives. Canonical output writes
-the added defaults through the explicit schema-3, schema-4 and schema-5 migrations.</p>
+the added defaults through explicit migration to the current schema 7.</p>
 <p>The V2 adapter preserves every original identity, alias, prose, parent,
 placement, trace and artifact. Generic ports become Legacy with their original
 direction/interface record. Existing FE endpoint IDs remain unchanged. For
@@ -2671,13 +2681,13 @@ IDs, required resolutions, generated endpoint IDs/aliases/owners, and boundary
 orientation defaults. REST import, replacement, candidate validation and
 project snapshots surface the same report. Opening an old server envelope
 preserves its resource ID/revision and bytes; the next explicit edit writes
-schema 5. Model/source exports contain only the canonical model. Migration
+schema 7. Model/source exports contain only the canonical model. Migration
 reports are transient response metadata, not persisted model facts.</p>
 <p>Admission checks account for generated objects and their references before
-construction. Both the old V2 contract and the resulting V5 graph are
+construction. Both the old V2 contract and the resulting current graph are
 validated. Migration itself does not save or increase a stored revision.
 Canonical second saves are stable. V1 normalization produces the frozen V2
-model and then uses these same V2-to-3-to-4-to-5 stages.</p>
+model and then uses the same explicit adapters to reach schema 7.</p>
 <p>Save validates a snapshot, writes a sibling temporary file, flushes it, and
 atomically replaces the destination. Failed serialization or validation must
 not truncate a previous file. External concurrent-writer conflict resolution