archctx 0.4.5 → 0.4.7

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.7",
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "entries": [
     {
@@ -389,5 +389,5 @@
     "structurizr.dsl",
     "twelve-factor"
   ],
-  "catalogDigest": "sha256:9687f9aabf24904bb08a174a9c0a83664d437bd0862bf0c7725faf2c11bbb913"
+  "catalogDigest": "sha256:557e42cbb594f7f2244b78847ab8d442f02977d5a08742a5c9576c051b1405b4"
 }

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.7", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.3.10", 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/validator.ts
 function validateJsonSchema(schema, value) {
@@ -10397,13 +10397,21 @@ function diagnostics() {
   const egress = localEgressStatus();
   return {
     node: process.version,
-    supportedNode: /^v(24|25)\./.test(process.version),
+    supportedNode: isSupportedNodeVersion(process.version),
     codeGraphVersion: REQUIRED_CODEGRAPH_VERSION,
     privacyRouteDigest: controlPlaneRouteDigest(),
     secureDefaults: secureDefaults(),
     egress
   };
 }
+function isSupportedNodeVersion(version) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(version);
+  if (!match)
+    return false;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  return major < 26 && (major > 22 || major === 22 && minor >= 22);
+}
 function secureDefaults() {
   return {
     tunnelEnabledByDefault: false,
@@ -10449,8 +10457,9 @@ function uninstallMarker(content, host) {
 function dependencyAudit(root) {
   const packageJson = JSON.parse(readFileSync6(resolve6(root, "package.json"), "utf8"));
   const issues = [];
-  if (!packageJson.engines?.node?.includes(">=24"))
-    issues.push("node engine must include >=24");
+  if (packageJson.engines?.node !== ARCHCONTEXT_NODE_RANGE) {
+    issues.push(`node engine must equal ${ARCHCONTEXT_NODE_RANGE}`);
+  }
   return { ok: issues.length === 0, issues };
 }
 function secretScan(root) {
@@ -28492,6 +28501,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 +28676,7 @@ class ArchctxDaemon {
   checkpointBaselines = new Map;
   checkpointCoalesced = new Map;
   changesets = new Map;
+  changeSetWorktreeDigestProfiles = new Map;
   deferredArchitectureChangeFeedFailures = new Map;
   auditRunAbortControllers = new Map;
   landscape;
@@ -29591,6 +29666,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 +29838,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 +29996,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 +32508,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 +32823,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 +35887,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 +37690,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 +37702,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 +37846,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 +37938,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 +37979,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 +38039,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 +38061,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 +38089,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 +38117,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 +38167,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.7",
   "description": "Local architecture context CLI for agentic coding workflows.",
   "private": false,
   "type": "module",
@@ -20,7 +20,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "engines": {
-    "node": ">=24 <26"
+    "node": ">=22.22 <26"
   },
   "dependencies": {
     "@colbymchenry/codegraph": "1.5.0",

package/schemas/runtime/product-version-manifest.schema.json

@@ -22,7 +22,7 @@
       "additionalProperties": false,
       "required": ["node"],
       "properties": {
-        "node": { "const": ">=24 <26" }
+        "node": { "const": ">=22.22 <26" }
       }
     },
     "surfaces": {