@akanjs/devkit 3.0.0-alpha.98 → 3.0.0-beta.0

package/DEV_RUNTIME_KNOBS.md

@@ -97,12 +97,19 @@ sized against idle suspend being on**; setting it to `0` keeps every builder res
 
 Two things bound the peak rather than the floor:
 
-- **`--concurrency` (default 1).** Apps boot in waves, and the next wave starts only once the previous one
-  reports ready. A cold boot build is the builder's peak, so booting `n` apps at once means `n` overlapping
-  peaks — which is what OOM-kills a container that would have been fine with them staggered.
+- **`--concurrency` (default: what the machine allows).** Apps boot in waves, and the next wave starts only
+  once the previous one reports ready. A cold boot build is the builder's peak, so booting `n` apps at once
+  means `n` overlapping peaks — which is what OOM-kills a container that would have been fine with them
+  staggered. Unset, the wave is `min(apps, half the memory budget / 900MB per app, cores / 4)`, never below
+  one, and the session prints which — so a laptop boots its apps together and a 1.2GB container still
+  staggers them. The memory budget is the smaller of the host's RAM and `AKAN_MEMORY_LIMIT` / the cgroup
+  limit; `os.freemem()` is not consulted, because it counts free pages rather than reclaimable ones and
+  reports ~0.3GB on an idle 48GB laptop.
 - **`AKAN_MEMORY_LIMIT` is per process, not per session.** Each dev host derives its builder and RSC-worker
   ceilings from it independently, so a limit sized for one app does not become a budget for four. Divide it
-  yourself, or leave it unset on a laptop.
+  yourself, or leave it unset on a laptop. The one place it is read as a session ceiling is the boot wave
+  above, and only downward: a session cannot outgrow the container it runs in, whatever each process inside
+  it was told it may take.
 
 ## Sizing a small sandbox
 

package/artifact/implicitRootLayout.test.ts

@@ -50,7 +50,9 @@ describe("resolveSsrPageEntries", () => {
     expect(groupedRoot?.seedAbsPaths).toContain(groupedLayoutPath);
 
     const generatedSource = await Bun.file(groupedRoot?.moduleAbsPath ?? "").text();
-    expect(generatedSource).toContain('import * as inheritedLayout from "../../../page/_layout.tsx";');
+    // Both user modules go through the route resolver, so a `rootLayout()` chain and the legacy exports read alike.
+    expect(generatedSource).toContain('import * as inheritedModule from "../../../page/_layout.tsx";');
+    expect(generatedSource).toContain("const inheritedLayout = resolveRouteModule(inheritedModule as never");
     expect(generatedSource).not.toContain("<System.Provider");
     expect(generatedSource).toContain("export async function generateMetadata(props: PageProps)");
     expect(generatedSource).toContain("if (userLayout.generateMetadata) return userLayout.generateMetadata(props);");

package/artifact/implicitRootLayout.ts

@@ -185,13 +185,17 @@ async function writeGeneratedRootLayoutFile(opts: {
   const clientImport = opts.includeStInit
     ? `import { st } from "@apps/${opts.appName}/client";\nvoid st;\n`
     : `import "@apps/${opts.appName}/client";\n`;
+  // Both user modules go through `resolveRouteModule`: a `rootLayout()` chain and the legacy named exports read
+  // the same afterwards, and this file never has to know which shape the app wrote.
+  const inheritedLabel = inheritedSourceAbsPath ? path.relative(opts.appCwdPath, inheritedSourceAbsPath) : "";
   const inheritedImport = inheritedSourceSpecifier
-    ? `import * as inheritedLayout from ${JSON.stringify(inheritedSourceSpecifier)};\n`
-    : "const inheritedLayout = {};\n";
+    ? `import * as inheritedModule from ${JSON.stringify(inheritedSourceSpecifier)};\nconst inheritedLayout = resolveRouteModule(inheritedModule as never, ${JSON.stringify(inheritedLabel)}).module as LayoutModule;\n`
+    : "const inheritedLayout: LayoutModule = {};\n";
   const prefix = routePrefixForSegments(opts.boundary.segments);
+  const userLabel = opts.boundary.sourceAbsPath ? path.relative(opts.appCwdPath, opts.boundary.sourceAbsPath) : "";
   const userImport = sourceSpecifier
-    ? `import UserLayout, * as userLayout from ${JSON.stringify(sourceSpecifier)};\n`
-    : "const UserLayout = ({ children }) => children;\nconst userLayout = {};\n";
+    ? `import * as userModule from ${JSON.stringify(sourceSpecifier)};\nconst userLayout = resolveRouteModule(userModule as never, ${JSON.stringify(userLabel)}).module as LayoutModule;\nconst UserLayout = userLayout.default as (props: LayoutProps) => ReactNode | Promise<ReactNode>;\n`
+    : "const UserLayout = ({ children }: LayoutProps) => children;\nconst userLayout: LayoutModule = {};\n";
   const isAsyncUserLayout = opts.boundary.sourceAbsPath
     ? await AsyncDefaultExportDetector.detect(opts.boundary.sourceAbsPath)
     : false;
@@ -212,8 +216,9 @@ async function writeGeneratedRootLayoutFile(opts: {
   const layoutChild = isAsyncUserLayout ? "{layout}" : userLayoutElement;
   const layoutReturn = isAsyncUserLayout ? "layout" : userLayoutElement;
   const source = opts.includeSystemProvider
-    ? `import type { LayoutProps, PageProps } from "akanjs/client";
-import { loadFonts } from "akanjs/client";
+    ? `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
+import { loadFonts, resolveRouteModule } from "akanjs/client";
+import type { ReactNode } from "react";
 import { System } from "akanjs/ui";
 import { env } from "@apps/${opts.appName}/env/env.client";
 import { allDictionary } from ${JSON.stringify(dictMacroSpecifier)};
@@ -264,7 +269,9 @@ ${layoutBinding}  return (
   );
 }
 `
-    : `import type { LayoutProps, PageProps } from "akanjs/client";
+    : `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
+import { resolveRouteModule } from "akanjs/client";
+import type { ReactNode } from "react";
 ${inheritedImport}${userImport}
 export async function generateHead(props: PageProps) {
   if (userLayout.generateHead) return userLayout.generateHead(props);

package/executors.test.ts

@@ -315,6 +315,11 @@ describe("Workspace and app executor environment contracts", () => {
     const prepared = await app.prepareCommand("build");
     expect(prepared.env.AKAN_COMMAND_TYPE).toBe("build");
     expect(prepared.env.AKAN_PUBLIC_BASE_PATHS).toBe("admin");
+    // Bundling reads `process.env` through getPublicEnv and `define`s every AKAN_PUBLIC_* into a literal, so a
+    // dev port published here would be baked into the artifact and outrank the PORT the container is run with.
+    expect(process.env.AKAN_PUBLIC_APP_NAME).toBe("demo");
+    expect(process.env.AKAN_PUBLIC_CLIENT_PORT).toBeUndefined();
+    expect(process.env.AKAN_PUBLIC_SERVER_PORT).toBeUndefined();
     expect((await stat(path.join(root, "dist/apps/demo/private"))).isDirectory()).toBe(true);
     expect((await stat(path.join(root, "dist/apps/demo/public"))).isDirectory()).toBe(true);
   });
@@ -590,9 +595,7 @@ describe("Workspace and app executor environment contracts", () => {
         "_index.tsx": `export const pageConfig = { devOnly: process.env.NODE_ENV !== "production" };\n${PAGE_SOURCE}`,
       });
 
-      await expect(app.getPageKeys({ refresh: true })).rejects.toThrow(
-        "pageConfig.devOnly must be a literal true or false",
-      );
+      await expect(app.getPageKeys({ refresh: true })).rejects.toThrow("devOnly must be a literal true or false");
     });
 
     test("reads devOnly through a satisfies annotation", async () => {

package/executors.ts

@@ -1455,7 +1455,15 @@ export class AppExecutor extends SysExecutor {
     // which filters to AKAN_PUBLIC_*) sees AKAN_PUBLIC_APP_NAME — otherwise SSR throws
     // "environment variable AKAN_PUBLIC_APP_NAME is required". Only AKAN_PUBLIC_* is baked into bundles, so
     // this does not leak non-public env.
-    if (type === "build") Object.assign(process.env, env);
+    // The port keys are this machine's dev allocation, and `define` turns an `AKAN_PUBLIC_*` into a literal the
+    // artifact can never be run with a different value for — a baked port would outrank the `PORT` the container
+    // is started with and send every SSR self-call to a port nothing bound.
+    if (type === "build") {
+      const buildEnv = { ...env };
+      delete buildEnv.AKAN_PUBLIC_CLIENT_PORT;
+      delete buildEnv.AKAN_PUBLIC_SERVER_PORT;
+      Object.assign(process.env, buildEnv);
+    }
     return { env };
   }
   #publicEnv: Record<string, string> | null = null;
@@ -1540,6 +1548,7 @@ export class AppExecutor extends SysExecutor {
         else {
           const info = validator.validateRouteSourceExports(routeSource, absPath, parsed.kind, {
             rootLayout: isRootLayout,
+            pattern: parsed.pattern,
           });
           if (info.devOnly) {
             devOnlyKeys.add(key);

package/frontendBuild/fontOptimizer.test.ts

@@ -17,15 +17,16 @@ const makeApp = async (layoutSource: string) => {
   await mkdir(path.join(cwdPath, "public/fonts"), { recursive: true });
   await writeFile(path.join(cwdPath, "page/_layout.tsx"), layoutSource);
   await Bun.write(path.join(cwdPath, "public/fonts/Assistant-Regular.woff2"), Bun.file(SOURCE_FONT));
+  const warnings: string[] = [];
   const app = {
     cwdPath,
     dist: { cwdPath: path.join(root, "dist/apps/demo") },
     workspace: { workspaceRoot: root },
     getPageKeys: async () => ["./_layout.tsx"],
     verbose: () => undefined,
-    logger: { warn: () => undefined },
+    logger: { warn: (message: string) => warnings.push(message) },
   } as unknown as App;
-  return { app, cwdPath };
+  return { app, cwdPath, warnings };
 };
 
 const layoutWith = (extra = "") => `
@@ -40,6 +41,22 @@ export default function Layout() {
 }
 `;
 
+const chainLayoutWith = (declaration: string) => `
+import { rootLayout } from "akanjs/client";
+
+export default rootLayout()
+  .fonts(${declaration})
+  .theme("dark")
+  .render(({ children }) => children);
+`;
+
+const chainFontEntry = (extra = "") => `{
+      name: "Assistant",${extra}
+      paths: [{ src: "/fonts/Assistant-Regular.woff2", weight: 400 }],
+    }`;
+
+const chainFontList = (extra = "") => `[\n    ${chainFontEntry(extra)},\n  ]`;
+
 const optimize = (app: App) => new FontOptimizer(app, "start").optimize();
 
 afterEach(async () => {
@@ -109,3 +126,59 @@ describe("FontOptimizer cache", () => {
     expect(result.files).toEqual([]);
   });
 });
+
+describe("FontOptimizer discovery", () => {
+  test("reads the .fonts() stage of a rootLayout() chain", async () => {
+    const { app, warnings } = await makeApp(chainLayoutWith(chainFontList()));
+
+    const result = await optimize(app);
+
+    expect(result.fonts.map((font) => font.name)).toEqual(["Assistant"]);
+    expect(result.files).toHaveLength(1);
+    expect(result.css).toContain("@font-face");
+    expect(warnings).toEqual([]);
+  });
+
+  test("keeps reading the legacy fonts export", async () => {
+    const { app } = await makeApp(layoutWith());
+    const result = await optimize(app);
+    expect(result.fonts.map((font) => font.name)).toEqual(["Assistant"]);
+    expect(result.files).toHaveLength(1);
+  });
+
+  test("picks up a config field the chain declares, so the cache key sees it", async () => {
+    const { app, cwdPath } = await makeApp(chainLayoutWith(chainFontList()));
+    const first = await optimize(app);
+
+    await writeFile(
+      path.join(cwdPath, "page/_layout.tsx"),
+      chainLayoutWith(chainFontList(`\n      className: "font-brand",`)),
+    );
+
+    const second = await optimize(app);
+    expect(second.css).not.toBe(first.css);
+    expect(second.css).toContain(".font-brand");
+  });
+
+  // A list the build cannot read subsets nothing while the runtime still preloads /_akan/fonts, so the 404s
+  // have to be announced at build time rather than found in a browser console.
+  test("warns when the chain is handed a font list it cannot read", async () => {
+    const { app, warnings } = await makeApp(chainLayoutWith("brandFonts"));
+
+    const result = await optimize(app);
+
+    expect(result.fonts).toEqual([]);
+    expect(result.files).toEqual([]);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("page/_layout.tsx");
+  });
+
+  test("warns about an entry it cannot read and keeps the ones it can", async () => {
+    const { app, warnings } = await makeApp(chainLayoutWith(`[...brandFonts, ${chainFontEntry()}]`));
+
+    const result = await optimize(app);
+
+    expect(result.fonts.map((font) => font.name)).toEqual(["Assistant"]);
+    expect(warnings).toHaveLength(1);
+  });
+});

package/frontendBuild/fontOptimizer.ts

@@ -152,7 +152,7 @@ export class FontOptimizer {
         const file = Bun.file(filePath);
         if (!(await file.exists())) return;
         const source = await file.text();
-        // A declaration named `fonts` cannot exist in text that never mentions it, and parsing the
+        // A `.fonts()` stage or a `fonts` declaration cannot exist in text that never mentions it, and parsing the
         // route files that never declare one is what a cached optimize() otherwise spends its time on.
         if (!source.includes("fonts")) return;
         fonts.push(...this.#extractFontsExport(source, filePath));
@@ -186,23 +186,75 @@ export class FontOptimizer {
     if (faceCss.length > 0) this.#cssParts.push(...faceCss, this.#buildRootVariableRule(font));
   }
 
+  /**
+   * The font list of a route file, from the `.fonts([…])` stage of its default-exported `rootLayout()` chain
+   * or from the legacy `export const fonts`. Only an inline literal is readable, because the build enumerates
+   * routes without evaluating them — and a list it cannot read is warned about rather than skipped in silence:
+   * the runtime still emits `/_akan/fonts` preloads for fonts nothing subset, and every one of them 404s.
+   */
   #extractFontsExport(source: string, filePath: string): ReactFont[] {
     const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-    const fonts: ReactFont[] = [];
+    const declaration = this.#findFontsDeclaration(sourceFile);
+    if (!declaration) return [];
+    const value = this.#literalToValue(declaration);
+    const entries: unknown[] = Array.isArray(value) ? value : [];
+    const fonts = entries.filter((entry): entry is ReactFont => this.#isReadableFont(entry));
+    if (fonts.length !== entries.length || !Array.isArray(value))
+      this.#app.logger.warn(
+        `[font] ${path.relative(this.#app.cwdPath, filePath)} declares fonts the build cannot read without evaluating the module — write the list inline, or nothing is subset for it and every /_akan/fonts request 404s`,
+      );
+    return fonts.map((font) => this.#withFontDefaults(font));
+  }
+
+  #isReadableFont(value: unknown): value is ReactFont {
+    if (!value || typeof value !== "object") return false;
+    const font = value as Partial<ReactFont>;
+    return typeof font.name === "string" && Array.isArray(font.paths);
+  }
+
+  #findFontsDeclaration(sourceFile: ts.SourceFile): ts.Expression | null {
     for (const statement of sourceFile.statements) {
+      if (ts.isExportAssignment(statement)) {
+        if (statement.isExportEquals) continue;
+        const stage = this.#findChainStageArgument(statement.expression, "fonts");
+        if (stage) return stage;
+        continue;
+      }
       if (!ts.isVariableStatement(statement)) continue;
       const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
-      const isExported = modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
-      if (!isExported) continue;
+      if (!modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
       for (const declaration of statement.declarationList.declarations) {
         if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "fonts") continue;
-        const value = declaration.initializer ? this.#literalToValue(declaration.initializer) : null;
-        if (Array.isArray(value)) {
-          fonts.push(...(value as ReactFont[]).map((font) => this.#withFontDefaults(font)));
-        }
+        if (declaration.initializer) return declaration.initializer;
       }
     }
-    return fonts;
+    return null;
+  }
+
+  /** Walks a `rootLayout()` chain from its outermost call inward, so the stage that wins at runtime is the one read. */
+  #findChainStageArgument(expression: ts.Expression, stageName: string): ts.Expression | null {
+    let node = this.#unwrapExpression(expression);
+    let argument: ts.Expression | null = null;
+    while (node && ts.isCallExpression(node)) {
+      const callee = this.#unwrapExpression(node.expression);
+      if (!callee) return null;
+      if (ts.isIdentifier(callee)) return callee.text === "rootLayout" ? argument : null;
+      if (!ts.isPropertyAccessExpression(callee)) return null;
+      if (callee.name.text === stageName) argument ??= node.arguments[0] ?? null;
+      node = this.#unwrapExpression(callee.expression);
+    }
+    return null;
+  }
+
+  #unwrapExpression(expression?: ts.Expression): ts.Expression | undefined {
+    let current = expression;
+    while (
+      current &&
+      (ts.isAsExpression(current) || ts.isSatisfiesExpression(current) || ts.isParenthesizedExpression(current))
+    ) {
+      current = current.expression;
+    }
+    return current;
   }
 
   #literalToValue(node: ts.Node): unknown {

package/integration/devStabilityHarness.ts

@@ -159,19 +159,20 @@ export const server = new AkanServer("${this.appName}", {
       this.writeFile(
         "page/_layout.tsx",
         `import "./styles.css";
-import type { LayoutProps } from "akanjs/client";
+import { layout } from "akanjs/client";
 
-export default function Layout({ children }: LayoutProps) {
+export default layout().render(({ children }) => {
   return <>{children}</>;
-}
+});
 `,
       ),
       this.writeFile(
         "page/_index.tsx",
-        `import { marker } from "../common/marker";
+        `import { page } from "akanjs/client";
+import { marker } from "../common/marker";
 import { ClientMarker } from "../ui/ClientMarker";
 
-export default function Page() {
+export default page().render(() => {
   return (
     <main>
       <h1>Dev stability fixture</h1>
@@ -179,7 +180,7 @@ export default function Page() {
       <ClientMarker />
     </main>
   );
-}
+});
 `,
       ),
       // A second route exists so a test can ask for a page the backend has *never* built, at a moment of
@@ -187,16 +188,17 @@ export default function Page() {
       // request of a test is the only one that reaches the builder at all.
       this.writeFile(
         "page/second/_index.tsx",
-        `import { ClientMarker } from "../../ui/ClientMarker";
+        `import { page } from "akanjs/client";
+import { ClientMarker } from "../../ui/ClientMarker";
 
-export default function Page() {
+export default page().render(() => {
   return (
     <main>
       <h1>Second route</h1>
       <ClientMarker />
     </main>
   );
-}
+});
 `,
       ),
       this.writeFile(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.98",
+  "version": "3.0.0-beta.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -44,7 +44,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.98",
+    "akanjs": "3.0.0-beta.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/routeSourceValidator.test.ts

@@ -39,3 +39,66 @@ describe("RouteSourceValidator", () => {
     });
   });
 });
+
+describe("RouteSourceValidator route chains", () => {
+  const chain = (source: string, kind: "page" | "layout", pattern: string) =>
+    RouteSourceValidator.validateRouteSourceExports(source, `page/${kind}.tsx`, kind, { pattern });
+
+  test("reads params, prompt and devOnly off a page() chain without evaluating it", () => {
+    const source = [
+      'import { page } from "akanjs/client";',
+      "export default page()",
+      '  .param("projectId", ID, { desc: "The project." })',
+      '  .search("status", String)',
+      "  .config({ transition: 'stack', devOnly: true })",
+      '  .prompt("briefProject", "Brief one project.")',
+      "  .render(async ({ projectId }) => null);",
+    ].join("\n");
+    expect(chain(source, "page", "/:lang/project/:projectId")).toEqual({
+      devOnly: true,
+      chain: { kind: "page", params: ["projectId"], prompt: "briefProject" },
+    });
+  });
+
+  test("names a [segment] the page did not declare and a .param() the path lacks", () => {
+    expect(() => chain("export default page().render(() => null);", "page", "/:lang/org/:orgId")).toThrow(
+      'sits under [orgId] but declares no .param("orgId")',
+    );
+    expect(() => chain('export default page().param("orgId", ID).render(() => null);', "page", "/:lang/org")).toThrow(
+      'declares .param("orgId") but no [orgId] segment is in its path',
+    );
+    expect(() =>
+      chain('export default page().param("lang", String).render(() => null);', "page", "/:lang/org"),
+    ).toThrow('declares .param("lang"), which every route receives undeclared');
+    // A layout may leave a segment undeclared.
+    expect(() =>
+      chain("export default layout().render(({ children }) => children);", "layout", "/:lang/org/:orgId"),
+    ).not.toThrow();
+  });
+
+  test("refuses named exports beside a chain, a chain in the wrong file kind, and a computed name", () => {
+    expect(() =>
+      chain(["export default page().render(() => null);", "export const pageConfig = {};"].join("\n"), "page", "/"),
+    ).toThrow("exports pageConfig beside its page() chain");
+    expect(() => chain("export default layout().render(() => null);", "page", "/")).toThrow(
+      "is a page file but exports layout()",
+    );
+    expect(() => chain("export default page().render(() => null);", "layout", "/")).toThrow(
+      "is a layout file but exports page()",
+    );
+    expect(() => chain("export default page().param(name, ID).render(() => null);", "page", "/:lang/:x")).toThrow(
+      ".param() takes a string literal first",
+    );
+    expect(() => chain("export default page().config({ devOnly: flag }).render(() => null);", "page", "/")).toThrow(
+      "devOnly must be a literal true or false",
+    );
+  });
+
+  test("still reads the legacy shape as before", () => {
+    const source = [
+      "export default function Page() { return null; }",
+      "export const pageConfig = { devOnly: false };",
+    ].join("\n");
+    expect(chain(source, "page", "/")).toEqual({ devOnly: false });
+  });
+});

package/routeSourceValidator.ts

@@ -3,10 +3,27 @@ import ts from "typescript";
 
 /** What the build needs out of a route module without evaluating it. */
 export interface RouteSourceInfo {
-  /** `pageConfig.devOnly === true`, read straight off the AST. */
+  /** `pageConfig.devOnly === true`, or `.config({ devOnly: true })` on a chain, read straight off the AST. */
   devOnly: boolean;
+  /** Present when the default export is a `page()` / `layout()` / `rootLayout()` chain. */
+  chain?: RouteSourceChain;
 }
 
+export interface RouteSourceChain {
+  kind: "page" | "layout" | "rootLayout";
+  /** The `.param()` names, in chain order. */
+  params: string[];
+  /** The `.prompt()` name, when the page publishes itself as an MCP prompt. */
+  prompt?: string;
+}
+
+interface ChainStage {
+  name: string;
+  args: ts.NodeArray<ts.Expression>;
+}
+
+const chainRoots = new Set(["page", "layout", "rootLayout"]);
+
 /**
  * Static enforcement of the `page/` route conventions, split out of `executors.ts` so that importing
  * an executor does not pull `typescript` (+65MB resident) into the module graph. Both validators need
@@ -21,7 +38,7 @@ export class RouteSourceValidator {
     source: string,
     filePath: string,
     kind: "page" | "layout",
-    options: { rootLayout?: boolean } = {},
+    options: { rootLayout?: boolean; pattern?: string } = {},
   ): RouteSourceInfo {
     const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
     const allowed = getRouteExports(kind, { rootLayout: options.rootLayout });
@@ -81,7 +98,91 @@ export class RouteSourceValidator {
     if (exported.has("metadata") && exported.has("generateMetadata")) {
       throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
     }
-    return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };
+    const chain = RouteSourceValidator.#readChain(sourceFile, filePath);
+    if (!chain) return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };
+    const named = [...exported].filter((name) => name !== "default");
+    if (named.length)
+      throw new Error(
+        `[route-convention] ${filePath} exports ${named.join(", ")} beside its ${chain.kind}() chain — every route setting is a stage of the chain`,
+      );
+    if (kind === "page" && chain.kind !== "page")
+      throw new Error(`[route-convention] ${filePath} is a page file but exports ${chain.kind}()`);
+    if (kind === "layout" && chain.kind === "page")
+      throw new Error(`[route-convention] ${filePath} is a layout file but exports page()`);
+    if (options.pattern) RouteSourceValidator.#assertChainParams(chain, options.pattern, filePath);
+    return {
+      devOnly: chain.devOnly,
+      chain: { kind: chain.kind, params: chain.params, ...(chain.prompt ? { prompt: chain.prompt } : {}) },
+    };
+  }
+
+  /**
+   * The default export as a `page()` / `layout()` / `rootLayout()` chain, or null when the module is the legacy
+   * shape. Read off the source for the same reason `devOnly` is: the build enumerates routes without importing
+   * them, and `akan sync` should name a `[projectId]` folder whose page declares no `.param("projectId")` before
+   * the first request does.
+   */
+  static #readChain(sourceFile: ts.SourceFile, filePath: string) {
+    for (const statement of sourceFile.statements) {
+      if (!ts.isExportAssignment(statement) || statement.isExportEquals) continue;
+      let node = RouteSourceValidator.#unwrapExpression(statement.expression);
+      const stages: ChainStage[] = [];
+      while (node && ts.isCallExpression(node)) {
+        const callee = node.expression;
+        if (ts.isPropertyAccessExpression(callee)) {
+          stages.unshift({ name: callee.name.text, args: node.arguments });
+          node = callee.expression;
+          continue;
+        }
+        if (ts.isIdentifier(callee) && chainRoots.has(callee.text))
+          return RouteSourceValidator.#chainOf(callee.text as RouteSourceChain["kind"], stages, filePath);
+        return null;
+      }
+      return null;
+    }
+    return null;
+  }
+
+  static #chainOf(kind: RouteSourceChain["kind"], stages: ChainStage[], filePath: string) {
+    const params: string[] = [];
+    let prompt: string | undefined;
+    let devOnly = false;
+    const literal = (stage: ChainStage) => {
+      const first = stage.args[0];
+      if (!first || !ts.isStringLiteralLike(first))
+        throw new Error(
+          `[route-convention] .${stage.name}() takes a string literal first in ${filePath} — the build reads it without evaluating the module`,
+        );
+      return first.text;
+    };
+    for (const stage of stages) {
+      if (stage.name === "param") params.push(literal(stage));
+      else if (stage.name === "prompt") prompt = literal(stage);
+      else if (stage.name === "config")
+        devOnly = RouteSourceValidator.#devOnlyOf(RouteSourceValidator.#unwrapExpression(stage.args[0]), filePath);
+    }
+    return { kind, params, prompt, devOnly };
+  }
+
+  /** The same rule the loader applies: a page names every `[x]` it sits under, a layout may name a subset. */
+  static #assertChainParams(chain: { kind: string; params: string[] }, pattern: string, filePath: string) {
+    const inPath = pattern
+      .split("/")
+      .filter((part) => part.startsWith(":"))
+      .map((part) => part.slice(1))
+      .filter((name) => name !== "lang");
+    if (chain.params.includes("lang"))
+      throw new Error(`[route-convention] ${filePath} declares .param("lang"), which every route receives undeclared`);
+    const unknown = chain.params.find((name) => !inPath.includes(name));
+    if (unknown)
+      throw new Error(
+        `[route-convention] ${filePath} declares .param("${unknown}") but no [${unknown}] segment is in its path`,
+      );
+    const undeclared = inPath.find((name) => !chain.params.includes(name));
+    if (chain.kind === "page" && undeclared)
+      throw new Error(
+        `[route-convention] ${filePath} sits under [${undeclared}] but declares no .param("${undeclared}") — a page reads only what it declares`,
+      );
   }
 
   /**
@@ -98,24 +199,30 @@ export class RouteSourceValidator {
       for (const declaration of statement.declarationList.declarations) {
         if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "pageConfig") continue;
         const initializer = RouteSourceValidator.#unwrapExpression(declaration.initializer);
-        if (!initializer || !ts.isObjectLiteralExpression(initializer)) continue;
-        for (const property of initializer.properties) {
-          if (!ts.isPropertyAssignment(property)) continue;
-          const name = property.name;
-          const key = ts.isIdentifier(name) ? name.text : ts.isStringLiteral(name) ? name.text : null;
-          if (key !== "devOnly") continue;
-          const value = RouteSourceValidator.#unwrapExpression(property.initializer);
-          if (value?.kind === ts.SyntaxKind.TrueKeyword) return true;
-          if (value?.kind === ts.SyntaxKind.FalseKeyword) return false;
-          throw new Error(
-            `[route-convention] pageConfig.devOnly must be a literal true or false in ${filePath} — the build reads it without evaluating the module`,
-          );
-        }
+        if (initializer && ts.isObjectLiteralExpression(initializer))
+          return RouteSourceValidator.#devOnlyOf(initializer, filePath);
       }
     }
     return false;
   }
 
+  static #devOnlyOf(config: ts.Expression | undefined, filePath: string): boolean {
+    if (!config || !ts.isObjectLiteralExpression(config)) return false;
+    for (const property of config.properties) {
+      if (!ts.isPropertyAssignment(property)) continue;
+      const name = property.name;
+      const key = ts.isIdentifier(name) ? name.text : ts.isStringLiteral(name) ? name.text : null;
+      if (key !== "devOnly") continue;
+      const value = RouteSourceValidator.#unwrapExpression(property.initializer);
+      if (value?.kind === ts.SyntaxKind.TrueKeyword) return true;
+      if (value?.kind === ts.SyntaxKind.FalseKeyword) return false;
+      throw new Error(
+        `[route-convention] devOnly must be a literal true or false in ${filePath} — the build reads it without evaluating the module`,
+      );
+    }
+    return false;
+  }
+
   static #unwrapExpression(expression?: ts.Expression): ts.Expression | undefined {
     let current = expression;
     while (

package/subspace.test.ts

@@ -202,6 +202,21 @@ describe("Subspace push", () => {
     expect(manifest.akan.source.hash).toMatch(/^[0-9a-f]{32}$/);
   });
 
+  test("ships a library file the workspace deleted, instead of reading it off the clone's stale index", async () => {
+    const { wsRoot, bareRoot, workRoot, subspace } = await makeMirror("moved-served", "moved-private", "moved-kit");
+    expect((await subspace.push("develop", { verify: false })).outcome).toBe("pushed");
+
+    await rm(path.join(wsRoot, "libs/moved-kit/common/helper.ts"));
+    await write(path.join(wsRoot, "libs/moved-kit/common/renamed.ts"), "export const helper = 1;\n");
+    await git(wsRoot, ["add", "-A"]);
+    await git(wsRoot, ["commit", "--quiet", "-m", "move the helper"]);
+
+    expect((await subspace.push("develop", { verify: false })).outcome).toBe("pushed");
+    const subspaceRoot = await cloneSubspace(workRoot, bareRoot, "moved-check");
+    expect(await FileSys.fileExists(path.join(subspaceRoot, "libs/moved-kit/common/helper.ts"))).toBe(false);
+    expect(await FileSys.fileExists(path.join(subspaceRoot, "libs/moved-kit/common/renamed.ts"))).toBe(true);
+  });
+
   test("is idempotent — a second push with no workspace change is skipped", async () => {
     const { subspace } = await makeMirror("idem-served", "idem-private", "idem-kit");
     expect((await subspace.push("develop", { verify: false })).outcome).toBe("pushed");

package/subspace.ts

@@ -232,7 +232,7 @@ export class Subspace {
     }
     const clone = new Executor(`subspace-${this.name}`, this.#clonePath);
     await clone.spawn("git", ["fetch", "--quiet", "origin", branch]);
-    await clone.spawn("git", ["checkout", "--quiet", "-B", branch, `origin/${branch}`]);
+    await clone.spawn("git", ["checkout", "--quiet", "-f", "-B", branch, `origin/${branch}`]);
     await clone.spawn("git", ["clean", "-qfd"]);
     return clone;
   }
@@ -462,10 +462,17 @@ export class Subspace {
       "--",
       `libs/${lib}`,
     ]);
-    const files = listed
+    const candidates = listed
       .split("\0")
       .filter((file) => !!file && !this.#isSubspaceOwned(file))
       .sort();
+    //* `--cached` reads the clone's index, which the slice replaced the members without updating — so it still
+    //* names every file the workspace has deleted or moved since the last push, and opening one throws. The
+    //* index is only reconciled by the `git add -A` a push commits with, long after the stamp is written.
+    const present = await Promise.all(
+      candidates.map(async (file) => await FileSys.entryExists(path.join(this.#clonePath, file))),
+    );
+    const files = candidates.filter((_, index) => present[index]);
     const hasher = new Bun.CryptoHasher("sha256");
     for (const file of files) {
       const content = await FileSys.readText(path.join(this.#clonePath, file));

package/transforms/asyncDefaultExportDetector.ts

@@ -65,6 +65,8 @@ export class AsyncDefaultExportDetector {
 
       if (ts.isExportAssignment(statement)) {
         if (this.#isAsyncFunctionExpression(statement.expression)) return true;
+        // `export default layout()….render(fn)`: the loader unfolds the chain into an async adapter whatever `fn` is.
+        if (ts.isCallExpression(statement.expression)) return true;
         if (ts.isIdentifier(statement.expression)) defaultIdentifier = statement.expression.text;
         continue;
       }