graphddb 0.7.10 → 0.8.0

package/dist/{maintenance-view-adapter-BAZ9uBGe.d.ts → key-DR7_lpyk.d.ts}

@@ -1,5 +1,4 @@
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import { c as Param, E as ExpressionSpec, a0 as ParamKind, Y as TransactionItemSpec } from './types-BQLzTEqh.js';
+import { a1 as Param, E as ExpressionSpec, a2 as ParamKind, T as TransactionSpec, X as TransactionItemSpec } from './types-2PMXEn5x.js';
 
 /**
  * CDC emulator types (issue #72). These types are **cdc-module-owned**; core
@@ -114,132 +113,6 @@ interface CdcEmulatorOptions {
 }
 type ShardId = string;
 
-/**
- * App-level throttle / transient-error retry for single-op sends (issue #111).
- *
- * GraphDDB's single-item ops (GetItem / Query / Put / Update / Delete) and the
- * read fan-out (relation resolution) used to throw on throttling
- * (`ProvisionedThroughputExceededException` / `ThrottlingException`) and rely
- * solely on the AWS SDK v3 default retry, so the LIBRARY itself guaranteed no
- * throttle-resilience. The batch ops already retry partial completion
- * (`UnprocessedKeys` / `UnprocessedItems`, see `src/operations/batch-retry.ts`);
- * this module is the SEPARATE, library-owned ERROR retry that wraps every
- * `docClient.send()` for the single ops via {@link RetryingExecutor}.
- *
- * The two retry layers are DISTINCT and must not be merged:
- *  - (A) partial-batch retry (`batch-retry.ts`) — DynamoDB accepted the request
- *    but could not process every key/item; the request itself did NOT error.
- *  - (B) error retry (this module) — `send()` REJECTED with a throttle / transient
- *    error and is retried whole.
- * They share {@link computeBackoffDelay} so backoff is consistent across both,
- * but they are different mechanisms.
- *
- * The default policy is ENABLED out of the box (see {@link DEFAULT_RETRY_POLICY}):
- * even with zero configuration a sensible exponential-backoff-with-jitter,
- * bounded-attempts retry applies. Users tune it globally via
- * `DDBModel.setRetryPolicy(...)` or per-call via the `retry?:` option on the
- * operation option bags; `retry: false` disables retry for that one call.
- *
- * NOTE on the AWS SDK's OWN retry: now that the library owns retry, a
- * `DynamoDBClient` left at the SDK default `maxAttempts: 3` retries
- * MULTIPLICATIVELY underneath this layer. Users should construct their client
- * with `maxAttempts: 1` so the library is the single source of truth for retry
- * (documented at `DDBModel.setClient` and in the README). The library does NOT
- * silently mutate a user-provided client.
- */
-/** The single-op kind a retry is wrapping — surfaced to {@link RetryPolicy.onRetry}. */
-type RetryOperationKind = 'get' | 'query' | 'batchGet' | 'put' | 'update' | 'delete' | 'batchWrite' | 'transactWrite';
-/** The context handed to {@link RetryPolicy.onRetry} before each backoff sleep. */
-interface RetryInfo {
-    /** 1-based attempt number that just FAILED and is about to be retried. */
-    readonly attempt: number;
-    /** The throttle / transient error that triggered this retry. */
-    readonly error: unknown;
-    /** The backoff delay (ms) about to be slept before the next attempt. */
-    readonly delayMs: number;
-    /** Which single-op kind is being retried. */
-    readonly operation: RetryOperationKind;
-}
-/**
- * A retry policy for the single-op error-retry layer (issue #111). Every field is
- * optional and resolved INDEPENDENTLY, in layers (see {@link resolveRetryPolicy}):
- * a per-call override field wins, else the globally-configured policy's field
- * (from {@link import('../model/DDBModel.js').DDBModel.setRetryPolicy}), else
- * {@link DEFAULT_RETRY_POLICY}. So a partial per-call override (e.g.
- * `{ maxAttempts: 3 }`) overrides ONLY that field and INHERITS the rest from the
- * global policy — a global `onRetry` / `jitter` is NOT dropped. A policy value of
- * `false` on an option bag disables retry entirely for that call.
- */
-interface RetryPolicy {
-    /**
-     * Maximum number of attempts (the FIRST try counts as attempt 1). `1` disables
-     * retry (a single try, no backoff). Default {@link DEFAULT_MAX_ATTEMPTS}.
-     */
-    readonly maxAttempts?: number;
-    /**
-     * Compute the base backoff delay (ms) for a 1-based retry attempt, BEFORE jitter.
-     * Defaults to {@link computeBackoffDelay} (`min(1000, 50*2^(attempt-1))`), the
-     * same ramp the batch partial-retry layer uses, so backoff is consistent across
-     * the two layers.
-     */
-    readonly computeDelay?: (attempt: number) => number;
-    /**
-     * Jitter strategy applied to the base delay:
-     *  - `'full'` (default) — uniform random in `[0, base]` (AWS "full jitter"),
-     *    the recommended strategy to de-correlate retries across clients.
-     *  - `'none'` — use the base delay verbatim (deterministic; handy in tests).
-     */
-    readonly jitter?: 'full' | 'none';
-    /**
-     * Classify whether an error is retryable. Defaults to {@link isRetryableError}
-     * (throttle + 5xx / transient). A custom classifier fully replaces the default —
-     * it should still avoid retrying validation / conditional-check failures.
-     */
-    readonly isRetryable?: (error: unknown) => boolean;
-    /**
-     * Observability hook (issue #111 §8): invoked BEFORE each backoff sleep with the
-     * attempt number, the triggering error, the computed (post-jitter) delay, and the
-     * operation kind. Never invoked on the terminal success or the terminal failure.
-     */
-    readonly onRetry?: (info: RetryInfo) => void;
-}
-/** Default cap on attempts: the first try plus up to 9 retries (mirrors the batch cap). */
-declare const DEFAULT_MAX_ATTEMPTS = 10;
-/**
- * The default, always-on retry policy (issue #111 §3). Exponential backoff (the
- * shared {@link computeBackoffDelay} ramp) + full jitter, capped at
- * {@link DEFAULT_MAX_ATTEMPTS} attempts, retrying throttle / 5xx / transient
- * errors only (never validation / conditional-check failures).
- */
-declare const DEFAULT_RETRY_POLICY: Required<Pick<RetryPolicy, 'maxAttempts' | 'computeDelay' | 'jitter' | 'isRetryable'>>;
-/**
- * Default error classifier (issue #111 §5). Retryable when the error is a known
- * throttle / transient fault, an AWS SDK error flagged `$retryable`, or a 5xx /
- * 429 status. NEVER retryable for validation / conditional-check / not-found /
- * access-denied — those are deterministic and would just burn the attempt budget.
- *
- * NOTE: a {@link https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html
- * TransactionCanceledException} is handled SEPARATELY by
- * {@link isRetryableTransactionCancellation}; this function treats it as
- * non-retryable so the transact path can inspect its `CancellationReasons` first.
- */
-declare function isRetryableError(error: unknown): boolean;
-/**
- * Classify a `TransactionCanceledException` (issue #111 §6). Inspects the
- * `CancellationReasons`:
- *  - ANY `ConditionalCheckFailed` reason ⇒ NOT retryable (a deterministic
- *    condition failure; retrying would just fail again) — return `false`.
- *  - Otherwise, when EVERY non-`None` reason is a throttle / conflict code
- *    (`ThrottlingError` / `ProvisionedThroughputExceeded` / `TransactionConflict`)
- *    ⇒ retryable — return `true`.
- *  - A cancellation with no inspectable reasons, or any other reason code, is
- *    treated conservatively as NOT retryable.
- *
- * Only meaningful for an error whose name is `TransactionCanceledException`; the
- * caller checks that first.
- */
-declare function isRetryableTransactionCancellation(error: unknown): boolean;
-
 interface RangeCondition {
     operator: 'begins_with';
     key: string;
@@ -280,17 +153,6 @@ type DynamoDBOperation = GetItemOperation | QueryOperation | BatchGetItemOperati
 interface ExecutionPlan {
     operations: DynamoDBOperation[];
 }
-type ResolvedKey = {
-    type: 'pk';
-    partial: boolean;
-    inputFieldNames: string[];
-} | {
-    type: 'gsi';
-    indexName: string;
-    unique: boolean;
-    partial: boolean;
-    inputFieldNames: string[];
-};
 
 /**
  * Internal brand identifying a {@link RawCondition} produced by {@link cond}.
@@ -467,27 +329,6 @@ interface WriteOptions<T> {
     readonly condition?: WriteCondition<T>;
 }
 
-/**
- * Internal brand symbol identifying a compiled select builder at runtime.
- * Consumers should not depend on this; it is used by the execution layer to
- * distinguish a builder instance from a plain select object.
- */
-declare const SELECT_BUILDER: unique symbol;
-/**
- * The normalized spec a select builder resolves to. This is the shape the
- * planner / traversal layer consumes. `filter` is the declarative server-side
- * DynamoDB FilterExpression input.
- *
- * @internal
- */
-interface SelectBuilderSpec {
-    readonly [SELECT_BUILDER]: true;
-    select: Record<string, unknown>;
-    filter?: Record<string, unknown>;
-    limit?: number;
-    after?: string;
-    order?: 'ASC' | 'DESC';
-}
 /**
  * Top-level select builder produced by `Model.project(...)`.
  *
@@ -827,65 +668,6 @@ type AtLeastOneKey<T> = {
  */
 type PartialQueryKeyOf<C> = QueryKeyOf<C> extends infer U ? U extends Record<string, unknown> ? AtLeastOneKey<U> : never : never;
 
-interface PutOptions<T = unknown> {
-    condition?: WriteCondition<T>;
-    /**
-     * Per-call throttle / transient-error retry override (issue #111). A
-     * {@link RetryPolicy} replaces the global policy for this call; `false` disables
-     * retry for this call. Omit to use the configured (or built-in default) policy.
-     */
-    retry?: RetryOverride;
-    /**
-     * Host-injected per-call write context (issue #50 / #139) — exposed to every
-     * write hook (W1–W5) as `ctx.context`. A host-language value, NEVER serialized
-     * into the SSoT / `operations.json` (the bridge #48 is unaffected). Absent ⇒ `{}`.
-     */
-    context?: RequestContext;
-}
-interface UpdateOptions<T = unknown> {
-    condition?: WriteCondition<T>;
-    /**
-     * Per-call throttle / transient-error retry override (issue #111). A
-     * {@link RetryPolicy} replaces the global policy for this call; `false` disables
-     * retry for this call.
-     */
-    retry?: RetryOverride;
-    /**
-     * How to re-derive a GSI key whose composing fields are changed but **not all**
-     * available from `{ ...key, ...changes }` (issue #115).
-     *
-     * - **unset (default)** — refuse with an explicit error rather than let the
-     *   index silently rot. The error names the index, the changed field, and the
-     *   missing field(s). The happy path (all composing fields available) re-derives
-     *   in the SAME `UpdateExpression` and is unaffected by this option.
-     * - `'read-modify-write'` — read the current item, merge `{ ...item, ...changes }`,
-     *   re-derive every affected GSI key from the merged image, and write back under
-     *   an optimistic condition (the item must still exist / be unchanged). This costs
-     *   one extra read and is NOT atomic with the original update, but always re-derives
-     *   correctly.
-     */
-    rederive?: 'read-modify-write';
-    /**
-     * Host-injected per-call write context (issue #50 / #139) — exposed to every
-     * write hook (W1–W5) as `ctx.context`. NEVER serialized. Absent ⇒ `{}`.
-     */
-    context?: RequestContext;
-}
-interface DeleteOptions<T = unknown> {
-    condition?: WriteCondition<T>;
-    /**
-     * Per-call throttle / transient-error retry override (issue #111). A
-     * {@link RetryPolicy} replaces the global policy for this call; `false` disables
-     * retry for this call.
-     */
-    retry?: RetryOverride;
-    /**
-     * Host-injected per-call write context (issue #50 / #139) — exposed to every
-     * write hook (W1–W5) as `ctx.context`. NEVER serialized. Absent ⇒ `{}`.
-     */
-    context?: RequestContext;
-}
-
 interface PutInput {
     TableName: string;
     Item: Record<string, unknown>;
@@ -893,8 +675,6 @@ interface PutInput {
     ExpressionAttributeNames?: Record<string, string>;
     ExpressionAttributeValues?: Record<string, unknown>;
 }
-declare function buildPutInput(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): PutInput;
-declare function executePut(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): Promise<void>;
 
 interface UpdateInput {
     TableName: string;
@@ -904,8 +684,6 @@ interface UpdateInput {
     ExpressionAttributeValues?: Record<string, unknown>;
     ConditionExpression?: string;
 }
-declare function buildUpdateInput(modelClass: Function, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): UpdateInput;
-declare function executeUpdate(modelClass: Function, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): Promise<void>;
 
 interface DeleteInput {
     TableName: string;
@@ -914,8 +692,96 @@ interface DeleteInput {
     ExpressionAttributeNames?: Record<string, string>;
     ExpressionAttributeValues?: Record<string, unknown>;
 }
-declare function buildDeleteInput(modelClass: Function, keyObj: Record<string, unknown>, options?: DeleteOptions): DeleteInput;
-declare function executeDelete(modelClass: Function, keyObj: Record<string, unknown>, options?: DeleteOptions): Promise<void>;
+
+/**
+ * App-level throttle / transient-error retry for single-op sends (issue #111).
+ *
+ * GraphDDB's single-item ops (GetItem / Query / Put / Update / Delete) and the
+ * read fan-out (relation resolution) used to throw on throttling
+ * (`ProvisionedThroughputExceededException` / `ThrottlingException`) and rely
+ * solely on the AWS SDK v3 default retry, so the LIBRARY itself guaranteed no
+ * throttle-resilience. The batch ops already retry partial completion
+ * (`UnprocessedKeys` / `UnprocessedItems`, see `src/operations/batch-retry.ts`);
+ * this module is the SEPARATE, library-owned ERROR retry that wraps every
+ * `docClient.send()` for the single ops via {@link RetryingExecutor}.
+ *
+ * The two retry layers are DISTINCT and must not be merged:
+ *  - (A) partial-batch retry (`batch-retry.ts`) — DynamoDB accepted the request
+ *    but could not process every key/item; the request itself did NOT error.
+ *  - (B) error retry (this module) — `send()` REJECTED with a throttle / transient
+ *    error and is retried whole.
+ * They share {@link computeBackoffDelay} so backoff is consistent across both,
+ * but they are different mechanisms.
+ *
+ * The default policy is ENABLED out of the box (see {@link DEFAULT_RETRY_POLICY}):
+ * even with zero configuration a sensible exponential-backoff-with-jitter,
+ * bounded-attempts retry applies. Users tune it globally via
+ * `graphddb.config.retry(...)` or per-call via the `retry?:` option on the
+ * operation option bags; `retry: false` disables retry for that one call.
+ *
+ * NOTE on the AWS SDK's OWN retry: now that the library owns retry, a
+ * `DynamoDBClient` left at the SDK default `maxAttempts: 3` retries
+ * MULTIPLICATIVELY underneath this layer. Users should construct their client
+ * with `maxAttempts: 1` so the library is the single source of truth for retry
+ * (documented at `graphddb.config.client` and in the README). The library does NOT
+ * silently mutate a user-provided client.
+ */
+/** The single-op kind a retry is wrapping — surfaced to {@link RetryPolicy.onRetry}. */
+type RetryOperationKind = 'get' | 'query' | 'batchGet' | 'put' | 'update' | 'delete' | 'batchWrite' | 'transactWrite';
+/** The context handed to {@link RetryPolicy.onRetry} before each backoff sleep. */
+interface RetryInfo {
+    /** 1-based attempt number that just FAILED and is about to be retried. */
+    readonly attempt: number;
+    /** The throttle / transient error that triggered this retry. */
+    readonly error: unknown;
+    /** The backoff delay (ms) about to be slept before the next attempt. */
+    readonly delayMs: number;
+    /** Which single-op kind is being retried. */
+    readonly operation: RetryOperationKind;
+}
+/**
+ * A retry policy for the single-op error-retry layer (issue #111). Every field is
+ * optional and resolved INDEPENDENTLY, in layers (see {@link resolveRetryPolicy}):
+ * a per-call override field wins, else the globally-configured policy's field
+ * (from `graphddb.config.retry`), else
+ * {@link DEFAULT_RETRY_POLICY}. So a partial per-call override (e.g.
+ * `{ maxAttempts: 3 }`) overrides ONLY that field and INHERITS the rest from the
+ * global policy — a global `onRetry` / `jitter` is NOT dropped. A policy value of
+ * `false` on an option bag disables retry entirely for that call.
+ */
+interface RetryPolicy {
+    /**
+     * Maximum number of attempts (the FIRST try counts as attempt 1). `1` disables
+     * retry (a single try, no backoff). Default {@link DEFAULT_MAX_ATTEMPTS}.
+     */
+    readonly maxAttempts?: number;
+    /**
+     * Compute the base backoff delay (ms) for a 1-based retry attempt, BEFORE jitter.
+     * Defaults to {@link computeBackoffDelay} (`min(1000, 50*2^(attempt-1))`), the
+     * same ramp the batch partial-retry layer uses, so backoff is consistent across
+     * the two layers.
+     */
+    readonly computeDelay?: (attempt: number) => number;
+    /**
+     * Jitter strategy applied to the base delay:
+     *  - `'full'` (default) — uniform random in `[0, base]` (AWS "full jitter"),
+     *    the recommended strategy to de-correlate retries across clients.
+     *  - `'none'` — use the base delay verbatim (deterministic; handy in tests).
+     */
+    readonly jitter?: 'full' | 'none';
+    /**
+     * Classify whether an error is retryable. Defaults to {@link isRetryableError}
+     * (throttle + 5xx / transient). A custom classifier fully replaces the default —
+     * it should still avoid retrying validation / conditional-check failures.
+     */
+    readonly isRetryable?: (error: unknown) => boolean;
+    /**
+     * Observability hook (issue #111 §8): invoked BEFORE each backoff sleep with the
+     * attempt number, the triggering error, the computed (post-jitter) delay, and the
+     * operation kind. Never invoked on the terminal success or the terminal failure.
+     */
+    readonly onRetry?: (info: RetryInfo) => void;
+}
 
 /** Result of a read operation (GetItem / Query / BatchGetItem). */
 interface ExecutorResult {
@@ -1057,7 +923,7 @@ interface Executor {
  * registry / runtime machinery the read hooks (#138) introduced.
  *
  * A write {@link Middleware} hook is host-only, runtime-registered (via
- * `DDBModel.use`), and **never serialized** — like the read hooks it lives only on
+ * `graphddb.config.use`), and **never serialized** — like the read hooks it lives only on
  * the {@link import('../client/ClientManager.js').ClientManager} host-runtime
  * singleton and never touches the planner / spec generator / `operations.json`, so
  * the TS↔Python bridge (#48) is unaffected. It is **unrestricted by intent**: a
@@ -1210,7 +1076,7 @@ interface WriteMiddleware {
  * module implements the **read** hook points R1–R5 and their context objects.
  *
  * A {@link Middleware} is a host-only, runtime-registered object (registered via
- * `DDBModel.use`) that runs at fixed seams in the read pipeline. Hooks are
+ * `graphddb.config.use`) that runs at fixed seams in the read pipeline. Hooks are
  * **never serialized** — they live only on the {@link import('../client/ClientManager.js').ClientManager}
  * host-runtime singleton and never touch the planner / spec generator /
  * `operations.json`, so the TS↔Python bridge (#48) is unaffected. Hooks are
@@ -1394,7 +1260,7 @@ type ProjectionOf<T, Sel> = Sel extends SelectableOf<T> ? Sel : SelectOf<Sel>;
  * usages keep compiling, while the precise inference is available when the
  * constructor type is supplied (as it is from `DDBModel.asModel()`).
  */
-type AnyModelClass$1 = abstract new (...args: any[]) => DDBModel;
+type AnyModelClass = abstract new (...args: any[]) => DDBModel;
 /**
  * The accepted PK / GSI key type for `list()` / `explain()`.
  *
@@ -1404,24 +1270,24 @@ type AnyModelClass$1 = abstract new (...args: any[]) => DDBModel;
  * {@link QueryKey}. Derived from the model class when available, otherwise
  * permissive.
  */
-type ListKey<C> = [C] extends [AnyModelClass$1] ? PartialQueryKeyOf<C> : Record<string, unknown>;
+type ListKey<C> = [C] extends [AnyModelClass] ? PartialQueryKeyOf<C> : Record<string, unknown>;
 /**
  * The accepted key type for `query()` — only keys guaranteed to return a
  * single item (PK + unique GSIs). Derived from the model class when available.
  */
-type QueryKey<C> = [C] extends [AnyModelClass$1] ? UniqueQueryKeyOf<C> : Record<string, unknown>;
+type QueryKey<C> = [C] extends [AnyModelClass] ? UniqueQueryKeyOf<C> : Record<string, unknown>;
 /**
  * The accepted key type for `delete()` (PK only). Derived from the model
  * class when available.
  */
-type DeleteKey<C> = [C] extends [AnyModelClass$1] ? PrimaryKeyOf<C> : Record<string, unknown>;
+type DeleteKey<C> = [C] extends [AnyModelClass] ? PrimaryKeyOf<C> : Record<string, unknown>;
 /**
  * The accepted *explicit* key type for `update()` — the base-table primary key
  * only. DynamoDB `UpdateItem` can target an item solely by its base-table PK
  * (GSI-based updates are impossible), so this is `PrimaryKeyOf<C>`, not
  * `UniqueQueryKeyOf<C>`. Derived from the model class when available.
  */
-type UpdateExplicitKey<C> = [C] extends [AnyModelClass$1] ? PrimaryKeyOf<C> : Record<string, unknown>;
+type UpdateExplicitKey<C> = [C] extends [AnyModelClass] ? PrimaryKeyOf<C> : Record<string, unknown>;
 /**
  * Options accepted by `list()` (third argument). The projection is supplied as
  * the separate second `select` argument, symmetric with `query()`.
@@ -1595,145 +1461,6 @@ interface ModelStatic<T extends DDBModel, C = unknown> {
     deleteItem(key: DeleteKey<C>, options?: WriteOptions<T>): Promise<void>;
 }
 
-type TransactWriteItemInput = {
-    Put: PutInput;
-} | {
-    Update: UpdateInput;
-} | {
-    Delete: DeleteInput;
-} | {
-    ConditionCheck: ConditionCheckInput;
-};
-declare function attachModelClass<T extends DDBModel>(modelStatic: ModelStatic<T>, modelClass: new (...args: unknown[]) => T): ModelStatic<T>;
-/**
- * Per-item capture descriptor recorded alongside each transact item, so the
- * write-capture seam (issue #72) can emit a labelled raw record after the
- * transaction commits. `TransactWriteItems` returns no images (spec §14), so
- * these carry the keys + the new item for Put/Update and keys only for Delete.
- */
-interface TransactCaptureMeta {
-    modelName?: string;
-    op: 'put' | 'update' | 'delete';
-    table: string;
-    keys: {
-        pk: string;
-        sk: string;
-    };
-    newItem?: Record<string, unknown>;
-}
-/**
- * One recorded logical write op of an imperative {@link TransactionContext}
- * (issue #139). Captured at `tx.put/update/delete` call time so the write hooks
- * W1 (`write.before`) can run on each op — and rebuild its physical item from the
- * possibly-mutated input — before the batch composes / commits. A `conditionCheck`
- * records NO logical op (it is a read-only assertion, not a logical write).
- */
-interface LogicalWriteOp {
-    kind: WriteKind;
-    modelClass: Function;
-    item?: Record<string, unknown>;
-    key?: Record<string, unknown>;
-    changes?: Record<string, unknown>;
-    options?: PutOptions & UpdateOptions & DeleteOptions;
-}
-declare class TransactionContext {
-    private readonly items;
-    private readonly captureMeta;
-    /**
-     * The logical write ops, parallel to {@link items} but EXCLUDING `conditionCheck`
-     * entries (those are read-only assertions, recorded only in `items`). Used by the
-     * write-hook path (#139) to run W1 on each logical op and recompose the batch.
-     * A `null` entry marks an `items` slot that has no logical op (a ConditionCheck),
-     * so the eager and logical arrays can be re-aligned at commit.
-     */
-    private readonly logicalOps;
-    get itemCount(): number;
-    put(model: ModelStatic<DDBModel>, item: Record<string, unknown>, options?: PutOptions): void;
-    update(model: ModelStatic<DDBModel>, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): void;
-    delete(model: ModelStatic<DDBModel>, key: Record<string, unknown>, options?: DeleteOptions): void;
-    /**
-     * Add a read-only `ConditionCheck` assertion on a keyed item (issue #81). The
-     * item is **not** mutated; the `options.condition` (e.g.
-     * `{ attributeExists: 'PK' }` to require the row exists) is asserted, and a
-     * failed assertion cancels the **whole** `TransactWriteItems` atomically. This
-     * is the foundation for referential-integrity derivation (proposal: `requires
-     * <Entity> exists`). A ConditionCheck emits no change-capture record (it writes
-     * nothing).
-     *
-     * @throws if `options.condition` is missing — a ConditionCheck without an
-     *   assertion is meaningless.
-     */
-    conditionCheck(model: ModelStatic<DDBModel>, key: Record<string, unknown>, options: {
-        condition: Record<string, unknown>;
-    }): void;
-    /** @internal */
-    getTransactItems(): TransactWriteItemInput[];
-    /** @internal — the recorded logical write ops (issue #139 W1), `null` per ConditionCheck slot. */
-    getLogicalOps(): readonly (LogicalWriteOp | null)[];
-    /** @internal — capture descriptors for the write-capture seam (issue #72). */
-    getCaptureMeta(): TransactCaptureMeta[];
-    private assertWithinLimit;
-}
-declare function executeTransaction(fn: (tx: TransactionContext) => void | Promise<void>, options?: {
-    context?: RequestContext;
-}): Promise<void>;
-
-interface BatchGetRequest {
-    model: ModelStatic<DDBModel>;
-    keys: Record<string, unknown>[];
-}
-/**
- * Per-call options for {@link DDBModel.batchGet} (issue #142).
- */
-interface BatchGetOptions {
-    /**
-     * Host-injected per-call read context (issue #50 / #138 / #142) — exposed to
-     * every read hook (R1/R4/R5 at the `batchGet` request level, R2/R3/R5 on each
-     * underlying `BatchGetItem` op) as `ctx.context`, and threaded UNCHANGED to
-     * every physical op so a global hook (e.g. a tenant-scope R2 FilterExpression
-     * or an observability probe) applies across the whole multi-key batch read. A
-     * host-language value, NEVER serialized into the SSoT / `operations.json` (the
-     * bridge #48 is unaffected). Absent ⇒ `{}`.
-     */
-    context?: RequestContext;
-}
-interface BatchPutRequest {
-    type: 'put';
-    model: ModelStatic<DDBModel>;
-    item: Record<string, unknown>;
-    options?: PutOptions;
-}
-interface BatchDeleteRequest {
-    type: 'delete';
-    model: ModelStatic<DDBModel>;
-    key: Record<string, unknown>;
-    options?: DeleteOptions;
-}
-type BatchWriteRequest = BatchPutRequest | BatchDeleteRequest;
-declare class BatchGetResult {
-    private readonly groups;
-    constructor(groups: Map<Function, Record<string, unknown>[]>);
-    get<T extends DDBModel>(model: ModelStatic<T>): Partial<T>[];
-}
-/**
- * The multi-key, multi-model batch-read core (issue #142). Wraps the request
- * entry in the request-level read hooks R1 (`read.before`) / R4
- * (`read.afterFetch`) / R5 (`read.onError`) with request kind `'batchGet'`, and
- * each underlying physical `BatchGetItem` op (per table/chunk) in R2/R3/R5 via
- * {@link executeBatchGetForTable}. The read middleware runtime is built ONCE here
- * from `options.context` and threaded UNCHANGED to every op, so a global hook
- * (e.g. a tenant-scope R2 FilterExpression) applies across the whole batch.
- *
- * R1 sees the mutable batch `requests` on `ctx.params.requests`; the library
- * re-reads them after R1 runs, so a hook may add / drop / mutate requests before
- * any op is issued and may `throw` to cancel the whole batch. R4 may transform /
- * replace the assembled {@link BatchGetResult}; R5 may recover by returning one.
- * With no middleware registered the shared `NO_MIDDLEWARE` runtime keeps the hot
- * path unchanged (the zero-overhead fast path).
- */
-declare function executeBatchGet(requests: BatchGetRequest[], options?: BatchGetOptions): Promise<BatchGetResult>;
-declare function executeBatchWrite(requests: BatchWriteRequest[]): Promise<void>;
-
 /**
  * Intermediate representation (IR) produced by the parameterized definition DSL
  * (issue #41). This is the **in-memory, typed** representation consumed by the
@@ -1831,26 +1558,6 @@ interface ConditionTree<X = never> {
     readonly not?: ConditionInput<X>;
     readonly [field: string]: ConditionLeaf<X> | ConditionOperatorObject<X> | readonly ConditionInput<X>[] | ConditionInput<X> | undefined;
 }
-/** Options accepted by the write `define*` entry points (issue #46). */
-interface WriteDefinitionOptions {
-    /** Optional declarative write condition (subset). */
-    readonly condition?: ConditionInput;
-    /**
-     * Optional human-readable description of the command use case (issue #154). Pure
-     * documentation — propagated to `operations.json` and the generated Python
-     * repository-method docstring. Omit for unchanged output.
-     */
-    readonly description?: string;
-}
-/** Options accepted by the read `define*` entry points (issue #154). */
-interface ReadDefinitionOptions {
-    /**
-     * Optional human-readable description of the query use case (issue #154). Pure
-     * documentation — propagated to `operations.json` and the generated Python
-     * repository-method docstring. Omit for unchanged output.
-     */
-    readonly description?: string;
-}
 /**
  * Identifies the entity an operation targets. `name` is the model class name
  * (entity name); `modelClass` is retained so the planner can resolve metadata
@@ -1896,8 +1603,8 @@ type ParamStructure = {
 /**
  * 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`.
+ * so that all type information survives into the operation IR the contract layer
+ * (`publishQuery` / `publishCommand`) lowers to via `opToDefinition`.
  *
  * Field presence by `operation`:
  *
@@ -1937,7 +1644,7 @@ interface OperationDefinition<T extends DDBModel, Op extends OperationKind, K, S
     readonly condition?: ConditionInput;
     /**
      * Optional human-readable description of the definition (issue #154), supplied
-     * via the entry-point options (`defineQuery(..., { description })` etc.). Pure
+     * via a contract method's `description` field. Pure
      * documentation — propagated to the serialized {@link
      * import('../spec/types.js').QuerySpec.description} /
      * {@link import('../spec/types.js').CommandSpec.description} and to the generated
@@ -1951,62 +1658,7 @@ interface OperationDefinition<T extends DDBModel, Op extends OperationKind, K, S
 }
 /** Any operation definition node, regardless of its type parameters. */
 type AnyOperationDefinition = OperationDefinition<any, OperationKind, unknown, unknown, unknown, Record<string, ParamDescriptor>>;
-/**
- * A map of definition name → {@link OperationDefinition}, as accepted by
- * `defineQueries` / `defineCommands` and returned (unchanged in type) from them.
- */
-type DefinitionMap = Record<string, AnyOperationDefinition>;
 
-/**
- * Model write-semantics — the reusable *save contract* `entityWrites` (issue #83,
- * Epic #80; spec `docs/mutation-command-derivation.md` §2).
- *
- * `Model.writes` declares the **write-side invariants / effects required for this
- * entity to be consistent on DynamoDB** — a *reusable save contract*, NOT a
- * mutation and NOT business logic. It is a per-lifecycle map
- * (`{ create?, update?, remove? }`) whose values are {@link LifecycleContract}s
- * built with `w.lifecycle({...})`; each carries the §2 effect arrays
- * (`requires` / `unique` / `edges` / `derive` / `emits` / `idempotency`).
- *
- * ## What #83 does — and deliberately does NOT — with the effects
- *
- * The mutation compiler (#83) resolves a fragment's lifecycle from this save
- * contract (the fragment's intent — `m.create` / `m.update` / `m.remove` — picks
- * `create` / `update` / `remove`) and emits the **base write op** for that
- * lifecycle (create → `PutItem` with `attribute_not_exists(PK)`, update →
- * `UpdateItem`, remove → `DeleteItem`). The §2 effect arrays are **stored
- * opaquely** here and consumed by NONE of #83: deriving `ConditionCheck`
- * (requires, #84), uniqueness guards (#86), adjacency edge `Put` / `Delete` from
- * `edges` (#85), derived counter `UpdateItem`s (#85), outbox events (#87), and
- * the idempotency guard (#87) are each their own follow-up issue. #83 only shapes
- * the declaration and exposes the {@link LifecycleContract.effects} a later issue
- * reads — the **per-fragment hook** the compiler leaves empty (see
- * `compileFragment` in `src/spec/mutation-command.ts`).
- *
- * ## Coexistence with edge writes (`edgeWrites`, #82)
- *
- * This is a **distinct** construct from {@link edgeWrites} (#82, the adjacency
- * edge-only `writes` member). `edgeWrites` declares *only* the edge write side of
- * an adjacency entity; `entityWrites` is the full per-lifecycle save contract a
- * mutation fragment adopts. Both are recognized by their own brand, so a model
- * may carry either form on its static `writes` member without collision; the
- * mutation compiler reads {@link getEntityWrites} (this marker), the edge
- * derivation reads its own.
- *
- * ## Trivial base op when a model declares no `writes`
- *
- * A target model that declares **no** `entityWrites` save contract has no
- * lifecycle to resolve; the fragment then compiles the **trivial base op** for
- * its intent (create → `Put` `attribute_not_exists(PK)`, update → `Update`,
- * remove → `Delete`) directly against the plain model. So
- * `{ create: () => PostModel, key, input }` works on a bare model — see
- * {@link resolveLifecycle} in `src/spec/mutation-command.ts`.
- */
-/**
- * The lifecycle phase a save contract entry declares. The mutation fragment's
- * intent (`m.create` / `m.update` / `m.remove`) selects the matching entry.
- */
-type WriteLifecyclePhase = 'create' | 'update' | 'remove';
 /**
  * A path-rooted leaf value in a save-contract effect (proposal §2): every value
  * binds to an explicit path root so its source is unambiguous —
@@ -2126,18 +1778,6 @@ declare const MAINTAIN_TRIGGER_BRAND: unique symbol;
 type MaintainTrigger = `${string}.${MaintainEvent}` & {
     readonly [MAINTAIN_TRIGGER_BRAND]: true;
 };
-/**
- * Construct a validated {@link MaintainTrigger} from an `Entity.event` string.
- * Rejects a value that is not a non-empty entity name followed by `.created` /
- * `.updated` / `.removed`, so an invalid trigger is refused at construction time
- * (the AC's "invalid trigger string is rejected"). The brand is a compile-time
- * marker only; the returned value is the input string verbatim.
- *
- * @throws if `value` is not a well-formed `Entity.event` trigger string.
- */
-declare function maintainTrigger(value: string): MaintainTrigger;
-/** Runtime guard: is `value` a well-formed {@link MaintainTrigger} string? */
-declare function isMaintainTrigger(value: unknown): value is MaintainTrigger;
 /**
  * A projection transform op (issue #120, 論点3 = 関数形): the function-form
  * `w.transform(path, op, ...args)` is the **primary** authoring surface (there is
@@ -2502,8 +2142,6 @@ interface LifecycleContract {
     /** 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
@@ -2526,8 +2164,6 @@ interface EntityWritesDefinition {
     /** 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}.
@@ -2654,8 +2290,6 @@ declare function entityWrites<M = unknown>(builder: (w: WriteRecorder) => Entity
  * 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,
@@ -2664,7 +2298,7 @@ declare function lifecyclePhaseForIntent(intent: 'create' | 'update' | 'remove')
  * 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(...)`,
+ * exposed surface is the fixed Command IF (`publishCommand(...).plan(...)`,
  * `src/define/contract.ts`); the mutation document is never exposed.
  *
  * The authoring form (issue #108) is a **descriptor map**: the body returns an
@@ -2715,11 +2349,18 @@ declare function lifecyclePhaseForIntent(intent: 'create' | 'update' | 'remove')
 
 /**
  * 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';
+ * / `upsert` (`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`, upsert → `PutItem`).
+ *
+ * `upsert` is a `PutItem` with **no** `attribute_not_exists(PK)` guard — an
+ * unconditional overwrite (the semantics of the removed `definePut`). It shares
+ * `create`'s base op (`put`) and lifecycle phase (a Put's derived effects are the
+ * same), but the trivial base op carries no existence guard: an author-supplied
+ * `condition` is honored verbatim (not ANDed with a `notExists`). That absence of
+ * the guard is exactly what distinguishes an `upsert` from a `create`.
+ */
+type MutationIntent = 'create' | 'update' | 'remove' | 'upsert';
 declare const INPUT_REF_BRAND: unique symbol;
 /**
  * A faithful reference to a mutation **input** field, minted by reading `$.<field>`
@@ -2736,8 +2377,6 @@ interface MutationInputRef {
     /** 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
@@ -2759,32 +2398,6 @@ interface MutationEntityRef {
     /** The source path, e.g. `$.entity[0].postId` (documentary; surfaces in errors). */
     readonly path: string;
 }
-/**
- * The placeholder proxy handed to a mutation body as `$`. In the descriptor-map
- * authoring form (issue #108) a top-level read `$.<x>` is **ambiguous** until used:
- *
- *  - `$.role` placed at a `key` / `input` leaf is an **input-field reference**
- *    (a {@link MutationInputRef}, token `{role}`) — bound from the command input;
- *  - `$.membership.role` is a **cross-fragment reference** — the `role` field
- *    written by the fragment named `membership` (an alias). It mints an
- *    {@link AliasFieldRef}, which the {@link mutation} assembler rewrites into the
- *    legacy `$.entity[<index>].<field>` string the compiler resolves (the alias →
- *    declaration-order index is known once every alias key is seen).
- *
- * So each top-level read returns a value that is **both** a faithful
- * {@link MutationInputRef} (when used directly as a leaf) and supports one further
- * `.<field>` access (when used as an alias root). Any other access / coercion
- * throws — the binding stays declarative (only a direct `$.field` / `$.alias.field`
- * reference or a literal is representable, never a transform).
- *
- * **Input Port 統一 (issue #264)**: this proxy is one of the three authoring
- * spellings of the SAME Input Port reference model — see the unification note
- * on {@link import('./transaction.js').ParamProxy} (`defineTransaction`'s
- * `p.*` proxy is the model; `{<field>}` templates and `{ref:["input","<field>"]}`
- * expression refs are the two serialized mirrors of one declared-input
- * namespace). Behavior here is unchanged in 0.7.x (interop kept).
- */
-type MutationInputProxy = Record<string, MutationInputRef>;
 declare const FRAGMENT_BRAND: unique symbol;
 /**
  * The per-field input binding of a fragment: model field name → a faithful
@@ -2793,14 +2406,6 @@ declare const FRAGMENT_BRAND: unique symbol;
  * field they key, never a transform.
  */
 type FragmentInput = Readonly<Record<string, MutationInputRef | string | number | boolean | Date | null>>;
-/**
- * A descriptor `key` / `input` value as authored in the descriptor-map form
- * (issue #108): a `$.field` input reference, a `$.alias.field` cross-fragment
- * reference (an opaque alias-field ref the assembler rewrites), or a literal.
- * Structurally `unknown` at the leaf because the alias-field ref is internal; the
- * assembler validates every leaf via {@link assertFaithfulInput}.
- */
-type DescriptorBinding = Readonly<Record<string, unknown>>;
 /** A concrete scalar admissible at a condition operand leaf. */
 type ConditionScalar = MutationInputRef | string | number | boolean | Date | null;
 /** A declarative operator object on one condition field (the #114-A subset). */
@@ -2820,8 +2425,8 @@ interface FragmentConditionOperatorObject {
 }
 /**
  * A declarative write **condition** authored on a {@link WriteDescriptor} (issue
- * #242, Phase 2) — the same #114-A subset the #101 public write descriptor and
- * `defineCommands` support, but with {@link MutationInputRef} (`$.field`) leaves
+ * #242, Phase 2) — the same #114-A subset the #101 public write descriptor
+ * supports, but with {@link MutationInputRef} (`$.field`) leaves
  * (the mutation authoring form's placeholder) rather than `param.*` / concrete
  * values. It is a recursive tree of field clauses (bare equality or an operator
  * object) and `and` / `or` / `not` logical groups. The compiler translates each
@@ -2874,8 +2479,6 @@ interface MutationFragment {
      */
     readonly condition?: FragmentCondition;
 }
-/** Runtime guard: is `value` a {@link MutationFragment}? */
-declare function isMutationFragment(value: unknown): value is MutationFragment;
 /**
  * A model reference in a write descriptor (issue #108): either the model class /
  * `.asModel()` value **directly** (`{ create: GroupMembership }`) or a **thunk**
@@ -2885,60 +2488,6 @@ declare function isMutationFragment(value: unknown): value is MutationFragment;
  * `m.create(() => Model, …)` recorder required.
  */
 type ModelRef = ModelStatic<DDBModel> | (new (...args: unknown[]) => unknown) | (() => ModelStatic<DDBModel> | (new (...args: unknown[]) => unknown));
-/**
- * One **write descriptor** in the descriptor-map authoring form (issue #108) —
- * the declarative twin of an in-process `DDBModel.mutate` entry (#101). The intent
- * key (`create` / `update` / `remove`) is the **discriminator** and carries the
- * target {@link ModelRef} (direct or thunk). The remaining fields are declarative
- * bindings (`$.field` references or literals):
- *
- *  - `key` — the target row's primary-key binding (identifies the row);
- *  - `input` — the non-key field binding (the body / changed fields). Optional for
- *    a `remove` (a delete writes no fields);
- *  - `condition` — an optional declarative write gate (issue #242, Phase 2). It is
- *    the #114-A condition subset (bare equality, operator objects `{ gt }` / `{ in }`
- *    / `{ between }` / …, and `and` / `or` / `not` groups) whose operand leaves are
- *    `$.field` input references or literals. The declaration-DSL compiler **consumes**
- *    it: each `$.field` leaf becomes a {@link import('./contract.js').ContractParamRef}
- *    and the tree is attached to the compiled base op's `condition`, so it is
- *    serialized (into the operation spec) and evaluated at runtime exactly as a #101
- *    public write descriptor's / `defineCommands` condition is (single-op, in-process
- *    transaction, and the Python bridge). A conditioned `update` / `remove` therefore
- *    fails a CAS-style write when the gate does not hold, rather than silently
- *    committing;
- *  - `result` — an optional read-back projection `{ select, options? }` (likewise
- *    accepted for authoring parity; the public read-back projection of a
- *    `command(...).plan(...)` method is still declared on `command({ select })`).
- *
- * Exactly one intent key must be present.
- */
-interface WriteDescriptor {
-    readonly create?: ModelRef;
-    readonly update?: ModelRef;
-    readonly remove?: ModelRef;
-    /** The target row's primary-key binding (`{ field: $.field | literal }`). */
-    readonly key: DescriptorBinding;
-    /** The non-key field binding; optional (a `remove` writes no fields). */
-    readonly input?: DescriptorBinding;
-    /**
-     * Optional declarative write gate — the #114-A condition subset (issue #242,
-     * Phase 2). Compiled, serialized, and evaluated at runtime; see the interface doc.
-     */
-    readonly condition?: FragmentCondition;
-    /** Optional read-back projection `{ select, options? }` (accepted for #101 parity). */
-    readonly result?: {
-        readonly select?: unknown;
-        readonly options?: unknown;
-    };
-    /**
-     * Optional custom save contract to adopt (the **whole** {@link
-     * EntityWritesDefinition}). Omit to default to the target model's own `writes`.
-     * Per the `use:` rule this is never a single lifecycle — the intent picks it.
-     */
-    readonly use?: EntityWritesDefinition;
-}
-/** The descriptor map a {@link mutation} body returns: alias → {@link WriteDescriptor}. */
-type MutationDescriptorMap = Record<string, WriteDescriptor>;
 declare const COMMAND_PLAN_BRAND: unique symbol;
 /**
  * The recorded **CommandPlan** — a mutation's IR (proposal §3). It carries the
@@ -2954,54 +2503,187 @@ interface CommandPlan {
     /** The declared write fragments, in declaration order (the mutation IR). */
     readonly fragments: readonly MutationFragment[];
 }
-/** Runtime guard: is `value` a {@link CommandPlan} (a `mutation(...)` result)? */
-declare function isCommandPlan(value: unknown): value is CommandPlan;
+
 /**
- * The body of a {@link mutation} in the descriptor-map authoring form (issue #108):
- * `$ => ({ alias: descriptor, … })`. It receives the placeholder proxy `$` and
- * returns an **alias → {@link WriteDescriptor}** map. The map's **insertion order**
- * is the fragments' declaration (execution) order, and each alias is the name a
- * later descriptor's `$.alias.field` cross-fragment reference resolves against.
+ * Declarative transaction definition DSL (issue #46, Python-bridge Phase 4).
+ *
+ * `defineTransaction(params, (tx, p) => { … })` captures a **single source of
+ * truth** for a `TransactWriteItems` batch: a parameter map plus a declarative
+ * instruction list (`tx.put` / `tx.update` / `tx.delete`, plus `tx.forEach` over
+ * an array param). The callback is evaluated at definition time with sentinel
+ * proxies in place of params / loop elements, so the recorded instructions carry
+ * **field-reference templates** (`{groupId}`, `{item.userId}`) rather than
+ * concrete values — exactly the shape the static planner (#42) turns into a
+ * serializable `transaction` op the TS and Python runtimes expand identically.
+ *
+ * ## Declarativity boundary (enforced — same soundness as #42 keys)
+ *
+ * The callback body may only:
+ *  - call `tx.put/update/delete(Model, …)` with **field references** (from `p`
+ *    or a `forEach` element) or **concrete literals** at scalar leaves;
+ *  - call `tx.forEach(p.<arrayParam>, (el) => { … }, { when? })` whose body is
+ *    itself only `tx.*` writes;
+ *  - attach a declarative `when` (a small comparison over field refs) and/or a
+ *    `condition` (the `{ notExists } | equality` subset, as for single writes).
+ *
+ * The same hardening that protects **key** positions (#42 `src/spec/symbolic.ts`)
+ * is applied to **value** positions (item / changes / condition values, `when`
+ * right-hand side). Value positions are in fact held to a *stricter* boundary
+ * than keys: a key may legitimately interpolate a field (`` `USER#${id}` ``), so
+ * coercion is allowed there and the differential template check is the boundary;
+ * a value leaf may **only** be a *direct* field reference or a concrete literal,
+ * so at a value position a faithful reference is **never coerced**. That single
+ * fact is the soundness boundary:
+ *
+ *  1. **Throwing sentinel Proxy.** Each param / element placeholder is a Proxy
+ *     whose `get` trap whitelists only primitive coercion
+ *     (`Symbol.toPrimitive` / `toString` / `valueOf`) and the brand / `token` /
+ *     `origin` reads the planner needs, and **throws on every other property or
+ *     method access**. So a *direct* transform on a value placeholder —
+ *     `p.role.length`, `p.role[0]`, `p.role.toUpperCase()` — fails at the access
+ *     site, exactly like a key sentinel. (Same first-line defense as #42.)
+ *  2. **Per-access coercion ledger (primary boundary).** Every minted field ref
+ *     records each time it is coerced to a primitive (`Symbol.toPrimitive` /
+ *     `toString` / `valueOf`). Because a faithful value reference is stored as
+ *     the Proxy *object* and never coerced, **any** coercion of a value ref is
+ *     positive proof the callback consumed the parameter into a transform, a
+ *     branch, an interpolation, or a comparison — and the build is rejected. This
+ *     is *access-site* accurate: it fires even when the same field is *also*
+ *     referenced faithfully elsewhere in the item (so its token still surfaces),
+ *     and it catches transforms that **converge to a constant or a shared marker
+ *     fragment** — `String(p.role).slice(0,0)` → `''`, `.slice(0,3)` → a shared
+ *     prefix, `[0]` / `.charAt(0)`, `.includes('Tx')` → a constant boolean, any
+ *     `… + 'CONST'` built atop them — which a purely output-comparing check could
+ *     not (the dropped field is masked by its faithful sibling, and the converged
+ *     value is byte-identical across passes).
+ *  3. **Differential evaluation (secondary).** The callback is evaluated **twice**,
+ *     each run delivering placeholders that coerce to a *different* per-field
+ *     marker (the two markers share no common prefix and no common substring of
+ *     length ≥ 2, and differ in length). Every recorded value leaf must be either
+ *     (a) a faithful field reference (the Proxy object survived intact in *both*
+ *     runs) or (b) a concrete literal byte-identical across both runs. This is a
+ *     defense-in-depth layer behind the coercion ledger.
+ *  4. **Consumed-field check.** A placeholder field that the callback *accessed*
+ *     but that never reached the recorded output — e.g. `(p.role === 'admin') ?
+ *     'A' : 'B'`, where `===` does **not** coerce (so the ledger does not fire),
+ *     the comparison is `false`, and only a literal is emitted — is rejected: the
+ *     param was silently dropped and a branch burned into the spec. (Same
+ *     consumed-field accounting #42 uses for `kind === 'admin' ? … : …`.)
+ *
+ * Arbitrary JS, reads, value branching, arithmetic, coercion, or string
+ * transforms on a param / element placeholder are therefore rejected at build
+ * time, in **both** key and value positions — **never silently emitted as a
+ * wrong spec**. Unlike key positions, value positions have **no residual class**:
+ * because a faithful value ref is never coerced, even an identity-shaped
+ * transform (`String(p.x).slice(0)`, `.normalize()`, `.trim()`, `.replace('§',…)`
+ * on an absent substring) is rejected (it coerced the ref). The only operations
+ * that *do not* coerce a ref are (a) storing it directly and (b) the brand read;
+ * (a) is the supported faithful reference and (b) is internal — so the ledger has
+ * no false positives and no escape.
  */
-type MutationBody = ($: MutationInputProxy) => MutationDescriptorMap;
+
+declare const TX_REF_BRAND: unique symbol;
 /**
- * Declare an internal **mutation** — a write-plan composition in the descriptor-map
- * authoring form (issue #108). The body returns an **alias → {@link WriteDescriptor}**
- * map; each descriptor names its target via the intent key (`create` / `update` /
- * `remove`: a model or a `() => Model` thunk) and binds `key` / `input` with `$.field`
- * placeholders. Insertion order is execution order, and a later descriptor may read
- * an earlier one's written field via `$.alias.field`.
- *
- * ```ts
- * const JoinGroup = mutation($ => ({
- *   membership: { create: GroupMembership, key: { groupId: $.groupId, userId: $.userId }, input: { role: $.role } },
- *   permission: { create: Permission,      key: { id: $.permissionId }, input: { groupId: $.membership.groupId } },
- * }));
- * ```
- *
- * A leading **name** is optional (it surfaces only in compiler error messages — the
- * alias map already names each fragment): `mutation('JoinGroup', $ => ({ … }))`.
- *
- * The result is a branded {@link CommandPlan} (the mutation IR) — *not* public; it
- * implements a Command IF via `publicCommandModel(...).plan(mutation)`. The IR shape
- * (`{ name, fragments }`) is unchanged from the legacy recorder form, so the compiler,
- * serializer, and every runtime consume it identically.
- *
- * @throws if the body returns a non-object / empty map, a descriptor has no (or
- *   multiple) intent key(s), a binding is non-declarative, or a `$.alias.field`
- *   reference names an unknown alias.
+ * A captured reference to a parameter (`{name}`) or a `forEach` element field
+ * (`{item.<field>}`). Branded so the planner can distinguish a reference from a
+ * concrete literal, and so a stray reference cannot be silently coerced.
  */
-declare function mutation(body: MutationBody): CommandPlan;
-declare function mutation(name: string, body: MutationBody): CommandPlan;
+interface TransactionRef {
+    readonly [TX_REF_BRAND]: true;
+    /** The template token this reference renders to, e.g. `{groupId}`. */
+    readonly token: string;
+    /** Human-readable origin (for error messages), e.g. `param 'groupId'`. */
+    readonly origin: string;
+}
+/** A declarative comparison used by `when` (the only branching allowed). */
+type WhenComparison = {
+    readonly op: 'eq';
+    readonly left: TransactionRef;
+    readonly right: unknown;
+} | {
+    readonly op: 'ne';
+    readonly left: TransactionRef;
+    readonly right: unknown;
+};
 /**
- * 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.
+ * A single captured instruction inside a transaction. The three write operations
+ * (`put` / `update` / `delete`) mutate an item; `conditionCheck` (issue #81) is a
+ * **read-only assertion** on another keyed item — it carries a `key` and a
+ * **required** `condition` and never mutates, but its failure rolls the whole
+ * transaction back. It is the foundation for referential-integrity derivation
+ * (`requires <Entity> exists` → a `conditionCheck` with `attributeExists`).
  */
-declare const definePlan: typeof mutation;
+interface TxWriteInstruction {
+    readonly kind: 'write';
+    readonly operation: 'put' | 'update' | 'delete' | 'conditionCheck';
+    readonly entity: EntityRef;
+    /** Put: the item structure (field → ref / literal). */
+    readonly item?: Record<string, unknown>;
+    /** Update / delete / conditionCheck: the key structure. */
+    readonly key?: Record<string, unknown>;
+    /** Update: the changes structure. */
+    readonly changes?: Record<string, unknown>;
+    /**
+     * The write / assertion condition (subset). Optional on `put` / `update` /
+     * `delete`; **required** on a `conditionCheck` (the assertion it makes).
+     *
+     * A tx condition operand may be a `p.*` field reference ({@link
+     * TransactionRef}) — the serializer renders it to a `{ $param }` marker — so
+     * the recorded leaf type is widened with `TransactionRef` in the tx context
+     * (#246), matching what the recorder captures from {@link TxWriteOptions}.
+     */
+    readonly condition?: ConditionInput<TransactionRef>;
+    /** Optional declarative guard (skip this item when it does not hold). */
+    readonly when?: WhenComparison;
+    /**
+     * Optional SCP expression guard (issue #261, Phase 3 S1): a behavior-contracts
+     * Expression IR `{ exprVersion: 1, expr }` envelope, carried beside the legacy
+     * `when`. Validated + canonicalized by the spec serializer; a bundle carrying
+     * one is stamped spec version 1.2 and loud-rejected by runtimes whose
+     * expression evaluation has not landed yet (fail-closed).
+     */
+    readonly guard?: ExpressionSpec;
+}
+/** A `forEach` block expanding `body` once per element of an array param. */
+interface TxForEachInstruction {
+    readonly kind: 'forEach';
+    /** The array-param name iterated. */
+    readonly source: string;
+    /** Optional per-element declarative guard. */
+    readonly when?: WhenComparison;
+    /** The (write-only) instructions emitted per element. */
+    readonly body: TxWriteInstruction[];
+}
+type TxInstruction = TxWriteInstruction | TxForEachInstruction;
+/** A small comparison helper: `when.eq(ref, value)` / `when.ne(ref, value)`. */
+declare const when: {
+    readonly eq: (left: TransactionRef, right: unknown) => WhenComparison;
+    readonly ne: (left: TransactionRef, right: unknown) => WhenComparison;
+};
+/** The typed IR node produced by {@link defineTransaction}. */
+interface TransactionDefinition {
+    /** @internal Marks this object as a transaction definition IR node. */
+    readonly __isTransactionDefinition: true;
+    /** Collected parameters: name → descriptor (array params carry `element`). */
+    readonly params: Readonly<Record<string, ParamDescriptor>>;
+    /** The captured, declarative instruction list. */
+    readonly instructions: readonly TxInstruction[];
+    /**
+     * The **atomicity mode** the author declared, sourced from the authoring call
+     * — the `mutate(body, { mode })` alias records it here. **Never defaulted**
+     * (Phase 4 S3.5): graphddb does not decide/default atomicity; whether a
+     * command body is a single `TransactWriteItems` is up to the model definition
+     * (whether its `mutate` asked for `{ mode: 'transaction' }`). `defineTransaction`
+     * / `defineScpTransaction` leave it `undefined`; the `mutate` alias stamps it
+     * from the authoring `{ mode }` option; `publishCommand`'s SCP-body branch reads
+     * it to decide the wire `single` resolution (undefined ⇒ non-atomic, atomicity
+     * being the sole home of `{ mode: 'transaction' }`).
+     */
+    readonly mode?: MutateMode;
+}
 
 /**
- * Contract DSL — `publicQueryModel` / `publicCommandModel` (issue #58, CQRS
+ * Contract DSL — `publishQuery` / `publishCommand` (issue #58, CQRS
  * Contract layer, Epic #57; spec `docs/cqrs-contract.md`).
  *
  * A **QueryModel / CommandModel** is the public, storage-independent interface
@@ -3010,15 +2692,15 @@ declare const definePlan: typeof mutation;
  * `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
+ * This module is the SOLE read/write authoring surface (#251: the define*
+ * single-op DSL was removed). It builds on the shared operation IR
+ * ({@link OperationDefinition}) that the spec builders (`buildQuerySpec` /
+ * `buildCommandSpec`) consume. 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>()({
+ * const ArticleById = publishQuery<ArticleIdKey>()({
  *   get: (keys, params) =>
  *     Article.query(keys, { articleId: true, title: true, body: true }, params),
  * });
@@ -3154,7 +2836,6 @@ type QueryMethod<TKey, TParams, TResult> = (key: TKey | readonly TKey[], params:
  */
 type CommandMethod<TKey, TParams, TResult> = (key: TKey | readonly TKey[], params: TParams) => TResult;
 declare const KEY_REF_BRAND: unique symbol;
-declare const KEY_FIELD_REF_BRAND: unique symbol;
 /**
  * The captured `keys` argument of a contract method body. A branded sentinel that
  * supports the two faithful uses the proposal's examples need:
@@ -3173,80 +2854,7 @@ declare const KEY_FIELD_REF_BRAND: unique symbol;
 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$1: 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$1]: 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
@@ -3262,93 +2870,8 @@ declare const COMPOSE_NODE_BRAND: unique symbol;
 interface ContractFromRef {
     readonly [FROM_REF_BRAND]: true;
     /** The `$`-rooted source path on the parent result, e.g. `$.billingAccountId`. */
-    readonly path: string;
-}
-/** Runtime guard: is `value` a {@link ContractFromRef} (a `from(...)` binding)? */
-declare function isContractFromRef(value: unknown): value is ContractFromRef;
-/**
- * A resolved External Query composition node produced by {@link query} and placed
- * at a `select` property of a contract method body (proposal "External Query"):
- *
- * ```ts
- * Account.query(keys, {
- *   accountId: true,
- *   billing: query(BillingPlanQueries.get, { accountId: from("$.billingAccountId") }),
- * })
- * ```
- *
- * It carries a faithful reference to the **referenced method spec** (so the
- * serializer can recover the referenced contract's *name* by identity against the
- * contract map, and its derived `resolution` / `cardinality` facts) plus the
- * declarative child-key binding (child key field → a {@link ContractFromRef}).
- * The owning `select` key becomes the composition's `as` property at record time
- * (it is not known to {@link query} itself).
- */
-interface ContractComposeNode {
-    readonly [COMPOSE_NODE_BRAND]: true;
-    /** The referenced query method spec (`OtherContract.method`). */
-    readonly method: QueryMethodSpec<unknown, unknown, unknown>;
-    /** The child-key binding: child key field → parent-result `from` path. */
-    readonly bind: Readonly<Record<string, ContractFromRef>>;
-}
-/** Runtime guard: is `value` a {@link ContractComposeNode} (a `query(...)` node)? */
-declare function isContractComposeNode(value: unknown): value is ContractComposeNode;
-/**
- * Declare a parent-result source path for an External Query child key binding
- * (proposal "External Query"). Used **only** inside a {@link query} binding:
- *
- * ```ts
- * query(BillingPlanQueries.get, { accountId: from("$.billingAccountId") })
- * ```
- *
- * The path is `$`-rooted (the parent record) and dotted; the bound child-key
- * field is read from that path of each resolved parent record at execution time.
- * The binding is **declarative** — `from` accepts only a literal path string and
- * rejects any other shape, so no arbitrary JS can sneak into a key binding.
- *
- * @param path A `$`-rooted dotted path, e.g. `"$.billingAccountId"` or `"$.a.b"`.
- * @throws if `path` is not a non-empty `$`-rooted dotted field path.
- */
-declare function from(path: string): ContractFromRef;
-/**
- * Reference another query contract's method as an **External Query** composition
- * child, bound to the parent result by a declarative `from` mapping (proposal
- * "Query Composition" / "External Query"). Place the result at a `select`
- * property of a contract method body; the property name becomes the composed
- * value's `as`:
- *
- * ```ts
- * export const AccountAccess = publicQueryModel<AccountKey>()({
- *   get: (keys, params) => Account.query(keys, {
- *     accountId: true,
- *     billing: query(BillingPlanQueries.get, { accountId: from("$.billingAccountId") }),
- *   }, params),
- * });
- * ```
- *
- * This is **build-time-resolved, in-process** contract chaining — the relation
- * primitive extended to point at another contract's method instead of a model
- * relation. There is no protocol / transport: the runtime collects every bound
- * key produced by the parent step and resolves the referenced contract **once,
- * batched** (proposal "External Query"). The child MUST be `point` (the parent
- * may yield N records, so a `range` child would be an N+1 fan-out) — that rule is
- * owned by the N+1 checker (#60), which rejects a `range` child at build time.
- *
- * @param method  The referenced query method (`OtherContract.method`), a resolved
- *   {@link QueryMethodSpec}.
- * @param bind    The child-key binding: child key field → a {@link from} path on
- *   the parent result. Must be non-empty and every value a `from(...)` ref.
- * @throws if `method` is not a query method spec, or `bind` is empty / carries a
- *   non-`from` value.
- */
-declare function query(method: QueryMethodSpec<any, any, any>, bind: Record<string, ContractFromRef>): ContractComposeNode;
-/**
- * The {@link QueryModelContract} that owns a resolved query method spec, or
- * `undefined` if the spec was not produced by {@link publicQueryModel} (so it has
- * no registered owner). Used by the serializer to resolve a composition's
- * referenced contract by identity.
- */
-declare function contractOfMethodSpec(method: QueryMethodSpec<unknown, unknown, unknown>): QueryModelContract<unknown, Record<string, QueryMethodSpec<unknown, unknown, unknown>>> | undefined;
+    readonly path: string;
+}
 /**
  * The declarative internal operation a contract method body resolves to — the
  * resolved declaration captured into the IR (the closure itself is discarded).
@@ -3375,7 +2898,7 @@ interface ContractMethodOp<Op extends OperationKind = OperationKind> {
     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).
+     * key-field argument (`publishQuery<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
@@ -3387,7 +2910,7 @@ interface ContractMethodOp<Op extends OperationKind = OperationKind> {
      *
      * 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
+     * when no explicit list was given to a `publishQuery<TKey>()` whole-key form
      * (the legacy backward-compatible path, which then defaults to the primary key).
      */
     readonly keyFields?: readonly string[];
@@ -3414,6 +2937,15 @@ interface ContractMethodOp<Op extends OperationKind = OperationKind> {
      * recorded operation, key, or runtime behaviour.
      */
     readonly description?: string;
+    /**
+     * Optional per-param descriptions (issue #154), keyed by param / key-field name,
+     * captured from a descriptor leaf's `param.*({ description })`. Pure documentation
+     * — carried on the op so the serializer ({@link import('../spec/contracts.js')})
+     * can seat each into the flattened definition's `ParamDescriptor.description`, so a
+     * documented contract param surfaces in `operations.json` (`params.field.description`)
+     * exactly as the removed define* param did. Never affects the recorded operation.
+     */
+    readonly paramDescriptions?: Readonly<Record<string, string>>;
 }
 /**
  * A recorded External Query composition edge on a contract method op (#63). The
@@ -3432,33 +2964,6 @@ interface RecordedCompose {
     /** The child-key binding: child key field → parent-result `from` path. */
     readonly bind: Readonly<Record<string, ContractFromRef>>;
 }
-/**
- * The **call signature** a contract method exposes to a caller, narrowed by its
- * decided {@link InputArity} — the type-level half of N+1 rule (a) ("array into a
- * `range` method", #60). Given a method's `inputArity`:
- *
- * - `'single'` (a `range` method) — the key argument is a **single** `TKey` only;
- *   passing an array (`readonly TKey[]`) is a **type error** by construction, so a
- *   `range` method's array overload does not type-check.
- * - `'either'` (a `point` read / known-key write) — a single key **or** an array
- *   (the array form coalesces to one `BatchGetItem` / batched write).
- * - `'array'` — an array only (reserved; not produced by the current resolvers).
- *
- * This mirrors the proposal's "the generated binding's types encode `inputArity`
- * (single → bare argument, array → array argument)". It is the type-level narrowing
- * used by the runtime call surface (`executeQueryMethod`, `src/runtime/contract-runtime.ts`):
- * the executor keys its key-argument type on the named method's **literal** arity
- * `A` (carried on {@link QueryMethodSpec} when the body is tagged with
- * {@link point} / {@link range}), so feeding an array into a `'single'` method is a
- * `tsc` compile error — the **primary** N+1 rule (a) layer, complementing the
- * build-time SSoT check ({@link assertContractN1Safe}) and the runtime backstop.
- *
- * @typeParam A       - The decided input arity (a literal `InputArity`).
- * @typeParam TKey    - The contract Key.
- * @typeParam TParams - The method's params type.
- * @typeParam TResult - The method's result type.
- */
-type ContractCallSignature<A extends InputArity, TKey, TParams, TResult> = (key: A extends 'single' ? TKey : A extends 'array' ? readonly TKey[] : TKey | readonly TKey[], params: TParams) => TResult;
 /**
  * The resolved IR of one **query** method. Carries the formal method type at the
  * type level (`QueryMethod<TKey, TParams, TResult>`) and, at runtime, the resolved
@@ -3516,8 +3021,29 @@ interface QueryMethodSpec<TKey, TParams, TResult, A extends InputArity = InputAr
 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;
+    /**
+     * The resolved internal write operation (closure discarded). Present on every
+     * descriptor- / mutation-authored method (the entity the method is keyed by /
+     * reads back from). **Absent** on an SCP-transaction-authored method (Phase 4
+     * S1, issue #278): a native-syntax multi-write body has no single primary
+     * entity, so it carries a pre-built {@link transaction} instead — the
+     * serializer branches on `transaction` before ever reading `op`.
+     */
+    readonly op?: ContractMethodOp;
+    /**
+     * The pre-built {@link TransactionSpec} of an **SCP-transaction-authored**
+     * command method (Phase 4 S1, issue #278). When a `publishCommand` method
+     * body is a {@link TransactionDefinition} (produced by `defineScpTransaction`
+     * — whose native `$`/`?:`/`&&`/`.map` body the `transformScpTransactionSource`
+     * pass has already lowered onto the recorder seams), it is compiled here by the
+     * SAME {@link import('../spec/transaction.js').buildTransactionSpec} the
+     * standalone `defineScpTransaction` path uses, so the emitted `TransactionSpec`
+     * is **byte-identical** to the equivalent standalone transaction. Present only
+     * for this authoring form; a descriptor / mutation method omits it (and carries
+     * {@link op} instead). The atomicity **mode** flows through {@link mode}
+     * (default `'transaction'`); the full verb/mode consolidation is Phase 4 S6.
+     */
+    readonly transaction?: TransactionSpec;
     /**
      * Derived input arity: a single key maps to one write op; an array maps to a
      * batched write (a transaction / `BatchWriteItem`). Writes accept `'either'`.
@@ -3699,10 +3225,6 @@ interface CommandModelContract<TKey, M extends Record<string, CommandMethodSpec<
     /** @internal Phantom carrier retaining the contract Key type `TKey`. */
     readonly __keyType?: (value: TKey) => void;
 }
-/** Runtime guard: is `value` a {@link QueryModelContract}? */
-declare function isQueryModelContract(value: unknown): value is QueryModelContract<unknown, Record<string, QueryMethodSpec<unknown, unknown, unknown>>>;
-/** Runtime guard: is `value` a {@link CommandModelContract}? */
-declare function isCommandModelContract(value: unknown): value is CommandModelContract<unknown, Record<string, CommandMethodSpec<unknown, unknown, unknown>>>;
 /** The entity type a descriptor {@link ModelRef} (model class / `.asModel()` / thunk) targets. */
 type EntityOfRef<M> = M extends ModelStatic<infer T, infer _C> ? T : M extends abstract new (...args: never[]) => infer T ? T : M extends () => infer R ? EntityOfRef<R> : unknown;
 /** The projected item type for an entity `T` and a select `S` (relation-nest aware). */
@@ -3713,6 +3235,82 @@ type LeafValueOf<L> = L extends Param<infer V> ? V : L;
 type KeyOf<KeyRec> = {
     readonly [F in keyof KeyRec]: LeafValueOf<KeyRec[F]>;
 };
+/** String-like scalar leaf types that accept a `Param<string>` placeholder (a Date /
+ * binary field crosses the param boundary as a string — `param` has no `datetime`
+ * builder, so it is authored via `param.string()`). */
+type StringLike = Date | Uint8Array;
+/** Scalar leaf types (a `param.*` placeholder replaces the leaf, never recursed). */
+type ScalarLeaf = string | number | boolean | bigint | symbol | StringLike;
+/** `null` / `undefined` — peeled off an optional leaf before the scalar test. */
+type Nullish = null | undefined;
+/**
+ * The relaxed leaf type for a scalar `V`: the concrete value plus a matching
+ * {@link Param} placeholder. A `string` / `number` / literal-union leaf `V` yields
+ * `V | Param<V>` (tuple-wrapped below so a literal union is NOT distributed — the
+ * whole-union `Param<'a' | 'b'>` fits, the #246 fix). A `Date` / `Uint8Array` leaf
+ * additionally admits a `string` / `Param<string>` (its param-boundary form).
+ */
+type ParamLeaf<V> = [V] extends [StringLike] ? V | string | Param<string> : V | Param<V>;
+/**
+ * Relaxes a real input type `K` so each scalar leaf additionally accepts a
+ * {@link Param} standing in for that leaf's value type, while field names and value
+ * types stay checked. The scalar test uses a **tuple wrap** so it does NOT distribute
+ * over a literal-union leaf — a `'a' | 'b'` field yields the whole-union placeholder
+ * `Param<'a' | 'b'>` (what `param.literal('a','b')` produces), the #246 fix. `Param`
+ * covariance still admits a single-member subset placeholder, while a value outside
+ * the union / a wider placeholder / a wrong scalar kind stays a type error.
+ */
+type Parameterize<K> = [Exclude<K, Nullish>] extends [ScalarLeaf] ? [Exclude<K, Nullish>] extends [never] ? K : ParamLeaf<Exclude<K, Nullish>> | Extract<K, Nullish> : K extends object ? {
+    [P in keyof K]: Parameterize<K[P]>;
+} : K;
+/** Union of all keys across every member of a (possibly union) `Real` type. */
+type KnownKeyOf<Real> = Real extends object ? keyof Real : never;
+/** The value type of key `P` across the members of a (possibly union) `Real`, non-nullable. */
+type NonNullableMember<Real, P extends PropertyKey> = NonNullable<Real extends object ? (P extends keyof Real ? Real[P] : never) : never>;
+/**
+ * Call-site excess-property guard for a parameterized structure (issue #41): maps
+ * every key of the inferred `K` that is NOT a known key of `Real` to `never`, so a
+ * stray field forces a compile error. Applied as `input & ExactParam<Real, input>`.
+ */
+type ExactParam<Real, K> = Real extends object ? {
+    [P in keyof K]: P extends KnownKeyOf<Real> ? K[P] extends Param<unknown> ? K[P] : K[P] extends object ? K[P] & ExactParam<NonNullableMember<Real, P>, K[P]> : K[P] : never;
+} : K;
+/**
+ * The model-aware constraint for a write descriptor's `input` given the descriptor
+ * `D` — `Parameterize<Partial<EntityInput<Entity>>>` + `ExactParam` when `D` targets
+ * a model via `create` / `update` / `remove`, else the inferred `input` unchanged. A
+ * `Partial` because a write descriptor's `input` may set only a subset of fields (an
+ * update patch / a create with defaulted fields).
+ */
+type WriteInputConstraint<D> = D extends {
+    readonly input: infer I;
+} ? Parameterize<Partial<EntityInput<WriteDescriptorEntity<D>>>> & ExactParam<Partial<EntityInput<WriteDescriptorEntity<D>>>, I> : unknown;
+/** The entity a write descriptor targets, from its `create` / `update` / `remove` / `upsert` model ref. */
+type WriteDescriptorEntity<D> = D extends {
+    readonly create: infer M;
+} ? EntityOfRef<M> : D extends {
+    readonly update: infer M;
+} ? EntityOfRef<M> : D extends {
+    readonly remove: infer M;
+} ? EntityOfRef<M> : D extends {
+    readonly upsert: infer M;
+} ? EntityOfRef<M> : unknown;
+/**
+ * The per-method validation overlay for {@link publishCommand} (issue #246): for
+ * each **write descriptor** method it re-asserts `input` against the target model
+ * (via {@link WriteInputConstraint}); non-write-descriptor methods (a bare
+ * `mutation(...)` plan, a `PublicComposeDescriptor`, an SCP `TransactionDefinition`)
+ * carry no model-checkable `input` here and pass through. Intersected into the
+ * `publishCommand` generic constraint so the model narrowing bites at the call site
+ * without widening the inferred `M`.
+ */
+type ValidateWriteDescriptors<M> = {
+    readonly [K in keyof M]: M[K] extends PublicWriteDescriptor ? Omit<M[K], 'input'> & (M[K] extends {
+        readonly input: unknown;
+    } ? {
+        readonly input: WriteInputConstraint<M[K]>;
+    } : Record<never, never>) : M[K];
+};
 /** The params a descriptor method accepts: the union of its `key` + `input` + `condition` leaf value types. */
 type DescriptorParamsOf<D> = (D extends {
     readonly key: infer K;
@@ -3799,7 +3397,7 @@ type WriteDescriptorKeyOf<D> = D extends {
 } ? KeyOf<K> : unknown;
 /**
  * The query-method map accepted by the #101 **direct** form
- * (`publicQueryModel({ get: descriptor, … })`): each value is a
+ * (`publishQuery({ get: descriptor, … })`): each value is a
  * {@link PublicReadDescriptor}. The contract Key and per-method result are inferred
  * from each descriptor's `key` / `select`.
  */
@@ -3810,12 +3408,13 @@ type ResolvedReadDescriptors<M extends ReadDescriptorMap> = QueryModelContract<M
 }>;
 /**
  * The command-method map accepted by the #101 **direct** form
- * (`publicCommandModel({ create: descriptor, … })`): each value is a
+ * (`publishCommand({ create: descriptor, … })`): each value is a
  * {@link PublicWriteDescriptor}, a {@link PublicComposeDescriptor} (a `mutation()`
- * wrapped with `input` / `result` / `mode`), or a bare composite `mutation()`
- * {@link CommandPlan}.
+ * wrapped with `input` / `result` / `mode`), a bare composite `mutation()`
+ * {@link CommandPlan}, or an SCP native-syntax `defineScpTransaction(...)`
+ * multi-write body ({@link TransactionDefinition}, Phase 4 S1 / issue #278).
  */
-type WriteDescriptorMap = Record<string, PublicWriteDescriptor | PublicComposeDescriptor | CommandPlan>;
+type WriteDescriptorMap = Record<string, PublicWriteDescriptor | PublicComposeDescriptor | CommandPlan | TransactionDefinition>;
 /** Resolve a write-descriptor map to its {@link CommandModelContract}. */
 type ResolvedWriteDescriptors<M extends WriteDescriptorMap> = CommandModelContract<M[keyof M] extends infer D ? WriteDescriptorKeyOf<D> : unknown, {
     readonly [K in keyof M]: CommandMethodSpec<WriteDescriptorKeyOf<M[K]>, DescriptorParamsOf<M[K]>, WriteDescriptorResultOf<M[K]>>;
@@ -3824,7 +3423,7 @@ type ResolvedWriteDescriptors<M extends WriteDescriptorMap> = CommandModelContra
  * Create a **QueryModel** from a **descriptor map** (issue #101, the only form):
  *
  * ```ts
- * export const UserQueries = publicQueryModel({
+ * export const UserQueries = publishQuery({
  *   get:  { query: User,            key: { userId: param.string() },  select: { name: true } },
  *   list: { list:  GroupMembership, key: { groupId: param.string() }, select: { role: true } },
  * });
@@ -3833,7 +3432,7 @@ type ResolvedWriteDescriptors<M extends WriteDescriptorMap> = CommandModelContra
  * The single argument is the method map itself; the contract Key and each method's
  * result type are **inferred** from the descriptors' `key` / `select` — there is no
  * generic key parameter, no curried factory call, and no explicit Key-field list
- * (the legacy `publicQueryModel<TKey>(['email'])` / model-derived overloads were
+ * (the legacy `publishQuery<TKey>(['email'])` / model-derived overloads were
  * withdrawn in #101). A GSI-keyed point read is expressed by its descriptor `key`
  * (e.g. `key: { email: param.string() }`); the build resolves the access pattern
  * from the model metadata, exactly as the curried key-field list once did. Each
@@ -3841,12 +3440,12 @@ type ResolvedWriteDescriptors<M extends WriteDescriptorMap> = CommandModelContra
  * a `select` is the existing query projection (relation-nest aware), and may carry
  * External Query `query(...)` nodes.
  */
-declare function publicQueryModel<const M extends ReadDescriptorMap>(methods: M): ResolvedReadDescriptors<M>;
+declare function publishQuery<const M extends ReadDescriptorMap>(methods: M): ResolvedReadDescriptors<M>;
 /**
  * Create a **CommandModel** from a **descriptor map** (issue #101, the only form):
  *
  * ```ts
- * export const MembershipCommands = publicCommandModel({
+ * export const MembershipCommands = publishCommand({
  *   create: { create: GroupMembership, key: { groupId: param.string(), userId: param.string() },
  *             input: { role: param.string() }, result: { select: { role: true } } },
  *   addMany: { create: GroupMembership, key: { … }, input: { … }, mode: 'parallel' },
@@ -3857,53 +3456,46 @@ declare function publicQueryModel<const M extends ReadDescriptorMap>(methods: M)
  * The single argument is the method map itself; the contract Key and each method's
  * read-back result are **inferred** from the descriptors' `key` / `result.select` —
  * there is no generic key parameter, no curried factory call, and no explicit
- * Key-field list (the legacy `publicCommandModel<TKey>()` / model-derived overloads
+ * Key-field list (the legacy `publishCommand<TKey>()` / model-derived overloads
  * were withdrawn in #101). A descriptor's `mode` declares the per-call execution
  * mode (`'transaction'` default | `'parallel'`); `result` presence drives whether
  * the method reads back and returns the written entity.
  */
-declare function publicCommandModel<const M extends WriteDescriptorMap>(methods: M): ResolvedWriteDescriptors<M>;
-declare const PLANNED_COMMAND_BRAND: unique symbol;
-/**
- * The input param shape a {@link command} declares: a record of named
- * {@link Param} placeholders (`param.string()` / `param.number()` /
- * `param.literal(...)`). These are the **external** params of the public Command
- * IF — the method's caller-supplied input. The mutation fragment binds them by
- * name into the written entity (`$.<field>`), so each input field name must match
- * a fragment `$.field` reference / a model field the fragment writes.
- */
-type CommandInputShape = Readonly<Record<string, Param<unknown>>>;
-/**
- * The return projection a {@link command} declares (proposal §3: "return = read
- * projection"): a JSON-safe boolean field map applied to the written entity as a
- * **consistent read-back** after the write commits. Omit for a fire-and-forget
- * command (no projected item is returned).
- */
-type CommandSelectShape = Readonly<Record<string, boolean>>;
-/**
- * A **planned command method** (#83): the branded result of
- * `command({ input, select }).plan(mutation)`. It carries the captured fragment
- * IR (the {@link CommandPlan}), the public input param shape, and the return
- * `select`. {@link buildCommandContract} detects the brand and routes it to the
- * single-fragment mutation compiler (NOT through #64's closure path).
- *
- * The external surface is **params in / result out only** — the internal mutation
- * document is never exposed.
- *
- * @typeParam TInput  - The input param shape (`{ field: Param<…> }`).
- * @typeParam TSelect - The return projection (`{ field: boolean }`), or `undefined`.
- */
-interface PlannedCommandMethod<TInput extends CommandInputShape = CommandInputShape, TSelect extends CommandSelectShape | undefined = CommandSelectShape | undefined> {
-    readonly [PLANNED_COMMAND_BRAND]: true;
-    /** The captured mutation IR (the fragment list). */
-    readonly plan: CommandPlan;
-    /** The public input param shape. */
-    readonly input: TInput;
-    /** The return projection (consistent read-back), or `undefined`. */
-    readonly select: TSelect;
+declare function publishCommand<const M extends WriteDescriptorMap & ValidateWriteDescriptors<M>>(methods: M): ResolvedWriteDescriptors<M>;
+/** Options accepted by the {@link mutate} authoring alias. */
+interface MutateAuthoringOptions {
+    /**
+     * The **atomicity mode** for this write body. This is the ONLY home of
+     * atomicity (Phase 4 S3.5): `'transaction'` composes the body's writes into one
+     * atomic `TransactWriteItems`; `'parallel'` runs them non-atomically. Omitted ⇒
+     * non-atomic — graphddb never defaults atomicity, so a multi-write body with no
+     * `mode` is a definition-time error (see the fail-closed guard).
+     */
+    readonly mode?: MutateMode;
 }
-/** Runtime guard: is `value` a {@link PlannedCommandMethod} (#83)? */
-declare function isPlannedCommandMethod(value: unknown): value is PlannedCommandMethod;
+/**
+ * The **`mutate` authoring alias** (Phase 4 S3.5) — the authoring twin of the
+ * runtime `DDBModel.mutate` / `mutate({ mode })`, usable as a `publishCommand`
+ * method value. It wraps an existing recorder / SCP-lowered write body (a
+ * {@link TransactionDefinition} produced by `defineScpTransaction` /
+ * `defineTransaction`, or a {@link CommandPlan} produced by `mutation(...)`) and
+ * records the authoring `{ mode }` onto the produced IR — the SOLE place
+ * atomicity is decided.
+ *
+ * It adds **no new lowering path**: the transform still recognizes only
+ * `tx.put/update/delete/forEach`, and the body flows through the SAME
+ * `buildTransactionSpec` path as the standalone form. The name + `{ mode }`
+ * option deliberately mirror the runtime `mutate`; the runtime/authoring fold is
+ * Phase 4 S6 (this only makes the authoring alias exist and carry `mode`).
+ *
+ * - `mutate(txDef, { mode })` → the same {@link TransactionDefinition} with
+ *   `mode` stamped (undefined ⇒ non-atomic; a multi-write body then throws in
+ *   `publishCommand`'s SCP-body branch — declare a mode).
+ * - `mutate(plan, { mode })` → a {@link PublicComposeDescriptor} (`{ command,
+ *   mode }`), the closure-free composite form.
+ */
+declare function mutate(body: TransactionDefinition, options?: MutateAuthoringOptions): TransactionDefinition;
+declare function mutate(body: CommandPlan, options?: MutateAuthoringOptions): PublicComposeDescriptor;
 /** The per-call execution mode of a command method (#101): replaces `batch`. */
 type CommandMode = 'transaction' | 'parallel';
 /** A public **read** descriptor (issue #101): `{ query | list: Model, key, select, options? }`. */
@@ -3921,11 +3513,21 @@ interface PublicReadDescriptor {
      */
     readonly description?: string;
 }
-/** A public **write** descriptor (issue #101): `{ create | update | remove: Model, key, input?, condition?, result?, mode? }`. */
+/** A public **write** descriptor (issue #101): `{ create | update | remove | upsert: Model, key, input?, condition?, result?, mode? }`. */
 interface PublicWriteDescriptor {
     readonly create?: ModelRef;
     readonly update?: ModelRef;
     readonly remove?: ModelRef;
+    /**
+     * `upsert` — a `PutItem` with **no** `attribute_not_exists(PK)` guard (an
+     * unconditional overwrite; the semantics of the removed `definePut`). Unlike
+     * `create` (always guarded against clobbering an existing row), an `upsert` writes
+     * whether or not the row exists. An author-supplied `condition` is honored VERBATIM
+     * — it is NOT ANDed with a `notExists` guard (that absence is what distinguishes an
+     * upsert from a create). The compiled base op is a `Put` whose only condition is the
+     * author's (or none), i.e. the ORIGINAL `definePut` wire shape.
+     */
+    readonly upsert?: ModelRef;
     readonly key: Readonly<Record<string, unknown>>;
     readonly input?: Readonly<Record<string, unknown>>;
     readonly condition?: Readonly<Record<string, unknown>> | RawCondition<any, any>;
@@ -4112,16 +3714,6 @@ interface MaintenanceGraph {
      */
     readonly multiMaintainerTargets: ReadonlyMap<string, readonly MaintainItem[]>;
 }
-/**
- * Build the {@link MaintenanceGraph} from every registered model's relation-side
- * maintenance declarations (`MetadataRegistry.getAll()`), validating each as it is
- * collected (round-trip, unresolved trigger) and the whole graph (cycle) before
- * returning. Throws a loud, actionable error on any invalid declaration.
- *
- * @param registry The models to scan. Defaults to `MetadataRegistry.getAll()`;
- *   an explicit map is accepted for tests / scoped builds.
- */
-declare function buildMaintenanceGraph(registry?: ReadonlyMap<Function, EntityMetadata>, views?: readonly ViewDefinition[]): MaintenanceGraph;
 
 /**
  * A **referential-integrity assertion** derived from a `requires`
@@ -4750,225 +4342,6 @@ interface CompiledMutationPlan {
  */
 declare function compileMutationPlan(plan: CommandPlan): CompiledMutationPlan;
 
-/**
- * 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`,
@@ -5021,188 +4394,12 @@ declare function executeRangeFanout(op: ContractMethodOp, keys: readonly Contrac
  * The TS and Python runtimes produce identical effects for the same SSoT.
  */
 
-/**
- * The **structural** shape of a resolved command contract the runtime executes.
- * It depends only on the facts the executor reads — the `command` discriminant
- * and the per-method `op` / `batch` / `result` — and is deliberately
- * **independent of the phantom Key / params / result types** carried by
- * {@link CommandModelContract} (those are invariant on the full interface, so a
- * concrete `CommandModelContract<{…}>` is not assignable to
- * `CommandModelContract<unknown, …>`). Every real command contract is
- * structurally assignable to this minimal type.
- */
-interface ExecutableCommandContract {
-    readonly kind: 'command';
-    readonly methods: Readonly<Record<string, {
-        readonly op: ContractMethodOp;
-        readonly result: CommandResultKind;
-        /**
-         * The #101 first-class per-call execution mode (`'transaction'` |
-         * `'parallel'`). Drives the key-array bulk form directly (`'transaction'`
-         * → atomic `TransactWriteItems`; `'parallel'` → non-atomic per-key fan-out
-         * with partial success, coalescing unconditioned put/delete into a
-         * `BatchWriteItem`).
-         */
-        readonly mode?: CommandMode;
-        /**
-         * The composed write ops of a **multi-fragment** `mutation`-derived method
-         * (issue #90). When present (N≥2), a **single-key** call executes ALL of
-         * them as **one atomic `TransactWriteItems`** (not sequential writes), so a
-         * condition failure on any fragment rolls back the whole transaction. Absent
-         * for a single-fragment / #83 / hand-written #64 method (which executes its
-         * one {@link op}). The read-back stays keyed on the primary op ({@link op}).
-         */
-        readonly ops?: readonly ContractMethodOp[];
-        /**
-         * The referential-integrity assertions derived from the mutation's
-         * `requires` effects (issue #84). When present (non-empty), a
-         * **single-key** call composes the base write(s) **and** one read-only
-         * `ConditionCheck` (`attribute_exists`) per assertion into **one atomic
-         * `TransactWriteItems`** — so a single-op write is **promoted** to a
-         * transaction. If any referenced entity is absent, its assertion fails and
-         * the WHOLE transaction rolls back (the entity write never persists). Absent
-         * on a mutation with no `requires` / a #64 hand-written method.
-         */
-        readonly conditionChecks?: readonly DerivedConditionCheck[];
-        /**
-         * The adjacency edge writes derived from the mutation's `edges` effects
-         * (issue #85). When present, a **single-key** call composes each edge's
-         * adjacency `Put` / `Delete` item(s) into the **same atomic
-         * `TransactWriteItems`** as the entity write (and any ConditionChecks /
-         * derived updates), so the edge is created / removed / moved atomically with
-         * the entity. Absent on a mutation with no `edges` / a #64 hand-written method.
-         */
-        readonly edgeWrites?: readonly DerivedEdgeWrite[];
-        /**
-         * The derived counter updates from the mutation's `derive` effects (issue
-         * #85): each an atomic `ADD` (`UpdateItem`) on a target counter (e.g.
-         * `User.postCount += 1`). When present, a **single-key** call composes each
-         * `ADD` into the same atomic `TransactWriteItems` as the entity write, so the
-         * counter moves atomically (and never clobbers a concurrent increment — an
-         * `ADD` needs no prior read). Absent on a mutation with no `derive`.
-         */
-        readonly derivedUpdates?: readonly DerivedUpdate[];
-        /**
-         * The uniqueness guards derived from the mutation's `unique` effects (issue
-         * #86): each a marker-row `Put` (`attribute_not_exists`) / `Delete` /
-         * `Delete(old)+Put(new)` swap. When present, a **single-key** call composes
-         * the guard item(s) into the same atomic `TransactWriteItems` as the entity
-         * write, so a duplicate scoped value (the guard `Put`'s `attribute_not_exists`
-         * failing) rolls the WHOLE transaction back — the entity is never created.
-         * Absent on a mutation with no `unique` / a #64 hand-written method.
-         */
-        readonly uniqueGuards?: readonly DerivedUniqueGuard[];
-        /**
-         * The outbox events derived from the mutation's `emits` effects (issue #87):
-         * each a transactional-outbox `Put`. When present, a **single-key** call
-         * composes each event's `Put` into the same atomic `TransactWriteItems` as the
-         * entity write, so the event RECORD is written ATOMICALLY with the state it
-         * announces (they can never diverge). The row is drainable from real
-         * DynamoDB Streams (captured at the table layer regardless of code path);
-         * delivery / handlers are OUT of scope. Since #94 the derived-command
-         * transaction also feeds every committed item (including this outbox `Put`)
-         * into the in-process `ChangeCaptureRegistry` seam, so the dev/test
-         * `src/cdc/` emulator now observes this path too — production Streams and the
-         * emulator agree. Absent on a mutation with no `emits`.
-         */
-        readonly outboxEvents?: readonly DerivedOutboxEvent[];
-        /**
-         * The client-token idempotency guard derived from the mutation's `idempotency`
-         * effect (issue #87): a marker-row `Put` (`attribute_not_exists`). When present,
-         * a **single-key** call composes the guard `Put` into the same atomic
-         * `TransactWriteItems` as the entity write, so a same-token re-execution fails
-         * the guard and rolls the WHOLE transaction back — no effect is double-applied.
-         * Absent on a mutation with no `idempotency` / a #64 hand-written method.
-         */
-        readonly idempotencyGuard?: DerivedIdempotencyGuard;
-        /**
-         * The maintenance writes derived from the relation-side `write.maintainedOn`
-         * declarations (issue #125 → #127; the D/#124 → compile lowering). When
-         * present (non-empty), a **single-key** call composes each maintenance write
-         * — a projected snapshot (`SET`) or a bounded-collection append
-         * (`SET … = list_append(…)`) on a SEPARATE owner row — into the same atomic
-         * `TransactWriteItems` as the source entity write (and every other effect),
-         * so the maintained row moves ATOMICALLY with the source: a failure on any
-         * item rolls the WHOLE transaction back (the snapshot / collection never
-         * partially persists). The owner row is upserted (a bare `UpdateItem`
-         * creates it if absent — the additive maintenance semantics). This is the
-         * synchronous (`updateMode: 'mutation'`) path only; the async stream path is
-         * #130 (loud-rejected at compile time). Absent on a mutation that fires no
-         * maintainer / a #64 hand-written method.
-         */
-        readonly maintainWrites?: readonly DerivedMaintainWrite[];
-        /**
-         * The maintenance-outbox events for `updateMode: 'stream'` maintainers (issue
-         * #130). Each is a transactional-outbox `Put` (the same `literalKey` marker
-         * mechanism as #87's outbox) composed into the method's atomic
-         * `TransactWriteItems` — recording the maintenance intent ATOMICALLY with the
-         * source write. The `src/cdc/` drain selects these (`PK begins_with
-         * 'OUTBOX#MAINT#'`) and applies the owner-row write asynchronously (so a
-         * snapshot SET / collection append+trim / counter ADD / running-max conditional
-         * SET happens off the write path, at-least-once, per-shard ordered). Absent on a
-         * mutation with no stream maintainer.
-         */
-        readonly maintainOutbox?: readonly DerivedMaintainOutbox[];
-        /**
-         * The return projection of a `mutation`-derived method (issue #83). When
-         * present, a **single-key** call performs the write then issues a
-         * **consistent read-back** (`GetItem` with `ConsistentRead`) of the
-         * written entity's primary key and returns the projected item via the
-         * existing read-projection machinery. Absent on a #64 hand-written method.
-         */
-        readonly returnSelection?: Readonly<Record<string, boolean>>;
-    }>>;
-}
-/** The params a command method consumes (the body's `params` argument). */
-type ContractCommandParams = Record<string, unknown>;
 /**
  * The projected read-back item a `mutation`-derived command method returns, or
  * `null` when the written row was absent at read-back (e.g. a `remove`). A plain
  * record of the projected fields.
  */
 type CommandReturn = Record<string, unknown> | null;
-/**
- * #101 Phase 3 — the per-op outcome of a `mode: 'parallel'` key-array bulk write.
- * A non-atomic fan-out reports each key's result independently: `{ ok: true }` on
- * success, `{ ok: false, error }` on a per-op failure (a failed condition / a
- * `BatchWriteItem` item that stayed unprocessed after retry). The array index
- * matches the input key index, and a per-op failure NEVER aborts the others.
- */
-interface ParallelOpResult$1 {
-    readonly ok: boolean;
-    readonly error?: string;
-}
-/** The partial-success return of a `mode: 'parallel'` key-array bulk write (#101). */
-interface CommandParallelReturn {
-    readonly results: readonly ParallelOpResult$1[];
-}
-/**
- * Execute a command-contract method for a **single** key — one write op
- * (`put` / `update` / `delete`).
- *
- * @param contract   The resolved command contract (a {@link CommandModelContract}).
- * @param methodName The method to execute.
- * @param key        A single contract key (the mutation target).
- * @param params     The mutation params (the body's `params` argument).
- */
-declare function executeCommandMethod(contract: ExecutableCommandContract, methodName: string, key: ContractKeyInput, params?: ContractCommandParams): Promise<void | CommandReturn>;
-/**
- * Execute a command-contract method for an **array** of keys — a batched write
- * per the method's declared {@link CommandBatchMode}:
- *
- * - `'transact'` → one atomic `TransactWriteItems` (≤25, condition-capable); a
- *   >25-key array is **rejected** (an atomic transaction cannot be split).
- * - `'batchWrite'` → a `BatchWriteItem` (no conditions; chunked ≤25 with
- *   `UnprocessedItems` retry).
- *
- * A method that declared no batched form rejects an array with a clear error.
- *
- * @param contract   The resolved command contract.
- * @param methodName The method to execute.
- * @param keys       An array of contract keys.
- * @param params     The mutation params shared across every key.
- */
-declare function executeCommandMethod(contract: ExecutableCommandContract, methodName: string, keys: readonly ContractKeyInput[], params?: ContractCommandParams): Promise<void | CommandParallelReturn>;
 
 /**
  * The **unified envelope** in-process execution engine (issue #101).
@@ -5260,17 +4457,30 @@ interface ReadRouteOptions {
 interface ReadRouteDescriptor {
     readonly query?: ModelRef;
     readonly list?: ModelRef;
-    readonly key: Record<string, unknown>;
+    /**
+     * The route's primary-key binding. A single key object reads once (result:
+     * `Item | null` for a `query` route, a connection for a `list` route). On a
+     * `query` route a **key ARRAY** (#283 — the batch-read fold that supersedes the
+     * removed `DDBModel.batchGet`) reads every key and the route result is an ARRAY
+     * of `Item | null` aligned to the input key order (a miss → `null`).
+     *
+     * The array read is HYBRID-routed by whether the select / key can use a chunked
+     * server-side `BatchGetItem` (see {@link executeReadRoute}): a pure point-read
+     * batch (no relation traversal, full-primary-key keys) runs through the chunked
+     * `BatchGetItem` machinery (⌈N/100⌉ ops, `UnprocessedKeys` retry) for batchGet's
+     * efficiency; a batch whose select requests relations (or whose key is a GSI /
+     * partial key) falls back to a per-key single-item read (`executeAdHocQuery`) run
+     * in parallel, since `BatchGetItem` cannot assemble relations. Both branches
+     * return the identical ordered `(Item | null)[]` — the routing is a physical-read
+     * choice only (no data / order / projection difference). A key array on a `list`
+     * route is rejected (a partition read has no multi-key meaning).
+     */
+    readonly key: Record<string, unknown> | readonly Record<string, unknown>[];
     readonly select: Record<string, unknown>;
     readonly options?: ReadRouteOptions;
 }
 /** The read envelope: alias → {@link ReadRouteDescriptor}. */
 type ReadEnvelope = Record<string, ReadRouteDescriptor>;
-/** The result of a read route — a `query` item (or `null`) or a `list` connection. */
-type ReadRouteResult = Record<string, unknown> | null | {
-    items: Record<string, unknown>[];
-    cursor: string | null;
-};
 /** The write execution mode: atomic transaction (default) or non-atomic parallel. */
 type MutateMode = 'transaction' | 'parallel';
 /** A read-back projection for a write op (the EXISTING query select shape). */
@@ -5286,6 +4496,12 @@ interface InProcessWriteDescriptor {
     readonly create?: ModelRef;
     readonly update?: ModelRef;
     readonly remove?: ModelRef;
+    /**
+     * `upsert` — a `PutItem` with **no** `attribute_not_exists(PK)` guard (an
+     * unconditional overwrite; the semantics of the removed `definePut`). Unlike
+     * `create`, an `upsert` may carry a `condition` (honored verbatim).
+     */
+    readonly upsert?: ModelRef;
     /**
      * The target's primary-key binding. A single key object applies the op once; an
      * **array** of key objects (#101 `key: K | K[]`) applies the SAME op to every key
@@ -5300,25 +4516,6 @@ interface InProcessWriteDescriptor {
 }
 /** The write envelope: alias → {@link InProcessWriteDescriptor}. */
 type WriteEnvelope = Record<string, InProcessWriteDescriptor>;
-/** Options for {@link executeWriteEnvelope}. */
-interface MutateOptions {
-    readonly mode?: MutateMode;
-    /**
-     * Per-call throttle / transient-error retry override (issue #111), applied to
-     * every write this envelope composes (the atomic `TransactWriteItems` in
-     * `transaction` mode, or each op's send in `parallel` mode). A {@link RetryPolicy}
-     * overrides the global policy; `false` disables retry. Omit ⇒ the configured /
-     * built-in default policy.
-     */
-    readonly retry?: RetryOverride;
-    /**
-     * Host-injected per-call write context (issue #50 / #139) — exposed to every
-     * write hook (W1–W5) as `ctx.context`. In `transaction` mode every composed op
-     * shares it and the persist hooks fire once for the atomic batch; in `parallel`
-     * mode each independent op sees it. NEVER serialized. Absent ⇒ `{}`.
-     */
-    readonly context?: RequestContext;
-}
 /** A per-alias result in `parallel` mode: success carries the read-back, else error. */
 type ParallelOpResult = {
     readonly ok: true;
@@ -5327,7 +4524,7 @@ type ParallelOpResult = {
     readonly ok: false;
     readonly error: Error;
 };
-declare const INTENT_KEYS: readonly ["create", "update", "remove"];
+declare const INTENT_KEYS: readonly ["create", "update", "remove", "upsert"];
 type Intent = (typeof INTENT_KEYS)[number];
 
 /**
@@ -5339,11 +4536,17 @@ type Intent = (typeof INTENT_KEYS)[number];
 
 /** The entity type a {@link ModelStatic} value (or model class) carries. */
 type EntityOf<M> = M extends ModelStatic<infer T, infer _C> ? T : M extends abstract new (...args: never[]) => infer T ? T extends DDBModel ? T : never : unknown;
-/** The result type of one read route, derived from `query` / `list` + `select`. */
+/**
+ * The result type of one read route, derived from `query` / `list` + `select`.
+ * A `query` route whose `key` is an ARRAY (#283 batch read, the `DDBModel.batchGet`
+ * fold) resolves to a per-key ARRAY of `Item | null`, aligned to the input keys.
+ */
 type ReadRouteResultOf<R> = R extends {
     readonly query: infer M;
     readonly select: infer S;
-} ? QueryResultFor<EntityOf<M>, S> | null : R extends {
+} ? R extends {
+    readonly key: readonly unknown[];
+} ? readonly (QueryResultFor<EntityOf<M>, S> | null)[] : QueryResultFor<EntityOf<M>, S> | null : R extends {
     readonly list: infer M;
     readonly select: infer S;
 } ? {
@@ -5499,7 +4702,7 @@ interface CompiledReadRoute {
  * ## Why "prepare once, execute many"
  *
  * `DDBModel.mutate` / `Model.query` recompile the plan on every call (`#203`'s
- * "軽量だが per-call 再コンパイル" cell). `publicCommandModel` / `publicQueryModel`
+ * "軽量だが per-call 再コンパイル" cell). `publishCommand` / `publishQuery`
  * precompile but weld it to a named CQRS contract. `prepare` is the missing
  * middle: precompiled **without** the contract ceremony.
  *
@@ -5514,11 +4717,11 @@ interface CompiledReadRoute {
  *   computed once. `execute` binds the concrete key VALUES + per-call pagination /
  *   consistency and runs the unified read-plan executor
  *   (`executeCompiledReadRoute`, issue #249) — the identical core `Model.query` /
- *   `Model.list` and `publicQueryModel` use. (The
+ *   `Model.list` and `publishQuery` use. (The
  *   `ExecutionPlan` bakes concrete key values into its `keyCondition`, so a single
  *   compiled operation object is NOT reusable across param sets; the precompiled
  *   product is the resolved model + normalized projection — exactly what the public
- *   `publicQueryModel` op reuses — and the residual per-op `plan()` is identical to
+ *   `publishQuery` op reuses — and the residual per-op `plan()` is identical to
  *   that public path.)
  *
  * ## No runtime capture (the design's key constraint)
@@ -5563,8 +4766,6 @@ interface PreparedParamRef {
     /** The param name, e.g. `userId`. */
     readonly name: string;
 }
-/** Runtime guard: is `value` a {@link PreparedParamRef} (a `$.<name>` read)? */
-declare function isPreparedParamRef(value: unknown): value is PreparedParamRef;
 /** The placeholder proxy handed to a `prepare` body as `$`. Every `$.<name>` read
  * mints a {@link PreparedParamRef}; any further access / coercion throws so the
  * body stays a pure, params-independent template (no runtime capture).
@@ -5582,6 +4783,8 @@ interface PreparedWriteRoute {
     readonly create?: ModelRef;
     readonly update?: ModelRef;
     readonly remove?: ModelRef;
+    /** `upsert` — a `PutItem` with no `attribute_not_exists(PK)` guard (unconditional overwrite; the `definePut` semantics). */
+    readonly upsert?: ModelRef;
     readonly key: Record<string, unknown>;
     readonly input?: Record<string, unknown>;
     readonly condition?: Record<string, unknown>;
@@ -5657,22 +4860,6 @@ declare class PreparedReadStatement {
     private runRoute;
 }
 type PreparedStatement = PreparedReadStatement | PreparedWriteStatement;
-/**
- * The max number of distinct compiled prepared statements the fallback cache
- * retains. Bounded so an unbounded variety of inline `prepare` shapes cannot grow
- * the cache without limit (issue #205 AC). LRU eviction: least-recently-used first.
- */
-declare const PREPARE_CACHE_MAX = 256;
-/**
- * Compile a declarative read/write route body into a reusable prepared statement
- * (issue #205). Backs {@link DDBModel.prepare}.
- *
- * The body is evaluated ONCE with a recording `$` proxy; the resulting routes are
- * classified (all-read or all-write), a structure key is computed, and the compiled
- * handle is memoized in the bounded fallback cache so an inline `prepare(fn)` of the
- * same shape recompiles at most once.
- */
-declare function prepare(body: PreparedBody): PreparedStatement;
 
 /**
  * `subscribe` — the declarative, batch CDC consumer builder (issue #153).
@@ -5747,66 +4934,6 @@ type CdcSubscribeHandlers = keyof CdcModelRegistry extends never ? Record<string
 declare abstract class DDBModel {
     /** @internal Type brand — prevents primitives from structurally matching DDBModel. */
     private readonly __brand;
-    /**
-     * Register the `DynamoDBClient` GraphDDB sends through.
-     *
-     * IMPORTANT (issue #111): GraphDDB now owns single-op throttle / transient-error
-     * retry (see {@link setRetryPolicy}), so a client left at the AWS SDK default
-     * `maxAttempts: 3` retries MULTIPLICATIVELY underneath the library. Construct the
-     * client with `maxAttempts: 1` so the library is the single source of truth for
-     * retry — e.g. `new DynamoDBClient({ maxAttempts: 1 })`. GraphDDB does NOT mutate
-     * a client you pass in.
-     */
-    static setClient(client: DynamoDBClient): void;
-    /**
-     * Read back the registered `DynamoDBClient` — the resolved client last passed to
-     * {@link setClient}. Symmetric with {@link setClient} and backed by the same
-     * {@link ClientManager} store, so it always reflects the client GraphDDB sends
-     * through.
-     *
-     * Throws a clear error if no client has been registered yet (call
-     * {@link setClient} first) — matching {@link ClientManager.getClient}'s "loud,
-     * never silently `undefined`" convention shared with the rest of the client API.
-     */
-    static getClient(): DynamoDBClient;
-    static setTableMapping(mapping: Record<string, string>): void;
-    /**
-     * Configure the global single-op retry policy (issue #111) — exponential backoff
-     * + jitter with a bounded attempt cap, applied to every GetItem / Query / Put /
-     * Update / Delete / relation-fan-out send and to `TransactWriteItems`. Mirrors
-     * {@link setClient} / {@link setTableMapping}. A sensible default is ALWAYS on; call
-     * this only to tune it (or pass `null` to restore the default). A per-call
-     * `retry?: RetryPolicy | false` on an operation's options overrides this globally
-     * for that call (`false` disables retry).
-     */
-    static setRetryPolicy(policy: RetryPolicy | null): void;
-    /**
-     * Register a {@link Middleware} (issue #50; read path #138, write path #139).
-     * One registered object may carry read and/or write hooks.
-     *
-     * - **Read** R1–R5 — request entry (`read.before`), each physical op before send
-     *   / after raw fetch (`read.op.before` / `read.op.afterFetch`, INCLUDING every
-     *   relation fan-out fetch), the final hydrated result (`read.afterFetch`), and on
-     *   error (`read.op.onError` / `read.onError`).
-     * - **Write** W1–W5 — the logical write before effect derivation (`write.before`,
-     *   may mutate `ctx.input` / `ctx.kind` incl. a delete→update rewrite), after commit
-     *   (`write.after`), the physical persist on the fully composed batch
-     *   (`write.persist.before` / `write.persist.after`, fires ONCE per atomic
-     *   transaction), and on error (`write.persist.onError` / `write.onError`).
-     *
-     * Hooks may observe, mutate `ctx`, `throw` to cancel, or (on `onError`) recover by
-     * returning a value; the library imposes no semantics. Ordering: `before*` runs
-     * first-registered-first (FIFO); `after*` / `onError` run last-registered-first
-     * (LIFO). Mirrors {@link setRetryPolicy} — a host-runtime global stored on
-     * {@link ClientManager}; never serialized (the bridge #48 is unaffected). Per-call
-     * host context flows in via the read's / write's `{ context }` option.
-     */
-    static use(mw: Middleware): void;
-    /** Remove every registered middleware (read AND write; teardown / tests). See {@link use}. */
-    static clearMiddleware(): void;
-    static transaction(fn: (tx: TransactionContext) => void | Promise<void>, options?: {
-        context?: RequestContext;
-    }): Promise<void>;
     /**
      * In-process multi-route READ (issue #101 — the unified envelope). Each alias
      * route (`{ query | list: Model, key, select, options? }`) runs **independently
@@ -5837,8 +4964,8 @@ declare abstract class DDBModel {
     /**
      * **Prepared statement** (issue #205 / design #203) — the read/write-unified
      * middle tier between the ad-hoc `DDBModel.mutate` / `DDBModel.query` (per-call
-     * recompiled) and the public CQRS contract (`publicCommandModel` /
-     * `publicQueryModel`, precompiled but contract-welded).
+     * recompiled) and the public CQRS contract (`publishCommand` /
+     * `publishQuery`, precompiled but contract-welded).
      *
      * `prepare($ => ({...}))` **compiles the declarative route body once** and returns
      * a handle whose `.execute(params)` binds the per-call values and runs through the
@@ -5908,20 +5035,6 @@ declare abstract class DDBModel {
      * registered `@cdcProjected` model throws at build time.
      */
     static subscribe(handlers: CdcSubscribeHandlers): ChangeHandler;
-    /**
-     * Multi-key, multi-model batch read. Each {@link BatchGetRequest} contributes its
-     * keys to a chunked `BatchGetItem` per physical table; results are re-grouped by
-     * model on the returned {@link BatchGetResult}.
-     *
-     * Fires the read hooks (issue #142): request-level R1/R4/R5 with kind
-     * `'batchGet'`, and op-level R2/R3/R5 for each underlying physical `BatchGetItem`
-     * op. The optional `{ context }` is exposed to every hook as `ctx.context` and
-     * threaded UNCHANGED to every op (absent ⇒ `{}`), so a global hook (e.g. a
-     * tenant-scope R2 FilterExpression) applies across the whole batch. With no
-     * middleware registered the read path is unchanged (zero-overhead fast path).
-     */
-    static batchGet(requests: BatchGetRequest[], options?: BatchGetOptions): Promise<BatchGetResult>;
-    static batchWrite(requests: BatchWriteRequest[]): Promise<void>;
     static asModel<C extends new (...args: never[]) => DDBModel>(this: C): ModelStatic<InstanceType<C>, C>;
 }
 
@@ -5950,8 +5063,6 @@ interface Column<V = unknown, M = unknown> {
     /** @internal phantom — owning-model brand. */
     readonly __model?: M;
 }
-/** Runtime guard: is this value a {@link Column} reference? */
-declare function isColumn(value: unknown): value is Column;
 /**
  * The `Model.col` map: one {@link Column} per scalar field of the entity, each
  * typed with the field's declared value type and branded to the model.
@@ -5984,8 +5095,6 @@ interface KeySegment {
     /** The interpolated column references, in order. */
     readonly columns: readonly Column[];
 }
-/** Runtime guard: is this value a {@link KeySegment}? */
-declare function isKeySegment(value: unknown): value is KeySegment;
 /**
  * The interpolation slot accepted by {@link k}: a typed column reference
  * (`c.field`). Bare strings are NOT accepted — a key field must be named via a
@@ -6051,519 +5160,4 @@ declare function key<T extends Record<string, unknown>>(builder: (c: {
     readonly [K in keyof T]-?: Column<T[K], T>;
 }) => KeyStructure): KeyDefinitionMarker<T>;
 
-type DynamoType = 'S' | 'N' | 'BOOL' | 'B' | 'SS' | 'NS' | 'L' | 'M';
-interface FieldOptions {
-    format?: 'datetime' | 'date';
-    readonly?: boolean;
-    serialize?: (value: unknown) => unknown;
-    deserialize?: (value: unknown) => unknown;
-    /**
-     * Optional human-readable description of the field (issue #154). Pure
-     * documentation metadata — it does NOT affect storage, hydration, key handling,
-     * or any runtime behaviour. When present it is propagated to the field entry in
-     * `manifest.json` ({@link ManifestField.description}) and surfaces as a field
-     * comment in the generated Python `types.py`. Absent → byte-for-byte unchanged
-     * output (backward compatible).
-     */
-    description?: string;
-}
-interface FieldMetadata {
-    propertyName: string;
-    dynamoType: DynamoType;
-    options?: FieldOptions;
-    /**
-     * For a `@literal(...)` field — a `string`-stored field whose value is one of a
-     * known, finite set — the allowed literal values, in declaration order (issue
-     * #75). Recorded purely as model metadata so a Contract param bound into the
-     * field can recover the precise `literal` param-kind from its bind position
-     * (`src/spec/contracts.ts`), serializing as `{ type: 'literal', literals: [...] }`
-     * instead of the imprecise `'string'`. JSON-safe by construction (a non-empty
-     * array of strings). `undefined` for every other field decorator (`@string`,
-     * `@number`, …), so plain fields are byte-for-byte unchanged (backward compat).
-     */
-    literals?: readonly string[];
-    /**
-     * For an `@ttl` field (issue #172, Epic #167 — CFn generator C4) — marks this
-     * field as the model's **DynamoDB Time-To-Live** attribute. `@ttl` is a
-     * standalone semantic decorator pinned to `number` (it records `dynamoType: 'N'`
-     * itself, so `@ttl expiresAt!: string` is a compile error), because DynamoDB TTL
-     * requires a Number attribute holding **epoch seconds**. It is a **physical
-     * schema** fact (unlike the maintenance signals kept off the manifest): the flag
-     * flows through {@link EntityMetadata} into `manifest.json`
-     * ({@link ManifestEntity.ttlAttribute}), which the CloudFormation emitter consumes
-     * to render `TimeToLiveSpecification`. DynamoDB allows exactly one TTL attribute
-     * per table, enforced loudly at model registration (`@model`). `undefined` for
-     * every other field decorator, so non-TTL fields are byte-for-byte unchanged.
-     */
-    ttl?: boolean;
-}
-
-/**
- * The maintenance kind of a model (issue #152). `'entity'` (the default) is a plain
- * stored entity. `'materializedView'` / `'sparseView'` mark a model as a maintained
- * **view** row whose `@maintainedFrom` declarations feed the maintenance graph (the
- * adapter that replaces the old `defineView` / `ViewRegistry` path). A `sparseView`
- * requires every `@maintainedFrom` to carry a `when` membership predicate.
- */
-type ModelKind = 'entity' | 'materializedView' | 'sparseView';
-/**
- * One lowered `@maintainedFrom(source, (self, source) => options)` declaration on a
- * view model (issue #152). It is the decorator-declarative replacement for one
- * `defineView` source slice: the symbolic `(self, source) =>` callback has already
- * been evaluated into the SAME payload-rooted IR (`keyBind` → `$.entity.*` key
- * binding, `project` → {@link ProjectionMap}), so the adapter
- * (`src/relation/maintenance-view-adapter.ts`) reconstructs a byte-identical
- * `ViewSourceSlice` from it.
- *
- * `collection` and `when` are mutually exclusive (a row either holds a maintained
- * list or appears/disappears as a whole — the same rule the old builder enforced).
- */
-interface MaintainedFromMetadata {
-    /** Resolves the source entity whose lifecycle events maintain the view row. */
-    sourceFactory: () => new (...args: unknown[]) => unknown;
-    /** The lifecycle events that maintain the view row (`created`/`updated`/`removed`). */
-    on: readonly MaintainEvent[];
-    /** The view-row key binding (view-row key field → payload-rooted source value). */
-    keyBind: Readonly<Record<string, EffectPath>>;
-    /** The projection of the source payload into the view row (target attr → transform). */
-    project: ProjectionMap;
-    /** Bounded/ordered collection options when this declaration maintains a list. */
-    collection?: {
-        /** The view-row attribute that holds the maintained list (a `self.<field>`). */
-        field: string;
-        maxItems?: number;
-        order?: 'ASC' | 'DESC';
-        /** The source value the collection orders by / trims on (`$.entity.<field>`). */
-        orderBy?: EffectPath;
-    };
-    /** Sparse-view membership predicate (mutually exclusive with `collection`). */
-    when?: MembershipPredicate;
-    consistency?: MaintainConsistency;
-    updateMode?: MaintainUpdateMode;
-    /**
-     * Optional human-readable description of this maintained-from source slice (issue
-     * #166, follow-up of #154), supplied via
-     * `@maintainedFrom(() => Source, (self, source) => ({ description, ... }))`. Pure
-     * documentation metadata — it does NOT affect the maintenance IR (`keyBind` /
-     * `project` / `on` / `collection` / `when`) or any runtime behaviour.
-     *
-     * NOTE (representation): the maintenance IR is deliberately kept OFF the
-     * serializable `manifest.json` / `operations.json` — the {@link Manifest} carries
-     * only the physical shape (table / keys / GSIs / relation navigation), NOT the
-     * maintenance graph (see `detectStreamMaintenance` in `src/codegen/cloudformation.ts`).
-     * There is therefore no manifest / operations / generated-Python site for a
-     * maintained-from source; this description is captured at the metadata layer only
-     * (mirroring where #154 captured its descriptions before propagation), available to
-     * any future consumer that DOES surface `@maintainedFrom` (e.g. the CDC-projection
-     * typed-consumer path, #153). Absent → byte-for-byte unchanged metadata.
-     */
-    description?: string;
-}
-interface KeyDefinition {
-    /** The canonical structured key (PK/SK segment lists). */
-    segmented: SegmentedKey;
-    inputFieldNames: string[];
-}
-interface GsiDefinition {
-    indexName: string;
-    /** The canonical structured key (PK/SK segment lists). */
-    segmented: SegmentedKey;
-    inputFieldNames: string[];
-    unique: boolean;
-    /**
-     * Optional human-readable description of the GSI (issue #166, follow-up of #154),
-     * supplied via `gsi(name, key, { description })`. Pure documentation metadata — it
-     * does NOT affect the index key, projection, or any runtime behaviour. When present
-     * it is propagated to the index entry in `manifest.json`
-     * ({@link ManifestGsi.description}) and surfaces as the docstring of any generated
-     * Python query method that reads through this index (a query carrying the GSI's
-     * `indexName`, when the query itself declares no description). Absent →
-     * byte-for-byte unchanged output (backward compatible).
-     */
-    description?: string;
-}
-interface RelationLimitOptions {
-    default: number;
-    max: number;
-}
-/**
- * The named maintenance pattern a relation participates in (Epic #118 §5.1).
- *
- * `pattern` is the *preset* selector: omitting it leaves the relation a plain
- * read-only navigation (the historical `hasMany`/`belongsTo`/`hasOne`
- * behaviour), exactly backward compatible. When present it names the AWS
- * design pattern the relation lowers to — the lowering itself (maintenance
- * graph / compile injection) is out of scope for issue #121 and lands in
- * #124/#125; here the value is recorded purely as declaration metadata.
- *
- * Typed as a `string` union of the known presets but kept open-ended via the
- * `(string & {})` tail so a future preset can be authored before this union is
- * widened, without a breaking change to callers.
- *
- * The union lists only the presets that are actually *reachable* as a recorded
- * `RelationOptions.pattern` / `AggregateOptions.pattern` value: `samePartition`,
- * `counter`, `embeddedSnapshot`, and the two versioned discriminators
- * `versionedLatest` / `versionedHistory` (issue #152). `materializedView` /
- * `sparseView` migrated to the model-level `@model({ kind })` selector (they are
- * a {@link ModelKind}, not a relation preset); the placeholder `edge` /
- * `dualEdge` / `versioned` / `externalProjection` names are not authored anywhere
- * and were removed. A future preset can still be written against the `(string & {})`
- * tail before it is added to this union.
- */
-type RelationPattern = 'samePartition' | 'counter' | 'embeddedSnapshot' | 'versionedLatest' | 'versionedHistory' | (string & {});
-/**
- * Consistency boundary a maintained write is declared against (Epic #118 §4.A.7):
- * `transactional` = same `TransactWriteItems`; `eventual` = asynchronous catch-up.
- */
-type RelationConsistency = 'transactional' | 'eventual';
-/**
- * How a maintained write is applied (Epic #118 §4.A.7):
- * `mutation` = composed into the same mutation; `stream` = driven asynchronously
- * off a stream / outbox.
- */
-type RelationUpdateMode = 'mutation' | 'stream';
-/**
- * Read-strategy hints for a maintained relation (Epic #118 §5.1 `read`).
- *
- * All fields optional — present only when a `pattern` declares a read shape
- * (e.g. an `embeddedSnapshot` keeping the latest N items). A bare relation
- * carries no `read` block.
- */
-interface RelationReadOptions {
-    /** Cap on materialised items kept inline (e.g. "latest 3 posts"). */
-    maxItems?: number;
-    /** Ordering of the maintained collection. */
-    order?: 'ASC' | 'DESC';
-}
-/**
- * Write-maintenance declaration for a relation (Epic #118 §5.1 `write`).
- *
- * `maintainedOn` is the cross-entity trigger list (`"<Entity>.<event>"`, e.g.
- * `"Post.created"`) that the maintenance graph (#124/#125) will key off. Recorded
- * here as declaration metadata only.
- */
-interface RelationWriteOptions {
-    /**
-     * Cross-entity triggers, e.g. `['Post.created', 'Post.removed']`. The event
-     * segment is the confirmed shared lifecycle vocabulary (epic #118 A/B
-     * reconciliation): `created` / `updated` / `removed`.
-     */
-    maintainedOn?: string[];
-    consistency?: RelationConsistency;
-    updateMode?: RelationUpdateMode;
-}
-/**
- * Snapshot / projection capture map for a maintained relation
- * (Epic #118 §5.1 / §5.2 `projection`).
- *
- * Maps each captured field name on the maintaining side to **how** the source
- * value is projected. The confirmed shared vocabulary (epic #118 A/B
- * reconciliation) is the **function-form IR** — the same {@link
- * ProjectionTransform} node A (#120) defines on `src/define/entity-writes.ts`,
- * re-used here (NOT re-defined) so the two surfaces never re-diverge. Each value
- * is either:
- *
- * - a {@link ProjectionTransform} (built with the standalone authoring helpers,
- *   e.g. `preview('body', 120)` — RFC §5.2 `textPreview: preview('body', 120)`),
- *   or
- * - a bare `string` — the **identity shorthand**: project that source path
- *   through unchanged (e.g. `{ postId: 'postId' }`).
- *
- * `Readonly` so the recorded declaration metadata is not mutated downstream.
- * Issue #121 scopes this to the declaration shape; the maintenance graph /
- * compile injection that consumes the IR is #124/#125.
- *
- * @example `{ postId: 'postId', textPreview: preview('body', 120) }`
- */
-type RelationProjection = Readonly<Record<string, ProjectionTransform | string>>;
-interface RelationOptions {
-    limit?: RelationLimitOptions;
-    order?: 'ASC' | 'DESC';
-    /**
-     * Optional human-readable description of the relation (issue #166, follow-up of
-     * #154), supplied via `@hasMany/@belongsTo/@hasOne(() => T, keyBind, { description })`.
-     * Pure documentation metadata — it does NOT affect navigation, key binding, or any
-     * runtime behaviour. When present it is propagated to the relation entry in
-     * `manifest.json` ({@link ManifestRelation.description}) and surfaces as a trailing
-     * `# …` comment on the relation's field in the generated Python result TypedDict /
-     * dataclass. Absent → byte-for-byte unchanged output (backward compatible).
-     */
-    description?: string;
-    /**
-     * Named maintenance preset (Epic #118). Omitted = plain read-only navigation,
-     * fully backward compatible with the historical relation decorators.
-     */
-    pattern?: RelationPattern;
-    read?: RelationReadOptions;
-    write?: RelationWriteOptions;
-    projection?: RelationProjection;
-    /**
-     * Lowered versioned-pattern declaration (issue #152, section B). Present only when
-     * the relation declares `pattern: 'versionedLatest' | 'versionedHistory'` via the
-     * `@hasOne/@hasMany(() => Target, (self, source) => ({...}))` callback form. The
-     * declaring model is the SOURCE (a revision); the relation target is the
-     * DESTINATION view row. The adapter
-     * (`src/relation/maintenance-view-adapter.ts`) lowers this to the SAME `defineView`
-     * snapshot IR the old `defineVersioned` produced (latest = overwrite, history =
-     * append). `on` are the lifecycle events; `project` is the lowered projection map.
-     */
-    versioned?: {
-        readonly mode: 'latest' | 'history';
-        readonly on: readonly MaintainEvent[];
-        readonly project: ProjectionMap;
-        readonly consistency?: MaintainConsistency;
-        readonly updateMode?: MaintainUpdateMode;
-    };
-}
-/**
- * Descriptor for a `refs` relation (issue #197, Pattern 2 Embedded Refs read
- * side). A `refs` relation resolves an **inline id-list** held on the parent row
- * — e.g. `PPost.tagRefs: { tagId: string }[]` — into the referenced child
- * bodies, in ONE deduped `BatchGetItem` (never per-ref `GetItem`).
- *
- * Unlike `hasMany`/`belongsTo`/`hasOne`, whose key is bound from a parent
- * **scalar** field ({@link RelationMetadata.keyBinding} — `target key ← parent
- * scalar`), a `refs` key is bound from EACH ELEMENT of a parent LIST attribute:
- * the traversal reads `parent[from]` (a list), pulls `.key` off every element,
- * and fans those out into a single BatchGet against the target. This descriptor
- * captures exactly that list-valued source shape, which the scalar `keyBinding`
- * `Record<string,string>` cannot express.
- *
- * `keyBinding` on a `refs` relation still records the **target child key field ←
- * element key name** mapping (e.g. `{ tagId: 'tagId' }`), so key building /
- * projection reuse the existing scalar machinery per resolved element; `refs`
- * only adds *where the scalar values come from* (the parent list), not a new key
- * grammar. That keeps `refs` byte-compatible with every scalar-keyBinding
- * consumer (manifest, planner, dedupe) — an unknown-to-them relation kind is
- * simply carried through with a valid scalar `keyBinding`.
- */
-interface RefsBinding {
-    /** The parent LIST attribute holding the inline reference elements (e.g. `'tagRefs'`). */
-    from: string;
-    /** The key field to read off EACH list element (e.g. `'tagId'`). */
-    key: string;
-}
-interface RelationMetadata {
-    type: 'hasMany' | 'hasOne' | 'belongsTo' | 'refs';
-    propertyName: string;
-    targetFactory: () => new (...args: unknown[]) => unknown;
-    keyBinding: Record<string, string>;
-    /**
-     * List-valued source descriptor for a `refs` relation (issue #197). Present
-     * IFF `type === 'refs'`; the traversal reads the parent list `refs.from`, pulls
-     * `refs.key` off each element, and resolves the referenced child bodies in one
-     * deduped BatchGet. Absent for every scalar-keyed relation (byte-compatible).
-     */
-    refs?: RefsBinding;
-    options?: RelationOptions;
-}
-/**
- * The scalar-aggregate value an `@aggregate` field derives from its source entity
- * (Epic #118 §5.2 counter / latest preset; issue #122). It is the function-form
- * IR built by the {@link count} / {@link max} value helpers — the aggregation an
- * `@aggregate(() => Source, keyBinding, { pattern, value })` field maintains:
- *
- * - `count` — the cardinality of source rows matched by the key binding (no
- *   source field; e.g. `postCount!: number` ← `count()`).
- * - `max` — the maximum value of a named source `field` (e.g. `lastPostAt!:
- *   string` ← `max('createdAt')`).
- *
- * Recorded purely as declaration metadata (issue #122 scope = declaration
- * surface): the maintenance graph (#124) / compile injection (#125) consume it;
- * the effect itself is out of scope here. Kept open-ended via the discriminated
- * `op` so a future aggregation (`min`, `sum`, …) extends the union without a
- * breaking change.
- *
- * @example `count()` → `{ op: 'count' }`
- * @example `max('createdAt')` → `{ op: 'max', field: 'createdAt' }`
- */
-type AggregateValue = {
-    readonly op: 'count';
-} | {
-    readonly op: 'max';
-    readonly field: string;
-};
-/**
- * Options for an `@aggregate` field (Epic #118 §5.2 counter / latest preset;
- * issue #122). Mirrors the maintenance vocabulary a relation declares so the two
- * authoring surfaces stay in lockstep:
- *
- * - `pattern` reuses {@link RelationPattern} (e.g. `'counter'`) — the named
- *   maintenance preset, NOT re-defined here.
- * - `value` is the {@link AggregateValue} the field maintains (`count()` /
- *   `max('createdAt')`).
- * - `write` reuses {@link RelationWriteOptions} verbatim — `maintainedOn`
- *   triggers (`Post.created` / `Post.removed`, the confirmed shared
- *   `created|updated|removed` event vocabulary) plus `consistency`
- *   (`transactional|eventual`) / `updateMode` (`mutation|stream`). These are NOT
- *   re-defined; they are the same shared types B (#121) added.
- */
-interface AggregateOptions {
-    /** Named maintenance preset (typically `'counter'`); reuses {@link RelationPattern}. */
-    pattern?: RelationPattern;
-    /** The scalar aggregation this field maintains (`count()` / `max('createdAt')`). */
-    value: AggregateValue;
-    /** Cross-entity maintenance triggers / consistency / update-mode (reused from B). */
-    write?: RelationWriteOptions;
-}
-/**
- * Declaration metadata recorded by an `@aggregate` field decorator (issue #122).
- *
- * An `@aggregate` is a **scalar** field (`postCount!: number`,
- * `lastPostAt!: string`) whose value is derived — by aggregating rows of a source
- * entity resolved by {@link targetFactory} + {@link keyBinding} — rather than
- * stored directly. It is therefore recorded in its **own** metadata array
- * (`EntityMetadata.aggregates`), distinct from both {@link FieldMetadata} (a
- * plain stored attribute) and {@link RelationMetadata} (a navigation yielding
- * model instances): an aggregate carries a source binding like a relation, but
- * surfaces a scalar value like a field. The collector path mirrors relations
- * (decorator pushes, `@model` drains).
- *
- * Issue #122 scope is the declaration surface + metadata pass-through only; the
- * aggregation effect's compile / runtime (#124/#125/#127) is out of scope.
- */
-interface AggregateMetadata {
-    /** The scalar field the aggregate value is written to. */
-    propertyName: string;
-    /** Resolves the source entity whose rows are aggregated. */
-    targetFactory: () => new (...args: unknown[]) => unknown;
-    /** The key binding selecting the source rows (target key field → source field). */
-    keyBinding: Record<string, string>;
-    /** The aggregate preset / value / maintenance-write declaration. */
-    options: AggregateOptions;
-}
-interface EmbeddedMetadata {
-    propertyName: string;
-    modelFactory: () => new (...args: unknown[]) => unknown;
-}
-interface EntityMetadata {
-    tableName: string;
-    prefix: string;
-    fields: FieldMetadata[];
-    primaryKey: KeyDefinition | null;
-    gsiDefinitions: GsiDefinition[];
-    relations: RelationMetadata[];
-    /** Scalar `@aggregate` fields (Epic #118 §5.2 counter / latest; issue #122). */
-    aggregates: AggregateMetadata[];
-    embeddedFields: EmbeddedMetadata[];
-    /**
-     * The model's maintenance kind (issue #152). `'entity'` (default; also assumed
-     * when absent, for hand-built metadata in tests) is a plain stored entity;
-     * `'materializedView'` / `'sparseView'` mark it a maintained view row fed by
-     * {@link maintainedFrom}.
-     */
-    kind?: ModelKind;
-    /**
-     * Optional human-readable description of the entity (issue #154), supplied via
-     * `@model({ description })`. Pure documentation metadata — it does NOT affect
-     * storage, keys, or any runtime behaviour. When present it is propagated to the
-     * entity entry in `manifest.json` ({@link ManifestEntity.description}) and
-     * surfaces as the class docstring in the generated Python `types.py`. Absent →
-     * byte-for-byte unchanged output (backward compatible).
-     */
-    description?: string;
-    /**
-     * Class-level `@maintainedFrom(...)` declarations (issue #152). Non-empty only on
-     * a `materializedView` / `sparseView` model; each is one source slice the view
-     * row is maintained from. The adapter lowers these to the maintenance graph's
-     * `ViewDefinition` IR (replacing the old `defineView` / `ViewRegistry` path).
-     * Absent / empty for a plain entity.
-     */
-    maintainedFrom?: MaintainedFromMetadata[];
-    /**
-     * Whether the model is flagged **CDC-parseable** by `@cdcProjected()` (issue
-     * #153). It carries NO runtime side effect — it is purely a compile-/registration-
-     * time capability marker: `Model.fromChange(event)` (and, transitively,
-     * `DDBModel.subscribe` routing to this model) is gated on it, and it is the SSoT
-     * the codegen reads to emit the `CdcModelRegistry` module augmentation that types
-     * `subscribe`'s handlers by model name. `true` only on a model carrying the
-     * decorator; absent (⇒ falsy) for every plain entity, so a non-`@cdcProjected`
-     * model is byte-for-byte unchanged (backward compatible). Deliberately kept OFF
-     * the manifest / bridge (it is a host-runtime + TS-typing concern, like the
-     * maintenance signals — not a physical-schema fact like {@link ttlAttribute}).
-     */
-    cdcProjected?: boolean;
-    /**
-     * The physical attribute name of the model's `@ttl` field, when one is declared
-     * (issue #172, Epic #167 — CFn generator C4). DynamoDB TTL requires a single
-     * Number attribute holding epoch seconds; `@model` derives this from the (unique)
-     * field carrying {@link FieldMetadata.ttl} and throws if more than one field on the
-     * SAME model is `@ttl` (the cross-entity, same-physical-table single-TTL rule is
-     * enforced downstream, at manifest build, where all entities on a table are known).
-     * A non-key field's physical attribute name is its property name, so this is the
-     * `@ttl` field's property name. Propagated to the manifest
-     * ({@link ManifestEntity.ttlAttribute}) — the SSoT the CloudFormation emitter reads
-     * to render `TimeToLiveSpecification`. Absent when the model declares no `@ttl`.
-     */
-    ttlAttribute?: string;
-}
-
-/**
- * Decorator-metadata → maintenance-graph `ViewDefinition` adapter (issue #152).
- *
- * ## What this replaces
- *
- * The old `defineView` / `defineVersioned` builders (deleted) registered
- * `ViewDefinition`s into a side `ViewRegistry`, which the maintenance graph read.
- * That builder carried a registration side-effect + a `generation` counter (a
- * silent-drop guard). This adapter removes that whole path: it derives the SAME
- * `ViewDefinition` IR purely from the declarative `MetadataRegistry` — the
- * Contract-layer SSoT, whose own `generation` counter is the single
- * invalidation source — so a view declared via `@model({ kind })` + `@maintainedFrom`
- * (and a versioned relation declared via `@hasOne/@hasMany` `pattern`) is discovered
- * with no separate registry.
- *
- * ## IR invariance
- *
- * The `ViewDefinition` / `ViewSourceSlice` shapes are UNCHANGED. The maintenance
- * graph, the K (#130) stream/drain, and the L (#131) rebuild consume the adapter's
- * output exactly as they consumed `ViewRegistry.getAll()`. Only the SOURCE of the
- * definitions moved from a builder side-effect to declarative metadata.
- *
- * ## Order independence (issue #152 hardening)
- *
- * Stacked `@maintainedFrom` declarations carry no order meaning. The adapter rejects
- * — symmetrically, so the error is identical whichever order the decorators are
- * stacked — any two declarations on the same view that:
- *   1. write the SAME projection target attribute (ambiguous duplicate projection);
- *   2. maintain the SAME `collection.field`;
- *   3. bind the SAME view-key field to a DIFFERENT source path (the view-row identity
- *      would be inconsistent across sources).
- * A legitimate multi-source view (different sources filling DIFFERENT fields, all
- * binding the SAME key the SAME way) is fine.
- */
-
-type AnyModelClass = abstract new (...args: any[]) => any;
-/** The view source slice IR the maintenance graph consumes (one per source × view). */
-interface ViewSourceSlice {
-    readonly sourceClass: AnyModelClass;
-    readonly maintainedOn: readonly MaintainTrigger[];
-    readonly keys: Readonly<Record<string, EffectPath>>;
-    readonly project: ProjectionMap;
-    readonly collection?: {
-        readonly field: string;
-        readonly maxItems?: number;
-        readonly orderBy?: EffectPath;
-        readonly orderDir?: 'ASC' | 'DESC';
-    };
-    readonly predicate?: MembershipPredicate;
-}
-/** The view definition IR — an independent view row maintained from one or more sources. */
-interface ViewDefinition {
-    readonly name: string;
-    readonly viewClass: AnyModelClass;
-    readonly pattern: 'materializedView' | 'sparseView';
-    readonly slices: readonly ViewSourceSlice[];
-    readonly updateMode?: 'mutation' | 'stream';
-    readonly consistency?: 'transactional' | 'eventual';
-}
-/**
- * Build every {@link ViewDefinition} for a registry — from `@model({ kind })` +
- * `@maintainedFrom` view models AND from versioned-pattern relations. This is the
- * adapter the maintenance graph calls in place of the deleted `ViewRegistry.getAll()`.
- *
- * @param registry The models to scan. Defaults to `MetadataRegistry.getAll()`.
- */
-declare function collectViewDefinitions(registry?: ReadonlyMap<Function, EntityMetadata>): ViewDefinition[];
-
-export { type DerivedOutboxEvent as $, type ParamDescriptor as A, type BatchResult as B, type CdcEmulatorOptions as C, type DynamoDBOperation as D, type EventLog as E, type FaultSpec as F, type EntityRef as G, type ConditionInput as H, type DefinitionMap as I, type AnyOperationDefinition as J, type PreparedBody as K, type CompiledFragment as L, type ModelStatic as M, type CompiledMutationPlan as N, type DerivedConditionCheck as O, type PutInput as P, type QueryModelContract as Q, type ReplayOptions as R, type ShardId as S, type TransactWriteExecItem as T, type Unsubscribe as U, type ViewDefinition as V, type WriteExecOptions as W, type DerivedEdgeWrite as X, type DerivedIdempotencyGuard as Y, type DerivedMaintainOutbox as Z, type DerivedMaintainWrite as _, type CdcMode as a, type CdcModelRegistry as a$, type DerivedUniqueGuard as a0, type DerivedUpdate as a1, type EntityRefResolver as a2, MAX_TRANSACT_COMPOSE_ITEMS as a3, assertNoCrossFragmentMaintainCollision as a4, compileFragment as a5, compileMutationPlan as a6, compileSingleFragmentPlan as a7, resetMaintenanceGraphCache as a8, resolveLifecycle as a9, type SelectBuilderSpec as aA, type RawCondition as aB, type ExecutionPlan as aC, type FieldMetadata as aD, type ResolvedKey as aE, type Slot as aF, type PreparedWriteExecOptions as aG, type CommandReturn as aH, type ParallelOpResult as aI, type PreparedStatement as aJ, type RelationMetadata as aK, type MaintainEffect as aL, type OperationDefinition as aM, type WriteDefinitionOptions as aN, type PartialQueryKeyOf as aO, type StrictSelectSpec as aP, type ReadDefinitionOptions as aQ, type EntityInput as aR, type UniqueQueryKeyOf as aS, type AggregateMetadata as aT, type BatchDeleteRequest as aU, type BatchGetOptions as aV, type BatchGetRequest as aW, BatchGetResult as aX, type BatchPutRequest as aY, type BatchWriteRequest as aZ, CONTRACT_RANGE_FANOUT_CONCURRENCY as a_, resolveMaintainers as aa, type SelectableOf as ab, type PrimaryKeyOf as ac, type RequestContext as ad, type Middleware as ae, type ReadRequestKind as af, type CtxModel as ag, type ReadParams as ah, type ReadRequestCtx as ai, type Item as aj, type RetryPolicy as ak, type RetryOverride as al, type KeyDefinition as am, type GsiDefinition as an, type ModelKind as ao, type FieldOptions as ap, type DynamoType as aq, type ProjectionTransform as ar, type MaintainEvent as as, type MembershipPredicate as at, type MaintainConsistency as au, type MaintainUpdateMode as av, type MembershipPredicateOp as aw, type RelationOptions as ax, type AggregateOptions as ay, type AggregateValue as az, type ChangeBatch as b, type MembershipEffect as b$, type CdcSubscribeHandlers as b0, type Change as b1, type CollectionEffect as b2, type CollectionOptions as b3, type Column as b4, type ColumnMap as b5, type CommandInputShape as b6, type CommandMethod as b7, type CommandPlan as b8, type CommandResultKind as b9, type EmbeddedMetadata as bA, type EmitEffect as bB, type EntityWritesDefinition as bC, type EntityWritesShape as bD, type ExecutableCommandContract as bE, type ExecutableQueryContract as bF, type FilterInput as bG, type FragmentCondition as bH, type FragmentConditionOperatorObject as bI, type FragmentInput as bJ, type GsiDefinitionMarker as bK, type GsiOptions as bL, type IdempotencyEffect as bM, type InProcessWriteDescriptor as bN, type InlineSnapshotSpec as bO, type InputArity as bP, type KeyDefinitionMarker as bQ, type KeySegment as bR, type KeySlot as bS, type KeyStructure as bT, type KeyedResult as bU, LIFECYCLE_CONTRACT_MARKER as bV, type LifecycleContract as bW, type LifecycleEffects as bX, type MaintainItem as bY, type MaintainTrigger as bZ, type MaintenanceGraph as b_, type CommandSelectShape as ba, type CondSlot as bb, type ConditionCheckInput as bc, type Connection as bd, type ContractCallSignature as be, type ContractCommandParams as bf, type ContractComposeNode as bg, type ContractFromRef as bh, type ContractItem as bi, type ContractKeyFieldRef as bj, type ContractKeyInput as bk, type ContractKeyRef as bl, type ContractMethodOp as bm, type ContractParamRef as bn, type ContractQueryParams as bo, type CounterAggregate as bp, type CounterEffect as bq, type CtxBase as br, DEFAULT_MAX_ATTEMPTS as bs, DEFAULT_RETRY_POLICY as bt, type DeleteOptions as bu, type DeriveEffect as bv, type DescriptorBinding as bw, ENTITY_WRITES_MARKER as bx, type EdgeEffect as by, type EffectPath as bz, type ChangeEvent as c, type WriteDescriptor as c$, type ModelRef as c0, type MutateMode as c1, type MutateOptions as c2, type MutateParallelResult as c3, type MutateTransactionResult as c4, type MutationBody as c5, type MutationDescriptorMap as c6, type MutationFragment as c7, type MutationInputProxy as c8, type MutationInputRef as c9, type ReadRouteResult as cA, type RecordedCompose as cB, type RelationBuilder as cC, type RelationConsistency as cD, type RelationLimitOptions as cE, type RelationPattern as cF, type RelationProjection as cG, type RelationReadOptions as cH, type RelationSelect as cI, type RelationSpec as cJ, type RelationUpdateMode as cK, type RelationWriteOptions as cL, type RequiresEffect as cM, type Resolution as cN, type RetryInfo as cO, type RetryOperationKind as cP, type SegmentSpec as cQ, type SegmentedKey as cR, type SelectBuilder as cS, type SelectOf as cT, type SnapshotEffect as cU, TransactionContext as cV, type UniqueEffect as cW, type Updatable as cX, type UpdateOptions as cY, type ViewSourceSlice as cZ, type WriteCtx as c_, type MutationIntent as ca, type OperationKind as cb, PREPARE_CACHE_MAX as cc, type ParamStructure as cd, type PersistCtx as ce, type PersistOrigin as cf, type PlannedCommandMethod as cg, type PreparedInputProxy as ch, type PreparedParamRef as ci, type PreparedReadExecOptions as cj, type PreparedReadRoute as ck, PreparedReadStatement as cl, type PreparedWriteRoute as cm, PreparedWriteStatement as cn, type ProjectionMap as co, type ProjectionTransformOp as cp, type PutOptions as cq, type QueryEnvelopeResult as cr, type QueryKeyOf as cs, type QueryMethod as ct, type QueryResult as cu, type ReadEnvelope as cv, type ReadOpCtx as cw, type ReadOpKind as cx, type ReadRouteDescriptor as cy, type ReadRouteOptions as cz, type ChangeEventName as d, wholeKeysSentinel as d$, type WriteEnvelope as d0, type WriteInput as d1, type WriteKind as d2, type WriteLifecyclePhase as d3, type WriteMiddleware as d4, type WriteRecorder as d5, type WriteResultProjection as d6, attachModelClass as d7, buildDeleteInput as d8, buildMaintenanceGraph as d9, isContractFromRef as dA, isContractKeyFieldRef as dB, isContractKeyRef as dC, isContractParamRef as dD, isEntityWritesDefinition as dE, isKeySegment as dF, isLifecycleContract as dG, isMaintainTrigger as dH, isMutationFragment as dI, isMutationInputRef as dJ, isPlannedCommandMethod as dK, isPreparedParamRef as dL, isQueryModelContract as dM, isRetryableError as dN, isRetryableTransactionCancellation as dO, k as dP, key as dQ, lifecyclePhaseForIntent as dR, maintainTrigger as dS, mintContractKeyFieldRef as dT, mintContractParamRef as dU, mutation as dV, prepare as dW, preview as dX, publicCommandModel as dY, publicQueryModel as dZ, query as d_, buildPutInput as da, buildUpdateInput as db, collectViewDefinitions as dc, cond as dd, contractOfMethodSpec as de, definePlan as df, entityWrites as dg, executeBatchGet as dh, executeBatchWrite as di, executeCommandMethod as dj, executeDelete as dk, executeKeyedBatchGet as dl, executePut as dm, executeQueryMethod as dn, executeRangeFanout as dp, executeTransaction as dq, executeUpdate as dr, from as ds, getEntityWrites as dt, gsi as du, identity as dv, isColumn as dw, isCommandModelContract as dx, isCommandPlan as dy, isContractComposeNode as dz, type ChangeHandler as e, type ClockMode as f, type ConcurrentRecomputeRef as g, type StartingPosition as h, type StreamViewType as i, type SubscribeHandler as j, type SubscribeHandlers as k, buildSubscribeHandler as l, type EntityMetadata as m, type Executor as n, type ReadExecOptions as o, type ExecutorResult as p, type BatchGetExecInput as q, type WriteResult as r, type UpdateInput as s, type DeleteInput as t, type BatchWriteExecItem as u, type BatchExecOptions as v, DDBModel as w, type QueryMethodSpec as x, type CommandModelContract as y, type CommandMethodSpec as z };
+export { type AnyOperationDefinition as $, type EventLog as A, type BatchGetExecInput as B, type CommandReturn as C, DDBModel as D, type EffectPath as E, type FaultSpec as F, type ReplayOptions as G, type ShardId as H, type MaintainTrigger as I, type BatchResult as J, type CdcMode as K, type ChangeBatch as L, type ModelStatic as M, type ChangeEventName as N, type ClockMode as O, type PreparedWriteExecOptions as P, type QueryModelContract as Q, type ReadExecOptions as R, type Slot as S, type TransactWriteExecItem as T, type UpdateInput as U, type StartingPosition as V, type WriteExecOptions as W, type StreamViewType as X, type SubscribeHandler as Y, type SubscribeHandlers as Z, buildSubscribeHandler as _, type ParallelOpResult as a, type SelectBuilder as a$, type TransactionDefinition as a0, type CompiledFragment as a1, type CompiledMutationPlan as a2, type DerivedConditionCheck as a3, type DerivedEdgeWrite as a4, type DerivedIdempotencyGuard as a5, type DerivedMaintainOutbox as a6, type DerivedMaintainWrite as a7, type DerivedOutboxEvent as a8, type DerivedUniqueGuard as a9, type GsiDefinitionMarker as aA, type GsiOptions as aB, type InlineSnapshotSpec as aC, type Item as aD, type KeyDefinitionMarker as aE, type KeySegment as aF, type KeySlot as aG, type KeyStructure as aH, type MutateAuthoringOptions as aI, type ParamDescriptor as aJ, type ParamStructure as aK, type PartialQueryKeyOf as aL, type PersistCtx as aM, type PersistOrigin as aN, type QueryKeyOf as aO, type QueryResult as aP, type RawCondition as aQ, type ReadOpCtx as aR, type ReadOpKind as aS, type ReadParams as aT, type ReadRequestCtx as aU, type ReadRequestKind as aV, type RelationBuilder as aW, type RelationSelect as aX, type RelationSpec as aY, type RequestContext as aZ, type SegmentSpec as a_, type DerivedUpdate as aa, type EntityRefResolver as ab, MAX_TRANSACT_COMPOSE_ITEMS as ac, assertNoCrossFragmentMaintainCollision as ad, compileFragment as ae, compileMutationPlan as af, compileSingleFragmentPlan as ag, resetMaintenanceGraphCache as ah, resolveLifecycle as ai, resolveMaintainers as aj, type SelectableOf as ak, type PrimaryKeyOf as al, type MembershipPredicateOp as am, publishQuery as an, publishCommand as ao, type RetryPolicy as ap, type Middleware as aq, type CdcModelRegistry as ar, type CdcSubscribeHandlers as as, type Change as at, type Column as au, type ColumnMap as av, type CondSlot as aw, type CtxBase as ax, type CtxModel as ay, type FilterInput as az, type PreparedBody as b, type SelectOf as b0, type UniqueQueryKeyOf as b1, type Updatable as b2, type WriteCtx as b3, type WriteInput as b4, type WriteKind as b5, type WriteMiddleware as b6, cond as b7, entityWrites as b8, getEntityWrites as b9, gsi as ba, identity as bb, k as bc, key as bd, mutate as be, preview as bf, when as bg, type PreparedStatement as c, type SegmentedKey as d, type ProjectionTransform as e, type MaintainEvent as f, type ProjectionMap as g, type MaintainConsistency as h, type MaintainUpdateMode as i, type MembershipPredicate as j, type QueryMethodSpec as k, type CommandModelContract as l, type CommandMethodSpec as m, type Executor as n, type DynamoDBOperation as o, type ExecutorResult as p, type PutInput as q, type WriteResult as r, type DeleteInput as s, type BatchWriteExecItem as t, type BatchExecOptions as u, type ChangeEvent as v, type CdcEmulatorOptions as w, type ChangeHandler as x, type Unsubscribe as y, type ConcurrentRecomputeRef as z };