archctx-contracts 0.4.4 → 0.4.6

package/fixtures/valid/archctx-capabilities.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": "archcontext.capabilities/v1",
-  "package": { "name": "archctx", "version": "0.4.4" },
+  "package": { "name": "archctx", "version": "0.4.6" },
   "protocols": {
     "projectionRequest": "archcontext.projection-request/v1",
-    "projectionResult": "archcontext.projection-result/v1",
+    "projectionResult": "archcontext.projection-result/v2",
     "architectureRefreshSignal": "archcontext.architecture-refresh-signal/v1"
   },
   "renderers": {
     "architectureDocs": "archcontext.docs-renderer/v4",
     "agentContext": "archcontext.agent-context-renderer/v1"
   },
-  "features": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "projection-protocol-v1"]
+  "features": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "projection-apply-receipt-v1", "projection-protocol-v2"]
 }

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

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

package/fixtures/valid/projection-result.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "archcontext.projection-result/v1",
+  "schemaVersion": "archcontext.projection-result/v2",
   "requestId": "projection_request.repo_main",
   "status": "applied",
   "inputSnapshot": {
@@ -43,5 +43,5 @@
   ],
   "humanActions": [],
   "refreshSignals": [],
-  "receiptDigest": "sha256:ba5f380502a07529a40febb353a6790fbeb950cad06bfe6c0331e3f9d35907bf"
+  "receiptDigest": "sha256:6adef4b3486194b61e1851fdd5c1c352de374e10011beb9a38ec845ee91ff702"
 }

package/package.json

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

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

@@ -22,7 +22,7 @@
       "required": ["projectionRequest", "projectionResult", "architectureRefreshSignal"],
       "properties": {
         "projectionRequest": { "const": "archcontext.projection-request/v1" },
-        "projectionResult": { "const": "archcontext.projection-result/v1" },
+        "projectionResult": { "const": "archcontext.projection-result/v2" },
         "architectureRefreshSignal": { "const": "archcontext.architecture-refresh-signal/v1" }
       }
     },
@@ -39,7 +39,7 @@
       "type": "array",
       "minItems": 3,
       "uniqueItems": true,
-      "items": { "enum": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "projection-protocol-v1"] }
+      "items": { "enum": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "projection-apply-receipt-v1", "projection-protocol-v2"] }
     }
   }
 }

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

@@ -1,20 +1,21 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://archcontext.dev/schemas/runtime/projection-result.schema.json",
-  "title": "ProjectionResultV1",
+  "title": "ProjectionResultV2",
   "type": "object",
   "additionalProperties": false,
   "required": ["schemaVersion", "requestId", "status", "inputSnapshot", "outputSnapshot", "affectedNodeIds", "files", "humanActions", "refreshSignals", "receiptDigest"],
   "properties": {
-    "schemaVersion": { "const": "archcontext.projection-result/v1" },
+    "schemaVersion": { "const": "archcontext.projection-result/v2" },
     "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"] },
+    "status": { "enum": ["adoption-required", "applied", "applied-reconcile-required", "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" } },
+    "applyReceipt": { "$ref": "#/$defs/applyIdentity" },
     "receiptDigest": { "$ref": "#/$defs/digest" }
   },
   "allOf": [
@@ -22,6 +23,13 @@
       "if": { "properties": { "status": { "enum": ["adoption-required", "human-action-required"] } }, "required": ["status"] },
       "then": { "properties": { "humanActions": { "minItems": 1 } } },
       "else": { "properties": { "humanActions": { "maxItems": 0 } } }
+    },
+    {
+      "if": { "properties": { "status": { "const": "applied-reconcile-required" } }, "required": ["status"] },
+      "then": {
+        "required": ["applyReceipt"],
+        "properties": { "refreshSignals": { "maxItems": 0 } }
+      }
     }
   ],
   "$defs": {
@@ -157,6 +165,30 @@
         "reasonCodes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/reasonCode" } },
         "affectedNodeIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
       }
+    },
+    "applyIdentity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "applyId", "lookupKey", "repositoryId", "workspaceId", "acceptedChange", "semanticCommit", "ownedFilesDigest", "refreshSignalsDigest"],
+      "properties": {
+        "schemaVersion": { "const": "archcontext.projection-apply-identity/v1" },
+        "applyId": { "$ref": "#/$defs/digest" },
+        "lookupKey": { "$ref": "#/$defs/digest" },
+        "repositoryId": { "type": "string", "minLength": 1 },
+        "workspaceId": { "type": "string", "minLength": 1 },
+        "acceptedChange": { "$ref": "#/$defs/acceptedChange" },
+        "semanticCommit": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["changeSetId", "idempotencyKey"],
+          "properties": {
+            "changeSetId": { "type": "string", "minLength": 1 },
+            "idempotencyKey": { "type": "string", "minLength": 1 }
+          }
+        },
+        "ownedFilesDigest": { "$ref": "#/$defs/digest" },
+        "refreshSignalsDigest": { "$ref": "#/$defs/digest" }
+      }
     }
   }
 }

package/src/product-version.ts

@@ -1,5 +1,5 @@
 export const ARCHCONTEXT_PRODUCT_NAME = "archctx";
-export const ARCHCONTEXT_PRODUCT_VERSION = "0.4.4";
+export const ARCHCONTEXT_PRODUCT_VERSION = "0.4.6";
 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";

package/src/projection.ts

@@ -1,7 +1,9 @@
 import { digestJson, type Json } from "./schema";
 
 export const PROJECTION_REQUEST_SCHEMA_VERSION = "archcontext.projection-request/v1" as const;
-export const PROJECTION_RESULT_SCHEMA_VERSION = "archcontext.projection-result/v1" as const;
+export const PROJECTION_RESULT_SCHEMA_VERSION = "archcontext.projection-result/v2" as const;
+export const PROJECTION_APPLY_IDENTITY_SCHEMA_VERSION = "archcontext.projection-apply-identity/v1" as const;
+export const PROJECTION_APPLY_RECEIPT_SCHEMA_VERSION = "archcontext.projection-apply-receipt/v1" as const;
 export const ARCHITECTURE_REFRESH_SIGNAL_SCHEMA_VERSION = "archcontext.architecture-refresh-signal/v1" as const;
 export const ARCHCTX_CAPABILITIES_SCHEMA_VERSION = "archcontext.capabilities/v1" as const;
 export const ARCHITECTURE_DOCS_RENDERER_VERSION = "archcontext.docs-renderer/v4" as const;
@@ -12,6 +14,7 @@ export const PROJECTION_TARGETS = ["agent-context", "architecture-docs"] as cons
 export const PROJECTION_RESULT_STATUSES = [
   "adoption-required",
   "applied",
+  "applied-reconcile-required",
   "blocked",
   "human-action-required",
   "noop",
@@ -51,7 +54,8 @@ export const ARCHITECTURE_REFRESH_TARGETS = [
 export const ARCHCTX_FEATURES = [
   "architecture-docs-renderer-v2",
   "architecture-refresh-signal-v1",
-  "projection-protocol-v1"
+  "projection-apply-receipt-v1",
+  "projection-protocol-v2"
 ] as const;
 
 export type ProjectionMode = (typeof PROJECTION_MODES)[number];
@@ -112,6 +116,21 @@ export interface ProjectionHumanActionV1 {
   requestPayloadDigest: Sha256Digest;
 }
 
+export interface ProjectionApplyIdentityV1 {
+  schemaVersion: typeof PROJECTION_APPLY_IDENTITY_SCHEMA_VERSION;
+  applyId: Sha256Digest;
+  lookupKey: Sha256Digest;
+  repositoryId: string;
+  workspaceId: string;
+  acceptedChange: AcceptedArchitectureChangeReferenceV1;
+  semanticCommit: {
+    changeSetId: string;
+    idempotencyKey: string;
+  };
+  ownedFilesDigest: Sha256Digest;
+  refreshSignalsDigest: Sha256Digest;
+}
+
 export interface ArchitectureDigestSetV1 {
   modelDigest: Sha256Digest;
   sourceTreeDigest: Sha256Digest;
@@ -143,7 +162,7 @@ export interface ArchitectureRefreshSignalV1 {
   projectionReceiptDigest: Sha256Digest;
 }
 
-export interface ProjectionResultV1 {
+export interface ProjectionResultV2 {
   schemaVersion: typeof PROJECTION_RESULT_SCHEMA_VERSION;
   requestId: string;
   status: ProjectionResultStatus;
@@ -153,9 +172,16 @@ export interface ProjectionResultV1 {
   files: ProjectionFileResultV1[];
   humanActions: ProjectionHumanActionV1[];
   refreshSignals: ArchitectureRefreshSignalV1[];
+  applyReceipt?: ProjectionApplyIdentityV1;
   receiptDigest: Sha256Digest;
 }
 
+export interface ProjectionApplyReceiptV1 {
+  schemaVersion: typeof PROJECTION_APPLY_RECEIPT_SCHEMA_VERSION;
+  identity: ProjectionApplyIdentityV1;
+  result: ProjectionResultV2;
+}
+
 export interface ArchctxCapabilitiesV1 {
   schemaVersion: typeof ARCHCTX_CAPABILITIES_SCHEMA_VERSION;
   package: {
@@ -222,7 +248,7 @@ export function projectionRequestInvariantIssues(input: ProjectionRequestV1): st
   return issues;
 }
 
-export function projectionResultInvariantIssues(input: ProjectionResultV1): string[] {
+export function projectionResultInvariantIssues(input: ProjectionResultV2): string[] {
   const issues = [
     ...sortedUniqueIssues("affectedNodeIds", input.affectedNodeIds),
     ...sortedUniqueIssues("files.path", input.files.map((file) => file.path)),
@@ -237,6 +263,10 @@ export function projectionResultInvariantIssues(input: ProjectionResultV1): stri
   const statusRequiresHumanAction = input.status === "adoption-required" || input.status === "human-action-required";
   if (statusRequiresHumanAction && input.humanActions.length === 0) issues.push(`${input.status} status requires at least one human action`);
   if (!statusRequiresHumanAction && input.humanActions.length > 0) issues.push(`human actions are not allowed when status=${input.status}`);
+  if (input.status === "applied-reconcile-required") {
+    if (!input.applyReceipt) issues.push("applied-reconcile-required status requires applyReceipt");
+    if (input.refreshSignals.length > 0) issues.push("applied-reconcile-required status cannot deliver refreshSignals");
+  }
   for (const [index, file] of input.files.entries()) {
     const prefix = `files[${index}]`;
     if (file.action === "create" && (file.preimageDigest !== null || file.outputDigest === null)) {
@@ -270,11 +300,74 @@ export function projectionResultInvariantIssues(input: ProjectionResultV1): stri
  * receipt payload to avoid a circular hash; every signal must then bind that receipt via
  * projectionReceiptDigest, which projectionResultInvariantIssues verifies.
  */
-export function projectionResultReceiptDigest(input: Omit<ProjectionResultV1, "receiptDigest">): Sha256Digest {
+export function projectionResultReceiptDigest(input: Omit<ProjectionResultV2, "receiptDigest">): Sha256Digest {
   const refreshSignals = input.refreshSignals.map(({ projectionReceiptDigest: _projectionReceiptDigest, ...signal }) => signal);
   return digestJson({ ...input, refreshSignals } as unknown as Json) as Sha256Digest;
 }
 
+export function projectionApplyLookupKey(input: {
+  repositoryId: string;
+  workspaceId: string;
+  acceptedChange: AcceptedArchitectureChangeReferenceV1;
+}): Sha256Digest {
+  return digestJson({
+    schemaVersion: "archcontext.projection-apply-lookup/v1",
+    repositoryId: input.repositoryId,
+    workspaceId: input.workspaceId,
+    acceptedChange: input.acceptedChange
+  } as unknown as Json) as Sha256Digest;
+}
+
+export function createProjectionApplyIdentity(input: {
+  repositoryId: string;
+  workspaceId: string;
+  acceptedChange: AcceptedArchitectureChangeReferenceV1;
+  changeSetId: string;
+  idempotencyKey: string;
+  files: ProjectionFileResultV1[];
+  refreshSignals: ArchitectureRefreshSignalV1[];
+}): ProjectionApplyIdentityV1 {
+  const lookupKey = projectionApplyLookupKey(input);
+  const ownedFilesDigest = digestJson(input.files as unknown as Json) as Sha256Digest;
+  const refreshSignals = input.refreshSignals.map(({ projectionReceiptDigest: _receipt, ...signal }) => signal);
+  const refreshSignalsDigest = digestJson(refreshSignals as unknown as Json) as Sha256Digest;
+  const withoutApplyId = {
+    schemaVersion: PROJECTION_APPLY_IDENTITY_SCHEMA_VERSION,
+    lookupKey,
+    repositoryId: input.repositoryId,
+    workspaceId: input.workspaceId,
+    acceptedChange: input.acceptedChange,
+    semanticCommit: { changeSetId: input.changeSetId, idempotencyKey: input.idempotencyKey },
+    ownedFilesDigest,
+    refreshSignalsDigest
+  };
+  return {
+    ...withoutApplyId,
+    applyId: digestJson(withoutApplyId as unknown as Json) as Sha256Digest
+  };
+}
+
+export function projectionApplyReceiptInvariantIssues(input: ProjectionApplyReceiptV1): string[] {
+  const identity = createProjectionApplyIdentity({
+    repositoryId: input.identity.repositoryId,
+    workspaceId: input.identity.workspaceId,
+    acceptedChange: input.identity.acceptedChange,
+    changeSetId: input.identity.semanticCommit.changeSetId,
+    idempotencyKey: input.identity.semanticCommit.idempotencyKey,
+    files: input.result.files,
+    refreshSignals: input.result.refreshSignals
+  });
+  const issues = projectionResultInvariantIssues(input.result);
+  if (digestJson(identity as unknown as Json) !== digestJson(input.identity as unknown as Json)) {
+    issues.push("projection apply identity must bind the committed files and original refresh signals");
+  }
+  if (input.result.status !== "applied") issues.push("projection apply receipt result status must be applied");
+  if (digestJson(input.result.applyReceipt as unknown as Json) !== digestJson(input.identity as unknown as Json)) {
+    issues.push("projection apply receipt result must carry the same apply identity");
+  }
+  return issues;
+}
+
 export function architectureRefreshSignalInvariantIssues(input: ArchitectureRefreshSignalV1, prefix = "signal"): string[] {
   const issues = [
     ...sortedUniqueIssues(`${prefix}.reasonCodes`, input.reasonCodes),