@hops-ops/distributed 4.8.0 → 4.10.0

package/dist/sveltekit/vite.js

@@ -1,12 +1,20 @@
 import { spawn } from 'node:child_process';
-import { existsSync, lstatSync, realpathSync } from 'node:fs';
-import { cp, lstat, mkdir, mkdtemp, open, readFile, realpath, rename, rm, unlink, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, unlink, writeFile } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { isMainThread } from 'node:worker_threads';
+import { analyzeDistributedSvelteKitBoundaries, validateDistributedSvelteKitBoundaryPlan } from './islands/boundaries.js';
+export { analyzeDistributedSvelteKitBoundaries, validateDistributedSvelteKitBoundaryPlan } from './islands/boundaries.js';
 const GENERATED_SVELTEKIT_MODULE = 'sveltekit.ts';
+const GENERATED_BOUNDARIES_MODULE = 'boundaries.ts';
 const MAX_COMMAND_OUTPUT_BYTES = 16 * 1024 * 1024;
+const MAX_GENERATED_COMPARE_FILES = 20_000;
+const MAX_GENERATED_COMPARE_BYTES = 128 * 1024 * 1024;
 const MODULE_NAME = /^\$distributed(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/;
 const COMPILER_LOCK = join('.svelte-kit', 'distributed', 'compiler.lock');
+const GENERATION_META = 'distributed-generation';
+const MAX_LIFECYCLE_STATE_BYTES = 1024 * 1024;
 const COMPILER_COORDINATORS = Symbol.for('@hops-ops/distributed/sveltekit/compiler-coordinators/v1');
 /** Vite proxy config for GraphQL HTTP and WebSocket traffic. */
 export function distributedGraphqlProxy(options) {
@@ -22,6 +30,22 @@ export function distributedGraphqlProxy(options) {
     }
     return { [path]: { target, changeOrigin: true, ws: true } };
 }
+/** Lifecycle-only side channel for projects using committed generated clients. */
+export function distributedLifecycle() {
+    let frameworkDist;
+    return {
+        name: '@hops-ops/distributed:lifecycle',
+        enforce: 'pre',
+        configResolved(config) {
+            frameworkDist = localFrameworkDist(config.root);
+        },
+        configureServer: configureLifecycleServer,
+        transformIndexHtml: lifecycleGenerationMeta,
+        handleHotUpdate(context) {
+            return suppressFrameworkHotUpdate(context, frameworkDist);
+        }
+    };
+}
 /** Generate every configured surface through the same transaction used by Vite. */
 export async function generateDistributedSvelteKit(options) {
     await runCompilerOnce(options, 'generate');
@@ -38,12 +62,14 @@ export async function checkDistributedSvelteKit(options) {
  * coalesced, abortable, and always invoked without a shell.
  */
 export function distributedSvelteKit(options) {
+    const lifecycleOwnsCompile = process.env.DISTRIBUTED_LIFECYCLE_DIR !== undefined;
     let resolved;
     let dirty = false;
     let running;
     let completedGeneration = 0;
     let reloadedGeneration = 0;
     let stopped = false;
+    let frameworkDist;
     const children = new Set();
     const cancellation = new AbortController();
     let lock;
@@ -106,7 +132,17 @@ export function distributedSvelteKit(options) {
                 throw new Error('Distributed SvelteKit Vite plugin was configured more than once');
             }
             resolved = resolveIntegration(options, options.cwd ?? config.root);
+            frameworkDist = localFrameworkDist(config.root);
             await validateResolvedPaths(resolved);
+            /*
+             * `distributed dev` has already staged this generation and owns every
+             * compiler input through its application watcher. Recompiling here would
+             * race the API process for Cargo and mutate generated output outside the
+             * lifecycle transaction. The virtual modules still resolve the staged
+             * files, while compiler inputs below are held for the supervisor reload.
+             */
+            if (lifecycleOwnsCompile)
+                return;
             /*
              * SvelteKit post-build analysis loads Vite config in an isolated
              * worker marked with SVELTEKIT_FORK. That pass reads framework
@@ -126,18 +162,32 @@ export function distributedSvelteKit(options) {
             }
         },
         configureServer(server) {
+            configureLifecycleServer(server);
             const integration = requireResolved(resolved);
-            const roots = integration.clients.flatMap((client) => client.watchRoots);
-            if (roots.length > 0)
-                server.watcher.add(roots);
+            if (!lifecycleOwnsCompile) {
+                const roots = [
+                    integration.routesDir,
+                    integration.libDir,
+                    ...integration.clients.flatMap((client) => [
+                        ...client.watchRoots,
+                        ...client.manifestWatchRoots
+                    ])
+                ];
+                if (roots.length > 0)
+                    server.watcher.add(roots);
+            }
             server.httpServer?.once('close', () => {
                 void stop();
             });
         },
         buildStart() {
             const integration = requireResolved(resolved);
+            if (lifecycleOwnsCompile)
+                return;
+            this.addWatchFile(integration.routesDir);
+            this.addWatchFile(integration.libDir);
             for (const client of integration.clients) {
-                for (const root of client.watchRoots)
+                for (const root of [...client.watchRoots, ...client.manifestWatchRoots])
                     this.addWatchFile(root);
             }
         },
@@ -151,12 +201,18 @@ export function distributedSvelteKit(options) {
                 return undefined;
             return `export * from ${JSON.stringify(portablePath(client.entry))};\n`;
         },
+        transformIndexHtml: lifecycleGenerationMeta,
         async handleHotUpdate(context) {
+            const suppressed = suppressFrameworkHotUpdate(context, frameworkDist);
+            if (suppressed !== undefined)
+                return suppressed;
             const integration = requireResolved(resolved);
-            if (!isGraphqlInput(context.file, integration))
+            if (!isCompilerInput(context.file, integration))
                 return undefined;
+            if (lifecycleOwnsCompile)
+                return [];
             try {
-                await compile(`GraphQL change ${context.file}`);
+                await compile(`GraphQL/Svelte change ${context.file}`);
             }
             catch (error) {
                 context.server.ws.send({
@@ -173,19 +229,220 @@ export function distributedSvelteKit(options) {
                     context.server.moduleGraph.invalidateModule(module);
                 }
             }
-            context.server.ws.send({ type: 'full-reload', path: '*' });
+            if (process.env.DISTRIBUTED_LIFECYCLE_DIR === undefined) {
+                context.server.ws.send({ type: 'full-reload', path: '*' });
+            }
             reloadedGeneration = completedGeneration;
             return [];
         },
         async watchChange(id) {
             const integration = requireResolved(resolved);
-            if (isGraphqlInput(id, integration)) {
-                await compile(`GraphQL watch change ${id}`);
+            if (lifecycleOwnsCompile)
+                return;
+            if (isCompilerInput(id, integration)) {
+                await compile(`GraphQL/Svelte watch change ${id}`);
             }
         },
         closeBundle: stop
     };
 }
+function localFrameworkDist(root) {
+    try {
+        const candidate = join(root, 'node_modules', '@hops-ops', 'distributed', 'dist');
+        return existsSync(candidate) ? realpathSync(candidate) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function suppressFrameworkHotUpdate(context, frameworkDist) {
+    if (process.env.DISTRIBUTED_LIFECYCLE_DIR === undefined ||
+        frameworkDist === undefined ||
+        !isWithin(frameworkDist, canonicalExistingPath(context.file)))
+        return undefined;
+    for (const module of context.modules ?? []) {
+        context.server.moduleGraph.invalidateModule(module);
+    }
+    return [];
+}
+function canonicalExistingPath(value) {
+    try {
+        return realpathSync(value);
+    }
+    catch {
+        return resolve(value);
+    }
+}
+const CONTROL_ID = /^[A-Za-z0-9_:-]{16,128}$/;
+const MAX_ACK_BYTES = 4096;
+function lifecycleGenerationMeta() {
+    const configured = process.env.DISTRIBUTED_LIFECYCLE_DIR;
+    if (configured === undefined || !isAbsolute(configured))
+        return [];
+    try {
+        const encoded = readFileSync(join(resolve(configured), 'dev.json'));
+        if (encoded.byteLength > MAX_LIFECYCLE_STATE_BYTES)
+            return [];
+        const state = JSON.parse(encoded.toString('utf8'));
+        const generationId = state.active?.generationId;
+        if (typeof generationId !== 'string' ||
+            generationId.length === 0 ||
+            generationId.length > 512 ||
+            generationId !== generationId.trim() ||
+            /[\u0000-\u001f\u007f]/.test(generationId))
+            return [];
+        return [Object.freeze({
+                tag: 'meta',
+                attrs: Object.freeze({ name: GENERATION_META, content: generationId }),
+                injectTo: 'head-prepend'
+            })];
+    }
+    catch {
+        // A lifecycle file is atomically replaced. Missing or malformed state
+        // simply omits the hint; the browser falls back to its first poll.
+        return [];
+    }
+}
+function configureLifecycleServer(server) {
+    const configured = process.env.DISTRIBUTED_LIFECYCLE_DIR;
+    if (configured === undefined || !isAbsolute(configured))
+        return;
+    const lifecycleRoot = resolve(configured);
+    server.middlewares?.use('/__distributed/lifecycle', (request, response) => {
+        void handleLifecycleRequest(lifecycleRoot, request, response).catch(() => {
+            if (response.statusCode < 400)
+                response.statusCode = 500;
+            response.end();
+        });
+    });
+}
+async function handleLifecycleRequest(lifecycleRoot, request, response) {
+    response.setHeader('cache-control', 'no-store');
+    if (request.method === 'GET') {
+        const participant = singleHeader(request.headers['x-distributed-participant']);
+        if (participant !== undefined && CONTROL_ID.test(participant)) {
+            await writeParticipantHeartbeat(lifecycleRoot, participant).catch(() => undefined);
+        }
+        const state = await readLifecycleState(lifecycleRoot);
+        if (state === undefined) {
+            response.statusCode = 404;
+            response.end();
+            return;
+        }
+        response.statusCode = 200;
+        response.setHeader('content-type', 'application/json');
+        response.end(state);
+        return;
+    }
+    if (request.method === 'POST') {
+        const contentType = singleHeader(request.headers['content-type']);
+        if (contentType?.split(';', 1)[0]?.trim().toLowerCase() !== 'application/json') {
+            response.statusCode = 415;
+            response.end();
+            return;
+        }
+        if (!sameOriginLifecycleRequest(request)) {
+            response.statusCode = 403;
+            response.end();
+            return;
+        }
+        const body = JSON.parse(await readRequestBody(request, MAX_ACK_BYTES));
+        if (!CONTROL_ID.test(String(body.transitionId ?? '')) ||
+            !CONTROL_ID.test(String(body.participantId ?? '')) ||
+            typeof body.ok !== 'boolean') {
+            response.statusCode = 400;
+            response.end();
+            return;
+        }
+        const stateSource = await readLifecycleState(lifecycleRoot);
+        const state = stateSource === undefined ? undefined : JSON.parse(stateSource);
+        if (state?.phase !== 'preparing' || state.transitionId !== body.transitionId) {
+            response.statusCode = 409;
+            response.end();
+            return;
+        }
+        await writeControlJson(join(lifecycleRoot, 'dev-control', 'acks', String(body.transitionId)), `${String(body.participantId)}.json`, { ok: body.ok });
+        response.statusCode = 204;
+        response.end();
+        return;
+    }
+    response.statusCode = 405;
+    response.end();
+}
+function writeParticipantHeartbeat(root, participant) {
+    return writeControlJson(join(root, 'dev-control', 'participants'), `${participant}.json`, { seenAtUnixMs: Date.now() });
+}
+async function readLifecycleState(root) {
+    const path = join(root, 'dev.json');
+    let metadata;
+    try {
+        metadata = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    if (metadata.isSymbolicLink() || !metadata.isFile() || metadata.size > MAX_LIFECYCLE_STATE_BYTES) {
+        throw new Error('invalid Distributed lifecycle state file');
+    }
+    return readFile(path, 'utf8');
+}
+async function writeControlJson(directory, name, value) {
+    await mkdir(directory, { recursive: true });
+    const temporary = join(directory, `.${name}.${process.pid}.${Date.now()}.${randomUUID()}`);
+    await writeFile(temporary, `${JSON.stringify(value)}\n`, { flag: 'wx', mode: 0o600 });
+    await rename(temporary, join(directory, name));
+}
+function sameOriginLifecycleRequest(request) {
+    const origin = singleHeader(request.headers.origin);
+    const host = singleHeader(request.headers.host);
+    if (origin === undefined || host === undefined)
+        return false;
+    try {
+        const parsed = new URL(origin);
+        const forwarded = singleHeader(request.headers['x-forwarded-proto']);
+        const socket = request.socket;
+        const protocol = forwarded === 'http' || forwarded === 'https'
+            ? `${forwarded}:`
+            : socket?.encrypted === true
+                ? 'https:'
+                : 'http:';
+        return (parsed.protocol === protocol &&
+            parsed.host === host &&
+            parsed.origin === origin);
+    }
+    catch {
+        return false;
+    }
+}
+function singleHeader(value) {
+    return typeof value === 'string' ? value : value?.[0];
+}
+function readRequestBody(request, maximum) {
+    return new Promise((resolvePromise, reject) => {
+        const chunks = [];
+        let bytes = 0;
+        let exceeded = false;
+        request.on('data', (chunk) => {
+            if (exceeded)
+                return;
+            bytes += chunk.byteLength;
+            if (bytes > maximum) {
+                exceeded = true;
+                chunks.length = 0;
+                reject(new Error('lifecycle acknowledgement exceeds bound'));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        request.on('error', reject);
+        request.on('end', () => {
+            if (!exceeded)
+                resolvePromise(Buffer.concat(chunks).toString('utf8'));
+        });
+    });
+}
 async function runCompilerOnce(options, mode) {
     const integration = resolveIntegration(options, options.cwd ?? process.cwd());
     await validateResolvedPaths(integration);
@@ -240,6 +497,14 @@ function resolveIntegration(options, fallbackCwd) {
     }
     const modules = new Set();
     const outputs = [];
+    const routesDir = containedPath(cwd, options.routesDir ?? 'src/routes', 'routesDir');
+    const libDir = containedPath(cwd, options.libDir ?? 'src/lib', 'libDir');
+    const aliases = Object.freeze(Object.fromEntries(Object.entries(options.aliases ?? {}).map(([key, value]) => {
+        if (!/^\$[A-Za-z0-9_-]+$/.test(key)) {
+            throw new TypeError(`Distributed SvelteKit alias \`${key}\` must be a single $name segment`);
+        }
+        return [key, portablePath(relative(cwd, containedPath(cwd, value, `alias ${key}`)))];
+    })));
     const clients = options.clients.map((client, index) => {
         if (client === null || typeof client !== 'object') {
             throw new TypeError(`Distributed client[${index}] must be an object`);
@@ -267,7 +532,21 @@ function resolveIntegration(options, fallbackCwd) {
             throw new TypeError(`Distributed client \`${client.module}\` requires at least one GraphQL document glob`);
         }
         const documents = client.documents.map((document, documentIndex) => nonempty(document, `${client.module} documents[${documentIndex}]`));
-        const routes = (client.routes ?? []).map((route, routeIndex) => nonempty(route, `${client.module} routes[${routeIndex}]`));
+        const boundaries = (client.boundaries ?? []).map((boundary, boundaryIndex) => {
+            if (boundary === null ||
+                typeof boundary !== 'object' ||
+                (boundary.kind !== 'page' && boundary.kind !== 'layout')) {
+                throw new TypeError(`${client.module} boundaries[${boundaryIndex}] is invalid`);
+            }
+            return Object.freeze({
+                operation: nonempty(boundary.operation, `${client.module} boundaries[${boundaryIndex}].operation`),
+                route: nonempty(boundary.route, `${client.module} boundaries[${boundaryIndex}].route`),
+                kind: boundary.kind,
+                ...(boundary.variables === undefined
+                    ? {}
+                    : { variables: boundary.variables })
+            });
+        });
         validateManifestSource(client.module, client.manifest);
         const out = containedPath(cwd, client.out, `${client.module} generated output`);
         if (out === cwd) {
@@ -279,15 +558,18 @@ function resolveIntegration(options, fallbackCwd) {
             }
         }
         outputs.push(out);
+        const adapterOut = join(cwd, '.svelte-kit', 'distributed', 'clients', Buffer.from(client.module).toString('base64url'));
         return Object.freeze({
             module: client.module,
             manifest: client.manifest,
             selector,
             documents: Object.freeze(documents),
-            routes: Object.freeze(routes),
+            boundaries: Object.freeze(boundaries),
             out,
             entry: join(out, GENERATED_SVELTEKIT_MODULE),
-            watchRoots: Object.freeze(documentWatchRoots(cwd, documents, out))
+            adapterOut,
+            watchRoots: Object.freeze(documentWatchRoots(cwd, documents, out)),
+            manifestWatchRoots: Object.freeze(manifestWatchRoots(cwd, client.manifest))
         });
     });
     return Object.freeze({
@@ -299,6 +581,9 @@ function resolveIntegration(options, fallbackCwd) {
             }
             return argument;
         })),
+        routesDir,
+        libDir,
+        aliases,
         clients: Object.freeze(clients)
     });
 }
@@ -352,8 +637,39 @@ function documentWatchRoots(cwd, documents, out) {
     }
     return [...roots].sort();
 }
+function manifestWatchRoots(cwd, manifest) {
+    const manifestPath = typeof manifest === 'string'
+        ? resolve(cwd, manifest)
+        : (() => {
+            const index = manifest.args.indexOf('--manifest-path');
+            return index === -1 || manifest.args[index + 1] === undefined
+                ? undefined
+                : resolve(cwd, manifest.args[index + 1]);
+        })();
+    if (manifestPath === undefined)
+        return [];
+    const root = dirname(manifestPath);
+    return [manifestPath, join(root, 'src'), join(root, 'crates')]
+        .filter((candidate) => existsSync(candidate))
+        .sort();
+}
+function isCompilerInput(file, integration) {
+    if (isGraphqlInput(file, integration))
+        return true;
+    const absolute = resolve(integration.cwd, file);
+    const basenameValue = basename(absolute);
+    if (!absolute.endsWith('.rs') && basenameValue !== 'Cargo.toml' && basenameValue !== 'Cargo.lock') {
+        return false;
+    }
+    return integration.clients.some((client) => client.manifestWatchRoots.some((root) => isWithin(root, absolute)));
+}
 function isGraphqlInput(file, integration) {
     const absolute = resolve(integration.cwd, file);
+    if (absolute.endsWith('.svelte') &&
+        (isWithin(integration.routesDir, absolute) ||
+            isWithin(integration.libDir, absolute))) {
+        return true;
+    }
     if ((!absolute.endsWith('.graphql') && !absolute.endsWith('.gql')) ||
         !isWithin(integration.cwd, absolute)) {
         return false;
@@ -366,7 +682,8 @@ function isGraphqlInput(file, integration) {
 async function compileTransaction(integration, children, signal) {
     throwIfAborted(signal);
     await validateResolvedPaths(integration);
-    const transaction = await mkdtemp(join(integration.cwd, '.distributed-sveltekit-'));
+    const transactionRoot = await compilerTransactionRoot(integration);
+    const transaction = await mkdtemp(join(transactionRoot, '.distributed-sveltekit-'));
     const staged = [];
     try {
         for (const [index, client] of integration.clients.entries()) {
@@ -380,17 +697,12 @@ async function compileTransaction(integration, children, signal) {
                     throw new Error(`generated output ${client.out} must be a real directory`);
                 }
                 hadOutput = true;
-                await cp(client.out, output, {
-                    recursive: true,
-                    errorOnExist: true,
-                    force: false,
-                    dereference: false
-                });
             }
             catch (error) {
                 if (!isMissing(error))
                     throw error;
             }
+            await mkdir(output, { recursive: true });
             const args = [
                 'client',
                 '--manifest',
@@ -401,19 +713,33 @@ async function compileTransaction(integration, children, signal) {
                     '--documents',
                     document
                 ]),
-                ...client.routes.flatMap((route) => ['--route', route]),
                 '--out',
                 output
             ];
             await runCommand(integration, args, children, signal);
-            await validateGeneratedEntrypoint(integration.cwd, output, client.module);
+            await validateGeneratedEntrypoint(transaction, output, client.module);
             staged.push({
                 client,
                 output,
                 backup: join(transaction, `backup-${index}`),
-                hadOutput
+                hadOutput,
+                adapterOutput: join(transaction, `adapter-${index}`),
+                adapterBackup: join(transaction, `adapter-backup-${index}`),
+                hadAdapterOutput: await realDirectoryExists(client.adapterOut)
             });
         }
+        const plans = await analyzeStagedBoundaries(integration, staged);
+        const plansByModule = new Map(plans.map((plan) => [plan.module, plan]));
+        for (const item of staged) {
+            const plan = plansByModule.get(item.client.module);
+            if (plan === undefined) {
+                throw new Error(`Distributed SvelteKit boundary analysis returned no plan for ${item.client.module}`);
+            }
+            await writeFile(join(item.output, GENERATED_BOUNDARIES_MODULE), boundaryModuleSource(plan), { encoding: 'utf8', flag: 'wx' });
+            await exposeBoundaryModule(item.output);
+            await mkdir(item.adapterOutput, { recursive: true });
+            await writeFile(join(item.adapterOutput, 'boundaries.json'), boundaryPlanSource(plan), { encoding: 'utf8', flag: 'wx' });
+        }
         throwIfAborted(signal);
         await commitOutputs(integration, staged, signal);
     }
@@ -424,14 +750,17 @@ async function compileTransaction(integration, children, signal) {
 async function checkTransaction(integration, children, signal) {
     throwIfAborted(signal);
     await validateResolvedPaths(integration);
-    const transaction = await mkdtemp(join(integration.cwd, '.distributed-sveltekit-check-'));
+    const transactionRoot = await compilerTransactionRoot(integration);
+    const transaction = await mkdtemp(join(transactionRoot, '.distributed-sveltekit-check-'));
     try {
+        const staged = [];
         for (const [index, client] of integration.clients.entries()) {
             throwIfAborted(signal);
             const manifest = await materializeManifest(integration, client, transaction, index, children, signal);
+            const output = join(transaction, `output-${index}`);
+            await mkdir(output, { recursive: true });
             await runCommand(integration, [
                 'client',
-                '--check',
                 '--manifest',
                 manifest,
                 client.selector[0],
@@ -440,16 +769,227 @@ async function checkTransaction(integration, children, signal) {
                     '--documents',
                     document
                 ]),
-                ...client.routes.flatMap((route) => ['--route', route]),
                 '--out',
-                client.out
+                output
             ], children, signal);
+            await validateGeneratedEntrypoint(integration.cwd, output, client.module);
+            staged.push(Object.freeze({ client, output }));
+        }
+        const plans = await analyzeStagedBoundaries(integration, staged);
+        const plansByModule = new Map(plans.map((plan) => [plan.module, plan]));
+        for (const [index, client] of integration.clients.entries()) {
+            const output = staged[index].output;
+            const plan = plansByModule.get(client.module);
+            if (plan === undefined) {
+                throw new Error(`Distributed SvelteKit boundary analysis returned no plan for ${client.module}`);
+            }
+            await writeFile(join(output, GENERATED_BOUNDARIES_MODULE), boundaryModuleSource(plan), { encoding: 'utf8', flag: 'wx' });
+            await exposeBoundaryModule(output);
+            await compareGeneratedTrees(client.out, output, client.module);
+            await validateAdapterBoundaryPlan(client, plan);
         }
     }
     finally {
         await rm(transaction, { recursive: true, force: true });
     }
 }
+async function compilerTransactionRoot(integration) {
+    const lifecycle = process.env.DISTRIBUTED_LIFECYCLE_DIR;
+    const root = lifecycle !== undefined && isAbsolute(lifecycle)
+        ? resolve(lifecycle)
+        : integration.cwd;
+    await mkdir(root, { recursive: true });
+    return root;
+}
+async function validateAdapterBoundaryPlan(client, plan) {
+    let actual;
+    try {
+        actual = await readFile(join(client.adapterOut, 'boundaries.json'), 'utf8');
+    }
+    catch (error) {
+        /*
+         * `.svelte-kit` is SvelteKit-owned build state. A production build may
+         * replace it after our Vite startup generation, while the durable client
+         * tree (including boundaries.ts) remains current and was checked above.
+         */
+        if (isMissing(error))
+            return;
+        throw error;
+    }
+    let persisted;
+    try {
+        persisted = JSON.parse(actual);
+    }
+    catch {
+        throw new Error(`[distributed.island.boundary_plan_invalid] ${client.module} boundaries.json is not valid JSON`);
+    }
+    validateDistributedSvelteKitBoundaryPlan(persisted, client.module);
+    const expected = boundaryPlanSource(plan);
+    if (actual !== expected) {
+        throw new Error(`Distributed SvelteKit boundary plan for ${client.module} is stale; run generation without check`);
+    }
+}
+async function analyzeStagedBoundaries(integration, staged) {
+    return await analyzeDistributedSvelteKitBoundaries({
+        cwd: integration.cwd,
+        routesDir: portablePath(relative(integration.cwd, integration.routesDir)),
+        libDir: portablePath(relative(integration.cwd, integration.libDir)),
+        aliases: integration.aliases,
+        clients: await Promise.all(staged.map(async ({ client, output }) => ({
+            module: client.module,
+            inventory: await readIslandInventory(integration.cwd, output),
+            explicitBoundaries: client.boundaries
+        })))
+    });
+}
+async function readIslandInventory(cwd, output) {
+    const path = join(output, 'islands.json');
+    const metadata = await lstat(path);
+    if (metadata.isSymbolicLink() || !metadata.isFile()) {
+        throw new Error(`Distributed island inventory ${portablePath(relative(cwd, path))} must be a regular file`);
+    }
+    const canonicalRoot = await realpath(cwd);
+    const canonical = await realpath(path);
+    if (!isWithin(canonicalRoot, canonical)) {
+        throw new Error('Distributed island inventory escaped the project root');
+    }
+    return JSON.parse(await readFile(canonical, 'utf8'));
+}
+function boundaryPlanSource(plan) {
+    return `${JSON.stringify(plan, null, 2)}\n`;
+}
+function boundaryModuleSource(plan) {
+    validateDistributedSvelteKitBoundaryPlan(plan, plan.module);
+    const occurrences = plan.boundaries.flatMap((boundary) => boundary.islands.map((island) => ({ boundary, island })));
+    const artifacts = new Map();
+    for (const { island } of occurrences) {
+        if (!/^operations\/[A-Za-z0-9._-]+\.ts$/.test(island.modulePath) ||
+            !/^[_A-Za-z][_0-9A-Za-z]*$/.test(island.exportName)) {
+            throw new Error(`[distributed.island.boundary_plan_invalid] ${island.graphqlSource} has an unsafe generated artifact reference`);
+        }
+        const key = `${island.modulePath}\u0000${island.exportName}`;
+        if (!artifacts.has(key)) {
+            artifacts.set(key, Object.freeze({
+                alias: `DistributedBoundaryArtifact_${artifacts.size}`,
+                module: island.modulePath.slice(0, -3),
+                exportName: island.exportName
+            }));
+        }
+    }
+    const imports = [...artifacts.values()].map(({ alias, module, exportName }) => `import { ${exportName} as ${alias} } from './${module}.js';`);
+    const definitions = occurrences.map(({ boundary, island }, index) => {
+        const artifact = artifacts.get(`${island.modulePath}\u0000${island.exportName}`);
+        const discovery = island.reason === 'static_component_import' ? 'component' : island.reason;
+        return [
+            `const DistributedBoundaryBinding_${index} = defineDistributedBoundaryBinding(`,
+            `  ${artifact.alias},`,
+            `  ${JSON.stringify(island.binding.sources, null, 2)} as const`,
+            `);`,
+            `const DistributedBoundaryOperation_${index} = defineDistributedBoundaryOperation(`,
+            `  ${JSON.stringify({
+                operation: island.operation,
+                route: boundary.route,
+                kind: boundary.kind,
+                sourcePath: island.graphqlSource,
+                discovery
+            }, null, 2)} as const,`,
+            `  ${artifact.alias},`,
+            `  DistributedBoundaryBinding_${index}`,
+            `);`
+        ].join('\n');
+    });
+    const operations = occurrences.map((_, index) => `  DistributedBoundaryOperation_${index}`);
+    return [
+        '/** GENERATED by the Distributed SvelteKit boundary planner. Do not edit. */',
+        "import { defineDistributedBoundaryBinding, defineDistributedBoundaryOperation } from '@hops-ops/distributed/sveltekit';",
+        ...imports,
+        '',
+        `export const DISTRIBUTED_BOUNDARY_PLAN = ${JSON.stringify(plan, null, 2)} as const;`,
+        '',
+        ...definitions,
+        '',
+        '/** Executable SSR/browser ownership assembled from the same boundary plan. */',
+        `export const DISTRIBUTED_BOUNDARY_OPERATIONS = ${operations.length === 0 ? '[]' : `[\n${operations.join(',\n')}\n]`} as const;`,
+        ''
+    ].join('\n');
+}
+async function exposeBoundaryModule(output) {
+    const path = join(output, GENERATED_SVELTEKIT_MODULE);
+    const source = await readFile(path, 'utf8');
+    if (!source.startsWith('/** GENERATED by distributed client. Do not edit. */')) {
+        throw new Error('generated SvelteKit entrypoint is missing its ownership marker');
+    }
+    await writeFile(path, `${source.trimEnd()}\n\nexport { DISTRIBUTED_BOUNDARY_OPERATIONS, DISTRIBUTED_BOUNDARY_PLAN } from './boundaries.js';\n`, 'utf8');
+}
+async function compareGeneratedTrees(actualRoot, expectedRoot, module) {
+    const [actual, expected] = await Promise.all([
+        readGeneratedTree(actualRoot),
+        readGeneratedTree(expectedRoot)
+    ]);
+    const drift = [];
+    for (const [path, contents] of expected) {
+        const current = actual.get(path);
+        if (current === undefined)
+            drift.push(`missing ${path}`);
+        else if (current !== contents)
+            drift.push(`changed ${path}`);
+    }
+    for (const path of actual.keys()) {
+        if (!expected.has(path))
+            drift.push(`unexpected ${path}`);
+    }
+    if (drift.length > 0) {
+        throw new Error(`Distributed SvelteKit client ${module} is stale:\n  ${drift.sort().join('\n  ')}\nrun generation without check`);
+    }
+}
+async function readGeneratedTree(root) {
+    const rootMetadata = await lstat(root);
+    if (rootMetadata.isSymbolicLink() || !rootMetadata.isDirectory()) {
+        throw new Error(`generated output ${root} must be a real directory`);
+    }
+    const files = new Map();
+    const pending = [
+        { absolute: root, relative: '' }
+    ];
+    while (pending.length > 0) {
+        const directory = pending.pop();
+        for (const entry of await readdir(directory.absolute, { withFileTypes: true })) {
+            const relativePath = directory.relative.length === 0
+                ? entry.name
+                : `${directory.relative}/${entry.name}`;
+            const absolutePath = join(directory.absolute, entry.name);
+            if (entry.isSymbolicLink()) {
+                throw new Error(`generated output contains unsupported symlink ${relativePath}`);
+            }
+            if (entry.isDirectory()) {
+                pending.push({ absolute: absolutePath, relative: relativePath });
+                continue;
+            }
+            if (!entry.isFile()) {
+                throw new Error(`generated output contains unsupported entry ${relativePath}`);
+            }
+            files.set(relativePath, await readFile(absolutePath, 'utf8'));
+            if (files.size > 8_192) {
+                throw new Error('generated output exceeds 8192 files');
+            }
+        }
+    }
+    return files;
+}
+async function realDirectoryExists(path) {
+    try {
+        const metadata = await lstat(path);
+        if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+            throw new Error(`Distributed SvelteKit adapter output ${path} must be a real directory`);
+        }
+        return true;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+}
 async function materializeManifest(integration, client, transaction, index, children, signal) {
     throwIfAborted(signal);
     if (typeof client.manifest === 'string') {
@@ -493,20 +1033,37 @@ async function validateGeneratedEntrypoint(cwd, output, module) {
 async function commitOutputs(integration, staged, signal) {
     throwIfAborted(signal);
     await validateResolvedPaths(integration);
+    const outputs = staged.flatMap((item) => [
+        {
+            target: item.client.out,
+            output: item.output,
+            backup: item.backup,
+            hadOutput: item.hadOutput
+        },
+        {
+            target: item.client.adapterOut,
+            output: item.adapterOutput,
+            backup: item.adapterBackup,
+            hadOutput: item.hadAdapterOutput
+        }
+    ]);
     const applied = [];
     try {
-        for (const item of staged) {
+        for (const item of outputs) {
             throwIfAborted(signal);
-            await mkdir(dirname(item.client.out), { recursive: true });
-            await validateNearestExistingParent(integration.cwd, item.client.out);
+            await mkdir(dirname(item.target), { recursive: true });
+            await validateNearestExistingParent(integration.cwd, item.target);
+            if (item.hadOutput && await generatedTreesEqual(item.target, item.output)) {
+                continue;
+            }
             if (item.hadOutput)
-                await rename(item.client.out, item.backup);
+                await rename(item.target, item.backup);
             try {
-                await rename(item.output, item.client.out);
+                await rename(item.output, item.target);
             }
             catch (error) {
                 if (item.hadOutput)
-                    await rename(item.backup, item.client.out);
+                    await rename(item.backup, item.target);
                 throw error;
             }
             applied.push(item);
@@ -515,13 +1072,63 @@ async function commitOutputs(integration, staged, signal) {
     }
     catch (error) {
         for (const item of [...applied].reverse()) {
-            await rm(item.client.out, { recursive: true, force: true });
+            await rm(item.target, { recursive: true, force: true });
             if (item.hadOutput)
-                await rename(item.backup, item.client.out);
+                await rename(item.backup, item.target);
         }
         throw error;
     }
 }
+async function generatedTreesEqual(left, right) {
+    const budget = { files: 0, bytes: 0 };
+    const compare = async (leftDirectory, rightDirectory) => {
+        const [leftEntries, rightEntries] = await Promise.all([
+            readdir(leftDirectory, { withFileTypes: true }),
+            readdir(rightDirectory, { withFileTypes: true })
+        ]);
+        leftEntries.sort((a, b) => a.name.localeCompare(b.name));
+        rightEntries.sort((a, b) => a.name.localeCompare(b.name));
+        if (leftEntries.length !== rightEntries.length)
+            return false;
+        for (let index = 0; index < leftEntries.length; index += 1) {
+            const leftEntry = leftEntries[index];
+            const rightEntry = rightEntries[index];
+            if (leftEntry.name !== rightEntry.name ||
+                leftEntry.isDirectory() !== rightEntry.isDirectory() ||
+                leftEntry.isFile() !== rightEntry.isFile())
+                return false;
+            if (!leftEntry.isDirectory() && !leftEntry.isFile())
+                return false;
+            const leftPath = join(leftDirectory, leftEntry.name);
+            const rightPath = join(rightDirectory, rightEntry.name);
+            if (leftEntry.isDirectory()) {
+                if (!await compare(leftPath, rightPath))
+                    return false;
+                continue;
+            }
+            budget.files += 1;
+            if (budget.files > MAX_GENERATED_COMPARE_FILES)
+                return false;
+            const [leftMetadata, rightMetadata] = await Promise.all([
+                lstat(leftPath),
+                lstat(rightPath)
+            ]);
+            if (leftMetadata.size !== rightMetadata.size)
+                return false;
+            budget.bytes += leftMetadata.size;
+            if (budget.bytes > MAX_GENERATED_COMPARE_BYTES)
+                return false;
+            const [leftBytes, rightBytes] = await Promise.all([
+                readFile(leftPath),
+                readFile(rightPath)
+            ]);
+            if (!leftBytes.equals(rightBytes))
+                return false;
+        }
+        return true;
+    };
+    return compare(left, right);
+}
 async function runCommand(integration, args, children, signal) {
     throwIfAborted(signal);
     const argv = [...integration.commandArgs, ...args];