@abide/abide 0.49.0 → 0.50.1

package/src/abideResolverPlugin.ts

@@ -1,30 +1,32 @@
 // node:fs existsSync — Bun plugin onResolve is sync-only; Bun.file().exists() is async
 import { existsSync, statSync } from 'node:fs'
-import { dirname, join } from 'node:path'
 import type { BunPlugin } from 'bun'
 import { Glob } from 'bun'
 import { abideImportName } from './lib/shared/abideImportName.ts'
 import { abideLog } from './lib/shared/abideLog.ts'
+import { bundleGraphFromMetafile } from './lib/shared/bundleGraphFromMetafile.ts'
+import type { RpcServerProgram } from './lib/shared/createRpcServerProgram.ts'
 import { escapeRegex } from './lib/shared/escapeRegex.ts'
-import { fileName } from './lib/shared/fileName.ts'
 import { fileStem } from './lib/shared/fileStem.ts'
 import { jsonSchemaForPromptArguments } from './lib/shared/jsonSchemaForPromptArguments.ts'
 import { manifestModule } from './lib/shared/manifestModule.ts'
+import { PROXIED_SERVER_SUBDIRS } from './lib/shared/PROXIED_SERVER_SUBDIRS.ts'
 import { pageUrlForFile } from './lib/shared/pageUrlForFile.ts'
 import { parsePromptMarkdown } from './lib/shared/parsePromptMarkdown.ts'
 import { prepareRpcModule } from './lib/shared/prepareRpcModule.ts'
 import { prepareSocketModule } from './lib/shared/prepareSocketModule.ts'
 import { programNameForPackage } from './lib/shared/programNameForPackage.ts'
 import { promptNameForFile } from './lib/shared/promptNameForFile.ts'
+import {
+    DEFINE_RPC_GLOBAL,
+    DEFINE_SOCKET_GLOBAL,
+    REMOTE_PROXY_GLOBAL,
+} from './lib/shared/RPC_SHIM_GLOBALS.ts'
 import { readPackageJson } from './lib/shared/readPackageJson.ts'
+import { rpcServerForRoot } from './lib/shared/rpcServerForRoot.ts'
 import { rpcUrlForFile } from './lib/shared/rpcUrlForFile.ts'
+import { scanPages } from './lib/shared/scanPages.ts'
 import { socketNameForFile } from './lib/shared/socketNameForFile.ts'
-import { writeHealthDts } from './lib/shared/writeHealthDts.ts'
-import { writePublicAssetsDts } from './lib/shared/writePublicAssetsDts.ts'
-import { writeRoutesDts } from './lib/shared/writeRoutesDts.ts'
-import { writeRpcDts } from './lib/shared/writeRpcDts.ts'
-import { writeTestRpcDts } from './lib/shared/writeTestRpcDts.ts'
-import { writeTestSocketsDts } from './lib/shared/writeTestSocketsDts.ts'
 
 /*
 Resolves a bare directory or extensionless path to a concrete file. Mirrors
@@ -68,6 +70,13 @@ function resolveExtensionUncached(path: string): string {
 
 const NS = 'abide-virtual'
 
+/* Per-input source-byte budget for the client bundle-hygiene diagnostic (ADR-0031 D2): a single
+   project module that SURVIVES tree-shaking into the client bundle heavier than this earns a
+   non-blocking build warning, so an accidentally-huge module (an inlined dataset, a fat vendored
+   dep pulled into src) is observable without a new bundler pass. Never fails the build — the only
+   hard onEnd failure stays the real side-crossing violation. */
+const CLIENT_BUNDLE_INPUT_BUDGET_BYTES = 512 * 1024
+
 /* Memoises a zero-arg async producer so repeat calls reuse the first in-flight promise. */
 function once<T>(produce: () => Promise<T>): () => Promise<T> {
     let promise: Promise<T> | undefined
@@ -144,57 +153,19 @@ export function abideResolverPlugin({
     re-globbing the trees. The shell read is memoised the same way so two
     passes don't re-read app.html from disk.
     */
-    const scanPagesOnce = once(() =>
-        scanPages(pagesDir).then(async (scan) => {
-            await writeRoutesDts({
-                cwd,
-                pageFiles: scan.pageFiles,
-                importName: await abideImportNameOnce(),
-            })
-            return scan
-        }),
-    )
-    const scanRpcOnce = once(() =>
-        scanDir(rpcDir, '**/*.ts').then(async (rpcFiles) => {
-            const importName = await abideImportNameOnce()
-            await writeRpcDts({ cwd, rpcDir, rpcFiles, importName })
-            /* Typed createTestApp `app.rpc.<rpc>` surface. */
-            await writeTestRpcDts({ cwd, rpcFiles, importName })
-            return rpcFiles
-        }),
-    )
-    const scanSocketsOnce = once(() =>
-        scanDir(socketsDir, '**/*.ts').then(async (socketFiles) => {
-            /* Typed createTestApp `app.sockets.<name>` surface. */
-            await writeTestSocketsDts({
-                cwd,
-                socketFiles,
-                importName: await abideImportNameOnce(),
-            })
-            return socketFiles
-        }),
-    )
-    /* One write per build, from the abide:app loader (the seam that already knows whether src/app.ts exists). */
-    let healthDtsWritten: Promise<void> | undefined
-    const writeHealthDtsOnce = (hasAppModule: boolean): Promise<void> => {
-        healthDtsWritten ??= abideImportNameOnce().then((importName) =>
-            writeHealthDts({ cwd, hasAppModule, importName }),
-        )
-        return healthDtsWritten
-    }
+    const scanPagesOnce = once(() => scanPages(pagesDir))
+    const scanRpcOnce = once(() => scanDir(rpcDir, '**/*.ts'))
+    const scanSocketsOnce = once(() => scanDir(socketsDir, '**/*.ts'))
     /*
-    Globs public/ once per build and writes publicAssets.d.ts so url() can
-    autocomplete known assets — independent of embedding (runs in dev/start
-    too, where the files are read off disk). The public-assets virtual reuses
-    the returned list for its embed.
+    Globs public/ once per build; the public-assets virtual reuses the returned
+    list for its embed. (.d.ts codegen — publicAssets.d.ts and its siblings —
+    moved to generateDeclarations, owned by build().)
     */
-    const scanPublicOnce = once(async () => {
-        const publicFiles = existsSync(publicDir)
+    const scanPublicOnce = once(async () =>
+        existsSync(publicDir)
             ? await Array.fromAsync(new Glob('**/*').scan({ cwd: publicDir, onlyFiles: true }))
-            : []
-        await writePublicAssetsDts({ cwd, publicFiles, importName: await abideImportNameOnce() })
-        return publicFiles
-    })
+            : [],
+    )
     const scanPromptsOnce = once(() => scanDir(promptsDir, '**/*.md'))
     const loadShellOnce = once(() => loadShell(cwd))
     /* Project package.json read once per build — three virtuals (cli-name,
@@ -206,53 +177,46 @@ export function abideResolverPlugin({
     const promptsFilter = new RegExp(`^${escapeRegex(promptsDir)}/.*\\.md$`)
 
     /*
-    Side-crossing guard (client target only). The client bundle must never pull a
-    server-only name into the browser. The exception is a registered rpc/socket —
-    `$server/rpc/*` and `$server/sockets/*` are replaced with remoteProxy/socketProxy
-    stubs by the onLoad hooks below — so only OTHER paths under src/server/ (helpers,
-    runtime/) and the public `abide/server/*` names are violations. `importerOf` records
-    each resolved edge so a violation can show the import chain back to its client-side
-    origin as evidence; it is reset per build in onStart.
+    Side-crossing guard (client target only). The client bundle must never ship server-only
+    code to the browser. A registered rpc/socket is the carve-out — `$server/rpc/*` and
+    `$server/sockets/*` are replaced with remoteProxy/socketProxy stubs by the onLoad hooks —
+    so a violation is a SURVIVING module under src/server/ that isn't one of those, or the
+    public `abide/server/*` names.
+
+    ADR-0022 D3 makes the project-server edge REACHABILITY-based rather than
+    presence-at-resolve: the D2 client rpc transform keeps the real module (handler elided),
+    so the elided handler's now-dead `$server/*` / `abide/server/*` imports are textually
+    present until tree-shaking removes them. A resolve-time throw would false-positive on
+    those. So the authority is a post-bundle `build.onEnd` pass that walks `metafile.inputs`
+    (the DCE-accurate graph) and flags any server-only module that SURVIVED. The one guard
+    that still fires at resolve is the public `abide/server/*` names reaching a genuine client
+    module — those live in node_modules, outside `serverDir`, so the metafile classifier can't
+    see them; the kept rpc module (proxied) is exempted so its dead handler imports don't
+    reject before DCE.
     */
-    const importerOf = new Map<string, string>()
+    /* Absolute proxied-server dirs, derived from the shared PROXIED_SERVER_SUBDIRS authority so this
+       resolver and the dev orchestrator's changeAffectsClient classify the same set — adding a
+       proxied dir is one edit there, not a silent lockstep across both. */
+    const proxiedServerDirPrefixes = PROXIED_SERVER_SUBDIRS.map(
+        (subdir) => `${serverDir}/${subdir}/`,
+    )
     const isProxiedServerModule = (path: string): boolean =>
-        path.startsWith(`${rpcDir}/`) || path.startsWith(`${socketsDir}/`)
+        proxiedServerDirPrefixes.some((prefix) => path.startsWith(prefix))
     const isServerOnlyModule = (path: string): boolean =>
         path.startsWith(`${serverDir}/`) && !isProxiedServerModule(path)
     const showPath = (path: string): string =>
         path.startsWith(`${cwd}/`) ? path.slice(cwd.length + 1) : path
-    /* Walks the recorded edges from the offending importer back to a graph root (cycle-safe),
-       formatting each module relative to cwd — the evidence a side-crossing throws. */
-    function sideCrossingChain(leaf: string, importer: string): string {
-        const chain = [leaf, importer]
-        const seen = new Set([importer])
-        let cursor = importer
-        while (importerOf.has(cursor)) {
-            cursor = importerOf.get(cursor) as string
-            if (seen.has(cursor)) {
-                break
-            }
-            seen.add(cursor)
-            chain.push(cursor)
-        }
-        return chain.reverse().map(showPath).join('\n  → ')
-    }
-    function throwSideCrossing(leaf: string, label: string, importer: string): never {
-        throw new Error(
-            `[abide] a client module imports the server-only name \`${label}\` — server code must not reach the browser bundle. Move it to src/shared/ or behind an RPC. Import chain:\n  ${sideCrossingChain(leaf, importer)}`,
-        )
-    }
-    /* Records the edge and, on the client target, rejects a non-server module reaching a
-       server-only one. Shared by the relative-import and `$server` alias resolvers. */
-    function recordAndGuard(resolved: string, label: string, importer: string | undefined): void {
-        if (importer === undefined) {
-            return
-        }
-        importerOf.set(resolved, importer)
-        if (target === 'client' && isServerOnlyModule(resolved) && !isServerOnlyModule(importer)) {
-            throwSideCrossing(resolved, label, importer)
-        }
-    }
+    /* Renders a root→offender absolute-path chain (from the bundle graph seam) as the cwd-relative
+       `a\n  → b\n  → c` evidence the onEnd diagnostics print — the same shape the resolve-time guard
+       gives. */
+    const formatChain = (chain: string[]): string => chain.map(showPath).join('\n  → ')
+
+    /* Warm per-root rpc server program (ADR-0025 D1). Lives in the setup closure so one build
+       reuses a single `ts.Program` across every rpc transform (streaming/method queries);
+       built lazily on the first rpc onLoad (so a build with no rpc modules never pays for it) and
+       failing open to undefined, in which case each query stays on its char-scan/regex. (The
+       rpc.d.ts codegen builds its own program in generateDeclarations, owned by build().) */
+    const rpcServerByRoot = new Map<string, RpcServerProgram | undefined>()
 
     return {
         name: 'abide-resolver',
@@ -264,33 +228,74 @@ export function abideResolverPlugin({
                build, so a freshly-created file resolves instead of staying "not found".
                onStart is build-time only — absent in the runtime/preload plugin context. */
             build.onStart?.(() => {
-                importerOf.clear()
                 resolveExtensionCache.clear()
             })
 
             /*
-            Relative-import edge recorder + side-crossing guard. Matches `./` and `../`
-            specifiers, records the edge for the evidence chain, and (client target) throws
-            when a non-server module reaches a server-only file. Returns undefined so normal
-            resolution proceeds — this only observes and, on violation, aborts.
+            Reachability-based side-crossing guard (client target, ADR-0022 D3). After the
+            bundle is built, `metafile.inputs` is the post-DCE module graph: a textually-imported
+            but tree-shaken module is ABSENT, a surviving one PRESENT. So walk it, flag any
+            server-only module that survived (the elided rpc handler's dead `$server/*` imports
+            are gone by now; a policy or page that LIVE-reaches server-only code is not), and on a
+            hit reconstruct the import chain from the graph's own edges. This is the sole authority
+            for the project-server edge — the resolve-time throw was relaxed so the kept rpc module
+            can carry its handler's imports until DCE. metafile.inputs keys are relative to
+            process.cwd(); edge `path`s are absolute — resolve both to absolute to match serverDir.
             */
-            build.onResolve({ filter: /^\.\.?\// }, (args) => {
-                if (args.importer) {
-                    const resolved = resolveExtension(join(dirname(args.importer), args.path))
-                    recordAndGuard(resolved, args.path, args.importer)
+            build.onEnd?.((result) => {
+                if (target !== 'client' || !result.metafile) {
+                    return
+                }
+                /* The post-DCE graph, walked once (ADR-0031 D2). Both consumers below read it — the
+                   side-crossing guard and the bundle-budget diagnostic — instead of each re-walking
+                   the metafile. */
+                const graph = bundleGraphFromMetafile(result.metafile, process.cwd())
+
+                /* Side-crossing guard (ADR-0022 D3): the FIRST surviving server-only module is a real
+                   violation — throw with its import chain. The sole hard onEnd failure. */
+                const offender = graph.modules.find((module) => isServerOnlyModule(module.path))
+                if (offender !== undefined) {
+                    throw new Error(
+                        `[abide] a client module reaches the server-only name \`${showPath(offender.path)}\` — server code must not reach the browser bundle. Move it to src/shared/ or behind an RPC. Import chain:\n  ${formatChain(graph.importerChain(offender.path))}`,
+                    )
+                }
+
+                /* Bundle-budget diagnostic (ADR-0031 D2), first consumer of the seam: a project src
+                   module that survived DCE heavier than the budget earns a NON-BLOCKING warn with its
+                   import chain — never fails the build. Scoped to files under cwd (excluding
+                   node_modules) so the warning is about code the author owns and can act on. */
+                for (const module of graph.modules) {
+                    if (
+                        module.bytes > CLIENT_BUNDLE_INPUT_BUDGET_BYTES &&
+                        module.path.startsWith(`${cwd}/`) &&
+                        !module.path.includes('/node_modules/')
+                    ) {
+                        abideLog.warn(
+                            `client bundle input \`${showPath(module.path)}\` is ${(module.bytes / 1024).toFixed(1)} KiB (over the ${CLIENT_BUNDLE_INPUT_BUDGET_BYTES / 1024} KiB budget) — consider splitting or lazy-loading it. Import chain:\n  ${formatChain(graph.importerChain(module.path))}`,
+                        )
+                    }
                 }
-                return undefined
             })
 
             /*
-            The public `abide/server/*` names are server-only. Importing one into the client
-            bundle is a side-crossing (the canonical `abide` and `@abide/abide` specifiers; a
-            custom package alias falls through to the relative/`$server` guards). The server
-            target resolves these normally.
+            The public `abide/server/*` names are server-only and live in node_modules — outside
+            `serverDir`, so the onEnd metafile classifier can't see them; this stays the resolve-time
+            guard for them (the canonical `abide` and `@abide/abide` specifiers; a custom package
+            alias falls through to the reachability guard). A genuine client module importing one is a
+            side-crossing. The kept rpc/socket module (proxied) is EXEMPTED: the D2 client transform
+            leaves its elided handler's `abide/server/*` imports textually present until DCE drops
+            them, so rejecting here would false-positive. The server target resolves these normally.
             */
             build.onResolve({ filter: /(^|\/)abide\/server\// }, (args) => {
-                if (target === 'client' && args.importer && !isServerOnlyModule(args.importer)) {
-                    throwSideCrossing(args.path, args.path, args.importer)
+                if (
+                    target === 'client' &&
+                    args.importer &&
+                    !isServerOnlyModule(args.importer) &&
+                    !isProxiedServerModule(args.importer)
+                ) {
+                    throw new Error(
+                        `[abide] a client module imports the server-only name \`${args.path}\` — server code must not reach the browser bundle. Move it to src/shared/ or behind an RPC. Import chain:\n  ${showPath(args.importer)}\n  → ${args.path}`,
+                    )
                 }
                 return undefined
             })
@@ -325,9 +330,10 @@ export function abideResolverPlugin({
                 build.onResolve({ filter: new RegExp(`^\\${alias}(\\/.*)?$`) }, (args) => {
                     const subpath = args.path.slice(alias.length)
                     const resolved = resolveExtension(subpath ? `${baseDir}${subpath}` : baseDir)
-                    /* `$server/rpc/*` + `$server/sockets/*` are proxied (allowed); other
-                       `$server/*` imports into the client bundle are side-crossings. */
-                    recordAndGuard(resolved, args.path, args.importer)
+                    /* No resolve-time side-crossing throw: a `$server/*` import that only the
+                       elided rpc handler reaches is dead code DCE removes. Whether server-only
+                       code actually survives into the client bundle is decided post-bundle by the
+                       onEnd metafile reachability guard (ADR-0022 D3). */
                     return { path: resolved }
                 })
             }
@@ -361,7 +367,50 @@ export function abideResolverPlugin({
                 const source = await Bun.file(args.path).text()
                 const url = rpcUrlForFile(relativePath)
                 const importName = await abideImportNameOnce()
-                const prepared = prepareRpcModule(source, importName)
+                /* Ask the warm server program for this handler's streaming verdict (return-type
+                   query — a stream returned via a wrapper function is seen); undefined when no
+                   program built or the node didn't resolve, so prepareRpcModule falls open to its
+                   char-scan (ADR-0025 D2). */
+                const rpcServerProgram = rpcServerForRoot(rpcServerByRoot, cwd, rpcDir)
+                const streamingOverride = rpcServerProgram?.streamingForModule(args.path)
+                /* The numeric/boolean input fields the server rewrite stamps as a `coerce` plan so
+                   parseArgs turns a string query/form value into the typed value the schema
+                   expects (ADR-0028). undefined (no program / unresolvable Args / no coercible
+                   field) stamps no plan — a GET field stays a string, exactly as today. */
+                const coercion = rpcServerProgram?.inputCoercionForModule(args.path)
+                /* The handler's return type projected to JSON Schema, stamped as `outputJsonSchema` so
+                   the runtime OpenAPI 200 / MCP outputSchema / inspector surface renders the real
+                   response shape without an author-declared `schemas.output` (ADR-0030 D2). undefined
+                   (no program / unprojectable body / an explicit override wins at runtime) stamps
+                   nothing — the surface falls back to today's behavior. */
+                const returnBodySchema = rpcServerProgram?.returnBodySchemaForModule(args.path)
+                /* The handler's typed-error branches projected to a status-keyed JSON-Schema map,
+                   stamped as `errorJsonSchemas` so the runtime OpenAPI surface documents each typed
+                   error's status + data payload alongside the 200 (ADR-0030). undefined (no program /
+                   no typed errors / unresolvable branch) stamps nothing — the surface omits the error
+                   responses exactly as today. */
+                const errorSchemas = rpcServerProgram?.errorSchemasForModule(args.path)
+                /* The handler's structured success fields, baked onto the CLIENT stub as
+                   `outputWirePlan` so the proxy revives a `Set`/`Map`/`bigint`/`Date` off a decoded
+                   response the server encoded to honest JSON (ADR-0029 output path). undefined (no
+                   program / unresolvable body / no structured field) bakes nothing — a response array
+                   stays an array. */
+                const outputWirePlan = rpcServerProgram?.outputWirePlanForModule(args.path)
+                /* The handler's input args projected to JSON Schema, stamped as `inputJsonSchema` so the
+                   runtime OpenAPI parameters/body / MCP inputSchema / inspector input surface renders the
+                   real input shape (and the endpoint becomes advertisable) without an author-declared
+                   `schemas.input` — mirroring the `outputJsonSchema` output-side path (ADR-0030). A
+                   declared `schemas.input` VALIDATOR still overrides it at runtime. undefined (no program
+                   / unresolvable Args / File-only body) stamps nothing — the surface behaves as today. */
+                const inputSchema = rpcServerProgram?.inputSchemaForModule(args.path)
+                const prepared = prepareRpcModule(source, importName, {
+                    streaming: streamingOverride,
+                    coercion,
+                    inputSchema,
+                    outputSchema: returnBodySchema,
+                    errorSchemas,
+                    outputWirePlan,
+                })
                 if (!prepared) {
                     throw new Error(
                         `[abide] src/server/rpc/${relativePath} has no \`export const <name> = <METHOD>(...)\` — every $rpc module must declare exactly one remote function`,
@@ -374,25 +423,22 @@ export function abideResolverPlugin({
                     )
                 }
                 /*
-                For the client bundle, replace the entire module source
-                with a single proxy stub so the handler body and any
-                server-only top-level imports never reach the browser.
-                The stub keeps the same export name the source declared,
-                so page imports resolve identically on both sides.
+                Client bundle: keep the real module but swap the METHOD( call for a remoteProxy(
+                call with the handler ELIDED (ADR-0022 D2), symmetric with the server rewrite
+                below. The handler body and the top-level imports only it used become dead code the
+                bundler tree-shakes out; the endpoint `opts` (schemas/cache/stream) rides through as
+                a LIVE expression, so policy can reference imports and separate modules. The
+                surviving-server-module reachability guard (build.onEnd) is the authority that no
+                server-only code leaks — resolve-time presence of the elided handler's imports is no
+                longer a violation.
                 */
                 if (target === 'client') {
-                    /* Build-time flags on the client proxy stub: `outbox: true` parks
-                       unreachable calls; `streaming: true` (handler returns jsonl()/sse())
-                       makes the bare call return the Subscribable directly. */
-                    const flags = [
-                        prepared.durable ? 'outbox: true' : undefined,
-                        prepared.streaming ? 'streaming: true' : undefined,
-                    ].filter(Boolean)
-                    const optsArg = flags.length > 0 ? `, { ${flags.join(', ')} }` : ''
-                    const contents = `import { remoteProxy as __abideRemoteProxy__ } from '${importName}/ui/remoteProxy';
-export const ${prepared.exportName} = __abideRemoteProxy__(${JSON.stringify(prepared.method)}, ${JSON.stringify(url)}${optsArg});
+                    const banner = `import { remoteProxy as ${REMOTE_PROXY_GLOBAL} } from '${importName}/ui/remoteProxy';
 `
-                    return { contents, loader: 'ts' }
+                    return {
+                        contents: `${banner}${prepared.rewriteForClient(url)}`,
+                        loader: 'ts',
+                    }
                 }
                 /*
                 Server target: strip the user's rpc import, then rewrite
@@ -404,7 +450,7 @@ export const ${prepared.exportName} = __abideRemoteProxy__(${JSON.stringify(prep
                 tokenizer-driven so `GET` mentions inside strings and
                 comments are left alone.
                 */
-                const banner = `import { defineRpc as __abideDefineRpc__ } from '${importName}/server/rpc/defineRpc';
+                const banner = `import { defineRpc as ${DEFINE_RPC_GLOBAL} } from '${importName}/server/rpc/defineRpc';
 `
                 return { contents: `${banner}${prepared.rewriteForServer(url)}`, loader: 'ts' }
             })
@@ -440,7 +486,7 @@ export const ${prepared.exportName} = __abideSocketProxy__(${JSON.stringify(name
 `
                     return { contents, loader: 'ts' }
                 }
-                const banner = `import { defineSocket as __abideDefineSocket__ } from '${importName}/server/sockets/defineSocket';
+                const banner = `import { defineSocket as ${DEFINE_SOCKET_GLOBAL} } from '${importName}/server/sockets/defineSocket';
 `
                 return {
                     contents: `${banner}${prepared.rewriteForServer(name)}`,
@@ -545,8 +591,6 @@ ${optionLines}
                 if (args.path === 'abide:app') {
                     const userApp = `${cwd}/src/app.ts`
                     const hasAppModule = await Bun.file(userApp).exists()
-                    /* health.d.ts keys the client health() read to the app hook's return type. */
-                    await writeHealthDtsOnce(hasAppModule)
                     if (hasAppModule) {
                         abideLog.info('using custom src/app.ts')
                         return {
@@ -882,30 +926,6 @@ ${encoded.map((entry) => entry.line).join('\n')}
 `
 }
 
-type PagesScan = {
-    pageFiles: string[]
-    layoutFiles: string[]
-}
-
-/*
-Walks src/ui/pages once and classifies each `.abide` leaf by filename: a
-`page.abide` is a route (its URL is the folder path), a `layout.abide` is a
-layout that wraps every page at or below its folder (keyed by the same folder
-URL). Any other `.abide` file (a shared component) is ignored here — free to
-live anywhere and be imported relatively.
-*/
-async function scanPages(pagesDir: string): Promise<PagesScan> {
-    if (!existsSync(pagesDir)) {
-        return { pageFiles: [], layoutFiles: [] }
-    }
-    const allFiles = await Array.fromAsync(new Glob('**/*.abide').scan({ cwd: pagesDir }))
-    const leafIs = (name: string) => (file: string) => fileName(file) === name
-    return {
-        pageFiles: allFiles.filter(leafIs('page.abide')),
-        layoutFiles: allFiles.filter(leafIs('layout.abide')),
-    }
-}
-
 /*
 Walks one registry directory once: src/server/rpc (every `.ts` file is an
 HTTP-method rpc handler), src/server/sockets (each `.ts` file declares one
@@ -1005,16 +1025,24 @@ function injectBeforeTag(
 }
 
 /*
-Scans `dist/_app/` for the hashed client entry filenames produced by
-build.ts (e.g. `client-abc12345.js`, `client-abc12345.css`) and swaps the
-shell's literal `/_app/client.js` and `/_app/client.css` references for
-them. The js reference appears twice (the modulepreload <link> and the entry
-<script>), so replaceAll covers both. When the directory is missing (someone
-running the server before a build) the shell is returned unchanged so the
-existing broken-asset behaviour is preserved.
+Scans the client-bundle directory for the hashed client entry filenames produced
+by build.ts (e.g. `client-abc12345.js`, `client-abc12345.css`) and swaps the
+shell's literal `/_app/client.js` and `/_app/client.css` references for them. The
+js reference appears twice (the modulepreload <link> and the entry <script>), so
+replaceAll covers both. When the directory is missing (someone running the server
+before a build) the shell is returned unchanged so the existing broken-asset
+behaviour is preserved.
+
+The directory is `dist/_app` for a production build, but under `abide dev` the
+orchestrator serves each build generation from its own `_app.gen-<id>` dir and
+passes it as `ABIDE_APP_DIR` (this runs in the worker, which resolves `abide:shell`
+at boot). Reading that env keeps the shell's entry ref, the preload manifest, and
+the asset server all pointed at the one generation this worker owns — never a
+sibling generation a concurrent worker is serving. Each generation dir holds
+exactly one entry, so `.find` is unambiguous.
 */
 async function rewriteHashedClientEntries(shell: string, cwd: string): Promise<string> {
-    const appDir = `${cwd}/dist/_app`
+    const appDir = process.env.ABIDE_APP_DIR ?? `${cwd}/dist/_app`
     if (!existsSync(appDir)) {
         return shell
     }