graphddb 0.7.9 → 0.8.0

package/dist/chunk-N4NWYNGZ.js

@@ -0,0 +1,1987 @@
+import {
+  PREPARED_FORMAT_VERSION,
+  buildManifest,
+  entityFingerprint
+} from "./chunk-LGHSZIEE.js";
+import {
+  analyzeWriteRoute,
+  assertBundleSerializable,
+  assertSupportedCondition,
+  buildTransactions,
+  compileReadRoute,
+  compileWriteFragment,
+  conditionInputToSpec,
+  contractOfMethodSpec,
+  deriveCompositionPlan,
+  deriveExecutionPlan,
+  evaluateKey,
+  evaluatePreparedRoutes,
+  isCommandModelContract,
+  isContractKeyFieldRef,
+  isContractKeyRef,
+  isContractParamRef,
+  isQueryModelContract
+} from "./chunk-I4LEJ4TF.js";
+import {
+  detectRelationFields,
+  isInlineSnapshotSpec,
+  normalizeSelectSpec
+} from "./chunk-HNY2EJPV.js";
+import {
+  MARKER_ROW_ENTITY,
+  SPEC_VERSION,
+  operationsSpecVersion
+} from "./chunk-L4QRCHRQ.js";
+import {
+  BATCH_GET_MAX_KEYS,
+  CONDITION_OPERATOR_KEYS,
+  MAX_TRANSACT_ITEMS,
+  MetadataRegistry,
+  isParam,
+  isRawCondition,
+  param,
+  resolveModelClass
+} from "./chunk-L2NEDS7U.js";
+import {
+  TableMapping,
+  isColumn,
+  resolveKey
+} from "./chunk-XTWXMOHD.js";
+
+// 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/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, kindOverride) => {
+    const recovered = kindOverride !== void 0 ? { kind: kindOverride } : recoverKind(metadata, bindField);
+    const description = op.paramDescriptions?.[paramName];
+    params[paramName] = {
+      kind: recovered.kind,
+      required: true,
+      ...recovered.literals !== void 0 ? { literals: recovered.literals } : {},
+      ...description !== void 0 ? { description } : {}
+    };
+    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 } : {},
+    // #154: the use-case description captured on the recorded op (from the
+    // descriptor's `description`) flows into the flattened `queries[op]` /
+    // `commands[op]` entry, so a documented contract read/write is self-describing
+    // in `operations.json` exactly as the removed define* op was.
+    ...op.description !== void 0 ? { description: op.description } : {},
+    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. \`publishQuery<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 (isConcreteLiteral(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, kindOverride) {
+  if (isContractParamRef(leaf)) {
+    place(leaf.field, bindField, kindOverride);
+    return leaf;
+  }
+  if (isContractKeyFieldRef(leaf)) {
+    place(leaf.field, bindField, kindOverride);
+    return leaf;
+  }
+  if (isConcreteLiteral(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 nearestColumnFields(condition) {
+  const parts = condition.parts;
+  const columnAt = (i) => isColumn(parts[i]) ? parts[i].name : void 0;
+  const out = [];
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (!isContractParamRef(part) && !isContractKeyFieldRef(part)) continue;
+    let found;
+    for (let d = 1; d < parts.length && found === void 0; d++) {
+      found = columnAt(i - d) ?? columnAt(i + d);
+    }
+    out.push(found);
+  }
+  return out;
+}
+function convertCondition(condition, place, context) {
+  if (isRawCondition(condition)) {
+    const compareFieldForSlot = nearestColumnFields(condition);
+    let slotIndex = 0;
+    for (const part of condition.parts) {
+      if (isContractParamRef(part) || isContractKeyFieldRef(part)) {
+        const compareField = compareFieldForSlot[slotIndex];
+        if (compareField === void 0) {
+          throw new Error(
+            `${context}: a raw \`cond\` value slot ('${part.field}') has no adjacent column, so its param type cannot be inferred. A \`cond\` param slot must be compared against a \`Model.col.<field>\` reference (e.g. \`cond\`\${Model.col.x} < \${param.number()}\`\`) so the parameter inherits that column's type; refusing to emit an un-typed (silently 'string') param.`
+          );
+        }
+        place(part.field, compareField);
+        slotIndex++;
+      }
+    }
+    return condition;
+  }
+  if (typeof condition === "object" && condition !== null) {
+    const obj2 = condition;
+    if (obj2.notExists === true) return { notExists: true };
+    if (typeof obj2.attributeExists === "string") {
+      return { attributeExists: obj2.attributeExists };
+    }
+    if (typeof obj2.attributeNotExists === "string") {
+      return { attributeNotExists: obj2.attributeNotExists };
+    }
+  }
+  const obj = condition;
+  if (usesConditionTree(obj)) {
+    return convertConditionTree(obj, place, context);
+  }
+  const out = {};
+  for (const [field, leaf] of Object.entries(obj)) {
+    out[field] = convertLeaf(leaf, field, place, `${context} field '${field}'`);
+  }
+  return out;
+}
+var CONDITION_LOGICAL_KEYS = /* @__PURE__ */ new Set(["and", "or", "not"]);
+function isConditionOperatorObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date || isContractParamRef(value) || isContractKeyFieldRef(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) return false;
+  return keys.every((k) => CONDITION_OPERATOR_KEYS.has(k));
+}
+function usesConditionTree(obj) {
+  for (const [key, value] of Object.entries(obj)) {
+    if (CONDITION_LOGICAL_KEYS.has(key)) return true;
+    if (isConditionOperatorObject(value)) return true;
+  }
+  return false;
+}
+function convertConditionTree(obj, place, context) {
+  const out = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === void 0) continue;
+    if (key === "and" || key === "or") {
+      out[key] = value.map(
+        (sub) => convertConditionTree(sub, place, `${context} ${key}`)
+      );
+      continue;
+    }
+    if (key === "not") {
+      out[key] = convertConditionTree(value, place, `${context} not`);
+      continue;
+    }
+    if (!isConditionOperatorObject(value)) {
+      out[key] = convertLeaf(value, key, place, `${context} field '${key}'`);
+      continue;
+    }
+    const ops = value;
+    const rendered = {};
+    for (const [op, opVal] of Object.entries(ops)) {
+      if (op === "between") {
+        const [lo, hi] = opVal;
+        rendered[op] = [
+          convertLeaf(lo, key, place, `${context} field '${key}' between[0]`),
+          convertLeaf(hi, key, place, `${context} field '${key}' between[1]`)
+        ];
+      } else if (op === "in") {
+        rendered[op] = opVal.map(
+          (v, i) => convertLeaf(v, key, place, `${context} field '${key}' in[${i}]`)
+        );
+      } else if (op === "attributeExists" || op === "attributeType") {
+        rendered[op] = opVal;
+      } else if (op === "size") {
+        rendered[op] = convertLeaf(opVal, key, place, `${context} field '${key}' ${op}`, "number");
+      } else {
+        rendered[op] = convertLeaf(opVal, key, place, `${context} field '${key}' ${op}`);
+      }
+    }
+    out[key] = rendered;
+  }
+  return out;
+}
+function assertBooleanProjection(select, context) {
+  const out = {};
+  for (const [field, leaf] of Object.entries(select)) {
+    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 isConcreteLiteral(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 publishQuery (no method name). Compose only the value of a publishQuery 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 { kind: "equals", fields: toElementRecord(condition.fields, keyParams) };
+  }
+  if (condition.kind === "expr") {
+    return { kind: "expr", declarative: toElementTree(condition.declarative, keyParams) };
+  }
+  if (condition.kind === "raw") {
+    return {
+      kind: "raw",
+      expression: condition.expression,
+      names: condition.names,
+      values: toElementTree(condition.values, keyParams)
+    };
+  }
+  return condition;
+}
+function toElementTree(node, keyParams) {
+  if (Array.isArray(node)) return node.map((n) => toElementTree(n, keyParams));
+  if (node === null || typeof node !== "object") return node;
+  const obj = node;
+  if (typeof obj.$param === "string" && !obj.$param.startsWith("item.")) {
+    return keyParams.has(obj.$param) ? { $param: `item.${obj.$param}` } : obj;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) out[k] = toElementTree(v, keyParams);
+  return out;
+}
+function synthesizeBatchTransaction(commandSpec, op) {
+  const keyParams = new Set(keyParamNames(op));
+  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(edgeWrites) {
+  const items = [];
+  const params = {};
+  for (const edge of edgeWrites) {
+    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)) {
+    if (typeof template !== "string") continue;
+    for (const match of template.matchAll(TEMPLATE_TOKEN_RE)) {
+      const token = match[1];
+      const field = token.startsWith("old.") ? token.slice("old.".length) : token;
+      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 buildMaintainWriteItems(maintainWrites) {
+  const items = [];
+  const params = {};
+  for (const maintain of maintainWrites) {
+    const metadata = MetadataRegistry.get(
+      maintain.entity.modelClass
+    );
+    if (!metadata.primaryKey) {
+      throw new Error(
+        `maintenance write: the maintained entity '${maintain.entity.name}' has no primary key, so a maintenance \`UpdateItem\` cannot be keyed.`
+      );
+    }
+    const tableName = TableMapping.resolve(metadata.tableName);
+    const present = new Set(Object.keys(maintain.keyBinding));
+    const { pk, sk } = evaluateKey(
+      metadata.primaryKey.segmented,
+      "param",
+      present,
+      (field) => maintain.keyBinding[field] ?? field
+    );
+    const keyCondition = { PK: pk };
+    if (sk !== void 0) keyCondition.SK = sk;
+    if (maintain.kind === "membership") {
+      throw new Error(
+        `maintenance write: a sparse-view membership maintainer ('${maintain.relationProperty}' on '${maintain.entity.name}') reached the synchronous transaction spec builder. Membership is stream-only (#133) \u2014 it should have been diverted to a maintenance-outbox row. This is a compiler defect.`
+      );
+    }
+    const projection = {};
+    for (const [attr, transform] of Object.entries(maintain.projection)) {
+      projection[attr] = {
+        op: transform.op,
+        args: [...transform.args],
+        inputField: transform.inputField
+      };
+    }
+    const maintainSpec = {
+      kind: maintain.kind,
+      relationProperty: maintain.relationProperty,
+      trigger: maintain.trigger,
+      projection,
+      ...maintain.kind === "collection" && maintain.collection !== void 0 ? {
+        collection: {
+          field: maintain.collection.field,
+          ...maintain.collection.maxItems !== void 0 ? { maxItems: maintain.collection.maxItems } : {},
+          ...maintain.collection.orderBy !== void 0 ? { orderBy: maintain.collection.orderBy } : {},
+          ...maintain.collection.orderBy !== void 0 && maintain.collection.orderDir !== void 0 ? { orderDir: maintain.collection.orderDir } : {}
+        }
+      } : {},
+      // #141: a counter carries its scalar `ADD` (attribute + literal numeric delta);
+      // the runtimes render `ADD #attr :delta` exactly as the self-lifecycle derived
+      // counter (#85) does, so a same-row counter merge stays consistent across paths.
+      ...maintain.kind === "counter" && maintain.counter !== void 0 && maintain.counter.op === "count" ? {
+        counter: {
+          attribute: maintain.counter.attribute,
+          delta: String(maintain.counter.delta)
+        }
+      } : {}
+    };
+    items.push({
+      type: "Update",
+      tableName,
+      entity: maintain.entity.name,
+      keyCondition,
+      maintain: maintainSpec
+    });
+    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 buildMaintainOutboxItems(maintainOutbox, entityMetadata) {
+  const items = [];
+  const params = {};
+  for (const outbox of maintainOutbox) {
+    for (const item of outbox.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, edgeWrites, derivedUpdates, uniqueGuards, outboxEvents, idempotencyGuard, maintainWrites, maintainOutbox) {
+  const label = opRefName(contractName, methodName);
+  const base = composeFragmentTransaction(contractName, methodName, ops);
+  const { items: edgeItemsRaw, params: edgeParams } = buildEdgeWriteItems(edgeWrites);
+  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 { items: maintainItems, params: maintainParams } = buildMaintainWriteItems(maintainWrites);
+  const { items: maintainOutboxItems, params: maintainOutboxParams } = buildMaintainOutboxItems(maintainOutbox, primaryMetadata);
+  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,
+    maintainParams,
+    maintainOutboxParams
+  ]) {
+    for (const [name, spec] of Object.entries(source)) params[name] = spec;
+  }
+  const items = [
+    ...base.items,
+    ...edgeItems,
+    ...updateItems,
+    ...guardItems,
+    ...outboxItems,
+    ...idempotencyItems,
+    ...maintainItems,
+    ...maintainOutboxItems,
+    ...checkItems
+  ];
+  const categories = [
+    ...base.items.map(() => "base"),
+    ...edgeItems.map(() => "edge"),
+    ...updateItems.map(() => "derive"),
+    ...guardItems.map(() => "unique"),
+    ...outboxItems.map(() => "outbox"),
+    ...idempotencyItems.map(() => "idempotency"),
+    ...maintainItems.map(() => "maintain"),
+    ...maintainOutboxItems.map(() => "maintainOutbox"),
+    ...checkItems.map(() => "check")
+  ];
+  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 {
+    spec: { params: sortedParams(params), items, maxItems: items.length },
+    categories
+  };
+}
+function serializePreparedWriteFragment(label, fragment) {
+  const { spec, categories } = synthesizeMutationTransaction(
+    label,
+    "plan",
+    [fragment.op],
+    fragment.conditionChecks ?? [],
+    fragment.edgeWrites ?? [],
+    fragment.derivedUpdates ?? [],
+    fragment.uniqueGuards ?? [],
+    fragment.outboxEvents ?? [],
+    fragment.idempotencyGuard,
+    fragment.maintainWrites ?? [],
+    fragment.maintainOutbox ?? []
+  );
+  return { transaction: spec, categories };
+}
+function modeTargetFor(mode, op, commandSpec, contractName, methodName, opName, transactionSpecs) {
+  if (mode === "parallel") {
+    return { mode: "parallel", operation: opName };
+  }
+  const txName = batchTxName(contractName, methodName);
+  transactionSpecs[txName] = synthesizeBatchTransaction(commandSpec, op);
+  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 publishQuery / publishCommand result. Pass the value returned by publishQuery(...) / publishCommand(...).`
+      );
+    }
+    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 } : {},
+      // Pure-documentation description (issue #154); absent → byte-identical spec.
+      ...method.description !== void 0 ? { description: method.description } : {}
+    };
+  }
+  return {
+    kind: "query",
+    key: { fields: sortedKeyFields(keyFields) },
+    methods
+  };
+}
+function singleWriteTransactionToCommandSpec(contractName, methodName, tx, mode) {
+  const ctx = `Contract '${contractName}.${methodName}'`;
+  if (tx.items.length !== 1) {
+    const cause = mode === "parallel" ? "non-atomic (mode:'parallel')" : "non-atomic (no mode)";
+    throw new Error(
+      `${ctx}: a ${cause} command body must be a single write (got ${tx.items.length} items). Declare mode:'transaction' for an atomic multi-write transaction.`
+    );
+  }
+  const item = tx.items[0];
+  if (item.type === "ConditionCheck") {
+    throw new Error(
+      `${ctx}: a ConditionCheck only exists inside an atomic transaction; declare mode:'transaction'.`
+    );
+  }
+  if (item.when !== void 0 || item.guard !== void 0) {
+    throw new Error(
+      `${ctx}: a single-write body carrying a per-item guard has no plain non-atomic op form; declare mode:'transaction' (atomic) or 'parallel'.`
+    );
+  }
+  const stringTemplates = (rec, label) => {
+    if (rec === void 0) return void 0;
+    const out = {};
+    for (const [field, leaf] of Object.entries(rec)) {
+      if (typeof leaf !== "string") {
+        throw new Error(
+          `${ctx}: the ${label} field '${field}' carries a typed ${typeof leaf} literal, which the non-atomic single-op form does not yet lower; declare an explicit mode (S6 folds this uniformly).`
+        );
+      }
+      out[field] = leaf;
+    }
+    return out;
+  };
+  void mode;
+  const commandType = item.type === "Put" ? "PutItem" : item.type === "Update" ? "UpdateItem" : "DeleteItem";
+  return {
+    type: commandType,
+    tableName: item.tableName,
+    entity: item.entity,
+    params: tx.params,
+    ...item.keyCondition !== void 0 ? { keyCondition: item.keyCondition } : {},
+    ...stringTemplates(item.item, "item") !== void 0 ? { item: stringTemplates(item.item, "item") } : {},
+    ...stringTemplates(item.changes, "changes") !== void 0 ? { changes: stringTemplates(item.changes, "changes") } : {},
+    ...item.condition !== void 0 ? { condition: item.condition } : {}
+  };
+}
+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];
+    if (method.transaction !== void 0) {
+      const opName2 = opRefName(contractName, methodName);
+      if (method.mode === "transaction") {
+        transactionSpecs[opName2] = method.transaction;
+        methods[methodName] = {
+          inputArity: method.inputArity,
+          result: method.result,
+          single: { mode: "transaction", transaction: opName2 },
+          ...method.description !== void 0 ? { description: method.description } : {}
+        };
+        continue;
+      }
+      commandSpecs[opName2] = singleWriteTransactionToCommandSpec(
+        contractName,
+        methodName,
+        method.transaction,
+        method.mode
+      );
+      methods[methodName] = {
+        inputArity: method.inputArity,
+        result: method.result,
+        single: { mode: "op", operation: opName2 },
+        ...method.description !== void 0 ? { description: method.description } : {}
+      };
+      continue;
+    }
+    const op = method.op;
+    if (op === void 0) {
+      throw new Error(
+        `Contract '${contractName}.${methodName}': a command method must carry either a resolved write op or a pre-built transaction (internal invariant).`
+      );
+    }
+    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 edgeWrites = method.edgeWrites ?? [];
+    const derivedUpdates = method.derivedUpdates ?? [];
+    const uniqueGuards = method.uniqueGuards ?? [];
+    const outboxEvents = method.outboxEvents ?? [];
+    const idempotencyGuard = method.idempotencyGuard;
+    const maintainWrites = method.maintainWrites ?? [];
+    const maintainOutbox = method.maintainOutbox ?? [];
+    const hasDerivedEffects = conditionChecks.length > 0 || edgeWrites.length > 0 || derivedUpdates.length > 0 || uniqueGuards.length > 0 || outboxEvents.length > 0 || idempotencyGuard !== void 0 || maintainWrites.length > 0 || maintainOutbox.length > 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,
+          edgeWrites,
+          derivedUpdates,
+          uniqueGuards,
+          outboxEvents,
+          idempotencyGuard,
+          maintainWrites,
+          maintainOutbox
+        ).spec
+      ) : (
+        // #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 = method.mode !== void 0 && !promotedToTransaction ? modeTargetFor(
+      method.mode,
+      op,
+      commandSpec,
+      contractName,
+      methodName,
+      opName,
+      transactionSpecs
+    ) : void 0;
+    const single = promotedToTransaction ? { mode: "transaction", transaction: opName } : { mode: "op", operation: opName };
+    methods[methodName] = {
+      inputArity: method.inputArity,
+      result: method.result,
+      single,
+      ...batch !== void 0 ? { batch } : {},
+      ...returnSelection !== void 0 && Object.keys(returnSelection).length > 0 ? { returnSelection: sortedReturnSelection(returnSelection) } : {},
+      // Pure-documentation description (issue #154); absent → byte-identical spec.
+      ...method.description !== void 0 ? { description: method.description } : {}
+    };
+  }
+  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/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().flatMap((name) => {
+      const op = contract.methods[name].op;
+      return op !== void 0 ? [[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] = {
+      type: d.kind,
+      required: d.required,
+      ...d.literals !== void 0 ? { literals: d.literals } : {},
+      // Pure-documentation description (issue #154); absent → byte-identical spec.
+      ...d.description !== void 0 ? { description: d.description } : {}
+    };
+  }
+  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 injectRefsSourceProjections(ops);
+}
+function projectionFields(select) {
+  const out = [];
+  for (const [field, value] of Object.entries(select)) {
+    if (value === true || isInlineSnapshotSpec(value)) 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 === "refs") {
+      if (spec.filter !== void 0) {
+        throw new Error(
+          `Relation '${rel.propertyName}' (refs) declares a \`filter\`, which the static operations spec cannot apply (a BatchGetItem has no server-side FilterExpression and the spec runtimes run no client-side filter stage). Remove the filter from selects compiled to operations.json / generated Python, or filter in the consumer.`
+        );
+      }
+      ops.push(
+        buildRefsOperation(rel, targetMeta, childSelect, `${childPath}.items`)
+      );
+      ops.push(...buildRelationOperations(targetMeta, childSelect, `${childPath}.items`));
+      continue;
+    }
+    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 range2 = sk2 !== void 0 && sk2 !== "" ? { operator: "begins_with", key: "SK", value: sk2 } : void 0;
+      return {
+        type: "Query",
+        tableName,
+        keyCondition: keyCondition2,
+        ...range2 ? { rangeCondition: range2 } : {},
+        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 range = sk !== void 0 && sk !== "" ? { operator: "begins_with", key: `${gsi.indexName}SK`, value: sk } : void 0;
+    return {
+      type: "Query",
+      tableName,
+      indexName: gsi.indexName,
+      keyCondition,
+      ...range ? { rangeCondition: range } : {},
+      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 buildRefsOperation(rel, targetMeta, select, resultPath) {
+  const refs = rel.refs;
+  if (!refs) {
+    throw new Error(
+      `Relation '${rel.propertyName}' is type 'refs' but carries no refs binding.`
+    );
+  }
+  const { targetField, sourceField } = singleSourceField(rel);
+  const resolved = resolveKey([targetField], targetMeta);
+  if (resolved.type !== "pk" || resolved.partial) {
+    throw new Error(
+      `Relation '${rel.propertyName}' (refs) 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,
+    sourceList: { from: refs.from, key: refs.key }
+  };
+}
+function injectRefsSourceProjections(ops) {
+  for (let i = 0; i < ops.length; i++) {
+    const op = ops[i];
+    if (op.sourceList === void 0) continue;
+    const tokens = op.resultPath.split(".");
+    const parentPath = tokens.slice(0, -2).join(".") || "$";
+    const parentIndex = ops.findIndex((p) => p.resultPath === parentPath);
+    if (parentIndex === -1) {
+      throw new Error(
+        `refs fan-out at '${op.resultPath}': no parent operation at '${parentPath}'.`
+      );
+    }
+    const parent = ops[parentIndex];
+    const from = op.sourceList.from;
+    if (parent.projection.includes(from)) {
+      continue;
+    }
+    ops[parentIndex] = {
+      ...parent,
+      projection: [...parent.projection, from].sort()
+    };
+    ops[i] = { ...op, sourceList: { ...op.sourceList, implicit: true } };
+  }
+  return ops;
+}
+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);
+  const description = def.description !== void 0 ? { description: def.description } : {};
+  if (def.operation === "put") {
+    const item = templateRecord(def.key);
+    return {
+      type: "PutItem",
+      tableName,
+      entity,
+      params,
+      item,
+      ...condition ? { condition } : {},
+      ...description
+    };
+  }
+  if (def.operation === "delete") {
+    return {
+      type: "DeleteItem",
+      tableName,
+      entity,
+      params,
+      keyCondition: writeKeyCondition(metadata, def.key, entity),
+      ...condition ? { condition } : {},
+      ...description
+    };
+  }
+  return {
+    type: "UpdateItem",
+    tableName,
+    entity,
+    params,
+    keyCondition: writeKeyCondition(metadata, def.key, entity),
+    changes: templateRecord(def.changes),
+    ...condition ? { condition } : {},
+    ...description
+  };
+}
+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 templateRecord(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),
+    (value, name) => conditionTreeLeaf(value, name),
+    // A raw `cond` value slot (issue #114-B): a contract param / key ref carries
+    // its own name; a plain `param.*` falls through to the positional default.
+    (part) => {
+      if (isContractParamRef(part)) return { $param: tokenName(part.token) };
+      if (isContractKeyFieldRef(part)) return { $param: part.field };
+      return void 0;
+    }
+  );
+}
+function conditionTreeLeaf(value, name) {
+  if (isContractParamRef(value)) return { $param: tokenName(value.token) };
+  if (isContractKeyFieldRef(value)) return { $param: value.field };
+  if (isParam(value)) return { $param: name };
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  throw new Error(
+    `A declarative write-condition operand must be a concrete literal or a param reference; got ${typeof value}.`
+  );
+}
+function tokenName(token) {
+  return token.startsWith("{") && token.endsWith("}") ? token.slice(1, -1) : token;
+}
+function buildQuerySpec(def) {
+  const operations = buildReadOperations(def);
+  const executionPlan = deriveExecutionPlan(operations.map((op) => op.resultPath));
+  return {
+    params: paramSpecs(def.params),
+    operations,
+    // operation 'query' → a single entity object; 'list' → a connection.
+    cardinality: def.operation === "query" ? "one" : "many",
+    ...executionPlan !== void 0 ? { executionPlan } : {},
+    // Pure-documentation description (issue #154); absent → byte-identical spec.
+    ...def.description !== void 0 ? { description: def.description } : {}
+  };
+}
+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);
+  const content = {
+    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 } : {}
+  };
+  return {
+    version: operationsSpecVersion(content),
+    ...content
+  };
+}
+
+// src/spec/prepared.ts
+function bindOfSlot(slot, where) {
+  if (slot.kind === "param") return { param: slot.name };
+  const v = slot.value;
+  if (v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+    return { literal: v };
+  }
+  if (v instanceof Date) return { literalDate: v.toISOString() };
+  if (typeof v === "bigint") return { literalBigInt: v.toString() };
+  throw new Error(
+    `prepared AOT: ${where} carries a non-serializable literal (${typeof v}).`
+  );
+}
+function bindMapOf(slots, where) {
+  const out = {};
+  for (const [field, slot] of Object.entries(slots)) {
+    out[field] = bindOfSlot(slot, `${where} field '${field}'`);
+  }
+  return out;
+}
+function paramKindForField(metadata, field) {
+  const f = metadata.fields.find((x) => x.propertyName === field);
+  return f?.dynamoType === "N" ? "number" : "string";
+}
+function addParam(params, name, kind) {
+  if (!(name in params)) params[name] = { type: kind, required: true };
+}
+function readRouteQuerySpec(route, metadata) {
+  const params = {};
+  const key = {};
+  for (const field of Object.keys(route.keySlots)) {
+    const kind = paramKindForField(metadata, field);
+    params[field] = { kind, required: true };
+    key[field] = kind === "number" ? param.number() : param.string();
+  }
+  const def = {
+    __isOperationDefinition: true,
+    entity: { name: route.modelClass.name, modelClass: route.modelClass },
+    operation: route.kind === "query" ? "query" : "list",
+    key,
+    select: route.select,
+    params
+  };
+  return buildQuerySpec(def);
+}
+function compileReadPlan(routes) {
+  const specs = [];
+  const params = {};
+  const entities = {};
+  for (const { alias, route } of routes) {
+    const compiled = compileReadRoute(alias, route);
+    const metadata = MetadataRegistry.get(compiled.modelClass);
+    const entityName = compiled.modelClass.name;
+    entities[entityName] = entityFingerprint(metadata);
+    for (const [field, slot] of Object.entries(compiled.keySlots)) {
+      if (slot.kind === "param") {
+        addParam(params, slot.name, paramKindForField(metadata, field));
+      }
+    }
+    const dynamicParam = (slot, kind) => {
+      if (slot?.kind === "param") addParam(params, slot.name, kind);
+    };
+    dynamicParam(compiled.limitSlot, "number");
+    dynamicParam(compiled.afterSlot, "string");
+    dynamicParam(compiled.consistentReadSlot, "string");
+    specs.push({
+      alias,
+      op: compiled.kind,
+      entity: entityName,
+      select: compiled.select,
+      key: bindMapOf(compiled.keySlots, `${alias} key`),
+      ...compiled.maxDepth !== void 0 ? { maxDepth: compiled.maxDepth } : {},
+      ...compiled.order !== void 0 ? { order: compiled.order } : {},
+      ...compiled.filter !== void 0 ? { filter: compiled.filter } : {},
+      ...compiled.consistentReadSlot !== void 0 ? { consistentRead: bindOfSlot(compiled.consistentReadSlot, `${alias} consistentRead`) } : {},
+      ...compiled.limitSlot !== void 0 ? { limit: bindOfSlot(compiled.limitSlot, `${alias} limit`) } : {},
+      ...compiled.afterSlot !== void 0 ? { after: bindOfSlot(compiled.afterSlot, `${alias} after`) } : {},
+      query: readRouteQuerySpec(compiled, metadata)
+    });
+  }
+  return { kind: "read", params, entities, reads: specs };
+}
+function compileWritePlan(routes, planLabel) {
+  const specs = [];
+  const params = {};
+  const entities = {};
+  for (const { alias, route } of routes) {
+    const analyzed = analyzeWriteRoute(alias, route);
+    if (analyzed.intent === "create" && analyzed.conditionSlots !== void 0) {
+      throw new Error(
+        `prepared AOT (${planLabel} '${alias}'): a \`condition\` on a 'create' is not supported \u2014 a create already guards with attribute_not_exists(PK). Use an 'update' with a condition, or drop the condition.`
+      );
+    }
+    const modelClass = resolveModelClass(analyzed.model);
+    const metadata = MetadataRegistry.get(modelClass);
+    const entityName = modelClass.name;
+    entities[entityName] = entityFingerprint(metadata);
+    const fragment = compileWriteFragment({
+      alias,
+      intent: analyzed.intent,
+      model: analyzed.model,
+      keyFieldNames: analyzed.keyFields,
+      inputFieldNames: analyzed.inputFields
+    });
+    const { transaction, categories } = serializePreparedWriteFragment(
+      `${planLabel}.${alias}`,
+      fragment
+    );
+    for (const item of transaction.items) {
+      if (item.literalKey === true || item.entity === MARKER_ROW_ENTITY) continue;
+      if (item.entity in entities) continue;
+      const cls = resolveRegisteredModel(item.entity, `${planLabel}.${alias}`);
+      entities[item.entity] = entityFingerprint(MetadataRegistry.get(cls));
+    }
+    for (const [field, slot] of Object.entries({
+      ...analyzed.inputSlots,
+      ...analyzed.keySlots,
+      ...analyzed.conditionSlots ?? {}
+    })) {
+      if (slot.kind === "param") {
+        addParam(params, slot.name, paramKindForField(metadata, field));
+      }
+    }
+    let readback;
+    const resultSelect = analyzed.result?.select;
+    if (resultSelect !== void 0 && Object.keys(resultSelect).length > 0) {
+      const kf = {};
+      const kp = {};
+      for (const field of fragment.keyFields) {
+        const kind = paramKindForField(metadata, field);
+        kp[field] = { kind, required: true };
+        kf[field] = kind === "number" ? param.number() : param.string();
+      }
+      readback = buildQuerySpec({
+        __isOperationDefinition: true,
+        entity: { name: entityName, modelClass },
+        operation: "query",
+        key: kf,
+        select: resultSelect,
+        params: kp
+      });
+    }
+    specs.push({
+      alias,
+      entity: entityName,
+      intent: analyzed.intent,
+      keyFields: fragment.keyFields,
+      key: bindMapOf(analyzed.keySlots, `${alias} key`),
+      input: bindMapOf(analyzed.inputSlots, `${alias} input`),
+      ...analyzed.conditionSlots !== void 0 ? { condition: bindMapOf(analyzed.conditionSlots, `${alias} condition`) } : {},
+      ...analyzed.result !== void 0 ? { result: analyzed.result } : {},
+      ...readback !== void 0 ? { readback } : {},
+      transaction,
+      categories
+    });
+  }
+  return { kind: "write", params, entities, writes: specs };
+}
+function resolveRegisteredModel(name, label) {
+  for (const cls of MetadataRegistry.getAll().keys()) {
+    if (cls.name === name) {
+      return cls;
+    }
+  }
+  throw new Error(
+    `prepared AOT (${label}): a derived effect targets entity '${name}', which is not a registered model.`
+  );
+}
+function compilePreparedPlan(body, planLabel = "prepared") {
+  const { kind, routes } = evaluatePreparedRoutes(body);
+  if (kind === "read") {
+    return compileReadPlan(
+      routes
+    );
+  }
+  return compileWritePlan(
+    routes,
+    planLabel
+  );
+}
+function buildPreparedPlanDocument(plans) {
+  const sorted = {};
+  for (const id of Object.keys(plans).sort()) sorted[id] = plans[id];
+  return {
+    formatVersion: PREPARED_FORMAT_VERSION,
+    specVersion: SPEC_VERSION,
+    plans: sorted
+  };
+}
+
+// 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 {
+  collectContractN1Violations,
+  assertContractN1Safe,
+  buildContracts,
+  buildContexts,
+  collectContractBoundaryViolations,
+  assertContractBoundaries,
+  buildQuerySpec,
+  buildOperations,
+  compilePreparedPlan,
+  buildPreparedPlanDocument,
+  buildBridgeBundle
+};