graphddb 0.8.1 → 0.9.1

package/dist/{types-2PMXEn5x.d.ts → types-CgXS-4Ox.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 =
@@ -576,7 +721,9 @@ type WriteOperationType = 'PutItem' | 'UpdateItem' | 'DeleteItem';
  * - `{ kind: 'attributeNotExists'; field }` → `attribute_not_exists(<field>)` — the
  *   named attribute must be absent (field-level uniqueness / first-write guard).
  * - `{ kind: 'equals'; fields }` → `#f = :v AND …` field equality (each value a
- *   `{param}` / literal template).
+ *   `{param}` string template or a typed literal — a `number` / `boolean` literal
+ *   is carried verbatim so it compares as `N` / `BOOL`, not a stringified `S`,
+ *   issue #299).
  * - `{ kind: 'expr'; declarative }` → the full declarative operator tree (issue
  *   #114-A): comparison (`gt`/`ge`/`lt`/`le`/`ne`), `between`, `in`,
  *   `begins_with`/`contains`/`notContains`, `attributeType`, and the logical
@@ -598,7 +745,7 @@ type ConditionSpec = {
     readonly field: string;
 } | {
     readonly kind: 'equals';
-    readonly fields: Readonly<Record<string, string>>;
+    readonly fields: Readonly<Record<string, TransactionValueLeaf>>;
 } | {
     readonly kind: 'expr';
     readonly declarative: unknown;
@@ -647,10 +794,33 @@ interface CommandSpec {
      * Absent for `PutItem` (the whole item is built from `item`).
      */
     readonly keyCondition?: Readonly<Record<string, string>>;
-    /** The full item template for `PutItem` (field name → template / literal). */
-    readonly item?: Readonly<Record<string, string>>;
-    /** Field-level changes for `UpdateItem` (field name → template / literal). */
-    readonly changes?: Readonly<Record<string, string>>;
+    /**
+     * The full item template for `PutItem` (field name → template / typed literal).
+     * A string value is a template ({@link TransactionValueLeaf}); a `number` /
+     * `boolean` is a typed literal carried verbatim so it lands as `N` / `BOOL`
+     * rather than a stringified `S` (issue #299, mirroring the transaction #245).
+     */
+    readonly item?: Readonly<Record<string, TransactionValueLeaf>>;
+    /**
+     * Field-level changes for `UpdateItem` (field name → template / typed literal).
+     * A string value is a template; a `number` / `boolean` is a typed literal
+     * carried verbatim (issue #299).
+     */
+    readonly changes?: Readonly<Record<string, TransactionValueLeaf>>;
+    /**
+     * Atomic-`ADD` deltas for a standalone `UpdateItem` (issue #301): field name →
+     * template / typed literal. Distinct from {@link changes} (a SET): each entry emits
+     * `ADD #field :delta` — an atomic, read-free, concurrency-safe increment (the
+     * aggregate-tree `mark`'s `version++`). The delta rides as a `{token}` template
+     * resolved from a caller `param.number()`. When present together with
+     * {@link condition}, the ADD is UNCONDITIONAL and the runtime executes a transparent
+     * TWO-STAGE write: `ADD + SET` under the condition (1 write); on
+     * `ConditionalCheckFailedException`, a fallback `ADD`-only write (no SET, no
+     * condition — the counter still increments). read=0, retry=0. Absent unless the
+     * command declared `add`, so a command with no `add` serializes byte-identically to
+     * the pre-#301 spec.
+     */
+    readonly add?: Readonly<Record<string, TransactionValueLeaf>>;
     /** Optional write condition (subset). */
     readonly condition?: ConditionSpec;
     /**
@@ -878,8 +1048,12 @@ interface MaintainItemSpec {
 interface MaintainCounterSpec {
     /** The target attribute the counter increments (e.g. `postCount`). */
     readonly attribute: string;
-    /** The signed `ADD` delta as a numeric template string (`"1"` / `"-1"`). */
-    readonly delta: string;
+    /**
+     * The signed `ADD` delta. A compile-time constant delta is carried as a typed
+     * `number` (`1` / `-1`) so it marshals as `N` (issue #299); a `{param}` numeric
+     * template rides as a string. (Pre-#299 a constant was stringified to `"1"`.)
+     */
+    readonly delta: TransactionValueLeaf;
 }
 /** A declarative transaction definition's full execution spec. */
 interface TransactionSpec {
@@ -892,6 +1066,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 +1277,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 +1377,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 +1428,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 +1454,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 +1473,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/dist/{types-DW__-Icc.d.ts → types-nk5okD7d.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-DZtjAQDh.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-CWytoEaE.js';
 
 type DynamoType = 'S' | 'N' | 'BOOL' | 'B' | 'SS' | 'NS' | 'L' | 'M';
 interface FieldOptions {

package/docs/python-bridge.md

@@ -276,63 +276,46 @@ Every operation carries a `params` map of `ParamSpec`:
 
 #### Queries
 
-A `QuerySpec` has `params`, an ordered `operations` array, and a `cardinality`
-(`"one"` or `"many"`). Each `OperationSpec`:
+A `QuerySpec` has `params`, an `operations` array carrying exactly **one**
+entry — the root physical op — and a `cardinality` (`"one"` or `"many"`).
+Since SCP IR Phase 3 (#290 P3-5) relation fan-out is NOT part of `queries`:
+it lives exclusively in the universal `components[]` graph (below). The root
+`OperationSpec`:
 
 ```jsonc
 {
   "type": "Query",                // "Query" | "GetItem" | "BatchGetItem"
   "tableName": "UserPermissions",
   "indexName": "GSI1",            // omitted for base-table access
-  "keyCondition": { "GSI1PK": "EMAIL#{email}", "GSI1SK": "PROFILE" },
-  "rangeCondition": { "operator": "begins_with", "key": "SK", "value": "USER#" },
   "projection": ["email", "name", "status", "userId"],
+  "keyExpr": { "GSI1PK": { "concat": ["EMAIL#", { "ref": ["input", "email"] }] },
+               "GSI1SK": "PROFILE" },
+  "rangeCondition": { "operator": "begins_with", "key": "SK", "valueExpr": "USER#" },
   "limit": 20,
-  "filter": { /* declarative FilterExpression */ },
-  "resultPath": "$",              // "$" or e.g. "$.groups.items"
-  "sourceField": "userId"         // present on relation child operations
+  "filter": { /* declarative FilterExpression */ }
 }
 ```
 
 The operation type is chosen by the planner from the key shape: a full PK+SK is
 a `GetItem`; a partial key with a contiguous sort-key prefix is a `Query` with a
 `begins_with` `rangeCondition`; a partition-key-only access is a `Query`. The
-`projection` is the set of scalar fields selected `true`.
-
-#### Template placeholders
-
-Key, item, and change templates use two placeholder forms plus literals:
-
-- `{paramName}` — bound from caller-supplied parameters.
-- `{result.sourceField}` — bound from a prior operation's result item(s), used to
-  chain relation operations.
-- Literal text (e.g. `PROFILE`, `USER#`) is emitted verbatim.
-
-The planner derives every template by **symbolic evaluation** of the model's key
-mapping (it evaluates the key function over symbolic field markers rather than
-concrete values), producing `USER#{userId}`-style templates directly from the
-metadata.
-
-#### Relation chaining and execution plan
-
-A relation traversal is expressed as additional `OperationSpec` nodes in the same
-query's `operations` array. Each child references its parent through
-`{result.sourceField}` in its `keyCondition`, and its `resultPath` nests the
-result under the parent (`$.groups.items` for a `hasMany`, `$.account` for a
-`belongsTo` / `hasOne`). `belongsTo` / `hasOne` children are emitted as
-`BatchGetItem`; `hasMany` children as `Query`.
-
-A query may carry an `executionPlan`:
-
-```jsonc
-{ "groups": [[1, 2], [3]], "concurrency": 16 }
-```
-
-`groups` is an ordered list of stages of operation indices (the root, index 0,
-is implicit and runs first). Operations within a stage are mutually independent
-and may run concurrently; later stages may read `{result.*}` produced by earlier
-ones. The same `deriveExecutionPlan` routine is used by the generator and by the
-TypeScript runtime, so the staging cannot drift between them.
+`projection` is the set of scalar fields selected `true`. The key wiring is
+portable Expression IR (`keyExpr` / `valueExpr`, #289), derived by **symbolic
+evaluation** of the model's key mapping. The runtime executes the root op via
+its `components[]` entry; the emitted root op remains the validation /
+`explain` / contract point-batch surface.
+
+#### Relation chaining and staging (`components[]`)
+
+A relation traversal is expressed as the query's entry in the top-level
+`components[]` — the universal SCP component graph (behavior-contracts
+`Component`): the root op becomes a `componentRef` body node, each relation a
+`componentRef` / `map` node whose id is the dotted result path
+(`groups.items`, `groups.items.group`), wired to its producer via `parent`
+and executed by `run_behavior` with the DynamoDB catalog handlers. A
+multi-node component carries a `plan` (`{ "groups": [[0], [1, 2]],
+"concurrency": 16 }`) staging mutually-independent nodes; the shared executor
+honors it.
 
 #### Commands
 
@@ -581,8 +564,9 @@ resuming with a cursor for the wrong key is rejected.
 
 ### 7.6 Relations, Batch, and Concurrency
 
-Relation children are resolved against the parents produced by earlier
-operations and merged into the result at their `resultPath`:
+Relation nodes of the query's `components[]` entry are resolved against the
+parents produced by earlier nodes and folded into the result at their node id
+path:
 
 - **`belongsTo` / `hasOne`** — source values from all parents are deduplicated
   and fetched in a single `BatchGetItem`, then matched back to each parent (a
@@ -592,10 +576,10 @@ operations and merged into the result at their `resultPath`:
 
 `BatchGetItem` requests are chunked at 100 keys, deduplicated, and retried on
 `UnprocessedKeys` with capped exponential backoff (up to 10 attempts).
-`BatchWriteItem` is chunked at 25 with the same `UnprocessedItems` retry. Stages
-of mutually independent operations (from `executionPlan`) run concurrently on a
-bounded thread pool (default 16 in flight); boto3 releases the GIL during
-network I/O, so the overlap is real. Result order is preserved.
+`BatchWriteItem` is chunked at 25 with the same `UnprocessedItems` retry. Node
+staging follows the component's `plan` inside the shared `run_behavior`
+executor (deterministic in-order reference semantics). Result order is
+preserved.
 
 ### 7.7 Transactions