@akanjs/devkit 3.2.0-rc.0 → 3.2.0-rc.10

package/akanApp/akanApp.host.test.ts

@@ -143,3 +143,130 @@ describe("a gateway whose replica crash-loops", () => {
     ]);
   });
 });
+
+describe("a builder request while no builder is running", () => {
+  isolateEnv({ AKAN_PUBLIC_REPO_NAME: "repo", AKAN_PUBLIC_SERVE_DOMAIN: "localhost", AKAN_PUBLIC_ENV: "local" });
+  const track = tempRoots();
+  const stoppedBuilder = {
+    status: "stopped",
+    patcherOff: false,
+    start: ({ onReady }: { onReady?: () => void }) => onReady?.(),
+    send: () => false,
+    stop: () => undefined,
+  } as unknown as IncrementalBuilderHost;
+
+  test("is answered at once and marked unavailable, so the backend can tell it from a failed build", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    const replyPath = path.join(root, "reply.json");
+    await writeText(
+      path.join(root, "apps/demo/main.ts"),
+      [
+        'import fs from "node:fs";',
+        `const replyPath = ${JSON.stringify(replyPath)};`,
+        'process.on("message", (message) => {',
+        '  if (message?.type !== "build-graph-res") return;',
+        '  fs.writeFileSync(replyPath + ".tmp", JSON.stringify(message));',
+        '  fs.renameSync(replyPath + ".tmp", replyPath);',
+        "});",
+        'process.send?.({ type: "backend-ready", pid: process.pid });',
+        'process.send?.({ type: "build-graph", id: 7 });',
+        "setInterval(() => undefined, 1_000);",
+        "",
+      ].join("\n"),
+    );
+    const create = IncrementalBuilderHost.create;
+    IncrementalBuilderHost.create = async () => stoppedBuilder;
+    const host = new AkanAppHost(app, { env: { ...process.env } as Record<string, string> });
+    try {
+      await host.start();
+      const deadline = performance.now() + 5_000;
+      while (!(await Bun.file(replyPath).exists()) && performance.now() < deadline) await Bun.sleep(25);
+      expect(await Bun.file(replyPath).json()).toEqual({
+        type: "build-graph-res",
+        id: 7,
+        ok: false,
+        error: "builder is stopped; reload after the builder is ready",
+        kind: "unavailable",
+      });
+    } finally {
+      await host.stop();
+      IncrementalBuilderHost.create = create;
+    }
+  });
+});
+
+describe("a stop while the builder is starting", () => {
+  isolateEnv({ AKAN_PUBLIC_REPO_NAME: "repo", AKAN_PUBLIC_SERVE_DOMAIN: "localhost", AKAN_PUBLIC_ENV: "local" });
+  const track = tempRoots();
+  const fakeBuilder = (onStart: (options: { onReady?: () => void; onExit?: () => void }) => void = () => undefined) => {
+    const builder = {
+      status: "starting",
+      patcherOff: false,
+      started: 0,
+      stopped: 0,
+      start: (options: { onReady?: () => void; onExit?: () => void }) => {
+        builder.started += 1;
+        onStart(options);
+      },
+      send: () => false,
+      stop: () => {
+        builder.stopped += 1;
+      },
+    };
+    return builder;
+  };
+
+  test("stops a builder created after the stop, and never starts it", async () => {
+    const { app } = track(await createTempApp("demo"));
+    const builder = fakeBuilder();
+    const created = Promise.withResolvers<IncrementalBuilderHost>();
+    const create = IncrementalBuilderHost.create;
+    let creates = 0;
+    IncrementalBuilderHost.create = async () => {
+      creates += 1;
+      return await created.promise;
+    };
+    const host = new AkanAppHost(app, { env: { ...process.env } as Record<string, string> });
+    try {
+      const starting = host.start();
+      await Bun.sleep(50);
+      await host.stop();
+      created.resolve(builder as unknown as IncrementalBuilderHost);
+      await expect(starting).rejects.toThrow("dev server stopped before the builder started");
+      expect({ creates, started: builder.started, stopped: builder.stopped }).toEqual({
+        creates: 1,
+        started: 0,
+        stopped: 1,
+      });
+    } finally {
+      IncrementalBuilderHost.create = create;
+    }
+  });
+
+  test("gives up a builder still booting at once instead of retrying after its ready timeout", async () => {
+    const { app } = track(await createTempApp("demo"));
+    let exitLate: (() => void) | undefined;
+    const builder = fakeBuilder(({ onExit }) => {
+      exitLate = onExit;
+    });
+    const create = IncrementalBuilderHost.create;
+    let creates = 0;
+    IncrementalBuilderHost.create = async () => {
+      creates += 1;
+      return builder as unknown as IncrementalBuilderHost;
+    };
+    const host = new AkanAppHost(app, { env: { ...process.env } as Record<string, string> });
+    try {
+      const starting = host.start();
+      await Bun.sleep(50);
+      expect(builder.started).toBe(1);
+      await host.stop();
+      await expect(starting).rejects.toThrow("dev server stopped before the builder was ready");
+      exitLate?.();
+      await Bun.sleep(50);
+      expect({ creates, stopped: builder.stopped }).toEqual({ creates: 1, stopped: 1 });
+    } finally {
+      IncrementalBuilderHost.create = create;
+    }
+  });
+});

package/akanApp/akanApp.host.ts

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { Logger } from "akanjs/common";
+import { Logger, RestartSchedule } from "akanjs/common";
 import type { BuilderMessage, BuilderMetrics, BuildPhase, ChangeBatch, DevBuildStatus } from "akanjs/server";
 import type { App } from "../commandDecorators";
 import { createTunnel } from "../createTunnel";
@@ -15,6 +15,7 @@ import {
   type BackendLifecycleState,
   type BackendRestartReason,
   BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS,
+  backendRecoveryPolicy,
   backendRestartReasonFromMessage,
   buildStatusReplaySequence,
   createBackendBuildStatus,
@@ -35,7 +36,6 @@ import {
   redisTunnelPolicy,
   resolveIdleSuspendMs,
   type SourceFingerprints,
-  shouldAbandonBackendRecovery,
   shouldHoldForReturningBuilder,
   shouldKeepBuildFailure,
   shouldMarkBuildPhaseRecovered,
@@ -59,10 +59,6 @@ const BACKEND_RESTART_DEBOUNCE_MS = 120;
 // Above the gateway's ~5s child-shutdown wait: a gateway SIGKILLed mid-shutdown strands orphan replicas.
 const BACKEND_GRACEFUL_TIMEOUT_MS = 8_000;
 
-const BACKEND_RECOVERY_BASE_DELAY_MS = 1_000;
-
-const BACKEND_RECOVERY_MAX_DELAY_MS = 30_000;
-
 const BACKEND_STDERR_TAIL_LIMIT = 40;
 
 const BUILDER_READY_TIMEOUT_MS = 150000;
@@ -77,11 +73,6 @@ const BUILDER_RSS_SETTLE_MS = 20_000;
 
 const PS_RSS_TIMEOUT_MS = 2_000;
 
-// The builder is the file watcher, so unlike the backend its recovery never gives up; it only backs off.
-const BUILDER_RECOVERY_BASE_DELAY_MS = 2_000;
-
-const BUILDER_RECOVERY_MAX_DELAY_MS = 60_000;
-
 interface LastGoodFrontendState {
   pages?: Extract<BuilderMessage, { type: "pages-updated" }>;
   css?: Extract<BuilderMessage, { type: "css-updated" }>;
@@ -101,8 +92,7 @@ export class AkanAppHost {
   #backendReady = false;
   #plannedBackendStops = new WeakSet<Bun.Subprocess<"ignore", "inherit", "inherit">>();
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
-  #backendRecoveryTimer: ReturnType<typeof setTimeout> | null = null;
-  #backendRecoveryAttempts = 0;
+  readonly #backendRecovery = new RestartSchedule(backendRecoveryPolicy);
   #backendGaveUp = false;
   #backendLifecycleState: BackendLifecycleState = "stopped";
   #pendingRestartReason: BackendRestartReason | null = null;
@@ -119,8 +109,9 @@ export class AkanAppHost {
   //? its recovery, reported past the failure's generation so the scan overlay clears.
   #restartFailedAfterApply: number | null = null;
   #stopping = false;
-  #builderRecoveryTimer: ReturnType<typeof setTimeout> | null = null;
-  #builderRecoveryAttempts = 0;
+  //? The builder is the file watcher, so unlike the backend its recovery never gives up; it only backs off.
+  readonly #builderRecovery = new RestartSchedule({ min: 2_000, max: 60_000 });
+  #abandonBuilderStart: ((error: Error) => void) | null = null;
   #backendStartStatus: { generation?: number; files: string[] } | null = null;
   #backendBuildStatusGeneration = 0;
   #backendStderrTail: string[] = [];
@@ -186,6 +177,8 @@ export class AkanAppHost {
     this.#cancelIdleSuspend();
     this.#stopIdleWatcher();
     this.#clearRestartTimers();
+    //? A stopped builder sends no exit: a start waiting for its ready would sit out the ready timeout, then retry.
+    this.#abandonBuilderStart?.(new Error("dev server stopped before the builder was ready"));
     this.#pendingRestartReason = null;
     // Before the backend goes away, while it can still receive the answer.
     this.#failPendingBuilderMessages("dev server is shutting down");
@@ -195,9 +188,10 @@ export class AkanAppHost {
     return this;
   }
   #clearRestartTimers() {
-    for (const timer of [this.#restartTimer, this.#backendRecoveryTimer, this.#builderRecoveryTimer])
-      if (timer) clearTimeout(timer);
-    this.#restartTimer = this.#backendRecoveryTimer = this.#builderRecoveryTimer = null;
+    if (this.#restartTimer) clearTimeout(this.#restartTimer);
+    this.#restartTimer = null;
+    this.#backendRecovery.cancel();
+    this.#builderRecovery.cancel();
   }
   kill() {
     void this.stop();
@@ -239,7 +233,7 @@ export class AkanAppHost {
         if (!msg || typeof msg !== "object") return;
         if (msg.type === "backend-ready") {
           this.#backendReady = true;
-          this.#backendRecoveryAttempts = 0;
+          this.#backendRecovery.reset();
           this.#setBackendLifecycleState("ready", `pid=${msg.pid}`);
           this.#recordBackendReadyStatus();
           this.logger.verbose(`backend ready pid=${msg.pid}`);
@@ -402,10 +396,7 @@ export class AkanAppHost {
       "restart-pending",
       `generation=${pending.generation ?? "(unknown)"} files=${pending.files.length} roles=${pending.roles.join(",") || "(none)"}`,
     );
-    if (this.#backendRecoveryTimer) {
-      clearTimeout(this.#backendRecoveryTimer);
-      this.#backendRecoveryTimer = null;
-    }
+    this.#backendRecovery.cancel();
     if (this.#restartTimer) clearTimeout(this.#restartTimer);
     this.#restartTimer = setTimeout(() => {
       this.#restartTimer = null;
@@ -426,16 +417,16 @@ export class AkanAppHost {
     this.logger.verbose(
       `[backend-reload] restarting backend generation=${reason.generation ?? "(unknown)"} files=${reason.files.length} roles=${reason.roles.join(",") || "(none)"}`,
     );
-    this.#backendRecoveryAttempts = 0;
+    this.#backendRecovery.reset();
     await Promise.all([this.#stopBackend(), this.#backendGraph.refresh()]);
     this.#startBackend({ generation: reason.generation, files: reason.files });
   }
   #scheduleBackendRecovery(reason: string) {
-    if (this.#backendRecoveryTimer || this.#backend) return;
-    if (shouldAbandonBackendRecovery(this.#backendRecoveryAttempts)) {
-      const message = `Backend exited ${this.#backendRecoveryAttempts} times in a row (${reason}); waiting for an edit or a green build to retry.`;
+    if (this.#backendRecovery.pending || this.#backend) return;
+    if (this.#backendRecovery.exhausted) {
+      const message = `Backend exited ${this.#backendRecovery.attempts} times in a row (${reason}); waiting for an edit or a green build to retry.`;
       this.#backendGaveUp = true;
-      this.#setBackendLifecycleState("stopped", `gave up after ${this.#backendRecoveryAttempts} recovery attempts`);
+      this.#setBackendLifecycleState("stopped", `gave up after ${this.#backendRecovery.attempts} recovery attempts`);
       this.logger.error(`[backend-recovery] ${message}`);
       if (this.#backendStderrTail.length > 0) {
         this.logger.error(`[backend-recovery] recent backend stderr:\n${this.#backendStderrTail.join("\n")}`);
@@ -445,9 +436,7 @@ export class AkanAppHost {
       return;
     }
     this.#setBackendLifecycleState("recovering", reason);
-    const attempt = this.#backendRecoveryAttempts;
-    const delay = Math.min(BACKEND_RECOVERY_BASE_DELAY_MS * 2 ** attempt, BACKEND_RECOVERY_MAX_DELAY_MS);
-    this.#backendRecoveryAttempts = attempt + 1;
+    const delay = this.#backendRecovery.next();
     const failureStatus = this.#recordBackendBuildStatus({
       ok: false,
       files: [],
@@ -455,18 +444,17 @@ export class AkanAppHost {
     });
     this.#sendOrQueueBuildStatus(failureStatus);
     this.logger.warn(
-      `[backend-recovery] backend exited unexpectedly (${reason}); restarting in ${delay}ms (attempt ${this.#backendRecoveryAttempts})`,
+      `[backend-recovery] backend exited unexpectedly (${reason}); restarting in ${delay}ms (attempt ${this.#backendRecovery.attempts})`,
     );
     if (this.#backendStderrTail.length > 0) {
       this.logger.warn(`[backend-recovery] recent backend stderr:\n${this.#backendStderrTail.join("\n")}`);
     }
-    this.#backendRecoveryTimer = setTimeout(() => {
-      this.#backendRecoveryTimer = null;
+    this.#backendRecovery.arm(delay, () => {
       if (this.#backend) return;
       void this.#backendGraph.refresh().finally(() => {
         if (!this.#backend) this.#startBackend({ generation: failureStatus.generation, files: failureStatus.files });
       });
-    }, delay);
+    });
   }
   #enqueueBuilderMessage(message: BuilderMessage) {
     this.#builderMessageQueue = this.#builderMessageQueue
@@ -763,8 +751,8 @@ export class AkanAppHost {
       this.#pendingRecycle ||
       this.#restartTimer ||
       this.#backendRestart ||
-      this.#backendRecoveryTimer ||
-      this.#builderRecoveryTimer ||
+      this.#backendRecovery.pending ||
+      this.#builderRecovery.pending ||
       this.#rssRecycleReason
     );
   }
@@ -922,11 +910,11 @@ export class AkanAppHost {
   }
   #failBuilderRequest(message: BuilderMessage, error: string): boolean {
     if (message.type === "build-route")
-      this.#sendToBackend({ type: "build-route-res", id: message.id, ok: false, error });
+      this.#sendToBackend({ type: "build-route-res", id: message.id, ok: false, error, kind: "unavailable" });
     else if (message.type === "build-csr")
-      this.#sendToBackend({ type: "build-csr-res", id: message.id, ok: false, error });
+      this.#sendToBackend({ type: "build-csr-res", id: message.id, ok: false, error, kind: "unavailable" });
     else if (message.type === "build-graph")
-      this.#sendToBackend({ type: "build-graph-res", id: message.id, ok: false, error });
+      this.#sendToBackend({ type: "build-graph-res", id: message.id, ok: false, error, kind: "unavailable" });
     else return false;
     return true;
   }
@@ -1024,28 +1012,25 @@ export class AkanAppHost {
     this.#scheduleBuilderRecovery({ generation, files: message.files });
   }
   #scheduleBuilderRecovery(reason: { generation?: number; files: string[] }): void {
-    if (this.#builderRecoveryTimer || this.#builder) return;
-    const attempt = this.#builderRecoveryAttempts;
-    const delay = Math.min(BUILDER_RECOVERY_BASE_DELAY_MS * 2 ** attempt, BUILDER_RECOVERY_MAX_DELAY_MS);
-    this.#builderRecoveryAttempts = attempt + 1;
+    if (this.#stopping || this.#builderRecovery.pending || this.#builder) return;
+    const delay = this.#builderRecovery.schedule(() => {
+      if (this.#stopping || this.#builder) return;
+      void this.#recoverBuilder(reason);
+    });
     this.logger.warn(
-      `[builder-recovery] builder is down; retrying start in ${delay}ms (attempt ${this.#builderRecoveryAttempts})`,
+      `[builder-recovery] builder is down; retrying start in ${delay}ms (attempt ${this.#builderRecovery.attempts})`,
     );
-    this.#builderRecoveryTimer = setTimeout(() => {
-      this.#builderRecoveryTimer = null;
-      if (this.#builder) return;
-      void this.#recoverBuilder(reason);
-    }, delay);
   }
   async #recoverBuilder(reason: { generation?: number; files: string[] }): Promise<void> {
     try {
       await this.#startBuilder();
     } catch (err) {
+      if (this.#stopping) return;
       this.logger.warn(`[builder-recovery] builder start failed: ${err instanceof Error ? err.message : String(err)}`);
       this.#scheduleBuilderRecovery(reason);
       return;
     }
-    this.#builderRecoveryAttempts = 0;
+    this.#builderRecovery.reset();
     this.logger.info("[builder-recovery] builder recovered");
     void this.#restartBackendForGapChanges();
     const failedAfterApply = this.#restartFailedAfterApply;
@@ -1062,14 +1047,14 @@ export class AkanAppHost {
     };
     this.#recordBuildStatus(status);
     this.#sendOrQueueBuildStatus(status);
-    if (!this.#backend && !this.#backendRecoveryTimer) {
+    if (!this.#backend && !this.#backendRecovery.pending) {
       this.#startBackend({ generation: reason.generation, files: reason.files });
     }
   }
   #reviveBackendAfterGreenBuild(status: DevBuildStatus): void {
-    if (!status.ok || !this.#backendGaveUp || this.#backend || this.#backendRecoveryTimer) return;
+    if (!status.ok || !this.#backendGaveUp || this.#backend || this.#backendRecovery.pending) return;
     this.logger.info(`[backend-recovery] build went green (generation=${status.generation}); retrying backend`);
-    this.#backendRecoveryAttempts = 0;
+    this.#backendRecovery.reset();
     this.#startBackend({ generation: status.generation, files: status.files });
   }
   async #restartDevChildren(message: Extract<BuilderMessage, { type: "invalidate" }>): Promise<void> {
@@ -1097,7 +1082,7 @@ export class AkanAppHost {
   ): Promise<void> {
     const generation = message.devPlan?.generation ?? message.generation;
     this.#clearRestartTimers();
-    this.#builderRecoveryAttempts = 0;
+    this.#builderRecovery.reset();
     this.#pendingRestartReason = null;
     await this.#backendRestart;
     this.#lastGoodFrontend = {};
@@ -1232,7 +1217,7 @@ export class AkanAppHost {
     this.app.verbose(`[cli] waiting for builder to complete initial base build…`);
     let lastError: unknown;
     for (let attempt = 1; attempt <= BUILDER_START_MAX_ATTEMPTS; attempt++) {
-      this.#builder = await IncrementalBuilderHost.create(
+      const builder = await IncrementalBuilderHost.create(
         this.app,
         this.env,
         (msg) => {
@@ -1244,6 +1229,11 @@ export class AkanAppHost {
           patcherOff: this.#patcherOff,
         },
       );
+      if (this.#stopping) {
+        builder.stop();
+        throw new Error("dev server stopped before the builder started");
+      }
+      this.#builder = builder;
       try {
         await this.#waitForBuilderReady(attempt, { announceBootState });
         this.app.verbose(`[cli] base build ready in ${Date.now() - startTime}ms — starting backend`);
@@ -1251,7 +1241,7 @@ export class AkanAppHost {
       } catch (err) {
         lastError = err;
         this.#stopBuilder();
-        if (attempt >= BUILDER_START_MAX_ATTEMPTS) break;
+        if (attempt >= BUILDER_START_MAX_ATTEMPTS || this.#stopping) break;
         this.app.verbose(`[cli] builder failed before ready; retrying (${attempt + 1}/${BUILDER_START_MAX_ATTEMPTS})`);
       }
     }
@@ -1269,8 +1259,11 @@ export class AkanAppHost {
         if (settled) return;
         settled = true;
         clearTimeout(timeout);
+        if (this.#abandonBuilderStart === abandon) this.#abandonBuilderStart = null;
         fn();
       };
+      const abandon = (error: Error) => settle(() => reject(error));
+      this.#abandonBuilderStart = abandon;
       const timeout = setTimeout(() => {
         settle(() => reject(new Error("[cli] builder timed out before emitting builder-ready")));
       }, BUILDER_READY_TIMEOUT_MS);

package/akanApp/devHostPolicy.test.ts

@@ -1,8 +1,10 @@
 import { describe, expect, test } from "bun:test";
+import { RestartSchedule } from "akanjs/common";
 import type { BuilderMessage, BuildPhase, DevBuildStatus, DevChangeAction } from "akanjs/server";
 //? The source itself, not the package: the published akanjs exports no such subpath, and tests are not bundled.
 import { DevBuildRecovery } from "../../../akanjs/server/artifact/devBuildRecovery";
 import {
+  backendRecoveryPolicy,
   backendRestartReasonFromMessage,
   buildStatusReplaySequence,
   createBackendBuildStatus,
@@ -18,7 +20,6 @@ import {
   normalizeBackendReportedGeneration,
   redisTunnelPolicy,
   resolveIdleSuspendMs,
-  shouldAbandonBackendRecovery,
   shouldHoldForReturningBuilder,
   shouldKeepBuildFailure,
   shouldMarkBuildPhaseRecovered,
@@ -489,16 +490,15 @@ describe("legacy backend graph fallback", () => {
 });
 
 describe("backend recovery abandonment", () => {
-  test("keeps retrying below the attempt ceiling and abandons at it", () => {
-    expect(shouldAbandonBackendRecovery(0)).toBe(false);
-    expect(shouldAbandonBackendRecovery(4)).toBe(false);
-    expect(shouldAbandonBackendRecovery(5)).toBe(true);
-    expect(shouldAbandonBackendRecovery(9)).toBe(true);
-  });
-
-  test("honors a custom attempt ceiling", () => {
-    expect(shouldAbandonBackendRecovery(2, 3)).toBe(false);
-    expect(shouldAbandonBackendRecovery(3, 3)).toBe(true);
+  test("backs off from 1s and gives up after five failed restarts in a row", () => {
+    const recovery = new RestartSchedule(backendRecoveryPolicy);
+    const delays = [1, 2, 3, 4].map(() => recovery.next());
+    expect(recovery.exhausted).toBe(false);
+    delays.push(recovery.next());
+    expect(delays).toEqual([1_000, 2_000, 4_000, 8_000, 16_000]);
+    expect(recovery.exhausted).toBe(true);
+    recovery.reset();
+    expect(recovery.exhausted).toBe(false);
   });
 });
 

package/akanApp/devHostPolicy.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import type { RestartPolicy } from "akanjs/common";
 import type {
   BuilderMessage,
   BuildPhase,
@@ -20,7 +21,7 @@ export const redisTunnelPolicy = ({
 }): "none" | "optional" | "required" =>
   environment === "local" ? "none" : databaseMode === "single" ? "optional" : "required";
 
-const BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
+export const backendRecoveryPolicy: RestartPolicy = { min: 1_000, max: 30_000, maxAttempts: 5 };
 
 // A page load asks for several routes, but a builder that never returns must not grow the hold queue unbounded.
 const HELD_BUILDER_REQUEST_LIMIT = 64;
@@ -57,9 +58,6 @@ export const shouldRestartBackendByDevPlan = (
 export const shouldRestartBuilderByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
   message.devPlan?.actions.includes("restart-builder") ?? false;
 
-export const shouldAbandonBackendRecovery = (attempts: number, maxAttempts = BACKEND_RECOVERY_MAX_ATTEMPTS): boolean =>
-  attempts >= maxAttempts;
-
 /** The gateway reports backend failures with `generation: -1`; the host assigns its own counter then. */
 export const normalizeBackendReportedGeneration = (generation: number): number | undefined =>
   generation >= 0 ? generation : undefined;

package/akanContext.ts

@@ -4,6 +4,7 @@ import { capitalize, isRecord, parseRouteModuleKey } from "akanjs/common";
 import { extractBlockVersion, readDevkitVersion } from "./agentsIndex";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
+import { unlabeledFieldNames } from "./moduleFieldNames";
 import { collectRecipeSources, findInlineRecipeDuplicates, scanRecipes } from "./recipeScanner";
 import type { PackageJson } from "./types";
 import {
@@ -337,9 +338,6 @@ const moduleShapeFiles = (module: AkanModuleContext) => {
   ];
 };
 
-const constantFieldNames = (content: string) =>
-  [...content.matchAll(/\b([A-Za-z_$][\w$]*)\s*:\s*field\(/g)].map((match) => match[1]).filter(Boolean);
-
 const safeReadDir = async (dirPath: string) =>
   (await readdir(dirPath, { withFileTypes: true }).catch(() => [])).sort((a, b) => a.name.localeCompare(b.name));
 
@@ -853,8 +851,7 @@ export class AkanContextAnalyzer {
             safeReadText(dictionaryPath),
           ]);
           if (constantContent && dictionaryContent) {
-            for (const fieldName of constantFieldNames(constantContent)) {
-              if (new RegExp(`\\b${fieldName}\\s*:`).test(dictionaryContent)) continue;
+            for (const fieldName of unlabeledFieldNames(constantContent, dictionaryContent)) {
               report(
                 {
                   severity: "warning",

package/akanMcpContract.ts

@@ -2,6 +2,7 @@ import { lstatSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { isRecord } from "akanjs/common";
 import { AkanContextAnalyzer, type AkanDiagnostic, type AkanModuleContext } from "./akanContext";
+import { AkanMcpToolError } from "./akanMcpToolError";
 import type { Workspace } from "./commandDecorators";
 import type {
   AkanContextEvidence,
@@ -172,7 +173,8 @@ export const workflowArtifactPath = (workspace: Workspace, filePath: string) =>
       ? path.join(root, "runs", `${filePath}.json`)
       : path.resolve(workspace.workspaceRoot, filePath);
   if (!isInside(root, resolved) || !staysInside(workspace.workspaceRoot, root, resolved))
-    throw new Error(
+    throw new AkanMcpToolError(
+      "invalidArgument",
       `MCP workflow files live under ${workflowArtifactDir}/ of the workspace, not ${JSON.stringify(filePath)}.`,
     );
   return resolved;
@@ -199,7 +201,7 @@ export const defaultWorkflowPlanPath = (workflow: string, inputs: WorkflowPlanIn
 export const applyFirstPolicy = {
   mode: "apply-first",
   directSourceEdits: "fallback-only",
-  applyRequiredWhen: ["plan_workflow returns planPath", "plan_workflow returns next.tool=apply_workflow"],
+  applyRequiredWhen: ["plan_workflow returns next.tool=apply_workflow"],
   approvalMeaning:
     "requiresApproval is an agent/user review signal before apply_workflow mutates files; it is not a separate MCP permission gate.",
   validationRequiredAfterApply: ["validationTarget", "applyReportPath"],
@@ -213,7 +215,8 @@ export const applyFirstPolicy = {
 
 export const stringArg = (args: Record<string, unknown>, key: string) => {
   const value = args[key];
-  if (typeof value !== "string" || !value) throw new Error(`MCP tool argument "${key}" is required.`);
+  if (typeof value !== "string" || !value)
+    throw new AkanMcpToolError("invalidArgument", `MCP tool argument "${key}" is required.`);
   return value;
 };
 
@@ -226,13 +229,20 @@ export const workflowInputsArg = (args: Record<string, unknown>) => {
 export const inspectAkanContextPropsArg = (args: Record<string, unknown>): InspectAkanContextProps => {
   const question = stringArg(args, "question");
   const review = stringArg(args, "review");
-  if (!isRecord(args.draft)) throw new Error('MCP tool argument "draft" is required.');
-  if (!isRecord(args.request)) throw new Error('MCP tool argument "request" is required.');
+  if (!isRecord(args.draft)) throw new AkanMcpToolError("invalidArgument", 'MCP tool argument "draft" is required.');
+  if (!isRecord(args.request))
+    throw new AkanMcpToolError("invalidArgument", 'MCP tool argument "request" is required.');
   if (!isInspectAkanContextRequestType(args.draft.type)) {
-    throw new Error('MCP tool argument "draft.type" must be a supported inspect_akan_context request type.');
+    throw new AkanMcpToolError(
+      "invalidArgument",
+      'MCP tool argument "draft.type" must be a supported inspect_akan_context request type.',
+    );
   }
   if (!isInspectAkanContextRequestType(args.request.type)) {
-    throw new Error('MCP tool argument "request.type" must be a supported inspect_akan_context request type.');
+    throw new AkanMcpToolError(
+      "invalidArgument",
+      'MCP tool argument "request.type" must be a supported inspect_akan_context request type.',
+    );
   }
   const base = { question, draft: { reason: stringArg(args.draft, "reason"), type: args.draft.type }, review };
   const request = args.request;
@@ -324,7 +334,7 @@ export const readonlyMcpTools: McpToolDefinition[] = [
   {
     name: "get_graph",
     description:
-      "Read-only Akan Graph from source, no dev server needed: models with their fields and relations, slices and endpoints with the guards they name (each guard keyed by the app or lib that declares it, with its scope and the comment that says what it checks), the service methods and queries each calls, the store actions that fetch them, and the components and routes that use them. A module's jobs (internal: interval, cron, timeout, initialize, destroy, process) read their schedule and server or operation modes and call service methods like endpoints do; each adaptor a service plugs (an adapt() class, or an akanjs role) is a node, a method that calls it links to it, and an adaptor links to the adaptors it plugs itself. Each page/ file is a route (its URL pattern after the locale) or a layout, layouts wrap what they contain, and a route or layout that runs .guard() reads `guard` and links each function its guard calls; a layout's guard gates every route it wraps. A graph too large to answer unscoped drops first the routes and layouts that neither changed nor use a change; app or module brings them back. Every node and edge carries its source location. Pass app and/or module to scope a large workspace. Pass since (a git revision such as main, or HEAD for uncommitted work) for the Change Map instead: what changed since HEAD forked from it, working tree included, with each node, field and edge marked added, removed or changed, the unchanged neighbours they call or are called by, and the changed files no node covers, each marked the same way.",
+      "Read-only Akan Graph from source, no dev server needed: models with their fields and relations, slices and endpoints with the guards they name (each guard keyed by the app or lib that declares it, with its scope and the comment that says what it checks), the service methods and queries each calls, the store actions that fetch them, and the components and routes that use them. A module's jobs (internal: interval, cron, timeout, initialize, destroy, process) read their schedule and server or operation modes and call service methods like endpoints do; each adaptor a service plugs (an adapt() class, or an akanjs role) is a node, a method that calls it links to it (an app service holds the fields its module's lib services plug, unless it declares the field itself), an adaptor links to the adaptors it plugs itself, a class from a package outside the workspace is adaptor:<package>:<Name>, and a role an app binds with applyAdaptor(Role, Impl) links to that implementation (binds, labelled with the app; a scope keeps its app's bindings). Each page/ file is a route (its URL pattern after the locale) or a layout, layouts wrap what they contain, and a route or layout that runs .guard() reads `guard` and links each function its guard calls; a layout's guard gates every route it wraps. A graph too large to answer unscoped drops first the routes and layouts that neither changed nor use a change; app or module brings them back. Every node and edge carries its source location. Pass app and/or module to scope a large workspace. Pass since (a git revision such as main, or HEAD for uncommitted work) for the Change Map instead: what changed since HEAD forked from it, working tree included, with each node, field and edge marked added, removed or changed, the unchanged neighbours they call or are called by, and the changed files no node covers, each marked the same way.",
     inputSchema: { type: "object", properties: { app: stringProperty, module: stringProperty, since: stringProperty } },
   },
   {
@@ -371,7 +381,7 @@ export const planMcpTools: McpToolDefinition[] = [
   {
     name: "plan_workflow",
     description:
-      "Create a read-only workflow plan after context inspection and return planPath plus next.tool=apply_workflow.",
+      "Create a read-only workflow plan after context inspection and return planPath, plus next.tool=apply_workflow unless a diagnostic is an error.",
     inputSchema: {
       type: "object",
       properties: { workflow: stringProperty, inputs: objectProperty, out: stringProperty },
@@ -383,7 +393,8 @@ export const planMcpTools: McpToolDefinition[] = [
 export const applyMcpTools: McpToolDefinition[] = [
   {
     name: "apply_workflow",
-    description: "Apply a stored workflow plan before direct edits and return validationTarget for run_validation.",
+    description:
+      "Apply a stored workflow plan before direct edits and return validationTarget. Unless it failed, next.tool is run_validation after an apply and apply_workflow without dryRun after a dry run.",
     inputSchema: {
       type: "object",
       properties: { planPath: stringProperty, dryRun: booleanProperty },

package/akanMcpToolError.ts

@@ -0,0 +1,16 @@
+import { AkanError } from "akanjs/base";
+import type { McpFailure } from "akanjs/common";
+
+export type AkanMcpToolErrorCode = "invalidArgument" | "toolUnavailable" | "unknownTool";
+
+export class AkanMcpToolError extends AkanError<AkanMcpToolErrorCode> {
+  constructor(code: AkanMcpToolErrorCode, message: string) {
+    super(code, message, { statusCode: 400 });
+  }
+
+  static failureOf(error: unknown): McpFailure {
+    return AkanError.is(error)
+      ? { code: error.code, statusCode: error.statusCode }
+      : { code: "toolFailed", statusCode: 500 };
+  }
+}