@nudojs/service 3.0.0 → 5.0.0-beta.0

package/dist/chunk-HEU4WON5.js

@@ -0,0 +1,2419 @@
+import {
+  unifiedDiff
+} from "./chunk-YLVZMHWC.js";
+import {
+  analyzeFileAsync,
+  defaultLoadModule,
+  evalAbsModuleGraph
+} from "./chunk-QAFMPM2E.js";
+import {
+  diskCacheRoot,
+  findProjectConfig,
+  interfaceConfig,
+  matchesEmitAllowlist
+} from "./chunk-YLALZXTZ.js";
+
+// src/dep-contents.ts
+import { loadModuleDepsFingerprint } from "@nudojs/core/internal";
+function collectLoadDepContents(filePath, source, loadModule) {
+  const fp = loadModuleDepsFingerprint(source, loadModule, filePath);
+  const depContents = fp.contents.length > 0 ? fp.contents : fp.paths.map((path) => ({ path, content: null }));
+  return { depContents, truncated: fp.truncated };
+}
+
+// src/disk-cache.ts
+import { createHash } from "crypto";
+import { createRequire } from "module";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from "fs";
+import { join, dirname, relative, sep, isAbsolute } from "path";
+function readServiceVersion() {
+  try {
+    const require2 = createRequire(import.meta.url);
+    for (const p of ["../package.json", "./package.json", "../../package.json"]) {
+      try {
+        const pkg = require2(p);
+        if (pkg?.name === "@nudojs/service" && pkg.version) return pkg.version;
+        if (pkg?.version && p.includes("service")) return pkg.version;
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return "0";
+}
+var ANALYSIS_ABI = `nudo-check-cache-v3+${readServiceVersion()}`;
+function sha256Hex(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
+function relativizePath(p, root) {
+  const norm = p.split(sep).join("/");
+  if (!root) return norm;
+  const r = relative(root, p).split(sep).join("/");
+  if (!r.startsWith("..") && !isAbsolute(r)) return r;
+  return `ext:${createHash("sha256").update(norm).digest("hex").slice(0, 16)}`;
+}
+function sanitizeCacheNamespace(ns) {
+  return ns.replace(/[^a-z0-9_-]/gi, "_").replace(/^_+|_+$/g, "") || "cache";
+}
+var DiskCache = class {
+  root;
+  ns;
+  enabled = false;
+  constructor(opts) {
+    this.root = opts.root;
+    this.ns = sanitizeCacheNamespace(opts.namespace);
+    this.enabled = !!opts.root;
+  }
+  pathFor(key) {
+    if (!/^[a-f0-9]{16,128}$/i.test(key)) {
+      throw new Error("DiskCache key must be a hex digest");
+    }
+    return join(this.root, this.ns, key.slice(0, 2), `${key}.json`);
+  }
+  get(key) {
+    if (!this.enabled || !this.root) return void 0;
+    try {
+      const p = this.pathFor(key);
+      if (!existsSync(p)) return void 0;
+      const raw = readFileSync(p, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed?.abi !== ANALYSIS_ABI) return void 0;
+      return parsed.value;
+    } catch {
+      return void 0;
+    }
+  }
+  set(key, value) {
+    if (!this.enabled || !this.root) return;
+    try {
+      const p = this.pathFor(key);
+      mkdirSync(dirname(p), { recursive: true });
+      writeFileSync(p, JSON.stringify({ abi: ANALYSIS_ABI, value }), "utf8");
+    } catch {
+    }
+  }
+  clearNamespace() {
+    if (!this.enabled || !this.root) return;
+    try {
+      rmSync(join(this.root, this.ns), { recursive: true, force: true });
+    } catch {
+    }
+  }
+};
+function checkCacheKey(filePath, source, opts) {
+  const rel = relativizePath(filePath, opts.projectDir);
+  const sidecarSha = opts.sidecarContent != null ? sha256Hex(opts.sidecarContent) : "nosidecar";
+  const depSeg = (opts.depContents ?? []).map(
+    (d) => `${relativizePath(d.path, opts.projectDir)}\0${d.content != null ? sha256Hex(d.content) : "miss"}`
+  ).join("\n");
+  const envSeg = (opts.projectEnvNames ?? []).length > 0 ? [...opts.projectEnvNames ?? []].sort().join(",") : "-";
+  const cfgSeg = opts.analysisCfg ? `${opts.analysisCfg.mode ?? "-"}|${opts.analysisCfg.evalMissingSlot ?? "-"}|${opts.analysisCfg.callSiteBudget ?? "-"}|${opts.analysisCfg.entryThrows ?? "-"}|${opts.analysisCfg.ignoreThrows ?? "-"}` : "-";
+  return sha256Hex(
+    [
+      ANALYSIS_ABI,
+      rel,
+      opts.autoBind ? "ab1" : "ab0",
+      sha256Hex(source),
+      sidecarSha,
+      depSeg,
+      envSeg,
+      cfgSeg
+    ].join("\0")
+  );
+}
+function ifaceCacheKey(filePath, source, opts) {
+  const rel = relativizePath(filePath, opts.projectDir);
+  const sidecarSeg = opts.autoBind && opts.sidecarSource !== void 0 ? `sc:${sha256Hex(opts.sidecarSource)}` : "sc0";
+  const depSeg = (opts.depContents ?? []).map(
+    (d) => `${relativizePath(d.path, opts.projectDir)}\0${d.content != null ? sha256Hex(d.content) : "miss"}`
+  ).join("\n");
+  const envSeg = (opts.projectEnvNames ?? []).length > 0 ? [...opts.projectEnvNames ?? []].sort().join(",") : "-";
+  return sha256Hex(
+    [
+      ANALYSIS_ABI,
+      "iface",
+      rel,
+      opts.autoBind ? "ab1" : "ab0",
+      sha256Hex(source),
+      sidecarSeg,
+      depSeg,
+      envSeg
+    ].join("\0")
+  );
+}
+function extractNudoImportSpecs(source) {
+  const specs = /* @__PURE__ */ new Set();
+  const named = /@nudo:import\s*\{[^}]*\}\s*from\s*["']([^"']+)["']/g;
+  const ns = /@nudo:import\s+\*\s+as\s+\w+\s+from\s*["']([^"']+)["']/g;
+  let m;
+  while (m = named.exec(source)) specs.add(m[1]);
+  while (m = ns.exec(source)) specs.add(m[1]);
+  return [...specs];
+}
+
+// src/interface-surface.ts
+import { readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import { dirname as dirname2, resolve } from "path";
+import {
+  effectiveInterface,
+  formatConstraint,
+  formatShape,
+  interfaceDiagCount,
+  localNamedExports,
+  refineDiagCount,
+  sidecarPathOf,
+  takeInterfaceDiagsSince,
+  takeRefineDiagsSince
+} from "@nudojs/core";
+function collectDepContents(filePath, source, loadModule) {
+  return collectLoadDepContents(filePath, source, loadModule ?? defaultLoadModule);
+}
+function formatInterfaceSurfaceLine(e) {
+  const params = `(${e.params.map((p) => `${p.name}: ${p.display}`).join(", ")})`;
+  let line = `  ${e.fn}  [${e.source}]  ${params}`;
+  if (e.returns !== void 0) line += ` \u2192 ${e.returns}`;
+  if (e.kind === "local") line += "  (local)";
+  return line;
+}
+function absToImplicitDisplay(a) {
+  try {
+    return formatShape(a);
+  } catch {
+    return "unknown";
+  }
+}
+function constraintToJson(c) {
+  return JSON.parse(JSON.stringify(c));
+}
+function cachedToEffective(e) {
+  return {
+    fnName: e.fnName,
+    params: e.params.map((p) => ({
+      param: p.param,
+      constraint: p.constraint
+    })),
+    ...e.returns ? { returns: { constraint: e.returns.constraint } } : {},
+    source: e.source,
+    ...e.conflict ? { conflict: e.conflict } : {}
+  };
+}
+async function interfaceSurface(filePath, opts = {}) {
+  const abs = resolve(filePath);
+  const source = opts.source ?? readFileSync2(abs, "utf-8");
+  const fromBuffer = opts.source !== void 0;
+  const ifaceSince = interfaceDiagCount();
+  const refineSince = refineDiagCount();
+  const proj = findProjectConfig(dirname2(abs));
+  const autoBind = opts.autoBind ?? interfaceConfig(proj?.config).autoBind;
+  const loadModule = opts.loadModule ?? defaultLoadModule;
+  const exported = localNamedExports(source);
+  const kindOf = (fnName) => exported.has(fnName) ? "export" : "local";
+  const analysis = await analyzeFileAsync(abs, source, void 0, opts.records, loadModule);
+  let disk;
+  let ifaceKey;
+  let cachedTable;
+  if (!opts.loadModule && !opts.records && !fromBuffer) {
+    const cacheRoot = diskCacheRoot(proj?.config, proj?.projectDir);
+    disk = new DiskCache({ root: cacheRoot, namespace: "iface" });
+    if (disk.enabled) {
+      let sidecarSource;
+      try {
+        const sc = sidecarPathOf(abs);
+        if (autoBind !== false) {
+          const openSc = loadModule(`./${sc.slice(sc.lastIndexOf("/") + 1)}`, abs);
+          if (openSc !== void 0) sidecarSource = openSc;
+          else if (existsSync2(sc)) sidecarSource = readFileSync2(sc, "utf-8");
+        }
+      } catch {
+        sidecarSource = void 0;
+      }
+      const dep = collectDepContents(abs, source, loadModule);
+      const hasBareMiss = (dep.depContents ?? []).some((d) => d.content == null);
+      if (dep.truncated || hasBareMiss) {
+        ifaceKey = void 0;
+        cachedTable = void 0;
+      } else {
+        ifaceKey = ifaceCacheKey(abs, source, {
+          autoBind: autoBind !== false,
+          projectDir: proj?.projectDir,
+          sidecarSource,
+          depContents: dep.depContents,
+          projectEnvNames: proj?.config.env ?? []
+        });
+        cachedTable = disk.get(ifaceKey);
+      }
+    }
+  }
+  const entries = [];
+  const freshTable = { fns: {} };
+  const useCache = cachedTable !== void 0;
+  for (const fn of analysis.functions) {
+    let eff;
+    if (useCache) {
+      const hit = cachedTable.fns[fn.name];
+      eff = hit === null ? void 0 : hit ? cachedToEffective(hit) : void 0;
+    } else {
+      eff = effectiveInterface(source, fn.name, {
+        loadModule,
+        fromFile: abs,
+        autoBind,
+        ...proj?.projectDir ? { projectDir: proj.projectDir } : {}
+      });
+      if (freshTable) {
+        freshTable.fns[fn.name] = eff ? {
+          fnName: eff.fnName,
+          params: eff.params.map((p) => ({
+            param: p.param,
+            constraint: constraintToJson(p.constraint)
+          })),
+          ...eff.returns ? { returns: { constraint: constraintToJson(eff.returns.constraint) } } : {},
+          // 磁盘表保留真实分档；implicit 也可序列化（展示层用）
+          source: eff.source,
+          ...eff.conflict ? { conflict: eff.conflict } : {}
+        } : null;
+      }
+    }
+    if (eff) {
+      entries.push({
+        fn: fn.name,
+        kind: kindOf(fn.name),
+        source: eff.source,
+        params: eff.params.map((p) => ({ name: p.param, display: formatConstraint(p.constraint) })),
+        returns: eff.returns ? formatConstraint(eff.returns.constraint) : void 0
+      });
+      continue;
+    }
+    const params = fn.paramNames.map((name, i) => {
+      const seen = [];
+      for (const c of fn.cases) {
+        const absArg = c.argAbs[i];
+        if (absArg) {
+          const s = absToImplicitDisplay(absArg);
+          if (!seen.includes(s)) seen.push(s);
+        }
+      }
+      return { name, display: seen.length > 0 ? seen.join(" | ") : "unknown" };
+    });
+    let ret;
+    if (fn.combinedAbs) {
+      ret = absToImplicitDisplay(fn.combinedAbs);
+    } else if (fn.cases.length > 0) {
+      const last = fn.cases[fn.cases.length - 1];
+      ret = absToImplicitDisplay(last.abs);
+    }
+    entries.push({ fn: fn.name, kind: kindOf(fn.name), source: "implicit", params, returns: ret });
+  }
+  if (disk?.enabled && ifaceKey && !useCache && analysis.functions.length > 0) {
+    try {
+      disk.set(ifaceKey, freshTable);
+    } catch {
+    }
+  }
+  takeInterfaceDiagsSince(ifaceSince);
+  takeRefineDiagsSince(refineSince);
+  return entries;
+}
+
+// src/interface-emitter.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2, renameSync, unlinkSync } from "fs";
+import { basename, dirname as dirname3, relative as relative2, resolve as resolve2 } from "path";
+import {
+  execNudoModule,
+  formatConstraint as formatConstraint2,
+  interfaceDiagCount as interfaceDiagCount2,
+  isNodeModulesPath,
+  isNudoConstraint,
+  joinThenProject,
+  localNamedExports as localNamedExports2,
+  parseSource,
+  refineDiagCount as refineDiagCount2,
+  sidecarPathOf as sidecarPathOf2,
+  takeInterfaceDiagsSince as takeInterfaceDiagsSince2,
+  takeRefineDiagsSince as takeRefineDiagsSince2
+} from "@nudojs/core";
+import { randomBytes } from "crypto";
+var GENERATED_HEADER = "// @generated by nudo \u2014 do not edit; regenerate with `nudo contract --emit`";
+async function emitInterface(filePath, opts) {
+  const abs = resolve2(filePath);
+  if (isNodeModulesPath(abs) || isNodeModulesPath(sidecarPathOf2(abs))) {
+    throw new Error(
+      `emit target '${abs}' is inside node_modules; contract sidecars are never written there`
+    );
+  }
+  const proj = findProjectConfig(dirname3(abs));
+  const allow = interfaceConfig(proj?.config).emit;
+  if (!matchesEmitAllowlist(abs, proj?.projectDir, allow)) {
+    return {
+      written: [],
+      skipped: [{ fn: opts.fnNames?.[0] ?? "*", reason: "emit-denied" }],
+      changed: false,
+      issues: [
+        {
+          code: "nudo:interface-emit-denied",
+          severity: "warning",
+          message: `emit target '${relative2(process.cwd(), abs) || abs}' is outside package.json#nudo.contract.emit allowlist`
+        }
+      ],
+      sidecarPath: sidecarPathOf2(abs)
+    };
+  }
+  const source = opts.source ?? readFileSync3(abs, "utf-8");
+  const ifaceSince = interfaceDiagCount2();
+  const refineSince = refineDiagCount2();
+  const sidecarPath = sidecarPathOf2(abs);
+  const sidecarSrc = existsSync3(sidecarPath) ? readFileSync3(sidecarPath, "utf-8") : "";
+  const srcRel = relative2(dirname3(sidecarPath), abs) || basename(abs);
+  const sections = collectGeneratedSections(sidecarSrc);
+  const generatedNames = new Set(sections.flatMap((s) => s.names));
+  const declared = topLevelDeclaredNames(sidecarSrc);
+  if (declared === void 0) {
+    throw new Error(
+      `sidecar '${relative2(process.cwd(), sidecarPath) || sidecarPath}' is not parseable; fix it before emitting`
+    );
+  }
+  for (const n of generatedNames) declared.delete(n);
+  const analysis = await analyzeFileAsync(
+    abs,
+    source,
+    void 0,
+    opts.records,
+    opts.loadModule
+  );
+  const exported = localNamedExports2(source);
+  const fnByName = /* @__PURE__ */ new Map();
+  for (const f of analysis.functions) {
+    if (!fnByName.has(f.name)) fnByName.set(f.name, f);
+  }
+  const fileExportOrder = analysis.functions.map((f) => f.name).filter((n) => exported.has(n));
+  let targetNames;
+  if (opts.fnNames && opts.fnNames.length > 0) {
+    targetNames = [...new Set(opts.fnNames)];
+  } else if (opts.all) {
+    targetNames = fileExportOrder;
+  } else {
+    targetNames = fileExportOrder.filter((n) => generatedNames.has(n));
+  }
+  const targetSet = new Set(targetNames);
+  const written = [];
+  const skipped = [];
+  const issues = [];
+  const accepted = [];
+  const planCache = /* @__PURE__ */ new Map();
+  const planFor = (name) => {
+    const hit = planCache.get(name);
+    if (hit) return hit;
+    const fn = fnByName.get(name);
+    const dsl = fn === void 0 ? void 0 : projectFunctionDsl(fn);
+    const roundTrip = dsl !== void 0 && roundTrips(sectionText(name, dsl, srcRel), name);
+    const rec = { dsl, roundTrip };
+    planCache.set(name, rec);
+    return rec;
+  };
+  const atomicSections = /* @__PURE__ */ new Set();
+  for (const s of sections) {
+    if (s.names.length <= 1) continue;
+    const everyRewritable = s.names.every(
+      (n) => targetSet.has(n) && exported.has(n) && !declared.has(n) && planFor(n).dsl !== void 0 && planFor(n).roundTrip
+    );
+    if (!everyRewritable) atomicSections.add(s);
+  }
+  const acceptedAtomic = /* @__PURE__ */ new Set();
+  for (const name of targetNames) {
+    if (!exported.has(name) || !fnByName.has(name)) {
+      skipped.push({
+        fn: name,
+        reason: "not-an-export"
+      });
+      continue;
+    }
+    if (declared.has(name)) {
+      skipped.push({ fn: name, reason: "name-clash" });
+      issues.push({
+        code: "nudo:interface-name-clash",
+        severity: "error",
+        message: `sidecar already has a handwritten binding '${name}' (${srcRel}); handwritten wins \u2014 skipping emit for it`
+      });
+      continue;
+    }
+    const prev = sections.find((s) => s.names.includes(name));
+    if (prev !== void 0 && atomicSections.has(prev)) {
+      if (!acceptedAtomic.has(prev)) {
+        acceptedAtomic.add(prev);
+        const keptText = normalizeSection(prev.text);
+        accepted.push({ fn: prev.names.join("+"), text: keptText, prevText: keptText });
+        issues.push({
+          code: "nudo:interface-multi-declarator",
+          severity: "warning",
+          message: `generated section '${prev.names.join(", ")}' is a hand-merged multi-declarator form; kept verbatim (split it into one export per section to re-emit)`
+        });
+      }
+      skipped.push({ fn: name, reason: "multi-declarator" });
+      continue;
+    }
+    const prevText = prev === void 0 ? void 0 : normalizeSection(prev.text);
+    const plan = planFor(name);
+    if (plan.dsl === void 0 || !plan.roundTrip) {
+      skipped.push({ fn: name, reason: "not-projectable" });
+      if (prevText !== void 0) {
+        accepted.push({ fn: name, text: prevText, prevText });
+      }
+      continue;
+    }
+    const text = sectionText(name, plan.dsl, srcRel);
+    if (opts.mode === "add" && prev !== void 0) {
+      skipped.push({ fn: name, reason: "no-change" });
+      continue;
+    }
+    if (prevText !== void 0 && prevText === normalizeSection(text)) {
+      skipped.push({ fn: name, reason: "no-change" });
+      accepted.push({ fn: name, text: prevText, prevText });
+      continue;
+    }
+    written.push(name);
+    accepted.push({ fn: name, text, prevText });
+  }
+  let finalContent;
+  if (opts.mode === "add") {
+    finalContent = accepted.length === 0 ? sidecarSrc : joinSections(sidecarSrc, accepted.map((a) => a.text));
+  } else {
+    const base = removeSections(sidecarSrc, sections);
+    const preserved = sections.filter((s) => !s.names.some((n) => targetSet.has(n))).map((s) => normalizeSection(s.text));
+    finalContent = joinSections(base, [...preserved, ...accepted.map((a) => a.text)]);
+  }
+  const changed = finalContent !== sidecarSrc;
+  const diff = changed ? unifiedDiff(sidecarSrc, finalContent, relative2(process.cwd(), sidecarPath) || sidecarPath) : void 0;
+  if (changed && !opts.dryRun) {
+    const tmp = `${sidecarPath}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+    try {
+      writeFileSync2(tmp, finalContent, "utf-8");
+      renameSync(tmp, sidecarPath);
+    } catch (e) {
+      try {
+        if (existsSync3(tmp)) unlinkSync(tmp);
+      } catch {
+      }
+      throw e;
+    }
+  }
+  takeRefineDiagsSince2(refineSince);
+  takeInterfaceDiagsSince2(ifaceSince);
+  return {
+    written,
+    skipped,
+    changed,
+    ...diff !== void 0 ? { diff } : {},
+    issues,
+    sidecarPath,
+    ...opts.fnNames && opts.fnNames.length > 0 ? {} : opts.all ? {} : targetNames.length === 0 ? { emptyDefaultTargets: true } : {}
+  };
+}
+function formatEmitSummary(sourcePath, sidecarRel, result) {
+  const lines = [];
+  if (result.changed) {
+    lines.push(`Updated ${sourcePath} \u2192 ${sidecarRel}`);
+    lines.push(`  written: ${result.written.join(", ") || "(none)"}`);
+  } else {
+    lines.push(`${sourcePath}: no interface changes`);
+    if (result.emptyDefaultTargets) {
+      lines.push(
+        `  tip: default --emit only refreshes existing @generated segments; pass --fn <name> or --all to create new ones`
+      );
+    }
+  }
+  for (const s of result.skipped.filter((x) => x.reason !== "no-change")) {
+    lines.push(`  skipped ${s.fn} (${s.reason})`);
+  }
+  for (const i of result.issues) {
+    lines.push(`  [${i.severity}] ${i.code}: ${i.message}`);
+  }
+  return lines;
+}
+function projectFunctionDsl(fn) {
+  const callsite = fn.cases.filter((c) => c.source === "callsite");
+  const directive = fn.cases.filter((c) => c.source === "directive");
+  const paramCases = callsite.length > 0 ? callsite : directive;
+  const returnCases = callsite.length > 0 ? callsite : directive.length > 0 ? directive : fn.cases;
+  const paramParts = [];
+  for (let i = 0; i < fn.paramNames.length; i++) {
+    const argAbs = [];
+    for (const c of paramCases) {
+      const a = c.argAbs[i];
+      if (a !== void 0) argAbs.push(a);
+    }
+    if (argAbs.length === 0) continue;
+    const constraint = joinThenProject(argAbs);
+    if (constraint === void 0) return void 0;
+    paramParts.push(`${fn.paramNames[i]}: ${formatConstraint2(constraint)}`);
+  }
+  const retAbs = [];
+  for (const c of returnCases) {
+    if (c.throwsAbs.shape.k !== "never") continue;
+    retAbs.push(c.abs);
+  }
+  const retConstraint = retAbs.length > 0 ? joinThenProject(retAbs) : void 0;
+  if (retConstraint === void 0 && paramParts.length === 0) return void 0;
+  if (retAbs.length > 0 && retConstraint === void 0) return void 0;
+  const ret = retConstraint === void 0 ? "" : `, ${formatConstraint2(retConstraint)}`;
+  return `fn({ ${paramParts.join(", ")} }${ret})`;
+}
+function sectionText(fn, dsl, srcRel) {
+  return `${GENERATED_HEADER}
+// source: ${srcRel}:${fn}
+export const ${fn} = ${dsl};
+`;
+}
+function roundTrips(text, fn) {
+  const since = refineDiagCount2();
+  try {
+    const exports = execNudoModule(text);
+    const v = exports[fn];
+    return isNudoConstraint(v) && v.fn !== void 0;
+  } catch {
+    return false;
+  } finally {
+    takeRefineDiagsSince2(since);
+  }
+}
+function collectGeneratedSections(sidecarSrc) {
+  if (sidecarSrc.trim() === "") return [];
+  let ast;
+  try {
+    ast = parseSource(sidecarSrc);
+  } catch {
+    throw new Error("sidecar is not parseable");
+  }
+  const out = [];
+  for (const stmt of ast.program.body) {
+    if (stmt.type !== "ExportNamedDeclaration" || stmt.source) continue;
+    const d = stmt.declaration;
+    if (!d || stmt.start == null || stmt.end == null) continue;
+    const names = [];
+    if (d.type === "VariableDeclaration") {
+      for (const decl of d.declarations) {
+        if (decl.id.type === "Identifier") names.push(decl.id.name);
+      }
+    } else if (d.type === "FunctionDeclaration" || d.type === "ClassDeclaration") {
+      if (d.id) names.push(d.id.name);
+    }
+    if (names.length === 0) continue;
+    const blockStart = generatedCommentBlockStart(sidecarSrc, stmt.start);
+    if (blockStart === void 0) continue;
+    out.push({ names, start: blockStart, end: stmt.end, text: sidecarSrc.slice(blockStart, stmt.end) });
+  }
+  return out;
+}
+function generatedCommentBlockStart(src, pos) {
+  const lines = src.slice(0, pos).split("\n");
+  let blockStartLine = -1;
+  let sawGenerated = false;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (line === "" || line === "*/") continue;
+    if (line.startsWith("//") || line.startsWith("/*") || line.startsWith("*")) {
+      blockStartLine = i;
+      if (/@generated/.test(line)) sawGenerated = true;
+      continue;
+    }
+    break;
+  }
+  if (!sawGenerated || blockStartLine < 0) return void 0;
+  const prefix = lines.slice(0, blockStartLine);
+  return prefix.length === 0 ? 0 : prefix.join("\n").length + 1;
+}
+function topLevelDeclaredNames(sidecarSrc) {
+  if (sidecarSrc.trim() === "") return /* @__PURE__ */ new Set();
+  let ast;
+  try {
+    ast = parseSource(sidecarSrc);
+  } catch {
+    return void 0;
+  }
+  const names = /* @__PURE__ */ new Set();
+  const collect = (stmt) => {
+    if (stmt.type === "VariableDeclaration") {
+      for (const d of stmt.declarations) {
+        if (d.id.type === "Identifier") names.add(d.id.name);
+      }
+    } else if (stmt.type === "FunctionDeclaration" || stmt.type === "ClassDeclaration") {
+      if (stmt.id) names.add(stmt.id.name);
+    }
+  };
+  for (const stmt of ast.program.body) {
+    if (stmt.type === "ExportNamedDeclaration") {
+      if (stmt.declaration) collect(stmt.declaration);
+      if (!stmt.source) {
+        for (const spec of stmt.specifiers) {
+          names.add(spec.exported.type === "Identifier" ? spec.exported.name : spec.exported.value);
+        }
+      }
+    } else {
+      collect(stmt);
+    }
+  }
+  return names;
+}
+function removeSections(src, sections) {
+  if (sections.length === 0) return src;
+  const sorted = [...sections].sort((a, b) => a.start - b.start);
+  let out = "";
+  let pos = 0;
+  for (const s of sorted) {
+    out += src.slice(pos, s.start);
+    pos = Math.max(pos, s.end);
+  }
+  out += src.slice(pos);
+  return out;
+}
+function normalizeSection(text) {
+  return text.replace(/\s*$/, "") + "\n";
+}
+function joinSections(base, sectionTexts) {
+  const normalized = sectionTexts.map(normalizeSection).filter((t) => t.trim() !== "");
+  const tailTrimmed = base.replace(/\s+$/, "");
+  if (normalized.length === 0) return tailTrimmed === "" ? "" : `${tailTrimmed}
+`;
+  const trimmed = tailTrimmed.replace(/^\s+/, "");
+  const lead = trimmed === "" ? "" : `${trimmed}
+
+`;
+  return lead + normalized.join("\n");
+}
+
+// src/interface-draft.ts
+import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync3, realpathSync } from "fs";
+import { basename as basename2, dirname as dirname4, isAbsolute as isAbsolute2, join as join2, relative as relative3 } from "path";
+import {
+  effectiveInterface as effectiveInterface2,
+  formatConstraint as formatConstraint3,
+  formatShape as formatShape2,
+  generalizeFromAst,
+  isIntFlag,
+  joinThenProject as joinThenProject2,
+  localNamedExports as localNamedExports3,
+  sidecarPathOf as sidecarPathOf3
+} from "@nudojs/core";
+import { parse } from "@nudojs/parser";
+function collectParamBodyAccesses(source) {
+  const out = /* @__PURE__ */ new Map();
+  let ast;
+  try {
+    ast = parse(source);
+  } catch {
+    return out;
+  }
+  const keyOf = (node) => {
+    if (node.type === "Identifier") return node.name;
+    if (node.type === "StringLiteral") return node.value;
+    return void 0;
+  };
+  const visitFn = (fnName, fnNode, paramNames) => {
+    if (paramNames.size === 0) return;
+    const byParam = /* @__PURE__ */ new Map();
+    const walk = (node, shadowed) => {
+      if (!node || typeof node !== "object") return;
+      const n = node;
+      if ((n.type === "VariableDeclarator" || n.type === "FunctionDeclaration") && n.id?.type === "Identifier") {
+        const id = n.id.name;
+        if (paramNames.has(id)) {
+          shadowed = new Set(shadowed).add(id);
+        }
+      }
+      if (n.type === "MemberExpression" || n.type === "OptionalMemberExpression") {
+        const obj = n.object;
+        const prop = n.property;
+        const computed = n.computed === true;
+        if (obj?.type === "Identifier" && paramNames.has(obj.name) && !shadowed.has(obj.name) && prop && !computed) {
+          const key = keyOf(prop);
+          const pname = obj.name;
+          if (key !== void 0) {
+            if (!byParam.has(pname)) byParam.set(pname, /* @__PURE__ */ new Set());
+            byParam.get(pname).add(key);
+          }
+        }
+      }
+      for (const k of Object.keys(n)) {
+        if (k === "loc" || k === "start" || k === "end") continue;
+        const child = n[k];
+        if (Array.isArray(child)) {
+          for (const item of child) walk(item, shadowed);
+        } else if (child && typeof child === "object") {
+          walk(child, shadowed);
+        }
+      }
+    };
+    walk(fnNode, /* @__PURE__ */ new Set());
+    if (byParam.size > 0) out.set(fnName, byParam);
+  };
+  const paramSet = (fnNode) => {
+    const names = /* @__PURE__ */ new Set();
+    const params = fnNode.params ?? [];
+    for (const p of params) {
+      if (!p) continue;
+      if (p.type === "Identifier") names.add(p.name);
+      else if (p.type === "AssignmentPattern" && p.left?.type === "Identifier") {
+        names.add(p.left.name);
+      } else if (p.type === "RestElement" && p.argument?.type === "Identifier") {
+        names.add(p.argument.name);
+      } else if (p.type === "ObjectPattern") {
+        for (const prop of p.properties ?? []) {
+          if (prop.type === "ObjectProperty") {
+            const v = prop.value;
+            if (v.type === "Identifier") names.add(v.name);
+            else if (v.type === "AssignmentPattern" && v.left?.type === "Identifier") {
+              names.add(v.left.name);
+            }
+          }
+        }
+      }
+    }
+    return names;
+  };
+  const visitClassMethods = (className, classNode) => {
+    const body = classNode.body?.body ?? [];
+    for (const m of body) {
+      const mem = m;
+      const isMethod = mem.type === "MethodDefinition" || mem.type === "ClassMethod" || mem.type === "TSDeclareMethod";
+      if (!isMethod || mem.static) continue;
+      if (mem.kind && mem.kind !== "method") continue;
+      const keyName = mem.key?.type === "Identifier" ? mem.key.name : void 0;
+      if (!keyName) continue;
+      const methodNode = mem.type === "MethodDefinition" ? mem.value : mem;
+      if (!methodNode) continue;
+      visitFn(`${className}.${keyName}`, methodNode, paramSet(methodNode));
+    }
+  };
+  const considerDecl = (decl, exported) => {
+    if (!decl) return;
+    if (decl.type === "FunctionDeclaration" && decl.id) {
+      const id = decl.id;
+      visitFn(id.name, decl, paramSet(decl));
+      return;
+    }
+    if (decl.type === "ClassDeclaration" && decl.id?.name) {
+      visitClassMethods(decl.id.name, decl);
+      return;
+    }
+    if (decl.type === "VariableDeclaration") {
+      for (const d of decl.declarations ?? []) {
+        const id = d.id;
+        const init = d.init;
+        if (exported && id?.type === "Identifier" && init && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")) {
+          visitFn(id.name, init, paramSet(init));
+        }
+      }
+    }
+  };
+  const program = ast.program;
+  const bodyStmts = program?.body ?? [];
+  for (const stmt of bodyStmts) {
+    if (stmt.type === "ExportNamedDeclaration") {
+      considerDecl(stmt.declaration, true);
+      for (const spec of stmt.specifiers ?? []) {
+        const local = spec.local;
+        if (local?.type !== "Identifier") continue;
+        for (const s2 of bodyStmts) {
+          if (s2.type === "ClassDeclaration" && s2.id?.name === local.name) {
+            visitClassMethods(local.name, s2);
+          }
+        }
+      }
+    } else if (stmt.type === "ExportDefaultDeclaration") {
+      considerDecl(stmt.declaration, true);
+    } else if (stmt.type === "ClassDeclaration") {
+      const id = stmt.id;
+      if (id?.name) visitClassMethods(id.name, stmt);
+    } else if (stmt.type === "FunctionDeclaration") {
+    }
+  }
+  return out;
+}
+function caseEvidence(fn) {
+  const callsite = fn.cases.filter((c) => c.source === "callsite");
+  const directive = fn.cases.filter((c) => c.source === "directive");
+  return {
+    paramCases: callsite.length > 0 ? callsite : directive,
+    returnCases: callsite.length > 0 ? callsite : directive.length > 0 ? directive : fn.cases,
+    paramEvidence: callsite.length > 0 ? "callsite" : directive.length > 0 ? "directive" : "none",
+    rawReturnEvidence: callsite.length > 0 ? "callsite" : directive.length > 0 ? "directive" : "none"
+  };
+}
+function widenDraftConstraint(c) {
+  const stripEqLits = (preds2) => preds2.filter((p) => !(p.op === "eq" && p.b?.op === "lit"));
+  if (c.members && c.members.length > 0) {
+    const widenedMembers = c.members.map(widenDraftConstraint).filter((m) => m !== void 0);
+    if (widenedMembers.length === 0) {
+      const prim = litPrimOf(c.members[0]);
+      if (!prim) return void 0;
+      return { __nudoConstraint: true, prim, preds: [] };
+    }
+    const prims = new Set(widenedMembers.map((m) => m.prim).filter(Boolean));
+    if (prims.size === 1 && widenedMembers.every((m) => !m.fields && !m.element && !m.members)) {
+      return { __nudoConstraint: true, prim: [...prims][0], preds: [] };
+    }
+    return {
+      __nudoConstraint: true,
+      ...c.prim ? { prim: c.prim } : {},
+      preds: stripEqLits(c.preds ?? []),
+      members: widenedMembers
+    };
+  }
+  if (c.fields) {
+    const fields = {};
+    for (const [k, f] of Object.entries(c.fields)) {
+      const w = widenDraftConstraint(f.constraint);
+      if (!w) continue;
+      fields[k] = { constraint: w, ...f.optional ? { optional: true } : {} };
+    }
+    return {
+      __nudoConstraint: true,
+      fields,
+      preds: stripEqLits(c.preds ?? [])
+    };
+  }
+  if (c.element) {
+    const el = widenDraftConstraint(c.element);
+    return {
+      __nudoConstraint: true,
+      preds: stripEqLits(c.preds ?? []),
+      ...el ? { element: el } : {}
+    };
+  }
+  if (c.fn) return void 0;
+  const preds = stripEqLits(c.preds ?? []);
+  const hasBounds = preds.length > 0;
+  if (!c.prim && !hasBounds && !isIntFlag(c)) return void 0;
+  return {
+    __nudoConstraint: true,
+    ...c.prim ? { prim: c.prim } : {},
+    preds,
+    // builder 上 .int 是链式方法，truthy 恒真；必须经 isIntFlag
+    ...isIntFlag(c) ? { int: true } : {}
+  };
+}
+function litPrimOf(c) {
+  if (!c) return void 0;
+  if (c.prim === "number" || c.prim === "string" || c.prim === "boolean") return c.prim;
+  const eq = c.preds?.find(
+    (p) => p.op === "eq" && p.b?.op === "lit"
+  );
+  const v = eq && eq.b?.op === "lit" ? eq.b.value : void 0;
+  if (typeof v === "number") return "number";
+  if (typeof v === "string") return "string";
+  if (typeof v === "boolean") return "boolean";
+  return c.members?.[0] ? litPrimOf(c.members[0]) : void 0;
+}
+function projectDraftParams(fn, paramCases, bodyByParam, formals) {
+  const bodyFor = (name, index) => {
+    if (!bodyByParam) return void 0;
+    const hit = bodyByParam.get(name);
+    if (hit) return hit;
+    const formal = formals?.[index];
+    if (formal && formal.kind === "pattern") {
+      for (const b of formal.bound) {
+        const boundHit = bodyByParam.get(b);
+        if (boundHit) return boundHit;
+      }
+    }
+    return bodyByParam.get(`_p${index}`);
+  };
+  return fn.paramNames.map((name, i) => {
+    const bodyAccesses = bodyFor(name, i) ? [...bodyFor(name, i)].sort() : void 0;
+    const argAbs = [];
+    for (const c of paramCases) {
+      const a = c.argAbs[i];
+      if (a !== void 0) argAbs.push(a);
+    }
+    if (argAbs.length === 0) {
+      if (bodyAccesses && bodyAccesses.length > 0) {
+        return {
+          name,
+          display: `/* body-read { ${bodyAccesses.join(", ")} } \u2014 fill types when accepting */`,
+          projected: false,
+          bodyAccesses
+        };
+      }
+      return { name, display: "/* no evidence \u2014 tighten */", projected: false };
+    }
+    const raw = joinThenProject2(argAbs);
+    if (raw === void 0) {
+      return {
+        name,
+        display: `/* not projectable: ${argAbs.map((a) => formatShape2(a)).join(" | ")} */`,
+        projected: false,
+        ...bodyAccesses ? { bodyAccesses } : {}
+      };
+    }
+    const constraint = widenDraftConstraint(raw);
+    if (constraint === void 0) {
+      const observed2 = formatConstraint3(raw);
+      return {
+        name,
+        display: `/* observed: ${observed2} \u2014 widen/confirm before accepting */`,
+        projected: false,
+        ...bodyAccesses ? { bodyAccesses } : {}
+      };
+    }
+    let display = formatConstraint3(constraint);
+    const observed = formatConstraint3(raw);
+    if (observed !== display) {
+      display += `  /* observed: ${observed} */`;
+    }
+    if (bodyAccesses && bodyAccesses.length > 0) {
+      display += `  /* body also reads: ${bodyAccesses.join(", ")} */`;
+    }
+    return {
+      name,
+      constraint,
+      display,
+      projected: true,
+      ...bodyAccesses ? { bodyAccesses } : {}
+    };
+  });
+}
+function projectDraftReturn(fn, returnCases, source, rawEvidence, loadModule, fromFile) {
+  const retAbs = [];
+  for (const c of returnCases) {
+    if (c.throwsAbs.shape.k !== "never") continue;
+    retAbs.push(c.abs);
+  }
+  if (retAbs.length > 0) {
+    const raw = joinThenProject2(retAbs);
+    if (raw !== void 0) {
+      if (rawEvidence === "none" || rawEvidence === "body") {
+        return {
+          display: `/* observed: ${formatConstraint3(raw)} \u2014 confirm before accepting */`,
+          projected: false,
+          evidence: rawEvidence === "none" ? "body" : rawEvidence
+        };
+      }
+      const constraint = widenDraftConstraint(raw);
+      if (constraint === void 0) {
+        return {
+          display: `/* observed: ${formatConstraint3(raw)} \u2014 widen/confirm */`,
+          projected: false,
+          evidence: rawEvidence
+        };
+      }
+      return {
+        constraint,
+        display: formatConstraint3(constraint),
+        projected: true,
+        evidence: rawEvidence
+      };
+    }
+    const shapeText = fn.combinedAbs ? formatShape2(fn.combinedAbs) : formatShape2(retAbs[0]);
+    return {
+      display: `/* not projectable: ${shapeText} */`,
+      projected: false,
+      evidence: rawEvidence
+    };
+  }
+  try {
+    const g = generalizeFromAst(fn.name, source, {
+      refine: {
+        ...loadModule ? { loadModule } : {},
+        ...fromFile ? { fromFile } : {}
+      }
+    });
+    if (g?.symbolic) {
+      return {
+        display: `/* symbolic: ${formatShape2(g.symbolic)}${g.display ? ` \u2014 ${g.display}` : ""} */`,
+        projected: false,
+        evidence: "symbolic"
+      };
+    }
+  } catch {
+  }
+  return { display: "/* no evidence */", projected: false, evidence: "none" };
+}
+function toDraftBuilderDsl(display) {
+  const s = display.replace(/\s*\/\*[\s\S]*?\*\/\s*/g, "").trim();
+  return s.replace(
+    /([A-Za-z_$][\w$]*)\?\s*:\s*([^,}\n]+)/g,
+    (_m, name, val) => {
+      const v = val.trim();
+      if (v.includes(".optional()")) return `${name}: ${v}`;
+      return `${name}: ${v}.optional()`;
+    }
+  );
+}
+function draftExportName(fnName) {
+  return fnName.includes(".") ? fnName.replace(/\./g, "_") : fnName;
+}
+function draftDsl(entry) {
+  const parts = entry.params.filter((p) => p.projected && p.constraint !== void 0).map((p) => {
+    const pure = toDraftBuilderDsl(formatConstraint3(p.constraint));
+    return `${p.name}: ${pure}`;
+  });
+  const obj = parts.length === 0 ? "{}" : `{ ${parts.join(", ")} }`;
+  const ret = entry.returns?.projected && entry.returns.constraint !== void 0 ? toDraftBuilderDsl(formatConstraint3(entry.returns.constraint)) : void 0;
+  return ret === void 0 || ret === "" ? `fn(${obj})` : `fn(${obj}, ${ret})`;
+}
+function suggestedBodyDsl(fnName, params) {
+  const withBody = params.filter((p) => p.bodyAccesses && p.bodyAccesses.length > 0 && !p.projected);
+  if (withBody.length === 0) return void 0;
+  const parts = withBody.map((p) => {
+    const fields = p.bodyAccesses.map((k) => `${k}: /* TODO */`).join(", ");
+    return `${p.name}: shape({ ${fields} })`;
+  });
+  return `//   suggested (body-read, not a contract): ${fnName} = fn({ ${parts.join(", ")} })`;
+}
+async function draftInterface(filePath, opts = {}) {
+  const source = opts.source ?? readFileSync4(filePath, "utf-8");
+  const loadModule = opts.loadModule ?? defaultLoadModule;
+  const sidecarPath = sidecarPathOf3(filePath);
+  const wantBody = opts.bodyAccesses !== false;
+  const analysis = await analyzeFileAsync(filePath, source, void 0, opts.records, loadModule);
+  const exported = localNamedExports3(source);
+  const selected = opts.fnNames && opts.fnNames.length > 0 ? new Set(opts.fnNames) : exported;
+  const bodyMap = wantBody ? collectParamBodyAccesses(source) : /* @__PURE__ */ new Map();
+  const entries = [];
+  for (const fn of analysis.functions) {
+    if (!selected.has(fn.name) && !opts.fnNames?.includes(fn.name)) continue;
+    if (!exported.has(fn.name)) {
+      if (opts.fnNames?.includes(fn.name)) {
+        entries.push({
+          fn: fn.name,
+          params: fn.paramNames.map((n) => ({
+            name: n,
+            display: "/* not an export */",
+            projected: false
+          })),
+          paramEvidence: "none",
+          returnEvidence: "none",
+          skipped: "not-an-export"
+        });
+      }
+      continue;
+    }
+    const eff = effectiveInterface2(source, fn.name, {
+      loadModule,
+      fromFile: filePath,
+      autoBind: true
+    });
+    if (eff?.source === "handwritten") {
+      entries.push({
+        fn: fn.name,
+        params: eff.params.map((p) => ({
+          name: p.param,
+          constraint: p.constraint,
+          display: formatConstraint3(p.constraint),
+          projected: true
+        })),
+        ...eff.returns ? {
+          returns: {
+            constraint: eff.returns.constraint,
+            display: formatConstraint3(eff.returns.constraint),
+            projected: true
+          }
+        } : {},
+        paramEvidence: "none",
+        returnEvidence: "none",
+        skipped: "handwritten"
+      });
+      continue;
+    }
+    const { paramCases, returnCases, paramEvidence, rawReturnEvidence } = caseEvidence(fn);
+    const bodyByParam = bodyMap.get(fn.name);
+    const params = projectDraftParams(fn, paramCases, bodyByParam, fn.formals);
+    const ret = projectDraftReturn(fn, returnCases, source, rawReturnEvidence, loadModule, filePath);
+    const { evidence: returnEvidence, ...returns } = ret;
+    let evidence = paramEvidence;
+    if (evidence === "none") {
+      const anyBody = params.some((p) => p.bodyAccesses && p.bodyAccesses.length > 0);
+      if (anyBody) evidence = "body";
+    }
+    entries.push({
+      fn: fn.name,
+      params,
+      returns,
+      paramEvidence: evidence,
+      returnEvidence,
+      dsl: draftDsl({ params, returns })
+    });
+  }
+  const draftSource = formatDraftModule(filePath, entries, sidecarPath);
+  return { file: filePath, entries, draftSource, sidecarPath };
+}
+function formatDraftModule(filePath, entries, sidecarPath) {
+  const target = sidecarPath ?? sidecarPathOf3(filePath);
+  const draftName = sidecarDraftPath(filePath).split(/[/\\]/).pop() ?? "*.nudo.draft.js";
+  const draftable = entries.filter((e) => e.dsl !== void 0 && e.skipped === void 0);
+  const BUILDERS = ["fn", "number", "string", "boolean", "any", "shape", "array", "lit", "union"];
+  const used = /* @__PURE__ */ new Set(["fn"]);
+  for (const e of draftable) {
+    const blob = `${e.dsl ?? ""}
+${suggestedBodyDsl(e.fn, e.params) ?? ""}`;
+    for (const b of BUILDERS) {
+      if (new RegExp(`\\b${b}\\b`).test(blob)) used.add(b);
+    }
+  }
+  const importList = BUILDERS.filter((b) => used.has(b)).join(", ");
+  const lines = [
+    "// @nudo:draft",
+    `// Generated by \`nudo contract --draft\` from ${filePath}`,
+    `// This ${draftName} file is NOT loaded as a sidecar contract.`,
+    `// Review each export, then copy it into ${target} to accept.`,
+    "//",
+    "// Evidence: callsite/directive = observed args; body = fields the",
+    "// implementation reads (suggestion only \u2014 never a check obligation);",
+    "// symbolic = generalize; omitted params = no evidence.",
+    "// Handwritten contracts are never overwritten.",
+    "",
+    `import { ${importList} } from "@nudojs/core";`,
+    ""
+  ];
+  if (draftable.length === 0) {
+    lines.push("// (no draftable exports \u2014 handwritten / non-export / empty)");
+    lines.push("");
+  }
+  for (const e of draftable) {
+    lines.push(`// ${e.fn} \u2014 param: ${e.paramEvidence}, return: ${e.returnEvidence}`);
+    for (const p of e.params) {
+      if (!p.projected) {
+        lines.push(`//   ${p.name}: ${p.display}`);
+      } else if (p.display.includes("/* observed") || p.display.includes("/* body also reads")) {
+        lines.push(`//   ${p.name}: ${p.display}`);
+      }
+    }
+    const suggested = suggestedBodyDsl(e.fn, e.params);
+    if (suggested) lines.push(suggested);
+    if (e.returns && !e.returns.projected) {
+      lines.push(`//   returns: ${e.returns.display}`);
+    } else if (e.returns?.display.includes("/* observed")) {
+      lines.push(`//   returns: ${e.returns.display}`);
+    } else if (e.returnEvidence === "symbolic") {
+      lines.push(`//   returns: ${e.returns?.display ?? ""} (symbolic)`);
+    }
+    lines.push(`export const ${draftExportName(e.fn)} = ${e.dsl};`);
+    if (e.fn.includes(".")) {
+      lines.push(`//   sidecar key may also be written as \`${e.fn}\` / nested { ${e.fn.split(".")[1]}: \u2026 }`);
+    }
+    lines.push("");
+  }
+  const skipped = entries.filter((e) => e.skipped !== void 0);
+  if (skipped.length > 0) {
+    lines.push("// Skipped:");
+    for (const s of skipped) {
+      lines.push(`//   ${s.fn} (${s.skipped})`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function sidecarDraftPath(filePath) {
+  return sidecarPathOf3(filePath).replace(/\.nudo\.([cm]?[jt]s)$/, ".nudo.draft.$1");
+}
+function safeRealpath(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    try {
+      return join2(realpathSync(dirname4(p)), basename2(p));
+    } catch {
+      return p;
+    }
+  }
+}
+function isDraftableEntry(entries) {
+  return entries.some((e) => e.dsl !== void 0 && e.skipped === void 0);
+}
+function writeInterfaceDraft(filePath, draftSource, opts = {}) {
+  const draftPath = sidecarDraftPath(filePath);
+  const formalPath = sidecarPathOf3(filePath);
+  if (draftPath === formalPath) {
+    throw new Error(
+      `draft write refused: draft path equals formal sidecar (${formalPath}); never overwrite handwritten contracts`
+    );
+  }
+  if (/[/\\]node_modules[/\\]/.test(draftPath) || /[/\\]node_modules[/\\]/.test(filePath)) {
+    throw new Error(`draft write refused: path is inside node_modules (${draftPath})`);
+  }
+  if (opts.projectDir) {
+    const rootReal = safeRealpath(opts.projectDir);
+    const draftReal = safeRealpath(draftPath);
+    const rel = relative3(rootReal, draftReal);
+    if (rel.startsWith("..") || isAbsolute2(rel)) {
+      throw new Error(`draft write refused: outside project root ${opts.projectDir}`);
+    }
+  }
+  const draftable = opts.draftable !== void 0 ? opts.draftable : opts.entries !== void 0 ? isDraftableEntry(opts.entries) : /export\s+const\s+[\p{ID_Start}$_][\p{ID_Continue}$]*\s*=/u.test(draftSource);
+  const prev = existsSync4(draftPath) ? readFileSync4(draftPath, "utf-8") : void 0;
+  const changed = prev !== draftSource;
+  const written = !opts.dryRun && changed && draftable;
+  if (written) {
+    writeFileSync3(draftPath, draftSource, "utf-8");
+  }
+  return {
+    draftPath,
+    written,
+    changed,
+    draftable,
+    draftSource
+  };
+}
+function formatDraftSummary(sourceRel, draftRel, result, write) {
+  const lines = [sourceRel];
+  for (const e of result.entries) {
+    if (e.skipped === "handwritten") {
+      lines.push(`  ${e.fn}  [handwritten]  skipped (draft never overwrites)`);
+    } else if (e.skipped === "not-an-export") {
+      lines.push(`  ${e.fn}  [not-an-export]  skipped`);
+    } else if (e.dsl) {
+      lines.push(`  ${e.fn}  [draft ${e.paramEvidence}/${e.returnEvidence}]  ${e.dsl}`);
+    }
+  }
+  if (write) {
+    if (write.changed && write.draftable) {
+      lines.push(
+        write.written ? `Draft written \u2192 ${draftRel}` : `[dry-run] would write \u2192 ${draftRel}`
+      );
+    } else if (write.changed && !write.draftable) {
+      if (result.entries.length > 0) {
+        const skipped = result.entries.filter((e) => e.skipped !== void 0).length;
+        lines.push(
+          skipped > 0 ? `Draft not written (${skipped} skipped, no writeable exports); nothing written \u2192 ${draftRel}` : `Draft not written (no writeable exports); nothing written \u2192 ${draftRel}`
+        );
+      } else {
+        lines.push(`Draft empty (no draftable exports); nothing written \u2192 ${draftRel}`);
+      }
+    } else {
+      lines.push(`${draftRel}: draft unchanged`);
+    }
+    lines.push(`  review, then copy accepted exports into ${sidecarPathOf3(result.file)}`);
+  } else {
+    lines.push("");
+    lines.push(result.draftSource.trimEnd());
+  }
+  return lines;
+}
+
+// src/interface-derivation-derive.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import { basename as basename3, dirname as dirname5, relative as relative4, resolve as resolve3 } from "path";
+import { parse as parse2 } from "@nudojs/parser";
+import {
+  constraintToEntryAbs,
+  effectiveInterface as effectiveInterface3,
+  interfaceDiagCount as interfaceDiagCount3,
+  isNodeModulesPath as isNodeModulesPath2,
+  runTranspiled,
+  callTranspiledExportFull,
+  setBCallCollector,
+  $new,
+  $invoke,
+  sidecarPathOf as sidecarPathOf4,
+  takeInterfaceDiagsSince as takeInterfaceDiagsSince3,
+  unknown as unknownAbs
+} from "@nudojs/core";
+import {
+  beginDerivationSession,
+  endDerivationSession,
+  listTopFunctions,
+  tagDerivationRoot
+} from "@nudojs/core/internal";
+
+// src/interface-derivation-project.ts
+import { formatConstraint as formatConstraint4, joinThenProject as joinThenProject3 } from "@nudojs/core";
+import { derivationChain, getDerivation, projectDerivationDsl } from "@nudojs/core/internal";
+function projectParamSlot(absList, paramName) {
+  if (absList.length === 0) return void 0;
+  const constraint = joinThenProject3(absList);
+  if (constraint === void 0) return void 0;
+  if (absList.length === 1) {
+    const node = getDerivation(absList[0]);
+    if (node) {
+      const proj = projectDerivationDsl(node, paramName);
+      if (proj) {
+        const chain = derivationChain(node);
+        const root = chain[chain.length - 1];
+        const shiftCount = chain.filter((n) => n.kind === "shift").length;
+        return {
+          constraint,
+          dsl: proj.expr,
+          prelude: proj.prelude,
+          imports: proj.imports,
+          compositional: true,
+          ...root?.kind === "root" ? { rootNodeId: root.id } : {},
+          shiftCount
+        };
+      }
+    }
+  }
+  if (absList.length > 1) {
+    const nodes = absList.map((a) => getDerivation(a));
+    const projs = nodes.map((n) => n ? projectDerivationDsl(n, paramName) : void 0);
+    const roots = nodes.map((n) => {
+      if (!n) return void 0;
+      const chain = derivationChain(n);
+      return chain[chain.length - 1];
+    });
+    const root0 = roots[0];
+    const sameRoot = root0 !== void 0 && root0.kind === "root" && roots.every((r) => r !== void 0 && r.id === root0.id && r.kind === "root");
+    if (sameRoot && projs.every((p) => p !== void 0)) {
+      const exprs = [...new Set(projs.map((p) => p.expr))];
+      const prelude = [];
+      const imports = [];
+      for (const p of projs) {
+        for (const line of p.prelude) if (!prelude.includes(line)) prelude.push(line);
+        for (const imp of p.imports) {
+          if (!imports.some((i) => i.name === imp.name && i.from === imp.from)) {
+            imports.push(imp);
+          }
+        }
+      }
+      const dsl = exprs.length === 1 ? exprs[0] : `union(${exprs.join(", ")})`;
+      const shiftCounts = nodes.map(
+        (n) => derivationChain(n).filter((x) => x.kind === "shift").length
+      );
+      return {
+        constraint,
+        dsl,
+        prelude,
+        imports,
+        compositional: true,
+        rootNodeId: root0.id,
+        shiftCount: Math.max(...shiftCounts)
+      };
+    }
+  }
+  return {
+    constraint,
+    dsl: formatConstraint4(constraint),
+    prelude: [],
+    imports: [],
+    compositional: false
+  };
+}
+function projectReturnSlot(retAbs, params, paramNames) {
+  if (retAbs.length === 0) return void 0;
+  const constraint = joinThenProject3(retAbs);
+  if (constraint === void 0) return void 0;
+  if (retAbs.length === 1) {
+    const node = getDerivation(retAbs[0]);
+    if (node && !derivationChain(node).some((n) => n.kind === "join" || n.kind === "opaque")) {
+      const rel = projectReturnRelativeToParams(node, params, paramNames);
+      if (rel) {
+        return {
+          constraint,
+          dsl: rel.dsl,
+          prelude: rel.prelude,
+          imports: rel.imports,
+          compositional: true
+        };
+      }
+      const proj = projectDerivationDsl(node, paramNames[0] ?? "ret");
+      if (proj) {
+        return {
+          constraint,
+          dsl: proj.expr,
+          prelude: proj.prelude,
+          imports: proj.imports,
+          compositional: true
+        };
+      }
+    }
+  }
+  return {
+    constraint,
+    dsl: formatConstraint4(constraint),
+    prelude: [],
+    imports: [],
+    compositional: false
+  };
+}
+function projectReturnRelativeToParams(node, params, paramNames) {
+  const chain = derivationChain(node);
+  const root = chain[chain.length - 1];
+  if (!root || root.kind !== "root") return void 0;
+  const shifts = [];
+  for (let j = chain.length - 2; j >= 0; j--) {
+    const n = chain[j];
+    if (n.kind !== "shift" || n.offset === void 0) return void 0;
+    shifts.push(n.offset);
+  }
+  for (let i = 0; i < params.length; i++) {
+    const p = params[i];
+    if (p.rootNodeId === void 0 || p.rootNodeId !== root.id) continue;
+    const paramShiftCount = p.shiftCount ?? 0;
+    if (shifts.length < paramShiftCount) continue;
+    const tail = shifts.slice(paramShiftCount);
+    if (tail.length === 0) {
+      return { dsl: p.dsl, prelude: [], imports: [] };
+    }
+    let expr = p.name || paramNames[i] || "x";
+    for (const off of tail) expr = `${expr}.shift(${off})`;
+    return { dsl: expr, prelude: [], imports: [] };
+  }
+  return void 0;
+}
+
+// src/interface-derivation-derive.ts
+function extractFnConstraintSources(sidecarSrc, fnName) {
+  const out = { params: {} };
+  let ast;
+  try {
+    ast = parse2(sidecarSrc);
+  } catch {
+    return out;
+  }
+  const imports = /* @__PURE__ */ new Map();
+  const locals = /* @__PURE__ */ new Map();
+  const srcOf = (node) => {
+    const n = node;
+    if (!n?.type) return void 0;
+    if (n.type === "Identifier" && n.name) {
+      const imp = imports.get(n.name);
+      if (imp) {
+        return { expr: imp.imported, importFrom: imp.from, importName: imp.imported };
+      }
+      const local = locals.get(n.name);
+      if (local !== void 0) return { expr: local };
+      return { expr: n.name };
+    }
+    if (n.start != null && n.end != null) {
+      return { expr: sidecarSrc.slice(n.start, n.end) };
+    }
+    return void 0;
+  };
+  for (const stmt of ast.program.body) {
+    if (stmt.type === "ImportDeclaration") {
+      const from = stmt.source.value;
+      for (const s of stmt.specifiers) {
+        if (s.type === "ImportSpecifier") {
+          const imported = s.imported.type === "Identifier" ? s.imported.name : String(s.imported);
+          imports.set(s.local.name, { from, imported });
+        }
+      }
+      continue;
+    }
+    if (stmt.type !== "ExportNamedDeclaration" || stmt.source) continue;
+    const d = stmt.declaration;
+    if (!d || d.type !== "VariableDeclaration") continue;
+    for (const decl of d.declarations) {
+      if (decl.id.type !== "Identifier") continue;
+      const name = decl.id.name;
+      const init = decl.init;
+      if (!init) continue;
+      const text = init.start != null && init.end != null ? sidecarSrc.slice(init.start, init.end) : name;
+      if (init.type !== "CallExpression") {
+        locals.set(name, text);
+        continue;
+      }
+      const calleeName = init.callee.type === "Identifier" ? init.callee.name : void 0;
+      locals.set(name, text);
+      if (calleeName !== "fn" || name !== fnName) continue;
+      const paramsNode = init.arguments[0];
+      if (paramsNode?.type === "ObjectExpression") {
+        for (const prop of paramsNode.properties) {
+          if (prop.type !== "ObjectProperty") continue;
+          const key = prop.key.type === "Identifier" ? prop.key.name : prop.key.type === "StringLiteral" ? prop.key.value : void 0;
+          if (!key) continue;
+          const expr = srcOf(prop.value);
+          if (expr) out.params[key] = expr;
+        }
+      }
+      const retNode = init.arguments[1];
+      if (retNode) {
+        const expr = srcOf(retNode);
+        if (expr) out.returns = expr;
+      }
+    }
+  }
+  return out;
+}
+function functionParamNames(source, fnName) {
+  try {
+    const ast = parse2(source);
+    if (fnName.includes(".")) {
+      const [clsName, methodName] = fnName.split(".", 2);
+      for (const stmt of ast.program.body) {
+        let decl = stmt.type === "ExportNamedDeclaration" ? stmt.declaration : stmt;
+        if (!decl) continue;
+        if (decl.type === "ExportDefaultDeclaration") {
+          decl = decl.declaration;
+        }
+        const c = decl;
+        if (c.type !== "ClassDeclaration" || c.id?.name !== clsName) continue;
+        for (const m of c.body?.body ?? []) {
+          const mem = m;
+          const isMethod = mem.type === "MethodDefinition" || mem.type === "ClassMethod" || mem.type === "ClassPrivateMethod";
+          if (!isMethod) continue;
+          if (mem.kind && mem.kind !== "method") continue;
+          const keyName = mem.key?.type === "Identifier" ? mem.key.name : void 0;
+          if (keyName === methodName) {
+            return (mem.params ?? []).map(
+              paramNameOf
+            );
+          }
+        }
+      }
+      return [];
+    }
+    for (const stmt of ast.program.body) {
+      const d = stmt.type === "ExportNamedDeclaration" ? stmt.declaration ?? void 0 : stmt;
+      if (!d) continue;
+      if (d.type === "FunctionDeclaration" && d.id?.name === fnName) {
+        return d.params.map(paramNameOf);
+      }
+      if (d.type === "VariableDeclaration") {
+        for (const decl of d.declarations) {
+          if (decl.id.type === "Identifier" && decl.id.name === fnName && decl.init && (decl.init.type === "ArrowFunctionExpression" || decl.init.type === "FunctionExpression")) {
+            return decl.init.params.map(paramNameOf);
+          }
+        }
+      }
+    }
+  } catch {
+  }
+  return [];
+}
+function paramNameOf(p) {
+  if (p.type === "Identifier" && p.name) return p.name;
+  if (p.type === "AssignmentPattern" && p.left?.type === "Identifier" && p.left.name) {
+    return p.left.name;
+  }
+  return "_";
+}
+function topLevelFnNames(source) {
+  try {
+    return listTopFunctions(source);
+  } catch {
+    return [];
+  }
+}
+function importLocalMap(source, fromFile) {
+  const out = /* @__PURE__ */ new Map();
+  try {
+    const ast = parse2(source);
+    const base = dirname5(resolve3(fromFile));
+    for (const stmt of ast.program.body) {
+      if (stmt.type !== "ImportDeclaration") continue;
+      const spec = stmt.source.value;
+      if (!spec.startsWith(".") && !spec.startsWith("/")) continue;
+      const raw = resolve3(base, spec);
+      let modulePath = null;
+      for (const cand of [raw, `${raw}.js`, `${raw}.ts`, `${raw}.mjs`]) {
+        if (existsSync5(cand)) {
+          modulePath = cand;
+          break;
+        }
+      }
+      if (!modulePath) continue;
+      for (const s of stmt.specifiers) {
+        if (s.type === "ImportSpecifier") {
+          const imported = s.imported.type === "Identifier" ? s.imported.name : String(s.imported);
+          out.set(s.local.name, { modulePath, exportName: imported });
+        }
+      }
+    }
+  } catch {
+  }
+  return out;
+}
+function deriveFromRoot(filePath, opts = {}) {
+  const abs = resolve3(filePath);
+  const source = readFileSync5(abs, "utf-8");
+  const since = interfaceDiagCount3();
+  const autoBind = opts.autoBind ?? interfaceConfig(findProjectConfig(dirname5(abs))?.config).autoBind;
+  const loadModule = opts.loadModule ?? defaultLoadModule;
+  const sidecarPath = sidecarPathOf4(abs);
+  const sidecarSrc = existsSync5(sidecarPath) && !isNodeModulesPath2(sidecarPath) ? readFileSync5(sidecarPath, "utf-8") : "";
+  const fnNames = topLevelFnNames(source);
+  const roots = [];
+  const plans = [];
+  for (const fn of fnNames) {
+    const eff = effectiveInterface3(source, fn, { loadModule, fromFile: abs, autoBind });
+    if (!eff || eff.source !== "handwritten") continue;
+    roots.push(fn);
+    const sources = sidecarSrc ? extractFnConstraintSources(sidecarSrc, fn) : { params: {} };
+    const srcParams = functionParamNames(source, fn);
+    const planParams = srcParams.map((pname) => {
+      const hit = eff.params.find((p) => p.param === pname);
+      if (hit) {
+        const src = sources.params[pname];
+        return {
+          name: pname,
+          constraint: hit.constraint,
+          ...src ? { src } : {}
+        };
+      }
+      return {
+        name: pname,
+        constraint: { __nudoConstraint: true, preds: [] }
+      };
+    });
+    plans.push({ fnName: fn, params: planParams });
+  }
+  if (plans.length === 0) {
+    takeInterfaceDiagsSince3(since);
+    return { roots: [], derived: [], hasRoot: false };
+  }
+  let modules = {};
+  try {
+    modules = evalAbsModuleGraph(source, abs, { loadModule }).modules;
+  } catch {
+    modules = {};
+  }
+  const importLocals = importLocalMap(source, abs);
+  const wanted = opts.fnNames && opts.fnNames.length > 0 ? new Set(opts.fnNames) : void 0;
+  const derived = [];
+  for (const plan of plans) {
+    const relRoot = relative4(process.cwd(), abs);
+    const label = `${relRoot === "" || relRoot.startsWith("..") ? basename3(abs) : relRoot}:${plan.fnName}`;
+    const rows = deriveOneRoot(plan, source, abs, modules, importLocals, label);
+    for (const row of rows) {
+      if (wanted && !wanted.has(row.fn)) continue;
+      derived.push(row);
+    }
+  }
+  takeInterfaceDiagsSince3(since);
+  return { roots, derived, hasRoot: true };
+}
+function deriveOneRoot(plan, source, file, modules, importLocals, label) {
+  beginDerivationSession();
+  const entryArgs = [];
+  try {
+    for (const p of plan.params) {
+      const entry = constraintToEntryAbs(p.constraint, p.name);
+      if (p.src) {
+        tagDerivationRoot(entry, {
+          expr: p.src.expr,
+          ...p.src.importFrom !== void 0 ? { importFrom: p.src.importFrom } : {},
+          ...p.src.importName !== void 0 ? { importName: p.src.importName } : {}
+        });
+      } else if (p.constraint.preds.length === 0 && !p.constraint.prim) {
+      }
+      entryArgs.push(entry);
+    }
+    const calls = [];
+    const bCalls = [];
+    const prevCall = setBCallCollector((r) => bCalls.push(r));
+    try {
+      {
+        const run = runTranspiled(source, { mode: "analyze", modules });
+        if (plan.fnName.includes(".")) {
+          const [clsName, methodName] = plan.fnName.split(".", 2);
+          const clsAbs = run[clsName ?? ""];
+          if (clsAbs && typeof clsAbs === "object" && "shape" in clsAbs) {
+            const inst = $new(clsAbs, []);
+            $invoke(inst, methodName ?? "", entryArgs);
+          }
+        } else if (plan.fnName in run) {
+          callTranspiledExportFull(run, plan.fnName, entryArgs);
+        }
+        calls.push(
+          ...bCalls.map((r) => ({
+            fnName: r.fnName,
+            args: r.args,
+            result: r.result,
+            callLoc: r.callLoc,
+            threw: r.threw
+          }))
+        );
+      }
+    } catch {
+      return [];
+    } finally {
+      setBCallCollector(prevCall);
+    }
+    const byCallee = /* @__PURE__ */ new Map();
+    for (const call of calls) {
+      const imp = importLocals.get(call.fnName);
+      let targetFile;
+      let targetExport = call.fnName;
+      if (imp) {
+        targetFile = imp.modulePath;
+        targetExport = imp.exportName;
+      } else {
+        targetFile = file;
+      }
+      if (isNodeModulesPath2(targetFile)) continue;
+      if (!existsSync5(targetFile)) continue;
+      const key = `${targetFile}::${targetExport}`;
+      let agg = byCallee.get(key);
+      if (!agg) {
+        agg = { targetFile, targetExport, argAbs: [], resultAbs: [] };
+        byCallee.set(key, agg);
+      }
+      agg.argAbs.push(call.args);
+      agg.resultAbs.push(call.threw ? unknownAbs : call.result);
+    }
+    const out = [];
+    for (const agg of byCallee.values()) {
+      let targetSource;
+      try {
+        targetSource = readFileSync5(agg.targetFile, "utf-8");
+      } catch {
+        continue;
+      }
+      const paramNames = functionParamNames(targetSource, agg.targetExport);
+      if (paramNames.length === 0 && agg.argAbs.every((a) => a.length === 0)) continue;
+      const width = Math.max(
+        paramNames.length,
+        ...agg.argAbs.map((a) => a.length),
+        0
+      );
+      const params = [];
+      let allCompositional = true;
+      let sawEvidence = false;
+      for (let i = 0; i < width; i++) {
+        const name = paramNames[i] ?? `_${i}`;
+        const absList = [];
+        for (const args of agg.argAbs) {
+          const a = args[i];
+          if (a) absList.push(a);
+        }
+        const slot = projectParamSlot(absList, name);
+        if (!slot) {
+          allCompositional = false;
+          continue;
+        }
+        sawEvidence = true;
+        if (!slot.compositional) allCompositional = false;
+        params.push({
+          name,
+          constraint: slot.constraint,
+          dsl: slot.dsl,
+          prelude: slot.prelude,
+          imports: slot.imports,
+          ...slot.rootNodeId !== void 0 ? { rootNodeId: slot.rootNodeId } : {},
+          ...slot.shiftCount !== void 0 ? { shiftCount: slot.shiftCount } : {}
+        });
+      }
+      const retAbs = agg.resultAbs.filter(
+        (a) => a.conf === "exact" || a.conf === "path"
+      );
+      const retSlot = projectReturnSlot(retAbs, params, paramNames);
+      if (retSlot && !retSlot.compositional) allCompositional = false;
+      if (retSlot) sawEvidence = true;
+      if (!sawEvidence) {
+        out.push({
+          file: agg.targetFile,
+          fn: agg.targetExport,
+          paramNames,
+          params: [],
+          derivedFrom: label,
+          compositional: false,
+          underivable: true
+        });
+        continue;
+      }
+      out.push({
+        file: agg.targetFile,
+        fn: agg.targetExport,
+        paramNames,
+        params,
+        ...retSlot ? {
+          returns: {
+            constraint: retSlot.constraint,
+            dsl: retSlot.dsl,
+            prelude: retSlot.prelude,
+            imports: retSlot.imports
+          }
+        } : {},
+        derivedFrom: label,
+        compositional: allCompositional && params.length > 0
+      });
+    }
+    return out;
+  } finally {
+    endDerivationSession();
+  }
+}
+
+// src/interface-derivation-rewrite.ts
+import { relative as relative5, resolve as resolve4 } from "path";
+function resolveRelImport(fromSpec, fromDir, targetDir) {
+  const abs = resolve4(fromDir, fromSpec);
+  let rel = relative5(targetDir, abs);
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  return rel.split("\\").join("/");
+}
+var NameAllocator = class {
+  taken;
+  constructor(initial) {
+    this.taken = new Set(initial ?? []);
+  }
+  claim(preferred) {
+    if (!this.taken.has(preferred)) {
+      this.taken.add(preferred);
+      return preferred;
+    }
+    let i = 2;
+    while (this.taken.has(`${preferred}_${i}`)) i++;
+    const name = `${preferred}_${i}`;
+    this.taken.add(name);
+    return name;
+  }
+};
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function rewriteIdents(src, map) {
+  if (map.size === 0) return src;
+  let out = src;
+  const keys = [...map.keys()].sort((a, b) => b.length - a.length);
+  for (const k of keys) {
+    const v = map.get(k);
+    if (k === v) continue;
+    out = out.replace(new RegExp(`(?<![\\w$.])${escapeRegExp(k)}(?![\\w$])`, "g"), v);
+  }
+  return out;
+}
+function preludeLocalName(line) {
+  const m = /^const\s+([A-Za-z_$][\w$]*)\s*=/.exec(line.trim());
+  return m?.[1];
+}
+function formatDerivedSection(row, opts) {
+  if (row.underivable || row.params.length === 0) return void 0;
+  const importMap = /* @__PURE__ */ new Map();
+  const preludes = [];
+  const paramDsls = [];
+  for (const p of row.params) {
+    for (const imp of p.imports) {
+      const rel = resolveRelImport(imp.from, opts.rootSidecarDir, opts.targetSidecarDir);
+      const prev = importMap.get(imp.name);
+      if (prev !== void 0 && prev !== rel) return void 0;
+      importMap.set(imp.name, rel);
+    }
+    for (const line of p.prelude) {
+      if (!preludes.includes(line)) preludes.push(line);
+    }
+    paramDsls.push(p.dsl);
+  }
+  let retDsl = "";
+  if (row.returns) {
+    for (const imp of row.returns.imports) {
+      const rel = resolveRelImport(imp.from, opts.rootSidecarDir, opts.targetSidecarDir);
+      const prev = importMap.get(imp.name);
+      if (prev !== void 0 && prev !== rel) return void 0;
+      importMap.set(imp.name, rel);
+    }
+    for (const line of row.returns.prelude) {
+      if (!preludes.includes(line)) preludes.push(line);
+    }
+    retDsl = `, ${row.returns.dsl}`;
+  }
+  const namer = new NameAllocator(opts.takenNames);
+  namer.claim(row.fn);
+  const renames = /* @__PURE__ */ new Map();
+  const importLocals = [];
+  for (const [name, from] of [...importMap.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const local = namer.claim(name);
+    if (local !== name) renames.set(name, local);
+    importLocals.push({ original: name, local, from });
+  }
+  const preludeClaimed = /* @__PURE__ */ new Set();
+  const renamedPreludes = [];
+  for (const line of preludes) {
+    const local = preludeLocalName(line);
+    if (local !== void 0 && !preludeClaimed.has(local)) {
+      preludeClaimed.add(local);
+      if (!renames.has(local)) {
+        const next = namer.claim(local);
+        if (next !== local) renames.set(local, next);
+      }
+    }
+    renamedPreludes.push(rewriteIdents(line, renames));
+  }
+  const paramParts = row.params.map((p, i) => {
+    const dsl = rewriteIdents(paramDsls[i], renames);
+    const name = rewriteIdents(p.name, renames);
+    return dsl === name ? name : `${name}: ${dsl}`;
+  });
+  const retPart = retDsl === "" ? "" : `, ${rewriteIdents(row.returns.dsl, renames)}`;
+  const importLineTexts = importLocals.map(({ original, local, from }) => {
+    const spec = original === local ? local : `${original} as ${local}`;
+    return `import { ${spec} } from ${JSON.stringify(from)};`;
+  }).sort((a, b) => a.localeCompare(b));
+  const lines = [
+    ...importLineTexts,
+    ...importLineTexts.length > 0 && renamedPreludes.length > 0 ? [""] : [],
+    ...renamedPreludes,
+    `export const ${row.fn} = fn({ ${paramParts.join(", ")} }${retPart});`
+  ];
+  const usedNames = /* @__PURE__ */ new Set();
+  for (const { local } of importLocals) usedNames.add(local);
+  for (const line of renamedPreludes) {
+    const n = preludeLocalName(line);
+    if (n) usedNames.add(n);
+  }
+  usedNames.add(row.fn);
+  return { text: lines.join("\n"), usedNames: [...usedNames] };
+}
+
+// src/interface-derivation-emit.ts
+import { existsSync as existsSync6, readFileSync as readFileSync6, renameSync as renameSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync4 } from "fs";
+import { basename as basename4, dirname as dirname6, relative as relative6, resolve as resolve5 } from "path";
+import {
+  execNudoModule as execNudoModule2,
+  isNodeModulesPath as isNodeModulesPath3,
+  isNudoConstraint as isNudoConstraint2,
+  parseSource as parseSource2,
+  refineDiagCount as refineDiagCount3,
+  sidecarPathOf as sidecarPathOf5,
+  takeRefineDiagsSince as takeRefineDiagsSince3
+} from "@nudojs/core";
+var DERIVED_HEADER = "// @generated by nudo \u2014 do not edit; regenerate with `nudo contract --emit`";
+function collectTopLevelNames(src) {
+  const names = /* @__PURE__ */ new Set();
+  if (src.trim() === "") return names;
+  let ast;
+  try {
+    ast = parseSource2(src);
+  } catch {
+    return names;
+  }
+  const addDecl = (d) => {
+    if (d.type === "VariableDeclaration") {
+      for (const decl of d.declarations) {
+        if (decl.id.type === "Identifier") names.add(decl.id.name);
+      }
+    } else if (d.type === "FunctionDeclaration" || d.type === "ClassDeclaration") {
+      if (d.id) names.add(d.id.name);
+    }
+  };
+  for (const stmt of ast.program.body) {
+    if (stmt.type === "ImportDeclaration") {
+      for (const s of stmt.specifiers) names.add(s.local.name);
+      continue;
+    }
+    if (stmt.type === "ExportNamedDeclaration") {
+      if (stmt.declaration) addDecl(stmt.declaration);
+      for (const spec of stmt.specifiers) {
+        names.add(
+          spec.exported.type === "Identifier" ? spec.exported.name : spec.exported.value
+        );
+      }
+      continue;
+    }
+    addDecl(stmt);
+  }
+  return names;
+}
+function sidecarAssembles(text, fromFile, loadModule) {
+  try {
+    parseSource2(text);
+    execNudoModule2(text, { loadModule, fromFile });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function emitDerivedFromRoot(rootFile, opts) {
+  const abs = resolve5(rootFile);
+  const derive = deriveFromRoot(abs, {
+    ...opts.loadModule ? { loadModule: opts.loadModule } : {},
+    ...opts.autoBind !== void 0 ? { autoBind: opts.autoBind } : {},
+    ...opts.fnNames && opts.fnNames.length > 0 ? { fnNames: opts.fnNames } : {}
+  });
+  if (!derive.hasRoot) {
+    return { sidecars: [], hasRoot: false, roots: [], entryOnly: true };
+  }
+  const proj = findProjectConfig(dirname6(abs));
+  const allow = interfaceConfig(proj?.config).emit;
+  const projectDir = proj?.projectDir;
+  const rootSidecarDir = dirname6(sidecarPathOf5(abs));
+  const wanted = opts.fnNames && opts.fnNames.length > 0 ? new Set(opts.fnNames) : void 0;
+  const result = {
+    sidecars: [],
+    hasRoot: true,
+    roots: derive.roots
+  };
+  const bySidecar = /* @__PURE__ */ new Map();
+  for (const row of derive.derived) {
+    if (wanted && !wanted.has(row.fn)) continue;
+    if (!matchesEmitAllowlist(row.file, projectDir, allow)) continue;
+    const sp = sidecarPathOf5(row.file);
+    if (isNodeModulesPath3(sp)) continue;
+    const list = bySidecar.get(sp) ?? [];
+    list.push(row);
+    bySidecar.set(sp, list);
+  }
+  for (const [sidecarPath, rows0] of bySidecar) {
+    const targetFile = rows0[0].file;
+    const targetSidecarDir = dirname6(sidecarPath);
+    const prevSrc = existsSync6(sidecarPath) ? readFileSync6(sidecarPath, "utf-8") : "";
+    const rows = opts.refreshExistingOnly ? rows0.filter((r) => findGeneratedSectionText(prevSrc, r.fn) !== void 0) : rows0;
+    if (rows.length === 0) continue;
+    const handwritten = handwrittenNames(prevSrc);
+    const loadModule = opts.loadModule ?? defaultLoadModule;
+    const batchFns = new Set(
+      rows.filter((r) => !r.underivable && !handwritten.has(r.fn)).map((r) => r.fn)
+    );
+    const baseForNames = opts.mode === "update" ? stripGeneratedFor(prevSrc, batchFns) : prevSrc;
+    const taken = collectTopLevelNames(baseForNames);
+    const accepted = [];
+    const issues = [];
+    const written = [];
+    let anySkip;
+    for (const row of rows) {
+      if (handwritten.has(row.fn)) {
+        issues.push({
+          code: "nudo:interface-name-clash",
+          severity: "error",
+          message: `sidecar already has a handwritten binding '${row.fn}' (${relative6(process.cwd(), sidecarPath) || sidecarPath}); handwritten wins \u2014 skipping emit`
+        });
+        anySkip = "name-clash";
+        continue;
+      }
+      if (row.underivable) {
+        issues.push({
+          code: "nudo:interface-underivable",
+          severity: "info",
+          message: `${row.fn}: contract underivable from ${row.derivedFrom} (opaque / truncated / no evidence)`
+        });
+        anySkip = "underivable";
+        continue;
+      }
+      const prevSection = findGeneratedSectionText(prevSrc, row.fn);
+      const body = formatDerivedSection(row, {
+        rootSidecarDir,
+        targetSidecarDir,
+        takenNames: taken
+      });
+      if (!body) {
+        anySkip = "not-projectable";
+        if (prevSection !== void 0) {
+          for (const n of collectTopLevelNames(prevSection)) taken.add(n);
+        }
+        continue;
+      }
+      for (const n of body.usedNames) taken.add(n);
+      const srcRel = relative6(targetSidecarDir, targetFile) || basename4(targetFile);
+      const section = [
+        DERIVED_HEADER,
+        `// source: ${srcRel}:${row.fn}`,
+        `// derived-from: ${row.derivedFrom}`,
+        body.text,
+        ""
+      ].join("\n");
+      if (!derivedRoundTrips(section, row.fn, sidecarPath, loadModule)) {
+        anySkip = "not-projectable";
+        if (prevSection !== void 0) {
+          for (const n of collectTopLevelNames(prevSection)) taken.add(n);
+        }
+        continue;
+      }
+      if (opts.mode === "add" && prevSection !== void 0) {
+        anySkip = "no-change";
+        for (const n of collectTopLevelNames(prevSection)) taken.add(n);
+        continue;
+      }
+      const norm = normalizeSectionText(section);
+      if (prevSection !== void 0 && normalizeSectionText(prevSection) === norm) {
+        anySkip = "no-change";
+        accepted.push({ fn: row.fn, text: prevSection, prevText: prevSection });
+        for (const n of collectTopLevelNames(prevSection)) taken.add(n);
+        continue;
+      }
+      written.push(row.fn);
+      accepted.push({ fn: row.fn, text: section, ...prevSection !== void 0 ? { prevText: prevSection } : {} });
+    }
+    let finalContent;
+    if (accepted.length === 0) {
+      finalContent = prevSrc;
+    } else if (opts.mode === "add") {
+      finalContent = joinSectionTexts(prevSrc, accepted.map((a) => a.text));
+    } else {
+      const acceptedFns = new Set(accepted.map((a) => a.fn));
+      const stripped = stripGeneratedFor(prevSrc, acceptedFns);
+      const preserved = collectGeneratedSectionsRaw(prevSrc).filter(
+        (s) => !s.names.some((n) => acceptedFns.has(n))
+      );
+      finalContent = joinSectionTexts(stripped, [
+        ...preserved.map((s) => normalizeSectionText(s.text)),
+        ...accepted.map((a) => a.text)
+      ]);
+    }
+    if (finalContent.trim() !== "" && !sidecarAssembles(finalContent, sidecarPath, loadModule)) {
+      issues.push({
+        code: "nudo:interface-not-projectable",
+        severity: "error",
+        message: `assembled sidecar failed round-trip (${relative6(process.cwd(), sidecarPath) || sidecarPath}); refusing to write`
+      });
+      anySkip = "not-projectable";
+      result.sidecars.push({
+        file: targetFile,
+        sidecarPath,
+        fn: rows.map((r) => r.fn).join(","),
+        written: false,
+        changed: false,
+        ...anySkip ? { skipped: anySkip } : {},
+        issues
+      });
+      continue;
+    }
+    const changed = finalContent !== prevSrc;
+    const diff = changed ? unifiedDiff(prevSrc, finalContent, relative6(process.cwd(), sidecarPath) || sidecarPath) : void 0;
+    if (changed && !opts.dryRun) {
+      const tmp = `${sidecarPath}.tmp-${process.pid}-${Math.random().toString(16).slice(2, 10)}`;
+      try {
+        writeFileSync4(tmp, finalContent, "utf-8");
+        renameSync2(tmp, sidecarPath);
+      } catch (e) {
+        try {
+          if (existsSync6(tmp)) unlinkSync2(tmp);
+        } catch {
+        }
+        throw e;
+      }
+    }
+    result.sidecars.push({
+      file: targetFile,
+      sidecarPath,
+      fn: rows.map((r) => r.fn).join(","),
+      written: written.length > 0 && changed,
+      changed,
+      ...anySkip ? { skipped: anySkip } : {},
+      ...diff !== void 0 ? { diff } : {},
+      issues
+    });
+  }
+  return result;
+}
+function collectGeneratedSectionsRaw(src) {
+  if (src.trim() === "") return [];
+  let ast;
+  try {
+    ast = parseSource2(src);
+  } catch {
+    return [];
+  }
+  const stmts = ast.program.body;
+  const out = [];
+  for (const headerPos of findGeneratedHeaderOffsets(src)) {
+    for (let i = 0; i < stmts.length; i++) {
+      const stmt = stmts[i];
+      if (stmt.type !== "ExportNamedDeclaration" || stmt.source) continue;
+      if (stmt.start == null || stmt.end == null || stmt.start < headerPos) continue;
+      const d = stmt.declaration;
+      if (!d) continue;
+      const names = [];
+      if (d.type === "VariableDeclaration") {
+        for (const decl of d.declarations) {
+          if (decl.id.type === "Identifier") names.push(decl.id.name);
+        }
+      } else if (d.type === "FunctionDeclaration" || d.type === "ClassDeclaration") {
+        if (d.id) names.push(d.id.name);
+      }
+      if (names.length === 0) continue;
+      out.push({
+        names,
+        start: headerPos,
+        end: stmt.end,
+        text: src.slice(headerPos, stmt.end)
+      });
+      break;
+    }
+  }
+  return out;
+}
+function findGeneratedHeaderOffsets(src) {
+  const out = [];
+  let pos = 0;
+  for (const line of src.split("\n")) {
+    const t = line.trim();
+    if ((t.startsWith("//") || t.startsWith("/*") || t.startsWith("*")) && /@generated/.test(t)) {
+      out.push(pos);
+    }
+    pos += line.length + 1;
+  }
+  return out;
+}
+function generatedSectionNames(src) {
+  return new Set(collectGeneratedSectionsRaw(src).flatMap((s) => s.names));
+}
+function handwrittenNames(src) {
+  if (src.trim() === "") return /* @__PURE__ */ new Set();
+  let ast;
+  try {
+    ast = parseSource2(src);
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+  const names = /* @__PURE__ */ new Set();
+  const collect = (stmt) => {
+    if (stmt.type === "VariableDeclaration") {
+      for (const d of stmt.declarations) {
+        if (d.id.type === "Identifier") names.add(d.id.name);
+      }
+    } else if (stmt.type === "FunctionDeclaration" || stmt.type === "ClassDeclaration") {
+      if (stmt.id) names.add(stmt.id.name);
+    }
+  };
+  for (const stmt of ast.program.body) {
+    if (stmt.type === "ExportNamedDeclaration") {
+      if (stmt.declaration) collect(stmt.declaration);
+      if (!stmt.source) {
+        for (const spec of stmt.specifiers) {
+          names.add(
+            spec.exported.type === "Identifier" ? spec.exported.name : spec.exported.value
+          );
+        }
+      }
+    } else {
+      collect(stmt);
+    }
+  }
+  for (const n of generatedSectionNames(src)) names.delete(n);
+  return names;
+}
+function findGeneratedSectionText(src, fn) {
+  return collectGeneratedSectionsRaw(src).find((s) => s.names.includes(fn))?.text;
+}
+function stripGeneratedFor(src, fns) {
+  const sections = collectGeneratedSectionsRaw(src).filter(
+    (s) => s.names.some((n) => fns.has(n))
+  );
+  if (sections.length === 0) return src;
+  const sorted = [...sections].sort((a, b) => a.start - b.start);
+  let out = "";
+  let pos = 0;
+  for (const s of sorted) {
+    out += src.slice(pos, s.start);
+    pos = Math.max(pos, s.end);
+  }
+  out += src.slice(pos);
+  return out;
+}
+function normalizeSectionText(text) {
+  return text.replace(/\s*$/, "") + "\n";
+}
+function joinSectionTexts(base, sectionTexts) {
+  const normalized = sectionTexts.map(normalizeSectionText).filter((t) => t.trim() !== "");
+  const tailTrimmed = base.replace(/\s+$/, "");
+  if (normalized.length === 0) return tailTrimmed === "" ? "" : `${tailTrimmed}
+`;
+  const trimmed = tailTrimmed.replace(/^\s+/, "");
+  const lead = trimmed === "" ? "" : `${trimmed}
+
+`;
+  return lead + normalized.join("\n");
+}
+function derivedRoundTrips(text, fn, fromFile, loadModule) {
+  const since = refineDiagCount3();
+  try {
+    const exports = execNudoModule2(text, { loadModule, fromFile });
+    const v = exports[fn];
+    return isNudoConstraint2(v) && v.fn !== void 0;
+  } catch {
+    return false;
+  } finally {
+    takeRefineDiagsSince3(since);
+  }
+}
+
+// src/what-if.ts
+import { parse as parse3 } from "@nudojs/parser";
+function splitTopLevelUnion(expr) {
+  const members = [];
+  let start = 0;
+  let depth = 0;
+  for (let i = 0; i < expr.length; i++) {
+    const c = expr[i];
+    if (c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ")" || c === "]" || c === "}") depth--;
+    else if (c === "|" && depth === 0) {
+      members.push(expr.slice(start, i));
+      start = i + 1;
+    }
+  }
+  members.push(expr.slice(start));
+  return members.map((m) => m.trim()).filter(Boolean);
+}
+function typeExprToDirective(expr) {
+  const members = splitTopLevelUnion(expr);
+  if (members.length === 0) return "any()";
+  const mapped = members.map((m) => {
+    if (m.startsWith("T.")) return "any()";
+    if (m === "number" || m === "string" || m === "boolean") return `${m}()`;
+    if (m === "unknown" || m === "any") return "any()";
+    if (m === "null" || m === "undefined" || m === "true" || m === "false") return m;
+    if (/^-?\d+(\.\d+)?$/.test(m)) return m;
+    if (/^["']/.test(m)) return m;
+    if (/[([{]|=>/.test(m) && !m.startsWith("T.")) return m;
+    if (/^(number|string|boolean|any|array|shape|lit|union|fn)\s*\(/.test(m)) return m;
+    return "any()";
+  });
+  return mapped.length === 1 ? mapped[0] : `union(${mapped.join(", ")})`;
+}
+function declaredNames(stmt, out) {
+  if (stmt.type === "FunctionDeclaration" && stmt.id) out.add(stmt.id.name);
+  else if (stmt.type === "ClassDeclaration" && stmt.id) out.add(stmt.id.name);
+  else if (stmt.type === "VariableDeclaration") {
+    for (const decl of stmt.declarations) {
+      if (decl.id?.type === "Identifier") out.add(decl.id.name);
+    }
+  } else if (stmt.type === "ExportNamedDeclaration" && stmt.declaration) {
+    declaredNames(stmt.declaration, out);
+  }
+}
+function injectBindings(source, bindings) {
+  const applied = [];
+  const unapplied = [];
+  if (bindings.length === 0) return { source, applied, unapplied };
+  const ast = parse3(source);
+  const declLines = /* @__PURE__ */ new Map();
+  for (const stmt of ast.program.body) {
+    const names = /* @__PURE__ */ new Set();
+    declaredNames(stmt, names);
+    if (names.size === 0 || !stmt.loc) continue;
+    const anchorLine = stmt.leadingComments?.[0]?.loc?.start.line ?? stmt.loc.start.line;
+    for (const name of names) {
+      if (!declLines.has(name)) declLines.set(name, anchorLine);
+    }
+  }
+  const byLine = /* @__PURE__ */ new Map();
+  for (const binding of bindings) {
+    const line = declLines.get(binding.name);
+    if (line === void 0) {
+      unapplied.push(binding.name);
+      continue;
+    }
+    const group = byLine.get(line) ?? [];
+    group.push(binding);
+    byLine.set(line, group);
+    applied.push(binding.name);
+  }
+  const insertions = [];
+  for (const [line, group] of byLine) {
+    insertions.push({
+      index: line - 1,
+      text: `// @nudo:as ${typeExprToDirective(group[0].type)}`
+    });
+  }
+  insertions.sort((a, b) => b.index - a.index);
+  const lines = source.split("\n");
+  for (const ins of insertions) lines.splice(ins.index, 0, ins.text);
+  return { source: lines.join("\n"), applied, unapplied };
+}
+
+export {
+  collectLoadDepContents,
+  ANALYSIS_ABI,
+  sha256Hex,
+  relativizePath,
+  DiskCache,
+  checkCacheKey,
+  ifaceCacheKey,
+  extractNudoImportSpecs,
+  formatInterfaceSurfaceLine,
+  interfaceSurface,
+  emitInterface,
+  formatEmitSummary,
+  collectParamBodyAccesses,
+  draftInterface,
+  formatDraftModule,
+  sidecarDraftPath,
+  isDraftableEntry,
+  writeInterfaceDraft,
+  formatDraftSummary,
+  extractFnConstraintSources,
+  deriveFromRoot,
+  formatDerivedSection,
+  emitDerivedFromRoot,
+  typeExprToDirective,
+  injectBindings
+};