@hops-ops/distributed 0.0.0

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

@@ -0,0 +1,13 @@
+import { replicaCommandProjectedLifecycle } from './symbols.js';
+/**
+ * Package-private causal lifecycle used by framework adapters.
+ *
+ * A caller-scoped `receipt.projected` can reject when its AbortSignal fires
+ * after acceptance. The underlying command remains globally pending until
+ * canonical projection evidence settles this independent promise.
+ *
+ * @internal
+ */
+export function replicaCommandProjectedLifecycleOf(receipt) {
+    return receipt[replicaCommandProjectedLifecycle];
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Package-private authority handshake implemented by DistributedReplica.
+ *
+ * This symbol is intentionally not exported from the public replica barrel.
+ * Generated command binders can therefore consume server-derived preset values,
+ * while application code cannot pass an ambient caller-owned inventory.
+ *
+ * @internal
+ */
+export declare const replicaCommandAuthority: unique symbol;
+/**
+ * Package-private post-commit observation channel implemented by
+ * DistributedReplica. Generated command runtimes register here so framework
+ * adapters never guess replica commit ordering.
+ *
+ * @internal
+ */
+export declare const replicaResultObservation: unique symbol;
+/**
+ * Package-private direct-projection commit implemented by DistributedReplica.
+ *
+ * The replica must advance its protocol record clock in the same confirmation
+ * path as the base-cache write. Otherwise an older query response can be
+ * mistaken for an incomplete write after the cache correctly rejects it.
+ *
+ * @internal
+ */
+export declare const replicaCommandDirectProjection: unique symbol;
+/** @internal Package-private; intentionally absent from the public barrel. */
+export declare const replicaCommandProjectedLifecycle: unique symbol;

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

@@ -0,0 +1,30 @@
+/**
+ * Package-private authority handshake implemented by DistributedReplica.
+ *
+ * This symbol is intentionally not exported from the public replica barrel.
+ * Generated command binders can therefore consume server-derived preset values,
+ * while application code cannot pass an ambient caller-owned inventory.
+ *
+ * @internal
+ */
+export const replicaCommandAuthority = Symbol('distributed.replica.command-authority');
+/**
+ * Package-private post-commit observation channel implemented by
+ * DistributedReplica. Generated command runtimes register here so framework
+ * adapters never guess replica commit ordering.
+ *
+ * @internal
+ */
+export const replicaResultObservation = Symbol('distributed.replica.result-observation');
+/**
+ * Package-private direct-projection commit implemented by DistributedReplica.
+ *
+ * The replica must advance its protocol record clock in the same confirmation
+ * path as the base-cache write. Otherwise an older query response can be
+ * mistaken for an incomplete write after the cache correctly rejects it.
+ *
+ * @internal
+ */
+export const replicaCommandDirectProjection = Symbol('distributed.replica.command-direct-projection');
+/** @internal Package-private; intentionally absent from the public barrel. */
+export const replicaCommandProjectedLifecycle = Symbol('distributed.replica.command-projected-lifecycle');

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

@@ -0,0 +1,222 @@
+import type { DistributedCommandMetadata, DistributedCommandState, DistributedRecordRevision, DistributedTrustedPreset } from '../../protocol.js';
+import type { GqlError } from '../../types.js';
+import type { PrepareReplicaCommandOptions, ReplicaCommandArtifact, ReplicaPreparedCommand, ReplicaTrustedPresetDescriptor } from '../commands.js';
+import type { ReplicaDiagnosticsSink } from '../diagnostics.js';
+import type { ReplicaIndexSemanticChange } from '../index-maintenance.js';
+import type { DistributedReplica, ReplicaAuthoritativeScope, ReplicaClientSurface, ReplicaIdentity, ReplicaModelArtifact, ReplicaOptimisticWriter, ReplicaResultEnvelope, ReplicaValue } from '../types.js';
+import { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectedLifecycle, replicaResultObservation } from './symbols.js';
+export type ReplicaCommandSurfaceContract = Readonly<{
+    protocolVersion: 1;
+    schemaHash: string;
+    protocolHash: string;
+    surface: ReplicaClientSurface;
+    trustedPresets: readonly ReplicaTrustedPresetDescriptor[];
+}>;
+export type ReplicaCommandAuthoritySnapshot = Readonly<{
+    generation: number;
+    scope: ReplicaAuthoritativeScope | undefined;
+    trustedPresets: readonly DistributedTrustedPreset[];
+    /** Aborted by the replica when this authorization generation closes. */
+    signal?: AbortSignal;
+}>;
+export type ReplicaCommandAuthorityRegistration = Readonly<{
+    read(): ReplicaCommandAuthoritySnapshot;
+    dispose(): void;
+}>;
+export type ReplicaResultObservationRegistration = Readonly<{
+    dispose(): void;
+}>;
+export type ReplicaCommandDirectProjection = Readonly<{
+    model: ReplicaModelArtifact;
+    identity: ReplicaIdentity;
+    evidence: DistributedRecordRevision;
+    fields: Readonly<Record<string, ReplicaValue>>;
+}>;
+export type ReplicaCommandAuthorityHost = DistributedReplica & {
+    readonly [replicaCommandAuthority]?: (contract: ReplicaCommandSurfaceContract) => ReplicaCommandAuthorityRegistration;
+    readonly [replicaResultObservation]?: (observer: (envelope: ReplicaResultEnvelope<unknown>) => void) => ReplicaResultObservationRegistration;
+    readonly [replicaCommandDirectProjection]?: (commandId: string, projection: ReplicaCommandDirectProjection) => void;
+};
+export type ReplicaCommandTransportRequest = Readonly<{
+    operation: 'mutation';
+    commandName: string;
+    commandId: string;
+    mutationField: string;
+    document: string;
+    operationHash: string;
+    variables: Readonly<Record<string, unknown>>;
+    extensions: Readonly<Record<string, unknown>>;
+    signal?: AbortSignal;
+}>;
+export type ReplicaCommandStatusArtifact = Readonly<{
+    name: string;
+    document: string;
+    operationHash: string;
+    protocol: Readonly<{
+        version: 1;
+        schemaHash: string;
+        protocolHash: string;
+        surface: ReplicaClientSurface;
+        operation: string;
+        /** Exact surface union: command presets plus client-evaluable policy claims. */
+        trustedPresets: readonly ReplicaTrustedPresetDescriptor[];
+    }>;
+}>;
+export type ReplicaCommandStatusRequest = Readonly<{
+    operation: 'status';
+    commandId: string;
+    name: string;
+    document: string;
+    operationHash: string;
+    variables: Readonly<{
+        commandId: string;
+    }>;
+    extensions: Readonly<Record<string, unknown>>;
+    signal?: AbortSignal;
+}>;
+export type ReplicaCommandTransportResult = Readonly<{
+    data?: Readonly<Record<string, unknown>> | null;
+    errors?: readonly GqlError[];
+    extensions?: unknown;
+    status: number;
+}>;
+export interface ReplicaCommandTransport {
+    dispatch(request: ReplicaCommandTransportRequest): Promise<ReplicaCommandTransportResult>;
+    /** Execute the exact compiler-owned command-status operation. */
+    status?(request: ReplicaCommandStatusRequest): Promise<ReplicaCommandTransportResult>;
+}
+export type ReplicaCommandProjectedOutcome<TOutput> = Readonly<{
+    commandId: string;
+    state: 'projected';
+    /** Present for same-transaction Projected<T>, absent for async facts. */
+    result?: TOutput;
+    metadata?: DistributedCommandMetadata;
+}>;
+export type ReplicaCommandStatus = Readonly<{
+    commandId: string;
+    state: DistributedCommandState;
+    /**
+     * Durable causal evidence. The server deliberately omits it for the
+     * non-enumerating `unknown` and compact `expired` states.
+     */
+    metadata?: DistributedCommandMetadata;
+}>;
+export type ReplicaCommandReceipt<TOutput> = Readonly<{
+    commandId: string;
+    state: Extract<DistributedCommandState, 'accepted' | 'accepted_pending_projection' | 'projected'>;
+    /** Typed application payload returned by the generated mutation. */
+    result: TOutput;
+    metadata: DistributedCommandMetadata;
+    /** One exact generated status read. Calls coalesce while in flight. */
+    status(): Promise<ReplicaCommandStatus>;
+    /**
+     * Causal visibility awaitable. It is omitted when no finite projection
+     * contract exists and never resolves because a wall-clock timer elapsed.
+     */
+    projected?: Promise<ReplicaCommandProjectedOutcome<TOutput>>;
+}>;
+export type ReplicaCommandReceiptWithLifecycle = ReplicaCommandReceipt<unknown> & Readonly<{
+    [replicaCommandProjectedLifecycle]?: Promise<ReplicaCommandProjectedOutcome<unknown>>;
+}>;
+/**
+ * Package-private causal lifecycle used by framework adapters.
+ *
+ * A caller-scoped `receipt.projected` can reject when its AbortSignal fires
+ * after acceptance. The underlying command remains globally pending until
+ * canonical projection evidence settles this independent promise.
+ *
+ * @internal
+ */
+/**
+ * Stable recovery handle attached to an ambiguous dispatch error.
+ *
+ * `status()` never infers success from time. The original immutable prepared
+ * mutation remains retained by the runtime/layer; status reports the durable
+ * server outcome without manufacturing rollback or confirmation.
+ */
+export type ReplicaCommandRecoveryReceipt<TOutput = unknown> = Readonly<{
+    commandId: string;
+    status(): Promise<ReplicaCommandStatus>;
+    /** Phantom slot retains the originating generated output type. */
+    readonly __output?: TOutput;
+}>;
+export type ReplicaCommandCallOptions<TOutput> = PrepareReplicaCommandOptions & Readonly<{
+    /**
+     * Cancels dispatch while the command outcome is unknown. After finite
+     * acceptance it instead bounds only this caller's `receipt.projected`
+     * wait; causal tracking and the optimistic layer continue independently.
+     */
+    signal?: AbortSignal;
+    /** Exact same prepared request retries after thrown/ambiguous transport. */
+    transportRetries?: number;
+    onAccepted?: (receipt: ReplicaCommandReceipt<TOutput>) => void | Promise<void>;
+}>;
+export type ReplicaCommandRuntimeErrorCode = 'REPLICA_COMMAND_ABORTED' | 'REPLICA_COMMAND_AUTHORITY_UNAVAILABLE' | 'REPLICA_COMMAND_DISPOSED' | 'REPLICA_COMMAND_OUTCOME_PENDING' | 'REPLICA_COMMAND_PROJECTION_FAILED' | 'REPLICA_COMMAND_PROTOCOL_INVALID' | 'REPLICA_COMMAND_REJECTED' | 'REPLICA_COMMAND_SCOPE_INVALIDATED' | 'REPLICA_COMMAND_STATUS_UNAVAILABLE' | 'REPLICA_COMMAND_TRANSPORT_AMBIGUOUS';
+export type AnyCommandArtifact = ReplicaCommandArtifact<unknown, unknown>;
+export type CommandEntry = AnyCommandArtifact | Readonly<{
+    artifact: AnyCommandArtifact;
+}>;
+export type ArtifactOf<TEntry> = TEntry extends ReplicaCommandArtifact<infer TInput, infer TOutput> ? ReplicaCommandArtifact<TInput, TOutput> : TEntry extends Readonly<{
+    artifact: ReplicaCommandArtifact<infer TInput, infer TOutput>;
+}> ? ReplicaCommandArtifact<TInput, TOutput> : never;
+export type InputOf<TEntry> = ArtifactOf<TEntry> extends ReplicaCommandArtifact<infer TInput, unknown> ? TInput : never;
+export type OutputOf<TEntry> = ArtifactOf<TEntry> extends ReplicaCommandArtifact<unknown, infer TOutput> ? TOutput : never;
+export type ReplicaBoundCommand<TInput, TOutput> = [TInput] extends [void] ? (options?: ReplicaCommandCallOptions<TOutput>) => Promise<ReplicaCommandReceipt<TOutput>> : (input: TInput, options?: ReplicaCommandCallOptions<TOutput>) => Promise<ReplicaCommandReceipt<TOutput>>;
+export type ReplicaBoundCommandPath<TPath extends string, TCommand> = TPath extends `${infer THead}.${infer TTail}` ? THead extends '' ? never : Readonly<{
+    [TKey in THead]: ReplicaBoundCommandPath<TTail, TCommand>;
+}> : TPath extends '' ? never : Readonly<{
+    [TKey in TPath]: TCommand;
+}>;
+export type UnionToIntersection<TValue> = (TValue extends unknown ? (value: TValue) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
+export type SimplifyCommandTree<TValue> = TValue extends (...args: infer _TArguments) => infer _TResult ? TValue : Readonly<{
+    [TKey in keyof TValue]: SimplifyCommandTree<TValue[TKey]>;
+}>;
+export type ReplicaBoundCommands<TEntries extends Readonly<Record<string, CommandEntry>>> = SimplifyCommandTree<UnionToIntersection<{
+    [TKey in Extract<keyof TEntries, string>]: ReplicaBoundCommandPath<TKey, ReplicaBoundCommand<InputOf<TEntries[TKey]>, OutputOf<TEntries[TKey]>>>;
+}[Extract<keyof TEntries, string>]>>;
+export type ReplicaCommandRuntimeOptions = Readonly<{
+    onBackgroundError?: (error: unknown) => void;
+    /** Exact generated status operation for delayed/ambiguous recovery. */
+    status?: ReplicaCommandStatusArtifact;
+    /** Optional shared replica diagnostics sink used only for static artifact inspection. */
+    diagnostics?: ReplicaDiagnosticsSink;
+}>;
+export interface ReplicaCommandRuntime<TEntries extends Readonly<Record<string, CommandEntry>>> {
+    readonly commands: ReplicaBoundCommands<TEntries>;
+    /**
+     * Observe a query/live result only after the replica committed it.
+     *
+     * This completes pending causal awaitables from exact scoped observations;
+     * it does not normalize or confirm cache data itself.
+     */
+    observeResult(envelope: ReplicaResultEnvelope<unknown>): void;
+    dispose(): void;
+}
+export type CapturedAuthority = Readonly<{
+    generation: number;
+    scope: ReplicaAuthoritativeScope;
+    trustedPresets: readonly DistributedTrustedPreset[];
+    signal?: AbortSignal;
+}>;
+export type PendingProjection = {
+    readonly commandId: string;
+    readonly causationId: string;
+    readonly authority: CapturedAuthority;
+    readonly resolve: (value: ReplicaCommandProjectedOutcome<unknown>) => void;
+    readonly reject: (error: unknown) => void;
+    readonly promise: Promise<ReplicaCommandProjectedOutcome<unknown>>;
+    readonly prepared: ReplicaPreparedCommand<unknown, unknown>;
+    abort?: () => void;
+    stopMonitor?: () => void;
+    metadata: DistributedCommandMetadata;
+    settled: boolean;
+};
+export type CommandStatusTracker = {
+    state: DistributedCommandState | undefined;
+    metadata: DistributedCommandMetadata | undefined;
+    inFlight: Promise<ReplicaCommandStatus> | undefined;
+    pending?: PendingProjection;
+};
+export type SemanticReplica = DistributedReplica & {
+    createOptimisticLayer(id: string, update: (writer: ReplicaOptimisticWriter) => void, semanticChanges?: readonly ReplicaIndexSemanticChange[]): void;
+};

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

@@ -0,0 +1 @@
+import { replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectedLifecycle, replicaResultObservation } from './symbols.js';

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

@@ -0,0 +1,3 @@
+/** Public entry for command runtime; implementation lives in ./command-runtime/. */
+export { createReplicaCommandRuntime, ReplicaCommandRuntimeError, replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectedLifecycle, replicaCommandProjectedLifecycleOf, replicaResultObservation } from './command-runtime/index.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 './command-runtime/index.js';

package/dist/replica/command-runtime.js

@@ -0,0 +1,2 @@
+/** Public entry for command runtime; implementation lives in ./command-runtime/. */
+export { createReplicaCommandRuntime, ReplicaCommandRuntimeError, replicaCommandAuthority, replicaCommandDirectProjection, replicaCommandProjectedLifecycle, replicaCommandProjectedLifecycleOf, replicaResultObservation } from './command-runtime/index.js';

package/dist/replica/commands/clone.d.ts

@@ -0,0 +1,12 @@
+import type { ReplicaClientSurface, ReplicaValue } from '../types.js';
+import type { ReplicaCommandGenerators, ReplicaCommandInputDefault, ReplicaCommandRevalidationPlan, ReplicaCommandEffectRelationship, ReplicaCommandScalarCodec, ReplicaCommandTypeDefinition, ReplicaCommandTypeField, ReplicaTrustedPresetDescriptor } from './types.js';
+export declare function cloneClientSurface(surface: ReplicaClientSurface): ReplicaClientSurface;
+export declare function cloneTrustedPresetDescriptors(value: readonly ReplicaTrustedPresetDescriptor[]): readonly ReplicaTrustedPresetDescriptor[];
+export declare function cloneDefinitionValue(definition: ReplicaCommandTypeDefinition, value: unknown, path: readonly string[], defaults: readonly ReplicaCommandInputDefault[], generators: ReplicaCommandGenerators | undefined, label: string): Readonly<Record<string, unknown>>;
+export declare function cloneFieldValue(field: ReplicaCommandTypeField, value: unknown, path: readonly string[], defaults: readonly ReplicaCommandInputDefault[], generators: ReplicaCommandGenerators | undefined, label: string): unknown;
+export declare function cloneNonNullFieldValue(field: ReplicaCommandTypeField, value: unknown, path: readonly string[], defaults: readonly ReplicaCommandInputDefault[], generators: ReplicaCommandGenerators | undefined, label: string): unknown;
+export declare function cloneScalar(codec: ReplicaCommandScalarCodec | undefined, value: unknown, path: string): ReplicaValue;
+export declare function cloneJson(value: unknown, path: string, active?: Set<object>, depth?: number): ReplicaValue;
+export declare function cloneRevalidation(plan: ReplicaCommandRevalidationPlan): ReplicaCommandRevalidationPlan;
+export declare function cloneRelationship(relationship: ReplicaCommandEffectRelationship, path: string): ReplicaCommandEffectRelationship;
+export declare function generateDefault(entry: ReplicaCommandInputDefault, generators: ReplicaCommandGenerators | undefined, path: string): string;

package/dist/replica/commands/clone.js

@@ -0,0 +1,187 @@
+import { createReplicaCommandId } from '../command-id.js';
+import { isPlainRecord } from '../../lib/is-plain-record.js';
+import { MAX_TYPE_DEPTH } from './constants.js';
+import { artifactInvalid, createUlid, defineEnumerable, inputInvalid, requiredString, samePath, validateUlid, validateUuidV7 } from './util.js';
+export function cloneClientSurface(surface) {
+    return surface.kind === 'role'
+        ? Object.freeze({ kind: 'role', name: surface.name })
+        : Object.freeze({
+            kind: 'application',
+            name: surface.name,
+            roles: Object.freeze([...surface.roles])
+        });
+}
+export function cloneTrustedPresetDescriptors(value) {
+    return Object.freeze(value.map(({ name, codec }) => Object.freeze({ name, codec })));
+}
+export function cloneDefinitionValue(definition, value, path, defaults, generators, label) {
+    if (!isPlainRecord(value))
+        inputInvalid(label);
+    const ownKeys = Reflect.ownKeys(value);
+    if (ownKeys.some((key) => typeof key !== 'string'))
+        inputInvalid(label);
+    const known = new Set(definition.fields.map((field) => field.name));
+    for (const key of ownKeys) {
+        if (!known.has(key))
+            inputInvalid(`${label}.${key}`);
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined || !('value' in descriptor)) {
+            inputInvalid(`${label}.${key}`);
+        }
+    }
+    const result = {};
+    for (const field of definition.fields) {
+        const fieldPath = [...path, field.name];
+        const fieldLabel = `${label}.${field.name}`;
+        const present = Object.prototype.hasOwnProperty.call(value, field.name) &&
+            value[field.name] !== undefined;
+        let fieldValue;
+        if (present) {
+            fieldValue = value[field.name];
+        }
+        else {
+            const declared = defaults.find((entry) => samePath(entry.path, fieldPath));
+            if (declared !== undefined) {
+                fieldValue = generateDefault(declared, generators, fieldLabel);
+            }
+            else if (field.nullable) {
+                continue;
+            }
+            else {
+                inputInvalid(fieldLabel);
+            }
+        }
+        defineEnumerable(result, field.name, cloneFieldValue(field, fieldValue, fieldPath, defaults, generators, fieldLabel));
+    }
+    return Object.freeze(result);
+}
+export function cloneFieldValue(field, value, path, defaults, generators, label) {
+    if (value === null) {
+        if (!field.nullable)
+            inputInvalid(label);
+        return null;
+    }
+    if (field.list) {
+        if (!Array.isArray(value))
+            inputInvalid(label);
+        return Object.freeze(value.map((item, index) => {
+            if (item === null) {
+                if (!field.itemNullable)
+                    inputInvalid(`${label}[${index}]`);
+                return null;
+            }
+            return cloneNonNullFieldValue(field, item, path, defaults, generators, `${label}[${index}]`);
+        }));
+    }
+    return cloneNonNullFieldValue(field, value, path, defaults, generators, label);
+}
+export function cloneNonNullFieldValue(field, value, path, defaults, generators, label) {
+    if (field.nested !== undefined) {
+        return cloneDefinitionValue(field.nested, value, path, defaults, generators, label);
+    }
+    return cloneScalar(field.codec, value, label);
+}
+export function cloneScalar(codec, value, path) {
+    switch (codec) {
+        case 'string':
+        case 'string_unvalidated_timestamp':
+        case 'base64':
+            if (typeof value !== 'string')
+                inputInvalid(path);
+            return value;
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                inputInvalid(path);
+            return value;
+        case 'int32':
+            if (typeof value !== 'number' ||
+                !Number.isInteger(value) ||
+                value < -2_147_483_648 ||
+                value > 2_147_483_647) {
+                inputInvalid(path);
+            }
+            return Object.is(value, -0) ? 0 : value;
+        case 'json_number_precision_limited':
+            if (typeof value !== 'number' || !Number.isInteger(value)) {
+                inputInvalid(path);
+            }
+            return Object.is(value, -0) ? 0 : value;
+        case 'float64':
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                inputInvalid(path);
+            }
+            return Object.is(value, -0) ? 0 : value;
+        case 'json':
+            return cloneJson(value, path);
+        default:
+            artifactInvalid(`${path}.codec`);
+    }
+}
+export function cloneJson(value, path, active = new Set(), depth = 0) {
+    if (depth > MAX_TYPE_DEPTH)
+        inputInvalid(path);
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            inputInvalid(path);
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (Array.isArray(value)) {
+        if (active.has(value))
+            inputInvalid(path);
+        active.add(value);
+        const result = Object.freeze(value.map((item, index) => cloneJson(item, `${path}[${index}]`, active, depth + 1)));
+        active.delete(value);
+        return result;
+    }
+    if (!isPlainRecord(value))
+        inputInvalid(path);
+    if (active.has(value))
+        inputInvalid(path);
+    active.add(value);
+    const keys = Reflect.ownKeys(value);
+    if (keys.some((key) => typeof key !== 'string'))
+        inputInvalid(path);
+    const result = {};
+    for (const key of keys.sort()) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined ||
+            !('value' in descriptor) ||
+            descriptor.value === undefined) {
+            inputInvalid(`${path}.${key}`);
+        }
+        defineEnumerable(result, key, cloneJson(descriptor.value, `${path}.${key}`, active, depth + 1));
+    }
+    active.delete(value);
+    return Object.freeze(result);
+}
+export function cloneRevalidation(plan) {
+    return Object.freeze({
+        version: 1,
+        required: plan.required,
+        dependencies: Object.freeze([...plan.dependencies]),
+        models: Object.freeze([...plan.models]),
+        relationships: Object.freeze(plan.relationships.map((relationship, index) => cloneRelationship(relationship, `artifact.revalidation.relationships[${index}]`)))
+    });
+}
+export function cloneRelationship(relationship, path) {
+    return Object.freeze({
+        sourceModel: requiredString(relationship.sourceModel, `${path}.sourceModel`),
+        field: requiredString(relationship.field, `${path}.field`),
+        targetModel: requiredString(relationship.targetModel, `${path}.targetModel`)
+    });
+}
+export function generateDefault(entry, generators, path) {
+    switch (entry.generator) {
+        case 'uuid_v7':
+            return validateUuidV7((generators?.uuidV7 ?? createReplicaCommandId)(), path, 'REPLICA_COMMAND_INPUT_INVALID');
+        case 'ulid':
+            return validateUlid((generators?.ulid ?? createUlid)(), path);
+        default:
+            artifactInvalid(`${path}.generator`);
+    }
+}

package/dist/replica/commands/constants.d.ts

@@ -0,0 +1,6 @@
+export declare const SHA256: RegExp;
+export declare const UUID_V7: RegExp;
+export declare const ULID: RegExp;
+export declare const GRAPHQL_NAME: RegExp;
+export declare const ULID_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export declare const MAX_TYPE_DEPTH = 64;

package/dist/replica/commands/constants.js

@@ -0,0 +1,6 @@
+export const SHA256 = /^sha256:[0-9a-f]{64}$/;
+export const UUID_V7 = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+export const GRAPHQL_NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
+export const ULID_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+export const MAX_TYPE_DEPTH = 64;

package/dist/replica/commands/errors.d.ts

@@ -0,0 +1,7 @@
+import type { ReplicaCommandContractErrorCode } from './types.js';
+export declare function commandErrorMessage(code: ReplicaCommandContractErrorCode, path: string): string;
+export declare class ReplicaCommandContractError extends Error {
+    readonly code: ReplicaCommandContractErrorCode;
+    readonly path: string;
+    constructor(code: ReplicaCommandContractErrorCode, path: string);
+}

package/dist/replica/commands/errors.js

@@ -0,0 +1,22 @@
+export function commandErrorMessage(code, path) {
+    switch (code) {
+        case 'REPLICA_COMMAND_ARTIFACT_INVALID':
+            return `Invalid generated replica command artifact at ${path}`;
+        case 'REPLICA_COMMAND_INPUT_INVALID':
+            return `Invalid replica command input at ${path}`;
+        case 'REPLICA_COMMAND_RECEIPT_MISMATCH':
+            return `Replica command receipt does not match ${path}`;
+        case 'REPLICA_COMMAND_TRUSTED_PRESET_MISMATCH':
+            return `Authoritative trusted preset inventory does not match ${path}`;
+    }
+}
+export class ReplicaCommandContractError extends Error {
+    code;
+    path;
+    constructor(code, path) {
+        super(commandErrorMessage(code, path));
+        this.name = 'ReplicaCommandContractError';
+        this.code = code;
+        this.path = path;
+    }
+}

package/dist/replica/commands/implementation.d.ts

@@ -0,0 +1,8 @@
+/** Re-export surface for command implementation modules (body-split). */
+export * from './util.js';
+export * from './clone.js';
+export * from './presets.js';
+export * from './validate.js';
+export * from './resolve.js';
+export * from './receipt.js';
+export * from './prepare.js';

package/dist/replica/commands/implementation.js

@@ -0,0 +1,8 @@
+/** Re-export surface for command implementation modules (body-split). */
+export * from './util.js';
+export * from './clone.js';
+export * from './presets.js';
+export * from './validate.js';
+export * from './resolve.js';
+export * from './receipt.js';
+export * from './prepare.js';

package/dist/replica/commands/index.d.ts

@@ -0,0 +1,5 @@
+export { prepareReplicaCommand, prepareReplicaCommandWithTrustedPresets } from './prepare.js';
+export { matchReplicaTrustedPresetInventory } from './presets.js';
+export { verifyReplicaCommandReceipt } from './receipt.js';
+export { ReplicaCommandContractError } from './errors.js';
+export type { PrepareReplicaCommandOptions, ReplicaCommandArtifact, ReplicaCommandConfirmation, ReplicaCommandConfirmations, ReplicaCommandContractErrorCode, ReplicaCommandDirectProjection, ReplicaCommandEffect, ReplicaCommandEffectExpression, ReplicaCommandEffectField, ReplicaCommandEffectKey, ReplicaCommandEffectRelationship, ReplicaCommandEffects, ReplicaCommandGenerators, ReplicaCommandInputDefault, ReplicaCommandInputDefaults, ReplicaCommandRevalidationPlan, ReplicaCommandScalarCodec, ReplicaCommandShape, ReplicaCommandTypeDefinition, ReplicaCommandTypeField, ReplicaCommandVariables, ReplicaMatchedTrustedPresetInventory, ReplicaPreparedCommand, ReplicaPreparedCommandEffect, ReplicaPreparedConfirmation, ReplicaPreparedConfirmations, ReplicaPreparedEffectField, ReplicaPreparedEffectKey, ReplicaReceiptVerification, ReplicaTrustedPresetDescriptor } from './types.js';

package/dist/replica/commands/index.js

@@ -0,0 +1,4 @@
+export { prepareReplicaCommand, prepareReplicaCommandWithTrustedPresets } from './prepare.js';
+export { matchReplicaTrustedPresetInventory } from './presets.js';
+export { verifyReplicaCommandReceipt } from './receipt.js';
+export { ReplicaCommandContractError } from './errors.js';

package/dist/replica/commands/prepare.d.ts

@@ -0,0 +1,27 @@
+import type { DistributedTrustedPreset } from '../../protocol.js';
+import type { PrepareReplicaCommandOptions, ReplicaCommandArtifact, ReplicaPreparedCommand } from './types.js';
+export declare function prepareReplicaCommand<TInput, TOutput>(artifact: ReplicaCommandArtifact<TInput, TOutput>, input: TInput, options?: PrepareReplicaCommandOptions): ReplicaPreparedCommand<TInput, TOutput>;
+/**
+ * Finalize a command with values obtained from the replica's current
+ * authoritative scope generation.
+ *
+ * The incoming inventory is scope-wide, so values owned by other commands are
+ * ignored. Every descriptor consumed by this artifact must nevertheless have
+ * one exact name/codec match before defaults, optimism, or transport state is
+ * created.
+ *
+ * This seam is package-internal and deliberately omitted from the public
+ * `@hops-ops/distributed/replica` entry point.
+ *
+ * @internal
+ */
+export declare function prepareReplicaCommandWithTrustedPresets<TInput, TOutput>(artifact: ReplicaCommandArtifact<TInput, TOutput>, input: TInput, authoritativePresets: readonly DistributedTrustedPreset[], options?: PrepareReplicaCommandOptions): ReplicaPreparedCommand<TInput, TOutput>;
+export declare function prepareReplicaCommandInternal<TInput, TOutput>(artifact: ReplicaCommandArtifact<TInput, TOutput>, input: TInput, options: PrepareReplicaCommandOptions, authoritativePresets?: readonly DistributedTrustedPreset[]): ReplicaPreparedCommand<TInput, TOutput>;
+/**
+ * Match two command-local inventories as exact name/codec sets.
+ *
+ * Both sides are reparsed instead of trusting TypeScript annotations. Missing,
+ * extra, duplicate, unsupported, or codec-mismatched entries fail closed.
+ *
+ * @internal
+ */