@hops-ops/distributed 4.8.0 → 4.9.0

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/sveltekit/index.d.ts

@@ -1,4 +1,6 @@
 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';

package/dist/sveltekit/index.js

@@ -1,4 +1,6 @@
 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 { bindSveltekitOperation, createPageDataSessionSource, createDistributedSvelteKit, sessionSourceFromPageData } from './replica.js';
 export { createDistributedSvelteKitServer, matchDistributedRoute, registerDistributedRoute } from './server-replica.js';

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 {};