graphddb 0.7.10 → 0.8.1

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';
+```
 
-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.
+- `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.
 
-> 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.
+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 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 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 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 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
@@ -330,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
@@ -455,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`)