archctx-contracts 0.3.0 → 0.4.1

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

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/projection-request.schema.json",
+  "title": "ProjectionRequestV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "requestId", "profile", "mode", "targets", "changedPaths", "expected"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.projection-request/v1" },
+    "requestId": { "type": "string", "pattern": "^[a-zA-Z0-9_.:-]+$", "minLength": 1 },
+    "profile": { "const": "repo-harness/v1" },
+    "mode": { "enum": ["check", "plan", "apply", "adopt"] },
+    "targets": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "description": "Canonical wire order is lexicographic and is enforced by projectionRequestInvariantIssues.",
+      "items": { "enum": ["agent-context", "architecture-docs"] }
+    },
+    "changedPaths": {
+      "type": "array",
+      "uniqueItems": true,
+      "description": "Canonical wire order is lexicographic and is enforced by projectionRequestInvariantIssues.",
+      "items": { "$ref": "#/$defs/repoPath" }
+    },
+    "expected": { "$ref": "#/$defs/expectedSnapshot" },
+    "adoptionPlanId": { "type": "string", "pattern": "^adoption_plan\\.[a-zA-Z0-9_.-]+$" },
+    "acceptedChange": { "$ref": "#/$defs/acceptedChange" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "mode": { "const": "adopt" } }, "required": ["mode"] },
+      "then": { "required": ["adoptionPlanId"] },
+      "else": { "not": { "required": ["adoptionPlanId"] } }
+    }
+  ],
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "repoPath": {
+      "type": "string",
+      "minLength": 1,
+      "not": {
+        "anyOf": [
+          { "pattern": "^/" },
+          { "pattern": "\\\\" },
+          { "pattern": "(^|/)\\.\\.(/|$)" }
+        ]
+      }
+    },
+    "acceptedChange": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["changeSetId", "eventId", "reasonCodes", "affectedNodeIds"],
+      "properties": {
+        "changeSetId": { "type": "string", "minLength": 1 },
+        "eventId": { "type": "string", "minLength": 1 },
+        "reasonCodes": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "Canonical wire order is lexicographic and is enforced by projectionRequestInvariantIssues.",
+          "items": {
+            "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"
+            ]
+          }
+        },
+        "affectedNodeIds": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "Canonical wire order is lexicographic and is enforced by projectionRequestInvariantIssues.",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "expectedSnapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repositoryId", "workspaceId", "headSha", "worktreeDigest"],
+      "properties": {
+        "repositoryId": { "type": "string", "minLength": 1 },
+        "workspaceId": { "type": "string", "minLength": 1 },
+        "headSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "worktreeDigest": { "$ref": "#/$defs/digest" }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,162 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://archcontext.dev/schemas/runtime/projection-result.schema.json",
+  "title": "ProjectionResultV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "requestId", "status", "inputSnapshot", "outputSnapshot", "affectedNodeIds", "files", "humanActions", "refreshSignals", "receiptDigest"],
+  "properties": {
+    "schemaVersion": { "const": "archcontext.projection-result/v1" },
+    "requestId": { "type": "string", "pattern": "^[a-zA-Z0-9_.:-]+$", "minLength": 1 },
+    "status": { "enum": ["adoption-required", "applied", "blocked", "human-action-required", "noop", "permanent-failure", "planned", "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 } },
+    "files": { "type": "array", "description": "Canonical wire order is by path and is enforced by projectionResultInvariantIssues.", "items": { "$ref": "#/$defs/file" } },
+    "humanActions": { "type": "array", "items": { "$ref": "#/$defs/humanAction" } },
+    "refreshSignals": { "type": "array", "description": "Canonical wire order is by signalId and cross-object receipt/snapshot bindings are enforced by projectionResultInvariantIssues.", "items": { "$ref": "#/$defs/refreshSignal" } },
+    "receiptDigest": { "$ref": "#/$defs/digest" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "enum": ["adoption-required", "human-action-required"] } }, "required": ["status"] },
+      "then": { "properties": { "humanActions": { "minItems": 1 } } },
+      "else": { "properties": { "humanActions": { "maxItems": 0 } } }
+    }
+  ],
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "nullableDigest": { "type": ["string", "null"], "pattern": "^sha256:[a-f0-9]{64}$" },
+    "snapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repositoryId", "workspaceId", "headSha", "baseHeadSha", "worktreeDigest", "sourceTreeDigest", "modelDigest", "codeGraphDigest", "indexedWorktreeDigest", "projectionInputDigest", "rendererVersion", "layoutVersion", "generatedFrom"],
+      "properties": {
+        "repositoryId": { "type": "string", "minLength": 1 },
+        "workspaceId": { "type": "string", "minLength": 1 },
+        "headSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "baseHeadSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "worktreeDigest": { "$ref": "#/$defs/digest" },
+        "sourceTreeDigest": { "$ref": "#/$defs/digest" },
+        "modelDigest": { "$ref": "#/$defs/digest" },
+        "codeGraphDigest": { "$ref": "#/$defs/digest" },
+        "indexedWorktreeDigest": { "$ref": "#/$defs/nullableDigest" },
+        "projectionInputDigest": { "$ref": "#/$defs/digest" },
+        "rendererVersion": { "const": "archcontext.docs-renderer/v2" },
+        "layoutVersion": { "const": "archcontext.docs-layout/v1" },
+        "generatedFrom": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["codeGraphPackage", "codeGraphVersion", "codeGraphBinaryDigest", "codeGraphStatus"],
+          "properties": {
+            "codeGraphPackage": { "const": "@colbymchenry/codegraph" },
+            "codeGraphVersion": { "const": "1.5.0" },
+            "codeGraphBinaryDigest": { "$ref": "#/$defs/digest" },
+            "codeGraphStatus": { "enum": ["ready", "unavailable"] }
+          }
+        }
+      }
+    },
+    "file": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "action", "preimageDigest", "outputDigest"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "not": { "anyOf": [{ "pattern": "^/" }, { "pattern": "\\\\" }, { "pattern": "(^|/)\\.\\.(/|$)" }] }
+        },
+        "action": { "enum": ["create", "delete", "unchanged", "update"] },
+        "preimageDigest": { "$ref": "#/$defs/nullableDigest" },
+        "outputDigest": { "$ref": "#/$defs/nullableDigest" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "action": { "const": "create" } }, "required": ["action"] },
+          "then": { "properties": { "preimageDigest": { "const": null }, "outputDigest": { "$ref": "#/$defs/digest" } } }
+        },
+        {
+          "if": { "properties": { "action": { "const": "delete" } }, "required": ["action"] },
+          "then": { "properties": { "preimageDigest": { "$ref": "#/$defs/digest" }, "outputDigest": { "const": null } } }
+        },
+        {
+          "if": { "properties": { "action": { "enum": ["unchanged", "update"] } }, "required": ["action"] },
+          "then": { "properties": { "preimageDigest": { "$ref": "#/$defs/digest" }, "outputDigest": { "$ref": "#/$defs/digest" } } }
+        }
+      ]
+    },
+    "humanAction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reasonCode", "affectedNodeIds", "requestPayloadDigest"],
+      "properties": {
+        "reasonCode": { "enum": ["adoption-required", "manual-region-conflict", "target-collision", "unprovable-required-flow", "unresolved-major-change"] },
+        "affectedNodeIds": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "requestPayloadDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "digestSet": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["modelDigest", "sourceTreeDigest", "flowProofDigest", "projectionDigest"],
+      "properties": {
+        "modelDigest": { "$ref": "#/$defs/digest" },
+        "sourceTreeDigest": { "$ref": "#/$defs/digest" },
+        "flowProofDigest": { "$ref": "#/$defs/digest" },
+        "projectionDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "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"]
+    },
+    "refreshSignal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "signalId", "idempotencyKey", "mode", "repository", "worktree", "cause", "reasonCodes", "affectedNodeIds", "refreshTargets", "baseDigests", "resultingDigests", "projectionReceiptDigest"],
+      "properties": {
+        "schemaVersion": { "const": "archcontext.architecture-refresh-signal/v1" },
+        "signalId": { "$ref": "#/$defs/digest" },
+        "idempotencyKey": { "$ref": "#/$defs/digest" },
+        "mode": { "enum": ["human-action-required", "refresh-required"] },
+        "repository": { "type": "object", "additionalProperties": false, "required": ["repositoryId"], "properties": { "repositoryId": { "type": "string", "minLength": 1 } } },
+        "worktree": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["workspaceId", "headSha", "worktreeDigest"],
+          "properties": {
+            "workspaceId": { "type": "string", "minLength": 1 },
+            "headSha": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+            "worktreeDigest": { "$ref": "#/$defs/digest" }
+          }
+        },
+        "cause": { "enum": ["accepted-semantic-delta", "unresolved-major-candidate", "verified-flow-proof-delta"] },
+        "acceptedChange": { "$ref": "#/$defs/acceptedChange" },
+        "reasonCodes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/reasonCode" } },
+        "affectedNodeIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "refreshTargets": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["architecture-contract-context", "architecture-readiness", "architecture-request-index", "capability-context", "capability-index"] } },
+        "baseDigests": { "$ref": "#/$defs/digestSet" },
+        "resultingDigests": { "$ref": "#/$defs/digestSet" },
+        "projectionReceiptDigest": { "$ref": "#/$defs/digest" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "cause": { "const": "unresolved-major-candidate" } }, "required": ["cause"] },
+          "then": { "properties": { "mode": { "const": "human-action-required" } }, "not": { "required": ["acceptedChange"] } },
+          "else": { "properties": { "mode": { "const": "refresh-required" } }, "required": ["acceptedChange"] }
+        }
+      ]
+    },
+    "acceptedChange": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["changeSetId", "eventId", "reasonCodes", "affectedNodeIds"],
+      "properties": {
+        "changeSetId": { "type": "string", "minLength": 1 },
+        "eventId": { "type": "string", "minLength": 1 },
+        "reasonCodes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/reasonCode" } },
+        "affectedNodeIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+      }
+    }
+  }
+}

package/src/architecture.ts

@@ -0,0 +1,73 @@
+export interface ArchitectureSinkSelectorV2 {
+  id: string;
+  path: string;
+  symbol: string;
+}
+
+export interface ArchitectureEntrypointSymbolV2 {
+  name: string;
+  sinks: ArchitectureSinkSelectorV2[];
+}
+
+export interface ArchitectureEntrypointV2 {
+  id: string;
+  path: string;
+  symbols: ArchitectureEntrypointSymbolV2[];
+}
+
+export interface ArchitectureNodeSourceV2 {
+  include?: string[];
+  exclude?: string[];
+  entrypoints?: ArchitectureEntrypointV2[];
+}
+
+export interface ArchitectureFlowEvidenceSelectorV1 {
+  entrypointId: string;
+  sourceSymbol: string;
+  sinkId: string;
+}
+
+export interface ArchitectureFlowParticipantV1 {
+  id: string;
+  nodeId: string;
+}
+
+export interface ArchitectureFlowStepV1 {
+  id: string;
+  from: string;
+  to: string;
+  label: string;
+  evidence: ArchitectureFlowEvidenceSelectorV1;
+}
+
+export interface ArchitectureFlowOutcomeV1 {
+  id: string;
+  kind: "success" | "error";
+  label: string;
+  steps: ArchitectureFlowStepV1[];
+  terminal: {
+    participant: string;
+    label: string;
+  };
+}
+
+export type ArchitectureFlowV1 = ArchitectureRequiredFlowV1 | ArchitectureNotApplicableFlowV1;
+
+interface ArchitectureFlowBaseV1 {
+  schemaVersion: "archcontext.flow/v1";
+  id: string;
+  capabilityId: string;
+  name: string;
+}
+
+export interface ArchitectureRequiredFlowV1 extends ArchitectureFlowBaseV1 {
+  applicability: "required";
+  participants: ArchitectureFlowParticipantV1[];
+  steps: ArchitectureFlowStepV1[];
+  outcomes: ArchitectureFlowOutcomeV1[];
+}
+
+export interface ArchitectureNotApplicableFlowV1 extends ArchitectureFlowBaseV1 {
+  applicability: "not-applicable";
+  rationale: string;
+}

package/src/index.ts

@@ -1,9 +1,11 @@
 export * from "./control-plane-routes";
+export * from "./architecture";
 export * from "./external-docs";
 export * from "./github-governance";
 export * from "./ledger";
 export * from "./ports";
 export * from "./practices";
+export * from "./projection";
 export * from "./product-version";
 export * from "./schema";
 export * from "./validator";

package/src/product-version.ts

@@ -1,5 +1,5 @@
 export const ARCHCONTEXT_PRODUCT_NAME = "archctx";
-export const ARCHCONTEXT_PRODUCT_VERSION = "0.3.0";
+export const ARCHCONTEXT_PRODUCT_VERSION = "0.4.1";
 export const ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.3.10";
 export const ARCHCONTEXT_NODE_RANGE = ">=24 <26";
 export const LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1";
@@ -41,7 +41,7 @@ export interface ProductVersionManifest {
     sqliteMigrations: string;
     codeGraph: {
       packageName: "@colbymchenry/codegraph";
-      requiredVersion: "1.4.0";
+      requiredVersion: "1.5.0";
       adapter: "codegraph-cli";
     };
   };
@@ -100,7 +100,7 @@ export function productVersionManifest(): ProductVersionManifest {
       sqliteMigrations: "0001_runtime_state..0012_explorer_projection_index",
       codeGraph: {
         packageName: "@colbymchenry/codegraph",
-        requiredVersion: "1.4.0",
+        requiredVersion: "1.5.0",
         adapter: "codegraph-cli"
       }
     }