@akanjs/devkit 2.3.5-rc.9 → 2.3.6-rc.0

package/akanApp/akanApp.host.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { Logger } from "akanjs/common";
-import type { BuilderMessage } from "akanjs/server";
+import type { BuilderMessage, BuildPhase, DevBuildStatus, DevChangeRole } from "akanjs/server";
 import type { App } from "../commandDecorators";
 import { createTunnel } from "../createTunnel";
 import { WorkspaceExecutor } from "../executors";
@@ -16,6 +16,9 @@ const BUILDER_START_MAX_ATTEMPTS = 3;
 const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 const NON_SOURCE_EXT_RE =
   /\.(css|scss|sass|less|json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav|html)$/i;
+const SERVER_SUFFIXES = [".service.ts", ".document.ts"];
+const SHARED_SUFFIXES = [".constant.ts", ".dictionary.ts", ".signal.ts"];
+const RUNTIME_METADATA_BASENAMES = new Set(["dict.ts", "sig.ts", "useClient.ts", "useServer.ts"]);
 const GRAPH_IMPORT_KINDS = new Set<Bun.ImportKind>([
   "import-statement",
   "require-call",
@@ -23,6 +26,122 @@ const GRAPH_IMPORT_KINDS = new Set<Bun.ImportKind>([
   "dynamic-import",
 ]);
 
+export const shouldRestartBackendByDevPlan = (
+  message: Extract<BuilderMessage, { type: "invalidate" }>,
+): boolean | null => {
+  if (!message.devPlan) return null;
+  if (message.devPlan.actions.includes("report-error")) return false;
+  return message.devPlan.actions.includes("restart-backend");
+};
+
+export const shouldRestartDevHostByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
+  message.devPlan?.actions.includes("restart-dev-host") ?? message.kinds.includes("config");
+
+export type BackendLifecycleState = "starting" | "ready" | "restart-pending" | "stopping" | "recovering" | "stopped";
+
+export interface BackendRestartReason {
+  generation?: number;
+  files: string[];
+  roles: Extract<DevChangeRole, "server" | "shared" | "barrel" | "config">[];
+}
+
+interface LastGoodFrontendState {
+  pages?: Extract<BuilderMessage, { type: "pages-updated" }>;
+  css?: Extract<BuilderMessage, { type: "css-updated" }>;
+}
+
+const RESTART_ROLE_ORDER: BackendRestartReason["roles"] = ["server", "shared", "barrel", "config"];
+
+const generationValue = (generation: number | undefined): number => generation ?? -1;
+
+export const isLegacyBackendFallbackFile = (file: string, workspaceRoot: string): boolean => {
+  const abs = path.resolve(file);
+  const ext = path.extname(abs).toLowerCase();
+  if (!SOURCE_EXTS.has(ext)) return false;
+  const rel = path.relative(path.resolve(workspaceRoot), abs);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return false;
+  const parts = rel.split(path.sep).filter(Boolean);
+  const [scope] = parts;
+  if (scope !== "apps" && scope !== "libs" && scope !== "pkgs") return false;
+
+  const base = path.basename(abs);
+  return (
+    parts.includes("srvkit") ||
+    parts.includes("common") ||
+    SERVER_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||
+    SHARED_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||
+    RUNTIME_METADATA_BASENAMES.has(base) ||
+    base === "main.ts" ||
+    base === "server.ts"
+  );
+};
+
+export const shouldMarkBuildPhaseRecovered = (
+  previousByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
+  status: DevBuildStatus,
+): boolean => {
+  const previous = previousByPhase.get(status.phase);
+  return Boolean(previous && status.ok && !previous.ok && generationValue(status.generation) >= previous.generation);
+};
+
+export const createBackendBuildStatus = ({
+  generation,
+  ok,
+  files = [],
+  message,
+}: {
+  generation: number;
+  ok: boolean;
+  files?: string[];
+  message?: string;
+}): DevBuildStatus => ({
+  generation,
+  phase: "backend",
+  ok,
+  files,
+  message,
+});
+
+export const backendRestartReasonFromMessage = (
+  message: Extract<BuilderMessage, { type: "invalidate" }>,
+): BackendRestartReason => {
+  const roleSet = new Set<BackendRestartReason["roles"][number]>();
+  for (const role of message.devPlan?.roles ?? []) {
+    if (role === "server" || role === "shared" || role === "barrel" || role === "config") roleSet.add(role);
+  }
+  return {
+    generation: message.devPlan?.generation ?? message.generation,
+    files: [...new Set(message.files)].sort(),
+    roles: RESTART_ROLE_ORDER.filter((role) => roleSet.has(role)),
+  };
+};
+
+export const mergeBackendRestartReasons = (
+  current: BackendRestartReason | null,
+  next: BackendRestartReason,
+): BackendRestartReason => ({
+  generation:
+    generationValue(next.generation) >= generationValue(current?.generation) ? next.generation : current?.generation,
+  files: [...new Set([...(current?.files ?? []), ...next.files])].sort(),
+  roles: RESTART_ROLE_ORDER.filter((role) => current?.roles.includes(role) || next.roles.includes(role)),
+});
+
+export const shouldReplaceLastGoodMessage = (
+  current:
+    | Extract<BuilderMessage, { type: "pages-updated" }>
+    | Extract<BuilderMessage, { type: "css-updated" }>
+    | undefined,
+  next: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
+): boolean => !current || generationValue(next.data.generation) >= generationValue(current.data.generation);
+
+export const shouldQueueBuildStatusReplay = (backendReady: boolean, pendingReplayCount: number): boolean =>
+  !backendReady || pendingReplayCount > 0;
+
+export const buildStatusReplaySequence = (
+  pendingReplay: readonly DevBuildStatus[],
+  latestByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
+): DevBuildStatus[] => [...pendingReplay, ...latestByPhase.values()];
+
 class BackendImportGraph {
   readonly #app: App;
   readonly #logger: Logger;
@@ -32,6 +151,7 @@ class BackendImportGraph {
   readonly #jsxTranspiler = new Bun.Transpiler({ loader: "jsx" });
   #files = new Set<string>();
   #ready = false;
+  #lastRefreshSucceeded = false;
 
   constructor(app: App, logger: Logger) {
     this.#app = app;
@@ -42,6 +162,10 @@ class BackendImportGraph {
     return this.#ready;
   }
 
+  get lastRefreshSucceeded() {
+    return this.#lastRefreshSucceeded;
+  }
+
   has(file: string) {
     return this.#files.has(path.resolve(file));
   }
@@ -51,10 +175,12 @@ class BackendImportGraph {
       const files = await this.#build();
       this.#files = files;
       this.#ready = true;
+      this.#lastRefreshSucceeded = true;
       this.#logger.verbose(`[backend-graph] scanned ${files.size} files`);
       return true;
     } catch (err) {
       this.#ready = this.#files.size > 0;
+      this.#lastRefreshSucceeded = false;
       this.#logger.warn(
         `[backend-graph] scan failed; ${this.#ready ? "using previous graph" : "using fallback rules"}: ${err instanceof Error ? err.message : String(err)}`,
       );
@@ -136,9 +262,13 @@ export class AkanAppHost {
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
   #backendRecoveryTimer: ReturnType<typeof setTimeout> | null = null;
   #backendRecoveryAttempts = 0;
-  #restartFiles = new Set<string>();
-  #latestPagesUpdated: Extract<BuilderMessage, { type: "pages-updated" }> | null = null;
-  #latestCssUpdated: Extract<BuilderMessage, { type: "css-updated" }> | null = null;
+  #backendLifecycleState: BackendLifecycleState = "stopped";
+  #pendingRestartReason: BackendRestartReason | null = null;
+  #backendStartStatus: { generation?: number; files: string[] } | null = null;
+  #backendBuildStatusGeneration = 0;
+  #lastGoodFrontend: LastGoodFrontendState = {};
+  #buildStatusByPhase = new Map<BuildPhase, DevBuildStatus>();
+  #pendingBuildStatusReplay: DevBuildStatus[] = [];
   #builderMessageQueue: Promise<void> = Promise.resolve();
   #backendGraph: BackendImportGraph;
   constructor(
@@ -183,7 +313,9 @@ export class AkanAppHost {
     if (environment === "local") return "localhost";
     return await createTunnel(type, { app: this.app, environment });
   }
-  #startBackend() {
+  #startBackend(startStatus: { generation?: number; files: string[] } | null = null) {
+    this.#backendStartStatus = startStatus;
+    this.#setBackendLifecycleState("starting");
     this.#backendReady = false;
     const backend = Bun.spawn(["bun", `apps/${this.app.name}/main.ts`], {
       cwd: this.app.workspace.workspaceRoot,
@@ -194,6 +326,8 @@ export class AkanAppHost {
         if (msg.type === "backend-ready") {
           this.#backendReady = true;
           this.#backendRecoveryAttempts = 0;
+          this.#setBackendLifecycleState("ready", `pid=${msg.pid}`);
+          this.#recordBackendReadyStatus();
           this.logger.verbose(`backend ready pid=${msg.pid}`);
           this.#replayBuilderState();
           return;
@@ -214,9 +348,57 @@ export class AkanAppHost {
     this.#backend = backend;
     this.logger.verbose(`backend spawned pid=${backend.pid}`);
   }
+  #nextBackendBuildStatusGeneration(generation?: number): number {
+    if (typeof generation === "number") {
+      this.#backendBuildStatusGeneration = Math.max(this.#backendBuildStatusGeneration, generation);
+      return generation;
+    }
+    this.#backendBuildStatusGeneration += 1;
+    return this.#backendBuildStatusGeneration;
+  }
+  #recordBackendBuildStatus({
+    generation,
+    ok,
+    files,
+    message,
+  }: {
+    generation?: number;
+    ok: boolean;
+    files?: string[];
+    message?: string;
+  }): DevBuildStatus {
+    const status = createBackendBuildStatus({
+      generation: this.#nextBackendBuildStatusGeneration(generation),
+      ok,
+      files,
+      message,
+    });
+    this.#recordBuildStatus(status);
+    return status;
+  }
+  #recordBackendReadyStatus(): void {
+    const previous = this.#buildStatusByPhase.get("backend");
+    const startStatus = this.#backendStartStatus;
+    if (startStatus || previous?.ok === false) {
+      const status = this.#recordBackendBuildStatus({
+        generation: startStatus?.generation ?? previous?.generation,
+        ok: true,
+        files: startStatus?.files ?? previous?.files ?? [],
+        message: "Backend ready",
+      });
+      this.#sendOrQueueBuildStatus(status);
+    }
+    this.#backendStartStatus = null;
+  }
+  #setBackendLifecycleState(next: BackendLifecycleState, detail?: string): void {
+    if (this.#backendLifecycleState === next && !detail) return;
+    const prev = this.#backendLifecycleState;
+    this.#backendLifecycleState = next;
+    this.logger.verbose(`[backend-lifecycle] ${prev} -> ${next}${detail ? ` ${detail}` : ""}`);
+  }
   #sendToBackend(message: BuilderMessage) {
     if (!this.#backend || !this.#backendReady) {
-      if (message.type === "css-updated" || message.type === "pages-updated") {
+      if (message.type === "css-updated" || message.type === "pages-updated" || message.type === "build-status") {
         this.logger.verbose(`backend is not ready; will replay ${message.type}`);
         return;
       }
@@ -236,6 +418,7 @@ export class AkanAppHost {
     const backend = this.#backend;
     this.#plannedBackendStops.add(backend);
     this.#backendReady = false;
+    this.#setBackendLifecycleState("stopping", `pid=${backend.pid}`);
     this.logger.verbose(`stopping backend pid=${backend.pid}`);
     try {
       backend.kill("SIGTERM");
@@ -250,10 +433,16 @@ export class AkanAppHost {
       }
     } finally {
       if (this.#backend === backend) this.#backend = null;
+      this.#setBackendLifecycleState("stopped", `pid=${backend.pid}`);
     }
   }
-  #scheduleBackendRestart(files: string[]) {
-    for (const file of files) this.#restartFiles.add(file);
+  #scheduleBackendRestart(reason: BackendRestartReason) {
+    this.#pendingRestartReason = mergeBackendRestartReasons(this.#pendingRestartReason, reason);
+    const pending = this.#pendingRestartReason;
+    this.#setBackendLifecycleState(
+      "restart-pending",
+      `generation=${pending.generation ?? "(unknown)"} files=${pending.files.length} roles=${pending.roles.join(",") || "(none)"}`,
+    );
     if (this.#backendRecoveryTimer) {
       clearTimeout(this.#backendRecoveryTimer);
       this.#backendRecoveryTimer = null;
@@ -261,22 +450,31 @@ export class AkanAppHost {
     if (this.#restartTimer) clearTimeout(this.#restartTimer);
     this.#restartTimer = setTimeout(() => {
       this.#restartTimer = null;
-      const changed = [...this.#restartFiles];
-      this.#restartFiles.clear();
-      void this.#restartBackend(changed);
+      const next = this.#pendingRestartReason;
+      this.#pendingRestartReason = null;
+      if (next) void this.#restartBackend(next);
     }, BACKEND_RESTART_DEBOUNCE_MS);
   }
-  async #restartBackend(files: string[]) {
-    this.logger.verbose(`[backend-reload] restarting backend for ${files.length} file(s)`);
+  async #restartBackend(reason: BackendRestartReason) {
+    this.logger.verbose(
+      `[backend-reload] restarting backend generation=${reason.generation ?? "(unknown)"} files=${reason.files.length} roles=${reason.roles.join(",") || "(none)"}`,
+    );
     this.#backendRecoveryAttempts = 0;
     await Promise.all([this.#stopBackend(), this.#backendGraph.refresh()]);
-    this.#startBackend();
+    this.#startBackend({ generation: reason.generation, files: reason.files });
   }
   #scheduleBackendRecovery(reason: string) {
     if (this.#backendRecoveryTimer || this.#backend) 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 failureStatus = this.#recordBackendBuildStatus({
+      ok: false,
+      files: [],
+      message: `Backend exited unexpectedly (${reason}); restarting in ${delay}ms`,
+    });
+    this.#sendOrQueueBuildStatus(failureStatus);
     this.logger.warn(
       `[backend-recovery] backend exited unexpectedly (${reason}); restarting in ${delay}ms (attempt ${this.#backendRecoveryAttempts})`,
     );
@@ -284,7 +482,7 @@ export class AkanAppHost {
       this.#backendRecoveryTimer = null;
       if (this.#backend) return;
       void this.#backendGraph.refresh().finally(() => {
-        if (!this.#backend) this.#startBackend();
+        if (!this.#backend) this.#startBackend({ generation: failureStatus.generation, files: failureStatus.files });
       });
     }, delay);
   }
@@ -296,8 +494,13 @@ export class AkanAppHost {
       });
   }
   async #handleBuilderMessage(message: BuilderMessage) {
-    if (message.type === "pages-updated") this.#latestPagesUpdated = message;
-    if (message.type === "css-updated") this.#latestCssUpdated = message;
+    if (message.type === "build-status") {
+      this.#recordBuildStatus(message.data);
+      this.#sendOrQueueBuildStatus(message.data);
+      return;
+    }
+    if (message.type === "pages-updated") this.#recordLastGood(message);
+    if (message.type === "css-updated") this.#recordLastGood(message);
     if (message.type === "invalidate") {
       await this.#handleInvalidate(message);
       return;
@@ -305,26 +508,107 @@ export class AkanAppHost {
     this.#sendToBackend(message);
   }
   async #handleInvalidate(message: Extract<BuilderMessage, { type: "invalidate" }>) {
+    if (shouldRestartDevHostByDevPlan(message)) {
+      this.#recordDevHostRestartRequired(message);
+      return;
+    }
     if (await this.#shouldRestartBackend(message)) {
-      this.#scheduleBackendRestart(message.files);
+      this.#scheduleBackendRestart(backendRestartReasonFromMessage(message));
       return;
     }
     this.#sendToBackend(message);
   }
-  #replayBuilderState() {
+  #recordLastGood(
+    message: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
+  ): void {
+    if (message.type === "pages-updated") {
+      if (!shouldReplaceLastGoodMessage(this.#lastGoodFrontend.pages, message)) return;
+      this.#lastGoodFrontend.pages = message;
+      this.logger.verbose(
+        `[last-good] pages generation=${message.data.generation ?? "(unknown)"} buildId=${message.data.buildId}`,
+      );
+      return;
+    }
+    if (!shouldReplaceLastGoodMessage(this.#lastGoodFrontend.css, message)) return;
+    this.#lastGoodFrontend.css = message;
+    this.logger.verbose(
+      `[last-good] css generation=${message.data.generation ?? "(unknown)"} assets=${Object.keys(message.data.cssAssets).length}`,
+    );
+  }
+  #recordDevHostRestartRequired(message: Extract<BuilderMessage, { type: "invalidate" }>): void {
+    const generation = message.devPlan?.generation ?? message.generation;
+    const detail = `generation=${generation ?? "(unknown)"} files=${message.files.length}`;
+    this.logger.warn(
+      `[dev-host] config change requires a manual restart until controlled dev-host restart is implemented (${detail})`,
+    );
+    if (typeof generation === "number") {
+      const status: DevBuildStatus = {
+        generation,
+        phase: "scan",
+        ok: false,
+        files: message.files,
+        message: "Config change requires restarting `akan start` to apply.",
+      };
+      this.#recordBuildStatus(status);
+      this.#sendOrQueueBuildStatus(status);
+    }
+  }
+  #recordBuildStatus(status: DevBuildStatus): void {
+    const recovered = shouldMarkBuildPhaseRecovered(this.#buildStatusByPhase, status);
+    this.#buildStatusByPhase.set(status.phase, status);
+    const label = `[build-status] generation=${status.generation} phase=${status.phase} ok=${status.ok} files=${status.files.length}`;
+    if (status.ok) this.logger.verbose(`${label}${recovered ? " recovered=1" : ""}`);
+    else this.logger.warn(`${label}${status.message ? ` message=${status.message}` : ""}`);
+  }
+  #sendOrQueueBuildStatus(status: DevBuildStatus): void {
+    if (!this.#backend || shouldQueueBuildStatusReplay(this.#backendReady, this.#pendingBuildStatusReplay.length)) {
+      this.#pendingBuildStatusReplay.push(status);
+      this.logger.verbose(
+        `backend is not ready; will replay build-status generation=${status.generation} phase=${status.phase}`,
+      );
+      return;
+    }
+    this.#sendToBackend({ type: "build-status", data: status });
+  }
+  #replayBuilderState(): void {
     if (!this.#backendReady) return;
-    if (this.#latestCssUpdated) this.#sendToBackend(this.#latestCssUpdated);
-    if (this.#latestPagesUpdated) this.#sendToBackend(this.#latestPagesUpdated);
+    if (this.#lastGoodFrontend.css) this.#sendToBackend(this.#lastGoodFrontend.css);
+    if (this.#lastGoodFrontend.pages) this.#sendToBackend(this.#lastGoodFrontend.pages);
+    const queuedStatuses = this.#pendingBuildStatusReplay.splice(0);
+    for (const status of buildStatusReplaySequence(queuedStatuses, this.#buildStatusByPhase)) {
+      this.#sendToBackend({ type: "build-status", data: status });
+    }
   }
   async #shouldRestartBackend(message: Extract<BuilderMessage, { type: "invalidate" }>): Promise<boolean> {
     if (message.kinds.length === 1 && message.kinds[0] === "css") return false;
-    if (!this.#backendGraph.ready && message.kinds.includes("code")) await this.#backendGraph.refresh();
-    return message.files.some((file) => this.#isBackendFile(file));
+    if (message.devPlan) {
+      const { generation, roles, actions, reasonByFile } = message.devPlan;
+      this.logger.verbose(
+        `[dev-plan] generation=${generation} roles=${roles.join(",") || "(none)"} actions=${actions.join(",") || "(none)"} reasons=${Object.keys(reasonByFile).length}`,
+      );
+      const shouldRestart = shouldRestartBackendByDevPlan(message) ?? false;
+      if (shouldRestart && message.kinds.includes("code")) await this.#backendGraph.refresh();
+      return shouldRestart;
+    }
+    if (message.kinds.includes("code")) await this.#backendGraph.refresh();
+    if (message.files.some((file) => this.#isBackendFile(file))) return true;
+    if (!this.#backendGraph.lastRefreshSucceeded) {
+      const fallbackFiles = message.files.filter((file) =>
+        isLegacyBackendFallbackFile(file, this.app.workspace.workspaceRoot),
+      );
+      if (fallbackFiles.length > 0) {
+        this.logger.warn(
+          `[backend-graph] using path-role fallback for legacy invalidate; restart files=${fallbackFiles.length}`,
+        );
+        return true;
+      }
+    }
+    return false;
   }
   #isBackendFile(file: string): boolean {
     return this.#backendGraph.has(file);
   }
-  async #startBuilder() {
+  async #startBuilder(): Promise<IncrementalBuilderHost> {
     const startTime = Date.now();
     this.app.verbose(`[cli] waiting for builder to complete initial base build…`);
     let lastError: unknown;
@@ -345,7 +629,7 @@ export class AkanAppHost {
     }
     throw lastError instanceof Error ? lastError : new Error(String(lastError));
   }
-  #waitForBuilderReady(attempt: number) {
+  #waitForBuilderReady(attempt: number): Promise<void> {
     return new Promise<void>((resolve, reject) => {
       if (!this.#builder) throw new Error("Builder Not Found");
       let settled = false;
@@ -372,7 +656,7 @@ export class AkanAppHost {
       });
     });
   }
-  #sendToBuilder(message: BuilderMessage) {
+  #sendToBuilder(message: BuilderMessage): void {
     if (this.#builder?.send(message)) return;
     if (message.type === "build-route") {
       this.#sendToBackend({
@@ -385,7 +669,7 @@ export class AkanAppHost {
     }
     this.logger.warn("akanAppHost builder is not running");
   }
-  #stopBuilder() {
+  #stopBuilder(): void {
     if (!this.#builder) return;
     this.#builder.stop();
     this.#builder = null;

package/frontendBuild/devChangePlanner.ts

@@ -0,0 +1,167 @@
+import path from "node:path";
+import type { ChangeKind, DevChangeAction, DevChangePlan, DevChangeRole } from "akanjs/server";
+
+const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+const CONFIG_BASENAMES = new Set(["akan.config.ts", "bunfig.toml", "tsconfig.json", "package.json"]);
+const BARREL_FACETS = new Set(["common", "srvkit", "ui", "webkit"]);
+const CLIENT_SUFFIXES = [".Template.tsx", ".Unit.tsx", ".Util.tsx", ".View.tsx", ".Zone.tsx", ".store.ts"];
+const SHARED_SUFFIXES = [".constant.ts", ".dictionary.ts", ".signal.ts"];
+const SERVER_SUFFIXES = [".service.ts", ".document.ts"];
+const RUNTIME_METADATA_BASENAMES = new Set(["dict.ts", "sig.ts", "useClient.ts", "useServer.ts"]);
+
+export interface DevChangePlannerOptions {
+  workspaceRoot: string;
+}
+
+export interface DevChangePlanInput {
+  generation: number;
+  files: string[];
+  kinds: Iterable<Exclude<ChangeKind, "ignore">>;
+  generatedFiles?: string[];
+}
+
+export class DevChangePlanner {
+  readonly #workspaceRoot: string;
+
+  constructor({ workspaceRoot }: DevChangePlannerOptions) {
+    this.#workspaceRoot = path.resolve(workspaceRoot);
+  }
+
+  plan({ generation, files, kinds, generatedFiles = [] }: DevChangePlanInput): DevChangePlan {
+    const fileList = uniqueResolved([...files, ...generatedFiles]);
+    const generatedSet = new Set(generatedFiles.map((file) => path.resolve(file)));
+    const kindSet = new Set(kinds);
+    const roles = new Set<DevChangeRole>();
+    const actions = new Set<DevChangeAction>();
+    const reasonByFile: Record<string, string[]> = {};
+
+    for (const kind of kindSet) {
+      if (kind === "css") {
+        roles.add("css");
+        actions.add("rebuild-css");
+      }
+      if (kind === "config") {
+        roles.add("config");
+        actions.add("restart-dev-host");
+      }
+    }
+
+    for (const file of fileList) {
+      const reasons = new Set<string>();
+      const fileRoles = this.#rolesForFile(file, { isGenerated: generatedSet.has(path.resolve(file)), reasons });
+      for (const role of fileRoles) roles.add(role);
+      if (reasons.size > 0) reasonByFile[path.resolve(file)] = [...reasons].sort();
+    }
+
+    if (roles.has("barrel")) actions.add("sync-generated");
+    if (roles.has("server") || roles.has("shared")) actions.add("restart-backend");
+    if (roles.has("client") || roles.has("shared")) actions.add("rebuild-client");
+    if (roles.has("css")) actions.add("rebuild-css");
+
+    return {
+      generation,
+      files: fileList,
+      generatedFiles: uniqueResolved(generatedFiles),
+      roles: [...roles].sort(),
+      actions: [...actions].sort(),
+      reasonByFile,
+    };
+  }
+
+  #rolesForFile(
+    file: string,
+    { isGenerated, reasons }: { isGenerated: boolean; reasons: Set<string> },
+  ): Set<DevChangeRole> {
+    const roles = new Set<DevChangeRole>();
+    const abs = path.resolve(file);
+    const base = path.basename(abs);
+    const ext = path.extname(abs).toLowerCase();
+    const isSource = SOURCE_EXTS.has(ext);
+    const rel = path.relative(this.#workspaceRoot, abs);
+    const parts = rel.split(path.sep).filter(Boolean);
+
+    if (CONFIG_BASENAMES.has(base)) {
+      roles.add("config");
+      reasons.add("config-file");
+    }
+    if (ext === ".css") {
+      roles.add("css");
+      reasons.add("css-file");
+    }
+    if (isGenerated || (isSource && this.#isBarrelFacetChild(parts))) {
+      roles.add("barrel");
+      reasons.add(isGenerated ? "generated-index" : "barrel-facet-child");
+    }
+    if (isSource && this.#isServerBiased(abs, parts)) {
+      roles.add("server");
+      reasons.add("server-path");
+    }
+    if (isSource && this.#isClientBiased(abs, parts)) {
+      roles.add("client");
+      reasons.add("client-path");
+    }
+    if (isSource && this.#isSharedBiased(abs, parts)) {
+      roles.add("shared");
+      reasons.add("shared-path");
+    }
+
+    if (roles.has("server") && roles.has("client")) {
+      roles.delete("server");
+      roles.delete("client");
+      roles.add("shared");
+      reasons.add("server-client-overlap");
+    }
+    if (roles.size === 0 && SOURCE_EXTS.has(ext) && this.#isWorkspaceSource(rel)) {
+      roles.add("shared");
+      reasons.add("workspace-source-fallback");
+    }
+
+    return roles;
+  }
+
+  #isServerBiased(abs: string, parts: string[]): boolean {
+    const base = path.basename(abs);
+    return (
+      parts.includes("srvkit") ||
+      SERVER_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||
+      base === "main.ts" ||
+      base === "server.ts"
+    );
+  }
+
+  #isClientBiased(abs: string, parts: string[]): boolean {
+    const base = path.basename(abs);
+    return (
+      parts.includes("ui") ||
+      parts.includes("webkit") ||
+      parts.includes("page") ||
+      CLIENT_SUFFIXES.some((suffix) => base.endsWith(suffix))
+    );
+  }
+
+  #isSharedBiased(abs: string, parts: string[]): boolean {
+    const base = path.basename(abs);
+    return (
+      parts.includes("common") ||
+      SHARED_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||
+      RUNTIME_METADATA_BASENAMES.has(base)
+    );
+  }
+
+  #isBarrelFacetChild(parts: string[]): boolean {
+    if (parts.length < 4) return false;
+    const [scope, , facet, child] = parts;
+    if (scope !== "apps" && scope !== "libs") return false;
+    if (!facet || !BARREL_FACETS.has(facet)) return false;
+    if (!child || child.startsWith(".") || child === "index.ts" || child === "index.tsx") return false;
+    return true;
+  }
+
+  #isWorkspaceSource(rel: string): boolean {
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return false;
+    const [scope] = rel.split(path.sep);
+    return scope === "apps" || scope === "libs" || scope === "pkgs";
+  }
+}
+
+const uniqueResolved = (files: string[]) => [...new Set(files.map((file) => path.resolve(file)))].sort();