archctx-contracts 0.7.2 → 0.8.1

package/schemas/runtime/architecture-debt.schema.json

@@ -0,0 +1,222 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archctx.repoharness.com/schemas/runtime/architecture-debt.schema.json",
+  "title": "ArchitectureDebtReportV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "scope",
+    "coverage",
+    "coverageReasonCodes",
+    "checks",
+    "items",
+    "actionsRequired",
+    "digest"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "archcontext.architecture-debt/v1"
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "changedPaths",
+        "capabilityIds"
+      ],
+      "properties": {
+        "kind": {
+          "enum": [
+            "repository",
+            "changed-paths"
+          ]
+        },
+        "changedPaths": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024
+          }
+        },
+        "capabilityIds": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024
+          }
+        }
+      }
+    },
+    "coverage": {
+      "enum": [
+        "complete",
+        "partial",
+        "unknown"
+      ]
+    },
+    "coverageReasonCodes": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 1024
+      }
+    },
+    "checks": {
+      "type": "array",
+      "minItems": 5,
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "check",
+          "coverage",
+          "reasonCodes"
+        ],
+        "properties": {
+          "check": {
+            "enum": [
+              "ownership",
+              "anchors",
+              "dependencies",
+              "flows",
+              "practices"
+            ]
+          },
+          "coverage": {
+            "enum": [
+              "complete",
+              "partial",
+              "unknown"
+            ]
+          },
+          "reasonCodes": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024
+            }
+          }
+        }
+      }
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "kind",
+          "nodeIds",
+          "capabilityIds",
+          "paths",
+          "reasonCode",
+          "action",
+          "details"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^debt\\.[a-f0-9]{64}$"
+          },
+          "kind": {
+            "enum": [
+              "unowned-path",
+              "ambiguous-owner",
+              "undeclared-dependency",
+              "flow-proof-failed",
+              "stale-anchor",
+              "practice-regression"
+            ]
+          },
+          "nodeIds": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024
+            }
+          },
+          "capabilityIds": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024
+            }
+          },
+          "paths": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024
+            }
+          },
+          "reasonCode": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024
+          },
+          "action": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024
+          },
+          "details": {
+            "type": "object",
+            "maxProperties": 12,
+            "additionalProperties": {
+              "oneOf": [
+                {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 1024
+                },
+                {
+                  "type": "integer"
+                },
+                {
+                  "type": "array",
+                  "uniqueItems": true,
+                  "items": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1024
+                  }
+                }
+              ]
+            }
+          }
+        }
+      }
+    },
+    "actionsRequired": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 1024
+      }
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    }
+  }
+}

package/schemas/runtime/capability-dependencies.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://archcontext.dev/schemas/runtime/capability-dependencies.schema.json",
   "title": "CapabilityDependenciesV1",
-  "description": "The data of `archctx deps`: a read-only capability x capability import matrix. Owners come from the parent-chain rule `refactor scan` uses, rolled up to the nearest capability. Call counts are not available in v1.",
+  "description": "The data of `archctx deps`: a read-only capability x capability import matrix. Owners come from the parent-chain rule `refactor scan` uses, rolled up to the nearest capability. Each cell says whether a model relation declares it. Call counts are not available in v1. Without code facts that attest to the measured tree, deps refuses with AC_CODE_FACTS_UNAVAILABLE instead of returning this data.",
   "type": "object",
   "additionalProperties": false,
   "required": ["schemaVersion", "ownershipRule", "filter", "capabilities", "matrix", "imports", "calls", "edges", "worktree", "privacy"],
@@ -24,13 +24,17 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["from", "to", "imports", "calls"],
+        "required": ["from", "to", "imports", "calls", "declared", "relationIds"],
         "properties": {
           "from": { "type": "string", "minLength": 1 },
           "to": { "type": "string", "minLength": 1 },
           "imports": { "type": "integer", "minimum": 1 },
-          "calls": { "type": "null" }
-        }
+          "calls": { "type": "null" },
+          "declared": { "type": "boolean", "description": "A relation of a declaring kind (every kind but deployed-on) runs from a node that rolls up to `from` into a node that rolls up to `to`. A cell with from equal to to is always declared and lists no relation ids." },
+          "relationIds": { "type": "array", "uniqueItems": true, "description": "The declaring relation ids, sorted. Non-empty exactly when a cross-capability cell is declared.", "items": { "type": "string", "minLength": 1 } }
+        },
+        "if": { "properties": { "relationIds": { "minItems": 1 } } },
+        "then": { "properties": { "declared": { "const": true } } }
       }
     },
     "imports": {
@@ -38,11 +42,11 @@
       "additionalProperties": false,
       "required": ["coverage", "reasonCodes", "truncated", "importNodeCount", "importNodeLimit", "importNodeLimitExceeded", "edgeCount", "unresolvedCount", "unattributed"],
       "properties": {
-        "coverage": { "enum": ["complete", "partial", "unknown"] },
+        "coverage": { "enum": ["complete", "partial"] },
         "reasonCodes": {
           "type": "array",
           "uniqueItems": true,
-          "items": { "enum": ["code-facts-import-limit", "code-facts-stale", "code-facts-truncated", "code-facts-unavailable"] }
+          "items": { "enum": ["code-facts-import-limit", "code-facts-truncated"] }
         },
         "truncated": { "type": "boolean" },
         "importNodeCount": { "type": ["integer", "null"], "minimum": 0 },

package/schemas/runtime/changeset.schema.json

@@ -93,7 +93,8 @@
                   "write_policy",
                   "write_waiver",
                   "render_projection",
-                  "render_agent_context"
+                  "render_agent_context",
+                  "write_refactor_decision"
                 ]
               },
               "entityId": {
@@ -150,6 +151,28 @@
                           "const": true
                         }
                       }
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "description": "Binds one projection-owned file the write set carries forward unchanged; accepted only by render_projection with the exact body hash the render read. Nothing is written; the apply fails unless the file still has that hash immediately before the commit.",
+                      "required": [
+                        "path",
+                        "expectedHash",
+                        "guard"
+                      ],
+                      "properties": {
+                        "path": {
+                          "type": "string"
+                        },
+                        "expectedHash": {
+                          "type": "string",
+                          "pattern": "^sha256:[a-f0-9]{64}$"
+                        },
+                        "guard": {
+                          "const": true
+                        }
+                      }
                     }
                   ]
                 }

package/schemas/runtime/docs-anchors.schema.json

@@ -41,12 +41,13 @@
         "byKind": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["line-moved", "line-out-of-range", "missing-path", "missing-symbol"],
+          "required": ["line-moved", "line-out-of-range", "missing-path", "missing-symbol", "unknown-selector"],
           "properties": {
             "line-moved": { "$ref": "#/$defs/count" },
             "line-out-of-range": { "$ref": "#/$defs/count" },
             "missing-path": { "$ref": "#/$defs/count" },
-            "missing-symbol": { "$ref": "#/$defs/count" }
+            "missing-symbol": { "$ref": "#/$defs/count" },
+            "unknown-selector": { "$ref": "#/$defs/count" }
           }
         }
       }
@@ -122,7 +123,7 @@
       "additionalProperties": false,
       "required": ["kind", "origin", "citation"],
       "properties": {
-        "kind": { "enum": ["line-moved", "line-out-of-range", "missing-path", "missing-symbol"] },
+        "kind": { "enum": ["line-moved", "line-out-of-range", "missing-path", "missing-symbol", "unknown-selector"] },
         "origin": { "$ref": "#/$defs/origin" },
         "citation": { "$ref": "#/$defs/citation" },
         "lineCount": { "$ref": "#/$defs/count" },

package/schemas/runtime/hook-debt-checkpoint.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archctx.repoharness.com/schemas/runtime/hook-debt-checkpoint.schema.json",
+  "title": "ArchitectureDebtHookCheckpointV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "debt",
+    "hookLog"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "archcontext.hook-debt-checkpoint/v1"
+    },
+    "debt": {
+      "$ref": "architecture-debt.schema.json"
+    },
+    "hookLog": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "event",
+        "elapsedMs",
+        "pathCount",
+        "changedPathDigest",
+        "reasonCode",
+        "failOpen",
+        "egress",
+        "network"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "archcontext.hook-log/v1"
+        },
+        "event": {
+          "type": "string",
+          "minLength": 1
+        },
+        "elapsedMs": {
+          "type": "number",
+          "minimum": 0
+        },
+        "pathCount": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "changedPathDigest": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "reasonCode": {
+          "type": "string",
+          "minLength": 1
+        },
+        "failOpen": {
+          "const": false
+        },
+        "egress": {
+          "const": "none"
+        },
+        "network": {
+          "const": "forbidden"
+        }
+      }
+    }
+  }
+}