@hops-ops/distributed 4.8.0 → 4.10.0

package/dist/sveltekit/lifecycle.d.ts

@@ -0,0 +1,57 @@
+import type { DistributedReplica, ReplicaDehydratedState } from '../replica/index.js';
+export type DistributedReloadStateDeclaration = Readonly<{
+    /** Stable application-owned partition name. */
+    key: string;
+    /** Changes when the serialized representation becomes incompatible. */
+    fingerprint: string;
+    capture(): unknown;
+    restore(value: unknown): void | Promise<void>;
+}>;
+export type DistributedReloadOptions = Readonly<{
+    /** Compiler-owned surface key; generated clients provide this automatically. */
+    key: string;
+    /** Explicitly declared serializable application state. Nothing else is captured. */
+    state?: readonly DistributedReloadStateDeclaration[];
+    /** Recover ambiguous receipts by ID; commands are never replayed by the framework. */
+    recoverPendingCommands?: (commandIds: readonly string[]) => void | Promise<void>;
+}>;
+type ReloadParticipant = Readonly<{
+    key: string;
+    prepare(): Readonly<{
+        replica?: ReplicaDehydratedState;
+        pendingCommandIds: readonly string[];
+        state: readonly Readonly<{
+            key: string;
+            fingerprint: string;
+            value: unknown;
+        }>[];
+    }>;
+    /** Return false when restoration is valid but must be retried later. */
+    restore(value: ReloadParticipantCapsule, compatible: boolean): boolean | Promise<boolean>;
+}>;
+type ReloadParticipantCapsule = Readonly<{
+    key: string;
+    replica?: ReplicaDehydratedState;
+    pendingCommandIds: readonly string[];
+    state: readonly Readonly<{
+        key: string;
+        fingerprint: string;
+        value: unknown;
+    }>[];
+}>;
+export interface DistributedReloadLifecycle {
+    assertDispatchOpen(): void;
+    register(participant: ReloadParticipant): () => void;
+    destroy(): void;
+}
+/** Validate one explicitly declared application-state partition before capture. */
+export declare function validateDistributedReloadState(value: unknown, path?: string): unknown;
+/** Preserve browser location only when it cannot copy an auth callback secret. */
+export declare function validateDistributedReloadLocation(location: URL): string;
+/** Register one generated client with the shared browser reload transaction. */
+export declare function registerDistributedReloadClient(replica: DistributedReplica, runtime: Readonly<{
+    pendingCommandIds?(): readonly string[];
+}> | undefined, options: DistributedReloadOptions): () => void;
+/** Browser singleton used by every generated SvelteKit surface in one page. */
+export declare function distributedReloadLifecycle(): DistributedReloadLifecycle;
+export {};

package/dist/sveltekit/lifecycle.js

@@ -0,0 +1,454 @@
+const STATE_ENDPOINT = '/__distributed/lifecycle';
+const CAPSULE_KEY = '@hops-ops/distributed/reload-capsule/v1';
+const GENERATION_META = 'distributed-generation';
+const MAX_CAPSULE_BYTES = 1024 * 1024;
+const MAX_STATE_DEPTH = 32;
+const PARTICIPANT_ID = /^[A-Za-z0-9_-]{16,128}$/;
+const SECRET_KEY = /(?:authorization|cookie|password|secret|token|credential)/i;
+const AUTH_QUERY_KEY = /^(?:code|samlresponse|session|state)$/i;
+const STATE_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const RESTORE_TIMEOUT_MS = 3_000;
+const CAPSULE_MIN_LIFETIME_MS = 30_000;
+// Preparation is followed by a bounded process-readiness transaction. Keep
+// the capsule alive through the CLI's 90-second aggregate readiness budget,
+// restoration, and ordinary browser scheduling delay.
+const CAPSULE_ACTIVATION_GRACE_MS = 120_000;
+/** Validate one explicitly declared application-state partition before capture. */
+export function validateDistributedReloadState(value, path = 'reloadState') {
+    assertSafeSerializable(value, path, 0, new Set(), true);
+    const encoded = JSON.stringify(value);
+    if (new TextEncoder().encode(encoded).length > MAX_CAPSULE_BYTES) {
+        throw new TypeError(`${path} exceeds 1 MiB`);
+    }
+    return value;
+}
+/** Preserve browser location only when it cannot copy an auth callback secret. */
+export function validateDistributedReloadLocation(location) {
+    const parameters = [location.searchParams];
+    if (location.hash.length > 1) {
+        parameters.push(new URLSearchParams(location.hash.slice(1)));
+    }
+    for (const key of parameters.flatMap((candidate) => [...candidate.keys()])) {
+        if (SECRET_KEY.test(key) || AUTH_QUERY_KEY.test(key)) {
+            throw new TypeError(`reload location parameter ${key} is auth-secret-like`);
+        }
+    }
+    return `${location.pathname}${location.search}${location.hash}`;
+}
+/** Register one generated client with the shared browser reload transaction. */
+export function registerDistributedReloadClient(replica, runtime, options) {
+    const state = new Map((options.state ?? []).map((declaration) => {
+        identity(declaration.key, 'reload state key');
+        identity(declaration.fingerprint, 'reload state fingerprint');
+        if (!STATE_KEY.test(declaration.key) || declaration.key.includes('..')) {
+            throw new TypeError('Distributed reload state keys must be distinct portable names');
+        }
+        return [declaration.key, declaration];
+    }));
+    if (state.size !== (options.state ?? []).length) {
+        throw new TypeError('duplicate Distributed reload state declaration');
+    }
+    return distributedReloadLifecycle().register(Object.freeze({
+        key: identity(options.key, 'reload participant key'),
+        prepare() {
+            const application = [...state.values()].map((declaration) => {
+                const value = declaration.capture();
+                validateDistributedReloadState(value, `reloadState.${declaration.key}`);
+                return Object.freeze({
+                    key: declaration.key,
+                    fingerprint: declaration.fingerprint,
+                    value
+                });
+            });
+            const dehydrated = replica.scope === undefined ? undefined : replica.dehydrate();
+            return Object.freeze({
+                ...(dehydrated === undefined ? {} : { replica: dehydrated }),
+                pendingCommandIds: runtime?.pendingCommandIds?.() ?? Object.freeze([]),
+                state: Object.freeze(application)
+            });
+        },
+        async restore(saved, compatible) {
+            // A client-only application learns its replica authority from its first
+            // query. Retain the capsule until that authority exists instead of
+            // treating a skipped compatible hydrate as successful restoration.
+            if (compatible && saved.replica !== undefined && replica.scope === undefined) {
+                return false;
+            }
+            const replicaCaptured = saved.replica !== undefined;
+            let replicaRestored = saved.replica === undefined;
+            if (compatible && saved.replica !== undefined && replica.scope !== undefined) {
+                replicaRestored = replica.hydrate(saved.replica, replica.scope);
+            }
+            for (const candidate of saved.state) {
+                const declaration = state.get(candidate.key);
+                if (declaration?.fingerprint === candidate.fingerprint) {
+                    await declaration.restore(candidate.value);
+                }
+            }
+            if (saved.pendingCommandIds.length > 0) {
+                await options.recoverPendingCommands?.(saved.pendingCommandIds);
+            }
+            window.dispatchEvent(new CustomEvent('distributed:reload-restored', {
+                detail: Object.freeze({
+                    key: options.key,
+                    replicaCaptured,
+                    replicaRestored,
+                    pendingCommandIds: saved.pendingCommandIds
+                })
+            }));
+            return true;
+        }
+    }));
+}
+let sharedLifecycle;
+// Schedule from the completed request, leaving a full idle window between
+// heartbeats. Besides reducing background work, this preserves browser tooling
+// that defines network-idle as 500 ms without an in-flight request.
+const LIFECYCLE_POLL_INTERVAL_MS = 1_000;
+/** Browser singleton used by every generated SvelteKit surface in one page. */
+export function distributedReloadLifecycle() {
+    if (sharedLifecycle === undefined) {
+        try {
+            sharedLifecycle = createDistributedReloadLifecycle();
+        }
+        catch {
+            // Storage and Web Crypto are optional browser capabilities. Losing
+            // them disables coherent reload state transfer, not the application.
+            sharedLifecycle = inertLifecycle();
+        }
+    }
+    return sharedLifecycle;
+}
+function createDistributedReloadLifecycle() {
+    if (typeof window === 'undefined')
+        return inertLifecycle();
+    const participants = new Map();
+    const participantId = browserParticipantId();
+    let blocked = false;
+    let destroyed = false;
+    let preparing;
+    let reloadRequested = false;
+    let loadedGenerationId = documentGenerationId();
+    let timer;
+    let restoration = Promise.resolve();
+    const queueRestoration = (active) => {
+        const requested = restoration.then(() => restoreAvailableParticipants(participants, active));
+        // Keep the queue usable after a storage/restore failure while returning
+        // the real result to the caller that owns this attempt.
+        restoration = requested.catch(() => undefined);
+        return requested;
+    };
+    const poll = async () => {
+        if (destroyed)
+            return;
+        try {
+            const response = await fetch(STATE_ENDPOINT, {
+                headers: { 'x-distributed-participant': participantId },
+                cache: 'no-store',
+                credentials: 'same-origin'
+            });
+            if (response.status === 404) {
+                blocked = false;
+                return;
+            }
+            if (!response.ok)
+                throw new Error(`lifecycle state returned ${response.status}`);
+            const state = parseLifecycleState(await response.json());
+            // The Vite lifecycle integration stamps the generation that served this
+            // document into its HTML. Fall back to the first observed active state for
+            // consumers that mount the lifecycle client without that integration.
+            loadedGenerationId ??= state.active.generationId;
+            if (state.phase === 'preparing' && state.pending !== undefined && state.transitionId !== undefined) {
+                blocked = true;
+                if (preparing !== state.transitionId) {
+                    preparing = state.transitionId;
+                    window.dispatchEvent(new CustomEvent('distributed:reload-preparing', {
+                        detail: Object.freeze({
+                            transitionId: state.transitionId,
+                            fromGenerationId: state.active.generationId,
+                            toGenerationId: state.pending.generationId
+                        })
+                    }));
+                    await prepareReload(state, participantId, participants);
+                }
+                return;
+            }
+            if (state.active.generationId !== loadedGenerationId) {
+                blocked = true;
+                if (!reloadRequested) {
+                    reloadRequested = true;
+                    markCapsuleRestoring();
+                    window.location.reload();
+                }
+                return;
+            }
+            preparing = undefined;
+            blocked = false;
+            await queueRestoration(state.active);
+        }
+        catch {
+            // A missing/failed lifecycle side channel cannot authorize dispatch
+            // during an already-observed transition.
+            if (preparing !== undefined)
+                blocked = true;
+        }
+        finally {
+            if (!destroyed)
+                timer = setTimeout(() => void poll(), LIFECYCLE_POLL_INTERVAL_MS);
+        }
+    };
+    void poll();
+    return Object.freeze({
+        assertDispatchOpen() {
+            if (blocked)
+                throw new Error('coherent application reload is in progress');
+        },
+        register(participant) {
+            participants.set(participant.key, participant);
+            void queueRestoration().catch(() => undefined);
+            return () => {
+                if (participants.get(participant.key) === participant) {
+                    participants.delete(participant.key);
+                }
+            };
+        },
+        destroy() {
+            destroyed = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            participants.clear();
+        }
+    });
+}
+async function prepareReload(state, participantId, participants) {
+    try {
+        const now = Date.now();
+        const capsule = Object.freeze({
+            version: 1,
+            transitionId: state.transitionId,
+            from: state.active,
+            to: state.pending,
+            location: validateDistributedReloadLocation(new URL(window.location.href)),
+            createdAtUnixMs: now,
+            expiresAtUnixMs: Math.max(now + CAPSULE_MIN_LIFETIME_MS, state.deadlineUnixMs + CAPSULE_ACTIVATION_GRACE_MS),
+            phase: 'prepared',
+            participants: Object.freeze([...participants.values()]
+                .sort((left, right) => left.key.localeCompare(right.key))
+                .map((participant) => Object.freeze({ key: participant.key, ...participant.prepare() })))
+        });
+        storeCapsule(capsule);
+        await acknowledge(state.transitionId, participantId, true);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'unknown preparation failure';
+        console.error('Distributed reload preparation failed:', message);
+        window.dispatchEvent(new CustomEvent('distributed:reload-prepare-failed', {
+            detail: Object.freeze({ transitionId: state.transitionId, message })
+        }));
+        await acknowledge(state.transitionId, participantId, false);
+    }
+}
+async function acknowledge(transitionId, participantId, ok) {
+    const response = await fetch(STATE_ENDPOINT, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        credentials: 'same-origin',
+        body: JSON.stringify({ transitionId, participantId, ok })
+    });
+    if (!response.ok)
+        throw new Error(`lifecycle acknowledgement returned ${response.status}`);
+}
+async function restoreAvailableParticipants(participants, active) {
+    const capsule = readCapsule();
+    if (capsule === undefined ||
+        capsule.phase !== 'restoring' ||
+        (active !== undefined && capsule.to.generationId !== active.generationId))
+        return;
+    const remaining = [];
+    const compatible = capsule.from.compatibilityId === capsule.to.compatibilityId;
+    for (const saved of capsule.participants) {
+        const participant = participants.get(saved.key);
+        if (participant === undefined) {
+            remaining.push(saved);
+            continue;
+        }
+        try {
+            const restored = await withDeadline(Promise.resolve(participant.restore(saved, compatible)), Math.min(RESTORE_TIMEOUT_MS, Math.max(1, capsule.expiresAtUnixMs - Date.now())));
+            if (!restored)
+                remaining.push(saved);
+        }
+        catch {
+            // Incompatible partitions are intentionally dropped; the mounted
+            // operation stores perform their ordinary authoritative fetch.
+        }
+    }
+    if (remaining.length === 0) {
+        sessionStorage.removeItem(CAPSULE_KEY);
+    }
+    else {
+        storeCapsule(Object.freeze({ ...capsule, participants: Object.freeze(remaining) }));
+    }
+}
+function withDeadline(operation, timeoutMs) {
+    return new Promise((resolvePromise, reject) => {
+        const timer = setTimeout(() => reject(new Error('Distributed reload restoration timed out')), timeoutMs);
+        operation.then((value) => {
+            clearTimeout(timer);
+            resolvePromise(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+function storeCapsule(capsule) {
+    assertSafeSerializable(capsule, 'reloadCapsule', 0, new Set(), false);
+    const encoded = JSON.stringify(capsule);
+    if (new TextEncoder().encode(encoded).length > MAX_CAPSULE_BYTES) {
+        throw new TypeError('Distributed reload capsule exceeds 1 MiB');
+    }
+    sessionStorage.setItem(CAPSULE_KEY, encoded);
+}
+function readCapsule() {
+    const encoded = sessionStorage.getItem(CAPSULE_KEY);
+    if (encoded === null || new TextEncoder().encode(encoded).length > MAX_CAPSULE_BYTES)
+        return undefined;
+    try {
+        const value = JSON.parse(encoded);
+        if (value.version !== 1 || value.expiresAtUnixMs < Date.now()) {
+            sessionStorage.removeItem(CAPSULE_KEY);
+            return undefined;
+        }
+        return value;
+    }
+    catch {
+        sessionStorage.removeItem(CAPSULE_KEY);
+        return undefined;
+    }
+}
+function markCapsuleRestoring() {
+    const capsule = readCapsule();
+    if (capsule !== undefined)
+        storeCapsule(Object.freeze({ ...capsule, phase: 'restoring' }));
+}
+function parseLifecycleState(value) {
+    const state = object(value, 'lifecycle');
+    if (state.schemaVersion !== 1 || (state.phase !== 'active' && state.phase !== 'preparing')) {
+        throw new TypeError('invalid Distributed lifecycle state');
+    }
+    const active = parseLifecycleGeneration(state.active, 'lifecycle.active');
+    const pending = state.pending === undefined
+        ? undefined
+        : parseLifecycleGeneration(state.pending, 'lifecycle.pending');
+    const transitionId = state.transitionId === undefined
+        ? undefined
+        : identity(state.transitionId, 'lifecycle.transitionId');
+    const deadlineUnixMs = state.deadlineUnixMs === undefined
+        ? undefined
+        : finiteInteger(state.deadlineUnixMs, 'lifecycle.deadlineUnixMs');
+    if (state.phase === 'preparing' && (pending === undefined || transitionId === undefined || deadlineUnixMs === undefined)) {
+        throw new TypeError('preparing lifecycle state is incomplete');
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        phase: state.phase,
+        active,
+        ...(pending === undefined ? {} : { pending }),
+        ...(transitionId === undefined ? {} : { transitionId }),
+        ...(deadlineUnixMs === undefined ? {} : { deadlineUnixMs })
+    });
+}
+function parseLifecycleGeneration(value, path) {
+    const generation = object(value, path);
+    return Object.freeze({
+        generationId: identity(generation.generationId, `${path}.generationId`),
+        releaseId: identity(generation.releaseId, `${path}.releaseId`),
+        topologyId: identity(generation.topologyId, `${path}.topologyId`),
+        compatibilityId: identity(generation.compatibilityId, `${path}.compatibilityId`)
+    });
+}
+function browserParticipantId() {
+    const key = '@hops-ops/distributed/reload-participant/v1';
+    const existing = sessionStorage.getItem(key);
+    if (existing !== null && PARTICIPANT_ID.test(existing))
+        return existing;
+    // `crypto.randomUUID()` is restricted to secure contexts, while
+    // `getRandomValues()` is intentionally available on ordinary HTTP origins.
+    // Local GitOps and LAN development commonly serve Vite through an HTTP
+    // service hostname, so requiring randomUUID would silently disable the
+    // lifecycle client there.
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    const created = [...bytes]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+    sessionStorage.setItem(key, created);
+    return created;
+}
+function documentGenerationId() {
+    if (typeof document === 'undefined')
+        return undefined;
+    const candidate = document
+        .querySelector(`meta[name="${GENERATION_META}"]`)
+        ?.getAttribute('content');
+    if (candidate === null || candidate === undefined)
+        return undefined;
+    try {
+        return identity(candidate, 'document generation');
+    }
+    catch {
+        return undefined;
+    }
+}
+function inertLifecycle() {
+    return Object.freeze({
+        assertDispatchOpen() { },
+        register() {
+            return () => undefined;
+        },
+        destroy() { }
+    });
+}
+function object(value, path) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError(`${path} must be an object`);
+    }
+    return value;
+}
+function identity(value, path) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 512 || value !== value.trim() || /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new TypeError(`${path} must be a bounded stable identity`);
+    }
+    return value;
+}
+function finiteInteger(value, path) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`${path} must be a non-negative safe integer`);
+    }
+    return value;
+}
+function assertSafeSerializable(value, path, depth, seen, rejectSecretKeys) {
+    if (depth > MAX_STATE_DEPTH)
+        throw new TypeError(`${path} exceeds maximum depth`);
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return;
+    if (typeof value !== 'object')
+        throw new TypeError(`${path} is not JSON serializable`);
+    if (seen.has(value))
+        throw new TypeError(`${path} contains a cycle`);
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            assertSafeSerializable(value[index], `${path}[${index}]`, depth + 1, seen, rejectSecretKeys);
+        }
+    }
+    else {
+        for (const [key, child] of Object.entries(value)) {
+            if (rejectSecretKeys && SECRET_KEY.test(key))
+                throw new TypeError(`${path}.${key} is secret-like state`);
+            assertSafeSerializable(child, `${path}.${key}`, depth + 1, seen, rejectSecretKeys);
+        }
+    }
+    seen.delete(value);
+}

package/dist/sveltekit/operation-identity.d.ts

@@ -0,0 +1,4 @@
+import type { ReplicaOperationArtifact } from '../replica/index.js';
+import type { GraphqlVariables } from '../types.js';
+/** Build the canonical identity shared by SSR scheduling and browser retention. */
+export declare function boundaryOperationIdentity(artifact: ReplicaOperationArtifact<unknown, GraphqlVariables>, variables: GraphqlVariables): string;

package/dist/sveltekit/operation-identity.js

@@ -0,0 +1,10 @@
+/** Build the canonical identity shared by SSR scheduling and browser retention. */
+export function boundaryOperationIdentity(artifact, variables) {
+    return JSON.stringify([
+        artifact.protocol.version,
+        artifact.protocol.schemaHash,
+        artifact.protocol.surface,
+        artifact.id,
+        variables
+    ]);
+}

package/dist/sveltekit/replica.d.ts

@@ -3,6 +3,9 @@ import type { GqlAuth, GqlError, GraphqlVariables } from '../types.js';
 import type { WebSocketConstructor } from '../websocket.js';
 import type { FetchLike } from '../request.js';
 import { type PageGraphqlData } from './auth.js';
+import { type DistributedBoundaryPlan, type DistributedBoundaryOperation, type DistributedBoundaryVariableSources, type DistributedBoundaryVariableContext } from './boundary-variables.js';
+import { type DistributedSvelteKitBoundaryInstance, type DistributedSvelteKitBoundaryLocation, type DistributedSvelteKitLocationContext, type SveltekitBoundaryLifecycleDiagnostic, type SveltekitBoundaryRetention } from './boundary-lifecycle.js';
+import { type DistributedReloadOptions } from './lifecycle.js';
 type UnknownCommandEntries = Readonly<Record<string, never>>;
 export type SveltekitSessionSource = Readonly<{
     /** Current credential. HTTP, WS, and commands all call this exact source. */
@@ -27,6 +30,8 @@ export type SveltekitReplicaHydration = Readonly<{
     version: 1;
     state: import('../replica/index.js').ReplicaDehydratedState;
     readonly operations?: readonly string[];
+    /** Exact variable-binding fingerprints used to create this SSR seed. */
+    readonly bindings?: readonly string[];
 }>;
 /**
  * Independently trusted SSR/session authority for one hydration transfer.
@@ -42,11 +47,11 @@ export type SveltekitDistributedPageData = PageGraphqlData & Readonly<{
     distributed?: SveltekitReplicaHydration;
     distributedAuthority?: SveltekitReplicaAuthority;
 }>;
-export type SveltekitCommandRuntimeLike<TCommands> = Pick<ReplicaCommandRuntime<UnknownCommandEntries>, 'dispose'> & Readonly<{
+export type SveltekitCommandRuntimeLike<TCommands> = Pick<ReplicaCommandRuntime<UnknownCommandEntries>, 'dispose' | 'pendingCommandIds'> & Readonly<{
     commands: TCommands;
 }>;
 export type SveltekitCommandRuntimeFactory<TCommands> = (replica: DistributedReplica, transport: ReplicaGraphqlTransport, options: SveltekitCommandRuntimeFactoryOptions) => SveltekitCommandRuntimeLike<TCommands>;
-export type SveltekitCommandRuntimeFactoryOptions = Pick<ReplicaCommandRuntimeOptions, 'diagnostics'>;
+export type SveltekitCommandRuntimeFactoryOptions = Pick<ReplicaCommandRuntimeOptions, 'diagnostics' | 'lifecycle'>;
 export type CreateDistributedSvelteKitOptions<TCommands = Readonly<Record<never, never>>> = Readonly<{
     session: SveltekitSessionSource;
     /** Same-origin `/graphql` by default. */
@@ -63,7 +68,13 @@ export type CreateDistributedSvelteKitOptions<TCommands = Readonly<Record<never,
     authority?: SveltekitReplicaAuthority;
     createCommands?: SveltekitCommandRuntimeFactory<TCommands>;
     replica?: Omit<DistributedReplicaOptions, 'transport'>;
+    /** Generated boundary operations accepted by this component-tree client. */
+    boundaries: readonly DistributedBoundaryOperation[];
+    /** Redacted structural lifecycle events for boundary ownership diagnostics. */
+    onBoundaryDiagnostic?: (event: SveltekitBoundaryLifecycleDiagnostic) => void;
     onAuthError?: (error: unknown) => void;
+    /** Generated clients supply the surface key; apps may declare safe state partitions. */
+    reload?: DistributedReloadOptions;
 }>;
 export type SveltekitQuerySnapshot<TData> = ReplicaSnapshot<TData> & Readonly<{
     loading: boolean;
@@ -107,12 +118,21 @@ export type SveltekitBoundOperation<TData, TVariables extends GraphqlVariables>
     read(variables: TVariables): ReplicaSnapshot<TData>;
     /** Client-side hover/nav warmup; no-ops when the replica already has a complete snapshot. */
     prefetch(variables: TVariables): Promise<void>;
+    /** One typed binding shared by SSR, navigation, prefetch, hydration, and live use. */
+    boundary<TSession = unknown, TProps = Readonly<Record<string, unknown>>>(plan: DistributedBoundaryPlan, sources: DistributedBoundaryVariableSources<TVariables>): DistributedBoundaryOperation<TData, TVariables, TSession, TProps>;
 }>;
 export type DistributedSvelteKitClient<TCommands> = Readonly<{
     replica: DistributedReplica;
     transport: ReplicaGraphqlTransport;
     commands: TCommands;
     operation<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>): SveltekitBoundOperation<TData, TVariables>;
+    boundary<TData, TVariables extends GraphqlVariables, TSession, TProps>(operation: DistributedBoundaryOperation<TData, TVariables, TSession, TProps>): SveltekitBoundBoundaryOperation<TData, TVariables, TSession, TProps>;
+    /** Retain every generated selection owned by one mounted page/layout instance. */
+    retainBoundary<TSession, TProps>(instance: DistributedSvelteKitBoundaryInstance, context: DistributedBoundaryVariableContext<TSession, TProps>): SveltekitBoundaryRetention;
+    /** Retain the nearest generated page/layout boundary at this location. */
+    retainLocation<TSession, TProps>(location: DistributedSvelteKitBoundaryLocation, context: DistributedSvelteKitLocationContext<TSession, TProps>): SveltekitBoundaryRetention;
+    /** Prefetch the generated page and owning layout selections for a target URL. */
+    prefetchLocation<TSession, TProps>(pathname: string, context: DistributedSvelteKitLocationContext<TSession, TProps>): Promise<void>;
     /**
      * Apply a server seed. A malformed or mismatched seed closes the old
      * generation and returns false so the bound operation refetches.
@@ -122,6 +142,13 @@ export type DistributedSvelteKitClient<TCommands> = Readonly<{
     invalidateAuthorization(): void;
     destroy(): void;
 }>;
+export type SveltekitBoundBoundaryOperation<TData, TVariables extends GraphqlVariables, TSession, TProps> = Readonly<{
+    operation: DistributedBoundaryOperation<TData, TVariables, TSession, TProps>;
+    variables(context: DistributedBoundaryVariableContext<TSession, TProps>): TVariables;
+    use(context: DistributedBoundaryVariableContext<TSession, TProps>, options?: UseSveltekitOperationOptions): SveltekitQueryStore<TData>;
+    read(context: DistributedBoundaryVariableContext<TSession, TProps>): ReplicaSnapshot<TData>;
+    prefetch(context: DistributedBoundaryVariableContext<TSession, TProps>): Promise<void>;
+}>;
 /**
  * Bind the framework-neutral replica to Svelte's readable-store lifecycle.
  *