graphddb 0.2.4 → 0.2.5

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SelectableOf, g as PrimaryKeyOf, E as Executor, h as RetryPolicy, i as ExecutionPlanSpec, j as SegmentedKey, k as SelectBuilderSpec, l as RawCondition, m as TransactionSpec, n as Manifest, o as RetryOverride, p as ExecutionPlan, q as ResolvedKey, 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, r as CdcEmulatorOptions, s as ChangeHandler, t as Unsubscribe, F as FaultSpec, u as ConcurrentRecomputeRef, C as ChangeEvent, v as EventLog, w as ReplayOptions, x as ShardId, y as TransactionItemSpec, z as Param, A as ParamDescriptor, G as DefinitionMap, O as OperationDefinition, f as DDBModel, M as ModelStatic, H as WriteDefinitionOptions, I as PartialQueryKeyOf, J as StrictSelectSpec, K as EntityInput, L as UniqueQueryKeyOf, N as EntityRef, Q as ConditionInput, V as QueryModelContract, X as QueryMethodSpec, Y as CommandModelContract, Z as CommandMethodSpec, _ as ContractSpec, $ as QuerySpec, a0 as CommandSpec, a1 as ContextSpec, a2 as OperationsDocument, a3 as AnyOperationDefinition, a4 as BridgeBundle, a5 as ConditionSpec } from './types-BEeQ_nSd.js';
-export { a6 as BatchDeleteRequest, a7 as BatchGetRequest, a8 as BatchGetResult, a9 as BatchPutRequest, aa as BatchResult, ab as BatchWriteRequest, ac as CONTRACT_RANGE_FANOUT_CONCURRENCY, ad as CdcMode, ae as ChangeBatch, af as ChangeEventName, ag as ClockMode, ah as Column, ai as ColumnMap, aj as CommandContractMethodSpec, ak as CommandInputShape, al as CommandMethod, am as CommandPlan, an as CommandResolutionTarget, ao as CommandResultKind, ap as CommandSelectShape, aq as CompiledFragment, ar as ComposeSpec, as as CondSlot, at as ConditionCheckInput, au as Connection, av as ContractCallSignature, aw as ContractCardinality, ax as ContractCommandParams, ay as ContractCommandResult, az as ContractComposeNode, aA as ContractFromRef, aB as ContractInputArity, aC as ContractItem, aD as ContractKeyFieldRef, aE as ContractKeyInput, aF as ContractKeyRef, aG as ContractKeySpec, aH as ContractKind, aI as ContractMethodOp, aJ as ContractParamRef, aK as ContractQueryParams, aL as ContractResolution, aM as DEFAULT_MAX_ATTEMPTS, aN as DEFAULT_RETRY_POLICY, aO as DeleteOptions, aP as DeriveEffect, aQ as DerivedEdgeWrite, aR as DerivedUpdate, aS as DescriptorBinding, aT as ENTITY_WRITES_MARKER, aU as EdgeEffect, aV as EffectPath, aW as EmitEffect, aX as EntityWritesDefinition, aY as EntityWritesShape, aZ as ExecutableCommandContract, a_ as ExecutableQueryContract, a$ as FilterInput, b0 as FilterSpec, b1 as FragmentInput, b2 as GsiDefinitionMarker, b3 as GsiOptions, b4 as IdempotencyEffect, b5 as InProcessWriteDescriptor, b6 as InputArity, b7 as KeyDefinitionMarker, b8 as KeySegment, b9 as KeySlot, ba as KeyStructure, bb as KeyedResult, bc as LIFECYCLE_CONTRACT_MARKER, bd as LifecycleContract, be as LifecycleEffects, bf as LiteralParam, bg as ManifestEntity, bh as ManifestField, bi as ManifestFieldType, bj as ManifestGsi, bk as ManifestKey, bl as ManifestRelation, bm as ManifestTable, bn as ModelRef, bo as MutateMode, bp as MutateOptions, bq as MutateParallelResult, br as MutateTransactionResult, bs as MutationBody, bt as MutationDescriptorMap, bu as MutationFragment, bv as MutationInputProxy, bw as MutationInputRef, bx as MutationIntent, by as NumberParam, bz as OperationKind, bA as OperationSpec, bB as ParallelOpResult, bC as ParamKind, bD as ParamSpec, bE as ParamStructure, bF as PlannedCommandMethod, bG as PutOptions, bH as QueryContractMethodSpec, bI as QueryEnvelopeResult, bJ as QueryKeyOf, bK as QueryMethod, bL as QueryResult, bM as RangeConditionSpec, bN as ReadEnvelope, bO as ReadOperationType, bP as ReadRouteDescriptor, bQ as ReadRouteOptions, bR as ReadRouteResult, bS as RecordedCompose, bT as RelationBuilder, bU as RelationSelect, bV as RelationSpec, bW as RequiresEffect, bX as Resolution, bY as RetryInfo, bZ as RetryOperationKind, b_ as SPEC_VERSION, b$ as SegmentSpec, c0 as SelectBuilder, c1 as SelectOf, c2 as StartingPosition, c3 as StreamViewType, c4 as StringParam, c5 as TransactionContext, c6 as TransactionItemType, c7 as UniqueEffect, c8 as Updatable, c9 as UpdateOptions, ca as WhenSpec, cb as WriteDescriptor, cc as WriteEnvelope, cd as WriteLifecyclePhase, ce as WriteOperationType, cf as WriteRecorder, cg as WriteResultProjection, ch as attachModelClass, ci as buildDeleteInput, cj as buildPutInput, ck as buildUpdateInput, cl as compileFragment, cm as compileMutationPlan, cn as compileSingleFragmentPlan, co as cond, cp as contractOfMethodSpec, cq as definePlan, cr as entityWrites, cs as executeBatchGet, ct as executeBatchWrite, cu as executeCommandMethod, cv as executeDelete, cw as executeKeyedBatchGet, cx as executePut, cy as executeQueryMethod, cz as executeRangeFanout, cA as executeTransaction, cB as executeUpdate, cC as from, cD as getEntityWrites, cE as gsi, cF as isColumn, cG as isCommandModelContract, cH as isCommandPlan, cI as isContractComposeNode, cJ as isContractFromRef, cK as isContractKeyFieldRef, cL as isContractKeyRef, cM as isContractParamRef, cN as isEntityWritesDefinition, cO as isKeySegment, cP as isLifecycleContract, cQ as isMutationFragment, cR as isMutationInputRef, cS as isParam, cT as isPlannedCommandMethod, cU as isQueryModelContract, cV as isRetryableError, cW as isRetryableTransactionCancellation, cX as k, cY as key, cZ as lifecyclePhaseForIntent, c_ as mintContractKeyFieldRef, c$ as mintContractParamRef, d0 as mutation, d1 as param, d2 as publicCommandModel, d3 as publicQueryModel, d4 as query, d5 as resolveLifecycle, d6 as wholeKeysSentinel } from './types-BEeQ_nSd.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).
  *
@@ -99,6 +192,15 @@ declare class ClientManager {
      * 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>;
@@ -129,6 +231,21 @@ declare class ClientManager {
     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;
 }
@@ -558,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>;
 
@@ -580,6 +705,28 @@ interface ListInput {
      * 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
@@ -1031,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.
@@ -2126,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, 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, 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, ReadExecOptions, type RelationLimitOptions, type RelationMetadata, type RelationOptions, type RelationTraversalOptions, ReplayOptions, 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 };
+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,11 +86,11 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-IQEOJVHI.js";
+} from "./chunk-SGYBE2OV.js";
 import {
   CdcEmulator,
   createCdcEmulator
-} from "./chunk-LNESVUTO.js";
+} from "./chunk-ITHQ2EDH.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
@@ -139,7 +139,7 @@ import {
   resolveKey,
   resolveModelClass,
   serializeFieldValue
-} from "./chunk-GCPEUPAA.js";
+} from "./chunk-4TYK3AV6.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-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-BEeQ_nSd.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';
 
 /**

package/dist/testing/index.js

@@ -1,12 +1,12 @@
 import {
   createCdcEmulator
-} from "../chunk-LNESVUTO.js";
+} from "../chunk-ITHQ2EDH.js";
 import {
   ClientManager,
   MetadataRegistry,
   TableMapping,
   resolveModelClass
-} from "../chunk-GCPEUPAA.js";
+} from "../chunk-4TYK3AV6.js";
 
 // src/memory/memory-store.ts
 function deepClone(value) {