Checkpoint source 7 workflows and in-progress diagram authoring redesign

Preserve current core, source, REST, desktop, recovery, documentation and validation work, including AGENTS.md and the development summary. This is a work-in-progress checkpoint: the new compact palette has outstanding compilation errors and native acceptance; earlier passing gates retain their documented scope.

crates/oa-server/tests/semantic_schema.py

@@ -1,7 +1,7 @@
 """Refresh the closed semantic OpenAPI catalog from the frozen Rust leaf table.
 
 Run from any directory with Python 3: semantic_schema.py [--check] [--validate].
---validate additionally runs source-6 structural fixtures with jsonschema.
+--validate additionally runs source-7 structural fixtures with jsonschema.
 This generates documentation only, never runtime selectors or model mutations.
 """
 import copy
@@ -99,7 +99,7 @@ for family, selector, review, body in families:
     schemas[review] = {"oneOf": [variant(leaf, reviewed(value)) for leaf, value in leaves]}
     selectors.append(variant(family, ref(selector)))
     reviews.append(variant(family, ref(review)))
-assert leaf_count == 85
+assert leaf_count == 90
 schemas["AnnotationKey"] = obj({"path": array(ref("Id")), "field": ref("Id")})
 id_keys, text_keys, annotation_keys = keypair("Id"), keypair("String"), keypair("AnnotationKey")
 artifact_types = {"Presence": "bool", "Name": "String", "Description": "String", "Owner": "Id",
@@ -124,13 +124,13 @@ schemas["FacetReview"] = {"oneOf": reviews}
 schemas["SemanticBaseline"] = obj({"facets": array(ref("FacetReview"))})
 schemas["TraceBaseline"]["properties"]["semantic"] = {**optional(ref("SemanticBaseline")), "default": None,
     "description": "Absent/null means Unreviewed. Historical typed facts never become live graph references."}
-schemas["Project"]["properties"]["schema_version"]["const"] = 6
-schemas["MigrationReport"]["properties"]["from_schema"]["enum"] = [1, 2, 3, 4, 5]
-schemas["MigrationReport"]["properties"]["to_schema"]["const"] = 6
-schemas["MigrationReport"]["description"] = re.sub(r"V1(?:/V[2-5])+ to V[4-6]", "V1/V2/V3/V4/V5 to V6", schemas["MigrationReport"]["description"])
-spec["info"]["description"] = re.sub(r"schema-[45]", "schema-6", spec["info"]["description"])
-spec["paths"]["/api/v1/projects/import"]["post"]["description"] = "Schema-6 native JSON is described below. Schema-1/2/3/4/5 JSON and source are accepted through explicit frozen readers and migration, also on replacement and candidate validation. Earlier versions reject source-6 constructors and saved view fields. Prior prose and typed reviews remain intact; absent semantic review stays Unreviewed. Export emits schema 6 / arcadia 6. See docs/language.rst."
-schemas["SourceBundle"]["description"] = re.sub(r"source[45] workspace \(source[^)]+\)", "source6 workspace (source3/4/5 migrate explicitly)", schemas["SourceBundle"]["description"])
+schemas["Project"]["properties"]["schema_version"]["const"] = 7
+schemas["MigrationReport"]["properties"]["from_schema"]["enum"] = [1, 2, 3, 4, 5, 6]
+schemas["MigrationReport"]["properties"]["to_schema"]["const"] = 7
+schemas["MigrationReport"]["description"] = re.sub(r"V1(?:/V[2-6])+ to V[4-7]", "V1/V2/V3/V4/V5/V6 to V7", schemas["MigrationReport"]["description"])
+spec["info"]["description"] = re.sub(r"schema-[4-6]", "schema-7", spec["info"]["description"])
+spec["paths"]["/api/v1/projects/import"]["post"]["description"] = "Schema-7 native JSON is described below. Schema-1/2/3/4/5/6 JSON and source are accepted through explicit frozen readers and migration, also on replacement and candidate validation. Earlier versions reject later constructors, fields and semantic facets, including explicit null. Prior prose and typed reviews remain intact; absent semantic review stays Unreviewed. Export emits schema 7 / arcadia 7. See docs/language.rst."
+schemas["SourceBundle"]["description"] = re.sub(r"source[4-6] workspace \(source[^)]+\)", "source7 workspace (source3/4/5/6 migrate explicitly)", schemas["SourceBundle"]["description"])
 
 # Source-6 additions are closed serde records; selectors with an empty payload
 # remain explicit selections rather than reverting to their omitted defaults.
@@ -155,6 +155,28 @@ def upsert_variant(variants, name, value):
 
 upsert_variant(schemas["RelationBody"]["oneOf"], "CommunicationMean", obj({
     "source": ref("Id"), "target": ref("Id"), "oriented": typed("bool"), "items": array(ref("Id"))}))
+
+# Source-7 adds exact caller-instance addresses and explicit operation intent.
+# Structural schemas do not replace core owner/path/port/signature validation.
+schemas["OccurrenceEndpoint"] = obj({"references": array(ref("Id"), 64), "occurrence": ref("Id")})
+schemas["OccurrenceEndpoint"]["description"] = "Ordered reference-occurrence IDs in an explicit caller owner, followed by the leaf contribution ID. Empty references means a direct contribution; sequence definition IDs are not path components."
+schemas["ContextualLinkPurpose"] = {"oneOf": [
+    variant("Precedence", obj({"guard": typed("String")})),
+    variant("Exchange", obj({"exchange": ref("Id")})),
+    variant("CommonWork", obj({"work": ref("Id")}))]}
+upsert_variant(schemas["RelationBody"]["oneOf"], "ContextualLink", obj({
+    "owner": ref("Id"), "source": ref("OccurrenceEndpoint"),
+    "target": ref("OccurrenceEndpoint"), "purpose": ref("ContextualLinkPurpose")}))
+schemas["OperationUse"] = obj({"allocation": optional(ref("Id"))}, [])
+schemas["OperationUse"]["description"] = "Present with absent/null allocation retains unresolved operation intent. A selected UUID identifies exactly an InterfaceItemAllocation, never an item, port, or name. Reply derives operation from its exact correlated Call."
+exchange_body = next(v["properties"]["Exchange"] for v in schemas["OccurrenceBody"]["oneOf"]
+                     if "Exchange" in v.get("properties", {}))
+exchange_body["properties"]["operation"] = {**optional(ref("OperationUse")), "default": None}
+exchange_body["description"] = "Absent/null operation retains ordinary channel semantics and is omitted on output. Present operation is allowed only on SA BoundaryInterface Call/Asynchronous messages. Reply stores no operation and derives its exact Call's selection. Existing message defaults remain unchanged."
+schemas["OperationOmission"] = obj({"source": ref("Id"), "rationale": typed("String")})
+schemas["TransitionRequest"]["properties"]["operation_omissions"] = {
+    **array(ref("OperationOmission"), 200), "default": [],
+    "description": "Explicit SA-to-OA abstraction per selected invocation with operation intent. Nonempty rationale required by core; duplicates, irrelevant sources, and other directions are refused. Replies derive the Call abstraction. Source operation identities and values are preserved."}
 upsert_variant(schemas["SharedBody"]["oneOf"][1]["oneOf"], "ExchangeCategory", obj({
     "family": ref("ExchangeFamily"), "exchanges": array(ref("Id"))}))
 schemas["CommunicationPortChoice"] = {"oneOf": [
@@ -298,9 +320,42 @@ if "--validate" in sys.argv:
     accepts("FacetSelector", {"Category": "Unknown"}, False)
     accepts("FacetReview", {"Category": {"Family": {"oa": {"Value": "Work"}, "sa": {"Value": "Participant"}}}})
     accepts("FacetSelector", {"Member": {"collection": "CategoryExchanges", "keys": {"oa": a, "sa": b}}})
-    assert schemas["Project"]["properties"]["schema_version"]["const"] == 6
-    assert schemas["MigrationReport"]["properties"]["from_schema"]["enum"] == [1, 2, 3, 4, 5]
-    print(f"Source-6 schema fixtures: {fixture_count} passed; all {len(schemas)} component schemas well-formed")
+    endpoint = {"references": [a], "occurrence": b}
+    accepts("OccurrenceEndpoint", endpoint)
+    accepts("OccurrenceEndpoint", {**endpoint, "references": []})
+    accepts("OccurrenceEndpoint", {**endpoint, "references": [a] * 64})
+    accepts("OccurrenceEndpoint", {**endpoint, "references": [a] * 65}, False)
+    accepts("OccurrenceEndpoint", {**endpoint, "typo": a}, False)
+    accepts("OccurrenceEndpoint", {"occurrence": a}, False)
+    for purpose in [{"Precedence": {"guard": "ready"}}, {"Exchange": {"exchange": a}},
+                    {"CommonWork": {"work": b}}]:
+        link = {"owner": a, "source": endpoint, "target": {"references": [], "occurrence": a},
+                "purpose": purpose}
+        accepts("RelationBody", {"ContextualLink": link})
+        accepts("RelationBody", {"ContextualLink": {**link, "extra": None}}, False)
+    accepts("ContextualLinkPurpose", {"CommonWork": {"work": a, "guard": ""}}, False)
+    accepts("OperationUse", {})
+    accepts("OperationUse", {"allocation": None})
+    accepts("OperationUse", {"allocation": a})
+    accepts("OperationUse", {"allocation": a, "item": b}, False)
+    accepts("OperationUse", {"allocation": "wrong"}, False)
+    message = {"exchange": a, "sender": a, "receiver": b, "message_kind": "Call"}
+    for operation in [None, {}, {"allocation": None}, {"allocation": a}]:
+        accepts("OccurrenceBody", {"Exchange": {**message, "operation": operation}})
+    accepts("OccurrenceBody", {"Exchange": {**message, "operation": a}}, False)
+    omission = {"source": a, "rationale": "Operational abstraction retains the request intent."}
+    accepts("OperationOmission", omission)
+    accepts("OperationOmission", {"source": a}, False)
+    accepts("TransitionRequest", {**request, "operation_omissions": [omission] * 200})
+    accepts("TransitionRequest", {**request, "operation_omissions": [omission] * 201}, False)
+    accepts("FacetSelector", {"Occurrence": "Operation"})
+    for facet in ["ContextOwner", "ContextSource", "ContextTarget", "ContextPurpose"]:
+        accepts("FacetSelector", {"Relation": facet})
+    accepts("FacetReview", {"Occurrence": {"Operation": {
+        "oa": "NotApplicable", "sa": {"Value": {"allocation": a}}}}})
+    assert schemas["Project"]["properties"]["schema_version"]["const"] == 7
+    assert schemas["MigrationReport"]["properties"]["from_schema"]["enum"] == [1, 2, 3, 4, 5, 6]
+    print(f"Source-7 schema fixtures: {fixture_count} passed; all {len(schemas)} component schemas well-formed")
 
 rendered = json.dumps(spec, indent=2, ensure_ascii=False) + "\n"
 if "--check" in sys.argv: