@nudojs/core 1.15.2 → 1.17.0

package/dist/{projection-budget-07VnMktV.d.ts → projection-budget-BkFV9pcs.d.ts}

@@ -1,11 +1,12 @@
 import { File } from '@babel/types';
-import { A as Abs, T as Term, P as PrimName, a as Pred, L as LiteralValue, b as Phi, C as Confidence } from './run-DfloWX6i.js';
+import { A as Abs, T as Term, P as PrimName, a as Pred, L as LiteralValue, C as Confidence, b as Phi } from './run-tV2J7PNI.js';
 
 declare function resetParseSourceCache(): void;
 declare function getParseSourceCacheSize(): number;
 declare function parseSource(source: string, opts?: {
     errorRecovery?: boolean;
     keepTs?: boolean;
+    filename?: string;
 }): File;
 
 /**
@@ -30,7 +31,12 @@ declare function drainPromiseMicros(): void;
 declare function evalPromiseCtor(args: Abs[]): Abs;
 /** then/catch/finally：可映射回调 → 新 inner；做不到诚实 promise<unknown> */
 declare function evalPromiseMethod(name: string, recv: Abs, args: Abs[]): Abs | undefined;
-declare function evalPromiseStatic(name: string, args: Abs[]): Abs | undefined;
+/**
+ * Bug 311：Promise 静态派发。thisVal = 静态方法值的 this 绑定（成员读出
+ * 的静态方法被单独调用时的接收者）；缺席 = 直接命名空间调用（this ≡
+ * Promise 构造器，合法）。非构造器接收者按原生抛 TypeError。
+ */
+declare function evalPromiseStatic(name: string, args: Abs[], thisVal?: Abs): Abs | undefined;
 
 /**
  * 项（Term）防爆炸：深度/宽度阈值 → leak 为新鲜 var + 等式约束。
@@ -87,6 +93,11 @@ declare function isNodeModulesPath(p: string): boolean;
  * 源文件的旁路侧车路径：.js/.mjs → 同名 .nudo.js；.ts/.mts → 同名 .nudo.ts。
  * 其他扩展名（.cjs/.jsx/无扩展名…）不做替换，直接追加 .nudo.js——侧车约定
  * 只覆盖四类入口；host loadModule 对不存在的路径返回 miss，自然无侧车来源。
+ *
+ * **幂等**（Bug 362）：输入本身已是侧车（`lib.nudo.js` / `lib.nudo.ts`）时
+ * **不再追加第二段** `.nudo`。旧口径产出 `lib.nudo.nudo.js`——该路径不是任何
+ * 源码的侧车 ⇒ 契约永久静默失效；草稿面还会落到 `lib.nudo.nudo.draft.js`
+ * 并指示用户「copy it into lib.nudo.nudo.js」（一个不存在的侧车名）。
  */
 declare function sidecarPathOf(file: string): string;
 
@@ -163,14 +174,26 @@ declare function string(): ConstraintBuilder;
 declare function boolean(): ConstraintBuilder;
 /** any() —— 无约束；formatConstraint / draft import 与显示同源 */
 declare function any(): ConstraintBuilder;
-/** array(item) —— 数组，元素满足 item；item 亦可为具体字面量（指令文法） */
-declare function array(item: NudoConstraint | ConstraintBuilder | number | string | boolean | null | undefined): ConstraintBuilder;
+/**
+ * array(item) —— 数组，元素满足 item；item 亦可为具体字面量（指令文法）。
+ *
+ * 元素约束**必填**（Bug 354）：少传元素时旧实现把 `undefined` 交给
+ * asNestedConstraint ⇒ 静默变成 `lit(undefined)` ⇒ 契约变成「元素必须是
+ * undefined」⇒ 任何合法数组实参都被判违反（假红），且零诊断说明缺参。
+ * 「元素可为 undefined」有显式写法：`array(lit(undefined))`。
+ */
+declare function array(item: NudoConstraint | ConstraintBuilder | number | string | boolean | null | undefined, ...rest: unknown[]): ConstraintBuilder;
 /**
  * object 形状约束（契约规范形状，无需 interface）：
  *
  *   shape({ id: number().gt(0), name: string() })
  *
  * 字段值亦可为具体字面量（指令文法）。
+ *
+ * 实参守卫（Bug 352 / 353）：缺参 ⇒ 点名构造器 + 说明缺参；非对象 ⇒ 点名
+ * 构造器 + 实际类型。旧实现把实参直接交给 `Object.entries`：`shape(42)` ⇒
+ * `[]` ⇒ 整条参数契约退化成空 shape（域放宽到任意对象 = 假绿）；`shape()`
+ * ⇒ 宿主 TypeError「Cannot convert undefined or null to object」原文进诊断。
  */
 declare function shape(fields: Record<string, NudoConstraint | ConstraintBuilder | number | string | boolean | null | undefined>): ConstraintBuilder;
 /** litC(v)：字面量契约——prim 按 v 类型、eq(self, v) pred 编码（不开新字段） */
@@ -216,6 +239,11 @@ declare function constraintAdmitsNullish(c: NudoConstraint, seen?: Set<object>):
  * fn(params, returns?, { throws? })：一等函数约束。
  * Phase 1 只展示不执法：参数位 instantiate 恒真（pTrue），
  * 逐参约束经 fnConstraintToEntryReqs 消费。
+ *
+ * 第三实参（opts）做**形态校验**（Bug 357）：
+ * - opts 必须是对象 —— 否则整条 throws 申报被静默丢弃（零诊断假红）；
+ * - opts.throws 归一后必须能抽出至少一个错误名（throwConstraintToKinds 非
+ *   undefined）—— 否则 throws 义务无声消失，用户已申报却仍报 may-throw。
  */
 declare function fn(params: Record<string, NudoConstraint | ConstraintBuilder | number | string | boolean | null | undefined>, returns?: NudoConstraint | ConstraintBuilder | number | string | boolean | null | undefined, opts?: {
     throws?: NudoConstraint | ConstraintBuilder | number | string | boolean | null | undefined;
@@ -226,11 +254,30 @@ declare function fn(params: Record<string, NudoConstraint | ConstraintBuilder |
  * prim 不一致或任一含 fields/element/members/fn → throw。
  */
 declare function andC(...cs: (NudoConstraint | ConstraintBuilder)[]): ConstraintBuilder;
-/** partial(c)：shape 全字段变可选；非 shape throw（lazy 包装先解一层） */
+/**
+ * partial(c)：shape 全字段变可选；非 shape throw（lazy 包装先解一层）。
+ *
+ * 写侧用**无原型字段表**（Bug 1027）：partial 是「读旧表 ⇒ 写新表」，
+ * 若新表是普通对象，字段名 `__proto__` 会被原型 setter 吞掉 ⇒ 经 partial
+ * 转一道仍二次吞键 ⇒ 契约被削弱成空 shape。
+ */
 declare function partial(c: NudoConstraint | ConstraintBuilder): ConstraintBuilder;
-/** pick(c, keys)：shape 子形状（不存在的 key 忽略）；非 shape throw（lazy 包装先解一层） */
+/**
+ * pick(c, keys)：shape 子形状（不存在的 key 忽略）；非 shape throw（lazy 包装先解一层）。
+ *
+ * 字段读取用**自有属性**判定（Bug 347）：`d.fields[k]` 沿原型链读，
+ * "constructor" / "toString" 会命中 Object.prototype 成员并被当成字段塞进
+ * 新字段表 ⇒ 后续读 `f.constraint` 拿到 undefined ⇒ contract / export 面裸崩、
+ * check 面静默作废整条契约。
+ */
 declare function pick(c: NudoConstraint | ConstraintBuilder, keys: string[]): ConstraintBuilder;
-/** omit(c, keys)：shape 去字段；非 shape throw（lazy 包装先解一层） */
+/**
+ * omit(c, keys)：shape 去字段；非 shape throw（lazy 包装先解一层）。
+ *
+ * 写侧用**无原型字段表**（Bug 1027）：omit 是「读旧表 ⇒ 写新表」，
+ * 若新表是普通对象，字段名 `__proto__` 会被原型 setter 吞掉 ⇒ 经 omit
+ * 转一道仍二次吞键 ⇒ 契约被削弱成空 shape。
+ */
 declare function omit(c: NudoConstraint | ConstraintBuilder, keys: string[]): ConstraintBuilder;
 /**
  * 约束构建器表面名表（单一真源）：case 实参文法、mock 类型表达式识别与
@@ -311,6 +358,9 @@ type RefineDiag = {
     code: string;
     message: string;
     file?: string;
+    /** Bug 374：诊断位置（1-based 行 / 0-based 列；与 Babel loc 同坐标面） */
+    line?: number;
+    column?: number;
 };
 /** 设置诊断观察者（null 清除）；缓冲照常累积，takeRefineDiags 取走 */
 declare function setRefineDiagCollector(fn: ((d: RefineDiag) => void) | null): void;
@@ -354,6 +404,9 @@ declare function refineToIndexedFull(source: string, fnName: string, paramNames:
 /**
  * 解析 `@nudo:contract return positive` → 返回契约。
  * 返回 undefined = 无声明（不猜后置）。
+ *
+ * Bug 360：多条 return 段**合成单条合取**（不再「首个命中即 return」）。
+ * Bug 351：fn 形态模板取其 `fn.returns`（与侧车口径一致，返回义务真被执法）。
  */
 declare function extractRefineReturnFromSource(source: string, fnName: string, opts?: RefineResolveOpts): {
     name: string;
@@ -369,6 +422,11 @@ declare function extractRefineReturnFromSource(source: string, fnName: string, o
  *
  * 与 refine 同扫函数前注释块（D6=G2 同一 scope 绑定）。
  * 返回 `*` = 申报任意；数组 = 按名申报；undefined = 无申报（L2 照常执法）。
+ *
+ * Bug 1032：粘连（`@nudo:throwsTypeError`）与**空载荷**（`@nudo:throws`）此前
+ * **整行不匹配**严格正则且**无 else 分支** ⇒ 抛错申报**零诊断**地蒸发 ⇒ L2
+ * 门禁按「未申报」执法（假红），而用户以为申报生效了 ⇒ 这里显式发
+ * `nudo:directive-syntax`（既有码，不另造新码）。
  */
 declare function extractDeclaredThrows(source: string, fnName: string): string[] | "*" | undefined;
 /**
@@ -414,10 +472,16 @@ declare function localNamedExports(source: string): Set<string>;
  */
 declare function exportedNameOfLocal(source: string, localName: string): string | undefined;
 /**
- * 侧车源码的生成段导出名：export 之前（跳过紧邻的 import/const 链）的注释
- * 行含 `@generated` → 该名为 generated。组合式下行段（§5.3）形态为
- * `import` + `@generated 头` + prelude + export；callsite 段则是头紧贴
- * export。隔了其他代码行 / 无标记 / re-export 列表均不算。
+ * 侧车源码的生成段导出名：export 之前（跳过紧邻的 import 链与**被 export
+ * 引用**的 const 链）的注释行是 nudo 自己的 `@generated` 标记 → 该名为
+ * generated。组合式下行段（§5.3）形态为 `import` + `@generated 头` + prelude +
+ * export；callsite 段则是头紧贴 export。隔了其他代码行 / 无标记 / re-export
+ * 列表均不算。
+ *
+ * 标记判定是**精确**的（Bug 440）：注释首个记号必须是 `@generated` 且点名 nudo
+ * ——散文里**提到** `@generated` 不算（那是用户引用 nudo 的提示语）。
+ * 段边界也**收紧**（Bug 432）：紧邻的 const 只有**被该 export 引用**时才属
+ * 段内，用户自己的 const 夹在中间 ⇒ 上一段的标记不落进本段。
  *
  * DESIGN-003 别名段：导出名不是合法绑定名（保留字 / 非 ident）时发射为
  * `const _nudo_1 = …; export { _nudo_1 as class };` —— 身份恒为**导出名**
@@ -459,6 +523,9 @@ type InterfaceDiag = {
     code: string;
     message: string;
     file?: string;
+    /** Bug 374：诊断位置（1-based 行 / 0-based 列；转发 refine 诊断时透传） */
+    line?: number;
+    column?: number;
 };
 /** 设置诊断观察者（null 清除）；缓冲照常累积，takeInterfaceDiags 取走 */
 declare function setInterfaceDiagCollector(fn: ((d: InterfaceDiag) => void) | null): void;
@@ -513,6 +580,17 @@ type EffectiveInterface = {
         params: string[];
         returns?: boolean;
     };
+    /**
+     * 合取**不可判定**标记（Bug 1141）：结构型组合（union / fn / 结构型∧标量…）
+     * 算不出交集 —— 不是「不可满足」（不标 conflict、既有义务继续执法），但
+     * **另一侧**的义务确实没被执法 ⇒ 显式报出（不得静默宽松）。
+     *
+     * 独立于 `conflict`：conflict 的语义是「矛盾 ⇒ 跳过该位执法」，两者不可混。
+     */
+    undecidable?: {
+        params: string[];
+        returns?: boolean;
+    };
 };
 /** 与 resetNudoModuleExecCache 同口径：分析会话/测试间清空失败去重表 */
 declare function resetSidecarLoadFailureCache(): void;
@@ -582,10 +660,35 @@ type LoadDepsFingerprint = {
      */
     readError: boolean;
 };
+/**
+ * 指纹的 ambient 侧车探测口径（Bug 1124）。
+ *
+ * ambient 侧车探测是**推测性**的：它只为算指纹，不代表分析真的要用这份侧车
+ * （autoBind 关 / 树外 / node_modules ⇒ 根本不会被绑定）。⇒ 探测失败
+ * **不得**升级成分析错误（门禁假红），但仍须让本轮指纹**不可信**
+ * （readError ⇒ 键带 readerr: 前缀、调用方 fail-open 禁 memo ⇒ 错误轮与
+ * miss 轮不共用键、互不为陈旧命中）。
+ */
+type LoadDepsFingerprintOpts = {
+    /**
+     * ambient 侧车探测专用 loader（**推测性**读）。
+     * 调用方（check.ts）传**未经降级闸**的 loader：读失败只标 readError，
+     * 不记入分析错误。缺省 = 用 `loadModule`（旧行为）。
+     */
+    ambientLoadModule?: (spec: string, fromFile: string) => string | undefined;
+    /**
+     * ambient 绑定资格（autoBind / projectDir / node_modules）。
+     * 返回 false ⇒ 该侧车不会被 ambient 绑定 ⇒ 探测无意义 ⇒ 跳过
+     * （不读盘、不进指纹）。缺省 = 允许（旧行为：过近似，只过度失效）。
+     */
+    ambientAllowed?: (sidecarPath: string) => boolean;
+};
 /**
  * All string module specs that analysis may resolve through loadModule.
- * Regex over-approximates (may hit comments) — extra dep fingerprint is safe
- * (more misses, never a stale hit).
+ *
+ * 正则**过近似**（可能命中注释里的假 import）**且**在两类形态上**欠近似**
+ * （仅副作用 import / 模板字符串 require）⇒ 正则集**并**AST 集（Bug 452）：
+ * 并集只可能比现状**多**（more misses），不会比现状**少**（never a stale hit）。
  */
 declare function extractAllLoadSpecs(source: string): string[];
 /**
@@ -603,36 +706,16 @@ declare function sidecarSpecsOf(source: string): string[];
  * ambient 绑定其侧车，依赖侧车内容影响调用方报告——不进指纹则编辑后 memo
  * 陈旧命中（错诊断）。侧车 loadModule miss（无侧车文件）→ 不加任何条目。
  *
- * 注意：本扩展对 autoBind=false 与 /node_modules/ 均**不** gate（刻意过近似，
+ * 注意：本扩展对 autoBind=false 与 /node_modules/ 默认**不** gate（刻意过近似，
  * 只过度失效、绝不陈旧命中——安全方向）；ambient 生效边界由
  * interface.ts 的 sidecarClosureFingerprint 负责，两者职责不同。
+ *
+ * Bug 1124：调用方（check.ts）可传 `opts.ambientAllowed`（ambient 绑定资格）
+ * 与 `opts.ambientLoadModule`（推测性探测 loader）——autoBind 关闭时该侧车
+ * 根本不会被绑定 ⇒ 不必探测；探测失败也**不得**升级成分析错误（门禁假红），
+ * 但仍须让本轮指纹不可信（readError ⇒ 禁 memo，错误轮与 miss 轮不共用键）。
  */
-declare function loadModuleDepsFingerprint(source: string, loadModule: (spec: string, fromFile: string) => string | undefined, fromFile: string): LoadDepsFingerprint;
-
-/**
- * 约束诊断：检查调用点实参是否满足函数的前置约束 / 参数 shape。
- * 输出可行动的建议，而不是 TS 式「类型不匹配」。
- */
-
-type Diagnostic = {
-    severity: "error" | "warning" | "info";
-    code: string;
-    message: string;
-    suggestion?: string;
-    fn?: string;
-    argIndex?: number;
-};
-/**
- * 检查实参是否满足「期望约束」。
- * expect: 相对参数 term 的 pred，例如 term > 0
- * arg: 实际实参 Abs
- */
-declare function checkArg(arg: Abs, expect: Pred | undefined, phi?: Phi): Diagnostic | undefined;
-/**
- * 对一次函数调用做诊断：实参 shape + 约束。
- */
-declare function checkCall(source: string, fnName: string, args: Abs[], phi?: Phi): Diagnostic[];
-declare function formatDiagnostics(diags: Diagnostic[]): string;
+declare function loadModuleDepsFingerprint(source: string, loadModule: (spec: string, fromFile: string) => string | undefined, fromFile: string, opts?: LoadDepsFingerprintOpts): LoadDepsFingerprint;
 
 /**
  * check 报告面：数据模型 + 渲染/序列化。
@@ -652,9 +735,17 @@ type NudoSig = {
     paramTypes?: string[];
     /** 符号 Abs 本体 */
     abs: Abs;
-    /** formatAbs 单行 */
+    /**
+     * 签名展示（**人类面口径**：shape 渲染）——与 `formatCheckReport` 的签名行
+     * **逐字同源**（Bug 413：机器面此前用 `formatAbs`，把 term / pred 段渲进
+     * 对外载荷，其中混着引擎内部计数器 id `len#N` ⇒ 载荷随参数列表位置漂移）。
+     */
     display: string;
-    /** formatAbsMultiline */
+    /**
+     * 签名明细（多行；首行 = 函数名）——与人类面 `--verbose` 同源。
+     * term / pred 里的引擎内部计数器 id 换成**稳定名**（`len#2` → `len`）
+     * （Bug 413）。
+     */
     detail: string;
     conf: Confidence;
     /** throws 域展示（如 TypeError）；省略 = 无 may-throw */
@@ -744,6 +835,17 @@ type CheckReport = {
 /**
  * `nudo check --json` 稳定契约（供 CI / Agent）。
  * 字段只增不改语义；Abs 以 formatAbs 字符串给出，不序列化内部 shape 图。
+ *
+ * ⚠ **Bug 413 的载荷语义变更**（v1 契约内的字段**取值口径**收紧）：
+ * - `signatures[].display` 改为**人类面口径**（`formatShape`）⇒ 与 `nudo check`
+ *   的 signatures 行**逐字同源**（此前是 `formatAbs` 单行，两面不一致）；
+ * - `signatures[].detail` / `signatures[].abs` 里的**引擎内部计数器 id**
+ *   （`len#N` 一族）换成**稳定名**（`len#2` → `len`）⇒ 形状 / 谓词证据 /
+ *   `#conf` / pathNote 全部保留，只有那个会随进程漂移的编号被抹平。
+ *
+ * 动机：内部计数器 id 的编号是**进程历史**的函数 ⇒ 同一个文件的载荷曾随
+ * 它在命令行参数列表中的位置漂移（`len#0` / `len#2` / `len#4`）⇒ 机器消费
+ * 方（CI diff / 快照 / 按文件比对）拿到的不是文件内容的函数。
  */
 type CheckJson = {
     version: 1;
@@ -874,6 +976,40 @@ declare function formatGitlabCodeQuality(r: CheckReport, opts?: {
     workspaceRoot?: string;
 }): GitlabCodeQualityIssue[];
 
+/**
+ * 约束诊断：检查调用点实参是否满足函数的前置约束 / 参数 shape。
+ * 输出可行动的建议，而不是 TS 式「类型不匹配」。
+ *
+ * Bug 364：本模块此前**没有生产者**——`checkArg` / `checkCall` 是死码 ⇒
+ * 文档承诺的调用点验证面在产品里整体静默。`checkCallSite` 是接进产品
+ * 路径（`scan-literal-calls.ts` 的调用点扫描）的入口。
+ */
+
+type Diagnostic = {
+    severity: "error" | "warning" | "info";
+    code: string;
+    message: string;
+    suggestion?: string;
+    fn?: string;
+    argIndex?: number;
+};
+/**
+ * 检查实参是否满足「期望约束」。
+ * expect: 相对参数 term 的 pred，例如 term > 0
+ * arg: 实际实参 Abs
+ *
+ * Bug 364：`expect` 的主题项是**参数位**的 term（通用化面里的 `A1`），
+ * 而 `arg.pred` 相对**实参** term（`x`）⇒ 两者永不同一 ⇒ 任何非字面量
+ * 实参都被判 `nudo:constraint-unproven`（假红）。⇒ 判定前把主题项
+ * 对齐到实参自身的 term（`alignToArg`）。
+ */
+declare function checkArg(arg: Abs, expect: Pred | undefined, phi?: Phi): Diagnostic | undefined;
+/**
+ * 对一次函数调用做诊断：实参 shape + 约束。
+ */
+declare function checkCall(source: string, fnName: string, args: Abs[], phi?: Phi): Diagnostic[];
+declare function formatDiagnostics(diags: Diagnostic[]): string;
+
 /**
  * 投影/格式化层共享的 Abs 遍历预算（DESIGN-001）。
  *

package/dist/{run-DfloWX6i.d.ts → run-tV2J7PNI.d.ts}

@@ -185,6 +185,17 @@ type Shape = {
     name?: string;
     paramTypes?: Abs[];
     returnType?: Abs;
+    /**
+     * Bug 399：逐位「可省略」标记（与 `params` 同下标，true = 该位有默认值 /
+     * 可省）。缺省 = 无标记（必选元数按名字后缀 `...` / `?` 判）。
+     *
+     * 为什么需要：默认形参（`f(a, b = 1)`）在形参表面上只是光秃秃的名字
+     * （`b`）⇒ 被计成必选元数 ⇒ `f = (x = 1) => x` 触发
+     * `nudo:assign-mismatch` 假红（JS 语义下 `(x = 1) => x` 的 `length` 是 0）。
+     *
+     * 与 `ctor` 同纪律：形态信息，不进指纹 / 展示串；`leq` 读它算必选元数。
+     */
+    optionalParams?: boolean[];
     /**
      * Dual-facet globals (Number/Array/…): callable AND carries static members.
      * `$get` reads these before falling back to Function.prototype names.
@@ -378,7 +389,7 @@ declare function filterDeclaredThrows(effects: MayThrowEffect[], declared: reado
  * 3. 无 impl 时 isRelFn 可走 E 路径（旧版恒 unknown）
  */
 
-/** 清空 pure memo（宿主入口 / 会话缓存失效） */
+/** 清空 pure memo（宿主入口 / 会话缓存失效；清**全部**实例——两条调用路径） */
 declare function clearPureMemo(): void;
 /**
  * apply 返回的 throws 面 → 调用方控制流通道（H1 单点路由）。
@@ -410,7 +421,7 @@ type EvalCallRecord = {
      *  局部量投影按帧过滤重入记录（与 $nodoPos 同口径）。 */
     depth?: number;
 };
-/** 清空 pureCallMemo（宿主入口 / 会话缓存失效） */
+/** 清空 pure memo（宿主入口 / 会话缓存失效；清**全部**实例——两条调用路径） */
 declare function clearPureCallMemo(): void;
 /** B 赋值记录（与 ast-records.ts AbsAssignRecord 同形；structuralAssignIssues 消费） */
 type EvalAbsAssignRecord = {
@@ -443,7 +454,7 @@ declare function getPosCollector(): ((r: EvalPosRecord) => void) | null;
  * 记入活跃 collector 并**原样返回**（语义恒等）；无收集器时
  * 直通（热路径零开销——仅重放开插桩）。
  *
- * 仅记最外层求值帧（evalCallDepth === 0）：递归函数的内层帧
+ * 仅记最外层求值帧（evalBudget.depth === 0）：递归函数的内层帧
  * （$callNamed/$new 预算帧）会以重入态重执行同一源码位置——
  * 自递归类型（lazy 自引用契约）下内层帧携带 cycle 截断的
  * opaque unknown，first-wins 记录会以外层正确值被污染为序；
@@ -463,10 +474,9 @@ declare function getEvalCallCollector(): ((r: EvalCallRecord) => void) | null;
  * loc: [line, column]（1-based line，0-based column，与 Babel 一致）
  * argLocs: 与 args 对齐的实参字面量源位置（provenance；无 loc 用 null）
  */
+/** B 命名调用深度上限——与 A 路径同值（@nudo:budget 可逐函数抬高） */
 declare const MAX_EVAL_CALL_DEPTH = 64;
-/** 总调用上限：与 call-budget.MAX_TOTAL_CALLS 同阀（递归×循环×分支展开的
- *  规模阀）。200k 在病态展开（lodash _baseFlatten）下 ~30s，20k 收口到
- *  ~3s——截断 → opaque（更保守，zero-FP 安全）。 */
+/** B 命名调用总调用上限——与 A 路径同值（递归×循环×分支展开的规模阀） */
 declare const MAX_EVAL_TOTAL_CALLS = 20000;
 /** 宿主入口前强制清零（测试 / 显式 API）。执行入口请用 enterEvalCallBudgetSession。 */
 declare function resetEvalCallBudget(): void;
@@ -493,13 +503,13 @@ declare function getEvalCallBudgetState(): {
 declare function $callNamed(name: string, fn: unknown, args: Abs[], loc?: [number, number], argLocs?: Array<[number, number] | null | undefined>): Abs;
 
 /**
- * 共享纯类型结点（AstEnv / HofCollectCtx / HofSite / RelSource）。
+ * 共享纯类型结点（AstEnv / HofSite / RelSource）。
  *
- * 这些类型曾形成 ast-env ↔ hof ↔ abs-fn 的类型环（ast-env 引 HofCollectCtx，
- * hof/abs-fn 引 AstEnv）。抽到本叶模块（只依赖 abs/term/babel，不回指
+ * 这些类型曾形成 ast-env ↔ hof ↔ abs-fn 的类型环（ast-env 引 HOF collector
+ * 类型，hof/abs-fn 引 AstEnv）。抽到本叶模块（只依赖 abs/term/babel，不回指
  * ast-env/hof/abs-fn）后，三个消费方都从这里取类型，环即断。
  *
- * 稳定导入路径不变：ast-env.ts 重导出 AstEnv，hof.ts 重导出 HOF 三类型。
+ * 稳定导入路径不变：ast-env.ts 重导出 AstEnv，hof.ts 重导出 HOF 两类型。
  */
 
 /**
@@ -522,30 +532,6 @@ type HofSite = {
         column: number;
     };
 };
-/**
- * run 局部 collector（与 Phi 并列，不进 Φ 合并）。
- * symbolic 一次跑：安装并沉淀到 PolyFn；instantiate 重跑：装 throwaway
- * 副本——形状提升仍生效，结果不写回共享状态（见 generalize.ts run()）。
- */
-type HofCollectCtx = {
-    /** 本次归纳的形参名集合（身份判定用） */
-    paramNames: ReadonlySet<string>;
-    /** 本次 typeParams 的 α id 集合（term 复用白名单） */
-    alphaIds: Set<string>;
-    /** fresh α 计数 */
-    freshSeq: {
-        n: number;
-    };
-    sites: HofSite[];
-    fnRels: Map<string, {
-        abs: Abs;
-        source: RelSource;
-    }>;
-    entryShapes: Map<string, {
-        abs: Abs;
-        source: RelSource;
-    }>;
-};
 type AstEnv = {
     vars: Map<string, Abs>;
     /** 用户函数：name → { params, body } */
@@ -554,13 +540,24 @@ type AstEnv = {
         body: Node;
         async?: boolean;
         kind?: string;
+        /**
+         * Bug 399：逐位「可省略」标记（与 `params` 同下标，`true` = 该位有
+         * 默认值 / 带 `?` / 是 rest）⇒ 必选元数不再靠名字后缀猜。
+         */
+        optionalParams?: boolean[];
+        /**
+         * 源码面严格性（strict mode code → true；sloppy → false）：ESM 源 ∨
+         * `"use strict"` 序言（`code-text.ts#sourceIsStrict`），strict 代码区内
+         * 词法继承，class 方法体恒 true。env 条目被包装成 Abs fn
+         * （`absFunction`）时透传为 `AbsFnImpl.strict`，供 body 编译单元发射
+         * `"use strict";`。按**源面严格性**判定，不按函数猜。
+         */
+        strict?: boolean;
     }>;
     /** class 表（旁路，withVar 必须保留） */
     classes?: Map<string, unknown>;
     /** 当前正在求值的方法所属类名（super.x() 从它的父类派发） */
     currentOwner?: string;
-    /** P2：generalize symbolic 跑的 HOF collector（run 局部，不进 Φ） */
-    hofCollect?: HofCollectCtx;
 };
 
 /**
@@ -617,12 +614,34 @@ type AbsFnImpl = {
     /** 声明时捕获的环境（闭包） */
     env?: AstEnv;
     kind?: string;
+    /**
+     * Bug 325：**函数种类**戳（async × generator 四象限）——原生
+     * `Object.prototype.toString.call(f)` 据此给标签（Function /
+     * AsyncFunction / GeneratorFunction / AsyncGeneratorFunction）。
+     *
+     * 与 `kind` 分开：`kind` 是**派发角色**维度（"protoMethod" = 内建原型
+     * 方法值，抑制 $invokeInner 的回退再入），而类方法**同时**可能是
+     * generator（`class A { *m(){} }`）⇒ 两种语义不能共用一个字段。
+     */
+    fnKind?: "function" | "async" | "generator" | "async-generator";
     /**
      * Bug 9：原生 fn.length（首个默认值/rest 形参前的形参数）——静态已知时
      * 记录（宿主函数 v.length / 全 Identifier 形参的 AST），$len / $get 的
      * f.length 折 exact；未记录（默认值/嵌套默认模式不可判）→ 保守 number≥0。
      */
     length?: number;
+    /**
+     * Bug 399：逐位「可省略」标记（与 `params` **同下标**，`true` = 该位有
+     * 默认值 / 带 `?` / 是 rest ⇒ 调用方可省）。
+     *
+     * 为什么不能靠 `length` 代替：`length` 是「首个默认值/rest **前**的形参数」
+     * ⇒ `f(a, b = 1, c)` 的 length = 1，但 `c` 仍**必选**（TS 语义：可选参数
+     * 之后的参数仍必选）⇒ 必选元数 ≠ length。
+     *
+     * 消费侧：`leq.ts` 的 `fnRequiredArity`（先读本标记，缺省回退
+     * `requiredFnArity` 的名字后缀判据）。
+     */
+    optionalParams?: boolean[];
     /**
      * 调用时直接派发（mock withArgs 等），优先于 body。
      * 返回裸 Abs = 不抛；返回 AbsApplyResult 时 throws 面经 $call 统一路由，
@@ -662,6 +681,16 @@ type AbsFnImpl = {
     };
     /** `@nudo:pure`：调用结果按实参记忆化（无副作用契约） */
     pureName?: string;
+    /**
+     * 源码面严格性（strict mode code → true；sloppy → false；未知不写）：
+     * ESM 源 **∨** 序言含 `"use strict"` 指令（`code-text.ts#sourceIsStrict`），
+     * 且 strict 代码区内词法继承（strict 函数体 / class 体内恒 strict）；
+     * class 方法体恒 true。body 编译单元（`exec/body-fn.ts`）据此发射
+     * `"use strict";`——块级函数声明、未声明赋值、形参/`arguments` 等
+     * sloppy↔strict 分叉必须与模块运行（B run 的 strict 前缀）同口径，
+     * 不能按函数猜。
+     */
+    strict?: boolean;
     /**
      * M4：transpile 静态判定的「无副作用面」facet（保守：任意赋值/自增/
      * 调用/delete/标签模板/非白名单 new 都算有副作用）。sort 等原生调用
@@ -707,7 +736,11 @@ declare function absFunction(params: string[], impl: Omit<AbsFnImpl, "params">,
  * `$new` / `$class(extends)` / 桥接包装按此 stamping。
  */
 declare function hostFnCtorFacet(v: Function): boolean | undefined;
-/** relationFn 稳定 fingerprint（同签名共享，见 §3.3 已知限制） */
+/**
+ * relationFn 稳定 fingerprint（同签名共享，见 §3.3 已知限制）。
+ * 结构序列化统一走 abs-key.ts（覆盖 holes / fn slots / optionalParams /
+ * ctor / obj 槽标志 / eff rejected / brand tv；无 α-rename）。
+ */
 declare function relationFingerprint(paramTypes: Abs[], returnType: Abs): string;
 /**
  * 无 body、纯关系的 fn Abs。params 仅记 arity。
@@ -758,6 +791,20 @@ type AbsModuleExports = {
      * 据此返回 default（= module.exports 值）；缺省按命名空间对象口径。
      */
     cjsMain?: boolean;
+    /**
+     * CJS 互操作模块：ESM **默认导入**（`import fs from "node:fs"`）解析到
+     * **模块对象本身**（= 命名空间 Abs），而不是「没有 default ⇒ unknown」。
+     *
+     * Bug 282：env 模块（node:fs / node:path…）是 CJS 内建互操作模块——Node
+     * 的默认导出就是模块对象本身（具名导出挂在它上面）。env 表此前只有具名
+     * 导出、没有 default 槽 ⇒ 默认导入折 unknown ⇒ 导出函数全量降级
+     * unknown + **假** `nudo:unknown-inference` + 门禁**假绿**（同一模块的
+     * 命名空间导入却判红 ⇒ 同一种导入语义两种门禁结论）。
+     *
+     * 口径：只对**显式标记**的互操作模块生效——用户模块缺 default 仍是
+     * unknown（模块表有该 mod 但没有 default ⇒ 就是没有 default）。
+     */
+    interopDefault?: boolean;
 };
 /**
  * 命名空间 Abs（`import * as ns` / `export * as ns` / CJS require 绑定）：
@@ -784,7 +831,8 @@ type RunTranspiledOptions = {
     mode?: "exec" | "analyze";
     /** @nudo:replace 注入值：varName → Abs */
     replacements?: Record<string, Abs>;
-    /** @nudo:replace 匹配表：传给 transpile */
+    /** @nudo:replace 匹配表：传给 transpile（stmtStart/stmtEnd = **字符区间**
+     *  `[start, end)`，非行号——Bug 166 起按 AST 节点身份定位） */
     replacementTargets?: Array<{
         target: string;
         varName: string;
@@ -793,7 +841,7 @@ type RunTranspiledOptions = {
     }>;
     /** @nudo:as 注入值：varName → Abs */
     asOverrides?: Record<string, Abs>;
-    /** @nudo:as 语句范围表 */
+    /** @nudo:as 语句范围表（stmtStart/stmtEnd = **字符区间**，非行号） */
     asOverrideTargets?: Array<{
         varName: string;
         stmtStart: number;
@@ -808,13 +856,31 @@ type RunTranspiledOptions = {
     recordPositions?: boolean;
     /** 宽松全局（调用点发现 exec 采集：未声明全局调用保守 unknown 不中断） */
     lenientGlobals?: boolean;
+    /**
+     * **关闭** async 体的生成器路径（`$async` 同步路径）——安全网。
+     *
+     * Bug 1139：生成器模式下 `await` 的位置表与转译侧脱节 ⇒ `yield` 落进嵌套
+     * 箭头 ⇒ `new Function` SyntaxError ⇒ **整个模块**编译失败 ⇒ 全部导出
+     * 丢失 ⇒ L2 闸门**假绿**（exit 0）。本开关让求值引擎能在生成器模式编译
+     * 失败时**重试一次**（关闭生成器路径）⇒ 模块至少编译得出来 ⇒ 导出可见。
+     */
+    disableAsyncGen?: boolean;
 };
 /**
  * inject/modules **内容**指纹（memo 键）。对象身份对「每次新建同内容」
  * 的 CLI 注入不稳——同一语义的 inject 跨 checkSource 调用会 miss 缓存。
  */
 declare function runTranspiledOptionsMemoKey(opts: RunTranspiledOptions | undefined): string;
-declare const RUNTIME_IMPORT_RE: RegExp;
+
+/**
+ * run 表的**顶层绑定表**：
+ * - 顶层 const/let（`$recordBinding` 通道，Abs 值）；
+ * - **私有**顶层函数声明（宿主 JS 函数；与 ANALYSIS_SLOTS 同源，导出面同名
+ *   可枚举键不重复登记——导出函数只走导出表）。
+ *
+ * 后者供 LSP completion / collectAbsBindingsFromGraph 与导出面复用同一套
+ * 宿主函数 → Abs 转换（源码形参表 / ctor facet）。
+ */
 declare function bindingsOf(run: Record<string, unknown>): Map<string, unknown> | undefined;
 /**
  * 执行一段 求值引擎程序，返回顶层 `export function` / `export const`。
@@ -867,12 +933,16 @@ declare function isAbsVal(v: unknown): v is Abs;
  *  callTranspiledExportApply）传引用——被调方对容器实参的变异必须对
  *  caller 帧可见（与同文件闭包调用同语义）；宿主重放（case/记录/LSP）
  *  不传，保持 D1 防御副本。
+ *  opts.preferLocal：**分析面**语义——按源码本地函数名解析
+ *  （nudo.analysis 表优先）。默认 false = 导出语义（callTranspiledExportApply
+ *  跨模块导出桥必须走导出槽；同名 re-export / CJS 合并值不得被本地函数顶替）。
  *  嵌套进入（导出桥 apply）继承外层预算；仅最外层宿主入口重置。
  *  #152 assume 前提不设选项位：播种统一走 withAssumePremises 动态域
  *  包裹（check.ts 的 runSeeded extent），单一机制无第二路径。 */
 declare function callTranspiledExportFull(exports: Record<string, unknown>, name: string, args: Abs[], opts?: {
     phi?: Phi;
     shareArgs?: boolean;
+    preferLocal?: boolean;
 }): TranspiledCallResult;
 /** 调用 runTranspiled 导出（仅结果） */
 declare function callTranspiledExport(exports: Record<string, unknown>, name: string, args: Abs[]): Abs;
@@ -887,7 +957,10 @@ declare function callTranspiledExport(exports: Record<string, unknown>, name: st
  * 宿主重放不走此工厂，保持 D1 防御副本。
  *
  * `exports` 可传惰性 getter（互递归模块桥：导出表在桥创建后才赋值）。
+ *
+ * **不传 preferLocal**：跨模块 import 桥必须调用**导出值**（同名 re-export /
+ * CJS 合并不得被本地私有函数顶替）；按名分析由调用方显式 preferLocal。
  */
 declare function callTranspiledExportApply(exports: Record<string, unknown> | (() => Record<string, unknown>), name: string): (args: Abs[], thisVal?: Abs) => AbsApplyResult;
 
-export { $tryDigestSoft as $, type Abs as A, orphanMayThrowEffects as B, type Confidence as C, popMayThrowFrame as D, ERROR_FAMILY as E, pushMayThrowFrame as F, recordMayThrow as G, resetEvalFallbackStats as H, runWithMayThrowSession as I, setMayThrowCollector as J, throwAbsToKinds as K, type LiteralValue as L, type MayThrowEffect as M, throwsKindCovered as N, withEvalBudgetOverride as O, type PrimName as P, type HofCollectCtx as Q, type RelSource as R, type Shape as S, type Term as T, type HofSite as U, type RunTranspiledOptions as V, $assignRecord as W, $call as X, $callNamed as Y, $recordBinding as Z, type AbsApplyNoThrow as _, type Pred as a, markPureFn as a$, type AbsApplyNoThrowFn as a0, type AbsApplyResult as a1, type AbsApplyReturn as a2, type AbsFnImpl as a3, type AbsSigImpl as a4, type EvalAbsAssignRecord as a5, type EvalCallRecord as a6, type EvalFallback as a7, type EvalPosRecord as a8, type ImplicationOracle as a9, confJoin as aA, emptyPhi as aB, eq as aC, evalExprAbs as aD, ge as aE, geNum as aF, getEvalCallCollector as aG, getFnImpl as aH, getImplicationOracle as aI, gt as aJ, gtNum as aK, hostFnCtorFacet as aL, implies as aM, isAbsApplyResult as aN, isAbsVal as aO, isBigPrim as aP, isCjsMainRun as aQ, isExactLit as aR, isNumPrim as aS, isStrPrim as aT, le as aU, leNum as aV, lit as aW, litValue as aX, lt as aY, ltNum as aZ, makeAbsApplyResult as a_, type LitValueResult as aa, MAX_EVAL_CALL_DEPTH as ab, MAX_EVAL_TOTAL_CALLS as ac, RUNTIME_IMPORT_RE as ad, TYPEOF_NAMES as ae, type TranspiledCallResult as af, type TypeofName as ag, abs as ah, absFunction as ai, absOnly as aj, absToString as ak, and as al, anyAbs as am, anyVar as an, app as ao, assumeFinite as ap, attachFnImpl as aq, bigintLit as ar, bindImports as as, bindingsOf as at, bool as au, boolLit as av, callTranspiledExport as aw, callTranspiledExportApply as ax, callTranspiledExportFull as ay, collectAbsExports as az, type Phi as b, namespaceAbsOf as b0, ne as b1, negatePred as b2, never as b3, not as b4, noteEvalCallRecord as b5, noteEvalFallback as b6, num as b7, numLit as b8, numVar as b9, str as bA, strLit as bB, substPred as bC, termEquals as bD, termToString as bE, tryRunTranspiled as bF, unknown as bG, v as bH, $nodoPos as bI, getPosCollector as bJ, routeApplyThrows as bK, obj as ba, or as bb, pFalse as bc, pTrue as bd, phiAnd as be, predEquals as bf, predToString as bg, predVars as bh, primToTypeof as bi, ptypeof as bj, pureFnNameOf as bk, relationFingerprint as bl, relationFn as bm, resetEvalCallBudget as bn, runTranspiled as bo, runTranspiledOptionsMemoKey as bp, setEvalAssignCollector as bq, setEvalBindingSink as br, setEvalCallCollector as bs, setEvalFallbackCollector as bt, setImplicationOracle as bu, setPosCollector as bv, shapeOfTerm as bw, shapeOnlyFn as bx, shapeToString as by, simplifyTerm as bz, type AbsModuleExports as c, type AstEnv as d, $tryMarkSoft as e, $tryReleaseSoft as f, type EvalFallbackStats as g, absLit as h, absNumLit as i, absStrLit as j, allAbsStr as k, clearPureCallMemo as l, clearPureMemo as m, enterEvalCallBudgetSession as n, errorTypeAbs as o, exitEvalCallBudgetSession as p, filterDeclaredThrows as q, filterGateThrows as r, filterIgnoredThrows as s, flushMayThrowEffects as t, formatThrowsAbs as u, getEvalCallBudgetState as v, getEvalFallbackStats as w, getMayThrowCollector as x, isThrowsIgnored as y, mayThrowEffectsToAbs as z };
+export { $tryDigestSoft as $, type Abs as A, orphanMayThrowEffects as B, type Confidence as C, popMayThrowFrame as D, ERROR_FAMILY as E, pushMayThrowFrame as F, recordMayThrow as G, resetEvalFallbackStats as H, runWithMayThrowSession as I, setMayThrowCollector as J, throwAbsToKinds as K, type LiteralValue as L, type MayThrowEffect as M, throwsKindCovered as N, withEvalBudgetOverride as O, type PrimName as P, type RelSource as Q, type RunTranspiledOptions as R, type Shape as S, type Term as T, type HofSite as U, $assignRecord as V, $call as W, $callNamed as X, $recordBinding as Y, type AbsApplyNoThrow as Z, type AbsApplyNoThrowFn as _, type Pred as a, ne as a$, type AbsApplyResult as a0, type AbsApplyReturn as a1, type AbsFnImpl as a2, type AbsSigImpl as a3, type EvalAbsAssignRecord as a4, type EvalCallRecord as a5, type EvalFallback as a6, type EvalPosRecord as a7, type ImplicationOracle as a8, type LitValueResult as a9, eq as aA, evalExprAbs as aB, ge as aC, geNum as aD, getEvalCallCollector as aE, getFnImpl as aF, getImplicationOracle as aG, gt as aH, gtNum as aI, hostFnCtorFacet as aJ, implies as aK, isAbsApplyResult as aL, isAbsVal as aM, isBigPrim as aN, isCjsMainRun as aO, isExactLit as aP, isNumPrim as aQ, isStrPrim as aR, le as aS, leNum as aT, lit as aU, litValue as aV, lt as aW, ltNum as aX, makeAbsApplyResult as aY, markPureFn as aZ, namespaceAbsOf as a_, MAX_EVAL_CALL_DEPTH as aa, MAX_EVAL_TOTAL_CALLS as ab, TYPEOF_NAMES as ac, type TranspiledCallResult as ad, type TypeofName as ae, abs as af, absFunction as ag, absOnly as ah, absToString as ai, and as aj, anyAbs as ak, anyVar as al, app as am, assumeFinite as an, attachFnImpl as ao, bigintLit as ap, bindImports as aq, bindingsOf as ar, bool as as, boolLit as at, callTranspiledExport as au, callTranspiledExportApply as av, callTranspiledExportFull as aw, collectAbsExports as ax, confJoin as ay, emptyPhi as az, type Phi as b, negatePred as b0, never as b1, not as b2, noteEvalCallRecord as b3, noteEvalFallback as b4, num as b5, numLit as b6, numVar as b7, obj as b8, or as b9, substPred as bA, termEquals as bB, termToString as bC, tryRunTranspiled as bD, unknown as bE, v as bF, $nodoPos as bG, getPosCollector as bH, routeApplyThrows as bI, pFalse as ba, pTrue as bb, phiAnd as bc, predEquals as bd, predToString as be, predVars as bf, primToTypeof as bg, ptypeof as bh, pureFnNameOf as bi, relationFingerprint as bj, relationFn as bk, resetEvalCallBudget as bl, runTranspiled as bm, runTranspiledOptionsMemoKey as bn, setEvalAssignCollector as bo, setEvalBindingSink as bp, setEvalCallCollector as bq, setEvalFallbackCollector as br, setImplicationOracle as bs, setPosCollector as bt, shapeOfTerm as bu, shapeOnlyFn as bv, shapeToString as bw, simplifyTerm as bx, str as by, strLit as bz, type AbsModuleExports as c, type AstEnv as d, $tryMarkSoft as e, $tryReleaseSoft as f, type EvalFallbackStats as g, absLit as h, absNumLit as i, absStrLit as j, allAbsStr as k, clearPureCallMemo as l, clearPureMemo as m, enterEvalCallBudgetSession as n, errorTypeAbs as o, exitEvalCallBudgetSession as p, filterDeclaredThrows as q, filterGateThrows as r, filterIgnoredThrows as s, flushMayThrowEffects as t, formatThrowsAbs as u, getEvalCallBudgetState as v, getEvalFallbackStats as w, getMayThrowCollector as x, isThrowsIgnored as y, mayThrowEffectsToAbs as z };