@hops-ops/distributed 0.0.0

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

@@ -0,0 +1,380 @@
+import { compareDistributedDecimal, parseDistributedTrustedPresetInventory } from '../../protocol.js';
+import { modelFromRecordKey } from './clocks.js';
+import { canonicalTrustedPresets } from './helpers.js';
+export function serializeOperationProtocolGroup(key, group, generation) {
+    return Object.freeze({
+        key,
+        ...(group.query === undefined
+            ? {}
+            : { query: serializeOperationProtocolState(group.query) }),
+        ...(group.live === undefined
+            ? {}
+            : { live: serializeOperationProtocolState(group.live) }),
+        ...(group.active === undefined ? {} : { active: group.active }),
+        generation
+    });
+}
+export function serializeOperationProtocolState(state) {
+    return Object.freeze({
+        operation: state.operation,
+        ...(state.snapshotScope === undefined
+            ? {}
+            : { snapshotScope: state.snapshotScope }),
+        indexClocks: Object.freeze([...state.indexClocks]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([projection, clock]) => Object.freeze([
+            projection,
+            Object.freeze({
+                scopeToken: clock.scopeToken,
+                position: clock.position
+            })
+        ]))),
+        ...(state.indexRevision === undefined
+            ? {}
+            : { indexRevision: state.indexRevision }),
+        indexKeys: Object.freeze([...state.indexKeys].sort()),
+        pathRecords: Object.freeze([...state.pathRecords]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([path, key]) => Object.freeze([path, key]))),
+        cursors: Object.freeze(state.cursors.map((cursor) => Object.freeze({
+            projection: cursor.projection,
+            position: cursor.position,
+            token: cursor.token
+        })))
+    });
+}
+export function parseAuthoritativeScope(value) {
+    try {
+        const scope = hydrationRecord(value, 'authoritativeScope', ['protocolVersion', 'schemaHash', 'cacheScope']);
+        if (scope.protocolVersion !== 1) {
+            hydrationInvalid('authoritativeScope.protocolVersion');
+        }
+        return Object.freeze({
+            protocolVersion: 1,
+            schemaHash: hydrationString(scope.schemaHash, 'authoritativeScope.schemaHash'),
+            cacheScope: hydrationOpaque(scope.cacheScope, 'authoritativeScope.cacheScope')
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+export function hydrationMetadataConsistent(parsed) {
+    try {
+        const recordByKey = new Map(parsed.cache.records.map((record) => [record.key, record]));
+        for (const record of parsed.cache.records) {
+            if (modelFromRecordKey(record.key) === undefined)
+                continue;
+            const clock = parsed.recordClocks.get(record.key);
+            if (clock === undefined ||
+                record.incarnation === undefined ||
+                clock.incarnation !== record.incarnation ||
+                clock.revision !== record.revision) {
+                return false;
+            }
+            if (clock.tombstone) {
+                if (record.tombstoneRevision !== clock.revision)
+                    return false;
+            }
+            else if (record.tombstoneRevision !== undefined) {
+                return false;
+            }
+        }
+        for (const [recordKey, clock] of parsed.recordClocks) {
+            const record = recordByKey.get(recordKey);
+            if (record?.tombstoneRevision !== undefined &&
+                (!clock.tombstone ||
+                    record.tombstoneRevision !== clock.revision)) {
+                return false;
+            }
+        }
+        const revisionsByIndex = new Map();
+        for (const group of parsed.operationProtocols.values()) {
+            for (const state of [group.query, group.live]) {
+                if (state === undefined)
+                    continue;
+                for (const recordKey of state.pathRecords.values()) {
+                    if (modelFromRecordKey(recordKey) !== undefined &&
+                        !parsed.recordClocks.has(recordKey)) {
+                        return false;
+                    }
+                }
+                if (state.indexRevision === undefined) {
+                    if (state.indexKeys.size > 0)
+                        return false;
+                    continue;
+                }
+                for (const indexKey of state.indexKeys) {
+                    let revisions = revisionsByIndex.get(indexKey);
+                    if (revisions === undefined) {
+                        revisions = new Set();
+                        revisionsByIndex.set(indexKey, revisions);
+                    }
+                    revisions.add(state.indexRevision);
+                }
+            }
+        }
+        const nextIndexRevision = parsed.nextIndexRevision;
+        for (const index of parsed.cache.indexes) {
+            const revision = hydrationDecimal(index.revision, 'state.payload.cache.indexes.revision');
+            if (compareDistributedDecimal(revision, nextIndexRevision) > 0 ||
+                !revisionsByIndex.get(index.key)?.has(index.revision)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseReplicaHydration(value) {
+    try {
+        const state = hydrationRecord(value, 'state', ['version', 'scope', 'payload']);
+        if (state.version !== 1)
+            hydrationInvalid('state.version');
+        const scopeValue = hydrationRecord(state.scope, 'state.scope', ['protocolVersion', 'schemaHash', 'cacheScope']);
+        if (scopeValue.protocolVersion !== 1) {
+            hydrationInvalid('state.scope.protocolVersion');
+        }
+        const scope = Object.freeze({
+            protocolVersion: 1,
+            schemaHash: hydrationString(scopeValue.schemaHash, 'state.scope.schemaHash'),
+            cacheScope: hydrationOpaque(scopeValue.cacheScope, 'state.scope.cacheScope')
+        });
+        const payload = hydrationRecord(state.payload, 'state.payload', [
+            'cache',
+            'operations',
+            'recordClocks',
+            'anonymousRecordClocks',
+            'trustedPresets',
+            'nextIndexRevision'
+        ]);
+        const cache = payload.cache;
+        if (!isHydrationRecord(cache))
+            hydrationInvalid('state.payload.cache');
+        const operationsValue = hydrationArray(payload.operations, 'state.payload.operations');
+        const operationProtocols = new Map();
+        const operationGenerations = new Map();
+        for (const [index, entry] of operationsValue.entries()) {
+            const path = `state.payload.operations[${index}]`;
+            const raw = hydrationRecord(entry, path, ['key', 'query', 'live', 'active', 'generation'], ['key', 'generation']);
+            const key = hydrationString(raw.key, `${path}.key`);
+            if (!key.startsWith('protocol:') || operationProtocols.has(key)) {
+                hydrationInvalid(`${path}.key`);
+            }
+            const query = raw.query === undefined
+                ? undefined
+                : parseOperationProtocolState(raw.query, `${path}.query`);
+            const live = raw.live === undefined
+                ? undefined
+                : parseOperationProtocolState(raw.live, `${path}.live`);
+            if (query === undefined && live === undefined)
+                hydrationInvalid(path);
+            const active = raw.active === undefined
+                ? undefined
+                : hydrationOperationSource(raw.active, `${path}.active`);
+            if ((active === 'query' && query === undefined) ||
+                (active === 'live' && live === undefined)) {
+                hydrationInvalid(`${path}.active`);
+            }
+            operationProtocols.set(key, {
+                ...(query === undefined ? {} : { query }),
+                ...(live === undefined ? {} : { live }),
+                ...(active === undefined ? {} : { active })
+            });
+            operationGenerations.set(key, hydrationGeneration(raw.generation, `${path}.generation`));
+        }
+        const recordClocks = new Map();
+        const recordKeysByScope = new Map();
+        for (const [index, entry] of hydrationArray(payload.recordClocks, 'state.payload.recordClocks').entries()) {
+            const path = `state.payload.recordClocks[${index}]`;
+            const pair = hydrationPair(entry, path);
+            const key = hydrationString(pair[0], `${path}[0]`);
+            if (recordClocks.has(key))
+                hydrationInvalid(`${path}[0]`);
+            const clock = parseRecordClock(pair[1], `${path}[1]`);
+            if (recordKeysByScope.has(clock.scopeToken)) {
+                hydrationInvalid(`${path}[1].scopeToken`);
+            }
+            recordClocks.set(key, clock);
+            recordKeysByScope.set(clock.scopeToken, key);
+        }
+        const anonymousRecordClocks = new Map();
+        for (const [index, entry] of hydrationArray(payload.anonymousRecordClocks, 'state.payload.anonymousRecordClocks').entries()) {
+            const path = `state.payload.anonymousRecordClocks[${index}]`;
+            const pair = hydrationPair(entry, path);
+            const scopeToken = hydrationOpaque(pair[0], `${path}[0]`);
+            if (anonymousRecordClocks.has(scopeToken) ||
+                recordKeysByScope.has(scopeToken)) {
+                hydrationInvalid(`${path}[0]`);
+            }
+            const raw = hydrationRecord(pair[1], `${path}[1]`, ['model', 'clock']);
+            const clock = parseRecordClock(raw.clock, `${path}[1].clock`);
+            if (clock.scopeToken !== scopeToken) {
+                hydrationInvalid(`${path}[1].clock.scopeToken`);
+            }
+            anonymousRecordClocks.set(scopeToken, Object.freeze({
+                model: hydrationString(raw.model, `${path}[1].model`),
+                clock
+            }));
+        }
+        const trustedPresets = canonicalTrustedPresets(parseDistributedTrustedPresetInventory(payload.trustedPresets, 'state.payload.trustedPresets'));
+        const nextIndexRevision = hydrationDecimal(payload.nextIndexRevision, 'state.payload.nextIndexRevision');
+        for (const group of operationProtocols.values()) {
+            for (const operation of [group.query, group.live]) {
+                if (operation?.indexRevision !== undefined &&
+                    compareDistributedDecimal(operation.indexRevision, nextIndexRevision) > 0) {
+                    hydrationInvalid('state.payload.nextIndexRevision');
+                }
+            }
+        }
+        return {
+            scope,
+            cache,
+            operationProtocols,
+            operationGenerations,
+            recordClocks,
+            recordKeysByScope,
+            anonymousRecordClocks,
+            trustedPresets,
+            nextIndexRevision
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parseOperationProtocolState(value, path) {
+    const raw = hydrationRecord(value, path, [
+        'operation',
+        'snapshotScope',
+        'indexClocks',
+        'indexRevision',
+        'indexKeys',
+        'pathRecords',
+        'cursors'
+    ], ['operation', 'indexClocks', 'indexKeys', 'pathRecords', 'cursors']);
+    const indexClocks = new Map();
+    for (const [index, entry] of hydrationArray(raw.indexClocks, `${path}.indexClocks`).entries()) {
+        const entryPath = `${path}.indexClocks[${index}]`;
+        const pair = hydrationPair(entry, entryPath);
+        const projection = hydrationString(pair[0], `${entryPath}[0]`);
+        if (indexClocks.has(projection))
+            hydrationInvalid(`${entryPath}[0]`);
+        const clock = hydrationRecord(pair[1], `${entryPath}[1]`, ['scopeToken', 'position']);
+        indexClocks.set(projection, Object.freeze({
+            scopeToken: hydrationOpaque(clock.scopeToken, `${entryPath}[1].scopeToken`),
+            position: hydrationDecimal(clock.position, `${entryPath}[1].position`)
+        }));
+    }
+    const indexKeys = new Set();
+    for (const [index, entry] of hydrationArray(raw.indexKeys, `${path}.indexKeys`).entries()) {
+        const key = hydrationString(entry, `${path}.indexKeys[${index}]`);
+        if (indexKeys.has(key))
+            hydrationInvalid(`${path}.indexKeys[${index}]`);
+        indexKeys.add(key);
+    }
+    const pathRecords = new Map();
+    for (const [index, entry] of hydrationArray(raw.pathRecords, `${path}.pathRecords`).entries()) {
+        const entryPath = `${path}.pathRecords[${index}]`;
+        const pair = hydrationPair(entry, entryPath);
+        const responsePath = hydrationString(pair[0], `${entryPath}[0]`);
+        if (pathRecords.has(responsePath))
+            hydrationInvalid(`${entryPath}[0]`);
+        pathRecords.set(responsePath, hydrationString(pair[1], `${entryPath}[1]`));
+    }
+    const cursors = hydrationArray(raw.cursors, `${path}.cursors`).map((entry, index) => {
+        const entryPath = `${path}.cursors[${index}]`;
+        const cursor = hydrationRecord(entry, entryPath, ['projection', 'position', 'token']);
+        return Object.freeze({
+            projection: hydrationString(cursor.projection, `${entryPath}.projection`),
+            position: hydrationDecimal(cursor.position, `${entryPath}.position`),
+            token: hydrationOpaque(cursor.token, `${entryPath}.token`)
+        });
+    });
+    return {
+        operation: hydrationString(raw.operation, `${path}.operation`),
+        ...(raw.snapshotScope === undefined
+            ? {}
+            : {
+                snapshotScope: hydrationOpaque(raw.snapshotScope, `${path}.snapshotScope`)
+            }),
+        indexClocks,
+        ...(raw.indexRevision === undefined
+            ? {}
+            : {
+                indexRevision: hydrationDecimal(raw.indexRevision, `${path}.indexRevision`)
+            }),
+        indexKeys,
+        pathRecords,
+        cursors: Object.freeze(cursors)
+    };
+}
+export function parseRecordClock(value, path) {
+    const raw = hydrationRecord(value, path, ['scopeToken', 'incarnation', 'revision', 'tombstone']);
+    if (typeof raw.tombstone !== 'boolean')
+        hydrationInvalid(`${path}.tombstone`);
+    return Object.freeze({
+        scopeToken: hydrationOpaque(raw.scopeToken, `${path}.scopeToken`),
+        incarnation: hydrationDecimal(raw.incarnation, `${path}.incarnation`),
+        revision: hydrationDecimal(raw.revision, `${path}.revision`),
+        tombstone: raw.tombstone
+    });
+}
+export function hydrationRecord(value, path, allowed, required = allowed) {
+    if (!isHydrationRecord(value))
+        hydrationInvalid(path);
+    const allowedKeys = new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!allowedKeys.has(key))
+            hydrationInvalid(`${path}.${key}`);
+    }
+    for (const key of required) {
+        if (!Object.prototype.hasOwnProperty.call(value, key)) {
+            hydrationInvalid(`${path}.${key}`);
+        }
+    }
+    return value;
+}
+export function isHydrationRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function hydrationArray(value, path) {
+    if (!Array.isArray(value))
+        hydrationInvalid(path);
+    return value;
+}
+export function hydrationPair(value, path) {
+    if (!Array.isArray(value) || value.length !== 2)
+        hydrationInvalid(path);
+    return value;
+}
+export function hydrationString(value, path) {
+    if (typeof value !== 'string' || value.length === 0)
+        hydrationInvalid(path);
+    return value;
+}
+export function hydrationOpaque(value, path) {
+    return hydrationString(value, path);
+}
+export function hydrationDecimal(value, path) {
+    const string = hydrationString(value, path);
+    if (!/^(0|[1-9][0-9]*)$/.test(string))
+        hydrationInvalid(path);
+    return string;
+}
+export function hydrationGeneration(value, path) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        hydrationInvalid(path);
+    }
+    return value;
+}
+export function hydrationOperationSource(value, path) {
+    if (value !== 'query' && value !== 'live')
+        hydrationInvalid(path);
+    return value;
+}
+export function hydrationInvalid(path) {
+    throw new TypeError(`invalid replica hydration state at ${path}`);
+}

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

@@ -0,0 +1,22 @@
+import type { CacheEngine } from '../../internal/cache-engine.js';
+import type { ReplicaDiagnosticEventInput, ReplicaDiagnosticLayerInput, ReplicaDiagnosticsSink } from '../diagnostics.js';
+import type { GraphqlVariables } from '../../types.js';
+import type { ReplicaOperationArtifact } from '../types.js';
+import type { OptimisticReceiptState, ProtocolGeneration } from './types.js';
+/**
+ * Host for diagnostics sync and event emission.
+ */
+export type DiagnosticsHost = {
+    readonly engine: CacheEngine;
+    readonly diagnostics: ReplicaDiagnosticsSink | undefined;
+    readonly diagnosticLayers: Map<string, ReplicaDiagnosticLayerInput> | undefined;
+    readonly optimisticReceipts: Map<string, OptimisticReceiptState>;
+    readonly reportObserverError: (error: AggregateError) => void;
+    getProtocolGeneration(): ProtocolGeneration | undefined;
+    getProtocolGenerationSequence(): number;
+};
+export declare function syncDiagnostics(host: DiagnosticsHost): void;
+export declare function diagnosticEvent(host: DiagnosticsHost, event: ReplicaDiagnosticEventInput): void;
+export declare function diagnosticOperation<TData, TVariables extends GraphqlVariables>(host: DiagnosticsHost, artifact: ReplicaOperationArtifact<TData, TVariables>): void;
+export declare function diagnosticScopeTransition(host: DiagnosticsHost, previous: ProtocolGeneration | undefined, next: ProtocolGeneration): void;
+export declare function retireDiagnosticLayer(host: DiagnosticsHost, id: string, action: 'retired' | 'rejected', receiptState: 'projected' | 'rejected', receipt?: OptimisticReceiptState): void;

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

@@ -0,0 +1,189 @@
+import { modelFromRecordKey } from './clocks.js';
+import { diagnosticReceiptCounts, diagnosticReceiptExpectations } from './optimistic.js';
+import { reportSafely } from './helpers.js';
+export function syncDiagnostics(host) {
+    const diagnostics = host.diagnostics;
+    if (diagnostics === undefined)
+        return;
+    try {
+        const cache = host.engine.extract();
+        const records = cache.records.map((record) => {
+            const model = modelFromRecordKey(record.key);
+            const tombstone = record.tombstoneRevision !== undefined;
+            const values = {};
+            if (!tombstone && diagnostics.redactRecordValue !== undefined) {
+                for (const [field, entry] of Object.entries(record.fields)) {
+                    const value = diagnostics.redactRecordValue(Object.freeze({
+                        recordKey: record.key,
+                        ...(model === undefined ? {} : { model }),
+                        field,
+                        kind: 'field'
+                    }), entry.value);
+                    if (value !== undefined)
+                        values[field] = value;
+                }
+                for (const [field, entry] of Object.entries(record.links)) {
+                    const value = diagnostics.redactRecordValue(Object.freeze({
+                        recordKey: record.key,
+                        ...(model === undefined ? {} : { model }),
+                        field,
+                        kind: 'link'
+                    }), entry.value);
+                    if (value !== undefined)
+                        values[field] = value;
+                }
+            }
+            return Object.freeze({
+                key: record.key,
+                ...(model === undefined ? {} : { model }),
+                revision: record.revision,
+                incarnation: record.incarnation ?? record.revision,
+                tombstone,
+                ...(record.tombstoneRevision === undefined
+                    ? {}
+                    : { tombstoneRevision: record.tombstoneRevision }),
+                presentFields: Object.freeze(tombstone ? [] : Object.keys(record.fields).sort()),
+                presentLinks: Object.freeze(tombstone ? [] : Object.keys(record.links).sort()),
+                ...(Object.keys(values).length === 0
+                    ? {}
+                    : { values: Object.freeze(values) })
+            });
+        });
+        const indexes = cache.indexes.map((index) => Object.freeze({
+            key: index.key,
+            revision: index.revision,
+            ...(index.staleRevision === undefined
+                ? {}
+                : { staleRevision: index.staleRevision }),
+            records: index.records,
+            complete: index.complete,
+            deleted: index.deleted,
+            ...(index.metadata === undefined
+                ? {}
+                : {
+                    field: index.metadata.field,
+                    ...(index.metadata.parent === undefined
+                        ? {}
+                        : { parent: index.metadata.parent }),
+                    argumentNames: Object.freeze(Object.keys(index.metadata.arguments).sort()),
+                    ...(diagnostics.includeStructuralIdentities
+                        ? { arguments: index.metadata.arguments }
+                        : {}),
+                    coverage: index.metadata.coverage,
+                    dependencies: index.metadata.dependencies,
+                    ...(index.metadata.staleReason === undefined
+                        ? {}
+                        : { staleReason: index.metadata.staleReason }),
+                    nullValue: index.metadata.nullValue === true
+                })
+        }));
+        const receipts = [];
+        for (const layer of host.diagnosticLayers?.values() ?? []) {
+            const receipt = host.optimisticReceipts.get(layer.id);
+            receipts.push(Object.freeze({
+                commandId: layer.id,
+                state: receipt === undefined
+                    ? 'optimistic'
+                    : receipt.expectations.size === 0
+                        ? 'accepted'
+                        : 'accepted_pending_projection',
+                expectations: receipt === undefined
+                    ? Object.freeze([])
+                    : diagnosticReceiptExpectations(receipt)
+            }));
+        }
+        const scope = host.getProtocolGeneration();
+        diagnostics.update(Object.freeze({
+            scope: scope === undefined
+                ? Object.freeze({
+                    generation: host.getProtocolGenerationSequence(),
+                    established: false
+                })
+                : Object.freeze({
+                    generation: host.getProtocolGenerationSequence(),
+                    established: true,
+                    protocolVersion: 1,
+                    schemaHash: scope.schemaHash
+                }),
+            records: Object.freeze(records),
+            indexes: Object.freeze(indexes),
+            layers: Object.freeze([
+                ...(host.diagnosticLayers?.values() ?? [])
+            ]),
+            receipts: Object.freeze(receipts)
+        }));
+    }
+    catch (error) {
+        reportSafely(host.reportObserverError, new AggregateError([error], 'replica diagnostics update failed'));
+    }
+}
+export function diagnosticEvent(host, event) {
+    if (host.diagnostics === undefined)
+        return;
+    try {
+        host.diagnostics.event(event);
+    }
+    catch (error) {
+        reportSafely(host.reportObserverError, new AggregateError([error], 'replica diagnostics event failed'));
+    }
+}
+export function diagnosticOperation(host, artifact) {
+    if (host.diagnostics === undefined)
+        return;
+    try {
+        host.diagnostics.operation(artifact);
+    }
+    catch (error) {
+        reportSafely(host.reportObserverError, new AggregateError([error], 'replica diagnostic artifact failed'));
+    }
+}
+export function diagnosticScopeTransition(host, previous, next) {
+    if (host.diagnostics === undefined)
+        return;
+    if (previous !== undefined &&
+        previous.cacheScope === next.cacheScope &&
+        previous.schemaHash === next.schemaHash) {
+        return;
+    }
+    diagnosticEvent(host, Object.freeze({
+        kind: 'scope',
+        action: previous === undefined ? 'established' : 'changed',
+        generation: host.getProtocolGenerationSequence(),
+        schemaHash: next.schemaHash
+    }));
+}
+export function retireDiagnosticLayer(host, id, action, receiptState, receipt) {
+    const layers = host.diagnosticLayers;
+    const removed = layers?.get(id);
+    if (removed === undefined)
+        return;
+    layers.delete(id);
+    diagnosticEvent(host, Object.freeze({
+        kind: 'layer',
+        layer: id,
+        action,
+        recordChanges: removed.recordChanges,
+        indexChanges: removed.indexChanges
+    }));
+    const causal = receipt ?? host.optimisticReceipts.get(id);
+    const counts = diagnosticReceiptCounts(causal);
+    diagnosticEvent(host, Object.freeze({
+        kind: 'receipt',
+        command: id,
+        state: receiptState,
+        obligations: counts.obligations,
+        observed: counts.observed
+    }));
+    for (const layer of layers.values()) {
+        if (layer.sequence <= removed.sequence)
+            continue;
+        diagnosticEvent(host, Object.freeze({
+            kind: 'layer',
+            layer: layer.id,
+            action: 'rebased',
+            recordChanges: layer.recordChanges,
+            indexChanges: layer.indexChanges,
+            reason: `${action}-earlier-layer`
+        }));
+    }
+}

package/dist/replica/distributed-replica/impl-fetch-live.d.ts

@@ -0,0 +1,39 @@
+import type { GraphqlVariables } from '../../types.js';
+import { type DistributedLiveCursor, type DistributedProtocolEnvelope } from '../../protocol.js';
+import type { ReplicaDiagnosticEventInput } from '../diagnostics.js';
+import type { ReplicaOperationArtifact, ReplicaResultEnvelope, ReplicaTransport, ReplicaWriteSource } from '../types.js';
+import type { LiveEntry, OperationProtocolGroup, ProtocolGeneration, QueryState } from './types.js';
+import type { ReplicaWatchState } from './watch.js';
+/**
+ * Host accessors for fetch / live subscription orchestration.
+ * Free functions never read private class fields; the class supplies state.
+ */
+export type FetchLiveHost = {
+    readonly transport: ReplicaTransport | undefined;
+    readonly inFlight: Map<string, Promise<void>>;
+    readonly inFlightAborts: Map<string, AbortController>;
+    readonly lives: Map<string, LiveEntry>;
+    readonly watches: Map<string, Set<ReplicaWatchState<unknown, GraphqlVariables>>>;
+    readonly operationProtocols: Map<string, OperationProtocolGroup>;
+    readonly diagnostics: {
+        readonly enabled: boolean;
+    };
+    protocolGenerationSequence(): number;
+    projectionGeneration(): number;
+    protocolGeneration(): ProtocolGeneration | undefined;
+    queryState(key: string): QueryState;
+    emitState(key: string, allowFetch: boolean): void;
+    operationGeneration(key: string): number;
+    allocateIndexRevision(): string;
+    writeCanonicalResult<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>, stableVariables: TVariables, envelope: ReplicaResultEnvelope<TData>, source: ReplicaWriteSource, requestRevision?: string, responseProjectionGeneration?: number): DistributedProtocolEnvelope;
+    diagnosticEvent(event: ReplicaDiagnosticEventInput): void;
+    resumeCursors(key: string): readonly DistributedLiveCursor[];
+};
+export declare function emitWatchState(host: FetchLiveHost, key: string, allowFetch: boolean): void;
+export declare function closeActiveTransports(host: FetchLiveHost): void;
+export declare function fetchWatch<TData, TVariables extends GraphqlVariables>(host: FetchLiveHost, watch: ReplicaWatchState<TData, TVariables>, force: boolean): Promise<void>;
+export declare function retainLive<TData, TVariables extends GraphqlVariables>(host: FetchLiveHost, watch: ReplicaWatchState<TData, TVariables>): void;
+export declare function fallbackFromLive<TData, TVariables extends GraphqlVariables>(host: FetchLiveHost, watch: ReplicaWatchState<TData, TVariables>, entry: LiveEntry): void;
+export declare function restartLive(host: FetchLiveHost, key: string): void;
+export declare function resumeLiveWatches(host: FetchLiveHost): void;
+export declare function releaseLive(host: FetchLiveHost, key: string): void;