graphddb 0.4.2 → 0.5.0

package/docs/middleware.md

@@ -0,0 +1,189 @@
+# GraphDDB Middleware / Hooks
+
+GraphDDB lets you register **host-side middleware** that runs at fixed points
+around reads and writes. Use it for cross-cutting concerns — logging, metrics,
+tracing, tenant / authorization scoping, soft-delete, result post-processing —
+without embedding any of it in your query or model definitions.
+
+## Principles
+
+- **Host-only, never serialized.** Middleware lives on the host runtime
+  (`ClientManager`) and never touches the planner, the spec generator, or
+  `operations.json`. The declarative "what to read/write" stays serializable and
+  portable across the TypeScript and Python runtimes; "what to do around it" is
+  host-specific.
+- **Unrestricted, your responsibility.** A hook may observe, mutate the
+  in-flight input / operation / result, cancel (by throwing), or recover from an
+  error (by returning a value). The library validates nothing and imposes no
+  semantics. If a hook breaks an invariant (e.g. removes a derived
+  `ConditionCheck` in a write persist hook), that is the host's responsibility.
+  Observation is the common use, not a restriction.
+- **Separate from CDC / capture.** The internal change-data-capture mechanism is
+  a different surface. Middleware is not a substitute for CDC, nor vice versa;
+  they coexist.
+
+## Registration
+
+```ts
+import { DDBModel } from 'graphddb';
+
+DDBModel.use(middleware);        // register (call as many times as you like)
+DDBModel.clearMiddleware();      // remove all (e.g. in test teardown)
+```
+
+Each registered object may set any subset of read and/or write hooks. Order
+matters: `before` hooks run in registration order (FIFO); `after` / `onError`
+hooks run in reverse (LIFO), so the first-registered middleware is the outermost
+wrapper — onion nesting without a `next()` callback. Every hook may be
+synchronous or return a `Promise`; the runtime always awaits.
+
+### Per-call context
+
+Pass `{ context }` on any read or write to make request-scoped values (tenant,
+actor, trace id) available to hooks as `ctx.context`. It is threaded unchanged to
+every relation fan-out operation. A call with no `context` sees `{}`.
+
+```ts
+await User.query(key, select, { context: { tenantId, actor } });
+await User.put(item, { context: { actor } });
+await DDBModel.batchGet(requests, { context: { tenantId } });
+```
+
+`context` is an ordinary host-language value and is **never** serialized.
+
+## The interface
+
+```ts
+interface Middleware {
+  name?: string;
+  read?: {
+    before?(ctx: ReadRequestCtx): void | Promise<void>;                 // R1
+    afterFetch?<T>(ctx: ReadRequestCtx, result: T): T | Promise<T>;      // R4
+    op?: {
+      before?(ctx: ReadOpCtx): void | Promise<void>;                    // R2
+      afterFetch?(ctx: ReadOpCtx, items: Item[]): Item[] | Promise<Item[]>; // R3
+      onError?(ctx: ReadOpCtx, err: unknown): void | Item[] | Promise<void | Item[]>; // R5
+    };
+    onError?(ctx: ReadRequestCtx, err: unknown): unknown;               // R5
+  };
+  write?: {
+    before?(ctx: WriteCtx): void | Promise<void>;                       // W1
+    after?(ctx: WriteCtx, change: Change): void | Promise<void>;        // W2
+    persist?: {
+      before?(ctx: PersistCtx): void | Promise<void>;                   // W3
+      after?(ctx: PersistCtx, results: unknown): void | Promise<void>;  // W4
+      onError?(ctx: PersistCtx, err: unknown): unknown;                 // W5
+    };
+    onError?(ctx: WriteCtx, err: unknown): unknown;                     // W5
+  };
+}
+```
+
+All context objects share `{ model, context, state }` (`state` is per-operation
+scratch; for cross-operation accumulation under concurrent fan-out, keep the
+accumulator on a host object referenced via `context`).
+
+## Read hooks
+
+A read flows: request entry → one or more physical operations (the root read
+**plus every relation fan-out fetch**) → hydration + relation merge → result.
+
+| ID | Hook | Fires | Receives / may do |
+|----|------|-------|-------------------|
+| **R1** | `read.before(ctx)` | once, at request entry (before key-resolution / planning) | mutate `ctx.params` (`key` / `select` / `options`, or `requests` for `batchGet`); `throw` to cancel |
+| **R2** | `read.op.before(ctx)` | per physical op, before send — incl. every relation fan-out fetch | mutate `ctx.operation` (the `DynamoDBOperation`, e.g. inject a `FilterExpression`); `throw` to cancel; inspect `ctx.relationPath` |
+| **R3** | `read.op.afterFetch(ctx, items)` | per physical op, with its raw items | return the (possibly filtered / replaced) `Item[]` |
+| **R4** | `read.afterFetch(ctx, result)` | once, on the final hydrated, relation-merged result | return the (possibly transformed) result |
+| **R5** | `read.op.onError` / `read.onError` | on an op-level / request-level error | observe, rethrow, or **recover** by returning a value |
+
+Context types: `ReadRequestCtx` (R1/R4/R5) carries `kind: 'query' | 'list' |
+'batchGet'` and the mutable `params`. `ReadOpCtx` (R2/R3/R5) carries `kind:
+'GetItem' | 'Query' | 'BatchGetItem'`, the mutable `operation`, and
+`relationPath` (`[]` for the root read, `['orders']` for a direct relation,
+`['orders', 'product']` for a nested one).
+
+### `DDBModel.batchGet`
+
+The multi-key read primitive fires the same hooks: R1/R4/R5 with kind
+`'batchGet'` (the mutable batch input is `ctx.params.requests`), and R2/R3/R5 per
+underlying `BatchGetItem` op (one per ≤100-key chunk). Note DynamoDB
+`BatchGetItem` has no server-side `FilterExpression`, so an R2 hook scopes a batch
+read by narrowing the key set or setting a `ProjectionExpression`.
+
+## Write hooks
+
+A write flows: logical write → effect derivation (edges, counter `ADD`s, GSI key
+re-derivation, referential `ConditionCheck`s) → the composed physical batch →
+commit. Hooks attach at two granularities — the **logical** op (before
+derivation) and the **physical** persist (the real composed batch).
+
+| ID | Hook | Fires | Receives / may do |
+|----|------|-------|-------------------|
+| **W1** | `write.before(ctx)` | per logical write, before derivation | mutate `ctx.input` and `ctx.kind` (incl. `delete` → `update` soft-delete-by-rewrite — derivation then runs on the rewritten op); `throw` to cancel (in a transaction, aborts **all** ops) |
+| **W2** | `write.after(ctx, change)` | per logical write, after commit | observe `change.{ oldImage, newImage }` (single-op writes carry a real old image; transactions return none) |
+| **W3** | `write.persist.before(ctx)` | once per physical persist (the whole atomic batch in a transaction), after derivation | mutate `ctx.items` (the composed `Put` / `Update` / `Delete` / `ConditionCheck` set — user write(s) **plus** every derived effect); `throw` to abort the batch — mutations are honored on the actual send |
+| **W4** | `write.persist.after(ctx, results)` | once per physical persist, after the executor returns | observe `results` |
+| **W5** | `write.persist.onError` / `write.onError` | on a persist-level / logical-level error | observe, rethrow, or **recover** by returning a value |
+
+Context types: `WriteCtx` (W1/W2/W5) carries the mutable `kind` and `input`, plus
+an optional `transaction.id` shared across the ops of one atomic batch.
+`PersistCtx` (W3/W4/W5) carries the mutable `items` and the `origins` of the
+batch.
+
+Atomicity: in `DDBModel.transaction` / `mutate({ mode: 'transaction' })`, persist
+hooks fire **once** for the whole atomic batch and any `before` `throw` aborts the
+entire transaction; in `parallel` mode each op is independent.
+
+## Cancellation & recovery
+
+- **Cancel** — `throw` from any `before` hook aborts that read/write (a transaction
+  `before` throw aborts the whole batch).
+- **Recover** — return a value from an `onError` hook to suppress the error and
+  substitute a result (the first hook in LIFO order that returns a non-`undefined`
+  value wins; if none does, the original error rethrows). Read `read.onError`
+  returns the read's result; `read.op.onError` returns the op's `Item[]`; write
+  `onError` / `persist.onError` return the resolved value.
+
+## Examples
+
+```ts
+// Tenant scope on every read, including relation fan-out (R2)
+DDBModel.use({ read: { op: { before(ctx) {
+  addFilter(ctx.operation, 'tenantId', ctx.context.tenantId);
+} } } });
+
+// Inject audit fields on every write (W1) — flows through derivation
+DDBModel.use({ write: { before(ctx) {
+  if (ctx.kind !== 'delete') ctx.input.item = { ...ctx.input.item, updatedBy: ctx.context.actor };
+} } });
+
+// Soft delete by rewrite (W1) — stored as an update
+DDBModel.use({ write: { before(ctx) {
+  if (ctx.kind === 'delete') { ctx.kind = 'update'; ctx.input.changes = { deletedAt: Date.now() }; }
+} } });
+
+// Redact non-admin reads (R4) and audit the real atomic batch (W3)
+DDBModel.use({ read:  { afterFetch: (ctx, r) => ctx.context.actor?.isAdmin ? r : redact(r) } });
+DDBModel.use({ write: { persist: { before(ctx) { auditLog(ctx.items, ctx.context); } } } });
+
+// Latency metric using per-request scratch (R1 → R4) and metrics on error (R5)
+DDBModel.use({ read: {
+  before(ctx)            { ctx.state.t0 = performance.now(); },
+  afterFetch(ctx, r)     { metric(`read.${ctx.kind}`, performance.now() - (ctx.state.t0 as number)); return r; },
+  onError(ctx)           { count(`read.${ctx.kind}.error`); /* return nothing → rethrow */ },
+} });
+```
+
+## Python parity
+
+The Python runtime exposes the same hook points (R1–R5, W1–W5), interface shape,
+ordering, atomicity, `context` injection, and `onError` recovery, registered
+through the Python runtime's equivalent of `DDBModel.use`. Because hooks are
+host-only and never serialized, the two runtimes implement them independently
+with no shared serialized surface; TS↔Python conformance is unaffected.
+
+## See also
+
+- [`cqrs-contract.md`](./cqrs-contract.md) — the public Query / Command contracts.
+- [`python-bridge.md`](./python-bridge.md) — the TypeScript→Python runtime parity.
+- [`cdc-emulator.md`](./cdc-emulator.md) — the (separate) change-data-capture mechanism.

package/docs/mutation-command-derivation.md

@@ -0,0 +1,356 @@
+# Deriving Command Execution Plans from Mutations + Model Semantics
+
+This document is the normative specification of GraphDDB's command-derivation
+layer **as implemented**. The query side compiles a GraphQL-like selection +
+model metadata into a complete read execution plan; the write side mirrors it:
+a **mutation** (an internal write-plan composition DSL) + **model write
+semantics** compiles into a **command execution plan**, so the author does not
+hand-write the write procedure.
+
+## Premise
+
+The query side already does this: a GraphQL-like selection + model metadata
+compiles to a complete **read execution plan** (point/range, relations,
+composition, parallel `executionPlan`). The write side now does the same — it
+compiles a **mutation** + model semantics into a **command execution plan** —
+instead of the author hand-writing the write procedure.
+
+This holds only to the extent the model carries write semantics. A mutation
+alone is just the *input shape*; it cannot decide what happens in storage. The
+decision lives in the model:
+
+```
+GraphQL mutation   = external input shape (syntax)
+graphddb model     = update target / relations / constraints / effects / access (semantics)
+mutation + model   → command execution plan
+```
+
+Where the model is silent, the plan cannot be derived and must fall back to an
+explicit, declarative action — never arbitrary procedure.
+
+---
+
+## Background — the read/write symmetry
+
+### The read side is fully derived (the template)
+
+`select` tree + model metadata → read plan: `point`/`range` resolution,
+relation traversal (`hasMany`→Query, `belongsTo`/`hasOne`→BatchGet), composition
+(External Query), and the `executionPlan` parallel groups — all derived by the
+planner and honored by both runtimes. This is the template the command side
+mirrors.
+
+### The model layer carries READ semantics plus an additive WRITE vocabulary
+
+Present in the read/core model layer (`src/decorators/`, `src/metadata/types.ts`):
+
+- Entity: `@model` (table), `@key` (segmented PK/SK), `@gsi` (`unique` flag).
+- Fields: `@string` / `@number` / `@boolean` / `@datetime` / `@binary` / sets /
+  `@list` / `@map` / `@embedded`, and `@literal(...)` (finite value set). Field
+  options: `format`, `readonly`, `serialize`/`deserialize`.
+- Relations: `@hasMany` / `@belongsTo` / `@hasOne` with `keyBinding`, limit/order
+  — these are read-traversal declarations.
+
+On top of that, the write-semantics vocabulary is declared additively (it does
+**not** change the read-side declarations):
+
+- **`Model.writes` / `entityWrites`** (`src/define/entity-writes.ts`) — the
+  entity's reusable *save contract*: lifecycle effects, referential integrity,
+  uniqueness, derived updates, edge effects, outbox events, idempotency.
+- **`edgeWrites` / `deriveEdgeWriteItems`** (`src/relation/`) — the write side
+  of an adjacency edge: from a declared edge, derive the lifecycle-distinguished
+  adjacency `Put`/`Delete` transaction items.
+- **`mutation` / `definePlan`** (`src/define/mutation.ts`) — the internal
+  write-plan composition DSL.
+
+### Command derivation, not hand-authored ops
+
+Earlier, the contract command layer (`publicCommandModel`, issue #64) had the
+author *write* the operation: a method body resolved to a single `put` /
+`update` / `delete` (`CommandSpec`) or a hand-built `defineTransaction`
+(`TransactWriteItems`). The command compiler now derives the plan from declared
+write semantics: an **intent → derive ops** step exists, turning the procedural
+DSL into a *derivable contract*.
+
+---
+
+## Mapping onto DynamoDB transaction primitives
+
+The derivation maps cleanly onto the DynamoDB transaction primitives the runtime
+already emits. Each write semantic has a known DynamoDB realization that fits the
+existing `CommandSpec` / `TransactionSpec` / `executionPlan` SSoT:
+
+| Derived effect | DynamoDB realization | Reuses |
+| --- | --- | --- |
+| put the entity item | `PutItem` (`attribute_not_exists(PK)` for create) | `CommandSpec` (#64) |
+| create adjacency edge(s) | extra `Put` item(s) in one `TransactWriteItems` | `TransactionSpec` (#64) |
+| `requires X exists` | `ConditionCheck` item (`attribute_exists`) in the tx | tx + extended condition subset |
+| uniqueness (`unique field per parent`) | a `UNIQUE#…` guard `Put` w/ `attribute_not_exists` | tx + uniqueness declaration |
+| counter / derived update | `UpdateItem` `ADD`/`SET` in the tx | tx + derived-update declaration |
+| domain event | outbox `Put` item in the tx, drained to Streams/`cdc` | tx + event declaration + `src/cdc/` |
+| idempotency | client-token guard item (`attribute_not_exists`) | tx + idempotency declaration |
+
+A multi-effect create (item + edge + counter + uniqueness + event) is one
+**atomic `TransactWriteItems`** — exactly what `defineTransaction` serializes,
+with the new pieces being *declarations* the compiler turns into items. The
+≤25-item limit and the "no per-item condition in `BatchWriteItem`" rules (#64)
+apply unchanged.
+
+Two capabilities the derivation depends on, both now implemented:
+
+1. **Extended condition subset.** Writes support the full declarative operator
+   subset of a read filter (`gt`/`ge`/`lt`/`le`/`ne`/`between`/`in`/`beginsWith`/
+   `contains`/`notContains`/`size`/`attributeType` + `and`/`or`/`not`), the
+   existence primitives (`attribute_exists` / `attribute_not_exists` / `notExists`),
+   equality, and the raw `cond` escape hatch (#114) — plus a **`ConditionCheck`
+   transaction item type** (a read-only assertion on another item). This is what
+   referential integrity needs.
+2. **Edge write side.** `@hasMany`/`belongsTo` describe how to *read* an
+   adjacency; `edgeWrites` / `deriveEdgeWriteItems` derive the inverse — the
+   adjacency `Put`/`Delete` items — from a declared edge.
+
+---
+
+## Specification
+
+### 1. Positioning — mutation is an INTERNAL write-plan composition DSL
+
+**The mutation is NOT a public API.** GraphQL is not exposed externally. A
+`mutation` is an **internal DSL for declaring a set of updates that must execute
+atomically** — a *write-plan composition language* used as the *implementation*
+of a Command. The only externally-exposed surface is the fixed **Command IF**
+(`publicCommandModel`, #64): params in, result out.
+
+```
+Public Command IF  (external, fixed)   = what other services depend on. ← the only public surface
+   ↑ implemented by
+Mutation (internal DSL)                = declares an atomic write plan by COMPOSING write fragments
+   ├─ fragment: create(Post)      ┐
+   └─ fragment: create(AuditLog)  ┘ → compiler MERGES into ONE TransactWriteItems
+Model semantics (entityWrites)         = the semantics of each write fragment
+Compiler                                = mutation AST + model → one CommandPlan / TransactionSpec
+Runtime                                 = atomic execution (TransactWriteItems)
+```
+
+Key consequences:
+
+- A mutation's **top-level fields are write *fragments*, not executed function
+  calls.** `mutation CreatePost { createPost(...) createAuditLog(...) }` does NOT
+  run `createPost` then `createAuditLog` sequentially — both fragments are
+  expanded and **composed at compile time into one atomic plan**.
+- Atomicity is achieved by **declaring multiple fragments in one mutation**, NOT
+  by a handler doing `await A(); await B()`. Sequential awaits in a handler are
+  the anti-pattern this replaces.
+- Each fragment's substance is derived from **model semantics** (§2). The
+  compiler composes fragments and validates them together (§3).
+- The CQRS split: **Query → Read Plan**; **Mutation → Command Plan** — the
+  mutation is internal; the Command IF is the boundary.
+- `GraphQL contrast`: composing fragments in one mutation under the default
+  `mode: 'transaction'` is **atomic all-or-nothing**; `mode: 'parallel'` is
+  **non-atomic**, surfacing **per-field partial success** (`{ ok }` | `{ error }`
+  per alias); on the read side `query` routes are **parallel independent reads**
+  with no cross-route consistency.
+
+### 2. Model write-semantics = reusable *save contract* (`entityWrites`)
+
+`Model.writes` declares the **write-side invariants/effects required for this
+entity to be consistent on DynamoDB** — a *reusable save contract*, NOT a
+mutation and NOT business logic. It stays **declarative** (no arbitrary
+procedure). Every leaf binds to an explicit path root (`$.input.*` = mutation
+input, `$.entity.*` = the written entity), so the source of each value is
+unambiguous.
+
+```ts
+static readonly writes = entityWrites<PostModel>((w) => ({
+  create: w.lifecycle({
+    requires: [ w.exists(() => UserModel, { userId: '$.input.userId' }) ],   // → ConditionCheck (#84)
+    unique:   [ w.unique({ name: 'postTitlePerUser',
+                           scope: ['$.input.userId'], fields: ['$.input.title'] }) ], // → guard (#86)
+    edges:    [ w.putEdge(() => UserModel, 'posts') ],                       // → adjacency Put (#82/#85)
+    derive:   [ w.increment(() => UserModel, { userId: '$.input.userId' }, 'postCount', 1) ], // (#85)
+    emits:    [ w.event('PostCreated', { postId: '$.entity.postId', userId: '$.input.userId' }) ], // (#87)
+    idempotency: w.idempotentBy('$.input.requestId'),                        // → guard (#87)
+  }),
+  remove: w.lifecycle({
+    edges:  [ w.deleteEdge(() => UserModel, 'posts') ],
+    derive: [ w.increment(() => UserModel, { userId: '$.entity.userId' }, 'postCount', -1) ],
+  }),
+}));
+```
+
+Design properties:
+
+- **`writes` is the entity's reusable *default* save-semantics, not the mutation.**
+  The mutation explicitly *adopts* it (`use:`), separating "reusable save rule"
+  from "public operation IF" (§3).
+- **`unique` is explicit `{ name, scope, fields }`** — the guard-item key shape
+  matters on DynamoDB; a bare `per:` is too weak for composite scope /
+  normalization / case-insensitive uniqueness.
+- **Edge effects are lifecycle-distinguished** — `putEdge` (onCreate),
+  `deleteEdge` (onDelete), and **`onUpdateKeyChange`** (when a foreign key like
+  `post.userId` changes: delete the old edge + create the new one), because
+  delete/update need the **old** value.
+
+### Responsibility boundary (what may live in `Model.writes`)
+
+`Model.writes` holds ONLY the persistence/relational/integrity contract:
+
+> referential integrity · uniqueness · edge create/delete · derived counter
+> updates · basic create/delete lifecycle · outbox event · idempotency guard
+
+It does **NOT** hold business flow, approval/state transitions, external API
+calls, notifications, payment, complex authorization, UI concerns, or use-case
+branching. Those are not "how this entity stays consistent on DynamoDB."
+
+**The mutation internal is persistence/records ONLY.** Business logic lives
+**outside** the mutation — in the application/service that calls the Command IF,
+or in a cross-cutting middleware layer (a separate concern; see #50). There is
+no business-logic "hook" inside the model or the mutation: needing one is a
+smell that logic leaked into the wrong layer. The split:
+
+```
+Caller / app layer  = business logic, authorization, external I/O, orchestration
+   ↓ calls
+Command IF (public) = fixed external surface; implemented by a mutation
+Mutation (internal) = composes write fragments into one atomic plan — RECORDS ONLY
+Model.writes        = common save semantics (DynamoDB consistency contract)
+Command Compiler    = fragment composition + cross-fragment validation → TransactWriteItems
+Middleware (#50)    = cross-cutting insertion points, designed separately/later
+```
+
+Note: a *declarative* guard on the current persisted value — e.g. "only writable
+while `status == 'draft'`" — is a **condition on the write** (the `{ field: value }`
+/ `attribute_exists` condition subset, #81/#84), which is records-level and stays
+inside. Genuine business logic (multi-step flows, external effects) does not.
+
+### 3. The command compiler (compose fragments → one atomic CommandPlan)
+
+A **mutation is internal**: it COMPOSES one or more **write fragments** in a
+descriptor alias-map — each alias an **intent** (`create` / `update` / `remove`)
++ target `Model` + `key` + `input` (with optional `condition` / `result` /
+`use`). The intent selects the lifecycle from the target's `writes`; `use:` is
+**optional** (defaults to the target model's own `writes`) and is given only to
+override with a custom write contract — and it takes the whole `writes` set,
+never `writes.create` (that would double-specify the intent). A cross-fragment
+data dependency is a `$.alias.field` reference. The compiler merges ALL
+fragments into ONE atomic plan. The **public surface is the Command IF**
+(`publicCommandModel`, #64), whose method is *implemented by* the mutation.
+
+```ts
+// ── internal write-plan composition (NOT public) ──
+const CreatePost = mutation($ => ({
+  // The INTENT (`create`) already selects the lifecycle. `use:` is OPTIONAL and
+  // defaults to the target's own `writes`; the compiler picks writes.create for
+  // create / writes.update for update / writes.remove for remove.
+  post: { create: PostModel, key: { postId: param.string() },        // fragment 1 → PostModel.writes.create
+          input: { userId: param.string(), title: param.string(), body: param.string() } },
+  audit: { create: AuditLogModel, key: { id: param.string() },        // fragment 2 — composed atomically
+           input: { action: 'post.created', actorId: $.post.userId, postId: $.post.postId } },
+}));
+
+// Override only when a non-default save contract is wanted:
+//   post: { create: PostModel, use: CustomPostWrites, key: {...}, input: { … } }
+// `use:` takes the WHOLE writes set (not writes.create) — the intent picks the
+// lifecycle, so writing `use: PostModel.writes.create` would double-specify it.
+
+// ── public Command IF (external, fixed — the only public surface) ──
+export const PostCommands = publicCommandModel({
+  create: mutation($ => ({
+    post: { create: PostModel, key: { postId: param.string() },
+            input: { requestId: param.string().optional(), userId: param.string(),
+                     title: param.string(), body: param.string() },
+            result: { select: { postId: true, title: true } } },          // return = read projection
+  })),
+});
+```
+
+Compilation (`compileFragment` for a single fragment;
+`compileMutationPlan` for the N-fragment atomic merge, #90):
+
+```
+Mutation = { alias₁: fragment₁, alias₂: fragment₂, … }   (each: intent + target Model + key + use: saveContract + input)
+  → for each fragment, derive its items from the adopted save contract:
+      [ ConditionCheck(requires), Put(entity, attribute_not_exists), Put(unique guards),
+        Put(edge) / Delete(old edge)+Put(new edge) on key change,
+        Update(derived), Put(outbox event), Put(idempotency guard) ]
+  → CROSS-FRAGMENT composition + validation:
+      • merge all fragments' items into ONE TransactWriteItems
+      • reject same-item conflicts (two writes to the same key in one tx — DynamoDB rejects)
+      • resolve cross-fragment data deps (e.g. fragment₂ reads fragment₁'s `$.alias.field`)
+      • enforce ≤25 items (hard error, never split — atomicity)
+      • dedupe/validate idempotency + outbox items
+  → emit one CommandSpec (single, single-fragment, no-tx-needed) OR TransactionSpec (atomic)
+  → attach executionPlan (#70); resolve return selection as a read projection
+```
+
+At runtime, every write path — single command, multi-fragment mutation, and the
+declarative `defineTransaction` — routes through the **single shared
+`commitTransaction` orchestration** (`src/runtime/transaction-commit.ts`, #97):
+op-aware collapse of same-physical-key collisions, the ≤25 enforcement, the
+atomic commit, and the CDC write-capture loop all live in that one place, so no
+caller carries its own collapse / limit / commit / capture logic.
+
+Naming: `mutation($ => ({...}))` = the INTERNAL composition DSL (not public);
+`publicCommandModel({ alias: mutation(...) })` = the public Command IF;
+`CommandPlan` = internal execution plan; `entityWrites` = model save-semantics.
+Fragment intents are the descriptor keys `create` / `update` / `remove`
+(`remove`, not `del`).
+
+This is the **same SSoT** as #64 (`CommandSpec`/`TransactionSpec`) and #70
+(`executionPlan`) — the compiler *populates* it from the adopted save contract
+instead of the author hand-writing it. N+1 safety, ≤25-item atomicity,
+condition-subset rules, and TS↔Python conformance all carry over unchanged.
+
+### 4. What is NOT derivable lives OUTSIDE the mutation (no in-model hook)
+
+Some logic is genuinely not derivable from declarative model semantics:
+
+- **Business state transitions** (multi-step flows beyond a declarative write
+  condition).
+- **External calls** (payment, email, notification).
+- **Compensating transactions** (partial-failure recovery across systems).
+- **Complex authorization** (org hierarchy, delegation, time-boxed grants).
+
+**This logic does NOT get a hook inside the model or the mutation.** Embedding a
+"policy/action hook" in the contract would blur the layer boundary the CQRS
+split exists to keep clean. The mutation internal is **persistence/records
+only**. Non-derivable business logic belongs **outside**:
+
+- in the **application/service** that calls the Command IF (it does authz,
+  orchestration, external I/O *around* the command), and/or
+- in a **cross-cutting middleware layer** — a separate concern, deferred and
+  tracked under **#50**, NOT part of this derivation layer.
+
+Needing a business-logic hook *inside* a mutation is a smell that logic leaked
+into the persistence layer. (A declarative guard on the current persisted value
+is a *write condition*, not business logic — it stays inside, per §2.)
+
+---
+
+## Design summary
+
+- **The external IF is GraphQL-like `query` | `mutation`**, forking internally
+  to read-plan vs command-plan compilers (CQRS). The mutation is the syntax; the
+  model is the semantics.
+- **The command is a derivable contract, not a procedure.** The model
+  write-semantics vocabulary (lifecycle / edge-effects / constraints / derived
+  updates / events / idempotency) lets the compiler derive the plan. (Authz and
+  other business logic are NOT model write-semantics — they live outside the
+  mutation; see §4.)
+- **The compile target is the SSoT** built for the contract layer
+  (`CommandSpec` / `TransactionSpec` / `executionPlan`) — no new execution
+  substrate.
+- **The two enabling primitives are in place**: the extended write condition
+  subset (`attribute_exists` + a `ConditionCheck` transaction item type), and
+  the edge write side (adjacency Put/Delete derived from a declared edge).
+- **Everything stays declarative + build-verified + conformance-locked**,
+  exactly as the query/command contract layer is.
+
+`mutation + model semantics → command plan` turns the command interface from a
+hand-written procedural DSL into a **derivable contract**, symmetric with the
+query side. The work is not in execution (the `TransactWriteItems` patterns and
+the SSoT already exist) — it is in the **model's declarative write-semantics
+vocabulary**, plus the two primitives (`ConditionCheck` / `attribute_exists`,
+and edge write-effects). The irreducible non-derivable logic (state machines,
+external I/O, compensation, complex authz) stays outside the mutation, never
+arbitrary procedure inside it.