graphddb 0.4.1 → 0.4.3

package/README.md

@@ -1,62 +1,55 @@
 # GraphDDB
 
-**DynamoDB のための型安全な Graph Query Runtime**
+**Build GraphQL-like queries directly on DynamoDB —— while keeping every access pattern explicit.**
 
-GraphDDB は DynamoDB のネイティブなアクセスパターンを GraphQL ライクなクエリモデルにマッピングする。
-PK、GSI、Projection、Relation、Cursor、そして操作の上限（limit）はすべて隠さず可視に保たれる。
+GraphDDB is a type-safe Runtime that 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.
+It is not an ORM —— it is for **defining, validating, and executing** DynamoDB access patterns through
+TypeScript types.
 
-GraphDDB は ORM ではない。
-TypeScript の型を使って DynamoDB のアクセスパターンを定義・検証・実行するための Runtime である。
-
-## 🤔 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
-```
+## ✨ Features
 
-Partition Key は Graph のエントリポイントであり、relation は明示的な traversal パスであり、
-projection は selection set である。GraphDDB はクエリ言語を発明しない —— よく設計された
-アクセスパターンを直接実行し、plan・limit・relation 解決を通じて曖昧さを可視化する。
+- ✅ **Type-safe models** —— the TS class is the single source of truth. Keys / GSIs / field types are checked at compile time.
+- ✅ **Graph-style traversal** —— nest `@hasMany` / `@belongsTo` / `@hasOne` inside `select`.
+- ✅ **Automatic access-pattern resolution** —— the runtime picks the PK / GSI from the fields you give.
+- ✅ **Projection** —— only `select`ed fields are read, and only those appear in the result type.
+- ✅ **Execution plan (Explain)** —— inspect the execution plan before touching DynamoDB.
+- ✅ **CQRS contracts** —— public Query/Command contracts (N+1-safe, context boundaries).
+- ✅ **Python generation** —— generate a Python client + runtime from TS as the SSoT (conformance-verified).
+- ✅ **Testing adapter** —— unit-test planner / traversal / transaction / CDC with an in-memory executor.
+- ✅ **Middleware** —— host-side hooks for reads / writes (logging, tenant, authorization).
+- ✅ **CDC emulator** —— drive and test change events equivalent to DynamoDB Streams locally.
+- ✅ **Maintained access paths** —— keep embedded snapshots / aggregate counters synchronized atomically.
+
+## 🤔 Philosophy
+
+- **Native DynamoDB access patterns** —— express access patterns directly in code instead of hiding them
+  behind an ORM abstraction. Because PK / GSI, projection, and limits stay visible, the correct design
+  becomes the easiest path.
+- **Graph-style traversal** —— GraphQL's query model (arguments → key lookup, selection → projection,
+  relation → Query/Get/BatchGet) corresponds naturally to DynamoDB's access patterns.
+- **Compile-time safety** —— undefined relations, missing GSIs, limit-less lists, and traversals exceeding
+  the allowed depth are rejected before execution at compile time / by the linter. The same constraints
+  apply equally to human-written and AI-generated code.
+- **Runtime transparency** —— the runtime is not a black box. `explain()` shows the execution plan, and the
+  plan reveals the shape of RCU usage.
 
 ## 📦 Install
 
 ```bash
 npm install graphddb
-```
-
-AWS SDK v3 は peer dependency である —— 使用するクライアントをインストールすること:
-
-```bash
+# AWS SDK v3 is a peer dependency. Install the clients you use:
 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):
 
 ```bash
 npm install -D tsx
 ```
 
-Node.js ≥ 22 が必要。
+Node.js ≥ 22 is required.
 
 ## 🚀 Quick Start
 
@@ -76,403 +69,41 @@ class UserModel extends DDBModel {
 }
 const User = UserModel.asModel();
 
-// DynamoDB クライアントは一度だけ接続する。GraphDDB が throttle / transient の retry を
-// 所有するため（後述の "Retry & throttling" を参照）、クライアントは `maxAttempts: 1` に設定し、
-// 二重 retry（SDK × ライブラリ）を避けること。
+// Connect the client once. GraphDDB owns throttle / transient retries, so set
+// `maxAttempts: 1` to avoid double retries (SDK × library) — see "Retry & throttling" below.
 DDBModel.setClient(new DynamoDBClient({ maxAttempts: 1 }));
 
-// Read —— 結果の型に現れるのは select したフィールドのみ。
+// READ —— only the fields you select appear in the result type.
 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 —— a unified envelope that writes multiple items atomically (default 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
-```
-
-独立した relation のサブクエリ（ここでは `members` と `permissions`）は並列にディスパッチされる。
-2番目のクエリの `belongsTo` 解決は N 件の lookup を1回の `BatchGetItem` にバッチ化する。
-並列ディスパッチを示すタイムラインは [example](./examples/user-permissions/) を参照。
-
-## 📖 Usage
-
-以下のスニペットは [user-permissions](./examples/user-permissions/) の例を圧縮したものである。
-
-### Entity Definition
-
-TypeScript クラスが単一の真実の源（single source of truth）である。Key と GSI は `k`
-タグ付きテンプレートの **segment** から構築され、key builder の入力型がそのまま
-クエリパラメータの型になる。
-
-```ts
-const TABLE = 'UserPermissions';
-
-@model({ table: TABLE, 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;
-
-  @hasMany(() => GroupMembershipModel, { userId: 'userId' }, {
-    limit: { default: 20, max: 100 },
-  })
-  groups!: GroupMembershipModel[];
-}
-
-@model({ table: TABLE, prefix: 'GROUP' })
-class GroupMembershipModel extends DDBModel {
-  static readonly keys = key<{ groupId: string; userId: string }>((c) => ({
-    pk: k`GROUP#${c.groupId}`,
-    sk: k`USER#${c.userId}`,
-  }));
-
-  static readonly userGroupsIndex = gsi<{ userId: string; groupId: string }>(
-    'GSI1',
-    (c) => ({ pk: k`USER#${c.userId}`, sk: k`GROUP#${c.groupId}` }),
-  );
 
-  @string groupId!: string;
-  @string userId!: string;
-  @string role!: string;
-}
-
-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) を参照。
-
-### GraphQL-like Queries
-
-第1引数は「どうやってデータを見つけるか」を記述する。
-第2引数は「何を返すか」を記述する。
-Runtime は与えられたフィールド名から、どのインデックスを使うかを解決する。
-
-```ts
-// email でユーザーを取得し、group membership へ traverse する。
-const alice = await User.query(
-  { email: 'alice@example.com' },
-  {
-    userId: true,
-    name: true,
-    groups: {
-      select: { groupId: true, role: true },
-      limit: 20,
-    },
-  },
-);
-
-// 未定義のキーフィールド -> コンパイルエラー
-User.query({ foo: 'bar' }, { name: true });
-```
-
-返り値の型は `select` から推論される:
-
-```ts
-// alice: {
-//   name: string;
-//   groups: {
-//     items: { groupId: string; role: string }[];
-//     cursor: string | null;
-//   };
-// }
-```
-
-### List Queries
-
-```ts
-const result = await GroupMembership.list(
-  { groupId: 'eng' },
-  { userId: true, role: true },
-  { limit: 20, after: cursor },
-);
-// result.items: GroupMembership[]
-// result.cursor: string | null
-```
-
-### Filtering（サーバーサイド `filter`）
-
-`filter` は宣言的で型安全な条件であり、DynamoDB の **`FilterExpression`** にコンパイルされ、
-**サーバーサイド** で評価される。AWS AppSync の `ModelFilterInput` をモデルにしている:
-裸の値は等価の省略記法、operator オブジェクトは比較を表現し、`and` / `or` / `not` で
-論理グループを構築する。**エンティティ全体** に対して型付けされるため、`select` に **含まれない**
-属性も参照できる。
-
-```ts
-const result = await Order.list(
-  { userId: 'u001' },
-  { orderId: true },                  // amount / status は projection 不要
-  {
-    filter: {
-      status: 'confirmed',            // #status = :v        (等価の省略記法)
-      amount: { gt: 100 },            // #amount > :v
-      title:  { beginsWith: 'A' },    // begins_with(#title, :v)
-      shippedAt: { attributeExists: true },
-      or: [{ status: 'pending' }, { amount: { lt: 10 } }],
-    },
-  },
-);
+// Raw base operations on a single item (named after the DynamoDB API).
+await User.putItem({ userId: 'alice', name: 'Alice' });
 ```
 
-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>` 参照を使わなければならない。値はパラメータ化される:
+Reads center on `query` (a single PK / unique GSI lookup) / `list` (multiple items, with a cursor).
+Writes center on `DDBModel.mutate` (a unified envelope), while `putItem` / `updateItem` / `deleteItem` are
+positioned secondarily as raw base operations named after the DynamoDB API. For the full API and options,
+see [`docs/spec.md`](./docs/spec.md).
 
 ```ts
-filter: cond`${Order.col.amount} > ${100} AND attribute_exists(${Order.col.status})`
-```
-
-すべての値はパラメータ化され（`ExpressionAttributeValues`）、すべてのカラム名は
-エイリアス化される（`ExpressionAttributeNames`）—— リテラルの補間は存在しないため、
-コンパイルされた式はインジェクション安全であり、`KeyConditionExpression` /
-`ProjectionExpression` とは独立して付与される。
-
-同じ `cond` fragment は read filter としてだけでなく、書き込みの `condition`
-（`putItem` / `updateItem` / `deleteItem`、transaction item、public command に対して）
-としても受け付けられる。
-
-> **RCU に関する注意:** `FilterExpression` は read capacity を **削減しない** ——
-> DynamoDB はまずマッチするキーを読み、その後に filter する。`limit` は filter の
-> **前** に適用されるため、1ページが `limit` **未満** のアイテムを返すことがある
-> （そしてページ全体が filter で除外された場合、null でない cursor を持つ空ページになる）。
-> 効率的な絞り込みのためにキーを設計し、`filter` は正しさのために使うこと。
-
-### Writes
-
-raw な base テーブルの書き込みは `putItem` / `updateItem` / `deleteItem` である ——
-ライフサイクルのセマンティクスを持たないプリミティブな単一アイテム操作:
-
-```ts
-await User.putItem({
-  userId: 'alice',
-  name: 'Alice',
-  email: 'alice@example.com',
-  status: 'active',
-});
-
-await GroupMembership.putItem({
-  groupId: 'eng',
-  userId: 'alice',
-  role: 'admin',
-});
+// query: the 1st argument says "how to find it", the 2nd says "what to return". The return type is inferred from select.
+const alice = await User.query({ userId: 'alice' }, { name: true });
 
-await User.updateItem({ userId: 'alice' }, { status: 'disabled' });
+// list: keys that return multiple items use a cursor-based list.
+const page = await GroupMembership.list({ groupId: 'eng' }, { userId: true, role: true }, { limit: 20 });
+// page.items / page.cursor
 ```
 
-ライフサイクルを意識した単一書き込み —— 条件ゲート、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 の並列フィールド解決とまったく同じである:
-
-```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 }
-```
-
-read route の記述子は `{ query | list: Model, key, select, options? }` である
-（`query` / `list` のいずれか一方）。`query` の `options` は
-`{ consistentRead?, maxDepth? }`、`list` の場合は `{ limit?, after?, order?, filter? }` である。
-
-`DDBModel.mutate(map, { mode })` は write route を実行する。write route の記述子は
-`{ create | update | remove: Model, key, input?, condition?, result? }` である:
-
-```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' });
-```
+## 🔎 Inspect Execution Plans (Explain)
 
-- **`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 である。
-
-### Inspect Execution Plans
-
-`explain()` は、実行される前の DynamoDB 操作を表示する。
-`select` は `ProjectionExpression` に変換されるため、要求した属性のみが読まれる。
+This is what sets GraphDDB apart. `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,252 +115,144 @@ 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 the complete shape of the plan (such as the `rangeCondition` separation on a GSI partial match), see
+[`docs/spec.md`](./docs/spec.md).
 
-```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#"
-//     },
-//     ...
-//   }]
-// }
-```
-
-## 🧠 Core Concepts
-
-### Entity = Access Pattern
-
-Entity は ORM モデルではない。
-DynamoDB に対する、境界付けられたアクセス表面（bounded access surface）である。
-
-Entity は、サービス境界内でデータにアクセスする、サポートされたすべての方法を定義する:
-
-- 物理キー
-- GSI
-- relation
-- projection
-- traversal ルール
+## 🧪 Testing (strongly recommended)
 
-物理的には、Entity は DynamoDB の item にマップされる。
-アーキテクチャ的には、サービスのその部分に許可されたアクセス表面を定義する。
+The **in-memory executor** in `graphddb/testing` lets you fully unit-test planner / relation traversal /
+transaction / CDC with **no Docker and no DynamoDB Local**. Because it never touches a real DynamoDB and
+runs in-process, you can verify model-mapping, query-plans, relation resolution, and differential
+aggregation while keeping CI fast and deterministic. See [`docs/testing.md`](./docs/testing.md).
 
-### Key / GSI = Structured Segments
+## 🔗 Relation Traversal
 
-`key()` と `gsi()` は `k` タグ付きテンプレートの **segment** からキーを構築する。builder の
-入力型がキー解決に必要なフィールドを定義し、同時にクエリパラメータの型にもなる。
+A relation is a query bound to the value of the parent entity. Declare it with `@hasMany` / `@belongsTo` /
+`@hasOne` and traverse it by nesting inside `select`. Independent relation subqueries are dispatched in
+parallel, and N `belongsTo` resolutions are aggregated into a single `BatchGetItem` (no N+1):
 
 ```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 },
+const alice = await User.query(
+  { email: 'alice@example.com' },
+  {
+    name: true,
+    groups: {
+      select: {
+        role: true,
+        group: { select: { name: true } },   // membership -> Group (belongsTo, BatchGet)
+      },
+      limit: 20,
+    },
+  },
+  { maxDepth: 2 },   // traversal defaults to depth=1. Deeper traversal must be explicitly allowed.
 );
 ```
 
-キーは不透明な文字列ではなく構造化された segment であるため、partial key —— sort-key
-segment の先頭プレフィックスのみを与えたもの —— はその segment 境界で `begins_with` に
-コンパイルされる。これが relation と prefix クエリの解決方法である。
-
-### Relation = Bound Query
-
-Relation は、親 Entity の値にバインドされたクエリである。
-同じ解決ロジックが適用される: runtime はフィールド名を Key / GSI 定義に照合する。
+`hasMany` / `list` require a default / max limit. For the complete relation model, see
+[`docs/spec.md`](./docs/spec.md).
+
+## 🧩 Maintained Access Paths
+
+Declaring a relation or scalar as a **maintained access path** keeps a *separate* row in sync with the
+lifecycle of the source entity (all of it composed into the same atomic transaction as the source write):
+
+- **embedded snapshot** —— `pattern: 'embeddedSnapshot'` on `@hasMany` / `@hasOne` keeps a projected
+  snapshot / bounded collection synchronized onto the owner row.
+- **aggregate counter** —— `@aggregate` + `count()` keeps a scalar aggregate synchronized with an atomic `ADD ±1`.
+- **materialized view / sparse view** —— `@model({ kind })` + `@maintainedFrom` declare a view as its own
+  model (later phases).
+- **versioned history** —— maintenance of versioned history rows.
+
+Synchronized maintenance (`updateMode: 'mutation'`) works in both TS and Python (conformance-verified). For
+how to declare them, the pattern mapping table, and per-phase coverage, see
+[`docs/design-patterns.md`](./docs/design-patterns.md). Examples:
+[embedded-snapshot-pattern](./examples/embedded-snapshot-pattern/) /
+[aggregate-counter](./examples/aggregate-counter/).
+
+## ⚙️ Runtime
+
+The runtime's responsibilities are short. For details, see [`docs/spec.md`](./docs/spec.md):
+
+- **access pattern resolution** —— pick the PK / GSI from the fields you give.
+- **projection** —— compile `select` into a `ProjectionExpression`.
+- **relation traversal** —— dispatch bound queries in parallel (N+1-safe BatchGet).
+- **retry / throttling** —— retry throttle / transient errors with full-jitter exponential backoff, no
+  configuration required (set the client to `maxAttempts: 1`, since the library owns retries).
+- **hydration** —— reconstruct raw items into typed partial entities.
+
+## 🛠 More Capabilities
+
+Each capability is summarized here only. For details, operator lists, and procedures, see each doc:
+
+- **Filtering** —— a declarative, type-safe server-side `filter` (compatible with `FilterExpression` /
+  AppSync `ModelFilterInput`). `Model.col` + the `cond` raw escape hatch are shared by read filters / write
+  `condition`s. For the operator list, see [`docs/spec.md`](./docs/spec.md).
+- **Middleware / Hooks** —— `DDBModel.use` for host-side hooks on reads / writes (logging, metrics, tenant /
+  authorization scoping). Host-only and non-serialized. For hook points, see [`docs/middleware.md`](./docs/middleware.md).
+- **Class hydration** —— `options.hydrate` loads read results into host-language domain objects (opt-in,
+  Phase 1: `query` top level). [`docs/class-hydration.md`](./docs/class-hydration.md).
+- **Python bridge** —— generate a Python client + runtime with TS as the SSoT, kept in step by a TS↔Python
+  conformance suite. [`docs/python-bridge.md`](./docs/python-bridge.md).
+- **CQRS contracts** —— public Query/Command contracts (cardinality matrix, N+1 safety, context boundaries,
+  composition across contracts). [`docs/cqrs-contract.md`](./docs/cqrs-contract.md) /
+  [`docs/mutation-command-derivation.md`](./docs/mutation-command-derivation.md).
+- **CDC emulator** —— change events equivalent to DynamoDB Streams, to drive and test differential
+  aggregation. [`docs/cdc-emulator.md`](./docs/cdc-emulator.md).
 
-```ts
-@hasMany(() => GroupMembershipModel, { userId: 'userId' }, {
-  limit: { default: 20, max: 100 },
-})
-groups!: GroupMembershipModel[];
-```
-
-### Field Decorators
-
-型安全なセマンティック decorator が DynamoDB の属性型を定義する。
-`ClassFieldDecoratorContext` に基づくコンパイル時チェックが、宣言された TypeScript の型と
-DynamoDB の型の不一致を検出する。
-
-```ts
-@string userId!: string;     // DynamoDB S
-@number amount!: number;     // DynamoDB N
-@datetime createdAt!: Date;  // ISO 8601 文字列として保存される
-@boolean isActive!: boolean; // DynamoDB BOOL
-```
+## 📚 Documentation
 
-### Select = Projection + Type Inference
+**The full documentation is bundled in the npm package** (under `docs/`). After installation you can browse
+every doc at `node_modules/graphddb/docs/`, and if you add it as a `devDependency` you have all the
+documentation available offline at hand. On GitHub, follow the links in the table below.
 
-`select` オブジェクトは DynamoDB の `ProjectionExpression` 生成と TypeScript の返り値型推論の
-両方を制御する。
-要求したフィールドだけが返り、結果の型にもそのフィールドだけが現れる。
+| Document | Description |
+|----------|-------------|
+| [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. |
 
-### Planner = Inspectable Execution Plan
+## 💡 Examples
 
-DynamoDB にアクセスする前に、runtime が実行計画（execution plan）を生成する。
-plan はテスト・デバッグ・RCU 見積もりに利用できる。
+| Example | Description |
+|---------|-------------|
+| [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. |
 
-## 🏗️ Architecture
+## 🏛 Architecture
 
-GraphDDB のクエリは 5 つのレイヤーを通って実行される:
+A query travels from the TS Model through the Planner / Runtime to DynamoDB:
 
 ```mermaid
-flowchart TD
-    L1["🧩 Layer 1: Schema Definition<br/>Entity / Field / Key / GSI / Relation / Embedded"]
-    L2["🔧 Layer 2: Query Builder<br/>型安全な DSL: key 解決 / select バリデーション"]
-    L3["🗺️ Layer 3: Query Planner<br/>Relation traversal / Get vs Query vs BatchGet 判定<br/>Projection 生成 / GSI 選択"]
-    L4["⚡ Layer 4: Executor<br/>DynamoDB DocumentClient ラッパー"]
-    L5["💧 Layer 5: Hydrator<br/>型変換 / Embedded 再構築 / メタデータ付与"]
-
-    L1 -->|EntityMetadata Registry| L2
-    L2 -->|ExecutionPlan| L3
-    L3 -->|"DynamoDBOperation[]"| L4
-    L4 -->|raw Items| L5
-    L5 -->|Partial Entity インスタンス| OUT(["✅ 型付き結果"])
+flowchart LR
+    M["TS Model<br/>Entity / Key / GSI / Relation"] --> P["Planner<br/>access pattern resolution / projection"]
+    P --> R["Runtime<br/>execute / retry / hydrate"]
+    R --> D[("DynamoDB")]
 ```
 
-## 📐 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 相当の変更イベント。
+From the same TS Model (the SSoT), multiple targets are derived:
 
-## 📚 Documentation
-
-| ドキュメント | 内容 |
-|----------|-------------|
-| [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 とのライブラリ比較。 |
-
-## 💡 Examples
-
-| Example | 内容 |
-|---------|-------------|
-| [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` を同期維持する。 |
-
-## ✨ 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) を参照
+```mermaid
+flowchart LR
+    M["TS Model (SSoT)"] --> RT["Runtime (TS)"]
+    M --> PY["Python client + runtime"]
+    M --> OA["OpenAPI"]
+    M --> CQ["CQRS Contract"]
+```
 
 ## 📄 License