graphddb 0.7.9 → 0.8.0

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

package/docs/python-bridge.md

@@ -33,7 +33,7 @@ access patterns that TypeScript has already defined and validated.
 ```text
 TypeScript (design-time / build-time SSoT)
   ├─ Entity / Key / GSI / Relation models
-  ├─ Parameterized query / command definitions (param + define*)
+  ├─ 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
@@ -51,7 +51,7 @@ boto3 DynamoDB client
 | Layer | Responsibility |
 |---|---|
 | TypeScript model | Entity / key / GSI / relation definitions |
-| Definition DSL (`param`, `define*`) | The permitted, parameterized queries and commands |
+| 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 |
@@ -69,68 +69,96 @@ 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.
+Parameters are legal only inside the structures passed to the contract authoring
+entry points (`graphddb.publishQuery` / `graphddb.publishCommand`) — never to the
+live `Model.query` / `Model.putItem` runtime API, whose types remain free of
+parameter placeholders.
 
-### 3.2 Definition Entry Points
+### 3.2 Contract Authoring Entry Points
 
-Definitions are built with dedicated entry points, each accepting `param`
+Public reads and writes are authored through the CQRS contract layer, the sole
+read/write authoring surface. Import the `graphddb` namespace and publish keyed
+contracts whose methods are declarative descriptors, 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.
+```ts
+import { graphddb, param } from 'graphddb';
+```
+
+- `graphddb.publishQuery({ name: { get: { query: Model, key, select } } })` —
+  single-item read (unique key).
+- `graphddb.publishQuery({ name: { list: { list: Model, key, select } } })` —
+  partition read (partial / partition key).
+- `graphddb.publishCommand({ name: { create: Model, key, input } })` — put.
+- `graphddb.publishCommand({ name: { update: Model, key, input } })` — update.
+- `graphddb.publishCommand({ name: { remove: Model, key } })` — 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.
+A command method descriptor accepts an optional `condition` (see §6.2) and an
+optional `result: { select }` read-back projection. Each published contract
+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.
+> Design note: the authoring surface is `graphddb.publishQuery` /
+> `graphddb.publishCommand` (not `Model.query(...)` overloads), so 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).
+`graphddb.publishQuery({ ... })` publishes a keyed read contract whose methods
+resolve to `get` / `list` descriptors; `graphddb.publishCommand({ ... })`
+publishes a keyed write contract whose methods resolve to `create` / `update` /
+`remove` descriptors. Each validates that every method is the correct operation
+kind and returns the typed contract that the planner consumes. Atomic multi-op
+writes are declared with a `mode: 'transaction'` descriptor and compile to a
+declarative `TransactionSpec` (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 },
-  ),
+import { graphddb, param } from 'graphddb';
+
+export const UserByEmail = graphddb.publishQuery({
+  get: {
+    query: User,
+    key: { email: param.string() },
+    select: { userId: true, name: true, email: true, status: true },
+  },
+});
+
+export const MembersByGroup = graphddb.publishQuery({
+  list: {
+    list: GroupMembership,
+    key: { groupId: param.string() },
+    select: { 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(),
-  }),
+export const MembershipCommands = graphddb.publishCommand({
+  addGroupMember: {
+    create: GroupMembership,
+    key: { groupId: param.string(), userId: param.string() },
+    input: { role: param.string() },
+  },
+  deleteGroupMember: {
+    remove: GroupMembership,
+    key: { groupId: param.string(), userId: param.string() },
+  },
 });
+
+export const UserCommands = graphddb.publishCommand({
+  disableUser: {
+    update: User,
+    key: { userId: param.string() },
+    input: { status: param.literal('disabled') },
+  },
+});
+
+// The `contracts` map the generator consumes (see §5).
+export const contracts = {
+  UserByEmail,
+  MembersByGroup,
+  MembershipCommands,
+  UserCommands,
+};
 ```
 
 ## 4. The Bridge Bundle
@@ -209,7 +237,7 @@ so the output is stable across runs.
 
 ```ts
 interface OperationsDocument {
-  readonly version: '1.1';
+  readonly version: '1.1' | '1.2';
   readonly queries: Record<string, QuerySpec>;
   readonly commands: Record<string, CommandSpec>;
   readonly transactions?: Record<string, TransactionSpec>;
@@ -218,6 +246,22 @@ interface OperationsDocument {
 }
 ```
 
+**Spec version `1.2` — SCP Expression IR (issue #261, conditional stamping).**
+`1.2` adds the behavior-contracts Expression IR vocabulary
+(`expression-ir.md` §2) to the operations document: a sixth write-condition
+variant `{ kind: 'scpExpr', expression: { exprVersion: 1, expr } }`, and a
+`guard: { exprVersion: 1, expr }` slot on transaction items and contract
+command methods (beside the legacy `when`). The expression payload is stored in
+**canonical form** (key-sorted in code-point order; `{int:"…"}` /
+`{float:n}` literal wrapping per expression-ir.md §2.3). The stamp is
+**conditional**: only a document that actually *contains* an SCP node is
+stamped `1.2` — every SCP-free document keeps `1.1` and serializes
+byte-identically. Runtimes keep `SPEC_VERSION_SUPPORTED = "1.1"` until their
+expression *evaluation* lands (Phase 3 S5/S6/S7 — #265/#266/#267), so an
+expression-bearing document is loud-rejected everywhere in the meantime
+(fail-closed, never a silently-skipped guard). The manifest never carries
+expression vocabulary and always stays `1.1`.
+
 #### Parameter specs
 
 Every operation carries a `params` map of `ParamSpec`:
@@ -314,20 +358,17 @@ GSI-keyed write is rejected by the planner.
 ```bash
 graphddb generate python \
   --entry src/models/index.ts \
-  --queries src/models/queries.ts \
-  --commands src/models/commands.ts \
+  --contracts src/models/contracts.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. |
+| `--entry`, `-e` | yes | — | Module that registers entity models (imported for side effects); may also export `contracts` / `contexts` / `transactions`. |
 | `--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`. |
+| `--contracts` | no | `--entry` | Module exporting the CQRS `contracts` map (`graphddb.publishQuery` / `graphddb.publishCommand` results). |
 | `--contexts` | no | `--contracts` then `--entry` | Module exporting context ownership. |
+| `--transactions`, `-t` | no | `--entry` | Module exporting `transactions`. |
 | `--dataclass` | no | `false` | Emit `@dataclass` result types instead of `TypedDict`. |
 
 TypeScript definition modules are transpiled on the fly (via tsx/esbuild — the
@@ -439,15 +480,21 @@ the serialized `expr` tree). (Per-item conditions are not available on
 
 ### 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.
+An atomic multi-op write — a `mode: 'transaction'` command descriptor, or the
+derived effects of any command (edges, counters, uniqueness guards, outbox,
+idempotency, maintenance writes) — compiles to a declarative `TransactionSpec`.
+Its `items` write with field references or literals at scalar leaves; a bulk
+`key: K[]` command lowers to a single `forEach`-over-keys item; and each item may
+carry a declarative `when` comparison (`eq` / `ne`) and/or a supported
+`condition`. The `TransactionSpec` `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.
+
+(The internal declarative-transaction recorder that produces this IR is the
+`publishCommand` / `mutate` compile backend and the `graphddb transform`
+lowering target — it is not a public authoring verb.)
 
 ## 7. The Python Runtime (`graphddb_runtime`)