@nudojs/core 1.15.2 → 1.16.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { d as AstEnv, A as Abs, b as Phi, T as Term, Q as HofCollectCtx, C as Confidence, S as Shape, a as Pred, R as RelSource, U as HofSite, c as AbsModuleExports, V as RunTranspiledOptions } from './run-DfloWX6i.js';
-export { W as $assignRecord, X as $call, Y as $callNamed, Z as $recordBinding, _ as AbsApplyNoThrow, a0 as AbsApplyNoThrowFn, a1 as AbsApplyResult, a2 as AbsApplyReturn, a3 as AbsFnImpl, a4 as AbsSigImpl, a5 as EvalAbsAssignRecord, a6 as EvalCallRecord, a7 as EvalFallback, a8 as EvalPosRecord, a9 as ImplicationOracle, aa as LitValueResult, L as LiteralValue, ab as MAX_EVAL_CALL_DEPTH, ac as MAX_EVAL_TOTAL_CALLS, P as PrimName, ad as RUNTIME_IMPORT_RE, ae as TYPEOF_NAMES, af as TranspiledCallResult, ag as TypeofName, ah as abs, ai as absFunction, aj as absOnly, ak as absToString, al as and, am as anyAbs, an as anyVar, ao as app, ap as assumeFinite, aq as attachFnImpl, ar as bigintLit, as as bindImports, at as bindingsOf, au as bool, av as boolLit, aw as callTranspiledExport, ax as callTranspiledExportApply, ay as callTranspiledExportFull, az as collectAbsExports, aA as confJoin, aB as emptyPhi, aC as eq, aD as evalExprAbs, aE as ge, aF as geNum, aG as getEvalCallCollector, aH as getFnImpl, aI as getImplicationOracle, aJ as gt, aK as gtNum, aL as hostFnCtorFacet, aM as implies, aN as isAbsApplyResult, aO as isAbsVal, aP as isBigPrim, aQ as isCjsMainRun, aR as isExactLit, aS as isNumPrim, aT as isStrPrim, aU as le, aV as leNum, aW as lit, aX as litValue, aY as lt, aZ as ltNum, a_ as makeAbsApplyResult, a$ as markPureFn, b0 as namespaceAbsOf, b1 as ne, b2 as negatePred, b3 as never, b4 as not, b5 as noteEvalCallRecord, b6 as noteEvalFallback, b7 as num, b8 as numLit, b9 as numVar, ba as obj, bb as or, bc as pFalse, bd as pTrue, be as phiAnd, bf as predEquals, bg as predToString, bh as predVars, bi as primToTypeof, bj as ptypeof, bk as pureFnNameOf, bl as relationFingerprint, bm as relationFn, bn as resetEvalCallBudget, bo as runTranspiled, bp as runTranspiledOptionsMemoKey, bq as setEvalAssignCollector, br as setEvalBindingSink, bs as setEvalCallCollector, bt as setEvalFallbackCollector, bu as setImplicationOracle, bv as setPosCollector, bw as shapeOfTerm, bx as shapeOnlyFn, by as shapeToString, bz as simplifyTerm, bA as str, bB as strLit, bC as substPred, bD as termEquals, bE as termToString, bF as tryRunTranspiled, bG as unknown, bH as v } from './run-DfloWX6i.js';
+import { d as AstEnv, A as Abs, b as Phi, T as Term, Q as HofCollectCtx, C as Confidence, S as Shape, a as Pred, U as RelSource, V as HofSite, c as AbsModuleExports, R as RunTranspiledOptions, L as LiteralValue } from './run-T9HWTziZ.js';
+export { W as $assignRecord, X as $call, Y as $callNamed, Z as $recordBinding, _ as AbsApplyNoThrow, a0 as AbsApplyNoThrowFn, a1 as AbsApplyResult, a2 as AbsApplyReturn, a3 as AbsFnImpl, a4 as AbsSigImpl, a5 as EvalAbsAssignRecord, a6 as EvalCallRecord, a7 as EvalFallback, a8 as EvalPosRecord, a9 as ImplicationOracle, aa as LitValueResult, ab as MAX_EVAL_CALL_DEPTH, ac as MAX_EVAL_TOTAL_CALLS, P as PrimName, ad as RUNTIME_IMPORT_RE, ae as TYPEOF_NAMES, af as TranspiledCallResult, ag as TypeofName, ah as abs, ai as absFunction, aj as absOnly, ak as absToString, al as and, am as anyAbs, an as anyVar, ao as app, ap as assumeFinite, aq as attachFnImpl, ar as bigintLit, as as bindImports, at as bindingsOf, au as bool, av as boolLit, aw as callTranspiledExport, ax as callTranspiledExportApply, ay as callTranspiledExportFull, az as collectAbsExports, aA as confJoin, aB as emptyPhi, aC as eq, aD as evalExprAbs, aE as ge, aF as geNum, aG as getEvalCallCollector, aH as getFnImpl, aI as getImplicationOracle, aJ as gt, aK as gtNum, aL as hostFnCtorFacet, aM as implies, aN as isAbsApplyResult, aO as isAbsVal, aP as isBigPrim, aQ as isCjsMainRun, aR as isExactLit, aS as isNumPrim, aT as isStrPrim, aU as le, aV as leNum, aW as lit, aX as litValue, aY as lt, aZ as ltNum, a_ as makeAbsApplyResult, a$ as markPureFn, b0 as namespaceAbsOf, b1 as ne, b2 as negatePred, b3 as never, b4 as not, b5 as noteEvalCallRecord, b6 as noteEvalFallback, b7 as num, b8 as numLit, b9 as numVar, ba as obj, bb as or, bc as pFalse, bd as pTrue, be as phiAnd, bf as predEquals, bg as predToString, bh as predVars, bi as primToTypeof, bj as ptypeof, bk as pureFnNameOf, bl as relationFingerprint, bm as relationFn, bn as resetEvalCallBudget, bo as runTranspiled, bp as runTranspiledOptionsMemoKey, bq as setEvalAssignCollector, br as setEvalBindingSink, bs as setEvalCallCollector, bt as setEvalFallbackCollector, bu as setImplicationOracle, bv as setPosCollector, bw as shapeOfTerm, bx as shapeOnlyFn, by as shapeToString, bz as simplifyTerm, bA as str, bB as strLit, bC as substPred, bD as termEquals, bE as termToString, bF as tryRunTranspiled, bG as unknown, bH as v } from './run-T9HWTziZ.js';
 import { Node, File } from '@babel/types';
-import { p as parseSource, L as LeakBudget, E as EffectiveInterfaceOpts, b as LoadDepsFingerprint, w as CheckReport, N as NudoConstraint, c as ProjectionBudget } from './projection-budget-07VnMktV.js';
-export { x as CONSTRAINT_BUILDERS, y as CONSTRAINT_BUILDER_NAMES, z as CONSTRAINT_EXPR_RE, A as CheckAction, C as CheckIssue, B as CheckJson, D as CheckJsonMulti, F as ConstraintBuilder, G as Diagnostic, H as EffectiveInterface, J as GitlabCodeQualityIssue, K as INTERFACE_SOURCE_ABBR, O as InterfaceDiag, I as InterfaceSource, Q as InterfaceTierInfo, a as InterfaceTierOpts, R as NamedImport, S as NudoField, T as NudoFnConstraint, U as NudoSidecarError, V as NudoSig, W as RefineDiag, X as RefineEntry, Y as RefineResolveOpts, Z as SELF, _ as actionsForIssue, $ as andC, a0 as any, a1 as array, a2 as boolean, a3 as checkArg, a4 as checkCall, a5 as constraintAdmitsNullish, a6 as constraintToEntryAbs, a7 as derefConstraint, a8 as drainPromiseMicros, a9 as effectiveInterface, aa as enterPromiseExecutorScope, ab as evalPromiseCtor, ac as evalPromiseMethod, ad as evalPromiseStatic, ae as execNudoModule, af as extractDeclaredThrows, ag as extractFnBudget, ah as extractNudoImports, ai as extractRefineReturnFromSource, aj as extractRefinesFromSource, ak as fn, al as fnConstraintToEntryReqs, am as formatCheckReport, an as formatConstraint, ao as formatDiagnostics, ap as formatEffectiveInterfaceDisplay, aq as formatGithubAnnotations, ar as formatGitlabCodeQuality, as as formatInterfaceTierLine, at as generatedExportNames, au as getParseSourceCacheSize, av as getTerm, aw as instantiateConstraint, ax as interfaceDiagCount, ay as interfaceSourceOf, az as interfaceTierOf, aA as isIntFlag, aB as isNodeModulesPath, aC as isNudoConstraint, aD as lazy, aE as leavePromiseExecutorScope, aF as lenTerm, aG as litC, aH as localNamedExports, aI as notePromiseExecutorFork, aJ as nullable, aK as number, aL as omit, aM as partial, aN as pick, aO as queuePromiseMicro, aP as refineDiagCount, aQ as refineToIndexedFull, aR as resetNudoModuleExecCache, aS as resetParseSourceCache, aT as resetSidecarLoadFailureCache, aU as serializeCheckJson, aV as serializeCheckJsonMulti, aW as setInterfaceDiagCollector, aX as setRefineDiagCollector, aY as shape, aZ as sidecarClosureFingerprint, a_ as sidecarPathOf, a$ as string, b0 as takeInterfaceDiags, b1 as takeInterfaceDiagsSince, b2 as takeRefineDiags, b3 as takeRefineDiagsSince, b4 as throwConstraintToKinds, b5 as union } from './projection-budget-07VnMktV.js';
+import { p as parseSource, L as LeakBudget, E as EffectiveInterfaceOpts, b as LoadDepsFingerprint, w as CheckReport, N as NudoConstraint, c as ProjectionBudget } from './projection-budget-DW-svmIf.js';
+export { x as CONSTRAINT_BUILDERS, y as CONSTRAINT_BUILDER_NAMES, z as CONSTRAINT_EXPR_RE, A as CheckAction, C as CheckIssue, B as CheckJson, D as CheckJsonMulti, F as ConstraintBuilder, G as Diagnostic, H as EffectiveInterface, J as GitlabCodeQualityIssue, K as INTERFACE_SOURCE_ABBR, O as InterfaceDiag, I as InterfaceSource, Q as InterfaceTierInfo, a as InterfaceTierOpts, R as NamedImport, S as NudoField, T as NudoFnConstraint, U as NudoSidecarError, V as NudoSig, W as RefineDiag, X as RefineEntry, Y as RefineResolveOpts, Z as SELF, _ as actionsForIssue, $ as andC, a0 as any, a1 as array, a2 as boolean, a3 as checkArg, a4 as checkCall, a5 as constraintAdmitsNullish, a6 as constraintToEntryAbs, a7 as derefConstraint, a8 as drainPromiseMicros, a9 as effectiveInterface, aa as enterPromiseExecutorScope, ab as evalPromiseCtor, ac as evalPromiseMethod, ad as evalPromiseStatic, ae as execNudoModule, af as extractDeclaredThrows, ag as extractFnBudget, ah as extractNudoImports, ai as extractRefineReturnFromSource, aj as extractRefinesFromSource, ak as fn, al as fnConstraintToEntryReqs, am as formatCheckReport, an as formatConstraint, ao as formatDiagnostics, ap as formatEffectiveInterfaceDisplay, aq as formatGithubAnnotations, ar as formatGitlabCodeQuality, as as formatInterfaceTierLine, at as generatedExportNames, au as getParseSourceCacheSize, av as getTerm, aw as instantiateConstraint, ax as interfaceDiagCount, ay as interfaceSourceOf, az as interfaceTierOf, aA as isIntFlag, aB as isNodeModulesPath, aC as isNudoConstraint, aD as lazy, aE as leavePromiseExecutorScope, aF as lenTerm, aG as litC, aH as localNamedExports, aI as notePromiseExecutorFork, aJ as nullable, aK as number, aL as omit, aM as partial, aN as pick, aO as queuePromiseMicro, aP as refineDiagCount, aQ as refineToIndexedFull, aR as resetNudoModuleExecCache, aS as resetParseSourceCache, aT as resetSidecarLoadFailureCache, aU as serializeCheckJson, aV as serializeCheckJsonMulti, aW as setInterfaceDiagCollector, aX as setRefineDiagCollector, aY as shape, aZ as sidecarClosureFingerprint, a_ as sidecarPathOf, a$ as string, b0 as takeInterfaceDiags, b1 as takeInterfaceDiagsSince, b2 as takeRefineDiags, b3 as takeRefineDiagsSince, b4 as throwConstraintToKinds, b5 as union } from './projection-budget-DW-svmIf.js';
 export { $add, $arguments, $arr, $arrMutContainer, $arrRest, $arrWithHoles, $async, $asyncReturn, $await, $bitand, $bitnot, $bitor, $bitxor, $catchVal, $class, $classExpr, $collectionForEach, $concat, $copy, $del, $delRes, $div, $dynamicImport, $elems, $eq, $eqLoose, $fnVal, $for, $forInKeys, $forIter, $forOf, $fork, $ge, $gen, $get, $gt, $idx, $idxSet, $importMeta, $in, $instanceof, $instanceofNonIdent, $invoke, $invokeSuper, $isBreakTo, $isForkExit, $join, $le, $len, $lit, $loopBreak, $loopContinue, $loopReturn, $lt, $mod, $mul, $ne, $neLoose, $neg, $new, $not, $nullishTest, $obj, $objAccessor, $objRest, $optionalGet, $optionalInvoke, $orDefault, $pow, $pushLoopExit, $rawThis, $reStateCall, $regex, $rethrowIfNudoReturn, $set, $setKey, $shl, $shr, $spread, $staticInvoke, $sub, $super, $switch, $thisGet, $thisSet, $throw, $toNumber, $toNumeric, $tryCurrentMark, $tryDetachSoftCatch, $tryDigestSoftCatch, $tryDiscardSoft, $tryMark, $tryOrphanSoft, $tryPopMark, $tryReleaseSoftCatch, $tryReleaseSoftOut, $tryTakeSince, $typeof, $unknown, $updateAdd, $updateSub, $ushr, $while, $whileSeq, $yield, DEFAULT_MAX_LOOP_ITERS, EvalClassSpec, NudoLoopSignal, NudoReturn, NudoThrow, NudoUnsupportedError, TranspileOptions, asAbsVal, callAtFunctionBoundary, clearBClasses, clearStaleTermPred, currentExecPhi, fillTuple, foldRequireSpecArg, foldStaticStringExpr, getEvalClass, isArrMutator, isDefinitelyFalse, isDefinitelyTrue, isNudoBreak, isNudoContinue, isNudoReturn, isNudoThrow, litTruth, lookupObjAccessor, namespaceNameOf, pushLoopExit, pushThrowExit, registerEvalClass, runWithLoopExits, runtimeImportOf, takeLoopExits, takeThrowExits, transpile, transpileBodyNode, transpileExpression, transpileFile, transpileSource, withExecPhi } from './exec.js';
 
 /**
@@ -86,11 +86,64 @@ declare namespace spy {
  */
 declare function mock(): MockHelper;
 
+/**
+ * 剥除选项（**可选**能力；分析面不传 ⇒ 行为与旧版逐字一致）。
+ *
+ * - report：剥除**事实**回报（只写不改）。migrate strip 的 notes 据此判定
+ *   「提示与事实是否一致」——注释 / 字符串里的 "enum " / "namespace "
+ *   不是声明，裸正则会误报（Bug 596）。
+ * - resolveSpecifier：相对说明符改写（migrate strip 的**产物**面）。
+ *   给「相对 spec」返回「产物 spec」，返回 undefined 表示不改写；
+ *   包说明符（"pkg" / "@scope/pkg"）永不进入该回调。
+ *
+ * report 的字段（**全部可选**；未发生的事实不写 ⇒ 调用方按 `=== true` 判定）：
+ * - enumRemoved：TS enum 声明被**整条删除**（仅 `declare enum` —— 环境声明
+ *   没有运行时语义）。**运行时 enum 现在是被「合成」而不是被删除** ⇒ 用
+ *   enumSynthesized 判定（Bug 913）。
+ * - enumSynthesized：TS enum 被**合成成运行时对象**（Bug 913）。
+ * - namespaceKept：非 declare 的 namespace 被保留（运行时语义）。
+ * - exportAssignmentRemoved：`export = X` / `export as namespace X` 被剥除
+ *   （Bug 446）。
+ * - thisParamRemoved：TS 的 `this` 形参被从形参数组里删除（Bug 448）。
+ * - typeOnlyImportRemoved：**本地**（相对路径）import 的绑定只在类型位置被
+ *   用到（值位置零引用）⇒ 被消掉（与 tsc 的 import elision 同口径）（Bug 445）。
+ * - typeOnlyImportKept：值位置的导入**被保留**（绑定有值位置引用，或引用
+ *   形态判不准 ⇒ 保守保留）⇒ 产物面应当提示人工确认（Bug 445）。
+ * - directivesBefore / directivesAfter / directivesDropped：**剥除前后**的
+ *   `@nudo:` 指令条数比对（Bug 968 的兜底自检）——不等 ⇒ 有指令随被删语句
+ *   一起消失。
+ * - ctorParamPropsSuperMissing：**派生类**的构造器参数属性降级时，构造器体
+ *   **顶层**找不到 `super(...)` 调用 ⇒ 赋值只能落回构造器体开头（原生语义：
+ *   `super()` 之前访问 `this` ⇒ ReferenceError；源本身即非法 TS）⇒ 产物面
+ *   应当提示人工确认（Bug 1071）。
+ */
+type StripOptions = {
+    report?: {
+        enumRemoved?: boolean;
+        enumSynthesized?: boolean;
+        namespaceKept?: boolean;
+        exportAssignmentRemoved?: boolean;
+        thisParamRemoved?: boolean;
+        typeOnlyImportRemoved?: boolean;
+        typeOnlyImportKept?: boolean;
+        directivesBefore?: number;
+        directivesAfter?: number;
+        directivesDropped?: boolean;
+        ctorParamPropsSuperMissing?: boolean;
+    };
+    resolveSpecifier?: (spec: string) => string | undefined;
+};
 /**
  * 原地剥除 AST 中的 TS-only 语法节点/字段，返回同一棵 AST（便于链式使用）。
  * 不改写任何 loc/start/end；语句删除只影响所在数组，不重排兄弟节点。
+ *
+ * @param source 源码文本（可选）。给了就把**类型注解的源码文本**留在节点上
+ *   （`nudoTypeText` / `nudoReturnTypeText`，见文件头）——分析面据此读回
+ *   `.ts` 源的声明类型；不给（migrate 的 keepTs 路径等）则纯剥除。
+ * @param opts 可选能力（见 StripOptions）：剥除事实回报 + 相对说明符改写。
+ *   分析面**不传** ⇒ 行为与旧版逐字一致。
  */
-declare function stripTypes<T extends Node>(ast: T): T;
+declare function stripTypes<T extends Node>(ast: T, source?: string, opts?: StripOptions): T;
 
 /**
  * 路径约束栈（Φ）。
@@ -360,6 +413,23 @@ declare function looseEqAbs(a: Abs, b: Abs): boolean | undefined;
 /**
  * 对象不变性侧表（freeze/seal/preventExtensions/defineProperty）。
  * WeakMap 侧表：Abs 不可变，写路径读侧表复现 sloppy 静默失败。
+ *
+ * Invariants（Bug 295）：
+ * - 枚举视图分**两套口径**，不得混用：
+ *   - `enumOwnKeys` = **CopyDataProperties 视图**（自有可枚举键，**含**
+ *     symbol 投影槽）——原生 spread `{...o}` / **对象 rest** / Object.assign
+ *     复制自有可枚举 **symbol 键**（node v26 实测：rest 也拷——`rest[
+ *     Symbol.toStringTag] === 2`；`{...{[Symbol.iterator](){}}}` 仍可迭代 ⇒
+ *     引擎的 @@iterator 协议槽正靠这条拷贝链落地）。
+ *   - `enumOwnStringKeys` = **字符串键视图**（**剔除** symbol 投影槽）——
+ *     原生 for-in / Object.keys|values|entries / getOwnPropertyNames /
+ *     JSON.stringify 只枚举字符串键。
+ *     **注意**（Bug 1075）：`Object.getOwnPropertyDescriptors` **不在**此列——
+ *     原生 gOPDs 走 [[OwnPropertyKeys]]（**含** symbol 键：结果对象带真
+ *     symbol 键，`Object.getOwnPropertySymbols(gOPDs(o))` 看得到）。
+ * - 报告建议「给 enumOwnKeys 补 symbolKey 过滤」与原生 oracle 冲突：它会
+ *   把 symbol 键从 spread/assign/rest 的拷贝链里剔掉 ⇒ 折坏 @@iterator 协议
+ *   槽（core 既有 8 处回归）。故按 oracle 拆两套视图，调用点分流。
  */
 
 type ExtState = "nonext" | "sealed" | "frozen";
@@ -384,6 +454,12 @@ declare function migrateInvariants(from: Abs, to: Abs): void;
  * NaN 策略（DEC：显式 NaN 臂）：操作数可能为 NaN 时结果为
  * `NaN | number@bounds`。契约 `ge(0).le(100)` 对 NaN 臂诚实报违例；
  * `if (Number.isNaN(n)) return …` 假臂的 `ne(n, NaN)` 事实可排除 NaN 臂。
+ *
+ * Invariants（Bug 958）：min/max 的**区间端点合并按合取/析取分家**——
+ * 合取位（min 的 lo / max 的 hi：`min(a,b) ≥ L ⟺ a ≥ L ∧ b ≥ L`）端点值
+ * 相同取**更松**（非 strict）的一侧；析取位（max 的 lo / min 的 hi）取
+ * **更严**的一侧。取反会产出**不可满足**谓词（`min(x,0) > 0 ∧ ≤ 0`）⇒
+ * 证明器 ex falso 放电 ⇒ 契约门禁假绿 + 分支选错臂且 `conf: exact`。
  */
 
 declare function evalMathMethod(name: string, args: Abs[]): Abs | undefined;
@@ -408,6 +484,26 @@ declare function evalMathMethod(name: string, args: Abs[]): Abs | undefined;
  *   侧表派发（getter 读折返回体、setter 写走侧表不误抛 writable:false）；
  *   描述符字段语义 = 新建属性缺省 false、已有属性仅显式 false 收紧；
  *   open/index 标记与 invariants/accessor 侧表随不可变更新迁移。
+ * - Bug 292：描述符字段语义改按 ES2024 10.4.5 ToPropertyDescriptor 的
+ *   **字段存在性**（HasProperty）——`get: undefined` 仍是「有 get 字段」
+ *   （⇒ 与 value/writable 共存 → 定抛）、`writable/enumerable/configurable:
+ *   undefined` ⇒ ToBoolean → false（收紧，不是「缺省保持原状」）。
+ *   安装机器实现 ValidateAndApplyPropertyDescriptor（10.4.9）：目标已有键
+ *   且**不可配置**时，标志/值/访问机制不可变（不可配置 / 枚举改 / 写门改 /
+ *   值改 / 数据↔访问器互转 → 重定义失败）；目标为**新键**且不可扩展 → 失败。
+ *   已有属性的标志**双向**应用描述符显式字段（未指定字段保持当前值）——
+ *   enumerable:false → enumerable:true 可恢复（此前只单向收紧，永不恢复）。
+ *   失败信号分两面：Object 口径定抛 TypeError（applyPropertyDescriptor）、
+ *   Reflect 口径返 false 不抛（applyPropertyDescriptorVerdict）。
+ * - Bug 300：Proxy [[GetOwnProperty]] 陷阱的单一实现
+ *   （proxyGetOwnPropDescTrap：派发 + ToPropertyDescriptor 非对象 → 定抛 +
+ *   completePropDescAbs 补全描述符）——Reflect 面在 builtins/reflect.ts
+ *   调用；Object 面需在 builtins/object/methods.ts 接线（越界诉求见报告）。
+ * - Bug 1074：Proxy [[GetOwnProperty]] 的**靶一致性不变量**（ES2024 10.5.5
+ *   step 12.f）——靶自有 + 不可配置 + 不可写的数据属性，陷阱描述符的
+ *   [[Value]] 必须 SameValue 靶上的实际值，否则原生定抛 TypeError
+ *   （enforceProxyGetOwnPropDescInvariant；口径与 [[Get]] 面的
+ *   exec/runtime/state.ts enforceProxyGetInvariant 同源）。
  * - Bug 86：tuple 接收者不再静默丢弃——下标键逐位装（增长段 hole、
  *   空描述符清 hole）、length 键截断/延长（非法 RangeError）、
  *   {writable:false} length 以 sealed 近似、frozen 相同值重定义放行。
@@ -420,6 +516,12 @@ declare function evalMathMethod(name: string, args: Abs[]): Abs | undefined;
  * - classifyAssignSet（Bug 128）是 Object.assign 逐键 [[Set]] 单一分类：
  *   自有访问器 setter / __proto__ 原型 setter（null|对象设原型、原始值
  *   忽略、抽象 open）/ 自有·继承非可写定抛 / 其余建自有键。
+ * - Bug 210：Proxy [[OwnPropertyKeys]] 的单一实现（proxyOwnKeysTrapKeys
+ *   派发 + enforceProxyOwnKeysInvariant 校验）——重复名 / 非字符串键 /
+ *   漏靶的不可配置自有键 / 不可扩展靶的多余键 → 原生定抛 TypeError；
+ *   不可判面（抽象键 / 抽象靶键集）→ 不抛（sound 保守）。
+ *   proxyTargetOwnStringKeys / proxyTargetEnumerableStringKeys 给出靶的
+ *   自有字符串键面（gOPN / Object.keys 用；internal·inherited·"@@X" 槽剔除）。
  *
  * 兄弟模块边界：methods.ts（evalObjectMethod）经导出复用安装机器；
  * readProperty 供 json.ts（stringify 读值）。
@@ -445,6 +547,27 @@ declare function assignSourceSlots(src: Abs): Record<string, {
  *   Abs 对象原型进 protoTable（[[Prototype]] 事实，Bug 67——instanceof 链
  *   终止判定不得把 null 终止链折 true）；第二实参 propertiesObject 逐可
  *   枚举键过 ToPropertyDescriptor 安装自有属性（Bug 32/23）。
+ * - Bug 323：create 的第二实参按**值**判定——「If properties is not
+ *   undefined」⇒ 显式 `undefined` 与不传同义（整步跳过，不抛）；`null` 抛。
+ * - Bug 324：defineProperties 的第二实参走 **ToObject**——null/undefined
+ *   抛；其它原始值装箱成零自有可枚举属性的包装器 ⇒ 不定义任何属性、不抛
+ *   （非空字符串例外：装箱后有下标键 ⇒ 描述符是字符 ⇒ TypeError）。
+ * - Bug 291：freeze / seal 落**键级标志**（freeze ⇒ writable+configurable
+ *   假；seal ⇒ configurable 假）＋ isFrozen / isSealed 的**平凡真**判定
+ *   （不可扩展 ∧ 每个自有属性不可配置 ∧（数据属性）不可写）。
+ * - Bug 301：freeze / seal 对 **Proxy** 走陷阱（preventExtensions ＋ 逐键
+ *   defineProperty；falsy ⇒ TypeError）。
+ * - Bug 308：RegExp 实例的自有 `lastIndex`（gOPN = 「全部自有键」语义）
+ *   与 gOPD 的数据描述符（可写、非可枚举、不可配置）。
+ * - Bug 315：Object.prototype.toLocaleString 的委派在 object-proto.ts；
+ *   本模块的描述符面须与之同口径（gOPDs 的访问器描述符 = {get, set}）。
+ * - Bug 326：键家族（keys/values/entries）对**自有键集不完备**的对象折
+ *   partial（标记在 prop flags 侧表）——不得折 exact 空元组。
+ * - Bug 1075：gOPDs 的自有键面走 [[OwnPropertyKeys]]——**含 symbol 键**
+ *   （原生 gOPDs 的结果对象带真 symbol 键）⇒ symbol 投影槽**保留**并带
+ *   `symbolKey` 标记（字符串键面 Object.keys / gOPN 仍剔除它）。
+ * - Bug 1077：不可变原型 Object.prototype 置 **null** 原型**放行**
+ *   （protoChangeAllowed；置非 null 仍拒——Object 面抛 / Reflect 面 false）。
  * - 未建模方法 → undefined 走通用回退。
  */
 
@@ -453,6 +576,18 @@ declare function evalObjectMethod(name: string, args: Abs[]): Abs | undefined;
 
 /**
  * JSON.parse / JSON.stringify
+ *
+ * Invariants:
+ * - **brand 折叠是递归的**（Bug 327）：内建 brand（Date / Map / Set / RegExp /
+ *   Error 族 / TypedArray / 装箱 prim…）的 JSON 值域在**任意深度**折叠——
+ *   顶层与对象/数组成员同款（此前白名单只对顶层接收者生效 ⇒ 嵌套 brand 一律
+ *   落「may carry BigInt / circular / throwing toJSON」⇒ L1/L2 假红）。
+ * - **total ≠ 精确**：值不可知但恒不抛的 brand（TypedArray 家族：元素值未
+ *   建模）折 total（值域 partial），**不**折成 "{}"——那会造出自信的错值。
+ * - bigint 元素家族（BigInt64Array / BigUint64Array）原生**定抛** TypeError
+ *   ⇒ 不在 total 集（保持 may-throw 记账）。
+ * - reviver（parse）与 replacer（stringify）**两侧口径对称**（Bug 298）：
+ *   callable 回调**真执行**（副作用通道不丢），返回值域保守（unknown）。
  */
 
 /** JSON.parse / stringify：字面量实参真执行折叠；失败硬抛（catch 可吸收） */
@@ -474,6 +609,22 @@ declare function evalGlobalFn(name: string, args: Abs[]): Abs | undefined;
 
 /**
  * Array 构造 / Array.* 静态方法
+ *
+ * Invariants:
+ * - Bug 202：`Array.from(用户 iterable)` **实际驱动**用户迭代器（GetIterator
+ *   + IteratorNext，元素按迭代序取）——与 elemsOf / for-of / spread 同款
+ *   协议；迭代器报告 done ⇒ 元素数确切 ⇒ exact 元组。
+ * - Bug 195：`Array.isArray` 认**数组视图标注**（markMatchArrayView）的对象
+ *   ——标签模板对象是冻结的数组 exotic（原生 true）；RegExp exec/match
+ *   结果同款（原生亦是真数组）。
+ * - Bug 294：array-like 读数（length / 逐索引）**先经访问器侧表**
+ *   （accessorReadDomain）——真 getter 住侧表、shape 里只有占位槽；
+ *   裸读槽 ⇒ length 被当 undefined（折空数组）+ getter 副作用消失。
+ *   每次 Array.from 读一次 length / 每个索引（与原生同款）。
+ * - Bug 296：`Array.from(items, mapFn, thisArg)` 的**第三实参**透传给
+ *   回调（此前丢弃 ⇒ 回调 this 恒 undefined ⇒ 假抛 / 计数器归零）。
+ * - Bug 330：Array.prototype.{toString,toLocaleString,join} 接收者为
+ *   **nullish** ⇒ 定抛 TypeError（ToObject）——不记抛 ⇒ L2 门禁假绿。
  */
 
 declare function makeArrayCtorAbs(args: Abs[]): Abs;
@@ -488,6 +639,18 @@ declare function evalArrayStatic(name: string, args: Abs[]): Abs | undefined;
  * coercer 槽 total（ToPrimitive 恒得 "[object Object]" → Invalid Date）；其余
  * 抽象 may（coercer 可能产 Symbol/BigInt）。多参形式每个实参直接 ToNumber。
  * Bug 62：setter 实参逐个 ToNumber 校验；getter/toString 族值域建模。
+ *
+ * Invariants:
+ * - Bug 297：Date 的 time value 是**可写槽**（构造期写入 brand shape 的 tv
+ *   facet）。`Date.prototype.set*` 族不再是空操作——按规范语义回写该槽
+ *   （MakeDay/MakeTime 归一化、月日溢出、TimeClip 越界 → Invalid Date，与
+ *   原生逐条同口径：实现走**宿主 Date**，两位年映射差异（构造器 1900 偏移 vs
+ *   setter 不偏移）自动对齐）。**实参不可判定 → 作废该槽**（精确渲染面随之
+ *   降级为 may-throw，绝不给过期日期）。getTime/valueOf 与 toISOString 读
+ *   同一槽 ⇒ 读面 / 投影面（JSON.stringify）同源，不会自相矛盾。
+ * - Bug 319：`toJSON` 单列一档——Invalid Date（tv=NaN）→ **null 字面量**
+ *   （原生返回 null，不是字符串）；tv 已知且有效 → ISO 串；tv 不可知 → 保守
+ *   `string | null` 域（不再是恒 string）。
  */
 
 declare function evalDateCtor(args: Abs[]): Abs;
@@ -496,6 +659,14 @@ declare function evalDateMethod(name: string, recv: Abs, args: Abs[]): Abs | und
 
 /**
  * RegExp 构造 / brand / 实例方法
+ *
+ * Invariants:
+ * - RegExpExecArray 原生是**数组 exotic**（IsArray = true，继承
+ *   Array.prototype）⇒ 匹配结果既有**数组方法面**（join / slice / map…，
+ *   经 markMatchArrayView 侧表 + 数组方法派发），也有**可迭代面**
+ *   （spread / for-of / 数组解构）。后者经「@@iterator 槽（非枚举）+
+ *   元素侧表」给出（Bug 290）——形状仍是 obj（容器 arr/tuple 无侧槽，
+ *   #136 的槽读面依赖它）。
  */
 
 declare function evalRegExpCtor(args: Abs[]): Abs;
@@ -566,7 +737,12 @@ declare function isObjectProtoBrand(a: Abs | undefined): boolean;
  * 与 new 分派在 dispatch.ts。
  */
 
-declare function evalNamespaceCall(ns: string, method: string, args: Abs[]): Abs | undefined;
+/**
+ * 命名空间静态分派。Bug 311：thisVal = 静态方法值的 this 绑定（成员读出的
+ * 静态方法被单独调用时的接收者，如 `Promise.resolve.call(null, 1)`）；
+ * 缺席 = 直接命名空间调用（this ≡ 命名空间构造器，合法）。
+ */
+declare function evalNamespaceCall(ns: string, method: string, args: Abs[], thisVal?: Abs): Abs | undefined;
 
 /**
  * Error 家族（ERROR_CTOR_NAMES/isErrorCtorName/errorBrandAbs）+ 宿主构造器
@@ -595,8 +771,8 @@ declare function isErrorCtorName(name: string | undefined): boolean;
 /**
  * Error brand：shape 带 name/message（字面量 message 保精确）。
  * AggregateError(errors, message[, options])：message 在第二实参，errors
- * 挂 .errors（原生是实参数组副本）；options.cause 挂 .cause（闭槽 miss
- * 会折 undefined 假精确——原生 .cause 可能有值）。
+ * 挂 .errors（原生是实参数组**副本**——见 iterableListCopy）；options.cause
+ * 挂 .cause（**仅当 options 真有 cause 键**才装槽——见 Bug 316）。
  * $new 的 new Error 路径共用——catch 形参成员访问可解。
  */
 declare function errorBrandAbs(name: string, args: Abs[]): Abs;
@@ -610,10 +786,13 @@ declare function errorBrandAbs(name: string, args: Abs[]): Abs;
  * - 两入口是内建构造/实例方法的总分派（exec $new 宿主分支与 Abs 面
  *   evalBuiltinNew 共用各域 builder；未建模名/方法 → undefined 走通用
  *   回退，不得折精确值）。
- * - TA set 三段校验（Bug 38）：ToIndex(offset) + ToObject(source) +
- *   off+srcLen > tgtLen 越界——长度读 binary 域构造入槽的 length 槽
- *  （makeTypedArrayAbs 数字形态）/ taSetSourceLength（tuple 元数/字符串
+ * - TA set 四段校验（Bug 38/304/305）：ToIndex(offset) + ToObject(source) +
+ *   off+srcLen > tgtLen 越界 + 源/目标内容类型一致（number vs bigint）+
+ *   逐元素 ToNumber/ToBigInt 转换——长度读 binary 域构造入槽的 length 槽
+ *   （makeTypedArrayAbs 数字形态）/ taSetSourceLength（tuple 元数/字符串
  *   长度/TA 源槽/装箱折 0）；成功恒返 undefined，元素拷贝值域不建模。
+ *   原生报错序（node v26）：越界（RangeError）→ 内容类型（TypeError）→
+ *   元素转换（TypeError/SyntaxError）——越界不可判时后两段只记 may。
  * - ArrayBuffer.resize（Bug 39）：resizable 槽 false 字面量定抛
  *   TypeError；成功臂 byteLength 槽**原地更新**（$set 引用语义惯例——
  *   别名同步）；transfer/grow/slice 不在此扩 scope。
@@ -621,11 +800,24 @@ declare function errorBrandAbs(name: string, args: Abs[]): Abs;
  *   viewLen 定抛 RangeError；读返回域按元素类型（bigint 家族 → bigint）。
  * - Error 家族 toString/toLocaleString = `${name}: ${message}`（槽已
  *   建模，空 message 只返 name）；Map/Set 方法族落 collections 条目机，
- *   迭代三件套经 iterator.ts 协议对象（mapEntryKey/setEntryTuple 条目
- *   投影），Set ES2025 方法族先过 binary 域 set-like 校验再 setMethodFold
+ *   迭代三件套经 iterator.ts 协议对象（collectionIteratorFor——**live
+ *   视图**，Bug 198：新增条目被访问、删除条目被跳过；快照与 live 同投影，
+ *   live 迭代器不登记静态元素侧表），Set ES2025 方法族先过 binary 域 set-like
+ *   校验再 setMethodFold
  *  （不可折 → 集合运算诚实 unknown / is* 抽象 boolean）。
  */
 
+/**
+ * Bug 198：Map/Set 迭代三件套（keys / values / entries）= **live 视图**的
+ * 协议对象——原生迭代器持条目指针：迭代期间**新增**的条目被访问、**删除**的
+ * 条目被跳过（`const it = m.keys(); it.next(); m.delete("b"); it.next().done`
+ * 原生 true，引擎快照口径折 false）。
+ *
+ * 投影与 live 视图的**同口径实现**都在 `builtins/error/iterator.ts` 的
+ * `collectionIteratorFor`（project 闭包只有一份：Map 的 keys/values 给
+ * 键/值，Set 的 entries 给 [el,el] 元组）——本文件此前自建了一份等价实现
+ * （绕开 iterator.ts 的投影错配），S17 已改回**直调**。
+ */
 /** new X(...) */
 declare function evalBuiltinNew(className: string, args: Abs[]): Abs | undefined;
 /** brand 实例方法（Date/RegExp/Map/Set/Error 家族/装箱拆箱后的 prim 面在外层） */
@@ -679,6 +871,17 @@ declare function stringOfSymbol(a: Abs): Abs;
 
 /**
  * Object.prototype 成员（hasOwnProperty / isPrototypeOf / toString / …）
+ *
+ * Invariants:
+ * - toString 走 typeTagOf 的**标签面**（"[object X]"）；toLocaleString 走
+ *   **委派面**（Bug 315：node 实测 Object.prototype.toLocaleString 调
+ *   接收者的 toString()——**不**调接收者自有的 toLocaleString；接收者没有
+ *   可调用的 toString（null 原型对象）⇒ TypeError）。委派面的「读接收者
+ *   toString 成员」由 exec 侧（member.ts）注册钩子提供（避免
+ *   builtins↔exec 的 import 环）。
+ * - Bug 325：fn 形状的标签按**函数种类**分（Function / AsyncFunction /
+ *   GeneratorFunction / AsyncGeneratorFunction）——种类戳由 transpile 侧
+ *   $fnVal opts.kind 打。
  */
 
 /**
@@ -736,10 +939,15 @@ type Slot = {
 /** ES 规范数组下标（无前导零、< 2^32-1）；非规范键返回 undefined */
 declare function canonicalArrayIndex(v: unknown): number | undefined;
 /**
- * ES ToPropertyKey 的字面量折叠：null→"null"、undefined→"undefined"、
+ * ES ToPropertyKey 的折叠：null→"null"、undefined→"undefined"、
  * true/false→"true"/"false"、number/bigint/string → String(v)（ToString）。
  * 必须看 term——litValue 把 lit(undefined) 吞成哨兵 undefined。
  * 抽象 / symbol 返回 undefined（调用方保守处理）。
+ *
+ * Bug 383：**对象键**也走 ToPropertyKey（ToPrimitive(string) → ToString）——
+ * 钩子**真调用**（与 Bug 381 的钩子调用面同口径：副作用与 throw 域随之而来）。
+ * 修前只认字面量 term ⇒ 对象键落「抽象键」臂 ⇒ 写被静默丢弃、键的强制
+ * 转换副作用全丢。
  */
 declare function propertyKeyOf(a: Abs | undefined): string | undefined;
 type ObjShape = {
@@ -1008,24 +1216,68 @@ declare function formatAbsMultiline(a: Abs, label?: string): string;
  * - ObjectPattern / ArrayPattern → 求值占位 `_p{i}`；契约面 = 顶层绑定名
  *   （对象属性 / 数组元素 Identifier）。嵌套 pattern 的绑定名标 `nested`，
  *   消费方可显式降级（C4.5 param-mismatch / 不执法）。
+ *
+ * Bug 479：`tsType` 携带**源码里的 TS 声明类型文本**（剥除 pass 留下的旁路
+ * `nudoTypeText`）——`.ts` 源的形参据此不是「无约束 any」。
+ *
+ * Bug 388：`kind: "pattern"` 同时覆盖 `ObjectPattern` 与 `ArrayPattern`
+ * ⇒ 模型层**记录模式种类**（`patternKind`），渲染层（签名面）与执法层
+ * （契约寻址）才能区分「按属性键寻址」与「按下标寻址」。
+ *
+ * Bug 397：TS 的 `this: T` 是**接收者标注**，不是运行时形参（Babel AST 里
+ * 就是 `Identifier("this")`）⇒ 不进形参表、不占实参位。
+ *
+ * Bug 399：默认形参**可省略** ⇒ 形参表带 `optional` 标记（消费侧据此算
+ * 必选元数，不再靠名字后缀猜）。
  */
 type FormalParam = {
     kind: "id";
     name: string;
     index: number;
+    tsType?: string;
+    /** 该形参位可省略（Bug 399）：true = 不计入必选元数 */
+    optional?: boolean;
 } | {
     kind: "default";
     name: string;
     index: number;
+    tsType?: string;
+    /** 默认形参恒可省略（Bug 399） */
+    optional?: boolean;
 } | {
     kind: "rest";
     name: string;
     display: string;
     index: number;
+    tsType?: string;
+    /** rest 形参恒可省略（Bug 399） */
+    optional?: boolean;
+    /**
+     * S6-1008：rest 形参的**元数信息**（本函数接受的实参个数域）。
+     *
+     * - `min`：**必选元数**——rest 之前**必选**形参的个数（默认形参 /
+     *   带默认值的解构形参可省略 ⇒ 不计；TS 的 `this` 接收者标注不是形参
+     *   ⇒ 不计）。
+     * - `variadic`：**变长**——rest 吸收 0..n 个实参 ⇒ 元数**无上界**
+     *   （「真正变长」由 core 建模 ⇒ 消费方不再各自按名字后缀猜）。
+     *
+     * 缺省 = undefined（未建模 ⇒ 消费方按既有「定长」口径处理）。
+     */
+    arity?: {
+        min: number;
+        variadic: true;
+    };
 } | {
     kind: "pattern";
     /** 求值/签名占位名（generalize 与 dts 用） */
     placeholder: string;
+    /**
+     * 模式种类（Bug 388）：
+     * - `"object"` = 对象解构（契约面按**属性键**寻址）
+     * - `"array"` = 数组解构（契约面按**元素下标**寻址）
+     * 缺省 = `"object"`（历史口径）。
+     */
+    patternKind?: "object" | "array";
     /** 顶层可表达绑定名（侧车契约面） */
     bound: string[];
     /**
@@ -1033,6 +1285,11 @@ type FormalParam = {
      * 投影必须用属性键 a（Abs 对象只有 slot a）。
      */
     propKey: Record<string, string>;
+    /**
+     * 数组解构：绑定名 → **元素下标**（`[a, b]` ⇒ a→0、b→1）。
+     * 对象解构不用这张表（对象解构按属性键寻址，见 `propKey`）。
+     */
+    boundIndex?: Record<string, number>;
     /** 仅嵌套内出现、顶层不可单独表达的名（降级用） */
     nested: string[];
     /**
@@ -1041,6 +1298,10 @@ type FormalParam = {
      */
     nestedPaths: string[];
     index: number;
+    /** TS 声明类型文本（.ts 源；缺省 = 无注解） */
+    tsType?: string;
+    /** 带默认值的解构形参（`{ a } = {}`）可省略（Bug 399） */
+    optional?: boolean;
 };
 type AstParam = {
     type: string;
@@ -1048,6 +1309,8 @@ type AstParam = {
     left?: AstParam;
     right?: unknown;
     argument?: AstParam;
+    /** Bug 479：剥除 pass 留下的类型注解文本旁路 */
+    nudoTypeText?: string;
     properties?: Array<{
         key?: AstParam;
         value?: AstParam;
@@ -1063,6 +1326,9 @@ declare function formalParamDisplayNames(formals: FormalParam[]): string[];
  * 签名展示名（C4.1 #64）：解构形参渲染为 `{ grade, findings }`，
  * 不落回求值占位 `_p0`——否则读签名的人以为没有契约。
  * 求值/内部键仍用 formalParamDisplayNames（`_p0`）。
+ *
+ * Bug 388：数组解构渲染为 `[ x, y ]`（与源码的解构形态一致）——
+ * 此前对象/数组解构一律渲染 `{ … }`，数组解构的签名面**看得出是对象**。
  */
 declare function formalParamSignatureNames(formals: FormalParam[]): string[];
 /** 侧车契约可绑定的参数名全集 */
@@ -1076,12 +1342,19 @@ declare function contractParamNameSet(formals: FormalParam[]): Set<string>;
  *   多段（field 为展示用点连接串）。平铺精确匹配必须先于任何点路径解析：
  *   源键 'a.b' 与路径 'a.b' 不可歧义——平铺胜。
  * - 未命中 → undefined（C4.5 param-mismatch）
+ *
+ * Bug 388 / 392：命中**数组解构**的顶层 bound 名时，契约面按**元素下标**
+ * 寻址（`[a, b]` 的 `a` 是下标 0 的元素），**不是**属性键 ⇒ 返回
+ * `fieldIndex`（下标）且**不给** `fieldPath`（fieldPath 是对象 slot 投影路径，
+ * 对数组无意义）。执法侧按 `fieldIndex` 投影实参的元素。
  */
 declare function locateContractParam(formals: FormalParam[], contractName: string): {
     index: number;
     field?: string;
     fieldPath?: string[];
     rest?: boolean;
+    /** 数组解构：契约命中的**元素下标**（对象解构无此字段） */
+    fieldIndex?: number;
 } | undefined;
 
 /**
@@ -1138,6 +1411,15 @@ type PolyFn = {
     }>;
     /** body 内对该形参的应用点（check/hover/dts 用） */
     hofSites?: HofSite[];
+    /**
+     * Bug 389：本次求值被 **env 门禁**挡下（源码声明了 `@nudo:env`，但那个 env
+     * **没解析出全局** ⇒ 无注入 ⇒ 函数体 fail-closed ⇒ 符号面 conf=opaque）。
+     *
+     * 门禁本身是对的（不注入就跑 ⇒ 宿主调用会假抛），但「因门禁而 opaque」**不
+     * 是**「路径没覆盖」⇒ 诊断层不得把它当成「已解释」（否则唯一能提示「推断
+     * 失败」的 `nudo:unknown-inference` 恰好在用户把 env 名写错时被吞掉）。
+     */
+    envGated?: boolean;
 };
 declare function extractFn(source: string, fnName: string, fileAst?: ReturnType<typeof parseSource>): {
     params: string[];
@@ -1174,8 +1456,17 @@ declare function listFunctionNames(source: string): string[];
 /**
  * 按 assume 集合构造实参：被 assume 的参数给带约束的符号，其余 any
  * （design-cli-semantics §2：入口无约束 = any，不是 unknown）。
+ *
+ * Bug 976（core 半）：被 assume 的形参的 pred 此前被**写死**成 `x > 0`——
+ * 用户写 `--assume 'x>-5'` 时，写死的界**更强**（`x>-5 ∧ x>0 ⇒ x>0`）⇒
+ * 引擎按 `x>0` 剪枝 ⇒ 观察面给出比用户声明**更窄**的结果（说谎）。
+ * 现在：**用户声明的界**（`bounds`：形参名 → Pred）直接落进形参的 pred；
+ * 没有声明界时**不写界**（不替用户发明一个更强的默认界）——Φ（CLI 侧）
+ * 是界的唯一来源。
  */
-declare function buildArgsFromAssume(source: string, fnName: string, assumeIds: Set<string>): Abs[];
+declare function buildArgsFromAssume(source: string, fnName: string, assumeIds: Set<string>, 
+/** 用户声明的界（形参名 → Pred）；缺省 = 不写界 */
+bounds?: ReadonlyMap<string, Pred>): Abs[];
 
 /**
  * CheckOptions — 从 check.ts 拆出的纯类型，打断 check ↔ check-memo/may-throw 环。
@@ -1204,9 +1495,14 @@ type CheckOptions = {
     /**
      * L2 入口 may-throw 执法档（design-cli-semantics §3）。
      * error（默认）| warning | off。仅作用于 export/default/CJS 入口函数。
+     *
+     * 同时是该 L2 族的**总闸**：模块装载期必抛（`nudo:module-throw`，顶层
+     * 无条件 `throw` ⇒ 模块未被分析）也按此档执法 / 静默 —— 零 FP 语料库
+     * （check-real-packages 的 `entryThrows: "off"`）因此不受新码影响。
      */
     entryThrows?: "error" | "warning" | "off";
-    /** L2 --ignore-throws：按 throws 类型名过滤；不吞 L1 */
+    /** L2 --ignore-throws：按 throws 类型名过滤；不吞 L1。
+     *  `nudo:module-throw` 同样消费：句法上判得出的抛出类型名被 ignore 即放行。 */
     ignoreThrows?: string[];
     /** 宿主已求值的依赖导出表（specifier → AbsModuleExports）；
      *  B 与解释路径共用——import/require 按表解析（CLI 经
@@ -1225,6 +1521,17 @@ type CheckOptions = {
      * 入口 may-throw（L2）不评估。调用点参数义务（scan）不受影响。
      */
     skips?: ReadonlyMap<string, Abs | null>;
+    /**
+     * 外部调用点证据（Bug 366）：`--from` 采集到的**跨文件**调用点记录。
+     *
+     * drift 判定的「今日域」证据此前**只**来自 checkSource 评估被检查文件
+     * 自身时产生的 AbsCallRecord ⇒ 调用点在别的文件里时，`--from` 写出的
+     * 生成段永远判不出陈旧（假绿）。本字段把跨文件证据接进同一条判定通道。
+     *
+     * 形状 = core 公共导出 AbsCallRecord（fnName = **被调方的导出名**；
+     * callLoc 省略 = 跨文件调用点在本文件内无位置）。
+     */
+    from?: readonly AbsCallRecord[];
 };
 
 /**
@@ -1277,7 +1584,7 @@ declare function checkSource(filePath: string, source: string, phi?: Phi, opts?:
  */
 
 type FnDirectiveScope = {
-    /** 绑定名：`f` / `C.m` / `default` / `<anonymous>` */
+    /** 绑定名：`f` / `C.m` / `C.static.m` / `default` / `<anonymous>` */
     name: string;
     node: Node;
     /** 该函数的前导注释块（comment.value 原文，文档序） */
@@ -1287,13 +1594,34 @@ type FnDirectiveScope = {
     /** 与 commentTexts 对齐的注释起始行号 */
     commentStartLines: number[];
     startLine: number;
+    /**
+     * 词法嵌套深度：0 = 顶层函数 / 类成员；每进入一层函数体 +1。
+     *
+     * Bug 424：scope 名**不唯一**（同名遮蔽函数 / 嵌套函数）⇒「按名 + 文档序
+     * 首个命中」会让**内层**同名函数抢走导出函数的注释块 ⇒ L2 门禁假绿 / 假红。
+     * ⇒ 按名查找取**最浅**（depth 最小）的那个。
+     */
+    depth?: number;
+    /** 宿主名（类名 / 外层函数名）；顶层为 undefined */
+    owner?: string;
 };
 /**
  * 全量 Function 站点：nested function、class method、object method 均可见。
  * 函数级指令绑「其前导注释块」；注释若带在非函数语句上则不绑（不留孤儿指令）。
  */
 declare function listFnDirectiveScopes(file: File): FnDirectiveScope[];
-/** 按绑定名找函数 scope（文档序第一个命中） */
+/**
+ * 按绑定名找函数 scope。
+ *
+ * Bug 424：scope 名**不保证唯一**（同名遮蔽函数 / 嵌套同名函数）⇒ 此前
+ * 「文档序**首个**命中」让**内层**同名函数抢走导出函数的注释块 ⇒
+ * 导出函数继承内层的 `@nudo:throws` ⇒ **L2 门禁假绿 / 假红**。
+ *
+ * ⇒ 同名时取**词法最浅**的那个（`depth` 最小：顶层函数 / 类成员 = 0，
+ * 每进入一层函数体 +1）；同深度取文档序第一个。
+ * 口径与**分析面**一致：顶层函数先登记（`generalize.ts` 的 env.fns），
+ * 嵌套同名者被跳过 ⇒ 分析面问到的「同名函数」就是最浅的那个。
+ */
 declare function findFnDirectiveScope(file: File, fnName: string): FnDirectiveScope | undefined;
 /**
  * 源文本级函数前导指令行（refine / throws / budget 的消费口）。
@@ -1303,6 +1631,11 @@ declare function fnDirectiveCommentLines(source: string, fnName: string): string
 /**
  * `@nudo:env` 载荷 → 命名 env token。只收 `\w+` 或 path-like
  * （拒绝 `node";` 这类截断捕获）。
+ *
+ * Bug 417：此前**只按 `,` 切分** ⇒ 空格分隔列表（`node web`）被切成**一个**
+ * token 后整条滤掉 ⇒ 零诊断地丢掉整条列表（env 未解析 ⇒ 全局 `unknown`）。
+ * ⇒ 逗号**与**空白两种分隔符都认；尾随的注释先剥掉（行尾注释是最自然的
+ * 写法：`/// @nudo:env node // 只需要 node`）。
  */
 declare function parseEnvPayload(payload: string): string[];
 type MockModuleRecord = {
@@ -1313,6 +1646,11 @@ type MockModuleRecord = {
 /**
  * `@nudo:mock-module "src" [ { a, b } ] from "path"` 载荷解析。
  * 名表 `{ … }` 可选；单源文法（parser / load-deps 共用）。
+ *
+ * Bug 415：两条正则原**硬编码双引号** ⇒ 单引号载荷（`'axios' from './m.js'`）
+ * 两条都不匹配 ⇒ 返回 `undefined` ⇒ 上游既不落诊断也不落记录 ⇒ 指令
+ * **静默蒸发**（mock 不生效、门禁照常绿）。⇒ 单引号与双引号**都认**
+ * （同一对引号必须自洽；source 与 path 的引号种类可不同）。
  */
 declare function parseMockModulePayload(payload: string): MockModuleRecord | undefined;
 type NudoImportRecord = {
@@ -1327,6 +1665,11 @@ type NudoImportRecord = {
  * default 等未识别形态返回 `malformed`（由消费方发诊断）。
  * import 绑定语义 local ← imported：`a as b` 两个名字都保留——只留 local
  * 会让查表用错名字（`exports[b]` miss，BUG-016）。
+ *
+ * Bug 422：**空载荷**（「标签命中但没写载荷」）此前返回 `undefined`
+ * （=「没有这条指令」）⇒ 畸形扫描器**永远看不到它** ⇒ 零诊断。
+ * ⇒ 空载荷是「这条指令写坏了」⇒ 返回 `malformed`，让既有的
+ * `nudo:contract-syntax` 通道自然接管。
  */
 declare function parseNudoImportPayload(payload: string): NudoImportRecord | "malformed-default" | "malformed" | undefined;
 declare function extractFileEnvNames(source: string): string[];
@@ -1336,14 +1679,22 @@ declare function extractNudoImportRecords(source: string): NudoImportRecord[];
 /**
  * 平衡括号摘取（字符串感知；`\` 不是转义——与 case 实参原样 slice 一致）。
  * 返回括号内文本；无平衡括号 → null。
+ *
+ * ⚠ Bug 420：**配平扫描**优先按 JS 转义语义走——串里的 `\"` / `\'` 不再提前
+ * 结束字符串 ⇒ 括号配平正确 ⇒ 含转义引号的 case 不再被**整条丢弃**，诊断也不再
+ * 错误归因为「unclosed argument list」。
+ * ⚠ 串**未闭合**（如 `"a\", -1`——非法 JS 串）时**回退**宽松口径（`\` 不是
+ * 转义）——Bug 1009 钉住的实参切分口径必须保持不变（两个面看到同一个世界）。
  */
 declare function extractBalancedParens(text: string, startIdx: number): string | null;
 type CaseTag = {
     name: string;
     /** 括号内实参原文（未清洗续行 `*`） */
     argsText: string;
-    /** `=> expected` 表达式原文（同行/续行 `=>`） */
+    /** `=> expected` 表达式原文（同行/续行 `=>`；已剥 `!! throws` 后缀与冗余括号） */
     expectedText?: string;
+    /** 期望**写了却抽不出**的原因（消费方发 nudo:directive-syntax；Bug 918） */
+    expectedIssue?: string;
     /** 标签在 comment.value 中的下标 */
     tagOffset: number;
 };
@@ -1363,6 +1714,11 @@ declare function scanContractSegments(lines: string[]): string[];
 /**
  * `@nudo:throws …` / case 行 `!! throws …`。
  * 返回 `*` = 申报任意；字符串 = 逗号/空白分隔的 kind 列表；undefined = 无申报。
+ *
+ * Bug 1033：`!! throws` 只在**指令位置**上采信（见 `scanCaseThrowsSuffixSpecs`）⇒
+ * 散文行 / case 名内部的同形文本不再被读成**函数级**申报 ⇒ L2 门禁照常执法。
+ *
+ * Bug 1118：case 后缀按**实参平衡终点**定位 ⇒ 多行实参写法的申报不再丢失。
  */
 declare function scanThrowsDecl(lines: string[]): string | undefined;
 /** `@nudo:budget forks=… calls=… depth=…` → 声明的维度 */
@@ -1379,18 +1735,28 @@ declare function scanBudgetDecl(lines: string[]): {
  * NudoConstraint 表达的域内。只覆盖可判定的标量子集：
  *
  *   - prim 门（prim 缺失或不匹配字面量类型 → false）
- *   - eq(self, lit v) 字面量等值（SameValue：含 undefined/NaN；与 leq 同口径）
+ *   - eq(self, lit v) 字面量等值（`===` + NaN 特例；见 literalSame）
  *   - gt/ge/lt/le 数值常数界（self op n）
  *   - 字符串长度界（length(self) op n，即 min/max/length 链）
  *   - int（整数性）
  *   - members（union）：任一成员满足即满足
  *
+ * **bigint**（族 11 片 S7 / Bug 915 延伸）：`lit(1n)` 这类 bigint 字面量契约
+ * 此前在本通道**判不了**（值域只放行 number / string / boolean / null /
+ * undefined）⇒ 字段位 / 元素位对 bigint 字面量实参**零诊断**（假绿），
+ * 而**标量实参位**（S6 修好）报违例 ⇒ 同一份契约两个位置两种裁决。
+ * 现在字面量值域含 bigint ⇒ 域隶属通道对 bigint 与其余标量同口径。
+ *
  * 对象 / 数组 / 函数域与不可判定的 pred 形态一律 false——保守不满足，
  * 对账侧宁可多报 domain-exceeds 也不放过。
  */
 
-/** 字面量 lv 是否落在约束 c 表达的域内（保守：判不了 → false）。 */
-declare function literalMeetsConstraint(lv: number | string | boolean | null | undefined, c: NudoConstraint, seen?: Set<object>): boolean;
+/** 字面量 lv 是否落在约束 c 表达的域内（保守：判不了 → false）。
+ *
+ *  值域 = `LiteralValue`（含 **bigint**；族 11 片 S7 / Bug 915 延伸）——
+ *  bigint 字面量实参此前不在值域内 ⇒ 域隶属通道对 bigint 恒不满足，
+ *  而调用点的守卫又不放行 bigint ⇒ 字段位 / 元素位对 bigint **零诊断**。 */
+declare function literalMeetsConstraint(lv: LiteralValue, c: NudoConstraint, seen?: Set<object>): boolean;
 
 /**
  * Abs → NudoConstraint 投影（Phase 1，interface 分层推导的生成侧半边）。
@@ -1432,4 +1798,4 @@ declare function absToConstraint(a: Abs, budget?: ProjectionBudget): NudoConstra
  */
 declare function joinThenProject(absList: Abs[]): NudoConstraint | undefined;
 
-export { Abs, type AbsAssignRecord, type AbsCallRecord, AbsModuleExports, AstEnv, type CaseTag, type CheckOptions, CheckReport, Confidence, EffectiveInterfaceOpts, type Environment, type ExtState, type FnAbs, type FnDirectiveScope, type FormalParam, type FormatOptions, HofCollectCtx, HofSite, type LeqResult, type MockHelper, type MockModuleRecord, NudoConstraint, type NudoImportRecord, OBJECT_PROTO_METHOD_NAMES, type ObjShape, Phi, type PolyFn, Pred, type PropFlags, RelSource, RunTranspiledOptions, Shape, type Slot, Term, type TypeParam, absShapeKey, absToConstraint, add, alphaOf, applyCallbackAbs, applyCallbackValue, asAbs, assignSourceSlots, beginCollectionFork, betaOf, bitandAbs, bitnotAbs, bitorAbs, bitxorAbs, buildArgsFromAssume, builtinCtorAbs, builtinCtorNameOf, callAbsMethod, canonicalArrayIndex, checkSource, clearCollectionTables, cmp, collectAbsFreeVars, collectionElementJoin, collectionExactLen, contractParamNameSet, createEnvironment, createHofCollectCtx, ctorArgDefinitelyInvalid, ctorNameOfRecv, currentPhi, definitelyNotNullishShape, describePhi, div, emptyEnv, endCollectionFork, errorBrandAbs, evalArrayStatic, evalBuiltinInstanceMethod, evalBuiltinNew, evalDateCtor, evalDateMethod, evalDateStatic, evalGlobalFn, evalJsonMethod, evalMathMethod, evalNamespaceCall, evalNumberStatic, evalObjectMethod, evalObjectProtoMethod, evalRegExpCtor, evalRegExpMethod, evalStringStatic, evalSymbolCtor, evictCheckSourceMemoForPaths, evictGeneralizeMemoForPaths, extStateOf, extractBalancedParens, extractFileEnvNames, extractFn, extractMockModuleRecords, extractNudoImportRecords, falseConstraint, findFnDirectiveScope, fnDirectiveCommentLines, fnOf, formalParamDisplayNames, formalParamSignatureNames, formalParamsFromNodes, formatAbs, formatAbsMultiline, formatShape, formatShapeSlot, generalizeAll, generalizeFromAst, getAbsProperty, getGeneralizeMemoSize, getPropFlags, getSlot, hostBuiltinCtorName, instantiateReturn, isErrorCtorName, isMapAbs, isNullProtoObj, isNullishLitAbs, isObj, isObjectProtoBrand, isRelFn, isSetAbs, isSymbolAbs, joinAbs, joinFunctions, joinObjects, joinThenProject, joinValues, leqAbs, listFnDirectiveScopes, listFunctionNames, literalMeetsConstraint, locateContractParam, looseEqAbs, makeArrayCtorAbs, makeMapAbs, makeSetAbs, makeSum, makeSymbolAbs, mapClearEntries, mapDeleteEntry, mapElementFallback, mapEntriesAbs, mapGetEntry, mapHasEntry, mapSetEntry, mapSizeAbs, mapValuesAbs, markExtState, markNullProtoObj, matchRelIdentLit, mergeCollectionArms, migrateInvariants, migrateNullProto, mock, mod, mul, negAbs, notAbs, noteCollectionWrite, objOf, objectProtoBrand, objectProtoMethodAbs, parseEnvPayload, parseMockModulePayload, parseNudoImportPayload, parseSource, popCollectionArm, popPhi, powAbs, projectFlatMapResult, promoteParamShape, propertyKeyOf, protoBrandAbs, protoOfRecv, pushCollectionArm, pushPhi, refineAbsForRelTrue, regexBrandAbsFrom, requiredFnArity, resetCheckSourceMemo, resetGeneralizeMemo, resetPhi, scanBudgetDecl, scanCaseArgSpans, scanCaseTags, scanContractSegments, scanThrowsDecl, setAddEntry, setApplyCallbackHost, setClearEntries, setDeleteEntry, setElementsAbs, setHasEntry, setPropFlags, setSizeAbs, shlAbs, shrAbs, snapshotAbs, spread, spy, strictEqAbs, stringOfSymbol, stripTypes, stub, sub, substAbs, substPredAbs, symbolDescriptionAbs, symbolIdOf, toNumberAbs, trueConstraint, tryMakeRegexAbs, tryPromoteDirectCall, tryPromoteForOfIteratee, tryPromoteHofCallback, tryPromoteReceiverAsArr, typeofAbs, undefAbs, ushrAbs, withPhiConstraint, withVar };
+export { Abs, type AbsAssignRecord, type AbsCallRecord, AbsModuleExports, AstEnv, type CaseTag, type CheckOptions, CheckReport, Confidence, EffectiveInterfaceOpts, type Environment, type ExtState, type FnAbs, type FnDirectiveScope, type FormalParam, type FormatOptions, HofCollectCtx, HofSite, type LeqResult, LiteralValue, type MockHelper, type MockModuleRecord, NudoConstraint, type NudoImportRecord, OBJECT_PROTO_METHOD_NAMES, type ObjShape, Phi, type PolyFn, Pred, type PropFlags, RelSource, RunTranspiledOptions, Shape, type Slot, Term, type TypeParam, absShapeKey, absToConstraint, add, alphaOf, applyCallbackAbs, applyCallbackValue, asAbs, assignSourceSlots, beginCollectionFork, betaOf, bitandAbs, bitnotAbs, bitorAbs, bitxorAbs, buildArgsFromAssume, builtinCtorAbs, builtinCtorNameOf, callAbsMethod, canonicalArrayIndex, checkSource, clearCollectionTables, cmp, collectAbsFreeVars, collectionElementJoin, collectionExactLen, contractParamNameSet, createEnvironment, createHofCollectCtx, ctorArgDefinitelyInvalid, ctorNameOfRecv, currentPhi, definitelyNotNullishShape, describePhi, div, emptyEnv, endCollectionFork, errorBrandAbs, evalArrayStatic, evalBuiltinInstanceMethod, evalBuiltinNew, evalDateCtor, evalDateMethod, evalDateStatic, evalGlobalFn, evalJsonMethod, evalMathMethod, evalNamespaceCall, evalNumberStatic, evalObjectMethod, evalObjectProtoMethod, evalRegExpCtor, evalRegExpMethod, evalStringStatic, evalSymbolCtor, evictCheckSourceMemoForPaths, evictGeneralizeMemoForPaths, extStateOf, extractBalancedParens, extractFileEnvNames, extractFn, extractMockModuleRecords, extractNudoImportRecords, falseConstraint, findFnDirectiveScope, fnDirectiveCommentLines, fnOf, formalParamDisplayNames, formalParamSignatureNames, formalParamsFromNodes, formatAbs, formatAbsMultiline, formatShape, formatShapeSlot, generalizeAll, generalizeFromAst, getAbsProperty, getGeneralizeMemoSize, getPropFlags, getSlot, hostBuiltinCtorName, instantiateReturn, isErrorCtorName, isMapAbs, isNullProtoObj, isNullishLitAbs, isObj, isObjectProtoBrand, isRelFn, isSetAbs, isSymbolAbs, joinAbs, joinFunctions, joinObjects, joinThenProject, joinValues, leqAbs, listFnDirectiveScopes, listFunctionNames, literalMeetsConstraint, locateContractParam, looseEqAbs, makeArrayCtorAbs, makeMapAbs, makeSetAbs, makeSum, makeSymbolAbs, mapClearEntries, mapDeleteEntry, mapElementFallback, mapEntriesAbs, mapGetEntry, mapHasEntry, mapSetEntry, mapSizeAbs, mapValuesAbs, markExtState, markNullProtoObj, matchRelIdentLit, mergeCollectionArms, migrateInvariants, migrateNullProto, mock, mod, mul, negAbs, notAbs, noteCollectionWrite, objOf, objectProtoBrand, objectProtoMethodAbs, parseEnvPayload, parseMockModulePayload, parseNudoImportPayload, parseSource, popCollectionArm, popPhi, powAbs, projectFlatMapResult, promoteParamShape, propertyKeyOf, protoBrandAbs, protoOfRecv, pushCollectionArm, pushPhi, refineAbsForRelTrue, regexBrandAbsFrom, requiredFnArity, resetCheckSourceMemo, resetGeneralizeMemo, resetPhi, scanBudgetDecl, scanCaseArgSpans, scanCaseTags, scanContractSegments, scanThrowsDecl, setAddEntry, setApplyCallbackHost, setClearEntries, setDeleteEntry, setElementsAbs, setHasEntry, setPropFlags, setSizeAbs, shlAbs, shrAbs, snapshotAbs, spread, spy, strictEqAbs, stringOfSymbol, stripTypes, stub, sub, substAbs, substPredAbs, symbolDescriptionAbs, symbolIdOf, toNumberAbs, trueConstraint, tryMakeRegexAbs, tryPromoteDirectCall, tryPromoteForOfIteratee, tryPromoteHofCallback, tryPromoteReceiverAsArr, typeofAbs, undefAbs, ushrAbs, withPhiConstraint, withVar };