graphddb 0.7.6 → 0.7.8

package/dist/{chunk-QOA5MSMD.js → chunk-NZRCBEWS.js}

@@ -1,5 +1,6 @@
 import {
   BATCH_GET_MAX_KEYS,
+  CONDITION_OPERATOR_KEYS,
   ChangeCaptureRegistry,
   ClientManager,
   MAX_TRANSACT_ITEMS,
@@ -21,6 +22,7 @@ import {
   chunkArray,
   commitTransaction,
   compileRawCondition,
+  condParamName,
   ctxModelFor,
   detectRelationFields,
   execItemKeySignature,
@@ -49,7 +51,7 @@ import {
   serializeRawCondition,
   skTemplate,
   validateInlineSnapshotSelect
-} from "./chunk-F2DI3GTI.js";
+} from "./chunk-HFFIB77D.js";
 import {
   TableMapping,
   createColumnMap,
@@ -201,6 +203,246 @@ function buildManifest(registry = MetadataRegistry) {
   };
 }
 
+// src/spec/guard.ts
+function conditionInputToSpec(condition, context, renderLeaf2, renderTreeLeaf, renderRawSlot) {
+  if (condition === void 0 || condition === null) return void 0;
+  if (isRawCondition(condition)) {
+    const { expression, names, values } = serializeRawCondition(
+      condition,
+      renderRawSlot
+    );
+    return { kind: "raw", expression, names, values };
+  }
+  if (typeof condition !== "object") {
+    throw new Error(
+      `${context}: write condition must be an object (\`{ notExists: true }\`, \`{ attributeExists: '<field>' }\`, \`{ attributeNotExists: '<field>' }\`, or a declarative field condition).`
+    );
+  }
+  const obj = condition;
+  if (obj.notExists === true) return { kind: "notExists" };
+  if ("attributeExists" in obj && typeof obj.attributeExists === "string") {
+    if (obj.attributeExists.length === 0) {
+      throw new Error(
+        `${context}: \`attributeExists\` must name a non-empty attribute field.`
+      );
+    }
+    return { kind: "attributeExists", field: obj.attributeExists };
+  }
+  if ("attributeNotExists" in obj) {
+    if (typeof obj.attributeNotExists !== "string" || obj.attributeNotExists.length === 0) {
+      throw new Error(
+        `${context}: \`attributeNotExists\` must name a non-empty attribute field.`
+      );
+    }
+    return { kind: "attributeNotExists", field: obj.attributeNotExists };
+  }
+  if (usesOperatorTree(obj)) {
+    const leaf = renderTreeLeaf ?? ((value, name) => defaultTreeLeaf(value, name, context));
+    return { kind: "expr", declarative: buildTree(obj, context, leaf) };
+  }
+  const fields = {};
+  for (const key of Object.keys(obj).sort()) {
+    fields[key] = renderLeaf2(key, obj[key]);
+  }
+  return { kind: "equals", fields };
+}
+function assertNotNestedRaw(sub, context) {
+  if (isRawCondition(sub)) {
+    throw new Error(
+      `${context}: a raw \`cond\` write condition may be used as a whole condition, but not nested inside an \`and\` / \`or\` / \`not\` group of a serializable (public-contract / Python-bridge) command. Move the \`cond\` to the top level, or express the group declaratively.`
+    );
+  }
+}
+var LOGICAL_KEYS = /* @__PURE__ */ new Set(["and", "or", "not"]);
+var OPERATOR_KEYS = /* @__PURE__ */ new Set([
+  "eq",
+  "ne",
+  "gt",
+  "ge",
+  "lt",
+  "le",
+  "between",
+  "in",
+  "beginsWith",
+  "contains",
+  "notContains",
+  "attributeExists",
+  "attributeType",
+  "size"
+]);
+function isOperatorObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) return false;
+  return keys.every((k) => OPERATOR_KEYS.has(k));
+}
+function usesOperatorTree(obj) {
+  for (const [key, value] of Object.entries(obj)) {
+    if (LOGICAL_KEYS.has(key)) return true;
+    if (isOperatorObject(value)) return true;
+  }
+  return false;
+}
+function defaultTreeLeaf(value, name, context) {
+  void name;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  throw new Error(
+    `${context}: condition operand must be a concrete literal or a param; got ${typeof value}.`
+  );
+}
+function conditionParamName(field, op, index) {
+  if (op === "between") return `${field}_${index === 0 ? "lo" : "hi"}`;
+  if (op === "in") return `${field}_${index ?? 0}`;
+  if (op === "size") return `${field}_size`;
+  return field;
+}
+function buildTree(obj, context, renderTreeLeaf) {
+  const out = {};
+  for (const key of Object.keys(obj).sort()) {
+    const value = obj[key];
+    if (value === void 0) continue;
+    if (key === "and" || key === "or") {
+      out[key] = value.map((sub) => {
+        assertNotNestedRaw(sub, context);
+        return buildTree(sub, context, renderTreeLeaf);
+      });
+      continue;
+    }
+    if (key === "not") {
+      assertNotNestedRaw(value, context);
+      out[key] = buildTree(
+        value,
+        context,
+        renderTreeLeaf
+      );
+      continue;
+    }
+    if (!isOperatorObject(value)) {
+      out[key] = { eq: renderTreeLeaf(value, conditionParamName(key, "eq")) };
+      continue;
+    }
+    const ops = value;
+    const rendered = {};
+    for (const op of Object.keys(ops).sort()) {
+      const opVal = ops[op];
+      if (op === "between") {
+        const [lo, hi] = opVal;
+        rendered[op] = [
+          renderTreeLeaf(lo, conditionParamName(key, op, 0)),
+          renderTreeLeaf(hi, conditionParamName(key, op, 1))
+        ];
+      } else if (op === "in") {
+        rendered[op] = opVal.map(
+          (v, i) => renderTreeLeaf(v, conditionParamName(key, op, i))
+        );
+      } else if (op === "attributeExists") {
+        rendered[op] = opVal;
+      } else if (op === "attributeType") {
+        rendered[op] = String(opVal);
+      } else {
+        rendered[op] = renderTreeLeaf(opVal, conditionParamName(key, op));
+      }
+    }
+    out[key] = rendered;
+  }
+  return out;
+}
+function assertSupportedCondition(commandName, condition) {
+  if (condition.kind === "notExists") return;
+  if (condition.kind === "attributeExists" || condition.kind === "attributeNotExists") {
+    if (typeof condition.field !== "string" || condition.field.length === 0) {
+      throw new Error(
+        `Command '${commandName}' has an ${condition.kind} write condition with no attribute field. The Python bridge requires a non-empty field name.`
+      );
+    }
+    return;
+  }
+  if (condition.kind === "equals") {
+    const entries = Object.entries(condition.fields);
+    if (entries.length === 0) {
+      throw new Error(
+        `Command '${commandName}' has an empty equality write condition. The Python bridge supports '{ notExists }' or non-empty field equality conditions only.`
+      );
+    }
+    for (const [field, value] of entries) {
+      if (typeof value !== "string") {
+        throw new Error(
+          `Command '${commandName}' write condition on '${field}' must be a template string value; the Python bridge supports equality on param/literal values only.`
+        );
+      }
+    }
+    return;
+  }
+  if (condition.kind === "raw") {
+    if (typeof condition.expression !== "string" || condition.expression.length === 0) {
+      throw new Error(
+        `Command '${commandName}' has an empty raw \`cond\` write condition.`
+      );
+    }
+    return;
+  }
+  if (condition.kind === "expr") {
+    const tree = condition.declarative;
+    if (!tree || Object.keys(tree).length === 0) {
+      throw new Error(
+        `Command '${commandName}' has an empty declarative write condition.`
+      );
+    }
+    return;
+  }
+  throw new Error(
+    `Command '${commandName}' has an unsupported write condition.`
+  );
+}
+function assertJsonSerializable(value, path = "$") {
+  if (value === null) return;
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return;
+    case "number":
+      if (!Number.isFinite(value)) {
+        throw new Error(
+          `Bridge spec is not JSON-serializable: non-finite number at ${path}.`
+        );
+      }
+      return;
+    case "object":
+      break;
+    default:
+      throw new Error(
+        `Bridge spec is not JSON-serializable: '${typeof value}' at ${path}.`
+      );
+  }
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => assertJsonSerializable(v, `${path}[${i}]`));
+    return;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) {
+    throw new Error(
+      `Bridge spec is not JSON-serializable: non-plain object (${value.constructor?.name ?? "unknown"}) at ${path}.`
+    );
+  }
+  for (const [k, v] of Object.entries(value)) {
+    if (v === void 0) {
+      throw new Error(
+        `Bridge spec is not JSON-serializable: 'undefined' value at ${path}.${k}.`
+      );
+    }
+    assertJsonSerializable(v, `${path}.${k}`);
+  }
+}
+function assertBundleSerializable(bundle) {
+  assertJsonSerializable(bundle.manifest, "$.manifest");
+  assertJsonSerializable(bundle.operations, "$.operations");
+}
+
 // src/planner/projection.ts
 function buildProjection(select, additionalFields) {
   const paths = [];
@@ -244,8 +486,8 @@ function buildProjection(select, additionalFields) {
 }
 
 // src/expression/filter-expression.ts
-var LOGICAL_KEYS = /* @__PURE__ */ new Set(["and", "or", "not"]);
-var OPERATOR_KEYS = /* @__PURE__ */ new Set([
+var LOGICAL_KEYS2 = /* @__PURE__ */ new Set(["and", "or", "not"]);
+var OPERATOR_KEYS2 = /* @__PURE__ */ new Set([
   "eq",
   "ne",
   "gt",
@@ -277,7 +519,7 @@ function valueAlias(ctx, field, raw) {
 }
 function compileField(ctx, field, condition) {
   const nAlias = nameAlias(ctx, field);
-  if (!isOperatorObject(condition)) {
+  if (!isOperatorObject2(condition)) {
     const vAlias = valueAlias(ctx, field, condition);
     return `${nAlias} = ${vAlias}`;
   }
@@ -346,13 +588,13 @@ function compileField(ctx, field, condition) {
   }
   return joinAnd(clauses);
 }
-function isOperatorObject(value) {
+function isOperatorObject2(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date || value instanceof Uint8Array || value instanceof Set) {
     return false;
   }
   const keys = Object.keys(value);
   if (keys.length === 0) return false;
-  return keys.every((k) => OPERATOR_KEYS.has(k));
+  return keys.every((k) => OPERATOR_KEYS2.has(k));
 }
 function joinAnd(clauses) {
   if (clauses.length === 1) return clauses[0];
@@ -395,7 +637,7 @@ function compileNode(ctx, node) {
   const clauses = [];
   for (const [key, value] of Object.entries(node)) {
     if (value === void 0) continue;
-    if (LOGICAL_KEYS.has(key)) {
+    if (LOGICAL_KEYS2.has(key)) {
       if (key === "and" || key === "or") {
         const parts = value.map((sub) => compileNode(ctx, sub)).filter((s) => s.length > 0);
         if (parts.length === 0) continue;
@@ -476,7 +718,7 @@ function eq(a, b) {
   return a === b;
 }
 function evaluateFieldCondition(actual, item, field, condition) {
-  if (!isOperatorObject(condition)) {
+  if (!isOperatorObject2(condition)) {
     return eq(actual, condition);
   }
   const ops = condition;
@@ -2597,18 +2839,66 @@ function renderInputLeaf(leaf, isKeyFieldInPut, consumerIndex, consumerField, re
   }
   return leaf;
 }
-function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenanceGraph) {
-  const keyFields = primaryKeyFields(fragment);
-  const keyFieldSet = new Set(keyFields);
-  const operation = INTENT_OPERATION[fragment.intent];
-  const lifecycle = resolveLifecycle(fragment);
-  for (const field of keyFields) {
-    if (!(field in fragment.input)) {
-      throw new Error(
-        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' must bind the primary-key field '${field}' in its \`input\` (it identifies the row), e.g. \`{ ${field}: $.${field}, \u2026 }\`.`
-      );
-    }
+function isConditionOperatorObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date || isMutationInputRef(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) return false;
+  return keys.every((k) => CONDITION_OPERATOR_KEYS.has(k));
+}
+function lowerConditionLeaf(leaf) {
+  if (isMutationInputRef(leaf)) return mintContractParamRef(leaf.field);
+  return leaf;
+}
+function lowerFragmentCondition(condition) {
+  const obj = condition;
+  const out = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === void 0) continue;
+    if (key === "and" || key === "or") {
+      out[key] = value.map((sub) => lowerFragmentCondition(sub));
+      continue;
+    }
+    if (key === "not") {
+      out[key] = lowerFragmentCondition(value);
+      continue;
+    }
+    if (!isConditionOperatorObject(value)) {
+      out[key] = lowerConditionLeaf(value);
+      continue;
+    }
+    const ops = value;
+    const rendered = {};
+    for (const [op, opVal] of Object.entries(ops)) {
+      if (op === "between") {
+        const [lo, hi] = opVal;
+        rendered[op] = [lowerConditionLeaf(lo), lowerConditionLeaf(hi)];
+      } else if (op === "in") {
+        rendered[op] = opVal.map((v) => lowerConditionLeaf(v));
+      } else if (op === "attributeExists" || op === "attributeType") {
+        rendered[op] = opVal;
+      } else {
+        rendered[op] = lowerConditionLeaf(opVal);
+      }
+    }
+    out[key] = rendered;
+  }
+  return out;
+}
+function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenanceGraph) {
+  const keyFields = primaryKeyFields(fragment);
+  const keyFieldSet = new Set(keyFields);
+  const operation = INTENT_OPERATION[fragment.intent];
+  const lifecycle = resolveLifecycle(fragment);
+  for (const field of keyFields) {
+    if (!(field in fragment.input)) {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' must bind the primary-key field '${field}' in its \`input\` (it identifies the row), e.g. \`{ ${field}: $.${field}, \u2026 }\`.`
+      );
+    }
   }
+  const userCondition = fragment.condition !== void 0 ? lowerFragmentCondition(fragment.condition) : void 0;
   let op;
   if (fragment.intent === "create") {
     const item = {};
@@ -2621,6 +2911,7 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenan
         resolveEntityRef
       );
     }
+    const condition = userCondition !== void 0 ? { and: [{ PK: { attributeExists: false } }, userCondition] } : { notExists: true };
     op = {
       __isContractMethodOp: true,
       entity: fragment.entity,
@@ -2628,9 +2919,7 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenan
       keys: wholeKeysSentinel(),
       // a `put` derives identity from the item.
       item,
-      // The base `create` op guards against clobbering an existing row, exactly as
-      // the proposal specifies (create → Put `attribute_not_exists(PK)`).
-      condition: { notExists: true }
+      condition
     };
   } else {
     const changes = {};
@@ -2644,7 +2933,11 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenan
       operation,
       keys: wholeKeysSentinel(),
       keyFields,
-      ...fragment.intent === "update" ? { changes } : {}
+      ...fragment.intent === "update" ? { changes } : {},
+      // #242: a conditioned update / remove — the write is a CAS-style gate (the
+      // row must satisfy the condition or the write is rejected, not silently
+      // committed). Absent → an unconditional update / remove (unchanged).
+      ...userCondition !== void 0 ? { condition: userCondition } : {}
     };
   }
   const conditionChecks = lifecycle?.effects.requires !== void 0 && lifecycle.effects.requires.length > 0 ? deriveConditionChecks(fragment, lifecycle.effects.requires) : void 0;
@@ -2832,13 +3125,62 @@ function renderCondition(condition, key, params, context) {
       return { attributeNotExists: obj.attributeNotExists };
     }
   }
-  return renderRecord(
+  return renderConditionTree(
     condition,
     key,
     params,
     `${context} condition`
   );
 }
+function isConditionOperatorObject2(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date || isContractParamRef(value) || isContractKeyFieldRef(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) return false;
+  return keys.every((k) => CONDITION_OPERATOR_KEYS.has(k));
+}
+function renderConditionTree(node, key, params, context) {
+  const out = {};
+  for (const [k, value] of Object.entries(node)) {
+    if (value === void 0) continue;
+    if (k === "and" || k === "or") {
+      out[k] = value.map(
+        (sub) => renderConditionTree(sub, key, params, `${context} ${k}`)
+      );
+      continue;
+    }
+    if (k === "not") {
+      out[k] = renderConditionTree(value, key, params, `${context} not`);
+      continue;
+    }
+    if (!isConditionOperatorObject2(value)) {
+      out[k] = renderLeaf(value, key, params, `${context} field '${k}'`);
+      continue;
+    }
+    const ops = value;
+    const rendered = {};
+    for (const [op, opVal] of Object.entries(ops)) {
+      if (op === "between") {
+        const [lo, hi] = opVal;
+        rendered[op] = [
+          renderLeaf(lo, key, params, `${context} field '${k}' between[0]`),
+          renderLeaf(hi, key, params, `${context} field '${k}' between[1]`)
+        ];
+      } else if (op === "in") {
+        rendered[op] = opVal.map(
+          (v, i) => renderLeaf(v, key, params, `${context} field '${k}' in[${i}]`)
+        );
+      } else if (op === "attributeExists" || op === "attributeType") {
+        rendered[op] = opVal;
+      } else {
+        rendered[op] = renderLeaf(opVal, key, params, `${context} field '${k}' ${op}`);
+      }
+    }
+    out[k] = rendered;
+  }
+  return out;
+}
 function renderWrite(op, key, params, contextLabel) {
   if (!isContractKeyRef(op.keys) && op.operation !== "put") {
     throw new Error(
@@ -2924,6 +3266,7 @@ function renderConditionCheck(check, key, params, contextLabel) {
 }
 var RUNTIME_TOKEN_RE = /\{([^{}]+)\}/g;
 function renderTemplate(template, key, params, contextLabel) {
+  if (typeof template !== "string") return template;
   const resolveToken = (token) => {
     if (token in params) return params[token];
     if (token in key) return key[token];
@@ -4579,6 +4922,19 @@ var DDBModel = class {
   static setClient(client) {
     ClientManager.setClient(client);
   }
+  /**
+   * Read back the registered `DynamoDBClient` — the resolved client last passed to
+   * {@link setClient}. Symmetric with {@link setClient} and backed by the same
+   * {@link ClientManager} store, so it always reflects the client GraphDDB sends
+   * through.
+   *
+   * Throws a clear error if no client has been registered yet (call
+   * {@link setClient} first) — matching {@link ClientManager.getClient}'s "loud,
+   * never silently `undefined`" convention shared with the rest of the client API.
+   */
+  static getClient() {
+    return ClientManager.getClient();
+  }
   static setTableMapping(mapping) {
     TableMapping.set(mapping);
   }
@@ -4932,23 +5288,107 @@ function assertFaithfulInput(input, intent, entityName) {
   }
   return input;
 }
+function isConditionOperatorObject3(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date || isMutationInputRef(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) return false;
+  return keys.every((k) => CONDITION_OPERATOR_KEYS.has(k));
+}
+function assertFaithfulConditionLeaf(leaf, intent, entityName, where) {
+  if (isMutationInputRef(leaf) || isConcreteLiteral(leaf)) return;
+  if (isAliasFieldRef(leaf)) {
+    throw new Error(
+      `mutation: the '${intent}' fragment on '${entityName}' uses a \`$.alias.field\` cross-fragment reference in its \`condition\` (${where}). A write condition gates a single row against the command INPUT (or the row's own persisted attributes) \u2014 a \`TransactWriteItems\` cannot read another item's value mid-transaction to gate this write. Use a \`$.field\` input reference or a literal.`
+    );
+  }
+  throw new Error(
+    `mutation: the '${intent}' fragment on '${entityName}' binds a \`condition\` operand (${where}) to a value that is neither a \`$.field\` input reference nor a concrete literal. A write condition is declarative \u2014 only \`$.field\` references or literals are allowed, never a computed value.`
+  );
+}
+function assertFaithfulCondition(condition, intent, entityName) {
+  if (condition === null || typeof condition !== "object" || Array.isArray(condition)) {
+    throw new Error(
+      `mutation: the '${intent}' fragment on '${entityName}' has a non-object \`condition\`. A write condition is a declarative field-clause / logical-group object (e.g. \`{ status: 'PENDING', version: { in: [$.v] } }\` or \`{ and: [ \u2026 ] }\`).`
+    );
+  }
+  const obj = condition;
+  if (Object.keys(obj).length === 0) {
+    throw new Error(
+      `mutation: the '${intent}' fragment on '${entityName}' declared an EMPTY \`condition\` object. Omit \`condition\` entirely for an unconditional write, or declare a real gate.`
+    );
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === void 0) continue;
+    if (key === "and" || key === "or") {
+      if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(
+          `mutation: the '${intent}' fragment on '${entityName}' \`condition\` \`${key}\` must be a non-empty array of sub-conditions.`
+        );
+      }
+      for (const sub of value) assertFaithfulCondition(sub, intent, entityName);
+      continue;
+    }
+    if (key === "not") {
+      assertFaithfulCondition(value, intent, entityName);
+      continue;
+    }
+    if (!isConditionOperatorObject3(value)) {
+      assertFaithfulConditionLeaf(value, intent, entityName, `field '${key}'`);
+      continue;
+    }
+    const ops = value;
+    for (const [op, opVal] of Object.entries(ops)) {
+      if (op === "between") {
+        if (!Array.isArray(opVal) || opVal.length !== 2) {
+          throw new Error(
+            `mutation: the '${intent}' fragment on '${entityName}' \`condition\` field '${key}' \`between\` takes a \`[lo, hi]\` pair.`
+          );
+        }
+        assertFaithfulConditionLeaf(opVal[0], intent, entityName, `field '${key}' between[0]`);
+        assertFaithfulConditionLeaf(opVal[1], intent, entityName, `field '${key}' between[1]`);
+      } else if (op === "in") {
+        if (!Array.isArray(opVal) || opVal.length === 0) {
+          throw new Error(
+            `mutation: the '${intent}' fragment on '${entityName}' \`condition\` field '${key}' \`in\` takes a non-empty array of operands.`
+          );
+        }
+        opVal.forEach(
+          (v, i) => assertFaithfulConditionLeaf(v, intent, entityName, `field '${key}' in[${i}]`)
+        );
+      } else if (op === "attributeExists" || op === "attributeType") {
+        if (isMutationInputRef(opVal)) {
+          throw new Error(
+            `mutation: the '${intent}' fragment on '${entityName}' \`condition\` field '${key}' \`${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 {
+        assertFaithfulConditionLeaf(opVal, intent, entityName, `field '${key}' ${op}`);
+      }
+    }
+  }
+  return condition;
+}
 function isConcreteLiteral(value) {
   const t = typeof value;
   return value === null || value instanceof Date || t === "string" || t === "number" || t === "boolean";
 }
-function makeFragment(intent, entity, input, use) {
+function makeFragment(intent, entity, input, use, condition) {
   const checked = assertFaithfulInput(input ?? {}, intent, entity.name);
   if (use !== void 0 && !isEntityWritesDefinition(use)) {
     throw new Error(
       `mutation: the '${intent}' fragment on '${entity.name}' was given a \`use:\` that is not an \`entityWrites(...)\` save contract. \`use:\` takes the WHOLE \`writes\` set (an \`entityWrites(...)\` value), never a single lifecycle (e.g. \`Model.writes.create\`) \u2014 the fragment's intent already selects the lifecycle.`
     );
   }
+  const checkedCondition = condition !== void 0 ? assertFaithfulCondition(condition, intent, entity.name) : void 0;
   return {
     [FRAGMENT_BRAND]: true,
     intent,
     entity,
     input: checked,
-    ...use !== void 0 ? { use } : {}
+    ...use !== void 0 ? { use } : {},
+    ...checkedCondition !== void 0 ? { condition: checkedCondition } : {}
   };
 }
 var COMMAND_PLAN_BRAND = /* @__PURE__ */ Symbol("graphddb:commandPlan");
@@ -5042,7 +5482,7 @@ function mutation(nameOrBody, maybeBody) {
     const { intent, entity } = resolveDescriptorTarget(descriptor, alias);
     const merged = mergeBindings(descriptor, intent, alias);
     const resolved = resolveAliasRefs(merged, aliasToIndex, alias);
-    return makeFragment(intent, entity, resolved, descriptor.use);
+    return makeFragment(intent, entity, resolved, descriptor.use, descriptor.condition);
   });
   return { [COMMAND_PLAN_BRAND]: true, name, fragments };
 }
@@ -5362,320 +5802,148 @@ function descriptorKeyRecord(record, name, what) {
   }
   return out;
 }
-function descriptorConditionRecord(record, name) {
-  const out = {};
-  for (const [field, leaf] of Object.entries(record)) {
-    if (isParam(leaf)) {
-      out[field] = mintContractParamRef(field);
-    } else {
-      out[field] = leaf;
-    }
-  }
-  return out;
-}
-function readDescriptorToOp(name, d) {
-  const isQuery = d.query !== void 0;
-  const isList = d.list !== void 0;
-  if (isQuery === isList) {
-    throw new Error(
-      `publicQueryModel: method '${name}' must carry exactly one of \`query\` or \`list\` (the target model); it declared ${isQuery && isList ? "both" : "neither"}.`
-    );
-  }
-  if (d.key === void 0 || d.select === void 0) {
-    throw new Error(
-      `publicQueryModel: the '${isQuery ? "query" : "list"}' descriptor for method '${name}' must declare both \`key\` and \`select\`.`
-    );
-  }
-  const model = resolveDescriptorModel(isQuery ? d.query : d.list, name);
-  const entity = entityRef(model);
-  const operation = isQuery ? "query" : "list";
-  const keyFieldNames2 = Object.keys(d.key);
-  const keyRecord = descriptorKeyRecord(d.key, name, `${operation} key`);
-  const { select, compose } = extractCompose({ ...d.select }, operation, entity.name);
-  const keys = isQuery ? wholeKeysSentinel() : keyRecord;
-  return {
-    __isContractMethodOp: true,
-    entity,
-    operation,
-    keys,
-    ...isQuery ? { keyFields: keyFieldNames2 } : {},
-    ...select !== void 0 ? { select } : {},
-    ...compose.length > 0 ? { compose } : {},
-    ...d.description !== void 0 ? { description: d.description } : {}
-  };
-}
-function writeDescriptorToPlan(name, d) {
-  const present = WRITE_INTENT_KEYS.filter((k) => d[k] !== void 0);
-  if (present.length !== 1) {
-    throw new Error(
-      `publicCommandModel: method '${name}' must carry exactly one intent key (\`create\` / \`update\` / \`remove\`), but declared ${present.length === 0 ? "none" : present.join(", ")}.`
-    );
-  }
-  const intent = present[0];
-  if (d.key === void 0 || d.key === null || typeof d.key !== "object") {
-    throw new Error(
-      `publicCommandModel: the '${intent}' descriptor for method '${name}' must declare a \`key\` object binding the target's primary-key fields.`
-    );
-  }
-  const model = resolveDescriptorModel(d[intent], name);
-  const keyFieldNames2 = Object.keys(d.key);
-  const inputFieldNames = d.input !== void 0 ? Object.keys(d.input) : [];
-  const plan2 = mutation(name, ($) => {
-    const refMap = (fields) => {
-      const out = {};
-      for (const f of fields) out[f] = $[f];
-      return out;
-    };
-    const descriptor = {
-      [intent]: (() => model),
-      key: refMap(keyFieldNames2),
-      ...inputFieldNames.length > 0 ? { input: refMap(inputFieldNames) } : {}
-    };
-    return { [name]: descriptor };
-  });
-  const select = d.result !== void 0 && d.result.select !== void 0 ? d.result.select : void 0;
-  const condition = d.condition !== void 0 ? descriptorConditionRecord(d.condition, name) : void 0;
-  return { plan: plan2, select, condition, mode: d.mode ?? "transaction", description: d.description };
-}
-
-// src/spec/guard.ts
-function conditionInputToSpec(condition, context, renderLeaf2, renderTreeLeaf, renderRawSlot) {
-  if (condition === void 0 || condition === null) return void 0;
-  if (isRawCondition(condition)) {
-    const { expression, names, values } = serializeRawCondition(
-      condition,
-      renderRawSlot
-    );
-    return { kind: "raw", expression, names, values };
-  }
-  if (typeof condition !== "object") {
-    throw new Error(
-      `${context}: write condition must be an object (\`{ notExists: true }\`, \`{ attributeExists: '<field>' }\`, \`{ attributeNotExists: '<field>' }\`, or a declarative field condition).`
-    );
-  }
-  const obj = condition;
-  if (obj.notExists === true) return { kind: "notExists" };
-  if ("attributeExists" in obj && typeof obj.attributeExists === "string") {
-    if (obj.attributeExists.length === 0) {
-      throw new Error(
-        `${context}: \`attributeExists\` must name a non-empty attribute field.`
-      );
-    }
-    return { kind: "attributeExists", field: obj.attributeExists };
-  }
-  if ("attributeNotExists" in obj) {
-    if (typeof obj.attributeNotExists !== "string" || obj.attributeNotExists.length === 0) {
-      throw new Error(
-        `${context}: \`attributeNotExists\` must name a non-empty attribute field.`
-      );
-    }
-    return { kind: "attributeNotExists", field: obj.attributeNotExists };
-  }
-  if (usesOperatorTree(obj)) {
-    const leaf = renderTreeLeaf ?? ((value, name) => defaultTreeLeaf(value, name, context));
-    return { kind: "expr", declarative: buildTree(obj, context, leaf) };
-  }
-  const fields = {};
-  for (const key of Object.keys(obj).sort()) {
-    fields[key] = renderLeaf2(key, obj[key]);
-  }
-  return { kind: "equals", fields };
-}
-function assertNotNestedRaw(sub, context) {
-  if (isRawCondition(sub)) {
-    throw new Error(
-      `${context}: a raw \`cond\` write condition may be used as a whole condition, but not nested inside an \`and\` / \`or\` / \`not\` group of a serializable (public-contract / Python-bridge) command. Move the \`cond\` to the top level, or express the group declaratively.`
-    );
-  }
-}
-var LOGICAL_KEYS2 = /* @__PURE__ */ new Set(["and", "or", "not"]);
-var OPERATOR_KEYS2 = /* @__PURE__ */ new Set([
-  "eq",
-  "ne",
-  "gt",
-  "ge",
-  "lt",
-  "le",
-  "between",
-  "in",
-  "beginsWith",
-  "contains",
-  "notContains",
-  "attributeExists",
-  "attributeType",
-  "size"
-]);
-function isOperatorObject2(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date) {
+function isConditionOperatorObject4(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date || isParam(value) || isContractParamRef(value) || isContractKeyFieldRef(value)) {
     return false;
   }
   const keys = Object.keys(value);
   if (keys.length === 0) return false;
-  return keys.every((k) => OPERATOR_KEYS2.has(k));
+  return keys.every((k) => CONDITION_OPERATOR_KEYS.has(k));
 }
-function usesOperatorTree(obj) {
-  for (const [key, value] of Object.entries(obj)) {
-    if (LOGICAL_KEYS2.has(key)) return true;
-    if (isOperatorObject2(value)) return true;
-  }
-  return false;
+function mintConditionOperand(leaf, field, op, index) {
+  if (isParam(leaf)) return mintContractParamRef(conditionParamName(field, op, index));
+  return leaf;
 }
-function defaultTreeLeaf(value, name, context) {
-  void name;
-  if (value instanceof Date) return value.toISOString();
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-    return value;
-  }
-  throw new Error(
-    `${context}: condition operand must be a concrete literal or a param; got ${typeof value}.`
-  );
+function mintRawConditionParams(raw) {
+  let paramIndex = 0;
+  const parts = raw.parts.map((part) => {
+    if (isColumn(part)) return part;
+    if (isParam(part)) return mintContractParamRef(condParamName(paramIndex++));
+    return part;
+  });
+  return { ...raw, parts };
 }
-function conditionParamName(field, op, index) {
-  if (op === "between") return `${field}_${index === 0 ? "lo" : "hi"}`;
-  if (op === "in") return `${field}_${index ?? 0}`;
-  if (op === "size") return `${field}_size`;
-  return field;
+function descriptorConditionRecord(record, name) {
+  if (isRawCondition(record)) {
+    return mintRawConditionParams(record);
+  }
+  const top = record;
+  if (top.notExists === true || typeof top.attributeExists === "string" || typeof top.attributeNotExists === "string") {
+    return { ...top };
+  }
+  return descriptorConditionTree(top, name, `publicCommandModel: method '${name}' condition`);
 }
-function buildTree(obj, context, renderTreeLeaf) {
+function descriptorConditionTree(obj, name, context) {
   const out = {};
-  for (const key of Object.keys(obj).sort()) {
-    const value = obj[key];
+  for (const [key, value] of Object.entries(obj)) {
     if (value === void 0) continue;
     if (key === "and" || key === "or") {
       out[key] = value.map((sub) => {
-        assertNotNestedRaw(sub, context);
-        return buildTree(sub, context, renderTreeLeaf);
+        assertNoNestedRawCond(sub, name);
+        return descriptorConditionTree(sub, name, `${context} ${key}`);
       });
       continue;
     }
     if (key === "not") {
-      assertNotNestedRaw(value, context);
-      out[key] = buildTree(
-        value,
-        context,
-        renderTreeLeaf
-      );
+      assertNoNestedRawCond(value, name);
+      out[key] = descriptorConditionTree(value, name, `${context} not`);
       continue;
     }
-    if (!isOperatorObject2(value)) {
-      out[key] = { eq: renderTreeLeaf(value, conditionParamName(key, "eq")) };
+    if (!isConditionOperatorObject4(value)) {
+      out[key] = mintConditionOperand(value, key, "eq");
       continue;
     }
     const ops = value;
     const rendered = {};
-    for (const op of Object.keys(ops).sort()) {
-      const opVal = ops[op];
+    for (const [op, opVal] of Object.entries(ops)) {
       if (op === "between") {
         const [lo, hi] = opVal;
         rendered[op] = [
-          renderTreeLeaf(lo, conditionParamName(key, op, 0)),
-          renderTreeLeaf(hi, conditionParamName(key, op, 1))
+          mintConditionOperand(lo, key, op, 0),
+          mintConditionOperand(hi, key, op, 1)
         ];
       } else if (op === "in") {
-        rendered[op] = opVal.map(
-          (v, i) => renderTreeLeaf(v, conditionParamName(key, op, i))
-        );
-      } else if (op === "attributeExists") {
+        rendered[op] = opVal.map((v, i) => mintConditionOperand(v, key, op, i));
+      } else if (op === "attributeExists" || op === "attributeType") {
         rendered[op] = opVal;
-      } else if (op === "attributeType") {
-        rendered[op] = String(opVal);
-      } else {
-        rendered[op] = renderTreeLeaf(opVal, conditionParamName(key, op));
-      }
-    }
-    out[key] = rendered;
-  }
-  return out;
-}
-function assertSupportedCondition(commandName, condition) {
-  if (condition.kind === "notExists") return;
-  if (condition.kind === "attributeExists" || condition.kind === "attributeNotExists") {
-    if (typeof condition.field !== "string" || condition.field.length === 0) {
-      throw new Error(
-        `Command '${commandName}' has an ${condition.kind} write condition with no attribute field. The Python bridge requires a non-empty field name.`
-      );
-    }
-    return;
-  }
-  if (condition.kind === "equals") {
-    const entries = Object.entries(condition.fields);
-    if (entries.length === 0) {
-      throw new Error(
-        `Command '${commandName}' has an empty equality write condition. The Python bridge supports '{ notExists }' or non-empty field equality conditions only.`
-      );
-    }
-    for (const [field, value] of entries) {
-      if (typeof value !== "string") {
-        throw new Error(
-          `Command '${commandName}' write condition on '${field}' must be a template string value; the Python bridge supports equality on param/literal values only.`
-        );
+      } else {
+        rendered[op] = mintConditionOperand(opVal, key, op);
       }
     }
-    return;
-  }
-  if (condition.kind === "raw") {
-    if (typeof condition.expression !== "string" || condition.expression.length === 0) {
-      throw new Error(
-        `Command '${commandName}' has an empty raw \`cond\` write condition.`
-      );
-    }
-    return;
+    out[key] = rendered;
   }
-  if (condition.kind === "expr") {
-    const tree = condition.declarative;
-    if (!tree || Object.keys(tree).length === 0) {
-      throw new Error(
-        `Command '${commandName}' has an empty declarative write condition.`
-      );
-    }
-    return;
+  return out;
+}
+function assertNoNestedRawCond(sub, name) {
+  if (isRawCondition(sub)) {
+    throw new Error(
+      `publicCommandModel: method '${name}' condition nests a raw \`cond\` fragment inside an \`and\` / \`or\` / \`not\` group, which is not serializable. Use a \`cond\` as the whole condition, or express the group with declarative operators.`
+    );
   }
-  throw new Error(
-    `Command '${commandName}' has an unsupported write condition.`
-  );
 }
-function assertJsonSerializable(value, path = "$") {
-  if (value === null) return;
-  switch (typeof value) {
-    case "string":
-    case "boolean":
-      return;
-    case "number":
-      if (!Number.isFinite(value)) {
-        throw new Error(
-          `Bridge spec is not JSON-serializable: non-finite number at ${path}.`
-        );
-      }
-      return;
-    case "object":
-      break;
-    default:
-      throw new Error(
-        `Bridge spec is not JSON-serializable: '${typeof value}' at ${path}.`
-      );
+function readDescriptorToOp(name, d) {
+  const isQuery = d.query !== void 0;
+  const isList = d.list !== void 0;
+  if (isQuery === isList) {
+    throw new Error(
+      `publicQueryModel: method '${name}' must carry exactly one of \`query\` or \`list\` (the target model); it declared ${isQuery && isList ? "both" : "neither"}.`
+    );
   }
-  if (Array.isArray(value)) {
-    value.forEach((v, i) => assertJsonSerializable(v, `${path}[${i}]`));
-    return;
+  if (d.key === void 0 || d.select === void 0) {
+    throw new Error(
+      `publicQueryModel: the '${isQuery ? "query" : "list"}' descriptor for method '${name}' must declare both \`key\` and \`select\`.`
+    );
   }
-  const proto = Object.getPrototypeOf(value);
-  if (proto !== Object.prototype && proto !== null) {
+  const model = resolveDescriptorModel(isQuery ? d.query : d.list, name);
+  const entity = entityRef(model);
+  const operation = isQuery ? "query" : "list";
+  const keyFieldNames2 = Object.keys(d.key);
+  const keyRecord = descriptorKeyRecord(d.key, name, `${operation} key`);
+  const { select, compose } = extractCompose({ ...d.select }, operation, entity.name);
+  const keys = isQuery ? wholeKeysSentinel() : keyRecord;
+  return {
+    __isContractMethodOp: true,
+    entity,
+    operation,
+    keys,
+    ...isQuery ? { keyFields: keyFieldNames2 } : {},
+    ...select !== void 0 ? { select } : {},
+    ...compose.length > 0 ? { compose } : {},
+    ...d.description !== void 0 ? { description: d.description } : {}
+  };
+}
+function writeDescriptorToPlan(name, d) {
+  const present = WRITE_INTENT_KEYS.filter((k) => d[k] !== void 0);
+  if (present.length !== 1) {
     throw new Error(
-      `Bridge spec is not JSON-serializable: non-plain object (${value.constructor?.name ?? "unknown"}) at ${path}.`
+      `publicCommandModel: method '${name}' must carry exactly one intent key (\`create\` / \`update\` / \`remove\`), but declared ${present.length === 0 ? "none" : present.join(", ")}.`
     );
   }
-  for (const [k, v] of Object.entries(value)) {
-    if (v === void 0) {
-      throw new Error(
-        `Bridge spec is not JSON-serializable: 'undefined' value at ${path}.${k}.`
-      );
-    }
-    assertJsonSerializable(v, `${path}.${k}`);
+  const intent = present[0];
+  if (d.key === void 0 || d.key === null || typeof d.key !== "object") {
+    throw new Error(
+      `publicCommandModel: the '${intent}' descriptor for method '${name}' must declare a \`key\` object binding the target's primary-key fields.`
+    );
   }
-}
-function assertBundleSerializable(bundle) {
-  assertJsonSerializable(bundle.manifest, "$.manifest");
-  assertJsonSerializable(bundle.operations, "$.operations");
+  const model = resolveDescriptorModel(d[intent], name);
+  const keyFieldNames2 = Object.keys(d.key);
+  const inputFieldNames = d.input !== void 0 ? Object.keys(d.input) : [];
+  const plan2 = mutation(name, ($) => {
+    const refMap = (fields) => {
+      const out = {};
+      for (const f of fields) out[f] = $[f];
+      return out;
+    };
+    const descriptor = {
+      [intent]: (() => model),
+      key: refMap(keyFieldNames2),
+      ...inputFieldNames.length > 0 ? { input: refMap(inputFieldNames) } : {}
+    };
+    return { [name]: descriptor };
+  });
+  const select = d.result !== void 0 && d.result.select !== void 0 ? d.result.select : void 0;
+  const condition = d.condition !== void 0 ? descriptorConditionRecord(d.condition, name) : void 0;
+  return { plan: plan2, select, condition, mode: d.mode ?? "transaction", description: d.description };
 }
 
 // src/define/transaction.ts
@@ -6047,7 +6315,7 @@ function verifyWrite(instrs, surfaced) {
   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`);
-  verifyRecord(
+  verifyCondition(
     instrs.map((x) => x.condition),
     surfaced,
     `${op} condition`
@@ -6079,6 +6347,148 @@ function verifyRecord(records, surfaced, context) {
     );
   }
 }
+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;
@@ -6191,10 +6601,19 @@ function conditionTreeLeaf(value, name, context) {
     `defineTransaction: ${context} condition operand must be a field reference (from \`p\` or a forEach element) or a concrete literal; got ${typeof value}.`
   );
 }
-function templateRecord2(structure, context) {
+function valueLeaf(value, context) {
+  if (isTransactionRef(value)) return value.token;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (typeof value === "string") return value;
+  throw new Error(
+    `defineTransaction: ${context} must be a field reference (from \`p\` or a forEach element) or a concrete literal; got ${typeof value}.`
+  );
+}
+function valueRecord(structure, context) {
   const out = {};
   for (const field of Object.keys(structure).sort()) {
-    out[field] = leafTemplate(structure[field], `${context} field '${field}'`);
+    out[field] = valueLeaf(structure[field], `${context} field '${field}'`);
   }
   return out;
 }
@@ -6267,7 +6686,7 @@ function buildWriteItem(instr, forEachSource, txName) {
   if (instr.operation === "put") {
     return {
       ...base,
-      item: templateRecord2(instr.item ?? {}, `${txName} put`)
+      item: valueRecord(instr.item ?? {}, `${txName} put`)
     };
   }
   if (instr.operation === "delete") {
@@ -6291,7 +6710,7 @@ function buildWriteItem(instr, forEachSource, txName) {
       )
     };
   }
-  const changes = templateRecord2(instr.changes ?? {}, `${txName} update changes`);
+  const changes = valueRecord(instr.changes ?? {}, `${txName} update changes`);
   injectTransactionGsiRederive(
     metadata,
     instr.key ?? {},
@@ -6480,8 +6899,8 @@ function recoverKind(metadata, fieldName) {
 function opToDefinition(contractName, methodName, op) {
   const metadata = MetadataRegistry.get(op.entity.modelClass);
   const params = {};
-  const place = (paramName, bindField) => {
-    const recovered = recoverKind(metadata, bindField);
+  const place = (paramName, bindField, kindOverride) => {
+    const recovered = kindOverride !== void 0 ? { kind: kindOverride } : recoverKind(metadata, bindField);
     params[paramName] = recovered.literals === void 0 ? { kind: recovered.kind, required: true } : { kind: recovered.kind, literals: recovered.literals, required: true };
     return recovered;
   };
@@ -6555,13 +6974,13 @@ function convertStructure(structure, place, context) {
   }
   return out;
 }
-function convertLeaf(leaf, bindField, place, context) {
+function convertLeaf(leaf, bindField, place, context, kindOverride) {
   if (isContractParamRef(leaf)) {
-    place(leaf.field, bindField);
+    place(leaf.field, bindField, kindOverride);
     return leaf;
   }
   if (isContractKeyFieldRef(leaf)) {
-    place(leaf.field, bindField);
+    place(leaf.field, bindField, kindOverride);
     return leaf;
   }
   if (isConcreteLiteral3(leaf)) return leaf;
@@ -6569,24 +6988,118 @@ function convertLeaf(leaf, bindField, place, context) {
     `${context}: value is neither a param/key reference nor a concrete literal \u2014 it cannot be serialized as a declarative contract operation.`
   );
 }
+function nearestColumnFields(condition) {
+  const parts = condition.parts;
+  const columnAt = (i) => isColumn(parts[i]) ? parts[i].name : void 0;
+  const out = [];
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (!isContractParamRef(part) && !isContractKeyFieldRef(part)) continue;
+    let found;
+    for (let d = 1; d < parts.length && found === void 0; d++) {
+      found = columnAt(i - d) ?? columnAt(i + d);
+    }
+    out.push(found);
+  }
+  return out;
+}
 function convertCondition(condition, place, context) {
-  if (isRawCondition(condition)) return condition;
+  if (isRawCondition(condition)) {
+    const compareFieldForSlot = nearestColumnFields(condition);
+    let slotIndex = 0;
+    for (const part of condition.parts) {
+      if (isContractParamRef(part) || isContractKeyFieldRef(part)) {
+        const compareField = compareFieldForSlot[slotIndex];
+        if (compareField === void 0) {
+          throw new Error(
+            `${context}: a raw \`cond\` value slot ('${part.field}') has no adjacent column, so its param type cannot be inferred. A \`cond\` param slot must be compared against a \`Model.col.<field>\` reference (e.g. \`cond\`\${Model.col.x} < \${param.number()}\`\`) so the parameter inherits that column's type; refusing to emit an un-typed (silently 'string') param.`
+          );
+        }
+        place(part.field, compareField);
+        slotIndex++;
+      }
+    }
+    return condition;
+  }
   if (typeof condition === "object" && condition !== null) {
-    const obj = condition;
-    if (obj.notExists === true) return { notExists: true };
-    if (typeof obj.attributeExists === "string") {
-      return { attributeExists: obj.attributeExists };
+    const obj2 = condition;
+    if (obj2.notExists === true) return { notExists: true };
+    if (typeof obj2.attributeExists === "string") {
+      return { attributeExists: obj2.attributeExists };
     }
-    if (typeof obj.attributeNotExists === "string") {
-      return { attributeNotExists: obj.attributeNotExists };
+    if (typeof obj2.attributeNotExists === "string") {
+      return { attributeNotExists: obj2.attributeNotExists };
     }
   }
+  const obj = condition;
+  if (usesConditionTree(obj)) {
+    return convertConditionTree(obj, place, context);
+  }
   const out = {};
-  for (const [field, leaf] of Object.entries(condition)) {
+  for (const [field, leaf] of Object.entries(obj)) {
     out[field] = convertLeaf(leaf, field, place, `${context} field '${field}'`);
   }
   return out;
 }
+var CONDITION_LOGICAL_KEYS = /* @__PURE__ */ new Set(["and", "or", "not"]);
+function isConditionOperatorObject6(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date || isContractParamRef(value) || isContractKeyFieldRef(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) return false;
+  return keys.every((k) => CONDITION_OPERATOR_KEYS.has(k));
+}
+function usesConditionTree(obj) {
+  for (const [key, value] of Object.entries(obj)) {
+    if (CONDITION_LOGICAL_KEYS.has(key)) return true;
+    if (isConditionOperatorObject6(value)) return true;
+  }
+  return false;
+}
+function convertConditionTree(obj, place, context) {
+  const out = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === void 0) continue;
+    if (key === "and" || key === "or") {
+      out[key] = value.map(
+        (sub) => convertConditionTree(sub, place, `${context} ${key}`)
+      );
+      continue;
+    }
+    if (key === "not") {
+      out[key] = convertConditionTree(value, place, `${context} not`);
+      continue;
+    }
+    if (!isConditionOperatorObject6(value)) {
+      out[key] = convertLeaf(value, key, place, `${context} field '${key}'`);
+      continue;
+    }
+    const ops = value;
+    const rendered = {};
+    for (const [op, opVal] of Object.entries(ops)) {
+      if (op === "between") {
+        const [lo, hi] = opVal;
+        rendered[op] = [
+          convertLeaf(lo, key, place, `${context} field '${key}' between[0]`),
+          convertLeaf(hi, key, place, `${context} field '${key}' between[1]`)
+        ];
+      } else if (op === "in") {
+        rendered[op] = opVal.map(
+          (v, i) => convertLeaf(v, key, place, `${context} field '${key}' in[${i}]`)
+        );
+      } else if (op === "attributeExists" || op === "attributeType") {
+        rendered[op] = opVal;
+      } else if (op === "size") {
+        rendered[op] = convertLeaf(opVal, key, place, `${context} field '${key}' ${op}`, "number");
+      } else {
+        rendered[op] = convertLeaf(opVal, key, place, `${context} field '${key}' ${op}`);
+      }
+    }
+    out[key] = rendered;
+  }
+  return out;
+}
 function assertBooleanProjection(select, context) {
   const out = {};
   for (const [field, leaf] of Object.entries(select)) {
@@ -6897,6 +7410,7 @@ var TEMPLATE_TOKEN_RE = /\{([^{}]+)\}/g;
 function collectTemplateParams(record, metadata, out) {
   if (record === void 0) return;
   for (const template of Object.values(record)) {
+    if (typeof template !== "string") continue;
     for (const match of template.matchAll(TEMPLATE_TOKEN_RE)) {
       const token = match[1];
       const field = token.startsWith("old.") ? token.slice("old.".length) : token;
@@ -7775,7 +8289,7 @@ function buildCommandSpec(def) {
   const condition = extractCondition(def);
   const description = def.description !== void 0 ? { description: def.description } : {};
   if (def.operation === "put") {
-    const item = templateRecord3(def.key);
+    const item = templateRecord2(def.key);
     return {
       type: "PutItem",
       tableName,
@@ -7803,7 +8317,7 @@ function buildCommandSpec(def) {
     entity,
     params,
     keyCondition: writeKeyCondition(metadata, def.key, entity),
-    changes: templateRecord3(def.changes),
+    changes: templateRecord2(def.changes),
     ...condition ? { condition } : {},
     ...description
   };
@@ -7827,7 +8341,7 @@ function writeKeyCondition(metadata, key, entity) {
   if (sk !== void 0) out.SK = sk;
   return out;
 }
-function templateRecord3(structure) {
+function templateRecord2(structure) {
   const out = {};
   for (const key of Object.keys(structure).sort()) {
     out[key] = templateLeaf(key, structure[key]);
@@ -8158,6 +8672,10 @@ export {
   MARKER_ROW_ENTITY,
   buildManifestEntity,
   buildManifest,
+  conditionParamName,
+  assertSupportedCondition,
+  assertJsonSerializable,
+  assertBundleSerializable,
   buildProjection,
   compileFilterExpression,
   evaluateFilter,
@@ -8225,10 +8743,6 @@ export {
   publicQueryModel,
   publicCommandModel,
   isPlannedCommandMethod,
-  conditionParamName,
-  assertSupportedCondition,
-  assertJsonSerializable,
-  assertBundleSerializable,
   isTransactionRef,
   when,
   defineTransaction,