graphddb 0.4.0 → 0.4.2

package/README.md

@@ -1,62 +1,32 @@
 # GraphDDB
 
-**DynamoDB のための型安全な Graph Query Runtime**
+**A type-safe Graph Query Runtime for DynamoDB**
 
-GraphDDB は DynamoDB のネイティブなアクセスパターンを GraphQL ライクなクエリモデルにマッピングする。
-PK、GSI、Projection、Relation、Cursor、そして操作の上限（limit）はすべて隠さず可視に保たれる。
+GraphDDB maps DynamoDB's native access patterns onto a GraphQL-like query model.
+PK / GSI / projection / relation / cursor / operation limits are all kept visible rather than hidden.
 
-GraphDDB は ORM ではない。
-TypeScript の型を使って DynamoDB のアクセスパターンを定義・検証・実行するための Runtime である。
+It is not an ORM. It is a Runtime for **defining, validating, and executing** DynamoDB access patterns through TypeScript types.
 
-## 🤔 Why GraphDDB?
-
-DynamoDB は高速でスケーラブルだが、誤った設計をしやすい。チームはしばしば DynamoDB を
-RDBMS のように扱い —— エンティティごとに1テーブル、アプリケーションコード内での join、
-ORM 抽象の裏に隠れたその場しのぎのアクセスパターン —— その結果、不安定なパフォーマンス、
-不要な GSI、不明瞭なサービス境界に陥る。
-
-GraphDDB は逆のアプローチを取る。DynamoDB のアクセスパターンを **コードに直接** 表現し、
-PK/GSI、projection、relation、cursor、操作の上限を可視に保つ。アクセスパターンと relation が
-明示的になり、クエリプランが検査可能になり、よく設計されたアクセスパターンが自然と
-サービス境界に整合する。GraphDDB は DynamoDB の設計を教えるのではない —— 正しい設計を、
-コードを書く上で最も簡単な道にする。
-
-これは GraphQL のクエリモデルと DynamoDB のアクセスパターンの自然な対応関係を通じて実現される:
-
-```text
-GraphQL Query Model        DynamoDB
-arguments           ---->  PK / GSI lookup
-selection           ---->  ProjectionExpression
-relation            ---->  Query / Get / BatchGet
-connection          ---->  Cursor pagination
-complexity          ---->  Operation limits
-```
-
-Partition Key は Graph のエントリポイントであり、relation は明示的な traversal パスであり、
-projection は selection set である。GraphDDB はクエリ言語を発明しない —— よく設計された
-アクセスパターンを直接実行し、plan・limit・relation 解決を通じて曖昧さを可視化する。
+Reads center on `query` / `list`, writes on `DDBModel.mutate` (a unified envelope), while
+`putItem` / `updateItem` / `deleteItem` are positioned secondarily as raw base operations named after the DynamoDB API.
 
 ## 📦 Install
 
 ```bash
 npm install graphddb
-```
-
-AWS SDK v3 は peer dependency である —— 使用するクライアントをインストールすること:
-
-```bash
+# AWS SDK v3 は peer dependency。使うクライアントを入れる:
 npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
 ```
 
-`tsx` は optional な peer dependency で、コード生成 CLI（`graphddb generate …`）を
-TypeScript の定義ファイルに対して直接実行する場合にのみ必要となる。ライブラリの利用者には
-不要である（そのため esbuild がランタイムバンドルに混入することはない）:
+`tsx` is an optional peer dependency, needed only when running the code-generation CLI
+(`graphddb generate …`) directly against TypeScript definitions. Library consumers do not need it
+(esbuild keeps it out of the runtime bundle):
 
 ```bash
 npm install -D tsx
 ```
 
-Node.js ≥ 22 が必要。
+Node.js ≥ 22 is required.
 
 ## 🚀 Quick Start
 
@@ -76,168 +46,40 @@ class UserModel extends DDBModel {
 }
 const User = UserModel.asModel();
 
-// DynamoDB クライアントは一度だけ接続する。GraphDDB が throttle / transient の retry を
-// 所有するため（後述の "Retry & throttling" を参照）、クライアントは `maxAttempts: 1` に設定し、
-// 二重 retry（SDK × ライブラリ）を避けること。
+// クライアントは一度だけ接続。GraphDDB が throttle / transient の retry を所有するため
+// `maxAttempts: 1` にして二重 retry（SDK × ライブラリ）を避ける（後述 "Retry & throttling"）。
 DDBModel.setClient(new DynamoDBClient({ maxAttempts: 1 }));
 
-// Read —— 結果の型に現れるのは select したフィールドのみ。
+// READ —— 結果型に現れるのは select したフィールドのみ。
 const user = await User.query({ userId: 'alice' }, { name: true });
 
-// 単一アイテムの書き込み —— DynamoDB API にちなんで名付けられた raw な base 操作。
-await User.putItem({ userId: 'alice', name: 'Alice' });
-
-// 複数アイテムの atomic な書き込み —— 統一 envelope（デフォルト `mode: 'transaction'`）。
+// WRITE —— 複数アイテムを atomic に書く統一 envelope（デフォルト mode: 'transaction'）。
 await DDBModel.mutate({
   user: { update: User, key: { userId: 'alice' }, input: { name: 'Alice B.' } },
 });
-```
-
-クロスサービス contract、Python bridge、複数 fragment の atomic mutation などについては、
-以下の各セクションおよび [`docs/spec.md`](./docs/spec.md) を参照。
-
-## 🔁 Retry & throttling
-
-GraphDDB は **すべての** 単一アイテム操作（`GetItem` / `Query` / `PutItem` / `UpdateItem` /
-`DeleteItem`）、relation read の fan-out、そして `TransactWriteItems` に対して、throttle /
-transient エラーの retry を行う —— 設定不要で、すぐに使える。デフォルトのポリシーは
-full jitter 付きの指数バックオフ（`min(1000, 50·2^(n-1))` ms）で、最大 10 回まで、
-throttle / 5xx / transient エラーのみを retry する（`ValidationException` や
-条件チェック失敗は決して retry しない）。キャンセルされた transaction は理由ごとに
-検査される: `ConditionalCheckFailed` の理由は即座に throw し、純粋に throttle による
-キャンセルは retry される。
-
-> これはライブラリ自身の **error retry** であり、`batchGet` / `batchWrite` が既に行う
-> 部分バッチの `UnprocessedKeys` / `UnprocessedItems` retry とは別物である。両者は同じ
-> バックオフのランプを使うが、独立したメカニズムである。
-
-**クライアントは `maxAttempts: 1` に設定すること。** ライブラリが retry を所有する以上、
-AWS SDK をデフォルト（`maxAttempts: 3`）のままにすると、GraphDDB の下層で
-*乗算的に* retry してしまう。ライブラリを単一の真実の源とすること:
-
-```ts
-DDBModel.setClient(new DynamoDBClient({ maxAttempts: 1 }));
-```
-
-GraphDDB は渡されたクライアントを決して変更しない —— この設定はあなたの責任である。
-
-ポリシーはグローバルに、あるいは呼び出しごとに調整できる:
-
-```ts
-import { DDBModel } from 'graphddb';
-
-// グローバルな上書き（setClient / setTableMapping と同様）。`null` でデフォルトに戻る。
-DDBModel.setRetryPolicy({
-  maxAttempts: 5,
-  jitter: 'full', // または 'none'
-  onRetry: ({ attempt, error, delayMs, operation }) => {
-    console.warn(`retry #${attempt} of ${operation} after ${delayMs}ms`, error);
-  },
-});
-
-// 任意の操作の options での呼び出しごとの上書き（`RetryPolicy | false`）。`false` で retry 無効。
-await User.putItem({ userId: 'alice', name: 'Alice' }, { retry: false });
-await User.query({ userId: 'alice' }, { name: true }, { retry: { maxAttempts: 3 } });
-```
-
-## 👥 User Permissions Example
-
-[user-permissions](./examples/user-permissions/) の例は、ユーザー・グループ・メンバーシップ・
-パーミッションを単一の DynamoDB テーブルでモデル化している。
-ここで GraphDDB の設計が最も分かりやすく見えてくる: テーブルは物理的だが、クエリの表面は
-Graph の形をしている。
-
-```text
-UserPermissions table
-
-Entity            PK                  SK                         GSI1PK              GSI1SK
-Group             GROUP#<groupId>     META
-User              USER#<userId>       PROFILE                    EMAIL#<email>       PROFILE
-GroupMembership   GROUP#<groupId>     USER#<userId>              USER#<userId>       GROUP#<groupId>
-Permission        GROUP#<groupId>     PERM#<resource>#<action>
-```
-
-`GroupMembership` は隣接リスト（adjacency list）パターンを使う:
 
-- `PK/SK` はグループのメンバーを読む
-- `GSI1PK/GSI1SK` はユーザーが所属するグループを読む
-
-同じ物理テーブルが、キーを隠すことなく両方向をサポートする。
-
-```ts
-const engGroup = await Group.query(
-  { groupId: 'eng' },
-  {
-    groupId: true,
-    name: true,
-    members: {
-      select: { userId: true, role: true },
-      limit: 20,
-    },
-    permissions: {
-      select: { resource: true, action: true },
-      limit: 20,
-    },
-  },
-);
-
-// email（GSI）でユーザーを探し、所属グループを一覧し、各グループについてグループ本体と
-// そのパーミッションを取得する。N 件の membership -> 親 Group の解決は単一の
-// BatchGetItem に集約される（N+1 にならない）。
-const alice = await User.query(
-  { email: 'alice@example.com' },
-  {
-    userId: true,
-    name: true,
-    groups: {
-      select: {
-        groupId: true,
-        role: true,
-        group: {                                // membership -> Group (belongsTo, BatchGet)
-          select: {
-            name: true,
-            permissions: {                      // group -> permissions (hasMany)
-              select: { resource: true, action: true },
-              filter: { resource: { attributeExists: true } },
-            },
-          },
-        },
-      },
-      limit: 20,
-    },
-  },
-  { maxDepth: 3 },
-);
-```
-
-最初のクエリは、小さく検査可能な DynamoDB plan に展開される:
-
-```mermaid
-flowchart LR
-    Q(["Group.query<br/>groupId: eng"]) --> S1["1 Query<br/>PK=GROUP#eng, SK=META<br/>→ Group"]
-    Q --> S2["2 Query<br/>PK=GROUP#eng, SK begins_with USER#<br/>→ members"]
-    Q --> S3["3 Query<br/>PK=GROUP#eng, SK begins_with PERM#<br/>→ permissions"]
-    S2 -.並列ディスパッチ.- S3
+// 単一アイテムの raw な base 操作（DynamoDB API 名に倣う）。
+await User.putItem({ userId: 'alice', name: 'Alice' });
 ```
 
-独立した relation のサブクエリ（ここでは `members` と `permissions`）は並列にディスパッチされる。
-2番目のクエリの `belongsTo` 解決は N 件の lookup を1回の `BatchGetItem` にバッチ化する。
-並列ディスパッチを示すタイムラインは [example](./examples/user-permissions/) を参照。
+Cross-service contracts, the Python bridge, atomic mutation of multiple fragments, and more are
+covered in the sections below and in [`docs/spec.md`](./docs/spec.md).
 
 ## 📖 Usage
 
-以下のスニペットは [user-permissions](./examples/user-permissions/) の例を圧縮したものである。
+The snippets below are condensed from the [user-permissions](./examples/user-permissions/) example.
 
 ### Entity Definition
 
-TypeScript クラスが単一の真実の源（single source of truth）である。Key と GSI は `k`
-タグ付きテンプレートの **segment** から構築され、key builder の入力型がそのまま
-クエリパラメータの型になる。
+The TypeScript class is the single source of truth. Keys / GSIs are built from the **segments** of the
+`k` tagged template, and the input type of the key builder becomes the type of the query parameters.
+`@model({ description })` is an optional human-readable description (#154) that is pure documentation
+metadata, propagated into the manifest and the generated Python docstrings.
 
 ```ts
 const TABLE = 'UserPermissions';
 
-@model({ table: TABLE, prefix: 'USER' })
+@model({ table: TABLE, prefix: 'USER', description: 'アプリのユーザー' })
 class UserModel extends DDBModel {
   static readonly keys = key<{ userId: string }>((c) => ({
     pk: k`USER#${c.userId}`,
@@ -282,18 +124,27 @@ export const User = UserModel.asModel();
 export const GroupMembership = GroupMembershipModel.asModel();
 ```
 
-複数 segment の sort key は segment の配列である（例: `sk: [k\`PERM#${c.resource}\`, k\`${c.action}\`]`）。
-partial key はマッチする segment 境界で `begins_with` にコンパイルされる。完全なキーモデルは
-[仕様書](./docs/spec.md) を参照。
+A multi-segment sort key is an array of segments (e.g. `sk: [k\`PERM#${c.resource}\`, k\`${c.action}\`]`).
+A partial key is compiled to `begins_with` at the matching segment boundary. For the complete key model,
+see [`docs/spec.md`](./docs/spec.md).
+
+Field decorators define the DynamoDB attribute type and catch mismatches with the declared TS type at compile time:
+
+```ts
+@string userId!: string;     // DynamoDB S
+@number amount!: number;     // DynamoDB N
+@datetime createdAt!: Date;  // ISO 8601 文字列として保存
+@boolean isActive!: boolean; // DynamoDB BOOL
+```
 
-### GraphQL-like Queries
+### Read: `query` / `list`
 
-第1引数は「どうやってデータを見つけるか」を記述する。
-第2引数は「何を返すか」を記述する。
-Runtime は与えられたフィールド名から、どのインデックスを使うかを解決する。
+The first argument describes "how to find the data"; the second describes "what to return". The runtime
+resolves which index (PK / GSI) to use from the given field names. The return type is inferred from
+`select`, and only the requested fields appear in the result.
 
 ```ts
-// email でユーザーを取得し、group membership へ traverse する。
+// email（unique GSI）でユーザーを取得し、group membership へ traverse する。
 const alice = await User.query(
   { email: 'alice@example.com' },
   {
@@ -305,24 +156,13 @@ const alice = await User.query(
     },
   },
 );
+// alice: { name: string; groups: { items: { groupId; role }[]; cursor: string | null } }
 
 // 未定義のキーフィールド -> コンパイルエラー
 User.query({ foo: 'bar' }, { name: true });
 ```
 
-返り値の型は `select` から推論される:
-
-```ts
-// alice: {
-//   name: string;
-//   groups: {
-//     items: { groupId: string; role: string }[];
-//     cursor: string | null;
-//   };
-// }
-```
-
-### List Queries
+`query` is for a **single** lookup of a PK or unique GSI only. For keys that may return multiple items, use `list` (with a cursor):
 
 ```ts
 const result = await GroupMembership.list(
@@ -330,17 +170,15 @@ const result = await GroupMembership.list(
   { userId: true, role: true },
   { limit: 20, after: cursor },
 );
-// result.items: GroupMembership[]
-// result.cursor: string | null
+// result.items: GroupMembership[] ; result.cursor: string | null
 ```
 
-### Filtering（サーバーサイド `filter`）
+### Filtering (server-side `filter`)
 
-`filter` は宣言的で型安全な条件であり、DynamoDB の **`FilterExpression`** にコンパイルされ、
-**サーバーサイド** で評価される。AWS AppSync の `ModelFilterInput` をモデルにしている:
-裸の値は等価の省略記法、operator オブジェクトは比較を表現し、`and` / `or` / `not` で
-論理グループを構築する。**エンティティ全体** に対して型付けされるため、`select` に **含まれない**
-属性も参照できる。
+`filter` is a declarative, type-safe condition that compiles to DynamoDB's **`FilterExpression`** and is
+evaluated **server-side** (modeled on AWS AppSync's `ModelFilterInput`). A bare value is shorthand for
+equality, an operator object is a comparison, and `and` / `or` / `not` form logical groups. Because it is
+typed against the **entire entity**, it can reference attributes **not** included in `select`.
 
 ```ts
 const result = await Order.list(
@@ -358,74 +196,57 @@ const result = await Order.list(
 );
 ```
 
-Relation は対象モデルの `Model.relation(...)` を通じて同じ `filter` を取る。サーバーサイドの
-`FilterExpression` で表現できないロジックには、返された projection に対して
-`result.items.filter(...)` を呼ぶこと —— 各 select フィールドの宣言済みスカラー型が保たれるため、
-`o.amount > 100` はキャスト不要である（組み込みの post-load 述語は存在しない）。
-
-利用可能な operator（フィールド型ごと）: `eq`、`ne`、`ge`、`le`、`gt`、`lt`、
-`between`、`in`、`beginsWith`、`contains`、`notContains`、`attributeExists`、
-`attributeType`、`size`。operator は **フィールドの宣言型によって制約される** ——
-例えば数値フィールドへの `beginsWith` / `contains`、あるいは数値への `gt: 'x'` は
-コンパイルエラーになる。
-
-operator オブジェクトでは表現できない稀な条件のために、`cond` という raw な escape hatch が
-式 fragment を受け取る。カラム名は bare な文字列ではなく、リファクタ安全な
-`Model.col.<field>` 参照を使わなければならない。値はパラメータ化される:
+Available operators: `eq` / `ne` / `ge` / `le` / `gt` / `lt` / `between` / `in` / `beginsWith` /
+`contains` / `notContains` / `attributeExists` / `attributeType` / `size`. Operators are
+**constrained by the declared type of the field** (`beginsWith` on a number, `gt: 'x'`, etc. are compile
+errors). For the rare condition an operator cannot express, write it with the raw escape hatch `cond`
+using `Model.col.<field>` (a refactor-safe column reference). All values are parameterized and column
+names are aliased, so it is injection-safe:
 
 ```ts
 filter: cond`${Order.col.amount} > ${100} AND attribute_exists(${Order.col.status})`
 ```
 
-すべての値はパラメータ化され（`ExpressionAttributeValues`）、すべてのカラム名は
-エイリアス化される（`ExpressionAttributeNames`）—— リテラルの補間は存在しないため、
-コンパイルされた式はインジェクション安全であり、`KeyConditionExpression` /
-`ProjectionExpression` とは独立して付与される。
+The same `cond` fragment works not only for read filters but also for write `condition`s (a `mutate`
+route, `putItem` / `updateItem` / `deleteItem`, a transaction item, a public command).
 
-同じ `cond` fragment は read filter としてだけでなく、書き込みの `condition`
-（`putItem` / `updateItem` / `deleteItem`、transaction item、public command に対して）
-としても受け付けられる。
+> **RCU note:** `FilterExpression` does **not** reduce read capacity —— DynamoDB reads the keys first
+> and filters afterward. `limit` is applied **before** the filter, so a single page may return fewer
+> than `limit`, or an entire page may be excluded, yielding an empty page with a non-null cursor.
+> Do efficient narrowing through key design and use `filter` for correctness.
 
-> **RCU に関する注意:** `FilterExpression` は read capacity を **削減しない** ——
-> DynamoDB はまずマッチするキーを読み、その後に filter する。`limit` は filter の
-> **前** に適用されるため、1ページが `limit` **未満** のアイテムを返すことがある
-> （そしてページ全体が filter で除外された場合、null でない cursor を持つ空ページになる）。
-> 効率的な絞り込みのためにキーを設計し、`filter` は正しさのために使うこと。
+### Write: `DDBModel.mutate` (unified envelope)
 
-### Writes
+The primary write path is `DDBModel.mutate`. It is an **alias-map envelope** that runs multiple write
+routes in a single call —— the in-process counterpart of a GraphQL operation. Each alias is a named
+route, and the result is keyed by the same alias. Lifecycle-aware writes (conditional gates, read-back,
+referential side effects) go through here.
 
-raw な base テーブルの書き込みは `putItem` / `updateItem` / `deleteItem` である ——
-ライフサイクルのセマンティクスを持たないプリミティブな単一アイテム操作:
+A write route descriptor is `{ create | update | remove: Model, key, input?, condition?, result? }`:
 
 ```ts
-await User.putItem({
-  userId: 'alice',
-  name: 'Alice',
-  email: 'alice@example.com',
-  status: 'active',
-});
-
-await GroupMembership.putItem({
-  groupId: 'eng',
-  userId: 'alice',
-  role: 'admin',
-});
-
-await User.updateItem({ userId: 'alice' }, { status: 'disabled' });
+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' });
 ```
 
-ライフサイクルを意識した単一書き込み —— 条件ゲート、read-back、参照整合的な副作用 ——
-は raw なプリミティブではなく `DDBModel.mutate` を経由する（後述の
-[The in-process unified envelope](#the-in-process-unified-envelope) を参照）。
-
-### The in-process unified envelope
-
-`DDBModel.query` と `DDBModel.mutate` は、1回の呼び出しで複数の route を実行する単一の
-**alias-map envelope** を取る。これは GraphQL operation の in-process 版である:
-各 alias は名前付きの route であり、結果は同じ alias でキー付けされる。
-
-`DDBModel.query(map)` は各 read route を独立かつ並列に実行する —— route 間の
-一貫性はなく、GraphQL の並列フィールド解決とまったく同じである:
+- **`key`** is a single object, or an **array of objects** (key-array bulk).
+- **`condition`** is the write gate of `WriteCondition` —— the same declarative operator subset as the
+  read filter (`eq` / `ne` / comparisons / `between` / `in` / string operations / `size` / `attributeType`
+  + `and` / `or` / `not`), the existence primitives (`notExists` / `attributeExists` / `attributeNotExists`),
+  or a raw `cond` fragment.
+- **`result: { select, options? }`** reads back the written item. Omit it for void.
+- **`mode: 'transaction'`** (default) is a single atomic `TransactWriteItems`: all-or-nothing, throws on
+  failure, a map of more than 25 items is an error (it is not split). Equivalent to GraphQL's
+  all-or-nothing contract.
+- **`mode: 'parallel'`** is a non-atomic `BatchWriteItem` (chunking + `UnprocessedItems` retry): each
+  alias reports partial success/failure as `{ ok }` | `{ error }`. Independent operations run in parallel;
+  dependencies are ordered via `$.alias.field` references.
+
+The read side has a symmetric `DDBModel.query(map)`. Each read route
+(`{ query | list: Model, key, select, options? }`) runs **independently and in parallel**, with no
+consistency across routes (just like GraphQL's parallel field resolution):
 
 ```ts
 const { user, members } = await DDBModel.query({
@@ -435,44 +256,60 @@ const { user, members } = await DDBModel.query({
 // user: Item | null ; members: { items, cursor }
 ```
 
-read route の記述子は `{ query | list: Model, key, select, options? }` である
-（`query` / `list` のいずれか一方）。`query` の `options` は
-`{ consistentRead?, maxDepth? }`、`list` の場合は `{ limit?, after?, order?, filter? }` である。
+### Raw base operations: `putItem` / `updateItem` / `deleteItem`
 
-`DDBModel.mutate(map, { mode })` は write route を実行する。write route の記述子は
-`{ create | update | remove: Model, key, input?, condition?, result? }` である:
+`putItem` / `updateItem` / `deleteItem` are **raw single-item operations** named after the DynamoDB API,
+primitives with no lifecycle semantics. They carry no atomic composition of multiple fragments and no
+derived side effects, unlike `mutate`:
 
 ```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' });
+await User.putItem({ userId: 'alice', name: 'Alice', email: 'alice@example.com', status: 'active' });
+await User.updateItem({ userId: 'alice' }, { status: 'disabled' });
+await User.deleteItem({ userId: 'alice' });
 ```
 
-- **`key`** は単一のオブジェクト、または **オブジェクトの配列**（key-array bulk）である。
-  transaction は `TransactWriteItems` にコンパイルされ、parallel モードは
-  `BatchWriteItem`（チャンク分割され、`UnprocessedItems` retry 付き）にコンパイルされる。
-- **`condition`** は `WriteCondition` の書き込みゲートである —— read filter と同じ宣言的
-  operator のサブセット（`eq`/`ne`/比較/`between`/`in`/文字列操作/`size`/`attributeType` +
-  `and`/`or`/`not`）、レガシーな存在プリミティブ（`notExists` / `attributeExists` /
-  `attributeNotExists`）、または raw な `cond` fragment。
-- **`result: { select, options? }`** は書き込んだアイテムを read-back する。省略すると
-  その route は void を返す。
-- **`mode: 'transaction'`**（デフォルト）は1回の atomic な `TransactWriteItems` である:
-  all-or-nothing のロールバック、失敗時に throw、25 件を超える map はエラーになる
-  （決して分割されない）。これは GraphQL の all-or-nothing な atomic 契約である。
-- **`mode: 'parallel'`** は非 atomic である: 各 alias は結果オブジェクト内で
-  `{ ok }` | `{ error }` として部分的な成否を報告し、GraphQL のフィールドごとの
-  部分成功を反映する。独立した操作は並列に実行され、依存関係は `$.alias.field`
-  参照で順序付けられる。
-
-GraphQL の用語で言えば: transaction は atomic な all-or-nothing、parallel は非 atomic な
-フィールドごとの部分成功、そして `query` route は route 間の一貫性を持たない並列独立 read である。
+If you need conditional gates, read-back, or referential side effects, use `DDBModel.mutate` rather than the raw primitives.
+
+### Relation Traversal
+
+A relation is a query bound to the value of the parent entity. Declare it with `@hasMany` / `@hasOne` /
+`@belongsTo` and traverse it by nesting inside `select`. `hasMany` / `list` require a default / max limit.
+Independent relation subqueries are dispatched in parallel, and N `belongsTo` resolutions are aggregated
+into a single `BatchGetItem` (no N+1):
+
+```ts
+// email でユーザーを探し、所属グループ -> 各グループ本体 -> そのパーミッションへ traverse。
+const alice = await User.query(
+  { email: 'alice@example.com' },
+  {
+    userId: true,
+    name: true,
+    groups: {
+      select: {
+        groupId: true,
+        role: true,
+        group: {                                // membership -> Group (belongsTo, BatchGet)
+          select: {
+            name: true,
+            permissions: {                      // group -> permissions (hasMany)
+              select: { resource: true, action: true },
+              filter: { resource: { attributeExists: true } },
+            },
+          },
+        },
+      },
+      limit: 20,
+    },
+  },
+  { maxDepth: 3 },   // traversal はデフォルト depth=1。深い traversal は明示許可が必要。
+);
+```
 
 ### Inspect Execution Plans
 
-`explain()` は、実行される前の DynamoDB 操作を表示する。
-`select` は `ProjectionExpression` に変換されるため、要求した属性のみが読まれる。
+`explain()` returns the DynamoDB operations before they run. `select` is translated into a
+`ProjectionExpression`, so only the requested attributes are read. The plan can be used for testing,
+debugging, and RCU estimation:
 
 ```ts
 const plan = GroupMembership.explain(
@@ -484,115 +321,186 @@ const plan = GroupMembership.explain(
 //     type: "Query",
 //     tableName: "UserPermissions",
 //     keyCondition: { PK: "GROUP#eng" },
-//     rangeCondition: {
-//       operator: "begins_with",
-//       key: "SK",
-//       value: "USER#"
-//     },
-//     limit: 10
+//     rangeCondition: { operator: "begins_with", key: "SK", value: "USER#" },
+//     limit: 10,
 //   }]
 // }
 ```
 
-partial な GSI キーマッチの場合、SK 条件は `rangeCondition` として分離される:
+For a partial GSI key match, the SK condition is separated out as a `rangeCondition`
+(`keyCondition: { GSI1PK: "USER#alice" }`, `indexName: "GSI1"`, `rangeCondition: { begins_with GSI1SK "GROUP#" }`).
 
-```ts
-const gsiPlan = GroupMembership.explain(
-  { userId: 'alice' },
-  { select: { groupId: true, role: true }, limit: 10 },
-);
-// {
-//   operations: [{
-//     type: "Query",
-//     keyCondition: { GSI1PK: "USER#alice" },
-//     indexName: "GSI1",
-//     rangeCondition: {
-//       operator: "begins_with",
-//       key: "GSI1SK",
-//       value: "GROUP#"
-//     },
-//     ...
-//   }]
-// }
-```
+### Maintained Access Paths (0.4.x / Epic #118)
+
+Declaring a relation or scalar as a **maintained access path** keeps a *separate* row in sync with the
+lifecycle of the source entity —— and all of it is composed into the same atomic transaction as the source write.
 
-## 🧠 Core Concepts
+- **`pattern` on `@hasMany` / `@hasOne`** —— `embeddedSnapshot` (keeping a projected snapshot / bounded
+  collection synchronized onto the owner row), versioned, sparse, etc. Declare the read shape with `read`,
+  the cross-entity trigger with `write.maintainedOn`, and the attributes to capture with `projection`:
 
-### Entity = Access Pattern
+  ```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[];
+  ```
 
-Entity は ORM モデルではない。
-DynamoDB に対する、境界付けられたアクセス表面（bounded access surface）である。
+- **`@aggregate` counter** —— keeps a scalar aggregate (`count()`, etc.) synchronized with an atomic `ADD ±1`:
 
-Entity は、サービス境界内でデータにアクセスする、サポートされたすべての方法を定義する:
+  ```ts
+  @aggregate(() => ThreadPostModel, { threadId: 'threadId' }, {
+    pattern: 'counter',
+    value: count(),
+    write: { maintainedOn: ['ThreadPost.created', 'ThreadPost.removed'] },
+  })
+  postCount!: number;
+  ```
 
-- 物理キー
-- GSI
-- relation
-- projection
-- traversal ルール
+- **`@model({ kind })` + `@maintainedFrom`** —— declare a view as *its own model* and bind each source
+  with a class-level `@maintainedFrom` (`materializedView` / `sparseView`).
 
-物理的には、Entity は DynamoDB の item にマップされる。
-アーキテクチャ的には、サービスのその部分に許可されたアクセス表面を定義する。
+Synchronized maintenance (`updateMode: 'mutation'`) works in both TS and Python (conformance-verified).
+`stream` / `max()` / `materializedView` / `sparseView` are later phases. For details and the pattern
+mapping table, see [`docs/design-patterns.md`](./docs/design-patterns.md). Examples:
+[embedded-snapshot-pattern](./examples/embedded-snapshot-pattern/) /
+[aggregate-counter](./examples/aggregate-counter/).
 
-### Key / GSI = Structured Segments
+### Middleware / Hooks (`DDBModel.use`)
 
-`key()` と `gsi()` は `k` タグ付きテンプレートの **segment** からキーを構築する。builder の
-入力型がキー解決に必要なフィールドを定義し、同時にクエリパラメータの型にもなる。
+You can register **host-side middleware** that runs at fixed points in reads / writes. This handles
+cross-cutting concerns —— logging, metrics, tracing, tenant / authorization scoping, soft-delete,
+result post-processing —— without embedding them in queries or model definitions. It is host-only, never
+touches the planner or the bridge SSoT, and is **not serialized**:
 
 ```ts
-// 1つの定義が2つの役割を果たす:
-// 1. 書き込みパス: Entity 保存時に PK/SK を生成
-// 2. クエリパス: User.query({ email: ... }) のパラメータ型を定義
-static readonly emailIndex = gsi<{ email: string }>(
-  'GSI1',
-  (c) => ({ pk: k`EMAIL#${c.email}`, sk: k`PROFILE` }),
-  { unique: true },
-);
+import { DDBModel } from 'graphddb';
+
+DDBModel.use({
+  name: 'tenant-scope',
+  read:  { before(ctx) { /* ctx を観測 / 変更、throw でキャンセル */ } },
+  write: { before(ctx) { /* ctx.input / ctx.kind を変更可 */ } },
+});
+DDBModel.clearMiddleware();   // 全解除（テスト teardown 等）
 ```
 
-キーは不透明な文字列ではなく構造化された segment であるため、partial key —— sort-key
-segment の先頭プレフィックスのみを与えたもの —— はその segment 境界で `begins_with` に
-コンパイルされる。これが relation と prefix クエリの解決方法である。
+`before*` runs in registration order (FIFO), `after*` / `onError` in reverse order (LIFO), so the
+first-registered middleware is the outermost (onion nesting without `next()`). Request-scoped values
+(tenant / actor / trace id) become visible from `ctx.context` when you pass `{ context }` to any
+read / write. Hooks can observe, mutate `ctx`, cancel by throwing, and recover in `onError`. For the
+full set of hook points (read R1–R5 / write W1–W5), see [`docs/middleware.md`](./docs/middleware.md).
+
+### Retry & throttling
 
-### Relation = Bound Query
+GraphDDB retries throttle / transient errors for **all** single-item operations
+(`GetItem` / `Query` / `PutItem` / `UpdateItem` / `DeleteItem`), the fan-out of relation reads, and
+`TransactWriteItems`, with **no configuration required**. The default is exponential backoff with full
+jitter (`min(1000, 50·2^(n-1))` ms), up to 10 attempts, for throttle / 5xx / transient only
+(`ValidationException` and condition-check failures are never retried).
 
-Relation は、親 Entity の値にバインドされたクエリである。
-同じ解決ロジックが適用される: runtime はフィールド名を Key / GSI 定義に照合する。
+> This is the library's own **error retry** and is distinct from the partial-batch `UnprocessedKeys` /
+> `UnprocessedItems` retry that `batchGet` / `batchWrite` already perform (they use the same backoff
+> ramp but are independent).
+
+**Set the client to `maxAttempts: 1`.** Since the library owns retries, leaving the SDK at its default
+(`maxAttempts: 3`) would *multiply* the retries. The policy can be tuned globally or per call:
 
 ```ts
-@hasMany(() => GroupMembershipModel, { userId: 'userId' }, {
-  limit: { default: 20, max: 100 },
-})
-groups!: GroupMembershipModel[];
+DDBModel.setRetryPolicy({ maxAttempts: 5, jitter: 'full' });     // null でデフォルトに戻る
+await User.putItem({ userId: 'alice', name: 'Alice' }, { retry: false });
+await User.query({ userId: 'alice' }, { name: true }, { retry: { maxAttempts: 3 } });
 ```
 
-### Field Decorators
+## 👥 Example: User Permissions
 
-型安全なセマンティック decorator が DynamoDB の属性型を定義する。
-`ClassFieldDecoratorContext` に基づくコンパイル時チェックが、宣言された TypeScript の型と
-DynamoDB の型の不一致を検出する。
+[user-permissions](./examples/user-permissions/) models users, groups, memberships, and permissions in a
+single DynamoDB table. The table is physical, but the query surface has the shape of a graph:
 
-```ts
-@string userId!: string;     // DynamoDB S
-@number amount!: number;     // DynamoDB N
-@datetime createdAt!: Date;  // ISO 8601 文字列として保存される
-@boolean isActive!: boolean; // DynamoDB BOOL
+```text
+UserPermissions table
+
+Entity            PK                  SK                         GSI1PK              GSI1SK
+Group             GROUP#<groupId>     META
+User              USER#<userId>       PROFILE                    EMAIL#<email>       PROFILE
+GroupMembership   GROUP#<groupId>     USER#<userId>              USER#<userId>       GROUP#<groupId>
+Permission        GROUP#<groupId>     PERM#<resource>#<action>
 ```
 
-### Select = Projection + Type Inference
+`GroupMembership` is an adjacency-list pattern: `PK/SK` reads a group's members, and `GSI1PK/GSI1SK`
+reads a user's groups. The same physical table supports both directions without hiding the keys.
+Fetching a group, its members, and its permissions in a single `query` expands into a small, inspectable plan:
+
+```mermaid
+flowchart LR
+    Q(["Group.query<br/>groupId: eng"]) --> S1["1 Query<br/>PK=GROUP#eng, SK=META<br/>→ Group"]
+    Q --> S2["2 Query<br/>PK=GROUP#eng, SK begins_with USER#<br/>→ members"]
+    Q --> S3["3 Query<br/>PK=GROUP#eng, SK begins_with PERM#<br/>→ permissions"]
+    S2 -.並列ディスパッチ.- S3
+```
+
+The independent relation subqueries (`members` and `permissions`) are dispatched in parallel. For a
+timeline illustrating the parallel dispatch, see the [example](./examples/user-permissions/).
+
+## 🤔 Design Philosophy (in brief)
+
+DynamoDB is fast but easy to misdesign. Teams often treat it like an RDBMS (one table per entity,
+in-app joins, access patterns hidden behind an ORM abstraction) and end up with unstable performance,
+unnecessary GSIs, and unclear service boundaries. GraphDDB does the opposite: it expresses access
+patterns **directly in code** and keeps PK / GSI, projection, relation, cursor, and limits visible.
+This makes the correct design the easiest path to take while writing code.
 
-`select` オブジェクトは DynamoDB の `ProjectionExpression` 生成と TypeScript の返り値型推論の
-両方を制御する。
-要求したフィールドだけが返り、結果の型にもそのフィールドだけが現れる。
+At its core is the natural correspondence between GraphQL's query model and DynamoDB's access patterns:
 
-### Planner = Inspectable Execution Plan
+```text
+GraphQL Query Model        DynamoDB
+arguments           ---->  PK / GSI lookup
+selection           ---->  ProjectionExpression
+relation            ---->  Query / Get / BatchGet
+connection          ---->  Cursor pagination
+complexity          ---->  Operation limits
+```
+
+- **Entity = access surface** —— not an ORM model, but the set of all supported ways to access data within
+  a service boundary (physical keys / GSIs / relations / projection / traversal rules).
+- **Key / GSI = structured segments** —— built from `k` tag segments. The builder's input type doubles as
+  the query parameter type, and a partial key compiles to `begins_with` at a segment boundary.
+- **Relation = bound query** —— a query bound to the parent's value. The same key/GSI resolution logic applies.
+- **Select = projection + type inference** —— only the requested fields are returned, and only those
+  fields appear in the result type.
+- **Planner = inspectable execution plan** —— a plan is produced before touching DynamoDB
+  (testing / debugging / RCU estimation).
 
-DynamoDB にアクセスする前に、runtime が実行計画（execution plan）を生成する。
-plan はテスト・デバッグ・RCU 見積もりに利用できる。
+Relation traversal follows only the access paths defined on the Entity. Undefined relations, missing GSIs,
+limit-less lists, and traversals exceeding the allowed depth are checked before execution. The same
+architectural constraints apply whether the code was written by a human or AI-generated.
 
-## 🏗️ Architecture
+### Design Rules
 
-GraphDDB のクエリは 5 つのレイヤーを通って実行される:
+| Rule | Description |
+|------|-------------|
+| Service Boundary First | A single table represents one service boundary, not one entity. |
+| Access Pattern First | Model the access patterns before tables or ORM-style entities. |
+| Natural Mapping | Map Query / Get / BatchGet / Projection / cursor onto a GraphQL-like shape. |
+| Inspectable Plans | DynamoDB operations and execution plans are inspectable before execution. |
+| Single-item query | `query` is for PK or unique GSI lookups only. Use `list` for keys that return multiple items. |
+| Explicit limits | `hasMany` and `list` require a default / max limit. |
+| Bounded depth | Traversal defaults to depth=1. Deeper traversal must be explicitly allowed with `maxDepth`. |
+| Parallel relations | Independent relation subqueries, BatchGet chunks, and nested resolutions are dispatched in parallel (bounded). |
+| No Scan | Full table scans are forbidden. The linter detects and blocks them. |
+| Partial select | Query results are partial types. Only the selected fields appear in the result type. |
+| Structured keys | Keys are built from `k` segment templates. A partial key compiles to `begins_with` at a segment boundary. |
+| Typed consistentRead | `consistentRead` is for PK queries only. GSI queries are rejected at compile time. |
+| Server-side filter | `filter` is a declarative `FilterExpression` (compatible with AppSync `ModelFilterInput`). It does not reduce RCU, and `limit` is applied before it. |
+
+The linter detects problems in Entity definitions before runtime (use of Scan, missing limits on
+`hasMany` / `list`, ambiguous GSI resolution, query/list boundary violations against a unique GSI).
+
+### Architecture
+
+A query executes through 5 layers:
 
 ```mermaid
 flowchart TD
@@ -609,127 +517,76 @@ flowchart TD
     L5 -->|Partial Entity インスタンス| OUT(["✅ 型付き結果"])
 ```
 
-## 📐 Design Rules
-
-| ルール | 内容 |
-|------|-------------|
-| Service Boundary First | 1テーブルは1エンティティではなく、1つのサービス境界を表す。 |
-| Access Pattern First | テーブルや ORM 風のエンティティをモデル化する前に、DynamoDB のアクセスパターンをモデル化する。 |
-| Natural Mapping | Query / Get / BatchGet / Projection / cursor を GraphQL ライクなクエリの形にマップする。 |
-| Inspectable Plans | DynamoDB の操作と実行計画は、実行前に検査可能である。 |
-| Single-item query | `query` は PK または unique GSI の lookup のみ。複数件返りうるキーには `list` を使う。 |
-| Explicit limits | `hasMany` と `list` は default/max limit の指定が必須。 |
-| Bounded depth | Relation traversal はデフォルトで depth=1。より深い traversal は `maxDepth` で明示的に許可する必要がある。 |
-| Parallel relations | 独立した relation のサブクエリ、BatchGet のチャンク、ネストした解決は並列にディスパッチされる（上限あり）。DynamoDB は HTTP ベースのため、直列化すべきコネクションが存在しない。 |
-| No Scan | Full table scan は禁止。linter が検出・ブロックする。 |
-| Partial select | クエリ結果は partial 型。select したフィールドのみが結果の型に現れる。 |
-| Structured keys | キーは `k` segment テンプレートから構築され、partial key は segment 境界で `begins_with` にコンパイルされる。 |
-| Typed consistentRead | `consistentRead` は PK クエリでのみ利用可能。GSI クエリはコンパイル時に拒否される。 |
-| Server-side filter | `filter` は宣言的な DynamoDB `FilterExpression`（AppSync `ModelFilterInput` 互換）で、エンティティ全体に対して型付けされ、projection されていない属性も参照できる。RCU は削減せず、`limit` はその前に適用される。 |
-
-## 🚧 Architectural Boundaries
-
-Relation traversal は、Entity 上に定義されたアクセスパスのみをたどる。
-未定義の relation、欠けている GSI、limit のない list、許可された depth を超える traversal は、
-実行前にチェックされる。
-
-これにより、境界をまたぐクエリや DynamoDB に不向きなアクセスパターンが、コード上で見えやすくなる。
-コードが人間によって書かれたものであれ、AI によって生成されたものであれ、同じアーキテクチャ上の
-制約が適用される。
-
-## 🔍 Linter
-
-静的解析が、runtime の前に Entity 定義の問題を検出する:
-
-- Scan の使用
-- `hasMany` / `list` での limit 未指定
-- 曖昧な GSI 解決
-- unique GSI に対する query/list の境界違反
-
 ## 🧱 Beyond the Core
 
-上記の query / relation / write API がコアレイヤーである。GraphDDB はさらに以下も提供する:
-
-- **[CQRS contracts](./docs/cqrs-contract.md)** —— N+1 安全な cardinality matrix、
-  contract をまたぐ合成、context 境界の強制を備えた、public な Query/Command contract モデル。
-- **[Mutation → command derivation](./docs/mutation-command-derivation.md)** —— public な
-  Command IF の背後にある、内部的な write-plan 合成 DSL。モデルの書き込みセマンティクス
-  （`entityWrites`: 参照整合性、一意性、edge effect、派生カウンタ、outbox event、冪等性）を
-  一度宣言すると、`mutation` が1つ以上の write fragment を合成し、コンパイラがそれらを単一の
-  atomic な `TransactWriteItems` にマージする。すべての書き込みパスは1つの共有された
-  `commitTransaction` オーケストレーションを経由する。**リレーション維持アクセスパス**
-  （Epic #118）はこれを拡張する: リレーションの `write.maintainedOn` やスカラ `@aggregate`
-  フィールドが、source エンティティのライフサイクルに同期して *別の* 行を維持する —— 射影された
-  **snapshot**（`SET`）、上限付き **collection**（`list_append`）、スカラ **counter**
-  （`@aggregate` `count()` → atomic `ADD ±1`）—— を source write と同一の atomic transaction に
-  合成する（[aggregate-counter](./examples/aggregate-counter/) 例を参照）。
-- **[Opt-in class hydration](./docs/class-hydration.md)** —— `options.hydrate` ファクトリを
-  渡すと、read 結果をデフォルトの Typed Plain Object ではなく、ホスト言語のドメインオブジェクトに
-  ロードできる。ホスト専用で、bridge SSoT にシリアライズされることはない。Phase 1
-  （`query` のトップレベル）は実装済み。`list` / relation ごとの hydration は今後の予定。
-- **[Multi-language (Python bridge)](./docs/python-bridge.md)** —— TypeScript が単一の真実の源
-  であり、同じ定義から Python クライアント + runtime を生成し、TS↔Python の conformance スイートで
-  歩調を合わせる。
-- **[In-memory testing](./docs/testing.md)** —— `graphddb/testing` は model-mapping、query-plan、
-  relation-traversal、CDC のテストを **Docker なしの in-process** で実行する。
-- **[CDC emulator](./docs/cdc-emulator.md)** —— ローカルでの差分集計を駆動・テストするための、
-  DynamoDB Streams 相当の変更イベント。
+The query / relation / write APIs above are the core layer. GraphDDB additionally provides:
+
+- **[CQRS contracts](./docs/cqrs-contract.md)** —— a public Query/Command contract model with an N+1-safe
+  cardinality matrix, composition across contracts, and enforcement of context boundaries.
+- **[Mutation → command derivation](./docs/mutation-command-derivation.md)** —— the internal write-plan
+  composition DSL behind the public Command IF. Declare a model's write semantics (`entityWrites`) once,
+  and `mutation` composes multiple fragments while the compiler merges them into a single atomic
+  `TransactWriteItems`.
+- **[Class hydration](./docs/class-hydration.md)** —— load read results into host-language domain objects
+  via the `options.hydrate` factory (host-only, non-serialized; Phase 1 = `query` top level implemented).
+- **[Multi-language / Python bridge](./docs/python-bridge.md)** —— generate a Python client + runtime with
+  TS as the SSoT, kept in step by a TS↔Python conformance suite.
+- **[In-memory testing](./docs/testing.md)** —— `graphddb/testing` runs model-mapping / query-plan /
+  relation-traversal / CDC tests in-process without Docker.
+- **[CDC emulator](./docs/cdc-emulator.md)** —— change events equivalent to DynamoDB Streams, to drive and
+  test differential aggregation locally.
 
 ## 📚 Documentation
 
-| ドキュメント | 内容 |
+| Document | Description |
 |----------|-------------|
-| [Specification](./docs/spec.md) | コア API: entity、structured keys/GSIs、query/filter、relation、batch/transaction、design rule、runtime の挙動。 |
-| [Design patterns](./docs/design-patterns.md) | DynamoDB の代表的な 10 設計パターン（RFC #118 §1）を graphddb の機能にマッピング: same-partition / embedded snapshot / edge / materialized view / sparse view / aggregate counter / versioned / reverse lookup / external projection。各パターンの用途・宣言方法（`pattern` / `@model({ kind })` + `@maintainedFrom` / `@hasOne`・`@hasMany` の versioned pattern / `@aggregate`）・read & write 維持の挙動・Phase 別の対応状況。 |
-| [CQRS contract layer](./docs/cqrs-contract.md) | public な Query/Command contract、cardinality matrix、N+1 安全性、contract をまたぐ合成、context 境界。 |
-| [Mutation → command derivation](./docs/mutation-command-derivation.md) | Command IF の背後にある内部的な write-plan 合成 DSL: モデルの write セマンティクス（`entityWrites`）、fragment 合成、atomic な `TransactWriteItems` の導出。 |
-| [Class hydration](./docs/class-hydration.md) | read 結果をホスト言語のオブジェクトにロードする opt-in な `options.hydrate` ファクトリ（Phase 1: `query` トップレベル; Phase 2–3 は今後）。 |
-| [Multi-language / Python bridge](./docs/python-bridge.md) | TS を SSoT としたコード生成と Python runtime; TS↔Python の conformance。 |
-| [In-memory test adapter](./docs/testing.md) | `graphddb/testing` と `MemoryInspector` による Docker 不要の in-process テスト。 |
-| [CDC emulator](./docs/cdc-emulator.md) | 差分集計パターン向けの変更イベント emulator（dev/test）。 |
-| [Benchmark](./benchmark/RESULTS.md) | 手書きの AWS SDK、ElectroDB、DynamoDB Toolbox、OneTable とのライブラリ比較。 |
+| [Specification](./docs/spec.md) | Core API: entities, structured keys/GSIs, query/filter, relations, batch/transaction, design rules, runtime behavior. |
+| [Design patterns](./docs/design-patterns.md) | Mapping representative DynamoDB design patterns onto graphddb features (how to declare `pattern` / `@model({ kind })` + `@maintainedFrom` / `@aggregate`, read & write maintenance, per-phase coverage). |
+| [Middleware / Hooks](./docs/middleware.md) | The `DDBModel.use` host-side middleware: hook points read R1–R5 / write W1–W5, `{ context }`, ordering. |
+| [CQRS contract layer](./docs/cqrs-contract.md) | Public Query/Command contracts, cardinality matrix, N+1 safety, composition across contracts, context boundaries. |
+| [Mutation → command derivation](./docs/mutation-command-derivation.md) | The internal write-plan composition DSL behind the Command IF (`entityWrites`, fragment composition, derivation of atomic `TransactWriteItems`). |
+| [Class hydration](./docs/class-hydration.md) | Opt-in `options.hydrate` that loads read results into host objects (Phase 1: `query` top level). |
+| [Multi-language / Python bridge](./docs/python-bridge.md) | Code generation with TS as the SSoT and a Python runtime; TS↔Python conformance. |
+| [In-memory test adapter](./docs/testing.md) | Docker-free in-process testing with `graphddb/testing` and `MemoryInspector`. |
+| [CDC emulator](./docs/cdc-emulator.md) | A change-event emulator for differential aggregation patterns (dev/test). |
+| [Benchmark](./benchmark/RESULTS.md) | Library comparison against hand-written AWS SDK, ElectroDB, DynamoDB Toolbox, and OneTable. |
 
 ## 💡 Examples
 
-| Example | 内容 |
+| Example | Description |
 |---------|-------------|
-| [user-permissions](./examples/user-permissions/) | Single Table Design でユーザー・グループ・パーミッションを管理する。隣接リスト、転置インデックス、relation traversal、`explain` を含む。 |
-| [aggregate-tree-pattern](./examples/aggregate-tree-pattern/) | CDC emulator で駆動される差分的なツリー集計（`siteScoreAverage`）: dirty 伝播、throttle 付き sweep、再計算。 |
-| [embedded-snapshot-pattern](./examples/embedded-snapshot-pattern/) | リレーションを **維持アクセスパス** として扱う（Epic #118）: `pattern: 'embeddedSnapshot'` のリレーションが、source write と同一の atomic transaction で、非正規化された collection / snapshot を owner 行に同期維持する。 |
-| [aggregate-counter](./examples/aggregate-counter/) | RFC §5.2 の `@aggregate` **counter**: `ThreadPost.created`/`removed` のライフサイクルが、source write と同一の `TransactWriteItems` 内で atomic な `ADD ±1` により `ThreadCounter.postCount` を同期維持する。 |
+| [user-permissions](./examples/user-permissions/) | Manages users, groups, and permissions with Single Table Design. Includes adjacency lists, inverted indexes, relation traversal, and `explain`. |
+| [aggregate-tree-pattern](./examples/aggregate-tree-pattern/) | Differential tree aggregation (`siteScoreAverage`) driven by the CDC emulator: dirty propagation, throttled sweeps, recomputation. |
+| [embedded-snapshot-pattern](./examples/embedded-snapshot-pattern/) | Treating a relation as a maintained access path (Epic #118): `pattern: 'embeddedSnapshot'` keeps a denormalized collection / snapshot synchronized onto the owner row in the same atomic transaction as the source write. |
+| [aggregate-counter](./examples/aggregate-counter/) | The `@aggregate` counter from RFC §5.2: the `ThreadPost.created` / `removed` lifecycle keeps `ThreadCounter.postCount` synchronized via an atomic `ADD ±1` within the same `TransactWriteItems` as the source write. |
 
 ## ✨ Features
 
-- Entity メタデータ / decorator
-- DDBModel 基底クラス / コネクション管理
-- 型システム（SelectableOf, QueryResult, QueryKeyOf）
-- CRUD（put, update, delete, 条件付き書き込み —— `WriteCondition` は宣言的 filter operator の
-  フルセットに加え `cond` raw escape hatch を共有する）
-- Query / List（planner, executor, hydrator, cursor pagination）
-- 型安全な filtering: 宣言的なサーバーサイド `filter`（FilterExpression / AppSync
-  `ModelFilterInput` 互換）、加えて `Model.col` のカラム参照と `cond` raw escape hatch
-- 構造化 segment キー（`k` タグ）: partial key は segment 境界で `begins_with` にコンパイルされる
-- 説明可能な実行計画
-- Relation（hasMany, belongsTo, hasOne, depth 制限, traversal）
-- 維持アクセスパス（Epic #118）: `pattern: 'embeddedSnapshot'` のリレーションが非正規化された collection / 単一行 snapshot を owner 行に同期維持し、`@aggregate` `count()` カウンタが atomic な `ADD ±1` で同期する。いずれも source write の atomic transaction に合成される（`maintainedOn` cross-entity トリガ、関数形 `projection`）。同期（`updateMode: 'mutation'`）の維持は TS / Python 両方で動作（conformance 検証済み）。stream / trim / `max()` / `materializedView` / `sparseView` は後続フェーズ
-- BatchGet 最適化
-- 並列 relation 実行（独立したサブクエリ、BatchGet チャンク、ネストした解決を上限付きの
-  並列度で同時にディスパッチ）
-- Linter（no-scan, require-limit, query-boundary, GSI ambiguity, 拡張された design rule）
-- ConsistentRead の型制約
-- Transaction DSL
-- Batch 操作
-- CQRS Query/Command contract レイヤー（public IF, N+1 安全な合成, context 境界）—— [docs](./docs/cqrs-contract.md) を参照
-- Mutation → command derivation: Command IF の背後にある内部的な write-plan 合成 DSL
-  （`entityWrites` + `mutation`）、複数 fragment の atomic 合成を1つの `TransactWriteItems` に
-  —— [docs](./docs/mutation-command-derivation.md) を参照
-- Opt-in class hydration（`options.hydrate`）: read 結果をホストオブジェクトにロードする;
-  ホスト専用で、シリアライズされない。Phase 1（`query` トップレベル）実装済み
-  —— [docs](./docs/class-hydration.md) を参照
-- Multi-language: TS を SSoT とした Python コード生成器 + runtime、TS↔Python の conformance 付き
-  —— [docs](./docs/python-bridge.md) を参照
-- In-memory test adapter（`graphddb/testing`）: Docker 不要のユニットテスト —— [docs](./docs/testing.md) を参照
-- CDC emulator: dev/test 向けの DynamoDB Streams 相当の変更イベント —— [docs](./docs/cdc-emulator.md) を参照
+- Entity metadata / decorators (`@model({ description })` propagates into the manifest / Python docstrings)
+- DDBModel base class / connection management
+- Type system (SelectableOf, QueryResult, QueryKeyOf)
+- Read: `query` (PK / unique GSI single lookup) / `list` (cursor pagination), planner / executor / hydrator
+- Write: `DDBModel.mutate` unified envelope (transaction / parallel, atomic composition of multiple fragments,
+  key-array bulk, `result` read-back) as the primary path, with raw `putItem` / `updateItem` / `deleteItem`
+  as secondary base operations
+- Type-safe filtering: declarative server-side `filter` (FilterExpression / AppSync `ModelFilterInput`
+  compatible), `Model.col` column references and the `cond` raw escape hatch (shared by read filter / write `condition`)
+- Structured segment keys (`k` tag): a partial key compiles to `begins_with` at a segment boundary
+- Explainable execution plans (`explain`)
+- Relations (hasMany, belongsTo, hasOne, depth limits, parallel traversal, N+1-safe BatchGet)
+- Maintained access paths (Epic #118): `pattern: 'embeddedSnapshot'` relations, `@aggregate` `count()` counters
+  (atomic `ADD ±1`), `@model({ kind })` + `@maintainedFrom`. Synchronized maintenance (`updateMode: 'mutation'`)
+  works in both TS / Python (conformance-verified). stream / `max()` / `materializedView` / `sparseView` are later
+- Middleware / Hooks (`DDBModel.use`): host-side hooks read R1–R5 / write W1–W5, `{ context }` —— non-serialized
+- Retry / throttling (single op / fan-out / transaction, full-jitter exponential backoff, global / per-call tuning)
+- Linter (no-scan, require-limit, query-boundary, GSI ambiguity)
+- Typed constraints on ConsistentRead, the Transaction DSL, Batch operations
+- CQRS Query/Command contract layer —— [docs](./docs/cqrs-contract.md)
+- Mutation → command derivation (`entityWrites` + `mutation`) —— [docs](./docs/mutation-command-derivation.md)
+- Opt-in class hydration (`options.hydrate`, Phase 1 implemented) —— [docs](./docs/class-hydration.md)
+- Multi-language: a Python code generator + runtime with TS as the SSoT, TS↔Python conformance —— [docs](./docs/python-bridge.md)
+- In-memory test adapter (`graphddb/testing`) —— [docs](./docs/testing.md)
+- CDC emulator —— [docs](./docs/cdc-emulator.md)
 
 ## 📄 License