graphddb 0.2.4 → 0.2.5

package/dist/{types-BEeQ_nSd.d.ts → types--tdHK3vi.d.ts}

@@ -778,6 +778,552 @@ 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>;
+    ConditionExpression?: string;
+    ExpressionAttributeNames?: Record<string, string>;
+    ExpressionAttributeValues?: Record<string, unknown>;
+}
+declare function buildPutInput(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): PutInput;
+declare function executePut(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): Promise<void>;
+
+interface UpdateInput {
+    TableName: string;
+    Key: Record<string, unknown>;
+    UpdateExpression: string;
+    ExpressionAttributeNames: Record<string, string>;
+    ExpressionAttributeValues?: Record<string, unknown>;
+    ConditionExpression?: string;
+}
+declare function buildUpdateInput(modelClass: Function, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): UpdateInput;
+declare function executeUpdate(modelClass: Function, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): Promise<void>;
+
+interface DeleteInput {
+    TableName: string;
+    Key: Record<string, unknown>;
+    ConditionExpression?: string;
+    ExpressionAttributeNames?: Record<string, string>;
+    ExpressionAttributeValues?: Record<string, unknown>;
+}
+declare function buildDeleteInput(modelClass: Function, keyObj: Record<string, unknown>, options?: DeleteOptions): DeleteInput;
+declare function executeDelete(modelClass: Function, keyObj: Record<string, unknown>, options?: DeleteOptions): Promise<void>;
+
+/** Result of a read operation (GetItem / Query / BatchGetItem). */
+interface ExecutorResult {
+    items: Record<string, unknown>[];
+    lastEvaluatedKey?: Record<string, unknown>;
+}
+/**
+ * Result of a single structured write. `oldItem` is the pre-write image,
+ * present only when the caller requested it (`returnOldImage: true`, mapped to
+ * DynamoDB `ReturnValues: ALL_OLD`) and an item existed before the write. The
+ * write-capture seam (issue #72) reads it to derive INSERT vs MODIFY and the
+ * REMOVE OldImage.
+ */
+interface WriteResult {
+    oldItem?: Record<string, unknown>;
+}
+/**
+ * A per-call retry override threaded down to {@link RetryingExecutor} (issue
+ * #111). `undefined` ⇒ use the globally-configured (or default) policy; a
+ * {@link RetryPolicy} ⇒ use that for this call; `false` ⇒ disable retry for this
+ * call. The default {@link DynamoExecutor} and the test `MemoryExecutor` ignore
+ * it — only {@link RetryingExecutor} acts on it.
+ */
+type RetryOverride = RetryPolicy | false;
+/**
+ * Per-call options for the READ path (issue #111). Carries the per-op retry
+ * override down to {@link RetryingExecutor}. Extended (rather than passing the
+ * override positionally) so future per-call read knobs have a home.
+ */
+interface ReadExecOptions {
+    /** Per-call retry override; see {@link RetryOverride}. */
+    retry?: RetryOverride;
+}
+/** Options shared by the single-item structured write methods. */
+interface WriteExecOptions {
+    /** Request the pre-write image (DynamoDB `ReturnValues: ALL_OLD`). */
+    returnOldImage?: boolean;
+    /** Per-call retry override (issue #111); see {@link RetryOverride}. */
+    retry?: RetryOverride;
+}
+/** Per-call options for the batch / transact paths (issue #111). */
+interface BatchExecOptions {
+    /** Per-call retry override; see {@link RetryOverride}. */
+    retry?: RetryOverride;
+}
+/**
+ * One BatchGetItem sub-request: a single physical table plus its keys and an
+ * optional projection. Mirrors {@link import('../planner/types.js').BatchGetItemOperation}
+ * without the discriminant `type` field, so callers that already chunked keys
+ * (relation traversal) and the planner-driven read path share one entry point.
+ */
+interface BatchGetExecInput {
+    tableName: string;
+    keys: Record<string, unknown>[];
+    projectionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    consistentRead?: boolean;
+}
+/** A single item in a {@link Executor.batchWrite} request, grouped by table. */
+type BatchWriteExecItem = {
+    type: 'put';
+    item: Record<string, unknown>;
+} | {
+    type: 'delete';
+    key: Record<string, unknown>;
+};
+/**
+ * A read-only `ConditionCheck` entry for {@link Executor.transactWrite} (issue
+ * #81): it asserts a `ConditionExpression` holds for the keyed item without
+ * mutating it. A failed assertion cancels the **whole** `TransactWriteItems`
+ * atomically — the foundation for referential-integrity derivation.
+ */
+interface ConditionCheckInput {
+    TableName: string;
+    Key: Record<string, unknown>;
+    ConditionExpression: string;
+    ExpressionAttributeNames?: Record<string, string>;
+    ExpressionAttributeValues?: Record<string, unknown>;
+}
+/**
+ * A `{ Put | Update | Delete | ConditionCheck }` entry for
+ * {@link Executor.transactWrite}. The first three mutate an item; `ConditionCheck`
+ * (issue #81) is a read-only assertion on another item.
+ */
+type TransactWriteExecItem = {
+    Put: PutInput;
+} | {
+    Update: UpdateInput;
+} | {
+    Delete: DeleteInput;
+} | {
+    ConditionCheck: ConditionCheckInput;
+};
+/**
+ * The unified I/O seam (issue #76). All of GraphDDB's read and write I/O is
+ * funneled through one injectable executor so the engine (planner / hydrator /
+ * relation traversal / write paths) can run unchanged against either real
+ * DynamoDB ({@link DynamoExecutor}, the default) or an in-process memory store
+ * (`MemoryExecutor`, the test adapter).
+ *
+ * Reads take a structured {@link DynamoDBOperation}; writes take the structured
+ * inputs the operation layer already builds (`PutInput` / `UpdateInput` / …),
+ * never an AWS SDK command. This keeps the seam at the *structured operation
+ * boundary* (proposal option B): no expression-string parsing is required to
+ * implement a fake.
+ */
+interface Executor {
+    /**
+     * Read path: GetItem / Query / BatchGetItem. The optional {@link ReadExecOptions}
+     * carries a per-call retry override (issue #111); the default
+     * {@link DynamoExecutor} and `MemoryExecutor` ignore it, only `RetryingExecutor`
+     * acts on it.
+     */
+    execute(operation: DynamoDBOperation, options?: ReadExecOptions): Promise<ExecutorResult>;
+    /**
+     * BatchGetItem for a single table. The caller is responsible for chunking
+     * keys ≤100 (the relation traversal and the planner-driven path both do).
+     */
+    batchGet(input: BatchGetExecInput, options?: ReadExecOptions): Promise<ExecutorResult>;
+    /** Put one item. */
+    put(input: PutInput, options?: WriteExecOptions): Promise<WriteResult>;
+    /** Update one item (applies its structured UpdateExpression). */
+    update(input: UpdateInput, options?: WriteExecOptions): Promise<WriteResult>;
+    /** Delete one item. */
+    delete(input: DeleteInput, options?: WriteExecOptions): Promise<WriteResult>;
+    /**
+     * BatchWriteItem for a single table (non-atomic). Keys/items are chunked ≤25
+     * with UnprocessedItems retry by the implementation.
+     */
+    batchWrite(tableName: string, items: BatchWriteExecItem[], options?: BatchExecOptions): Promise<void>;
+    /** TransactWriteItems — all-or-nothing atomic. */
+    transactWrite(items: TransactWriteExecItem[], options?: BatchExecOptions): Promise<void>;
+}
+
+/**
+ * Write middleware / hook public surface (issue #50 write path, #139). The merged
+ * design is `docs/proposals/read-middleware.md`; this module implements the
+ * **write** hook points W1–W5 and their context objects, layered on the SAME
+ * 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
+ * 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
+ * hook may observe, mutate `ctx`, `throw` to cancel, or (on `onError`) recover by
+ * returning a value. The library does NOT validate hook logic or impose semantics
+ * (proposal appendix A). The internal CDC / capture mechanism (`src/capture/`,
+ * `src/cdc/`) is a SEPARATE surface — write hooks are not a substitute for it nor
+ * it for them (proposal appendix C).
+ *
+ * @see docs/proposals/read-middleware.md (hook points W1–W5)
+ */
+
+/**
+ * The logical write kinds a {@link WriteCtx} may carry (W1 / W2 / W5). A W1 hook
+ * may REWRITE this in place — the canonical case is a `delete` → `update`
+ * (soft-delete-by-rewrite); derivation then runs on the rewritten op, so the
+ * stored effect is the update, not the delete (proposal W1 + examples).
+ */
+type WriteKind = 'put' | 'update' | 'delete';
+/**
+ * The mutable logical write input a W1 hook observes / mutates. This is the
+ * declarative write payload — NOT a serialized spec — at the granularity the
+ * logical op carries:
+ *
+ * - `put`    — the full `item` is in {@link WriteInput.item};
+ * - `update` — the target `key` (entity) is in {@link WriteInput.key} and the
+ *   field `changes` in {@link WriteInput.changes};
+ * - `delete` — the target `key` is in {@link WriteInput.key}.
+ *
+ * A W1 hook may mutate these in place (e.g. inject `updatedBy`), and may rewrite
+ * `ctx.kind` together with these fields (a `delete` → `update` sets `changes`).
+ * Keeping `input` and `kind` consistent is the host's responsibility (appendix A).
+ */
+interface WriteInput {
+    /** The item written by a `put` (its key fields appear here). Mutable in W1. */
+    item?: Record<string, unknown>;
+    /** The target entity / key of an `update` / `delete`. Mutable in W1. */
+    key?: Record<string, unknown>;
+    /** The field changes of an `update`. Mutable in W1 (and when rewriting delete→update). */
+    changes?: Record<string, unknown>;
+    /** The per-call write options (`condition` / `retry` / `rederive` / …). Mutable in W1. */
+    options?: Record<string, unknown>;
+}
+/**
+ * W1 / W2 / W5 (logical-write-level) context. `before` (W1) may mutate
+ * {@link WriteCtx.input} and {@link WriteCtx.kind} (incl. the delete→update
+ * rewrite) and may `throw` to cancel the write (in a transaction, aborting ALL
+ * ops); `after` (W2) observes the committed change `{ oldImage?, newImage? }`;
+ * `onError` (W5) sees the logical-level failure and may recover by returning a
+ * value (symmetric with the read `onError`).
+ */
+interface WriteCtx extends CtxBase {
+    /** The logical write kind. Mutable in W1 (incl. delete→update rewrite). */
+    kind: WriteKind;
+    /** The mutable logical write payload (W1). */
+    input: WriteInput;
+    /**
+     * Present when this logical write is part of an atomic transaction
+     * (`DDBModel.transaction` / `mutate({ mode: 'transaction' })`). Its `id` symbol
+     * is shared by every logical op in the same atomic batch, so a hook can
+     * correlate the W1/W2 ops that compose one transaction. Absent for a
+     * non-transactional single-op write (and for `parallel`-mode ops, which are
+     * independent).
+     */
+    readonly transaction?: {
+        readonly id: symbol;
+    };
+}
+/**
+ * The committed change handed to a W2 (`write.after`) hook. A
+ * `TransactWriteItems` returns no item images (spec §14), so within a transaction
+ * the images are best-effort (often absent); a single-op write may carry the
+ * pre-write `oldImage` when one was fetched.
+ */
+interface Change {
+    readonly oldImage?: Record<string, unknown>;
+    readonly newImage?: Record<string, unknown>;
+}
+/** One origin entry describing a logical op that contributed to a persist batch. */
+interface PersistOrigin {
+    readonly model: CtxModel;
+    readonly kind: WriteKind;
+}
+/**
+ * W3 / W4 / W5 (physical-persist-level) context — fires AFTER derivation, on the
+ * REAL composed batch. `before` (W3) may mutate {@link PersistCtx.items} (the
+ * fully composed `Put` / `Update` / `Delete` / `ConditionCheck` set: the user
+ * write(s) PLUS every derived edge / counter / GSI re-derivation / referential
+ * ConditionCheck) and may `throw` to abort the batch — mutations are honored on
+ * the ACTUAL send. `after` (W4) observes the executor's results; `onError` (W5)
+ * sees the persist-level failure and may recover by returning a value.
+ *
+ * In a transaction the persist hooks fire ONCE for the whole atomic batch; for a
+ * non-transactional single-op write `items` is the one-element `[{ Put|Update|Delete }]`.
+ */
+interface PersistCtx {
+    /** The fully composed physical batch (user + derived). Mutable in W3. */
+    items: TransactWriteExecItem[];
+    /** The logical ops that composed this batch (one per contributing W-level op). */
+    readonly origins: readonly PersistOrigin[];
+    /** The host-injected per-call context (`{}` when the write passed none). */
+    readonly context: RequestContext;
+    /** Scratch shared across this persist op's W3 → W4 → W5 phases. */
+    readonly state: Record<string, unknown>;
+    /** Present (with the shared `id`) when this batch is an atomic transaction. */
+    readonly transaction?: {
+        readonly id: symbol;
+    };
+}
+/**
+ * The write half of a registered {@link import('./types.js').Middleware}. Any
+ * subset of the write hook points may be set; an unset hook is skipped. All hooks
+ * are async-first — the runtime always `await`s, so sync and async hooks compose
+ * uniformly (proposal "sync / async").
+ *
+ * @see docs/proposals/read-middleware.md (hook points W1–W5)
+ */
+interface WriteMiddleware {
+    /** W1 — logical write, before effect derivation. May mutate `ctx.input` / `ctx.kind`; `throw` cancels (in a tx, aborts all). */
+    before?(ctx: WriteCtx): void | Promise<void>;
+    /** W2 — logical write, after commit. Observes the committed `{ oldImage?, newImage? }`. */
+    after?(ctx: WriteCtx, change: Change): void | Promise<void>;
+    persist?: {
+        /** W3 — physical persist, after derivation, on the real batch. May mutate `ctx.items`; `throw` aborts the batch. */
+        before?(ctx: PersistCtx): void | Promise<void>;
+        /** W4 — physical persist, after the executor returns. Observes `results`. */
+        after?(ctx: PersistCtx, results: unknown): void | Promise<void>;
+        /**
+         * W5 (persist-level) — the persist failed. Runs LIFO. **Recover** by RETURNING
+         * a non-`undefined` value: the persist is treated as succeeded and the value is
+         * available to W4 (the first hook that returns a value wins and short-circuits
+         * the chain). Return `void` / `undefined` to decline — if no hook recovers, the
+         * original error rethrows (symmetric with the read `op.onError`).
+         */
+        onError?(ctx: PersistCtx, err: unknown): unknown;
+    };
+    /**
+     * W5 (logical-level) — the logical write failed. Runs LIFO. **Recover** by
+     * RETURNING a non-`undefined` value: it becomes the write's resolved value in
+     * place of throwing (the first hook that returns a value wins). Return `void` /
+     * `undefined` to decline — if no hook recovers, the original error rethrows
+     * (symmetric with the read `onError`).
+     */
+    onError?(ctx: WriteCtx, err: unknown): unknown;
+}
+
+/**
+ * Read middleware / hook public surface (issue #50, implemented for the read
+ * path in #138). The merged design is `docs/proposals/read-middleware.md`; this
+ * 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
+ * **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
+ * **unrestricted by intent**: a hook may observe, mutate `ctx`, `throw` to
+ * cancel, or return a replacement value. The library does NOT validate hook
+ * logic or impose semantics — see the proposal appendix A.
+ *
+ * @see docs/proposals/read-middleware.md
+ */
+
+/** A raw DynamoDB item (the shape R3 sees, per-op). */
+type Item = Record<string, unknown>;
+/**
+ * Host-injected, library-opaque per-call context — the value passed as
+ * `{ context }` on a read. Threaded unchanged to every R2/R3 fan-out op (issue
+ * #138). A read issued with no `{ context }` sees `{}`.
+ */
+type RequestContext = Record<string, unknown>;
+/**
+ * The `ModelStatic` shape the library hands to a hook's `ctx.model`. The
+ * concrete entity type is erased at the hook boundary (a hook is registered
+ * globally and may see any model), so it is the permissive
+ * `ModelStatic<DDBModel>`.
+ */
+type CtxModel = ModelStatic<DDBModel>;
+/** Fields shared by every read context object. */
+interface CtxBase {
+    /** The model the read targets. */
+    readonly model: CtxModel;
+    /** The host-injected per-call context (`{}` when the read passed none). */
+    readonly context: RequestContext;
+    /**
+     * Scratch space shared across this op's phases (R2 → R3 → R5 for one op, or
+     * R1 → R4 → R5 for the request). A fresh object per request context object;
+     * each fan-out op gets its own `state` (see proposal appendix D — siblings run
+     * concurrently, so a shared accumulator should live on a host object via
+     * `context`, updated commutatively).
+     */
+    readonly state: Record<string, unknown>;
+}
+/**
+ * The logical read kinds an {@link ReadRequestCtx} may carry (R1 / R4 / R5).
+ *
+ * Only the kinds the runtime actually emits are advertised. A `query` route in
+ * the read envelope delegates to {@link import('../operations/query.js').executeQuery}
+ * (kind `'query'`), a `list` route to {@link import('../operations/list.js').executeList}
+ * (kind `'list'`), so there is no distinct `'envelopeRoute'` kind. `batchGet`
+ * (`DDBModel.batchGet`, the public multi-key read primitive) fires request-level
+ * hooks since issue #142 — its R1/R4/R5 carry kind `'batchGet'`; each underlying
+ * physical `BatchGetItem` op fires R2/R3/R5 with op kind `'BatchGetItem'`.
+ */
+type ReadRequestKind = 'query' | 'list' | 'batchGet';
+/**
+ * The mutable request-level parameters R1 may observe / mutate. This is the
+ * declarative read input — `key` / `select` / and per-call read options — NOT a
+ * serialized spec. A hook may mutate these in place before key-resolution /
+ * planning (R1).
+ *
+ * For a `batchGet` read (kind `'batchGet'`, issue #142) there is no single
+ * `key` / `select` — the read spans multiple models/keys — so `key` / `select`
+ * are empty placeholders and the mutable batch input lives on
+ * {@link ReadParams.requests}; the library re-reads `requests` after R1 runs.
+ */
+interface ReadParams {
+    /** The key input (PK / GSI fields). Mutable in R1. Empty `{}` for `batchGet`. */
+    key: Record<string, unknown>;
+    /** The select / projection spec (plain object or a `project(...)` builder). Mutable in R1. Empty `{}` for `batchGet`. */
+    select: Record<string, unknown>;
+    /**
+     * The per-call read options (`consistentRead` / `maxDepth` / `limit` /
+     * `after` / `order` / `filter` / `updatable` / …) for this read kind. Mutable
+     * in R1. The library re-reads these after R1 runs.
+     */
+    options: Record<string, unknown>;
+    /**
+     * Only for a `batchGet` read (issue #142): the mutable list of batch-get
+     * requests (each `{ model, keys }`). A hook may add / drop / mutate requests
+     * or their keys in place before the underlying `BatchGetItem` ops are issued;
+     * the library re-reads this after R1 runs. `undefined` for `query` / `list`.
+     */
+    requests?: unknown[];
+}
+/**
+ * R1 / R4 / R5 (request-level) context. `before` (R1) may mutate
+ * {@link ReadParams} and may `throw` to cancel the whole read; `afterFetch` (R4)
+ * receives the final hydrated, relation-merged result and may return a
+ * replacement; `onError` (R5) sees a request-level failure.
+ */
+interface ReadRequestCtx extends CtxBase {
+    readonly kind: ReadRequestKind;
+    /** Mutable in R1 (request entry, before key-resolution / plan). */
+    params: ReadParams;
+}
+/** The physical op kinds an {@link ReadOpCtx} may carry (R2 / R3 / R5). */
+type ReadOpKind = 'GetItem' | 'Query' | 'BatchGetItem';
+/**
+ * R2 / R3 / R5 (op-level) context — fires for the root read AND for every
+ * relation fan-out fetch (incl. nested recursion). `before` (R2) may mutate
+ * {@link ReadOpCtx.operation} before it is sent and may `throw` to cancel;
+ * `afterFetch` (R3) receives the op's raw items and may return a replacement
+ * array; `onError` (R5) sees the op-level failure.
+ */
+interface ReadOpCtx extends CtxBase {
+    readonly kind: ReadOpKind;
+    /** The physical operation about to be sent. Mutable in R2. */
+    operation: DynamoDBOperation;
+    /**
+     * The relation path from the root read to this op: `[]` for the root read,
+     * `['orders']` for a direct relation fetch, `['orders', 'product']` for a
+     * nested one. Lets a hook scope behavior to a specific fan-out leg.
+     */
+    readonly relationPath: readonly string[];
+}
+/**
+ * A registered read middleware object. Any subset of the read hook points may
+ * be set; an unset hook is simply skipped. All hooks may be synchronous or
+ * return a `Promise` — the runtime always `await`s (async-first, see proposal
+ * "sync / async").
+ *
+ * @see docs/proposals/read-middleware.md (the write hooks W1–W5 are a later phase)
+ */
+interface Middleware {
+    /** Optional name (for host-side debugging / ordering introspection). */
+    name?: string;
+    read?: {
+        /** R1 — request entry, before key-resolution / plan. May mutate `ctx.params`; `throw` cancels. */
+        before?(ctx: ReadRequestCtx): void | Promise<void>;
+        /** R4 — final hydrated, relation-merged result. Returns the (possibly replaced) result. */
+        afterFetch?<T>(ctx: ReadRequestCtx, result: T): T | Promise<T>;
+        op?: {
+            /** R2 — each physical op, before send. May mutate `ctx.operation`; `throw` cancels. */
+            before?(ctx: ReadOpCtx): void | Promise<void>;
+            /** R3 — each physical op's raw items. Returns the (possibly replaced) items. */
+            afterFetch?(ctx: ReadOpCtx, items: Item[]): Item[] | Promise<Item[]>;
+            /**
+             * R5 (op-level) — a physical op failed. Runs LIFO. **Recover** by RETURNING
+             * an `Item[]`: those become this op's items and the read pipeline continues
+             * (the first hook that returns a value wins and short-circuits the chain).
+             * Return `void` / `undefined` to decline — if no hook recovers, the original
+             * error rethrows. (See proposal R5 + appendix A — hooks are unrestricted.)
+             */
+            onError?(ctx: ReadOpCtx, err: unknown): void | Item[] | Promise<void | Item[]>;
+        };
+        /**
+         * R5 (request-level) — the read failed. Runs LIFO. **Recover** by RETURNING a
+         * value: it becomes the read's result in place of throwing (the first hook
+         * that returns a non-`undefined` value wins and short-circuits the chain).
+         * Return `void` / `undefined` to decline — if no hook recovers, the original
+         * error rethrows. The returned value is the read's resolved value verbatim, so
+         * its shape is the host's responsibility (e.g. `null` / an item for `query`, a
+         * `{ items, cursor }` for `list`).
+         */
+        onError?(ctx: ReadRequestCtx, err: unknown): unknown;
+    };
+    /**
+     * The write hook points W1–W5 (issue #50 write path, #139). Any subset may be
+     * set; one registered object may carry read and/or write hooks. See
+     * {@link WriteMiddleware}.
+     */
+    write?: WriteMiddleware;
+}
+
 /**
  * A top-level `select` may be either a plain projection (`SelectableOf<T>`) or
  * a {@link SelectBuilder} produced by `Model.project(...)`. The builder is
@@ -847,6 +1393,13 @@ type ListCallOptions<T> = {
      * `& Updatable`, so it can be passed straight back to `updateItem()`.
      */
     updatable?: boolean;
+    /**
+     * Host-injected per-call read context (issue #50 / #138) — passed to every
+     * registered read hook as `ctx.context` and threaded to every relation
+     * fan-out op. A host-language value, never serialized (the bridge #48 is
+     * unaffected). Absent ⇒ `{}`.
+     */
+    context?: RequestContext;
 };
 /**
  * Public, type-inferring API surface produced by {@link DDBModel.asModel}.
@@ -914,6 +1467,8 @@ interface ModelStatic<T extends DDBModel, C = unknown> {
         maxDepth?: number;
         updatable?: boolean;
         hydrate: (raw: QueryResult<T, ProjectionOf<T, Sel>>) => R;
+        /** Host-injected per-call read context (issue #50 / #138); see {@link ListCallOptions.context}. */
+        context?: RequestContext;
     }): Promise<R | null>;
     /**
      * Fetch a single item by a unique key, requesting an **updatable** result.
@@ -927,6 +1482,8 @@ interface ModelStatic<T extends DDBModel, C = unknown> {
         consistentRead?: boolean;
         maxDepth?: number;
         updatable: true;
+        /** Host-injected per-call read context (issue #50 / #138); see {@link ListCallOptions.context}. */
+        context?: RequestContext;
     }): Promise<(QueryResult<T, ProjectionOf<T, Sel>> & Updatable) | null>;
     /**
      * Fetch a single item by a unique key. The return type contains only the
@@ -936,6 +1493,8 @@ interface ModelStatic<T extends DDBModel, C = unknown> {
         consistentRead?: boolean;
         maxDepth?: number;
         updatable?: false;
+        /** Host-injected per-call read context (issue #50 / #138); see {@link ListCallOptions.context}. */
+        context?: RequestContext;
     }): Promise<QueryResult<T, ProjectionOf<T, Sel>> | null>;
     /**
      * List items for a partition, symmetric with {@link ModelStatic.query}:
@@ -985,213 +1544,6 @@ interface ModelStatic<T extends DDBModel, C = unknown> {
     deleteItem(key: DeleteKey<C>, options?: WriteOptions<T>): Promise<void>;
 }
 
-interface UpdateInput {
-    TableName: string;
-    Key: Record<string, unknown>;
-    UpdateExpression: string;
-    ExpressionAttributeNames: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
-    ConditionExpression?: string;
-}
-declare function buildUpdateInput(modelClass: Function, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): UpdateInput;
-declare function executeUpdate(modelClass: Function, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): Promise<void>;
-
-interface DeleteInput {
-    TableName: string;
-    Key: Record<string, unknown>;
-    ConditionExpression?: string;
-    ExpressionAttributeNames?: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
-}
-declare function buildDeleteInput(modelClass: Function, keyObj: Record<string, unknown>, options?: DeleteOptions): DeleteInput;
-declare function executeDelete(modelClass: Function, keyObj: Record<string, unknown>, options?: DeleteOptions): Promise<void>;
-
-/** Result of a read operation (GetItem / Query / BatchGetItem). */
-interface ExecutorResult {
-    items: Record<string, unknown>[];
-    lastEvaluatedKey?: Record<string, unknown>;
-}
-/**
- * Result of a single structured write. `oldItem` is the pre-write image,
- * present only when the caller requested it (`returnOldImage: true`, mapped to
- * DynamoDB `ReturnValues: ALL_OLD`) and an item existed before the write. The
- * write-capture seam (issue #72) reads it to derive INSERT vs MODIFY and the
- * REMOVE OldImage.
- */
-interface WriteResult {
-    oldItem?: Record<string, unknown>;
-}
-/**
- * A per-call retry override threaded down to {@link RetryingExecutor} (issue
- * #111). `undefined` ⇒ use the globally-configured (or default) policy; a
- * {@link RetryPolicy} ⇒ use that for this call; `false` ⇒ disable retry for this
- * call. The default {@link DynamoExecutor} and the test `MemoryExecutor` ignore
- * it — only {@link RetryingExecutor} acts on it.
- */
-type RetryOverride = RetryPolicy | false;
-/**
- * Per-call options for the READ path (issue #111). Carries the per-op retry
- * override down to {@link RetryingExecutor}. Extended (rather than passing the
- * override positionally) so future per-call read knobs have a home.
- */
-interface ReadExecOptions {
-    /** Per-call retry override; see {@link RetryOverride}. */
-    retry?: RetryOverride;
-}
-/** Options shared by the single-item structured write methods. */
-interface WriteExecOptions {
-    /** Request the pre-write image (DynamoDB `ReturnValues: ALL_OLD`). */
-    returnOldImage?: boolean;
-    /** Per-call retry override (issue #111); see {@link RetryOverride}. */
-    retry?: RetryOverride;
-}
-/** Per-call options for the batch / transact paths (issue #111). */
-interface BatchExecOptions {
-    /** Per-call retry override; see {@link RetryOverride}. */
-    retry?: RetryOverride;
-}
-/**
- * One BatchGetItem sub-request: a single physical table plus its keys and an
- * optional projection. Mirrors {@link import('../planner/types.js').BatchGetItemOperation}
- * without the discriminant `type` field, so callers that already chunked keys
- * (relation traversal) and the planner-driven read path share one entry point.
- */
-interface BatchGetExecInput {
-    tableName: string;
-    keys: Record<string, unknown>[];
-    projectionExpression?: string;
-    expressionAttributeNames?: Record<string, string>;
-    consistentRead?: boolean;
-}
-/** A single item in a {@link Executor.batchWrite} request, grouped by table. */
-type BatchWriteExecItem = {
-    type: 'put';
-    item: Record<string, unknown>;
-} | {
-    type: 'delete';
-    key: Record<string, unknown>;
-};
-/**
- * A read-only `ConditionCheck` entry for {@link Executor.transactWrite} (issue
- * #81): it asserts a `ConditionExpression` holds for the keyed item without
- * mutating it. A failed assertion cancels the **whole** `TransactWriteItems`
- * atomically — the foundation for referential-integrity derivation.
- */
-interface ConditionCheckInput {
-    TableName: string;
-    Key: Record<string, unknown>;
-    ConditionExpression: string;
-    ExpressionAttributeNames?: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
-}
-/**
- * A `{ Put | Update | Delete | ConditionCheck }` entry for
- * {@link Executor.transactWrite}. The first three mutate an item; `ConditionCheck`
- * (issue #81) is a read-only assertion on another item.
- */
-type TransactWriteExecItem = {
-    Put: PutInput;
-} | {
-    Update: UpdateInput;
-} | {
-    Delete: DeleteInput;
-} | {
-    ConditionCheck: ConditionCheckInput;
-};
-/**
- * The unified I/O seam (issue #76). All of GraphDDB's read and write I/O is
- * funneled through one injectable executor so the engine (planner / hydrator /
- * relation traversal / write paths) can run unchanged against either real
- * DynamoDB ({@link DynamoExecutor}, the default) or an in-process memory store
- * (`MemoryExecutor`, the test adapter).
- *
- * Reads take a structured {@link DynamoDBOperation}; writes take the structured
- * inputs the operation layer already builds (`PutInput` / `UpdateInput` / …),
- * never an AWS SDK command. This keeps the seam at the *structured operation
- * boundary* (proposal option B): no expression-string parsing is required to
- * implement a fake.
- */
-interface Executor {
-    /**
-     * Read path: GetItem / Query / BatchGetItem. The optional {@link ReadExecOptions}
-     * carries a per-call retry override (issue #111); the default
-     * {@link DynamoExecutor} and `MemoryExecutor` ignore it, only `RetryingExecutor`
-     * acts on it.
-     */
-    execute(operation: DynamoDBOperation, options?: ReadExecOptions): Promise<ExecutorResult>;
-    /**
-     * BatchGetItem for a single table. The caller is responsible for chunking
-     * keys ≤100 (the relation traversal and the planner-driven path both do).
-     */
-    batchGet(input: BatchGetExecInput, options?: ReadExecOptions): Promise<ExecutorResult>;
-    /** Put one item. */
-    put(input: PutInput, options?: WriteExecOptions): Promise<WriteResult>;
-    /** Update one item (applies its structured UpdateExpression). */
-    update(input: UpdateInput, options?: WriteExecOptions): Promise<WriteResult>;
-    /** Delete one item. */
-    delete(input: DeleteInput, options?: WriteExecOptions): Promise<WriteResult>;
-    /**
-     * BatchWriteItem for a single table (non-atomic). Keys/items are chunked ≤25
-     * with UnprocessedItems retry by the implementation.
-     */
-    batchWrite(tableName: string, items: BatchWriteExecItem[], options?: BatchExecOptions): Promise<void>;
-    /** TransactWriteItems — all-or-nothing atomic. */
-    transactWrite(items: TransactWriteExecItem[], options?: BatchExecOptions): Promise<void>;
-}
-
-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;
-}
-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';
-}
-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;
-}
-
-interface PutInput {
-    TableName: string;
-    Item: Record<string, unknown>;
-    ConditionExpression?: string;
-    ExpressionAttributeNames?: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
-}
-declare function buildPutInput(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): PutInput;
-declare function executePut(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): Promise<void>;
-
 type TransactWriteItemInput = {
     Put: PutInput;
 } | {
@@ -1218,9 +1570,32 @@ interface TransactCaptureMeta {
     };
     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;
@@ -1242,16 +1617,35 @@ declare class TransactionContext {
     }): 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>): Promise<void>;
+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>;
@@ -1270,7 +1664,23 @@ declare class BatchGetResult {
     constructor(groups: Map<Function, Record<string, unknown>[]>);
     get<T extends DDBModel>(model: ModelStatic<T>): Partial<T>[];
 }
-declare function executeBatchGet(requests: BatchGetRequest[]): Promise<BatchGetResult>;
+/**
+ * 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>;
 
 /**
@@ -4391,6 +4801,13 @@ interface ReadRouteOptions {
     readonly after?: string;
     readonly order?: 'ASC' | 'DESC';
     readonly filter?: Record<string, unknown>;
+    /**
+     * Host-injected per-call read context (issue #50 / #138). Threaded into the
+     * route's underlying read (`executeQuery` / `executeList`), so the read hooks
+     * R1–R5 fire for the route with this `ctx.context`. Each route runs
+     * independently, so its hooks see only its own context. Absent ⇒ `{}`.
+     */
+    readonly context?: RequestContext;
 }
 /** One read route: a `query` (point/unique) or a `list` (partition) descriptor. */
 interface ReadRouteDescriptor {
@@ -4447,6 +4864,13 @@ interface MutateOptions {
      * 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 = {
@@ -4548,7 +4972,33 @@ declare abstract class DDBModel {
      * for that call (`false` disables retry).
      */
     static setRetryPolicy(policy: RetryPolicy | null): void;
-    static transaction(fn: (tx: TransactionContext) => void | Promise<void>): Promise<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
@@ -4576,7 +5026,19 @@ declare abstract class DDBModel {
     static mutate<const E extends WriteEnvelope>(envelope: E, options: {
         mode: 'parallel';
     }): Promise<MutateParallelResult<E>>;
-    static batchGet(requests: BatchGetRequest[]): Promise<BatchGetResult>;
+    /**
+     * 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>;
 }
@@ -4820,4 +5282,4 @@ interface CdcEmulatorOptions {
 }
 type ShardId = string;
 
-export { type QuerySpec as $, type ParamDescriptor as A, type BatchGetExecInput as B, type ChangeEvent as C, type DynamoDBOperation as D, type Executor as E, type FaultSpec as F, type DefinitionMap as G, type WriteDefinitionOptions as H, type PartialQueryKeyOf as I, type StrictSelectSpec as J, type EntityInput as K, type UniqueQueryKeyOf as L, type ModelStatic as M, type EntityRef as N, type OperationDefinition as O, type PutInput as P, type ConditionInput as Q, type ReadExecOptions as R, type SelectableOf as S, type TransactWriteExecItem as T, type UpdateInput as U, type QueryModelContract as V, type WriteExecOptions as W, type QueryMethodSpec as X, type CommandModelContract as Y, type CommandMethodSpec as Z, type ContractSpec as _, type ExecutorResult as a, type FilterInput as a$, type CommandSpec as a0, type ContextSpec as a1, type OperationsDocument as a2, type AnyOperationDefinition as a3, type BridgeBundle as a4, type ConditionSpec as a5, type BatchDeleteRequest as a6, type BatchGetRequest as a7, BatchGetResult as a8, type BatchPutRequest as a9, type ContractFromRef as aA, type ContractInputArity as aB, type ContractItem as aC, type ContractKeyFieldRef as aD, type ContractKeyInput as aE, type ContractKeyRef as aF, type ContractKeySpec as aG, type ContractKind as aH, type ContractMethodOp as aI, type ContractParamRef as aJ, type ContractQueryParams as aK, type ContractResolution as aL, DEFAULT_MAX_ATTEMPTS as aM, DEFAULT_RETRY_POLICY as aN, type DeleteOptions as aO, type DeriveEffect as aP, type DerivedEdgeWrite as aQ, type DerivedUpdate as aR, type DescriptorBinding as aS, ENTITY_WRITES_MARKER as aT, type EdgeEffect as aU, type EffectPath as aV, type EmitEffect as aW, type EntityWritesDefinition as aX, type EntityWritesShape as aY, type ExecutableCommandContract as aZ, type ExecutableQueryContract as a_, type BatchResult as aa, type BatchWriteRequest as ab, CONTRACT_RANGE_FANOUT_CONCURRENCY as ac, type CdcMode as ad, type ChangeBatch as ae, type ChangeEventName as af, type ClockMode as ag, type Column as ah, type ColumnMap as ai, type CommandContractMethodSpec as aj, type CommandInputShape as ak, type CommandMethod as al, type CommandPlan as am, type CommandResolutionTarget as an, type CommandResultKind as ao, type CommandSelectShape as ap, type CompiledFragment as aq, type ComposeSpec as ar, type CondSlot as as, type ConditionCheckInput as at, type Connection as au, type ContractCallSignature as av, type ContractCardinality as aw, type ContractCommandParams as ax, type ContractCommandResult as ay, type ContractComposeNode as az, type WriteResult as b, type SegmentSpec as b$, type FilterSpec as b0, type FragmentInput as b1, type GsiDefinitionMarker as b2, type GsiOptions as b3, type IdempotencyEffect as b4, type InProcessWriteDescriptor as b5, type InputArity as b6, type KeyDefinitionMarker as b7, type KeySegment as b8, type KeySlot as b9, type OperationSpec as bA, type ParallelOpResult as bB, type ParamKind as bC, type ParamSpec as bD, type ParamStructure as bE, type PlannedCommandMethod as bF, type PutOptions as bG, type QueryContractMethodSpec as bH, type QueryEnvelopeResult as bI, type QueryKeyOf as bJ, type QueryMethod as bK, type QueryResult as bL, type RangeConditionSpec as bM, type ReadEnvelope as bN, type ReadOperationType as bO, type ReadRouteDescriptor as bP, type ReadRouteOptions as bQ, type ReadRouteResult as bR, type RecordedCompose as bS, type RelationBuilder as bT, type RelationSelect as bU, type RelationSpec as bV, type RequiresEffect as bW, type Resolution as bX, type RetryInfo as bY, type RetryOperationKind as bZ, SPEC_VERSION as b_, type KeyStructure as ba, type KeyedResult as bb, LIFECYCLE_CONTRACT_MARKER as bc, type LifecycleContract as bd, type LifecycleEffects as be, type LiteralParam as bf, type ManifestEntity as bg, type ManifestField as bh, type ManifestFieldType as bi, type ManifestGsi as bj, type ManifestKey as bk, type ManifestRelation as bl, type ManifestTable as bm, type ModelRef as bn, type MutateMode as bo, type MutateOptions as bp, type MutateParallelResult as bq, type MutateTransactionResult as br, type MutationBody as bs, type MutationDescriptorMap as bt, type MutationFragment as bu, type MutationInputProxy as bv, type MutationInputRef as bw, type MutationIntent as bx, type NumberParam as by, type OperationKind as bz, type DeleteInput as c, mintContractParamRef as c$, type SelectBuilder as c0, type SelectOf as c1, type StartingPosition as c2, type StreamViewType as c3, type StringParam as c4, TransactionContext as c5, type TransactionItemType as c6, type UniqueEffect as c7, type Updatable as c8, type UpdateOptions as c9, executeTransaction as cA, executeUpdate as cB, from as cC, getEntityWrites as cD, gsi as cE, isColumn as cF, isCommandModelContract as cG, isCommandPlan as cH, isContractComposeNode as cI, isContractFromRef as cJ, isContractKeyFieldRef as cK, isContractKeyRef as cL, isContractParamRef as cM, isEntityWritesDefinition as cN, isKeySegment as cO, isLifecycleContract as cP, isMutationFragment as cQ, isMutationInputRef as cR, isParam as cS, isPlannedCommandMethod as cT, isQueryModelContract as cU, isRetryableError as cV, isRetryableTransactionCancellation as cW, k as cX, key as cY, lifecyclePhaseForIntent as cZ, mintContractKeyFieldRef as c_, type WhenSpec as ca, type WriteDescriptor as cb, type WriteEnvelope as cc, type WriteLifecyclePhase as cd, type WriteOperationType as ce, type WriteRecorder as cf, type WriteResultProjection as cg, attachModelClass as ch, buildDeleteInput as ci, buildPutInput as cj, buildUpdateInput as ck, compileFragment as cl, compileMutationPlan as cm, compileSingleFragmentPlan as cn, cond as co, contractOfMethodSpec as cp, definePlan as cq, entityWrites as cr, executeBatchGet as cs, executeBatchWrite as ct, executeCommandMethod as cu, executeDelete as cv, executeKeyedBatchGet as cw, executePut as cx, executeQueryMethod as cy, executeRangeFanout as cz, type BatchWriteExecItem as d, mutation as d0, param as d1, publicCommandModel as d2, publicQueryModel as d3, query as d4, resolveLifecycle as d5, wholeKeysSentinel as d6, type BatchExecOptions as e, DDBModel as f, type PrimaryKeyOf as g, type RetryPolicy as h, type ExecutionPlanSpec as i, type SegmentedKey as j, type SelectBuilderSpec as k, type RawCondition as l, type TransactionSpec as m, type Manifest as n, type RetryOverride as o, type ExecutionPlan as p, type ResolvedKey as q, type CdcEmulatorOptions as r, type ChangeHandler as s, type Unsubscribe as t, type ConcurrentRecomputeRef as u, type EventLog as v, type ReplayOptions as w, type ShardId as x, type TransactionItemSpec as y, type Param as z };
+export { type EntityRef as $, type ConcurrentRecomputeRef as A, type BatchGetExecInput as B, type ChangeEvent as C, type DynamoDBOperation as D, type Executor as E, type FaultSpec as F, type EventLog as G, type ReplayOptions as H, type Item as I, type ShardId as J, type TransactionItemSpec as K, type Param as L, type ModelStatic as M, type ParamDescriptor as N, type DefinitionMap as O, type PutInput as P, type OperationDefinition as Q, type ReadExecOptions as R, type SelectableOf as S, type TransactWriteExecItem as T, type UpdateInput as U, type WriteDefinitionOptions as V, type WriteExecOptions as W, type PartialQueryKeyOf as X, type StrictSelectSpec as Y, type EntityInput as Z, type UniqueQueryKeyOf as _, type ExecutorResult as a, type DerivedUpdate as a$, type ConditionInput as a0, type QueryModelContract as a1, type QueryMethodSpec as a2, type CommandModelContract as a3, type CommandMethodSpec as a4, type ContractSpec as a5, type QuerySpec as a6, type CommandSpec as a7, type ContextSpec as a8, type OperationsDocument as a9, type ComposeSpec as aA, type CondSlot as aB, type ConditionCheckInput as aC, type Connection as aD, type ContractCallSignature as aE, type ContractCardinality as aF, type ContractCommandParams as aG, type ContractCommandResult as aH, type ContractComposeNode as aI, type ContractFromRef as aJ, type ContractInputArity as aK, type ContractItem as aL, type ContractKeyFieldRef as aM, type ContractKeyInput as aN, type ContractKeyRef as aO, type ContractKeySpec as aP, type ContractKind as aQ, type ContractMethodOp as aR, type ContractParamRef as aS, type ContractQueryParams as aT, type ContractResolution as aU, type CtxBase as aV, DEFAULT_MAX_ATTEMPTS as aW, DEFAULT_RETRY_POLICY as aX, type DeleteOptions as aY, type DeriveEffect as aZ, type DerivedEdgeWrite as a_, type AnyOperationDefinition as aa, type BridgeBundle as ab, type ConditionSpec as ac, type BatchDeleteRequest as ad, type BatchGetOptions as ae, type BatchGetRequest as af, BatchGetResult as ag, type BatchPutRequest as ah, type BatchResult as ai, type BatchWriteRequest as aj, CONTRACT_RANGE_FANOUT_CONCURRENCY as ak, type CdcMode as al, type Change as am, type ChangeBatch as an, type ChangeEventName as ao, type ClockMode as ap, type Column as aq, type ColumnMap as ar, type CommandContractMethodSpec as as, type CommandInputShape as at, type CommandMethod as au, type CommandPlan as av, type CommandResolutionTarget as aw, type CommandResultKind as ax, type CommandSelectShape as ay, type CompiledFragment as az, type WriteResult as b, type ReadOpKind as b$, type DescriptorBinding as b0, ENTITY_WRITES_MARKER as b1, type EdgeEffect as b2, type EffectPath as b3, type EmitEffect as b4, type EntityWritesDefinition as b5, type EntityWritesShape as b6, type ExecutableCommandContract as b7, type ExecutableQueryContract as b8, type FilterInput as b9, type MutateParallelResult as bA, type MutateTransactionResult as bB, type MutationBody as bC, type MutationDescriptorMap as bD, type MutationFragment as bE, type MutationInputProxy as bF, type MutationInputRef as bG, type MutationIntent as bH, type NumberParam as bI, type OperationKind as bJ, type OperationSpec as bK, type ParallelOpResult as bL, type ParamKind as bM, type ParamSpec as bN, type ParamStructure as bO, type PersistCtx as bP, type PersistOrigin as bQ, type PlannedCommandMethod as bR, type PutOptions as bS, type QueryContractMethodSpec as bT, type QueryEnvelopeResult as bU, type QueryKeyOf as bV, type QueryMethod as bW, type QueryResult as bX, type RangeConditionSpec as bY, type ReadEnvelope as bZ, type ReadOpCtx as b_, type FilterSpec as ba, type FragmentInput as bb, type GsiDefinitionMarker as bc, type GsiOptions as bd, type IdempotencyEffect as be, type InProcessWriteDescriptor as bf, type InputArity as bg, type KeyDefinitionMarker as bh, type KeySegment as bi, type KeySlot as bj, type KeyStructure as bk, type KeyedResult as bl, LIFECYCLE_CONTRACT_MARKER as bm, type LifecycleContract as bn, type LifecycleEffects as bo, type LiteralParam as bp, type ManifestEntity as bq, type ManifestField as br, type ManifestFieldType as bs, type ManifestGsi as bt, type ManifestKey as bu, type ManifestRelation as bv, type ManifestTable as bw, type ModelRef as bx, type MutateMode as by, type MutateOptions as bz, type DeleteInput as c, isContractFromRef as c$, type ReadOperationType as c0, type ReadRouteDescriptor as c1, type ReadRouteOptions as c2, type ReadRouteResult as c3, type RecordedCompose as c4, type RelationBuilder as c5, type RelationSelect as c6, type RelationSpec as c7, type RequiresEffect as c8, type Resolution as c9, buildDeleteInput as cA, buildPutInput as cB, buildUpdateInput as cC, compileFragment as cD, compileMutationPlan as cE, compileSingleFragmentPlan as cF, cond as cG, contractOfMethodSpec as cH, definePlan as cI, entityWrites as cJ, executeBatchGet as cK, executeBatchWrite as cL, executeCommandMethod as cM, executeDelete as cN, executeKeyedBatchGet as cO, executePut as cP, executeQueryMethod as cQ, executeRangeFanout as cR, executeTransaction as cS, executeUpdate as cT, from as cU, getEntityWrites as cV, gsi as cW, isColumn as cX, isCommandModelContract as cY, isCommandPlan as cZ, isContractComposeNode as c_, type RetryInfo as ca, type RetryOperationKind as cb, SPEC_VERSION as cc, type SegmentSpec as cd, type SelectBuilder as ce, type SelectOf as cf, type StartingPosition as cg, type StreamViewType as ch, type StringParam as ci, TransactionContext as cj, type TransactionItemType as ck, type UniqueEffect as cl, type Updatable as cm, type UpdateOptions as cn, type WhenSpec as co, type WriteCtx as cp, type WriteDescriptor as cq, type WriteEnvelope as cr, type WriteInput as cs, type WriteKind as ct, type WriteLifecyclePhase as cu, type WriteMiddleware as cv, type WriteOperationType as cw, type WriteRecorder as cx, type WriteResultProjection as cy, attachModelClass as cz, type BatchWriteExecItem as d, isContractKeyFieldRef as d0, isContractKeyRef as d1, isContractParamRef as d2, isEntityWritesDefinition as d3, isKeySegment as d4, isLifecycleContract as d5, isMutationFragment as d6, isMutationInputRef as d7, isParam as d8, isPlannedCommandMethod as d9, isQueryModelContract as da, isRetryableError as db, isRetryableTransactionCancellation as dc, k as dd, key as de, lifecyclePhaseForIntent as df, mintContractKeyFieldRef as dg, mintContractParamRef as dh, mutation as di, param as dj, publicCommandModel as dk, publicQueryModel as dl, query as dm, resolveLifecycle as dn, wholeKeysSentinel as dp, type BatchExecOptions as e, DDBModel as f, type PrimaryKeyOf as g, type RequestContext as h, type Middleware as i, type ReadRequestKind as j, type CtxModel as k, type ReadParams as l, type ReadRequestCtx as m, type RetryPolicy as n, type ExecutionPlanSpec as o, type SegmentedKey as p, type SelectBuilderSpec as q, type RawCondition as r, type TransactionSpec as s, type Manifest as t, type RetryOverride as u, type ExecutionPlan as v, type ResolvedKey as w, type CdcEmulatorOptions as x, type ChangeHandler as y, type Unsubscribe as z };