@hops-ops/distributed 0.0.0

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

@@ -0,0 +1,299 @@
+import { createCacheEngine } from '../../internal/cache-engine.js';
+import { matchReplicaTrustedPresetInventory } from '../commands.js';
+import { replicaIndexKey, resolveArguments } from '../identity.js';
+import { runtimeRoot } from '../selection.js';
+import { freezeRecordClock } from './clocks.js';
+import { trustedPresetInventoryFingerprint } from './helpers.js';
+import { hydrationMetadataConsistent, parseAuthoritativeScope, parseReplicaHydration, serializeOperationProtocolGroup } from './hydration.js';
+export function reachableConfirmedState(host) {
+    const snapshot = host.engine.extract();
+    const indexes = new Map(snapshot.indexes.map((index) => [index.key, index]));
+    const records = new Map(snapshot.records.map((record) => [record.key, record]));
+    const indexKeys = new Set();
+    const recordKeys = new Set();
+    const clockRecordKeys = new Set();
+    const recordFields = new Map();
+    const models = new Set();
+    const rememberSelection = (selection) => {
+        if (selection.storage.kind === 'normalized') {
+            models.add(selection.storage.model);
+        }
+        for (const member of selection.members) {
+            if (member.kind === 'branch')
+                rememberSelection(member.selection);
+        }
+    };
+    const rememberRecord = (recordKey, selection) => {
+        recordKeys.add(recordKey);
+        clockRecordKeys.add(recordKey);
+        let selected = recordFields.get(recordKey);
+        if (selected === undefined) {
+            selected = new Set();
+            recordFields.set(recordKey, selected);
+        }
+        for (const member of selection.members) {
+            if (member.kind === 'scalar')
+                selected.add(member.field);
+        }
+    };
+    const visitObject = (selection, recordKey, variables) => {
+        rememberRecord(recordKey, selection);
+        for (const member of selection.members) {
+            if (member.kind !== 'branch')
+                continue;
+            visitBranch(member, recordKey, variables);
+        }
+    };
+    const visitBranch = (selection, parent, variables) => {
+        const key = replicaIndexKey({
+            ...(parent === undefined ? {} : { parent }),
+            field: selection.field,
+            arguments: resolveArguments(selection.arguments, variables, selection.coverage)
+        });
+        const index = indexes.get(key);
+        if (index === undefined)
+            return;
+        indexKeys.add(key);
+        for (const recordKey of index.records) {
+            visitObject(selection.selection, recordKey, variables);
+        }
+    };
+    for (const [key, rendered] of host.renderedOperations) {
+        for (const rootArtifact of rendered.artifact.roots) {
+            const root = runtimeRoot(rootArtifact);
+            rememberSelection(root.selection);
+            visitBranch(root, undefined, rendered.variables);
+        }
+        const group = host.operationProtocols.get(key);
+        for (const state of [group?.query, group?.live]) {
+            for (const recordKey of state?.pathRecords.values() ?? []) {
+                clockRecordKeys.add(recordKey);
+            }
+        }
+    }
+    return Object.freeze({
+        cache: Object.freeze({
+            version: 1,
+            records: Object.freeze([...recordKeys]
+                .sort()
+                .flatMap((key) => {
+                const record = records.get(key);
+                if (record === undefined)
+                    return [];
+                const selected = recordFields.get(key) ?? new Set();
+                return [
+                    Object.freeze({
+                        ...record,
+                        fields: Object.freeze(Object.fromEntries(Object.entries(record.fields).filter(([field]) => selected.has(field)))),
+                        links: Object.freeze({})
+                    })
+                ];
+            })),
+            indexes: Object.freeze([...indexKeys]
+                .sort()
+                .flatMap((key) => {
+                const index = indexes.get(key);
+                return index === undefined ? [] : [index];
+            }))
+        }),
+        recordKeys,
+        clockRecordKeys,
+        models
+    });
+}
+export function finishDehydration(host) {
+    let plansChanged = false;
+    for (const key of host.readOperationKeys) {
+        if (!host.watchRenderCounts.has(key)) {
+            host.renderedOperations.delete(key);
+            const registration = host.indexPlanRegistrations.get(key);
+            if (registration !== undefined) {
+                host.indexPlanRegistrations.delete(key);
+                registration.dispose();
+                plansChanged = true;
+            }
+        }
+    }
+    host.readOperationKeys.clear();
+    if (plansChanged)
+        host.refreshIndexMaintenance();
+}
+export function dehydrateReplica(host) {
+    const scope = host.getProtocolGeneration();
+    if (scope === undefined) {
+        throw new Error('cannot dehydrate replica before the server establishes an authoritative scope');
+    }
+    const reachable = reachableConfirmedState(host);
+    const reachableIndexKeys = new Set(reachable.cache.indexes.map((index) => index.key));
+    const operationKeys = new Set(host.renderedOperations.keys());
+    for (const [key, group] of host.operationProtocols) {
+        const governsReachableState = [group.query, group.live].some((state) => state !== undefined &&
+            ([...state.indexKeys].some((indexKey) => reachableIndexKeys.has(indexKey)) ||
+                [...state.pathRecords.values()].some((recordKey) => reachable.clockRecordKeys.has(recordKey))));
+        if (governsReachableState)
+            operationKeys.add(key);
+    }
+    const operations = [...operationKeys]
+        .sort()
+        .flatMap((key) => {
+        const group = host.operationProtocols.get(key);
+        if (group === undefined)
+            return [];
+        return [
+            serializeOperationProtocolGroup(key, group, host.operationGeneration(key))
+        ];
+    });
+    const recordClocks = [...host.recordClocks]
+        .filter(([key]) => reachable.clockRecordKeys.has(key))
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, clock]) => Object.freeze([key, freezeRecordClock(clock)]));
+    const anonymousRecordClocks = [...host.anonymousRecordClocks]
+        .filter(([, value]) => reachable.models.has(value.model))
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([scopeToken, value]) => Object.freeze([
+        scopeToken,
+        Object.freeze({
+            model: value.model,
+            clock: freezeRecordClock(value.clock)
+        })
+    ]));
+    const payload = Object.freeze({
+        cache: reachable.cache,
+        operations: Object.freeze(operations),
+        recordClocks: Object.freeze(recordClocks),
+        anonymousRecordClocks: Object.freeze(anonymousRecordClocks),
+        trustedPresets: host.getTrustedPresets(),
+        nextIndexRevision: host.getNextIndexRevision()
+    });
+    const state = Object.freeze({
+        version: 1,
+        scope: Object.freeze({
+            protocolVersion: 1,
+            schemaHash: scope.schemaHash,
+            cacheScope: scope.cacheScope
+        }),
+        payload
+    });
+    host.finishDehydration();
+    return state;
+}
+export function hydrateReplica(host, state, authoritativeScope) {
+    const rejected = (reason) => {
+        if (host.diagnostics.enabled) {
+            host.diagnosticEvent(Object.freeze({ kind: 'hydration', action: 'rejected', reason }));
+        }
+        return false;
+    };
+    const parsed = parseReplicaHydration(state);
+    const expectedScope = parseAuthoritativeScope(authoritativeScope);
+    if (parsed === undefined || expectedScope === undefined) {
+        return rejected('invalid');
+    }
+    if (parsed.scope.protocolVersion !== expectedScope.protocolVersion ||
+        parsed.scope.schemaHash !== expectedScope.schemaHash ||
+        parsed.scope.cacheScope !== expectedScope.cacheScope) {
+        return rejected('scope-mismatch');
+    }
+    const binding = host.getArtifactBinding();
+    if (binding !== undefined &&
+        binding.schemaHash !== parsed.scope.schemaHash) {
+        return rejected('artifact-mismatch');
+    }
+    const current = host.getProtocolGeneration();
+    if (current !== undefined &&
+        (current.protocolVersion !== parsed.scope.protocolVersion ||
+            current.schemaHash !== parsed.scope.schemaHash ||
+            current.cacheScope !== parsed.scope.cacheScope)) {
+        return rejected('active-scope-mismatch');
+    }
+    const preserveLocalCommandState = current !== undefined;
+    // Validate the private engine payload before closing transports or changing
+    // any live state. `restore` parses fully before its own transaction.
+    try {
+        createCacheEngine().restore(parsed.cache);
+        const expectedTrustedPresets = binding?.trustedPresets !== undefined
+            ? binding.trustedPresets
+            : host.getCommandAuthorityContract()?.trustedPresets;
+        if (expectedTrustedPresets !== undefined) {
+            matchReplicaTrustedPresetInventory(expectedTrustedPresets, parsed.trustedPresets);
+        }
+        if (preserveLocalCommandState &&
+            trustedPresetInventoryFingerprint(host.getTrustedPresets()) !==
+                trustedPresetInventoryFingerprint(parsed.trustedPresets)) {
+            throw new TypeError('trusted presets changed within one authoritative cache scope');
+        }
+    }
+    catch {
+        return rejected('invalid');
+    }
+    if (!hydrationMetadataConsistent(parsed)) {
+        return rejected('metadata-mismatch');
+    }
+    if (preserveLocalCommandState) {
+        host.closeActiveTransports();
+    }
+    else {
+        host.closeAuthorizationGeneration();
+    }
+    host.queryStates.clear();
+    host.operationProtocols.clear();
+    for (const [key, group] of parsed.operationProtocols) {
+        host.operationProtocols.set(key, group);
+    }
+    host.operationGenerations.clear();
+    for (const [key, generation] of parsed.operationGenerations) {
+        host.operationGenerations.set(key, generation);
+    }
+    host.recordClocks.clear();
+    for (const [key, clock] of parsed.recordClocks) {
+        host.recordClocks.set(key, clock);
+    }
+    host.recordKeysByScope.clear();
+    for (const [scopeToken, key] of parsed.recordKeysByScope) {
+        host.recordKeysByScope.set(scopeToken, key);
+    }
+    host.anonymousRecordClocks.clear();
+    for (const [scopeToken, clock] of parsed.anonymousRecordClocks) {
+        host.anonymousRecordClocks.set(scopeToken, clock);
+    }
+    if (!preserveLocalCommandState) {
+        host.optimisticReceipts.clear();
+        host.diagnosticLayers?.clear();
+        host.setDiagnosticLayerSequence(0);
+    }
+    host.setTrustedPresets(parsed.trustedPresets);
+    host.setNextIndexRevision(parsed.nextIndexRevision);
+    host.setProtocolGeneration(parsed.scope);
+    host.setArtifactBinding(Object.freeze({
+        version: 1,
+        schemaHash: parsed.scope.schemaHash,
+        ...(binding?.surfaceIdentity !== undefined
+            ? { surfaceIdentity: binding.surfaceIdentity }
+            : {}),
+        ...(binding?.trustedPresets !== undefined
+            ? { trustedPresets: binding.trustedPresets }
+            : {})
+    }));
+    if (preserveLocalCommandState) {
+        host.engine.restoreConfirmed(parsed.cache);
+    }
+    else {
+        host.engine.restore(parsed.cache);
+    }
+    host.resumeLiveWatches();
+    host.syncDiagnostics();
+    if (host.diagnostics.enabled) {
+        host.diagnosticEvent(Object.freeze({
+            kind: 'hydration',
+            action: 'accepted',
+            reason: 'accepted'
+        }));
+        host.diagnosticEvent(Object.freeze({
+            kind: 'scope',
+            action: 'established',
+            generation: host.getProtocolGenerationSequence(),
+            schemaHash: parsed.scope.schemaHash
+        }));
+    }
+    return true;
+}

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

@@ -0,0 +1,31 @@
+import type { CacheEngine } from '../../internal/cache-engine.js';
+import { type DistributedCommandMetadata, type DistributedProjectionObservation } from '../../protocol.js';
+import type { ReplicaDiagnosticEventInput, ReplicaDiagnosticLayerInput } from '../diagnostics.js';
+import type { ReplicaIndexSemanticChange } from '../index-maintenance.js';
+import type { ReplicaBaseWriter, ReplicaOptimisticWriter } from '../types.js';
+import type { OptimisticReceiptState } from './types.js';
+/**
+ * Host for optimistic layer lifecycle and receipt planning.
+ */
+export type OptimisticHost = {
+    readonly engine: CacheEngine;
+    readonly optimisticReceipts: Map<string, OptimisticReceiptState>;
+    readonly diagnosticLayers: Map<string, ReplicaDiagnosticLayerInput> | undefined;
+    readonly diagnostics: {
+        readonly enabled: boolean;
+    };
+    getDiagnosticLayerSequence(): number;
+    setDiagnosticLayerSequence(value: number): void;
+    diagnosticEvent(event: ReplicaDiagnosticEventInput): void;
+    syncDiagnostics(): void;
+    retireDiagnosticLayer(id: string, action: 'retired' | 'rejected', receiptState: 'projected' | 'rejected', receipt?: OptimisticReceiptState): void;
+};
+export declare function createOptimisticLayerOn(host: OptimisticHost, id: string, update: (writer: ReplicaOptimisticWriter) => void, semanticChanges?: readonly ReplicaIndexSemanticChange[]): void;
+export declare function markOptimisticLayerAcceptedOn(host: OptimisticHost, id: string, receipt?: DistributedCommandMetadata): boolean;
+export declare function confirmOptimisticLayerOn<T>(host: OptimisticHost, id: string, update: (writer: ReplicaBaseWriter) => T): T;
+export declare function rejectOptimisticLayerOn(host: OptimisticHost, id: string): boolean;
+export declare function planOptimisticReceipts(host: OptimisticHost, command: DistributedCommandMetadata | undefined, observations: readonly DistributedProjectionObservation[], satisfactionAdmissible: boolean): {
+    updates: Map<string, OptimisticReceiptState>;
+    satisfied: string[];
+};
+export declare function applyReceiptOnly(host: OptimisticHost, command: DistributedCommandMetadata | undefined): void;

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

@@ -0,0 +1,172 @@
+import { DistributedProtocolError } from '../../protocol.js';
+import { protocolInvalid } from './clocks.js';
+import { baseWriter } from './helpers.js';
+import { assertReplicaOptimisticLayerId, captureReplicaOptimisticUpdate, cloneOptimisticReceipt, diagnosticReceiptCounts, expectationKey, optimisticReceiptState, replayReplicaOptimisticUpdate, sameReceipt } from './optimistic.js';
+export function createOptimisticLayerOn(host, id, update, semanticChanges = Object.freeze([])) {
+    assertReplicaOptimisticLayerId(id);
+    if (host.engine.optimisticLayerState(id) !== undefined) {
+        throw new Error(`optimistic layer already exists: ${id}`);
+    }
+    if (typeof update !== 'function') {
+        throw new TypeError('optimistic layer update must be a function');
+    }
+    const captured = captureReplicaOptimisticUpdate(id, update, semanticChanges);
+    host.engine.createOptimisticLayer(id, (writer) => replayReplicaOptimisticUpdate(writer, captured.operations), captured.context);
+    if (host.diagnosticLayers !== undefined) {
+        const recordChanges = captured.operations.filter((operation) => operation.kind === 'write-record' ||
+            operation.kind === 'tombstone-record').length;
+        const indexChanges = captured.operations.length - recordChanges;
+        const nextSequence = host.getDiagnosticLayerSequence() + 1;
+        host.setDiagnosticLayerSequence(nextSequence);
+        const layer = Object.freeze({
+            id,
+            sequence: nextSequence,
+            state: 'optimistic',
+            recordChanges,
+            indexChanges,
+            semanticChanges: recordChanges + semanticChanges.length
+        });
+        host.diagnosticLayers.set(id, layer);
+        host.diagnosticEvent(Object.freeze({
+            kind: 'layer',
+            layer: id,
+            action: 'created',
+            recordChanges,
+            indexChanges
+        }));
+        host.diagnosticEvent(Object.freeze({
+            kind: 'receipt',
+            command: id,
+            state: 'optimistic',
+            obligations: 0,
+            observed: 0
+        }));
+        host.syncDiagnostics();
+    }
+}
+export function markOptimisticLayerAcceptedOn(host, id, receipt) {
+    if (receipt !== undefined && receipt.commandId !== id) {
+        throw new TypeError('optimistic layer id must equal the causal command id');
+    }
+    const accepted = host.engine.markOptimisticLayerAccepted(id);
+    if (!accepted)
+        return false;
+    const diagnosticLayer = host.diagnosticLayers?.get(id);
+    if (diagnosticLayer !== undefined) {
+        host.diagnosticLayers.set(id, Object.freeze({ ...diagnosticLayer, state: 'accepted' }));
+        host.diagnosticEvent(Object.freeze({
+            kind: 'layer',
+            layer: id,
+            action: 'accepted',
+            recordChanges: diagnosticLayer.recordChanges,
+            indexChanges: diagnosticLayer.indexChanges
+        }));
+    }
+    if (receipt === undefined) {
+        if (host.diagnostics.enabled) {
+            host.diagnosticEvent(Object.freeze({
+                kind: 'receipt',
+                command: id,
+                state: 'accepted',
+                obligations: 0,
+                observed: 0
+            }));
+        }
+        host.syncDiagnostics();
+        return true;
+    }
+    const next = optimisticReceiptState(receipt);
+    const current = host.optimisticReceipts.get(id);
+    if (current !== undefined && !sameReceipt(current, next)) {
+        throw new DistributedProtocolError('DISTRIBUTED_PROTOCOL_INVALID', 'extensions.distributed.command');
+    }
+    host.optimisticReceipts.set(id, next);
+    if (host.diagnostics.enabled) {
+        const counts = diagnosticReceiptCounts(next);
+        host.diagnosticEvent(Object.freeze({
+            kind: 'receipt',
+            command: id,
+            state: counts.obligations === 0
+                ? 'accepted'
+                : 'accepted_pending_projection',
+            obligations: counts.obligations,
+            observed: counts.observed
+        }));
+    }
+    host.syncDiagnostics();
+    return true;
+}
+export function confirmOptimisticLayerOn(host, id, update) {
+    const result = host.engine.confirmOptimisticLayer(id, (writer) => update(baseWriter(writer)));
+    host.retireDiagnosticLayer(id, 'retired', 'projected');
+    host.optimisticReceipts.delete(id);
+    host.syncDiagnostics();
+    return result;
+}
+export function rejectOptimisticLayerOn(host, id) {
+    const rejected = host.engine.rejectOptimisticLayer(id);
+    if (rejected) {
+        host.retireDiagnosticLayer(id, 'rejected', 'rejected');
+        host.optimisticReceipts.delete(id);
+        host.syncDiagnostics();
+    }
+    return rejected;
+}
+export function planOptimisticReceipts(host, command, observations, satisfactionAdmissible) {
+    const updates = new Map();
+    if (command !== undefined &&
+        host.engine.optimisticLayerState(command.commandId) !== undefined) {
+        const proposed = optimisticReceiptState(command);
+        const current = host.optimisticReceipts.get(command.commandId);
+        if (current !== undefined && !sameReceipt(current, proposed)) {
+            protocolInvalid('extensions.distributed.command');
+        }
+        updates.set(command.commandId, cloneOptimisticReceipt(current ?? proposed));
+    }
+    for (const [id, receipt] of host.optimisticReceipts) {
+        if (!updates.has(id)) {
+            updates.set(id, cloneOptimisticReceipt(receipt));
+        }
+    }
+    for (const receipt of updates.values()) {
+        for (const observation of observations) {
+            if (observation.causationId !== receipt.causationId)
+                continue;
+            const key = expectationKey(observation);
+            if (receipt.expectations.has(key))
+                receipt.observed.add(key);
+        }
+    }
+    const satisfied = satisfactionAdmissible
+        ? [...updates]
+            .filter(([, receipt]) => receipt.expectations.size > 0 &&
+            [...receipt.expectations.keys()].every((key) => receipt.observed.has(key)))
+            .map(([id]) => id)
+        : [];
+    return { updates, satisfied };
+}
+export function applyReceiptOnly(host, command) {
+    if (command === undefined)
+        return;
+    const plan = planOptimisticReceipts(host, command, command.observations, true);
+    for (const [id, receipt] of plan.updates) {
+        host.optimisticReceipts.set(id, receipt);
+        host.engine.markOptimisticLayerAccepted(id);
+        const layer = host.diagnosticLayers?.get(id);
+        if (layer !== undefined) {
+            host.diagnosticLayers.set(id, Object.freeze({ ...layer, state: 'accepted' }));
+        }
+        if (host.diagnostics.enabled) {
+            const counts = diagnosticReceiptCounts(receipt);
+            host.diagnosticEvent(Object.freeze({
+                kind: 'receipt',
+                command: id,
+                state: counts.obligations === 0
+                    ? 'accepted'
+                    : 'accepted_pending_projection',
+                obligations: counts.obligations,
+                observed: counts.observed
+            }));
+        }
+    }
+}

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

@@ -0,0 +1,53 @@
+import type { CacheEngine } from '../../internal/cache-engine.js';
+import type { GraphqlVariables } from '../../types.js';
+import type { DistributedOpaqueString, DistributedProtocolEnvelope, DistributedTrustedPreset } from '../../protocol.js';
+import type { ReplicaDiagnosticEventInput, ReplicaDiagnosticLayerInput } from '../diagnostics.js';
+import type { ReplicaIndexPlanRegistration } from '../index-maintenance.js';
+import type { ReplicaOperationArtifact, ReplicaWriteSource } from '../types.js';
+import type { AnonymousRecordProtocolClock, OperationProtocolGroup, OptimisticReceiptState, ProjectedRecordFence, ProtocolGeneration, QueryState, RecordProtocolClock, RegisteredCommandAuthorityContract, RenderedOperation } from './types.js';
+import type { ReplicaWatchState } from './watch.js';
+/**
+ * Host for protocol generation staging, purge, and authorization closeout.
+ */
+export type ProtocolHost = {
+    readonly engine: CacheEngine;
+    readonly queryStates: Map<string, QueryState>;
+    readonly operationProtocols: Map<string, OperationProtocolGroup>;
+    readonly operationGenerations: Map<string, number>;
+    readonly recordClocks: Map<string, RecordProtocolClock>;
+    readonly recordKeysByScope: Map<DistributedOpaqueString, string>;
+    readonly projectedRecordFences: Map<string, ProjectedRecordFence>;
+    readonly anonymousRecordClocks: Map<DistributedOpaqueString, AnonymousRecordProtocolClock>;
+    readonly optimisticReceipts: Map<string, OptimisticReceiptState>;
+    readonly diagnosticLayers: Map<string, ReplicaDiagnosticLayerInput> | undefined;
+    readonly indexPlanRegistrations: Map<string, ReplicaIndexPlanRegistration>;
+    readonly renderedOperations: Map<string, RenderedOperation>;
+    readonly readOperationKeys: Set<string>;
+    readonly watchRenderCounts: Map<string, number>;
+    readonly watches: Map<string, Set<ReplicaWatchState<unknown, GraphqlVariables>>>;
+    readonly diagnostics: {
+        readonly enabled: boolean;
+    };
+    getProtocolGeneration(): ProtocolGeneration | undefined;
+    setProtocolGeneration(value: ProtocolGeneration | undefined): void;
+    getProtocolGenerationSequence(): number;
+    bumpProtocolGenerationSequence(): void;
+    getTrustedPresets(): readonly DistributedTrustedPreset[];
+    setTrustedPresets(value: readonly DistributedTrustedPreset[]): void;
+    getCommandAuthorityContract(): RegisteredCommandAuthorityContract | undefined;
+    setProjectionGeneration(value: number): void;
+    setNextIndexRevision(value: string): void;
+    setDiagnosticLayerSequence(value: number): void;
+    clearIndexMaintenance(): void;
+    abortAuthorization(): void;
+    closeActiveTransports(): void;
+    syncDiagnostics(): void;
+    emitState(key: string, allowFetch: boolean): void;
+    diagnosticEvent(event: ReplicaDiagnosticEventInput): void;
+    rememberRenderedOperation<TData, TVariables extends GraphqlVariables>(key: string, artifact: ReplicaOperationArtifact<TData, TVariables>, variables: TVariables, source: 'read' | 'watch'): void;
+};
+export declare function validateProtocolBinding<TData, TVariables extends GraphqlVariables>(host: ProtocolHost, artifact: ReplicaOperationArtifact<TData, TVariables>, envelope: DistributedProtocolEnvelope, source: ReplicaWriteSource): void;
+export declare function stageProtocolGeneration(host: ProtocolHost, envelope: DistributedProtocolEnvelope): ProtocolGeneration;
+export declare function stageTrustedPresets<TData, TVariables extends GraphqlVariables>(host: ProtocolHost, incoming: readonly DistributedTrustedPreset[], nextGeneration: ProtocolGeneration, artifact: ReplicaOperationArtifact<TData, TVariables>): readonly DistributedTrustedPreset[];
+export declare function purgeProtocolGeneration(host: ProtocolHost): void;
+export declare function closeAuthorizationGeneration(host: ProtocolHost): void;

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

@@ -0,0 +1,108 @@
+import { matchReplicaTrustedPresetInventory } from '../commands.js';
+import { validateReplicaOperationBinding as validatedArtifactBinding } from '../operation-binding.js';
+import { protocolInvalid } from './clocks.js';
+import { EMPTY_CACHE_SNAPSHOT, EMPTY_TRUSTED_PRESETS } from './constants.js';
+import { canonicalTrustedPresets, trustedPresetDescriptorFingerprint, trustedPresetInventoryFingerprint } from './helpers.js';
+export function validateProtocolBinding(host, artifact, envelope, source) {
+    const binding = artifact.protocol;
+    if (binding === undefined) {
+        protocolInvalid('extensions.distributed');
+    }
+    if (binding.version !== 1) {
+        throw new TypeError('replica artifact protocol version is unsupported');
+    }
+    if (binding.schemaHash !== envelope.schemaHash) {
+        purgeProtocolGeneration(host);
+        protocolInvalid('extensions.distributed.schemaHash');
+    }
+    const expectedOperation = source === 'live' ? artifact.live?.id : binding.operation;
+    if (expectedOperation === undefined ||
+        envelope.operation !== expectedOperation) {
+        protocolInvalid('extensions.distributed.operation');
+    }
+}
+export function stageProtocolGeneration(host, envelope) {
+    const next = {
+        protocolVersion: 1,
+        cacheScope: envelope.cacheScope,
+        schemaHash: envelope.schemaHash
+    };
+    const current = host.getProtocolGeneration();
+    if (current === undefined)
+        return next;
+    if (current.cacheScope === next.cacheScope &&
+        current.schemaHash === next.schemaHash) {
+        return current;
+    }
+    purgeProtocolGeneration(host);
+    return next;
+}
+export function stageTrustedPresets(host, incoming, nextGeneration, artifact) {
+    const presets = canonicalTrustedPresets(incoming);
+    try {
+        const binding = validatedArtifactBinding(artifact);
+        const operationDescriptors = binding.trustedPresets;
+        const commandDescriptors = host.getCommandAuthorityContract()?.trustedPresets;
+        if (commandDescriptors !== undefined &&
+            trustedPresetDescriptorFingerprint(operationDescriptors) !==
+                trustedPresetDescriptorFingerprint(commandDescriptors)) {
+            throw new TypeError('operation and command trusted preset contracts differ');
+        }
+        matchReplicaTrustedPresetInventory(operationDescriptors, presets);
+        if (host.getProtocolGeneration() === nextGeneration &&
+            trustedPresetInventoryFingerprint(host.getTrustedPresets()) !==
+                trustedPresetInventoryFingerprint(presets)) {
+            throw new TypeError('trusted presets changed within one authoritative cache scope');
+        }
+        return presets;
+    }
+    catch {
+        if (host.getProtocolGeneration() !== undefined) {
+            purgeProtocolGeneration(host);
+        }
+        protocolInvalid('extensions.distributed.trustedPresets');
+    }
+}
+export function purgeProtocolGeneration(host) {
+    closeAuthorizationGeneration(host);
+    host.queryStates.clear();
+    host.operationProtocols.clear();
+    host.operationGenerations.clear();
+    host.recordClocks.clear();
+    host.recordKeysByScope.clear();
+    host.projectedRecordFences.clear();
+    host.anonymousRecordClocks.clear();
+    host.optimisticReceipts.clear();
+    host.diagnosticLayers?.clear();
+    host.setDiagnosticLayerSequence(0);
+    host.clearIndexMaintenance();
+    host.indexPlanRegistrations.clear();
+    host.renderedOperations.clear();
+    host.readOperationKeys.clear();
+    host.watchRenderCounts.clear();
+    host.setTrustedPresets(EMPTY_TRUSTED_PRESETS);
+    host.setProjectionGeneration(0);
+    host.setNextIndexRevision('0');
+    host.setProtocolGeneration(undefined);
+    host.engine.restore(EMPTY_CACHE_SNAPSHOT);
+    host.syncDiagnostics();
+    for (const watches of host.watches.values()) {
+        for (const watch of watches) {
+            host.rememberRenderedOperation(watch.key, watch.artifact, watch.variables, 'watch');
+        }
+    }
+    for (const key of host.watches.keys())
+        host.emitState(key, true);
+    if (host.diagnostics.enabled) {
+        host.diagnosticEvent(Object.freeze({
+            kind: 'scope',
+            action: 'invalidated',
+            generation: host.getProtocolGenerationSequence()
+        }));
+    }
+}
+export function closeAuthorizationGeneration(host) {
+    host.bumpProtocolGenerationSequence();
+    host.abortAuthorization();
+    host.closeActiveTransports();
+}