graphddb 0.5.3 → 0.7.0

package/dist/{chunk-Y7XV5QL2.js → chunk-GFGVDF4W.js}

@@ -22,14 +22,17 @@ import {
   commitTransaction,
   compileRawCondition,
   ctxModelFor,
+  detectRelationFields,
   execItemKeySignature,
   executeDelete,
   executePut,
   executeTransaction,
   executeUpdate,
   getEntityWrites,
+  getImplicitKeyFields,
   hydrate,
   isEntityWritesDefinition,
+  isInlineSnapshotSpec,
   isLifecycleContract,
   isParam,
   isRawCondition,
@@ -44,8 +47,9 @@ import {
   resolveSegmentedKey,
   serializeFieldValue,
   serializeRawCondition,
-  skTemplate
-} from "./chunk-CCIVET5K.js";
+  skTemplate,
+  validateInlineSnapshotSelect
+} from "./chunk-F2DI3GTI.js";
 import {
   TableMapping,
   createColumnMap,
@@ -116,6 +120,10 @@ function buildRelations(metadata) {
       type: rel.type,
       target: targetClass.name,
       keyBinding: { ...rel.keyBinding },
+      // List-valued source descriptor for a `refs` relation (issue #197); emitted
+      // only for `refs` so a scalar-keyed relation is byte-identical to the pre-#197
+      // manifest.
+      ...rel.refs !== void 0 ? { refs: { ...rel.refs } } : {},
       // Purely-documentary relation description (issue #166); emitted only when
       // declared so an undescribed relation is byte-identical to the pre-#166 manifest.
       ...rel.options?.description !== void 0 ? { description: rel.options.description } : {}
@@ -190,36 +198,6 @@ function buildManifest(registry = MetadataRegistry) {
   };
 }
 
-// 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/planner/projection.ts
 function buildProjection(select, additionalFields) {
   const paths = [];
@@ -237,6 +215,8 @@ function buildProjection(select, additionalFields) {
     for (const [fieldName, value] of Object.entries(selectObj)) {
       if (value === true) {
         addPath([...parentSegments, fieldName]);
+      } else if (isInlineSnapshotSpec(value)) {
+        addPath([...parentSegments, fieldName]);
       } else if (typeof value === "object" && value !== null) {
         if ("select" in value || isSelectBuilder(value)) {
           continue;
@@ -702,6 +682,11 @@ async function executeListInternal(modelClass, key, selectSpec, options = {}) {
   const after = options.after ?? normalized.after;
   const limit = options.limit ?? normalized.limit;
   const order = options.order ?? normalized.order;
+  validateInlineSnapshotSelect(
+    select,
+    metadata,
+    (rel) => MetadataRegistry.get(rel.targetFactory())
+  );
   const exclusiveStartKey = after ? decodeCursor(after) : void 0;
   const implicitKeys = getImplicitKeyFields(select, metadata);
   const executionPlan = plan(metadata, {
@@ -970,7 +955,7 @@ function relationResultPaths(select, metadata, parentPath = "$") {
     const childSelect = normalizeSelectSpec(select[rel.propertyName]).select ?? {};
     const targetMeta = MetadataRegistry.get(rel.targetFactory());
     const childPath = `${parentPath}.${rel.propertyName}`;
-    const isMany = rel.type === "hasMany";
+    const isMany = rel.type === "hasMany" || rel.type === "refs";
     const resultPath = isMany ? `${childPath}.items` : childPath;
     out.push({
       propertyName: rel.propertyName,
@@ -1064,7 +1049,7 @@ function validateDepth(select, metadata, maxDepth, currentDepth = 1) {
 }
 function relationResultPath(parentPath, rel) {
   const base = `${parentPath}.${rel.propertyName}`;
-  return rel.type === "hasMany" ? `${base}.items` : base;
+  return rel.type === "hasMany" || rel.type === "refs" ? `${base}.items` : base;
 }
 function stageRelations(relations, parentPath, plan2) {
   if (plan2 === void 0 || relations.length === 0) {
@@ -1188,6 +1173,95 @@ async function fetchBelongsToHasOneBatch(rel, rawParentItems, selectSpec, target
   );
   return results;
 }
+async function fetchRefsList(rel, rawParentItem, selectSpec, targetMeta, options, currentDepth, ownPath) {
+  const refsBinding = rel.refs;
+  if (!refsBinding) {
+    throw new Error(
+      `Relation '${rel.propertyName}' is type 'refs' but carries no refs binding.`
+    );
+  }
+  const [targetKeyField] = Object.keys(rel.keyBinding);
+  const rawList = rawParentItem[refsBinding.from];
+  const elements = Array.isArray(rawList) ? rawList : [];
+  const queryKeys = [];
+  for (const element of elements) {
+    const refValue = element != null && typeof element === "object" ? element[refsBinding.key] : element;
+    if (refValue == null) continue;
+    queryKeys.push({ [targetKeyField]: refValue });
+  }
+  if (queryKeys.length === 0) {
+    return [];
+  }
+  const implicitKeys = getImplicitKeyFields(selectSpec.select, targetMeta);
+  const projectionExtras = options.updatable ? [...implicitKeys, "PK", "SK"] : implicitKeys;
+  const batchOps = planBatchGetForQueryKeys(
+    targetMeta,
+    queryKeys,
+    selectSpec.select,
+    projectionExtras.length > 0 ? projectionExtras : void 0
+  );
+  const executor = ClientManager.getExecutor();
+  const queryKeyToRaw = /* @__PURE__ */ new Map();
+  const mw = options.mw ?? NO_MIDDLEWARE;
+  const opPath = [...options.relationPath ?? [], rel.propertyName];
+  const opModel = mw.active ? ctxModelFor(rel.targetFactory()) : void 0;
+  for (const operation of batchOps) {
+    const items = mw.active ? await mw.runOp(
+      operation,
+      opPath,
+      opModel,
+      (op) => executor.batchGet(
+        op,
+        options.retry !== void 0 ? { retry: options.retry } : void 0
+      ).then((r) => r.items)
+    ) : (await executor.batchGet(
+      operation,
+      options.retry !== void 0 ? { retry: options.retry } : void 0
+    )).items;
+    for (const item of items) {
+      for (const queryKey of queryKeys) {
+        if (!matchesQueryKey(item, queryKey)) continue;
+        queryKeyToRaw.set(serializeQueryKey(queryKey), item);
+      }
+    }
+  }
+  const nestedRelations = detectRelationFields(selectSpec.select, targetMeta);
+  const seen = /* @__PURE__ */ new Set();
+  const orderedKeys = [];
+  for (const queryKey of queryKeys) {
+    const serialized = serializeQueryKey(queryKey);
+    if (seen.has(serialized)) continue;
+    seen.add(serialized);
+    orderedKeys.push(queryKey);
+  }
+  const resolved = orderedKeys.map(() => null);
+  await mapWithConcurrency(
+    orderedKeys,
+    options.plan?.plan.concurrency ?? RELATION_TRAVERSAL_CONCURRENCY,
+    async (queryKey, index) => {
+      const raw = queryKeyToRaw.get(serializeQueryKey(queryKey));
+      if (!raw) return;
+      const updatable = options.updatable ?? false;
+      let item = hydrate([raw], selectSpec.select, targetMeta, updatable)[0] ?? null;
+      if (item && nestedRelations.length > 0) {
+        item = await resolveRelations(
+          item,
+          raw,
+          selectSpec.select,
+          targetMeta,
+          options,
+          currentDepth + 1,
+          ownPath
+        );
+        if (item && updatable) attachHiddenKey(item, raw);
+      }
+      if (item && passesPostLoad(item, selectSpec, targetMeta)) {
+        resolved[index] = item;
+      }
+    }
+  );
+  return resolved.filter((item) => item !== null);
+}
 function passesPostLoad(item, spec, targetMeta) {
   if (spec.filter && !evaluateFilterClientSide(item, spec.filter, targetMeta)) {
     return false;
@@ -1270,6 +1344,21 @@ async function resolveRelations(parentItem, rawParentItem, select, metadata, opt
       };
       return;
     }
+    if (rel.type === "refs") {
+      const targetClass2 = rel.targetFactory();
+      const targetMeta2 = MetadataRegistry.get(targetClass2);
+      const items = await fetchRefsList(
+        rel,
+        rawParentItem,
+        selectSpec,
+        targetMeta2,
+        opts,
+        currentDepth,
+        ownPath
+      );
+      result[rel.propertyName] = { items, cursor: null };
+      return;
+    }
     const targetClass = rel.targetFactory();
     const targetMeta = MetadataRegistry.get(targetClass);
     const [resolvedItem] = await fetchBelongsToHasOneBatch(
@@ -1329,6 +1418,11 @@ async function executeQueryInner(modelClass, key, selectSpec, options, mw) {
   const normalized = normalizeTopLevelSelect(selectSpec);
   const select = normalized.select;
   const filter = normalized.filter;
+  validateInlineSnapshotSelect(
+    select,
+    metadata,
+    (rel) => MetadataRegistry.get(rel.targetFactory())
+  );
   const maxDepth = options?.maxDepth ?? 1;
   const relations = detectRelationFields(select, metadata);
   if (relations.length > 0) {
@@ -1346,8 +1440,13 @@ async function executeQueryInner(modelClass, key, selectSpec, options, mw) {
   });
   const operation = executionPlan.operations[0];
   const canParallelizeRelations = relations.length > 0 && relations.every(
-    (rel) => Object.values(rel.keyBinding).every(
-      (sourceField) => key[sourceField] != null
+    (rel) => (
+      // A `refs` relation (issue #197) resolves from the parent row's inline
+      // id-list (`refs.from`), which only exists on the FETCHED parent — never the
+      // input key — so it can never be dispatched before the parent read.
+      rel.type !== "refs" && Object.values(rel.keyBinding).every(
+        (sourceField) => key[sourceField] != null
+      )
     )
   );
   const retry = options?.retry;
@@ -1887,7 +1986,7 @@ function deriveOneConditionCheck(fragment, req) {
   return { entity: { name: targetName, modelClass: targetClass }, keyBinding };
 }
 function deriveEdgeWrites(fragment, edges, lifecycle) {
-  return edges.map((edge) => deriveOneEdgeWrite(fragment, edge, lifecycle));
+  return edges.flatMap((edge) => deriveOneEdgeWrite(fragment, edge, lifecycle));
 }
 function deriveOneEdgeWrite(fragment, edge, lifecycle) {
   const targetClass = edge.targetFactory();
@@ -1903,16 +2002,48 @@ function deriveOneEdgeWrite(fragment, edge, lifecycle) {
     );
   }
   const adjacencyClass = relation.targetFactory();
-  const items = deriveEdgeWriteItemsFor(
+  if (edge.inverse === void 0) {
+    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
+      }
+    ];
+  }
+  const inverseAdjacency = edge.inverse.adjacencyFactory();
+  const allItems = deriveEdgeWriteItemsFor(
     adjacencyClass,
-    { targetFactory: edge.targetFactory, relationProperty: edge.relationProperty },
+    {
+      targetFactory: edge.targetFactory,
+      relationProperty: edge.relationProperty,
+      inverse: edge.inverse
+    },
     lifecycle
   );
-  return {
-    entity: { name: adjacencyClass.name, modelClass: adjacencyClass },
-    relation: { target: targetClass.name, property: edge.relationProperty },
-    items
-  };
+  const forwardItems = allItems.filter((it) => it.entity === adjacencyClass.name);
+  const inverseItems = allItems.filter((it) => it.entity === inverseAdjacency.name);
+  const inverseTargetClass = edge.inverse.targetFactory();
+  return [
+    {
+      entity: { name: adjacencyClass.name, modelClass: adjacencyClass },
+      relation: { target: targetClass.name, property: edge.relationProperty },
+      items: forwardItems
+    },
+    {
+      entity: { name: inverseAdjacency.name, modelClass: inverseAdjacency },
+      relation: {
+        target: inverseTargetClass.name,
+        property: edge.inverse.relationProperty
+      },
+      items: inverseItems
+    }
+  ];
 }
 function deriveUpdates(fragment, derive) {
   return derive.map((d) => deriveOneUpdate(fragment, d));
@@ -3629,17 +3760,15 @@ function normalizeWriteOp(alias, d) {
   }
   return [{ ...base, key: d.key }];
 }
-function compileWriteOp(op) {
-  const keyFieldNames2 = Object.keys(op.key);
-  const inputFieldNames = Object.keys(op.input);
-  const model = op.model;
+function compileWriteFragment(input) {
+  const { alias, intent, model, keyFieldNames: keyFieldNames2, inputFieldNames } = input;
   const body = ($) => {
     const descriptor = {
-      [op.intent]: (() => model),
+      [intent]: (() => model),
       key: mapToRefs($, keyFieldNames2),
       ...inputFieldNames.length > 0 ? { input: mapToRefs($, inputFieldNames) } : {}
     };
-    const map = { [op.alias]: descriptor };
+    const map = { [alias]: descriptor };
     return map;
   };
   const plan2 = mutation(body);
@@ -3647,7 +3776,16 @@ function compileWriteOp(op) {
     throw new Error("DDBModel.mutate: internal error building the mutation plan.");
   }
   const compiled = compileMutationPlan(plan2);
-  const fragment = compiled.fragments[0];
+  return compiled.fragments[0];
+}
+function compileWriteOp(op) {
+  const fragment = compileWriteFragment({
+    alias: op.alias,
+    intent: op.intent,
+    model: op.model,
+    keyFieldNames: Object.keys(op.key),
+    inputFieldNames: Object.keys(op.input)
+  });
   const params = { ...op.input, ...op.key };
   return {
     fragment,
@@ -3716,6 +3854,445 @@ function resolveModelStatic(ref, alias) {
   return ref;
 }
 
+// src/runtime/prepared.ts
+var PREPARE_LABEL = "DDBModel.prepare";
+var PARAM_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:preparedParamRef");
+function isPreparedParamRef(value) {
+  return typeof value === "object" && value !== null && value[PARAM_REF_BRAND] === true;
+}
+function makeParamRef(name) {
+  const origin = `the placeholder '${name}' (\`$.${name}\`)`;
+  const target = /* @__PURE__ */ Object.create(null);
+  const proxy = new Proxy(target, {
+    get(_t, prop) {
+      if (prop === PARAM_REF_BRAND) return true;
+      if (prop === "name") return name;
+      if (typeof prop === "symbol") return void 0;
+      throw new Error(
+        `${PREPARE_LABEL}: unsupported access '${String(prop)}' on ${origin}. A \`key\` / \`input\` / option value only supports a direct \`$.name\` param reference or a concrete static literal \u2014 never a transform, a nested access, or a coercion (that would capture a per-call runtime value).`
+      );
+    },
+    set() {
+      throw new Error(`${PREPARE_LABEL}: cannot assign on ${origin}.`);
+    }
+  });
+  return proxy;
+}
+function makePreparedInputProxy() {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(_t, prop) {
+      if (typeof prop === "symbol") return void 0;
+      const name = prop;
+      let ref = cache.get(name);
+      if (!ref) {
+        ref = makeParamRef(name);
+        cache.set(name, ref);
+      }
+      return ref;
+    },
+    set() {
+      throw new Error(`${PREPARE_LABEL}: cannot assign to the \`$\` placeholder proxy.`);
+    }
+  });
+}
+function assertNoRuntimeCapture(value, where) {
+  if (isPreparedParamRef(value)) return;
+  if (value === null) return;
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean" || t === "bigint") return;
+  if (value instanceof Date) return;
+  if (t === "undefined") {
+    throw new Error(
+      `${PREPARE_LABEL}: ${where} is undefined. Bind a \`$.name\` param reference or a concrete static literal \u2014 or omit the field from the template entirely.`
+    );
+  }
+  if (t === "function") {
+    throw new Error(
+      `${PREPARE_LABEL}: ${where} is a function. A prepared body may only bind a \`$.name\` param reference or a static literal here; a function is a captured per-call value (no runtime capture \u2014 see the prepared-statement contract).`
+    );
+  }
+  if (t === "symbol") {
+    throw new Error(`${PREPARE_LABEL}: ${where} is a symbol, which is not a bindable value.`);
+  }
+  throw new Error(
+    `${PREPARE_LABEL}: ${where} is a non-literal object. A prepared body may only bind a \`$.name\` param reference or a static literal here \u2014 an object value is a captured per-call runtime value.`
+  );
+}
+function recordSlots(binding, where) {
+  const fields = Object.keys(binding);
+  const slots = {};
+  for (const f of fields) {
+    const v = binding[f];
+    if (isPreparedParamRef(v)) {
+      slots[f] = { kind: "param", name: v.name };
+    } else {
+      assertNoRuntimeCapture(v, `${where} field '${f}'`);
+      slots[f] = { kind: "literal", value: v };
+    }
+  }
+  return { fields, slots };
+}
+function bindSlots(slots, params) {
+  const out = {};
+  for (const [field, slot] of Object.entries(slots)) {
+    out[field] = slot.kind === "param" ? params[slot.name] : slot.value;
+  }
+  return out;
+}
+function bindOptionalSlot(slot, params) {
+  if (slot === void 0) return void 0;
+  return slot.kind === "param" ? params[slot.name] : slot.value;
+}
+function recordOptionSlot(value, where) {
+  if (value === void 0) return void 0;
+  if (isPreparedParamRef(value)) return { kind: "param", name: value.name };
+  assertNoRuntimeCapture(value, where);
+  return { kind: "literal", value };
+}
+var PreparedWriteStatement = class {
+  /** @internal */
+  constructor(ops) {
+    this.ops = ops;
+  }
+  ops;
+  async execute(params = {}, options = {}) {
+    const compiled = this.ops.map((op) => ({
+      fragment: op.fragment,
+      params: { ...bindSlots(op.inputSlots, params), ...bindSlots(op.keySlots, params) },
+      ...op.conditionSlots !== void 0 ? { condition: bindSlots(op.conditionSlots, params) } : {},
+      ...op.result !== void 0 ? { result: op.result } : {}
+    }));
+    const mode = options.mode ?? "transaction";
+    const runOpts = {
+      label: PREPARE_LABEL,
+      ...options.retry !== void 0 ? { retry: options.retry } : {},
+      ...options.context !== void 0 ? { context: options.context } : {}
+    };
+    if (mode === "transaction") {
+      const { readBacks } = await executeCompiledWriteOp(compiled, runOpts);
+      const out2 = {};
+      this.ops.forEach((op, i) => {
+        if (op.result !== void 0) out2[op.alias] = readBacks[i];
+      });
+      return out2;
+    }
+    const settled = await executeCompiledParallelWrites(compiled, runOpts);
+    const out = {};
+    this.ops.forEach((op, i) => {
+      const res = settled[i];
+      out[op.alias] = res.ok ? { ok: true, value: op.result !== void 0 ? res.value : void 0 } : { ok: false, error: res.error };
+    });
+    return out;
+  }
+};
+var PreparedReadStatement = class {
+  /** @internal */
+  constructor(routes) {
+    this.routes = routes;
+  }
+  routes;
+  async execute(params = {}, options = {}) {
+    const results = await Promise.all(
+      this.routes.map((route) => this.runRoute(route, params, options))
+    );
+    const out = {};
+    this.routes.forEach((route, i) => {
+      out[route.alias] = results[i];
+    });
+    return out;
+  }
+  runRoute(route, params, options) {
+    const key = bindSlots(route.keySlots, params);
+    const consistentRead = bindOptionalSlot(route.consistentReadSlot, params);
+    if (route.kind === "query") {
+      return executeQuery(route.modelClass, key, route.select, {
+        consistentRead,
+        maxDepth: route.maxDepth,
+        ...options.retry !== void 0 ? { retry: options.retry } : {},
+        ...options.context !== void 0 ? { context: options.context } : {}
+      });
+    }
+    const limit = bindOptionalSlot(route.limitSlot, params);
+    const after = bindOptionalSlot(route.afterSlot, params);
+    return executeList(route.modelClass, key, route.select, {
+      limit,
+      after,
+      order: route.order,
+      filter: route.filter,
+      ...options.retry !== void 0 ? { retry: options.retry } : {},
+      ...options.context !== void 0 ? { context: options.context } : {}
+    });
+  }
+};
+var READ_INTENT_KEYS = ["query", "list"];
+function classify(routes) {
+  let kind;
+  for (const { alias, route } of routes) {
+    const rec = route;
+    const isRead = READ_INTENT_KEYS.some((k) => rec[k] !== void 0);
+    const isWrite = INTENT_KEYS.some((k) => rec[k] !== void 0);
+    if (isRead === isWrite) {
+      throw new Error(
+        `${PREPARE_LABEL}: the descriptor for alias '${alias}' must carry exactly one of a read intent (\`query\` / \`list\`) OR a write intent (\`create\` / \`update\` / \`remove\`). It declared ${isRead && isWrite ? "both" : "neither"}.`
+      );
+    }
+    const routeKind = isRead ? "read" : "write";
+    if (kind === void 0) kind = routeKind;
+    else if (kind !== routeKind) {
+      throw new Error(
+        `${PREPARE_LABEL}: a prepared body must be all-read or all-write; alias '${alias}' is a ${routeKind} route but a previous alias was a ${kind} route. Split them into two prepared statements.`
+      );
+    }
+  }
+  if (kind === void 0) {
+    throw new Error(
+      `${PREPARE_LABEL}: the prepared body declared no routes. Declare at least one \`{ alias: { query|list|create|update|remove: () => Model, key, ... } }\`.`
+    );
+  }
+  return kind;
+}
+function compileWriteRoute(alias, route) {
+  const present = INTENT_KEYS.filter((k) => route[k] !== void 0);
+  if (present.length !== 1) {
+    throw new Error(
+      `${PREPARE_LABEL}: the write descriptor for alias '${alias}' must carry exactly one intent (\`create\` / \`update\` / \`remove\`), but declared ${present.length === 0 ? "none" : present.join(", ")}.`
+    );
+  }
+  const intent = present[0];
+  if (route.key === null || typeof route.key !== "object") {
+    throw new Error(
+      `${PREPARE_LABEL}: the '${intent}' descriptor for alias '${alias}' must declare a \`key\` object binding the target's primary-key fields.`
+    );
+  }
+  const model = resolveModelStatic(route[intent], alias);
+  const keyRec = recordSlots(route.key, `${alias} key`);
+  const inputRec = recordSlots(
+    route.input ?? {},
+    `${alias} input`
+  );
+  const conditionRec = route.condition !== void 0 ? recordSlots(route.condition, `${alias} condition`) : void 0;
+  if (route.result !== void 0) assertStaticTemplate(route.result, `${alias} result`);
+  const fragment = compileWriteFragment({
+    alias,
+    intent,
+    model,
+    keyFieldNames: keyRec.fields,
+    inputFieldNames: inputRec.fields
+  });
+  return {
+    alias,
+    intent,
+    fragment,
+    keySlots: keyRec.slots,
+    inputSlots: inputRec.slots,
+    ...conditionRec !== void 0 ? { conditionSlots: conditionRec.slots } : {},
+    ...route.result !== void 0 ? { result: route.result } : {}
+  };
+}
+function compileReadRoute(alias, route) {
+  const isQuery = route.query !== void 0;
+  const isList = route.list !== void 0;
+  if (isQuery === isList) {
+    throw new Error(
+      `${PREPARE_LABEL}: the read descriptor for alias '${alias}' must carry exactly one of \`query\` or \`list\`. It declared ${isQuery && isList ? "both" : "neither"}.`
+    );
+  }
+  if (route.key === null || typeof route.key !== "object" || route.select === void 0) {
+    throw new Error(
+      `${PREPARE_LABEL}: the '${isQuery ? "query" : "list"}' descriptor for alias '${alias}' must declare both \`key\` and \`select\`.`
+    );
+  }
+  const model = resolveModelStatic(isQuery ? route.query : route.list, alias);
+  const modelClass = resolveModelClass(model);
+  const keyRec = recordSlots(route.key, `${alias} key`);
+  assertStaticTemplate(route.select, `${alias} select`);
+  const opt = route.options ?? {};
+  if (isQuery) {
+    for (const unsupported of ["limit", "after", "order", "filter"]) {
+      if (opt[unsupported] !== void 0) {
+        throw new Error(
+          `${PREPARE_LABEL}: the 'query' descriptor for alias '${alias}' declares \`options.${unsupported}\`, which a single-entity query does not support (a query supports \`consistentRead\` / \`maxDepth\`). Use a \`list\` route for pagination / ordering / filtering.`
+        );
+      }
+    }
+  } else if (opt.consistentRead !== void 0) {
+    throw new Error(
+      `${PREPARE_LABEL}: the 'list' descriptor for alias '${alias}' declares \`options.consistentRead\`, which \`Model.list\` does not support \u2014 it would be silently ignored. Remove it (a list always reads eventually consistent).`
+    );
+  }
+  if (opt.filter !== void 0) {
+    assertStaticTemplate(opt.filter, `${alias} options.filter`);
+  }
+  return {
+    alias,
+    kind: isQuery ? "query" : "list",
+    modelClass,
+    select: route.select,
+    keySlots: keyRec.slots,
+    ...typeof opt.maxDepth === "number" ? { maxDepth: opt.maxDepth } : {},
+    ...opt.order !== void 0 ? { order: opt.order } : {},
+    ...opt.filter !== void 0 ? { filter: opt.filter } : {},
+    ...(() => {
+      const s = recordOptionSlot(opt.consistentRead, `${alias} options.consistentRead`);
+      return s !== void 0 ? { consistentReadSlot: s } : {};
+    })(),
+    ...(() => {
+      const s = recordOptionSlot(opt.limit, `${alias} options.limit`);
+      return s !== void 0 ? { limitSlot: s } : {};
+    })(),
+    ...(() => {
+      const s = recordOptionSlot(opt.after, `${alias} options.after`);
+      return s !== void 0 ? { afterSlot: s } : {};
+    })()
+  };
+}
+function assertStaticTemplate(value, where) {
+  if (isPreparedParamRef(value)) {
+    throw new Error(
+      `${PREPARE_LABEL}: ${where} is a \`$\` param reference. This position is a static projection / template \u2014 only \`key\` (and the dynamic pagination options) may bind params.`
+    );
+  }
+  if (typeof value === "function") {
+    throw new Error(
+      `${PREPARE_LABEL}: ${where} is a function \u2014 a captured per-call value (no runtime capture). This position must be a static, params-independent template.`
+    );
+  }
+  if (value !== null && typeof value === "object") {
+    if (Array.isArray(value)) {
+      value.forEach((v, i) => assertStaticTemplate(v, `${where}[${i}]`));
+    } else {
+      for (const [k, v] of Object.entries(value)) {
+        assertStaticTemplate(v, `${where}.${k}`);
+      }
+    }
+  }
+}
+var PREPARE_CACHE_MAX = 256;
+var BoundedLru = class {
+  constructor(max) {
+    this.max = max;
+  }
+  max;
+  map = /* @__PURE__ */ new Map();
+  get(key) {
+    const v = this.map.get(key);
+    if (v !== void 0) {
+      this.map.delete(key);
+      this.map.set(key, v);
+    }
+    return v;
+  }
+  set(key, value) {
+    if (this.map.has(key)) this.map.delete(key);
+    this.map.set(key, value);
+    if (this.map.size > this.max) {
+      const oldest = this.map.keys().next().value;
+      if (oldest !== void 0) this.map.delete(oldest);
+    }
+  }
+  get size() {
+    return this.map.size;
+  }
+  clear() {
+    this.map.clear();
+  }
+};
+var PREPARE_CACHE = new BoundedLru(PREPARE_CACHE_MAX);
+function structureKey(routes) {
+  const parts = routes.map(({ alias, route }) => {
+    const rec = route;
+    const intent = [...INTENT_KEYS, ...READ_INTENT_KEYS].find((k) => rec[k] !== void 0) ?? "?";
+    const modelRef = rec[intent];
+    const modelId = modelIdentity(modelRef, alias);
+    const key = describeBinding(route.key);
+    const rw = route;
+    const rr = route;
+    const extra = intent === "query" || intent === "list" ? `select=${stableJson(rr.select)};opt=${describeReadOptions(rr.options)}` : `input=${describeBinding(rw.input)};cond=${describeBinding(rw.condition)};result=${stableJson(rw.result)}`;
+    return `${alias}|${intent}|${modelId}|key=${key}|${extra}`;
+  });
+  return parts.join("||");
+}
+var MODEL_IDENTITY_IDS = /* @__PURE__ */ new WeakMap();
+var nextModelIdentityId = 1;
+function modelIdentity(ref, alias) {
+  try {
+    const model = resolveModelStatic(ref, alias);
+    const cls = resolveModelClass(model);
+    let id = MODEL_IDENTITY_IDS.get(cls);
+    if (id === void 0) {
+      id = nextModelIdentityId++;
+      MODEL_IDENTITY_IDS.set(cls, id);
+    }
+    return `model#${id}`;
+  } catch {
+    return "unresolved";
+  }
+}
+function describeBinding(binding) {
+  if (binding === void 0) return "\u2205";
+  const keys = Object.keys(binding).sort();
+  return keys.map((k) => {
+    const v = binding[k];
+    return isPreparedParamRef(v) ? `${k}=$(${v.name})` : `${k}=L(${stableJson(v)})`;
+  }).join(",");
+}
+function describeReadOptions(options) {
+  if (options === void 0) return "\u2205";
+  const o = options;
+  const slot = (v) => isPreparedParamRef(v) ? `$(${v.name})` : v === void 0 ? "\u2205" : `L(${stableJson(v)})`;
+  return `cr=${slot(o.consistentRead)};limit=${slot(o.limit)};after=${slot(o.after)};depth=${o.maxDepth ?? "\u2205"};order=${o.order ?? "\u2205"};filter=${stableJson(o.filter)}`;
+}
+function stableJson(value) {
+  return JSON.stringify(value, (_k, v) => {
+    if (isPreparedParamRef(v)) return `$${v.name}`;
+    if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+      const sorted = {};
+      for (const k of Object.keys(v).sort()) {
+        sorted[k] = v[k];
+      }
+      return sorted;
+    }
+    return v;
+  });
+}
+function prepare(body) {
+  if (typeof body !== "function") {
+    throw new Error(
+      `${PREPARE_LABEL}: expected a body function \`($) => ({ alias: { ... } })\`.`
+    );
+  }
+  const $ = makePreparedInputProxy();
+  const map = body($);
+  if (map === null || typeof map !== "object") {
+    throw new Error(
+      `${PREPARE_LABEL}: the body must return a descriptor map \`{ alias: { ... } }\`.`
+    );
+  }
+  const routes = Object.keys(map).map((alias) => ({
+    alias,
+    route: map[alias]
+  }));
+  const cacheKey = structureKey(routes);
+  const cached = PREPARE_CACHE.get(cacheKey);
+  if (cached !== void 0) return cached;
+  const kind = classify(routes);
+  let handle;
+  if (kind === "write") {
+    const ops = routes.map(
+      ({ alias, route }) => compileWriteRoute(alias, route)
+    );
+    handle = new PreparedWriteStatement(ops);
+  } else {
+    const compiledRoutes = routes.map(
+      ({ alias, route }) => compileReadRoute(alias, route)
+    );
+    handle = new PreparedReadStatement(compiledRoutes);
+  }
+  PREPARE_CACHE.set(cacheKey, handle);
+  return handle;
+}
+
 // src/model/DDBModel.ts
 var DDBModel = class {
   /**
@@ -3790,6 +4367,43 @@ var DDBModel = class {
   static mutate(envelope, options) {
     return executeWriteEnvelope(envelope, options);
   }
+  /**
+   * **Prepared statement** (issue #205 / design #203) — the read/write-unified
+   * middle tier between the ad-hoc `DDBModel.mutate` / `DDBModel.query` (per-call
+   * recompiled) and the public CQRS contract (`publicCommandModel` /
+   * `publicQueryModel`, precompiled but contract-welded).
+   *
+   * `prepare($ => ({...}))` **compiles the declarative route body once** and returns
+   * a handle whose `.execute(params)` binds the per-call values and runs through the
+   * SAME execution cores those two surfaces use — so a write's derived maintainers /
+   * atomic transaction semantics are identical to `DDBModel.mutate`, and a read's
+   * projection / relation resolution / pagination are identical to `Model.query` /
+   * `list`. A body is **all-read or all-write**:
+   *
+   * ```ts
+   * const createPost = DDBModel.prepare(($) => ({
+   *   post: { create: () => Post, key: { threadId: $.threadId, postId: $.postId },
+   *           input: { body: $.body } },
+   * }));
+   * await createPost.execute({ threadId, postId, body });
+   *
+   * const userById = DDBModel.prepare(($) => ({
+   *   user: { query: () => User, key: { userId: $.userId },
+   *           select: { userId: true, name: true } },
+   * }));
+   * await userById.execute({ userId });
+   * ```
+   *
+   * The body may reference only `$` placeholders (per-call values) and module-static
+   * model refs — a captured per-call runtime value is a **loud reject** (the runtime
+   * half of the no-runtime-capture rule; the static build lint is phase 2 / #206). A
+   * handle hoisted to module scope recompiles nothing; an inline `prepare(fn)` hits a
+   * bounded structural cache after the first compile (placement-independent safety
+   * net).
+   */
+  static prepare(body) {
+    return prepare(body);
+  }
   /**
    * Parse a single CDC {@link ChangeEvent} into the `[oldRecord, newRecord]` tuple
    * for THIS model (issue #153 — the pure `(event) => [old, new]` typed mapper).
@@ -4178,12 +4792,12 @@ function wholeKeysSentinel() {
 function isContractKeyFieldRef(value) {
   return typeof value === "object" && value !== null && value[KEY_FIELD_REF_BRAND] === true;
 }
-var PARAM_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:contractParamRef");
+var PARAM_REF_BRAND2 = /* @__PURE__ */ Symbol("graphddb:contractParamRef");
 function isContractParamRef(value) {
-  return typeof value === "object" && value !== null && value[PARAM_REF_BRAND] === true;
+  return typeof value === "object" && value !== null && value[PARAM_REF_BRAND2] === true;
 }
 function mintContractParamRef(field) {
-  return { [PARAM_REF_BRAND]: true, field, token: `{${field}}` };
+  return { [PARAM_REF_BRAND2]: true, field, token: `{${field}}` };
 }
 var FROM_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:contractFromRef");
 var COMPOSE_NODE_BRAND = /* @__PURE__ */ Symbol("graphddb:contractComposeNode");
@@ -4440,13 +5054,13 @@ function normalizeReturnSelection(select) {
   }
   return Object.keys(out).length > 0 ? out : void 0;
 }
-var READ_INTENT_KEYS = ["query", "list"];
+var READ_INTENT_KEYS2 = ["query", "list"];
 var WRITE_INTENT_KEYS = ["create", "update", "remove"];
 function isPublicComposeDescriptor(value) {
   return typeof value === "object" && value !== null && isCommandPlan(value.command);
 }
 function isPublicReadDescriptor(value) {
-  return typeof value === "object" && value !== null && READ_INTENT_KEYS.some((k) => value[k] !== void 0);
+  return typeof value === "object" && value !== null && READ_INTENT_KEYS2.some((k) => value[k] !== void 0);
 }
 function isPublicWriteDescriptor(value) {
   return typeof value === "object" && value !== null && WRITE_INTENT_KEYS.some((k) => value[k] !== void 0);
@@ -6669,6 +7283,11 @@ function buildRelationOperations(metadata, select, parentPath) {
     const targetClass = rel.targetFactory();
     const targetMeta = MetadataRegistry.get(targetClass);
     const childPath = `${parentPath}.${rel.propertyName}`;
+    if (rel.type === "refs") {
+      throw new Error(
+        `Relation '${rel.propertyName}' is a 'refs' relation (issue #197): its read fans an inline parent-row id-list ('${rel.refs?.from}[].${rel.refs?.key}') out into one BatchGet. The static operations spec / Python codegen cannot represent a parent-list key fan-out (operation key conditions bind a single scalar '{result.*}'), so a 'refs' relation is resolvable ONLY through the TS in-process runtime (Model.query). Remove '${rel.propertyName}' from selects that are compiled to operations.json / generated Python, or resolve it with a separate BatchGet in the generated-code consumer.`
+      );
+    }
     if (rel.type === "hasMany") {
       const limit = spec.limit ?? rel.options?.limit?.default ?? 20;
       ops.push(
@@ -6946,8 +7565,6 @@ export {
   SPEC_VERSION,
   MARKER_ROW_ENTITY,
   buildManifest,
-  detectRelationFields,
-  getImplicitKeyFields,
   buildProjection,
   compileFilterExpression,
   evaluateFilter,
@@ -6984,6 +7601,11 @@ export {
   MAX_TRANSACT_COMPOSE_ITEMS,
   compileMutationPlan,
   executeCommandMethod,
+  isPreparedParamRef,
+  PreparedWriteStatement,
+  PreparedReadStatement,
+  PREPARE_CACHE_MAX,
+  prepare,
   DDBModel,
   isMutationInputRef,
   isMutationFragment,