@hops-ops/distributed 4.10.0 → 4.11.0

package/README.md

@@ -134,9 +134,52 @@ request-local replica. A single-surface application can omit the second entry.
 A component can own a sibling `Component.graphql` island. The adapter walks
 static Svelte imports and promotes `@load` work to the nearest page/layout.
 Route-local `+page.graphql` and `+layout.graphql` remain first-class. When a
-required variable cannot be proved from route/search/session/forwarded-prop
-sources, add one typed `boundaries` registration here; that generated binding
-is reused by SSR, hover prefetch, navigation, hydration, and live work.
+surface needs its own authorization-specific copy, use a qualified route
+document such as `+layout.public.graphql`; it still belongs to that layout.
+
+Put stable values in GraphQL itself:
+
+```graphql
+query ChatMessages(
+  $limit: Int! = 25
+  $offset: Int! = 0
+) @load @live {
+  chat_messages(limit: $limit, offset: $offset) { message_id body }
+}
+```
+
+The generated variable properties are optional, while the compiler-owned codec
+canonicalizes the defaults before cache identity, SSR, live continuation, or
+transport. An explicit `ChatMessages.use({ limit: 50, offset: 0 })` overrides
+them; `ChatMessages.use()` uses the exact defaults.
+
+Same-name route parameters are inferred. For external values, add one bounded
+sidecar beside the document rather than putting screen behavior in
+`distributed.config.js`:
+
+```js
+// SearchResults.graphql.bindings.js
+import {
+  defineGraphqlIslandBindings,
+  forwardedProp,
+  searchParam,
+  sessionClaim
+} from '@hops-ops/distributed/sveltekit';
+
+export default defineGraphqlIslandBindings({
+  query: searchParam('q'),
+  viewerId: sessionClaim('user', 'id'),
+  filters: forwardedProp('filters')
+});
+```
+
+The helper rejects unsafe shapes, generation checks the keys against the
+operation, and the same binding is reused by SSR, hover prefetch, navigation,
+hydration, and live work. Resolution precedence is explicit call variables,
+then sidecar/route sources, then GraphQL defaults. A non-null variable without
+any of those sources fails generation before transport. Central `boundaries`
+registrations remain an explicit-placement escape hatch and cannot be combined
+with a sidecar for the same operation.
 
 The Vite integration runs `distributed client` at startup/build, watches GraphQL
 documents, stages all surfaces, commits a rollback-capable multi-output

package/dist/replica/identity/codec.d.ts

@@ -3,6 +3,7 @@ import type { ReplicaOperationArtifact, ReplicaVariableCodecArtifact, ReplicaVar
 export type VariableCodecRegistry = {
     readonly limits: ReplicaVariableCodecLimits;
     readonly variables: ReadonlyMap<string, ReplicaVariableInputRef>;
+    readonly defaults: ReadonlyMap<string, ReplicaValue>;
     readonly inputs: ReadonlyMap<string, ReplicaVariableInputDefinition>;
 };
 /**

package/dist/replica/identity/codec.js

@@ -24,6 +24,10 @@ export function canonicalizeOperationVariables(artifact, variables) {
     for (const [name, input] of [...registry.variables].sort(([left], [right]) => compareCodeUnits(left, right))) {
         const present = supplied.has(name) && supplied.get(name) !== undefined;
         if (!present) {
+            if (registry.defaults.has(name)) {
+                canonical.push([name, registry.defaults.get(name)]);
+                continue;
+            }
             if (!input.nullable) {
                 variableValueInvalid(`variables.${name}`, 'required variable is missing');
             }
@@ -37,8 +41,8 @@ export function canonicalizeOperationVariables(artifact, variables) {
     return freezeRecord(canonical);
 }
 export function validateVariableCodec(codec) {
-    const root = artifactRecord(codec, 'artifact.variableCodec', ['version', 'limits', 'variables', 'inputs']);
-    if (root.version !== 1)
+    const root = artifactRecord(codec, 'artifact.variableCodec', ['version', 'limits', 'variables', 'defaults', 'inputs']);
+    if (root.version !== 2)
         variableCodecInvalid('artifact.variableCodec.version');
     const rawLimits = artifactRecord(root.limits, 'artifact.variableCodec.limits', ['maxDepth', 'maxBoolWidth', 'maxInList']);
     const limits = {
@@ -62,7 +66,16 @@ export function validateVariableCodec(codec) {
     for (const [name, definition] of inputs) {
         validateInputDefinition(definition, `artifact.variableCodec.inputs.${name}`, inputs, new Set(), 0);
     }
-    return { limits, variables, inputs };
+    const defaults = new Map();
+    const registry = { limits, variables, defaults, inputs };
+    for (const [name, value] of artifactRecordEntries(root.defaults, 'artifact.variableCodec.defaults')) {
+        const input = variables.get(name);
+        if (input === undefined) {
+            variableCodecInvalid(`artifact.variableCodec.defaults.${name}`);
+        }
+        defaults.set(name, canonicalizeInputRef(input, value, registry, `artifact.variableCodec.defaults.${name}`, new Set(), 0));
+    }
+    return registry;
 }
 export function validateInputRef(value, path, inputs, limits, active, depth) {
     checkCodecDepth(depth, path);

package/dist/replica/types.d.ts

@@ -150,9 +150,11 @@ export type ReplicaVariableCodecLimits = {
 };
 /** Exact variable codec emitted beside a generated operation artifact. */
 export type ReplicaVariableCodecArtifact = {
-    readonly version: 1;
+    readonly version: 2;
     readonly limits: ReplicaVariableCodecLimits;
     readonly variables: Readonly<Record<string, ReplicaVariableInputRef>>;
+    /** Canonical GraphQL defaults, applied before cache identity or transport. */
+    readonly defaults: Readonly<Record<string, ReplicaValue>>;
     readonly inputs: Readonly<Record<string, ReplicaVariableInputDefinition>>;
 };
 export type ReplicaFilterOperator = '_eq' | '_neq' | '_gt' | '_gte' | '_lt' | '_lte' | '_in' | '_nin' | '_is_null' | '_like' | '_ilike' | '_contains' | '_contained_in' | '_has_key';
@@ -463,6 +465,7 @@ export type ReplicaIslandMetadata = {
         readonly variables: readonly {
             readonly name: string;
             readonly graphqlType: string;
+            readonly defaultValue?: ReplicaValue;
         }[];
     };
     readonly liveCoverage: {

package/dist/sveltekit/boundary-variables.js

@@ -96,9 +96,13 @@ function validateSources(artifact, sources) {
         throw new TypeError('Distributed boundary variable sources must be an object');
     }
     const definitions = artifact.variableCodec?.variables;
+    const defaults = artifact.variableCodec?.defaults;
     if (definitions === null || typeof definitions !== 'object' || Array.isArray(definitions)) {
         throw new TypeError('Distributed boundary artifact has no variable codec');
     }
+    if (defaults === null || typeof defaults !== 'object' || Array.isArray(defaults)) {
+        throw new TypeError('Distributed boundary artifact has no variable defaults');
+    }
     const names = Object.keys(sources);
     if (names.length > MAX_BINDING_VARIABLES) {
         throw new TypeError(`Distributed boundary binding exceeds ${MAX_BINDING_VARIABLES} variables`);
@@ -116,7 +120,7 @@ function validateSources(artifact, sources) {
             typeof definition === 'object' &&
             'nullable' in definition &&
             definition.nullable === false;
-        if (required && !Object.hasOwn(sources, name)) {
+        if (required && !Object.hasOwn(defaults, name) && !Object.hasOwn(sources, name)) {
             throw new TypeError(`Distributed boundary binding is missing required variable ${name}; use an explicit binding, parent/boundary query, client-only execution, or a better read root`);
         }
     }

package/dist/sveltekit/index.d.ts

@@ -2,6 +2,7 @@ export { authFromPageData, type PageGraphqlData } from './auth.js';
 export { distributedReloadLifecycle, registerDistributedReloadClient, validateDistributedReloadLocation, validateDistributedReloadState, type DistributedReloadLifecycle, type DistributedReloadOptions, type DistributedReloadStateDeclaration } from './lifecycle.js';
 export { parseDistributedGenerationEnvelope, type DistributedGenerationEnvelope } from '../generation.js';
 export { defineDistributedBoundaryBinding, defineDistributedBoundaryOperation, resolveDistributedBoundaryVariables, type DistributedBoundaryBinding, type DistributedBoundaryOperation, type DistributedBoundaryPlan, type DistributedBoundaryVariableContext, type DistributedBoundaryVariableSource, type DistributedBoundaryVariableSources } from './boundary-variables.js';
+export { constant, defineGraphqlIslandBindings, forwardedProp, omitVariable, routeParam, searchParam, sessionClaim } from './island-bindings.js';
 export { DistributedSvelteKitBoundaryController, type DistributedSvelteKitBoundaryInstance, type DistributedSvelteKitBoundaryLocation, type DistributedSvelteKitLocationContext, type SveltekitBoundaryLifecycleDiagnostic, type SveltekitBoundaryRetention } from './boundary-lifecycle.js';
 export { defineDistributedSvelteKitOperation, provideDistributedSvelteKitClient, retainDistributedSvelteKitBoundary, useDistributedSvelteKitClient, useDistributedSvelteKitCommands } from './context.js';
 export { bindSveltekitOperation, createPageDataSessionSource, createDistributedSvelteKit, sessionSourceFromPageData, type CreateDistributedSvelteKitOptions, type DistributedSvelteKitClient, type SveltekitBoundOperation, type SveltekitBoundBoundaryOperation, type SveltekitCommandRuntimeFactory, type SveltekitCommandRuntimeFactoryOptions, type SveltekitCommandRuntimeLike, type SveltekitDistributedPageData, type SveltekitPageDataSessionSource, type SveltekitPageDataSource, type SveltekitQuerySnapshot, type SveltekitQueryStore, type SveltekitReplicaAuthority, type SveltekitReplicaHydration, type SveltekitSessionSource, type UseSveltekitOperationOptions } from './replica.js';

package/dist/sveltekit/index.js

@@ -2,6 +2,7 @@ export { authFromPageData } from './auth.js';
 export { distributedReloadLifecycle, registerDistributedReloadClient, validateDistributedReloadLocation, validateDistributedReloadState } from './lifecycle.js';
 export { parseDistributedGenerationEnvelope } from '../generation.js';
 export { defineDistributedBoundaryBinding, defineDistributedBoundaryOperation, resolveDistributedBoundaryVariables } from './boundary-variables.js';
+export { constant, defineGraphqlIslandBindings, forwardedProp, omitVariable, routeParam, searchParam, sessionClaim } from './island-bindings.js';
 export { DistributedSvelteKitBoundaryController } from './boundary-lifecycle.js';
 export { defineDistributedSvelteKitOperation, provideDistributedSvelteKitClient, retainDistributedSvelteKitBoundary, useDistributedSvelteKitClient, useDistributedSvelteKitCommands } from './context.js';
 export { bindSveltekitOperation, createPageDataSessionSource, createDistributedSvelteKit, sessionSourceFromPageData } from './replica.js';

package/dist/sveltekit/island-bindings.d.ts

@@ -0,0 +1,17 @@
+import type { GraphqlVariables } from '../types.js';
+import type { DistributedBoundaryVariableSource, DistributedBoundaryVariableSources } from './boundary-variables.js';
+/**
+ * Define the exceptional variables for one colocated GraphQL island.
+ *
+ * Save the default export as `<document>.bindings.js`. Route parameters with
+ * the same name and GraphQL variable defaults need no sidecar entry.
+ */
+export declare function defineGraphqlIslandBindings<TVariables extends GraphqlVariables = GraphqlVariables>(sources: DistributedBoundaryVariableSources<TVariables>): DistributedBoundaryVariableSources<TVariables>;
+/** @internal Validate a discovered sidecar without trusting its prototype. */
+export declare function isGraphqlIslandBindings(value: unknown): value is DistributedBoundaryVariableSources<GraphqlVariables>;
+export declare function routeParam(name: string): DistributedBoundaryVariableSource;
+export declare function searchParam(name: string, mode?: 'first' | 'all'): DistributedBoundaryVariableSource;
+export declare function sessionClaim(...path: string[]): DistributedBoundaryVariableSource;
+export declare function forwardedProp(...path: string[]): DistributedBoundaryVariableSource;
+export declare function constant<TValue>(value: TValue): DistributedBoundaryVariableSource<TValue>;
+export declare function omitVariable(): DistributedBoundaryVariableSource;

package/dist/sveltekit/island-bindings.js

@@ -0,0 +1,58 @@
+const GRAPHQL_ISLAND_BINDINGS = Symbol.for('@hops-ops/distributed/graphql-island-bindings');
+const HOSTILE_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+/**
+ * Define the exceptional variables for one colocated GraphQL island.
+ *
+ * Save the default export as `<document>.bindings.js`. Route parameters with
+ * the same name and GraphQL variable defaults need no sidecar entry.
+ */
+export function defineGraphqlIslandBindings(sources) {
+    if (sources === null ||
+        typeof sources !== 'object' ||
+        Array.isArray(sources) ||
+        (Object.getPrototypeOf(sources) !== Object.prototype &&
+            Object.getPrototypeOf(sources) !== null)) {
+        throw new TypeError('GraphQL island bindings must be an object');
+    }
+    const bindings = {};
+    for (const key of Object.keys(sources)) {
+        if (HOSTILE_KEYS.has(key)) {
+            throw new TypeError(`GraphQL island binding name ${key} is unsafe`);
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(sources, key);
+        if (descriptor === undefined || !('value' in descriptor)) {
+            throw new TypeError(`GraphQL island binding ${key} must be a data property`);
+        }
+        bindings[key] = descriptor.value;
+    }
+    Object.defineProperty(bindings, GRAPHQL_ISLAND_BINDINGS, {
+        value: true,
+        enumerable: false
+    });
+    return Object.freeze(bindings);
+}
+/** @internal Validate a discovered sidecar without trusting its prototype. */
+export function isGraphqlIslandBindings(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const descriptor = Object.getOwnPropertyDescriptor(value, GRAPHQL_ISLAND_BINDINGS);
+    return descriptor !== undefined && 'value' in descriptor && descriptor.value === true;
+}
+export function routeParam(name) {
+    return Object.freeze({ kind: 'route_param', name });
+}
+export function searchParam(name, mode = 'first') {
+    return Object.freeze({ kind: 'search_param', name, mode });
+}
+export function sessionClaim(...path) {
+    return Object.freeze({ kind: 'trusted_session', path: Object.freeze(path) });
+}
+export function forwardedProp(...path) {
+    return Object.freeze({ kind: 'forwarded_prop', path: Object.freeze(path) });
+}
+export function constant(value) {
+    return Object.freeze({ kind: 'constant', value });
+}
+export function omitVariable() {
+    return Object.freeze({ kind: 'omit' });
+}

package/dist/sveltekit/islands/boundaries.d.ts

@@ -34,6 +34,7 @@ export type DistributedIslandPlanInput = Readonly<{
         variables: readonly Readonly<{
             name: string;
             graphqlType: string;
+            defaultValue?: unknown;
         }>[];
     }>;
 }>;
@@ -98,7 +99,9 @@ export type DistributedSvelteKitBoundaryAnalysisOptions = Readonly<{
 /** Validate a persisted adapter plan before check/dev treats it as coherent. */
 export declare function validateDistributedSvelteKitBoundaryPlan(value: unknown, module?: string): DistributedSvelteKitBoundaryPlan;
 /**
- * Analyze Svelte component reachability without evaluating application code.
- * The returned plan is deterministic and contains project-relative paths only.
+ * Analyze Svelte component reachability without evaluating application
+ * components. Colocated, bounded GraphQL binding sidecars are the only app
+ * modules evaluated. The returned plan is deterministic and contains
+ * project-relative paths only.
  */
 export declare function analyzeDistributedSvelteKitBoundaries(options: DistributedSvelteKitBoundaryAnalysisOptions): Promise<readonly DistributedSvelteKitBoundaryPlan[]>;

package/dist/sveltekit/islands/boundaries.js

@@ -1,10 +1,15 @@
-import { lstat, readFile, readdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readdir, realpath } from 'node:fs/promises';
 import { dirname, extname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { parse } from 'svelte/compiler';
+import { isGraphqlIslandBindings } from '../island-bindings.js';
 const BOUNDARY_PLAN_VERSION = 1;
+const VARIABLE_CODEC_VERSION = 2;
 const MAX_COMPONENTS = 4_096;
 const MAX_ISLANDS = 4_096;
 const MAX_COMPONENT_BYTES = 2 * 1024 * 1024;
+const MAX_BINDINGS_BYTES = 256 * 1024;
 const MAX_GRAPH_EDGES = 32_768;
 /** Validate a persisted adapter plan before check/dev treats it as coherent. */
 export function validateDistributedSvelteKitBoundaryPlan(value, module) {
@@ -21,8 +26,10 @@ export function validateDistributedSvelteKitBoundaryPlan(value, module) {
     return value;
 }
 /**
- * Analyze Svelte component reachability without evaluating application code.
- * The returned plan is deterministic and contains project-relative paths only.
+ * Analyze Svelte component reachability without evaluating application
+ * components. Colocated, bounded GraphQL binding sidecars are the only app
+ * modules evaluated. The returned plan is deterministic and contains
+ * project-relative paths only.
  */
 export async function analyzeDistributedSvelteKitBoundaries(options) {
     const cwd = resolve(options.cwd);
@@ -52,6 +59,7 @@ export async function analyzeDistributedSvelteKitBoundaries(options) {
         }
     }
     const plans = [];
+    const colocatedBindings = await loadColocatedBindings(cwd, sourceOwners.keys());
     for (const client of [...options.clients].sort((left, right) => left.module.localeCompare(right.module))) {
         const loadIslands = client.inventory.islands
             .filter((island) => island.directives.load)
@@ -115,11 +123,11 @@ export async function analyzeDistributedSvelteKitBoundaries(options) {
             const explicitEntries = explicitByBoundary.get(root.id) ?? [];
             const explicitAtBoundary = new Set(explicitEntries.map(({ entry }) => entry.island.id));
             for (const { entry, registration } of explicitEntries) {
-                occurrences.push(occurrence(cwd, entry, root, root.path, 'explicit', false, registration.variables));
+                occurrences.push(occurrence(cwd, entry, root, root.path, 'explicit', false, bindingSources(entry, registration.variables, colocatedBindings)));
                 placed.add(entry.island.id);
             }
             for (const entry of routeIslands.get(routeBoundaryKey(root.kind, dirname(root.path))) ?? []) {
-                occurrences.push(occurrence(cwd, entry, root, root.path, 'route_document', false, explicitByIdentity.get(`${root.id}\u0000${entry.island.operation}`)?.variables));
+                occurrences.push(occurrence(cwd, entry, root, root.path, 'route_document', false, bindingSources(entry, explicitByIdentity.get(`${root.id}\u0000${entry.island.operation}`)?.variables, colocatedBindings)));
                 placed.add(entry.island.id);
             }
             const dynamicComponentIslands = new Map([...componentIslands.entries()]
@@ -131,7 +139,7 @@ export async function analyzeDistributedSvelteKitBoundaries(options) {
             const reachable = traverse(root, components, aliases, dynamicComponentIslands, cwd);
             for (const component of reachable) {
                 for (const entry of componentIslands.get(component) ?? []) {
-                    occurrences.push(occurrence(cwd, entry, root, component, 'static_component_import', true, explicitByIdentity.get(`${root.id}\u0000${entry.island.operation}`)?.variables));
+                    occurrences.push(occurrence(cwd, entry, root, component, 'static_component_import', true, bindingSources(entry, explicitByIdentity.get(`${root.id}\u0000${entry.island.operation}`)?.variables, colocatedBindings)));
                     placed.add(entry.island.id);
                 }
             }
@@ -164,6 +172,49 @@ export async function analyzeDistributedSvelteKitBoundaries(options) {
     }
     return Object.freeze(plans);
 }
+function bindingSources(entry, explicit, colocated) {
+    const sidecar = colocated.get(entry.source);
+    if (explicit !== undefined && sidecar !== undefined) {
+        throw diagnostic('distributed.island.variable_binding_conflict', entry.source, entry.island.source.line, entry.island.source.column, `operation ${entry.island.operation} has both centralized and colocated variable bindings; remove the screen behavior from distributed.config and keep ${entry.source}.bindings.js`);
+    }
+    return sidecar ?? explicit;
+}
+async function loadColocatedBindings(cwd, sources) {
+    const canonicalRoot = await realpath(cwd);
+    const bindings = new Map();
+    for (const source of [...new Set(sources)].sort()) {
+        const path = contained(cwd, `${source}.bindings.js`, 'GraphQL island bindings');
+        let metadata;
+        try {
+            metadata = await lstat(path);
+        }
+        catch (error) {
+            if (isMissing(error))
+                continue;
+            throw error;
+        }
+        if (!metadata.isFile() || metadata.isSymbolicLink()) {
+            throw new Error(`[distributed.island.bindings_invalid] ${source}.bindings.js must be a regular project-local file`);
+        }
+        if (metadata.size > MAX_BINDINGS_BYTES) {
+            throw new Error(`[distributed.island.bindings_too_large] ${source}.bindings.js exceeds ${MAX_BINDINGS_BYTES} bytes`);
+        }
+        const canonicalPath = await realpath(path);
+        if (!isWithin(canonicalRoot, canonicalPath)) {
+            throw new Error(`[distributed.island.bindings_invalid] ${source}.bindings.js must stay within the project root`);
+        }
+        const bytes = await readFile(canonicalPath);
+        const url = pathToFileURL(canonicalPath);
+        url.searchParams.set('distributed-binding', createHash('sha256').update(bytes).digest('hex'));
+        const loaded = await import(url.href);
+        const value = ownDataValue(loaded, 'default');
+        if (!isGraphqlIslandBindings(value)) {
+            throw new Error(`[distributed.island.bindings_invalid] ${source}.bindings.js must default-export defineGraphqlIslandBindings({...})`);
+        }
+        bindings.set(source, value);
+    }
+    return bindings;
+}
 function occurrence(cwd, entry, root, component, reason, conservative, explicitSources) {
     if (root.kind === 'layout' &&
         entry.island.directives.live &&
@@ -222,7 +273,7 @@ function boundaryBinding(entry, root, explicitSources) {
             ]);
             hasRoute = true;
         }
-        else if (!variable.graphqlType.endsWith('!')) {
+        else if (Object.hasOwn(variable, 'defaultValue') || !variable.graphqlType.endsWith('!')) {
             sources.push([variable.name, Object.freeze({ kind: 'omit' })]);
         }
         else {
@@ -546,10 +597,11 @@ function islandOwnerComponent(cwd, source) {
     const suffix = extname(absolute);
     const base = absolute.slice(0, -suffix.length);
     const name = posix.basename(portable(base));
-    if (name === '+page' || name === '+layout') {
+    const routeDocument = /^\+(page|layout)(?:\.[_A-Za-z][_0-9A-Za-z-]*)?$/.exec(name);
+    if (routeDocument !== null) {
         return {
             kind: 'route',
-            key: routeBoundaryKey(name === '+page' ? 'page' : 'layout', dirname(base))
+            key: routeBoundaryKey(routeDocument[1] === 'page' ? 'page' : 'layout', dirname(base))
         };
     }
     return { kind: 'component', path: `${base}.svelte` };
@@ -590,6 +642,8 @@ function validateInventory(module, inventory) {
             Array.isArray(variableSchema) ||
             typeof variableSchema.reference !== 'string' ||
             !Number.isSafeInteger(variableSchema.codecVersion) ||
+            variableSchema.codecVersion !== VARIABLE_CODEC_VERSION ||
+            !variableSchema.reference.endsWith(`#variable-codec-v${VARIABLE_CODEC_VERSION}`) ||
             !Array.isArray(variableSchema.variables) ||
             variableSchema.variables.some((variable) => variable === null ||
                 typeof variable !== 'object' ||

package/dist/sveltekit/vite.js

@@ -62,7 +62,7 @@ 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;
+    const lifecycleOwnsCompile = process.env.DISTRIBUTED_LIFECYCLE_OWNS_CLIENT_COMPILE === '1';
     let resolved;
     let dirty = false;
     let running;
@@ -135,14 +135,11 @@ export function distributedSvelteKit(options) {
             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.
+             * The lifecycle has already built the active generation before it starts
+             * this UI process. The supervisor activates later generations atomically
+             * while this server stays available; compiling again here would race that
+             * owner and can prevent the UI from reaching its readiness probe.
              */
-            if (lifecycleOwnsCompile)
-                return;
             /*
              * SvelteKit post-build analysis loads Vite config in an isolated
              * worker marked with SVELTEKIT_FORK. That pass reads framework
@@ -151,6 +148,8 @@ export function distributedSvelteKit(options) {
              */
             if (!isMainThread && process.env.SVELTEKIT_FORK === 'true')
                 return;
+            if (lifecycleOwnsCompile)
+                return;
             lock = await acquireCompilerLock(resolved.cwd);
             try {
                 await compile('Vite startup', true);
@@ -229,7 +228,7 @@ export function distributedSvelteKit(options) {
                     context.server.moduleGraph.invalidateModule(module);
                 }
             }
-            if (process.env.DISTRIBUTED_LIFECYCLE_DIR === undefined) {
+            if (!lifecycleOwnsCompile) {
                 context.server.ws.send({ type: 'full-reload', path: '*' });
             }
             reloadedGeneration = completedGeneration;
@@ -665,12 +664,15 @@ function isCompilerInput(file, integration) {
 }
 function isGraphqlInput(file, integration) {
     const absolute = resolve(integration.cwd, file);
+    const isDocument = absolute.endsWith('.graphql') || absolute.endsWith('.gql');
+    const isBindings = absolute.endsWith('.graphql.bindings.js') ||
+        absolute.endsWith('.gql.bindings.js');
     if (absolute.endsWith('.svelte') &&
         (isWithin(integration.routesDir, absolute) ||
             isWithin(integration.libDir, absolute))) {
         return true;
     }
-    if ((!absolute.endsWith('.graphql') && !absolute.endsWith('.gql')) ||
+    if ((!isDocument && !isBindings) ||
         !isWithin(integration.cwd, absolute)) {
         return false;
     }
@@ -728,7 +730,7 @@ async function compileTransaction(integration, children, signal) {
                 hadAdapterOutput: await realDirectoryExists(client.adapterOut)
             });
         }
-        const plans = await analyzeStagedBoundaries(integration, staged);
+        const plans = await analyzeStagedBoundaries(integration, transaction, staged);
         const plansByModule = new Map(plans.map((plan) => [plan.module, plan]));
         for (const item of staged) {
             const plan = plansByModule.get(item.client.module);
@@ -775,7 +777,7 @@ async function checkTransaction(integration, children, signal) {
             await validateGeneratedEntrypoint(integration.cwd, output, client.module);
             staged.push(Object.freeze({ client, output }));
         }
-        const plans = await analyzeStagedBoundaries(integration, staged);
+        const plans = await analyzeStagedBoundaries(integration, transaction, staged);
         const plansByModule = new Map(plans.map((plan) => [plan.module, plan]));
         for (const [index, client] of integration.clients.entries()) {
             const output = staged[index].output;
@@ -829,7 +831,7 @@ async function validateAdapterBoundaryPlan(client, plan) {
         throw new Error(`Distributed SvelteKit boundary plan for ${client.module} is stale; run generation without check`);
     }
 }
-async function analyzeStagedBoundaries(integration, staged) {
+async function analyzeStagedBoundaries(integration, transactionRoot, staged) {
     return await analyzeDistributedSvelteKitBoundaries({
         cwd: integration.cwd,
         routesDir: portablePath(relative(integration.cwd, integration.routesDir)),
@@ -837,18 +839,18 @@ async function analyzeStagedBoundaries(integration, staged) {
         aliases: integration.aliases,
         clients: await Promise.all(staged.map(async ({ client, output }) => ({
             module: client.module,
-            inventory: await readIslandInventory(integration.cwd, output),
+            inventory: await readIslandInventory(transactionRoot, output),
             explicitBoundaries: client.boundaries
         })))
     });
 }
-async function readIslandInventory(cwd, output) {
+async function readIslandInventory(transactionRoot, 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`);
+        throw new Error(`Distributed island inventory ${portablePath(relative(transactionRoot, path))} must be a regular file`);
     }
-    const canonicalRoot = await realpath(cwd);
+    const canonicalRoot = await realpath(transactionRoot);
     const canonical = await realpath(path);
     if (!isWithin(canonicalRoot, canonical)) {
         throw new Error('Distributed island inventory escaped the project root');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hops-ops/distributed",
-  "version": "4.10.0",
+  "version": "4.11.0",
   "description": "Typed GraphQL client, causal replica, command runtime, and framework adapters for Distributed services",
   "type": "module",
   "license": "UNLICENSED",