archctx-contracts 0.5.11 → 0.5.13

package/fixtures/valid/archctx-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "archcontext.capabilities/v1",
-  "package": { "name": "archctx", "version": "0.5.11" },
+  "package": { "name": "archctx", "version": "0.5.13" },
   "protocols": {
     "projectionRequest": "archcontext.projection-request/v1",
     "projectionResult": "archcontext.projection-result/v2",

package/fixtures/valid/product-version-manifest.json

@@ -2,7 +2,7 @@
   "schemaVersion": "archcontext.product-version-manifest/v1",
   "product": {
     "name": "archctx",
-    "version": "0.5.11",
+    "version": "0.5.13",
     "distribution": "one-package"
   },
   "packageManager": "bun@1.4.0",
@@ -12,25 +12,25 @@
   "surfaces": {
     "cli": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.5.11",
+      "version": "0.5.13",
       "entrypoint": "archctx"
     },
     "daemon": {
       "packageName": "@archcontext/local-runtime",
-      "version": "0.5.11",
+      "version": "0.5.13",
       "entrypoint": "archctx daemon start",
       "rpcSchemaVersion": "archcontext.runtime-rpc/v1"
     },
     "mcp": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.5.11",
+      "version": "0.5.13",
       "entrypoint": "archctx mcp",
       "transport": "stdio"
     }
   },
   "schemas": {
     "schemaSetVersion": "2026-06-25.al0-ledger",
-    "contractsPackageVersion": "0.5.11",
+    "contractsPackageVersion": "0.5.13",
     "reviewChallenge": "archcontext.review-challenge/v2",
     "attestation": "archcontext.attestation/v2",
     "deviceIdentity": "archcontext.device-identity/v1",

package/package.json

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

package/schemas/runtime/changeset.schema.json

@@ -4,62 +4,235 @@
   "title": "ChangeSet",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schemaVersion", "id", "status", "base", "reason", "operations", "preconditions", "postconditions", "requiresConfirmation", "idempotencyKey"],
+  "required": [
+    "schemaVersion",
+    "id",
+    "status",
+    "base",
+    "reason",
+    "operations",
+    "preconditions",
+    "postconditions",
+    "requiresConfirmation",
+    "idempotencyKey"
+  ],
   "properties": {
-    "schemaVersion": { "const": "archcontext.changeset/v1" },
-    "id": { "type": "string", "pattern": "^changeset\\.[a-zA-Z0-9_-]+$" },
-    "status": { "type": "string", "enum": ["proposed", "approved", "applied", "rolled-back", "rejected"] },
+    "schemaVersion": {
+      "const": "archcontext.changeset/v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^changeset\\.[a-zA-Z0-9_-]+$"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "proposed",
+        "approved",
+        "applied",
+        "rolled-back",
+        "rejected"
+      ]
+    },
     "base": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["headSha", "worktreeDigest", "modelDigest"],
+      "required": [
+        "headSha",
+        "worktreeDigest",
+        "modelDigest"
+      ],
       "properties": {
-        "headSha": { "type": "string" },
-        "worktreeDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
-        "modelDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+        "headSha": {
+          "type": "string"
+        },
+        "worktreeDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "modelDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        }
       }
     },
     "reason": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["taskSessionId"],
+      "required": [
+        "taskSessionId"
+      ],
       "properties": {
-        "taskSessionId": { "type": "string" },
-        "interventionId": { "type": "string" }
+        "taskSessionId": {
+          "type": "string"
+        },
+        "interventionId": {
+          "type": "string"
+        }
       }
     },
     "operations": {
       "type": "array",
       "minItems": 1,
       "items": {
-        "type": "object",
-        "additionalProperties": true,
-        "required": ["op", "expectedHash"],
-        "properties": {
-          "op": { "type": "string", "enum": ["create_entity", "update_entity_fields", "delete_entity", "write_policy", "write_waiver", "render_projection", "render_agent_context"] },
-          "entityId": { "type": "string" },
-          "path": { "type": "string" },
-          "expectedHash": { "type": "string" },
-          "projectionFiles": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": ["path", "expectedHash", "body"],
-              "properties": {
-                "path": { "type": "string" },
-                "expectedHash": { "type": "string" },
-                "body": { "type": "string" }
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": true,
+            "required": [
+              "op",
+              "expectedHash"
+            ],
+            "properties": {
+              "op": {
+                "type": "string",
+                "enum": [
+                  "create_entity",
+                  "update_entity_fields",
+                  "delete_entity",
+                  "write_policy",
+                  "write_waiver",
+                  "render_projection",
+                  "render_agent_context"
+                ]
+              },
+              "entityId": {
+                "type": "string"
+              },
+              "path": {
+                "type": "string"
+              },
+              "expectedHash": {
+                "type": "string"
+              },
+              "projectionFiles": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "path",
+                    "expectedHash",
+                    "body"
+                  ],
+                  "properties": {
+                    "path": {
+                      "type": "string"
+                    },
+                    "expectedHash": {
+                      "type": "string"
+                    },
+                    "body": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "op",
+              "path",
+              "expectedHash",
+              "fields"
+            ],
+            "properties": {
+              "op": {
+                "const": "update_manifest_fields"
+              },
+              "path": {
+                "const": ".archcontext/manifest.yaml"
+              },
+              "expectedHash": {
+                "type": "string",
+                "pattern": "^sha256:[a-f0-9]{64}$"
+              },
+              "fields": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "content.decisions"
+                ],
+                "properties": {
+                  "content.decisions": {
+                    "const": "docs/adr"
+                  }
+                }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "op",
+              "path",
+              "expectedHash",
+              "references"
+            ],
+            "properties": {
+              "op": {
+                "const": "update_adr_references"
+              },
+              "path": {
+                "type": "string",
+                "pattern": "^docs/adr/ADR-[0-9]{4}-[a-z0-9][a-z0-9-]*\\.md$"
+              },
+              "expectedHash": {
+                "type": "string",
+                "pattern": "^sha256:[a-f0-9]{64}$"
+              },
+              "references": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "from",
+                    "to"
+                  ],
+                  "properties": {
+                    "from": {
+                      "type": "string",
+                      "pattern": "^[a-z0-9][a-z0-9._-]{2,127}$"
+                    },
+                    "to": {
+                      "type": "string",
+                      "pattern": "^[a-z0-9][a-z0-9._-]{2,127}$"
+                    }
+                  }
+                }
               }
             }
           }
-        }
+        ]
       }
     },
-    "preconditions": { "type": "array", "items": { "type": "string" } },
-    "postconditions": { "type": "array", "items": { "type": "string" } },
-    "requiresConfirmation": { "type": "boolean" },
-    "idempotencyKey": { "type": "string" },
-    "extensions": { "type": "object", "additionalProperties": true }
+    "preconditions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "postconditions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "requiresConfirmation": {
+      "type": "boolean"
+    },
+    "idempotencyKey": {
+      "type": "string"
+    },
+    "extensions": {
+      "type": "object",
+      "additionalProperties": true
+    }
   }
 }

package/src/architecture.ts

@@ -71,3 +71,82 @@ export interface ArchitectureNotApplicableFlowV1 extends ArchitectureFlowBaseV1
   applicability: "not-applicable";
   rationale: string;
 }
+
+/**
+ * A `forbid-dependency` constraint (`archcontext.constraint/v1`), narrowed to the fields the
+ * dependency gate evaluates. A file owned by a `scope.nodes` node (or a descendant) must not
+ * import a file owned by a `rule.targets` node (or a descendant). v1 has no `allowedVia` escape.
+ */
+export interface DependencyConstraintV1 {
+  id: string;
+  severity: "error" | "warning";
+  scope: { nodes: string[] };
+  rule: { type: "forbid-dependency"; targets: string[] };
+  rationale: string;
+}
+
+export const DEPENDENCY_CONSTRAINT_STATUSES = ["not-applicable", "pass", "undetermined", "violated"] as const;
+export type DependencyConstraintStatus = (typeof DEPENDENCY_CONSTRAINT_STATUSES)[number];
+
+/**
+ * Why a dependency result is not a complete observation: no index answered, the index attested
+ * to a different worktree, the import dump hit its limit, a constrained file carries a
+ * repository-local import that resolved to no file, or the workspace package map could not be
+ * read, so no bare workspace specifier could be resolved.
+ */
+export const DEPENDENCY_CONSTRAINT_REASON_CODES = [
+  "code-facts-stale",
+  "code-facts-truncated",
+  "code-facts-unavailable",
+  "unresolved-import",
+  "workspace-resolution-failed"
+] as const;
+export type DependencyConstraintReasonCode = (typeof DEPENDENCY_CONSTRAINT_REASON_CODES)[number];
+
+export interface DependencyConstraintViolationV1 {
+  constraintId: string;
+  fromPath: string;
+  toPath: string;
+  fromNode: string;
+  toNode: string;
+  severity: "error" | "warning";
+}
+
+export interface DependencyConstraintEvaluationV1 {
+  schemaVersion: "archcontext.dependency-constraint-evaluation/v1";
+  status: DependencyConstraintStatus;
+  /** `complete` only when an index attested to the evaluated worktree and was not truncated. */
+  coverage: "complete" | "partial" | "unknown";
+  reasonCodes: DependencyConstraintReasonCode[];
+  constraintIds: string[];
+  /** Import observations the evaluation read; zero when the index did not attest to this tree. */
+  importEdgeCount: number;
+  /** Repository-local specifiers from constrained files that resolved to no file. */
+  unresolvedImports: { from: string; specifier: string }[];
+  violations: DependencyConstraintViolationV1[];
+}
+
+/**
+ * The closed `failOn` vocabulary of `.archcontext/policies/review.yaml`. A review finding in one
+ * of these categories blocks only when its category is listed; findings outside the vocabulary
+ * are never affected by the policy.
+ */
+export const REVIEW_FAIL_ON_CATEGORIES = [
+  "incomplete-intervention",
+  "invalid-schema",
+  "prohibited-dependency",
+  "stale-context",
+  "unjustified-compatibility"
+] as const;
+export type ReviewFailOnCategory = (typeof REVIEW_FAIL_ON_CATEGORIES)[number];
+
+/**
+ * The effective review policy. An error in a category missing from `failOn` is downgraded to a
+ * warning, with one exception: the task-snapshot HEAD-mismatch `stale-context` finding always stays
+ * an error, because a stale snapshot skips every other review gate.
+ */
+export interface ReviewPolicyV1 {
+  failOn: ReviewFailOnCategory[];
+  /** `default` when the policy file is missing or invalid in any way: every category blocks. */
+  source: "policy-file" | "default";
+}

package/src/ports.ts

@@ -140,13 +140,38 @@ export interface LocalStorePort {
   saveReviewResult(reviewId: string, result: unknown): Promise<void>;
 }
 
+export interface ModelValidationResult {
+  valid: boolean;
+  errors: string[];
+  /**
+   * The subset of `errors` that are cross-file references resolving to nothing, such as an ADR
+   * `appliesTo` id with no node. Omitted when empty.
+   */
+  referenceErrors?: string[];
+  /** Problems that do not invalidate the model, such as an ignored legacy setting. Omitted when empty. */
+  warnings?: string[];
+  modelDigest: string;
+}
+
 export interface ModelStorePort {
   loadManifest(workspace: WorkspaceRef): Promise<unknown>;
   loadModel(workspace: WorkspaceRef): Promise<unknown[]>;
-  validateModel(workspace: WorkspaceRef): Promise<{ valid: boolean; errors: string[]; modelDigest: string }>;
+  validateModel(workspace: WorkspaceRef): Promise<ModelValidationResult>;
   writeChangeSetPreview(changeSet: unknown): Promise<{ digest: string; summary: string }>;
 }
 
+/**
+ * Errors that make a model unusable as the base of a write. Dangling references are excluded so
+ * that a change repairing them (for example restoring a deleted node) is not blocked; the
+ * after-apply model is still validated in full.
+ */
+export function baseModelBlockingErrors(result: ModelValidationResult): string[] {
+  if (result.valid) return [];
+  if (result.errors.length === 0) return ["unknown validation error"];
+  const references = new Set(result.referenceErrors ?? []);
+  return result.errors.filter((error) => !references.has(error));
+}
+
 export interface PolicyPort {
   evaluateChangeSet(changeSet: unknown): Promise<{ allowed: boolean; violations: string[] }>;
   evaluateReview(input: unknown): Promise<{ result: "pass" | "fail"; findings: unknown[] }>;
@@ -750,3 +775,66 @@ export interface ChatGptGaToolContract {
   requiresLocalConfirmationForWrite: boolean;
   disclosure: string;
 }
+
+export type DetachedReviewWorktreeReason =
+  | "HEAD_UNAVAILABLE"
+  | "HEAD_SHA_MISMATCH"
+  | "TREE_OID_MISMATCH"
+  | "WORKTREE_NOT_DETACHED"
+  | "WORKTREE_NOT_CLEAN";
+
+export interface DetachedReviewWorktreeVerification {
+  schemaVersion: "archcontext.detached-review-worktree-verification/v1";
+  accepted: boolean;
+  reasonCode?: DetachedReviewWorktreeReason;
+  expected: {
+    headSha: string;
+    headTreeOid?: string;
+  };
+  observed: {
+    headSha?: string;
+    headTreeOid?: string;
+    detached?: boolean;
+    clean?: boolean;
+  };
+}
+
+
+export interface ReviewCheckoutGitPort {
+  findRepositoryRoot(start: string): string;
+  readOriginUrl(root: string): string | null;
+  verifyDetachedWorktree(input: {
+    worktreeRoot: string;
+    expectedHeadSha: string;
+    expectedHeadTreeOid?: string;
+  }): DetachedReviewWorktreeVerification;
+}
+
+export interface NonLocalEgressChannel {
+  channel: "context7" | "agent-audit" | "github-issue-publishing" | "npm-update-check" | "codegraph-telemetry";
+  destination: string;
+  trigger: string;
+  data: string;
+  status: "enabled" | "declared-awaiting-user-consent" | "blocked-by-policy";
+}
+
+export interface LocalEgressReport {
+  ok: boolean;
+  policyMode: "configured" | "local-only";
+  enforcement: "application-admission";
+  defaultOutbound: "local-only";
+  effectiveOutbound: "local-only" | "non-local";
+  nonLocalEgress: NonLocalEgressChannel[];
+  cloudContentUpload: "deny";
+  secureMcpTunnel: "disabled-by-default";
+  thirdPartyTelemetry: "disabled" | "not-disabled-by-env";
+  codeGraph: {
+    provider: "codegraph";
+    telemetry: "disabled" | "not-disabled-by-env";
+    envVar: string;
+    configuredValue: string | null;
+    effectiveValue: string;
+    source: "archcontext-default" | "environment";
+  };
+  warnings: string[];
+}

package/src/product-version.ts

@@ -1,5 +1,5 @@
 export const ARCHCONTEXT_PRODUCT_NAME = "archctx";
-export const ARCHCONTEXT_PRODUCT_VERSION = "0.5.11";
+export const ARCHCONTEXT_PRODUCT_VERSION = "0.5.13";
 export const ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.0";
 export const ARCHCONTEXT_NODE_RANGE = ">=22.22 <26";
 export const LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1";