graphddb 0.8.0 → 0.9.0

package/dist/{key-DR7_lpyk.d.ts → key-Dne-a20Q.d.ts}

@@ -1,4 +1,4 @@
-import { a1 as Param, E as ExpressionSpec, a2 as ParamKind, T as TransactionSpec, X as TransactionItemSpec } from './types-2PMXEn5x.js';
+import { a3 as Param, E as ExpressionSpec, a4 as ParamKind, T as TransactionSpec, Y as TransactionItemSpec } from './types-CfxzTEFL.js';
 
 /**
  * CDC emulator types (issue #72). These types are **cdc-module-owned**; core
@@ -725,6 +725,22 @@ interface DeleteInput {
  * with `maxAttempts: 1` so the library is the single source of truth for retry
  * (documented at `graphddb.config.client` and in the README). The library does NOT
  * silently mutate a user-provided client.
+ *
+ * NOTE on the SCP Error Policy Kind (issue #292 / G9, bc `scp-error.md`):
+ * everything in this module is **Tuning** (max attempts / delay / backoff /
+ * jitter / `isRetryable`) — Runtime-owned, IR-external, Conformance-external.
+ * The op-level Policy **Kind** (`fail`/`retry`/`continue`) is a separate,
+ * IR-carried control-flow intent interpreted ONLY by behavior-contracts'
+ * `runPlan` (graphddb adds no Kind interpretation of its own; the runtimes
+ * convert a DynamoDB failure to the shared `ExecOutcome {error}` at the
+ * handler boundary and let `runPlan` decide). No double-retry arises today:
+ * this executor layer belongs to the TS live executor, which does not run
+ * through `runBehavior`, and the 4 spec-consumer runtimes' handlers issue SDK
+ * calls without a Kind-driven retry loop (bc's reference `runPlan` treats a
+ * persistent `retry`-Kind failure as exhausted, converging on the `fail`
+ * propagation). If a runtime later implements a real `retry`-Kind loop, this
+ * Tuning (and the SDK's own `maxAttempts`) must be treated as the INNER
+ * mechanism of a single logical attempt — never stacked as a second policy.
  */
 /** The single-op kind a retry is wrapping — surfaced to {@link RetryPolicy.onRetry}. */
 type RetryOperationKind = 'get' | 'query' | 'batchGet' | 'put' | 'update' | 'delete' | 'batchWrite' | 'transactWrite';
@@ -2398,6 +2414,32 @@ interface MutationEntityRef {
     /** The source path, e.g. `$.entity[0].postId` (documentary; surfaces in errors). */
     readonly path: string;
 }
+/**
+ * The placeholder proxy handed to a mutation body as `$`. In the descriptor-map
+ * authoring form (issue #108) a top-level read `$.<x>` is **ambiguous** until used:
+ *
+ *  - `$.role` placed at a `key` / `input` leaf is an **input-field reference**
+ *    (a {@link MutationInputRef}, token `{role}`) — bound from the command input;
+ *  - `$.membership.role` is a **cross-fragment reference** — the `role` field
+ *    written by the fragment named `membership` (an alias). It mints an
+ *    {@link AliasFieldRef}, which the {@link mutation} assembler rewrites into the
+ *    legacy `$.entity[<index>].<field>` string the compiler resolves (the alias →
+ *    declaration-order index is known once every alias key is seen).
+ *
+ * So each top-level read returns a value that is **both** a faithful
+ * {@link MutationInputRef} (when used directly as a leaf) and supports one further
+ * `.<field>` access (when used as an alias root). Any other access / coercion
+ * throws — the binding stays declarative (only a direct `$.field` / `$.alias.field`
+ * reference or a literal is representable, never a transform).
+ *
+ * **Input Port 統一 (issue #264)**: this proxy is one of the three authoring
+ * spellings of the SAME Input Port reference model — see the unification note
+ * on {@link import('./transaction.js').ParamProxy} (`defineTransaction`'s
+ * `p.*` proxy is the model; `{<field>}` templates and `{ref:["input","<field>"]}`
+ * expression refs are the two serialized mirrors of one declared-input
+ * namespace). Behavior here is unchanged in 0.7.x (interop kept).
+ */
+type MutationInputProxy = Record<string, MutationInputRef>;
 declare const FRAGMENT_BRAND: unique symbol;
 /**
  * The per-field input binding of a fragment: model field name → a faithful
@@ -2406,6 +2448,14 @@ declare const FRAGMENT_BRAND: unique symbol;
  * field they key, never a transform.
  */
 type FragmentInput = Readonly<Record<string, MutationInputRef | string | number | boolean | Date | null>>;
+/**
+ * A descriptor `key` / `input` value as authored in the descriptor-map form
+ * (issue #108): a `$.field` input reference, a `$.alias.field` cross-fragment
+ * reference (an opaque alias-field ref the assembler rewrites), or a literal.
+ * Structurally `unknown` at the leaf because the alias-field ref is internal; the
+ * assembler validates every leaf via {@link assertFaithfulInput}.
+ */
+type DescriptorBinding = Readonly<Record<string, unknown>>;
 /** A concrete scalar admissible at a condition operand leaf. */
 type ConditionScalar = MutationInputRef | string | number | boolean | Date | null;
 /** A declarative operator object on one condition field (the #114-A subset). */
@@ -2488,6 +2538,68 @@ interface MutationFragment {
  * `m.create(() => Model, …)` recorder required.
  */
 type ModelRef = ModelStatic<DDBModel> | (new (...args: unknown[]) => unknown) | (() => ModelStatic<DDBModel> | (new (...args: unknown[]) => unknown));
+/**
+ * One **write descriptor** in the descriptor-map authoring form (issue #108) —
+ * the declarative twin of an in-process `DDBModel.mutate` entry (#101). The intent
+ * key (`create` / `update` / `remove`) is the **discriminator** and carries the
+ * target {@link ModelRef} (direct or thunk). The remaining fields are declarative
+ * bindings (`$.field` references or literals):
+ *
+ *  - `key` — the target row's primary-key binding (identifies the row);
+ *  - `input` — the non-key field binding (the body / changed fields). Optional for
+ *    a `remove` (a delete writes no fields);
+ *  - `condition` — an optional declarative write gate (issue #242, Phase 2). It is
+ *    the #114-A condition subset (bare equality, operator objects `{ gt }` / `{ in }`
+ *    / `{ between }` / …, and `and` / `or` / `not` groups) whose operand leaves are
+ *    `$.field` input references or literals. The declaration-DSL compiler **consumes**
+ *    it: each `$.field` leaf becomes a {@link import('./contract.js').ContractParamRef}
+ *    and the tree is attached to the compiled base op's `condition`, so it is
+ *    serialized (into the operation spec) and evaluated at runtime exactly as a #101
+ *    public write descriptor's condition is (single-op, in-process
+ *    transaction, and the Python bridge). A conditioned `update` / `remove` therefore
+ *    fails a CAS-style write when the gate does not hold, rather than silently
+ *    committing;
+ *  - `result` — an optional read-back projection `{ select, options? }` (likewise
+ *    accepted for authoring parity; the public read-back projection of a
+ *    `command(...).plan(...)` method is still declared on `command({ select })`).
+ *
+ * Exactly one intent key must be present.
+ */
+interface WriteDescriptor {
+    readonly create?: ModelRef;
+    readonly update?: ModelRef;
+    readonly remove?: ModelRef;
+    /**
+     * `upsert` — a `PutItem` with **no** `attribute_not_exists(PK)` guard (an
+     * unconditional overwrite; the semantics of the removed `definePut`). Unlike
+     * `create` (which always guards against clobbering an existing row), an `upsert`
+     * writes whether or not the row exists; an author-supplied `condition` is honored
+     * verbatim (never ANDed with a `notExists` guard).
+     */
+    readonly upsert?: ModelRef;
+    /** The target row's primary-key binding (`{ field: $.field | literal }`). */
+    readonly key: DescriptorBinding;
+    /** The non-key field binding; optional (a `remove` writes no fields). */
+    readonly input?: DescriptorBinding;
+    /**
+     * Optional declarative write gate — the #114-A condition subset (issue #242,
+     * Phase 2). Compiled, serialized, and evaluated at runtime; see the interface doc.
+     */
+    readonly condition?: FragmentCondition;
+    /** Optional read-back projection `{ select, options? }` (accepted for #101 parity). */
+    readonly result?: {
+        readonly select?: unknown;
+        readonly options?: unknown;
+    };
+    /**
+     * Optional custom save contract to adopt (the **whole** {@link
+     * EntityWritesDefinition}). Omit to default to the target model's own `writes`.
+     * Per the `use:` rule this is never a single lifecycle — the intent picks it.
+     */
+    readonly use?: EntityWritesDefinition;
+}
+/** The descriptor map a {@link mutation} body returns: alias → {@link WriteDescriptor}. */
+type MutationDescriptorMap = Record<string, WriteDescriptor>;
 declare const COMMAND_PLAN_BRAND: unique symbol;
 /**
  * The recorded **CommandPlan** — a mutation's IR (proposal §3). It carries the
@@ -2503,6 +2615,14 @@ interface CommandPlan {
     /** The declared write fragments, in declaration order (the mutation IR). */
     readonly fragments: readonly MutationFragment[];
 }
+/**
+ * The body of a {@link mutation} in the descriptor-map authoring form (issue #108):
+ * `$ => ({ alias: descriptor, … })`. It receives the placeholder proxy `$` and
+ * returns an **alias → {@link WriteDescriptor}** map. The map's **insertion order**
+ * is the fragments' declaration (execution) order, and each alias is the name a
+ * later descriptor's `$.alias.field` cross-fragment reference resolves against.
+ */
+type MutationBody = ($: MutationInputProxy) => MutationDescriptorMap;
 
 /**
  * Declarative transaction definition DSL (issue #46, Python-bridge Phase 4).
@@ -3260,9 +3380,10 @@ type ParamLeaf<V> = [V] extends [StringLike] ? V | string | Param<string> : V |
  * covariance still admits a single-member subset placeholder, while a value outside
  * the union / a wider placeholder / a wrong scalar kind stays a type error.
  */
-type Parameterize<K> = [Exclude<K, Nullish>] extends [ScalarLeaf] ? [Exclude<K, Nullish>] extends [never] ? K : ParamLeaf<Exclude<K, Nullish>> | Extract<K, Nullish> : K extends object ? {
+type Parameterize<K> = [Exclude<K, Nullish>] extends [ScalarLeaf] ? [Exclude<K, Nullish>] extends [never] ? K : ParamLeaf<Exclude<K, Nullish>> | Extract<K, Nullish> : K extends object ? // An object-typed leaf (a `@map` / `@embedded` field) additionally accepts a
+{
     [P in keyof K]: Parameterize<K[P]>;
-} : K;
+} | Param<K> : K;
 /** Union of all keys across every member of a (possibly union) `Real` type. */
 type KnownKeyOf<Real> = Real extends object ? keyof Real : never;
 /** The value type of key `P` across the members of a (possibly union) `Real`, non-nullable. */
@@ -3391,7 +3512,13 @@ type WriteDescriptorResultOf<D> = D extends {
         readonly select: infer S;
     };
 } ? S extends Record<string, unknown> ? Readonly<Record<Extract<keyof S, string>, unknown>> | null : void : void;
-/** A write descriptor's contract Key (from its `key` record). */
+/**
+ * A write descriptor's contract Key (from its `key` record). A #293 PUBLIC composite
+ * descriptor (`{ writes, input }`) has no single top-level `key` — it is a
+ * multi-entity write with no single primary Key — so it falls through to `unknown`,
+ * exactly as a bare `mutation()` plan / SCP transaction body does; its public params
+ * are still precise via {@link DescriptorParamsOf} (the separate `input` schema).
+ */
 type WriteDescriptorKeyOf<D> = D extends {
     readonly key: infer K;
 } ? KeyOf<K> : unknown;
@@ -3414,7 +3541,7 @@ type ResolvedReadDescriptors<M extends ReadDescriptorMap> = QueryModelContract<M
  * {@link CommandPlan}, or an SCP native-syntax `defineScpTransaction(...)`
  * multi-write body ({@link TransactionDefinition}, Phase 4 S1 / issue #278).
  */
-type WriteDescriptorMap = Record<string, PublicWriteDescriptor | PublicComposeDescriptor | CommandPlan | TransactionDefinition>;
+type WriteDescriptorMap = Record<string, PublicWriteDescriptor | PublicCompositeDescriptor | PublicComposeDescriptor | CommandPlan | TransactionDefinition>;
 /** Resolve a write-descriptor map to its {@link CommandModelContract}. */
 type ResolvedWriteDescriptors<M extends WriteDescriptorMap> = CommandModelContract<M[keyof M] extends infer D ? WriteDescriptorKeyOf<D> : unknown, {
     readonly [K in keyof M]: CommandMethodSpec<WriteDescriptorKeyOf<M[K]>, DescriptorParamsOf<M[K]>, WriteDescriptorResultOf<M[K]>>;
@@ -3493,11 +3620,33 @@ interface MutateAuthoringOptions {
  *   `publishCommand`'s SCP-body branch — declare a mode).
  * - `mutate(plan, { mode })` → a {@link PublicComposeDescriptor} (`{ command,
  *   mode }`), the closure-free composite form.
+ * - `mutate(compositeDescriptor, { mode })` → the same PUBLIC composite descriptor
+ *   (`{ writes, input?, result? }`, issue #293) with `mode` stamped — the
+ *   import-free composite form usable directly as a `publishCommand` method value.
  */
 declare function mutate(body: TransactionDefinition, options?: MutateAuthoringOptions): TransactionDefinition;
 declare function mutate(body: CommandPlan, options?: MutateAuthoringOptions): PublicComposeDescriptor;
-/** The per-call execution mode of a command method (#101): replaces `batch`. */
-type CommandMode = 'transaction' | 'parallel';
+declare function mutate(body: PublicCompositeDescriptor, options?: MutateAuthoringOptions): PublicCompositeDescriptor;
+/**
+ * The per-call execution mode of a command method (#101): replaces `batch`.
+ *
+ * `'batchWrite'` (issue #298) is the DynamoDB `BatchWriteItem` bulk form —
+ * non-atomic, condition-free, any array size chunked ≤25 per request with
+ * `UnprocessedItems` retry, 1×WCU — the semantics the runtime has always
+ * implemented ({@link import('../runtime/command-runtime.js')}'s
+ * `executeBatchWrite` machinery); #298 makes it declarable/reachable from the
+ * public contract surface. It is only legal for an **unconditional** put /
+ * delete (`upsert` / condition-free `remove`) — `BatchWriteItem` physically
+ * carries no `ConditionExpression` and no `Update`, so a conditional / create
+ * (implicit `notExists` guard) / update / derived-effect method loud-rejects it
+ * at build time.
+ *
+ * **0.9.0 default flip ("bulk is the base case")**: an eligible method that
+ * declares NO mode now defaults to `'batchWrite'` (previously `'transaction'`).
+ * Declare `mode: 'transaction'` explicitly to keep the atomic
+ * `TransactWriteItems` bulk form.
+ */
+type CommandMode = 'transaction' | 'parallel' | 'batchWrite';
 /** A public **read** descriptor (issue #101): `{ query | list: Model, key, select, options? }`. */
 interface PublicReadDescriptor {
     readonly query?: ModelRef;
@@ -3567,6 +3716,54 @@ interface PublicComposeDescriptor {
      */
     readonly description?: string;
 }
+/**
+ * A public **composite mutation** descriptor (issue #293) — the PUBLIC, closure-free
+ * authoring form for a multi-entity atomic (or non-atomic) write, needing **no**
+ * `mutation(...)` / `defineScpTransaction(...)` import. It carries a `writes` body
+ * (`$ => ({ alias: { create|update|remove|upsert: Model, key, input?, condition? } })`
+ * — the same mutation body the internal `mutation()` builder consumes), a **separate**
+ * `input` schema (`{ field: param.* }`) that names the public input fields the `$`
+ * proxy in the body references, an optional read-back `result.select`, and an optional
+ * execution `mode`.
+ *
+ * `publishCommand` compiles the `writes` body internally via the retained (internal)
+ * `mutation()` builder, then routes the resulting {@link CommandPlan} through the SAME
+ * `buildPlannedCommandMethod` path a bare `mutation()` plan / a
+ * {@link PublicComposeDescriptor} takes. A **single-alias** `writes` body is one write;
+ * a **multi-alias** body is an atomic composite (promoted to one
+ * `TransactWriteItems` by DynamoDB necessity — the existing promotion path), so its
+ * wire is byte-identical to authoring the same composite via the internal `mutation()`.
+ *
+ * The `input` schema is the public param declaration: its `param.*` leaves drive the
+ * generated typed binding's input struct (and the TS-level `params` type). It exists
+ * separately from the body (the owner-final #293 decision) so the mutation body stays a
+ * pure write declaration — options (input schema / read-back) are specified alongside it,
+ * not baked into it.
+ */
+interface PublicCompositeDescriptor {
+    /**
+     * The mutation body: `$ => ({ alias: writeDescriptor, … })`. Single alias ⇒ one
+     * write; multiple aliases ⇒ an atomic composite. The `$` proxy's fields are the
+     * public input fields declared in {@link input}.
+     */
+    readonly writes: MutationBody;
+    /**
+     * The public input schema: `{ field: param.* }`. Names (and types) the input fields
+     * the `writes` body's `$` proxy references. Optional (a body may bind only literals),
+     * though a composite normally declares at least the key params.
+     */
+    readonly input?: Readonly<Record<string, unknown>>;
+    readonly result?: {
+        readonly select?: Readonly<Record<string, boolean>>;
+        readonly options?: unknown;
+    };
+    readonly mode?: CommandMode;
+    /**
+     * Optional human-readable description of the composite write use case (issue #154).
+     * Pure documentation — propagated to the serialized command method spec.
+     */
+    readonly description?: string;
+}
 
 /**
  * Maintenance graph builder (Epic #118 issue #124 — the RFC B-案 core).

package/dist/linter/index.d.ts

@@ -1,8 +1,9 @@
-import { L as Linter, a as LintRule } from '../linter-C-vypgut.js';
-export { b as LintResult } from '../linter-C-vypgut.js';
-import '../types-BXLzIcQD.js';
-import '../key-DR7_lpyk.js';
-import '../types-2PMXEn5x.js';
+import { L as Linter, a as LintRule } from '../linter-Cr1Hnw7n.js';
+export { b as LintResult } from '../linter-Cr1Hnw7n.js';
+import '../types-BnFsTZwl.js';
+import '../key-Dne-a20Q.js';
+import '../types-CfxzTEFL.js';
+import 'behavior-contracts';
 
 /**
  * Creates a Linter pre-loaded with rules safe for Entity registration.

package/dist/{linter-C-vypgut.d.ts → linter-Cr1Hnw7n.d.ts}

@@ -1,4 +1,4 @@
-import { E as EntityMetadata } from './types-BXLzIcQD.js';
+import { E as EntityMetadata } from './types-BnFsTZwl.js';
 
 declare class MetadataRegistry {
     private static store;

package/dist/{prepared-artifact-BpPgkXEo.d.ts → prepared-artifact-BXkARxwO.d.ts}

@@ -1,6 +1,6 @@
-import { E as EntityMetadata } from './types-BXLzIcQD.js';
-import { C as ContractSpec, Q as QuerySpec, a as CommandSpec, T as TransactionSpec, b as ContextSpec, S as SPEC_VERSION, P as ParamSpec } from './types-2PMXEn5x.js';
-import { Q as QueryModelContract, k as QueryMethodSpec, l as CommandModelContract, m as CommandMethodSpec } from './key-DR7_lpyk.js';
+import { E as EntityMetadata } from './types-BnFsTZwl.js';
+import { C as ContractSpec, Q as QuerySpec, a as CommandSpec, T as TransactionSpec, b as ContextSpec, S as SPEC_VERSION_KEY_EXPR, P as ParamSpec } from './types-CfxzTEFL.js';
+import { Q as QueryModelContract, k as QueryMethodSpec, l as CommandModelContract, m as CommandMethodSpec } from './key-Dne-a20Q.js';
 
 /**
  * Contract-layer serialization (issue #59, CQRS Contract layer, Epic #57;
@@ -262,7 +262,7 @@ interface PreparedPlanSpec {
 interface PreparedPlanDocument {
     readonly formatVersion: typeof PREPARED_FORMAT_VERSION;
     /** The shared operation-IR version the plans were compiled against. */
-    readonly specVersion: typeof SPEC_VERSION;
+    readonly specVersion: typeof SPEC_VERSION_KEY_EXPR;
     /** Plan id (the transform's stable call-site id) → compiled plan. */
     readonly plans: Readonly<Record<string, PreparedPlanSpec>>;
 }

package/dist/spec/index.d.ts

@@ -1,11 +1,14 @@
-import { $ as AnyOperationDefinition, a0 as TransactionDefinition, b as PreparedBody } from '../key-DR7_lpyk.js';
-export { a1 as CompiledFragment, a2 as CompiledMutationPlan, a3 as DerivedConditionCheck, a4 as DerivedEdgeWrite, a5 as DerivedIdempotencyGuard, a6 as DerivedMaintainOutbox, a7 as DerivedMaintainWrite, a8 as DerivedOutboxEvent, a9 as DerivedUniqueGuard, aa as DerivedUpdate, ab as EntityRefResolver, ac as MAX_TRANSACT_COMPOSE_ITEMS, ad as assertNoCrossFragmentMaintainCollision, ae as compileFragment, af as compileMutationPlan, ag as compileSingleFragmentPlan, ah as resetMaintenanceGraphCache, ai as resolveLifecycle, aj as resolveMaintainers } from '../key-DR7_lpyk.js';
-import { M as MetadataRegistry } from '../linter-C-vypgut.js';
-import { C as ContractMap, e as ContextOwnershipMap, c as PreparedPlanSpec, a as PreparedPlanDocument } from '../prepared-artifact-BpPgkXEo.js';
-export { A as AnyModelContract, B as BuiltContracts, f as ContextOwnership, g as PREPARED_FORMAT_VERSION, h as PreparedBindMap, b as PreparedBindSpec, d as PreparedReadRouteSpec, P as PreparedWriteOpSpec, i as buildContexts, j as buildContracts, k as canonicalJson, l as entityFingerprint, p as planFingerprint } from '../prepared-artifact-BpPgkXEo.js';
-import { O as OperationsDocument, Q as QuerySpec, M as Manifest, C as ContractSpec, T as TransactionSpec, B as BridgeBundle, c as ConditionSpec, E as ExpressionSpec, a as CommandSpec, d as SpecVersion } from '../types-2PMXEn5x.js';
-export { e as CommandContractMethodSpec, f as CommandResolutionTarget, g as ComposeSpec, h as CompositionPlanSpec, b as ContextSpec, i as ContractCardinality, j as ContractCommandResult, k as ContractInputArity, l as ContractKeySpec, m as ContractKind, n as ContractResolution, o as EXPR_VERSION, p as ExecutionPlanSpec, q as ExpressionArrNode, r as ExpressionFloatNode, s as ExpressionIntNode, t as ExpressionNode, u as ExpressionObjNode, v as ExpressionOpNode, w as ExpressionOperator, x as ExpressionRefNode, y as ExpressionRefOptNode, z as ExpressionScalar, F as FilterSpec, A as ManifestEntity, D as ManifestField, G as ManifestFieldType, H as ManifestGsi, I as ManifestKey, J as ManifestRelation, K as ManifestTable, L as OperationSpec, P as ParamSpec, N as QueryContractMethodSpec, R as RangeConditionSpec, U as ReadOperationType, S as SPEC_VERSION, V as SPEC_VERSION_SCP, W as SPEC_VERSION_SUPPORTED, X as TransactionItemSpec, Y as TransactionItemType, Z as WhenSpec, _ as WriteOperationType } from '../types-2PMXEn5x.js';
-import '../types-BXLzIcQD.js';
+import { $ as AnyOperationDefinition, a0 as TransactionDefinition, b as PreparedBody } from '../key-Dne-a20Q.js';
+export { a1 as CompiledFragment, a2 as CompiledMutationPlan, a3 as DerivedConditionCheck, a4 as DerivedEdgeWrite, a5 as DerivedIdempotencyGuard, a6 as DerivedMaintainOutbox, a7 as DerivedMaintainWrite, a8 as DerivedOutboxEvent, a9 as DerivedUniqueGuard, aa as DerivedUpdate, ab as EntityRefResolver, ac as MAX_TRANSACT_COMPOSE_ITEMS, ad as assertNoCrossFragmentMaintainCollision, ae as compileFragment, af as compileMutationPlan, ag as compileSingleFragmentPlan, ah as resetMaintenanceGraphCache, ai as resolveLifecycle, aj as resolveMaintainers } from '../key-Dne-a20Q.js';
+import { M as MetadataRegistry } from '../linter-Cr1Hnw7n.js';
+import { B as BehaviorModelContract } from '../behaviors-DDltNivc.js';
+export { a as BehaviorMethodSpec } from '../behaviors-DDltNivc.js';
+import { C as ContractMap, e as ContextOwnershipMap, c as PreparedPlanSpec, a as PreparedPlanDocument } from '../prepared-artifact-BXkARxwO.js';
+export { A as AnyModelContract, B as BuiltContracts, f as ContextOwnership, g as PREPARED_FORMAT_VERSION, h as PreparedBindMap, b as PreparedBindSpec, d as PreparedReadRouteSpec, P as PreparedWriteOpSpec, i as buildContexts, j as buildContracts, k as canonicalJson, l as entityFingerprint, p as planFingerprint } from '../prepared-artifact-BXkARxwO.js';
+import { O as OperationsDocument, Q as QuerySpec, M as Manifest, T as TransactionSpec, C as ContractSpec, B as BridgeBundle, c as ConditionSpec, E as ExpressionSpec, a as CommandSpec, d as SpecVersion } from '../types-CfxzTEFL.js';
+export { e as CommandContractMethodSpec, f as CommandResolutionTarget, g as ComposeSpec, h as CompositionPlanSpec, b as ContextSpec, i as ContractCardinality, j as ContractCommandResult, k as ContractInputArity, l as ContractKeySpec, m as ContractKind, n as ContractResolution, o as EXPR_VERSION, p as ExecutionPlanSpec, q as ExpressionArrNode, r as ExpressionFloatNode, s as ExpressionIntNode, t as ExpressionNode, u as ExpressionObjNode, v as ExpressionOpNode, w as ExpressionOperator, x as ExpressionRefNode, y as ExpressionRefOptNode, z as ExpressionScalar, F as FilterSpec, A as ManifestEntity, D as ManifestField, G as ManifestFieldType, H as ManifestGsi, I as ManifestKey, J as ManifestRelation, K as ManifestTable, L as OperationSpec, P as ParamSpec, N as QueryContractMethodSpec, R as RangeConditionSpec, U as ReadOperationType, V as SPEC_VERSION, S as SPEC_VERSION_KEY_EXPR, W as SPEC_VERSION_SCP, X as SPEC_VERSION_SUPPORTED, Y as TransactionItemSpec, Z as TransactionItemType, _ as WhenSpec, $ as WriteOperationType } from '../types-CfxzTEFL.js';
+import { Component, ComponentGraphIR } from 'behavior-contracts';
+import '../types-BnFsTZwl.js';
 
 /**
  * Static parameterized operation-spec generation (issue #42, Phase 0b).
@@ -33,6 +36,16 @@ interface ContractInputs {
     readonly contracts?: ContractMap;
     /** Context-ownership declarations (context → member models / contracts). */
     readonly contexts?: ContextOwnershipMap;
+    /**
+     * Resolved behavior contracts (`publishBehaviors` output, #297 SP3) — the
+     * shared-authoring surface registrations. ADDITIVE: each contract's bc-lowered
+     * components register into the emitted `components[]` as
+     * `<RegistrationKey>__<method>` alongside the publish* output; nothing else
+     * in the document changes, and an absent/empty map reproduces the previous
+     * bytes exactly. Their CQRS effect is purely graph-derived (there is no
+     * declared side to verify — see `assertPublishSplitMatchesDerived`).
+     */
+    readonly behaviors?: Readonly<Record<string, BehaviorModelContract>>;
 }
 /**
  * Build the operations document from grouped read (`queries`) and write
@@ -46,6 +59,10 @@ interface ContractInputs {
  * contract-free input (`contractInputs` empty / absent) reproduces the pre-#59
  * document byte-for-byte — no `contracts` / `contexts` keys appear.
  *
+ * The shared-authoring layer (#297 SP3) is likewise additive: each
+ * `contractInputs.behaviors` registration appends its bc-lowered components to
+ * `components[]` (as `<Key>__<method>`); an absent/empty map changes nothing.
+ *
  * @throws if a command carries a write condition outside the supported subset
  *   (`{ notExists }` or pure equality) — the bridge guard; or if a contract op
  *   name collides with a hand-written definition.
@@ -70,6 +87,192 @@ declare function buildOperations(queries?: Record<string, AnyOperationDefinition
  */
 declare function buildManifest(registry?: typeof MetadataRegistry): Manifest;
 
+/**
+ * Universal component-graph IR emitter (SCP IR Phase 3, issue #290 — sub-pass 1b,
+ * DUAL-EMIT, behavior-contracts vocabulary v2).
+ *
+ * This module additively lifts the graphddb-specific operation IR
+ * (`QuerySpec.operations[]` / `TransactionSpec.items[]`, wired by `resultPath` /
+ * `sourceField` / `sourceList` / `{item.*}`) into the **universal SCP
+ * component-graph** form behavior-contracts defines
+ * (`scp-ir-architecture.md` §5/§5.1, `ts/src/behavior.ts`): a `Component{ name,
+ * inputPorts, body[], output, plan }` whose `body` nodes are `componentRef` /
+ * `map` referencing the graphddb catalog (`GetItem` / `Query` / `BatchGetItem` /
+ * `PutItem` / `UpdateItem` / `DeleteItem` / `ConditionCheck`) and whose Port
+ * wiring is Expression IR.
+ *
+ * ## SP5 ownership split (#297 / bc#26)
+ *
+ * Since #297 SP5 this module EXTRACTS but does not ASSEMBLE: every derived
+ * graph (node ids, ports, map/into/batched decisions, relationKind, plan) is
+ * handed to behavior-contracts' data-registration builder
+ * (`buildComponentDefinition`, validated against `GRAPHDDB_CATALOG`), which
+ * owns the IR shape — structural/catalog/plan validation, reference-root
+ * existence, and the deterministic code-point key-sorted canonicalization of
+ * the final `Component`. graphddb's `assertComponentsInCatalog` stays as the
+ * stricter consumer-side gate on top (its dynamic-family whitelist is tighter
+ * than the builder's `additionalPorts` acceptance — belt-and-suspenders by
+ * design).
+ *
+ * ## Dual-emit (this sub-pass only)
+ *
+ * The emitted `components[]` sits ALONGSIDE the existing
+ * `queries`/`commands`/`transactions` — nothing here removes or rewrites the old
+ * wiring. The 4 spec-consumer runtimes (py/php/rust/go) keep reading the OLD path
+ * (`queries` etc.); `components[]` is a new top-level field they tolerate (they
+ * read only the keys they know, and `validateEnvelope` checks only `version`).
+ * The purpose of the additive emit is to PROVE, via behavior-contracts
+ * `assertPortableComponentGraph` + `runBehavior`, that the universal form is
+ * well-formed and semantically reproduces the query — de-risking the later
+ * sub-passes that migrate the runtimes onto it.
+ *
+ * ## Vocabulary v2 (bc#22, behaviorVersion 2) — the sub-pass-2a gap closures
+ *
+ * The 2a escalation proved 6 constructs the sub-pass-1 emission could not carry;
+ * this emitter closes them on the v2 map vocabulary:
+ *
+ * 1. **Depth-2+ relations** (`$.groups.items.group[.permissions.items]`): a
+ *    relation whose producer is a CONNECTION is emitted as a `map` over the
+ *    parent connection's `items` with `into: <relationProp>` (zip-attach onto the
+ *    per-element membership row); deeper levels CHAIN over the previous map's
+ *    augmented list (`over: {ref:[<prevMapId>]}`), reading the parent body
+ *    through the attach key (`{ref:["$el","group",…]}`). The attach is FLAT on
+ *    the element (v2 `into` semantics — the canonical bc depth-2 vector shape);
+ *    the node id carries the full `resultPath`-derived path
+ *    (`groups.items.group.permissions.items`), so re-nesting the flat key into
+ *    the old assembled placement (`item.group.permissions`) is a mechanical,
+ *    id-driven fold in the consuming runtime.
+ * 2. **Per-element transaction guards**: the legacy `when:{op,left,right}`
+ *    comparison AND the #267/#268 `guard` Expression IR both lower to `map.when`
+ *    (evaluated under the `$item` element binding; strict-bool, fail-closed).
+ * 3. **Write-condition / write-item ports completeness**: every transaction
+ *    item's `entity`, `condition` (all kinds), `literalKey` and `maintain`
+ *    payload are carried as ports, so a handler builds the exact TransactWrite
+ *    item from the evaluated ports alone (plus its injected manifest/config —
+ *    the C4 boundary; no node-identity join needed).
+ * 4. **Relation filters**: an op's `filter.declarative` tree rides in the read
+ *    ports (JSON-encoded — see below).
+ * 5. **Implicit-strip marker**: a `refs` fan-out whose driver list was projected
+ *    only implicitly (`sourceList.implicit`) emits `implicitSourceField` in its
+ *    map ports, so the post-assembly strip of the driver field from the parent
+ *    is expressible without the old `sourceList`.
+ * 6. **Batched fan-out**: fan-outs the old path serves with ONE deduped/chunked
+ *    `BatchGetItem` (a `sourceList` refs fan-out; a belongsTo child of a
+ *    connection) emit `batched: true` — the handler receives `{items:[…]}` once
+ *    and owns dedupe/chunk/retry (CONSUMER), returning a list aligned to
+ *    `items`. Per-element `GetItem`/`Query` maps stay unbatched.
+ *
+ * ## Opaque-JSON ports (declarative trees)
+ *
+ * A port VALUE is Expression IR: `assertPortableComponentGraph` walks every port
+ * value through the closed operator set, so a declarative operator tree
+ * (`filter.declarative`, `condition.declarative`, `condition.names`, `maintain`)
+ * — whose single-key nodes (`{and:…}`, `{name:…}`) would be mis-read as
+ * unknown operators — is carried as a **canonical JSON string literal**
+ * (deterministically key-sorted), which the handler parses. Caller-param leaves
+ * (`{$param}`) that such a tree binds at execution time are lifted OUT into
+ * companion `condition.params.<name>` / `condition.values.<slot>` ports whose
+ * values are `{ref:[<param>]}` — evaluated by the executor, so the handler gets
+ * the bound values without reaching into graphddb scope internals.
+ *
+ * ## Scope convention (`runBehavior`-native)
+ *
+ * The graphddb Phase-2 key wiring roots its Expression IR references at
+ * `input.<param>` / `result.<field>` (and guards at `item.<field>`). The
+ * universal `runBehavior` executor evaluates ports against a FLAT scope
+ * `{ ...input, ...nodeResultsById, [<as>]: element }`, so this emitter REMAPS
+ * the scope roots when lowering:
+ *
+ * - `["input", p]`  → `[p]`                    — a param at the top-level scope.
+ * - `["result", f]` → `[<parentNodeId>, f]`    — the parent node result, or
+ *   `["$el"(…attach segs), f]` inside a relation map, or `[<as>, f]` inside a
+ *   refs fan-out map.
+ * - `["item", f]`   → `["$item", f]`           — a forEach guard's element field.
+ *
+ * The remap is a pure rename of the reference ROOTS; the literal/`concat`
+ * structure the Phase-2 lowerer produced is reused verbatim.
+ *
+ * ## Cardinality-one root collapse
+ *
+ * A cardinality-`'one'` query whose root is a `Query` (unique-GSI lookup)
+ * assembles, on the old path, a SINGLE entity (first matched item) that child
+ * relations key off (`{result.userId}`). Expression IR has no list indexing, so
+ * the collapse is carried as a root port `cardinality: 'one'` — the catalog
+ * `Query` handler returns the first matched item (or null) instead of a
+ * connection, exactly the old runtime's root shaping.
+ */
+
+/**
+ * Lower one {@link QuerySpec} into a universal SCP {@link Component}. Each read
+ * {@link OperationSpec} becomes a body node:
+ *
+ * - the root op (`resultPath === '$'`) → a `componentRef` whose ports carry the
+ *   remapped `keyExpr` (rooted at the params) and `projection`; a
+ *   cardinality-one Query root adds the `cardinality: 'one'` collapse port;
+ * - a `refs` fan-out op (carrying `sourceList`) → a **batched** `map` node
+ *   iterating the parent list attribute (`sourceList.over`), the per-element key
+ *   bound through the `sourceList.as` element binding, with the
+ *   `implicitSourceField` strip marker when the driver list was implicit;
+ * - a relation whose producer is a CONNECTION (or a deeper link of such a
+ *   chain) → a `map` over the connection's items / the previous map's augmented
+ *   list, `into: <relationProp>` (zip-attach; `batched` when the old path served
+ *   it with one BatchGetItem);
+ * - a root-level `hasMany` / `belongsTo` relation → a `componentRef` with
+ *   `parent`, `bindField` (the source field for null-binding skip), and
+ *   `relationKind`.
+ *
+ * The component's `output` is the Φ merge: the root node result with each
+ * ROOT-LEVEL relation attached under its property; a chained connection exposes
+ * `{obj:{cursor:<connection cursor>, items:<final augmented list>}}`. The `plan`
+ * is re-derived from the emitted parent wiring (identical `{groups,
+ * concurrency}` shape; equal to the query's plan wherever chaining introduced no
+ * new dependency), or absent for a single-node read.
+ */
+declare function buildQueryComponent(name: string, query: QuerySpec): Component;
+/**
+ * Lower one {@link TransactionSpec} into a universal SCP {@link Component}. A
+ * transaction is a single-stage batched write; each item becomes a body node:
+ *
+ * - a `forEach` item (expanded once per element of the named array param) → an
+ *   SCP `map` over that array param (`over: {ref:[<source>]}`, `as: "$item"`),
+ *   its `{item.<field>}` template tokens lowered to `["$item", field]` refs and
+ *   its `when`/`guard` lowered to `map.when` (gap 2 — a falsy element is
+ *   skipped: handler not called, excluded from the result, order preserved);
+ * - a plain item with an input-scope `guard` → a MAP OF ONE with `when`
+ *   (`over: {arr:[true]}`), reproducing the old kept/skipped expansion;
+ * - a plain item → a `componentRef` against the params.
+ *
+ * The `component` name is the DynamoDB write catalog entry (`Put` → `PutItem`,
+ * `Update` → `UpdateItem`, `Delete` → `DeleteItem`, `ConditionCheck` →
+ * `ConditionCheck`). The output is the array of every item node's result (a
+ * transaction returns no per-item image, so this is descriptive of the writes).
+ */
+declare function buildTransactionComponent(name: string, tx: TransactionSpec): Component;
+/**
+ * Build the universal `components[]` for a whole operations document (dual-emit,
+ * issue #290 sub-pass 1b). Every query and every transaction is lifted into one
+ * {@link Component}; commands (single writes) are represented via the query
+ * readbacks / transactions already present, so this sub-pass lifts the two
+ * multi-node forms (queries, transactions) that exercise the universal `map` /
+ * `componentRef` / plan vocabulary. Deterministic: queries then transactions,
+ * each in sorted-name order.
+ *
+ * Every emitted component is validated against {@link GRAPHDDB_CATALOG}
+ * (#297 SP1c — names, required ports, declared-port families); a mismatch
+ * throws, so an emitter drift from the catalog is a BUILD error, never a
+ * silently-shipped document.
+ */
+declare function buildComponents(queries: Readonly<Record<string, QuerySpec>>, transactions: Readonly<Record<string, TransactionSpec>>): Component[];
+/**
+ * Wrap emitted `components[]` into the portable component-graph IR document
+ * (`{irVersion, exprVersion, components}` — scp-ir-architecture.md §5): the
+ * ONLY input shape behavior-contracts' common Generator accepts (issue #257 —
+ * `generateModule` loudly rejects the raw operations bundle / internal IR).
+ * graphddb adds no generation logic: this envelope is the entire consumer-side
+ * input contract of the upstream codegen-static endpoint (§7.3 endpoint 3).
+ */
+declare function portableIrDocument(components: readonly Component[]): ComponentGraphIR;
+
 /**
  * N+1 static checker for the CQRS Contract layer (issue #60, Epic #57; proposal
  * `docs/cqrs-contract.md`, "N+1 Safety (Static Restriction)").
@@ -394,24 +597,22 @@ declare function assertBundleSerializable(bundle: BridgeBundle): void;
  */
 declare function canonicalizeExpressionSpec(input: unknown, context: string): ExpressionSpec;
 /**
- * Does this operations-document content actually contain an SCP Expression IR
- * node — a `{ kind: 'scpExpr' }` write condition or a `guard` (transaction
- * item / contract command method)? This is the **presence scan** behind the
- * conditional stamp (issue #261): the walk visits exactly the slots the spec
- * vocabulary defines, so an SCP-free document is provably stamped `1.1` and
- * stays byte-identical.
+ * The spec version to stamp on an operations document. **SCP IR Phase 2 (#289):
+ * always `2.0`.** The read-op key wiring moved from `{param}` string templates to
+ * the portable Expression IR (`keyExpr` / `valueExpr`), a MAJOR IR serialization
+ * change — so the whole operations IR moves to `2.0` at once (migration plan §4).
+ * A pre-#289 runtime (supported `1.2`) `validateEnvelope`-rejects a `2.0`
+ * document, the intended breaking cut. The former conditional `1.1`/`1.2`
+ * presence-scan stamping (issue #261, `operationsContainScpNodes`) was removed
+ * in the final #290 sub-pass: every `2.0` document is a superset (guard/scpExpr
+ * nodes still validate under exprVersion 2), so a single unconditional `2.0`
+ * stamp is correct now that the read-op key wiring is unconditionally Expression
+ * IR.
  */
-declare function operationsContainScpNodes(doc: {
+declare function operationsSpecVersion(_doc: {
     readonly commands: Readonly<Record<string, CommandSpec>>;
-    readonly transactions?: Readonly<Record<string, TransactionSpec>>;
     readonly contracts?: Readonly<Record<string, ContractSpec>>;
-}): boolean;
-/**
- * The spec version to stamp on an operations document: `1.2` iff it actually
- * contains an SCP node ({@link operationsContainScpNodes}), else the base
- * `1.1` — so every pre-#261 bundle serializes byte-identically.
- */
-declare function operationsSpecVersion(doc: Parameters<typeof operationsContainScpNodes>[0]): SpecVersion;
+}): SpecVersion;
 
 /**
  * Static prepared-plan artifact — the **build-time** (AOT) compilation of
@@ -503,4 +704,4 @@ declare function buildPreparedPlanDocument(plans: Readonly<Record<string, Prepar
  */
 declare function buildBridgeBundle(queries?: Record<string, AnyOperationDefinition>, commands?: Record<string, AnyOperationDefinition>, registry?: typeof MetadataRegistry, transactions?: Record<string, TransactionDefinition>, contractInputs?: ContractInputs): BridgeBundle;
 
-export { BridgeBundle, CommandSpec, ConditionSpec, ContextOwnershipMap, type ContractBoundaryViolation, type ContractInputs, ContractMap, type ContractN1Violation, ContractSpec, ExpressionSpec, Manifest, OperationsDocument, PreparedPlanDocument, PreparedPlanSpec, QuerySpec, SpecVersion, TransactionSpec, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, buildBridgeBundle, buildManifest, buildOperations, buildPreparedPlanDocument, buildQuerySpec, buildTransactionSpec, buildTransactions, canonicalizeExpressionSpec, collectContractBoundaryViolations, collectContractN1Violations, compilePreparedPlan, operationsContainScpNodes, operationsSpecVersion };
+export { BehaviorModelContract, BridgeBundle, CommandSpec, ConditionSpec, ContextOwnershipMap, type ContractBoundaryViolation, type ContractInputs, ContractMap, type ContractN1Violation, ContractSpec, ExpressionSpec, Manifest, OperationsDocument, PreparedPlanDocument, PreparedPlanSpec, QuerySpec, SpecVersion, TransactionSpec, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, buildBridgeBundle, buildComponents, buildManifest, buildOperations, buildPreparedPlanDocument, buildQueryComponent, buildQuerySpec, buildTransactionComponent, buildTransactionSpec, buildTransactions, canonicalizeExpressionSpec, collectContractBoundaryViolations, collectContractN1Violations, compilePreparedPlan, operationsSpecVersion, portableIrDocument };