graphddb 0.2.3 → 0.2.5

package/README.md

@@ -1,28 +1,27 @@
 # GraphDDB
 
-**Type-safe Graph Query Runtime for DynamoDB**
+**DynamoDB のための型安全な Graph Query Runtime**
 
-GraphDDB maps DynamoDB's native access patterns to a GraphQL-like query model:
-PK, GSI, Projection, Relation, Cursor, and operation limits all remain visible.
+GraphDDB は DynamoDB のネイティブなアクセスパターンを GraphQL ライクなクエリモデルにマッピングする。
+PK、GSI、Projection、Relation、Cursor、そして操作の上限（limit）はすべて隠さず可視に保たれる。
 
-GraphDDB is not an ORM.
-It is a runtime for defining, validating, and executing DynamoDB access patterns with TypeScript types.
+GraphDDB は ORM ではない。
+TypeScript の型を使って DynamoDB のアクセスパターンを定義・検証・実行するための Runtime である。
 
-## Why GraphDDB?
+## 🤔 Why GraphDDB?
 
-DynamoDB is fast and scalable, but easy to design incorrectly. Teams often treat it like an
-RDBMS — one table per entity, joins in application code, ad-hoc access patterns hidden behind
-ORM abstractions — and end up with unstable performance, unnecessary GSIs, and unclear service
-boundaries.
+DynamoDB は高速でスケーラブルだが、誤った設計をしやすい。チームはしばしば DynamoDB を
+RDBMS のように扱い —— エンティティごとに1テーブル、アプリケーションコード内での join、
+ORM 抽象の裏に隠れたその場しのぎのアクセスパターン —— その結果、不安定なパフォーマンス、
+不要な GSI、不明瞭なサービス境界に陥る。
 
-GraphDDB takes the opposite approach: it represents DynamoDB access patterns **directly in
-code**, keeping PK/GSI, projections, relations, cursors, and operation limits visible. Access
-patterns and relations become explicit, query plans become inspectable, and well-designed
-access patterns naturally align with service boundaries. GraphDDB does not teach DynamoDB
-design — it makes correct design the easiest way to write code.
+GraphDDB は逆のアプローチを取る。DynamoDB のアクセスパターンを **コードに直接** 表現し、
+PK/GSI、projection、relation、cursor、操作の上限を可視に保つ。アクセスパターンと relation が
+明示的になり、クエリプランが検査可能になり、よく設計されたアクセスパターンが自然と
+サービス境界に整合する。GraphDDB は DynamoDB の設計を教えるのではない —— 正しい設計を、
+コードを書く上で最も簡単な道にする。
 
-It does this through a natural correspondence between GraphQL's query model and DynamoDB's
-access patterns:
+これは GraphQL のクエリモデルと DynamoDB のアクセスパターンの自然な対応関係を通じて実現される:
 
 ```text
 GraphQL Query Model        DynamoDB
@@ -33,33 +32,33 @@ connection          ---->  Cursor pagination
 complexity          ---->  Operation limits
 ```
 
-A partition key is a graph entry point, a relation an explicit traversal path, a projection a
-selection set. GraphDDB does not invent a query language — it executes well-designed access
-patterns directly and makes ambiguity visible through plans, limits, and relation resolution.
+Partition Key は Graph のエントリポイントであり、relation は明示的な traversal パスであり、
+projection は selection set である。GraphDDB はクエリ言語を発明しない —— よく設計された
+アクセスパターンを直接実行し、plan・limit・relation 解決を通じて曖昧さを可視化する。
 
-## Install
+## 📦 Install
 
 ```bash
 npm install graphddb
 ```
 
-The AWS SDK v3 is a peer dependency — install the clients you use:
+AWS SDK v3 は peer dependency である —— 使用するクライアントをインストールすること:
 
 ```bash
 npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
 ```
 
-`tsx` is an optional peer dependency, needed only to run the code-generation CLI
-(`graphddb generate …`) directly against TypeScript definition files. Library
-consumers don't need it (so it never pulls esbuild into your runtime bundle):
+`tsx` は optional な peer dependency で、コード生成 CLI（`graphddb generate …`）を
+TypeScript の定義ファイルに対して直接実行する場合にのみ必要となる。ライブラリの利用者には
+不要である（そのため esbuild がランタイムバンドルに混入することはない）:
 
 ```bash
 npm install -D tsx
 ```
 
-Requires Node.js ≥ 22.
+Node.js ≥ 22 が必要。
 
-## Quick Start
+## 🚀 Quick Start
 
 ```ts
 import { DDBModel, model, string, key, k } from 'graphddb';
@@ -77,28 +76,76 @@ class UserModel extends DDBModel {
 }
 const User = UserModel.asModel();
 
-// Wire up the DynamoDB client once (configure retries/region on the client itself).
-DDBModel.setClient(new DynamoDBClient({}));
+// DynamoDB クライアントは一度だけ接続する。GraphDDB が throttle / transient の retry を
+// 所有するため（後述の "Retry & throttling" を参照）、クライアントは `maxAttempts: 1` に設定し、
+// 二重 retry（SDK × ライブラリ）を避けること。
+DDBModel.setClient(new DynamoDBClient({ maxAttempts: 1 }));
 
-// Read — only the selected fields appear in the result type.
+// Read —— 結果の型に現れるのは select したフィールドのみ。
 const user = await User.query({ userId: 'alice' }, { name: true });
 
-// Single-item write — raw base op, named after the DynamoDB API.
+// 単一アイテムの書き込み —— DynamoDB API にちなんで名付けられた raw な base 操作。
 await User.putItem({ userId: 'alice', name: 'Alice' });
 
-// Multi-item atomic write — the unified envelope (default `mode: 'transaction'`).
+// 複数アイテムの atomic な書き込み —— 統一 envelope（デフォルト `mode: 'transaction'`）。
 await DDBModel.mutate({
   user: { update: User, key: { userId: 'alice' }, input: { name: 'Alice B.' } },
 });
 ```
 
-For cross-service contracts, the Python bridge, multi-fragment atomic mutations,
-and more, see the sections below and [`docs/spec.md`](./docs/spec.md).
+クロスサービス contract、Python bridge、複数 fragment の atomic mutation などについては、
+以下の各セクションおよび [`docs/spec.md`](./docs/spec.md) を参照。
 
-## User Permissions Example
+## 🔁 Retry & throttling
 
-The [user-permissions](./examples/user-permissions/) example models users, groups, memberships, and permissions in a single DynamoDB table.
-This is where GraphDDB's design becomes easiest to see: the table is physical, while the query surface is graph-shaped.
+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
@@ -110,12 +157,12 @@ GroupMembership   GROUP#<groupId>     USER#<userId>              USER#<userId>
 Permission        GROUP#<groupId>     PERM#<resource>#<action>
 ```
 
-`GroupMembership` uses the adjacency list pattern:
+`GroupMembership` は隣接リスト（adjacency list）パターンを使う:
 
-- `PK/SK` reads members of a group
-- `GSI1PK/GSI1SK` reads groups for a user
+- `PK/SK` はグループのメンバーを読む
+- `GSI1PK/GSI1SK` はユーザーが所属するグループを読む
 
-The same physical table supports both directions without hiding the keys.
+同じ物理テーブルが、キーを隠すことなく両方向をサポートする。
 
 ```ts
 const engGroup = await Group.query(
@@ -134,9 +181,9 @@ const engGroup = await Group.query(
   },
 );
 
-// Find a user by email (GSI), list their groups, and for each group fetch the
-// group and its permissions. The N memberships -> parent Group resolution
-// collapses into a single BatchGetItem (no N+1).
+// email（GSI）でユーザーを探し、所属グループを一覧し、各グループについてグループ本体と
+// そのパーミッションを取得する。N 件の membership -> 親 Group の解決は単一の
+// BatchGetItem に集約される（N+1 にならない）。
 const alice = await User.query(
   { email: 'alice@example.com' },
   {
@@ -163,24 +210,29 @@ const alice = await User.query(
 );
 ```
 
-The first query expands into a small, inspectable DynamoDB plan:
+最初のクエリは、小さく検査可能な DynamoDB plan に展開される:
 
-```text
-1. Query  PK = GROUP#eng, SK = META             -> Group
-2. Query  PK = GROUP#eng, SK begins_with USER#  -> members      ┐ dispatched
-3. Query  PK = GROUP#eng, SK begins_with PERM#  -> permissions  ┘ in parallel
+```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
 ```
 
-Independent relation sub-queries (here `members` and `permissions`) are dispatched concurrently; the `belongsTo` resolution in the second query batches N lookups into one `BatchGetItem`. See the [example](./examples/user-permissions/) for a timeline that proves the parallel dispatch.
+独立した relation のサブクエリ（ここでは `members` と `permissions`）は並列にディスパッチされる。
+2番目のクエリの `belongsTo` 解決は N 件の lookup を1回の `BatchGetItem` にバッチ化する。
+並列ディスパッチを示すタイムラインは [example](./examples/user-permissions/) を参照。
 
-## Usage
+## 📖 Usage
 
-The snippets below are compressed from the [user-permissions](./examples/user-permissions/) example.
+以下のスニペットは [user-permissions](./examples/user-permissions/) の例を圧縮したものである。
 
 ### Entity Definition
 
-A TypeScript class is the single source of truth. Keys and GSIs are built from `k` tagged-template
-**segments**, and the key builder's input type becomes the query parameter type.
+TypeScript クラスが単一の真実の源（single source of truth）である。Key と GSI は `k`
+タグ付きテンプレートの **segment** から構築され、key builder の入力型がそのまま
+クエリパラメータの型になる。
 
 ```ts
 const TABLE = 'UserPermissions';
@@ -230,18 +282,18 @@ 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 compiles to `begins_with` at the matching segment boundary. See the
-[specification](./docs/spec.md) for the full key model.
+複数 segment の sort key は segment の配列である（例: `sk: [k\`PERM#${c.resource}\`, k\`${c.action}\`]`）。
+partial key はマッチする segment 境界で `begins_with` にコンパイルされる。完全なキーモデルは
+[仕様書](./docs/spec.md) を参照。
 
 ### GraphQL-like Queries
 
-The first argument describes how to find data.
-The second argument describes what to return.
-The runtime resolves which index to use from the provided field names.
+第1引数は「どうやってデータを見つけるか」を記述する。
+第2引数は「何を返すか」を記述する。
+Runtime は与えられたフィールド名から、どのインデックスを使うかを解決する。
 
 ```ts
-// Fetch a user by email and traverse to group memberships.
+// email でユーザーを取得し、group membership へ traverse する。
 const alice = await User.query(
   { email: 'alice@example.com' },
   {
@@ -254,11 +306,11 @@ const alice = await User.query(
   },
 );
 
-// Unknown key field -> compile-time error
+// 未定義のキーフィールド -> コンパイルエラー
 User.query({ foo: 'bar' }, { name: true });
 ```
 
-The return type is inferred from `select`:
+返り値の型は `select` から推論される:
 
 ```ts
 // alice: {
@@ -282,21 +334,21 @@ const result = await GroupMembership.list(
 // result.cursor: string | null
 ```
 
-### Filtering (server-side `filter`)
+### Filtering（サーバーサイド `filter`）
 
-`filter` is a declarative, type-safe condition compiled to a DynamoDB **`FilterExpression`** and
-evaluated **server-side**. Modeled on AWS AppSync's `ModelFilterInput`: a bare value is an
-equality shorthand, an operator object expresses comparisons, and `and` / `or` / `not` build
-logical groups. It is typed against the **full entity**, so it can reference attributes that are
-**not** in `select`.
+`filter` は宣言的で型安全な条件であり、DynamoDB の **`FilterExpression`** にコンパイルされ、
+**サーバーサイド** で評価される。AWS AppSync の `ModelFilterInput` をモデルにしている:
+裸の値は等価の省略記法、operator オブジェクトは比較を表現し、`and` / `or` / `not` で
+論理グループを構築する。**エンティティ全体** に対して型付けされるため、`select` に **含まれない**
+属性も参照できる。
 
 ```ts
 const result = await Order.list(
   { userId: 'u001' },
-  { orderId: true },                  // amount / status need not be projected
+  { orderId: true },                  // amount / status は projection 不要
   {
     filter: {
-      status: 'confirmed',            // #status = :v        (equality shorthand)
+      status: 'confirmed',            // #status = :v        (等価の省略記法)
       amount: { gt: 100 },            // #amount > :v
       title:  { beginsWith: 'A' },    // begins_with(#title, :v)
       shippedAt: { attributeExists: true },
@@ -306,44 +358,44 @@ const result = await Order.list(
 );
 ```
 
-Relations take the same `filter` via `Model.relation(...)` of the target model. For logic a
-server-side `FilterExpression` cannot express, call `result.items.filter(...)` on the returned
-projection — it keeps each selected field's declared scalar type, so `o.amount > 100` needs no
-cast (there is no built-in post-load predicate).
+Relation は対象モデルの `Model.relation(...)` を通じて同じ `filter` を取る。サーバーサイドの
+`FilterExpression` で表現できないロジックには、返された projection に対して
+`result.items.filter(...)` を呼ぶこと —— 各 select フィールドの宣言済みスカラー型が保たれるため、
+`o.amount > 100` はキャスト不要である（組み込みの post-load 述語は存在しない）。
 
-Available operators (per field type): `eq`, `ne`, `ge`, `le`, `gt`, `lt`,
-`between`, `in`, `beginsWith`, `contains`, `notContains`, `attributeExists`,
-`attributeType`, `size`. Operators are **constrained by the field's declared
-type** — e.g. `beginsWith` / `contains` on a numeric field, or `gt: 'x'` on a
-number, are compile errors.
+利用可能な operator（フィールド型ごと）: `eq`、`ne`、`ge`、`le`、`gt`、`lt`、
+`between`、`in`、`beginsWith`、`contains`、`notContains`、`attributeExists`、
+`attributeType`、`size`。operator は **フィールドの宣言型によって制約される** ——
+例えば数値フィールドへの `beginsWith` / `contains`、あるいは数値への `gt: 'x'` は
+コンパイルエラーになる。
 
-For rare conditions the operator objects cannot express, the `cond` raw escape
-hatch accepts an expression fragment. Column names must use refactor-safe
-`Model.col.<field>` references (never bare strings); values are parameterized:
+operator オブジェクトでは表現できない稀な条件のために、`cond` という raw な escape hatch が
+式 fragment を受け取る。カラム名は bare な文字列ではなく、リファクタ安全な
+`Model.col.<field>` 参照を使わなければならない。値はパラメータ化される:
 
 ```ts
 filter: cond`${Order.col.amount} > ${100} AND attribute_exists(${Order.col.status})`
 ```
 
-All values are parameterized (`ExpressionAttributeValues`) and all column names
-are aliased (`ExpressionAttributeNames`) — there is no literal interpolation, so
-the compiled expression is injection-free, and it is attached independently of
-the `KeyConditionExpression` / `ProjectionExpression`.
+すべての値はパラメータ化され（`ExpressionAttributeValues`）、すべてのカラム名は
+エイリアス化される（`ExpressionAttributeNames`）—— リテラルの補間は存在しないため、
+コンパイルされた式はインジェクション安全であり、`KeyConditionExpression` /
+`ProjectionExpression` とは独立して付与される。
 
-The same `cond` fragment is also accepted as a write `condition` (on
-`putItem` / `updateItem` / `deleteItem`, transaction items, and public commands),
-not just as a read filter.
+同じ `cond` fragment は read filter としてだけでなく、書き込みの `condition`
+（`putItem` / `updateItem` / `deleteItem`、transaction item、public command に対して）
+としても受け付けられる。
 
-> **RCU note:** A `FilterExpression` does **not** reduce read capacity —
-> DynamoDB reads matching keys first, then filters. `limit` is applied
-> **before** the filter, so a single page may return **fewer** than `limit`
-> items (and, if the whole page is filtered out, an empty page with a non-null
-> cursor). Design keys for efficient narrowing; use `filter` for correctness.
+> **RCU に関する注意:** `FilterExpression` は read capacity を **削減しない** ——
+> DynamoDB はまずマッチするキーを読み、その後に filter する。`limit` は filter の
+> **前** に適用されるため、1ページが `limit` **未満** のアイテムを返すことがある
+> （そしてページ全体が filter で除外された場合、null でない cursor を持つ空ページになる）。
+> 効率的な絞り込みのためにキーを設計し、`filter` は正しさのために使うこと。
 
 ### Writes
 
-Raw base-table writes are `putItem` / `updateItem` / `deleteItem` — the primitive
-single-item operations with no lifecycle semantics:
+raw な base テーブルの書き込みは `putItem` / `updateItem` / `deleteItem` である ——
+ライフサイクルのセマンティクスを持たないプリミティブな単一アイテム操作:
 
 ```ts
 await User.putItem({
@@ -362,19 +414,18 @@ await GroupMembership.putItem({
 await User.updateItem({ userId: 'alice' }, { status: 'disabled' });
 ```
 
-Lifecycle-aware single writes — conditional gates, read-back, referential
-effects — go through `DDBModel.mutate`, not the raw primitives (see
-[The in-process unified envelope](#the-in-process-unified-envelope) below).
+ライフサイクルを意識した単一書き込み —— 条件ゲート、read-back、参照整合的な副作用 ——
+は raw なプリミティブではなく `DDBModel.mutate` を経由する（後述の
+[The in-process unified envelope](#the-in-process-unified-envelope) を参照）。
 
 ### The in-process unified envelope
 
-`DDBModel.query` and `DDBModel.mutate` take a single **alias-map envelope** that
-runs multiple routes in one call. This is the in-process analog of a GraphQL
-operation: each alias is a named route, and the result is keyed by the same
-aliases.
+`DDBModel.query` と `DDBModel.mutate` は、1回の呼び出しで複数の route を実行する単一の
+**alias-map envelope** を取る。これは GraphQL operation の in-process 版である:
+各 alias は名前付きの route であり、結果は同じ alias でキー付けされる。
 
-`DDBModel.query(map)` runs each read route independently and in parallel — there
-is no cross-route consistency, exactly like GraphQL's parallel field resolution:
+`DDBModel.query(map)` は各 read route を独立かつ並列に実行する —— route 間の
+一貫性はなく、GraphQL の並列フィールド解決とまったく同じである:
 
 ```ts
 const { user, members } = await DDBModel.query({
@@ -384,12 +435,12 @@ const { user, members } = await DDBModel.query({
 // user: Item | null ; members: { items, cursor }
 ```
 
-A read route descriptor is `{ query | list: Model, key, select, options? }`
-(exactly one of `query` / `list`). `options` for `query` is
-`{ consistentRead?, maxDepth? }`; for `list` it is `{ limit?, after?, order?, filter? }`.
+read route の記述子は `{ query | list: Model, key, select, options? }` である
+（`query` / `list` のいずれか一方）。`query` の `options` は
+`{ consistentRead?, maxDepth? }`、`list` の場合は `{ limit?, after?, order?, filter? }` である。
 
-`DDBModel.mutate(map, { mode })` runs write routes. A write route descriptor is
-`{ create | update | remove: Model, key, input?, condition?, result? }`:
+`DDBModel.mutate(map, { mode })` は write route を実行する。write route の記述子は
+`{ create | update | remove: Model, key, input?, condition?, result? }` である:
 
 ```ts
 const res = await DDBModel.mutate({
@@ -398,32 +449,30 @@ const res = await DDBModel.mutate({
 }, { mode: 'transaction' });
 ```
 
-- **`key`** is a single object or an **array of objects** (key-array bulk). A
-  transaction compiles to `TransactWriteItems`; parallel mode compiles to
-  `BatchWriteItem` (chunked, with `UnprocessedItems` retry).
-- **`condition`** is a `WriteCondition` write gate — the same declarative
-  operator subset as read filters (`eq`/`ne`/comparisons/`between`/`in`/string
-  ops/`size`/`attributeType` + `and`/`or`/`not`), the legacy existence primitives
-  (`notExists` / `attributeExists` / `attributeNotExists`), or a raw `cond`
-  fragment.
-- **`result: { select, options? }`** reads the written item back; omit it and the
-  route returns void.
-- **`mode: 'transaction'`** (DEFAULT) is one atomic `TransactWriteItems`:
-  all-or-nothing rollback, throws on failure, and a map of more than 25 items
-  errors (it is never split). This is GraphQL's all-or-nothing atomic contract.
-- **`mode: 'parallel'`** is non-atomic: each alias reports partial success in the
-  result object as `{ ok }` | `{ error }`, mirroring GraphQL's per-field partial
-  success. Independent ops run in parallel; dependencies are ordered by
-  `$.alias.field` references.
-
-In GraphQL terms: a transaction is atomic all-or-nothing; parallel is non-atomic
-per-field partial success; and `query` routes are parallel independent reads with
-no cross-route consistency.
+- **`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()` shows the DynamoDB operations before they are executed.
-`select` is converted into a `ProjectionExpression`, so only requested attributes are read.
+`explain()` は、実行される前の DynamoDB 操作を表示する。
+`select` は `ProjectionExpression` に変換されるため、要求した属性のみが読まれる。
 
 ```ts
 const plan = GroupMembership.explain(
@@ -445,7 +494,7 @@ const plan = GroupMembership.explain(
 // }
 ```
 
-For partial GSI key matches, the SK condition is separated as a `rangeCondition`:
+partial な GSI キーマッチの場合、SK 条件は `rangeCondition` として分離される:
 
 ```ts
 const gsiPlan = GroupMembership.explain(
@@ -467,33 +516,33 @@ const gsiPlan = GroupMembership.explain(
 // }
 ```
 
-## Core Concepts
+## 🧠 Core Concepts
 
 ### Entity = Access Pattern
 
-An Entity is not an ORM model.
-It is a bounded access surface for DynamoDB.
+Entity は ORM モデルではない。
+DynamoDB に対する、境界付けられたアクセス表面（bounded access surface）である。
 
-An Entity defines every supported way to access data within a service boundary:
+Entity は、サービス境界内でデータにアクセスする、サポートされたすべての方法を定義する:
 
-- physical keys
-- GSIs
-- relations
-- projections
-- traversal rules
+- 物理キー
+- GSI
+- relation
+- projection
+- traversal ルール
 
-Physically, an Entity maps to a DynamoDB item.
-Architecturally, it defines the allowed access surface for that part of the service.
+物理的には、Entity は DynamoDB の item にマップされる。
+アーキテクチャ的には、サービスのその部分に許可されたアクセス表面を定義する。
 
 ### Key / GSI = Structured Segments
 
-`key()` and `gsi()` build keys from `k` tagged-template **segments**. The builder's input type
-defines the fields required to resolve the key, and also becomes the query parameter type.
+`key()` と `gsi()` は `k` タグ付きテンプレートの **segment** からキーを構築する。builder の
+入力型がキー解決に必要なフィールドを定義し、同時にクエリパラメータの型にもなる。
 
 ```ts
-// One definition serves two roles:
-// 1. Write path: generate PK/SK when saving an Entity
-// 2. Query path: define the parameter type for User.query({ email: ... })
+// 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` }),
@@ -501,14 +550,14 @@ static readonly emailIndex = gsi<{ email: string }>(
 );
 ```
 
-Because keys are structured segments rather than opaque strings, a partial key — one supplying
-only a leading prefix of the sort-key segments — compiles to `begins_with` at that segment
-boundary. This is how relations and prefix queries resolve.
+キーは不透明な文字列ではなく構造化された segment であるため、partial key —— sort-key
+segment の先頭プレフィックスのみを与えたもの —— はその segment 境界で `begins_with` に
+コンパイルされる。これが relation と prefix クエリの解決方法である。
 
 ### Relation = Bound Query
 
-A Relation is a query bound to values from the parent Entity.
-The same resolution logic applies: the runtime matches field names against Key / GSI definitions.
+Relation は、親 Entity の値にバインドされたクエリである。
+同じ解決ロジックが適用される: runtime はフィールド名を Key / GSI 定義に照合する。
 
 ```ts
 @hasMany(() => GroupMembershipModel, { userId: 'userId' }, {
@@ -519,154 +568,160 @@ groups!: GroupMembershipModel[];
 
 ### Field Decorators
 
-Type-safe semantic decorators define DynamoDB attribute types.
-Compile-time checks based on `ClassFieldDecoratorContext` detect mismatches between declared TypeScript types and DynamoDB types.
+型安全なセマンティック decorator が DynamoDB の属性型を定義する。
+`ClassFieldDecoratorContext` に基づくコンパイル時チェックが、宣言された TypeScript の型と
+DynamoDB の型の不一致を検出する。
 
 ```ts
 @string userId!: string;     // DynamoDB S
 @number amount!: number;     // DynamoDB N
-@datetime createdAt!: Date;  // stored as an ISO 8601 string
+@datetime createdAt!: Date;  // ISO 8601 文字列として保存される
 @boolean isActive!: boolean; // DynamoDB BOOL
 ```
 
 ### Select = Projection + Type Inference
 
-The `select` object controls both DynamoDB `ProjectionExpression` generation and TypeScript return type inference.
-Only requested fields are returned, and only those fields appear in the result type.
+`select` オブジェクトは DynamoDB の `ProjectionExpression` 生成と TypeScript の返り値型推論の
+両方を制御する。
+要求したフィールドだけが返り、結果の型にもそのフィールドだけが現れる。
 
 ### Planner = Inspectable Execution Plan
 
-Before DynamoDB is accessed, the runtime generates an execution plan.
-Plans can be used for tests, debugging, and RCU estimation.
+DynamoDB にアクセスする前に、runtime が実行計画（execution plan）を生成する。
+plan はテスト・デバッグ・RCU 見積もりに利用できる。
 
-## Architecture
+## 🏗️ Architecture
 
-```text
-Layer 1: Schema Definition
-    Entity / Field / Key / GSI / Relation / Embedded
-    -> EntityMetadata Registry
-
-Layer 2: Query Builder
-    Type-safe DSL: key resolution, select validation
-    -> ExecutionPlan
-
-Layer 3: Query Planner
-    Relation traversal, Get vs Query vs BatchGet decisions
-    Projection generation, GSI selection
-    -> DynamoDBOperation[]
-
-Layer 4: Executor
-    DynamoDB DocumentClient wrapper
-    -> raw Items
-
-Layer 5: Hydrator
-    raw Items -> Partial Entity instances
-    type conversion, Embedded reconstruction, metadata attachment
+GraphDDB のクエリは 5 つのレイヤーを通って実行される:
+
+```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(["✅ 型付き結果"])
 ```
 
-## Design Rules
+## 📐 Design Rules
 
-| Rule | Description |
+| ルール | 内容 |
 |------|-------------|
-| Service Boundary First | One table represents one service boundary, not one entity. |
-| Access Pattern First | Model DynamoDB access patterns before modeling tables or ORM-style entities. |
-| Natural Mapping | Map Query / Get / BatchGet / Projection / cursor to a GraphQL-like query shape. |
-| Inspectable Plans | DynamoDB operations and execution plans are inspectable before execution. |
-| Single-item query | `query` is only for PK or unique GSI lookups. Use `list` for keys that can return multiple items. |
-| Explicit limits | `hasMany` and `list` require default/max limits. |
-| Bounded depth | Relation traversal defaults to depth=1. Deeper traversal must be explicitly allowed with `maxDepth`. |
-| Parallel relations | Independent relation sub-queries, BatchGet chunks, and nested resolution are dispatched concurrently (bounded). DynamoDB is HTTP-based, so there is no connection to serialize on. |
-| No Scan | Full table scans are forbidden. The linter detects and blocks them. |
-| Partial select | Query results are partial types. Only selected fields appear in the result type. |
-| Structured keys | Keys are built from `k` segment templates; partial keys compile to `begins_with` at a segment boundary. |
-| Typed consistentRead | `consistentRead` is only available for PK queries. GSI queries are rejected at compile time. |
-| Server-side filter | `filter` is a declarative DynamoDB `FilterExpression` (AppSync `ModelFilterInput`-compatible), typed against the full entity and able to reference unprojected attributes. It does not reduce RCU, and `limit` is applied before it. |
-
-## Architectural Boundaries
-
-Relation traversal only follows access paths defined on Entities.
-Undefined relations, missing GSIs, lists without limits, and traversal that exceeds allowed depth are checked before execution.
-
-This makes cross-boundary queries and DynamoDB-unfriendly access patterns easier to see in code.
-The same architectural constraints apply regardless of whether code is written by humans or generated by AI.
-
-## Linter
-
-Static analysis detects problems in Entity definitions before runtime:
-
-- Scan usage
-- missing limits on `hasMany` / `list`
-- ambiguous GSI resolution
-- query/list boundary violations for unique GSIs
-
-## Beyond the Core
-
-The query / relation / write API above is the core layer. GraphDDB also ships:
-
-- **[CQRS contracts](./docs/cqrs-contract.md)** — public Query/Command contract models with an
-  N+1-safe cardinality matrix, cross-contract composition, and context-boundary enforcement.
-- **[Mutation → command derivation](./docs/mutation-command-derivation.md)** — an internal
-  write-plan composition DSL behind the public Command IF. Declare a model's write semantics
-  (`entityWrites`: referential integrity, uniqueness, edge effects, derived counters, outbox
-  events, idempotency) once; a `mutation` composes one or more write fragments that the compiler
-  merges into a single atomic `TransactWriteItems`. All write paths route through one shared
-  `commitTransaction` orchestration.
-- **[Opt-in class hydration](./docs/class-hydration.md)** — pass an `options.hydrate` factory to
-  load a read result onto a host-language domain object instead of the default Typed Plain Object.
-  Host-only and never serialized into the bridge SSoT. Phase 1 (`query` top-level) is implemented;
-  `list` / per-relation hydration are planned future phases.
-- **[Multi-language (Python bridge)](./docs/python-bridge.md)** — TypeScript is the single source
-  of truth; generate a Python client + runtime from the same definitions, kept in lockstep by a
-  TS↔Python conformance suite.
-- **[In-memory testing](./docs/testing.md)** — `graphddb/testing` runs model-mapping, query-plan,
-  relation-traversal, and CDC tests **in-process, without Docker**.
-- **[CDC emulator](./docs/cdc-emulator.md)** — DynamoDB-Streams-equivalent change events for
-  driving and testing incremental aggregation locally.
-
-## Documentation
-
-| Document | Description |
+| 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` オーケストレーションを経由する。
+- **[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 相当の変更イベント。
+
+## 📚 Documentation
+
+| ドキュメント | 内容 |
 |----------|-------------|
-| [Specification](./docs/spec.md) | Core API: entities, structured keys/GSIs, query/filter, relations, batch/transactions, design rules, runtime behavior. |
-| [CQRS contract layer](./docs/cqrs-contract.md) | Public Query/Command contracts, cardinality matrix, N+1 safety, cross-contract composition, context boundaries. |
-| [Mutation → command derivation](./docs/mutation-command-derivation.md) | The internal write-plan composition DSL behind the Command IF: model write-semantics (`entityWrites`), fragment composition, and atomic `TransactWriteItems` derivation. |
-| [Class hydration](./docs/class-hydration.md) | Opt-in `options.hydrate` factory that loads a read result onto a host-language object (Phase 1: `query` top-level; Phases 2–3 future). |
-| [Multi-language / Python bridge](./docs/python-bridge.md) | TS-as-SSoT code generation and the Python runtime; TS↔Python conformance. |
-| [In-memory test adapter](./docs/testing.md) | Docker-free, in-process testing via `graphddb/testing` and `MemoryInspector`. |
-| [CDC emulator](./docs/cdc-emulator.md) | Change-event emulator (dev/test) for incremental aggregation patterns. |
-| [Benchmark](./benchmark/RESULTS.md) | Library comparison vs. hand-written AWS SDK, ElectroDB, DynamoDB Toolbox, and OneTable. |
-
-## Examples
-
-| Example | Description |
+| [Specification](./docs/spec.md) | コア API: entity、structured keys/GSIs、query/filter、relation、batch/transaction、design rule、runtime の挙動。 |
+| [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/) | Manage users, groups, and permissions with Single Table Design. Includes adjacency lists, inverted indexes, relation traversal, and `explain`. |
-| [aggregate-tree-pattern](./examples/aggregate-tree-pattern/) | Incremental tree aggregation (`siteScoreAverage`) driven by the CDC emulator: dirty propagation, throttled sweep, and recompute. |
-
-## Features
-
-- Entity metadata / decorators
-- DDBModel base class / connection management
-- Type system (SelectableOf, QueryResult, QueryKeyOf)
-- CRUD (put, update, delete, conditional writes — `WriteCondition` shares the full declarative filter operator set plus the `cond` raw escape hatch)
-- Query / List (planner, executor, hydrator, cursor pagination)
-- Type-safe filtering: declarative server-side `filter` (FilterExpression / AppSync `ModelFilterInput`-compatible), plus `Model.col` column refs and the `cond` raw escape hatch
-- Structured segment keys (`k` tag): partial keys compile to `begins_with` at a segment boundary
-- Explainable execution plans
-- Relations (hasMany, belongsTo, hasOne, depth limits, traversal)
-- BatchGet optimization
-- Parallel relation execution (independent sub-queries, BatchGet chunks, and nested resolution are dispatched concurrently with bounded concurrency)
-- Linter (no-scan, require-limit, query-boundary, GSI ambiguity, expanded design rules)
-- ConsistentRead type constraints
+| [user-permissions](./examples/user-permissions/) | Single Table Design でユーザー・グループ・パーミッションを管理する。隣接リスト、転置インデックス、relation traversal、`explain` を含む。 |
+| [aggregate-tree-pattern](./examples/aggregate-tree-pattern/) | CDC emulator で駆動される差分的なツリー集計（`siteScoreAverage`）: dirty 伝播、throttle 付き sweep、再計算。 |
+
+## ✨ 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）
+- BatchGet 最適化
+- 並列 relation 実行（独立したサブクエリ、BatchGet チャンク、ネストした解決を上限付きの
+  並列度で同時にディスパッチ）
+- Linter（no-scan, require-limit, query-boundary, GSI ambiguity, 拡張された design rule）
+- ConsistentRead の型制約
 - Transaction DSL
-- Batch operations
-- CQRS Query/Command contract layer (public IF, N+1-safe composition, context boundaries) — see [docs](./docs/cqrs-contract.md)
-- Mutation → command derivation: internal write-plan composition DSL (`entityWrites` + `mutation`) behind the Command IF, multi-fragment atomic composition into one `TransactWriteItems` — see [docs](./docs/mutation-command-derivation.md)
-- Opt-in class hydration (`options.hydrate`): load a read result onto a host object; host-only, never serialized. Phase 1 (`query` top-level) implemented — see [docs](./docs/class-hydration.md)
-- Multi-language: TS-as-SSoT Python code generator + runtime, with TS↔Python conformance — see [docs](./docs/python-bridge.md)
-- In-memory test adapter (`graphddb/testing`): Docker-free unit testing — see [docs](./docs/testing.md)
-- CDC emulator: DynamoDB-Streams-equivalent change events for dev/test — see [docs](./docs/cdc-emulator.md)
-
-## License
+- 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) を参照
+
+## 📄 License
 
 MIT