archctx-contracts 0.6.3 → 0.7.1

package/fixtures/valid/runtime-refactor-scan.json

@@ -0,0 +1,543 @@
+{
+  "schemaVersion": "archcontext.runtime-refactor-scan/v1",
+  "repository": {
+    "repositoryId": "repo.537182127c5f2134",
+    "storageRepositoryId": "repo.03ba73c90cbf6a7e"
+  },
+  "worktree": {
+    "workspaceId": "ws.537182127c5f2134",
+    "storageWorkspaceId": "ws.537182127c5f2134",
+    "branch": "main",
+    "headSha": "728b42479d7ab7a2d401ea44af26cdac64912f0f",
+    "worktreeDigest": "sha256:96cbb5ccf708d8b7c56c2633e8937311338957998b7154879461706460d4c467"
+  },
+  "requestId": "refactor_request.d514edefd58b7a9e",
+  "request": {
+    "schemaVersion": "archcontext.refactor-request/v1",
+    "scope": {
+      "kind": "repository"
+    }
+  },
+  "trackedFileCount": 9,
+  "untrackedExcludedCount": 0,
+  "snapshot": {
+    "schemaVersion": "archcontext.module-statistics/v1",
+    "repository": {
+      "repositoryId": "repo.537182127c5f2134",
+      "storageRepositoryId": "repo.03ba73c90cbf6a7e"
+    },
+    "worktree": {
+      "workspaceId": "ws.537182127c5f2134",
+      "storageWorkspaceId": "ws.537182127c5f2134",
+      "branch": "main",
+      "headSha": "728b42479d7ab7a2d401ea44af26cdac64912f0f",
+      "worktreeDigest": "sha256:96cbb5ccf708d8b7c56c2633e8937311338957998b7154879461706460d4c467"
+    },
+    "modelDigest": "sha256:54ed020e2f65d0649b215df9251332d5a288746a687d9d7a654b9700dfd995a7",
+    "codeFacts": {
+      "provider": "codegraph",
+      "version": "",
+      "binaryDigest": "",
+      "indexedWorktreeDigest": null,
+      "coverage": "unknown",
+      "truncated": true,
+      "edgeLimit": 5000,
+      "reasonCodes": [
+        "caller-coverage-unknown",
+        "code-facts-missing",
+        "code-facts-truncated",
+        "node-footprint-undeclared"
+      ]
+    },
+    "modules": [
+      {
+        "nodeId": "capability.architecture.context",
+        "nodeDigest": "sha256:47f48ff9115682aeb1cce33a01ecac47ef79935a7e9a10a4577d7e7c8582c3f0",
+        "parentNodeId": null,
+        "footprintDeclared": false,
+        "footprint": null,
+        "surfaces": {
+          "declaredEntrypoints": [],
+          "observedEntrypoints": [],
+          "lifecycleOwners": [],
+          "datastoreSubjects": []
+        },
+        "dependencyGraph": null,
+        "tests": {
+          "testFileCount": null,
+          "observedTestEdges": null,
+          "callerCoverage": null,
+          "coverageStatus": "unknown"
+        },
+        "uncertainty": {
+          "unresolvedImports": 0,
+          "dynamicInvocation": "unknown",
+          "ambiguousOwnership": false
+        },
+        "moduleDigest": "sha256:7c539afac512c4aed0d7408f4b1945c51ddb79e24a017732c2a2a5cd5f52481e"
+      },
+      {
+        "nodeId": "module.dump",
+        "nodeDigest": "sha256:8f77a427f093506f0ff5197dd0129f6888c1653c0ccc65e3981d587e102a882b",
+        "parentNodeId": null,
+        "footprintDeclared": true,
+        "footprint": {
+          "fileCount": 1,
+          "lineCount": 1,
+          "sourceFilesDigest": "sha256:5f2ceccfe01dc55c63a1b0e5bf2ce51676e8f2805499e0c8519d59fdc8e265c4",
+          "includePatterns": [
+            "src/**"
+          ],
+          "excludePatterns": []
+        },
+        "surfaces": {
+          "declaredEntrypoints": [],
+          "observedEntrypoints": [],
+          "lifecycleOwners": [],
+          "datastoreSubjects": []
+        },
+        "dependencyGraph": null,
+        "tests": {
+          "testFileCount": null,
+          "observedTestEdges": null,
+          "callerCoverage": null,
+          "coverageStatus": "unknown"
+        },
+        "uncertainty": {
+          "unresolvedImports": 0,
+          "dynamicInvocation": "unknown",
+          "ambiguousOwnership": false
+        },
+        "moduleDigest": "sha256:32d887790fe89e1415d1cb0e68557509e025b4026184ad8a463f4d886a3de182"
+      }
+    ],
+    "repositorySummary": {
+      "moduleCount": 2,
+      "undeclaredFootprintNodeCount": 1,
+      "ownedFileCount": 1,
+      "unownedFileCount": 0,
+      "multiplyOwnedFileCount": 0,
+      "crossModuleEdgeCount": 0,
+      "crossModuleCycleCount": 0,
+      "stronglyConnectedComponentCount": 0,
+      "unresolvedImportCount": 0,
+      "dynamicInvocationRiskCount": 2
+    },
+    "createdAt": "2026-10-11T04:21:31.000Z",
+    "snapshotDigest": "sha256:35796bb112cab526dfe31a9ad84bc9df5d28b6a9ef4154d7d3c2d7d3a7753f7e"
+  },
+  "assessment": {
+    "schemaVersion": "archcontext.refactor-assessment/v1",
+    "requestId": "refactor_request.d514edefd58b7a9e",
+    "statisticsSnapshotDigest": "sha256:35796bb112cab526dfe31a9ad84bc9df5d28b6a9ef4154d7d3c2d7d3a7753f7e",
+    "modelDigest": "sha256:54ed020e2f65d0649b215df9251332d5a288746a687d9d7a654b9700dfd995a7",
+    "codeFactsDigest": "sha256:1044803e55c9413cc85b58a5d5ec995b311d1ee50cc476f80b7f7babf3ad4662",
+    "requestedScope": {
+      "kind": "repository"
+    },
+    "proposalDigest": null,
+    "observations": [
+      {
+        "kind": "evidence-gap",
+        "subjectSelectorId": "repository:repo.537182127c5f2134",
+        "metrics": {
+          "unresolvedImportCount": 0,
+          "edgeLimit": 5000
+        },
+        "evidence": {
+          "kind": "evidence-gap",
+          "coverage": "unknown",
+          "reasonCodes": [
+            "caller-coverage-unknown",
+            "code-facts-missing",
+            "code-facts-truncated",
+            "node-footprint-undeclared"
+          ],
+          "unresolvedImports": [],
+          "totalCount": 0,
+          "truncated": false
+        },
+        "signalIds": [
+          "signal.evidence-gap.262e0ca20828366e"
+        ]
+      },
+      {
+        "kind": "undeclared-footprint",
+        "subjectSelectorId": "capability.architecture.context",
+        "metrics": {},
+        "evidence": {
+          "kind": "undeclared-footprint",
+          "paths": [],
+          "totalCount": 0,
+          "truncated": false
+        },
+        "signalIds": [
+          "signal.undeclared-footprint.bc66b760c4329111"
+        ]
+      }
+    ],
+    "scale": null,
+    "scaleReasonCodes": [],
+    "affectedNodeIds": [],
+    "majorChangeReasons": [],
+    "pressure": {
+      "level": "low",
+      "score": 10,
+      "signalIds": [
+        "signal.evidence-gap.262e0ca20828366e",
+        "signal.undeclared-footprint.bc66b760c4329111"
+      ]
+    },
+    "confidence": {
+      "level": "low",
+      "callerCoverage": null,
+      "testsObserved": null,
+      "rollbackObserved": null,
+      "unresolvedEvidence": [
+        "coverage:unknown"
+      ]
+    },
+    "createdAt": "2026-10-11T04:21:31.000Z",
+    "assessmentDigest": "sha256:308510d9a08558453b9644d33fe24a73f4579832c448602b24c5053bdc4aa5ca"
+  },
+  "proposedRecommendations": [
+    {
+      "schemaVersion": "archcontext.recommendation/v3",
+      "recommendationId": "recommendation.c8c842b3d8529388",
+      "runId": "recommendation_run.9d3423295f1a45e6",
+      "fingerprint": "sha256:27b2fed8524041b6003797081dbf77355d7fccfa54327becf00ecaef0728db2a",
+      "subject": "capability.architecture.context",
+      "status": "open",
+      "confidence": "low",
+      "enforcement": "advisory",
+      "risk": "medium",
+      "uncertainty": "high",
+      "evidenceBindingIds": [
+        "binding.7577455e29083b0b"
+      ],
+      "explanation": [
+        "capability.architecture.context declares no source.include footprint, so none of its files or imports are measured.",
+        "It declares no entrypoint paths either."
+      ],
+      "authoredBy": {
+        "kind": "daemon",
+        "id": "archctxd",
+        "source": "daemon"
+      },
+      "subjectSelectorId": "subject.node.d4eae75fb5b5121f",
+      "relations": {},
+      "createdAt": "2026-10-11T04:21:31.000Z",
+      "updatedAt": "2026-10-11T04:21:31.000Z",
+      "category": "structural_observation",
+      "payload": {
+        "assessmentDigest": "sha256:308510d9a08558453b9644d33fe24a73f4579832c448602b24c5053bdc4aa5ca",
+        "kind": "undeclared-footprint",
+        "affectedNodeIds": [
+          "capability.architecture.context"
+        ],
+        "baselineSnapshotDigest": "sha256:35796bb112cab526dfe31a9ad84bc9df5d28b6a9ef4154d7d3c2d7d3a7753f7e",
+        "derivedOutcomes": [
+          {
+            "metric": "module.footprintDeclared",
+            "subjectSelectorId": "subject.node.d4eae75fb5b5121f",
+            "nodeId": "capability.architecture.context",
+            "operator": "present",
+            "value": null,
+            "required": true,
+            "outcomeId": "outcome.58946c9d4f0f41c1"
+          }
+        ],
+        "metrics": {},
+        "signalIds": [
+          "signal.undeclared-footprint.bc66b760c4329111"
+        ],
+        "evidence": {
+          "kind": "undeclared-footprint",
+          "paths": [],
+          "totalCount": 0,
+          "truncated": false
+        }
+      },
+      "extensions": {
+        "assessmentDigest": "sha256:308510d9a08558453b9644d33fe24a73f4579832c448602b24c5053bdc4aa5ca",
+        "baselineSnapshotDigest": "sha256:35796bb112cab526dfe31a9ad84bc9df5d28b6a9ef4154d7d3c2d7d3a7753f7e",
+        "riskSignals": [
+          "ownership-change"
+        ],
+        "uncertaintySignals": [
+          "low-coverage"
+        ],
+        "score": 23
+      }
+    },
+    {
+      "schemaVersion": "archcontext.recommendation/v3",
+      "recommendationId": "recommendation.22feb92677c752aa",
+      "runId": "recommendation_run.9d3423295f1a45e6",
+      "fingerprint": "sha256:d84b7558a783350a40ee16260cce07b4caed1270b8984f774329fa980f91b0a9",
+      "subject": "repository:repo.537182127c5f2134",
+      "status": "open",
+      "confidence": "low",
+      "enforcement": "advisory",
+      "risk": "low",
+      "uncertainty": "high",
+      "evidenceBindingIds": [
+        "binding.3bc9dc35b8c72768"
+      ],
+      "explanation": [
+        "Code facts coverage is unknown (caller-coverage-unknown, code-facts-missing, code-facts-truncated, node-footprint-undeclared), so structural metrics are incomplete."
+      ],
+      "authoredBy": {
+        "kind": "daemon",
+        "id": "archctxd",
+        "source": "daemon"
+      },
+      "subjectSelectorId": "subject.repository.525bab1b3e65c960",
+      "relations": {},
+      "createdAt": "2026-10-11T04:21:31.000Z",
+      "updatedAt": "2026-10-11T04:21:31.000Z",
+      "category": "structural_observation",
+      "payload": {
+        "assessmentDigest": "sha256:308510d9a08558453b9644d33fe24a73f4579832c448602b24c5053bdc4aa5ca",
+        "kind": "evidence-gap",
+        "affectedNodeIds": [],
+        "baselineSnapshotDigest": "sha256:35796bb112cab526dfe31a9ad84bc9df5d28b6a9ef4154d7d3c2d7d3a7753f7e",
+        "derivedOutcomes": [
+          {
+            "metric": "repositorySummary.unresolvedImportCount",
+            "subjectSelectorId": "subject.repository.525bab1b3e65c960",
+            "nodeId": null,
+            "operator": "absent",
+            "value": null,
+            "required": true,
+            "outcomeId": "outcome.8ad0edda6755e289"
+          }
+        ],
+        "metrics": {
+          "unresolvedImportCount": 0,
+          "edgeLimit": 5000
+        },
+        "signalIds": [
+          "signal.evidence-gap.262e0ca20828366e"
+        ],
+        "evidence": {
+          "kind": "evidence-gap",
+          "coverage": "unknown",
+          "reasonCodes": [
+            "caller-coverage-unknown",
+            "code-facts-missing",
+            "code-facts-truncated",
+            "node-footprint-undeclared"
+          ],
+          "unresolvedImports": [],
+          "totalCount": 0,
+          "truncated": false
+        }
+      },
+      "extensions": {
+        "assessmentDigest": "sha256:308510d9a08558453b9644d33fe24a73f4579832c448602b24c5053bdc4aa5ca",
+        "baselineSnapshotDigest": "sha256:35796bb112cab526dfe31a9ad84bc9df5d28b6a9ef4154d7d3c2d7d3a7753f7e",
+        "riskSignals": [],
+        "uncertaintySignals": [
+          "low-coverage"
+        ],
+        "score": 13
+      }
+    }
+  ],
+  "evidenceItems": [
+    {
+      "schemaVersion": "archcontext.evidence-item/v2",
+      "evidenceId": "evidence.module_statistics_snapshot.35796bb112cab526",
+      "kind": "module-statistics-snapshot",
+      "strength": "observed",
+      "polarity": "positive",
+      "origin": "runtime-daemon",
+      "subject": "repository:repo.537182127c5f2134",
+      "selector": {
+        "kind": "snapshot",
+        "id": "sha256:35796bb112cab526dfe31a9ad84bc9df5d28b6a9ef4154d7d3c2d7d3a7753f7e"
+      },
+      "summary": "Module statistics baseline for 2 declared module(s).",
+      "coverage": {
+        "level": "unknown",
+        "scope": "module-statistics-snapshot"
+      },
+      "supports": [
+        "recommendation"
+      ],
+      "provenance": {
+        "producer": "recommendation-engine",
+        "command": "archctx refactor record",
+        "inputDigest": "sha256:35796bb112cab526dfe31a9ad84bc9df5d28b6a9ef4154d7d3c2d7d3a7753f7e"
+      },
+      "createdAt": "2026-10-11T04:21:31.000Z",
+      "digest": "sha256:5ee758961ef4ea532ef72359f46e2d06fa528d70bab6bd19cd59dbfca8acd3fc",
+      "extensions": {
+        "moduleStatisticsSnapshot": {
+          "schemaVersion": "archcontext.module-statistics/v1",
+          "repository": {
+            "repositoryId": "repo.537182127c5f2134",
+            "storageRepositoryId": "repo.03ba73c90cbf6a7e"
+          },
+          "worktree": {
+            "workspaceId": "ws.537182127c5f2134",
+            "storageWorkspaceId": "ws.537182127c5f2134",
+            "branch": "main",
+            "headSha": "728b42479d7ab7a2d401ea44af26cdac64912f0f",
+            "worktreeDigest": "sha256:96cbb5ccf708d8b7c56c2633e8937311338957998b7154879461706460d4c467"
+          },
+          "modelDigest": "sha256:54ed020e2f65d0649b215df9251332d5a288746a687d9d7a654b9700dfd995a7",
+          "codeFacts": {
+            "provider": "codegraph",
+            "version": "",
+            "binaryDigest": "",
+            "indexedWorktreeDigest": null,
+            "coverage": "unknown",
+            "truncated": true,
+            "edgeLimit": 5000,
+            "reasonCodes": [
+              "caller-coverage-unknown",
+              "code-facts-missing",
+              "code-facts-truncated",
+              "node-footprint-undeclared"
+            ]
+          },
+          "modules": [
+            {
+              "nodeId": "capability.architecture.context",
+              "nodeDigest": "sha256:47f48ff9115682aeb1cce33a01ecac47ef79935a7e9a10a4577d7e7c8582c3f0",
+              "parentNodeId": null,
+              "footprintDeclared": false,
+              "footprint": null,
+              "surfaces": {
+                "declaredEntrypoints": [],
+                "observedEntrypoints": [],
+                "lifecycleOwners": [],
+                "datastoreSubjects": []
+              },
+              "dependencyGraph": null,
+              "tests": {
+                "testFileCount": null,
+                "observedTestEdges": null,
+                "callerCoverage": null,
+                "coverageStatus": "unknown"
+              },
+              "uncertainty": {
+                "unresolvedImports": 0,
+                "dynamicInvocation": "unknown",
+                "ambiguousOwnership": false
+              },
+              "moduleDigest": "sha256:7c539afac512c4aed0d7408f4b1945c51ddb79e24a017732c2a2a5cd5f52481e"
+            },
+            {
+              "nodeId": "module.dump",
+              "nodeDigest": "sha256:8f77a427f093506f0ff5197dd0129f6888c1653c0ccc65e3981d587e102a882b",
+              "parentNodeId": null,
+              "footprintDeclared": true,
+              "footprint": {
+                "fileCount": 1,
+                "lineCount": 1,
+                "sourceFilesDigest": "sha256:5f2ceccfe01dc55c63a1b0e5bf2ce51676e8f2805499e0c8519d59fdc8e265c4",
+                "includePatterns": [
+                  "src/**"
+                ],
+                "excludePatterns": []
+              },
+              "surfaces": {
+                "declaredEntrypoints": [],
+                "observedEntrypoints": [],
+                "lifecycleOwners": [],
+                "datastoreSubjects": []
+              },
+              "dependencyGraph": null,
+              "tests": {
+                "testFileCount": null,
+                "observedTestEdges": null,
+                "callerCoverage": null,
+                "coverageStatus": "unknown"
+              },
+              "uncertainty": {
+                "unresolvedImports": 0,
+                "dynamicInvocation": "unknown",
+                "ambiguousOwnership": false
+              },
+              "moduleDigest": "sha256:32d887790fe89e1415d1cb0e68557509e025b4026184ad8a463f4d886a3de182"
+            }
+          ],
+          "repositorySummary": {
+            "moduleCount": 2,
+            "undeclaredFootprintNodeCount": 1,
+            "ownedFileCount": 1,
+            "unownedFileCount": 0,
+            "multiplyOwnedFileCount": 0,
+            "crossModuleEdgeCount": 0,
+            "crossModuleCycleCount": 0,
+            "stronglyConnectedComponentCount": 0,
+            "unresolvedImportCount": 0,
+            "dynamicInvocationRiskCount": 2
+          },
+          "createdAt": "2026-10-11T04:21:31.000Z",
+          "snapshotDigest": "sha256:35796bb112cab526dfe31a9ad84bc9df5d28b6a9ef4154d7d3c2d7d3a7753f7e"
+        }
+      }
+    }
+  ],
+  "evidenceBindings": [
+    {
+      "schemaVersion": "archcontext.evidence-binding/v1",
+      "bindingId": "binding.7577455e29083b0b",
+      "evidenceId": "evidence.module_statistics_snapshot.35796bb112cab526",
+      "target": {
+        "kind": "recommendation",
+        "id": "recommendation.c8c842b3d8529388"
+      },
+      "bindingReason": "deterministic-check",
+      "authorityEffect": "context-only",
+      "createdAt": "2026-10-11T04:21:31.000Z",
+      "provenance": {
+        "producer": "recommendation-engine",
+        "command": "archctx refactor record",
+        "inputDigest": "sha256:35796bb112cab526dfe31a9ad84bc9df5d28b6a9ef4154d7d3c2d7d3a7753f7e"
+      }
+    },
+    {
+      "schemaVersion": "archcontext.evidence-binding/v1",
+      "bindingId": "binding.3bc9dc35b8c72768",
+      "evidenceId": "evidence.module_statistics_snapshot.35796bb112cab526",
+      "target": {
+        "kind": "recommendation",
+        "id": "recommendation.22feb92677c752aa"
+      },
+      "bindingReason": "deterministic-check",
+      "authorityEffect": "context-only",
+      "createdAt": "2026-10-11T04:21:31.000Z",
+      "provenance": {
+        "producer": "recommendation-engine",
+        "command": "archctx refactor record",
+        "inputDigest": "sha256:35796bb112cab526dfe31a9ad84bc9df5d28b6a9ef4154d7d3c2d7d3a7753f7e"
+      }
+    }
+  ],
+  "suppressed": [],
+  "recording": {
+    "recordable": true,
+    "reasonCode": null,
+    "measuredBytes": 11039,
+    "limitBytes": 262144
+  },
+  "limits": {
+    "evidenceSampleLimit": 20,
+    "maxEvidenceSampleLimit": 20,
+    "maxRecommendationsPerRun": 25,
+    "candidateCount": 2,
+    "omittedCandidateCount": 0
+  },
+  "recordCommand": "archctx refactor record --assessment-digest sha256:308510d9a08558453b9644d33fe24a73f4579832c448602b24c5053bdc4aa5ca --expected-worktree-digest sha256:96cbb5ccf708d8b7c56c2633e8937311338957998b7154879461706460d4c467",
+  "privacy": {
+    "writes": "none",
+    "rawSourcePersisted": false,
+    "rawDiffPersisted": false,
+    "promptPersisted": false
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archctx-contracts",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/schemas/runtime/archctx-capabilities.schema.json

@@ -31,7 +31,7 @@
       "additionalProperties": false,
       "required": ["architectureDocs", "agentContext"],
       "properties": {
-        "architectureDocs": { "const": "archcontext.docs-renderer/v4" },
+        "architectureDocs": { "const": "archcontext.docs-renderer/v5" },
         "agentContext": { "const": "archcontext.agent-context-renderer/v1" }
       }
     },
@@ -39,7 +39,12 @@
       "type": "array",
       "minItems": 3,
       "uniqueItems": true,
-      "items": { "enum": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "module-statistics-v1", "projection-apply-readback-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-prior-committed-applies-v1", "projection-protocol-v2", "recommendation-v3", "refactor-assessment-v1", "refactor-resolution-v1"] }
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*-v[0-9]+$",
+        "description": "One feature flag: a lowercase kebab-case name that ends in a version suffix (-v1, -v2, ...). The pattern is open, so a validator built from this schema accepts flags that a later archctx adds. A consumer must ignore a flag it does not know. examples lists the flags this schema version knows.",
+        "examples": ["architecture-change-capabilities-v1", "architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "capability-dependencies-v1", "changeset-entity-operations-v1", "changeset-ownership-delta-v1", "code-facts-unavailable-error-v1", "docs-anchors-v1", "flow-selector-check-v1", "module-statistics-v1", "projection-apply-readback-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-apply-replay-v1", "projection-check-freshness-v1", "projection-manifest-contract-v2", "projection-observed-major-change-acceptance-v1", "projection-orphan-review-v1", "projection-preview-v1", "projection-prior-committed-applies-v1", "projection-protocol-v2", "recommendation-scan-decision-v1", "recommendation-v3", "refactor-assessment-v1", "refactor-observation-evidence-v1", "refactor-resolution-v1", "refactor-scan-limits-v1", "refactor-scan-untracked-count-v1"]
+      }
     }
   }
 }

package/schemas/runtime/architecture-refresh-signal.schema.json

@@ -40,6 +40,12 @@
       "uniqueItems": true,
       "items": { "type": "string", "minLength": 1 }
     },
+    "capabilities": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The observed per-capability breakdown of this signal, sorted by capabilityId (enforced by architectureRefreshSignalInvariantIssues). Part of the signal identity; signals committed before it existed lack it.",
+      "items": { "$ref": "#/$defs/capabilityChange" }
+    },
     "refreshTargets": {
       "type": "array",
       "minItems": 1,
@@ -59,6 +65,27 @@
   ],
   "$defs": {
     "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "capabilityChange": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["capabilityId", "reasonCodes", "changedFacets", "proofStatusBefore", "proofStatusAfter"],
+      "properties": {
+        "capabilityId": { "type": "string", "minLength": 1 },
+        "reasonCodes": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/reasonCode" } },
+        "changedFacets": { "type": "array", "uniqueItems": true, "items": { "enum": ["constraints", "entrypoints", "interfaces", "lifecycle", "names", "ownership", "placement", "relations", "responsibilities", "riskBoundaries"] } },
+        "proofStatusBefore": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/proofStatus" }] },
+        "proofStatusAfter": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/proofStatus" }] }
+      }
+    },
+    "proofStatus": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["p1", "p2"],
+      "properties": {
+        "p1": { "enum": ["proven", "unprovable"] },
+        "p2": { "enum": ["not-applicable", "proven", "unprovable"] }
+      }
+    },
     "reasonCode": {
       "enum": ["constraint-changed", "entrypoint-changed", "interface-changed", "lifecycle-changed", "node-added", "node-moved", "node-removed", "node-renamed", "ownership-changed", "relation-changed", "responsibility-changed", "risk-boundary-changed", "verified-flow-proof-changed"]
     },