graphddb 0.1.0

package/dist/chunk-6LEHSX45.js

@@ -0,0 +1,4276 @@
+import {
+  BATCH_GET_MAX_KEYS,
+  MAX_TRANSACT_ITEMS,
+  MetadataRegistry,
+  TableMapping,
+  pkTemplate,
+  resolveKey,
+  resolveModelClass,
+  segmentFieldNames,
+  skTemplate
+} from "./chunk-347U24SB.js";
+
+// src/spec/types.ts
+var SPEC_VERSION = "1.0";
+var MARKER_ROW_ENTITY = "__marker__";
+
+// src/spec/symbolic.ts
+function evaluateKey(segmented, scope, presentFields, nameOf = (f) => f, partial = false) {
+  void partial;
+  const pk = pkTemplate(segmented, scope, nameOf);
+  const sk = skTemplate(segmented, presentFields, scope, nameOf);
+  return { pk, sk: sk?.template };
+}
+
+// src/spec/manifest.ts
+var DYNAMO_TYPE_TO_FIELD_TYPE = {
+  S: "string",
+  N: "number",
+  BOOL: "boolean",
+  B: "binary",
+  SS: "stringSet",
+  NS: "numberSet",
+  L: "list",
+  M: "map"
+};
+function sortedRecord(record) {
+  const out = {};
+  for (const key of Object.keys(record).sort()) {
+    out[key] = record[key];
+  }
+  return out;
+}
+function buildKey(key) {
+  if (!key) return null;
+  const { pk, sk } = evaluateKey(key.segmented, "param");
+  return {
+    inputFields: [...key.inputFieldNames],
+    pkTemplate: pk,
+    skTemplate: sk ?? null
+  };
+}
+function buildGsis(metadata) {
+  return [...metadata.gsiDefinitions].sort((a, b) => a.indexName.localeCompare(b.indexName)).map((gsi) => {
+    const { pk, sk } = evaluateKey(gsi.segmented, "param");
+    return {
+      indexName: gsi.indexName,
+      unique: gsi.unique,
+      inputFields: [...gsi.inputFieldNames],
+      pkTemplate: pk,
+      skTemplate: sk ?? null
+    };
+  });
+}
+function buildRelations(metadata) {
+  const relations = {};
+  for (const rel of metadata.relations) {
+    const targetClass = rel.targetFactory();
+    relations[rel.propertyName] = {
+      type: rel.type,
+      target: targetClass.name,
+      keyBinding: { ...rel.keyBinding }
+    };
+  }
+  return sortedRecord(relations);
+}
+function buildFields(metadata) {
+  const fields = {};
+  for (const field of metadata.fields) {
+    const format = field.options?.format;
+    fields[field.propertyName] = format ? { type: DYNAMO_TYPE_TO_FIELD_TYPE[field.dynamoType], format } : { type: DYNAMO_TYPE_TO_FIELD_TYPE[field.dynamoType] };
+  }
+  return sortedRecord(fields);
+}
+function buildEntity(metadata) {
+  return {
+    table: metadata.tableName,
+    physicalName: TableMapping.resolve(metadata.tableName),
+    prefix: metadata.prefix,
+    fields: buildFields(metadata),
+    key: buildKey(metadata.primaryKey),
+    gsis: buildGsis(metadata),
+    relations: buildRelations(metadata)
+  };
+}
+function buildManifest(registry = MetadataRegistry) {
+  const all = registry.getAll();
+  const entitiesByName = /* @__PURE__ */ new Map();
+  for (const [cls, metadata] of all) {
+    entitiesByName.set(cls.name, metadata);
+  }
+  const entities = {};
+  const tables = {};
+  for (const name of [...entitiesByName.keys()].sort()) {
+    const metadata = entitiesByName.get(name);
+    entities[name] = buildEntity(metadata);
+    tables[metadata.tableName] = {
+      physicalName: TableMapping.resolve(metadata.tableName)
+    };
+  }
+  return {
+    version: SPEC_VERSION,
+    tables: sortedRecord(tables),
+    entities
+  };
+}
+
+// src/types/select-builder.ts
+var SELECT_BUILDER = /* @__PURE__ */ Symbol.for("graphddb.selectBuilder");
+var SELECT_SPEC = /* @__PURE__ */ Symbol.for("graphddb.selectSpec");
+
+// src/select/builder.ts
+var BuilderImpl = class _BuilderImpl {
+  [SELECT_BUILDER] = true;
+  /** The resolved spec, exposed (non-method) so normalizers can read it. */
+  [SELECT_SPEC];
+  constructor(spec) {
+    this[SELECT_SPEC] = spec;
+  }
+  clone(patch) {
+    return new _BuilderImpl({ ...this[SELECT_SPEC], ...patch });
+  }
+  filter(filter) {
+    return this.clone({ filter });
+  }
+  limit(limit) {
+    return this.clone({ limit });
+  }
+  after(cursor) {
+    return this.clone({ after: cursor });
+  }
+  order(order) {
+    return this.clone({ order });
+  }
+};
+function isSelectBuilder(value) {
+  return typeof value === "object" && value !== null && value[SELECT_BUILDER] === true;
+}
+function fromBuilder(value) {
+  const spec = value[SELECT_SPEC];
+  return {
+    select: spec.select,
+    filter: spec.filter,
+    limit: spec.limit,
+    after: spec.after,
+    order: spec.order
+  };
+}
+function normalizeSelectSpec(value) {
+  if (isSelectBuilder(value)) {
+    return fromBuilder(value);
+  }
+  const obj = value;
+  return {
+    select: obj.select,
+    filter: obj.filter,
+    limit: obj.limit,
+    after: obj.after,
+    order: obj.order
+  };
+}
+function normalizeTopLevelSelect(value) {
+  if (isSelectBuilder(value)) {
+    return fromBuilder(value);
+  }
+  return { select: value ?? {} };
+}
+function buildProject(select) {
+  return new BuilderImpl({
+    [SELECT_BUILDER]: true,
+    select
+  });
+}
+function buildRelation(select) {
+  return new BuilderImpl({
+    [SELECT_BUILDER]: true,
+    select
+  });
+}
+
+// src/relation/detect.ts
+function isRelationSpec(value) {
+  if (typeof value !== "object" || value === null) return false;
+  return "select" in value || isSelectBuilder(value);
+}
+function detectRelationFields(select, metadata) {
+  const result = [];
+  for (const [fieldName, value] of Object.entries(select)) {
+    if (isRelationSpec(value)) {
+      const rel = metadata.relations.find((r) => r.propertyName === fieldName);
+      if (rel) {
+        result.push(rel);
+      }
+    }
+  }
+  return result;
+}
+function getImplicitKeyFields(select, metadata) {
+  const relations = detectRelationFields(select, metadata);
+  const needed = /* @__PURE__ */ new Set();
+  for (const rel of relations) {
+    for (const sourceField of Object.values(rel.keyBinding)) {
+      if (!(sourceField in select) || select[sourceField] !== true) {
+        needed.add(sourceField);
+      }
+    }
+  }
+  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 };
+  }
+};
+function isParam(value) {
+  return typeof value === "object" && value !== null && "kind" in value && (value.kind === "string" || value.kind === "number" || value.kind === "literal" || value.kind === "array");
+}
+
+// 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/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\`.`
+      );
+    }
+    return void 0;
+  }
+  return {
+    [ENTITY_REF_BRAND]: true,
+    fragmentIndex: Number(match[1]),
+    field: match[2],
+    path: leaf
+  };
+}
+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}.`);
+    }
+  });
+  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);
+      }
+      return ref;
+    },
+    set() {
+      throw new Error("mutation: cannot assign to the `$` input proxy.");
+    }
+  });
+}
+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 };
+}
+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) && !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.`
+      );
+    }
+  }
+  return input;
+}
+function isConcreteLiteral(value) {
+  const t = typeof value;
+  return value === null || value instanceof Date || t === "string" || t === "number" || t === "boolean";
+}
+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.`
+    );
+  }
+  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;
+}
+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.");
+  }
+  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.`
+    );
+  }
+  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.`
+    );
+  }
+  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 };
+}
+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;
+}
+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 [
+    ...segmentFieldNames(segmented.pkSegments),
+    ...segmentFieldNames(segmented.skSegments)
+  ];
+}
+function assertRelationRoundTrips(entity, edgeFields, decl) {
+  const targetClass = decl.targetFactory();
+  const targetMeta = MetadataRegistry.get(targetClass);
+  const relation = targetMeta.relations.find(
+    (r) => r.propertyName === decl.relationProperty
+  );
+  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.`
+    );
+  }
+  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/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}}` };
+}
+function wholeKeysSentinel() {
+  return { [KEY_REF_BRAND]: true };
+}
+function isContractKeyFieldRef(value) {
+  return typeof value === "object" && value !== null && value[KEY_FIELD_REF_BRAND] === true;
+}
+function makeKeyFieldRef(field, marker, onCoerce) {
+  const token = `{key.${field}}`;
+  const origin = `keys field '${field}'`;
+  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 === "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 (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* 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.`
+      );
+    },
+    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}.`);
+    }
+  });
+  return proxy;
+}
+function makeKeySentinel(pass, onFieldAccess, onCoerce) {
+  const cache = /* @__PURE__ */ new Map();
+  const target = /* @__PURE__ */ Object.create(null);
+  const proxy = new Proxy(target, {
+    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 (!ref) {
+        ref = makeKeyFieldRef(prop, paramMarker(pass, `key.${prop}`), onCoerce);
+        cache.set(prop, 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`."
+      );
+    }
+  });
+  return proxy;
+}
+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 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 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() {
+      throw new Error(
+        `publicQueryModel/publicCommandModel: cannot define a property on ${origin}.`
+      );
+    },
+    deleteProperty() {
+      throw new Error(
+        `publicQueryModel/publicCommandModel: cannot delete on ${origin}.`
+      );
+    }
+  });
+  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;
+        }
+        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."
+        );
+      }
+      onAccess(prop);
+      let ref = cache.get(prop);
+      if (!ref) {
+        ref = makeParamFieldRef(prop, paramMarker(pass, prop), () => onCoerce(prop));
+        cache.set(prop, ref);
+      }
+      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() {
+      throw new Error(
+        "publicQueryModel/publicCommandModel: cannot delete a field of `params`."
+      );
+    }
+  });
+}
+var FROM_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:contractFromRef");
+var COMPOSE_NODE_BRAND = /* @__PURE__ */ Symbol("graphddb:contractComposeNode");
+function isContractFromRef(value) {
+  return typeof value === "object" && value !== null && value[FROM_REF_BRAND] === true;
+}
+function isContractComposeNode(value) {
+  return typeof value === "object" && value !== null && value[COMPOSE_NODE_BRAND] === true;
+}
+var FROM_PATH_RE = /^\$(?:\.[^.\s$[\]*]+)*$/;
+var FROM_PATH_BLOCKED_SEGMENTS = /* @__PURE__ */ new Set([
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
+function from(path) {
+  if (typeof path !== "string" || !FROM_PATH_RE.test(path)) {
+    throw new Error(
+      `query/from: a composition binding source must be a \`$\`-rooted dotted field path string (e.g. \`from("$.billingAccountId")\` or \`from("$.a.b")\`), but received ${JSON.stringify(path)}. The binding is declarative \u2014 only a literal parent-result field path is allowed, never a computed value.`
+    );
+  }
+  const blocked = path.split(".").find((segment) => FROM_PATH_BLOCKED_SEGMENTS.has(segment));
+  if (blocked !== void 0) {
+    throw new Error(
+      `query/from: a composition binding source path may not address the segment \`${blocked}\` (received ${JSON.stringify(path)}). The segments \`__proto__\`, \`constructor\`, and \`prototype\` are forbidden in a \`$\`-rooted field path \u2014 they are never valid parent-result fields.`
+    );
+  }
+  return { [FROM_REF_BRAND]: true, path };
+}
+function query(method, bind) {
+  if (typeof method !== "object" || method === null || method.__methodKind !== "query") {
+    throw new Error(
+      `query: the first argument must be a query contract method (e.g. \`OtherContract.get\`, the value of a publicQueryModel method). A command method or a non-method value is not composable as an External Query.`
+    );
+  }
+  if (typeof bind !== "object" || bind === null) {
+    throw new Error(
+      `query: the second argument must be a child-key binding object (e.g. \`{ accountId: from("$.billingAccountId") }\`).`
+    );
+  }
+  const entries = Object.entries(bind);
+  if (entries.length === 0) {
+    throw new Error(
+      `query: a composition must bind at least one child key field via \`from(...)\` (e.g. \`{ accountId: from("$.billingAccountId") }\`); an empty binding cannot resolve the child's key.`
+    );
+  }
+  const resolvedBind = {};
+  for (const [field, ref] of entries) {
+    if (!isContractFromRef(ref)) {
+      throw new Error(
+        `query: composition binding for child key field '${field}' must be a \`from("$.parentField")\` reference, not ${JSON.stringify(ref)}. The parent\u2192child key binding is declarative \u2014 only \`from(...)\` paths are allowed.`
+      );
+    }
+    resolvedBind[field] = ref;
+  }
+  return { [COMPOSE_NODE_BRAND]: true, method, bind: resolvedBind };
+}
+var methodSpecToContract = /* @__PURE__ */ new WeakMap();
+function contractOfMethodSpec(method) {
+  return methodSpecToContract.get(method);
+}
+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 = {};
+  const compose = [];
+  for (const [field, value] of Object.entries(select)) {
+    if (isContractComposeNode(value)) {
+      if (operation !== "query" && operation !== "list") {
+        throw new Error(
+          `publicQueryModel: an External Query composition (\`query(...)\`) at select property '${field}' is only valid on a read; the recorded op on '${entityName}' is a '${operation}'.`
+        );
+      }
+      compose.push({ as: field, method: value.method, bind: value.bind });
+      continue;
+    }
+    projection[field] = value;
+  }
+  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" };
+  }
+  if (isContractKeyRef(op.keys) && op.keyFields !== void 0 && op.keyFields.length > 0) {
+    const metadata = MetadataRegistry.get(
+      op.entity.modelClass
+    );
+    const resolved = resolveKey([...op.keyFields], metadata);
+    if (resolved.type === "gsi") {
+      if (resolved.unique && !resolved.partial) {
+        return { resolution: "point", inputArity: "single" };
+      }
+      return { resolution: "range", inputArity: "single" };
+    }
+    if (resolved.partial) {
+      return { resolution: "range", inputArity: "single" };
+    }
+    return { resolution: "point", inputArity: "either" };
+  }
+  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 buildQueryContract(methods, keyFields) {
+  const resolved = {};
+  for (const [name, body] of Object.entries(methods)) {
+    if (typeof body !== "function") {
+      throw new Error(
+        `publicQueryModel: method '${name}' must be a function (keys, params) => Model.query(...) | Model.list(...).`
+      );
+    }
+    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,
+      resolution,
+      inputArity,
+      __methodName: name
+    };
+  }
+  const contract = { __isContract: true, kind: "query", methods: resolved };
+  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 buildCommandContract(methods, keyFields) {
+  const resolved = {};
+  for (const [name, body] of Object.entries(methods)) {
+    if (isPlannedCommandMethod(body)) {
+      resolved[name] = buildPlannedCommandMethod(name, body, keyFields);
+      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).`
+      );
+    }
+    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.`
+      );
+    }
+    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 } : {}
+    };
+  }
+  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.`
+      );
+    }
+  }
+  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);
+  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.`
+    );
+  }
+  const idempotencyGuard = idempotencyGuards[0];
+  return {
+    __methodKind: "command",
+    op,
+    ...ops !== void 0 ? { ops } : {},
+    ...conditionChecks.length > 0 ? { conditionChecks } : {},
+    ...edgeWrites2.length > 0 ? { edgeWrites: edgeWrites2 } : {},
+    ...derivedUpdates.length > 0 ? { derivedUpdates } : {},
+    ...uniqueGuards.length > 0 ? { uniqueGuards } : {},
+    ...outboxEvents.length > 0 ? { outboxEvents } : {},
+    ...idempotencyGuard !== void 0 ? { idempotencyGuard } : {},
+    inputArity: "either",
+    // A return projection means the method returns the read-back entity; otherwise
+    // it is a fire-and-forget write (`void`).
+    result: returnSelection !== void 0 ? "entity" : "void",
+    ...returnSelection !== void 0 ? { returnSelection } : {}
+  };
+}
+function normalizeReturnSelection(select) {
+  if (select === void 0) return void 0;
+  const out = {};
+  for (const [field, flag] of Object.entries(select)) {
+    if (flag === true) out[field] = true;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+
+// src/spec/mutation-command.ts
+var INTENT_OPERATION = {
+  create: "put",
+  update: "update",
+  remove: "delete"
+};
+var INPUT_PATH_RE = /^\$\.input\.([A-Za-z_$][\w$]*)$/;
+var ENTITY_FIELD_PATH_RE = /^\$\.entity\.([A-Za-z_$][\w$]*)$/;
+var OLD_PATH_RE = /^\$\.old\.([A-Za-z_$][\w$]*)$/;
+var INTENT_EDGE_LIFECYCLE = {
+  create: "onCreate",
+  update: "onUpdateKeyChange",
+  remove: "onDelete"
+};
+function deriveConditionChecks(fragment, requires) {
+  return requires.map((req) => deriveOneConditionCheck(fragment, req));
+}
+function deriveOneConditionCheck(fragment, req) {
+  const targetClass = req.targetFactory();
+  const targetName = targetClass.name;
+  const metadata = MetadataRegistry.get(
+    targetClass
+  );
+  if (!metadata.primaryKey) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares a \`requires\` referential-integrity constraint on '${targetName}', but that model has no primary key \u2014 a ConditionCheck (\`attribute_exists\`) asserts a keyed row, so the referenced entity must declare a primary key.`
+    );
+  }
+  const targetKeyFields = metadata.primaryKey.inputFieldNames;
+  const keyBinding = {};
+  for (const [targetField, source] of Object.entries(req.keys)) {
+    if (!targetKeyFields.includes(targetField)) {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' binds '${targetName}.${targetField}' in its \`requires\` constraint, but '${targetField}' is not a primary-key field of '${targetName}' (its key is [${targetKeyFields.join(", ")}]). A referential-integrity assertion must key the referenced entity by its primary key.`
+      );
+    }
+    const match = INPUT_PATH_RE.exec(source);
+    if (match === null) {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' binds '${targetName}.${targetField}' in its \`requires\` constraint to ${JSON.stringify(source)}, which is not a \`$.input.<field>\` reference. The referenced entity's key is resolved from the mutation input, so each key value must be a \`$.input.<field>\` path (e.g. \`'$.input.userId'\`).`
+      );
+    }
+    keyBinding[targetField] = match[1];
+  }
+  for (const field of targetKeyFields) {
+    if (!(field in keyBinding)) {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares a \`requires\` constraint on '${targetName}' that does not bind its primary-key field '${field}'. A ConditionCheck asserts a single keyed row, so the constraint must bind EVERY primary-key field of '${targetName}' ([${targetKeyFields.join(", ")}]) from \`$.input.*\`.`
+      );
+    }
+  }
+  return { entity: { name: targetName, modelClass: targetClass }, keyBinding };
+}
+function deriveEdgeWrites(fragment, edges, lifecycle) {
+  return edges.map((edge) => deriveOneEdgeWrite(fragment, edge, lifecycle));
+}
+function deriveOneEdgeWrite(fragment, edge, lifecycle) {
+  const targetClass = edge.targetFactory();
+  const targetMeta = MetadataRegistry.get(
+    targetClass
+  );
+  const relation = targetMeta.relations.find(
+    (r) => r.propertyName === edge.relationProperty
+  );
+  if (!relation) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares an edge effect on relation '${edge.relationProperty}' of '${targetClass.name}', which has no such relation. Declare the edge with the read-side relation property it materializes.`
+    );
+  }
+  const adjacencyClass = relation.targetFactory();
+  const items = deriveEdgeWriteItemsFor(
+    adjacencyClass,
+    { targetFactory: edge.targetFactory, relationProperty: edge.relationProperty },
+    lifecycle
+  );
+  return {
+    entity: { name: adjacencyClass.name, modelClass: adjacencyClass },
+    relation: { target: targetClass.name, property: edge.relationProperty },
+    items
+  };
+}
+function deriveUpdates(fragment, derive) {
+  return derive.map((d) => deriveOneUpdate(fragment, d));
+}
+function deriveOneUpdate(fragment, effect) {
+  const targetClass = effect.targetFactory();
+  const targetName = targetClass.name;
+  const metadata = MetadataRegistry.get(
+    targetClass
+  );
+  if (!metadata.primaryKey) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares a derived update on '${targetName}', but that model has no primary key \u2014 an \`UpdateItem\` keys a single row, so the target must declare a primary key.`
+    );
+  }
+  const targetKeyFields = metadata.primaryKey.inputFieldNames;
+  const keyBinding = {};
+  for (const [targetField, source] of Object.entries(effect.keys)) {
+    if (!targetKeyFields.includes(targetField)) {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' binds '${targetName}.${targetField}' in a derived update, but '${targetField}' is not a primary-key field of '${targetName}' (its key is [${targetKeyFields.join(", ")}]). A derived update keys the target by its primary key.`
+      );
+    }
+    const inputMatch = INPUT_PATH_RE.exec(source);
+    const oldMatch = OLD_PATH_RE.exec(source);
+    if (inputMatch !== null) {
+      keyBinding[targetField] = inputMatch[1];
+    } else if (oldMatch !== null) {
+      keyBinding[targetField] = `${OLD_VALUE_NAMESPACE}.${oldMatch[1]}`;
+    } else {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' binds '${targetName}.${targetField}' in a derived update to ${JSON.stringify(source)}, which is not a \`$.input.<field>\` (current value) or \`$.old.<field>\` (pre-mutation value) reference. The target row's key is resolved from the mutation input, so each key value must be a \`$.input.*\` / \`$.old.*\` path.`
+      );
+    }
+  }
+  for (const field of targetKeyFields) {
+    if (!(field in keyBinding)) {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares a derived update on '${targetName}' that does not bind its primary-key field '${field}'. An \`UpdateItem\` keys a single row, so the update must bind EVERY primary-key field of '${targetName}' ([${targetKeyFields.join(", ")}]).`
+      );
+    }
+  }
+  const isField = metadata.fields.some((f) => f.propertyName === effect.attribute);
+  if (!isField) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares a derived update of '${targetName}.${effect.attribute}', which is not a field of '${targetName}'. A derived counter must increment a declared numeric field.`
+    );
+  }
+  const selfModel = targetClass === fragment.entity.modelClass;
+  const allCurrentInput = Object.values(keyBinding).every(
+    (inputField) => !inputField.startsWith(`${OLD_VALUE_NAMESPACE}.`)
+  );
+  const reproducesOwnKey = targetKeyFields.every((field) => keyBinding[field] === field);
+  if (selfModel && allCurrentInput && reproducesOwnKey) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares a derived counter (\`increment\`) on '${targetName}.${effect.attribute}' that targets the SAME row as the entity write (its key binds the fragment's own primary key from \`$.input.*\`). A Put+Update on one item is unsupported in a transaction (DynamoDB rejects touching one key twice), and silently dropping the \`ADD\` would lose the increment. A \`w.increment(...)\` must target a DIFFERENT row (e.g. a parent aggregate's counter); to maintain a counter ON the written entity, write the field as part of the entity itself, not via a derived counter onto its own row.`
+    );
+  }
+  return {
+    entity: { name: targetName, modelClass: targetClass },
+    keyBinding,
+    attribute: effect.attribute,
+    amount: effect.amount
+  };
+}
+var UNIQUE_GUARD_PK_PREFIX = "UNIQUE#";
+var UNIQUE_GUARD_SK_PREFIX = "VALUE#";
+function deriveUniqueGuards(fragment, unique) {
+  const seen = /* @__PURE__ */ new Set();
+  return unique.map((u) => {
+    if (seen.has(u.name)) {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares two uniqueness constraints named '${u.name}'. A uniqueness guard's marker-row key is built from its name, so the name must be unique within a lifecycle.`
+      );
+    }
+    seen.add(u.name);
+    return deriveOneUniqueGuard(fragment, u);
+  });
+}
+function uniquePathToInputField(fragment, effect, role, path) {
+  const match = INPUT_PATH_RE.exec(path);
+  if (match === null) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' binds a \`${role}\` value of its '${effect.name}' uniqueness constraint to ${JSON.stringify(path)}, which is not a \`$.input.<field>\` reference. A uniqueness guard's marker-row key is resolved from the mutation input, so each \`scope\` / \`fields\` value must be a \`$.input.<field>\` path (e.g. \`'$.input.userId'\`).`
+    );
+  }
+  return match[1];
+}
+function uniqueGuardKey(name, scopeFields, fieldFields, namespace) {
+  const token = (field) => namespace === "old" ? `{${OLD_VALUE_NAMESPACE}.${field}}` : `{${field}}`;
+  const pk = UNIQUE_GUARD_PK_PREFIX + name + scopeFields.map((f) => `#${token(f)}`).join("");
+  const sk = UNIQUE_GUARD_SK_PREFIX + fieldFields.map((f) => token(f)).join("#");
+  return { PK: pk, SK: sk };
+}
+function deriveOneUniqueGuard(fragment, effect) {
+  if (effect.fields.length === 0) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares the '${effect.name}' uniqueness constraint with no \`fields\`. A uniqueness guard must name at least one field whose value is unique within the scope.`
+    );
+  }
+  const scopeFields = effect.scope.map(
+    (p) => uniquePathToInputField(fragment, effect, "scope", p)
+  );
+  const fieldFields = effect.fields.map(
+    (p) => uniquePathToInputField(fragment, effect, "fields", p)
+  );
+  const newKey = uniqueGuardKey(effect.name, scopeFields, fieldFields, "input");
+  const putGuard = {
+    type: "Put",
+    tableName: tableNameOf(fragment),
+    entity: MARKER_ROW_ENTITY,
+    item: { PK: newKey.PK, SK: newKey.SK },
+    condition: { kind: "attributeNotExists", field: "PK" },
+    literalKey: true
+  };
+  if (fragment.intent === "create") {
+    return { name: effect.name, items: [putGuard] };
+  }
+  if (fragment.intent === "remove") {
+    return {
+      name: effect.name,
+      items: [
+        {
+          type: "Delete",
+          tableName: tableNameOf(fragment),
+          entity: MARKER_ROW_ENTITY,
+          keyCondition: { PK: newKey.PK, SK: newKey.SK },
+          literalKey: true
+        }
+      ]
+    };
+  }
+  const oldKey = uniqueGuardKey(effect.name, scopeFields, fieldFields, "old");
+  return {
+    name: effect.name,
+    items: [
+      {
+        type: "Delete",
+        tableName: tableNameOf(fragment),
+        entity: MARKER_ROW_ENTITY,
+        keyCondition: { PK: oldKey.PK, SK: oldKey.SK },
+        literalKey: true
+      },
+      putGuard
+    ]
+  };
+}
+function tableNameOf(fragment) {
+  const metadata = MetadataRegistry.get(
+    fragment.entity.modelClass
+  );
+  return metadata.tableName;
+}
+var OUTBOX_PK_PREFIX = "OUTBOX#";
+var OUTBOX_SK_PREFIX = "EVENT#";
+var OUTBOX_EVENT_NAME_ATTR = "eventName";
+var IDEMPOTENCY_PK_PREFIX = "IDEMP#";
+var IDEMPOTENCY_SK = "TOKEN";
+function emitPathToInputField(fragment, eventName, field, path) {
+  const inputMatch = INPUT_PATH_RE.exec(path);
+  if (inputMatch !== null) return inputMatch[1];
+  const entityMatch = ENTITY_FIELD_PATH_RE.exec(path);
+  if (entityMatch !== null) return entityMatch[1];
+  throw new Error(
+    `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' binds the '${field}' payload field of its '${eventName}' event to ${JSON.stringify(path)}, which is not a \`$.input.<field>\` (mutation input) or \`$.entity.<field>\` (the written entity) reference. An outbox event payload must bind declaratively from the input / written entity (no arbitrary procedure), so each value must be a \`$.input.<field>\` / \`$.entity.<field>\` path (e.g. \`'$.input.userId'\`).`
+  );
+}
+function deriveOutboxEvents(fragment, emits) {
+  if (fragment.intent !== "create") {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares an outbox event, but \`emits\` is supported only on a 'create' lifecycle. The outbox row is keyed deterministically by (event name + entity primary key) with no per-emission discriminator, so a 'create' (guarded one-per-row by the entity's \`attribute_not_exists\`) gets exactly one event row; an 'update' would overwrite a prior, possibly-undrained, outbox row (losing the earlier event) and a 'remove' would race the entity's tombstone. An update / delete event stream is a separate concern (a dedicated append-keyed write), out of scope for the derived outbox.`
+    );
+  }
+  const keyFields = primaryKeyFields(fragment);
+  const seen = /* @__PURE__ */ new Set();
+  return emits.map((emit) => {
+    if (emit.name.includes("{") || emit.name.includes("}")) {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares an outbox event named ${JSON.stringify(emit.name)}, which contains a '{' / '}'. The event name is spliced into the outbox row's key template (\`OUTBOX#<name>#\u2026\`), so a brace would forge a spurious \`{token}\` placeholder. Use a brace-free event name.`
+      );
+    }
+    if (seen.has(emit.name)) {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares two events named '${emit.name}'. An outbox row's marker key is built from the event name, so the name must be unique within a lifecycle.`
+      );
+    }
+    seen.add(emit.name);
+    return deriveOneOutboxEvent(fragment, emit, keyFields);
+  });
+}
+function deriveOneOutboxEvent(fragment, emit, keyFields) {
+  const keySegments = keyFields.map((f) => `#{${f}}`).join("");
+  const pk = OUTBOX_PK_PREFIX + emit.name + keySegments;
+  const sk = OUTBOX_SK_PREFIX + keyFields.map((f) => `{${f}}`).join("#");
+  const item = {
+    PK: pk,
+    SK: sk,
+    // The event name is stored verbatim so the `newImage` carries it for routing.
+    [OUTBOX_EVENT_NAME_ATTR]: emit.name
+  };
+  for (const [field, source] of Object.entries(emit.payload)) {
+    const inputField = emitPathToInputField(fragment, emit.name, field, source);
+    item[field] = `{${inputField}}`;
+  }
+  return {
+    name: emit.name,
+    items: [
+      {
+        type: "Put",
+        tableName: tableNameOf(fragment),
+        entity: MARKER_ROW_ENTITY,
+        item,
+        // No `attribute_not_exists`: the outbox row is keyed by the entity key, which
+        // the entity `Put`'s own create guard already makes unique — the event is
+        // appended atomically with the row it announces.
+        literalKey: true
+      }
+    ]
+  };
+}
+function deriveIdempotencyGuard(fragment, effect) {
+  const match = INPUT_PATH_RE.exec(effect.token);
+  if (match === null) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' declares an idempotency guard keyed on ${JSON.stringify(effect.token)}, which is not a \`$.input.<field>\` reference. The client token is a mutation input field, so \`w.idempotentBy(...)\` must name a \`$.input.<field>\` path (e.g. \`'$.input.requestId'\`).`
+    );
+  }
+  const tokenField = match[1];
+  return {
+    tokenField,
+    items: [
+      {
+        type: "Put",
+        tableName: tableNameOf(fragment),
+        entity: MARKER_ROW_ENTITY,
+        item: { PK: `${IDEMPOTENCY_PK_PREFIX}{${tokenField}}`, SK: IDEMPOTENCY_SK },
+        // The claim guard: the token row must not already exist. A same-token replay
+        // targets the SAME row and fails, rolling the whole tx back (no double effect).
+        condition: { kind: "attributeNotExists", field: "PK" },
+        literalKey: true
+      }
+    ]
+  };
+}
+function resolveLifecycle(fragment) {
+  const writes = fragment.use ?? getEntityWrites(fragment.entity.modelClass);
+  if (writes === void 0) return void 0;
+  const phase = lifecyclePhaseForIntent(fragment.intent);
+  const contract = writes[phase];
+  if (contract === void 0) return void 0;
+  if (!isLifecycleContract(contract)) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' lifecycle of the save contract adopted by the fragment on '${fragment.entity.name}' is not a \`w.lifecycle({...})\`.`
+    );
+  }
+  return contract;
+}
+function primaryKeyFields(fragment) {
+  const metadata = MetadataRegistry.get(
+    fragment.entity.modelClass
+  );
+  if (!metadata.primaryKey) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment targets '${fragment.entity.name}', which has no primary key. A mutation fragment writes / identifies a row by its primary key, so the target model must declare one.`
+    );
+  }
+  return metadata.primaryKey.inputFieldNames;
+}
+function renderInputLeaf(leaf, isKeyFieldInPut, consumerIndex, consumerField, resolveEntityRef) {
+  if (isMutationInputRef(leaf)) {
+    return isKeyFieldInPut ? mintContractKeyFieldRef(leaf.field) : mintContractParamRef(leaf.field);
+  }
+  const entityRef3 = parseEntityRef(leaf);
+  if (entityRef3 !== void 0) {
+    if (resolveEntityRef === null) {
+      throw new Error(
+        `mutation: the cross-fragment reference '${entityRef3.path}' is only valid in a MULTI-fragment mutation \u2014 it names a value produced by an earlier fragment, but this mutation has a single fragment (there is no fragment #${entityRef3.fragmentIndex} to read from). Bind '${consumerField}' to a \`$.field\` input reference or a literal instead.`
+      );
+    }
+    return resolveEntityRef(entityRef3, consumerIndex, consumerField);
+  }
+  return leaf;
+}
+function compileFragment(fragment, index = 0, resolveEntityRef = null) {
+  const keyFields = primaryKeyFields(fragment);
+  const keyFieldSet = new Set(keyFields);
+  const operation = INTENT_OPERATION[fragment.intent];
+  const lifecycle = resolveLifecycle(fragment);
+  for (const field of keyFields) {
+    if (!(field in fragment.input)) {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' must bind the primary-key field '${field}' in its \`input\` (it identifies the row), e.g. \`{ ${field}: $.${field}, \u2026 }\`.`
+      );
+    }
+  }
+  let op;
+  if (fragment.intent === "create") {
+    const item = {};
+    for (const [field, leaf] of Object.entries(fragment.input)) {
+      item[field] = renderInputLeaf(
+        leaf,
+        keyFieldSet.has(field),
+        index,
+        field,
+        resolveEntityRef
+      );
+    }
+    op = {
+      __isContractMethodOp: true,
+      entity: fragment.entity,
+      operation,
+      keys: wholeKeysSentinel(),
+      // a `put` derives identity from the item.
+      item,
+      // The base `create` op guards against clobbering an existing row, exactly as
+      // the proposal specifies (create → Put `attribute_not_exists(PK)`).
+      condition: { notExists: true }
+    };
+  } else {
+    const changes = {};
+    for (const [field, leaf] of Object.entries(fragment.input)) {
+      if (keyFieldSet.has(field)) continue;
+      changes[field] = renderInputLeaf(leaf, false, index, field, resolveEntityRef);
+    }
+    op = {
+      __isContractMethodOp: true,
+      entity: fragment.entity,
+      operation,
+      keys: wholeKeysSentinel(),
+      keyFields,
+      ...fragment.intent === "update" ? { changes } : {}
+    };
+  }
+  const conditionChecks = lifecycle?.effects.requires !== void 0 && lifecycle.effects.requires.length > 0 ? deriveConditionChecks(fragment, lifecycle.effects.requires) : void 0;
+  const edgeWrites2 = lifecycle?.effects.edges !== void 0 && lifecycle.effects.edges.length > 0 ? deriveEdgeWrites(fragment, lifecycle.effects.edges, INTENT_EDGE_LIFECYCLE[fragment.intent]) : void 0;
+  const derivedUpdates = lifecycle?.effects.derive !== void 0 && lifecycle.effects.derive.length > 0 ? deriveUpdates(fragment, lifecycle.effects.derive) : void 0;
+  const uniqueGuards = lifecycle?.effects.unique !== void 0 && lifecycle.effects.unique.length > 0 ? deriveUniqueGuards(fragment, lifecycle.effects.unique) : void 0;
+  const outboxEvents = lifecycle?.effects.emits !== void 0 && lifecycle.effects.emits.length > 0 ? deriveOutboxEvents(fragment, lifecycle.effects.emits) : void 0;
+  const idempotencyGuard = lifecycle?.effects.idempotency !== void 0 ? deriveIdempotencyGuard(fragment, lifecycle.effects.idempotency) : void 0;
+  return {
+    op,
+    keyFields,
+    ...lifecycle !== void 0 ? { effects: lifecycle.effects } : {},
+    ...conditionChecks !== void 0 ? { conditionChecks } : {},
+    ...edgeWrites2 !== void 0 ? { edgeWrites: edgeWrites2 } : {},
+    ...derivedUpdates !== void 0 ? { derivedUpdates } : {},
+    ...uniqueGuards !== void 0 ? { uniqueGuards } : {},
+    ...outboxEvents !== void 0 ? { outboxEvents } : {},
+    ...idempotencyGuard !== void 0 ? { idempotencyGuard } : {}
+  };
+}
+function compileSingleFragmentPlan(plan) {
+  if (!isCommandPlan(plan)) {
+    throw new Error(
+      "mutation compiler: expected a `mutation(...)` CommandPlan, but received a non-plan value."
+    );
+  }
+  if (plan.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).`
+    );
+  }
+  return compileFragment(plan.fragments[0], 0, null);
+}
+var MAX_TRANSACT_COMPOSE_ITEMS = 25;
+function keySignature(fragment) {
+  const op = fragment.op;
+  const parts = [];
+  if (op.operation === "put") {
+    const item = op.item ?? {};
+    for (const field of [...fragment.keyFields].sort()) {
+      const leaf = item[field];
+      parts.push(`${field}=${keyLeafToken(leaf)}`);
+    }
+  } else {
+    for (const field of [...fragment.keyFields].sort()) {
+      parts.push(`${field}=input:${field}`);
+    }
+  }
+  return `${op.entity.name}#${parts.join("&")}`;
+}
+function keyLeafToken(leaf) {
+  if (isContractKeyFieldRef(leaf)) return `input:${leaf.field}`;
+  if (isContractParamRef(leaf)) return `input:${leaf.field}`;
+  return `literal:${JSON.stringify(leaf)}`;
+}
+function compileMutationPlan(plan) {
+  if (!isCommandPlan(plan)) {
+    throw new Error(
+      "mutation compiler: expected a `mutation(...)` CommandPlan, but received a non-plan value."
+    );
+  }
+  const fragments = plan.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.`
+        );
+      }
+      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\`.`
+        );
+      }
+      return resolved;
+    };
+    compiled.push(compileFragment(fragments[i], i, resolveEntityRef));
+  }
+  const byKey = /* @__PURE__ */ new Map();
+  for (let i = 0; i < compiled.length; i++) {
+    const sig = keySignature(compiled[i]);
+    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.`
+      );
+    }
+    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}.`
+    );
+  }
+  return { name: plan.name, fragments: compiled };
+}
+function producedFieldLeaf(producer, field) {
+  const op = producer.op;
+  if (op.operation === "put") {
+    const item = op.item ?? {};
+    if (field in item) {
+      const leaf = item[field];
+      return isContractKeyFieldRef(leaf) ? mintContractParamRef(leaf.field) : leaf;
+    }
+    return void 0;
+  }
+  if (op.operation === "update") {
+    const changes = op.changes ?? {};
+    if (field in changes) return changes[field];
+  }
+  if (producer.keyFields.includes(field)) return mintContractParamRef(field);
+  return void 0;
+}
+function describeKey(fragment) {
+  return `[${[...fragment.keyFields].sort().join(", ")}]`;
+}
+
+// src/spec/guard.ts
+function conditionInputToSpec(condition, context, renderLeaf) {
+  if (condition === void 0 || condition === null) return void 0;
+  if (typeof condition !== "object") {
+    throw new Error(
+      `${context}: write condition must be an object (\`{ notExists: true }\`, \`{ attributeExists: '<field>' }\`, \`{ attributeNotExists: '<field>' }\`, or field equality).`
+    );
+  }
+  const obj = condition;
+  if (obj.notExists === true) return { kind: "notExists" };
+  if ("attributeExists" in obj) {
+    if (typeof obj.attributeExists !== "string" || obj.attributeExists.length === 0) {
+      throw new Error(
+        `${context}: \`attributeExists\` must name a non-empty attribute field.`
+      );
+    }
+    return { kind: "attributeExists", field: obj.attributeExists };
+  }
+  if ("attributeNotExists" in obj) {
+    if (typeof obj.attributeNotExists !== "string" || obj.attributeNotExists.length === 0) {
+      throw new Error(
+        `${context}: \`attributeNotExists\` must name a non-empty attribute field.`
+      );
+    }
+    return { kind: "attributeNotExists", field: obj.attributeNotExists };
+  }
+  const fields = {};
+  for (const key of Object.keys(obj).sort()) {
+    fields[key] = renderLeaf(key, obj[key]);
+  }
+  return { kind: "equals", fields };
+}
+function assertSupportedCondition(commandName, condition) {
+  if (condition.kind === "notExists") return;
+  if (condition.kind === "attributeExists" || condition.kind === "attributeNotExists") {
+    if (typeof condition.field !== "string" || condition.field.length === 0) {
+      throw new Error(
+        `Command '${commandName}' has an ${condition.kind} write condition with no attribute field. The Python bridge requires a non-empty field name.`
+      );
+    }
+    return;
+  }
+  if (condition.kind === "equals") {
+    const entries = Object.entries(condition.fields);
+    if (entries.length === 0) {
+      throw new Error(
+        `Command '${commandName}' has an empty equality write condition. The Python bridge supports '{ notExists }' or non-empty field equality conditions only.`
+      );
+    }
+    for (const [field, value] of entries) {
+      if (typeof value !== "string") {
+        throw new Error(
+          `Command '${commandName}' write condition on '${field}' must be a template string value; the Python bridge supports equality on param/literal values only.`
+        );
+      }
+    }
+    return;
+  }
+  throw new Error(
+    `Command '${commandName}' has an unsupported write condition. The Python bridge supports '{ notExists }' or field equality only.`
+  );
+}
+function assertJsonSerializable(value, path = "$") {
+  if (value === null) return;
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return;
+    case "number":
+      if (!Number.isFinite(value)) {
+        throw new Error(
+          `Bridge spec is not JSON-serializable: non-finite number at ${path}.`
+        );
+      }
+      return;
+    case "object":
+      break;
+    default:
+      throw new Error(
+        `Bridge spec is not JSON-serializable: '${typeof value}' at ${path}.`
+      );
+  }
+  if (Array.isArray(value)) {
+    value.forEach((v, i) => assertJsonSerializable(v, `${path}[${i}]`));
+    return;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) {
+    throw new Error(
+      `Bridge spec is not JSON-serializable: non-plain object (${value.constructor?.name ?? "unknown"}) at ${path}.`
+    );
+  }
+  for (const [k, v] of Object.entries(value)) {
+    if (v === void 0) {
+      throw new Error(
+        `Bridge spec is not JSON-serializable: 'undefined' value at ${path}.${k}.`
+      );
+    }
+    assertJsonSerializable(v, `${path}.${k}`);
+  }
+}
+function assertBundleSerializable(bundle) {
+  assertJsonSerializable(bundle.manifest, "$.manifest");
+  assertJsonSerializable(bundle.operations, "$.operations");
+}
+
+// src/define/transaction.ts
+var TX_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:txref");
+function isTransactionRef(value) {
+  return typeof value === "object" && value !== null && value[TX_REF_BRAND] === true;
+}
+var MARKER_TAGS = [
+  // pass 0: short, begins with 'A'.
+  "Axqv",
+  // pass 1: long, begins with 'Z'. The two tags share NO common prefix and NO
+  // common substring of length >= 2 (their alphabets are disjoint), and differ
+  // in length, so any fragment-extracting / length-dependent transform
+  // (`slice(0,n)`, `[i]`, `charAt`, `padStart`, `padEnd`) yields *different*
+  // fragments across the two passes -- the differential check then rejects it.
+  // (Convergence-to-constant escapes that even disjoint markers cannot separate
+  // -- `slice(0,0)` -> '' in both passes, `includes('x')` -> a constant boolean
+  // -- are caught instead by the per-access coercion ledger; see
+  // {@link makeFieldRef} and {@link defineTransaction}.)
+  "Zmnoprstuwy0123456789WIDEMARKERBODYFILLERZ"
+];
+var MARKER_PASS_COUNT = MARKER_TAGS.length;
+function markerValue(pass, field) {
+  const tag = MARKER_TAGS[pass];
+  return `${tag}::${field}::${tag}`;
+}
+function makeValueSentinel(fields, tokenFor, originFor, markerFor, containerOrigin, onAccess, onCoerce) {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(_t, key) {
+      if (typeof key === "symbol") {
+        if (key === Symbol.iterator || key === Symbol.asyncIterator || key === Symbol.toStringTag || typeof Symbol.for === "function" && (key === /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom") || key.description === "nodejs.util.inspect.custom")) {
+          return void 0;
+        }
+        throw new Error(
+          `defineTransaction: unsupported symbol access on ${containerOrigin}. Only declarative field references are allowed; any JS transform / branching / coercion on a parameter is not representable as a declarative transaction template.`
+        );
+      }
+      if (!fields.has(key)) {
+        throw new Error(
+          `defineTransaction: ${containerOrigin} has no field '${key}'. Reference only declared fields; arbitrary property access (or any JS transform / branching on a parameter) is not representable as a declarative transaction template.`
+        );
+      }
+      onAccess(key);
+      let ref = cache.get(key);
+      if (!ref) {
+        ref = makeFieldRef(
+          tokenFor(key),
+          originFor(key),
+          markerFor(key),
+          () => onCoerce(key)
+        );
+        cache.set(key, ref);
+      }
+      return ref;
+    },
+    set() {
+      throw new Error(
+        `defineTransaction: cannot assign to a field of ${containerOrigin}.`
+      );
+    },
+    defineProperty() {
+      throw new Error(
+        `defineTransaction: cannot define a property on ${containerOrigin}.`
+      );
+    },
+    deleteProperty() {
+      throw new Error(
+        `defineTransaction: cannot delete a field of ${containerOrigin}.`
+      );
+    }
+  });
+}
+function makeFieldRef(token, origin, marker, onCoerce) {
+  const target = /* @__PURE__ */ Object.create(null);
+  const proxy = new Proxy(target, {
+    get(_t, key) {
+      if (key === TX_REF_BRAND) return true;
+      if (key === "token") return token;
+      if (key === "origin") return origin;
+      if (key === Symbol.toPrimitive) {
+        return (hint) => {
+          onCoerce();
+          return hint === "number" ? NaN : marker;
+        };
+      }
+      if (key === "toString" || key === Symbol.toStringTag) {
+        return () => {
+          onCoerce();
+          return marker;
+        };
+      }
+      if (key === "valueOf") {
+        return () => {
+          onCoerce();
+          return NaN;
+        };
+      }
+      if (key === Symbol.iterator || key === Symbol.asyncIterator || key === "then" || key === "constructor" || key === "prototype" || typeof key === "symbol" && typeof Symbol.for === "function" && (key === /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom") || key.description === "nodejs.util.inspect.custom")) {
+        return void 0;
+      }
+      const name = typeof key === "symbol" ? key.toString() : String(key);
+      throw new Error(
+        `defineTransaction: unsupported operation '${name}' on ${origin}. The static planner (Python bridge) only supports direct field references (\`p.field\` / \`el.field\`) or concrete literals at value positions; any string transform, property access (e.g. \`.length\`, \`[i]\`, \`.toUpperCase()\`), arithmetic, or value branching on a parameter is not representable as a declarative transaction template.`
+      );
+    },
+    set() {
+      throw new Error(`defineTransaction: cannot assign on ${origin}.`);
+    },
+    defineProperty() {
+      throw new Error(`defineTransaction: cannot define a property on ${origin}.`);
+    },
+    deleteProperty() {
+      throw new Error(`defineTransaction: cannot delete on ${origin}.`);
+    }
+  });
+  return proxy;
+}
+var when = {
+  eq(left, right) {
+    assertRef(left, "when.eq");
+    return { op: "eq", left, right };
+  },
+  ne(left, right) {
+    assertRef(left, "when.ne");
+    return { op: "ne", left, right };
+  }
+};
+function assertRef(value, context) {
+  if (!isTransactionRef(value)) {
+    throw new Error(
+      `defineTransaction: ${context} expects a field reference (e.g. \`p.status\` or an element field) on its left-hand side.`
+    );
+  }
+}
+function entityRef2(model) {
+  const modelClass = resolveModelClass(model);
+  return { name: modelClass.name, modelClass };
+}
+function descriptorOf(p) {
+  if (p.kind === "array") {
+    const element = {};
+    for (const [field, fieldParam] of Object.entries(p.element ?? {})) {
+      element[field] = descriptorOf(fieldParam);
+    }
+    return { kind: "array", required: true, element };
+  }
+  return p.literals === void 0 ? { kind: p.kind, required: true } : { kind: p.kind, literals: p.literals, required: true };
+}
+function runBuildPass(params, build, scalarFields, arrayParams, pass, accessed, coerced) {
+  const noteAccess = (token, origin) => {
+    if (!accessed.has(token)) accessed.set(token, { token, origin });
+  };
+  const noteCoerce = (token, origin) => {
+    if (!coerced.has(token)) coerced.set(token, { token, origin });
+  };
+  const scalarSentinel = makeValueSentinel(
+    scalarFields,
+    (f) => `{${f}}`,
+    (f) => `param '${f}'`,
+    (f) => markerValue(pass, f),
+    "params",
+    (f) => noteAccess(`{${f}}`, `param '${f}'`),
+    (f) => noteCoerce(`{${f}}`, `param '${f}'`)
+  );
+  const pProxy = new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(_t, key) {
+      if (typeof key === "symbol") {
+        if (key === Symbol.iterator || key === Symbol.asyncIterator || key === Symbol.toStringTag || typeof Symbol.for === "function" && (key === /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom") || key.description === "nodejs.util.inspect.custom")) {
+          return void 0;
+        }
+        throw new Error("defineTransaction: unsupported symbol access on params.");
+      }
+      if (arrayParams.has(key)) return params[key];
+      if (scalarFields.has(key)) return scalarSentinel[key];
+      throw new Error(
+        `defineTransaction: unknown parameter '${key}'. Declare it in the params map passed to defineTransaction.`
+      );
+    }
+  });
+  const instructions = [];
+  let currentBody = instructions;
+  let insideForEach = false;
+  const recordWrite = (instr) => {
+    currentBody.push(instr);
+  };
+  const recorder3 = {
+    put(model, item, options) {
+      recordWrite({
+        kind: "write",
+        operation: "put",
+        entity: entityRef2(model),
+        item,
+        ...options?.condition !== void 0 ? { condition: options.condition } : {},
+        ...options?.when !== void 0 ? { when: options.when } : {}
+      });
+    },
+    update(model, key, changes, options) {
+      recordWrite({
+        kind: "write",
+        operation: "update",
+        entity: entityRef2(model),
+        key,
+        changes,
+        ...options?.condition !== void 0 ? { condition: options.condition } : {},
+        ...options?.when !== void 0 ? { when: options.when } : {}
+      });
+    },
+    delete(model, key, options) {
+      recordWrite({
+        kind: "write",
+        operation: "delete",
+        entity: entityRef2(model),
+        key,
+        ...options?.condition !== void 0 ? { condition: options.condition } : {},
+        ...options?.when !== void 0 ? { when: options.when } : {}
+      });
+    },
+    conditionCheck(model, key, options) {
+      if (options?.condition === void 0 || options.condition === null) {
+        throw new Error(
+          "defineTransaction: tx.conditionCheck requires a `condition` (the read-only assertion it makes); e.g. `{ condition: { attributeExists: 'PK' } }`."
+        );
+      }
+      recordWrite({
+        kind: "write",
+        operation: "conditionCheck",
+        entity: entityRef2(model),
+        key,
+        condition: options.condition,
+        ...options.when !== void 0 ? { when: options.when } : {}
+      });
+    },
+    forEach(source, body, options) {
+      if (insideForEach) {
+        throw new Error(
+          "defineTransaction: nested forEach is not supported; flatten the loop."
+        );
+      }
+      if (!isParam(source) || source.kind !== "array") {
+        throw new Error(
+          "defineTransaction: forEach source must be a `param.array(...)` parameter accessed via `p.<name>`."
+        );
+      }
+      const arrayParam = source;
+      const sourceName = arrayParams.size ? Object.keys(params).find((k) => params[k] === arrayParam) : void 0;
+      if (sourceName === void 0) {
+        throw new Error(
+          "defineTransaction: forEach source is not a declared array param."
+        );
+      }
+      const elementFields = new Set(Object.keys(arrayParam.element ?? {}));
+      const elementProxy = makeValueSentinel(
+        elementFields,
+        (f) => `{item.${f}}`,
+        (f) => `element field '${f}' of '${sourceName}'`,
+        (f) => markerValue(pass, `item.${f}`),
+        `element of '${sourceName}'`,
+        (f) => noteAccess(`{item.${f}}`, `element field '${f}' of '${sourceName}'`),
+        (f) => noteCoerce(`{item.${f}}`, `element field '${f}' of '${sourceName}'`)
+      );
+      const block = {
+        kind: "forEach",
+        source: sourceName,
+        ...options?.when !== void 0 ? { when: options.when } : {},
+        body: []
+      };
+      const prevBody = currentBody;
+      currentBody = block.body;
+      insideForEach = true;
+      try {
+        body(elementProxy);
+      } finally {
+        insideForEach = false;
+        currentBody = prevBody;
+      }
+      currentBody.push(block);
+    }
+  };
+  build(recorder3, pProxy);
+  return instructions;
+}
+function defineTransaction(params, build) {
+  const descriptors = {};
+  for (const [name, value] of Object.entries(params)) {
+    if (!isParam(value)) {
+      throw new Error(
+        `defineTransaction: param '${name}' is not a param.* placeholder.`
+      );
+    }
+    descriptors[name] = descriptorOf(value);
+  }
+  const scalarFields = new Set(
+    Object.keys(params).filter((k) => params[k].kind !== "array")
+  );
+  const arrayParams = new Set(
+    Object.keys(params).filter((k) => params[k].kind === "array")
+  );
+  const accessed = /* @__PURE__ */ new Map();
+  const coerced = /* @__PURE__ */ new Map();
+  const passes = [];
+  for (let pass = 0; pass < MARKER_PASS_COUNT; pass++) {
+    passes.push(
+      runBuildPass(
+        params,
+        build,
+        scalarFields,
+        arrayParams,
+        pass,
+        accessed,
+        coerced
+      )
+    );
+  }
+  if (coerced.size > 0) {
+    const info = [...coerced.values()][0];
+    throw new Error(
+      `defineTransaction: ${info.origin} is coerced to a primitive (e.g. via \`String(${info.origin.includes("element") ? "el" : "p"}.x)\`, a template literal \`\${\u2026}\`, string concatenation, or a comparison) and then consumed by a transform or branch \u2014 for example \`String(p.x).slice(0, n)\`, \`String(p.x)[0]\`, \`String(p.x).includes('\u2026')\`, or \`\${p.x}-suffix\`. At a value position the static planner (Python bridge) only supports a *direct* field reference (stored without coercion) or a concrete literal; a coerced / transformed parameter is not representable as a declarative transaction template, and (because the transform may converge to a constant or a shared marker fragment) could otherwise be silently emitted as a wrong spec. Reference the field directly (\`p.x\` / \`el.x\`) or use a literal.`
+    );
+  }
+  const surfaced = /* @__PURE__ */ new Set();
+  verifyInstructions(passes, surfaced);
+  for (const [token, info] of accessed) {
+    if (!surfaced.has(token)) {
+      throw new Error(
+        `defineTransaction: ${info.origin} is accessed but never appears as a field reference in the recorded transaction. This happens when a parameter is consumed by a value branch (e.g. \`p.role === 'admin' ? 'A' : 'B'\`) or a string transform (e.g. \`String(p.role).toUpperCase()\`) instead of being referenced directly. The static planner (Python bridge) only supports direct field references or concrete literals at value positions; branching or transforming a parameter is not representable as a declarative transaction template.`
+      );
+    }
+  }
+  return {
+    __isTransactionDefinition: true,
+    params: descriptors,
+    instructions: passes[0]
+  };
+}
+function verifyInstructions(passes, surfaced) {
+  const first = passes[0];
+  for (let i = 0; i < first.length; i++) {
+    const instrs = passes.map((p) => p[i]);
+    const kind = first[i].kind;
+    if (instrs.some((x) => x.kind !== kind)) {
+      throw new Error(
+        "defineTransaction: build is not deterministic across evaluation (instruction shape diverged between passes). The callback must be a pure, declarative description of the writes."
+      );
+    }
+    if (kind === "write") {
+      verifyWrite(instrs, surfaced);
+    } else {
+      const blocks = instrs;
+      verifyWhen(
+        blocks.map((b) => b.when),
+        surfaced,
+        `forEach '${blocks[0].source}' when`
+      );
+      verifyInstructions(
+        blocks.map((b) => b.body),
+        surfaced
+      );
+    }
+  }
+}
+function verifyWrite(instrs, surfaced) {
+  const op = instrs[0].operation;
+  if (instrs.some((x) => x.operation !== op)) {
+    throw new Error(
+      "defineTransaction: write operation diverged between evaluation passes; the callback must be a pure, declarative description of the writes."
+    );
+  }
+  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(
+    instrs.map((x) => x.condition),
+    surfaced,
+    `${op} condition`
+  );
+  verifyWhen(instrs.map((x) => x.when), surfaced, `${op} when`);
+}
+function verifyRecord2(records, surfaced, context) {
+  const present = records.filter((r) => r !== void 0);
+  if (present.length === 0) return;
+  if (present.length !== records.length) {
+    throw new Error(
+      `defineTransaction: ${context} present in some evaluation passes but not others; the callback must be a pure, declarative description.`
+    );
+  }
+  const keys = Object.keys(present[0]).sort();
+  for (const r of present) {
+    const k = Object.keys(r).sort();
+    if (k.length !== keys.length || k.some((x, i) => x !== keys[i])) {
+      throw new Error(
+        `defineTransaction: ${context} field set diverged between evaluation passes; the callback must be a pure, declarative description.`
+      );
+    }
+  }
+  for (const field of keys) {
+    verifyLeaf2(
+      present.map((r) => r[field]),
+      surfaced,
+      `${context} field '${field}'`
+    );
+  }
+}
+function verifyWhen(whens, surfaced, context) {
+  const present = whens.filter((w) => w !== void 0);
+  if (present.length === 0) return;
+  if (present.length !== whens.length) {
+    throw new Error(
+      `defineTransaction: ${context} present in some evaluation passes but not others; the callback must be a pure, declarative description.`
+    );
+  }
+  for (const w of present) {
+    if (isTransactionRef(w.left)) surfaced.add(w.left.token);
+  }
+  verifyLeaf2(present.map((w) => w.right), surfaced, `${context} right-hand value`);
+}
+function verifyLeaf2(values, surfaced, context) {
+  const refTokens = values.map((v) => isTransactionRef(v) ? v.token : void 0);
+  const anyRef = refTokens.some((t) => t !== void 0);
+  if (anyRef) {
+    if (refTokens.some((t) => t === void 0)) {
+      throw new Error(
+        `defineTransaction: ${context} is a field reference in some evaluation passes but a transformed value in others \u2014 a coercion/transform escape (e.g. \`String(p.x).toUpperCase()\`) was applied. Use a direct field reference or a concrete literal.`
+      );
+    }
+    const token = refTokens[0];
+    if (refTokens.some((t) => t !== token)) {
+      throw new Error(
+        `defineTransaction: ${context} resolves to different field references across evaluation passes \u2014 the value is not a stable, declarative reference.`
+      );
+    }
+    surfaced.add(token);
+    return;
+  }
+  const norm = values.map(normalizeLiteral2);
+  for (let i = 1; i < norm.length; i++) {
+    if (norm[i] !== norm[0]) {
+      throw new Error(
+        `defineTransaction: ${context} is not a stable concrete literal \u2014 evaluating the callback twice produced different values ('${norm[0]}' vs '${norm[i]}'). This means a parameter was coerced or transformed into the value (e.g. \`String(p.x).toUpperCase()\`, \`\${p.x}-suffix\`, or arithmetic). The static planner (Python bridge) only supports a direct field reference or a concrete literal at a value position.`
+      );
+    }
+  }
+}
+function normalizeLiteral2(value) {
+  if (value === null) return "t:null";
+  if (value instanceof Date) return `t:date:${value.toISOString()}`;
+  const t = typeof value;
+  if (t === "string") return `t:s:${value}`;
+  if (t === "boolean") return `t:b:${String(value)}`;
+  if (t === "number") {
+    if (Number.isNaN(value)) {
+      throw new Error(
+        "defineTransaction: a value leaf coerced to NaN, which means arithmetic was performed on a parameter. Only direct field references or concrete literals are allowed at value positions."
+      );
+    }
+    return `t:n:${String(value)}`;
+  }
+  throw new Error(
+    `defineTransaction: a value leaf has unsupported type '${t}'. Only a direct field reference (\`p.field\` / \`el.field\`) or a concrete literal (string / number / boolean / Date) is allowed at a value position.`
+  );
+}
+function defineTransactions(definitions) {
+  for (const [name, def] of Object.entries(definitions)) {
+    if (def === null || typeof def !== "object" || def.__isTransactionDefinition !== true) {
+      throw new Error(
+        `defineTransactions: '${name}' is not a transaction definition. Use defineTransaction(...) to build entries.`
+      );
+    }
+  }
+  return definitions;
+}
+
+// src/spec/transaction.ts
+function paramSpec(d) {
+  if (d.kind === "array") {
+    const element = {};
+    for (const field of Object.keys(d.element ?? {}).sort()) {
+      element[field] = paramSpec(d.element[field]);
+    }
+    return { type: "array", required: d.required, element };
+  }
+  return d.literals === void 0 ? { type: d.kind, required: d.required } : {
+    type: d.kind,
+    required: d.required,
+    literals: d.literals
+  };
+}
+function transactionParamSpecs(params) {
+  const out = {};
+  for (const name of Object.keys(params).sort()) {
+    out[name] = paramSpec(params[name]);
+  }
+  return out;
+}
+function leafTemplate(value, context) {
+  if (isTransactionRef(value)) return value.token;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  throw new Error(
+    `defineTransaction: ${context} must be a field reference (from \`p\` or a forEach element) or a concrete literal; got ${typeof value}.`
+  );
+}
+function templateRecord2(structure, context) {
+  const out = {};
+  for (const field of Object.keys(structure).sort()) {
+    out[field] = leafTemplate(structure[field], `${context} field '${field}'`);
+  }
+  return out;
+}
+function tokenName(token) {
+  return token.startsWith("{") && token.endsWith("}") ? token.slice(1, -1) : token;
+}
+function keyConditionTemplate2(metadata, keyStructure, context) {
+  if (!metadata.primaryKey) {
+    throw new Error(`defineTransaction: ${context} entity has no primary key.`);
+  }
+  const nameByField = /* @__PURE__ */ new Map();
+  for (const [field, value] of Object.entries(keyStructure)) {
+    if (!isTransactionRef(value)) {
+      throw new Error(
+        `defineTransaction: ${context} key field '${field}' must be a field reference (from \`p\` or a forEach element); a transaction key may not be a computed or literal value.`
+      );
+    }
+    nameByField.set(field, tokenName(value.token));
+  }
+  const present = new Set(Object.keys(keyStructure));
+  const { pk, sk } = evaluateKey(
+    metadata.primaryKey.segmented,
+    "param",
+    present,
+    (f) => nameByField.get(f) ?? f
+  );
+  const out = { PK: pk };
+  if (sk !== void 0) out.SK = sk;
+  return out;
+}
+function whenSpec(when2) {
+  const left = when2.left.token;
+  const right = leafTemplate(when2.right, "when right-hand value");
+  return { op: when2.op, left, right };
+}
+function conditionSpec(condition, commandName) {
+  const spec = conditionInputToSpec(
+    condition,
+    commandName,
+    (field, value) => leafTemplate(value, `condition field '${field}'`)
+  );
+  if (spec) assertSupportedCondition(commandName, spec);
+  return spec;
+}
+var ITEM_TYPE = {
+  put: "Put",
+  update: "Update",
+  delete: "Delete",
+  conditionCheck: "ConditionCheck"
+};
+function buildWriteItem(instr, forEachSource, txName) {
+  const metadata = MetadataRegistry.get(instr.entity.modelClass);
+  const tableName = TableMapping.resolve(metadata.tableName);
+  const entity = instr.entity.name;
+  const condition = conditionSpec(instr.condition, `${txName} (${entity})`);
+  const when2 = instr.when ? whenSpec(instr.when) : void 0;
+  const base = {
+    type: ITEM_TYPE[instr.operation],
+    tableName,
+    entity,
+    ...condition ? { condition } : {},
+    ...when2 ? { when: when2 } : {},
+    ...forEachSource ? { forEach: { source: forEachSource } } : {}
+  };
+  if (instr.operation === "put") {
+    return {
+      ...base,
+      item: templateRecord2(instr.item ?? {}, `${txName} put`)
+    };
+  }
+  if (instr.operation === "delete") {
+    return {
+      ...base,
+      keyCondition: keyConditionTemplate2(metadata, instr.key ?? {}, `${txName} delete`)
+    };
+  }
+  if (instr.operation === "conditionCheck") {
+    if (!condition) {
+      throw new Error(
+        `defineTransaction '${txName}': a ConditionCheck on '${entity}' requires a condition (the read-only assertion it makes).`
+      );
+    }
+    return {
+      ...base,
+      keyCondition: keyConditionTemplate2(
+        metadata,
+        instr.key ?? {},
+        `${txName} conditionCheck`
+      )
+    };
+  }
+  return {
+    ...base,
+    keyCondition: keyConditionTemplate2(metadata, instr.key ?? {}, `${txName} update`),
+    changes: templateRecord2(instr.changes ?? {}, `${txName} update changes`)
+  };
+}
+function buildTransactionSpec(txName, def) {
+  const items = [];
+  let hasForEach = false;
+  for (const instr of def.instructions) {
+    if (instr.kind === "write") {
+      items.push(buildWriteItem(instr, void 0, txName));
+    } else {
+      hasForEach = true;
+      const block = instr;
+      const blockWhen = block.when ? whenSpec(block.when) : void 0;
+      for (const w of block.body) {
+        const item = buildWriteItem(w, block.source, txName);
+        items.push(blockWhen && !item.when ? { ...item, when: blockWhen } : item);
+      }
+    }
+  }
+  if (!hasForEach) {
+    if (items.length === 0) {
+      throw new Error(
+        `defineTransaction '${txName}': a transaction must contain at least one write.`
+      );
+    }
+    if (items.length > MAX_TRANSACT_ITEMS) {
+      throw new Error(
+        `defineTransaction '${txName}': ${items.length} write items exceed the DynamoDB TransactWriteItems limit of ${MAX_TRANSACT_ITEMS}.`
+      );
+    }
+    return {
+      params: transactionParamSpecs(def.params),
+      items,
+      maxItems: items.length
+    };
+  }
+  return {
+    params: transactionParamSpecs(def.params),
+    items
+  };
+}
+function buildTransactions(transactions = {}) {
+  const out = {};
+  for (const name of Object.keys(transactions).sort()) {
+    out[name] = buildTransactionSpec(name, transactions[name]);
+  }
+  return out;
+}
+
+// src/spec/contract-n1-check.ts
+function isQueryMethodSpec(spec) {
+  return typeof spec.resolution === "string" && spec.resolution !== void 0;
+}
+function checkArrayIntoRange(contract, method, spec) {
+  if (spec.resolution === "range" && spec.inputArity !== "single") {
+    return {
+      rule: "array-into-range",
+      contract,
+      method,
+      message: `Contract '${contract}.${method}': a \`range\` resolution accepts an array input (inputArity: '${spec.inputArity}'), but a partition \`Query\` cannot be coalesced across partition keys \u2014 feeding N keys would issue N \`Query\`s (an N+1 fan-out). A \`range\` method must be \`inputArity: 'single'\`. Resolve "just these few" with an application-side loop (\`Promise.all(ids.map((id) => contract.method(id)))\`), keeping the N visible at the call site; there is no bounded-fan-out opt-in.`
+    };
+  }
+  return void 0;
+}
+function checkArrayIntoGsiPoint(contract, method, spec, isGsiPoint) {
+  if (spec.resolution === "point" && isGsiPoint && spec.inputArity !== "single") {
+    return {
+      rule: "array-into-gsi-point",
+      contract,
+      method,
+      message: `Contract '${contract}.${method}': a \`point\` read whose Key resolves via a unique GSI accepts an array input (inputArity: '${spec.inputArity}'), but a GSI point read is a per-key \`Query\` \u2014 \`BatchGetItem\` cannot read a GSI \u2014 so feeding N keys would issue N \`Query\`s (an N+1 fan-out). A unique-GSI \`point\` method must be \`inputArity: 'single'\` (only a base-table primary-key point coalesces into one \`BatchGetItem\`). Resolve "just these few" with an application-side loop (\`Promise.all(keys.map((k) => contract.method(k)))\`), keeping the N visible at the call site; there is no bounded-fan-out opt-in.`
+    };
+  }
+  return void 0;
+}
+function checkComposeChild(contract, method, parentCardinality, node) {
+  const childResolution = node.resolution;
+  if (childResolution !== "range") return void 0;
+  if (parentCardinality === "many") {
+    return {
+      rule: "list-under-list",
+      contract,
+      method,
+      message: `Contract '${contract}.${method}': composed child '${node.as}' is a \`range\` read nested under a parent step whose per-key cardinality is 'many' \u2014 a "list under a list". The parent yields N records and each drives its own partition \`Query\`, an N+1 fan-out, which is rejected at build time. A composed child under a many-yielding parent must be \`point\` (it coalesces to one \`BatchGetItem\`); resolve a true to-many with an application-side loop instead.`
+    };
+  }
+  return {
+    rule: "compose-range-under-many",
+    contract,
+    method,
+    message: `Contract '${contract}.${method}': composed child '${node.as}' is a \`range\` read (a partition \`Query\`). An External Query / composition child must be \`point\` so it coalesces to one \`BatchGetItem\` across all parent keys; a \`range\` child cannot be batched across the parent's keys and is an N+1 fan-out. Expose the to-many as a single-key \`range\` method and resolve it with an application-side loop, or make the child a \`point\` contract.`
+  };
+}
+function collectContractN1Violations(contractName, spec, isGsiPoint = () => false) {
+  const violations = [];
+  if (spec.kind !== "query") return violations;
+  for (const methodName of Object.keys(spec.methods)) {
+    const methodSpec = spec.methods[methodName];
+    if (!isQueryMethodSpec(methodSpec)) continue;
+    const arrayIntoRange = checkArrayIntoRange(contractName, methodName, methodSpec);
+    if (arrayIntoRange) violations.push(arrayIntoRange);
+    const arrayIntoGsiPoint = checkArrayIntoGsiPoint(
+      contractName,
+      methodName,
+      methodSpec,
+      isGsiPoint(methodName)
+    );
+    if (arrayIntoGsiPoint) violations.push(arrayIntoGsiPoint);
+    const parentCardinality = methodSpec.cardinality;
+    for (const child of methodSpec.compose ?? []) {
+      const violation = checkComposeChild(
+        contractName,
+        methodName,
+        parentCardinality,
+        child
+      );
+      if (violation) violations.push(violation);
+    }
+  }
+  return violations;
+}
+function assertContractN1Safe(contractName, spec, isGsiPoint) {
+  const violations = collectContractN1Violations(contractName, spec, isGsiPoint);
+  if (violations.length === 0) return;
+  const [first, ...rest] = violations;
+  const suffix = rest.length > 0 ? `
+
+(${rest.length} further N+1 violation${rest.length === 1 ? "" : "s"} in this contract:
+${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();
+  const contractOwner = /* @__PURE__ */ new Map();
+  const claim = (owner, kind, name, context) => {
+    const existing = owner.get(name);
+    if (existing !== void 0 && existing !== context) {
+      throw new Error(
+        `Context-ownership declaration is ambiguous: ${kind} '${name}' is claimed by both context '${existing}' and context '${context}'. A ${kind} belongs to exactly one bounded context \u2014 remove it from one of the \`${kind === "Model" ? "models" : "contracts"}\` lists.`
+      );
+    }
+    owner.set(name, context);
+  };
+  for (const context of Object.keys(contexts).sort()) {
+    const membership = contexts[context];
+    for (const model of membership.models ?? []) claim(modelOwner, "Model", model, context);
+    for (const contract of membership.contracts ?? [])
+      claim(contractOwner, "Contract", contract, context);
+  }
+  return { modelOwner, contractOwner };
+}
+function methodOpsOf(contract) {
+  if (isQueryModelContract(contract) || isCommandModelContract(contract)) {
+    return Object.keys(contract.methods).sort().map((name) => [name, contract.methods[name].op]);
+  }
+  return [];
+}
+function collectContractBoundaryViolations(contracts, contexts) {
+  const violations = [];
+  const { modelOwner, contractOwner } = buildOwnershipIndex(contexts);
+  for (const contractName of Object.keys(contracts).sort()) {
+    const contractContext = contractOwner.get(contractName);
+    if (contractContext === void 0) continue;
+    const contract = contracts[contractName];
+    const seen = /* @__PURE__ */ new Set();
+    for (const [method, op] of methodOpsOf(contract)) {
+      const model = op.entity.name;
+      const foreignContext = modelOwner.get(model);
+      if (foreignContext === void 0) continue;
+      if (foreignContext === contractContext) continue;
+      const dedupeKey = `${method}\0${model}`;
+      if (seen.has(dedupeKey)) continue;
+      seen.add(dedupeKey);
+      violations.push({
+        contract: contractName,
+        contractContext,
+        method,
+        foreignModel: model,
+        foreignContext,
+        message: `Contract '${contractName}.${method}' (context '${contractContext}') directly references Model '${model}', which is private to context '${foreignContext}'. A Model is the private implementation of its bounded context; crossing a context boundary is allowed only through the other context's published Contract (an External Query / Command), never its Models. Depend on context '${foreignContext}''s published Contract for '${model}' instead of reaching into the Model directly.`
+      });
+    }
+  }
+  return violations;
+}
+function assertContractBoundaries(contracts, contexts) {
+  const violations = collectContractBoundaryViolations(contracts, contexts);
+  if (violations.length === 0) return;
+  const [first, ...rest] = violations;
+  const suffix = rest.length > 0 ? `
+
+(${rest.length} further context-boundary violation${rest.length === 1 ? "" : "s"}:
+${rest.map((v) => `  - ${v.message}`).join("\n")})` : "";
+  throw new Error(first.message + suffix);
+}
+
+// src/spec/operations.ts
+function paramSpecs(params) {
+  const out = {};
+  for (const name of Object.keys(params).sort()) {
+    const d = params[name];
+    out[name] = d.literals === void 0 ? { type: d.kind, required: d.required } : {
+      type: d.kind,
+      required: d.required,
+      literals: d.literals
+    };
+  }
+  return out;
+}
+function metaFor(def) {
+  return MetadataRegistry.get(def.entity.modelClass);
+}
+function templateLeaf(key, value) {
+  if (isContractParamRef(value)) return value.token;
+  if (isContractKeyFieldRef(value)) return `{${value.field}}`;
+  if (isParam(value)) return `{${key}}`;
+  if (value instanceof Date) return value.toISOString();
+  return String(value);
+}
+function keyFieldNames(key) {
+  if (key === null || typeof key !== "object") return [];
+  return Object.keys(key);
+}
+function buildReadOperations(def) {
+  const metadata = metaFor(def);
+  const fields = keyFieldNames(def.key);
+  const resolved = resolveKey(fields, metadata);
+  const select = def.select ?? {};
+  const tableName = TableMapping.resolve(metadata.tableName);
+  const present = new Set(fields);
+  let type;
+  let indexName;
+  let keyCondition = {};
+  let rangeCondition;
+  if (resolved.type === "pk") {
+    if (!metadata.primaryKey) throw new Error("Primary key not defined");
+    const { pk, sk } = evaluateKey(
+      metadata.primaryKey.segmented,
+      "param",
+      present,
+      void 0,
+      resolved.partial
+    );
+    if (resolved.partial) {
+      type = "Query";
+      keyCondition = { PK: pk };
+      if (sk !== void 0 && sk !== "") {
+        rangeCondition = { operator: "begins_with", key: "SK", value: sk };
+      }
+    } else if (sk !== void 0) {
+      type = "GetItem";
+      keyCondition = { PK: pk, SK: sk };
+    } else {
+      type = "Query";
+      keyCondition = { PK: pk };
+    }
+  } else {
+    const gsi = metadata.gsiDefinitions.find(
+      (g) => g.indexName === resolved.indexName
+    );
+    if (!gsi) throw new Error(`GSI '${resolved.indexName}' not found`);
+    const { pk, sk } = evaluateKey(
+      gsi.segmented,
+      "param",
+      present,
+      void 0,
+      resolved.partial
+    );
+    type = "Query";
+    indexName = gsi.indexName;
+    keyCondition = { [`${gsi.indexName}PK`]: pk };
+    if (resolved.partial) {
+      if (sk !== void 0 && sk !== "") {
+        rangeCondition = {
+          operator: "begins_with",
+          key: `${gsi.indexName}SK`,
+          value: sk
+        };
+      }
+    } else if (sk !== void 0 && sk !== "") {
+      keyCondition[`${gsi.indexName}SK`] = sk;
+    }
+  }
+  const projection = projectionFields(select);
+  const root = {
+    type,
+    tableName,
+    ...indexName ? { indexName } : {},
+    keyCondition,
+    ...rangeCondition ? { rangeCondition } : {},
+    projection,
+    resultPath: "$"
+  };
+  const ops = [root];
+  ops.push(...buildRelationOperations(metadata, select, "$"));
+  return ops;
+}
+function projectionFields(select) {
+  const out = [];
+  for (const [field, value] of Object.entries(select)) {
+    if (value === true) out.push(field);
+  }
+  return out.sort();
+}
+function buildRelationOperations(metadata, select, parentPath) {
+  const ops = [];
+  const relations = detectRelationFields(select, metadata);
+  for (const rel of [...relations].sort(
+    (a, b) => a.propertyName.localeCompare(b.propertyName)
+  )) {
+    const spec = normalizeSelectSpec(select[rel.propertyName]);
+    const childSelect = spec.select ?? {};
+    const targetClass = rel.targetFactory();
+    const targetMeta = MetadataRegistry.get(targetClass);
+    const childPath = `${parentPath}.${rel.propertyName}`;
+    if (rel.type === "hasMany") {
+      const limit = spec.limit ?? rel.options?.limit?.default ?? 20;
+      ops.push(
+        buildHasManyOperation(rel, targetMeta, childSelect, limit, spec.filter, `${childPath}.items`)
+      );
+      ops.push(...buildRelationOperations(targetMeta, childSelect, `${childPath}.items`));
+    } else {
+      ops.push(
+        buildBatchGetOperation(rel, targetMeta, childSelect, childPath)
+      );
+      ops.push(...buildRelationOperations(targetMeta, childSelect, childPath));
+    }
+  }
+  return ops;
+}
+function singleSourceField(rel) {
+  const entries = Object.entries(rel.keyBinding);
+  if (entries.length !== 1) {
+    throw new Error(
+      `Relation '${rel.propertyName}' binds ${entries.length} fields; the static planner currently supports single-field relation key bindings only.`
+    );
+  }
+  const [targetField, sourceField] = entries[0];
+  return { targetField, sourceField };
+}
+function buildHasManyOperation(rel, targetMeta, select, limit, filter, resultPath) {
+  const { targetField, sourceField } = singleSourceField(rel);
+  const resolved = resolveKey([targetField], targetMeta);
+  const tableName = TableMapping.resolve(targetMeta.tableName);
+  const nameOf = (f) => f === targetField ? sourceField : f;
+  const present = /* @__PURE__ */ new Set([targetField]);
+  const op = (() => {
+    if (resolved.type === "pk") {
+      if (!targetMeta.primaryKey) throw new Error("Primary key not defined");
+      const { pk: pk2, sk: sk2 } = evaluateKey(
+        targetMeta.primaryKey.segmented,
+        "result",
+        present,
+        nameOf,
+        resolved.partial
+      );
+      const keyCondition2 = {
+        PK: pk2
+      };
+      const range3 = sk2 !== void 0 && sk2 !== "" ? { operator: "begins_with", key: "SK", value: sk2 } : void 0;
+      return {
+        type: "Query",
+        tableName,
+        keyCondition: keyCondition2,
+        ...range3 ? { rangeCondition: range3 } : {},
+        projection: projectionFields(select),
+        limit,
+        resultPath,
+        sourceField
+      };
+    }
+    const gsi = targetMeta.gsiDefinitions.find((g) => g.indexName === resolved.indexName);
+    const { pk, sk } = evaluateKey(
+      gsi.segmented,
+      "result",
+      present,
+      nameOf,
+      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;
+    return {
+      type: "Query",
+      tableName,
+      indexName: gsi.indexName,
+      keyCondition,
+      ...range2 ? { rangeCondition: range2 } : {},
+      projection: projectionFields(select),
+      limit,
+      resultPath,
+      sourceField
+    };
+  })();
+  return filter ? { ...op, filter: filterSpec(filter) } : op;
+}
+function buildBatchGetOperation(rel, targetMeta, select, resultPath) {
+  const { targetField, sourceField } = singleSourceField(rel);
+  const resolved = resolveKey([targetField], targetMeta);
+  if (resolved.type !== "pk" || resolved.partial) {
+    throw new Error(
+      `Relation '${rel.propertyName}' (${rel.type}) must resolve to a full primary key (BatchGetItem); got ${resolved.type}${resolved.partial ? " (partial)" : ""}.`
+    );
+  }
+  if (!targetMeta.primaryKey) throw new Error("Primary key not defined");
+  const nameOf = (f) => f === targetField ? sourceField : f;
+  const { pk, sk } = evaluateKey(
+    targetMeta.primaryKey.segmented,
+    "result",
+    /* @__PURE__ */ new Set([targetField]),
+    nameOf
+  );
+  const keyCondition = {
+    PK: pk
+  };
+  if (sk !== void 0) keyCondition.SK = sk;
+  return {
+    type: "BatchGetItem",
+    tableName: TableMapping.resolve(targetMeta.tableName),
+    keyCondition,
+    projection: projectionFields(select),
+    resultPath,
+    sourceField
+  };
+}
+function filterSpec(filter) {
+  return { declarative: filter };
+}
+function buildCommandSpec(def) {
+  const metadata = metaFor(def);
+  const tableName = TableMapping.resolve(metadata.tableName);
+  const params = paramSpecs(def.params);
+  const entity = def.entity.name;
+  const condition = extractCondition(def);
+  if (def.operation === "put") {
+    const item = templateRecord3(def.key);
+    return {
+      type: "PutItem",
+      tableName,
+      entity,
+      params,
+      item,
+      ...condition ? { condition } : {}
+    };
+  }
+  if (def.operation === "delete") {
+    return {
+      type: "DeleteItem",
+      tableName,
+      entity,
+      params,
+      keyCondition: writeKeyCondition(metadata, def.key, entity),
+      ...condition ? { condition } : {}
+    };
+  }
+  return {
+    type: "UpdateItem",
+    tableName,
+    entity,
+    params,
+    keyCondition: writeKeyCondition(metadata, def.key, entity),
+    changes: templateRecord3(def.changes),
+    ...condition ? { condition } : {}
+  };
+}
+function writeKeyCondition(metadata, key, entity) {
+  if (!metadata.primaryKey) throw new Error("Primary key not defined");
+  const fields = Object.keys(key);
+  const resolved = resolveKey(fields, metadata);
+  if (resolved.type === "gsi") {
+    throw new Error(
+      `Command on '${entity}': the contract Key fields ${JSON.stringify(fields)} resolve to the GSI '${resolved.indexName}', but a DynamoDB write (\`UpdateItem\` / \`DeleteItem\`) can target an item only by its base-table primary key \u2014 there is no GSI-keyed write. A command keyed by a secondary index is not expressible. Key the command by the model's primary key (e.g. read the item by its GSI first, then write by the resolved primary key), or model the write against the base-table PK Key fields.`
+    );
+  }
+  const present = new Set(fields);
+  const { pk, sk } = evaluateKey(
+    metadata.primaryKey.segmented,
+    "param",
+    present
+  );
+  const out = { PK: pk };
+  if (sk !== void 0) out.SK = sk;
+  return out;
+}
+function templateRecord3(structure) {
+  const out = {};
+  for (const key of Object.keys(structure).sort()) {
+    out[key] = templateLeaf(key, structure[key]);
+  }
+  return out;
+}
+function extractCondition(def) {
+  return conditionInputToSpec(
+    def.condition,
+    `Command on '${def.entity.name}'`,
+    (field, value) => templateLeaf(field, value)
+  );
+}
+function buildQuerySpec(def) {
+  const operations = buildReadOperations(def);
+  const executionPlan = deriveExecutionPlan(operations.map((op) => op.resultPath));
+  return {
+    params: paramSpecs(def.params),
+    operations,
+    // `defineQuery` → a single entity object; `defineList` → a connection.
+    cardinality: def.operation === "query" ? "one" : "many",
+    ...executionPlan !== void 0 ? { executionPlan } : {}
+  };
+}
+function mergeSpecs(base, synthesized, kind) {
+  for (const name of Object.keys(synthesized)) {
+    if (Object.prototype.hasOwnProperty.call(base, name)) {
+      throw new Error(
+        `Contract serialization produced ${kind} '${name}', which collides with a hand-written definition of the same name. Contract method ops are named '<Contract>__<method>'; rename the conflicting definition.`
+      );
+    }
+    base[name] = synthesized[name];
+  }
+}
+function buildOperations(queries = {}, commands = {}, transactions = {}, contractInputs = {}) {
+  const querySpecs = {};
+  for (const name of Object.keys(queries).sort()) {
+    querySpecs[name] = buildQuerySpec(queries[name]);
+  }
+  const commandSpecs = {};
+  for (const name of Object.keys(commands).sort()) {
+    const spec = buildCommandSpec(commands[name]);
+    if (spec.condition) assertSupportedCondition(name, spec.condition);
+    commandSpecs[name] = spec;
+  }
+  const transactionSpecs = buildTransactions(transactions);
+  const contractInputMap = contractInputs.contracts ?? {};
+  const contextInputMap = contractInputs.contexts ?? {};
+  assertContractBoundaries(contractInputMap, contextInputMap);
+  const built = buildContracts(contractInputMap);
+  mergeSpecs(querySpecs, built.queries, "query");
+  mergeSpecs(commandSpecs, built.commands, "command");
+  mergeSpecs(transactionSpecs, built.transactions, "transaction");
+  const contractSpecs = built.contracts;
+  const contextSpecs = buildContexts(contextInputMap);
+  return {
+    version: SPEC_VERSION,
+    queries: querySpecs,
+    commands: commandSpecs,
+    ...Object.keys(transactionSpecs).length > 0 ? { transactions: transactionSpecs } : {},
+    ...Object.keys(contractSpecs).length > 0 ? { contracts: contractSpecs } : {},
+    ...Object.keys(contextSpecs).length > 0 ? { contexts: contextSpecs } : {}
+  };
+}
+
+// src/spec/contracts.ts
+function kindForDynamoType(dynamoType) {
+  return dynamoType === "N" ? "number" : "string";
+}
+function recoverKind(metadata, fieldName) {
+  const field = metadata.fields.find((f) => f.propertyName === fieldName);
+  if (field === void 0) return { kind: "string" };
+  if (field.literals !== void 0 && field.literals.length > 0) {
+    return { kind: "literal", literals: field.literals };
+  }
+  return { kind: kindForDynamoType(field.dynamoType) };
+}
+function opToDefinition(contractName, methodName, op) {
+  const metadata = MetadataRegistry.get(op.entity.modelClass);
+  const params = {};
+  const place = (paramName, bindField) => {
+    const recovered = recoverKind(metadata, bindField);
+    params[paramName] = recovered.literals === void 0 ? { kind: recovered.kind, required: true } : { kind: recovered.kind, literals: recovered.literals, required: true };
+    return recovered;
+  };
+  let key;
+  if (op.operation === "put") {
+    key = convertStructure(op.item ?? {}, place, `${contractName}.${methodName} item`);
+  } else if (isContractKeyRef(op.keys)) {
+    key = wholeKeyToParams(metadata, op, contractName, methodName, place);
+  } else {
+    key = convertKeyRecord(op.keys, place, `${contractName}.${methodName} key`);
+  }
+  const select = op.select !== void 0 ? assertBooleanProjection(op.select, `${contractName}.${methodName} select`) : void 0;
+  const changes = op.changes !== void 0 ? convertStructure(op.changes, place, `${contractName}.${methodName} changes`) : void 0;
+  const condition = op.condition !== void 0 ? convertCondition(op.condition, place, `${contractName}.${methodName} condition`) : void 0;
+  return {
+    __isOperationDefinition: true,
+    entity: op.entity,
+    operation: op.operation,
+    key,
+    select,
+    changes,
+    ...condition !== void 0 ? { condition } : {},
+    params
+  };
+}
+function paramOfKind(recovered) {
+  if (recovered.kind === "number") return param.number();
+  if (recovered.kind === "literal" && recovered.literals !== void 0 && recovered.literals.length > 0) {
+    return param.literal(
+      ...recovered.literals
+    );
+  }
+  return param.string();
+}
+function wholeKeyToParams(metadata, op, contractName, methodName, place) {
+  const fields = wholeKeyFieldNames(metadata, op, contractName, methodName);
+  const key = {};
+  for (const field of fields) {
+    key[field] = paramOfKind(place(field, field));
+  }
+  return key;
+}
+function wholeKeyFieldNames(metadata, op, contractName, methodName) {
+  if (op.keyFields !== void 0 && op.keyFields.length > 0) return op.keyFields;
+  if (!metadata.primaryKey) {
+    throw new Error(
+      `Contract '${contractName}.${methodName}': the '${op.operation}' op passes the whole \`keys\` into the key position, but model '${op.entity.name}' has no primary key to resolve the contract Key from. Supply an explicit Key-field list to the factory (e.g. \`publicQueryModel<Key>(['field'])\`).`
+    );
+  }
+  return metadata.primaryKey.inputFieldNames;
+}
+function convertKeyRecord(record, place, context) {
+  const out = {};
+  for (const [field, leaf] of Object.entries(record)) {
+    if (isContractKeyFieldRef(leaf)) {
+      out[field] = paramOfKind(place(leaf.field, field));
+    } else if (isConcreteLiteral3(leaf)) {
+      out[field] = leaf;
+    } else {
+      throw new Error(
+        `${context}: key field '${field}' is neither a \`keys.<field>\` reference nor a concrete literal \u2014 it cannot be serialized.`
+      );
+    }
+  }
+  return out;
+}
+function convertStructure(structure, place, context) {
+  const out = {};
+  for (const [field, leaf] of Object.entries(structure)) {
+    out[field] = convertLeaf(leaf, field, place, `${context} field '${field}'`);
+  }
+  return out;
+}
+function convertLeaf(leaf, bindField, place, context) {
+  if (isContractParamRef(leaf)) {
+    place(leaf.field, bindField);
+    return leaf;
+  }
+  if (isContractKeyFieldRef(leaf)) {
+    place(leaf.field, bindField);
+    return leaf;
+  }
+  if (isConcreteLiteral3(leaf)) return leaf;
+  throw new Error(
+    `${context}: value is neither a param/key reference nor a concrete literal \u2014 it cannot be serialized as a declarative contract operation.`
+  );
+}
+function convertCondition(condition, place, context) {
+  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 };
+    }
+  }
+  const out = {};
+  for (const [field, leaf] of Object.entries(condition)) {
+    out[field] = convertLeaf(leaf, field, place, `${context} field '${field}'`);
+  }
+  return out;
+}
+function assertBooleanProjection(select, context) {
+  const out = {};
+  for (const [field, leaf] of Object.entries(select)) {
+    if (typeof leaf === "boolean") {
+      out[field] = leaf;
+      continue;
+    }
+    if (leaf !== null && typeof leaf === "object" && !isContractParamRef(leaf) && !isContractKeyFieldRef(leaf)) {
+      out[field] = leaf;
+      continue;
+    }
+    throw new Error(
+      `${context}: projection field '${field}' must be a boolean flag (\`true\` / \`false\`), but a ${describeLeaf(leaf)} was found. A parameter reference in a projection slot is not a valid select \u2014 refusing to emit it.`
+    );
+  }
+  return out;
+}
+function describeLeaf(leaf) {
+  if (isContractParamRef(leaf)) return `param reference (${leaf.token})`;
+  if (isContractKeyFieldRef(leaf)) return `key-field reference (${leaf.token})`;
+  return `value of type '${typeof leaf}'`;
+}
+function isConcreteLiteral3(value) {
+  const t = typeof value;
+  return value === null || value instanceof Date || t === "string" || t === "number" || t === "boolean";
+}
+function opRefName(contractName, methodName) {
+  return `${contractName}__${methodName}`;
+}
+function composeSpecOf(node, contractName, methodName, contracts) {
+  if (isRecordedCompose(node)) {
+    return recordedComposeSpec(node, contractName, methodName, contracts);
+  }
+  const c = node;
+  if (typeof c.as !== "string" || typeof c.contract !== "string" || typeof c.method !== "string") {
+    throw new Error(
+      `Contract '${contractName}.${methodName}': a composition must declare string \`as\` / \`contract\` / \`method\`.`
+    );
+  }
+  if (c.resolution !== "point" && c.resolution !== "range") {
+    throw new Error(
+      `Contract '${contractName}.${methodName}': composed child '${c.as}' must declare a \`resolution\` of 'point' or 'range'.`
+    );
+  }
+  const bindIn = c.bind ?? {};
+  const bind = {};
+  for (const field of Object.keys(bindIn).sort()) {
+    const v = bindIn[field];
+    if (typeof v !== "string") {
+      throw new Error(
+        `Contract '${contractName}.${methodName}': composition '${c.as}' binding '${field}' must be a \`from\` path string (e.g. "$.billingAccountId").`
+      );
+    }
+    bind[field] = v;
+  }
+  const cardinality = c.cardinality === "many" ? "many" : "one";
+  return {
+    as: c.as,
+    contract: c.contract,
+    method: c.method,
+    ...typeof c.context === "string" ? { context: c.context } : {},
+    bind,
+    resolution: c.resolution,
+    cardinality
+  };
+}
+function isRecordedCompose(node) {
+  return typeof node === "object" && node !== null && typeof node.as === "string" && typeof node.method === "object" && node.method?.__methodKind === "query";
+}
+function recordedComposeSpec(node, contractName, methodName, contracts) {
+  const { contract: refName, method: refMethodName } = resolveComposeRef(
+    node,
+    contractName,
+    methodName,
+    contracts
+  );
+  const refMethod = node.method;
+  const bind = {};
+  for (const field of Object.keys(node.bind).sort()) {
+    bind[field] = node.bind[field].path;
+  }
+  const cardinality = refMethod.resolution === "point" ? "one" : "many";
+  return {
+    as: node.as,
+    contract: refName,
+    method: refMethodName,
+    bind,
+    resolution: refMethod.resolution,
+    cardinality
+  };
+}
+function resolveComposeRef(node, contractName, methodName, contracts) {
+  const refMethodName = node.method.__methodName;
+  if (typeof refMethodName !== "string") {
+    throw new Error(
+      `Contract '${contractName}.${methodName}': composed child '${node.as}' references a query method that was not produced by publicQueryModel (no method name). Compose only the value of a publicQueryModel method (e.g. \`query(OtherContract.get, \u2026)\`).`
+    );
+  }
+  const owner = contractOfMethodSpec(node.method);
+  if (owner !== void 0) {
+    for (const name of Object.keys(contracts)) {
+      if (contracts[name] === owner) return { contract: name, method: refMethodName };
+    }
+  }
+  throw new Error(
+    `Contract '${contractName}.${methodName}': composed child '${node.as}' references a contract method that is not registered in this SSoT. An External Query must reference another contract passed to the generator's contract map (a same-SSoT, in-process reference); add the referenced contract to the \`contracts\` map.`
+  );
+}
+function composeOf(op) {
+  const raw = op.compose;
+  return Array.isArray(raw) ? raw : [];
+}
+function compositionPlanOf(compose) {
+  if (compose.length === 0) return void 0;
+  const { stages, concurrency } = deriveCompositionPlan(compose.length);
+  return {
+    stages: stages.map((s) => [...s]),
+    concurrency,
+    batchChunkSize: BATCH_GET_MAX_KEYS
+  };
+}
+function batchTxName(contractName, methodName) {
+  return `${opRefName(contractName, methodName)}__batch`;
+}
+function keyParamNames(op) {
+  return keyFieldsOf(op);
+}
+var TX_ITEM_TYPE = {
+  PutItem: "Put",
+  UpdateItem: "Update",
+  DeleteItem: "Delete"
+};
+function toElementTemplate(template, keyParams) {
+  return template.replace(
+    /\{([^}]+)\}/g,
+    (match, name) => keyParams.has(name) ? `{item.${name}}` : match
+  );
+}
+function toElementRecord(record, keyParams) {
+  const out = {};
+  for (const field of Object.keys(record)) {
+    out[field] = toElementTemplate(record[field], keyParams);
+  }
+  return out;
+}
+function toElementCondition(condition, keyParams) {
+  if (condition.kind !== "equals") return condition;
+  return { kind: "equals", fields: toElementRecord(condition.fields, keyParams) };
+}
+function synthesizeBatchTransaction(commandSpec, op) {
+  const keyParams = new Set(keyParamNames(op));
+  const elementFields = {};
+  const sharedParams = {};
+  for (const name of Object.keys(commandSpec.params).sort()) {
+    if (keyParams.has(name)) elementFields[name] = commandSpec.params[name];
+    else sharedParams[name] = commandSpec.params[name];
+  }
+  const params = {
+    ...sharedParams,
+    keys: { type: "array", required: true, element: elementFields }
+  };
+  const condition = commandSpec.condition !== void 0 ? toElementCondition(commandSpec.condition, keyParams) : void 0;
+  const item = {
+    type: TX_ITEM_TYPE[commandSpec.type],
+    tableName: commandSpec.tableName,
+    entity: commandSpec.entity,
+    ...commandSpec.item !== void 0 ? { item: toElementRecord(commandSpec.item, keyParams) } : {},
+    ...commandSpec.keyCondition !== void 0 ? { keyCondition: toElementRecord(commandSpec.keyCondition, keyParams) } : {},
+    ...commandSpec.changes !== void 0 ? { changes: toElementRecord(commandSpec.changes, keyParams) } : {},
+    ...condition !== void 0 ? { condition } : {},
+    forEach: { source: "keys" }
+  };
+  return { params, items: [item] };
+}
+function composeFragmentTransaction(contractName, methodName, ops) {
+  const items = [];
+  const params = {};
+  for (let i = 0; i < ops.length; i++) {
+    const op = ops[i];
+    const def = opToDefinition(contractName, `${methodName}__f${i}`, op);
+    const commandSpec = buildCommandSpec(def);
+    if (commandSpec.condition) {
+      assertSupportedCondition(`${opRefName(contractName, methodName)}#${i}`, commandSpec.condition);
+    }
+    for (const [name, spec] of Object.entries(commandSpec.params)) {
+      params[name] = spec;
+    }
+    const item = {
+      type: TX_ITEM_TYPE[commandSpec.type],
+      tableName: commandSpec.tableName,
+      entity: commandSpec.entity,
+      ...commandSpec.item !== void 0 ? { item: commandSpec.item } : {},
+      ...commandSpec.keyCondition !== void 0 ? { keyCondition: commandSpec.keyCondition } : {},
+      ...commandSpec.changes !== void 0 ? { changes: commandSpec.changes } : {},
+      ...commandSpec.condition !== void 0 ? { condition: commandSpec.condition } : {}
+    };
+    items.push(item);
+  }
+  return { params: sortedParams(params), items, maxItems: items.length };
+}
+function itemKeySignature(item) {
+  if (item.type === "Put") {
+    const metadata = MetadataRegistry.get(
+      // The entity name matches a manifest entity / a registered model class name.
+      resolveModelByName(item.entity)
+    );
+    if (!metadata.primaryKey) return `${item.entity}#<no-key>`;
+    const present = new Set(Object.keys(item.item ?? {}));
+    const { pk, sk } = evaluateKey(metadata.primaryKey.segmented, "param", present);
+    return `${item.entity}#${pk}#${sk ?? ""}`;
+  }
+  const kc = item.keyCondition ?? {};
+  return `${item.entity}#${kc.PK ?? ""}#${kc.SK ?? ""}`;
+}
+function resolveModelByName(name) {
+  for (const modelClass of MetadataRegistry.getAll().keys()) {
+    if (modelClass.name === name) {
+      return modelClass;
+    }
+  }
+  throw new Error(
+    `Contract serializer: cannot resolve model '${name}' for the edge de-dup key signature \u2014 it is not a registered model.`
+  );
+}
+function sortedParams(params) {
+  const out = {};
+  for (const name of Object.keys(params).sort()) out[name] = params[name];
+  return out;
+}
+function buildConditionCheckItems(checks, label) {
+  const items = [];
+  const params = {};
+  for (const check of checks) {
+    const metadata = MetadataRegistry.get(
+      check.entity.modelClass
+    );
+    if (!metadata.primaryKey) {
+      throw new Error(
+        `${label}: the referenced entity '${check.entity.name}' has no primary key, so a referential-integrity ConditionCheck cannot be keyed.`
+      );
+    }
+    const tableName = TableMapping.resolve(metadata.tableName);
+    const present = new Set(Object.keys(check.keyBinding));
+    const { pk, sk } = evaluateKey(
+      metadata.primaryKey.segmented,
+      "param",
+      present,
+      (field) => check.keyBinding[field] ?? field
+    );
+    const keyCondition = { PK: pk };
+    if (sk !== void 0) keyCondition.SK = sk;
+    const condition = { kind: "attributeExists", field: "PK" };
+    assertSupportedCondition(`${label} (${check.entity.name})`, condition);
+    items.push({
+      type: "ConditionCheck",
+      tableName,
+      entity: check.entity.name,
+      keyCondition,
+      condition
+    });
+    for (const [targetField, inputField] of Object.entries(check.keyBinding)) {
+      const recovered = recoverKind(metadata, targetField);
+      params[inputField] = recovered.literals === void 0 ? { type: recovered.kind, required: true } : { type: recovered.kind, required: true, literals: recovered.literals };
+    }
+  }
+  return { items, params };
+}
+function buildEdgeWriteItems(edgeWrites2) {
+  const items = [];
+  const params = {};
+  for (const edge of edgeWrites2) {
+    const metadata = MetadataRegistry.get(
+      edge.entity.modelClass
+    );
+    for (const item of edge.items) {
+      items.push(item);
+      collectTemplateParams(item.item, metadata, params);
+      collectTemplateParams(item.keyCondition, metadata, params);
+    }
+  }
+  return { items, params };
+}
+var TEMPLATE_TOKEN_RE = /\{([^{}]+)\}/g;
+function collectTemplateParams(record, metadata, out) {
+  if (record === void 0) return;
+  for (const template of Object.values(record)) {
+    for (const match of template.matchAll(TEMPLATE_TOKEN_RE)) {
+      const token = match[1];
+      const field = token.startsWith("old.") ? token.slice("old.".length) : token;
+      const recovered = recoverKind(metadata, field);
+      out[token] = recovered.literals === void 0 ? { type: recovered.kind, required: true } : { type: recovered.kind, required: true, literals: recovered.literals };
+    }
+  }
+}
+function buildDerivedUpdateItems(derivedUpdates) {
+  const items = [];
+  const params = {};
+  for (const update of derivedUpdates) {
+    const metadata = MetadataRegistry.get(
+      update.entity.modelClass
+    );
+    if (!metadata.primaryKey) {
+      throw new Error(
+        `derived update: the target entity '${update.entity.name}' has no primary key, so a derived counter \`UpdateItem\` cannot be keyed.`
+      );
+    }
+    const tableName = TableMapping.resolve(metadata.tableName);
+    const present = new Set(Object.keys(update.keyBinding));
+    const { pk, sk } = evaluateKey(
+      metadata.primaryKey.segmented,
+      "param",
+      present,
+      (field) => update.keyBinding[field] ?? field
+    );
+    const keyCondition = { PK: pk };
+    if (sk !== void 0) keyCondition.SK = sk;
+    items.push({
+      type: "Update",
+      tableName,
+      entity: update.entity.name,
+      keyCondition,
+      // The delta is a compile-time constant → a literal numeric template (no param).
+      add: { [update.attribute]: String(update.amount) }
+    });
+    collectTemplateParams(keyCondition, metadata, params);
+  }
+  return { items, params };
+}
+function buildUniqueGuardItems(uniqueGuards, entityMetadata) {
+  const items = [];
+  const params = {};
+  for (const guard of uniqueGuards) {
+    for (const item of guard.items) {
+      items.push({ ...item, tableName: TableMapping.resolve(item.tableName) });
+      collectTemplateParams(item.item, entityMetadata, params);
+      collectTemplateParams(item.keyCondition, entityMetadata, params);
+    }
+  }
+  return { items, params };
+}
+function buildOutboxEventItems(outboxEvents, entityMetadata) {
+  const items = [];
+  const params = {};
+  for (const event of outboxEvents) {
+    for (const item of event.items) {
+      items.push({ ...item, tableName: TableMapping.resolve(item.tableName) });
+      collectTemplateParams(item.item, entityMetadata, params);
+    }
+  }
+  return { items, params };
+}
+function buildIdempotencyGuardItems(guard, entityMetadata) {
+  const items = [];
+  const params = {};
+  for (const item of guard.items) {
+    items.push({ ...item, tableName: TableMapping.resolve(item.tableName) });
+    collectTemplateParams(item.item, entityMetadata, params);
+  }
+  return { items, params };
+}
+function synthesizeMutationTransaction(contractName, methodName, ops, checks, edgeWrites2, derivedUpdates, uniqueGuards, outboxEvents, idempotencyGuard) {
+  const label = opRefName(contractName, methodName);
+  const base = composeFragmentTransaction(contractName, methodName, ops);
+  const { items: edgeItemsRaw, params: edgeParams } = buildEdgeWriteItems(edgeWrites2);
+  const { items: updateItems, params: updateParams } = buildDerivedUpdateItems(derivedUpdates);
+  const { items: checkItems, params: checkParams } = buildConditionCheckItems(checks, label);
+  const primaryMetadata = MetadataRegistry.get(
+    ops[0].entity.modelClass
+  );
+  const { items: guardItemsRaw, params: guardParams } = buildUniqueGuardItems(
+    uniqueGuards,
+    primaryMetadata
+  );
+  const { items: outboxItems, params: outboxParams } = buildOutboxEventItems(
+    outboxEvents,
+    primaryMetadata
+  );
+  const { items: idempotencyItems, params: idempotencyParams } = idempotencyGuard !== void 0 ? buildIdempotencyGuardItems(idempotencyGuard, primaryMetadata) : { items: [], params: {} };
+  const baseKeys = new Set(base.items.map(itemKeySignature));
+  for (const update of updateItems) {
+    if (baseKeys.has(itemKeySignature(update))) {
+      throw new Error(
+        `Contract '${contractName}.${methodName}': a derived counter (\`increment\`) targets the same row as the entity write (entity '${update.entity}', key ${JSON.stringify(update.keyCondition ?? {})}) \u2014 a Put+Update on one item is unsupported in a transaction (DynamoDB rejects touching one key twice). A \`w.increment(...)\` must target a DIFFERENT row (e.g. a parent aggregate's counter), not the fragment's own entity row; increment a field on the entity write itself instead of deriving a counter onto it.`
+      );
+    }
+  }
+  const edgeItems = edgeItemsRaw.filter((item) => {
+    const sig = itemKeySignature(item);
+    if (baseKeys.has(sig)) return false;
+    baseKeys.add(sig);
+    return true;
+  });
+  const guardItems = guardItemsRaw;
+  const params = { ...base.params };
+  for (const source of [
+    edgeParams,
+    updateParams,
+    checkParams,
+    guardParams,
+    outboxParams,
+    idempotencyParams
+  ]) {
+    for (const [name, spec] of Object.entries(source)) params[name] = spec;
+  }
+  const items = [
+    ...base.items,
+    ...edgeItems,
+    ...updateItems,
+    ...guardItems,
+    ...outboxItems,
+    ...idempotencyItems,
+    ...checkItems
+  ];
+  if (items.length > MAX_TRANSACT_ITEMS) {
+    throw new Error(
+      `Contract '${contractName}.${methodName}': a mutation composes ${items.length} items (writes + edges + derived updates + uniqueness guards + outbox events + idempotency guard + ConditionChecks) into one TransactWriteItems, exceeding the DynamoDB limit of ${MAX_TRANSACT_ITEMS}. An atomic transaction cannot be split; reduce the fragment / effect count.`
+    );
+  }
+  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 };
+  }
+  const txName = batchTxName(contractName, methodName);
+  transactionSpecs[txName] = synthesizeBatchTransaction(commandSpec, op);
+  return { mode: "transaction", transaction: txName };
+}
+function buildContracts(contracts = {}) {
+  const contractSpecs = {};
+  const querySpecs = {};
+  const commandSpecs = {};
+  const transactionSpecs = {};
+  for (const contractName of Object.keys(contracts).sort()) {
+    const contract = contracts[contractName];
+    let spec;
+    if (isQueryModelContract(contract)) {
+      spec = serializeQueryContract(contractName, contract, querySpecs, contracts);
+    } else if (isCommandModelContract(contract)) {
+      spec = serializeCommandContract(
+        contractName,
+        contract,
+        commandSpecs,
+        transactionSpecs,
+        querySpecs
+      );
+    } else {
+      throw new Error(
+        `Contract '${contractName}' is not a publicQueryModel / publicCommandModel result. Pass the value returned by publicQueryModel(...) / publicCommandModel(...).`
+      );
+    }
+    assertContractN1Safe(
+      contractName,
+      spec,
+      (methodName) => isGsiPointOp(querySpecs[opRefName(contractName, methodName)])
+    );
+    contractSpecs[contractName] = spec;
+  }
+  return {
+    contracts: contractSpecs,
+    queries: querySpecs,
+    commands: commandSpecs,
+    transactions: transactionSpecs
+  };
+}
+function serializeQueryContract(contractName, contract, querySpecs, contracts) {
+  const methods = {};
+  const keyFields = /* @__PURE__ */ new Set();
+  for (const methodName of Object.keys(contract.methods).sort()) {
+    const method = contract.methods[methodName];
+    const op = method.op;
+    const def = opToDefinition(contractName, methodName, op);
+    const querySpec = buildQuerySpec(def);
+    const opName = opRefName(contractName, methodName);
+    querySpecs[opName] = querySpec;
+    for (const f of keyFieldsOf(op)) keyFields.add(f);
+    const compose = composeOf(op).map(
+      (n) => composeSpecOf(n, contractName, methodName, contracts)
+    );
+    const compositionPlan = compositionPlanOf(compose);
+    methods[methodName] = {
+      resolution: method.resolution,
+      inputArity: method.inputArity,
+      // Per-key cardinality: a point read is at most one item; a range read is a
+      // connection. Derived from the #58 facts, not re-computed from storage.
+      cardinality: method.resolution === "point" ? "one" : "many",
+      operation: opName,
+      ...compose.length > 0 ? { compose } : {},
+      ...compositionPlan !== void 0 ? { compositionPlan } : {}
+    };
+  }
+  return {
+    kind: "query",
+    key: { fields: sortedKeyFields(keyFields) },
+    methods
+  };
+}
+function serializeCommandContract(contractName, contract, commandSpecs, transactionSpecs, querySpecs) {
+  const methods = {};
+  const keyFields = /* @__PURE__ */ new Set();
+  for (const methodName of Object.keys(contract.methods).sort()) {
+    const method = contract.methods[methodName];
+    const op = method.op;
+    const def = opToDefinition(contractName, methodName, op);
+    const commandSpec = buildCommandSpec(def);
+    if (commandSpec.condition) assertSupportedCondition(opRefName(contractName, methodName), commandSpec.condition);
+    const opName = opRefName(contractName, methodName);
+    commandSpecs[opName] = commandSpec;
+    const methodKeyFields = keyFieldsOf(op);
+    for (const f of methodKeyFields) keyFields.add(f);
+    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;
+    const promotedToTransaction = isMultiFragment || hasDerivedEffects;
+    if (promotedToTransaction) {
+      const txName = opName;
+      const ops = method.ops ?? [op];
+      const tx = hasDerivedEffects ? (
+        // #84/#85/#86/#87: writes + ConditionChecks + edge writes + derived updates +
+        // uniqueness guards + outbox events + idempotency guard, one atomic tx.
+        synthesizeMutationTransaction(
+          contractName,
+          methodName,
+          ops,
+          conditionChecks,
+          edgeWrites2,
+          derivedUpdates,
+          uniqueGuards,
+          outboxEvents,
+          idempotencyGuard
+        )
+      ) : (
+        // #90: writes only.
+        composeFragmentTransaction(contractName, methodName, ops)
+      );
+      if (tx.items.length > MAX_TRANSACT_ITEMS) {
+        throw new Error(
+          `Contract '${contractName}.${methodName}': a mutation composes ${tx.items.length} items (writes + ConditionChecks) into one TransactWriteItems, exceeding the DynamoDB limit of ${MAX_TRANSACT_ITEMS}. An atomic transaction cannot be split; reduce the fragment / requires count.`
+        );
+      }
+      transactionSpecs[txName] = tx;
+    }
+    const returnSelection = method.returnSelection;
+    if (returnSelection !== void 0 && Object.keys(returnSelection).length > 0) {
+      querySpecs[readbackQueryName(contractName, methodName)] = buildReadbackQuerySpec(
+        contractName,
+        methodName,
+        op,
+        methodKeyFields,
+        returnSelection
+      );
+    }
+    const batch = batchTargetFor(
+      method.batch,
+      op,
+      commandSpec,
+      contractName,
+      methodName,
+      opName,
+      transactionSpecs
+    );
+    const single = promotedToTransaction ? { mode: "transaction", transaction: opName } : { mode: "op", operation: opName };
+    methods[methodName] = {
+      inputArity: method.inputArity,
+      result: method.result,
+      single,
+      ...batch !== void 0 ? { batch } : {},
+      ...returnSelection !== void 0 && Object.keys(returnSelection).length > 0 ? { returnSelection: sortedReturnSelection(returnSelection) } : {}
+    };
+  }
+  return {
+    kind: "command",
+    key: { fields: sortedKeyFields(keyFields) },
+    methods
+  };
+}
+function readbackQueryName(contractName, methodName) {
+  return `${opRefName(contractName, methodName)}__readback`;
+}
+function sortedReturnSelection(selection) {
+  const out = {};
+  for (const field of Object.keys(selection).sort()) {
+    if (selection[field] === true) out[field] = true;
+  }
+  return out;
+}
+function buildReadbackQuerySpec(contractName, methodName, op, keyFields, returnSelection) {
+  if (keyFields.length === 0) {
+    throw new Error(
+      `Contract '${contractName}.${methodName}': a return projection needs the written entity's primary key to read it back, but no contract Key fields were resolved. The target model must declare a primary key.`
+    );
+  }
+  const metadata = MetadataRegistry.get(
+    op.entity.modelClass
+  );
+  const params = {};
+  const key = {};
+  for (const field of keyFields) {
+    const recovered = recoverKind(metadata, field);
+    params[field] = recovered.literals === void 0 ? { kind: recovered.kind, required: true } : { kind: recovered.kind, literals: recovered.literals, required: true };
+    key[field] = paramOfKind(recovered);
+  }
+  const select = {};
+  for (const f of Object.keys(returnSelection).sort()) {
+    if (returnSelection[f] === true) select[f] = true;
+  }
+  const def = {
+    __isOperationDefinition: true,
+    entity: op.entity,
+    operation: "query",
+    key,
+    select,
+    params
+  };
+  return buildQuerySpec(def);
+}
+function keyFieldsOf(op) {
+  if (op.operation === "put") {
+    const fields2 = [];
+    for (const leaf of Object.values(op.item ?? {})) {
+      if (isContractKeyFieldRef(leaf)) fields2.push(leaf.field);
+    }
+    return fields2;
+  }
+  if (isContractKeyRef(op.keys)) {
+    if (op.keyFields !== void 0 && op.keyFields.length > 0) return op.keyFields;
+    const metadata = MetadataRegistry.get(
+      op.entity.modelClass
+    );
+    return metadata.primaryKey ? metadata.primaryKey.inputFieldNames : [];
+  }
+  const fields = [];
+  for (const leaf of Object.values(op.keys)) {
+    if (isContractKeyFieldRef(leaf)) fields.push(leaf.field);
+  }
+  return fields;
+}
+function sortedKeyFields(fields) {
+  return [...fields].sort();
+}
+function isGsiPointOp(querySpec) {
+  if (querySpec === void 0) return false;
+  const root = querySpec.operations[0];
+  return root !== void 0 && root.indexName !== void 0;
+}
+function buildContexts(contexts = {}) {
+  const out = {};
+  for (const name of Object.keys(contexts).sort()) {
+    const c = contexts[name];
+    out[name] = {
+      models: [...c.models ?? []].sort(),
+      contracts: [...c.contracts ?? []].sort()
+    };
+  }
+  return out;
+}
+
+// src/spec/index.ts
+function buildBridgeBundle(queries = {}, commands = {}, registry = MetadataRegistry, transactions = {}, contractInputs = {}) {
+  const bundle = {
+    manifest: buildManifest(registry),
+    operations: buildOperations(queries, commands, transactions, contractInputs)
+  };
+  assertBundleSerializable(bundle);
+  return bundle;
+}
+
+export {
+  SPEC_VERSION,
+  MARKER_ROW_ENTITY,
+  buildManifest,
+  isSelectBuilder,
+  normalizeSelectSpec,
+  normalizeTopLevelSelect,
+  buildProject,
+  buildRelation,
+  detectRelationFields,
+  getImplicitKeyFields,
+  param,
+  isParam,
+  LIFECYCLE_CONTRACT_MARKER,
+  isLifecycleContract,
+  ENTITY_WRITES_MARKER,
+  isEntityWritesDefinition,
+  entityWrites,
+  getEntityWrites,
+  lifecyclePhaseForIntent,
+  isMutationInputRef,
+  isMutationFragment,
+  isCommandPlan,
+  mutation,
+  definePlan,
+  OLD_VALUE_NAMESPACE,
+  EDGE_WRITES_MARKER,
+  isEdgeWritesDefinition,
+  edgeWrites,
+  deriveEdgeWriteItemsFor,
+  deriveEdgeWriteItems,
+  getEdgeWrites,
+  deriveModelEdgeWriteItems,
+  resolveLifecycle,
+  compileFragment,
+  compileSingleFragmentPlan,
+  compileMutationPlan,
+  isCommandBatchMode,
+  isContractKeyRef,
+  mintContractKeyFieldRef,
+  wholeKeysSentinel,
+  isContractKeyFieldRef,
+  isContractParamRef,
+  mintContractParamRef,
+  isContractFromRef,
+  isContractComposeNode,
+  from,
+  query,
+  contractOfMethodSpec,
+  recordContractOp,
+  isRecordingContractMethod,
+  point,
+  range,
+  isQueryModelContract,
+  isCommandModelContract,
+  publicQueryModel,
+  publicCommandModel,
+  isPlannedCommandMethod,
+  command,
+  RELATION_TRAVERSAL_CONCURRENCY,
+  mapWithConcurrency,
+  buildRelationExecutionPlan,
+  deriveCompositionPlan,
+  stageOfResultPath,
+  assertSupportedCondition,
+  assertJsonSerializable,
+  assertBundleSerializable,
+  isTransactionRef,
+  when,
+  defineTransaction,
+  defineTransactions,
+  buildTransactionSpec,
+  buildTransactions,
+  collectContractN1Violations,
+  assertContractN1Safe,
+  buildContracts,
+  buildContexts,
+  collectContractBoundaryViolations,
+  assertContractBoundaries,
+  buildQuerySpec,
+  buildOperations,
+  buildBridgeBundle
+};