graphddb 0.7.9 → 0.7.10

package/dist/{chunk-NYM7K2ST.js → chunk-EOJDN3SA.js}

@@ -1,3 +1,32 @@
+import {
+  SELECT_SPEC,
+  buildMaintenanceGraph,
+  buildProject,
+  buildRelation,
+  buildSubscribeHandler,
+  detectRelationFields,
+  getEntityWrites,
+  getImplicitKeyFields,
+  hydrate,
+  isEntityWritesDefinition,
+  isInlineSnapshotSpec,
+  isLifecycleContract,
+  isSelectBuilder,
+  lifecyclePhaseForIntent,
+  normalizeSelectSpec,
+  normalizeTopLevelSelect,
+  parseChange,
+  validateInlineSnapshotSelect
+} from "./chunk-DFUKGU2Q.js";
+import {
+  EXPR_VERSION,
+  MARKER_ROW_ENTITY,
+  SPEC_VERSION,
+  canonicalizeExpressionSpec,
+  isScpExprConditionInput,
+  isTransactionRef,
+  operationsSpecVersion
+} from "./chunk-3UD3XIF2.js";
 import {
   BATCH_GET_MAX_KEYS,
   CONDITION_OPERATOR_KEYS,
@@ -6,17 +35,12 @@ import {
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
   NO_MIDDLEWARE,
-  SELECT_SPEC,
   attachHiddenKey,
   attachModelClass,
   buildConditionExpression,
   buildDeleteInput,
-  buildMaintenanceGraph,
-  buildProject,
   buildPutInput,
   buildReadRuntime,
-  buildRelation,
-  buildSubscribeHandler,
   buildUpdateInput,
   buildWriteRuntime,
   captureWrite,
@@ -25,34 +49,21 @@ import {
   compileRawCondition,
   condParamName,
   ctxModelFor,
-  detectRelationFields,
   execItemKeySignature,
   executeDelete,
   executePut,
   executeTransaction,
   executeUpdate,
-  getEntityWrites,
-  getImplicitKeyFields,
-  hydrate,
-  isEntityWritesDefinition,
-  isInlineSnapshotSpec,
-  isLifecycleContract,
   isParam,
   isRawCondition,
-  isSelectBuilder,
-  lifecyclePhaseForIntent,
-  normalizeSelectSpec,
-  normalizeTopLevelSelect,
   param,
-  parseChange,
   pkTemplate,
   resolveModelClass,
   resolveSegmentedKey,
   serializeFieldValue,
   serializeRawCondition,
-  skTemplate,
-  validateInlineSnapshotSelect
-} from "./chunk-PFFPLD4B.js";
+  skTemplate
+} from "./chunk-3ZU2VW3L.js";
 import {
   TableMapping,
   createColumnMap,
@@ -69,10 +80,6 @@ function evaluateKey(segmented, scope, presentFields, nameOf = (f) => f, partial
   return { pk, sk: sk?.template };
 }
 
-// src/spec/types.ts
-var SPEC_VERSION = "1.1";
-var MARKER_ROW_ENTITY = "__marker__";
-
 // src/spec/manifest.ts
 var DYNAMO_TYPE_TO_FIELD_TYPE = {
   S: "string",
@@ -220,6 +227,18 @@ function conditionInputToSpec(condition, context, renderLeaf2, renderTreeLeaf, r
     );
   }
   const obj = condition;
+  if (isScpExprConditionInput(obj)) {
+    const siblings = Object.keys(obj).filter((k) => k !== "scpExpr");
+    if (siblings.length > 0) {
+      throw new Error(
+        `${context}: a \`scpExpr\` write condition must be the WHOLE condition object; it cannot be mixed with sibling clauses [${siblings.join(", ")}] (they would be silently dropped). Fold the other clauses into the expression itself (e.g. \`{and: [...]}\`), or keep the condition fully declarative.`
+      );
+    }
+    return {
+      kind: "scpExpr",
+      expression: canonicalizeExpressionSpec(obj.scpExpr, `${context} (scpExpr)`)
+    };
+  }
   if (obj.notExists === true) return { kind: "notExists" };
   if ("attributeExists" in obj && typeof obj.attributeExists === "string") {
     if (obj.attributeExists.length === 0) {
@@ -254,6 +273,13 @@ function assertNotNestedRaw(sub, context) {
     );
   }
 }
+function assertNotNestedScpExpr(sub, context) {
+  if (sub !== null && typeof sub === "object" && !Array.isArray(sub) && "scpExpr" in sub) {
+    throw new Error(
+      `${context}: a \`scpExpr\` write condition may be used as a whole condition, but not nested inside an \`and\` / \`or\` / \`not\` group of a declarative condition tree. Lift the expression to the top level and express the group inside the expression (e.g. \`{and: [...]}\`), or keep the group fully declarative.`
+    );
+  }
+}
 var LOGICAL_KEYS = /* @__PURE__ */ new Set(["and", "or", "not"]);
 var OPERATOR_KEYS = /* @__PURE__ */ new Set([
   "eq",
@@ -310,12 +336,14 @@ function buildTree(obj, context, renderTreeLeaf) {
     if (key === "and" || key === "or") {
       out[key] = value.map((sub) => {
         assertNotNestedRaw(sub, context);
+        assertNotNestedScpExpr(sub, context);
         return buildTree(sub, context, renderTreeLeaf);
       });
       continue;
     }
     if (key === "not") {
       assertNotNestedRaw(value, context);
+      assertNotNestedScpExpr(value, context);
       out[key] = buildTree(
         value,
         context,
@@ -396,6 +424,15 @@ function assertSupportedCondition(commandName, condition) {
     }
     return;
   }
+  if (condition.kind === "scpExpr") {
+    const expression = condition.expression;
+    if (!expression || expression.exprVersion !== EXPR_VERSION || expression.expr === void 0) {
+      throw new Error(
+        `Command '${commandName}' has a malformed scpExpr write condition \u2014 expected \`{ exprVersion: ${EXPR_VERSION}, expr: <node> }\`.`
+      );
+    }
+    return;
+  }
   throw new Error(
     `Command '${commandName}' has an unsupported write condition.`
   );
@@ -2977,14 +3014,14 @@ function renderInputLeaf(leaf, isKeyFieldInPut, consumerIndex, consumerField, re
   if (isMutationInputRef(leaf)) {
     return isKeyFieldInPut ? mintContractKeyFieldRef(leaf.field) : mintContractParamRef(leaf.field);
   }
-  const entityRef3 = parseEntityRef(leaf);
-  if (entityRef3 !== void 0) {
+  const entityRef2 = parseEntityRef(leaf);
+  if (entityRef2 !== void 0) {
     if (resolveEntityRef === null) {
       throw new Error(
-        `mutation: the cross-fragment reference '${entityRef3.path}' is only valid in a MULTI-fragment mutation \u2014 it names a value produced by an earlier fragment, but this mutation has a single fragment (there is no fragment #${entityRef3.fragmentIndex} to read from). Bind '${consumerField}' to a \`$.field\` input reference or a literal instead.`
+        `mutation: the cross-fragment reference '${entityRef2.path}' is only valid in a MULTI-fragment mutation \u2014 it names a value produced by an earlier fragment, but this mutation has a single fragment (there is no fragment #${entityRef2.fragmentIndex} to read from). Bind '${consumerField}' to a \`$.field\` input reference or a literal instead.`
       );
     }
-    return resolveEntityRef(entityRef3, consumerIndex, consumerField);
+    return resolveEntityRef(entityRef2, consumerIndex, consumerField);
   }
   return leaf;
 }
@@ -3266,6 +3303,11 @@ function renderCondition(condition, key, params, context) {
   }
   if (typeof condition === "object" && condition !== null) {
     const obj = condition;
+    if ("scpExpr" in obj) {
+      throw new Error(
+        `Contract runtime: ${context} \u2014 this runtime does not evaluate scpExpr write conditions yet (spec 1.2 expression vocabulary, issue #261); evaluation lands with Phase 3 S5 (#265). Refusing to execute the write with its condition ignored.`
+      );
+    }
     if (obj.notExists === true) return { notExists: true };
     if (typeof obj.attributeExists === "string") {
       return { attributeExists: obj.attributeExists };
@@ -6032,618 +6074,6 @@ function writeDescriptorToPlan(name, d) {
   return { plan: plan2, select, condition, mode: d.mode ?? "transaction", description: d.description };
 }
 
-// src/define/transaction.ts
-var TX_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:txref");
-function isTransactionRef(value) {
-  return typeof value === "object" && value !== null && value[TX_REF_BRAND] === true;
-}
-var MARKER_TAGS = [
-  // pass 0: short, begins with 'A'.
-  "Axqv",
-  // pass 1: long, begins with 'Z'. The two tags share NO common prefix and NO
-  // common substring of length >= 2 (their alphabets are disjoint), and differ
-  // in length, so any fragment-extracting / length-dependent transform
-  // (`slice(0,n)`, `[i]`, `charAt`, `padStart`, `padEnd`) yields *different*
-  // fragments across the two passes -- the differential check then rejects it.
-  // (Convergence-to-constant escapes that even disjoint markers cannot separate
-  // -- `slice(0,0)` -> '' in both passes, `includes('x')` -> a constant boolean
-  // -- are caught instead by the per-access coercion ledger; see
-  // {@link makeFieldRef} and {@link defineTransaction}.)
-  "Zmnoprstuwy0123456789WIDEMARKERBODYFILLERZ"
-];
-var MARKER_PASS_COUNT = MARKER_TAGS.length;
-function markerValue(pass, field) {
-  const tag = MARKER_TAGS[pass];
-  return `${tag}::${field}::${tag}`;
-}
-function makeValueSentinel(fields, tokenFor, originFor, markerFor, containerOrigin, onAccess, onCoerce) {
-  const cache = /* @__PURE__ */ new Map();
-  return new Proxy(/* @__PURE__ */ Object.create(null), {
-    get(_t, key) {
-      if (typeof key === "symbol") {
-        if (key === Symbol.iterator || key === Symbol.asyncIterator || key === Symbol.toStringTag || typeof Symbol.for === "function" && (key === /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom") || key.description === "nodejs.util.inspect.custom")) {
-          return void 0;
-        }
-        throw new Error(
-          `defineTransaction: unsupported symbol access on ${containerOrigin}. Only declarative field references are allowed; any JS transform / branching / coercion on a parameter is not representable as a declarative transaction template.`
-        );
-      }
-      if (!fields.has(key)) {
-        throw new Error(
-          `defineTransaction: ${containerOrigin} has no field '${key}'. Reference only declared fields; arbitrary property access (or any JS transform / branching on a parameter) is not representable as a declarative transaction template.`
-        );
-      }
-      onAccess(key);
-      let ref = cache.get(key);
-      if (!ref) {
-        ref = makeFieldRef(
-          tokenFor(key),
-          originFor(key),
-          markerFor(key),
-          () => onCoerce(key)
-        );
-        cache.set(key, ref);
-      }
-      return ref;
-    },
-    set() {
-      throw new Error(
-        `defineTransaction: cannot assign to a field of ${containerOrigin}.`
-      );
-    },
-    defineProperty() {
-      throw new Error(
-        `defineTransaction: cannot define a property on ${containerOrigin}.`
-      );
-    },
-    deleteProperty() {
-      throw new Error(
-        `defineTransaction: cannot delete a field of ${containerOrigin}.`
-      );
-    }
-  });
-}
-function makeFieldRef(token, origin, marker, onCoerce) {
-  const target = /* @__PURE__ */ Object.create(null);
-  const proxy = new Proxy(target, {
-    get(_t, key) {
-      if (key === TX_REF_BRAND) return true;
-      if (key === "token") return token;
-      if (key === "origin") return origin;
-      if (key === Symbol.toPrimitive) {
-        return (hint) => {
-          onCoerce();
-          return hint === "number" ? NaN : marker;
-        };
-      }
-      if (key === "toString" || key === Symbol.toStringTag) {
-        return () => {
-          onCoerce();
-          return marker;
-        };
-      }
-      if (key === "valueOf") {
-        return () => {
-          onCoerce();
-          return NaN;
-        };
-      }
-      if (key === Symbol.iterator || key === Symbol.asyncIterator || key === "then" || key === "constructor" || key === "prototype" || typeof key === "symbol" && typeof Symbol.for === "function" && (key === /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom") || key.description === "nodejs.util.inspect.custom")) {
-        return void 0;
-      }
-      const name = typeof key === "symbol" ? key.toString() : String(key);
-      throw new Error(
-        `defineTransaction: unsupported operation '${name}' on ${origin}. The static planner (Python bridge) only supports direct field references (\`p.field\` / \`el.field\`) or concrete literals at value positions; any string transform, property access (e.g. \`.length\`, \`[i]\`, \`.toUpperCase()\`), arithmetic, or value branching on a parameter is not representable as a declarative transaction template.`
-      );
-    },
-    set() {
-      throw new Error(`defineTransaction: cannot assign on ${origin}.`);
-    },
-    defineProperty() {
-      throw new Error(`defineTransaction: cannot define a property on ${origin}.`);
-    },
-    deleteProperty() {
-      throw new Error(`defineTransaction: cannot delete on ${origin}.`);
-    }
-  });
-  return proxy;
-}
-var when = {
-  eq(left, right) {
-    assertRef(left, "when.eq");
-    return { op: "eq", left, right };
-  },
-  ne(left, right) {
-    assertRef(left, "when.ne");
-    return { op: "ne", left, right };
-  }
-};
-function assertRef(value, context) {
-  if (!isTransactionRef(value)) {
-    throw new Error(
-      `defineTransaction: ${context} expects a field reference (e.g. \`p.status\` or an element field) on its left-hand side.`
-    );
-  }
-}
-function entityRef2(model) {
-  const modelClass = resolveModelClass(model);
-  return { name: modelClass.name, modelClass };
-}
-function descriptorOf(p) {
-  if (p.kind === "array") {
-    const element = {};
-    for (const [field, fieldParam] of Object.entries(p.element ?? {})) {
-      element[field] = descriptorOf(fieldParam);
-    }
-    return { kind: "array", required: true, element };
-  }
-  return p.literals === void 0 ? { kind: p.kind, required: true } : { kind: p.kind, literals: p.literals, required: true };
-}
-function runBuildPass(params, build, scalarFields, arrayParams, pass, accessed, coerced) {
-  const noteAccess = (token, origin) => {
-    if (!accessed.has(token)) accessed.set(token, { token, origin });
-  };
-  const noteCoerce = (token, origin) => {
-    if (!coerced.has(token)) coerced.set(token, { token, origin });
-  };
-  const scalarSentinel = makeValueSentinel(
-    scalarFields,
-    (f) => `{${f}}`,
-    (f) => `param '${f}'`,
-    (f) => markerValue(pass, f),
-    "params",
-    (f) => noteAccess(`{${f}}`, `param '${f}'`),
-    (f) => noteCoerce(`{${f}}`, `param '${f}'`)
-  );
-  const pProxy = new Proxy(/* @__PURE__ */ Object.create(null), {
-    get(_t, key) {
-      if (typeof key === "symbol") {
-        if (key === Symbol.iterator || key === Symbol.asyncIterator || key === Symbol.toStringTag || typeof Symbol.for === "function" && (key === /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom") || key.description === "nodejs.util.inspect.custom")) {
-          return void 0;
-        }
-        throw new Error("defineTransaction: unsupported symbol access on params.");
-      }
-      if (arrayParams.has(key)) return params[key];
-      if (scalarFields.has(key)) return scalarSentinel[key];
-      throw new Error(
-        `defineTransaction: unknown parameter '${key}'. Declare it in the params map passed to defineTransaction.`
-      );
-    }
-  });
-  const instructions = [];
-  let currentBody = instructions;
-  let insideForEach = false;
-  const recordWrite = (instr) => {
-    currentBody.push(instr);
-  };
-  const recorder2 = {
-    put(model, item, options) {
-      recordWrite({
-        kind: "write",
-        operation: "put",
-        entity: entityRef2(model),
-        item,
-        ...options?.condition !== void 0 ? { condition: options.condition } : {},
-        ...options?.when !== void 0 ? { when: options.when } : {}
-      });
-    },
-    update(model, key, changes, options) {
-      recordWrite({
-        kind: "write",
-        operation: "update",
-        entity: entityRef2(model),
-        key,
-        changes,
-        ...options?.condition !== void 0 ? { condition: options.condition } : {},
-        ...options?.when !== void 0 ? { when: options.when } : {}
-      });
-    },
-    delete(model, key, options) {
-      recordWrite({
-        kind: "write",
-        operation: "delete",
-        entity: entityRef2(model),
-        key,
-        ...options?.condition !== void 0 ? { condition: options.condition } : {},
-        ...options?.when !== void 0 ? { when: options.when } : {}
-      });
-    },
-    conditionCheck(model, key, options) {
-      if (options?.condition === void 0 || options.condition === null) {
-        throw new Error(
-          "defineTransaction: tx.conditionCheck requires a `condition` (the read-only assertion it makes); e.g. `{ condition: { attributeExists: 'PK' } }`."
-        );
-      }
-      recordWrite({
-        kind: "write",
-        operation: "conditionCheck",
-        entity: entityRef2(model),
-        key,
-        condition: options.condition,
-        ...options.when !== void 0 ? { when: options.when } : {}
-      });
-    },
-    forEach(source, body, options) {
-      if (insideForEach) {
-        throw new Error(
-          "defineTransaction: nested forEach is not supported; flatten the loop."
-        );
-      }
-      if (!isParam(source) || source.kind !== "array") {
-        throw new Error(
-          "defineTransaction: forEach source must be a `param.array(...)` parameter accessed via `p.<name>`."
-        );
-      }
-      const arrayParam = source;
-      const sourceName = arrayParams.size ? Object.keys(params).find((k) => params[k] === arrayParam) : void 0;
-      if (sourceName === void 0) {
-        throw new Error(
-          "defineTransaction: forEach source is not a declared array param."
-        );
-      }
-      const elementFields = new Set(Object.keys(arrayParam.element ?? {}));
-      const elementProxy = makeValueSentinel(
-        elementFields,
-        (f) => `{item.${f}}`,
-        (f) => `element field '${f}' of '${sourceName}'`,
-        (f) => markerValue(pass, `item.${f}`),
-        `element of '${sourceName}'`,
-        (f) => noteAccess(`{item.${f}}`, `element field '${f}' of '${sourceName}'`),
-        (f) => noteCoerce(`{item.${f}}`, `element field '${f}' of '${sourceName}'`)
-      );
-      const block = {
-        kind: "forEach",
-        source: sourceName,
-        ...options?.when !== void 0 ? { when: options.when } : {},
-        body: []
-      };
-      const prevBody = currentBody;
-      currentBody = block.body;
-      insideForEach = true;
-      try {
-        body(elementProxy);
-      } finally {
-        insideForEach = false;
-        currentBody = prevBody;
-      }
-      currentBody.push(block);
-    }
-  };
-  build(recorder2, pProxy);
-  return instructions;
-}
-function defineTransaction(params, build) {
-  const descriptors = {};
-  for (const [name, value] of Object.entries(params)) {
-    if (!isParam(value)) {
-      throw new Error(
-        `defineTransaction: param '${name}' is not a param.* placeholder.`
-      );
-    }
-    descriptors[name] = descriptorOf(value);
-  }
-  const scalarFields = new Set(
-    Object.keys(params).filter((k) => params[k].kind !== "array")
-  );
-  const arrayParams = new Set(
-    Object.keys(params).filter((k) => params[k].kind === "array")
-  );
-  const accessed = /* @__PURE__ */ new Map();
-  const coerced = /* @__PURE__ */ new Map();
-  const passes = [];
-  for (let pass = 0; pass < MARKER_PASS_COUNT; pass++) {
-    passes.push(
-      runBuildPass(
-        params,
-        build,
-        scalarFields,
-        arrayParams,
-        pass,
-        accessed,
-        coerced
-      )
-    );
-  }
-  if (coerced.size > 0) {
-    const info = [...coerced.values()][0];
-    throw new Error(
-      `defineTransaction: ${info.origin} is coerced to a primitive (e.g. via \`String(${info.origin.includes("element") ? "el" : "p"}.x)\`, a template literal \`\${\u2026}\`, string concatenation, or a comparison) and then consumed by a transform or branch \u2014 for example \`String(p.x).slice(0, n)\`, \`String(p.x)[0]\`, \`String(p.x).includes('\u2026')\`, or \`\${p.x}-suffix\`. At a value position the static planner (Python bridge) only supports a *direct* field reference (stored without coercion) or a concrete literal; a coerced / transformed parameter is not representable as a declarative transaction template, and (because the transform may converge to a constant or a shared marker fragment) could otherwise be silently emitted as a wrong spec. Reference the field directly (\`p.x\` / \`el.x\`) or use a literal.`
-    );
-  }
-  const surfaced = /* @__PURE__ */ new Set();
-  verifyInstructions(passes, surfaced);
-  for (const [token, info] of accessed) {
-    if (!surfaced.has(token)) {
-      throw new Error(
-        `defineTransaction: ${info.origin} is accessed but never appears as a field reference in the recorded transaction. This happens when a parameter is consumed by a value branch (e.g. \`p.role === 'admin' ? 'A' : 'B'\`) or a string transform (e.g. \`String(p.role).toUpperCase()\`) instead of being referenced directly. The static planner (Python bridge) only supports direct field references or concrete literals at value positions; branching or transforming a parameter is not representable as a declarative transaction template.`
-      );
-    }
-  }
-  return {
-    __isTransactionDefinition: true,
-    params: descriptors,
-    instructions: passes[0]
-  };
-}
-function verifyInstructions(passes, surfaced) {
-  const first = passes[0];
-  for (let i = 0; i < first.length; i++) {
-    const instrs = passes.map((p) => p[i]);
-    const kind = first[i].kind;
-    if (instrs.some((x) => x.kind !== kind)) {
-      throw new Error(
-        "defineTransaction: build is not deterministic across evaluation (instruction shape diverged between passes). The callback must be a pure, declarative description of the writes."
-      );
-    }
-    if (kind === "write") {
-      verifyWrite(instrs, surfaced);
-    } else {
-      const blocks = instrs;
-      verifyWhen(
-        blocks.map((b) => b.when),
-        surfaced,
-        `forEach '${blocks[0].source}' when`
-      );
-      verifyInstructions(
-        blocks.map((b) => b.body),
-        surfaced
-      );
-    }
-  }
-}
-function verifyWrite(instrs, surfaced) {
-  const op = instrs[0].operation;
-  if (instrs.some((x) => x.operation !== op)) {
-    throw new Error(
-      "defineTransaction: write operation diverged between evaluation passes; the callback must be a pure, declarative description of the writes."
-    );
-  }
-  verifyRecord(instrs.map((x) => x.item), surfaced, `${op} item`);
-  verifyRecord(instrs.map((x) => x.key), surfaced, `${op} key`);
-  verifyRecord(instrs.map((x) => x.changes), surfaced, `${op} changes`);
-  verifyCondition(
-    instrs.map((x) => x.condition),
-    surfaced,
-    `${op} condition`
-  );
-  verifyWhen(instrs.map((x) => x.when), surfaced, `${op} when`);
-}
-function verifyRecord(records, surfaced, context) {
-  const present = records.filter((r) => r !== void 0);
-  if (present.length === 0) return;
-  if (present.length !== records.length) {
-    throw new Error(
-      `defineTransaction: ${context} present in some evaluation passes but not others; the callback must be a pure, declarative description.`
-    );
-  }
-  const keys = Object.keys(present[0]).sort();
-  for (const r of present) {
-    const k = Object.keys(r).sort();
-    if (k.length !== keys.length || k.some((x, i) => x !== keys[i])) {
-      throw new Error(
-        `defineTransaction: ${context} field set diverged between evaluation passes; the callback must be a pure, declarative description.`
-      );
-    }
-  }
-  for (const field of keys) {
-    verifyLeaf(
-      present.map((r) => r[field]),
-      surfaced,
-      `${context} field '${field}'`
-    );
-  }
-}
-function isConditionOperatorObject5(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date || isTransactionRef(value)) {
-    return false;
-  }
-  const keys = Object.keys(value);
-  if (keys.length === 0) return false;
-  return keys.every((k) => CONDITION_OPERATOR_KEYS.has(k));
-}
-function verifyCondition(conditions, surfaced, context) {
-  const present = conditions.filter(
-    (c) => c !== void 0 && c !== null
-  );
-  if (present.length === 0) return;
-  if (present.length !== conditions.length) {
-    throw new Error(
-      `defineTransaction: ${context} present in some evaluation passes but not others; the callback must be a pure, declarative description.`
-    );
-  }
-  if (present.some((c) => isRawCondition(c))) return;
-  if (present.some((c) => typeof c !== "object" || Array.isArray(c))) {
-    throw new Error(
-      `defineTransaction: ${context} must be a declarative condition object (field clause / operator object / \`and\` / \`or\` / \`not\` group).`
-    );
-  }
-  verifyConditionTree(
-    present.map((c) => c),
-    surfaced,
-    context
-  );
-}
-function verifyConditionTree(nodes, surfaced, context) {
-  const keys = Object.keys(nodes[0]).sort();
-  for (const n of nodes) {
-    const k = Object.keys(n).sort();
-    if (k.length !== keys.length || k.some((x, i) => x !== keys[i])) {
-      throw new Error(
-        `defineTransaction: ${context} key set diverged between evaluation passes; the callback must be a pure, declarative description.`
-      );
-    }
-  }
-  for (const key of keys) {
-    const values = nodes.map((n) => n[key]);
-    if (key === "and" || key === "or") {
-      const arrays = values.map((v) => {
-        if (!Array.isArray(v) || v.length === 0) {
-          throw new Error(
-            `defineTransaction: ${context} \`${key}\` must be a non-empty array of sub-conditions.`
-          );
-        }
-        return v;
-      });
-      const len = arrays[0].length;
-      if (arrays.some((a) => a.length !== len)) {
-        throw new Error(
-          `defineTransaction: ${context} \`${key}\` length diverged between evaluation passes; the callback must be declarative.`
-        );
-      }
-      for (let i = 0; i < len; i++) {
-        verifyCondition(
-          arrays.map((a) => a[i]),
-          surfaced,
-          `${context} ${key}[${i}]`
-        );
-      }
-      continue;
-    }
-    if (key === "not") {
-      verifyCondition(
-        values,
-        surfaced,
-        `${context} not`
-      );
-      continue;
-    }
-    if (!values.every((v) => isConditionOperatorObject5(v))) {
-      if (values.some((v) => isConditionOperatorObject5(v))) {
-        throw new Error(
-          `defineTransaction: ${context} field '${key}' is an operator object in some evaluation passes but a bare value in others; the callback must be declarative.`
-        );
-      }
-      verifyLeaf(values, surfaced, `${context} field '${key}'`);
-      continue;
-    }
-    verifyOperatorObject(
-      values.map((v) => v),
-      surfaced,
-      `${context} field '${key}'`
-    );
-  }
-}
-function verifyOperatorObject(objs, surfaced, context) {
-  const ops = Object.keys(objs[0]).sort();
-  for (const o of objs) {
-    const k = Object.keys(o).sort();
-    if (k.length !== ops.length || k.some((x, i) => x !== ops[i])) {
-      throw new Error(
-        `defineTransaction: ${context} operator set diverged between evaluation passes; the callback must be a pure, declarative description.`
-      );
-    }
-  }
-  for (const op of ops) {
-    const opVals = objs.map((o) => o[op]);
-    if (op === "between") {
-      const pairs = opVals.map((v) => {
-        if (!Array.isArray(v) || v.length !== 2) {
-          throw new Error(
-            `defineTransaction: ${context} \`between\` takes a \`[lo, hi]\` pair.`
-          );
-        }
-        return v;
-      });
-      verifyLeaf(pairs.map((p) => p[0]), surfaced, `${context} between[0]`);
-      verifyLeaf(pairs.map((p) => p[1]), surfaced, `${context} between[1]`);
-    } else if (op === "in") {
-      const arrays = opVals.map((v) => {
-        if (!Array.isArray(v) || v.length === 0) {
-          throw new Error(
-            `defineTransaction: ${context} \`in\` takes a non-empty array of operands.`
-          );
-        }
-        return v;
-      });
-      const len = arrays[0].length;
-      if (arrays.some((a) => a.length !== len)) {
-        throw new Error(
-          `defineTransaction: ${context} \`in\` length diverged between evaluation passes; the callback must be declarative.`
-        );
-      }
-      for (let i = 0; i < len; i++) {
-        verifyLeaf(arrays.map((a) => a[i]), surfaced, `${context} in[${i}]`);
-      }
-    } else if (op === "attributeExists" || op === "attributeType") {
-      if (opVals.some((v) => isTransactionRef(v))) {
-        throw new Error(
-          `defineTransaction: ${context} \`${op}\` was given a field reference. \`${op}\` takes a ${op === "attributeExists" ? "concrete boolean" : "concrete DynamoDB type-code string"} (a structural operand, not a value-bound param); use a literal.`
-        );
-      }
-    } else {
-      verifyLeaf(opVals, surfaced, `${context} ${op}`);
-    }
-  }
-}
-function verifyWhen(whens, surfaced, context) {
-  const present = whens.filter((w) => w !== void 0);
-  if (present.length === 0) return;
-  if (present.length !== whens.length) {
-    throw new Error(
-      `defineTransaction: ${context} present in some evaluation passes but not others; the callback must be a pure, declarative description.`
-    );
-  }
-  for (const w of present) {
-    if (isTransactionRef(w.left)) surfaced.add(w.left.token);
-  }
-  verifyLeaf(present.map((w) => w.right), surfaced, `${context} right-hand value`);
-}
-function verifyLeaf(values, surfaced, context) {
-  const refTokens = values.map((v) => isTransactionRef(v) ? v.token : void 0);
-  const anyRef = refTokens.some((t) => t !== void 0);
-  if (anyRef) {
-    if (refTokens.some((t) => t === void 0)) {
-      throw new Error(
-        `defineTransaction: ${context} is a field reference in some evaluation passes but a transformed value in others \u2014 a coercion/transform escape (e.g. \`String(p.x).toUpperCase()\`) was applied. Use a direct field reference or a concrete literal.`
-      );
-    }
-    const token = refTokens[0];
-    if (refTokens.some((t) => t !== token)) {
-      throw new Error(
-        `defineTransaction: ${context} resolves to different field references across evaluation passes \u2014 the value is not a stable, declarative reference.`
-      );
-    }
-    surfaced.add(token);
-    return;
-  }
-  const norm = values.map(normalizeLiteral);
-  for (let i = 1; i < norm.length; i++) {
-    if (norm[i] !== norm[0]) {
-      throw new Error(
-        `defineTransaction: ${context} is not a stable concrete literal \u2014 evaluating the callback twice produced different values ('${norm[0]}' vs '${norm[i]}'). This means a parameter was coerced or transformed into the value (e.g. \`String(p.x).toUpperCase()\`, \`\${p.x}-suffix\`, or arithmetic). The static planner (Python bridge) only supports a direct field reference or a concrete literal at a value position.`
-      );
-    }
-  }
-}
-function normalizeLiteral(value) {
-  if (value === null) return "t:null";
-  if (value instanceof Date) return `t:date:${value.toISOString()}`;
-  const t = typeof value;
-  if (t === "string") return `t:s:${value}`;
-  if (t === "boolean") return `t:b:${String(value)}`;
-  if (t === "number") {
-    if (Number.isNaN(value)) {
-      throw new Error(
-        "defineTransaction: a value leaf coerced to NaN, which means arithmetic was performed on a parameter. Only direct field references or concrete literals are allowed at value positions."
-      );
-    }
-    return `t:n:${String(value)}`;
-  }
-  throw new Error(
-    `defineTransaction: a value leaf has unsupported type '${t}'. Only a direct field reference (\`p.field\` / \`el.field\`) or a concrete literal (string / number / boolean / Date) is allowed at a value position.`
-  );
-}
-function defineTransactions(definitions) {
-  for (const [name, def] of Object.entries(definitions)) {
-    if (def === null || typeof def !== "object" || def.__isTransactionDefinition !== true) {
-      throw new Error(
-        `defineTransactions: '${name}' is not a transaction definition. Use defineTransaction(...) to build entries.`
-      );
-    }
-  }
-  return definitions;
-}
-
 // src/spec/transaction.ts
 function paramSpec(d) {
   if (d.kind === "array") {
@@ -6730,10 +6160,66 @@ function keyConditionTemplate2(metadata, keyStructure, context) {
   if (sk !== void 0) out.SK = sk;
   return out;
 }
-function whenSpec(when2) {
-  const left = when2.left.token;
-  const right = leafTemplate(when2.right, "when right-hand value");
-  return { op: when2.op, left, right };
+function walkExpressionRefs(node, visit) {
+  if (node === null || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const el of node) walkExpressionRefs(el, visit);
+    return;
+  }
+  const [key] = Object.keys(node);
+  const arg = node[key];
+  if (key === "ref" || key === "refOpt") {
+    visit(arg);
+    return;
+  }
+  if (key === "obj") {
+    for (const v of Object.values(arg)) {
+      walkExpressionRefs(v, visit);
+    }
+    return;
+  }
+  if (key === "int" || key === "float") return;
+  walkExpressionRefs(arg, visit);
+}
+function assertGuardRefsBound(guard, params, forEachSource, context) {
+  walkExpressionRefs(guard.expr, (path) => {
+    const [scope, field] = path;
+    const rendered = JSON.stringify(path);
+    if (scope !== "input" && scope !== "item") {
+      throw new Error(
+        `${context}: guard reference ${rendered} uses unknown scope '${scope}' \u2014 expression references use the FIXED scope names 'input' (declared params) and 'item' (the forEach element), mirroring the {param} / {item.<field>} template scopes (issue #264).`
+      );
+    }
+    if (field === void 0) {
+      throw new Error(
+        `${context}: guard reference ${rendered} names no field \u2014 a reference path is [scope, field, \u2026] (issue #264).`
+      );
+    }
+    if (scope === "input") {
+      if (params[field] === void 0) {
+        throw new Error(
+          `${context}: guard reference ${rendered} names undeclared input '${field}' \u2014 declared params: ${Object.keys(params).sort().map((p) => `'${p}'`).join(", ") || "(none)"}. Expression input refs and the ParamSpec names are one namespace (issue #264); an unbound reference is a build error, never a runtime leak (#243).`
+        );
+      }
+      return;
+    }
+    if (forEachSource === void 0) {
+      throw new Error(
+        `${context}: guard reference ${rendered} uses the 'item' scope outside a forEach fan-out \u2014 an element reference only exists inside a forEach block (issue #264).`
+      );
+    }
+    const element = params[forEachSource]?.element;
+    if (element === void 0 || element[field] === void 0) {
+      throw new Error(
+        `${context}: guard reference ${rendered} names '${field}', which is not a declared element field of the forEach source '${forEachSource}' \u2014 declared element fields: ${Object.keys(element ?? {}).sort().map((f) => `'${f}'`).join(", ") || "(none)"} (issue #264 single namespace; #243: unbound references are build errors).`
+      );
+    }
+  });
+}
+function whenSpec(when) {
+  const left = when.left.token;
+  const right = leafTemplate(when.right, "when right-hand value");
+  return { op: when.op, left, right };
 }
 function conditionSpec(condition, commandName) {
   const spec = conditionInputToSpec(
@@ -6755,18 +6241,23 @@ var ITEM_TYPE = {
   delete: "Delete",
   conditionCheck: "ConditionCheck"
 };
-function buildWriteItem(instr, forEachSource, txName) {
+function buildWriteItem(instr, forEachSource, txName, params) {
   const metadata = MetadataRegistry.get(instr.entity.modelClass);
   const tableName = TableMapping.resolve(metadata.tableName);
   const entity = instr.entity.name;
   const condition = conditionSpec(instr.condition, `${txName} (${entity})`);
-  const when2 = instr.when ? whenSpec(instr.when) : void 0;
+  const when = instr.when ? whenSpec(instr.when) : void 0;
+  const guard = instr.guard !== void 0 ? canonicalizeExpressionSpec(instr.guard, `${txName} (${entity}) guard`) : void 0;
+  if (guard !== void 0) {
+    assertGuardRefsBound(guard, params, forEachSource, `${txName} (${entity})`);
+  }
   const base = {
     type: ITEM_TYPE[instr.operation],
     tableName,
     entity,
     ...condition ? { condition } : {},
-    ...when2 ? { when: when2 } : {},
+    ...when ? { when } : {},
+    ...guard ? { guard } : {},
     ...forEachSource ? { forEach: { source: forEachSource } } : {}
   };
   if (instr.operation === "put") {
@@ -6846,13 +6337,13 @@ function buildTransactionSpec(txName, def) {
   let hasForEach = false;
   for (const instr of def.instructions) {
     if (instr.kind === "write") {
-      items.push(buildWriteItem(instr, void 0, txName));
+      items.push(buildWriteItem(instr, void 0, txName, def.params));
     } else {
       hasForEach = true;
       const block = instr;
       const blockWhen = block.when ? whenSpec(block.when) : void 0;
       for (const w of block.body) {
-        const item = buildWriteItem(w, block.source, txName);
+        const item = buildWriteItem(w, block.source, txName, def.params);
         items.push(blockWhen && !item.when ? { ...item, when: blockWhen } : item);
       }
     }
@@ -7128,7 +6619,7 @@ function convertCondition(condition, place, context) {
   return out;
 }
 var CONDITION_LOGICAL_KEYS = /* @__PURE__ */ new Set(["and", "or", "not"]);
-function isConditionOperatorObject6(value) {
+function isConditionOperatorObject5(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date || isContractParamRef(value) || isContractKeyFieldRef(value)) {
     return false;
   }
@@ -7139,7 +6630,7 @@ function isConditionOperatorObject6(value) {
 function usesConditionTree(obj) {
   for (const [key, value] of Object.entries(obj)) {
     if (CONDITION_LOGICAL_KEYS.has(key)) return true;
-    if (isConditionOperatorObject6(value)) return true;
+    if (isConditionOperatorObject5(value)) return true;
   }
   return false;
 }
@@ -7157,7 +6648,7 @@ function convertConditionTree(obj, place, context) {
       out[key] = convertConditionTree(value, place, `${context} not`);
       continue;
     }
-    if (!isConditionOperatorObject6(value)) {
+    if (!isConditionOperatorObject5(value)) {
       out[key] = convertLeaf(value, key, place, `${context} field '${key}'`);
       continue;
     }
@@ -8508,14 +7999,17 @@ function buildOperations(queries = {}, commands = {}, transactions = {}, contrac
   mergeSpecs(transactionSpecs, built.transactions, "transaction");
   const contractSpecs = built.contracts;
   const contextSpecs = buildContexts(contextInputMap);
-  return {
-    version: SPEC_VERSION,
+  const content = {
     queries: querySpecs,
     commands: commandSpecs,
     ...Object.keys(transactionSpecs).length > 0 ? { transactions: transactionSpecs } : {},
     ...Object.keys(contractSpecs).length > 0 ? { contracts: contractSpecs } : {},
     ...Object.keys(contextSpecs).length > 0 ? { contexts: contextSpecs } : {}
   };
+  return {
+    version: operationsSpecVersion(content),
+    ...content
+  };
 }
 
 // src/spec/prepared-artifact.ts
@@ -8754,8 +8248,6 @@ function buildBridgeBundle(queries = {}, commands = {}, registry = MetadataRegis
 }
 
 export {
-  SPEC_VERSION,
-  MARKER_ROW_ENTITY,
   buildManifestEntity,
   buildManifest,
   conditionParamName,
@@ -8829,10 +8321,6 @@ export {
   publicQueryModel,
   publicCommandModel,
   isPlannedCommandMethod,
-  isTransactionRef,
-  when,
-  defineTransaction,
-  defineTransactions,
   buildTransactionSpec,
   buildTransactions,
   collectContractN1Violations,