@hops-ops/distributed 0.0.0

package/dist/replica/index-maintenance/index.js

@@ -0,0 +1 @@
+export { createReplicaIndexMaintenanceRegistry, formatReplicaIndexStaleReason } from './implementation.js';

package/dist/replica/index-maintenance/registry.d.ts

@@ -0,0 +1,2 @@
+import type { ReplicaIndexMaintenanceRegistry } from './types.js';
+export declare function createReplicaIndexMaintenanceRegistry(): ReplicaIndexMaintenanceRegistry;

package/dist/replica/index-maintenance/registry.js

@@ -0,0 +1,49 @@
+import { canonicalizeOperationVariables } from '../identity.js';
+import { compareCodeUnits } from '../../lib/compare-code-units.js';
+import { applyLayers, canonicalValue, compilePlans, evaluatePlan, instantiatePlans, planAffected, reason, stale, validateIndexes } from './engine.js';
+class PurposeBuiltIndexMaintenanceRegistry {
+    #plans = new Map();
+    #nextRegistration = 0;
+    registerOperation(artifact, variables) {
+        const canonicalVariables = canonicalizeOperationVariables(artifact, variables);
+        const id = `${artifact.id}:${canonicalValue(canonicalVariables)}:${++this.#nextRegistration}`;
+        this.#plans.set(id, compilePlans(id, artifact, canonicalVariables));
+        let active = true;
+        return Object.freeze({
+            id,
+            dispose: () => {
+                if (!active)
+                    return;
+                active = false;
+                this.#plans.delete(id);
+            }
+        });
+    }
+    evaluate(snapshot, layers, trustedPresets = Object.freeze([])) {
+        const applied = applyLayers(snapshot.records, layers);
+        const indexes = validateIndexes(snapshot.indexes);
+        const plansByIndex = instantiatePlans([...this.#plans.values()].flat(), indexes);
+        const decisions = [];
+        for (const [indexKey, plans] of [...plansByIndex].sort(([left], [right]) => compareCodeUnits(left, right))) {
+            const index = indexes.get(indexKey);
+            if (index === undefined)
+                continue;
+            const affected = plans.filter((plan) => planAffected(plan, index, applied));
+            if (affected.length === 0)
+                continue;
+            const signatures = new Set(affected.map(({ signature }) => signature));
+            if (signatures.size !== 1) {
+                decisions.push(stale(indexKey, reason('conflicting_index_plan', ['indexes', indexKey], 'multiple active artifacts disagree about one semantic index plan')));
+                continue;
+            }
+            decisions.push(evaluatePlan(affected[0], index, applied, trustedPresets));
+        }
+        return Object.freeze(decisions);
+    }
+    clear() {
+        this.#plans.clear();
+    }
+}
+export function createReplicaIndexMaintenanceRegistry() {
+    return new PurposeBuiltIndexMaintenanceRegistry();
+}

package/dist/replica/index-maintenance/types.d.ts

@@ -0,0 +1,58 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { DistributedTrustedPreset } from '../../protocol.js';
+import type { ReplicaIndexCoverage, ReplicaIndexSemanticChange, ReplicaOperationArtifact, ReplicaValue } from '../types.js';
+export type { ReplicaIndexDependencyChange, ReplicaIndexRecordChange, ReplicaIndexRelationshipChange, ReplicaIndexSemanticChange } from '../types.js';
+export type ReplicaIndexMaintenanceRecord = {
+    readonly key: string;
+    readonly model: string;
+    readonly fields: Readonly<Record<string, ReplicaValue>>;
+};
+export type ReplicaIndexMaintenanceIndex = {
+    readonly key: string;
+    readonly records: readonly string[];
+    readonly complete: boolean;
+    readonly metadata: {
+        readonly parent?: string;
+        readonly field: string;
+        readonly arguments: Readonly<Record<string, ReplicaValue>>;
+        readonly coverage: ReplicaIndexCoverage;
+        readonly dependencies: readonly string[];
+        readonly staleReason?: string;
+    };
+};
+export type ReplicaIndexSemanticLayer = {
+    readonly id: string;
+    readonly changes: readonly ReplicaIndexSemanticChange[];
+};
+export type ReplicaIndexMaintenanceSnapshot = {
+    readonly records: readonly ReplicaIndexMaintenanceRecord[];
+    readonly indexes: readonly ReplicaIndexMaintenanceIndex[];
+};
+export type ReplicaIndexMaintenanceReasonCode = 'aggregate_dependency_changed' | 'conflicting_index_plan' | 'dependency_changed' | 'duplicate_index_record' | 'index_incomplete' | 'invalid_index_metadata' | 'missing_index_record' | 'missing_order_plan' | 'missing_parent_record' | 'non_unique_order' | 'relationship_dependency_missing' | 'relationship_maintenance_revalidate' | 'relationship_mapping_unknown' | 'unsupported_cardinality' | import('../query-plan.js').ReplicaQueryPlanReasonCode;
+export type ReplicaIndexMaintenanceReason = {
+    readonly code: ReplicaIndexMaintenanceReasonCode;
+    readonly path: readonly (string | number)[];
+    readonly message: string;
+};
+export type ReplicaIndexMaintenanceDecision = {
+    readonly kind: 'write';
+    readonly indexKey: string;
+    readonly records: readonly string[];
+    readonly complete: true;
+} | {
+    readonly kind: 'stale';
+    readonly indexKey: string;
+    readonly reason: ReplicaIndexMaintenanceReason;
+} | {
+    readonly kind: 'unchanged';
+    readonly indexKey: string;
+};
+export type ReplicaIndexPlanRegistration = {
+    readonly id: string;
+    dispose(): void;
+};
+export interface ReplicaIndexMaintenanceRegistry {
+    registerOperation<TData, TVariables extends GraphqlVariables>(artifact: ReplicaOperationArtifact<TData, TVariables>, variables: TVariables): ReplicaIndexPlanRegistration;
+    evaluate(snapshot: ReplicaIndexMaintenanceSnapshot, layers: readonly ReplicaIndexSemanticLayer[], trustedPresets?: readonly DistributedTrustedPreset[]): readonly ReplicaIndexMaintenanceDecision[];
+    clear(): void;
+}

package/dist/replica/index-maintenance/types.js

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

package/dist/replica/index-maintenance.d.ts

@@ -0,0 +1,3 @@
+/** Index maintenance registry and plan evaluation; implementation in ./index-maintenance/. */
+export { createReplicaIndexMaintenanceRegistry, formatReplicaIndexStaleReason } from './index-maintenance/index.js';
+export type { ReplicaIndexDependencyChange, ReplicaIndexMaintenanceDecision, ReplicaIndexMaintenanceIndex, ReplicaIndexMaintenanceReason, ReplicaIndexMaintenanceReasonCode, ReplicaIndexMaintenanceRecord, ReplicaIndexMaintenanceRegistry, ReplicaIndexMaintenanceSnapshot, ReplicaIndexPlanRegistration, ReplicaIndexRecordChange, ReplicaIndexRelationshipChange, ReplicaIndexSemanticChange, ReplicaIndexSemanticLayer } from './index-maintenance/index.js';

package/dist/replica/index-maintenance.js

@@ -0,0 +1,2 @@
+/** Index maintenance registry and plan evaluation; implementation in ./index-maintenance/. */
+export { createReplicaIndexMaintenanceRegistry, formatReplicaIndexStaleReason } from './index-maintenance/index.js';

package/dist/replica/index.d.ts

@@ -0,0 +1,17 @@
+export { createDistributedReplica } from './distributed-replica.js';
+export { createReplicaDevelopmentCapability, createReplicaDiagnostics, inspectReplicaCommandArtifact, inspectReplicaOperationArtifact } from './diagnostics.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.js';
+export { createReplicaGraphqlTransport } from './graphql-transport.js';
+export type { ReplicaGraphqlTransport, ReplicaGraphqlTransportOptions } from './graphql-transport.js';
+export { canonicalizeOperationVariables, replicaIndexKey, replicaRecordKey } from './identity.js';
+export { prepareReplicaCommand, ReplicaCommandContractError, verifyReplicaCommandReceipt } from './commands.js';
+export { createReplicaCommandRuntime, ReplicaCommandRuntimeError } from './command-runtime.js';
+export { createReplicaIndexedDbPersistence, REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED } from './persistence.js';
+export type { ReplicaBoundCommand, ReplicaBoundCommands, ReplicaCommandCallOptions, ReplicaCommandProjectedOutcome, ReplicaCommandReceipt, ReplicaCommandRecoveryReceipt, ReplicaCommandRuntime, ReplicaCommandRuntimeErrorCode, ReplicaCommandRuntimeOptions, ReplicaCommandStatus, ReplicaCommandStatusArtifact, ReplicaCommandStatusRequest, ReplicaCommandTransport, ReplicaCommandTransportRequest, ReplicaCommandTransportResult } from './command-runtime.js';
+export type { ReplicaIndexedDbFactory, ReplicaIndexedDbPersistence, ReplicaIndexedDbPersistenceOptions, ReplicaPersistenceModelPolicy, ReplicaPersistencePolicy } from './persistence.js';
+export type { PrepareReplicaCommandOptions, ReplicaCommandArtifact, ReplicaCommandConfirmation, ReplicaCommandConfirmations, ReplicaCommandContractErrorCode, ReplicaCommandDirectProjection, ReplicaCommandEffect, ReplicaCommandEffectExpression, ReplicaCommandEffectField, ReplicaCommandEffectKey, ReplicaCommandEffectRelationship, ReplicaCommandEffects, ReplicaCommandGenerators, ReplicaCommandInputDefault, ReplicaCommandInputDefaults, ReplicaCommandRevalidationPlan, ReplicaCommandScalarCodec, ReplicaCommandShape, ReplicaCommandTypeDefinition, ReplicaCommandTypeField, ReplicaCommandVariables, ReplicaTrustedPresetDescriptor, ReplicaPreparedCommand, ReplicaPreparedCommandEffect, ReplicaPreparedConfirmation, ReplicaPreparedConfirmations, ReplicaPreparedEffectField, ReplicaPreparedEffectKey, ReplicaReceiptVerification } from './commands.js';
+export { compareReplicaOrder, decideReplicaPaginationMaintenance, evaluateReplicaFilter } from './query-plan.js';
+export { createReplicaIndexMaintenanceRegistry, formatReplicaIndexStaleReason } from './index-maintenance.js';
+export type { ReplicaIndexDependencyChange, ReplicaIndexMaintenanceDecision, ReplicaIndexMaintenanceIndex, ReplicaIndexMaintenanceReason, ReplicaIndexMaintenanceReasonCode, ReplicaIndexMaintenanceRecord, ReplicaIndexMaintenanceRegistry, ReplicaIndexMaintenanceSnapshot, ReplicaIndexPlanRegistration, ReplicaIndexRecordChange, ReplicaIndexRelationshipChange, ReplicaIndexSemanticChange, ReplicaIndexSemanticLayer } from './index-maintenance.js';
+export type { ReplicaFilterEvaluation, ReplicaFilterEvaluationOptions, ReplicaOrderComparison, ReplicaPaginationChange, ReplicaPaginationMaintenanceDecision, ReplicaQueryPlanPath, ReplicaQueryPlanReason, ReplicaQueryPlanReasonCode, ReplicaRelationshipFilterRequest } from './query-plan.js';
+export type { DistributedReplicaOptions, DistributedReplica, ReplicaArgumentsArtifact, ReplicaArgumentValue, ReplicaAuthoritativeScope, ReplicaBaseWriter, ReplicaBranchSemantic, ReplicaClientSurface, ReplicaCoverageArtifact, ReplicaDehydratedState, ReplicaFilterArtifact, ReplicaFilterExpression, ReplicaFilterFieldArtifact, ReplicaFilterLiteral, ReplicaFilterOperand, ReplicaFilterOperator, ReplicaIdentity, ReplicaIndexCoverage, ReplicaIndexInspection, ReplicaIndexTarget, ReplicaListValue, ReplicaLiveObserver, ReplicaLiveState, ReplicaLiteralValue, ReplicaModelArtifact, ReplicaObjectBranch, ReplicaObjectMember, ReplicaObjectSelection, ReplicaObjectValue, ReplicaOperationArtifact, ReplicaOperationSourceLocation, ReplicaOperationProtocol, ReplicaOrderArtifact, ReplicaOrderFieldArtifact, ReplicaOrderTieBreakerArtifact, ReplicaOptimisticWriter, ReplicaPaginationArtifact, ReplicaPaginationDisposition, ReplicaProtocolOperationArtifact, ReplicaRecordInspection, ReplicaRecordPatch, ReplicaRevalidationPlan, ReplicaRevalidationRelationship, ReplicaRevision, ReplicaRelationshipArtifact, ReplicaRelationshipKeyMapping, ReplicaRelationshipKind, ReplicaResultEnvelope, ReplicaRowPolicyArtifact, ReplicaRootSelection, ReplicaScalarSelection, ReplicaSelectionStorage, ReplicaSparse, ReplicaSnapshot, ReplicaStatus, ReplicaTransport, ReplicaTransportRequest, ReplicaVariableValue, ReplicaVariableCodecArtifact, ReplicaVariableEnumInputRef, ReplicaVariableFilterInputDefinition, ReplicaVariableFilterInputField, ReplicaVariableFilterInputRelationship, ReplicaVariableFilterInputTarget, ReplicaVariableInputDefinition, ReplicaVariableInputRef, ReplicaVariableListInputRef, ReplicaVariableNamedInputRef, ReplicaVariableOrderInputDefinition, ReplicaVariableOrderInputField, ReplicaVariableScalarInputRef, ReplicaValue, ReplicaWatch, ReplicaWriteSource, WatchReplicaOptions } from './types.js';

package/dist/replica/index.js

@@ -0,0 +1,9 @@
+export { createDistributedReplica } from './distributed-replica.js';
+export { createReplicaDevelopmentCapability, createReplicaDiagnostics, inspectReplicaCommandArtifact, inspectReplicaOperationArtifact } from './diagnostics.js';
+export { createReplicaGraphqlTransport } from './graphql-transport.js';
+export { canonicalizeOperationVariables, replicaIndexKey, replicaRecordKey } from './identity.js';
+export { prepareReplicaCommand, ReplicaCommandContractError, verifyReplicaCommandReceipt } from './commands.js';
+export { createReplicaCommandRuntime, ReplicaCommandRuntimeError } from './command-runtime.js';
+export { createReplicaIndexedDbPersistence, REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED } from './persistence.js';
+export { compareReplicaOrder, decideReplicaPaginationMaintenance, evaluateReplicaFilter } from './query-plan.js';
+export { createReplicaIndexMaintenanceRegistry, formatReplicaIndexStaleReason } from './index-maintenance.js';

package/dist/replica/materialize.d.ts

@@ -0,0 +1,10 @@
+import type { CacheReader } from '../internal/cache-engine.js';
+import type { GraphqlVariables } from '../types.js';
+import type { ReplicaOperationArtifact, ReplicaSparse } from './types.js';
+export type MaterializedReplicaResult<TData> = {
+    readonly data: ReplicaSparse<TData>;
+    readonly complete: boolean;
+    readonly stale: boolean;
+    readonly identitySignature: string;
+};
+export declare function materializeReplicaOperation<TData, TVariables extends GraphqlVariables>(reader: CacheReader, artifact: ReplicaOperationArtifact<TData, TVariables>, variables: TVariables): MaterializedReplicaResult<TData>;

package/dist/replica/materialize.js

@@ -0,0 +1,163 @@
+import { replicaIndexKey, resolveArguments } from './identity.js';
+import { runtimeRoot } from './selection.js';
+export function materializeReplicaOperation(reader, artifact, variables) {
+    const output = {};
+    let complete = true;
+    let stale = false;
+    const signatures = [];
+    for (const artifactRoot of artifact.roots) {
+        const root = runtimeRoot(artifactRoot);
+        const argumentsValue = resolveArguments(root.arguments, variables, root.coverage);
+        const indexKey = replicaIndexKey({ field: root.field, arguments: argumentsValue });
+        const index = reader.index(indexKey);
+        const branch = materializeBranch(reader, root, index, variables);
+        if (branch.present) {
+            defineOutputValue(output, root.responseKey, branch.value);
+        }
+        complete &&= branch.complete;
+        stale ||= branch.stale;
+        signatures.push(`${indexKey}:${branch.identitySignature}`);
+    }
+    return Object.freeze({
+        data: Object.freeze(output),
+        complete,
+        stale,
+        identitySignature: signatures.join('|')
+    });
+}
+function materializeBranch(reader, selection, index, variables) {
+    if (!index || !index.metadata) {
+        return {
+            present: false,
+            complete: false,
+            stale: false,
+            identitySignature: 'missing-index'
+        };
+    }
+    const stale = index.metadata.staleReason !== undefined;
+    /*
+     * Completeness and freshness are independent. A stale complete index still
+     * has a structurally materializable result and remains visible during
+     * stale-while-revalidate. Partial/lifecycle-invalidated indexes explicitly
+     * carry `complete=false` and remain sparse.
+     */
+    const indexComplete = index.complete;
+    if (index.metadata.nullValue) {
+        return {
+            value: null,
+            present: true,
+            complete: indexComplete && selection.nullable,
+            stale,
+            identitySignature: `null:${index.metadata.staleReason ?? ''}`
+        };
+    }
+    if (selection.cardinality === 'one') {
+        const key = index.records[0];
+        if (key === undefined) {
+            return {
+                present: false,
+                complete: false,
+                stale,
+                identitySignature: `missing-record:${index.metadata.staleReason ?? ''}`
+            };
+        }
+        const object = materializeObject(reader, selection.selection, key, variables);
+        return {
+            value: object.value,
+            present: object.value !== undefined,
+            complete: indexComplete && index.records.length === 1 && object.complete,
+            stale: stale || object.stale,
+            identitySignature: object.identitySignature
+        };
+    }
+    const values = [];
+    let childrenComplete = true;
+    let childrenStale = false;
+    const signatures = [];
+    for (const key of index.records) {
+        const object = materializeObject(reader, selection.selection, key, variables);
+        if (object.value !== undefined)
+            values.push(object.value);
+        else
+            childrenComplete = false;
+        childrenComplete &&= object.complete;
+        childrenStale ||= object.stale;
+        signatures.push(object.identitySignature);
+    }
+    return {
+        value: Object.freeze(values),
+        present: true,
+        complete: indexComplete && childrenComplete,
+        stale: stale || childrenStale,
+        identitySignature: signatures.join(',')
+    };
+}
+function materializeObject(reader, selection, key, variables) {
+    const record = reader.recordMeta(key);
+    if (!record) {
+        return {
+            complete: false,
+            stale: false,
+            identitySignature: `${key}:missing`
+        };
+    }
+    const output = {};
+    let complete = true;
+    let stale = false;
+    const nestedSignatures = [];
+    for (const member of selection.members) {
+        if (member.kind !== 'scalar')
+            continue;
+        const presence = reader.field(key, member.field);
+        if (!presence.present || (presence.value === null && !member.nullable)) {
+            complete = false;
+            continue;
+        }
+        if (member.expose !== false) {
+            defineOutputValue(output, member.responseKey, presence.value);
+        }
+    }
+    for (const member of selection.members) {
+        if (member.kind !== 'branch')
+            continue;
+        const branchResult = materializeNestedBranch(reader, key, record.incarnation, member, variables);
+        if (member.expose !== false && branchResult.present) {
+            defineOutputValue(output, member.responseKey, branchResult.value);
+        }
+        complete &&= branchResult.complete;
+        stale ||= branchResult.stale;
+        nestedSignatures.push(`${member.field}:${branchResult.identitySignature}`);
+    }
+    return {
+        value: Object.freeze(output),
+        complete,
+        stale,
+        identitySignature: `${key}@${record.incarnation}[${nestedSignatures.join('|')}]`
+    };
+}
+function materializeNestedBranch(reader, parentKey, parentIncarnation, selection, variables) {
+    const argumentsValue = resolveArguments(selection.arguments, variables, selection.coverage);
+    const indexKey = replicaIndexKey({
+        parent: parentKey,
+        field: selection.field,
+        arguments: argumentsValue
+    });
+    const index = reader.index(indexKey);
+    if (index?.metadata?.parentIncarnation !== parentIncarnation) {
+        return {
+            present: false,
+            complete: false,
+            stale: index !== undefined,
+            identitySignature: `parent-incarnation-mismatch:${parentIncarnation}`
+        };
+    }
+    return materializeBranch(reader, selection, index, variables);
+}
+function defineOutputValue(output, key, value) {
+    Object.defineProperty(output, key, {
+        value,
+        enumerable: true,
+        configurable: false,
+        writable: false
+    });
+}

package/dist/replica/normalize.d.ts

@@ -0,0 +1,27 @@
+import type { BaseCacheWriter, CacheValue } from '../internal/cache-engine.js';
+import type { DistributedRecordRevision } from '../protocol.js';
+import type { GraphqlVariables } from '../types.js';
+import type { ReplicaOperationArtifact, ReplicaRevision, ReplicaResultEnvelope } from './types.js';
+export type ReplicaNormalizationSummary = {
+    readonly wrote: boolean;
+    readonly partial: boolean;
+    readonly indexKeys: readonly string[];
+};
+export type ReplicaProtocolRecordResolution = {
+    readonly evidence: DistributedRecordRevision;
+    /** False means a same-scope newer base record already won. */
+    readonly apply: boolean;
+};
+export type ReplicaNormalizationProtocol = {
+    readonly indexRevision: ReplicaRevision;
+    readonly writeIndexes: boolean;
+    readonly indexesComplete: boolean;
+    /**
+     * Missing causal record evidence may use operation-local snapshot storage.
+     * Such rows remain renderable without impersonating a shared normalized
+     * identity.
+     */
+    readonly allowSnapshotOnlyRecords: boolean;
+    readonly record: (path: readonly string[], model: string, key: string, fields: Readonly<Record<string, CacheValue>>) => ReplicaProtocolRecordResolution | undefined;
+};
+export declare function normalizeReplicaResult<TData, TVariables extends GraphqlVariables>(writer: BaseCacheWriter, artifact: ReplicaOperationArtifact<TData, TVariables>, variables: TVariables, envelope: ReplicaResultEnvelope<TData>, protocol: ReplicaNormalizationProtocol): ReplicaNormalizationSummary;

package/dist/replica/normalize.js

@@ -0,0 +1,298 @@
+import { cloneJsonValue, coverageFromArtifact, replicaIndexKey, replicaRecordKey, resolveArguments } from './identity.js';
+import { embeddedRecordKey, runtimeRoot } from './selection.js';
+import { deepEqual } from '../lib/deep-equal.js';
+export function normalizeReplicaResult(writer, artifact, variables, envelope, protocol) {
+    validateArtifact(artifact);
+    const snapshotRevision = protocol.indexRevision;
+    const errors = collectErrorPaths(envelope.errors ?? []);
+    if (errors.global || envelope.data === undefined) {
+        return Object.freeze({ wrote: false, partial: errors.global, indexKeys: [] });
+    }
+    if (envelope.data === null && (envelope.errors?.length ?? 0) > 0) {
+        // `data: null` is a valid GraphQL error result after non-null propagation.
+        // The ingress coordinator will stale the operation roots without replacing
+        // the last known-good memberships.
+        return Object.freeze({ wrote: false, partial: true, indexKeys: [] });
+    }
+    if (envelope.data === null || !isObject(envelope.data)) {
+        throw new TypeError(`operation ${artifact.id} returned a non-object GraphQL data value`);
+    }
+    let wrote = false;
+    let partial = false;
+    const indexKeys = [];
+    for (const artifactRoot of artifact.roots) {
+        const root = runtimeRoot(artifactRoot);
+        const path = [root.responseKey];
+        const hasValue = Object.prototype.hasOwnProperty.call(envelope.data, root.responseKey);
+        const blocked = pathBlocked(errors, path);
+        const argumentsValue = resolveArguments(root.arguments, variables, root.coverage);
+        const key = replicaIndexKey({ field: root.field, arguments: argumentsValue });
+        const hasErrors = pathHasErrors(errors, path);
+        const rawValue = hasValue ? envelope.data[root.responseKey] : undefined;
+        if (blocked || !hasValue || (rawValue === null && hasErrors)) {
+            wrote =
+                protocol.writeIndexes
+                    ? writer.markIndexStale(key, hasErrors ? 'graphql-partial-error' : 'incomplete-result', snapshotRevision) || wrote
+                    : wrote;
+            indexKeys.push(key);
+            partial = true;
+            continue;
+        }
+        const branch = normalizeBranch(writer, artifact.id, root, rawValue, path, key, snapshotRevision, variables, errors, protocol, indexKeys);
+        const rootPartial = branch.partial ||
+            hasErrors ||
+            !protocol.indexesComplete;
+        const metadata = indexMetadata(root, argumentsValue, branch, rootPartial, hasErrors);
+        if (protocol.writeIndexes &&
+            writer.writeIndex({
+                key,
+                revision: snapshotRevision,
+                records: branch.keys,
+                complete: !rootPartial,
+                metadata
+            })) {
+            wrote = true;
+        }
+        indexKeys.push(key);
+        partial ||= rootPartial;
+    }
+    return Object.freeze({
+        wrote,
+        partial,
+        indexKeys: Object.freeze(indexKeys)
+    });
+}
+function normalizeBranch(writer, artifactId, selection, value, path, indexKey, snapshotRevision, variables, errors, protocol, indexKeys) {
+    if (value === null) {
+        if (!selection.nullable && !pathHasErrors(errors, path)) {
+            throw new TypeError(`operation ${artifactId} returned null for non-null field ${pathLabel(path)}`);
+        }
+        return { keys: [], nullValue: true, partial: false };
+    }
+    if (value === undefined)
+        return { keys: [], nullValue: false, partial: true };
+    if (selection.cardinality === 'one') {
+        const object = normalizeObject(writer, artifactId, selection.selection, value, path, indexKey, undefined, snapshotRevision, variables, errors, protocol, indexKeys);
+        return {
+            keys: object.key === undefined ? [] : [object.key],
+            nullValue: false,
+            partial: object.partial
+        };
+    }
+    if (!Array.isArray(value)) {
+        throw new TypeError(`operation ${artifactId} returned a non-list value for ${pathLabel(path)}`);
+    }
+    const keys = [];
+    let partial = false;
+    for (const [ordinal, entry] of value.entries()) {
+        const entryPath = [...path, ordinal];
+        if (entry === null || entry === undefined) {
+            if (pathHasErrors(errors, entryPath)) {
+                partial = true;
+                continue;
+            }
+            throw new TypeError(`operation ${artifactId} returned null for non-null list item ${pathLabel(entryPath)}`);
+        }
+        const object = normalizeObject(writer, artifactId, selection.selection, entry, entryPath, indexKey, ordinal, snapshotRevision, variables, errors, protocol, indexKeys);
+        if (object.key === undefined)
+            partial = true;
+        else
+            keys.push(object.key);
+        partial ||= object.partial;
+    }
+    return { keys, nullValue: false, partial };
+}
+function normalizeObject(writer, artifactId, selection, value, path, enclosingIndexKey, ordinal, snapshotRevision, variables, errors, protocol, indexKeys) {
+    if (pathBlocked(errors, path))
+        return { partial: true };
+    if (!isObject(value)) {
+        throw new TypeError(`operation ${artifactId} returned a non-object value for ${pathLabel(path)}`);
+    }
+    const fields = Object.create(null);
+    let partial = false;
+    for (const member of selection.members) {
+        if (member.kind !== 'scalar')
+            continue;
+        const fieldPath = [...path, member.responseKey];
+        const hasValue = Object.prototype.hasOwnProperty.call(value, member.responseKey);
+        const rawValue = hasValue ? value[member.responseKey] : undefined;
+        if (pathBlocked(errors, fieldPath) ||
+            !hasValue) {
+            partial = true;
+            continue;
+        }
+        if (rawValue === null && !member.nullable) {
+            if (pathHasErrors(errors, fieldPath)) {
+                partial = true;
+                continue;
+            }
+            throw new TypeError(`operation ${artifactId} returned null for non-null field ${pathLabel(fieldPath)}`);
+        }
+        const next = cloneJsonValue(rawValue);
+        if (Object.prototype.hasOwnProperty.call(fields, member.field)) {
+            if (!deepEqual(fields[member.field], next)) {
+                throw new TypeError(`operation aliases disagree for ${selection.typename}.${member.field}`);
+            }
+            continue;
+        }
+        fields[member.field] = next;
+    }
+    let key;
+    let revision;
+    let incarnation;
+    let resolution;
+    if (selection.storage.kind === 'normalized') {
+        const identity = [];
+        for (const field of selection.storage.identityFields) {
+            if (!Object.prototype.hasOwnProperty.call(fields, field) ||
+                fields[field] === null) {
+                return { partial: true };
+            }
+            identity.push(fields[field]);
+        }
+        key = replicaRecordKey({
+            id: selection.storage.model,
+            identityFields: selection.storage.identityFields
+        }, identity);
+        resolution = protocol.record(path.map(String), selection.storage.model, key, fields);
+        if (resolution === undefined) {
+            if (!protocol.allowSnapshotOnlyRecords) {
+                return { key, partial: true };
+            }
+            /*
+             * This row came from an exact authorized query, but the selected
+             * surface has no safely comparable record clock for its model.
+             * Scope the storage to this operation/index position so a later
+             * snapshot can replace it without corrupting causally normalized
+             * state shared by another operation.
+             */
+            key = embeddedRecordKey(artifactId, enclosingIndexKey, ordinal);
+            revision = snapshotRevision;
+            incarnation = snapshotRevision;
+        }
+        else {
+            if (resolution.evidence.tombstone) {
+                throw new TypeError('live GraphQL row carries tombstone record evidence');
+            }
+            revision = resolution.evidence.revision;
+            incarnation = resolution.evidence.incarnation;
+        }
+    }
+    else {
+        // Embedded output is an operation-local replacement snapshot, not a
+        // normalized server record. Its synthetic incarnation deliberately
+        // advances with the enclosing response so removed sparse fields disappear.
+        key = embeddedRecordKey(artifactId, enclosingIndexKey, ordinal);
+        revision = snapshotRevision;
+        incarnation = snapshotRevision;
+    }
+    if (resolution?.apply !== false) {
+        writer.writeRecord({
+            key,
+            revision,
+            ...(incarnation === undefined ? {} : { incarnation }),
+            fields
+        });
+    }
+    const storedClock = writer.recordClock(key);
+    if (storedClock === undefined ||
+        storedClock.tombstoned ||
+        (resolution?.apply !== false &&
+            (storedClock.revision !== String(revision) ||
+                (incarnation !== undefined &&
+                    storedClock.incarnation !== String(incarnation))))) {
+        return { partial: true };
+    }
+    for (const member of selection.members) {
+        if (member.kind !== 'branch')
+            continue;
+        const branchPath = [...path, member.responseKey];
+        const hasValue = Object.prototype.hasOwnProperty.call(value, member.responseKey);
+        const blocked = pathBlocked(errors, branchPath);
+        const hasErrors = pathHasErrors(errors, branchPath);
+        const rawValue = hasValue ? value[member.responseKey] : undefined;
+        const argumentsValue = resolveArguments(member.arguments, variables, member.coverage);
+        const branchIndexKey = replicaIndexKey({
+            parent: key,
+            field: member.field,
+            arguments: argumentsValue
+        });
+        indexKeys.push(branchIndexKey);
+        if (!hasValue || blocked || (rawValue === null && hasErrors)) {
+            if (protocol.writeIndexes) {
+                writer.markIndexStale(branchIndexKey, hasErrors ? 'graphql-partial-error' : 'incomplete-result', snapshotRevision);
+            }
+            partial = true;
+            continue;
+        }
+        const branch = normalizeBranch(writer, artifactId, member, rawValue, branchPath, branchIndexKey, snapshotRevision, variables, errors, protocol, indexKeys);
+        const branchPartial = branch.partial ||
+            hasErrors ||
+            !protocol.indexesComplete;
+        if (protocol.writeIndexes) {
+            writer.writeIndex({
+                key: branchIndexKey,
+                revision: snapshotRevision,
+                records: branch.keys,
+                complete: !branchPartial,
+                metadata: indexMetadata(member, argumentsValue, branch, branchPartial, hasErrors, key, storedClock.revision)
+            });
+        }
+        partial ||= branchPartial;
+    }
+    return { key, partial };
+}
+function indexMetadata(selection, argumentsValue, branch, partial, hasErrors, parent, parentRevision) {
+    return Object.freeze({
+        ...(parent === undefined ? {} : { parent }),
+        ...(parentRevision === undefined ? {} : { parentRevision: String(parentRevision) }),
+        field: selection.field,
+        arguments: argumentsValue,
+        coverage: coverageFromArtifact(selection.coverage, argumentsValue, branch.keys.length),
+        dependencies: Object.freeze([...new Set(selection.dependencies)].sort()),
+        ...(partial
+            ? { staleReason: hasErrors ? 'graphql-partial-error' : 'incomplete-result' }
+            : {}),
+        nullValue: branch.nullValue
+    });
+}
+function collectErrorPaths(errors) {
+    const paths = [];
+    let global = false;
+    for (const error of errors) {
+        if (!Array.isArray(error.path) || error.path.length === 0) {
+            global = true;
+            continue;
+        }
+        paths.push(Object.freeze([...error.path]));
+    }
+    return { global, paths };
+}
+function pathBlocked(errors, path) {
+    return errors.global || errors.paths.some((errorPath) => isPrefix(errorPath, path));
+}
+function pathHasErrors(errors, path) {
+    return (errors.global ||
+        errors.paths.some((errorPath) => isPrefix(path, errorPath) || isPrefix(errorPath, path)));
+}
+function isPrefix(prefix, value) {
+    return (prefix.length <= value.length &&
+        prefix.every((entry, index) => entry === value[index]));
+}
+function validateArtifact(artifact) {
+    if (!artifact || typeof artifact !== 'object') {
+        throw new TypeError('replica artifact is required');
+    }
+    if (typeof artifact.id !== 'string' || artifact.id.length === 0) {
+        throw new TypeError('replica artifact id must be a non-empty string');
+    }
+    if (!Array.isArray(artifact.roots) || artifact.roots.length === 0) {
+        throw new TypeError(`operation ${artifact.id} must contain at least one root selection`);
+    }
+}
+function pathLabel(path) {
+    return path.map(String).join('.');
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}