@nudojs/service 1.0.1 → 3.0.0

package/dist/index.js

@@ -1,17 +1,21 @@
 import {
+  DEFAULT_ANALYSIS_MODE,
+  analysisConfig,
   builtinProtoMember,
   builtinProtoMemberNames,
+  clearPathEnvCaches,
   describeAbsMember,
+  diskCacheRoot,
   findProjectConfig,
   interfaceConfig,
   loadEnvs,
   matchesEmitAllowlist,
   preloadPathEnvs
-} from "./chunk-2VHITMTM.js";
+} from "./chunk-ADFCZP72.js";
 
 // src/analyzer.ts
-import { readFileSync as readFileSync5, existsSync as existsSync4, statSync as statSync4, realpathSync } from "fs";
-import { resolve as resolve5, dirname as dirname6 } from "path";
+import { readFileSync as readFileSync5, existsSync as existsSync5, statSync as statSync5, realpathSync } from "fs";
+import { resolve as resolve6, dirname as dirname7 } from "path";
 import traverse from "@babel/traverse";
 import {
   createEnvironment as createEnvironment2,
@@ -34,6 +38,9 @@ import {
   strLit,
   boolLit,
   abs as makeAbsVal,
+  formalParamsFromNodes,
+  formalParamDisplayNames,
+  runWithEvalMissingSlot,
   stableAnalyzeKeySource as stableAnalyzeKeySource2,
   fnFingerprints
 } from "@nudojs/core";
@@ -383,9 +390,70 @@ function defaultLoadModule(spec, fromFile) {
   }
 }
 
+// src/env-path-deps.ts
+import { existsSync as existsSync2, statSync as statSync2 } from "fs";
+import { dirname as dirname2, resolve as resolve2, join as join2 } from "path";
+import { extractAllLoadSpecs } from "@nudojs/core";
+var envDependents = /* @__PURE__ */ new Map();
+function norm(p) {
+  return p.replace(/\\/g, "/");
+}
+function resolveLoadSpecPath(spec, fromFile) {
+  if (!spec.startsWith(".") && !spec.startsWith("/")) return void 0;
+  try {
+    const base = dirname2(resolve2(fromFile));
+    const p = resolve2(base, spec);
+    for (const cand of [
+      p,
+      `${p}.js`,
+      `${p}.mjs`,
+      `${p}.ts`,
+      join2(p, "index.js"),
+      join2(p, "index.mjs"),
+      join2(p, "index.ts")
+    ]) {
+      if (existsSync2(cand) && !statSync2(cand).isDirectory()) return cand;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function noteEnvPathDeps(sourcePath, source) {
+  const src = norm(sourcePath);
+  for (const set of envDependents.values()) set.delete(src);
+  let specs = [];
+  try {
+    specs = extractAllLoadSpecs(source);
+  } catch {
+    return;
+  }
+  for (const spec of specs) {
+    if (!spec.startsWith(".") && !spec.startsWith("/")) continue;
+    const abs = resolveLoadSpecPath(spec, sourcePath);
+    if (!abs) continue;
+    const key = norm(abs);
+    if (!envDependents.has(key)) envDependents.set(key, /* @__PURE__ */ new Set());
+    envDependents.get(key).add(src);
+  }
+}
+function envPathDependents(envPath) {
+  return [...envDependents.get(norm(envPath)) ?? []];
+}
+function clearEnvPathDeps() {
+  envDependents.clear();
+}
+function isEnvTemplatePath(path) {
+  const lower = norm(path).toLowerCase();
+  return lower.endsWith(".env.js") || lower.endsWith(".env.mjs") || lower.endsWith(".env.ts") || lower.endsWith(".env.cjs") || lower.endsWith(".env.cts") || lower.endsWith(".env.mts") || /\/mock-[^/]+\.(js|mjs|ts)$/.test(lower) || /\.mock\.(js|mjs|ts)$/.test(lower);
+}
+
+// src/analyzer.ts
+import { loadModuleDepsFingerprint as loadModuleDepsFingerprint2, hashSource as hashSource2 } from "@nudojs/core";
+
 // src/abs-modules-graph.ts
-import { readFileSync as readFileSync4, statSync as statSync3 } from "fs";
-import { dirname as dirname5, resolve as resolve4 } from "path";
+import { readFileSync as readFileSync4, statSync as statSync4 } from "fs";
+import { dirname as dirname6, resolve as resolve5 } from "path";
 import { parse as parse3 } from "@nudojs/parser";
 import {
   evalProgramAbs,
@@ -398,19 +466,19 @@ import {
   confJoin as confJoin2,
   absFunction as absFunction2
 } from "@nudojs/core";
-import { dirname as dirname4 } from "path";
+import { dirname as dirname5 } from "path";
 
 // src/harvest-auto.ts
 import { parse as parse2 } from "@nudojs/parser";
 
 // src/static-imports.ts
 import { parse } from "@nudojs/parser";
-import { readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
-import { resolve as resolve2, dirname as dirname2, join as join2 } from "path";
+import { readFileSync as readFileSync2, existsSync as existsSync3 } from "fs";
+import { resolve as resolve3, dirname as dirname3, join as join3 } from "path";
 import { generalizeFromAst } from "@nudojs/core";
 function resolveRelative(fromFile, spec) {
   if (!spec.startsWith(".") && !spec.startsWith("/")) return void 0;
-  const base = resolve2(dirname2(fromFile), spec);
+  const base = resolve3(dirname3(fromFile), spec);
   for (const cand of [
     base,
     base + ".js",
@@ -419,12 +487,12 @@ function resolveRelative(fromFile, spec) {
     base + ".ts",
     base + ".mts",
     base + ".cts",
-    join2(base, "index.js"),
-    join2(base, "index.cjs"),
-    join2(base, "index.mjs"),
-    join2(base, "index.ts")
+    join3(base, "index.js"),
+    join3(base, "index.cjs"),
+    join3(base, "index.mjs"),
+    join3(base, "index.ts")
   ]) {
-    if (existsSync2(cand)) return cand;
+    if (existsSync3(cand)) return cand;
   }
   return void 0;
 }
@@ -543,14 +611,14 @@ function collectCjsExports(stmt, named, setDefault) {
 function collectStaticImports(entryFile, maxDepth = 8) {
   const graph = /* @__PURE__ */ new Map();
   const queue = [
-    { file: resolve2(entryFile), depth: 0 }
+    { file: resolve3(entryFile), depth: 0 }
   ];
   const seen = /* @__PURE__ */ new Set();
   while (queue.length > 0) {
     const { file, depth } = queue.shift();
     if (seen.has(file) || depth > maxDepth) continue;
     seen.add(file);
-    if (!existsSync2(file)) continue;
+    if (!existsSync3(file)) continue;
     const source = readFileSync2(file, "utf8");
     const mod = analyzeExportsFromSource(file, source);
     graph.set(file, mod);
@@ -564,19 +632,19 @@ function collectStaticImports(entryFile, maxDepth = 8) {
 }
 
 // src/harvest-package.ts
-import { existsSync as existsSync3, readdirSync, statSync as statSync2, readFileSync as readFileSync3 } from "fs";
-import { join as join3, resolve as resolve3, dirname as dirname3, basename } from "path";
+import { existsSync as existsSync4, readdirSync, statSync as statSync3, readFileSync as readFileSync3 } from "fs";
+import { join as join4, resolve as resolve4, dirname as dirname4, basename } from "path";
 import { harvestDts } from "@nudojs/harvester";
 import { formatShape } from "@nudojs/core";
 function resolvePackageRoot(pkg, fromDir = process.cwd()) {
-  let dir = resolve3(fromDir);
+  let dir = resolve4(fromDir);
   const bare = pkg.replace(/^@/, "").replace(/\//g, "__");
   for (let i = 0; i < 8; i++) {
-    const typesPath = join3(dir, "node_modules", "@types", bare);
-    if (existsSync3(typesPath)) return typesPath;
-    const pkgPath = join3(dir, "node_modules", pkg);
-    if (existsSync3(pkgPath)) return pkgPath;
-    const parent = resolve3(dir, "..");
+    const typesPath = join4(dir, "node_modules", "@types", bare);
+    if (existsSync4(typesPath)) return typesPath;
+    const pkgPath = join4(dir, "node_modules", pkg);
+    if (existsSync4(pkgPath)) return pkgPath;
+    const parent = resolve4(dir, "..");
     if (parent === dir) break;
     dir = parent;
   }
@@ -606,10 +674,10 @@ function collectDtsFiles(root, maxFiles = 8) {
     for (const name of entries) {
       if (out.length >= maxFiles * 3) return;
       if (SKIP_DIRS.has(name)) continue;
-      const p = join3(dir, name);
+      const p = join4(dir, name);
       let st;
       try {
-        st = statSync2(p);
+        st = statSync3(p);
       } catch {
         continue;
       }
@@ -625,15 +693,15 @@ function collectDtsFiles(root, maxFiles = 8) {
   return out.slice(0, maxFiles);
 }
 function entryDtsFromPackageJson(root) {
-  const pj = join3(root, "package.json");
-  if (!existsSync3(pj)) return void 0;
+  const pj = join4(root, "package.json");
+  if (!existsSync4(pj)) return void 0;
   try {
     const raw = JSON.parse(readFileSync3(pj, "utf8"));
     const entry = raw.types ?? raw.typings;
     if (typeof entry === "string" && entry.endsWith(".d.ts")) {
-      const p = resolve3(root, entry);
-      if (existsSync3(p)) {
-        const st = statSync2(p);
+      const p = resolve4(root, entry);
+      if (existsSync4(p)) {
+        const st = statSync3(p);
         if (st.size <= MAX_DTS_BYTES) return p;
       }
     }
@@ -649,7 +717,7 @@ function collectDtsFromEntry(entry, maxFiles = 200) {
   const RELATIVE_FROM_REGEX = /\bfrom\s+["'](\.[^"']+)["']/g;
   while (queue.length > 0 && files.length < maxFiles) {
     const current = queue.shift();
-    if (seen.has(current) || !existsSync3(current)) continue;
+    if (seen.has(current) || !existsSync4(current)) continue;
     seen.add(current);
     if (!current.endsWith(".d.ts")) continue;
     files.push(current);
@@ -659,14 +727,14 @@ function collectDtsFromEntry(entry, maxFiles = 200) {
     } catch {
       continue;
     }
-    const dir = dirname3(current);
+    const dir = dirname4(current);
     for (const match of text.matchAll(REFERENCE_PATH_REGEX)) {
-      queue.push(resolve3(dir, match[1]));
+      queue.push(resolve4(dir, match[1]));
     }
     for (const match of text.matchAll(RELATIVE_FROM_REGEX)) {
-      const base = resolve3(dir, match[1]);
-      for (const candidate of [`${base}.d.ts`, join3(base, "index.d.ts")]) {
-        if (existsSync3(candidate)) {
+      const base = resolve4(dir, match[1]);
+      for (const candidate of [`${base}.d.ts`, join4(base, "index.d.ts")]) {
+        if (existsSync4(candidate)) {
           queue.push(candidate);
           break;
         }
@@ -678,11 +746,11 @@ function collectDtsFromEntry(entry, maxFiles = 200) {
 function harvestPackage(pkg, fromDir, maxFiles = 8) {
   const root = resolvePackageRoot(pkg, fromDir);
   if (!root) return { error: `package not found: ${pkg}` };
-  const entry = entryDtsFromPackageJson(root) ?? join3(root, "index.d.ts");
-  let dtsFiles = existsSync3(entry) ? collectDtsFromEntry(entry, maxFiles) : [];
+  const entry = entryDtsFromPackageJson(root) ?? join4(root, "index.d.ts");
+  let dtsFiles = existsSync4(entry) ? collectDtsFromEntry(entry, maxFiles) : [];
   if (dtsFiles.length === 0) {
     const collected = collectDtsFiles(root, maxFiles);
-    dtsFiles = entry && existsSync3(entry) && !collected.includes(entry) ? [entry, ...collected.filter((f) => f !== entry)].slice(0, maxFiles) : collected;
+    dtsFiles = entry && existsSync4(entry) && !collected.includes(entry) ? [entry, ...collected.filter((f) => f !== entry)].slice(0, maxFiles) : collected;
   }
   if (dtsFiles.length === 0) {
     return { error: `no .d.ts under ${root}` };
@@ -710,6 +778,49 @@ function lookupHarvested(h, moduleName, exportName) {
 }
 
 // src/harvest-auto.ts
+var NODE_BUILTINS = /* @__PURE__ */ new Set([
+  "assert",
+  "async_hooks",
+  "buffer",
+  "child_process",
+  "cluster",
+  "console",
+  "constants",
+  "crypto",
+  "dgram",
+  "diagnostics_channel",
+  "dns",
+  "domain",
+  "events",
+  "fs",
+  "http",
+  "http2",
+  "https",
+  "inspector",
+  "module",
+  "net",
+  "os",
+  "path",
+  "perf_hooks",
+  "process",
+  "punycode",
+  "querystring",
+  "readline",
+  "repl",
+  "stream",
+  "string_decoder",
+  "timers",
+  "tls",
+  "trace_events",
+  "tty",
+  "url",
+  "util",
+  "v8",
+  "vm",
+  "wasi",
+  "worker_threads",
+  "zlib"
+]);
 function barePackageName(spec) {
   if (!spec) return void 0;
   if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("node:")) return void 0;
@@ -717,7 +828,9 @@ function barePackageName(spec) {
   if (spec.startsWith("@")) {
     return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : void 0;
   }
-  return parts[0];
+  const name = parts[0];
+  if (NODE_BUILTINS.has(name)) return void 0;
+  return name;
 }
 function collectBarePackages(source) {
   try {
@@ -840,7 +953,7 @@ function bareSpecToAbsModules(spec, fromFile) {
   const parts = spec.split("/");
   const pkg = spec.startsWith("@") ? parts.length >= 2 ? `${parts[0]}/${parts[1]}` : void 0 : parts[0];
   if (!pkg) return void 0;
-  const table = harvestToAbsModules(pkg, dirname4(fromFile));
+  const table = harvestToAbsModules(pkg, dirname5(fromFile));
   return table[spec] ?? table[pkg];
 }
 
@@ -848,8 +961,8 @@ function bareSpecToAbsModules(spec, fromFile) {
 function defaultAbsLoadModule(spec, fromFile) {
   if (!spec.startsWith(".") && !spec.startsWith("/")) return void 0;
   try {
-    const p = resolve4(dirname5(resolve4(fromFile)), spec);
-    for (const cand of [p, `${p}.js`, `${p}.mjs`, `${p}.ts`, resolve4(p, "index.js")]) {
+    const p = resolve5(dirname6(resolve5(fromFile)), spec);
+    for (const cand of [p, `${p}.js`, `${p}.mjs`, `${p}.ts`, resolve5(p, "index.js")]) {
       try {
         return readFileSync4(cand, "utf-8");
       } catch {
@@ -861,8 +974,8 @@ function defaultAbsLoadModule(spec, fromFile) {
   }
 }
 function relCandidates(spec, fromFile) {
-  const p = resolve4(dirname5(resolve4(fromFile)), spec);
-  return [p, `${p}.js`, `${p}.mjs`, `${p}.ts`, resolve4(p, "index.js")];
+  const p = resolve5(dirname6(resolve5(fromFile)), spec);
+  return [p, `${p}.js`, `${p}.mjs`, `${p}.ts`, resolve5(p, "index.js")];
 }
 function resolveRel(spec, fromFile) {
   if (!spec.startsWith(".") && !spec.startsWith("/")) return null;
@@ -966,7 +1079,7 @@ function evalAbsModuleGraph(entrySource, entryFile, opts = {}) {
     const shared = absModuleCache.get(absPath);
     if (shared) {
       try {
-        const st = statSync3(absPath);
+        const st = statSync4(absPath);
         if (st.mtimeMs === shared.mtimeMs && st.size === shared.size) {
           for (const iss of shared.issues) pushIssue(iss.kind, iss.label, iss.reason);
           cache.set(absPath, shared.exports);
@@ -1031,7 +1144,7 @@ function evalAbsModuleGraph(entrySource, entryFile, opts = {}) {
     cache.set(absPath, exports);
     let fingerprint;
     try {
-      const st = statSync3(absPath);
+      const st = statSync4(absPath);
       fingerprint = { mtimeMs: st.mtimeMs, size: st.size };
     } catch {
     }
@@ -1102,7 +1215,8 @@ import {
   stableAnalyzeKeySource,
   formatAbs as formatAbs3,
   hashSource,
-  getFnImpl as getFnImpl2
+  getFnImpl as getFnImpl2,
+  loadModuleDepsFingerprint
 } from "@nudojs/core";
 import { parse as parse4, extractInlineDirectives } from "@nudojs/parser";
 
@@ -1245,6 +1359,50 @@ function collectEnvModules(envNames) {
   }
   return out;
 }
+var envHarvestConflictCollector = null;
+function setEnvHarvestConflictCollector(collector) {
+  const prev = envHarvestConflictCollector;
+  envHarvestConflictCollector = collector;
+  return prev;
+}
+function getEnvHarvestConflictCollector() {
+  return envHarvestConflictCollector;
+}
+function mergeHarvestUnderEnv(harvestModules, envModules, opts) {
+  const out = {};
+  for (const [mod, exports] of Object.entries(harvestModules)) {
+    const named = { ...exports.named };
+    out[mod] = exports.default !== void 0 ? { named, default: exports.default } : { named };
+  }
+  const notify = opts?.onConflict ?? envHarvestConflictCollector;
+  for (const [mod, envExports] of Object.entries(envModules)) {
+    const existing = out[mod];
+    if (!existing) {
+      const named2 = { ...envExports.named };
+      out[mod] = envExports.default !== void 0 ? { named: named2, default: envExports.default } : { named: named2 };
+      continue;
+    }
+    const overwritten = [];
+    for (const key of Object.keys(envExports.named)) {
+      if (existing.named[key] !== void 0) overwritten.push(key);
+    }
+    const defaultOverwritten = envExports.default !== void 0 && existing.default !== void 0;
+    if (notify && (overwritten.length > 0 || defaultOverwritten)) {
+      try {
+        notify({
+          module: mod,
+          exports: overwritten,
+          defaultOverwritten
+        });
+      } catch {
+      }
+    }
+    const named = { ...existing.named, ...envExports.named };
+    const defaultAbs = envExports.default !== void 0 ? envExports.default : existing.default;
+    out[mod] = defaultAbs !== void 0 ? { named, default: defaultAbs } : { named };
+  }
+  return out;
+}
 function collectBPathReplacements(source) {
   const targets = [];
   const values = {};
@@ -1304,6 +1462,15 @@ function isBPathCapable(source, envNames = []) {
 }
 var bRunByFile = /* @__PURE__ */ new Map();
 var MAX_B_RUN_CACHE = 32;
+function bPathDepKey(source, filePath) {
+  try {
+    const fp = loadModuleDepsFingerprint(source, defaultLoadModule, filePath);
+    if (fp.truncated) return null;
+    return hashSource(fp.fp);
+  } catch {
+    return null;
+  }
+}
 function clearBPathCache() {
   bRunByFile.clear();
   clearAnalysisFileCache();
@@ -1316,12 +1483,12 @@ function evictBPathCacheForFiles(files) {
   }
   return n;
 }
-function bPathCacheSet(filePath, stableSource, mode, envKey, mockKey, value) {
+function bPathCacheSet(filePath, stableSource, mode, envKey, mockKey, depKey, value) {
   if (bRunByFile.size >= MAX_B_RUN_CACHE && !bRunByFile.has(filePath)) {
     const oldest = bRunByFile.keys().next().value;
     if (oldest !== void 0) bRunByFile.delete(oldest);
   }
-  bRunByFile.set(filePath, { stableSource, mode, envKey, mockKey, value });
+  bRunByFile.set(filePath, { stableSource, mode, envKey, mockKey, depKey, value });
 }
 function tryRunBPath(source, filePath, opts = {}) {
   if (!isBPathCapable(source, opts.envNames ?? [])) return void 0;
@@ -1329,11 +1496,15 @@ function tryRunBPath(source, filePath, opts = {}) {
   const envKey = (opts.envNames ?? []).join(",");
   const mockKey = mockSeedFingerprint(opts.mocks);
   const stable = stableAnalyzeKeySource(source);
-  const cached = bRunByFile.get(filePath);
-  if (cached && cached.stableSource === stable && cached.mode === mode && cached.envKey === envKey && cached.mockKey === mockKey) {
-    bRunByFile.delete(filePath);
-    bRunByFile.set(filePath, cached);
-    return cached.value ?? void 0;
+  const depKey = bPathDepKey(source, filePath);
+  const canCache = depKey !== null;
+  if (canCache) {
+    const cached = bRunByFile.get(filePath);
+    if (cached && cached.stableSource === stable && cached.mode === mode && cached.envKey === envKey && cached.mockKey === mockKey && cached.depKey === depKey) {
+      bRunByFile.delete(filePath);
+      bRunByFile.set(filePath, cached);
+      return cached.value ?? void 0;
+    }
   }
   let out = null;
   try {
@@ -1346,7 +1517,7 @@ function tryRunBPath(source, filePath, opts = {}) {
     try {
       const { modules: graphMods, issues } = evalAbsModuleGraph(source, filePath);
       const envMods = collectEnvModules(opts.envNames ?? []);
-      const modules = { ...envMods, ...graphMods };
+      const modules = mergeHarvestUnderEnv(graphMods, envMods);
       const { targets, values, asTargets, asValues } = collectBPathReplacements(source);
       const envGlobals = {
         ...collectEnvGlobals(opts.envNames ?? []),
@@ -1378,7 +1549,9 @@ function tryRunBPath(source, filePath, opts = {}) {
   } catch {
     out = null;
   }
-  bPathCacheSet(filePath, stable, mode, envKey, mockKey, out);
+  if (canCache && depKey !== null) {
+    bPathCacheSet(filePath, stable, mode, envKey, mockKey, depKey, out);
+  }
   return out ?? void 0;
 }
 function tryBPathCallFull(source, filePath, fnName, args, opts = {}) {
@@ -1520,6 +1693,9 @@ function collectDeclared(file) {
       case "ImportNamespaceSpecifier":
         addId(o.local);
         break;
+      case "CatchClause":
+        addId(o.param);
+        break;
       default:
         break;
     }
@@ -1621,10 +1797,10 @@ function collectBPathDiagnostics(source, extraKnown) {
 // src/analyzer.ts
 import { setAbsTruncationCollector as setAbsTruncationCollector2 } from "@nudojs/core";
 function resolveImportPath(specifier, fromDir) {
-  const basePath = resolve5(fromDir, specifier);
+  const basePath = resolve6(fromDir, specifier);
   for (const ext of ["", ".js", ".ts", ".mjs"]) {
     const candidate = basePath + ext;
-    if (existsSync4(candidate)) return candidate;
+    if (existsSync5(candidate)) return candidate;
   }
   return null;
 }
@@ -1644,7 +1820,7 @@ function buildModuleGraph(files, cache) {
     if (cache) {
       let stat = null;
       try {
-        stat = statSync4(file);
+        stat = statSync5(file);
       } catch {
       }
       const cached = stat ? cache.get(file) : void 0;
@@ -1673,7 +1849,7 @@ function extractImportEdges(file) {
     if (stmt.type !== "ImportDeclaration") continue;
     const specifier = stmt.source.value;
     if (!specifier.startsWith(".") && !specifier.startsWith("/")) continue;
-    const resolved = resolveImportPath(specifier, dirname6(file));
+    const resolved = resolveImportPath(specifier, dirname7(file));
     if (resolved) edges.push(resolved);
   }
   return edges;
@@ -1748,23 +1924,13 @@ function locFromNode(node) {
 }
 function extractParamNames(node) {
   const fn = node.type === "ExportDefaultDeclaration" ? node.declaration : node;
-  if (fn.type === "FunctionDeclaration" || fn.type === "FunctionExpression" || fn.type === "ArrowFunctionExpression") {
-    return fn.params.map((p) => {
-      if (p.type === "Identifier") return p.name;
-      if (p.type === "AssignmentPattern" && p.left.type === "Identifier") return p.left.name;
-      if (p.type === "RestElement" && p.argument.type === "Identifier") return `...${p.argument.name}`;
-      return "_";
-    });
+  if (fn.type === "FunctionDeclaration" || fn.type === "FunctionExpression" || fn.type === "ArrowFunctionExpression" || fn.type === "ClassMethod" || fn.type === "ObjectMethod" || fn.type === "TSDeclareMethod") {
+    return formalParamDisplayNames(formalParamsFromNodes(fn.params));
   }
   if (fn.type === "VariableDeclaration") {
     const decl = fn.declarations[0];
     if (decl.init?.type === "FunctionExpression" || decl.init?.type === "ArrowFunctionExpression") {
-      return decl.init.params.map((p) => {
-        if (p.type === "Identifier") return p.name;
-        if (p.type === "AssignmentPattern" && p.left.type === "Identifier") return p.left.name;
-        if (p.type === "RestElement" && p.argument.type === "Identifier") return `...${p.argument.name}`;
-        return "_";
-      });
+      return formalParamDisplayNames(formalParamsFromNodes(decl.init.params));
     }
   }
   return [];
@@ -1828,12 +1994,103 @@ function assignmentChainName(expr) {
 function collectTopLevelFunctions(ast) {
   const results = [];
   if (ast.type !== "File") return results;
-  for (const stmt of ast.program.body) {
+  const body = ast.program.body;
+  const classDecls = /* @__PURE__ */ new Map();
+  const exportedClassNames = /* @__PURE__ */ new Set();
+  const collectClassMethods = (cname, decl, stmt) => {
+    const members = decl?.body?.body ?? [];
+    for (const m of members) {
+      const mem = m;
+      const isMethod = mem.type === "MethodDefinition" || mem.type === "ClassMethod" || mem.type === "TSDeclareMethod";
+      if (!isMethod) continue;
+      if (mem.kind && mem.kind !== "method") continue;
+      if (mem.static) 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;
+      results.push({
+        name: `${cname}.${keyName}`,
+        node: methodNode,
+        stmt,
+        noDeclaration: true
+      });
+    }
+  };
+  for (const stmt of body) {
+    if (stmt.type === "ClassDeclaration" && stmt.id?.name) {
+      const n = stmt.id.name;
+      classDecls.set(n, { node: stmt, stmt });
+      continue;
+    }
+    if (stmt.type === "ExportNamedDeclaration") {
+      const d = stmt.declaration;
+      if (d?.type === "ClassDeclaration" && d.id?.name) {
+        const n = d.id.name;
+        classDecls.set(n, { node: d, stmt });
+        exportedClassNames.add(n);
+        continue;
+      }
+      if (!d && stmt.specifiers) {
+        for (const spec of stmt.specifiers) {
+          if (spec?.type !== "ExportSpecifier") continue;
+          const local = spec.local?.name;
+          const exported = spec.exported?.name ?? spec.exported?.value;
+          if (!local) continue;
+          if (classDecls.has(local) || body.some(
+            (s) => s.type === "ClassDeclaration" && s.id?.name === local
+          )) {
+            exportedClassNames.add(local);
+          }
+          if (exported === "default") exportedClassNames.add(local);
+        }
+        continue;
+      }
+    }
+    if (stmt.type === "ExportDefaultDeclaration") {
+      const d = stmt.declaration;
+      if (d?.type === "ClassDeclaration" && d.id?.name) {
+        const n = d.id.name;
+        classDecls.set(n, { node: d, stmt });
+        exportedClassNames.add(n);
+      } else if (d?.type === "Identifier" && typeof d.name === "string") {
+        exportedClassNames.add(d.name);
+      }
+      continue;
+    }
+  }
+  for (const stmt of body) {
     const decl = resolveFunctionNode(stmt);
     if (decl.type === "FunctionDeclaration" && decl.id) {
       results.push({ name: decl.id.name, node: decl, stmt, noDeclaration: false });
       continue;
     }
+    if (decl.type === "ClassDeclaration" && decl.id?.name) {
+      continue;
+    }
+    if (stmt.type === "ExportNamedDeclaration") {
+      const d = resolveFunctionNode(stmt);
+      if (d.type === "FunctionDeclaration" && d.id) {
+        results.push({ name: d.id.name, node: d, stmt, noDeclaration: false });
+      }
+      if (d.type === "ClassDeclaration" && d.id?.name) {
+      }
+      continue;
+    }
+    if (stmt.type === "ExportDefaultDeclaration") {
+      const d = stmt.declaration;
+      if (d?.type === "FunctionDeclaration" && d.id) {
+        results.push({ name: d.id.name, node: d, stmt, noDeclaration: false });
+      } else if (d && (isFnExprValue(d) || d.type === "FunctionDeclaration" && !d.id)) {
+        results.push({
+          name: "default",
+          node: d,
+          stmt,
+          noDeclaration: true
+        });
+      }
+      continue;
+    }
     if (stmt.type === "VariableDeclaration") {
       for (const declarator of stmt.declarations) {
         if (declarator.id?.type === "Identifier" && isFnExprValue(declarator.init)) {
@@ -1851,6 +2108,11 @@ function collectTopLevelFunctions(ast) {
       }
     }
   }
+  for (const cname of exportedClassNames) {
+    const hit = classDecls.get(cname);
+    if (!hit) continue;
+    collectClassMethods(cname, hit.node, hit.stmt);
+  }
   return results;
 }
 function findSingleModuleExportsFunction(ast) {
@@ -1877,7 +2139,7 @@ function findSingleModuleExportsFunction(ast) {
   }
   return found;
 }
-var MAX_PRECISE_CALLSITE_CASES = 3;
+var DEFAULT_CALLSITE_BUDGET = 3;
 var COLLAPSE_LITERAL_THRESHOLD = 4;
 function dedupeCallRecords(records) {
   const seen = /* @__PURE__ */ new Set();
@@ -1895,7 +2157,7 @@ function locFromCallLoc(loc) {
   const p = loc ?? { line: 0, column: 0 };
   return { start: { line: p.line, column: p.column }, end: { line: p.line, column: p.column } };
 }
-function synthesizeExternalFunctions(records, currentFile) {
+function synthesizeExternalFunctions(records, currentFile, callSiteBudget = DEFAULT_CALLSITE_BUDGET) {
   const groups = /* @__PURE__ */ new Map();
   for (const rec of records) {
     if (!rec.targetModule || !rec.targetExport) continue;
@@ -1919,7 +2181,7 @@ function synthesizeExternalFunctions(records, currentFile) {
       cases: [],
       fromModule: module
     };
-    const precise = deduped.slice(0, MAX_PRECISE_CALLSITE_CASES);
+    const precise = deduped.slice(0, callSiteBudget);
     for (const rec of precise) {
       analysis.cases.push({
         name: `call@L${rec.callLoc?.line ?? 0}`,
@@ -1929,7 +2191,7 @@ function synthesizeExternalFunctions(records, currentFile) {
         source: "callsite"
       });
     }
-    const remaining = deduped.slice(MAX_PRECISE_CALLSITE_CASES);
+    const remaining = deduped.slice(callSiteBudget);
     if (remaining.length > 0) {
       const symArgsAbs = Array.from(
         { length: arity },
@@ -1970,16 +2232,17 @@ function collectEnvNames(filePath, source, includeProject) {
   const fileDirectives = extractFileDirectives(ast);
   const fileEnvNames = fileDirectives.filter((d) => d.kind === "env").flatMap((d) => d.envs);
   if (!includeProject) return fileEnvNames;
-  const projectConfig = findProjectConfig(dirname6(filePath));
+  const projectConfig = findProjectConfig(dirname7(filePath));
   const projectEnvNames = projectConfig?.config.env ?? [];
   return [.../* @__PURE__ */ new Set([...projectEnvNames, ...fileEnvNames])];
 }
-async function analyzeFileAsync(filePath, source, activeCases, externalCallRecords) {
+async function analyzeFileAsync(filePath, source, activeCases, externalCallRecords, loadModule) {
   const envNames = collectEnvNames(filePath, source, true);
+  noteEnvPathDeps(filePath, source);
   if (envNames.length > 0) {
-    await preloadPathEnvs(envNames, dirname6(filePath));
+    await preloadPathEnvs(envNames, dirname7(filePath));
   }
-  return analyzeFile(filePath, source, activeCases, externalCallRecords);
+  return analyzeFile(filePath, source, activeCases, externalCallRecords, loadModule);
 }
 function collectCallRecords(filePath, source) {
   if (/\brequire\s*\(/.test(source) && filePath) {
@@ -2050,7 +2313,7 @@ function collectCallRecords(filePath, source) {
 var TEST_CALLBACK_NAMES = /* @__PURE__ */ new Set(["it", "test", "describe"]);
 var externalRecordIds = /* @__PURE__ */ new WeakMap();
 var nextExternalRecordId = 1;
-function analysisFileCacheKey(filePath, source, activeCases, externalCallRecords) {
+function analysisFileCacheKey(filePath, source, activeCases, externalCallRecords, analysisCfg, loadModule, projectEnvNames, autoBind) {
   let cases = "-";
   if (activeCases && activeCases.size > 0) {
     cases = [...activeCases.entries()].sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0).map(([k, v]) => `${k}=${v}`).join(",");
@@ -2064,11 +2327,31 @@ function analysisFileCacheKey(filePath, source, activeCases, externalCallRecords
     }
     ext = `n${externalCallRecords.length}#id${id}`;
   }
+  const cfg = analysisCfg ? `m=${analysisCfg.mode}|e=${analysisCfg.evalMissingSlot}|b=${analysisCfg.callSiteBudget}|d=${analysisCfg.diagnostics}` : "-";
+  const lm = loadModule !== void 0 && loadModule !== defaultLoadModule ? "lm1" : "lm0";
+  const envSeg = projectEnvNames && projectEnvNames.length > 0 ? projectEnvNames.join(",") : "-";
+  const abSeg = autoBind === false ? "ab0" : autoBind === true ? "ab1" : "ab?";
+  const effectiveLoader = loadModule ?? defaultLoadModule;
+  let depSeg = "-";
+  let noCache = false;
+  try {
+    const fp = loadModuleDepsFingerprint2(source, effectiveLoader, filePath);
+    if (fp.truncated) {
+      noCache = true;
+      depSeg = `trunc:${fp.paths.length}`;
+    } else {
+      depSeg = hashSource2(fp.fp);
+    }
+  } catch {
+    noCache = true;
+    depSeg = "fperr";
+  }
   return {
     filePath,
     // 尾部无 @nudo 注释/空行不进键：comment-only 编辑命中 AnalysisResult
     source: stableAnalyzeKeySource2(source),
-    auxKey: `${cases}\0${ext}`
+    auxKey: `${cases}\0${ext}\0${cfg}\0${lm}\0${envSeg}\0${abSeg}\0${depSeg}`,
+    noCache
   };
 }
 function cloneAnalysisResult(r) {
@@ -2086,12 +2369,20 @@ function cloneFunctionAnalysis(a) {
   return {
     ...a,
     paramNames: [...a.paramNames],
+    ...a.formals ? { formals: a.formals.map((f) => ({ ...f })) } : {},
     cases: a.cases.map((c) => ({
       ...c,
       argAbs: [...c.argAbs],
       ...c.intension ? { intension: { ...c.intension } } : {}
     })),
-    loc: { start: { ...a.loc.start }, end: { ...a.loc.end } }
+    loc: { start: { ...a.loc.start }, end: { ...a.loc.end } },
+    ...a.hof ? {
+      hof: {
+        ...a.hof.fnRels ? { fnRels: a.hof.fnRels.map((r) => ({ ...r })) } : {},
+        ...a.hof.entryShapes ? { entryShapes: a.hof.entryShapes.map((s) => ({ ...s })) } : {},
+        ...a.hof.symbolic ? { symbolic: a.hof.symbolic } : {}
+      }
+    } : {}
   };
 }
 function shiftSourceLoc(loc, lineDelta) {
@@ -2115,17 +2406,60 @@ function shiftCallRecordLines(r, lineDelta) {
     callLoc: { line: r.callLoc.line + lineDelta, column: r.callLoc.column }
   };
 }
-function analyzeFile(filePath, source, activeCases, externalCallRecords) {
-  const k = analysisFileCacheKey(filePath, source, activeCases, externalCallRecords);
-  const hit = analysisCacheGet(k.filePath, k.source, k.auxKey);
-  if (hit !== void 0) {
-    return cloneAnalysisResult(hit);
+function analyzeFile(filePath, source, activeCases, externalCallRecords, loadModule) {
+  const projectConfig = findProjectConfig(dirname7(filePath));
+  const cfg = analysisConfig(projectConfig?.config);
+  const projectEnvNames = projectConfig?.config.env ?? [];
+  const autoBind = interfaceConfig(projectConfig?.config).autoBind;
+  const k = analysisFileCacheKey(
+    filePath,
+    source,
+    activeCases,
+    externalCallRecords,
+    cfg,
+    loadModule,
+    projectEnvNames,
+    autoBind !== false
+  );
+  if (!k.noCache) {
+    const hit = analysisCacheGet(k.filePath, k.source, k.auxKey);
+    if (hit !== void 0) {
+      return cloneAnalysisResult(hit);
+    }
+  }
+  const result = analyzeFileUncached(filePath, source, activeCases, externalCallRecords, loadModule);
+  if (!k.noCache) {
+    analysisCacheSet(k.filePath, k.source, k.auxKey, result);
   }
-  const result = analyzeFileUncached(filePath, source, activeCases, externalCallRecords);
-  analysisCacheSet(k.filePath, k.source, k.auxKey, result);
   return cloneAnalysisResult(result);
 }
-function analyzeFileUncached(filePath, source, activeCases, externalCallRecords) {
+function analyzeFileUncached(filePath, source, activeCases, externalCallRecords, loadModule) {
+  const projectConfig = findProjectConfig(dirname7(filePath));
+  const missingSlotOn = analysisConfig(projectConfig?.config).evalMissingSlot === "warning";
+  return runWithEvalMissingSlot(
+    missingSlotOn,
+    () => analyzeFileUncachedInner(filePath, source, activeCases, externalCallRecords, loadModule)
+  );
+}
+function findModuleImportLoc(source, module) {
+  const bare = module.startsWith("node:") ? module.slice("node:".length) : module;
+  const alts = [.../* @__PURE__ */ new Set([module, bare, `node:${bare}`])];
+  const lines = source.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const alt of alts) {
+      const re = new RegExp(
+        `["'\`]${alt.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["'\`]`
+      );
+      const m = re.exec(line);
+      if (m && m.index !== void 0) {
+        return { line: i, column: m.index, length: m[0].length };
+      }
+    }
+  }
+  return null;
+}
+function analyzeFileUncachedInner(filePath, source, activeCases, externalCallRecords, loadModule) {
   const ast = parse5(source);
   const functions = extractDirectives(ast);
   const diagnostics = [];
@@ -2133,20 +2467,47 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
   const nodeAbsMap = /* @__PURE__ */ new Map();
   const functionResults = [];
   const caseHints = [];
+  const envHarvestConflicts = [];
+  const prevHarvestConflictCollector = setEnvHarvestConflictCollector((c) => {
+    if (!envHarvestConflicts.some((x) => x.module === c.module)) {
+      envHarvestConflicts.push(c);
+    } else {
+      const prev = envHarvestConflicts.find((x) => x.module === c.module);
+      for (const e of c.exports) {
+        if (!prev.exports.includes(e)) prev.exports.push(e);
+      }
+      prev.defaultOverwritten ||= c.defaultOverwritten;
+    }
+  });
   const fileDirectives = extractFileDirectives(ast);
   const fileEnvNames = fileDirectives.filter((d) => d.kind === "env").flatMap((d) => d.envs);
-  const projectConfig = findProjectConfig(dirname6(filePath));
+  const projectConfig = findProjectConfig(dirname7(filePath));
   const projectEnvNames = projectConfig?.config.env ?? [];
   const envNames = [.../* @__PURE__ */ new Set([...projectEnvNames, ...fileEnvNames])];
+  const analysisCfg = analysisConfig(projectConfig?.config);
+  const callSiteBudget = analysisCfg.callSiteBudget;
   const callRecords = [];
   const globalEnv = createEnvironment2();
   const bMemberDiagNames = /* @__PURE__ */ new Set();
   const bMemberDiagSeen = /* @__PURE__ */ new Set();
   const pushBMemberDiag = (d, fallbackLine) => {
     bMemberDiagNames.add(d.name);
-    const key = `${d.kind}:${d.name}:${d.receiver}:${d.line ?? fallbackLine}:${d.column ?? 0}`;
+    const key = `${d.kind}:${d.name}:${d.receiver}:${d.line ?? fallbackLine}:${d.column ?? 0}:${d.code ?? ""}`;
     if (bMemberDiagSeen.has(key)) return;
     bMemberDiagSeen.add(key);
+    if (d.code === "nudo:missing-slot") {
+      diagnostics.push({
+        range: {
+          start: { line: d.line ?? fallbackLine, column: d.column ?? 0 },
+          end: { line: d.line ?? fallbackLine, column: (d.column ?? 0) + d.name.length }
+        },
+        severity: "warning",
+        message: `Field '${d.name}' is missing on the evaluated object shape`,
+        code: "nudo:missing-slot",
+        ...d.origin ? { origin: d.origin } : {}
+      });
+      return;
+    }
     if (d.receiver === "unknown") {
       diagnostics.push({
         range: {
@@ -2204,9 +2565,10 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
     try {
       const g = evalAbsModuleGraph(source, filePath, {
         seedVars: seeds.seedVars,
-        seedFns: seeds.seedFns
+        seedFns: seeds.seedFns,
+        ...loadModule ? { loadModule } : {}
       });
-      absGraphModules = { ...collectEnvModules(envNames), ...g.modules };
+      absGraphModules = mergeHarvestUnderEnv(g.modules, collectEnvModules(envNames));
       pushBModuleIssues(g.issues);
     } catch {
     }
@@ -2235,7 +2597,7 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
   if (selfContained || canAbsModules) {
     setAbsTruncationCollector2((label) => bTruncatedFns.add(label));
     try {
-      absCallRecords = collectAbsCallRecords(source, seeds, filePath, absGraphModules, envNames);
+      absCallRecords = collectAbsCallRecords(source, seeds, filePath, absGraphModules, envNames, loadModule);
     } finally {
       setAbsTruncationCollector2(null);
     }
@@ -2257,7 +2619,10 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
     } catch {
     }
   }
-  if ((selfContained || canAbsModules) && absCallRecords.length > 0) {
+  if (bHostedEval && bTopCallRecords.length > 0) {
+    callRecords.length = 0;
+    callRecords.push(...bTopCallRecords);
+  } else if ((selfContained || canAbsModules) && absCallRecords.length > 0) {
     callRecords.length = 0;
     callRecords.push(...absCallRecords);
   } else if (bTopCallRecords.length > 0) {
@@ -2345,7 +2710,16 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
     const skipDirective = fn.directives.find((d) => d.kind === "skip");
     const fnLoc = locFromNode(fn.node);
     const paramNames = extractParamNames(fn.node);
-    const analysis = { name: fn.name, loc: fnLoc, paramNames, cases: [] };
+    const formals = formalParamsFromNodes(
+      fn.node.params ?? []
+    );
+    const analysis = {
+      name: fn.name,
+      loc: fnLoc,
+      paramNames,
+      ...formals.length > 0 ? { formals } : {},
+      cases: []
+    };
     if (skipDirective && skipDirective.kind === "skip") {
       analysis.skipped = true;
       if (skipDirective.returns) {
@@ -2357,14 +2731,31 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
     const caseDirectives = fn.directives.filter((d) => d.kind === "case");
     const activeCaseIdx = activeCases?.get(fn.name) ?? 0;
     const fp = fnFpMap?.get(fn.name);
-    const fnCacheKey = fp && caseDirectives.length > 0 ? [
+    const analysisFnKey = `m=${analysisCfg.mode}|e=${analysisCfg.evalMissingSlot}|b=${analysisCfg.callSiteBudget}`;
+    let fnDepSeg = "-";
+    let fnDepFailClosed = false;
+    try {
+      const dfp = loadModuleDepsFingerprint2(source, loadModule ?? defaultLoadModule, filePath);
+      if (dfp.truncated) {
+        fnDepFailClosed = true;
+        fnDepSeg = null;
+      } else {
+        fnDepSeg = hashSource2(dfp.fp);
+      }
+    } catch {
+      fnDepFailClosed = true;
+      fnDepSeg = null;
+    }
+    const fnCacheKey = !fnDepFailClosed && fp && caseDirectives.length > 0 ? [
       filePath,
       fp.own,
       fp.deps,
       String(activeCaseIdx),
       caseDirectiveKey(caseDirectives, formatAbs4),
       envKeyFn,
-      mockKeyFn
+      mockKeyFn,
+      analysisFnKey,
+      fnDepSeg ?? "-"
     ].join("\0") : void 0;
     const dLen0 = diagnostics.length;
     const hLen0 = caseHints.length;
@@ -2538,6 +2929,7 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
         COLLAPSE_LITERAL_THRESHOLD
       );
     }
+    attachHofSnapshot(analysis, source);
     if (fnCacheKey) {
       fnAnalysisCacheSet(fnCacheKey, {
         analysis: cloneFunctionAnalysis(analysis),
@@ -2571,7 +2963,7 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
     }
     return n;
   };
-  const currentModulePath = normalizeModulePath(resolve5(filePath));
+  const currentModulePath = normalizeModulePath(resolve6(filePath));
   const singleExportFn = findSingleModuleExportsFunction(ast);
   const reportInjectedDomainExceeds = (name, node, fallbackLoc) => {
     if (!externalCallRecords || externalCallRecords.length === 0) return;
@@ -2586,10 +2978,10 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
     if (injected.length === 0) return;
     const nameLoc = fnNameLoc(node, fallbackLoc);
     const fnNode = resolveFunctionNode(node);
-    const autoBind = interfaceConfig(findProjectConfig(dirname6(filePath))?.config).autoBind;
+    const autoBind = interfaceConfig(findProjectConfig(dirname7(filePath))?.config).autoBind;
     const domainIssues = checkInjectedDomainEvidence(name, source, injected, {
       paramNames: extractParamNames(fnNode),
-      loadModule: defaultLoadModule,
+      loadModule: loadModule ?? defaultLoadModule,
       fromFile: filePath,
       loc: { line: nameLoc.start.line, column: nameLoc.start.column },
       ...autoBind === false ? { autoBind: false } : {}
@@ -2639,7 +3031,7 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
         return 0;
       };
       const ordered = records.map((r, i) => ({ r, i })).sort((a, b) => informativeness(a.r) - informativeness(b.r) || a.i - b.i).map(({ r }) => r);
-      const precise = ordered.slice(0, MAX_PRECISE_CALLSITE_CASES);
+      const precise = ordered.slice(0, callSiteBudget);
       for (const rec of precise) {
         let absRaw;
         let absResult;
@@ -2666,7 +3058,7 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
         if (absRaw) attachAbsToIntension(caseResult2, absRaw, candidate.name);
         candidate.analysis.cases.push(caseResult2);
       }
-      const remaining = ordered.slice(MAX_PRECISE_CALLSITE_CASES).filter((rec) => !rec.argAbs.some((a) => a.shape.k === "unknown" && !a.term));
+      const remaining = ordered.slice(callSiteBudget).filter((rec) => !rec.argAbs.some((a) => a.shape.k === "unknown" && !a.term));
       if (remaining.length > 0) {
         const fnNode2 = resolveFunctionNode(candidate.node);
         const paramCount = extractParamNames(fnNode2).length;
@@ -2707,7 +3099,8 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
         const symCase = {
           name: "call@symbolic",
           argAbs: widenedArgsAbs,
-          abs: symAbs ?? absUnknown2,
+          // B4：超预算聚合必须 #widened（可解释降级）
+          abs: symAbs ? { ...symAbs, conf: symAbs.conf === "exact" ? "widened" : symAbs.conf } : absUnknown2,
           throwsAbs: neverAbs,
           source: "callsite",
           aggregatedFrom: remaining.length
@@ -2771,11 +3164,34 @@ function analyzeFileUncached(filePath, source, activeCases, externalCallRecords)
     candidate.analysis.cases.push(caseResult);
     candidate.analysis.entryOnly = true;
     candidate.analysis.combinedAbs = entryAbs;
+    attachHofSnapshot(candidate.analysis, source);
   }
   if (!bHostedEval) {
     buildNodeTypeMap(ast, globalEnv, nodeAbsMap);
   }
-  const externalFunctions = synthesizeExternalFunctions(callRecords, filePath);
+  const externalFunctions = synthesizeExternalFunctions(
+    callRecords,
+    filePath,
+    analysisConfig(projectConfig?.config).callSiteBudget
+  );
+  setEnvHarvestConflictCollector(prevHarvestConflictCollector);
+  for (const c of envHarvestConflicts) {
+    const parts = [];
+    if (c.exports.length > 0) parts.push(`export(s) ${c.exports.join(", ")}`);
+    if (c.defaultOverwritten) parts.push("default");
+    const detail = parts.length > 0 ? ` \u2014 ${parts.join("; ")}` : "";
+    const loc = findModuleImportLoc(source, c.module);
+    const range = loc ? {
+      start: { line: loc.line, column: loc.column },
+      end: { line: loc.line, column: loc.column + loc.length }
+    } : { start: { line: 0, column: 0 }, end: { line: 0, column: 0 } };
+    diagnostics.push({
+      range,
+      severity: "warning",
+      message: `handwritten @nudo:env wins over harvest on module "${c.module}"${detail}; harvest only fills missing slots (B8). code=nudo:env-harvest-conflict`,
+      code: "nudo:env-harvest-conflict"
+    });
+  }
   return {
     functions: functionResults,
     diagnostics,
@@ -2870,7 +3286,7 @@ function absModulesOk(source, envNames) {
   void envNames;
   return true;
 }
-function collectAbsCallRecords(source, seeds, filePath, precomputedModules, envNames = []) {
+function collectAbsCallRecords(source, seeds, filePath, precomputedModules, envNames = [], loadModule) {
   const absCalls = [];
   let modules = precomputedModules;
   let importLocals = /* @__PURE__ */ new Map();
@@ -2879,7 +3295,8 @@ function collectAbsCallRecords(source, seeds, filePath, precomputedModules, envN
       try {
         const graph = evalAbsModuleGraph(source, filePath, {
           seedVars: seeds?.seedVars,
-          seedFns: seeds?.seedFns
+          seedFns: seeds?.seedFns,
+          ...loadModule ? { loadModule } : {}
         });
         modules = graph.modules;
       } catch {
@@ -2887,7 +3304,7 @@ function collectAbsCallRecords(source, seeds, filePath, precomputedModules, envN
       }
     }
     if (envNames.length > 0) {
-      modules = { ...collectEnvModules(envNames), ...modules ?? {} };
+      modules = mergeHarvestUnderEnv(modules ?? {}, collectEnvModules(envNames));
     }
     try {
       importLocals = buildAbsImportLocalMap(source, filePath);
@@ -2986,10 +3403,10 @@ function buildAbsImportLocalMap(source, fromFile) {
   return out;
 }
 function resolveImportAbs(spec, fromFile) {
-  const base = dirname6(resolve5(fromFile));
-  const p = resolve5(base, spec);
-  for (const cand of [p, `${p}.js`, `${p}.mjs`, `${p}.ts`, resolve5(p, "index.js")]) {
-    if (existsSync4(cand) && !statSync4(cand).isDirectory()) return cand;
+  const base = dirname7(resolve6(fromFile));
+  const p = resolve6(base, spec);
+  for (const cand of [p, `${p}.js`, `${p}.mjs`, `${p}.ts`, resolve6(p, "index.js")]) {
+    if (existsSync5(cand) && !statSync5(cand).isDirectory()) return cand;
   }
   return null;
 }
@@ -3063,6 +3480,22 @@ function tryAttachIntension(caseResult, source, fnName) {
   } catch {
   }
 }
+function attachHofSnapshot(analysis, source) {
+  if (analysis.hof) return;
+  try {
+    const g = generalizeFromAst2(analysis.name, source);
+    if (!g) return;
+    const fnRels = g.fnRels ? [...g.fnRels.entries()].map(([param, rec]) => ({ param, abs: rec.abs })) : void 0;
+    const entryShapes = g.entryShapes ? [...g.entryShapes.entries()].map(([param, rec]) => ({ param, abs: rec.abs })) : void 0;
+    if (!fnRels?.length && !entryShapes?.length) return;
+    analysis.hof = {
+      ...fnRels?.length ? { fnRels } : {},
+      ...entryShapes?.length ? { entryShapes } : {},
+      symbolic: g.symbolic
+    };
+  } catch {
+  }
+}
 function attachAbsToIntension(caseResult, absVal, label) {
   const prev = caseResult.intension ?? {};
   caseResult.abs = absVal;
@@ -3074,10 +3507,27 @@ function attachAbsToIntension(caseResult, absVal, label) {
   };
 }
 function safeAbsOrUnknown(a) {
-  if (!a || typeof a !== "object" || !("shape" in a) || !a.shape) {
-    return { shape: { k: "unknown" }, conf: "opaque" };
+  if (a && typeof a === "object" && "shape" in a && "conf" in a) {
+    return a;
+  }
+  if (typeof a === "function") {
+    const fn = a;
+    const n = Math.max(0, fn.length);
+    const params = Array.from({ length: n }, (_, i) => `arg${i}`);
+    return absFunction4(params, {
+      body: { type: "BlockStatement", body: [], directives: [] },
+      apply: (args) => {
+        try {
+          const r = fn(...args);
+          if (r && typeof r === "object" && "shape" in r) return r;
+          return absUnknown2;
+        } catch {
+          return absUnknown2;
+        }
+      }
+    });
   }
-  return a;
+  return absUnknown2;
 }
 function callRecordFromAbsCall(r, impMap) {
   const argAbs = r.args.map(safeAbsOrUnknown);
@@ -3099,7 +3549,7 @@ function callRecordFromAbsCall(r, impMap) {
 }
 
 // src/lsp-surface.ts
-import { dirname as dirname7 } from "path";
+import { dirname as dirname8 } from "path";
 import traverse2 from "@babel/traverse";
 import {
   generalizeFromAst as generalizeFromAst3,
@@ -3109,7 +3559,8 @@ import {
   collectAbsNodeTypes,
   findAbsAtPosition,
   evalSource,
-  setAbsNodeCollector as setAbsNodeCollector2
+  setAbsNodeCollector as setAbsNodeCollector2,
+  interfaceTierOf
 } from "@nudojs/core";
 import { parse as parse6, extractDirectives as extractDirectives2, extractFileDirectives as extractFileDirectives2 } from "@nudojs/parser";
 function getCasesForFile(filePath, source) {
@@ -3123,14 +3574,14 @@ function getCasesForFile(filePath, source) {
 async function getTypeAtPositionAsync(filePath, source, line, column, activeCases) {
   const envNames = collectEnvNames(filePath, source, false);
   if (envNames.length > 0) {
-    await preloadPathEnvs(envNames, dirname7(filePath));
+    await preloadPathEnvs(envNames, dirname8(filePath));
   }
   return getTypeAtPosition(filePath, source, line, column, activeCases);
 }
 async function getAbsAtPositionAsync(filePath, source, line, column, activeCases) {
   const envNames = collectEnvNames(filePath, source, false);
   if (envNames.length > 0) {
-    await preloadPathEnvs(envNames, dirname7(filePath));
+    await preloadPathEnvs(envNames, dirname8(filePath));
   }
   return getAbsAtPosition(filePath, source, line, column, activeCases);
 }
@@ -3218,7 +3669,7 @@ function getAbsAtPosition(filePath, source, line, column, activeCases) {
 function getTypeAtPosition(filePath, source, line, column, activeCases) {
   return getAbsAtPosition(filePath, source, line, column, activeCases);
 }
-function getHoverAtPosition(filePath, source, line, column, activeCases) {
+function getHoverAtPosition(filePath, source, line, column, activeCases, opts) {
   let file;
   try {
     file = parse6(source);
@@ -3227,6 +3678,7 @@ function getHoverAtPosition(filePath, source, line, column, activeCases) {
   }
   const envNames = collectEnvNames(filePath, source, false);
   const fnName = findFunctionNameAtPosition(source, line, column, file);
+  const tier = fnName !== void 0 ? interfaceTierOf(source, fnName, filePath, opts ?? {}) : void 0;
   let gDisplay;
   let gAbs;
   let gMulti;
@@ -3241,18 +3693,26 @@ function getHoverAtPosition(filePath, source, line, column, activeCases) {
     } catch {
     }
   }
+  const withTier = (info) => {
+    if (!info || !tier) return info;
+    return {
+      ...info,
+      interfaceSource: tier.source,
+      ...tier.display !== void 0 ? { interfaceDisplay: tier.display } : {}
+    };
+  };
   const attachIntension = (info) => {
-    if (!gDisplay) return info;
+    if (!gDisplay) return withTier(info);
     if (!info) {
-      return { typeText: gDisplay, intension: gDisplay, abs: gAbs, absMultiline: gMulti };
+      return withTier({ typeText: gDisplay, intension: gDisplay, abs: gAbs, absMultiline: gMulti });
     }
-    return {
+    return withTier({
       ...info,
       intension: gDisplay,
       // 外延侧已有更准 Abs 时保留；否则用 symbolic 兜底
       abs: info.abs ?? gAbs,
       absMultiline: info.absMultiline ?? gMulti
-    };
+    });
   };
   const insideCaseFn = positionInsideCaseFunction(
     source,
@@ -3333,6 +3793,14 @@ function getHoverAtPosition(filePath, source, line, column, activeCases) {
     }
   } catch {
   }
+  if (tier && gDisplay) {
+    return withTier({
+      typeText: gDisplay,
+      intension: gDisplay,
+      abs: gAbs,
+      absMultiline: gMulti
+    });
+  }
   return null;
 }
 function findIdentNameAtPosition(source, line, column, fileAst) {
@@ -3657,10 +4125,111 @@ function serializeInferJson(result, file) {
 function isNudoTargetPath(path) {
   const lower = path.toLowerCase();
   if (lower.endsWith(".d.ts")) return false;
-  if (lower.endsWith(".nudo.js") || lower.endsWith(".nudo.ts")) return false;
+  if (lower.endsWith(".nudo.js") || lower.endsWith(".nudo.mjs") || lower.endsWith(".nudo.ts") || lower.endsWith(".nudo.draft.js") || lower.endsWith(".nudo.draft.mjs") || lower.endsWith(".nudo.draft.ts")) {
+    return false;
+  }
   return lower.endsWith(".js") || lower.endsWith(".mjs") || lower.endsWith(".ts");
 }
 
+// src/watch-paths.ts
+var PROJECT_CONFIG_BASENAMES = /* @__PURE__ */ new Set([
+  "package.json",
+  "nudo.json",
+  "nudo.config.js",
+  "nudo.config.mjs",
+  "nudo.config.ts",
+  ".nudorc",
+  ".nudorc.json"
+]);
+function isSidecarPath(path) {
+  const lower = path.toLowerCase().replace(/\\/g, "/");
+  if (lower.includes(".nudo.draft.")) return false;
+  return lower.endsWith(".nudo.js") || lower.endsWith(".nudo.mjs") || lower.endsWith(".nudo.ts");
+}
+function isProjectConfigPath(path) {
+  const norm2 = path.replace(/\\/g, "/");
+  if (/\/node_modules\//.test(`/${norm2}`)) return false;
+  const base = norm2.split("/").pop() ?? path;
+  return PROJECT_CONFIG_BASENAMES.has(base.toLowerCase());
+}
+function isWatchRelevantPath(path) {
+  return isNudoTargetPath(path) || isSidecarPath(path) || isProjectConfigPath(path) || isEnvTemplatePath(path);
+}
+function ambientSourcesOfSidecar(sidecarPath) {
+  const norm2 = sidecarPath.replace(/\\/g, "/");
+  const m = norm2.match(/^(.*)\.nudo\.(js|ts)$/i);
+  if (!m || norm2.toLowerCase().includes(".nudo.draft.")) return [];
+  const base = m[1];
+  const ext = m[2].toLowerCase();
+  return ext === "js" ? [`${base}.js`, `${base}.mjs`] : [`${base}.ts`, `${base}.mts`];
+}
+
+// src/analysis-scope.ts
+import { dirname as dirname9 } from "path";
+import { existsSync as existsSync6 } from "fs";
+import { sidecarPathOf } from "@nudojs/core";
+var NOISY_WARNING_CODES = /* @__PURE__ */ new Set([
+  "nudo:unknown-recv",
+  "nudo:builtin-unknown",
+  "nudo:no-signature"
+]);
+function filterDiagnosticsByLevel(diags, level) {
+  if (level === "verbose") return diags;
+  if (level === "off") return [];
+  if (level === "errors") return diags.filter((d) => d.severity === "error");
+  return diags.filter((d) => {
+    if (d.severity === "error") return true;
+    if (d.severity === "info") return false;
+    if (d.severity === "warning" && d.code && NOISY_WARNING_CODES.has(d.code)) return false;
+    return d.severity === "warning";
+  });
+}
+function diagnosticsLevelForFile(filePath) {
+  return analysisConfig(findProjectConfig(dirname9(filePath))?.config).diagnostics;
+}
+function hasNudoDirectives(source) {
+  return /@nudo:(case|mock|pure|skip|sample|refine|interface|import|env|mock-module|as|replace)\b/.test(source);
+}
+function stripCommentsAndStrings(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ").replace(/'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*"|`(?:\\.|[^`\\])*`/g, '""');
+}
+function hasExport(source) {
+  const s = stripCommentsAndStrings(source);
+  return /(^|[\s;}])export\b/.test(s) || /\bmodule\.exports\b/.test(s) || /\bexports\s*[.[]/.test(s) || /Object\.assign\s*\(\s*(module\.)?exports\b/.test(s);
+}
+function shouldAnalyzeFile(filePath, source, config) {
+  if (!isNudoTargetPath(filePath)) return false;
+  const proj = findProjectConfig(dirname9(filePath));
+  const cfg = config ?? analysisConfig(proj?.config);
+  const projectDir = proj?.projectDir;
+  if (cfg.exclude.length > 0 && projectDir) {
+    if (matchesEmitAllowlist(filePath, projectDir, cfg.exclude)) return false;
+  } else if (cfg.exclude.length > 0 && !projectDir) {
+    const norm2 = filePath.replace(/\\/g, "/");
+    if (cfg.exclude.some((p) => simpleExcludeHit(p, norm2))) return false;
+  }
+  if (cfg.include.length > 0 && projectDir) {
+    if (!matchesEmitAllowlist(filePath, projectDir, cfg.include)) return false;
+  }
+  if (cfg.mode === "all") return true;
+  const text = source;
+  if (text !== void 0 && hasNudoDirectives(text)) return true;
+  if (cfg.mode === "directives") return false;
+  if (text !== void 0 && hasExport(text)) return true;
+  try {
+    if (existsSync6(sidecarPathOf(filePath))) return true;
+  } catch {
+  }
+  return false;
+}
+function simpleExcludeHit(pattern, path) {
+  const bare = pattern.replace(/^\*\*/, "").replace(/^\//, "").replace(/\/\*\*$/, "").replace(/^\*\//, "");
+  if (!bare || bare.includes("*")) {
+    return /\/(node_modules|dist|coverage)\//.test("/" + path + "/");
+  }
+  return path.includes(`/${bare}/`) || path.endsWith(`/${bare}`);
+}
+
 // src/session-cache.ts
 import {
   resetGeneralizeMemo,
@@ -3674,10 +4243,12 @@ function evictAnalysisCachesForFiles(files) {
   evictAnalysisFileCacheForFiles(files);
   evictFnAnalysisCacheForFiles(files);
   evictAbsModuleCacheFiles(files);
+  clearPathEnvCaches();
 }
 function clearAnalysisSessionCaches() {
   clearBPathCache();
   clearAbsModuleCache();
+  clearPathEnvCaches();
   resetGeneralizeMemo();
   resetCheckSourceMemo();
   resetNudoModuleExecCache();
@@ -3687,20 +4258,269 @@ function resetAllAnalysisCaches() {
   resetParseSourceCache();
 }
 
+// src/analysis-session.ts
+function createDefaultSession() {
+  return {
+    evictForDependents(files) {
+      evictAnalysisCachesForFiles(files);
+    },
+    clear() {
+      clearAnalysisSessionCaches();
+    },
+    reset() {
+      resetAllAnalysisCaches();
+    },
+    analyze(filePath, source, activeCases, externalCallRecords) {
+      return analyzeFile(
+        filePath,
+        source,
+        activeCases,
+        externalCallRecords
+      );
+    }
+  };
+}
+var defaultSession = void 0;
+function getAnalysisSession() {
+  if (!defaultSession) defaultSession = createDefaultSession();
+  return defaultSession;
+}
+function setAnalysisSession(session) {
+  const prev = defaultSession;
+  defaultSession = session;
+  return prev;
+}
+
+// src/disk-cache.ts
+import { createHash } from "crypto";
+import { createRequire } from "module";
+import { mkdirSync, readFileSync as readFileSync6, writeFileSync, existsSync as existsSync7, rmSync } from "fs";
+import { join as join5, dirname as dirname10, 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-v2+${readServiceVersion()}`;
+function sha256Hex(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
+function relativizePath(p, root) {
+  const norm2 = p.split(sep).join("/");
+  if (!root) return norm2;
+  const r = relative(root, p).split(sep).join("/");
+  if (!r.startsWith("..") && !isAbsolute(r)) return r;
+  return `ext:${createHash("sha256").update(norm2).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 join5(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 (!existsSync7(p)) return void 0;
+      const raw = readFileSync6(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(dirname10(p), { recursive: true });
+      writeFileSync(p, JSON.stringify({ abi: ANALYSIS_ABI, value }), "utf8");
+    } catch {
+    }
+  }
+  clearNamespace() {
+    if (!this.enabled || !this.root) return;
+    try {
+      rmSync(join5(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 ?? "-"}` : "-";
+  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/dep-contents.ts
+import { loadModuleDepsFingerprint as loadModuleDepsFingerprint3 } from "@nudojs/core";
+function collectLoadDepContents(filePath, source, loadModule) {
+  const fp = loadModuleDepsFingerprint3(source, loadModule, filePath);
+  const depContents = fp.contents.length > 0 ? fp.contents : fp.paths.map((path) => ({ path, content: null }));
+  return { depContents, truncated: fp.truncated };
+}
+
 // src/harvest-node.ts
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync8, statSync as statSync6 } from "fs";
+import { join as join6 } from "path";
 import { harvestDts as harvestDts2 } from "@nudojs/harvester";
-function harvestNodeTypes(fromDir, maxFiles = 12, maxMs = 2500) {
+var HARVEST_NODE_DEFAULT_MAX_FILES = 12;
+var HARVEST_NODE_DEFAULT_MAX_MS = 2500;
+var nodeHarvestCache = /* @__PURE__ */ new Map();
+function notFoundCacheKey(fromDir) {
+  return `not-found|@types/node|${fromDir ?? ""}`;
+}
+function nodeHarvestCacheKey(root, maxFiles, maxMs) {
+  let sig = "nostat";
+  try {
+    const st = statSync6(join6(root, "package.json"));
+    sig = `${st.size}:${Math.floor(st.mtimeMs)}`;
+  } catch {
+  }
+  return `${root}|${maxFiles}|${maxMs}|${sig}`;
+}
+function clearNodeHarvestCache() {
+  nodeHarvestCache.clear();
+}
+function getNodeHarvestCacheSize() {
+  return nodeHarvestCache.size;
+}
+function isHarvestNodeDisabled(env = process.env) {
+  return env.NUDO_HARVEST_NODE === "off";
+}
+function harvestNodeTypes(fromDir, maxFiles = HARVEST_NODE_DEFAULT_MAX_FILES, maxMs = HARVEST_NODE_DEFAULT_MAX_MS) {
+  if (isHarvestNodeDisabled()) {
+    return {
+      ok: false,
+      error: "harvest disabled via NUDO_HARVEST_NODE=off",
+      reason: "disabled"
+    };
+  }
   const root = resolvePackageRoot("@types/node", fromDir) ?? resolvePackageRoot("node", fromDir);
-  if (!root || !existsSync5(root)) {
-    return { ok: false, error: "@types/node not found" };
+  if (!root || !existsSync8(root)) {
+    const missKey = notFoundCacheKey(fromDir);
+    const miss = nodeHarvestCache.get(missKey);
+    if (miss && !miss.ok && miss.reason === "not-found") {
+      return { ...miss, cached: true };
+    }
+    const result = {
+      ok: false,
+      error: "@types/node not found",
+      reason: "not-found"
+    };
+    nodeHarvestCache.set(missKey, result);
+    return result;
+  }
+  const key = nodeHarvestCacheKey(root, maxFiles, maxMs);
+  const hit = nodeHarvestCache.get(key);
+  if (hit) {
+    return hit.ok ? { ...hit, cached: true } : { ...hit, cached: true };
   }
   const dts = collectDtsFiles(root, maxFiles);
   if (dts.length === 0) {
-    return { ok: false, error: `no .d.ts under ${root}` };
+    const result = {
+      ok: false,
+      error: `no .d.ts under ${root}`,
+      reason: "no-dts"
+    };
+    nodeHarvestCache.set(key, result);
+    return result;
+  }
+  try {
+    const env = harvestDts2(dts, { maxMs });
+    const stats = {
+      files: env.stats.files,
+      symbols: env.stats.symbols,
+      skipped: env.stats.skipped
+    };
+    const result = {
+      ok: true,
+      env,
+      root,
+      files: stats.files,
+      stats,
+      cached: false
+    };
+    nodeHarvestCache.set(key, result);
+    return result;
+  } catch (e) {
+    const result = {
+      ok: false,
+      error: `harvest failed: ${e.message}`,
+      reason: "failed"
+    };
+    nodeHarvestCache.set(key, result);
+    return result;
   }
-  const env = harvestDts2(dts, { maxMs });
-  return { ok: true, env, root, files: env.stats.files };
 }
 function summarizeNodeEnv(env) {
   return {
@@ -3712,6 +4532,9 @@ function summarizeNodeEnv(env) {
 
 // src/semantic-tokens.ts
 import { parse as parse7 } from "@nudojs/parser";
+import {
+  interfaceTierOf as interfaceTierOf2
+} from "@nudojs/core";
 var SEMANTIC_TOKEN_TYPES = [
   "function",
   "variable",
@@ -3729,7 +4552,13 @@ var SEMANTIC_TOKEN_MODIFIERS = [
   "declaration",
   "readonly",
   "deprecated",
-  "unreachable"
+  "unreachable",
+  /** handwritten：显式契约（侧车手写 / @nudo:refine） */
+  "contract",
+  /** generated：侧车 @generated 段 */
+  "generated",
+  /** derived：implicit 展示档（非义务契约） */
+  "derived"
 ];
 function encodeSemanticTokens(tokens) {
   const result = [];
@@ -3750,6 +4579,12 @@ var TYPE_PARAMETER = SEMANTIC_TOKEN_TYPES.indexOf("parameter");
 var TYPE_PROPERTY = SEMANTIC_TOKEN_TYPES.indexOf("property");
 var TYPE_METHOD = SEMANTIC_TOKEN_TYPES.indexOf("method");
 var MOD_DECLARATION = 1 << SEMANTIC_TOKEN_MODIFIERS.indexOf("declaration");
+var MOD_CONTRACT = 1 << SEMANTIC_TOKEN_MODIFIERS.indexOf("contract");
+var MOD_GENERATED = 1 << SEMANTIC_TOKEN_MODIFIERS.indexOf("generated");
+var MOD_DERIVED = 1 << SEMANTIC_TOKEN_MODIFIERS.indexOf("derived");
+function interfaceTierModifierBit(src) {
+  return src === "handwritten" ? MOD_CONTRACT : src === "generated" ? MOD_GENERATED : MOD_DERIVED;
+}
 function collectFunctionBindingNames(filePath, source, _ast) {
   try {
     const binds = collectAbsBindingsFromGraph(source, filePath);
@@ -3764,7 +4599,7 @@ function collectFunctionBindingNames(filePath, source, _ast) {
   }
   return /* @__PURE__ */ new Set();
 }
-function buildSemanticTokens(filePath, source) {
+function buildSemanticTokens(filePath, source, opts) {
   let ast;
   try {
     ast = parse7(source);
@@ -3774,6 +4609,7 @@ function buildSemanticTokens(filePath, source) {
   const functionNames = collectFunctionBindingNames(filePath, source, ast);
   const program = ast.program ?? ast;
   const topLevelDeclarators = /* @__PURE__ */ new Set();
+  const topLevelFnDeclNodes = /* @__PURE__ */ new Set();
   for (const stmt of program.body ?? []) {
     const decl = stmt.type === "ExportNamedDeclaration" || stmt.type === "ExportDefaultDeclaration" ? stmt.declaration ?? null : stmt;
     if (decl && decl.type === "VariableDeclaration") {
@@ -3781,9 +4617,30 @@ function buildSemanticTokens(filePath, source) {
         topLevelDeclarators.add(d);
       }
     }
+    if (decl && decl.type === "FunctionDeclaration" && decl.id) {
+      topLevelFnDeclNodes.add(decl);
+    }
   }
+  const tierOpts = {
+    ...opts?.loadModule ? { loadModule: opts.loadModule } : {},
+    ...opts?.autoBind !== void 0 ? { autoBind: opts.autoBind } : {}
+  };
+  const tierModCache = /* @__PURE__ */ new Map();
+  const tierModFor = (name) => {
+    const cached = tierModCache.get(name);
+    if (cached !== void 0) return cached;
+    let bit = 0;
+    try {
+      const tier = interfaceTierOf2(source, name, filePath, tierOpts);
+      if (tier) bit = interfaceTierModifierBit(tier.source);
+    } catch {
+      bit = 0;
+    }
+    tierModCache.set(name, bit);
+    return bit;
+  };
   const tokens = [];
-  const pushIdentifier = (id, typeIndex) => {
+  const pushIdentifier = (id, typeIndex, extraMod = 0) => {
     const loc = id.loc;
     const name = id.name;
     if (!loc || typeof name !== "string") return;
@@ -3792,7 +4649,7 @@ function buildSemanticTokens(filePath, source) {
       char: loc.start.column,
       length: name.length,
       typeIndex,
-      modifierBitmask: MOD_DECLARATION
+      modifierBitmask: MOD_DECLARATION | extraMod
     });
   };
   const collectParams = (params) => {
@@ -3815,15 +4672,23 @@ function buildSemanticTokens(filePath, source) {
         const id = n.id;
         if (id?.type === "Identifier") {
           const isTopLevel = topLevelDeclarators.has(node);
-          const typeIndex = isTopLevel && isFunctionValue(id.name) ? TYPE_FUNCTION : TYPE_VARIABLE;
-          pushIdentifier(id, typeIndex);
+          const name = id.name;
+          const isFn = isTopLevel && isFunctionValue(name);
+          const typeIndex = isFn ? TYPE_FUNCTION : TYPE_VARIABLE;
+          const extraMod = isFn ? tierModFor(name) : 0;
+          pushIdentifier(id, typeIndex, extraMod);
         }
         break;
       }
       case "FunctionDeclaration":
       case "FunctionExpression": {
         const id = n.id;
-        if (id?.type === "Identifier") pushIdentifier(id, TYPE_FUNCTION);
+        if (id?.type === "Identifier") {
+          const name = id.name;
+          const isTopLevelFnDecl = n.type === "FunctionDeclaration" && topLevelFnDeclNodes.has(node);
+          const extraMod = isTopLevelFnDecl ? tierModFor(name) : 0;
+          pushIdentifier(id, TYPE_FUNCTION, extraMod);
+        }
         collectParams(n.params ?? []);
         break;
       }
@@ -3871,14 +4736,102 @@ import {
   litValue as litValue3,
   abs as makeAbs2,
   isTemplateLike,
-  templatePartsOf
+  templatePartsOf,
+  collectAbsFreeVars
 } from "@nudojs/core";
-function wrapComplexAbs(a) {
-  const ts = absToTSType(a);
-  if (a.shape.k === "sum") return `(${ts})`;
+function tsTypeParamName(id) {
+  let n = id.replace(/[^A-Za-z0-9_$]/g, "_");
+  if (!/^[A-Za-z_$]/.test(n)) n = `T_${n}`;
+  if (n.length === 0) n = "T";
+  return n;
+}
+function wrapComplexAbs(a, typeVars) {
+  const ts = absToTSType(a, typeVars);
+  if (a.shape.k === "sum" || a.shape.k === "fn") return `(${ts})`;
   return ts;
 }
-function absToTSType(a) {
+function wrapUnionMember(a, typeVars) {
+  const ts = absToTSType(a, typeVars);
+  if (a.shape.k === "fn") return `(${ts})`;
+  return ts;
+}
+var TS_PARAM_RESERVED = /* @__PURE__ */ new Set([
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "import",
+  "in",
+  "instanceof",
+  "new",
+  "null",
+  "return",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield",
+  "let",
+  "static",
+  "await",
+  "implements",
+  "interface",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "arguments",
+  "eval",
+  "constructor"
+]);
+function isTsIdent(name) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) && !TS_PARAM_RESERVED.has(name);
+}
+function sanitizeParamName(name, index) {
+  if (name.startsWith("...")) {
+    const rest = name.slice(3);
+    if (isTsIdent(rest)) return name;
+    return `...arg${index}`;
+  }
+  if (isTsIdent(name)) return name;
+  return `arg${index}`;
+}
+function formatPropKey(k) {
+  if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k)) return k;
+  if (/^\d+$/.test(k)) return k;
+  return JSON.stringify(k);
+}
+function absToTSType(a, typeVars) {
+  if (a.shape.k === "any" && a.term?.op === "var" && typeVars) {
+    const mapped = typeVars.get(a.term.id);
+    if (mapped) return mapped;
+  }
+  if (a.shape.k === "arr" && a.shape.element.shape.k === "any" && a.shape.element.term?.op === "var" && typeVars) {
+    const mapped = typeVars.get(a.shape.element.term.id);
+    if (mapped) return `${mapped}[]`;
+  }
   if (a.term?.op === "lit") {
     const v = a.term.value;
     if (v === null) return "null";
@@ -3894,7 +4847,7 @@ function absToTSType(a) {
     const inner = parts.map((p) => {
       const lv = litValue3(p);
       if (typeof lv === "string") return lv;
-      return `\${${absToTSType(p)}}`;
+      return `\${${absToTSType(p, typeVars)}}`;
     }).join("");
     return `\`${inner}\``;
   }
@@ -3908,34 +4861,50 @@ function absToTSType(a) {
       return a.shape.type;
     case "obj": {
       const entries = Object.entries(a.shape.slots).map(([k, slot]) => {
-        const inner = absToTSType(slot.value);
+        const inner = absToTSType(slot.value, typeVars);
         if (slot.optional) {
-          const t = slot.value.shape.k === "sum" ? `(${inner})` : inner;
-          return `${k}: ${t} | undefined`;
+          const t = wrapComplexAbs(slot.value, typeVars);
+          return `${formatPropKey(k)}: ${t} | undefined`;
         }
-        return `${k}: ${inner}`;
+        return `${formatPropKey(k)}: ${inner}`;
       });
       if (entries.length === 0) return "{}";
       return `{ ${entries.join("; ")} }`;
     }
     case "arr":
-      return `${wrapComplexAbs(a.shape.element)}[]`;
+      return `${wrapComplexAbs(a.shape.element, typeVars)}[]`;
     case "tuple": {
-      const inner = a.shape.elements.map(absToTSType).join(", ");
-      return `[${inner}]`;
+      const parts = a.shape.elements.map((e) => absToTSType(e, typeVars));
+      if (a.shape.rest) {
+        const rest = a.shape.rest;
+        const restTs = rest.shape.k === "arr" ? absToTSType(rest, typeVars) : `${absToTSType(rest, typeVars)}[]`;
+        parts.push(`...${restTs}`);
+      }
+      return `[${parts.join(", ")}]`;
     }
     case "fn": {
-      const params = a.shape.params.map((p) => `${p}: unknown`).join(", ");
-      const ret = a.shape.returnType ? absToTSType(a.shape.returnType) : "unknown";
+      const paramTypes = a.shape.paramTypes;
+      const params = a.shape.params.map((p, i) => {
+        const isRest = p.startsWith("...");
+        const name = sanitizeParamName(p, i);
+        const pt = paramTypes?.[i];
+        let typeStr;
+        if (pt) typeStr = absToTSType(pt, typeVars);
+        else if (isRest) typeStr = "unknown[]";
+        else typeStr = "unknown";
+        return `${name}: ${typeStr}`;
+      }).join(", ");
+      const ret = a.shape.returnType ? absToTSType(a.shape.returnType, typeVars) : "unknown";
       return `(${params}) => ${ret}`;
     }
     case "brand":
-      return a.shape.name;
+      return isTsIdent(a.shape.name) || /^[A-Z][A-Za-z0-9_$]*$/.test(a.shape.name) ? a.shape.name : "unknown";
     case "eff":
-      if (a.shape.eff === "promise") return `Promise<${absToTSType(a.shape.inner)}>`;
-      return absToTSType(a.shape.inner);
+      if (a.shape.eff === "promise")
+        return `Promise<${absToTSType(a.shape.inner, typeVars)}>`;
+      return absToTSType(a.shape.inner, typeVars);
     case "sum": {
-      const parts = a.shape.members.map(absToTSType).filter((p) => p !== "never");
+      const parts = a.shape.members.map((m) => wrapUnionMember(m, typeVars)).filter((p) => p !== "never");
       const uniq = [...new Set(parts)];
       if (uniq.length === 0) return "never";
       if (uniq.length === 1) return uniq[0];
@@ -4067,13 +5036,18 @@ function computeMainSignature(fn) {
     }
     const typeStr = paramTypeFromAbs(members);
     let name = getParamName(fn, i);
+    const isRest = name.startsWith("...");
+    const bare = isRest ? name.slice(3) : name;
+    if (!isTsIdent(bare)) {
+      name = isRest ? `...arg${i}` : `arg${i}`;
+    }
     if (usedNames.has(name)) {
       let n = 2;
       while (usedNames.has(`${name}${n}`)) n++;
       name = `${name}${n}`;
     }
     usedNames.add(name);
-    const optional = i >= minArity && !name.startsWith("...");
+    const optional = i >= minArity && !isRest;
     params.push(optional ? `${name}?: ${typeStr}` : `${name}: ${typeStr}`);
     paramNames.push(name);
     paramTypes.push(typeStr);
@@ -4088,7 +5062,7 @@ function generateJSDoc(fn, sig) {
   for (const c of fn.cases) {
     const preciseDiffers = c.argAbs.length !== sig.paramTypes.length || c.argAbs.some((a, i) => absToTSType(a) !== sig.paramTypes[i]) || absToTSType(c.abs) !== sig.returnType;
     if (!preciseDiffers) continue;
-    const argsStr = c.argAbs.map(absToTSType).join(", ");
+    const argsStr = c.argAbs.map((a) => absToTSType(a)).join(", ");
     lines.push(` * Case: ${c.name} (${argsStr}) => ${absToTSType(c.abs)}`);
   }
   for (let i = 0; i < sig.paramTypes.length; i++) {
@@ -4098,8 +5072,103 @@ function generateJSDoc(fn, sig) {
   lines.push(" */");
   return lines.join("\n");
 }
+function computeHofSignature(fn) {
+  const hof = fn.hof;
+  if (!hof) return void 0;
+  const byParam = /* @__PURE__ */ new Map();
+  for (const s of hof.entryShapes ?? []) byParam.set(s.param, s.abs);
+  for (const r of hof.fnRels ?? []) byParam.set(r.param, r.abs);
+  if (byParam.size === 0 && !hof.symbolic) return void 0;
+  if (fn.cases.length > 0) {
+    for (const [param] of byParam) {
+      const idx = fn.paramNames.indexOf(param);
+      if (idx < 0) continue;
+      const caseType = paramTypeFromAbs(
+        fn.cases.map((c) => c.argAbs[idx]).filter((a) => !!a)
+      );
+      if (caseType !== "unknown" && caseType !== "unknown[]") {
+        return void 0;
+      }
+    }
+  }
+  const arity = Math.max(
+    fn.paramNames.length,
+    ...[...byParam.keys()].map((p) => fn.paramNames.indexOf(p) + 1),
+    0
+  );
+  if (arity === 0 && !hof.symbolic) return void 0;
+  const free = /* @__PURE__ */ new Set();
+  for (const a of byParam.values()) {
+    for (const id of collectAbsFreeVars(a)) free.add(id);
+  }
+  const retAbs = hof.symbolic ?? fn.combinedAbs;
+  if (retAbs) {
+    for (const id of collectAbsFreeVars(retAbs)) free.add(id);
+  }
+  if (free.size === 0) return void 0;
+  const typeVars = /* @__PURE__ */ new Map();
+  const used = /* @__PURE__ */ new Set();
+  const typeParams = [];
+  for (const id of [...free].sort()) {
+    let n = tsTypeParamName(id);
+    if (used.has(n) || TS_PARAM_RESERVED.has(n)) {
+      let i = 2;
+      while (used.has(`${n}${i}`)) i++;
+      n = `${n}${i}`;
+    }
+    used.add(n);
+    typeVars.set(id, n);
+    typeParams.push(n);
+  }
+  const params = [];
+  const paramNames = [];
+  const paramTypes = [];
+  const usedNames = /* @__PURE__ */ new Set();
+  for (let i = 0; i < arity; i++) {
+    const rawName = getParamName(fn, i);
+    const isRest = rawName.startsWith("...");
+    let name = sanitizeParamName(rawName, i);
+    if (usedNames.has(name)) {
+      let n = 2;
+      while (usedNames.has(`${name}${n}`)) n++;
+      name = isRest && name.startsWith("...") ? `...${name.slice(3)}${n}` : `${name}${n}`;
+    }
+    usedNames.add(name);
+    const promoted = byParam.get(fn.paramNames[i] ?? rawName) ?? byParam.get(rawName);
+    const typeStr = promoted ? absToTSType(promoted, typeVars) : isRest ? "unknown[]" : "unknown";
+    params.push(`${name}: ${typeStr}`);
+    paramNames.push(name);
+    paramTypes.push(typeStr);
+  }
+  const returnType = retAbs ? absToTSType(retAbs, typeVars) : "unknown";
+  return { typeParams, params, paramNames, paramTypes, returnType };
+}
 function generateFunctionDtsLines(fn) {
-  if (fn.noDeclaration) return [];
+  let emitFn = fn;
+  if (fn.noDeclaration) {
+    const m = /^([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)$/.exec(fn.name);
+    if (!m) return [];
+    emitFn = { ...fn, name: `${m[1]}_${m[2]}`, noDeclaration: false };
+  }
+  fn = emitFn;
+  const hofSig = computeHofSignature(fn);
+  if (hofSig) {
+    const lines2 = [];
+    if (fn.cases.length > 0) {
+      const jsdoc2 = generateJSDoc(fn, {
+        params: hofSig.params,
+        paramNames: hofSig.paramNames,
+        paramTypes: hofSig.paramTypes,
+        returnType: hofSig.returnType
+      });
+      if (jsdoc2) lines2.push(jsdoc2);
+    }
+    const tparams = hofSig.typeParams.length > 0 ? `<${hofSig.typeParams.join(", ")}>` : "";
+    lines2.push(
+      `export declare function ${fn.name}${tparams}(${hofSig.params.join(", ")}): ${hofSig.returnType};`
+    );
+    return lines2;
+  }
   if (fn.cases.length === 0) {
     const retAbs = fn.combinedAbs;
     if (retAbs) {
@@ -4108,7 +5177,6 @@ function generateFunctionDtsLines(fn) {
       ];
     }
     return [];
-    return [];
   }
   const sig = computeMainSignature(fn);
   const jsdoc = generateJSDoc(fn, sig);
@@ -4539,8 +5607,8 @@ function unifiedDiff(a, b, path) {
 }
 
 // src/interface-surface.ts
-import { readFileSync as readFileSync6 } from "fs";
-import { dirname as dirname8, resolve as resolve6 } from "path";
+import { readFileSync as readFileSync7, existsSync as existsSync9 } from "fs";
+import { dirname as dirname11, resolve as resolve7 } from "path";
 import {
   effectiveInterface,
   formatConstraint,
@@ -4548,9 +5616,13 @@ import {
   interfaceDiagCount,
   localNamedExports,
   refineDiagCount,
+  sidecarPathOf as sidecarPathOf2,
   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}`;
@@ -4565,19 +5637,92 @@ function absToImplicitDisplay(a) {
     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 = resolve6(filePath);
-  const source = readFileSync6(abs, "utf-8");
+  const abs = resolve7(filePath);
+  const source = opts.source ?? readFileSync7(abs, "utf-8");
+  const fromBuffer = opts.source !== void 0;
   const ifaceSince = interfaceDiagCount();
   const refineSince = refineDiagCount();
-  const autoBind = opts.autoBind ?? interfaceConfig(findProjectConfig(dirname8(abs))?.config).autoBind;
+  const proj = findProjectConfig(dirname11(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);
+  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 = sidecarPathOf2(abs);
+        if (autoBind !== false) {
+          const openSc = loadModule(`./${sc.slice(sc.lastIndexOf("/") + 1)}`, abs);
+          if (openSc !== void 0) sidecarSource = openSc;
+          else if (existsSync9(sc)) sidecarSource = readFileSync7(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) {
-    const eff = effectiveInterface(source, fn.name, { loadModule, fromFile: abs, autoBind });
+    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 });
+      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,
@@ -4608,14 +5753,20 @@ async function interfaceSurface(filePath, opts = {}) {
     }
     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 existsSync6, readFileSync as readFileSync7, writeFileSync, renameSync, unlinkSync } from "fs";
-import { basename as basename2, dirname as dirname9, relative, resolve as resolve7 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync8, writeFileSync as writeFileSync2, renameSync, unlinkSync } from "fs";
+import { basename as basename2, dirname as dirname12, relative as relative2, resolve as resolve8 } from "path";
 import {
   execNudoModule,
   formatConstraint as formatConstraint2,
@@ -4626,20 +5777,20 @@ import {
   localNamedExports as localNamedExports2,
   parseSource as parseSource2,
   refineDiagCount as refineDiagCount2,
-  sidecarPathOf,
+  sidecarPathOf as sidecarPathOf3,
   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 interface --emit`";
 async function emitInterface(filePath, opts) {
-  const abs = resolve7(filePath);
-  if (isNodeModulesPath(abs) || isNodeModulesPath(sidecarPathOf(abs))) {
+  const abs = resolve8(filePath);
+  if (isNodeModulesPath(abs) || isNodeModulesPath(sidecarPathOf3(abs))) {
     throw new Error(
       `emit target '${abs}' is inside node_modules; contract sidecars are never written there`
     );
   }
-  const proj = findProjectConfig(dirname9(abs));
+  const proj = findProjectConfig(dirname12(abs));
   const allow = interfaceConfig(proj?.config).emit;
   if (!matchesEmitAllowlist(abs, proj?.projectDir, allow)) {
     return {
@@ -4650,28 +5801,34 @@ async function emitInterface(filePath, opts) {
         {
           code: "nudo:interface-emit-denied",
           severity: "warning",
-          message: `emit target '${relative(process.cwd(), abs) || abs}' is outside package.json#nudo.interface.emit allowlist`
+          message: `emit target '${relative2(process.cwd(), abs) || abs}' is outside package.json#nudo.interface.emit allowlist`
         }
       ],
-      sidecarPath: sidecarPathOf(abs)
+      sidecarPath: sidecarPathOf3(abs)
     };
   }
-  const source = readFileSync7(abs, "utf-8");
+  const source = opts.source ?? readFileSync8(abs, "utf-8");
   const ifaceSince = interfaceDiagCount2();
   const refineSince = refineDiagCount2();
-  const sidecarPath = sidecarPathOf(abs);
-  const sidecarSrc = existsSync6(sidecarPath) ? readFileSync7(sidecarPath, "utf-8") : "";
-  const srcRel = relative(dirname9(sidecarPath), abs) || basename2(abs);
+  const sidecarPath = sidecarPathOf3(abs);
+  const sidecarSrc = existsSync10(sidecarPath) ? readFileSync8(sidecarPath, "utf-8") : "";
+  const srcRel = relative2(dirname12(sidecarPath), abs) || basename2(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 '${relative(process.cwd(), sidecarPath) || sidecarPath}' is not parseable; fix it before emitting`
+      `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);
+  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) {
@@ -4774,15 +5931,15 @@ async function emitInterface(filePath, opts) {
     finalContent = joinSections(base, [...preserved, ...accepted.map((a) => a.text)]);
   }
   const changed = finalContent !== sidecarSrc;
-  const diff = changed ? unifiedDiff(sidecarSrc, finalContent, relative(process.cwd(), sidecarPath) || sidecarPath) : void 0;
+  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 {
-      writeFileSync(tmp, finalContent, "utf-8");
+      writeFileSync2(tmp, finalContent, "utf-8");
       renameSync(tmp, sidecarPath);
     } catch (e) {
       try {
-        if (existsSync6(tmp)) unlinkSync(tmp);
+        if (existsSync10(tmp)) unlinkSync(tmp);
       } catch {
       }
       throw e;
@@ -4972,29 +6129,638 @@ function joinSections(base, sectionTexts) {
   return lead + normalized.join("\n");
 }
 
-// src/interface-derivation.ts
-import { existsSync as existsSync7, readFileSync as readFileSync8, renameSync as renameSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "fs";
-import { basename as basename3, dirname as dirname10, relative as relative2, resolve as resolve8 } from "path";
+// src/interface-draft.ts
+import { existsSync as existsSync11, readFileSync as readFileSync9, writeFileSync as writeFileSync3, realpathSync as realpathSync2 } from "fs";
+import { basename as basename3, dirname as dirname13, isAbsolute as isAbsolute2, join as join7, relative as relative3 } from "path";
+import {
+  effectiveInterface as effectiveInterface2,
+  formatConstraint as formatConstraint3,
+  formatShape as formatShape6,
+  generalizeFromAst as generalizeFromAst4,
+  isIntFlag,
+  joinThenProject as joinThenProject2,
+  localNamedExports as localNamedExports3,
+  sidecarPathOf as sidecarPathOf4
+} from "@nudojs/core";
 import { parse as parse9 } from "@nudojs/parser";
+function collectParamBodyAccesses(source) {
+  const out = /* @__PURE__ */ new Map();
+  let ast;
+  try {
+    ast = parse9(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) => formatShape6(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 ? formatShape6(fn.combinedAbs) : formatShape6(retAbs[0]);
+    return {
+      display: `/* not projectable: ${shapeText} */`,
+      projected: false,
+      evidence: rawEvidence
+    };
+  }
+  try {
+    const g = generalizeFromAst4(fn.name, source, {
+      refine: {
+        ...loadModule ? { loadModule } : {},
+        ...fromFile ? { fromFile } : {}
+      }
+    });
+    if (g?.symbolic) {
+      return {
+        display: `/* symbolic: ${formatShape6(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 ?? readFileSync9(filePath, "utf-8");
+  const loadModule = opts.loadModule ?? defaultLoadModule;
+  const sidecarPath = sidecarPathOf4(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 ?? sidecarPathOf4(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 interface --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 sidecarPathOf4(filePath).replace(/\.nudo\.([cm]?[jt]s)$/, ".nudo.draft.$1");
+}
+function safeRealpath(p) {
+  try {
+    return realpathSync2(p);
+  } catch {
+    try {
+      return join7(realpathSync2(dirname13(p)), basename3(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 = sidecarPathOf4(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 = existsSync11(draftPath) ? readFileSync9(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 ${sidecarPathOf4(result.file)}`);
+  } else {
+    lines.push("");
+    lines.push(result.draftSource.trimEnd());
+  }
+  return lines;
+}
+
+// src/interface-derivation.ts
+import { existsSync as existsSync12, readFileSync as readFileSync10, renameSync as renameSync2, unlinkSync as unlinkSync2, writeFileSync as writeFileSync4 } from "fs";
+import { basename as basename4, dirname as dirname14, relative as relative4, resolve as resolve9 } from "path";
+import { parse as parse10 } from "@nudojs/parser";
 import {
   analyzeFn,
   beginDerivationSession,
   constraintToEntryAbs,
   derivationChain,
-  effectiveInterface as effectiveInterface2,
+  effectiveInterface as effectiveInterface3,
   endDerivationSession,
   execNudoModule as execNudoModule2,
-  formatConstraint as formatConstraint3,
+  formatConstraint as formatConstraint4,
   getDerivation,
   interfaceDiagCount as interfaceDiagCount3,
   isNodeModulesPath as isNodeModulesPath2,
   isNudoConstraint as isNudoConstraint2,
-  joinThenProject as joinThenProject2,
+  joinThenProject as joinThenProject3,
   parseSource as parseSource3,
   projectDerivationDsl,
   refineDiagCount as refineDiagCount3,
   setAbsCallCollector as setAbsCallCollector2,
-  sidecarPathOf as sidecarPathOf2,
+  sidecarPathOf as sidecarPathOf5,
   tagDerivationRoot,
   takeInterfaceDiagsSince as takeInterfaceDiagsSince3,
   takeRefineDiagsSince as takeRefineDiagsSince3,
@@ -5004,7 +6770,7 @@ function extractFnConstraintSources(sidecarSrc, fnName) {
   const out = { params: {} };
   let ast;
   try {
-    ast = parse9(sidecarSrc);
+    ast = parse10(sidecarSrc);
   } catch {
     return out;
   }
@@ -5075,7 +6841,7 @@ function extractFnConstraintSources(sidecarSrc, fnName) {
 }
 function functionParamNames(source, fnName) {
   try {
-    const ast = parse9(source);
+    const ast = parse10(source);
     for (const stmt of ast.program.body) {
       const d = stmt.type === "ExportNamedDeclaration" ? stmt.declaration ?? void 0 : stmt;
       if (!d) continue;
@@ -5104,7 +6870,7 @@ function paramNameOf(p) {
 function topLevelFnNames(source) {
   const out = [];
   try {
-    const ast = parse9(source);
+    const ast = parse10(source);
     for (const stmt of ast.program.body) {
       const d = stmt.type === "ExportNamedDeclaration" ? stmt.declaration ?? void 0 : stmt;
       if (!d) continue;
@@ -5124,16 +6890,16 @@ function topLevelFnNames(source) {
 function importLocalMap(source, fromFile) {
   const out = /* @__PURE__ */ new Map();
   try {
-    const ast = parse9(source);
-    const base = dirname10(resolve8(fromFile));
+    const ast = parse10(source);
+    const base = dirname14(resolve9(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 = resolve8(base, spec);
+      const raw = resolve9(base, spec);
       let modulePath = null;
       for (const cand of [raw, `${raw}.js`, `${raw}.ts`, `${raw}.mjs`]) {
-        if (existsSync7(cand)) {
+        if (existsSync12(cand)) {
           modulePath = cand;
           break;
         }
@@ -5151,14 +6917,14 @@ function importLocalMap(source, fromFile) {
   return out;
 }
 function resolveRelImport(fromSpec, fromDir, targetDir) {
-  const abs = resolve8(fromDir, fromSpec);
-  let rel = relative2(targetDir, abs);
+  const abs = resolve9(fromDir, fromSpec);
+  let rel = relative4(targetDir, abs);
   if (!rel.startsWith(".")) rel = `./${rel}`;
   return rel.split("\\").join("/");
 }
 function projectParamSlot(absList, paramName) {
   if (absList.length === 0) return void 0;
-  const constraint = joinThenProject2(absList);
+  const constraint = joinThenProject3(absList);
   if (constraint === void 0) return void 0;
   if (absList.length === 1) {
     const node = getDerivation(absList[0]);
@@ -5182,7 +6948,7 @@ function projectParamSlot(absList, paramName) {
   }
   return {
     constraint,
-    dsl: formatConstraint3(constraint),
+    dsl: formatConstraint4(constraint),
     prelude: [],
     imports: [],
     compositional: false
@@ -5190,7 +6956,7 @@ function projectParamSlot(absList, paramName) {
 }
 function projectReturnSlot(retAbs, params, paramNames) {
   if (retAbs.length === 0) return void 0;
-  const constraint = joinThenProject2(retAbs);
+  const constraint = joinThenProject3(retAbs);
   if (constraint === void 0) return void 0;
   if (retAbs.length === 1) {
     const node = getDerivation(retAbs[0]);
@@ -5219,7 +6985,7 @@ function projectReturnSlot(retAbs, params, paramNames) {
   }
   return {
     constraint,
-    dsl: formatConstraint3(constraint),
+    dsl: formatConstraint4(constraint),
     prelude: [],
     imports: [],
     compositional: false
@@ -5251,18 +7017,18 @@ function projectReturnRelativeToParams(node, params, paramNames) {
   return void 0;
 }
 function deriveFromRoot(filePath, opts = {}) {
-  const abs = resolve8(filePath);
-  const source = readFileSync8(abs, "utf-8");
+  const abs = resolve9(filePath);
+  const source = readFileSync10(abs, "utf-8");
   const since = interfaceDiagCount3();
-  const autoBind = opts.autoBind ?? interfaceConfig(findProjectConfig(dirname10(abs))?.config).autoBind;
+  const autoBind = opts.autoBind ?? interfaceConfig(findProjectConfig(dirname14(abs))?.config).autoBind;
   const loadModule = opts.loadModule ?? defaultLoadModule;
-  const sidecarPath = sidecarPathOf2(abs);
-  const sidecarSrc = existsSync7(sidecarPath) && !isNodeModulesPath2(sidecarPath) ? readFileSync8(sidecarPath, "utf-8") : "";
+  const sidecarPath = sidecarPathOf5(abs);
+  const sidecarSrc = existsSync12(sidecarPath) && !isNodeModulesPath2(sidecarPath) ? readFileSync10(sidecarPath, "utf-8") : "";
   const fnNames = topLevelFnNames(source);
   const roots = [];
   const plans = [];
   for (const fn of fnNames) {
-    const eff = effectiveInterface2(source, fn, { loadModule, fromFile: abs, autoBind });
+    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: {} };
@@ -5298,8 +7064,8 @@ function deriveFromRoot(filePath, opts = {}) {
   const wanted = opts.fnNames && opts.fnNames.length > 0 ? new Set(opts.fnNames) : void 0;
   const derived = [];
   for (const plan of plans) {
-    const relRoot = relative2(process.cwd(), abs);
-    const label = `${relRoot === "" || relRoot.startsWith("..") ? basename3(abs) : relRoot}:${plan.fnName}`;
+    const relRoot = relative4(process.cwd(), abs);
+    const label = `${relRoot === "" || relRoot.startsWith("..") ? basename4(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;
@@ -5346,7 +7112,7 @@ function deriveOneRoot(plan, source, file, modules, importLocals, label) {
         targetFile = file;
       }
       if (isNodeModulesPath2(targetFile)) continue;
-      if (!existsSync7(targetFile)) continue;
+      if (!existsSync12(targetFile)) continue;
       const key = `${targetFile}::${targetExport}`;
       let agg = byCallee.get(key);
       if (!agg) {
@@ -5360,7 +7126,7 @@ function deriveOneRoot(plan, source, file, modules, importLocals, label) {
     for (const agg of byCallee.values()) {
       let targetSource;
       try {
-        targetSource = readFileSync8(agg.targetFile, "utf-8");
+        targetSource = readFileSync10(agg.targetFile, "utf-8");
       } catch {
         continue;
       }
@@ -5597,7 +7363,7 @@ function sidecarAssembles(text, fromFile, loadModule) {
   }
 }
 function emitDerivedFromRoot(rootFile, opts) {
-  const abs = resolve8(rootFile);
+  const abs = resolve9(rootFile);
   const derive = deriveFromRoot(abs, {
     ...opts.loadModule ? { loadModule: opts.loadModule } : {},
     ...opts.autoBind !== void 0 ? { autoBind: opts.autoBind } : {},
@@ -5606,10 +7372,10 @@ function emitDerivedFromRoot(rootFile, opts) {
   if (!derive.hasRoot) {
     return { sidecars: [], hasRoot: false, roots: [], entryOnly: true };
   }
-  const proj = findProjectConfig(dirname10(abs));
+  const proj = findProjectConfig(dirname14(abs));
   const allow = interfaceConfig(proj?.config).emit;
   const projectDir = proj?.projectDir;
-  const rootSidecarDir = dirname10(sidecarPathOf2(abs));
+  const rootSidecarDir = dirname14(sidecarPathOf5(abs));
   const wanted = opts.fnNames && opts.fnNames.length > 0 ? new Set(opts.fnNames) : void 0;
   const result = {
     sidecars: [],
@@ -5620,7 +7386,7 @@ function emitDerivedFromRoot(rootFile, opts) {
   for (const row of derive.derived) {
     if (wanted && !wanted.has(row.fn)) continue;
     if (!matchesEmitAllowlist(row.file, projectDir, allow)) continue;
-    const sp = sidecarPathOf2(row.file);
+    const sp = sidecarPathOf5(row.file);
     if (isNodeModulesPath2(sp)) continue;
     const list = bySidecar.get(sp) ?? [];
     list.push(row);
@@ -5628,8 +7394,8 @@ function emitDerivedFromRoot(rootFile, opts) {
   }
   for (const [sidecarPath, rows0] of bySidecar) {
     const targetFile = rows0[0].file;
-    const targetSidecarDir = dirname10(sidecarPath);
-    const prevSrc = existsSync7(sidecarPath) ? readFileSync8(sidecarPath, "utf-8") : "";
+    const targetSidecarDir = dirname14(sidecarPath);
+    const prevSrc = existsSync12(sidecarPath) ? readFileSync10(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);
@@ -5648,7 +7414,7 @@ function emitDerivedFromRoot(rootFile, opts) {
         issues.push({
           code: "nudo:interface-name-clash",
           severity: "error",
-          message: `sidecar already has a handwritten binding '${row.fn}' (${relative2(process.cwd(), sidecarPath) || sidecarPath}); handwritten wins \u2014 skipping emit`
+          message: `sidecar already has a handwritten binding '${row.fn}' (${relative4(process.cwd(), sidecarPath) || sidecarPath}); handwritten wins \u2014 skipping emit`
         });
         anySkip = "name-clash";
         continue;
@@ -5676,7 +7442,7 @@ function emitDerivedFromRoot(rootFile, opts) {
         continue;
       }
       for (const n of body.usedNames) taken.add(n);
-      const srcRel = relative2(targetSidecarDir, targetFile) || basename3(targetFile);
+      const srcRel = relative4(targetSidecarDir, targetFile) || basename4(targetFile);
       const section = [
         DERIVED_HEADER,
         `// source: ${srcRel}:${row.fn}`,
@@ -5696,8 +7462,8 @@ function emitDerivedFromRoot(rootFile, opts) {
         for (const n of collectTopLevelNames(prevSection)) taken.add(n);
         continue;
       }
-      const norm = normalizeSectionText(section);
-      if (prevSection !== void 0 && normalizeSectionText(prevSection) === norm) {
+      const norm2 = normalizeSectionText(section);
+      if (prevSection !== void 0 && normalizeSectionText(prevSection) === norm2) {
         anySkip = "no-change";
         accepted.push({ fn: row.fn, text: prevSection, prevText: prevSection });
         for (const n of collectTopLevelNames(prevSection)) taken.add(n);
@@ -5726,7 +7492,7 @@ function emitDerivedFromRoot(rootFile, opts) {
       issues.push({
         code: "nudo:interface-not-projectable",
         severity: "error",
-        message: `assembled sidecar failed round-trip (${relative2(process.cwd(), sidecarPath) || sidecarPath}); refusing to write`
+        message: `assembled sidecar failed round-trip (${relative4(process.cwd(), sidecarPath) || sidecarPath}); refusing to write`
       });
       anySkip = "not-projectable";
       result.sidecars.push({
@@ -5741,15 +7507,15 @@ function emitDerivedFromRoot(rootFile, opts) {
       continue;
     }
     const changed = finalContent !== prevSrc;
-    const diff = changed ? unifiedDiff(prevSrc, finalContent, relative2(process.cwd(), sidecarPath) || sidecarPath) : void 0;
+    const diff = changed ? unifiedDiff(prevSrc, finalContent, relative4(process.cwd(), sidecarPath) || sidecarPath) : void 0;
     if (changed && !opts.dryRun) {
       const tmp = `${sidecarPath}.tmp-${process.pid}-${Math.random().toString(16).slice(2, 10)}`;
       try {
-        writeFileSync2(tmp, finalContent, "utf-8");
+        writeFileSync4(tmp, finalContent, "utf-8");
         renameSync2(tmp, sidecarPath);
       } catch (e) {
         try {
-          if (existsSync7(tmp)) unlinkSync2(tmp);
+          if (existsSync12(tmp)) unlinkSync2(tmp);
         } catch {
         }
         throw e;
@@ -5900,10 +7666,18 @@ function derivedRoundTrips(text, fn, fromFile, loadModule) {
   }
 }
 export {
+  ANALYSIS_ABI,
+  DEFAULT_ANALYSIS_MODE,
+  DiskCache,
+  HARVEST_NODE_DEFAULT_MAX_FILES,
+  HARVEST_NODE_DEFAULT_MAX_MS,
   SEMANTIC_TOKEN_MODIFIERS,
   SEMANTIC_TOKEN_TYPES,
   absToTSType,
   absToZodSchema,
+  ambientSourcesOfSidecar,
+  analysisConfig,
+  analysisFileCacheKey,
   analyzeExportsFromSource,
   analyzeFile,
   analyzeFileAsync,
@@ -5913,12 +7687,16 @@ export {
   buildCaseDirective,
   buildModuleGraph,
   buildSemanticTokens,
+  checkCacheKey,
   clearAbsModuleCache,
   clearAnalysisFileCache,
   clearAnalysisSessionCaches,
   clearBPathCache,
+  clearEnvPathDeps,
   clearFnAnalysisCache,
   clearHarvestCache,
+  clearNodeHarvestCache,
+  clearPathEnvCaches,
   collectAbsBindingsFromGraph,
   collectAbsInlays,
   collectBPathDiagnostics,
@@ -5929,14 +7707,20 @@ export {
   collectDtsFromEntry,
   collectEnvGlobals,
   collectEnvModules,
+  collectLoadDepContents,
+  collectParamBodyAccesses,
   collectStaticImports,
   computeDirtySet,
   defaultAbsLoadModule,
   defaultLoadModule,
   deriveFromRoot,
+  diagnosticsLevelForFile,
+  diskCacheRoot,
+  draftInterface,
   emitDerivedFromRoot,
   emitInterface,
   encodeSemanticTokens,
+  envPathDependents,
   evalAbsModuleGraph,
   evalProgramAbsWithModules,
   evictAbsModuleCacheFiles,
@@ -5945,8 +7729,12 @@ export {
   evictBPathCacheForFiles,
   evictFnAnalysisCacheForFiles,
   extractFnConstraintSources,
+  extractNudoImportSpecs,
+  filterDiagnosticsByLevel,
   findProjectConfig,
   formatDerivedSection,
+  formatDraftModule,
+  formatDraftSummary,
   formatEmitSummary,
   formatHarvestSummary,
   formatInterfaceSurfaceLine,
@@ -5957,9 +7745,12 @@ export {
   getAbsAtPosition,
   getAbsAtPositionAsync,
   getAnalysisFileCacheSize,
+  getAnalysisSession,
   getCasesForFile,
   getCompletionsAtPosition,
+  getEnvHarvestConflictCollector,
   getHoverAtPosition,
+  getNodeHarvestCacheSize,
   getTypeAtPosition,
   getTypeAtPositionAsync,
   harvestNodeTypes,
@@ -5967,24 +7758,42 @@ export {
   harvestPackageCached,
   harvestToAbsModules,
   harvestedValueToAbs,
+  ifaceCacheKey,
   insertGeneratedCaseDirectives,
   interfaceConfig,
   interfaceSurface,
+  interfaceTierModifierBit,
   isBPathCapable,
+  isDraftableEntry,
+  isEnvTemplatePath,
+  isHarvestNodeDisabled,
   isNudoTargetPath,
+  isProjectConfigPath,
+  isSidecarPath,
+  isWatchRelevantPath,
   lookupHarvested,
   matchesEmitAllowlist,
+  mergeHarvestUnderEnv,
   mockDirectivesToAbsSeeds,
+  noteEnvPathDeps,
   packageHarvestToAbsModules,
+  relativizePath,
   resetAllAnalysisCaches,
   resolvePackageRoot,
   serializeCaseArg,
   serializeInferJson,
+  setAnalysisSession,
+  setEnvHarvestConflictCollector,
+  sha256Hex,
+  shouldAnalyzeFile,
+  sidecarDraftPath,
+  hasNudoDirectives as sourceHasNudoDirectives,
   stripGeneratedCaseDirectives,
   summarizeNodeEnv,
   topoSortDirty,
   tryBPathCall,
   tryBPathCallFull,
   tryRunBPath,
-  unifiedDiff
+  unifiedDiff,
+  writeInterfaceDraft
 };