graphddb 0.6.0 → 0.7.1

package/dist/{chunk-N5NQM3SO.js → chunk-C5Q2NMRW.js}

@@ -67,7 +67,7 @@ function evaluateKey(segmented, scope, presentFields, nameOf = (f) => f, partial
 }
 
 // src/spec/types.ts
-var SPEC_VERSION = "1.0";
+var SPEC_VERSION = "1.1";
 var MARKER_ROW_ENTITY = "__marker__";
 
 // src/spec/manifest.ts
@@ -144,6 +144,9 @@ function buildFields(metadata) {
   }
   return sortedRecord(fields);
 }
+function buildManifestEntity(metadata) {
+  return buildEntity(metadata);
+}
 function buildEntity(metadata) {
   return {
     table: metadata.tableName,
@@ -3532,8 +3535,23 @@ async function persistSingleWriteWithHooks(w, runtime, origins, transaction, ret
   });
 }
 async function runEnvelopeW1(op, runtime, transaction, writeCtxs) {
-  const kind = op.fragment.op.operation;
-  const keyFields = new Set(op.fragment.keyFields);
+  const r = await runLogicalW1(
+    {
+      kind: op.fragment.op.operation,
+      modelClass: op.fragment.op.entity.modelClass,
+      keyFields: op.fragment.keyFields,
+      params: op.params
+    },
+    runtime,
+    transaction,
+    writeCtxs
+  );
+  if (r.rewritten !== void 0) return { op, rewritten: r.rewritten };
+  return { op: { ...op, params: r.params } };
+}
+async function runLogicalW1(op, runtime, transaction, writeCtxs) {
+  const kind = op.kind;
+  const keyFields = new Set(op.keyFields);
   const input = {};
   if (kind === "put") {
     input.item = { ...op.params };
@@ -3547,15 +3565,14 @@ async function runEnvelopeW1(op, runtime, transaction, writeCtxs) {
     input.key = key;
     input.changes = changes;
   }
-  const modelClass = op.fragment.op.entity.modelClass;
-  const ctx = runtime.writeCtx(kind, ctxModelFor(modelClass), input, transaction);
+  const ctx = runtime.writeCtx(kind, ctxModelFor(op.modelClass), input, transaction);
   await runtime.runWriteBefore(ctx);
   writeCtxs.push(ctx);
   if (ctx.kind !== kind) {
-    return { op, rewritten: renderRewrittenWrite(modelClass, ctx) };
+    return { params: op.params, rewritten: renderRewrittenWrite(op.modelClass, ctx) };
   }
   const merged = ctx.kind === "put" ? { ...ctx.input.item ?? {} } : { ...ctx.input.key ?? {}, ...ctx.input.changes ?? {} };
-  return { op: { ...op, params: merged } };
+  return { params: merged };
 }
 function renderRewrittenWrite(modelClass, ctx) {
   const modelStatic = modelClass.asModel();
@@ -3646,6 +3663,199 @@ async function executeCompiledParallelWrites(ops, options) {
   ]);
   return results;
 }
+var LOGICAL_EFFECT_CATEGORIES = [
+  "edge",
+  "derive",
+  "unique",
+  "outbox",
+  "idempotency",
+  "maintain",
+  "maintainOutbox"
+];
+function renderLogicalWrite(op, params) {
+  const base = {
+    operation: op.kind,
+    modelClass: op.modelClass,
+    modelStatic: op.modelStatic,
+    key: params,
+    ...op.condition !== void 0 ? { condition: op.condition } : {}
+  };
+  if (op.kind === "put") return { ...base, item: params };
+  if (op.kind === "update") {
+    const keyFields = new Set(op.keyFields);
+    const changes = {};
+    for (const [k, v] of Object.entries(params)) {
+      if (!keyFields.has(k)) changes[k] = v;
+    }
+    return { ...base, changes };
+  }
+  return base;
+}
+function renderLogicalOp(op, params) {
+  const write = renderLogicalWrite(op, params);
+  const rendered = op.renderEffects(params);
+  const e = rendered.effects;
+  const checkItems = rendered.checks.map((check) => ({ check }));
+  const modelBySignature = new Map(rendered.modelBySignature);
+  const pick = (c) => [...e[c] ?? []];
+  const edgeItems = pick("edge");
+  const updateItems = pick("derive");
+  const guardItems = pick("unique");
+  const outboxItems = pick("outbox");
+  const idempotencyItems = pick("idempotency");
+  const maintainItems = pick("maintain");
+  const maintainOutboxItems = pick("maintainOutbox");
+  return {
+    write,
+    edgeItems,
+    updateItems,
+    guardItems,
+    outboxItems,
+    idempotencyItems,
+    maintainItems,
+    maintainOutboxItems,
+    checkItems,
+    modelBySignature,
+    hasDerivedEffects: edgeItems.length > 0 || updateItems.length > 0 || guardItems.length > 0 || outboxItems.length > 0 || idempotencyItems.length > 0 || maintainItems.length > 0 || maintainOutboxItems.length > 0 || checkItems.length > 0
+  };
+}
+function readBackForLogicalOp(op, params) {
+  const sel = op.result?.select;
+  if (sel === void 0 || Object.keys(sel).length === 0) return void 0;
+  const key = {};
+  for (const f of op.keyFields) {
+    if (f in params) key[f] = params[f];
+  }
+  return executeQuery(op.modelClass, key, sel, {
+    consistentRead: op.result?.options?.consistentRead ?? true,
+    maxDepth: op.result?.options?.maxDepth
+  });
+}
+async function executeLogicalWriteOps(ops, options) {
+  const label = options.label;
+  const writeMw = buildWriteRuntime(options.context);
+  const writeCtxs = [];
+  const txId = { id: /* @__PURE__ */ Symbol("graphddb.prepared-aot") };
+  const effectiveParams = [];
+  const rewrites = [];
+  if (writeMw.active) {
+    for (const op of ops) {
+      const r = await runLogicalW1(op, writeMw, txId, writeCtxs);
+      effectiveParams.push(r.params);
+      rewrites.push(r.rewritten ?? null);
+    }
+  } else {
+    for (const op of ops) {
+      effectiveParams.push(op.params);
+      rewrites.push(null);
+    }
+  }
+  const renderedOps = ops.map(
+    (op, i) => rewrites[i] !== null ? rewrittenCompiledOp(rewrites[i]) : renderLogicalOp(op, effectiveParams[i])
+  );
+  const rendered = renderedOps.map((r) => r.write);
+  const modelBySignature = /* @__PURE__ */ new Map();
+  const edgeItems = [];
+  const updateItems = [];
+  const guardItems = [];
+  const outboxItems = [];
+  const idempotencyItems = [];
+  const maintainItems = [];
+  const maintainOutboxItems = [];
+  const checkItems = [];
+  for (const r of renderedOps) {
+    for (const [sig, name] of r.modelBySignature) modelBySignature.set(sig, name);
+    edgeItems.push(...r.edgeItems);
+    updateItems.push(...r.updateItems);
+    guardItems.push(...r.guardItems);
+    outboxItems.push(...r.outboxItems);
+    idempotencyItems.push(...r.idempotencyItems);
+    maintainItems.push(...r.maintainItems);
+    maintainOutboxItems.push(...r.maintainOutboxItems);
+    checkItems.push(...r.checkItems);
+  }
+  const hasDerivedEffects = renderedOps.some((r) => r.hasDerivedEffects);
+  const origins = writeMw.active ? rendered.map((w) => ({ model: ctxModelFor(w.modelClass), kind: w.operation })) : [];
+  if (rendered.length === 1 && !hasDerivedEffects) {
+    if (writeMw.active) {
+      await persistSingleWriteWithHooks(rendered[0], writeMw, origins, txId, options.retry);
+    } else {
+      await executeSingleWrite(rendered[0], options.retry);
+    }
+  } else {
+    await executeReferentialTransaction(
+      rendered,
+      edgeItems,
+      updateItems,
+      guardItems,
+      outboxItems,
+      idempotencyItems,
+      maintainItems,
+      maintainOutboxItems,
+      checkItems,
+      label,
+      modelBySignature,
+      options.retry,
+      writeMw.active ? { runtime: writeMw, origins, transaction: txId } : void 0
+    );
+  }
+  if (writeMw.active) {
+    for (let i = writeCtxs.length - 1; i >= 0; i--) {
+      await writeMw.runWriteAfter(writeCtxs[i], {});
+    }
+  }
+  const readBacks = await Promise.all(
+    ops.map((op, i) => readBackForLogicalOp(op, effectiveParams[i]))
+  );
+  return { readBacks };
+}
+async function executeLogicalParallelWrites(ops, options) {
+  const label = options.label;
+  const results = new Array(ops.length);
+  const renderedOps = ops.map((op) => renderLogicalOp(op, op.params));
+  const coalescibleIdx = [];
+  const individualIdx = [];
+  const hooksActive = buildWriteRuntime(options.context).active;
+  renderedOps.forEach((r, i) => {
+    const w = r.write;
+    if (!hooksActive && !r.hasDerivedEffects && w.condition === void 0 && (w.operation === "put" || w.operation === "delete")) {
+      coalescibleIdx.push(i);
+    } else {
+      individualIdx.push(i);
+    }
+  });
+  await Promise.all([
+    (async () => {
+      if (coalescibleIdx.length === 0) return;
+      const writes = coalescibleIdx.map((i) => renderedOps[i].write);
+      try {
+        await executeParallelWrites(writes);
+        await Promise.all(
+          coalescibleIdx.map(async (i) => {
+            const value = await readBackForLogicalOp(ops[i], ops[i].params);
+            results[i] = { ok: true, value };
+          })
+        );
+      } catch (e) {
+        const error = e instanceof Error ? e : new Error(String(e));
+        for (const i of coalescibleIdx) results[i] = { ok: false, error };
+      }
+    })(),
+    ...individualIdx.map(async (i) => {
+      try {
+        const { readBacks } = await executeLogicalWriteOps([ops[i]], {
+          label: `${label} (op #${i})`,
+          ...options.retry !== void 0 ? { retry: options.retry } : {},
+          ...options.context !== void 0 ? { context: options.context } : {}
+        });
+        results[i] = { ok: true, value: readBacks[0] };
+      } catch (e) {
+        results[i] = { ok: false, error: e instanceof Error ? e : new Error(String(e)) };
+      }
+    })
+  ]);
+  return results;
+}
 function withCondition(op, condition) {
   if (op.condition === void 0) return { ...op, condition };
   const base = op.condition;
@@ -3760,17 +3970,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);
@@ -3778,7 +3986,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,
@@ -3847,6 +4064,478 @@ 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 analyzeWriteRoute(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`);
+  return {
+    alias,
+    intent,
+    model,
+    keyFields: keyRec.fields,
+    inputFields: inputRec.fields,
+    keySlots: keyRec.slots,
+    inputSlots: inputRec.slots,
+    ...conditionRec !== void 0 ? { conditionSlots: conditionRec.slots } : {},
+    ...route.result !== void 0 ? { result: route.result } : {}
+  };
+}
+function compileWriteRoute(alias, route) {
+  const analyzed = analyzeWriteRoute(alias, route);
+  const fragment = compileWriteFragment({
+    alias,
+    intent: analyzed.intent,
+    model: analyzed.model,
+    keyFieldNames: analyzed.keyFields,
+    inputFieldNames: analyzed.inputFields
+  });
+  return {
+    alias,
+    intent: analyzed.intent,
+    fragment,
+    keySlots: analyzed.keySlots,
+    inputSlots: analyzed.inputSlots,
+    ...analyzed.conditionSlots !== void 0 ? { conditionSlots: analyzed.conditionSlots } : {},
+    ...analyzed.result !== void 0 ? { result: analyzed.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 evaluatePreparedRoutes(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]
+  }));
+  return { kind: classify(routes), routes };
+}
+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 {
   /**
@@ -3921,6 +4610,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).
@@ -4309,12 +5035,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");
@@ -4571,13 +5297,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);
@@ -6356,12 +7082,42 @@ function synthesizeMutationTransaction(contractName, methodName, ops, checks, ed
     ...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 { params: sortedParams(params), items, maxItems: items.length };
+  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") {
@@ -6484,7 +7240,7 @@ function serializeCommandContract(contractName, contract, commandSpecs, transact
           idempotencyGuard,
           maintainWrites,
           maintainOutbox
-        )
+        ).spec
       ) : (
         // #90: writes only.
         composeFragmentTransaction(contractName, methodName, ops)
@@ -6780,12 +7536,12 @@ function buildReadOperations(def) {
   };
   const ops = [root];
   ops.push(...buildRelationOperations(metadata, select, "$"));
-  return ops;
+  return injectRefsSourceProjections(ops);
 }
 function projectionFields(select) {
   const out = [];
   for (const [field, value] of Object.entries(select)) {
-    if (value === true) out.push(field);
+    if (value === true || isInlineSnapshotSpec(value)) out.push(field);
   }
   return out.sort();
 }
@@ -6801,9 +7557,16 @@ function buildRelationOperations(metadata, select, parentPath) {
     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 (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;
@@ -6914,6 +7677,65 @@ function buildBatchGetOperation(rel, targetMeta, 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 from2 = op.sourceList.from;
+    if (parent.projection.includes(from2)) {
+      continue;
+    }
+    ops[parentIndex] = {
+      ...parent,
+      projection: [...parent.projection, from2].sort()
+    };
+    ops[i] = { ...op, sourceList: { ...op.sourceList, implicit: true } };
+  }
+  return ops;
+}
 function filterSpec(filter) {
   return { declarative: filter };
 }
@@ -7068,6 +7890,216 @@ function buildOperations(queries = {}, commands = {}, transactions = {}, contrac
   };
 }
 
+// src/spec/prepared.ts
+import { createHash } from "crypto";
+var PREPARED_FORMAT_VERSION = "1";
+function canonicalJson(value) {
+  return JSON.stringify(value, (_k, v) => {
+    if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+      const sorted = {};
+      for (const key of Object.keys(v).sort()) {
+        sorted[key] = v[key];
+      }
+      return sorted;
+    }
+    return v;
+  });
+}
+function entityFingerprint(metadata) {
+  return createHash("sha256").update(canonicalJson(buildManifestEntity(metadata))).digest("hex");
+}
+function planFingerprint(plan2) {
+  return createHash("sha256").update(canonicalJson(plan2)).digest("hex");
+}
+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 = {
@@ -7081,6 +8113,7 @@ function buildBridgeBundle(queries = {}, commands = {}, registry = MetadataRegis
 export {
   SPEC_VERSION,
   MARKER_ROW_ENTITY,
+  buildManifestEntity,
   buildManifest,
   buildProjection,
   compileFilterExpression,
@@ -7118,6 +8151,14 @@ export {
   MAX_TRANSACT_COMPOSE_ITEMS,
   compileMutationPlan,
   executeCommandMethod,
+  LOGICAL_EFFECT_CATEGORIES,
+  executeLogicalWriteOps,
+  executeLogicalParallelWrites,
+  isPreparedParamRef,
+  PreparedWriteStatement,
+  PreparedReadStatement,
+  PREPARE_CACHE_MAX,
+  prepare,
   DDBModel,
   isMutationInputRef,
   isMutationFragment,
@@ -7158,5 +8199,11 @@ export {
   assertContractBoundaries,
   buildQuerySpec,
   buildOperations,
+  PREPARED_FORMAT_VERSION,
+  canonicalJson,
+  entityFingerprint,
+  planFingerprint,
+  compilePreparedPlan,
+  buildPreparedPlanDocument,
   buildBridgeBundle
 };