graphddb 0.9.0 → 0.9.2

package/docs/diagrams/ssot-derivation.en.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 988.3999999999979 582.9" width="988.3999999999979" height="582.9" font-family="Helvetica Neue, Arial, Hiragino Sans, sans-serif">
+<defs>
+<marker id="marker-filledArrow-33415c" markerWidth="7" markerHeight="7" refX="7" refY="3.5" orient="auto-start-reverse"><path d="M 0,0 L 7,3.5 L 0,7 Z" fill="#33415c"/></marker>
+</defs>
+<rect x="0" y="0" width="988.3999999999979" height="582.9" fill="#ffffff"/>
+<g id="vstack_1"><g id="hstack_1"><g id="ssot"><rect x="18" y="231.35000000000002" width="180" height="68.1" rx="10" fill="#eef3fc" stroke="#2b4bab" stroke-width="1.5"/><g id="vstack_2"><g id="text_1"><text x="108" y="260.1" text-anchor="middle" fill="#1d3a8f" font-size="15" font-weight="bold"><tspan x="108" dy="0">TS Model</tspan></text></g><g id="text_2"><text x="108" y="282.425" text-anchor="middle" fill="#444444" font-size="11.5"><tspan x="108" dy="0">(SSoT — single source of truth)</tspan></text></g></g></g><g id="vstack_3"><g id="rt"><rect x="288" y="18" width="620" height="57.3" rx="10" fill="white" stroke="#5886cd" stroke-width="1.5"/><g id="vstack_4"><g id="text_3"><text x="302" y="42.175" text-anchor="start" fill="#1d3a8f" font-size="13.5" font-weight="bold"><tspan x="302" dy="0">Runtime (TS)</tspan></text></g><g id="text_4"><text x="302" y="61.449999999999996" text-anchor="start" fill="#555555" font-size="11"><tspan x="302" dy="0">live execution — query / list / mutate / subscribe / explain</tspan></text></g></g></g><g id="ir"><rect x="288" y="91.3" width="620" height="57.3" rx="10" fill="white" stroke="#5886cd" stroke-width="1.5"/><g id="vstack_5"><g id="text_5"><text x="302" y="115.475" text-anchor="start" fill="#1d3a8f" font-size="13.5" font-weight="bold"><tspan x="302" dy="0">Portable IR (bridge bundle)</tspan></text></g><g id="text_6"><text x="302" y="134.75" text-anchor="start" fill="#555555" font-size="11"><tspan x="302" dy="0">manifest.json + operations.json — components[] graph (shared behavior-contracts vocabulary)</tspan></text></g></g></g><g id="langs"><rect x="288" y="196.6" width="620" height="96.3" rx="10" fill="#f7f9fd" stroke="#5886cd" stroke-width="1.5"/><g id="vstack_6"><g id="box_1"><rect x="288" y="196.6" width="620" height="28.799999999999997" rx="9" fill="#1d3a8f" stroke="#e5e7eb" stroke-width="0"/><g id="text_7"><text x="598" y="215.2" text-anchor="middle" fill="white" font-size="12" font-weight="bold"><tspan x="598" dy="0">Generated clients + runtimes (4 languages)</tspan></text></g></g><g id="box_2"><rect x="288" y="225.39999999999998" width="620" height="67.5" fill="none" stroke="#e5e7eb" stroke-width="0"/><g id="hstack_2"><g id="py"><rect x="298" y="235.39999999999998" width="140" height="47.5" rx="8" fill="white" stroke="#3776ab" stroke-width="1.8"/><g id="vstack_7"><g id="text_8"><text x="368" y="256.04999999999995" text-anchor="middle" fill="#3776ab" font-size="13" font-weight="bold"><tspan x="368" dy="0">Python</tspan></text></g><g id="text_9"><text x="368" y="272.575" text-anchor="middle" fill="#666666" font-size="9.5"><tspan x="368" dy="0">graphddb-runtime (PyPI)</tspan></text></g></g></g><g id="rs"><rect x="448" y="235.39999999999998" width="140" height="47.5" rx="8" fill="white" stroke="#b7410e" stroke-width="1.8"/><g id="vstack_8"><g id="text_10"><text x="518" y="256.04999999999995" text-anchor="middle" fill="#b7410e" font-size="13" font-weight="bold"><tspan x="518" dy="0">Rust</tspan></text></g><g id="text_11"><text x="518" y="272.575" text-anchor="middle" fill="#666666" font-size="9.5"><tspan x="518" dy="0">graphddb_runtime (crates.io)</tspan></text></g></g></g><g id="go"><rect x="598" y="235.39999999999998" width="140" height="47.5" rx="8" fill="white" stroke="#007d9c" stroke-width="1.8"/><g id="vstack_9"><g id="text_12"><text x="668" y="256.04999999999995" text-anchor="middle" fill="#007d9c" font-size="13" font-weight="bold"><tspan x="668" dy="0">Go</tspan></text></g><g id="text_13"><text x="668" y="272.575" text-anchor="middle" fill="#666666" font-size="9.5"><tspan x="668" dy="0">go module (go/vX.Y.Z tag)</tspan></text></g></g></g><g id="php"><rect x="748" y="235.39999999999998" width="140" height="47.5" rx="8" fill="white" stroke="#777bb4" stroke-width="1.8"/><g id="vstack_10"><g id="text_14"><text x="818" y="256.04999999999995" text-anchor="middle" fill="#777bb4" font-size="13" font-weight="bold"><tspan x="818" dy="0">PHP</tspan></text></g><g id="text_15"><text x="818" y="272.575" text-anchor="middle" fill="#666666" font-size="9.5"><tspan x="818" dy="0">graphddb/runtime (in-repo)</tspan></text></g></g></g></g></g></g></g><g id="cq"><rect x="288" y="308.9" width="620" height="57.3" rx="10" fill="white" stroke="#5886cd" stroke-width="1.5"/><g id="vstack_11"><g id="text_16"><text x="302" y="333.075" text-anchor="start" fill="#1d3a8f" font-size="13.5" font-weight="bold"><tspan x="302" dy="0">CQRS Contract</tspan></text></g><g id="text_17"><text x="302" y="352.34999999999997" text-anchor="start" fill="#555555" font-size="11"><tspan x="302" dy="0">public Query / Command contracts (N+1-safe, context boundaries)</tspan></text></g></g></g><g id="cfn"><rect x="288" y="382.2" width="620" height="57.3" rx="10" fill="white" stroke="#5886cd" stroke-width="1.5"/><g id="vstack_12"><g id="text_18"><text x="302" y="406.375" text-anchor="start" fill="#1d3a8f" font-size="13.5" font-weight="bold"><tspan x="302" dy="0">CloudFormation template</tspan></text></g><g id="text_19"><text x="302" y="425.65" text-anchor="start" fill="#555555" font-size="11"><tspan x="302" dy="0">generate cloudformation — GSI union / Streams / TTL / PITR / Auto Scaling</tspan></text></g></g></g><g id="doc"><rect x="288" y="455.5" width="620" height="57.3" rx="10" fill="white" stroke="#5886cd" stroke-width="1.5"/><g id="vstack_13"><g id="text_20"><text x="302" y="479.675" text-anchor="start" fill="#1d3a8f" font-size="13.5" font-weight="bold"><tspan x="302" dy="0">Model docs (Markdown + Mermaid)</tspan></text></g><g id="text_21"><text x="302" y="498.95" text-anchor="start" fill="#555555" font-size="11"><tspan x="302" dy="0">generate docs — model specification with user-overridable Handlebars templates</tspan></text></g></g></g></g></g><g id="conf"><rect x="18" y="532.8" width="890" height="32.099999999999994" rx="8" fill="#fbfcfe" stroke="#2f855a" stroke-width="1.2" stroke-dasharray="6 4"/><g id="vstack_14"><g id="text_22"><text x="32" y="552.875" text-anchor="start" fill="#22543d" font-size="11.5"><tspan x="32" dy="0">5-language conformance: TS / Python / Rust / Go / PHP run the same cases against DynamoDB Local, and CI pins the results byte-identical.</tspan></text></g></g></g></g>
+<g id="connector_1"><path d="M 198 235.43600000000004 C 267.01668456528756 235.43600000000004, 218.98331543471244 46.65, 288 46.65" fill="none" stroke="#33415c" stroke-width="2" marker-end="url(#marker-filledArrow-33415c)"/></g>
+<g id="connector_2"><path d="M 198 250.41800000000003 C 250.30463462938636 250.41800000000003, 235.69536537061364 119.94999999999999, 288 119.94999999999999" fill="none" stroke="#33415c" stroke-width="2" marker-end="url(#marker-filledArrow-33415c)"/></g>
+<g id="connector_3"><path d="M 198 273.572 C 234.43950864525482 273.572, 251.56049135474518 337.54999999999995, 288 337.54999999999995" fill="none" stroke="#33415c" stroke-width="2" marker-end="url(#marker-filledArrow-33415c)"/></g>
+<g id="connector_4"><path d="M 198 285.83000000000004 C 248.83499821540272 285.83000000000004, 237.16500178459728 410.84999999999997, 288 410.84999999999997" fill="none" stroke="#33415c" stroke-width="2" marker-end="url(#marker-filledArrow-33415c)"/></g>
+<g id="connector_5"><path d="M 198 296.045 C 266.8138952001883 296.045, 219.1861047998117 484.15, 288 484.15" fill="none" stroke="#33415c" stroke-width="2" marker-end="url(#marker-filledArrow-33415c)"/></g>
+<g id="connector_6"><path d="M 598 148.6 C 598 164.44, 598 180.76, 598 196.6" fill="none" stroke="#33415c" stroke-width="2" marker-end="url(#marker-filledArrow-33415c)"/></g>
+</svg>

package/docs/diagrams/ssot-derivation.ja.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 926 582.9" width="926" height="582.9" font-family="Helvetica Neue, Arial, Hiragino Sans, sans-serif">
+<defs>
+<marker id="marker-filledArrow-33415c" markerWidth="7" markerHeight="7" refX="7" refY="3.5" orient="auto-start-reverse"><path d="M 0,0 L 7,3.5 L 0,7 Z" fill="#33415c"/></marker>
+</defs>
+<rect x="0" y="0" width="926" height="582.9" fill="#ffffff"/>
+<g id="vstack_1"><g id="hstack_1"><g id="ssot"><rect x="18" y="231.35000000000002" width="180" height="68.1" rx="10" fill="#eef3fc" stroke="#2b4bab" stroke-width="1.5"/><g id="vstack_2"><g id="text_1"><text x="108" y="260.1" text-anchor="middle" fill="#1d3a8f" font-size="15" font-weight="bold"><tspan x="108" dy="0">TS Model</tspan></text></g><g id="text_2"><text x="108" y="282.425" text-anchor="middle" fill="#444444" font-size="11.5"><tspan x="108" dy="0">（SSoT — 単一の真実の源）</tspan></text></g></g></g><g id="vstack_3"><g id="rt"><rect x="288" y="18" width="620" height="57.3" rx="10" fill="white" stroke="#5886cd" stroke-width="1.5"/><g id="vstack_4"><g id="text_3"><text x="302" y="42.175" text-anchor="start" fill="#1d3a8f" font-size="13.5" font-weight="bold"><tspan x="302" dy="0">Runtime（TS）</tspan></text></g><g id="text_4"><text x="302" y="61.449999999999996" text-anchor="start" fill="#555555" font-size="11"><tspan x="302" dy="0">ライブ実行 — query / list / mutate / subscribe / explain</tspan></text></g></g></g><g id="ir"><rect x="288" y="91.3" width="620" height="57.3" rx="10" fill="white" stroke="#5886cd" stroke-width="1.5"/><g id="vstack_5"><g id="text_5"><text x="302" y="115.475" text-anchor="start" fill="#1d3a8f" font-size="13.5" font-weight="bold"><tspan x="302" dy="0">Portable IR（bridge bundle）</tspan></text></g><g id="text_6"><text x="302" y="134.75" text-anchor="start" fill="#555555" font-size="11"><tspan x="302" dy="0">manifest.json + operations.json — components[] グラフ（behavior-contracts 共通語彙）</tspan></text></g></g></g><g id="langs"><rect x="288" y="196.6" width="620" height="96.3" rx="10" fill="#f7f9fd" stroke="#5886cd" stroke-width="1.5"/><g id="vstack_6"><g id="box_1"><rect x="288" y="196.6" width="620" height="28.799999999999997" rx="9" fill="#1d3a8f" stroke="#e5e7eb" stroke-width="0"/><g id="text_7"><text x="598" y="215.2" text-anchor="middle" fill="white" font-size="12" font-weight="bold"><tspan x="598" dy="0">生成クライアント + runtime（4言語）</tspan></text></g></g><g id="box_2"><rect x="288" y="225.39999999999998" width="620" height="67.5" fill="none" stroke="#e5e7eb" stroke-width="0"/><g id="hstack_2"><g id="py"><rect x="298" y="235.39999999999998" width="140" height="47.5" rx="8" fill="white" stroke="#3776ab" stroke-width="1.8"/><g id="vstack_7"><g id="text_8"><text x="368" y="256.04999999999995" text-anchor="middle" fill="#3776ab" font-size="13" font-weight="bold"><tspan x="368" dy="0">Python</tspan></text></g><g id="text_9"><text x="368" y="272.575" text-anchor="middle" fill="#666666" font-size="9.5"><tspan x="368" dy="0">graphddb-runtime（PyPI）</tspan></text></g></g></g><g id="rs"><rect x="448" y="235.39999999999998" width="140" height="47.5" rx="8" fill="white" stroke="#b7410e" stroke-width="1.8"/><g id="vstack_8"><g id="text_10"><text x="518" y="256.04999999999995" text-anchor="middle" fill="#b7410e" font-size="13" font-weight="bold"><tspan x="518" dy="0">Rust</tspan></text></g><g id="text_11"><text x="518" y="272.575" text-anchor="middle" fill="#666666" font-size="9.5"><tspan x="518" dy="0">graphddb_runtime（crates.io）</tspan></text></g></g></g><g id="go"><rect x="598" y="235.39999999999998" width="140" height="47.5" rx="8" fill="white" stroke="#007d9c" stroke-width="1.8"/><g id="vstack_9"><g id="text_12"><text x="667.9999999999999" y="256.04999999999995" text-anchor="middle" fill="#007d9c" font-size="13" font-weight="bold"><tspan x="667.9999999999999" dy="0">Go</tspan></text></g><g id="text_13"><text x="668" y="272.575" text-anchor="middle" fill="#666666" font-size="9.5"><tspan x="668" dy="0">go module（go/vX.Y.Z tag）</tspan></text></g></g></g><g id="php"><rect x="748" y="235.39999999999998" width="140" height="47.5" rx="8" fill="white" stroke="#777bb4" stroke-width="1.8"/><g id="vstack_10"><g id="text_14"><text x="818.0000000000001" y="256.04999999999995" text-anchor="middle" fill="#777bb4" font-size="13" font-weight="bold"><tspan x="818.0000000000001" dy="0">PHP</tspan></text></g><g id="text_15"><text x="818" y="272.575" text-anchor="middle" fill="#666666" font-size="9.5"><tspan x="818" dy="0">graphddb/runtime（repo同梱）</tspan></text></g></g></g></g></g></g></g><g id="cq"><rect x="288" y="308.9" width="620" height="57.3" rx="10" fill="white" stroke="#5886cd" stroke-width="1.5"/><g id="vstack_11"><g id="text_16"><text x="302" y="333.075" text-anchor="start" fill="#1d3a8f" font-size="13.5" font-weight="bold"><tspan x="302" dy="0">CQRS Contract</tspan></text></g><g id="text_17"><text x="302" y="352.34999999999997" text-anchor="start" fill="#555555" font-size="11"><tspan x="302" dy="0">public な Query / Command contract（N+1 安全・context 境界）</tspan></text></g></g></g><g id="cfn"><rect x="288" y="382.2" width="620" height="57.3" rx="10" fill="white" stroke="#5886cd" stroke-width="1.5"/><g id="vstack_12"><g id="text_18"><text x="302" y="406.375" text-anchor="start" fill="#1d3a8f" font-size="13.5" font-weight="bold"><tspan x="302" dy="0">CloudFormation template</tspan></text></g><g id="text_19"><text x="302" y="425.65" text-anchor="start" fill="#555555" font-size="11"><tspan x="302" dy="0">generate cloudformation — GSI union / Streams / TTL / PITR / Auto Scaling</tspan></text></g></g></g><g id="doc"><rect x="288" y="455.5" width="620" height="57.3" rx="10" fill="white" stroke="#5886cd" stroke-width="1.5"/><g id="vstack_13"><g id="text_20"><text x="302" y="479.675" text-anchor="start" fill="#1d3a8f" font-size="13.5" font-weight="bold"><tspan x="302" dy="0">Model docs（Markdown + Mermaid）</tspan></text></g><g id="text_21"><text x="302" y="498.95" text-anchor="start" fill="#555555" font-size="11"><tspan x="302" dy="0">generate docs — Handlebars テンプレートで差し替え可能なモデル仕様書</tspan></text></g></g></g></g></g><g id="conf"><rect x="18" y="532.8" width="890" height="32.099999999999994" rx="8" fill="#fbfcfe" stroke="#2f855a" stroke-width="1.2" stroke-dasharray="6 4"/><g id="vstack_14"><g id="text_22"><text x="32" y="552.875" text-anchor="start" fill="#22543d" font-size="11.5"><tspan x="32" dy="0">5言語 conformance: TS / Python / Rust / Go / PHP が同一ケースを DynamoDB Local 実経路で実行し、結果の byte-identical を CI で固定する。</tspan></text></g></g></g></g>
+<g id="connector_1"><path d="M 198 235.43600000000004 C 267.01668456528756 235.43600000000004, 218.98331543471244 46.65, 288 46.65" fill="none" stroke="#33415c" stroke-width="2" marker-end="url(#marker-filledArrow-33415c)"/></g>
+<g id="connector_2"><path d="M 198 250.41800000000003 C 250.30463462938636 250.41800000000003, 235.69536537061364 119.94999999999999, 288 119.94999999999999" fill="none" stroke="#33415c" stroke-width="2" marker-end="url(#marker-filledArrow-33415c)"/></g>
+<g id="connector_3"><path d="M 198 273.572 C 234.43950864525482 273.572, 251.56049135474518 337.54999999999995, 288 337.54999999999995" fill="none" stroke="#33415c" stroke-width="2" marker-end="url(#marker-filledArrow-33415c)"/></g>
+<g id="connector_4"><path d="M 198 285.83000000000004 C 248.83499821540272 285.83000000000004, 237.16500178459728 410.84999999999997, 288 410.84999999999997" fill="none" stroke="#33415c" stroke-width="2" marker-end="url(#marker-filledArrow-33415c)"/></g>
+<g id="connector_5"><path d="M 198 296.045 C 266.8138952001883 296.045, 219.1861047998117 484.15, 288 484.15" fill="none" stroke="#33415c" stroke-width="2" marker-end="url(#marker-filledArrow-33415c)"/></g>
+<g id="connector_6"><path d="M 598 148.6 C 598 164.44, 598 180.76, 598 196.6" fill="none" stroke="#33415c" stroke-width="2" marker-end="url(#marker-filledArrow-33415c)"/></g>
+</svg>

package/docs/python-bridge.md

@@ -1,19 +1,36 @@
-# GraphDDB Python Bridge — Multi-Language Code Generation and Runtime
+# GraphDDB Multi-Language Bridge — Code Generation and Runtimes
 
-This document is the normative specification of GraphDDB's TypeScript-to-Python
+This document is the normative specification of GraphDDB's multi-language
 bridge as implemented. TypeScript is the Single Source of Truth (SSoT): queries
 and commands are defined and validated in TypeScript, a static parameterized
-planner emits language-neutral JSON specifications, and `graphddb generate
-python` produces typed Python repositories that a thin runtime executes against
-DynamoDB via boto3. Python never re-implements the GraphDDB DSL; it executes the
-access patterns that TypeScript has already defined and validated.
+planner emits language-neutral JSON specifications (the portable IR), and
+`graphddb generate <python|php|rust|go>` produces typed repositories that a
+thin per-language runtime executes against DynamoDB. No target language
+re-implements the GraphDDB DSL; each executes the access patterns that
+TypeScript has already defined and validated.
+
+Four target languages ship today, all consuming the same bridge bundle:
+
+| Language | Runtime package | Distribution | DynamoDB SDK | Notes |
+|----------|----------------|--------------|--------------|-------|
+| Python | `graphddb-runtime` | PyPI | boto3 | The worked example of §5–§7. |
+| Rust | `graphddb_runtime` | crates.io | aws-sdk-dynamodb | Generated codegen-static modules need **Rust >= 1.80** (`std::sync::LazyLock`). |
+| Go | `github.com/foo-log-inc/graphddb/go` | go module (`go/vX.Y.Z` tags) | aws-sdk-go-v2 | behavior-contracts is a private module dependency. |
+| PHP | `graphddb/runtime` | bundled in-repo (not on composer) | aws/aws-sdk-php | Vendors the behavior-contracts PHP port (`php/src/BehaviorContracts/`). |
+
+All four mirror the same architecture: interpret `manifest.json` /
+`operations.json`, share the behavior-contracts primitives (spec-version
+validation, canonical serialization, expression evaluation), and are pinned
+together with the TS live executor by the 5-language conformance suite (§8).
+Python is used as the worked example throughout §5–§7; the other runtimes
+follow the same contract.
 
 ## 1. Scope and Principles
 
 - **TypeScript is the SSoT.** Entity, key, GSI, and relation models, together
   with the set of permitted queries and commands, are defined only in
-  TypeScript. Python does not define entities, build ad-hoc queries, design
-  access patterns, or resolve relations dynamically.
+  TypeScript. A target language does not define entities, build ad-hoc queries,
+  design access patterns, or resolve relations dynamically.
 - **Declarative subset only.** Only declarative, serializable definitions cross
   the bridge: parameterized keys and items, the strict select projection,
   declarative server-side filters, relation traversal, and the supported write
@@ -21,12 +38,13 @@ access patterns that TypeScript has already defined and validated.
   API is fully declarative, and any application-side post-processing is the
   caller's responsibility (`result.items.filter(...)` on the typed result),
   never bridged.
-- **Security boundary.** A Python caller can invoke only the queries and
+- **Security boundary.** A non-TS caller can invoke only the queries and
   commands defined in TypeScript. Undefined relation traversals, Scans,
   unbounded lists, and unintended access patterns cannot be expressed.
 - **No drift by construction.** A single bridge bundle (`manifest.json` +
-  `operations.json`) is the contract shared by every runtime, and TypeScript and
-  Python execution semantics are pinned together by a golden conformance suite.
+  `operations.json`) is the contract shared by every runtime, and the execution
+  semantics of all five languages (TS / Python / Rust / Go / PHP) are pinned
+  together by a golden conformance suite.
 
 ## 2. Architecture
 
@@ -36,16 +54,16 @@ TypeScript (design-time / build-time SSoT)
   ├─ Parameterized query / command contracts (param + graphddb.publish*)
   ├─ Static parameterized planner (symbolic key evaluation)
   ├─ Bridge guard (reject non-declarative / non-serializable specs)
-  └─ Bridge bundle: manifest.json + operations.json
-        │  graphddb generate python
+  └─ Bridge bundle: manifest.json + operations.json   (portable IR — components[])
+        │  graphddb generate <python|php|rust|go>
         ▼
-Python (generated bindings + runtime)
-  ├─ types.py          (TypedDict / @dataclass result types)
-  ├─ repositories.py   (per-entity repository classes)
-  ├─ __init__.py       (re-exports)
-  └─ graphddb_runtime  (hand-written thin executor)
+Generated typed bindings + hand-written thin runtime, per language
+  ├─ Python  graphddb-runtime                    → boto3
+  ├─ Rust    graphddb_runtime                    → aws-sdk-dynamodb
+  ├─ Go      github.com/foo-log-inc/graphddb/go  → aws-sdk-go-v2
+  └─ PHP     graphddb/runtime                    → aws/aws-sdk-php
         ▼
-boto3 DynamoDB client
+DynamoDB
 ```
 
 | Layer | Responsibility |
@@ -53,9 +71,23 @@ boto3 DynamoDB client
 | TypeScript model | Entity / key / GSI / relation definitions |
 | Contract DSL (`param`, `graphddb.publish*`) | The permitted, parameterized queries and commands |
 | Static planner (`src/spec/*`) | Symbolic key evaluation → `manifest.json` / `operations.json` |
-| Generator (`src/codegen/python.ts`, `src/cli/*`) | Python repositories, result types, package exports |
-| Python repository | Stable application-facing interface |
-| Python runtime (`graphddb_runtime`) | Interprets the JSON specs and executes via boto3 |
+| Generator (`src/codegen/*`, `src/cli/*`) | Typed repositories, result types, package exports per language |
+| Generated repository | Stable application-facing interface |
+| Language runtime | Interprets the JSON specs and executes via the language's DynamoDB SDK |
+
+Execution itself has three permanent surfaces (issue #257): the **dynamic JSON
+path** (default — load `components[]` at runtime and interpret it with the
+shared `run_behavior`), the **codegen-static path** (opt-in — `graphddb
+generate behaviors --lang <ts|python|go|rust|php>` bakes the same IR into
+native modules through the shared upstream behavior-contracts generator, with
+fingerprint-checked stale rejection), and the **typed bindings** described in
+this document (`generate <python|php|rust|go>` — a consumer-UX surface that
+delegates execution to the other two).
+
+The remainder of this document uses **Python** as the worked example: §5–§7
+describe the `generate python` CLI, the generated bindings, and
+`graphddb-runtime` in full. The PHP / Rust / Go generators and runtimes mirror
+the same bundle, validation rules, spec-version guard, and error taxonomy.
 
 ## 3. TypeScript Definition DSL
 
@@ -377,7 +409,9 @@ generated/graphddb/
   __init__.py          # package re-exports
 ```
 
-`generate python` is the only `generate` subcommand.
+`generate php` / `generate rust` / `generate go` are the sibling typed-bindings
+subcommands (same bundle, same flags shape); `generate behaviors` /
+`generate cloudformation` / `generate docs` serve the other surfaces.
 
 ## 5.1 Generated Python
 
@@ -625,12 +659,16 @@ them inside the handler. The deployment artifact needs the runtime package, the
 generated bindings, and the two JSON specs (boto3/botocore are provided by the
 Lambda runtime).
 
-## 8. TS ↔ Python Conformance
+## 8. Cross-Language Conformance (5 languages)
 
-The TypeScript live executor and the Python runtime are two independent
-implementations of the same semantics; a golden conformance suite
-(`conformance/`) proves they agree. Against a shared DynamoDB Local table seeded
-with deterministic fixed-date data:
+The TypeScript live executor and the Python / PHP / Rust / Go runtimes are five
+independent implementations of the same semantics; a golden conformance suite
+(`conformance/`) proves they agree. The orchestrator runs the TS path once and
+compares each language runner (`py_runner.py` / `php_runner.php` /
+`rust_runner` / `go_runner`) against it with the identical deep-compare — the
+runners mirror one another byte-for-byte in job/result shape. The TS ↔ Python
+pair below stands for all four pairings. Against a shared DynamoDB Local table
+seeded with deterministic fixed-date data:
 
 - The **TypeScript path** substitutes concrete parameters into each definition's
   IR and dispatches to the live executor (`executeQuery` / `executeList` /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphddb",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Graph data modeling on DynamoDB with adjacency list pattern",
   "type": "module",
   "main": "dist/index.js",