@hops-ops/distributed 0.0.0

package/dist/replica/command-runtime/errors.js

@@ -0,0 +1,41 @@
+export function commandRuntimeErrorMessage(code) {
+    switch (code) {
+        case 'REPLICA_COMMAND_ABORTED':
+            return 'Caller aborted command dispatch or projection visibility wait';
+        case 'REPLICA_COMMAND_AUTHORITY_UNAVAILABLE':
+            return 'Command dispatch requires a current authoritative replica scope';
+        case 'REPLICA_COMMAND_DISPOSED':
+            return 'Command runtime is disposed';
+        case 'REPLICA_COMMAND_OUTCOME_PENDING':
+            return 'Command outcome remains pending';
+        case 'REPLICA_COMMAND_PROJECTION_FAILED':
+            return 'Command projection failed';
+        case 'REPLICA_COMMAND_PROTOCOL_INVALID':
+            return 'Command response violated the generated protocol contract';
+        case 'REPLICA_COMMAND_REJECTED':
+            return 'Command was rejected';
+        case 'REPLICA_COMMAND_SCOPE_INVALIDATED':
+            return 'Command authorization scope changed';
+        case 'REPLICA_COMMAND_STATUS_UNAVAILABLE':
+            return 'Generated command status transport is unavailable';
+        case 'REPLICA_COMMAND_TRANSPORT_AMBIGUOUS':
+            return 'Command transport outcome is ambiguous';
+    }
+}
+/** Redacted typed failure from the integrated generated-command lifecycle. */
+export class ReplicaCommandRuntimeError extends Error {
+    code;
+    commandId;
+    state;
+    recovery;
+    constructor(code, options = {}) {
+        super(commandRuntimeErrorMessage(code), {
+            ...(options.cause === undefined ? {} : { cause: options.cause })
+        });
+        this.name = 'ReplicaCommandRuntimeError';
+        this.code = code;
+        this.commandId = options.commandId;
+        this.state = options.state;
+        this.recovery = options.recovery;
+    }
+}

package/dist/replica/command-runtime/index.d.ts

@@ -0,0 +1,5 @@
+export { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectedLifecycle, replicaResultObservation } from './symbols.js';
+export type { ReplicaBoundCommand, ReplicaBoundCommands, ReplicaCommandAuthorityHost, ReplicaCommandAuthorityRegistration, ReplicaCommandAuthoritySnapshot, ReplicaCommandCallOptions, ReplicaCommandDirectProjection, ReplicaCommandProjectedOutcome, ReplicaCommandReceipt, ReplicaCommandRecoveryReceipt, ReplicaCommandRuntime, ReplicaCommandRuntimeErrorCode, ReplicaCommandRuntimeOptions, ReplicaCommandStatus, ReplicaCommandStatusArtifact, ReplicaCommandStatusRequest, ReplicaCommandSurfaceContract, ReplicaCommandTransport, ReplicaCommandTransportRequest, ReplicaCommandTransportResult, ReplicaResultObservationRegistration } from './types.js';
+export { ReplicaCommandRuntimeError } from './errors.js';
+export { replicaCommandProjectedLifecycleOf } from './lifecycle.js';
+export { createReplicaCommandRuntime } from './create.js';

package/dist/replica/command-runtime/index.js

@@ -0,0 +1,4 @@
+export { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectedLifecycle, replicaResultObservation } from './symbols.js';
+export { ReplicaCommandRuntimeError } from './errors.js';
+export { replicaCommandProjectedLifecycleOf } from './lifecycle.js';
+export { createReplicaCommandRuntime } from './create.js';

package/dist/replica/command-runtime/lib/binding.d.ts

@@ -0,0 +1,4 @@
+export declare function defineBoundCommand(root: Record<string, unknown>, path: string, command: unknown): void;
+export declare function commandPathSegments(path: string): readonly string[];
+export declare function commandNamespaceCollision(path: string): never;
+export declare function freezeCommandTree(value: Record<string, unknown>): void;

package/dist/replica/command-runtime/lib/binding.js

@@ -0,0 +1,64 @@
+import { isPlainRecord } from '../../../lib/is-plain-record.js';
+export function defineBoundCommand(root, path, command) {
+    const segments = commandPathSegments(path);
+    let namespace = root;
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        const leaf = index === segments.length - 1;
+        const exists = Object.prototype.hasOwnProperty.call(namespace, segment);
+        if (leaf) {
+            if (exists)
+                commandNamespaceCollision(path);
+            Object.defineProperty(namespace, segment, {
+                enumerable: true,
+                configurable: false,
+                writable: false,
+                value: command
+            });
+            continue;
+        }
+        if (exists) {
+            const value = namespace[segment];
+            if (!isPlainRecord(value))
+                commandNamespaceCollision(path);
+            namespace = value;
+            continue;
+        }
+        const child = Object.create(null);
+        Object.defineProperty(namespace, segment, {
+            enumerable: true,
+            configurable: false,
+            writable: false,
+            value: child
+        });
+        namespace = child;
+    }
+}
+export function commandPathSegments(path) {
+    if (path.length === 0 || path.length > 512) {
+        throw new TypeError('replica command path is invalid');
+    }
+    const segments = path.split('.');
+    if (segments.length > 64 ||
+        segments.some((segment) => segment.length === 0 ||
+            segment.length > 128 ||
+            segment.trim() !== segment ||
+            /[\u0000-\u001f\u007f-\u009f]/.test(segment) ||
+            segment === '__proto__' ||
+            segment === 'prototype' ||
+            segment === 'constructor')) {
+        throw new TypeError(`replica command path ${path} is invalid`);
+    }
+    return Object.freeze(segments);
+}
+export function commandNamespaceCollision(path) {
+    throw new TypeError(`replica command namespace collision at ${path}`);
+}
+export function freezeCommandTree(value) {
+    for (const child of Object.values(value)) {
+        if (isPlainRecord(child)) {
+            freezeCommandTree(child);
+        }
+    }
+    Object.freeze(value);
+}

package/dist/replica/command-runtime/lib/effects.d.ts

@@ -0,0 +1,11 @@
+import { type ReplicaPreparedCommand, type ReplicaPreparedCommandEffect, type ReplicaPreparedEffectKey } from '../../commands.js';
+import type { ReplicaIndexSemanticChange } from '../../index-maintenance.js';
+import type { ReplicaModelArtifact, ReplicaOptimisticWriter, ReplicaValue } from '../../types.js';
+export declare function applyOptimisticEffects(writer: ReplicaOptimisticWriter, effects: readonly ReplicaPreparedCommandEffect[]): void;
+export declare function preparedSemanticChanges<TInput, TOutput>(prepared: ReplicaPreparedCommand<TInput, TOutput>): readonly ReplicaIndexSemanticChange[];
+export declare function modelFromKey(model: string, key: ReplicaPreparedEffectKey): ReplicaModelArtifact;
+export declare function identityFromKey(key: ReplicaPreparedEffectKey): readonly ReplicaValue[];
+export declare function fieldsFromEffect(model: string, key: ReplicaPreparedEffectKey, fields: readonly {
+    readonly field: string;
+    readonly value: ReplicaValue;
+}[]): Readonly<Record<string, ReplicaValue>>;

package/dist/replica/command-runtime/lib/effects.js

@@ -0,0 +1,89 @@
+import {} from '../../commands.js';
+import { replicaRecordKey } from '../../identity.js';
+export function applyOptimisticEffects(writer, effects) {
+    for (const effect of effects) {
+        switch (effect.kind) {
+            case 'upsert':
+            case 'patch': {
+                const model = modelFromKey(effect.model, effect.key);
+                writer.writeRecord(model, identityFromKey(effect.key), {
+                    fields: fieldsFromEffect(effect.model, effect.key, effect.fields)
+                });
+                break;
+            }
+            case 'delete':
+                writer.tombstoneRecord(modelFromKey(effect.model, effect.key), identityFromKey(effect.key));
+                break;
+            case 'link':
+            case 'unlink':
+            case 'invalidate_model':
+            case 'invalidate_relationship':
+                // Task 8 consumes the exact semantic context. Guessing a to-one
+                // record link for a to-many relationship would corrupt truth.
+                break;
+        }
+    }
+}
+export function preparedSemanticChanges(prepared) {
+    const dependencies = Object.freeze([...prepared.revalidation.dependencies]);
+    const changes = [];
+    for (const effect of prepared.optimistic.operations) {
+        switch (effect.kind) {
+            case 'upsert':
+            case 'patch':
+            case 'delete':
+                // DistributedReplica captures ordinary writer mutations into the
+                // same layer context. Supplying them again would double-apply the
+                // semantic record operation.
+                break;
+            case 'link':
+            case 'unlink': {
+                const source = modelFromKey(effect.relationship.sourceModel, effect.source);
+                const target = modelFromKey(effect.relationship.targetModel, effect.target);
+                changes.push(Object.freeze({
+                    kind: effect.kind,
+                    sourceModel: effect.relationship.sourceModel,
+                    field: effect.relationship.field,
+                    targetModel: effect.relationship.targetModel,
+                    sourceKey: replicaRecordKey(source, identityFromKey(effect.source)),
+                    targetKey: replicaRecordKey(target, identityFromKey(effect.target)),
+                    dependencies
+                }));
+                break;
+            }
+            case 'invalidate_model':
+            case 'invalidate_relationship':
+                changes.push(Object.freeze({
+                    kind: 'invalidate',
+                    dependencies
+                }));
+                break;
+        }
+    }
+    return Object.freeze(changes);
+}
+export function modelFromKey(model, key) {
+    return Object.freeze({
+        id: model,
+        identityFields: Object.freeze(key.fields.map(({ field }) => field))
+    });
+}
+export function identityFromKey(key) {
+    return Object.freeze(key.fields.map(({ value }) => value));
+}
+export function fieldsFromEffect(model, key, fields) {
+    const result = Object.create(null);
+    for (const field of [
+        { field: '__typename', value: model },
+        ...key.fields,
+        ...fields
+    ]) {
+        Object.defineProperty(result, field.field, {
+            enumerable: true,
+            configurable: false,
+            writable: false,
+            value: field.value
+        });
+    }
+    return Object.freeze(result);
+}

package/dist/replica/command-runtime/lib/index.d.ts

@@ -0,0 +1,9 @@
+/** Command-runtime support modules (inventory, transport, projection, …). */
+export * from './inventory.js';
+export * from './binding.js';
+export * from './effects.js';
+export * from './transport.js';
+export * from './status.js';
+export * from './output.js';
+export * from './projection.js';
+export * from './util.js';

package/dist/replica/command-runtime/lib/index.js

@@ -0,0 +1,9 @@
+/** Command-runtime support modules (inventory, transport, projection, …). */
+export * from './inventory.js';
+export * from './binding.js';
+export * from './effects.js';
+export * from './transport.js';
+export * from './status.js';
+export * from './output.js';
+export * from './projection.js';
+export * from './util.js';

package/dist/replica/command-runtime/lib/inventory.d.ts

@@ -0,0 +1,10 @@
+import { type ReplicaTrustedPresetDescriptor } from '../../commands.js';
+import type { AnyCommandArtifact, CommandEntry, ReplicaCommandStatusArtifact, ReplicaCommandSurfaceContract } from '../types.js';
+export declare function normalizeInventory<TEntries extends Readonly<Record<string, CommandEntry>>>(entries: TEntries): readonly {
+    readonly key: string;
+    readonly artifact: AnyCommandArtifact;
+}[];
+export declare function commandSurfaceContract(artifacts: readonly AnyCommandArtifact[], surfacePresets: readonly ReplicaTrustedPresetDescriptor[] | undefined): ReplicaCommandSurfaceContract;
+export declare function commandStatusArtifact(value: ReplicaCommandStatusArtifact, contract: ReplicaCommandSurfaceContract): ReplicaCommandStatusArtifact;
+export declare function normalizePresetDescriptors(value: readonly ReplicaTrustedPresetDescriptor[], path: string): readonly ReplicaTrustedPresetDescriptor[];
+export declare function samePresetDescriptors(left: readonly ReplicaTrustedPresetDescriptor[], right: readonly ReplicaTrustedPresetDescriptor[]): boolean;

package/dist/replica/command-runtime/lib/inventory.js

@@ -0,0 +1,141 @@
+import { isDistributedTrustedPresetCodec } from '../../../protocol.js';
+import {} from '../../commands.js';
+import { SHA256 } from '../constants.js';
+import { compareCodeUnits } from '../../../lib/compare-code-units.js';
+import { commandNamespaceCollision, commandPathSegments } from './binding.js';
+import { cloneSurface, sameSurface } from './util.js';
+export function normalizeInventory(entries) {
+    if (entries === null || typeof entries !== 'object' || Array.isArray(entries)) {
+        throw new TypeError('replica command inventory must be an object');
+    }
+    const names = new Set();
+    const inventory = Object.entries(entries).map(([key, entry]) => {
+        commandPathSegments(key);
+        const artifact = 'artifact' in entry ? entry.artifact : entry;
+        if (names.has(artifact.name)) {
+            throw new TypeError(`duplicate replica command artifact ${artifact.name}`);
+        }
+        names.add(artifact.name);
+        return Object.freeze({ key, artifact });
+    });
+    const sortedPaths = inventory.map(({ key }) => key).sort(compareCodeUnits);
+    for (let index = 1; index < sortedPaths.length; index += 1) {
+        const previous = sortedPaths[index - 1];
+        const current = sortedPaths[index];
+        if (current.startsWith(`${previous}.`)) {
+            commandNamespaceCollision(current);
+        }
+    }
+    return Object.freeze(inventory);
+}
+export function commandSurfaceContract(artifacts, surfacePresets) {
+    if (artifacts.length === 0) {
+        throw new TypeError('replica command inventory must not be empty');
+    }
+    const first = artifacts[0];
+    const protocol = first.protocol;
+    if (protocol.surface === undefined) {
+        throw new TypeError('generated command protocol requires a client surface');
+    }
+    const trustedPresets = normalizePresetDescriptors(protocol.trustedPresets, 'artifact.protocol.trustedPresets');
+    const commandPresets = new Map();
+    for (const artifact of artifacts) {
+        if (artifact.protocol.version !== 1 ||
+            artifact.protocol.schemaHash !== protocol.schemaHash ||
+            artifact.protocol.protocolHash !== protocol.protocolHash ||
+            !sameSurface(artifact.protocol.surface, protocol.surface) ||
+            !samePresetDescriptors(normalizePresetDescriptors(artifact.protocol.trustedPresets, 'artifact.protocol.trustedPresets'), trustedPresets)) {
+            throw new TypeError('replica command inventory spans incompatible client surfaces');
+        }
+        for (const descriptor of artifact.trustedPresets ?? []) {
+            const previous = commandPresets.get(descriptor.name);
+            if (previous !== undefined && previous.codec !== descriptor.codec) {
+                throw new TypeError(`trusted preset ${descriptor.name} has conflicting codecs`);
+            }
+            commandPresets.set(descriptor.name, Object.freeze({ name: descriptor.name, codec: descriptor.codec }));
+        }
+    }
+    if (surfacePresets !== undefined &&
+        !samePresetDescriptors(normalizePresetDescriptors(surfacePresets, 'status.protocol.trustedPresets'), trustedPresets)) {
+        throw new TypeError('generated command status inventory does not match its client surface');
+    }
+    const surfaceByName = new Map(trustedPresets.map((descriptor) => [descriptor.name, descriptor]));
+    for (const descriptor of commandPresets.values()) {
+        if (surfaceByName.get(descriptor.name)?.codec !== descriptor.codec) {
+            throw new TypeError(`command trusted preset ${descriptor.name} is absent from the client surface`);
+        }
+    }
+    return Object.freeze({
+        protocolVersion: 1,
+        schemaHash: protocol.schemaHash,
+        protocolHash: protocol.protocolHash,
+        surface: cloneSurface(protocol.surface),
+        trustedPresets
+    });
+}
+export function commandStatusArtifact(value, contract) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        typeof value.name !== 'string' ||
+        value.name.trim().length === 0 ||
+        typeof value.document !== 'string' ||
+        value.document.trim().length === 0 ||
+        typeof value.operationHash !== 'string' ||
+        !SHA256.test(value.operationHash) ||
+        value.protocol === null ||
+        typeof value.protocol !== 'object' ||
+        value.protocol.version !== 1 ||
+        value.protocol.operation !== value.operationHash ||
+        value.protocol.schemaHash !== contract.schemaHash ||
+        value.protocol.protocolHash !== contract.protocolHash ||
+        !sameSurface(value.protocol.surface, contract.surface)) {
+        throw new TypeError('generated command status artifact is invalid');
+    }
+    const trustedPresets = normalizePresetDescriptors(value.protocol.trustedPresets, 'status.protocol.trustedPresets');
+    if (!samePresetDescriptors(trustedPresets, contract.trustedPresets)) {
+        throw new TypeError('generated command status inventory does not match its client surface');
+    }
+    return Object.freeze({
+        name: value.name,
+        document: value.document,
+        operationHash: value.operationHash,
+        protocol: Object.freeze({
+            version: 1,
+            schemaHash: contract.schemaHash,
+            protocolHash: contract.protocolHash,
+            surface: cloneSurface(contract.surface),
+            operation: value.operationHash,
+            trustedPresets
+        })
+    });
+}
+export function normalizePresetDescriptors(value, path) {
+    if (!Array.isArray(value)) {
+        throw new TypeError(`${path} must be an array`);
+    }
+    const names = new Set();
+    const result = value.map((descriptor, index) => {
+        if (descriptor === null ||
+            typeof descriptor !== 'object' ||
+            typeof descriptor.name !== 'string' ||
+            descriptor.name.length === 0 ||
+            descriptor.name.length > 128 ||
+            descriptor.name.trim() !== descriptor.name ||
+            /[\u0000-\u001f\u007f-\u009f]/.test(descriptor.name) ||
+            names.has(descriptor.name) ||
+            !isDistributedTrustedPresetCodec(descriptor.codec)) {
+            throw new TypeError(`${path}[${index}] is invalid`);
+        }
+        names.add(descriptor.name);
+        return Object.freeze({
+            name: descriptor.name,
+            codec: descriptor.codec
+        });
+    });
+    return Object.freeze(result.sort(({ name: left }, { name: right }) => compareCodeUnits(left, right)));
+}
+export function samePresetDescriptors(left, right) {
+    return (left.length === right.length &&
+        left.every((descriptor, index) => descriptor.name === right[index]?.name &&
+            descriptor.codec === right[index]?.codec));
+}

package/dist/replica/command-runtime/lib/output.d.ts

@@ -0,0 +1,13 @@
+import { type DistributedCommandMetadata } from '../../../protocol.js';
+import { type ReplicaCommandArtifact } from '../../commands.js';
+import type { ReplicaValue } from '../../types.js';
+export declare function projectionExpectationFingerprint(value: DistributedCommandMetadata['expects'][number]): string;
+export declare function projectionObservationFingerprint(value: DistributedCommandMetadata['observations'][number]): string;
+export declare function recordRevisionFingerprint(value: DistributedCommandMetadata['records'][number]): string;
+export declare function tupleFingerprint(parts: readonly string[]): string;
+export declare function sameStringMultiset(left: readonly string[], right: readonly string[]): boolean;
+export declare function isStringSubset(subset: readonly string[], superset: readonly string[]): boolean;
+export declare function commandOutput<TInput, TOutput>(artifact: ReplicaCommandArtifact<TInput, TOutput>, data: Readonly<Record<string, unknown>> | null | undefined, field: string): unknown;
+export declare function cloneOutputShape(shape: ReplicaCommandArtifact<unknown, unknown>['output'], value: unknown, path: string, depth: number): unknown;
+export declare function cloneOutputScalar(codec: string | undefined, value: unknown, path: string): ReplicaValue;
+export declare function cloneOutputJson(value: unknown, path: string, active: Set<object>, depth: number): ReplicaValue;

package/dist/replica/command-runtime/lib/output.js

@@ -0,0 +1,190 @@
+import {} from '../../../protocol.js';
+import {} from '../../commands.js';
+import { MAX_OUTPUT_DEPTH } from '../constants.js';
+import { ReplicaCommandRuntimeError } from '../errors.js';
+import { compareCodeUnits } from '../../../lib/compare-code-units.js';
+import { isPlainRecord } from '../../../lib/is-plain-record.js';
+import { comparePropertyKeys, outputInvalid } from './util.js';
+export function projectionExpectationFingerprint(value) {
+    return tupleFingerprint([
+        value.projection,
+        value.model,
+        value.scopeToken
+    ]);
+}
+export function projectionObservationFingerprint(value) {
+    return tupleFingerprint([
+        value.causationId,
+        value.projection,
+        value.model,
+        value.scopeToken
+    ]);
+}
+export function recordRevisionFingerprint(value) {
+    return tupleFingerprint([
+        value.model,
+        value.scopeToken,
+        value.incarnation,
+        value.revision,
+        value.tombstone ? '1' : '0',
+        ...(value.path ?? [])
+    ]);
+}
+export function tupleFingerprint(parts) {
+    return parts.map((part) => `${part.length}:${part}`).join('');
+}
+export function sameStringMultiset(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const sortedLeft = [...left].sort(compareCodeUnits);
+    const sortedRight = [...right].sort(compareCodeUnits);
+    return sortedLeft.every((value, index) => value === sortedRight[index]);
+}
+export function isStringSubset(subset, superset) {
+    const remaining = new Map();
+    for (const value of superset) {
+        remaining.set(value, (remaining.get(value) ?? 0) + 1);
+    }
+    for (const value of subset) {
+        const count = remaining.get(value) ?? 0;
+        if (count === 0)
+            return false;
+        remaining.set(value, count - 1);
+    }
+    return true;
+}
+export function commandOutput(artifact, data, field) {
+    if (data === undefined ||
+        data === null ||
+        !Object.prototype.hasOwnProperty.call(data, field) ||
+        Reflect.ownKeys(data).some((key) => key !== field)) {
+        throw new ReplicaCommandRuntimeError('REPLICA_COMMAND_PROTOCOL_INVALID');
+    }
+    return cloneOutputShape(artifact.output, data[field], `data.${field}`, 0);
+}
+export function cloneOutputShape(shape, value, path, depth) {
+    if (depth > MAX_OUTPUT_DEPTH)
+        outputInvalid(path);
+    if (shape.kind !== 'object')
+        outputInvalid(path);
+    if (!isPlainRecord(value))
+        outputInvalid(path);
+    const known = new Set(shape.definition.fields.map(({ name }) => name));
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== 'string' || !known.has(key))
+            outputInvalid(`${path}.${String(key)}`);
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined || !('value' in descriptor)) {
+            outputInvalid(`${path}.${key}`);
+        }
+    }
+    const output = {};
+    for (const field of shape.definition.fields) {
+        const present = Object.prototype.hasOwnProperty.call(value, field.name) &&
+            value[field.name] !== undefined;
+        if (!present) {
+            outputInvalid(`${path}.${field.name}`);
+        }
+        const fieldValue = value[field.name];
+        if (fieldValue === null) {
+            if (!field.nullable)
+                outputInvalid(`${path}.${field.name}`);
+            output[field.name] = null;
+            continue;
+        }
+        const cloneItem = (item, itemPath) => field.nested === undefined
+            ? cloneOutputScalar(field.codec, item, itemPath)
+            : cloneOutputShape({ kind: 'object', definition: field.nested }, item, itemPath, depth + 1);
+        if (field.list) {
+            if (!Array.isArray(fieldValue))
+                outputInvalid(`${path}.${field.name}`);
+            output[field.name] = Object.freeze(fieldValue.map((item, index) => {
+                if (item === null) {
+                    if (!field.itemNullable) {
+                        outputInvalid(`${path}.${field.name}[${index}]`);
+                    }
+                    return null;
+                }
+                return cloneItem(item, `${path}.${field.name}[${index}]`);
+            }));
+        }
+        else {
+            output[field.name] = cloneItem(fieldValue, `${path}.${field.name}`);
+        }
+    }
+    return Object.freeze(output);
+}
+export function cloneOutputScalar(codec, value, path) {
+    switch (codec) {
+        case 'string':
+        case 'string_unvalidated_timestamp':
+        case 'base64':
+            if (typeof value !== 'string')
+                outputInvalid(path);
+            return value;
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                outputInvalid(path);
+            return value;
+        case 'int32':
+            if (typeof value !== 'number' ||
+                !Number.isInteger(value) ||
+                value < -2_147_483_648 ||
+                value > 2_147_483_647) {
+                outputInvalid(path);
+            }
+            return Object.is(value, -0) ? 0 : value;
+        case 'json_number_precision_limited':
+            if (typeof value !== 'number' || !Number.isInteger(value)) {
+                outputInvalid(path);
+            }
+            return Object.is(value, -0) ? 0 : value;
+        case 'float64':
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                outputInvalid(path);
+            }
+            return Object.is(value, -0) ? 0 : value;
+        case 'json':
+            return cloneOutputJson(value, path, new Set(), 0);
+        default:
+            outputInvalid(`${path}.codec`);
+    }
+}
+export function cloneOutputJson(value, path, active, depth) {
+    if (depth > MAX_OUTPUT_DEPTH)
+        outputInvalid(path);
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            outputInvalid(path);
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (typeof value !== 'object' || active.has(value))
+        outputInvalid(path);
+    active.add(value);
+    if (Array.isArray(value)) {
+        const output = Object.freeze(value.map((item, index) => cloneOutputJson(item, `${path}[${index}]`, active, depth + 1)));
+        active.delete(value);
+        return output;
+    }
+    if (!isPlainRecord(value))
+        outputInvalid(path);
+    const output = {};
+    for (const key of Reflect.ownKeys(value).sort(comparePropertyKeys)) {
+        if (typeof key !== 'string')
+            outputInvalid(path);
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined ||
+            !('value' in descriptor) ||
+            descriptor.value === undefined) {
+            outputInvalid(`${path}.${key}`);
+        }
+        output[key] = cloneOutputJson(descriptor.value, `${path}.${key}`, active, depth + 1);
+    }
+    active.delete(value);
+    return Object.freeze(output);
+}

package/dist/replica/command-runtime/lib/projection.d.ts

@@ -0,0 +1,20 @@
+import { type DistributedCommandMetadata } from '../../../protocol.js';
+import { type ReplicaPreparedCommand } from '../../commands.js';
+import type { CapturedAuthority, CommandStatusTracker, PendingProjection, ReplicaCommandAuthorityHost, ReplicaCommandProjectedOutcome, ReplicaCommandStatus } from '../types.js';
+export declare function confirmDirectProjection<TInput, TOutput>(replica: ReplicaCommandAuthorityHost, prepared: ReplicaPreparedCommand<TInput, TOutput>, output: TOutput, metadata: DistributedCommandMetadata): void;
+export declare function pendingProjection(authority: CapturedAuthority, metadata: DistributedCommandMetadata, prepared: ReplicaPreparedCommand<unknown, unknown>): PendingProjection;
+/**
+ * Generated fact commands converge without application polling. Durable status
+ * is the only completion signal; timers merely schedule reads and never infer a
+ * successful outcome.
+ */
+export declare function monitorPendingProjection(controller: PendingProjection, readStatus: () => Promise<ReplicaCommandStatus>, retained: () => boolean, reportError: ((error: unknown) => void) | undefined): void;
+export declare function reportBackgroundErrorSafely(reportError: ((error: unknown) => void) | undefined, error: unknown): void;
+export declare function projectionAuthorityAborted(controller: PendingProjection): boolean;
+export declare function waitForProjectionPoll(delay: number, signals: readonly AbortSignal[]): Promise<void>;
+export declare function settleProjectionSuccess(controller: PendingProjection): void;
+export declare function callerProjectedPromise(controller: PendingProjection, signal: AbortSignal | undefined): Promise<ReplicaCommandProjectedOutcome<unknown>>;
+export declare function attachAuthorityAbort(controller: PendingProjection, onSettled: () => void): void;
+export declare function settleProjectionFailure(controller: PendingProjection, error: unknown): void;
+export declare function settleTrackedProjection(tracker: CommandStatusTracker, pending: Map<string, PendingProjection>): void;
+export declare function failTrackedProjection(tracker: CommandStatusTracker, pending: Map<string, PendingProjection>, error: unknown): void;