graphddb 0.4.2 → 0.5.0

package/docs/spec.md

@@ -0,0 +1,1626 @@
+# GraphDDB — Interface Specification
+
+GraphDDB is a TypeScript library for modeling **graph-shaped data on Amazon
+DynamoDB** using the single-table / adjacency-list pattern. You declare entities
+and their access patterns (primary key, GSIs) and relations between them with
+TC39 decorators, and query them with a GraphQL-style "key + selection" API. The
+library resolves the access pattern, projects only the requested attributes,
+traverses relations (in parallel, bounded), and hydrates the raw items back into
+typed objects.
+
+This document is the **interface specification** for library consumers. Every
+signature, type, default, and behavior below is taken from the current source.
+
+> Version: `0.1.0`. Module type: ESM. Node `>=22`. Peer dependencies:
+> `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` (`^3.0.0`).
+
+### Related specifications
+
+This document is the **core API reference**. The following subsystems have their
+own specs:
+
+- [`cqrs-contract.md`](./cqrs-contract.md) — the CQRS Query / Command contracts.
+- [`python-bridge.md`](./python-bridge.md) — multi-language TypeScript→Python code
+  generation and runtime.
+- [`design-patterns.md`](./design-patterns.md) — the ten canonical DynamoDB
+  access-pattern designs (RFC #118 §1) and how each maps to a graphddb feature.
+- [`cdc-emulator.md`](./cdc-emulator.md) — the Change Data Capture emulator for
+  local development and tests.
+- [`testing.md`](./testing.md) — the in-memory test adapter (`graphddb/testing`).
+- [`middleware.md`](./middleware.md) — host-side read & write middleware / hooks
+  (`DDBModel.use`): read R1–R5, write W1–W5, registration, per-call `context`,
+  ordering, cancellation / recovery, and Python parity.
+
+For a comparison against other DynamoDB libraries, see
+[`../benchmark/RESULTS.md`](../benchmark/RESULTS.md).
+
+---
+
+## Table of contents
+
+1. [Concepts and architecture](#1-concepts-and-architecture)
+2. [Connection and client configuration](#2-connection-and-client-configuration)
+3. [Defining entities](#3-defining-entities)
+4. [Field types and the type system](#4-field-types-and-the-type-system)
+5. [Keys and GSIs](#5-keys-and-gsis)
+6. [Embedded objects](#6-embedded-objects)
+7. [Relations](#7-relations)
+8. [The model API (`asModel`)](#8-the-model-api-asmodel)
+9. [Selecting fields (projection)](#9-selecting-fields-projection)
+10. [`query` — fetch a single item](#10-query--fetch-a-single-item)
+11. [`list` — query a partition](#11-list--query-a-partition)
+12. [Pagination and ordering](#12-pagination-and-ordering)
+13. [`filter` — server-side FilterExpression](#13-filter--server-side-filterexpression)
+14. [Post-load filtering](#14-post-load-filtering)
+15. [`cond` and `Model.col` — raw escape hatch](#15-cond-and-modelcol--raw-escape-hatch)
+16. [Relation traversal](#16-relation-traversal)
+17. [`explain` — execution plan](#17-explain--execution-plan)
+18. [Create / Put](#18-create--put)
+19. [Update](#19-update)
+20. [Delete](#20-delete)
+21. [Conditional writes](#21-conditional-writes)
+22. [The unified envelope — `DDBModel.query` / `DDBModel.mutate`](#22-the-unified-envelope--ddbmodelquery--ddbmodelmutate)
+23. [Batch operations](#23-batch-operations)
+24. [The Linter and design rules](#24-the-linter-and-design-rules)
+25. [Runtime responsibilities (pipeline)](#25-runtime-responsibilities-pipeline)
+26. [Error reference](#26-error-reference)
+27. [Public API surface](#27-public-api-surface)
+
+The running examples use the `examples/user-permissions` model
+(`Group`, `User`, `GroupMembership`, `Permission`) — a single-table,
+adjacency-list permissions graph.
+
+---
+
+## 1. Concepts and architecture
+
+**Single table, adjacency list.** All entities map to one DynamoDB table with a
+composite key `PK` (partition) / `SK` (sort). Each entity declares a `prefix`
+that is prepended to its partition key (`<prefix>#<pk>`), and a key mapping
+function that produces `{ pk, sk }`. Different entity types can share a partition
+(e.g. a `GROUP#eng` partition holds the group `META` item, its `USER#…`
+memberships, and its `PERM#…` permissions); they are distinguished by their `SK`
+shape. GSIs follow the same pattern with attributes `<indexName>PK` /
+`<indexName>SK`.
+
+**GraphQL-style separation.** A read is split into a **key** (the access-pattern
+input, dynamic values) and a **selection** (which fields, statically declared).
+This mirrors GraphQL's arguments + selection set.
+
+**Declarative metadata, no `reflect-metadata`.** Decorators record metadata into
+a module-level collector at class-definition time; the `@model` class decorator
+drains it into a `MetadataRegistry` entry. Key/GSI definitions are stored as
+static class properties and finalized lazily on first metadata access. The
+library does not depend on `reflect-metadata`.
+
+**Execution pipeline.** A read flows through these stages (each is a public
+module):
+
+```
+key + select
+  → key-resolver        (which access pattern: PK / GSI, full or partial)
+  → planner             (build DynamoDBOperation: GetItem vs Query, projection, filter)
+  → executor            (issue GetItem / Query / BatchGetItem via the AWS SDK)
+  → hydrator            (raw item → typed object: Date restore, embedded rebuild, selected fields only)
+  → relation traversal  (resolve nested relations, bounded-parallel)
+```
+
+Arbitrary post-load TypeScript filtering is not part of this pipeline; it is
+applied by the caller on the already-typed result (`result.items.filter(...)`,
+§14).
+
+---
+
+## 2. Connection and client configuration
+
+GraphDDB uses a process-global client (`ClientManager`) and an optional
+table-name remap (`TableMapping`). Configure them via the static methods on
+`DDBModel` before issuing any operation.
+
+```ts
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DDBModel } from 'graphddb';
+
+DDBModel.setClient(new DynamoDBClient({ region: 'us-east-1' }));
+
+// Optional: remap declared table names → physical table names (e.g. per stage).
+DDBModel.setTableMapping({ UserPermissions: 'UserPermissions-prod' });
+```
+
+| Method | Signature | Behavior |
+| --- | --- | --- |
+| `DDBModel.setClient` | `(client: DynamoDBClient) => void` | Stores the client globally and discards any cached document client. |
+| `DDBModel.setTableMapping` | `(mapping: Record<string, string>) => void` | Replaces the declared-name → physical-name map. |
+
+- The low-level marshalling uses a `DynamoDBDocumentClient` (`@aws-sdk/lib-dynamodb`),
+  created lazily from the configured client and cached. Values you pass and
+  receive are plain JS (un-marshalled).
+- If no client is set, the first operation throws:
+  `DynamoDB client is not configured. Call DDBModel.setClient(new DynamoDBClient({...})) first.`
+- `TableMapping.resolve(name)` returns the mapped physical name, or the declared
+  name unchanged when no mapping entry exists.
+
+---
+
+## 3. Defining entities
+
+An entity is a class extending `DDBModel`, annotated with `@model(...)` and field
+decorators. Key/GSI definitions are `static` class properties.
+
+```ts
+import { DDBModel, model, string, datetime, key, k, gsi, hasMany } from 'graphddb';
+
+@model({ table: 'UserPermissions', prefix: 'USER' })
+class UserModel extends DDBModel {
+  static readonly keys = key<{ userId: string }>((c) => ({
+    pk: k`USER#${c.userId}`,
+    sk: k`PROFILE`,
+  }));
+
+  static readonly emailIndex = gsi<{ email: string }>(
+    'GSI1',
+    (c) => ({ pk: k`EMAIL#${c.email}`, sk: k`PROFILE` }),
+    { unique: true },
+  );
+
+  @string userId!: string;
+  @string name!: string;
+  @string email!: string;
+  @string status!: string;
+  @datetime createdAt!: Date;
+
+  @hasMany(() => GroupMembershipModel, { userId: 'userId' }, {
+    limit: { default: 20, max: 100 },
+  })
+  groups!: GroupMembershipModel[];
+}
+```
+
+### `@model(options)`
+
+```ts
+interface ModelOptions {
+  table: string;    // declared table name (resolved through TableMapping)
+  prefix?: string;  // PK prefix; derived from the class name when omitted
+}
+```
+
+- Applied to the class, it drains all field / embedded / relation metadata
+  collected by the field decorators above it and registers an `EntityMetadata`
+  entry.
+- **PK prefix rule** (`derivePrefix`):
+  - explicit `prefix: 'USER'` → stored as `USER#` (a `#` is appended);
+  - omitted → derived from the class name, stripping a trailing `Model`
+    (`UserModel` → `User#`); the class name must be available or registration
+    throws.
+- Registration runs the **linter** (see §24); error-severity rule violations
+  throw at finalization time.
+
+### `EntityMetadata`
+
+The registered shape (exported as a type) is:
+
+```ts
+interface EntityMetadata {
+  tableName: string;
+  prefix: string;                    // includes the trailing '#'
+  fields: FieldMetadata[];
+  primaryKey: KeyDefinition | null;
+  gsiDefinitions: GsiDefinition[];
+  relations: RelationMetadata[];
+  aggregates: AggregateMetadata[];   // scalar @aggregate fields (Epic #118 §5.2)
+  embeddedFields: EmbeddedMetadata[];
+}
+```
+
+`MetadataRegistry.get(class)` returns it (finalizing key/GSI/lint on first call)
+and throws if the class was never decorated with `@model`.
+
+`aggregates` holds the scalar `@aggregate` fields (a `counter` / latest preset —
+e.g. `postCount!: number ← count()`, `lastPostAt!: string ← max('createdAt')`;
+Epic #118 §5.2, issue #122). It is its own array, distinct from both `fields` (a
+plain stored attribute) and `relations` (a navigation): an aggregate carries a
+source binding like a relation but surfaces a scalar value like a field. The
+`@aggregate` `count()` counter is maintained end-to-end (an atomic `ADD ±1` on the
+counter row, composed into the same transaction as the source write, in both the
+TS runtime and the Python mirror; #141). A `max(field)` aggregate is recorded in
+the IR but loud-rejected on the synchronous path (it needs the stream path, #130;
+see §"Maintained relations" below).
+
+---
+
+## 4. Field types and the type system
+
+### Semantic field decorators
+
+Each scalar attribute is annotated with a **semantic decorator** that maps to a
+DynamoDB attribute type and is **bound to the declared TypeScript field type**.
+The decorator only type-checks against a field whose declared type is assignable
+to the decorator's type — e.g. `@string age!: number` is a **compile error**,
+while `@string name!: string` and optional `@string name?: string` pass.
+
+| Decorator | DynamoDB type (`DynamoType`) | Bound TS type | Notes |
+| --- | --- | --- | --- |
+| `@string` | `S` | `string` | |
+| `@number` | `N` | `number` | |
+| `@boolean` | `BOOL` | `boolean` | |
+| `@datetime` | `S` | `Date` | Serialized to ISO 8601; default `{ format: 'datetime' }`. |
+| `@binary` | `B` | `Uint8Array` | |
+| `@stringSet` | `SS` | `Set<string>` | |
+| `@numberSet` | `NS` | `Set<number>` | |
+| `@list` | `L` | `unknown[]` | |
+| `@map` | `M` | `Record<string, unknown>` | |
+| `@field(type, opts?)` | (explicit) | (untyped) | **Deprecated**, low-level escape hatch; not type-bound. |
+
+Semantic decorators are **dual-mode**: apply directly (`@string name`) or as a
+factory with options (`@string({ readonly: true }) id`).
+
+### `FieldOptions`
+
+```ts
+interface FieldOptions {
+  format?: 'datetime' | 'date';
+  readonly?: boolean;
+  serialize?: (value: unknown) => unknown;
+  deserialize?: (value: unknown) => unknown;
+}
+```
+
+- `@datetime` defaults to `format: 'datetime'`.
+- `readonly: true` fields can be written by `putItem` but cause `updateItem` to
+  **throw** if included in the changes (see §19).
+- `serialize` / `deserialize` override the default conversion (see §25).
+
+### Serialization / hydration of `Date`
+
+- **On write** (`serializeFieldValue`): a custom `serialize` wins; otherwise a
+  `Date` with `format: 'datetime'` → `value.toISOString()`, with `format: 'date'`
+  → `value.toISOString().split('T')[0]` (date-only `YYYY-MM-DD`).
+- **On read** (hydrator): a custom `deserialize` wins; otherwise an ISO string
+  with `format: 'datetime'` → `new Date(value)`, with `format: 'date'` →
+  `new Date(value + 'T00:00:00.000Z')`.
+
+### Derived projection / input types
+
+The type layer derives several mapped types from an entity `T`:
+
+- `SelectableOf<T>` — the selection spec: scalar → `true`, embedded → nested
+  `SelectableOf`, `hasMany` (`E[]`) / `belongsTo`·`hasOne` (`E | null`) → a
+  `RelationSpec<E>`. Functions are excluded.
+- `EntityInput<T>` — the `put` input: scalars kept with their declared type,
+  embedded recursed, **relations excluded** (relations are not written by `put`).
+- `ColumnMap<T>` — one `Column` per scalar field for `Model.col` (relations and
+  embedded excluded).
+
+---
+
+## 5. Keys and GSIs
+
+Access patterns are declared as **static class properties** assigned the result
+of `key(...)` / `gsi(...)`. The builder receives a typed **column accessor** `c`
+(one `Column` per input field) and returns `{ pk, sk }`, where each of `pk` / `sk`
+is built from the `` k`…` `` tagged template — a **structured key segment**.
+
+A `` k`USER#${c.userId}` `` template keeps its literal parts and the interpolated
+column references **structurally** (the columns are never stringified). This
+structure — not an opaque mapping closure — is the single source of truth for a
+model's key: both the runtime (concrete values) and the Python-bridge spec
+generator (`{field}` templates) read it directly, with no symbolic evaluation.
+
+`k` accepts **only typed column references** (`c.field`) as interpolations; a bare
+string interpolation throws at definition time, so a key field is always named via
+a refactor-safe column reference.
+
+### `key`
+
+```ts
+function key<T extends Record<string, unknown>>(
+  builder: (c: { readonly [K in keyof T]-?: Column<T[K], T> }) => KeyStructure,
+): KeyDefinitionMarker<T>;
+
+// k — the tagged-template segment builder
+function k(literals: TemplateStringsArray, ...columns: Column[]): KeySegment;
+
+interface KeyStructure {
+  readonly pk: SegmentSpec;       // single segment or an ordered list
+  readonly sk?: SegmentSpec;
+}
+type SegmentSpec = KeySegment | KeySegment[];
+```
+
+```ts
+// Composite primary key (PK segment + single SK segment):
+static readonly keys = key<{ groupId: string; userId: string }>((c) => ({
+  pk: k`GROUP#${c.groupId}`,
+  sk: k`USER#${c.userId}`,
+}));
+
+// Multi-segment sort key — pass an array of segments:
+static readonly keys = key<{ groupId: string; resource: string; action: string }>(
+  (c) => ({
+    pk: k`GROUP#${c.groupId}`,
+    sk: [k`PERM#${c.resource}`, k`${c.action}`],
+  }),
+);
+```
+
+- The **type parameter `T`** is the key input type (it drives compile-time key
+  checking for `query` / `list`). The accessor `c` exposes one `Column` per field
+  of `T`.
+- The input field names are collected from the column references across the PK
+  then SK segments, in first-seen order (e.g. `['groupId', 'userId']`). This set
+  is what the resolver matches query keys against and what the type layer uses to
+  derive key types.
+- The `pk` is later prefixed (`<prefix>#<pk>`). A **multi-segment** SK (or PK) is
+  joined with the delimiter `#`.
+- An entity has at most one `key` (primary key). Type-level: `key`'s input type
+  `T` becomes `PrimaryKeyOf<C>`.
+
+**Partial keys and `begins_with`.** Segments are a **truncation boundary**. When a
+read supplies only a *contiguous prefix* of the SK segments (e.g. `{ groupId,
+resource }` against the `[PERM#{resource}, {action}]` SK above), the SK condition
+compiles to a `begins_with` at the first incomplete segment, closed with that
+segment's leading literal followed by a trailing `#` so the prefix cannot bleed
+into a longer sibling token (`PERM#read#` does not match `PERM#readonly`). A
+*non-contiguous* selection (a later segment supplied while an earlier one is
+missing, or only some fields of a multi-field segment) is a resolve error.
+
+### `gsi`
+
+```ts
+function gsi<T extends Record<string, unknown>>(
+  indexName: string,
+  builder: (c: { readonly [K in keyof T]-?: Column<T[K], T> }) => KeyStructure,
+  options?: { unique?: boolean },
+): GsiDefinitionMarker<T, boolean>;
+```
+
+```ts
+static readonly emailIndex = gsi<{ email: string }>(
+  'GSI1',
+  (c) => ({ pk: k`EMAIL#${c.email}`, sk: k`PROFILE` }),
+  { unique: true },
+);
+```
+
+- The builder uses the same `` k`…` `` structured-segment form as `key`.
+- `unique: true` declares that the index resolves to a **single item**, which
+  makes it usable by `query()`. Non-unique (default) GSIs are list-only.
+- Multiple GSIs are allowed. The GSI attribute names written/queried are
+  `<indexName>PK` / `<indexName>SK`.
+
+### Derived key types
+
+From the model class `C` (the constructor, supplied automatically by `asModel`):
+
+| Type | Contents | Used by |
+| --- | --- | --- |
+| `PrimaryKeyOf<C>` | PK input only | `deleteItem()` key |
+| `UniqueQueryKeyOf<C>` | PK + **unique** GSI inputs | `query()` key (must resolve to one item) |
+| `QueryKeyOf<C>` | PK + **all** GSI inputs | (constraint label) |
+| `PartialQueryKeyOf<C>` | "at least one field" relaxation of `QueryKeyOf` | `list()` / `explain()` key |
+
+`PartialQueryKeyOf` permits a **partial** key (the partition-key subset; the
+sort-key tail is optional), because `list`/`explain` issue a Query against a
+partition. `query()` stays strict.
+
+### Access-pattern resolution (`resolveKey`)
+
+Given the set of fields present in the supplied key, the resolver matches in this
+**priority order**:
+
+1. **Exact PK match** — query fields equal the PK input field set → PK access,
+   full key.
+2. **Exact GSI match** — equal to a GSI input field set → that GSI (carrying its
+   `unique` flag).
+3. **Partial PK match** — a non-empty strict subset of the PK input fields that
+   still produces a valid (non-`undefined`) partition key → PK access, partial.
+4. **Partial GSI match** — same, for a GSI → that GSI, partial (treated as
+   non-unique), with a `begins_with` range condition on the sort key.
+
+If nothing matches, the resolver **throws** `No access pattern found for fields
+[...]` listing the available patterns. "Produces a valid PK" is checked by
+calling the mapping function with placeholder values and rejecting outputs that
+are `undefined`/`null` or that stringify to contain `"undefined"`.
+
+> Example (from `user-permissions`): `GroupMembership` has PK input
+> `[groupId, userId]` and `GSI1` input `[userId, groupId]` (with `groupId`
+> optional). Querying with `{ userId }` is an **exact GSI match** (priority 2)
+> and resolves to `GSI1`, not a partial PK match.
+
+---
+
+## 6. Embedded objects
+
+An embedded object is a nested non-`DDBModel` structure stored inline as a
+DynamoDB Map (`M`) attribute, declared with `@embedded`.
+
+```ts
+@embedded(() => AddressModel)
+address!: AddressModel;
+```
+
+- The decorator records `{ propertyName, modelFactory }` (a lazy `() => Class`).
+- On `put`, an embedded value present on the item is written as-is under its
+  property name (in addition to scalar fields).
+- On `update`, top-level keys of an embedded object are flattened into nested
+  `SET`/`REMOVE` paths (`#emb.#field = …`) — see §19.
+- On read, the hydrator reconstructs the embedded object from the Map, recursing
+  into nested embedded selects.
+- Embedded fields are part of `SelectableOf` (nested `{ field: true }`
+  projection) and `EntityInput`, but are **excluded** from `ColumnMap` /
+  `FilterInput` (filters target scalar fields only).
+
+---
+
+## 7. Relations
+
+Relations connect entities along their key bindings. Three decorators:
+
+```ts
+function hasMany(
+  targetFactory: () => Constructor,
+  keyBinding: Record<string, string>,   // { targetField: parentSourceField }
+  options?: RelationOptions,
+): FieldDecorator;
+
+function belongsTo(targetFactory, keyBinding, options?: RelationOptions): FieldDecorator;
+function hasOne(targetFactory, keyBinding): FieldDecorator;
+```
+
+| Type | Field shape | Resolved via | Cardinality |
+| --- | --- | --- | --- |
+| `hasMany` | `Target[]` | Query against the target's partition | many |
+| `belongsTo` | `Target \| null` | `BatchGetItem` (N parents → one batch) | one |
+| `hasOne` | `Target \| null` | `BatchGetItem` | one |
+
+```ts
+@hasMany(() => GroupMembershipModel, { groupId: 'groupId' }, {
+  limit: { default: 50, max: 200 },
+})
+members!: GroupMembershipModel[];
+
+@belongsTo(() => GroupModel, { groupId: 'groupId' })
+group!: GroupModel | null;
+```
+
+- **`keyBinding`** maps `{ targetField: sourceField }`: the relation's query key
+  is built by reading `sourceField` from the (raw) parent item and binding it to
+  `targetField` on the target. The bound target fields must form a resolvable
+  access pattern on the target entity (enforced by the `missing-gsi` linter rule;
+  see §24).
+- **`RelationOptions`** (accepted by `hasMany` and `belongsTo`):
+  ```ts
+  interface RelationOptions {
+    limit?: { default: number; max: number };
+    order?: 'ASC' | 'DESC';
+    // ── maintained access path (Epic #118; optional) ──
+    pattern?: RelationPattern;          // e.g. 'embeddedSnapshot' | 'samePartition' | …
+    read?: { maxItems?: number; order?: 'ASC' | 'DESC' };
+    write?: {
+      maintainedOn?: string[];          // cross-entity triggers, e.g. ['Post.created']
+      consistency?: 'transactional' | 'eventual';
+      updateMode?: 'mutation' | 'stream';
+    };
+    projection?: Record<string, ProjectionTransform | string>;
+  }
+  ```
+  `limit.default` is used when the relation select supplies no `limit`. `order`
+  is the default scan direction. (The `max` is consumed by the `require-limit`
+  linter rule; it is not separately enforced as a runtime cap in the traversal.)
+- `hasOne` takes **no** options. `belongsTo` accepts `RelationOptions` (it carries
+  no `limit`/`order` read semantics, but takes the maintenance options below for a
+  single-row `embeddedSnapshot`).
+- `targetFactory` is a thunk (`() => Class`) to allow circular references.
+
+### Maintained relations (Epic #118)
+
+> **See also:** [`design-patterns.md`](./design-patterns.md) maps the ten
+> canonical DynamoDB access-pattern designs (RFC #118 §1) to the graphddb feature
+> that implements each, with minimal code and the per-phase support status.
+
+Omitting `pattern` leaves a relation a plain **read-only navigation** (the
+historical behaviour, fully backward compatible). Declaring `pattern` turns the
+relation into a **maintained access path**: a single mutation on the *source*
+entity keeps a denormalized shape on the *owner* row in sync.
+
+```ts
+@hasMany(
+  () => PostModel,
+  { threadId: 'threadId' },
+  {
+    pattern: 'embeddedSnapshot',
+    read:  { maxItems: 3, order: 'DESC' },
+    write: { maintainedOn: ['Post.created'] },
+    projection: { postId: 'postId', textPreview: preview('$.entity.body', 120) },
+  },
+)
+latestPosts!: PostModel[];           // a collection embeddedSnapshot
+```
+
+Shared vocabulary (confirmed across the epic):
+
+- **`pattern`** — the named maintenance preset. `embeddedSnapshot` (a `hasMany`
+  collection or a `belongsTo` single-row mirror) and `samePartition` are declared
+  on the relation decorators (Phase 1). The view presets that live on a **separate
+  view model** — `materializedView` / `sparseView` — are declared with `@model({ kind })`
+  + `@maintainedFrom` (§7.1 below). The **versioned** presets ride the `@hasOne` /
+  `@hasMany` `pattern` discriminated union (`versionedLatest` / `versionedHistory`).
+  External projection is being redesigned as a typed-consumer-IF contract (#153) and
+  has no decorator. Unknown values on a relation are accepted by the open-ended union
+  but not lowered.
+- **`write.maintainedOn`** — cross-entity triggers `"<Entity>.<event>"`. The
+  Entity segment is the **logical** entity name (`PostModel → 'Post'`; or the
+  `@model({ prefix })` value sans `#`), and the event is one of
+  `created | updated | removed`.
+- **`write.consistency`** — `transactional` (same `TransactWriteItems`) or
+  `eventual`. **`write.updateMode`** — `mutation` (synchronous, same transaction)
+  or `stream` (asynchronous outbox→CDC-drain; §7.2). Both are now realized.
+- **`projection`** — the **function-form IR** mapping each captured owner
+  attribute to how the source value is projected: `preview('$.entity.body', 120)`
+  (the `preview` / `identity` helpers), or a bare string for the identity
+  shorthand (`postId: 'postId'`). Projection sources are the written source payload
+  (`$.entity.*` / `$.input.*`).
+
+**Synchronous (`updateMode: 'mutation'`)** maintainers lower to a maintenance write
+folded into the **same** `TransactWriteItems` as the source write (atomic with it):
+a `belongsTo` snapshot re-projects the single mirrored row in place; a `hasMany`
+collection appends a projected item (a `list_append`). On the synchronous path a
+collection is **append-only** — `read.maxItems` trim and `removed`-driven splices
+need a read-modify-write and are therefore the **stream** path (§7.2). Two
+maintainers targeting the same owner row in one mutation is a loud reject ("1
+mutation × 1 target row = 1 effect"). The maintenance graph is built by
+`buildMaintenanceGraph()` (`src/relation/maintenance-graph.ts`) and injected at
+compile time (`src/spec/mutation-command.ts`). A runnable example is
+`examples/embedded-snapshot-pattern/`.
+
+The scalar **`@aggregate` counter** (RFC §5.2 `pattern: 'counter'`) is the
+maintenance-pipeline sibling of the snapshot/collection maintainers (§3). A
+`count()` counter is maintained end-to-end synchronously (an atomic, concurrency-
+safe `ADD ±1` composed into the source write's transaction); a `max(field)`
+counter needs a conditional `SET` and so is the **stream** path (a loud reject on
+the synchronous `mutation` path — `src/spec/mutation-command.ts`). A runnable
+example is `examples/aggregate-counter/`.
+
+### 7.1 Maintained view models — `@model({ kind })` + `@maintainedFrom`; versioned `pattern` union (Phase 2/3)
+
+`embeddedSnapshot` / `counter` maintain a shape **on a row of an existing entity**
+(keyed by the source's own key binding). The materialized-data patterns that need
+a **distinct view model** — one whose rows exist only to serve a read — are
+declared **decorator-declaratively** (issue #152): a maintained view is its own
+`@model({ kind: 'materializedView' | 'sparseView' })`, fed by class-level
+`@maintainedFrom` decorators. Each lowers to the **same maintenance IR** the relation
+decorators produce (via `src/relation/maintenance-view-adapter.ts`), so the
+maintenance graph, the stream drain (§7.2), and the rebuild planner (§7.3) consume
+them identically — the IR is byte-invariant versus the previous builder.
+
+**`@maintainedFrom(source, (self, source) => options)`** — a class-level, **stackable**
+view maintainer. The callback is symbolic: `source.<field>` is a typed reference to a
+source field (lowering to the payload-rooted value the IR reads, typed `keyof Source`),
+`self.<field>` names a view field (the `collection.field` position), and `keyBind` /
+`project` KEYS are typed `keyof Self` names. `on` is the event list (`created`/
+`updated`/`removed`) — the source is the first argument, so no `'Entity.event'` string
+is resolved. **Declaration order is meaningless**: two declarations writing the same
+projection target, the same `collection.field`, or a different view-key field SET are a
+loud build error (no silent last-wins). A `sparseView` requires every declaration to
+carry a `when` membership predicate (built with `whenMember(source.field, op, value?)`),
+mutually exclusive with `collection`.
+
+```ts
+@model({ table: 'AppTable', prefix: 'UTL', kind: 'materializedView' })
+@maintainedFrom(() => PostModel, (self, source) => ({
+  keyBind:    { userId: source.userId },
+  on:         ['created', 'removed'],
+  project:    { postId: source.postId, textPreview: preview(source.body, 120) },
+  collection: { field: self.recentPosts, maxItems: 3, order: 'DESC', orderBy: source.createdAt },
+  updateMode: 'stream',
+}))
+@maintainedFrom(() => ThreadModel, (_self, source) => ({
+  keyBind: { userId: source.userId }, on: ['updated'],
+  project: { threadTitle: source.title }, updateMode: 'stream',
+}))
+class UserThreadListModel extends DDBModel { /* keys, fields */ }
+```
+
+**Versioned (`@hasOne` / `@hasMany` `pattern` union)** — versioned reuses the core
+snapshot effect, so it rides the relation `pattern` discriminator on the SOURCE
+(revision) model rather than a dedicated builder. `@hasOne(() => LatestModel,
+(self, source) => ({ pattern: 'versionedLatest', on, project }))` is the single
+overwritten latest pointer; `@hasMany(() => HistoryModel, (self, source) => ({ pattern:
+'versionedHistory', on, project }))` is the append-only history. Cardinality is type-
+enforced (`versionedLatest` only on `@hasOne`, `versionedHistory` only on `@hasMany`).
+The latest/history key binding is derived from each target model's own `key` fields
+(latest omits the version discriminator, history includes it). Both lower to the SAME
+composed snapshot×2 IR. (A self-co-located form is a deferred follow-up.)
+
+External projection's old `defineProjection` / `ProjectionSinkDrain` runtime was
+**removed in 0.4.0** and is being redesigned as a typed-consumer-IF contract (#153).
+
+### 7.2 Stream maintenance — outbox → CDC drain (`updateMode: 'stream'`, #130)
+
+A maintainer declaring `write: { updateMode: 'stream' }` is **not** composed into
+the source `TransactWriteItems`. Instead, the source write atomically emits a
+maintenance-outbox row (`MAINT_OUTBOX_PK_PREFIX = 'OUTBOX#MAINT#'`); a host-side
+CDC consumer then applies the owner-row write asynchronously. The stream path is
+what realizes the operations a single atomic transaction cannot express:
+
+- collection **trim** (`maxItems`) and `removed`-driven **splice** (read-modify-write);
+- the **`max(field)`** counter (a conditional `SET` whose failed guard must not roll
+  back the legitimate source write);
+- **sparse-view membership** (a row must be `PUT` when its predicate holds and
+  `DELETE`d when it flips — a branch a single transaction item cannot take).
+
+`createMaintenanceDrain({ models })` (and `createMaintenanceDrainHandler`)
+returns a `ChangeHandler` for the CDC emulator (`docs/cdc-emulator.md`) /
+DynamoDB Streams that de-duplicates per event id (at-least-once) and applies
+counters (`ADD` / conditional `max`), snapshots (`SET`), collections
+(read-modify-write order+trim), and membership (put/delete). The drain derives the
+view IR from the same declarative `models` (the view models, by their `@model({ kind })`
++ `@maintainedFrom`) — no separate `views` argument. External-sink projection delivery
+is the consumer's responsibility (redesign #153).
+
+### 7.3 Repair / rebuild planner (`createMaintenanceRebuilder`, #131)
+
+`createMaintenanceRebuilder({ models, views })` re-derives a maintained owner row
+from its **source rows** to detect and repair drift:
+
+- `.detectDrift(OwnerModel, relationProperty, ownerKey)` → a `DriftReport`
+  (`{ kind, drifted, expected, actual }`).
+- `.rebuild(OwnerModel, relationProperty, ownerKey)` → a `RebuildResult`
+  (`{ ...DriftReport, repaired }`), writing the **absolute** re-derived value
+  (a count is re-derived as a `SET`, not an `ADD`).
+
+It re-uses the shared re-derivation rules (`src/relation/maintenance-projection.ts`)
+so a rebuilt value is byte-consistent with what the drain converges to. It **loudly
+rejects** two cases it cannot faithfully reconstruct: an **unordered bounded
+collection** (`maxItems` with no `read.order` — the trimmed subset depends on stream
+arrival order) and a **sparse-view membership** maintainer (rebuild it by re-running
+the source events through the drain).
+
+---
+
+## 8. The model API (`asModel`)
+
+Operations are issued through a **model object** obtained from
+`Class.asModel()`, which returns a `ModelStatic<T, C>` whose key and select types
+are precisely inferred from the class.
+
+```ts
+export const User = UserModel.asModel();
+export const Group = GroupModel.asModel();
+export const GroupMembership = GroupMembershipModel.asModel();
+```
+
+> Call `asModel()` with **no** explicit type argument. Its generic is the
+> constructor type (`C extends new (...) => DDBModel`), inferred from the static
+> receiver; passing `asModel<UserModel>()` would wrongly supply the instance
+> type.
+
+`ModelStatic<T, C>` exposes:
+
+| Member | Kind | Summary |
+| --- | --- | --- |
+| `col` | `ColumnMap<T>` | typed column refs for `cond` (§15) |
+| `project(select)` | builder factory | top-level select builder (§9, §14) |
+| `relation(select)` | builder factory | relation select builder (§9, §14) |
+| `query(key, select, options?)` | read | single item by unique key (§10) |
+| `list(key, select, options?)` | read | partition query (§11) |
+| `explain(key, options?)` | plan | execution plan, no I/O (§17) |
+| `putItem(item, options?)` | write | create/overwrite (§18) |
+| `updateItem(entity, changes, options?)` | write | partial update (§19) |
+| `deleteItem(key, options?)` | write | delete (§20) |
+
+The static, class-level methods (`setClient`, `setTableMapping`, `query`,
+`mutate`, `batchGet`, `batchWrite`, `asModel`) live on `DDBModel` itself. The
+unified-envelope `DDBModel.query` / `DDBModel.mutate` (§22) drive multi-route
+reads and lifecycle-aware writes.
+
+---
+
+## 9. Selecting fields (projection)
+
+A **selection** describes which fields to return. Scalars are marked `true`,
+embedded objects are nested selections, and relations carry their own selection
+plus pagination/filter.
+
+```ts
+// SelectableOf<UserModel> form
+{
+  userId: true,
+  name: true,
+  groups: {                              // relation: plain object form
+    select: { groupId: true, role: true },
+    limit: 20,
+    filter: { role: 'admin' },           // server-side (§13)
+  },
+}
+```
+
+### Strictness
+
+Selections are **exact**: an unknown field key is a **compile error**
+(`StrictSelect` maps unknown keys to `never`). This applies at the top level and
+recursively into nested relation and embedded selects. The result type contains
+**only** the selected fields, computed by `QueryResult<T, S>`.
+
+### Relation selection forms
+
+A relation field accepts either:
+
+1. a plain object `{ select, limit?, after?, order?, filter? }` (`RelationSelect`), or
+2. a **model-bound builder** `Target.relation({ … }).filter(…).limit(…)…`.
+
+The builder form pins the relation's target type, so it structurally rejects
+another model's builder (closes #33). Both forms accept the same declarative
+server-side `filter` (§13); arbitrary post-load filtering is done on the result
+(§14).
+
+### Implicit key projection
+
+When a relation is selected, the parent's **key-binding source fields** must be
+read from the raw item to build the relation's query key. If such a field is not
+already projected, it is added to the projection automatically
+(`getImplicitKeyFields`) so traversal works without you having to select it.
+These implicit attributes are not added to the hydrated result unless you
+selected them.
+
+---
+
+## 10. `query` — fetch a single item
+
+```ts
+query<Sel>(
+  key: UniqueQueryKeyOf<C>,
+  select: Sel,
+  options?: { consistentRead?: boolean; maxDepth?: number },
+): Promise<QueryResult<T, Sel> | null>;
+```
+
+Fetches a single item by a **full unique key** (PK or a unique GSI). Returns the
+projected object, or `null` if not found.
+
+```ts
+const alice = await User.query(
+  { email: 'alice@example.com' },        // unique GSI
+  {
+    userId: true, name: true, email: true,
+    groups: { select: { groupId: true, role: true }, limit: 20 },
+  },
+  { maxDepth: 2 },
+);
+```
+
+Behavior:
+
+- `key` must match the PK input set or a **unique** GSI input set. Resolving to a
+  **non-unique** GSI throws: `Cannot use query() with non-unique GSI '...'. Use
+  list() instead.`
+- `options.maxDepth` defaults to **1**. Relation depth beyond `maxDepth` throws
+  (see §16).
+- `options.consistentRead` is honored for PK queries only. (DynamoDB forbids
+  consistent reads on GSIs; the planner throws if `consistentRead` is requested
+  on a GSI — see §13/§25.)
+- The top-level `select` may be a `Model.project(...)` builder; its server-side
+  `filter` is applied during the read.
+- Internally, a full-key PK read with no server-side filter is a `GetItem`;
+  otherwise it is a `Query` (§25).
+
+---
+
+## 11. `list` — query a partition
+
+```ts
+list<Sel>(
+  key: PartialQueryKeyOf<C>,
+  select: Sel,               // plain projection or a project(...) builder
+  options?: {
+    limit?: number;
+    after?: string;          // pagination cursor
+    order?: 'ASC' | 'DESC';
+    filter?: FilterInput<T>; // server-side FilterExpression (§13)
+  },
+): Promise<{ items: QueryResult<T, Sel>[]; cursor: string | null }>;
+```
+
+The signature is symmetric with `query(key, select, options?)`: `select` is a
+**separate 2nd argument**, not a key inside the `options` object.
+
+Issues a DynamoDB **Query** against a partition (PK or GSI) and returns the
+projected items plus a pagination `cursor`.
+
+```ts
+const admins = await GroupMembership.list(
+  { groupId: 'eng' },
+  { userId: true, role: true },
+  { filter: { role: 'admin' } },
+);
+admins.items;   // [{ userId, role }, …]
+admins.cursor;  // string | null
+```
+
+Behavior:
+
+- `key` may be a **partial** key (partition-key subset). A partial GSI key adds a
+  `begins_with` range condition on the GSI sort key.
+- `filter` is the declarative server-side `FilterExpression` (§13). It is
+  **not** RCU-reducing and is applied **after** `limit` (§12, §13).
+- When `select` is a `project(...)` builder, an explicit `options` value
+  (`filter` / `after` / `limit` / `order`) **takes precedence** over the
+  builder's value of the same name.
+- `query()` differs from `list()` in three ways: `list` accepts partial keys,
+  always uses Query (never GetItem), and returns an array + cursor instead of a
+  single nullable item.
+
+---
+
+## 12. Pagination and ordering
+
+- **Cursor.** `cursor` (returned by `list`) is the base64url-encoded DynamoDB
+  `LastEvaluatedKey`. Pass it back as `after` to continue. `null` means the last
+  page. `encodeCursor` / `decodeCursor` are exported for advanced use.
+- **Order.** `order: 'ASC' | 'DESC'` sets the Query `ScanIndexForward`
+  (`ASC` → `true`). Default is `ASC`.
+- **`limit` vs `filter`.** DynamoDB applies `Limit` to the **read**, before the
+  `FilterExpression`. Consequently:
+  - a page may return **fewer than `limit`** items even when more matches exist
+    further in the partition;
+  - an entirely filtered-out page may still return a **non-null `cursor`**;
+  - the cursor reflects the **pre-filter** read position. Post-load filtering on
+    the result (`result.items.filter(...)`, §14) likewise does not change the
+    cursor.
+
+---
+
+## 13. `filter` — server-side FilterExpression
+
+`filter` is a **declarative, server-side** DynamoDB `FilterExpression`, modeled
+on AWS AppSync's `ModelFilterInput`. It is typed against the **full entity**
+(`FilterInput<T>`), so it may reference attributes that are **not in the
+projection**, and operators are constrained per field type.
+
+```ts
+type FilterInput<T> =
+  | ({ [K in ScalarKeys<T>]?: T[K] | FieldCondition<T[K]> } & {
+      and?: readonly (FilterInput<T> | RawCondition<T>)[];
+      or?:  readonly (FilterInput<T> | RawCondition<T>)[];
+      not?: FilterInput<T> | RawCondition<T>;
+    })
+  | RawCondition<T>;  // a whole `cond`…`` fragment (§15)
+```
+
+A field key takes either an **equality shorthand** (a bare value) or an
+**operator object**. Multiple field keys, and multiple operators within one
+field object, are joined with implicit `AND`.
+
+### Operators and their type constraints
+
+| Operator | Expression | Valid on |
+| --- | --- | --- |
+| `eq` | `#f = :v` | all scalars |
+| `ne` | `#f <> :v` | all scalars |
+| `in` | `#f IN (:v0, …)` | all scalars (`readonly V[]`) |
+| `attributeExists` | `attribute_exists(#f)` / `attribute_not_exists(#f)` (when `false`) | all scalars (`boolean`) |
+| `attributeType` | `attribute_type(#f, :v)` | all scalars (`string` type code) |
+| `gt` `ge` `lt` `le` | `#f > / >= / < / <= :v` | string, number, Date |
+| `between` | `#f BETWEEN :lo AND :hi` | string, number, Date (`readonly [V, V]`) |
+| `beginsWith` | `begins_with(#f, :v)` | **string only** |
+| `contains` | `contains(#f, :v)` | **string only** |
+| `notContains` | `NOT contains(#f, :v)` | **string only** |
+| `size` | `size(#f) = :v` | **string only** (`number`) |
+
+Type binding (`FieldCondition<V>`): string → common + comparable + string-only;
+number → common + comparable; Date → common + comparable; boolean / other →
+common only. So `beginsWith` on a numeric field, or `gt: 'x'` on a number field,
+is a **compile error**.
+
+### Logical groups
+
+```ts
+filter: { or: [{ role: 'admin' }, { role: 'viewer' }] }
+filter: { and: [{ role: { attributeExists: true } }, { not: { role: 'viewer' } }] }
+```
+
+### Compilation and semantics
+
+- Compiled by `compileFilterExpression` into a `FilterExpression` with `#`-aliased
+  names (one alias per distinct column, reused) and fresh `:`-aliased,
+  **parameterized** values (serialized per field type — e.g. `Date` → ISO). There
+  is **no literal interpolation**: the compiler is injection-free.
+- The compiled filter is attached **independently** of the
+  `KeyConditionExpression` and `ProjectionExpression`. Its names/values are merged
+  by the executor.
+- **RCU is not reduced.** DynamoDB reads matching keys first, then filters; a
+  filter does not lower read capacity, and `limit` applies before the filter
+  (§12).
+- A field given an empty / no-op operator object compiles to nothing; an entirely
+  empty filter is skipped.
+- On a **`belongsTo` / `hasOne`** relation (resolved via `BatchGetItem`, which has
+  no server-side filter), a declarative `filter` is evaluated **client-side**
+  against the resolved item (`evaluateFilter`). On **`hasMany`** relations and at
+  the top level, the filter is pushed **server-side**.
+
+---
+
+## 14. Post-load filtering
+
+For logic the server-side `filter` (§13) cannot express, call
+`result.items.filter(...)` on the already-typed projection. Because `query` /
+`list` return a fully typed `QueryResult<T, S>`, this stays type-safe (selected
+fields carry their declared scalar types; an unselected field is a compile error).
+There is **no built-in post-load predicate** — the former `refine` builder was
+removed (see CHANGELOG), keeping the select API fully declarative and serializable.
+
+---
+
+## 15. `cond` and `Model.col` — raw escape hatch
+
+For conditions the declarative operators cannot express, use the `cond` tagged
+template. Column names **must** be embedded via `Model.col.<field>` references
+(bare strings are rejected); values are embedded directly and parameterized.
+
+```ts
+import { cond } from 'graphddb';
+
+filter: cond`${GroupMembership.col.role} = ${'admin'}`
+filter: cond`${User.col.age} > ${18} and attribute_exists(${User.col.email})`
+```
+
+- `Model.col` is a `ColumnMap<T>`: one `Column<V, M>` per scalar field, carrying
+  the declared value type and **branded to the owning model**. Passing another
+  model's column into this model's `cond` is a compile error. Relations and
+  embedded objects are excluded from `col`.
+- A `RawCondition<M>` produced by `cond` is assignable wherever a
+  `FilterInput<M>` of the **same** model is expected — as a whole filter, inside
+  `and` / `or`, or as `not`.
+- `cond` is **not read-only**: it is equally a valid `WriteCondition<M>` (issue
+  #114-B), so it may be used as a write `condition` on `putItem` / `updateItem` /
+  `deleteItem`, on a transaction item / `ConditionCheck`, and in the declarative
+  `mutation(...)` / public command `condition` (where its value slots may carry
+  `param.*` bindings — see [cqrs-contract](./cqrs-contract.md)).
+  - **Nesting constraint (serializable surfaces):** a `cond` used as a **whole**
+    condition is fully supported everywhere. A `cond` **nested inside** a
+    declarative `and` / `or` / `not` group works **in-process** (TS/memory), but
+    a serializable (public-contract / Python-bridge) command **rejects it at
+    build time** with an explicit error — the serialized `expr` tree carries no
+    raw fragment. Move the `cond` to the top level, or express the group
+    declaratively.
+- At compile time the column refs become `#`-aliased names and values become
+  `:`-aliased parameters, sharing the same allocators as the declarative filter
+  compiler so aliases never collide. The escape hatch is therefore also
+  injection-free.
+- `Column` references are plain attribute names (refactor-safe); they are not
+  bare strings, so renaming the field through the type system surfaces breaks.
+
+---
+
+## 16. Relation traversal
+
+When a selection includes relation fields, the runtime resolves them after the
+parent items are read and hydrated.
+
+### Depth control
+
+- `maxDepth` (a `query` / `explain` option) bounds traversal depth, **default 1**
+  (parent → direct relations). The top-level item is depth 1; its relations are
+  validated against `maxDepth`.
+- Selecting relations deeper than `maxDepth` throws at runtime
+  (`validateDepth`): `Relation traversal depth exceeded: '<field>' at depth N
+  exceeds maxDepth M. Set maxDepth: N to allow this.`
+- Static analysis: the `relation-depth` linter rule **warns** at registration if
+  an entity's relation graph can exceed the default depth of 1 (see §24).
+
+### Resolution mechanics
+
+- **`hasMany`** resolves via `executeListInternal` (a Query) against the target's
+  partition, using the key built from `keyBinding`. The relation's effective
+  `limit` is `selectSpec.limit ?? rel.options.limit.default ?? 20`; `order` is
+  `selectSpec.order ?? rel.options.order ?? 'ASC'`. A declarative `filter` is
+  pushed **server-side**.
+- **`belongsTo` / `hasOne`** resolve via **`BatchGetItem`**: the runtime collects
+  one query key per parent that has a complete binding, **deduplicates** the
+  resulting DynamoDB keys, splits them into chunks of `BATCH_GET_MAX_KEYS` (100),
+  and matches results back to each parent slot. This collapses the N+1 problem
+  into a single batch (N memberships → one `BatchGetItem`, not N `GetItem`s).
+  Their declarative `filter` runs **client-side** (§13).
+- Each relation also recurses into its own nested relations (subject to
+  `maxDepth`).
+
+### Parallel execution
+
+Independent traversal work is dispatched **concurrently with a bounded fan-out**
+(`mapWithConcurrency`), capped by `RELATION_TRAVERSAL_CONCURRENCY` (**16**):
+
+- sibling relations of the same parent (e.g. `members` and `permissions`) resolve
+  in parallel — each writes a distinct property, so completion order is
+  irrelevant;
+- per-item nested resolution of `belongsTo`/`hasOne` batches runs in parallel;
+- `BatchGetItem` chunks (>100 keys) are issued in parallel (`Promise.all`),
+  preserving input order on flatten.
+
+DynamoDB is HTTP-based with an SDK-managed connection pool, so there is no
+per-connection serialization; the cap bounds in-flight requests to avoid throughput
+spikes. Set the constant to `Infinity` to disable bounding. Residual throttling is
+handled by UnprocessedKeys retry (§23).
+
+---
+
+## 17. `explain` — execution plan
+
+```ts
+explain<Sel>(
+  key: PartialQueryKeyOf<C>,
+  options?: {
+    select?: Sel;
+    limit?: number;
+    after?: string;
+    order?: 'ASC' | 'DESC';
+    consistentRead?: boolean;
+    filter?: FilterInput<T>;
+  },
+): ExecutionPlan;   // synchronous, no I/O
+```
+
+Returns the planned DynamoDB operations **without** executing anything — useful
+for inspecting access patterns and relation fan-out in tests.
+
+```ts
+const plan = GroupMembership.explain(
+  { groupId: 'eng' },
+  { select: { userId: true, role: true }, limit: 10 },
+);
+```
+
+`ExecutionPlan`:
+
+```ts
+interface ExecutionPlan { operations: DynamoDBOperation[]; }
+
+type DynamoDBOperation = GetItemOperation | QueryOperation | BatchGetItemOperation;
+
+interface DynamoDBOperationBase {
+  tableName: string;
+  projectionExpression?: string;
+  expressionAttributeNames?: Record<string, string>;
+  consistentRead?: boolean;
+  filterExpression?: string;
+  filterExpressionAttributeNames?: Record<string, string>;
+  filterExpressionAttributeValues?: Record<string, unknown>;
+}
+
+interface GetItemOperation extends DynamoDBOperationBase {
+  type: 'GetItem';
+  keyCondition: Record<string, unknown>;     // { PK, SK }
+}
+
+interface QueryOperation extends DynamoDBOperationBase {
+  type: 'Query';
+  indexName?: string;                         // present for GSI queries
+  keyCondition: Record<string, unknown>;
+  rangeCondition?: { operator: 'begins_with'; key: string; value: unknown };
+  scanIndexForward?: boolean;                 // ASC → true
+  limit?: number;
+  exclusiveStartKey?: Record<string, unknown>;
+}
+
+interface BatchGetItemOperation extends DynamoDBOperationBase {
+  type: 'BatchGetItem';
+  keys: Record<string, unknown>[];
+}
+```
+
+- The first operation is the main read (`GetItem` or `Query`); subsequent
+  operations are the relation plan: `hasMany` → a `Query` per relation,
+  `belongsTo`/`hasOne` → `BatchGetItem` operation(s) using placeholder keys
+  (sized by the estimated parent count, chunked at 100). Relation operations
+  recurse for nested relations.
+- For a partial GSI key, the planner emits a `rangeCondition`
+  (`begins_with` on the GSI sort key).
+- `consistentRead` only appears on PK operations.
+
+---
+
+## 18. Create / Put
+
+```ts
+putItem(item: EntityInput<T>, options?: PutOptions): Promise<void>;
+```
+
+```ts
+await User.putItem({
+  userId: 'alice', name: 'Alice', email: 'alice@example.com',
+  status: 'active', createdAt: new Date(),
+});
+```
+
+Behavior:
+
+- The input type `EntityInput<T>` includes scalar and embedded fields and
+  **excludes relations** (relations are not persisted by `putItem`).
+- `putItem` / `updateItem` / `deleteItem` are the **raw base operations**. For
+  lifecycle-aware single writes, go through `DDBModel.mutate(...)` (§22) rather
+  than the raw primitives.
+- The runtime serializes each declared field, computes `{ pk, sk }` from the
+  primary key, and writes `{ PK: '<prefix><pk>', SK: String(sk), ...fields }`.
+  For every GSI, it also writes `<indexName>PK` / `<indexName>SK`. Embedded
+  values present on the item are written under their property name.
+- Requires a primary key; throws `No primary key defined for '<Class>'.` if
+  missing.
+- The low-level command is `PutCommand`. `putItem` overwrites an existing item
+  unless a condition is supplied (§21).
+
+`buildPutInput(modelClass, item, options?)` is exported to build the raw
+`PutInput` without executing (used by transactions/batch).
+
+---
+
+## 19. Update
+
+`updateItem` has two overloads, distinguished by their first argument:
+
+```ts
+// 1. Explicit base-table primary key (canonical).
+updateItem(key: PrimaryKeyOf<C>, changes: Partial<T>, options?: UpdateOptions): Promise<void>;
+
+// 2. An entity read with `{ updatable: true }`, carrying a hidden resolved key.
+updateItem(entity: Partial<T> & Updatable, changes: Partial<T>, options?: UpdateOptions): Promise<void>;
+```
+
+```ts
+// Explicit-key form — no read required:
+await User.updateItem(
+  { userId: 'alice' },             // PrimaryKeyOf<C> — identifies the item
+  { status: 'suspended' },         // changes
+);
+
+// Updatable-entity form — read, mutate, write back:
+const user = await User.query({ userId: 'alice' }, { name: true }, { updatable: true });
+if (user) await User.updateItem(user, { name: 'Alice B.' });
+```
+
+`changes` supplies the attributes to modify (the same `UpdateExpression` rules in
+both forms).
+
+### GSI key re-derivation (issue #115)
+
+`putItem` derives every GSI key attribute (`<index>PK` / `<index>SK`) from the
+item's fields. `updateItem` mirrors that contract: when a change touches a field
+that composes a GSI key, the affected index key is **re-derived and SET in the
+same `UpdateExpression`** — the index follows the row instead of silently rotting
+(a stale key that makes GSI queries miss). The rules:
+
+1. **Affected indexes only.** An index is re-derived only when `changes` touches at
+   least one of its composing fields; unrelated indexes are never modified, so a
+   routine update is unchanged.
+2. **Available values = `{ ...key, ...changes }`.** When every composing field of
+   an affected index is available (from the update key's named fields plus the
+   changes), the key re-derives inline — no extra read, fully atomic.
+3. **Otherwise throw.** When a composing field is missing (e.g. `GSI1PK =
+   f(tenantId, status)` but only `status` is changed and `tenantId` is absent),
+   `updateItem` refuses with an explicit error naming the index and the missing
+   field(s) — the same partial-input discipline the base-table key uses. Opt into
+   `{ rederive: 'read-modify-write' }` to read the current item, merge, re-derive
+   from the full image, and write back under an optimistic condition.
+
+Transaction updates (`defineTransaction` … `tx.update`) apply the same rule: the
+affected index keys are re-derived into the update at build time, or the build
+throws when a composing field is unavailable.
+
+### Key resolution (3-stage)
+
+DynamoDB `UpdateItem` targets an item by its **base-table** `{ PK, SK }` only, so
+GSI-based updates are impossible — the explicit-key overload is therefore
+`PrimaryKeyOf<C>`, not a GSI/unique key. `updateItem` resolves the target key in
+a deliberate priority order (`resolveUpdateKey`), where the most reliable source
+wins and an unresolvable key **throws** rather than silently composing a wrong one
+(e.g. `PK: "USER#undefined"`):
+
+1. **Hidden resolved key.** A read taken with `{ updatable: true }` carries its
+   already-resolved `{ PK, SK }` as a **non-enumerable Symbol** property
+   (`GRAPHDDB_KEY`). When present it is used as-is — so the write works even for a
+   **partial `select`** (key fields not projected) or a **GSI-based** read (whose
+   result carries no base-table key fields). The result type is branded
+   `& Updatable` so it can be passed straight back to `updateItem()`.
+2. **Native key fields.** Only when **every** PK/SK input field is present and
+   non-`undefined`; the key is then derived from the structured segments. This is
+   the explicit-key path (`updateItem({ userId }, changes)`) and the full-entity path.
+3. **Throw.** Neither holds: report the missing field(s) — `Cannot resolve update
+   key for '<Class>': missing key field(s) [...]. Provide an explicit key
+   (updateItem({ ... }, changes)), select all key fields, or query with { updatable:
+   true }.`
+
+> Because the hidden key is keyed by a Symbol and is `enumerable: false`, it is
+> invisible to `JSON.stringify` / `Object.keys` / `for...in` / object spread. A
+> spread, clone, or JSON round-trip drops it (and the compile-time `& Updatable`
+> brand) — by design — so `updateItem` falls through to stage 2/3 rather than writing
+> to the wrong item. **Pass an updatable entity as-is; do not copy it.** This is a
+> host-side runtime behaviour only — it is not part of the serialized query
+> (`operations.json`) and does not affect the Python bridge.
+>
+> `TransactionContext.update` shares `buildUpdateInput`, so it inherits the same
+> 3-stage resolution.
+
+Behavior:
+
+- The runtime builds an `UpdateExpression` from `changes`:
+  - a field set to a value → `SET #field = :val`;
+  - a field set to `undefined` → `REMOVE #field`;
+  - for an **embedded** field whose value is a plain object, top-level keys are
+    flattened into nested dotted paths (`SET #emb.#k = :val` / `REMOVE #emb.#k`).
+    Nested update therefore patches individual sub-keys rather than replacing the
+    whole map.
+- **Readonly fields** (`@string({ readonly: true })`, etc.) included in `changes`
+  cause a throw: `Cannot update readonly field '<f>' on '<Class>'. Readonly
+  fields can only be set during put.`
+- Empty changes (no sets, no removes) throw `No changes provided for update.`
+- Requires a primary key (throws otherwise). The low-level command is
+  `UpdateCommand`.
+
+`buildUpdateInput(...)` is exported for transactions/batch.
+
+---
+
+## 20. Delete
+
+```ts
+deleteItem(key: PrimaryKeyOf<C>, options?: DeleteOptions): Promise<void>;
+```
+
+```ts
+await GroupMembership.deleteItem({ groupId: 'eng', userId: 'bob' });
+```
+
+- The key is the **primary key only** (`PrimaryKeyOf<C>`); GSI keys are not
+  accepted for `delete`.
+- Computes `{ PK, SK }` and issues `DeleteCommand`. Requires a primary key.
+
+`buildDeleteInput(...)` is exported for transactions/batch.
+
+---
+
+## 21. Conditional writes
+
+`putItem`, `updateItem`, and `deleteItem` accept an optional `condition` typed
+as `WriteCondition<T>` (issue #114) — the **same declarative operator subset as
+the read-side `FilterInput<T>` (§13)**, with the identical per-field-type
+constraints, plus the legacy existence primitives:
+
+```ts
+interface PutOptions<T>    { condition?: WriteCondition<T>; }
+interface UpdateOptions<T> { condition?: WriteCondition<T>; }
+interface DeleteOptions<T> { condition?: WriteCondition<T>; }
+```
+
+Supported condition shapes (`WriteCondition<T>`):
+
+- **Declarative field operators** — every operator from the filter table (§13):
+  `eq` (equality shorthand), `ne`, `gt` / `ge` / `lt` / `le`, `between`, `in`,
+  `beginsWith`, `contains`, `notContains`, `size`, `attributeType` — bound to the
+  field's declared type (e.g. `beginsWith` on a numeric field is a compile
+  error).
+- **Logical groups** — `and` / `or` (arrays) and `not` (single), composing the
+  above.
+- **Legacy existence primitives** — `{ notExists: true }` →
+  `attribute_not_exists(PK)` (a create-only whole-row guard); `attributeExists` /
+  `attributeNotExists` for a named attribute.
+- **Raw `cond` escape hatch (§15)** — a whole `cond\`…\`` fragment is also a valid
+  `WriteCondition<T>`, for conditions the declarative subset cannot express. (See
+  the nesting constraint below.)
+
+```ts
+// Create only if absent
+await User.putItem(item, { condition: { notExists: true } });
+
+// Optimistic lock (equality shorthand)
+await User.updateItem({ userId: 'alice' }, { status: 'x', version: 4 },
+  { condition: { version: 3 } });
+
+// Comparison / range / logical groups now work on writes
+await User.updateItem({ userId: 'alice' }, { status: 'x' },
+  { condition: { and: [{ version: { ge: 3 } }, { status: { ne: 'banned' } }] } });
+
+// Raw escape hatch on a write
+await User.updateItem({ userId: 'alice' }, { status: 'x' },
+  { condition: cond`${User.col.version} >= ${3}` });
+```
+
+Condition names/values use a dedicated allocator (a `cond_` prefix) so they never
+collide with the update expression's names/values. A failed condition surfaces as
+the AWS SDK's `ConditionalCheckFailedException`.
+
+---
+
+## 22. The unified envelope — `DDBModel.query` / `DDBModel.mutate`
+
+Multi-route reads and lifecycle-aware writes are issued through a single
+in-process **unified envelope**: a **descriptor map** keyed by caller-chosen
+aliases, where each value is a route descriptor naming a model and an operation.
+The result is an object with the same aliases.
+
+### Read envelope — `DDBModel.query(map)`
+
+`DDBModel.query(map)` runs each alias route **independently and in parallel**
+(there is no cross-route consistency — these are parallel independent reads):
+
+```ts
+const { user, members } = await DDBModel.query({
+  user:    { query: User,            key: { userId: 'u1' },   select: { name: true } },
+  members: { list:  GroupMembership, key: { groupId: 'eng' }, select: { role: true }, options: { limit: 20 } },
+});
+// user: Item | null ; members: { items, cursor }
+```
+
+A **read route descriptor** is `{ query | list: Model, key, select, options? }`
+(exactly one of `query` / `list`):
+
+- `query` route → resolves to a single `Item | null` (unique key, §10).
+- `list` route → resolves to `{ items, cursor }` (partition query, §11).
+- `options` for `query`: `{ consistentRead?, maxDepth? }`; for `list`:
+  `{ limit?, after?, order?, filter? }`.
+
+### Write envelope — `DDBModel.mutate(map, { mode })`
+
+`DDBModel.mutate(map, { mode })` performs lifecycle-aware writes. This is the
+path for **single** writes too — the raw primitives `putItem` / `updateItem` /
+`deleteItem` (§18–20) are base ops, not lifecycle-aware.
+
+```ts
+const res = await DDBModel.mutate({
+  a: { create: GroupMembership, key: { groupId: 'eng', userId: 'u1' }, input: { role: 'admin' } },
+  b: { update: User, key: { userId: 'u1' }, input: { name: 'Ann' }, condition: { status: 'active' }, result: { select: { name: true } } },
+}, { mode: 'transaction' });
+```
+
+A **write route descriptor** is `{ create | update | remove: Model, key, input?, condition?, result? }`:
+
+- `key`: a **single** object **or an array** of objects (bulk). In
+  `transaction` mode bulk compiles to `TransactWriteItems`; in `parallel` mode it
+  compiles to `BatchWriteItem` (chunked, with `UnprocessedItems` retry).
+- `condition`: a `WriteCondition` write gate — the full declarative operator
+  subset of `FilterInput` (`eq`/`ne`/comparisons/`between`/`in`/string ops/`size`/
+  `attributeType` + `and`/`or`/`not`), the legacy existence primitives, or a whole
+  `cond` fragment (§15, §21).
+- `result: { select, options? }`: read-back of the written item(s); **omit** →
+  the route returns `void`.
+
+### Modes
+
+- **`mode: 'transaction'`** (DEFAULT) — one atomic `TransactWriteItems`:
+  all-or-nothing with rollback, **throws** on failure. More than 25 items errors
+  (it is **never** split, to preserve atomicity).
+- **`mode: 'parallel'`** — non-atomic. Each op (alias) reports **partial
+  success** in the result object as `{ ok }` | `{ error }`. Independent ops run in
+  parallel; ops that reference another via `$.alias.field` are ordered after
+  their dependency.
+
+### GraphQL contrast
+
+`transaction` = atomic, all-or-nothing (mirrors a single all-or-nothing
+mutation); `parallel` = non-atomic per-field partial success (each field
+succeeds or fails on its own); `query` routes are parallel independent reads with
+no cross-route consistency.
+
+---
+
+## 23. Batch operations
+
+```ts
+DDBModel.batchGet(requests: BatchGetRequest[]): Promise<BatchGetResult>;
+DDBModel.batchWrite(requests: BatchWriteRequest[]): Promise<void>;
+```
+
+```ts
+interface BatchGetRequest { model: ModelStatic<T>; keys: Record<string, unknown>[]; }
+
+type BatchWriteRequest =
+  | { type: 'put';    model; item: Record<string, unknown>; options?: PutOptions }
+  | { type: 'delete'; model; key:  Record<string, unknown>; options?: DeleteOptions };
+```
+
+```ts
+const result = await DDBModel.batchGet([
+  { model: User, keys: [{ userId: 'alice' }, { userId: 'bob' }] },
+]);
+const users = result.get(User);   // Partial<UserModel>[]
+
+await DDBModel.batchWrite([
+  { type: 'put',    model: User,            item: { userId: 'dave', /* … */ } },
+  { type: 'delete', model: GroupMembership, key:  { groupId: 'eng', userId: 'bob' } },
+]);
+```
+
+Behavior and limits:
+
+- **`batchGet`** groups keys by physical table, fetches all scalar fields,
+  hydrates them (merging back any embedded maps), and returns a `BatchGetResult`
+  whose `.get(model)` yields the items for that model (`Partial<T>[]`). Keys are
+  matched back to items by `PK::SK`.
+- **`batchWrite`** groups by table, builds put/delete inputs, and writes.
+- **Chunking:** keys/items are split into chunks of `BATCH_GET_MAX_KEYS = 100`
+  (get) and `BATCH_WRITE_MAX_ITEMS = 25` (write) and issued per chunk.
+- **Retry:** unprocessed keys/items are retried with exponential backoff
+  (`50·2^(n-1)` ms, capped at 1000 ms) up to `BATCH_MAX_RETRY_ATTEMPTS = 10`
+  retries, after which it throws (rather than looping forever) — typically a sign
+  of sustained throttling.
+- Item-level `condition` options on `batchWrite` puts/deletes are accepted in the
+  request type but DynamoDB BatchWrite does not support per-item conditions; use
+  transactions for conditional atomic writes.
+
+---
+
+## 24. The Linter and design rules
+
+GraphDDB runs a **linter over entity metadata at registration time** (when an
+entity's metadata is first finalized). Error-severity findings **throw**;
+warning-severity findings are logged with `console.warn` (prefix
+`[graphddb] <ruleId>: …`).
+
+### Default rule set (`createDefaultLinter`)
+
+| Rule | Severity | Fires when |
+| --- | --- | --- |
+| `no-scan` | error | the entity has **no** primary key and **no** GSI (all reads would be a full scan). |
+| `require-limit` | warning | a `hasMany` relation is missing `limit.default` or `limit.max` (risk of unbounded RCU). |
+| `gsi-ambiguity` | error | two access patterns (PK + GSIs) have a subset relationship on their input field sets, so one query input could match both. |
+| `missing-gsi` | error | a relation's `keyBinding` target fields do not resolve to any access pattern on the target entity, or the target is unregistered. |
+| `relation-depth` | warning | the entity's relation graph can exceed the default `maxDepth` of 1 (deep traversal needs explicit `maxDepth`). |
+| `same-partition-preset` | error | a `pattern: 'samePartition'` relation does not lower to a valid same-partition `begins_with` access pattern (Epic #118 #123). |
+| `missing-context` | error | a maintained relation's `projection` reads a source attribute not present on the source payload (Phase 1 = payload-同梱 only; Epic #118 #126). |
+| `400kb` | warning | a maintained `embeddedSnapshot` collection's worst-case materialized size risks the 400 KB item cap (Epic #118 #126). |
+| `hot-partition` | warning | a maintained `embeddedSnapshot` concentrates every source write onto one owner ("root") row — a hot partition (Epic #118 #126). |
+| `fan-out` | warning | one source lifecycle event would fan out a maintenance write onto many destination rows in a single mutation (Epic #118 #126). |
+| `multi-maintainer-same-row` | error | two+ maintained relations write the **same** owner row under the **same** trigger ("1 mutation × 1 target row = 1 effect"; Epic #118 #126). |
+
+`query-boundary` (error: a non-unique GSI is unsafe for `query()`) exists and is
+exported but is **not** in the default set — non-unique GSIs are valid for
+`list()`, and the `query()`-on-non-unique-GSI case is enforced at runtime by the
+resolver instead.
+
+### Customizing
+
+```ts
+import { MetadataRegistry, Linter, noScanRule, requireLimitRule } from 'graphddb';
+
+const linter = new Linter();
+linter.addRule(noScanRule);
+linter.addRule(requireLimitRule);
+MetadataRegistry.linter = linter;        // set BEFORE defining/registering models
+// MetadataRegistry.resetLinter();        // restore the default set
+```
+
+> The `user-permissions` example installs a custom linter without `gsi-ambiguity`
+> on purpose: `GroupMembership` uses `[userId]` as its GSI input, a subset of its
+> PK input `[groupId, userId]`. The runtime resolves this unambiguously (exact
+> GSI match outranks partial PK match), but the static rule would flag the subset.
+
+A standalone `validateGsiAmbiguity(primaryKey, gsiDefinitions)` helper is also
+exported (throws on a subset overlap).
+
+---
+
+## 25. Runtime responsibilities (pipeline)
+
+What the runtime owns, end to end:
+
+1. **Key resolution** (`resolveKey`): pick the access pattern from the supplied
+   key fields, by the priority order in §5 (exact PK → exact GSI → partial PK →
+   partial GSI), or throw.
+2. **Planning** (`plan`):
+   - builds the `KeyCondition` (`{ PK, SK }` for PK; `{ <gsi>PK, <gsi>SK }` for
+     GSI; partial keys produce just the partition key, GSI partials produce a
+     `begins_with` range condition);
+   - **GetItem vs Query**: emits a `GetItem` only when the access pattern is a
+     **full PK** (non-partial, with a present sort key) **and** no server-side
+     filter is requested — because `GetItem` does not support `FilterExpression`,
+     a requested filter forces a `Query`. Everything else is a `Query`;
+   - builds the `ProjectionExpression` (scalars → aliased names; embedded →
+     nested `#a.#b`; relations excluded; plus implicit key fields);
+   - compiles the declarative `filter` into a `FilterExpression`;
+   - **`consistentRead`**: rejected for GSI access (`consistentRead is not
+     supported for GSI queries. Use a primary key query instead.`); attached only
+     to PK operations.
+3. **Execution** (`execute`): dispatches `GetItem` / `Query` / `BatchGetItem` to
+   the document client, merging projection + filter names/values, and returns
+   `{ items, lastEvaluatedKey? }`. Query key conditions and `begins_with` ranges
+   are aliased (`#k0 = :k0`, `begins_with(#kN, :kN)`).
+4. **Hydration** (`hydrate`): per the selection, converts ISO strings back to
+   `Date` (per `format`) and rebuilds embedded maps. It copies only the fields
+   named in the selection, so the hydrated result contains only selected fields;
+   internal `PK`/`SK`/GSI key attributes are not included (they are simply never
+   copied, not actively stripped).
+5. **Relation traversal** (§16): resolves nested relations (bounded-parallel),
+   `hasMany` via Query (server-side filter), `belongsTo`/`hasOne` via batched
+   `BatchGetItem` (client-side filter).
+
+The cursor is derived from `LastEvaluatedKey` and reflects the pre-filter read
+position (§12). Post-load TypeScript filtering is not part of this pipeline (§14).
+
+---
+
+## 26. Error reference
+
+| Condition | Message (abridged) | Where |
+| --- | --- | --- |
+| No client configured | `DynamoDB client is not configured. Call DDBModel.setClient(new DynamoDBClient({...})) first.` | first op |
+| Class not `@model`-decorated | `No metadata registered for '<name>'. Did you apply @model()?` | metadata access |
+| No matching access pattern | `No access pattern found for fields […]. Available: …` | key resolution |
+| `query()` on non-unique GSI | `Cannot use query() with non-unique GSI '<i>'. Use list() instead.` | `query` |
+| `consistentRead` on GSI | `consistentRead is not supported for GSI queries…` | planner |
+| Relation depth exceeded | `Relation traversal depth exceeded: '<f>' at depth N exceeds maxDepth M…` | traversal |
+| No primary key | `No primary key defined for '<Class>'…` | put/update/delete |
+| Readonly field updated | `Cannot update readonly field '<f>' on '<Class>'…` | update |
+| Empty update | `No changes provided for update.` | update |
+| Transaction over limit | `Transaction exceeds DynamoDB limit of 25 items` | transaction |
+| Invalid model reference | `Invalid model reference. Use ModelStatic from DDBModel.asModel().` | tx/batch |
+| Batch retry exhausted | `BatchGet exceeded the maximum of 10 retry attempts with N key(s) still unprocessed for table "…"…` / `BatchWrite exceeded the maximum of 10 retry attempts with N item(s) still unprocessed for table "…"…` | batch |
+| Lint error(s) at registration | `Entity lint errors:\n<ruleId>: <message>…` | registration |
+| Unknown filter operator | `Unknown filter operator '<op>' on field '<f>'` | filter compile/eval |
+
+---
+
+## 27. Public API surface
+
+The package entry point (`graphddb`) exports:
+
+**Base class & model API**
+`DDBModel`, type `ModelStatic`.
+
+**Decorators & key builders**
+`model`, `field`, `string`, `number`, `boolean`, `datetime`, `binary`,
+`stringSet`, `numberSet`, `list`, `map`, `literal`, `key`, `k`, `isKeySegment`,
+`gsi`, `embedded`, `hasMany`, `belongsTo`, `hasOne`, `aggregate`, `count`, `max`;
+types `ModelOptions`, `KeyDefinitionMarker`, `KeySegment`, `KeySlot`,
+`SegmentSpec`, `KeyStructure`, `SegmentedKey`, `GsiOptions`,
+`GsiDefinitionMarker`. (`aggregate` / `count` / `max` are the Epic #118 §5.2
+scalar-aggregate declaration surface; their runtime is #141.)
+
+**Maintained access path (Epic #118)**
+`buildMaintenanceGraph` and the `preview` / `identity` projection helpers (the
+function-form projection IR for relation `projection` options); maintenance IR
+types (`MaintainTrigger`, `MaintainEffect`, `SnapshotEffect`, `CollectionEffect`,
+`ProjectionTransform`, …) and relation-option types (`RelationPattern`,
+`RelationReadOptions`, `RelationWriteOptions`, `RelationProjection`,
+`RelationOptions`, `AggregateValue`, `AggregateOptions`, `AggregateMetadata`).
+
+**Client**
+`ClientManager`, `TableMapping`.
+
+**Type-safe query/select types**
+`SelectableOf`, `RelationSelect`, `RelationSpec`, `QueryResult`, `PrimaryKeyOf`,
+`QueryKeyOf`, `UniqueQueryKeyOf`, `PartialQueryKeyOf`, `QueryOptions`,
+`ListOptions`, `FilterInput`, `SelectBuilder`, `RelationBuilder`, `SelectOf`,
+`Updatable`.
+
+**Filter / select runtime**
+`cond`, `isColumn`, `isSelectBuilder`; types `RawCondition`, `CondSlot`, `Column`,
+`ColumnMap`.
+
+**Metadata**
+`MetadataRegistry`, `derivePrefix`, `validateGsiAmbiguity`; entity-metadata
+types.
+
+**Linter**
+`Linter`, `createDefaultLinter`, `noScanRule`, `requireLimitRule`,
+`queryBoundaryRule`, `gsiAmbiguityRule`, `missingGsiRule`, `relationDepthRule`,
+plus the Epic #118 maintenance/preset rules (`samePartitionPresetRule`,
+`missingContextRule`, `embeddedSnapshotSizeRule`, `hotPartitionRule`,
+`fanOutRule`, `multiMaintainerSameRowRule`); types `LintRule`, `LintResult`. The
+default set (`createDefaultLinter`) includes every rule **except**
+`queryBoundaryRule`; the maintenance rules are no-ops for relations that declare
+no `write.maintainedOn`.
+
+**Lower-level building blocks** (for advanced/transaction/batch use)
+`executePut`, `executeUpdate`, `executeDelete`, `executeQuery`, `executeList`,
+`executeExplain`, `executeTransaction`, `executeBatchGet`, `executeBatchWrite`,
+`buildPutInput`, `buildUpdateInput`, `buildDeleteInput`, `serializeFieldValue`,
+`TransactionContext`, `BatchGetResult`, `attachModelClass`, `MAX_TRANSACT_ITEMS`
+(25), `BATCH_GET_MAX_KEYS` (100), `BATCH_WRITE_MAX_ITEMS` (25); expression
+builders `buildUpdateExpression`, `buildConditionExpression`,
+`compileFilterExpression`, `evaluateFilter`; planner `resolveKey`,
+`buildProjection`, `plan`; executor `execute`; `hydrate`; pagination
+`encodeCursor` / `decodeCursor`; relation `detectRelationFields`,
+`getImplicitKeyFields`, `validateDepth`, `resolveRelations`.
+
+---
+
+*This specification reflects the implementation as of the current source tree.
+For runnable end-to-end usage, see `examples/user-permissions/`.*