@hops-ops/distributed 4.8.0 → 4.10.0

package/README.md

@@ -5,7 +5,7 @@ The generated, end-to-end typed client for
 
 Rust table, relationship, role, and command definitions produce one authorized
 client surface. `distributed client` combines that surface with application GraphQL
-documents and emits typed operations, live companions, route-load plans, and
+documents and emits typed operations, live companions, island metadata, and
 commands. This package executes those artifacts through one normalized,
 causally consistent browser replica.
 
@@ -67,7 +67,7 @@ injects wire-only identity and revision fields, and emits:
 - an exact typed operation and optional live companion;
 - normalization, identity, relationship, filter, order, and pagination plans;
 - the closed variable codec used before cache lookup or transport;
-- a static `@load` route registry;
+- framework-neutral island metadata plus an inspectable SvelteKit boundary plan;
 - an SSR-safe SvelteKit wrapper with static operation bindings and tree-local
   client/command access;
 - a nested command tree with input defaults, optimistic effects, and causal
@@ -100,7 +100,10 @@ export const distributedClients = [
     module: '$distributed',
     manifest: { args: serviceManifestArgs },
     surface: 'e2e-ui',
-    documents: ['src/routes/(app)/**/*.graphql'],
+    documents: [
+      'src/routes/(app)/**/*.graphql',
+      'src/lib/components/**/*.graphql'
+    ],
     out: 'src/lib/generated/distributed'
   },
   {
@@ -128,6 +131,13 @@ keeps ordinary application documents out of the admin tree; each trust boundary
 has its own Rust manifest entrypoint, generated directory, virtual module, and
 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.
+
 The Vite integration runs `distributed client` at startup/build, watches GraphQL
 documents, stages all surfaces, commits a rollback-capable multi-output
 transaction, then triggers one reload. It exposes the generated Svelte wrapper
@@ -194,11 +204,11 @@ import {
   createDistributedSvelteKitServer
 } from '@hops-ops/distributed/sveltekit';
 import {
-  DISTRIBUTED_ROUTE_OPERATIONS
+  DISTRIBUTED_BOUNDARY_OPERATIONS
 } from '$distributed';
 
 const distributed = createDistributedSvelteKitServer({
-  routes: DISTRIBUTED_ROUTE_OPERATIONS,
+  boundaries: DISTRIBUTED_BOUNDARY_OPERATIONS,
   getSession: ({ locals }) => locals.auth(),
   getRole: (session) => roleFromSession(session)
 });
@@ -212,15 +222,20 @@ authorization lifecycle. The generated module retains no client singleton:
 ```ts
 // src/routes/+layout.svelte
 import { browser } from '$app/environment';
+import { page } from '$app/state';
 import {
   createPageDataSessionSource
 } from '@hops-ops/distributed/sveltekit';
-import { provideDistributed } from '$distributed';
+import {
+  DISTRIBUTED_BOUNDARY_OPERATIONS,
+  provideDistributed
+} from '$distributed';
 
 let { data, children } = $props();
 const pageData = createPageDataSessionSource(data);
 
 const client = provideDistributed({
+  boundaries: DISTRIBUTED_BOUNDARY_OPERATIONS,
   browser,
   session: pageData.session,
   ...(data.distributed !== undefined &&
@@ -233,6 +248,26 @@ const client = provideDistributed({
 });
 
 $effect(() => pageData.set(data));
+
+$effect(() => {
+  const retained = client.retainLocation(
+    { id: 'active-page', pathname: page.url.pathname, kind: 'page' },
+    {
+      search: page.url.searchParams,
+      session: data.session,
+      props: data
+    }
+  );
+  return () => retained.release();
+});
+
+// A delegated link-hover handler can warm any generated target without an
+// operation-name switch or a second variable map.
+await client.prefetchLocation(target.pathname, {
+  search: target.searchParams,
+  session: data.session,
+  props: data
+});
 ```
 
 Route components import only their generated surface. Static operation wrappers
@@ -296,7 +331,10 @@ deduplicates work, and optionally maintains the generated live operation.
 `read()` is side-effect-free. `dehydrate()` and `hydrate()` transfer confirmed
 state without exposing a public storage schema. Cold `hydrate` seeds an empty
 client; warm same-scope `hydrate` merges so soft navigation cannot discard
-confirmed session data the next route did not re-dehydrate.
+confirmed session data the next boundary did not re-dehydrate. Layout
+retention survives child navigation, page retention is replaced on page exit,
+and exact layout/page duplicates share one replica watch until the final owner
+releases it.
 
 The replica stores normalized records and exact argument-sensitive indexes,
 not GraphQL response blobs. Generated selection metadata reconstructs each
@@ -423,7 +461,7 @@ duplicated as decision documents in this package.
   command runtime, query-plan helpers, and optional persistence.
 - `@hops-ops/distributed/diagnostics` — redacted support snapshots and artifact
   inspection.
-- `@hops-ops/distributed/sveltekit` — Svelte stores, SSR route loading,
+- `@hops-ops/distributed/sveltekit` — Svelte stores, island SSR composition,
   hydration, auth lifecycle, and tree-local generated bindings.
 - `@hops-ops/distributed/sveltekit/vite` — Node-only one-shot/check/watch
   generation, virtual module aliases, and GraphQL HTTP/WebSocket proxy helpers.

package/dist/generation.d.ts

@@ -0,0 +1,15 @@
+export type DistributedGenerationEnvelope = Readonly<{
+    version: 1;
+    generationId: string;
+    releaseId: string;
+    applicationId?: string;
+    clientId?: string;
+    schemaId?: string;
+    protocolId?: string;
+    topologyId?: string;
+    workerId?: string;
+    memberId?: string;
+    compatibilityId?: string;
+}>;
+/** Parse a generation envelope without trusting unbounded process metadata. */
+export declare function parseDistributedGenerationEnvelope(value: unknown, path?: string): DistributedGenerationEnvelope;

package/dist/generation.js

@@ -0,0 +1,41 @@
+/** Parse a generation envelope without trusting unbounded process metadata. */
+export function parseDistributedGenerationEnvelope(value, path = 'generation') {
+    const record = object(value, path);
+    if (record.version !== 1)
+        throw new TypeError(`${path}.version must be 1`);
+    const parsed = {
+        version: 1,
+        generationId: identity(record.generationId, `${path}.generationId`),
+        releaseId: identity(record.releaseId, `${path}.releaseId`)
+    };
+    for (const key of [
+        'applicationId',
+        'clientId',
+        'schemaId',
+        'protocolId',
+        'topologyId',
+        'workerId',
+        'memberId',
+        'compatibilityId'
+    ]) {
+        if (record[key] !== undefined)
+            parsed[key] = identity(record[key], `${path}.${key}`);
+    }
+    return Object.freeze(parsed);
+}
+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;
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export type { GqlAuth, GqlError, GqlErrorLocation, GqlResult, GraphqlVariables } from './types.js';
+export { parseDistributedGenerationEnvelope, type DistributedGenerationEnvelope } from './generation.js';
 export { DISTRIBUTED_PROTOCOL_VERSION, DistributedProtocolError, compareDistributedDecimal, distributedLiveResumeExtensions, parseDistributedProtocolEnvelope, parseGraphqlResponseExtensions, type DistributedDecimalString, type DistributedCommandConsistency, type DistributedCommandMetadata, type DistributedCommandState, type DistributedIndexRevision, type DistributedLiveCursor, type DistributedLiveMetadata, type DistributedLiveResumeExtensions, type DistributedOpaqueString, type DistributedProjectionExpectation, type DistributedProjectionObservation, type DistributedProtocolValue, type DistributedProtocolEnvelope, type DistributedProtocolErrorCode, type DistributedQuerySnapshot, type DistributedRecordRevision, type DistributedTrustedPreset, type DistributedTrustedPresetCodec, type GraphqlResponseExtensions } from './protocol.js';
 export { documentToString, type GqlDocument } from './document.js';
 export { applyWsDevHeaderParams, buildAuthHeaders, wsConnectionInitPayload } from './auth-headers.js';

package/dist/index.js

@@ -1,3 +1,4 @@
+export { parseDistributedGenerationEnvelope } from './generation.js';
 export { DISTRIBUTED_PROTOCOL_VERSION, DistributedProtocolError, compareDistributedDecimal, distributedLiveResumeExtensions, parseDistributedProtocolEnvelope, parseGraphqlResponseExtensions } from './protocol.js';
 export { documentToString } from './document.js';
 export { applyWsDevHeaderParams, buildAuthHeaders, wsConnectionInitPayload } from './auth-headers.js';

package/dist/protocol.d.ts

@@ -7,6 +7,7 @@
  * them, but never parses them as numbers or reconstructs server scopes.
  */
 import { type CommandProjectionMetadata } from './replica/projection-delta/index.js';
+import { type DistributedGenerationEnvelope } from './generation.js';
 /** The only Distributed GraphQL protocol version understood by this package. */
 export declare const DISTRIBUTED_PROTOCOL_VERSION: 1;
 declare const opaqueDistributedString: unique symbol;
@@ -125,6 +126,7 @@ export type DistributedProtocolEnvelope = Readonly<Record<string, unknown> & {
     schemaHash: string;
     authorizationGeneration: string;
     cacheScope: DistributedOpaqueString;
+    generation?: DistributedGenerationEnvelope;
     operation?: string;
     command?: DistributedCommandMetadata;
     snapshot?: DistributedQuerySnapshot;

package/dist/protocol.js

@@ -7,6 +7,7 @@
  * them, but never parses them as numbers or reconstructs server scopes.
  */
 import { parseCommandProjectionMetadata } from './replica/projection-delta/index.js';
+import { parseDistributedGenerationEnvelope } from './generation.js';
 /** The only Distributed GraphQL protocol version understood by this package. */
 export const DISTRIBUTED_PROTOCOL_VERSION = 1;
 /** Safe parse failure that reports structure, never hidden server values. */
@@ -82,6 +83,9 @@ export function parseDistributedProtocolEnvelope(value) {
     const schemaHash = publicString(envelope.schemaHash, 'extensions.distributed.schemaHash');
     const authorizationGeneration = publicString(envelope.authorizationGeneration, 'extensions.distributed.authorizationGeneration');
     const cacheScope = opaqueString(envelope.cacheScope, 'extensions.distributed.cacheScope');
+    const generation = envelope.generation === undefined
+        ? undefined
+        : parseDistributedGenerationEnvelope(envelope.generation, 'extensions.distributed.generation');
     const operation = envelope.operation === undefined
         ? undefined
         : publicString(envelope.operation, 'extensions.distributed.operation');
@@ -102,6 +106,7 @@ export function parseDistributedProtocolEnvelope(value) {
         schemaHash,
         authorizationGeneration,
         cacheScope,
+        ...(generation === undefined ? {} : { generation }),
         ...(operation === undefined ? {} : { operation }),
         ...(command === undefined ? {} : { command }),
         ...(snapshot === undefined ? {} : { snapshot }),

package/dist/replica/command-runtime/create.js

@@ -372,6 +372,14 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
         if (disposed) {
             throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_DISPOSED');
         }
+        try {
+            options.lifecycle?.assertDispatchOpen();
+        }
+        catch (error) {
+            throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_RELOADING', {
+                cause: error
+            });
+        }
         const snapshot = authoritySnapshot();
         const scope = snapshot.scope;
         if (scope === undefined ||
@@ -1088,6 +1096,9 @@ export function createReplicaCommandRuntime(replica, transport, entries, options
     return Object.freeze({
         commands: commands,
         observeResult,
+        pendingCommandIds() {
+            return Object.freeze([...new Set([...pending.keys(), ...unmanagedLayers])].sort());
+        },
         dispose() {
             if (disposed)
                 return;

package/dist/replica/command-runtime/errors.js

@@ -14,6 +14,8 @@ export function commandRuntimeErrorMessage(code) {
             return 'Command response violated the generated protocol contract';
         case 'REPLICA_COMMAND_REJECTED':
             return 'Command was rejected';
+        case 'REPLICA_COMMAND_RELOADING':
+            return 'Command dispatch is paused during a coherent application reload';
         case 'REPLICA_COMMAND_SCOPE_INVALIDATED':
             return 'Command authorization scope changed';
         case 'REPLICA_COMMAND_STATUS_UNAVAILABLE':

package/dist/replica/command-runtime/types.d.ts

@@ -154,7 +154,7 @@ export type ReplicaCommandCallOptions<TOutput> = PrepareReplicaCommandOptions &
     transportRetries?: number;
     onSucceeded?: (receipt: ReplicaCommandReceipt<TOutput>) => void | Promise<void>;
 }>;
-export type ReplicaCommandRuntimeErrorCode = 'REPLICA_COMMAND_ABORTED' | 'REPLICA_COMMAND_AUTHORITY_UNAVAILABLE' | 'REPLICA_COMMAND_DISPOSED' | 'REPLICA_COMMAND_OUTCOME_PENDING' | 'REPLICA_COMMAND_PROJECTION_FAILED' | 'REPLICA_COMMAND_PROTOCOL_INVALID' | 'REPLICA_COMMAND_REJECTED' | 'REPLICA_COMMAND_SCOPE_INVALIDATED' | 'REPLICA_COMMAND_STATUS_UNAVAILABLE' | 'REPLICA_COMMAND_TRANSPORT_AMBIGUOUS';
+export type ReplicaCommandRuntimeErrorCode = 'REPLICA_COMMAND_ABORTED' | 'REPLICA_COMMAND_AUTHORITY_UNAVAILABLE' | 'REPLICA_COMMAND_DISPOSED' | 'REPLICA_COMMAND_OUTCOME_PENDING' | 'REPLICA_COMMAND_PROJECTION_FAILED' | 'REPLICA_COMMAND_PROTOCOL_INVALID' | 'REPLICA_COMMAND_REJECTED' | 'REPLICA_COMMAND_RELOADING' | 'REPLICA_COMMAND_SCOPE_INVALIDATED' | 'REPLICA_COMMAND_STATUS_UNAVAILABLE' | 'REPLICA_COMMAND_TRANSPORT_AMBIGUOUS';
 export type AnyCommandArtifact = ReplicaCommandArtifact<unknown, unknown>;
 export type CommandEntry = AnyCommandArtifact | Readonly<{
     artifact: AnyCommandArtifact;
@@ -188,6 +188,10 @@ export type ReplicaCommandRuntimeOptions = Readonly<{
      * Generated clients ship their inventory; apps do not invent board sims ad hoc.
      */
     pureFunctions?: Readonly<Record<string, ReplicaPureFunction>>;
+    /** Framework lifecycle fence checked immediately before command preparation. */
+    lifecycle?: Readonly<{
+        assertDispatchOpen(): void;
+    }>;
 }>;
 export interface ReplicaCommandRuntime<TEntries extends Readonly<Record<string, CommandEntry>>> {
     readonly commands: ReplicaBoundCommands<TEntries>;
@@ -198,6 +202,8 @@ export interface ReplicaCommandRuntime<TEntries extends Readonly<Record<string,
      * it does not normalize or confirm cache data itself.
      */
     observeResult(envelope: ReplicaResultEnvelope<unknown>): void;
+    /** Opaque receipt identities safe to carry across a controlled reload. */
+    pendingCommandIds(): readonly string[];
     dispose(): void;
 }
 export type CapturedAuthority = Readonly<{

package/dist/replica/distributed-replica/impl-protocol.d.ts

@@ -34,6 +34,7 @@ export type ProtocolHost = {
     setProtocolGeneration(value: ProtocolGeneration | undefined): void;
     getProtocolGenerationSequence(): number;
     bumpProtocolGenerationSequence(): void;
+    disposeAuthorizationGeneration(): void;
     getTrustedPresets(): readonly DistributedTrustedPreset[];
     setTrustedPresets(value: readonly DistributedTrustedPreset[]): void;
     getCommandAuthorityContract(): RegisteredCommandAuthorityContract | undefined;

package/dist/replica/distributed-replica/impl-protocol.js

@@ -107,6 +107,7 @@ export function purgeProtocolGeneration(host) {
 }
 export function closeAuthorizationGeneration(host) {
     host.bumpProtocolGenerationSequence();
+    host.disposeAuthorizationGeneration();
     host.abortAuthorization();
     host.closeActiveTransports();
 }

package/dist/replica/distributed-replica/impl.js

@@ -22,6 +22,7 @@ export class DistributedReplicaImpl {
     #engine;
     #transport;
     #reportObserverError;
+    #onAuthorizationGenerationDispose;
     #diagnostics;
     #diagnosticLayers;
     #inFlight = new Map();
@@ -68,6 +69,8 @@ export class DistributedReplicaImpl {
     constructor(options = {}) {
         this.#transport = options.transport;
         this.#reportObserverError = options.onObserverError ?? reportUnhandledObserverError;
+        this.#onAuthorizationGenerationDispose =
+            options.onAuthorizationGenerationDispose;
         this.#diagnostics = options.diagnostics;
         this.#diagnosticLayers =
             options.diagnostics === undefined ? undefined : new Map();
@@ -209,6 +212,14 @@ export class DistributedReplicaImpl {
             bumpProtocolGenerationSequence: () => {
                 self.#protocolGenerationSequence += 1;
             },
+            disposeAuthorizationGeneration: () => {
+                try {
+                    self.#onAuthorizationGenerationDispose?.();
+                }
+                catch (error) {
+                    self._reportObserverErrors([error]);
+                }
+            },
             getTrustedPresets: () => self.#trustedPresets,
             setTrustedPresets: (value) => {
                 self.#trustedPresets = value;

package/dist/replica/distributed-replica/watch.js

@@ -11,6 +11,7 @@ export class ReplicaWatchState {
     #snapshot;
     #identitySignature;
     #destroyed = false;
+    #autoFetchScheduled = false;
     #unregister;
     constructor(owner, artifact, variables, options) {
         this.#owner = owner;
@@ -57,7 +58,8 @@ export class ReplicaWatchState {
         if (this.#destroyed)
             return;
         this.materialized = materialized;
-        this.#sync(true);
+        this.#sync(false);
+        this.#scheduleAutoFetch();
     }
     _stateChanged(allowFetch) {
         if (this.#destroyed)
@@ -92,4 +94,14 @@ export class ReplicaWatchState {
         if (allowFetch)
             void this.#owner._fetch(this, false);
     }
+    #scheduleAutoFetch() {
+        if (this.#autoFetchScheduled || this.#destroyed)
+            return;
+        this.#autoFetchScheduled = true;
+        queueMicrotask(() => {
+            this.#autoFetchScheduled = false;
+            if (!this.#destroyed)
+                void this.#owner._fetch(this, false);
+        });
+    }
 }

package/dist/replica/index.d.ts

@@ -17,6 +17,6 @@ export { compareReplicaOrder, decideReplicaPaginationMaintenance, evaluateReplic
 export { createReplicaIndexMaintenanceRegistry, formatReplicaIndexStaleReason } from './index-maintenance.js';
 export type { ReplicaIndexDependencyChange, ReplicaIndexMaintenanceDecision, ReplicaIndexMaintenanceIndex, ReplicaIndexMaintenanceReason, ReplicaIndexMaintenanceReasonCode, ReplicaIndexMaintenanceRecord, ReplicaIndexMaintenanceRegistry, ReplicaIndexMaintenanceSnapshot, ReplicaIndexPlanRegistration, ReplicaIndexRecordChange, ReplicaIndexRelationshipChange, ReplicaIndexSemanticChange, ReplicaIndexSemanticLayer } from './index-maintenance.js';
 export type { ReplicaFilterEvaluation, ReplicaFilterEvaluationOptions, ReplicaOrderComparison, ReplicaPaginationChange, ReplicaPaginationMaintenanceDecision, ReplicaQueryPlanPath, ReplicaQueryPlanReason, ReplicaQueryPlanReasonCode, ReplicaRelationshipFilterRequest } from './query-plan.js';
-export type { DistributedReplicaOptions, DistributedReplica, ReplicaArgumentsArtifact, ReplicaArgumentValue, ReplicaAuthoritativeScope, ReplicaBaseWriter, ReplicaBranchSemantic, ReplicaClientSurface, ReplicaCoverageArtifact, ReplicaDehydratedState, ReplicaFilterArtifact, ReplicaFilterExpression, ReplicaFilterFieldArtifact, ReplicaFilterLiteral, ReplicaFilterOperand, ReplicaFilterOperator, ReplicaIdentity, ReplicaIndexCoverage, ReplicaIndexInspection, ReplicaIndexTarget, ReplicaListValue, ReplicaLiveObserver, ReplicaLiveState, ReplicaLiteralValue, ReplicaModelArtifact, ReplicaObjectBranch, ReplicaObjectMember, ReplicaObjectSelection, ReplicaObjectValue, ReplicaOperationArtifact, ReplicaOperationSourceLocation, ReplicaOperationProtocol, ReplicaOrderArtifact, ReplicaOrderFieldArtifact, ReplicaOrderTieBreakerArtifact, ReplicaOptimisticWriter, ReplicaPaginationArtifact, ReplicaPaginationDisposition, ReplicaProtocolOperationArtifact, ReplicaRecordInspection, ReplicaRecordPatch, ReplicaRevalidationPlan, ReplicaRevalidationRelationship, ReplicaRevision, ReplicaRelationshipArtifact, ReplicaRelationshipKeyMapping, ReplicaRelationshipKind, ReplicaResultEnvelope, ReplicaRowPolicyArtifact, ReplicaRootSelection, ReplicaScalarSelection, ReplicaSelectionStorage, ReplicaSparse, ReplicaSnapshot, ReplicaStatus, ReplicaTransport, ReplicaTransportRequest, ReplicaVariableValue, ReplicaVariableCodecArtifact, ReplicaVariableEnumInputRef, ReplicaVariableFilterInputDefinition, ReplicaVariableFilterInputField, ReplicaVariableFilterInputRelationship, ReplicaVariableFilterInputTarget, ReplicaVariableInputDefinition, ReplicaVariableInputRef, ReplicaVariableListInputRef, ReplicaVariableNamedInputRef, ReplicaVariableOrderInputDefinition, ReplicaVariableOrderInputField, ReplicaVariableScalarInputRef, ReplicaValue, ReplicaWatch, ReplicaWriteSource, WatchReplicaOptions } from './types.js';
+export type { DistributedReplicaOptions, DistributedReplica, ReplicaArgumentsArtifact, ReplicaArgumentValue, ReplicaAuthoritativeScope, ReplicaBaseWriter, ReplicaBranchSemantic, ReplicaClientSurface, ReplicaCoverageArtifact, ReplicaDehydratedState, ReplicaFilterArtifact, ReplicaFilterExpression, ReplicaFilterFieldArtifact, ReplicaFilterLiteral, ReplicaFilterOperand, ReplicaFilterOperator, ReplicaIdentity, ReplicaIndexCoverage, ReplicaIndexInspection, ReplicaIndexTarget, ReplicaIslandMetadata, ReplicaIslandOperation, ReplicaListValue, ReplicaLiveObserver, ReplicaLiveState, ReplicaLiteralValue, ReplicaModelArtifact, ReplicaObjectBranch, ReplicaObjectMember, ReplicaObjectSelection, ReplicaObjectValue, ReplicaOperationArtifact, ReplicaOperationSourceLocation, ReplicaOperationProtocol, ReplicaOrderArtifact, ReplicaOrderFieldArtifact, ReplicaOrderTieBreakerArtifact, ReplicaOptimisticWriter, ReplicaPaginationArtifact, ReplicaPaginationDisposition, ReplicaProtocolOperationArtifact, ReplicaRecordInspection, ReplicaRecordPatch, ReplicaRevalidationPlan, ReplicaRevalidationRelationship, ReplicaRevision, ReplicaRelationshipArtifact, ReplicaRelationshipKeyMapping, ReplicaRelationshipKind, ReplicaResultEnvelope, ReplicaRowPolicyArtifact, ReplicaRootSelection, ReplicaScalarSelection, ReplicaSelectionStorage, ReplicaSparse, ReplicaSnapshot, ReplicaStatus, ReplicaTransport, ReplicaTransportRequest, ReplicaVariableValue, ReplicaVariableCodecArtifact, ReplicaVariableEnumInputRef, ReplicaVariableFilterInputDefinition, ReplicaVariableFilterInputField, ReplicaVariableFilterInputRelationship, ReplicaVariableFilterInputTarget, ReplicaVariableInputDefinition, ReplicaVariableInputRef, ReplicaVariableListInputRef, ReplicaVariableNamedInputRef, ReplicaVariableOrderInputDefinition, ReplicaVariableOrderInputField, ReplicaVariableScalarInputRef, ReplicaValue, ReplicaWatch, ReplicaWriteSource, WatchReplicaOptions } from './types.js';
 export { lowerMutationCache, MUTATION_CACHE_VISIBILITY_FULL, MUTATION_CACHE_VISIBILITY_UNAUTHORIZED, } from './mutation-cache.js';
 export type { MutationCacheEffect, MutationCacheProgram, MutationCacheVisibility, MutationField, MutationOperation, MutationProgram, MutationTarget, } from './mutation-cache.js';

package/dist/replica/types.d.ts

@@ -444,6 +444,39 @@ export type ReplicaProtocolOperationArtifact<TData = Record<string, unknown>, TV
     readonly variableCodec: ReplicaVariableCodecArtifact;
 };
 export type ReplicaOperationArtifact<TData = Record<string, unknown>, TVariables extends GraphqlVariables = GraphqlVariables> = ReplicaProtocolOperationArtifact<TData, TVariables>;
+/** Framework-neutral compiler metadata consumed by placement adapters. */
+export type ReplicaIslandMetadata = {
+    readonly version: 1;
+    readonly id: string;
+    readonly operation: string;
+    readonly operationHash: string;
+    readonly modulePath: string;
+    readonly exportName: string;
+    readonly source: ReplicaOperationSourceLocation;
+    readonly directives: {
+        readonly load: boolean;
+        readonly live: boolean;
+    };
+    readonly variableSchema: {
+        readonly reference: string;
+        readonly codecVersion: number;
+        readonly variables: readonly {
+            readonly name: string;
+            readonly graphqlType: string;
+        }[];
+    };
+    readonly liveCoverage: {
+        readonly requested: boolean;
+        readonly finite: boolean;
+        readonly kind: string;
+        readonly maxItems?: number;
+    };
+};
+/** One adapter-consumable island plan bound to its executable operation. */
+export type ReplicaIslandOperation<TData = Record<string, unknown>, TVariables extends GraphqlVariables = GraphqlVariables> = {
+    readonly plan: ReplicaIslandMetadata;
+    readonly artifact: ReplicaOperationArtifact<TData, TVariables>;
+};
 export type ReplicaWriteSource = 'network' | 'live' | 'ssr' | 'restore' | 'atomic';
 export type ReplicaResultEnvelope<TData = unknown> = {
     readonly data?: TData | null;
@@ -532,6 +565,11 @@ export type WatchReplicaOptions = {
 export type DistributedReplicaOptions = {
     readonly transport?: ReplicaTransport;
     readonly onObserverError?: (error: AggregateError) => void;
+    /**
+     * Runs after the old generation is fenced and before its transports/state
+     * are purged. Framework adapters use this to release generation-owned views.
+     */
+    readonly onAuthorizationGenerationDispose?: () => void;
     /** Opt-in framework-neutral diagnostics; absent in production by default. */
     readonly diagnostics?: ReplicaDiagnosticsSink;
 };

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

@@ -0,0 +1,37 @@
+import type { DistributedReplica } from '../replica/index.js';
+import type { DistributedBoundaryOperation, DistributedBoundaryVariableContext } from './boundary-variables.js';
+export type DistributedSvelteKitBoundaryInstance = Readonly<{
+    /** Opaque identity for one mounted SvelteKit page or layout instance. */
+    id: string;
+    route: string;
+    kind: 'layout' | 'page';
+}>;
+export type DistributedSvelteKitBoundaryLocation = Readonly<{
+    /** Opaque identity for one mounted page or layout instance. */
+    id: string;
+    pathname: string;
+    kind: 'layout' | 'page';
+}>;
+export type DistributedSvelteKitLocationContext<TSession = unknown, TProps = Readonly<Record<string, unknown>>> = Omit<DistributedBoundaryVariableContext<TSession, TProps>, 'params'>;
+export type SveltekitBoundaryLifecycleDiagnostic = Readonly<{
+    action: 'acquire' | 'retain' | 'release' | 'scope-dispose' | 'final-unsubscribe';
+    boundary: string;
+    operation?: string;
+    live?: boolean;
+    owners: number;
+}>;
+export type SveltekitBoundaryRetention = Readonly<{
+    release(): void;
+}>;
+export declare class DistributedSvelteKitBoundaryController {
+    #private;
+    constructor(replica: DistributedReplica, operations: readonly DistributedBoundaryOperation[], diagnostic?: (event: SveltekitBoundaryLifecycleDiagnostic) => void);
+    retain<TSession, TProps>(instance: DistributedSvelteKitBoundaryInstance, context: DistributedBoundaryVariableContext<TSession, TProps>): SveltekitBoundaryRetention;
+    /** Retain the nearest generated page/layout boundary at a browser location. */
+    retainLocation<TSession, TProps>(location: DistributedSvelteKitBoundaryLocation, context: DistributedSvelteKitLocationContext<TSession, TProps>): SveltekitBoundaryRetention;
+    /** Warm every generated page and owning layout selection for one target URL. */
+    prefetchLocation<TSession, TProps>(pathname: string, context: DistributedSvelteKitLocationContext<TSession, TProps>): Promise<void>;
+    /** Close every old-scope owner while keeping the controller reusable. */
+    disposeScope(): void;
+    destroy(): void;
+}