graphddb 0.2.4 → 0.3.0

package/dist/{chunk-LNESVUTO.js → chunk-QQNP43JL.js}

@@ -1,7 +1,7 @@
 import {
   ChangeCaptureRegistry,
   resolveModelClass
-} from "./chunk-GCPEUPAA.js";
+} from "./chunk-6AIAHP3A.js";
 
 // src/cdc/prng.ts
 var SeededRandom = class {

package/dist/cli.js

@@ -2,10 +2,10 @@
 import {
   buildBridgeBundle,
   normalizeSelectSpec
-} from "./chunk-IQEOJVHI.js";
+} from "./chunk-QEOFIXTN.js";
 import {
   MetadataRegistry
-} from "./chunk-GCPEUPAA.js";
+} from "./chunk-6AIAHP3A.js";
 
 // src/cli.ts
 import { createRequire } from "module";

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 EntityMetadata, K as KeyDefinition, G as GsiDefinition, F as FieldOptions, q as DynamoType, r as RelationOptions, A as AggregateOptions, s as AggregateValue, t as SelectBuilderSpec, u as RawCondition, v as TransactionSpec, w as Manifest, x as RetryOverride, y as ExecutionPlan, z as FieldMetadata, H 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, J as CdcEmulatorOptions, L as ChangeHandler, N as Unsubscribe, O as FaultSpec, Q as ConcurrentRecomputeRef, C as ChangeEvent, V as EventLog, X as ReplayOptions, Y as ShardId, Z as RelationMetadata, _ as TransactionItemSpec, $ as Param, a0 as ParamDescriptor, a1 as DefinitionMap, a2 as OperationDefinition, f as DDBModel, M as ModelStatic, a3 as WriteDefinitionOptions, a4 as PartialQueryKeyOf, a5 as StrictSelectSpec, a6 as EntityInput, a7 as UniqueQueryKeyOf, a8 as EntityRef, a9 as ConditionInput, aa as QueryModelContract, ab as QueryMethodSpec, ac as CommandModelContract, ad as CommandMethodSpec, ae as ContractSpec, af as QuerySpec, ag as CommandSpec, ah as ContextSpec, ai as OperationsDocument, aj as AnyOperationDefinition, ak as BridgeBundle, al as ConditionSpec } from './types-xJRn5qkv.js';
+export { am as AggregateMetadata, an as BatchDeleteRequest, ao as BatchGetOptions, ap as BatchGetRequest, aq as BatchGetResult, ar as BatchPutRequest, as as BatchResult, at as BatchWriteRequest, au as CONTRACT_RANGE_FANOUT_CONCURRENCY, av as CdcMode, aw as Change, ax as ChangeBatch, ay as ChangeEventName, az as ClockMode, aA as CollectionEffect, aB as CollectionOptions, aC as Column, aD as ColumnMap, aE as CommandContractMethodSpec, aF as CommandInputShape, aG as CommandMethod, aH as CommandPlan, aI as CommandResolutionTarget, aJ as CommandResultKind, aK as CommandSelectShape, aL as CompiledFragment, aM as ComposeSpec, aN as CondSlot, aO as ConditionCheckInput, aP as Connection, aQ as ContractCallSignature, aR as ContractCardinality, aS as ContractCommandParams, aT as ContractCommandResult, aU as ContractComposeNode, aV as ContractFromRef, aW as ContractInputArity, aX as ContractItem, aY as ContractKeyFieldRef, aZ as ContractKeyInput, a_ as ContractKeyRef, a$ as ContractKeySpec, b0 as ContractKind, b1 as ContractMethodOp, b2 as ContractParamRef, b3 as ContractQueryParams, b4 as ContractResolution, b5 as CounterAggregate, b6 as CounterEffect, b7 as CtxBase, b8 as DEFAULT_MAX_ATTEMPTS, b9 as DEFAULT_RETRY_POLICY, ba as DeleteOptions, bb as DeriveEffect, bc as DerivedEdgeWrite, bd as DerivedUpdate, be as DescriptorBinding, bf as ENTITY_WRITES_MARKER, bg as EdgeEffect, bh as EffectPath, bi as EmbeddedMetadata, bj as EmitEffect, bk as EntityWritesDefinition, bl as EntityWritesShape, bm as ExecutableCommandContract, bn as ExecutableQueryContract, bo as FilterInput, bp as FilterSpec, bq as FragmentInput, br as GsiDefinitionMarker, bs as GsiOptions, bt as IdempotencyEffect, bu as InProcessWriteDescriptor, bv as InputArity, bw as KeyDefinitionMarker, bx as KeySegment, by as KeySlot, bz as KeyStructure, bA as KeyedResult, bB as LIFECYCLE_CONTRACT_MARKER, bC as LifecycleContract, bD as LifecycleEffects, bE as LiteralParam, bF as MaintainConsistency, bG as MaintainEffect, bH as MaintainEvent, bI as MaintainItem, bJ as MaintainTrigger, bK as MaintainUpdateMode, bL as MaintenanceGraph, bM as ManifestEntity, bN as ManifestField, bO as ManifestFieldType, bP as ManifestGsi, bQ as ManifestKey, bR as ManifestRelation, bS as ManifestTable, bT as ModelRef, bU as MutateMode, bV as MutateOptions, bW as MutateParallelResult, bX as MutateTransactionResult, bY as MutationBody, bZ as MutationDescriptorMap, b_ as MutationFragment, b$ as MutationInputProxy, c0 as MutationInputRef, c1 as MutationIntent, c2 as NumberParam, c3 as OperationKind, c4 as OperationSpec, c5 as ParallelOpResult, c6 as ParamKind, c7 as ParamSpec, c8 as ParamStructure, c9 as PersistCtx, ca as PersistOrigin, cb as PlannedCommandMethod, cc as ProjectionMap, cd as ProjectionTransform, ce as ProjectionTransformOp, cf as PutOptions, cg as QueryContractMethodSpec, ch as QueryEnvelopeResult, ci as QueryKeyOf, cj as QueryMethod, ck as QueryResult, cl as RangeConditionSpec, cm as ReadEnvelope, cn as ReadOpCtx, co as ReadOpKind, cp as ReadOperationType, cq as ReadRouteDescriptor, cr as ReadRouteOptions, cs as ReadRouteResult, ct as RecordedCompose, cu as RelationBuilder, cv as RelationConsistency, cw as RelationLimitOptions, cx as RelationPattern, cy as RelationProjection, cz as RelationReadOptions, cA as RelationSelect, cB as RelationSpec, cC as RelationUpdateMode, cD as RelationWriteOptions, cE as RequiresEffect, cF as Resolution, cG as RetryInfo, cH as RetryOperationKind, cI as SPEC_VERSION, cJ as SegmentSpec, cK as SegmentedKey, cL as SelectBuilder, cM as SelectOf, cN as SnapshotEffect, cO as StartingPosition, cP as StreamViewType, cQ as StringParam, cR as TransactionContext, cS as TransactionItemType, cT as UniqueEffect, cU as Updatable, cV as UpdateOptions, cW as WhenSpec, cX as WriteCtx, cY as WriteDescriptor, cZ as WriteEnvelope, c_ as WriteInput, c$ as WriteKind, d0 as WriteLifecyclePhase, d1 as WriteMiddleware, d2 as WriteOperationType, d3 as WriteRecorder, d4 as WriteResultProjection, d5 as attachModelClass, d6 as buildDeleteInput, d7 as buildMaintenanceGraph, d8 as buildPutInput, d9 as buildUpdateInput, da as compileFragment, db as compileMutationPlan, dc as compileSingleFragmentPlan, dd as cond, de as contractOfMethodSpec, df as definePlan, dg as entityWrites, dh as executeBatchGet, di as executeBatchWrite, dj as executeCommandMethod, dk as executeDelete, dl as executeKeyedBatchGet, dm as executePut, dn as executeQueryMethod, dp as executeRangeFanout, dq as executeTransaction, dr as executeUpdate, ds as from, dt as getEntityWrites, du as gsi, dv as identity, dw as isColumn, dx as isCommandModelContract, dy as isCommandPlan, dz as isContractComposeNode, dA as isContractFromRef, dB as isContractKeyFieldRef, dC as isContractKeyRef, dD as isContractParamRef, dE as isEntityWritesDefinition, dF as isKeySegment, dG as isLifecycleContract, dH as isMaintainTrigger, dI as isMutationFragment, dJ as isMutationInputRef, dK as isParam, dL as isPlannedCommandMethod, dM as isQueryModelContract, dN as isRetryableError, dO as isRetryableTransactionCancellation, dP as k, dQ as key, dR as lifecyclePhaseForIntent, dS as maintainTrigger, dT as mintContractKeyFieldRef, dU as mintContractParamRef, dV as mutation, dW as param, dX as preview, dY as publicCommandModel, dZ as publicQueryModel, d_ as query, d$ as resolveLifecycle, e0 as wholeKeysSentinel } from './types-xJRn5qkv.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 docs/middleware.md
+ * 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/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;
 }
@@ -196,71 +313,6 @@ interface RelationExecutionPlan {
     readonly resultPaths: readonly string[];
 }
 
-type DynamoType = 'S' | 'N' | 'BOOL' | 'B' | 'SS' | 'NS' | 'L' | 'M';
-interface FieldOptions {
-    format?: 'datetime' | 'date';
-    readonly?: boolean;
-    serialize?: (value: unknown) => unknown;
-    deserialize?: (value: unknown) => unknown;
-}
-interface FieldMetadata {
-    propertyName: string;
-    dynamoType: DynamoType;
-    options?: FieldOptions;
-    /**
-     * For a `@literal(...)` field — a `string`-stored field whose value is one of a
-     * known, finite set — the allowed literal values, in declaration order (issue
-     * #75). Recorded purely as model metadata so a Contract param bound into the
-     * field can recover the precise `literal` param-kind from its bind position
-     * (`src/spec/contracts.ts`), serializing as `{ type: 'literal', literals: [...] }`
-     * instead of the imprecise `'string'`. JSON-safe by construction (a non-empty
-     * array of strings). `undefined` for every other field decorator (`@string`,
-     * `@number`, …), so plain fields are byte-for-byte unchanged (backward compat).
-     */
-    literals?: readonly string[];
-}
-
-interface KeyDefinition {
-    /** The canonical structured key (PK/SK segment lists). */
-    segmented: SegmentedKey;
-    inputFieldNames: string[];
-}
-interface GsiDefinition {
-    indexName: string;
-    /** The canonical structured key (PK/SK segment lists). */
-    segmented: SegmentedKey;
-    inputFieldNames: string[];
-    unique: boolean;
-}
-interface RelationLimitOptions {
-    default: number;
-    max: number;
-}
-interface RelationOptions {
-    limit?: RelationLimitOptions;
-    order?: 'ASC' | 'DESC';
-}
-interface RelationMetadata {
-    type: 'hasMany' | 'hasOne' | 'belongsTo';
-    propertyName: string;
-    targetFactory: () => new (...args: unknown[]) => unknown;
-    keyBinding: Record<string, string>;
-    options?: RelationOptions;
-}
-interface EmbeddedMetadata {
-    propertyName: string;
-    modelFactory: () => new (...args: unknown[]) => unknown;
-}
-interface EntityMetadata {
-    tableName: string;
-    prefix: string;
-    fields: FieldMetadata[];
-    primaryKey: KeyDefinition | null;
-    gsiDefinitions: GsiDefinition[];
-    relations: RelationMetadata[];
-    embeddedFields: EmbeddedMetadata[];
-}
-
 interface LintRule {
     id: string;
     severity: 'error' | 'warning';
@@ -284,6 +336,22 @@ declare class Linter {
 declare class MetadataRegistry {
     private static store;
     private static _linter;
+    /**
+     * A monotonically-increasing counter bumped on every change to the set of
+     * registered models ({@link register} / {@link clear}). It lets a consumer that
+     * caches a structure derived from the whole registry (e.g. the maintenance graph
+     * in `src/spec/mutation-command.ts`) detect that the registry has changed since
+     * the cache was built and rebuild — closing the silent-drop window where a model
+     * registered after a cache build would be invisible to it. Only the membership
+     * of {@link store} changes here; per-model lazy finalize ({@link finalize}) does
+     * not bump it (it adds no relations/triggers, so it cannot change the graph).
+     */
+    private static _generation;
+    /**
+     * The current registry generation (see {@link _generation}). A consumer caches
+     * the value it built against and rebuilds when it no longer matches.
+     */
+    static get generation(): number;
     static register(target: Function, metadata: EntityMetadata): void;
     static get(target: Function): EntityMetadata;
     static has(target: Function): boolean;
@@ -414,9 +482,92 @@ declare const map: FieldDecorator<Record<string, unknown>>;
 declare function embedded(modelFactory: () => new (...args: unknown[]) => unknown): (_value: undefined, context: ClassFieldDecoratorContext) => void;
 
 declare function hasMany(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options?: RelationOptions): (_value: undefined, context: ClassFieldDecoratorContext) => void;
-declare function belongsTo(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>): (_value: undefined, context: ClassFieldDecoratorContext) => void;
+declare function belongsTo(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options?: RelationOptions): (_value: undefined, context: ClassFieldDecoratorContext) => void;
 declare function hasOne(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>): (_value: undefined, context: ClassFieldDecoratorContext) => void;
 
+/**
+ * `@aggregate` — a **scalar-aggregate** field decorator (Epic #118 §5.2 counter /
+ * latest preset; issue #122).
+ *
+ * Where `@hasMany` / `@belongsTo` declare a *navigation* (a relation yielding
+ * model instances) and `@string` / `@number` declare a *stored* attribute,
+ * `@aggregate` declares a **scalar value derived by aggregating a source
+ * entity's rows**. It is a field (the decorated property holds a `number` /
+ * `string`), but — like a relation — it carries a source `targetFactory` +
+ * `keyBinding` selecting the rows it aggregates. The declaration surface mirrors
+ * the RFC §5.2 example:
+ *
+ * ```ts
+ * @model({ table: 'AppTable', prefix: 'THREAD' })
+ * class ThreadSummaryModel extends DDBModel {
+ *   @string threadId!: string;
+ *
+ *   @aggregate(() => PostModel, { threadId: 'threadId' }, {
+ *     pattern: 'counter', value: count(),
+ *     write: { maintainedOn: ['Post.created', 'Post.removed'] },
+ *   })
+ *   postCount!: number;
+ *
+ *   @aggregate(() => PostModel, { threadId: 'threadId' }, {
+ *     pattern: 'counter', value: max('createdAt'),
+ *     write: { maintainedOn: ['Post.created'] },
+ *   })
+ *   lastPostAt!: string;
+ * }
+ * ```
+ *
+ * ## Scope (issue #122)
+ *
+ * This is the **declaration surface only** — the decorator records an
+ * {@link AggregateMetadata} into its own collector array (drained by `@model`
+ * into `EntityMetadata.aggregates`), exactly as the relation decorators push to
+ * the relation collector. The aggregation *effect* (maintenance graph #124,
+ * compile injection #125, runtime #127) is out of scope and consumes this
+ * metadata later.
+ *
+ * ## Vocabulary reuse (no double definition)
+ *
+ * `options.pattern` is the shared {@link RelationPattern} (typically `'counter'`)
+ * and `options.write` is the shared {@link RelationWriteOptions} — `maintainedOn`
+ * triggers on the `created|updated|removed` event vocabulary plus
+ * `consistency` (`transactional|eventual`) / `updateMode` (`mutation|stream`).
+ * Both were defined by B (#121) in `src/metadata/types.ts` and are **reused**
+ * here, never re-defined.
+ *
+ * @param targetFactory - Resolves the source entity whose rows are aggregated
+ *   (lazy, mirroring the relation decorators, to tolerate circular imports).
+ * @param keyBinding - The key binding selecting the source rows
+ *   (target key field → source field).
+ * @param options - The aggregate preset / value / maintenance-write declaration.
+ */
+declare function aggregate(targetFactory: () => new (...args: unknown[]) => unknown, keyBinding: Record<string, string>, options: AggregateOptions): (_value: undefined, context: ClassFieldDecoratorContext) => void;
+/**
+ * Value helper for an `@aggregate` field: the **count** aggregation — the
+ * cardinality of source rows matched by the key binding (Epic #118 §5.2
+ * `counter` preset, `count()`). It takes no source field (it counts rows, not a
+ * value), so the decorated field is a `number` (e.g. `postCount!: number`).
+ *
+ * Produces the {@link AggregateValue} IR node `{ op: 'count' }`. This is the
+ * standalone, recorder-free authoring helper used directly in the decorator
+ * argument (mirroring the standalone `preview(...)` / `identity(...)` projection
+ * helpers A (#120) exposes for relation options).
+ */
+declare function count(): AggregateValue;
+/**
+ * Value helper for an `@aggregate` field: the **max** aggregation — the maximum
+ * value of a named source `field` across the rows matched by the key binding
+ * (Epic #118 §5.2 `counter` / latest preset, `max('createdAt')`). The decorated
+ * field's type matches the source field's (e.g. `lastPostAt!: string` ←
+ * `max('createdAt')`).
+ *
+ * Produces the {@link AggregateValue} IR node `{ op: 'max', field }`.
+ *
+ * @param field - The source field whose maximum is tracked (e.g. `'createdAt'`).
+ * @throws if `field` is not a non-empty string (an aggregation over no source
+ *   field is meaningless — a defensive runtime check mirroring `@literal`'s).
+ */
+declare function max(field: string): AggregateValue;
+
 declare class TableMapping {
     private static mapping;
     static set(mapping: Record<string, string>): void;
@@ -558,6 +709,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 +739,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
@@ -978,10 +1159,14 @@ declare function decodePerKeyCursor(cursor: string, expectedKey: Record<string,
 /**
  * Creates a Linter pre-loaded with rules safe for Entity registration.
  *
- * Rules included: no-scan, require-limit, gsi-ambiguity, missing-gsi, relation-depth.
- * query-boundary is excluded because it flags non-unique GSIs which
- * are valid for list() operations; boundary enforcement is handled
- * at runtime by the planner's boundary-check.
+ * Rules included: no-scan, require-limit, gsi-ambiguity, missing-gsi,
+ * relation-depth, same-partition-preset, plus the Epic #118 Phase 1 maintenance
+ * validators (issue #126): missing-context, 400kb, hot-partition, fan-out,
+ * multi-maintainer-same-row. The maintenance validators are no-ops for any
+ * relation that does not declare `write.maintainedOn`, so unannotated models are
+ * unaffected. query-boundary is excluded because it flags non-unique GSIs which
+ * are valid for list() operations; boundary enforcement is handled at runtime by
+ * the planner's boundary-check.
  */
 declare function createDefaultLinter(): Linter;
 
@@ -1031,6 +1216,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 +2328,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 { AggregateOptions, AggregateValue, 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, DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, EntityMetadata, EntityRef, EventLog, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FaultSpec, FieldMetadata, FieldOptions, type FilterExpressionResult, GsiDefinition, Item, 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, RelationMetadata, RelationOptions, type RelationTraversalOptions, ReplayOptions, RequestContext, ResolvedKey, RetryOverride, RetryPolicy, RetryingExecutor, 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, aggregate, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, belongsTo, binary, boolean, buildBridgeBundle, buildConditionExpression, buildContexts, buildContracts, buildManifest, buildOperations, buildProjection, buildQuerySpec, buildTransactionSpec, buildTransactions, buildUpdateExpression, collectContractBoundaryViolations, collectContractN1Violations, compileFilterExpression, count, 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, max, missingGsiRule, model, noScanRule, number, numberSet, plan, queryBoundaryRule, relationDepthRule, requireLimitRule, resolveKey, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, validateDepth, validateGsiAmbiguity, when };