graphddb 0.6.0 → 0.7.1

package/dist/index.js

@@ -5,8 +5,13 @@ import {
   BatchGetResult,
   DDBModel,
   EDGE_WRITES_MARKER,
+  LOGICAL_EFFECT_CATEGORIES,
   MARKER_ROW_ENTITY,
   OLD_VALUE_NAMESPACE,
+  PREPARED_FORMAT_VERSION,
+  PREPARE_CACHE_MAX,
+  PreparedReadStatement,
+  PreparedWriteStatement,
   RELATION_TRAVERSAL_CONCURRENCY,
   SPEC_VERSION,
   assertBundleSerializable,
@@ -18,6 +23,7 @@ import {
   buildContexts,
   buildContracts,
   buildManifest,
+  buildManifestEntity,
   buildOperations,
   buildProjection,
   buildQuerySpec,
@@ -41,6 +47,7 @@ import {
   deriveModelEdgeWriteItems,
   edgeWrites,
   encodeCursor,
+  entityFingerprint,
   evaluateFilter,
   execute,
   executeBatchGet,
@@ -49,6 +56,8 @@ import {
   executeExplain,
   executeList,
   executeListInternal,
+  executeLogicalParallelWrites,
+  executeLogicalWriteOps,
   executeQuery,
   from,
   getEdgeWrites,
@@ -63,6 +72,7 @@ import {
   isMutationFragment,
   isMutationInputRef,
   isPlannedCommandMethod,
+  isPreparedParamRef,
   isQueryModelContract,
   isTransactionRef,
   mapWithConcurrency,
@@ -70,6 +80,7 @@ import {
   mintContractParamRef,
   mutation,
   plan,
+  prepare,
   publicCommandModel,
   publicQueryModel,
   query,
@@ -78,7 +89,7 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-N5NQM3SO.js";
+} from "./chunk-C5Q2NMRW.js";
 import {
   CdcEmulator,
   MAINT_OUTBOX_PK_PREFIX,
@@ -1277,6 +1288,256 @@ async function executeRangeFanout(op, keys, params = {}) {
   return out;
 }
 
+// src/runtime/prepared-loader.ts
+var LOAD_LABEL = "graphddb.loadPreparedPlan";
+function slotOfBind(bind) {
+  if ("param" in bind) return { kind: "param", name: bind.param };
+  if ("literal" in bind) return { kind: "literal", value: bind.literal };
+  if ("literalDate" in bind) return { kind: "literal", value: new Date(bind.literalDate) };
+  return { kind: "literal", value: BigInt(bind.literalBigInt) };
+}
+function slotsOfBindMap(map2) {
+  const out = {};
+  for (const [field2, bind] of Object.entries(map2 ?? {})) out[field2] = slotOfBind(bind);
+  return out;
+}
+function bindValues(slots, params) {
+  const out = {};
+  for (const [field2, slot] of Object.entries(slots)) {
+    out[field2] = slot.kind === "param" ? params[slot.name] : slot.value;
+  }
+  return out;
+}
+function resolveModelByName(name, planId) {
+  for (const modelClass of MetadataRegistry.getAll().keys()) {
+    if (modelClass.name === name) return modelClass;
+  }
+  throw new Error(
+    `${LOAD_LABEL}: static plan '${planId}' targets entity '${name}', which is not a registered model in this process. Ensure the model module is imported before the plan executes, or regenerate the artifact (graphddb transform prepared --aot).`
+  );
+}
+function bindEntities(plan2, planId) {
+  const classes = /* @__PURE__ */ new Map();
+  const entities = {};
+  const tables = {};
+  for (const [name, expected] of Object.entries(plan2.entities)) {
+    const modelClass = resolveModelByName(name, planId);
+    const metadata = MetadataRegistry.get(modelClass);
+    const actual = entityFingerprint(metadata);
+    if (actual !== expected) {
+      throw new Error(
+        `${LOAD_LABEL}: static plan '${planId}' is STALE \u2014 entity '${name}' has changed since the plan artifact was generated (declaration fingerprint mismatch: expected ${expected.slice(0, 12)}\u2026, live ${actual.slice(0, 12)}\u2026). A stale static plan never executes. Regenerate the artifact: \`graphddb transform prepared --aot <artifact> --write\` (CI: run the check mode to catch this at build time).`
+      );
+    }
+    classes.set(name, modelClass);
+    const entity = buildManifestEntity(metadata);
+    entities[name] = entity;
+    tables[metadata.tableName] = { physicalName: TableMapping.resolve(metadata.tableName) };
+  }
+  return { classes, manifest: { version: SPEC_VERSION, tables, entities } };
+}
+function templateParams(values) {
+  const out = {};
+  for (const [k2, v] of Object.entries(values)) {
+    out[k2] = v instanceof Date ? v.toISOString() : v;
+  }
+  return out;
+}
+function renderSpecItem(transaction, index, manifest, params) {
+  const single = {
+    params: transaction.params,
+    items: [transaction.items[index]]
+  };
+  return expandTransactionItems(single, manifest, params);
+}
+function renderEffectsForOp(op, boundParams) {
+  const rendered = templateParams(boundParams);
+  const effects = {};
+  const checks = [];
+  const modelBySignature = /* @__PURE__ */ new Map();
+  const { transaction, categories } = op.spec;
+  for (let i = 0; i < transaction.items.length; i++) {
+    const category = categories[i];
+    if (category === "base") continue;
+    for (const out of renderSpecItem(transaction, i, op.manifest, rendered)) {
+      const item = out.item;
+      if (category === "check") {
+        if (item.ConditionCheck !== void 0) checks.push(item.ConditionCheck);
+        continue;
+      }
+      const family = category;
+      if (!LOGICAL_EFFECT_CATEGORIES.includes(family)) {
+        throw new Error(
+          `${LOAD_LABEL}: unknown effect category '${String(category)}' in a static plan (artifact format skew \u2014 regenerate the artifact).`
+        );
+      }
+      (effects[family] ??= []).push(item);
+      if (out.model !== void 0) {
+        modelBySignature.set(execItemKeySignature(item), out.model);
+      }
+    }
+  }
+  return { effects, checks, modelBySignature };
+}
+var INTENT_TO_KIND = { create: "put", update: "update", remove: "delete" };
+var AotPreparedWriteStatement = class {
+  /** @internal */
+  constructor(ops) {
+    this.ops = ops;
+  }
+  ops;
+  async execute(params = {}, options = {}) {
+    const logical = this.ops.map((op) => {
+      const bound = {
+        ...bindValues(op.inputSlots, params),
+        ...bindValues(op.keySlots, params)
+      };
+      const condition = op.conditionSlots !== void 0 ? bindValues(op.conditionSlots, params) : void 0;
+      return {
+        kind: INTENT_TO_KIND[op.spec.intent],
+        modelClass: op.modelClass,
+        modelStatic: op.modelStatic,
+        keyFields: op.spec.keyFields,
+        params: bound,
+        // A `create` guards with attribute_not_exists — the same condition the
+        // compiled base op carries; an explicit gate on a create was rejected at
+        // BUILD time (mirroring the compiled core's `withCondition` reject).
+        ...op.spec.intent === "create" ? { condition: { notExists: true } } : condition !== void 0 ? { condition } : {},
+        ...op.spec.result !== void 0 ? { result: op.spec.result } : {},
+        renderEffects: (postW1) => renderEffectsForOp(op, postW1)
+      };
+    });
+    const mode = options.mode ?? "transaction";
+    const runOpts = {
+      label: LOAD_LABEL,
+      ...options.retry !== void 0 ? { retry: options.retry } : {},
+      ...options.context !== void 0 ? { context: options.context } : {}
+    };
+    if (mode === "transaction") {
+      const { readBacks } = await executeLogicalWriteOps(logical, runOpts);
+      const out2 = {};
+      this.ops.forEach((op, i) => {
+        if (op.spec.result !== void 0) out2[op.alias] = readBacks[i];
+      });
+      return out2;
+    }
+    const settled = await executeLogicalParallelWrites(logical, runOpts);
+    const out = {};
+    this.ops.forEach((op, i) => {
+      const res = settled[i];
+      out[op.alias] = res.ok ? { ok: true, value: op.spec.result !== void 0 ? res.value : void 0 } : { ok: false, error: res.error };
+    });
+    return out;
+  }
+};
+function bindReadPlan(plan2, planId) {
+  const { classes } = bindEntities(plan2, planId);
+  const routes = (plan2.reads ?? []).map((r) => {
+    const modelClass = classes.get(r.entity);
+    if (modelClass === void 0) {
+      throw new Error(
+        `${LOAD_LABEL}: static plan '${planId}' route '${r.alias}' targets entity '${r.entity}', which the plan does not fingerprint (artifact skew \u2014 regenerate).`
+      );
+    }
+    const consistentReadSlot = r.consistentRead !== void 0 ? slotOfBind(r.consistentRead) : void 0;
+    const limitSlot = r.limit !== void 0 ? slotOfBind(r.limit) : void 0;
+    const afterSlot = r.after !== void 0 ? slotOfBind(r.after) : void 0;
+    return {
+      alias: r.alias,
+      kind: r.op,
+      modelClass,
+      select: r.select,
+      keySlots: slotsOfBindMap(r.key),
+      ...r.maxDepth !== void 0 ? { maxDepth: r.maxDepth } : {},
+      ...r.order !== void 0 ? { order: r.order } : {},
+      ...r.filter !== void 0 ? { filter: r.filter } : {},
+      ...consistentReadSlot !== void 0 ? { consistentReadSlot } : {},
+      ...limitSlot !== void 0 ? { limitSlot } : {},
+      ...afterSlot !== void 0 ? { afterSlot } : {}
+    };
+  });
+  return new PreparedReadStatement(routes);
+}
+function bindWritePlan(plan2, planId) {
+  const { classes, manifest } = bindEntities(plan2, planId);
+  const ops = (plan2.writes ?? []).map((w) => {
+    const modelClass = classes.get(w.entity);
+    if (modelClass === void 0) {
+      throw new Error(
+        `${LOAD_LABEL}: static plan '${planId}' op '${w.alias}' targets entity '${w.entity}', which the plan does not fingerprint (artifact skew \u2014 regenerate).`
+      );
+    }
+    const modelStatic = modelClass.asModel();
+    return {
+      alias: w.alias,
+      spec: w,
+      modelClass,
+      modelStatic,
+      keySlots: slotsOfBindMap(w.key),
+      inputSlots: slotsOfBindMap(w.input),
+      ...w.condition !== void 0 ? { conditionSlots: slotsOfBindMap(w.condition) } : {},
+      manifest
+    };
+  });
+  return new AotPreparedWriteStatement(ops);
+}
+function bindPlan(doc, planId) {
+  if (doc === null || typeof doc !== "object" || doc.plans === void 0) {
+    throw new Error(`${LOAD_LABEL}: not a prepared-plan document.`);
+  }
+  if (doc.formatVersion !== PREPARED_FORMAT_VERSION) {
+    throw new Error(
+      `${LOAD_LABEL}: unsupported artifact format version '${String(doc.formatVersion)}' (this runtime supports '${PREPARED_FORMAT_VERSION}'). Regenerate the artifact with the installed graphddb version.`
+    );
+  }
+  if (doc.specVersion !== SPEC_VERSION) {
+    throw new Error(
+      `${LOAD_LABEL}: the artifact was compiled against operation-IR version '${String(doc.specVersion)}' but this runtime speaks '${SPEC_VERSION}'. A version-skewed static plan never executes \u2014 regenerate the artifact.`
+    );
+  }
+  const plan2 = doc.plans[planId];
+  if (plan2 === void 0) {
+    const available = Object.keys(doc.plans).sort().slice(0, 8).join(", ");
+    throw new Error(
+      `${LOAD_LABEL}: the artifact carries no plan '${planId}' (available: ${available}${Object.keys(doc.plans).length > 8 ? ", \u2026" : ""}). The source and the artifact have drifted \u2014 regenerate: \`graphddb transform prepared --aot <artifact> --write\`.`
+    );
+  }
+  return plan2.kind === "read" ? bindReadPlan(plan2, planId) : bindWritePlan(plan2, planId);
+}
+var BOUND = /* @__PURE__ */ new WeakMap();
+var LazyAotHandle = class {
+  constructor(doc, planId) {
+    this.doc = doc;
+    this.planId = planId;
+  }
+  doc;
+  planId;
+  bound;
+  resolve() {
+    if (this.bound !== void 0) return this.bound;
+    let perDoc = BOUND.get(this.doc);
+    if (perDoc === void 0) {
+      perDoc = /* @__PURE__ */ new Map();
+      BOUND.set(this.doc, perDoc);
+    }
+    let handle = perDoc.get(this.planId);
+    if (handle === void 0) {
+      handle = bindPlan(this.doc, this.planId);
+      perDoc.set(this.planId, handle);
+    }
+    this.bound = handle;
+    return handle;
+  }
+  async execute(params, options) {
+    const target = this.resolve();
+    return target.execute(params, options);
+  }
+};
+function loadPreparedPlan(doc, planId, body) {
+  void body;
+  return new LazyAotHandle(doc, planId);
+}
+
 // src/relation/maintenance-rebuild.ts
 function toClass(m) {
   try {
@@ -1853,6 +2114,7 @@ function assertDefinition(name, def) {
   }
 }
 export {
+  AotPreparedWriteStatement,
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
   BatchGetResult,
@@ -1873,6 +2135,9 @@ export {
   MaintenanceRebuilder,
   MetadataRegistry,
   OLD_VALUE_NAMESPACE,
+  PREPARE_CACHE_MAX,
+  PreparedReadStatement,
+  PreparedWriteStatement,
   RetryingExecutor,
   SPEC_VERSION,
   TableMapping,
@@ -1987,6 +2252,7 @@ export {
   isMutationInputRef,
   isParam,
   isPlannedCommandMethod,
+  isPreparedParamRef,
   isQueryModelContract,
   isRetryableError,
   isRetryableTransactionCancellation,
@@ -1997,6 +2263,7 @@ export {
   lifecyclePhaseForIntent,
   list,
   literal,
+  loadPreparedPlan,
   maintainTrigger,
   maintainedFrom,
   map,
@@ -2012,6 +2279,7 @@ export {
   param,
   parseChange,
   plan,
+  prepare,
   preview,
   publicCommandModel,
   publicQueryModel,

package/dist/linter/index.d.ts

@@ -1,7 +1,7 @@
-import { L as LintRule } from '../registry-DbqmFyab.js';
-export { a as LintResult, b as Linter } from '../registry-DbqmFyab.js';
-export { c as createDefaultLinter, g as gsiAmbiguityRule, m as missingGsiRule, n as noScanRule, q as queryBoundaryRule, r as relationDepthRule, a as requireLimitRule } from '../relation-depth-0TiWr5OW.js';
-import '../maintenance-view-adapter-CFeasCKo.js';
+import { L as LintRule } from '../registry-BndKbZbg.js';
+export { a as LintResult, b as Linter } from '../registry-BndKbZbg.js';
+export { c as createDefaultLinter, g as gsiAmbiguityRule, m as missingGsiRule, n as noScanRule, q as queryBoundaryRule, r as relationDepthRule, a as requireLimitRule } from '../relation-depth-CCGHLTOv.js';
+import '../maintenance-view-adapter-NBTZbE8-.js';
 import '@aws-sdk/client-dynamodb';
 
 /**