@nudojs/service 1.0.1 → 1.1.1

package/dist/index.d.ts

@@ -1,327 +1,47 @@
-import { Node, File } from '@babel/types';
-import { Abs, PolyFn, AbsModuleExports, AstEnv, Phi, BMemberDiag, BCallRecord, TranspiledCallResult, NudoConstraint } from '@nudojs/core';
-export { AbsInlay, BMemberDiag, collectAbsInlays } from '@nudojs/core';
-import { C as CallRecord } from './config-NqDRWWpn.js';
-export { I as InterfaceConfig, N as NudoConfig, f as findProjectConfig, i as interfaceConfig, m as matchesEmitAllowlist } from './config-NqDRWWpn.js';
-import { HarvestedEnv } from '@nudojs/harvester';
-import { FunctionWithDirectives } from '@nudojs/parser';
+import { a as AnalyzeLoadModule, D as DirectiveCaseMode, A as AnalysisResult } from './analyzer-types-CfBrPK9L.js';
+export { B as BindingInfo, C as CaseHint, b as CaseResult, c as CompletionItem, d as Diagnostic, e as DiagnosticSeverity, f as DiagnosticTag, F as FunctionAnalysis, R as ReferenceInfo, S as SourceLocation, g as SymbolInfo, h as SymbolTable } from './analyzer-types-CfBrPK9L.js';
+export { A as AbsGraphOptions, a as AbsModuleCacheEntry, b as AbsModuleGraphResult, c as AbsModuleLoadIssue, B as BPathRunResult, E as EnvHarvestConflict, M as MergeHarvestOptions, d as ModuleGraphCache, e as analyzeFile, f as analyzeFileAsync, g as buildModuleGraph, h as clearAbsModuleCache, i as clearBPathCache, j as collectAbsBindingsFromGraph, k as collectBPathReplacements, l as collectCallRecords, m as collectEnvGlobals, n as collectEnvModules, o as collectEnvNames, p as computeDirtySet, q as defaultAbsLoadModule, r as diagnosticsLevelForFile, s as evalAbsModuleGraph, t as evictAbsModuleCacheFiles, u as evictBPathCacheForFiles, v as filterDiagnosticsByLevel, w as getAbsModuleCacheSize, x as getBPathCacheSize, y as getEnvHarvestConflictCollector, z as isBPathCapable, C as locFromNode, D as mergeHarvestUnderEnv, F as resolveModule, G as setEnvHarvestConflictCollector, H as shouldAnalyzeFile, I as sourceHasNudoDirectives, J as topoSortDirty, K as trimBPathCache, L as tryBPathCall, N as tryBPathCallFull, O as tryRunBPath } from './analysis-_DlXLC-L.js';
+import { C as CallRecord } from './call-record-CkyCFkT9.js';
+export { c as clearPathEnvCaches, g as getPathEnvCacheSizes } from './env-loader-fj0TSCcA.js';
+import { N as NudoConfig } from './config-DDB588oA.js';
+export { A as AnalysisConfig, a as AnalysisMode, C as CheckConfig, e as DEFAULT_ANALYSIS_MODE, D as DiagnosticsLevel, I as InterfaceConfig, b as analysisConfig, g as applyBForkBudgetFromConfig, c as checkConfig, h as currentBForkBudgetLimit, d as diskCacheRoot, f as findProjectConfig, i as interfaceConfig, m as matchesEmitAllowlist } from './config-DDB588oA.js';
+import { File, Node } from '@babel/types';
+import { PolyFn, Abs, AbsModuleExports } from '@nudojs/core';
+import { L as LoadModule } from './what-if-mIo7I5Ii.js';
+export { T as TypeBinding, d as defaultLoadModule, i as injectBindings, t as typeExprToDirective } from './what-if-mIo7I5Ii.js';
+import { FunctionWithDirectives, FileDirective } from '@nudojs/parser';
+import '@nudojs/core/internal';
+
+declare function analysisFileCacheKey(filePath: string, source: string, activeCases?: Map<string, number>, externalCallRecords?: CallRecord[], analysisCfg?: {
+    mode: string;
+    evalMissingSlot: string;
+    callSiteBudget: number;
+    diagnostics: string;
+}, loadModule?: AnalyzeLoadModule, projectEnvNames?: string[], 
+/** ambient 侧车绑定：变更必须 miss（dep 指纹故意不编码 autoBind） */
+autoBind?: boolean, caseMode?: DirectiveCaseMode): {
+    filePath: string;
+    source: string;
+    auxKey: string;
+    noCache?: boolean;
+};
 
 /**
  * Per-function FunctionAnalysis cache (body-edit: recompute only dirty fns).
  * Cleared together with B-path / whole-file analysis caches.
  */
 
+/** 测试/诊断：当前条目数（≤ getSessionCacheLimits().maxFns） */
+declare function getFnAnalysisCacheSize(): number;
 declare function clearFnAnalysisCache(): void;
+/** 立刻压到当前 maxFns（调低上限时收内存） */
+declare function trimFnAnalysisCache(): void;
 /**
  * Dependency content changed: drop every per-fn entry for these entry files.
  * Keys are `filePath\0...`, so a prefix scan is sound and cheap at LRU size.
  */
 declare function evictFnAnalysisCacheForFiles(files: string[]): number;
 
-type SourceLocation = {
-    start: {
-        line: number;
-        column: number;
-    };
-    end: {
-        line: number;
-        column: number;
-    };
-};
-type DiagnosticSeverity = "error" | "warning" | "info";
-type DiagnosticTag = "unnecessary";
-type Diagnostic = {
-    range: SourceLocation;
-    severity: DiagnosticSeverity;
-    message: string;
-    tags?: DiagnosticTag[];
-    code?: string;
-    suggestions?: string[];
-    data?: unknown;
-    /** provenance of the receiver value (callsite argument that flowed into the error) */
-    origin?: {
-        line: number;
-        column: number;
-    };
-};
-type CaseResult = {
-    name: string;
-    /** 无损参数 Abs */
-    argAbs: Abs[];
-    /** 无损结果 Abs */
-    abs: Abs;
-    /** 无损抛出 Abs（未抛为 never） */
-    throwsAbs: Abs;
-    throwLoc?: SourceLocation;
-    source?: "directive" | "callsite";
-    /** `@nudo:case "name" (…) => expected` — presence means the case is a test assertion */
-    expected?: Abs;
-    /** number of additional call sites folded into a symbolic case */
-    aggregatedFrom?: number;
-    /**
-     * 内涵摘要（代数 generalize）：无损 Abs + term/pred/conf。
-     */
-    intension?: {
-        display?: string;
-        term?: string;
-        pred?: string;
-        conf?: string;
-        /** 无损 Abs 单行（formatAbs） */
-        abs?: string;
-        /** 无损 Abs 多行（formatAbsMultiline） */
-        absMultiline?: string;
-    };
-};
-type FunctionAnalysis = {
-    name: string;
-    loc: SourceLocation;
-    paramNames: string[];
-    cases: CaseResult[];
-    /** cases 结果 Abs 的 join；dts 返回位源 */
-    combinedAbs?: Abs;
-    entryOnly?: boolean;
-    skipped?: boolean;
-    /**
-     * True for functions collected from CJS-style bindings/assignments
-     * (`exports.X = fn`, `module.exports = fn`, `const f = fn`): their name has
-     * no declaration-level stability, so .d.ts generation skips them while
-     * infer/JSON output still reports them.
-     */
-    noDeclaration?: boolean;
-    /** absolute path of the module this function is imported from (externalFunctions only) */
-    fromModule?: string;
-};
-type BindingInfo = {
-    /** 无损 Abs */
-    abs: Abs;
-    loc?: SourceLocation;
-};
-type CaseHint = {
-    line: number;
-    label: string;
-    ok: boolean;
-};
-type AnalysisResult = {
-    functions: FunctionAnalysis[];
-    diagnostics: Diagnostic[];
-    bindings: Map<string, BindingInfo>;
-    /**
-     * Node identity is from the analysis-time parse. A later re-parse of the
-     * same source returns a *different* File (new Nodes) if the AST LRU evicted
-     * the original — lookups must use the File that produced this result, not a
-     * freshly parsed one. getTypeAtPosition rebuilds its own map and is unaffected.
-     */
-    /** 无损节点 Abs */
-    nodeAbsMap: Map<Node, Abs>;
-    caseHints: CaseHint[];
-    /** functions imported from other modules, synthesized from cross-file call sites observed while analyzing this file */
-    externalFunctions?: FunctionAnalysis[];
-};
-type CompletionItem = {
-    label: string;
-    kind: "property" | "method" | "variable";
-    detail?: string;
-};
-type SymbolInfo = {
-    name: string;
-    kind: "function" | "variable" | "class" | "parameter";
-    loc: SourceLocation;
-    uri?: string;
-};
-type ReferenceInfo = {
-    name: string;
-    loc: SourceLocation;
-    uri?: string;
-};
-type SymbolTable = {
-    definitions: Map<string, SymbolInfo>;
-    references: ReferenceInfo[];
-};
-/** mtime 边缓存：key 为文件路径，edges 为已抽取的相对 import 边（与 buildModuleGraph 返回语义一致）。 */
-type ModuleGraphCache = Map<string, {
-    mtimeMs: number;
-    size: number;
-    edges: string[];
-}>;
-/** Statically extract each file's relative import edges (extension resolution identical to CLI resolveModule: ''/'.js'/'.ts'/'.mjs'; bare npm specifiers skipped). */
-declare function buildModuleGraph(files: string[], cache?: ModuleGraphCache): {
-    imports: Map<string, Set<string>>;
-    dependents: Map<string, Set<string>>;
-};
-/** changed plus its transitive dependents (reverse-edge BFS); cycle-safe via visited. */
-declare function computeDirtySet(dependents: Map<string, Set<string>>, changedFile: string): string[];
-/** Topological order with dependencies before dependents (only imports edges internal to dirty; cycles tolerated — remaining files appended in arbitrary order). */
-declare function topoSortDirty(imports: Map<string, Set<string>>, dirty: string[]): string[];
-/**
- * Async entry to analyzeFile: preloads path-based env files
- * (`/// @nudo:env ./nudo-harvest-node.ts`) via dynamic import — impossible
- * synchronously in ESM — then runs the sync analysis, which picks the
- * preloaded factories up from the env-loader cache. The sync analyzeFile
- * signature is unchanged for existing consumers (LSP, MCP, vite-plugin).
- */
-declare function analyzeFileAsync(filePath: string, source: string, activeCases?: Map<string, number>, externalCallRecords?: CallRecord[]): Promise<AnalysisResult>;
-/**
- * 调用点发现（阶段一）：在"使用现场"文件（测试 / 上层应用）中求值
- * 顶层代码，收集它对（外部模块导出的）函数的调用记录。每条记录带
- * 真实的实参类型与结果类型——后续 analyzeFile 将其注入合成 case，
- * 使被使用方从 entry-only（参数全 unknown）升级为真实调用形态。
- *
- * Abs 路径（TypeValue evaluateProgram 已删）：evalProgramAbs + AbsCallRecord。
- * 只做求值与记录，不产出诊断；求值异常不抛出（使用现场文件可能
- * 依赖未 mock 的全局，收集不到就收集不到，不能拖垮主分析）。
- */
-declare function collectCallRecords(filePath: string, source: string): CallRecord[];
-/**
- * 整文件分析。同 (path, source, cases, external) 命中 memo → O(1)。
- * 不再每次 clearBPathCache：B 路径按本文件 source 键控。
- *
- * 宿主契约：入口 source 未变但依赖模块内容变了时，必须调用
- * `evictBPathCacheForFiles` / `evictAnalysisFileCacheForFiles` /
- * `evictFnAnalysisCacheForFiles`（LSP 已接好）。非 LSP 宿主
- * （CLI watch / vite-plugin）在 dep 变更时应 `clearBPathCache()` 或上述逐出。
- */
-declare function analyzeFile(filePath: string, source: string, activeCases?: Map<string, number>, externalCallRecords?: CallRecord[]): AnalysisResult;
-
-type CaseInfo = {
-    functionName: string;
-    caseName: string;
-    caseIndex: number;
-};
-declare function getCasesForFile(filePath: string, source: string): {
-    functionName: string;
-    cases: {
-        name: string;
-        index: number;
-    }[];
-    loc: SourceLocation;
-}[];
-/** Async entry to getTypeAtPosition with path-env preloading (see analyzeFileAsync). */
-declare function getTypeAtPositionAsync(filePath: string, source: string, line: number, column: number, activeCases?: Map<string, number>): Promise<Abs | null>;
-/** Async entry to getAbsAtPosition（与 getTypeAtPositionAsync 同预加载口径） */
-declare function getAbsAtPositionAsync(filePath: string, source: string, line: number, column: number, activeCases?: Map<string, number>): Promise<Abs | null>;
-/**
- * 光标处无损 Abs。B-path 节点表优先；用例函数体走 Abs 重放。
- */
-declare function getAbsAtPosition(filePath: string, source: string, line: number, column: number, activeCases?: Map<string, number>): Abs | null;
-/** 光标处类型（Abs）。B-path 节点表优先；用例函数体走 Abs 重放。 */
-declare function getTypeAtPosition(filePath: string, source: string, line: number, column: number, activeCases?: Map<string, number>): Abs | null;
-type HoverInfo = {
-    /** 外延展示（formatShape / formatAbs） */
-    typeText: string;
-    /** 内涵签名（代数 generalize） */
-    intension?: string;
-    /** 无损 Abs 单行展示（shape / term / pred / conf） */
-    abs?: string;
-    /** 无损 Abs 多行展示 */
-    absMultiline?: string;
-};
-/**
- * LSP hover：优先无损 Abs（类型即计算本体）。
- * 节点表也是 Abs（collectAbsNodeTypes），不经 bridge。
- *
- * 函数名/调用 callee 位置（design-hof-relations §7）：
- * intension 一律走 generalize/formatPoly（HOF fnRels 在这里）；
- * typeText 仍落 B-path Abs（调用点显示结果类型，不是函数签名）。
- * 禁止用 B-path 的 arity-only fn Abs 冒充权威关系源。
- */
-declare function getHoverAtPosition(filePath: string, source: string, line: number, column: number, activeCases?: Map<string, number>): HoverInfo | null;
-declare function getCompletionsAtPosition(filePath: string, source: string, line: number, column: number): CompletionItem[];
-
-/**
- * `nudo infer --json` 稳定契约 v1（CI / Agent）。
- *
- * 字段只增不改语义：
- * - args / result / throws / combined：formatShape 外延投影（有损，兼容）
- * - intension.abs*：无损 Abs 展示（主线）
- * - argsAbs / resultAbs：CaseResult 上的无损 Abs（formatAbs）；有则补齐
- */
-
-type InferJsonCase = {
-    name: string;
-    /** TypeValue 投影（有损外延） */
-    args: string[];
-    result: string;
-    throws: string | null;
-    source: string | null;
-    aggregatedFrom?: number;
-    /** 无损参数 Abs 展示（与 args 对齐；缺失位省略） */
-    argsAbs?: string[];
-    /** 无损结果 Abs 展示 */
-    resultAbs?: string;
-    /** 无损内涵（Abs）；无则省略 */
-    intension?: {
-        display?: string;
-        abs?: string;
-        absMultiline?: string;
-        term?: string;
-        pred?: string;
-        conf?: string;
-    };
-};
-type InferJsonFunction = {
-    name: string;
-    loc: SourceLocation;
-    entryOnly: boolean;
-    noDeclaration?: boolean;
-    cases: InferJsonCase[];
-    combined?: string;
-    /** 无损 combined Abs 展示 */
-    combinedAbs?: string;
-};
-type InferJson = {
-    version: 1;
-    file: string;
-    summary: {
-        functions: number;
-        externalFunctions: number;
-        cases: number;
-        diagnostics: number;
-    };
-    functions: InferJsonFunction[];
-    externalFunctions?: Array<{
-        name: string;
-        fromModule?: string;
-        cases: InferJsonCase[];
-    }>;
-    diagnostics: Array<{
-        range: SourceLocation;
-        severity: string;
-        message: string;
-        code?: string;
-        suggestions?: string[];
-        tags?: string[];
-        origin?: {
-            line: number;
-            column: number;
-        };
-    }>;
-};
-declare function serializeInferJson(result: AnalysisResult, file: string): InferJson;
-
-/**
- * nudo 推断目标文件判定（纯扩展名规则，路径无需存在）。
- *
- * 规则：.js / .mjs / .ts 可作为推断目标；其余扩展（.cjs/.tsx/.jsx/.mts/.d.ts…）
- * 一律 false。显式排除：
- *  - .d.ts —— 类型声明文件（harvester 的输入），不是可求值的实现源码；
- *  - .tsx / .jsx —— JSX 构造的求值超出 nudo 推断器范围；
- *  - *.nudo.js / *.nudo.ts —— 侧车契约模块（interface 绑定源），不是源码
- *    推断目标；目录级 check/infer/doctor 展开不得把它们当实现分析。
- *
- * 消费方：CLI 的 collectNudoFiles/watch 过滤/doctor 目录展开（.ts 放开后统一
- * 走本函数，避免各处手写 endsWith 漂移），以及 LSP 的 isNudoFile（接线由
- * LSP 侧负责）。
- */
-declare function isNudoTargetPath(path: string): boolean;
-
-/**
- * 相对/绝对 specifier → 模块源码。
- * CLI / LSP / vite / check 共用同一扩展名表，避免门禁结果分叉。
- */
-type LoadModule = (spec: string, fromFile: string) => string | undefined;
-/** 默认 loadModule：支持 .js/.mjs/.ts 与 index 入口 */
-declare function defaultLoadModule(spec: string, fromFile: string): string | undefined;
-
 /**
  * Host 侧多文件解析（非代数层）。
  *
@@ -351,219 +71,102 @@ declare function analyzeExportsFromSource(filePath: string, source: string): Mod
 declare function collectStaticImports(entryFile: string, maxDepth?: number): Map<string, ModuleExports>;
 
 /**
- * Host：从 npm 包 / @types 收集 .d.ts → harvestDts。
- * 代数不碰 fs；这里只做「找到 dts 路径」这一层宿主职责。
- */
-
-/** 在 node_modules 中解析包根（含 @types/*） */
-declare function resolvePackageRoot(pkg: string, fromDir?: string): string | undefined;
-type PackageHarvest = {
-    pkg: string;
-    root: string;
-    dtsFiles: string[];
-    env: HarvestedEnv;
-};
-/**
- * 从入口 .d.ts 沿 reference path / 相对 import 做 BFS 收集。
- * 适合 @types 包（三斜线引用图）；比整树 walk 更贴声明入口。
- */
-declare function collectDtsFromEntry(entry: string, maxFiles?: number): string[];
-/** harvest 一个 npm 包（或 @types 包） */
-declare function harvestPackage(pkg: string, fromDir?: string, maxFiles?: number): PackageHarvest | {
-    error: string;
+ * Entry-variant (browser / node) observation signal.
+ *
+ * (Module named entry-variants to avoid "dual engine" confusion; the
+ * product diagnostic code remains `nudo:dual-entry`.)
+ *
+ * Call-site records are file-scoped: when a package ships separate browser and
+ * node entrypoints, records collected against one variant do **not** inject
+ * into analysis of the other (design limitation, not a bug). This module makes
+ * that ceiling visible: when analysis runs on one entry variant of a dual-entry
+ * package, emit `nudo:dual-entry` once so the user is not left thinking both
+ * entries were covered.
+ *
+ * Zero-FP discipline: fires only when package.json really declares two faces
+ * (browser + node/default) that resolve to **different** files, and the file
+ * being analyzed is one of those entry targets. Single-entry packages never
+ * fire.
+ */
+type EntryVariantInfo = {
+    pkgPath: string;
+    pkgDir: string;
+    pkgName?: string;
+    kind: "exports-conditions" | "browser-field";
+    /** resolved absolute paths of the browser face */
+    browserPaths: string[];
+    /** resolved absolute paths of the node/default face */
+    nodePaths: string[];
+    /** which face the analyzed file belongs to */
+    role: "browser" | "node";
+    /** display targets (as declared, relative) for the message */
+    browserTargets: string[];
+    nodeTargets: string[];
+};
+type EntryVariantFaces = {
+    kind: "exports-conditions" | "browser-field";
+    browser: string[];
+    node: string[];
+};
+/**
+ * Detect browser/node dual faces in a parsed package.json.
+ * Returns null unless both faces exist and differ (zero-FP on single-entry).
+ */
+declare function detectEntryVariantsFromPackageJson(pkg: unknown): EntryVariantFaces | null;
+/** Nearest package.json walking up from the file's directory. */
+declare function findOwningPackage(fromFile: string): {
+    path: string;
+    dir: string;
+    pkg: Record<string, unknown>;
+} | null;
+/**
+ * Dual-entry info for an analyzed file: the owning package must declare two
+ * differing faces **and** this file must be one of the entry targets.
+ * Returns null otherwise (single-entry packages, shared helpers, …).
+ */
+declare function entryVariantForFile(filePath: string): EntryVariantInfo | null;
+/** Host-facing info issue (CLI check / JSON) for one analyzed entry variant. */
+type EntryVariantIssue = {
+    severity: "info";
+    code: "nudo:dual-entry";
+    message: string;
+    suggestion: string;
+    line: number;
+    column: number;
 };
-/** harvest 结果 → 人类可读导出表 */
-declare function formatHarvestSummary(h: PackageHarvest): string;
-/** 取某个导出的展示串（formatShape） */
-declare function lookupHarvested(h: PackageHarvest, moduleName: string, exportName: string): string | undefined;
+declare function entryVariantIssueForFile(filePath: string): EntryVariantIssue | null;
 
 /**
- * harvest 自动化：源码裸 import → @types/package → env modules。
- * 手动 `nudo harvest` 仍保留；这里是分析路径上的按需注入。
+ * `@nudo:skip [returnsExpr]` 采集（host 侧）。
+ *
+ * core 的 `checkSource` 不依赖 parser，所以 skip 指令由 host（CLI / LSP /
+ * vite-plugin）解析后经 `CheckOptions.skips` 下传——保证 check 面与 test 面
+ * 对 skip 的口径一致：不评估 body、退出 L1/L2 门禁。
  */
 
-/** 裸说明符 → 包名（含 scope）；相对/绝对/node: 内建返回 undefined */
-declare function barePackageName(spec: string): string | undefined;
-declare function collectBarePackages(source: string): string[];
-declare function harvestPackageCached(pkg: string, fromDir: string): PackageHarvest | null;
-declare function clearHarvestCache(): void;
 /**
- * 自动 harvest 源码中全部裸包（有 @types 或包内 dts 时）。
- * 返回可注入 setEnvModules 的 modules 表；无包可 harvest 时为空对象。
+ * 每个带 `@nudo:skip` 的顶层函数 → 声明的返回 Abs；`null` = 未声明返回类型。
+ * 解析失败（语法错误等）→ 空表（check 退回默认路径，不静默吞函数）。
  */
-declare function autoHarvestModules(source: string, fromDir: string): Record<string, Record<string, Abs>>;
+declare function collectSkipReturns(source: string): Map<string, Abs | null>;
 
 /**
- * Host：import 图（相对 + 裸包 harvest）→ Abs 导出表 → 注入入口。
- * 读 fs / 解析路径 / harvest 在这里；core 只收 modules 表。
+ * check/iface 磁盘缓存键的依赖内容采集。
+ * 走 core `loadModuleDepsFingerprint`：覆盖 ESM from / require / dynamic import /
+ * `@nudo:import` / ambient 侧车闭包——不只 `@nudo:import` 注释。
+ *
+ * 内容必须优先取 loadModule 解析结果（fingerprint.contents），不得回读磁盘：
+ * LSP buffer-aware loadModule 与自定义 loader 的内容可能与磁盘不一致，
+ * 回读会让缓存键分叉（buffer 编辑后仍命中磁盘旧内容）。
  */
-
-type AbsLoadModule = (spec: string, fromFile: string) => string | undefined;
-/** 相对说明符 → 源码 */
-declare function defaultAbsLoadModule(spec: string, fromFile: string): string | undefined;
-/** 模块加载守卫：与 TypeValue loadModuleEnv 口径对齐，供 analyzer 映射诊断 */
-type AbsModuleLoadIssue = {
-    kind: "cycle" | "depth" | "missing";
-    /** 诊断定位用标签（文件 basename 或 require/import 说明符） */
-    label: string;
-    reason: string;
-};
-type AbsModuleGraphResult = {
-    /** 入口 import 说明符 → 依赖导出表 */
-    modules: Record<string, AbsModuleExports>;
-    /** 绝对路径 → 导出表（含依赖；循环时占位为空） */
-    byPath: Map<string, AbsModuleExports>;
-    /** cycle / depth / missing（B 路径权威，避免 TypeValue 叠报） */
-    issues: AbsModuleLoadIssue[];
-};
-type AbsGraphOptions = {
-    loadModule?: AbsLoadModule;
-    seedVars?: Record<string, Abs>;
-    seedFns?: Record<string, {
-        params: string[];
-        body: Node;
-        async?: boolean;
-    }>;
-    maxDepth?: number;
-};
-/** 会话级依赖模块缓存条目：stat 指纹 + 导出 + 子树装载 issue。 */
-type AbsModuleCacheEntry = {
-    mtimeMs: number;
-    size: number;
-    exports: AbsModuleExports;
-    /** 该模块子树首次求值时记录的 cycle/depth/missing；命中时重放。 */
-    issues: AbsModuleLoadIssue[];
+type DepContent = {
+    path: string;
+    content: string | null;
 };
-declare function clearAbsModuleCache(): void;
-declare function evictAbsModuleCacheFiles(paths: string[]): void;
-/**
- * 递归求值相对依赖 + 裸包 harvest，产出入口可用的 modules 表。
- * 循环依赖：先放空表再回填（与 TypeValue 路径 partial 口径一致），
- * 并记录 cycle/depth/missing 供诊断。
- */
-declare function evalAbsModuleGraph(entrySource: string, entryFile: string, opts?: AbsGraphOptions): AbsModuleGraphResult;
-/** 便捷：入口求值 + 依赖 Abs 注入 */
-declare function evalProgramAbsWithModules(source: string, entryFile: string, opts?: AbsGraphOptions & {
-    file?: unknown;
-}): {
-    env: AstEnv;
-    last: Abs;
-    phi: Phi;
+declare function collectLoadDepContents(filePath: string, source: string, loadModule: (spec: string, fromFile: string) => string | undefined): {
+    depContents: DepContent[];
+    truncated: boolean;
 };
-/**
- * 收集顶层绑定名 → Abs（含相对 import / 裸包 harvest 注入）。
- * 供 bindings / hover 从 Abs 投影，不必走 TypeValue evaluator。
- */
-declare function collectAbsBindingsFromGraph(source: string, filePath: string, opts?: AbsGraphOptions): Map<string, Abs>;
-
-/**
- * Harvest Abs 导出 → AbsModuleExports（供 Abs 模块图注入）。
- * harvest 产物已是 Abs；fn 槽 apply 直接返回声明返回类型（conf=mock）。
- */
-
-/** 单个 Abs 导出 → 可调用 mock（fn 槽 apply 返回声明返回类型） */
-declare function harvestedValueToAbs(a: Abs): Abs;
-/**
- * 把 harvest 的 modules/globals 合成 AbsModuleExports。
- * 键同时登记：原始模块路径、包名、basename（path / @types/path）。
- */
-declare function harvestToAbsModules(pkg: string, fromDir: string): Record<string, AbsModuleExports>;
-declare function packageHarvestToAbsModules(pkg: string, h: PackageHarvest): Record<string, AbsModuleExports>;
-/** 裸说明符 → Abs 导出表（走 harvest 缓存） */
-declare function bareSpecToAbsModules(spec: string, fromFile: string): AbsModuleExports | undefined;
-
-/** @nudo:env → Abs 全局表（env 模块 Abs 原生） */
-declare function collectEnvGlobals(envNames: string[]): Record<string, Abs>;
-/** @nudo:env modules（path / node:path / fs…）→ AbsModuleExports */
-declare function collectEnvModules(envNames: string[]): Record<string, AbsModuleExports>;
-/** 收集 @nudo:replace + @nudo:as → transpile 注入表 */
-declare function collectBPathReplacements(source: string): {
-    targets: Array<{
-        target: string;
-        varName: string;
-        stmtStart?: number;
-        stmtEnd?: number;
-    }>;
-    values: Record<string, Abs>;
-    asTargets: Array<{
-        varName: string;
-        stmtStart: number;
-        stmtEnd: number;
-    }>;
-    asValues: Record<string, Abs>;
-};
-/** 可走 transpile+exec：env 经 loadEnvs（内置 + 已 preload 的路径型） */
-declare function isBPathCapable(source: string, envNames?: string[]): boolean;
-type BPathRunResult = {
-    exports: Record<string, unknown>;
-    modules: Record<string, AbsModuleExports>;
-    /** 顶层执行期 method-missing */
-    memberDiags?: BMemberDiag[];
-    /** 模块图 cycle/depth/missing（B 权威） */
-    moduleIssues?: AbsModuleLoadIssue[];
-    /** Abs 求值递归截断的函数标签 */
-    truncatedFns?: string[];
-    /** 顶层 $callNamed 调用点（call@ 合成；不经 TypeValue collector） */
-    calls?: BCallRecord[];
-};
-declare function clearBPathCache(): void;
-/** 依赖文件变更后：逐出以这些文件为入口的 B-path 缓存 */
-declare function evictBPathCacheForFiles(files: string[]): number;
-/** 模块图 + runTranspiled（默认 analyze 模式） */
-declare function tryRunBPath(source: string, filePath: string, opts?: {
-    maxLoopIters?: number;
-    mode?: "exec" | "analyze";
-    envNames?: string[];
-    /** @nudo:mock → Abs，注入为全局绑定（防止顶层调用真 fetch 等） */
-    mocks?: Record<string, Abs>;
-}): BPathRunResult | undefined;
-/**
- * B 路径求值具名导出（结果 + throws）；opts.collectCalls 时附带调用点记录。
- *
- * `calls` 只含**本次具名调用期间**（callTranspiledExportFull 内）发生的
- * 调用点——不含模块级顶层调用（run.calls）。模块级记录由主分析流程
- * 另行收集（analyzer 的 bTopCallRecords / absCallRecords）；在此重复返回
- * 会把 B 路径结果（常为 unknown）当第二组记录推给 analyzer，dedupe 因
- * 结果形态不同而保留，污染被调函数的 case 列表（多余 call@L 重复 +
- * call@symbolic 聚合 case，见 analyzer directive-case 分支）。
- */
-declare function tryBPathCallFull(source: string, filePath: string, fnName: string, args: Abs[], opts?: {
-    collectCalls?: boolean;
-    collectMemberDiags?: boolean;
-    envNames?: string[];
-    mocks?: Record<string, Abs>;
-}): (TranspiledCallResult & {
-    calls?: BCallRecord[];
-    memberDiags?: BMemberDiag[];
-    moduleIssues?: AbsModuleLoadIssue[];
-    truncatedFns?: string[];
-}) | undefined;
-/** B 路径求值具名导出（仅成功结果） */
-declare function tryBPathCall(source: string, filePath: string, fnName: string, args: Abs[], opts?: {
-    envNames?: string[];
-    mocks?: Record<string, Abs>;
-}): Abs | undefined;
-
-declare function clearAnalysisFileCache(): void;
-declare function getAnalysisFileCacheSize(): number;
-/** 依赖变更后：按入口文件逐出 */
-declare function evictAnalysisFileCacheForFiles(files: string[]): number;
-
-/**
- * 依赖内容变更后：按入口文件定向逐出 service 层缓存。
- * 调用方应传「以这些文件为入口」的路径（脏集里的 dependents），
- * 而不是变更的 dep 文件本身——dep 自己 source 变了会自然 miss。
- */
-declare function evictAnalysisCachesForFiles(files: string[]): void;
-/**
- * 清空全部会话级分析缓存（service + core）。
- * 适用于：CLI watch 增量批前、vite buildStart / watchChange、测试隔离。
- * 比定向逐出重，但保证无陈旧命中；单次 analyze 内部的 per-fn / generalize
- * memo 不受影响（它们在同一轮里先写后读）。
- */
-declare function clearAnalysisSessionCaches(): void;
-/** 比 clearAnalysisSessionCaches 更彻底：再丢 AST LRU（测试 / 进程复用场景） */
-declare function resetAllAnalysisCaches(): void;
 
 /**
  * B 路径静态诊断（AST，不执行）：
@@ -599,129 +202,9 @@ type BPathDiagnostics = {
 declare function collectBPathDiagnostics(source: string, extraKnown?: Iterable<string>): BPathDiagnostics;
 
 /**
- * 预置 Node API env：从 @types/node 的 .d.ts harvest。
- * 与 packages/env 的手写 env 并行；此路径自动、可刷新。
- */
-
-type NodeEnvResult = {
-    ok: true;
-    env: HarvestedEnv;
-    root: string;
-    files: number;
-} | {
-    ok: false;
-    error: string;
-};
-/** harvest @types/node（限制文件数 + 时间预算，避免拖垮启动） */
-declare function harvestNodeTypes(fromDir?: string, maxFiles?: number, maxMs?: number): NodeEnvResult;
-/** 把 harvest 结果压成「模块名 → 导出名列表」摘要，便于日志/测试 */
-declare function summarizeNodeEnv(env: HarvestedEnv): {
-    modules: string[];
-    globals: string[];
-    symbolCount: number;
-};
-
-/**
- * Semantic tokens 图例（tokenTypes 下标即 LSP 编码里的 tokenType 值）。
- * 与 LSP server capabilities 里声明的 legend 必须逐字对齐——server.ts 直接
- * 导入本常量注册，保证「提取端索引」与「客户端图例」单一来源。
- * 顺序沿用 lsp 包原 legend（function/variable/parameter/property 在前），
- * 末尾追加 method（对象字面量方法键），只追加不重排，客户端索引稳定。
- */
-declare const SEMANTIC_TOKEN_TYPES: readonly ["function", "variable", "parameter", "property", "type", "keyword", "string", "number", "comment", "decorator", "method"];
-declare const SEMANTIC_TOKEN_MODIFIERS: readonly ["declaration", "readonly", "deprecated", "unreachable"];
-type SemanticToken = {
-    line: number;
-    char: number;
-    length: number;
-    typeIndex: number;
-    modifierBitmask: number;
-};
-/** LSP 标准相对五元组编码：deltaLine/deltaStartChar/length/tokenType/tokenModifiers。 */
-declare function encodeSemanticTokens(tokens: SemanticToken[]): number[];
-/**
- * 从源码提取 semantic tokens 并按 LSP 相对编码返回扁平 number[]。
- *
- * 上色范围（声明位优先，未解析的 token 一律不上色）：
- * - 顶层 const/let/var 声明的绑定名：推断为函数绑定 → function，否则 variable
- *   （函数体内部的声明不做 env 反查——外层同名绑定会串味，统一 variable）；
- * - 函数声明/函数表达式的名字 → function；所有函数的参数 → parameter；
- * - 对象字面量的键：值为函数 → method，否则 property。
- *
- * 推断优先 Abs 模块图绑定（TypeValue 退出主路径）；失败时复用
- * evaluateProgram。解析失败返回 []。
- */
-declare function buildSemanticTokens(filePath: string, source: string): number[];
-
-/** Abs → TS 类型串。有损：pred / 非 lit term 落到 shape 基类型。 */
-declare function absToTSType(a: Abs): string;
-/**
- * 为单个函数生成 .d.ts 声明行（JSDoc + 单一 widen 主签名）。
- * service 的 generateDts 与 CLI `--dts`（infer/watch）共用本函数，
- * 两条路径输出保持一致。
- */
-declare function generateFunctionDtsLines(fn: FunctionAnalysis): string[];
-declare function generateDts(result: AnalysisResult): string;
-
-/** Abs → zod schema 源码。有损：pred / 非 lit term 落到 shape 基类型。 */
-declare function absToZodSchema(a: Abs): string;
-
-/** Abs 指称守卫（设计 §2.7）：保留 pred */
-declare function generateGuardFunctionFromAbs(name: string, abs: Abs): string;
-/** 兼容别名：Abs 路径唯一 */
-declare function generateGuardFunction(name: string, abs: Abs): string;
-
-/** 单个 Abs → parseCaseArgExpr 可解析回去的表达式文本；不可表达返回 null */
-declare function serializeCaseArg(a: Abs): string | null;
-/**
- * 组装单行 ` * @nudo:case "name" (a, b)` 指令文本（无尾换行）。
- * 任一实参不可序列化、或名字含双引号/换行（名字正则 `"([^"]+)"` 承载不了）→ 整体 null。
- */
-declare function buildCaseDirective(name: string, argsAbs: Abs[]): string | null;
-/**
- * 从源码剥离所有本模块生成的 @nudo:case 指令（名字以 call@ 开头，整行删除）。
- * 若所属 JSDoc 块因此只剩空 ` *` 行（无其他 @nudo:* 指令、无文字内容），
- * 连块首 `/**` 行与块尾行整块删除。绝不碰非 case 指令与普通注释。
- * 注意：手写但以 call@ 命名的 case 同样会被删——call@ 前缀保留为生成物标记。
- * removed 返回被删指令名列表（按出现顺序）。
- */
-declare function stripGeneratedCaseDirectives(source: string): {
-    source: string;
-    removed: string[];
-};
-type EmitSkipReason = "hand-written" | "already-generated" | "entry-only" | "no-serializable-cases" | "no-declaration" | "skipped";
-type EmitResult = {
-    source: string;
-    changed: boolean;
-    written: Array<{
-        fn: string;
-        cases: string[];
-    }>;
-    skipped: Array<{
-        fn: string;
-        reason: EmitSkipReason;
-        detail?: string;
-    }>;
-};
-/**
- * 把 analysis 中的合成 case（source === "callsite"）固化为源码指令：
- *
- * 1. 源码已有任何非 call@ 命名的 case → skip "hand-written"；
- *    已有 call@ case → skip "already-generated"。
- * 2. fn.skipped / fn.noDeclaration / fn.entryOnly → 对应 skip。
- * 3. 逐 case 序列化；个别不可序列化的丢弃并在 skipped 记
- *    no-serializable-cases（函数整体仍写可序列化子集，全不可序列化才整函数跳过）。
- * 4. 写入位置：函数声明行正上方——已有 JSDoc 块则插到 `/**` 行后，
- *    无块则新建三行块。缩进取声明行的 loc.start.column（babel 0 基列）。
- *    多函数编辑按行号从下往上应用，避免行号漂移。
- */
-declare function insertGeneratedCaseDirectives(source: string, analysis: AnalysisResult): EmitResult;
-/** 行级 unified diff：`--- a/path` 头 + `@@` hunk + 上下文 3 行；相同返回 "" */
-declare function unifiedDiff(a: string, b: string, path: string): string;
-
-/**
- * @nudo:mock / sinon 指令 → Abs seed（供 evalProgramAbs）。
- * host 层：依赖 parser 指令形态；core 只吃 seedVars/seedFns。
+ * @nudo:mock / sinon 指令 → Abs seed（供 B 路径注入：runTranspiled
+ * envGlobals / mockSeedsToAbsMocks）。
+ * host 层：依赖 parser 指令形态；core 只吃 Abs 绑定。
  */
 
 type AbsMockSeeds = {
@@ -732,242 +215,271 @@ type AbsMockSeeds = {
         async?: boolean;
         fingerprint?: string;
     }>;
+    /** `@nudo:mock name from "path"` 解析失败（缺文件 / 缺绑定 / 求值失败）——fail-closed 诊断用 */
+    fromErrors?: FromMockError[];
+};
+type FromMockError = {
+    name: string;
+    fromPath: string;
+    message: string;
 };
+/**
+ * B 路径注入用：seedVars + seedFns 统一为 Abs 函数绑定。
+ * arrowFn mock 落在 seedFns（AST body，供 ast-eval），B 路径的
+ * envGlobals 注入只吃 Abs——不合并会把 mock 丢掉，函数体内的调用
+ * 会落到真实原生函数（如 fetch 拿 Abs 当 URL，直接崩）。
+ */
+declare function mockSeedsToAbsMocks(seeds: AbsMockSeeds): Record<string, Abs>;
 /** 从函数上的 @nudo:mock 指令收集 Abs seed */
 declare function mockDirectivesToAbsSeeds(functions: Array<{
     directives: FunctionWithDirectives["directives"];
-}>): AbsMockSeeds;
+}>, opts?: {
+    /** `@nudo:mock name from "path"` 相对解析基准（被分析文件） */
+    fromFile?: string;
+    /** 自定义装载器（LSP buffer-aware）；缺省 defaultLoadModule */
+    loadModule?: LoadModule;
+}): AbsMockSeeds;
+/** 便捷入口：源码 → @nudo:mock 的 B 注入 Abs 绑定（checkSource 注入管线用） */
+declare function mockSeedsForSource(source: string, opts?: {
+    fromFile?: string;
+    loadModule?: LoadModule;
+}): Record<string, Abs>;
 
 /**
- * `nudo interface` 的打印数据源（design-refine-derivation §11 第 0 步）：
- * 逐顶层函数展示有效契约分层——effectiveInterface 命中（手写契约 / 侧车
- * 生成段）时 params/returns 用 formatConstraint 组合式显示；未命中走
- * implicit：优先 CaseResult.argAbs / FunctionAnalysis.combinedAbs（无损
- * Abs 源），展示用 formatShape（外延口径，不强求约束式、不带 conf）。
+ * `@nudo:mock-module "spec" from "./mock.js"` — file-level module replacement.
+ * Full replace swaps the specifier's exports table; partial `{ a, b }` only
+ * overlays those named exports and lets the rest fall through.
  *
- * autoBind 沿 package.json#nudo.interface（findProjectConfig → interfaceConfig）
- * 下传，可用 opts 覆盖（测试 / CLI 显式开关）；读盘用 defaultLoadModule
- * （与 check 的 refine 解析同一扩展名表）。
+ * Fail-closed: missing mock file / eval failure / empty binding → error, not
+ * a silent drop and not invented types.
  */
 
-type InterfaceSurfaceEntry = {
-    fn: string;
-    /** 本文件 named export（自动绑定边界口径：localNamedExports） */
-    kind: "export" | "local";
-    source: "handwritten" | "generated" | "implicit";
-    params: Array<{
-        name: string;
-        display: string;
-    }>;
-    returns?: string;
-};
-type InterfaceSurfaceOpts = {
-    /** 覆盖项目配置的 autoBind（默认 findProjectConfig → interfaceConfig） */
-    autoBind?: boolean;
-    /** 模块源码装载器（测试注入）；默认 defaultLoadModule 真实读盘 */
-    loadModule?: LoadModule;
-    /** 跨文件调用记录（--callsites 采集）：implicit 展示的实参域原料 */
-    records?: CallRecord[];
+type MockModuleApplyResult = {
+    modules: Record<string, AbsModuleExports>;
+    errors: FromMockError[];
+    /** true when at least one mock-module directive was applied */
+    applied: boolean;
 };
-/** 单条 interface 打印行（CLI runInterface 与 LSP agent 面共用） */
-declare function formatInterfaceSurfaceLine(e: InterfaceSurfaceEntry): string;
 /**
- * 单文件 interface 表面：analyzer 推断结果给出函数清单与 implicit 展示，
- * effectiveInterface 给出契约命中（手写 > 生成段）。诊断 side-channel
- * 在收尾时取走丢弃——打印命令不执法，interface-load 等错误留给 check 路径。
+ * Overlay `@nudo:mock-module` directives onto a modules map.
+ * `base` is not mutated; a new map is returned.
  */
-declare function interfaceSurface(filePath: string, opts?: InterfaceSurfaceOpts): Promise<InterfaceSurfaceEntry[]>;
+declare function applyMockModuleDirectives(base: Record<string, AbsModuleExports>, fileDirectives: FileDirective[], opts: {
+    fromFile: string;
+    loadModule?: LoadModule;
+}): MockModuleApplyResult;
+/** Source string → apply mock-module (CLI / one-shot hosts). */
+declare function applyMockModuleDirectivesFromSource(source: string, base: Record<string, AbsModuleExports>, opts: {
+    fromFile: string;
+    loadModule?: LoadModule;
+}): MockModuleApplyResult;
 
 /**
- * `nudo interface --emit` 的写盘器（design-refine-derivation §5.4 / §7.3 / §11）：
- * 把分析产出的调用点域投影（joinThenProject，先 Abs join 再投影）固化为侧车
- * `*.nudo.js` / `*.nudo.ts` 的 `@generated` 段——`export const <fn> = fn({…}, …)`。
+ * B5：workspace 级 AnalysisSession——LSP 与 CLI（同进程）共享的分析 memo 面。
  *
- * - 生成段 = 三行：`@generated` 头注释 + `// source: <相对file>:<fn>` + export 行。
- *   DSL 由 formatConstraint 产出，**写入前 round-trip 自检**（生成文本经
- *   execNudoModule 求值、导出须 isNudoConstraint 且 fn 槽存在）：展示兜底形态
- *   （`x?:` 可选字段、`.eq()` 伪链、`{谓词原文}`）不是合法 DSL，自检拦下 →
- *   not-projectable 跳过，不写垃圾。
- * - 手写导出永不覆盖：目标名已是侧车手写绑定 → 跳过写入并报
- *   `nudo:interface-name-clash`（error，手写优先）。
- * - mode=update：剥离全部生成段再重排（幂等；非目标的既有生成段原样保留，
- *   不随 --fn 丢失）；mode=add：仅追加缺失段。
- * - 目标过滤（§7.3）：--fn 白名单 > --all 全量 > 默认只刷新已有生成段
- *   （「无根只处理已存在生成段」；Phase 1 无 root 闭包下行推导）。
- * - autoBind=false 不影响 emit（显式动作，非 ambient 加载）。
- */
-
-type EmitInterfaceSkipReason = "name-clash" | "not-projectable" | "not-an-export" | "no-change"
-/** package.json#nudo.interface.emit 白名单拒绝 */
- | "emit-denied"
-/** 手工合并的多声明符 @generated 段：按段原子保留，不拆不重写 */
- | "multi-declarator";
-type EmitInterfaceOpts = {
-    /** 目标导出名白名单（Phase 1：只过滤目标文件自身的导出；跨文件 root 闭包 emit 是 Phase 2 下行推导能力） */
-    fnNames?: string[];
-    /** update=剥离全部生成段再重排（幂等）；add=仅追加缺失段 */
-    mode: "add" | "update";
-    /** 全部顶层导出（显式 opt-in，CLI 侧文档警告勿默认） */
-    all?: boolean;
-    /** 不写盘，返回 unifiedDiff */
-    dryRun?: boolean;
-    /**
-     * 跨文件调用记录（--callsites 采集）：域根导出（本文件无调用点、仅有
-     * 外部使用现场记录）的投影原料；缺省时仅用本文件调用点证据。
-     */
-    records?: CallRecord[];
-};
-type EmitInterfaceResult = {
-    written: string[];
-    skipped: Array<{
-        fn: string;
-        reason: EmitInterfaceSkipReason;
-    }>;
-    changed: boolean;
-    diff?: string;
-    issues: Array<{
-        code: string;
-        severity: "error" | "warning";
-        message: string;
-    }>;
-    /** 侧车绝对路径（新建或已有） */
-    sidecarPath: string;
+ * core/service 的 analyzeFile / B-path / generalize / checkSource 都是
+ * 进程级模块缓存；本模块把「清空 / 定向逐出 / 依赖变更」收成一个显式
+ * session 对象，避免宿主各接一套失效逻辑，也便于测试隔离。
+ *
+ * 宿主契约：
+ * - 依赖内容变更 → `session.evictForDependents(files)`
+ * - 全量重置（watch 批前 / vite buildStart）→ `session.clear()`
+ * - LSP validate 与 agent check/hover/interface 在同一进程共用默认 session
+ */
+
+type AnalysisSession = {
+    /** 依赖变更：按「以这些文件为入口」的路径定向逐出 */
+    evictForDependents(files: string[]): void;
+    /** 清空 service+core 会话 memo（不含 AST LRU） */
+    clear(): void;
+    /** 彻底重置（含 AST LRU） */
+    reset(): void;
     /**
-     * 默认过滤（无 --fn/--all）且侧车无既有 @generated 段可刷 —— 调用方
-     * 用它把「no interface changes」解释成首次 emit 的用法提示，而非漂移。
+     * 与 analyzeFile 同源，但强制走本 session 的 memo（进程内默认即共享）。
+     * LSP / CLI / agent 工具都应调用这里，而不是旁路第二套缓存。
      */
-    emptyDefaultTargets?: boolean;
+    analyze(filePath: string, source: string, activeCases?: Map<string, number>, externalCallRecords?: unknown): AnalysisResult;
 };
+/** 进程内默认 AnalysisSession（LSP server / CLI watch / agent tools 共用） */
+declare function getAnalysisSession(): AnalysisSession;
+/** 测试：替换默认 session（返回旧值以便恢复） */
+declare function setAnalysisSession(session: AnalysisSession | undefined): AnalysisSession | undefined;
+
+declare function clearAnalysisFileCache(): void;
+declare function getAnalysisFileCacheSize(): number;
+/** 立刻压到当前 maxFiles（调低上限时收内存） */
+declare function trimAnalysisFileCache(): void;
+/** 依赖变更后：按入口文件逐出 */
+declare function evictAnalysisFileCacheForFiles(files: string[]): number;
+
+/**
+ * 会话级内存 LRU 上限（进程内，非磁盘 cache）。
+ * 多项目开 LSP 时用 env 封顶内存；单大仓可调高换 warm 命中。
+ *
+ * 优先级：setSessionCacheLimits（显式）> env > package.json#nudo.sessionCache > 默认
+ *
+ * 覆盖面：analysis-file-cache（maxFiles）/ fn-analysis-cache（maxFns）/
+ * bpath-run（maxBRuns）。其余驻留结构（harvest-auto / harvest-node /
+ * abs-modules-graph / env-loader path-env / env-path-deps）用各自的硬上限常量，
+ * 见各文件与 lru-map.ts。所有上限加起来给出大仓分析后 retained 内存的上界。
+ */
+type SessionCacheLimits = {
+    /** 整文件 AnalysisResult LRU；0 = 关闭 */
+    maxFiles: number;
+    /** per-fn FunctionAnalysis LRU；0 = 关闭 */
+    maxFns: number;
+    /** B-path run LRU；0 = 关闭 */
+    maxBRuns: number;
+};
+/** 保守默认：多项目共存时不悄悄吃内存（大仓请显式调高） */
+declare const DEFAULT_SESSION_CACHE_LIMITS: SessionCacheLimits;
+type PartialLimits = Partial<SessionCacheLimits>;
+declare function getSessionCacheLimits(env?: NodeJS.ProcessEnv): SessionCacheLimits;
+/** 显式覆盖（宿主 / 测试）。传 null 清除显式层 */
+declare function setSessionCacheLimits(partial: PartialLimits | null): SessionCacheLimits;
+/** package.json#nudo.sessionCache 层（findProjectConfig / 宿主接线） */
+declare function setSessionCacheFromProject(partial: PartialLimits | null | undefined): void;
+/** 测试：丢弃 env 惰性缓存，重新读 process.env */
+declare function resetSessionCacheLimitState(): void;
+
 /**
- * 单文件 emit：分析 → 逐目标投影/自检 → 组装侧车内容 →（非 dryRun）写盘。
- * 诊断 side-channel（round-trip 自检触发的 refine/interface diags）收尾取走丢弃。
+ * 依赖内容变更后：按入口文件定向逐出 service 层缓存。
+ * 调用方应传「以这些文件为入口」的路径（脏集里的 dependents），
+ * 而不是变更的 dep 文件本身——dep 自己 source 变了会自然 miss。
+ * 残余缺口：absModuleCache 按 dep 路径 + mtime/size 键控；「同 size + 同 mtime」
+ * 编辑需再 evictAbsModuleCacheFiles([depPath]) 或 clearAnalysisSessionCaches。
  */
-declare function emitInterface(filePath: string, opts: EmitInterfaceOpts): Promise<EmitInterfaceResult>;
+declare function evictAnalysisCachesForFiles(files: string[]): void;
 /**
- * emit 摘要行（CLI runInterfaceEmit 与 LSP agent 面共用；路径由调用方按
- * 展示口径传入——CLI 传 cwd 相对、agent 传绝对路径）。
+ * 清空全部会话级分析缓存（service + core）。
+ * 适用于：CLI watch 增量批前、vite buildStart / watchChange、测试隔离。
+ * 比定向逐出重，但保证无陈旧命中；单次 analyze 内部的 per-fn / generalize
+ * memo 不受影响（它们在同一轮里先写后读）。
  */
-declare function formatEmitSummary(sourcePath: string, sidecarRel: string, result: EmitInterfaceResult): string[];
-
+declare function clearAnalysisSessionCaches(): void;
 /**
- * Root 驱动的契约下行（design-refine-derivation §4.2 / §11 Phase 2）。
- *
- * 对含手写契约根的文件（lib.nudo.js 绑定 add4）：
- *   1. 从侧车 AST 抽出参数约束的源表达式（`positive` ← `./std.nudo.js`）；
- *   2. constraintToEntryAbs + tagDerivationRoot；
- *   3. analyzeFn 求值 body（模块图注入下游），收集调用记录 + 推导打点；
- *   4. 闭包内下游导出投影为组合式 DSL，禁止事后从 Abs 反编译链。
- *
- * check 分轨：每条 root 链独立；join 只用于工件聚合（多调用者）。
+ * 接线 package.json#nudo.sessionCache（进程内 LRU 上限）并立刻 trim。
+ * env `NUDO_CACHE_MAX_FILES|FNS|BRUNS` 仍优先（多项目内存封顶）。
  */
+declare function applySessionCacheConfig(config: NudoConfig | null | undefined): SessionCacheLimits;
+/** 比 clearAnalysisSessionCaches 更彻底：再丢 AST LRU（测试 / 进程复用场景） */
+declare function resetAllAnalysisCaches(): void;
 
-type ConstraintSourceExpr = {
-    expr: string;
-    importFrom?: string;
-    importName?: string;
-};
-type DerivedParam = {
-    name: string;
-    constraint: NudoConstraint;
-    dsl: string;
-    prelude: string[];
-    imports: Array<{
-        name: string;
-        from: string;
+/**
+ * 磁盘内容寻址缓存（B3，design-persistent-cache.md L1 骨架）。
+ * - 键：sha256(analysisAbi + relative paths + content hashes + import deps)
+ * - fail-open：读写失败/版本不符 → miss，绝不 throw
+ * - 不存 Abs；只存可 JSON 再执行投影（如 CheckJson）
+ * - 缓存根解析见 `evaluator/config.ts` 的 `diskCacheRoot`（唯一入口）
+ *
+ * 内存上界：本层不持有进程内 map——每次 get/set 直读/直写磁盘，retained
+ * heap O(1)。磁盘容量不在本层封顶（由宿主/CI 清理 `diskCacheRoot`）。
+ * 进程内 LRU 上界见 session-cache-limits / lru-map.ts（analysis/fn/bpath/
+ * harvest/abs-module/path-env）。
+ */
+/**
+ * 带包版本：升级 @nudojs/* 后旧 CheckJson 不得继续命中。
+ * 语义大改仍可手工再抬 major（`nudo-check-cache-v3`）。
+ */
+declare const ANALYSIS_ABI: string;
+type DiskCacheOptions = {
+    /** 缓存根目录；undefined = 禁用 */
+    root?: string | undefined;
+    /** 命名空间子目录（check / interface …） */
+    namespace: string;
+};
+declare function sha256Hex(data: string | Buffer): string;
+/** 相对化路径，避免绝对路径进磁盘键；树外路径用稳定内容 hash */
+declare function relativizePath(p: string, root?: string): string;
+declare class DiskCache {
+    private readonly root;
+    private readonly ns;
+    enabled: boolean;
+    constructor(opts: DiskCacheOptions);
+    private pathFor;
+    get<T>(key: string): T | undefined;
+    set(key: string, value: unknown): void;
+    clearNamespace(): void;
+}
+/**
+ * check 报告键：abi + 相对路径 + 源码 sha + autoBind + **侧车 sha** +
+ * **@nudo:import / 传递契约依赖内容 sha**（依赖变更必须 miss）。
+ * dep 路径同样相对化（`relativizePath`）：绝对路径进键会让同内容在不同
+ * 机器/checkout 上键不同，缓存无法跨环境复用。
+ */
+declare function checkCacheKey(filePath: string, source: string, opts: {
+    autoBind: boolean;
+    projectDir?: string;
+    sidecarContent?: string | null;
+    depContents?: Array<{
+        path: string;
+        content: string | null;
     }>;
-    /** 单链组合式投影时的推导图 root 节点 id（返回位相对锚定用） */
-    rootNodeId?: number;
-    /** 该参数位自 root 起消耗的 shift 步数（与 prelude 行数无关，读图） */
-    shiftCount?: number;
-};
-type DerivedExport = {
-    file: string;
-    fn: string;
-    paramNames: string[];
-    params: DerivedParam[];
-    returns?: {
-        constraint: NudoConstraint;
-        dsl: string;
-        prelude: string[];
-        imports: Array<{
-            name: string;
-            from: string;
-        }>;
+    /** package.json#nudo.env 等项目维（named env 不在 path-dep 指纹里） */
+    projectEnvNames?: string[];
+    /** analysis knobs that can change check surface */
+    analysisCfg?: {
+        mode?: string;
+        evalMissingSlot?: string;
+        callSiteBudget?: number;
+        entryThrows?: string;
+        ignoreThrows?: string;
     };
-    /** `lib.js:add4` */
-    derivedFrom: string;
-    compositional: boolean;
-    underivable?: boolean;
-};
-type RootDeriveOpts = {
-    loadModule?: LoadModule;
-    autoBind?: boolean;
-    fnNames?: string[];
-    /**
-     * true：只刷新目标侧车里**已存在**的 @generated 段（CLI 无 --fn/--all 时
-     * 的默认行为——不发明新下游契约）。false/省略：闭包内全部可推导导出。
-     */
-    refreshExistingOnly?: boolean;
-};
-type RootDeriveResult = {
-    roots: string[];
-    derived: DerivedExport[];
-    hasRoot: boolean;
-};
-/** 从侧车源码抽出 `export const f = fn({ x: positive }, ret)` 的约束源表达式 */
-declare function extractFnConstraintSources(sidecarSrc: string, fnName: string): {
-    params: Record<string, ConstraintSourceExpr>;
-    returns?: ConstraintSourceExpr;
-};
-/**
- * 入口：对 filePath 做 root 驱动下行推导。
- */
-declare function deriveFromRoot(filePath: string, opts?: RootDeriveOpts): RootDeriveResult;
+}): string;
+/**
+ * effectiveInterface 表键（L1 Phase B，design-persistent-cache）。
+ * 维度：相对路径 + 源码 sha256 + autoBind + 侧车内容 sha256 + import 依赖
+ * （dep 路径相对化，与 checkCacheKey 同口径）。
+ * **不含** emit allowlist（白名单不影响契约读取）。
+ */
+declare function ifaceCacheKey(filePath: string, source: string, opts: {
+    autoBind: boolean;
+    projectDir?: string;
+    /** 侧车源码（已读入）；undefined = 无侧车或 autoBind 关 */
+    sidecarSource?: string | undefined;
+    depContents?: Array<{
+        path: string;
+        content: string | null;
+    }>;
+    projectEnvNames?: string[];
+}): string;
+/** 从源码提取 `@nudo:import` / `@nudo:import * as` 的 specifier */
+declare function extractNudoImportSpecs(source: string): string[];
+
 /**
- * 组装生成段（组合式 + import + prelude）。
- * importFrom 相对 root 侧车解析，再相对 target 侧车写出。
+ * nudo 推断目标文件判定（纯扩展名规则，路径无需存在）。
+ *
+ * 规则：.js / .mjs / .ts 可作为推断目标；其余扩展（.cjs/.tsx/.jsx/.mts/.d.ts…）
+ * 一律 false。显式排除：
+ *  - .d.ts —— 类型声明文件（harvester 的输入），不是可求值的实现源码；
+ *  - .tsx / .jsx —— JSX 构造的求值超出 nudo 推断器范围；
+ *  - *.nudo.js / *.nudo.mjs / *.nudo.ts —— 侧车契约模块（interface 绑定源），
+ *    不是源码推断目标；目录级 check/infer/doctor 展开不得把它们当实现分析；
+ *  - *.nudo.draft.js / *.nudo.draft.mjs / *.nudo.draft.ts —— draft 产物，
+ *    明确不被 ambient 绑定，也不得当实现源码分析。
  *
- * `takenNames`：侧车顶层已占用标识符（手写 / 既有生成段 / 本批先前段）。
- * 同文件多导出时对 import local 与 prelude local 做避让改写，
- * 保证拼出的侧车在模块作用域内无重复声明。
+ * 消费方：CLI 的 collectNudoFiles/watch 过滤/doctor 目录展开（.ts 放开后统一
+ * 走本函数，避免各处手写 endsWith 漂移），以及 LSP 的 isNudoFile（接线由
+ * LSP 侧负责）。
  */
-declare function formatDerivedSection(row: DerivedExport, opts: {
-    rootSidecarDir: string;
-    targetSidecarDir: string;
-    takenNames?: Iterable<string>;
-}): {
-    text: string;
-    usedNames: string[];
-} | undefined;
-type EmitDerivedResult = {
-    /** 被写/将写的下游侧车（绝对路径） */
-    sidecars: Array<{
-        file: string;
-        sidecarPath: string;
-        fn: string;
-        written: boolean;
-        changed: boolean;
-        skipped?: "name-clash" | "not-projectable" | "underivable" | "no-change";
-        diff?: string;
-        issues: Array<{
-            code: string;
-            severity: "error" | "warning" | "info";
-            message: string;
-        }>;
-    }>;
-    hasRoot: boolean;
-    roots: string[];
-    /** 根在别处 / 无契约根且无已存在生成段 → info */
-    entryOnly?: boolean;
-};
-declare function emitDerivedFromRoot(rootFile: string, opts: {
-    fnNames?: string[];
-    mode: "add" | "update";
-    dryRun?: boolean;
-    loadModule?: LoadModule;
-    autoBind?: boolean;
-    /** 只刷新目标侧车里已存在的 @generated 段（不发明新下游契约） */
-    refreshExistingOnly?: boolean;
-}): EmitDerivedResult;
+declare function isNudoTargetPath(path: string): boolean;
 
-export { type AbsGraphOptions, type AbsMockSeeds, type AbsModuleCacheEntry, type AbsModuleGraphResult, type AbsModuleLoadIssue, type AnalysisResult, type BPathBuiltinUnknown, type BPathDiagnostics, type BPathRunResult, type BPathUnreachable, type BindingInfo, CallRecord, type CaseHint, type CaseInfo, type CaseResult, type CompletionItem, type ConstraintSourceExpr, type DerivedExport, type DerivedParam, type Diagnostic, type DiagnosticSeverity, type DiagnosticTag, type EmitDerivedResult, type EmitInterfaceOpts, type EmitInterfaceResult, type EmitInterfaceSkipReason, type EmitResult, type EmitSkipReason, type FunctionAnalysis, type HoverInfo, type InferJson, type InferJsonCase, type InferJsonFunction, type InterfaceSurfaceEntry, type InterfaceSurfaceOpts, type LoadModule, type ModuleExports, type ModuleGraphCache, type NodeEnvResult, type PackageHarvest, type ReferenceInfo, type RootDeriveOpts, type RootDeriveResult, SEMANTIC_TOKEN_MODIFIERS, SEMANTIC_TOKEN_TYPES, type SemanticToken, type SourceLocation, type SymbolInfo, type SymbolTable, absToTSType, absToZodSchema, analyzeExportsFromSource, analyzeFile, analyzeFileAsync, autoHarvestModules, barePackageName, bareSpecToAbsModules, buildCaseDirective, buildModuleGraph, buildSemanticTokens, clearAbsModuleCache, clearAnalysisFileCache, clearAnalysisSessionCaches, clearBPathCache, clearFnAnalysisCache, clearHarvestCache, collectAbsBindingsFromGraph, collectBPathDiagnostics, collectBPathReplacements, collectBarePackages, collectCallRecords, collectDependencySpecs, collectDtsFromEntry, collectEnvGlobals, collectEnvModules, collectStaticImports, computeDirtySet, defaultAbsLoadModule, defaultLoadModule, deriveFromRoot, emitDerivedFromRoot, emitInterface, encodeSemanticTokens, evalAbsModuleGraph, evalProgramAbsWithModules, evictAbsModuleCacheFiles, evictAnalysisCachesForFiles, evictAnalysisFileCacheForFiles, evictBPathCacheForFiles, evictFnAnalysisCacheForFiles, extractFnConstraintSources, formatDerivedSection, formatEmitSummary, formatHarvestSummary, formatInterfaceSurfaceLine, generateDts, generateFunctionDtsLines, generateGuardFunction, generateGuardFunctionFromAbs, getAbsAtPosition, getAbsAtPositionAsync, getAnalysisFileCacheSize, getCasesForFile, getCompletionsAtPosition, getHoverAtPosition, getTypeAtPosition, getTypeAtPositionAsync, harvestNodeTypes, harvestPackage, harvestPackageCached, harvestToAbsModules, harvestedValueToAbs, insertGeneratedCaseDirectives, interfaceSurface, isBPathCapable, isNudoTargetPath, lookupHarvested, mockDirectivesToAbsSeeds, packageHarvestToAbsModules, resetAllAnalysisCaches, resolvePackageRoot, serializeCaseArg, serializeInferJson, stripGeneratedCaseDirectives, summarizeNodeEnv, topoSortDirty, tryBPathCall, tryBPathCallFull, tryRunBPath, unifiedDiff };
+/** Formal sidecar contracts only — drafts never ambient-bind and need not reanalyze */
+declare function isSidecarPath(path: string): boolean;
+declare function isProjectConfigPath(path: string): boolean;
+/** Watch accept gate: analysis targets + sidecar/config/env-template invalidators */
+declare function isWatchRelevantPath(path: string): boolean;
+/** `lib.nudo.js|ts` → candidate ambient sources next to it */
+declare function ambientSourcesOfSidecar(sidecarPath: string): string[];
+
+/** 测试/诊断：反向依赖驻留规模 */
+declare function getEnvPathDepsSize(): number;
+/** 源码里的 path-based load specs 解析为绝对路径后登记反向边 */
+declare function noteEnvPathDeps(sourcePath: string, source: string): void;
+/** 依赖该 env 模板的源文件列表 */
+declare function envPathDependents(envPath: string): string[];
+declare function clearEnvPathDeps(): void;
+/** watch 门禁：env 模板变更必须可被接收（即便扩展名不进 isNudoTargetPath） */
+declare function isEnvTemplatePath(path: string): boolean;
+
+export { ANALYSIS_ABI, type AbsMockSeeds, AnalysisResult, type AnalysisSession, type BPathBuiltinUnknown, type BPathDiagnostics, type BPathUnreachable, CallRecord, DEFAULT_SESSION_CACHE_LIMITS, type DepContent, DirectiveCaseMode, DiskCache, type DiskCacheOptions, type EntryVariantInfo, type EntryVariantIssue, LoadModule, type MockModuleApplyResult, type ModuleExports, NudoConfig, type SessionCacheLimits, ambientSourcesOfSidecar, analysisFileCacheKey, analyzeExportsFromSource, applyMockModuleDirectives, applyMockModuleDirectivesFromSource, applySessionCacheConfig, checkCacheKey, clearAnalysisFileCache, clearAnalysisSessionCaches, clearEnvPathDeps, clearFnAnalysisCache, collectBPathDiagnostics, collectDependencySpecs, collectLoadDepContents, collectSkipReturns, collectStaticImports, detectEntryVariantsFromPackageJson, entryVariantForFile, entryVariantIssueForFile, envPathDependents, evictAnalysisCachesForFiles, evictAnalysisFileCacheForFiles, evictFnAnalysisCacheForFiles, extractNudoImportSpecs, findOwningPackage, getAnalysisFileCacheSize, getAnalysisSession, getEnvPathDepsSize, getFnAnalysisCacheSize, getSessionCacheLimits, ifaceCacheKey, isEnvTemplatePath, isNudoTargetPath, isProjectConfigPath, isSidecarPath, isWatchRelevantPath, mockDirectivesToAbsSeeds, mockSeedsForSource, mockSeedsToAbsMocks, noteEnvPathDeps, relativizePath, resetAllAnalysisCaches, resetSessionCacheLimitState, setAnalysisSession, setSessionCacheFromProject, setSessionCacheLimits, sha256Hex, trimAnalysisFileCache, trimFnAnalysisCache };