@hops-ops/distributed 0.0.0

package/dist/replica/commands/prepare.js

@@ -0,0 +1,77 @@
+import { createReplicaCommandId } from '../command-id.js';
+import { validateArtifact } from './validate.js';
+import { selectReplicaTrustedPresetInventory } from './presets.js';
+import { materializeInput, resolveConfirmations, resolveDirectProjection, resolveEffect } from './resolve.js';
+import { cloneClientSurface, cloneRevalidation, cloneTrustedPresetDescriptors } from './clone.js';
+import { validateUuidV7 } from './util.js';
+export function prepareReplicaCommand(artifact, input, options = {}) {
+    return prepareReplicaCommandInternal(artifact, input, options);
+}
+/**
+ * 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 function prepareReplicaCommandWithTrustedPresets(artifact, input, authoritativePresets, options = {}) {
+    return prepareReplicaCommandInternal(artifact, input, options, authoritativePresets);
+}
+export function prepareReplicaCommandInternal(artifact, input, options, authoritativePresets) {
+    const descriptors = validateArtifact(artifact, authoritativePresets !== undefined);
+    const trustedPresets = authoritativePresets === undefined
+        ? undefined
+        : selectReplicaTrustedPresetInventory(descriptors, authoritativePresets);
+    const defaults = artifact.inputDefaults?.defaults ?? [];
+    const finalizedInput = materializeInput(artifact.input, input, defaults, options.generators);
+    const commandId = validateUuidV7(options.commandId ?? createReplicaCommandId(), 'options.commandId', 'REPLICA_COMMAND_INPUT_INVALID');
+    const variables = Object.freeze({
+        commandId,
+        ...(artifact.input.kind === 'none' ? {} : { input: finalizedInput })
+    });
+    const operations = Object.freeze(artifact.effects.operations.map((effect, index) => resolveEffect(effect, finalizedInput, `artifact.effects.operations[${index}]`, trustedPresets)));
+    const confirmations = resolveConfirmations(artifact.confirmations, finalizedInput, trustedPresets);
+    const directProjection = resolveDirectProjection(artifact.directProjection, finalizedInput, trustedPresets);
+    const protocol = Object.freeze({
+        ...artifact.protocol,
+        surface: cloneClientSurface(artifact.protocol.surface),
+        trustedPresets: cloneTrustedPresetDescriptors(artifact.protocol.trustedPresets)
+    });
+    const revalidation = cloneRevalidation(artifact.revalidation);
+    return Object.freeze({
+        name: artifact.name,
+        commandId,
+        consistency: artifact.consistency,
+        input: finalizedInput,
+        transport: Object.freeze({
+            mutationField: artifact.mutationField,
+            document: artifact.document,
+            operationHash: artifact.operationHash,
+            protocol,
+            variables
+        }),
+        optimistic: Object.freeze({
+            version: 1,
+            operations,
+            fallback: 'revalidate'
+        }),
+        ...(confirmations === undefined ? {} : { confirmations }),
+        ...(directProjection === undefined ? {} : { directProjection }),
+        revalidation
+    });
+}
+/**
+ * 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
+ */

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

@@ -0,0 +1,12 @@
+import { type DistributedTrustedPreset } from '../../protocol.js';
+import type { ReplicaMatchedTrustedPresetInventory, ReplicaTrustedPresetDescriptor } from './types.js';
+export declare function matchReplicaTrustedPresetInventory(expected: readonly ReplicaTrustedPresetDescriptor[], authoritative: readonly DistributedTrustedPreset[]): ReplicaMatchedTrustedPresetInventory;
+export declare function selectReplicaTrustedPresetInventory(expected: readonly ReplicaTrustedPresetDescriptor[], authoritative: readonly DistributedTrustedPreset[]): ReplicaMatchedTrustedPresetInventory;
+/**
+ * Verify one parsed server receipt against the immutable prepared contract.
+ *
+ * This does not drive command status or overlay retirement. It only decides
+ * whether task 9 may safely consume the receipt as matching evidence.
+ */
+export declare function parseReplicaTrustedPresetDescriptors(value: unknown, path?: string): readonly ReplicaTrustedPresetDescriptor[];
+export declare function trustedPresetName(value: unknown, path: string): string;

package/dist/replica/commands/presets.js

@@ -0,0 +1,84 @@
+import { isDistributedTrustedPresetCodec, parseDistributedTrustedPresetInventory } from '../../protocol.js';
+import { isPlainRecord } from '../../lib/is-plain-record.js';
+import { artifactInvalid, trustedPresetMismatch } from './util.js';
+export function matchReplicaTrustedPresetInventory(expected, authoritative) {
+    const descriptors = parseReplicaTrustedPresetDescriptors(expected);
+    let values;
+    try {
+        values = parseDistributedTrustedPresetInventory(authoritative, 'authoritativePresets');
+    }
+    catch {
+        trustedPresetMismatch('authoritativePresets');
+    }
+    if (descriptors.length !== values.length) {
+        trustedPresetMismatch('authoritativePresets');
+    }
+    const byName = new Map(values.map((preset) => [preset.name, preset]));
+    for (let index = 0; index < descriptors.length; index += 1) {
+        const descriptor = descriptors[index];
+        const value = byName.get(descriptor.name);
+        if (value === undefined || value.codec !== descriptor.codec) {
+            trustedPresetMismatch(`authoritativePresets.${descriptor.name}`);
+        }
+    }
+    const resolve = (name) => {
+        const value = byName.get(name);
+        if (value === undefined) {
+            trustedPresetMismatch(`authoritativePresets.${name}`);
+        }
+        return value.value;
+    };
+    return Object.freeze({
+        descriptors,
+        values,
+        resolve
+    });
+}
+export function selectReplicaTrustedPresetInventory(expected, authoritative) {
+    let values;
+    try {
+        values = parseDistributedTrustedPresetInventory(authoritative, 'authoritativePresets');
+    }
+    catch {
+        trustedPresetMismatch('authoritativePresets');
+    }
+    const names = new Set(expected.map(({ name }) => name));
+    return matchReplicaTrustedPresetInventory(expected, values.filter(({ name }) => names.has(name)));
+}
+/**
+ * Verify one parsed server receipt against the immutable prepared contract.
+ *
+ * This does not drive command status or overlay retirement. It only decides
+ * whether task 9 may safely consume the receipt as matching evidence.
+ */
+export function parseReplicaTrustedPresetDescriptors(value, path = 'artifact.trustedPresets') {
+    if (!Array.isArray(value))
+        artifactInvalid(path);
+    const names = new Set();
+    return Object.freeze(value.map((candidate, index) => {
+        const itemPath = `${path}[${index}]`;
+        if (!isPlainRecord(candidate))
+            artifactInvalid(itemPath);
+        const name = trustedPresetName(candidate.name, `${itemPath}.name`);
+        if (names.has(name))
+            artifactInvalid(`${itemPath}.name`);
+        names.add(name);
+        if (!isDistributedTrustedPresetCodec(candidate.codec)) {
+            artifactInvalid(`${itemPath}.codec`);
+        }
+        return Object.freeze({
+            name,
+            codec: candidate.codec
+        });
+    }));
+}
+export function trustedPresetName(value, path) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > 128 ||
+        value.trim() !== value ||
+        /[\u0000-\u001f\u007f-\u009f]/.test(value)) {
+        artifactInvalid(path);
+    }
+    return value;
+}

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

@@ -0,0 +1,3 @@
+import type { DistributedCommandMetadata } from '../../protocol.js';
+import type { ReplicaPreparedCommand, ReplicaReceiptVerification } from './types.js';
+export declare function verifyReplicaCommandReceipt<TInput, TOutput>(prepared: ReplicaPreparedCommand<TInput, TOutput>, receipt: DistributedCommandMetadata): ReplicaReceiptVerification;

package/dist/replica/commands/receipt.js

@@ -0,0 +1,36 @@
+import { receiptMismatch, sameProjectionMultiset } from './util.js';
+export function verifyReplicaCommandReceipt(prepared, receipt) {
+    if (receipt.commandId !== prepared.commandId) {
+        receiptMismatch('receipt.commandId');
+    }
+    if (receipt.consistency !== prepared.consistency) {
+        receiptMismatch('receipt.consistency');
+    }
+    const contract = prepared.confirmations;
+    if (contract?.kind === 'unavailable') {
+        return Object.freeze({
+            kind: 'revalidate',
+            revalidate: true,
+            reason: 'confirmation_unavailable'
+        });
+    }
+    const expected = contract?.kind === 'finite'
+        ? contract.expected.map(({ projector, model }) => ({
+            projection: projector,
+            model
+        }))
+        : [];
+    if (receipt.state === 'in_progress' && receipt.expects.length === 0) {
+        return Object.freeze({
+            kind: 'deferred',
+            revalidate: prepared.revalidation.required
+        });
+    }
+    if (!sameProjectionMultiset(expected, receipt.expects)) {
+        receiptMismatch('receipt.expects');
+    }
+    return Object.freeze({
+        kind: receipt.state === 'in_progress' ? 'deferred' : 'matched',
+        revalidate: prepared.revalidation.required
+    });
+}

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

@@ -0,0 +1,11 @@
+import type { ReplicaValue } from '../types.js';
+import type { ReplicaCommandConfirmations, ReplicaCommandDirectProjection, ReplicaCommandEffect, ReplicaCommandEffectExpression, ReplicaCommandEffectField, ReplicaCommandEffectKey, ReplicaCommandGenerators, ReplicaCommandInputDefault, ReplicaCommandShape, ReplicaCommandTypeDefinition, ReplicaCommandTypeField, ReplicaMatchedTrustedPresetInventory, ReplicaPreparedCommand, ReplicaPreparedCommandEffect, ReplicaPreparedConfirmations, ReplicaPreparedEffectField, ReplicaPreparedEffectKey } from './types.js';
+export declare function materializeInput(shape: ReplicaCommandShape, input: unknown, defaults: readonly ReplicaCommandInputDefault[], generators: ReplicaCommandGenerators | undefined): unknown;
+export declare function resolveEffect(effect: ReplicaCommandEffect, input: unknown, path: string, trustedPresets: ReplicaMatchedTrustedPresetInventory | undefined): ReplicaPreparedCommandEffect;
+export declare function resolveKey(key: ReplicaCommandEffectKey, input: unknown, path: string, trustedPresets: ReplicaMatchedTrustedPresetInventory | undefined): ReplicaPreparedEffectKey;
+export declare function resolveFields(fields: readonly ReplicaCommandEffectField[], input: unknown, path: string, trustedPresets: ReplicaMatchedTrustedPresetInventory | undefined): readonly ReplicaPreparedEffectField[];
+export declare function resolveExpression(expression: ReplicaCommandEffectExpression, input: unknown, path: string, trustedPresets: ReplicaMatchedTrustedPresetInventory | undefined): ReplicaValue;
+export declare function resolveInputPath(input: unknown, segments: readonly string[], path: string): ReplicaValue;
+export declare function resolveConfirmations(confirmations: ReplicaCommandConfirmations | undefined, input: unknown, trustedPresets: ReplicaMatchedTrustedPresetInventory | undefined): ReplicaPreparedConfirmations | undefined;
+export declare function resolveDirectProjection(direct: ReplicaCommandDirectProjection | undefined, input: unknown, trustedPresets: ReplicaMatchedTrustedPresetInventory | undefined): ReplicaPreparedCommand<unknown>['directProjection'] | undefined;
+export declare function fieldAtPath(definition: ReplicaCommandTypeDefinition, segments: readonly string[], path: string): ReplicaCommandTypeField;

package/dist/replica/commands/resolve.js

@@ -0,0 +1,165 @@
+import { isPlainRecord } from '../../lib/is-plain-record.js';
+import { GRAPHQL_NAME } from './constants.js';
+import { artifactInvalid, inputInvalid, requiredString } from './util.js';
+import { cloneDefinitionValue, cloneJson, cloneRelationship } from './clone.js';
+export function materializeInput(shape, input, defaults, generators) {
+    switch (shape.kind) {
+        case 'none':
+            if (input !== undefined)
+                inputInvalid('input');
+            return undefined;
+        case 'object':
+            return cloneDefinitionValue(shape.definition, input, [], defaults, generators, 'input');
+    }
+}
+export function resolveEffect(effect, input, path, trustedPresets) {
+    switch (effect.kind) {
+        case 'upsert':
+        case 'patch':
+            return Object.freeze({
+                kind: effect.kind,
+                model: requiredString(effect.model, `${path}.model`),
+                key: resolveKey(effect.key, input, `${path}.key`, trustedPresets),
+                fields: resolveFields(effect.fields, input, `${path}.fields`, trustedPresets)
+            });
+        case 'delete':
+            return Object.freeze({
+                kind: effect.kind,
+                model: requiredString(effect.model, `${path}.model`),
+                key: resolveKey(effect.key, input, `${path}.key`, trustedPresets)
+            });
+        case 'link':
+        case 'unlink':
+            return Object.freeze({
+                kind: effect.kind,
+                relationship: cloneRelationship(effect.relationship, `${path}.relationship`),
+                source: resolveKey(effect.source, input, `${path}.source`, trustedPresets),
+                target: resolveKey(effect.target, input, `${path}.target`, trustedPresets)
+            });
+        case 'invalidate_model':
+            return Object.freeze({
+                kind: effect.kind,
+                model: requiredString(effect.model, `${path}.model`)
+            });
+        case 'invalidate_relationship':
+            return Object.freeze({
+                kind: effect.kind,
+                relationship: cloneRelationship(effect.relationship, `${path}.relationship`),
+                source: resolveKey(effect.source, input, `${path}.source`, trustedPresets)
+            });
+        default:
+            artifactInvalid(`${path}.kind`);
+    }
+}
+export function resolveKey(key, input, path, trustedPresets) {
+    if (key === null ||
+        typeof key !== 'object' ||
+        !Array.isArray(key.fields) ||
+        key.fields.length === 0) {
+        artifactInvalid(path);
+    }
+    return Object.freeze({
+        fields: resolveFields(key.fields, input, `${path}.fields`, trustedPresets)
+    });
+}
+export function resolveFields(fields, input, path, trustedPresets) {
+    if (!Array.isArray(fields))
+        artifactInvalid(path);
+    const names = new Set();
+    return Object.freeze(fields.map((field, index) => {
+        const fieldPath = `${path}[${index}]`;
+        const name = requiredString(field.field, `${fieldPath}.field`);
+        if (names.has(name))
+            artifactInvalid(`${fieldPath}.field`);
+        names.add(name);
+        return Object.freeze({
+            field: name,
+            value: resolveExpression(field.value, input, `${fieldPath}.value`, trustedPresets)
+        });
+    }));
+}
+export function resolveExpression(expression, input, path, trustedPresets) {
+    switch (expression.kind) {
+        case 'input':
+            return resolveInputPath(input, expression.path, path);
+        case 'constant':
+            return cloneJson(expression.value, `${path}.value`);
+        case 'null':
+            return null;
+        case 'trusted_preset':
+            if (trustedPresets === undefined)
+                artifactInvalid(path);
+            return trustedPresets.resolve(expression.name);
+        default:
+            artifactInvalid(`${path}.kind`);
+    }
+}
+export function resolveInputPath(input, segments, path) {
+    if (!Array.isArray(segments) ||
+        segments.length === 0 ||
+        segments.some((segment) => !GRAPHQL_NAME.test(segment))) {
+        artifactInvalid(`${path}.path`);
+    }
+    let current = input;
+    for (const segment of segments) {
+        if (!isPlainRecord(current) ||
+            !Object.prototype.hasOwnProperty.call(current, segment)) {
+            inputInvalid(`input.${segments.join('.')}`);
+        }
+        current = current[segment];
+    }
+    if (current === undefined)
+        inputInvalid(`input.${segments.join('.')}`);
+    return current;
+}
+export function resolveConfirmations(confirmations, input, trustedPresets) {
+    if (confirmations === undefined)
+        return undefined;
+    if (confirmations.kind === 'unavailable') {
+        return Object.freeze({ kind: 'unavailable' });
+    }
+    return Object.freeze({
+        kind: 'finite',
+        expected: Object.freeze(confirmations.expected.map((confirmation, index) => {
+            const path = `artifact.confirmations.expected[${index}]`;
+            const partition = confirmation.partition === undefined
+                ? undefined
+                : resolveExpression(confirmation.partition, input, `${path}.partition`, trustedPresets);
+            return Object.freeze({
+                projector: requiredString(confirmation.projector, `${path}.projector`),
+                model: requiredString(confirmation.model, `${path}.model`),
+                key: resolveKey(confirmation.key, input, `${path}.key`, trustedPresets),
+                ...(partition === undefined ? {} : { partition })
+            });
+        }))
+    });
+}
+export function resolveDirectProjection(direct, input, trustedPresets) {
+    if (direct === undefined)
+        return undefined;
+    const partition = direct.partition === undefined
+        ? undefined
+        : resolveExpression(direct.partition, input, 'artifact.directProjection.partition', trustedPresets);
+    return Object.freeze({
+        topology: Object.freeze({ ...direct.topology }),
+        model: direct.model,
+        identityFields: Object.freeze([...direct.identityFields]),
+        ...(partition === undefined ? {} : { partition }),
+        changeEpoch: direct.changeEpoch
+    });
+}
+export function fieldAtPath(definition, segments, path) {
+    let current = definition;
+    for (let index = 0; index < segments.length; index += 1) {
+        const field = current.fields.find(({ name }) => name === segments[index]);
+        if (field === undefined)
+            artifactInvalid(`${path}.path`);
+        if (index + 1 === segments.length)
+            return field;
+        if (field.list || field.nested === undefined) {
+            artifactInvalid(`${path}.path`);
+        }
+        current = field.nested;
+    }
+    artifactInvalid(`${path}.path`);
+}

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

@@ -0,0 +1,278 @@
+import type { DistributedCommandConsistency, DistributedTrustedPreset, DistributedTrustedPresetCodec } from '../../protocol.js';
+import type { ReplicaClientSurface, ReplicaValue } from '../types.js';
+export type ReplicaCommandScalarCodec = DistributedTrustedPresetCodec;
+/** Static name/codec declaration emitted without a server-derived value. */
+export type ReplicaTrustedPresetDescriptor = {
+    readonly name: string;
+    readonly codec: ReplicaCommandScalarCodec;
+};
+export type ReplicaCommandShape = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'object';
+    readonly definition: ReplicaCommandTypeDefinition;
+};
+export type ReplicaCommandTypeDefinition = {
+    readonly name: string;
+    readonly fields: readonly ReplicaCommandTypeField[];
+};
+export type ReplicaCommandTypeField = {
+    readonly name: string;
+    readonly typeName: string;
+    readonly nullable: boolean;
+    readonly list: boolean;
+    readonly itemNullable: boolean;
+    readonly codec?: ReplicaCommandScalarCodec;
+    readonly nested?: ReplicaCommandTypeDefinition;
+};
+export type ReplicaCommandInputDefault = {
+    readonly path: readonly string[];
+    readonly generator: 'uuid_v7' | 'ulid';
+};
+export type ReplicaCommandInputDefaults = {
+    readonly version: 1;
+    readonly defaults: readonly ReplicaCommandInputDefault[];
+};
+export type ReplicaCommandEffectExpression = {
+    readonly kind: 'input';
+    readonly path: readonly string[];
+} | {
+    readonly kind: 'trusted_preset';
+    readonly name: string;
+} | {
+    readonly kind: 'constant';
+    readonly value: ReplicaValue;
+} | {
+    readonly kind: 'null';
+};
+export type ReplicaCommandEffectField = {
+    readonly field: string;
+    readonly value: ReplicaCommandEffectExpression;
+};
+export type ReplicaCommandEffectKey = {
+    readonly fields: readonly ReplicaCommandEffectField[];
+};
+export type ReplicaCommandEffectRelationship = {
+    readonly sourceModel: string;
+    readonly field: string;
+    readonly targetModel: string;
+};
+export type ReplicaCommandEffect = {
+    readonly kind: 'upsert' | 'patch';
+    readonly model: string;
+    readonly key: ReplicaCommandEffectKey;
+    readonly fields: readonly ReplicaCommandEffectField[];
+} | {
+    readonly kind: 'delete';
+    readonly model: string;
+    readonly key: ReplicaCommandEffectKey;
+} | {
+    readonly kind: 'link' | 'unlink';
+    readonly relationship: ReplicaCommandEffectRelationship;
+    readonly source: ReplicaCommandEffectKey;
+    readonly target: ReplicaCommandEffectKey;
+} | {
+    readonly kind: 'invalidate_model';
+    readonly model: string;
+} | {
+    readonly kind: 'invalidate_relationship';
+    readonly relationship: ReplicaCommandEffectRelationship;
+    readonly source: ReplicaCommandEffectKey;
+};
+export type ReplicaCommandEffects = {
+    readonly version: 1;
+    readonly operations: readonly ReplicaCommandEffect[];
+    readonly fallback: 'revalidate';
+};
+export type ReplicaCommandConfirmation = {
+    readonly projector: string;
+    readonly model: string;
+    readonly key: ReplicaCommandEffectKey;
+    readonly partition?: ReplicaCommandEffectExpression;
+};
+export type ReplicaCommandConfirmations = {
+    readonly version: 1;
+    readonly kind: 'finite';
+    readonly expected: readonly ReplicaCommandConfirmation[];
+    readonly fallback: 'revalidate';
+} | {
+    readonly version: 1;
+    readonly kind: 'unavailable';
+    readonly expected: readonly [];
+    readonly fallback: 'revalidate';
+};
+export type ReplicaCommandDirectProjection = {
+    readonly topology: {
+        readonly version: 1;
+        readonly name: string;
+        readonly digest: string;
+    };
+    readonly model: string;
+    readonly identityFields: readonly string[];
+    readonly partition?: ReplicaCommandEffectExpression;
+    readonly changeEpoch: string;
+};
+/**
+ * Conservative invalidation inventory emitted by the compiler.
+ *
+ * `dependencies` are the role-visible physical/model dependencies which task 9
+ * may hand to the replica revalidator. `required` means the command cannot be
+ * proven by its local effect/confirmation contract alone.
+ */
+export type ReplicaCommandRevalidationPlan = {
+    readonly version: 1;
+    readonly required: boolean;
+    readonly dependencies: readonly string[];
+    readonly models: readonly string[];
+    readonly relationships: readonly ReplicaCommandEffectRelationship[];
+};
+/**
+ * Framework-neutral executable command descriptor emitted by `dctl client`.
+ *
+ * The compiler has already validated the Rust-owned declaration. Runtime
+ * validation remains fail-closed so a stale or hand-edited artifact cannot
+ * create optimistic cache truth.
+ */
+export type ReplicaCommandArtifact<TInput = void, TOutput = unknown> = {
+    readonly version: 1;
+    readonly name: string;
+    readonly mutationField: string;
+    readonly document: string;
+    readonly operationHash: string;
+    readonly protocol: {
+        readonly version: 1;
+        readonly schemaHash: string;
+        readonly protocolHash: string;
+        readonly surface: ReplicaClientSurface;
+        readonly operation: string;
+        /** Exact scope-wide preset inventory for this generated client surface. */
+        readonly trustedPresets: readonly ReplicaTrustedPresetDescriptor[];
+    };
+    readonly input: ReplicaCommandShape;
+    readonly output: ReplicaCommandShape;
+    readonly inputDefaults?: ReplicaCommandInputDefaults;
+    readonly consistency: DistributedCommandConsistency;
+    readonly effects: ReplicaCommandEffects;
+    readonly confirmations?: ReplicaCommandConfirmations;
+    readonly directProjection?: ReplicaCommandDirectProjection;
+    readonly trustedPresets?: readonly ReplicaTrustedPresetDescriptor[];
+    readonly revalidation: ReplicaCommandRevalidationPlan;
+    /** Phantom slots preserve generated input/output types. */
+    readonly __input?: TInput;
+    readonly __output?: TOutput;
+};
+export type ReplicaPreparedEffectField = {
+    readonly field: string;
+    readonly value: ReplicaValue;
+};
+export type ReplicaPreparedEffectKey = {
+    readonly fields: readonly ReplicaPreparedEffectField[];
+};
+export type ReplicaPreparedCommandEffect = {
+    readonly kind: 'upsert' | 'patch';
+    readonly model: string;
+    readonly key: ReplicaPreparedEffectKey;
+    readonly fields: readonly ReplicaPreparedEffectField[];
+} | {
+    readonly kind: 'delete';
+    readonly model: string;
+    readonly key: ReplicaPreparedEffectKey;
+} | {
+    readonly kind: 'link' | 'unlink';
+    readonly relationship: ReplicaCommandEffectRelationship;
+    readonly source: ReplicaPreparedEffectKey;
+    readonly target: ReplicaPreparedEffectKey;
+} | {
+    readonly kind: 'invalidate_model';
+    readonly model: string;
+} | {
+    readonly kind: 'invalidate_relationship';
+    readonly relationship: ReplicaCommandEffectRelationship;
+    readonly source: ReplicaPreparedEffectKey;
+};
+export type ReplicaPreparedConfirmation = {
+    readonly projector: string;
+    readonly model: string;
+    readonly key: ReplicaPreparedEffectKey;
+    readonly partition?: ReplicaValue;
+};
+export type ReplicaPreparedConfirmations = {
+    readonly kind: 'finite';
+    readonly expected: readonly ReplicaPreparedConfirmation[];
+} | {
+    readonly kind: 'unavailable';
+};
+export type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer TItem)[] ? readonly DeepReadonly<TItem>[] : T extends object ? {
+    readonly [TKey in keyof T]: DeepReadonly<T[TKey]>;
+} : T;
+export type ReplicaCommandVariables<TInput> = [TInput] extends [void] ? Readonly<{
+    commandId: string;
+}> : Readonly<{
+    commandId: string;
+    input: DeepReadonly<TInput>;
+}>;
+export type ReplicaPreparedCommand<TInput = void, TOutput = unknown> = {
+    readonly name: string;
+    readonly commandId: string;
+    readonly consistency: DistributedCommandConsistency;
+    readonly input: DeepReadonly<TInput>;
+    readonly transport: {
+        readonly mutationField: string;
+        readonly document: string;
+        readonly operationHash: string;
+        readonly protocol: ReplicaCommandArtifact<TInput, TOutput>['protocol'];
+        readonly variables: ReplicaCommandVariables<TInput>;
+    };
+    readonly optimistic: {
+        readonly version: 1;
+        readonly operations: readonly ReplicaPreparedCommandEffect[];
+        readonly fallback: 'revalidate';
+    };
+    readonly confirmations?: ReplicaPreparedConfirmations;
+    readonly directProjection?: {
+        readonly topology: ReplicaCommandDirectProjection['topology'];
+        readonly model: string;
+        readonly identityFields: readonly string[];
+        readonly partition?: ReplicaValue;
+        readonly changeEpoch: string;
+    };
+    readonly revalidation: ReplicaCommandRevalidationPlan;
+    /** Phantom output slot for generated wrappers. */
+    readonly __output?: TOutput;
+};
+export type ReplicaCommandGenerators = {
+    readonly uuidV7?: () => string;
+    readonly ulid?: () => string;
+};
+export type PrepareReplicaCommandOptions = {
+    readonly commandId?: string;
+    readonly generators?: ReplicaCommandGenerators;
+};
+/**
+ * Exact immutable command-local view over a server-derived scope inventory.
+ *
+ * The backing lookup is intentionally not exposed as a mutable Map.
+ *
+ * @internal
+ */
+export type ReplicaMatchedTrustedPresetInventory = Readonly<{
+    descriptors: readonly ReplicaTrustedPresetDescriptor[];
+    values: readonly DistributedTrustedPreset[];
+    resolve(name: string): ReplicaValue;
+}>;
+export type ReplicaReceiptVerification = {
+    readonly kind: 'matched';
+    readonly revalidate: boolean;
+} | {
+    readonly kind: 'deferred';
+    readonly revalidate: boolean;
+} | {
+    readonly kind: 'revalidate';
+    readonly revalidate: true;
+    readonly reason: 'confirmation_unavailable';
+};
+export type ReplicaCommandContractErrorCode = 'REPLICA_COMMAND_ARTIFACT_INVALID' | 'REPLICA_COMMAND_INPUT_INVALID' | 'REPLICA_COMMAND_RECEIPT_MISMATCH' | 'REPLICA_COMMAND_TRUSTED_PRESET_MISMATCH';
+export type TrustedPresetReference = Readonly<{
+    name: string;
+    path: string;
+}>;

package/dist/replica/commands/types.js

@@ -0,0 +1,2 @@
+/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export {};