graphddb 0.2.3 → 0.2.5

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

@@ -1,5 +1,131 @@
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 
+/**
+ * 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;
@@ -652,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
@@ -721,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}.
@@ -788,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.
@@ -801,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
@@ -810,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}:
@@ -859,166 +1544,6 @@ interface ModelStatic<T extends DDBModel, C = unknown> {
     deleteItem(key: DeleteKey<C>, options?: WriteOptions<T>): Promise<void>;
 }
 
-interface PutOptions<T = unknown> {
-    condition?: WriteCondition<T>;
-}
-interface UpdateOptions<T = unknown> {
-    condition?: WriteCondition<T>;
-    /**
-     * 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>;
-}
-
-interface PutInput {
-    TableName: string;
-    Item: Record<string, unknown>;
-    ConditionExpression?: string;
-    ExpressionAttributeNames?: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
-}
-declare function buildPutInput(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): PutInput;
-declare function executePut(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): Promise<void>;
-
-interface UpdateInput {
-    TableName: string;
-    Key: Record<string, unknown>;
-    UpdateExpression: string;
-    ExpressionAttributeNames: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
-    ConditionExpression?: string;
-}
-declare function buildUpdateInput(modelClass: Function, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): UpdateInput;
-declare function executeUpdate(modelClass: Function, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): Promise<void>;
-
-interface DeleteInput {
-    TableName: string;
-    Key: Record<string, unknown>;
-    ConditionExpression?: string;
-    ExpressionAttributeNames?: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
-}
-declare function buildDeleteInput(modelClass: Function, keyObj: Record<string, unknown>, options?: DeleteOptions): DeleteInput;
-declare function executeDelete(modelClass: Function, keyObj: Record<string, unknown>, options?: DeleteOptions): Promise<void>;
-
-/** Result of a read operation (GetItem / Query / BatchGetItem). */
-interface ExecutorResult {
-    items: Record<string, unknown>[];
-    lastEvaluatedKey?: Record<string, unknown>;
-}
-/**
- * Result of a single structured write. `oldItem` is the pre-write image,
- * present only when the caller requested it (`returnOldImage: true`, mapped to
- * DynamoDB `ReturnValues: ALL_OLD`) and an item existed before the write. The
- * write-capture seam (issue #72) reads it to derive INSERT vs MODIFY and the
- * REMOVE OldImage.
- */
-interface WriteResult {
-    oldItem?: Record<string, unknown>;
-}
-/** Options shared by the single-item structured write methods. */
-interface WriteExecOptions {
-    /** Request the pre-write image (DynamoDB `ReturnValues: ALL_OLD`). */
-    returnOldImage?: boolean;
-}
-/**
- * One BatchGetItem sub-request: a single physical table plus its keys and an
- * optional projection. Mirrors {@link import('../planner/types.js').BatchGetItemOperation}
- * without the discriminant `type` field, so callers that already chunked keys
- * (relation traversal) and the planner-driven read path share one entry point.
- */
-interface BatchGetExecInput {
-    tableName: string;
-    keys: Record<string, unknown>[];
-    projectionExpression?: string;
-    expressionAttributeNames?: Record<string, string>;
-    consistentRead?: boolean;
-}
-/** A single item in a {@link Executor.batchWrite} request, grouped by table. */
-type BatchWriteExecItem = {
-    type: 'put';
-    item: Record<string, unknown>;
-} | {
-    type: 'delete';
-    key: Record<string, unknown>;
-};
-/**
- * A read-only `ConditionCheck` entry for {@link Executor.transactWrite} (issue
- * #81): it asserts a `ConditionExpression` holds for the keyed item without
- * mutating it. A failed assertion cancels the **whole** `TransactWriteItems`
- * atomically — the foundation for referential-integrity derivation.
- */
-interface ConditionCheckInput {
-    TableName: string;
-    Key: Record<string, unknown>;
-    ConditionExpression: string;
-    ExpressionAttributeNames?: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
-}
-/**
- * A `{ Put | Update | Delete | ConditionCheck }` entry for
- * {@link Executor.transactWrite}. The first three mutate an item; `ConditionCheck`
- * (issue #81) is a read-only assertion on another item.
- */
-type TransactWriteExecItem = {
-    Put: PutInput;
-} | {
-    Update: UpdateInput;
-} | {
-    Delete: DeleteInput;
-} | {
-    ConditionCheck: ConditionCheckInput;
-};
-/**
- * The unified I/O seam (issue #76). All of GraphDDB's read and write I/O is
- * funneled through one injectable executor so the engine (planner / hydrator /
- * relation traversal / write paths) can run unchanged against either real
- * DynamoDB ({@link DynamoExecutor}, the default) or an in-process memory store
- * (`MemoryExecutor`, the test adapter).
- *
- * Reads take a structured {@link DynamoDBOperation}; writes take the structured
- * inputs the operation layer already builds (`PutInput` / `UpdateInput` / …),
- * never an AWS SDK command. This keeps the seam at the *structured operation
- * boundary* (proposal option B): no expression-string parsing is required to
- * implement a fake.
- */
-interface Executor {
-    /** Read path: GetItem / Query / BatchGetItem. */
-    execute(operation: DynamoDBOperation): Promise<ExecutorResult>;
-    /**
-     * BatchGetItem for a single table. The caller is responsible for chunking
-     * keys ≤100 (the relation traversal and the planner-driven path both do).
-     */
-    batchGet(input: BatchGetExecInput): Promise<ExecutorResult>;
-    /** Put one item. */
-    put(input: PutInput, options?: WriteExecOptions): Promise<WriteResult>;
-    /** Update one item (applies its structured UpdateExpression). */
-    update(input: UpdateInput, options?: WriteExecOptions): Promise<WriteResult>;
-    /** Delete one item. */
-    delete(input: DeleteInput, options?: WriteExecOptions): Promise<WriteResult>;
-    /**
-     * BatchWriteItem for a single table (non-atomic). Keys/items are chunked ≤25
-     * with UnprocessedItems retry by the implementation.
-     */
-    batchWrite(tableName: string, items: BatchWriteExecItem[]): Promise<void>;
-    /** TransactWriteItems — all-or-nothing atomic. */
-    transactWrite(items: TransactWriteExecItem[]): Promise<void>;
-}
-
 type TransactWriteItemInput = {
     Put: PutInput;
 } | {
@@ -1045,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;
@@ -1069,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>;
@@ -1097,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>;
 
 /**
@@ -4218,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 {
@@ -4266,6 +4856,21 @@ 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 = {
@@ -4345,9 +4950,55 @@ type MutateParallelResult<E extends WriteEnvelope> = {
 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;
     static setTableMapping(mapping: Record<string, string>): void;
-    static transaction(fn: (tx: TransactionContext) => void | Promise<void>): Promise<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
@@ -4375,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>;
 }
@@ -4619,4 +5282,4 @@ interface CdcEmulatorOptions {
 }
 type ShardId = string;
 
-export { type AnyOperationDefinition as $, type StrictSelectSpec as A, type BatchGetExecInput as B, type ChangeEvent as C, type DynamoDBOperation as D, type Executor as E, type FaultSpec as F, type EntityInput as G, type UniqueQueryKeyOf as H, type EntityRef as I, type ConditionInput as J, type QueryMethodSpec as K, type CommandModelContract as L, type ModelStatic as M, type CommandMethodSpec as N, type OperationDefinition as O, type PutInput as P, type QueryModelContract as Q, type RawCondition as R, type SelectableOf as S, type TransactWriteExecItem as T, type UpdateInput as U, type ContractSpec as V, type WriteExecOptions as W, type QuerySpec as X, type CommandSpec as Y, type ContextSpec as Z, type OperationsDocument as _, type ExecutorResult as a, type InProcessWriteDescriptor as a$, type BridgeBundle as a0, type ConditionSpec as a1, type BatchDeleteRequest as a2, type BatchGetRequest as a3, BatchGetResult as a4, type BatchPutRequest as a5, type BatchResult as a6, type BatchWriteRequest as a7, CONTRACT_RANGE_FANOUT_CONCURRENCY as a8, type CdcMode as a9, type ContractKeyInput as aA, type ContractKeyRef as aB, type ContractKeySpec as aC, type ContractKind as aD, type ContractMethodOp as aE, type ContractParamRef as aF, type ContractQueryParams as aG, type ContractResolution as aH, type DeleteOptions as aI, type DeriveEffect as aJ, type DerivedEdgeWrite as aK, type DerivedUpdate as aL, type DescriptorBinding as aM, ENTITY_WRITES_MARKER as aN, type EdgeEffect as aO, type EffectPath as aP, type EmitEffect as aQ, type EntityWritesDefinition as aR, type EntityWritesShape as aS, type ExecutableCommandContract as aT, type ExecutableQueryContract as aU, type FilterInput as aV, type FilterSpec as aW, type FragmentInput as aX, type GsiDefinitionMarker as aY, type GsiOptions as aZ, type IdempotencyEffect as a_, type ChangeBatch as aa, type ChangeEventName as ab, type ClockMode as ac, type Column as ad, type ColumnMap as ae, type CommandContractMethodSpec as af, type CommandInputShape as ag, type CommandMethod as ah, type CommandPlan as ai, type CommandResolutionTarget as aj, type CommandResultKind as ak, type CommandSelectShape as al, type CompiledFragment as am, type ComposeSpec as an, type CondSlot as ao, type ConditionCheckInput as ap, type Connection as aq, type ContractCallSignature as ar, type ContractCardinality as as, type ContractCommandParams as at, type ContractCommandResult as au, type ContractComposeNode as av, type ContractFromRef as aw, type ContractInputArity as ax, type ContractItem as ay, type ContractKeyFieldRef as az, type WriteResult as b, type UniqueEffect as b$, type InputArity as b0, type KeyDefinitionMarker as b1, type KeySegment as b2, type KeySlot as b3, type KeyStructure as b4, type KeyedResult as b5, LIFECYCLE_CONTRACT_MARKER as b6, type LifecycleContract as b7, type LifecycleEffects as b8, type LiteralParam as b9, type PutOptions as bA, type QueryContractMethodSpec as bB, type QueryEnvelopeResult as bC, type QueryKeyOf as bD, type QueryMethod as bE, type QueryResult as bF, type RangeConditionSpec as bG, type ReadEnvelope as bH, type ReadOperationType as bI, type ReadRouteDescriptor as bJ, type ReadRouteOptions as bK, type ReadRouteResult as bL, type RecordedCompose as bM, type RelationBuilder as bN, type RelationSelect as bO, type RelationSpec as bP, type RequiresEffect as bQ, type Resolution as bR, SPEC_VERSION as bS, type SegmentSpec as bT, type SelectBuilder as bU, type SelectOf as bV, type StartingPosition as bW, type StreamViewType as bX, type StringParam as bY, TransactionContext as bZ, type TransactionItemType as b_, type ManifestEntity as ba, type ManifestField as bb, type ManifestFieldType as bc, type ManifestGsi as bd, type ManifestKey as be, type ManifestRelation as bf, type ManifestTable as bg, type ModelRef as bh, type MutateMode as bi, type MutateOptions as bj, type MutateParallelResult as bk, type MutateTransactionResult as bl, type MutationBody as bm, type MutationDescriptorMap as bn, type MutationFragment as bo, type MutationInputProxy as bp, type MutationInputRef as bq, type MutationIntent as br, type NumberParam as bs, type OperationKind as bt, type OperationSpec as bu, type ParallelOpResult as bv, type ParamKind as bw, type ParamSpec as bx, type ParamStructure as by, type PlannedCommandMethod as bz, type DeleteInput as c, type Updatable as c0, type UpdateOptions as c1, type WhenSpec as c2, type WriteDescriptor as c3, type WriteEnvelope as c4, type WriteLifecyclePhase as c5, type WriteOperationType as c6, type WriteRecorder as c7, type WriteResultProjection as c8, attachModelClass as c9, isContractComposeNode as cA, isContractFromRef as cB, isContractKeyFieldRef as cC, isContractKeyRef as cD, isContractParamRef as cE, isEntityWritesDefinition as cF, isKeySegment as cG, isLifecycleContract as cH, isMutationFragment as cI, isMutationInputRef as cJ, isParam as cK, isPlannedCommandMethod as cL, isQueryModelContract as cM, k as cN, key as cO, lifecyclePhaseForIntent as cP, mintContractKeyFieldRef as cQ, mintContractParamRef as cR, mutation as cS, param as cT, publicCommandModel as cU, publicQueryModel as cV, query as cW, resolveLifecycle as cX, wholeKeysSentinel as cY, buildDeleteInput as ca, buildPutInput as cb, buildUpdateInput as cc, compileFragment as cd, compileMutationPlan as ce, compileSingleFragmentPlan as cf, cond as cg, contractOfMethodSpec as ch, definePlan as ci, entityWrites as cj, executeBatchGet as ck, executeBatchWrite as cl, executeCommandMethod as cm, executeDelete as cn, executeKeyedBatchGet as co, executePut as cp, executeQueryMethod as cq, executeRangeFanout as cr, executeTransaction as cs, executeUpdate as ct, from as cu, getEntityWrites as cv, gsi as cw, isColumn as cx, isCommandModelContract as cy, isCommandPlan as cz, type BatchWriteExecItem as d, DDBModel as e, type PrimaryKeyOf as f, type ExecutionPlanSpec as g, type SegmentedKey as h, type SelectBuilderSpec as i, type TransactionSpec as j, type Manifest as k, type ExecutionPlan as l, type ResolvedKey as m, type CdcEmulatorOptions as n, type ChangeHandler as o, type Unsubscribe as p, type ConcurrentRecomputeRef as q, type EventLog as r, type ReplayOptions as s, type ShardId as t, type TransactionItemSpec as u, type Param as v, type ParamDescriptor as w, type DefinitionMap as x, type WriteDefinitionOptions as y, type PartialQueryKeyOf 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 };