@nudojs/core 1.15.0 → 1.16.0

package/dist/{projection-budget-07VnMktV.d.ts → projection-budget-DW-svmIf.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-T9HWTziZ.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-T9HWTziZ.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.
@@ -554,6 +565,11 @@ type AstEnv = {
         body: Node;
         async?: boolean;
         kind?: string;
+        /**
+         * Bug 399：逐位「可省略」标记（与 `params` 同下标，`true` = 该位有
+         * 默认值 / 带 `?` / 是 rest）⇒ 必选元数不再靠名字后缀猜。
+         */
+        optionalParams?: boolean[];
     }>;
     /** class 表（旁路，withVar 必须保留） */
     classes?: Map<string, unknown>;
@@ -617,12 +633,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 统一路由，
@@ -758,6 +796,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 +836,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 +846,7 @@ type RunTranspiledOptions = {
     }>;
     /** @nudo:as 注入值：varName → Abs */
     asOverrides?: Record<string, Abs>;
-    /** @nudo:as 语句范围表 */
+    /** @nudo:as 语句范围表（stmtStart/stmtEnd = **字符区间**，非行号） */
     asOverrideTargets?: Array<{
         varName: string;
         stmtStart: number;
@@ -808,6 +861,15 @@ 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 键）。对象身份对「每次新建同内容」
@@ -890,4 +952,4 @@ declare function callTranspiledExport(exports: Record<string, unknown>, name: st
  */
 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 HofCollectCtx as Q, type RunTranspiledOptions as R, type Shape as S, type Term as T, type RelSource as U, type HofSite 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nudojs/core",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "engines": {
     "node": ">=22"
   },