graphddb 0.8.1 → 0.9.1

package/dist/{chunk-LAT64YCZ.js → chunk-MBJ4JVRM.js}

@@ -2,7 +2,7 @@ import {
   PREPARED_FORMAT_VERSION,
   buildManifest,
   entityFingerprint
-} from "./chunk-S2NI4PBW.js";
+} from "./chunk-PHXUFAY2.js";
 import {
   analyzeWriteRoute,
   assertBundleSerializable,
@@ -21,33 +21,96 @@ import {
   isContractKeyRef,
   isContractParamRef,
   isQueryModelContract
-} from "./chunk-T44OB5GU.js";
+} from "./chunk-HLFNCKFV.js";
 import {
   detectRelationFields,
   isInlineSnapshotSpec,
   normalizeSelectSpec
-} from "./chunk-HNY2EJPV.js";
+} from "./chunk-7OCXY4R6.js";
 import {
+  EXPR_VERSION,
   MARKER_ROW_ENTITY,
-  SPEC_VERSION,
+  SPEC_VERSION_KEY_EXPR,
   operationsSpecVersion
-} from "./chunk-L4QRCHRQ.js";
+} from "./chunk-WOFRHRXY.js";
 import {
   BATCH_GET_MAX_KEYS,
   CONDITION_OPERATOR_KEYS,
+  GRAPHDDB_CATALOG,
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
+  assertComponentsInCatalog,
+  assertPublishSplitMatchesDerived,
+  deriveComponentEffects,
   isParam,
   isRawCondition,
   param,
   resolveModelClass
-} from "./chunk-L2NEDS7U.js";
+} from "./chunk-GWWRXIHF.js";
 import {
   TableMapping,
   isColumn,
   resolveKey
 } from "./chunk-XTWXMOHD.js";
 
+// src/spec/key-expr.ts
+var PLACEHOLDER = /\{([^{}]+)\}/g;
+var RESULT_PREFIX = "result.";
+var ITEM_PREFIX = "item.";
+function tokenRef(token, template) {
+  if (token.startsWith(ITEM_PREFIX)) {
+    throw new Error(
+      `lowerKeyTemplate: read-path key template '${template}' references an '${token}' (item/Map-element) binding, which is a Phase 3 write-path token, not a Phase 2 read-path key wiring. Refusing to lower it.`
+    );
+  }
+  if (token.startsWith(RESULT_PREFIX)) {
+    return { ref: ["result", token.slice(RESULT_PREFIX.length)] };
+  }
+  return { ref: ["input", token] };
+}
+function lowerKeyTemplate(template) {
+  const parts = [];
+  let last = 0;
+  PLACEHOLDER.lastIndex = 0;
+  for (let m = PLACEHOLDER.exec(template); m !== null; m = PLACEHOLDER.exec(template)) {
+    const literal = template.slice(last, m.index);
+    if (literal !== "") parts.push(literal);
+    parts.push(tokenRef(m[1], template));
+    last = m.index + m[0].length;
+  }
+  const tail = template.slice(last);
+  if (tail !== "") parts.push(tail);
+  if (parts.length === 0) return "";
+  if (parts.length === 1) return parts[0];
+  return { concat: parts };
+}
+function lowerKeyCondition(keyCondition) {
+  const out = {};
+  for (const [attr, template] of Object.entries(keyCondition)) {
+    out[attr] = lowerKeyTemplate(template);
+  }
+  return out;
+}
+function renderKeyExprToTemplate(node) {
+  if (typeof node === "string") return node;
+  if (node !== null && typeof node === "object") {
+    const obj = node;
+    if (Array.isArray(obj.ref)) return refToToken(obj.ref);
+    if (Array.isArray(obj.concat)) {
+      return obj.concat.map(renderKeyExprToTemplate).join("");
+    }
+  }
+  throw new Error(
+    `renderKeyExprToTemplate: node is not a key-wiring expression (string literal / ref / concat): ${JSON.stringify(node)}`
+  );
+}
+function refToToken(path) {
+  const [root, ...rest] = path;
+  if (root === "result") return `{result.${rest.join(".")}}`;
+  if (root === "input") return `{${rest.join(".")}}`;
+  throw new Error(`renderKeyExprToTemplate: unexpected ref root '${root}' in key wiring`);
+}
+
 // src/spec/contract-n1-check.ts
 function isQueryMethodSpec(spec) {
   return typeof spec.resolution === "string" && spec.resolution !== void 0;
@@ -133,7 +196,9 @@ ${rest.map((v) => `  - ${v.message}`).join("\n")})` : "";
 
 // src/spec/contracts.ts
 function kindForDynamoType(dynamoType) {
-  return dynamoType === "N" ? "number" : "string";
+  if (dynamoType === "N") return "number";
+  if (dynamoType === "M") return "map";
+  return "string";
 }
 function recoverKind(metadata, fieldName) {
   const field = metadata.fields.find((f) => f.propertyName === fieldName);
@@ -167,6 +232,7 @@ function opToDefinition(contractName, methodName, op) {
   }
   const select = op.select !== void 0 ? assertBooleanProjection(op.select, `${contractName}.${methodName} select`) : void 0;
   const changes = op.changes !== void 0 ? convertStructure(op.changes, place, `${contractName}.${methodName} changes`) : void 0;
+  const add = op.add !== void 0 ? convertStructure(op.add, place, `${contractName}.${methodName} add`) : void 0;
   const condition = op.condition !== void 0 ? convertCondition(op.condition, place, `${contractName}.${methodName} condition`) : void 0;
   return {
     __isOperationDefinition: true,
@@ -175,6 +241,7 @@ function opToDefinition(contractName, methodName, op) {
     key,
     select,
     changes,
+    ...add !== void 0 ? { add } : {},
     ...condition !== void 0 ? { condition } : {},
     // #154: the use-case description captured on the recorded op (from the
     // descriptor's `description`) flows into the flattened `queries[op]` /
@@ -185,6 +252,11 @@ function opToDefinition(contractName, methodName, op) {
   };
 }
 function paramOfKind(recovered) {
+  if (recovered.kind === "map") {
+    throw new Error(
+      `A \`@map\` field cannot bind a key-position param: a DynamoDB key is composed of scalar segments, but this key field's model storage type is 'M' (issue #295). Bind map values at a value position (\`input\`) instead.`
+    );
+  }
   if (recovered.kind === "number") return param.number();
   if (recovered.kind === "literal" && recovered.literals !== void 0 && recovered.literals.length > 0) {
     return param.literal(
@@ -402,6 +474,13 @@ function composeSpecOf(node, contractName, methodName, contracts) {
       `Contract '${contractName}.${methodName}': composed child '${c.as}' must declare a \`resolution\` of 'point' or 'range'.`
     );
   }
+  const target = contracts[c.contract];
+  if (target !== void 0 && isQueryModelContract(target)) {
+    const targetMethod = target.methods[c.method];
+    if (targetMethod !== void 0) {
+      assertComposeTargetNotNested(contractName, methodName, c.as, c.contract, c.method, targetMethod.op);
+    }
+  }
   const bindIn = c.bind ?? {};
   const bind = {};
   for (const field of Object.keys(bindIn).sort()) {
@@ -435,6 +514,7 @@ function recordedComposeSpec(node, contractName, methodName, contracts) {
     contracts
   );
   const refMethod = node.method;
+  assertComposeTargetNotNested(contractName, methodName, node.as, refName, refMethodName, refMethod.op);
   const bind = {};
   for (const field of Object.keys(node.bind).sort()) {
     bind[field] = node.bind[field].path;
@@ -470,6 +550,12 @@ function composeOf(op) {
   const raw = op.compose;
   return Array.isArray(raw) ? raw : [];
 }
+function assertComposeTargetNotNested(contractName, methodName, as, targetContract, targetMethod, targetOp) {
+  if (targetOp === void 0 || composeOf(targetOp).length === 0) return;
+  throw new Error(
+    `Contract '${contractName}.${methodName}': composed child '${as}' references '${targetContract}.${targetMethod}', which itself declares a composition (nested compose). No runtime resolves a composed child's own compose edges, so '${targetContract}.${targetMethod}'s compose field(s) would never be populated through '${contractName}.${methodName}' \u2014 the generated result type would over-promise. Compose the grandchild directly from '${contractName}.${methodName}' instead (issue #256).`
+  );
+}
 function compositionPlanOf(compose) {
   if (compose.length === 0) return void 0;
   const { stages, concurrency } = deriveCompositionPlan(compose.length);
@@ -482,6 +568,9 @@ function compositionPlanOf(compose) {
 function batchTxName(contractName, methodName) {
   return `${opRefName(contractName, methodName)}__batch`;
 }
+function batchWriteTxName(contractName, methodName) {
+  return `${opRefName(contractName, methodName)}__batchWrite`;
+}
 function keyParamNames(op) {
   return keyFieldsOf(op);
 }
@@ -497,6 +586,14 @@ function toElementTemplate(template, keyParams) {
   );
 }
 function toElementRecord(record, keyParams) {
+  const out = {};
+  for (const field of Object.keys(record)) {
+    const value = record[field];
+    out[field] = typeof value === "string" ? toElementTemplate(value, keyParams) : value;
+  }
+  return out;
+}
+function toElementKeyRecord(record, keyParams) {
   const out = {};
   for (const field of Object.keys(record)) {
     out[field] = toElementTemplate(record[field], keyParams);
@@ -549,13 +646,51 @@ function synthesizeBatchTransaction(commandSpec, op) {
     tableName: commandSpec.tableName,
     entity: commandSpec.entity,
     ...commandSpec.item !== void 0 ? { item: toElementRecord(commandSpec.item, keyParams) } : {},
-    ...commandSpec.keyCondition !== void 0 ? { keyCondition: toElementRecord(commandSpec.keyCondition, keyParams) } : {},
+    ...commandSpec.keyCondition !== void 0 ? { keyCondition: toElementKeyRecord(commandSpec.keyCondition, keyParams) } : {},
     ...commandSpec.changes !== void 0 ? { changes: toElementRecord(commandSpec.changes, keyParams) } : {},
     ...condition !== void 0 ? { condition } : {},
     forEach: { source: "keys" }
   };
   return { params, items: [item] };
 }
+function synthesizeBatchWriteTransaction(contractName, methodName, commandSpec) {
+  const at = `Contract '${contractName}.${methodName}'`;
+  if (commandSpec.type === "UpdateItem") {
+    throw new Error(
+      `${at}: mode 'batchWrite' cannot express an update \u2014 DynamoDB BatchWriteItem carries only PutRequest / DeleteRequest (internal invariant; the authoring layer should have rejected this).`
+    );
+  }
+  if (commandSpec.condition !== void 0) {
+    throw new Error(
+      `${at}: mode 'batchWrite' cannot carry a write condition \u2014 DynamoDB BatchWriteItem has no ConditionExpression (internal invariant; the authoring layer should have rejected this).`
+    );
+  }
+  const elementFields = {};
+  for (const name of Object.keys(commandSpec.params).sort()) {
+    elementFields[name] = commandSpec.params[name];
+  }
+  const params = {
+    items: { type: "array", required: true, element: elementFields }
+  };
+  const allParams = new Set(Object.keys(commandSpec.params));
+  const toElement = (record) => {
+    const out = {};
+    for (const field of Object.keys(record)) {
+      const v = record[field];
+      out[field] = typeof v === "string" ? toElementTemplate(v, allParams) : v;
+    }
+    return out;
+  };
+  const item = {
+    type: TX_ITEM_TYPE[commandSpec.type],
+    tableName: commandSpec.tableName,
+    entity: commandSpec.entity,
+    ...commandSpec.item !== void 0 ? { item: toElement(commandSpec.item) } : {},
+    ...commandSpec.keyCondition !== void 0 ? { keyCondition: toElement(commandSpec.keyCondition) } : {},
+    forEach: { source: "items" }
+  };
+  return { params, items: [item], batchWrite: true };
+}
 function composeFragmentTransaction(contractName, methodName, ops) {
   const items = [];
   const params = {};
@@ -704,8 +839,9 @@ function buildDerivedUpdateItems(derivedUpdates) {
       tableName,
       entity: update.entity.name,
       keyCondition,
-      // The delta is a compile-time constant → a literal numeric template (no param).
-      add: { [update.attribute]: String(update.amount) }
+      // The delta is a compile-time constant → a TYPED numeric literal (no param),
+      // carried verbatim so it marshals as `N`, not a stringified `S "1"` (#299).
+      add: { [update.attribute]: update.amount }
     });
     collectTemplateParams(keyCondition, metadata, params);
   }
@@ -765,7 +901,8 @@ function buildMaintainWriteItems(maintainWrites) {
       ...maintain.kind === "counter" && maintain.counter !== void 0 && maintain.counter.op === "count" ? {
         counter: {
           attribute: maintain.counter.attribute,
-          delta: String(maintain.counter.delta)
+          // TYPED numeric delta (#299): carried verbatim so it marshals as `N`.
+          delta: maintain.counter.delta
         }
       } : {}
     };
@@ -923,6 +1060,15 @@ function modeTargetFor(mode, op, commandSpec, contractName, methodName, opName,
   if (mode === "parallel") {
     return { mode: "parallel", operation: opName };
   }
+  if (mode === "batchWrite") {
+    const txName2 = batchWriteTxName(contractName, methodName);
+    transactionSpecs[txName2] = synthesizeBatchWriteTransaction(
+      contractName,
+      methodName,
+      commandSpec
+    );
+    return { mode: "batchWrite", transaction: txName2 };
+  }
   const txName = batchTxName(contractName, methodName);
   transactionSpecs[txName] = synthesizeBatchTransaction(commandSpec, op);
   return { mode: "transaction", transaction: txName };
@@ -1138,6 +1284,11 @@ function serializeCommandContract(contractName, contract, commandSpecs, transact
         returnSelection
       );
     }
+    if (method.mode === "batchWrite" && promotedToTransaction) {
+      throw new Error(
+        `Contract '${contractName}.${methodName}': mode 'batchWrite' on a method promoted to an atomic TransactWriteItems (derived effects / multi-fragment) \u2014 BatchWriteItem cannot compose those items (internal invariant).`
+      );
+    }
     const batch = method.mode !== void 0 && !promotedToTransaction ? modeTargetFor(
       method.mode,
       op,
@@ -1314,6 +1465,417 @@ ${rest.map((v) => `  - ${v.message}`).join("\n")})` : "";
   throw new Error(first.message + suffix);
 }
 
+// src/spec/components.ts
+import {
+  buildComponentDefinition
+} from "behavior-contracts";
+function registerComponent(name, inputPorts, body, output, plan) {
+  return buildComponentDefinition(
+    { name, inputPorts, body, output, plan },
+    { catalog: GRAPHDDB_CATALOG }
+  );
+}
+function remapRefRoots(node, resultRoot, itemRoot) {
+  if (node === null || typeof node !== "object") return node;
+  if (Array.isArray(node)) {
+    return node.map((e) => remapRefRoots(e, resultRoot, itemRoot));
+  }
+  const obj = node;
+  const keys = Object.keys(obj);
+  if (keys.length === 1) {
+    const key = keys[0];
+    const arg = obj[key];
+    if (key === "ref" || key === "refOpt") {
+      const path = arg;
+      const [root, ...rest] = path;
+      const remapped = root === "input" ? rest : root === "result" ? [...resultRoot, ...rest] : root === "item" && itemRoot !== void 0 ? [...itemRoot, ...rest] : path;
+      return { [key]: remapped };
+    }
+    if (key === "int" || key === "float") return node;
+    if (key === "obj") {
+      const out = {};
+      for (const [k, v] of Object.entries(arg)) {
+        out[k] = remapRefRoots(v, resultRoot, itemRoot);
+      }
+      return { obj: out };
+    }
+    if (Array.isArray(arg)) {
+      return {
+        [key]: arg.map((e) => remapRefRoots(e, resultRoot, itemRoot))
+      };
+    }
+    return {
+      [key]: remapRefRoots(arg, resultRoot, itemRoot)
+    };
+  }
+  return node;
+}
+function stableJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const keys = Object.keys(value).sort();
+  const body = keys.map((k) => `${JSON.stringify(k)}:${stableJson(value[k])}`).join(",");
+  return `{${body}}`;
+}
+function collectParamLeaves(tree, out) {
+  if (tree === null || typeof tree !== "object") return;
+  if (Array.isArray(tree)) {
+    for (const e of tree) collectParamLeaves(e, out);
+    return;
+  }
+  const rec = tree;
+  if (typeof rec.$param === "string" && Object.keys(rec).length === 1) {
+    out.add(rec.$param);
+    return;
+  }
+  for (const v of Object.values(rec)) collectParamLeaves(v, out);
+}
+function pathToId(resultPath) {
+  if (resultPath === "$") return "root";
+  return resultPath.startsWith("$.") ? resultPath.slice(2) : resultPath;
+}
+function parentPath(op) {
+  const tokens = op.resultPath.split(".");
+  const drop = op.resultPath.endsWith(".items") ? 2 : 1;
+  const p = tokens.slice(0, tokens.length - drop).join(".");
+  return p === "" ? "$" : p;
+}
+function relationProp(op) {
+  const tokens = op.resultPath.split(".");
+  const idx = op.resultPath.endsWith(".items") ? tokens.length - 2 : tokens.length - 1;
+  return tokens[idx];
+}
+function relationKindOf(op) {
+  return op.resultPath.endsWith(".items") ? "connection" : "single";
+}
+function readPorts(op, resultRoot) {
+  const ports = { table: op.tableName };
+  if (op.indexName !== void 0) ports.indexName = op.indexName;
+  for (const [attr, node] of Object.entries(op.keyExpr ?? {})) {
+    ports[attr] = remapRefRoots(node, resultRoot);
+  }
+  if (op.rangeCondition !== void 0) {
+    ports.rangeKey = op.rangeCondition.key;
+    ports.rangeOperator = op.rangeCondition.operator;
+    ports.rangeValue = remapRefRoots(
+      op.rangeCondition.valueExpr ?? "",
+      resultRoot
+    );
+  }
+  if (op.limit !== void 0) ports.limit = op.limit;
+  if (op.filter !== void 0) ports.filter = stableJson(op.filter.declarative);
+  ports.projection = { arr: [...op.projection] };
+  return ports;
+}
+function buildQueryComponent(name, query) {
+  const ops = query.operations;
+  const idByPath = /* @__PURE__ */ new Map();
+  const opByPath = /* @__PURE__ */ new Map();
+  for (const op of ops) {
+    idByPath.set(op.resultPath, pathToId(op.resultPath));
+    opByPath.set(op.resultPath, op);
+  }
+  const lineages = /* @__PURE__ */ new Map();
+  const elementInfo = /* @__PURE__ */ new Map();
+  const body = ops.map((op) => {
+    const id = pathToId(op.resultPath);
+    if (op.resultPath === "$") {
+      const ports = readPorts(op, []);
+      if (query.cardinality === "one" && op.type === "Query") ports.cardinality = "one";
+      const node2 = { id, component: op.type, ports };
+      return node2;
+    }
+    const reject = (kind) => {
+      throw new Error(`buildQueryComponent('${name}'): op '${op.resultPath}': ${kind}`);
+    };
+    const pp = parentPath(op);
+    const producerId = idByPath.get(pp) ?? reject(`no producer op at '${pp}'`);
+    if (op.sourceList !== void 0) {
+      if (pp !== "$") reject("nested sourceList not expressible (v2 map)");
+      const as = op.sourceList.as ?? `$${op.sourceList.key}`;
+      const over = remapRefRoots(
+        op.sourceList.over ?? { ref: ["result", op.sourceList.from] },
+        [producerId]
+      );
+      const ports = readPorts(op, [as]);
+      if (op.sourceList.implicit === true) ports.implicitSourceField = op.sourceList.from;
+      const node2 = {
+        id,
+        map: {
+          over,
+          as,
+          component: op.type,
+          ports,
+          parent: producerId,
+          relationKind: relationKindOf(op),
+          batched: true
+        }
+      };
+      lineages.set(op.resultPath, { tailExpr: { ref: [id] }, tailId: id });
+      return node2;
+    }
+    const producerOp = opByPath.get(pp);
+    const producerIsConnection = producerOp !== void 0 && pp.endsWith(".items");
+    const producerElement = elementInfo.get(pp);
+    if (producerIsConnection || producerElement !== void 0) {
+      const lineageKey = producerElement?.lineageKey ?? pp;
+      const lineage = producerElement !== void 0 && pp.endsWith(".items") ? reject("nested per-element connection not expressible (v2 map)") : lineages.get(lineageKey) ?? reject(`no element chain for '${lineageKey}'`);
+      const as = "$el";
+      const attach = producerElement?.attachSeg ?? [];
+      const into = relationProp(op);
+      const node2 = {
+        id,
+        map: {
+          over: lineage.tailExpr,
+          as,
+          component: op.type,
+          ports: readPorts(op, [as, ...attach]),
+          parent: lineage.tailId,
+          relationKind: relationKindOf(op),
+          into,
+          // A belongsTo child the old path resolves via ONE deduped BatchGetItem
+          // (gap 6) is batched; a per-element Query stays per-element.
+          ...op.type === "BatchGetItem" ? { batched: true } : {}
+        }
+      };
+      lineages.set(lineageKey, { tailExpr: { ref: [id] }, tailId: id });
+      elementInfo.set(op.resultPath, { lineageKey, attachSeg: [into] });
+      return node2;
+    }
+    const node = {
+      id,
+      component: op.type,
+      ports: readPorts(op, [producerId]),
+      parent: producerId,
+      ...op.sourceField !== void 0 ? { bindField: op.sourceField } : {},
+      relationKind: relationKindOf(op)
+    };
+    if (relationKindOf(op) === "connection") {
+      lineages.set(op.resultPath, { tailExpr: { ref: [id, "items"] }, tailId: id });
+    }
+    return node;
+  });
+  const relOps = ops.filter((op) => op.resultPath !== "$");
+  let output;
+  if (relOps.length === 0) {
+    output = { ref: ["root"] };
+  } else {
+    const outputObj = { root: { ref: ["root"] } };
+    for (const op of relOps) {
+      const id = pathToId(op.resultPath);
+      if (elementInfo.has(op.resultPath)) continue;
+      const lineage = lineages.get(op.resultPath);
+      const key = parentPath(op) === "$" ? relationProp(op) : id;
+      if (lineage !== void 0 && lineage.tailId !== id && relationKindOf(op) === "connection" && op.sourceList === void 0) {
+        outputObj[key] = {
+          obj: { cursor: { ref: [id, "cursor"] }, items: lineage.tailExpr }
+        };
+      } else {
+        outputObj[key] = { ref: [id] };
+      }
+    }
+    output = { obj: outputObj };
+  }
+  let plan;
+  if (query.executionPlan) {
+    const idToIndex = new Map(body.map((n, i) => [n.id, i]));
+    const stageOf = [];
+    const groups = [];
+    body.forEach((n, i) => {
+      const pid = "map" in n ? n.map.parent : "cond" in n ? n.cond.parent : n.parent;
+      const stage = pid === void 0 ? 0 : stageOf[idToIndex.get(pid)] + 1;
+      stageOf[i] = stage;
+      (groups[stage] ??= []).push(i);
+    });
+    plan = { groups, concurrency: query.executionPlan.concurrency };
+  }
+  return registerComponent(name, portSchemas(query.params), body, output, plan ?? null);
+}
+function lowerTransactionTemplate(template) {
+  const PLACEHOLDER2 = /\{([^{}]+)\}/g;
+  const parts = [];
+  let last = 0;
+  PLACEHOLDER2.lastIndex = 0;
+  for (let m = PLACEHOLDER2.exec(template); m !== null; m = PLACEHOLDER2.exec(template)) {
+    const literal = template.slice(last, m.index);
+    if (literal !== "") parts.push(literal);
+    const token = m[1];
+    parts.push(
+      token.startsWith("item.") ? { ref: ["$item", token.slice("item.".length)] } : { ref: [token] }
+    );
+    last = m.index + m[0].length;
+  }
+  const tail = template.slice(last);
+  if (tail !== "") parts.push(tail);
+  if (parts.length === 0) return "";
+  if (parts.length === 1) return parts[0];
+  return { concat: parts };
+}
+function lowerTransactionValue(value) {
+  return typeof value === "string" ? lowerTransactionTemplate(value) : value;
+}
+function conditionPorts(condition, ports) {
+  ports["condition.kind"] = condition.kind;
+  switch (condition.kind) {
+    case "notExists":
+      return;
+    case "attributeExists":
+    case "attributeNotExists":
+      ports["condition.field"] = condition.field;
+      return;
+    case "equals": {
+      for (const field of Object.keys(condition.fields).sort()) {
+        ports[`condition.equals.${field}`] = lowerTransactionValue(condition.fields[field]);
+      }
+      return;
+    }
+    case "expr": {
+      ports["condition.declarative"] = stableJson(condition.declarative);
+      const params = /* @__PURE__ */ new Set();
+      collectParamLeaves(condition.declarative, params);
+      for (const p of [...params].sort()) {
+        ports[`condition.params.${p}`] = { ref: [p] };
+      }
+      return;
+    }
+    case "raw": {
+      ports["condition.expression"] = condition.expression;
+      ports["condition.names"] = stableJson(condition.names);
+      for (const slot of Object.keys(condition.values).sort()) {
+        const v = condition.values[slot];
+        const leaf = v !== null && typeof v === "object" && typeof v.$param === "string" ? { ref: [v.$param] } : v;
+        ports[`condition.values.${slot}`] = leaf;
+      }
+      return;
+    }
+    case "scpExpr":
+      ports["condition.expression"] = stableJson(condition.expression);
+      return;
+  }
+}
+function transactionItemPorts(item) {
+  const ports = { table: item.tableName, entity: item.entity };
+  const record = (src, group) => {
+    if (src === void 0) return;
+    for (const [field, value] of Object.entries(src)) {
+      ports[`${group}.${field}`] = lowerTransactionValue(value);
+    }
+  };
+  record(item.item, "item");
+  record(item.keyCondition, "key");
+  record(item.changes, "changes");
+  record(item.add, "add");
+  if (item.literalKey === true) ports.literalKey = true;
+  if (item.condition !== void 0) conditionPorts(item.condition, ports);
+  if (item.maintain !== void 0) ports.maintain = stableJson(item.maintain);
+  return ports;
+}
+function lowerItemGuard(item) {
+  if (item.guard !== void 0) {
+    return remapRefRoots(item.guard.expr, [], ["$item"]);
+  }
+  const when = item.when;
+  if (when === void 0) return void 0;
+  const args = [lowerTransactionTemplate(when.left), lowerTransactionTemplate(when.right)];
+  return when.op === "eq" ? { eq: args } : { ne: args };
+}
+function buildTransactionComponent(name, tx) {
+  const catalog = {
+    Put: "PutItem",
+    Update: "UpdateItem",
+    Delete: "DeleteItem",
+    ConditionCheck: "ConditionCheck"
+  };
+  const body = tx.items.map((item, i) => {
+    const id = `item${i}`;
+    const component = catalog[item.type];
+    const when = lowerItemGuard(item);
+    if (tx.batchWrite === true) {
+      const reject = (kind) => {
+        throw new Error(
+          `buildTransactionComponent('${name}'): batchWrite item${i}: ${kind} \u2014 DynamoDB BatchWriteItem carries only unconditional PutRequest / DeleteRequest (internal invariant; the emitter synthesizes this form).`
+        );
+      };
+      if (component !== "PutItem" && component !== "DeleteItem") reject(`'${component}' item`);
+      if (item.condition !== void 0) reject("a write condition");
+      if (when !== void 0) reject("a when/guard");
+      if (item.forEach === void 0) reject("no forEach (the bulk form is forEach-over-items)");
+      const node2 = {
+        id,
+        map: {
+          over: { ref: [item.forEach.source] },
+          as: "$item",
+          component,
+          ports: transactionItemPorts(item),
+          batched: true
+        }
+      };
+      return node2;
+    }
+    if (item.forEach !== void 0) {
+      const node2 = {
+        id,
+        map: {
+          over: { ref: [item.forEach.source] },
+          as: "$item",
+          component,
+          ports: transactionItemPorts(item),
+          ...when !== void 0 ? { when } : {}
+        }
+      };
+      return node2;
+    }
+    if (when !== void 0) {
+      const node2 = {
+        id,
+        map: {
+          over: { arr: [true] },
+          as: "$item",
+          component,
+          ports: transactionItemPorts(item),
+          when
+        }
+      };
+      return node2;
+    }
+    const node = { id, component, ports: transactionItemPorts(item) };
+    return node;
+  });
+  return registerComponent(
+    name,
+    portSchemas(tx.params),
+    body,
+    { arr: body.map((n) => ({ ref: [n.id] })) },
+    null
+  );
+}
+function portSchemas(params) {
+  const out = {};
+  for (const name of Object.keys(params).sort()) {
+    const p = params[name];
+    out[name] = { type: p.type, required: p.required };
+  }
+  return out;
+}
+function buildComponents(queries, transactions) {
+  const components = [];
+  for (const name of Object.keys(queries).sort()) {
+    components.push(buildQueryComponent(name, queries[name]));
+  }
+  for (const name of Object.keys(transactions).sort()) {
+    components.push(buildTransactionComponent(name, transactions[name]));
+  }
+  assertComponentsInCatalog(components);
+  return components;
+}
+function portableIrDocument(components) {
+  return {
+    irVersion: 1,
+    exprVersion: EXPR_VERSION,
+    components: [...components]
+  };
+}
+
 // src/spec/operations.ts
 function paramSpecs(params) {
   const out = {};
@@ -1332,11 +1894,12 @@ function paramSpecs(params) {
 function metaFor(def) {
   return MetadataRegistry.get(def.entity.modelClass);
 }
-function templateLeaf(key, value) {
+function templateValueLeaf(key, value) {
   if (isContractParamRef(value)) return value.token;
   if (isContractKeyFieldRef(value)) return `{${value.field}}`;
   if (isParam(value)) return `{${key}}`;
   if (value instanceof Date) return value.toISOString();
+  if (typeof value === "number" || typeof value === "boolean") return value;
   return String(value);
 }
 function keyFieldNames(key) {
@@ -1415,7 +1978,20 @@ function buildReadOperations(def) {
   };
   const ops = [root];
   ops.push(...buildRelationOperations(metadata, select, "$"));
-  return injectRefsSourceProjections(ops);
+  return injectRefsSourceProjections(ops).map(lowerOperationKeyExprs);
+}
+function lowerOperationKeyExprs(op) {
+  const keyExpr = op.keyCondition ? lowerKeyCondition(op.keyCondition) : {};
+  const { keyCondition: _dropKeyCondition, rangeCondition, ...rest } = op;
+  const nextRange = rangeCondition ? (() => {
+    const { value: _dropValue, ...rc } = rangeCondition;
+    return { ...rc, valueExpr: lowerKeyTemplate(rangeCondition.value ?? "") };
+  })() : void 0;
+  return {
+    ...rest,
+    keyExpr,
+    ...nextRange ? { rangeCondition: nextRange } : {}
+  };
 }
 function projectionFields(select) {
   const out = [];
@@ -1424,7 +2000,7 @@ function projectionFields(select) {
   }
   return out.sort();
 }
-function buildRelationOperations(metadata, select, parentPath) {
+function buildRelationOperations(metadata, select, parentPath2) {
   const ops = [];
   const relations = detectRelationFields(select, metadata);
   for (const rel of [...relations].sort(
@@ -1434,7 +2010,7 @@ function buildRelationOperations(metadata, select, parentPath) {
     const childSelect = spec.select ?? {};
     const targetClass = rel.targetFactory();
     const targetMeta = MetadataRegistry.get(targetClass);
-    const childPath = `${parentPath}.${rel.propertyName}`;
+    const childPath = `${parentPath2}.${rel.propertyName}`;
     if (rel.type === "refs") {
       if (spec.filter !== void 0) {
         throw new Error(
@@ -1587,7 +2163,16 @@ function buildRefsOperation(rel, targetMeta, select, resultPath) {
     projection: projectionFields(select),
     resultPath,
     sourceField,
-    sourceList: { from: refs.from, key: refs.key }
+    // #289 P2-5: the sourceList carries its Phase-3 Map shape prep — `over` is
+    // the Expression-IR ref to the parent list attribute the Map iterates, `as`
+    // is the per-element binding name. Descriptive only in Phase 2 (behavior is
+    // still driven by `from`/`key`); Phase 3 lowers the fan-out body onto them.
+    sourceList: {
+      from: refs.from,
+      key: refs.key,
+      over: { ref: ["result", refs.from] },
+      as: `$${refs.key}`
+    }
   };
 }
 function injectRefsSourceProjections(ops) {
@@ -1595,11 +2180,11 @@ function injectRefsSourceProjections(ops) {
     const op = ops[i];
     if (op.sourceList === void 0) continue;
     const tokens = op.resultPath.split(".");
-    const parentPath = tokens.slice(0, -2).join(".") || "$";
-    const parentIndex = ops.findIndex((p) => p.resultPath === parentPath);
+    const parentPath2 = tokens.slice(0, -2).join(".") || "$";
+    const parentIndex = ops.findIndex((p) => p.resultPath === parentPath2);
     if (parentIndex === -1) {
       throw new Error(
-        `refs fan-out at '${op.resultPath}': no parent operation at '${parentPath}'.`
+        `refs fan-out at '${op.resultPath}': no parent operation at '${parentPath2}'.`
       );
     }
     const parent = ops[parentIndex];
@@ -1648,6 +2233,8 @@ function buildCommandSpec(def) {
       ...description
     };
   }
+  const addStructure = def.add;
+  const add = addStructure !== void 0 && Object.keys(addStructure).length > 0 ? { add: templateRecord(addStructure) } : {};
   return {
     type: "UpdateItem",
     tableName,
@@ -1655,6 +2242,7 @@ function buildCommandSpec(def) {
     params,
     keyCondition: writeKeyCondition(metadata, def.key, entity),
     changes: templateRecord(def.changes),
+    ...add,
     ...condition ? { condition } : {},
     ...description
   };
@@ -1681,7 +2269,7 @@ function writeKeyCondition(metadata, key, entity) {
 function templateRecord(structure) {
   const out = {};
   for (const key of Object.keys(structure).sort()) {
-    out[key] = templateLeaf(key, structure[key]);
+    out[key] = templateValueLeaf(key, structure[key]);
   }
   return out;
 }
@@ -1689,7 +2277,7 @@ function extractCondition(def) {
   return conditionInputToSpec(
     def.condition,
     `Command on '${def.entity.name}'`,
-    (field, value) => templateLeaf(field, value),
+    (field, value) => templateValueLeaf(field, value),
     (value, name) => conditionTreeLeaf(value, name),
     // A raw `cond` value slot (issue #114-B): a contract param / key ref carries
     // its own name; a plain `param.*` falls through to the positional default.
@@ -1728,6 +2316,27 @@ function buildQuerySpec(def) {
     ...def.description !== void 0 ? { description: def.description } : {}
   };
 }
+function toPortableQuery(name, spec) {
+  const root = spec.operations[0];
+  if (root === void 0 || root.resultPath !== "$") {
+    throw new Error(
+      `toPortableQuery('${name}'): expected the root op at operations[0] (resultPath '$'); got ${root === void 0 ? "no operations" : `'${root.resultPath}'`}.`
+    );
+  }
+  const { resultPath: _rp, sourceField: _sf, sourceList: _sl, ...portableRoot } = root;
+  return {
+    params: spec.params,
+    operations: [portableRoot],
+    ...spec.cardinality !== void 0 ? { cardinality: spec.cardinality } : {},
+    ...spec.description !== void 0 ? { description: spec.description } : {}
+  };
+}
+function toPortableTransaction(spec) {
+  return {
+    params: spec.params,
+    ...spec.batchWrite === true ? { batchWrite: true } : {}
+  };
+}
 function mergeSpecs(base, synthesized, kind) {
   for (const name of Object.keys(synthesized)) {
     if (Object.prototype.hasOwnProperty.call(base, name)) {
@@ -1759,16 +2368,55 @@ function buildOperations(queries = {}, commands = {}, transactions = {}, contrac
   mergeSpecs(transactionSpecs, built.transactions, "transaction");
   const contractSpecs = built.contracts;
   const contextSpecs = buildContexts(contextInputMap);
+  const components = buildComponents(querySpecs, transactionSpecs);
+  const behaviorNames = /* @__PURE__ */ new Set();
+  {
+    const behaviorInputs = contractInputs.behaviors ?? {};
+    const taken = new Set(components.map((c) => c.name));
+    for (const key of Object.keys(behaviorInputs).sort()) {
+      for (const c of behaviorInputs[key].components) {
+        const name = `${key}__${c.name}`;
+        if (taken.has(name)) {
+          throw new Error(
+            `publishBehaviors registration '${key}' produced component '${name}', which collides with another emitted component. Rename the behavior registration or the method.`
+          );
+        }
+        taken.add(name);
+        behaviorNames.add(name);
+        components.push({ ...c, name });
+      }
+    }
+    if (behaviorNames.size > 0) assertComponentsInCatalog(components);
+  }
+  assertPublishSplitMatchesDerived(
+    deriveComponentEffects(components),
+    {
+      queries: new Set(Object.keys(querySpecs)),
+      transactions: new Set(Object.keys(transactionSpecs)),
+      commands: new Set(Object.keys(commandSpecs)),
+      behaviors: behaviorNames
+    },
+    contractSpecs
+  );
+  const portableQueries = {};
+  for (const [name, spec] of Object.entries(querySpecs)) {
+    portableQueries[name] = toPortableQuery(name, spec);
+  }
+  const portableTransactions = {};
+  for (const [name, spec] of Object.entries(transactionSpecs)) {
+    portableTransactions[name] = toPortableTransaction(spec);
+  }
   const content = {
-    queries: querySpecs,
+    queries: portableQueries,
     commands: commandSpecs,
-    ...Object.keys(transactionSpecs).length > 0 ? { transactions: transactionSpecs } : {},
+    ...Object.keys(portableTransactions).length > 0 ? { transactions: portableTransactions } : {},
     ...Object.keys(contractSpecs).length > 0 ? { contracts: contractSpecs } : {},
     ...Object.keys(contextSpecs).length > 0 ? { contexts: contextSpecs } : {}
   };
   return {
     version: operationsSpecVersion(content),
-    ...content
+    ...content,
+    ...components.length > 0 ? { components } : {}
   };
 }
 
@@ -1957,7 +2605,9 @@ function buildPreparedPlanDocument(plans) {
   for (const id of Object.keys(plans).sort()) sorted[id] = plans[id];
   return {
     formatVersion: PREPARED_FORMAT_VERSION,
-    specVersion: SPEC_VERSION,
+    // #289 Phase 2: the embedded operations IR is 2.0 (major bump); the prepared
+    // artifact's specVersion tracks it so a version-skewed plan fails closed.
+    specVersion: SPEC_VERSION_KEY_EXPR,
     plans: sorted
   };
 }
@@ -1973,12 +2623,17 @@ function buildBridgeBundle(queries = {}, commands = {}, registry = MetadataRegis
 }
 
 export {
+  renderKeyExprToTemplate,
   collectContractN1Violations,
   assertContractN1Safe,
   buildContracts,
   buildContexts,
   collectContractBoundaryViolations,
   assertContractBoundaries,
+  buildQueryComponent,
+  buildTransactionComponent,
+  buildComponents,
+  portableIrDocument,
   buildQuerySpec,
   buildOperations,
   compilePreparedPlan,