graphddb 0.1.0 → 0.2.0

package/dist/types-D6qLpw2M.d.ts

@@ -0,0 +1,4514 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
+interface RangeCondition {
+    operator: 'begins_with';
+    key: string;
+    value: unknown;
+}
+interface DynamoDBOperationBase {
+    tableName: string;
+    projectionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    consistentRead?: boolean;
+    /**
+     * Server-side DynamoDB FilterExpression (independent of the
+     * KeyConditionExpression and ProjectionExpression). Names/values here are
+     * merged into the command's ExpressionAttributeNames/Values by the executor.
+     */
+    filterExpression?: string;
+    filterExpressionAttributeNames?: Record<string, string>;
+    filterExpressionAttributeValues?: Record<string, unknown>;
+}
+interface GetItemOperation extends DynamoDBOperationBase {
+    type: 'GetItem';
+    keyCondition: Record<string, unknown>;
+}
+interface QueryOperation extends DynamoDBOperationBase {
+    type: 'Query';
+    indexName?: string;
+    keyCondition: Record<string, unknown>;
+    rangeCondition?: RangeCondition;
+    scanIndexForward?: boolean;
+    limit?: number;
+    exclusiveStartKey?: Record<string, unknown>;
+}
+interface BatchGetItemOperation extends DynamoDBOperationBase {
+    type: 'BatchGetItem';
+    keys: Record<string, unknown>[];
+}
+type DynamoDBOperation = GetItemOperation | QueryOperation | BatchGetItemOperation;
+interface ExecutionPlan {
+    operations: DynamoDBOperation[];
+}
+type ResolvedKey = {
+    type: 'pk';
+    partial: boolean;
+    inputFieldNames: string[];
+} | {
+    type: 'gsi';
+    indexName: string;
+    unique: boolean;
+    partial: boolean;
+    inputFieldNames: string[];
+};
+
+/**
+ * Internal brand identifying a {@link RawCondition} produced by {@link cond}.
+ */
+declare const RAW_COND: unique symbol;
+/**
+ * A compiled raw filter fragment produced by the {@link cond} escape hatch.
+ * Column references are pre-resolved to `#`-aliased placeholders and embedded
+ * values to `:`-aliased parameters; the executor merges these alongside the
+ * declarative filter's names/values.
+ *
+ * @typeParam M - The owning model brand. A `cond` is only assignable to a
+ *   `FilterInput<M>` of the same model, so embedding a different model's column
+ *   is a compile error.
+ */
+interface RawCondition<M = unknown> {
+    readonly [RAW_COND]: true;
+    /** @internal phantom — owning-model brand. */
+    readonly __model?: M;
+    /** Expression fragment with `{name}` / `{value}` markers already inlined. */
+    readonly template: TemplateStringsArray;
+    /** The interpolated parts, each either a Column ref or an embedded value. */
+    readonly parts: unknown[];
+}
+/**
+ * The interpolation slot type accepted by {@link cond}. A column reference
+ * (`Model.col.<field>`) — required for naming a column — or an embedded value
+ * that is type-checked against that column. Bare column-name strings are NOT
+ * accepted; you must use a {@link Column} reference, which keeps the fragment
+ * refactor-safe.
+ *
+ * @typeParam M - The owning model brand. Constrains all columns to one model,
+ *   so passing another model's column is a compile error.
+ */
+type CondSlot<M> = Column<any, M> | string | number | boolean | Date;
+/**
+ * Raw DynamoDB condition escape hatch.
+ *
+ * Use only for conditions the declarative operator objects cannot express.
+ * Column names MUST be embedded via `Model.col.<field>` references (never bare
+ * strings); values are embedded directly and parameterized.
+ *
+ * @example
+ * ```ts
+ * filter: cond`${User.col.age} > ${18} and attribute_exists(${User.col.email})`
+ * ```
+ */
+declare function cond<M = unknown>(template: TemplateStringsArray, ...parts: CondSlot<M>[]): RawCondition<M>;
+
+/**
+ * Type-safe attribute condition API (DynamoDB `FilterExpression`).
+ *
+ * Modeled on AWS AppSync's `ModelFilterInput`: field keys map to either an
+ * equality shorthand (a bare value) or an operator object. Operators are
+ * constrained per field type so that e.g. `beginsWith` on a numeric field is a
+ * compile error. Logical groups are expressed with the reserved `and` / `or`
+ * keys (arrays) and `not` (a single nested filter).
+ *
+ * The condition is typed against the *full* Entity `T` (its scalar fields),
+ * **not** the `select` projection — so server-side filters can reference
+ * attributes that are not projected, and nested-relation filters stay fully
+ * type-checked without callbacks (this is what structurally closes the #29
+ * type hole).
+ */
+type IsString<V> = [V] extends [string] ? true : false;
+type IsNumber<V> = [V] extends [number | bigint] ? true : false;
+/**
+ * Operators common to all scalar field types.
+ *
+ * @typeParam V - The declared field value type.
+ */
+interface CommonOperators<V> {
+    /** `#f = :v` */
+    eq?: V;
+    /** `#f <> :v` */
+    ne?: V;
+    /** `#f IN (:v0, :v1, …)` */
+    in?: readonly V[];
+    /** `attribute_exists(#f)` (true) / `attribute_not_exists(#f)` (false) */
+    attributeExists?: boolean;
+    /** `attribute_type(#f, :v)` — DynamoDB attribute type code, e.g. `'S'`, `'N'`. */
+    attributeType?: string;
+}
+/** Comparison operators valid on orderable (string / number / Date) fields. */
+interface ComparableOperators<V> {
+    /** `#f > :v` */
+    gt?: V;
+    /** `#f >= :v` */
+    ge?: V;
+    /** `#f < :v` */
+    lt?: V;
+    /** `#f <= :v` */
+    le?: V;
+    /** `#f BETWEEN :lo AND :hi` */
+    between?: readonly [V, V];
+}
+/** Operators valid only on string fields. */
+interface StringOnlyOperators {
+    /** `begins_with(#f, :v)` */
+    beginsWith?: string;
+    /** `contains(#f, :v)` */
+    contains?: string;
+    /** `NOT contains(#f, :v)` */
+    notContains?: string;
+    /** `size(#f) = :v` (string length) */
+    size?: number;
+}
+/**
+ * The operator object accepted for a field of value type `V`.
+ *
+ * - string  → common + comparable + string-only (`beginsWith`, `contains`, …)
+ * - number  → common + comparable (no `beginsWith` / `contains`)
+ * - Date    → common + comparable (compared against `Date`)
+ * - boolean → common only
+ * - other   → common only
+ */
+type FieldCondition<V> = IsString<V> extends true ? CommonOperators<V> & ComparableOperators<V> & StringOnlyOperators : IsNumber<V> extends true ? CommonOperators<V> & ComparableOperators<V> : [NonNullable<V>] extends [Date] ? CommonOperators<V> & ComparableOperators<V> : CommonOperators<V>;
+/** A field key may be given as an equality shorthand or an operator object. */
+type FieldFilter<V> = V | FieldCondition<V>;
+/**
+ * Same scalar classification used across the public API: a field is filterable
+ * when its value type is a leaf scalar (string/number/boolean/Date/bigint/…),
+ * not a relation (`DDBModel` / `DDBModel[]`) or embedded object.
+ */
+type FilterableScalar = string | number | boolean | bigint | Date | null | undefined;
+/**
+ * The set of filterable scalar field keys of `T` (relations and embedded
+ * objects excluded). Mirrors the projection rules in `selectable.ts`.
+ */
+type ScalarKeys<T> = {
+    [K in keyof T]: T[K] extends Function ? never : T[K] extends Array<infer E> ? [E] extends [DDBModel] ? never : K : NonNullable<T[K]> extends DDBModel ? never : NonNullable<T[K]> extends FilterableScalar ? K : never;
+}[keyof T];
+/**
+ * AppSync `ModelFilterInput`-compatible filter for the full Entity `T`.
+ *
+ * Field keys (scalar attributes of `T`) accept an equality shorthand or an
+ * operator object; the reserved `and` / `or` keys take arrays of nested
+ * filters and `not` takes a single nested filter.
+ */
+type FilterInput<T> = ({
+    [K in ScalarKeys<T>]?: FieldFilter<T[K]>;
+} & {
+    and?: readonly (FilterInput<T> | RawCondition<T>)[];
+    or?: readonly (FilterInput<T> | RawCondition<T>)[];
+    not?: FilterInput<T> | RawCondition<T>;
+}) | RawCondition<T>;
+
+/**
+ * Internal brand symbol identifying a compiled select builder at runtime.
+ * Consumers should not depend on this; it is used by the execution layer to
+ * distinguish a builder instance from a plain select object.
+ */
+declare const SELECT_BUILDER: unique symbol;
+/**
+ * The normalized spec a select builder resolves to. This is the shape the
+ * planner / traversal layer consumes. `filter` is the declarative server-side
+ * DynamoDB FilterExpression input.
+ *
+ * @internal
+ */
+interface SelectBuilderSpec {
+    readonly [SELECT_BUILDER]: true;
+    select: Record<string, unknown>;
+    filter?: Record<string, unknown>;
+    limit?: number;
+    after?: string;
+    order?: 'ASC' | 'DESC';
+}
+/**
+ * Top-level select builder produced by `Model.project(...)`.
+ *
+ * Two-stage, model-bound inference: the entity type `T` is fixed by the model,
+ * and the projection `S` is inferred from the `project(...)` argument.
+ *
+ * `.filter(...)` is the declarative server-side DynamoDB FilterExpression,
+ * typed against the full Entity `T` (so it may reference unprojected attributes
+ * and type-checks operators / value types).
+ *
+ * @typeParam T - The (model-bound) Entity type.
+ * @typeParam S - The (fixed) select projection.
+ */
+interface SelectBuilder<T, S> {
+    /** Declarative server-side DynamoDB FilterExpression, typed against `T`. */
+    filter(filter: FilterInput<T>): SelectBuilder<T, S>;
+}
+/**
+ * Relation select builder produced by `Model.relation(...)`. Same model-bound
+ * two-stage inference as {@link SelectBuilder}, plus per-relation pagination
+ * controls.
+ *
+ * @typeParam T - The (model-bound) relation target Entity type.
+ * @typeParam S - The (fixed) select projection for this relation.
+ */
+interface RelationBuilder<T, S> {
+    filter(filter: FilterInput<T>): RelationBuilder<T, S>;
+    limit(limit: number): RelationBuilder<T, S>;
+    after(cursor: string): RelationBuilder<T, S>;
+    order(order: 'ASC' | 'DESC'): RelationBuilder<T, S>;
+}
+/**
+ * Extracts the projection `S` carried by a top-level or relation builder.
+ * Used by `QueryResult` so a builder in a select position resolves to the same
+ * result type as the bare projection it wraps.
+ */
+type SelectOf<B> = B extends SelectBuilder<infer _T, infer S> ? S : B extends RelationBuilder<infer _RT, infer RS> ? RS : never;
+
+type Scalar = string | number | boolean | bigint | symbol | null | undefined | Date | Uint8Array | Set<any>;
+/**
+ * Derives the select specification type from an Entity type.
+ *
+ * - Scalar fields → `true`
+ * - Embedded objects (non-DDBModel) → nested `SelectableOf<E>`
+ * - hasMany relations (`DDBModel[]`) → `RelationSelect<E>`
+ * - belongsTo/hasOne relations (`DDBModel | null`) → `RelationSelect<E>`
+ * - Function properties → excluded
+ */
+type SelectableOf<T> = {
+    [K in keyof T as T[K] extends Function ? never : K]?: T[K] extends Array<infer E> ? [E] extends [DDBModel] ? RelationSpec<E> : true : NonNullable<T[K]> extends DDBModel ? null extends T[K] ? RelationSpec<NonNullable<T[K]>> : SelectableOf<T[K]> : T[K] extends Scalar ? true : SelectableOf<T[K]>;
+};
+/**
+ * What a relation field accepts in a `select`: either the plain
+ * {@link RelationSelect} object, or a {@link RelationBuilder} produced by the
+ * target model's `Model.relation(...)`. The model-bound builder pins the
+ * relation's target type, so passing another model's builder here is a compile
+ * error (closes #33).
+ */
+type RelationSpec<T> = RelationSelect<T> | RelationBuilder<T, any>;
+/**
+ * Plain-object selection spec for a Relation field. Wraps `SelectableOf<T>`
+ * with pagination controls and an optional declarative server-side `filter`
+ * (typed against the full relation target `T`, so it may reference attributes
+ * not in the projection).
+ *
+ * For arbitrary post-load TypeScript filtering, narrow as far as possible with
+ * the declarative server-side `filter`, then apply any remaining JS-only
+ * condition on the (already fully typed) result with `result.items.filter(...)`.
+ *
+ * @typeParam T - The target relation Entity type
+ * @typeParam S - The select specification for this relation (inferred per call)
+ */
+type RelationSelect<T, S extends SelectableOf<T> = SelectableOf<T>> = {
+    select: S;
+    limit?: number;
+    after?: string;
+    order?: 'ASC' | 'DESC';
+    filter?: FilterInput<T>;
+};
+/**
+ * Strict ("exact") version of a select projection that rejects excess
+ * properties.
+ *
+ * # Why this exists
+ *
+ * `query` / `list` infer the projection as a free generic parameter
+ * (`<Sel extends SelectSpec<T>>`, `select: Sel`). When an object literal is
+ * matched against a *bare type parameter* TypeScript infers `Sel` to the
+ * literal's exact shape and then only checks the constraint
+ * `Sel extends SelectSpec<T>` **structurally** — there is no object-literal
+ * *freshness* (excess-property) check against a concrete target, because the
+ * target (`Sel`) is whatever the literal is. `SelectableOf<T>` has all-optional
+ * properties, so an extra key like `BOGUS: true` satisfies the constraint and
+ * compiles. The `SelectableOf<T> | SelectBuilder<…>` union compounds this
+ * (freshness checks are also suppressed against unions).
+ *
+ * `StrictSelect` closes the hole without `any`: it maps every key of the
+ * inferred `Sel` that is **not** a known key of `SelectableOf<T>` to `never`.
+ * Used as an *additional* constraint at the call site
+ * (`select: Sel & StrictSelect<T, Sel>`), a stray key forces that property's
+ * type to `never`, which the supplied `true` (or nested object) is not
+ * assignable to — so the call is a compile error. Known keys keep their
+ * inferred value type, so the result-type inference (`QueryResult`) and the
+ * builder branch are unaffected.
+ *
+ * Recurses into the plain-object nested forms so the same rejection applies to
+ * nested **relation** selects (`{ select: { … } }`) and **embedded** object
+ * selects. Builder values (`RelationBuilder` / `SelectBuilder`) are left as-is —
+ * their projection was already constrained to `SelectableOf<T>` when the
+ * `Model.relation(...)` / `Model.project(...)` factory produced them.
+ *
+ * @typeParam T   - The Entity type the projection is taken against.
+ * @typeParam Sel - The inferred select object (per call).
+ */
+type StrictSelect<T, Sel> = {
+    [K in keyof Sel]: K extends keyof SelectableOf<T> ? Sel[K] extends {
+        select: infer Nested;
+    } ? K extends keyof T ? Sel[K] & {
+        select: StrictSelect<RelationTargetOf<T[K]>, Nested>;
+    } : Sel[K] : Sel[K] extends object ? Sel[K] extends RelationBuilder<infer _RT, infer _RS> ? Sel[K] : K extends keyof T ? Sel[K] & StrictSelect<NonNullable<T[K]>, Sel[K]> : Sel[K] : Sel[K] : never;
+};
+/**
+ * Extracts the relation **target entity type** from an entity field type:
+ * `E[]` → `E`, `E | null` → `E`. Mirrors the helper in `select-builder.ts`;
+ * used by {@link StrictSelect} to recurse a nested relation select against the
+ * related model's fields.
+ */
+type RelationTargetOf<F> = F extends Array<infer E> ? E : NonNullable<F> extends DDBModel ? NonNullable<F> : NonNullable<F>;
+/**
+ * Call-site excess-property constraint for a top-level `select` (which may be a
+ * plain projection **or** a `Model.project(...)` builder).
+ *
+ * - If `Sel` is a {@link SelectBuilder}, it passes through untouched — the
+ *   builder's projection was already constrained to `SelectableOf<T>` by the
+ *   `Model.project(...)` factory, and applying {@link StrictSelect} would
+ *   wrongly poison the builder's own `filter` member.
+ * - Otherwise `Sel` is a plain object and {@link StrictSelect} rejects any key
+ *   not declared on `T` (top-level and nested).
+ *
+ * Applied as `select: Sel & StrictSelectSpec<T, Sel>`, so known keys keep their
+ * inferred type (result inference unaffected) and stray keys become `never`.
+ *
+ * @typeParam T   - The Entity type the projection is taken against.
+ * @typeParam Sel - The inferred select spec (per call).
+ */
+type StrictSelectSpec<T, Sel> = Sel extends SelectBuilder<any, any> ? Sel : StrictSelect<T, Sel>;
+/**
+ * Derives the persistable input type for `put()` from an Entity type.
+ *
+ * - Function properties → excluded
+ * - Relation fields (`DDBModel[]`, `DDBModel | null`) → excluded
+ *   (relations are not written by `put`)
+ * - Scalar fields → kept with their declared type
+ * - Embedded objects (non-`DDBModel`) → recursively `EntityInput`
+ */
+type EntityInput<T> = {
+    [K in keyof T as T[K] extends Function ? never : T[K] extends Array<infer E> ? [E] extends [DDBModel] ? never : K : NonNullable<T[K]> extends DDBModel ? null extends T[K] ? never : K : K]: T[K] extends Scalar ? T[K] : NonNullable<T[K]> extends DDBModel ? EntityInput<NonNullable<T[K]>> : T[K] extends object ? EntityInput<T[K]> : T[K];
+};
+
+/**
+ * Derives the return type from an Entity type `T` and a select specification `S`.
+ *
+ * - `S[K] === true` → `T[K]` (scalar value)
+ * - `S[K]` has `select` property and `T[K]` is an array (hasMany) →
+ *   `{ items: QueryResult<E, Sel>[]; cursor: string | null }`
+ * - `S[K]` has `select` property and `T[K]` is nullable (belongsTo/hasOne) →
+ *   `QueryResult<E, Sel> | null`
+ * - `S[K]` is a plain object → nested `QueryResult` (embedded)
+ * - fallback → `T[K]` (for dynamic/widened select types)
+ *
+ * Distributes over union types in `S` so that dynamically constructed
+ * selects produce a union of result types.
+ */
+
+type QueryResult<T, S> = S extends unknown ? {
+    [K in keyof S & keyof T]: S[K] extends true ? T[K] : S[K] extends RelationBuilder<infer _RT, infer Sel> ? T[K] extends Array<infer E> ? {
+        items: QueryResult<E, Sel>[];
+        cursor: string | null;
+    } : QueryResult<NonNullable<T[K]>, Sel> | null : S[K] extends {
+        select: infer Sel;
+    } ? T[K] extends Array<infer E> ? {
+        items: QueryResult<E, Sel>[];
+        cursor: string | null;
+    } : QueryResult<NonNullable<T[K]>, Sel> | null : S[K] extends Record<string, unknown> ? QueryResult<T[K], S[K]> : T[K];
+} : never;
+
+/**
+ * Compile-time brand for read results that carry a hidden, resolved base-table
+ * key (issue #54). A `query(..., { updatable: true })` / `list(..., { updatable:
+ * true })` result is typed `QueryResult<...> & Updatable` so it can be passed
+ * straight back to `update()`.
+ *
+ * The brand is phantom (no runtime field). Spreading / cloning / JSON
+ * round-tripping a branded value produces a plain object that no longer
+ * structurally matches `Updatable`, so the compiler rejects passing a
+ * stripped copy where an updatable entity is required. (Runtime existence of
+ * the hidden key is enforced separately by `update()`, which throws when it is
+ * absent — see `resolveUpdateKey`.)
+ *
+ * @example
+ * ```ts
+ * const user = await User.query({ userId: 'u' }, { name: true }, { updatable: true });
+ * if (user) await User.updateItem(user, { name: 'New' }); // ok — branded
+ * // await User.updateItem({ ...user }, { name: 'New' }); // compile error — spread drops the brand
+ * ```
+ */
+declare const updatableBrand: unique symbol;
+interface Updatable {
+    readonly [updatableBrand]: true;
+}
+
+declare const GSI_MARKER: unique symbol;
+interface GsiDefinitionMarker<T extends Record<string, unknown> = Record<string, unknown>, U extends boolean = boolean> {
+    readonly [GSI_MARKER]: true;
+    readonly indexName: string;
+    readonly segmented: SegmentedKey;
+    readonly inputFieldNames: string[];
+    readonly unique: U;
+    /** @internal Phantom field for type-level input type extraction. */
+    readonly _phantom?: T;
+}
+interface GsiOptions {
+    unique?: boolean;
+}
+type GsiBuilder<T extends Record<string, unknown>> = (c: {
+    readonly [K in keyof T]-?: Column<T[K], T>;
+}) => KeyStructure;
+declare function gsi<T extends Record<string, unknown>>(indexName: string, builder: GsiBuilder<T>, options: GsiOptions & {
+    unique: true;
+}): GsiDefinitionMarker<T, true>;
+declare function gsi<T extends Record<string, unknown>>(indexName: string, builder: GsiBuilder<T>, options?: GsiOptions): GsiDefinitionMarker<T, false>;
+
+/**
+ * Extracts the Primary Key input type from a model class.
+ * Scans static properties for `KeyDefinitionMarker<T>` and returns `T`.
+ *
+ * @typeParam C - The model class constructor (`typeof UserModel`)
+ */
+type PrimaryKeyOf<C> = {
+    [K in keyof C]: C[K] extends KeyDefinitionMarker<infer I> ? I : never;
+}[keyof C];
+/**
+ * Union of all query key input types (PK + all GSIs).
+ * Used as the constraint for `list()`.
+ *
+ * @typeParam C - The model class constructor (`typeof UserModel`)
+ */
+type QueryKeyOf<C> = {
+    [K in keyof C]: C[K] extends KeyDefinitionMarker<infer I> ? I : C[K] extends GsiDefinitionMarker<infer I, any> ? I : never;
+}[keyof C];
+/**
+ * Union of unique query key input types (PK + unique GSIs only).
+ * Used as the constraint for `query()` — only keys guaranteed to
+ * return a single item are allowed.
+ *
+ * @typeParam C - The model class constructor (`typeof UserModel`)
+ */
+type UniqueQueryKeyOf<C> = {
+    [K in keyof C]: C[K] extends KeyDefinitionMarker<infer I> ? I : C[K] extends GsiDefinitionMarker<infer I, true> ? I : never;
+}[keyof C];
+/**
+ * "At least one" relaxation of a single key input type `T`: every field is
+ * known and correctly typed, but only a non-empty subset need be supplied (the
+ * remaining fields become optional).
+ *
+ * For a composite key `{ groupId: string; userId: string }` this yields
+ * `{ groupId: string; userId?: string } | { groupId?: string; userId: string }`
+ * — i.e. you may supply just the partition-key field(s) without the full
+ * sort-key tail. Unknown fields are still rejected (object-literal excess
+ * property checking), so it stays strictly typed.
+ */
+type AtLeastOneKey<T> = {
+    [K in keyof T]-?: {
+        [P in K]-?: T[P];
+    } & {
+        [P in Exclude<keyof T, K>]?: T[P];
+    } extends infer O ? {
+        [P in keyof O]: O[P];
+    } : never;
+}[keyof T];
+/**
+ * Key type accepted by `list()` / `explain()`. These issue a DynamoDB *Query*
+ * against a partition (PK or GSI), so a **partial** key — the partition-key
+ * subset of a PK/GSI input — is sufficient; the sort-key portion is optional
+ * (it narrows the range, e.g. `begins_with`). This mirrors the runtime key
+ * resolver, which accepts any field subset that produces a valid partition key
+ * (`src/planner/key-resolver.ts`) and throws otherwise.
+ *
+ * Distinct from {@link QueryKeyOf} (full key, used as the constraint label by
+ * the type tests) and {@link UniqueQueryKeyOf} (full unique key for `query()`,
+ * which must resolve to a single item). `query()` deliberately stays strict —
+ * only this `list`/`explain` boundary is relaxed.
+ *
+ * @typeParam C - The model class constructor (`typeof UserModel`)
+ */
+type PartialQueryKeyOf<C> = QueryKeyOf<C> extends infer U ? U extends Record<string, unknown> ? AtLeastOneKey<U> : never : never;
+
+/**
+ * A top-level `select` may be either a plain projection (`SelectableOf<T>`) or
+ * a {@link SelectBuilder} produced by `Model.project(...)`. The builder is
+ * model-bound to `T`, so its `.filter(...)` is typed against the full entity.
+ */
+type SelectSpec<T> = SelectableOf<T> | SelectBuilder<T, any>;
+/**
+ * Resolves the projection `S` from a top-level select spec (plain object or
+ * builder), so the result type is computed identically for both forms.
+ */
+type ProjectionOf<T, Sel> = Sel extends SelectableOf<T> ? Sel : SelectOf<Sel>;
+/**
+ * Default model-class constraint used when a `ModelStatic` is referenced
+ * without its concrete constructor type (e.g. `ModelStatic<UserModel>`).
+ *
+ * In that case key/option types fall back to permissive shapes so existing
+ * usages keep compiling, while the precise inference is available when the
+ * constructor type is supplied (as it is from `DDBModel.asModel()`).
+ */
+type AnyModelClass = abstract new (...args: any[]) => DDBModel;
+/**
+ * The accepted PK / GSI key type for `list()` / `explain()`.
+ *
+ * `list`/`explain` issue a DynamoDB *Query* against a partition, so a **partial**
+ * key (partition-key subset of a PK/GSI input) is accepted — the sort-key tail
+ * is optional. This matches the runtime key resolver. `query()` stays strict via
+ * {@link QueryKey}. Derived from the model class when available, otherwise
+ * permissive.
+ */
+type ListKey<C> = [C] extends [AnyModelClass] ? PartialQueryKeyOf<C> : Record<string, unknown>;
+/**
+ * The accepted key type for `query()` — only keys guaranteed to return a
+ * single item (PK + unique GSIs). Derived from the model class when available.
+ */
+type QueryKey<C> = [C] extends [AnyModelClass] ? UniqueQueryKeyOf<C> : Record<string, unknown>;
+/**
+ * The accepted key type for `delete()` (PK only). Derived from the model
+ * class when available.
+ */
+type DeleteKey<C> = [C] extends [AnyModelClass] ? PrimaryKeyOf<C> : Record<string, unknown>;
+/**
+ * The accepted *explicit* key type for `update()` — the base-table primary key
+ * only. DynamoDB `UpdateItem` can target an item solely by its base-table PK
+ * (GSI-based updates are impossible), so this is `PrimaryKeyOf<C>`, not
+ * `UniqueQueryKeyOf<C>`. Derived from the model class when available.
+ */
+type UpdateExplicitKey<C> = [C] extends [AnyModelClass] ? PrimaryKeyOf<C> : Record<string, unknown>;
+/**
+ * Options accepted by `list()` (third argument). The projection is supplied as
+ * the separate second `select` argument, symmetric with `query()`.
+ *
+ * - `filter` is the declarative server-side DynamoDB FilterExpression, typed
+ *   against the full Entity `T` (may reference unprojected attributes). For
+ *   arbitrary JS-only post-load filtering, narrow with `filter` then apply
+ *   `result.items.filter(...)` (already fully typed).
+ *
+ * @typeParam T - The Entity type.
+ */
+type ListCallOptions<T> = {
+    limit?: number;
+    after?: string;
+    order?: 'ASC' | 'DESC';
+    filter?: FilterInput<T>;
+    /**
+     * When `true`, each returned item is updatable: it carries its resolved
+     * base-table key as a hidden, non-enumerable property and is branded
+     * `& Updatable`, so it can be passed straight back to `updateItem()`.
+     */
+    updatable?: boolean;
+};
+/**
+ * Public, type-inferring API surface produced by {@link DDBModel.asModel}.
+ *
+ * @typeParam T - The Entity type of the model.
+ * @typeParam C - The model class constructor type. Supplied automatically by
+ *   `asModel()`; when omitted, key/option types widen to permissive shapes so
+ *   that `ModelStatic<T>` keeps compiling for callers that only name the entity.
+ */
+interface ModelStatic<T extends DDBModel, C = unknown> {
+    /**
+     * Type-safe column references for this model, one per scalar field. Used by
+     * the `cond` raw escape hatch (`cond\`${Model.col.age} > ${18}\``). Each
+     * column carries its declared type and is branded to this model, so passing
+     * another model's column into this model's `cond` is a compile error.
+     */
+    readonly col: ColumnMap<T>;
+    /**
+     * Begin a model-bound, top-level select builder. The entity type `T` is fixed
+     * by this model and the projection `S` is inferred from the argument.
+     * `.filter(...)` is typed `FilterInput<T>` against the full entity.
+     *
+     * @example
+     * ```ts
+     * Order.list({ userId: 'u' },
+     *   Order.project({ orderId: true, amount: true })
+     *     .filter({ status: 'confirmed', amount: { gt: 100 } }),
+     * );
+     * ```
+     */
+    project<const S extends SelectableOf<T>>(select: S): SelectBuilder<T, S>;
+    /**
+     * Begin a model-bound relation select builder for use as a relation field's
+     * value inside a parent `select`. `T` is this (relation target) model's
+     * entity type; `S` is inferred from the argument. Same model-bound inference
+     * as {@link ModelStatic.project}, plus per-relation pagination
+     * (`limit` / `after` / `order`).
+     *
+     * @example
+     * ```ts
+     * User.query({ userId: 'u' }, {
+     *   name: true,
+     *   orders: Order.relation({ orderId: true, amount: true })
+     *     .filter({ amount: { gt: 100 } }),
+     * });
+     * ```
+     */
+    relation<const S extends SelectableOf<T>>(select: S): RelationBuilder<T, S>;
+    /**
+     * Fetch a single item by a unique key and **hydrate** the plain result onto a
+     * host-side object (issue #53). The `hydrate` factory receives the fully-built
+     * plain object — `QueryResult<T, ProjectionOf<T, Sel>>`, typed against exactly
+     * the `select`ed fields — and its return type `R` becomes the read's return
+     * type (subsuming a `queryAs(Ctor, …)` style: `hydrate: (raw) => new Ctor(raw)`).
+     *
+     * Applied as the **final after-fetch step**, only to a present item: a missing
+     * item resolves to `null` and the factory is NOT invoked (hence `R | null`). A
+     * throw from the factory propagates verbatim as the read's rejection.
+     *
+     * Host-runtime ONLY: the factory is a host-language closure, never serialized
+     * into the SSoT / `operations.json`, so it does not impede the bridge (#48).
+     */
+    query<Sel extends SelectSpec<T>, R>(key: QueryKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options: {
+        consistentRead?: boolean;
+        maxDepth?: number;
+        updatable?: boolean;
+        hydrate: (raw: QueryResult<T, ProjectionOf<T, Sel>>) => R;
+    }): Promise<R | null>;
+    /**
+     * Fetch a single item by a unique key, requesting an **updatable** result.
+     * The returned item (when non-null) carries its resolved base-table key as a
+     * hidden, non-enumerable property and is branded `& Updatable`, so it can be
+     * passed straight back to {@link ModelStatic.updateItem} — even for a partial
+     * `select` or a GSI-based query. Do not spread / clone / JSON round-trip the
+     * result before updating: that drops both the hidden key and the brand.
+     */
+    query<Sel extends SelectSpec<T>>(key: QueryKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options: {
+        consistentRead?: boolean;
+        maxDepth?: number;
+        updatable: true;
+    }): Promise<(QueryResult<T, ProjectionOf<T, Sel>> & Updatable) | null>;
+    /**
+     * Fetch a single item by a unique key. The return type contains only the
+     * selected fields, derived from `select`.
+     */
+    query<Sel extends SelectSpec<T>>(key: QueryKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options?: {
+        consistentRead?: boolean;
+        maxDepth?: number;
+        updatable?: false;
+    }): Promise<QueryResult<T, ProjectionOf<T, Sel>> | null>;
+    /**
+     * List items for a partition, symmetric with {@link ModelStatic.query}:
+     * `list(key, select, options?)`. `select` (the second argument) may be a plain
+     * projection or a `project(...)` builder. `options.filter` is the declarative
+     * server-side FilterExpression typed against the full Entity. Returned items
+     * contain only the selected fields.
+     */
+    list<Sel extends SelectSpec<T>>(key: ListKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options: ListCallOptions<T> & {
+        updatable: true;
+    }): Promise<{
+        items: (QueryResult<T, ProjectionOf<T, Sel>> & Updatable)[];
+        cursor: string | null;
+    }>;
+    list<Sel extends SelectSpec<T>>(key: ListKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options?: ListCallOptions<T>): Promise<{
+        items: QueryResult<T, ProjectionOf<T, Sel>>[];
+        cursor: string | null;
+    }>;
+    explain<Sel extends SelectSpec<T>>(key: ListKey<C>, options?: {
+        select?: Sel & StrictSelectSpec<T, Sel>;
+        limit?: number;
+        after?: string;
+        order?: 'ASC' | 'DESC';
+        consistentRead?: boolean;
+        filter?: FilterInput<T>;
+    }): ExecutionPlan;
+    putItem(item: EntityInput<T>, options?: Record<string, unknown>): Promise<void>;
+    /**
+     * Update an item identified by its **explicit base-table primary key**
+     * (`PrimaryKeyOf<C>`). This is the canonical form — it requires the key input
+     * up front, so it can never silently target the wrong item.
+     *
+     * @example `await User.updateItem({ userId: 'alice' }, { status: 'disabled' });`
+     */
+    updateItem(key: UpdateExplicitKey<C>, changes: Partial<T>, options?: Record<string, unknown>): Promise<void>;
+    /**
+     * Update an item using an **updatable** entity obtained from
+     * `query(..., { updatable: true })` / `list(..., { updatable: true })`. The
+     * hidden base-table key carried by that entity is used directly, so this
+     * works even for a partial `select` or a GSI-based read.
+     *
+     * Pass the entity as-is. A spread / clone / JSON round-trip drops both the
+     * brand (rejected here at compile time) and the hidden key (rejected at
+     * runtime), preventing an accidental wrong-item update.
+     */
+    updateItem(entity: Partial<T> & Updatable, changes: Partial<T>, options?: Record<string, unknown>): Promise<void>;
+    deleteItem(key: DeleteKey<C>, options?: Record<string, unknown>): Promise<void>;
+}
+
+interface PutOptions {
+    condition?: Record<string, unknown>;
+}
+interface UpdateOptions {
+    condition?: Record<string, unknown>;
+}
+interface DeleteOptions {
+    condition?: Record<string, unknown>;
+}
+
+interface PutInput {
+    TableName: string;
+    Item: Record<string, unknown>;
+    ConditionExpression?: string;
+    ExpressionAttributeNames?: Record<string, string>;
+    ExpressionAttributeValues?: Record<string, unknown>;
+}
+declare function buildPutInput(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): PutInput;
+declare function executePut(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): Promise<void>;
+
+interface UpdateInput {
+    TableName: string;
+    Key: Record<string, unknown>;
+    UpdateExpression: string;
+    ExpressionAttributeNames: Record<string, string>;
+    ExpressionAttributeValues?: Record<string, unknown>;
+    ConditionExpression?: string;
+}
+declare function buildUpdateInput(modelClass: Function, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): UpdateInput;
+declare function executeUpdate(modelClass: Function, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): Promise<void>;
+
+interface DeleteInput {
+    TableName: string;
+    Key: Record<string, unknown>;
+    ConditionExpression?: string;
+    ExpressionAttributeNames?: Record<string, string>;
+    ExpressionAttributeValues?: Record<string, unknown>;
+}
+declare function buildDeleteInput(modelClass: Function, keyObj: Record<string, unknown>, options?: DeleteOptions): DeleteInput;
+declare function executeDelete(modelClass: Function, keyObj: Record<string, unknown>, options?: DeleteOptions): Promise<void>;
+
+/** Result of a read operation (GetItem / Query / BatchGetItem). */
+interface ExecutorResult {
+    items: Record<string, unknown>[];
+    lastEvaluatedKey?: Record<string, unknown>;
+}
+/**
+ * Result of a single structured write. `oldItem` is the pre-write image,
+ * present only when the caller requested it (`returnOldImage: true`, mapped to
+ * DynamoDB `ReturnValues: ALL_OLD`) and an item existed before the write. The
+ * write-capture seam (issue #72) reads it to derive INSERT vs MODIFY and the
+ * REMOVE OldImage.
+ */
+interface WriteResult {
+    oldItem?: Record<string, unknown>;
+}
+/** Options shared by the single-item structured write methods. */
+interface WriteExecOptions {
+    /** Request the pre-write image (DynamoDB `ReturnValues: ALL_OLD`). */
+    returnOldImage?: boolean;
+}
+/**
+ * One BatchGetItem sub-request: a single physical table plus its keys and an
+ * optional projection. Mirrors {@link import('../planner/types.js').BatchGetItemOperation}
+ * without the discriminant `type` field, so callers that already chunked keys
+ * (relation traversal) and the planner-driven read path share one entry point.
+ */
+interface BatchGetExecInput {
+    tableName: string;
+    keys: Record<string, unknown>[];
+    projectionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    consistentRead?: boolean;
+}
+/** A single item in a {@link Executor.batchWrite} request, grouped by table. */
+type BatchWriteExecItem = {
+    type: 'put';
+    item: Record<string, unknown>;
+} | {
+    type: 'delete';
+    key: Record<string, unknown>;
+};
+/**
+ * A read-only `ConditionCheck` entry for {@link Executor.transactWrite} (issue
+ * #81): it asserts a `ConditionExpression` holds for the keyed item without
+ * mutating it. A failed assertion cancels the **whole** `TransactWriteItems`
+ * atomically — the foundation for referential-integrity derivation.
+ */
+interface ConditionCheckInput {
+    TableName: string;
+    Key: Record<string, unknown>;
+    ConditionExpression: string;
+    ExpressionAttributeNames?: Record<string, string>;
+    ExpressionAttributeValues?: Record<string, unknown>;
+}
+/**
+ * A `{ Put | Update | Delete | ConditionCheck }` entry for
+ * {@link Executor.transactWrite}. The first three mutate an item; `ConditionCheck`
+ * (issue #81) is a read-only assertion on another item.
+ */
+type TransactWriteExecItem = {
+    Put: PutInput;
+} | {
+    Update: UpdateInput;
+} | {
+    Delete: DeleteInput;
+} | {
+    ConditionCheck: ConditionCheckInput;
+};
+/**
+ * The unified I/O seam (issue #76). All of GraphDDB's read and write I/O is
+ * funneled through one injectable executor so the engine (planner / hydrator /
+ * relation traversal / write paths) can run unchanged against either real
+ * DynamoDB ({@link DynamoExecutor}, the default) or an in-process memory store
+ * (`MemoryExecutor`, the test adapter).
+ *
+ * Reads take a structured {@link DynamoDBOperation}; writes take the structured
+ * inputs the operation layer already builds (`PutInput` / `UpdateInput` / …),
+ * never an AWS SDK command. This keeps the seam at the *structured operation
+ * boundary* (proposal option B): no expression-string parsing is required to
+ * implement a fake.
+ */
+interface Executor {
+    /** Read path: GetItem / Query / BatchGetItem. */
+    execute(operation: DynamoDBOperation): Promise<ExecutorResult>;
+    /**
+     * BatchGetItem for a single table. The caller is responsible for chunking
+     * keys ≤100 (the relation traversal and the planner-driven path both do).
+     */
+    batchGet(input: BatchGetExecInput): Promise<ExecutorResult>;
+    /** Put one item. */
+    put(input: PutInput, options?: WriteExecOptions): Promise<WriteResult>;
+    /** Update one item (applies its structured UpdateExpression). */
+    update(input: UpdateInput, options?: WriteExecOptions): Promise<WriteResult>;
+    /** Delete one item. */
+    delete(input: DeleteInput, options?: WriteExecOptions): Promise<WriteResult>;
+    /**
+     * BatchWriteItem for a single table (non-atomic). Keys/items are chunked ≤25
+     * with UnprocessedItems retry by the implementation.
+     */
+    batchWrite(tableName: string, items: BatchWriteExecItem[]): Promise<void>;
+    /** TransactWriteItems — all-or-nothing atomic. */
+    transactWrite(items: TransactWriteExecItem[]): Promise<void>;
+}
+
+type TransactWriteItemInput = {
+    Put: PutInput;
+} | {
+    Update: UpdateInput;
+} | {
+    Delete: DeleteInput;
+} | {
+    ConditionCheck: ConditionCheckInput;
+};
+declare function attachModelClass<T extends DDBModel>(modelStatic: ModelStatic<T>, modelClass: new (...args: unknown[]) => T): ModelStatic<T>;
+/**
+ * Per-item capture descriptor recorded alongside each transact item, so the
+ * write-capture seam (issue #72) can emit a labelled raw record after the
+ * transaction commits. `TransactWriteItems` returns no images (spec §14), so
+ * these carry the keys + the new item for Put/Update and keys only for Delete.
+ */
+interface TransactCaptureMeta {
+    modelName?: string;
+    op: 'put' | 'update' | 'delete';
+    table: string;
+    keys: {
+        pk: string;
+        sk: string;
+    };
+    newItem?: Record<string, unknown>;
+}
+declare class TransactionContext {
+    private readonly items;
+    private readonly captureMeta;
+    get itemCount(): number;
+    put(model: ModelStatic<DDBModel>, item: Record<string, unknown>, options?: PutOptions): void;
+    update(model: ModelStatic<DDBModel>, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): void;
+    delete(model: ModelStatic<DDBModel>, key: Record<string, unknown>, options?: DeleteOptions): void;
+    /**
+     * Add a read-only `ConditionCheck` assertion on a keyed item (issue #81). The
+     * item is **not** mutated; the `options.condition` (e.g.
+     * `{ attributeExists: 'PK' }` to require the row exists) is asserted, and a
+     * failed assertion cancels the **whole** `TransactWriteItems` atomically. This
+     * is the foundation for referential-integrity derivation (proposal: `requires
+     * <Entity> exists`). A ConditionCheck emits no change-capture record (it writes
+     * nothing).
+     *
+     * @throws if `options.condition` is missing — a ConditionCheck without an
+     *   assertion is meaningless.
+     */
+    conditionCheck(model: ModelStatic<DDBModel>, key: Record<string, unknown>, options: {
+        condition: Record<string, unknown>;
+    }): void;
+    /** @internal */
+    getTransactItems(): TransactWriteItemInput[];
+    /** @internal — capture descriptors for the write-capture seam (issue #72). */
+    getCaptureMeta(): TransactCaptureMeta[];
+    private assertWithinLimit;
+}
+declare function executeTransaction(fn: (tx: TransactionContext) => void | Promise<void>): Promise<void>;
+
+interface BatchGetRequest {
+    model: ModelStatic<DDBModel>;
+    keys: Record<string, unknown>[];
+}
+interface BatchPutRequest {
+    type: 'put';
+    model: ModelStatic<DDBModel>;
+    item: Record<string, unknown>;
+    options?: PutOptions;
+}
+interface BatchDeleteRequest {
+    type: 'delete';
+    model: ModelStatic<DDBModel>;
+    key: Record<string, unknown>;
+    options?: DeleteOptions;
+}
+type BatchWriteRequest = BatchPutRequest | BatchDeleteRequest;
+declare class BatchGetResult {
+    private readonly groups;
+    constructor(groups: Map<Function, Record<string, unknown>[]>);
+    get<T extends DDBModel>(model: ModelStatic<T>): Partial<T>[];
+}
+declare function executeBatchGet(requests: BatchGetRequest[]): Promise<BatchGetResult>;
+declare function executeBatchWrite(requests: BatchWriteRequest[]): Promise<void>;
+
+/**
+ * Parameter placeholders for the parameterized query / command definition DSL
+ * (issue #41, Python-bridge Phase 0a).
+ *
+ * A `Param<T>` is a **branded placeholder** standing in for a value that is not
+ * known at definition time but is supplied later (at execution, e.g. from
+ * Python). It carries:
+ *
+ * - the **TypeScript value type** `T` it represents (`string`, `number`, or a
+ *   string-literal union), preserved through the IR and the inferred return
+ *   types of `defineQueries` / `defineCommands`; and
+ * - a **runtime descriptor** (`kind` + optional `literals`) that the static
+ *   planner (#42) and the code generator read to emit `operations.json`.
+ *
+ * Placeholders are created with `param.string()`, `param.number()`, and
+ * `param.literal(...)`. They are *only* legal at value positions inside a
+ * parameterized key / changes structure passed to the `define*` entry points —
+ * never to the live `Model.query` / `Model.putItem` runtime API, whose types remain
+ * uncontaminated by params.
+ */
+/** Brand tag preventing a plain object from structurally matching a {@link Param}. */
+declare const PARAM_BRAND: unique symbol;
+/** Runtime discriminant for a parameter placeholder. */
+type ParamKind = 'string' | 'number' | 'literal' | 'array';
+/**
+ * A branded parameter placeholder representing a value of TypeScript type `T`
+ * that is bound at execution time rather than definition time.
+ *
+ * The brand (`[PARAM_BRAND]: T`) keeps `Param<string>` and `Param<number>`
+ * distinct and prevents a bare value from being mistaken for a placeholder.
+ *
+ * @typeParam T - The value type this placeholder stands in for.
+ */
+interface Param<out T> {
+    /** @internal Type brand carrying the represented value type. */
+    readonly [PARAM_BRAND]: T;
+    /** Runtime discriminant: `'string'` | `'number'` | `'literal'` | `'array'`. */
+    readonly kind: ParamKind;
+    /**
+     * For `param.literal(...)`, the allowed literal values (preserved at runtime
+     * for the generator). `undefined` for `string` / `number`.
+     */
+    readonly literals?: readonly T[];
+    /**
+     * For `param.array({...})`, the descriptor of each element's fields. Lets the
+     * transaction planner (#46) type `forEach` element references and emit the
+     * `{item.<field>}` templates. `undefined` for scalar params.
+     */
+    readonly element?: Readonly<Record<string, Param<unknown>>>;
+}
+/** A `Param` whose represented value type is `string`. */
+type StringParam = Param<string>;
+/** A `Param` whose represented value type is `number`. */
+type NumberParam = Param<number>;
+/** A `Param` whose represented value type is the literal union `L`. */
+type LiteralParam<L extends string | number> = Param<L>;
+/** The element-field descriptor shape accepted by {@link param.array}. */
+type ArrayElementShape = Record<string, Param<unknown>>;
+/**
+ * The TypeScript element type implied by an {@link ArrayElementShape} `E`: each
+ * field carries the value type its placeholder represents.
+ */
+type ElementOf<E extends ArrayElementShape> = {
+    [K in keyof E]: E[K] extends Param<infer V> ? V : never;
+};
+/** A `Param` standing in for an **array** whose elements have shape `E`. */
+type ArrayParam<E extends ArrayElementShape> = Param<ElementOf<E>[]> & {
+    readonly element: E;
+};
+/** Allowed scalar value types a placeholder may stand in for. */
+type ParamValue = string | number;
+/**
+ * Placeholder factory. Each call returns a branded {@link Param} carrying both
+ * the TypeScript value type and a runtime descriptor.
+ */
+declare const param: {
+    /** A placeholder for a `string` value. */
+    readonly string: () => StringParam;
+    /** A placeholder for a `number` value. */
+    readonly number: () => NumberParam;
+    /**
+     * A placeholder constrained to one of the given literal values. The value
+     * type of the resulting {@link Param} is the **union of the literals**, so it
+     * is preserved precisely in the IR and the inferred definition types.
+     *
+     * @example
+     * ```ts
+     * param.literal('active', 'disabled'); // Param<'active' | 'disabled'>
+     * ```
+     */
+    readonly literal: <const L extends readonly [ParamValue, ...ParamValue[]]>(...values: L) => LiteralParam<L[number]>;
+    /**
+     * A placeholder for an **array** parameter whose elements have the given field
+     * shape. Used by `defineTransaction`'s `tx.forEach(p.<arrayParam>, …)` to bind
+     * each element's fields to `{item.<field>}` templates.
+     *
+     * @example
+     * ```ts
+     * param.array({ userId: param.string(), role: param.string() });
+     * // Param<{ userId: string; role: string }[]>
+     * ```
+     */
+    readonly array: <const E extends ArrayElementShape>(element: E) => ArrayParam<E>;
+};
+/** Runtime type guard: is `value` a parameter placeholder? */
+declare function isParam(value: unknown): value is Param<unknown>;
+
+/**
+ * Intermediate representation (IR) produced by the parameterized definition DSL
+ * (issue #41). This is the **in-memory, typed** representation consumed by the
+ * static planner (#42); JSON serialization is #42's responsibility, so nothing
+ * here is serialized — the IR keeps full type information (param value types,
+ * select projection) so downstream type derivation stays sound.
+ *
+ * Each `define*` entry point captures, for one definition:
+ *
+ * - `entity`   — the model name + (runtime) class the operation targets;
+ * - `operation`— the operation kind (`query` | `list` | `put` | `update`
+ *   | `delete`);
+ * - the operation **structure** with {@link Param} placeholders left in place
+ *   (`key` / `item` / `changes`, plus `select` for reads); and
+ * - `params`   — a `name → descriptor` map collected from every placeholder in
+ *   the structure, with the descriptor preserving the param's value type.
+ */
+
+/** The set of operation kinds a definition may describe. */
+type OperationKind = 'query' | 'list' | 'put' | 'update' | 'delete';
+/**
+ * A declarative write condition for a parameterized command definition (issues
+ * #46, #81). Mirrors the runtime `condition` subset
+ * (`expression/condition-expression.ts`):
+ *
+ * - `{ notExists: true }` → `attribute_not_exists(PK)` (the row must not exist).
+ *   This legacy whole-row form is kept verbatim for backward compatibility.
+ * - `{ attributeExists: '<field>' }` → `attribute_exists(<field>)` — the named
+ *   attribute (any field, including PK / SK) must be present. The foundation for
+ *   referential-integrity derivation (proposal "capability gaps": `requires X
+ *   exists`).
+ * - `{ attributeNotExists: '<field>' }` → `attribute_not_exists(<field>)` — the
+ *   named attribute must be absent (a field-level uniqueness / first-write guard).
+ * - `{ field: value, … }` → field equality (`#f = :v AND …`). Each value may be
+ *   a concrete literal **or** a {@link Param} placeholder (bound at execution).
+ *
+ * The forms are mutually exclusive: `notExists` / `attributeExists` /
+ * `attributeNotExists` are single-primitive conditions and ignore any sibling
+ * fields. (When more than one would be present the most specific is taken in the
+ * order `notExists` → `attributeExists` → `attributeNotExists`.)
+ */
+type ConditionInput = {
+    readonly notExists: true;
+} | {
+    readonly attributeExists: string;
+} | {
+    readonly attributeNotExists: string;
+} | Readonly<Record<string, Param<unknown> | string | number | boolean>>;
+/** Options accepted by the write `define*` entry points (issue #46). */
+interface WriteDefinitionOptions {
+    /** Optional declarative write condition (subset). */
+    readonly condition?: ConditionInput;
+}
+/**
+ * Identifies the entity an operation targets. `name` is the model class name
+ * (entity name); `modelClass` is retained so the planner can resolve metadata
+ * (keys / GSIs / fields) from the `MetadataRegistry`.
+ */
+interface EntityRef {
+    readonly name: string;
+    readonly modelClass: Function;
+}
+/**
+ * A single parameter descriptor in an operation's `params` map. Carries the
+ * runtime `kind` (and, for `literal`, the allowed values) and — purely at the
+ * type level — the represented value type `T`.
+ *
+ * @typeParam T - The value type the parameter stands in for.
+ */
+interface ParamDescriptor<T = unknown> {
+    readonly kind: ParamKind;
+    readonly literals?: readonly T[];
+    /**
+     * For an `array` param (transaction `forEach` source), the per-element field
+     * descriptors. `undefined` for scalar params.
+     */
+    readonly element?: Readonly<Record<string, ParamDescriptor>>;
+    /** Parameters are always required (no optional params in this phase). */
+    readonly required: true;
+}
+/**
+ * Structure with {@link Param} placeholders left intact (key / item / changes).
+ * A recursive record whose leaves are either concrete scalar literals (e.g. a
+ * fixed sort-key discriminator) or `Param<…>` placeholders.
+ */
+type ParamStructure = {
+    readonly [key: string]: ParamStructure | Param<unknown> | string | number | boolean;
+};
+/**
+ * The typed IR for one definition. Generic over the entity, the parameterized
+ * structure(s), the (optional) select projection, and the collected params map
+ * so that all type information survives into the value returned by
+ * `defineQueries` / `defineCommands`.
+ *
+ * Field presence by `operation`:
+ *
+ * | op       | key | select | changes | params |
+ * |----------|-----|--------|---------|--------|
+ * | query    | ✓   | ✓      | —       | ✓      |
+ * | list     | ✓   | ✓      | —       | ✓      |
+ * | put      | item (in `key`) | — | — | ✓ |
+ * | update   | ✓   | —      | ✓       | ✓      |
+ * | delete   | ✓   | —      | —       | ✓      |
+ *
+ * @typeParam T  - The entity type.
+ * @typeParam Op - The operation kind.
+ * @typeParam K  - The parameterized key / item structure.
+ * @typeParam S  - The select projection (reads only; `undefined` for writes).
+ * @typeParam Ch - The parameterized changes structure (`update` only).
+ * @typeParam P  - The collected `name → ParamDescriptor` map.
+ */
+interface OperationDefinition<T extends DDBModel, Op extends OperationKind, K, S, Ch, P extends Record<string, ParamDescriptor>> {
+    /** @internal Marks this object as a definition IR node. */
+    readonly __isOperationDefinition: true;
+    readonly entity: EntityRef;
+    readonly operation: Op;
+    /**
+     * The parameterized key for `query` / `list` / `update` / `delete`, or the
+     * parameterized item for `put`. Placeholders are preserved in place.
+     */
+    readonly key: K;
+    /** The select projection for `query` / `list`; `undefined` otherwise. */
+    readonly select: S;
+    /** The parameterized changes for `update`; `undefined` otherwise. */
+    readonly changes: Ch;
+    /**
+     * The declarative write condition for `put` / `update` / `delete`; `undefined`
+     * when no condition is attached or for reads (issue #46).
+     */
+    readonly condition?: ConditionInput;
+    /** Collected parameters: name → descriptor (value type preserved in `P`). */
+    readonly params: P;
+    /** @internal Phantom carrier so the entity type `T` is retained on the node. */
+    readonly __entityType?: (value: T) => void;
+}
+/** Any operation definition node, regardless of its type parameters. */
+type AnyOperationDefinition = OperationDefinition<any, OperationKind, unknown, unknown, unknown, Record<string, ParamDescriptor>>;
+/**
+ * A map of definition name → {@link OperationDefinition}, as accepted by
+ * `defineQueries` / `defineCommands` and returned (unchanged in type) from them.
+ */
+type DefinitionMap = Record<string, AnyOperationDefinition>;
+
+/**
+ * Model write-semantics — the reusable *save contract* `entityWrites` (issue #83,
+ * Epic #80; spec `docs/mutation-command-derivation.md` §2).
+ *
+ * `Model.writes` declares the **write-side invariants / effects required for this
+ * entity to be consistent on DynamoDB** — a *reusable save contract*, NOT a
+ * mutation and NOT business logic. It is a per-lifecycle map
+ * (`{ create?, update?, remove? }`) whose values are {@link LifecycleContract}s
+ * built with `w.lifecycle({...})`; each carries the §2 effect arrays
+ * (`requires` / `unique` / `edges` / `derive` / `emits` / `idempotency`).
+ *
+ * ## What #83 does — and deliberately does NOT — with the effects
+ *
+ * The mutation compiler (#83) resolves a fragment's lifecycle from this save
+ * contract (the fragment's intent — `m.create` / `m.update` / `m.remove` — picks
+ * `create` / `update` / `remove`) and emits the **base write op** for that
+ * lifecycle (create → `PutItem` with `attribute_not_exists(PK)`, update →
+ * `UpdateItem`, remove → `DeleteItem`). The §2 effect arrays are **stored
+ * opaquely** here and consumed by NONE of #83: deriving `ConditionCheck`
+ * (requires, #84), uniqueness guards (#86), adjacency edge `Put` / `Delete` from
+ * `edges` (#85), derived counter `UpdateItem`s (#85), outbox events (#87), and
+ * the idempotency guard (#87) are each their own follow-up issue. #83 only shapes
+ * the declaration and exposes the {@link LifecycleContract.effects} a later issue
+ * reads — the **per-fragment hook** the compiler leaves empty (see
+ * `compileFragment` in `src/spec/mutation-command.ts`).
+ *
+ * ## Coexistence with edge writes (`edgeWrites`, #82)
+ *
+ * This is a **distinct** construct from {@link edgeWrites} (#82, the adjacency
+ * edge-only `writes` member). `edgeWrites` declares *only* the edge write side of
+ * an adjacency entity; `entityWrites` is the full per-lifecycle save contract a
+ * mutation fragment adopts. Both are recognized by their own brand, so a model
+ * may carry either form on its static `writes` member without collision; the
+ * mutation compiler reads {@link getEntityWrites} (this marker), the edge
+ * derivation reads its own.
+ *
+ * ## Trivial base op when a model declares no `writes`
+ *
+ * A target model that declares **no** `entityWrites` save contract has no
+ * lifecycle to resolve; the fragment then compiles the **trivial base op** for
+ * its intent (create → `Put` `attribute_not_exists(PK)`, update → `Update`,
+ * remove → `Delete`) directly against the plain model. So
+ * `{ create: () => PostModel, key, input }` works on a bare model — see
+ * {@link resolveLifecycle} in `src/spec/mutation-command.ts`.
+ */
+/**
+ * The lifecycle phase a save contract entry declares. The mutation fragment's
+ * intent (`m.create` / `m.update` / `m.remove`) selects the matching entry.
+ */
+type WriteLifecyclePhase = 'create' | 'update' | 'remove';
+/**
+ * A path-rooted leaf value in a save-contract effect (proposal §2): every value
+ * binds to an explicit path root so its source is unambiguous —
+ * `$.input.*` (the mutation input) or `$.entity.*` (the written entity). #83
+ * stores these verbatim (it consumes none); a follow-up issue (#84–#87) reads
+ * them when deriving the effect's DynamoDB realization.
+ */
+type EffectPath = string;
+/**
+ * A referential-integrity requirement (proposal §2 `requires`): the named target
+ * entity must exist for the keys bound from `$.input.*` / `$.entity.*`. Derived
+ * to a `ConditionCheck` (`attribute_exists`) by #84 — **not** by #83, which only
+ * stores it.
+ */
+interface RequiresEffect {
+    readonly kind: 'requires';
+    /** Resolves the entity whose existence is asserted. */
+    readonly targetFactory: () => new (...args: unknown[]) => unknown;
+    /** The key binding: target key field → a path-rooted source value. */
+    readonly keys: Readonly<Record<string, EffectPath>>;
+}
+/**
+ * A uniqueness guard (proposal §2 `unique`): `{ name, scope, fields }` — a named
+ * composite-scope uniqueness invariant. Derived to a `UNIQUE#…` guard `Put` with
+ * `attribute_not_exists` by #86 — stored opaquely here.
+ */
+interface UniqueEffect {
+    readonly kind: 'unique';
+    /** The guard name (its key-shape discriminator on DynamoDB). */
+    readonly name: string;
+    /** The scope the uniqueness is partitioned by (path-rooted values). */
+    readonly scope: readonly EffectPath[];
+    /** The fields whose combined value must be unique within the scope. */
+    readonly fields: readonly EffectPath[];
+}
+/**
+ * An edge write effect (proposal §2 `edges`): create / delete the adjacency row
+ * that materializes a target relation. Derived to an adjacency `Put` / `Delete`
+ * by #82/#85 (the `src/relation/edge-write.ts` primitive) — stored opaquely here.
+ */
+interface EdgeEffect {
+    readonly kind: 'putEdge' | 'deleteEdge';
+    /** Resolves the target model whose relation this edge feeds. */
+    readonly targetFactory: () => new (...args: unknown[]) => unknown;
+    /** The relation property on the target that reads this edge. */
+    readonly relationProperty: string;
+}
+/**
+ * A derived (cascading) update (proposal §2 `derive`): e.g. `User.postCount +=
+ * 1`. Derived to an `UpdateItem` `ADD` / `SET` in the transaction by #85 —
+ * stored opaquely here.
+ */
+interface DeriveEffect {
+    readonly kind: 'derive';
+    /** Resolves the entity whose attribute is derived-updated. */
+    readonly targetFactory: () => new (...args: unknown[]) => unknown;
+    /** The key binding of the updated row (path-rooted values). */
+    readonly keys: Readonly<Record<string, EffectPath>>;
+    /** The attribute to increment / set. */
+    readonly attribute: string;
+    /** The amount to add (for an increment). */
+    readonly amount: number;
+}
+/**
+ * A domain event (proposal §2 `emits`): an outbox `Put` drained to Streams /
+ * `src/cdc/`. Derived by #87 — stored opaquely here.
+ */
+interface EmitEffect {
+    readonly kind: 'event';
+    /** The event name (e.g. `PostCreated`). */
+    readonly name: string;
+    /** The event payload, each value path-rooted. */
+    readonly payload: Readonly<Record<string, EffectPath>>;
+}
+/**
+ * An idempotency guard (proposal §2 `idempotency`): a client-token guard item
+ * (`attribute_not_exists`). Derived by #87 — stored opaquely here.
+ */
+interface IdempotencyEffect {
+    readonly kind: 'idempotency';
+    /** The path-rooted token the guard keys on (e.g. `$.input.requestId`). */
+    readonly token: EffectPath;
+}
+/**
+ * The full §2 effect set a {@link LifecycleContract} carries. Every field is
+ * optional; an omitted field is the empty effect set. #83 stores this verbatim
+ * and consumes none — the per-fragment hook a later issue (#84–#87) reads.
+ */
+interface LifecycleEffects {
+    /** Referential-integrity requirements (→ `ConditionCheck`, #84). */
+    readonly requires?: readonly RequiresEffect[];
+    /** Uniqueness guards (→ `UNIQUE#…` guard `Put`, #86). */
+    readonly unique?: readonly UniqueEffect[];
+    /** Edge write effects (→ adjacency `Put` / `Delete`, #82/#85). */
+    readonly edges?: readonly EdgeEffect[];
+    /** Derived / cascading updates (→ `UpdateItem` `ADD`/`SET`, #85). */
+    readonly derive?: readonly DeriveEffect[];
+    /** Domain events (→ outbox `Put`, #87). */
+    readonly emits?: readonly EmitEffect[];
+    /** Idempotency guard (→ client-token guard `Put`, #87). */
+    readonly idempotency?: IdempotencyEffect;
+}
+/**
+ * Marker carried by a {@link LifecycleContract} so it is recognized regardless of
+ * declaration shape. Built by {@link WriteRecorder.lifecycle}.
+ */
+declare const LIFECYCLE_CONTRACT_MARKER: unique symbol;
+/**
+ * One lifecycle's save contract — the §2 effect set for a single phase
+ * (`create` / `update` / `remove`). #83 emits the lifecycle's **base write op**
+ * (selected from the fragment intent) and leaves the {@link effects} as the
+ * untouched per-fragment hook a later issue derives.
+ */
+interface LifecycleContract {
+    readonly [LIFECYCLE_CONTRACT_MARKER]: true;
+    /** The §2 effect arrays, stored opaquely by #83. */
+    readonly effects: LifecycleEffects;
+}
+/** Runtime guard: is `value` a {@link LifecycleContract} (a `w.lifecycle(...)`)? */
+declare function isLifecycleContract(value: unknown): value is LifecycleContract;
+/**
+ * Marker carried by a model's static `writes` member when it is an
+ * {@link EntityWritesDefinition} (an `entityWrites(...)` save contract), so it is
+ * told apart from an {@link edgeWrites} member (#82) on the same conventional
+ * property name.
+ */
+declare const ENTITY_WRITES_MARKER: unique symbol;
+/**
+ * The per-lifecycle save contract produced by {@link entityWrites}: a map from
+ * {@link WriteLifecyclePhase} to its {@link LifecycleContract}. Every phase is
+ * optional — a model may declare only the lifecycles it needs (e.g. a `create` +
+ * `remove` save contract with no `update`).
+ */
+interface EntityWritesDefinition {
+    readonly [ENTITY_WRITES_MARKER]: true;
+    /** The create-lifecycle save contract, if declared. */
+    readonly create?: LifecycleContract;
+    /** The update-lifecycle save contract, if declared. */
+    readonly update?: LifecycleContract;
+    /** The remove-lifecycle save contract, if declared. */
+    readonly remove?: LifecycleContract;
+}
+/** Runtime guard: is `value` an {@link EntityWritesDefinition}? */
+declare function isEntityWritesDefinition(value: unknown): value is EntityWritesDefinition;
+/**
+ * The recorder handed to the {@link entityWrites} builder. `w.lifecycle({...})`
+ * accepts the §2 effect arrays and brands them into a {@link LifecycleContract}.
+ * #83 stores the effects opaquely; #84–#87 read them.
+ */
+interface WriteRecorder {
+    /**
+     * Build one lifecycle's save contract from its §2 effect arrays. Every effect
+     * field is optional; an omitted field is an empty effect set. The returned
+     * contract is branded so the compiler can resolve it from the model's `writes`
+     * map by lifecycle phase.
+     */
+    lifecycle(effects?: LifecycleEffects): LifecycleContract;
+    /** Declare a referential-integrity requirement (§2 `requires`; derived #84). */
+    exists(target: () => new (...args: unknown[]) => unknown, keys: Readonly<Record<string, EffectPath>>): RequiresEffect;
+    /** Declare a uniqueness guard (§2 `unique`; derived #86). */
+    unique(spec: {
+        readonly name: string;
+        readonly scope: readonly EffectPath[];
+        readonly fields: readonly EffectPath[];
+    }): UniqueEffect;
+    /** Declare an edge create effect (§2 `edges`; derived #82/#85). */
+    putEdge(target: () => new (...args: unknown[]) => unknown, relationProperty: string): EdgeEffect;
+    /** Declare an edge delete effect (§2 `edges`; derived #82/#85). */
+    deleteEdge(target: () => new (...args: unknown[]) => unknown, relationProperty: string): EdgeEffect;
+    /** Declare a derived / cascading update (§2 `derive`; derived #85). */
+    increment(target: () => new (...args: unknown[]) => unknown, keys: Readonly<Record<string, EffectPath>>, attribute: string, amount: number): DeriveEffect;
+    /** Declare a domain event (§2 `emits`; derived #87). */
+    event(name: string, payload: Readonly<Record<string, EffectPath>>): EmitEffect;
+    /** Declare an idempotency guard (§2 `idempotency`; derived #87). */
+    idempotentBy(token: EffectPath): IdempotencyEffect;
+}
+/**
+ * The lifecycle map a {@link entityWrites} builder returns: each phase is either
+ * a built {@link LifecycleContract} (`w.lifecycle({...})`) or omitted.
+ */
+interface EntityWritesShape {
+    readonly create?: LifecycleContract;
+    readonly update?: LifecycleContract;
+    readonly remove?: LifecycleContract;
+}
+/**
+ * Declare a model's reusable **save contract** (issue #83, proposal §2). The
+ * builder receives a {@link WriteRecorder} and returns the per-lifecycle map
+ * (`{ create?, update?, remove? }`), each value a `w.lifecycle({...})` carrying
+ * the §2 effect arrays. The result is stored on the model as
+ * `static readonly writes = entityWrites<Model>((w) => ({ … }))`.
+ *
+ * #83 reads only **which** lifecycles are declared (to resolve a fragment's base
+ * write op by intent) and stores the effect arrays opaquely; the effect
+ * derivation is #84–#87.
+ *
+ * @typeParam M The model type the save contract belongs to (documentary; the
+ *   recorder is structural).
+ * @example
+ * ```ts
+ * static readonly writes = entityWrites<PostModel>((w) => ({
+ *   create: w.lifecycle({
+ *     requires: [w.exists(() => UserModel, { userId: '$.input.userId' })],
+ *     edges:    [w.putEdge(() => UserModel, 'posts')],
+ *   }),
+ *   remove: w.lifecycle({ edges: [w.deleteEdge(() => UserModel, 'posts')] }),
+ * }));
+ * ```
+ */
+declare function entityWrites<M = unknown>(builder: (w: WriteRecorder) => EntityWritesShape): EntityWritesDefinition;
+/**
+ * Read the {@link EntityWritesDefinition} declared on a model class as its static
+ * `writes` member, or `undefined` when the model declares no `entityWrites` save
+ * contract. Scans the class's own static members for the {@link
+ * ENTITY_WRITES_MARKER}, exactly as {@link getEdgeWrites} (#82) scans for the
+ * edge marker — so the two `writes` forms coexist without a fixed property name
+ * collision (a model carries one or the other; the marker disambiguates).
+ */
+declare function getEntityWrites(modelClass: new (...args: unknown[]) => unknown): EntityWritesDefinition | undefined;
+/** The lifecycle phase a mutation fragment intent selects. */
+declare function lifecyclePhaseForIntent(intent: 'create' | 'update' | 'remove'): WriteLifecyclePhase;
+
+/**
+ * Internal write-plan composition DSL — `mutation` / `definePlan` (issue #83,
+ * Epic #80; spec `docs/mutation-command-derivation.md` §1, §3).
+ *
+ * A **mutation is INTERNAL** — it is *not* a public API. It is a *write-plan
+ * composition language* used as the **implementation** of a Command: it declares
+ * a set of write **fragments** that must execute atomically. The only externally
+ * exposed surface is the fixed Command IF (`publicCommandModel(...).plan(...)`,
+ * `src/define/contract.ts`); the mutation document is never exposed.
+ *
+ * The authoring form (issue #108) is a **descriptor map**: the body returns an
+ * **alias → write-descriptor** object, the declarative twin of an in-process
+ * `DDBModel.mutate(...)` call (the only difference is the values are `$.field`
+ * placeholders rather than concrete values):
+ *
+ * ```ts
+ * const JoinGroup = mutation($ => ({
+ *   membership: { create: GroupMembership, key: { groupId: $.groupId, userId: $.userId }, input: { role: $.role } },
+ *   permission: { create: () => Permission,  key: { id: $.permId }, input: { groupId: $.membership.groupId } },
+ * }));
+ * ```
+ *
+ * ## Descriptors are DECLARATIONS, not executed calls
+ *
+ * Each descriptor is a write **fragment** declaration, never an executed write.
+ * The intent key (`create` / `update` / `remove`) is the **discriminator** and
+ * carries the target model (directly, or as a `() => Model` thunk — the
+ * forward/circular-reference escape hatch); `key` / `input` bind model fields to
+ * `$.field` placeholders (or literals). The compiler
+ * (`src/spec/mutation-command.ts`) expands the captured {@link MutationFragment}
+ * list at compile time into a {@link CommandSpec} / `TransactionSpec`. The map's
+ * **insertion order** is the fragments' declaration (execution) order, so the IR
+ * is the SAME ordered `{ name, fragments }` shape the legacy recorder produced —
+ * the single-fragment fast path (#83) and the N-fragment atomic merge (#90) are
+ * unchanged.
+ *
+ * ## Intent selects the lifecycle; `use:` is optional
+ *
+ * Each fragment's **intent** (`create` / `update` / `remove`) selects the
+ * lifecycle from the target's `writes` save contract (`entityWrites`, §2):
+ * `create` → `writes.create`, etc. `use:` is **optional** — it defaults to the
+ * target model's own `writes`; supply it only to adopt a *custom* write contract,
+ * and it takes the **whole** `writes` set (an {@link EntityWritesDefinition}),
+ * never `writes.create` (the intent already picks the lifecycle, so naming the
+ * lifecycle would double-specify it). When the target declares **no** `writes`,
+ * the fragment compiles the **trivial base op** for its intent (create → `Put`
+ * `attribute_not_exists(PK)`, update → `Update`, remove → `Delete`).
+ *
+ * The `$` argument is the **placeholder proxy**: `$.userId` at a `key` / `input`
+ * leaf mints a faithful {@link MutationInputRef} naming an input field, and
+ * `$.alias.field` names a value an **earlier** fragment (by alias) writes — a
+ * cross-fragment reference resolved at compile time (the legacy `$.entity[i].field`
+ * positional form, now alias-based). No arbitrary JS may reach a binding, exactly
+ * as the contract `params` sentinel enforces.
+ */
+
+/**
+ * The intent of a write fragment (proposal §3): `create` / `update` / `remove`
+ * (`remove`, **not** `del`). The intent selects the lifecycle from the target's
+ * save contract, and the base write op (create → `PutItem`, update →
+ * `UpdateItem`, remove → `DeleteItem`).
+ */
+type MutationIntent = 'create' | 'update' | 'remove';
+declare const INPUT_REF_BRAND: unique symbol;
+/**
+ * A faithful reference to a mutation **input** field, minted by reading `$.<field>`
+ * in a mutation body (e.g. `$.title`). Branded so the compiler tells a faithful
+ * input reference from a literal and renders its `{token}` (`{title}`) into the
+ * derived write template — the declarative binding the proposal's `$.input.*`
+ * path root names (here the root is implied: a fragment `input` value is always
+ * an input field reference or a concrete literal).
+ */
+interface MutationInputRef {
+    readonly [INPUT_REF_BRAND]: true;
+    /** The input field name, e.g. `title`. */
+    readonly field: string;
+    /** The template token this reference renders to, e.g. `{title}`. */
+    readonly token: string;
+}
+/** Runtime guard: is `value` a {@link MutationInputRef} (a `$.<field>` read)? */
+declare function isMutationInputRef(value: unknown): value is MutationInputRef;
+declare const ENTITY_REF_BRAND: unique symbol;
+/**
+ * A faithful **cross-fragment reference** (`$.entity[i].field`): the value a later
+ * fragment binds from an **earlier** fragment's written field (proposal §3). The
+ * compiler ({@link compileMutationPlan}) resolves it at **compile time** to the
+ * earlier fragment's binding for that field — a `TransactWriteItems` cannot read
+ * one item's value mid-transaction, so the dependency is resolved declaratively
+ * from the shared input (the referenced field must itself trace to an input
+ * reference or a literal), keeping the composed transaction render-time-resolvable
+ * and atomic. A **forward / self** reference (to a same-or-later fragment) is a
+ * circular dependency, rejected at build time.
+ */
+interface MutationEntityRef {
+    readonly [ENTITY_REF_BRAND]: true;
+    /** The 0-based index of the producing fragment (declaration order). */
+    readonly fragmentIndex: number;
+    /** The produced field name on that fragment's written entity. */
+    readonly field: string;
+    /** The source path, e.g. `$.entity[0].postId` (documentary; surfaces in errors). */
+    readonly path: string;
+}
+/**
+ * The placeholder proxy handed to a mutation body as `$`. In the descriptor-map
+ * authoring form (issue #108) a top-level read `$.<x>` is **ambiguous** until used:
+ *
+ *  - `$.role` placed at a `key` / `input` leaf is an **input-field reference**
+ *    (a {@link MutationInputRef}, token `{role}`) — bound from the command input;
+ *  - `$.membership.role` is a **cross-fragment reference** — the `role` field
+ *    written by the fragment named `membership` (an alias). It mints an
+ *    {@link AliasFieldRef}, which the {@link mutation} assembler rewrites into the
+ *    legacy `$.entity[<index>].<field>` string the compiler resolves (the alias →
+ *    declaration-order index is known once every alias key is seen).
+ *
+ * So each top-level read returns a value that is **both** a faithful
+ * {@link MutationInputRef} (when used directly as a leaf) and supports one further
+ * `.<field>` access (when used as an alias root). Any other access / coercion
+ * throws — the binding stays declarative (only a direct `$.field` / `$.alias.field`
+ * reference or a literal is representable, never a transform).
+ */
+type MutationInputProxy = Record<string, MutationInputRef>;
+declare const FRAGMENT_BRAND: unique symbol;
+/**
+ * The per-field input binding of a fragment: model field name → a faithful
+ * {@link MutationInputRef} (a `$.<field>` reference) or a concrete scalar literal
+ * (e.g. a fixed discriminator). One declarative level — the values bind the model
+ * field they key, never a transform.
+ */
+type FragmentInput = Readonly<Record<string, MutationInputRef | string | number | boolean | Date | null>>;
+/**
+ * A descriptor `key` / `input` value as authored in the descriptor-map form
+ * (issue #108): a `$.field` input reference, a `$.alias.field` cross-fragment
+ * reference (an opaque alias-field ref the assembler rewrites), or a literal.
+ * Structurally `unknown` at the leaf because the alias-field ref is internal; the
+ * assembler validates every leaf via {@link assertFaithfulInput}.
+ */
+type DescriptorBinding = Readonly<Record<string, unknown>>;
+/**
+ * One recorded write fragment (proposal §3): an **intent** + a target entity + an
+ * optional adopted save contract (`use:`) + the input binding. It is a
+ * *declaration* the compiler expands — never an executed write.
+ *
+ * - `intent` — `create` / `update` / `remove`; selects the lifecycle + base op.
+ * - `entity` — the target entity (resolved at definition time).
+ * - `input` — the model-field → input-field / literal binding (declarative).
+ * - `use` — the adopted {@link EntityWritesDefinition} (whole set), or `undefined`
+ *   to default to the target model's own `writes` (and, absent that, the trivial
+ *   base op). Per the `use:` rule it is **never** a single lifecycle.
+ */
+interface MutationFragment {
+    readonly [FRAGMENT_BRAND]: true;
+    readonly intent: MutationIntent;
+    readonly entity: EntityRef;
+    readonly input: FragmentInput;
+    readonly use?: EntityWritesDefinition;
+}
+/** Runtime guard: is `value` a {@link MutationFragment}? */
+declare function isMutationFragment(value: unknown): value is MutationFragment;
+/**
+ * A model reference in a write descriptor (issue #108): either the model class /
+ * `.asModel()` value **directly** (`{ create: GroupMembership }`) or a **thunk**
+ * (`{ create: () => GroupMembership }`). The thunk form is the escape hatch that
+ * preserves forward / circular references — a model not yet defined at the
+ * descriptor's evaluation point is named through a closure, exactly as the legacy
+ * `m.create(() => Model, …)` recorder required.
+ */
+type ModelRef = ModelStatic<DDBModel> | (new (...args: unknown[]) => unknown) | (() => ModelStatic<DDBModel> | (new (...args: unknown[]) => unknown));
+/**
+ * One **write descriptor** in the descriptor-map authoring form (issue #108) —
+ * the declarative twin of an in-process `DDBModel.mutate` entry (#101). The intent
+ * key (`create` / `update` / `remove`) is the **discriminator** and carries the
+ * target {@link ModelRef} (direct or thunk). The remaining fields are declarative
+ * bindings (`$.field` references or literals):
+ *
+ *  - `key` — the target row's primary-key binding (identifies the row);
+ *  - `input` — the non-key field binding (the body / changed fields). Optional for
+ *    a `remove` (a delete writes no fields);
+ *  - `condition` — an optional declarative write gate (accepted for authoring
+ *    parity with the #101 descriptor; threaded by #101's in-process executor — the
+ *    declaration-DSL compiler does not consume it, so the serialized IR is
+ *    unchanged);
+ *  - `result` — an optional read-back projection `{ select, options? }` (likewise
+ *    accepted for authoring parity; the public read-back projection of a
+ *    `command(...).plan(...)` method is still declared on `command({ select })`).
+ *
+ * Exactly one intent key must be present.
+ */
+interface WriteDescriptor {
+    readonly create?: ModelRef;
+    readonly update?: ModelRef;
+    readonly remove?: ModelRef;
+    /** The target row's primary-key binding (`{ field: $.field | literal }`). */
+    readonly key: DescriptorBinding;
+    /** The non-key field binding; optional (a `remove` writes no fields). */
+    readonly input?: DescriptorBinding;
+    /** Optional declarative write gate (accepted for #101 parity; see above). */
+    readonly condition?: DescriptorBinding;
+    /** Optional read-back projection `{ select, options? }` (accepted for #101 parity). */
+    readonly result?: {
+        readonly select?: unknown;
+        readonly options?: unknown;
+    };
+    /**
+     * Optional custom save contract to adopt (the **whole** {@link
+     * EntityWritesDefinition}). Omit to default to the target model's own `writes`.
+     * Per the `use:` rule this is never a single lifecycle — the intent picks it.
+     */
+    readonly use?: EntityWritesDefinition;
+}
+/** The descriptor map a {@link mutation} body returns: alias → {@link WriteDescriptor}. */
+type MutationDescriptorMap = Record<string, WriteDescriptor>;
+declare const COMMAND_PLAN_BRAND: unique symbol;
+/**
+ * The recorded **CommandPlan** — a mutation's IR (proposal §3). It carries the
+ * mutation `name` and the **list** of {@link MutationFragment}s the body declared
+ * (1..N; #83 compiles the 1-fragment case end-to-end, the list shape is ready for
+ * the #90 N-fragment merge). The body closure is discarded — only the declarative
+ * fragment list is kept, exactly as the contract IR discards its method closures.
+ */
+interface CommandPlan {
+    readonly [COMMAND_PLAN_BRAND]: true;
+    /** The mutation name (documentary; surfaces in compiler error messages). */
+    readonly name: string;
+    /** The declared write fragments, in declaration order (the mutation IR). */
+    readonly fragments: readonly MutationFragment[];
+}
+/** Runtime guard: is `value` a {@link CommandPlan} (a `mutation(...)` result)? */
+declare function isCommandPlan(value: unknown): value is CommandPlan;
+/**
+ * The body of a {@link mutation} in the descriptor-map authoring form (issue #108):
+ * `$ => ({ alias: descriptor, … })`. It receives the placeholder proxy `$` and
+ * returns an **alias → {@link WriteDescriptor}** map. The map's **insertion order**
+ * is the fragments' declaration (execution) order, and each alias is the name a
+ * later descriptor's `$.alias.field` cross-fragment reference resolves against.
+ */
+type MutationBody = ($: MutationInputProxy) => MutationDescriptorMap;
+/**
+ * Declare an internal **mutation** — a write-plan composition in the descriptor-map
+ * authoring form (issue #108). The body returns an **alias → {@link WriteDescriptor}**
+ * map; each descriptor names its target via the intent key (`create` / `update` /
+ * `remove`: a model or a `() => Model` thunk) and binds `key` / `input` with `$.field`
+ * placeholders. Insertion order is execution order, and a later descriptor may read
+ * an earlier one's written field via `$.alias.field`.
+ *
+ * ```ts
+ * const JoinGroup = mutation($ => ({
+ *   membership: { create: GroupMembership, key: { groupId: $.groupId, userId: $.userId }, input: { role: $.role } },
+ *   permission: { create: Permission,      key: { id: $.permissionId }, input: { groupId: $.membership.groupId } },
+ * }));
+ * ```
+ *
+ * A leading **name** is optional (it surfaces only in compiler error messages — the
+ * alias map already names each fragment): `mutation('JoinGroup', $ => ({ … }))`.
+ *
+ * The result is a branded {@link CommandPlan} (the mutation IR) — *not* public; it
+ * implements a Command IF via `publicCommandModel(...).plan(mutation)`. The IR shape
+ * (`{ name, fragments }`) is unchanged from the legacy recorder form, so the compiler,
+ * serializer, and every runtime consume it identically.
+ *
+ * @throws if the body returns a non-object / empty map, a descriptor has no (or
+ *   multiple) intent key(s), a binding is non-declarative, or a `$.alias.field`
+ *   reference names an unknown alias.
+ */
+declare function mutation(body: MutationBody): CommandPlan;
+declare function mutation(name: string, body: MutationBody): CommandPlan;
+/**
+ * Alias of {@link mutation} (proposal naming: the internal DSL is `mutation` /
+ * `definePlan`). Identical behavior; provided so a producer may name the plan
+ * declaration `definePlan(…)` when that reads more clearly at the call site.
+ */
+declare const definePlan: typeof mutation;
+
+/**
+ * Serializable static operation specs and manifest (issue #42, Python-bridge
+ * Phase 0b).
+ *
+ * Everything in this module is **JSON-serializable** by construction (only
+ * strings / numbers / booleans / arrays / plain objects — no functions, classes,
+ * `Date`, `Set`, or `undefined`-valued fields are emitted). These types mirror
+ * the `graphddb_manifest.json` / `graphddb_operations.json` shapes sketched in
+ * `docs/python-bridge.md`. The generator (#43) writes them to disk; the
+ * Python runtime (#44+) interprets them.
+ *
+ * ## Templates and placeholders
+ *
+ * Key-condition / range / item / change *values* are **template strings** with
+ * two placeholder forms:
+ *
+ * - `{paramName}` — bound from the caller-supplied params at execution time.
+ * - `{result.sourceField}` — bound from a field of the **prior** operation's
+ *   result item(s), used to chain relation operations.
+ *
+ * A value with no `{...}` is a literal (e.g. a fixed sort-key discriminator
+ * `PROFILE`).
+ */
+
+/** The schema version emitted in every manifest / operations document. */
+declare const SPEC_VERSION: "1.0";
+/** Field type as carried in the manifest (derived from the DynamoDB type). */
+type ManifestFieldType = 'string' | 'number' | 'boolean' | 'binary' | 'stringSet' | 'numberSet' | 'list' | 'map';
+interface ManifestField {
+    readonly type: ManifestFieldType;
+    /**
+     * Semantic format for `string` fields that carry a serialized temporal value.
+     * `datetime` → ISO 8601 instant, `date` → `YYYY-MM-DD`. Absent for plain
+     * fields. The Python runtime uses this to restore `datetime` on hydration,
+     * mirroring the TS hydrator's `format`-driven `Date` reconstruction.
+     */
+    readonly format?: 'datetime' | 'date';
+}
+/** A key (PK or GSI) template descriptor in the manifest. */
+interface ManifestKey {
+    /** Input field names the key is composed from (in declaration order). */
+    readonly inputFields: readonly string[];
+    /** Template for the partition-key value, e.g. `EMAIL#{email}`. */
+    readonly pkTemplate: string;
+    /** Template for the sort-key value, or `null` when the key has no sort key. */
+    readonly skTemplate: string | null;
+}
+interface ManifestGsi extends ManifestKey {
+    readonly indexName: string;
+    readonly unique: boolean;
+}
+interface ManifestRelation {
+    readonly type: 'hasMany' | 'hasOne' | 'belongsTo';
+    /** Target entity (model class) name. */
+    readonly target: string;
+    /** target field → source field (on this entity). */
+    readonly keyBinding: Readonly<Record<string, string>>;
+}
+interface ManifestEntity {
+    /** Declared (logical) table name. */
+    readonly table: string;
+    /** Physical table name (after `TableMapping` resolution). */
+    readonly physicalName: string;
+    /** PK prefix, e.g. `USER#`. */
+    readonly prefix: string;
+    readonly fields: Readonly<Record<string, ManifestField>>;
+    /** Primary key, or `null` when the entity has none. */
+    readonly key: ManifestKey | null;
+    readonly gsis: readonly ManifestGsi[];
+    readonly relations: Readonly<Record<string, ManifestRelation>>;
+}
+interface ManifestTable {
+    readonly physicalName: string;
+}
+interface Manifest {
+    readonly version: typeof SPEC_VERSION;
+    readonly tables: Readonly<Record<string, ManifestTable>>;
+    readonly entities: Readonly<Record<string, ManifestEntity>>;
+}
+interface ParamSpec {
+    readonly type: ParamKind;
+    readonly required: boolean;
+    /** Allowed literal values for `literal` params; omitted otherwise. */
+    readonly literals?: readonly (string | number)[];
+    /**
+     * For an `array` param (transaction `forEach` source), the per-element field
+     * descriptors (field name → element param spec). Omitted for scalar params.
+     */
+    readonly element?: Readonly<Record<string, ParamSpec>>;
+}
+/** A `begins_with` range condition on a sort key (templated value). */
+interface RangeConditionSpec {
+    readonly operator: 'begins_with';
+    readonly key: string;
+    /** Template value, e.g. `GROUP#` or `GROUP#{result.groupId}`. */
+    readonly value: string;
+}
+/** Server-side declarative filter, carried verbatim for the runtime to compile. */
+interface FilterSpec {
+    /** The declarative {@link FilterInput} tree (JSON-safe). */
+    readonly declarative: unknown;
+}
+type ReadOperationType = 'Query' | 'GetItem' | 'BatchGetItem';
+/**
+ * A single static read operation. Relation chains are expressed as multiple
+ * operations whose `resultPath` / templated key conditions wire them together.
+ */
+interface OperationSpec {
+    readonly type: ReadOperationType;
+    readonly tableName: string;
+    readonly indexName?: string;
+    /**
+     * Key condition: attribute name → template value. For a `BatchGetItem` this is
+     * the per-key shape (one key per resolved source item at runtime).
+     */
+    readonly keyCondition: Readonly<Record<string, string>>;
+    readonly rangeCondition?: RangeConditionSpec;
+    /** Projected fields (entity field names). */
+    readonly projection: readonly string[];
+    readonly limit?: number;
+    readonly filter?: FilterSpec;
+    /**
+     * Where the result of this operation is placed in the assembled result.
+     * `$` is the root; `$.groups.items` a relation connection's items, etc.
+     */
+    readonly resultPath: string;
+    /**
+     * For relation operations: the source field on the prior result whose value(s)
+     * drive this operation's `{result.*}` placeholders. Absent on the root op.
+     */
+    readonly sourceField?: string;
+}
+/**
+ * The **execution plan** for a multi-operation read (issue #70a). It is the
+ * Single Source of Truth for *how* a query's {@link OperationSpec}[] is staged:
+ * which operations are independent (may run concurrently) and which must wait for
+ * a prior operation's result. Every runtime that honors it produces identical
+ * effects with identical concurrency discipline — the staging is **serialized,
+ * not re-derived** (cf. the contract decided-facts discipline).
+ *
+ * - `groups` is an ordered list of **stages**; each stage is a list of indices
+ *   into the query's `operations[]`. Operations **within** a stage are mutually
+ *   independent and may be issued concurrently; stages run **in order** because a
+ *   later stage reads a `{result.*}` value produced by an earlier one. Stage 0 is
+ *   always `[0]` (the root). Every operation index appears in exactly one stage,
+ *   and the stages are a topological layering of the result-dependency graph.
+ * - `concurrency` is the declared in-flight bound a runtime applies **within**
+ *   each stage (the shared {@link RELATION_TRAVERSAL_CONCURRENCY} = 16): at most
+ *   this many operations of a stage are issued at once.
+ *
+ * ## Derivation (see `buildReadOperations` / `deriveExecutionPlan`)
+ *
+ * The planner emits `operations[]` in a deterministic pre-order: the root at
+ * index 0, then each relation child immediately followed by its own descendants.
+ * A child's key templates reference `{result.<sourceField>}` of the **operation
+ * whose `resultPath` is the child's parent path** — that producer is the child's
+ * sole dependency. The stage of an operation is therefore `1 + stage(parent)`:
+ * the root is stage 0; sibling relations that share a parent path land in the
+ * **same** stage (no inter-`{result.*}` dependency between siblings, so they are
+ * independent and concurrency-eligible); a grandchild that reads its parent's
+ * `{result.*}` lands one stage later. This mirrors exactly the level-by-level
+ * fan-out the TS relation runtime performs at runtime (`resolveRelations` issues
+ * sibling relations together under the same bound) — #70a only *records* it.
+ *
+ * Absent on a single-operation spec and on specs produced before #70a; a consumer
+ * without a plan falls back to one-operation-per-stage **sequential** execution
+ * (the pre-#70 behavior), so an absent plan never changes results.
+ */
+interface ExecutionPlanSpec {
+    /** Ordered stages; each stage is indices into `operations[]` (stage 0 = `[0]`). */
+    readonly groups: readonly (readonly number[])[];
+    /** The declared in-flight bound applied within each stage (16). */
+    readonly concurrency: number;
+}
+/** A query (read) definition's full execution spec. */
+interface QuerySpec {
+    readonly params: Readonly<Record<string, ParamSpec>>;
+    readonly operations: readonly OperationSpec[];
+    /**
+     * Result cardinality of the **root** (`$`) operation, derived from the
+     * definition kind: `'one'` for `defineQuery` (a single entity object, with any
+     * relations attached directly), `'many'` for `defineList` (a `{ items, cursor }`
+     * connection). The relation runtime (#45) uses this to shape the root result:
+     * a `'one'` Query root takes the first matched item rather than returning a
+     * connection. Absent in specs produced before #45; consumers should treat an
+     * absent value as `'many'` for a `Query`/`BatchGetItem` root and `'one'` for a
+     * `GetItem` root (the pre-#45 behavior).
+     */
+    readonly cardinality?: 'one' | 'many';
+    /**
+     * The staged execution plan (issue #70a): which {@link operations} are
+     * independent (concurrency-eligible) vs. result-dependent. Present only when the
+     * query has more than one operation (a relation chain); a single-operation read
+     * needs no plan. See {@link ExecutionPlanSpec} for the derivation and the
+     * backward-compatible (plan-absent → sequential) fallback.
+     */
+    readonly executionPlan?: ExecutionPlanSpec;
+}
+type WriteOperationType = 'PutItem' | 'UpdateItem' | 'DeleteItem';
+/**
+ * A condition expression on a write, as a JSON-serializable spec (issues #46,
+ * #81). The supported subset:
+ *
+ * - `{ kind: 'notExists' }` → `attribute_not_exists(PK)` (legacy whole-row guard).
+ * - `{ kind: 'attributeExists'; field }` → `attribute_exists(<field>)` — the named
+ *   attribute (any field, incl. PK/SK) must be present. The foundation for
+ *   referential-integrity derivation.
+ * - `{ kind: 'attributeNotExists'; field }` → `attribute_not_exists(<field>)` — the
+ *   named attribute must be absent (field-level uniqueness / first-write guard).
+ * - `{ kind: 'equals'; fields }` → `#f = :v AND …` field equality (each value a
+ *   `{param}` / literal template).
+ */
+type ConditionSpec = {
+    readonly kind: 'notExists';
+} | {
+    readonly kind: 'attributeExists';
+    readonly field: string;
+} | {
+    readonly kind: 'attributeNotExists';
+    readonly field: string;
+} | {
+    readonly kind: 'equals';
+    readonly fields: Readonly<Record<string, string>>;
+};
+interface CommandSpec {
+    readonly type: WriteOperationType;
+    readonly tableName: string;
+    readonly entity: string;
+    readonly params: Readonly<Record<string, ParamSpec>>;
+    /**
+     * Key condition for `UpdateItem` / `DeleteItem` (attribute name → template).
+     * Absent for `PutItem` (the whole item is built from `item`).
+     */
+    readonly keyCondition?: Readonly<Record<string, string>>;
+    /** The full item template for `PutItem` (field name → template / literal). */
+    readonly item?: Readonly<Record<string, string>>;
+    /** Field-level changes for `UpdateItem` (field name → template / literal). */
+    readonly changes?: Readonly<Record<string, string>>;
+    /** Optional write condition (subset). */
+    readonly condition?: ConditionSpec;
+}
+/**
+ * A declarative `when` guard on a transaction item (issue #46). Compares a
+ * templated left-hand value against a templated right-hand value; the item is
+ * skipped when the comparison does not hold. Both values are template strings
+ * (`{param}` / `{item.<field>}` / literal), resolved by the runtime before the
+ * comparison. The runtime compares the resolved **string** values.
+ */
+interface WhenSpec {
+    readonly op: 'eq' | 'ne';
+    /** Templated left-hand value (typically an `{item.<field>}` or `{param}`). */
+    readonly left: string;
+    /** Templated right-hand value (literal or another reference). */
+    readonly right: string;
+}
+/**
+ * The kind of a transaction item. The three write kinds (`Put` / `Update` /
+ * `Delete`) mutate an item; `ConditionCheck` (issue #81) is a **read-only
+ * assertion** on another item — it asserts a {@link ConditionSpec} holds for the
+ * keyed row without modifying it, and its failure cancels the **whole**
+ * `TransactWriteItems` atomically. It is the foundation for referential-integrity
+ * derivation (proposal: `requires <Entity> exists` → a `ConditionCheck` with
+ * `attribute_exists`).
+ */
+type TransactionItemType = 'Put' | 'Update' | 'Delete' | 'ConditionCheck';
+/**
+ * A single templated item in a transaction. When `forEach` is present, the item
+ * is expanded **once per element** of the named array param, with each element's
+ * fields bound to the item's `{item.<field>}` placeholders.
+ *
+ * Field presence by `type`:
+ *
+ * | type           | item | keyCondition | changes | add | condition                |
+ * |----------------|------|--------------|---------|-----|--------------------------|
+ * | `Put`          | ✓    | —            | —       | —   | optional                 |
+ * | `Update`       | —    | ✓            | ✓ / —   | ✓ / — | optional               |
+ * | `Delete`       | —    | ✓            | —       | —   | optional                 |
+ * | `ConditionCheck` | —  | ✓            | —       | —   | **required** (the assert) |
+ *
+ * An `Update` carries `changes` (a `SET` of named fields) and/or `add` (an atomic
+ * `ADD` of named numeric fields, issue #85) — at least one of the two. The two are
+ * distinct DynamoDB update actions: `SET #f = :v` **overwrites**, while
+ * `ADD #f :delta` **atomically increments** without a read (concurrency-safe), so
+ * a derived counter (`User.postCount += 1`) MUST be an `add`, never a `changes`
+ * `SET` (which would clobber a concurrent increment).
+ */
+interface TransactionItemSpec {
+    readonly type: TransactionItemType;
+    readonly tableName: string;
+    readonly entity: string;
+    /** Put: the full item template (field → template / literal). */
+    readonly item?: Readonly<Record<string, string>>;
+    /** Update / Delete / ConditionCheck: the key template (attribute → template). */
+    readonly keyCondition?: Readonly<Record<string, string>>;
+    /** Update: field-level `SET` change templates (overwrite). */
+    readonly changes?: Readonly<Record<string, string>>;
+    /**
+     * Update: field-level atomic `ADD` deltas (issue #85, derived counters). Each
+     * value is a numeric template (`{param}` / a literal number string); the runtime
+     * applies `ADD #field :delta`, an atomic increment that needs no prior read and
+     * is safe under concurrency. A negative delta decrements (e.g. `-1` on a remove).
+     */
+    readonly add?: Readonly<Record<string, string>>;
+    /**
+     * The write / assertion condition (subset). Optional on `Put` / `Update` /
+     * `Delete`; **required** on a `ConditionCheck` (the assertion it makes).
+     */
+    readonly condition?: ConditionSpec;
+    /** Optional declarative guard; the item is skipped when it does not hold. */
+    readonly when?: WhenSpec;
+    /** When present, expand this item once per element of the named array param. */
+    readonly forEach?: {
+        readonly source: string;
+    };
+    /**
+     * Marks a **raw marker-row** write (issue #86 uniqueness guard): the row is NOT a
+     * modeled entity, so its primary key is carried **literally** rather than derived
+     * from manifest metadata. When `true`:
+     *
+     * - a `Put` writes its `item` record **verbatim** as the stored item — the `item`
+     *   already carries the synthetic `PK` / `SK` templates (`UNIQUE#…`), so the
+     *   runtimes do NOT prepend a model prefix or compute GSI attributes;
+     * - a `Delete` uses its `keyCondition` (the `PK` / `SK` templates) as the row Key
+     *   verbatim.
+     *
+     * The companion {@link entity} is the {@link MARKER_ROW_ENTITY} sentinel (there is
+     * no manifest entity to resolve). Absent / `false` on every modeled write (a base
+     * entity / edge / counter / ConditionCheck item), so those paths are unchanged.
+     */
+    readonly literalKey?: boolean;
+}
+/** A declarative transaction definition's full execution spec. */
+interface TransactionSpec {
+    readonly params: Readonly<Record<string, ParamSpec>>;
+    readonly items: readonly TransactionItemSpec[];
+    /**
+     * A static upper bound on the expanded item count when computable (no `forEach`
+     * present → the exact count; with `forEach` it is left absent because the
+     * element count is only known at execution — the runtime then enforces the
+     * DynamoDB ≤25 limit after expansion).
+     */
+    readonly maxItems?: number;
+}
+/**
+ * Whether a contract is a public **read** (`'query'`) or **write** (`'command'`)
+ * interface. Mirrors {@link QueryModelContract} / {@link CommandModelContract}'s
+ * `kind` discriminant from the Contract IR (#58).
+ */
+type ContractKind = 'query' | 'command';
+/**
+ * The resolution kind of a contract query method, **derived** by the planner from
+ * the internal op (never hand-written; see proposal "N+1 Safety"):
+ *
+ * - `'point'` — target keys are known (unique-key `query` / `GetItem`); a key
+ *   array coalesces to one `BatchGetItem`.
+ * - `'range'` — target key set is unknown (partition `list` / `Query`); one
+ *   request per partition key, so it is only ever safe for a single key.
+ */
+type ContractResolution = 'point' | 'range';
+/**
+ * What input arity a contract method accepts, **derived** from its resolution:
+ *
+ * - `'either'` — a single key **or** an array (a `point` read / a known-key
+ *   write; the array form is one `BatchGetItem` / batched write).
+ * - `'single'` — a single key only (a `range` read; an array would be an N+1
+ *   fan-out and is rejected by construction).
+ * - `'array'` — an array only (reserved; not produced by the current resolvers).
+ */
+type ContractInputArity = 'single' | 'array' | 'either';
+/**
+ * The per-key result cardinality of a contract query method, **derived** from the
+ * internal op kind (proposal "Cardinality matrix"):
+ *
+ * - `'one'` — at most one item per key (a `point` read).
+ * - `'many'` — a connection (`{ items, cursor }`) per key (a `range` read).
+ *
+ * This is the per-key shape; the input arity (single vs. array) then decides
+ * whether the overall result is bare or keyed.
+ */
+type ContractCardinality = 'one' | 'many';
+/**
+ * The category of a contract command method's declared result, part of the
+ * contract (it surfaces in OpenAPI and every binding; proposal "Return values"):
+ *
+ * - `'void'` — fire-and-forget write (no body).
+ * - `'result'` — an outcome / status object (e.g. `{ ok, version }`).
+ * - `'entity'` — the updated entity (the post-write projection).
+ */
+type ContractCommandResult = 'void' | 'result' | 'entity';
+/** The Key of a contract: the field names that compose its access / join key. */
+interface ContractKeySpec {
+    /** The key field names, in declaration order (e.g. `["articleId"]`). */
+    readonly fields: readonly string[];
+}
+/**
+ * One External Query (Query Composition) binding on a contract query method
+ * (proposal "External Query"). It is a **build-time, in-process** read dependency
+ * on another contract referenced by name in the same SSoT — there is no protocol
+ * or transport. The runtime collects every parent key produced at this level and
+ * resolves the referenced contract **once, batched**, for all of them.
+ *
+ * A composed child MUST be `point` (proposal "N+1 Safety"): the parent step may
+ * yield N records, so a `range` child would be an N+1 fan-out.
+ */
+interface ComposeSpec {
+    /** The result property the composed value is attached to (e.g. `billing`). */
+    readonly as: string;
+    /** The referenced contract name (a symbol in the same SSoT). */
+    readonly contract: string;
+    /** The referenced method on that contract (e.g. `get`). */
+    readonly method: string;
+    /**
+     * An optional **logical** owner label (the bounded context that owns the
+     * referenced contract) — not a network address. Omitted when unlabeled.
+     */
+    readonly context?: string;
+    /**
+     * The child-key binding: child key field → a `from` source path on the parent
+     * result, e.g. `{ accountId: "$.billingAccountId" }`.
+     */
+    readonly bind: Readonly<Record<string, string>>;
+    /**
+     * The composed child's resolution. It MUST be `'point'` in a valid contract — a
+     * composed child coalesces to one `BatchGetItem` across all parent keys, so a
+     * `range` child (a partition `Query` that cannot be batched across the parent's
+     * keys) is an N+1 fan-out. The N+1 static checker (#60,
+     * {@link assertContractN1Safe}) rejects a `'range'` value on the build path; the
+     * field is widened to {@link ContractResolution} so the offending node can be
+     * carried into the assembled {@link ContractSpec} for the checker to inspect and
+     * reject with a clear message, rather than being silently unrepresentable.
+     */
+    readonly resolution: ContractResolution;
+    /** The composed child's per-key cardinality (`'one'` for a valid `point`). */
+    readonly cardinality: ContractCardinality;
+}
+/**
+ * The **composition execution plan** for one query contract method (issue #70a),
+ * the contract-layer mirror of {@link ExecutionPlanSpec}. It records how a method's
+ * External Query compositions (`compose[]`) are staged relative to the parent read
+ * and to one another, and the batching discipline each composed child obeys:
+ *
+ * - `stages` is an ordered list whose entries are indices into the method's
+ *   `compose[]`. The parent read (the referenced `operation`) is the implicit
+ *   stage before all of these. Every compose child binds its child key purely from
+ *   the **parent** result (`from('$.…')` paths), so sibling compositions are
+ *   mutually independent: they form a single stage `[0, 1, …]` and may be resolved
+ *   concurrently. (A composed child cannot, today, bind from another composed
+ *   child — the #63 DSL only exposes parent `from` paths — so there is never a
+ *   cross-composition dependency; the field is a list of stages so the shape can
+ *   carry one if a future primitive introduces it.)
+ * - `concurrency` is the declared in-flight bound applied **within** a stage (the
+ *   shared {@link RELATION_TRAVERSAL_CONCURRENCY} = 16).
+ * - `batchChunkSize` is the per-request key cap for a composed child read (100,
+ *   the DynamoDB `BatchGetItem` limit): a composition resolves **one batched
+ *   call** across all parent records (chunked at this size), never an N+1 fan-out
+ *   (the composed child is `point`, enforced by the #60 N+1 checker).
+ *
+ * Emitted only when the method declares at least one composition. A method without
+ * compositions carries no plan, and a runtime without one resolves any
+ * compositions sequentially (the pre-#70 behavior) — so an absent plan never
+ * changes results.
+ */
+interface CompositionPlanSpec {
+    /** Ordered stages of indices into `compose[]` (independent siblings share a stage). */
+    readonly stages: readonly (readonly number[])[];
+    /** The declared in-flight bound applied within each composition stage (16). */
+    readonly concurrency: number;
+    /** Per-request key cap for a composed child's batched read (100, BatchGetItem limit). */
+    readonly batchChunkSize: number;
+}
+/**
+ * The serialized spec of one **query** contract method. Carries the decided facts
+ * (`resolution` / `inputArity` / `cardinality`) the planner derived in #58, a
+ * reference into `queries` by name (the internal op), and any External Query
+ * compositions. The decided facts are **serialized, not re-derived** — every
+ * runtime honors them.
+ */
+interface QueryContractMethodSpec {
+    /** Derived: `'point'` (unique-key query) or `'range'` (partition list). */
+    readonly resolution: ContractResolution;
+    /** Derived: `'either'` for `point`, `'single'` for `range`. */
+    readonly inputArity: ContractInputArity;
+    /** Derived per-key result shape: `'one'` (point) or `'many'` (range). */
+    readonly cardinality: ContractCardinality;
+    /** The referenced read op name in `queries` (e.g. `ArticleById__get`). */
+    readonly operation: string;
+    /** External Query compositions on this method; omitted when there are none. */
+    readonly compose?: readonly ComposeSpec[];
+    /**
+     * The composition staging + batch plan (issue #70a); present only when `compose`
+     * is. See {@link CompositionPlanSpec}: independent compositions form one
+     * concurrency-eligible stage after the parent read, each resolved as one batched
+     * call (chunk ≤100). Absent → resolve compositions sequentially (pre-#70).
+     */
+    readonly compositionPlan?: CompositionPlanSpec;
+}
+/**
+ * How a contract command method resolves a single key vs. an array of keys to the
+ * underlying write surface (proposal "Consistency with the existing write
+ * surface"). A single key → one write op (or one transaction); an array → a
+ * batched write — a `TransactWriteItems` when atomicity / per-item conditions are
+ * required, or a `BatchWriteItem` when neither is.
+ */
+type CommandResolutionTarget = 
+/** One write op, referenced by name in `commands`. */
+{
+    readonly mode: 'op';
+    readonly operation: string;
+}
+/** One transaction, referenced by name in `transactions`. */
+ | {
+    readonly mode: 'transaction';
+    readonly transaction: string;
+}
+/**
+ * A non-atomic **parallel** fan-out over the per-key write op (#101). The op
+ * MAY carry a condition (guarded create / conditioned update). Unconditioned
+ * `put`/`delete` ops coalesce into a `BatchWriteItem` (with `UnprocessedItems`
+ * retry); conditioned/update ops issue individual conditional writes
+ * concurrently. Per-op success/failure is reported (partial success); a
+ * per-op failure never aborts the others. References the per-key write op in
+ * `commands`.
+ */
+ | {
+    readonly mode: 'parallel';
+    readonly operation: string;
+};
+/**
+ * The serialized spec of one **command** contract method. Symmetric to
+ * {@link QueryContractMethodSpec}: it carries the declared `result` type and the
+ * `single` / `batch` resolution targets into the existing write specs.
+ */
+interface CommandContractMethodSpec {
+    /** Derived input arity: writes accept `'either'` (single key or key array). */
+    readonly inputArity: ContractInputArity;
+    /** The declared result type (`void` | a `Result` | the updated entity). */
+    readonly result: ContractCommandResult;
+    /** How a single key resolves (one op / one transaction). */
+    readonly single: CommandResolutionTarget;
+    /**
+     * How an array of keys resolves (a transaction / `BatchWriteItem`); omitted
+     * when the contract does not declare a batched write form.
+     */
+    readonly batch?: CommandResolutionTarget;
+    /**
+     * The **return projection** of a `mutation`-derived command method (issue #83;
+     * proposal §3, "return selection as a read projection"). A JSON-safe boolean
+     * field map: after the write commits, the runtime issues a **`GetItem` with
+     * `ConsistentRead`** of the written entity's primary key and applies this
+     * projection via the existing read-projection machinery, returning the projected
+     * item. This is the **uniform** return mechanism for both a single-op command
+     * and a future transaction (a `TransactWriteItems` cannot return item images),
+     * so TS and Python return an **identical** projected item.
+     *
+     * The consistent read-back is issued against the read op named
+     * `<Contract>__<method>__readback` (a synthesized {@link QuerySpec}: a `GetItem`
+     * on the written entity's primary key projecting these fields). Present only on
+     * a `.plan(mutation)` method; a hand-written #64 command omits it (its
+     * {@link result} stays `'void'` / `'entity'` and it returns no projected item).
+     */
+    readonly returnSelection?: Readonly<Record<string, boolean>>;
+}
+/**
+ * A serialized contract — a keyed public read (`'query'`) or write (`'command'`)
+ * interface holding one or more named methods. Each method references an existing
+ * operation spec by name and adds the decided contract facts. The existing
+ * operation-spec shapes are unchanged, so the current runtime keeps working.
+ */
+interface ContractSpec {
+    /** Whether this is a read (`'query'`) or write (`'command'`) contract. */
+    readonly kind: ContractKind;
+    /** The contract Key (the access pattern / join / batch key). */
+    readonly key: ContractKeySpec;
+    /**
+     * The named methods (use cases over the same Key). A query contract's methods
+     * are {@link QueryContractMethodSpec}; a command contract's are
+     * {@link CommandContractMethodSpec}. The map is keyed by contract `kind`.
+     */
+    readonly methods: Readonly<Record<string, QueryContractMethodSpec>> | Readonly<Record<string, CommandContractMethodSpec>>;
+}
+/**
+ * One bounded context's membership (issue #59, "context ownership"). Lists the
+ * Models and Contracts that belong to the same context, so the future boundary
+ * lint (#61) can tell **own** from **foreign**: a contract may resolve its own
+ * context's Models directly, but may only reach another context through that
+ * context's published Contract (direct use of a foreign Model is a build error).
+ *
+ * This issue only **serializes / emits** this declaration; it does not enforce
+ * it. Both lists are entity / contract *names* (matching `manifest.entities` keys
+ * and `contracts` keys respectively).
+ */
+interface ContextSpec {
+    /** Model (entity) names owned by this context (sorted; manifest entity keys). */
+    readonly models: readonly string[];
+    /** Contract names owned by this context (sorted; `contracts` map keys). */
+    readonly contracts: readonly string[];
+}
+interface OperationsDocument {
+    readonly version: typeof SPEC_VERSION;
+    readonly queries: Readonly<Record<string, QuerySpec>>;
+    readonly commands: Readonly<Record<string, CommandSpec>>;
+    /** Declarative transactions (issue #46). Absent in pre-#46 specs. */
+    readonly transactions?: Readonly<Record<string, TransactionSpec>>;
+    /**
+     * The CQRS Contract layer (issue #59): contract name → {@link ContractSpec}.
+     * Layered **on top of** the existing `queries` / `commands` / `transactions`
+     * (each method references one of them by name). **Absent** when the input
+     * defines no contracts — so a contract-free input produces a byte-identical
+     * pre-#59 operations document (backward compatibility).
+     */
+    readonly contracts?: Readonly<Record<string, ContractSpec>>;
+    /**
+     * Context-ownership declarations (issue #59): context name →
+     * {@link ContextSpec}. Used by the boundary lint (#61) to tell own from
+     * foreign. **Absent** when no contexts are declared (backward compatibility).
+     */
+    readonly contexts?: Readonly<Record<string, ContextSpec>>;
+}
+/** The full `{ manifest, operations }` bundle produced by the static planner. */
+interface BridgeBundle {
+    readonly manifest: Manifest;
+    readonly operations: OperationsDocument;
+}
+
+/**
+ * Single-fragment mutation → command-op compiler (issue #83, Epic #80; proposal
+ * `docs/mutation-command-derivation.md` §3).
+ *
+ * A {@link CommandPlan} (a `mutation(...)` result) is the internal IR: a **list**
+ * of write fragments to compose atomically. This module compiles the
+ * **single-fragment** case end-to-end into the **same** {@link ContractMethodOp}
+ * the #58 contract recorder produces, so the existing serializer
+ * (`opToDefinition` → `buildCommandSpec`, `src/spec/contracts.ts` /
+ * `src/spec/operations.ts`) and the existing runtimes consume it with no new
+ * write substrate. The IR is already a list, so the **N-fragment atomic merge is
+ * #90** — this module rejects N>1 with a clear pointer rather than half-merging.
+ *
+ * ## Intent → base op (proposal §3, "single fragment compile")
+ *
+ * | intent   | base op                                   |
+ * |----------|-------------------------------------------|
+ * | `create` | `PutItem` (`attribute_not_exists(PK)`)    |
+ * | `update` | `UpdateItem` (key + changed fields)       |
+ * | `remove` | `DeleteItem` (key)                        |
+ *
+ * ## `use:` resolution (the resolved fork — proposal §3, pinned spec correction)
+ *
+ * The fragment's **intent** selects the lifecycle; `use:` is **optional**:
+ *
+ * - `use:` present → adopt that {@link EntityWritesDefinition} (the **whole**
+ *   `writes` set; never a single lifecycle).
+ * - `use:` omitted → default to the **target model's own** `entityWrites` save
+ *   contract ({@link getEntityWrites}).
+ * - the resolved save contract (custom or default) has **no** entry for the
+ *   intent's lifecycle, **or the target declares no `writes` at all** → the
+ *   **trivial base op** for the intent (create → `Put` `attribute_not_exists(PK)`,
+ *   update → `Update`, remove → `Delete`) against the plain model. So
+ *   `{ create: () => PostModel, key, input }` works on a bare model.
+ *
+ * Either way #83 emits the **same** base op — the resolved
+ * {@link LifecycleContract} only matters as the **per-fragment hook** the
+ * effect-derivation issues (#84–#87) read: the resolved lifecycle's
+ * {@link LifecycleContract.effects} are exposed on {@link CompiledFragment} and
+ * consumed by NONE of #83 (the empty hook).
+ */
+
+/**
+ * A **referential-integrity assertion** derived from a `requires`
+ * ({@link RequiresEffect}) effect (issue #84; proposal §2/§3). It is the
+ * realization of `w.exists(() => Entity, { <entityKeyField>: '$.input.<field>' })`:
+ * the referenced entity must already exist for the bound keys, asserted by a
+ * read-only `ConditionCheck` (`attribute_exists(PK)`) item composed into the
+ * mutation's atomic `TransactWriteItems`. A failed assertion cancels the WHOLE
+ * transaction, so the entity / edges / derived updates / events that the same
+ * transaction would write never persist (referential integrity is enforced
+ * atomically, not by a pre-read).
+ *
+ * The shape is **runtime-neutral** — it carries the structural binding (target
+ * entity + the target key fields resolved from the mutation input) that BOTH the
+ * spec serializer (→ a {@link import('./types.js').TransactionItemSpec} with
+ * templated `keyCondition`, for the Python bridge) and the in-process TS runtime
+ * (→ a `ConditionCheck` `TransactWriteItems` entry, keyed from `(key, params)`)
+ * derive their concrete form from. The compiler resolves the key binding once,
+ * here, so both runtimes assert the **same** keyed row from the same input.
+ */
+interface DerivedConditionCheck {
+    /** The referenced entity whose existence is asserted (resolved target model). */
+    readonly entity: EntityRef;
+    /**
+     * The asserted row's key binding: target primary-key **input field name** → the
+     * **mutation input field** that supplies it (parsed from the effect's
+     * `$.input.<field>` value). Every target primary-key field is bound (a partial
+     * key cannot identify a row to assert on), so the runtimes build the referenced
+     * entity's full primary key from the mutation params.
+     */
+    readonly keyBinding: Readonly<Record<string, string>>;
+}
+/**
+ * A **derived edge write** — the adjacency `Put` / `Delete` {@link TransactionItemSpec}
+ * set that materializes a relation edge on DynamoDB (issue #85; proposal §2 `edges`),
+ * derived from one `w.putEdge(() => Target, 'relation')` / `w.deleteEdge(...)` effect.
+ *
+ * The effect names a **relation** (`Target.relationProperty`) whose rows form the
+ * edge; the **adjacency entity** — the entity whose row IS that edge — is the
+ * relation's *target model* ({@link RelationMetadata.targetFactory}), resolved here
+ * and round-trip-verified by the #82 primitive ({@link deriveEdgeWriteItemsFor}, with
+ * the #85-tightened PK-partition guard). The resolved item set is lifecycle-distinguished
+ * by the fragment's intent ({@link INTENT_EDGE_LIFECYCLE}):
+ *
+ * - `create` → `onCreate`: a single adjacency `Put` (the new edge row);
+ * - `remove` → `onDelete`: a single adjacency `Delete` (the edge row keyed by PK/SK);
+ * - `update` → `onUpdateKeyChange`: `Delete`(old edge, keyed in the `{old.*}`
+ *   namespace) + `Put`(new edge) — the edge **moves** atomically (spec correction).
+ *
+ * The items carry templated key/item fields (`{field}` / `{old.field}`); the
+ * serializer composes them into the atomic `TransactWriteItems` and the in-process
+ * runtime renders the same items from the shared `(key, params)`, so both runtimes
+ * write the **same** adjacency row(s) from the same input.
+ */
+interface DerivedEdgeWrite {
+    /** The adjacency entity (the relation's target — whose row is the edge). */
+    readonly entity: EntityRef;
+    /** The relation (`Target.relationProperty`) the edge materializes (documentary). */
+    readonly relation: {
+        readonly target: string;
+        readonly property: string;
+    };
+    /** The lifecycle-distinguished adjacency item set (`Put` / `Delete`). */
+    readonly items: readonly TransactionItemSpec[];
+}
+/**
+ * A **derived update** — an atomic `ADD` (`UpdateItem`) on a target row, derived
+ * from one `w.increment(() => Entity, { key }, 'field', delta)` effect (issue #85;
+ * proposal §2 `derive`). It realizes a cascading counter such as
+ * `User.postCount += 1`: an atomic `ADD #field :delta` that needs no prior read and
+ * is safe under concurrency (a `SET` would clobber a concurrent increment).
+ *
+ * The lifecycle decides the sign convention the *declaration* uses (the author
+ * declares `+1` on `create`, `-1` on `remove`, and a `-1`-on-old + `+1`-on-new pair
+ * on `update` / onUpdateKeyChange); the compiler stores the declared delta verbatim.
+ * The target row's key binds from the mutation input — `$.input.<field>` (the new /
+ * current value) or `$.old.<field>` (the pre-mutation value, for decrementing the
+ * **old** parent on a key change; the {@link OLD_VALUE_NAMESPACE} convention).
+ */
+interface DerivedUpdate {
+    /** The entity whose attribute is derive-updated (resolved target model). */
+    readonly entity: EntityRef;
+    /**
+     * The target row's key binding: target primary-key **input field name** → the
+     * source param that supplies it. A `$.input.<field>` source binds the param
+     * `<field>`; a `$.old.<field>` source binds the param `old.<field>` (the
+     * pre-mutation value). Every target primary-key field is bound.
+     */
+    readonly keyBinding: Readonly<Record<string, string>>;
+    /** The attribute to atomically `ADD` to. */
+    readonly attribute: string;
+    /** The signed delta to add (e.g. `+1` create, `-1` remove). */
+    readonly amount: number;
+}
+/**
+ * A **derived uniqueness guard** — the marker-row `Put` (and, on a unique-field
+ * change, the old-guard `Delete` + new-guard `Put` swap) that enforces an
+ * application-level uniqueness invariant declared by `w.unique({ name, scope,
+ * fields })` (issue #86; proposal §2 `unique`). It is the realization of a named,
+ * composite-scope uniqueness constraint that a unique GSI cannot express
+ * (e.g. *unique title per user*).
+ *
+ * ## The guard-row key (deterministic, built from `name` / `scope` / `fields`)
+ *
+ * The guard occupies a synthetic marker row whose primary key is built **purely**
+ * from the constraint:
+ *
+ * - `PK` = `UNIQUE#<name>` followed by one `#{<scopeField>}` segment per `scope`
+ *   path (a composite scope yields several segments) — the **partition** the
+ *   uniqueness applies within, e.g. `UNIQUE#postTitlePerUser#{userId}`;
+ * - `SK` = `VALUE#` followed by one `#{<field>}` segment per `fields` path (the
+ *   first carries no leading separator) — the **unique value** within that scope,
+ *   e.g. `VALUE#{title}`.
+ *
+ * Each `$.input.<field>` path contributes a `{<field>}` template token (rendered
+ * from the mutation input). The shape is **deterministic** (same constraint →
+ * same key), so a second write of the same scoped value targets the SAME row, and
+ * the `attribute_not_exists` guard on the `Put` then fails — rolling back the
+ * WHOLE transaction so the entity is never created.
+ *
+ * ## create vs. update-swap
+ *
+ * - **create / remove** — a single guard item: `create` → `Put` (claim the value)
+ *   guarded by `attribute_not_exists(PK)`; `remove` → `Delete` (release the value);
+ * - **update changing a unique field** — `Delete`(OLD guard) + `Put`(NEW guard):
+ *   the old marker row (keyed in the `{old.*}` namespace, the {@link
+ *   OLD_VALUE_NAMESPACE} convention shared with the edge `onUpdateKeyChange` and
+ *   the derived-counter old-parent decrement) is released and the new value claimed
+ *   atomically, so the uniqueness moves with the field. The new `Put` keeps the
+ *   `attribute_not_exists` guard so the moved-to value cannot collide.
+ *
+ * The items are **runtime-neutral** {@link TransactionItemSpec}s carrying the
+ * literal-key marker ({@link TransactionItemSpec.literalKey}) and the
+ * {@link MARKER_ROW_ENTITY} sentinel (there is no manifest entity), so BOTH runtimes
+ * write the SAME marker row(s) from the same input and the guard composes into the
+ * entity's atomic `TransactWriteItems` (#90).
+ */
+interface DerivedUniqueGuard {
+    /** The constraint name (its key-shape discriminator on DynamoDB). */
+    readonly name: string;
+    /** The guard's marker-row item set (`Put` / `Delete`), lifecycle-distinguished. */
+    readonly items: readonly TransactionItemSpec[];
+}
+/**
+ * A **derived outbox event** — the transactional-outbox `Put` ({@link
+ * TransactionItemSpec}) that records a domain event ATOMICALLY with the entity
+ * write, derived from one `w.event(name, payload)` effect (issue #87; proposal §2
+ * `emits`, §4 "delivery is outside"). The event row is written in the **same**
+ * `TransactWriteItems` as the entity, so the event and the state it announces can
+ * never diverge (no "wrote the row, lost the event" gap).
+ *
+ * ## The outbox-row key + shape (deterministic; drainable via `src/cdc/`)
+ *
+ * The row occupies a synthetic marker row in its own `OUTBOX#…` key-space:
+ *
+ * - `PK` = `OUTBOX#<eventName>` followed by one `#{<keyField>}` segment per
+ *   primary-key input field of the **writing entity** — so each entity emission has
+ *   its own deterministic outbox row, e.g. `OUTBOX#PostCreated#{postId}`;
+ * - `SK` = `EVENT#` followed by the same per-key-field segments — a stable,
+ *   single-row-per-emission sort key;
+ * - the item also stores `eventName` plus every declared `payload` field (each a
+ *   `{field}` template rendered from the shared method params), so the **`newImage`**
+ *   of the row carries the complete, typed event body.
+ *
+ * Because the row is a normal table item, the `src/cdc/` Streams substrate captures
+ * its write as a {@link import('../cdc/types.js').ChangeEvent} (`eventName:
+ * 'INSERT'`, `newImage` = this item). A consumer drains the outbox by filtering the
+ * stream on `PK begins_with 'OUTBOX#'` and reading the event body off `newImage` —
+ * **delivery / handlers / business reactions live OUTSIDE the mutation** (proposal
+ * §4); #87 only writes the drainable RECORD.
+ */
+interface DerivedOutboxEvent {
+    /** The event name (e.g. `PostCreated`). */
+    readonly name: string;
+    /** The outbox marker-row `Put` (one item; `literalKey`, `MARKER_ROW_ENTITY`). */
+    readonly items: readonly TransactionItemSpec[];
+}
+/**
+ * A **derived idempotency guard** — the client-token guard `Put` ({@link
+ * TransactionItemSpec}) that makes a same-token re-execution a NO-OP, derived from
+ * the lifecycle's `w.idempotentBy(token)` effect (issue #87; proposal §2
+ * `idempotency`). It is the transactional realization of "process this command at
+ * most once for this client token".
+ *
+ * ## The guard-row key (deterministic, built from the token)
+ *
+ * The guard occupies a synthetic marker row keyed **purely** by the client token:
+ *
+ * - `PK` = `IDEMP#{<tokenField>}` — the `$.input.<field>` token (e.g.
+ *   `IDEMP#{requestId}`), rendered from the shared method params;
+ * - `SK` = `TOKEN` (a fixed discriminator — one guard row per token).
+ *
+ * The `Put` is guarded by `attribute_not_exists(PK)`: the FIRST execution claims the
+ * token row; a SECOND execution with the same token targets the SAME row and the
+ * guard fails, cancelling the WHOLE `TransactWriteItems` — so the entity write, the
+ * outbox event, and every other effect roll back and **no effect is double-applied**.
+ * The shape is identical to the uniqueness guard's claim `Put` (the same `literalKey`
+ * marker mechanism), so BOTH runtimes write / assert the SAME row from the same input.
+ */
+interface DerivedIdempotencyGuard {
+    /** The mutation-input field the token binds from (documentary; surfaces in errors). */
+    readonly tokenField: string;
+    /** The guard marker-row `Put` (one item; `attribute_not_exists`, `literalKey`). */
+    readonly items: readonly TransactionItemSpec[];
+}
+/**
+ * The result of compiling one fragment: the {@link ContractMethodOp} the existing
+ * serializer / runtime consume, the resolved contract Key fields (the model's
+ * primary-key input fields, also the consistent read-back key), and the **opaque
+ * per-fragment hook** — the resolved lifecycle's §2 effect set (empty-consumed by
+ * #83; read by #84–#87).
+ */
+interface CompiledFragment {
+    /** The resolved write op (`put` / `update` / `delete`), serializer-ready. */
+    readonly op: ContractMethodOp;
+    /** The contract Key fields (the model primary-key input fields). */
+    readonly keyFields: readonly string[];
+    /**
+     * The resolved lifecycle's §2 effect set, or `undefined` when the fragment
+     * resolved to the trivial base op (no `writes` entry). **The per-fragment hook
+     * for #84–#87** — #83 derives NO items from it. #84 reads the `requires` arm to
+     * derive {@link conditionChecks}; the remaining arms (unique / edges / derive /
+     * emits / idempotency) are still stored opaquely for #85–#87.
+     */
+    readonly effects?: LifecycleEffects;
+    /**
+     * The referential-integrity assertions derived from the resolved lifecycle's
+     * `requires` effects (issue #84): one {@link DerivedConditionCheck} per
+     * `w.exists(...)`. Present (non-empty) only when the fragment's lifecycle
+     * declares `requires`; absent otherwise (no regression — a fragment with no
+     * `requires` compiles to exactly the #83/#90 base op). Each becomes a read-only
+     * `ConditionCheck` (`attribute_exists`) item in the mutation's atomic
+     * `TransactWriteItems`, and their presence **promotes** an otherwise single-op
+     * mutation to a transaction (a `ConditionCheck` only exists inside a
+     * `TransactWriteItems`).
+     */
+    readonly conditionChecks?: readonly DerivedConditionCheck[];
+    /**
+     * The adjacency edge writes derived from the resolved lifecycle's `edges` effects
+     * (issue #85): one {@link DerivedEdgeWrite} per `w.putEdge(...)` / `w.deleteEdge(...)`,
+     * lifecycle-distinguished by the fragment intent (`create` → `Put`, `remove` →
+     * `Delete`, `update` → `Delete(old) + Put(new)`). Present (non-empty) only when the
+     * lifecycle declares `edges`; absent otherwise (no regression). Each derived item is
+     * composed into the method's atomic `TransactWriteItems`.
+     */
+    readonly edgeWrites?: readonly DerivedEdgeWrite[];
+    /**
+     * The derived (cascading) updates from the resolved lifecycle's `derive` effects
+     * (issue #85): one {@link DerivedUpdate} per `w.increment(...)`, each an atomic
+     * `ADD` on a target counter. Present (non-empty) only when the lifecycle declares
+     * `derive`; absent otherwise (no regression). Each becomes an `UpdateItem` (`ADD`)
+     * in the method's atomic `TransactWriteItems`.
+     */
+    readonly derivedUpdates?: readonly DerivedUpdate[];
+    /**
+     * The uniqueness guards derived from the resolved lifecycle's `unique` effects
+     * (issue #86): one {@link DerivedUniqueGuard} per `w.unique({ name, scope,
+     * fields })`, lifecycle-distinguished by the fragment intent (`create` → a guarded
+     * marker `Put`, `remove` → a marker `Delete`, `update` → `Delete(old) + Put(new)`
+     * — the value swap). Present (non-empty) only when the lifecycle declares
+     * `unique`; absent otherwise (no regression — a fragment with no `unique` compiles
+     * to exactly the #83/#90 base op). Each guard's items compose into the method's
+     * atomic `TransactWriteItems`; the guard `Put`'s `attribute_not_exists` makes a
+     * duplicate roll the WHOLE transaction back, so the entity is never created.
+     */
+    readonly uniqueGuards?: readonly DerivedUniqueGuard[];
+    /**
+     * The outbox events derived from the resolved lifecycle's `emits` effects (issue
+     * #87): one {@link DerivedOutboxEvent} per `w.event(name, payload)`, each a
+     * transactional-outbox `Put` recording the event ATOMICALLY with the entity write
+     * (so event and state cannot diverge). Present (non-empty) only when the lifecycle
+     * declares `emits`; absent otherwise (no regression — a fragment with no `emits`
+     * compiles to exactly the #83/#90 base op). Each event's `Put` composes into the
+     * method's atomic `TransactWriteItems`; its row is drainable via `src/cdc/`
+     * (`PK begins_with 'OUTBOX#'`). Delivery / handlers are OUT of scope (proposal §4).
+     */
+    readonly outboxEvents?: readonly DerivedOutboxEvent[];
+    /**
+     * The idempotency guard derived from the resolved lifecycle's `idempotency` effect
+     * (issue #87): a single {@link DerivedIdempotencyGuard} (the `w.idempotentBy(token)`
+     * client-token guard `Put`, `attribute_not_exists`). Present only when the lifecycle
+     * declares `idempotency`; absent otherwise (no regression). Its `Put` composes into
+     * the method's atomic `TransactWriteItems`; a same-token re-execution fails the
+     * guard and rolls the WHOLE transaction back — so no effect is double-applied.
+     */
+    readonly idempotencyGuard?: DerivedIdempotencyGuard;
+}
+/**
+ * Resolve the {@link LifecycleContract} a fragment adopts for its intent:
+ * `use:` (the whole save contract) when present, else the target model's own
+ * `entityWrites`, then the lifecycle entry for the intent's phase. Returns
+ * `undefined` (→ the trivial base op) when no save contract declares the phase or
+ * the target declares no `writes`.
+ */
+declare function resolveLifecycle(fragment: MutationFragment): LifecycleContract | undefined;
+/**
+ * A resolver for a {@link MutationEntityRef} (`$.entity[i].field`) — supplied by
+ * the multi-fragment compiler ({@link compileMutationPlan}) so a later fragment's
+ * leaf can be resolved to the **earlier** fragment's binding for that field. It
+ * returns the already-rendered value the producer fragment stores at that field
+ * (a {@link ContractParamRef} / {@link ContractKeyFieldRef} / literal), so the
+ * cross-fragment value renders from the **same** shared input at execution time
+ * (a `TransactWriteItems` cannot read another item mid-transaction). `null` for a
+ * single-fragment compile, where a cross-fragment reference is meaningless.
+ */
+type EntityRefResolver = (ref: MutationEntityRef, consumerIndex: number, consumerField: string) => unknown;
+/**
+ * Compile one fragment into a {@link CompiledFragment}. Builds the intent's base
+ * op as a {@link ContractMethodOp}:
+ *
+ * - `create` → a `put` whose `item` is the fragment input (primary-key fields as
+ *   {@link ContractKeyFieldRef}, the rest as {@link ContractParamRef}), guarded by
+ *   `attribute_not_exists(PK)` (`{ notExists: true }`);
+ * - `update` → an `update` whose `keys` is the whole-keys sentinel with
+ *   `keyFields` = the primary-key fields (bound from `$.input.*`), and whose
+ *   `changes` is the **non-key** fragment input;
+ * - `remove` → a `delete` whose `keys` is the whole-keys sentinel + `keyFields`.
+ *
+ * The resolved lifecycle's effect set is attached as the empty per-fragment hook.
+ *
+ * @param fragment  The fragment to compile.
+ * @param index     Its 0-based position in the mutation's fragment list (the
+ *   cross-fragment reference index). `0` for a single-fragment compile.
+ * @param resolveEntityRef Resolver for a `$.entity[i].field` cross-fragment
+ *   reference (multi-fragment compile), or `null` for a single-fragment compile
+ *   (where such a reference is a hard error).
+ */
+declare function compileFragment(fragment: MutationFragment, index?: number, resolveEntityRef?: EntityRefResolver | null): CompiledFragment;
+/**
+ * Compile a single-fragment {@link CommandPlan} into its {@link CompiledFragment}.
+ * The N-fragment atomic merge is **#90** ({@link compileMutationPlan}); this entry
+ * point is the single-fragment fast path used by #83 and by the multi-fragment
+ * compiler for `N === 1` (no behavioral change). A cross-fragment reference is a
+ * hard error here — there is no earlier fragment to read from.
+ *
+ * @throws if `plan` is not a {@link CommandPlan}, or declares more than one fragment.
+ */
+declare function compileSingleFragmentPlan(plan: CommandPlan): CompiledFragment;
+/**
+ * The result of compiling a (1..N)-fragment {@link CommandPlan} (#90): the ordered
+ * per-fragment {@link CompiledFragment}s, merged so they form **one atomic
+ * `TransactWriteItems`**. For a single fragment this is exactly the #83 result with
+ * `fragments.length === 1` (no regression); for N≥2 the fragments are validated
+ * together — same-item conflicts rejected, cross-fragment `$.entity[i].field`
+ * dependencies resolved (circular deps rejected), and the composed item count
+ * capped at {@link MAX_TRANSACT_COMPOSE_ITEMS}.
+ *
+ * The **primary fragment** is fragment 0 — the entity the public Command IF is
+ * keyed by and read back from (`returnSelection`); the proposal's `CreatePost`
+ * keys on `Post` (fragment 0), with `AuditLog` (fragment 1) composed atomically.
+ */
+interface CompiledMutationPlan {
+    /** The mutation name (documentary; surfaces in compiler errors). */
+    readonly name: string;
+    /** Each fragment compiled to its base op, in declaration order. */
+    readonly fragments: readonly CompiledFragment[];
+}
+/**
+ * Compile a (1..N)-fragment {@link CommandPlan} into one **atomically composable**
+ * {@link CompiledMutationPlan} (issue #90; proposal §3, "CROSS-FRAGMENT composition
+ * + validation"). Each fragment is compiled with #83's per-fragment compiler; the
+ * resulting items are **merged into one `TransactWriteItems`**, with every MUST AC
+ * enforced at build time:
+ *
+ * 1. **Cross-fragment data dependencies** — a fragment's `$.entity[i].field` leaf
+ *    is resolved to fragment `i`'s binding for `field` (a build-time alias, so the
+ *    value renders from the same shared input at execution; a `TransactWriteItems`
+ *    cannot read another item mid-transaction). A reference to a **same-or-later**
+ *    fragment (`i ≥ consumer`) is a **circular** dependency and is rejected; an
+ *    out-of-range index, or a field the producer does not write, is rejected.
+ * 2. **Same-item conflict** — two fragments that write the **same primary key**
+ *    ({@link keySignature}) in one transaction are rejected (DynamoDB rejects a
+ *    transaction touching one item twice), naming the conflicting fragments.
+ * 3. **≤25 items** — a composed plan over {@link MAX_TRANSACT_COMPOSE_ITEMS} base
+ *    items is a hard error (an atomic transaction is NEVER split — atomicity, #64).
+ *
+ * Because fragment `i` is fully compiled before fragment `i+1`, and a cross-fragment
+ * reference may only point **backward** (to an already-compiled fragment), resolving
+ * dependencies in declaration order is itself the topological order — a forward /
+ * self reference is the only cycle shape and is rejected directly, so no separate
+ * cycle search is needed.
+ *
+ * @throws if `plan` is not a {@link CommandPlan}; on a malformed / circular / dangling
+ *   cross-fragment reference; on a same-item conflict; or on >25 composed items.
+ */
+declare function compileMutationPlan(plan: CommandPlan): CompiledMutationPlan;
+
+/**
+ * Contract DSL — `publicQueryModel` / `publicCommandModel` (issue #58, CQRS
+ * Contract layer, Epic #57; spec `docs/cqrs-contract.md`).
+ *
+ * A **QueryModel / CommandModel** is the public, storage-independent interface
+ * of a CQRS (logical) service. It is **keyed** — its Key *is* the access pattern
+ * — and holds **one or more named Methods**, each a distinct **use case** (e.g.
+ * `get` + `summary` over the same key, differing only in projection). The Key is
+ * the access pattern; the Method is the use case.
+ *
+ * This module sits **on top of** the existing definition DSL
+ * (`defineQuery` / `defineList` / `definePut` / `defineUpdate` / `defineDelete`,
+ * `src/define/define.ts`) and shares its internal representation
+ * ({@link OperationDefinition}). A contract method body resolves to a single
+ * declarative operation on the underlying model; the closure is **never**
+ * serialized — only the resolved declaration is captured into the IR.
+ *
+ * ```ts
+ * const ArticleById = publicQueryModel<ArticleIdKey>()({
+ *   get: (keys, params) =>
+ *     Article.query(keys, { articleId: true, title: true, body: true }, params),
+ * });
+ * ```
+ *
+ * ## Method signatures (the generation source)
+ *
+ * Every method has one uniform signature, accepting **either one key or an array
+ * of keys** (the array form is what makes a contract uniformly batch-resolvable):
+ *
+ * ```ts
+ * type QueryMethod<TKey, TParams, TResult>   = (key: TKey | readonly TKey[], params: TParams) => TResult;
+ * type CommandMethod<TKey, TParams, TResult> = (key: TKey | readonly TKey[], params: TParams) => TResult;
+ * ```
+ *
+ * These two types are the **generation source** for every binding target
+ * (OpenAPI / Python / PHP / Go / Rust) — see the proposal.
+ *
+ * ## Method names are use cases, not operations
+ *
+ * A method is named for its **use case** (`get` / `summary` / `recent` /
+ * `disable`), never for the storage op it runs. Whether it resolves internally
+ * to a `query` (point lookup) or a `list` (partition read) is the **Runtime's**
+ * concern and is invisible to callers and to generated bindings. The internal op
+ * still determines the **derived** `resolution` / `inputArity` facts (below), but
+ * those are bookkeeping, not part of the method's public name.
+ *
+ * ## Derived facts: `resolution` and `inputArity`
+ *
+ * Per the proposal's N+1 Safety section these are **derived** from the internal
+ * op kind, never hand-written:
+ *
+ * - a unique-key `query` / `GetItem` → `resolution: 'point'`, `inputArity:
+ *   'either'` (a key array becomes one `BatchGetItem`);
+ * - a partition `list` / `Query` → `resolution: 'range'`, `inputArity: 'single'`
+ *   (DynamoDB cannot coalesce N partition `Query`s — feeding an array would be an
+ *   N+1 fan-out, so the range method only accepts a single key).
+ *
+ * Command methods additionally carry an explicit **result type** (`void` | a
+ * `Result` | the updated entity) as part of the contract; see
+ * {@link CommandResultKind}.
+ *
+ * ## Build-time hardening (reused from `defineTransaction`)
+ *
+ * The method body is evaluated at definition time with **throwing sentinels** in
+ * place of `keys` / `params`, recorded through a model recorder, and subjected to
+ * the **same** hardening `defineTransaction` (`src/define/transaction.ts`) applies
+ * to value positions:
+ *
+ *  1. **Throwing sentinel Proxy** — every property / method access other than the
+ *     internal brand reads and primitive coercion throws at the access site.
+ *  2. **Per-access coercion ledger (primary boundary)** — a faithful reference is
+ *     stored as the Proxy object and is *never* coerced, so any coercion of a
+ *     `params` field is positive proof the body consumed it into a transform /
+ *     branch / interpolation and the build is rejected.
+ *  3. **Differential evaluation (secondary)** — the body runs twice with disjoint
+ *     per-field markers; every recorded leaf must be a faithful reference or a
+ *     byte-identical literal across passes.
+ *  4. **Consumed-field check** — a `params` field the body accessed but that never
+ *     reached the recorded operation (a silent value branch) is rejected.
+ *
+ * So any non-declarative body (a transform, a value branch, a coercion, arbitrary
+ * JS over `keys` / `params`) is rejected at build time — never silently emitted
+ * as a wrong spec. The #58 issue was the **DSL + IR + type-level surface only**:
+ * serialization to the JSON SSoT (#59) and execution against DynamoDB (#62) were
+ * out of scope there.
+ *
+ * ## External Query composition (`query` / `from`, issue #63)
+ *
+ * The {@link query} / {@link from} primitive (added by #63) extends a read method
+ * body with a **build-time-resolved, in-process** reference to **another query
+ * contract's** method — relation chaining where the link is a contract reference
+ * instead of a model relation (there is no protocol / transport). Placed at a
+ * `select` property (`as: query(OtherContract.method, { childKey: from("$.field") })`),
+ * it is recorded as a declarative {@link RecordedCompose} edge on the method op
+ * (the property name becomes `as`, and it is removed from the read projection).
+ * The binding stays declarative — `from` admits only a literal `$`-rooted path —
+ * so no arbitrary JS reaches a key binding. The serializer (#59) recovers the
+ * referenced contract name by identity and emits the proposal's `compose` shape;
+ * the N+1 checker (#60) enforces the `point`-child rule; the runtimes (#62 infra
+ * reused) resolve the child once, batched, across all parent records.
+ */
+
+/**
+ * The **resolution kind** of a method, derived from its internal op:
+ *
+ * - `'point'` — target keys are known (unique-key `query` / `GetItem`, fixed key
+ *   sets); coalesces to a `BatchGetItem` for a key array.
+ * - `'range'` — target key set is unknown (partition `list` / `Query`); one
+ *   request per partition key, so it is only ever safe for a single key.
+ */
+type Resolution = 'point' | 'range';
+/**
+ * What input arity a method accepts, derived from its `resolution`:
+ *
+ * - `'either'` — a single key **or** an array (a `point` read; the array form is
+ *   one `BatchGetItem`).
+ * - `'single'` — a single key only (a `range` read; an array would be an N+1
+ *   fan-out and is rejected by construction).
+ * - `'array'` — an array only (reserved; not produced by the current resolvers).
+ */
+type InputArity = 'single' | 'array' | 'either';
+/**
+ * The category of a {@link CommandMethod}'s declared result, part of the
+ * contract (it surfaces in OpenAPI and every binding):
+ *
+ * - `'void'` — fire-and-forget write (no body);
+ * - `'result'` — an outcome/status object (e.g. `{ ok, version }`);
+ * - `'entity'` — the updated entity (the post-write projection).
+ *
+ * The concrete `TResult` type is preserved at the type level on
+ * {@link CommandMethodSpec}; this discriminant is the runtime/SSoT-facing label.
+ */
+type CommandResultKind = 'void' | 'result' | 'entity';
+/**
+ * The formal **query** method signature (proposal: "Query Method — Common
+ * Interface"). Accepts a single key **or** an array of keys and returns
+ * `TResult`. This one type is the generation source for every binding target.
+ *
+ * @typeParam TKey    - The contract Key (the access pattern / join key).
+ * @typeParam TParams - The retrieval options (pagination / cursor / consistency).
+ * @typeParam TResult - The method's result type.
+ */
+type QueryMethod<TKey, TParams, TResult> = (key: TKey | readonly TKey[], params: TParams) => TResult;
+/**
+ * The formal **command** method signature (proposal: "Command Definition").
+ * Symmetric to {@link QueryMethod}, with an explicit result type. A single key
+ * maps to one write op; an array maps to a batched write.
+ *
+ * @typeParam TKey    - The contract Key (the target identity).
+ * @typeParam TParams - The call params.
+ * @typeParam TResult - The declared result type (`void` | a `Result` | entity).
+ */
+type CommandMethod<TKey, TParams, TResult> = (key: TKey | readonly TKey[], params: TParams) => TResult;
+declare const KEY_REF_BRAND: unique symbol;
+declare const KEY_FIELD_REF_BRAND: unique symbol;
+/**
+ * The captured `keys` argument of a contract method body. A branded sentinel that
+ * supports the two faithful uses the proposal's examples need:
+ *
+ *  - **passed whole** into a model op's key position
+ *    (`Model.query(keys, …)` / `Model.updateItem(keys, …)`) — the point / write form;
+ *  - **destructured per field** to rebuild a partition key
+ *    (`Model.list({ categoryId: keys.categoryId }, …)`) — the range form. Each
+ *    `keys.<field>` mints a faithful {@link ContractKeyFieldRef}.
+ *
+ * Both forms are declarative: the recorded key slot is either this sentinel
+ * itself (whole) or a `{ field: ContractKeyFieldRef }` record. Any non-faithful
+ * use — coercing `keys`, or transforming a `keys.<field>` ref — is rejected by the
+ * same coercion ledger / differential checks as `params`.
+ */
+interface ContractKeyRef {
+    readonly [KEY_REF_BRAND]: true;
+}
+/**
+ * A captured reference to a single field of the method's `keys` argument
+ * (`keys.<field>`), minted when a range body rebuilds a partition key. Branded so
+ * the verifier can distinguish a faithful key-field reference from a literal, and
+ * so it cannot be silently coerced.
+ */
+interface ContractKeyFieldRef {
+    readonly [KEY_FIELD_REF_BRAND]: true;
+    /** The key field name, e.g. `categoryId`. */
+    readonly field: string;
+    /** The template token this reference renders to, e.g. `{key.categoryId}`. */
+    readonly token: string;
+}
+/** Runtime guard: is `value` a {@link ContractKeyRef} (the whole key sentinel)? */
+declare function isContractKeyRef(value: unknown): value is ContractKeyRef;
+/**
+ * Mint a faithful {@link ContractKeyFieldRef} for a named key field — a plain
+ * (non-Proxy) reference rendering the `{key.field}` differential token but, at a
+ * **value** position (a `put` item field), serialized as `{field}` (see
+ * `templateLeaf`, `src/spec/operations.ts`). Used by the **mutation compiler**
+ * (#83) to mark which of a `create` fragment's item fields are the model's
+ * primary-key (contract Key) fields, so the existing serializer recovers the
+ * contract Key from the put item (`keyFieldsOf`) exactly as it does for a
+ * hand-written #64 `put` that binds `keys.<field>` into the item. Mirrors
+ * {@link mintContractParamRef}.
+ *
+ * @param field The key field name (rendered `{field}` at a value position).
+ */
+declare function mintContractKeyFieldRef(field: string): ContractKeyFieldRef;
+/**
+ * The whole-`keys` sentinel value an `update` / `delete` op records in its key
+ * slot when the body passed `keys` whole into the op's key position. Exposed so
+ * the **mutation compiler** (#83) can build an equivalent planned `update` /
+ * `delete` op without re-entering the hardening machinery (a mutation has no
+ * `keys` argument — its key fields are bound from `$.input.*`, captured via
+ * {@link ContractMethodOp.keyFields}).
+ */
+declare function wholeKeysSentinel(): ContractKeyRef;
+/** Runtime guard: is `value` a {@link ContractKeyFieldRef}? */
+declare function isContractKeyFieldRef(value: unknown): value is ContractKeyFieldRef;
+declare const PARAM_REF_BRAND: unique symbol;
+/**
+ * A captured reference to a field of the method's `params` argument (`{<field>}`).
+ * Branded so the recorder can distinguish a faithful reference from a concrete
+ * literal, and so a stray reference cannot be silently coerced.
+ */
+interface ContractParamRef {
+    readonly [PARAM_REF_BRAND]: true;
+    /** The template token this reference renders to, e.g. `{limit}`. */
+    readonly token: string;
+    /** The field name on `params`, e.g. `limit`. */
+    readonly field: string;
+}
+/** Runtime guard: is `value` a {@link ContractParamRef}? */
+declare function isContractParamRef(value: unknown): value is ContractParamRef;
+/**
+ * Mint a faithful {@link ContractParamRef} for a named field — a concrete
+ * (non-Proxy) reference rendering the `{field}` token. Unlike the hardening
+ * sentinels {@link makeParamFieldRef} builds during a contract method body (which
+ * throw on any transform to detect non-declarative use), this is a *plain* ref
+ * used by the **mutation compiler** (#83, `src/spec/mutation-command.ts`): a
+ * mutation fragment's `input` binding is captured as a {@link MutationInputRef}
+ * (its own declarative sentinel), and the compiler translates each one into this
+ * `ContractParamRef` so the **existing** contract serializer
+ * ({@link opToDefinition} → {@link buildCommandSpec}) and TS runtime
+ * ({@link renderLeaf}) consume it with **zero** new template / param machinery —
+ * the param name and `{token}` are the input field name, exactly as a hand-written
+ * `params.field` reference would render.
+ *
+ * @param field The param / input field name (the rendered token is `{field}`).
+ */
+declare function mintContractParamRef(field: string): ContractParamRef;
+declare const FROM_REF_BRAND: unique symbol;
+declare const COMPOSE_NODE_BRAND: unique symbol;
+/**
+ * A parent-result source path produced by {@link from} (proposal "External
+ * Query"). It names the field of the **parent** method's result that supplies a
+ * composed child's key, e.g. `from("$.billingAccountId")`. The path is a plain
+ * `"$.field"` string — the binding is **declarative** (no arbitrary JS): the
+ * value is read from the resolved parent record at execution time, never computed.
+ *
+ * The grammar is intentionally minimal — a single dotted field path rooted at
+ * `$` (the parent record). `$.a.b` reaches a nested field; anything else (a bare
+ * field with no `$`, an index, a wildcard, an empty path) is rejected by
+ * {@link from} at build time so a malformed binding can never reach the SSoT.
+ */
+interface ContractFromRef {
+    readonly [FROM_REF_BRAND]: true;
+    /** The `$`-rooted source path on the parent result, e.g. `$.billingAccountId`. */
+    readonly path: string;
+}
+/** Runtime guard: is `value` a {@link ContractFromRef} (a `from(...)` binding)? */
+declare function isContractFromRef(value: unknown): value is ContractFromRef;
+/**
+ * A resolved External Query composition node produced by {@link query} and placed
+ * at a `select` property of a contract method body (proposal "External Query"):
+ *
+ * ```ts
+ * Account.query(keys, {
+ *   accountId: true,
+ *   billing: query(BillingPlanQueries.get, { accountId: from("$.billingAccountId") }),
+ * })
+ * ```
+ *
+ * It carries a faithful reference to the **referenced method spec** (so the
+ * serializer can recover the referenced contract's *name* by identity against the
+ * contract map, and its derived `resolution` / `cardinality` facts) plus the
+ * declarative child-key binding (child key field → a {@link ContractFromRef}).
+ * The owning `select` key becomes the composition's `as` property at record time
+ * (it is not known to {@link query} itself).
+ */
+interface ContractComposeNode {
+    readonly [COMPOSE_NODE_BRAND]: true;
+    /** The referenced query method spec (`OtherContract.method`). */
+    readonly method: QueryMethodSpec<unknown, unknown, unknown>;
+    /** The child-key binding: child key field → parent-result `from` path. */
+    readonly bind: Readonly<Record<string, ContractFromRef>>;
+}
+/** Runtime guard: is `value` a {@link ContractComposeNode} (a `query(...)` node)? */
+declare function isContractComposeNode(value: unknown): value is ContractComposeNode;
+/**
+ * Declare a parent-result source path for an External Query child key binding
+ * (proposal "External Query"). Used **only** inside a {@link query} binding:
+ *
+ * ```ts
+ * query(BillingPlanQueries.get, { accountId: from("$.billingAccountId") })
+ * ```
+ *
+ * The path is `$`-rooted (the parent record) and dotted; the bound child-key
+ * field is read from that path of each resolved parent record at execution time.
+ * The binding is **declarative** — `from` accepts only a literal path string and
+ * rejects any other shape, so no arbitrary JS can sneak into a key binding.
+ *
+ * @param path A `$`-rooted dotted path, e.g. `"$.billingAccountId"` or `"$.a.b"`.
+ * @throws if `path` is not a non-empty `$`-rooted dotted field path.
+ */
+declare function from(path: string): ContractFromRef;
+/**
+ * Reference another query contract's method as an **External Query** composition
+ * child, bound to the parent result by a declarative `from` mapping (proposal
+ * "Query Composition" / "External Query"). Place the result at a `select`
+ * property of a contract method body; the property name becomes the composed
+ * value's `as`:
+ *
+ * ```ts
+ * export const AccountAccess = publicQueryModel<AccountKey>()({
+ *   get: (keys, params) => Account.query(keys, {
+ *     accountId: true,
+ *     billing: query(BillingPlanQueries.get, { accountId: from("$.billingAccountId") }),
+ *   }, params),
+ * });
+ * ```
+ *
+ * This is **build-time-resolved, in-process** contract chaining — the relation
+ * primitive extended to point at another contract's method instead of a model
+ * relation. There is no protocol / transport: the runtime collects every bound
+ * key produced by the parent step and resolves the referenced contract **once,
+ * batched** (proposal "External Query"). The child MUST be `point` (the parent
+ * may yield N records, so a `range` child would be an N+1 fan-out) — that rule is
+ * owned by the N+1 checker (#60), which rejects a `range` child at build time.
+ *
+ * @param method  The referenced query method (`OtherContract.method`), a resolved
+ *   {@link QueryMethodSpec}.
+ * @param bind    The child-key binding: child key field → a {@link from} path on
+ *   the parent result. Must be non-empty and every value a `from(...)` ref.
+ * @throws if `method` is not a query method spec, or `bind` is empty / carries a
+ *   non-`from` value.
+ */
+declare function query(method: QueryMethodSpec<any, any, any>, bind: Record<string, ContractFromRef>): ContractComposeNode;
+/**
+ * The {@link QueryModelContract} that owns a resolved query method spec, or
+ * `undefined` if the spec was not produced by {@link publicQueryModel} (so it has
+ * no registered owner). Used by the serializer to resolve a composition's
+ * referenced contract by identity.
+ */
+declare function contractOfMethodSpec(method: QueryMethodSpec<unknown, unknown, unknown>): QueryModelContract<unknown, Record<string, QueryMethodSpec<unknown, unknown, unknown>>> | undefined;
+/**
+ * The declarative internal operation a contract method body resolves to — the
+ * resolved declaration captured into the IR (the closure itself is discarded).
+ * Mirrors {@link OperationDefinition} but is produced by the model recorder
+ * handed to a contract method body rather than a `define*` entry point.
+ *
+ * @typeParam Op - The internal op kind (`query` | `list` | `put` | `update` |
+ *   `delete`).
+ */
+interface ContractMethodOp<Op extends OperationKind = OperationKind> {
+    /** @internal Marks this object as a recorded contract method op. */
+    readonly __isContractMethodOp: true;
+    /** The model the op targets (name + runtime class). */
+    readonly entity: EntityRef;
+    /** The internal op kind. Determines the derived `resolution` / `inputArity`. */
+    readonly operation: Op;
+    /**
+     * The captured key slot. Either the whole {@link ContractKeyRef} sentinel
+     * (passed faithfully into the op's key position — the point / write form) or a
+     * `{ field: ContractKeyFieldRef }` record rebuilt from `keys.<field>` (the range
+     * form). For `put` it is the inert {@link PUT_HAS_NO_KEY} marker. Stored as
+     * evidence of faithfulness; never serialized.
+     */
+    readonly keys: ContractKeyRef | Readonly<Record<string, unknown>>;
+    /**
+     * The **explicit contract Key field names** captured from the factory's
+     * key-field argument (`publicQueryModel<EmailKey>(['email'])(...)`, issue #71).
+     * Present only for a **whole-`keys`** op (the {@link keys} slot is the whole
+     * {@link ContractKeyRef} sentinel) when the author supplied a field list, or
+     * when the model-derived factory form defaulted it to the model's primary-key
+     * input fields. It is the SSoT for "which fields the Key is composed of" — fed
+     * through {@link resolveKey} so the serializer emits the correct base-table PK
+     * **or** GSI (`indexName` + GSI key template) key, and so the planner can tell a
+     * coalescible base-table point (`GetItem` / `BatchGetItem`) from a non-coalescible
+     * GSI point (a unique-GSI `Query`).
+     *
+     * Absent when the body rebuilds a partition key from `keys.<field>` references
+     * (the range form already captures field names in the {@link keys} record) or
+     * when no explicit list was given to a `publicQueryModel<TKey>()` whole-key form
+     * (the legacy backward-compatible path, which then defaults to the primary key).
+     */
+    readonly keyFields?: readonly string[];
+    /** The select projection for `query` / `list`; `undefined` for writes. */
+    readonly select?: Readonly<Record<string, unknown>>;
+    /** The changes structure for `update`; `undefined` otherwise. */
+    readonly changes?: Readonly<Record<string, unknown>>;
+    /** The item structure for `put`; `undefined` otherwise. */
+    readonly item?: Readonly<Record<string, unknown>>;
+    /** The optional declarative write condition for writes. */
+    readonly condition?: ConditionInput;
+    /**
+     * External Query compositions (#63) extracted from the recorded `select`: each
+     * `query(OtherContract.method, { childKey: from("$.parentField") })` node placed
+     * at a `select` property becomes one {@link RecordedCompose} here (the property
+     * name is its `as`), and the property is removed from the read projection. Absent
+     * when the body declares no composition.
+     */
+    readonly compose?: readonly RecordedCompose[];
+}
+/**
+ * A recorded External Query composition edge on a contract method op (#63). The
+ * declarative result of a `query(OtherContract.method, { … })` call placed at a
+ * `select` property: it pairs the property name (`as`) with a faithful reference
+ * to the referenced method spec and the declarative child-key binding. The
+ * referenced contract's *name* and the child's derived `resolution` / `cardinality`
+ * are recovered by the serializer (`src/spec/contracts.ts`) from the method spec
+ * by identity against the contract map; they are not duplicated here.
+ */
+interface RecordedCompose {
+    /** The result property the composed value attaches to (the `select` key). */
+    readonly as: string;
+    /** The referenced query method spec (`OtherContract.method`). */
+    readonly method: QueryMethodSpec<unknown, unknown, unknown>;
+    /** The child-key binding: child key field → parent-result `from` path. */
+    readonly bind: Readonly<Record<string, ContractFromRef>>;
+}
+/**
+ * The **call signature** a contract method exposes to a caller, narrowed by its
+ * decided {@link InputArity} — the type-level half of N+1 rule (a) ("array into a
+ * `range` method", #60). Given a method's `inputArity`:
+ *
+ * - `'single'` (a `range` method) — the key argument is a **single** `TKey` only;
+ *   passing an array (`readonly TKey[]`) is a **type error** by construction, so a
+ *   `range` method's array overload does not type-check.
+ * - `'either'` (a `point` read / known-key write) — a single key **or** an array
+ *   (the array form coalesces to one `BatchGetItem` / batched write).
+ * - `'array'` — an array only (reserved; not produced by the current resolvers).
+ *
+ * This mirrors the proposal's "the generated binding's types encode `inputArity`
+ * (single → bare argument, array → array argument)". It is the type-level narrowing
+ * used by the runtime call surface (`executeQueryMethod`, `src/runtime/contract-runtime.ts`):
+ * the executor keys its key-argument type on the named method's **literal** arity
+ * `A` (carried on {@link QueryMethodSpec} when the body is tagged with
+ * {@link point} / {@link range}), so feeding an array into a `'single'` method is a
+ * `tsc` compile error — the **primary** N+1 rule (a) layer, complementing the
+ * build-time SSoT check ({@link assertContractN1Safe}) and the runtime backstop.
+ *
+ * @typeParam A       - The decided input arity (a literal `InputArity`).
+ * @typeParam TKey    - The contract Key.
+ * @typeParam TParams - The method's params type.
+ * @typeParam TResult - The method's result type.
+ */
+type ContractCallSignature<A extends InputArity, TKey, TParams, TResult> = (key: A extends 'single' ? TKey : A extends 'array' ? readonly TKey[] : TKey | readonly TKey[], params: TParams) => TResult;
+/**
+ * The resolved IR of one **query** method. Carries the formal method type at the
+ * type level (`QueryMethod<TKey, TParams, TResult>`) and, at runtime, the resolved
+ * internal op plus the **derived** facts (`resolution` / `inputArity`).
+ *
+ * @typeParam TKey    - The contract Key.
+ * @typeParam TParams - The method's params type.
+ * @typeParam TResult - The method's result type.
+ * @typeParam A       - The method's **literal** {@link InputArity} when the author
+ *   tagged the body with {@link point} / {@link range} (the type-level half of
+ *   N+1 rule (a), threaded into the call surface so an array fed into a `'single'`
+ *   method is a `tsc` error — see {@link ContractCallSignature} and
+ *   `executeQueryMethod`). Defaults to the wide `InputArity` for an untagged body,
+ *   which then relies on the build-time checker + the runtime backstop only.
+ */
+interface QueryMethodSpec<TKey, TParams, TResult, A extends InputArity = InputArity> {
+    /** @internal Marks this object as a query method spec. */
+    readonly __methodKind: 'query';
+    /** The resolved internal operation (closure discarded). */
+    readonly op: ContractMethodOp;
+    /** Derived: `'point'` (unique-key query) or `'range'` (partition list). */
+    readonly resolution: Resolution;
+    /**
+     * Derived: `'either'` for a base-table `point`, `'single'` for a `range` or a
+     * unique-GSI `point`. Typed as the method's **literal** arity `A` when the body
+     * was tagged ({@link point} / {@link range}); a tagged literal is verified
+     * against this derived value at build time (a mismatch is a build error), so the
+     * type cannot lie about the runtime arity.
+     */
+    readonly inputArity: A;
+    /**
+     * @internal The method's own name in its contract (`'get'`, `'summary'`, …),
+     * stamped by the factory. An External Query composition (#63) references this
+     * spec object; the serializer recovers the referenced method name from here and
+     * the referenced contract name by identity ({@link contractOfMethodSpec}).
+     */
+    readonly __methodName?: string;
+    /** @internal Phantom carrier retaining the formal `QueryMethod` type. */
+    readonly __signature?: QueryMethod<TKey, TParams, TResult>;
+}
+/**
+ * The resolved IR of one **command** method. Symmetric to {@link QueryMethodSpec},
+ * with an explicit declared result (`void` | a `Result` | the updated entity).
+ *
+ * @typeParam TKey    - The contract Key.
+ * @typeParam TParams - The method's params type.
+ * @typeParam TResult - The method's declared result type.
+ */
+interface CommandMethodSpec<TKey, TParams, TResult> {
+    /** @internal Marks this object as a command method spec. */
+    readonly __methodKind: 'command';
+    /** The resolved internal write operation (closure discarded). */
+    readonly op: ContractMethodOp;
+    /**
+     * Derived input arity: a single key maps to one write op; an array maps to a
+     * batched write (a transaction / `BatchWriteItem`). Writes accept `'either'`.
+     */
+    readonly inputArity: InputArity;
+    /**
+     * The category of the declared result type (`void` | `result` | `entity`),
+     * part of the contract (it surfaces in OpenAPI and every binding). Derived from
+     * the internal op when not explicitly annotated: an `update` returning the
+     * entity → `'entity'`; a `delete` → `'void'`.
+     */
+    readonly result: CommandResultKind;
+    /**
+     * The per-call execution **mode** (issue #101): `'transaction'` (default, atomic
+     * all-or-nothing) or `'parallel'` (non-atomic, per-op partial success). It drives
+     * the key-array bulk resolution form directly (the serializer's `modeTargetFor`).
+     * Present on every descriptor-authored command method.
+     */
+    readonly mode?: CommandMode;
+    /**
+     * The return projection of a {@link mutation}-derived command method (issue
+     * #83): a boolean field map applied to the written entity as a **consistent
+     * read-back** projection after the write commits (the proposal's "return =
+     * read projection"). Present only on a `.plan(mutation)` method; a hand-written
+     * #64 method (the closure form) omits it. JSON-safe (only boolean leaves), so
+     * it serializes verbatim into {@link CommandContractMethodSpec.returnSelection}
+     * and both runtimes apply the **same** projection.
+     */
+    readonly returnSelection?: Readonly<Record<string, boolean>>;
+    /**
+     * The composed write ops of a **multi-fragment** `mutation`-derived method
+     * (issue #90): when a mutation declares **2+ fragments**, each fragment compiles
+     * to one write {@link ContractMethodOp} and the whole set executes as **one
+     * atomic `TransactWriteItems`** (NOT sequential writes). Present only for N≥2; a
+     * single-fragment method carries only {@link op} (no regression — #83 behavior).
+     * The merge (same-item conflict / cross-fragment dep / ≤25 enforcement) is done
+     * at build time by `compileMutationPlan`; `op` is set to the **primary** fragment
+     * (fragment 0 — the entity the method is keyed by and read back from) so the
+     * Key / read-back machinery is unchanged.
+     */
+    readonly ops?: readonly ContractMethodOp[];
+    /**
+     * The referential-integrity assertions derived from the mutation's `requires`
+     * effects (issue #84): one {@link DerivedConditionCheck} per
+     * `w.exists(...)`, flattened across every fragment. Present (non-empty) only when
+     * a fragment's lifecycle declares `requires`; absent otherwise (no regression —
+     * the method then carries only its base op(s)). Each becomes a read-only
+     * `ConditionCheck` (`attribute_exists`) item in the method's atomic
+     * `TransactWriteItems`, and their presence **promotes** an otherwise single-op
+     * method to a transaction: the serializer emits a {@link
+     * import('../spec/types.js').TransactionItemSpec}-based `TransactionSpec` and
+     * `single: { mode: 'transaction' }`, and the in-process runtime composes the base
+     * write(s) + the ConditionCheck(s) into one transaction so an absent referent
+     * rolls the WHOLE write back.
+     */
+    readonly conditionChecks?: readonly DerivedConditionCheck[];
+    /**
+     * The adjacency edge writes derived from the mutation's `edges` effects (issue
+     * #85), flattened across every fragment in declaration order. Present (non-empty)
+     * only when a fragment's lifecycle declares `edges`; absent otherwise (no
+     * regression). Each {@link DerivedEdgeWrite} contributes its adjacency `Put` /
+     * `Delete` item(s) to the method's atomic `TransactWriteItems`, and their presence
+     * (like {@link conditionChecks}) **promotes** an otherwise single-op method to a
+     * transaction so the edge moves / removes atomically with the entity write.
+     */
+    readonly edgeWrites?: readonly DerivedEdgeWrite[];
+    /**
+     * The derived (cascading) updates from the mutation's `derive` effects (issue
+     * #85), flattened across every fragment in declaration order: each an atomic `ADD`
+     * (`UpdateItem`) on a target counter (e.g. `User.postCount += 1`). Present
+     * (non-empty) only when a fragment's lifecycle declares `derive`; absent otherwise
+     * (no regression). Each contributes an `UpdateItem` (`ADD`) to the method's atomic
+     * `TransactWriteItems` and **promotes** the method to a transaction.
+     */
+    readonly derivedUpdates?: readonly DerivedUpdate[];
+    /**
+     * The uniqueness guards derived from the mutation's `unique` effects (issue #86),
+     * flattened across every fragment in declaration order. Present (non-empty) only
+     * when a fragment's lifecycle declares `unique`; absent otherwise (no regression).
+     * Each {@link DerivedUniqueGuard} contributes its marker-row `Put` / `Delete`
+     * item(s) to the method's atomic `TransactWriteItems`, and their presence (like
+     * {@link conditionChecks}) **promotes** an otherwise single-op method to a
+     * transaction so a duplicate scoped value (the guard `Put`'s `attribute_not_exists`
+     * failing) rolls the WHOLE write back — the entity is never created.
+     */
+    readonly uniqueGuards?: readonly DerivedUniqueGuard[];
+    /**
+     * The outbox events derived from the mutation's `emits` effects (issue #87),
+     * flattened across every fragment in declaration order. Present (non-empty) only
+     * when a fragment's lifecycle declares `emits`; absent otherwise (no regression).
+     * Each {@link DerivedOutboxEvent} contributes its transactional-outbox `Put` to the
+     * method's atomic `TransactWriteItems` — recording the event ATOMICALLY with the
+     * entity write (event and state cannot diverge) — and their presence (like
+     * {@link conditionChecks}) **promotes** an otherwise single-op method to a
+     * transaction. The outbox row is drainable via `src/cdc/`; delivery is out of scope.
+     */
+    readonly outboxEvents?: readonly DerivedOutboxEvent[];
+    /**
+     * The client-token idempotency guard derived from the mutation's `idempotency`
+     * effect (issue #87). Present only when a fragment's lifecycle declares
+     * `idempotency`; absent otherwise (no regression). The {@link DerivedIdempotencyGuard}
+     * contributes its `attribute_not_exists` guard `Put` to the method's atomic
+     * `TransactWriteItems`, and its presence (like {@link conditionChecks}) **promotes**
+     * an otherwise single-op method to a transaction so a same-token re-execution fails
+     * the guard and rolls the WHOLE write back — no effect is double-applied.
+     */
+    readonly idempotencyGuard?: DerivedIdempotencyGuard;
+    /** @internal Phantom carrier retaining the formal `CommandMethod` type. */
+    readonly __signature?: CommandMethod<TKey, TParams, TResult>;
+}
+/**
+ * A resolved **QueryModel** — a keyed public read contract holding one or more
+ * named query methods. The Key (`TKey`) is the access pattern; each entry of
+ * `methods` is a use case. Carries the contract `kind` and the resolved per-method
+ * IR; the source method closures are discarded.
+ *
+ * @typeParam TKey - The contract Key (the access pattern / join key).
+ * @typeParam M    - The method map (name → resolved {@link QueryMethodSpec}).
+ */
+interface QueryModelContract<TKey, M extends Record<string, QueryMethodSpec<TKey, any, any>>> {
+    /** @internal Marks this object as a contract IR node. */
+    readonly __isContract: true;
+    /** Discriminant: a read contract. */
+    readonly kind: 'query';
+    /** The resolved, named query methods (use cases over the same Key). */
+    readonly methods: M;
+    /** @internal Phantom carrier retaining the contract Key type `TKey`. */
+    readonly __keyType?: (value: TKey) => void;
+}
+/**
+ * A resolved **CommandModel** — the write counterpart of {@link QueryModelContract},
+ * completely symmetric: keyed, holding one or more named write-use-case methods.
+ *
+ * @typeParam TKey - The contract Key (the target identity).
+ * @typeParam M    - The method map (name → resolved {@link CommandMethodSpec}).
+ */
+interface CommandModelContract<TKey, M extends Record<string, CommandMethodSpec<TKey, any, any>>> {
+    /** @internal Marks this object as a contract IR node. */
+    readonly __isContract: true;
+    /** Discriminant: a write contract. */
+    readonly kind: 'command';
+    /** The resolved, named command methods (write use cases over the same Key). */
+    readonly methods: M;
+    /** @internal Phantom carrier retaining the contract Key type `TKey`. */
+    readonly __keyType?: (value: TKey) => void;
+}
+/** Runtime guard: is `value` a {@link QueryModelContract}? */
+declare function isQueryModelContract(value: unknown): value is QueryModelContract<unknown, Record<string, QueryMethodSpec<unknown, unknown, unknown>>>;
+/** Runtime guard: is `value` a {@link CommandModelContract}? */
+declare function isCommandModelContract(value: unknown): value is CommandModelContract<unknown, Record<string, CommandMethodSpec<unknown, unknown, unknown>>>;
+/** The entity type a descriptor {@link ModelRef} (model class / `.asModel()` / thunk) targets. */
+type EntityOfRef<M> = M extends ModelStatic<infer T, infer _C> ? T : M extends abstract new (...args: never[]) => infer T ? T : M extends () => infer R ? EntityOfRef<R> : unknown;
+/** The projected item type for an entity `T` and a select `S` (relation-nest aware). */
+type QueryResultFor$1<T, S> = T extends DDBModel ? S extends Record<string, unknown> ? QueryResult<T, ProjectionOf<T, S>> : Record<string, unknown> : Record<string, unknown>;
+/** The TS value type a descriptor leaf (`param.*` or a literal) represents. */
+type LeafValueOf<L> = L extends Param<infer V> ? V : L;
+/** The contract Key inferred from a descriptor `key` record (its `param.*` / literal leaves). */
+type KeyOf<KeyRec> = {
+    readonly [F in keyof KeyRec]: LeafValueOf<KeyRec[F]>;
+};
+/** The params a descriptor method accepts: the union of its `key` + `input` leaf value types. */
+type DescriptorParamsOf<D> = (D extends {
+    readonly key: infer K;
+} ? KeyOf<K> : Record<never, never>) & (D extends {
+    readonly input: infer I;
+} ? {
+    readonly [F in keyof I]: LeafValueOf<I[F]>;
+} : Record<never, never>);
+/** The result of a read descriptor: a projected item (`query` → item | null, `list` → connection). */
+type ReadDescriptorResultOf<D> = D extends {
+    readonly query: infer M;
+    readonly select: infer S;
+} ? QueryResultFor$1<EntityOfRef<M>, S> | null : D extends {
+    readonly list: infer M;
+    readonly select: infer S;
+} ? {
+    items: QueryResultFor$1<EntityOfRef<M>, S>[];
+    cursor: string | null;
+} : unknown;
+/** A read descriptor's contract Key (from its `key` record). */
+type ReadDescriptorKeyOf<D> = D extends {
+    readonly key: infer K;
+} ? KeyOf<K> : unknown;
+/** The result of a write descriptor: the read-back projection (when `result.select`) or void. */
+type WriteDescriptorResultOf<D> = D extends {
+    readonly result: {
+        readonly select: infer S;
+    };
+} ? S extends Record<string, unknown> ? Readonly<Record<Extract<keyof S, string>, unknown>> | null : void : void;
+/** A write descriptor's contract Key (from its `key` record). */
+type WriteDescriptorKeyOf<D> = D extends {
+    readonly key: infer K;
+} ? KeyOf<K> : unknown;
+/**
+ * The query-method map accepted by the #101 **direct** form
+ * (`publicQueryModel({ get: descriptor, … })`): each value is a
+ * {@link PublicReadDescriptor}. The contract Key and per-method result are inferred
+ * from each descriptor's `key` / `select`.
+ */
+type ReadDescriptorMap = Record<string, PublicReadDescriptor>;
+/** Resolve a read-descriptor map to its {@link QueryModelContract}. */
+type ResolvedReadDescriptors<M extends ReadDescriptorMap> = QueryModelContract<M[keyof M] extends infer D ? ReadDescriptorKeyOf<D> : unknown, {
+    readonly [K in keyof M]: QueryMethodSpec<ReadDescriptorKeyOf<M[K]>, DescriptorParamsOf<M[K]>, ReadDescriptorResultOf<M[K]>>;
+}>;
+/**
+ * The command-method map accepted by the #101 **direct** form
+ * (`publicCommandModel({ create: descriptor, … })`): each value is a
+ * {@link PublicWriteDescriptor}, a {@link PublicComposeDescriptor} (a `mutation()`
+ * wrapped with `input` / `result` / `mode`), or a bare composite `mutation()`
+ * {@link CommandPlan}.
+ */
+type WriteDescriptorMap = Record<string, PublicWriteDescriptor | PublicComposeDescriptor | CommandPlan>;
+/** Resolve a write-descriptor map to its {@link CommandModelContract}. */
+type ResolvedWriteDescriptors<M extends WriteDescriptorMap> = CommandModelContract<M[keyof M] extends infer D ? WriteDescriptorKeyOf<D> : unknown, {
+    readonly [K in keyof M]: CommandMethodSpec<WriteDescriptorKeyOf<M[K]>, DescriptorParamsOf<M[K]>, WriteDescriptorResultOf<M[K]>>;
+}>;
+/**
+ * Create a **QueryModel** from a **descriptor map** (issue #101, the only form):
+ *
+ * ```ts
+ * export const UserQueries = publicQueryModel({
+ *   get:  { query: User,            key: { userId: param.string() },  select: { name: true } },
+ *   list: { list:  GroupMembership, key: { groupId: param.string() }, select: { role: true } },
+ * });
+ * ```
+ *
+ * The single argument is the method map itself; the contract Key and each method's
+ * result type are **inferred** from the descriptors' `key` / `select` — there is no
+ * generic key parameter, no curried factory call, and no explicit Key-field list
+ * (the legacy `publicQueryModel<TKey>(['email'])` / model-derived overloads were
+ * withdrawn in #101). A GSI-keyed point read is expressed by its descriptor `key`
+ * (e.g. `key: { email: param.string() }`); the build resolves the access pattern
+ * from the model metadata, exactly as the curried key-field list once did. Each
+ * descriptor's `key` fields carry `param.*` placeholders (the public input schema);
+ * a `select` is the existing query projection (relation-nest aware), and may carry
+ * External Query `query(...)` nodes.
+ */
+declare function publicQueryModel<const M extends ReadDescriptorMap>(methods: M): ResolvedReadDescriptors<M>;
+/**
+ * Create a **CommandModel** from a **descriptor map** (issue #101, the only form):
+ *
+ * ```ts
+ * export const MembershipCommands = publicCommandModel({
+ *   create: { create: GroupMembership, key: { groupId: param.string(), userId: param.string() },
+ *             input: { role: param.string() }, result: { select: { role: true } } },
+ *   addMany: { create: GroupMembership, key: { … }, input: { … }, mode: 'parallel' },
+ *   join: mutation($ => ({ … })),   // composite (multi-fragment, atomic) method
+ * });
+ * ```
+ *
+ * The single argument is the method map itself; the contract Key and each method's
+ * read-back result are **inferred** from the descriptors' `key` / `result.select` —
+ * there is no generic key parameter, no curried factory call, and no explicit
+ * Key-field list (the legacy `publicCommandModel<TKey>()` / model-derived overloads
+ * were withdrawn in #101). A descriptor's `mode` declares the per-call execution
+ * mode (`'transaction'` default | `'parallel'`); `result` presence drives whether
+ * the method reads back and returns the written entity.
+ */
+declare function publicCommandModel<const M extends WriteDescriptorMap>(methods: M): ResolvedWriteDescriptors<M>;
+declare const PLANNED_COMMAND_BRAND: unique symbol;
+/**
+ * The input param shape a {@link command} declares: a record of named
+ * {@link Param} placeholders (`param.string()` / `param.number()` /
+ * `param.literal(...)`). These are the **external** params of the public Command
+ * IF — the method's caller-supplied input. The mutation fragment binds them by
+ * name into the written entity (`$.<field>`), so each input field name must match
+ * a fragment `$.field` reference / a model field the fragment writes.
+ */
+type CommandInputShape = Readonly<Record<string, Param<unknown>>>;
+/**
+ * The return projection a {@link command} declares (proposal §3: "return = read
+ * projection"): a JSON-safe boolean field map applied to the written entity as a
+ * **consistent read-back** after the write commits. Omit for a fire-and-forget
+ * command (no projected item is returned).
+ */
+type CommandSelectShape = Readonly<Record<string, boolean>>;
+/**
+ * A **planned command method** (#83): the branded result of
+ * `command({ input, select }).plan(mutation)`. It carries the captured fragment
+ * IR (the {@link CommandPlan}), the public input param shape, and the return
+ * `select`. {@link buildCommandContract} detects the brand and routes it to the
+ * single-fragment mutation compiler (NOT through #64's closure path).
+ *
+ * The external surface is **params in / result out only** — the internal mutation
+ * document is never exposed.
+ *
+ * @typeParam TInput  - The input param shape (`{ field: Param<…> }`).
+ * @typeParam TSelect - The return projection (`{ field: boolean }`), or `undefined`.
+ */
+interface PlannedCommandMethod<TInput extends CommandInputShape = CommandInputShape, TSelect extends CommandSelectShape | undefined = CommandSelectShape | undefined> {
+    readonly [PLANNED_COMMAND_BRAND]: true;
+    /** The captured mutation IR (the fragment list). */
+    readonly plan: CommandPlan;
+    /** The public input param shape. */
+    readonly input: TInput;
+    /** The return projection (consistent read-back), or `undefined`. */
+    readonly select: TSelect;
+}
+/** Runtime guard: is `value` a {@link PlannedCommandMethod} (#83)? */
+declare function isPlannedCommandMethod(value: unknown): value is PlannedCommandMethod;
+/** The per-call execution mode of a command method (#101): replaces `batch`. */
+type CommandMode = 'transaction' | 'parallel';
+/** A public **read** descriptor (issue #101): `{ query | list: Model, key, select, options? }`. */
+interface PublicReadDescriptor {
+    readonly query?: ModelRef;
+    readonly list?: ModelRef;
+    readonly key: Readonly<Record<string, unknown>>;
+    readonly select: Readonly<Record<string, unknown>>;
+    readonly options?: Readonly<Record<string, unknown>>;
+}
+/** A public **write** descriptor (issue #101): `{ create | update | remove: Model, key, input?, condition?, result?, mode? }`. */
+interface PublicWriteDescriptor {
+    readonly create?: ModelRef;
+    readonly update?: ModelRef;
+    readonly remove?: ModelRef;
+    readonly key: Readonly<Record<string, unknown>>;
+    readonly input?: Readonly<Record<string, unknown>>;
+    readonly condition?: Readonly<Record<string, unknown>>;
+    readonly result?: {
+        readonly select?: Readonly<Record<string, boolean>>;
+        readonly options?: unknown;
+    };
+    readonly mode?: CommandMode;
+}
+/**
+ * A public **composite write** descriptor (issue #101) — the closure-free twin of
+ * `command({ input, select }).plan(mutation)`. It wraps an internal
+ * {@link CommandPlan} (`mutation(...)` / `definePlan(...)`) with the public input
+ * param shape, the optional read-back projection, and the optional execution mode.
+ * The mutation document is never exposed; only `input` params + `result.select`
+ * cross the boundary.
+ */
+interface PublicComposeDescriptor {
+    readonly command: CommandPlan;
+    readonly input?: Readonly<Record<string, unknown>>;
+    readonly result?: {
+        readonly select?: Readonly<Record<string, boolean>>;
+        readonly options?: unknown;
+    };
+    readonly mode?: CommandMode;
+}
+
+/**
+ * Single-service contract **Runtime** — execution of CQRS query-contract methods
+ * (issue #62, Epic #57; spec `docs/cqrs-contract.md`, "Query Method
+ * — Common Interface" + "Cardinality matrix"). READS only; command/write
+ * execution is #64 and single-contract composition / External Query is #63 — both
+ * out of scope here.
+ *
+ * The Runtime is the **execution engine**: given a resolved query contract (a
+ * {@link QueryModelContract} from #58, carrying per-method `resolution` /
+ * `inputArity` and a resolved {@link ContractMethodOp}) it executes one method
+ * for a single key **or** an array of keys and returns the correct result shape
+ * from the proposal's cardinality matrix:
+ *
+ * | Input          | `resolution` | Result shape                          | Notation         |
+ * | -------------- | ------------ | ------------------------------------- | ---------------- |
+ * | `key` (single) | `point`      | `Item \| null`                        | `key1 : result1` |
+ * | `key` (single) | `range`      | `Connection` (`{ items, cursor }`)    | `key1 : resultM` |
+ * | `keys[]` (N)   | `point`      | keyed `Map<keyId, Item \| null>`      | `keyN : resultN` |
+ * | `keys[]` (N)   | `range`      | **unreachable for a single contract** | `keyN : resultN×M` |
+ *
+ * ## On `keyN : resultN×M` (range + array) — unreachable here, by design
+ *
+ * The fourth matrix cell — a keyed map of connections — is **not reachable for a
+ * single contract** at the direct-call surface. The proposal's N+1 Safety rule
+ * fixes a `range` method's `inputArity` to `'single'` ("A `range` method is
+ * necessarily `'single'`"; "feeding an array of keys into a range method … is an
+ * N+1 fan-out and is rejected at build time, with no opt-in escape hatch"). #58's
+ * {@link inputArityOf} derives exactly that, and #60's N+1 checker rejects any
+ * contract that violates it before it reaches the SSoT. So a range method only
+ * ever accepts one key, and this runtime **rejects** an array fed into a `range`
+ * method ({@link executeQueryMethod}) rather than fanning out. `keyN : resultN×M`
+ * arises only under cross-contract composition (a `point` parent referencing a
+ * child whose per-key result is a connection) — that is #63's External Query
+ * territory, explicitly out of scope for #62. We therefore implement the **three
+ * reachable shapes** and guard the fourth with a clear error, rather than
+ * silently fanning out a forbidden N+1.
+ *
+ * ## Reuse, not reinvention
+ *
+ * Execution delegates to the proven machinery:
+ *
+ * - `point` single  → {@link executeQuery} (GetItem / unique Query).
+ * - `point` array   → {@link executeKeyedBatchGet} below, which reuses the
+ *   `batch-retry` primitives (chunk ≤100, dedup, UnprocessedKeys retry) and
+ *   builds the **keyed** map (BatchGet neither preserves order nor returns absent
+ *   keys, so missing keys are filled with explicit `null`).
+ * - `range` single  → {@link executeListInternal} for a `{ items, cursor }`
+ *   connection, with the cursor wrapped in a per-key envelope
+ *   ({@link encodePerKeyCursor}) so it carries the key it belongs to.
+ *
+ * The result-shape typing (single → bare, array → keyed) is expressed as call
+ * overloads on {@link executeQueryMethod}.
+ */
+
+/**
+ * The **structural** shape of a resolved query contract the runtime executes.
+ * It depends only on the facts the executor reads — the `query` discriminant and
+ * the per-method `resolution` and internal `op` — and is deliberately
+ * **independent of the phantom Key / params / result types** carried by
+ * {@link QueryModelContract}. Those phantom types are invariant /
+ * contravariant on the full interface, so a concrete `QueryModelContract<{…}>`
+ * is not assignable to `QueryModelContract<unknown, …>`; this minimal structural
+ * type sidesteps that variance while accepting every real contract (a
+ * {@link QueryModelContract} is structurally assignable to it). The runtime never
+ * needs the method param / result types — it returns the dynamic
+ * cardinality-matrix shapes ({@link ContractItem} / {@link Connection} /
+ * {@link KeyedResult}).
+ */
+interface ExecutableQueryContract {
+    readonly kind: 'query';
+    readonly methods: Readonly<Record<string, {
+        readonly resolution: Resolution;
+        /**
+         * The method's decided input arity (issue #71): `'either'` for a
+         * coalescible base-table `point` (a key array → one `BatchGetItem`),
+         * `'single'` for a `range` (partition `Query`) **or** a unique-GSI `point`
+         * (a per-key GSI `Query`, not coalescible). The executor honors it to
+         * reject an array fed into any `'single'` method rather than fanning out.
+         */
+        readonly inputArity: InputArity;
+        readonly op: ContractMethodOp;
+    }>>;
+}
+/** A plain contract key (the access pattern / join key), e.g. `{ articleId }`. */
+type ContractKeyInput = Record<string, unknown>;
+/**
+ * The literal {@link InputArity} the contract `C` carries for method `K`. A
+ * {@link QueryMethodSpec} carries the method's literal arity in its `inputArity`
+ * type when the body was tagged with `point` / `range` (`src/define/contract.ts`);
+ * an untagged method keeps the wide `InputArity`. Falls back to `InputArity` for a
+ * structurally-typed contract (e.g. the bare {@link ExecutableQueryContract}),
+ * which keeps the call surface array-capable (the runtime backstop still rejects an
+ * array fed into a `'single'` method).
+ */
+type ArityOfMethod<C extends ExecutableQueryContract, K extends keyof C['methods']> = C['methods'][K] extends {
+    readonly inputArity: infer A extends InputArity;
+} ? A : InputArity;
+/**
+ * The **array** key-argument type accepted by `executeQueryMethod` for method `K`
+ * of contract `C`. A method whose literal arity is `'single'` (a `range` read **or**
+ * a unique-GSI `point` — both one request per key) accepts **no** array: the type
+ * collapses to `never`, so passing an array is a `tsc` compile error at the
+ * user-facing surface (issue #71, N+1 rule (a), the **primary** enforcement layer).
+ * Any other arity (`'either'` / `'array'`, or the wide `InputArity` for an untagged
+ * / structural contract) accepts an array of keys (it coalesces to one batched
+ * call). This is the array-overload half of {@link ContractCallSignature}'s
+ * narrowing, applied at the real execution surface.
+ */
+type ArrayKeyArg<C extends ExecutableQueryContract, K extends keyof C['methods']> = ArityOfMethod<C, K> extends 'single' ? never : readonly ContractKeyInput[];
+/** A single hydrated result item (only the method's projected fields). */
+type ContractItem = Record<string, unknown>;
+/**
+ * A pagination connection: a page of items plus an opaque `cursor` for the next
+ * page (`null` when the page is the last). For a `range` contract method the
+ * cursor is a **per-key envelope** ({@link encodePerKeyCursor}) that identifies
+ * the key it paginates.
+ */
+interface Connection<TItem = ContractItem> {
+    readonly items: TItem[];
+    readonly cursor: string | null;
+}
+/**
+ * The keyed result of a batched contract read: input-key identity (the canonical
+ * {@link serializeContractKey} string) → per-key result. Backed by a `Map` so
+ * the association is explicit and order-independent; missing keys are present
+ * with an explicit `null` value (`point`) rather than omitted.
+ *
+ * @typeParam TValue The per-key value (`Item | null` for `point`).
+ */
+type KeyedResult<TValue> = Map<string, TValue>;
+/**
+ * Retrieval options accepted by a contract query method (the serializable subset
+ * from the proposal). All optional; a `point` method ignores the pagination
+ * fields, a `range` method honors them.
+ */
+interface ContractQueryParams {
+    /** Strongly-consistent read (point reads on the base table only). */
+    readonly consistentRead?: boolean;
+    /** Page size for a `range` (`list`) method. */
+    readonly limit?: number;
+    /** Resume token — a per-key cursor envelope from a prior `range` page. */
+    readonly after?: string;
+    /** Sort direction for a `range` (`list`) method. */
+    readonly order?: 'ASC' | 'DESC';
+}
+/**
+ * Maximum number of in-flight per-key queries for a batched `range` fan-out.
+ * Reuses the relation-traversal cap — the same rationale (bound in-flight
+ * requests, ride out throttling via UnprocessedKeys retry beneath the cap). Note
+ * that a single-contract `range` method is `inputArity: 'single'`, so the
+ * fan-out path is only exercised by the (out-of-scope, #63) composition runtime;
+ * the bound is defined here so the seam is ready and tested in isolation.
+ */
+declare const CONTRACT_RANGE_FANOUT_CONCURRENCY = 16;
+/**
+ * Keyed BatchGet: resolve `keys` against `modelClass` in one batched call and
+ * return a `Map<keyId, Item | null>` with every input key present (misses →
+ * `null`). Reuses the `batch-retry` primitives (chunk ≤100, dedup, UnprocessedKeys
+ * retry) — never reinvented.
+ *
+ * Implementation notes:
+ *  - **Dedup**: the same key supplied twice is fetched once; both map entries
+ *    point at the same resolved item (or `null`).
+ *  - **Order / absence**: BatchGet returns matched items unordered and omits
+ *    misses, so each returned raw item is indexed by its `PK::SK` and looked up
+ *    per input key; an unmatched key gets `null`.
+ *  - **Projection**: items are fetched whole (DynamoDB BatchGet has no reliable
+ *    server-side projection for mixed keys here) and hydrated against the
+ *    method's `select`, so the per-key item carries exactly the projected fields.
+ */
+declare function executeKeyedBatchGet(modelClass: Function, keys: readonly ContractKeyInput[], select: Record<string, unknown>): Promise<KeyedResult<ContractItem | null>>;
+/**
+ * Execute a query-contract method for a **single** key.
+ *
+ * The result shape is determined by the method's derived `resolution`:
+ *  - `point` → `Item | null` (`key1 : result1`);
+ *  - `range` → `Connection` (`key1 : resultM`).
+ *
+ * A single key is accepted for **every** method regardless of arity.
+ *
+ * @param contract The resolved query contract (a {@link QueryModelContract}).
+ * @param methodName The method to execute (a method name of `contract`).
+ * @param key A single contract key.
+ * @param params Retrieval options (pagination / consistency).
+ */
+declare function executeQueryMethod<C extends ExecutableQueryContract, K extends keyof C['methods'] & string>(contract: C, methodName: K, key: ContractKeyInput, params?: ContractQueryParams): Promise<ContractItem | null | Connection>;
+/**
+ * Execute a query-contract method for an **array** of keys (a single batched
+ * call). Valid **only** for a method whose literal arity is not `'single'` — a
+ * coalescible base-table `point` (`inputArity: 'either'`, a key array → one
+ * `BatchGetItem`). A `'single'` method (a `range` read **or** a unique-GSI `point`)
+ * makes the array key argument `never`, so passing an array is a **`tsc` compile
+ * error** by construction (issue #71, N+1 rule (a) — the primary enforcement
+ * layer; the build-time checker and runtime backstop remain). The result is a keyed
+ * `Map<keyId, Item | null>` (`keyN : resultN`).
+ *
+ * @param contract The resolved query contract.
+ * @param methodName The method to execute (a method name of `contract`).
+ * @param keys An array of contract keys (rejected for a `'single'` method).
+ * @param params Retrieval options.
+ */
+declare function executeQueryMethod<C extends ExecutableQueryContract, K extends keyof C['methods'] & string>(contract: C, methodName: K, keys: ArrayKeyArg<C, K>, params?: ContractQueryParams): Promise<KeyedResult<ContractItem | null>>;
+/**
+ * The runtime fan-out seam for a batched `range` (`keyN : resultN×M`). NOT
+ * reachable for a single contract under #62 (a `range` method's `inputArity` is
+ * `'single'`, so {@link executeQueryMethod} rejects an array). It is the
+ * cross-contract composition runtime (#63) that drives a per-key range fan-out;
+ * this function implements that fan-out — N bounded-parallel Queries grouped by
+ * input key, each connection carrying its own per-key cursor — so the seam is
+ * defined, reused (via {@link mapWithConcurrency}), and unit-tested in isolation
+ * ahead of #63, rather than left as a stub. #62 does not call it on any contract
+ * surface.
+ *
+ * @param op     The `range` method op to run per key.
+ * @param keys   The parent keys to fan out over.
+ * @param params Retrieval options applied to **every** key's connection.
+ */
+declare function executeRangeFanout(op: ContractMethodOp, keys: readonly ContractKeyInput[], params?: ContractQueryParams): Promise<KeyedResult<Connection>>;
+
+/**
+ * Single-service contract **Runtime** — execution of CQRS command-contract
+ * methods (issue #64, Epic #57; spec `docs/cqrs-contract.md`,
+ * "Command Contract" + "Command Definition"). WRITES only; query reads are #62
+ * ({@link executeQueryMethod}) and cross-contract composition is #63 — both out
+ * of scope here.
+ *
+ * Given a resolved command contract (a {@link CommandModelContract} from #58,
+ * carrying per-method `result` and the declared {@link CommandBatchMode}, plus a
+ * resolved write {@link ContractMethodOp}) it executes one method for a **single
+ * key** or an **array of keys** and applies the write(s) to DynamoDB:
+ *
+ * | Input          | resolution                                                  |
+ * | -------------- | ----------------------------------------------------------- |
+ * | `key` (single) | one write op (`put` / `update` / `delete`)                  |
+ * | `keys[]` (N)   | a **batched** write per the method's declared `batch` mode  |
+ *
+ * The batched form is **declared by the contract** (proposal "Consistency with
+ * the existing write surface"):
+ *
+ * - `'transact'` — one `TransactWriteItems`: the per-key write applied
+ *   **atomically** (all-or-nothing) and **condition-capable** ({@link ConditionInput},
+ *   `{ notExists }` / equality). DynamoDB caps `TransactWriteItems` at **25** and
+ *   the call is atomic, so an array of **>25 keys cannot be split** without
+ *   breaking atomicity — this runtime **rejects** it with a clear error rather
+ *   than silently truncating or chunking ({@link MAX_TRANSACT_ITEMS}).
+ * - `'batchWrite'` — a `BatchWriteItem`: the per-key writes applied
+ *   **non-atomically**, **without conditions** (DynamoDB's `BatchWriteItem` has no
+ *   `ConditionExpression`). An array of any size is permitted; it is chunked per
+ *   the 25-items-per-request limit with `UnprocessedItems` retry, reusing the
+ *   existing batch machinery ({@link executeBatchWrite}).
+ * - **undefined** — the method declared no batched form: an array is rejected (it
+ *   resolves only a single key).
+ *
+ * ## Reuse, not reinvention
+ *
+ * The recorded write op carries declarative sentinels ({@link ContractParamRef} /
+ * {@link ContractKeyFieldRef}) at its value positions; {@link renderRecord} binds
+ * them to the concrete `(key, params)` at execution time, producing the very same
+ * `item` / `changes` / `key` / `condition` objects a hand-written `Model.putItem` /
+ * `Model.updateItem` / `Model.deleteItem` would pass. Execution then delegates to the
+ * proven write machinery:
+ *
+ * - single  → {@link executePut} / {@link executeUpdate} / {@link executeDelete};
+ * - transact → one `TransactWriteItems` built from `buildPutInput` /
+ *   `buildUpdateInput` / `buildDeleteInput` (the same inputs the imperative
+ *   {@link TransactionContext} uses), with the ≤25 limit enforced;
+ * - batchWrite → {@link executeBatchWrite} (chunk ≤25, `UnprocessedItems` retry).
+ *
+ * The TS and Python runtimes produce identical effects for the same SSoT.
+ */
+
+/**
+ * The **structural** shape of a resolved command contract the runtime executes.
+ * It depends only on the facts the executor reads — the `command` discriminant
+ * and the per-method `op` / `batch` / `result` — and is deliberately
+ * **independent of the phantom Key / params / result types** carried by
+ * {@link CommandModelContract} (those are invariant on the full interface, so a
+ * concrete `CommandModelContract<{…}>` is not assignable to
+ * `CommandModelContract<unknown, …>`). Every real command contract is
+ * structurally assignable to this minimal type.
+ */
+interface ExecutableCommandContract {
+    readonly kind: 'command';
+    readonly methods: Readonly<Record<string, {
+        readonly op: ContractMethodOp;
+        readonly result: CommandResultKind;
+        /**
+         * The #101 first-class per-call execution mode (`'transaction'` |
+         * `'parallel'`). Drives the key-array bulk form directly (`'transaction'`
+         * → atomic `TransactWriteItems`; `'parallel'` → non-atomic per-key fan-out
+         * with partial success, coalescing unconditioned put/delete into a
+         * `BatchWriteItem`).
+         */
+        readonly mode?: CommandMode;
+        /**
+         * The composed write ops of a **multi-fragment** `mutation`-derived method
+         * (issue #90). When present (N≥2), a **single-key** call executes ALL of
+         * them as **one atomic `TransactWriteItems`** (not sequential writes), so a
+         * condition failure on any fragment rolls back the whole transaction. Absent
+         * for a single-fragment / #83 / hand-written #64 method (which executes its
+         * one {@link op}). The read-back stays keyed on the primary op ({@link op}).
+         */
+        readonly ops?: readonly ContractMethodOp[];
+        /**
+         * The referential-integrity assertions derived from the mutation's
+         * `requires` effects (issue #84). When present (non-empty), a
+         * **single-key** call composes the base write(s) **and** one read-only
+         * `ConditionCheck` (`attribute_exists`) per assertion into **one atomic
+         * `TransactWriteItems`** — so a single-op write is **promoted** to a
+         * transaction. If any referenced entity is absent, its assertion fails and
+         * the WHOLE transaction rolls back (the entity write never persists). Absent
+         * on a mutation with no `requires` / a #64 hand-written method.
+         */
+        readonly conditionChecks?: readonly DerivedConditionCheck[];
+        /**
+         * The adjacency edge writes derived from the mutation's `edges` effects
+         * (issue #85). When present, a **single-key** call composes each edge's
+         * adjacency `Put` / `Delete` item(s) into the **same atomic
+         * `TransactWriteItems`** as the entity write (and any ConditionChecks /
+         * derived updates), so the edge is created / removed / moved atomically with
+         * the entity. Absent on a mutation with no `edges` / a #64 hand-written method.
+         */
+        readonly edgeWrites?: readonly DerivedEdgeWrite[];
+        /**
+         * The derived counter updates from the mutation's `derive` effects (issue
+         * #85): each an atomic `ADD` (`UpdateItem`) on a target counter (e.g.
+         * `User.postCount += 1`). When present, a **single-key** call composes each
+         * `ADD` into the same atomic `TransactWriteItems` as the entity write, so the
+         * counter moves atomically (and never clobbers a concurrent increment — an
+         * `ADD` needs no prior read). Absent on a mutation with no `derive`.
+         */
+        readonly derivedUpdates?: readonly DerivedUpdate[];
+        /**
+         * The uniqueness guards derived from the mutation's `unique` effects (issue
+         * #86): each a marker-row `Put` (`attribute_not_exists`) / `Delete` /
+         * `Delete(old)+Put(new)` swap. When present, a **single-key** call composes
+         * the guard item(s) into the same atomic `TransactWriteItems` as the entity
+         * write, so a duplicate scoped value (the guard `Put`'s `attribute_not_exists`
+         * failing) rolls the WHOLE transaction back — the entity is never created.
+         * Absent on a mutation with no `unique` / a #64 hand-written method.
+         */
+        readonly uniqueGuards?: readonly DerivedUniqueGuard[];
+        /**
+         * The outbox events derived from the mutation's `emits` effects (issue #87):
+         * each a transactional-outbox `Put`. When present, a **single-key** call
+         * composes each event's `Put` into the same atomic `TransactWriteItems` as the
+         * entity write, so the event RECORD is written ATOMICALLY with the state it
+         * announces (they can never diverge). The row is drainable from real
+         * DynamoDB Streams (captured at the table layer regardless of code path);
+         * delivery / handlers are OUT of scope. Since #94 the derived-command
+         * transaction also feeds every committed item (including this outbox `Put`)
+         * into the in-process `ChangeCaptureRegistry` seam, so the dev/test
+         * `src/cdc/` emulator now observes this path too — production Streams and the
+         * emulator agree. Absent on a mutation with no `emits`.
+         */
+        readonly outboxEvents?: readonly DerivedOutboxEvent[];
+        /**
+         * The client-token idempotency guard derived from the mutation's `idempotency`
+         * effect (issue #87): a marker-row `Put` (`attribute_not_exists`). When present,
+         * a **single-key** call composes the guard `Put` into the same atomic
+         * `TransactWriteItems` as the entity write, so a same-token re-execution fails
+         * the guard and rolls the WHOLE transaction back — no effect is double-applied.
+         * Absent on a mutation with no `idempotency` / a #64 hand-written method.
+         */
+        readonly idempotencyGuard?: DerivedIdempotencyGuard;
+        /**
+         * The return projection of a `mutation`-derived method (issue #83). When
+         * present, a **single-key** call performs the write then issues a
+         * **consistent read-back** (`GetItem` with `ConsistentRead`) of the
+         * written entity's primary key and returns the projected item via the
+         * existing read-projection machinery. Absent on a #64 hand-written method.
+         */
+        readonly returnSelection?: Readonly<Record<string, boolean>>;
+    }>>;
+}
+/** The params a command method consumes (the body's `params` argument). */
+type ContractCommandParams = Record<string, unknown>;
+/**
+ * The projected read-back item a `mutation`-derived command method returns, or
+ * `null` when the written row was absent at read-back (e.g. a `remove`). A plain
+ * record of the projected fields.
+ */
+type CommandReturn = Record<string, unknown> | null;
+/**
+ * #101 Phase 3 — the per-op outcome of a `mode: 'parallel'` key-array bulk write.
+ * A non-atomic fan-out reports each key's result independently: `{ ok: true }` on
+ * success, `{ ok: false, error }` on a per-op failure (a failed condition / a
+ * `BatchWriteItem` item that stayed unprocessed after retry). The array index
+ * matches the input key index, and a per-op failure NEVER aborts the others.
+ */
+interface ParallelOpResult$1 {
+    readonly ok: boolean;
+    readonly error?: string;
+}
+/** The partial-success return of a `mode: 'parallel'` key-array bulk write (#101). */
+interface CommandParallelReturn {
+    readonly results: readonly ParallelOpResult$1[];
+}
+/**
+ * Execute a command-contract method for a **single** key — one write op
+ * (`put` / `update` / `delete`).
+ *
+ * @param contract   The resolved command contract (a {@link CommandModelContract}).
+ * @param methodName The method to execute.
+ * @param key        A single contract key (the mutation target).
+ * @param params     The mutation params (the body's `params` argument).
+ */
+declare function executeCommandMethod(contract: ExecutableCommandContract, methodName: string, key: ContractKeyInput, params?: ContractCommandParams): Promise<void | CommandReturn>;
+/**
+ * Execute a command-contract method for an **array** of keys — a batched write
+ * per the method's declared {@link CommandBatchMode}:
+ *
+ * - `'transact'` → one atomic `TransactWriteItems` (≤25, condition-capable); a
+ *   >25-key array is **rejected** (an atomic transaction cannot be split).
+ * - `'batchWrite'` → a `BatchWriteItem` (no conditions; chunked ≤25 with
+ *   `UnprocessedItems` retry).
+ *
+ * A method that declared no batched form rejects an array with a clear error.
+ *
+ * @param contract   The resolved command contract.
+ * @param methodName The method to execute.
+ * @param keys       An array of contract keys.
+ * @param params     The mutation params shared across every key.
+ */
+declare function executeCommandMethod(contract: ExecutableCommandContract, methodName: string, keys: readonly ContractKeyInput[], params?: ContractCommandParams): Promise<void | CommandParallelReturn>;
+
+/**
+ * The **unified envelope** in-process execution engine (issue #101).
+ *
+ * `DDBModel.query(map)` and `DDBModel.mutate(map, { mode })` are the in-process,
+ * multi-route counterparts of the single primitives `Model.query` /
+ * `Model.putItem|updateItem|deleteItem`, sharing one descriptor shape (alias → descriptor)
+ * with the declarative `mutation(...)` DSL (#108) and the public contract layer.
+ *
+ * - **READ** — `{ alias: { query | list: Model, key, select, options? } }`. Each
+ *   route runs **independently and in parallel** (`Promise.all`): a `query` route
+ *   delegates to {@link executeQuery}, a `list` route to {@link executeList}. The
+ *   nested selection / relation resolution / optimisation under a route is the
+ *   existing read path, reused verbatim. Cross-route consistency is NOT guaranteed
+ *   (each route is its own read).
+ *
+ * - **WRITE** — `{ alias: { create | update | remove: Model, key, input?,
+ *   condition?, result? } }` plus a call-level `{ mode }`:
+ *   - `mode: 'transaction'` (default) — every operation composes into ONE atomic
+ *     `TransactWriteItems` (all-or-nothing); a `condition` failure (or any other)
+ *     rolls the whole set back and the call throws. Over the 25-item cap is an
+ *     error (an atomic transaction is never split).
+ *   - `mode: 'parallel'` — non-atomic. Operations are ordered by their
+ *     cross-fragment data dependencies (`$.alias.field`) into dependency levels;
+ *     within a level they run in parallel. Each operation (by alias) reports
+ *     success / failure **individually** in the returned result object (the call
+ *     does NOT throw on a per-op failure).
+ *
+ * Both write modes funnel through the **same execution core** the public
+ * contract runtime (`executeCommandMethod`) uses — a descriptor is converted into
+ * an anonymous `mutation()` plan, compiled by `compileMutationPlan`, and committed
+ * via the shared command-runtime primitives — so atomicity / conformance is
+ * identical to the public boundary by construction (no second code path).
+ */
+
+/** A read route's options (`query`: consistency/depth; `list`: paging/filter). */
+interface ReadRouteOptions {
+    readonly consistentRead?: boolean;
+    readonly maxDepth?: number;
+    readonly limit?: number;
+    readonly after?: string;
+    readonly order?: 'ASC' | 'DESC';
+    readonly filter?: Record<string, unknown>;
+}
+/** One read route: a `query` (point/unique) or a `list` (partition) descriptor. */
+interface ReadRouteDescriptor {
+    readonly query?: ModelRef;
+    readonly list?: ModelRef;
+    readonly key: Record<string, unknown>;
+    readonly select: Record<string, unknown>;
+    readonly options?: ReadRouteOptions;
+}
+/** The read envelope: alias → {@link ReadRouteDescriptor}. */
+type ReadEnvelope = Record<string, ReadRouteDescriptor>;
+/** The result of a read route — a `query` item (or `null`) or a `list` connection. */
+type ReadRouteResult = Record<string, unknown> | null | {
+    items: Record<string, unknown>[];
+    cursor: string | null;
+};
+/** The write execution mode: atomic transaction (default) or non-atomic parallel. */
+type MutateMode = 'transaction' | 'parallel';
+/** A read-back projection for a write op (the EXISTING query select shape). */
+interface WriteResultProjection {
+    readonly select?: Record<string, unknown>;
+    readonly options?: {
+        readonly consistentRead?: boolean;
+        readonly maxDepth?: number;
+    };
+}
+/** One write descriptor (alias entry) for the in-process `DDBModel.mutate`. */
+interface InProcessWriteDescriptor {
+    readonly create?: ModelRef;
+    readonly update?: ModelRef;
+    readonly remove?: ModelRef;
+    /**
+     * The target's primary-key binding. A single key object applies the op once; an
+     * **array** of key objects (#101 `key: K | K[]`) applies the SAME op to every key
+     * (bulk). Under `transaction` mode a bulk descriptor composes one atomic
+     * `TransactWriteItems` over all keys; under `parallel` mode it runs each key
+     * non-atomically with per-key partial success.
+     */
+    readonly key: Record<string, unknown> | readonly Record<string, unknown>[];
+    readonly input?: Record<string, unknown>;
+    readonly condition?: Record<string, unknown>;
+    readonly result?: WriteResultProjection;
+}
+/** The write envelope: alias → {@link InProcessWriteDescriptor}. */
+type WriteEnvelope = Record<string, InProcessWriteDescriptor>;
+/** Options for {@link executeWriteEnvelope}. */
+interface MutateOptions {
+    readonly mode?: MutateMode;
+}
+/** A per-alias result in `parallel` mode: success carries the read-back, else error. */
+type ParallelOpResult = {
+    readonly ok: true;
+    readonly value: CommandReturn | undefined;
+} | {
+    readonly ok: false;
+    readonly error: Error;
+};
+
+/**
+ * Type-level inference for the unified envelope (issue #101). Maps a read / write
+ * envelope's descriptor map to its alias-keyed result type, deriving each route's
+ * result from its intent discriminator (`query`/`list` ↔ `create`/`update`/`remove`)
+ * and `select` projection — reusing the `Model.query` `ProjectionOf` machinery.
+ */
+
+/** The entity type a {@link ModelStatic} value (or model class) carries. */
+type EntityOf<M> = M extends ModelStatic<infer T, infer _C> ? T : M extends abstract new (...args: never[]) => infer T ? T extends DDBModel ? T : never : unknown;
+/** The result type of one read route, derived from `query` / `list` + `select`. */
+type ReadRouteResultOf<R> = R extends {
+    readonly query: infer M;
+    readonly select: infer S;
+} ? QueryResultFor<EntityOf<M>, S> | null : R extends {
+    readonly list: infer M;
+    readonly select: infer S;
+} ? {
+    items: QueryResultFor<EntityOf<M>, S>[];
+    cursor: string | null;
+} : unknown;
+/** The projected item type for an entity `T` and a select `S` (relation-nest aware). */
+type QueryResultFor<T, S> = T extends DDBModel ? S extends Record<string, unknown> ? QueryResult<T, ProjectionOf<T, S>> : Record<string, unknown> : Record<string, unknown>;
+/** The alias-keyed result of {@link DDBModel.query}. */
+type QueryEnvelopeResult<E extends ReadEnvelope> = {
+    readonly [K in keyof E]: ReadRouteResultOf<E[K]>;
+};
+/** The projected read-back type of one write op (or `undefined` when no `result`). */
+type WriteReadBackOf<W> = W extends {
+    readonly result: {
+        readonly select: infer S;
+    };
+} ? W extends {
+    readonly create: infer M;
+} ? QueryResultFor<EntityOf<M>, S> | null : W extends {
+    readonly update: infer M;
+} ? QueryResultFor<EntityOf<M>, S> | null : W extends {
+    readonly remove: infer M;
+} ? QueryResultFor<EntityOf<M>, S> | null : CommandReturn : undefined;
+/**
+ * #101 `key: K | K[]` — is the descriptor a BULK write (its `key` is an array)?
+ * A bulk alias's result is an ARRAY (aligned to the keys); a single key's is scalar.
+ */
+type IsBulk<W> = W extends {
+    readonly key: readonly unknown[];
+} ? true : false;
+/** Wrap a per-alias result in an array when the descriptor declared a `key` array. */
+type BulkWrap<W, R> = IsBulk<W> extends true ? readonly R[] : R;
+/** The alias-keyed result of {@link DDBModel.mutate} in `transaction` mode. */
+type MutateTransactionResult<E extends WriteEnvelope> = {
+    readonly [K in keyof E as E[K] extends {
+        readonly result: unknown;
+    } ? K : never]: BulkWrap<E[K], WriteReadBackOf<E[K]>>;
+};
+/** A per-alias `parallel`-mode result carrying the typed read-back on success. */
+type ParallelResultOf<W> = {
+    readonly ok: true;
+    readonly value: WriteReadBackOf<W>;
+} | {
+    readonly ok: false;
+    readonly error: Error;
+};
+/** The alias-keyed result of {@link DDBModel.mutate} in `parallel` mode. */
+type MutateParallelResult<E extends WriteEnvelope> = {
+    readonly [K in keyof E]: BulkWrap<E[K], ParallelResultOf<E[K]>>;
+};
+
+declare abstract class DDBModel {
+    /** @internal Type brand — prevents primitives from structurally matching DDBModel. */
+    private readonly __brand;
+    static setClient(client: DynamoDBClient): void;
+    static setTableMapping(mapping: Record<string, string>): void;
+    static transaction(fn: (tx: TransactionContext) => void | Promise<void>): Promise<void>;
+    /**
+     * In-process multi-route READ (issue #101 — the unified envelope). Each alias
+     * route (`{ query | list: Model, key, select, options? }`) runs **independently
+     * and in parallel**; the result is an object keyed by the input aliases. A
+     * `query` route delegates to the single-item read path, a `list` route to the
+     * partition read path. Cross-route consistency is NOT guaranteed.
+     */
+    static query<const E extends ReadEnvelope>(envelope: E): Promise<QueryEnvelopeResult<E>>;
+    /**
+     * In-process multi-operation WRITE (issue #101 — the unified envelope).
+     *
+     * - `mode: 'transaction'` (default) — every op composes into ONE atomic
+     *   `TransactWriteItems`; a `condition` failure rolls the whole set back and the
+     *   call throws. Result: `{ alias: readback }` for ops that declared a `result`.
+     * - `mode: 'parallel'` — non-atomic; ops report success / failure individually
+     *   (the call does not throw on a per-op failure). Result:
+     *   `{ alias: { ok:true, value } | { ok:false, error } }`.
+     *
+     * Both modes funnel through the SAME write-execution core the public contract
+     * runtime uses, so atomicity / derived-effect semantics are identical.
+     */
+    static mutate<const E extends WriteEnvelope>(envelope: E, options?: {
+        mode?: 'transaction';
+    }): Promise<MutateTransactionResult<E>>;
+    static mutate<const E extends WriteEnvelope>(envelope: E, options: {
+        mode: 'parallel';
+    }): Promise<MutateParallelResult<E>>;
+    static batchGet(requests: BatchGetRequest[]): Promise<BatchGetResult>;
+    static batchWrite(requests: BatchWriteRequest[]): Promise<void>;
+    static asModel<C extends new (...args: never[]) => DDBModel>(this: C): ModelStatic<InstanceType<C>, C>;
+}
+
+/**
+ * Internal brand identifying a {@link Column} reference at runtime, used by the
+ * `cond` raw escape hatch to recognize and alias embedded column references.
+ */
+declare const COLUMN_REF: unique symbol;
+/**
+ * A type-safe reference to a model field (column).
+ *
+ * Each column carries its declared value type as a phantom parameter so the
+ * `cond` escape hatch can type-check embedded values against the column. The
+ * `__model` phantom brands the column to its owning model, so passing a column
+ * from a different model into another model's `cond` is a type error.
+ *
+ * @typeParam V - The declared field value type.
+ * @typeParam M - The owning model (brand only; never read at runtime).
+ */
+interface Column<V = unknown, M = unknown> {
+    readonly [COLUMN_REF]: true;
+    /** The underlying attribute (property) name. */
+    readonly name: string;
+    /** @internal phantom — value type carried for `cond` value checking. */
+    readonly __value?: V;
+    /** @internal phantom — owning-model brand. */
+    readonly __model?: M;
+}
+/** Runtime guard: is this value a {@link Column} reference? */
+declare function isColumn(value: unknown): value is Column;
+/**
+ * The `Model.col` map: one {@link Column} per scalar field of the entity, each
+ * typed with the field's declared value type and branded to the model.
+ *
+ * @typeParam T - The Entity type.
+ */
+type ColumnMap<T> = {
+    [K in keyof T as T[K] extends Function ? never : NonNullable<T[K]> extends DDBModel ? never : T[K] extends Array<infer E> ? [E] extends [DDBModel] ? never : K : K]: Column<T[K], T>;
+};
+
+declare const KEY_MARKER: unique symbol;
+/**
+ * Brand identifying a {@link KeySegment} produced by the {@link k} tag.
+ */
+declare const KEY_SEGMENT: unique symbol;
+/**
+ * A single structured key segment — the output of one `` k`...` `` tagged
+ * template. Its literal parts and the column references interpolated between
+ * them are preserved verbatim (the column refs are NOT stringified), so the
+ * planner / spec generator can derive `{field}` templates directly from the
+ * structure rather than recovering them by symbolic evaluation.
+ *
+ * Exactly one `` k`...` `` = one segment = one truncation boundary for a
+ * multi-segment sort key.
+ */
+interface KeySegment {
+    readonly [KEY_SEGMENT]: true;
+    /** The literal string parts; always one longer than {@link columns}. */
+    readonly literals: readonly string[];
+    /** The interpolated column references, in order. */
+    readonly columns: readonly Column[];
+}
+/** Runtime guard: is this value a {@link KeySegment}? */
+declare function isKeySegment(value: unknown): value is KeySegment;
+/**
+ * The interpolation slot accepted by {@link k}: a typed column reference
+ * (`c.field`). Bare strings are NOT accepted — a key field must be named via a
+ * {@link Column} reference so the structure stays type-safe and refactor-safe.
+ */
+type KeySlot = Column;
+/**
+ * Tagged-template builder for a single key segment.
+ *
+ * The literal parts and the interpolated column references are kept structurally
+ * (never stringified), mirroring the {@link cond} escape hatch. A segment such
+ * as `` k`USER#${c.userId}` `` becomes `{ literals: ['USER#', ''], columns: [userId] }`,
+ * which the planner turns into the template `USER#{userId}`.
+ *
+ * @example
+ * ```ts
+ * key((c) => ({ pk: k`USER#${c.userId}`, sk: k`PROFILE` }));
+ * key((c) => ({
+ *   pk: k`REGION#${c.region}`,
+ *   sk: [k`CITY#${c.city}`, k`STORE#${c.store}`],
+ * }));
+ * ```
+ */
+declare function k(literals: TemplateStringsArray, ...columns: KeySlot[]): KeySegment;
+/** A single segment, or an ordered list of segments (multi-segment SK). */
+type SegmentSpec = KeySegment | KeySegment[];
+/** The `{ pk, sk }` structure returned by a key builder. */
+interface KeyStructure {
+    readonly pk: SegmentSpec;
+    readonly sk?: SegmentSpec;
+}
+/**
+ * The canonical, structured representation of a key (PK or SK as a list of
+ * segments). This — not an opaque mapping closure — is the single source of
+ * truth for a model's key.
+ */
+interface SegmentedKey {
+    /** Partition-key segments (all required at resolve time). */
+    readonly pkSegments: readonly KeySegment[];
+    /** Sort-key segments, evaluated in order with truncation. */
+    readonly skSegments: readonly KeySegment[];
+}
+interface KeyDefinitionMarker<T extends Record<string, unknown> = Record<string, unknown>> {
+    readonly [KEY_MARKER]: true;
+    readonly segmented: SegmentedKey;
+    readonly inputFieldNames: string[];
+    /** @internal Phantom field for type-level input type extraction. */
+    readonly _phantom?: T;
+}
+/**
+ * Define a model's primary key from a **structured segment** builder.
+ *
+ * The builder receives a typed column accessor `c` (one `Column` per field) and
+ * returns `{ pk, sk }`, where each of `pk` / `sk` is a single `` k`...` ``
+ * segment or an array of them. Column references are captured structurally, so
+ * the key template is recovered directly from the structure — no symbolic
+ * evaluation of an opaque closure.
+ *
+ * @typeParam T - The key input type (drives compile-time key checking for
+ *   `query` / `list`). Supplied by the caller's parameter annotation on `c`.
+ */
+declare function key<T extends Record<string, unknown>>(builder: (c: {
+    readonly [K in keyof T]-?: Column<T[K], T>;
+}) => KeyStructure): KeyDefinitionMarker<T>;
+
+/**
+ * CDC emulator types (issue #72). These types are **cdc-module-owned**; core
+ * never references them. The {@link ChangeEvent} shape mirrors DynamoDB Streams
+ * (`NEW_AND_OLD_IMAGES`) so a consumer written against the emulator runs
+ * unchanged against real Streams in production (spec §4).
+ */
+/** Stream view type. Fixed to `NEW_AND_OLD_IMAGES` — incremental aggregation
+ * needs both images (spec §4). */
+type StreamViewType = 'NEW_AND_OLD_IMAGES';
+/** Stream event kind, matching DynamoDB Streams. */
+type ChangeEventName = 'INSERT' | 'MODIFY' | 'REMOVE';
+/**
+ * A single change event. Within one shard, `sequenceNumber` is monotonically
+ * increasing; across shards order is independent (spec §6).
+ */
+interface ChangeEvent<T = Record<string, unknown>> {
+    eventName: ChangeEventName;
+    table: string;
+    /** Resolved model name when known. */
+    model?: string;
+    keys: {
+        pk: string;
+        sk: string;
+    };
+    /** Present for MODIFY / REMOVE. */
+    oldImage?: T;
+    /** Present for INSERT / MODIFY. */
+    newImage?: T;
+    /** Deterministic-clock-derived creation time (ISO 8601). */
+    approximateCreationTime: string;
+    /** Monotonic within a shard (zero-padded for lexicographic ordering). */
+    sequenceNumber: string;
+    /** Partition = hash(pk). */
+    shardId: string;
+}
+/** A delivered batch. Records of the same shard are in `sequenceNumber` order. */
+interface ChangeBatch<T = Record<string, unknown>> {
+    records: ChangeEvent<T>[];
+}
+/**
+ * The consumer's response to a batch (spec §6, `ReportBatchItemFailures`
+ * equivalent). Returning the `sequenceNumber`s of records that failed lets the
+ * emulator advance the checkpoint past the successful prefix and redeliver only
+ * the failures.
+ */
+interface BatchResult {
+    /** `sequenceNumber`s of records the consumer failed to process. */
+    batchItemFailures?: string[];
+}
+/** The consumer handler. */
+type ChangeHandler = (batch: ChangeBatch) => Promise<BatchResult | void>;
+/** Unsubscribe handle. */
+type Unsubscribe = () => void;
+/** Where a fresh subscriber begins reading. */
+type StartingPosition = 'TRIM_HORIZON' | 'LATEST';
+/** Clock mode. `virtual` makes time deterministic via `advanceClock`. */
+type ClockMode = 'real' | 'virtual';
+/** Delivery mode (spec §7). */
+type CdcMode = 'inline' | 'queued' | 'record' | 'replay';
+/** Deterministic fault-injection spec (spec §8). All probabilities are seeded. */
+interface FaultSpec {
+    /** Probability [0,1] a delivered record is also re-delivered (duplicate). */
+    duplicate?: number;
+    /** Shuffle within-shard order on delivery (invariant-violation testing). */
+    reorder?: boolean;
+    /** Per-record virtual-time delivery delay range (ms). Requires queued mode. */
+    delay?: {
+        min: number;
+        max: number;
+    };
+    /** Probability [0,1] a record is dropped on first delivery then redelivered. */
+    dropThenRedeliver?: number;
+    /** Probability [0,1] a record is reported as a partial-batch failure. */
+    partialBatchFailure?: number;
+}
+/** A reference whose recompute should be forced to race a mark (spec §8, §7). */
+interface ConcurrentRecomputeRef {
+    /** Opaque node ref the harness recomputes concurrently with marking. */
+    ref: string;
+}
+/** A persisted event log (spec §10, record/replay). */
+interface EventLog {
+    seed: number;
+    events: ChangeEvent[];
+}
+/** Replay options (spec §10). */
+interface ReplayOptions {
+    /** Deliver events in a deterministic shuffled order (any-order replay). */
+    shuffle?: boolean;
+    /** Probability [0,1] each event is delivered twice during replay. */
+    duplicate?: number;
+}
+/** Constructor options (spec §11). */
+interface CdcEmulatorOptions {
+    /** Stream-enabled model classes (opt-in; default none). */
+    models?: Function[];
+    /** Delivery mode. Default `inline`. */
+    mode?: CdcMode;
+    /** Clock mode. Default `virtual` for queued, `real` otherwise. */
+    clock?: ClockMode;
+    /** Records per delivered batch. Default 100. */
+    batchSize?: number;
+    /** Max redelivery attempts before a record goes to the DLQ. Default 3. */
+    maxRetries?: number;
+    /** Where a subscriber starts. Default `TRIM_HORIZON`. */
+    startingPosition?: StartingPosition;
+    /** Seed for fault injection / shard assignment determinism. Default 1. */
+    seed?: number;
+    /** Number of shards events are partitioned across. Default 8. */
+    shardCount?: number;
+}
+type ShardId = string;
+
+export { type BridgeBundle as $, type EntityInput as A, type BatchGetExecInput as B, type ChangeEvent as C, type DynamoDBOperation as D, type Executor as E, type FaultSpec as F, type UniqueQueryKeyOf as G, type EntityRef as H, type ConditionInput as I, type QueryMethodSpec as J, type CommandModelContract as K, type CommandMethodSpec as L, type ModelStatic as M, type ContractSpec as N, type OperationDefinition as O, type PutInput as P, type QueryModelContract as Q, type ResolvedKey as R, type SelectableOf as S, type TransactWriteExecItem as T, type UpdateInput as U, type QuerySpec as V, type WriteExecOptions as W, type CommandSpec as X, type ContextSpec as Y, type OperationsDocument as Z, type AnyOperationDefinition as _, type ExecutorResult as a, type InputArity as a$, type ConditionSpec as a0, type BatchDeleteRequest as a1, type BatchGetRequest as a2, BatchGetResult as a3, type BatchPutRequest as a4, type BatchResult as a5, type BatchWriteRequest as a6, CONTRACT_RANGE_FANOUT_CONCURRENCY as a7, type CdcMode as a8, type ChangeBatch as a9, type ContractKeyRef as aA, type ContractKeySpec as aB, type ContractKind as aC, type ContractMethodOp as aD, type ContractParamRef as aE, type ContractQueryParams as aF, type ContractResolution as aG, type DeleteOptions as aH, type DeriveEffect as aI, type DerivedEdgeWrite as aJ, type DerivedUpdate as aK, type DescriptorBinding as aL, ENTITY_WRITES_MARKER as aM, type EdgeEffect as aN, type EffectPath as aO, type EmitEffect as aP, type EntityWritesDefinition as aQ, type EntityWritesShape as aR, type ExecutableCommandContract as aS, type ExecutableQueryContract as aT, type FilterInput as aU, type FilterSpec as aV, type FragmentInput as aW, type GsiDefinitionMarker as aX, type GsiOptions as aY, type IdempotencyEffect as aZ, type InProcessWriteDescriptor as a_, type ChangeEventName as aa, type ClockMode as ab, type Column as ac, type ColumnMap as ad, type CommandContractMethodSpec as ae, type CommandInputShape as af, type CommandMethod as ag, type CommandPlan as ah, type CommandResolutionTarget as ai, type CommandResultKind as aj, type CommandSelectShape as ak, type CompiledFragment as al, type ComposeSpec as am, type CondSlot as an, type ConditionCheckInput as ao, type Connection as ap, type ContractCallSignature as aq, type ContractCardinality as ar, type ContractCommandParams as as, type ContractCommandResult as at, type ContractComposeNode as au, type ContractFromRef as av, type ContractInputArity as aw, type ContractItem as ax, type ContractKeyFieldRef as ay, type ContractKeyInput as az, type WriteResult as b, type UniqueEffect as b$, type KeyDefinitionMarker as b0, type KeySegment as b1, type KeySlot as b2, type KeyStructure as b3, type KeyedResult as b4, LIFECYCLE_CONTRACT_MARKER as b5, type LifecycleContract as b6, type LifecycleEffects as b7, type LiteralParam as b8, type ManifestEntity as b9, type QueryContractMethodSpec as bA, type QueryEnvelopeResult as bB, type QueryKeyOf as bC, type QueryMethod as bD, type QueryResult as bE, type RangeConditionSpec as bF, type RawCondition as bG, type ReadEnvelope as bH, type ReadOperationType as bI, type ReadRouteDescriptor as bJ, type ReadRouteOptions as bK, type ReadRouteResult as bL, type RecordedCompose as bM, type RelationBuilder as bN, type RelationSelect as bO, type RelationSpec as bP, type RequiresEffect as bQ, type Resolution as bR, SPEC_VERSION as bS, type SegmentSpec as bT, type SelectBuilder as bU, type SelectOf as bV, type StartingPosition as bW, type StreamViewType as bX, type StringParam as bY, TransactionContext as bZ, type TransactionItemType as b_, type ManifestField as ba, type ManifestFieldType as bb, type ManifestGsi as bc, type ManifestKey as bd, type ManifestRelation as be, type ManifestTable as bf, type ModelRef as bg, type MutateMode as bh, type MutateOptions as bi, type MutateParallelResult as bj, type MutateTransactionResult as bk, type MutationBody as bl, type MutationDescriptorMap as bm, type MutationFragment as bn, type MutationInputProxy as bo, type MutationInputRef as bp, type MutationIntent as bq, type NumberParam as br, type OperationKind as bs, type OperationSpec as bt, type ParallelOpResult as bu, type ParamKind as bv, type ParamSpec as bw, type ParamStructure as bx, type PlannedCommandMethod as by, type PutOptions as bz, type DeleteInput as c, type Updatable as c0, type UpdateOptions as c1, type WhenSpec as c2, type WriteDescriptor as c3, type WriteEnvelope as c4, type WriteLifecyclePhase as c5, type WriteOperationType as c6, type WriteRecorder as c7, type WriteResultProjection as c8, attachModelClass as c9, isContractComposeNode as cA, isContractFromRef as cB, isContractKeyFieldRef as cC, isContractKeyRef as cD, isContractParamRef as cE, isEntityWritesDefinition as cF, isKeySegment as cG, isLifecycleContract as cH, isMutationFragment as cI, isMutationInputRef as cJ, isParam as cK, isPlannedCommandMethod as cL, isQueryModelContract as cM, k as cN, key as cO, lifecyclePhaseForIntent as cP, mintContractKeyFieldRef as cQ, mintContractParamRef as cR, mutation as cS, param as cT, publicCommandModel as cU, publicQueryModel as cV, query as cW, resolveLifecycle as cX, wholeKeysSentinel as cY, buildDeleteInput as ca, buildPutInput as cb, buildUpdateInput as cc, compileFragment as cd, compileMutationPlan as ce, compileSingleFragmentPlan as cf, cond as cg, contractOfMethodSpec as ch, definePlan as ci, entityWrites as cj, executeBatchGet as ck, executeBatchWrite as cl, executeCommandMethod as cm, executeDelete as cn, executeKeyedBatchGet as co, executePut as cp, executeQueryMethod as cq, executeRangeFanout as cr, executeTransaction as cs, executeUpdate as ct, from as cu, getEntityWrites as cv, gsi as cw, isColumn as cx, isCommandModelContract as cy, isCommandPlan as cz, type BatchWriteExecItem as d, DDBModel as e, type PrimaryKeyOf as f, type ExecutionPlanSpec as g, type SegmentedKey as h, type SelectBuilderSpec as i, type TransactionSpec as j, type Manifest as k, type ExecutionPlan as l, type CdcEmulatorOptions as m, type ChangeHandler as n, type Unsubscribe as o, type ConcurrentRecomputeRef as p, type EventLog as q, type ReplayOptions as r, type ShardId as s, type TransactionItemSpec as t, type Param as u, type ParamDescriptor as v, type DefinitionMap as w, type WriteDefinitionOptions as x, type PartialQueryKeyOf as y, type StrictSelectSpec as z };