graphddb 0.6.0 → 0.7.1

package/dist/transform/index.js

@@ -0,0 +1,982 @@
+// src/transform/prepared-transform.ts
+import ts from "typescript";
+var HOIST_SLOT_PREFIX = "__gddbPrepared";
+var SLOT_NAME_RE = /^__gddbPrepared\d+$/;
+function collectModuleBindings(sf) {
+  const out = /* @__PURE__ */ new Map();
+  for (const stmt of sf.statements) {
+    if (ts.isImportDeclaration(stmt) && stmt.importClause) {
+      const clause = stmt.importClause;
+      if (clause.name) {
+        out.set(clause.name.text, {
+          kind: "import",
+          importedName: void 0,
+          namespace: false
+        });
+      }
+      const bindings = clause.namedBindings;
+      if (bindings) {
+        if (ts.isNamespaceImport(bindings)) {
+          out.set(bindings.name.text, {
+            kind: "import",
+            importedName: void 0,
+            namespace: true
+          });
+        } else {
+          for (const spec of bindings.elements) {
+            out.set(spec.name.text, {
+              kind: "import",
+              importedName: (spec.propertyName ?? spec.name).text,
+              namespace: false
+            });
+          }
+        }
+      }
+    } else if (ts.isVariableStatement(stmt)) {
+      const isConst = (stmt.declarationList.flags & ts.NodeFlags.Const) !== 0;
+      for (const decl of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name)) {
+          out.set(
+            decl.name.text,
+            isConst ? { kind: "const", initializer: decl.initializer } : { kind: "mutable" }
+          );
+        } else {
+          for (const name of bindingNames(decl.name)) {
+            out.set(
+              name,
+              isConst ? { kind: "const", initializer: void 0 } : { kind: "mutable" }
+            );
+          }
+        }
+      }
+    } else if (ts.isClassDeclaration(stmt) && stmt.name) {
+      out.set(stmt.name.text, { kind: "class", node: stmt });
+    } else if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+      out.set(stmt.name.text, { kind: "function", node: stmt });
+    } else if (ts.isEnumDeclaration(stmt)) {
+      out.set(stmt.name.text, { kind: "enum" });
+    }
+  }
+  return out;
+}
+function bindingNames(name) {
+  if (ts.isIdentifier(name)) return [name.text];
+  const out = [];
+  for (const el of name.elements) {
+    if (ts.isBindingElement(el)) out.push(...bindingNames(el.name));
+  }
+  return out;
+}
+function isDDBModelRef(expr, bindings, seen = /* @__PURE__ */ new Set()) {
+  const e = unwrapExpr(expr);
+  if (ts.isIdentifier(e)) {
+    const name = e.text;
+    if (seen.has(name)) return false;
+    seen.add(name);
+    const b = bindings.get(name);
+    if (!b) return false;
+    if (b.kind === "import") return b.importedName === "DDBModel";
+    if (b.kind === "const" && b.initializer)
+      return isDDBModelRef(b.initializer, bindings, seen);
+    if (b.kind === "class") {
+      const heritage = b.node.heritageClauses?.find(
+        (h) => h.token === ts.SyntaxKind.ExtendsKeyword
+      );
+      const base = heritage?.types[0]?.expression;
+      return base !== void 0 && isDDBModelRef(base, bindings, seen);
+    }
+    return false;
+  }
+  if (ts.isPropertyAccessExpression(e) && e.name.text === "DDBModel") {
+    const root = unwrapExpr(e.expression);
+    if (ts.isIdentifier(root)) {
+      const b = bindings.get(root.text);
+      return b?.kind === "import" && b.namespace;
+    }
+  }
+  return false;
+}
+function unwrapExpr(e) {
+  let cur = e;
+  for (; ; ) {
+    if (ts.isParenthesizedExpression(cur)) cur = cur.expression;
+    else if (ts.isAsExpression(cur)) cur = cur.expression;
+    else if (ts.isSatisfiesExpression(cur)) cur = cur.expression;
+    else if (ts.isNonNullExpression(cur)) cur = cur.expression;
+    else if (ts.isTypeAssertionExpression(cur)) cur = cur.expression;
+    else return cur;
+  }
+}
+function isFunctionLikeScope(n) {
+  return ts.isFunctionDeclaration(n) || ts.isFunctionExpression(n) || ts.isArrowFunction(n) || ts.isMethodDeclaration(n) || ts.isConstructorDeclaration(n) || ts.isGetAccessorDeclaration(n) || ts.isSetAccessorDeclaration(n);
+}
+function scopeDeclares(scope, name) {
+  if (isFunctionLikeScope(scope)) {
+    const fn = scope;
+    for (const p of fn.parameters) {
+      if (bindingNames(p.name).includes(name)) return true;
+    }
+    if (fn.body && ts.isBlock(fn.body) && blockDeclares(fn.body, name)) return true;
+    if ((ts.isFunctionExpression(scope) || ts.isFunctionDeclaration(scope)) && scope.name?.text === name) {
+      return true;
+    }
+    return false;
+  }
+  if (ts.isBlock(scope)) return blockDeclares(scope, name);
+  if (ts.isCatchClause(scope)) {
+    return scope.variableDeclaration !== void 0 && bindingNames(scope.variableDeclaration.name).includes(name);
+  }
+  if (ts.isForStatement(scope) || ts.isForOfStatement(scope) || ts.isForInStatement(scope)) {
+    const init = scope.initializer;
+    if (init && ts.isVariableDeclarationList(init)) {
+      for (const d of init.declarations) {
+        if (bindingNames(d.name).includes(name)) return true;
+      }
+    }
+    return false;
+  }
+  return false;
+}
+function blockDeclares(block, name) {
+  for (const stmt of block.statements) {
+    if (ts.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (bindingNames(d.name).includes(name)) return true;
+      }
+    } else if ((ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt)) && stmt.name?.text === name) {
+      return true;
+    }
+  }
+  return false;
+}
+function resolveIdentifier(id, bodyFn, bindings) {
+  const name = id.text;
+  let node = id;
+  while (node.parent) {
+    const parent = node.parent;
+    if (isFunctionLikeScope(parent) || ts.isBlock(parent) || ts.isCatchClause(parent) || ts.isForStatement(parent) || ts.isForOfStatement(parent) || ts.isForInStatement(parent)) {
+      if (scopeDeclares(parent, name)) {
+        if (bodyFn && isInside(parent, bodyFn)) return { at: "body-local" };
+        if (isFunctionLikeScope(parent) || hasFunctionAncestorBelowModule(parent)) {
+          return { at: "enclosing-function" };
+        }
+        return { at: "module", binding: { kind: "const", initializer: void 0 } };
+      }
+    }
+    node = parent;
+  }
+  const b = bindings.get(name);
+  if (b) return { at: "module", binding: b };
+  return { at: "unresolved" };
+}
+function isInside(node, ancestor) {
+  let cur = node;
+  while (cur) {
+    if (cur === ancestor) return true;
+    cur = cur.parent;
+  }
+  return false;
+}
+function hasFunctionAncestorBelowModule(node) {
+  let cur = node.parent;
+  while (cur && !ts.isSourceFile(cur)) {
+    if (isFunctionLikeScope(cur)) return true;
+    cur = cur.parent;
+  }
+  return false;
+}
+function report(ctx, node, code, message, category = "error") {
+  const { line, character } = ctx.sf.getLineAndCharacterOfPosition(node.getStart(ctx.sf));
+  ctx.diagnostics.push({
+    code,
+    category,
+    message,
+    file: ctx.fileName,
+    line: line + 1,
+    column: character + 1
+  });
+}
+function lintPreparedBody(ctx, fn) {
+  const before = countErrors(ctx.diagnostics);
+  if (fn.parameters.length > 1) {
+    report(
+      ctx,
+      fn.parameters[1],
+      "impure-expression",
+      "A prepared body takes exactly one parameter (the `$` placeholder)."
+    );
+    return countErrors(ctx.diagnostics) - before;
+  }
+  const paramNames = /* @__PURE__ */ new Set();
+  const destructured = /* @__PURE__ */ new Set();
+  const param = fn.parameters[0];
+  if (param) {
+    if (ts.isIdentifier(param.name)) {
+      paramNames.add(param.name.text);
+    } else if (ts.isObjectBindingPattern(param.name)) {
+      for (const el of param.name.elements) {
+        if (!ts.isBindingElement(el) || !ts.isIdentifier(el.name) || el.initializer !== void 0 || el.dotDotDotToken !== void 0 || el.propertyName !== void 0 && !ts.isIdentifier(el.propertyName)) {
+          report(
+            ctx,
+            el,
+            "impure-expression",
+            "Only a plain, single-level destructuring of the `$` placeholder is supported (no nesting, defaults, or rest)."
+          );
+        } else {
+          destructured.add(el.name.text);
+        }
+      }
+    } else {
+      report(
+        ctx,
+        param,
+        "impure-expression",
+        "The `$` parameter must be a plain identifier or a single-level object destructuring."
+      );
+    }
+  }
+  const env = { bodyFn: fn, paramNames, destructuredParamNames: destructured };
+  const body = fn.body;
+  if (body !== void 0) {
+    if (ts.isBlock(body)) lintBodyBlock(ctx, body, env);
+    else checkExpr(ctx, body, env);
+  }
+  return countErrors(ctx.diagnostics) - before;
+}
+function countErrors(diags) {
+  return diags.reduce((n, d) => n + (d.category === "error" ? 1 : 0), 0);
+}
+function lintBodyBlock(ctx, block, env) {
+  for (const stmt of block.statements) {
+    if (ts.isReturnStatement(stmt)) {
+      if (stmt.expression) checkExpr(ctx, stmt.expression, env);
+      continue;
+    }
+    if (ts.isVariableStatement(stmt) && (stmt.declarationList.flags & ts.NodeFlags.Const) !== 0) {
+      for (const d of stmt.declarationList.declarations) {
+        if (d.initializer) checkExpr(ctx, d.initializer, env);
+      }
+      continue;
+    }
+    report(
+      ctx,
+      stmt,
+      "impure-expression",
+      "A prepared body block may contain only `const` declarations and `return` statements \u2014 any other statement is per-call control flow, which breaks compile-time hoisting."
+    );
+  }
+}
+function checkExpr(ctx, node, env) {
+  const e = unwrapExpr(node);
+  if (ts.isStringLiteral(e) || ts.isNumericLiteral(e) || ts.isBigIntLiteral(e) || ts.isNoSubstitutionTemplateLiteral(e) || e.kind === ts.SyntaxKind.TrueKeyword || e.kind === ts.SyntaxKind.FalseKeyword || e.kind === ts.SyntaxKind.NullKeyword) {
+    return;
+  }
+  if (ts.isPrefixUnaryExpression(e) && (e.operator === ts.SyntaxKind.MinusToken || e.operator === ts.SyntaxKind.PlusToken) && ts.isNumericLiteral(e.operand)) {
+    return;
+  }
+  if (ts.isObjectLiteralExpression(e)) {
+    for (const prop of e.properties) {
+      if (ts.isPropertyAssignment(prop)) {
+        if (ts.isComputedPropertyName(prop.name)) {
+          report(
+            ctx,
+            prop.name,
+            "impure-expression",
+            "A computed property name is per-call control flow \u2014 a prepared template needs statically known keys."
+          );
+        }
+        checkExpr(ctx, prop.initializer, env);
+      } else if (ts.isShorthandPropertyAssignment(prop)) {
+        checkIdentifierRef(ctx, prop.name, env);
+      } else if (ts.isSpreadAssignment(prop)) {
+        checkExpr(ctx, prop.expression, env);
+      } else {
+        report(
+          ctx,
+          prop,
+          "impure-expression",
+          "Only plain property assignments are supported in a prepared template."
+        );
+      }
+    }
+    return;
+  }
+  if (ts.isArrayLiteralExpression(e)) {
+    for (const el of e.elements) {
+      if (ts.isSpreadElement(el)) checkExpr(ctx, el.expression, env);
+      else checkExpr(ctx, el, env);
+    }
+    return;
+  }
+  if (ts.isArrowFunction(e) || ts.isFunctionExpression(e)) {
+    if (e.parameters.length !== 0) {
+      report(
+        ctx,
+        e,
+        "impure-expression",
+        "A function inside a prepared template is only valid as a zero-parameter model ref (`() => Model`)."
+      );
+      return;
+    }
+    const refExpr = thunkResultExpression(e);
+    if (refExpr === void 0) {
+      report(
+        ctx,
+        e,
+        "impure-expression",
+        "A model-ref thunk must be a single expression (or single `return`) referencing a module-static model."
+      );
+      return;
+    }
+    checkStaticRefChain(ctx, refExpr, env);
+    return;
+  }
+  if (ts.isIdentifier(e)) {
+    checkIdentifierRef(ctx, e, env);
+    return;
+  }
+  if (ts.isPropertyAccessExpression(e)) {
+    checkPropertyChain(ctx, e, env);
+    return;
+  }
+  if (ts.isCallExpression(e) || ts.isNewExpression(e)) {
+    report(
+      ctx,
+      e,
+      "call-in-body",
+      "A call inside a prepared body is an indirect runtime-capture channel (the lint cannot see through it, and even a global like `Date.now()` is a fresh per-call value). Inline the result as a static literal, bind it via `$`, or extract a module-scope `const` template."
+    );
+    return;
+  }
+  if (e.kind === ts.SyntaxKind.ThisKeyword) {
+    report(
+      ctx,
+      e,
+      "runtime-capture",
+      "`this` inside a prepared body captures the per-call receiver. Bind the value via `$` instead."
+    );
+    return;
+  }
+  if (ts.isTemplateExpression(e)) {
+    report(
+      ctx,
+      e,
+      "impure-expression",
+      "A template literal with substitutions embeds a runtime value into the template. Bind the value via `$` (the runtime binds whole fields, never string fragments)."
+    );
+    return;
+  }
+  report(
+    ctx,
+    e,
+    "impure-expression",
+    `Unsupported expression (${ts.SyntaxKind[e.kind]}) in a prepared body \u2014 only object/array literals, static literals, \`$.<name>\` refs, module-static references, and \`() => Model\` thunks are declarative.`
+  );
+}
+function thunkResultExpression(fn) {
+  if (ts.isArrowFunction(fn) && !ts.isBlock(fn.body)) return fn.body;
+  const body = fn.body;
+  if (body && ts.isBlock(body) && body.statements.length === 1) {
+    const only = body.statements[0];
+    if (ts.isReturnStatement(only) && only.expression) return only.expression;
+  }
+  return void 0;
+}
+function checkStaticRefChain(ctx, expr, env) {
+  const e = unwrapExpr(expr);
+  if (ts.isIdentifier(e)) {
+    checkIdentifierRef(
+      ctx,
+      e,
+      env,
+      /* refOnly */
+      true
+    );
+    return;
+  }
+  if (ts.isPropertyAccessExpression(e)) {
+    checkPropertyChain(
+      ctx,
+      e,
+      env,
+      /* refOnly */
+      true
+    );
+    return;
+  }
+  report(
+    ctx,
+    e,
+    "impure-expression",
+    "A model ref must be a plain reference to a module-static model (`() => Model` / `() => ns.Model`)."
+  );
+}
+function checkIdentifierRef(ctx, id, env, refOnly = false) {
+  const name = id.text;
+  if (name === "undefined") {
+    report(
+      ctx,
+      id,
+      "non-static-reference",
+      "`undefined` is not a bindable template value \u2014 omit the field or bind it via `$`."
+    );
+    return;
+  }
+  if (env.paramNames.has(name)) {
+    report(
+      ctx,
+      id,
+      "impure-expression",
+      "The `$` placeholder itself is not a value \u2014 bind a specific param via `$.<name>`."
+    );
+    return;
+  }
+  if (env.destructuredParamNames.has(name)) return;
+  const res = resolveIdentifier(id, env.bodyFn, ctx.bindings);
+  switch (res.at) {
+    case "body-local":
+      return;
+    case "enclosing-function":
+      report(
+        ctx,
+        id,
+        "runtime-capture",
+        `'${name}' is declared in an enclosing function \u2014 a per-call runtime value captured into the prepared body. Bind it via \`$\` (a per-call param) or move it to a module-scope \`const\`.`
+      );
+      return;
+    case "unresolved":
+      report(
+        ctx,
+        id,
+        "non-static-reference",
+        `'${name}' does not resolve to \`$\` or a module-static binding in this file. Globals are per-call runtime state; a prepared body may reference only \`$\` and module-static values.`
+      );
+      return;
+    case "module":
+      checkModuleBindingUse(ctx, id, name, res.binding, refOnly);
+      return;
+  }
+}
+function checkModuleBindingUse(ctx, at, name, binding, refOnly) {
+  switch (binding.kind) {
+    case "mutable":
+      report(
+        ctx,
+        at,
+        "mutable-module-state",
+        `'${name}' is module-scope \`let\`/\`var\` \u2014 mutable module state. A hoisted body would freeze its value while an unhoisted one would not; results must not depend on placement. Make it a \`const\` or bind it via \`$\`.`
+      );
+      return;
+    case "import":
+    case "class":
+    case "enum":
+      return;
+    // module-static by construction (see the documented limits).
+    case "function":
+      if (binding.node.parameters.length === 0) {
+        const result = binding.node.body ? functionSingleReturn(binding.node) : void 0;
+        if (result !== void 0) {
+          checkStaticRefChain(
+            ctx,
+            result,
+            // Module context: no `$`, no body scope.
+            { bodyFn: void 0, paramNames: /* @__PURE__ */ new Set(), destructuredParamNames: /* @__PURE__ */ new Set() }
+          );
+          return;
+        }
+      }
+      if (!refOnly) return;
+      report(
+        ctx,
+        at,
+        "impure-expression",
+        `'${name}' is not a zero-parameter thunk returning a module-static reference \u2014 a model ref must be statically resolvable.`
+      );
+      return;
+    case "const": {
+      if (binding.initializer === void 0) return;
+      if (ctx.visitedConsts.has(name)) return;
+      ctx.visitedConsts.add(name);
+      checkExpr(ctx, binding.initializer, {
+        bodyFn: void 0,
+        paramNames: /* @__PURE__ */ new Set(),
+        destructuredParamNames: /* @__PURE__ */ new Set()
+      });
+      return;
+    }
+  }
+}
+function functionSingleReturn(fn) {
+  const body = fn.body;
+  if (body && body.statements.length === 1) {
+    const only = body.statements[0];
+    if (ts.isReturnStatement(only) && only.expression) return only.expression;
+  }
+  return void 0;
+}
+function checkPropertyChain(ctx, e, env, refOnly = false) {
+  let levels = 0;
+  let cur = e;
+  while (ts.isPropertyAccessExpression(cur)) {
+    levels += 1;
+    cur = unwrapExpr(cur.expression);
+  }
+  if (ts.isIdentifier(cur)) {
+    const rootName = cur.text;
+    if (env.paramNames.has(rootName)) {
+      if (levels > 1) {
+        report(
+          ctx,
+          e,
+          "param-deep-access",
+          "Only a direct `$.<name>` read is supported \u2014 nested access on a param is a per-call transform the runtime rejects too."
+        );
+      }
+      return;
+    }
+    if (env.destructuredParamNames.has(rootName)) {
+      report(
+        ctx,
+        e,
+        "param-deep-access",
+        "A destructured `$` param is already the bound value \u2014 nested access on it is a per-call transform."
+      );
+      return;
+    }
+    checkIdentifierRef(ctx, cur, env, refOnly);
+    return;
+  }
+  if (cur.kind === ts.SyntaxKind.ThisKeyword) {
+    report(
+      ctx,
+      e,
+      "runtime-capture",
+      "`this` inside a prepared body captures the per-call receiver. Bind the value via `$` instead."
+    );
+    return;
+  }
+  report(
+    ctx,
+    e,
+    "impure-expression",
+    "A property chain in a prepared body must be rooted at `$` or a module-static reference."
+  );
+}
+function isPerCallSite(call) {
+  let cur = call.parent;
+  while (cur && !ts.isSourceFile(cur)) {
+    if (isFunctionLikeScope(cur)) return true;
+    if (ts.isPropertyDeclaration(cur) && !cur.modifiers?.some((m) => m.kind === ts.SyntaxKind.StaticKeyword)) {
+      return true;
+    }
+    cur = cur.parent;
+  }
+  return false;
+}
+function isAlreadyHoisted(call) {
+  const parent = call.parent;
+  return parent !== void 0 && ts.isBinaryExpression(parent) && parent.operatorToken.kind === ts.SyntaxKind.QuestionQuestionEqualsToken && ts.isIdentifier(parent.left) && SLOT_NAME_RE.test(parent.left.text) && parent.right === call;
+}
+function transformPreparedSource(fileName, sourceText, options = {}) {
+  const mode = options.mode ?? "transform";
+  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,
+    /* setParentNodes */
+    true,
+    scriptKind
+  );
+  const bindings = collectModuleBindings(sf);
+  const ctx = {
+    sf,
+    fileName,
+    bindings,
+    diagnostics: [],
+    visitedConsts: /* @__PURE__ */ new Set()
+  };
+  const calls = [];
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "prepare" && isDDBModelRef(node.expression.expression, bindings)) {
+      let bodyFn;
+      let indirect = false;
+      const arg = node.arguments.length === 1 ? unwrapExpr(node.arguments[0]) : void 0;
+      if (arg && (ts.isArrowFunction(arg) || ts.isFunctionExpression(arg))) {
+        bodyFn = arg;
+      } else if (arg && ts.isIdentifier(arg)) {
+        const res = resolveIdentifier(arg, void 0, bindings);
+        if (res.at === "module") {
+          const b = res.binding;
+          if (b.kind === "const" && b.initializer) {
+            const init = unwrapExpr(b.initializer);
+            if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+              bodyFn = init;
+              indirect = true;
+            }
+          } else if (b.kind === "function") {
+            bodyFn = b.node;
+            indirect = true;
+          }
+        }
+      }
+      calls.push({ call: node, bodyFn, bodyIsIndirect: indirect });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  const edits = [];
+  const slotNames = [];
+  let hoistedCount = 0;
+  let moduleScopeCount = 0;
+  let alreadyHoistedCount = 0;
+  let slotIndex = 0;
+  for (const m of sourceText.matchAll(/__gddbPrepared(\d+)\b/g)) {
+    slotIndex = Math.max(slotIndex, Number(m[1]));
+  }
+  for (const { call, bodyFn } of calls) {
+    if (bodyFn === void 0) {
+      report(
+        ctx,
+        call,
+        "unverifiable-body",
+        "The `prepare` argument is not a statically visible function (an inline arrow/function or a module-scope `const` body). The no-runtime-capture lint cannot verify it \u2014 pass the body inline or as a module-scope const."
+      );
+      continue;
+    }
+    const bodyErrors = lintPreparedBody(ctx, bodyFn);
+    if (bodyErrors > 0) continue;
+    if (isAlreadyHoisted(call)) {
+      alreadyHoistedCount += 1;
+      continue;
+    }
+    if (!isPerCallSite(call)) {
+      moduleScopeCount += 1;
+      continue;
+    }
+    if (mode === "lint") {
+      report(
+        ctx,
+        call,
+        "hoistable",
+        "Inline `DDBModel.prepare` call site \u2014 `graphddb transform prepared --write` normalizes it to a module-scope prepared slot (zero per-op overhead). Untransformed it falls back to the runtime structural-memoization path.",
+        "note"
+      );
+      continue;
+    }
+    slotIndex += 1;
+    const slot = `${HOIST_SLOT_PREFIX}${slotIndex}`;
+    slotNames.push(slot);
+    edits.push({ pos: call.getStart(sf), insert: `(${slot} ??= ` });
+    edits.push({ pos: call.getEnd(), insert: `)` });
+    hoistedCount += 1;
+  }
+  const errorCount = countErrors(ctx.diagnostics);
+  if (errorCount > 0) {
+    return {
+      fileName,
+      text: sourceText,
+      changed: false,
+      hoistedCount: 0,
+      moduleScopeCount,
+      alreadyHoistedCount,
+      diagnostics: ctx.diagnostics,
+      errorCount
+    };
+  }
+  let text = sourceText;
+  if (hoistedCount > 0) {
+    let declPos = 0;
+    for (const stmt of sf.statements) {
+      if (ts.isImportDeclaration(stmt)) declPos = stmt.getEnd();
+    }
+    const nl = sourceText.includes("\r\n") ? "\r\n" : "\n";
+    const header = `${nl}${nl}// graphddb transform prepared (#206): module-scope lazy slots \u2014 each${nl}// prepared statement compiles once per module and every later call is a${nl}// plain \`.execute\` (zero per-op planning / hashing).` + slotNames.map((s) => `${nl}let ${s};`).join("");
+    edits.push({ pos: declPos, insert: declPos === 0 ? header.trimStart() + nl : header });
+    edits.sort((a, b) => b.pos - a.pos);
+    for (const e of edits) {
+      text = text.slice(0, e.pos) + e.insert + text.slice(e.pos);
+    }
+  }
+  return {
+    fileName,
+    text,
+    changed: text !== sourceText,
+    hoistedCount,
+    moduleScopeCount,
+    alreadyHoistedCount,
+    diagnostics: ctx.diagnostics,
+    errorCount: 0
+  };
+}
+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,
+  transformPreparedSourceAot
+};