graphddb 0.1.1 → 0.2.1

package/dist/{chunk-6LEHSX45.js → chunk-4B4MUPUJ.js}

@@ -1,14 +1,38 @@
 import {
   BATCH_GET_MAX_KEYS,
+  ChangeCaptureRegistry,
+  ClientManager,
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
   TableMapping,
+  attachHiddenKey,
+  attachModelClass,
+  buildConditionExpression,
+  buildDeleteInput,
+  buildPutInput,
+  buildUpdateInput,
+  captureWrite,
+  commitTransaction,
+  compileRawCondition,
+  createColumnMap,
+  execItemKeySignature,
+  executeDelete,
+  executePut,
+  executeTransaction,
+  executeUpdate,
+  isColumn,
+  isParam,
+  isRawCondition,
+  param,
   pkTemplate,
   resolveKey,
   resolveModelClass,
+  resolveSegmentedKey,
   segmentFieldNames,
+  serializeFieldValue,
+  serializeRawCondition,
   skTemplate
-} from "./chunk-347U24SB.js";
+} from "./chunk-PWV7JDMR.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -217,305 +241,1451 @@ function getImplicitKeyFields(select, metadata) {
   return [...needed];
 }
 
-// src/define/param.ts
-function makeParam(kind, literals) {
-  return literals === void 0 ? { kind } : { kind, literals };
-}
-var param = {
-  /** A placeholder for a `string` value. */
-  string() {
-    return makeParam("string");
-  },
-  /** A placeholder for a `number` value. */
-  number() {
-    return makeParam("number");
-  },
-  /**
-   * A placeholder constrained to one of the given literal values. The value
-   * type of the resulting {@link Param} is the **union of the literals**, so it
-   * is preserved precisely in the IR and the inferred definition types.
-   *
-   * @example
-   * ```ts
-   * param.literal('active', 'disabled'); // Param<'active' | 'disabled'>
-   * ```
-   */
-  literal(...values) {
-    return makeParam("literal", values);
-  },
-  /**
-   * A placeholder for an **array** parameter whose elements have the given field
-   * shape. Used by `defineTransaction`'s `tx.forEach(p.<arrayParam>, …)` to bind
-   * each element's fields to `{item.<field>}` templates.
-   *
-   * @example
-   * ```ts
-   * param.array({ userId: param.string(), role: param.string() });
-   * // Param<{ userId: string; role: string }[]>
-   * ```
-   */
-  array(element) {
-    return { kind: "array", element };
+// src/planner/projection.ts
+function buildProjection(select, additionalFields) {
+  const paths = [];
+  const names = {};
+  let nameCounter = 0;
+  function addPath(segments) {
+    const aliased = segments.map((seg) => {
+      const alias = `#p${nameCounter++}`;
+      names[alias] = seg;
+      return alias;
+    });
+    paths.push(aliased.join("."));
+  }
+  function traverse(selectObj, parentSegments) {
+    for (const [fieldName, value] of Object.entries(selectObj)) {
+      if (value === true) {
+        addPath([...parentSegments, fieldName]);
+      } else if (typeof value === "object" && value !== null) {
+        if ("select" in value || isSelectBuilder(value)) {
+          continue;
+        }
+        traverse(value, [...parentSegments, fieldName]);
+      }
+    }
   }
-};
-function isParam(value) {
-  return typeof value === "object" && value !== null && "kind" in value && (value.kind === "string" || value.kind === "number" || value.kind === "literal" || value.kind === "array");
+  traverse(select, []);
+  if (additionalFields) {
+    for (const fieldName of additionalFields) {
+      addPath([fieldName]);
+    }
+  }
+  if (paths.length === 0) {
+    return void 0;
+  }
+  return {
+    projectionExpression: paths.join(", "),
+    expressionAttributeNames: names
+  };
 }
 
-// src/define/entity-writes.ts
-var LIFECYCLE_CONTRACT_MARKER = /* @__PURE__ */ Symbol(
-  "graphddb:lifecycleContract"
-);
-function isLifecycleContract(value) {
-  return typeof value === "object" && value !== null && value[LIFECYCLE_CONTRACT_MARKER] === true;
+// src/expression/filter-expression.ts
+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 nameAlias(ctx, column) {
+  for (const [alias2, col] of Object.entries(ctx.names)) {
+    if (col === column) return alias2;
+  }
+  const alias = `#f${ctx.nameCounter.n++}`;
+  ctx.names[alias] = column;
+  return alias;
+}
+function valueAlias(ctx, field, raw) {
+  const alias = `:vf${ctx.valueCounter.n++}`;
+  const fieldMeta = ctx.fieldMap.get(field);
+  ctx.values[alias] = fieldMeta ? serializeFieldValue(raw, fieldMeta) : raw;
+  return alias;
+}
+function compileField(ctx, field, condition) {
+  const nAlias = nameAlias(ctx, field);
+  if (!isOperatorObject(condition)) {
+    const vAlias = valueAlias(ctx, field, condition);
+    return `${nAlias} = ${vAlias}`;
+  }
+  const ops = condition;
+  const clauses = [];
+  for (const [op, value] of Object.entries(ops)) {
+    switch (op) {
+      case "eq":
+        clauses.push(`${nAlias} = ${valueAlias(ctx, field, value)}`);
+        break;
+      case "ne":
+        clauses.push(`${nAlias} <> ${valueAlias(ctx, field, value)}`);
+        break;
+      case "gt":
+        clauses.push(`${nAlias} > ${valueAlias(ctx, field, value)}`);
+        break;
+      case "ge":
+        clauses.push(`${nAlias} >= ${valueAlias(ctx, field, value)}`);
+        break;
+      case "lt":
+        clauses.push(`${nAlias} < ${valueAlias(ctx, field, value)}`);
+        break;
+      case "le":
+        clauses.push(`${nAlias} <= ${valueAlias(ctx, field, value)}`);
+        break;
+      case "between": {
+        const [lo, hi] = value;
+        clauses.push(
+          `${nAlias} BETWEEN ${valueAlias(ctx, field, lo)} AND ${valueAlias(ctx, field, hi)}`
+        );
+        break;
+      }
+      case "in": {
+        const arr = value;
+        const aliases = arr.map((v) => valueAlias(ctx, field, v));
+        clauses.push(`${nAlias} IN (${aliases.join(", ")})`);
+        break;
+      }
+      case "beginsWith":
+        clauses.push(`begins_with(${nAlias}, ${valueAlias(ctx, field, value)})`);
+        break;
+      case "contains":
+        clauses.push(`contains(${nAlias}, ${valueAlias(ctx, field, value)})`);
+        break;
+      case "notContains":
+        clauses.push(
+          `NOT contains(${nAlias}, ${valueAlias(ctx, field, value)})`
+        );
+        break;
+      case "attributeExists":
+        clauses.push(
+          value === false ? `attribute_not_exists(${nAlias})` : `attribute_exists(${nAlias})`
+        );
+        break;
+      case "attributeType":
+        clauses.push(
+          `attribute_type(${nAlias}, ${valueAlias(ctx, field, value)})`
+        );
+        break;
+      case "size":
+        clauses.push(`size(${nAlias}) = ${valueAlias(ctx, field, value)}`);
+        break;
+      default:
+        throw new Error(`Unknown filter operator '${op}' on field '${field}'`);
+    }
+  }
+  return joinAnd(clauses);
 }
-var ENTITY_WRITES_MARKER = /* @__PURE__ */ Symbol("graphddb:entityWrites");
-function isEntityWritesDefinition(value) {
-  return typeof value === "object" && value !== null && value[ENTITY_WRITES_MARKER] === true;
+function isOperatorObject(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));
 }
-function freezeEffects(effects) {
-  const out = {};
-  if (effects.requires !== void 0) out.requires = effects.requires;
-  if (effects.unique !== void 0) out.unique = effects.unique;
-  if (effects.edges !== void 0) out.edges = effects.edges;
-  if (effects.derive !== void 0) out.derive = effects.derive;
-  if (effects.emits !== void 0) out.emits = effects.emits;
-  if (effects.idempotency !== void 0) out.idempotency = effects.idempotency;
-  return out;
+function joinAnd(clauses) {
+  if (clauses.length === 1) return clauses[0];
+  return clauses.map((c) => wrap(c)).join(" AND ");
 }
-var recorder = {
-  lifecycle(effects = {}) {
-    return {
-      [LIFECYCLE_CONTRACT_MARKER]: true,
-      effects: freezeEffects(effects)
-    };
-  },
-  exists(targetFactory, keys) {
-    return { kind: "requires", targetFactory, keys };
-  },
-  unique(spec) {
-    return { kind: "unique", name: spec.name, scope: spec.scope, fields: spec.fields };
-  },
-  putEdge(targetFactory, relationProperty) {
-    return { kind: "putEdge", targetFactory, relationProperty };
-  },
-  deleteEdge(targetFactory, relationProperty) {
-    return { kind: "deleteEdge", targetFactory, relationProperty };
-  },
-  increment(targetFactory, keys, attribute, amount) {
-    return { kind: "derive", targetFactory, keys, attribute, amount };
-  },
-  event(name, payload) {
-    return { kind: "event", name, payload };
-  },
-  idempotentBy(token) {
-    return { kind: "idempotency", token };
+function wrap(expr) {
+  if (isAlreadyWrapped(expr)) return expr;
+  if (expr.includes(" AND ") || expr.includes(" OR ")) {
+    return `(${expr})`;
   }
-};
-function entityWrites(builder) {
-  const shape = builder(recorder);
-  for (const phase of ["create", "update", "remove"]) {
-    const contract = shape[phase];
-    if (contract !== void 0 && !isLifecycleContract(contract)) {
-      throw new Error(
-        `entityWrites: the '${phase}' lifecycle must be built with \`w.lifecycle({...})\` (it carries the \xA72 effect arrays), but received ${JSON.stringify(contract)}.`
-      );
+  return expr;
+}
+function isAlreadyWrapped(expr) {
+  if (!expr.startsWith("(") || !expr.endsWith(")")) return false;
+  let depth = 0;
+  for (let i = 0; i < expr.length; i++) {
+    if (expr[i] === "(") depth++;
+    else if (expr[i] === ")") {
+      depth--;
+      if (depth === 0 && i < expr.length - 1) return false;
     }
   }
-  if (shape.create === void 0 && shape.update === void 0 && shape.remove === void 0) {
-    throw new Error(
-      "entityWrites(...) must declare at least one lifecycle (`create` / `update` / `remove`); an empty save contract declares nothing."
-    );
-  }
-  return {
-    [ENTITY_WRITES_MARKER]: true,
-    ...shape.create !== void 0 ? { create: shape.create } : {},
-    ...shape.update !== void 0 ? { update: shape.update } : {},
-    ...shape.remove !== void 0 ? { remove: shape.remove } : {}
-  };
+  return depth === 0;
 }
-function getEntityWrites(modelClass) {
-  for (const name of Object.getOwnPropertyNames(modelClass)) {
-    let value;
-    try {
-      value = modelClass[name];
-    } catch {
+function compileRaw(ctx, raw) {
+  return compileRawCondition(
+    raw,
+    (column) => nameAlias(ctx, column),
+    (value) => {
+      const alias = `:vf${ctx.valueCounter.n++}`;
+      ctx.values[alias] = value;
+      return alias;
+    }
+  );
+}
+function compileNode(ctx, node) {
+  if (isRawCondition(node)) {
+    return compileRaw(ctx, node);
+  }
+  const clauses = [];
+  for (const [key, value] of Object.entries(node)) {
+    if (value === void 0) continue;
+    if (LOGICAL_KEYS.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;
+        if (parts.length === 1) {
+          clauses.push(parts[0]);
+        } else {
+          const sep = key === "and" ? " AND " : " OR ";
+          const joined = parts.map((p) => wrap(p)).join(sep);
+          clauses.push(`(${joined})`);
+        }
+      } else {
+        const inner = compileNode(ctx, value);
+        if (inner.length > 0) clauses.push(`NOT ${wrap(inner)}`);
+      }
       continue;
     }
-    if (isEntityWritesDefinition(value)) return value;
+    const clause = compileField(ctx, key, value);
+    if (clause.length > 0) clauses.push(clause);
   }
-  return void 0;
-}
-function lifecyclePhaseForIntent(intent) {
-  return intent;
+  return joinAnd(clauses);
 }
-
-// src/define/mutation.ts
-var INPUT_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:mutationInputRef");
-function isMutationInputRef(value) {
-  return typeof value === "object" && value !== null && value[INPUT_REF_BRAND] === true;
-}
-var ENTITY_REF_RE = /^\$\.entity\[(\d+)\]\.([A-Za-z_$][\w$]*)$/;
-var ENTITY_REF_PREFIX_RE = /^\s*\$\s*\.\s*entity\b/;
-var ENTITY_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:mutationEntityRef");
-function parseEntityRef(leaf) {
-  if (typeof leaf !== "string") return void 0;
-  const match = ENTITY_REF_RE.exec(leaf);
-  if (match === null) {
-    if (ENTITY_REF_PREFIX_RE.test(leaf)) {
-      throw new Error(
-        `mutation: the input value ${JSON.stringify(leaf)} looks like a cross-fragment reference but is malformed. The only supported form is \`$.entity[<index>].<field>\` (e.g. \`$.entity[0].postId\`) \u2014 a single dotted field on a 0-based, non-negative fragment index. Fix the path or, if you meant a literal string, it must not begin with \`$.entity\`.`
-      );
-    }
+function compileFilterExpression(filter, metadata) {
+  if (!filter || Object.keys(filter).length === 0) {
+    return void 0;
+  }
+  const ctx = {
+    names: {},
+    values: {},
+    fieldMap: new Map(metadata.fields.map((f) => [f.propertyName, f])),
+    nameCounter: { n: 0 },
+    valueCounter: { n: 0 }
+  };
+  const expression = compileNode(ctx, filter);
+  if (expression.length === 0) {
     return void 0;
   }
   return {
-    [ENTITY_REF_BRAND]: true,
-    fragmentIndex: Number(match[1]),
-    field: match[2],
-    path: leaf
+    filterExpression: expression,
+    expressionAttributeNames: ctx.names,
+    expressionAttributeValues: ctx.values
   };
 }
-function makeInputFieldRef(field) {
-  const token = `{${field}}`;
-  const origin = `the input field '${field}' (\`$.${field}\`)`;
-  const target = /* @__PURE__ */ Object.create(null);
-  const proxy = new Proxy(target, {
-    get(_t, prop) {
-      if (prop === INPUT_REF_BRAND) return true;
-      if (prop === "field") return field;
-      if (prop === "token") return token;
-      if (typeof prop === "symbol") return void 0;
-      throw new Error(
-        `mutation: unsupported operation '${String(prop)}' on ${origin}. A fragment \`input\` binding only supports a *direct* \`$.field\` reference or a concrete literal \u2014 any transform, indexing, coercion, or concatenation on an input field is not representable as a declarative mutation.`
-      );
-    },
-    set() {
-      throw new Error(`mutation: cannot assign on ${origin}.`);
+function evaluateFilter(item, filter) {
+  for (const [key, value] of Object.entries(filter)) {
+    if (value === void 0) continue;
+    if (key === "and") {
+      if (!value.every((s) => evaluateFilter(item, s)))
+        return false;
+      continue;
     }
-  });
-  return proxy;
-}
-function makeInputProxy() {
-  const cache = /* @__PURE__ */ new Map();
-  return new Proxy(/* @__PURE__ */ Object.create(null), {
-    get(_t, prop) {
-      if (typeof prop === "symbol") return void 0;
-      const field = prop;
-      let ref = cache.get(field);
-      if (!ref) {
-        ref = makeInputFieldRef(field);
-        cache.set(field, ref);
+    if (key === "or") {
+      if (!value.some((s) => evaluateFilter(item, s)))
+        return false;
+      continue;
+    }
+    if (key === "not") {
+      if (evaluateFilter(item, value)) return false;
+      continue;
+    }
+    if (!evaluateFieldCondition(item[key], item, key, value)) {
+      return false;
+    }
+  }
+  return true;
+}
+function cmp(a, b) {
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() - b.getTime();
+  }
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string")
+    return a < b ? -1 : a > b ? 1 : 0;
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+function eq(a, b) {
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  return a === b;
+}
+function evaluateFieldCondition(actual, item, field, condition) {
+  if (!isOperatorObject(condition)) {
+    return eq(actual, condition);
+  }
+  const ops = condition;
+  for (const [op, value] of Object.entries(ops)) {
+    switch (op) {
+      case "eq":
+        if (!eq(actual, value)) return false;
+        break;
+      case "ne":
+        if (eq(actual, value)) return false;
+        break;
+      case "gt":
+        if (!(cmp(actual, value) > 0)) return false;
+        break;
+      case "ge":
+        if (!(cmp(actual, value) >= 0)) return false;
+        break;
+      case "lt":
+        if (!(cmp(actual, value) < 0)) return false;
+        break;
+      case "le":
+        if (!(cmp(actual, value) <= 0)) return false;
+        break;
+      case "between": {
+        const [lo, hi] = value;
+        if (!(cmp(actual, lo) >= 0 && cmp(actual, hi) <= 0)) return false;
+        break;
       }
-      return ref;
-    },
-    set() {
-      throw new Error("mutation: cannot assign to the `$` input proxy.");
+      case "in":
+        if (!value.some((v) => eq(actual, v))) return false;
+        break;
+      case "beginsWith":
+        if (typeof actual !== "string" || !actual.startsWith(value))
+          return false;
+        break;
+      case "contains":
+        if (typeof actual !== "string" || !actual.includes(value))
+          return false;
+        break;
+      case "notContains":
+        if (typeof actual === "string" && actual.includes(value))
+          return false;
+        break;
+      case "attributeExists": {
+        const exists = field in item && actual !== void 0 && actual !== null;
+        if (value === false ? exists : !exists) return false;
+        break;
+      }
+      case "attributeType":
+        break;
+      case "size": {
+        const len = typeof actual === "string" || Array.isArray(actual) ? actual.length : void 0;
+        if (len !== value) return false;
+        break;
+      }
+      default:
+        throw new Error(`Unknown filter operator '${op}' on field '${field}'`);
     }
-  });
-}
-var FRAGMENT_BRAND = /* @__PURE__ */ Symbol("graphddb:mutationFragment");
-function isMutationFragment(value) {
-  return typeof value === "object" && value !== null && value[FRAGMENT_BRAND] === true;
-}
-function targetEntityRef(target) {
-  const resolved = target();
-  const modelClass = resolveModelClass(resolved);
-  return { name: modelClass.name, modelClass };
+  }
+  return true;
 }
-function assertFaithfulInput(input, intent, entityName) {
-  if (input === null || typeof input !== "object") {
+
+// src/planner/planner.ts
+function plan(metadata, input) {
+  const queryFields = Object.keys(input.key);
+  const resolved = resolveKey(queryFields, metadata);
+  if (input.consistentRead && resolved.type === "gsi") {
     throw new Error(
-      `mutation: the '${intent}' fragment on '${entityName}' must declare an \`input\` object binding model fields to \`$.field\` references or literals.`
+      "consistentRead is not supported for GSI queries. Use a primary key query instead."
     );
   }
-  for (const [field, leaf] of Object.entries(input)) {
-    if (!isMutationInputRef(leaf) && !isConcreteLiteral(leaf)) {
-      throw new Error(
-        `mutation: the '${intent}' fragment on '${entityName}' binds model field '${field}' to a value that is neither a \`$.field\` input reference nor a concrete literal. A fragment input is declarative \u2014 only \`$.<field>\` references or literals are allowed, never a computed value.`
-      );
+  const tableName = TableMapping.resolve(metadata.tableName);
+  const built = buildKeyCondition(metadata, resolved, input.key);
+  const keyCondition = built.keyCondition;
+  const additionalProjectionFields = input.updatable ? Array.from(
+    /* @__PURE__ */ new Set([...input.additionalProjectionFields ?? [], "PK", "SK"])
+  ) : input.additionalProjectionFields;
+  const projection = buildProjection(input.select, additionalProjectionFields);
+  const compiledFilter = compileFilterExpression(input.filter, metadata);
+  const isGetItem = resolved.type === "pk" && !resolved.partial && built.skValue !== void 0 && // GetItem does not support FilterExpression — fall back to Query when a
+  // server-side filter is requested so the condition can be applied.
+  !compiledFilter;
+  const projectionFields2 = projection ? {
+    projectionExpression: projection.projectionExpression,
+    expressionAttributeNames: projection.expressionAttributeNames
+  } : {};
+  const filterFields = compiledFilter ? {
+    filterExpression: compiledFilter.filterExpression,
+    filterExpressionAttributeNames: compiledFilter.expressionAttributeNames,
+    filterExpressionAttributeValues: compiledFilter.expressionAttributeValues
+  } : {};
+  const consistentRead = input.consistentRead && resolved.type === "pk" ? { consistentRead: true } : {};
+  let op;
+  if (isGetItem) {
+    op = {
+      type: "GetItem",
+      tableName,
+      keyCondition,
+      ...projectionFields2,
+      ...consistentRead
+    };
+  } else {
+    const queryOp = {
+      type: "Query",
+      tableName,
+      keyCondition,
+      scanIndexForward: (input.order ?? "ASC") === "ASC",
+      ...projectionFields2,
+      ...filterFields,
+      ...consistentRead
+    };
+    if (resolved.type === "gsi") {
+      queryOp.indexName = resolved.indexName;
+    }
+    if (built.rangeCondition) {
+      queryOp.rangeCondition = built.rangeCondition;
+    }
+    if (input.limit != null) {
+      queryOp.limit = input.limit;
+    }
+    if (input.after) {
+      queryOp.exclusiveStartKey = input.after;
     }
+    op = queryOp;
   }
-  return input;
-}
-function isConcreteLiteral(value) {
-  const t = typeof value;
-  return value === null || value instanceof Date || t === "string" || t === "number" || t === "boolean";
+  return { operations: [op] };
 }
-function makeFragment(intent, target, options) {
-  const entity = targetEntityRef(target);
-  const input = assertFaithfulInput(options.input ?? {}, intent, entity.name);
-  if (options.use !== void 0 && !isEntityWritesDefinition(options.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.`
+function buildKeyCondition(metadata, resolved, queryKey) {
+  if (resolved.type === "pk") {
+    if (!metadata.primaryKey) throw new Error("Primary key not defined");
+    return buildFromSegments(
+      metadata.primaryKey.segmented,
+      metadata.primaryKey.inputFieldNames,
+      queryKey,
+      "PK",
+      "SK"
     );
   }
-  return {
-    [FRAGMENT_BRAND]: true,
-    intent,
-    entity,
-    input,
-    ...options.use !== void 0 ? { use: options.use } : {}
-  };
-}
-var mutationRecorder = {
-  create: (target, options) => makeFragment("create", target, options),
-  update: (target, options) => makeFragment("update", target, options),
-  remove: (target, options) => makeFragment("remove", target, options)
-};
-var COMMAND_PLAN_BRAND = /* @__PURE__ */ Symbol("graphddb:commandPlan");
-function isCommandPlan(value) {
-  return typeof value === "object" && value !== null && value[COMMAND_PLAN_BRAND] === true;
+  const gsiDef = metadata.gsiDefinitions.find(
+    (g) => g.indexName === resolved.indexName
+  );
+  if (!gsiDef) throw new Error(`GSI '${resolved.indexName}' not found`);
+  return buildFromSegments(
+    gsiDef.segmented,
+    gsiDef.inputFieldNames,
+    queryKey,
+    `${gsiDef.indexName}PK`,
+    `${gsiDef.indexName}SK`
+  );
 }
-function mutation(name, body) {
-  if (typeof name !== "string" || name.length === 0) {
-    throw new Error("mutation: the first argument must be a non-empty mutation name.");
+function buildFromSegments(segmented, inputFieldNames, queryKey, pkAttr, skAttr) {
+  const keyInput = {};
+  for (const fieldName of inputFieldNames) {
+    keyInput[fieldName] = queryKey[fieldName];
   }
-  const $ = makeInputProxy();
-  const result = body(mutationRecorder, $);
-  if (!Array.isArray(result)) {
-    throw new Error(
-      `mutation '${name}': the body must RETURN an array of write fragments (e.g. \`(m, $) => [ m.create(() => Model, { input }) ]\`). The fragments are declarations composed at compile time, not executed calls.`
-    );
+  const { pk, sk, skTruncated } = resolveSegmentedKey(segmented, keyInput);
+  const keyCondition = { [pkAttr]: pk };
+  if (sk === void 0) {
+    return { keyCondition };
   }
-  if (result.length === 0) {
-    throw new Error(
-      `mutation '${name}': the body returned an empty fragment list. A mutation must declare at least one write fragment.`
-    );
+  if (skTruncated) {
+    return {
+      keyCondition,
+      rangeCondition: { operator: "begins_with", key: skAttr, value: sk }
+    };
   }
-  result.forEach((fragment, i) => {
-    if (!isMutationFragment(fragment)) {
-      throw new Error(
-        `mutation '${name}': fragment #${i} is not a write fragment. Each list element must be an \`m.create\` / \`m.update\` / \`m.remove\` declaration.`
-      );
-    }
-  });
-  return { [COMMAND_PLAN_BRAND]: true, name, fragments: result };
+  keyCondition[skAttr] = sk;
+  return { keyCondition, skValue: sk };
 }
-var definePlan = mutation;
 
-// src/relation/edge-write.ts
-var OLD_VALUE_NAMESPACE = "old";
-var EDGE_WRITES_MARKER = /* @__PURE__ */ Symbol("graphddb:edgeWrites");
-function isEdgeWritesDefinition(value) {
-  return typeof value === "object" && value !== null && value[EDGE_WRITES_MARKER] === true;
+// src/executor/executor.ts
+async function execute(operation) {
+  return ClientManager.getExecutor().execute(operation);
 }
-function declaration(target, relationProperty) {
-  return { targetFactory: target, relationProperty };
+
+// src/hydrator/hydrator.ts
+function hydrate(rawItems, select, metadata, updatable = false) {
+  return rawItems.map((item) => hydrateItem(item, select, metadata, updatable));
 }
-var recorder2 = {
-  putEdge: declaration,
-  deleteEdge: declaration,
-  updateKeyChangeEdge: declaration
-};
-function edgeWrites(builder) {
-  const edges = builder(recorder2);
-  if (edges.length === 0) {
-    throw new Error(
-      "edgeWrites(...) must declare at least one edge (w.putEdge / w.deleteEdge / w.updateKeyChangeEdge); an empty declaration writes nothing."
-    );
-  }
-  return { [EDGE_WRITES_MARKER]: true, edges };
+function hydrateItem(raw, select, metadata, updatable = false) {
+  const fieldMap = new Map(
+    metadata.fields.map((f) => [f.propertyName, f])
+  );
+  const embeddedMap = new Map(
+    metadata.embeddedFields.map((e) => [e.propertyName, e])
+  );
+  const result = {};
+  for (const [fieldName, selectValue] of Object.entries(select)) {
+    if (selectValue === true) {
+      const value = raw[fieldName];
+      if (value !== void 0) {
+        const fieldMeta = fieldMap.get(fieldName);
+        result[fieldName] = deserializeValue(value, fieldMeta);
+      }
+    } else if (typeof selectValue === "object" && selectValue !== null) {
+      if ("select" in selectValue || isSelectBuilder(selectValue)) {
+        continue;
+      }
+      const rawEmb = raw[fieldName];
+      if (rawEmb && typeof rawEmb === "object") {
+        result[fieldName] = hydrateEmbedded(
+          rawEmb,
+          selectValue,
+          metadata,
+          fieldName
+        );
+      }
+    }
+  }
+  if (updatable) {
+    attachHiddenKey(result, raw);
+  }
+  return result;
+}
+function hydrateEmbedded(raw, select, _metadata, _fieldName) {
+  const result = {};
+  for (const [key, selectValue] of Object.entries(select)) {
+    if (selectValue === true) {
+      if (raw[key] !== void 0) {
+        result[key] = raw[key];
+      }
+    } else if (typeof selectValue === "object" && selectValue !== null && !("select" in selectValue)) {
+      const nested = raw[key];
+      if (nested && typeof nested === "object") {
+        result[key] = hydrateEmbedded(
+          nested,
+          selectValue,
+          _metadata,
+          key
+        );
+      }
+    }
+  }
+  return result;
+}
+function deserializeValue(value, fieldMeta) {
+  if (!fieldMeta) return value;
+  if (fieldMeta.options?.deserialize) {
+    return fieldMeta.options.deserialize(value);
+  }
+  if (fieldMeta.options?.format === "datetime" && typeof value === "string") {
+    return new Date(value);
+  }
+  if (fieldMeta.options?.format === "date" && typeof value === "string") {
+    return /* @__PURE__ */ new Date(value + "T00:00:00.000Z");
+  }
+  return value;
+}
+
+// src/pagination/cursor.ts
+function encodeCursor(lastEvaluatedKey) {
+  const json = JSON.stringify(lastEvaluatedKey);
+  const bytes = new TextEncoder().encode(json);
+  let binary = "";
+  for (const b of bytes) {
+    binary += String.fromCharCode(b);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeCursor(cursor) {
+  let base64 = cursor.replace(/-/g, "+").replace(/_/g, "/");
+  while (base64.length % 4 !== 0) {
+    base64 += "=";
+  }
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  const json = new TextDecoder().decode(bytes);
+  return JSON.parse(json);
+}
+
+// src/operations/list.ts
+async function executeListInternal(modelClass, key, selectSpec, options = {}) {
+  const metadata = MetadataRegistry.get(modelClass);
+  const normalized = normalizeTopLevelSelect(selectSpec);
+  const select = normalized.select;
+  const filter = options.filter ?? normalized.filter;
+  const after = options.after ?? normalized.after;
+  const limit = options.limit ?? normalized.limit;
+  const order = options.order ?? normalized.order;
+  const exclusiveStartKey = after ? decodeCursor(after) : void 0;
+  const implicitKeys = getImplicitKeyFields(select, metadata);
+  const executionPlan = plan(metadata, {
+    key,
+    select,
+    limit,
+    after: exclusiveStartKey,
+    order,
+    filter,
+    additionalProjectionFields: implicitKeys.length > 0 ? implicitKeys : void 0,
+    updatable: options.updatable ?? false
+  });
+  const operation = executionPlan.operations[0];
+  const result = await execute(operation);
+  const rawItems = result.items;
+  const hydrated = hydrate(rawItems, select, metadata, options.updatable ?? false);
+  const cursor = result.lastEvaluatedKey ? encodeCursor(result.lastEvaluatedKey) : null;
+  return { items: hydrated, rawItems, cursor };
+}
+async function executeList(modelClass, key, selectSpec, options = {}) {
+  const { items, cursor } = await executeListInternal(
+    modelClass,
+    key,
+    selectSpec,
+    options
+  );
+  return { items, cursor };
+}
+
+// src/planner/relation-planner.ts
+function buildRelationQueryKey(rel, rawParentItem) {
+  const queryKey = {};
+  for (const [targetField, sourceField] of Object.entries(rel.keyBinding)) {
+    queryKey[targetField] = rawParentItem[sourceField];
+  }
+  return queryKey;
+}
+function serializeQueryKey(queryKey) {
+  const entries = Object.entries(queryKey).sort(([a], [b]) => a.localeCompare(b));
+  return JSON.stringify(entries);
+}
+function planGetItemForQueryKey(metadata, queryKey, select, additionalProjectionFields) {
+  const executionPlan = plan(metadata, {
+    key: queryKey,
+    select,
+    additionalProjectionFields
+  });
+  const operation = executionPlan.operations[0];
+  if (operation.type !== "GetItem") {
+    throw new Error(
+      `Relation target requires GetItem access pattern, got ${operation.type}`
+    );
+  }
+  return operation;
+}
+function planBatchGetForQueryKeys(metadata, queryKeys, select, additionalProjectionFields) {
+  if (queryKeys.length === 0) {
+    return [];
+  }
+  const keyFields = [
+    ...new Set(queryKeys.flatMap((queryKey) => Object.keys(queryKey)))
+  ].filter((field) => !(field in select && select[field] === true));
+  const projectionFields2 = [
+    .../* @__PURE__ */ new Set([
+      ...(additionalProjectionFields ?? []).filter(
+        (field) => !(field in select && select[field] === true)
+      ),
+      ...keyFields
+    ])
+  ];
+  const samplePlan = planGetItemForQueryKey(
+    metadata,
+    queryKeys[0],
+    select,
+    projectionFields2.length > 0 ? projectionFields2 : void 0
+  );
+  const uniqueKeys = dedupeDynamoKeys(
+    queryKeys.map(
+      (queryKey) => planGetItemForQueryKey(
+        metadata,
+        queryKey,
+        select,
+        projectionFields2.length > 0 ? projectionFields2 : void 0
+      ).keyCondition
+    )
+  );
+  const operations = [];
+  for (let i = 0; i < uniqueKeys.length; i += BATCH_GET_MAX_KEYS) {
+    operations.push({
+      type: "BatchGetItem",
+      tableName: samplePlan.tableName,
+      keys: uniqueKeys.slice(i, i + BATCH_GET_MAX_KEYS),
+      ...samplePlan.projectionExpression ? { projectionExpression: samplePlan.projectionExpression } : {},
+      ...samplePlan.expressionAttributeNames ? { expressionAttributeNames: samplePlan.expressionAttributeNames } : {},
+      ...samplePlan.consistentRead ? { consistentRead: true } : {}
+    });
+  }
+  return operations;
+}
+function dedupeDynamoKeys(keys) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const key of keys) {
+    const serialized = JSON.stringify(
+      Object.entries(key).sort(([a], [b]) => a.localeCompare(b))
+    );
+    if (seen.has(serialized)) continue;
+    seen.add(serialized);
+    result.push(key);
+  }
+  return result;
+}
+function planRelationOperations(metadata, select, context = { estimatedParentCount: 1 }) {
+  const operations = [];
+  const relations = detectRelationFields(select, metadata);
+  for (const rel of relations) {
+    const selectSpec = normalizeSelectSpec(select[rel.propertyName]);
+    const targetClass = rel.targetFactory();
+    const targetMeta = MetadataRegistry.get(targetClass);
+    if (rel.type === "hasMany") {
+      const limit = selectSpec.limit ?? rel.options?.limit?.default ?? 20;
+      const tableName = TableMapping.resolve(targetMeta.tableName);
+      const listPlan = plan(targetMeta, {
+        key: buildPlaceholderHasManyKey(rel, targetMeta),
+        select: selectSpec.select,
+        limit
+      });
+      operations.push(...listPlan.operations);
+      operations.push(
+        ...planRelationOperations(targetMeta, selectSpec.select, {
+          estimatedParentCount: limit
+        })
+      );
+      continue;
+    }
+    const estimatedCount = context.estimatedParentCount ?? 1;
+    operations.push(
+      ...planBatchGetForExplain(targetMeta, selectSpec.select, estimatedCount)
+    );
+    operations.push(
+      ...planRelationOperations(targetMeta, selectSpec.select, {
+        estimatedParentCount: 1
+      })
+    );
+  }
+  return operations;
+}
+function buildPlaceholderHasManyKey(rel, targetMeta) {
+  const queryKey = {};
+  for (const targetField of Object.keys(rel.keyBinding)) {
+    queryKey[targetField] = `__${targetField}__`;
+  }
+  if (targetMeta.primaryKey) {
+    for (const fieldName of targetMeta.primaryKey.inputFieldNames) {
+      if (!(fieldName in queryKey)) {
+        queryKey[fieldName] = `__${fieldName}__`;
+      }
+    }
+  }
+  return queryKey;
+}
+function planBatchGetForExplain(metadata, select, estimatedKeyCount) {
+  const placeholderKeys = Array.from(
+    { length: estimatedKeyCount },
+    (_, index) => buildExplainPlaceholderKey(metadata, index)
+  );
+  return planBatchGetForQueryKeys(metadata, placeholderKeys, select);
+}
+function buildExplainPlaceholderKey(metadata, index) {
+  const queryKey = {};
+  if (metadata.primaryKey) {
+    for (const fieldName of metadata.primaryKey.inputFieldNames) {
+      queryKey[fieldName] = `__explain_${fieldName}_${index}__`;
+    }
+  }
+  return queryKey;
+}
+
+// src/relation/concurrency.ts
+var RELATION_TRAVERSAL_CONCURRENCY = 16;
+async function mapWithConcurrency(items, limit, worker) {
+  if (items.length === 0) {
+    return [];
+  }
+  const effectiveLimit = Math.max(1, Math.min(limit, items.length));
+  if (effectiveLimit >= items.length) {
+    return Promise.all(items.map((item, index) => worker(item, index)));
+  }
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  async function runWorker() {
+    while (true) {
+      const index = nextIndex++;
+      if (index >= items.length) {
+        return;
+      }
+      results[index] = await worker(items[index], index);
+    }
+  }
+  const runners = [];
+  for (let i = 0; i < effectiveLimit; i++) {
+    runners.push(runWorker());
+  }
+  await Promise.all(runners);
+  return results;
+}
+
+// src/relation/execution-plan.ts
+function relationResultPaths(select, metadata, parentPath = "$") {
+  const out = [];
+  const relations = detectRelationFields(select, metadata);
+  for (const rel of [...relations].sort(
+    (a, b) => a.propertyName.localeCompare(b.propertyName)
+  )) {
+    const childSelect = normalizeSelectSpec(select[rel.propertyName]).select ?? {};
+    const targetMeta = MetadataRegistry.get(rel.targetFactory());
+    const childPath = `${parentPath}.${rel.propertyName}`;
+    const isMany = rel.type === "hasMany";
+    const resultPath = isMany ? `${childPath}.items` : childPath;
+    out.push({
+      propertyName: rel.propertyName,
+      parentPath,
+      resultPath,
+      isMany
+    });
+    out.push(...relationResultPaths(childSelect, targetMeta, resultPath));
+  }
+  return out;
+}
+function parentResultPath(resultPath) {
+  if (!resultPath.startsWith("$.")) return "$";
+  const tokens = resultPath.slice(2).split(".");
+  if (tokens[tokens.length - 1] === "items") tokens.pop();
+  tokens.pop();
+  return tokens.length === 0 ? "$" : `$.${tokens.join(".")}`;
+}
+function deriveExecutionPlan(resultPaths) {
+  if (resultPaths.length <= 1) return void 0;
+  const indexByPath = /* @__PURE__ */ new Map();
+  resultPaths.forEach((path, i) => {
+    indexByPath.set(path, i);
+  });
+  const stageOf = new Array(resultPaths.length);
+  for (let i = 0; i < resultPaths.length; i++) {
+    if (resultPaths[i] === "$") {
+      stageOf[i] = 0;
+      continue;
+    }
+    const parentPath = parentResultPath(resultPaths[i]);
+    const parentIndex = indexByPath.get(parentPath);
+    const parentStage = parentIndex !== void 0 ? stageOf[parentIndex] : 0;
+    stageOf[i] = parentStage + 1;
+  }
+  const stageCount = Math.max(...stageOf) + 1;
+  const groups = Array.from({ length: stageCount }, () => []);
+  for (let i = 0; i < resultPaths.length; i++) {
+    groups[stageOf[i]].push(i);
+  }
+  for (const g of groups) g.sort((a, b) => a - b);
+  return { groups, concurrency: RELATION_TRAVERSAL_CONCURRENCY };
+}
+function buildRelationExecutionPlan(select, metadata) {
+  const relationPaths = relationResultPaths(select, metadata);
+  if (relationPaths.length === 0) return void 0;
+  const resultPaths = ["$", ...relationPaths.map((r) => r.resultPath)];
+  const plan2 = deriveExecutionPlan(resultPaths);
+  if (plan2 === void 0) return void 0;
+  return { plan: plan2, resultPaths };
+}
+function deriveCompositionPlan(composeCount) {
+  if (composeCount <= 0) {
+    return { stages: [], concurrency: RELATION_TRAVERSAL_CONCURRENCY };
+  }
+  const stage = Array.from({ length: composeCount }, (_unused, i) => i);
+  return { stages: [stage], concurrency: RELATION_TRAVERSAL_CONCURRENCY };
+}
+function stageOfResultPath(resolved, resultPath) {
+  const index = resolved.resultPaths.indexOf(resultPath);
+  if (index < 0) return void 0;
+  for (let s = 0; s < resolved.plan.groups.length; s++) {
+    if (resolved.plan.groups[s].includes(index)) return s;
+  }
+  return void 0;
+}
+
+// src/relation/traversal.ts
+function evaluateFilterClientSide(item, filter, _targetMeta) {
+  return evaluateFilter(item, filter);
+}
+function relationSpec(value) {
+  return normalizeSelectSpec(value);
+}
+function validateDepth(select, metadata, maxDepth, currentDepth = 1) {
+  for (const [fieldName, value] of Object.entries(select)) {
+    if (typeof value === "object" && value !== null && ("select" in value || isSelectBuilder(value))) {
+      const rel = metadata.relations.find((r) => r.propertyName === fieldName);
+      if (!rel) continue;
+      if (currentDepth > maxDepth) {
+        throw new Error(
+          `Relation traversal depth exceeded: '${fieldName}' at depth ${currentDepth} exceeds maxDepth ${maxDepth}. Set maxDepth: ${currentDepth} to allow this.`
+        );
+      }
+      const targetClass = rel.targetFactory();
+      const targetMeta = MetadataRegistry.get(targetClass);
+      const innerSelect = relationSpec(value).select;
+      validateDepth(innerSelect, targetMeta, maxDepth, currentDepth + 1);
+    }
+  }
+}
+function relationResultPath(parentPath, rel) {
+  const base = `${parentPath}.${rel.propertyName}`;
+  return rel.type === "hasMany" ? `${base}.items` : base;
+}
+function stageRelations(relations, parentPath, plan2) {
+  if (plan2 === void 0 || relations.length === 0) {
+    return relations.length > 0 ? { stages: [[...relations]], concurrency: RELATION_TRAVERSAL_CONCURRENCY } : { stages: [], concurrency: RELATION_TRAVERSAL_CONCURRENCY };
+  }
+  const byStage = /* @__PURE__ */ new Map();
+  const unstaged = [];
+  for (const rel of relations) {
+    const stage = stageOfResultPath(plan2, relationResultPath(parentPath, rel));
+    if (stage === void 0) {
+      unstaged.push(rel);
+      continue;
+    }
+    const bucket = byStage.get(stage);
+    if (bucket) bucket.push(rel);
+    else byStage.set(stage, [rel]);
+  }
+  const stages = [...byStage.keys()].sort((a, b) => a - b).map((s) => byStage.get(s));
+  if (unstaged.length > 0) stages.push(unstaged);
+  return { stages, concurrency: plan2.plan.concurrency };
+}
+async function runStaged(relations, parentPath, plan2, worker) {
+  const { stages, concurrency } = stageRelations(relations, parentPath, plan2);
+  for (const stage of stages) {
+    await mapWithConcurrency(stage, concurrency, (rel) => worker(rel));
+  }
+}
+function hasCompleteQueryKey(queryKey) {
+  return Object.values(queryKey).every((value) => value != null);
+}
+function matchesQueryKey(item, queryKey) {
+  return Object.entries(queryKey).every(
+    ([field, value]) => item[field] === value
+  );
+}
+async function fetchBelongsToHasOneBatch(rel, rawParentItems, selectSpec, targetMeta, options, currentDepth, parentPath) {
+  const results = rawParentItems.map(
+    () => null
+  );
+  const queryKeys = [];
+  const parentIndexes = [];
+  for (let i = 0; i < rawParentItems.length; i++) {
+    const queryKey = buildRelationQueryKey(rel, rawParentItems[i]);
+    if (!hasCompleteQueryKey(queryKey)) {
+      continue;
+    }
+    queryKeys.push(queryKey);
+    parentIndexes.push(i);
+  }
+  if (queryKeys.length === 0) {
+    return results;
+  }
+  const implicitKeys = getImplicitKeyFields(selectSpec.select, targetMeta);
+  const projectionExtras = options.updatable ? [...implicitKeys, "PK", "SK"] : implicitKeys;
+  const batchOps = planBatchGetForQueryKeys(
+    targetMeta,
+    queryKeys,
+    selectSpec.select,
+    projectionExtras.length > 0 ? projectionExtras : void 0
+  );
+  const executor = ClientManager.getExecutor();
+  const queryKeyToRaw = /* @__PURE__ */ new Map();
+  for (const operation of batchOps) {
+    const batchResult = await executor.batchGet(operation);
+    for (const item of batchResult.items) {
+      for (const queryKey of queryKeys) {
+        if (!matchesQueryKey(item, queryKey)) {
+          continue;
+        }
+        queryKeyToRaw.set(serializeQueryKey(queryKey), item);
+      }
+    }
+  }
+  const nestedRelations = detectRelationFields(selectSpec.select, targetMeta);
+  const ownPath = relationResultPath(parentPath, rel);
+  await mapWithConcurrency(
+    queryKeys,
+    options.plan?.plan.concurrency ?? RELATION_TRAVERSAL_CONCURRENCY,
+    async (queryKey, j) => {
+      const parentIndex = parentIndexes[j];
+      const raw = queryKeyToRaw.get(serializeQueryKey(queryKey));
+      if (!raw) {
+        return;
+      }
+      const updatable = options.updatable ?? false;
+      let resolvedItem = hydrate([raw], selectSpec.select, targetMeta, updatable)[0] ?? null;
+      if (resolvedItem && nestedRelations.length > 0) {
+        resolvedItem = await resolveRelations(
+          resolvedItem,
+          raw,
+          selectSpec.select,
+          targetMeta,
+          options,
+          currentDepth + 1,
+          ownPath
+        );
+        if (resolvedItem && updatable) {
+          attachHiddenKey(resolvedItem, raw);
+        }
+      }
+      if (resolvedItem && !passesPostLoad(resolvedItem, selectSpec, targetMeta)) {
+        results[parentIndex] = null;
+      } else {
+        results[parentIndex] = resolvedItem;
+      }
+    }
+  );
+  return results;
+}
+function passesPostLoad(item, spec, targetMeta) {
+  if (spec.filter && !evaluateFilterClientSide(item, spec.filter, targetMeta)) {
+    return false;
+  }
+  return true;
+}
+async function resolveSingleValueRelationsBatch(parentItems, rawParentItems, select, metadata, options, currentDepth, parentPath) {
+  const results = parentItems.map((item, i) => {
+    const copy = { ...item };
+    if (options.updatable) {
+      attachHiddenKey(copy, rawParentItems[i]);
+    }
+    return copy;
+  });
+  const relations = detectRelationFields(select, metadata).filter(
+    (rel) => rel.type === "belongsTo" || rel.type === "hasOne"
+  );
+  await runStaged(relations, parentPath, options.plan, async (rel) => {
+    const selectSpec = relationSpec(select[rel.propertyName]);
+    const targetClass = rel.targetFactory();
+    const targetMeta = MetadataRegistry.get(targetClass);
+    const batchResults = await fetchBelongsToHasOneBatch(
+      rel,
+      rawParentItems,
+      selectSpec,
+      targetMeta,
+      options,
+      currentDepth,
+      parentPath
+    );
+    for (let i = 0; i < results.length; i++) {
+      results[i][rel.propertyName] = batchResults[i];
+    }
+  });
+  return results;
+}
+async function resolveRelations(parentItem, rawParentItem, select, metadata, options, currentDepth = 1, currentPath = "$") {
+  const result = { ...parentItem };
+  const relations = detectRelationFields(select, metadata);
+  const plan2 = options.plan ?? (currentPath === "$" ? buildRelationExecutionPlan(select, metadata) : void 0);
+  const opts = plan2 === options.plan ? options : { ...options, plan: plan2 };
+  await runStaged(relations, currentPath, opts.plan, async (rel) => {
+    const selectSpec = relationSpec(select[rel.propertyName]);
+    const ownPath = relationResultPath(currentPath, rel);
+    if (rel.type === "hasMany") {
+      const targetClass2 = rel.targetFactory();
+      const queryKey = buildRelationQueryKey(rel, rawParentItem);
+      const limit = selectSpec.limit ?? rel.options?.limit?.default ?? 20;
+      const order = selectSpec.order ?? rel.options?.order ?? "ASC";
+      const listResult = await executeListInternal(targetClass2, queryKey, selectSpec.select, {
+        limit,
+        after: selectSpec.after,
+        order,
+        filter: selectSpec.filter,
+        updatable: opts.updatable
+      });
+      let items = listResult.items;
+      const rawItems = listResult.rawItems;
+      const targetMeta2 = MetadataRegistry.get(targetClass2);
+      const nestedRelations = detectRelationFields(selectSpec.select, targetMeta2);
+      if (nestedRelations.length > 0) {
+        items = await resolveSingleValueRelationsBatch(
+          items,
+          rawItems,
+          selectSpec.select,
+          targetMeta2,
+          opts,
+          currentDepth + 1,
+          ownPath
+        );
+      }
+      result[rel.propertyName] = {
+        items,
+        cursor: listResult.cursor
+      };
+      return;
+    }
+    const targetClass = rel.targetFactory();
+    const targetMeta = MetadataRegistry.get(targetClass);
+    const [resolvedItem] = await fetchBelongsToHasOneBatch(
+      rel,
+      [rawParentItem],
+      selectSpec,
+      targetMeta,
+      opts,
+      currentDepth,
+      currentPath
+    );
+    result[rel.propertyName] = resolvedItem;
+  });
+  return result;
+}
+
+// src/operations/query.ts
+async function executeQuery(modelClass, key, selectSpec, options) {
+  const metadata = MetadataRegistry.get(modelClass);
+  const queryFields = Object.keys(key);
+  const resolved = resolveKey(queryFields, metadata);
+  if (resolved.type === "gsi" && !resolved.unique) {
+    throw new Error(
+      `Cannot use query() with non-unique GSI '${resolved.indexName}'. Use list() instead.`
+    );
+  }
+  const normalized = normalizeTopLevelSelect(selectSpec);
+  const select = normalized.select;
+  const filter = normalized.filter;
+  const maxDepth = options?.maxDepth ?? 1;
+  const relations = detectRelationFields(select, metadata);
+  if (relations.length > 0) {
+    validateDepth(select, metadata, maxDepth);
+  }
+  const implicitKeys = getImplicitKeyFields(select, metadata);
+  const updatable = options?.updatable ?? false;
+  const executionPlan = plan(metadata, {
+    key,
+    select,
+    filter,
+    consistentRead: options?.consistentRead,
+    additionalProjectionFields: implicitKeys.length > 0 ? implicitKeys : void 0,
+    updatable
+  });
+  const operation = executionPlan.operations[0];
+  const canParallelizeRelations = relations.length > 0 && relations.every(
+    (rel) => Object.values(rel.keyBinding).every(
+      (sourceField) => key[sourceField] != null
+    )
+  );
+  const parentPromise = execute(operation);
+  const relationPromise = canParallelizeRelations ? resolveRelations({}, key, select, metadata, { maxDepth, updatable }, 1) : null;
+  let result;
+  try {
+    result = await parentPromise;
+  } catch (err) {
+    if (relationPromise) await relationPromise.catch(() => void 0);
+    throw err;
+  }
+  if (result.items.length === 0) {
+    if (relationPromise) await relationPromise.catch(() => void 0);
+    return null;
+  }
+  const rawItem = result.items[0];
+  const hydrated = hydrate(result.items, select, metadata, updatable);
+  let hydratedItem = hydrated[0] ?? null;
+  if (hydratedItem && relations.length > 0) {
+    if (relationPromise) {
+      const resolvedRelations = await relationPromise;
+      for (const rel of relations) {
+        hydratedItem[rel.propertyName] = resolvedRelations[rel.propertyName];
+      }
+    } else {
+      hydratedItem = await resolveRelations(
+        hydratedItem,
+        rawItem,
+        select,
+        metadata,
+        { maxDepth, updatable },
+        1
+      );
+      if (hydratedItem && updatable) {
+        attachHiddenKey(hydratedItem, rawItem);
+      }
+    }
+  }
+  if (options?.hydrate) {
+    return options.hydrate(hydratedItem);
+  }
+  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,
+    after: exclusiveStartKey,
+    order: options?.order,
+    consistentRead: options?.consistentRead,
+    filter
+  });
+  const relationOps = planRelationOperations(metadata, select, {
+    estimatedParentCount: 1
+  });
+  return {
+    operations: [...mainPlan.operations, ...relationOps]
+  };
+}
+
+// src/operations/batch.ts
+var BatchGetResult = class {
+  groups;
+  constructor(groups) {
+    this.groups = groups;
+  }
+  get(model) {
+    const modelClass = resolveModelClass(model);
+    return this.groups.get(modelClass) ?? [];
+  }
+};
+function buildScalarSelect(metadata) {
+  const select = {};
+  for (const field of metadata.fields) {
+    select[field.propertyName] = true;
+  }
+  return select;
+}
+function buildDynamoKey(modelClass, keyObj) {
+  const deleteInput = buildDeleteInput(modelClass, keyObj);
+  return deleteInput.Key;
+}
+function hydrateBatchItems(rawItems, metadata) {
+  if (rawItems.length === 0) {
+    return [];
+  }
+  const select = buildScalarSelect(metadata);
+  const hydrated = hydrate(rawItems, select, metadata);
+  if (metadata.embeddedFields.length === 0) {
+    return hydrated;
+  }
+  return hydrated.map((item, index) => {
+    const raw = rawItems[index];
+    const merged = { ...item };
+    for (const emb of metadata.embeddedFields) {
+      const rawEmb = raw?.[emb.propertyName];
+      if (rawEmb !== void 0 && rawEmb !== null) {
+        merged[emb.propertyName] = rawEmb;
+      }
+    }
+    return merged;
+  });
+}
+async function executeBatchGetForTable(tableName, entries) {
+  const groups = /* @__PURE__ */ new Map();
+  if (entries.length === 0) {
+    return groups;
+  }
+  const keys = entries.map((entry) => entry.dynamoKey);
+  const { items: rawItems } = await ClientManager.getExecutor().batchGet({
+    tableName,
+    keys
+  });
+  const entriesByModel = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const existing = entriesByModel.get(entry.modelClass) ?? [];
+    existing.push(entry);
+    entriesByModel.set(entry.modelClass, existing);
+  }
+  for (const [modelClass, modelEntries] of entriesByModel) {
+    const metadata = modelEntries[0].metadata;
+    const expectedKeys = new Set(
+      modelEntries.map(
+        (entry) => `${String(entry.dynamoKey.PK)}::${String(entry.dynamoKey.SK)}`
+      )
+    );
+    const modelRawItems = rawItems.filter(
+      (item) => expectedKeys.has(`${String(item.PK)}::${String(item.SK)}`)
+    );
+    groups.set(modelClass, hydrateBatchItems(modelRawItems, metadata));
+  }
+  return groups;
+}
+async function executeBatchGet(requests) {
+  const entriesByTable = /* @__PURE__ */ new Map();
+  for (const request of requests) {
+    const modelClass = resolveModelClass(request.model);
+    const metadata = MetadataRegistry.get(modelClass);
+    const tableName = TableMapping.resolve(metadata.tableName);
+    for (const keyObj of request.keys) {
+      const entry = {
+        modelClass,
+        metadata,
+        dynamoKey: buildDynamoKey(modelClass, keyObj)
+      };
+      const existing = entriesByTable.get(tableName) ?? [];
+      existing.push(entry);
+      entriesByTable.set(tableName, existing);
+    }
+  }
+  const mergedGroups = /* @__PURE__ */ new Map();
+  for (const [, entries] of entriesByTable) {
+    const tableName = TableMapping.resolve(entries[0].metadata.tableName);
+    const tableGroups = await executeBatchGetForTable(tableName, entries);
+    for (const [modelClass, items] of tableGroups) {
+      const existing = mergedGroups.get(modelClass) ?? [];
+      mergedGroups.set(modelClass, existing.concat(items));
+    }
+  }
+  return new BatchGetResult(mergedGroups);
+}
+function toExecItem(entry) {
+  if (entry.request.type === "put") {
+    return { type: "put", item: entry.request.putInput.Item };
+  }
+  return { type: "delete", key: entry.request.deleteInput.Key };
+}
+async function executeBatchWrite(requests) {
+  const entriesByTable = /* @__PURE__ */ new Map();
+  for (const request of requests) {
+    const modelClass = resolveModelClass(request.model);
+    const metadata = MetadataRegistry.get(modelClass);
+    const tableName = TableMapping.resolve(metadata.tableName);
+    if (request.type === "put") {
+      const putInput = buildPutInput(modelClass, request.item, request.options);
+      const entry2 = {
+        tableName,
+        modelName: modelClass.name,
+        request: { type: "put", putInput }
+      };
+      const existing2 = entriesByTable.get(tableName) ?? [];
+      existing2.push(entry2);
+      entriesByTable.set(tableName, existing2);
+      continue;
+    }
+    const deleteInput = buildDeleteInput(modelClass, request.key, request.options);
+    const entry = {
+      tableName,
+      modelName: modelClass.name,
+      request: { type: "delete", deleteInput }
+    };
+    const existing = entriesByTable.get(tableName) ?? [];
+    existing.push(entry);
+    entriesByTable.set(tableName, existing);
+  }
+  const executor = ClientManager.getExecutor();
+  for (const [tableName, entries] of entriesByTable) {
+    await executor.batchWrite(tableName, entries.map(toExecItem));
+  }
+  if (ChangeCaptureRegistry.hasSubscribers()) {
+    for (const [, entries] of entriesByTable) {
+      for (const entry of entries) {
+        if (entry.request.type === "put") {
+          const item = entry.request.putInput.Item;
+          captureWrite({
+            table: entry.tableName,
+            ...entry.modelName ? { model: entry.modelName } : {},
+            op: "put",
+            keys: { pk: String(item.PK), sk: String(item.SK ?? "") },
+            newItem: item
+          });
+        } else {
+          const dkey = entry.request.deleteInput.Key;
+          captureWrite({
+            table: entry.tableName,
+            ...entry.modelName ? { model: entry.modelName } : {},
+            op: "delete",
+            keys: { pk: String(dkey.PK), sk: String(dkey.SK ?? "") }
+          });
+        }
+      }
+    }
+  }
+}
+
+// src/define/entity-writes.ts
+var LIFECYCLE_CONTRACT_MARKER = /* @__PURE__ */ Symbol(
+  "graphddb:lifecycleContract"
+);
+function isLifecycleContract(value) {
+  return typeof value === "object" && value !== null && value[LIFECYCLE_CONTRACT_MARKER] === true;
+}
+var ENTITY_WRITES_MARKER = /* @__PURE__ */ Symbol("graphddb:entityWrites");
+function isEntityWritesDefinition(value) {
+  return typeof value === "object" && value !== null && value[ENTITY_WRITES_MARKER] === true;
+}
+function freezeEffects(effects) {
+  const out = {};
+  if (effects.requires !== void 0) out.requires = effects.requires;
+  if (effects.unique !== void 0) out.unique = effects.unique;
+  if (effects.edges !== void 0) out.edges = effects.edges;
+  if (effects.derive !== void 0) out.derive = effects.derive;
+  if (effects.emits !== void 0) out.emits = effects.emits;
+  if (effects.idempotency !== void 0) out.idempotency = effects.idempotency;
+  return out;
+}
+var recorder = {
+  lifecycle(effects = {}) {
+    return {
+      [LIFECYCLE_CONTRACT_MARKER]: true,
+      effects: freezeEffects(effects)
+    };
+  },
+  exists(targetFactory, keys) {
+    return { kind: "requires", targetFactory, keys };
+  },
+  unique(spec) {
+    return { kind: "unique", name: spec.name, scope: spec.scope, fields: spec.fields };
+  },
+  putEdge(targetFactory, relationProperty) {
+    return { kind: "putEdge", targetFactory, relationProperty };
+  },
+  deleteEdge(targetFactory, relationProperty) {
+    return { kind: "deleteEdge", targetFactory, relationProperty };
+  },
+  increment(targetFactory, keys, attribute, amount) {
+    return { kind: "derive", targetFactory, keys, attribute, amount };
+  },
+  event(name, payload) {
+    return { kind: "event", name, payload };
+  },
+  idempotentBy(token) {
+    return { kind: "idempotency", token };
+  }
+};
+function entityWrites(builder) {
+  const shape = builder(recorder);
+  for (const phase of ["create", "update", "remove"]) {
+    const contract = shape[phase];
+    if (contract !== void 0 && !isLifecycleContract(contract)) {
+      throw new Error(
+        `entityWrites: the '${phase}' lifecycle must be built with \`w.lifecycle({...})\` (it carries the \xA72 effect arrays), but received ${JSON.stringify(contract)}.`
+      );
+    }
+  }
+  if (shape.create === void 0 && shape.update === void 0 && shape.remove === void 0) {
+    throw new Error(
+      "entityWrites(...) must declare at least one lifecycle (`create` / `update` / `remove`); an empty save contract declares nothing."
+    );
+  }
+  return {
+    [ENTITY_WRITES_MARKER]: true,
+    ...shape.create !== void 0 ? { create: shape.create } : {},
+    ...shape.update !== void 0 ? { update: shape.update } : {},
+    ...shape.remove !== void 0 ? { remove: shape.remove } : {}
+  };
+}
+function getEntityWrites(modelClass) {
+  for (const name of Object.getOwnPropertyNames(modelClass)) {
+    let value;
+    try {
+      value = modelClass[name];
+    } catch {
+      continue;
+    }
+    if (isEntityWritesDefinition(value)) return value;
+  }
+  return void 0;
+}
+function lifecyclePhaseForIntent(intent) {
+  return intent;
+}
+
+// src/relation/edge-write.ts
+var OLD_VALUE_NAMESPACE = "old";
+var EDGE_WRITES_MARKER = /* @__PURE__ */ Symbol("graphddb:edgeWrites");
+function isEdgeWritesDefinition(value) {
+  return typeof value === "object" && value !== null && value[EDGE_WRITES_MARKER] === true;
+}
+function declaration(target, relationProperty) {
+  return { targetFactory: target, relationProperty };
+}
+var recorder2 = {
+  putEdge: declaration,
+  deleteEdge: declaration,
+  updateKeyChangeEdge: declaration
+};
+function edgeWrites(builder) {
+  const edges = builder(recorder2);
+  if (edges.length === 0) {
+    throw new Error(
+      "edgeWrites(...) must declare at least one edge (w.putEdge / w.deleteEdge / w.updateKeyChangeEdge); an empty declaration writes nothing."
+    );
+  }
+  return { [EDGE_WRITES_MARKER]: true, edges };
 }
 function edgeKeyFields(segmented) {
   return [
@@ -531,335 +1701,1244 @@ function assertRelationRoundTrips(entity, edgeFields, decl) {
   );
   if (!relation) {
     throw new Error(
-      `Edge write declaration references relation '${decl.relationProperty}' on '${targetClass.name}', which has no such relation. Declare the edge with the read-side relation property it materializes.`
+      `Edge write declaration references relation '${decl.relationProperty}' on '${targetClass.name}', which has no such relation. Declare the edge with the read-side relation property it materializes.`
+    );
+  }
+  const boundFields = Object.keys(relation.keyBinding);
+  for (const targetField of boundFields) {
+    if (!edgeFields.has(targetField)) {
+      throw new Error(
+        `Edge write declaration for relation '${decl.relationProperty}' on '${targetClass.name}' binds on field '${targetField}', which is not a key field of the adjacency entity '${entity.tableName}' edge (key fields: ${[...edgeFields].map((f) => `'${f}'`).join(", ")}). The written row would not be reachable by the relation's read \u2014 declare the edge on the entity whose key carries the relation's bound field.`
+      );
+    }
+  }
+  try {
+    resolveKey(boundFields, entity);
+  } catch (cause) {
+    throw new Error(
+      `Edge write declaration for relation '${decl.relationProperty}' on '${targetClass.name}' binds [${boundFields.map((f) => `'${f}'`).join(", ")}], which does not cover any access-pattern partition of the adjacency entity '${entity.tableName}' edge (base key [${edgeKeyFields(entity.primaryKey.segmented).map((f) => `'${f}'`).join(", ")}]). The relation's read could not resolve a partition for the written row, so the edge would be unreadable \u2014 bind every partition-key field of the index the relation reads through. (${cause.message})`
+    );
+  }
+  return relation;
+}
+function templateRecord(fields) {
+  const out = {};
+  for (const field of [...fields].sort()) {
+    out[field] = `{${field}}`;
+  }
+  return out;
+}
+function keyConditionTemplate(segmented, namespace) {
+  const nameOf = namespace ? (f) => `${namespace}.${f}` : (f) => f;
+  const { pk, sk } = evaluateKey(segmented, "param", void 0, nameOf);
+  const out = { PK: pk };
+  if (sk !== void 0) out.SK = sk;
+  return out;
+}
+function putItemTemplate(edgeFields) {
+  return templateRecord(edgeFields);
+}
+function deriveEdgeWriteItemsFor(adjacencyClass, decl, lifecycle) {
+  const entity = MetadataRegistry.get(adjacencyClass);
+  if (!entity.primaryKey) {
+    throw new Error(
+      `Cannot derive edge write items for an entity with no primary key (table '${entity.tableName}'): an edge row needs a key to write / delete.`
+    );
+  }
+  const segmented = entity.primaryKey.segmented;
+  const edgeFields = edgeKeyFields(segmented);
+  assertRelationRoundTrips(entity, new Set(edgeFields), decl);
+  const tableName = TableMapping.resolve(entity.tableName);
+  const entityName = adjacencyClass.name;
+  const put = {
+    type: "Put",
+    tableName,
+    entity: entityName,
+    item: putItemTemplate(edgeFields)
+  };
+  const deleteNew = {
+    type: "Delete",
+    tableName,
+    entity: entityName,
+    keyCondition: keyConditionTemplate(segmented)
+  };
+  const deleteOld = {
+    type: "Delete",
+    tableName,
+    entity: entityName,
+    keyCondition: keyConditionTemplate(segmented, OLD_VALUE_NAMESPACE)
+  };
+  switch (lifecycle) {
+    case "onCreate":
+      return [put];
+    case "onDelete":
+      return [deleteNew];
+    case "onUpdateKeyChange":
+      return [deleteOld, put];
+  }
+}
+function deriveEdgeWriteItems(adjacencyClass, writes, lifecycle) {
+  const items = [];
+  for (const decl of writes.edges) {
+    items.push(...deriveEdgeWriteItemsFor(adjacencyClass, decl, lifecycle));
+  }
+  return items;
+}
+function getEdgeWrites(modelClass) {
+  for (const name of Object.getOwnPropertyNames(modelClass)) {
+    let value;
+    try {
+      value = modelClass[name];
+    } catch {
+      continue;
+    }
+    if (isEdgeWritesDefinition(value)) return value;
+  }
+  return void 0;
+}
+function deriveModelEdgeWriteItems(modelClass, lifecycle) {
+  const writes = getEdgeWrites(modelClass);
+  if (!writes) {
+    throw new Error(
+      `Model '${modelClass.name}' declares no edge write side (no static \`writes = edgeWrites(...)\`). Declare it to derive adjacency items.`
+    );
+  }
+  return deriveEdgeWriteItems(modelClass, writes, lifecycle);
+}
+
+// src/runtime/command-runtime.ts
+function resolveCommandMethod(contract, methodName) {
+  const method = contract.methods[methodName];
+  if (method === void 0) {
+    throw new Error(
+      `Contract runtime: command method '${methodName}' does not exist on this contract. Available methods: ${Object.keys(contract.methods).sort().join(", ") || "(none)"}.`
     );
   }
-  const boundFields = Object.keys(relation.keyBinding);
-  for (const targetField of boundFields) {
-    if (!edgeFields.has(targetField)) {
+  return method;
+}
+function modelClassOf(op) {
+  return op.entity.modelClass;
+}
+function modelStaticOf(op) {
+  return op.entity.modelClass.asModel();
+}
+function renderLeaf(leaf, key, params, context) {
+  if (isContractParamRef(leaf)) {
+    if (!(leaf.field in params)) {
       throw new Error(
-        `Edge write declaration for relation '${decl.relationProperty}' on '${targetClass.name}' binds on field '${targetField}', which is not a key field of the adjacency entity '${entity.tableName}' edge (key fields: ${[...edgeFields].map((f) => `'${f}'`).join(", ")}). The written row would not be reachable by the relation's read \u2014 declare the edge on the entity whose key carries the relation's bound field.`
+        `Contract runtime: ${context} references params field '${leaf.field}', which was not supplied. Pass it in the method's params argument.`
       );
     }
+    return params[leaf.field];
   }
-  try {
-    resolveKey(boundFields, entity);
-  } catch (cause) {
+  if (isContractKeyFieldRef(leaf)) {
+    if (leaf.field in key) return key[leaf.field];
+    if (leaf.field in params) return params[leaf.field];
     throw new Error(
-      `Edge write declaration for relation '${decl.relationProperty}' on '${targetClass.name}' binds [${boundFields.map((f) => `'${f}'`).join(", ")}], which does not cover any access-pattern partition of the adjacency entity '${entity.tableName}' edge (base key [${edgeKeyFields(entity.primaryKey.segmented).map((f) => `'${f}'`).join(", ")}]). The relation's read could not resolve a partition for the written row, so the edge would be unreadable \u2014 bind every partition-key field of the index the relation reads through. (${cause.message})`
+      `Contract runtime: ${context} references key field '${leaf.field}', which was not supplied. Pass it in the method's key or params argument.`
     );
   }
-  return relation;
+  return leaf;
 }
-function templateRecord(fields) {
+function renderRecord(structure, key, params, context) {
   const out = {};
-  for (const field of [...fields].sort()) {
-    out[field] = `{${field}}`;
+  if (structure === void 0) return out;
+  for (const [field, leaf] of Object.entries(structure)) {
+    out[field] = renderLeaf(leaf, key, params, `${context} field '${field}'`);
   }
   return out;
 }
-function keyConditionTemplate(segmented, namespace) {
-  const nameOf = namespace ? (f) => `${namespace}.${f}` : (f) => f;
-  const { pk, sk } = evaluateKey(segmented, "param", void 0, nameOf);
-  const out = { PK: pk };
-  if (sk !== void 0) out.SK = sk;
+function renderCondition(condition, key, params, context) {
+  if (condition === void 0) return void 0;
+  if (isRawCondition(condition)) {
+    const parts = condition.parts.map(
+      (part) => isColumn(part) ? part : renderLeaf(part, key, params, `${context} condition`)
+    );
+    return { ...condition, parts };
+  }
+  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 };
+    }
+    if (typeof obj.attributeNotExists === "string") {
+      return { attributeNotExists: obj.attributeNotExists };
+    }
+  }
+  return renderRecord(
+    condition,
+    key,
+    params,
+    `${context} condition`
+  );
+}
+function renderWrite(op, key, params, contextLabel) {
+  if (!isContractKeyRef(op.keys) && op.operation !== "put") {
+    throw new Error(
+      `Contract runtime: ${contextLabel} did not pass the contract key directly into its '${op.operation}' key position. A command method must call \`Model.${op.operation}(keys, \u2026)\` with the key whole.`
+    );
+  }
+  const base = {
+    operation: op.operation,
+    modelClass: modelClassOf(op),
+    modelStatic: modelStaticOf(op),
+    key,
+    condition: renderCondition(op.condition, key, params, contextLabel)
+  };
+  if (op.operation === "put") {
+    return { ...base, item: renderRecord(op.item, key, params, `${contextLabel} item`) };
+  }
+  if (op.operation === "update") {
+    return { ...base, changes: renderRecord(op.changes, key, params, `${contextLabel} changes`) };
+  }
+  return base;
+}
+async function executeSingleWrite(w) {
+  const options = w.condition !== void 0 ? { condition: w.condition } : void 0;
+  if (w.operation === "put") {
+    await executePut(w.modelClass, w.item ?? {}, options);
+    return;
+  }
+  if (w.operation === "update") {
+    await executeUpdate(w.modelClass, w.key, w.changes ?? {}, options);
+    return;
+  }
+  await executeDelete(w.modelClass, w.key, options);
+}
+async function readBackProjection(write, returnSelection) {
+  const select = {};
+  for (const field of Object.keys(returnSelection)) {
+    if (returnSelection[field] === true) select[field] = true;
+  }
+  const key = readBackKey(write);
+  return executeQuery(write.modelClass, key, select, { consistentRead: true });
+}
+function readBackKey(write) {
+  if (write.operation !== "put") return write.key;
+  const metadata = MetadataRegistry.get(write.modelClass);
+  const item = write.item ?? {};
+  const key = {};
+  const fields = metadata.primaryKey ? metadata.primaryKey.inputFieldNames : Object.keys(item);
+  for (const field of fields) {
+    if (field in item) key[field] = item[field];
+  }
+  return key;
+}
+function renderConditionCheck(check, key, params, contextLabel) {
+  const modelClass = check.entity.modelClass;
+  const referencedKey = {};
+  for (const [targetField, inputField] of Object.entries(check.keyBinding)) {
+    if (inputField in params) {
+      referencedKey[targetField] = params[inputField];
+    } else if (inputField in key) {
+      referencedKey[targetField] = key[inputField];
+    } else {
+      throw new Error(
+        `Contract runtime: ${contextLabel} asserts '${check.entity.name}' exists, keyed by input field '${inputField}', which was not supplied. Pass it in the method's params (or key) argument.`
+      );
+    }
+  }
+  const { TableName, Key } = buildDeleteInput(
+    modelClass,
+    referencedKey
+  );
+  const cond = buildConditionExpression({ attributeExists: "PK" });
+  const checkInput = {
+    TableName,
+    Key,
+    ConditionExpression: cond.expression
+  };
+  if (Object.keys(cond.names).length > 0) checkInput.ExpressionAttributeNames = cond.names;
+  if (Object.keys(cond.values).length > 0) checkInput.ExpressionAttributeValues = cond.values;
+  return checkInput;
+}
+var RUNTIME_TOKEN_RE = /\{([^{}]+)\}/g;
+function renderTemplate(template, key, params, contextLabel) {
+  const resolveToken = (token) => {
+    if (token in params) return params[token];
+    if (token in key) return key[token];
+    throw new Error(
+      `Contract runtime: ${contextLabel} references input field '${token}', which was not supplied. Pass it in the method's params (or key) argument` + (token.startsWith("old.") ? ` \u2014 an \`old.*\` token is the pre-mutation value of a foreign key on an onUpdateKeyChange (pass it as \`{ '${token}': \u2026 }\`).` : `.`)
+    );
+  };
+  const whole = /^\{([^{}]+)\}$/.exec(template);
+  if (whole !== null) return resolveToken(whole[1]);
+  return template.replace(RUNTIME_TOKEN_RE, (_m, token) => String(resolveToken(token)));
+}
+function renderTemplateRecord(record, key, params, contextLabel) {
+  const out = {};
+  for (const [field, template] of Object.entries(record ?? {})) {
+    out[field] = renderTemplate(template, key, params, contextLabel);
+  }
   return out;
 }
-function putItemTemplate(edgeFields) {
-  return templateRecord(edgeFields);
+function renderEdgeWriteItems(edge, key, params, contextLabel, modelBySignature) {
+  const adjacency = edge.entity.modelClass;
+  return edge.items.map((item) => {
+    if (item.type === "Put") {
+      const rendered = renderTemplateRecord(item.item, key, params, `${contextLabel} edge Put`);
+      const out2 = { Put: buildPutInput(adjacency, rendered) };
+      modelBySignature?.set(execItemKeySignature(out2), adjacency.name);
+      return out2;
+    }
+    const renderedKey = renderTemplateRecord(
+      item.keyCondition,
+      key,
+      params,
+      `${contextLabel} edge Delete`
+    );
+    const del = {
+      TableName: TableMapping.resolve(item.tableName),
+      Key: renderedKey
+    };
+    const out = { Delete: del };
+    modelBySignature?.set(execItemKeySignature(out), adjacency.name);
+    return out;
+  });
 }
-function deriveEdgeWriteItemsFor(adjacencyClass, decl, lifecycle) {
-  const entity = MetadataRegistry.get(adjacencyClass);
-  if (!entity.primaryKey) {
+function renderDerivedUpdate(update, key, params, contextLabel, modelBySignature) {
+  const metadata = MetadataRegistry.get(update.entity.modelClass);
+  if (!metadata.primaryKey) {
     throw new Error(
-      `Cannot derive edge write items for an entity with no primary key (table '${entity.tableName}'): an edge row needs a key to write / delete.`
+      `Contract runtime: ${contextLabel} derives a counter update on '${update.entity.name}', which has no primary key.`
     );
   }
-  const segmented = entity.primaryKey.segmented;
-  const edgeFields = edgeKeyFields(segmented);
-  assertRelationRoundTrips(entity, new Set(edgeFields), decl);
-  const tableName = TableMapping.resolve(entity.tableName);
-  const entityName = adjacencyClass.name;
-  const put = {
-    type: "Put",
-    tableName,
-    entity: entityName,
-    item: putItemTemplate(edgeFields)
+  const keyInput = {};
+  for (const [targetField, inputField] of Object.entries(update.keyBinding)) {
+    keyInput[targetField] = renderTemplate(
+      `{${inputField}}`,
+      key,
+      params,
+      `${contextLabel} derived-update key`
+    );
+  }
+  const { TableName, Key } = buildDeleteInput(
+    update.entity.modelClass,
+    keyInput
+  );
+  const updateInput = {
+    TableName,
+    Key,
+    UpdateExpression: "ADD #a0 :a0",
+    ExpressionAttributeNames: { "#a0": update.attribute },
+    ExpressionAttributeValues: { ":a0": update.amount }
   };
-  const deleteNew = {
-    type: "Delete",
-    tableName,
-    entity: entityName,
-    keyCondition: keyConditionTemplate(segmented)
+  const out = { Update: updateInput };
+  modelBySignature?.set(execItemKeySignature(out), update.entity.modelClass.name);
+  return out;
+}
+function renderUniqueGuardItems(guard, key, params, contextLabel) {
+  return guard.items.map((item) => {
+    if (item.type === "Put") {
+      const Item = renderTemplateRecord(item.item, key, params, `${contextLabel} guard Put`);
+      const put = { TableName: TableMapping.resolve(item.tableName), Item };
+      const cond = buildConditionExpression({ attributeNotExists: "PK" });
+      put.ConditionExpression = cond.expression;
+      if (Object.keys(cond.names).length > 0) put.ExpressionAttributeNames = cond.names;
+      if (Object.keys(cond.values).length > 0) put.ExpressionAttributeValues = cond.values;
+      return { Put: put };
+    }
+    const Key = renderTemplateRecord(item.keyCondition, key, params, `${contextLabel} guard Delete`);
+    const del = { TableName: TableMapping.resolve(item.tableName), Key };
+    return { Delete: del };
+  });
+}
+function renderOutboxEventItems(event, key, params, contextLabel) {
+  return event.items.map((item) => {
+    const Item = renderTemplateRecord(item.item, key, params, `${contextLabel} outbox Put`);
+    const put = { TableName: TableMapping.resolve(item.tableName), Item };
+    return { Put: put };
+  });
+}
+function renderIdempotencyGuardItems(guard, key, params, contextLabel) {
+  return guard.items.map((item) => {
+    const Item = renderTemplateRecord(item.item, key, params, `${contextLabel} idempotency Put`);
+    const put = { TableName: TableMapping.resolve(item.tableName), Item };
+    const cond = buildConditionExpression({ attributeNotExists: "PK" });
+    put.ConditionExpression = cond.expression;
+    if (Object.keys(cond.names).length > 0) put.ExpressionAttributeNames = cond.names;
+    if (Object.keys(cond.values).length > 0) put.ExpressionAttributeValues = cond.values;
+    return { Put: put };
+  });
+}
+async function executeReferentialTransaction(writes, edgeItems, updateItems, guardItemsRaw, outboxItems, idempotencyItems, checks, methodName, modelBySignature = /* @__PURE__ */ new Map()) {
+  const writeItems = writes.map((w) => {
+    const options = w.condition !== void 0 ? { condition: w.condition } : void 0;
+    let item;
+    if (w.operation === "put") {
+      item = { Put: buildPutInput(w.modelClass, w.item ?? {}, options) };
+    } else if (w.operation === "update") {
+      item = { Update: buildUpdateInput(w.modelClass, w.key, w.changes ?? {}, options) };
+    } else {
+      item = { Delete: buildDeleteInput(w.modelClass, w.key, options) };
+    }
+    modelBySignature.set(execItemKeySignature(item), w.modelClass.name);
+    return item;
+  });
+  const checkItems = checks.map((c) => ({ ConditionCheck: c.check }));
+  await commitTransaction(
+    [
+      ...writeItems,
+      ...edgeItems,
+      ...updateItems,
+      ...guardItemsRaw,
+      ...outboxItems,
+      ...idempotencyItems,
+      ...checkItems
+    ],
+    {
+      modelBySignature,
+      limitError: (count) => new Error(
+        `Contract runtime: command method '${methodName}' composes ${count} items (writes + edges + derived updates + uniqueness guards + outbox events + idempotency guard + ConditionChecks) into one TransactWriteItems, but DynamoDB caps a transaction at ${MAX_TRANSACT_ITEMS} items and a transaction is atomic \u2014 it cannot be split. Reduce the fragment / effect count.`
+      )
+    }
+  );
+}
+async function executeTransactWrites(writes, methodName) {
+  if (writes.length === 0) return;
+  const modelBySignature = /* @__PURE__ */ new Map();
+  const transactItems = writes.map((w) => {
+    const options = w.condition !== void 0 ? { condition: w.condition } : void 0;
+    let item;
+    if (w.operation === "put") {
+      item = { Put: buildPutInput(w.modelClass, w.item ?? {}, options) };
+    } else if (w.operation === "update") {
+      item = { Update: buildUpdateInput(w.modelClass, w.key, w.changes ?? {}, options) };
+    } else {
+      item = { Delete: buildDeleteInput(w.modelClass, w.key, options) };
+    }
+    modelBySignature.set(execItemKeySignature(item), w.modelClass.name);
+    return item;
+  });
+  await commitTransaction(transactItems, {
+    modelBySignature,
+    limitError: (count) => new Error(
+      `Contract runtime: command method '${methodName}' resolves an array of ${count} keys to a 'transact' (TransactWriteItems) batch, but DynamoDB caps a transaction at ${MAX_TRANSACT_ITEMS} items and a transaction is atomic \u2014 it cannot be split across requests without breaking atomicity. Pass \u2264${MAX_TRANSACT_ITEMS} keys, or declare \`batch: 'batchWrite'\` (a non-atomic BatchWriteItem, chunked automatically) if atomicity is not required.`
+    )
+  });
+}
+async function executeParallelWrites(writes) {
+  if (writes.length === 0) return [];
+  const coalescible = writes.every(
+    (w) => w.condition === void 0 && (w.operation === "put" || w.operation === "delete")
+  );
+  if (coalescible) {
+    const requests = writes.map(
+      (w) => w.operation === "put" ? { type: "put", model: w.modelStatic, item: w.item ?? {} } : { type: "delete", model: w.modelStatic, key: w.key }
+    );
+    await executeBatchWrite(requests);
+    return writes.map(() => ({ ok: true }));
+  }
+  return Promise.all(
+    writes.map(async (w) => {
+      try {
+        await executeSingleWrite(w);
+        return { ok: true };
+      } catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+      }
+    })
+  );
+}
+async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}) {
+  const method = resolveCommandMethod(contract, methodName);
+  if (Array.isArray(keyOrKeys)) {
+    const keys = keyOrKeys;
+    if (method.ops !== void 0 && method.ops.length > 1) {
+      throw new Error(
+        `Contract runtime: command method '${methodName}' is a multi-fragment mutation (it composes ${method.ops.length} fragments into one atomic TransactWriteItems) and accepts a single key only. Call it once per target, not with a key array.`
+      );
+    }
+    const hasDerivedEffects2 = method.conditionChecks !== void 0 && method.conditionChecks.length > 0 || method.edgeWrites !== void 0 && method.edgeWrites.length > 0 || method.derivedUpdates !== void 0 && method.derivedUpdates.length > 0 || method.uniqueGuards !== void 0 && method.uniqueGuards.length > 0 || method.outboxEvents !== void 0 && method.outboxEvents.length > 0 || method.idempotencyGuard !== void 0;
+    if (hasDerivedEffects2) {
+      throw new Error(
+        `Contract runtime: command method '${methodName}' carries derived effects (referential integrity / edge writes / derived counters / uniqueness guards / outbox events / idempotency guard \u2014 it composes its write + those items into one atomic TransactWriteItems) and accepts a single key only. Call it once per target, not with a key array.`
+      );
+    }
+    const writes = keys.map(
+      (key2, i) => renderWrite(method.op, key2, params, `command method '${methodName}' (key #${i})`)
+    );
+    if (method.mode === "parallel") {
+      return { results: await executeParallelWrites(writes) };
+    }
+    await executeTransactWrites(writes, methodName);
+    return;
+  }
+  const key = keyOrKeys;
+  const conditionChecks = method.conditionChecks ?? [];
+  const edgeWrites2 = method.edgeWrites ?? [];
+  const derivedUpdates = method.derivedUpdates ?? [];
+  const uniqueGuards = method.uniqueGuards ?? [];
+  const outboxEvents = method.outboxEvents ?? [];
+  const idempotencyGuard = method.idempotencyGuard;
+  const hasDerivedEffects = conditionChecks.length > 0 || edgeWrites2.length > 0 || derivedUpdates.length > 0 || uniqueGuards.length > 0 || outboxEvents.length > 0 || idempotencyGuard !== void 0;
+  const isMultiFragment = method.ops !== void 0 && method.ops.length > 1;
+  if (isMultiFragment || hasDerivedEffects) {
+    const ops = method.ops ?? [method.op];
+    const writes = ops.map(
+      (opn, i) => renderWrite(opn, key, params, `command method '${methodName}' (fragment #${i})`)
+    );
+    if (hasDerivedEffects) {
+      const modelBySignature = /* @__PURE__ */ new Map();
+      const edgeItems = edgeWrites2.flatMap(
+        (edge, i) => renderEdgeWriteItems(
+          edge,
+          key,
+          params,
+          `command method '${methodName}' (edge #${i})`,
+          modelBySignature
+        )
+      );
+      const updateItems = derivedUpdates.map(
+        (update, i) => renderDerivedUpdate(
+          update,
+          key,
+          params,
+          `command method '${methodName}' (derive #${i})`,
+          modelBySignature
+        )
+      );
+      const guardItems = uniqueGuards.flatMap(
+        (guard, i) => renderUniqueGuardItems(guard, key, params, `command method '${methodName}' (unique #${i})`)
+      );
+      const outboxItems = outboxEvents.flatMap(
+        (event, i) => renderOutboxEventItems(event, key, params, `command method '${methodName}' (emit #${i})`)
+      );
+      const idempotencyItems = idempotencyGuard !== void 0 ? renderIdempotencyGuardItems(
+        idempotencyGuard,
+        key,
+        params,
+        `command method '${methodName}' (idempotency)`
+      ) : [];
+      const checks = conditionChecks.map((check, i) => ({
+        check: renderConditionCheck(
+          check,
+          key,
+          params,
+          `command method '${methodName}' (requires #${i})`
+        )
+      }));
+      await executeReferentialTransaction(
+        writes,
+        edgeItems,
+        updateItems,
+        guardItems,
+        outboxItems,
+        idempotencyItems,
+        checks,
+        methodName,
+        modelBySignature
+      );
+    } else {
+      await executeTransactWrites(writes, methodName);
+    }
+    if (method.returnSelection !== void 0 && Object.keys(method.returnSelection).length > 0) {
+      return readBackProjection(writes[0], method.returnSelection);
+    }
+    return;
+  }
+  const write = renderWrite(method.op, key, params, `command method '${methodName}'`);
+  await executeSingleWrite(write);
+  if (method.returnSelection !== void 0 && Object.keys(method.returnSelection).length > 0) {
+    return readBackProjection(write, method.returnSelection);
+  }
+}
+function renderCompiledOp(op, ctx) {
+  const fragment = op.fragment;
+  const baseOp = op.condition !== void 0 ? withCondition(fragment.op, op.condition) : fragment.op;
+  const modelBySignature = /* @__PURE__ */ new Map();
+  const write = renderWrite(baseOp, op.params, op.params, ctx);
+  const edgeItems = [];
+  const updateItems = [];
+  const guardItems = [];
+  const outboxItems = [];
+  const idempotencyItems = [];
+  const checkItems = [];
+  for (const edge of fragment.edgeWrites ?? []) {
+    edgeItems.push(...renderEdgeWriteItems(edge, op.params, op.params, `${ctx} edge`, modelBySignature));
+  }
+  for (const u of fragment.derivedUpdates ?? []) {
+    updateItems.push(renderDerivedUpdate(u, op.params, op.params, `${ctx} derive`, modelBySignature));
+  }
+  for (const g of fragment.uniqueGuards ?? []) {
+    guardItems.push(...renderUniqueGuardItems(g, op.params, op.params, `${ctx} unique`));
+  }
+  for (const e of fragment.outboxEvents ?? []) {
+    outboxItems.push(...renderOutboxEventItems(e, op.params, op.params, `${ctx} emit`));
+  }
+  if (fragment.idempotencyGuard !== void 0) {
+    idempotencyItems.push(
+      ...renderIdempotencyGuardItems(fragment.idempotencyGuard, op.params, op.params, `${ctx} idempotency`)
+    );
+  }
+  for (const c of fragment.conditionChecks ?? []) {
+    checkItems.push({ check: renderConditionCheck(c, op.params, op.params, `${ctx} requires`) });
+  }
+  const hasDerivedEffects = edgeItems.length > 0 || updateItems.length > 0 || guardItems.length > 0 || outboxItems.length > 0 || idempotencyItems.length > 0 || checkItems.length > 0;
+  return {
+    write,
+    edgeItems,
+    updateItems,
+    guardItems,
+    outboxItems,
+    idempotencyItems,
+    checkItems,
+    modelBySignature,
+    hasDerivedEffects
   };
-  const deleteOld = {
-    type: "Delete",
-    tableName,
-    entity: entityName,
-    keyCondition: keyConditionTemplate(segmented, OLD_VALUE_NAMESPACE)
+}
+function readBackForCompiledOp(op, write) {
+  const sel = op.result?.select;
+  if (sel === void 0 || Object.keys(sel).length === 0) return void 0;
+  const key = {};
+  for (const f of op.fragment.keyFields) {
+    if (f in op.params) key[f] = op.params[f];
+  }
+  return executeQuery(write.modelClass, key, sel, {
+    consistentRead: op.result?.options?.consistentRead ?? true,
+    maxDepth: op.result?.options?.maxDepth
+  });
+}
+async function executeCompiledWriteOp(ops, options) {
+  const label = options.label;
+  const renderedOps = ops.map((op, i) => renderCompiledOp(op, `${label} (op #${i})`));
+  const rendered = renderedOps.map((r) => r.write);
+  const modelBySignature = /* @__PURE__ */ new Map();
+  const edgeItems = [];
+  const updateItems = [];
+  const guardItems = [];
+  const outboxItems = [];
+  const idempotencyItems = [];
+  const checkItems = [];
+  for (const r of renderedOps) {
+    for (const [sig, name] of r.modelBySignature) modelBySignature.set(sig, name);
+    edgeItems.push(...r.edgeItems);
+    updateItems.push(...r.updateItems);
+    guardItems.push(...r.guardItems);
+    outboxItems.push(...r.outboxItems);
+    idempotencyItems.push(...r.idempotencyItems);
+    checkItems.push(...r.checkItems);
+  }
+  const hasDerivedEffects = renderedOps.some((r) => r.hasDerivedEffects);
+  if (rendered.length === 1 && !hasDerivedEffects) {
+    await executeSingleWrite(rendered[0]);
+  } else {
+    await executeReferentialTransaction(
+      rendered,
+      edgeItems,
+      updateItems,
+      guardItems,
+      outboxItems,
+      idempotencyItems,
+      checkItems,
+      label,
+      modelBySignature
+    );
+  }
+  const readBacks = await Promise.all(
+    ops.map((op, i) => readBackForCompiledOp(op, rendered[i]))
+  );
+  return { readBacks };
+}
+async function executeCompiledParallelWrites(ops, options) {
+  const label = options.label;
+  const results = new Array(ops.length);
+  const renderedOps = ops.map((op, i) => renderCompiledOp(op, `${label} (op #${i})`));
+  const coalescibleIdx = [];
+  const individualIdx = [];
+  renderedOps.forEach((r, i) => {
+    const w = r.write;
+    if (!r.hasDerivedEffects && w.condition === void 0 && (w.operation === "put" || w.operation === "delete")) {
+      coalescibleIdx.push(i);
+    } else {
+      individualIdx.push(i);
+    }
+  });
+  await Promise.all([
+    // The coalescible group → ONE BatchWriteItem (chunked, UnprocessedItems retry) via
+    // the shared public-layer coalescing. On success every op reports `{ ok: true }`
+    // plus its read-back; a BatchWriteItem request failure fails the whole group.
+    (async () => {
+      if (coalescibleIdx.length === 0) return;
+      const writes = coalescibleIdx.map((i) => renderedOps[i].write);
+      try {
+        await executeParallelWrites(writes);
+        await Promise.all(
+          coalescibleIdx.map(async (i) => {
+            const value = await readBackForCompiledOp(ops[i], renderedOps[i].write);
+            results[i] = { ok: true, value };
+          })
+        );
+      } catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e));
+        for (const i of coalescibleIdx) results[i] = { ok: false, error };
+      }
+    })(),
+    // Each individual op → its own single-op atomic execution (condition gate / derived
+    // effects / read-back preserved), concurrently and with per-op partial success.
+    ...individualIdx.map(async (i) => {
+      try {
+        const { readBacks } = await executeCompiledWriteOp([ops[i]], {
+          label: `${label} (op #${i})`
+        });
+        results[i] = { ok: true, value: readBacks[0] };
+      } catch (e) {
+        results[i] = { ok: false, error: e instanceof Error ? e : new Error(String(e)) };
+      }
+    })
+  ]);
+  return results;
+}
+function withCondition(op, condition) {
+  if (op.condition === void 0) return { ...op, condition };
+  const base = op.condition;
+  if (base.notExists === true && Object.keys(condition).length > 0) {
+    throw new Error(
+      `DDBModel.mutate: a \`condition\` (equality write gate) on a 'create' is not supported \u2014 a create already guards with attribute_not_exists(PK). Use an 'update' with a condition, or drop the condition.`
+    );
+  }
+  return { ...op, condition };
+}
+
+// src/runtime/envelope.ts
+async function executeReadEnvelope(envelope) {
+  const aliases = Object.keys(envelope);
+  const results = await Promise.all(
+    aliases.map((alias) => executeReadRoute(alias, envelope[alias]))
+  );
+  const out = {};
+  aliases.forEach((alias, i) => {
+    out[alias] = results[i];
+  });
+  return out;
+}
+async function executeReadRoute(alias, route) {
+  if (route === null || typeof route !== "object") {
+    throw new Error(
+      `DDBModel.query: the descriptor for alias '${alias}' is not a read descriptor (\`{ query | list: Model, key, select, options? }\`).`
+    );
+  }
+  const isQuery = route.query !== void 0;
+  const isList = route.list !== void 0;
+  if (isQuery === isList) {
+    throw new Error(
+      `DDBModel.query: the descriptor for alias '${alias}' must carry exactly one of \`query\` or \`list\` (the target model). It declared ${isQuery && isList ? "both" : "neither"}.`
+    );
+  }
+  if (route.key === void 0 || route.select === void 0) {
+    throw new Error(
+      `DDBModel.query: the '${isQuery ? "query" : "list"}' descriptor for alias '${alias}' must declare both \`key\` and \`select\`.`
+    );
+  }
+  const modelClass = resolveModelClass(
+    resolveModelStatic(isQuery ? route.query : route.list, alias)
+  );
+  const opt = route.options ?? {};
+  if (isQuery) {
+    return executeQuery(modelClass, route.key, route.select, {
+      consistentRead: opt.consistentRead,
+      maxDepth: opt.maxDepth
+    });
+  }
+  return executeList(modelClass, route.key, route.select, {
+    limit: opt.limit,
+    after: opt.after,
+    order: opt.order,
+    filter: opt.filter
+  });
+}
+var INTENT_KEYS = ["create", "update", "remove"];
+async function executeWriteEnvelope(envelope, options = {}) {
+  const mode = options.mode ?? "transaction";
+  const aliases = Object.keys(envelope);
+  if (aliases.length === 0) {
+    throw new Error(
+      "DDBModel.mutate: the write envelope is empty. Declare at least one `{ alias: { create | update | remove: Model, key, input? } }` operation."
+    );
+  }
+  const ops = aliases.flatMap((alias) => normalizeWriteOp(alias, envelope[alias]));
+  if (mode === "transaction") {
+    return executeTransactionMode(ops);
+  }
+  return executeParallelMode(ops);
+}
+function normalizeWriteOp(alias, d) {
+  if (d === null || typeof d !== "object") {
+    throw new Error(
+      `DDBModel.mutate: the descriptor for alias '${alias}' is not a write descriptor (\`{ create | update | remove: Model, key, input?, condition?, result? }\`).`
+    );
+  }
+  const present = INTENT_KEYS.filter((k) => d[k] !== void 0);
+  if (present.length !== 1) {
+    throw new Error(
+      `DDBModel.mutate: the descriptor for alias '${alias}' 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(
+      `DDBModel.mutate: the '${intent}' descriptor for alias '${alias}' must declare a \`key\` object (or a non-empty array of key objects) binding the target's primary-key fields.`
+    );
+  }
+  const model = resolveModelStatic(d[intent], alias);
+  const input = d.input ?? {};
+  const base = { alias, intent, model, input, condition: d.condition, result: d.result };
+  if (Array.isArray(d.key)) {
+    const keys = d.key;
+    if (keys.length === 0) {
+      throw new Error(
+        `DDBModel.mutate: the '${intent}' descriptor for alias '${alias}' declared an EMPTY key array. Pass at least one key, or omit the operation.`
+      );
+    }
+    return keys.map((key, bulkIndex) => {
+      if (key === null || typeof key !== "object") {
+        throw new Error(
+          `DDBModel.mutate: the '${intent}' descriptor for alias '${alias}' key #${bulkIndex} is not a key object.`
+        );
+      }
+      return { ...base, key, bulkIndex };
+    });
+  }
+  return [{ ...base, key: d.key }];
+}
+function compileWriteOp(op) {
+  const keyFieldNames2 = Object.keys(op.key);
+  const inputFieldNames = Object.keys(op.input);
+  const model = op.model;
+  const body = ($) => {
+    const descriptor = {
+      [op.intent]: (() => model),
+      key: mapToRefs($, keyFieldNames2),
+      ...inputFieldNames.length > 0 ? { input: mapToRefs($, inputFieldNames) } : {}
+    };
+    const map = { [op.alias]: descriptor };
+    return map;
   };
-  switch (lifecycle) {
-    case "onCreate":
-      return [put];
-    case "onDelete":
-      return [deleteNew];
-    case "onUpdateKeyChange":
-      return [deleteOld, put];
+  const plan2 = mutation(body);
+  if (!isCommandPlan(plan2)) {
+    throw new Error("DDBModel.mutate: internal error building the mutation plan.");
   }
+  const compiled = compileMutationPlan(plan2);
+  const fragment = compiled.fragments[0];
+  const params = { ...op.input, ...op.key };
+  return {
+    fragment,
+    params,
+    condition: op.condition,
+    result: op.result
+  };
+}
+function mapToRefs($, fields) {
+  const out = {};
+  for (const f of fields) out[f] = $[f];
+  return out;
 }
-function deriveEdgeWriteItems(adjacencyClass, writes, lifecycle) {
-  const items = [];
-  for (const decl of writes.edges) {
-    items.push(...deriveEdgeWriteItemsFor(adjacencyClass, decl, lifecycle));
-  }
-  return items;
+async function executeTransactionMode(ops) {
+  const compiled = ops.map(compileWriteOp);
+  const { readBacks } = await executeCompiledWriteOp(compiled, {
+    label: "DDBModel.mutate"
+  });
+  const out = {};
+  ops.forEach((op, i) => {
+    if (op.result === void 0) return;
+    if (op.bulkIndex === void 0) {
+      out[op.alias] = readBacks[i];
+    } else {
+      const arr = out[op.alias] ?? [];
+      arr[op.bulkIndex] = readBacks[i];
+      out[op.alias] = arr;
+    }
+  });
+  return out;
 }
-function getEdgeWrites(modelClass) {
-  for (const name of Object.getOwnPropertyNames(modelClass)) {
-    let value;
-    try {
-      value = modelClass[name];
-    } catch {
-      continue;
+async function executeParallelMode(ops) {
+  const compiled = ops.map(compileWriteOp);
+  const settled = await executeCompiledParallelWrites(compiled, {
+    label: "DDBModel.mutate"
+  });
+  const out = {};
+  ops.forEach((op, i) => {
+    const res = settled[i];
+    const mapped = res.ok ? { ok: true, value: op.result !== void 0 ? res.value : void 0 } : { ok: false, error: res.error };
+    if (op.bulkIndex === void 0) {
+      out[op.alias] = mapped;
+    } else {
+      const arr = out[op.alias] ?? [];
+      arr[op.bulkIndex] = mapped;
+      out[op.alias] = arr;
     }
-    if (isEdgeWritesDefinition(value)) return value;
+  });
+  return out;
+}
+function resolveModelStatic(ref, alias) {
+  if (ref === null || ref === void 0) {
+    throw new Error(`DDBModel: the descriptor for alias '${alias}' names no target model.`);
   }
-  return void 0;
+  if (typeof ref === "function") {
+    const asModel = ref.asModel;
+    if (typeof asModel === "function") {
+      return asModel.call(ref);
+    }
+    return resolveModelStatic(ref(), alias);
+  }
+  return ref;
 }
-function deriveModelEdgeWriteItems(modelClass, lifecycle) {
-  const writes = getEdgeWrites(modelClass);
-  if (!writes) {
-    throw new Error(
-      `Model '${modelClass.name}' declares no edge write side (no static \`writes = edgeWrites(...)\`). Declare it to derive adjacency items.`
+
+// src/model/DDBModel.ts
+var DDBModel = class {
+  static setClient(client) {
+    ClientManager.setClient(client);
+  }
+  static setTableMapping(mapping) {
+    TableMapping.set(mapping);
+  }
+  static async transaction(fn) {
+    await executeTransaction(fn);
+  }
+  /**
+   * In-process multi-route READ (issue #101 — the unified envelope). Each alias
+   * route (`{ query | list: Model, key, select, options? }`) runs **independently
+   * and in parallel**; the result is an object keyed by the input aliases. A
+   * `query` route delegates to the single-item read path, a `list` route to the
+   * partition read path. Cross-route consistency is NOT guaranteed.
+   */
+  static async query(envelope) {
+    return executeReadEnvelope(envelope);
+  }
+  static mutate(envelope, options) {
+    return executeWriteEnvelope(envelope, options);
+  }
+  static async batchGet(requests) {
+    return executeBatchGet(requests);
+  }
+  static async batchWrite(requests) {
+    return executeBatchWrite(requests);
+  }
+  static asModel() {
+    const modelClass = this;
+    const modelStatic = {
+      col: createColumnMap(),
+      project(select) {
+        return buildProject(select);
+      },
+      relation(select) {
+        return buildRelation(select);
+      },
+      // The public `query` is overloaded (plain / updatable / hydrate, the last
+      // introducing a fresh return-type parameter `R`, issue #53). An overloaded
+      // method on an object literal cannot contextually infer its single
+      // implementation signature, so the implementation is written with explicit
+      // runtime-facing parameter types and assigned through the interface's
+      // method type — the public overloads (the only caller-visible surface)
+      // are untouched.
+      query: ((key, select, options) => {
+        return executeQuery(modelClass, key, select, options);
+      }),
+      list: ((key, select, options) => {
+        return executeList(modelClass, key, select, options);
+      }),
+      explain(key, options) {
+        return executeExplain(
+          modelClass,
+          key,
+          options
+        );
+      },
+      async putItem(item, options) {
+        await executePut(
+          modelClass,
+          item,
+          options
+        );
+      },
+      async updateItem(entity, changes, options) {
+        await executeUpdate(
+          modelClass,
+          entity,
+          changes,
+          options
+        );
+      },
+      async deleteItem(key, options) {
+        await executeDelete(modelClass, key, options);
+      }
+    };
+    return attachModelClass(
+      modelStatic,
+      modelClass
     );
   }
-  return deriveEdgeWriteItems(modelClass, writes, lifecycle);
-}
+};
 
-// src/define/contract.ts
-function isCommandBatchMode(value) {
-  return value === "transact" || value === "batchWrite";
-}
-var KEY_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:contractKeyRef");
-var KEY_FIELD_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:contractKeyFieldRef");
-function isContractKeyRef(value) {
-  return typeof value === "object" && value !== null && value[KEY_REF_BRAND] === true;
-}
-function mintContractKeyFieldRef(field) {
-  return { [KEY_FIELD_REF_BRAND]: true, field, token: `{key.${field}}` };
+// src/define/mutation.ts
+var INPUT_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:mutationInputRef");
+function isMutationInputRef(value) {
+  return typeof value === "object" && value !== null && value[INPUT_REF_BRAND] === true;
 }
-function wholeKeysSentinel() {
-  return { [KEY_REF_BRAND]: true };
+var ENTITY_REF_RE = /^\$\.entity\[(\d+)\]\.([A-Za-z_$][\w$]*)$/;
+var ENTITY_REF_PREFIX_RE = /^\s*\$\s*\.\s*entity\b/;
+var ENTITY_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:mutationEntityRef");
+function parseEntityRef(leaf) {
+  if (typeof leaf !== "string") return void 0;
+  const match = ENTITY_REF_RE.exec(leaf);
+  if (match === null) {
+    if (ENTITY_REF_PREFIX_RE.test(leaf)) {
+      throw new Error(
+        `mutation: the input value ${JSON.stringify(leaf)} looks like a cross-fragment reference but is malformed. The only supported form is \`$.entity[<index>].<field>\` (e.g. \`$.entity[0].postId\`) \u2014 a single dotted field on a 0-based, non-negative fragment index. Fix the path or, if you meant a literal string, it must not begin with \`$.entity\`.`
+      );
+    }
+    return void 0;
+  }
+  return {
+    [ENTITY_REF_BRAND]: true,
+    fragmentIndex: Number(match[1]),
+    field: match[2],
+    path: leaf
+  };
 }
-function isContractKeyFieldRef(value) {
-  return typeof value === "object" && value !== null && value[KEY_FIELD_REF_BRAND] === true;
+var ALIAS_FIELD_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:mutationAliasFieldRef");
+function isAliasFieldRef(value) {
+  return typeof value === "object" && value !== null && value[ALIAS_FIELD_REF_BRAND] === true;
 }
-function makeKeyFieldRef(field, marker, onCoerce) {
-  const token = `{key.${field}}`;
-  const origin = `keys field '${field}'`;
+function makeRootRef(root) {
+  const token = `{${root}}`;
+  const origin = `the placeholder '${root}' (\`$.${root}\`)`;
+  const aliasFieldCache = /* @__PURE__ */ new Map();
   const target = /* @__PURE__ */ Object.create(null);
   const proxy = new Proxy(target, {
     get(_t, prop) {
-      if (prop === KEY_FIELD_REF_BRAND) return true;
-      if (prop === "field") return field;
+      if (prop === INPUT_REF_BRAND) return true;
+      if (prop === "field") return root;
       if (prop === "token") return token;
-      if (prop === Symbol.toPrimitive) {
-        return (hint) => {
-          onCoerce();
-          return hint === "number" ? NaN : marker;
-        };
-      }
-      if (prop === "toString" || prop === Symbol.toStringTag) {
-        return () => {
-          onCoerce();
-          return marker;
-        };
+      if (typeof prop === "symbol") return void 0;
+      if (prop === "toString" || prop === "valueOf" || prop === "constructor") {
+        throw new Error(
+          `mutation: unsupported operation '${prop}' on ${origin}. A descriptor \`key\` / \`input\` value only supports a direct \`$.field\` input reference, a \`$.alias.field\` cross-fragment reference, or a concrete literal \u2014 never a transform or coercion.`
+        );
       }
-      if (prop === "valueOf") {
-        return () => {
-          onCoerce();
-          return NaN;
-        };
+      let ref = aliasFieldCache.get(prop);
+      if (!ref) {
+        ref = { [ALIAS_FIELD_REF_BRAND]: true, alias: root, field: prop };
+        aliasFieldCache.set(prop, ref);
       }
-      if (typeof prop === "symbol") return void 0;
-      const name = String(prop);
-      throw new Error(
-        `publicQueryModel/publicCommandModel: unsupported operation '${name}' on ${origin}. A contract method body only supports a *direct* key-field reference (\`keys.field\`) or the whole \`keys\` passed into a model op's key position; any transform, indexing, or coercion on a key field is not representable as a declarative contract method.`
-      );
+      return ref;
     },
     set() {
-      throw new Error(`publicQueryModel/publicCommandModel: cannot assign on ${origin}.`);
-    },
-    defineProperty() {
-      throw new Error(
-        `publicQueryModel/publicCommandModel: cannot define a property on ${origin}.`
-      );
-    },
-    deleteProperty() {
-      throw new Error(`publicQueryModel/publicCommandModel: cannot delete on ${origin}.`);
+      throw new Error(`mutation: cannot assign on ${origin}.`);
     }
   });
   return proxy;
 }
-function makeKeySentinel(pass, onFieldAccess, onCoerce) {
+function makeInputProxy() {
   const cache = /* @__PURE__ */ new Map();
-  const target = /* @__PURE__ */ Object.create(null);
-  const proxy = new Proxy(target, {
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
     get(_t, prop) {
-      if (prop === KEY_REF_BRAND) return true;
-      if (prop === Symbol.toPrimitive) {
-        return (hint) => {
-          onCoerce();
-          return hint === "number" ? NaN : "[contract key]";
-        };
-      }
-      if (prop === "toString" || prop === Symbol.toStringTag) {
-        return () => {
-          onCoerce();
-          return "[contract key]";
-        };
-      }
-      if (prop === "valueOf") {
-        return () => {
-          onCoerce();
-          return NaN;
-        };
-      }
-      if (prop === Symbol.iterator || prop === Symbol.asyncIterator || prop === "then" || prop === "constructor" || prop === "prototype" || typeof prop === "symbol" && typeof Symbol.for === "function" && (prop === /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom") || prop.description === "nodejs.util.inspect.custom")) {
-        return void 0;
-      }
-      if (typeof prop === "symbol") {
-        throw new Error(
-          "publicQueryModel/publicCommandModel: unsupported symbol access on `keys`."
-        );
-      }
-      onFieldAccess(prop);
-      let ref = cache.get(prop);
+      if (typeof prop === "symbol") return void 0;
+      const root = prop;
+      let ref = cache.get(root);
       if (!ref) {
-        ref = makeKeyFieldRef(prop, paramMarker(pass, `key.${prop}`), onCoerce);
-        cache.set(prop, ref);
+        ref = makeRootRef(root);
+        cache.set(root, ref);
       }
       return ref;
     },
     set() {
-      throw new Error("publicQueryModel/publicCommandModel: cannot assign to `keys`.");
-    },
-    defineProperty() {
-      throw new Error(
-        "publicQueryModel/publicCommandModel: cannot define a property on `keys`."
-      );
-    },
-    deleteProperty() {
-      throw new Error(
-        "publicQueryModel/publicCommandModel: cannot delete a field of `keys`."
-      );
+      throw new Error("mutation: cannot assign to the `$` placeholder proxy.");
     }
   });
-  return proxy;
 }
-var PARAM_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:contractParamRef");
-function isContractParamRef(value) {
-  return typeof value === "object" && value !== null && value[PARAM_REF_BRAND] === true;
+var FRAGMENT_BRAND = /* @__PURE__ */ Symbol("graphddb:mutationFragment");
+function isMutationFragment(value) {
+  return typeof value === "object" && value !== null && value[FRAGMENT_BRAND] === true;
 }
-function mintContractParamRef(field) {
-  return { [PARAM_REF_BRAND]: true, field, token: `{${field}}` };
+var INTENT_KEYS2 = ["create", "update", "remove"];
+function resolveDescriptorTarget(descriptor, alias) {
+  const present = INTENT_KEYS2.filter((k) => descriptor[k] !== void 0);
+  if (present.length === 0) {
+    throw new Error(
+      `mutation: the descriptor for alias '${alias}' has no intent key. Each descriptor must carry exactly one of \`create\` / \`update\` / \`remove\` whose value is the target model (or a \`() => Model\` thunk), e.g. \`{ create: GroupMembership, key, input }\`.`
+    );
+  }
+  if (present.length > 1) {
+    throw new Error(
+      `mutation: the descriptor for alias '${alias}' declares multiple intent keys (${present.join(", ")}). A descriptor is exactly one write \u2014 declare a single \`create\` / \`update\` / \`remove\`.`
+    );
+  }
+  const intent = present[0];
+  const ref = descriptor[intent];
+  const resolved = resolveModelRef(ref, intent, alias);
+  const modelClass = resolveModelClass(resolved);
+  return { intent, entity: { name: modelClass.name, modelClass } };
 }
-var PARAM_MARKER_TAGS = [
-  "Bxqv",
-  "Ymnoprstuwy0123456789WIDEMARKERBODYFILLERY"
-];
-var PARAM_PASS_COUNT = PARAM_MARKER_TAGS.length;
-function paramMarker(pass, field) {
-  const tag = PARAM_MARKER_TAGS[pass];
-  return `${tag}::${field}::${tag}`;
+function resolveModelRef(ref, intent, alias) {
+  if (ref === null || ref === void 0) {
+    throw new Error(
+      `mutation: the '${intent}' descriptor for alias '${alias}' names no target model.`
+    );
+  }
+  if (typeof ref === "function") {
+    const proto = ref.prototype;
+    const isModelClass = proto instanceof DDBModel || typeof ref === "function" && ref.prototype instanceof DDBModel;
+    if (isModelClass) {
+      return ref;
+    }
+    return ref();
+  }
+  return ref;
 }
-function makeParamFieldRef(field, marker, onCoerce) {
-  const token = `{${field}}`;
-  const origin = `params field '${field}'`;
-  const target = /* @__PURE__ */ Object.create(null);
-  const proxy = new Proxy(target, {
-    get(_t, prop) {
-      if (prop === PARAM_REF_BRAND) return true;
-      if (prop === "token") return token;
-      if (prop === "field") return field;
-      if (prop === Symbol.toPrimitive) {
-        return (hint) => {
-          onCoerce();
-          return hint === "number" ? NaN : marker;
-        };
-      }
-      if (prop === "toString" || prop === Symbol.toStringTag) {
-        return () => {
-          onCoerce();
-          return marker;
-        };
-      }
-      if (prop === "valueOf") {
-        return () => {
-          onCoerce();
-          return NaN;
-        };
-      }
-      if (typeof prop === "symbol") return void 0;
-      const name = String(prop);
-      throw new Error(
-        `publicQueryModel/publicCommandModel: unsupported operation '${name}' on ${origin}. A contract method body only supports a *direct* field reference (\`params.field\`) or a concrete literal at a value position; any string transform, property access (e.g. \`.length\`, \`[i]\`, \`.toUpperCase()\`), arithmetic, or value branching on a parameter is not representable as a declarative contract method.`
-      );
-    },
-    set() {
-      throw new Error(
-        `publicQueryModel/publicCommandModel: cannot assign on ${origin}.`
-      );
-    },
-    defineProperty() {
+function assertFaithfulInput(input, intent, entityName) {
+  if (input === null || typeof input !== "object") {
+    throw new Error(
+      `mutation: the '${intent}' fragment on '${entityName}' must declare an \`input\` object binding model fields to \`$.field\` references or literals.`
+    );
+  }
+  for (const [field, leaf] of Object.entries(input)) {
+    if (!isMutationInputRef(leaf) && !isAliasFieldRef(leaf) && !isConcreteLiteral(leaf)) {
       throw new Error(
-        `publicQueryModel/publicCommandModel: cannot define a property on ${origin}.`
+        `mutation: the '${intent}' fragment on '${entityName}' binds model field '${field}' to a value that is neither a \`$.field\` input reference, a \`$.alias.field\` cross-fragment reference, nor a concrete literal. A fragment input is declarative \u2014 only \`$.field\` / \`$.alias.field\` references or literals are allowed, never a computed value.`
       );
-    },
-    deleteProperty() {
+    }
+  }
+  return input;
+}
+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) {
+  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.`
+    );
+  }
+  return {
+    [FRAGMENT_BRAND]: true,
+    intent,
+    entity,
+    input: checked,
+    ...use !== void 0 ? { use } : {}
+  };
+}
+var COMMAND_PLAN_BRAND = /* @__PURE__ */ Symbol("graphddb:commandPlan");
+function isCommandPlan(value) {
+  return typeof value === "object" && value !== null && value[COMMAND_PLAN_BRAND] === true;
+}
+function mergeBindings(descriptor, intent, alias) {
+  const merged = {};
+  const key = descriptor.key;
+  if (key === void 0 || key === null || typeof key !== "object") {
+    throw new Error(
+      `mutation: the '${intent}' descriptor for alias '${alias}' must declare a \`key\` object binding the target's primary-key fields (\`{ field: $.field, \u2026 }\`).`
+    );
+  }
+  for (const [field, leaf] of Object.entries(key)) merged[field] = leaf;
+  const input = descriptor.input;
+  if (input !== void 0 && input !== null) {
+    if (typeof input !== "object") {
       throw new Error(
-        `publicQueryModel/publicCommandModel: cannot delete on ${origin}.`
+        `mutation: the '${intent}' descriptor for alias '${alias}' has a non-object \`input\`.`
       );
     }
-  });
-  return proxy;
-}
-function makeParamsProxy(pass, onAccess, onCoerce) {
-  const cache = /* @__PURE__ */ new Map();
-  return new Proxy(/* @__PURE__ */ Object.create(null), {
-    get(_t, prop) {
-      if (typeof prop === "symbol") {
-        if (prop === Symbol.iterator || prop === Symbol.asyncIterator || prop === Symbol.toStringTag || typeof Symbol.for === "function" && (prop === /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom") || prop.description === "nodejs.util.inspect.custom")) {
-          return void 0;
-        }
+    for (const [field, leaf] of Object.entries(input)) {
+      if (field in merged) {
         throw new Error(
-          "publicQueryModel/publicCommandModel: unsupported symbol access on `params`. Reference only declared param fields directly; any JS transform / branching / coercion on a parameter is not representable as a declarative contract method."
+          `mutation: the '${intent}' descriptor for alias '${alias}' binds field '${field}' in both \`key\` and \`input\`. A primary-key field belongs in \`key\` only.`
         );
       }
-      onAccess(prop);
-      let ref = cache.get(prop);
-      if (!ref) {
-        ref = makeParamFieldRef(prop, paramMarker(pass, prop), () => onCoerce(prop));
-        cache.set(prop, ref);
+      merged[field] = leaf;
+    }
+  }
+  return merged;
+}
+function resolveAliasRefs(input, aliasToIndex, alias) {
+  const out = {};
+  for (const [field, leaf] of Object.entries(input)) {
+    if (isAliasFieldRef(leaf)) {
+      const index = aliasToIndex.get(leaf.alias);
+      if (index === void 0) {
+        throw new Error(
+          `mutation: the descriptor for alias '${alias}' binds '${field}' to \`$.${leaf.alias}.${leaf.field}\`, but no descriptor is aliased '${leaf.alias}'. A cross-fragment reference must name another alias in the same mutation map.`
+        );
       }
-      return ref;
-    },
-    set() {
-      throw new Error(
-        "publicQueryModel/publicCommandModel: cannot assign to a field of `params`."
-      );
-    },
-    defineProperty() {
-      throw new Error(
-        "publicQueryModel/publicCommandModel: cannot define a property on `params`."
-      );
-    },
-    deleteProperty() {
+      out[field] = `$.entity[${index}].${leaf.field}`;
+    } else {
+      out[field] = leaf;
+    }
+  }
+  return out;
+}
+function mutation(nameOrBody, maybeBody) {
+  let name;
+  let body;
+  if (typeof nameOrBody === "string") {
+    if (maybeBody === void 0) {
+      throw new Error("mutation: a name was given but no body function.");
+    }
+    name = nameOrBody;
+    body = maybeBody;
+  } else {
+    body = nameOrBody;
+    name = "mutation";
+  }
+  if (typeof body !== "function") {
+    throw new Error(
+      "mutation: the body must be a function `$ => ({ alias: descriptor, \u2026 })` returning an alias \u2192 write-descriptor map."
+    );
+  }
+  const $ = makeInputProxy();
+  const map = body($);
+  if (map === null || typeof map !== "object" || Array.isArray(map)) {
+    throw new Error(
+      `mutation '${name}': the body must RETURN an alias \u2192 descriptor object (e.g. \`$ => ({ membership: { create: Model, key, input } })\`). Note the \`({ \u2026 })\` parentheses \u2014 an arrow returning an object literal needs them.`
+    );
+  }
+  const aliases = Object.keys(map);
+  if (aliases.length === 0) {
+    throw new Error(
+      `mutation '${name}': the body returned an empty descriptor map. A mutation must declare at least one write descriptor.`
+    );
+  }
+  const aliasToIndex = /* @__PURE__ */ new Map();
+  aliases.forEach((alias, i) => aliasToIndex.set(alias, i));
+  const fragments = aliases.map((alias) => {
+    const descriptor = map[alias];
+    if (descriptor === null || typeof descriptor !== "object") {
       throw new Error(
-        "publicQueryModel/publicCommandModel: cannot delete a field of `params`."
+        `mutation '${name}': the value for alias '${alias}' is not a write descriptor (an object \`{ create | update | remove: Model, key, input? }\`).`
       );
     }
+    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 { [COMMAND_PLAN_BRAND]: true, name, fragments };
+}
+var definePlan = mutation;
+
+// src/define/contract.ts
+var KEY_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:contractKeyRef");
+var KEY_FIELD_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:contractKeyFieldRef");
+function isContractKeyRef(value) {
+  return typeof value === "object" && value !== null && value[KEY_REF_BRAND] === true;
+}
+function mintContractKeyFieldRef(field) {
+  return { [KEY_FIELD_REF_BRAND]: true, field, token: `{key.${field}}` };
+}
+function wholeKeysSentinel() {
+  return { [KEY_REF_BRAND]: true };
+}
+function isContractKeyFieldRef(value) {
+  return typeof value === "object" && value !== null && value[KEY_FIELD_REF_BRAND] === true;
+}
+var PARAM_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:contractParamRef");
+function isContractParamRef(value) {
+  return typeof value === "object" && value !== null && value[PARAM_REF_BRAND] === true;
+}
+function mintContractParamRef(field) {
+  return { [PARAM_REF_BRAND]: true, field, token: `{${field}}` };
 }
 var FROM_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:contractFromRef");
 var COMPOSE_NODE_BRAND = /* @__PURE__ */ Symbol("graphddb:contractComposeNode");
@@ -925,69 +3004,10 @@ function entityRef(model) {
   const modelClass = resolveModelClass(model);
   return { name: modelClass.name, modelClass };
 }
-var PUT_HAS_NO_KEY = { [KEY_REF_BRAND]: true };
-function assertFaithfulKeys(keys, op) {
-  if (isContractKeyRef(keys)) return keys;
-  if (keys !== null && typeof keys === "object" && !isContractKeyFieldRef(keys)) {
-    const record = keys;
-    for (const [field, leaf] of Object.entries(record)) {
-      if (!isContractKeyFieldRef(leaf) && !isConcreteLiteral2(leaf)) {
-        throw new Error(
-          `publicQueryModel/publicCommandModel: the \`${op}\` operation's key field '${field}' is neither a direct \`keys.${field}\` reference nor a concrete literal. A rebuilt partition key may only place \`keys.<field>\` references or literals at its leaves; a transformed value is not representable as a declarative contract method.`
-        );
-      }
-    }
-    return record;
-  }
-  throw new Error(
-    `publicQueryModel/publicCommandModel: the \`${op}\` operation must receive the method's \`keys\` argument *directly* in its key position, or a partition key rebuilt from \`keys.<field>\` references. The value passed is not a valid contract key \u2014 it was transformed, coerced, or replaced, which is not representable as a declarative contract method.`
-  );
-}
 function isConcreteLiteral2(value) {
   const t = typeof value;
   return value === null || value instanceof Date || t === "string" || t === "number" || t === "boolean";
 }
-var activeSink = null;
-function recordContractOp(operation, model, args) {
-  const entity = entityRef(model);
-  let keys;
-  if (operation === "put") {
-    keys = PUT_HAS_NO_KEY;
-  } else {
-    keys = assertFaithfulKeys(args.keys, operation);
-  }
-  const { select, compose } = extractCompose(args.select, operation, entity.name);
-  const batch = args.batch === void 0 || args.batch === null ? void 0 : args.batch;
-  const op = {
-    __isContractMethodOp: true,
-    entity,
-    operation,
-    keys,
-    ...select !== void 0 ? { select } : {},
-    ...args.changes !== void 0 ? { changes: args.changes } : {},
-    ...args.item !== void 0 ? { item: args.item } : {},
-    ...args.condition !== void 0 ? { condition: args.condition } : {},
-    // Captured raw (cast through the field type); validated in the factory.
-    ...batch !== void 0 ? { batch } : {},
-    ...compose.length > 0 ? { compose } : {}
-  };
-  activeSink.push(op);
-  return op;
-}
-function assertBatchModeDeclaration(name, op) {
-  const batch = op.batch;
-  if (batch === void 0) return;
-  if (!isCommandBatchMode(batch)) {
-    throw new Error(
-      `publicCommandModel: method '${name}' declared an invalid \`batch\` mode \u2014 \`batch\` must be 'transact' (atomic TransactWriteItems, \u226425, condition-capable) or 'batchWrite' (non-atomic BatchWriteItem, no conditions), but received ${JSON.stringify(batch)}.`
-    );
-  }
-  if (batch === "batchWrite" && op.condition !== void 0) {
-    throw new Error(
-      `publicCommandModel: method '${name}' declares a 'batchWrite' batch mode but also a write condition \u2014 DynamoDB's BatchWriteItem has no ConditionExpression and cannot carry one. Declare \`batch: 'transact'\` (an atomic TransactWriteItems, which supports the \`{ notExists }\` / equality condition subset) for a conditional batched write.`
-    );
-  }
-}
 function extractCompose(select, operation, entityName) {
   if (select === void 0) return { select: void 0, compose: [] };
   const projection = {};
@@ -1006,225 +3026,6 @@ function extractCompose(select, operation, entityName) {
   }
   return { select: projection, compose };
 }
-function isRecordingContractMethod() {
-  return activeSink !== null;
-}
-function runMethodPass(body, pass, accessed, coerced, keyCoerced) {
-  const keys = makeKeySentinel(
-    pass,
-    () => {
-    },
-    () => {
-      keyCoerced.value = true;
-    }
-  );
-  const params = makeParamsProxy(
-    pass,
-    (field) => accessed.add(field),
-    (field) => coerced.add(field)
-  );
-  const sink = [];
-  const previous = activeSink;
-  activeSink = sink;
-  try {
-    body(keys, params);
-  } finally {
-    activeSink = previous;
-  }
-  if (sink.length === 0) {
-    throw new Error(
-      "publicQueryModel/publicCommandModel: a method body must resolve to exactly one model operation (e.g. `return Model.query(keys, select, params)`). No model operation was recorded \u2014 the body did not call `Model.query` / `Model.list` / `Model.put` / `Model.update` / `Model.delete`."
-    );
-  }
-  if (sink.length > 1) {
-    throw new Error(
-      `publicQueryModel/publicCommandModel: a method body must resolve to exactly one model operation, but it recorded ${sink.length}. A contract method is a single declarative operation; multiple writes belong in a transaction (defineTransaction), and branching across operations is not representable as a declarative contract method.`
-    );
-  }
-  return sink[0];
-}
-function verifyOps(a, b, surfaced) {
-  if (a.operation !== b.operation) {
-    throw new Error(
-      "publicQueryModel/publicCommandModel: the method body is not deterministic (it resolved to different operations across evaluation passes). A contract method must be a pure, declarative description of a single operation."
-    );
-  }
-  if (a.entity.name !== b.entity.name) {
-    throw new Error(
-      "publicQueryModel/publicCommandModel: the method body targeted different models across evaluation passes; it must be a pure, declarative description."
-    );
-  }
-  verifyKeySlot(a.keys, b.keys, `${a.operation} key`);
-  verifyRecord(a.select, b.select, surfaced, `${a.operation} select`);
-  verifyRecord(a.changes, b.changes, surfaced, `${a.operation} changes`);
-  verifyRecord(a.item, b.item, surfaced, `${a.operation} item`);
-  verifyRecord(
-    a.condition,
-    b.condition,
-    surfaced,
-    `${a.operation} condition`
-  );
-  verifyCompose(a.compose, b.compose, `${a.operation} compose`);
-  if (a.batch !== b.batch) {
-    throw new Error(
-      `publicCommandModel: the method body declared a different \`batch\` mode across evaluation passes ('${String(a.batch)}' vs '${String(b.batch)}'); the batched-write mode must be a fixed literal declaration.`
-    );
-  }
-}
-function verifyCompose(a, b, context) {
-  const ca = a ?? [];
-  const cb = b ?? [];
-  const byAsA = new Map(ca.map((c) => [c.as, c]));
-  const byAsB = new Map(cb.map((c) => [c.as, c]));
-  if (byAsA.size !== ca.length || byAsB.size !== cb.length) {
-    throw new Error(
-      `publicQueryModel: ${context} declares two compositions at the same select property; each \`query(...)\` must attach to a distinct property.`
-    );
-  }
-  const keysA = [...byAsA.keys()].sort();
-  const keysB = [...byAsB.keys()].sort();
-  if (keysA.length !== keysB.length || keysA.some((x, i) => x !== keysB[i])) {
-    throw new Error(
-      `publicQueryModel: ${context} property set diverged between evaluation passes; the method body must declare a fixed set of compositions.`
-    );
-  }
-  for (const as of keysA) {
-    const na = byAsA.get(as);
-    const nb = byAsB.get(as);
-    if (na.method !== nb.method) {
-      throw new Error(
-        `publicQueryModel: ${context} '${as}' references a different contract method across evaluation passes; a composition must point at a single, stable contract method.`
-      );
-    }
-    const fieldsA = Object.keys(na.bind).sort();
-    const fieldsB = Object.keys(nb.bind).sort();
-    if (fieldsA.length !== fieldsB.length || fieldsA.some((x, i) => x !== fieldsB[i])) {
-      throw new Error(
-        `publicQueryModel: ${context} '${as}' binds a different set of child key fields across evaluation passes; the binding must be a fixed declarative map.`
-      );
-    }
-    for (const field of fieldsA) {
-      if (na.bind[field].path !== nb.bind[field].path) {
-        throw new Error(
-          `publicQueryModel: ${context} '${as}' binding '${field}' resolves to a different \`from\` path across evaluation passes; the binding must be a literal declarative path.`
-        );
-      }
-    }
-  }
-}
-function verifyKeySlot(a, b, context) {
-  const wholeA = isContractKeyRef(a);
-  const wholeB = isContractKeyRef(b);
-  if (wholeA && wholeB) return;
-  if (wholeA !== wholeB) {
-    throw new Error(
-      `publicQueryModel/publicCommandModel: ${context} is the whole \`keys\` in one evaluation pass but a rebuilt key in the other; the method body must be a pure, declarative description.`
-    );
-  }
-  verifyRecord(
-    a,
-    b,
-    /* @__PURE__ */ new Set(),
-    context
-  );
-}
-function verifyRecord(a, b, surfaced, context) {
-  if (a === void 0 && b === void 0) return;
-  if (a === void 0 || b === void 0) {
-    throw new Error(
-      `publicQueryModel/publicCommandModel: ${context} present in one evaluation pass but not the other; the method body must be a pure, declarative description.`
-    );
-  }
-  const ka = Object.keys(a).sort();
-  const kb = Object.keys(b).sort();
-  if (ka.length !== kb.length || ka.some((x, i) => x !== kb[i])) {
-    throw new Error(
-      `publicQueryModel/publicCommandModel: ${context} field set diverged between evaluation passes; the method body must be a pure, declarative description.`
-    );
-  }
-  for (const field of ka) {
-    verifyLeaf(a[field], b[field], surfaced, `${context} field '${field}'`);
-  }
-}
-function refTokenOf(value) {
-  if (isContractParamRef(value)) return value.token;
-  if (isContractKeyFieldRef(value)) return value.token;
-  return void 0;
-}
-function verifyLeaf(va, vb, surfaced, context) {
-  const ra = refTokenOf(va);
-  const rb = refTokenOf(vb);
-  if (ra !== void 0 || rb !== void 0) {
-    if (ra === void 0 || rb === void 0) {
-      throw new Error(
-        `publicQueryModel/publicCommandModel: ${context} is a field reference in one evaluation pass but a transformed value in the other \u2014 a coercion / transform escape was applied. Use a direct \`params.field\` / \`keys.field\` reference or a concrete literal.`
-      );
-    }
-    if (ra !== rb) {
-      throw new Error(
-        `publicQueryModel/publicCommandModel: ${context} resolves to different field references across evaluation passes \u2014 the value is not a stable, declarative reference.`
-      );
-    }
-    if (isContractParamRef(va)) surfaced.add(ra);
-    return;
-  }
-  const na = normalizeLiteral(va);
-  const nb = normalizeLiteral(vb);
-  if (na !== nb) {
-    throw new Error(
-      `publicQueryModel/publicCommandModel: ${context} is not a stable concrete literal \u2014 evaluating the method body twice produced different values ('${na}' vs '${nb}'). A parameter was coerced or transformed into the value (e.g. \`String(params.x).toUpperCase()\`, \`\${params.x}-suffix\`, or arithmetic). Only a direct field reference or a concrete literal is allowed at a value position.`
-    );
-  }
-}
-function normalizeLiteral(value) {
-  if (value === null) return "t:null";
-  if (value === void 0) return "t:undef";
-  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(
-        "publicQueryModel/publicCommandModel: 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(
-    `publicQueryModel/publicCommandModel: a value leaf has unsupported type '${t}'. Only a direct \`params.field\` reference or a concrete literal (string / number / boolean / Date) is allowed at a value position.`
-  );
-}
-function resolveMethodOp(name, body) {
-  const accessed = /* @__PURE__ */ new Set();
-  const coerced = /* @__PURE__ */ new Set();
-  const keyCoerced = { value: false };
-  const ops = [];
-  for (let pass = 0; pass < PARAM_PASS_COUNT; pass++) {
-    ops.push(runMethodPass(body, pass, accessed, coerced, keyCoerced));
-  }
-  if (keyCoerced.value) {
-    throw new Error(
-      `publicQueryModel/publicCommandModel: method '${name}' coerces its \`keys\` argument to a primitive (e.g. via \`\${keys}\`, \`String(keys)\`, string concatenation, or a comparison). \`keys\` may only be passed *directly* into a model operation's key position; coercing or transforming it is not representable as a declarative contract method.`
-    );
-  }
-  if (coerced.size > 0) {
-    const field = [...coerced][0];
-    throw new Error(
-      `publicQueryModel/publicCommandModel: method '${name}' coerces params field '${field}' to a primitive (e.g. via \`String(params.${field})\`, a template literal \`\${\u2026}\`, string concatenation, or a comparison) and then consumes it in a transform or branch \u2014 for example \`String(params.${field}).slice(0, n)\` or \`\${params.${field}}-suffix\`. A contract method only supports a *direct* field reference or a concrete literal at a value position; a coerced / transformed parameter is not representable as a declarative contract method.`
-    );
-  }
-  const surfaced = /* @__PURE__ */ new Set();
-  verifyOps(ops[0], ops[1], surfaced);
-  for (const field of accessed) {
-    if (!surfaced.has(`{${field}}`)) {
-      throw new Error(
-        `publicQueryModel/publicCommandModel: method '${name}' accesses params field '${field}' but it never appears as a field reference in the recorded operation. This happens when a parameter is consumed by a value branch (e.g. \`params.${field} === 'x' ? \u2026 : \u2026\`) or a string transform instead of being referenced directly. A contract method only supports direct \`params.field\` references or concrete literals at value positions.`
-      );
-    }
-  }
-  return ops[0];
-}
 function deriveReadFacts(op) {
   if (op.operation === "list") {
     return { resolution: "range", inputArity: "single" };
@@ -1247,103 +3048,32 @@ function deriveReadFacts(op) {
   }
   return { resolution: "point", inputArity: "either" };
 }
-function assertDeclaredArity(name, declared, resolution, derived) {
-  if (declared === void 0) return;
-  if (declared === derived) return;
-  const hint = resolution === "range" ? `it resolved to a 'range' read (a partition \`Query\`), whose arity is always 'single' \u2014 use \`range(body)\`, not \`point(...)\`.` : derived === "single" ? `it resolved to a non-coalescible unique-GSI 'point' read (a per-key GSI \`Query\`; \`BatchGetItem\` cannot read a GSI), whose arity is 'single' \u2014 use \`point(body, { coalesce: false })\`.` : `it resolved to a coalescible base-table 'point' read (a key array \u2192 one \`BatchGetItem\`), whose arity is 'either' \u2014 use \`point(body)\` (\`coalesce\` defaults to \`true\`).`;
-  throw new Error(
-    `publicQueryModel: method '${name}' declared input arity '${declared}', but ${hint} The declared arity is threaded into the type-level call surface, so it must match the resolved access pattern.`
-  );
-}
-var ARITY_TAG = "__contractArity";
-function tagArity(arity, body) {
-  if (typeof body !== "function") {
-    throw new Error(
-      `publicQueryModel: point()/range() must wrap a method body function (\`(keys, params) => Model.query(...) | Model.list(...)\`), received ${body === null ? "null" : typeof body}.`
-    );
-  }
-  Object.defineProperty(body, ARITY_TAG, { value: arity, enumerable: false });
-  return body;
-}
-function declaredArityOf(body) {
-  if (typeof body !== "function" && typeof body !== "object") return void 0;
-  if (body === null) return void 0;
-  const tag = body[ARITY_TAG];
-  return tag === "single" || tag === "either" || tag === "array" ? tag : void 0;
-}
-function point(body, options) {
-  const arity = options?.coalesce === false ? "single" : "either";
-  return tagArity(arity, body);
-}
-function range(body) {
-  return tagArity("single", body);
-}
 function isQueryModelContract(value) {
   return typeof value === "object" && value !== null && value.__isContract === true && value.kind === "query";
 }
 function isCommandModelContract(value) {
   return typeof value === "object" && value !== null && value.__isContract === true && value.kind === "command";
 }
-function publicQueryModel(modelOrKeyFields, maybeKeyFields) {
-  const { keyFields } = normalizeFactoryArgs("publicQueryModel", modelOrKeyFields, maybeKeyFields);
-  return (methods) => buildQueryContract(methods, keyFields);
-}
-function normalizeFactoryArgs(factory, modelOrKeyFields, maybeKeyFields) {
-  let model;
-  let keyFields;
-  if (Array.isArray(modelOrKeyFields)) {
-    keyFields = modelOrKeyFields;
-  } else if (modelOrKeyFields !== void 0) {
-    model = modelOrKeyFields;
-    keyFields = maybeKeyFields;
-  }
-  if (model !== void 0) resolveModelClass(model);
-  if (keyFields !== void 0) assertKeyFieldList(factory, keyFields);
-  return { keyFields };
-}
-function assertKeyFieldList(factory, keyFields) {
-  if (keyFields.length === 0) {
-    throw new Error(
-      `${factory}: the explicit Key-field list is empty. Supply at least one Key field (e.g. \`['email']\`), or omit the list to default to the model's primary key.`
-    );
-  }
-  const seen = /* @__PURE__ */ new Set();
-  for (const field of keyFields) {
-    if (typeof field !== "string" || field.length === 0) {
-      throw new Error(
-        `${factory}: an explicit Key field must be a non-empty string, but the list ${JSON.stringify(keyFields)} contains ${JSON.stringify(field)}.`
-      );
-    }
-    if (seen.has(field)) {
-      throw new Error(
-        `${factory}: the explicit Key-field list ${JSON.stringify(keyFields)} repeats the field '${field}'; each Key field must appear once.`
-      );
-    }
-    seen.add(field);
-  }
-}
-function withKeyFields(op, keyFields) {
-  if (keyFields === void 0) return op;
-  if (op.operation === "put") return op;
-  if (!isContractKeyRef(op.keys)) return op;
-  return { ...op, keyFields };
+function publicQueryModel(methods) {
+  return buildQueryContract(methods);
 }
-function buildQueryContract(methods, keyFields) {
+function buildQueryContract(methods) {
   const resolved = {};
   for (const [name, body] of Object.entries(methods)) {
-    if (typeof body !== "function") {
+    let op;
+    if (isPublicReadDescriptor(body)) {
+      op = readDescriptorToOp(name, body);
+    } else {
       throw new Error(
-        `publicQueryModel: method '${name}' must be a function (keys, params) => Model.query(...) | Model.list(...).`
+        `publicQueryModel: method '${name}' must be a read descriptor (\`{ query | list: Model, key, select, options? }\`). The legacy (keys, params) => Model.query(...) | Model.list(...) closure form has been removed (#101).`
       );
     }
-    const op = withKeyFields(resolveMethodOp(name, body), keyFields);
     if (op.operation !== "query" && op.operation !== "list") {
       throw new Error(
         `publicQueryModel: method '${name}' resolves to a '${op.operation}' (write) operation; a query model may only resolve to a read (\`Model.query\` / \`Model.list\`). Use publicCommandModel for writes.`
       );
     }
     const { resolution, inputArity } = deriveReadFacts(op);
-    assertDeclaredArity(name, declaredArityOf(body), resolution, inputArity);
     resolved[name] = {
       __methodKind: "query",
       op,
@@ -1356,115 +3086,61 @@ function buildQueryContract(methods, keyFields) {
   for (const spec of Object.values(resolved)) methodSpecToContract.set(spec, contract);
   return contract;
 }
-function publicCommandModel(modelOrKeyFields, maybeKeyFields) {
-  const { keyFields } = normalizeFactoryArgs("publicCommandModel", modelOrKeyFields, maybeKeyFields);
-  return (methods) => buildCommandContract(methods, keyFields);
+function publicCommandModel(methods) {
+  return buildCommandContract(methods);
 }
-function buildCommandContract(methods, keyFields) {
+function buildCommandContract(methods) {
   const resolved = {};
   for (const [name, body] of Object.entries(methods)) {
-    if (isPlannedCommandMethod(body)) {
-      resolved[name] = buildPlannedCommandMethod(name, body, keyFields);
+    if (isPublicWriteDescriptor(body)) {
+      const { plan: plan2, select, condition, mode } = writeDescriptorToPlan(name, body);
+      resolved[name] = finalizeDescriptorCommand(name, plan2, select, condition, mode);
       continue;
     }
-    if (typeof body !== "function") {
-      throw new Error(
-        `publicCommandModel: method '${name}' must be a function (keys, params) => Model.put(...) | Model.update(...) | Model.delete(...), or a \`command({ input, select }).plan(mutation)\` planned method (#83).`
+    if (isPublicComposeDescriptor(body)) {
+      const select = body.result !== void 0 && body.result.select !== void 0 ? body.result.select : void 0;
+      resolved[name] = finalizeDescriptorCommand(
+        name,
+        body.command,
+        select,
+        void 0,
+        body.mode ?? "transaction"
       );
+      continue;
     }
-    const op = withKeyFields(resolveMethodOp(name, body), keyFields);
-    if (op.operation !== "put" && op.operation !== "update" && op.operation !== "delete") {
-      throw new Error(
-        `publicCommandModel: method '${name}' resolves to a '${op.operation}' (read) operation; a command model may only resolve to a write (\`Model.put\` / \`Model.update\` / \`Model.delete\`). Use publicQueryModel for reads.`
+    if (isCommandPlan(body)) {
+      resolved[name] = finalizeDescriptorCommand(
+        name,
+        body,
+        void 0,
+        void 0,
+        "transaction"
       );
+      continue;
     }
-    assertBatchModeDeclaration(name, op);
-    resolved[name] = {
-      __methodKind: "command",
-      op,
-      // A single key → one write op; a key array → a batched write. Both forms
-      // are point writes against known keys, so the accepted arity is 'either'.
-      inputArity: "either",
-      result: commandResultOf(op),
-      ...op.batch !== void 0 ? { batch: op.batch } : {}
-    };
+    throw new Error(
+      `publicCommandModel: method '${name}' must be a write descriptor (\`{ create | update | remove: Model, key, input?, condition?, result?, mode? }\`), a composite \`{ command: mutation(...), input?, result?, mode? }\` descriptor, or a bare \`mutation($ => ({ \u2026 }))\` plan. The legacy closure form (\`(keys, params) => Model.putItem(...)\`) and the \`command(...).plan(...)\` builder have been removed (#101).`
+    );
   }
   return { __isContract: true, kind: "command", methods: resolved };
 }
-function commandResultOf(op) {
-  return op.operation === "update" ? "entity" : "void";
-}
 var PLANNED_COMMAND_BRAND = /* @__PURE__ */ Symbol("graphddb:plannedCommandMethod");
 function isPlannedCommandMethod(value) {
-  return typeof value === "object" && value !== null && value[PLANNED_COMMAND_BRAND] === true;
-}
-function command(spec) {
-  const input = spec.input;
-  if (typeof input !== "object" || input === null) {
-    throw new Error(
-      "command({ input, select }): `input` must be a record of `param.*` placeholders (e.g. `{ userId: param.string(), title: param.string() }`)."
-    );
-  }
-  for (const [field, p] of Object.entries(input)) {
-    if (!isParam(p)) {
-      throw new Error(
-        `command({ input }): input field '${field}' must be a \`param.*\` placeholder (e.g. \`param.string()\`), not ${JSON.stringify(p)}.`
-      );
-    }
-  }
-  const select = spec.select;
-  if (select !== void 0) {
-    if (typeof select !== "object" || select === null) {
-      throw new Error(
-        "command({ select }): `select` must be a boolean field map (e.g. `{ postId: true, title: true }`), or omitted for no return projection."
-      );
-    }
-    for (const [field, flag] of Object.entries(select)) {
-      if (typeof flag !== "boolean") {
-        throw new Error(
-          `command({ select }): return projection field '${field}' must be a boolean flag (\`true\` / \`false\`), not ${JSON.stringify(flag)}.`
-        );
-      }
-    }
-  }
-  return {
-    plan(plan) {
-      if (!isCommandPlan(plan)) {
-        throw new Error(
-          "command(...).plan(...): expected a `mutation(...)` / `definePlan(...)` CommandPlan (the internal write-plan composition), but received a non-plan value."
-        );
-      }
-      return {
-        [PLANNED_COMMAND_BRAND]: true,
-        plan,
-        input,
-        select
-      };
-    }
-  };
-}
-function buildPlannedCommandMethod(name, planned, keyFields) {
-  const plan = compileMutationPlan(planned.plan);
-  const primary = plan.fragments[0];
-  if (keyFields !== void 0) {
-    const want = [...keyFields].sort().join(",");
-    const got = [...primary.keyFields].sort().join(",");
-    if (want !== got) {
-      throw new Error(
-        `publicCommandModel: planned method '${name}' writes '${primary.op.entity.name}' keyed by its primary key [${primary.keyFields.join(", ")}], but the factory was given an explicit Key-field list [${keyFields.join(", ")}]. A mutation-derived command is keyed by the written entity's primary key; omit the explicit list or match it.`
-      );
-    }
-  }
+  return typeof value === "object" && value !== null && value[PLANNED_COMMAND_BRAND] === true;
+}
+function buildPlannedCommandMethod(name, planned) {
+  const plan2 = compileMutationPlan(planned.plan);
+  const primary = plan2.fragments[0];
   const stamp = (fragment) => fragment.op.operation === "put" ? fragment.op : { ...fragment.op, keyFields: fragment.keyFields };
   const op = stamp(primary);
   const returnSelection = normalizeReturnSelection(planned.select);
-  const ops = plan.fragments.length > 1 ? plan.fragments.map(stamp) : void 0;
-  const conditionChecks = plan.fragments.flatMap((f) => f.conditionChecks ?? []);
-  const edgeWrites2 = plan.fragments.flatMap((f) => f.edgeWrites ?? []);
-  const derivedUpdates = plan.fragments.flatMap((f) => f.derivedUpdates ?? []);
-  const uniqueGuards = plan.fragments.flatMap((f) => f.uniqueGuards ?? []);
-  const outboxEvents = plan.fragments.flatMap((f) => f.outboxEvents ?? []);
-  const idempotencyGuards = plan.fragments.map((f) => f.idempotencyGuard).filter((g) => g !== void 0);
+  const ops = plan2.fragments.length > 1 ? plan2.fragments.map(stamp) : void 0;
+  const conditionChecks = plan2.fragments.flatMap((f) => f.conditionChecks ?? []);
+  const edgeWrites2 = plan2.fragments.flatMap((f) => f.edgeWrites ?? []);
+  const derivedUpdates = plan2.fragments.flatMap((f) => f.derivedUpdates ?? []);
+  const uniqueGuards = plan2.fragments.flatMap((f) => f.uniqueGuards ?? []);
+  const outboxEvents = plan2.fragments.flatMap((f) => f.outboxEvents ?? []);
+  const idempotencyGuards = plan2.fragments.map((f) => f.idempotencyGuard).filter((g) => g !== void 0);
   if (idempotencyGuards.length > 1) {
     throw new Error(
       `publicCommandModel: planned method '${name}' declares an idempotency guard on more than one fragment. Idempotency is a single command-level client token (it keys the whole atomic write); declare \`w.idempotentBy(...)\` on at most one fragment's lifecycle.`
@@ -1488,6 +3164,21 @@ function buildPlannedCommandMethod(name, planned, keyFields) {
     ...returnSelection !== void 0 ? { returnSelection } : {}
   };
 }
+function finalizeDescriptorCommand(name, plan2, select, condition, mode) {
+  const planned = {
+    [PLANNED_COMMAND_BRAND]: true,
+    plan: plan2,
+    input: {},
+    select
+  };
+  const built = buildPlannedCommandMethod(name, planned);
+  const op = condition !== void 0 ? { ...built.op, condition } : built.op;
+  return {
+    ...built,
+    op,
+    mode
+  };
+}
 function normalizeReturnSelection(select) {
   if (select === void 0) return void 0;
   const out = {};
@@ -1496,6 +3187,117 @@ function normalizeReturnSelection(select) {
   }
   return Object.keys(out).length > 0 ? out : void 0;
 }
+var READ_INTENT_KEYS = ["query", "list"];
+var WRITE_INTENT_KEYS = ["create", "update", "remove"];
+function isPublicComposeDescriptor(value) {
+  return typeof value === "object" && value !== null && isCommandPlan(value.command);
+}
+function isPublicReadDescriptor(value) {
+  return typeof value === "object" && value !== null && READ_INTENT_KEYS.some((k) => value[k] !== void 0);
+}
+function isPublicWriteDescriptor(value) {
+  return typeof value === "object" && value !== null && WRITE_INTENT_KEYS.some((k) => value[k] !== void 0);
+}
+function resolveDescriptorModel(ref, name) {
+  if (ref === null || ref === void 0) {
+    throw new Error(`publicQueryModel/publicCommandModel: method '${name}' names no target model.`);
+  }
+  if (typeof ref === "function") {
+    const asModel = ref.asModel;
+    if (typeof asModel === "function") return asModel.call(ref);
+    return resolveDescriptorModel(ref(), name);
+  }
+  return ref;
+}
+function descriptorKeyRecord(record, name, what) {
+  const out = {};
+  for (const [field, leaf] of Object.entries(record)) {
+    if (isParam(leaf)) {
+      out[field] = mintContractKeyFieldRef(field);
+    } else if (isConcreteLiteral2(leaf)) {
+      out[field] = leaf;
+    } else {
+      throw new Error(
+        `publicQueryModel/publicCommandModel: method '${name}' ${what} field '${field}' must be a \`param.*\` placeholder or a concrete literal, not ${JSON.stringify(leaf)}.`
+      );
+    }
+  }
+  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 } : {}
+  };
+}
+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" };
+}
 
 // src/spec/mutation-command.ts
 var INTENT_OPERATION = {
@@ -1928,18 +3730,18 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null) {
     ...idempotencyGuard !== void 0 ? { idempotencyGuard } : {}
   };
 }
-function compileSingleFragmentPlan(plan) {
-  if (!isCommandPlan(plan)) {
+function compileSingleFragmentPlan(plan2) {
+  if (!isCommandPlan(plan2)) {
     throw new Error(
       "mutation compiler: expected a `mutation(...)` CommandPlan, but received a non-plan value."
     );
   }
-  if (plan.fragments.length !== 1) {
+  if (plan2.fragments.length !== 1) {
     throw new Error(
-      `mutation '${plan.name}': compileSingleFragmentPlan expects exactly one fragment, but the plan declares ${plan.fragments.length}. Use compileMutationPlan for the N-fragment atomic merge (issue #90).`
+      `mutation '${plan2.name}': compileSingleFragmentPlan expects exactly one fragment, but the plan declares ${plan2.fragments.length}. Use compileMutationPlan for the N-fragment atomic merge (issue #90).`
     );
   }
-  return compileFragment(plan.fragments[0], 0, null);
+  return compileFragment(plan2.fragments[0], 0, null);
 }
 var MAX_TRANSACT_COMPOSE_ITEMS = 25;
 function keySignature(fragment) {
@@ -1963,26 +3765,26 @@ function keyLeafToken(leaf) {
   if (isContractParamRef(leaf)) return `input:${leaf.field}`;
   return `literal:${JSON.stringify(leaf)}`;
 }
-function compileMutationPlan(plan) {
-  if (!isCommandPlan(plan)) {
+function compileMutationPlan(plan2) {
+  if (!isCommandPlan(plan2)) {
     throw new Error(
       "mutation compiler: expected a `mutation(...)` CommandPlan, but received a non-plan value."
     );
   }
-  const fragments = plan.fragments;
+  const fragments = plan2.fragments;
   const compiled = [];
   for (let i = 0; i < fragments.length; i++) {
     const resolveEntityRef = (ref, consumerIndex, consumerField) => {
       if (ref.fragmentIndex >= consumerIndex) {
         throw new Error(
-          `mutation '${plan.name}': fragment #${consumerIndex} binds '${consumerField}' to '${ref.path}', a CIRCULAR cross-fragment dependency \u2014 a fragment may only reference a value produced by an EARLIER fragment (a lower index), never itself or a later one. A \`TransactWriteItems\` is atomic and cannot read one item's value while writing another, so the reference graph must be acyclic.`
+          `mutation '${plan2.name}': fragment #${consumerIndex} binds '${consumerField}' to '${ref.path}', a CIRCULAR cross-fragment dependency \u2014 a fragment may only reference a value produced by an EARLIER fragment (a lower index), never itself or a later one. A \`TransactWriteItems\` is atomic and cannot read one item's value while writing another, so the reference graph must be acyclic.`
         );
       }
       const producer = compiled[ref.fragmentIndex];
       const resolved = producedFieldLeaf(producer, ref.field);
       if (resolved === void 0) {
         throw new Error(
-          `mutation '${plan.name}': fragment #${consumerIndex} binds '${consumerField}' to '${ref.path}', but fragment #${ref.fragmentIndex} ('${producer.op.entity.name}') does not write a field '${ref.field}'. A cross-fragment reference must name a field the producing fragment binds in its \`input\`.`
+          `mutation '${plan2.name}': fragment #${consumerIndex} binds '${consumerField}' to '${ref.path}', but fragment #${ref.fragmentIndex} ('${producer.op.entity.name}') does not write a field '${ref.field}'. A cross-fragment reference must name a field the producing fragment binds in its \`input\`.`
         );
       }
       return resolved;
@@ -1995,17 +3797,17 @@ function compileMutationPlan(plan) {
     const prior = byKey.get(sig);
     if (prior !== void 0) {
       throw new Error(
-        `mutation '${plan.name}': fragments #${prior} and #${i} both write the same item ('${compiled[i].op.entity.name}', key ${describeKey(compiled[i])}) in one \`TransactWriteItems\`. DynamoDB rejects a transaction that operates on the same primary key more than once \u2014 split the conflicting writes into separate mutations, or merge them into a single fragment.`
+        `mutation '${plan2.name}': fragments #${prior} and #${i} both write the same item ('${compiled[i].op.entity.name}', key ${describeKey(compiled[i])}) in one \`TransactWriteItems\`. DynamoDB rejects a transaction that operates on the same primary key more than once \u2014 split the conflicting writes into separate mutations, or merge them into a single fragment.`
       );
     }
     byKey.set(sig, i);
   }
   if (compiled.length > MAX_TRANSACT_COMPOSE_ITEMS) {
     throw new Error(
-      `mutation '${plan.name}': composes ${compiled.length} write fragments into one \`TransactWriteItems\`, but DynamoDB caps a transaction at ${MAX_TRANSACT_COMPOSE_ITEMS} items and a transaction is atomic \u2014 it cannot be split across requests without breaking atomicity. Reduce the fragment count to \u2264${MAX_TRANSACT_COMPOSE_ITEMS}.`
+      `mutation '${plan2.name}': composes ${compiled.length} write fragments into one \`TransactWriteItems\`, but DynamoDB caps a transaction at ${MAX_TRANSACT_COMPOSE_ITEMS} items and a transaction is atomic \u2014 it cannot be split across requests without breaking atomicity. Reduce the fragment count to \u2264${MAX_TRANSACT_COMPOSE_ITEMS}.`
     );
   }
-  return { name: plan.name, fragments: compiled };
+  return { name: plan2.name, fragments: compiled };
 }
 function producedFieldLeaf(producer, field) {
   const op = producer.op;
@@ -2029,17 +3831,24 @@ function describeKey(fragment) {
 }
 
 // src/spec/guard.ts
-function conditionInputToSpec(condition, context, renderLeaf) {
+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 field equality).`
+      `${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) {
-    if (typeof obj.attributeExists !== "string" || obj.attributeExists.length === 0) {
+  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.`
       );
@@ -2054,12 +3863,122 @@ function conditionInputToSpec(condition, context, renderLeaf) {
     }
     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] = renderLeaf(key, obj[key]);
+    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) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) return false;
+  return keys.every((k) => OPERATOR_KEYS2.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 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 (!isOperatorObject2(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") {
@@ -2086,8 +4005,25 @@ function assertSupportedCondition(commandName, condition) {
     }
     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. The Python bridge supports '{ notExists }' or field equality only.`
+    `Command '${commandName}' has an unsupported write condition.`
   );
 }
 function assertJsonSerializable(value, path = "$") {
@@ -2500,17 +4436,17 @@ function verifyWrite(instrs, surfaced) {
       "defineTransaction: write operation diverged between evaluation passes; the callback must be a pure, declarative description of the writes."
     );
   }
-  verifyRecord2(instrs.map((x) => x.item), surfaced, `${op} item`);
-  verifyRecord2(instrs.map((x) => x.key), surfaced, `${op} key`);
-  verifyRecord2(instrs.map((x) => x.changes), surfaced, `${op} changes`);
-  verifyRecord2(
+  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(
     instrs.map((x) => x.condition),
     surfaced,
     `${op} condition`
   );
   verifyWhen(instrs.map((x) => x.when), surfaced, `${op} when`);
 }
-function verifyRecord2(records, surfaced, context) {
+function verifyRecord(records, surfaced, context) {
   const present = records.filter((r) => r !== void 0);
   if (present.length === 0) return;
   if (present.length !== records.length) {
@@ -2528,7 +4464,7 @@ function verifyRecord2(records, surfaced, context) {
     }
   }
   for (const field of keys) {
-    verifyLeaf2(
+    verifyLeaf(
       present.map((r) => r[field]),
       surfaced,
       `${context} field '${field}'`
@@ -2546,9 +4482,9 @@ function verifyWhen(whens, surfaced, context) {
   for (const w of present) {
     if (isTransactionRef(w.left)) surfaced.add(w.left.token);
   }
-  verifyLeaf2(present.map((w) => w.right), surfaced, `${context} right-hand value`);
+  verifyLeaf(present.map((w) => w.right), surfaced, `${context} right-hand value`);
 }
-function verifyLeaf2(values, surfaced, context) {
+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) {
@@ -2566,7 +4502,7 @@ function verifyLeaf2(values, surfaced, context) {
     surfaced.add(token);
     return;
   }
-  const norm = values.map(normalizeLiteral2);
+  const norm = values.map(normalizeLiteral);
   for (let i = 1; i < norm.length; i++) {
     if (norm[i] !== norm[0]) {
       throw new Error(
@@ -2575,7 +4511,7 @@ function verifyLeaf2(values, surfaced, context) {
     }
   }
 }
-function normalizeLiteral2(value) {
+function normalizeLiteral(value) {
   if (value === null) return "t:null";
   if (value instanceof Date) return `t:date:${value.toISOString()}`;
   const t = typeof value;
@@ -2636,6 +4572,17 @@ function leafTemplate(value, context) {
     `defineTransaction: ${context} must be a field reference (from \`p\` or a forEach element) or a concrete literal; got ${typeof value}.`
   );
 }
+function conditionTreeLeaf(value, name, context) {
+  void name;
+  if (isTransactionRef(value)) return { $param: tokenName(value.token) };
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  throw new Error(
+    `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) {
   const out = {};
   for (const field of Object.keys(structure).sort()) {
@@ -2679,7 +4626,12 @@ function conditionSpec(condition, commandName) {
   const spec = conditionInputToSpec(
     condition,
     commandName,
-    (field, value) => leafTemplate(value, `condition field '${field}'`)
+    (field, value) => leafTemplate(value, `condition field '${field}'`),
+    (value, name) => conditionTreeLeaf(value, name, commandName),
+    // A raw `cond` value slot in a transaction is a field reference
+    // (`p.*` / forEach element) → a `{ $param }` marker carrying its token name;
+    // a concrete literal falls through to the default renderer (issue #114-B).
+    (part) => isTransactionRef(part) ? { $param: tokenName(part.token) } : void 0
   );
   if (spec) assertSupportedCondition(commandName, spec);
   return spec;
@@ -2866,113 +4818,6 @@ ${rest.map((v) => `  - ${v.message}`).join("\n")})` : "";
   throw new Error(first.message + suffix);
 }
 
-// src/relation/concurrency.ts
-var RELATION_TRAVERSAL_CONCURRENCY = 16;
-async function mapWithConcurrency(items, limit, worker) {
-  if (items.length === 0) {
-    return [];
-  }
-  const effectiveLimit = Math.max(1, Math.min(limit, items.length));
-  if (effectiveLimit >= items.length) {
-    return Promise.all(items.map((item, index) => worker(item, index)));
-  }
-  const results = new Array(items.length);
-  let nextIndex = 0;
-  async function runWorker() {
-    while (true) {
-      const index = nextIndex++;
-      if (index >= items.length) {
-        return;
-      }
-      results[index] = await worker(items[index], index);
-    }
-  }
-  const runners = [];
-  for (let i = 0; i < effectiveLimit; i++) {
-    runners.push(runWorker());
-  }
-  await Promise.all(runners);
-  return results;
-}
-
-// src/relation/execution-plan.ts
-function relationResultPaths(select, metadata, parentPath = "$") {
-  const out = [];
-  const relations = detectRelationFields(select, metadata);
-  for (const rel of [...relations].sort(
-    (a, b) => a.propertyName.localeCompare(b.propertyName)
-  )) {
-    const childSelect = normalizeSelectSpec(select[rel.propertyName]).select ?? {};
-    const targetMeta = MetadataRegistry.get(rel.targetFactory());
-    const childPath = `${parentPath}.${rel.propertyName}`;
-    const isMany = rel.type === "hasMany";
-    const resultPath = isMany ? `${childPath}.items` : childPath;
-    out.push({
-      propertyName: rel.propertyName,
-      parentPath,
-      resultPath,
-      isMany
-    });
-    out.push(...relationResultPaths(childSelect, targetMeta, resultPath));
-  }
-  return out;
-}
-function parentResultPath(resultPath) {
-  if (!resultPath.startsWith("$.")) return "$";
-  const tokens = resultPath.slice(2).split(".");
-  if (tokens[tokens.length - 1] === "items") tokens.pop();
-  tokens.pop();
-  return tokens.length === 0 ? "$" : `$.${tokens.join(".")}`;
-}
-function deriveExecutionPlan(resultPaths) {
-  if (resultPaths.length <= 1) return void 0;
-  const indexByPath = /* @__PURE__ */ new Map();
-  resultPaths.forEach((path, i) => {
-    indexByPath.set(path, i);
-  });
-  const stageOf = new Array(resultPaths.length);
-  for (let i = 0; i < resultPaths.length; i++) {
-    if (resultPaths[i] === "$") {
-      stageOf[i] = 0;
-      continue;
-    }
-    const parentPath = parentResultPath(resultPaths[i]);
-    const parentIndex = indexByPath.get(parentPath);
-    const parentStage = parentIndex !== void 0 ? stageOf[parentIndex] : 0;
-    stageOf[i] = parentStage + 1;
-  }
-  const stageCount = Math.max(...stageOf) + 1;
-  const groups = Array.from({ length: stageCount }, () => []);
-  for (let i = 0; i < resultPaths.length; i++) {
-    groups[stageOf[i]].push(i);
-  }
-  for (const g of groups) g.sort((a, b) => a - b);
-  return { groups, concurrency: RELATION_TRAVERSAL_CONCURRENCY };
-}
-function buildRelationExecutionPlan(select, metadata) {
-  const relationPaths = relationResultPaths(select, metadata);
-  if (relationPaths.length === 0) return void 0;
-  const resultPaths = ["$", ...relationPaths.map((r) => r.resultPath)];
-  const plan = deriveExecutionPlan(resultPaths);
-  if (plan === void 0) return void 0;
-  return { plan, resultPaths };
-}
-function deriveCompositionPlan(composeCount) {
-  if (composeCount <= 0) {
-    return { stages: [], concurrency: RELATION_TRAVERSAL_CONCURRENCY };
-  }
-  const stage = Array.from({ length: composeCount }, (_unused, i) => i);
-  return { stages: [stage], concurrency: RELATION_TRAVERSAL_CONCURRENCY };
-}
-function stageOfResultPath(resolved, resultPath) {
-  const index = resolved.resultPaths.indexOf(resultPath);
-  if (index < 0) return void 0;
-  for (let s = 0; s < resolved.plan.groups.length; s++) {
-    if (resolved.plan.groups[s].includes(index)) return s;
-  }
-  return void 0;
-}
-
 // src/spec/contract-boundary-check.ts
 function buildOwnershipIndex(contexts) {
   const modelOwner = /* @__PURE__ */ new Map();
@@ -3202,12 +5047,12 @@ function buildHasManyOperation(rel, targetMeta, select, limit, filter, resultPat
       const keyCondition2 = {
         PK: pk2
       };
-      const range3 = sk2 !== void 0 && sk2 !== "" ? { operator: "begins_with", key: "SK", value: sk2 } : void 0;
+      const range2 = sk2 !== void 0 && sk2 !== "" ? { operator: "begins_with", key: "SK", value: sk2 } : void 0;
       return {
         type: "Query",
         tableName,
         keyCondition: keyCondition2,
-        ...range3 ? { rangeCondition: range3 } : {},
+        ...range2 ? { rangeCondition: range2 } : {},
         projection: projectionFields(select),
         limit,
         resultPath,
@@ -3223,13 +5068,13 @@ function buildHasManyOperation(rel, targetMeta, select, limit, filter, resultPat
       resolved.partial
     );
     const keyCondition = { [`${gsi.indexName}PK`]: pk };
-    const range2 = sk !== void 0 && sk !== "" ? { operator: "begins_with", key: `${gsi.indexName}SK`, value: sk } : void 0;
+    const range = sk !== void 0 && sk !== "" ? { operator: "begins_with", key: `${gsi.indexName}SK`, value: sk } : void 0;
     return {
       type: "Query",
       tableName,
       indexName: gsi.indexName,
       keyCondition,
-      ...range2 ? { rangeCondition: range2 } : {},
+      ...range ? { rangeCondition: range } : {},
       projection: projectionFields(select),
       limit,
       resultPath,
@@ -3337,9 +5182,32 @@ function extractCondition(def) {
   return conditionInputToSpec(
     def.condition,
     `Command on '${def.entity.name}'`,
-    (field, value) => templateLeaf(field, value)
+    (field, value) => templateLeaf(field, value),
+    (value, name) => conditionTreeLeaf2(value, name),
+    // A raw `cond` value slot (issue #114-B): a contract param / key ref carries
+    // its own name; a plain `param.*` falls through to the positional default.
+    (part) => {
+      if (isContractParamRef(part)) return { $param: tokenName2(part.token) };
+      if (isContractKeyFieldRef(part)) return { $param: part.field };
+      return void 0;
+    }
   );
 }
+function conditionTreeLeaf2(value, name) {
+  if (isContractParamRef(value)) return { $param: tokenName2(value.token) };
+  if (isContractKeyFieldRef(value)) return { $param: value.field };
+  if (isParam(value)) return { $param: name };
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  throw new Error(
+    `A declarative write-condition operand must be a concrete literal or a param reference; got ${typeof value}.`
+  );
+}
+function tokenName2(token) {
+  return token.startsWith("{") && token.endsWith("}") ? token.slice(1, -1) : token;
+}
 function buildQuerySpec(def) {
   const operations = buildReadOperations(def);
   const executionPlan = deriveExecutionPlan(operations.map((op) => op.resultPath));
@@ -3497,6 +5365,7 @@ function convertLeaf(leaf, bindField, place, context) {
   );
 }
 function convertCondition(condition, place, context) {
+  if (isRawCondition(condition)) return condition;
   if (typeof condition === "object" && condition !== null) {
     const obj = condition;
     if (obj.notExists === true) return { notExists: true };
@@ -3659,8 +5528,32 @@ function toElementRecord(record, keyParams) {
   return out;
 }
 function toElementCondition(condition, keyParams) {
-  if (condition.kind !== "equals") return condition;
-  return { kind: "equals", fields: toElementRecord(condition.fields, keyParams) };
+  if (condition.kind === "equals") {
+    return { kind: "equals", fields: toElementRecord(condition.fields, keyParams) };
+  }
+  if (condition.kind === "expr") {
+    return { kind: "expr", declarative: toElementTree(condition.declarative, keyParams) };
+  }
+  if (condition.kind === "raw") {
+    return {
+      kind: "raw",
+      expression: condition.expression,
+      names: condition.names,
+      values: toElementTree(condition.values, keyParams)
+    };
+  }
+  return condition;
+}
+function toElementTree(node, keyParams) {
+  if (Array.isArray(node)) return node.map((n) => toElementTree(n, keyParams));
+  if (node === null || typeof node !== "object") return node;
+  const obj = node;
+  if (typeof obj.$param === "string" && !obj.$param.startsWith("item.")) {
+    return keyParams.has(obj.$param) ? { $param: `item.${obj.$param}` } : obj;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) out[k] = toElementTree(v, keyParams);
+  return out;
 }
 function synthesizeBatchTransaction(commandSpec, op) {
   const keyParams = new Set(keyParamNames(op));
@@ -3933,15 +5826,9 @@ function synthesizeMutationTransaction(contractName, methodName, ops, checks, ed
   }
   return { params: sortedParams(params), items, maxItems: items.length };
 }
-function batchTargetFor(mode, op, commandSpec, contractName, methodName, opName, transactionSpecs) {
-  if (mode === void 0) return void 0;
-  if (mode === "batchWrite") {
-    if (commandSpec.condition !== void 0) {
-      throw new Error(
-        `Contract '${contractName}.${methodName}': a 'batchWrite' batched form cannot carry a write condition \u2014 DynamoDB's BatchWriteItem has no ConditionExpression. Declare \`batch: 'transact'\` for a conditional batch.`
-      );
-    }
-    return { mode: "batchWrite", operation: opName };
+function modeTargetFor(mode, op, commandSpec, contractName, methodName, opName, transactionSpecs) {
+  if (mode === "parallel") {
+    return { mode: "parallel", operation: opName };
   }
   const txName = batchTxName(contractName, methodName);
   transactionSpecs[txName] = synthesizeBatchTransaction(commandSpec, op);
@@ -4076,15 +5963,15 @@ function serializeCommandContract(contractName, contract, commandSpecs, transact
         returnSelection
       );
     }
-    const batch = batchTargetFor(
-      method.batch,
+    const batch = method.mode !== void 0 && !promotedToTransaction ? modeTargetFor(
+      method.mode,
       op,
       commandSpec,
       contractName,
       methodName,
       opName,
       transactionSpecs
-    );
+    ) : void 0;
     const single = promotedToTransaction ? { mode: "transaction", transaction: opName } : { mode: "op", operation: opName };
     methods[methodName] = {
       inputArity: method.inputArity,
@@ -4197,13 +6084,28 @@ export {
   buildManifest,
   isSelectBuilder,
   normalizeSelectSpec,
-  normalizeTopLevelSelect,
-  buildProject,
-  buildRelation,
   detectRelationFields,
   getImplicitKeyFields,
-  param,
-  isParam,
+  buildProjection,
+  compileFilterExpression,
+  evaluateFilter,
+  plan,
+  execute,
+  hydrate,
+  encodeCursor,
+  decodeCursor,
+  executeListInternal,
+  executeList,
+  RELATION_TRAVERSAL_CONCURRENCY,
+  mapWithConcurrency,
+  deriveCompositionPlan,
+  validateDepth,
+  resolveRelations,
+  executeQuery,
+  executeExplain,
+  BatchGetResult,
+  executeBatchGet,
+  executeBatchWrite,
   LIFECYCLE_CONTRACT_MARKER,
   isLifecycleContract,
   ENTITY_WRITES_MARKER,
@@ -4211,11 +6113,6 @@ export {
   entityWrites,
   getEntityWrites,
   lifecyclePhaseForIntent,
-  isMutationInputRef,
-  isMutationFragment,
-  isCommandPlan,
-  mutation,
-  definePlan,
   OLD_VALUE_NAMESPACE,
   EDGE_WRITES_MARKER,
   isEdgeWritesDefinition,
@@ -4228,7 +6125,13 @@ export {
   compileFragment,
   compileSingleFragmentPlan,
   compileMutationPlan,
-  isCommandBatchMode,
+  executeCommandMethod,
+  DDBModel,
+  isMutationInputRef,
+  isMutationFragment,
+  isCommandPlan,
+  mutation,
+  definePlan,
   isContractKeyRef,
   mintContractKeyFieldRef,
   wholeKeysSentinel,
@@ -4240,21 +6143,12 @@ export {
   from,
   query,
   contractOfMethodSpec,
-  recordContractOp,
-  isRecordingContractMethod,
-  point,
-  range,
   isQueryModelContract,
   isCommandModelContract,
   publicQueryModel,
   publicCommandModel,
   isPlannedCommandMethod,
-  command,
-  RELATION_TRAVERSAL_CONCURRENCY,
-  mapWithConcurrency,
-  buildRelationExecutionPlan,
-  deriveCompositionPlan,
-  stageOfResultPath,
+  conditionParamName,
   assertSupportedCondition,
   assertJsonSerializable,
   assertBundleSerializable,