graphddb 0.4.2 → 0.4.3

package/docs/python-bridge.md

@@ -0,0 +1,611 @@
+# GraphDDB Python Bridge — Multi-Language Code Generation and Runtime
+
+This document is the normative specification of GraphDDB's TypeScript-to-Python
+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.
+
+## 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.
+- **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
+  conditions. Arbitrary post-load TypeScript logic is out of scope — the select
+  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
+  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.
+
+## 2. Architecture
+
+```text
+TypeScript (design-time / build-time SSoT)
+  ├─ Entity / Key / GSI / Relation models
+  ├─ Parameterized query / command definitions (param + define*)
+  ├─ Static parameterized planner (symbolic key evaluation)
+  ├─ Bridge guard (reject non-declarative / non-serializable specs)
+  └─ Bridge bundle: manifest.json + operations.json
+        │  graphddb generate python
+        ▼
+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)
+        ▼
+boto3 DynamoDB client
+```
+
+| Layer | Responsibility |
+|---|---|
+| TypeScript model | Entity / key / GSI / relation definitions |
+| Definition DSL (`param`, `define*`) | 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 |
+
+## 3. TypeScript Definition DSL
+
+### 3.1 Parameters
+
+A parameter is a branded placeholder standing in for a value supplied at
+execution time. Placeholders are created with `param.string()`,
+`param.number()`, `param.literal(...)`, and `param.array({...})`. Each carries a
+TypeScript value type (preserved through the inferred definition types) and a
+runtime descriptor (`kind`, optional `literals`, optional element shape) that
+the planner and generator read. `param.literal('active', 'disabled')` has value
+type `'active' | 'disabled'`; the literal set is preserved in the spec.
+
+Parameters are legal only inside the structures passed to the `define*` entry
+points — never to the live `Model.query` / `Model.putItem` runtime API, whose types
+remain free of parameter placeholders.
+
+### 3.2 Definition Entry Points
+
+Definitions are built with dedicated entry points, each accepting `param`
+placeholders at scalar leaves while checking field names, value types, the key
+boundary, and the strict select against the model:
+
+- `defineQuery(Model, key, select)` — single-item read (unique key).
+- `defineList(Model, key, select)` — partition read (partial / partition key).
+- `definePut(Model, item, options?)` — put.
+- `defineUpdate(Model, key, changes, options?)` — update.
+- `defineDelete(Model, key, options?)` — delete.
+
+Write entry points accept an optional `{ condition }` (see §6.2). Each entry
+point collects its placeholders into a `name → ParamDescriptor` map; a parameter
+name used twice with conflicting types is rejected at definition time.
+
+> Design note: the entry points are dedicated functions (not `Model.query(...)`
+> overloads) so that the live runtime model API is never widened to accept
+> parameter placeholders.
+
+### 3.3 Grouping
+
+`defineQueries({ ... })` groups read definitions (`defineQuery` / `defineList`);
+`defineCommands({ ... })` groups write definitions (`definePut` / `defineUpdate`
+/ `defineDelete`). Each validates that every entry is the correct operation kind
+and returns the typed record that the planner consumes. `defineTransactions({
+... })` groups declarative transactions (see §6.3).
+
+```ts
+export const queries = defineQueries({
+  getUserByEmail: defineQuery(
+    User,
+    { email: param.string() },
+    { userId: true, name: true, email: true, status: true },
+  ),
+  listGroupMembers: defineList(
+    GroupMembership,
+    { groupId: param.string() },
+    { userId: true, role: true, joinedAt: true },
+  ),
+});
+
+export const commands = defineCommands({
+  addGroupMember: definePut(GroupMembership, {
+    groupId: param.string(),
+    userId: param.string(),
+    role: param.string(),
+  }),
+  disableUser: defineUpdate(
+    User,
+    { userId: param.string() },
+    { status: param.literal('disabled') },
+  ),
+  deleteGroupMember: defineDelete(GroupMembership, {
+    groupId: param.string(),
+    userId: param.string(),
+  }),
+});
+```
+
+## 4. The Bridge Bundle
+
+`buildBridgeBundle(queries?, commands?, registry?, transactions?, contracts?)`
+produces a deterministic, JSON-serializable `BridgeBundle` of two documents:
+
+```ts
+interface BridgeBundle {
+  readonly manifest: Manifest;        // manifest.json
+  readonly operations: OperationsDocument; // operations.json
+}
+```
+
+Building runs `buildManifest`, then `buildOperations`, then asserts the whole
+bundle is serializable (§6.1). All collections are emitted in name-sorted order
+so the output is stable across runs.
+
+### 4.1 `manifest.json` — Schema Metadata
+
+```jsonc
+{
+  "version": "1.0",
+  "tables": { "UserPermissions": { "physicalName": "UserPermissions" } },
+  "entities": {
+    "UserModel": {
+      "table": "UserPermissions",
+      "physicalName": "UserPermissions",
+      "prefix": "USER#",
+      "fields": {
+        "userId":    { "type": "string" },
+        "email":     { "type": "string" },
+        "status":    { "type": "string" },
+        "createdAt": { "type": "string", "format": "datetime" }
+      },
+      "key": {
+        "inputFields": ["userId"],
+        "pkTemplate": "USER#{userId}",
+        "skTemplate": "PROFILE"
+      },
+      "gsis": [
+        {
+          "indexName": "GSI1",
+          "unique": true,
+          "inputFields": ["email"],
+          "pkTemplate": "EMAIL#{email}",
+          "skTemplate": "PROFILE"
+        }
+      ],
+      "relations": {
+        "groups": {
+          "type": "hasMany",
+          "target": "GroupMembershipModel",
+          "keyBinding": { "userId": "userId" }
+        }
+      }
+    }
+  }
+}
+```
+
+- `fields[*].type` is one of `string | number | boolean | binary | stringSet |
+  numberSet | list | map`. A string field that holds a temporal value carries
+  `format: "datetime"` or `format: "date"`, used by the runtime to restore
+  Python `datetime` values during hydration.
+- `key` / `gsis[*]` carry `inputFields` and `pkTemplate` / `skTemplate` where the
+  templates use `{field}` placeholders (e.g. `USER#{userId}`, `EMAIL#{email}`).
+  `skTemplate` is `null` when the access pattern has no sort key.
+- `relations[*]` is one of `hasMany | hasOne | belongsTo` with a `target` entity
+  and a `keyBinding` (target field → source field).
+
+### 4.2 `operations.json` — Execution Specs
+
+```ts
+interface OperationsDocument {
+  readonly version: '1.0';
+  readonly queries: Record<string, QuerySpec>;
+  readonly commands: Record<string, CommandSpec>;
+  readonly transactions?: Record<string, TransactionSpec>;
+  readonly contracts?: Record<string, ContractSpec>;
+  readonly contexts?: Record<string, ContextSpec>;
+}
+```
+
+#### Parameter specs
+
+Every operation carries a `params` map of `ParamSpec`:
+
+```jsonc
+{ "type": "string", "required": true }
+{ "type": "number", "required": true }
+{ "type": "literal", "required": true, "literals": ["disabled"] }
+{ "type": "array", "required": true,
+  "element": { "userId": { "type": "string", "required": true } } }
+```
+
+#### Queries
+
+A `QuerySpec` has `params`, an ordered `operations` array, and a `cardinality`
+(`"one"` or `"many"`). Each `OperationSpec`:
+
+```jsonc
+{
+  "type": "Query",                // "Query" | "GetItem" | "BatchGetItem"
+  "tableName": "UserPermissions",
+  "indexName": "GSI1",            // omitted for base-table access
+  "keyCondition": { "GSI1PK": "EMAIL#{email}", "GSI1SK": "PROFILE" },
+  "rangeCondition": { "operator": "begins_with", "key": "SK", "value": "USER#" },
+  "projection": ["email", "name", "status", "userId"],
+  "limit": 20,
+  "filter": { /* declarative FilterExpression */ },
+  "resultPath": "$",              // "$" or e.g. "$.groups.items"
+  "sourceField": "userId"         // present on relation child operations
+}
+```
+
+The operation type is chosen by the planner from the key shape: a full PK+SK is
+a `GetItem`; a partial key with a contiguous sort-key prefix is a `Query` with a
+`begins_with` `rangeCondition`; a partition-key-only access is a `Query`. The
+`projection` is the set of scalar fields selected `true`.
+
+#### Template placeholders
+
+Key, item, and change templates use two placeholder forms plus literals:
+
+- `{paramName}` — bound from caller-supplied parameters.
+- `{result.sourceField}` — bound from a prior operation's result item(s), used to
+  chain relation operations.
+- Literal text (e.g. `PROFILE`, `USER#`) is emitted verbatim.
+
+The planner derives every template by **symbolic evaluation** of the model's key
+mapping (it evaluates the key function over symbolic field markers rather than
+concrete values), producing `USER#{userId}`-style templates directly from the
+metadata.
+
+#### Relation chaining and execution plan
+
+A relation traversal is expressed as additional `OperationSpec` nodes in the same
+query's `operations` array. Each child references its parent through
+`{result.sourceField}` in its `keyCondition`, and its `resultPath` nests the
+result under the parent (`$.groups.items` for a `hasMany`, `$.account` for a
+`belongsTo` / `hasOne`). `belongsTo` / `hasOne` children are emitted as
+`BatchGetItem`; `hasMany` children as `Query`.
+
+A query may carry an `executionPlan`:
+
+```jsonc
+{ "groups": [[1, 2], [3]], "concurrency": 16 }
+```
+
+`groups` is an ordered list of stages of operation indices (the root, index 0,
+is implicit and runs first). Operations within a stage are mutually independent
+and may run concurrently; later stages may read `{result.*}` produced by earlier
+ones. The same `deriveExecutionPlan` routine is used by the generator and by the
+TypeScript runtime, so the staging cannot drift between them.
+
+#### Commands
+
+```jsonc
+{
+  "type": "UpdateItem",           // "PutItem" | "UpdateItem" | "DeleteItem"
+  "tableName": "UserPermissions",
+  "entity": "UserModel",
+  "params": { "userId": {"type":"string","required":true},
+              "status": {"type":"literal","required":true,"literals":["disabled"]} },
+  "keyCondition": { "PK": "USER#{userId}", "SK": "PROFILE" },
+  "changes": { "status": "{status}" },
+  "condition": { "kind": "notExists" }   // or "equals" / "expr" / "raw" / attributeExists… (§6.2)
+}
+```
+
+A `put` carries an `item` template; an `update` carries `changes`; both `update`
+and `delete` carry a `keyCondition`. Writes target the base table — a
+GSI-keyed write is rejected by the planner.
+
+## 5. The `graphddb generate python` CLI
+
+```bash
+graphddb generate python \
+  --entry src/models/index.ts \
+  --queries src/models/queries.ts \
+  --commands src/models/commands.ts \
+  --out generated/graphddb
+```
+
+| Flag | Required | Default | Meaning |
+|---|---|---|---|
+| `--entry`, `-e` | yes | — | Module that registers entity models (imported for side effects); may also export the definition maps. |
+| `--out`, `-o` | yes | — | Output directory (created if absent). |
+| `--queries`, `-q` | no | `--entry` | Module exporting `queries`. |
+| `--commands`, `-c` | no | `--entry` | Module exporting `commands`. |
+| `--transactions`, `-t` | no | `--commands` then `--entry` | Module exporting `transactions`. |
+| `--contracts` | no | `--entry` | Module exporting CQRS `contracts`. |
+| `--contexts` | no | `--contracts` then `--entry` | Module exporting context ownership. |
+| `--dataclass` | no | `false` | Emit `@dataclass` result types instead of `TypedDict`. |
+
+TypeScript definition modules are transpiled on the fly (via tsx/esbuild — the
+same transform the build uses), so you do **not** need to wrap the CLI in `tsx`
+or enable Node type-stripping; run `graphddb generate` under plain `node`.
+
+`tsx` is an *optional* peer dependency: it is only needed to load `.ts`
+definition modules, so install it as a devDependency in projects that run
+codegen (`npm i -D tsx`). The library half of the package never needs it, so
+runtime consumers do not pull esbuild. Already-compiled `.js` / `.mjs` modules
+load without tsx.
+
+The entry module is imported first (registering the models), after which the
+definition maps are read from their named exports. The command builds the bridge
+bundle and writes exactly five files:
+
+```text
+generated/graphddb/
+  manifest.json        # schema metadata (2-space JSON, trailing newline)
+  operations.json      # execution specs
+  types.py             # result / element types
+  repositories.py      # repository classes
+  __init__.py          # package re-exports
+```
+
+`generate python` is the only `generate` subcommand.
+
+## 5.1 Generated Python
+
+Every generated file begins with `# DO NOT EDIT. Generated by GraphDDB.` and
+`from __future__ import annotations`. Application-specific logic wraps the
+generated repositories rather than editing them.
+
+### Result types (`types.py`)
+
+Result types are named `<PascalCaseQueryName>Result` (e.g. `GetUserByEmailResult`)
+with name-sorted fields. By default each is a `TypedDict`; with `--dataclass`
+each is an `@dataclass` (optional fields default to `None` and follow required
+fields). Manifest field types map to Python: `string`/`stringSet` → `str`,
+`number`/`numberSet` → `float`, `boolean` → `bool`, `binary` → `bytes`, `list`
+→ `list`, `map` → `dict`; literal params render as `Literal[...]`. A `hasMany`
+relation renders as a `<Item>Connection` (`items: list[...]`, `cursor: str |
+None`); a `belongsTo` / `hasOne` renders as `<Item> | None`. Transaction array
+parameters yield `<Transaction><Param>Item` element types.
+
+### Repositories (`repositories.py`)
+
+One `class <Entity>Repository:` per owning entity, constructed with a
+`GraphDDBRuntime`. Methods are named in `snake_case`; arguments are `snake_case`
+while the dict passed to the runtime keys parameters by their original
+definition names. Query methods return `<Result> | None`; command methods return
+`None`. If transactions exist, a `TransactionsRepository` exposes them via
+`execute_transaction`.
+
+```python
+class UserRepository:
+    def __init__(self, runtime: GraphDDBRuntime) -> None:
+        self._runtime = runtime
+
+    def get_user_by_email(self, email: str) -> GetUserByEmailResult | None:
+        return self._runtime.execute_query(
+            query_id="getUserByEmail",
+            params={"email": email},
+        )
+
+    def disable_user(self, status: Literal["disabled"], user_id: str) -> None:
+        self._runtime.execute_command(
+            command_id="disableUser",
+            params={"status": status, "userId": user_id},
+        )
+```
+
+`__init__.py` re-exports the result types and repository classes with a
+name-sorted `__all__`.
+
+## 6. Build-Time Guarantees
+
+### 6.1 Serializability
+
+The bridge guard asserts that every value in the bundle survives `JSON.stringify`
+round-tripping: only strings, finite numbers, booleans, `null`, arrays, and plain
+objects are allowed. Functions, symbols, `undefined`, `Date`, `Map`, `Set`,
+class instances, and non-finite numbers are rejected.
+
+### 6.2 Supported Write Conditions
+
+A write `condition` (`WriteCondition`, issue #114) serializes to one of these
+`ConditionSpec` kinds:
+
+- `{ notExists: true }` → `{ "kind": "notExists" }` (`attribute_not_exists` on the
+  partition key);
+- `{ attributeExists: '<field>' }` → `{ "kind": "attributeExists", "field" }`;
+  `{ attributeNotExists: '<field>' }` → `{ "kind": "attributeNotExists", "field" }`;
+- a field-equality map → `{ "kind": "equals", "fields": { ... } }` (legacy,
+  golden-stable shape);
+- the **declarative operator subset** (the same operators as a read filter —
+  `gt`/`ge`/`lt`/`le`/`ne`/`between`/`in`/`beginsWith`/`contains`/`notContains`/
+  `size`/`attributeType` + `and`/`or`/`not`) → `{ "kind": "expr", "declarative": … }`,
+  which both runtimes re-render through the shared filter compiler;
+- a raw `cond\`…\`` fragment → `{ "kind": "raw", "expression", "names", "values" }`,
+  pre-compiled to a finished `ConditionExpression` with stable `#cr_<field>` /
+  `:crN` aliases. A value may be a native literal or a `{ "$param": "<name>" }`
+  leaf bound from a caller param at execution time.
+
+A raw `cond` is serializable only as a **whole** condition; a `cond` nested inside
+a declarative `and` / `or` / `not` group is rejected at build time (no raw node in
+the serialized `expr` tree). (Per-item conditions are not available on
+`BatchWriteItem`; conditional batch writes must use a transaction.)
+
+### 6.3 Transactions (declarative subset)
+
+`defineTransaction` records a declarative transaction whose body may only call
+`tx.put` / `tx.update` / `tx.delete` with field references or literals at scalar
+leaves, iterate an array parameter with `tx.forEach(p.<arrayParam>, ...)`, and
+attach a declarative `when` comparison (`eq` / `ne`) and/or a supported
+`condition`. The planner emits a `TransactionSpec` whose `items` carry rendered
+templates (`{param}`, `{item.field}` for `forEach` elements), optional
+`condition`, optional `when`, and optional `forEach: { source }`. A transaction
+with no `forEach` is rejected at build time if it exceeds 25 items; with
+`forEach`, the 25-item limit is enforced by the runtime after expansion.
+
+## 7. The Python Runtime (`graphddb_runtime`)
+
+`graphddb_runtime` is the hand-written package the generated bindings import. It
+interprets `manifest.json` / `operations.json` and executes the validated access
+patterns through a boto3 DynamoDB client. The runtime core is synchronous (boto3
+is a synchronous SDK).
+
+### 7.1 Construction and API
+
+```python
+GraphDDBRuntime(
+    dynamodb_client,
+    manifest_path: str,
+    operations_path: str,
+    table_mapping: Mapping[str, str] | None = None,
+    limits: RuntimeLimits | None = None,
+)
+```
+
+`table_mapping` maps logical table names to deployed physical names. The
+specs are loaded and cached at construction.
+
+| Method | Behavior |
+|---|---|
+| `execute_query(query_id, params, options=None) -> dict \| None` | Run a single- or multi-operation query; returns the hydrated result, or `None` when the root matches nothing. `options` may carry a pagination `cursor`. |
+| `execute_command(command_id, params, options=None) -> None` | Run a single write (`PutItem` / `UpdateItem` / `DeleteItem`). |
+| `execute_transaction(transaction_id, params) -> None` | Expand and run a declarative transaction as `TransactWriteItems`. |
+| `explain(query_id, params) -> dict` | Resolve the operation list without executing — substitutes `{param}` and leaves `{result.*}` intact. |
+
+`AsyncGraphDDBRuntime(sync_runtime)` provides an `await`-able surface for the
+same methods by running each blocking call via `asyncio.to_thread`; behavior
+(params, specs, results, error types) is identical. The wrapped runtime is
+available as `.sync`. No `aioboto3` is required.
+
+### 7.2 Parameter Validation and Template Resolution
+
+Parameters are validated against each operation's `params` spec **before** any
+DynamoDB call: required parameters must be present, unknown ones are rejected,
+and scalar types and literal sets are checked. Template resolution substitutes
+`{name}` placeholders; `{result.sourceField}` placeholders are bound from a prior
+operation's results when chaining relations. An unbound placeholder raises
+`ParameterValidationError`.
+
+### 7.3 boto3 Conversion
+
+Python values are converted to DynamoDB AttributeValues with
+`boto3.dynamodb.types.TypeSerializer` and back with `TypeDeserializer`. Numbers
+deserialize to `Decimal`.
+
+### 7.4 Hydration
+
+For each returned item the runtime keeps only the fields selected `true` in the
+projection, strips internal key attributes (`PK`, `SK`, `GSI*PK`, `GSI*SK`), and
+restores temporal fields: a `format: "datetime"` string parses to a
+timezone-aware UTC `datetime`, and a `format: "date"` string parses to midnight
+UTC. A malformed temporal string raises `HydrationError`.
+
+### 7.5 Cursors
+
+A single-operation cursor is the DynamoDB `LastEvaluatedKey` serialized as
+compact JSON (with `Decimal` rendered as int/float and binary base64-encoded)
+and encoded as unpadded base64url. `decode_cursor` reverses this. The cursor's
+contents are opaque to the application. Batched range contract methods use a
+per-key cursor envelope (`{ key, inner }`) keyed by the owning contract key, so
+resuming with a cursor for the wrong key is rejected.
+
+### 7.6 Relations, Batch, and Concurrency
+
+Relation children are resolved against the parents produced by earlier
+operations and merged into the result at their `resultPath`:
+
+- **`belongsTo` / `hasOne`** — source values from all parents are deduplicated
+  and fetched in a single `BatchGetItem`, then matched back to each parent (a
+  miss yields `None`). This avoids the N+1 pattern.
+- **`hasMany`** — one `Query` per parent (with the `begins_with` range and any
+  declarative filter), producing an `{ items, cursor }` connection.
+
+`BatchGetItem` requests are chunked at 100 keys, deduplicated, and retried on
+`UnprocessedKeys` with capped exponential backoff (up to 10 attempts).
+`BatchWriteItem` is chunked at 25 with the same `UnprocessedItems` retry. Stages
+of mutually independent operations (from `executionPlan`) run concurrently on a
+bounded thread pool (default 16 in flight); boto3 releases the GIL during
+network I/O, so the overlap is real. Result order is preserved.
+
+### 7.7 Transactions
+
+`execute_transaction` expands a `TransactionSpec` into boto3 transact items:
+`forEach` items iterate their array source, `when` guards filter items, and
+templates resolve `{param}` and `{item.field}`. Conditions are any serialized
+`ConditionSpec` kind (§6.2) — existence primitives, AND-joined equality, the
+declarative operator subset (`expr`), or a whole `cond` raw fragment. The expanded
+set is limited to 25 items.
+
+### 7.8 Runtime Limits
+
+```python
+@dataclass(frozen=True)
+class RuntimeLimits:
+    max_operations: int = 20
+    max_items: int = 100
+    max_depth: int = 1
+    max_batch_get_items: int = 100
+```
+
+These bound the number of read operations per query, the result cardinality
+(items per Query, keys per BatchGet, relation fan-out), the relation nesting
+depth, and the BatchGet chunk size. A violation raises `LimitExceededError`
+before any DynamoDB call.
+
+### 7.9 Errors
+
+All runtime errors derive from `GraphDDBError`:
+
+`QueryNotFoundError`, `CommandNotFoundError`, `TransactionNotFoundError`,
+`ContractNotFoundError`, `ContractArityError`, `ParameterValidationError`,
+`LimitExceededError`, `OperationExecutionError` (wraps a boto3 `ClientError` /
+`BotoCoreError`, preserving the cause as `.original`), `HydrationError`, and
+`MultiOperationNotSupportedError`.
+
+### 7.10 AWS Lambda
+
+The runtime loads the JSON specs from disk and constructs a boto3 client — both
+cold-start costs. Construct the runtime and repositories in module scope so they
+are reused across warm invocations and captured by SnapStart; never construct
+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
+
+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 path** substitutes concrete parameters into each definition's
+  IR and dispatches to the live executor (`executeQuery` / `executeList` /
+  `executePut` / `executeUpdate` / `executeDelete`), relations included.
+- The **Python path** runs the **generated** `operations.json` / `manifest.json`
+  through `GraphDDBRuntime` against the same seeded table.
+- Both results are normalized to canonical JSON and deep-compared; the run exits
+  non-zero on any divergence.
+
+Normalization absorbs only representation differences — `Date` ↔ `datetime`
+rendered to the same ISO-8601 instant, an absent connection `cursor` defaulting
+to `null`, and the cardinality-one root shape — applied symmetrically to both
+sides. Real semantics are preserved and must match exactly: all field values,
+the set of projected fields, item ordering within connections (DynamoDB
+sort-key order), relation nesting, filter results, BatchGet dedup/order, and
+persisted command items. The TypeScript and Python sides write under private key
+suffixes (`-ts` / `-py`) so they share the table without colliding.
+
+Coverage spans single `GetItem`, unique-GSI `Query`, partition `Query`/list,
+relation queries (`belongsTo` BatchGet + nested `hasMany` + server filter +
+cursor), put / update / delete, conditional writes (existence primitives, equality, the declarative operator subset, and `cond` raw fragments),
+and declarative transactions (including `forEach` + `when`). A
+`CONFORMANCE_MUTATE` switch injects a deliberate divergence (corrupting a
+hydrated date, neutralizing the filter compiler, or corrupting a persisted item)
+to prove the suite detects drift rather than passing vacuously.
+
+> Note: the static build-time N+1 safety check on CQRS contracts is
+> TypeScript-only — there is no Python build step — so it is a TypeScript-side
+> boundary rather than a cross-runtime parity claim.