graphddb 0.7.7 → 0.7.9

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

@@ -1,10 +1,12 @@
 import {
   BATCH_GET_MAX_KEYS,
+  CONDITION_OPERATOR_KEYS,
   ChangeCaptureRegistry,
   ClientManager,
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
   NO_MIDDLEWARE,
+  SELECT_SPEC,
   attachHiddenKey,
   attachModelClass,
   buildConditionExpression,
@@ -21,6 +23,7 @@ import {
   chunkArray,
   commitTransaction,
   compileRawCondition,
+  condParamName,
   ctxModelFor,
   detectRelationFields,
   execItemKeySignature,
@@ -49,7 +52,7 @@ import {
   serializeRawCondition,
   skTemplate,
   validateInlineSnapshotSelect
-} from "./chunk-F2DI3GTI.js";
+} from "./chunk-PFFPLD4B.js";
 import {
   TableMapping,
   createColumnMap,
@@ -201,6 +204,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 +487,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 +520,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 +589,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 +638,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 +719,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;
@@ -1512,17 +1755,165 @@ async function executeQueryInner(modelClass, key, selectSpec, options, mw) {
   return hydratedItem;
 }
 
-// src/operations/explain.ts
-function executeExplain(modelClass, key, options) {
-  const metadata = MetadataRegistry.get(modelClass);
-  const exclusiveStartKey = options?.after ? decodeCursor(options.after) : void 0;
-  const normalized = normalizeTopLevelSelect(options?.select);
-  const select = normalized.select ?? {};
-  const filter = options?.filter ?? normalized.filter;
-  const mainPlan = plan(metadata, {
-    key,
-    select,
-    limit: options?.limit,
+// src/runtime/read-plan.ts
+function bindSlots(slots, params) {
+  const out = {};
+  for (const [field, slot] of Object.entries(slots)) {
+    out[field] = slot.kind === "param" ? params[slot.name] : slot.value;
+  }
+  return out;
+}
+function bindOptionalSlot(slot, params) {
+  if (slot === void 0) return void 0;
+  return slot.kind === "param" ? params[slot.name] : slot.value;
+}
+function executeCompiledReadRoute(route, params, options) {
+  const key = bindSlots(route.keySlots, params);
+  const opts = { ...options ?? {} };
+  if (route.kind === "query") {
+    if (route.consistentReadSlot !== void 0) {
+      opts.consistentRead = bindOptionalSlot(route.consistentReadSlot, params);
+    }
+    if (route.maxDepth !== void 0) opts.maxDepth = route.maxDepth;
+    return executeQuery(route.modelClass, key, route.select, opts);
+  }
+  if (route.limitSlot !== void 0) {
+    opts.limit = bindOptionalSlot(route.limitSlot, params);
+  }
+  if (route.afterSlot !== void 0) {
+    opts.after = bindOptionalSlot(route.afterSlot, params);
+  }
+  if (route.order !== void 0) opts.order = route.order;
+  if (route.filter !== void 0) opts.filter = route.filter;
+  return executeList(route.modelClass, key, route.select, opts);
+}
+var MODEL_CLASS_IDS = /* @__PURE__ */ new WeakMap();
+var nextModelClassId = 1;
+function modelClassIdentity(cls) {
+  let id = MODEL_CLASS_IDS.get(cls);
+  if (id === void 0) {
+    id = nextModelClassId++;
+    MODEL_CLASS_IDS.set(cls, id);
+  }
+  return `model#${id}`;
+}
+var BoundedLru = class {
+  constructor(max) {
+    this.max = max;
+  }
+  max;
+  map = /* @__PURE__ */ new Map();
+  get(key) {
+    const v = this.map.get(key);
+    if (v !== void 0) {
+      this.map.delete(key);
+      this.map.set(key, v);
+    }
+    return v;
+  }
+  set(key, value) {
+    if (this.map.has(key)) this.map.delete(key);
+    this.map.set(key, value);
+    if (this.map.size > this.max) {
+      const oldest = this.map.keys().next().value;
+      if (oldest !== void 0) this.map.delete(oldest);
+    }
+  }
+  get size() {
+    return this.map.size;
+  }
+  clear() {
+    this.map.clear();
+  }
+};
+var ADHOC_READ_PLAN_CACHE_MAX = 256;
+var ADHOC_READ_PLAN_CACHE = new BoundedLru(ADHOC_READ_PLAN_CACHE_MAX);
+var adHocCompileCount = 0;
+function shapeToken(value) {
+  if (value === null) return "null";
+  const t = typeof value;
+  if (t === "string") return JSON.stringify(value);
+  if (t === "number" || t === "boolean") return String(value);
+  if (t === "undefined") return "u";
+  if (t === "bigint") return `n${String(value)}`;
+  if (t === "function" || t === "symbol") return null;
+  if (value instanceof Date) return `D${value.getTime()}`;
+  if (Array.isArray(value)) {
+    const parts2 = [];
+    for (const v of value) {
+      const p = shapeToken(v);
+      if (p === null) return null;
+      parts2.push(p);
+    }
+    return `[${parts2.join(",")}]`;
+  }
+  if (isSelectBuilder(value)) {
+    const spec = value[SELECT_SPEC];
+    const inner = shapeToken({
+      select: spec.select,
+      filter: spec.filter,
+      limit: spec.limit,
+      after: spec.after,
+      order: spec.order
+    });
+    return inner === null ? null : `B${inner}`;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return null;
+  const rec = value;
+  const parts = [];
+  for (const k of Object.keys(rec).sort()) {
+    const p = shapeToken(rec[k]);
+    if (p === null) return null;
+    parts.push(`${JSON.stringify(k)}:${p}`);
+  }
+  return `{${parts.join(",")}}`;
+}
+function adHocStructureKey(kind, modelClass, key, select) {
+  const selectToken = shapeToken(select);
+  if (selectToken === null) return null;
+  const fields = Object.keys(key).map((f) => JSON.stringify(f)).join(",");
+  return `${kind}|${modelClassIdentity(modelClass)}|${fields}|${selectToken}`;
+}
+function lowerAdHocReadRoute(kind, modelClass, key, select) {
+  const cacheKey = adHocStructureKey(kind, modelClass, key, select);
+  if (cacheKey !== null) {
+    const cached = ADHOC_READ_PLAN_CACHE.get(cacheKey);
+    if (cached !== void 0) return cached;
+  }
+  adHocCompileCount++;
+  const keySlots = {};
+  for (const field of Object.keys(key)) {
+    keySlots[field] = { kind: "param", name: field };
+  }
+  const route = { alias: "$adhoc", kind, modelClass, select, keySlots };
+  if (cacheKey !== null) ADHOC_READ_PLAN_CACHE.set(cacheKey, route);
+  return route;
+}
+function runAdHoc(route, select, key, options) {
+  const effective = route.select === select ? route : { ...route, select };
+  return executeCompiledReadRoute(effective, key, options);
+}
+function executeAdHocQuery(modelClass, key, selectSpec, options) {
+  const route = lowerAdHocReadRoute("query", modelClass, key, selectSpec);
+  return runAdHoc(route, selectSpec, key, options);
+}
+function executeAdHocList(modelClass, key, selectSpec, options) {
+  const route = lowerAdHocReadRoute("list", modelClass, key, selectSpec);
+  return runAdHoc(route, selectSpec, key, options);
+}
+
+// src/operations/explain.ts
+function executeExplain(modelClass, key, options) {
+  const metadata = MetadataRegistry.get(modelClass);
+  const exclusiveStartKey = options?.after ? decodeCursor(options.after) : void 0;
+  const normalized = normalizeTopLevelSelect(options?.select);
+  const select = normalized.select ?? {};
+  const filter = options?.filter ?? normalized.filter;
+  const mainPlan = plan(metadata, {
+    key,
+    select,
+    limit: options?.limit,
     after: exclusiveStartKey,
     order: options?.order,
     consistentRead: options?.consistentRead,
@@ -2597,6 +2988,53 @@ function renderInputLeaf(leaf, isKeyFieldInPut, consumerIndex, consumerField, re
   }
   return leaf;
 }
+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);
@@ -2609,6 +3047,7 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenan
       );
     }
   }
+  const userCondition = fragment.condition !== void 0 ? lowerFragmentCondition(fragment.condition) : void 0;
   let op;
   if (fragment.intent === "create") {
     const item = {};
@@ -2621,6 +3060,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 +3068,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 +3082,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 +3274,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 +3415,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];
@@ -3930,13 +4422,13 @@ async function executeReadRoute(alias, route) {
   );
   const opt = route.options ?? {};
   if (isQuery) {
-    return executeQuery(modelClass, route.key, route.select, {
+    return executeAdHocQuery(modelClass, route.key, route.select, {
       consistentRead: opt.consistentRead,
       maxDepth: opt.maxDepth,
       context: opt.context
     });
   }
-  return executeList(modelClass, route.key, route.select, {
+  return executeAdHocList(modelClass, route.key, route.select, {
     limit: opt.limit,
     after: opt.after,
     order: opt.order,
@@ -4171,17 +4663,6 @@ function recordSlots(binding, where) {
   }
   return { fields, slots };
 }
-function bindSlots(slots, params) {
-  const out = {};
-  for (const [field, slot] of Object.entries(slots)) {
-    out[field] = slot.kind === "param" ? params[slot.name] : slot.value;
-  }
-  return out;
-}
-function bindOptionalSlot(slot, params) {
-  if (slot === void 0) return void 0;
-  return slot.kind === "param" ? params[slot.name] : slot.value;
-}
 function recordOptionSlot(value, where) {
   if (value === void 0) return void 0;
   if (isPreparedParamRef(value)) return { kind: "param", name: value.name };
@@ -4241,23 +4722,7 @@ var PreparedReadStatement = class {
     return out;
   }
   runRoute(route, params, options) {
-    const key = bindSlots(route.keySlots, params);
-    const consistentRead = bindOptionalSlot(route.consistentReadSlot, params);
-    if (route.kind === "query") {
-      return executeQuery(route.modelClass, key, route.select, {
-        consistentRead,
-        maxDepth: route.maxDepth,
-        ...options.retry !== void 0 ? { retry: options.retry } : {},
-        ...options.context !== void 0 ? { context: options.context } : {}
-      });
-    }
-    const limit = bindOptionalSlot(route.limitSlot, params);
-    const after = bindOptionalSlot(route.afterSlot, params);
-    return executeList(route.modelClass, key, route.select, {
-      limit,
-      after,
-      order: route.order,
-      filter: route.filter,
+    return executeCompiledReadRoute(route, params, {
       ...options.retry !== void 0 ? { retry: options.retry } : {},
       ...options.context !== void 0 ? { context: options.context } : {}
     });
@@ -4421,35 +4886,6 @@ function assertStaticTemplate(value, where) {
   }
 }
 var PREPARE_CACHE_MAX = 256;
-var BoundedLru = class {
-  constructor(max) {
-    this.max = max;
-  }
-  max;
-  map = /* @__PURE__ */ new Map();
-  get(key) {
-    const v = this.map.get(key);
-    if (v !== void 0) {
-      this.map.delete(key);
-      this.map.set(key, v);
-    }
-    return v;
-  }
-  set(key, value) {
-    if (this.map.has(key)) this.map.delete(key);
-    this.map.set(key, value);
-    if (this.map.size > this.max) {
-      const oldest = this.map.keys().next().value;
-      if (oldest !== void 0) this.map.delete(oldest);
-    }
-  }
-  get size() {
-    return this.map.size;
-  }
-  clear() {
-    this.map.clear();
-  }
-};
 var PREPARE_CACHE = new BoundedLru(PREPARE_CACHE_MAX);
 function structureKey(routes) {
   const parts = routes.map(({ alias, route }) => {
@@ -4465,18 +4901,11 @@ function structureKey(routes) {
   });
   return parts.join("||");
 }
-var MODEL_IDENTITY_IDS = /* @__PURE__ */ new WeakMap();
-var nextModelIdentityId = 1;
 function modelIdentity(ref, alias) {
   try {
     const model = resolveModelStatic(ref, alias);
     const cls = resolveModelClass(model);
-    let id = MODEL_IDENTITY_IDS.get(cls);
-    if (id === void 0) {
-      id = nextModelIdentityId++;
-      MODEL_IDENTITY_IDS.set(cls, id);
-    }
-    return `model#${id}`;
+    return modelClassIdentity(cls);
   } catch {
     return "unresolved";
   }
@@ -4776,10 +5205,10 @@ var DDBModel = class {
       // method type — the public overloads (the only caller-visible surface)
       // are untouched.
       query: ((key, select, options) => {
-        return executeQuery(modelClass, key, select, options);
+        return executeAdHocQuery(modelClass, key, select, options);
       }),
       list: ((key, select, options) => {
-        return executeList(modelClass, key, select, options);
+        return executeAdHocList(modelClass, key, select, options);
       }),
       explain(key, options) {
         return executeExplain(
@@ -4945,23 +5374,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");
@@ -5055,7 +5568,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 };
 }
@@ -5375,320 +5888,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
@@ -6060,7 +6401,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`
@@ -6092,6 +6433,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;
@@ -6204,10 +6687,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;
 }
@@ -6280,7 +6772,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") {
@@ -6304,7 +6796,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 ?? {},
@@ -6493,8 +6985,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;
   };
@@ -6568,13 +7060,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;
@@ -6582,24 +7074,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)) {
@@ -6910,6 +7496,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;
@@ -7788,7 +8375,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,
@@ -7816,7 +8403,7 @@ function buildCommandSpec(def) {
     entity,
     params,
     keyCondition: writeKeyCondition(metadata, def.key, entity),
-    changes: templateRecord3(def.changes),
+    changes: templateRecord2(def.changes),
     ...condition ? { condition } : {},
     ...description
   };
@@ -7840,7 +8427,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]);
@@ -8171,6 +8758,10 @@ export {
   MARKER_ROW_ENTITY,
   buildManifestEntity,
   buildManifest,
+  conditionParamName,
+  assertSupportedCondition,
+  assertJsonSerializable,
+  assertBundleSerializable,
   buildProjection,
   compileFilterExpression,
   evaluateFilter,
@@ -8238,10 +8829,6 @@ export {
   publicQueryModel,
   publicCommandModel,
   isPlannedCommandMethod,
-  conditionParamName,
-  assertSupportedCondition,
-  assertJsonSerializable,
-  assertBundleSerializable,
   isTransactionRef,
   when,
   defineTransaction,