@hops-ops/distributed 4.9.0 → 4.10.0

package/dist/sveltekit/boundary-variables.d.ts

@@ -0,0 +1,57 @@
+import { type ReplicaOperationArtifact } from '../replica/index.js';
+import type { GraphqlVariables } from '../types.js';
+export type DistributedBoundaryVariableSource<TValue = unknown> = Readonly<{
+    kind: 'route_param';
+    name: string;
+}> | Readonly<{
+    kind: 'search_param';
+    name: string;
+    mode?: 'first' | 'all';
+}> | Readonly<{
+    kind: 'trusted_session';
+    path: readonly string[];
+}> | Readonly<{
+    kind: 'constant';
+    value: TValue;
+}> | Readonly<{
+    kind: 'forwarded_prop';
+    path: readonly string[];
+}> | Readonly<{
+    kind: 'omit';
+}>;
+export type DistributedBoundaryVariableSources<TVariables extends GraphqlVariables> = Readonly<{
+    [K in keyof TVariables]?: DistributedBoundaryVariableSource<TVariables[K]>;
+}>;
+export type DistributedBoundaryVariableContext<TSession = unknown, TProps = Readonly<Record<string, unknown>>> = Readonly<{
+    params: Readonly<Record<string, string | undefined>>;
+    search: URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
+    session: TSession | null;
+    props: TProps;
+}>;
+export type DistributedBoundaryBinding<TVariables extends GraphqlVariables, TSession = unknown, TProps = Readonly<Record<string, unknown>>> = Readonly<{
+    version: 1;
+    id: string;
+    artifactId: string;
+    sources: DistributedBoundaryVariableSources<TVariables>;
+    resolve(context: DistributedBoundaryVariableContext<TSession, TProps>): TVariables;
+    canonicalBytes(context: DistributedBoundaryVariableContext<TSession, TProps>): string;
+}>;
+export type DistributedBoundaryPlan = Readonly<{
+    operation: string;
+    route: string;
+    kind: 'layout' | 'page';
+    sourcePath?: string;
+    discovery: 'component' | 'route_document' | 'explicit';
+}>;
+export type DistributedBoundaryOperation<TData = unknown, TVariables extends GraphqlVariables = GraphqlVariables, TSession = unknown, TProps = Readonly<Record<string, unknown>>> = Readonly<{
+    plan: DistributedBoundaryPlan;
+    artifact: ReplicaOperationArtifact<TData, TVariables>;
+    binding: DistributedBoundaryBinding<TVariables, TSession, TProps>;
+}>;
+/**
+ * Define one closed, inspectable variable binding for every boundary lifecycle.
+ * The operation artifact remains the sole owner of coercion and cache identity.
+ */
+export declare function defineDistributedBoundaryBinding<TData, TVariables extends GraphqlVariables, TSession = unknown, TProps = Readonly<Record<string, unknown>>>(artifact: ReplicaOperationArtifact<TData, TVariables>, sources: DistributedBoundaryVariableSources<TVariables>): DistributedBoundaryBinding<TVariables, TSession, TProps>;
+export declare function defineDistributedBoundaryOperation<TData, TVariables extends GraphqlVariables, TSession = unknown, TProps = Readonly<Record<string, unknown>>>(plan: DistributedBoundaryPlan, artifact: ReplicaOperationArtifact<TData, TVariables>, binding: DistributedBoundaryBinding<TVariables, TSession, TProps>): DistributedBoundaryOperation<TData, TVariables, TSession, TProps>;
+export declare function resolveDistributedBoundaryVariables<TData, TVariables extends GraphqlVariables, TSession, TProps>(artifact: ReplicaOperationArtifact<TData, TVariables>, sources: DistributedBoundaryVariableSources<TVariables>, context: DistributedBoundaryVariableContext<TSession, TProps>): TVariables;

package/dist/sveltekit/boundary-variables.js

@@ -0,0 +1,290 @@
+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;
+    if (definitions === null || typeof definitions !== 'object' || Array.isArray(definitions)) {
+        throw new TypeError('Distributed boundary artifact has no variable codec');
+    }
+    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(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,8 @@
 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 { 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,8 @@
 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 { 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/islands/boundaries.d.ts

@@ -0,0 +1,104 @@
+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;
+        }>[];
+    }>;
+}>;
+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 code.
+ * The returned plan is deterministic and contains project-relative paths only.
+ */
+export declare function analyzeDistributedSvelteKitBoundaries(options: DistributedSvelteKitBoundaryAnalysisOptions): Promise<readonly DistributedSvelteKitBoundaryPlan[]>;