graphddb 0.7.0 → 0.7.2

package/dist/transform/index.js

@@ -712,8 +712,271 @@ function transformPreparedSource(fileName, sourceText, options = {}) {
 function lintPreparedSource(fileName, sourceText) {
   return transformPreparedSource(fileName, sourceText, { mode: "lint" }).diagnostics;
 }
+var AOT_LOADER_LOCAL = "__gddbLoadPreparedPlan";
+var AOT_PLANS_LOCAL = "__gddbPreparedPlans";
+var AOT_SHIM_EXPORT = "__gddbAotBodies";
+function referencedIdentifierNames(node, out) {
+  const visit = (n) => {
+    if (ts.isIdentifier(n)) {
+      const parent = n.parent;
+      if (parent !== void 0) {
+        if (ts.isPropertyAccessExpression(parent) && parent.name === n) return;
+        if (ts.isQualifiedName(parent) && parent.right === n) return;
+        if ((ts.isClassDeclaration(parent) || ts.isFunctionDeclaration(parent) || ts.isEnumDeclaration(parent) || ts.isVariableDeclaration(parent) || ts.isParameter(parent) || ts.isMethodDeclaration(parent) || ts.isPropertyDeclaration(parent) || ts.isGetAccessorDeclaration(parent) || ts.isSetAccessorDeclaration(parent) || ts.isBindingElement(parent)) && parent.name === n) {
+          return;
+        }
+        if (ts.isPropertyAssignment(parent) && parent.name === n) return;
+        if (ts.isImportSpecifier(parent) || ts.isExportSpecifier(parent)) return;
+      }
+      out.add(n.text);
+      return;
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(node);
+}
+function collectShimDeps(roots, bindings) {
+  const referenced = /* @__PURE__ */ new Set();
+  for (const root of roots) referencedIdentifierNames(root, referenced);
+  const deps = /* @__PURE__ */ new Set();
+  const queue = [...referenced];
+  while (queue.length > 0) {
+    const name = queue.pop();
+    if (deps.has(name)) continue;
+    const binding = bindings.get(name);
+    if (binding === void 0) continue;
+    deps.add(name);
+    const nested = /* @__PURE__ */ new Set();
+    if (binding.kind === "const" && binding.initializer !== void 0) {
+      referencedIdentifierNames(binding.initializer, nested);
+    } else if (binding.kind === "class" || binding.kind === "function") {
+      referencedIdentifierNames(binding.node, nested);
+    }
+    for (const n of nested) {
+      if (!deps.has(n)) queue.push(n);
+    }
+  }
+  return deps;
+}
+function statementBoundNames(stmt) {
+  const names = [];
+  if (ts.isImportDeclaration(stmt) && stmt.importClause) {
+    const clause = stmt.importClause;
+    if (clause.name) names.push(clause.name.text);
+    const b = clause.namedBindings;
+    if (b) {
+      if (ts.isNamespaceImport(b)) names.push(b.name.text);
+      else for (const spec of b.elements) names.push(spec.name.text);
+    }
+  } else if (ts.isVariableStatement(stmt)) {
+    for (const d of stmt.declarationList.declarations) names.push(...bindingNames(d.name));
+  } else if ((ts.isClassDeclaration(stmt) || ts.isFunctionDeclaration(stmt) || ts.isEnumDeclaration(stmt)) && stmt.name !== void 0) {
+    names.push(stmt.name.text);
+  }
+  return names;
+}
+function transformPreparedSourceAot(fileName, sourceText, options) {
+  const scriptKind = fileName.endsWith(".tsx") ? ts.ScriptKind.TSX : fileName.endsWith(".jsx") ? ts.ScriptKind.JSX : ts.ScriptKind.TS;
+  const sf = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, scriptKind);
+  const bindings = collectModuleBindings(sf);
+  const ctx = { sf, fileName, bindings, diagnostics: [], visitedConsts: /* @__PURE__ */ new Set() };
+  const detected = [];
+  const visit = (node) => {
+    if (ts.isCallExpression(node)) {
+      if (ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "prepare" && isDDBModelRef(node.expression.expression, bindings)) {
+        const arg = node.arguments.length >= 1 ? node.arguments[0] : void 0;
+        const resolved = arg !== void 0 ? resolveBodyFn(arg, bindings) : void 0;
+        if (arg !== void 0) {
+          detected.push({ call: node, form: "prepare", bodyArg: arg, bodyFn: resolved });
+        } else {
+          report(ctx, node, "unverifiable-body", "A `prepare` call needs a body argument.");
+        }
+      } else if (ts.isIdentifier(node.expression) && node.expression.text === AOT_LOADER_LOCAL) {
+        if (node.arguments.length !== 3 || !ts.isStringLiteral(node.arguments[1])) {
+          report(
+            ctx,
+            node,
+            "unverifiable-body",
+            `A '${AOT_LOADER_LOCAL}' call must have the generated shape (document, '<plan id>', body). Regenerate with --aot --write.`
+          );
+        } else {
+          const arg = node.arguments[2];
+          detected.push({
+            call: node,
+            form: "aot",
+            bodyArg: arg,
+            bodyFn: resolveBodyFn(arg, bindings),
+            idLiteral: node.arguments[1]
+          });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  const edits = [];
+  const slotNames = [];
+  const sites = [];
+  const verifiedBodies = [];
+  let slotIndex = 0;
+  for (const m of sourceText.matchAll(/__gddbPrepared(\d+)\b/g)) {
+    slotIndex = Math.max(slotIndex, Number(m[1]));
+  }
+  let needsHeaderImports = false;
+  let index = 0;
+  for (const site of detected) {
+    index += 1;
+    const planId = `${options.planIdPrefix}#${index}`;
+    if (site.bodyFn === void 0) {
+      report(
+        ctx,
+        site.call,
+        "unverifiable-body",
+        "The prepared body is not a statically visible function (an inline arrow/function or a module-scope `const` body) \u2014 it cannot be verified or compiled at build time."
+      );
+      continue;
+    }
+    const bodyErrors = lintPreparedBody(ctx, site.bodyFn);
+    if (bodyErrors > 0) continue;
+    sites.push({ index, planId, form: site.form });
+    verifiedBodies.push({ index, bodyArg: site.bodyArg, bodyFn: site.bodyFn });
+    if (options.mode === "check") {
+      if (site.form === "prepare") {
+        report(
+          ctx,
+          site.call,
+          "aot-pending",
+          `Call site not yet rewritten to the static prepared plan '${planId}' \u2014 run \`graphddb transform prepared --aot <artifact> --write\`.`,
+          "note"
+        );
+      }
+      continue;
+    }
+    if (site.form === "prepare") {
+      needsHeaderImports = true;
+      edits.push({
+        pos: site.call.getStart(sf),
+        end: site.bodyArg.getStart(sf),
+        insert: `${AOT_LOADER_LOCAL}(${AOT_PLANS_LOCAL}, ${JSON.stringify(planId)}, `
+      });
+      if (isPerCallSite(site.call) && !isAlreadyHoisted(site.call)) {
+        slotIndex += 1;
+        const slot = `${HOIST_SLOT_PREFIX}${slotIndex}`;
+        slotNames.push(slot);
+        edits.push({ pos: site.call.getStart(sf), end: site.call.getStart(sf), insert: `(${slot} ??= ` });
+        edits.push({ pos: site.call.getEnd(), end: site.call.getEnd(), insert: `)` });
+      }
+    } else if (site.idLiteral !== void 0 && site.idLiteral.text !== planId) {
+      edits.push({
+        pos: site.idLiteral.getStart(sf),
+        end: site.idLiteral.getEnd(),
+        insert: JSON.stringify(planId)
+      });
+    }
+  }
+  const errorCount = countErrors(ctx.diagnostics);
+  if (errorCount > 0) {
+    return {
+      fileName,
+      text: sourceText,
+      changed: false,
+      sites: [],
+      diagnostics: ctx.diagnostics,
+      errorCount
+    };
+  }
+  let shimSource;
+  if (verifiedBodies.length > 0) {
+    const deps = collectShimDeps(
+      verifiedBodies.flatMap((b) => [b.bodyFn, b.bodyArg]),
+      bindings
+    );
+    const parts = [
+      "// Generated by `graphddb transform prepared --aot` \u2014 build-time evaluation",
+      "// shim (auto-deleted). Carries ONLY the module-static declarations the",
+      "// prepared bodies reference; top-level side effects are NOT copied."
+    ];
+    for (const stmt of sf.statements) {
+      const bound = statementBoundNames(stmt);
+      if (bound.length === 0) continue;
+      const isDecl = ts.isImportDeclaration(stmt) || ts.isVariableStatement(stmt) || ts.isClassDeclaration(stmt) || ts.isFunctionDeclaration(stmt) || ts.isEnumDeclaration(stmt);
+      if (!isDecl) continue;
+      if (bound.some((n) => deps.has(n))) {
+        parts.push(sourceText.slice(stmt.getStart(sf), stmt.getEnd()));
+      }
+    }
+    for (const b of verifiedBodies) {
+      parts.push(
+        `const __gddbAotBody_${b.index} = (${sourceText.slice(
+          b.bodyArg.getStart(sf),
+          b.bodyArg.getEnd()
+        )});`
+      );
+    }
+    parts.push(
+      `export const ${AOT_SHIM_EXPORT} = {` + verifiedBodies.map((b) => ` ${b.index}: __gddbAotBody_${b.index},`).join("") + " };"
+    );
+    shimSource = parts.join("\n") + "\n";
+  }
+  let text = sourceText;
+  if (options.mode === "transform" && (edits.length > 0 || needsHeaderImports)) {
+    let header = "";
+    const nl = sourceText.includes("\r\n") ? "\r\n" : "\n";
+    if (needsHeaderImports && !bindings.has(AOT_LOADER_LOCAL)) {
+      header += `${nl}${nl}// graphddb transform prepared --aot (#208): static prepared plans \u2014 each${nl}// call site loads its build-time-compiled plan; the body stays in source as${nl}// the plan's compile source (drift regeneration) and typed fallback.${nl}import { loadPreparedPlan as ${AOT_LOADER_LOCAL} } from 'graphddb';${nl}import ${AOT_PLANS_LOCAL} from '${options.artifactImport}';`;
+    }
+    if (slotNames.length > 0) {
+      header += `${nl}${nl}// graphddb transform prepared (#206): module-scope lazy slots.` + slotNames.map((s) => `${nl}let ${s};`).join("");
+    }
+    if (header !== "") {
+      let declPos = 0;
+      for (const stmt of sf.statements) {
+        if (ts.isImportDeclaration(stmt)) declPos = stmt.getEnd();
+      }
+      edits.push({
+        pos: declPos,
+        end: declPos,
+        insert: declPos === 0 ? header.trimStart() + nl : header
+      });
+    }
+    edits.sort((a, b) => b.pos - a.pos || b.end - a.end);
+    for (const e of edits) {
+      text = text.slice(0, e.pos) + e.insert + text.slice(e.end);
+    }
+  }
+  return {
+    fileName,
+    text,
+    changed: text !== sourceText,
+    sites,
+    ...shimSource !== void 0 ? { shimSource } : {},
+    diagnostics: ctx.diagnostics,
+    errorCount: 0
+  };
+}
+function resolveBodyFn(arg, bindings) {
+  const e = unwrapExpr(arg);
+  if (ts.isArrowFunction(e) || ts.isFunctionExpression(e)) return e;
+  if (ts.isIdentifier(e)) {
+    const res = resolveIdentifier(e, void 0, bindings);
+    if (res.at === "module") {
+      const b = res.binding;
+      if (b.kind === "const" && b.initializer !== void 0) {
+        const init = unwrapExpr(b.initializer);
+        if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) return init;
+      } else if (b.kind === "function") {
+        return b.node;
+      }
+    }
+  }
+  return void 0;
+}
 export {
+  AOT_LOADER_LOCAL,
+  AOT_PLANS_LOCAL,
+  AOT_SHIM_EXPORT,
   HOIST_SLOT_PREFIX,
   lintPreparedSource,
-  transformPreparedSource
+  transformPreparedSource,
+  transformPreparedSourceAot
 };

package/docs/cqrs-contract.md

@@ -393,7 +393,7 @@ input produces a byte-identical pre-contract document).
 
 ```jsonc
 {
-  "version": "1.0",
+  "version": "1.1",
   "contracts": {
     // point query: single OR array (array → BatchGetItem)
     "ArticleById": {

package/docs/design-patterns.md

@@ -180,13 +180,15 @@ BatchGet, so a `refs` read's `select` cannot push a server-side `FilterExpressio
 on the children (BatchGet has none); filter on the returned `items` if needed.
 
 > **Runtime scope.** A `refs` read fans a **parent-row list attribute** out into a
-> BatchGet. The static operations spec (`operations.json`) and the generated Python
-> runtime bind relation keys from a single scalar `{result.<field>}` and have no
-> parent-list key-fan-out primitive, so a `refs` relation is resolvable **only**
-> through the TS in-process runtime. Compiling a select that traverses a `refs`
-> relation to `operations.json` / generated Python **fails loudly** (rather than
-> emitting a physically wrong scalar-key BatchGet); resolve it in the generated-code
-> consumer with a separate BatchGet if you need it there.
+> BatchGet. Since issue #208 (spec version 1.1) the shared operation IR carries this
+> as a first-class **binding form** (`sourceList` on a `BatchGetItem` op), so a
+> select that traverses a `refs` relation compiles to `operations.json` and the
+> generated Python runtime resolves it with the same semantics as the TS in-process
+> runtime (first-seen order, dedup, dangling refs dropped, `cursor: null`; the
+> parent list attribute is projected implicitly and stripped from the result when
+> unselected). One remaining spec-path difference: a client-side `filter` on a
+> `refs` select is TS-in-process-only and is rejected loudly by the spec compiler
+> (never silently dropped).
 
 ---
 

package/docs/prepared-statements.md

@@ -5,7 +5,8 @@
 `execute(params)` binds the per-call values into the precompiled plan and runs
 it through the **same execution cores** `DDBModel.mutate` / `Model.query` /
 `Model.list` and the public CQRS contracts use — effects are identical by
-construction (design #203, runtime #205, compile-time transform #206).
+construction (design #203, runtime #205, compile-time transform #206, static
+AOT plans #208).
 
 ## The three execution layers (orthogonal, pick per use)
 
@@ -61,14 +62,80 @@ whole contract:
 
 | Build | Per-op cost of an inline `prepare(fn).execute()` | Result |
 |---|---|---|
-| **transform applied** (`graphddb transform prepared --write`) | **zero** planning / compiling / structure hashing — the call site is normalized to a module-scope prepared slot; after the first call it is a nullish check + `.execute` | identical |
+| **AOT** (`graphddb transform prepared --aot <artifact> --write`, #208) | **zero compilation at runtime, including the first call** — the plan was compiled at BUILD time into a static artifact; the call site loads it and every call binds params into the frozen plan | identical |
+| **transform applied** (`graphddb transform prepared --write`) | zero per-op after the FIRST call (the lazy slot compiles once per module at first use) | identical |
 | **no transform** (fallback) | phase-1 **structural memoization**: the body is re-evaluated and structure-hashed per call, then the compiled handle is reused from a bounded LRU (no recompile) | identical |
-| hand-hoisted module-level `const stmt = DDBModel.prepare(...)` | zero (already optimal; the transform leaves it untouched) | identical |
+| hand-hoisted module-level `const stmt = DDBModel.prepare(...)` | compile once at first use (runtime); the transform leaves it untouched | identical |
 
 The transform exists to remove the placement footgun: without it, an inline
 `prepare` is *correct but warmer* than a module-level one (silent-slow). With
 it, both spellings compile to the same optimal form.
 
+### The three optimization tiers — when to use which
+
+1. **AOT static plans** (`--aot`, #208) — production builds with a build step.
+   Plan construction happens at BUILD time: cold starts (Lambda SnapStart,
+   first request) pay **zero** compilation, and a broken plan fails the
+   **build**, not the first request. Requires committing the generated
+   artifact module and running the drift check in CI (below).
+2. **Lazy slot + structural memoization** (`--write`, #206 / #205) — dev runs,
+   `tsx`/`ts-node` no-build-step deployments, and every call site the AOT pass
+   did not rewrite (e.g. `prepare` calls inside `node_modules`). The plan
+   compiles at runtime, once.
+3. **Ad-hoc `mutate` / `query`** — one-shot operations where preparing buys
+   nothing (recompiles per call, by design).
+
+The runtime structural-memoization cache is deliberately **kept** even when AOT
+is applied: untransformed builds and third-party `prepare` call sites fall back
+to it with identical behavior (perf only differs), so a build without the
+transform can never become silently per-call-slow.
+
+## True build-time compilation: `--aot` static plans (#208)
+
+```bash
+# compile every verified prepare body at BUILD time, write the static plan
+# artifact module, and rewrite call sites to load it
+graphddb transform prepared --src src/ --aot src/graphddb.prepared.ts --write
+
+# CI drift gate: recompile and compare — exits 1 when model declarations (or
+# prepare bodies) changed without regenerating the artifact
+graphddb transform prepared --src src/ --aot src/graphddb.prepared.ts
+```
+
+The rewrite keeps the body **in source** — it is the plan's compile source, the
+type source, and the untransformed-build fallback; at runtime the loader never
+evaluates it:
+
+```ts
+// after `--aot src/graphddb.prepared.ts --write`
+import { loadPreparedPlan as __gddbLoadPreparedPlan } from 'graphddb';
+import __gddbPreparedPlans from './graphddb.prepared.js';
+let __gddbPrepared1;
+export async function getUser(userId: string) {
+  return (__gddbPrepared1 ??= __gddbLoadPreparedPlan(__gddbPreparedPlans, 'src/app.ts#1', ($) => ({
+    u: { query: () => User, key: { userId: $.userId }, select: USER_SELECT },
+  }))).execute({ userId });
+}
+```
+
+What the artifact carries (the same serialized-IR vocabulary `operations.json`
+uses — templated key conditions / transaction items, model references by
+**entity name**):
+
+- a **write** plan freezes the whole mutation compile — lifecycle resolution
+  and every derived effect (edges, counters, uniqueness guards, outbox,
+  idempotency, maintenance writes, referential ConditionChecks) — into one
+  declarative `TransactionSpec` per op;
+- a **read** plan carries the analyzed route (entity, select template, param
+  binds, options) plus its physical `QuerySpec`, so a broken read plan fails
+  the build.
+
+**Stale plans never execute.** Each plan records a fingerprint of every entity
+declaration it touches; the loader recomputes them against the live
+`MetadataRegistry` on first use and rejects loudly on any mismatch (model /
+table-mapping drift since generation), version skew, or a missing plan id — in
+addition to the CI drift gate above.
+
 ### CLI
 
 ```bash

package/docs/python-bridge.md

@@ -153,7 +153,7 @@ so the output is stable across runs.
 
 ```jsonc
 {
-  "version": "1.0",
+  "version": "1.1",
   "tables": { "UserPermissions": { "physicalName": "UserPermissions" } },
   "entities": {
     "UserModel": {
@@ -199,14 +199,17 @@ so the output is stable across runs.
 - `key` / `gsis[*]` carry `inputFields` and `pkTemplate` / `skTemplate` where the
   templates use `{field}` placeholders (e.g. `USER#{userId}`, `EMAIL#{email}`).
   `skTemplate` is `null` when the access pattern has no sort key.
-- `relations[*]` is one of `hasMany | hasOne | belongsTo` with a `target` entity
-  and a `keyBinding` (target field → source field).
+- `relations[*]` is one of `hasMany | hasOne | belongsTo | refs` with a `target`
+  entity and a `keyBinding` (target field → source field). A `refs` relation
+  (issue #197 / #208) additionally carries `refs: { from, key }` — the parent
+  LIST attribute holding the inline reference elements and the field read off
+  each element.
 
 ### 4.2 `operations.json` — Execution Specs
 
 ```ts
 interface OperationsDocument {
-  readonly version: '1.0';
+  readonly version: '1.1';
   readonly queries: Record<string, QuerySpec>;
   readonly commands: Record<string, CommandSpec>;
   readonly transactions?: Record<string, TransactionSpec>;
@@ -468,6 +471,23 @@ GraphDDBRuntime(
 `table_mapping` maps logical table names to deployed physical names. The
 specs are loaded and cached at construction.
 
+**Spec-version guard (#208).** The IR is a stable execution contract, so
+construction validates both documents' `version` against
+`SPEC_VERSION_SUPPORTED` (currently `1.1`) and raises `GraphDDBError` — loudly,
+never a silent per-operation mis-execution — when a document cannot be
+faithfully executed. The compatibility rule for a `<major>.<minor>` document:
+
+- the **major** must equal the supported major (a major bump changes the shape
+  of existing vocabulary);
+- the **minor** must be **≤** the supported minor — minors are additive (e.g.
+  `1.1` added the `sourceList` list fan-out binding form for `refs`), so every
+  *older* document is fully understood, while a *newer* one may carry binding
+  forms this runtime does not implement and is forward-rejected;
+- a missing or malformed `version` is rejected.
+
+Upgrade `graphddb_runtime` (or regenerate the documents with a matching
+generator) to clear the error.
+
 | Method | Behavior |
 |---|---|
 | `execute_query(query_id, params, options=None) -> dict \| None` | Run a single- or multi-operation query; returns the hydrated result, or `None` when the root matches nothing. `options` may carry a pagination `cursor`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphddb",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Graph data modeling on DynamoDB with adjacency list pattern",
   "type": "module",
   "main": "dist/index.js",