@nudojs/core 0.3.0 → 0.4.0

package/dist/index-DgyudAkw.d.ts

@@ -0,0 +1,911 @@
+import { ImportDeclaration, File, Node, Expression } from '@babel/types';
+
+/** 项（Term）：抽象值的身份。字面量是项的特例。 */
+type LiteralValue = string | number | boolean | null | undefined;
+type Term = {
+    op: "lit";
+    value: LiteralValue;
+} | {
+    op: "var";
+    id: string;
+} | {
+    op: "app";
+    fn: string;
+    args: Term[];
+};
+declare const lit: (value: LiteralValue) => Term;
+declare const v: (id: string) => Term;
+declare const app: (fn: string, args: Term[]) => Term;
+declare function termEquals(a: Term, b: Term): boolean;
+declare function termToString(t: Term): string;
+/** 常量折叠 + 简单代数化简 */
+declare function simplifyTerm(t: Term): Term;
+
+/** 约束（Pred）：附着在项上的事实，可传播。 */
+
+type PrimName = "number" | "string" | "boolean" | "bigint" | "symbol";
+type Pred = {
+    op: "true";
+} | {
+    op: "false";
+} | {
+    op: "eq";
+    a: Term;
+    b: Term;
+} | {
+    op: "ne";
+    a: Term;
+    b: Term;
+} | {
+    op: "lt";
+    a: Term;
+    b: Term;
+} | {
+    op: "le";
+    a: Term;
+    b: Term;
+} | {
+    op: "gt";
+    a: Term;
+    b: Term;
+} | {
+    op: "ge";
+    a: Term;
+    b: Term;
+} | {
+    op: "and";
+    args: Pred[];
+} | {
+    op: "or";
+    args: Pred[];
+} | {
+    op: "not";
+    arg: Pred;
+} | {
+    op: "typeof";
+    t: Term;
+    type: PrimName;
+};
+declare const pTrue: Pred;
+declare const pFalse: Pred;
+declare const eq: (a: Term, b: Term) => Pred;
+declare const ne: (a: Term, b: Term) => Pred;
+declare const lt: (a: Term, b: Term) => Pred;
+declare const le: (a: Term, b: Term) => Pred;
+declare const gt: (a: Term, b: Term) => Pred;
+declare const ge: (a: Term, b: Term) => Pred;
+declare const ptypeof: (t: Term, type: PrimName) => Pred;
+declare function and(...preds: Pred[]): Pred;
+declare function or(...preds: Pred[]): Pred;
+declare function not(p: Pred): Pred;
+declare function predEquals(a: Pred, b: Pred): boolean;
+declare function predToString(p: Pred): string;
+/** 把 pred 里的 Term 用 subst 替换（用于 bound 变量重命名等） */
+declare function substPred(p: Pred, subst: (t: Term) => Term): Pred;
+/** 收集 pred 中出现的自由变量 */
+declare function predVars(p: Pred): Set<string>;
+/** 约束环境 Φ：Pred 的合取 */
+type Phi = Pred;
+declare const emptyPhi: Phi;
+declare const phiAnd: typeof and;
+/** 简单蕴含：在区间/字面量可判定范围内判断 Φ ⊢ pred */
+declare function implies(phi: Phi, pred: Pred): boolean;
+/** 便捷：数字下界 */
+declare function gtNum(term: Term, n: number): Pred;
+declare function geNum(term: Term, n: number): Pred;
+declare function ltNum(term: Term, n: number): Pred;
+declare function leNum(term: Term, n: number): Pred;
+
+/** 抽象值 Abs = 形状 × 项 × 约束 × 置信度 */
+
+type Confidence = "exact" | "path" | "widened" | "mock" | "partial" | "opaque";
+type Shape = {
+    k: "never";
+}
+/**
+ * any：JS 里可以是任意值（无约束参数）。
+ * 运算按真实 JS 语义取并集，不是「分析失败」。
+ */
+ | {
+    k: "any";
+}
+/** unknown：分析拿不到信息（求值失败/泄漏），不是「任意值」 */
+ | {
+    k: "unknown";
+} | {
+    k: "prim";
+    type: PrimName;
+} | {
+    k: "obj";
+    slots: Record<string, {
+        value: Abs;
+        optional?: boolean;
+        readonly?: boolean;
+    }>;
+    index?: {
+        key: Abs;
+        value: Abs;
+    };
+    open?: boolean;
+} | {
+    k: "arr";
+    element: Abs;
+} | {
+    k: "tuple";
+    elements: Abs[];
+    rest?: Abs;
+} | {
+    k: "fn";
+    params: string[];
+    name?: string;
+    paramTypes?: Abs[];
+    returnType?: Abs;
+} | {
+    k: "brand";
+    name: string;
+    shape: Abs;
+} | {
+    k: "eff";
+    eff: "promise" | "generator";
+    inner: Abs;
+} | {
+    k: "sum";
+    members: Abs[];
+};
+type Abs = {
+    shape: Shape;
+    term?: Term;
+    pred?: Pred;
+    conf: Confidence;
+};
+declare const never: Abs;
+/** 分析无信息 */
+declare const unknown: Abs;
+/** 带 term 的 any（generalize type-var） */
+declare function anyVar(id: string, conf?: Confidence): Abs;
+declare function num(): Abs;
+declare function str(): Abs;
+declare function bool(): Abs;
+declare function numLit(value: number): Abs;
+declare function strLit(value: string): Abs;
+declare function boolLit(value: boolean): Abs;
+/** 带项的符号数，例如参数 x */
+declare function numVar(id: string, pred?: Pred, conf?: Confidence): Abs;
+declare function obj(slots: Record<string, {
+    value: Abs;
+    optional?: boolean;
+}>): Abs;
+declare function confJoin(a: Confidence, b: Confidence): Confidence;
+declare function absToString(a: Abs): string;
+declare function shapeToString(s: Shape): string;
+/** 从 term 反推 prim shape */
+declare function shapeOfTerm(t: Term): Shape;
+/** 构造带项的结果 Abs；pred 相对 term */
+declare function abs(shape: Shape, term: Term | undefined, pred: Pred | undefined, conf: Confidence): Abs;
+declare function isNumPrim(a: Abs): boolean;
+declare function isStrPrim(a: Abs): boolean;
+/** 置信度：字面量全确定 */
+declare function isExactLit(a: Abs): boolean;
+declare function litValue(a: Abs): LiteralValue | undefined;
+
+/**
+ * 项（Term）防爆炸：深度/宽度阈值 → leak 为新鲜 var + 等式约束。
+ */
+
+type LeakBudget = {
+    maxDepth: number;
+    maxNodes: number;
+};
+declare const defaultLeakBudget: LeakBudget;
+declare function termDepth(t: Term): number;
+declare function termNodes(t: Term): number;
+declare function exceedsBudget(t: Term, budget?: LeakBudget): boolean;
+declare function resetLeakCounter(): void;
+/**
+ * 若项超预算，替换为新鲜变量，并返回附加等式 pred：fresh = originalTerm。
+ * 未超预算则原样返回。
+ */
+declare function maybeLeak(a: Abs, budget?: LeakBudget, label?: string): Abs;
+/**
+ * 批量：在算术结果上应用 leak。
+ */
+declare function leakIfNeeded(a: Abs, budget?: LeakBudget, label?: string): Abs;
+
+/**
+ * HOF 关系 Abs：无 body 的外延关系（paramTypes → returnType）的判定、
+ * α 替换与应用。类型变量仍是 term var；关系仍是 fn 形状上的外延槽。
+ */
+
+/**
+ * 关系来源标记：P4 豁免与 diagnostics 依赖它，禁止隐式猜。
+ * - promote：使用驱动提升（generalize symbolic / instantiate 局部）
+ * - refine：@nudo:refine 契约
+ * - relationFn：harvest/mock/测试直接写入 fnRels 时的预留来源（P4 error 路径）
+ */
+type RelSource = "promote" | "refine" | "relationFn";
+type HofSite = {
+    /** 形参名（函数形参） */
+    param: string;
+    /** 输入侧 term：实参的 term（element 的 var/lit/app）；map 1 个、reduce 2 个 */
+    argTerms: Term[];
+    /** 输出侧：归纳出的返回 Abs */
+    result: Abs;
+    /** 源位置，便于 diagnostics */
+    loc?: {
+        line: number;
+        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;
+    }>;
+};
+declare function createHofCollectCtx(paramNames: ReadonlySet<string>, alphaIds: Iterable<string>): HofCollectCtx;
+/**
+ * 仅当 term 是 var 且 id ∈ alphaIds（本次 typeParams）时复用；否则 fresh α。
+ * 绝不把调用点具体值/字面量冻进关系。
+ */
+declare function alphaOf(absOrTerm: Abs | Term | undefined, ctx: HofCollectCtx): Term;
+/** 共享输出变量 B:${param}（§5.1 P2 钉死） */
+declare function betaOf(param: string): Term;
+/**
+ * 提升写入载体：替换 env.vars map 项，禁止 mutate 共享 Abs。
+ * arrival-first：已有 fn/arr 形状 → 拒绝新观测。
+ * 返回是否真正写入。
+ */
+declare function promoteParamShape(env: AstEnv, param: string, promotedShape: Shape, opts?: {
+    loc?: {
+        line: number;
+        column: number;
+    };
+    recordSite?: boolean;
+}): boolean;
+/**
+ * 挂载点①：方法派发 miss。receiver 是形参 Identifier 且 shape 为 any/未知，
+ * 方法名为 filter/map/reduce/flatMap → 提升为 arr(自身 var)。
+ */
+declare function tryPromoteReceiverAsArr(env: AstEnv, receiverName: string, method: string, loc?: {
+    line: number;
+    column: number;
+}): Abs | undefined;
+/**
+ * for-of 迭代对象提升（applyEach 型）：`for (const x of items)`，
+ * items 为形参且仍是 any/unknown → arr(自身 var)。不依赖方法名。
+ */
+declare function tryPromoteForOfIteratee(env: AstEnv, iterateeName: string, loc?: {
+    line: number;
+    column: number;
+}): Abs | undefined;
+/**
+ * 挂载点②：CallExpression callee = 形参 Identifier 直接调用 p(x) / p(a,b)。
+ * 提升为 fn(paramTypes=[αOf(args)], returnType=B:param)。
+ */
+declare function tryPromoteDirectCall(env: AstEnv, calleeName: string, args: Abs[], loc?: {
+    line: number;
+    column: number;
+}): Abs | undefined;
+/**
+ * 挂载点③：HOF 回调实参。回调是 Identifier ∈ paramNames 且尚未有 fn 形状。
+ * 按方法名提升：map/flatMap → fn([αOf(el)], B:param)；filter → fn([αOf(el)], bool)；
+ * reduce → fn([αOf(init), αOf(el)], B:param)。
+ */
+declare function tryPromoteHofCallback(env: AstEnv, cbName: string, method: string, argAbses: Abs[], loc?: {
+    line: number;
+    column: number;
+}): Abs | undefined;
+/** deep-ish copy for snapshot（新对象，不是 env.vars 同一引用） */
+declare function snapshotAbs(a: Abs): Abs;
+/**
+ * 「有可用外延签名」判定：唯一权威定义。
+ *
+ * 名实说明：isRelFn **不要求** term 是 var。完全单态的具体签名
+ * （paramTypes=[number], returnType=string）同样满足——map 有槽就用。
+ * 多态（term=var）只是其中一种形态；名字里的 Rel 指「关系槽可用」。
+ *
+ * 收紧条件——仅有 returnType 而 paramTypes 与 arity 不对齐时，不算 rel，
+ * 防止半截签名在 map 里冒充关系。
+ */
+declare function isRelFn(a: Abs | undefined | null): boolean;
+/**
+ * pred 三条规则：
+ * 1. var ∈ map + 实参有 term → 换 term，可归约则归约，否则残余保留
+ * 2. var ∈ map + 实参无 term → pred → true（conf 由调用方降级）
+ * 3. var ∉ map（自由 α）→ 原样保留
+ */
+declare function substPredAbs(p: Pred, map: ReadonlyMap<string, Abs>): {
+    pred: Pred;
+    dropped: boolean;
+};
+/**
+ * α 替换：map 的 key 是 term var id，value 是替换 Abs。
+ * var ∉ map 原样保留（含自由 α 上的 term/pred）。
+ */
+declare function substAbs(a: Abs, map: ReadonlyMap<string, Abs>): Abs;
+/**
+ * relation-only / isRelFn 的应用：按 paramTypes 做 α 替换得到 returnType。
+ * impl.relation 槽优先于 shape.returnType。重复 α 先绑定保留。
+ */
+declare function instantiateReturn(fn: Abs, args: Abs[]): Abs;
+/**
+ * 回调统一入口（单点定义）。A–F + sum：
+ * A Node inline | B apply | C body | D relation | E isRelFn | F unknown
+ *
+ * 实现委托 ast-eval 的 applyAbsFn（已含 sum / D / E / body 优先）。
+ * Identifier 解析层：env.vars 有 Abs → B–E；env.fns 有 → callFunction；否则 unknown。
+ *
+ * 为避免 hof ↔ ast-eval 循环依赖，本函数由宿主在运行时绑定。
+ *
+ * 依赖说明：宿主在 `ast-eval.ts` 模块加载时注册（副作用）。
+ * 只 import hof.ts 而未加载 ast-eval 时，fallback 仅认 relation/isRelFn。
+ * 与 §5.1 的「禁止全局 collector」不同——这里是无状态委托钩子，不是 run 局部状态。
+ */
+type ApplyCallbackHost = (cb: Abs | {
+    type: string;
+}, args: Abs[], env: unknown, phi: unknown, budget: unknown) => Abs;
+/**
+ * ast-eval 模块加载时注册（副作用）。
+ * 必须经 `ast-eval.ts`（或其依赖方：exec/call、exec/class、generalize）加载，
+ * 才能启用 Identifier/env.fns/inline body 路径；只 import hof.ts 时 fallback
+ * 仅认 relation/isRelFn。勿在多份 ast-eval 实例下各写各的——双包/双副本会覆盖。
+ */
+declare function setApplyCallbackHost(fn: ApplyCallbackHost): void;
+declare function applyCallbackAbs(cb: Abs | {
+    type: string;
+}, args: Abs[], env: unknown, phi: unknown, budget: unknown): Abs;
+/** undefined 值的统一 Abs 表示（forEach/find 等） */
+declare function undefAbs(): Abs;
+/**
+ * map 元素投影：body 在符号实参上跑出 unknown 时，
+ * 用 shape.returnType 槽，conf 由调用方按 path/partial 处理。
+ * rel 回调不会走到这里（instantiateReturn 已给出结果）。
+ */
+declare function mapElementFallback(cbAbs: Abs | undefined, elem: Abs, out: Abs): Abs;
+/**
+ * flatMap 统一结果：展开后的元素 join 成 arr(γ)。
+ * JS flatMap 永远返回 Array；双路径共用此投影，禁止一边 tuple 一边 arr。
+ * 同 term 元素 first-wins（joinAbs 会丢 β 身份，见 design §5.1）。
+ */
+declare function projectFlatMapResult(arrConf: Confidence, mapped: Abs[]): Abs;
+/** 从 map/filter/reduce 回调实参里取出 Abs（Identifier 已绑定或直接 Abs） */
+declare function asAbs(v: unknown): Abs | undefined;
+
+/**
+ * Abs 模块面（无 fs）：import 绑定 + export 收集。
+ * 解析路径/读文件在 host；core 只吃「specifier → 导出表」。
+ */
+
+type AbsModuleExports = {
+    named: Record<string, Abs>;
+    default?: Abs;
+};
+/** 把 import 说明符绑定进 env（宿主已求值依赖） */
+declare function bindImports(node: ImportDeclaration, env: AstEnv, modules: Record<string, AbsModuleExports>): void;
+/**
+ * 从已求值 env + AST 收集 ESM 导出。
+ * 支持：export function/const、export { a, b as c }、export default（具名）、
+ * 以及带 source 的 re-export（`export { a } from "mod"` / `export * from "mod"`——
+ * 需 host 传入已求值 modules）。
+ */
+declare function collectAbsExports(file: File, env: AstEnv, modules?: Record<string, AbsModuleExports>): AbsModuleExports;
+
+/**
+ * Babel AST 抽象求值：把「类型即计算」接到真实 JS 源码。
+ * 支持表达式、函数声明/箭头、return、if、const/let、块作用域、类、循环。
+ */
+
+type AstEnv = {
+    vars: Map<string, Abs>;
+    /** 用户函数：name → { params, body } */
+    fns: Map<string, {
+        params: string[];
+        body: Node;
+        async?: boolean;
+        kind?: string;
+    }>;
+    /** class 表（旁路，withVar 必须保留） */
+    classes?: Map<string, unknown>;
+    /** 当前正在求值的方法所属类名（super.x() 从它的父类派发） */
+    currentOwner?: string;
+    /** P2：generalize symbolic 跑的 HOF collector（run 局部，不进 Φ） */
+    hofCollect?: HofCollectCtx;
+};
+declare function emptyEnv(): AstEnv;
+declare function withVar(env: AstEnv, name: string, value: Abs): AstEnv;
+type EvalOptions = {
+    phi?: Phi;
+    budget?: LeakBudget;
+    /** 预解析 AST（check 等批量场景避免重复 parse） */
+    file?: File;
+    /** host 已求值的相对依赖导出表 */
+    modules?: Record<string, AbsModuleExports>;
+};
+declare const MAX_CALL_DEPTH = 64;
+declare const MAX_TOTAL_CALLS = 200000;
+/** 宿主入口（evalProgramAbs / analyzeFn / check）前重置 */
+declare function resetAbsCallBudget(): void;
+/** 记录被截断的递归（service 可映射为 nudo:recursion-truncated） */
+declare function setAbsTruncationCollector(collector: ((fnLabel: string) => void) | null): void;
+/** Abs 域调用记录（自包含程序可不经 TypeValue evaluator） */
+type AbsCallRecord = {
+    fnName: string;
+    args: Abs[];
+    result: Abs;
+    callLoc?: {
+        line: number;
+        column: number;
+    };
+    threw?: boolean;
+};
+declare function setAbsCallCollector(collector: ((r: AbsCallRecord) => void) | null): void;
+declare function setAbsNodeCollector(collector: ((node: Node, value: Abs) => void) | null): void;
+/** 赋值记录：结构可赋值检查用 */
+type AbsAssignRecord = {
+    name: string;
+    prev?: Abs;
+    next: Abs;
+    line?: number;
+    column?: number;
+};
+declare function setAbsAssignCollector(collector: ((r: AbsAssignRecord) => void) | null): void;
+type EvalResult = {
+    value: Abs;
+    phi: Phi;
+    env: AstEnv;
+    /** 函数已通过 return 跳出，块内后续语句不可达 */
+    returned?: boolean;
+    /** break 跳出最近循环 */
+    brk?: boolean;
+    /** continue 进入下一轮 */
+    cont?: boolean;
+    /** throw 了 value（未捕获时向上传播） */
+    threw?: boolean;
+    /**
+     * if 无 else 且 consequent 已 return/throw：真分支已产出 value，
+     * 假分支 fall-through 仍可能走后续语句。evalBlock 需与后续结果 join。
+     */
+    partialReturn?: boolean;
+};
+/**
+ * 分析一段 JS 源码。
+ * 若含多个顶层函数声明，先注册全部，再对 `main` 或最后一个有调用的函数求值。
+ * 更简单：提供 `analyzeFunction(source, fnName, args)`。
+ */
+declare function evalSource(source: string, entry: {
+    fn: string;
+    args: Abs[];
+}, opts?: EvalOptions): EvalResult;
+declare function callFunction(env: AstEnv, name: string, args: Abs[], phi?: Phi, budget?: LeakBudget): Abs;
+/**
+ * 在 this=receiver 下求值方法体。
+ * constructor 无显式 return 时返回更新后的 this（字段写入已并入 env）。
+ */
+declare function evalMethodBody(method: {
+    params: string[];
+    body: Node;
+    async?: boolean;
+    kind?: string;
+}, args: Abs[], thisVal: Abs, env: AstEnv, phi?: Phi, budget?: LeakBudget, 
+/** 方法定义所在类名（用于 super 派发） */
+ownerClass?: string): Abs;
+/** 对外入口：求值并记入节点表（Map<Node, Abs> 由 collector 消费） */
+declare function evalNode(node: Node, env: AstEnv, phi: Phi, budget: LeakBudget): EvalResult;
+/**
+ * 应用 Abs 一等函数。统一顺序：apply → body → relation → isRelFn。
+ * 调用门须扩为 `getFnImpl || isRelFn`，否则 E 路径永远进不来。
+ */
+declare function applyAbsFn(fnVal: Abs, args: Abs[], env: AstEnv, phi: Phi, budget: LeakBudget): Abs;
+/**
+ * 从源码分析指定函数在给定实参下的抽象结果。
+ *
+ * @example
+ * analyzeFn(`
+ *   const add = (a, b) => a + b;
+ *   function scale(x) { return add(x, 1); }
+ * `, "scale", [numVar("x", gtNum(v("x"), 0))], gtNum(v("x"), 0))
+ */
+declare function analyzeFn(source: string, fnName: string, args: Abs[], phi?: Phi, budget?: LeakBudget, file?: File, modules?: Record<string, AbsModuleExports>): Abs;
+/**
+ * 程序级 Abs 求值：注册全部顶层函数/class，再顺序执行语句。
+ * 返回最终 env（vars 含导出绑定）。TypeValue 仅在调用方 bridge 时出现。
+ *
+ * seedVars / seedFns：host 注入（@nudo:mock 等）在求值前绑定。
+ * modules：host 已求值的依赖导出表（specifier → AbsModuleExports）。
+ */
+declare function evalProgramAbs(source: string, opts?: EvalOptions & {
+    seedVars?: Record<string, Abs>;
+    seedFns?: Record<string, {
+        params: string[];
+        body: Node;
+        async?: boolean;
+    }>;
+    modules?: Record<string, AbsModuleExports>;
+}): {
+    env: AstEnv;
+    last: Abs;
+    phi: Phi;
+};
+/**
+ * 收集整文件的节点 → Abs 表（LSP 无损信息源）。
+ * 自包含源码上一次 evalProgramAbs 即可；失败返回空表。
+ */
+declare function collectAbsNodeTypes(source: string, opts?: EvalOptions & {
+    seedVars?: Record<string, Abs>;
+    seedFns?: Record<string, {
+        params: string[];
+        body: Node;
+        async?: boolean;
+    }>;
+}): Map<Node, Abs>;
+/** 按 loc 找最紧的节点 Abs（hover 用） */
+declare function findAbsAtPosition(nodeTypes: Map<Node, Abs>, line: number, column: number): Abs | undefined;
+
+/**
+ * B 路径运行时：transpile 后的程序在 Node 上执行时，值就是 Abs。
+ * 与 AST 解释器语义同构；TypeValue 不再是求值载体。
+ */
+
+declare function currentExecPhi(): Phi;
+declare function withExecPhi<T>(p: Phi, body: () => T): T;
+declare function $add(a: Abs, b: Abs): Abs;
+declare function $sub(a: Abs, b: Abs): Abs;
+declare function $mul(a: Abs, b: Abs): Abs;
+declare function $div(a: Abs, b: Abs): Abs;
+declare function $mod(a: Abs, b: Abs): Abs;
+declare function $neg(a: Abs): Abs;
+declare function $typeof(a: Abs): Abs;
+declare function $not(a: Abs): Abs;
+declare function $eq(a: Abs, b: Abs): Abs;
+declare function $ne(a: Abs, b: Abs): Abs;
+declare function $lt(a: Abs, b: Abs): Abs;
+declare function $le(a: Abs, b: Abs): Abs;
+declare function $gt(a: Abs, b: Abs): Abs;
+declare function $ge(a: Abs, b: Abs): Abs;
+declare function $join(a: Abs, b: Abs): Abs;
+/**
+ * transpile 泄漏的 JS 函数值 → 一等 fn Abs。
+ * B 路径把函数声明/表达式编译成真实 JS 函数；它们流进对象槽、
+ * 元组、join 等 Abs 结构时不能裸存——下游（bridge/leq/join）读 `.shape`。
+ * 参数名无法从运行时函数恢复（用 fn.length → argN，与 analyzer 的
+ * extractParamNames 回退口径一致）；带真实参数名走 $fnVal（transpile 侧）。
+ */
+declare function asAbsVal(v: unknown): Abs;
+/** 函数表达式 → 一等 fn Abs（transpile 侧带真实参数名；异步 body 包 $async） */
+declare function $fnVal(params: string[], impl: (...args: Abs[]) => Abs): Abs;
+/** 字面量 → Abs（transpile 侧数字/字符串/布尔/null/undefined） */
+declare function $lit(v: unknown): Abs;
+/** JS 真值：字面量按 Boolean(v)；对象形恒真；不可判 → undefined */
+declare function litTruth(a: Abs): boolean | undefined;
+declare function isDefinitelyTrue(a: Abs): boolean;
+declare function isDefinitelyFalse(a: Abs): boolean;
+/**
+ * if：两侧都探索（抽象条件），具体条件短路。
+ */
+declare function $fork(test: Abs, consequent: () => Abs, alternate?: () => Abs): Abs;
+declare const DEFAULT_MAX_LOOP_ITERS = 8;
+/**
+ * for 的惰性展开：生成器只负责「按上限吐状态」。
+ * 抽象条件无法诚实终止——消费者必须自带 maxIters。
+ */
+declare function $forIter(init: Abs, test: (s: Abs) => Abs, step: (s: Abs) => Abs, body: (s: Abs) => Abs, maxIters?: number): Generator<{
+    state: Abs;
+    test: Abs;
+    afterBody: Abs;
+}, void, void>;
+/**
+ * 有界 for：unroll ≤ maxIters，每步「可能退出」的态 join；
+ * 相邻态 leq 视为不动点提前停。
+ */
+declare function $for(init: Abs, test: (s: Abs) => Abs, step: (s: Abs) => Abs, body: (s: Abs) => Abs, maxIters?: number): Abs;
+/** 数组字面量 → Abs tuple（长度已知） */
+declare function $arr(items: Abs[]): Abs;
+/** 下标读 a[i]；字面量 i 走 tuple 精确投影，否则并所有元素；string[i] → 单字符 */
+declare function $idx(a: Abs, i: Abs): Abs;
+/** 下标写 a[i]=v → 新 tuple（越界写按 JS 语义增长，空洞为 undefined） */
+declare function $idxSet(a: Abs, i: Abs, value: Abs): Abs;
+/** 数组/字符串长度 */
+declare function $len(a: Abs): Abs;
+/** 对象字面量 → Abs obj */
+declare function $obj(slots: Record<string, Abs>): Abs;
+/** 对象展开 { ...a, b } */
+declare function $spread(a: Abs, b: Abs): Abs;
+/** 数组连接 [...a, ...b] / [...a, x] */
+declare function $concat(a: Abs, b: Abs): Abs;
+/** 元素列表（tuple 展开；arr 抽象） */
+declare function $elems(a: Abs): Abs[];
+/**
+ * for-of：对 iterable 每个元素跑 body；有界展开。
+ * body(item, i) 可返回 void；状态由外部 JS 变量承接。
+ */
+declare function $forOf(iterable: Abs, body: (item: Abs, index: Abs) => void, maxIters?: number): void;
+/**
+ * 命名空间身份表：transpile 后 `Math.max(0, x)` 的接收者是宿主 JS 全局对象
+ * （非 Abs）。按对象身份识别命名空间，路由到 Abs builtin 表。
+ */
+declare function namespaceNameOf(v: unknown): string | undefined;
+/** 正则字面量 → RegExp brand（source/flags 进 slots，供 exec/test 精确执行） */
+declare function $regex(pattern: string, flags?: string): Abs;
+/** 成员读：obj.slots[key]；缺失 → undefined 字面量；brand 解包内层 */
+declare function $get(o: Abs, key: string, opts?: {
+    silent?: boolean;
+}): Abs;
+/** 成员写：返回新 obj/brand（不可变更新） */
+declare function $set(o: Abs, key: string, value: Abs): Abs;
+/**
+ * 有界 while：state 线程穿 test/step（与 $for 同折叠语义）。
+ * 抽象条件无法诚实终止——必须 maxIters。
+ */
+declare function $while(init: Abs, test: (s: Abs) => Abs, step: (s: Abs) => Abs, maxIters?: number): Abs;
+/**
+ * 顺序 while（具体/可变闭包）：body 内对 JS 变量赋值。
+ * 适合 transpile `let i; while (…) { i = … }`；抽象条件仍靠预算截断，
+ * 不保证 exit-join 健全——健全路径用 $while/$for + 状态对象。
+ */
+declare function $whileSeq(test: () => Abs, body: () => void, maxIters?: number): void;
+/** B 路径 throw 载荷：携带 Abs 抛出值 */
+declare class NudoThrow extends Error {
+    readonly absValue: Abs;
+    constructor(absValue: Abs);
+}
+/** transpile `throw x` → `$throw(x)` */
+declare function $throw(v: Abs): never;
+declare function isNudoThrow(e: unknown): e is NudoThrow;
+/** catch 参数：从 NudoThrow 取出 Abs，否则 unknown */
+declare function $catchVal(e: unknown): Abs;
+/**
+ * async 函数体包进 thunk，返回值经 wrapPromise。
+ */
+declare function $async(thunk: () => Abs): Abs;
+/** await → 解包 eff("promise") */
+declare function $await(v: Abs): Abs;
+/** async 直接 return 的 coerce */
+declare function $asyncReturn(v: Abs): Abs;
+/** function* 体：收集所有 yield 值为 tuple Abs */
+declare function $gen(body: () => void): Abs;
+/** yield v：压入当前生成器收集器；表达式值用 unknown */
+declare function $yield(v: Abs): Abs;
+/**
+ * switch：具体 disc 选中匹配 case；抽象 disc 并所有分支。
+ */
+declare function $switch(disc: Abs, cases: Array<{
+    test: Abs;
+    run: () => Abs;
+}>, dflt?: () => Abs): Abs;
+
+/**
+ * B 路径 transpile：JS AST → 可在 Node 上执行的抽象值程序（源码字符串）。
+ * 运算符改为 $add/$sub/…；if 改为 $fork；for 改为 $for。
+ * 值类型是 Abs；副作用与模块仍由 host mock/注入。
+ */
+
+type TranspileOptions = {
+    /** 运行时 import 说明符 */
+    runtimeImport?: string;
+    maxLoopIters?: number;
+    /** 方法体内 this 的绑定名（transpile class 时注入） */
+    thisParam?: string;
+    /** 当前类名（super 派发用） */
+    className?: string;
+    /** 原始源码（@nudo:replace 按节点文本匹配） */
+    source?: string;
+    /** 替换表：归一化目标文本 → 注入变量名；可选语句范围 */
+    replacements?: Array<{
+        target: string;
+        varName: string;
+        /** 仅该语句范围内生效（1-based 行） */
+        stmtStart?: number;
+        stmtEnd?: number;
+    }>;
+    /** @nudo:as：覆盖紧随语句的 init / return */
+    asOverrides?: Array<{
+        varName: string;
+        stmtStart: number;
+        stmtEnd: number;
+    }>;
+};
+declare function transpileSource(source: string, opts?: TranspileOptions): string;
+declare function transpileFile(file: File, opts?: TranspileOptions): string;
+declare function transpileExpression(expr: Expression, opts?: TranspileOptions): string;
+/** 解析 + transpile */
+declare function transpile(source: string, opts?: TranspileOptions): string;
+
+/**
+ * 调用 Abs 一等函数（absFunction impl）或 mock apply。
+ * 供 B 路径 import 绑定包装：`(...args) => $call(absFn, args)`。
+ *
+ * 统一顺序：apply → body → relation → isRelFn（委托 applyAbsFn）。
+ * 行为对齐说明（与旧 $call 的差异，均属刻意）：
+ * 1. 带 body 的函数也进 call-budget（与 ast-eval 同轨；递归会 truncated 而非爆栈）
+ * 2. body 抛错 → never（applyAbsFn 内恢复，不返回中间值）
+ * 3. 无 impl 时 isRelFn 可走 E 路径（旧版恒 unknown）
+ */
+
+declare function $call(fn: Abs, args: Abs[]): Abs;
+
+/**
+ * B class 规格表（无 call/ast-eval 依赖，避免循环）。
+ * Abs-eval registerClassDecl 与 transpile $class 共用。
+ */
+
+type BClassSpec = {
+    name: string;
+    superName?: string;
+    ctor?: (thisVal: Abs, ...args: Abs[]) => Abs;
+    methods?: Record<string, (thisVal: Abs, ...args: Abs[]) => Abs>;
+    staticMethods?: Record<string, (...args: Abs[]) => Abs>;
+    statics?: Record<string, Abs>;
+};
+declare function registerBClass(spec: BClassSpec): void;
+declare function getBClass(name: string): BClassSpec | undefined;
+declare function clearBClasses(): void;
+
+/**
+ * B 路径 class：brand 实例 + ctor/method 闭包 + 继承链。
+ * 方法内 this 由 transpile 改写为 thisVal 参数。
+ */
+
+/** 定义类 → 可 new 的 Abs（brand 标记；静态字段挂在 slots） */
+declare function $class(name: string, spec: Omit<BClassSpec, "name"> & {
+    extends?: string;
+}): Abs;
+/** new C(...) → 空 brand 实例 + ctor 写字段；非类构造走 impl/$call */
+declare function $new(cls: Abs | ((...a: unknown[]) => unknown), args: Abs[]): Abs;
+/**
+ * super(...)：父类构造写入字段（this 保持子类 brand）。
+ * transpile: super(a,b) → __this = $super(__this, "Child", [a,b])
+ */
+declare function $super(thisVal: Abs, childName: string, args: Abs[]): Abs;
+/** 实例方法调用：沿继承链；类 Abs 上回落 staticMethods；obj 上回落属性函数 */
+declare function $invoke(thisVal: Abs, method: string, args: Abs[], loc?: [number, number]): Abs;
+/** super.method()：从父类起找（跳过自身覆盖） */
+declare function $invokeSuper(thisVal: Abs, childName: string, method: string, args: Abs[]): Abs;
+declare function $thisGet(thisVal: Abs, key: string): Abs;
+declare function $thisSet(thisVal: Abs, key: string, value: Abs): Abs;
+/** 解构默认值：undefined 时用 default */
+declare function $orDefault(v: Abs, dflt: () => Abs): Abs;
+/** 可选链 a?.b：nullish 短路为 undefined 字面量 */
+declare function $optionalGet(o: Abs, key: string): Abs;
+/** 可选链 a?.m()：nullish 短路为 undefined */
+declare function $optionalInvoke(thisVal: Abs, method: string, args: Abs[]): Abs;
+/** 静态方法：cls.staticMethod(args) */
+declare function $staticInvoke(cls: Abs, method: string, args: Abs[]): Abs;
+/** 计算属性写：o[kAbs] = v */
+declare function $setKey(o: Abs, key: Abs, value: Abs): Abs;
+
+/**
+ * 成员缺失诊断（B 路径 + Abs ast-eval 共用）。
+ * 无 $call / transpile 依赖，避免 ast-eval ↔ calls 循环。
+ */
+
+type BMemberDiag = {
+    kind: "method" | "property";
+    name: string;
+    /** 接收者 prim 类型名，或 "unknown" */
+    receiver: string;
+    line?: number;
+    column?: number;
+    /** 调用点来源（provenance）：实参字面量 loc 优先，否则最近 $callNamed loc */
+    origin?: {
+        line: number;
+        column: number;
+    };
+};
+/** 给实参 Abs 打 provenance（调用点参数字面量） */
+declare function tagAbsOrigin(a: Abs, loc: {
+    line: number;
+    column: number;
+}): void;
+declare function getAbsOrigin(a: Abs | undefined): {
+    line: number;
+    column: number;
+} | undefined;
+declare function setMemberDiagCollector(c: ((d: BMemberDiag) => void) | null): void;
+declare function recordMemberDiag(d: BMemberDiag): void;
+/**
+ * prim 接收者上的未知成员 → 诊断。
+ * 返回 true 表示确定缺失（number 上任意方法；string 上表外方法）。
+ */
+declare function notePrimMemberMissing(recv: Abs | undefined, name: string, kind: "method" | "property", loc?: [number, number]): boolean;
+/**
+ * unknown 接收者上的成员访问 → unknown-recv（与 TypeValue 口径对齐：
+ * object/instance/refined/promise 静默；其余记一条）。
+ */
+declare function noteUnknownMemberMissing(recv: Abs | undefined, name: string, kind: "method" | "property", loc?: [number, number]): boolean;
+/** 方法分派失败时的统一记账（prim / unknown；obj/brand/promise 静默） */
+declare function noteMemberDispatchMiss(recv: Abs | undefined, name: string, kind: "method" | "property", loc?: [number, number]): void;
+
+/**
+ * B 路径调用点记录：transpile 把 `f(args)` 改成 $callNamed，
+ * 分析时可收集 call@ 所需的 AbsCallRecord。
+ * 成员缺失诊断见 member-diag.ts（与 ast-eval 共用，避免循环依赖）。
+ */
+
+type BCallRecord = {
+    fnName: string;
+    args: Abs[];
+    result: Abs;
+    callLoc?: {
+        line: number;
+        column: number;
+    };
+    threw?: boolean;
+};
+declare function setBCallCollector(collector: ((r: BCallRecord) => void) | null): void;
+declare function getBCallCollector(): ((r: BCallRecord) => void) | null;
+/**
+ * 按名调用并记录。
+ * loc: [line, column]（1-based line，0-based column，与 Babel 一致）
+ * argLocs: 与 args 对齐的实参字面量源位置（provenance；无 loc 用 null）
+ */
+declare function $callNamed(name: string, fn: unknown, args: Abs[], loc?: [number, number], argLocs?: Array<[number, number] | null | undefined>): Abs;
+
+/**
+ * 进程内 B 路径执行：transpile 源码 → new Function 跑在 runtime 上。
+ * 不写临时文件；相对 import 用注入的 AbsModuleExports / JS 导出绑定。
+ *
+ * mode:
+ * - "exec"（默认）：执行全部顶层（含副作用）
+ * - "analyze"：只保留函数声明与纯字面量 const；跳过顶层表达式/循环/if
+ *   ——分析入口安全，不触发 fetch 等顶层副作用
+ */
+
+type RunTranspiledOptions = {
+    /** 说明符 → 依赖导出（host 模块图或 runTranspiled 产物） */
+    modules?: Record<string, AbsModuleExports | Record<string, unknown>>;
+    maxLoopIters?: number;
+    /** analyze = 跳过效应性顶层语句 */
+    mode?: "exec" | "analyze";
+    /** @nudo:replace 注入值：varName → Abs */
+    replacements?: Record<string, Abs>;
+    /** @nudo:replace 匹配表：传给 transpile */
+    replacementTargets?: Array<{
+        target: string;
+        varName: string;
+        stmtStart?: number;
+        stmtEnd?: number;
+    }>;
+    /** @nudo:as 注入值：varName → Abs */
+    asOverrides?: Record<string, Abs>;
+    /** @nudo:as 语句范围表 */
+    asOverrideTargets?: Array<{
+        varName: string;
+        stmtStart: number;
+        stmtEnd: number;
+    }>;
+    /** @nudo:env 全局 Abs（JSON/Math/console…）→ 作用域绑定 */
+    envGlobals?: Record<string, Abs>;
+};
+/**
+ * 执行一段 B 路径程序，返回顶层 `export function` / `export const`。
+ */
+declare function runTranspiled(source: string, opts?: RunTranspiledOptions): Record<string, unknown>;
+type TranspiledCallResult = {
+    result: Abs;
+    /** 非 never 表示函数可能 throw 该类型 */
+    throws: Abs;
+};
+/** 调用 runTranspiled 导出（捕获 $throw） */
+declare function callTranspiledExportFull(exports: Record<string, unknown>, name: string, args: Abs[]): TranspiledCallResult;
+/** 调用 runTranspiled 导出（仅结果） */
+declare function callTranspiledExport(exports: Record<string, unknown>, name: string, args: Abs[]): Abs;
+
+export { $add as $, type AstEnv as A, $invoke as B, type Confidence as C, $invokeSuper as D, $join as E, $le as F, $len as G, type HofSite as H, $lit as I, $lt as J, $mod as K, type LeakBudget as L, $mul as M, $ne as N, $neg as O, type Phi as P, $new as Q, type RelSource as R, type Shape as S, type Term as T, $not as U, $obj as V, $optionalGet as W, $optionalInvoke as X, $orDefault as Y, $regex as Z, $set as _, type Abs as a, ge as a$, $setKey as a0, $spread as a1, $staticInvoke as a2, $sub as a3, $super as a4, $switch as a5, $thisGet as a6, $thisSet as a7, $throw as a8, $typeof as a9, applyAbsFn as aA, applyCallbackAbs as aB, asAbs as aC, asAbsVal as aD, betaOf as aE, bindImports as aF, bool as aG, boolLit as aH, callFunction as aI, callTranspiledExport as aJ, callTranspiledExportFull as aK, clearBClasses as aL, collectAbsExports as aM, collectAbsNodeTypes as aN, confJoin as aO, createHofCollectCtx as aP, currentExecPhi as aQ, defaultLeakBudget as aR, emptyEnv as aS, emptyPhi as aT, eq as aU, evalMethodBody as aV, evalNode as aW, evalProgramAbs as aX, evalSource as aY, exceedsBudget as aZ, findAbsAtPosition as a_, $while as aa, $whileSeq as ab, $yield as ac, type AbsAssignRecord as ad, type AbsCallRecord as ae, type AbsModuleExports as af, type BCallRecord as ag, type BClassSpec as ah, type BMemberDiag as ai, DEFAULT_MAX_LOOP_ITERS as aj, type EvalOptions as ak, type EvalResult as al, type HofCollectCtx as am, MAX_CALL_DEPTH as an, MAX_TOTAL_CALLS as ao, NudoThrow as ap, type RunTranspiledOptions as aq, type TranspileOptions as ar, type TranspiledCallResult as as, abs as at, absToString as au, alphaOf as av, analyzeFn as aw, and as ax, anyVar as ay, app as az, type Pred as b, strLit as b$, geNum as b0, getAbsOrigin as b1, getBCallCollector as b2, getBClass as b3, gt as b4, gtNum as b5, implies as b6, instantiateReturn as b7, isDefinitelyFalse as b8, isDefinitelyTrue as b9, or as bA, pFalse as bB, pTrue as bC, phiAnd as bD, predEquals as bE, predToString as bF, predVars as bG, projectFlatMapResult as bH, promoteParamShape as bI, ptypeof as bJ, recordMemberDiag as bK, registerBClass as bL, resetAbsCallBudget as bM, resetLeakCounter as bN, runTranspiled as bO, setAbsAssignCollector as bP, setAbsCallCollector as bQ, setAbsNodeCollector as bR, setAbsTruncationCollector as bS, setApplyCallbackHost as bT, setBCallCollector as bU, setMemberDiagCollector as bV, shapeOfTerm as bW, shapeToString as bX, simplifyTerm as bY, snapshotAbs as bZ, str as b_, isExactLit as ba, isNudoThrow as bb, isNumPrim as bc, isRelFn as bd, isStrPrim as be, le as bf, leNum as bg, leakIfNeeded as bh, lit as bi, litTruth as bj, litValue as bk, lt as bl, ltNum as bm, mapElementFallback as bn, maybeLeak as bo, namespaceNameOf as bp, ne as bq, never as br, not as bs, noteMemberDispatchMiss as bt, notePrimMemberMissing as bu, noteUnknownMemberMissing as bv, num as bw, numLit as bx, numVar as by, obj as bz, type PrimName as c, substAbs as c0, substPred as c1, substPredAbs as c2, tagAbsOrigin as c3, termDepth as c4, termEquals as c5, termNodes as c6, termToString as c7, transpile as c8, transpileExpression as c9, transpileFile as ca, transpileSource as cb, tryPromoteDirectCall as cc, tryPromoteForOfIteratee as cd, tryPromoteHofCallback as ce, tryPromoteReceiverAsArr as cf, undefAbs as cg, unknown as ch, v as ci, withExecPhi as cj, withVar as ck, $arr as d, $async as e, $asyncReturn as f, $await as g, $call as h, $callNamed as i, $catchVal as j, $class as k, $concat as l, $div as m, $elems as n, $eq as o, $fnVal as p, $for as q, $forIter as r, $forOf as s, $fork as t, $ge as u, $gen as v, $get as w, $gt as x, $idx as y, $idxSet as z };