archctx 0.4.5 → 0.4.6

package/assets/catalog.yaml

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "archcontext.practice-catalog-manifest/v1",
   "catalogVersion": "2026.06.0",
-  "productVersion": "0.4.5",
+  "productVersion": "0.4.6",
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "entries": [
     {
@@ -389,5 +389,5 @@
     "structurizr.dsl",
     "twelve-factor"
   ],
-  "catalogDigest": "sha256:9687f9aabf24904bb08a174a9c0a83664d437bd0862bf0c7725faf2c11bbb913"
+  "catalogDigest": "sha256:12ce681507d3cf7bcec02fe367b1bb9161f3b469559a8f5d2db861d3a692c469"
 }

package/bin/archctx.mjs

@@ -1088,7 +1088,7 @@ function productVersionManifest() {
     }
   };
 }
-var ARCHCONTEXT_PRODUCT_NAME = "archctx", ARCHCONTEXT_PRODUCT_VERSION = "0.4.5", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.3.10", ARCHCONTEXT_NODE_RANGE = ">=24 <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.4.6", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.3.10", ARCHCONTEXT_NODE_RANGE = ">=24 <26", LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1", ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-07-11.explorer-view-v2";
 
 // packages/contracts/src/validator.ts
 function validateJsonSchema(schema, value) {
@@ -28492,6 +28492,71 @@ function auditGithubIssuesEnabledInManifestText(manifestText) {
 }
 var RUNTIME_RPC_VERSION = LOCAL_RUNTIME_RPC_SCHEMA_VERSION;
 
+class RuntimeUpdateInputError extends Error {
+}
+function decodeRuntimeWorktreeDigestProfile(value, field) {
+  switch (value) {
+    case "repository":
+    case "architecture-documentation-projection":
+      return value;
+    default:
+      throw new RuntimeUpdateInputError(`${field} must be repository or architecture-documentation-projection`);
+  }
+}
+function decodeRuntimePlanUpdateInput(value) {
+  const input = runtimeUpdateInputRecord(value, "plan_update input");
+  if (typeof input.id !== "string" || input.id.length === 0) {
+    throw new RuntimeUpdateInputError("plan_update id must be a non-empty string");
+  }
+  if (!Array.isArray(input.operations)) {
+    throw new RuntimeUpdateInputError("plan_update operations must be an array");
+  }
+  let worktreeDigestPrecondition;
+  if (input.worktreeDigestPrecondition !== undefined) {
+    const precondition = runtimeUpdateInputRecord(input.worktreeDigestPrecondition, "plan_update worktreeDigestPrecondition");
+    const profile = decodeRuntimeWorktreeDigestProfile(precondition.profile, "plan_update worktreeDigestPrecondition.profile");
+    if (profile !== "architecture-documentation-projection") {
+      throw new RuntimeUpdateInputError("plan_update worktreeDigestPrecondition.profile must be architecture-documentation-projection");
+    }
+    if (typeof precondition.expectedDigest !== "string" || precondition.expectedDigest.length === 0) {
+      throw new RuntimeUpdateInputError("plan_update worktreeDigestPrecondition.expectedDigest must be a non-empty string");
+    }
+    worktreeDigestPrecondition = { profile, expectedDigest: precondition.expectedDigest };
+  }
+  return {
+    id: input.id,
+    operations: input.operations,
+    ...input.reason === undefined ? {} : { reason: input.reason },
+    ...worktreeDigestPrecondition === undefined ? {} : { worktreeDigestPrecondition }
+  };
+}
+function decodeRuntimeApplyUpdateInput(value) {
+  const input = runtimeUpdateInputRecord(value, "apply_update input");
+  if (typeof input.id !== "string" || input.id.length === 0) {
+    throw new RuntimeUpdateInputError("apply_update id must be a non-empty string");
+  }
+  if (typeof input.approved !== "boolean") {
+    throw new RuntimeUpdateInputError("apply_update approved must be a boolean");
+  }
+  if (typeof input.expectedWorktreeDigest !== "string" || input.expectedWorktreeDigest.length === 0) {
+    throw new RuntimeUpdateInputError("apply_update expectedWorktreeDigest must be a non-empty string");
+  }
+  const worktreeDigestProfile = input.worktreeDigestProfile === undefined ? undefined : decodeRuntimeWorktreeDigestProfile(input.worktreeDigestProfile, "apply_update worktreeDigestProfile");
+  return {
+    id: input.id,
+    approved: input.approved,
+    expectedWorktreeDigest: input.expectedWorktreeDigest,
+    ...worktreeDigestProfile === undefined ? {} : { worktreeDigestProfile },
+    ...input.projectionApplyReceipt === undefined ? {} : { projectionApplyReceipt: input.projectionApplyReceipt }
+  };
+}
+function runtimeUpdateInputRecord(value, field) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new RuntimeUpdateInputError(`${field} must be an object`);
+  }
+  return value;
+}
+
 class ArchitectureLedgerReadModelStore {
   fallback;
   localStore;
@@ -28602,6 +28667,7 @@ class ArchctxDaemon {
   checkpointBaselines = new Map;
   checkpointCoalesced = new Map;
   changesets = new Map;
+  changeSetWorktreeDigestProfiles = new Map;
   deferredArchitectureChangeFeedFailures = new Map;
   auditRunAbortControllers = new Map;
   landscape;
@@ -29591,6 +29657,7 @@ class ArchctxDaemon {
       operations: [{ op: "write_waiver", path, expectedHash, body }]
     });
     this.changesets.set(draft.id, draft);
+    this.changeSetWorktreeDigestProfiles.set(draft.id, "repository");
     return okEnvelope("practices.waive", {
       schemaVersion: "archcontext.practice-waiver-plan/v1",
       waiver,
@@ -29762,21 +29829,36 @@ class ArchctxDaemon {
     };
     return okEnvelope("resource.read", result);
   }
-  async planUpdate(root, input) {
+  async planUpdate(root, rawInput) {
     this.assertRunning();
+    let input;
+    try {
+      input = decodeRuntimePlanUpdateInput(rawInput);
+    } catch (error) {
+      if (error instanceof RuntimeUpdateInputError) {
+        return errorEnvelope("plan_update", "AC_SCHEMA_INVALID", error.message);
+      }
+      throw error;
+    }
     const session = await this.openSession(root);
     const model = await this.readModelStore.validateModel(session.workspace);
+    const worktreeDigestProfile = input.worktreeDigestPrecondition?.profile ?? "repository";
+    const worktreeDigest = runtimeWorktreeDigest(root, worktreeDigestProfile);
+    if (input.worktreeDigestPrecondition && input.worktreeDigestPrecondition.expectedDigest !== worktreeDigest) {
+      throw new Error("Worktree digest changed before plan");
+    }
     const draft = this.changeSetEngine.plan({
       id: input.id,
       base: {
         headSha: session.workspace.headSha,
-        worktreeDigest: session.snapshot.worktreeDigest,
+        worktreeDigest,
         modelDigest: model.modelDigest
       },
       reason: input.reason ?? { taskSessionId: "task_runtime" },
       operations: input.operations
     });
     this.changesets.set(draft.id, draft);
+    this.changeSetWorktreeDigestProfiles.set(draft.id, worktreeDigestProfile);
     return okEnvelope("plan_update", {
       draft,
       preview: this.changeSetEngine.preview(root, draft)
@@ -29905,18 +29987,31 @@ class ArchctxDaemon {
       return cached ? { ...cached.resource, queryDigest, cacheStatus: "stale" } : undefined;
     }
   }
-  async applyUpdate(root, input) {
+  async applyUpdate(root, rawInput) {
     this.assertRunning();
+    let input;
+    try {
+      input = decodeRuntimeApplyUpdateInput(rawInput);
+    } catch (error) {
+      if (error instanceof RuntimeUpdateInputError) {
+        return errorEnvelope("apply_update", "AC_SCHEMA_INVALID", error.message);
+      }
+      throw error;
+    }
     return this.withWriter(async () => {
-      if (!input.expectedWorktreeDigest)
-        throw new Error("apply_update requires expectedWorktreeDigest");
-      const current = computeWorktreeDigest2(root);
-      if (current !== input.expectedWorktreeDigest)
-        throw new Error("Worktree digest changed before apply");
-      const session = await this.openSession(root);
       const draft = this.changesets.get(input.id);
       if (!draft)
         throw new Error(`Unknown ChangeSet: ${input.id}`);
+      const plannedProfile = this.changeSetWorktreeDigestProfiles.get(input.id);
+      if (!plannedProfile)
+        throw new Error("ChangeSet worktree digest profile missing before apply");
+      const requestedProfile = input.worktreeDigestProfile ?? "repository";
+      if (requestedProfile !== plannedProfile)
+        throw new Error("ChangeSet worktree digest profile changed before apply");
+      const current = runtimeWorktreeDigest(root, plannedProfile);
+      if (current !== input.expectedWorktreeDigest)
+        throw new Error("Worktree digest changed before apply");
+      const session = await this.openSession(root);
       if (draft.base.headSha !== session.workspace.headSha)
         throw new Error("ChangeSet HEAD changed before apply");
       if (draft.base.worktreeDigest !== current)
@@ -32404,7 +32499,7 @@ class ArchctxRuntimeRpcServer {
         pid: process.pid,
         protocol: "http-loopback",
         version: 1,
-        product: productVersionManifest(),
+        product: this.options.productManifest?.() ?? productVersionManifest(),
         composition: this.daemon.compositionReport()
       });
       return;
@@ -32719,6 +32814,16 @@ function shouldSkipGeneratedProjectionJob(metadata, input) {
 function isRuntimeAgentJobCursorStale(job, scope) {
   return job.worktree.headSha !== scope.worktree.headSha || job.worktree.worktreeDigest !== scope.worktree.worktreeDigest;
 }
+function runtimeWorktreeDigest(root, profile) {
+  switch (profile) {
+    case "repository":
+      return computeWorktreeDigest2(root);
+    case "architecture-documentation-projection":
+      return architectureDocumentationProjectionWorktreeDigest(root, loadNativeModelFromArchContext(root));
+    default:
+      throw new RuntimeUpdateInputError(`unsupported worktree digest profile: ${String(profile)}`);
+  }
+}
 function isArchContextGeneratedProjectionPath(path) {
   return path.replace(/\\/g, "/").startsWith(".archcontext/generated/");
 }
@@ -35773,14 +35878,19 @@ async function runProjectionProtocolCommand(args2, cwd, daemon) {
     const planned = await daemon.planUpdate(root, {
       id: changeSetId,
       reason: { taskSessionId: request.requestId },
-      operations: [architectureDocsRenderProjectionOperation(root, projection3.files)]
+      operations: [architectureDocsRenderProjectionOperation(root, projection3.files)],
+      worktreeDigestPrecondition: {
+        profile: "architecture-documentation-projection",
+        expectedDigest: request.expected.worktreeDigest
+      }
     });
     if (!planned.ok)
       return planned;
     const applied = await daemon.applyUpdate(root, {
       id: changeSetId,
       approved: true,
-      expectedWorktreeDigest: computeWorktreeDigest(root),
+      expectedWorktreeDigest: request.expected.worktreeDigest,
+      worktreeDigestProfile: "architecture-documentation-projection",
       ...applyReceipt ? { projectionApplyReceipt: applyReceipt } : {}
     });
     if (!applied.ok)
@@ -37571,6 +37681,9 @@ async function doctorDaemon(cwd) {
   const health = await client.health().catch(() => {
     return;
   });
+  const healthIssue = runtimeRpcCompatibilityIssueFromHealth(cwd, client, health);
+  if (healthIssue)
+    return incompatibleDaemonStatus(healthIssue);
   if (health?.ok === true) {
     const stalenessIssue = cliEntryStalenessIssue(cwd);
     if (stalenessIssue?.pidAlive)
@@ -37580,6 +37693,7 @@ async function doctorDaemon(cwd) {
     running: health?.ok === true,
     staleConnection: health?.ok !== true,
     rpcVersionCompatible: health?.schemaVersion === productVersionManifest().runtime.localRpc.schemaVersion,
+    productVersionCompatible: health?.product?.product?.version === productVersionManifest().product.version,
     connection: client.connectionInfo(),
     health: health?.ok === true ? {
       composition: health.composition,
@@ -37723,6 +37837,9 @@ async function createOrStartRuntimeRpcClient(cwd) {
     const health = await startedClient.health().catch(() => {
       return;
     });
+    const healthIssue = runtimeRpcCompatibilityIssueFromHealth(cwd, startedClient, health);
+    if (healthIssue)
+      throw new RuntimeVersionUnsupportedError(healthIssue);
     if (health?.ok === true)
       return startedClient;
   }
@@ -37812,6 +37929,7 @@ async function runDaemonCommand(args2, cwd) {
         running: true,
         product: health.product,
         rpcVersionCompatible: health.schemaVersion === RUNTIME_RPC_VERSION,
+        productVersionCompatible: true,
         ...client.connectionInfo(),
         token: "stored-in-connection-file"
       });
@@ -37852,6 +37970,9 @@ async function startBackgroundDaemon(args2, cwd) {
     return errorEnvelope("daemon.start", "AC_RUNTIME_VERSION_UNSUPPORTED", runtimeVersionUnsupportedMessage(compatibilityIssue));
   }
   const discovered = await discoverRunningDaemonInfo(cwd, { recoverStale: true });
+  if (discovered.compatibilityIssue?.pidAlive) {
+    return errorEnvelope("daemon.start", "AC_RUNTIME_VERSION_UNSUPPORTED", runtimeVersionUnsupportedMessage(discovered.compatibilityIssue));
+  }
   if (discovered.info) {
     return okEnvelope("daemon.start", {
       running: true,
@@ -37909,7 +38030,8 @@ async function startBackgroundDaemon(args2, cwd) {
   }
 }
 async function upgradeDaemon(args2, cwd) {
-  const issue = runtimeRpcCompatibilityIssue(cwd) ?? cliEntryStalenessIssue(cwd);
+  const persistedIssue = runtimeRpcCompatibilityIssue(cwd) ?? cliEntryStalenessIssue(cwd);
+  const issue = persistedIssue ?? (await discoverRunningDaemonInfo(cwd)).compatibilityIssue;
   if (!issue) {
     const started2 = await startBackgroundDaemon(args2, cwd);
     return started2.ok ? { ...started2, requestId: "daemon.upgrade", data: { ...started2.data, upgraded: false, reason: "runtime-compatible" } } : started2;
@@ -37930,6 +38052,10 @@ async function upgradeDaemon(args2, cwd) {
     previousStartedAt: issue.received,
     entrypointMtime: issue.expected,
     previousPid: issue.pid
+  } : issue.reason === "product-version-mismatch" ? {
+    previousProductVersion: issue.received,
+    expectedProductVersion: issue.expected,
+    previousPid: issue.pid
   } : {
     previousRpcSchemaVersion: issue.received,
     expectedRpcSchemaVersion: issue.expected,
@@ -37954,17 +38080,27 @@ async function discoverRunningDaemonInfo(cwd, options = {}) {
   if (!client) {
     return {
       info: undefined,
+      compatibilityIssue: undefined,
       recovery: options.recoverStale ? recoverStaleDaemonControlFiles(cwd) : emptyRecovery(cwd)
     };
   }
   const health = await client.health().catch(() => {
     return;
   });
+  const compatibilityIssue = runtimeRpcCompatibilityIssueFromHealth(cwd, client, health) ?? cliEntryStalenessIssue(cwd);
+  if (compatibilityIssue) {
+    return {
+      info: undefined,
+      compatibilityIssue,
+      recovery: emptyRecovery(cwd)
+    };
+  }
   if (health?.ok === true) {
-    return { info: client.connectionInfo(), recovery: emptyRecovery(cwd) };
+    return { info: client.connectionInfo(), compatibilityIssue: undefined, recovery: emptyRecovery(cwd) };
   }
   return {
     info: undefined,
+    compatibilityIssue: undefined,
     recovery: options.recoverStale ? recoverStaleDaemonControlFiles(cwd, { removeUnhealthyConnection: true }) : emptyRecovery(cwd)
   };
 }
@@ -37972,26 +38108,40 @@ function runtimeRpcCompatibilityIssueFromHealth(cwd, client, health) {
   if (!(health && typeof health === "object"))
     return;
   const body = health;
-  if (body.ok !== false || body.error !== "runtime RPC version mismatch")
-    return;
   const connection = client.connectionInfo();
   const pid = typeof connection.pid === "number" ? connection.pid : undefined;
-  return {
-    reason: "rpc-version-mismatch",
-    expected: RUNTIME_RPC_VERSION,
-    received: typeof body.expected === "string" ? body.expected : "unknown",
+  const location = {
     connectionPath: connection.connectionPath ?? defaultDaemonConnectionPath(cwd),
     lockPath: connection.lockPath ?? defaultDaemonLockPath(cwd),
     pid,
     pidAlive: pid !== undefined ? isPidAlive(pid) : false,
     upgradeCommand: "archctx daemon upgrade"
   };
+  if (body.ok === true) {
+    const expected = productVersionManifest().product.version;
+    const received = typeof body.product?.product?.version === "string" ? body.product.product.version : "unknown";
+    return received === expected ? undefined : {
+      reason: "product-version-mismatch",
+      expected,
+      received,
+      ...location
+    };
+  }
+  if (body.ok !== false || body.error !== "runtime RPC version mismatch")
+    return;
+  return {
+    reason: "rpc-version-mismatch",
+    expected: RUNTIME_RPC_VERSION,
+    received: typeof body.expected === "string" ? body.expected : "unknown",
+    ...location
+  };
 }
 function incompatibleDaemonStatus(issue) {
   return {
     running: issue.pidAlive,
     protocol: "http-loopback",
-    rpcVersionCompatible: false,
+    rpcVersionCompatible: issue.reason === "product-version-mismatch",
+    productVersionCompatible: issue.reason !== "product-version-mismatch",
     connectionPath: issue.connectionPath,
     lockPath: issue.lockPath,
     pid: issue.pid,
@@ -38008,6 +38158,9 @@ function runtimeVersionUnsupportedMessage(issue) {
   if (issue.reason === "stale-daemon-entry") {
     return `archctxd (pid ${issue.pid ?? "unknown"}, started ${issue.received}) was spawned from an older copy of the archctx entrypoint than the one running this command (modified ${issue.expected}); run ${issue.upgradeCommand} to replace the local daemon.`;
   }
+  if (issue.reason === "product-version-mismatch") {
+    return `archctxd product version ${issue.received} does not exactly match this CLI (${issue.expected}); run ${issue.upgradeCommand} to replace the local daemon.`;
+  }
   return `archctxd RPC version ${issue.received} is incompatible with this CLI (${issue.expected}); run ${issue.upgradeCommand} to replace the local daemon.`;
 }
 async function waitForPidExit(pid, timeoutMs) {

package/package.json

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