graphddb 0.7.0 → 0.7.2

package/dist/{chunk-GFGVDF4W.js → chunk-H34BNRDZ.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,
@@ -2939,6 +2942,30 @@ function renderTemplateRecord(record, key, params, contextLabel) {
   }
   return out;
 }
+var EFFECT_FIELD_MAPS = /* @__PURE__ */ new WeakMap();
+function effectFieldMap(modelClass) {
+  let map = EFFECT_FIELD_MAPS.get(modelClass);
+  if (map === void 0) {
+    map = new Map(MetadataRegistry.get(modelClass).fields.map((f) => [f.propertyName, f]));
+    EFFECT_FIELD_MAPS.set(modelClass, map);
+  }
+  return map;
+}
+function serializeEffectParams(modelClasses, values) {
+  const maps = modelClasses.map(effectFieldMap);
+  const oldPrefix = `${OLD_VALUE_NAMESPACE}.`;
+  const out = {};
+  for (const [name, value] of Object.entries(values)) {
+    const fieldName = name.startsWith(oldPrefix) ? name.slice(oldPrefix.length) : name;
+    let fieldMeta;
+    for (const map of maps) {
+      fieldMeta = map.get(fieldName);
+      if (fieldMeta !== void 0) break;
+    }
+    out[name] = fieldMeta !== void 0 ? serializeFieldValue(value, fieldMeta) : value instanceof Date ? value.toISOString() : value;
+  }
+  return out;
+}
 function renderEdgeWriteItems(edge, key, params, contextLabel, modelBySignature) {
   const adjacency = edge.entity.modelClass;
   return edge.items.map((item) => {
@@ -3284,11 +3311,14 @@ async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}
     );
     if (hasDerivedEffects) {
       const modelBySignature = /* @__PURE__ */ new Map();
+      const fragmentClasses = ops.map((opn) => modelClassOf(opn));
+      const effectKey = serializeEffectParams(fragmentClasses, key);
+      const effectParams = serializeEffectParams(fragmentClasses, params);
       const edgeItems = edgeWrites2.flatMap(
         (edge, i) => renderEdgeWriteItems(
           edge,
-          key,
-          params,
+          effectKey,
+          effectParams,
           `command method '${methodName}' (edge #${i})`,
           modelBySignature
         )
@@ -3296,41 +3326,41 @@ async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}
       const updateItems = derivedUpdates.map(
         (update, i) => renderDerivedUpdate(
           update,
-          key,
-          params,
+          effectKey,
+          effectParams,
           `command method '${methodName}' (derive #${i})`,
           modelBySignature
         )
       );
       const guardItems = uniqueGuards.flatMap(
-        (guard, i) => renderUniqueGuardItems(guard, key, params, `command method '${methodName}' (unique #${i})`)
+        (guard, i) => renderUniqueGuardItems(guard, effectKey, effectParams, `command method '${methodName}' (unique #${i})`)
       );
       const outboxItems = outboxEvents.flatMap(
-        (event, i) => renderOutboxEventItems(event, key, params, `command method '${methodName}' (emit #${i})`)
+        (event, i) => renderOutboxEventItems(event, effectKey, effectParams, `command method '${methodName}' (emit #${i})`)
       );
       const idempotencyItems = idempotencyGuard !== void 0 ? renderIdempotencyGuardItems(
         idempotencyGuard,
-        key,
-        params,
+        effectKey,
+        effectParams,
         `command method '${methodName}' (idempotency)`
       ) : [];
       const maintainItems = maintainWrites.map(
         (m, i) => renderMaintainWriteItem(
           m,
-          key,
-          params,
+          effectKey,
+          effectParams,
           `command method '${methodName}' (maintain #${i})`,
           modelBySignature
         )
       );
       const maintainOutboxItems = maintainOutbox.flatMap(
-        (mo, i) => renderMaintainOutboxItems(mo, key, params, `command method '${methodName}' (maintain-outbox #${i})`)
+        (mo, i) => renderMaintainOutboxItems(mo, effectKey, effectParams, `command method '${methodName}' (maintain-outbox #${i})`)
       );
       const checks = conditionChecks.map((check, i) => ({
         check: renderConditionCheck(
           check,
-          key,
-          params,
+          effectKey,
+          effectParams,
           `command method '${methodName}' (requires #${i})`
         )
       }));
@@ -3366,6 +3396,7 @@ function renderCompiledOp(op, ctx) {
   const baseOp = op.condition !== void 0 ? withCondition(fragment.op, op.condition) : fragment.op;
   const modelBySignature = /* @__PURE__ */ new Map();
   const write = renderWrite(baseOp, op.params, op.params, ctx);
+  const effectParams = serializeEffectParams([modelClassOf(fragment.op)], op.params);
   const edgeItems = [];
   const updateItems = [];
   const guardItems = [];
@@ -3375,34 +3406,34 @@ function renderCompiledOp(op, ctx) {
   const maintainOutboxItems = [];
   const checkItems = [];
   for (const edge of fragment.edgeWrites ?? []) {
-    edgeItems.push(...renderEdgeWriteItems(edge, op.params, op.params, `${ctx} edge`, modelBySignature));
+    edgeItems.push(...renderEdgeWriteItems(edge, effectParams, effectParams, `${ctx} edge`, modelBySignature));
   }
   for (const u of fragment.derivedUpdates ?? []) {
-    updateItems.push(renderDerivedUpdate(u, op.params, op.params, `${ctx} derive`, modelBySignature));
+    updateItems.push(renderDerivedUpdate(u, effectParams, effectParams, `${ctx} derive`, modelBySignature));
   }
   for (const g of fragment.uniqueGuards ?? []) {
-    guardItems.push(...renderUniqueGuardItems(g, op.params, op.params, `${ctx} unique`));
+    guardItems.push(...renderUniqueGuardItems(g, effectParams, effectParams, `${ctx} unique`));
   }
   for (const e of fragment.outboxEvents ?? []) {
-    outboxItems.push(...renderOutboxEventItems(e, op.params, op.params, `${ctx} emit`));
+    outboxItems.push(...renderOutboxEventItems(e, effectParams, effectParams, `${ctx} emit`));
   }
   if (fragment.idempotencyGuard !== void 0) {
     idempotencyItems.push(
-      ...renderIdempotencyGuardItems(fragment.idempotencyGuard, op.params, op.params, `${ctx} idempotency`)
+      ...renderIdempotencyGuardItems(fragment.idempotencyGuard, effectParams, effectParams, `${ctx} idempotency`)
     );
   }
   for (const m of fragment.maintainWrites ?? []) {
     maintainItems.push(
-      renderMaintainWriteItem(m, op.params, op.params, `${ctx} maintain`, modelBySignature)
+      renderMaintainWriteItem(m, effectParams, effectParams, `${ctx} maintain`, modelBySignature)
     );
   }
   for (const mo of fragment.maintainOutbox ?? []) {
     maintainOutboxItems.push(
-      ...renderMaintainOutboxItems(mo, op.params, op.params, `${ctx} maintain-outbox`)
+      ...renderMaintainOutboxItems(mo, effectParams, effectParams, `${ctx} maintain-outbox`)
     );
   }
   for (const c of fragment.conditionChecks ?? []) {
-    checkItems.push({ check: renderConditionCheck(c, op.params, op.params, `${ctx} requires`) });
+    checkItems.push({ check: renderConditionCheck(c, effectParams, effectParams, `${ctx} requires`) });
   }
   const 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;
   return {
@@ -3532,8 +3563,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 +3593,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 +3691,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;
@@ -4052,7 +4290,7 @@ function classify(routes) {
   }
   return kind;
 }
-function compileWriteRoute(alias, route) {
+function analyzeWriteRoute(alias, route) {
   const present = INTENT_KEYS.filter((k) => route[k] !== void 0);
   if (present.length !== 1) {
     throw new Error(
@@ -4073,23 +4311,37 @@ function compileWriteRoute(alias, route) {
   );
   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,
+    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;
@@ -4256,6 +4508,25 @@ function stableJson(value) {
     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(
@@ -6839,12 +7110,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") {
@@ -6967,7 +7268,7 @@ function serializeCommandContract(contractName, contract, commandSpecs, transact
           idempotencyGuard,
           maintainWrites,
           maintainOutbox
-        )
+        ).spec
       ) : (
         // #90: writes only.
         composeFragmentTransaction(contractName, methodName, ops)
@@ -7263,12 +7564,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();
 }
@@ -7284,9 +7585,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;
@@ -7397,6 +7705,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 };
 }
@@ -7551,6 +7918,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 = {
@@ -7564,6 +8141,7 @@ function buildBridgeBundle(queries = {}, commands = {}, registry = MetadataRegis
 export {
   SPEC_VERSION,
   MARKER_ROW_ENTITY,
+  buildManifestEntity,
   buildManifest,
   buildProjection,
   compileFilterExpression,
@@ -7600,7 +8178,11 @@ export {
   compileSingleFragmentPlan,
   MAX_TRANSACT_COMPOSE_ITEMS,
   compileMutationPlan,
+  serializeEffectParams,
   executeCommandMethod,
+  LOGICAL_EFFECT_CATEGORIES,
+  executeLogicalWriteOps,
+  executeLogicalParallelWrites,
   isPreparedParamRef,
   PreparedWriteStatement,
   PreparedReadStatement,
@@ -7646,5 +8228,11 @@ export {
   assertContractBoundaries,
   buildQuerySpec,
   buildOperations,
+  PREPARED_FORMAT_VERSION,
+  canonicalJson,
+  entityFingerprint,
+  planFingerprint,
+  compilePreparedPlan,
+  buildPreparedPlanDocument,
   buildBridgeBundle
 };