archctx 0.7.2 → 0.8.0

package/schemas/runtime/projection-manifest.schema.json

@@ -1,29 +1,26 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://archcontext.dev/schemas/runtime/projection-manifest.schema.json",
-  "title": "ArchitectureDocsProjectionManifestV2",
-  "description": "The committed docs/architecture/.projection-manifest.json the architecture documentation projection writes (#264). Version v2 (archctx 0.7.0) has content-stamp targets and provenance v3; a v1 manifest is not valid against this schema. Sorted/unique orders, targetCount/fileCount and the 1-2-5 bucket ladder are enforced by architectureDocsProjectionManifestIssues.",
+  "title": "ArchitectureDocsProjectionManifestV3",
+  "description": "The committed docs/architecture/.projection-manifest.json the architecture documentation projection writes (#264, #327). Version v3 records no global digest of all owned sources: header lines change only on a protocol upgrade, semanticBaseline.modelDigest is the one Git-visible anchor, and every other value belongs to one capability or one target row, so changes to different capabilities rewrite disjoint lines. A v1 or v2 manifest is not valid against this schema and is refused with projection-manifest-upgrade-required. Sorted/unique orders, one stamp per node, scale/sourceStamps pairing, the 1-2-5 bucket ladder and the byte layout are enforced by architectureDocsProjectionManifestIssues and serializeArchitectureDocsProjectionManifest.",
   "type": "object",
   "additionalProperties": false,
   "required": [
     "schemaVersion",
     "rendererVersion",
     "profile",
-    "sourceDigest",
-    "provenance",
-    "projectionDigest",
+    "layoutVersion",
+    "generatedFrom",
     "semanticBaseline",
-    "receiptDigest",
-    "targetCount",
-    "fileCount",
     "targets"
   ],
   "properties": {
     "schemaVersion": {
-      "const": "archcontext.architecture-docs-projection-manifest/v2"
+      "const": "archcontext.architecture-docs-projection-manifest/v3"
     },
     "rendererVersion": {
-      "const": "archcontext.docs-renderer/v5"
+      "type": "string",
+      "minLength": 1
     },
     "profile": {
       "enum": [
@@ -31,34 +28,47 @@
         "repo-harness/v1"
       ]
     },
-    "sourceDigest": {
-      "$ref": "#/$defs/digest"
-    },
-    "provenance": {
-      "$ref": "#/$defs/provenance"
+    "layoutVersion": {
+      "const": "archcontext.docs-layout/v1"
     },
-    "projectionDigest": {
-      "$ref": "#/$defs/digest"
+    "generatedFrom": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "codeGraphPackage",
+        "codeGraphVersion"
+      ],
+      "description": "Reproducible CodeGraph identity only: package name and version. The binary digest, index status and evidence digests are machine-specific runtime facts and never enter the committed manifest (#266, #277).",
+      "properties": {
+        "codeGraphPackage": {
+          "type": "string",
+          "minLength": 1
+        },
+        "codeGraphVersion": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
     },
     "semanticBaseline": {
       "$ref": "#/$defs/semanticBaseline"
     },
-    "receiptDigest": {
-      "$ref": "#/$defs/digest"
-    },
-    "targetCount": {
-      "type": "integer",
-      "minimum": 0
-    },
-    "fileCount": {
-      "type": "integer",
-      "minimum": 0
-    },
     "targets": {
-      "type": "array",
-      "items": {
+      "type": "object",
+      "description": "Target rows keyed by targetId.",
+      "additionalProperties": {
         "$ref": "#/$defs/target"
       }
+    },
+    "minimumRendererVersion": {
+      "type": "string",
+      "pattern": "^archcontext\\.docs-renderer/v[1-9][0-9]*$",
+      "description": "Optional minimum engine renderer; an older engine refuses rendering and writes."
+    },
+    "minimumProtocolVersion": {
+      "type": "string",
+      "pattern": "^archcontext\\.projection-request/v[1-9][0-9]*$",
+      "description": "Optional minimum projection request protocol supported by the engine."
     }
   },
   "$defs": {
@@ -66,132 +76,17 @@
       "type": "string",
       "pattern": "^sha256:[a-f0-9]{64}$"
     },
-    "provenance": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "schemaVersion",
-        "sourceTreeDigest",
-        "modelDigest",
-        "projectionInputDigest",
-        "rendererVersion",
-        "layoutVersion",
-        "generatedFrom"
-      ],
-      "properties": {
-        "schemaVersion": {
-          "const": "archcontext.architecture-docs-projection-provenance/v3"
-        },
-        "sourceTreeDigest": {
-          "$ref": "#/$defs/digest"
-        },
-        "modelDigest": {
-          "$ref": "#/$defs/digest"
-        },
-        "projectionInputDigest": {
-          "$ref": "#/$defs/digest"
-        },
-        "rendererVersion": {
-          "const": "archcontext.docs-renderer/v5"
-        },
-        "layoutVersion": {
-          "const": "archcontext.docs-layout/v1"
-        },
-        "generatedFrom": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": [
-            "codeGraphPackage",
-            "codeGraphVersion"
-          ],
-          "description": "Reproducible CodeGraph identity only: package name and version. The binary digest, index status and evidence digests are machine-specific runtime facts and never enter the committed manifest (#266, #277).",
-          "properties": {
-            "codeGraphPackage": {
-              "type": "string",
-              "minLength": 1
-            },
-            "codeGraphVersion": {
-              "type": "string",
-              "minLength": 1
-            }
-          }
-        }
-      }
-    },
     "semanticBaseline": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "semanticState",
-        "digests"
-      ],
-      "properties": {
-        "semanticState": {
-          "$ref": "#/$defs/semanticState"
-        },
-        "digests": {
-          "$ref": "#/$defs/digestSet"
-        },
-        "evidence": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": [
-            "sourceTreeDigest",
-            "selectorEvidenceDigest",
-            "rendererVersion"
-          ],
-          "description": "The non-model proof inputs this baseline was rendered from. Absent in manifests written before it existed.",
-          "properties": {
-            "sourceTreeDigest": {
-              "$ref": "#/$defs/digest"
-            },
-            "selectorEvidenceDigest": {
-              "$ref": "#/$defs/digest"
-            },
-            "rendererVersion": {
-              "type": "string",
-              "minLength": 1
-            }
-          }
-        }
-      }
-    },
-    "digestSet": {
       "type": "object",
       "additionalProperties": false,
       "required": [
         "modelDigest",
-        "sourceTreeDigest",
-        "flowProofDigest",
-        "projectionDigest"
+        "capabilities"
       ],
       "properties": {
         "modelDigest": {
-          "$ref": "#/$defs/digest"
-        },
-        "sourceTreeDigest": {
-          "$ref": "#/$defs/digest"
-        },
-        "flowProofDigest": {
-          "$ref": "#/$defs/digest"
-        },
-        "projectionDigest": {
-          "$ref": "#/$defs/digest"
-        }
-      }
-    },
-    "semanticState": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "schemaVersion",
-        "capabilities",
-        "semanticFingerprint",
-        "flowProofFingerprint"
-      ],
-      "properties": {
-        "schemaVersion": {
-          "const": "archcontext.architecture-semantic-state/v1"
+          "$ref": "#/$defs/digest",
+          "description": "The one Git-visible anchor: the digest of the model this baseline was compiled from. Concurrent model changes conflict on this line, as they should."
         },
         "capabilities": {
           "type": "array",
@@ -199,12 +94,6 @@
           "items": {
             "$ref": "#/$defs/capabilityState"
           }
-        },
-        "semanticFingerprint": {
-          "$ref": "#/$defs/digest"
-        },
-        "flowProofFingerprint": {
-          "$ref": "#/$defs/digest"
         }
       }
     },
@@ -217,7 +106,8 @@
         "semanticFingerprint",
         "flowProofFingerprint",
         "proofStatus",
-        "facets"
+        "facets",
+        "selectorEvidenceDigest"
       ],
       "properties": {
         "capabilityId": {
@@ -288,6 +178,10 @@
               "$ref": "#/$defs/digest"
             }
           }
+        },
+        "selectorEvidenceDigest": {
+          "$ref": "#/$defs/digest",
+          "description": "Digest of the proof-relevant selector evidence for the selectors this capability's flows cite."
         }
       }
     },
@@ -353,21 +247,15 @@
       "type": "object",
       "additionalProperties": false,
       "required": [
-        "targetId",
         "type",
         "scope",
         "path",
         "ownership",
-        "rendererVersion",
         "format",
-        "sourceDigest",
         "outputDigest"
       ],
+      "description": "One target row, keyed by its targetId. The key and the manifest header carry the targetId and the renderer version, so the row repeats neither.",
       "properties": {
-        "targetId": {
-          "type": "string",
-          "minLength": 1
-        },
         "type": {
           "enum": [
             "architecture-index",
@@ -429,9 +317,6 @@
             "mixed"
           ]
         },
-        "rendererVersion": {
-          "const": "archcontext.docs-renderer/v5"
-        },
         "format": {
           "enum": [
             "markdown",
@@ -440,49 +325,59 @@
             "likec4"
           ]
         },
-        "sourceDigest": {
-          "$ref": "#/$defs/digest"
-        },
         "outputDigest": {
           "$ref": "#/$defs/digest"
         },
-        "sourceFootprintDigest": {
-          "$ref": "#/$defs/digest",
-          "description": "Content digest of the node's declared source footprint the document was verified against. entity-summary targets of nodes that declare source.include only; present exactly when scale is."
+        "sourceStamps": {
+          "type": "object",
+          "description": "entity-summary targets only: the content digest of every declared source footprint this target documents, by node id. Each footprint belongs to its node's nearest ancestor-or-self with an entity-summary target, so each node is stamped on exactly one row.",
+          "additionalProperties": {
+            "$ref": "#/$defs/digest"
+          }
         },
         "scale": {
           "$ref": "#/$defs/scale",
-          "description": "The scale buckets the module document prints. Present exactly when sourceFootprintDigest is."
+          "description": "Present exactly when sourceStamps stamps the target's own node."
         }
       },
       "allOf": [
         {
           "if": {
             "required": [
-              "sourceFootprintDigest"
+              "scale"
             ]
           },
           "then": {
             "required": [
-              "scale"
-            ],
-            "properties": {
-              "type": {
-                "const": "entity-summary"
-              }
-            }
+              "sourceStamps"
+            ]
           }
         },
         {
           "if": {
-            "required": [
-              "scale"
-            ]
+            "properties": {
+              "type": {
+                "not": {
+                  "const": "entity-summary"
+                }
+              }
+            }
           },
           "then": {
-            "required": [
-              "sourceFootprintDigest"
-            ]
+            "not": {
+              "anyOf": [
+                {
+                  "required": [
+                    "sourceStamps"
+                  ]
+                },
+                {
+                  "required": [
+                    "scale"
+                  ]
+                }
+              ]
+            }
           }
         }
       ]

package/schemas/runtime/projection-result.schema.json

@@ -8,7 +8,7 @@
   "properties": {
     "schemaVersion": { "const": "archcontext.projection-result/v2" },
     "requestId": { "type": "string", "pattern": "^[a-zA-Z0-9_.:-]+$", "minLength": 1 },
-    "status": { "enum": ["adoption-required", "applied", "applied-reconcile-required", "blocked", "human-action-required", "noop", "permanent-failure", "planned", "retryable-failure"] },
+    "status": { "enum": ["adoption-required", "applied", "applied-partial", "applied-reconcile-required", "blocked", "human-action-required", "noop", "permanent-failure", "planned", "planned-partial", "retryable-failure"] },
     "inputSnapshot": { "$ref": "#/$defs/snapshot" },
     "outputSnapshot": { "$ref": "#/$defs/snapshot" },
     "affectedNodeIds": { "type": "array", "uniqueItems": true, "description": "Canonical wire order is lexicographic and is enforced by projectionResultInvariantIssues.", "items": { "type": "string", "minLength": 1 } },
@@ -18,8 +18,12 @@
     "applyReceipt": { "$ref": "#/$defs/applyIdentity" },
     "priorCommittedApplies": { "type": "array", "minItems": 1, "description": "Omitted, never empty. Canonical wire order is by changeSetId and is enforced by projectionResultInvariantIssues.", "items": { "$ref": "#/$defs/priorCommittedApply" } },
     "freshness": { "$ref": "#/$defs/freshness" },
+    "architectureDebt": { "$ref": "#/$defs/architectureDebt" },
+    "changes": { "type": "array", "description": "Present on every check and plan result and on no other. One entry per target path, the projection manifest excluded. Canonical wire order is by path; the precedence derivation of classification, the reason-code couplings and the binding of plannedAction to files[] and of blocked targets to coverage are enforced by projectionTargetChangesIssues and projectionResultInvariantIssues.", "items": { "$ref": "#/$defs/targetChange" } },
     "replayed": { "const": true, "description": "A repeated apply for the same requestId and request digest returned the committed result without applying again. Excluded from receiptDigest." },
+    "written": { "type": "boolean", "description": "Present exactly when replayed is. false: the replay wrote nothing. true: the projection-owned outputs differed from the approved result at the approved snapshot and the replay wrote the committed fixed point again under the original receipt. Excluded from receiptDigest." },
     "majorChangeAcceptance": { "const": "declined-unprovable-proof", "description": "Present only when the request sent acceptObservedMajorChange and the provider declined it because a capability proof is unprovable; humanActions then carries unprovable-required-flow instead of unresolved-major-change." },
+    "coverage": { "$ref": "#/$defs/coverage" },
     "receiptDigest": { "$ref": "#/$defs/digest" }
   },
   "allOf": [
@@ -47,12 +51,25 @@
         }
       }
     },
+    {
+      "if": { "properties": { "status": { "enum": ["applied-partial", "planned-partial"] } }, "required": ["status"] },
+      "then": {
+        "required": ["coverage"],
+        "not": { "required": ["applyReceipt"] },
+        "properties": { "refreshSignals": { "maxItems": 0 } }
+      },
+      "else": { "not": { "required": ["coverage"] } }
+    },
     {
       "if": { "required": ["replayed"] },
       "then": {
-        "required": ["applyReceipt"],
+        "required": ["applyReceipt", "written"],
         "properties": { "status": { "enum": ["applied", "applied-reconcile-required"] } }
       }
+    },
+    {
+      "if": { "required": ["written"] },
+      "then": { "required": ["replayed"] }
     }
   ],
   "$defs": {
@@ -73,7 +90,7 @@
         "codeGraphDigest": { "$ref": "#/$defs/digest" },
         "indexedWorktreeDigest": { "$ref": "#/$defs/nullableDigest" },
         "projectionInputDigest": { "$ref": "#/$defs/digest" },
-        "rendererVersion": { "const": "archcontext.docs-renderer/v5" },
+        "rendererVersion": { "const": "archcontext.docs-renderer/v6" },
         "layoutVersion": { "const": "archcontext.docs-layout/v1" },
         "generatedFrom": {
           "type": "object",
@@ -81,7 +98,7 @@
           "required": ["codeGraphPackage", "codeGraphVersion", "codeGraphStatus"],
           "properties": {
             "codeGraphPackage": { "const": "@colbymchenry/codegraph" },
-            "codeGraphVersion": { "const": "1.6.1" },
+            "codeGraphVersion": { "const": "1.6.2" },
             "codeGraphStatus": { "enum": ["ready", "unavailable"] }
           }
         }
@@ -250,7 +267,7 @@
         "reasonCodes": {
           "type": "array",
           "uniqueItems": true,
-          "items": { "enum": ["projection-manifest-missing", "projection-manifest-unreadable", "projection-snapshot-provenance-missing", "projection-source-changed-since-stamp", "projection-source-stamp-invalid", "projection-source-stamp-missing", "projection-source-tree-digest-mismatch"] }
+          "items": { "enum": ["projection-manifest-missing", "projection-manifest-unreadable", "projection-source-changed-since-stamp", "projection-source-stamp-missing", "projection-source-tree-digest-mismatch"] }
         },
         "staleNodes": {
           "type": "array",
@@ -267,6 +284,116 @@
         }
       }
     },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Present exactly on planned-partial and applied-partial results; a result that covers every target omits it. Canonical wire orders, the capability bindings and the exclusion of carried-forward paths from files are enforced by projectionCoverageIssues.",
+      "required": ["complete", "blockedCapabilityIds", "blockedTargets", "appliedTargetIds"],
+      "properties": {
+        "complete": { "const": false },
+        "blockedCapabilityIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "blockedTargets": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["targetId", "path", "capabilityIds", "reasonCodes"],
+            "properties": {
+              "targetId": { "type": "string", "minLength": 1 },
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "not": { "anyOf": [{ "pattern": "^/" }, { "pattern": "\\\\" }, { "pattern": "(^|/)\\.\\.(/|$)" }] }
+              },
+              "capabilityIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+              "reasonCodes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["unprovable-required-flow", "verified-flow-proof-changed"] } }
+            }
+          }
+        },
+        "appliedTargetIds": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "targetChange": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How one target changes since the committed projection and what this run's write does to its file (#327). null is an unknown comparison. classification follows blocked > proof-change (a known proof change) > baseline-missing > semantic-change > output-change > stamp-only > unchanged.",
+      "required": ["targetId", "path", "affectedCapabilityIds", "stampChanged", "outputChanged", "semanticChanged", "proofChanged", "plannedAction", "classification", "reasonCodes"],
+      "properties": {
+        "targetId": { "type": "string", "minLength": 1 },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "not": { "anyOf": [{ "pattern": "^/" }, { "pattern": "\\\\" }, { "pattern": "(^|/)\\.\\.(/|$)" }] }
+        },
+        "affectedCapabilityIds": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "stampChanged": { "type": ["boolean", "null"] },
+        "outputChanged": { "type": "boolean" },
+        "semanticChanged": { "type": ["boolean", "null"] },
+        "proofChanged": { "type": ["boolean", "null"] },
+        "plannedAction": { "enum": ["create", "delete", "none", "update"] },
+        "classification": { "enum": ["baseline-missing", "blocked", "output-change", "proof-change", "semantic-change", "stamp-only", "unchanged"] },
+        "reasonCodes": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "enum": ["adoption-required", "ambiguous-ownership", "baseline-missing", "file-bytes-changed", "flow-proof-changed", "model-digest-changed", "orphan-review-required", "rendered-output-changed", "selector-evidence-changed", "semantic-fingerprint-changed", "source-stamp-changed", "target-added", "target-removed", "target-row-missing", "unprovable-required-flow", "verified-flow-proof-changed"] }
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "classification": { "const": "blocked" } }, "required": ["classification"] },
+          "then": { "properties": { "plannedAction": { "const": "none" } } }
+        },
+        {
+          "if": { "properties": { "classification": { "enum": ["stamp-only", "unchanged"] } }, "required": ["classification"] },
+          "then": { "properties": { "plannedAction": { "const": "none" }, "outputChanged": { "const": false }, "stampChanged": { "type": "boolean" }, "semanticChanged": { "const": false }, "proofChanged": { "const": false } } }
+        },
+        {
+          "if": { "properties": { "classification": { "const": "unchanged" } }, "required": ["classification"] },
+          "then": { "properties": { "reasonCodes": { "maxItems": 0 }, "affectedCapabilityIds": { "maxItems": 0 } } },
+          "else": { "properties": { "reasonCodes": { "minItems": 1 } } }
+        }
+      ]
+    },
+    "architectureDebt": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Present on every check and plan result and on no other. Never changes status. Canonical wire orders and the coverage/coverageReasonCodes coupling are enforced by projectionArchitectureDebtIssues.",
+      "required": ["coverage", "coverageReasonCodes", "items"],
+      "properties": {
+        "coverage": { "enum": ["complete", "partial", "unknown"] },
+        "coverageReasonCodes": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "enum": ["code-facts-import-limit", "code-facts-truncated", "code-facts-unavailable", "workspace-resolution-failed"] }
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["reasonCode", "fromCapabilityId", "toCapabilityId", "importEdgeCount"],
+            "properties": {
+              "reasonCode": { "enum": ["undeclared-dependency"] },
+              "fromCapabilityId": { "type": "string", "minLength": 1 },
+              "toCapabilityId": { "type": "string", "minLength": 1 },
+              "importEdgeCount": { "type": "integer", "minimum": 1 }
+            }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "coverage": { "const": "complete" } }, "required": ["coverage"] },
+          "then": { "properties": { "coverageReasonCodes": { "maxItems": 0 } } },
+          "else": { "properties": { "coverageReasonCodes": { "minItems": 1 } } }
+        },
+        {
+          "if": { "properties": { "coverage": { "const": "unknown" } }, "required": ["coverage"] },
+          "then": { "properties": { "items": { "maxItems": 0 } } }
+        }
+      ]
+    },
     "priorCommittedApply": {
       "type": "object",
       "additionalProperties": false,

package/schemas/runtime/projection-target.schema.json

@@ -4,7 +4,10 @@
   "title": "ProjectionTarget",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schemaVersion", "targetId", "type", "scope", "path", "ownership", "generatedRegion", "rendererVersion", "format", "sourceDigest", "outputDigest"],
+  "required": ["schemaVersion", "targetId", "type", "scope", "path", "ownership", "rendererVersion", "format", "sourceDigest", "outputDigest"],
+  "if": { "properties": { "ownership": { "const": "mixed" } }, "required": ["ownership"] },
+  "then": { "required": ["generatedRegion"] },
+  "else": { "not": { "required": ["generatedRegion"] } },
   "properties": {
     "schemaVersion": { "const": "archcontext.projection-target/v1" },
     "targetId": { "type": "string", "pattern": "^projection_target\\.[a-zA-Z0-9_.-]+$" },