graphddb 0.8.1 → 0.9.0

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/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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphddb",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Graph data modeling on DynamoDB with adjacency list pattern",
   "type": "module",
   "main": "dist/index.js",
@@ -54,6 +54,9 @@
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "gen:py:fixtures": "tsx src/cli.ts generate python --entry python/tests/fixtures/models.ts --transactions python/tests/fixtures/definitions.ts --contracts python/tests/fixtures/definitions.ts --out python/tests/fixtures/generated",
     "gen:py:fixtures:multi": "tsx src/cli.ts generate python --entry python/tests/fixtures/models.ts --contracts python/tests/fixtures/definitions_multi.ts --out python/tests/fixtures/generated_multi",
+    "gen:py:behaviors:fixture": "tsx src/cli.ts generate behaviors --lang python --entry python/tests/fixtures/models.ts --transactions python/tests/fixtures/definitions.ts --contracts python/tests/fixtures/definitions.ts --out python/tests/fixtures/generated_behaviors",
+    "gen:rust:behaviors:fixture": "tsx src/cli.ts generate behaviors --lang rust --entry python/tests/fixtures/models.ts --transactions python/tests/fixtures/definitions.ts --contracts python/tests/fixtures/definitions.ts --out rust/graphddb_runtime/tests/generated_behaviors",
+    "gen:php:behaviors:fixture": "tsx src/cli.ts generate behaviors --lang php --entry python/tests/fixtures/models.ts --transactions python/tests/fixtures/definitions.ts --contracts python/tests/fixtures/definitions.ts --out php/tests/fixtures/generated_behaviors",
     "test:py": "python3 -m pytest python/tests -m \"not integration\"",
     "test:py:integration": "python3 -m pytest python/tests -m integration",
     "test:conformance": "tsx conformance/run.ts",
@@ -71,7 +74,9 @@
     "embedoc:build": "embedoc build",
     "embedoc:watch": "embedoc watch",
     "embedoc:generate": "embedoc generate --all",
+    "prepare": "git config core.hooksPath .githooks 2>/dev/null || true",
     "embedoc:check": "node scripts/embedoc-drift-check.mjs",
+    "deps:check": "node scripts/check-no-local-deps.mjs",
     "vendor:bc-php": "node scripts/vendor-behavior-contracts-php.mjs",
     "vendor:bc-php:check": "node scripts/vendor-behavior-contracts-php.mjs --check",
     "vendor:bc-vectors": "node scripts/vendor-behavior-contracts-vectors.mjs",
@@ -80,6 +85,9 @@
     "bench:crosslang:integration": "tsx benchmark/crosslang/integration.ts",
     "bench:crosslang:test": "vitest run benchmark/crosslang/__tests__"
   },
+  "size-limit-notes": {
+    "graphddb/spec (build-time)": "#290 transitional loop CLOSED at the final sub-pass (P3-5): the components[] emitter is now the PERMANENT (and only) portable carrier of relation fan-out + transaction write plans, so the sub-pass-1 dual-emit bump does not fully revert — the old operation/transaction builders remain as the emitter INTERNAL lowering input (they also feed the TS declarative executor and the AOT prepared plan); only their serialization into operations.json was removed, replaced by the small portable projection. Measured 22.38->22.51 KB across the flip (all first-party src/spec, zero new dependencies, all runtime bundles flat); budget stays 23 KB as the steady-state ceiling. Any future growth must be traced per the size-limit-gate discipline, never blanket-raised. #297 SP1+SP2 traced growth: 22.51->25.02 KB (+2.51 brotli), two traced components — (1) first-party src/spec/catalog.ts: the bc-typed GRAPHDDB_CATALOG + the SP1c emitter validation + the SP2 CQRS effect-derivation invariant, both wired into buildOperations so a catalog/effect mismatch is a BUILD error (load-bearing by design, must ship in this bundle); (2) behavior-contracts/dist/authoring.js partial inclusion, 5.66 KB minified (esbuild metafile-traced): the SP2-mandated classifyBehaviorEffect/referencedComponents live in bc's authoring module, whose top-level `export const add = binOp('add')`-style const-initializer calls esbuild cannot prove pure — bc 0.1.6 ships no sideEffects:false / __PURE__ annotations, so the two tiny helpers drag the authoring-DSL scaffolding along. NOT a new dependency (behavior-contracts already supplied this bundle's contract types); an upstream bc annotation fix reclaims (2), and the ceiling must be re-tightened when it lands. New ceiling 25.5 KB keeps the same ~0.5 KB headroom discipline as the previous 23 KB ceiling. #297 SP3+SP4 traced growth: 25.04->25.26 KB (+0.22 brotli), all first-party src/spec — the SP4 inversion (deriveComponentEffects + assertPublishSplitMatchesDerived with method-naming errors, replacing the SP2 symmetric assertion) plus the additive contractInputs.behaviors registration loop in buildOperations (rename + collision check + re-validation); the publishBehaviors authoring machinery itself is type-only from this bundle (src/define/behaviors.ts never enters dist/spec). Runtime-core bucket flat (39.08->39.07: the eager graphddb.publishBehaviors member tree-shakes out of a { DDBModel }-only consumer — bc 0.1.7 ships sideEffects:false); import-* bucket 47.8->55.4 (+7.6: bc compileBehaviors recorder/scanner + src/define/behaviors.ts + src/executor/behavior-exec.ts, all reachable only via publishBehaviors / behaviorComponents / behavior-exec). #297 SP5 traced growth: 25.26->28.84 KB (+3.58 brotli), one traced component — behavior-contracts/dist/builder.js (11.69 KB minified) + its guard.js dependency (3.51 KB minified), esbuild metafile-traced: SP5 moved components[] IR assembly/validation/canonicalization OUT of src/spec/components.ts and INTO bc's data-registration builder (buildComponentDefinition, bc#26 — the owner-decided split: extraction stays graphddb, IR shape is bc's), and the builder internally applies assertPortableComponentGraph (guard.js) as its fail-closed self-check, so both are load-bearing in the spec build path BY DESIGN (this is the seam the sub-pass exists to create, not a dependency leak). First-party src/spec shrank slightly (the hand-assembled Component return + inline plan emission were replaced by the registration call). New ceiling 29.3 KB keeps the same ~0.5 KB headroom discipline."
+  },
   "size-limit": [
     {
       "name": "runtime core (DDBModel + authoring)",
@@ -102,7 +110,7 @@
       "name": "graphddb/spec (build-time)",
       "path": "dist/spec/index.js",
       "import": "{ buildBridgeBundle }",
-      "limit": "20 KB"
+      "limit": "29.3 KB"
     },
     {
       "name": "graphddb/internal (AOT prepared-plan loader)",
@@ -150,7 +158,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "behavior-contracts": "0.1.3",
+    "behavior-contracts": "0.2.0",
     "commander": "^15.0.0",
     "handlebars": "^4.7.9"
   },