archctx-contracts 0.5.7 → 0.5.9

package/fixtures/valid/archctx-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "archcontext.capabilities/v1",
-  "package": { "name": "archctx", "version": "0.5.7" },
+  "package": { "name": "archctx", "version": "0.5.9" },
   "protocols": {
     "projectionRequest": "archcontext.projection-request/v1",
     "projectionResult": "archcontext.projection-result/v2",
@@ -10,5 +10,5 @@
     "architectureDocs": "archcontext.docs-renderer/v4",
     "agentContext": "archcontext.agent-context-renderer/v1"
   },
-  "features": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "module-statistics-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-protocol-v2", "recommendation-v3", "refactor-assessment-v1", "refactor-resolution-v1"]
+  "features": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "module-statistics-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-prior-committed-applies-v1", "projection-protocol-v2", "recommendation-v3", "refactor-assessment-v1", "refactor-resolution-v1"]
 }

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

@@ -2,7 +2,7 @@
   "schemaVersion": "archcontext.product-version-manifest/v1",
   "product": {
     "name": "archctx",
-    "version": "0.5.7",
+    "version": "0.5.9",
     "distribution": "one-package"
   },
   "packageManager": "bun@1.4.0",
@@ -12,25 +12,25 @@
   "surfaces": {
     "cli": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.5.7",
+      "version": "0.5.9",
       "entrypoint": "archctx"
     },
     "daemon": {
       "packageName": "@archcontext/local-runtime",
-      "version": "0.5.7",
+      "version": "0.5.9",
       "entrypoint": "archctx daemon start",
       "rpcSchemaVersion": "archcontext.runtime-rpc/v1"
     },
     "mcp": {
       "packageName": "@archcontext/surfaces",
-      "version": "0.5.7",
+      "version": "0.5.9",
       "entrypoint": "archctx mcp",
       "transport": "stdio"
     }
   },
   "schemas": {
     "schemaSetVersion": "2026-06-25.al0-ledger",
-    "contractsPackageVersion": "0.5.7",
+    "contractsPackageVersion": "0.5.9",
     "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.7",
+  "version": "0.5.9",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

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

@@ -39,7 +39,7 @@
       "type": "array",
       "minItems": 3,
       "uniqueItems": true,
-      "items": { "enum": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "module-statistics-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-protocol-v2", "recommendation-v3", "refactor-assessment-v1", "refactor-resolution-v1"] }
+      "items": { "enum": ["architecture-docs-renderer-v2", "architecture-refresh-signal-v1", "module-statistics-v1", "projection-apply-receipt-v1", "projection-apply-recovery-v1", "projection-prior-committed-applies-v1", "projection-protocol-v2", "recommendation-v3", "refactor-assessment-v1", "refactor-resolution-v1"] }
     }
   }
 }

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

@@ -16,6 +16,7 @@
     "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" },
+    "priorCommittedApplies": { "type": "array", "minItems": 1, "description": "Omitted, never empty. Canonical wire order is by changeSetId and is enforced by projectionResultInvariantIssues.", "items": { "$ref": "#/$defs/priorCommittedApply" } },
     "receiptDigest": { "$ref": "#/$defs/digest" }
   },
   "allOf": [
@@ -166,6 +167,45 @@
         "affectedNodeIds": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
       }
     },
+    "priorCommittedApply": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requestId", "changeSetId", "committedAt", "files"],
+      "properties": {
+        "applyId": { "$ref": "#/$defs/digest" },
+        "lookupKey": { "$ref": "#/$defs/digest" },
+        "requestId": { "type": "string", "pattern": "^[a-zA-Z0-9_.:-]+$", "minLength": 1 },
+        "changeSetId": { "type": "string", "minLength": 1 },
+        "committedAt": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" },
+        "files": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Canonical wire order is by path and is enforced by projectionResultInvariantIssues.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "operation", "hash"],
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "not": { "anyOf": [{ "pattern": "^/" }, { "pattern": "\\\\" }, { "pattern": "(^|/)\\.\\.(/|$)" }] }
+              },
+              "operation": { "enum": ["delete", "write"] },
+              "hash": { "type": "string", "pattern": "^(?:sha256:[a-f0-9]{64}|missing)$" }
+            },
+            "allOf": [
+              {
+                "if": { "properties": { "operation": { "const": "delete" } }, "required": ["operation"] },
+                "then": { "properties": { "hash": { "const": "missing" } } },
+                "else": { "properties": { "hash": { "$ref": "#/$defs/digest" } } }
+              }
+            ]
+          }
+        }
+      },
+      "dependentRequired": { "applyId": ["lookupKey"], "lookupKey": ["applyId"] }
+    },
     "applyIdentity": {
       "type": "object",
       "additionalProperties": false,

package/src/product-version.ts

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

package/src/projection.ts

@@ -1,4 +1,4 @@
-import { digestJson, type Json } from "./schema";
+import { digestJson, isRepoRelativePosixPath, 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/v2" as const;
@@ -14,6 +14,7 @@ export const ARCHITECTURE_DOCS_RENDERER_VERSION = "archcontext.docs-renderer/v4"
 export const AGENT_CONTEXT_RENDERER_VERSION = "archcontext.agent-context-renderer/v1" as const;
 
 export const PROJECTION_MODES = ["check", "plan", "apply", "adopt"] as const;
+export const PROJECTION_PRIOR_COMMITTED_APPLY_OPERATIONS = ["delete", "write"] as const;
 export const PROJECTION_TARGETS = ["agent-context", "architecture-docs"] as const;
 export const PROJECTION_RESULT_STATUSES = [
   "adoption-required",
@@ -61,6 +62,7 @@ export const ARCHCTX_FEATURES = [
   "module-statistics-v1",
   "projection-apply-receipt-v1",
   "projection-apply-recovery-v1",
+  "projection-prior-committed-applies-v1",
   "projection-protocol-v2",
   "recommendation-v3",
   "refactor-assessment-v1",
@@ -71,6 +73,7 @@ export type ProjectionMode = (typeof PROJECTION_MODES)[number];
 export type ProjectionTarget = (typeof PROJECTION_TARGETS)[number];
 export type ProjectionResultStatus = (typeof PROJECTION_RESULT_STATUSES)[number];
 export type ProjectionHumanActionReasonCode = (typeof PROJECTION_HUMAN_ACTION_REASON_CODES)[number];
+export type ProjectionPriorCommittedApplyOperation = (typeof PROJECTION_PRIOR_COMMITTED_APPLY_OPERATIONS)[number];
 export type ArchitectureMajorChangeReasonCode = (typeof ARCHITECTURE_MAJOR_CHANGE_REASON_CODES)[number];
 export type ArchitectureRefreshTarget = (typeof ARCHITECTURE_REFRESH_TARGETS)[number];
 export type ArchctxFeature = (typeof ARCHCTX_FEATURES)[number];
@@ -171,6 +174,33 @@ export interface ArchitectureRefreshSignalV1 {
   projectionReceiptDigest: Sha256Digest;
 }
 
+export interface ProjectionPriorCommittedApplyFileV1 {
+  path: string;
+  operation: ProjectionPriorCommittedApplyOperation;
+  /** `digestJson({ body })` of the body this ChangeSet wrote, or `"missing"` for a delete. */
+  hash: string;
+}
+
+/**
+ * A ChangeSet already committed under this request's requestId by an earlier attempt of the same
+ * request. The CLI is a short-lived RPC client while the daemon owns the write, so a caller whose
+ * process was killed after the commit sees only `status: noop` on retry; this array is the only
+ * surface that names what that lost attempt actually wrote.
+ */
+export interface ProjectionPriorCommittedApplyV1 {
+  /**
+   * Present together with `lookupKey` only when the committed ChangeSet also carried a projection
+   * apply receipt, which happens only for an accepted-semantic-change apply. A plain drift-repair
+   * apply commits without one, and both fields are then absent rather than invented.
+   */
+  applyId?: Sha256Digest;
+  lookupKey?: Sha256Digest;
+  requestId: string;
+  changeSetId: string;
+  committedAt: string;
+  files: ProjectionPriorCommittedApplyFileV1[];
+}
+
 export interface ProjectionResultV2 {
   schemaVersion: typeof PROJECTION_RESULT_SCHEMA_VERSION;
   requestId: string;
@@ -182,6 +212,8 @@ export interface ProjectionResultV2 {
   humanActions: ProjectionHumanActionV1[];
   refreshSignals: ArchitectureRefreshSignalV1[];
   applyReceipt?: ProjectionApplyIdentityV1;
+  /** Omitted, never `[]`, when no earlier attempt of this requestId committed. */
+  priorCommittedApplies?: ProjectionPriorCommittedApplyV1[];
   receiptDigest: Sha256Digest;
 }
 
@@ -359,6 +391,9 @@ export function projectionResultInvariantIssues(input: ProjectionResultV2): stri
       issues.push(`${prefix} unchanged requires equal non-null digests`);
     }
   }
+  if (input.priorCommittedApplies) {
+    issues.push(...projectionPriorCommittedAppliesIssues(input.priorCommittedApplies, input.requestId));
+  }
   const { receiptDigest, ...receiptPayload } = input;
   if (projectionResultReceiptDigest(receiptPayload) !== receiptDigest) issues.push("receiptDigest must match the canonical projection result payload");
   for (const [index, signal] of input.refreshSignals.entries()) {
@@ -372,6 +407,40 @@ export function projectionResultInvariantIssues(input: ProjectionResultV2): stri
   return issues;
 }
 
+export function projectionPriorCommittedAppliesIssues(
+  input: readonly ProjectionPriorCommittedApplyV1[],
+  requestId: string
+): string[] {
+  const issues = sortedUniqueIssues("priorCommittedApplies.changeSetId", input.map((entry) => entry.changeSetId));
+  if (input.length === 0) issues.push("priorCommittedApplies must be omitted instead of empty");
+  for (const [index, entry] of input.entries()) {
+    const prefix = `priorCommittedApplies[${index}]`;
+    issues.push(...sortedUniqueIssues(`${prefix}.files.path`, entry.files.map((file) => file.path)));
+    if (entry.requestId !== requestId) issues.push(`${prefix}.requestId must match the projection result requestId`);
+    if (entry.changeSetId.trim() === "") issues.push(`${prefix}.changeSetId must not be empty`);
+    if (!ISO_INSTANT.test(entry.committedAt)) issues.push(`${prefix}.committedAt must be an ISO-8601 UTC instant`);
+    if (entry.files.length === 0) issues.push(`${prefix}.files must name at least one committed file`);
+    if ((entry.applyId === undefined) !== (entry.lookupKey === undefined)) {
+      issues.push(`${prefix}.applyId and lookupKey must be present together or both absent`);
+    }
+    for (const field of ["applyId", "lookupKey"] as const) {
+      const value = entry[field];
+      if (value !== undefined && !SHA256_DIGEST.test(value)) issues.push(`${prefix}.${field} must be a SHA-256 digest`);
+    }
+    for (const [fileIndex, file] of entry.files.entries()) {
+      const filePrefix = `${prefix}.files[${fileIndex}]`;
+      if (!isRepoRelativePosixPath(file.path)) issues.push(`${filePrefix}.path must be a repository-relative POSIX path`);
+      if (!(PROJECTION_PRIOR_COMMITTED_APPLY_OPERATIONS as readonly string[]).includes(file.operation)) {
+        issues.push(`${filePrefix}.operation must be a supported committed operation`);
+      }
+      const expectsMissing = file.operation === "delete";
+      if (expectsMissing && file.hash !== "missing") issues.push(`${filePrefix}.hash must be "missing" for a delete`);
+      if (!expectsMissing && !SHA256_DIGEST.test(file.hash)) issues.push(`${filePrefix}.hash must be a SHA-256 body digest`);
+    }
+  }
+  return issues;
+}
+
 /**
  * Computes the accepted projection receipt. Signal back-references are omitted from the
  * receipt payload to avoid a circular hash; every signal must then bind that receipt via
@@ -615,6 +684,9 @@ export function architectureRefreshSignalInvariantIssues(input: ArchitectureRefr
   return issues;
 }
 
+const SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
+const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+
 function sortedUniqueIssues(label: string, values: readonly string[]): string[] {
   const expected = [...new Set(values)].sort();
   return expected.length === values.length && expected.every((value, index) => value === values[index])