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

package/typecheck/projectTypecheck.ts

@@ -1,5 +1,6 @@
 import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
+import { CliError } from "../commandDecorators/cliError";
 import type { TypecheckRecord } from "../typeChecker";
 import { TypecheckFailure } from "./typecheckFailure";
 
@@ -69,7 +70,10 @@ export class ProjectTypecheck {
     if (exitCode === 0) return;
     const records = report === "records" ? ProjectTypecheck.#parseRecords(stdout) : null;
     if (records?.length) throw new TypecheckFailure(records);
-    throw new Error((stderr || stdout).trim() || `Typecheck failed with exit code ${exitCode}`);
+    const output = (stderr || stdout).trim();
+    if (exitCode === TypecheckFailure.workerExitCode && report === "pretty")
+      throw new CliError("checkFailed", output || "Typecheck failed");
+    throw new Error(output || `Typecheck failed with exit code ${exitCode}`);
   }
 
   static #parseRecords(stdout: string): TypecheckRecord[] | null {

package/typecheck/typecheck.proc.ts

@@ -1,5 +1,6 @@
 import { Logger } from "akanjs/common";
 import { TypeChecker } from "../typeChecker";
+import { TypecheckFailure } from "./typecheckFailure";
 
 try {
   const filePath = process.env.AKAN_TYPECHECK_FILE;
@@ -28,11 +29,11 @@ try {
     //? Not process.cwd(): that is the realpath (/private/var on macOS) while TypeScript keeps the spelling it was given.
     const root = process.env.AKAN_TYPECHECK_ROOT ?? process.cwd();
     process.stdout.write(JSON.stringify(TypeChecker.toRecords(result.errors, root)));
-    process.exit(result.errors.length > 0 ? 1 : 0);
+    process.exit(result.errors.length > 0 ? TypecheckFailure.workerExitCode : 0);
   }
   if (result.errors.length > 0) {
     console.error(result.message);
-    process.exit(1);
+    process.exit(TypecheckFailure.workerExitCode);
   }
 } catch (error) {
   console.error(error instanceof Error ? error.message : String(error));

package/typecheck/typecheckFailure.ts

@@ -1,8 +1,13 @@
+import { CliError } from "../commandDecorators/cliError";
 import type { TypecheckRecord } from "../typeChecker";
 
-export class TypecheckFailure extends Error {
+export class TypecheckFailure extends CliError<"checkFailed"> {
+  //? The worker's exit when the project has type errors, so its crash, which exits 1, is told apart.
+  static readonly workerExitCode = 3;
+
   constructor(readonly records: TypecheckRecord[]) {
     super(
+      "checkFailed",
       records
         .slice(0, 20)
         .map((record) => `${record.file ?? "-"}:${record.line}:${record.col} ${record.code} ${record.message}`)

package/workflow/artifacts.ts

@@ -16,6 +16,7 @@ import type {
   WorkflowNextActionCode,
   WorkflowOverallStatus,
   WorkflowPlan,
+  WorkflowRecommendation,
   WorkflowRunArtifact,
   WorkflowRunSource,
   WorkflowValidationCommandResult,
@@ -94,11 +95,11 @@ export const createWorkflowApplyReport = ({
   postApplyChecks?: WorkflowApplyReport["postApplyChecks"];
   recommendations?: WorkflowApplyReport["recommendations"];
 }): WorkflowApplyReport => {
-  const validationCommands = recommendedValidationCommands ?? commands;
-  const nextActionsWithIntent = nextActions.map((action) => ({
-    ...action,
-    action: inferNextActionCode(action, diagnostics),
-  }));
+  const status = workflowStatus(diagnostics);
+  const validationCommands = status === "failed" ? [] : (recommendedValidationCommands ?? commands);
+  const nextActionsWithIntent = nextActions
+    .map((action) => ({ ...action, action: inferNextActionCode(action, diagnostics) }))
+    .filter((action) => status !== "failed" || action.action !== "validate");
   if (sourceChangeBlocked(diagnostics) && !nextActionsWithIntent.some((action) => action.action === "blocked")) {
     nextActionsWithIntent.unshift({
       command: `akan workflow explain ${workflow}`,
@@ -110,12 +111,13 @@ export const createWorkflowApplyReport = ({
     (left, right) => nextActionPriority(left, diagnostics) - nextActionPriority(right, diagnostics),
   );
   const sourceFilesChanged = uniqueBy(changedFiles, (file) => `${file.action}:${file.path}:${file.reason}`);
-  const generatedFilesSynced = uniqueBy(generatedFiles, (file) => `${file.action}:${file.path}:${file.reason}`);
+  const generatedFilesSynced =
+    status === "failed" ? [] : uniqueBy(generatedFiles, (file) => `${file.action}:${file.path}:${file.reason}`);
   return {
     schemaVersion: 1,
     workflow,
     mode,
-    status: workflowStatus(diagnostics),
+    status,
     summary: {
       sourceFilesChanged,
       generatedFilesSynced,
@@ -133,6 +135,11 @@ export const createWorkflowApplyReport = ({
   };
 };
 
+export const withoutApplyHints = (recommendations: readonly WorkflowRecommendation[]) =>
+  recommendations.filter(
+    (recommendation) => recommendation.kind !== "auto-apply" && recommendation.kind !== "validation",
+  );
+
 export const resolveWorkflowCommand = (command: string, plan: WorkflowPlan) => {
   const target = typeof plan.inputs.app === "string" ? plan.inputs.app : "<app-or-lib>";
   return command
@@ -526,6 +533,17 @@ export const createWorkflowValidationRunReport = async ({
 };
 
 export const createDryRunWorkflowApplyReport = (plan: WorkflowPlan) => {
+  if (workflowStatus(plan.diagnostics) === "failed")
+    return createWorkflowApplyReport({
+      workflow: plan.workflow,
+      mode: "dry-run",
+      changedFiles: [],
+      generatedFiles: [],
+      diagnostics: [...plan.diagnostics],
+      recommendations: withoutApplyHints(plan.recommendations),
+      nextActions: [],
+      plan,
+    });
   const changedFiles: PrimitiveChangedFile[] = plan.predictedChanges.flatMap((change) => {
     if (change.action !== "create" && change.action !== "modify") return [];
     return [

package/workflow/fieldType.ts

@@ -0,0 +1,92 @@
+import ts from "typescript";
+import type { Sys } from "../commandDecorators";
+import { ensureBaseImport, ensureNamedImport, getSysRoot, moduleComponentName, moduleSourcePaths } from "./source";
+import { sourceFileFor } from "./sourceAst";
+import type { WorkflowDiagnostic } from "./types";
+
+const builtInFieldTypes = new Set(["String", "Boolean", "Date", "Map"]);
+const baseFieldTypes = new Set(["Int", "Float", "ID", "Any", "Binary", "ImageResult"]);
+const fieldTypeReference = /^\[*([A-Za-z_$][\w$]*)((?:\.[A-Za-z_$][\w$]*)*)\]*$/;
+
+export const ensureBaseTypeImport = (content: string, typeName: string) => {
+  const [, name = "", member] = fieldTypeReference.exec(typeName) ?? [];
+  if (member || !baseFieldTypes.has(name)) return content;
+  return ensureBaseImport(content, name);
+};
+
+const valueNamesOf = (content: string) => {
+  const names = new Set<string>();
+  for (const statement of sourceFileFor("source.ts", content).statements) {
+    if (ts.isImportDeclaration(statement)) {
+      const clause = statement.importClause;
+      if (!clause || clause.isTypeOnly) continue;
+      if (clause.name) names.add(clause.name.text);
+      const bindings = clause.namedBindings;
+      if (bindings && ts.isNamespaceImport(bindings)) names.add(bindings.name.text);
+      else for (const element of bindings?.elements ?? []) if (!element.isTypeOnly) names.add(element.name.text);
+    } else if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations)
+        if (ts.isIdentifier(declaration.name)) names.add(declaration.name.text);
+    } else if (
+      (ts.isClassDeclaration(statement) || ts.isEnumDeclaration(statement) || ts.isFunctionDeclaration(statement)) &&
+      statement.name
+    )
+      names.add(statement.name.text);
+  }
+  return names;
+};
+
+export const fieldTypeSource = async (
+  sys: Sys,
+  module: string,
+  typeName: string,
+  constantContent: string,
+): Promise<{ import?: { name: string; from: string }; diagnostic?: WorkflowDiagnostic }> => {
+  const reference = fieldTypeReference.exec(typeName);
+  if (!reference)
+    return {
+      diagnostic: {
+        severity: "error",
+        code: "primitive-field-type-unknown",
+        input: "type",
+        message: `Field type "${typeName}" is not a type name field() takes. Name one type, such as Address, or a list of one, such as [Address], then plan this again.`,
+      },
+    };
+  const [, name = "", member] = reference;
+  if (builtInFieldTypes.has(name) || baseFieldTypes.has(name) || valueNamesOf(constantContent).has(name)) return {};
+  const [scalars, models] = await Promise.all([sys.getScalarModules(), sys.getDatabaseModules()]);
+  const scalar = member ? undefined : scalars.find((scalarName) => moduleComponentName(scalarName) === name);
+  if (scalar) return { import: { name, from: `../__scalar/${scalar}/${scalar}.constant` } };
+  const model = member ? undefined : models.find((modelName) => moduleComponentName(modelName) === name);
+  if (model) return { import: { name, from: `../${model}/${model}.constant` } };
+  const root = getSysRoot(sys);
+  const constantPath = `${root}/${moduleSourcePaths(module).constant}`;
+  const named = (kind: string, names: string[]) =>
+    names.length ? `Its ${kind} are ${names.map(moduleComponentName).join(", ")}.` : `It has no ${kind}.`;
+  return {
+    diagnostic: {
+      severity: "error",
+      code: "primitive-field-type-unknown",
+      input: "type",
+      message: [
+        `Field type "${typeName}" names ${name}, which is not a built-in or akanjs/base type, not imported by ${constantPath}, and not a scalar or model in ${root}.`,
+        named("scalars", scalars),
+        named("models", models),
+        `Create the scalar with the create-scalar workflow first, or import ${name} into ${constantPath}, then plan this again.`,
+      ].join(" "),
+    },
+  };
+};
+
+export const withFieldTypeImport = async (
+  sys: Sys,
+  module: string,
+  typeName: string,
+  content: string,
+  diagnostics: WorkflowDiagnostic[],
+) => {
+  const withBaseImport = ensureBaseTypeImport(content, typeName);
+  const source = await fieldTypeSource(sys, module, typeName, withBaseImport);
+  if (source.diagnostic) diagnostics.push(source.diagnostic);
+  return source.import ? ensureNamedImport(withBaseImport, source.import.from, source.import.name) : withBaseImport;
+};

package/workflow/index.ts

@@ -1,11 +1,13 @@
 export * from "./artifacts";
 export * from "./executor";
+export * from "./fieldType";
 export * from "./guardCatalog";
 export * from "./interactionScaffold";
 export * from "./keyRename";
 export * from "./moduleIndex";
 export * from "./mutationScaffold";
 export * from "./mutationSource";
+export * from "./plainName";
 export * from "./plan";
 export * from "./render";
 export * from "./rolloutGate";

package/workflow/plainName.ts

@@ -0,0 +1,28 @@
+export const sysNamePattern = /^[a-z0-9][a-zA-Z0-9_-]*$/;
+export const identifierPattern = /^_{0,2}[a-zA-Z][a-zA-Z0-9_-]*$/;
+const packageNamePattern = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+export type PlainNameKind = "app" | "lib" | "module" | "service" | "scalar";
+
+export const isWorkflowSysName = (value: unknown): value is string =>
+  typeof value === "string" && sysNamePattern.test(value);
+export const isWorkflowModuleName = (value: unknown): value is string =>
+  typeof value === "string" && identifierPattern.test(value);
+
+export const plainNameProblem = (kind: PlainNameKind, name: string) => {
+  const isSys = kind === "app" || kind === "lib";
+  if (isSys ? isWorkflowSysName(name) : isWorkflowModuleName(name)) return null;
+  return `${JSON.stringify(name)} is no ${kind} name; use letters, digits, - and _, starting with ${isSys ? "a lowercase letter or digit" : "a letter"}`;
+};
+
+export const assertPlainName = (kind: PlainNameKind, name: string) => {
+  const problem = plainNameProblem(kind, name);
+  if (problem) throw new Error(problem);
+};
+
+export const assertPackageName = (name: string) => {
+  if (packageNamePattern.test(name)) return;
+  throw new Error(
+    `${JSON.stringify(name)} is no package name; use name or @scope/name, each of lowercase letters, digits, -, . and _, starting with a letter or digit`,
+  );
+};

package/workflow/plan.ts

@@ -1,11 +1,13 @@
 import { capitalize } from "akanjs/common";
 import type { Sys, Workspace } from "../commandDecorators";
-import { workflowPlanApproval } from "./artifacts";
+import { withoutApplyHints, workflowPlanApproval } from "./artifacts";
 import { resolveWorkflowSys } from "./executor";
+import { fieldTypeSource } from "./fieldType";
 import { InteractionScaffold } from "./interactionScaffold";
 import { KeyRename } from "./keyRename";
 import { MutationScaffold } from "./mutationScaffold";
-import { coerceFieldDefault, getSysRoot, moduleSourcePaths } from "./source";
+import { identifierPattern, sysNamePattern } from "./plainName";
+import { coerceFieldDefault, getSysRoot, moduleSourcePaths, normalizeFieldType } from "./source";
 import type {
   WorkflowDiagnostic,
   WorkflowInputSpec,
@@ -17,11 +19,10 @@ import type {
   WorkflowSurfaceMode,
 } from "./types";
 import { addFieldUiPolicyForType } from "./uiPolicy";
+import { workflowStatus } from "./utils";
 
 const surfaceModes = new Set<WorkflowSurfaceMode>(["infer", "include", "skip"]);
 
-const sysNamePattern = /^[a-z0-9][a-zA-Z0-9_-]*$/;
-const identifierPattern = /^_{0,2}[a-zA-Z][a-zA-Z0-9_-]*$/;
 //? These inputs become path segments, identifiers and command arguments, so none may carry a separator or a dot.
 const nameInputPatterns: Record<string, RegExp> = {
   app: sysNamePattern,
@@ -35,11 +36,6 @@ const nameInputPatterns: Record<string, RegExp> = {
   interaction: identifierPattern,
 };
 
-export const isWorkflowSysName = (value: unknown): value is string =>
-  typeof value === "string" && sysNamePattern.test(value);
-export const isWorkflowModuleName = (value: unknown): value is string =>
-  typeof value === "string" && identifierPattern.test(value);
-
 const parseStringList = (value: unknown) => {
   if (Array.isArray(value)) {
     const values = value.filter((item): item is string => typeof item === "string" && item.trim().length > 0);
@@ -487,7 +483,7 @@ const syssHolding = async (workspace: Workspace, module: string, except: Sys) =>
       .map(async (name) => await resolveWorkflowSys(workspace, name)),
   );
   const holding = await Promise.all(
-    others.map(async (other) => (other && (await other.readdir("lib")).includes(module) ? other : null)),
+    others.map(async (other) => (other && (await other.getDatabaseModules()).includes(module) ? other : null)),
   );
   return holding.filter((other): other is Sys => other !== null);
 };
@@ -495,28 +491,64 @@ const syssHolding = async (workspace: Workspace, module: string, except: Sys) =>
 const moduleMissing = async (workspace: Workspace, sys: Sys, module: string): Promise<WorkflowDiagnostic | null> => {
   if ((await sys.readdir("lib")).includes(module)) return null;
   const root = getSysRoot(sys);
-  const modules = [...(await sys.getDatabaseModules()), ...(await sys.getServiceModules())];
-  const sameName = modules.find((name) => name.replace(/^_/, "").toLowerCase() === module.toLowerCase());
+  const modules = await sys.getDatabaseModules();
+  const sameName = modules.find((name) => name.toLowerCase() === module.toLowerCase());
+  const service = (await sys.getServiceModules()).find(
+    (name) => name.replace(/^_/, "").toLowerCase() === module.replace(/^_/, "").toLowerCase(),
+  );
   const isScalar = (await sys.getScalarModules()).includes(module);
-  const [holder] = sameName || isScalar ? [] : await syssHolding(workspace, module, sys);
+  const [holder] = sameName || service || isScalar ? [] : await syssHolding(workspace, module, sys);
   return {
     severity: "error",
     code: "workflow-module-missing",
     input: "module",
     message: [
       `No module named ${module} in ${root}: ${root}/lib/${module} does not exist.`,
-      modules.length ? `Its modules are ${modules.join(", ")}.` : `${root} has no modules yet.`,
+      modules.length ? `Its database modules are ${modules.join(", ")}.` : `${root} has no database modules yet.`,
       sameName
         ? `Did you mean ${sameName}?`
-        : isScalar
-          ? `${root}/lib/__scalar/${module} is a scalar, and this workflow writes only into a module under ${root}/lib.`
-          : holder
-            ? `${module} is in ${getSysRoot(holder)}, so plan this with --app ${holder.name}.`
-            : `If ${module} is a new model, create it with the create-module workflow first, then plan this again.`,
+        : service
+          ? `${root}/lib/${service} is a service module, which stores no model, and this workflow writes only into a database module.`
+          : isScalar
+            ? `${root}/lib/__scalar/${module} is a scalar, and this workflow writes only into a module under ${root}/lib.`
+            : holder
+              ? `${module} is in ${getSysRoot(holder)}, so plan this with --app ${holder.name}.`
+              : `If ${module} is a new model, create it with the create-module workflow first, then plan this again.`,
+    ].join(" "),
+  };
+};
+
+const moduleNotDatabase = async (sys: Sys, spec: WorkflowSpec, module: string): Promise<WorkflowDiagnostic | null> => {
+  const databaseModules = await sys.getDatabaseModules();
+  if (databaseModules.includes(module)) return null;
+  const root = getSysRoot(sys);
+  const isServiceModule = module.startsWith("_") && !module.startsWith("__");
+  return {
+    severity: "error",
+    code: "workflow-module-not-database",
+    input: "module",
+    message: [
+      isServiceModule
+        ? `${module} in ${root} is a service module, which stores no model.`
+        : `${root}/lib/${module} is not a database module: it has no ${module}.constant.ts.`,
+      `${spec.name} needs a database module, one with lib/<model>/<model>.constant.ts.`,
+      databaseModules.length
+        ? `Its database modules are ${databaseModules.join(", ")}.`
+        : `${root} has no database modules yet.`,
+      spec.inputs.field
+        ? "Add the field to one of them, or create its model with the create-module workflow first; a value several models embed is a scalar, made with create-scalar and added to a model as a field of that type."
+        : "Plan this on one of them, or create the model with the create-module workflow first.",
     ].join(" "),
   };
 };
 
+const fieldTypeUnknown = async (sys: Sys, spec: WorkflowSpec, module: string, type: string | null) => {
+  if (spec.name !== "add-field" || !type || ["enum", "number", "numeric", "upload"].includes(type.toLowerCase()))
+    return null;
+  const constant = await sys.readFile(moduleSourcePaths(module).constant);
+  return (await fieldTypeSource(sys, module, normalizeFieldType(type), constant)).diagnostic ?? null;
+};
+
 export const workflowTargetDiagnostics = async (
   workspace: Workspace,
   spec: WorkflowSpec,
@@ -539,11 +571,14 @@ export const workflowTargetDiagnostics = async (
   const module = planString(inputs, "module");
   const moduleSpec: WorkflowInputSpec | undefined = spec.inputs.module;
   if (!module || !moduleSpec?.mustExist) return [];
-  const missing = await moduleMissing(workspace, sys, module);
-  return missing ? [missing] : [];
+  const refused =
+    (await moduleMissing(workspace, sys, module)) ??
+    (await moduleNotDatabase(sys, spec, module)) ??
+    (await fieldTypeUnknown(sys, spec, module, planString(inputs, "type")));
+  return refused ? [refused] : [];
 };
 
-export const inspectWorkflowPlan = async (
+const inspectPlanTarget = async (
   workspace: Workspace,
   spec: WorkflowSpec,
   plan: WorkflowPlan,
@@ -586,3 +621,13 @@ export const inspectWorkflowPlan = async (
     recommendations: [...plan.recommendations, ...inspected.recommendations],
   };
 };
+
+export const inspectWorkflowPlan = async (
+  workspace: Workspace,
+  spec: WorkflowSpec,
+  plan: WorkflowPlan,
+): Promise<WorkflowPlan> => {
+  const inspected = await inspectPlanTarget(workspace, spec, plan);
+  if (workflowStatus(inspected.diagnostics) === "passed") return inspected;
+  return { ...inspected, recommendations: withoutApplyHints(inspected.recommendations) };
+};

package/workflow/source.ts

@@ -238,11 +238,6 @@ export const ensureImportDeclaration = (content: string, moduleSpecifier: string
 
 export const ensureBaseImport = (content: string, name: string) => ensureNamedImport(content, "akanjs/base", name);
 
-export const ensureBaseTypeImport = (content: string, typeName: string) => {
-  if (typeName !== "Int" && typeName !== "Float") return content;
-  return ensureBaseImport(content, typeName);
-};
-
 export type FieldDefaultValue = string | number | boolean | null;
 
 const numericDefault = (typeName: "Int" | "Float", rawDefault: FieldDefaultValue): string | null => {

package/workspaceGraph.test.ts

@@ -1,7 +1,17 @@
-import { describe, expect, it } from "bun:test";
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import type { AkanChangeMap, AkanGraphEdge, AkanGraphNode } from "@akanjs/language";
+import { AkanGraphDiff } from "@akanjs/language";
+import type { Workspace } from "./commandDecorators";
 import { WorkspaceGraph } from "./workspaceGraph";
 
+const roots: string[] = [];
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
 const node = (id: string, owner: string | null, change?: AkanGraphNode["change"]): AkanGraphNode => ({
   id,
   kind: id.split(":")[0] as AkanGraphNode["kind"],
@@ -13,10 +23,15 @@ const node = (id: string, owner: string | null, change?: AkanGraphNode["change"]
   at: null,
   ...(change ? { change } : {}),
 });
-const edge = (from: string, to: string, change?: AkanGraphEdge["change"]): AkanGraphEdge => ({
+const edge = (
+  from: string,
+  to: string,
+  change?: AkanGraphEdge["change"],
+  kind: AkanGraphEdge["kind"] = "calls",
+): AkanGraphEdge => ({
   from,
   to,
-  kind: "calls",
+  kind,
   label: null,
   count: 1,
   at: null,
@@ -102,6 +117,60 @@ describe("WorkspaceGraph.answer", () => {
   });
 });
 
+describe("WorkspaceGraph.answer past the node limit", () => {
+  const changeMapOf = (nodes: AkanGraphNode[], edges: AkanGraphEdge[]): AkanChangeMap => ({
+    version: 1,
+    nodes,
+    edges,
+    since: "0123456789ab",
+    summary: { added: 0, removed: 0, changed: nodes.filter((item) => item.change).length },
+    unmapped: [],
+  });
+
+  it("drops the layout that only wraps a changed route, and keeps the route", () => {
+    const fillers = Array.from({ length: 599 }, (_, idx) => node(`method:apps/demo:memo.m${idx}`, "apps/demo"));
+    const answer = WorkspaceGraph.answer(
+      {
+        version: 1,
+        nodes: [
+          node("layout:apps/demo:/", "apps/demo"),
+          node("route:apps/demo:/memo", "apps/demo", "changed"),
+          ...fillers,
+        ],
+        edges: [edge("layout:apps/demo:/", "route:apps/demo:/memo", undefined, "wraps")],
+      },
+      {},
+    );
+    if ("diagnostics" in answer) throw new Error("expected an answer");
+    expect(answer.nodes.filter((item) => item.kind !== "method").map(({ id }) => id)).toEqual([
+      "route:apps/demo:/memo",
+    ]);
+    expect(answer.edges).toEqual([]);
+  });
+
+  it("answers a Change Map whole once its unchanged pages are set aside", () => {
+    const routes = Array.from({ length: 10 }, (_, idx) => node(`route:apps/demo:/r${idx}`, "apps/demo"));
+    const changed = Array.from({ length: 595 }, (_, idx) =>
+      node(`method:apps/demo:memo.m${idx}`, "apps/demo", "changed"),
+    );
+    const answer = WorkspaceGraph.answerChanges(changeMapOf([...routes, ...changed], []), {});
+    if ("diagnostics" in answer) throw new Error("expected an answer");
+    expect(answer.nodes).toHaveLength(595);
+    expect(answer.summary).toEqual({ added: 0, removed: 0, changed: 595 });
+  });
+
+  it("counts the changed pages it keeps when it names the owners to scope to", () => {
+    const routes = Array.from({ length: 650 }, (_, idx) => node(`route:apps/demo:/r${idx}`, "apps/demo", "changed"));
+    const answer = WorkspaceGraph.answerChanges(
+      changeMapOf([...routes, node("method:libs/shared:file.touch", "libs/shared", "changed")], []),
+      {},
+    );
+    if (!("owners" in answer)) throw new Error("expected a scope request");
+    expect(answer.diagnostics.map(({ message }) => message).join("\n")).toContain("651 nodes");
+    expect(answer.owners).toEqual({ "apps/demo": 650, "libs/shared": 1 });
+  });
+});
+
 describe("WorkspaceGraph.scope", () => {
   it("keeps a lib's guard without pulling in every app endpoint that uses it", () => {
     const guard = "guard:libs/shared:Admin";
@@ -118,4 +187,132 @@ describe("WorkspaceGraph.scope", () => {
     expect(scoped.nodes.map(({ id }) => id)).toEqual([guard, own]);
     expect(scoped.edges).toEqual([edge(own, guard)]);
   });
+
+  it("follows a role the scope's method calls to the implementation its app binds", () => {
+    const role = "adaptor::LlmAdaptorRole";
+    const binds = (to: string, label: string): AkanGraphEdge => ({ ...edge(role, to), kind: "binds", label });
+    const graph = {
+      version: 1 as const,
+      nodes: [
+        { ...node("method:apps/sceny:plan.draft", "apps/sceny"), module: "plan" },
+        { ...node("method:apps/angelo:chat.reply", "apps/angelo"), module: "chat" },
+        { ...node("method:libs/genai:prompt.run", "libs/genai"), module: "prompt" },
+        node(role, null),
+        node("adaptor::AnthropicLlm", null),
+        node("adaptor:apps/angelo:ChatCompletionsLlm", "apps/angelo"),
+        node("adaptor:libs/genai:GenaiLlm", "libs/genai"),
+      ],
+      edges: [
+        edge("method:apps/sceny:plan.draft", role),
+        edge("method:apps/angelo:chat.reply", role),
+        edge("method:libs/genai:prompt.run", role),
+        binds("adaptor::AnthropicLlm", "apps/sceny"),
+        binds("adaptor:apps/angelo:ChatCompletionsLlm", "apps/angelo"),
+        binds("adaptor:libs/genai:GenaiLlm", "libs/genai"),
+      ],
+    };
+    const bound = (scope: { app?: string; module?: string }) =>
+      WorkspaceGraph.scope(graph, scope)
+        .edges.filter(({ kind }) => kind === "binds")
+        .map(({ to, label }) => `${label} ${to}`);
+    expect(bound({ app: "sceny" })).toEqual(["apps/sceny adaptor::AnthropicLlm"]);
+    expect(WorkspaceGraph.scope(graph, { app: "sceny" }).nodes.map(({ id }) => id)).toContain("adaptor::AnthropicLlm");
+    expect(bound({ app: "angelo" })).toEqual(["apps/angelo adaptor:apps/angelo:ChatCompletionsLlm"]);
+    expect(bound({ app: "genai" })).toEqual([
+      "apps/sceny adaptor::AnthropicLlm",
+      "apps/angelo adaptor:apps/angelo:ChatCompletionsLlm",
+      "libs/genai adaptor:libs/genai:GenaiLlm",
+    ]);
+    expect(bound({ module: "plan" })).toHaveLength(3);
+    expect(
+      WorkspaceGraph.visibleTo(graph, "sceny")
+        .edges.filter(({ kind }) => kind === "binds")
+        .map(({ label }) => label),
+    ).toEqual(["apps/sceny"]);
+  });
+
+  it("scopes a Change Map to the binding the app runs, whether or not that binding changed", () => {
+    const role = "adaptor::LlmAdaptorRole";
+    const versioned = (id: string, owner: string | null, digest: string, module: string | null = null) => ({
+      ...node(id, owner),
+      module,
+      digest,
+      at: { file: `${owner ?? "akanjs"}/x.ts`, line: 1, column: 1 },
+    });
+    const binds = (to: string, label: string): AkanGraphEdge => ({ ...edge(role, to), kind: "binds", label });
+    const graphOf = (ownBinding: boolean, method: string, lib: string) => ({
+      version: 1 as const,
+      nodes: [
+        versioned("method:apps/sceny:plan.draft", "apps/sceny", method, "plan"),
+        node(role, null),
+        node("adaptor::AnthropicLlm", null),
+        versioned("adaptor:libs/genai:GenaiLlm", "libs/genai", lib),
+      ],
+      edges: [
+        edge("method:apps/sceny:plan.draft", role),
+        ...(ownBinding ? [binds("adaptor::AnthropicLlm", "apps/sceny")] : []),
+        binds("adaptor:libs/genai:GenaiLlm", "libs/genai"),
+      ],
+    });
+    const scopedBinds = (base: ReturnType<typeof graphOf>, head: ReturnType<typeof graphOf>) => {
+      const changes = { ...AkanGraphDiff.between(base, head), since: "0123456789ab", unmapped: [] };
+      const answer = WorkspaceGraph.answerChanges(changes, { app: "sceny" });
+      if (!("edges" in answer)) throw new Error("expected an answer");
+      return answer.edges
+        .filter(({ kind }) => kind === "binds")
+        .map(({ label, to, change }) => `${change ?? "unchanged"} ${label} ${to}`);
+    };
+    expect(scopedBinds(graphOf(true, "1", "1"), graphOf(true, "2", "2"))).toEqual([
+      "unchanged apps/sceny adaptor::AnthropicLlm",
+    ]);
+    expect(scopedBinds(graphOf(true, "1", "1"), graphOf(false, "1", "2"))).toEqual([
+      "unchanged libs/genai adaptor:libs/genai:GenaiLlm",
+      "removed apps/sceny adaptor::AnthropicLlm",
+    ]);
+  });
+});
+
+describe("WorkspaceGraph.changesAt", () => {
+  it("maps an edit to a factory in one lib onto the guards it makes in another, and lists no file as unmapped", async () => {
+    const root = await mkdtemp(path.join(tmpdir(), "akan-graph-"));
+    roots.push(root);
+    const git = (...args: string[]) => {
+      const result = Bun.spawnSync(
+        ["git", "-c", "user.name=akan", "-c", "user.email=akan@example.com", "-c", "commit.gpgsign=false", ...args],
+        { cwd: root, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } },
+      );
+      expect(result.exitCode).toBe(0);
+      return result.stdout.toString().trim();
+    };
+    const write = async (file: string, text: string) => {
+      await mkdir(path.dirname(path.join(root, file)), { recursive: true });
+      await writeFile(path.join(root, file), text);
+    };
+    const factory = (body: string) => `import type { Guard } from "akanjs/signal";
+export const resourceGuard = (field: string) =>
+  class implements Guard {
+    canPass() {
+      return ${body};
+    }
+  };
+`;
+    git("init", "-q", "-b", "main");
+    await write("libs/util/srvkit/resource.ts", factory("!!field"));
+    await write(
+      "apps/demo/srvkit/guards.ts",
+      `import { resourceGuard } from "@libs/util/srvkit";\nexport const Member = resourceGuard("member");\n`,
+    );
+    git("add", "-A");
+    git("commit", "-q", "--no-verify", "-m", "base");
+    await write("libs/util/srvkit/resource.ts", factory("field.length > 0"));
+    const changes = await WorkspaceGraph.changesAt(
+      { workspaceRoot: root } as unknown as Workspace,
+      git("rev-parse", "HEAD"),
+    );
+    expect(changes.nodes.filter((node) => node.change).map(({ id, change }) => `${change} ${id}`)).toEqual([
+      "changed guard:apps/demo:Member",
+    ]);
+    expect(changes.unmapped).toEqual([]);
+    expect(changes.nodes.some((node) => "sources" in node)).toBe(false);
+  });
 });