graphddb 0.1.1 → 0.2.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SelectableOf, f as PrimaryKeyOf, E as Executor, g as SegmentedKey, h as SelectBuilderSpec, i as ExecutionPlan, R as ResolvedKey, D as DynamoDBOperation, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, T as TransactWriteExecItem, j as CdcEmulatorOptions, k as ChangeHandler, l as Unsubscribe, F as FaultSpec, m as ConcurrentRecomputeRef, C as ChangeEvent, n as EventLog, o as ReplayOptions, p as ShardId, e as DDBModel, M as ModelStatic, q as PartialQueryKeyOf, r as StrictSelectSpec, s as EntityInput, t as UniqueQueryKeyOf } from './types-CDrWiPxp.js';
-export { u as BatchDeleteRequest, v as BatchGetRequest, w as BatchGetResult, x as BatchPutRequest, y as BatchResult, z as BatchWriteRequest, A as CdcMode, G as ChangeBatch, H as ChangeEventName, I as ClockMode, J as Column, K as ColumnMap, L as CondSlot, N as ConditionCheckInput, O as DeleteOptions, Q as FilterInput, V as GsiDefinitionMarker, X as GsiOptions, Y as KeyDefinitionMarker, Z as KeySegment, _ as KeySlot, $ as KeyStructure, a0 as PutOptions, a1 as QueryKeyOf, a2 as QueryResult, a3 as RawCondition, a4 as RelationBuilder, a5 as RelationSelect, a6 as RelationSpec, a7 as SegmentSpec, a8 as SelectBuilder, a9 as SelectOf, aa as StartingPosition, ab as StreamViewType, ac as TransactionContext, ad as Updatable, ae as UpdateOptions, af as attachModelClass, ag as buildDeleteInput, ah as buildPutInput, ai as buildUpdateInput, aj as cond, ak as executeBatchGet, al as executeBatchWrite, am as executeDelete, an as executePut, ao as executeTransaction, ap as executeUpdate, aq as gsi, ar as isColumn, as as isKeySegment, at as k, au as key } from './types-CDrWiPxp.js';
+import { S as SelectableOf, f as PrimaryKeyOf, E as Executor, g as ExecutionPlanSpec, h as SegmentedKey, i as SelectBuilderSpec, R as RawCondition, j as TransactionSpec, k as Manifest, l as ExecutionPlan, m as ResolvedKey, D as DynamoDBOperation, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, T as TransactWriteExecItem, n as CdcEmulatorOptions, o as ChangeHandler, p as Unsubscribe, F as FaultSpec, q as ConcurrentRecomputeRef, C as ChangeEvent, r as EventLog, s as ReplayOptions, t as ShardId, u as TransactionItemSpec, v as Param, w as ParamDescriptor, x as DefinitionMap, O as OperationDefinition, e as DDBModel, M as ModelStatic, y as WriteDefinitionOptions, z as PartialQueryKeyOf, A as StrictSelectSpec, G as EntityInput, H as UniqueQueryKeyOf, I as EntityRef, J as ConditionInput, Q as QueryModelContract, K as QueryMethodSpec, L as CommandModelContract, N as CommandMethodSpec, V as ContractSpec, X as QuerySpec, Y as CommandSpec, Z as ContextSpec, _ as OperationsDocument, $ as AnyOperationDefinition, a0 as BridgeBundle, a1 as ConditionSpec } from './types-DPJ4tPjX.js';
+export { a2 as BatchDeleteRequest, a3 as BatchGetRequest, a4 as BatchGetResult, a5 as BatchPutRequest, a6 as BatchResult, a7 as BatchWriteRequest, a8 as CONTRACT_RANGE_FANOUT_CONCURRENCY, a9 as CdcMode, aa as ChangeBatch, ab as ChangeEventName, ac as ClockMode, ad as Column, ae as ColumnMap, af as CommandContractMethodSpec, ag as CommandInputShape, ah as CommandMethod, ai as CommandPlan, aj as CommandResolutionTarget, ak as CommandResultKind, al as CommandSelectShape, am as CompiledFragment, an as ComposeSpec, ao as CondSlot, ap as ConditionCheckInput, aq as Connection, ar as ContractCallSignature, as as ContractCardinality, at as ContractCommandParams, au as ContractCommandResult, av as ContractComposeNode, aw as ContractFromRef, ax as ContractInputArity, ay as ContractItem, az as ContractKeyFieldRef, aA as ContractKeyInput, aB as ContractKeyRef, aC as ContractKeySpec, aD as ContractKind, aE as ContractMethodOp, aF as ContractParamRef, aG as ContractQueryParams, aH as ContractResolution, aI as DeleteOptions, aJ as DeriveEffect, aK as DerivedEdgeWrite, aL as DerivedUpdate, aM as DescriptorBinding, aN as ENTITY_WRITES_MARKER, aO as EdgeEffect, aP as EffectPath, aQ as EmitEffect, aR as EntityWritesDefinition, aS as EntityWritesShape, aT as ExecutableCommandContract, aU as ExecutableQueryContract, aV as FilterInput, aW as FilterSpec, aX as FragmentInput, aY as GsiDefinitionMarker, aZ as GsiOptions, a_ as IdempotencyEffect, a$ as InProcessWriteDescriptor, b0 as InputArity, b1 as KeyDefinitionMarker, b2 as KeySegment, b3 as KeySlot, b4 as KeyStructure, b5 as KeyedResult, b6 as LIFECYCLE_CONTRACT_MARKER, b7 as LifecycleContract, b8 as LifecycleEffects, b9 as LiteralParam, ba as ManifestEntity, bb as ManifestField, bc as ManifestFieldType, bd as ManifestGsi, be as ManifestKey, bf as ManifestRelation, bg as ManifestTable, bh as ModelRef, bi as MutateMode, bj as MutateOptions, bk as MutateParallelResult, bl as MutateTransactionResult, bm as MutationBody, bn as MutationDescriptorMap, bo as MutationFragment, bp as MutationInputProxy, bq as MutationInputRef, br as MutationIntent, bs as NumberParam, bt as OperationKind, bu as OperationSpec, bv as ParallelOpResult, bw as ParamKind, bx as ParamSpec, by as ParamStructure, bz as PlannedCommandMethod, bA as PutOptions, bB as QueryContractMethodSpec, bC as QueryEnvelopeResult, bD as QueryKeyOf, bE as QueryMethod, bF as QueryResult, bG as RangeConditionSpec, bH as ReadEnvelope, bI as ReadOperationType, bJ as ReadRouteDescriptor, bK as ReadRouteOptions, bL as ReadRouteResult, bM as RecordedCompose, bN as RelationBuilder, bO as RelationSelect, bP as RelationSpec, bQ as RequiresEffect, bR as Resolution, bS as SPEC_VERSION, bT as SegmentSpec, bU as SelectBuilder, bV as SelectOf, bW as StartingPosition, bX as StreamViewType, bY as StringParam, bZ as TransactionContext, b_ as TransactionItemType, b$ as UniqueEffect, c0 as Updatable, c1 as UpdateOptions, c2 as WhenSpec, c3 as WriteDescriptor, c4 as WriteEnvelope, c5 as WriteLifecyclePhase, c6 as WriteOperationType, c7 as WriteRecorder, c8 as WriteResultProjection, c9 as attachModelClass, ca as buildDeleteInput, cb as buildPutInput, cc as buildUpdateInput, cd as compileFragment, ce as compileMutationPlan, cf as compileSingleFragmentPlan, cg as cond, ch as contractOfMethodSpec, ci as definePlan, cj as entityWrites, ck as executeBatchGet, cl as executeBatchWrite, cm as executeCommandMethod, cn as executeDelete, co as executeKeyedBatchGet, cp as executePut, cq as executeQueryMethod, cr as executeRangeFanout, cs as executeTransaction, ct as executeUpdate, cu as from, cv as getEntityWrites, cw as gsi, cx as isColumn, cy as isCommandModelContract, cz as isCommandPlan, cA as isContractComposeNode, cB as isContractFromRef, cC as isContractKeyFieldRef, cD as isContractKeyRef, cE as isContractParamRef, cF as isEntityWritesDefinition, cG as isKeySegment, cH as isLifecycleContract, cI as isMutationFragment, cJ as isMutationInputRef, cK as isParam, cL as isPlannedCommandMethod, cM as isQueryModelContract, cN as k, cO as key, cP as lifecyclePhaseForIntent, cQ as mintContractKeyFieldRef, cR as mintContractParamRef, cS as mutation, cT as param, cU as publicCommandModel, cV as publicQueryModel, cW as query, cX as resolveLifecycle, cY as wholeKeysSentinel } from './types-DPJ4tPjX.js';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 
@@ -122,6 +122,60 @@ declare const BATCH_GET_MAX_KEYS = 100;
  */
 declare const BATCH_WRITE_MAX_ITEMS = 25;
 
+/**
+ * The single source of truth for **relation execution staging** (issue #70),
+ * shared by the static SSoT generator (`src/spec/operations.ts`,
+ * {@link buildQuerySpec}) and the TS host runtime
+ * (`src/relation/traversal.ts`, {@link resolveRelations}). It is the TS analogue
+ * of the Python runtime's `_relation_stages` / `_plan_concurrency`
+ * (`python/graphddb_runtime/runtime.py`).
+ *
+ * ## Why one shared module (anti-drift)
+ *
+ * #70a records an {@link ExecutionPlanSpec} (`groups` + `concurrency`) in the
+ * SSoT; #70b made the Python runtime **honor** it; #70c makes the TS host runtime
+ * honor it too. For the two runtimes to make **identical** plan-declared
+ * decisions, TS must consume *the same plan facts* the generator serialized — not
+ * re-derive parallelism by an independent "parallelize every sibling" walk. The
+ * host runtime has no generated JSON to load (it works off live decorator
+ * metadata + a `select` tree), so it derives the plan from that live tree using
+ * **this exact function** — the same one the generator calls to produce the
+ * serialized `executionPlan`. Generator and runtime therefore cannot drift: they
+ * are one codepath. {@link deriveExecutionPlan} is the seam.
+ *
+ * ## How the runtime obtains the plan
+ *
+ * The generator produces `operations[]` (root + relation ops, each with a
+ * `resultPath`) and runs {@link deriveExecutionPlan} over their result paths. The
+ * host runtime walks the live `select` tree with {@link relationResultPaths},
+ * which emits the **identical** ordered `resultPath` list
+ * (`buildRelationOperations` is refactored to use it), and runs the **same**
+ * {@link deriveExecutionPlan} over `['$', ...those]`. The resulting
+ * {@link ExecutionPlanSpec} is threaded through the recursive relation traversal:
+ * at each parent level the traversal honors the plan's grouping (which child ops
+ * are an independent, concurrency-eligible stage) and the declared `concurrency`
+ * bound — reading them from the plan, never re-deciding them.
+ */
+
+/**
+ * A **resolved** relation execution plan as the host runtime consumes it: the
+ * serialized {@link ExecutionPlanSpec} (`groups` over operation indices +
+ * `concurrency`) together with the `resultPath` each operation index produces, so
+ * the recursive traversal can locate "the operations at this parent level" and
+ * read their declared stage from the plan.
+ *
+ * Built once at a read's entry point ({@link buildRelationExecutionPlan}) and
+ * threaded, unchanged, through every recursion level. A read whose `select` has
+ * **no** relations (or where the plan would be a single op) carries no plan; the
+ * traversal then has nothing to stage.
+ */
+interface RelationExecutionPlan {
+    /** The serialized staging facts (issue #70a) the traversal honors. */
+    readonly plan: ExecutionPlanSpec;
+    /** Operation index → the `resultPath` it writes (index 0 = root `$`). */
+    readonly resultPaths: readonly string[];
+}
+
 type DynamoType = 'S' | 'N' | 'BOOL' | 'B' | 'SS' | 'NS' | 'L' | 'M';
 interface FieldOptions {
     format?: 'datetime' | 'date';
@@ -366,22 +420,8 @@ interface ConditionExpressionResult {
     names: Record<string, string>;
     values: Record<string, unknown>;
 }
-/**
- * Build a DynamoDB ConditionExpression from a condition object (issues #46, #81).
- *
- * - `{ notExists: true }` → `attribute_not_exists(PK)` (legacy whole-row guard)
- * - `{ attributeExists: 'email' }` → `attribute_exists(#cond_email)` (any field,
- *   incl. PK/SK)
- * - `{ attributeNotExists: 'email' }` → `attribute_not_exists(#cond_email)`
- * - `{ version: 3 }` → `#cond_version = :cond0`
- * - `{ version: 3, status: 'active' }` → `#cond_version = :cond0 AND #cond_status = :cond1`
- *
- * Attribute name/value keys use the `cond_` prefix to avoid collisions with
- * UpdateExpression names/values. The existence primitives go through a `#name`
- * placeholder rather than a bare attribute so reserved-word fields (and PK/SK)
- * are always legal.
- */
-declare function buildConditionExpression(condition: Record<string, unknown>): ConditionExpressionResult;
+
+declare function buildConditionExpression(condition: Record<string, unknown> | RawCondition): ConditionExpressionResult;
 
 /**
  * Compiled DynamoDB `FilterExpression`. Names are `#`-aliased column
@@ -412,732 +452,6 @@ declare function compileFilterExpression(filter: Record<string, unknown> | undef
  */
 declare function evaluateFilter(item: Record<string, unknown>, filter: Record<string, unknown>): boolean;
 
-/**
- * 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.put` 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>;
-
-/**
- * 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 `BatchWriteItem` over the per-key write op (no conditions). References the
- * single write op in `commands` that is expanded per key.
- */
- | {
-    readonly mode: 'batchWrite';
-    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;
-}
-
 /**
  * Declarative transaction executor (issue #46, Python-bridge Phase 4).
  *
@@ -1221,8 +535,6 @@ interface QueryOptions {
 declare function executeQuery(modelClass: Function, key: Record<string, unknown>, selectSpec: Record<string, unknown>, options?: QueryOptions): Promise<Record<string, unknown> | null>;
 
 interface ListInput {
-    /** A plain projection or a `project(...)` builder. */
-    select: Record<string, unknown>;
     limit?: number;
     after?: string;
     order?: 'ASC' | 'DESC';
@@ -1250,7 +562,7 @@ interface ListResult {
  * only `{ items, cursor }`, so internal-only fields such as `rawItems` never
  * cross the public API boundary (no reliance on `as` type narrowing).
  */
-declare function executeList(modelClass: Function, key: Record<string, unknown>, options: ListInput): Promise<ListResult>;
+declare function executeList(modelClass: Function, key: Record<string, unknown>, selectSpec: Record<string, unknown>, options?: ListInput): Promise<ListResult>;
 
 interface ExplainInput {
     select?: Record<string, unknown>;
@@ -1497,2591 +809,6 @@ declare class CdcEmulator {
 /** Create a CDC emulator (spec §10). */
 declare function createCdcEmulator(opts?: CdcEmulatorOptions): CdcEmulator;
 
-/**
- * The single source of truth for **relation execution staging** (issue #70),
- * shared by the static SSoT generator (`src/spec/operations.ts`,
- * {@link buildQuerySpec}) and the TS host runtime
- * (`src/relation/traversal.ts`, {@link resolveRelations}). It is the TS analogue
- * of the Python runtime's `_relation_stages` / `_plan_concurrency`
- * (`python/graphddb_runtime/runtime.py`).
- *
- * ## Why one shared module (anti-drift)
- *
- * #70a records an {@link ExecutionPlanSpec} (`groups` + `concurrency`) in the
- * SSoT; #70b made the Python runtime **honor** it; #70c makes the TS host runtime
- * honor it too. For the two runtimes to make **identical** plan-declared
- * decisions, TS must consume *the same plan facts* the generator serialized — not
- * re-derive parallelism by an independent "parallelize every sibling" walk. The
- * host runtime has no generated JSON to load (it works off live decorator
- * metadata + a `select` tree), so it derives the plan from that live tree using
- * **this exact function** — the same one the generator calls to produce the
- * serialized `executionPlan`. Generator and runtime therefore cannot drift: they
- * are one codepath. {@link deriveExecutionPlan} is the seam.
- *
- * ## How the runtime obtains the plan
- *
- * The generator produces `operations[]` (root + relation ops, each with a
- * `resultPath`) and runs {@link deriveExecutionPlan} over their result paths. The
- * host runtime walks the live `select` tree with {@link relationResultPaths},
- * which emits the **identical** ordered `resultPath` list
- * (`buildRelationOperations` is refactored to use it), and runs the **same**
- * {@link deriveExecutionPlan} over `['$', ...those]`. The resulting
- * {@link ExecutionPlanSpec} is threaded through the recursive relation traversal:
- * at each parent level the traversal honors the plan's grouping (which child ops
- * are an independent, concurrency-eligible stage) and the declared `concurrency`
- * bound — reading them from the plan, never re-deciding them.
- */
-
-/**
- * A **resolved** relation execution plan as the host runtime consumes it: the
- * serialized {@link ExecutionPlanSpec} (`groups` over operation indices +
- * `concurrency`) together with the `resultPath` each operation index produces, so
- * the recursive traversal can locate "the operations at this parent level" and
- * read their declared stage from the plan.
- *
- * Built once at a read's entry point ({@link buildRelationExecutionPlan}) and
- * threaded, unchanged, through every recursion level. A read whose `select` has
- * **no** relations (or where the plan would be a single op) carries no plan; the
- * traversal then has nothing to stage.
- */
-interface RelationExecutionPlan {
-    /** The serialized staging facts (issue #70a) the traversal honors. */
-    readonly plan: ExecutionPlanSpec;
-    /** Operation index → the `resultPath` it writes (index 0 = root `$`). */
-    readonly resultPaths: readonly string[];
-}
-
-/**
- * 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
- * `m.create(() => PostModel, { 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.
- *
- * ```ts
- * const CreatePost = mutation('CreatePost', (m, $) => [
- *   m.create(() => PostModel, { input: { userId: $.userId, title: $.title } }),
- * ]);
- * ```
- *
- * ## Fragments are DECLARATIONS, not executed calls
- *
- * A mutation's top-level fields are write **fragments** — *declarations*, NOT
- * executed function calls. `m.create(...)` does **not** run a write; it records a
- * {@link MutationFragment} (intent + target + input + optional `use:`). The
- * compiler (`src/spec/mutation-command.ts`) expands the fragment list at compile
- * time into a {@link CommandSpec} / `TransactionSpec`. #83 compiles the
- * **single-fragment** case end-to-end; the IR is already a **list** so the
- * N-fragment atomic merge (#90) drops in without reshaping it.
- *
- * ## Intent selects the lifecycle; `use:` is optional
- *
- * Each fragment's **intent** (`m.create` / `m.update` / `m.remove`) selects the
- * lifecycle from the target's `writes` save contract (`entityWrites`, §2):
- * `m.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 **input proxy**: `$.userId` mints a faithful
- * {@link MutationInputRef} naming an input field, so a fragment's `input` map
- * binds model fields to input fields declaratively (no arbitrary JS), exactly as
- * the contract `params` sentinel does.
- */
-
-/**
- * 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 input proxy handed to a mutation body as `$`. Any field read mints a
- * faithful {@link MutationInputRef}; symbol probes are inert. A field is never
- * coerced or transformed — a fragment `input` value is either a `$.<field>`
- * reference or a concrete literal, matching the declarative-only line (§2). The
- * type is `Record<string, MutationInputRef>` so a body reads `$.anyField`.
- */
-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>>;
-/**
- * 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;
-/**
- * Options for a write fragment: the declarative `input` binding and the optional
- * `use:` save-contract override (the **whole** `writes` set, never a lifecycle).
- */
-interface FragmentOptions {
-    /** The model-field → input-field / literal binding. */
-    readonly input: FragmentInput;
-    /**
-     * An optional custom save contract to adopt (the **whole** {@link
-     * EntityWritesDefinition}). Omit to default to the target model's own `writes`.
-     * Per the proposal's `use:` rule this is never a single lifecycle (`writes.create`)
-     * — the fragment's intent already selects the lifecycle.
-     */
-    readonly use?: EntityWritesDefinition;
-}
-/**
- * The intent recorder handed to a mutation body as `m`. `m.create` / `m.update` /
- * `m.remove` each record a {@link MutationFragment} of the corresponding intent;
- * `remove` (not `del`) is the deletion intent per the proposal.
- */
-interface MutationRecorder {
-    /** Record a `create` fragment (→ lifecycle `create`, base op `PutItem`). */
-    create(target: () => ModelStatic<DDBModel> | (new (...args: unknown[]) => unknown), options: FragmentOptions): MutationFragment;
-    /** Record an `update` fragment (→ lifecycle `update`, base op `UpdateItem`). */
-    update(target: () => ModelStatic<DDBModel> | (new (...args: unknown[]) => unknown), options: FragmentOptions): MutationFragment;
-    /** Record a `remove` fragment (→ lifecycle `remove`, base op `DeleteItem`). */
-    remove(target: () => ModelStatic<DDBModel> | (new (...args: unknown[]) => unknown), options: FragmentOptions): MutationFragment;
-}
-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;
-/**
- * Declare an internal **mutation** — a write-plan composition (proposal §1, §3).
- * The body receives the intent recorder `m` (`m.create` / `m.update` /
- * `m.remove`) and the input proxy `$` (`$.field` → a {@link MutationInputRef}),
- * and returns the **list** of write fragments to compose atomically. The result
- * is a branded {@link CommandPlan} (the mutation IR) — *not* public; it implements
- * a Command IF via `publicCommandModel(...).plan(mutation)`.
- *
- * @param name The mutation name (documentary; used in compiler errors).
- * @param body `(m, $) => [fragment, …]` — declares the fragment list.
- * @throws if the body returns a non-array, an empty list, or a non-fragment value.
- */
-declare function mutation(name: string, body: (m: MutationRecorder, $: MutationInputProxy) => readonly MutationFragment[]): 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;
-
-/**
- * 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
- *   `m.create(() => PostModel, { 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';
-/**
- * How a command method resolves an **array of keys** to the underlying write
- * surface (proposal "Consistency with the existing write surface"; issue #64).
- * A single key always maps to one write op; an array maps to a batched write,
- * and a contract **must declare which** form it resolves to:
- *
- * - `'transact'` — a `TransactWriteItems`: the per-key write is applied
- *   **atomically** (all-or-nothing) and **may carry the write condition subset**
- *   ({@link ConditionInput}, `{ notExists }` / equality). DynamoDB caps a
- *   `TransactWriteItems` at **25 items** and the call is atomic, so an array of
- *   >25 keys **cannot** be split (that would break atomicity); the runtime
- *   rejects it with a clear error rather than silently truncating or splitting.
- * - `'batchWrite'` — a `BatchWriteItem`: the per-key writes are applied
- *   **non-atomically** and **carry no conditions** (DynamoDB's `BatchWriteItem`
- *   cannot express a `ConditionExpression`). An array of any size is permitted;
- *   the runtime chunks it per DynamoDB's 25-items-per-request limit and retries
- *   `UnprocessedItems`, reusing the existing batch machinery.
- *
- * The single-key form is always one write op regardless of this declaration;
- * `batchMode` only decides how a key **array** is executed.
- */
-type CommandBatchMode = 'transact' | 'batchWrite';
-/**
- * Runtime guard: is `value` a {@link CommandBatchMode} literal (`'transact'` /
- * `'batchWrite'`)? Used by {@link recordContractOp} to validate a declared batch
- * mode at the recording boundary.
- */
-declare function isCommandBatchMode(value: unknown): value is CommandBatchMode;
-/**
- * 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;
-/**
- * The options a **command** contract method body passes to a model write
- * (`Model.put` / `Model.update` / `Model.delete`) to declare its batched-write
- * resolution (issue #64) and, optionally, a write condition:
- *
- * ```ts
- * disableMany: (keys, params: { reason: string }) =>
- *   User.update(
- *     keys,
- *     { status: 'disabled', disableReason: params.reason },
- *     { batch: 'transact', condition: { notExists: true } },
- *   ),
- * ```
- *
- * This is the **type-safe** declaration point: `batch` is constrained to a
- * {@link CommandBatchMode} literal, so a typo'd mode is a compile error, and the
- * recorder ({@link resolveBatchMode}) re-validates at build time (e.g. it rejects
- * a `condition` under `'batchWrite'`, which DynamoDB cannot express). The
- * single-key execution form ignores `batch`; only a key **array** consults it.
- */
-interface ContractWriteOptions {
-    /**
-     * How a **key array** resolves to the underlying write surface: `'transact'`
-     * (atomic `TransactWriteItems`, ≤25, condition-capable) or `'batchWrite'`
-     * (non-atomic `BatchWriteItem`, no conditions, chunked). Omit to resolve only a
-     * single key (an array is then rejected at execution).
-     */
-    readonly batch?: CommandBatchMode;
-    /**
-     * An optional declarative write condition — the existing subset
-     * ({@link ConditionInput}: `{ notExists }` or equality). Valid for a single
-     * write and for a `'transact'` batch; **not** for `'batchWrite'` (rejected at
-     * build time).
-     */
-    readonly condition?: ConditionInput;
-}
-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.update(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<unknown, unknown, unknown>, 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;
-    /**
-     * The declared batched-write resolution mode for a **write** op (issue #64):
-     * how a *key array* resolves to the underlying write surface — a
-     * `TransactWriteItems` (`'transact'`, atomic, condition-capable, ≤25) or a
-     * `BatchWriteItem` (`'batchWrite'`, non-atomic, no conditions, chunked). Absent
-     * when the author did not declare a batched form (the method then accepts a
-     * single key only at execution; see {@link CommandBatchMode}). Never present on
-     * a read op. The serializer (#59) reads this to emit the method's `batch`
-     * resolution target.
-     */
-    readonly batch?: CommandBatchMode;
-    /**
-     * 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;
-/**
- * @internal The non-enumerable property an arity-tagged body ({@link point} /
- * {@link range}) carries its declared literal {@link InputArity} on. The factory
- * reads it to (1) thread the literal into the resolved {@link QueryMethodSpec}'s
- * `inputArity` type and (2) **verify** the declared literal equals the
- * runtime-derived arity ({@link deriveReadFacts}) at build time — a mismatch is a
- * build error, so the type-level arity cannot lie.
- */
-declare const ARITY_TAG: "__contractArity";
-/**
- * A contract query-method body **tagged** with its declared literal
- * {@link InputArity} (issue #71). Structurally an {@link AuthoredMethod} (single-key
- * `(keys, params) => …`) carrying a phantom `A`, so `<const M>` factory inference
- * preserves the literal arity into the resolved {@link QueryMethodSpec} and on into
- * the `executeQueryMethod` call surface, where {@link ContractCallSignature} narrows
- * the key argument by `A` — making an array fed into a `'single'` method a `tsc`
- * error. The runtime value is the original body function with a non-enumerable
- * `ARITY_TAG`, so it still records its op exactly as an untagged body does.
- *
- * @typeParam A       - The declared literal arity (`'single'` | `'either'`).
- * @typeParam TKey    - The contract Key (single key at authoring time).
- * @typeParam TParams - The method's params type.
- * @typeParam TResult - The method's result type.
- */
-interface ArityTaggedQueryMethod<A extends InputArity, TKey, TParams, TResult> {
-    (keys: TKey, params: TParams): TResult;
-    /** @internal The declared literal arity, read by the factory and build-verified. */
-    readonly [ARITY_TAG]: A;
-}
-/**
- * Declare a query method as a **`point`** read — a unique-key lookup whose per-key
- * result is at most one item (proposal: `resolution: 'point'`). Wrap the method
- * body to thread the read's **literal** {@link InputArity} into the type-level
- * call surface so an array fed into a non-coalescible point is a `tsc` error
- * (issue #71, N+1 rule (a)):
- *
- * ```ts
- * // A base-table primary-key point — a key array coalesces to one BatchGetItem.
- * const GroupById = publicQueryModel<{ groupId: string }>()({
- *   get: point((keys, params: { consistentRead?: boolean }) =>
- *     Group.query(keys, { groupId: true, name: true }, params)),
- * });
- *
- * // A UNIQUE-GSI point — a per-key GSI `Query` (BatchGetItem cannot read a GSI),
- * // so it is NOT coalescible: declare `coalesce: false`.
- * const UserByEmail = publicQueryModel<{ email: string }>(['email'])({
- *   get: point((keys) => User.query(keys, { userId: true, email: true }),
- *     { coalesce: false }),
- * });
- * ```
- *
- * The default (`coalesce: true`) is `inputArity: 'either'` (a base-table PK point);
- * `{ coalesce: false }` is `inputArity: 'single'` (a unique-GSI point). The declared
- * arity is **verified against the build-derived arity** ({@link deriveReadFacts}):
- * declaring `coalesce: true` on a GSI point — or `coalesce: false` on a base-table
- * point — is a build error, so the type never disagrees with the resolved access
- * pattern. Tagging is **optional**: an untagged body keeps the wide `InputArity`
- * and relies on the build-time checker + runtime backstop only.
- *
- * @param body    The single-key method body (`(keys, params) => Model.query(...)`).
- * @param options `{ coalesce }` — `true` (default) for a base-table PK point
- *   (`'either'`), `false` for a unique-GSI point (`'single'`).
- */
-declare function point<TKey, TParams, TResult>(body: (keys: TKey, params: TParams) => TResult, options: {
-    readonly coalesce: false;
-}): ArityTaggedQueryMethod<'single', TKey, TParams, TResult>;
-declare function point<TKey, TParams, TResult>(body: (keys: TKey, params: TParams) => TResult, options?: {
-    readonly coalesce?: true;
-}): ArityTaggedQueryMethod<'either', TKey, TParams, TResult>;
-/**
- * Declare a query method as a **`range`** read — a partition `Query` (`Model.list`)
- * whose per-key result is a connection (`resolution: 'range'`). A range read is
- * **never** coalescible (DynamoDB cannot coalesce N partition `Query`s), so its
- * arity is fixed to `'single'`; wrapping the body threads that literal into the
- * call surface so an array fed into a range method is a `tsc` error (issue #71,
- * N+1 rule (a)):
- *
- * ```ts
- * const MembersByGroup = publicQueryModel<{ groupId: string }>()({
- *   list: range((key, params: { limit?: number }) =>
- *     Member.list({ groupId: key.groupId }, { select: { userId: true }, ...params })),
- * });
- * ```
- *
- * The declared `'single'` arity is **verified against the build-derived arity**
- * ({@link deriveReadFacts}): tagging a body that resolves to a coalescible base-table
- * point with `range(...)` is a build error. Tagging is **optional** (see
- * {@link point}).
- *
- * @param body The single-key method body (`(keys, params) => Model.list(...)`).
- */
-declare function range<TKey, TParams, TResult>(body: (keys: TKey, params: TParams) => TResult): ArityTaggedQueryMethod<'single', TKey, 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 declared batched-write mode (issue #64): how a **key array** resolves —
-     * `'transact'` (atomic `TransactWriteItems`, ≤25, condition-capable) or
-     * `'batchWrite'` (non-atomic `BatchWriteItem`, no conditions, chunked). Absent
-     * when the author declared no batched form — the method then accepts only a
-     * single key at execution; an array is rejected with a clear error. The
-     * single-key form is unaffected by this declaration.
-     */
-    readonly batch?: CommandBatchMode;
-    /**
-     * 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, unknown, unknown>>> {
-    /** @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>>>;
-/**
- * Recovers the model-class constructor type `C` from a `ModelStatic<T, C>`
- * (Model-derived key form). Mirrors the helper used by the `define*` entry
- * points; the contract Key is then `PrimaryKeyOf<ClassOf<M>>`.
- */
-type ClassOf$1<M> = M extends ModelStatic<infer _T, infer C> ? C : unknown;
-/**
- * The **authoring** signature of a contract method body. Deliberately distinct
- * from the formal, array-capable {@link QueryMethod} / {@link CommandMethod}: the
- * author writes a **single-key** body (`(keys: TKey, params) => …`) so that
- * `keys` (and `keys.<field>`) is assignable into the underlying model op's key
- * position, while the array capability (`get(keys[])`) is **derived** by the
- * contract and exposed on the resolved spec's `__signature`. This matches the
- * proposal: a contract method body "resolves to a declarative operation"; the
- * author does not hand-write the batched overload.
- *
- * @typeParam TKey - The contract Key (single key at authoring time).
- */
-type AuthoredMethod<TKey> = (keys: TKey, params: never) => unknown;
-/**
- * The query-method-map type accepted by a {@link publicQueryModel} factory. Each
- * entry is an {@link AuthoredMethod} (a bare body) **or** an
- * {@link ArityTaggedQueryMethod} (a {@link point} / {@link range}-tagged body) whose
- * key type is fixed to the contract `TKey`; `TParams` / `TResult` (and, for a
- * tagged body, the literal arity `A`) are inferred per method.
- */
-type QueryMethodMap<TKey> = Record<string, AuthoredMethod<TKey>>;
-/**
- * The command-method-map type accepted by a {@link publicCommandModel} factory.
- * Each entry is either a hand-written #64 {@link AuthoredMethod} closure
- * (`(keys, params) => Model.put|update|delete(...)`) **or** a #83
- * {@link PlannedCommandMethod} (`command({ input, select }).plan(mutation)`). The
- * two forms coexist in one contract — the brand routes each at build time.
- */
-type CommandMethodMap<TKey> = Record<string, AuthoredMethod<TKey> | PlannedCommandMethod>;
-/**
- * The literal {@link InputArity} a (possibly {@link point} / {@link range}-tagged)
- * authored body declares, or the wide `InputArity` for a bare (untagged) body. An
- * `ArityTaggedQueryMethod` carries its literal `A` on the {@link ARITY_TAG} brand;
- * a bare body has none, so the resolved spec keeps the wide arity (build-checker +
- * runtime backstop only).
- */
-type DeclaredArity<F> = F extends {
-    readonly [ARITY_TAG]: infer A extends InputArity;
-} ? A : InputArity;
-/**
- * Maps a supplied query-method map `M` to its resolved {@link QueryMethodSpec}
- * map. The resolved spec carries the method's authored `TParams` / `TResult` and
- * its **literal** {@link InputArity} when the body was tagged ({@link point} /
- * {@link range}) — the literal threads on into the `executeQueryMethod` call
- * surface, where an array fed into a `'single'` method is a `tsc` error (issue
- * #71, N+1 rule (a)).
- */
-type ResolvedQueryMethods<TKey, M extends QueryMethodMap<TKey>> = {
-    readonly [K in keyof M]: M[K] extends (keys: TKey, params: infer P) => infer R ? QueryMethodSpec<TKey, P, R, DeclaredArity<M[K]>> : never;
-};
-/**
- * The TypeScript value type an input param shape `I` represents: each field
- * carries the value its placeholder stands in for (e.g. `param.string()` →
- * `string`). The public Command IF method's `TParams` for a #83 planned method.
- */
-type InputParamsOf<I extends CommandInputShape> = {
-    readonly [K in keyof I]: I[K] extends Param<infer V> ? V : never;
-};
-/**
- * The result type a #83 planned method returns: the projected read-back item when
- * a `select` is declared (a partial record over the projected fields), or `void`
- * for a fire-and-forget command (no `select`). The concrete field set is the
- * `true`-flagged keys of the declared `select`.
- */
-type PlannedResultOf<S extends CommandSelectShape | undefined> = S extends CommandSelectShape ? Readonly<Record<Extract<keyof S, string>, unknown>> | null : void;
-/**
- * Maps a supplied command-method map to its resolved {@link CommandMethodSpec}
- * map. A #83 {@link PlannedCommandMethod} resolves to a spec whose `TParams` is
- * its input param shape and whose `TResult` is its read-back projection (or
- * `void`); a hand-written #64 closure resolves by its `(keys, params) => R`
- * signature, exactly as before.
- */
-type ResolvedCommandMethods<TKey, M extends CommandMethodMap<TKey>> = {
-    readonly [K in keyof M]: M[K] extends PlannedCommandMethod<infer I, infer S> ? CommandMethodSpec<TKey, InputParamsOf<I>, PlannedResultOf<S>> : M[K] extends (keys: TKey, params: infer P) => infer R ? CommandMethodSpec<TKey, P, R> : never;
-};
-/**
- * The explicit Key-field list a factory accepts (issue #71): the field names that
- * compose the contract Key, constrained to `keyof TKey`. Supplied to the explicit
- * form (`publicQueryModel<EmailKey>(['email'])`) so a **whole-`keys`** point
- * contract whose Key is a GSI (not the model's primary key) is resolved to the
- * right access pattern — without it, the type-erased whole-`keys` op carries no
- * field names and the serializer can only default to the primary key.
- */
-type KeyFieldList<TKey> = readonly (keyof TKey & string)[];
-/**
- * Create a **QueryModel** factory bound to an explicit **Query key** (`TKey`) —
- * the form used for a GSI / alternate access pattern whose key is not the model's
- * primary key:
- *
- * ```ts
- * type CategoryKey = { categoryId: string };
- * const ArticleByCategory = publicQueryModel<CategoryKey>()({
- *   list: (key, params) => Article.list({ categoryId: key.categoryId }, { select: { … } }),
- * });
- * ```
- *
- * **Explicit Key-field capture (issue #71).** A **whole-`keys`** point contract
- * whose Key is a **GSI** (e.g. `EmailKey = { email: string }` resolved through a
- * unique `email` index) must declare its Key fields so the build can resolve the
- * right access pattern — passing `keys` whole into `Model.query(keys, …)` erases
- * the field names (only the phantom `TKey` knows them). Supply the field list:
- *
- * ```ts
- * type EmailKey = { email: string };
- * const UserByEmail = publicQueryModel<EmailKey>(['email'])({
- *   get: (keys, params) => User.query(keys, { userId: true, email: true }),
- * });
- * ```
- *
- * The captured fields are fed through {@link resolveKey}: a Key that resolves to a
- * **unique GSI** emits the GSI `indexName` + GSI key template and is a per-key
- * `Query` (`inputArity: 'single'` — not batch-coalescible), while a Key that
- * resolves to the **base-table primary key** keeps `inputArity: 'either'` (a key
- * array → one `BatchGetItem`). The list is **optional** for backward
- * compatibility: a whole-`keys` contract with no list defaults to the model's
- * primary key, exactly as before #71.
- *
- * The returned factory takes a record of named query methods (the use cases) and
- * resolves each body to its declarative internal op, deriving `resolution` /
- * `inputArity`. The method closures are discarded; only the resolved IR is kept.
- *
- * @typeParam TKey - The explicit contract Key (the access pattern / join key).
- * @param keyFields - Optional explicit Key-field names (issue #71); when present
- *   they are captured into the IR and resolved to the access pattern.
- */
-declare function publicQueryModel<TKey>(keyFields?: KeyFieldList<TKey>): <const M extends QueryMethodMap<TKey>>(methods: M) => QueryModelContract<TKey, ResolvedQueryMethods<TKey, M>>;
-/**
- * Create a **QueryModel** factory whose Key is **derived** from a Model's primary
- * key (no explicit key type needed):
- *
- * ```ts
- * const ArticleById = publicQueryModel(ArticleModel)({
- *   get: (keys, params) => Article.query(keys, { articleId: true, title: true }, params),
- * });
- * ```
- *
- * An explicit Key-field list (issue #71) is **optional** here: the Key continues
- * to derive from the model's primary key when omitted.
- *
- * @param model - The model whose primary key becomes the contract Key.
- * @param keyFields - Optional explicit Key-field names; defaults to the model's
- *   primary-key input fields.
- */
-declare function publicQueryModel<M extends ModelStatic<DDBModel>>(model: M, keyFields?: KeyFieldList<PrimaryKeyOf<ClassOf$1<M>>>): <const Methods extends QueryMethodMap<PrimaryKeyOf<ClassOf$1<M>>>>(methods: Methods) => QueryModelContract<PrimaryKeyOf<ClassOf$1<M>>, ResolvedQueryMethods<PrimaryKeyOf<ClassOf$1<M>>, Methods>>;
-/**
- * Create a **CommandModel** factory bound to an explicit **Command key** (`TKey`).
- * Symmetric to {@link publicQueryModel}; each method resolves to a write op
- * (`put` / `update` / `delete`) and carries an explicit, contract-level result
- * type (`void` | a `Result` | the updated entity):
- *
- * ```ts
- * type UserKey = { userId: string };
- * const UserCommands = publicCommandModel<UserKey>()({
- *   disable: (keys, params: { reason: string }): UpdatedUser =>
- *     User.update(keys, { status: 'disabled', disableReason: params.reason }),
- *   changeRole: (keys, params: { role: Role }): void =>
- *     User.update(keys, { role: params.role }),
- * });
- * ```
- *
- * An explicit Key-field list (issue #71) is **optional**; symmetric to
- * {@link publicQueryModel}, it captures the whole-`keys` Key fields into the IR
- * so the serializer emits the contract Key explicitly. A command always writes to
- * the base table by its key, so the list does not change a command's
- * `inputArity` (always `'either'` — a single key or a batched write).
- *
- * @typeParam TKey - The explicit contract Key (the target identity).
- * @param keyFields - Optional explicit Key-field names (issue #71).
- */
-declare function publicCommandModel<TKey>(keyFields?: KeyFieldList<TKey>): <const M extends CommandMethodMap<TKey>>(methods: M) => CommandModelContract<TKey, ResolvedCommandMethods<TKey, M>>;
-/**
- * Create a **CommandModel** factory whose Key is **derived** from a Model's
- * primary key.
- *
- * @param model - The model whose primary key becomes the contract Key.
- * @param keyFields - Optional explicit Key-field names; defaults to the model's
- *   primary-key input fields.
- */
-declare function publicCommandModel<M extends ModelStatic<DDBModel>>(model: M, keyFields?: KeyFieldList<PrimaryKeyOf<ClassOf$1<M>>>): <const Methods extends CommandMethodMap<PrimaryKeyOf<ClassOf$1<M>>>>(methods: Methods) => CommandModelContract<PrimaryKeyOf<ClassOf$1<M>>, ResolvedCommandMethods<PrimaryKeyOf<ClassOf$1<M>>, Methods>>;
-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 builder returned by {@link command}: `.plan(mutation)` finalizes the public
- * Command IF method by attaching the internal {@link CommandPlan} that implements
- * it, yielding a branded {@link PlannedCommandMethod}.
- */
-interface CommandBuilder<TInput extends CommandInputShape, TSelect extends CommandSelectShape | undefined> {
-    /**
-     * Attach the internal mutation that **implements** this Command IF method. The
-     * mutation is a {@link CommandPlan} (a `mutation(...)` / `definePlan(...)`
-     * result); the public surface stays params (the `input`) + result (the `select`
-     * read-back projection) only.
-     *
-     * @param plan The internal {@link CommandPlan} that implements this method.
-     */
-    plan(plan: CommandPlan): PlannedCommandMethod<TInput, TSelect>;
-}
-/**
- * Declare a public **Command IF** method (#83; proposal §3) — the external,
- * fixed surface other services depend on: **params in** (`input`) and **result
- * out** (`select`, the post-write read-back projection). The method is
- * *implemented by* an internal mutation, attached via {@link CommandBuilder.plan}:
- *
- * ```ts
- * export const PostCommands = publicCommandModel<PostKey>()({
- *   create: command({
- *     input:  { userId: param.string(), title: param.string(), body: param.string() },
- *     select: { postId: true, title: true },   // return = read-back projection
- *   }).plan(CreatePost),                         // implemented by the internal mutation
- * });
- * ```
- *
- * The mutation document is **never** exposed; only the `input` params and the
- * `select` result cross the boundary.
- *
- * @param spec `{ input, select? }` — the public input param shape and the optional
- *   return projection (consistent read-back).
- */
-declare function command<const TInput extends CommandInputShape, const TSelect extends CommandSelectShape | undefined = undefined>(spec: {
-    input: TInput;
-    select?: TSelect;
-}): CommandBuilder<TInput, TSelect>;
-
-/**
- * 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.put` /
- * `Model.update` / `Model.delete` 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;
-        readonly batch?: CommandBatchMode;
-        /**
-         * 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;
-/**
- * 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>;
-
 /**
  * Per-key cursor envelope for batched `range` (`list`) contract methods (issue
  * #62, CQRS single-service runtime; spec `docs/cqrs-contract.md`,
@@ -4549,7 +1276,7 @@ type ParamLeavesOf<X> = X extends Param<infer V> ? V : X extends object ? {
  * These accept {@link Param} placeholders at scalar leaves while keeping field
  * names / value types / the key boundary / strict-select checked at definition
  * time (via {@link Parameterize} layered on the model's real key & select
- * types). `Model.query` / `Model.put` / … are **untouched**.
+ * types). `Model.query` / `Model.putItem` / … are **untouched**.
  *
  * `defineQueries({...})` / `defineCommands({...})` take a record of these
  * definition nodes and return the same record (typed), forming the IR the
@@ -5306,4 +2033,4 @@ declare function assertBundleSerializable(bundle: BridgeBundle): void;
  */
 declare function buildBridgeBundle(queries?: DefinitionMap, commands?: DefinitionMap, registry?: typeof MetadataRegistry, transactions?: Record<string, TransactionDefinition>, contractInputs?: ContractInputs): BridgeBundle;
 
-export { type AnyModelContract, type AnyOperationDefinition, type ArityTaggedQueryMethod, BATCH_GET_MAX_KEYS, BATCH_WRITE_MAX_ITEMS, BatchGetExecInput, BatchWriteExecItem, type BridgeBundle, type BuiltContracts, CONTRACT_RANGE_FANOUT_CONCURRENCY, CdcEmulator, CdcEmulatorOptions, ChangeEvent, ChangeHandler, ClientManager, type CollectParams, type CommandBatchMode, type CommandBuilder, type CommandContractMethodSpec, type CommandInputShape, type CommandMethod, type CommandMethodSpec, type CommandModelContract, type CommandPlan, type CommandResolutionTarget, type CommandResultKind, type CommandSelectShape, type CommandSpec, type CompiledFragment, type ComposeSpec, ConcurrentRecomputeRef, type ConditionExpressionResult, type ConditionInput, type ConditionSpec, type Connection, type ContextOwnership, type ContextOwnershipMap, type ContextSpec, type ContractBoundaryViolation, type ContractCallSignature, type ContractCardinality, type ContractCommandParams, type ContractCommandResult, type ContractComposeNode, type ContractFromRef, type ContractInputArity, type ContractInputs, type ContractItem, type ContractKeyFieldRef, type ContractKeyInput, type ContractKeyRef, type ContractKeySpec, type ContractKind, type ContractMap, type ContractMethodOp, type ContractN1Violation, type ContractParamRef, type ContractQueryParams, type ContractResolution, type ContractSpec, type ContractWriteOptions, DDBModel, type DefinitionMap, DeleteInput, type DeriveEffect, type DerivedEdgeWrite, type DerivedUpdate, DynamoDBOperation, DynamoExecutor, type DynamoType, EDGE_WRITES_MARKER, ENTITY_WRITES_MARKER, type EdgeEffect, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, type EffectPath, type EmbeddedMetadata, type EmitEffect, type EntityMetadata, type EntityRef, type EntityWritesDefinition, type EntityWritesShape, EventLog, type ExecutableCommandContract, type ExecutableQueryContract, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FaultSpec, type FieldMetadata, type FieldOptions, type FilterExpressionResult, type FilterSpec, type FragmentInput, type FragmentOptions, type GsiDefinition, type IdempotencyEffect, type InputArity, type KeyDefinition, type KeyedResult, LIFECYCLE_CONTRACT_MARKER, type LifecycleContract, type LifecycleEffects, type LintResult, type LintRule, Linter, type ListInput, type ListOptions, type LiteralParam, MAX_TRANSACT_ITEMS, type Manifest, type ManifestEntity, type ManifestField, type ManifestFieldType, type ManifestGsi, type ManifestKey, type ManifestRelation, type ManifestTable, MetadataRegistry, type ModelOptions, ModelStatic, type MutationFragment, type MutationInputProxy, type MutationInputRef, type MutationIntent, type MutationRecorder, type NumberParam, OLD_VALUE_NAMESPACE, type OperationDefinition, type OperationKind, type OperationSpec, type OperationsDocument, type Param, type ParamDescriptor, type ParamKind, type ParamSpec, type ParamStructure, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, type PlannedCommandMethod, PrimaryKeyOf, type ProjectionResult, PutInput, type QueryContractMethodSpec, type QueryMethod, type QueryMethodSpec, type QueryModelContract, type QueryOptions$1 as QueryOptions, type QuerySpec, type RangeConditionSpec, type ReadOperationType, type RecordedCompose, type RelationLimitOptions, type RelationMetadata, type RelationOptions, type RelationTraversalOptions, ReplayOptions, type RequiresEffect, type Resolution, ResolvedKey, SPEC_VERSION, SegmentedKey, SelectableOf, ShardId, type StringParam, TableMapping, TransactWriteExecItem, type TransactionDefinition, type TransactionItemSpec, type TransactionItemType, type TransactionParamShape, type TransactionRef, type TransactionSpec, type TxConditionCheckOptions, type TxForEachInstruction, type TxForEachOptions, type TxInstruction, type TxRecorder, type TxWriteInstruction, type TxWriteOptions, type UniqueEffect, UniqueQueryKeyOf, type UpdateExpressionResult, UpdateInput, type WhenComparison, type WhenSpec, type WriteDefinitionOptions, WriteExecOptions, type WriteLifecyclePhase, type WriteOperationType, type WriteRecorder, WriteResult, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, belongsTo, binary, boolean, buildBridgeBundle, buildConditionExpression, buildContexts, buildContracts, buildManifest, buildOperations, buildProjection, buildQuerySpec, buildTransactionSpec, buildTransactions, buildUpdateExpression, collectContractBoundaryViolations, collectContractN1Violations, command, compileFilterExpression, compileFragment, compileMutationPlan, compileSingleFragmentPlan, contractOfMethodSpec, createCdcEmulator, createDefaultLinter, datetime, decodeCursor, decodePerKeyCursor, defineCommands, defineDelete, defineList, definePlan, definePut, defineQueries, defineQuery, defineTransaction, defineTransactions, defineUpdate, deriveEdgeWriteItems, deriveEdgeWriteItemsFor, deriveModelEdgeWriteItems, derivePrefix, detectRelationFields, edgeWrites, embedded, encodeCursor, encodePerKeyCursor, entityWrites, evaluateFilter, execute, executeCommandMethod, executeDeclarativeTransaction, executeExplain, executeKeyedBatchGet, executeList, executeQuery, executeQueryMethod, executeRangeFanout, expandTransaction, field, from, getEdgeWrites, getEntityWrites, getImplicitKeyFields, gsiAmbiguityRule, hasMany, hasOne, hydrate, isCommandBatchMode, isCommandModelContract, isCommandPlan, isContractComposeNode, isContractFromRef, isContractKeyFieldRef, isContractKeyRef, isContractParamRef, isEdgeWritesDefinition, isEntityWritesDefinition, isLifecycleContract, isMutationFragment, isMutationInputRef, isParam, isPlannedCommandMethod, isQueryModelContract, isSelectBuilder, isTransactionRef, lifecyclePhaseForIntent, list, literal, map, mintContractKeyFieldRef, mintContractParamRef, missingGsiRule, model, mutation, noScanRule, number, numberSet, param, plan, point, publicCommandModel, publicQueryModel, query, queryBoundaryRule, range, relationDepthRule, requireLimitRule, resolveKey, resolveLifecycle, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, validateDepth, validateGsiAmbiguity, when, wholeKeysSentinel };
+export { type AnyModelContract, AnyOperationDefinition, BATCH_GET_MAX_KEYS, BATCH_WRITE_MAX_ITEMS, BatchGetExecInput, BatchWriteExecItem, BridgeBundle, type BuiltContracts, CdcEmulator, CdcEmulatorOptions, ChangeEvent, ChangeHandler, ClientManager, type CollectParams, CommandMethodSpec, CommandModelContract, CommandSpec, ConcurrentRecomputeRef, type ConditionExpressionResult, ConditionInput, ConditionSpec, type ContextOwnership, type ContextOwnershipMap, ContextSpec, type ContractBoundaryViolation, type ContractInputs, type ContractMap, type ContractN1Violation, ContractSpec, DDBModel, DefinitionMap, DeleteInput, DynamoDBOperation, DynamoExecutor, type DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, type EmbeddedMetadata, type EntityMetadata, EntityRef, EventLog, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FaultSpec, type FieldMetadata, type FieldOptions, type FilterExpressionResult, type GsiDefinition, type KeyDefinition, type LintResult, type LintRule, Linter, type ListInput, type ListOptions, MAX_TRANSACT_ITEMS, Manifest, MetadataRegistry, type ModelOptions, ModelStatic, OLD_VALUE_NAMESPACE, OperationDefinition, OperationsDocument, Param, ParamDescriptor, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, PrimaryKeyOf, type ProjectionResult, PutInput, QueryMethodSpec, QueryModelContract, type QueryOptions$1 as QueryOptions, QuerySpec, RawCondition, type RelationLimitOptions, type RelationMetadata, type RelationOptions, type RelationTraversalOptions, ReplayOptions, ResolvedKey, SegmentedKey, SelectableOf, ShardId, TableMapping, TransactWriteExecItem, type TransactionDefinition, TransactionItemSpec, type TransactionParamShape, type TransactionRef, TransactionSpec, type TxConditionCheckOptions, type TxForEachInstruction, type TxForEachOptions, type TxInstruction, type TxRecorder, type TxWriteInstruction, type TxWriteOptions, UniqueQueryKeyOf, type UpdateExpressionResult, UpdateInput, type WhenComparison, WriteDefinitionOptions, WriteExecOptions, WriteResult, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, belongsTo, binary, boolean, buildBridgeBundle, buildConditionExpression, buildContexts, buildContracts, buildManifest, buildOperations, buildProjection, buildQuerySpec, buildTransactionSpec, buildTransactions, buildUpdateExpression, collectContractBoundaryViolations, collectContractN1Violations, compileFilterExpression, createCdcEmulator, createDefaultLinter, datetime, decodeCursor, decodePerKeyCursor, defineCommands, defineDelete, defineList, definePut, defineQueries, defineQuery, defineTransaction, defineTransactions, defineUpdate, deriveEdgeWriteItems, deriveEdgeWriteItemsFor, deriveModelEdgeWriteItems, derivePrefix, detectRelationFields, edgeWrites, embedded, encodeCursor, encodePerKeyCursor, evaluateFilter, execute, executeDeclarativeTransaction, executeExplain, executeList, executeQuery, expandTransaction, field, getEdgeWrites, getImplicitKeyFields, gsiAmbiguityRule, hasMany, hasOne, hydrate, isEdgeWritesDefinition, isSelectBuilder, isTransactionRef, list, literal, map, missingGsiRule, model, noScanRule, number, numberSet, plan, queryBoundaryRule, relationDepthRule, requireLimitRule, resolveKey, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, validateDepth, validateGsiAmbiguity, when };