archctx-contracts 0.6.3 → 0.7.1

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

@@ -0,0 +1,116 @@
+{
+  "$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.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "ownershipRule", "filter", "capabilities", "matrix", "imports", "calls", "edges", "worktree", "privacy"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.capability-dependencies/v1" },
+    "ownershipRule": { "const": "parent-chain" },
+    "filter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from", "into"],
+      "properties": {
+        "from": { "type": ["string", "null"] },
+        "into": { "type": ["string", "null"] }
+      }
+    },
+    "capabilities": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "matrix": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["from", "to", "imports", "calls"],
+        "properties": {
+          "from": { "type": "string", "minLength": 1 },
+          "to": { "type": "string", "minLength": 1 },
+          "imports": { "type": "integer", "minimum": 1 },
+          "calls": { "type": "null" }
+        }
+      }
+    },
+    "imports": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["coverage", "reasonCodes", "truncated", "importNodeCount", "importNodeLimit", "importNodeLimitExceeded", "edgeCount", "unresolvedCount", "unattributed"],
+      "properties": {
+        "coverage": { "enum": ["complete", "partial", "unknown"] },
+        "reasonCodes": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "enum": ["code-facts-import-limit", "code-facts-stale", "code-facts-truncated", "code-facts-unavailable"] }
+        },
+        "truncated": { "type": "boolean" },
+        "importNodeCount": { "type": ["integer", "null"], "minimum": 0 },
+        "importNodeLimit": { "type": "integer", "minimum": 1 },
+        "importNodeLimitExceeded": { "type": "boolean" },
+        "edgeCount": { "type": "integer", "minimum": 0 },
+        "unresolvedCount": { "type": "integer", "minimum": 0 },
+        "unattributed": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["unownedEndpoint", "contestedEndpoint", "noCapabilityEndpoint"],
+          "properties": {
+            "unownedEndpoint": { "type": "integer", "minimum": 0 },
+            "contestedEndpoint": { "type": "integer", "minimum": 0 },
+            "noCapabilityEndpoint": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "calls": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["coverage", "reasonCodes"],
+      "properties": {
+        "coverage": { "const": "unknown" },
+        "reasonCodes": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "const": "call-edges-not-exposed" } }
+      }
+    },
+    "edges": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["limit", "count", "omittedCount", "items"],
+      "properties": {
+        "limit": { "type": "integer", "minimum": 0 },
+        "count": { "type": "integer", "minimum": 0 },
+        "omittedCount": { "type": "integer", "minimum": 0 },
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["fromPath", "toPath", "fromCapability", "toCapability"],
+            "properties": {
+              "fromPath": { "type": "string", "minLength": 1 },
+              "toPath": { "type": "string", "minLength": 1 },
+              "fromCapability": { "type": "string", "minLength": 1 },
+              "toCapability": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "worktree": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["headSha", "worktreeDigest"],
+      "properties": {
+        "headSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "worktreeDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+      }
+    },
+    "privacy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["writes"],
+      "properties": {
+        "writes": { "const": "none" }
+      }
+    }
+  }
+}

package/schemas/runtime/changeset.schema.json

@@ -108,24 +108,50 @@
               "projectionFiles": {
                 "type": "array",
                 "items": {
-                  "type": "object",
-                  "additionalProperties": false,
-                  "required": [
-                    "path",
-                    "expectedHash",
-                    "body"
-                  ],
-                  "properties": {
-                    "path": {
-                      "type": "string"
-                    },
-                    "expectedHash": {
-                      "type": "string"
+                  "oneOf": [
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": [
+                        "path",
+                        "expectedHash",
+                        "body"
+                      ],
+                      "properties": {
+                        "path": {
+                          "type": "string"
+                        },
+                        "expectedHash": {
+                          "type": "string"
+                        },
+                        "body": {
+                          "type": "string"
+                        }
+                      }
                     },
-                    "body": {
-                      "type": "string"
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "description": "Removes one projection-owned file; accepted only by render_projection with the exact current body hash.",
+                      "required": [
+                        "path",
+                        "expectedHash",
+                        "delete"
+                      ],
+                      "properties": {
+                        "path": {
+                          "type": "string"
+                        },
+                        "expectedHash": {
+                          "type": "string",
+                          "pattern": "^sha256:[a-f0-9]{64}$"
+                        },
+                        "delete": {
+                          "const": true
+                        }
+                      }
                     }
-                  }
+                  ]
                 }
               }
             }

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

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/docs-anchors.schema.json",
+  "title": "DocsAnchorsReportV1",
+  "description": "Read-only result of `archctx docs anchors`: stale citations in human-owned module document regions and node prose. A signal, not a gate.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "profile", "codeGraph", "summary", "nodes"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.docs-anchors/v1" },
+    "profile": { "enum": ["default", "repo-harness/v1"] },
+    "codeGraph": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["availability"],
+          "properties": { "availability": { "const": "ready" } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["availability", "reasonCode"],
+          "properties": {
+            "availability": { "const": "unavailable" },
+            "reasonCode": { "enum": ["index-missing", "index-open-failed"] }
+          }
+        }
+      ]
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodes", "documents", "citations", "findings", "unchecked", "byKind"],
+      "properties": {
+        "nodes": { "$ref": "#/$defs/count" },
+        "documents": { "$ref": "#/$defs/count" },
+        "citations": { "$ref": "#/$defs/count" },
+        "findings": { "$ref": "#/$defs/count" },
+        "unchecked": { "$ref": "#/$defs/count" },
+        "byKind": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["line-moved", "line-out-of-range", "missing-path", "missing-symbol"],
+          "properties": {
+            "line-moved": { "$ref": "#/$defs/count" },
+            "line-out-of-range": { "$ref": "#/$defs/count" },
+            "missing-path": { "$ref": "#/$defs/count" },
+            "missing-symbol": { "$ref": "#/$defs/count" }
+          }
+        }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["nodeId", "citationCount", "findings", "unchecked"],
+        "properties": {
+          "nodeId": { "type": "string", "minLength": 1 },
+          "documentPath": { "$ref": "#/$defs/repoPath" },
+          "citationCount": { "type": "integer", "minimum": 1 },
+          "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } },
+          "unchecked": { "type": "array", "items": { "$ref": "#/$defs/unchecked" } }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "count": { "type": "integer", "minimum": 0 },
+    "line": { "type": "integer", "minimum": 1 },
+    "repoPath": {
+      "type": "string",
+      "minLength": 1,
+      "not": { "anyOf": [{ "pattern": "^/" }, { "pattern": "\\\\" }, { "pattern": "(^|/)\\.\\.(/|$)" }] }
+    },
+    "origin": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "path", "line"],
+          "properties": {
+            "kind": { "const": "document" },
+            "path": { "$ref": "#/$defs/repoPath" },
+            "line": { "$ref": "#/$defs/line" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind"],
+          "properties": { "kind": { "const": "node-summary" } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "index"],
+          "properties": {
+            "kind": { "const": "node-responsibility" },
+            "index": { "type": "integer", "minimum": 0 }
+          }
+        }
+      ]
+    },
+    "citation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["text"],
+      "properties": {
+        "text": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "minLength": 1 },
+        "resolvedPath": { "$ref": "#/$defs/repoPath" },
+        "line": { "$ref": "#/$defs/line" },
+        "endLine": { "$ref": "#/$defs/line" },
+        "symbol": { "type": "string", "minLength": 1 }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "origin", "citation"],
+      "properties": {
+        "kind": { "enum": ["line-moved", "line-out-of-range", "missing-path", "missing-symbol"] },
+        "origin": { "$ref": "#/$defs/origin" },
+        "citation": { "$ref": "#/$defs/citation" },
+        "lineCount": { "$ref": "#/$defs/count" },
+        "currentLines": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/line" } }
+      }
+    },
+    "unchecked": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reasonCode", "origin", "citation"],
+      "properties": {
+        "reasonCode": { "enum": ["codegraph-unavailable", "language-unsupported", "path-ambiguous"] },
+        "origin": { "$ref": "#/$defs/origin" },
+        "citation": { "$ref": "#/$defs/citation" }
+      }
+    }
+  }
+}

package/schemas/runtime/flow-selector-check.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/flow-selector-check.schema.json",
+  "title": "ArchitectureFlowSelectorCheckV1",
+  "description": "The data of `archctx flows check`: the P2 flow proof of every capability that declares a flow, and the proof status of every declared entrypoint-to-sink selector, computed without rendering. Consumers detect it through the flow-selector-check-v1 capability.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "ok", "codeGraph", "summary", "selectors", "capabilities"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.flow-selector-check/v1" },
+    "ok": { "type": "boolean", "description": "True when no capability that declares a flow has an unprovable P2 proof." },
+    "codeGraph": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["availability", "version"],
+      "properties": {
+        "availability": { "enum": ["ready", "unavailable"] },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["selectors", "proven", "unproven", "usedUnproven"],
+      "properties": {
+        "selectors": { "type": "integer", "minimum": 0 },
+        "proven": { "type": "integer", "minimum": 0 },
+        "unproven": { "type": "integer", "minimum": 0 },
+        "usedUnproven": { "type": "integer", "minimum": 0, "description": "Unproven selectors that a required-flow step names." }
+      }
+    },
+    "selectors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["nodeId", "entrypointId", "sourcePath", "sourceSymbol", "sinkId", "sinkPath", "sinkSymbol", "status", "callSites", "referenceSites", "rejectedBuiltinCallSites", "flowSteps"],
+        "properties": {
+          "nodeId": { "type": "string", "minLength": 1 },
+          "entrypointId": { "type": "string", "minLength": 1 },
+          "sourcePath": { "type": "string", "minLength": 1 },
+          "sourceSymbol": { "type": "string", "minLength": 1 },
+          "sinkId": { "type": "string", "minLength": 1 },
+          "sinkPath": { "type": "string", "minLength": 1 },
+          "sinkSymbol": { "type": "string", "minLength": 1 },
+          "status": {
+            "enum": ["ambiguous-symbol", "evidence-missing", "evidence-truncated", "false-builtin-call", "no-direct-call", "only-references", "proven"],
+            "description": "Only proven binds a flow step."
+          },
+          "callSites": { "$ref": "#/$defs/sites" },
+          "referenceSites": { "$ref": "#/$defs/sites" },
+          "rejectedBuiltinCallSites": { "$ref": "#/$defs/sites" },
+          "flowSteps": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["flowId", "stepId"],
+              "properties": {
+                "flowId": { "type": "string", "minLength": 1 },
+                "stepId": { "type": "string", "minLength": 1 }
+              }
+            }
+          }
+        }
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["capabilityId", "p2Status", "diagnostics"],
+        "properties": {
+          "capabilityId": { "type": "string", "minLength": 1 },
+          "p2Status": { "enum": ["not-applicable", "proven", "unprovable"] },
+          "diagnostics": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["code", "detail"],
+              "properties": {
+                "code": { "type": "string", "minLength": 1 },
+                "flowId": { "type": "string", "minLength": 1 },
+                "stepId": { "type": "string", "minLength": 1 },
+                "detail": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "sites": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "line": { "type": "integer", "minimum": 1 }
+        }
+      }
+    }
+  }
+}