graphddb 0.8.0 → 0.9.0

package/dist/spec/index.js

@@ -2,22 +2,26 @@ import {
   assertContractBoundaries,
   assertContractN1Safe,
   buildBridgeBundle,
+  buildComponents,
   buildContexts,
   buildContracts,
   buildOperations,
   buildPreparedPlanDocument,
+  buildQueryComponent,
   buildQuerySpec,
+  buildTransactionComponent,
   collectContractBoundaryViolations,
   collectContractN1Violations,
-  compilePreparedPlan
-} from "../chunk-N4NWYNGZ.js";
+  compilePreparedPlan,
+  portableIrDocument
+} from "../chunk-SSVG6NQK.js";
 import {
   PREPARED_FORMAT_VERSION,
   buildManifest,
   canonicalJson,
   entityFingerprint,
   planFingerprint
-} from "../chunk-LGHSZIEE.js";
+} from "../chunk-NWTEUWJD.js";
 import {
   MAX_TRANSACT_COMPOSE_ITEMS,
   assertBundleSerializable,
@@ -32,24 +36,25 @@ import {
   resetMaintenanceGraphCache,
   resolveLifecycle,
   resolveMaintainers
-} from "../chunk-I4LEJ4TF.js";
-import "../chunk-HNY2EJPV.js";
+} from "../chunk-XZTA4VJH.js";
+import "../chunk-KOIJ4SNO.js";
 import {
   EXPR_VERSION,
   SPEC_VERSION,
+  SPEC_VERSION_KEY_EXPR,
   SPEC_VERSION_SCP,
   SPEC_VERSION_SUPPORTED,
   canonicalizeExpressionSpec,
-  operationsContainScpNodes,
   operationsSpecVersion
-} from "../chunk-L4QRCHRQ.js";
-import "../chunk-L2NEDS7U.js";
+} from "../chunk-WOFRHRXY.js";
+import "../chunk-ZNU7OI5I.js";
 import "../chunk-XTWXMOHD.js";
 export {
   EXPR_VERSION,
   MAX_TRANSACT_COMPOSE_ITEMS,
   PREPARED_FORMAT_VERSION,
   SPEC_VERSION,
+  SPEC_VERSION_KEY_EXPR,
   SPEC_VERSION_SCP,
   SPEC_VERSION_SUPPORTED,
   assertBundleSerializable,
@@ -59,12 +64,15 @@ export {
   assertNoCrossFragmentMaintainCollision,
   assertSupportedCondition,
   buildBridgeBundle,
+  buildComponents,
   buildContexts,
   buildContracts,
   buildManifest,
   buildOperations,
   buildPreparedPlanDocument,
+  buildQueryComponent,
   buildQuerySpec,
+  buildTransactionComponent,
   buildTransactionSpec,
   buildTransactions,
   canonicalJson,
@@ -76,9 +84,9 @@ export {
   compilePreparedPlan,
   compileSingleFragmentPlan,
   entityFingerprint,
-  operationsContainScpNodes,
   operationsSpecVersion,
   planFingerprint,
+  portableIrDocument,
   resetMaintenanceGraphCache,
   resolveLifecycle,
   resolveMaintainers

package/dist/testing/index.d.ts

@@ -1,5 +1,6 @@
-import { n as Executor, o as DynamoDBOperation, R as ReadExecOptions, p as ExecutorResult, B as BatchGetExecInput, q as PutInput, W as WriteExecOptions, r as WriteResult, U as UpdateInput, s as DeleteInput, t as BatchWriteExecItem, u as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, D as DDBModel, v as ChangeEvent } from '../key-DR7_lpyk.js';
-import '../types-2PMXEn5x.js';
+import { n as Executor, o as DynamoDBOperation, R as ReadExecOptions, p as ExecutorResult, B as BatchGetExecInput, q as PutInput, W as WriteExecOptions, r as WriteResult, U as UpdateInput, s as DeleteInput, t as BatchWriteExecItem, u as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, D as DDBModel, v as ChangeEvent } from '../key-Dne-a20Q.js';
+import '../types-CfxzTEFL.js';
+import 'behavior-contracts';
 
 /**
  * In-process physical store backing the GraphDDB Memory Test Adapter

package/dist/testing/index.js

@@ -1,12 +1,12 @@
 import {
   createCdcEmulator
-} from "../chunk-GS4C5VGO.js";
-import "../chunk-HNY2EJPV.js";
+} from "../chunk-YGQ2NO6J.js";
+import "../chunk-KOIJ4SNO.js";
 import {
   ClientManager,
   MetadataRegistry,
   resolveModelClass
-} from "../chunk-L2NEDS7U.js";
+} from "../chunk-ZNU7OI5I.js";
 import {
   TableMapping
 } from "../chunk-XTWXMOHD.js";

package/dist/transform/index.d.ts

@@ -1,5 +1,6 @@
 import ts from 'typescript';
-import { E as ExpressionSpec } from '../types-2PMXEn5x.js';
+import { E as ExpressionSpec } from '../types-CfxzTEFL.js';
+import 'behavior-contracts';
 
 /**
  * Compile-time hoist transform + no-runtime-capture build lint for

package/dist/transform/index.js

@@ -2,8 +2,8 @@ import {
   EXPR_VERSION,
   SCP_LOWERED_MARKER,
   canonicalizeExpressionSpec
-} from "../chunk-L4QRCHRQ.js";
-import "../chunk-L2NEDS7U.js";
+} from "../chunk-WOFRHRXY.js";
+import "../chunk-ZNU7OI5I.js";
 import "../chunk-XTWXMOHD.js";
 
 // src/transform/prepared-transform.ts

package/dist/{types-BXLzIcQD.d.ts → types-BnFsTZwl.d.ts}

@@ -1,4 +1,4 @@
-import { d as SegmentedKey, e as ProjectionTransform, f as MaintainEvent, g as ProjectionMap, h as MaintainConsistency, i as MaintainUpdateMode, E as EffectPath, j as MembershipPredicate } from './key-DR7_lpyk.js';
+import { d as SegmentedKey, e as ProjectionTransform, f as MaintainEvent, g as ProjectionMap, h as MaintainConsistency, i as MaintainUpdateMode, E as EffectPath, j as MembershipPredicate } from './key-Dne-a20Q.js';
 
 type DynamoType = 'S' | 'N' | 'BOOL' | 'B' | 'SS' | 'NS' | 'L' | 'M';
 interface FieldOptions {

package/dist/{types-2PMXEn5x.d.ts → types-CfxzTEFL.d.ts}

@@ -1,3 +1,5 @@
+import { Component } from 'behavior-contracts';
+
 /**
  * Parameter placeholders for the parameterized query / command definition DSL
  * (issue #41, Python-bridge Phase 0a).
@@ -21,7 +23,7 @@
 /** Brand tag preventing a plain object from structurally matching a {@link Param}. */
 declare const PARAM_BRAND: unique symbol;
 /** Runtime discriminant for a parameter placeholder. */
-type ParamKind = 'string' | 'number' | 'literal' | 'array';
+type ParamKind = 'string' | 'number' | 'literal' | 'array' | 'map';
 /**
  * A branded parameter placeholder representing a value of TypeScript type `T`
  * that is bound at execution time rather than definition time.
@@ -64,6 +66,28 @@ type StringParam = Param<string>;
 type NumberParam = Param<number>;
 /** A `Param` whose represented value type is the literal union `L`. */
 type LiteralParam<L extends string | number> = Param<L>;
+/**
+ * A `Param` standing in for a **map / embedded object** value (issue #295): a
+ * JSON-serializable object written to a single DynamoDB `M` attribute. The
+ * `kind` is narrowed to the `'map'` literal so type-level dispatch works, and
+ * the represented value type `T` (default `Record<string, unknown>`) lets a
+ * typed domain value class ride the placeholder:
+ *
+ * ```ts
+ * type AvgValue = Record<string, Record<string, { sum: number; count: number }>>;
+ * param.map<AvgValue>(); // Param<AvgValue> bound to a `@map value!: AvgValue` field
+ * ```
+ *
+ * The value crosses every boundary as a **native DynamoDB `M` attribute**
+ * (never a JSON-string blob): the placeholder renders to a `{field}` token /
+ * `{ref:["field"]}` Expression-IR reference in the portable IR, and each
+ * runtime's (already recursive) attribute marshaller serializes the supplied
+ * object to `M`. Generated bindings type it as the language's native free-form
+ * map (`dict` / `map[string]any` / `serde_json::Value` / `array`).
+ */
+type MapParam<T extends Record<string, unknown> = Record<string, unknown>> = Param<T> & {
+    readonly kind: 'map';
+};
 /** The element-field descriptor shape accepted by {@link param.array}. */
 type ArrayElementShape = Record<string, Param<unknown>>;
 /**
@@ -131,6 +155,29 @@ declare const param: {
      * ```
      */
     readonly array: <const E extends ArrayElementShape>(element: E, options?: ParamOptions) => ArrayParam<E>;
+    /**
+     * A placeholder for a **map / embedded object** value written to a single
+     * DynamoDB `M` attribute (issue #295). Free-form by design: the model-side
+     * vocabulary (`@map` / `@embedded`) records no nested schema, so the param is
+     * typed as the language-native map in generated bindings (`dict` /
+     * `map[string]any` / `serde_json::Value` / `array`) while the optional type
+     * parameter `T` keeps the TS authoring surface precise.
+     *
+     * Legal at **value positions only** (a write descriptor's `input`, a
+     * transaction fragment value, a batch-write per-item payload field) — a map
+     * cannot compose a key, so a `param.map()` in a key position is rejected
+     * loudly at build time.
+     *
+     * @example
+     * ```ts
+     * putLeaf: {
+     *   upsert: TreeNode,
+     *   key: { part: param.string(), child: param.string() },
+     *   input: { value: param.map<AvgValue>(), computedAt: param.number() },
+     * }
+     * ```
+     */
+    readonly map: <T extends Record<string, unknown> = Record<string, unknown>>(options?: ParamOptions) => MapParam<T>;
 };
 
 /**
@@ -181,6 +228,27 @@ declare const SPEC_VERSION: "1.1";
  * (#265/#266/#267) land and bump the supported constant with the wiring.
  */
 declare const SPEC_VERSION_SCP: "1.2";
+/**
+ * The schema version stamped on an operations document whose **read operations**
+ * carry the SCP IR Phase 2 Expression-IR key wiring (`keyExpr` / `valueExpr`,
+ * issue #289). This is the **operations IR 2.0 milestone** (the "2.0-rc" of the
+ * migration plan §3 Phase 2 / M3): a MAJOR bump (`1.x` → `2.x`), because the key
+ * wiring's serialization changed from a `{param}` string template to the portable
+ * Expression IR `concat`/`ref` closed vocabulary (behavior-contracts
+ * `expression-ir.md`). The BEHAVIOR is identical — the change is purely in IR
+ * serialization — but a major bump is correct: a pre-#289 runtime (supported
+ * `1.2`) `validateEnvelope`-rejects a `2.0` document (its `keyExpr` reader does
+ * not exist), which is the intended fail-closed break. Stamped **only** when a
+ * document actually carries a read op (a `queries` entry); a commands/transactions
+ * -only document has no read-path key wiring and keeps its `1.1`/`1.2` stamp,
+ * serializing byte-identically.
+ *
+ * The stamp string is the integer `<major>.<minor>` form `validateEnvelope`
+ * requires (`2.0`); "2.0-rc" is the migration MILESTONE label (dual-emit proven,
+ * flip landed), not the wire version — a `-rc` suffix is not a valid envelope
+ * version and would fail-closed in graphddb's own runtime.
+ */
+declare const SPEC_VERSION_KEY_EXPR: "2.0";
 /**
  * The HIGHEST spec-IR minor this **TS runtime** understands and will EXECUTE
  * (issue #265, Phase 3 S5). The shared `validateEnvelope` fail-closed rule is
@@ -194,10 +262,19 @@ declare const SPEC_VERSION_SCP: "1.2";
  * unknown `exprVersion` / operator still fail-closes (the expr evaluator rejects
  * it). The py/rust/go runtimes bump in S6, PHP in S7 — the whole release column
  * moves to `1.2` together.
+ *
+ * **SCP IR Phase 2 (#289): bumped to `2.0` (major).** The read-op key wiring is
+ * now portable Expression IR (`keyExpr` / `valueExpr`), a MAJOR serialization
+ * change. `validateEnvelope`'s rule is "major must match, minor ≤ supported", so
+ * a `2.0` runtime accepts `2.0` documents and **rejects every `1.x` document**
+ * (major mismatch) — and every `1.x` runtime rejects a `2.0` document. That is
+ * the intended breaking cut: the whole operations IR moves to `2.0` at once
+ * (migration plan §4). All 4 runtimes bump their supported constant to `2.0`
+ * together (one release column), mirroring the `1.2` bump discipline.
  */
-declare const SPEC_VERSION_SUPPORTED: "1.2";
-/** A spec version an operations document may carry (see {@link SPEC_VERSION_SCP}). */
-type SpecVersion = typeof SPEC_VERSION | typeof SPEC_VERSION_SCP;
+declare const SPEC_VERSION_SUPPORTED: "2.0";
+/** A spec version an operations document may carry (see {@link SPEC_VERSION_KEY_EXPR}). */
+type SpecVersion = typeof SPEC_VERSION | typeof SPEC_VERSION_SCP | typeof SPEC_VERSION_KEY_EXPR;
 /** Field type as carried in the manifest (derived from the DynamoDB type). */
 type ManifestFieldType = 'string' | 'number' | 'boolean' | 'binary' | 'stringSet' | 'numberSet' | 'list' | 'map';
 interface ManifestField {
@@ -305,12 +382,17 @@ interface ManifestTable {
 }
 interface Manifest {
     /**
-     * Always the base {@link SPEC_VERSION}: the manifest carries entity/schema
-     * metadata only — the SCP Expression IR vocabulary (issue #261) lives in the
-     * operations document, so the conditional `1.2` stamp never applies here and
-     * every manifest stays byte-identical.
+     * The IR SSoT version. Historically the base {@link SPEC_VERSION} (`1.1`): the
+     * manifest carries entity/schema metadata only, so the conditional `1.2`
+     * Expression-IR stamp never applied here. **SCP IR Phase 2 (#289): moved to
+     * {@link SPEC_VERSION_KEY_EXPR} (`2.0`).** The operations IR took a MAJOR bump
+     * (portable Expression IR key wiring), and `validateEnvelope`'s "major must
+     * match" rule is applied to the manifest AND the operations document against a
+     * single supported constant — so the manifest version must track the same major
+     * or every load would fail major-mismatch. The manifest CONTENT is unchanged;
+     * only its version stamp moves to `2.0` with the rest of the IR SSoT.
      */
-    readonly version: typeof SPEC_VERSION;
+    readonly version: typeof SPEC_VERSION_KEY_EXPR;
     readonly tables: Readonly<Record<string, ManifestTable>>;
     readonly entities: Readonly<Record<string, ManifestEntity>>;
 }
@@ -332,12 +414,31 @@ interface ParamSpec {
      */
     readonly description?: string;
 }
-/** A `begins_with` range condition on a sort key (templated value). */
+/** A `begins_with` range condition on a sort key (Expression-IR value). */
 interface RangeConditionSpec {
     readonly operator: 'begins_with';
     readonly key: string;
-    /** Template value, e.g. `GROUP#` or `GROUP#{result.groupId}`. */
-    readonly value: string;
+    /**
+     * The range value as **Expression IR** (SCP IR Phase 2, issue #289): e.g.
+     * `"USER#"` (a bare literal) or `{concat:["USER#",{ref:["result","groupId"]}]}`.
+     * The runtime evaluates it with `evaluateExpression` — the same closed
+     * `concat`/`ref` vocabulary the key wiring uses (`key-expr.ts`). Replaces the
+     * pre-#289 `{param}` string template (dual-emitted and proven byte-identical
+     * through conformance before the template path was removed, P2-3).
+     *
+     * Optional only because the builders construct the raw range condition with
+     * `value` first and the `lowerOperationKeyExprs` pass fills `valueExpr` — every
+     * serialized range condition carries `valueExpr`.
+     */
+    readonly valueExpr?: ExpressionNode;
+    /**
+     * @deprecated Phase 2 dual-emit (issue #289 P2-3): the pre-#289 `{param}`
+     * string template (`GROUP#{result.groupId}`), emitted ALONGSIDE
+     * {@link valueExpr} only during the migration so the runtimes' Expression-IR
+     * reading can be proven byte-identical to the template render before the
+     * template path is deleted. Removed at the flip.
+     */
+    readonly value?: string;
 }
 /** Server-side declarative filter, carried verbatim for the runtime to compile. */
 interface FilterSpec {
@@ -354,10 +455,28 @@ interface OperationSpec {
     readonly tableName: string;
     readonly indexName?: string;
     /**
-     * Key condition: attribute name → template value. For a `BatchGetItem` this is
-     * the per-key shape (one key per resolved source item at runtime).
+     * Key condition as **Expression IR** (SCP IR Phase 2, issue #289): attribute
+     * name → an Expression IR node (`concat`/`ref`) that evaluates to the key
+     * value, e.g. `PK: {concat:["ARTICLE#",{ref:["input","articleId"]}]}`. For a
+     * `BatchGetItem` this is the per-key shape (one key per resolved source item).
+     * The runtime evaluates each node with `evaluateExpression` against the
+     * `{input, result}` scope — the universal Port-wiring vocabulary
+     * (scp-ir-architecture.md §5), lowered from the pre-#289 `{param}` string
+     * template by `key-expr.ts`.
+     *
+     * Optional only because the builders construct the raw op with `keyCondition`
+     * first and a single `lowerOperationKeyExprs` pass fills `keyExpr` from it
+     * (operations.ts) — every serialized op carries `keyExpr`.
+     */
+    readonly keyExpr?: Readonly<Record<string, ExpressionNode>>;
+    /**
+     * @deprecated Phase 2 dual-emit (issue #289 P2-3): the pre-#289 `{param}`
+     * string-template key condition (`ARTICLE#{articleId}`), emitted ALONGSIDE
+     * {@link keyExpr} only during the migration so the runtimes' Expression-IR key
+     * reading can be proven byte-identical to the template render before the
+     * template path is deleted. Removed at the flip.
      */
-    readonly keyCondition: Readonly<Record<string, string>>;
+    readonly keyCondition?: Readonly<Record<string, string>>;
     readonly rangeCondition?: RangeConditionSpec;
     /** Projected fields (entity field names). */
     readonly projection: readonly string[];
@@ -412,6 +531,25 @@ interface SourceListSpec {
      * the query's select projects the attribute itself (it stays in the result).
      */
     readonly implicit?: boolean;
+    /**
+     * **SCP IR Phase 2 prep toward the universal Map node (issue #289 P2-5).** The
+     * shared IR expresses a fan-out as an SCP `map` node
+     * (`{ map: { over: <ref to the list>, as: "$el", component, ports } }`,
+     * scp-ir-architecture.md §5) — a single static node iterating a list Port. This
+     * `refs`/`sourceList` binding form is the DynamoDB-specific precursor of that
+     * Map. Phase 2 only PREPARES the migration (the full `map`-node emission +
+     * runtime expansion is Phase 3): {@link over} records the Expression-IR
+     * reference to the parent's list attribute the Map iterates
+     * (`{ ref: ["result", from] }`), and {@link as} records the per-element binding
+     * name (`"$<key>"`) the Phase-3 `map` body will reference. Both are ADDITIVE and
+     * DESCRIPTIVE only — the Phase-2 runtimes still execute the fan-out via
+     * {@link from}/{@link key} (unchanged behavior); Phase 3 lowers the body onto
+     * `over`/`as`. Carrying them now freezes the intended Map shape for review and
+     * lets a Phase-3 runtime resolve it without re-deriving.
+     */
+    readonly over?: ExpressionNode;
+    /** The Phase-3 Map element binding name (`"$<key>"`); see {@link over}. */
+    readonly as?: string;
 }
 /**
  * The **execution plan** for a multi-operation read (issue #70a). It is the
@@ -489,8 +627,15 @@ interface QuerySpec {
 /**
  * The Expression IR vocabulary version (behavior-contracts `expression-ir.md`
  * §9). A runtime handed an unknown `exprVersion` MUST fail closed.
+ *
+ * **SCP IR Phase 2 (#289, G6): bumped `1` → `2`.** graphddb now follows the
+ * behavior-contracts `exprVersion: 2` vocabulary (the v1→v2 change is the `obj`
+ * node `__proto__` `FORBIDDEN_KEY` fail-closed hardening — additive/backward
+ * compatible, `expression-ir.md` §9), closing the minor-version lag the migration
+ * plan flagged (§2 G6). Every embedded {@link ExpressionSpec} — guards, scpExpr
+ * conditions, and the new `keyExpr` key wiring — stamps `exprVersion: 2`.
  */
-declare const EXPR_VERSION: 1;
+declare const EXPR_VERSION: 2;
 /**
  * The closed operator vocabulary of Expression IR v1 (expression-ir.md §3).
  * An operator node is a **single-key** object — key = operator name, value =
@@ -892,6 +1037,25 @@ interface TransactionSpec {
      * DynamoDB ≤25 limit after expansion).
      */
     readonly maxItems?: number;
+    /**
+     * Marks a **BatchWriteItem** bulk form (issue #298): the spec is executed
+     * NON-ATOMICALLY through DynamoDB `BatchWriteItem` — chunked ≤25 per request
+     * with `UnprocessedItems` exponential retry, 1×WCU, no all-or-nothing
+     * guarantee — instead of one atomic `TransactWriteItems`. Synthesized only by
+     * the command-contract serializer for a `mode: 'batchWrite'` method (the
+     * 0.9.0 default for an unconditional put / delete): a single `forEach`-over-
+     * `items` write item whose element carries the FULL per-item payload (key +
+     * input fields), so each item binds its own values.
+     *
+     * Fail-closed on both sides: the emitter only stamps this on a spec whose
+     * every item is an **unconditional** `Put` / `Delete` `forEach` (DynamoDB's
+     * `BatchWriteItem` carries no `ConditionExpression` and no `Update`), and the
+     * runtimes' `executeTransaction` loud-rejects a marked spec (it must go
+     * through `executeBatchWrite`) while `executeBatchWrite` loud-rejects an
+     * unmarked one. Absent on every atomic transaction, so those serialize
+     * byte-identically to the pre-#298 spec.
+     */
+    readonly batchWrite?: true;
 }
 /**
  * Whether a contract is a public **read** (`'query'`) or **write** (`'command'`)
@@ -1084,6 +1248,20 @@ type CommandResolutionTarget =
  | {
     readonly mode: 'parallel';
     readonly operation: string;
+}
+/**
+ * A non-atomic **BatchWriteItem** bulk write with per-item values (issue
+ * #298; the 0.9.0 DEFAULT for an unconditional put / delete). References the
+ * synthesized `<Contract>__<method>__batchWrite` {@link TransactionSpec} in
+ * `transactions` (stamped {@link TransactionSpec.batchWrite}): a single
+ * `forEach`-over-`items` write whose array element carries the FULL per-item
+ * payload (key + input fields). The runtimes execute it through their
+ * `BatchWriteItem` machinery — any array size, chunked ≤25 per request with
+ * `UnprocessedItems` exponential retry, 1×WCU, no conditions, non-atomic.
+ */
+ | {
+    readonly mode: 'batchWrite';
+    readonly transaction: string;
 };
 /**
  * The serialized spec of one **command** contract method. Symmetric to
@@ -1170,6 +1348,50 @@ interface ContextSpec {
     /** Contract names owned by this context (sorted; `contracts` map keys). */
     readonly contracts: readonly string[];
 }
+/**
+ * The PORTABLE form of a read operation — what `operations.json` actually
+ * carries since SCP IR Phase 3 (#290 P3-5): the physical **root** op minus the
+ * proprietary relation wiring (`resultPath` / `sourceField` / `sourceList`).
+ * That wiring now exists ONLY inside the build pipeline ({@link OperationSpec},
+ * feeding the `components[]` lowering and the TS AOT prepared plan) and never
+ * reaches the portable IR — relation execution is expressed exclusively by the
+ * universal SCP component graph (`components[]`).
+ */
+type PortableOperationSpec = Omit<OperationSpec, 'resultPath' | 'sourceField' | 'sourceList'>;
+/**
+ * The PORTABLE form of a query (#290 P3-5). `operations` carries exactly ONE
+ * entry — the root physical op (the still-live single-op surfaces: the contract
+ * key-array point-batch reads its `keyExpr` / `projection`; `explain` renders
+ * it). Relation fan-out and staging live ONLY in `components[]`, so the old
+ * relation operations and the `executionPlan` are not emitted.
+ */
+interface PortableQuerySpec {
+    readonly params: Readonly<Record<string, ParamSpec>>;
+    /** Exactly one entry: the root physical operation. */
+    readonly operations: readonly PortableOperationSpec[];
+    /** See {@link QuerySpec.cardinality}. */
+    readonly cardinality?: 'one' | 'many';
+    /** See {@link QuerySpec.description}. */
+    readonly description?: string;
+}
+/**
+ * The PORTABLE form of a declarative transaction (#290 P3-5): only the input
+ * contract (`params`, read by every runtime's `validate_params` surface). The
+ * old templated item bodies (`items[]` with `forEach` / `{item.*}` templates)
+ * are not emitted — the write plan lives ONLY in the transaction's
+ * `components[]` entry, which the runtimes execute via `runBehavior`.
+ */
+interface PortableTransactionSpec {
+    readonly params: Readonly<Record<string, ParamSpec>>;
+    /**
+     * Marks the `BatchWriteItem` bulk form (issue #298 — see
+     * {@link TransactionSpec.batchWrite}). Portable ON PURPOSE: it is the
+     * runtimes' fail-closed dispatch signal (`executeBatchWrite` requires it,
+     * `executeTransaction` rejects it) and the codegen signal for the per-item
+     * `*BatchWrite` generated-method shape. Absent on every atomic transaction.
+     */
+    readonly batchWrite?: true;
+}
 interface OperationsDocument {
     /**
      * `1.1` unless the document actually contains an SCP Expression IR node (a
@@ -1177,10 +1399,18 @@ interface OperationsDocument {
      * (issue #261, conditional stamping — see {@link SPEC_VERSION_SCP}).
      */
     readonly version: SpecVersion;
-    readonly queries: Readonly<Record<string, QuerySpec>>;
+    /**
+     * Portable query specs (#290 P3-5): the root physical op + params only; the
+     * relation wiring lives in {@link components}.
+     */
+    readonly queries: Readonly<Record<string, PortableQuerySpec>>;
     readonly commands: Readonly<Record<string, CommandSpec>>;
-    /** Declarative transactions (issue #46). Absent in pre-#46 specs. */
-    readonly transactions?: Readonly<Record<string, TransactionSpec>>;
+    /**
+     * Declarative transactions (issue #46). Absent in pre-#46 specs. Since #290
+     * P3-5 only the params contract is emitted; the write plan lives in
+     * {@link components}.
+     */
+    readonly transactions?: Readonly<Record<string, PortableTransactionSpec>>;
     /**
      * The CQRS Contract layer (issue #59): contract name → {@link ContractSpec}.
      * Layered **on top of** the existing `queries` / `commands` / `transactions`
@@ -1195,6 +1425,18 @@ interface OperationsDocument {
      * foreign. **Absent** when no contexts are declared (backward compatibility).
      */
     readonly contexts?: Readonly<Record<string, ContextSpec>>;
+    /**
+     * The universal SCP **component-graph** (issue #290, Phase 3). The queries /
+     * transactions lifted into behavior-contracts `Component[]` (name /
+     * inputPorts / body / output / plan, `scp-ir-architecture.md` §5). Since the
+     * P3-5 flip this is the ONLY carrier of relation fan-out and transaction
+     * write plans in the portable IR — every spec-consumer runtime
+     * (py/php/rust/go) executes reads and transactions via `runBehavior` over
+     * this graph, and the typed-binding / docs generators reconstruct the result
+     * shape from it. **Absent** when the input defines no queries or
+     * transactions (backward compatible).
+     */
+    readonly components?: readonly Component[];
 }
 /** The full `{ manifest, operations }` bundle produced by the static planner. */
 interface BridgeBundle {
@@ -1202,4 +1444,4 @@ interface BridgeBundle {
     readonly operations: OperationsDocument;
 }
 
-export { type LiteralParam as $, type ManifestEntity as A, type BridgeBundle as B, type ContractSpec as C, type ManifestField as D, type ExpressionSpec as E, type FilterSpec as F, type ManifestFieldType as G, type ManifestGsi as H, type ManifestKey as I, type ManifestRelation as J, type ManifestTable as K, type OperationSpec as L, type Manifest as M, type QueryContractMethodSpec as N, type OperationsDocument as O, type ParamSpec as P, type QuerySpec as Q, type RangeConditionSpec as R, SPEC_VERSION as S, type TransactionSpec as T, type ReadOperationType as U, SPEC_VERSION_SCP as V, SPEC_VERSION_SUPPORTED as W, type TransactionItemSpec as X, type TransactionItemType as Y, type WhenSpec as Z, type WriteOperationType as _, type CommandSpec as a, type NumberParam as a0, type Param as a1, type ParamKind as a2, type StringParam as a3, param as a4, type ContextSpec as b, type ConditionSpec as c, type SpecVersion as d, type CommandContractMethodSpec as e, type CommandResolutionTarget as f, type ComposeSpec as g, type CompositionPlanSpec as h, type ContractCardinality as i, type ContractCommandResult as j, type ContractInputArity as k, type ContractKeySpec as l, type ContractKind as m, type ContractResolution as n, EXPR_VERSION as o, type ExecutionPlanSpec as p, type ExpressionArrNode as q, type ExpressionFloatNode as r, type ExpressionIntNode as s, type ExpressionNode as t, type ExpressionObjNode as u, type ExpressionOpNode as v, type ExpressionOperator as w, type ExpressionRefNode as x, type ExpressionRefOptNode as y, type ExpressionScalar as z };
+export { type WriteOperationType as $, type ManifestEntity as A, type BridgeBundle as B, type ContractSpec as C, type ManifestField as D, type ExpressionSpec as E, type FilterSpec as F, type ManifestFieldType as G, type ManifestGsi as H, type ManifestKey as I, type ManifestRelation as J, type ManifestTable as K, type OperationSpec as L, type Manifest as M, type QueryContractMethodSpec as N, type OperationsDocument as O, type ParamSpec as P, type QuerySpec as Q, type RangeConditionSpec as R, SPEC_VERSION_KEY_EXPR as S, type TransactionSpec as T, type ReadOperationType as U, SPEC_VERSION as V, SPEC_VERSION_SCP as W, SPEC_VERSION_SUPPORTED as X, type TransactionItemSpec as Y, type TransactionItemType as Z, type WhenSpec as _, type CommandSpec as a, type LiteralParam as a0, type MapParam as a1, type NumberParam as a2, type Param as a3, type ParamKind as a4, type StringParam as a5, param as a6, type ContextSpec as b, type ConditionSpec as c, type SpecVersion as d, type CommandContractMethodSpec as e, type CommandResolutionTarget as f, type ComposeSpec as g, type CompositionPlanSpec as h, type ContractCardinality as i, type ContractCommandResult as j, type ContractInputArity as k, type ContractKeySpec as l, type ContractKind as m, type ContractResolution as n, EXPR_VERSION as o, type ExecutionPlanSpec as p, type ExpressionArrNode as q, type ExpressionFloatNode as r, type ExpressionIntNode as s, type ExpressionNode as t, type ExpressionObjNode as u, type ExpressionOpNode as v, type ExpressionOperator as w, type ExpressionRefNode as x, type ExpressionRefOptNode as y, type ExpressionScalar as z };

package/docs/cqrs-contract.md

@@ -263,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
@@ -498,15 +544,20 @@ Definition DSL (`src/define/contract.ts`) — import the `graphddb` namespace
 
 ```ts
 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
 ```
 
 A query method may compose another query contract's method (cross-fragment refs
-via `$.alias.field`); a command descriptor composes its derived write ops and
-maintenance writes into one plan. These are declared inside the
-`publishQuery` / `publishCommand` map — there is no separate public `query()` /
-`mutation()` composite verb (removed in 0.8.0).
+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).
 
 Execution is the two `graphddb.*` verbs (`graphddb.query` / `graphddb.mutate`) —
 they route contract methods through the in-process runtime.