graphddb 0.2.4 → 0.3.0

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

@@ -778,213 +778,75 @@ type AtLeastOneKey<T> = {
  */
 type PartialQueryKeyOf<C> = QueryKeyOf<C> extends infer U ? U extends Record<string, unknown> ? AtLeastOneKey<U> : never : never;
 
-/**
- * A top-level `select` may be either a plain projection (`SelectableOf<T>`) or
- * a {@link SelectBuilder} produced by `Model.project(...)`. The builder is
- * model-bound to `T`, so its `.filter(...)` is typed against the full entity.
- */
-type SelectSpec<T> = SelectableOf<T> | SelectBuilder<T, any>;
-/**
- * Resolves the projection `S` from a top-level select spec (plain object or
- * builder), so the result type is computed identically for both forms.
- */
-type ProjectionOf<T, Sel> = Sel extends SelectableOf<T> ? Sel : SelectOf<Sel>;
-/**
- * Default model-class constraint used when a `ModelStatic` is referenced
- * without its concrete constructor type (e.g. `ModelStatic<UserModel>`).
- *
- * In that case key/option types fall back to permissive shapes so existing
- * usages keep compiling, while the precise inference is available when the
- * constructor type is supplied (as it is from `DDBModel.asModel()`).
- */
-type AnyModelClass = abstract new (...args: any[]) => DDBModel;
-/**
- * The accepted PK / GSI key type for `list()` / `explain()`.
- *
- * `list`/`explain` issue a DynamoDB *Query* against a partition, so a **partial**
- * key (partition-key subset of a PK/GSI input) is accepted — the sort-key tail
- * is optional. This matches the runtime key resolver. `query()` stays strict via
- * {@link QueryKey}. Derived from the model class when available, otherwise
- * permissive.
- */
-type ListKey<C> = [C] extends [AnyModelClass] ? PartialQueryKeyOf<C> : Record<string, unknown>;
-/**
- * The accepted key type for `query()` — only keys guaranteed to return a
- * single item (PK + unique GSIs). Derived from the model class when available.
- */
-type QueryKey<C> = [C] extends [AnyModelClass] ? UniqueQueryKeyOf<C> : Record<string, unknown>;
-/**
- * The accepted key type for `delete()` (PK only). Derived from the model
- * class when available.
- */
-type DeleteKey<C> = [C] extends [AnyModelClass] ? PrimaryKeyOf<C> : Record<string, unknown>;
-/**
- * The accepted *explicit* key type for `update()` — the base-table primary key
- * only. DynamoDB `UpdateItem` can target an item solely by its base-table PK
- * (GSI-based updates are impossible), so this is `PrimaryKeyOf<C>`, not
- * `UniqueQueryKeyOf<C>`. Derived from the model class when available.
- */
-type UpdateExplicitKey<C> = [C] extends [AnyModelClass] ? PrimaryKeyOf<C> : Record<string, unknown>;
-/**
- * Options accepted by `list()` (third argument). The projection is supplied as
- * the separate second `select` argument, symmetric with `query()`.
- *
- * - `filter` is the declarative server-side DynamoDB FilterExpression, typed
- *   against the full Entity `T` (may reference unprojected attributes). For
- *   arbitrary JS-only post-load filtering, narrow with `filter` then apply
- *   `result.items.filter(...)` (already fully typed).
- *
- * @typeParam T - The Entity type.
- */
-type ListCallOptions<T> = {
-    limit?: number;
-    after?: string;
-    order?: 'ASC' | 'DESC';
-    filter?: FilterInput<T>;
-    /**
-     * When `true`, each returned item is updatable: it carries its resolved
-     * base-table key as a hidden, non-enumerable property and is branded
-     * `& Updatable`, so it can be passed straight back to `updateItem()`.
-     */
-    updatable?: boolean;
-};
-/**
- * Public, type-inferring API surface produced by {@link DDBModel.asModel}.
- *
- * @typeParam T - The Entity type of the model.
- * @typeParam C - The model class constructor type. Supplied automatically by
- *   `asModel()`; when omitted, key/option types widen to permissive shapes so
- *   that `ModelStatic<T>` keeps compiling for callers that only name the entity.
- */
-interface ModelStatic<T extends DDBModel, C = unknown> {
+interface PutOptions<T = unknown> {
+    condition?: WriteCondition<T>;
     /**
-     * Type-safe column references for this model, one per scalar field. Used by
-     * the `cond` raw escape hatch (`cond\`${Model.col.age} > ${18}\``). Each
-     * column carries its declared type and is branded to this model, so passing
-     * another model's column into this model's `cond` is a compile error.
+     * Per-call throttle / transient-error retry override (issue #111). A
+     * {@link RetryPolicy} replaces the global policy for this call; `false` disables
+     * retry for this call. Omit to use the configured (or built-in default) policy.
      */
-    readonly col: ColumnMap<T>;
+    retry?: RetryOverride;
     /**
-     * Begin a model-bound, top-level select builder. The entity type `T` is fixed
-     * by this model and the projection `S` is inferred from the argument.
-     * `.filter(...)` is typed `FilterInput<T>` against the full entity.
-     *
-     * @example
-     * ```ts
-     * Order.list({ userId: 'u' },
-     *   Order.project({ orderId: true, amount: true })
-     *     .filter({ status: 'confirmed', amount: { gt: 100 } }),
-     * );
-     * ```
+     * Host-injected per-call write context (issue #50 / #139) — exposed to every
+     * write hook (W1–W5) as `ctx.context`. A host-language value, NEVER serialized
+     * into the SSoT / `operations.json` (the bridge #48 is unaffected). Absent ⇒ `{}`.
      */
-    project<const S extends SelectableOf<T>>(select: S): SelectBuilder<T, S>;
+    context?: RequestContext;
+}
+interface UpdateOptions<T = unknown> {
+    condition?: WriteCondition<T>;
     /**
-     * Begin a model-bound relation select builder for use as a relation field's
-     * value inside a parent `select`. `T` is this (relation target) model's
-     * entity type; `S` is inferred from the argument. Same model-bound inference
-     * as {@link ModelStatic.project}, plus per-relation pagination
-     * (`limit` / `after` / `order`).
-     *
-     * @example
-     * ```ts
-     * User.query({ userId: 'u' }, {
-     *   name: true,
-     *   orders: Order.relation({ orderId: true, amount: true })
-     *     .filter({ amount: { gt: 100 } }),
-     * });
-     * ```
+     * Per-call throttle / transient-error retry override (issue #111). A
+     * {@link RetryPolicy} replaces the global policy for this call; `false` disables
+     * retry for this call.
      */
-    relation<const S extends SelectableOf<T>>(select: S): RelationBuilder<T, S>;
+    retry?: RetryOverride;
     /**
-     * Fetch a single item by a unique key and **hydrate** the plain result onto a
-     * host-side object (issue #53). The `hydrate` factory receives the fully-built
-     * plain object — `QueryResult<T, ProjectionOf<T, Sel>>`, typed against exactly
-     * the `select`ed fields — and its return type `R` becomes the read's return
-     * type (subsuming a `queryAs(Ctor, …)` style: `hydrate: (raw) => new Ctor(raw)`).
-     *
-     * Applied as the **final after-fetch step**, only to a present item: a missing
-     * item resolves to `null` and the factory is NOT invoked (hence `R | null`). A
-     * throw from the factory propagates verbatim as the read's rejection.
+     * How to re-derive a GSI key whose composing fields are changed but **not all**
+     * available from `{ ...key, ...changes }` (issue #115).
      *
-     * Host-runtime ONLY: the factory is a host-language closure, never serialized
-     * into the SSoT / `operations.json`, so it does not impede the bridge (#48).
-     */
-    query<Sel extends SelectSpec<T>, R>(key: QueryKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options: {
-        consistentRead?: boolean;
-        maxDepth?: number;
-        updatable?: boolean;
-        hydrate: (raw: QueryResult<T, ProjectionOf<T, Sel>>) => R;
-    }): Promise<R | null>;
-    /**
-     * Fetch a single item by a unique key, requesting an **updatable** result.
-     * The returned item (when non-null) carries its resolved base-table key as a
-     * hidden, non-enumerable property and is branded `& Updatable`, so it can be
-     * passed straight back to {@link ModelStatic.updateItem} — even for a partial
-     * `select` or a GSI-based query. Do not spread / clone / JSON round-trip the
-     * result before updating: that drops both the hidden key and the brand.
-     */
-    query<Sel extends SelectSpec<T>>(key: QueryKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options: {
-        consistentRead?: boolean;
-        maxDepth?: number;
-        updatable: true;
-    }): Promise<(QueryResult<T, ProjectionOf<T, Sel>> & Updatable) | null>;
-    /**
-     * Fetch a single item by a unique key. The return type contains only the
-     * selected fields, derived from `select`.
+     * - **unset (default)** — refuse with an explicit error rather than let the
+     *   index silently rot. The error names the index, the changed field, and the
+     *   missing field(s). The happy path (all composing fields available) re-derives
+     *   in the SAME `UpdateExpression` and is unaffected by this option.
+     * - `'read-modify-write'` — read the current item, merge `{ ...item, ...changes }`,
+     *   re-derive every affected GSI key from the merged image, and write back under
+     *   an optimistic condition (the item must still exist / be unchanged). This costs
+     *   one extra read and is NOT atomic with the original update, but always re-derives
+     *   correctly.
      */
-    query<Sel extends SelectSpec<T>>(key: QueryKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options?: {
-        consistentRead?: boolean;
-        maxDepth?: number;
-        updatable?: false;
-    }): Promise<QueryResult<T, ProjectionOf<T, Sel>> | null>;
+    rederive?: 'read-modify-write';
     /**
-     * List items for a partition, symmetric with {@link ModelStatic.query}:
-     * `list(key, select, options?)`. `select` (the second argument) may be a plain
-     * projection or a `project(...)` builder. `options.filter` is the declarative
-     * server-side FilterExpression typed against the full Entity. Returned items
-     * contain only the selected fields.
+     * Host-injected per-call write context (issue #50 / #139) — exposed to every
+     * write hook (W1–W5) as `ctx.context`. NEVER serialized. Absent ⇒ `{}`.
      */
-    list<Sel extends SelectSpec<T>>(key: ListKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options: ListCallOptions<T> & {
-        updatable: true;
-    }): Promise<{
-        items: (QueryResult<T, ProjectionOf<T, Sel>> & Updatable)[];
-        cursor: string | null;
-    }>;
-    list<Sel extends SelectSpec<T>>(key: ListKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options?: ListCallOptions<T>): Promise<{
-        items: QueryResult<T, ProjectionOf<T, Sel>>[];
-        cursor: string | null;
-    }>;
-    explain<Sel extends SelectSpec<T>>(key: ListKey<C>, options?: {
-        select?: Sel & StrictSelectSpec<T, Sel>;
-        limit?: number;
-        after?: string;
-        order?: 'ASC' | 'DESC';
-        consistentRead?: boolean;
-        filter?: FilterInput<T>;
-    }): ExecutionPlan;
-    putItem(item: EntityInput<T>, options?: WriteOptions<T>): Promise<void>;
+    context?: RequestContext;
+}
+interface DeleteOptions<T = unknown> {
+    condition?: WriteCondition<T>;
     /**
-     * Update an item identified by its **explicit base-table primary key**
-     * (`PrimaryKeyOf<C>`). This is the canonical form — it requires the key input
-     * up front, so it can never silently target the wrong item.
-     *
-     * @example `await User.updateItem({ userId: 'alice' }, { status: 'disabled' });`
+     * Per-call throttle / transient-error retry override (issue #111). A
+     * {@link RetryPolicy} replaces the global policy for this call; `false` disables
+     * retry for this call.
      */
-    updateItem(key: UpdateExplicitKey<C>, changes: Partial<T>, options?: WriteOptions<T>): Promise<void>;
+    retry?: RetryOverride;
     /**
-     * Update an item using an **updatable** entity obtained from
-     * `query(..., { updatable: true })` / `list(..., { updatable: true })`. The
-     * hidden base-table key carried by that entity is used directly, so this
-     * works even for a partial `select` or a GSI-based read.
-     *
-     * Pass the entity as-is. A spread / clone / JSON round-trip drops both the
-     * brand (rejected here at compile time) and the hidden key (rejected at
-     * runtime), preventing an accidental wrong-item update.
+     * Host-injected per-call write context (issue #50 / #139) — exposed to every
+     * write hook (W1–W5) as `ctx.context`. NEVER serialized. Absent ⇒ `{}`.
      */
-    updateItem(entity: Partial<T> & Updatable, changes: Partial<T>, options?: WriteOptions<T>): Promise<void>;
-    deleteItem(key: DeleteKey<C>, options?: WriteOptions<T>): Promise<void>;
+    context?: RequestContext;
 }
 
+interface PutInput {
+    TableName: string;
+    Item: Record<string, unknown>;
+    ConditionExpression?: string;
+    ExpressionAttributeNames?: Record<string, string>;
+    ExpressionAttributeValues?: Record<string, unknown>;
+}
+declare function buildPutInput(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): PutInput;
+declare function executePut(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): Promise<void>;
+
 interface UpdateInput {
     TableName: string;
     Key: Record<string, unknown>;
@@ -1139,58 +1001,548 @@ interface Executor {
     transactWrite(items: TransactWriteExecItem[], options?: BatchExecOptions): Promise<void>;
 }
 
-interface PutOptions<T = unknown> {
-    condition?: WriteCondition<T>;
+/**
+ * Write middleware / hook public surface (issue #50 write path, #139). The merged
+ * design is `docs/middleware.md`; this module implements the
+ * **write** hook points W1–W5 and their context objects, layered on the SAME
+ * registry / runtime machinery the read hooks (#138) introduced.
+ *
+ * A write {@link Middleware} hook is host-only, runtime-registered (via
+ * `DDBModel.use`), and **never serialized** — like the read hooks it lives only on
+ * the {@link import('../client/ClientManager.js').ClientManager} host-runtime
+ * singleton and never touches the planner / spec generator / `operations.json`, so
+ * the TS↔Python bridge (#48) is unaffected. It is **unrestricted by intent**: a
+ * hook may observe, mutate `ctx`, `throw` to cancel, or (on `onError`) recover by
+ * returning a value. The library does NOT validate hook logic or impose semantics
+ * (see docs/middleware.md). The internal CDC / capture mechanism (`src/capture/`,
+ * `src/cdc/`) is a SEPARATE surface — write hooks are not a substitute for it nor
+ * it for them (see docs/middleware.md).
+ *
+ * @see docs/middleware.md (hook points W1–W5)
+ */
+
+/**
+ * The logical write kinds a {@link WriteCtx} may carry (W1 / W2 / W5). A W1 hook
+ * may REWRITE this in place — the canonical case is a `delete` → `update`
+ * (soft-delete-by-rewrite); derivation then runs on the rewritten op, so the
+ * stored effect is the update, not the delete (see docs/middleware.md).
+ */
+type WriteKind = 'put' | 'update' | 'delete';
+/**
+ * The mutable logical write input a W1 hook observes / mutates. This is the
+ * declarative write payload — NOT a serialized spec — at the granularity the
+ * logical op carries:
+ *
+ * - `put`    — the full `item` is in {@link WriteInput.item};
+ * - `update` — the target `key` (entity) is in {@link WriteInput.key} and the
+ *   field `changes` in {@link WriteInput.changes};
+ * - `delete` — the target `key` is in {@link WriteInput.key}.
+ *
+ * A W1 hook may mutate these in place (e.g. inject `updatedBy`), and may rewrite
+ * `ctx.kind` together with these fields (a `delete` → `update` sets `changes`).
+ * Keeping `input` and `kind` consistent is the host's responsibility (appendix A).
+ */
+interface WriteInput {
+    /** The item written by a `put` (its key fields appear here). Mutable in W1. */
+    item?: Record<string, unknown>;
+    /** The target entity / key of an `update` / `delete`. Mutable in W1. */
+    key?: Record<string, unknown>;
+    /** The field changes of an `update`. Mutable in W1 (and when rewriting delete→update). */
+    changes?: Record<string, unknown>;
+    /** The per-call write options (`condition` / `retry` / `rederive` / …). Mutable in W1. */
+    options?: Record<string, unknown>;
+}
+/**
+ * W1 / W2 / W5 (logical-write-level) context. `before` (W1) may mutate
+ * {@link WriteCtx.input} and {@link WriteCtx.kind} (incl. the delete→update
+ * rewrite) and may `throw` to cancel the write (in a transaction, aborting ALL
+ * ops); `after` (W2) observes the committed change `{ oldImage?, newImage? }`;
+ * `onError` (W5) sees the logical-level failure and may recover by returning a
+ * value (symmetric with the read `onError`).
+ */
+interface WriteCtx extends CtxBase {
+    /** The logical write kind. Mutable in W1 (incl. delete→update rewrite). */
+    kind: WriteKind;
+    /** The mutable logical write payload (W1). */
+    input: WriteInput;
     /**
-     * Per-call throttle / transient-error retry override (issue #111). A
-     * {@link RetryPolicy} replaces the global policy for this call; `false` disables
-     * retry for this call. Omit to use the configured (or built-in default) policy.
+     * Present when this logical write is part of an atomic transaction
+     * (`DDBModel.transaction` / `mutate({ mode: 'transaction' })`). Its `id` symbol
+     * is shared by every logical op in the same atomic batch, so a hook can
+     * correlate the W1/W2 ops that compose one transaction. Absent for a
+     * non-transactional single-op write (and for `parallel`-mode ops, which are
+     * independent).
      */
-    retry?: RetryOverride;
+    readonly transaction?: {
+        readonly id: symbol;
+    };
 }
-interface UpdateOptions<T = unknown> {
-    condition?: WriteCondition<T>;
+/**
+ * The committed change handed to a W2 (`write.after`) hook. A
+ * `TransactWriteItems` returns no item images (spec §14), so within a transaction
+ * the images are best-effort (often absent); a single-op write may carry the
+ * pre-write `oldImage` when one was fetched.
+ */
+interface Change {
+    readonly oldImage?: Record<string, unknown>;
+    readonly newImage?: Record<string, unknown>;
+}
+/** One origin entry describing a logical op that contributed to a persist batch. */
+interface PersistOrigin {
+    readonly model: CtxModel;
+    readonly kind: WriteKind;
+}
+/**
+ * W3 / W4 / W5 (physical-persist-level) context — fires AFTER derivation, on the
+ * REAL composed batch. `before` (W3) may mutate {@link PersistCtx.items} (the
+ * fully composed `Put` / `Update` / `Delete` / `ConditionCheck` set: the user
+ * write(s) PLUS every derived edge / counter / GSI re-derivation / referential
+ * ConditionCheck) and may `throw` to abort the batch — mutations are honored on
+ * the ACTUAL send. `after` (W4) observes the executor's results; `onError` (W5)
+ * sees the persist-level failure and may recover by returning a value.
+ *
+ * In a transaction the persist hooks fire ONCE for the whole atomic batch; for a
+ * non-transactional single-op write `items` is the one-element `[{ Put|Update|Delete }]`.
+ */
+interface PersistCtx {
+    /** The fully composed physical batch (user + derived). Mutable in W3. */
+    items: TransactWriteExecItem[];
+    /** The logical ops that composed this batch (one per contributing W-level op). */
+    readonly origins: readonly PersistOrigin[];
+    /** The host-injected per-call context (`{}` when the write passed none). */
+    readonly context: RequestContext;
+    /** Scratch shared across this persist op's W3 → W4 → W5 phases. */
+    readonly state: Record<string, unknown>;
+    /** Present (with the shared `id`) when this batch is an atomic transaction. */
+    readonly transaction?: {
+        readonly id: symbol;
+    };
+}
+/**
+ * The write half of a registered {@link import('./types.js').Middleware}. Any
+ * subset of the write hook points may be set; an unset hook is skipped. All hooks
+ * are async-first — the runtime always `await`s, so sync and async hooks compose
+ * uniformly (see docs/middleware.md).
+ *
+ * @see docs/middleware.md (hook points W1–W5)
+ */
+interface WriteMiddleware {
+    /** W1 — logical write, before effect derivation. May mutate `ctx.input` / `ctx.kind`; `throw` cancels (in a tx, aborts all). */
+    before?(ctx: WriteCtx): void | Promise<void>;
+    /** W2 — logical write, after commit. Observes the committed `{ oldImage?, newImage? }`. */
+    after?(ctx: WriteCtx, change: Change): void | Promise<void>;
+    persist?: {
+        /** W3 — physical persist, after derivation, on the real batch. May mutate `ctx.items`; `throw` aborts the batch. */
+        before?(ctx: PersistCtx): void | Promise<void>;
+        /** W4 — physical persist, after the executor returns. Observes `results`. */
+        after?(ctx: PersistCtx, results: unknown): void | Promise<void>;
+        /**
+         * W5 (persist-level) — the persist failed. Runs LIFO. **Recover** by RETURNING
+         * a non-`undefined` value: the persist is treated as succeeded and the value is
+         * available to W4 (the first hook that returns a value wins and short-circuits
+         * the chain). Return `void` / `undefined` to decline — if no hook recovers, the
+         * original error rethrows (symmetric with the read `op.onError`).
+         */
+        onError?(ctx: PersistCtx, err: unknown): unknown;
+    };
+    /**
+     * W5 (logical-level) — the logical write failed. Runs LIFO. **Recover** by
+     * RETURNING a non-`undefined` value: it becomes the write's resolved value in
+     * place of throwing (the first hook that returns a value wins). Return `void` /
+     * `undefined` to decline — if no hook recovers, the original error rethrows
+     * (symmetric with the read `onError`).
+     */
+    onError?(ctx: WriteCtx, err: unknown): unknown;
+}
+
+/**
+ * Read middleware / hook public surface (issue #50, implemented for the read
+ * path in #138). The merged design is `docs/middleware.md`; this
+ * module implements the **read** hook points R1–R5 and their context objects.
+ *
+ * A {@link Middleware} is a host-only, runtime-registered object (registered via
+ * `DDBModel.use`) that runs at fixed seams in the read pipeline. Hooks are
+ * **never serialized** — they live only on the {@link import('../client/ClientManager.js').ClientManager}
+ * host-runtime singleton and never touch the planner / spec generator /
+ * `operations.json`, so the TS↔Python bridge (#48) is unaffected. Hooks are
+ * **unrestricted by intent**: a hook may observe, mutate `ctx`, `throw` to
+ * cancel, or return a replacement value. The library does NOT validate hook
+ * logic or impose semantics — see docs/middleware.md.
+ *
+ * @see docs/middleware.md
+ */
+
+/** A raw DynamoDB item (the shape R3 sees, per-op). */
+type Item = Record<string, unknown>;
+/**
+ * Host-injected, library-opaque per-call context — the value passed as
+ * `{ context }` on a read. Threaded unchanged to every R2/R3 fan-out op (issue
+ * #138). A read issued with no `{ context }` sees `{}`.
+ */
+type RequestContext = Record<string, unknown>;
+/**
+ * The `ModelStatic` shape the library hands to a hook's `ctx.model`. The
+ * concrete entity type is erased at the hook boundary (a hook is registered
+ * globally and may see any model), so it is the permissive
+ * `ModelStatic<DDBModel>`.
+ */
+type CtxModel = ModelStatic<DDBModel>;
+/** Fields shared by every read context object. */
+interface CtxBase {
+    /** The model the read targets. */
+    readonly model: CtxModel;
+    /** The host-injected per-call context (`{}` when the read passed none). */
+    readonly context: RequestContext;
+    /**
+     * Scratch space shared across this op's phases (R2 → R3 → R5 for one op, or
+     * R1 → R4 → R5 for the request). A fresh object per request context object;
+     * each fan-out op gets its own `state` ((docs/middleware.md) — siblings run
+     * concurrently, so a shared accumulator should live on a host object via
+     * `context`, updated commutatively).
+     */
+    readonly state: Record<string, unknown>;
+}
+/**
+ * The logical read kinds an {@link ReadRequestCtx} may carry (R1 / R4 / R5).
+ *
+ * Only the kinds the runtime actually emits are advertised. A `query` route in
+ * the read envelope delegates to {@link import('../operations/query.js').executeQuery}
+ * (kind `'query'`), a `list` route to {@link import('../operations/list.js').executeList}
+ * (kind `'list'`), so there is no distinct `'envelopeRoute'` kind. `batchGet`
+ * (`DDBModel.batchGet`, the public multi-key read primitive) fires request-level
+ * hooks since issue #142 — its R1/R4/R5 carry kind `'batchGet'`; each underlying
+ * physical `BatchGetItem` op fires R2/R3/R5 with op kind `'BatchGetItem'`.
+ */
+type ReadRequestKind = 'query' | 'list' | 'batchGet';
+/**
+ * The mutable request-level parameters R1 may observe / mutate. This is the
+ * declarative read input — `key` / `select` / and per-call read options — NOT a
+ * serialized spec. A hook may mutate these in place before key-resolution /
+ * planning (R1).
+ *
+ * For a `batchGet` read (kind `'batchGet'`, issue #142) there is no single
+ * `key` / `select` — the read spans multiple models/keys — so `key` / `select`
+ * are empty placeholders and the mutable batch input lives on
+ * {@link ReadParams.requests}; the library re-reads `requests` after R1 runs.
+ */
+interface ReadParams {
+    /** The key input (PK / GSI fields). Mutable in R1. Empty `{}` for `batchGet`. */
+    key: Record<string, unknown>;
+    /** The select / projection spec (plain object or a `project(...)` builder). Mutable in R1. Empty `{}` for `batchGet`. */
+    select: Record<string, unknown>;
+    /**
+     * The per-call read options (`consistentRead` / `maxDepth` / `limit` /
+     * `after` / `order` / `filter` / `updatable` / …) for this read kind. Mutable
+     * in R1. The library re-reads these after R1 runs.
+     */
+    options: Record<string, unknown>;
+    /**
+     * Only for a `batchGet` read (issue #142): the mutable list of batch-get
+     * requests (each `{ model, keys }`). A hook may add / drop / mutate requests
+     * or their keys in place before the underlying `BatchGetItem` ops are issued;
+     * the library re-reads this after R1 runs. `undefined` for `query` / `list`.
+     */
+    requests?: unknown[];
+}
+/**
+ * R1 / R4 / R5 (request-level) context. `before` (R1) may mutate
+ * {@link ReadParams} and may `throw` to cancel the whole read; `afterFetch` (R4)
+ * receives the final hydrated, relation-merged result and may return a
+ * replacement; `onError` (R5) sees a request-level failure.
+ */
+interface ReadRequestCtx extends CtxBase {
+    readonly kind: ReadRequestKind;
+    /** Mutable in R1 (request entry, before key-resolution / plan). */
+    params: ReadParams;
+}
+/** The physical op kinds an {@link ReadOpCtx} may carry (R2 / R3 / R5). */
+type ReadOpKind = 'GetItem' | 'Query' | 'BatchGetItem';
+/**
+ * R2 / R3 / R5 (op-level) context — fires for the root read AND for every
+ * relation fan-out fetch (incl. nested recursion). `before` (R2) may mutate
+ * {@link ReadOpCtx.operation} before it is sent and may `throw` to cancel;
+ * `afterFetch` (R3) receives the op's raw items and may return a replacement
+ * array; `onError` (R5) sees the op-level failure.
+ */
+interface ReadOpCtx extends CtxBase {
+    readonly kind: ReadOpKind;
+    /** The physical operation about to be sent. Mutable in R2. */
+    operation: DynamoDBOperation;
+    /**
+     * The relation path from the root read to this op: `[]` for the root read,
+     * `['orders']` for a direct relation fetch, `['orders', 'product']` for a
+     * nested one. Lets a hook scope behavior to a specific fan-out leg.
+     */
+    readonly relationPath: readonly string[];
+}
+/**
+ * A registered read middleware object. Any subset of the read hook points may
+ * be set; an unset hook is simply skipped. All hooks may be synchronous or
+ * return a `Promise` — the runtime always `await`s (async-first, see docs/middleware.md
+ * "sync / async").
+ *
+ * @see docs/middleware.md (the write hooks W1–W5 are a later phase)
+ */
+interface Middleware {
+    /** Optional name (for host-side debugging / ordering introspection). */
+    name?: string;
+    read?: {
+        /** R1 — request entry, before key-resolution / plan. May mutate `ctx.params`; `throw` cancels. */
+        before?(ctx: ReadRequestCtx): void | Promise<void>;
+        /** R4 — final hydrated, relation-merged result. Returns the (possibly replaced) result. */
+        afterFetch?<T>(ctx: ReadRequestCtx, result: T): T | Promise<T>;
+        op?: {
+            /** R2 — each physical op, before send. May mutate `ctx.operation`; `throw` cancels. */
+            before?(ctx: ReadOpCtx): void | Promise<void>;
+            /** R3 — each physical op's raw items. Returns the (possibly replaced) items. */
+            afterFetch?(ctx: ReadOpCtx, items: Item[]): Item[] | Promise<Item[]>;
+            /**
+             * R5 (op-level) — a physical op failed. Runs LIFO. **Recover** by RETURNING
+             * an `Item[]`: those become this op's items and the read pipeline continues
+             * (the first hook that returns a value wins and short-circuits the chain).
+             * Return `void` / `undefined` to decline — if no hook recovers, the original
+             * error rethrows. (see docs/middleware.md — hooks are unrestricted.)
+             */
+            onError?(ctx: ReadOpCtx, err: unknown): void | Item[] | Promise<void | Item[]>;
+        };
+        /**
+         * R5 (request-level) — the read failed. Runs LIFO. **Recover** by RETURNING a
+         * value: it becomes the read's result in place of throwing (the first hook
+         * that returns a non-`undefined` value wins and short-circuits the chain).
+         * Return `void` / `undefined` to decline — if no hook recovers, the original
+         * error rethrows. The returned value is the read's resolved value verbatim, so
+         * its shape is the host's responsibility (e.g. `null` / an item for `query`, a
+         * `{ items, cursor }` for `list`).
+         */
+        onError?(ctx: ReadRequestCtx, err: unknown): unknown;
+    };
+    /**
+     * The write hook points W1–W5 (issue #50 write path, #139). Any subset may be
+     * set; one registered object may carry read and/or write hooks. See
+     * {@link WriteMiddleware}.
+     */
+    write?: WriteMiddleware;
+}
+
+/**
+ * A top-level `select` may be either a plain projection (`SelectableOf<T>`) or
+ * a {@link SelectBuilder} produced by `Model.project(...)`. The builder is
+ * model-bound to `T`, so its `.filter(...)` is typed against the full entity.
+ */
+type SelectSpec<T> = SelectableOf<T> | SelectBuilder<T, any>;
+/**
+ * Resolves the projection `S` from a top-level select spec (plain object or
+ * builder), so the result type is computed identically for both forms.
+ */
+type ProjectionOf<T, Sel> = Sel extends SelectableOf<T> ? Sel : SelectOf<Sel>;
+/**
+ * Default model-class constraint used when a `ModelStatic` is referenced
+ * without its concrete constructor type (e.g. `ModelStatic<UserModel>`).
+ *
+ * In that case key/option types fall back to permissive shapes so existing
+ * usages keep compiling, while the precise inference is available when the
+ * constructor type is supplied (as it is from `DDBModel.asModel()`).
+ */
+type AnyModelClass = abstract new (...args: any[]) => DDBModel;
+/**
+ * The accepted PK / GSI key type for `list()` / `explain()`.
+ *
+ * `list`/`explain` issue a DynamoDB *Query* against a partition, so a **partial**
+ * key (partition-key subset of a PK/GSI input) is accepted — the sort-key tail
+ * is optional. This matches the runtime key resolver. `query()` stays strict via
+ * {@link QueryKey}. Derived from the model class when available, otherwise
+ * permissive.
+ */
+type ListKey<C> = [C] extends [AnyModelClass] ? PartialQueryKeyOf<C> : Record<string, unknown>;
+/**
+ * The accepted key type for `query()` — only keys guaranteed to return a
+ * single item (PK + unique GSIs). Derived from the model class when available.
+ */
+type QueryKey<C> = [C] extends [AnyModelClass] ? UniqueQueryKeyOf<C> : Record<string, unknown>;
+/**
+ * The accepted key type for `delete()` (PK only). Derived from the model
+ * class when available.
+ */
+type DeleteKey<C> = [C] extends [AnyModelClass] ? PrimaryKeyOf<C> : Record<string, unknown>;
+/**
+ * The accepted *explicit* key type for `update()` — the base-table primary key
+ * only. DynamoDB `UpdateItem` can target an item solely by its base-table PK
+ * (GSI-based updates are impossible), so this is `PrimaryKeyOf<C>`, not
+ * `UniqueQueryKeyOf<C>`. Derived from the model class when available.
+ */
+type UpdateExplicitKey<C> = [C] extends [AnyModelClass] ? PrimaryKeyOf<C> : Record<string, unknown>;
+/**
+ * Options accepted by `list()` (third argument). The projection is supplied as
+ * the separate second `select` argument, symmetric with `query()`.
+ *
+ * - `filter` is the declarative server-side DynamoDB FilterExpression, typed
+ *   against the full Entity `T` (may reference unprojected attributes). For
+ *   arbitrary JS-only post-load filtering, narrow with `filter` then apply
+ *   `result.items.filter(...)` (already fully typed).
+ *
+ * @typeParam T - The Entity type.
+ */
+type ListCallOptions<T> = {
+    limit?: number;
+    after?: string;
+    order?: 'ASC' | 'DESC';
+    filter?: FilterInput<T>;
+    /**
+     * When `true`, each returned item is updatable: it carries its resolved
+     * base-table key as a hidden, non-enumerable property and is branded
+     * `& Updatable`, so it can be passed straight back to `updateItem()`.
+     */
+    updatable?: boolean;
+    /**
+     * Host-injected per-call read context (issue #50 / #138) — passed to every
+     * registered read hook as `ctx.context` and threaded to every relation
+     * fan-out op. A host-language value, never serialized (the bridge #48 is
+     * unaffected). Absent ⇒ `{}`.
+     */
+    context?: RequestContext;
+};
+/**
+ * Public, type-inferring API surface produced by {@link DDBModel.asModel}.
+ *
+ * @typeParam T - The Entity type of the model.
+ * @typeParam C - The model class constructor type. Supplied automatically by
+ *   `asModel()`; when omitted, key/option types widen to permissive shapes so
+ *   that `ModelStatic<T>` keeps compiling for callers that only name the entity.
+ */
+interface ModelStatic<T extends DDBModel, C = unknown> {
+    /**
+     * Type-safe column references for this model, one per scalar field. Used by
+     * the `cond` raw escape hatch (`cond\`${Model.col.age} > ${18}\``). Each
+     * column carries its declared type and is branded to this model, so passing
+     * another model's column into this model's `cond` is a compile error.
+     */
+    readonly col: ColumnMap<T>;
+    /**
+     * Begin a model-bound, top-level select builder. The entity type `T` is fixed
+     * by this model and the projection `S` is inferred from the argument.
+     * `.filter(...)` is typed `FilterInput<T>` against the full entity.
+     *
+     * @example
+     * ```ts
+     * Order.list({ userId: 'u' },
+     *   Order.project({ orderId: true, amount: true })
+     *     .filter({ status: 'confirmed', amount: { gt: 100 } }),
+     * );
+     * ```
+     */
+    project<const S extends SelectableOf<T>>(select: S): SelectBuilder<T, S>;
+    /**
+     * Begin a model-bound relation select builder for use as a relation field's
+     * value inside a parent `select`. `T` is this (relation target) model's
+     * entity type; `S` is inferred from the argument. Same model-bound inference
+     * as {@link ModelStatic.project}, plus per-relation pagination
+     * (`limit` / `after` / `order`).
+     *
+     * @example
+     * ```ts
+     * User.query({ userId: 'u' }, {
+     *   name: true,
+     *   orders: Order.relation({ orderId: true, amount: true })
+     *     .filter({ amount: { gt: 100 } }),
+     * });
+     * ```
+     */
+    relation<const S extends SelectableOf<T>>(select: S): RelationBuilder<T, S>;
+    /**
+     * Fetch a single item by a unique key and **hydrate** the plain result onto a
+     * host-side object (issue #53). The `hydrate` factory receives the fully-built
+     * plain object — `QueryResult<T, ProjectionOf<T, Sel>>`, typed against exactly
+     * the `select`ed fields — and its return type `R` becomes the read's return
+     * type (subsuming a `queryAs(Ctor, …)` style: `hydrate: (raw) => new Ctor(raw)`).
+     *
+     * Applied as the **final after-fetch step**, only to a present item: a missing
+     * item resolves to `null` and the factory is NOT invoked (hence `R | null`). A
+     * throw from the factory propagates verbatim as the read's rejection.
+     *
+     * Host-runtime ONLY: the factory is a host-language closure, never serialized
+     * into the SSoT / `operations.json`, so it does not impede the bridge (#48).
+     */
+    query<Sel extends SelectSpec<T>, R>(key: QueryKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options: {
+        consistentRead?: boolean;
+        maxDepth?: number;
+        updatable?: boolean;
+        hydrate: (raw: QueryResult<T, ProjectionOf<T, Sel>>) => R;
+        /** Host-injected per-call read context (issue #50 / #138); see {@link ListCallOptions.context}. */
+        context?: RequestContext;
+    }): Promise<R | null>;
+    /**
+     * Fetch a single item by a unique key, requesting an **updatable** result.
+     * The returned item (when non-null) carries its resolved base-table key as a
+     * hidden, non-enumerable property and is branded `& Updatable`, so it can be
+     * passed straight back to {@link ModelStatic.updateItem} — even for a partial
+     * `select` or a GSI-based query. Do not spread / clone / JSON round-trip the
+     * result before updating: that drops both the hidden key and the brand.
+     */
+    query<Sel extends SelectSpec<T>>(key: QueryKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options: {
+        consistentRead?: boolean;
+        maxDepth?: number;
+        updatable: true;
+        /** Host-injected per-call read context (issue #50 / #138); see {@link ListCallOptions.context}. */
+        context?: RequestContext;
+    }): Promise<(QueryResult<T, ProjectionOf<T, Sel>> & Updatable) | null>;
+    /**
+     * Fetch a single item by a unique key. The return type contains only the
+     * selected fields, derived from `select`.
+     */
+    query<Sel extends SelectSpec<T>>(key: QueryKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options?: {
+        consistentRead?: boolean;
+        maxDepth?: number;
+        updatable?: false;
+        /** Host-injected per-call read context (issue #50 / #138); see {@link ListCallOptions.context}. */
+        context?: RequestContext;
+    }): Promise<QueryResult<T, ProjectionOf<T, Sel>> | null>;
     /**
-     * Per-call throttle / transient-error retry override (issue #111). A
-     * {@link RetryPolicy} replaces the global policy for this call; `false` disables
-     * retry for this call.
+     * List items for a partition, symmetric with {@link ModelStatic.query}:
+     * `list(key, select, options?)`. `select` (the second argument) may be a plain
+     * projection or a `project(...)` builder. `options.filter` is the declarative
+     * server-side FilterExpression typed against the full Entity. Returned items
+     * contain only the selected fields.
      */
-    retry?: RetryOverride;
+    list<Sel extends SelectSpec<T>>(key: ListKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options: ListCallOptions<T> & {
+        updatable: true;
+    }): Promise<{
+        items: (QueryResult<T, ProjectionOf<T, Sel>> & Updatable)[];
+        cursor: string | null;
+    }>;
+    list<Sel extends SelectSpec<T>>(key: ListKey<C>, select: Sel & StrictSelectSpec<T, Sel>, options?: ListCallOptions<T>): Promise<{
+        items: QueryResult<T, ProjectionOf<T, Sel>>[];
+        cursor: string | null;
+    }>;
+    explain<Sel extends SelectSpec<T>>(key: ListKey<C>, options?: {
+        select?: Sel & StrictSelectSpec<T, Sel>;
+        limit?: number;
+        after?: string;
+        order?: 'ASC' | 'DESC';
+        consistentRead?: boolean;
+        filter?: FilterInput<T>;
+    }): ExecutionPlan;
+    putItem(item: EntityInput<T>, options?: WriteOptions<T>): Promise<void>;
     /**
-     * How to re-derive a GSI key whose composing fields are changed but **not all**
-     * available from `{ ...key, ...changes }` (issue #115).
+     * Update an item identified by its **explicit base-table primary key**
+     * (`PrimaryKeyOf<C>`). This is the canonical form — it requires the key input
+     * up front, so it can never silently target the wrong item.
      *
-     * - **unset (default)** — refuse with an explicit error rather than let the
-     *   index silently rot. The error names the index, the changed field, and the
-     *   missing field(s). The happy path (all composing fields available) re-derives
-     *   in the SAME `UpdateExpression` and is unaffected by this option.
-     * - `'read-modify-write'` — read the current item, merge `{ ...item, ...changes }`,
-     *   re-derive every affected GSI key from the merged image, and write back under
-     *   an optimistic condition (the item must still exist / be unchanged). This costs
-     *   one extra read and is NOT atomic with the original update, but always re-derives
-     *   correctly.
+     * @example `await User.updateItem({ userId: 'alice' }, { status: 'disabled' });`
      */
-    rederive?: 'read-modify-write';
-}
-interface DeleteOptions<T = unknown> {
-    condition?: WriteCondition<T>;
+    updateItem(key: UpdateExplicitKey<C>, changes: Partial<T>, options?: WriteOptions<T>): Promise<void>;
     /**
-     * Per-call throttle / transient-error retry override (issue #111). A
-     * {@link RetryPolicy} replaces the global policy for this call; `false` disables
-     * retry for this call.
+     * Update an item using an **updatable** entity obtained from
+     * `query(..., { updatable: true })` / `list(..., { updatable: true })`. The
+     * hidden base-table key carried by that entity is used directly, so this
+     * works even for a partial `select` or a GSI-based read.
+     *
+     * Pass the entity as-is. A spread / clone / JSON round-trip drops both the
+     * brand (rejected here at compile time) and the hidden key (rejected at
+     * runtime), preventing an accidental wrong-item update.
      */
-    retry?: RetryOverride;
-}
-
-interface PutInput {
-    TableName: string;
-    Item: Record<string, unknown>;
-    ConditionExpression?: string;
-    ExpressionAttributeNames?: Record<string, string>;
-    ExpressionAttributeValues?: Record<string, unknown>;
+    updateItem(entity: Partial<T> & Updatable, changes: Partial<T>, options?: WriteOptions<T>): Promise<void>;
+    deleteItem(key: DeleteKey<C>, options?: WriteOptions<T>): Promise<void>;
 }
-declare function buildPutInput(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): PutInput;
-declare function executePut(modelClass: Function, item: Record<string, unknown>, options?: PutOptions): Promise<void>;
 
 type TransactWriteItemInput = {
     Put: PutInput;
@@ -1218,9 +1570,32 @@ interface TransactCaptureMeta {
     };
     newItem?: Record<string, unknown>;
 }
+/**
+ * One recorded logical write op of an imperative {@link TransactionContext}
+ * (issue #139). Captured at `tx.put/update/delete` call time so the write hooks
+ * W1 (`write.before`) can run on each op — and rebuild its physical item from the
+ * possibly-mutated input — before the batch composes / commits. A `conditionCheck`
+ * records NO logical op (it is a read-only assertion, not a logical write).
+ */
+interface LogicalWriteOp {
+    kind: WriteKind;
+    modelClass: Function;
+    item?: Record<string, unknown>;
+    key?: Record<string, unknown>;
+    changes?: Record<string, unknown>;
+    options?: PutOptions & UpdateOptions & DeleteOptions;
+}
 declare class TransactionContext {
     private readonly items;
     private readonly captureMeta;
+    /**
+     * The logical write ops, parallel to {@link items} but EXCLUDING `conditionCheck`
+     * entries (those are read-only assertions, recorded only in `items`). Used by the
+     * write-hook path (#139) to run W1 on each logical op and recompose the batch.
+     * A `null` entry marks an `items` slot that has no logical op (a ConditionCheck),
+     * so the eager and logical arrays can be re-aligned at commit.
+     */
+    private readonly logicalOps;
     get itemCount(): number;
     put(model: ModelStatic<DDBModel>, item: Record<string, unknown>, options?: PutOptions): void;
     update(model: ModelStatic<DDBModel>, entity: Record<string, unknown>, changes: Record<string, unknown>, options?: UpdateOptions): void;
@@ -1242,16 +1617,35 @@ declare class TransactionContext {
     }): void;
     /** @internal */
     getTransactItems(): TransactWriteItemInput[];
+    /** @internal — the recorded logical write ops (issue #139 W1), `null` per ConditionCheck slot. */
+    getLogicalOps(): readonly (LogicalWriteOp | null)[];
     /** @internal — capture descriptors for the write-capture seam (issue #72). */
     getCaptureMeta(): TransactCaptureMeta[];
     private assertWithinLimit;
 }
-declare function executeTransaction(fn: (tx: TransactionContext) => void | Promise<void>): Promise<void>;
+declare function executeTransaction(fn: (tx: TransactionContext) => void | Promise<void>, options?: {
+    context?: RequestContext;
+}): Promise<void>;
 
 interface BatchGetRequest {
     model: ModelStatic<DDBModel>;
     keys: Record<string, unknown>[];
 }
+/**
+ * Per-call options for {@link DDBModel.batchGet} (issue #142).
+ */
+interface BatchGetOptions {
+    /**
+     * Host-injected per-call read context (issue #50 / #138 / #142) — exposed to
+     * every read hook (R1/R4/R5 at the `batchGet` request level, R2/R3/R5 on each
+     * underlying `BatchGetItem` op) as `ctx.context`, and threaded UNCHANGED to
+     * every physical op so a global hook (e.g. a tenant-scope R2 FilterExpression
+     * or an observability probe) applies across the whole multi-key batch read. A
+     * host-language value, NEVER serialized into the SSoT / `operations.json` (the
+     * bridge #48 is unaffected). Absent ⇒ `{}`.
+     */
+    context?: RequestContext;
+}
 interface BatchPutRequest {
     type: 'put';
     model: ModelStatic<DDBModel>;
@@ -1270,7 +1664,23 @@ declare class BatchGetResult {
     constructor(groups: Map<Function, Record<string, unknown>[]>);
     get<T extends DDBModel>(model: ModelStatic<T>): Partial<T>[];
 }
-declare function executeBatchGet(requests: BatchGetRequest[]): Promise<BatchGetResult>;
+/**
+ * The multi-key, multi-model batch-read core (issue #142). Wraps the request
+ * entry in the request-level read hooks R1 (`read.before`) / R4
+ * (`read.afterFetch`) / R5 (`read.onError`) with request kind `'batchGet'`, and
+ * each underlying physical `BatchGetItem` op (per table/chunk) in R2/R3/R5 via
+ * {@link executeBatchGetForTable}. The read middleware runtime is built ONCE here
+ * from `options.context` and threaded UNCHANGED to every op, so a global hook
+ * (e.g. a tenant-scope R2 FilterExpression) applies across the whole batch.
+ *
+ * R1 sees the mutable batch `requests` on `ctx.params.requests`; the library
+ * re-reads them after R1 runs, so a hook may add / drop / mutate requests before
+ * any op is issued and may `throw` to cancel the whole batch. R4 may transform /
+ * replace the assembled {@link BatchGetResult}; R5 may recover by returning one.
+ * With no middleware registered the shared `NO_MIDDLEWARE` runtime keeps the hot
+ * path unchanged (the zero-overhead fast path).
+ */
+declare function executeBatchGet(requests: BatchGetRequest[], options?: BatchGetOptions): Promise<BatchGetResult>;
 declare function executeBatchWrite(requests: BatchWriteRequest[]): Promise<void>;
 
 /**
@@ -1559,6 +1969,259 @@ interface DeriveEffect {
     /** The amount to add (for an increment). */
     readonly amount: number;
 }
+/**
+ * A model lifecycle event that triggers a maintenance effect, expressed as an
+ * `Entity.event` string — the source entity's class name, a dot, then one of the
+ * lifecycle events. The three events mirror {@link WriteLifecyclePhase}
+ * (`create` / `update` / `remove`) in past-tense event form, so a maintenance
+ * effect is keyed by *what happened* to the source row.
+ *
+ * The string is **branded** ({@link MaintainTrigger}) so a raw `string` is not
+ * accepted where a validated trigger is required; construct one with
+ * {@link maintainTrigger}, which rejects a malformed value.
+ *
+ * @example `'Post.created'`, `'User.updated'`, `'Comment.removed'`
+ */
+type MaintainEvent = 'created' | 'updated' | 'removed';
+/** The brand carried by a validated {@link MaintainTrigger}. */
+declare const MAINTAIN_TRIGGER_BRAND: unique symbol;
+/**
+ * A validated `Entity.event` maintenance trigger string (e.g. `'Post.created'`).
+ * Branded so it is told apart from a raw `string`; build one with
+ * {@link maintainTrigger}. The shape is `${EntityName}.${MaintainEvent}` where
+ * `EntityName` is a non-empty identifier-ish token.
+ */
+type MaintainTrigger = `${string}.${MaintainEvent}` & {
+    readonly [MAINTAIN_TRIGGER_BRAND]: true;
+};
+/**
+ * Construct a validated {@link MaintainTrigger} from an `Entity.event` string.
+ * Rejects a value that is not a non-empty entity name followed by `.created` /
+ * `.updated` / `.removed`, so an invalid trigger is refused at construction time
+ * (the AC's "invalid trigger string is rejected"). The brand is a compile-time
+ * marker only; the returned value is the input string verbatim.
+ *
+ * @throws if `value` is not a well-formed `Entity.event` trigger string.
+ */
+declare function maintainTrigger(value: string): MaintainTrigger;
+/** Runtime guard: is `value` a well-formed {@link MaintainTrigger} string? */
+declare function isMaintainTrigger(value: unknown): value is MaintainTrigger;
+/**
+ * A projection transform op (issue #120, 論点3 = 関数形): the function-form
+ * `w.transform(path, op, ...args)` is the **primary** authoring surface (there is
+ * no string DSL). The initial op set is:
+ *
+ * - `identity` — copy the source path through unchanged (no args).
+ * - `preview` — keep a length-bounded preview of the source value; `n` is the
+ *   bound (`w.transform('$.body', 'preview', 200)`).
+ *
+ * New ops extend this union (and {@link ProjectionTransform}'s `args` shape) as
+ * the maintenance graph (#124) needs them.
+ */
+type ProjectionTransformOp = 'identity' | 'preview';
+/**
+ * One entry in a maintenance projection map: a `w.transform(path, op, ...args)`
+ * IR node binding a source {@link EffectPath} to a target attribute through a
+ * {@link ProjectionTransformOp}. `args` carries the op's positional arguments
+ * (e.g. `preview`'s length bound); `identity` carries none.
+ *
+ * The function form is the only authoring surface (no string DSL); the node is a
+ * plain branded record so the maintenance graph (#124) and compile injection
+ * (#125) can read it without retaining a closure.
+ */
+interface ProjectionTransform {
+    readonly kind: 'transform';
+    /** The path-rooted source value (`$.input.*` / `$.entity.*`). */
+    readonly path: EffectPath;
+    /** The transform op applied to the source value. */
+    readonly op: ProjectionTransformOp;
+    /** The op's positional arguments (e.g. `[200]` for `preview`); empty for `identity`. */
+    readonly args: readonly unknown[];
+}
+/**
+ * A maintenance **projection map**: target attribute name → its
+ * {@link ProjectionTransform}. Generalizes the way {@link DeriveEffect} names a
+ * single derived `attribute`, to a whole projected row / collection item.
+ */
+type ProjectionMap = Readonly<Record<string, ProjectionTransform>>;
+/**
+ * Standalone authoring helper for a `preview` {@link ProjectionTransform}: keep a
+ * length-bounded preview of the source `path` (the first `n` characters). This is
+ * the recorder-free counterpart to `w.transform(path, 'preview', n)` — used where
+ * there is no {@link WriteRecorder} `w`, the relation-options decorator arguments
+ * (epic #118 §5.2 / issue #121, e.g. `projection: { textPreview: preview('body',
+ * 120) }`). It produces the **same** IR node as `w.transform` (both route through
+ * {@link makeProjectionTransform}), so the two surfaces never diverge.
+ *
+ * @param path The source value the preview is taken of (a projection source path).
+ * @param n The preview length bound (a positive integer).
+ * @throws if `n` is not a positive integer.
+ */
+declare function preview(path: EffectPath, n: number): ProjectionTransform;
+/**
+ * Standalone authoring helper for an `identity` {@link ProjectionTransform}: copy
+ * the source `path` through unchanged. The recorder-free counterpart to
+ * `w.transform(path, 'identity')`. In relation-options `projection` maps a bare
+ * `string` path is the idiomatic identity shorthand; this helper is provided for
+ * symmetry / when an explicit IR node is wanted. Routes through
+ * {@link makeProjectionTransform} so it is structurally identical to the recorder
+ * form.
+ *
+ * @param path The source value copied through unchanged.
+ */
+declare function identity(path: EffectPath): ProjectionTransform;
+/**
+ * The **path** a maintenance write travels (shared vocabulary, epic #118 A/B
+ * reconciliation — RFC §5.1 / issue #121 are the authority). `mutation` lands the
+ * maintenance write **synchronously**, in the same `TransactWriteItems` as the
+ * source mutation; `stream` defers it to the **asynchronous** Streams path. This
+ * is the path axis, NOT a write-reconciliation axis.
+ *
+ * NOTE: A(#120) previously defined `updateMode` as an *invented* write-reconcile
+ * axis (`'overwrite' | 'ifNewer'`); that axis is **removed for Phase 1** (論点2=b
+ * fixes "1 mutation × 1 target row = 1 effect", so no reconcile is needed) and the
+ * name is reclaimed for the path vocabulary above. A reconcile axis may be
+ * reintroduced later under a *different* name if a future phase needs it.
+ */
+type MaintainUpdateMode = 'mutation' | 'stream';
+/**
+ * The read/write consistency a maintenance effect is realized under (shared
+ * vocabulary, epic #118 A/B reconciliation — RFC §5.1 / issue #121 are the
+ * authority). `transactional` requires the maintenance write to land in the same
+ * transaction as the source write; `eventual` (the default the consumers assume
+ * when omitted) lets it lag. A's earlier `'strong'` value is **retired** in favor
+ * of `'transactional'`.
+ */
+type MaintainConsistency = 'transactional' | 'eventual';
+/**
+ * A **snapshot** maintenance effect (issue #120): on a {@link MaintainTrigger}
+ * the source's {@link project} is mirrored into a single target row resolved by
+ * {@link targetFactory} + {@link keys}. Generalizes {@link DeriveEffect} from a
+ * single scalar `ADD`/`SET` to a projected row. Consumed by the maintenance graph
+ * (#124) and compile injection (#125); #120 defines the type only.
+ */
+interface SnapshotEffect {
+    readonly kind: 'snapshot';
+    /** The lifecycle event of the source entity that drives the snapshot. */
+    readonly trigger: MaintainTrigger;
+    /** Resolves the target entity whose row holds the snapshot. */
+    readonly targetFactory: () => new (...args: unknown[]) => unknown;
+    /** The key binding of the target row (path-rooted values). */
+    readonly keys: Readonly<Record<string, EffectPath>>;
+    /** The projection map: target attribute → `w.transform(...)` IR. */
+    readonly project: ProjectionMap;
+    /** The path the write travels — synchronous `mutation` tx or async `stream`. */
+    readonly updateMode?: MaintainUpdateMode;
+    /** The consistency the write lands under (default `eventual`). */
+    readonly consistency?: MaintainConsistency;
+}
+/**
+ * Options for the bounded collection a {@link CollectionEffect} maintains: the
+ * target {@link field} that holds the collection, an optional {@link maxItems}
+ * cap (oldest items are evicted past it), and an optional {@link orderBy} source
+ * path the items are ordered by.
+ */
+interface CollectionOptions {
+    /** The target attribute that holds the maintained collection. */
+    readonly field: string;
+    /** Cap on the collection size; items past it are evicted (unbounded if omitted). */
+    readonly maxItems?: number;
+    /** A path-rooted source value the collection is ordered by (e.g. `$.entity.createdAt`). */
+    readonly orderBy?: EffectPath;
+}
+/**
+ * A **collection** maintenance effect (issue #120): on a {@link MaintainTrigger}
+ * the source's {@link project} is appended as an item into the bounded collection
+ * named by {@link collection} on the target row resolved by {@link targetFactory}
+ * + {@link keys}. Generalizes {@link DeriveEffect} to a bounded list projection.
+ * Consumed by the maintenance graph (#124) and compile injection (#125); #120
+ * defines the type only.
+ */
+interface CollectionEffect {
+    readonly kind: 'collection';
+    /** The lifecycle event of the source entity that drives the collection write. */
+    readonly trigger: MaintainTrigger;
+    /** Resolves the target entity whose row holds the collection. */
+    readonly targetFactory: () => new (...args: unknown[]) => unknown;
+    /** The key binding of the target row (path-rooted values). */
+    readonly keys: Readonly<Record<string, EffectPath>>;
+    /** The projection map for each collection item: attribute → `w.transform(...)` IR. */
+    readonly project: ProjectionMap;
+    /** The bounded-collection options (`field` / `maxItems` / `orderBy`). */
+    readonly collection: CollectionOptions;
+    /** The path the write travels — synchronous `mutation` tx or async `stream`. */
+    readonly updateMode?: MaintainUpdateMode;
+    /** The consistency the write lands under (default `eventual`). */
+    readonly consistency?: MaintainConsistency;
+}
+/**
+ * The aggregation a {@link CounterEffect} maintains (Epic #118 §5.2 counter /
+ * latest preset; issue #141). The function-form IR `count()` / `max(field)` the
+ * `@aggregate` value helpers build, lifted into the maintenance IR:
+ *
+ * - `count` — the cardinality of the matched source rows: a `created` trigger
+ *   adds `+1`, a `removed` trigger adds `-1` (the {@link CounterEffect.delta}).
+ * - `max` — the running maximum of a named source `field`. A synchronous
+ *   transactional max cannot be expressed as a concurrency-safe single-item
+ *   `UpdateExpression` (a conditional `SET` whose guard fails would roll back the
+ *   *source* write that legitimately happened), so Phase 1 records the IR but the
+ *   compile injection (#141) rejects it for the synchronous `mutation` path —
+ *   `max` is the asynchronous stream path (#130, Phase 2). The op is kept here so
+ *   the IR is complete and the reject is precise.
+ */
+type CounterAggregate = {
+    readonly op: 'count';
+} | {
+    readonly op: 'max';
+    readonly field: string;
+};
+/**
+ * A **counter** maintenance effect (Epic #118 §5.2 counter preset; issue #141): on
+ * a {@link MaintainTrigger} a scalar aggregate on a single target row resolved by
+ * {@link targetFactory} + {@link keys} is kept in sync with the source entity's
+ * lifecycle. Where {@link SnapshotEffect} mirrors a projection and
+ * {@link CollectionEffect} appends an item, a counter applies an atomic scalar
+ * `ADD` — the maintenance-pipeline generalization of the self-lifecycle
+ * {@link DeriveEffect} (`w.increment`, #85), but driven by a CROSS-entity
+ * `maintainedOn` trigger rather than the written entity's own lifecycle.
+ *
+ * For `value.op === 'count'` the {@link delta} is the signed amount the trigger
+ * applies (`+1` on `created`, `-1` on `removed`); the maintenance graph (#124)
+ * derives it from the trigger event. Two counter effects targeting the SAME row in
+ * one mutation MERGE (the symmetric-ADD collapse #92), unlike snapshot/collection
+ * which reject a same-row collision — an `ADD` is commutative.
+ *
+ * Consumed by the maintenance graph (#124, `em.aggregates` walk) and the compile
+ * injection (#141, `DerivedMaintainWrite` of `kind: 'counter'`).
+ */
+interface CounterEffect {
+    readonly kind: 'counter';
+    /** The lifecycle event of the source entity that drives the counter. */
+    readonly trigger: MaintainTrigger;
+    /** Resolves the target entity whose row holds the counter scalar. */
+    readonly targetFactory: () => new (...args: unknown[]) => unknown;
+    /** The key binding of the target row (path-rooted values). */
+    readonly keys: Readonly<Record<string, EffectPath>>;
+    /** The target attribute the aggregate scalar is written to (e.g. `postCount`). */
+    readonly attribute: string;
+    /** The aggregation maintained (`count()` / `max(field)`). */
+    readonly value: CounterAggregate;
+    /**
+     * For `value.op === 'count'`, the signed `ADD` delta this trigger applies
+     * (`+1` created / `-1` removed). Absent for `max` (not realized synchronously).
+     */
+    readonly delta?: number;
+    /** The path the write travels — synchronous `mutation` tx or async `stream`. */
+    readonly updateMode?: MaintainUpdateMode;
+    /** The consistency the write lands under (default `eventual`). */
+    readonly consistency?: MaintainConsistency;
+}
+/**
+ * The union of maintenance effects a {@link SnapshotEffect}, {@link CollectionEffect},
+ * or {@link CounterEffect} can be. The shared IR the maintenance graph (#124) and
+ * compile injection (#125 snapshot/collection, #141 counter) consume.
+ */
+type MaintainEffect = SnapshotEffect | CollectionEffect | CounterEffect;
 /**
  * A domain event (proposal §2 `emits`): an outbox `Put` drained to Streams /
  * `src/cdc/`. Derived by #87 — stored opaquely here.
@@ -1667,6 +2330,21 @@ interface WriteRecorder {
     deleteEdge(target: () => new (...args: unknown[]) => unknown, relationProperty: string): EdgeEffect;
     /** Declare a derived / cascading update (§2 `derive`; derived #85). */
     increment(target: () => new (...args: unknown[]) => unknown, keys: Readonly<Record<string, EffectPath>>, attribute: string, amount: number): DeriveEffect;
+    /**
+     * Build a projection transform IR node (issue #120, 関数形): the primary
+     * function-form authoring surface for a maintenance projection map entry. The
+     * initial ops are `identity` (no args — copy the source path through) and
+     * `preview` (one numeric arg — keep a length-bounded preview). There is no
+     * string DSL. The returned {@link ProjectionTransform} is consumed by the
+     * maintenance graph (#124) / compile injection (#125).
+     *
+     * NOTE (issue #120 scope): the escape-hatch recorders that *attach* a
+     * {@link SnapshotEffect} / {@link CollectionEffect} to a lifecycle
+     * (`w.snapshotInto` / `w.captureInto`) and the `LifecycleEffects.maintain`
+     * wiring are **Phase 2** and are intentionally NOT part of this recorder.
+     */
+    transform(path: EffectPath, op: 'identity'): ProjectionTransform;
+    transform(path: EffectPath, op: 'preview', n: number): ProjectionTransform;
     /** Declare a domain event (§2 `emits`; derived #87). */
     event(name: string, payload: Readonly<Record<string, EffectPath>>): EmitEffect;
     /** Declare an idempotency guard (§2 `idempotency`; derived #87). */
@@ -1990,6 +2668,163 @@ declare function mutation(name: string, body: MutationBody): CommandPlan;
  */
 declare const definePlan: typeof mutation;
 
+/**
+ * Maintenance graph builder (Epic #118 issue #124 — the RFC B-案 core).
+ *
+ * ## What this module is
+ *
+ * A relation may declare a **maintenance** side via its relation options
+ * (issue #121, the B work): `write.maintainedOn` lists the cross-entity
+ * lifecycle triggers (`"<Entity>.<event>"`, e.g. `"Post.created"`) that should
+ * keep the relation's materialized shape in sync, and `projection` declares how
+ * the source entity is projected into that shape. This module walks every
+ * registered model (`MetadataRegistry.getAll()`), reads those relation-side
+ * declarations, and builds an **index**:
+ *
+ *     trigger source entity × lifecycle event (created/updated/removed)
+ *         → list of maintenance effects to apply
+ *
+ * That index is exactly the question the compile-injection step (#125) asks of
+ * a mutation: "this mutation `created` a `Post` — what must be maintained?". This
+ * module answers *which* effect fires for *which* trigger, and validates that
+ * every declared effect is realizable (round-trips with the read side); it does
+ * **not** inject anything into the compiler — see "Scope" below.
+ *
+ * ## Input is relation-side declarations only (論点1 = c)
+ *
+ * The only input is each relation's `options.write.maintainedOn` +
+ * `options.projection` (the #121 relation options). The `entityWrites` escape
+ * hatch (`w.snapshotInto` / `w.captureInto` attached to a lifecycle) is **Phase
+ * 2** and is deliberately not read here.
+ *
+ * ## Reuses the A (#120) maintenance IR — no second definition
+ *
+ * The maintenance effect each index entry carries is the **A-defined IR** —
+ * {@link SnapshotEffect} / {@link CollectionEffect} / {@link ProjectionTransform}
+ * from `src/define/entity-writes.ts` (also re-exported from the root barrel). This
+ * module *synthesizes* those nodes from the relation-side declaration (it is the
+ * relation-options → IR lowering); it never re-defines the IR shapes.
+ *
+ * ## Round-trip validation (流用 of `assertRelationRoundTrips`)
+ *
+ * Mirroring `src/relation/edge-write.ts`'s build-time round-trip guard, the graph
+ * is verified the moment it is built, and a mis-declaration is a **loud reject**:
+ *
+ * - **Snapshot/collection target key points at a real row.** The relation's
+ *   `keyBinding` target fields must resolve to a real access pattern on the
+ *   target entity (the row that holds the snapshot/collection), via the *same*
+ *   {@link resolveKey} the read planner uses. A binding that covers no partition
+ *   would write/read an unreachable row → reject.
+ * - **Projection source attributes exist on the source payload (論点4 = payload
+ *   同梱のみ).** Every projection source path (`$.entity.<field>` /
+ *   `$.input.<field>`) must name an attribute that the *source* entity (the
+ *   trigger origin) actually carries. There is no fetch / re-projection: an
+ *   attribute that is not in the source payload is rejected, not fetched.
+ * - **Unresolved trigger.** A trigger whose entity segment names no registered
+ *   model, or whose event is not `created`/`updated`/`removed`, is rejected.
+ * - **Cycle.** A maintenance dependency cycle (entity A's event maintains a
+ *   shape on B while B's event maintains a shape on A, transitively) is detected
+ *   and rejected — an unbounded maintenance cascade.
+ *
+ * ## Scope (#124 only — NOT #125)
+ *
+ * This module builds and validates the index, and exposes enough structure for
+ * the compile-injection step (#125/#126) to consume it — including the material
+ * to detect that *two* maintainers target the **same** target row (論点2 = b,
+ * "1 mutation × 1 target row = 1 effect"). It does **not** resolve maintainers
+ * into the mutation compiler, derive `DerivedMaintainWrite`s, or emit any
+ * transaction items; `resolveMaintainers` / `deriveMaintainItems` are #125's.
+ */
+
+type ModelClass = new (...args: unknown[]) => unknown;
+/**
+ * One maintenance effect, keyed in the graph by its {@link trigger}. Synthesized
+ * from a single relation's maintenance declaration (its `write.maintainedOn` +
+ * `projection`).
+ *
+ * The role mapping follows RFC §5.1 (`relation({ from, to, maintainedOn })`):
+ *
+ * - **source** = the relation's `to` (its `targetFactory()`): the entity whose
+ *   lifecycle event fires the maintenance and whose payload is projected. The
+ *   trigger's `Entity` segment names this source.
+ * - **owner** = the relation's `from` (the model declaring the relation): the row
+ *   that *holds* the maintained snapshot / collection — the **destination** of the
+ *   maintenance write.
+ *
+ * So a `Post.created` trigger on `ThreadSummary.latestPosts → Post` maintains the
+ * `ThreadSummary` (owner) row from the `Post` (source) payload. It carries the
+ * A-defined {@link MaintainEffect} IR ({@link SnapshotEffect} /
+ * {@link CollectionEffect}) the maintenance lowers to.
+ */
+interface MaintainItem {
+    /** The validated `Entity.event` trigger that fires this effect. */
+    readonly trigger: MaintainTrigger;
+    /**
+     * The source entity name (trigger origin — the row whose lifecycle fires this
+     * and whose payload is projected). Equals the relation's target (`to`).
+     */
+    readonly sourceEntity: string;
+    /** The source model class (the relation's `targetFactory()`). */
+    readonly sourceClass: ModelClass;
+    /**
+     * The entity that *declares* the maintaining relation (the relation owner /
+     * `from`) — the row that holds the maintained snapshot / collection (the
+     * maintenance write **destination**).
+     */
+    readonly ownerEntity: string;
+    /** The owner model class (the maintenance destination). */
+    readonly ownerClass: ModelClass;
+    /** The relation property on the owner that declares this maintenance. */
+    readonly relationProperty: string;
+    /**
+     * A stable key for the **destination row** a single trigger writes (the owner
+     * row), derived from the relation's bound owner-key fields. Two
+     * {@link MaintainItem}s firing on the same trigger with the same
+     * {@link destinationRowKey} write the same row — the material #125/#126 uses to
+     * enforce 論点2 = b ("1 mutation × 1 target row = 1 effect"; multiple is a
+     * reject). Built deterministically (sorted), so it is a directly comparable
+     * string.
+     */
+    readonly destinationRowKey: string;
+    /** The A-defined maintenance IR this relation lowers to. */
+    readonly effect: MaintainEffect;
+}
+/**
+ * The maintenance graph: the trigger → effects index plus the validation surface.
+ *
+ * `byTrigger` is the core index: a `MaintainTrigger` (`"Post.created"`) maps to
+ * every {@link MaintainItem} that fires on it, in a stable order (owner entity,
+ * then relation property). Empty (no entry) for a trigger nothing maintains on.
+ */
+interface MaintenanceGraph {
+    /** Every maintenance item, flattened, in deterministic order. */
+    readonly items: readonly MaintainItem[];
+    /** The core index: trigger → the effects it fires. */
+    readonly byTrigger: ReadonlyMap<MaintainTrigger, readonly MaintainItem[]>;
+    /** Look up the effects fired by a trigger (empty array if none). */
+    effectsFor(trigger: MaintainTrigger): readonly MaintainItem[];
+    /**
+     * Items that, under the SAME trigger, write the SAME target row — grouped by
+     * `"<trigger><targetRowKey>"`. Only groups with **more than one** item are
+     * present, so an empty map means no trigger has a multi-maintainer collision.
+     * This is the detection material for 論点2 = b; #124 surfaces it, #125/#126
+     * decide the reject. (Build-time we do NOT reject here — a model may legitimately
+     * declare overlapping shapes that a later phase reconciles; #124's contract is
+     * to make the collision *detectable*.)
+     */
+    readonly multiMaintainerTargets: ReadonlyMap<string, readonly MaintainItem[]>;
+}
+/**
+ * Build the {@link MaintenanceGraph} from every registered model's relation-side
+ * maintenance declarations (`MetadataRegistry.getAll()`), validating each as it is
+ * collected (round-trip, unresolved trigger) and the whole graph (cycle) before
+ * returning. Throws a loud, actionable error on any invalid declaration.
+ *
+ * @param registry The models to scan. Defaults to `MetadataRegistry.getAll()`;
+ *   an explicit map is accepted for tests / scoped builds.
+ */
+declare function buildMaintenanceGraph(registry?: ReadonlyMap<Function, EntityMetadata>): MaintenanceGraph;
+
 /**
  * Serializable static operation specs and manifest (issue #42, Python-bridge
  * Phase 0b).
@@ -2354,6 +3189,99 @@ interface TransactionItemSpec {
      * entity / edge / counter / ConditionCheck item), so those paths are unchanged.
      */
     readonly literalKey?: boolean;
+    /**
+     * A **relation-side maintenance write** (Epic #118, issue #129 — the JSON-SSoT /
+     * Python mirror of the TS in-process `renderMaintainWriteItem`). Present ONLY on an
+     * `Update` item that materializes a maintained access path: a projected
+     * {@link DerivedMaintainWrite} of a just-written source row into a SEPARATE owner
+     * (destination) row, in the SAME atomic transaction as the source write.
+     *
+     * The item's {@link keyCondition} carries the owner row's key templates (bound from
+     * the source payload — `{sourceInputField}`), so the same key derivation / collapse
+     * signature the other `Update` items use applies unchanged. This `maintain` payload
+     * carries the projection transform IR (`identity` / `preview`) the runtimes apply
+     * IDENTICALLY when rendering the `SET … = :v` (snapshot) / `list_append(…)`
+     * (collection) `UpdateExpression`, so the maintained row is byte-consistent across
+     * TS and Python. The `changes` / `add` fields are NOT used when this is present.
+     */
+    readonly maintain?: MaintainItemSpec;
+}
+/**
+ * The transform op applied to one projected maintenance attribute (Epic #118).
+ * Mirrors `ProjectionTransformOp` from `src/define/entity-writes.ts`: `identity`
+ * copies the source value through unchanged; `preview` keeps the first `n`
+ * characters of (the string form of) the source value. The runtimes apply this
+ * IDENTICALLY so the maintained row is byte-consistent.
+ */
+type MaintainProjectionOp = 'identity' | 'preview';
+/**
+ * One projected maintenance attribute: the source value is read from the mutation
+ * input field {@link inputField} (payload 同梱 — the just-written source row image),
+ * then run through {@link op} with {@link args} (e.g. `preview`'s length bound).
+ */
+interface MaintainProjectionEntry {
+    /** The transform op applied to the source value (`identity` / `preview`). */
+    readonly op: MaintainProjectionOp;
+    /** The op's positional arguments (`[n]` for `preview`; empty for `identity`). */
+    readonly args: readonly unknown[];
+    /** The mutation-input field the source value is read from (`{inputField}`). */
+    readonly inputField: string;
+}
+/**
+ * The bounded-collection options a `collection` maintenance write carries. Phase 1
+ * is **append-only**: `maxItems` / `orderBy` are recorded for the future async trim
+ * (#130) but NOT applied synchronously — a single `UpdateExpression` cannot
+ * read-modify-write a bounded/ordered list.
+ */
+interface MaintainCollectionSpec {
+    /** The target attribute that holds the maintained collection. */
+    readonly field: string;
+    /** Cap on the collection size (recorded for #130; not trimmed in Phase 1). */
+    readonly maxItems?: number;
+    /** The mutation-input field the items are ordered by (recorded for #130). */
+    readonly orderBy?: string;
+}
+/**
+ * The maintenance payload an `Update` {@link TransactionItemSpec} carries when it
+ * materializes a maintained access path (Epic #118 / #129). A `snapshot` mirrors
+ * the projection onto the owner row via `SET`; a `collection` appends the projection
+ * as an item into the bounded list named by {@link collection} via `list_append`.
+ */
+interface MaintainItemSpec {
+    /**
+     * Whether the write mirrors a single row (`snapshot`), appends a collection item
+     * (`collection`), or applies a scalar `ADD` counter (`counter`, Epic #118 / #141).
+     */
+    readonly kind: 'snapshot' | 'collection' | 'counter';
+    /** The relation property / `@aggregate` field that declared this maintenance (documentary). */
+    readonly relationProperty: string;
+    /** The trigger (`<sourceLogicalName>.<event>`) that fired this maintenance. */
+    readonly trigger: string;
+    /** target attribute → its projection transform (source field + op + args). Empty for `counter`. */
+    readonly projection: Readonly<Record<string, MaintainProjectionEntry>>;
+    /** The bounded-collection options; present only for `kind: 'collection'`. */
+    readonly collection?: MaintainCollectionSpec;
+    /**
+     * The scalar counter `ADD`; present only for `kind: 'counter'` (#141). The runtimes
+     * render `ADD #attr :delta` — an atomic, concurrency-safe increment that MERGES with
+     * a same-row counter ADD (#92), the maintenance-pipeline analogue of the
+     * self-lifecycle derived counter's `add` slot. `delta` is a numeric template string
+     * (the compile-time constant `+1` created / `-1` removed).
+     */
+    readonly counter?: MaintainCounterSpec;
+}
+/**
+ * The scalar counter a `counter` maintenance write applies (Epic #118 / #141): an
+ * atomic `ADD #attribute :delta`. `delta` is a literal numeric template string (the
+ * compile-time constant the trigger fixed — `"1"` created / `"-1"` removed); the
+ * runtimes serialize it as a number. Only `count()` is realized synchronously
+ * (`max(field)` is rejected for the synchronous path — #130 / Phase 2).
+ */
+interface MaintainCounterSpec {
+    /** The target attribute the counter increments (e.g. `postCount`). */
+    readonly attribute: string;
+    /** The signed `ADD` delta as a numeric template string (`"1"` / `"-1"`). */
+    readonly delta: string;
 }
 /** A declarative transaction definition's full execution spec. */
 interface TransactionSpec {
@@ -2783,6 +3711,75 @@ interface DerivedUpdate {
     /** The signed delta to add (e.g. `+1` create, `-1` remove). */
     readonly amount: number;
 }
+/**
+ * One **derived maintenance write** — the projection of a just-written source row
+ * into a *separate* target (owner) row, derived from one maintenance-graph
+ * {@link MaintainItem} (issue #125; the D/#124 → compile lowering). It generalizes
+ * {@link DerivedUpdate}: where a `derive` is one scalar `ADD`, a maintenance write
+ * mirrors a whole projection — a single-row {@link SnapshotEffect} (`kind:
+ * 'snapshot'`) or an item appended into a bounded collection ({@link
+ * CollectionEffect}, `kind: 'collection'`).
+ *
+ * The target row's key is bound from the source payload (the relation's owner-key
+ * fields, filled from `$.entity.<sourceField>` → the fragment's `<sourceField>`
+ * input param), and each projected attribute is a {@link ProjectionTransform} IR
+ * node (A/#120 関数形 — `identity` / `preview`) resolved to the input param it reads.
+ * #125 produces this structure; the runtime realization (the actual `Put` / `Update`
+ * item and its placement in the atomic `TransactWriteItems`) is #127.
+ */
+interface DerivedMaintainWrite {
+    /** The maintained (destination / owner) entity whose row holds the snapshot / collection. */
+    readonly entity: EntityRef;
+    /** The relation property on the owner that declared this maintenance (documentary). */
+    readonly relationProperty: string;
+    /** The trigger (`<sourceLogicalName>.<event>`) that fired this maintenance. */
+    readonly trigger: MaintainTrigger;
+    /**
+     * Whether the write mirrors a single row (`snapshot`), appends a collection item
+     * (`collection`), or applies a scalar `ADD` counter (`counter`, #141).
+     */
+    readonly kind: 'snapshot' | 'collection' | 'counter';
+    /**
+     * The destination row's key binding: target key field → the mutation-input param
+     * that supplies it (resolved from the effect's `$.entity.<sourceField>` paths —
+     * the source row image, payload 同梱). Every owner-key field is bound.
+     */
+    readonly keyBinding: Readonly<Record<string, string>>;
+    /**
+     * The projection: target attribute → `{ op, args, inputField }`, where `inputField`
+     * is the mutation-input param the source value is read from and `op` / `args` are
+     * the A/#120 {@link ProjectionTransform} realization (`identity` copies through,
+     * `preview` keeps the first `n` chars). Empty for a `counter` (a scalar `ADD`
+     * projects no row attributes).
+     */
+    readonly projection: Readonly<Record<string, {
+        readonly op: ProjectionTransform['op'];
+        readonly args: readonly unknown[];
+        readonly inputField: string;
+    }>>;
+    /**
+     * For a `collection` write, the bounded-collection options (the target `field`,
+     * the optional `maxItems` cap, and the optional `orderBy` input param); absent for
+     * a `snapshot` / `counter`.
+     */
+    readonly collection?: {
+        readonly field: string;
+        readonly maxItems?: number;
+        readonly orderBy?: string;
+    };
+    /**
+     * For a `counter` write (#141 — `@aggregate(..., { pattern: 'counter', value:
+     * count() })`), the scalar `ADD`: the target {@link counter.attribute} and the
+     * signed {@link counter.delta} the trigger applies (`+1` created / `-1` removed).
+     * A counter `ADD` is commutative, so two counter writes on the SAME row MERGE (the
+     * #92 symmetric-counter collapse) rather than reject — unlike snapshot/collection.
+     * Absent for a `snapshot` / `collection`.
+     */
+    readonly counter?: {
+        readonly attribute: string;
+        readonly delta: number;
+    };
+}
 /**
  * A **derived uniqueness guard** — the marker-row `Put` (and, on a unique-field
  * change, the old-guard `Delete` + new-guard `Put` swap) that enforces an
@@ -2975,6 +3972,20 @@ interface CompiledFragment {
      * guard and rolls the WHOLE transaction back — so no effect is double-applied.
      */
     readonly idempotencyGuard?: DerivedIdempotencyGuard;
+    /**
+     * The maintenance writes derived from the maintenance graph (issue #125; the
+     * D/#124 → compile lowering): one {@link DerivedMaintainWrite} per relation that
+     * declared `write.maintainedOn` for this fragment's lifecycle event (a projected
+     * snapshot / collection on a SEPARATE target row). Present (non-empty) only when
+     * the fragment's trigger fires at least one maintainer; absent otherwise (no
+     * regression — a fragment that maintains nothing compiles exactly as before).
+     *
+     * SCOPE (#125): each entry is the runtime-neutral structure the runtime (#127)
+     * realizes into the atomic `TransactWriteItems`; #125 derives it and rejects a
+     * same-target collision (論点2 = b). The cross-fragment AGGREGATION and the
+     * one-atomic-tx execution wiring are #127 — not done here.
+     */
+    readonly maintainWrites?: readonly DerivedMaintainWrite[];
 }
 /**
  * Resolve the {@link LifecycleContract} a fragment adopts for its intent:
@@ -3015,8 +4026,12 @@ type EntityRefResolver = (ref: MutationEntityRef, consumerIndex: number, consume
  * @param resolveEntityRef Resolver for a `$.entity[i].field` cross-fragment
  *   reference (multi-fragment compile), or `null` for a single-fragment compile
  *   (where such a reference is a hard error).
+ * @param maintenanceGraph The {@link MaintenanceGraph} the #125 maintain injection
+ *   queries for this fragment's trigger ({@link resolveMaintainers}). Defaults to a
+ *   lazily-built, cached graph over the global registry; an explicit graph is
+ *   accepted for scoped tests.
  */
-declare function compileFragment(fragment: MutationFragment, index?: number, resolveEntityRef?: EntityRefResolver | null): CompiledFragment;
+declare function compileFragment(fragment: MutationFragment, index?: number, resolveEntityRef?: EntityRefResolver | null, maintenanceGraph?: MaintenanceGraph): CompiledFragment;
 /**
  * Compile a single-fragment {@link CommandPlan} into its {@link CompiledFragment}.
  * The N-fragment atomic merge is **#90** ({@link compileMutationPlan}); this entry
@@ -3688,6 +4703,23 @@ interface CommandMethodSpec<TKey, TParams, TResult> {
      * the guard and rolls the WHOLE write back — no effect is double-applied.
      */
     readonly idempotencyGuard?: DerivedIdempotencyGuard;
+    /**
+     * The maintenance writes derived from the relation-side `write.maintainedOn`
+     * declarations (issue #125; D/#124 → compile lowering), flattened across every
+     * fragment in declaration order. Present (non-empty) only when a fragment's
+     * lifecycle event (`Post.created` etc.) fires at least one maintainer; absent
+     * otherwise (no regression — a maintainer-free mutation is byte-identical to its
+     * pre-#127 form). Each {@link DerivedMaintainWrite} projects the just-written
+     * source row into a SEPARATE owner (destination) row — a single-row snapshot
+     * (`kind: 'snapshot'`) or an item appended into a bounded collection (`kind:
+     * 'collection'`). Their presence (like {@link conditionChecks}) **promotes** an
+     * otherwise single-op method to a transaction: the runtime (#127) realizes each
+     * into the method's atomic `TransactWriteItems`, so the maintained row moves
+     * atomically with the source write (a failure rolls the WHOLE set back). #127 is
+     * the synchronous (`updateMode: 'mutation'`) path only; the async stream path is
+     * #130 (loud-rejected at compile time, never silently dropped).
+     */
+    readonly maintainWrites?: readonly DerivedMaintainWrite[];
     /** @internal Phantom carrier retaining the formal `CommandMethod` type. */
     readonly __signature?: CommandMethod<TKey, TParams, TResult>;
 }
@@ -4288,6 +5320,22 @@ interface ExecutableCommandContract {
          * Absent on a mutation with no `idempotency` / a #64 hand-written method.
          */
         readonly idempotencyGuard?: DerivedIdempotencyGuard;
+        /**
+         * The maintenance writes derived from the relation-side `write.maintainedOn`
+         * declarations (issue #125 → #127; the D/#124 → compile lowering). When
+         * present (non-empty), a **single-key** call composes each maintenance write
+         * — a projected snapshot (`SET`) or a bounded-collection append
+         * (`SET … = list_append(…)`) on a SEPARATE owner row — into the same atomic
+         * `TransactWriteItems` as the source entity write (and every other effect),
+         * so the maintained row moves ATOMICALLY with the source: a failure on any
+         * item rolls the WHOLE transaction back (the snapshot / collection never
+         * partially persists). The owner row is upserted (a bare `UpdateItem`
+         * creates it if absent — the additive maintenance semantics). This is the
+         * synchronous (`updateMode: 'mutation'`) path only; the async stream path is
+         * #130 (loud-rejected at compile time). Absent on a mutation that fires no
+         * maintainer / a #64 hand-written method.
+         */
+        readonly maintainWrites?: readonly DerivedMaintainWrite[];
         /**
          * The return projection of a `mutation`-derived method (issue #83). When
          * present, a **single-key** call performs the write then issues a
@@ -4391,6 +5439,13 @@ interface ReadRouteOptions {
     readonly after?: string;
     readonly order?: 'ASC' | 'DESC';
     readonly filter?: Record<string, unknown>;
+    /**
+     * Host-injected per-call read context (issue #50 / #138). Threaded into the
+     * route's underlying read (`executeQuery` / `executeList`), so the read hooks
+     * R1–R5 fire for the route with this `ctx.context`. Each route runs
+     * independently, so its hooks see only its own context. Absent ⇒ `{}`.
+     */
+    readonly context?: RequestContext;
 }
 /** One read route: a `query` (point/unique) or a `list` (partition) descriptor. */
 interface ReadRouteDescriptor {
@@ -4447,6 +5502,13 @@ interface MutateOptions {
      * built-in default policy.
      */
     readonly retry?: RetryOverride;
+    /**
+     * Host-injected per-call write context (issue #50 / #139) — exposed to every
+     * write hook (W1–W5) as `ctx.context`. In `transaction` mode every composed op
+     * shares it and the persist hooks fire once for the atomic batch; in `parallel`
+     * mode each independent op sees it. NEVER serialized. Absent ⇒ `{}`.
+     */
+    readonly context?: RequestContext;
 }
 /** A per-alias result in `parallel` mode: success carries the read-back, else error. */
 type ParallelOpResult = {
@@ -4548,7 +5610,33 @@ declare abstract class DDBModel {
      * for that call (`false` disables retry).
      */
     static setRetryPolicy(policy: RetryPolicy | null): void;
-    static transaction(fn: (tx: TransactionContext) => void | Promise<void>): Promise<void>;
+    /**
+     * Register a {@link Middleware} (issue #50; read path #138, write path #139).
+     * One registered object may carry read and/or write hooks.
+     *
+     * - **Read** R1–R5 — request entry (`read.before`), each physical op before send
+     *   / after raw fetch (`read.op.before` / `read.op.afterFetch`, INCLUDING every
+     *   relation fan-out fetch), the final hydrated result (`read.afterFetch`), and on
+     *   error (`read.op.onError` / `read.onError`).
+     * - **Write** W1–W5 — the logical write before effect derivation (`write.before`,
+     *   may mutate `ctx.input` / `ctx.kind` incl. a delete→update rewrite), after commit
+     *   (`write.after`), the physical persist on the fully composed batch
+     *   (`write.persist.before` / `write.persist.after`, fires ONCE per atomic
+     *   transaction), and on error (`write.persist.onError` / `write.onError`).
+     *
+     * Hooks may observe, mutate `ctx`, `throw` to cancel, or (on `onError`) recover by
+     * returning a value; the library imposes no semantics. Ordering: `before*` runs
+     * first-registered-first (FIFO); `after*` / `onError` run last-registered-first
+     * (LIFO). Mirrors {@link setRetryPolicy} — a host-runtime global stored on
+     * {@link ClientManager}; never serialized (the bridge #48 is unaffected). Per-call
+     * host context flows in via the read's / write's `{ context }` option.
+     */
+    static use(mw: Middleware): void;
+    /** Remove every registered middleware (read AND write; teardown / tests). See {@link use}. */
+    static clearMiddleware(): void;
+    static transaction(fn: (tx: TransactionContext) => void | Promise<void>, options?: {
+        context?: RequestContext;
+    }): Promise<void>;
     /**
      * In-process multi-route READ (issue #101 — the unified envelope). Each alias
      * route (`{ query | list: Model, key, select, options? }`) runs **independently
@@ -4576,7 +5664,19 @@ declare abstract class DDBModel {
     static mutate<const E extends WriteEnvelope>(envelope: E, options: {
         mode: 'parallel';
     }): Promise<MutateParallelResult<E>>;
-    static batchGet(requests: BatchGetRequest[]): Promise<BatchGetResult>;
+    /**
+     * Multi-key, multi-model batch read. Each {@link BatchGetRequest} contributes its
+     * keys to a chunked `BatchGetItem` per physical table; results are re-grouped by
+     * model on the returned {@link BatchGetResult}.
+     *
+     * Fires the read hooks (issue #142): request-level R1/R4/R5 with kind
+     * `'batchGet'`, and op-level R2/R3/R5 for each underlying physical `BatchGetItem`
+     * op. The optional `{ context }` is exposed to every hook as `ctx.context` and
+     * threaded UNCHANGED to every op (absent ⇒ `{}`), so a global hook (e.g. a
+     * tenant-scope R2 FilterExpression) applies across the whole batch. With no
+     * middleware registered the read path is unchanged (zero-overhead fast path).
+     */
+    static batchGet(requests: BatchGetRequest[], options?: BatchGetOptions): Promise<BatchGetResult>;
     static batchWrite(requests: BatchWriteRequest[]): Promise<void>;
     static asModel<C extends new (...args: never[]) => DDBModel>(this: C): ModelStatic<InstanceType<C>, C>;
 }
@@ -4707,6 +5807,236 @@ declare function key<T extends Record<string, unknown>>(builder: (c: {
     readonly [K in keyof T]-?: Column<T[K], T>;
 }) => KeyStructure): KeyDefinitionMarker<T>;
 
+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;
+}
+/**
+ * The named maintenance pattern a relation participates in (Epic #118 §5.1).
+ *
+ * `pattern` is the *preset* selector: omitting it leaves the relation a plain
+ * read-only navigation (the historical `hasMany`/`belongsTo`/`hasOne`
+ * behaviour), exactly backward compatible. When present it names the AWS
+ * design pattern the relation lowers to — the lowering itself (maintenance
+ * graph / compile injection) is out of scope for issue #121 and lands in
+ * #124/#125; here the value is recorded purely as declaration metadata.
+ *
+ * Typed as a `string` union of the known presets but kept open-ended via the
+ * `(string & {})` tail so a future preset can be authored before this union is
+ * widened, without a breaking change to callers.
+ */
+type RelationPattern = 'samePartition' | 'edge' | 'counter' | 'embeddedSnapshot' | 'materializedView' | 'sparseView' | 'externalProjection' | (string & {});
+/**
+ * Consistency boundary a maintained write is declared against (Epic #118 §4.A.7):
+ * `transactional` = same `TransactWriteItems`; `eventual` = asynchronous catch-up.
+ */
+type RelationConsistency = 'transactional' | 'eventual';
+/**
+ * How a maintained write is applied (Epic #118 §4.A.7):
+ * `mutation` = composed into the same mutation; `stream` = driven asynchronously
+ * off a stream / outbox.
+ */
+type RelationUpdateMode = 'mutation' | 'stream';
+/**
+ * Read-strategy hints for a maintained relation (Epic #118 §5.1 `read`).
+ *
+ * All fields optional — present only when a `pattern` declares a read shape
+ * (e.g. an `embeddedSnapshot` keeping the latest N items). A bare relation
+ * carries no `read` block.
+ */
+interface RelationReadOptions {
+    /** Cap on materialised items kept inline (e.g. "latest 3 posts"). */
+    maxItems?: number;
+    /** Ordering of the maintained collection. */
+    order?: 'ASC' | 'DESC';
+}
+/**
+ * Write-maintenance declaration for a relation (Epic #118 §5.1 `write`).
+ *
+ * `maintainedOn` is the cross-entity trigger list (`"<Entity>.<event>"`, e.g.
+ * `"Post.created"`) that the maintenance graph (#124/#125) will key off. Recorded
+ * here as declaration metadata only.
+ */
+interface RelationWriteOptions {
+    /**
+     * Cross-entity triggers, e.g. `['Post.created', 'Post.removed']`. The event
+     * segment is the confirmed shared lifecycle vocabulary (epic #118 A/B
+     * reconciliation): `created` / `updated` / `removed`.
+     */
+    maintainedOn?: string[];
+    consistency?: RelationConsistency;
+    updateMode?: RelationUpdateMode;
+}
+/**
+ * Snapshot / projection capture map for a maintained relation
+ * (Epic #118 §5.1 / §5.2 `projection`).
+ *
+ * Maps each captured field name on the maintaining side to **how** the source
+ * value is projected. The confirmed shared vocabulary (epic #118 A/B
+ * reconciliation) is the **function-form IR** — the same {@link
+ * ProjectionTransform} node A (#120) defines on `src/define/entity-writes.ts`,
+ * re-used here (NOT re-defined) so the two surfaces never re-diverge. Each value
+ * is either:
+ *
+ * - a {@link ProjectionTransform} (built with the standalone authoring helpers,
+ *   e.g. `preview('body', 120)` — RFC §5.2 `textPreview: preview('body', 120)`),
+ *   or
+ * - a bare `string` — the **identity shorthand**: project that source path
+ *   through unchanged (e.g. `{ postId: 'postId' }`).
+ *
+ * `Readonly` so the recorded declaration metadata is not mutated downstream.
+ * Issue #121 scopes this to the declaration shape; the maintenance graph /
+ * compile injection that consumes the IR is #124/#125.
+ *
+ * @example `{ postId: 'postId', textPreview: preview('body', 120) }`
+ */
+type RelationProjection = Readonly<Record<string, ProjectionTransform | string>>;
+interface RelationOptions {
+    limit?: RelationLimitOptions;
+    order?: 'ASC' | 'DESC';
+    /**
+     * Named maintenance preset (Epic #118). Omitted = plain read-only navigation,
+     * fully backward compatible with the historical relation decorators.
+     */
+    pattern?: RelationPattern;
+    read?: RelationReadOptions;
+    write?: RelationWriteOptions;
+    projection?: RelationProjection;
+}
+interface RelationMetadata {
+    type: 'hasMany' | 'hasOne' | 'belongsTo';
+    propertyName: string;
+    targetFactory: () => new (...args: unknown[]) => unknown;
+    keyBinding: Record<string, string>;
+    options?: RelationOptions;
+}
+/**
+ * The scalar-aggregate value an `@aggregate` field derives from its source entity
+ * (Epic #118 §5.2 counter / latest preset; issue #122). It is the function-form
+ * IR built by the {@link count} / {@link max} value helpers — the aggregation an
+ * `@aggregate(() => Source, keyBinding, { pattern, value })` field maintains:
+ *
+ * - `count` — the cardinality of source rows matched by the key binding (no
+ *   source field; e.g. `postCount!: number` ← `count()`).
+ * - `max` — the maximum value of a named source `field` (e.g. `lastPostAt!:
+ *   string` ← `max('createdAt')`).
+ *
+ * Recorded purely as declaration metadata (issue #122 scope = declaration
+ * surface): the maintenance graph (#124) / compile injection (#125) consume it;
+ * the effect itself is out of scope here. Kept open-ended via the discriminated
+ * `op` so a future aggregation (`min`, `sum`, …) extends the union without a
+ * breaking change.
+ *
+ * @example `count()` → `{ op: 'count' }`
+ * @example `max('createdAt')` → `{ op: 'max', field: 'createdAt' }`
+ */
+type AggregateValue = {
+    readonly op: 'count';
+} | {
+    readonly op: 'max';
+    readonly field: string;
+};
+/**
+ * Options for an `@aggregate` field (Epic #118 §5.2 counter / latest preset;
+ * issue #122). Mirrors the maintenance vocabulary a relation declares so the two
+ * authoring surfaces stay in lockstep:
+ *
+ * - `pattern` reuses {@link RelationPattern} (e.g. `'counter'`) — the named
+ *   maintenance preset, NOT re-defined here.
+ * - `value` is the {@link AggregateValue} the field maintains (`count()` /
+ *   `max('createdAt')`).
+ * - `write` reuses {@link RelationWriteOptions} verbatim — `maintainedOn`
+ *   triggers (`Post.created` / `Post.removed`, the confirmed shared
+ *   `created|updated|removed` event vocabulary) plus `consistency`
+ *   (`transactional|eventual`) / `updateMode` (`mutation|stream`). These are NOT
+ *   re-defined; they are the same shared types B (#121) added.
+ */
+interface AggregateOptions {
+    /** Named maintenance preset (typically `'counter'`); reuses {@link RelationPattern}. */
+    pattern?: RelationPattern;
+    /** The scalar aggregation this field maintains (`count()` / `max('createdAt')`). */
+    value: AggregateValue;
+    /** Cross-entity maintenance triggers / consistency / update-mode (reused from B). */
+    write?: RelationWriteOptions;
+}
+/**
+ * Declaration metadata recorded by an `@aggregate` field decorator (issue #122).
+ *
+ * An `@aggregate` is a **scalar** field (`postCount!: number`,
+ * `lastPostAt!: string`) whose value is derived — by aggregating rows of a source
+ * entity resolved by {@link targetFactory} + {@link keyBinding} — rather than
+ * stored directly. It is therefore recorded in its **own** metadata array
+ * (`EntityMetadata.aggregates`), distinct from both {@link FieldMetadata} (a
+ * plain stored attribute) and {@link RelationMetadata} (a navigation yielding
+ * model instances): an aggregate carries a source binding like a relation, but
+ * surfaces a scalar value like a field. The collector path mirrors relations
+ * (decorator pushes, `@model` drains).
+ *
+ * Issue #122 scope is the declaration surface + metadata pass-through only; the
+ * aggregation effect's compile / runtime (#124/#125/#127) is out of scope.
+ */
+interface AggregateMetadata {
+    /** The scalar field the aggregate value is written to. */
+    propertyName: string;
+    /** Resolves the source entity whose rows are aggregated. */
+    targetFactory: () => new (...args: unknown[]) => unknown;
+    /** The key binding selecting the source rows (target key field → source field). */
+    keyBinding: Record<string, string>;
+    /** The aggregate preset / value / maintenance-write declaration. */
+    options: AggregateOptions;
+}
+interface EmbeddedMetadata {
+    propertyName: string;
+    modelFactory: () => new (...args: unknown[]) => unknown;
+}
+interface EntityMetadata {
+    tableName: string;
+    prefix: string;
+    fields: FieldMetadata[];
+    primaryKey: KeyDefinition | null;
+    gsiDefinitions: GsiDefinition[];
+    relations: RelationMetadata[];
+    /** Scalar `@aggregate` fields (Epic #118 §5.2 counter / latest; issue #122). */
+    aggregates: AggregateMetadata[];
+    embeddedFields: EmbeddedMetadata[];
+}
+
 /**
  * CDC emulator types (issue #72). These types are **cdc-module-owned**; core
  * never references them. The {@link ChangeEvent} shape mirrors DynamoDB Streams
@@ -4820,4 +6150,4 @@ interface CdcEmulatorOptions {
 }
 type ShardId = string;
 
-export { type QuerySpec as $, type ParamDescriptor as A, type BatchGetExecInput as B, type ChangeEvent as C, type DynamoDBOperation as D, type Executor as E, type FaultSpec as F, type DefinitionMap as G, type WriteDefinitionOptions as H, type PartialQueryKeyOf as I, type StrictSelectSpec as J, type EntityInput as K, type UniqueQueryKeyOf as L, type ModelStatic as M, type EntityRef as N, type OperationDefinition as O, type PutInput as P, type ConditionInput as Q, type ReadExecOptions as R, type SelectableOf as S, type TransactWriteExecItem as T, type UpdateInput as U, type QueryModelContract as V, type WriteExecOptions as W, type QueryMethodSpec as X, type CommandModelContract as Y, type CommandMethodSpec as Z, type ContractSpec as _, type ExecutorResult as a, type FilterInput as a$, type CommandSpec as a0, type ContextSpec as a1, type OperationsDocument as a2, type AnyOperationDefinition as a3, type BridgeBundle as a4, type ConditionSpec as a5, type BatchDeleteRequest as a6, type BatchGetRequest as a7, BatchGetResult as a8, type BatchPutRequest as a9, type ContractFromRef as aA, type ContractInputArity as aB, type ContractItem as aC, type ContractKeyFieldRef as aD, type ContractKeyInput as aE, type ContractKeyRef as aF, type ContractKeySpec as aG, type ContractKind as aH, type ContractMethodOp as aI, type ContractParamRef as aJ, type ContractQueryParams as aK, type ContractResolution as aL, DEFAULT_MAX_ATTEMPTS as aM, DEFAULT_RETRY_POLICY as aN, type DeleteOptions as aO, type DeriveEffect as aP, type DerivedEdgeWrite as aQ, type DerivedUpdate as aR, type DescriptorBinding as aS, ENTITY_WRITES_MARKER as aT, type EdgeEffect as aU, type EffectPath as aV, type EmitEffect as aW, type EntityWritesDefinition as aX, type EntityWritesShape as aY, type ExecutableCommandContract as aZ, type ExecutableQueryContract as a_, type BatchResult as aa, type BatchWriteRequest as ab, CONTRACT_RANGE_FANOUT_CONCURRENCY as ac, type CdcMode as ad, type ChangeBatch as ae, type ChangeEventName as af, type ClockMode as ag, type Column as ah, type ColumnMap as ai, type CommandContractMethodSpec as aj, type CommandInputShape as ak, type CommandMethod as al, type CommandPlan as am, type CommandResolutionTarget as an, type CommandResultKind as ao, type CommandSelectShape as ap, type CompiledFragment as aq, type ComposeSpec as ar, type CondSlot as as, type ConditionCheckInput as at, type Connection as au, type ContractCallSignature as av, type ContractCardinality as aw, type ContractCommandParams as ax, type ContractCommandResult as ay, type ContractComposeNode as az, type WriteResult as b, type SegmentSpec as b$, type FilterSpec as b0, type FragmentInput as b1, type GsiDefinitionMarker as b2, type GsiOptions as b3, type IdempotencyEffect as b4, type InProcessWriteDescriptor as b5, type InputArity as b6, type KeyDefinitionMarker as b7, type KeySegment as b8, type KeySlot as b9, type OperationSpec as bA, type ParallelOpResult as bB, type ParamKind as bC, type ParamSpec as bD, type ParamStructure as bE, type PlannedCommandMethod as bF, type PutOptions as bG, type QueryContractMethodSpec as bH, type QueryEnvelopeResult as bI, type QueryKeyOf as bJ, type QueryMethod as bK, type QueryResult as bL, type RangeConditionSpec as bM, type ReadEnvelope as bN, type ReadOperationType as bO, type ReadRouteDescriptor as bP, type ReadRouteOptions as bQ, type ReadRouteResult as bR, type RecordedCompose as bS, type RelationBuilder as bT, type RelationSelect as bU, type RelationSpec as bV, type RequiresEffect as bW, type Resolution as bX, type RetryInfo as bY, type RetryOperationKind as bZ, SPEC_VERSION as b_, type KeyStructure as ba, type KeyedResult as bb, LIFECYCLE_CONTRACT_MARKER as bc, type LifecycleContract as bd, type LifecycleEffects as be, type LiteralParam as bf, type ManifestEntity as bg, type ManifestField as bh, type ManifestFieldType as bi, type ManifestGsi as bj, type ManifestKey as bk, type ManifestRelation as bl, type ManifestTable as bm, type ModelRef as bn, type MutateMode as bo, type MutateOptions as bp, type MutateParallelResult as bq, type MutateTransactionResult as br, type MutationBody as bs, type MutationDescriptorMap as bt, type MutationFragment as bu, type MutationInputProxy as bv, type MutationInputRef as bw, type MutationIntent as bx, type NumberParam as by, type OperationKind as bz, type DeleteInput as c, mintContractParamRef as c$, type SelectBuilder as c0, type SelectOf as c1, type StartingPosition as c2, type StreamViewType as c3, type StringParam as c4, TransactionContext as c5, type TransactionItemType as c6, type UniqueEffect as c7, type Updatable as c8, type UpdateOptions as c9, executeTransaction as cA, executeUpdate as cB, from as cC, getEntityWrites as cD, gsi as cE, isColumn as cF, isCommandModelContract as cG, isCommandPlan as cH, isContractComposeNode as cI, isContractFromRef as cJ, isContractKeyFieldRef as cK, isContractKeyRef as cL, isContractParamRef as cM, isEntityWritesDefinition as cN, isKeySegment as cO, isLifecycleContract as cP, isMutationFragment as cQ, isMutationInputRef as cR, isParam as cS, isPlannedCommandMethod as cT, isQueryModelContract as cU, isRetryableError as cV, isRetryableTransactionCancellation as cW, k as cX, key as cY, lifecyclePhaseForIntent as cZ, mintContractKeyFieldRef as c_, type WhenSpec as ca, type WriteDescriptor as cb, type WriteEnvelope as cc, type WriteLifecyclePhase as cd, type WriteOperationType as ce, type WriteRecorder as cf, type WriteResultProjection as cg, attachModelClass as ch, buildDeleteInput as ci, buildPutInput as cj, buildUpdateInput as ck, compileFragment as cl, compileMutationPlan as cm, compileSingleFragmentPlan as cn, cond as co, contractOfMethodSpec as cp, definePlan as cq, entityWrites as cr, executeBatchGet as cs, executeBatchWrite as ct, executeCommandMethod as cu, executeDelete as cv, executeKeyedBatchGet as cw, executePut as cx, executeQueryMethod as cy, executeRangeFanout as cz, type BatchWriteExecItem as d, mutation as d0, param as d1, publicCommandModel as d2, publicQueryModel as d3, query as d4, resolveLifecycle as d5, wholeKeysSentinel as d6, type BatchExecOptions as e, DDBModel as f, type PrimaryKeyOf as g, type RetryPolicy as h, type ExecutionPlanSpec as i, type SegmentedKey as j, type SelectBuilderSpec as k, type RawCondition as l, type TransactionSpec as m, type Manifest as n, type RetryOverride as o, type ExecutionPlan as p, type ResolvedKey as q, type CdcEmulatorOptions as r, type ChangeHandler as s, type Unsubscribe as t, type ConcurrentRecomputeRef as u, type EventLog as v, type ReplayOptions as w, type ShardId as x, type TransactionItemSpec as y, type Param as z };
+export { type Param as $, type AggregateOptions as A, type BatchGetExecInput as B, type ChangeEvent as C, type DynamoDBOperation as D, type Executor as E, type FieldOptions as F, type GsiDefinition as G, type ResolvedKey as H, type Item as I, type CdcEmulatorOptions as J, type KeyDefinition as K, type ChangeHandler as L, type ModelStatic as M, type Unsubscribe as N, type FaultSpec as O, type PutInput as P, type ConcurrentRecomputeRef as Q, type ReadExecOptions as R, type SelectableOf as S, type TransactWriteExecItem as T, type UpdateInput as U, type EventLog as V, type WriteExecOptions as W, type ReplayOptions as X, type ShardId as Y, type RelationMetadata as Z, type TransactionItemSpec as _, type ExecutorResult as a, type ContractKeySpec as a$, type ParamDescriptor as a0, type DefinitionMap as a1, type OperationDefinition as a2, type WriteDefinitionOptions as a3, type PartialQueryKeyOf as a4, type StrictSelectSpec as a5, type EntityInput as a6, type UniqueQueryKeyOf as a7, type EntityRef as a8, type ConditionInput as a9, type CollectionEffect as aA, type CollectionOptions as aB, type Column as aC, type ColumnMap as aD, type CommandContractMethodSpec as aE, type CommandInputShape as aF, type CommandMethod as aG, type CommandPlan as aH, type CommandResolutionTarget as aI, type CommandResultKind as aJ, type CommandSelectShape as aK, type CompiledFragment as aL, type ComposeSpec as aM, type CondSlot as aN, type ConditionCheckInput as aO, type Connection as aP, type ContractCallSignature as aQ, type ContractCardinality as aR, type ContractCommandParams as aS, type ContractCommandResult as aT, type ContractComposeNode as aU, type ContractFromRef as aV, type ContractInputArity as aW, type ContractItem as aX, type ContractKeyFieldRef as aY, type ContractKeyInput as aZ, type ContractKeyRef as a_, type QueryModelContract as aa, type QueryMethodSpec as ab, type CommandModelContract as ac, type CommandMethodSpec as ad, type ContractSpec as ae, type QuerySpec as af, type CommandSpec as ag, type ContextSpec as ah, type OperationsDocument as ai, type AnyOperationDefinition as aj, type BridgeBundle as ak, type ConditionSpec as al, type AggregateMetadata as am, type BatchDeleteRequest as an, type BatchGetOptions as ao, type BatchGetRequest as ap, BatchGetResult as aq, type BatchPutRequest as ar, type BatchResult as as, type BatchWriteRequest as at, CONTRACT_RANGE_FANOUT_CONCURRENCY as au, type CdcMode as av, type Change as aw, type ChangeBatch as ax, type ChangeEventName as ay, type ClockMode as az, type WriteResult as b, type MutationInputProxy as b$, type ContractKind as b0, type ContractMethodOp as b1, type ContractParamRef as b2, type ContractQueryParams as b3, type ContractResolution as b4, type CounterAggregate as b5, type CounterEffect as b6, type CtxBase as b7, DEFAULT_MAX_ATTEMPTS as b8, DEFAULT_RETRY_POLICY as b9, type KeyedResult as bA, LIFECYCLE_CONTRACT_MARKER as bB, type LifecycleContract as bC, type LifecycleEffects as bD, type LiteralParam as bE, type MaintainConsistency as bF, type MaintainEffect as bG, type MaintainEvent as bH, type MaintainItem as bI, type MaintainTrigger as bJ, type MaintainUpdateMode as bK, type MaintenanceGraph as bL, type ManifestEntity as bM, type ManifestField as bN, type ManifestFieldType as bO, type ManifestGsi as bP, type ManifestKey as bQ, type ManifestRelation as bR, type ManifestTable as bS, type ModelRef as bT, type MutateMode as bU, type MutateOptions as bV, type MutateParallelResult as bW, type MutateTransactionResult as bX, type MutationBody as bY, type MutationDescriptorMap as bZ, type MutationFragment as b_, type DeleteOptions as ba, type DeriveEffect as bb, type DerivedEdgeWrite as bc, type DerivedUpdate as bd, type DescriptorBinding as be, ENTITY_WRITES_MARKER as bf, type EdgeEffect as bg, type EffectPath as bh, type EmbeddedMetadata as bi, type EmitEffect as bj, type EntityWritesDefinition as bk, type EntityWritesShape as bl, type ExecutableCommandContract as bm, type ExecutableQueryContract as bn, type FilterInput as bo, type FilterSpec as bp, type FragmentInput as bq, type GsiDefinitionMarker as br, type GsiOptions as bs, type IdempotencyEffect as bt, type InProcessWriteDescriptor as bu, type InputArity as bv, type KeyDefinitionMarker as bw, type KeySegment as bx, type KeySlot as by, type KeyStructure as bz, type DeleteInput as c, type WriteKind as c$, type MutationInputRef as c0, type MutationIntent as c1, type NumberParam as c2, type OperationKind as c3, type OperationSpec as c4, type ParallelOpResult as c5, type ParamKind as c6, type ParamSpec as c7, type ParamStructure as c8, type PersistCtx as c9, type RelationSelect as cA, type RelationSpec as cB, type RelationUpdateMode as cC, type RelationWriteOptions as cD, type RequiresEffect as cE, type Resolution as cF, type RetryInfo as cG, type RetryOperationKind as cH, SPEC_VERSION as cI, type SegmentSpec as cJ, type SegmentedKey as cK, type SelectBuilder as cL, type SelectOf as cM, type SnapshotEffect as cN, type StartingPosition as cO, type StreamViewType as cP, type StringParam as cQ, TransactionContext as cR, type TransactionItemType as cS, type UniqueEffect as cT, type Updatable as cU, type UpdateOptions as cV, type WhenSpec as cW, type WriteCtx as cX, type WriteDescriptor as cY, type WriteEnvelope as cZ, type WriteInput as c_, type PersistOrigin as ca, type PlannedCommandMethod as cb, type ProjectionMap as cc, type ProjectionTransform as cd, type ProjectionTransformOp as ce, type PutOptions as cf, type QueryContractMethodSpec as cg, type QueryEnvelopeResult as ch, type QueryKeyOf as ci, type QueryMethod as cj, type QueryResult as ck, type RangeConditionSpec as cl, type ReadEnvelope as cm, type ReadOpCtx as cn, type ReadOpKind as co, type ReadOperationType as cp, type ReadRouteDescriptor as cq, type ReadRouteOptions as cr, type ReadRouteResult as cs, type RecordedCompose as ct, type RelationBuilder as cu, type RelationConsistency as cv, type RelationLimitOptions as cw, type RelationPattern as cx, type RelationProjection as cy, type RelationReadOptions as cz, type BatchWriteExecItem as d, resolveLifecycle as d$, type WriteLifecyclePhase as d0, type WriteMiddleware as d1, type WriteOperationType as d2, type WriteRecorder as d3, type WriteResultProjection as d4, attachModelClass as d5, buildDeleteInput as d6, buildMaintenanceGraph as d7, buildPutInput as d8, buildUpdateInput as d9, isContractFromRef as dA, isContractKeyFieldRef as dB, isContractKeyRef as dC, isContractParamRef as dD, isEntityWritesDefinition as dE, isKeySegment as dF, isLifecycleContract as dG, isMaintainTrigger as dH, isMutationFragment as dI, isMutationInputRef as dJ, isParam as dK, isPlannedCommandMethod as dL, isQueryModelContract as dM, isRetryableError as dN, isRetryableTransactionCancellation as dO, k as dP, key as dQ, lifecyclePhaseForIntent as dR, maintainTrigger as dS, mintContractKeyFieldRef as dT, mintContractParamRef as dU, mutation as dV, param as dW, preview as dX, publicCommandModel as dY, publicQueryModel as dZ, query as d_, compileFragment as da, compileMutationPlan as db, compileSingleFragmentPlan as dc, cond as dd, contractOfMethodSpec as de, definePlan as df, entityWrites as dg, executeBatchGet as dh, executeBatchWrite as di, executeCommandMethod as dj, executeDelete as dk, executeKeyedBatchGet as dl, executePut as dm, executeQueryMethod as dn, executeRangeFanout as dp, executeTransaction as dq, executeUpdate as dr, from as ds, getEntityWrites as dt, gsi as du, identity as dv, isColumn as dw, isCommandModelContract as dx, isCommandPlan as dy, isContractComposeNode as dz, type BatchExecOptions as e, wholeKeysSentinel as e0, DDBModel as f, type PrimaryKeyOf as g, type RequestContext as h, type Middleware as i, type ReadRequestKind as j, type CtxModel as k, type ReadParams as l, type ReadRequestCtx as m, type RetryPolicy as n, type ExecutionPlanSpec as o, type EntityMetadata as p, type DynamoType as q, type RelationOptions as r, type AggregateValue as s, type SelectBuilderSpec as t, type RawCondition as u, type TransactionSpec as v, type Manifest as w, type RetryOverride as x, type ExecutionPlan as y, type FieldMetadata as z };