@nudojs/service 1.0.1 → 3.0.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { Node, File } from '@babel/types';
-import { Abs, PolyFn, AbsModuleExports, AstEnv, Phi, BMemberDiag, BCallRecord, TranspiledCallResult, NudoConstraint } from '@nudojs/core';
+import { FormalParam, Abs, InterfaceSource, InterfaceTierOpts, 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 { C as CallRecord, D as DiagnosticsLevel, A as AnalysisConfig } from './config-Cqj8zeZH.js';
+export { a as AnalysisMode, b as DEFAULT_ANALYSIS_MODE, I as InterfaceConfig, N as NudoConfig, c as analysisConfig, d as clearPathEnvCaches, e as diskCacheRoot, f as findProjectConfig, i as interfaceConfig, m as matchesEmitAllowlist } from './config-Cqj8zeZH.js';
 import { HarvestedEnv } from '@nudojs/harvester';
 import { FunctionWithDirectives } from '@nudojs/parser';
 
@@ -76,6 +76,8 @@ type FunctionAnalysis = {
     name: string;
     loc: SourceLocation;
     paramNames: string[];
+    /** C4.1 形参表面：draft/契约对齐（解构 placeholder + bound 名） */
+    formals?: FormalParam[];
     cases: CaseResult[];
     /** cases 结果 Abs 的 join；dts 返回位源 */
     combinedAbs?: Abs;
@@ -90,6 +92,24 @@ type FunctionAnalysis = {
     noDeclaration?: boolean;
     /** absolute path of the module this function is imported from (externalFunctions only) */
     fromModule?: string;
+    /**
+     * HOF / entry shape 关系快照（generalizeFromAst），供 dts 泛型投影（C3.3）。
+     * 只存投影所需的 Abs，不挂 PolyFn 本体（缓存可克隆）。
+     */
+    hof?: {
+        /** 函数形参：外延关系 Abs（fn 形状，paramTypes/returnType） */
+        fnRels?: Array<{
+            param: string;
+            abs: Abs;
+        }>;
+        /** 值形参提升快照（如 items → arr(A1)） */
+        entryShapes?: Array<{
+            param: string;
+            abs: Abs;
+        }>;
+        /** 符号返回 Abs（含自由 α / B:param） */
+        symbolic?: Abs;
+    };
 };
 type BindingInfo = {
     /** 无损 Abs */
@@ -152,14 +172,18 @@ declare function buildModuleGraph(files: string[], cache?: ModuleGraphCache): {
 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[];
+/** Optional module loader for analysis (sidecar / relative imports). */
+type AnalyzeLoadModule = (spec: string, fromFile: string) => string | undefined;
 /**
  * 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).
+ * preloaded factories up from the env-loader cache.
+ * `loadModule` is optional; when provided it is used for relative imports /
+ * sidecar ambient bindings (LSP buffer-aware path). Default remains
+ * `defaultLoadModule` (disk).
  */
-declare function analyzeFileAsync(filePath: string, source: string, activeCases?: Map<string, number>, externalCallRecords?: CallRecord[]): Promise<AnalysisResult>;
+declare function analyzeFileAsync(filePath: string, source: string, activeCases?: Map<string, number>, externalCallRecords?: CallRecord[], loadModule?: AnalyzeLoadModule): Promise<AnalysisResult>;
 /**
  * 调用点发现（阶段一）：在"使用现场"文件（测试 / 上层应用）中求值
  * 顶层代码，收集它对（外部模块导出的）函数的调用记录。每条记录带
@@ -171,16 +195,32 @@ declare function analyzeFileAsync(filePath: string, source: string, activeCases?
  * 依赖未 mock 的全局，收集不到就收集不到，不能拖垮主分析）。
  */
 declare function collectCallRecords(filePath: string, source: string): CallRecord[];
+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): {
+    filePath: string;
+    source: string;
+    auxKey: string;
+    noCache?: boolean;
+};
 /**
  * 整文件分析。同 (path, source, cases, external) 命中 memo → O(1)。
  * 不再每次 clearBPathCache：B 路径按本文件 source 键控。
  *
+ * `loadModule`：可选；提供时用于相对 import / 侧车 ambient（LSP
+ * buffer-aware）。未提供时走 defaultLoadModule（磁盘）。
+ *
  * 宿主契约：入口 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;
+declare function analyzeFile(filePath: string, source: string, activeCases?: Map<string, number>, externalCallRecords?: CallRecord[], loadModule?: AnalyzeLoadModule): AnalysisResult;
 
 type CaseInfo = {
     functionName: string;
@@ -214,7 +254,13 @@ type HoverInfo = {
     abs?: string;
     /** 无损 Abs 多行展示 */
     absMultiline?: string;
+    /** CodeLens `● interface` 同源档位（A7）；仅本地 named export */
+    interfaceSource?: InterfaceSource;
+    /** 有效契约展示（handwritten/generated）；implicit 为 undefined */
+    interfaceDisplay?: string;
 };
+/** A7：hover/inlay 与 CodeLens interface 档同源（design-refine-derivation §8） */
+type HoverInterfaceOpts = InterfaceTierOpts;
 /**
  * LSP hover：优先无损 Abs（类型即计算本体）。
  * 节点表也是 Abs（collectAbsNodeTypes），不经 bridge。
@@ -223,8 +269,12 @@ type HoverInfo = {
  * intension 一律走 generalize/formatPoly（HOF fnRels 在这里）；
  * typeText 仍落 B-path Abs（调用点显示结果类型，不是函数签名）。
  * 禁止用 B-path 的 arity-only fn Abs 冒充权威关系源。
+ *
+ * A7 default 档：函数名 hover 附带 interfaceTierOf 来源 + 契约展示，
+ * 与 CodeLens `● interface / <source>` 同源；选 case 时 body 仍走
+ * activeCases 重放，interface 档标注不变。
  */
-declare function getHoverAtPosition(filePath: string, source: string, line: number, column: number, activeCases?: Map<string, number>): HoverInfo | null;
+declare function getHoverAtPosition(filePath: string, source: string, line: number, column: number, activeCases?: Map<string, number>, opts?: HoverInterfaceOpts): HoverInfo | null;
 declare function getCompletionsAtPosition(filePath: string, source: string, line: number, column: number): CompletionItem[];
 
 /**
@@ -305,8 +355,10 @@ declare function serializeInferJson(result: AnalysisResult, file: string): Infer
  * 一律 false。显式排除：
  *  - .d.ts —— 类型声明文件（harvester 的输入），不是可求值的实现源码；
  *  - .tsx / .jsx —— JSX 构造的求值超出 nudo 推断器范围；
- *  - *.nudo.js / *.nudo.ts —— 侧车契约模块（interface 绑定源），不是源码
- *    推断目标；目录级 check/infer/doctor 展开不得把它们当实现分析。
+ *  - *.nudo.js / *.nudo.mjs / *.nudo.ts —— 侧车契约模块（interface 绑定源），
+ *    不是源码推断目标；目录级 check/infer/doctor 展开不得把它们当实现分析；
+ *  - *.nudo.draft.js / *.nudo.draft.mjs / *.nudo.draft.ts —— draft 产物，
+ *    明确不被 ambient 绑定，也不得当实现源码分析。
  *
  * 消费方：CLI 的 collectNudoFiles/watch 过滤/doctor 目录展开（.ts 放开后统一
  * 走本函数，避免各处手写 endsWith 漂移），以及 LSP 的 isNudoFile（接线由
@@ -314,6 +366,51 @@ declare function serializeInferJson(result: AnalysisResult, file: string): Infer
  */
 declare function isNudoTargetPath(path: string): boolean;
 
+/** 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[];
+
+/** 源码里的 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;
+
+/**
+ * 分析范围判定（A1/A2，design-analysis-scope.md）。
+ * CLI 显式路径不受 mode 限制；本模块供 LSP/watch 自动验证使用。
+ */
+
+/**
+ * 按 analysis.diagnostics 档过滤 evaluator/check **显示路径**诊断。
+ * - off：显示层全静音（与 errors 档区分）。check 门禁（CLI `nudo check` /
+ *   checkSource）独立于本过滤，不受 off 影响。
+ * - errors：只发 severity=error
+ * - default：error + warning（静音 NOISY_WARNING_CODES）
+ * - verbose：全量
+ */
+declare function filterDiagnosticsByLevel<T extends {
+    severity: string;
+    code?: string;
+}>(diags: T[], level: DiagnosticsLevel): T[];
+declare function diagnosticsLevelForFile(filePath: string): DiagnosticsLevel;
+declare function hasNudoDirectives(source: string): boolean;
+/**
+ * 是否应对该文件跑分析（自动路径，如 LSP validate）。
+ * - 非 target 路径 → false
+ * - exclude 命中 / include 未命中 → false
+ * - mode=directives → 仅有指令
+ * - mode=exports → 指令 | export | 同名侧车
+ * - mode=all → true
+ */
+declare function shouldAnalyzeFile(filePath: string, source: string | undefined, config?: AnalysisConfig): boolean;
+
 /**
  * 相对/绝对 specifier → 模块源码。
  * CLI / LSP / vite / check 共用同一扩展名表，避免门禁结果分叉。
@@ -382,7 +479,7 @@ declare function lookupHarvested(h: PackageHarvest, moduleName: string, exportNa
  * 手动 `nudo harvest` 仍保留；这里是分析路径上的按需注入。
  */
 
-/** 裸说明符 → 包名（含 scope）；相对/绝对/node: 内建返回 undefined */
+/** 裸说明符 → 包名（含 scope）；相对/绝对/node: 与裸 Node 内建返回 undefined */
 declare function barePackageName(spec: string): string | undefined;
 declare function collectBarePackages(source: string): string[];
 declare function harvestPackageCached(pkg: string, fromDir: string): PackageHarvest | null;
@@ -476,6 +573,34 @@ declare function bareSpecToAbsModules(spec: string, fromFile: string): AbsModule
 declare function collectEnvGlobals(envNames: string[]): Record<string, Abs>;
 /** @nudo:env modules（path / node:path / fs…）→ AbsModuleExports */
 declare function collectEnvModules(envNames: string[]): Record<string, AbsModuleExports>;
+/** Conflict when handwritten env overwrote a harvest module/export (B8). */
+type EnvHarvestConflict = {
+    module: string;
+    /** export names where env replaced a harvest binding (empty + defaulted = default only) */
+    exports: string[];
+    defaultOverwritten: boolean;
+};
+/**
+ * Install conflict collector; returns the previous one so nested/concurrent
+ * analyzeFile callers can save/restore (module-global is not re-entrant).
+ */
+declare function setEnvHarvestConflictCollector(collector: ((c: EnvHarvestConflict) => void) | null): ((c: EnvHarvestConflict) => void) | null;
+/** Read-only peek for tests / nested restore. */
+declare function getEnvHarvestConflictCollector(): ((c: EnvHarvestConflict) => void) | null;
+type MergeHarvestOptions = {
+    /**
+     * Per-call conflict sink. Takes precedence over the module-global collector
+     * installed via `setEnvHarvestConflictCollector`.
+     */
+    onConflict?: (c: EnvHarvestConflict) => void;
+};
+/**
+ * Handwritten `@nudojs/env` wins over harvest / graph modules on overlapping
+ * module keys and overlapping export names (docs/versioning.md B8 + website
+ * harvester API). Harvest-only modules/exports are kept as fill-in.
+ * Overwrites notify `opts.onConflict` or the global collector.
+ */
+declare function mergeHarvestUnderEnv(harvestModules: Record<string, AbsModuleExports>, envModules: Record<string, AbsModuleExports>, opts?: MergeHarvestOptions): Record<string, AbsModuleExports>;
 /** 收集 @nudo:replace + @nudo:as → transpile 注入表 */
 declare function collectBPathReplacements(source: string): {
     targets: Array<{
@@ -565,6 +690,129 @@ declare function clearAnalysisSessionCaches(): void;
 /** 比 clearAnalysisSessionCaches 更彻底：再丢 AST LRU（测试 / 进程复用场景） */
 declare function resetAllAnalysisCaches(): void;
 
+/**
+ * B5：workspace 级 AnalysisSession——LSP 与 CLI（同进程）共享的分析 memo 面。
+ *
+ * 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;
+    /**
+     * 与 analyzeFile 同源，但强制走本 session 的 memo（进程内默认即共享）。
+     * LSP / CLI / agent 工具都应调用这里，而不是旁路第二套缓存。
+     */
+    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;
+
+/**
+ * 磁盘内容寻址缓存（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`（唯一入口）
+ */
+/**
+ * 带包版本：升级 @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;
+    }>;
+    /** package.json#nudo.env 等项目维（named env 不在 path-dep 指纹里） */
+    projectEnvNames?: string[];
+    /** analysis knobs that can change check surface */
+    analysisCfg?: {
+        mode?: string;
+        evalMissingSlot?: string;
+        callSiteBudget?: number;
+    };
+}): 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[];
+
+/**
+ * check/iface 磁盘缓存键的依赖内容采集。
+ * 走 core `loadModuleDepsFingerprint`：覆盖 ESM from / require / dynamic import /
+ * `@nudo:import` / ambient 侧车闭包——不只 `@nudo:import` 注释。
+ *
+ * 内容必须优先取 loadModule 解析结果（fingerprint.contents），不得回读磁盘：
+ * LSP buffer-aware loadModule 与自定义 loader 的内容可能与磁盘不一致，
+ * 回读会让缓存键分叉（buffer 编辑后仍命中磁盘旧内容）。
+ */
+type DepContent = {
+    path: string;
+    content: string | null;
+};
+declare function collectLoadDepContents(filePath: string, source: string, loadModule: (spec: string, fromFile: string) => string | undefined): {
+    depContents: DepContent[];
+    truncated: boolean;
+};
+
 /**
  * B 路径静态诊断（AST，不执行）：
  * - unreachable：同块 return/throw 之后的语句
@@ -601,18 +849,57 @@ declare function collectBPathDiagnostics(source: string, extraKnown?: Iterable<s
 /**
  * 预置 Node API env：从 @types/node 的 .d.ts harvest。
  * 与 packages/env 的手写 env 并行；此路径自动、可刷新。
+ *
+ * Productization (P0-B B2/B7):
+ * - In-process cache keyed by package root + package.json mtime/size.
+ * - Terminal failures (`not-found`/`no-dts`/`failed`) also cache — no retry storm.
+ *   `disabled` is never cached (env var can flip mid-process).
+ * - `clearNodeHarvestCache()` for tests / watch invalidation.
+ * - `NUDO_HARVEST_NODE=off` disables harvest (explicit skip, not silent).
+ * - Defaults stay IDE-budgeted: maxFiles=12, maxMs=2500.
  */
 
+/** IDE-startup budgets for @types/node harvest. Do not raise casually. */
+declare const HARVEST_NODE_DEFAULT_MAX_FILES = 12;
+declare const HARVEST_NODE_DEFAULT_MAX_MS = 2500;
+type HarvestNodeStats = {
+    files: number;
+    symbols: number;
+    skipped: number;
+};
 type NodeEnvResult = {
     ok: true;
     env: HarvestedEnv;
     root: string;
     files: number;
+    stats: HarvestNodeStats;
+    /** true when this result came from the in-process cache */
+    cached: boolean;
 } | {
     ok: false;
     error: string;
+    reason: "disabled" | "not-found" | "no-dts" | "failed";
+    /** true when this failure came from the in-process cache */
+    cached?: boolean;
 };
-/** harvest @types/node（限制文件数 + 时间预算，避免拖垮启动） */
+/**
+ * Clear the in-process @types/node harvest cache.
+ * Drops **success and terminal-failure** entries (including `not-found`), so
+ * a mid-session `@types/node` install becomes visible without process restart.
+ * Tests, watch-mode dep-hash invalidation, and package-manager hooks should
+ * call this when `node_modules/@types/node` changes underneath the process.
+ */
+declare function clearNodeHarvestCache(): void;
+/** Number of cached harvest results (diagnostics / tests). */
+declare function getNodeHarvestCacheSize(): number;
+declare function isHarvestNodeDisabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * harvest @types/node（限制文件数 + 时间预算，避免拖垮启动）。
+ * Success **and** terminal failures (`not-found` / `no-dts` / `failed`) are
+ * cached in-process so IDE analysis does not re-walk / re-timeout every file.
+ * `disabled` is never cached — the env var can flip mid-process.
+ * Call `clearNodeHarvestCache()` after `@types/node` changes.
+ */
 declare function harvestNodeTypes(fromDir?: string, maxFiles?: number, maxMs?: number): NodeEnvResult;
 /** 把 harvest 结果压成「模块名 → 导出名列表」摘要，便于日志/测试 */
 declare function summarizeNodeEnv(env: HarvestedEnv): {
@@ -626,10 +913,11 @@ declare function summarizeNodeEnv(env: HarvestedEnv): {
  * 与 LSP server capabilities 里声明的 legend 必须逐字对齐——server.ts 直接
  * 导入本常量注册，保证「提取端索引」与「客户端图例」单一来源。
  * 顺序沿用 lsp 包原 legend（function/variable/parameter/property 在前），
- * 末尾追加 method（对象字面量方法键），只追加不重排，客户端索引稳定。
+ * 末尾追加 method（对象字面量方法键）与 interface 档 modifier（A7），
+ * 只追加不重排，客户端索引稳定。
  */
 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"];
+declare const SEMANTIC_TOKEN_MODIFIERS: readonly ["declaration", "readonly", "deprecated", "unreachable", "contract", "generated", "derived"];
 type SemanticToken = {
     line: number;
     char: number;
@@ -639,6 +927,11 @@ type SemanticToken = {
 };
 /** LSP 标准相对五元组编码：deltaLine/deltaStartChar/length/tokenType/tokenModifiers。 */
 declare function encodeSemanticTokens(tokens: SemanticToken[]): number[];
+/** A7：interface 档 → semantic token modifier（与 CodeLens 同源） */
+declare function interfaceTierModifierBit(src: InterfaceSource): number;
+type BuildSemanticTokensOpts = InterfaceTierOpts & {
+    loadModule?: (spec: string, fromFile: string) => string | undefined;
+};
 /**
  * 从源码提取 semantic tokens 并按 LSP 相对编码返回扁平 number[]。
  *
@@ -648,15 +941,24 @@ declare function encodeSemanticTokens(tokens: SemanticToken[]): number[];
  * - 函数声明/函数表达式的名字 → function；所有函数的参数 → parameter；
  * - 对象字面量的键：值为函数 → method，否则 property。
  *
+ * A7：本地 named export 的函数绑定额外带 interface 档 modifier
+ * （contract / generated / derived），与 CodeLens `● interface` 同源。
+ * 非导出绑定只带 declaration，不假装进档。
+ *
  * 推断优先 Abs 模块图绑定（TypeValue 退出主路径）；失败时复用
  * evaluateProgram。解析失败返回 []。
  */
-declare function buildSemanticTokens(filePath: string, source: string): number[];
+declare function buildSemanticTokens(filePath: string, source: string, opts?: BuildSemanticTokensOpts): number[];
 
-/** Abs → TS 类型串。有损：pred / 非 lit term 落到 shape 基类型。 */
-declare function absToTSType(a: Abs): string;
+/**
+ * Abs → TS 类型串。有损：pred / 非 lit term 落到 shape 基类型。
+ * `typeVars`：term var id → TS 类型参数名（HOF 泛型投影时传入；
+ * `any`+var 在此映射下渲染为该参数名，否则 `unknown`）。
+ */
+declare function absToTSType(a: Abs, typeVars?: Map<string, string>): string;
 /**
  * 为单个函数生成 .d.ts 声明行（JSDoc + 单一 widen 主签名）。
+ * 有 hof 关系时优先泛型投影（C3.3）；否则 case-widen。
  * service 的 generateDts 与 CLI `--dts`（infer/watch）共用本函数，
  * 两条路径输出保持一致。
  */
@@ -748,6 +1050,10 @@ declare function mockDirectivesToAbsSeeds(functions: Array<{
  * autoBind 沿 package.json#nudo.interface（findProjectConfig → interfaceConfig）
  * 下传，可用 opts 覆盖（测试 / CLI 显式开关）；读盘用 defaultLoadModule
  * （与 check 的 refine 解析同一扩展名表）。
+ *
+ * B3 Phase B：`nudo.cache` / NUDO_CACHE_DIR 打开时，整文件 effectiveInterface
+ * 表（含 implicit 负缓存 null）落盘；二次冷启动跳过侧车 exec / 契约合并。
+ * 缓存只服务打印/表面，不加速 B-path 分析（design-persistent-cache §0）。
  */
 
 type InterfaceSurfaceEntry = {
@@ -768,6 +1074,8 @@ type InterfaceSurfaceOpts = {
     loadModule?: LoadModule;
     /** 跨文件调用记录（--callsites 采集）：implicit 展示的实参域原料 */
     records?: CallRecord[];
+    /** 打开 buffer 覆盖磁盘源码（E5：agent/LSP 与 hover 同口径） */
+    source?: string;
 };
 /** 单条 interface 打印行（CLI runInterface 与 LSP agent 面共用） */
 declare function formatInterfaceSurfaceLine(e: InterfaceSurfaceEntry): string;
@@ -816,6 +1124,10 @@ type EmitInterfaceOpts = {
      * 外部使用现场记录）的投影原料；缺省时仅用本文件调用点证据。
      */
     records?: CallRecord[];
+    /** 缓冲源（E5：agent/LSP 与 validate 同源）；缺省读盘 */
+    source?: string;
+    /** 模块装载器（buffer-aware 侧车可见）；缺省 defaultLoadModule */
+    loadModule?: (spec: string, fromFile: string) => string | undefined;
 };
 type EmitInterfaceResult = {
     written: string[];
@@ -849,6 +1161,112 @@ declare function emitInterface(filePath: string, opts: EmitInterfaceOpts): Promi
  */
 declare function formatEmitSummary(sourcePath: string, sidecarRel: string, result: EmitInterfaceResult): string[];
 
+/**
+ * `nudo interface --draft`：从已有 JS **逻辑** 生成 interface 草稿。
+ *
+ * 产品位（代码优先 / 迁移）：先写实现，再反推可审阅的 `fn({…}, …)` 草稿；
+ * 人审后迁入 `*.nudo.js` 才成为契约。
+ *
+ * 证据分层（与 C0 一致：草稿 ≠ ambient 义务）：
+ * - callsite / directive case → joinThenProject 值域（迁移最可信）
+ * - body 触达（**仅草稿展示**）→ 参数上被读到的字段名建议；不进 check
+ * - generalize symbolic → 返回位兜底
+ * - 无证据 → 参数槽省略 + 注释 TODO（不发明义务）
+ * - 已有 handwritten 契约 → **跳过**（手写优先，不覆盖）
+ *
+ * 写盘：默认只打印；`--write` 写入 `<file>.nudo.draft.js`——**不会**被
+ * sidecar 自动绑定（loadModule 只认 `*.nudo.js`）。审阅后复制进正式侧车。
+ */
+
+/**
+ * DraftEvidence `body` = 仅来自函数体对形参的成员读取（草稿建议，非义务）。
+ * check / effectiveInterface **永不**消费该档。
+ */
+type DraftEvidence = "callsite" | "directive" | "symbolic" | "body" | "none";
+type InterfaceDraftEntry = {
+    fn: string;
+    /** 全部形参（含无证据槽，便于人读） */
+    params: Array<{
+        name: string;
+        constraint?: NudoConstraint;
+        display: string;
+        /** false = 无证据，DSL 对象里省略该槽 */
+        projected: boolean;
+        /** 函数体读到的字段名（草稿建议；与 projected 无关） */
+        bodyAccesses?: string[];
+    }>;
+    returns?: {
+        constraint?: NudoConstraint;
+        display: string;
+        projected: boolean;
+    };
+    paramEvidence: DraftEvidence;
+    returnEvidence: DraftEvidence;
+    skipped?: "handwritten" | "not-an-export";
+    /** 草稿 DSL：`fn({ … }, …)`；handwritten / 非导出时 undefined */
+    dsl?: string;
+};
+type InterfaceDraftOpts = {
+    fnNames?: string[];
+    records?: CallRecord[];
+    loadModule?: LoadModule;
+    /**
+     * Accepted for API compatibility; **ignored**. The handwritten-contract probe
+     * always uses `effectiveInterface(..., { autoBind: true })` so draft skips
+     * disk sidecars even when ambient autoBind is off (product: draft asks
+     * "does a contract already exist?", not "is ambient binding on?").
+     */
+    autoBind?: boolean;
+    /** 默认 true：收集 body 成员读取作草稿建议（永不进 check） */
+    bodyAccesses?: boolean;
+    /** 打开 buffer 源（E5：与 hover/interface 同口径） */
+    source?: string;
+};
+type InterfaceDraftResult = {
+    file: string;
+    entries: InterfaceDraftEntry[];
+    draftSource: string;
+    sidecarPath: string;
+};
+/**
+ * Draft-only：收集每个顶层函数形参上的成员读取键（`user.name` → name）。
+ * **不是** C0 禁止的 body→义务通道——只进草稿注释/建议，check 不读此表。
+ */
+declare function collectParamBodyAccesses(source: string): Map<string, Map<string, Set<string>>>;
+/**
+ * 为单文件顶层导出生成 interface 草稿（不写盘）。
+ * handwritten 跳过；已有 @generated 仍出草稿（便于对照）。
+ */
+declare function draftInterface(filePath: string, opts?: InterfaceDraftOpts): Promise<InterfaceDraftResult>;
+/** 草稿模块文本（人读 + 可复制到 *.nudo.js / *.nudo.ts） */
+declare function formatDraftModule(filePath: string, entries: InterfaceDraftEntry[], sidecarPath?: string): string;
+/** `lib.js|ts` → `lib.nudo.draft.js|ts`（不进 ambient sidecar 表） */
+declare function sidecarDraftPath(filePath: string): string;
+type WriteDraftResult = {
+    draftPath: string;
+    written: boolean;
+    changed: boolean;
+    draftable: boolean;
+    draftSource: string;
+};
+/** Parse-layer draftable: at least one entry has generated DSL and was not skipped */
+declare function isDraftableEntry(entries: ReadonlyArray<Pick<InterfaceDraftEntry, "dsl" | "skipped">>): boolean;
+/**
+ * 写入 `*.nudo.draft.js`（覆盖草稿文件本身；不碰正式 `*.nudo.js`）。
+ * 基础路径防护：拒绝 node_modules；拒绝 draft 路径与正式侧车重合；
+ * 拒绝 draft 路径落在源文件目录之外的穿越。
+ *
+ * `opts.entries` / `opts.draftable`：解析层判定（优先）。缺省时用 Unicode
+ * 感知 export 正则兜底——`\w` 会静默丢掉 `计算` 这类标识符。
+ */
+declare function writeInterfaceDraft(filePath: string, draftSource: string, opts?: {
+    dryRun?: boolean;
+    projectDir?: string;
+    entries?: ReadonlyArray<Pick<InterfaceDraftEntry, "dsl" | "skipped">>;
+    draftable?: boolean;
+}): WriteDraftResult;
+declare function formatDraftSummary(sourceRel: string, draftRel: string, result: InterfaceDraftResult, write?: WriteDraftResult): string[];
+
 /**
  * Root 驱动的契约下行（design-refine-derivation §4.2 / §11 Phase 2）。
  *
@@ -970,4 +1388,4 @@ declare function emitDerivedFromRoot(rootFile: string, opts: {
     refreshExistingOnly?: boolean;
 }): EmitDerivedResult;
 
-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 };
+export { ANALYSIS_ABI, type AbsGraphOptions, type AbsMockSeeds, type AbsModuleCacheEntry, type AbsModuleGraphResult, type AbsModuleLoadIssue, AnalysisConfig, type AnalysisResult, type AnalysisSession, type BPathBuiltinUnknown, type BPathDiagnostics, type BPathRunResult, type BPathUnreachable, type BindingInfo, type BuildSemanticTokensOpts, CallRecord, type CaseHint, type CaseInfo, type CaseResult, type CompletionItem, type ConstraintSourceExpr, type DepContent, type DerivedExport, type DerivedParam, type Diagnostic, type DiagnosticSeverity, type DiagnosticTag, DiagnosticsLevel, DiskCache, type DiskCacheOptions, type DraftEvidence, type EmitDerivedResult, type EmitInterfaceOpts, type EmitInterfaceResult, type EmitInterfaceSkipReason, type EmitResult, type EmitSkipReason, type EnvHarvestConflict, type FunctionAnalysis, HARVEST_NODE_DEFAULT_MAX_FILES, HARVEST_NODE_DEFAULT_MAX_MS, type HarvestNodeStats, type HoverInfo, type InferJson, type InferJsonCase, type InferJsonFunction, type InterfaceDraftEntry, type InterfaceDraftOpts, type InterfaceDraftResult, type InterfaceSurfaceEntry, type InterfaceSurfaceOpts, type LoadModule, type MergeHarvestOptions, 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, type WriteDraftResult, absToTSType, absToZodSchema, ambientSourcesOfSidecar, analysisFileCacheKey, analyzeExportsFromSource, analyzeFile, analyzeFileAsync, autoHarvestModules, barePackageName, bareSpecToAbsModules, buildCaseDirective, buildModuleGraph, buildSemanticTokens, checkCacheKey, clearAbsModuleCache, clearAnalysisFileCache, clearAnalysisSessionCaches, clearBPathCache, clearEnvPathDeps, clearFnAnalysisCache, clearHarvestCache, clearNodeHarvestCache, collectAbsBindingsFromGraph, collectBPathDiagnostics, collectBPathReplacements, collectBarePackages, collectCallRecords, collectDependencySpecs, collectDtsFromEntry, collectEnvGlobals, collectEnvModules, collectLoadDepContents, collectParamBodyAccesses, collectStaticImports, computeDirtySet, defaultAbsLoadModule, defaultLoadModule, deriveFromRoot, diagnosticsLevelForFile, draftInterface, emitDerivedFromRoot, emitInterface, encodeSemanticTokens, envPathDependents, evalAbsModuleGraph, evalProgramAbsWithModules, evictAbsModuleCacheFiles, evictAnalysisCachesForFiles, evictAnalysisFileCacheForFiles, evictBPathCacheForFiles, evictFnAnalysisCacheForFiles, extractFnConstraintSources, extractNudoImportSpecs, filterDiagnosticsByLevel, formatDerivedSection, formatDraftModule, formatDraftSummary, formatEmitSummary, formatHarvestSummary, formatInterfaceSurfaceLine, generateDts, generateFunctionDtsLines, generateGuardFunction, generateGuardFunctionFromAbs, getAbsAtPosition, getAbsAtPositionAsync, getAnalysisFileCacheSize, getAnalysisSession, getCasesForFile, getCompletionsAtPosition, getEnvHarvestConflictCollector, getHoverAtPosition, getNodeHarvestCacheSize, getTypeAtPosition, getTypeAtPositionAsync, harvestNodeTypes, harvestPackage, harvestPackageCached, harvestToAbsModules, harvestedValueToAbs, ifaceCacheKey, insertGeneratedCaseDirectives, interfaceSurface, interfaceTierModifierBit, isBPathCapable, isDraftableEntry, isEnvTemplatePath, isHarvestNodeDisabled, isNudoTargetPath, isProjectConfigPath, isSidecarPath, isWatchRelevantPath, lookupHarvested, mergeHarvestUnderEnv, mockDirectivesToAbsSeeds, noteEnvPathDeps, packageHarvestToAbsModules, relativizePath, resetAllAnalysisCaches, resolvePackageRoot, serializeCaseArg, serializeInferJson, setAnalysisSession, setEnvHarvestConflictCollector, sha256Hex, shouldAnalyzeFile, sidecarDraftPath, hasNudoDirectives as sourceHasNudoDirectives, stripGeneratedCaseDirectives, summarizeNodeEnv, topoSortDirty, tryBPathCall, tryBPathCallFull, tryRunBPath, unifiedDiff, writeInterfaceDraft };