graphddb 0.7.10 → 0.8.1

package/docs/cqrs-contract.md

@@ -83,7 +83,9 @@ field list argument. The access pattern — primary key or GSI — is resolved f
 the `Model` plus the `key` fields named in the descriptor:
 
 ```ts
-const UserByEmail = publicQueryModel({
+import { graphddb, param } from 'graphddb';
+
+const UserByEmail = graphddb.publishQuery({
   get: { query: User, key: { email: param.string() }, select: { userId: true, email: true } },
 });
 ```
@@ -95,7 +97,7 @@ key, select, options? }`, with exactly one of `query` / `list`. `select` and
 `options` are separate keys (no `select` nested inside `options`).
 
 ```ts
-export const ArticleById = publicQueryModel({
+export const ArticleById = graphddb.publishQuery({
   get: { query: Article, key: { articleId: param.string() },
          select: { articleId: true, title: true, body: true },
          options: { consistentRead: false } },
@@ -193,7 +195,7 @@ write-use-case Methods. A command method is a single declarative write
 result?, mode? }`, with exactly one of `create` / `update` / `remove`.
 
 ```ts
-export const UserCommands = publicCommandModel({
+export const UserCommands = graphddb.publishCommand({
   disable: { update: User, key: { userId: param.string() },
              input: { status: 'disabled', disableReason: param.string() },
              result: { select: { userId: true, status: true } } },
@@ -214,7 +216,7 @@ export const UserCommands = publicCommandModel({
   **or** a raw `cond\`…\`` fragment whose value slots may be `param.*` bindings:
 
   ```ts
-  export const UserCommands = publicCommandModel({
+  export const UserCommands = graphddb.publishCommand({
     // declarative operators in a write condition
     promote: { update: User, key: { userId: param.string() },
                input: { role: 'admin' },
@@ -261,6 +263,52 @@ addMany: { create: GroupMembership, key: { groupId: param.string(), userId: para
 `GraphQL contrast`: `mode: 'transaction'` is atomic all-or-nothing; `mode:
 'parallel'` is non-atomic per-field partial success.
 
+### Composite (multi-entity atomic) methods — the `writes` body
+
+A single write descriptor covers one entity. A **composite** method writes
+**multiple entities atomically** — the canonical case being a cross-entity write
+that has **no relation to fall back on** (e.g. marking a hash-keyed aggregate node
+`dirty` alongside a chunk's terminal update). Author it with the **`writes` body**
+form:
+
+```ts
+export const ChunkCompleteCommands = graphddb.publishCommand({
+  complete: {
+    // the public input schema — names + types the params the body references
+    input: { chunkId: param.string(), nodeId: param.string() },
+    // the mutation body: `$ => ({ alias: descriptor, … })`; `$` refers to the inputs
+    writes: ($) => ({
+      chunk: { update: Chunk,   key: { chunkId: $.chunkId }, input: { done: true } },
+      agg:   { update: AggNode, key: { nodeId: $.nodeId },  input: { dirty: true } },
+    }),
+    // optional read-back projection (keyed on the primary — first — fragment)
+    result: { select: { chunkId: true, done: true } },
+  },
+});
+```
+
+- `writes` is a body `$ => ({ alias: writeDescriptor, … })`. Each alias value is a
+  write descriptor (`{ create | update | remove | upsert: Model, key, input?,
+  condition? }` — the same shape as a single-descriptor method, minus `result` /
+  `mode`, which are declared on the composite as a whole). The `$` proxy fields are
+  the input fields declared in the separate **`input`** schema; a later descriptor
+  may reference an earlier alias's written field via `$.alias.field`.
+- **Single-alias** `writes` ⇒ one write. **Multi-alias** ⇒ an **atomic composite**:
+  it is promoted to a single `TransactWriteItems` by DynamoDB necessity (there is no
+  non-atomic multi-item form for a cross-entity write), so no `mode` ceremony is
+  needed — a multi-alias composite is always atomic.
+- `input` (the public param schema), `result` (read-back), and `mode` are specified
+  **alongside** the body, never baked into it.
+- **No `mutation(...)` / `defineScpTransaction(...)` import is needed** —
+  `publishCommand` compiles the `writes` body internally. The emitted
+  `operations.json` wire is byte-identical to the equivalent internal composition.
+- The single-descriptor form above stays the sugar for a single-entity write; the
+  `writes` body is the additive form for the multi-entity atomic case.
+
+> The full **SCP native-syntax** composite body (imperative `$`/`?:`/`&&`/`.map`
+> transaction sources) is a separate surface, deferred to a later release; the
+> `writes` descriptor-map body above is the supported public composite form today.
+
 #### The 25-item limit is a hard error, never a silent split
 
 `TransactWriteItems` is capped at **25 items** and is atomic. A
@@ -276,7 +324,7 @@ read dependency, declared with the `query($ => ({...}))` builder; a cross-
 fragment reference uses `$.alias.field`:
 
 ```ts
-export const AccountAccess = publicQueryModel({
+export const AccountAccess = graphddb.publishQuery({
   get: query($ => ({
     account: { query: Account, key: { accountId: param.string() },
                select: { accountId: true } },
@@ -361,7 +409,8 @@ single-model lint framework.
 
 A method body is evaluated at definition time with throwing sentinels in place
 of `keys` / `params`, recorded through a model recorder, and subjected to the
-same hardening `defineTransaction` applies:
+same no-runtime-capture build-time hardening the prepared-statement compiler
+applies:
 
 1. **Throwing sentinel Proxy** — any property / method access other than the
    internal brand reads or primitive coercion throws at the access site.
@@ -489,31 +538,41 @@ input produces a byte-identical pre-contract document).
 
 ## Public API surface
 
-Definition DSL (`src/define/contract.ts`):
+Definition DSL (`src/define/contract.ts`) — import the `graphddb` namespace
+(`import { graphddb } from 'graphddb'`); `graphddb.publishQuery` /
+`graphddb.publishCommand` are the sole read/write authoring surface:
 
 ```ts
-publicQueryModel({ alias: { query | list: Model, key, select, options? } })
-publicCommandModel({ alias: { create | update | remove: Model, key, input, condition?, result?, mode? } })
-query($ => ({ alias: descriptor, ... }))           // composite read; cross-fragment refs $.alias.field
-mutation($ => ({ alias: descriptor, ... }))         // composite write; cross-fragment refs $.alias.field
+graphddb.publishQuery({ alias: { query | list: Model, key, select, options? } })
+// single-entity write
+graphddb.publishCommand({ alias: { create | update | remove: Model, key, input, condition?, result?, use?, mode? } })
+// multi-entity atomic (composite) write — the `writes` body form (#293)
+graphddb.publishCommand({ alias: { input, writes: $ => ({ alias: descriptor, … }), result?, mode? } })
 param.string() / param.number() / ...               // descriptor key/input parameters
 ```
 
-Runtime (`src/runtime/*`):
+A query method may compose another query contract's method (cross-fragment refs
+via `$.alias.field`); a command method composes its derived write ops and
+maintenance writes into one plan, and a **composite** command method's `writes`
+body composes a multi-entity atomic write (§ Composite methods). These are all
+declared inside the `publishQuery` / `publishCommand` map — there is no separate
+public `query()` / `mutation()` composite verb (removed in 0.8.0; the composite
+`writes` body is compiled internally, needing no import).
 
-```ts
-executeQueryMethod(contract, methodName, key | keys[], params?)    // contract-runtime
-executeCommandMethod(contract, methodName, key | keys[], params?)  // command-runtime
-encodePerKeyCursor / decodePerKeyCursor / serializeContractKey     // per-key-cursor
-```
+Execution is the two `graphddb.*` verbs (`graphddb.query` / `graphddb.mutate`) —
+they route contract methods through the in-process runtime.
+
+The contract runtime (`executeQueryMethod` / `executeCommandMethod` /
+per-key-cursor helpers, `src/runtime/*`) is **internal** machinery behind those
+verbs — not a public export.
 
-Build / static analysis (`src/spec/*`):
+Build / static analysis is the advanced `graphddb/spec` subpath:
 
 ```ts
+import { buildContracts, buildContexts } from 'graphddb/spec';
+
 buildContracts(contracts)                  // → { contracts, queries, commands, transactions }
 buildContexts(contexts)                    // → context-ownership specs
-assertContractN1Safe(name, spec, isGsiPoint?)
-assertContractBoundaries(...)              // context-boundary lint
 ```
 
 ## Query vs Command

package/docs/design-patterns.md

@@ -542,11 +542,11 @@ GSI). *Dual-edge form* — declare `w.dualEdge(forward, inverse)` on the forward
 keep a **two-row** bidirectional edge in sync without an inverse GSI. The dual edge can
 be recorded in either of two write vocabularies carrying the SAME `w.dualEdge`:
 
-- **`entityWrites` (recommended when driving through the command / mutation IF, #195)** —
+- **`entityWrites` (recommended when driving through the command IF, #195)** —
   place `w.dualEdge(...)` in a lifecycle's `edges` array. The dual edge is then derived by
-  `executeCommandMethod` / `DDBModel.mutate`, so a `mutation` over the edge maintains BOTH
-  rows in the SAME atomic transaction with no low-level handwork. Use this form if the edge
-  is created / removed through a command.
+  the command runtime behind `graphddb.publishCommand` / `graphddb.mutate`, so a write over
+  the edge maintains BOTH rows in the SAME atomic transaction with no low-level handwork. Use
+  this form if the edge is created / removed through a command.
 - **`edgeWrites` (the low-level edge-only primitive)** — the historical adjacency-only
   `writes` member. Same two-row synchronization, but driven through the low-level edge-write
   path rather than the command IF.
@@ -626,7 +626,7 @@ actual sink write happens inside the consumer's CDC infrastructure, outside grap
 That runtime was **removed in 0.4.0** (issue #152). External projection is now a
 **typed-consumer-IF contract** (issue #153): mark the source model with
 `@cdcProjected()`, then parse a CDC change event into typed instances — `Model.fromChange(event)`
-returns `[oldRecord, newRecord]`, and `DDBModel.subscribe(handlers)` (the GraphQL-style
+returns `[oldRecord, newRecord]`, and `graphddb.subscribe(handlers)` (the GraphQL-style
 sibling of `query` / `mutate`) returns a `ChangeHandler` the consumer mounts on its own
 stream. graphddb owns the *parse → typed record* contract; subscription, sink delivery,
 and idempotency stay with the consumer. See [`cdc-projection.md`](./cdc-projection.md)

package/docs/docs-generation.md

@@ -40,15 +40,15 @@ graphddb generate docs --entry models.ts --out doc.md
   `<dir>/index.md` (backward compatible). Either way the command prints a JSON
   result (`{"status":"ok","outDir":…,"files":[…]}`) to stdout, where `files`
   reports the written path(s).
-- **`--queries`** (optional) points at the module exporting your `queries` /
-  `commands` (the `defineQueries` / `defineCommands` maps). It powers the Access
-  Patterns and Mutation Contracts sections; omit it and those sections are empty.
-  Defaults to the entry module.
+- **`--contracts`** (optional) points at the module exporting your `contracts`
+  map (the `graphddb.publishQuery` / `graphddb.publishCommand` results). It powers
+  the Access Patterns and Mutation Contracts sections; omit it and those sections
+  are empty. Defaults to the entry module.
 
 To also document your access patterns and mutations:
 
 ```bash
-graphddb generate docs --entry models.ts --queries definitions.ts --out docs/
+graphddb generate docs --entry models.ts --contracts contracts.ts --out docs/
 ```
 
 ## Output sections
@@ -78,7 +78,7 @@ flag (PITR, table class, encryption) render as `as configured at deployment`.
 | --- | --- | --- |
 | `--entry <file>` | (required) | Entry module registering the entity models. |
 | `--out <path>` | (required) | Output path. A `*.md` file is written verbatim at that path; any other value is a directory and `index.md` is written inside it. |
-| `--queries <file>` | entry module | Module exporting `queries` / `commands` for Access Patterns / Mutation Contracts. |
+| `--contracts <file>` | entry module | Module exporting the `contracts` map for Access Patterns / Mutation Contracts. |
 | `--format <format>` | `markdown` | Output format (only `markdown` today). |
 | `--split <mode>` | `none` | `none` emits a single `index.md`. `entity` is reserved for a future per-entity split. |
 | `--template-dir <dir>` | — | Directory of override `<partial>.hbs` templates. |

package/docs/middleware.md

@@ -25,10 +25,10 @@ without embedding any of it in your query or model definitions.
 ## Registration
 
 ```ts
-import { DDBModel } from 'graphddb';
+import { graphddb } from 'graphddb';
 
-DDBModel.use(middleware);        // register (call as many times as you like)
-DDBModel.clearMiddleware();      // remove all (e.g. in test teardown)
+graphddb.config.use(middleware);        // register (call as many times as you like)
+graphddb.config.clearMiddleware();      // remove all (e.g. in test teardown)
 ```
 
 Each registered object may set any subset of read and/or write hooks. Order
@@ -45,8 +45,8 @@ 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 } });
+await User.putItem(item, { context: { actor } });
+await graphddb.query({ users: { query: User, key: keys, select: { name: true } } }, { context: { tenantId } });
 ```
 
 `context` is an ordinary host-language value and is **never** serialized.
@@ -102,9 +102,9 @@ Context types: `ReadRequestCtx` (R1/R4/R5) carries `kind: 'query' | 'list' |
 `relationPath` (`[]` for the root read, `['orders']` for a direct relation,
 `['orders', 'product']` for a nested one).
 
-### `DDBModel.batchGet`
+### Batch read (`graphddb.query({ key: K[] })`)
 
-The multi-key read primitive fires the same hooks: R1/R4/R5 with kind
+The multi-key read path 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
@@ -130,7 +130,7 @@ 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
+Atomicity: in `graphddb.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.
 
@@ -148,26 +148,26 @@ entire transaction; in `parallel` mode each op is independent.
 
 ```ts
 // Tenant scope on every read, including relation fan-out (R2)
-DDBModel.use({ read: { op: { before(ctx) {
+graphddb.config.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) {
+graphddb.config.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) {
+graphddb.config.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); } } } });
+graphddb.config.use({ read:  { afterFetch: (ctx, r) => ctx.context.actor?.isAdmin ? r : redact(r) } });
+graphddb.config.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: {
+graphddb.config.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 */ },
@@ -178,7 +178,7 @@ DDBModel.use({ read: {
 
 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
+through the Python runtime's equivalent of `graphddb.config.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.
 

package/docs/mutation-command-derivation.md

@@ -65,12 +65,12 @@ On top of that, the write-semantics vocabulary is declared additively (it does
 
 ### Command derivation, not hand-authored ops
 
-Earlier, the contract command layer (`publicCommandModel`, issue #64) had the
+Earlier, the contract command layer (`graphddb.publishCommand`, 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*.
+`update` / `delete` (`CommandSpec`) or a hand-built atomic `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*.
 
 ---
 
@@ -91,8 +91,9 @@ existing `CommandSpec` / `TransactionSpec` / `executionPlan` SSoT:
 | 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
+**atomic `TransactWriteItems`** — exactly what `graphddb.mutate({ mode:
+'transaction' })` 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.
 
@@ -119,7 +120,7 @@ Two capabilities the derivation depends on, both now implemented:
 `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.
+(`graphddb.publishCommand`, #64): params in, result out.
 
 ```
 Public Command IF  (external, fixed)   = what other services depend on. ← the only public surface
@@ -234,34 +235,41 @@ 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.
+(`graphddb.publishCommand`, #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 } },
-}));
+The public surface is `graphddb.publishCommand` — a map of method name → single
+declarative write **descriptor** (`{ create | update | remove: Model, key, input?,
+condition?, result?, use?, mode? }`). The INTENT (`create` / `update` / `remove`)
+selects the lifecycle from the target's `writes`; the compiler folds the derived
+effects (edges, counters, uniqueness guards, outbox, idempotency, and any
+composed maintenance/audit writes) into ONE atomic `TransactWriteItems`. The
+author writes only the descriptor:
 
-// 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.
+```ts
+import { graphddb, param } from 'graphddb';
 
 // ── 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
-  })),
+export const PostCommands = graphddb.publishCommand({
+  // Intent `create` selects PostModel.writes.create; the descriptor's derived
+  // effects + any composed maintenance/audit writes are merged into one atomic
+  // TransactWriteItems by the compiler.
+  create: {
+    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
+  },
 });
+
+// Override the default save contract only when a non-default one is wanted:
+//   create: { 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.
 ```
 
 Compilation (`compileFragment` for a single fragment;
@@ -283,18 +291,20 @@ Mutation = { alias₁: fragment₁, alias₂: fragment₂, … }   (each: intent
   → 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;
+At runtime, every write path — a single command, a multi-effect composed
+descriptor, and an atomic `graphddb.mutate({ mode: 'transaction' })` — 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: the internal composition DSL (`src/define/mutation.ts`) is **not public** —
+the public Command IF is `graphddb.publishCommand({ alias: descriptor })`, where
+each `descriptor` is `{ create | update | remove: Model, key, input?, … }`.
 `CommandPlan` = internal execution plan; `entityWrites` = model save-semantics.
-Fragment intents are the descriptor keys `create` / `update` / `remove`
-(`remove`, not `del`).
+Descriptor intents are the 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

package/docs/prepared-statements.md

@@ -1,9 +1,9 @@
 # GraphDDB Prepared Statements
 
-`DDBModel.prepare($ => ({...}))` → `.execute(params)` is the read/write-unified
+`graphddb.prepare($ => ({...}))` → `.execute(params)` is the read/write-unified
 **prepared statement**: a declarative route body is compiled **once**, and each
 `execute(params)` binds the per-call values into the precompiled plan and runs
-it through the **same execution cores** `DDBModel.mutate` / `Model.query` /
+it through the **same execution cores** `graphddb.mutate` / `Model.query` /
 `Model.list` and the public CQRS contracts use — effects are identical by
 construction (design #203, runtime #205, compile-time transform #206, static
 AOT plans #208).
@@ -12,21 +12,21 @@ AOT plans #208).
 
 | Use | API |
 |---|---|
-| ad-hoc one-shot | `DDBModel.mutate({...})` / `Model.query(...)` / `Model.list(...)` — recompiles per call |
-| repeated hot path (prepared statement) | `DDBModel.prepare($ => ({...}))` → `.execute(params)` |
-| public CQRS contract | `publicCommandModel({...})` / `publicQueryModel({...})` |
+| ad-hoc one-shot | `graphddb.mutate({...})` / `Model.query(...)` / `Model.list(...)` — recompiles per call |
+| repeated hot path (prepared statement) | `graphddb.prepare($ => ({...}))` → `.execute(params)` |
+| public CQRS contract | `graphddb.publishCommand({...})` / `graphddb.publishQuery({...})` |
 
 `prepare` is the missing middle: **precompiled without the contract ceremony**.
 
 ```ts
 // write
-const createPost = DDBModel.prepare(($) => ({
+const createPost = graphddb.prepare(($) => ({
   post: { create: () => Post, key: { threadId: $.threadId, postId: $.postId }, input: { body: $.body } },
 }));
 await createPost.execute({ threadId, postId, body });
 
 // read — symmetric; only the key values (+ limit/cursor/consistentRead) are dynamic
-const userById = DDBModel.prepare(($) => ({
+const userById = graphddb.prepare(($) => ({
   user: { query: () => User, key: { userId: $.userId }, select: { userId: true, name: true } },
 }));
 await userById.execute({ userId });
@@ -65,7 +65,7 @@ whole contract:
 | **AOT** (`graphddb transform prepared --aot <artifact> --write`, #208) | **zero compilation at runtime, including the first call** — the plan was compiled at BUILD time into a static artifact; the call site loads it and every call binds params into the frozen plan | identical |
 | **transform applied** (`graphddb transform prepared --write`) | zero per-op after the FIRST call (the lazy slot compiles once per module at first use) | identical |
 | **no transform** (fallback) | phase-1 **structural memoization**: the body is re-evaluated and structure-hashed per call, then the compiled handle is reused from a bounded LRU (no recompile) | identical |
-| hand-hoisted module-level `const stmt = DDBModel.prepare(...)` | compile once at first use (runtime); the transform leaves it untouched | identical |
+| hand-hoisted module-level `const stmt = graphddb.prepare(...)` | compile once at first use (runtime); the transform leaves it untouched | identical |
 
 The transform exists to remove the placement footgun: without it, an inline
 `prepare` is *correct but warmer* than a module-level one (silent-slow). With
@@ -108,7 +108,7 @@ evaluates it:
 
 ```ts
 // after `--aot src/graphddb.prepared.ts --write`
-import { loadPreparedPlan as __gddbLoadPreparedPlan } from 'graphddb';
+import { loadPreparedPlan as __gddbLoadPreparedPlan } from 'graphddb/internal';
 import __gddbPreparedPlans from './graphddb.prepared.js';
 let __gddbPrepared1;
 export async function getUser(userId: string) {
@@ -152,7 +152,7 @@ The rewrite normalizes each inline call site to a module-scope **lazy slot**:
 ```ts
 // before (inline, per-call structural memoization)
 export async function getUser(userId: string) {
-  return DDBModel.prepare(($) => ({
+  return graphddb.prepare(($) => ({
     u: { query: () => User, key: { userId: $.userId }, select: USER_SELECT },
   })).execute({ userId });
 }
@@ -160,7 +160,7 @@ export async function getUser(userId: string) {
 // after `graphddb transform prepared --write`
 let __gddbPrepared1;
 export async function getUser(userId: string) {
-  return (__gddbPrepared1 ??= DDBModel.prepare(($) => ({
+  return (__gddbPrepared1 ??= graphddb.prepare(($) => ({
     u: { query: () => User, key: { userId: $.userId }, select: USER_SELECT },
   }))).execute({ userId });
 }
@@ -172,7 +172,7 @@ file), the plan compiles once per module at first use, and every later call is
 a single nullish check straight into `.execute`. Files containing any
 violation are **never rewritten** — the build fails loudly instead.
 
-A file is scanned when it contains a `DDBModel.prepare` call site; detection
+A file is scanned when it contains a `graphddb.prepare` call site; detection
 follows import aliases (`import { DDBModel as M }`), namespace imports
 (`g.DDBModel`), module-const aliases, and same-file `extends DDBModel`
 subclasses. Call sites already evaluated once per module load (module-scope
@@ -212,7 +212,7 @@ site is never wrong, only warmer.
 
 Detection also does **not check the import's module specifier**: a binding
 imported as `DDBModel` from **any** package (`import { DDBModel } from
-'<other-package>'`) matches, so another library's same-named `DDBModel.prepare`
+'<other-package>'`) matches, so another library's same-named `graphddb.prepare`
 call site is transformed / linted too (a false transform or a spurious lint
 error is possible). Take care in files that mix graphddb with a same-named
 foreign API.
@@ -221,7 +221,7 @@ foreign API.
 
 - **write** — the params-independent op template compiles once
   (`compileWriteFragment`); `execute` runs the identical core the envelope and
-  `publicCommandModel` use: derived maintainers and atomic
+  `graphddb.publishCommand` use: derived maintainers and atomic
   `TransactWriteItems` semantics match exactly. Multi-alias bodies compose one
   atomic transaction (`mode: 'parallel'` opts out per call).
 - **read** — the params-independent products (resolved model, normalized