graphddb 0.4.2 → 0.5.0

package/README.md

@@ -1,26 +1,49 @@
 # GraphDDB
 
-**A type-safe Graph Query Runtime for DynamoDB**
+**Build GraphQL-like queries directly on DynamoDB —— while keeping every access pattern explicit.**
 
-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 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.
 
-It is not an ORM. It is a Runtime for **defining, validating, and executing** DynamoDB access patterns through TypeScript types.
+## ✨ Features
 
-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.
+- ✅ **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。使うクライアントを入れる:
+# AWS SDK v3 is a peer dependency. Install the clients you use:
 npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
 ```
 
 `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):
+(`graphddb generate …`) directly against TypeScript definitions (library consumers do not need it):
 
 ```bash
 npm install -D tsx
@@ -46,498 +69,151 @@ class UserModel extends DDBModel {
 }
 const User = UserModel.asModel();
 
-// クライアントは一度だけ接続。GraphDDB が throttle / transient の retry を所有するため
-// `maxAttempts: 1` にして二重 retry（SDK × ライブラリ）を避ける（後述 "Retry & throttling"）。
+// 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 });
 
-// WRITE —— 複数アイテムを 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.' } },
 });
 
-// 単一アイテムの raw な base 操作（DynamoDB API 名に倣う）。
+// Raw base operations on a single item (named after the DynamoDB API).
 await User.putItem({ userId: 'alice', name: 'Alice' });
 ```
 
-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
-
-The snippets below are condensed from the [user-permissions](./examples/user-permissions/) example.
-
-### Entity Definition
-
-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', description: 'アプリのユーザー' })
-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();
-```
-
-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,
+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).
 
-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
-```
-
-### Read: `query` / `list`
-
-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（unique GSI）でユーザーを取得し、group membership へ traverse する。
-const alice = await User.query(
-  { email: 'alice@example.com' },
-  {
-    userId: true,
-    name: true,
-    groups: {
-      select: { groupId: true, role: true },
-      limit: 20,
-    },
-  },
-);
-// alice: { name: string; groups: { items: { groupId; role }[]; cursor: string | null } }
+// 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 });
 
-// 未定義のキーフィールド -> コンパイルエラー
-User.query({ foo: 'bar' }, { name: true });
+// 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
 ```
 
-`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):
+## 🔎 Inspect Execution Plans (Explain)
 
-```ts
-const result = await GroupMembership.list(
-  { groupId: 'eng' },
-  { userId: true, role: true },
-  { limit: 20, after: cursor },
-);
-// result.items: GroupMembership[] ; result.cursor: string | null
-```
-
-### Filtering (server-side `filter`)
-
-`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`.
+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 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 } }],
-    },
-  },
+const plan = GroupMembership.explain(
+  { groupId: 'eng' },
+  { select: { userId: true, role: true }, limit: 10 },
 );
+// {
+//   operations: [{
+//     type: "Query",
+//     tableName: "UserPermissions",
+//     keyCondition: { PK: "GROUP#eng" },
+//     rangeCondition: { operator: "begins_with", key: "SK", value: "USER#" },
+//     limit: 10,
+//   }]
+// }
 ```
 
-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})`
-```
-
-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).
-
-> **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.
-
-### Write: `DDBModel.mutate` (unified envelope)
-
-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.
-
-A write route descriptor is `{ 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' });
-```
-
-- **`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({
-  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 }
-```
-
-### Raw base operations: `putItem` / `updateItem` / `deleteItem`
-
-`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`:
+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
-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' });
-```
+## 🧪 Testing (strongly recommended)
 
-If you need conditional gates, read-back, or referential side effects, use `DDBModel.mutate` rather than the raw primitives.
+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).
 
-### Relation Traversal
+## 🔗 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):
+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
-// 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 } },
-            },
-          },
-        },
+        group: { select: { name: true } },   // membership -> Group (belongsTo, BatchGet)
       },
       limit: 20,
     },
   },
-  { maxDepth: 3 },   // traversal はデフォルト depth=1。深い traversal は明示許可が必要。
+  { maxDepth: 2 },   // traversal defaults to depth=1. Deeper traversal must be explicitly allowed.
 );
 ```
 
-### Inspect Execution Plans
+`hasMany` / `list` require a default / max limit. For the complete relation model, see
+[`docs/spec.md`](./docs/spec.md).
 
-`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(
-  { groupId: 'eng' },
-  { select: { userId: true, role: true }, limit: 10 },
-);
-// {
-//   operations: [{
-//     type: "Query",
-//     tableName: "UserPermissions",
-//     keyCondition: { PK: "GROUP#eng" },
-//     rangeCondition: { operator: "begins_with", key: "SK", value: "USER#" },
-//     limit: 10,
-//   }]
-// }
-```
-
-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#" }`).
-
-### Maintained Access Paths (0.4.x / Epic #118)
+## 🧩 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 —— and all of it is composed into the same atomic transaction as the source write.
-
-- **`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`:
-
-  ```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[];
-  ```
-
-- **`@aggregate` counter** —— keeps a scalar aggregate (`count()`, etc.) synchronized with an atomic `ADD ±1`:
-
-  ```ts
-  @aggregate(() => ThreadPostModel, { threadId: 'threadId' }, {
-    pattern: 'counter',
-    value: count(),
-    write: { maintainedOn: ['ThreadPost.created', 'ThreadPost.removed'] },
-  })
-  postCount!: number;
-  ```
-
-- **`@model({ kind })` + `@maintainedFrom`** —— declare a view as *its own model* and bind each source
-  with a class-level `@maintainedFrom` (`materializedView` / `sparseView`).
-
-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:
+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/).
 
-### Middleware / Hooks (`DDBModel.use`)
-
-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
-import { DDBModel } from 'graphddb';
-
-DDBModel.use({
-  name: 'tenant-scope',
-  read:  { before(ctx) { /* ctx を観測 / 変更、throw でキャンセル */ } },
-  write: { before(ctx) { /* ctx.input / ctx.kind を変更可 */ } },
-});
-DDBModel.clearMiddleware();   // 全解除（テスト teardown 等）
-```
-
-`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
-
-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).
-
-> 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
-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 } });
-```
-
-## 👥 Example: User Permissions
-
-[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:
-
-```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` 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.
-
-At its core is the natural correspondence between GraphQL's query model and DynamoDB's access patterns:
-
-```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).
-
-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.
-
-### Design Rules
-
-| 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
-    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(["✅ 型付き結果"])
-```
-
-## 🧱 Beyond the Core
-
-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.
+## ⚙️ 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).
+- **CloudFormation generation** —— `graphddb generate cloudformation` emits a CloudFormation template for
+  the DynamoDB table(s) a model set maps onto (GSI union / Streams / TTL / PITR / PROVISIONED / Auto
+  Scaling). [`docs/cloudformation.md`](./docs/cloudformation.md).
 
 ## 📚 Documentation
 
+**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.
+
 | Document | Description |
 |----------|-------------|
 | [Specification](./docs/spec.md) | Core API: entities, structured keys/GSIs, query/filter, relations, batch/transaction, design rules, runtime behavior. |
@@ -549,6 +225,7 @@ The query / relation / write APIs above are the core layer. GraphDDB additionall
 | [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). |
+| [CloudFormation generation](./docs/cloudformation.md) | The `generate cloudformation` command: emit a CloudFormation template for the DynamoDB table(s) a model set maps onto (GSI union / Streams / TTL / PITR / TableClass / SSE / PROVISIONED / Auto Scaling). All options, derivation rules, and scope boundary. |
 | [Benchmark](./benchmark/RESULTS.md) | Library comparison against hand-written AWS SDK, ElectroDB, DynamoDB Toolbox, and OneTable. |
 
 ## 💡 Examples
@@ -557,36 +234,28 @@ The query / relation / write APIs above are the core layer. GraphDDB additionall
 |---------|-------------|
 | [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. |
+| [embedded-snapshot-pattern](./examples/embedded-snapshot-pattern/) | Treating a relation as a maintained access path: `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
+## 🏛 Architecture
 
-- 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)
+A query travels from the TS Model through the Planner / Runtime to DynamoDB:
+
+```mermaid
+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")]
+```
+
+From the same TS Model (the SSoT), multiple targets are derived:
+
+```mermaid
+flowchart LR
+    M["TS Model (SSoT)"] --> RT["Runtime (TS)"]
+    M --> PY["Python client + runtime"]
+    M --> CQ["CQRS Contract"]
+```
 
 ## 📄 License