graphddb 0.7.8 → 0.7.10

package/dist/chunk-3UD3XIF2.js

@@ -0,0 +1,860 @@
+import {
+  CONDITION_OPERATOR_KEYS,
+  isParam,
+  isRawCondition,
+  resolveModelClass
+} from "./chunk-3ZU2VW3L.js";
+
+// src/spec/types.ts
+var SPEC_VERSION = "1.1";
+var SPEC_VERSION_SCP = "1.2";
+var SPEC_VERSION_SUPPORTED = SPEC_VERSION_SCP;
+var EXPR_VERSION = 1;
+var MARKER_ROW_ENTITY = "__marker__";
+
+// src/spec/expression.ts
+var UNARY_OPS = /* @__PURE__ */ new Set(["neg", "not", "len"]);
+var BINARY_OPS = /* @__PURE__ */ new Set([
+  "add",
+  "sub",
+  "mul",
+  "div",
+  "mod",
+  "concat",
+  "eq",
+  "ne",
+  "lt",
+  "le",
+  "gt",
+  "ge",
+  "and",
+  "or",
+  "coalesce"
+]);
+var TERNARY_OPS = /* @__PURE__ */ new Set(["cond"]);
+var ALL_OPS = /* @__PURE__ */ new Set([...UNARY_OPS, ...BINARY_OPS, ...TERNARY_OPS]);
+var I64_MIN = -(2n ** 63n);
+var I64_MAX = 2n ** 63n - 1n;
+function cmpCodePoints(a, b) {
+  const ia = a[Symbol.iterator]();
+  const ib = b[Symbol.iterator]();
+  for (; ; ) {
+    const ra = ia.next();
+    const rb = ib.next();
+    if (ra.done && rb.done) return 0;
+    if (ra.done) return -1;
+    if (rb.done) return 1;
+    const ca = ra.value.codePointAt(0);
+    const cb = rb.value.codePointAt(0);
+    if (ca !== cb) return ca < cb ? -1 : 1;
+  }
+}
+function invalid(context, path, message) {
+  throw new Error(`${context}: invalid SCP expression at ${path}: ${message}`);
+}
+function isPlainObject(v) {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+function canonicalizeNode(node, context, path) {
+  if (node === null) return null;
+  if (typeof node === "string" || typeof node === "boolean") return node;
+  if (typeof node === "number") {
+    if (!Number.isFinite(node)) {
+      invalid(context, path, `non-finite number literal (${node}).`);
+    }
+    if (Number.isInteger(node) && !Number.isSafeInteger(node)) {
+      invalid(
+        context,
+        path,
+        `integral number literal ${node} exceeds the safe-integer range; carry it as {int:"${node}"} (expression-ir.md \xA72.3).`
+      );
+    }
+    return node;
+  }
+  if (Array.isArray(node)) {
+    invalid(context, path, "a bare array is not an expression (use {arr:[\u2026]}).");
+  }
+  if (!isPlainObject(node)) {
+    invalid(context, path, `expected a literal or a single-key node object.`);
+  }
+  const keys = Object.keys(node);
+  if (keys.length !== 1) {
+    invalid(
+      context,
+      path,
+      `a node object must have exactly one key, got [${keys.join(", ")}].`
+    );
+  }
+  const key = keys[0];
+  const arg = node[key];
+  if (key === "int") {
+    if (typeof arg !== "string" || !/^-?[0-9]+$/.test(arg)) {
+      invalid(context, `${path}.int`, '{int:"\u2026"} expects an integer string.');
+    }
+    const v = BigInt(arg);
+    if (v < I64_MIN || v > I64_MAX) {
+      invalid(context, `${path}.int`, `int literal ${arg} exceeds i64.`);
+    }
+    if (v >= BigInt(Number.MIN_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER)) {
+      return Number(v);
+    }
+    return { int: v.toString() };
+  }
+  if (key === "float") {
+    if (typeof arg !== "number" || !Number.isFinite(arg)) {
+      invalid(context, `${path}.float`, "{float:n} expects a finite number.");
+    }
+    return Number.isInteger(arg) ? { float: arg } : arg;
+  }
+  if (key === "ref" || key === "refOpt") {
+    if (!Array.isArray(arg) || arg.length === 0) {
+      invalid(context, `${path}.${key}`, `{${key}:[\u2026]} expects a non-empty path array.`);
+    }
+    const segs = arg.map((seg, i) => {
+      if (typeof seg !== "string" || seg.length === 0) {
+        invalid(
+          context,
+          `${path}.${key}[${i}]`,
+          "a reference path segment must be a non-empty string."
+        );
+      }
+      return seg;
+    });
+    return key === "ref" ? { ref: segs } : { refOpt: segs };
+  }
+  if (key === "obj") {
+    if (!isPlainObject(arg)) {
+      invalid(context, `${path}.obj`, "{obj:{\u2026}} expects a plain object.");
+    }
+    const out = {};
+    for (const k of Object.keys(arg).sort(cmpCodePoints)) {
+      out[k] = canonicalizeNode(arg[k], context, `${path}.obj.${k}`);
+    }
+    return { obj: out };
+  }
+  if (key === "arr") {
+    if (!Array.isArray(arg)) {
+      invalid(context, `${path}.arr`, "{arr:[\u2026]} expects an array.");
+    }
+    return {
+      arr: arg.map((el, i) => canonicalizeNode(el, context, `${path}.arr[${i}]`))
+    };
+  }
+  if (!ALL_OPS.has(key)) {
+    invalid(
+      context,
+      path,
+      `unknown operator '${key}' \u2014 outside the Expression IR v1 closed set.`
+    );
+  }
+  const op = key;
+  if (!Array.isArray(arg)) {
+    invalid(context, `${path}.${op}`, `'${op}' expects an argument array.`);
+  }
+  const arity = UNARY_OPS.has(op) ? 1 : TERNARY_OPS.has(op) ? 3 : 2;
+  if (arg.length !== arity) {
+    invalid(
+      context,
+      `${path}.${op}`,
+      `'${op}' expects ${arity} argument(s), got ${arg.length}.`
+    );
+  }
+  const args = arg.map((a, i) => canonicalizeNode(a, context, `${path}.${op}[${i}]`));
+  return { [op]: args };
+}
+function canonicalizeExpressionSpec(input, context) {
+  if (!isPlainObject(input)) {
+    throw new Error(
+      `${context}: an SCP expression must be a plain \`{ exprVersion: 1, expr: <node> }\` object.`
+    );
+  }
+  const keys = Object.keys(input).sort();
+  if (keys.length !== 2 || keys[0] !== "expr" || keys[1] !== "exprVersion") {
+    throw new Error(
+      `${context}: an SCP expression envelope must have exactly the keys \`exprVersion\` and \`expr\`; got [${Object.keys(input).join(", ")}].`
+    );
+  }
+  if (input.exprVersion !== EXPR_VERSION) {
+    throw new Error(
+      `${context}: unsupported exprVersion ${JSON.stringify(input.exprVersion)} \u2014 this build understands exprVersion ${EXPR_VERSION} only (fail-closed).`
+    );
+  }
+  return {
+    exprVersion: EXPR_VERSION,
+    expr: canonicalizeNode(input.expr, context, "$")
+  };
+}
+function isScpExprConditionInput(condition) {
+  return "scpExpr" in condition;
+}
+function conditionHasScp(condition) {
+  return condition?.kind === "scpExpr";
+}
+function operationsContainScpNodes(doc) {
+  for (const command of Object.values(doc.commands)) {
+    if (conditionHasScp(command.condition)) return true;
+  }
+  for (const transaction of Object.values(doc.transactions ?? {})) {
+    for (const item of transaction.items) {
+      if (item.guard !== void 0 || conditionHasScp(item.condition)) return true;
+    }
+  }
+  for (const contract of Object.values(doc.contracts ?? {})) {
+    if (contract.kind !== "command") continue;
+    for (const method of Object.values(contract.methods)) {
+      if (method.guard !== void 0) return true;
+    }
+  }
+  return false;
+}
+function operationsSpecVersion(doc) {
+  return operationsContainScpNodes(doc) ? SPEC_VERSION_SCP : SPEC_VERSION;
+}
+
+// src/define/transaction.ts
+var TX_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:txref");
+function isTransactionRef(value) {
+  return typeof value === "object" && value !== null && value[TX_REF_BRAND] === true;
+}
+var MARKER_TAGS = [
+  // pass 0: short, begins with 'A'.
+  "Axqv",
+  // pass 1: long, begins with 'Z'. The two tags share NO common prefix and NO
+  // common substring of length >= 2 (their alphabets are disjoint), and differ
+  // in length, so any fragment-extracting / length-dependent transform
+  // (`slice(0,n)`, `[i]`, `charAt`, `padStart`, `padEnd`) yields *different*
+  // fragments across the two passes -- the differential check then rejects it.
+  // (Convergence-to-constant escapes that even disjoint markers cannot separate
+  // -- `slice(0,0)` -> '' in both passes, `includes('x')` -> a constant boolean
+  // -- are caught instead by the per-access coercion ledger; see
+  // {@link makeFieldRef} and {@link defineTransaction}.)
+  "Zmnoprstuwy0123456789WIDEMARKERBODYFILLERZ"
+];
+var MARKER_PASS_COUNT = MARKER_TAGS.length;
+function markerValue(pass, field) {
+  const tag = MARKER_TAGS[pass];
+  return `${tag}::${field}::${tag}`;
+}
+function makeValueSentinel(fields, tokenFor, originFor, markerFor, containerOrigin, onAccess, onCoerce) {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(_t, key) {
+      if (typeof key === "symbol") {
+        if (key === Symbol.iterator || key === Symbol.asyncIterator || key === Symbol.toStringTag || typeof Symbol.for === "function" && (key === /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom") || key.description === "nodejs.util.inspect.custom")) {
+          return void 0;
+        }
+        throw new Error(
+          `defineTransaction: unsupported symbol access on ${containerOrigin}. Only declarative field references are allowed; any JS transform / branching / coercion on a parameter is not representable as a declarative transaction template.`
+        );
+      }
+      if (!fields.has(key)) {
+        throw new Error(
+          `defineTransaction: ${containerOrigin} has no field '${key}'. Reference only declared fields; arbitrary property access (or any JS transform / branching on a parameter) is not representable as a declarative transaction template.`
+        );
+      }
+      onAccess(key);
+      let ref = cache.get(key);
+      if (!ref) {
+        ref = makeFieldRef(
+          tokenFor(key),
+          originFor(key),
+          markerFor(key),
+          () => onCoerce(key)
+        );
+        cache.set(key, ref);
+      }
+      return ref;
+    },
+    set() {
+      throw new Error(
+        `defineTransaction: cannot assign to a field of ${containerOrigin}.`
+      );
+    },
+    defineProperty() {
+      throw new Error(
+        `defineTransaction: cannot define a property on ${containerOrigin}.`
+      );
+    },
+    deleteProperty() {
+      throw new Error(
+        `defineTransaction: cannot delete a field of ${containerOrigin}.`
+      );
+    }
+  });
+}
+function makeFieldRef(token, origin, marker, onCoerce) {
+  const target = /* @__PURE__ */ Object.create(null);
+  const proxy = new Proxy(target, {
+    get(_t, key) {
+      if (key === TX_REF_BRAND) return true;
+      if (key === "token") return token;
+      if (key === "origin") return origin;
+      if (key === Symbol.toPrimitive) {
+        return (hint) => {
+          onCoerce();
+          return hint === "number" ? NaN : marker;
+        };
+      }
+      if (key === "toString" || key === Symbol.toStringTag) {
+        return () => {
+          onCoerce();
+          return marker;
+        };
+      }
+      if (key === "valueOf") {
+        return () => {
+          onCoerce();
+          return NaN;
+        };
+      }
+      if (key === Symbol.iterator || key === Symbol.asyncIterator || key === "then" || key === "constructor" || key === "prototype" || typeof key === "symbol" && typeof Symbol.for === "function" && (key === /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom") || key.description === "nodejs.util.inspect.custom")) {
+        return void 0;
+      }
+      const name = typeof key === "symbol" ? key.toString() : String(key);
+      throw new Error(
+        `defineTransaction: unsupported operation '${name}' on ${origin}. The static planner (Python bridge) only supports direct field references (\`p.field\` / \`el.field\`) or concrete literals at value positions; any string transform, property access (e.g. \`.length\`, \`[i]\`, \`.toUpperCase()\`), arithmetic, or value branching on a parameter is not representable as a declarative transaction template.`
+      );
+    },
+    set() {
+      throw new Error(`defineTransaction: cannot assign on ${origin}.`);
+    },
+    defineProperty() {
+      throw new Error(`defineTransaction: cannot define a property on ${origin}.`);
+    },
+    deleteProperty() {
+      throw new Error(`defineTransaction: cannot delete on ${origin}.`);
+    }
+  });
+  return proxy;
+}
+var when = {
+  eq(left, right) {
+    assertRef(left, "when.eq");
+    return { op: "eq", left, right };
+  },
+  ne(left, right) {
+    assertRef(left, "when.ne");
+    return { op: "ne", left, right };
+  }
+};
+function assertRef(value, context) {
+  if (!isTransactionRef(value)) {
+    throw new Error(
+      `defineTransaction: ${context} expects a field reference (e.g. \`p.status\` or an element field) on its left-hand side.`
+    );
+  }
+}
+function entityRef(model) {
+  const modelClass = resolveModelClass(model);
+  return { name: modelClass.name, modelClass };
+}
+function descriptorOf(p) {
+  if (p.kind === "array") {
+    const element = {};
+    for (const [field, fieldParam] of Object.entries(p.element ?? {})) {
+      element[field] = descriptorOf(fieldParam);
+    }
+    return { kind: "array", required: true, element };
+  }
+  return p.literals === void 0 ? { kind: p.kind, required: true } : { kind: p.kind, literals: p.literals, required: true };
+}
+function runBuildPass(params, build, scalarFields, arrayParams, pass, accessed, coerced) {
+  const noteAccess = (token, origin) => {
+    if (!accessed.has(token)) accessed.set(token, { token, origin });
+  };
+  const noteCoerce = (token, origin) => {
+    if (!coerced.has(token)) coerced.set(token, { token, origin });
+  };
+  const scalarSentinel = makeValueSentinel(
+    scalarFields,
+    (f) => `{${f}}`,
+    (f) => `param '${f}'`,
+    (f) => markerValue(pass, f),
+    "params",
+    (f) => noteAccess(`{${f}}`, `param '${f}'`),
+    (f) => noteCoerce(`{${f}}`, `param '${f}'`)
+  );
+  const pProxy = new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(_t, key) {
+      if (typeof key === "symbol") {
+        if (key === Symbol.iterator || key === Symbol.asyncIterator || key === Symbol.toStringTag || typeof Symbol.for === "function" && (key === /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom") || key.description === "nodejs.util.inspect.custom")) {
+          return void 0;
+        }
+        throw new Error("defineTransaction: unsupported symbol access on params.");
+      }
+      if (arrayParams.has(key)) return params[key];
+      if (scalarFields.has(key)) return scalarSentinel[key];
+      throw new Error(
+        `defineTransaction: unknown parameter '${key}'. Declare it in the params map passed to defineTransaction.`
+      );
+    }
+  });
+  const instructions = [];
+  let currentBody = instructions;
+  let insideForEach = false;
+  const recordWrite = (instr) => {
+    currentBody.push(instr);
+  };
+  const recorder = {
+    put(model, item, options) {
+      recordWrite({
+        kind: "write",
+        operation: "put",
+        entity: entityRef(model),
+        item,
+        ...options?.condition !== void 0 ? { condition: options.condition } : {},
+        ...options?.when !== void 0 ? { when: options.when } : {},
+        ...options?.guard !== void 0 ? { guard: options.guard } : {}
+      });
+    },
+    update(model, key, changes, options) {
+      recordWrite({
+        kind: "write",
+        operation: "update",
+        entity: entityRef(model),
+        key,
+        changes,
+        ...options?.condition !== void 0 ? { condition: options.condition } : {},
+        ...options?.when !== void 0 ? { when: options.when } : {},
+        ...options?.guard !== void 0 ? { guard: options.guard } : {}
+      });
+    },
+    delete(model, key, options) {
+      recordWrite({
+        kind: "write",
+        operation: "delete",
+        entity: entityRef(model),
+        key,
+        ...options?.condition !== void 0 ? { condition: options.condition } : {},
+        ...options?.when !== void 0 ? { when: options.when } : {},
+        ...options?.guard !== void 0 ? { guard: options.guard } : {}
+      });
+    },
+    conditionCheck(model, key, options) {
+      if (options?.condition === void 0 || options.condition === null) {
+        throw new Error(
+          "defineTransaction: tx.conditionCheck requires a `condition` (the read-only assertion it makes); e.g. `{ condition: { attributeExists: 'PK' } }`."
+        );
+      }
+      recordWrite({
+        kind: "write",
+        operation: "conditionCheck",
+        entity: entityRef(model),
+        key,
+        condition: options.condition,
+        ...options.when !== void 0 ? { when: options.when } : {},
+        ...options.guard !== void 0 ? { guard: options.guard } : {}
+      });
+    },
+    forEach(source, body, options) {
+      if (insideForEach) {
+        throw new Error(
+          "defineTransaction: nested forEach is not supported; flatten the loop."
+        );
+      }
+      if (!isParam(source) || source.kind !== "array") {
+        throw new Error(
+          "defineTransaction: forEach source must be a `param.array(...)` parameter accessed via `p.<name>`."
+        );
+      }
+      const arrayParam = source;
+      const sourceName = arrayParams.size ? Object.keys(params).find((k) => params[k] === arrayParam) : void 0;
+      if (sourceName === void 0) {
+        throw new Error(
+          "defineTransaction: forEach source is not a declared array param."
+        );
+      }
+      const elementFields = new Set(Object.keys(arrayParam.element ?? {}));
+      const elementProxy = makeValueSentinel(
+        elementFields,
+        (f) => `{item.${f}}`,
+        (f) => `element field '${f}' of '${sourceName}'`,
+        (f) => markerValue(pass, `item.${f}`),
+        `element of '${sourceName}'`,
+        (f) => noteAccess(`{item.${f}}`, `element field '${f}' of '${sourceName}'`),
+        (f) => noteCoerce(`{item.${f}}`, `element field '${f}' of '${sourceName}'`)
+      );
+      const block = {
+        kind: "forEach",
+        source: sourceName,
+        ...options?.when !== void 0 ? { when: options.when } : {},
+        body: []
+      };
+      const prevBody = currentBody;
+      currentBody = block.body;
+      insideForEach = true;
+      try {
+        body(elementProxy);
+      } finally {
+        insideForEach = false;
+        currentBody = prevBody;
+      }
+      currentBody.push(block);
+    }
+  };
+  build(recorder, pProxy);
+  return instructions;
+}
+function defineTransaction(params, build) {
+  const descriptors = {};
+  for (const [name, value] of Object.entries(params)) {
+    if (!isParam(value)) {
+      throw new Error(
+        `defineTransaction: param '${name}' is not a param.* placeholder.`
+      );
+    }
+    descriptors[name] = descriptorOf(value);
+  }
+  const scalarFields = new Set(
+    Object.keys(params).filter((k) => params[k].kind !== "array")
+  );
+  const arrayParams = new Set(
+    Object.keys(params).filter((k) => params[k].kind === "array")
+  );
+  const accessed = /* @__PURE__ */ new Map();
+  const coerced = /* @__PURE__ */ new Map();
+  const passes = [];
+  for (let pass = 0; pass < MARKER_PASS_COUNT; pass++) {
+    passes.push(
+      runBuildPass(
+        params,
+        build,
+        scalarFields,
+        arrayParams,
+        pass,
+        accessed,
+        coerced
+      )
+    );
+  }
+  if (coerced.size > 0) {
+    const info = [...coerced.values()][0];
+    throw new Error(
+      `defineTransaction: ${info.origin} is coerced to a primitive (e.g. via \`String(${info.origin.includes("element") ? "el" : "p"}.x)\`, a template literal \`\${\u2026}\`, string concatenation, or a comparison) and then consumed by a transform or branch \u2014 for example \`String(p.x).slice(0, n)\`, \`String(p.x)[0]\`, \`String(p.x).includes('\u2026')\`, or \`\${p.x}-suffix\`. At a value position the static planner (Python bridge) only supports a *direct* field reference (stored without coercion) or a concrete literal; a coerced / transformed parameter is not representable as a declarative transaction template, and (because the transform may converge to a constant or a shared marker fragment) could otherwise be silently emitted as a wrong spec. Reference the field directly (\`p.x\` / \`el.x\`) or use a literal.`
+    );
+  }
+  const surfaced = /* @__PURE__ */ new Set();
+  verifyInstructions(passes, surfaced);
+  for (const [token, info] of accessed) {
+    if (!surfaced.has(token)) {
+      throw new Error(
+        `defineTransaction: ${info.origin} is accessed but never appears as a field reference in the recorded transaction. This happens when a parameter is consumed by a value branch (e.g. \`p.role === 'admin' ? 'A' : 'B'\`) or a string transform (e.g. \`String(p.role).toUpperCase()\`) instead of being referenced directly. The static planner (Python bridge) only supports direct field references or concrete literals at value positions; branching or transforming a parameter is not representable as a declarative transaction template.`
+      );
+    }
+  }
+  return {
+    __isTransactionDefinition: true,
+    params: descriptors,
+    instructions: passes[0]
+  };
+}
+function verifyInstructions(passes, surfaced) {
+  const first = passes[0];
+  for (let i = 0; i < first.length; i++) {
+    const instrs = passes.map((p) => p[i]);
+    const kind = first[i].kind;
+    if (instrs.some((x) => x.kind !== kind)) {
+      throw new Error(
+        "defineTransaction: build is not deterministic across evaluation (instruction shape diverged between passes). The callback must be a pure, declarative description of the writes."
+      );
+    }
+    if (kind === "write") {
+      verifyWrite(instrs, surfaced);
+    } else {
+      const blocks = instrs;
+      verifyWhen(
+        blocks.map((b) => b.when),
+        surfaced,
+        `forEach '${blocks[0].source}' when`
+      );
+      verifyInstructions(
+        blocks.map((b) => b.body),
+        surfaced
+      );
+    }
+  }
+}
+function verifyWrite(instrs, surfaced) {
+  const op = instrs[0].operation;
+  if (instrs.some((x) => x.operation !== op)) {
+    throw new Error(
+      "defineTransaction: write operation diverged between evaluation passes; the callback must be a pure, declarative description of the writes."
+    );
+  }
+  verifyRecord(instrs.map((x) => x.item), surfaced, `${op} item`);
+  verifyRecord(instrs.map((x) => x.key), surfaced, `${op} key`);
+  verifyRecord(instrs.map((x) => x.changes), surfaced, `${op} changes`);
+  verifyCondition(
+    instrs.map((x) => x.condition),
+    surfaced,
+    `${op} condition`
+  );
+  verifyWhen(instrs.map((x) => x.when), surfaced, `${op} when`);
+}
+function verifyRecord(records, surfaced, context) {
+  const present = records.filter((r) => r !== void 0);
+  if (present.length === 0) return;
+  if (present.length !== records.length) {
+    throw new Error(
+      `defineTransaction: ${context} present in some evaluation passes but not others; the callback must be a pure, declarative description.`
+    );
+  }
+  const keys = Object.keys(present[0]).sort();
+  for (const r of present) {
+    const k = Object.keys(r).sort();
+    if (k.length !== keys.length || k.some((x, i) => x !== keys[i])) {
+      throw new Error(
+        `defineTransaction: ${context} field set diverged between evaluation passes; the callback must be a pure, declarative description.`
+      );
+    }
+  }
+  for (const field of keys) {
+    verifyLeaf(
+      present.map((r) => r[field]),
+      surfaced,
+      `${context} field '${field}'`
+    );
+  }
+}
+function isConditionOperatorObject(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) => isConditionOperatorObject(v))) {
+      if (values.some((v) => isConditionOperatorObject(v))) {
+        throw new Error(
+          `defineTransaction: ${context} field '${key}' is an operator object in some evaluation passes but a bare value in others; the callback must be declarative.`
+        );
+      }
+      verifyLeaf(values, surfaced, `${context} field '${key}'`);
+      continue;
+    }
+    verifyOperatorObject(
+      values.map((v) => v),
+      surfaced,
+      `${context} field '${key}'`
+    );
+  }
+}
+function verifyOperatorObject(objs, surfaced, context) {
+  const ops = Object.keys(objs[0]).sort();
+  for (const o of objs) {
+    const k = Object.keys(o).sort();
+    if (k.length !== ops.length || k.some((x, i) => x !== ops[i])) {
+      throw new Error(
+        `defineTransaction: ${context} operator set diverged between evaluation passes; the callback must be a pure, declarative description.`
+      );
+    }
+  }
+  for (const op of ops) {
+    const opVals = objs.map((o) => o[op]);
+    if (op === "between") {
+      const pairs = opVals.map((v) => {
+        if (!Array.isArray(v) || v.length !== 2) {
+          throw new Error(
+            `defineTransaction: ${context} \`between\` takes a \`[lo, hi]\` pair.`
+          );
+        }
+        return v;
+      });
+      verifyLeaf(pairs.map((p) => p[0]), surfaced, `${context} between[0]`);
+      verifyLeaf(pairs.map((p) => p[1]), surfaced, `${context} between[1]`);
+    } else if (op === "in") {
+      const arrays = opVals.map((v) => {
+        if (!Array.isArray(v) || v.length === 0) {
+          throw new Error(
+            `defineTransaction: ${context} \`in\` takes a non-empty array of operands.`
+          );
+        }
+        return v;
+      });
+      const len = arrays[0].length;
+      if (arrays.some((a) => a.length !== len)) {
+        throw new Error(
+          `defineTransaction: ${context} \`in\` length diverged between evaluation passes; the callback must be declarative.`
+        );
+      }
+      for (let i = 0; i < len; i++) {
+        verifyLeaf(arrays.map((a) => a[i]), surfaced, `${context} in[${i}]`);
+      }
+    } else if (op === "attributeExists" || op === "attributeType") {
+      if (opVals.some((v) => isTransactionRef(v))) {
+        throw new Error(
+          `defineTransaction: ${context} \`${op}\` was given a field reference. \`${op}\` takes a ${op === "attributeExists" ? "concrete boolean" : "concrete DynamoDB type-code string"} (a structural operand, not a value-bound param); use a literal.`
+        );
+      }
+    } else {
+      verifyLeaf(opVals, surfaced, `${context} ${op}`);
+    }
+  }
+}
+function verifyWhen(whens, surfaced, context) {
+  const present = whens.filter((w) => w !== void 0);
+  if (present.length === 0) return;
+  if (present.length !== whens.length) {
+    throw new Error(
+      `defineTransaction: ${context} present in some evaluation passes but not others; the callback must be a pure, declarative description.`
+    );
+  }
+  for (const w of present) {
+    if (isTransactionRef(w.left)) surfaced.add(w.left.token);
+  }
+  verifyLeaf(present.map((w) => w.right), surfaced, `${context} right-hand value`);
+}
+function verifyLeaf(values, surfaced, context) {
+  const refTokens = values.map((v) => isTransactionRef(v) ? v.token : void 0);
+  const anyRef = refTokens.some((t) => t !== void 0);
+  if (anyRef) {
+    if (refTokens.some((t) => t === void 0)) {
+      throw new Error(
+        `defineTransaction: ${context} is a field reference in some evaluation passes but a transformed value in others \u2014 a coercion/transform escape (e.g. \`String(p.x).toUpperCase()\`) was applied. Use a direct field reference or a concrete literal.`
+      );
+    }
+    const token = refTokens[0];
+    if (refTokens.some((t) => t !== token)) {
+      throw new Error(
+        `defineTransaction: ${context} resolves to different field references across evaluation passes \u2014 the value is not a stable, declarative reference.`
+      );
+    }
+    surfaced.add(token);
+    return;
+  }
+  const norm = values.map(normalizeLiteral);
+  for (let i = 1; i < norm.length; i++) {
+    if (norm[i] !== norm[0]) {
+      throw new Error(
+        `defineTransaction: ${context} is not a stable concrete literal \u2014 evaluating the callback twice produced different values ('${norm[0]}' vs '${norm[i]}'). This means a parameter was coerced or transformed into the value (e.g. \`String(p.x).toUpperCase()\`, \`\${p.x}-suffix\`, or arithmetic). The static planner (Python bridge) only supports a direct field reference or a concrete literal at a value position.`
+      );
+    }
+  }
+}
+function normalizeLiteral(value) {
+  if (value === null) return "t:null";
+  if (value instanceof Date) return `t:date:${value.toISOString()}`;
+  const t = typeof value;
+  if (t === "string") return `t:s:${value}`;
+  if (t === "boolean") return `t:b:${String(value)}`;
+  if (t === "number") {
+    if (Number.isNaN(value)) {
+      throw new Error(
+        "defineTransaction: a value leaf coerced to NaN, which means arithmetic was performed on a parameter. Only direct field references or concrete literals are allowed at value positions."
+      );
+    }
+    return `t:n:${String(value)}`;
+  }
+  throw new Error(
+    `defineTransaction: a value leaf has unsupported type '${t}'. Only a direct field reference (\`p.field\` / \`el.field\`) or a concrete literal (string / number / boolean / Date) is allowed at a value position.`
+  );
+}
+var SCP_LOWERED_MARKER = "graphddb:scp-lowered/v1";
+function defineScpTransaction(params, build, lowered) {
+  if (lowered !== SCP_LOWERED_MARKER) {
+    throw new Error(
+      "defineScpTransaction: this body has not been compiled by the SCP structural transform (issue #263). The native-syntax form must be built with `transformScpTransactionSource` (graphddb/transform), which lowers Guard / Conditional / .map onto the recorder seams and stamps the call with the lowered-body marker. Running it untransformed could silently record a wrong spec (a dropped or unguarded item), so it is rejected at definition time instead."
+    );
+  }
+  return defineTransaction(
+    params,
+    build
+  );
+}
+function defineTransactions(definitions) {
+  for (const [name, def] of Object.entries(definitions)) {
+    if (def === null || typeof def !== "object" || def.__isTransactionDefinition !== true) {
+      throw new Error(
+        `defineTransactions: '${name}' is not a transaction definition. Use defineTransaction(...) to build entries.`
+      );
+    }
+  }
+  return definitions;
+}
+
+export {
+  SPEC_VERSION,
+  SPEC_VERSION_SCP,
+  SPEC_VERSION_SUPPORTED,
+  EXPR_VERSION,
+  MARKER_ROW_ENTITY,
+  canonicalizeExpressionSpec,
+  isScpExprConditionInput,
+  operationsContainScpNodes,
+  operationsSpecVersion,
+  isTransactionRef,
+  when,
+  defineTransaction,
+  SCP_LOWERED_MARKER,
+  defineScpTransaction,
+  defineTransactions
+};