graphddb 0.2.3 → 0.2.5

package/dist/cli.js

@@ -2,10 +2,10 @@
 import {
   buildBridgeBundle,
   normalizeSelectSpec
-} from "./chunk-NJEC76TX.js";
+} from "./chunk-SGYBE2OV.js";
 import {
   MetadataRegistry
-} from "./chunk-FWDJSGF3.js";
+} from "./chunk-4TYK3AV6.js";
 
 // src/cli.ts
 import { createRequire } from "module";

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SelectableOf, f as PrimaryKeyOf, E as Executor, g as ExecutionPlanSpec, h as SegmentedKey, i as SelectBuilderSpec, R as RawCondition, j as TransactionSpec, k as Manifest, l as ExecutionPlan, m as ResolvedKey, D as DynamoDBOperation, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, T as TransactWriteExecItem, n as CdcEmulatorOptions, o as ChangeHandler, p as Unsubscribe, F as FaultSpec, q as ConcurrentRecomputeRef, C as ChangeEvent, r as EventLog, s as ReplayOptions, t as ShardId, u as TransactionItemSpec, v as Param, w as ParamDescriptor, x as DefinitionMap, O as OperationDefinition, e as DDBModel, M as ModelStatic, y as WriteDefinitionOptions, z as PartialQueryKeyOf, A as StrictSelectSpec, G as EntityInput, H as UniqueQueryKeyOf, I as EntityRef, J as ConditionInput, Q as QueryModelContract, K as QueryMethodSpec, L as CommandModelContract, N as CommandMethodSpec, V as ContractSpec, X as QuerySpec, Y as CommandSpec, Z as ContextSpec, _ as OperationsDocument, $ as AnyOperationDefinition, a0 as BridgeBundle, a1 as ConditionSpec } from './types-SKxZQbQO.js';
-export { a2 as BatchDeleteRequest, a3 as BatchGetRequest, a4 as BatchGetResult, a5 as BatchPutRequest, a6 as BatchResult, a7 as BatchWriteRequest, a8 as CONTRACT_RANGE_FANOUT_CONCURRENCY, a9 as CdcMode, aa as ChangeBatch, ab as ChangeEventName, ac as ClockMode, ad as Column, ae as ColumnMap, af as CommandContractMethodSpec, ag as CommandInputShape, ah as CommandMethod, ai as CommandPlan, aj as CommandResolutionTarget, ak as CommandResultKind, al as CommandSelectShape, am as CompiledFragment, an as ComposeSpec, ao as CondSlot, ap as ConditionCheckInput, aq as Connection, ar as ContractCallSignature, as as ContractCardinality, at as ContractCommandParams, au as ContractCommandResult, av as ContractComposeNode, aw as ContractFromRef, ax as ContractInputArity, ay as ContractItem, az as ContractKeyFieldRef, aA as ContractKeyInput, aB as ContractKeyRef, aC as ContractKeySpec, aD as ContractKind, aE as ContractMethodOp, aF as ContractParamRef, aG as ContractQueryParams, aH as ContractResolution, aI as DeleteOptions, aJ as DeriveEffect, aK as DerivedEdgeWrite, aL as DerivedUpdate, aM as DescriptorBinding, aN as ENTITY_WRITES_MARKER, aO as EdgeEffect, aP as EffectPath, aQ as EmitEffect, aR as EntityWritesDefinition, aS as EntityWritesShape, aT as ExecutableCommandContract, aU as ExecutableQueryContract, aV as FilterInput, aW as FilterSpec, aX as FragmentInput, aY as GsiDefinitionMarker, aZ as GsiOptions, a_ as IdempotencyEffect, a$ as InProcessWriteDescriptor, b0 as InputArity, b1 as KeyDefinitionMarker, b2 as KeySegment, b3 as KeySlot, b4 as KeyStructure, b5 as KeyedResult, b6 as LIFECYCLE_CONTRACT_MARKER, b7 as LifecycleContract, b8 as LifecycleEffects, b9 as LiteralParam, ba as ManifestEntity, bb as ManifestField, bc as ManifestFieldType, bd as ManifestGsi, be as ManifestKey, bf as ManifestRelation, bg as ManifestTable, bh as ModelRef, bi as MutateMode, bj as MutateOptions, bk as MutateParallelResult, bl as MutateTransactionResult, bm as MutationBody, bn as MutationDescriptorMap, bo as MutationFragment, bp as MutationInputProxy, bq as MutationInputRef, br as MutationIntent, bs as NumberParam, bt as OperationKind, bu as OperationSpec, bv as ParallelOpResult, bw as ParamKind, bx as ParamSpec, by as ParamStructure, bz as PlannedCommandMethod, bA as PutOptions, bB as QueryContractMethodSpec, bC as QueryEnvelopeResult, bD as QueryKeyOf, bE as QueryMethod, bF as QueryResult, bG as RangeConditionSpec, bH as ReadEnvelope, bI as ReadOperationType, bJ as ReadRouteDescriptor, bK as ReadRouteOptions, bL as ReadRouteResult, bM as RecordedCompose, bN as RelationBuilder, bO as RelationSelect, bP as RelationSpec, bQ as RequiresEffect, bR as Resolution, bS as SPEC_VERSION, bT as SegmentSpec, bU as SelectBuilder, bV as SelectOf, bW as StartingPosition, bX as StreamViewType, bY as StringParam, bZ as TransactionContext, b_ as TransactionItemType, b$ as UniqueEffect, c0 as Updatable, c1 as UpdateOptions, c2 as WhenSpec, c3 as WriteDescriptor, c4 as WriteEnvelope, c5 as WriteLifecyclePhase, c6 as WriteOperationType, c7 as WriteRecorder, c8 as WriteResultProjection, c9 as attachModelClass, ca as buildDeleteInput, cb as buildPutInput, cc as buildUpdateInput, cd as compileFragment, ce as compileMutationPlan, cf as compileSingleFragmentPlan, cg as cond, ch as contractOfMethodSpec, ci as definePlan, cj as entityWrites, ck as executeBatchGet, cl as executeBatchWrite, cm as executeCommandMethod, cn as executeDelete, co as executeKeyedBatchGet, cp as executePut, cq as executeQueryMethod, cr as executeRangeFanout, cs as executeTransaction, ct as executeUpdate, cu as from, cv as getEntityWrites, cw as gsi, cx as isColumn, cy as isCommandModelContract, cz as isCommandPlan, cA as isContractComposeNode, cB as isContractFromRef, cC as isContractKeyFieldRef, cD as isContractKeyRef, cE as isContractParamRef, cF as isEntityWritesDefinition, cG as isKeySegment, cH as isLifecycleContract, cI as isMutationFragment, cJ as isMutationInputRef, cK as isParam, cL as isPlannedCommandMethod, cM as isQueryModelContract, cN as k, cO as key, cP as lifecyclePhaseForIntent, cQ as mintContractKeyFieldRef, cR as mintContractParamRef, cS as mutation, cT as param, cU as publicCommandModel, cV as publicQueryModel, cW as query, cX as resolveLifecycle, cY as wholeKeysSentinel } from './types-SKxZQbQO.js';
+import { S as SelectableOf, g as PrimaryKeyOf, h as RequestContext, i as Middleware, j as ReadRequestKind, k as CtxModel, l as ReadParams, m as ReadRequestCtx, D as DynamoDBOperation, I as Item, E as Executor, n as RetryPolicy, o as ExecutionPlanSpec, p as SegmentedKey, q as SelectBuilderSpec, r as RawCondition, s as TransactionSpec, t as Manifest, u as RetryOverride, v as ExecutionPlan, w as ResolvedKey, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, x as CdcEmulatorOptions, y as ChangeHandler, z as Unsubscribe, F as FaultSpec, A as ConcurrentRecomputeRef, C as ChangeEvent, G as EventLog, H as ReplayOptions, J as ShardId, K as TransactionItemSpec, L as Param, N as ParamDescriptor, O as DefinitionMap, Q as OperationDefinition, f as DDBModel, M as ModelStatic, V as WriteDefinitionOptions, X as PartialQueryKeyOf, Y as StrictSelectSpec, Z as EntityInput, _ as UniqueQueryKeyOf, $ as EntityRef, a0 as ConditionInput, a1 as QueryModelContract, a2 as QueryMethodSpec, a3 as CommandModelContract, a4 as CommandMethodSpec, a5 as ContractSpec, a6 as QuerySpec, a7 as CommandSpec, a8 as ContextSpec, a9 as OperationsDocument, aa as AnyOperationDefinition, ab as BridgeBundle, ac as ConditionSpec } from './types--tdHK3vi.js';
+export { ad as BatchDeleteRequest, ae as BatchGetOptions, af as BatchGetRequest, ag as BatchGetResult, ah as BatchPutRequest, ai as BatchResult, aj as BatchWriteRequest, ak as CONTRACT_RANGE_FANOUT_CONCURRENCY, al as CdcMode, am as Change, an as ChangeBatch, ao as ChangeEventName, ap as ClockMode, aq as Column, ar as ColumnMap, as as CommandContractMethodSpec, at as CommandInputShape, au as CommandMethod, av as CommandPlan, aw as CommandResolutionTarget, ax as CommandResultKind, ay as CommandSelectShape, az as CompiledFragment, aA as ComposeSpec, aB as CondSlot, aC as ConditionCheckInput, aD as Connection, aE as ContractCallSignature, aF as ContractCardinality, aG as ContractCommandParams, aH as ContractCommandResult, aI as ContractComposeNode, aJ as ContractFromRef, aK as ContractInputArity, aL as ContractItem, aM as ContractKeyFieldRef, aN as ContractKeyInput, aO as ContractKeyRef, aP as ContractKeySpec, aQ as ContractKind, aR as ContractMethodOp, aS as ContractParamRef, aT as ContractQueryParams, aU as ContractResolution, aV as CtxBase, aW as DEFAULT_MAX_ATTEMPTS, aX as DEFAULT_RETRY_POLICY, aY as DeleteOptions, aZ as DeriveEffect, a_ as DerivedEdgeWrite, a$ as DerivedUpdate, b0 as DescriptorBinding, b1 as ENTITY_WRITES_MARKER, b2 as EdgeEffect, b3 as EffectPath, b4 as EmitEffect, b5 as EntityWritesDefinition, b6 as EntityWritesShape, b7 as ExecutableCommandContract, b8 as ExecutableQueryContract, b9 as FilterInput, ba as FilterSpec, bb as FragmentInput, bc as GsiDefinitionMarker, bd as GsiOptions, be as IdempotencyEffect, bf as InProcessWriteDescriptor, bg as InputArity, bh as KeyDefinitionMarker, bi as KeySegment, bj as KeySlot, bk as KeyStructure, bl as KeyedResult, bm as LIFECYCLE_CONTRACT_MARKER, bn as LifecycleContract, bo as LifecycleEffects, bp as LiteralParam, bq as ManifestEntity, br as ManifestField, bs as ManifestFieldType, bt as ManifestGsi, bu as ManifestKey, bv as ManifestRelation, bw as ManifestTable, bx as ModelRef, by as MutateMode, bz as MutateOptions, bA as MutateParallelResult, bB as MutateTransactionResult, bC as MutationBody, bD as MutationDescriptorMap, bE as MutationFragment, bF as MutationInputProxy, bG as MutationInputRef, bH as MutationIntent, bI as NumberParam, bJ as OperationKind, bK as OperationSpec, bL as ParallelOpResult, bM as ParamKind, bN as ParamSpec, bO as ParamStructure, bP as PersistCtx, bQ as PersistOrigin, bR as PlannedCommandMethod, bS as PutOptions, bT as QueryContractMethodSpec, bU as QueryEnvelopeResult, bV as QueryKeyOf, bW as QueryMethod, bX as QueryResult, bY as RangeConditionSpec, bZ as ReadEnvelope, b_ as ReadOpCtx, b$ as ReadOpKind, c0 as ReadOperationType, c1 as ReadRouteDescriptor, c2 as ReadRouteOptions, c3 as ReadRouteResult, c4 as RecordedCompose, c5 as RelationBuilder, c6 as RelationSelect, c7 as RelationSpec, c8 as RequiresEffect, c9 as Resolution, ca as RetryInfo, cb as RetryOperationKind, cc as SPEC_VERSION, cd as SegmentSpec, ce as SelectBuilder, cf as SelectOf, cg as StartingPosition, ch as StreamViewType, ci as StringParam, cj as TransactionContext, ck as TransactionItemType, cl as UniqueEffect, cm as Updatable, cn as UpdateOptions, co as WhenSpec, cp as WriteCtx, cq as WriteDescriptor, cr as WriteEnvelope, cs as WriteInput, ct as WriteKind, cu as WriteLifecyclePhase, cv as WriteMiddleware, cw as WriteOperationType, cx as WriteRecorder, cy as WriteResultProjection, cz as attachModelClass, cA as buildDeleteInput, cB as buildPutInput, cC as buildUpdateInput, cD as compileFragment, cE as compileMutationPlan, cF as compileSingleFragmentPlan, cG as cond, cH as contractOfMethodSpec, cI as definePlan, cJ as entityWrites, cK as executeBatchGet, cL as executeBatchWrite, cM as executeCommandMethod, cN as executeDelete, cO as executeKeyedBatchGet, cP as executePut, cQ as executeQueryMethod, cR as executeRangeFanout, cS as executeTransaction, cT as executeUpdate, cU as from, cV as getEntityWrites, cW as gsi, cX as isColumn, cY as isCommandModelContract, cZ as isCommandPlan, c_ as isContractComposeNode, c$ as isContractFromRef, d0 as isContractKeyFieldRef, d1 as isContractKeyRef, d2 as isContractParamRef, d3 as isEntityWritesDefinition, d4 as isKeySegment, d5 as isLifecycleContract, d6 as isMutationFragment, d7 as isMutationInputRef, d8 as isParam, d9 as isPlannedCommandMethod, da as isQueryModelContract, db as isRetryableError, dc as isRetryableTransactionCancellation, dd as k, de as key, df as lifecyclePhaseForIntent, dg as mintContractKeyFieldRef, dh as mintContractParamRef, di as mutation, dj as param, dk as publicCommandModel, dl as publicQueryModel, dm as query, dn as resolveLifecycle, dp as wholeKeysSentinel } from './types--tdHK3vi.js';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 
@@ -32,6 +32,99 @@ type ListOptions<T, S extends SelectableOf<T> = SelectableOf<T>> = {
     order?: 'ASC' | 'DESC';
 };
 
+/**
+ * Read-middleware runtime (issue #138). Drives the registered {@link Middleware}
+ * list through the read hook points R1–R5 with the ordering the proposal
+ * specifies:
+ *
+ * - `before*` (R1 / R2) run **first-registered-first** (FIFO);
+ * - `afterFetch` (R3 / R4) and `onError` (R5) run **last-registered-first**
+ *   (LIFO) — onion nesting without a `next()` callback.
+ *
+ * All hooks are async-first: each is always `await`ed, so a sync hook (returns
+ * `void` / a value) and an async hook (returns a `Promise`) compose uniformly.
+ *
+ * A {@link MiddlewareRuntime} is constructed ONCE per read at the request entry
+ * (R1) from the snapshot of registered middleware + the per-call `context`, then
+ * threaded — unchanged — through the root read and every relation fan-out op
+ * (the same way `retry` is threaded, see `RelationTraversalOptions`). Threading
+ * an immutable runtime (not re-reading the registry per op) keeps a read's hook
+ * set stable even if middleware is (un)registered mid-flight, and is
+ * concurrency-safe under parallel fan-out (#31).
+ *
+ * @see docs/proposals/read-middleware.md
+ */
+
+/**
+ * The per-read middleware runtime. Immutable wrt the middleware list and the
+ * request `context`; threaded by reference into every fan-out op. A read with no
+ * registered middleware is represented by an EMPTY runtime whose `active` is
+ * `false`, so the hot read path can skip all hook plumbing with one check.
+ */
+declare class MiddlewareRuntime {
+    /** The frozen, registration-ordered middleware snapshot for this read. */
+    private readonly chain;
+    /** The host-injected per-call context (`{}` when the read passed none). */
+    readonly context: RequestContext;
+    constructor(chain: readonly Middleware[], context: RequestContext);
+    /** `true` when at least one middleware is registered for this read. */
+    get active(): boolean;
+    /**
+     * Build the request-level context (R1 / R4 / R5 share it). Pure — no hooks run
+     * — so a caller can create it up front and still reference it from R5 even if
+     * R1 throws mid-chain.
+     */
+    requestCtx(kind: ReadRequestKind, model: CtxModel, params: ReadParams): ReadRequestCtx;
+    /**
+     * R1 — request entry, before key-resolution / plan. Builds the
+     * {@link ReadRequestCtx} then runs every `read.before` FIFO; a hook may mutate
+     * `ctx.params` and may `throw` to cancel the read. Returns the (possibly
+     * hook-mutated) ctx so the caller can re-read `params` and reuse the SAME ctx
+     * for R4 / R5 (shared `state`).
+     */
+    runRequestBefore(kind: ReadRequestKind, model: CtxModel, params: ReadParams): Promise<ReadRequestCtx>;
+    /**
+     * R4 — final hydrated, relation-merged result. Runs every `read.afterFetch`
+     * LIFO, threading each hook's return value into the next (onion), and returns
+     * the final (possibly replaced) result. `ctx` is the SAME object R1 produced,
+     * so a `before`/`afterFetch` pair shares `ctx.state`.
+     */
+    runRequestAfter<T>(ctx: ReadRequestCtx, result: T): Promise<T>;
+    /**
+     * R5 (request-level) — runs every `read.onError` LIFO. A hook may **recover**
+     * by RETURNING a non-`undefined` value: it becomes the read's resolved result
+     * in place of throwing, and the FIRST such hook (in LIFO order) wins and
+     * short-circuits the rest of the chain. If every hook declines (returns
+     * `undefined`/`void`), the original error rethrows — preserving the
+     * "failed read still rejects" default. (Proposal R5 + appendix A: onError may
+     * "rethrow / recover"; hooks are unrestricted.)
+     *
+     * The recovered value is returned as `T` (the read's result type); its shape
+     * is the host's responsibility — a hook recovering a `query` should return an
+     * item / `null`, one recovering a `list` a `{ items, cursor }`.
+     */
+    runRequestError<T>(ctx: ReadRequestCtx, err: unknown): Promise<T>;
+    /**
+     * Drive ONE physical op (root read or any fan-out fetch) through R2 → send →
+     * R3, with R5 (op-level) on failure:
+     *
+     * 1. R2 (`read.op.before`, FIFO) — may mutate `ctx.operation`, may `throw`;
+     * 2. the caller's `send` runs against the (possibly mutated) operation;
+     * 3. R3 (`read.op.afterFetch`, LIFO) — transforms the raw items (onion);
+     * 4. on any throw from `send` (or R2 / R3), R5 (`read.op.onError`, LIFO) runs:
+     *    a hook may **recover** by RETURNING an `Item[]` (those become this op's
+     *    items and the pipeline continues); the FIRST hook that returns items wins
+     *    and short-circuits the chain. If none recovers, the original error
+     *    rethrows.
+     *
+     * Returns the (possibly R3-replaced, or R5-recovered) items. The `send` closure
+     * receives the final operation so a caller that built its operation from
+     * `ctx.operation` before this call still observes an R2 mutation (the caller
+     * MUST send `ctx.operation`, which this method passes through).
+     */
+    runOp(operation: DynamoDBOperation, relationPath: readonly string[], model: CtxModel, send: (operation: DynamoDBOperation) => Promise<Item[]>): Promise<Item[]>;
+}
+
 /**
  * The ONE shared `TransactWriteItems` commit orchestration (issue #97).
  *
@@ -92,6 +185,22 @@ declare class ClientManager {
      */
     private static executor;
     private static defaultExecutor;
+    /**
+     * The globally-configured single-op retry policy (issue #111). `null` ⇒ the
+     * always-on built-in {@link DEFAULT_RETRY_POLICY} applies (retry is enabled out
+     * of the box). Set via {@link DDBModel.setRetryPolicy} / {@link setRetryPolicy};
+     * read at call time by the default {@link RetryingExecutor}.
+     */
+    private static retryPolicy;
+    /**
+     * The host-runtime read-middleware registry (issue #50 / #138) — a process-wide
+     * ordered list of {@link Middleware}, the same global-config + injectable-seam
+     * pattern as {@link retryPolicy} / {@link executor}. Registered via
+     * {@link DDBModel.use} / {@link use}, snapshotted per read, and NEVER serialized
+     * (it never touches the planner / spec / `operations.json`, so the bridge #48 is
+     * unaffected). {@link reset} clears it.
+     */
+    private static middleware;
     static setClient(client: DynamoDBClient): void;
     static getClient(): DynamoDBClient;
     static getDocumentClient(): Promise<DynamoDBDocumentClient>;
@@ -105,10 +214,38 @@ declare class ClientManager {
      * executor module graph.
      */
     static getExecutor(): Executor;
-    /** Inject a custom executor (test adapter / memory engine). */
+    /**
+     * Inject a custom executor (test adapter / memory engine). It is used AS-IS —
+     * not wrapped in a {@link RetryingExecutor} — so the in-memory adapter (which
+     * never throttles) bypasses the retry layer entirely (issue #111).
+     */
     static setExecutor(executor: Executor): void;
-    /** Restore the default {@link DynamoExecutor}. */
+    /** Restore the default {@link RetryingExecutor}-wrapped {@link DynamoExecutor}. */
     static resetExecutor(): void;
+    /**
+     * Configure the global single-op retry policy (issue #111). Mirrors
+     * {@link setClient} / {@link setTableMapping}: a process-wide setting the default
+     * {@link RetryingExecutor} reads. `null` restores the always-on built-in default.
+     * A per-call `retry?:` override on an operation option bag takes precedence.
+     */
+    static setRetryPolicy(policy: RetryPolicy | null): void;
+    /** The globally-configured retry policy, or `null` for the built-in default. */
+    static getRetryPolicy(): RetryPolicy | null;
+    /**
+     * Register a read {@link Middleware} (issue #50 / #138). Appended last, so its
+     * `before*` hooks run last (FIFO) and its `afterFetch` / `onError` hooks run
+     * first (LIFO). Mirrors {@link setRetryPolicy}; backs {@link DDBModel.use}.
+     */
+    static use(mw: Middleware): void;
+    /** Remove every registered read middleware (teardown / tests). Backs {@link DDBModel.clearMiddleware}. */
+    static clearMiddleware(): void;
+    /**
+     * A point-in-time, registration-ordered snapshot of the registered read
+     * middleware. A read takes this once at entry (R1) and threads it down, so the
+     * read's hook set stays stable even if middleware is registered / cleared
+     * mid-flight.
+     */
+    static getMiddleware(): readonly Middleware[];
     /** @internal — for testing only */
     static reset(): void;
 }
@@ -503,6 +640,13 @@ declare function executeDeclarativeTransaction(spec: TransactionSpec, manifest:
 interface QueryOptions {
     consistentRead?: boolean;
     maxDepth?: number;
+    /**
+     * Per-call throttle / transient-error retry override (issue #111), applied to the
+     * parent read AND to every relation-fan-out send under it. A {@link RetryPolicy}
+     * replaces the global policy for this call; `false` disables retry. Omit to use
+     * the configured (or built-in default) policy.
+     */
+    retry?: RetryOverride;
     /**
      * When `true`, the returned item carries its resolved base-table key as a
      * non-enumerable Symbol property so it can be passed back to `update()`
@@ -531,6 +675,14 @@ interface QueryOptions {
      * "What to fetch" stays declarative; "what object to load it onto" is host-side.
      */
     hydrate?: (raw: Record<string, unknown> | null) => unknown;
+    /**
+     * Host-injected per-call read context (issue #50 / #138) — exposed to every
+     * read hook (R1–R5) as `ctx.context`, and threaded UNCHANGED to every relation
+     * fan-out op so a hook (e.g. a tenant-scope R2 filter) applies across the root
+     * read AND the fan-out fetches. A host-language value, NEVER serialized into the
+     * SSoT / `operations.json` (the bridge #48 is unaffected). Absent ⇒ `{}`.
+     */
+    context?: RequestContext;
 }
 declare function executeQuery(modelClass: Function, key: Record<string, unknown>, selectSpec: Record<string, unknown>, options?: QueryOptions): Promise<Record<string, unknown> | null>;
 
@@ -547,6 +699,34 @@ interface ListInput {
      * query.
      */
     updatable?: boolean;
+    /**
+     * Per-call throttle / transient-error retry override (issue #111). A
+     * {@link RetryPolicy} replaces the global policy for this read; `false` disables
+     * retry. Omit to use the configured (or built-in default) policy.
+     */
+    retry?: RetryOverride;
+    /**
+     * Host-injected per-call read context (issue #50 / #138) — exposed to every
+     * read hook as `ctx.context`. Used only when this `list` is the read ENTRY
+     * point (the public `DDBModel.list` / a `list` envelope route): a fresh
+     * {@link MiddlewareRuntime} is built from it. Ignored when a relation fan-out
+     * threads an already-built {@link mw} (the runtime then carries the root read's
+     * context). Absent ⇒ `{}`.
+     */
+    context?: RequestContext;
+    /**
+     * @internal The per-read middleware runtime, threaded UNCHANGED from a relation
+     * fan-out (issue #138) so the hasMany Query's op-level hooks (R2/R3/R5) fire
+     * with the root read's context + the fan-out's {@link relationPath}. When absent
+     * at the entry point, one is built from {@link context}.
+     */
+    mw?: MiddlewareRuntime;
+    /**
+     * @internal The relation path to THIS list read — `[]` (or absent) for a
+     * top-level `list`; the fan-out leg (e.g. `['orders']`) for a hasMany Query.
+     * Populates the op-level ctx's `relationPath` (issue #138).
+     */
+    relationPath?: readonly string[];
 }
 /**
  * Public list result returned by `DDBModel.list()`. Contains exactly the
@@ -618,10 +798,12 @@ declare function plan(metadata: EntityMetadata, input: PlanInput): ExecutionPlan
  *
  * This is the read entry point the planner-driven paths (`query` / `list`) call.
  * It delegates to `ClientManager.getExecutor()`, which is the default
- * {@link import('./dynamo-executor.js').DynamoExecutor} unless a test has
- * injected a `MemoryExecutor` via `ClientManager.setExecutor()`.
+ * {@link import('./retrying-executor.js').RetryingExecutor}-wrapped
+ * {@link import('./dynamo-executor.js').DynamoExecutor} unless a test has injected
+ * a `MemoryExecutor` via `ClientManager.setExecutor()`. The optional
+ * {@link ReadExecOptions} carries a per-call retry override (issue #111).
  */
-declare function execute(operation: DynamoDBOperation): Promise<ExecutorResult>;
+declare function execute(operation: DynamoDBOperation, options?: ReadExecOptions): Promise<ExecutorResult>;
 
 /**
  * The default {@link Executor}: a thin, behavior-preserving move of GraphDDB's
@@ -630,15 +812,65 @@ declare function execute(operation: DynamoDBOperation): Promise<ExecutorResult>;
  * refactor and sends it through `ClientManager.getDocumentClient()`, so the
  * command shapes (and therefore every existing mock-based / integration test)
  * are unchanged.
+ *
+ * The optional per-call options (`ReadExecOptions` / `BatchExecOptions`) carry a
+ * retry override (issue #111) that is meaningful ONLY to {@link RetryingExecutor};
+ * here they are accepted to satisfy the {@link Executor} interface and otherwise
+ * ignored (this executor performs no app-level error retry of its own).
  */
 declare class DynamoExecutor implements Executor {
-    execute(operation: DynamoDBOperation): Promise<ExecutorResult>;
-    batchGet(input: BatchGetExecInput): Promise<ExecutorResult>;
+    execute(operation: DynamoDBOperation, _options?: ReadExecOptions): Promise<ExecutorResult>;
+    batchGet(input: BatchGetExecInput, _options?: ReadExecOptions): Promise<ExecutorResult>;
     put(input: PutInput, options?: WriteExecOptions): Promise<WriteResult>;
     update(input: UpdateInput, options?: WriteExecOptions): Promise<WriteResult>;
     delete(input: DeleteInput, options?: WriteExecOptions): Promise<WriteResult>;
-    batchWrite(tableName: string, items: BatchWriteExecItem[]): Promise<void>;
-    transactWrite(items: TransactWriteExecItem[]): Promise<void>;
+    batchWrite(tableName: string, items: BatchWriteExecItem[], _options?: BatchExecOptions): Promise<void>;
+    transactWrite(items: TransactWriteExecItem[], _options?: BatchExecOptions): Promise<void>;
+}
+
+/**
+ * {@link RetryingExecutor} — the single-op throttle / transient-error retry layer
+ * (issue #111). It DECORATES an inner {@link Executor} (the default
+ * {@link DynamoExecutor}), wrapping every single-op send — `execute` (Get/Query),
+ * `batchGet` (relation fan-out + planner reads), `put` / `update` / `delete`, and
+ * `transactWrite` — in {@link runWithRetry} so a throttle / transient error is
+ * retried with exponential backoff + jitter under a bounded attempt cap.
+ *
+ * This is the (B) ERROR-retry layer; the (A) partial-batch retry
+ * (`UnprocessedKeys` / `UnprocessedItems`) lives inside `batchGet` / `batchWrite`
+ * and is a SEPARATE concern (see `retry-policy.ts` header). The two share the
+ * backoff function but never merge:
+ *  - `batchGet` here gets an OUTER error-retry wrap (the inner BatchGet still does
+ *    its own UnprocessedKeys retry; the outer wrap catches a hard throttle REJECT
+ *    of the whole send).
+ *  - `batchWrite` is the in-flight bulk path that already owns UnprocessedItems
+ *    retry per chunk; it is passed through UNWRAPPED here to avoid double-counting
+ *    a throttle as both an unprocessed-item retry and an error retry. (Its chunks
+ *    already back off on the shared ramp.)
+ *
+ * The policy precedence per call: an explicit per-call override (`retry:` on the
+ * option bag) wins; otherwise the globally-configured policy
+ * (`DDBModel.setRetryPolicy`); otherwise the always-on {@link DEFAULT_RETRY_POLICY}.
+ * `retry: false`, or a resolved `maxAttempts <= 1`, disables retry for that call.
+ */
+
+declare class RetryingExecutor implements Executor {
+    private readonly inner;
+    private readonly getGlobalPolicy;
+    /**
+     * @param inner the wrapped executor (the real {@link DynamoExecutor}).
+     * @param getGlobalPolicy reads the globally-configured policy (or `null` for the
+     *   built-in default) at CALL time, so a `DDBModel.setRetryPolicy(...)` after the
+     *   executor is constructed still takes effect.
+     */
+    constructor(inner: Executor, getGlobalPolicy: () => RetryPolicy | null);
+    execute(operation: DynamoDBOperation, options?: ReadExecOptions): Promise<ExecutorResult>;
+    batchGet(input: BatchGetExecInput, options?: ReadExecOptions): Promise<ExecutorResult>;
+    put(input: PutInput, options?: WriteExecOptions): Promise<WriteResult>;
+    update(input: UpdateInput, options?: WriteExecOptions): Promise<WriteResult>;
+    delete(input: DeleteInput, options?: WriteExecOptions): Promise<WriteResult>;
+    batchWrite(tableName: string, items: BatchWriteExecItem[], options?: BatchExecOptions): Promise<void>;
+    transactWrite(items: TransactWriteExecItem[], options?: BatchExecOptions): Promise<void>;
 }
 
 /**
@@ -923,6 +1155,14 @@ interface RelationTraversalOptions {
      * non-enumerable Symbol property so it can be passed back to `update()`.
      */
     updatable?: boolean;
+    /**
+     * Per-call throttle / transient-error retry override (issue #111), threaded from
+     * the read's entry point into every relation-fan-out send (the `BatchGet` for
+     * `belongsTo` / `hasOne`, the `Query` for `hasMany`). A {@link RetryPolicy}
+     * replaces the global policy; `false` disables retry. Threaded unchanged through
+     * every recursion level.
+     */
+    retry?: RetryOverride;
     /**
      * The **declared execution plan** (issue #70c) the traversal HONORS to decide
      * which sibling relations are independent (a concurrency-eligible stage) and the
@@ -938,6 +1178,23 @@ interface RelationTraversalOptions {
      * grouping / bound and observe the traversal execute accordingly.
      */
     plan?: RelationExecutionPlan;
+    /**
+     * The per-read middleware runtime (issue #50 / #138), threaded UNCHANGED from
+     * the read's entry point into every relation fan-out fetch — exactly like
+     * `retry`. Each fan-out send is wrapped so the op-level hooks R2 (before send) /
+     * R3 (raw items) / R5 (op error) fire for that physical op too, with
+     * `ctx.relationPath` identifying the fan-out leg (`['orders']`,
+     * `['orders','product']`, …) and `ctx.model` the relation's target model.
+     * Absent → {@link NO_MIDDLEWARE} (no hooks).
+     */
+    mw?: MiddlewareRuntime;
+    /**
+     * The relation path from the root read to the CURRENT traversal level — `[]`
+     * at the root, extended by each relation's property name as the traversal
+     * recurses. Used only to populate `ctx.relationPath` for the op-level hooks
+     * (R2/R3/R5). Threaded alongside {@link mw}.
+     */
+    relationPath?: readonly string[];
 }
 /**
  * Validates that the select depth does not exceed maxDepth.
@@ -2033,4 +2290,4 @@ declare function assertBundleSerializable(bundle: BridgeBundle): void;
  */
 declare function buildBridgeBundle(queries?: DefinitionMap, commands?: DefinitionMap, registry?: typeof MetadataRegistry, transactions?: Record<string, TransactionDefinition>, contractInputs?: ContractInputs): BridgeBundle;
 
-export { type AnyModelContract, AnyOperationDefinition, BATCH_GET_MAX_KEYS, BATCH_WRITE_MAX_ITEMS, BatchGetExecInput, BatchWriteExecItem, BridgeBundle, type BuiltContracts, CdcEmulator, CdcEmulatorOptions, ChangeEvent, ChangeHandler, ClientManager, type CollectParams, CommandMethodSpec, CommandModelContract, CommandSpec, ConcurrentRecomputeRef, type ConditionExpressionResult, ConditionInput, ConditionSpec, type ContextOwnership, type ContextOwnershipMap, ContextSpec, type ContractBoundaryViolation, type ContractInputs, type ContractMap, type ContractN1Violation, ContractSpec, DDBModel, DefinitionMap, DeleteInput, DynamoDBOperation, DynamoExecutor, type DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, type EmbeddedMetadata, type EntityMetadata, EntityRef, EventLog, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FaultSpec, type FieldMetadata, type FieldOptions, type FilterExpressionResult, type GsiDefinition, type KeyDefinition, type LintResult, type LintRule, Linter, type ListInput, type ListOptions, MAX_TRANSACT_ITEMS, Manifest, MetadataRegistry, type ModelOptions, ModelStatic, OLD_VALUE_NAMESPACE, OperationDefinition, OperationsDocument, Param, ParamDescriptor, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, PrimaryKeyOf, type ProjectionResult, PutInput, QueryMethodSpec, QueryModelContract, type QueryOptions$1 as QueryOptions, QuerySpec, RawCondition, type RelationLimitOptions, type RelationMetadata, type RelationOptions, type RelationTraversalOptions, ReplayOptions, ResolvedKey, SegmentedKey, SelectableOf, ShardId, TableMapping, TransactWriteExecItem, type TransactionDefinition, TransactionItemSpec, type TransactionParamShape, type TransactionRef, TransactionSpec, type TxConditionCheckOptions, type TxForEachInstruction, type TxForEachOptions, type TxInstruction, type TxRecorder, type TxWriteInstruction, type TxWriteOptions, UniqueQueryKeyOf, type UpdateExpressionResult, UpdateInput, type WhenComparison, WriteDefinitionOptions, WriteExecOptions, WriteResult, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, belongsTo, binary, boolean, buildBridgeBundle, buildConditionExpression, buildContexts, buildContracts, buildManifest, buildOperations, buildProjection, buildQuerySpec, buildTransactionSpec, buildTransactions, buildUpdateExpression, collectContractBoundaryViolations, collectContractN1Violations, compileFilterExpression, createCdcEmulator, createDefaultLinter, datetime, decodeCursor, decodePerKeyCursor, defineCommands, defineDelete, defineList, definePut, defineQueries, defineQuery, defineTransaction, defineTransactions, defineUpdate, deriveEdgeWriteItems, deriveEdgeWriteItemsFor, deriveModelEdgeWriteItems, derivePrefix, detectRelationFields, edgeWrites, embedded, encodeCursor, encodePerKeyCursor, evaluateFilter, execute, executeDeclarativeTransaction, executeExplain, executeList, executeQuery, expandTransaction, field, getEdgeWrites, getImplicitKeyFields, gsiAmbiguityRule, hasMany, hasOne, hydrate, isEdgeWritesDefinition, isSelectBuilder, isTransactionRef, list, literal, map, missingGsiRule, model, noScanRule, number, numberSet, plan, queryBoundaryRule, relationDepthRule, requireLimitRule, resolveKey, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, validateDepth, validateGsiAmbiguity, when };
+export { type AnyModelContract, AnyOperationDefinition, BATCH_GET_MAX_KEYS, BATCH_WRITE_MAX_ITEMS, BatchExecOptions, BatchGetExecInput, BatchWriteExecItem, BridgeBundle, type BuiltContracts, CdcEmulator, CdcEmulatorOptions, ChangeEvent, ChangeHandler, ClientManager, type CollectParams, CommandMethodSpec, CommandModelContract, CommandSpec, ConcurrentRecomputeRef, type ConditionExpressionResult, ConditionInput, ConditionSpec, type ContextOwnership, type ContextOwnershipMap, ContextSpec, type ContractBoundaryViolation, type ContractInputs, type ContractMap, type ContractN1Violation, ContractSpec, CtxModel, DDBModel, DefinitionMap, DeleteInput, DynamoDBOperation, DynamoExecutor, type DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, type EmbeddedMetadata, type EntityMetadata, EntityRef, EventLog, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FaultSpec, type FieldMetadata, type FieldOptions, type FilterExpressionResult, type GsiDefinition, Item, type KeyDefinition, type LintResult, type LintRule, Linter, type ListInput, type ListOptions, MAX_TRANSACT_ITEMS, Manifest, MetadataRegistry, Middleware, type ModelOptions, ModelStatic, OLD_VALUE_NAMESPACE, OperationDefinition, OperationsDocument, Param, ParamDescriptor, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, PrimaryKeyOf, type ProjectionResult, PutInput, QueryMethodSpec, QueryModelContract, type QueryOptions$1 as QueryOptions, QuerySpec, RawCondition, ReadExecOptions, ReadParams, ReadRequestCtx, ReadRequestKind, type RelationLimitOptions, type RelationMetadata, type RelationOptions, type RelationTraversalOptions, ReplayOptions, RequestContext, ResolvedKey, RetryOverride, RetryPolicy, RetryingExecutor, SegmentedKey, SelectableOf, ShardId, TableMapping, TransactWriteExecItem, type TransactionDefinition, TransactionItemSpec, type TransactionParamShape, type TransactionRef, TransactionSpec, type TxConditionCheckOptions, type TxForEachInstruction, type TxForEachOptions, type TxInstruction, type TxRecorder, type TxWriteInstruction, type TxWriteOptions, UniqueQueryKeyOf, type UpdateExpressionResult, UpdateInput, type WhenComparison, WriteDefinitionOptions, WriteExecOptions, WriteResult, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, belongsTo, binary, boolean, buildBridgeBundle, buildConditionExpression, buildContexts, buildContracts, buildManifest, buildOperations, buildProjection, buildQuerySpec, buildTransactionSpec, buildTransactions, buildUpdateExpression, collectContractBoundaryViolations, collectContractN1Violations, compileFilterExpression, createCdcEmulator, createDefaultLinter, datetime, decodeCursor, decodePerKeyCursor, defineCommands, defineDelete, defineList, definePut, defineQueries, defineQuery, defineTransaction, defineTransactions, defineUpdate, deriveEdgeWriteItems, deriveEdgeWriteItemsFor, deriveModelEdgeWriteItems, derivePrefix, detectRelationFields, edgeWrites, embedded, encodeCursor, encodePerKeyCursor, evaluateFilter, execute, executeDeclarativeTransaction, executeExplain, executeList, executeQuery, expandTransaction, field, getEdgeWrites, getImplicitKeyFields, gsiAmbiguityRule, hasMany, hasOne, hydrate, isEdgeWritesDefinition, isSelectBuilder, isTransactionRef, list, literal, map, missingGsiRule, model, noScanRule, number, numberSet, plan, queryBoundaryRule, relationDepthRule, requireLimitRule, resolveKey, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, validateDepth, validateGsiAmbiguity, when };

package/dist/index.js

@@ -86,19 +86,22 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-NJEC76TX.js";
+} from "./chunk-SGYBE2OV.js";
 import {
   CdcEmulator,
   createCdcEmulator
-} from "./chunk-CVUDLLRS.js";
+} from "./chunk-ITHQ2EDH.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
   ClientManager,
+  DEFAULT_MAX_ATTEMPTS,
+  DEFAULT_RETRY_POLICY,
   DynamoExecutor,
   Linter,
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
+  RetryingExecutor,
   TableMapping,
   TransactionContext,
   attachModelClass,
@@ -123,6 +126,8 @@ import {
   isKeySegment,
   isParam,
   isRawCondition,
+  isRetryableError,
+  isRetryableTransactionCancellation,
   k,
   key,
   missingGsiRule,
@@ -134,7 +139,7 @@ import {
   resolveKey,
   resolveModelClass,
   serializeFieldValue
-} from "./chunk-FWDJSGF3.js";
+} from "./chunk-4TYK3AV6.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -1044,6 +1049,8 @@ export {
   CdcEmulator,
   ClientManager,
   DDBModel,
+  DEFAULT_MAX_ATTEMPTS,
+  DEFAULT_RETRY_POLICY,
   DynamoExecutor,
   EDGE_WRITES_MARKER,
   ENTITY_WRITES_MARKER,
@@ -1052,6 +1059,7 @@ export {
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
   OLD_VALUE_NAMESPACE,
+  RetryingExecutor,
   SPEC_VERSION,
   TableMapping,
   TransactionContext,
@@ -1155,6 +1163,8 @@ export {
   isParam,
   isPlannedCommandMethod,
   isQueryModelContract,
+  isRetryableError,
+  isRetryableTransactionCancellation,
   isSelectBuilder,
   isTransactionRef,
   k,

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { E as Executor, D as DynamoDBOperation, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, T as TransactWriteExecItem, M as ModelStatic, e as DDBModel, C as ChangeEvent } from '../types-SKxZQbQO.js';
+import { E as Executor, D as DynamoDBOperation, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, f as DDBModel, C as ChangeEvent } from '../types--tdHK3vi.js';
 import '@aws-sdk/client-dynamodb';
 
 /**
@@ -71,15 +71,15 @@ declare class MemoryStore {
 declare class MemoryExecutor implements Executor {
     private readonly store;
     constructor(store: MemoryStore);
-    execute(operation: DynamoDBOperation): Promise<ExecutorResult>;
-    batchGet(input: BatchGetExecInput): Promise<ExecutorResult>;
+    execute(operation: DynamoDBOperation, _options?: ReadExecOptions): Promise<ExecutorResult>;
+    batchGet(input: BatchGetExecInput, _options?: ReadExecOptions): Promise<ExecutorResult>;
     private getItem;
     private query;
     put(input: PutInput, options?: WriteExecOptions): Promise<WriteResult>;
     update(input: UpdateInput, options?: WriteExecOptions): Promise<WriteResult>;
     delete(input: DeleteInput, options?: WriteExecOptions): Promise<WriteResult>;
-    batchWrite(tableName: string, items: BatchWriteExecItem[]): Promise<void>;
-    transactWrite(items: TransactWriteExecItem[]): Promise<void>;
+    batchWrite(tableName: string, items: BatchWriteExecItem[], _options?: BatchExecOptions): Promise<void>;
+    transactWrite(items: TransactWriteExecItem[], _options?: BatchExecOptions): Promise<void>;
     private restoreTable;
     /**
      * Evaluate a transaction `ConditionCheck` (issue #81): read the keyed item and

package/dist/testing/index.js

@@ -1,12 +1,12 @@
 import {
   createCdcEmulator
-} from "../chunk-CVUDLLRS.js";
+} from "../chunk-ITHQ2EDH.js";
 import {
   ClientManager,
   MetadataRegistry,
   TableMapping,
   resolveModelClass
-} from "../chunk-FWDJSGF3.js";
+} from "../chunk-4TYK3AV6.js";
 
 // src/memory/memory-store.ts
 function deepClone(value) {
@@ -543,7 +543,10 @@ var MemoryExecutor = class {
   }
   store;
   // ── reads ────────────────────────────────────────────────────────────────
-  async execute(operation) {
+  // The optional per-call options (`ReadExecOptions` / `BatchExecOptions`) carry a
+  // retry override (issue #111) that only `RetryingExecutor` acts on; the in-memory
+  // adapter never throttles, so it accepts and ignores them.
+  async execute(operation, _options) {
     if (operation.type === "GetItem") {
       return this.getItem(operation);
     }
@@ -552,7 +555,7 @@ var MemoryExecutor = class {
     }
     return this.query(operation);
   }
-  async batchGet(input) {
+  async batchGet(input, _options) {
     const items = [];
     for (const key of input.keys) {
       const found = this.store.getItem(
@@ -673,7 +676,7 @@ var MemoryExecutor = class {
     this.store.deleteItem(input.TableName, pk, sk);
     return options?.returnOldImage && prior ? { oldItem: prior } : {};
   }
-  async batchWrite(tableName, items) {
+  async batchWrite(tableName, items, _options) {
     for (const item of items) {
       if (item.type === "put") {
         this.store.putItem(tableName, item.item);
@@ -686,7 +689,7 @@ var MemoryExecutor = class {
       }
     }
   }
-  async transactWrite(items) {
+  async transactWrite(items, _options) {
     if (items.length === 0) return;
     const touchedTables = /* @__PURE__ */ new Set();
     for (const it of items) {