@hops-ops/distributed 0.0.0

package/dist/internal/cache-engine/types.d.ts

@@ -0,0 +1,300 @@
+export type Revision = number | string | bigint;
+export type RecordKey = string;
+export type IndexKey = string;
+export type CacheValue = null | boolean | number | string | readonly CacheValue[] | {
+    readonly [key: string]: CacheValue;
+};
+export type RecordLink = RecordKey | readonly RecordKey[] | null;
+export type RecordWrite = {
+    key: RecordKey;
+    revision: Revision;
+    /** Stable incarnation fence. Defaults to the first live revision. */
+    incarnation?: Revision;
+    /** Omitted fields stay absent. A present `null` remains present. */
+    fields?: Readonly<Record<string, CacheValue>>;
+    /** Relationship identities are stored separately from scalar/JSON fields. */
+    links?: Readonly<Record<string, RecordLink>>;
+};
+export type OptimisticRecordWrite = Omit<RecordWrite, 'revision' | 'incarnation'>;
+export type CacheIndexCoverage = {
+    readonly kind: 'complete';
+} | {
+    readonly kind: 'unknown';
+} | {
+    readonly kind: 'offset';
+    readonly offset: number;
+    readonly limit?: number;
+    readonly returned?: number;
+    readonly hasNext?: boolean;
+} | {
+    readonly kind: 'cursor';
+    readonly after?: CacheValue;
+    readonly before?: CacheValue;
+    readonly first?: number;
+    readonly last?: number;
+    readonly start?: CacheValue;
+    readonly end?: CacheValue;
+    readonly hasNext?: boolean;
+    readonly hasPrevious?: boolean;
+};
+export type CacheIndexMetadata = {
+    readonly parent?: RecordKey;
+    /** Parent row clock claimed by the response that produced this relationship. */
+    readonly parentRevision?: string;
+    /** Parent lifecycle fence stamped by the engine. */
+    readonly parentIncarnation?: string;
+    readonly field: string;
+    readonly arguments: Readonly<Record<string, CacheValue>>;
+    readonly coverage: CacheIndexCoverage;
+    readonly dependencies: readonly string[];
+    readonly staleReason?: string;
+    /** Distinguishes a present GraphQL `null` from an empty collection. */
+    readonly nullValue?: boolean;
+};
+export type IndexWrite = {
+    key: IndexKey;
+    revision: Revision;
+    records: readonly RecordKey[];
+    complete?: boolean;
+    metadata?: CacheIndexMetadata;
+};
+export type OptimisticIndexWrite = Omit<IndexWrite, 'revision'>;
+export type SparseRecord = {
+    readonly key: RecordKey;
+    readonly revision: string;
+    readonly incarnation: string;
+    readonly fields: Readonly<Record<string, CacheValue>>;
+    readonly links: Readonly<Record<string, RecordLink>>;
+};
+export type CacheIndex = {
+    readonly key: IndexKey;
+    readonly revision: string;
+    readonly staleRevision?: string;
+    readonly records: readonly RecordKey[];
+    readonly complete: boolean;
+    readonly metadata?: CacheIndexMetadata;
+};
+export type CachePresence<T> = {
+    readonly present: false;
+} | {
+    readonly present: true;
+    readonly value: T;
+};
+export type SparseRecordMeta = {
+    readonly key: RecordKey;
+    readonly incarnation: string;
+};
+export type BaseRecordClock = {
+    readonly revision: string;
+    readonly incarnation: string;
+    readonly tombstoned: boolean;
+};
+/** Raised when one source revision claims two different values. */
+export interface CacheReader {
+    recordMeta(key: RecordKey): SparseRecordMeta | undefined;
+    field(key: RecordKey, name: string): CachePresence<CacheValue>;
+    link(key: RecordKey, name: string): CachePresence<RecordLink>;
+    record(key: RecordKey): SparseRecord | undefined;
+    index(key: IndexKey): CacheIndex | undefined;
+}
+export interface BaseCacheWriter {
+    recordClock(key: RecordKey): BaseRecordClock | undefined;
+    writeRecord(write: RecordWrite): boolean;
+    tombstoneRecord(key: RecordKey, revision: Revision, incarnation?: Revision): boolean;
+    /** Drop uncertified fields while preserving higher protocol clocks externally. */
+    discardRecord(key: RecordKey): boolean;
+    writeIndex(write: IndexWrite): boolean;
+    markIndexStale(key: IndexKey, reason: string, revision?: Revision): boolean;
+    deleteIndex(key: IndexKey, revision: Revision): boolean;
+}
+export interface OptimisticCacheWriter {
+    writeRecord(write: OptimisticRecordWrite): void;
+    tombstoneRecord(key: RecordKey): void;
+    writeIndex(write: OptimisticIndexWrite): void;
+    deleteIndex(key: IndexKey): void;
+}
+export type CacheSelector<T> = (reader: CacheReader) => T;
+export type CacheListener<T> = (value: T, previous: T | undefined) => void;
+export type WatchOptions = {
+    immediate?: boolean;
+};
+export type CacheEngineOptions = {
+    /** Observer failures are reported after every eligible watcher was delivered. */
+    onWatcherError?: (error: AggregateError) => void;
+};
+export type OptimisticLayerState = 'optimistic' | 'accepted';
+export type CacheEngineSnapshot = {
+    readonly version: 1;
+    readonly records: readonly {
+        readonly key: RecordKey;
+        readonly revision: string;
+        readonly incarnation?: string;
+        readonly tombstoneRevision?: string;
+        readonly fields: Readonly<Record<string, {
+            readonly revision: string;
+            readonly value: CacheValue;
+        }>>;
+        readonly links: Readonly<Record<string, {
+            readonly revision: string;
+            readonly value: RecordLink;
+        }>>;
+    }[];
+    readonly indexes: readonly {
+        readonly key: IndexKey;
+        readonly revision: string;
+        readonly staleRevision?: string;
+        readonly records: readonly RecordKey[];
+        readonly complete: boolean;
+        readonly deleted: boolean;
+        readonly metadata?: CacheIndexMetadata;
+    }[];
+};
+/**
+ * Opaque, detached JSON context owned by the replica and carried with one
+ * optimistic layer. The cache engine never interprets it.
+ */
+export type OptimisticLayerContext = CacheValue;
+export type OptimisticLayerView = {
+    readonly id: string;
+    readonly sequence: number;
+    readonly state: OptimisticLayerState;
+    readonly context?: OptimisticLayerContext;
+};
+export type DerivedIndexMutation = {
+    readonly kind: 'write';
+    readonly write: OptimisticIndexWrite;
+} | {
+    readonly kind: 'stale';
+    readonly key: IndexKey;
+    readonly reason: string;
+} | {
+    readonly kind: 'delete';
+    readonly key: IndexKey;
+};
+/**
+ * Rebuild the complete derived-index overlay from confirmed state and the
+ * ordered semantic contexts of every surviving optimistic layer.
+ */
+export type DerivedIndexReconciler = (confirmed: CacheEngineSnapshot, layers: readonly OptimisticLayerView[]) => readonly DerivedIndexMutation[];
+export interface CacheEngine {
+    read<T>(selector: CacheSelector<T>): T;
+    /**
+     * Read only the authoritative base graph, excluding optimistic records and
+     * their derived-index overlay.
+     */
+    readConfirmed<T>(selector: CacheSelector<T>): T;
+    /**
+     * Return the authoritative write fence for requested base indexes.
+     * Deleted sentinels remain visible here even though CacheReader hides them.
+     */
+    confirmedIndexFences(keys: readonly IndexKey[]): ReadonlyMap<IndexKey, string>;
+    watch<T>(selector: CacheSelector<T>, listener: CacheListener<T>, options?: WatchOptions): () => void;
+    batch<T>(update: (writer: BaseCacheWriter) => T): T;
+    createOptimisticLayer(id: string, update: (writer: OptimisticCacheWriter) => void, context?: OptimisticLayerContext): void;
+    setDerivedIndexReconciler(reconciler: DerivedIndexReconciler | undefined): void;
+    markOptimisticLayerAccepted(id: string): boolean;
+    confirmOptimisticLayer<T>(id: string, update: (writer: BaseCacheWriter) => T): T;
+    confirmOptimisticLayers<T>(ids: readonly string[], update: (writer: BaseCacheWriter) => T): T;
+    rejectOptimisticLayer(id: string): boolean;
+    optimisticLayerState(id: string): OptimisticLayerState | undefined;
+    extract(): CacheEngineSnapshot;
+    restore(snapshot: CacheEngineSnapshot): void;
+    /**
+     * Replace only confirmed base state while preserving local optimistic layers,
+     * their acceptance state, and causal sequencing floors.
+     */
+    restoreConfirmed(snapshot: CacheEngineSnapshot): void;
+    /**
+     * Drop incomparable/reset base indexes without assigning them a fabricated
+     * revision. Pending optimistic overlays remain layered above the new gap.
+     */
+    discardIndexes(keys: readonly IndexKey[]): void;
+    retain(key: RecordKey): void;
+    release(key: RecordKey): void;
+    gc(): readonly RecordKey[];
+}
+export type StoredField<T> = {
+    revision: bigint;
+    value: T;
+};
+export type StoredRecord = {
+    revision: bigint;
+    incarnation: bigint;
+    tombstoneRevision?: bigint;
+    fields: Map<string, StoredField<CacheValue>>;
+    links: Map<string, StoredField<RecordLink>>;
+};
+export type StoredIndex = {
+    revision: bigint;
+    staleRevision?: bigint;
+    records: RecordKey[];
+    complete: boolean;
+    deleted: boolean;
+    metadata?: CacheIndexMetadata;
+};
+export type OverlayOperation = {
+    kind: 'write-record';
+    write: OptimisticRecordWrite;
+} | {
+    kind: 'tombstone-record';
+    key: RecordKey;
+} | {
+    kind: 'write-index';
+    write: OptimisticIndexWrite;
+} | {
+    kind: 'delete-index';
+    key: IndexKey;
+};
+export type OptimisticLayer = {
+    id: string;
+    sequence: number;
+    state: OptimisticLayerState;
+    operations: OverlayOperation[];
+    context?: OptimisticLayerContext;
+};
+export type DerivedIndexOperation = {
+    kind: 'write-index';
+    write: OptimisticIndexWrite;
+} | {
+    kind: 'mark-index-stale';
+    key: IndexKey;
+    reason: string;
+} | {
+    kind: 'delete-index';
+    key: IndexKey;
+};
+export type VisibleRecord = {
+    revision: bigint;
+    incarnation: bigint;
+    tombstoned: boolean;
+    fields: Map<string, CacheValue>;
+    links: Map<string, RecordLink>;
+};
+export type VisibleIndex = {
+    revision: bigint;
+    staleRevision?: bigint;
+    records: RecordKey[];
+    complete: boolean;
+    deleted: boolean;
+    metadata?: CacheIndexMetadata;
+};
+export type MaterializedCacheGraph = {
+    records: Map<RecordKey, VisibleRecord>;
+    indexes: Map<IndexKey, VisibleIndex>;
+};
+export type Watcher<T = unknown> = {
+    selector: CacheSelector<T>;
+    listener: CacheListener<T>;
+    value: T;
+    dependencies: Set<string>;
+};
+export type EngineBackup = {
+    records: Map<RecordKey, StoredRecord>;
+    indexes: Map<IndexKey, StoredIndex>;
+    layers: OptimisticLayer[];
+    derivedIndexOperations: DerivedIndexOperation[];
+    confirmedFloors: Map<string, number>;
+    retained: Map<RecordKey, number>;
+    nextLayerSequence: number;
+    changedDependencies: Set<string>;
+};

package/dist/internal/cache-engine/types.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/cache-engine.d.ts

@@ -0,0 +1,3 @@
+/** Private cache engine; implementation lives in ./cache-engine/. */
+export { CacheRevisionConflictError, cacheIndexKey, createCacheEngine } from './cache-engine/index.js';
+export type { BaseCacheWriter, BaseRecordClock, CacheEngine, CacheEngineOptions, CacheEngineSnapshot, CacheIndex, CacheIndexCoverage, CacheIndexMetadata, CacheListener, CachePresence, CacheReader, CacheSelector, CacheValue, DerivedIndexMutation, DerivedIndexReconciler, IndexKey, IndexWrite, OptimisticCacheWriter, OptimisticIndexWrite, OptimisticLayerContext, OptimisticLayerState, OptimisticLayerView, OptimisticRecordWrite, RecordKey, RecordLink, RecordWrite, Revision, SparseRecord, SparseRecordMeta, WatchOptions } from './cache-engine/index.js';

package/dist/internal/cache-engine.js

@@ -0,0 +1,2 @@
+/** Private cache engine; implementation lives in ./cache-engine/. */
+export { CacheRevisionConflictError, cacheIndexKey, createCacheEngine } from './cache-engine/index.js';

package/dist/lib/assert-name.d.ts

@@ -0,0 +1,2 @@
+/** Require a non-empty string (field names, layer ids, etc.). */
+export declare function assertName(value: unknown, description: string): asserts value is string;

package/dist/lib/assert-name.js

@@ -0,0 +1,6 @@
+/** Require a non-empty string (field names, layer ids, etc.). */
+export function assertName(value, description) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new TypeError(`${description} must be a non-empty string`);
+    }
+}

package/dist/lib/compare-code-units.d.ts

@@ -0,0 +1,2 @@
+/** Lexicographic compare using UTF-16 code units (JS string order). */
+export declare function compareCodeUnits(left: string, right: string): number;

package/dist/lib/compare-code-units.js

@@ -0,0 +1,4 @@
+/** Lexicographic compare using UTF-16 code units (JS string order). */
+export function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/lib/deep-equal.d.ts

@@ -0,0 +1,2 @@
+/** Structural equality for JSON-like values (objects, arrays, primitives). */
+export declare function deepEqual(left: unknown, right: unknown): boolean;

package/dist/lib/deep-equal.js

@@ -0,0 +1,24 @@
+/** Structural equality for JSON-like values (objects, arrays, primitives). */
+export function deepEqual(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (typeof left !== typeof right || left === null || right === null)
+        return false;
+    if (typeof left !== 'object' || typeof right !== 'object')
+        return false;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        if (!Array.isArray(left) ||
+            !Array.isArray(right) ||
+            left.length !== right.length) {
+            return false;
+        }
+        return left.every((entry, index) => deepEqual(entry, right[index]));
+    }
+    const leftRecord = left;
+    const rightRecord = right;
+    const leftKeys = Object.keys(leftRecord);
+    const rightKeys = Object.keys(rightRecord);
+    return (leftKeys.length === rightKeys.length &&
+        leftKeys.every((key) => Object.prototype.hasOwnProperty.call(rightRecord, key) &&
+            deepEqual(leftRecord[key], rightRecord[key])));
+}

package/dist/lib/freeze-record.d.ts

@@ -0,0 +1,2 @@
+/** Build an immutable plain object from key/value pairs. */
+export declare function freezeRecord<T>(entries: readonly (readonly [string, T])[]): Readonly<Record<string, T>>;

package/dist/lib/freeze-record.js

@@ -0,0 +1,13 @@
+/** Build an immutable plain object from key/value pairs. */
+export function freezeRecord(entries) {
+    const result = {};
+    for (const [key, value] of entries) {
+        Object.defineProperty(result, key, {
+            value,
+            enumerable: true,
+            configurable: false,
+            writable: false
+        });
+    }
+    return Object.freeze(result);
+}

package/dist/lib/index.d.ts

@@ -0,0 +1,6 @@
+export { assertName } from './assert-name.js';
+export { compareCodeUnits } from './compare-code-units.js';
+export { deepEqual } from './deep-equal.js';
+export { freezeRecord } from './freeze-record.js';
+export { isPlainRecord } from './is-plain-record.js';
+export { reportSafely, reportUnhandledError } from './report.js';

package/dist/lib/index.js

@@ -0,0 +1,6 @@
+export { assertName } from './assert-name.js';
+export { compareCodeUnits } from './compare-code-units.js';
+export { deepEqual } from './deep-equal.js';
+export { freezeRecord } from './freeze-record.js';
+export { isPlainRecord } from './is-plain-record.js';
+export { reportSafely, reportUnhandledError } from './report.js';

package/dist/lib/is-plain-record.d.ts

@@ -0,0 +1,2 @@
+/** True for non-null objects that are not arrays (own enumerable bag). */
+export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;

package/dist/lib/is-plain-record.js

@@ -0,0 +1,8 @@
+/** True for non-null objects that are not arrays (own enumerable bag). */
+export function isPlainRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}

package/dist/lib/report.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Deliver an AggregateError to a user reporter without letting the reporter
+ * change success semantics of the surrounding operation.
+ */
+export declare function reportSafely(reporter: (error: AggregateError) => void, error: AggregateError, failureMessage?: string): void;
+/** Best-effort delivery of an unhandled AggregateError to the host. */
+export declare function reportUnhandledError(error: AggregateError): void;

package/dist/lib/report.js

@@ -0,0 +1,26 @@
+/**
+ * Deliver an AggregateError to a user reporter without letting the reporter
+ * change success semantics of the surrounding operation.
+ */
+export function reportSafely(reporter, error, failureMessage = 'error reporter failed') {
+    try {
+        reporter(error);
+    }
+    catch (reporterError) {
+        queueMicrotask(() => {
+            throw new AggregateError([error, reporterError], failureMessage);
+        });
+    }
+}
+/** Best-effort delivery of an unhandled AggregateError to the host. */
+export function reportUnhandledError(error) {
+    const reportError = globalThis
+        .reportError;
+    if (typeof reportError === 'function') {
+        reportError(error);
+        return;
+    }
+    queueMicrotask(() => {
+        throw error;
+    });
+}

package/dist/protocol.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Versioned framework metadata carried in GraphQL's top-level
+ * `extensions.distributed` response envelope.
+ *
+ * Domain result objects never contain these values. Hidden identities and
+ * positions remain opaque strings: the JavaScript client compares or returns
+ * them, but never parses them as numbers or reconstructs server scopes.
+ */
+/** The only Distributed GraphQL protocol version understood by this package. */
+export declare const DISTRIBUTED_PROTOCOL_VERSION: 1;
+declare const opaqueDistributedString: unique symbol;
+declare const distributedDecimalString: unique symbol;
+/** Server-owned identity/token whose contents must not be interpreted by clients. */
+export type DistributedOpaqueString = string & {
+    readonly [opaqueDistributedString]: true;
+};
+/** Canonical unsigned u64 decimal carried without JavaScript numeric coercion. */
+export type DistributedDecimalString = string & {
+    readonly [distributedDecimalString]: true;
+};
+export type DistributedCommandState = 'in_progress' | 'accepted' | 'accepted_pending_projection' | 'projected' | 'rejected' | 'projection_failed' | 'expired' | 'unknown';
+export type DistributedCommandConsistency = 'accepted' | 'fact' | 'projected';
+/** Closed wire codecs for server-derived, client-visible trusted presets. */
+export type DistributedTrustedPresetCodec = 'string' | 'string_unvalidated_timestamp' | 'base64' | 'boolean' | 'int32' | 'float64' | 'json_number_precision_limited' | 'json';
+/** JSON value accepted by the Distributed protocol parser. */
+export type DistributedProtocolValue = null | boolean | number | string | readonly DistributedProtocolValue[] | {
+    readonly [key: string]: DistributedProtocolValue;
+};
+/**
+ * One server-derived value valid only under its containing envelope's exact
+ * authoritative cache scope.
+ */
+export type DistributedTrustedPreset = Readonly<{
+    name: string;
+    codec: DistributedTrustedPresetCodec;
+    value: DistributedProtocolValue;
+}>;
+/** One finite, server-resolved projection obligation for a command. */
+export type DistributedProjectionExpectation = Readonly<Record<string, unknown> & {
+    projection: string;
+    model: string;
+    scopeToken: DistributedOpaqueString;
+}>;
+/** Comparable record evidence within one exact opaque record scope. */
+export type DistributedRecordRevision = Readonly<Record<string, unknown> & {
+    path?: readonly string[];
+    model: string;
+    scopeToken: DistributedOpaqueString;
+    incarnation: DistributedDecimalString;
+    revision: DistributedDecimalString;
+    tombstone: boolean;
+}>;
+/** Exact observation of one command causation in one projection obligation. */
+export type DistributedProjectionObservation = Readonly<Record<string, unknown> & {
+    causationId: DistributedOpaqueString;
+    projection: string;
+    model: string;
+    scopeToken: DistributedOpaqueString;
+}>;
+/** Opaque resumable position for one named projection scope. */
+export type DistributedLiveCursor = Readonly<Record<string, unknown> & {
+    projection: string;
+    position: DistributedDecimalString;
+    token: DistributedOpaqueString;
+}>;
+/** Comparable checkpoint for one exact query-index projection member. */
+export type DistributedIndexRevision = Readonly<Record<string, unknown> & {
+    projection: string;
+    scopeToken: DistributedOpaqueString;
+    position: DistributedDecimalString;
+    resume?: DistributedLiveCursor;
+}>;
+/**
+ * Record and causal-index evidence for one exact operation instance.
+ *
+ * The GraphQL payload itself is the authoritative query snapshot. These flags
+ * describe whether the server could additionally prove every normalized record
+ * clock and expose a safely comparable projection vector. Row-filtered
+ * authorization commonly makes `indexesComparable` false without making the
+ * authorized payload partial.
+ */
+export type DistributedQuerySnapshot = Readonly<Record<string, unknown> & {
+    scopeToken: DistributedOpaqueString;
+    recordsComplete: boolean;
+    indexesComparable: boolean;
+    records: readonly DistributedRecordRevision[];
+    indexes: readonly DistributedIndexRevision[];
+    observations: readonly DistributedProjectionObservation[];
+}>;
+/** Per-frame decision about live support, reset, and resumable cursors. */
+export type DistributedLiveMetadata = Readonly<Record<string, unknown> & {
+    supported: boolean;
+    reset: boolean;
+    cursors: readonly DistributedLiveCursor[];
+}>;
+/** Private GraphQL request extension consumed by generated live operations. */
+export type DistributedLiveResumeExtensions = Readonly<{
+    distributed: Readonly<{
+        resume: Readonly<{
+            cursors: readonly DistributedLiveCursor[];
+        }>;
+    }>;
+}>;
+/** Durable receipt/status metadata for one idempotent command identity. */
+export type DistributedCommandMetadata = Readonly<Record<string, unknown> & {
+    commandId: DistributedOpaqueString;
+    causationId: DistributedOpaqueString;
+    state: DistributedCommandState;
+    consistency: DistributedCommandConsistency;
+    expects: readonly DistributedProjectionExpectation[];
+    /** Defaults to an empty array when omitted by the compact wire format. */
+    observations: readonly DistributedProjectionObservation[];
+    /** Defaults to an empty array when omitted by the compact wire format. */
+    records: readonly DistributedRecordRevision[];
+}>;
+/** Canonical contents of top-level `extensions.distributed`. */
+export type DistributedProtocolEnvelope = Readonly<Record<string, unknown> & {
+    protocolVersion: typeof DISTRIBUTED_PROTOCOL_VERSION;
+    schemaHash: string;
+    cacheScope: DistributedOpaqueString;
+    operation?: string;
+    command?: DistributedCommandMetadata;
+    snapshot?: DistributedQuerySnapshot;
+    live?: DistributedLiveMetadata;
+    /** Defaults to an empty array when omitted by the compact wire format. */
+    trustedPresets: readonly DistributedTrustedPreset[];
+}>;
+/** GraphQL top-level extensions with a validated Distributed envelope. */
+export type GraphqlResponseExtensions = Readonly<Record<string, unknown> & {
+    distributed?: DistributedProtocolEnvelope;
+}>;
+export type DistributedProtocolErrorCode = 'DISTRIBUTED_PROTOCOL_INVALID' | 'DISTRIBUTED_PROTOCOL_VERSION_UNSUPPORTED';
+/** Safe parse failure that reports structure, never hidden server values. */
+export declare class DistributedProtocolError extends Error {
+    readonly code: DistributedProtocolErrorCode;
+    readonly path: string;
+    constructor(code: DistributedProtocolErrorCode, path: string);
+}
+/**
+ * Parse GraphQL's optional top-level `extensions` object.
+ *
+ * Non-Distributed extension keys are preserved. When `distributed` is present,
+ * its required version/scope/schema fields and known receipt/evidence fields are
+ * validated. A malformed or incompatible envelope throws
+ * {@link DistributedProtocolError}; transports convert that into a fail-closed
+ * GraphQL result/error rather than exposing the accompanying data as trusted.
+ */
+export declare function parseGraphqlResponseExtensions(value: unknown): GraphqlResponseExtensions | undefined;
+/** Parse one `extensions.distributed` value independently of a transport. */
+export declare function parseDistributedProtocolEnvelope(value: unknown): DistributedProtocolEnvelope;
+/**
+ * Parse and deeply freeze one scope-wide trusted-preset value inventory.
+ *
+ * This is exported for the framework-neutral replica's internal command seam.
+ * Applications receive the same values through
+ * {@link parseDistributedProtocolEnvelope}; they must never supply this
+ * inventory as command authority.
+ *
+ * @internal
+ */
+export declare function parseDistributedTrustedPresetInventory(value: unknown, path?: string): readonly DistributedTrustedPreset[];
+/**
+ * Build the private request extension for a generated live resume.
+ *
+ * The server remains authoritative and verifies every token. This client-side
+ * check only prevents malformed, duplicate, or unbounded state from leaving
+ * the replica.
+ *
+ * @internal
+ */
+export declare function distributedLiveResumeExtensions(value: readonly DistributedLiveCursor[]): DistributedLiveResumeExtensions;
+/** @internal */
+export declare function isDistributedTrustedPresetCodec(value: unknown): value is DistributedTrustedPresetCodec;
+/**
+ * Compare two already-validated protocol decimals without converting either
+ * through JavaScript's numeric types.
+ */
+export declare function compareDistributedDecimal(left: DistributedDecimalString, right: DistributedDecimalString): -1 | 0 | 1;
+export {};