@nudojs/core 1.3.0 → 1.4.0

package/dist/{run-Dk08Q5zl.d.ts → run-WJfj477N.d.ts}

@@ -2,7 +2,7 @@ import * as _babel_types from '@babel/types';
 import { Node, ImportDeclaration, File } from '@babel/types';
 
 /** 项（Term）：抽象值的身份。字面量是项的特例。 */
-type LiteralValue = string | number | boolean | null | undefined;
+type LiteralValue = string | number | boolean | bigint | null | undefined;
 type Term = {
     op: "lit";
     value: LiteralValue;
@@ -247,7 +247,17 @@ declare function isStrPrim(a: Abs): boolean;
 declare function isBigPrim(a: Abs): boolean;
 /** 置信度：字面量全确定 */
 declare function isExactLit(a: Abs): boolean;
-declare function litValue(a: Abs): LiteralValue | undefined;
+/**
+ * tagged result：把「无字面量」与「字面量 undefined」分开。
+ * 判定是否是字面量必须看 `ok`，禁止用 `value !== undefined` / `(litValue(...).ok ? litValue(...).value : undefined) !== undefined`。
+ */
+type LitValueResult = {
+    ok: true;
+    value: LiteralValue;
+} | {
+    ok: false;
+};
+declare function litValue(a: Abs): LitValueResult;
 
 /**
  * may-throw 效果收集（design-cli-semantics §3.3）。
@@ -321,6 +331,27 @@ declare function filterIgnoredThrows(effects: MayThrowEffect[], ignore: readonly
  */
 declare function filterDeclaredThrows(effects: MayThrowEffect[], declared: readonly string[] | "*" | undefined): MayThrowEffect[];
 
+/**
+ * 调用 Abs 一等函数（absFunction impl）或 mock apply。
+ * 供 求值引擎 import 绑定包装：`(...args) => $call(absFn, args)`。
+ *
+ * 统一顺序：apply → body → relation → isRelFn（委托 applyAbsFn）。
+ * 行为对齐说明（与旧 $call 的差异，均属刻意）：
+ * 1. 带 body 的函数也进 call-budget（递归会 truncated 而非爆栈）
+ * 2. body 抛错与 apply 同径 rethrow（不吞成 never 返回，调用边界决定吸收）
+ * 3. 无 impl 时 isRelFn 可走 E 路径（旧版恒 unknown）
+ */
+
+/** 清空 pure memo（宿主入口 / 会话缓存失效） */
+declare function clearPureMemo(): void;
+/**
+ * apply 返回的 throws 面 → 调用方控制流通道（H1 单点路由）。
+ * always-throw（abs=never）→ NudoThrow，由调用边界收成 throws；
+ * may-throw → pushThrowExit 记入调用方 throwExits（try/catch 可吸收）。
+ */
+declare function routeApplyThrows(r: Abs, throws: Abs | undefined): Abs;
+declare function $call(fn: Abs, args: Abs[], thisVal?: Abs): Abs;
+
 /**
  * 求值引擎调用点记录：transpile 把 `f(args)` 改成 $callNamed，
  * 分析时可收集 call@ 所需的 AbsCallRecord。
@@ -337,6 +368,8 @@ type EvalCallRecord = {
     };
     threw?: boolean;
 };
+/** 清空 pureCallMemo（宿主入口 / 会话缓存失效） */
+declare function clearPureCallMemo(): void;
 /** B 赋值记录（与 ast-records.ts AbsAssignRecord 同形；structuralAssignIssues 消费） */
 type EvalAbsAssignRecord = {
     name: string;
@@ -463,6 +496,147 @@ type AstEnv = {
     hofCollect?: HofCollectCtx;
 };
 
+/**
+ * Abs 上的一等函数：shape 是 fn，实现在旁路（不污染 Shape）。
+ * 与 term-registry 同一纪律：不给共享单例挂 impl。
+ */
+
+/** Abs 原生 env/builtin 实现（evaluator 优先） */
+type AbsSigImpl = (args: Abs[], thisVal?: Abs) => Abs | undefined;
+/**
+ * 已知不抛的 apply 返回面（裸 Abs，无 throws 通道）。
+ * 等价 `Abs`，仅作意图标注：impl 作者写死「本 apply 不抛」时用它收窄签名，
+ * 调用侧仍应经 `absOnly` / `isAbsApplyResult` 取 abs（`AbsFnImpl.apply` 静态面是宽的）。
+ */
+type AbsApplyNoThrow = Abs;
+/**
+ * 已知不抛的 apply 实现签名（`AbsSigImpl` 的 apply 对偶）。
+ * 返回裸 `Abs` = 不抛；需要 throws 面时改用 `AbsFnImpl["apply"]`（`AbsApplyReturn`）。
+ */
+type AbsApplyNoThrowFn = (args: Abs[], thisVal?: Abs) => AbsApplyNoThrow;
+/**
+ * apply 契约返回的 throws 通道（H1 / DESIGN-003）。
+ * `throws` 必填：不抛传 `never`。$call 统一路由——
+ * always-throw（abs=never）→ NudoThrow 由调用边界收成 throws；
+ * may-throw → pushThrowExit 记入调用方 throwExits（try/catch 可吸收）。
+ * 包装 `callTranspiledExportFull` 必须走 `callTranspiledExportApply`，
+ * 不得手拆 `.result`（会静默丢 throws 面）。
+ *
+ * 构造只经 `makeAbsApplyResult`（打上 brand）；`isAbsApplyResult` 只认 brand，
+ * 避免裸对象靠 `!shape` 误判成 apply 结果、吞掉 throws 面。
+ */
+type AbsApplyResult = {
+    abs: Abs;
+    throws: Abs;
+    /** Discriminator stamped by makeAbsApplyResult. */
+    readonly applyResult: true;
+};
+/** apply 可返回裸 Abs（无 throws）或带 throws 通道的 AbsApplyResult */
+type AbsApplyReturn = Abs | AbsApplyResult;
+/** 唯一构造入口：打上 applyResult brand。 */
+declare function makeAbsApplyResult(abs: Abs, throws: Abs): AbsApplyResult;
+/** AbsApplyResult 判别：只认 brand（不靠 !shape 结构猜）。 */
+declare function isAbsApplyResult(v: AbsApplyReturn): v is AbsApplyResult;
+/**
+ * apply 返回值取 abs 面（已知不抛 / 测试面只想看结果时用）。
+ * 丢弃 throws 通道——若 impl 可能抛，必须走 `$call` 统一路由，不得用本函数吞 throws。
+ */
+declare function absOnly(r: AbsApplyReturn): AbsApplyNoThrow;
+type AbsFnImpl = {
+    params: string[];
+    /** 可选：无 body 时走 relation（纯关系 fn） */
+    body?: Node;
+    async?: boolean;
+    /** 声明时捕获的环境（闭包） */
+    env?: AstEnv;
+    kind?: string;
+    /**
+     * 调用时直接派发（mock withArgs 等），优先于 body。
+     * 返回裸 Abs = 不抛；返回 AbsApplyResult 时 throws 面经 $call 统一路由，
+     * 不得在 apply 内自行 re-throw / pushThrowExit（会与 $call 路由叠算）。
+     */
+    apply?: (args: Abs[], thisVal?: Abs) => AbsApplyReturn;
+    /**
+     * 对象方法（ObjectMethod / 方法型 FunctionExpression）：$invoke 时把
+     * receiver 作为 apply 的**首参**注入。shape.params 仍是用户可见形参
+     * （不含 receiver），自由调用不注入 → this 为 unbound（JS 语义）。
+     */
+    bindThis?: boolean;
+    /**
+     * Optional content key for cache fingerprints. formatAbs cannot see
+     * WeakMap-side mock semantics (returns/withArgs/callsFake), so hosts that
+     * build mocks should stamp a stable fingerprint here.
+     * relation-only 必填（未传时 relationFn 自动生成）。
+     */
+    fingerprint?: string;
+    /** 无 body 时，按 paramTypes 做 α 替换得到返回 */
+    relation?: {
+        paramTypes: Abs[];
+        returnType: Abs;
+        /**
+         * 条件类型 infer：绑定 fromVar 后从 via 投出 inferVar
+         * （`T extends (infer E)[]` → via: "arr"；`T extends Promise<infer U>` → "promise"）。
+         */
+        inferFrom?: {
+            fromVar: string;
+            via: "arr" | "promise";
+            inferVar: string;
+        };
+        /** extends 不成立时的假分支（如 never） */
+        condFallback?: Abs;
+    };
+    /** `@nudo:pure`：调用结果按实参记忆化（无副作用契约） */
+    pureName?: string;
+};
+declare function attachFnImpl(a: Abs, impl: AbsFnImpl): void;
+declare function getFnImpl(a: Abs): AbsFnImpl | undefined;
+/** 标记纯函数（@nudo:pure）：调用结果可按实参记忆化 */
+declare function markPureFn(target: object, name: string): void;
+/** 读纯函数标记（Abs impl 或对象属性 `_memoize`） */
+declare function pureFnNameOf(fn: unknown): string | undefined;
+/** 造一个带实现的 Abs 函数值 */
+declare function absFunction(params: string[], impl: Omit<AbsFnImpl, "params">, opts?: {
+    name?: string;
+    paramTypes?: Abs[];
+    returnType?: Abs;
+    slots?: Record<string, {
+        value: Abs;
+        optional?: boolean;
+        readonly?: boolean;
+    }>;
+    conf?: Confidence;
+}): Abs;
+/** relationFn 稳定 fingerprint（同签名共享，见 §3.3 已知限制） */
+declare function relationFingerprint(paramTypes: Abs[], returnType: Abs): string;
+/**
+ * 无 body、纯关系的 fn Abs。params 仅记 arity。
+ *
+ * **双写纪律：** 同一份关系数据必须同时写到——
+ *   1. `shape.paramTypes` / `shape.returnType`  —— format / leq / 展示读这里
+ *   2. `impl.relation`                         —— D 路径应用读这里
+ * 两槽共享同一数组/对象引用（防内容分叉）；构造后请勿原地 mutate。
+ *
+ * 默认 conf="path"（与提升产物一致）。禁止静默对齐 absFunction 的 "exact"。
+ * fingerprint 必填（call-budget）；未传时由 paramTypes+returnType 稳定序列化生成。
+ * 同签名 relationFn 共享 fingerprint → 共享 budget 键（见 design §3.3 已知限制）。
+ */
+declare function relationFn(paramTypes: Abs[], returnType: Abs, opts?: {
+    params?: string[];
+    conf?: Confidence;
+    fingerprint?: string;
+    inferFrom?: {
+        fromVar: string;
+        via: "arr" | "promise";
+        inferVar: string;
+    };
+    condFallback?: Abs;
+}): Abs;
+/** 仅写 shape 槽（E 路径 / §5.2 提升产物）；禁止 attachFnImpl */
+declare function shapeOnlyFn(paramTypes: Abs[], returnType: Abs, opts?: {
+    params?: string[];
+    conf?: Confidence;
+}): Abs;
+
 /**
  * Abs 模块面（无 fs）：import 绑定 + export 收集。
  * 解析路径/读文件在 host；core 只吃「specifier → 导出表」。
@@ -582,5 +756,14 @@ declare function callTranspiledExportFull(exports: Record<string, unknown>, name
 }): TranspiledCallResult;
 /** 调用 runTranspiled 导出（仅结果） */
 declare function callTranspiledExport(exports: Record<string, unknown>, name: string, args: Abs[]): Abs;
+/**
+ * 包装 runTranspiled 导出为 Abs apply 钩子——throws 面经返回值通道强制保留
+ * （H1 / DESIGN-003）。这是包装 `callTranspiledExportFull` 的**唯一入口**：
+ * 返回 AbsApplyResult（`{abs, throws}`），$call 统一路由 throws。
+ * 手拆 `.result` 会静默丢 throws 面（BUG-006 根因）。
+ *
+ * `exports` 可传惰性 getter（互递归模块桥：导出表在桥创建后才赋值）。
+ */
+declare function callTranspiledExportApply(exports: Record<string, unknown> | (() => Record<string, unknown>), name: string): (args: Abs[], thisVal?: Abs) => AbsApplyResult;
 
-export { $tryDigestSoft as $, type Abs as A, throwAbsToKinds as B, type Confidence as C, throwsKindCovered as D, ERROR_FAMILY as E, withEvalBudgetOverride as F, type HofSite as G, type HofCollectCtx as H, type AbsModuleExports as I, type RunTranspiledOptions as J, $assignRecord as K, $callNamed as L, type MayThrowEffect as M, $recordBinding as N, type EvalAbsAssignRecord as O, type PrimName as P, type EvalCallRecord as Q, type RelSource as R, type Shape as S, type Term as T, type EvalFallback as U, type ImplicationOracle as V, type LiteralValue as W, MAX_EVAL_CALL_DEPTH as X, MAX_EVAL_TOTAL_CALLS as Y, RUNTIME_IMPORT_RE as Z, TYPEOF_NAMES as _, type Pred as a, setEvalCallCollector as a$, type TranspiledCallResult as a0, type TypeofName as a1, abs as a2, absToString as a3, and as a4, anyAbs as a5, anyVar as a6, app as a7, assumeFinite as a8, bigintLit as a9, lt as aA, ltNum as aB, namespaceAbsOf as aC, ne as aD, negatePred as aE, never as aF, not as aG, noteEvalCallRecord as aH, noteEvalFallback as aI, num as aJ, numLit as aK, numVar as aL, obj as aM, or as aN, pFalse as aO, pTrue as aP, phiAnd as aQ, predEquals as aR, predToString as aS, predVars as aT, primToTypeof as aU, ptypeof as aV, resetEvalCallBudget as aW, runTranspiled as aX, runTranspiledOptionsMemoKey as aY, setEvalAssignCollector as aZ, setEvalBindingSink as a_, bindImports as aa, bindingsOf as ab, bool as ac, boolLit as ad, callTranspiledExport as ae, callTranspiledExportFull as af, collectAbsExports as ag, confJoin as ah, emptyPhi as ai, eq as aj, evalExprAbs as ak, ge as al, geNum as am, getEvalCallCollector as an, getImplicationOracle as ao, gt as ap, gtNum as aq, implies as ar, isBigPrim as as, isExactLit as at, isNumPrim as au, isStrPrim as av, le as aw, leNum as ax, lit as ay, litValue as az, type Phi as b, setEvalFallbackCollector as b0, setImplicationOracle as b1, shapeOfTerm as b2, shapeToString as b3, simplifyTerm as b4, str as b5, strLit as b6, substPred as b7, termEquals as b8, termToString as b9, tryRunTranspiled as ba, unknown as bb, v as bc, type AstEnv as c, $tryMarkSoft as d, $tryReleaseSoft as e, type EvalFallbackStats as f, enterEvalCallBudgetSession as g, errorTypeAbs as h, exitEvalCallBudgetSession as i, filterDeclaredThrows as j, filterGateThrows as k, filterIgnoredThrows as l, flushMayThrowEffects as m, formatThrowsAbs as n, getEvalCallBudgetState as o, getEvalFallbackStats as p, getMayThrowCollector as q, isThrowsIgnored as r, mayThrowEffectsToAbs as s, orphanMayThrowEffects as t, popMayThrowFrame as u, pushMayThrowFrame as v, recordMayThrow as w, resetEvalFallbackStats as x, runWithMayThrowSession as y, setMayThrowCollector as z };
+export { $tryDigestSoft as $, type Abs as A, runWithMayThrowSession as B, type Confidence as C, setMayThrowCollector as D, ERROR_FAMILY as E, throwAbsToKinds as F, throwsKindCovered as G, withEvalBudgetOverride as H, type HofCollectCtx as I, type HofSite as J, type AbsModuleExports as K, type LiteralValue as L, type MayThrowEffect as M, type RunTranspiledOptions as N, $assignRecord as O, type PrimName as P, $call as Q, type RelSource as R, type Shape as S, type Term as T, $callNamed as U, $recordBinding as V, type AbsApplyNoThrow as W, type AbsApplyNoThrowFn as X, type AbsApplyResult as Y, type AbsApplyReturn as Z, type AbsFnImpl as _, type Pred as a, num as a$, type AbsSigImpl as a0, type EvalAbsAssignRecord as a1, type EvalCallRecord as a2, type EvalFallback as a3, type ImplicationOracle as a4, type LitValueResult as a5, MAX_EVAL_CALL_DEPTH as a6, MAX_EVAL_TOTAL_CALLS as a7, RUNTIME_IMPORT_RE as a8, TYPEOF_NAMES as a9, geNum as aA, getEvalCallCollector as aB, getFnImpl as aC, getImplicationOracle as aD, gt as aE, gtNum as aF, implies as aG, isAbsApplyResult as aH, isBigPrim as aI, isExactLit as aJ, isNumPrim as aK, isStrPrim as aL, le as aM, leNum as aN, lit as aO, litValue as aP, lt as aQ, ltNum as aR, makeAbsApplyResult as aS, markPureFn as aT, namespaceAbsOf as aU, ne as aV, negatePred as aW, never as aX, not as aY, noteEvalCallRecord as aZ, noteEvalFallback as a_, type TranspiledCallResult as aa, type TypeofName as ab, abs as ac, absFunction as ad, absOnly as ae, absToString as af, and as ag, anyAbs as ah, anyVar as ai, app as aj, assumeFinite as ak, attachFnImpl as al, bigintLit as am, bindImports as an, bindingsOf as ao, bool as ap, boolLit as aq, callTranspiledExport as ar, callTranspiledExportApply as as, callTranspiledExportFull as at, collectAbsExports as au, confJoin as av, emptyPhi as aw, eq as ax, evalExprAbs as ay, ge as az, type Phi as b, numLit as b0, numVar as b1, obj as b2, or as b3, pFalse as b4, pTrue as b5, phiAnd as b6, predEquals as b7, predToString as b8, predVars as b9, primToTypeof as ba, ptypeof as bb, pureFnNameOf as bc, relationFingerprint as bd, relationFn as be, resetEvalCallBudget as bf, runTranspiled as bg, runTranspiledOptionsMemoKey as bh, setEvalAssignCollector as bi, setEvalBindingSink as bj, setEvalCallCollector as bk, setEvalFallbackCollector as bl, setImplicationOracle as bm, shapeOfTerm as bn, shapeOnlyFn as bo, shapeToString as bp, simplifyTerm as bq, str as br, strLit as bs, substPred as bt, termEquals as bu, termToString as bv, tryRunTranspiled as bw, unknown as bx, v as by, routeApplyThrows as bz, type AstEnv as c, $tryMarkSoft as d, $tryReleaseSoft as e, type EvalFallbackStats as f, clearPureCallMemo as g, clearPureMemo as h, enterEvalCallBudgetSession as i, errorTypeAbs as j, exitEvalCallBudgetSession as k, filterDeclaredThrows as l, filterGateThrows as m, filterIgnoredThrows as n, flushMayThrowEffects as o, formatThrowsAbs as p, getEvalCallBudgetState as q, getEvalFallbackStats as r, getMayThrowCollector as s, isThrowsIgnored as t, mayThrowEffectsToAbs as u, orphanMayThrowEffects as v, popMayThrowFrame as w, pushMayThrowFrame as x, recordMayThrow as y, resetEvalFallbackStats as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nudojs/core",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "engines": {
     "node": ">=20"
   },