archctx 0.5.10 → 0.5.11

package/assets/catalog.yaml

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "archcontext.practice-catalog-manifest/v1",
   "catalogVersion": "2026.06.0",
-  "productVersion": "0.5.10",
+  "productVersion": "0.5.11",
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "entries": [
     {
@@ -389,5 +389,5 @@
     "structurizr.dsl",
     "twelve-factor"
   ],
-  "catalogDigest": "sha256:e232080de13c700345d792ced46dd3a14fa7ad416b67306f637c4d27d9bc202e"
+  "catalogDigest": "sha256:674bb22ba5dd6562e15f80689b171a98789b5a9c21cdb59c89aada354b61abd8"
 }

package/bin/archctx.mjs

@@ -1039,6 +1039,87 @@ function projectionApplyRecoveryBindingInvariantIssues(binding, receipt) {
   }
   return issues;
 }
+function projectionApplyReadbackRequestInvariantIssues(request) {
+  const issues = projectionRequestInvariantIssues(request);
+  const allowed = new Set(["schemaVersion", "requestId", "profile", "mode", "targets", "changedPaths", "expected", "acceptedChange"]);
+  if (Object.keys(request).some((key) => !allowed.has(key)))
+    issues.push("readback request contains unsupported fields");
+  if (request.mode !== "apply" || !request.acceptedChange)
+    issues.push("readback requires an accepted apply request");
+  if (request.schemaVersion !== PROJECTION_REQUEST_SCHEMA_VERSION || request.profile !== "repo-harness/v1")
+    issues.push("readback request protocol is invalid");
+  if (typeof request.requestId !== "string" || request.targets.some((target) => !PROJECTION_TARGETS.includes(target)) || request.changedPaths.some((path) => typeof path !== "string" || !isRepoRelativePosixPath(path)))
+    issues.push("readback request fields are invalid");
+  const expectedKeys = ["repositoryId", "workspaceId", "headSha", "worktreeDigest"];
+  if (Object.keys(request.expected).some((key) => !expectedKeys.includes(key)) || expectedKeys.some((key) => typeof request.expected[key] !== "string") || !request.expected.repositoryId || !request.expected.workspaceId || !/^[a-f0-9]{40}$/.test(request.expected.headSha) || !SHA256_DIGEST.test(request.expected.worktreeDigest))
+    issues.push("readback expected snapshot is invalid");
+  if (request.acceptedChange && Object.keys(request.acceptedChange).some((key) => !["changeSetId", "eventId", "reasonCodes", "affectedNodeIds"].includes(key))) {
+    issues.push("readback accepted change contains unsupported fields");
+  }
+  return issues;
+}
+function projectionApplyAbsenceInvariantIssues(input, request) {
+  const issues = projectionApplyReadbackRequestInvariantIssues(request);
+  if (input.schemaVersion !== "archcontext.projection-apply-absence/v1")
+    issues.push("absence schemaVersion is invalid");
+  if (Object.keys(input).some((key) => !["schemaVersion", "requestId", "requestDigest", "lookupKey", "current", "absenceDigest"].includes(key)))
+    issues.push("absence contains unsupported fields");
+  const { absenceDigest, ...body } = input;
+  if (absenceDigest !== digestJson(body))
+    issues.push("absenceDigest must bind the complete absence result");
+  if (input.requestId !== request.requestId || input.requestDigest !== digestJson(request))
+    issues.push("absence request identity mismatch");
+  if (digestJson(input.current) !== digestJson(request.expected))
+    issues.push("absence current snapshot differs from request");
+  if (!request.acceptedChange || input.lookupKey !== projectionApplyLookupKey({
+    repositoryId: request.expected.repositoryId,
+    workspaceId: request.expected.workspaceId,
+    acceptedChange: request.acceptedChange
+  }))
+    issues.push("absence lookup identity mismatch");
+  return issues;
+}
+function projectionApplyReadbackResultDigest(input) {
+  return digestJson(input);
+}
+function projectionApplyReadbackResultInvariantIssues(input, request) {
+  const issues = projectionApplyReceiptInvariantIssues(input.receipt);
+  const { readbackDigest, ...body } = input;
+  if (input.schemaVersion !== PROJECTION_APPLY_READBACK_RESULT_SCHEMA_VERSION)
+    issues.push("readback schemaVersion is invalid");
+  if (projectionApplyReadbackResultDigest(body) !== readbackDigest)
+    issues.push("readbackDigest must bind the complete readback result");
+  if (!/^[a-zA-Z0-9_.:-]+$/.test(input.requestId))
+    issues.push("readback requestId is invalid");
+  for (const value of [input.requestDigest, input.current.ownedOutputDigest, input.current.fixedPointDigest]) {
+    if (!/^sha256:[a-f0-9]{64}$/.test(value))
+      issues.push("readback digest is invalid");
+  }
+  const receipt = input.receipt;
+  if (receipt.schemaVersion !== PROJECTION_APPLY_RECEIPT_SCHEMA_VERSION)
+    issues.push("readback receipt schemaVersion is invalid");
+  const binding = receipt.recovery;
+  if (!binding)
+    return [...issues, "committed receipt lacks its original recovery binding"];
+  for (const field of ["repositoryId", "workspaceId", "headSha", "worktreeDigest"]) {
+    if (input.current.snapshot[field] !== binding.originalExpectedSnapshot[field])
+      issues.push(`readback current ${field} differs from approval`);
+  }
+  if (input.current.snapshot.generatedFrom.codeGraphStatus !== "ready" || input.current.snapshot.rendererVersion !== binding.rendererVersion || input.current.snapshot.layoutVersion !== binding.layoutVersion || input.current.snapshot.projectionInputDigest !== receipt.result.outputSnapshot.projectionInputDigest || input.current.snapshot.codeGraphDigest !== receipt.result.outputSnapshot.codeGraphDigest || digestJson(input.current.snapshot.generatedFrom) !== digestJson(binding.generatedFrom) || digestJson(input.current.resultingDigests) !== digestJson(binding.expectedResultingDigests) || input.current.ownedOutputDigest !== binding.ownedOutputDigest) {
+    issues.push("readback current state differs from committed recovery binding");
+  }
+  if (input.requestId !== receipt.result.requestId)
+    issues.push("readback requestId differs from committed request");
+  if (request) {
+    issues.push(...projectionApplyReadbackRequestInvariantIssues(request));
+    if (input.requestDigest !== digestJson(request) || input.requestId !== request.requestId)
+      issues.push("readback request identity mismatch");
+    if (digestJson(request.expected) !== digestJson(binding.originalExpectedSnapshot) || digestJson(request.acceptedChange) !== digestJson(receipt.identity.acceptedChange) || digestJson(request.targets) !== digestJson(binding.targets) || digestJson(request.changedPaths) !== digestJson(binding.changedPaths)) {
+      issues.push("readback request differs from committed approval binding");
+    }
+  }
+  return issues;
+}
 function projectionApplyRecoveryIntentInvariantIssues(input) {
   const issues = [];
   if (input.schemaVersion !== PROJECTION_APPLY_RECOVERY_INTENT_SCHEMA_VERSION)
@@ -1168,7 +1249,7 @@ function sortedUniqueIssues(label, values) {
   const expected = [...new Set(values)].sort();
   return expected.length === values.length && expected.every((value, index) => value === values[index]) ? [] : [`${label} must be sorted and unique`];
 }
-var PROJECTION_REQUEST_SCHEMA_VERSION = "archcontext.projection-request/v1", PROJECTION_RESULT_SCHEMA_VERSION = "archcontext.projection-result/v2", PROJECTION_APPLY_IDENTITY_SCHEMA_VERSION = "archcontext.projection-apply-identity/v1", PROJECTION_APPLY_RECOVERY_BINDING_SCHEMA_VERSION = "archcontext.projection-apply-recovery-binding/v1", PROJECTION_APPLY_RECOVERY_INTENT_SCHEMA_VERSION = "archcontext.projection-apply-recovery-intent/v1", PROJECTION_APPLY_RECOVERY_PROOF_SCHEMA_VERSION = "archcontext.projection-apply-recovery-proof/v1", PROJECTION_APPLY_RECOVERY_RESULT_SCHEMA_VERSION = "archcontext.projection-apply-recovery-result/v1", ARCHITECTURE_REFRESH_SIGNAL_SCHEMA_VERSION = "archcontext.architecture-refresh-signal/v1", ARCHCTX_CAPABILITIES_SCHEMA_VERSION = "archcontext.capabilities/v1", ARCHITECTURE_DOCS_RENDERER_VERSION = "archcontext.docs-renderer/v4", AGENT_CONTEXT_RENDERER_VERSION = "archcontext.agent-context-renderer/v1", PROJECTION_MODES, PROJECTION_PRIOR_COMMITTED_APPLY_OPERATIONS, PROJECTION_TARGETS, ARCHITECTURE_MAJOR_CHANGE_REASON_CODES, ARCHCTX_FEATURES, SHA256_DIGEST, ISO_INSTANT;
+var PROJECTION_REQUEST_SCHEMA_VERSION = "archcontext.projection-request/v1", PROJECTION_RESULT_SCHEMA_VERSION = "archcontext.projection-result/v2", PROJECTION_APPLY_IDENTITY_SCHEMA_VERSION = "archcontext.projection-apply-identity/v1", PROJECTION_APPLY_RECEIPT_SCHEMA_VERSION = "archcontext.projection-apply-receipt/v1", PROJECTION_APPLY_RECOVERY_BINDING_SCHEMA_VERSION = "archcontext.projection-apply-recovery-binding/v1", PROJECTION_APPLY_RECOVERY_INTENT_SCHEMA_VERSION = "archcontext.projection-apply-recovery-intent/v1", PROJECTION_APPLY_RECOVERY_PROOF_SCHEMA_VERSION = "archcontext.projection-apply-recovery-proof/v1", PROJECTION_APPLY_RECOVERY_RESULT_SCHEMA_VERSION = "archcontext.projection-apply-recovery-result/v1", PROJECTION_APPLY_READBACK_RESULT_SCHEMA_VERSION = "archcontext.projection-apply-readback-result/v1", ARCHITECTURE_REFRESH_SIGNAL_SCHEMA_VERSION = "archcontext.architecture-refresh-signal/v1", ARCHCTX_CAPABILITIES_SCHEMA_VERSION = "archcontext.capabilities/v1", ARCHITECTURE_DOCS_RENDERER_VERSION = "archcontext.docs-renderer/v4", AGENT_CONTEXT_RENDERER_VERSION = "archcontext.agent-context-renderer/v1", PROJECTION_MODES, PROJECTION_PRIOR_COMMITTED_APPLY_OPERATIONS, PROJECTION_TARGETS, ARCHITECTURE_MAJOR_CHANGE_REASON_CODES, ARCHCTX_FEATURES, SHA256_DIGEST, ISO_INSTANT;
 var init_projection = __esm(() => {
   init_schema();
   PROJECTION_MODES = ["check", "plan", "apply", "adopt"];
@@ -1193,6 +1274,7 @@ var init_projection = __esm(() => {
     "architecture-docs-renderer-v2",
     "architecture-refresh-signal-v1",
     "module-statistics-v1",
+    "projection-apply-readback-v1",
     "projection-apply-receipt-v1",
     "projection-apply-recovery-v1",
     "projection-prior-committed-applies-v1",
@@ -1259,7 +1341,7 @@ function productVersionManifest() {
     }
   };
 }
-var ARCHCONTEXT_PRODUCT_NAME = "archctx", ARCHCONTEXT_PRODUCT_VERSION = "0.5.10", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.0", ARCHCONTEXT_NODE_RANGE = ">=22.22 <26", LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1", ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-07-11.explorer-view-v2";
+var ARCHCONTEXT_PRODUCT_NAME = "archctx", ARCHCONTEXT_PRODUCT_VERSION = "0.5.11", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.4.0", ARCHCONTEXT_NODE_RANGE = ">=22.22 <26", LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1", ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-07-11.explorer-view-v2";
 
 // packages/contracts/src/refactor.ts
 function refactorProposalDigest(proposal) {
@@ -2604,7 +2686,7 @@ var init_src2 = __esm(() => {
 
 // node_modules/.bun/@colbymchenry+codegraph@1.5.0/node_modules/@colbymchenry/codegraph/npm-sdk.js
 var require_npm_sdk = __commonJS(function(exports, module) {
-  var __dirname = "/Users/ancienttwo/Projects/arch-context-wt-projection-journal-read/node_modules/.bun/@colbymchenry+codegraph@1.5.0/node_modules/@colbymchenry/codegraph";
+  var __dirname = "/Users/ancienttwo/Projects/arch-context-wt-projection-receipt-readback/node_modules/.bun/@colbymchenry+codegraph@1.5.0/node_modules/@colbymchenry/codegraph";
   var path = __require("path");
   var os = __require("os");
   var fs = __require("fs");
@@ -34166,6 +34248,9 @@ class ArchctxDaemon {
       }
       if (draft.base.modelDigest !== currentModel.modelDigest)
         throw new Error("ChangeSet model digest changed before apply");
+      if (input.projectionApplyReceipt && await this.localStore.inspectProjectionApplyReceipt(input.projectionApplyReceipt.identity.lookupKey)) {
+        return errorEnvelope("apply_update", "AC_PRECONDITION_FAILED", "committed projection receipt requires explicit projection recover");
+      }
       const approved = input.approved ? this.changeSetEngine.approve(draft) : draft;
       let ledgerAppend;
       const writesLedger = architectureLedgerWriteAppendsEvents(this.architectureLedger.writeMode);
@@ -34237,6 +34322,65 @@ class ArchctxDaemon {
     }
     return okEnvelope("projection.prior-committed-applies", { applies });
   }
+  async readbackProjectionApply(root, request) {
+    this.assertRunning();
+    try {
+      const issues = projectionApplyReadbackRequestInvariantIssues(request);
+      if (issues.length > 0)
+        return errorEnvelope("projection.readback", "AC_SCHEMA_INVALID", issues.join("; "));
+    } catch (error) {
+      return errorEnvelope("projection.readback", "AC_SCHEMA_INVALID", error instanceof Error ? error.message : String(error));
+    }
+    return this.withWriter(async () => {
+      try {
+        const session = await this.openSession(root);
+        const inspection = await this.localStore.inspectProjectionApplyReceipt(projectionApplyLookupKey({
+          repositoryId: request.expected.repositoryId,
+          workspaceId: request.expected.workspaceId,
+          acceptedChange: request.acceptedChange
+        }));
+        if (!inspection) {
+          const body2 = {
+            schemaVersion: "archcontext.projection-apply-absence/v1",
+            requestId: request.requestId,
+            requestDigest: digestJson(request),
+            lookupKey: projectionApplyLookupKey({ repositoryId: request.expected.repositoryId, workspaceId: request.expected.workspaceId, acceptedChange: request.acceptedChange }),
+            current: {
+              repositoryId: session.workspace.repositoryId,
+              workspaceId: runtimeProjectionWorkspaceId(root),
+              headSha: readHeadSha2(root),
+              worktreeDigest: runtimeWorktreeDigest(root, "architecture-documentation-projection")
+            }
+          };
+          const absence = { ...body2, absenceDigest: digestJson(body2) };
+          const issues2 = projectionApplyAbsenceInvariantIssues(absence, request);
+          return issues2.length === 0 ? okEnvelope("projection.readback", absence) : errorEnvelope("projection.readback", "AC_PRECONDITION_FAILED", issues2.join("; "));
+        }
+        const receipt = inspection.receipt;
+        const fixedPoint = buildRuntimeProjectionRecoveryFixedPoint(root);
+        const issues = runtimeProjectionRecoveryFixedPointIssues(receipt, fixedPoint);
+        if (issues.length > 0)
+          return errorEnvelope("projection.readback", "AC_PRECONDITION_FAILED", `projection readback proof failed: ${issues.join("; ")}`);
+        const body = {
+          schemaVersion: PROJECTION_APPLY_READBACK_RESULT_SCHEMA_VERSION,
+          requestId: request.requestId,
+          requestDigest: digestJson(request),
+          receipt,
+          current: runtimeProjectionRecoveryCurrent(fixedPoint)
+        };
+        const result = { ...body, readbackDigest: projectionApplyReadbackResultDigest(body) };
+        const resultIssues = projectionApplyReadbackResultInvariantIssues(result, request);
+        if (session.workspace.repositoryId !== result.current.snapshot.repositoryId || session.workspace.headSha !== result.current.snapshot.headSha || runtimeWorktreeDigest(root, "architecture-documentation-projection") !== result.current.snapshot.worktreeDigest) {
+          resultIssues.push("projection readback authority changed before response");
+        }
+        if (resultIssues.length > 0)
+          return errorEnvelope("projection.readback", "AC_PRECONDITION_FAILED", resultIssues.join("; "));
+        return okEnvelope("projection.readback", result);
+      } catch (error) {
+        return errorEnvelope("projection.readback", "AC_PRECONDITION_FAILED", error instanceof Error ? error.message : String(error));
+      }
+    });
+  }
   async recoverProjectionApply(root, intent) {
     this.assertRunning();
     const intentIssues = projectionApplyRecoveryIntentInvariantIssues(intent);
@@ -37059,6 +37203,9 @@ class RuntimeRpcClient {
   listProjectionPriorCommittedApplies(root, requestId) {
     return this.call("listProjectionPriorCommittedApplies", [root, requestId]);
   }
+  readbackProjectionApply(root, request) {
+    return this.call("readbackProjectionApply", [root, request]);
+  }
   recoverProjectionApply(root, intent) {
     return this.call("recoverProjectionApply", [root, intent]);
   }
@@ -37419,6 +37566,8 @@ class ArchctxRuntimeRpcServer {
         return this.daemon.inspectProjectionApplyReceipt(params[0], params[1]);
       case "listProjectionPriorCommittedApplies":
         return this.daemon.listProjectionPriorCommittedApplies(params[0], params[1]);
+      case "readbackProjectionApply":
+        return this.daemon.readbackProjectionApply(params[0], params[1]);
       case "recoverProjectionApply":
         return this.daemon.recoverProjectionApply(params[0], params[1]);
       case "ledgerState":
@@ -37806,8 +37955,8 @@ function runtimeProjectionRecoveryFixedPointIssues(receipt, fixedPoint) {
     issues.push("current proof snapshot requires CodeGraph ready");
   return issues;
 }
-function createRuntimeProjectionRecoveryProof(intent, receipt, fixedPoint) {
-  const current = {
+function runtimeProjectionRecoveryCurrent(fixedPoint) {
+  return {
     snapshot: fixedPoint.snapshot,
     resultingDigests: fixedPoint.projection.architectureDigests,
     ownedOutputDigest: fixedPoint.ownedOutputDigest,
@@ -37821,6 +37970,9 @@ function createRuntimeProjectionRecoveryProof(intent, receipt, fixedPoint) {
       refreshSignalIds: fixedPoint.projection.refreshSignals.map((signal) => signal.signalId)
     })
   };
+}
+function createRuntimeProjectionRecoveryProof(intent, receipt, fixedPoint) {
+  const current = runtimeProjectionRecoveryCurrent(fixedPoint);
   const payload = {
     schemaVersion: "archcontext.projection-apply-recovery-proof/v1",
     requestId: intent.requestId,
@@ -39673,6 +39825,9 @@ class RuntimeRpcClient2 {
   listProjectionPriorCommittedApplies(root, requestId) {
     return this.call("listProjectionPriorCommittedApplies", [root, requestId]);
   }
+  readbackProjectionApply(root, request) {
+    return this.call("readbackProjectionApply", [root, request]);
+  }
   recoverProjectionApply(root, intent) {
     return this.call("recoverProjectionApply", [root, intent]);
   }
@@ -41329,6 +41484,9 @@ async function runArchitectureDocsAdoptionCommand(args2, root, daemon, projectio
   const canonicalExistingByPath = new Map(simulatedByPath);
   for (const file of canonicalFirst.files)
     canonicalExistingByPath.set(file.path, file);
+  const canonicalBaseline = buildArchitectureDocsProjection(root, generatedAt, profile, [...canonicalExistingByPath.values()]);
+  for (const file of canonicalBaseline.files)
+    canonicalExistingByPath.set(file.path, file);
   const canonical = buildArchitectureDocsProjection(root, generatedAt, profile, [...canonicalExistingByPath.values()]);
   if (!canonical.plan.drift.ok || canonical.plan.rejected.length > 0 || canonical.plan.projectionDigest !== canonicalFirst.plan.projectionDigest) {
     const reasons = canonical.plan.rejected.map((entry) => entry.reasonCode).join(",") || "none";
@@ -41449,10 +41607,12 @@ async function applyProjectionProtocolFixedPoint(request, input, fixedPoint, cha
 }
 async function runProjectionProtocolCommand(args2, cwd, daemon) {
   const subcommand = args2[0] ?? "run";
+  if (subcommand === "readback")
+    return runProjectionApplyReadbackCommand(args2.slice(1), cwd, daemon);
   if (subcommand === "recover")
     return runProjectionApplyRecoveryCommand(args2.slice(1), cwd, daemon);
   if (subcommand !== "run")
-    return errorEnvelope("projection", "AC_SCHEMA_INVALID", "projection requires run|recover --request-json <request>");
+    return errorEnvelope("projection", "AC_SCHEMA_INVALID", "projection requires run|recover|readback --request-json <request>");
   const raw = readFlag(args2, "--request-json");
   if (!raw)
     return errorEnvelope("projection.run", "AC_SCHEMA_INVALID", "projection run requires --request-json");
@@ -41547,6 +41707,29 @@ function parseProjectionPriorCommittedApplies(value, requestId) {
     throw new Error(`prior committed apply invariant failed: ${issues.join("; ")}`);
   return applies;
 }
+async function runProjectionApplyReadbackCommand(args2, cwd, daemon) {
+  const raw = readFlag(args2, "--request-json");
+  if (!raw)
+    return errorEnvelope("projection.readback", "AC_SCHEMA_INVALID", "projection readback requires --request-json");
+  let request;
+  try {
+    request = parseProjectionProtocolRequest(raw);
+    const issues = projectionApplyReadbackRequestInvariantIssues(request);
+    if (issues.length > 0)
+      throw new Error(issues.join("; "));
+  } catch (error) {
+    return errorEnvelope("projection.readback", "AC_SCHEMA_INVALID", error instanceof Error ? error.message : String(error));
+  }
+  try {
+    const result = await daemon.readbackProjectionApply(findRepositoryRoot(cwd), request);
+    if (!result.ok)
+      return result;
+    const issues = result.data?.schemaVersion === "archcontext.projection-apply-absence/v1" ? projectionApplyAbsenceInvariantIssues(result.data, request) : projectionApplyReadbackResultInvariantIssues(result.data, request);
+    return issues.length === 0 ? result : errorEnvelope("projection.readback", "AC_SCHEMA_INVALID", issues.join("; "));
+  } catch (error) {
+    return errorEnvelope("projection.readback", "AC_PRECONDITION_FAILED", error instanceof Error ? error.message : String(error));
+  }
+}
 async function runProjectionApplyRecoveryCommand(args2, cwd, daemon) {
   const raw = readFlag(args2, "--request-json");
   if (!raw)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archctx",
-  "version": "0.5.10",
+  "version": "0.5.11",
   "description": "Local architecture context CLI for agentic coding workflows.",
   "private": false,
   "type": "module",

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-prior-committed-applies-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-readback-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"] }
     }
   }
 }