@akanjs/devkit 3.2.0-rc.2 → 3.2.0-rc.3

package/CHANGELOG.md

@@ -34,6 +34,17 @@
   - **`pkgs/akanjs/ARCHITECTURE.md`** pairs a hand-kept walk through the processes and a request with a generated part between markers. `akan sync-architecture` regenerates that part, and a devkit test fails when it is stale, when a channel is gone, when two facets load values from each other, when a message lacks a recognised sender or handler outside a short list whose other end lies beyond the framework source, or when the hand-kept part names a class the source no longer has.
   - **`AkanIpcMessage` no longer lists `backend-ready`.** The gateway sends it to the dev host, which reads it as a `BuilderMessage`, where it stays; no gateway or child ever handled it.
 
+- 4d61170: The Akan Graph follows an app's adaptor wiring further. `applyAdaptor(LlmAdaptorRole, ChatCompletionsLlm)` in an app's or lib's `option.ts` draws a `binds` edge from the role, `adaptor::LlmAdaptorRole`, to the implementation it binds, labelled with the app or lib and located at the call, so a method that calls a plugged role reaches the class that answers it. `get_graph` scoped to an app keeps that app's own bindings, and a lib's binding of a role the app does not bind itself; scoped to a lib or a module it keeps every binding of a role it reaches. A Change Map carries every binding of a role it shows, changed or not, so the binding an app runs stays in view; a binding the app removed no longer hides the lib binding it now runs; and Studio's Change Map for one app keeps only the bindings that app runs. An app service holds the fields its module's lib services plug (`...user.services`), so `this.notifier.getMemo()` in an app method links to the `Notifier` a lib's `MemoService` plugs, where it linked to the `memo` model; a service whose own builder declares the field (`notifier: use<…>()`) inherits nothing. A plug imported from a package outside the workspace, `plug(Stripe)` from `stripe-sdk`, or through a lib's re-export of it (`export { Stripe }`, `export { default as Stripe }`, or `export * from "stripe-sdk"` where the lib declares no `Stripe` itself), is `adaptor:stripe-sdk:Stripe` with the package in `detail`, where it linked to a same-name adaptor the app declares or to an unlocated `adaptor:libs/util:Stripe`. Two adaptors with the same class name in one app or lib are two nodes, each with its own location, digest and `plugs`, and a plug reaches the one its import names. A job's `detail` lists only the options its kind honours: `once` on an `initialize` job, `unlocked` on an `interval` job (`Bun.cron` never overlaps a cron job, so `lock: false` changes nothing there); `cron("0 * * * *" as const)` reads `0 * * * *`.
+
+  Ids and details that change for a saved graph or a Change Map base:
+
+  - While two adaptors of one owner share a class name, each is keyed by its file, `adaptor:apps/demo:srvkit/clockB.ts#Clock`; an adaptor whose name no other adaptor of its owner shares keeps `adaptor:<owner>:<Name>`. The Change Map treats the two forms of one declaration as one node, so a second same-name adaptor shows as one added node, not a removal of the first.
+  - A plug from a non-workspace package is `adaptor:<package>:<Name>` with the package as `detail`, where it was `adaptor::<Name>` or a workspace adaptor of that name.
+  - A job's `detail` drops `once` and `unlocked` where the runtime ignores them, and `as const` from a cron expression.
+
+  - **`binds`** joins `AkanGraphEdgeKind` in `akanjs/common`.
+  - **`FileFacts.adaptorBindings`** in `@akanjs/language`: each `applyAdaptor(role, adaptor)` call a file makes; `AkanIndex.setFile` also reads non-test files whose text mentions `applyAdaptor`. **`ServiceClassFact.fields`**: the names a service's builder declares.
+
 - c723713: The Akan Graph keys a guard function by the file that declares it, locates more of a workspace's guards, and stops counting things that are not guards.
 
   A guard function a route or layout imports is keyed by its file, as one the page declares already was: `guard:libs/shared:webkit/signedIn.ts#signedIn`. A `canEdit` in `webkit/` and one in `common/` are two nodes, each at its own declaration, and an edit to either marks only that one changed in the Change Map. A guard called through a namespace import (`auth.signedIn()`), or imported under a name a file re-exports (`export { signedIn as hasSession } from "./auth"`), reaches its declaration. A function the guard declares, or a parameter it binds, shadows an import of the same name only inside its own scope, so `[1].forEach((signedIn) => …)` no longer hides a real `signedIn()` beside it. A guard declared after another declarator (`export const ready = true, signedIn = …`) is found, and an overloaded guard's digest covers every signature. Only a file whose text declares or re-exports the name is parsed, so a guard that calls `usePage()` from the generated client no longer parses every page that names it.
@@ -204,6 +215,8 @@
   - **The CSR build and its MCP App views** rewrite `akanjs/ui` imports to the components a file names, as the SSR route builds already did, so a page that imports `Link` no longer bundles every component.
   - **Animations use `@react-spring/web`** instead of the `react-spring` umbrella package, which also installed the native, three.js, konva and zdog renderers.
 
+- 58b7329: `akan create-scalar`, `remove-scalar`, `create-module`, `create-service`, `create-application`, `create-library`, `install-library` and `create-workspace --app` refuse a name that is not one plain path segment before they touch a file, such as `"../.." is no scalar name; use letters, digits, - and _, starting with a letter`. Before, the name went into the path unchecked: `akan remove-scalar ../.. <app>` deleted `apps/<app>` and exited 0, and the create commands wrote their files outside `lib/`, `apps/` or `libs/`. A scalar, module or service name is checked as a workflow's `module` input already was, an app or lib name as its `app` input; both checks now live in `@akanjs/devkit/workflow/plainName`, with `assertPlainName`.
+- b4b8f85: `akan preview` and the code agent's page preview give a browser that died or was closed the full `startTimeoutMs` (120 s by default) for its next start. Before, after one page had run out of the start bound, a browser that then died while another page waited for it stayed marked as slow to start. The next page started a fresh browser within only its own `timeoutMs` (60 s for `akan preview`, 30 s for the code agent's check).
 - 686e0b8: `akan preview` and the code agent's page preview bound a page only once the browser is up. Before, a process's first page shared its `timeoutMs` with starting the browser. On a cold machine where Chrome took longer than that to start, the first page failed as `Timed out loading …; the dev server may be rebuilding or stuck.`
 
   Starting the browser now has its own bound of 120 s, `startTimeoutMs` on `PreviewView.probe`. Running out of it reads `Timed out starting the <engine> browser after 120 s.`, where the engine is `chrome` or `webkit`. A browser that misses its bound may still come up late, so later pages in that process try again, but each waits only its own `timeoutMs` for the browser. Once the browser answers, the full bound applies again. So a browser that never starts holds the first page for 120 s, where before it held it for `timeoutMs` (60 s for `akan preview`, 30 s for the code agent's check).
@@ -327,6 +340,7 @@
 - Updated dependencies [61fbd7d]
 - Updated dependencies [b3f85fa]
 - Updated dependencies [a707354]
+- Updated dependencies [4d61170]
 - Updated dependencies [c723713]
 - Updated dependencies [0351ad4]
 - Updated dependencies [ba417c6]
@@ -381,7 +395,9 @@
 - Updated dependencies [5e08722]
 - Updated dependencies [df32c46]
 - Updated dependencies [5f809e8]
+- Updated dependencies [76705dd]
 - Updated dependencies [206bb69]
+- Updated dependencies [e4c7e5c]
 - Updated dependencies [6291fec]
 - Updated dependencies [0c480c6]
 - Updated dependencies [d9eaacc]

package/akanMcpContract.ts

@@ -324,7 +324,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 } },
   },
   {

package/frontendBuild/clientEntryDiscovery.test.ts

@@ -2,6 +2,7 @@ import { afterAll, describe, expect, test } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { createTsconfigPackageResolver } from "../transforms/barrelImportsPlugin";
 import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
 
 const dirs: string[] = [];
@@ -122,6 +123,35 @@ describe("GraphClientEntryDiscovery", () => {
     expect(await discovery.discover([file("M5.tsx")])).toEqual([file("C.tsx")]);
   });
 
+  test("a root layout importing System by its file under a tsconfig wildcard reaches System's client entries", async () => {
+    const file = await tempDir();
+    const workspaceRoot = path.dirname(file("x"));
+    await Bun.write(
+      file("pkgs/akanjs/ui/System/index.tsx"),
+      'import SSR from "./SSR";\nexport const System = { SSR };\n',
+    );
+    await Bun.write(
+      file("pkgs/akanjs/ui/System/SSR.tsx"),
+      'import { ClientWrapper } from "./Client";\nexport default ClientWrapper;\n',
+    );
+    await Bun.write(
+      file("pkgs/akanjs/ui/System/Client.tsx"),
+      '"use client";\nexport const ClientWrapper = () => null;\n',
+    );
+    await Bun.write(
+      file("root/__root_layout.tsx"),
+      'import { System } from "akanjs/ui/System/index.tsx";\nexport default System;\n',
+    );
+    const resolvePackage = await createTsconfigPackageResolver({
+      workspace: { workspaceRoot },
+      getTsConfig: async () => ({ compilerOptions: { paths: { "akanjs/ui/*": ["./pkgs/akanjs/ui/*"] } } }),
+    } as never);
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, resolvePackage);
+    expect(await discovery.discover([file("root/__root_layout.tsx")])).toEqual([
+      file("pkgs/akanjs/ui/System/Client.tsx"),
+    ]);
+  });
+
   test("a file walked inside an import cycle keeps no partial result for a walk that starts at it", async () => {
     const file = await tempDir();
     await Bun.write(file("A.tsx"), 'import "./B";\nimport "./C";\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.2.0-rc.2",
+  "version": "3.2.0-rc.3",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.2.0-rc.2",
+    "@akanjs/language": "3.2.0-rc.3",
     "@earendil-works/pi-agent-core": "1.3.0",
     "@earendil-works/pi-ai": "1.3.0",
     "@earendil-works/pi-codemode": "1.3.0",
@@ -50,7 +50,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.2.0-rc.2",
+    "akanjs": "3.2.0-rc.3",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/preview/PreviewView.ts

@@ -80,12 +80,14 @@ export class PreviewView {
     const view = PreviewView.#open({ width, height, engine, onConsole: (line) => logs.push(line) });
     try {
       //? A browser that missed its start bound may still come up, so a later page retries it within only its own bound.
+      //? One that died or was closed instead is spawned afresh by the next view, which gets the full bound.
       const startMs = PreviewView.#stalled.has(engine) ? Math.min(startTimeoutMs, timeoutMs) : startTimeoutMs;
       const stalled = new Error(`Timed out starting the ${engine} browser after ${startMs / 1_000} s.`);
       await PreviewView.#within(view.navigate("about:blank"), Date.now() + startMs, stalled).then(
         () => PreviewView.#stalled.delete(engine),
         (error: unknown) => {
           if (error === stalled) PreviewView.#stalled.add(engine);
+          else PreviewView.#stalled.delete(engine);
           throw error;
         },
       );

package/preview/previewView.test.ts

@@ -14,7 +14,12 @@ const slowChromeRuns = PreviewView.isAvailable("chrome") && process.platform !==
 const withSlowChrome = async (body: string, startSeconds = 3) => {
   const dir = await mkdtemp(path.join(tmpdir(), "akan-slow-chrome-"));
   const chrome = path.join(dir, "chrome");
-  await writeFile(chrome, `#!/bin/sh\nsleep ${startSeconds}\nexec "${PreviewChrome.executable()}" "$@"\n`);
+  const chromeLog = path.join(dir, "chrome.log");
+  //? Bun.WebView sends the browser's stderr to /dev/null, which would hide why it died.
+  await writeFile(
+    chrome,
+    `#!/bin/sh\nexec 2>>"${chromeLog}"\nsleep ${startSeconds}\nexec "${PreviewChrome.executable()}" "$@"\n`,
+  );
   await chmod(chrome, 0o755);
   const script = `const { PreviewView } = await import(${JSON.stringify(path.join(import.meta.dir, "PreviewView.ts"))});\n${body}`;
   //? Chrome is spawned once per process, so only a fresh process takes the slow executable.
@@ -30,7 +35,10 @@ const withSlowChrome = async (body: string, startSeconds = 3) => {
       new Response(child.stderr).text(),
       child.exited,
     ]);
-    return { code, out: out.trim(), err };
+    const chromeErr = await Bun.file(chromeLog)
+      .text()
+      .catch(() => "");
+    return { code, out: out.trim(), log: `${err}\nChrome's stderr:\n${chromeErr}` };
   } finally {
     child.kill();
     await rm(dir, { recursive: true, force: true });
@@ -112,12 +120,12 @@ describe("PreviewView", () => {
     async () => {
       const server = serve("<!doctype html><title>Up</title><body>up</body>");
       try {
-        const { code, out, err } = await withSlowChrome(
+        const { code, out, log } = await withSlowChrome(
           `const probe = await PreviewView.probe("http://localhost:${server.port}/", { engine: "chrome", timeoutMs: 1_500 });
 console.log(probe.text);`,
         );
-        expect(out || err).toBe("up");
-        expect(code).toBe(0);
+        expect(out, log).toBe("up");
+        expect(code, log).toBe(0);
       } finally {
         server.stop(true);
       }
@@ -128,7 +136,7 @@ console.log(probe.text);`,
   test.skipIf(!slowChromeRuns)(
     "gives a later page only its own bound for a browser that missed its start, and recovers once it is up",
     async () => {
-      const { code, out, err } = await withSlowChrome(
+      const { code, out, log } = await withSlowChrome(
         `const open = () =>
   PreviewView.probe("about:blank", { engine: "chrome", startTimeoutMs: 1_500, timeoutMs: 1_000 }).then(
     () => "opened",
@@ -137,7 +145,7 @@ console.log(probe.text);`,
 console.log(await open());
 console.log(await open());
 let late = await open();
-for (let tries = 0; late !== "opened" && tries < 100; tries++) late = await open();
+for (let tries = 0; late.startsWith("Timed out starting") && tries < 100; tries++) late = await open();
 console.log(late);
 Bun.WebView.closeAll();
 await Bun.sleep(500);
@@ -145,7 +153,7 @@ console.log(await open());
 Bun.WebView.closeAll();`,
         6,
       );
-      expect(out || err).toBe(
+      expect(out, log).toBe(
         [
           "Timed out starting the chrome browser after 1.5 s.",
           "Timed out starting the chrome browser after 1 s.",
@@ -153,7 +161,36 @@ Bun.WebView.closeAll();`,
           "Timed out starting the chrome browser after 1.5 s.",
         ].join("\n"),
       );
-      expect(code).toBe(0);
+      expect(code, log).toBe(0);
+    },
+    browserTestMs,
+  );
+
+  test.skipIf(!slowChromeRuns)(
+    "gives a browser killed after it missed its start the full bound for its next start",
+    async () => {
+      const { code, out, log } = await withSlowChrome(
+        `const open = () =>
+  PreviewView.probe("about:blank", { engine: "chrome", startTimeoutMs: 1_500, timeoutMs: 1_000 }).then(
+    () => "opened",
+    (error) => error.message,
+  );
+console.log(await open());
+const killed = open();
+Bun.WebView.closeAll();
+console.error(await killed);
+await Bun.sleep(500);
+console.log(await open());
+Bun.WebView.closeAll();`,
+        6,
+      );
+      expect(out, log).toBe(
+        [
+          "Timed out starting the chrome browser after 1.5 s.",
+          "Timed out starting the chrome browser after 1.5 s.",
+        ].join("\n"),
+      );
+      expect(code, log).toBe(0);
     },
     browserTestMs,
   );

package/workflow/index.ts

@@ -6,6 +6,7 @@ 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,15 @@
+export const sysNamePattern = /^[a-z0-9][a-zA-Z0-9_-]*$/;
+export const identifierPattern = /^_{0,2}[a-zA-Z][a-zA-Z0-9_-]*$/;
+
+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 assertPlainName = (kind: "app" | "lib" | "module" | "service" | "scalar", name: string) => {
+  const isSys = kind === "app" || kind === "lib";
+  if (isSys ? isWorkflowSysName(name) : isWorkflowModuleName(name)) return;
+  throw new Error(
+    `${JSON.stringify(name)} is no ${kind} name; use letters, digits, - and _, starting with ${isSys ? "a lowercase letter or digit" : "a letter"}`,
+  );
+};

package/workflow/plan.ts

@@ -5,6 +5,7 @@ import { resolveWorkflowSys } from "./executor";
 import { InteractionScaffold } from "./interactionScaffold";
 import { KeyRename } from "./keyRename";
 import { MutationScaffold } from "./mutationScaffold";
+import { identifierPattern, sysNamePattern } from "./plainName";
 import { coerceFieldDefault, getSysRoot, moduleSourcePaths } from "./source";
 import type {
   WorkflowDiagnostic,
@@ -21,8 +22,6 @@ 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,
@@ -36,11 +35,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);

package/workspaceGraph.test.ts

@@ -3,6 +3,7 @@ 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";
 
@@ -186,6 +187,89 @@ 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", () => {

package/workspaceGraph.ts

@@ -1,6 +1,13 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { type AkanChangeMap, type AkanGraph, AkanGraphDiff, type AkanGraphNode, AkanIndex } from "@akanjs/language";
+import {
+  type AkanChangeMap,
+  type AkanGraph,
+  AkanGraphDiff,
+  type AkanGraphEdge,
+  type AkanGraphNode,
+  AkanIndex,
+} from "@akanjs/language";
 import ts from "typescript";
 import type { Workspace } from "./commandDecorators";
 import { GitRevision } from "./gitRevision";
@@ -109,9 +116,30 @@ export class WorkspaceGraph {
     //? A lib's guard is linked from every app's endpoints; through it, a scope would reach all of them.
     const guards = new Set(graph.nodes.filter((node) => node.kind === "guard").map((node) => node.id));
     const reaches = (id: string) => seeds.has(id) && !guards.has(id);
-    const edges = graph.edges.filter((edge) => reaches(edge.from) || reaches(edge.to));
-    const ids = new Set([...seeds, ...edges.flatMap((edge) => [edge.from, edge.to])]);
-    return { version: 1, nodes: graph.nodes.filter((node) => ids.has(node.id)), edges };
+    const edges = graph.edges.filter((edge) => edge.kind !== "binds" && (reaches(edge.from) || reaches(edge.to)));
+    const kept = new Set([...seeds, ...edges.flatMap((edge) => [edge.from, edge.to])]);
+    const isLib =
+      !!app &&
+      graph.nodes.some((node) => node.owner === `libs/${app}`) &&
+      !graph.nodes.some((node) => node.owner === `apps/${app}`);
+    const applicable = WorkspaceGraph.#bindingsOf(graph, app && !isLib ? `apps/${app}` : null);
+    const isOwn = (edge: AkanGraphEdge) => !module && !!owners?.has(edge.label ?? "");
+    const roles = new Set(
+      applicable.filter((edge) => isOwn(edge) || kept.has(edge.from) || reaches(edge.to)).map((edge) => edge.from),
+    );
+    const bindings = applicable.filter((edge) => roles.has(edge.from));
+    const ids = new Set([...kept, ...bindings.flatMap((edge) => [edge.from, edge.to])]);
+    return { version: 1, nodes: graph.nodes.filter((node) => ids.has(node.id)), edges: [...edges, ...bindings] };
+  }
+
+  //? An app runs a role as its own `applyAdaptor` binds it, else as a lib's does; a lib's code runs under every app's.
+  static #bindingsOf(graph: AkanGraph, appOwner: string | null) {
+    const binds = graph.edges.filter((edge) => edge.kind === "binds");
+    if (!appOwner) return binds;
+    const own = new Set(
+      binds.filter((edge) => edge.label === appOwner && edge.change !== "removed").map((edge) => edge.from),
+    );
+    return binds.filter((edge) => edge.label === appOwner || (!edge.label?.startsWith("apps/") && !own.has(edge.from)));
   }
 
   //? Pages are many and most only wrap one another, so a graph too large to answer whole drops the pages that neither
@@ -141,7 +169,14 @@ export class WorkspaceGraph {
     const isVisible = ({ owner }: AkanGraphNode) => !owner || owner === appOwner || owner.startsWith("libs/");
     const nodes = graph.nodes.filter(isVisible);
     const ids = new Set(nodes.map((node) => node.id));
-    return { version: 1, nodes, edges: graph.edges.filter((edge) => ids.has(edge.from) && ids.has(edge.to)) };
+    const bindings = new Set(WorkspaceGraph.#bindingsOf(graph, appOwner));
+    return {
+      version: 1,
+      nodes,
+      edges: graph.edges.filter(
+        (edge) => ids.has(edge.from) && ids.has(edge.to) && (edge.kind !== "binds" || bindings.has(edge)),
+      ),
+    };
   }
 
   static changesVisibleTo(changes: AkanChangeMap, app: string): AkanChangeMap {