@hops-ops/distributed 4.9.0 → 4.11.0

package/dist/sveltekit/boundary-variables.js

@@ -0,0 +1,294 @@
+import { canonicalizeOperationVariables } from '../replica/index.js';
+const BINDING_VERSION = 1;
+const GRAPHQL_NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
+const MAX_BINDING_VARIABLES = 128;
+const MAX_PATH_SEGMENTS = 16;
+const MAX_LITERAL_DEPTH = 32;
+const MAX_LITERAL_VALUES = 4_096;
+const HOSTILE_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+/**
+ * Define one closed, inspectable variable binding for every boundary lifecycle.
+ * The operation artifact remains the sole owner of coercion and cache identity.
+ */
+export function defineDistributedBoundaryBinding(artifact, sources) {
+    const validated = validateSources(artifact, sources);
+    const id = `boundary-v${BINDING_VERSION}:${fnv1a64(`${artifact.id}\n${stableJson(validated)}`)}`;
+    const resolve = (context) => resolveDistributedBoundaryVariables(artifact, validated, context);
+    return Object.freeze({
+        version: BINDING_VERSION,
+        id,
+        artifactId: artifact.id,
+        sources: validated,
+        resolve,
+        canonicalBytes(context) {
+            return JSON.stringify(resolve(context));
+        }
+    });
+}
+export function defineDistributedBoundaryOperation(plan, artifact, binding) {
+    if (binding.artifactId !== artifact.id) {
+        throw new TypeError('Distributed boundary binding belongs to a different operation artifact');
+    }
+    if (plan === null ||
+        typeof plan !== 'object' ||
+        !GRAPHQL_NAME.test(plan.operation) ||
+        !plan.route.startsWith('/') ||
+        (plan.kind !== 'layout' && plan.kind !== 'page') ||
+        !['component', 'route_document', 'explicit'].includes(plan.discovery)) {
+        throw new TypeError('Distributed boundary operation plan is invalid');
+    }
+    return Object.freeze({
+        plan: Object.freeze({ ...plan }),
+        artifact,
+        binding
+    });
+}
+export function resolveDistributedBoundaryVariables(artifact, sources, context) {
+    if (context === null || typeof context !== 'object') {
+        throw new TypeError('Distributed boundary variable context is required');
+    }
+    const entries = [];
+    for (const [variable, source] of Object.entries(sources).sort(([left], [right]) => left.localeCompare(right))) {
+        const value = resolveSource(source, context);
+        if (value !== OMITTED)
+            entries.push([variable, value]);
+    }
+    return canonicalizeOperationVariables(artifact, Object.fromEntries(entries));
+}
+const OMITTED = Symbol('distributed.boundary.omitted');
+function resolveSource(source, context) {
+    switch (source.kind) {
+        case 'omit':
+            return OMITTED;
+        case 'constant':
+            return source.value;
+        case 'route_param': {
+            const value = ownValue(context.params, source.name);
+            return value === undefined ? OMITTED : value;
+        }
+        case 'search_param': {
+            const search = context.search;
+            if (isSearchParams(search)) {
+                if (source.mode === 'all')
+                    return search.getAll(source.name);
+                const value = search.get(source.name);
+                return value === null ? OMITTED : value;
+            }
+            const value = ownValue(search, source.name);
+            if (value === undefined)
+                return source.mode === 'all' ? [] : OMITTED;
+            if (source.mode === 'all')
+                return Array.isArray(value) ? [...value] : [value];
+            return Array.isArray(value) ? (value[0] ?? OMITTED) : value;
+        }
+        case 'trusted_session': {
+            const value = readPath(context.session, source.path, 'trusted session');
+            return value === undefined ? OMITTED : value;
+        }
+        case 'forwarded_prop': {
+            const value = readPath(context.props, source.path, 'forwarded prop');
+            return value === undefined ? OMITTED : value;
+        }
+    }
+}
+function validateSources(artifact, sources) {
+    if (sources === null || typeof sources !== 'object' || Array.isArray(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`);
+    }
+    const entries = [];
+    for (const name of names.sort()) {
+        if (!GRAPHQL_NAME.test(name) || !Object.hasOwn(definitions, name)) {
+            throw new TypeError(`Distributed boundary binding names unknown variable ${name}`);
+        }
+        const source = ownValue(sources, name);
+        entries.push([name, validateSource(source, name)]);
+    }
+    for (const [name, definition] of Object.entries(definitions)) {
+        const required = definition !== null &&
+            typeof definition === 'object' &&
+            'nullable' in definition &&
+            definition.nullable === false;
+        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`);
+        }
+    }
+    return Object.freeze(Object.fromEntries(entries));
+}
+function validateSource(value, variable) {
+    const source = exactRecord(value, `binding source ${variable}`);
+    if (typeof source.kind !== 'string') {
+        throw new TypeError(`Distributed boundary source ${variable} has no kind`);
+    }
+    switch (source.kind) {
+        case 'omit':
+            exactKeys(source, ['kind'], variable);
+            return Object.freeze({ kind: 'omit' });
+        case 'route_param':
+            exactKeys(source, ['kind', 'name'], variable);
+            return Object.freeze({ kind: 'route_param', name: safeName(source.name, variable) });
+        case 'search_param': {
+            exactKeys(source, ['kind', 'name', 'mode'], variable, ['mode']);
+            if (source.mode !== undefined && source.mode !== 'first' && source.mode !== 'all') {
+                throw new TypeError(`Distributed boundary source ${variable} has invalid search mode`);
+            }
+            return Object.freeze({
+                kind: 'search_param',
+                name: safeName(source.name, variable),
+                ...(source.mode === undefined ? {} : { mode: source.mode })
+            });
+        }
+        case 'trusted_session':
+            exactKeys(source, ['kind', 'path'], variable);
+            return Object.freeze({ kind: 'trusted_session', path: safePath(source.path, variable) });
+        case 'forwarded_prop':
+            exactKeys(source, ['kind', 'path'], variable);
+            return Object.freeze({ kind: 'forwarded_prop', path: safePath(source.path, variable) });
+        case 'constant':
+            exactKeys(source, ['kind', 'value'], variable);
+            return Object.freeze({
+                kind: 'constant',
+                value: freezeJson(stableValue(source.value))
+            });
+        default:
+            throw new TypeError(`Distributed boundary source ${variable} is unsupported; use an explicit binding, parent/boundary query, client-only execution, or a better read root`);
+    }
+}
+function safePath(value, variable) {
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        value.length > MAX_PATH_SEGMENTS ||
+        value.some((part) => typeof part !== 'string' || !GRAPHQL_NAME.test(part) || HOSTILE_KEYS.has(part))) {
+        throw new TypeError(`Distributed boundary source ${variable} has an invalid path`);
+    }
+    return Object.freeze([...value]);
+}
+function safeName(value, variable) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 512) {
+        throw new TypeError(`Distributed boundary source ${variable} has an invalid name`);
+    }
+    return value;
+}
+function readPath(value, path, label) {
+    let current = value;
+    for (const segment of path) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        const descriptor = Object.getOwnPropertyDescriptor(current, segment);
+        if (descriptor === undefined)
+            return undefined;
+        if (!('value' in descriptor)) {
+            throw new TypeError(`Distributed boundary ${label} path contains an accessor`);
+        }
+        current = descriptor.value;
+    }
+    return current;
+}
+function ownValue(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined)
+        return undefined;
+    if (!('value' in descriptor)) {
+        throw new TypeError('Distributed boundary input contains an accessor');
+    }
+    return descriptor.value;
+}
+function isSearchParams(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof value.get === 'function' &&
+        typeof value.getAll === 'function');
+}
+function exactRecord(value, label) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
+        throw new TypeError(`Distributed ${label} must be a plain object`);
+    }
+    return value;
+}
+function exactKeys(value, allowed, variable, optional = []) {
+    const permitted = new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!permitted.has(key)) {
+            throw new TypeError(`Distributed boundary source ${variable} contains unknown field ${key}`);
+        }
+    }
+    for (const key of allowed) {
+        if (!optional.includes(key) && !Object.hasOwn(value, key)) {
+            throw new TypeError(`Distributed boundary source ${variable} is missing field ${key}`);
+        }
+    }
+}
+function stableJson(value) {
+    return JSON.stringify(stableValue(value));
+}
+function stableValue(value) {
+    let visited = 0;
+    const active = new Set();
+    const visit = (current, depth) => {
+        visited += 1;
+        if (visited > MAX_LITERAL_VALUES || depth > MAX_LITERAL_DEPTH) {
+            throw new TypeError('Distributed boundary constant exceeds structural limits');
+        }
+        if (current === null ||
+            typeof current === 'string' ||
+            typeof current === 'boolean')
+            return current;
+        if (typeof current === 'number' && Number.isFinite(current))
+            return current;
+        if (typeof current !== 'object') {
+            throw new TypeError('Distributed boundary constant is not JSON-compatible');
+        }
+        if (active.has(current))
+            throw new TypeError('Distributed boundary constant is cyclic');
+        active.add(current);
+        try {
+            if (Array.isArray(current))
+                return current.map((entry) => visit(entry, depth + 1));
+            const record = exactRecord(current, 'boundary constant');
+            return Object.fromEntries(Object.keys(record).sort().map((key) => {
+                if (HOSTILE_KEYS.has(key)) {
+                    throw new TypeError('Distributed boundary constant contains a hostile object key');
+                }
+                return [key, visit(ownValue(record, key), depth + 1)];
+            }));
+        }
+        finally {
+            active.delete(current);
+        }
+    };
+    return visit(value, 0);
+}
+function fnv1a64(value) {
+    let hash = 0xcbf29ce484222325n;
+    for (const byte of new TextEncoder().encode(value)) {
+        hash ^= BigInt(byte);
+        hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+    }
+    return hash.toString(16).padStart(16, '0');
+}
+function freezeJson(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            freezeJson(entry);
+        return Object.freeze(value);
+    }
+    for (const entry of Object.values(value))
+        freezeJson(entry);
+    return Object.freeze(value);
+}

package/dist/sveltekit/context.d.ts

@@ -1,5 +1,6 @@
 import type { ReplicaOperationArtifact } from '../replica/index.js';
 import type { GraphqlVariables } from '../types.js';
+import type { DistributedSvelteKitBoundaryInstance, SveltekitBoundaryRetention } from './boundary-lifecycle.js';
 import type { DistributedSvelteKitClient, SveltekitBoundOperation } from './replica.js';
 /**
  * Install one client in the current Svelte component tree.
@@ -19,6 +20,8 @@ export declare function provideDistributedSvelteKitClient<TCommands>(client: Dis
 export declare function useDistributedSvelteKitClient<TCommands = Readonly<Record<never, never>>>(): DistributedSvelteKitClient<TCommands>;
 /** Resolve the nearest generated command surface without a global proxy. */
 export declare function useDistributedSvelteKitCommands<TCommands>(): TCommands;
+/** Retain the generated selections owned by the nearest page/layout instance. */
+export declare function retainDistributedSvelteKitBoundary<TSession, TProps>(instance: DistributedSvelteKitBoundaryInstance, context: import('./boundary-variables.js').DistributedBoundaryVariableContext<TSession, TProps>): SveltekitBoundaryRetention;
 /**
  * Define one SSR-safe generated operation wrapper.
  *

package/dist/sveltekit/context.js

@@ -1,4 +1,5 @@
 import { getContext, setContext } from 'svelte';
+import { defineDistributedBoundaryBinding, defineDistributedBoundaryOperation } from './boundary-variables.js';
 const DISTRIBUTED_CLIENT_CONTEXT = Symbol('@hops-ops/distributed/sveltekit/client');
 /**
  * Install one client in the current Svelte component tree.
@@ -34,6 +35,10 @@ export function useDistributedSvelteKitClient() {
 export function useDistributedSvelteKitCommands() {
     return useDistributedSvelteKitClient().commands;
 }
+/** Retain the generated selections owned by the nearest page/layout instance. */
+export function retainDistributedSvelteKitBoundary(instance, context) {
+    return useDistributedSvelteKitClient().retainBoundary(instance, context);
+}
 /**
  * Define one SSR-safe generated operation wrapper.
  *
@@ -58,6 +63,9 @@ export function defineDistributedSvelteKitOperation(artifact) {
             return useDistributedSvelteKitClient()
                 .operation(artifact)
                 .prefetch(variables);
+        },
+        boundary(plan, sources) {
+            return defineDistributedBoundaryOperation(plan, artifact, defineDistributedBoundaryBinding(artifact, sources));
         }
     });
 }

package/dist/sveltekit/index.d.ts

@@ -1,6 +1,9 @@
 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 { defineDistributedSvelteKitOperation, provideDistributedSvelteKitClient, useDistributedSvelteKitClient, useDistributedSvelteKitCommands } from './context.js';
-export { bindSveltekitOperation, createPageDataSessionSource, createDistributedSvelteKit, sessionSourceFromPageData, type CreateDistributedSvelteKitOptions, type DistributedSvelteKitClient, type SveltekitBoundOperation, 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';
-export { createDistributedSvelteKitServer, matchDistributedRoute, registerDistributedRoute, type CreateDistributedSvelteKitServerOptions, type DistributedRouteOperation, type DistributedRoutePlan, type DistributedRouteVariables, type DistributedSvelteKitServer, type SveltekitServerLoadEventLike } from './server-replica.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';
+export { createDistributedSvelteKitServer, type CreateDistributedSvelteKitServerOptions, type DistributedSvelteKitServer, type SveltekitServerLoadEventLike } from './server-replica.js';

package/dist/sveltekit/index.js

@@ -1,6 +1,9 @@
 export { authFromPageData } from './auth.js';
 export { distributedReloadLifecycle, registerDistributedReloadClient, validateDistributedReloadLocation, validateDistributedReloadState } from './lifecycle.js';
 export { parseDistributedGenerationEnvelope } from '../generation.js';
-export { defineDistributedSvelteKitOperation, provideDistributedSvelteKitClient, useDistributedSvelteKitClient, useDistributedSvelteKitCommands } from './context.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';
-export { createDistributedSvelteKitServer, matchDistributedRoute, registerDistributedRoute } from './server-replica.js';
+export { createDistributedSvelteKitServer } from './server-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

@@ -0,0 +1,107 @@
+import type { DistributedBoundaryVariableSource } from '../boundary-variables.js';
+export type DistributedIslandInventory = Readonly<{
+    version: number;
+    schemaFingerprint: string;
+    protocolFingerprint: string;
+    surface: unknown;
+    islands: readonly DistributedIslandPlanInput[];
+}>;
+export type DistributedIslandPlanInput = Readonly<{
+    version: number;
+    id: string;
+    operation: string;
+    operationHash: string;
+    modulePath: string;
+    exportName: string;
+    source: Readonly<{
+        path: string;
+        line: number;
+        column: number;
+    }>;
+    directives: Readonly<{
+        load: boolean;
+        live: boolean;
+    }>;
+    liveCoverage: Readonly<{
+        requested: boolean;
+        finite: boolean;
+        kind: string;
+        maxItems?: number;
+    }>;
+    variableSchema: Readonly<{
+        reference: string;
+        codecVersion: number;
+        variables: readonly Readonly<{
+            name: string;
+            graphqlType: string;
+            defaultValue?: unknown;
+        }>[];
+    }>;
+}>;
+export type DistributedSvelteKitBoundaryOccurrence = Readonly<{
+    islandId: string;
+    operation: string;
+    modulePath: string;
+    exportName: string;
+    component: string;
+    graphqlSource: string;
+    reason: 'route_document' | 'static_component_import' | 'explicit';
+    conservative: boolean;
+    directives: Readonly<{
+        load: boolean;
+        live: boolean;
+    }>;
+    liveCoverage: DistributedIslandPlanInput['liveCoverage'];
+    binding: Readonly<{
+        version: 1;
+        id: string;
+        discovery: 'route_param' | 'empty' | 'explicit';
+        sources: Readonly<Record<string, DistributedBoundaryVariableSource>>;
+    }>;
+}>;
+export type DistributedSvelteKitBoundary = Readonly<{
+    id: string;
+    route: string;
+    kind: 'layout' | 'page';
+    source: string;
+    islands: readonly DistributedSvelteKitBoundaryOccurrence[];
+}>;
+export type DistributedSvelteKitBoundaryPlan = Readonly<{
+    version: number;
+    module: string;
+    schemaFingerprint: string;
+    protocolFingerprint: string;
+    boundaries: readonly DistributedSvelteKitBoundary[];
+    unplaced: readonly Readonly<{
+        islandId: string;
+        operation: string;
+        graphqlSource: string;
+    }>[];
+}>;
+export type DistributedSvelteKitBoundaryAnalysisClient = Readonly<{
+    module: string;
+    inventory: DistributedIslandInventory;
+    explicitBoundaries?: readonly DistributedSvelteKitBoundaryRegistration[];
+}>;
+export type DistributedSvelteKitBoundaryRegistration = Readonly<{
+    operation: string;
+    route: string;
+    kind: 'layout' | 'page';
+    variables?: Readonly<Record<string, DistributedBoundaryVariableSource>>;
+}>;
+export type DistributedSvelteKitBoundaryAnalysisOptions = Readonly<{
+    cwd: string;
+    routesDir?: string;
+    libDir?: string;
+    aliases?: Readonly<Record<string, string>>;
+    clients: readonly DistributedSvelteKitBoundaryAnalysisClient[];
+}>;
+/** 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
+ * 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[]>;