@hops-ops/distributed 0.0.0

package/dist/replica/diagnostics/types.d.ts

@@ -0,0 +1,295 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { ReplicaCommandArtifact } from '../commands.js';
+import type { ReplicaIndexCoverage, ReplicaOperationArtifact, ReplicaValue, ReplicaWriteSource } from '../types.js';
+export declare const DIAGNOSTICS_BUNDLE_MARKER: "distributed-replica-diagnostics-v1";
+declare const developmentCapabilityBrand: unique symbol;
+export type ReplicaDevelopmentCapability = Readonly<{
+    readonly version: 1;
+    readonly [developmentCapabilityBrand]: true;
+}>;
+export type ReplicaDiagnosticFieldValueContext = Readonly<{
+    recordKey: string;
+    model?: string;
+    field: string;
+    kind: 'field' | 'link';
+}>;
+export type ReplicaDiagnosticFieldValuePolicy = Readonly<{
+    capability: ReplicaDevelopmentCapability;
+    /** A field must be explicitly authorized before its value reaches the redactor. */
+    allow(context: ReplicaDiagnosticFieldValueContext): boolean;
+    /**
+     * Return a support-safe replacement. Returning undefined omits the value.
+     * Raw values are never retained before this function returns.
+     */
+    redact(value: ReplicaValue, context: ReplicaDiagnosticFieldValueContext): ReplicaValue | undefined;
+}>;
+export type ReplicaDiagnosticReasonContext = Readonly<{
+    kind: 'index-stale';
+    indexKey: string;
+}> | Readonly<{
+    kind: 'layer';
+    layerId: string;
+    action: 'created' | 'rebased' | 'accepted' | 'retired' | 'rejected';
+}>;
+export type ReplicaDiagnosticReasonPolicy = Readonly<{
+    capability: ReplicaDevelopmentCapability;
+    /**
+     * Return a bounded support-safe replacement. Returning undefined keeps the
+     * structural default (`application-stale`, for example).
+     */
+    redact(reason: string, context: ReplicaDiagnosticReasonContext): string | undefined;
+}>;
+export type ReplicaDiagnosticsOptions = Readonly<{
+    maxEvents?: number;
+    development?: ReplicaDevelopmentCapability;
+    fieldValues?: ReplicaDiagnosticFieldValuePolicy;
+    reasons?: ReplicaDiagnosticReasonPolicy;
+    now?: () => number;
+    onObserverError?: (error: AggregateError) => void;
+}>;
+export type ReplicaDiagnosticScopeInput = Readonly<{
+    generation: number;
+    established: boolean;
+    protocolVersion?: 1;
+    schemaHash?: string;
+}>;
+export type ReplicaDiagnosticRecordInput = Readonly<{
+    key: string;
+    model?: string;
+    revision: string;
+    incarnation: string;
+    tombstone: boolean;
+    tombstoneRevision?: string;
+    presentFields: readonly string[];
+    presentLinks: readonly string[];
+    /**
+     * Values in this object must already be support-safe redactor output. Replica
+     * core obtains them only through `redactRecordValue`.
+     */
+    values?: Readonly<Record<string, ReplicaValue>>;
+}>;
+export type ReplicaDiagnosticIndexInput = Readonly<{
+    key: string;
+    revision: string;
+    staleRevision?: string;
+    records: readonly string[];
+    complete: boolean;
+    deleted: boolean;
+    field?: string;
+    parent?: string;
+    argumentNames?: readonly string[];
+    arguments?: Readonly<Record<string, ReplicaValue>>;
+    coverage?: ReplicaIndexCoverage;
+    dependencies?: readonly string[];
+    staleReason?: string;
+    nullValue?: boolean;
+}>;
+export type ReplicaDiagnosticLayerInput = Readonly<{
+    id: string;
+    sequence: number;
+    state: 'optimistic' | 'accepted';
+    recordChanges: number;
+    indexChanges: number;
+    semanticChanges: number;
+}>;
+export type ReplicaDiagnosticReceiptExpectationInput = Readonly<{
+    projection: string;
+    model: string;
+    observed: boolean;
+}>;
+export type ReplicaDiagnosticReceiptInput = Readonly<{
+    commandId: string;
+    state: 'optimistic' | 'accepted' | 'accepted_pending_projection';
+    consistency?: 'accepted' | 'fact' | 'projected';
+    expectations: readonly ReplicaDiagnosticReceiptExpectationInput[];
+}>;
+/** Engine-independent state contract implemented by DistributedReplica. */
+export type ReplicaDiagnosticStateInput = Readonly<{
+    scope: ReplicaDiagnosticScopeInput;
+    records: readonly ReplicaDiagnosticRecordInput[];
+    indexes: readonly ReplicaDiagnosticIndexInput[];
+    layers: readonly ReplicaDiagnosticLayerInput[];
+    receipts: readonly ReplicaDiagnosticReceiptInput[];
+}>;
+export type ReplicaDiagnosticEventInput = Readonly<{
+    kind: 'normalization';
+    operation: string;
+    source: ReplicaWriteSource;
+    records: number;
+    indexes: number;
+    partial: boolean;
+}> | Readonly<{
+    kind: 'index-decision';
+    index: string;
+    decision: 'maintained' | 'stale' | 'revalidate';
+    reason?: string;
+}> | Readonly<{
+    kind: 'revalidation';
+    operation: string;
+    action: 'requested' | 'deduplicated' | 'skipped-complete';
+    reason: 'watch' | 'refresh' | 'stale';
+}> | Readonly<{
+    kind: 'layer';
+    layer: string;
+    action: 'created' | 'rebased' | 'accepted' | 'retired' | 'rejected';
+    recordChanges?: number;
+    indexChanges?: number;
+    reason?: string;
+}> | Readonly<{
+    kind: 'receipt';
+    command: string;
+    state: 'optimistic' | 'accepted' | 'accepted_pending_projection' | 'projected' | 'rejected';
+    obligations: number;
+    observed: number;
+}> | Readonly<{
+    kind: 'response-fenced';
+    operation: string;
+    transport: 'http' | 'live';
+    reason: 'authorization-generation' | 'operation-generation' | 'superseded';
+}> | Readonly<{
+    kind: 'gc';
+    records: number;
+}> | Readonly<{
+    kind: 'hydration';
+    action: 'accepted' | 'rejected';
+    reason: 'accepted' | 'invalid' | 'scope-mismatch' | 'artifact-mismatch' | 'active-scope-mismatch' | 'metadata-mismatch';
+}> | Readonly<{
+    kind: 'scope';
+    action: 'established' | 'changed' | 'invalidated';
+    generation: number;
+    schemaHash?: string;
+}>;
+export type ReplicaDiagnosticEvent = ReplicaDiagnosticEventInput & Readonly<{
+    sequence: number;
+    at: number;
+}>;
+export type ReplicaDiagnosticRecord = Readonly<{
+    key: string;
+    model?: string;
+    revision: string;
+    incarnation: string;
+    tombstone: boolean;
+    tombstoneRevision?: string;
+    presentFields: readonly string[];
+    presentLinks: readonly string[];
+    values?: Readonly<Record<string, ReplicaValue>>;
+}>;
+export type ReplicaDiagnosticIndex = Readonly<{
+    key: string;
+    revision: string;
+    staleRevision?: string;
+    records: readonly string[];
+    complete: boolean;
+    deleted: boolean;
+    field?: string;
+    parent?: string;
+    argumentNames: readonly string[];
+    arguments?: Readonly<Record<string, ReplicaValue>>;
+    coverage?: ReplicaIndexCoverage;
+    dependencies: readonly string[];
+    staleReason?: string;
+    nullValue: boolean;
+}>;
+export type ReplicaDiagnosticLayer = Readonly<{
+    id: string;
+    sequence: number;
+    state: 'optimistic' | 'accepted';
+    recordChanges: number;
+    indexChanges: number;
+    semanticChanges: number;
+}>;
+export type ReplicaDiagnosticReceipt = Readonly<{
+    commandId: string;
+    state: 'optimistic' | 'accepted' | 'accepted_pending_projection';
+    consistency?: 'accepted' | 'fact' | 'projected';
+    expectations: readonly ReplicaDiagnosticReceiptExpectationInput[];
+}>;
+export type ReplicaArtifactSourceLocation = Readonly<{
+    path: string;
+    line: number;
+    column: number;
+}>;
+export type ReplicaOperationInjectedFieldInspection = Readonly<{
+    path: string;
+    responseKey: string;
+    field: string;
+}>;
+export type ReplicaOperationIndexInspection = Readonly<{
+    path: string;
+    field: string;
+    cardinality: 'one' | 'many';
+    dependencies: readonly string[];
+    coverage?: ReplicaIndexCoverage['kind'];
+    filtered: boolean;
+    ordered: boolean;
+    pagination?: 'complete' | 'offset' | 'cursor';
+}>;
+export type ReplicaOperationArtifactInspection = Readonly<{
+    kind: 'operation';
+    id: string;
+    source?: ReplicaArtifactSourceLocation;
+    rootFields: readonly string[];
+    injectedFields: readonly ReplicaOperationInjectedFieldInspection[];
+    dependencies: readonly string[];
+    indexes: readonly ReplicaOperationIndexInspection[];
+    live?: Readonly<{
+        operation: string;
+    }>;
+}>;
+export type ReplicaCommandEffectInspection = Readonly<{
+    kind: 'upsert' | 'patch' | 'delete' | 'link' | 'unlink' | 'invalidate_model' | 'invalidate_relationship';
+    models: readonly string[];
+    fields: readonly string[];
+    valueSources: readonly ('input' | 'trusted_preset' | 'constant' | 'null')[];
+}>;
+export type ReplicaCommandArtifactInspection = Readonly<{
+    kind: 'command';
+    name: string;
+    operation: string;
+    consistency: 'accepted' | 'fact' | 'projected';
+    effects: readonly ReplicaCommandEffectInspection[];
+    revalidation: Readonly<{
+        required: boolean;
+        dependencies: readonly string[];
+        models: readonly string[];
+    }>;
+}>;
+export type ReplicaDiagnosticsSnapshot = Readonly<{
+    version: 1;
+    marker: typeof DIAGNOSTICS_BUNDLE_MARKER;
+    mode: 'redacted' | 'development';
+    sequence: number;
+    scope: ReplicaDiagnosticScopeInput;
+    records: readonly ReplicaDiagnosticRecord[];
+    indexes: readonly ReplicaDiagnosticIndex[];
+    layers: readonly ReplicaDiagnosticLayer[];
+    receipts: readonly ReplicaDiagnosticReceipt[];
+    artifacts: Readonly<{
+        operations: readonly ReplicaOperationArtifactInspection[];
+        commands: readonly ReplicaCommandArtifactInspection[];
+    }>;
+    events: readonly ReplicaDiagnosticEvent[];
+}>;
+/**
+ * Small core-facing contract. Implementations must not throw into replica
+ * transactions; DistributedReplica also catches sink failures defensively.
+ */
+export interface ReplicaDiagnosticsSink {
+    readonly includeStructuralIdentities: boolean;
+    redactRecordValue?(context: ReplicaDiagnosticFieldValueContext, value: ReplicaValue): ReplicaValue | undefined;
+    update(state: ReplicaDiagnosticStateInput): void;
+    event(event: ReplicaDiagnosticEventInput): void;
+    operation<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>): void;
+    command<TInput, TOutput>(artifact: ReplicaCommandArtifact<TInput, TOutput>): void;
+}
+export interface ReplicaDiagnostics extends ReplicaDiagnosticsSink {
+    snapshot(): ReplicaDiagnosticsSnapshot;
+    /** React/useSyncExternalStore-compatible alias with stable referential output. */
+    getSnapshot(): ReplicaDiagnosticsSnapshot;
+    subscribe(listener: (snapshot: ReplicaDiagnosticsSnapshot) => void): () => void;
+    inspectOperation<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>): ReplicaOperationArtifactInspection;
+    inspectCommand<TInput, TOutput>(artifact: ReplicaCommandArtifact<TInput, TOutput>): ReplicaCommandArtifactInspection;
+    clear(): void;
+}
+export {};
+/** Create an unforgeable, process-local opt-in to development identities. */

package/dist/replica/diagnostics/types.js

@@ -0,0 +1,2 @@
+export const DIAGNOSTICS_BUNDLE_MARKER = 'distributed-replica-diagnostics-v1';
+/** Create an unforgeable, process-local opt-in to development identities. */

package/dist/replica/diagnostics.d.ts

@@ -0,0 +1,3 @@
+/** Replica diagnostics sink and artifact inspection; implementation in ./diagnostics/. */
+export { createReplicaDevelopmentCapability, createReplicaDiagnostics, inspectReplicaCommandArtifact, inspectReplicaOperationArtifact } from './diagnostics/index.js';
+export type { ReplicaArtifactSourceLocation, ReplicaCommandArtifactInspection, ReplicaCommandEffectInspection, ReplicaDevelopmentCapability, ReplicaDiagnosticEvent, ReplicaDiagnosticEventInput, ReplicaDiagnosticFieldValueContext, ReplicaDiagnosticFieldValuePolicy, ReplicaDiagnosticIndex, ReplicaDiagnosticIndexInput, ReplicaDiagnosticLayer, ReplicaDiagnosticLayerInput, ReplicaDiagnosticReceipt, ReplicaDiagnosticReceiptExpectationInput, ReplicaDiagnosticReceiptInput, ReplicaDiagnosticRecord, ReplicaDiagnosticRecordInput, ReplicaDiagnosticReasonContext, ReplicaDiagnosticReasonPolicy, ReplicaDiagnostics, ReplicaDiagnosticsOptions, ReplicaDiagnosticsSink, ReplicaDiagnosticsSnapshot, ReplicaDiagnosticScopeInput, ReplicaDiagnosticStateInput, ReplicaOperationArtifactInspection, ReplicaOperationIndexInspection, ReplicaOperationInjectedFieldInspection } from './diagnostics/index.js';

package/dist/replica/diagnostics.js

@@ -0,0 +1,2 @@
+/** Replica diagnostics sink and artifact inspection; implementation in ./diagnostics/. */
+export { createReplicaDevelopmentCapability, createReplicaDiagnostics, inspectReplicaCommandArtifact, inspectReplicaOperationArtifact } from './diagnostics/index.js';

package/dist/replica/distributed-replica/clocks.d.ts

@@ -0,0 +1,23 @@
+import type { CacheValue } from '../../internal/cache-engine.js';
+import { type DistributedIndexRevision, type DistributedLiveCursor, type DistributedProtocolEnvelope, type DistributedQuerySnapshot, type DistributedRecordRevision } from '../../protocol.js';
+import type { ReplicaValue } from '../types.js';
+import type { IndexDisposition, IndexProtocolClock, OperationProtocolState, ProjectedRecordFence, RecordProtocolClock } from './types.js';
+import { deepEqual } from '../../lib/deep-equal.js';
+export declare function sameRecordRevision(left: DistributedRecordRevision, right: DistributedRecordRevision): boolean;
+export declare function recordKeyMatchesModel(recordKey: string, model: string): boolean;
+export declare function modelFromRecordKey(recordKey: string): string | undefined;
+export declare function compareIndexVector(current: ReadonlyMap<string, IndexProtocolClock>, incoming: readonly DistributedIndexRevision[]): IndexDisposition;
+export declare function compareSnapshotToOperationState(state: OperationProtocolState, snapshot: DistributedQuerySnapshot): IndexDisposition;
+export declare function isComparableHandoffDisposition(disposition: IndexDisposition): boolean;
+export declare function indexClockMap(indexes: readonly DistributedIndexRevision[]): Map<string, IndexProtocolClock>;
+export declare function latestCursors(snapshot: DistributedQuerySnapshot, live: DistributedProtocolEnvelope['live']): readonly DistributedLiveCursor[];
+export declare function responsePathKey(path: readonly string[]): string;
+export declare function compareRecordClock(left: RecordProtocolClock, right: RecordProtocolClock): -1 | 0 | 1;
+export declare function compareEvidenceToProjectedFence(evidence: DistributedRecordRevision, fence: ProjectedRecordFence): -1 | 0 | 1 | undefined;
+export declare function sameRecordClock(left: RecordProtocolClock, right: RecordProtocolClock): boolean;
+export declare function incrementCanonicalDecimal(value: string): string;
+export declare function compareCanonicalDecimalStrings(left: string, right: string): number;
+export declare function protocolInvalid(path: string): never;
+export declare function freezeRecordClock(clock: RecordProtocolClock): RecordProtocolClock;
+export declare function compareProjectedRecordFields(projected: Readonly<Record<string, ReplicaValue>>, incoming: Readonly<Record<string, CacheValue>>): 'conflict' | 'partial' | 'complete';
+export { deepEqual };

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

@@ -0,0 +1,156 @@
+import { compareDistributedDecimal, DistributedProtocolError } from '../../protocol.js';
+import { deepEqual } from '../../lib/deep-equal.js';
+export function sameRecordRevision(left, right) {
+    return (left.model === right.model &&
+        left.scopeToken === right.scopeToken &&
+        left.incarnation === right.incarnation &&
+        left.revision === right.revision &&
+        left.tombstone === right.tombstone);
+}
+export function recordKeyMatchesModel(recordKey, model) {
+    return recordKey.startsWith(`record:${encodeURIComponent(model)}:`);
+}
+export function modelFromRecordKey(recordKey) {
+    if (!recordKey.startsWith('record:'))
+        return undefined;
+    const separator = recordKey.indexOf(':', 'record:'.length);
+    if (separator === -1)
+        return undefined;
+    try {
+        const model = decodeURIComponent(recordKey.slice('record:'.length, separator));
+        return model.length === 0 ? undefined : model;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function compareIndexVector(current, incoming) {
+    if (current.size === 0)
+        return 'fresh';
+    if (current.size !== incoming.length)
+        return 'incomparable';
+    let lower = false;
+    let higher = false;
+    for (const evidence of incoming) {
+        const previous = current.get(evidence.projection);
+        if (previous === undefined ||
+            previous.scopeToken !== evidence.scopeToken) {
+            return 'incomparable';
+        }
+        const comparison = compareDistributedDecimal(evidence.position, previous.position);
+        lower ||= comparison < 0;
+        higher ||= comparison > 0;
+    }
+    if (lower && higher)
+        return 'incomparable';
+    if (lower)
+        return 'lower';
+    if (higher)
+        return 'higher';
+    return 'equal';
+}
+export function compareSnapshotToOperationState(state, snapshot) {
+    if (state.snapshotScope === undefined)
+        return 'fresh';
+    if (state.snapshotScope !== snapshot.scopeToken)
+        return 'incomparable';
+    if (state.indexClocks.size === 0 || snapshot.indexes.length === 0) {
+        return state.indexClocks.size === snapshot.indexes.length
+            ? 'equal'
+            : 'incomparable';
+    }
+    return compareIndexVector(state.indexClocks, snapshot.indexes);
+}
+export function isComparableHandoffDisposition(disposition) {
+    return (disposition === 'fresh' ||
+        disposition === 'equal' ||
+        disposition === 'higher');
+}
+export function indexClockMap(indexes) {
+    return new Map(indexes.map((index) => [
+        index.projection,
+        {
+            scopeToken: index.scopeToken,
+            position: index.position
+        }
+    ]));
+}
+export function latestCursors(snapshot, live) {
+    if (live !== undefined) {
+        return live.supported ? live.cursors : Object.freeze([]);
+    }
+    return Object.freeze(snapshot.indexes.flatMap((index) => index.resume === undefined ? [] : [index.resume]));
+}
+export function responsePathKey(path) {
+    return JSON.stringify(path);
+}
+export function compareRecordClock(left, right) {
+    const incarnation = compareDistributedDecimal(left.incarnation, right.incarnation);
+    return incarnation === 0
+        ? compareDistributedDecimal(left.revision, right.revision)
+        : incarnation;
+}
+export function compareEvidenceToProjectedFence(evidence, fence) {
+    if (evidence.scopeToken !== fence.clock.scopeToken)
+        return undefined;
+    return compareRecordClock({
+        scopeToken: evidence.scopeToken,
+        incarnation: evidence.incarnation,
+        revision: evidence.revision,
+        tombstone: evidence.tombstone
+    }, fence.clock);
+}
+export function sameRecordClock(left, right) {
+    return (left.scopeToken === right.scopeToken &&
+        left.incarnation === right.incarnation &&
+        left.revision === right.revision &&
+        left.tombstone === right.tombstone);
+}
+export function incrementCanonicalDecimal(value) {
+    const digits = [...value];
+    let carry = true;
+    for (let index = digits.length - 1; index >= 0 && carry; index -= 1) {
+        const digit = digits[index];
+        if (digit === '9') {
+            digits[index] = '0';
+        }
+        else {
+            digits[index] = '0123456789'['0123456789'.indexOf(digit) + 1];
+            carry = false;
+        }
+    }
+    if (carry)
+        digits.unshift('1');
+    return digits.join('');
+}
+export function compareCanonicalDecimalStrings(left, right) {
+    return left.length === right.length
+        ? left.localeCompare(right)
+        : left.length < right.length
+            ? -1
+            : 1;
+}
+export function protocolInvalid(path) {
+    throw new DistributedProtocolError('DISTRIBUTED_PROTOCOL_INVALID', path);
+}
+export function freezeRecordClock(clock) {
+    return Object.freeze({
+        scopeToken: clock.scopeToken,
+        incarnation: clock.incarnation,
+        revision: clock.revision,
+        tombstone: clock.tombstone
+    });
+}
+export function compareProjectedRecordFields(projected, incoming) {
+    let complete = true;
+    for (const [field, value] of Object.entries(projected)) {
+        if (!Object.prototype.hasOwnProperty.call(incoming, field)) {
+            complete = false;
+            continue;
+        }
+        if (!deepEqual(value, incoming[field]))
+            return 'conflict';
+    }
+    return complete ? 'complete' : 'partial';
+}
+export { deepEqual };

package/dist/replica/distributed-replica/constants.d.ts

@@ -0,0 +1,12 @@
+import type { GqlError } from '../../types.js';
+import type { DistributedTrustedPreset } from '../../protocol.js';
+export declare const EMPTY_ERRORS: readonly GqlError[];
+/** Matches protocol.ts MAX_EVIDENCE_ITEMS without making it public API. */
+export declare const MAX_ANONYMOUS_RECORD_CLOCKS = 4096;
+export declare const SHA256: RegExp;
+export declare const EMPTY_TRUSTED_PRESETS: readonly DistributedTrustedPreset[];
+export declare const EMPTY_CACHE_SNAPSHOT: Readonly<{
+    version: 1;
+    records: readonly never[];
+    indexes: readonly never[];
+}>;

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

@@ -0,0 +1,10 @@
+export const EMPTY_ERRORS = Object.freeze([]);
+/** Matches protocol.ts MAX_EVIDENCE_ITEMS without making it public API. */
+export const MAX_ANONYMOUS_RECORD_CLOCKS = 4_096;
+export const SHA256 = /^sha256:[0-9a-f]{64}$/;
+export const EMPTY_TRUSTED_PRESETS = Object.freeze([]);
+export const EMPTY_CACHE_SNAPSHOT = Object.freeze({
+    version: 1,
+    records: Object.freeze([]),
+    indexes: Object.freeze([])
+});

package/dist/replica/distributed-replica/helpers.d.ts

@@ -0,0 +1,48 @@
+import { type BaseCacheWriter, type CacheEngineSnapshot, type CacheIndexMetadata, type OptimisticLayerView } from '../../internal/cache-engine.js';
+import type { GqlError, GraphqlVariables } from '../../types.js';
+import { type DistributedQuerySnapshot, type DistributedRecordRevision, type DistributedTrustedPreset } from '../../protocol.js';
+import type { ReplicaTrustedPresetDescriptor } from '../commands.js';
+import type { ReplicaCommandSurfaceContract } from '../command-runtime.js';
+import { type ReplicaIndexMaintenanceSnapshot, type ReplicaIndexSemanticLayer } from '../index-maintenance.js';
+import type { MaterializedReplicaResult } from '../materialize.js';
+import { type RuntimeObjectBranch, type RuntimeObjectSelection, type RuntimeRootSelection } from '../selection.js';
+import type { ReplicaBaseWriter, ReplicaIndexTarget, ReplicaOperationArtifact, ReplicaResultEnvelope, ReplicaSnapshot, ReplicaWriteSource } from '../types.js';
+import type { OperationProtocolSource, QueryState, RegisteredCommandAuthorityContract } from './types.js';
+import { reportSafely, reportUnhandledError } from '../../lib/report.js';
+export { deepEqual } from './clocks.js';
+export declare function prepareRecordEvidence(snapshot: DistributedQuerySnapshot, commandRecords: readonly DistributedRecordRevision[]): {
+    byPath: Map<string, DistributedRecordRevision>;
+    tombstones: readonly DistributedRecordRevision[];
+    pathless: readonly DistributedRecordRevision[];
+    livePaths: ReadonlySet<string>;
+};
+export declare function replicaResultIndexKeys<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>, variables: TVariables, envelope: ReplicaResultEnvelope<TData>, snapshot: DistributedQuerySnapshot): ReadonlySet<string>;
+export declare function collectResultBranchIndexKeys(artifactId: string, selection: RuntimeRootSelection | RuntimeObjectBranch, value: unknown, path: readonly (string | number)[], enclosingIndexKey: string, variables: GraphqlVariables, errorPaths: readonly (readonly (string | number)[])[], evidencePaths: ReadonlySet<string>, keys: Set<string>): void;
+export declare function collectResultObjectIndexKeys(artifactId: string, selection: RuntimeObjectSelection, value: unknown, path: readonly (string | number)[], enclosingIndexKey: string, ordinal: number | undefined, variables: GraphqlVariables, errorPaths: readonly (readonly (string | number)[])[], evidencePaths: ReadonlySet<string>, keys: Set<string>): void;
+export declare function resultPathBlocked(errorPaths: readonly (readonly (string | number)[])[], path: readonly (string | number)[]): boolean;
+export declare function resultPathHasErrors(errorPaths: readonly (readonly (string | number)[])[], path: readonly (string | number)[]): boolean;
+export declare function resultPathPrefix(prefix: readonly (string | number)[], value: readonly (string | number)[]): boolean;
+export declare function isReplicaResultObject(value: unknown): value is Readonly<Record<string, unknown>>;
+export declare function indexMaintenanceSnapshot(confirmed: CacheEngineSnapshot): ReplicaIndexMaintenanceSnapshot;
+export declare function indexSemanticLayer(layer: OptimisticLayerView): ReplicaIndexSemanticLayer;
+export declare function baseWriter(writer: BaseCacheWriter): ReplicaBaseWriter;
+export declare function metadataFromTarget(target: ReplicaIndexTarget): CacheIndexMetadata;
+export declare function indexKeyFromTarget(target: ReplicaIndexTarget): string;
+export declare function replicaClientRequestExtensions<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>): {
+    readonly extensions?: Readonly<Record<string, unknown>>;
+};
+export declare function validatedCommandAuthorityContract(value: ReplicaCommandSurfaceContract): RegisteredCommandAuthorityContract;
+export declare function canonicalTrustedPresets(value: readonly DistributedTrustedPreset[]): readonly DistributedTrustedPreset[];
+export declare function trustedPresetInventoryFingerprint(value: readonly DistributedTrustedPreset[]): string;
+export declare function trustedPresetDescriptorFingerprint(value: readonly ReplicaTrustedPresetDescriptor[]): string;
+export declare function operationKey<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>, variables: TVariables): string;
+export declare function validatedSurfaceIdentity(value: NonNullable<ReplicaOperationArtifact['protocol']>['surface']): string;
+export declare function snapshotFrom<TData>(materialized: MaterializedReplicaResult<TData>, state: QueryState): ReplicaSnapshot<TData>;
+export declare function snapshotEqual<TData>(left: ReplicaSnapshot<TData>, right: ReplicaSnapshot<TData>): boolean;
+export declare function freezeErrors(errors: readonly GqlError[]): readonly GqlError[];
+export declare function stableErrors(current: readonly GqlError[], next: readonly GqlError[]): readonly GqlError[];
+export declare function graphqlError(error: unknown): GqlError;
+export declare function assertWriteSource(source: ReplicaWriteSource): void;
+export declare function protocolOperationSource(source: ReplicaWriteSource): OperationProtocolSource;
+export { reportSafely };
+export declare const reportUnhandledObserverError: typeof reportUnhandledError;