graphddb 0.4.2 → 0.5.0

package/docs/cqrs-contract.md

@@ -0,0 +1,526 @@
+# GraphDDB CQRS Query / Command Contract Specification
+
+## Overview
+
+The contract layer defines storage-independent public interfaces over GraphDDB
+models, organized as one layering:
+
+```text
+Contract   ← the public, storage-independent interface
+   ↓
+Runtime    ← the execution engine (batch / retry / transaction / cursor / composition)
+   ↓
+Storage    ← the implementation (DynamoDB today)
+```
+
+A contract is the public interface of a CQRS (logical) service. The **Query**
+side is the read API (a read model resolved from storage); the **Command** side
+is the write API (resolving to write operations / transactions). A contract is
+the single source of truth (SSoT) for runtime generation, multi-language
+bindings, OpenAPI generation, execution-plan generation, and static analysis.
+The serialized SSoT is the `contracts` map in the operations document
+(layered on top of the existing `queries` / `commands` / `transactions`).
+
+### Canonical concepts
+
+| Concept           | Definition                          |
+| ----------------- | ----------------------------------- |
+| **Model**         | Data structure (private to a context) |
+| **QueryModel**    | Public read contract — keyed (Key)  |
+| **QueryMethod**   | A read use case (a projection)      |
+| **CommandModel**  | Public write contract — keyed (Key) |
+| **CommandMethod** | A write use case                    |
+| **Runtime**       | Execution engine                    |
+| **Storage**       | Implementation                      |
+
+A QueryModel / CommandModel is identified by its **Key** (the access pattern)
+and holds **one or more Methods**, each a distinct use case. The Key is the
+access pattern; the Method is the use case (e.g. `get` and `summary` over the
+same key, differing only in projection).
+
+Scope is **Query** and **Command** contracts only. Workflow / Event
+orchestration is out of scope (a Runtime concern).
+
+## Architecture
+
+- **Model** defines the data structure. It is the private implementation of a
+  bounded context and does **not** define public access patterns.
+- **Query / Command Contracts** define the public API.
+- **Runtime** performs execution — batching, retries, transactions, per-key
+  cursors, and cross-contract composition — not business logic and not storage
+  shape.
+- **Storage** is the implementation behind the Runtime.
+
+Language targets (TypeScript / Python / OpenAPI / …) are **renderers** of the
+same contract. In 0.2.0 a method is declared as a **descriptor** in a descriptor
+map (no closure body); the two formal method shapes are the generation source:
+
+```ts
+// read route descriptor — exactly one of query | list
+type QueryMethod   = { query | list: Model; key; select; options? };
+// write route descriptor — exactly one of create | update | remove
+type CommandMethod = { create | update | remove: Model; key; input?; condition?; result?; mode? };
+```
+
+`GraphQL contrast`: `query` routes are **parallel independent reads** (no
+cross-route consistency); a command's `mode: 'transaction'` is **atomic
+all-or-nothing**, while `mode: 'parallel'` is **non-atomic per-field partial
+success**.
+
+## Query Contract
+
+A Query Contract (`QueryModel`) defines a public read interface. It is keyed —
+its Key *is* the access pattern — and behaves as a **virtual Model**: the
+records it returns have an identity (its Key) other contracts can join against
+and batch-resolve. A QueryModel holds one or more Methods, each a read use case
+over that same Key, differing in projection (and params).
+
+### Query Key
+
+In 0.2.0 a method's Key is declared **inline in its descriptor** via the `key`
+map (each field a `param.*()`); there is no separate key-type generic or key-
+field list argument. The access pattern — primary key or GSI — is resolved from
+the `Model` plus the `key` fields named in the descriptor:
+
+```ts
+const UserByEmail = publicQueryModel({
+  get: { query: User, key: { email: param.string() }, select: { userId: true, email: true } },
+});
+```
+
+### Query Definition
+
+A method is a single declarative read **descriptor** — `{ query | list: Model,
+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({
+  get: { query: Article, key: { articleId: param.string() },
+         select: { articleId: true, title: true, body: true },
+         options: { consistentRead: false } },
+});
+```
+
+A single descriptor declares the per-key shape; the array capability
+(`get(keys[])`) is derived by the contract.
+
+### Method names are use cases, not operations
+
+A method is named for its use case (`get`, `summary`, `recent`, `disable`),
+never for the storage op it runs. Whether it resolves internally to a `query`
+(point lookup) or a `list` (partition read) is the Runtime's concern and is
+invisible to callers and generated bindings. The internal op determines the
+derived `resolution` / `inputArity` / `cardinality` facts, which are
+bookkeeping, not part of the public method name.
+
+### Derived facts: resolution and input arity
+
+Per method, two facts are **derived** from the internal op (never
+hand-written):
+
+- `resolution`: `'point'` | `'range'`.
+- `inputArity`: `'single'` | `'either'` (`'array'` is reserved, not produced by
+  the current resolvers).
+
+The resolvers:
+
+- a `list` (partition `Query`) → `resolution: 'range'`, `inputArity: 'single'`;
+- a `query` resolving to the **full base-table primary key** (a unique row) →
+  `resolution: 'point'`, `inputArity: 'either'` (a key array coalesces to one
+  `BatchGetItem`);
+- a `query` resolving to a **full, unique GSI** → `resolution: 'point'`,
+  `inputArity: 'single'`: it is a per-key GSI `Query` (a `BatchGetItem` cannot
+  read a GSI), so a key array would be an N+1 fan-out;
+- a `query` resolving to **anything else** (a partial PK prefix, a non-unique
+  GSI, or a partial GSI prefix) is a multi-row partition `Query` and is treated
+  as `resolution: 'range'`, `inputArity: 'single'` (it is not a point — a unique
+  row is the only point).
+
+### Derived arity (no author tagging)
+
+A method's literal arity is **derived** from its descriptor (`query` vs `list`,
+and whether the `key` resolves a unique row) and **build-verified**. There is no
+author-side arity wrapper — the descriptor's `query` / `list` discriminator and
+the resolved key carry the same information:
+
+```ts
+// base-table PK point — a key array coalesces to one BatchGetItem
+get:  { query: Article, key: { articleId: param.string() }, select: { articleId: true, title: true } },
+
+// range list — a partition Query, single key only
+list: { list: Member, key: { groupId: param.string() }, select: { userId: true } },
+```
+
+A `query` resolving to a full base-table primary key is `inputArity: 'either'`
+(a key array coalesces to one `BatchGetItem`); a `query` resolving a unique GSI
+is `'single'` (a per-key GSI Query, not coalescible); a `list` is always
+`'single'`.
+
+### Cardinality matrix
+
+A method's result shape is determined by its internal `resolution` and the
+input cardinality (single key vs. array), both derived. The four combinations:
+
+| Input          | Resolution | Per key    | Result shape                                |
+| -------------- | ---------- | ---------- | ------------------------------------------- |
+| `key` (single) | `point`    | 0..1 item  | `Item \| null`                              |
+| `key` (single) | `range`    | 0..M items | `Connection<Item>` (`{ items, cursor }`)    |
+| `keys[]` (N)   | `point`    | 0..1 each  | `Map<keyId, Item \| null>`                  |
+| `keys[]` (N)   | `range`    | —          | rejected (range is `inputArity: 'single'`)  |
+
+A batched `point` result is **keyed, not flat**: a `Map` keyed by the canonical
+key identity (a field-sorted JSON string, byte-identical across TS and Python),
+where every input key is present with an explicit `null` for a miss (a
+`BatchGetItem` neither preserves order nor returns absent keys).
+
+### Pagination — per-key cursors
+
+A `range` connection's `cursor` is a **per-key envelope**: the inner page cursor
+(the base64url DynamoDB `LastEvaluatedKey`) wrapped together with the canonical
+identity of the owning key, then base64url-encoded as a single opaque string.
+On resume, a supplied `after` is decoded and **verified to belong to the key
+being read** — a cursor minted for one key, fed back for another, is rejected.
+The single-key range form is wrapped too, so cursor handling never branches on
+input arity.
+
+## Command Contract
+
+A Command Contract (`CommandModel`) is the write counterpart of a QueryModel,
+fully symmetric: keyed (its Key is the target identity) and holding one or more
+write-use-case Methods. A command method is a single declarative write
+**descriptor** — `{ create | update | remove: Model, key, input?, condition?,
+result?, mode? }`, with exactly one of `create` / `update` / `remove`.
+
+```ts
+export const UserCommands = publicCommandModel({
+  disable: { update: User, key: { userId: param.string() },
+             input: { status: 'disabled', disableReason: param.string() },
+             result: { select: { userId: true, status: true } } },
+  enable:  { update: User, key: { userId: param.string() }, input: { status: 'active' } },
+  changeRole: { update: User, key: { userId: param.string() }, input: { role: param.string() } },
+});
+```
+
+### Result and condition
+
+- `result: { select, options? }` — the post-write read-back projection. Omit it
+  → the method returns `void`.
+- `condition` — a `WriteCondition` write gate: the write applies only if the
+  persisted item matches. It accepts the **full declarative operator subset** of a
+  read filter (`eq`/`ne`/`gt`/`ge`/`lt`/`le`/`between`/`in`/`beginsWith`/
+  `contains`/`notContains`/`size`/`attributeType` + `and`/`or`/`not`), the legacy
+  existence primitives (`notExists` / `attributeExists` / `attributeNotExists`),
+  **or** a raw `cond\`…\`` fragment whose value slots may be `param.*` bindings:
+
+  ```ts
+  export const UserCommands = publicCommandModel({
+    // declarative operators in a write condition
+    promote: { update: User, key: { userId: param.string() },
+               input: { role: 'admin' },
+               condition: { and: [{ status: { ne: 'banned' } },
+                                  { version: { ge: param.number() } }] } },
+    // raw `cond` escape hatch, value slot bound to a param
+    bump: { update: User, key: { userId: param.string() },
+            input: { version: param.number() },
+            condition: cond`${User.col.version} = ${param.number()}` },
+  });
+  ```
+
+  **Constraint:** a `cond` used as the **whole** condition is fully supported. A
+  `cond` **nested inside** a declarative `and` / `or` / `not` group is **rejected
+  at build time** on this serializable surface (the serialized `expr` tree carries
+  no raw fragment) — move it to the top level or express the group declaratively.
+- `key` may be a single object **or** an array of objects (bulk).
+
+### Mode (atomicity) — the `mode` descriptor key
+
+A command method declares its atomicity per method via `mode`, replacing the old
+`batch` option:
+
+```ts
+// default — one atomic TransactWriteItems (condition-capable, ≤25)
+disable: { update: User, key: { userId: param.string() },
+           input: { status: 'disabled' }, mode: 'transaction' },
+
+// non-atomic — BatchWriteItem (chunked + UnprocessedItems retry), per-op partial success
+addMany: { create: GroupMembership, key: { groupId: param.string(), userId: param.string() },
+           input: { role: param.string() }, mode: 'parallel' },
+```
+
+- `mode: 'transaction'` (**DEFAULT**) — one `TransactWriteItems`: writes applied
+  **atomically**, all-or-nothing rollback, throws on failure, and
+  condition-capable (`WriteCondition`: the full declarative operator subset, the
+  existence primitives, or a `cond` fragment). More than 25 items
+  is a hard error (never split).
+- `mode: 'parallel'` — **non-atomic**: independent ops run in parallel; each
+  alias surfaces **per-op partial success** in the result object as `{ ok }` |
+  `{ error }`. Ordering of dependent ops is derived from `$.alias.field`
+  references.
+
+`GraphQL contrast`: `mode: 'transaction'` is atomic all-or-nothing; `mode:
+'parallel'` is non-atomic per-field partial success.
+
+#### The 25-item limit is a hard error, never a silent split
+
+`TransactWriteItems` is capped at **25 items** and is atomic. A
+`mode: 'transaction'` method called with more than 25 keys is **rejected** with a
+clear error rather than truncated or split — splitting would break the
+all-or-nothing guarantee. A caller needing per-key independence at higher volume
+must declare `mode: 'parallel'`, which is chunked automatically.
+
+## External Query / Cross-Contract Composition
+
+A query method may compose **another query contract's** method as a composed
+read dependency, declared with the `query($ => ({...}))` builder; a cross-
+fragment reference uses `$.alias.field`:
+
+```ts
+export const AccountAccess = publicQueryModel({
+  get: query($ => ({
+    account: { query: Account, key: { accountId: param.string() },
+               select: { accountId: true } },
+    billing: { query: BillingPlan, key: { accountId: $.account.billingAccountId },
+               select: { plan: true } },
+  })),
+});
+```
+
+A `$.alias.field` reference is recorded as a declarative composition edge: the
+fragment whose key reads `$.alias.field` is resolved after, and batched against,
+the producing fragment. The binding is declarative — a `$`-rooted dotted field
+path only (a bare field, index, wildcard, or empty path is rejected, and the
+segments `__proto__` / `constructor` / `prototype` are forbidden), so no
+arbitrary JS reaches a key binding.
+
+This is **build-time-resolved, in-process** contract chaining — relation
+chaining where the link is a contract reference instead of a model relation.
+There is no protocol, transport, or service discovery; the "boundary" crossed is
+logical. The runtime collects every bound key produced by the parent step and
+resolves the referenced contract **once, batched** (DataLoader-style), across
+all parent records — N parents collapse to one `BatchGetItem`. The composed
+child **must** be `point`; a `range` child would be an N+1 fan-out and is
+rejected at build time.
+
+The serializer recovers the referenced contract's name by identity and emits a
+`compose` node. An independent set of sibling compositions forms one
+concurrency-eligible stage executed after the parent read; the staging,
+concurrency bound (16), and per-request chunk size (100, the `BatchGetItem`
+limit) are serialized as a composition plan the runtimes **honor**, not
+re-derive.
+
+## N+1 Safety (static restriction)
+
+Whether a resolution is N+1-safe depends on two facts: the **resolution kind**
+(`point` coalesces; `range` is one request per partition key) and the **input
+cardinality** (a `range` method is one query for one key but N for N keys).
+Output cardinality alone is insufficient, so both `resolution` and `inputArity`
+are decided once on the producer side and **serialized as decided facts** — every
+runtime honors them rather than re-deriving the policy.
+
+### The rule
+
+A `range` resolution is allowed only with single-key input. There is
+intentionally **no bounded-fan-out opt-in**; a caller needing "just these few"
+loops in application code, keeping the N visible at the call site. `point`
+resolutions are always allowed (they coalesce). The following are build-time
+errors, raised on the contract build path:
+
+- **array into a `range` method** — a `range` method whose `inputArity` is not
+  `'single'`;
+- **array into a unique-GSI `point` method** — a `point` method that resolves via
+  a unique GSI (a per-key `Query`) but whose `inputArity` is not `'single'`;
+- **list under a list** — a `range` child nested under a parent step whose
+  per-key output cardinality is `'many'`;
+- **`range` composed child under a many-yielding parent** — the cross-contract
+  form of the above.
+
+Enforcement is layered: the generated binding types encode `inputArity` (a
+`'single'` method's array argument is `never`, so an array is a `tsc` error),
+the build-time SSoT checker rejects the four forms above, and the runtime is a
+final backstop that rejects an array fed into any `'single'` method.
+
+## Context boundary enforcement
+
+A Model is the private implementation of its bounded context; a Contract is its
+published interface. Within its own context a contract resolves its own Models
+directly. Across a context boundary it may depend on another context **only
+through that context's published Contract** (an External Query / Command);
+reaching directly into a foreign Model is a **build-time error**.
+
+Ownership is declared in a `contexts` map (context name → `{ models, contracts }`).
+A method op against a Model owned by a context different from the contract's own
+owning context is the violation. The check is purely additive and fires only
+when **both** the contract and the touched Model have declared, different
+owners: a contract in no declared context is unconstrained, and an undeclared
+Model has no owner to protect. The check runs on the build path (where the
+recorded op `entity` refs and the `contexts` map are both available), not in the
+single-model lint framework.
+
+## Build-time hardening of method bodies
+
+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:
+
+1. **Throwing sentinel Proxy** — any property / method access other than the
+   internal brand reads or primitive coercion throws at the access site.
+2. **Per-access coercion ledger** — a faithful reference is stored as the Proxy
+   object and never coerced, so any coercion of a `keys` / `params` field proves
+   the body consumed it into a transform / branch / interpolation, and the build
+   is rejected.
+3. **Differential evaluation** — the body runs twice with disjoint per-field
+   markers; every recorded leaf must be a faithful reference or a byte-identical
+   literal across both passes.
+4. **Consumed-field check** — a `params` field the body accessed but that never
+   reached the recorded operation (a silent value branch) is rejected.
+
+A body must resolve to **exactly one** model operation; zero or more than one is
+rejected (multiple writes belong in a transaction). A query model rejects a body
+that resolves to a write op, and a command model rejects a body that resolves to
+a read op. So any non-declarative body — a transform, a value branch, a
+coercion, or arbitrary JS over `keys` / `params` — is a build error, never
+silently emitted as a wrong spec.
+
+## SSoT Schema
+
+The contract layer is serialized as a `contracts` map layered on top of the
+existing operation specs. Each contract method references an existing operation
+spec (in `queries` / `commands` / `transactions`) by name and adds the decided
+facts. The existing operation-spec shapes are unchanged, and both `contracts`
+and `contexts` are **absent** when the input declares none (a contract-free
+input produces a byte-identical pre-contract document).
+
+```jsonc
+{
+  "version": "1.0",
+  "contracts": {
+    // point query: single OR array (array → BatchGetItem)
+    "ArticleById": {
+      "kind": "query",
+      "key": { "fields": ["articleId"] },
+      "methods": {
+        "get": {
+          "resolution": "point",
+          "inputArity": "either",
+          "cardinality": "one",
+          "operation": "ArticleById__get"
+        }
+      }
+    },
+
+    // range list: single key only (partition Query, not batchable)
+    "ArticleByCategory": {
+      "kind": "query",
+      "key": { "fields": ["categoryId"] },
+      "methods": {
+        "list": {
+          "resolution": "range",
+          "inputArity": "single",
+          "cardinality": "many",
+          "operation": "ArticleByCategory__list"
+        }
+      }
+    },
+
+    // composition / External Query: child must be `point`
+    "AccountAccess": {
+      "kind": "query",
+      "key": { "fields": ["accountId"] },
+      "methods": {
+        "get": {
+          "resolution": "point",
+          "inputArity": "either",
+          "cardinality": "one",
+          "operation": "AccountAccess__get",
+          "compose": [
+            {
+              "as": "billing",
+              "contract": "BillingPlanQueries",
+              "method": "get",
+              "context": "billing",
+              "bind": { "accountId": "$.billingAccountId" },
+              "resolution": "point",
+              "cardinality": "one"
+            }
+          ],
+          "compositionPlan": { "stages": [[0]], "concurrency": 16, "batchChunkSize": 100 }
+        }
+      }
+    },
+
+    // command: single → one write; array → transaction
+    "UserCommands": {
+      "kind": "command",
+      "key": { "fields": ["userId"] },
+      "methods": {
+        "disable": {
+          "inputArity": "either",
+          "result": "entity",
+          "single": { "mode": "op",          "operation": "UserCommands__disable" },
+          "batch":  { "mode": "transaction", "transaction": "UserCommands__disable__batch" }
+        }
+      }
+    }
+  },
+
+  "contexts": {
+    "billing": { "models": ["BillingPlan"], "contracts": ["BillingPlanQueries"] }
+  },
+
+  // existing specs, unchanged shape, referenced by `operation` / `transaction`
+  "queries":      { "ArticleById__get": { /* … */ } },
+  "commands":     { "UserCommands__disable": { /* … */ } },
+  "transactions": { "UserCommands__disable__batch": { /* forEach over keys */ } }
+}
+```
+
+### Serialized types
+
+- `ContractSpec` — `{ kind, key: { fields }, methods }`.
+- `QueryContractMethodSpec` — `{ resolution, inputArity, cardinality, operation,
+  compose?, compositionPlan? }`.
+- `ComposeSpec` — `{ as, contract, method, context?, bind, resolution,
+  cardinality }`. A composed child's `resolution` must be `'point'`.
+- `CommandContractMethodSpec` — `{ inputArity, result, single, batch? }`, where a
+  resolution target is `{ mode: 'op', operation }`, `{ mode: 'transaction',
+  transaction }`, or `{ mode: 'parallel', operation }`.
+- `ContextSpec` — `{ models, contracts }` (sorted name lists).
+
+## Public API surface
+
+Definition DSL (`src/define/contract.ts`):
+
+```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
+param.string() / param.number() / ...               // descriptor key/input parameters
+```
+
+Runtime (`src/runtime/*`):
+
+```ts
+executeQueryMethod(contract, methodName, key | keys[], params?)    // contract-runtime
+executeCommandMethod(contract, methodName, key | keys[], params?)  // command-runtime
+encodePerKeyCursor / decodePerKeyCursor / serializeContractKey     // per-key-cursor
+```
+
+Build / static analysis (`src/spec/*`):
+
+```ts
+buildContracts(contracts)                  // → { contracts, queries, commands, transactions }
+buildContexts(contexts)                    // → context-ownership specs
+assertContractN1Safe(name, spec, isGsiPoint?)
+assertContractBoundaries(...)              // context-boundary lint
+```
+
+## Query vs Command
+
+| Aspect       | Query                  | Command                          |
+| ------------ | ---------------------- | -------------------------------- |
+| Direction    | Read                   | Write                            |
+| Side effects | None                   | State mutation                   |
+| Composition  | May compose other contracts | Composes internal write ops |
+| Boundary     | Public read contract   | Public write contract            |