@nudojs/core 1.7.10 → 1.8.0

package/dist/exec.js

@@ -193,7 +193,7 @@ import {
   tryRunTranspiled,
   withEvalBudgetOverride,
   withExecPhi
-} from "./chunk-MJP4P5J3.js";
+} from "./chunk-P6O5BXOA.js";
 export {
   $absVal,
   $add,

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { c as AstEnv, A as Abs, b as Phi, T as Term, O as HofCollectCtx, C as Confidence, S as Shape, a as Pred, R as RelSource, Q as HofSite, U as AbsModuleExports, V as RunTranspiledOptions } from './run-DbDRo5z6.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 ImplicationOracle, a9 as LitValueResult, L as LiteralValue, aa as MAX_EVAL_CALL_DEPTH, ab as MAX_EVAL_TOTAL_CALLS, P as PrimName, ac as RUNTIME_IMPORT_RE, ad as TYPEOF_NAMES, ae as TranspiledCallResult, af as TypeofName, ag as abs, ah as absFunction, ai as absOnly, aj as absToString, ak as and, al as anyAbs, am as anyVar, an as app, ao as assumeFinite, ap as attachFnImpl, aq as bigintLit, ar as bindImports, as as bindingsOf, at as bool, au as boolLit, av as callTranspiledExport, aw as callTranspiledExportApply, ax as callTranspiledExportFull, ay as collectAbsExports, az as confJoin, aA as emptyPhi, aB as eq, aC as evalExprAbs, aD as ge, aE as geNum, aF as getEvalCallCollector, aG as getFnImpl, aH as getImplicationOracle, aI as gt, aJ as gtNum, aK as hostFnCtorFacet, aL as implies, aM as isAbsApplyResult, aN as isAbsVal, aO as isBigPrim, aP as isExactLit, aQ as isNumPrim, aR as isStrPrim, aS as le, aT as leNum, aU as lit, aV as litValue, aW as lt, aX as ltNum, aY as makeAbsApplyResult, aZ as markPureFn, a_ as namespaceAbsOf, a$ as ne, b0 as negatePred, b1 as never, b2 as not, b3 as noteEvalCallRecord, b4 as noteEvalFallback, b5 as num, b6 as numLit, b7 as numVar, b8 as obj, b9 as or, ba as pFalse, bb as pTrue, bc as phiAnd, bd as predEquals, be as predToString, bf as predVars, bg as primToTypeof, bh as ptypeof, bi as pureFnNameOf, bj as relationFingerprint, bk as relationFn, bl as resetEvalCallBudget, bm as runTranspiled, bn as runTranspiledOptionsMemoKey, bo as setEvalAssignCollector, bp as setEvalBindingSink, bq as setEvalCallCollector, br as setEvalFallbackCollector, bs as setImplicationOracle, bt as shapeOfTerm, bu as shapeOnlyFn, bv as shapeToString, bw as simplifyTerm, bx as str, by as strLit, bz as substPred, bA as termEquals, bB as termToString, bC as tryRunTranspiled, bD as unknown, bE as v } from './run-DbDRo5z6.js';
 import { Node, File } from '@babel/types';
-import { p as parseSource, L as LeakBudget, E as EffectiveInterfaceOpts, b as LoadDepsFingerprint, v as CheckReport, N as NudoConstraint, c as ProjectionBudget } from './projection-budget-CtwnzYLG.js';
-export { w as CONSTRAINT_BUILDERS, x as CONSTRAINT_BUILDER_NAMES, y as CONSTRAINT_EXPR_RE, z as CheckAction, C as CheckIssue, A as CheckJson, B as CheckJsonMulti, D as ConstraintBuilder, F as Diagnostic, G as EffectiveInterface, H as GitlabCodeQualityIssue, J as InterfaceDiag, I as InterfaceSource, K as InterfaceTierInfo, a as InterfaceTierOpts, O as NamedImport, Q as NudoField, R as NudoFnConstraint, S as NudoSidecarError, T as NudoSig, U as RefineDiag, V as RefineEntry, W as RefineResolveOpts, X as SELF, Y as actionsForIssue, Z as andC, _ as any, $ as array, a0 as boolean, a1 as checkArg, a2 as checkCall, a3 as constraintAdmitsNullish, a4 as constraintToEntryAbs, a5 as drainPromiseMicros, a6 as effectiveInterface, a7 as enterPromiseExecutorScope, a8 as evalPromiseCtor, a9 as evalPromiseMethod, aa as evalPromiseStatic, ab as execNudoModule, ac as extractDeclaredThrows, ad as extractFnBudget, ae as extractNudoImports, af as extractRefineReturnFromSource, ag as extractRefinesFromSource, ah as fn, ai as fnConstraintToEntryReqs, aj as formatCheckReport, ak as formatConstraint, al as formatDiagnostics, am as formatEffectiveInterfaceDisplay, an as formatGithubAnnotations, ao as formatGitlabCodeQuality, ap as formatInterfaceTierLine, aq as generatedExportNames, ar as getParseSourceCacheSize, as as getTerm, at as instantiateConstraint, au as interfaceDiagCount, av as interfaceSourceOf, aw as interfaceTierOf, ax as isIntFlag, ay as isNodeModulesPath, az as isNudoConstraint, aA as leavePromiseExecutorScope, aB as lenTerm, aC as litC, aD as localNamedExports, aE as notePromiseExecutorFork, aF as nullable, aG as number, aH as omit, aI as partial, aJ as pick, aK as queuePromiseMicro, aL as refineDiagCount, aM as refineToIndexedFull, aN as resetNudoModuleExecCache, aO as resetParseSourceCache, aP as resetSidecarLoadFailureCache, aQ as serializeCheckJson, aR as serializeCheckJsonMulti, aS as setInterfaceDiagCollector, aT as setRefineDiagCollector, aU as shape, aV as sidecarClosureFingerprint, aW as sidecarPathOf, aX as string, aY as takeInterfaceDiags, aZ as takeInterfaceDiagsSince, a_ as takeRefineDiags, a$ as takeRefineDiagsSince, b0 as throwConstraintToKinds, b1 as union } from './projection-budget-CtwnzYLG.js';
+import { p as parseSource, L as LeakBudget, E as EffectiveInterfaceOpts, b as LoadDepsFingerprint, v as CheckReport, N as NudoConstraint, c as ProjectionBudget } from './projection-budget-vi5Ssjdr.js';
+export { w as CONSTRAINT_BUILDERS, x as CONSTRAINT_BUILDER_NAMES, y as CONSTRAINT_EXPR_RE, z as CheckAction, C as CheckIssue, A as CheckJson, B as CheckJsonMulti, D as ConstraintBuilder, F as Diagnostic, G as EffectiveInterface, H as GitlabCodeQualityIssue, J as InterfaceDiag, I as InterfaceSource, K as InterfaceTierInfo, a as InterfaceTierOpts, O as NamedImport, Q as NudoField, R as NudoFnConstraint, S as NudoSidecarError, T as NudoSig, U as RefineDiag, V as RefineEntry, W as RefineResolveOpts, X as SELF, Y as actionsForIssue, Z as andC, _ as any, $ as array, a0 as boolean, a1 as checkArg, a2 as checkCall, a3 as constraintAdmitsNullish, a4 as constraintToEntryAbs, a5 as derefConstraint, a6 as drainPromiseMicros, a7 as effectiveInterface, a8 as enterPromiseExecutorScope, a9 as evalPromiseCtor, aa as evalPromiseMethod, ab as evalPromiseStatic, ac as execNudoModule, ad as extractDeclaredThrows, ae as extractFnBudget, af as extractNudoImports, ag as extractRefineReturnFromSource, ah as extractRefinesFromSource, ai as fn, aj as fnConstraintToEntryReqs, ak as formatCheckReport, al as formatConstraint, am as formatDiagnostics, an as formatEffectiveInterfaceDisplay, ao as formatGithubAnnotations, ap as formatGitlabCodeQuality, aq as formatInterfaceTierLine, ar as generatedExportNames, as as getParseSourceCacheSize, at as getTerm, au as instantiateConstraint, av as interfaceDiagCount, aw as interfaceSourceOf, ax as interfaceTierOf, ay as isIntFlag, az as isNodeModulesPath, aA as isNudoConstraint, aB as lazy, aC as leavePromiseExecutorScope, aD as lenTerm, aE as litC, aF as localNamedExports, aG as notePromiseExecutorFork, aH as nullable, aI as number, aJ as omit, aK as partial, aL as pick, aM as queuePromiseMicro, aN as refineDiagCount, aO as refineToIndexedFull, aP as resetNudoModuleExecCache, aQ as resetParseSourceCache, aR as resetSidecarLoadFailureCache, aS as serializeCheckJson, aT as serializeCheckJsonMulti, aU as setInterfaceDiagCollector, aV as setRefineDiagCollector, aW as shape, aX as sidecarClosureFingerprint, aY as sidecarPathOf, aZ as string, a_ as takeInterfaceDiags, a$ as takeInterfaceDiagsSince, b0 as takeRefineDiags, b1 as takeRefineDiagsSince, b2 as throwConstraintToKinds, b3 as union } from './projection-budget-vi5Ssjdr.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';
 
 /**
@@ -1201,7 +1201,7 @@ declare function scanBudgetDecl(lines: string[]): {
  */
 
 /** 字面量 lv 是否落在约束 c 表达的域内（保守：判不了 → false）。 */
-declare function literalMeetsConstraint(lv: number | string | boolean | null | undefined, c: NudoConstraint): boolean;
+declare function literalMeetsConstraint(lv: number | string | boolean | null | undefined, c: NudoConstraint, seen?: Set<object>): boolean;
 
 /**
  * Abs → NudoConstraint 投影（Phase 1，interface 分层推导的生成侧半边）。

package/dist/index.js

@@ -1,19 +1,9 @@
 import "./chunk-US532PZA.js";
 import {
-  CONSTRAINT_BUILDERS,
-  CONSTRAINT_BUILDER_NAMES,
-  CONSTRAINT_EXPR_RE,
   NudoSidecarError,
-  SELF,
-  andC,
-  any,
-  array,
-  boolean,
   buildArgsFromAssume,
   canSkipLiteralCallScan,
   collectAbsFreeVars,
-  constraintAdmitsNullish,
-  constraintToEntryAbs,
   effectiveInterface,
   evictGeneralizeMemoForPaths,
   execNudoModule,
@@ -28,8 +18,6 @@ import {
   extractRefineReturnFromSource,
   extractRefinesFromSource,
   findFnDirectiveScope,
-  fn,
-  fnConstraintToEntryReqs,
   fnDirectiveCommentLines,
   formatConstraint,
   formatEffectiveInterfaceDisplay,
@@ -38,39 +26,27 @@ import {
   generalizeFromAst,
   generatedExportNames,
   getGeneralizeMemoSize,
-  getTerm,
   hashSource,
-  instantiateConstraint,
-  instantiateOnTerm,
   interfaceDiagCount,
   interfaceSourceOf,
   interfaceTierOf,
-  isIntFlag,
   isNodeModulesPath,
-  isNudoConstraint,
-  lenTerm,
   listFnDirectiveScopes,
   listFunctionNames,
   listTopFunctions,
-  litC,
-  literalMeetsConstraint,
   loadModuleDepsFingerprint,
   localNamedExports,
   normPath,
-  nullable,
-  number,
-  omit,
   parseEnvPayload,
   parseMockModulePayload,
   parseNudoImportPayload,
-  partial,
-  pick,
   refineDiagCount,
   refineToIndexedFull,
   resetGeneralizeMemo,
   resetHashSourceCache,
   resetNudoModuleExecCache,
   resetSidecarLoadFailureCache,
+  resolveDepPath,
   scanBudgetDecl,
   scanCaseArgSpans,
   scanCaseTags,
@@ -79,19 +55,15 @@ import {
   scanThrowsDecl,
   setInterfaceDiagCollector,
   setRefineDiagCollector,
-  shape,
   sidecarClosureFingerprint,
   sidecarPathOf,
   stableAnalyzeKeySource,
   stablePathKey,
-  string,
   takeInterfaceDiags,
   takeInterfaceDiagsSince,
   takeRefineDiags,
-  takeRefineDiagsSince,
-  throwConstraintToKinds,
-  union
-} from "./chunk-45WFXDZD.js";
+  takeRefineDiagsSince
+} from "./chunk-WT5J6QTZ.js";
 import {
   $add,
   $arguments,
@@ -203,6 +175,9 @@ import {
   $while,
   $whileSeq,
   $yield,
+  CONSTRAINT_BUILDERS,
+  CONSTRAINT_BUILDER_NAMES,
+  CONSTRAINT_EXPR_RE,
   DEFAULT_MAX_LOOP_ITERS,
   FORK_TRUNCATION_LABEL,
   HOST_EFFECT_LABEL_PREFIX,
@@ -218,6 +193,7 @@ import {
   PROMISE_MICRO_OVERFLOW_LABEL,
   ProjectionBudget,
   RUNTIME_IMPORT_RE,
+  SELF,
   TYPEOF_NAMES,
   abs,
   absFunction,
@@ -227,15 +203,19 @@ import {
   add,
   alphaOf,
   and,
+  andC,
+  any,
   anyAbs,
   anyVar,
   app,
   applyCallbackAbs,
   applyCallbackValue,
+  array,
   asAbs,
   asAbsVal,
   assignSourceSlots,
   assumeFinite,
+  attachContractFaces,
   attachFnImpl,
   beginCollectionFork,
   betaOf,
@@ -248,6 +228,7 @@ import {
   bitxorAbs,
   bool,
   boolLit,
+  boolean,
   builtinCtorAbs,
   builtinCtorNameOf,
   callAbsMethod,
@@ -264,12 +245,16 @@ import {
   collectionElementJoin,
   collectionExactLen,
   confJoin,
+  constraintAdmitsNullish,
+  constraintToEntryAbs,
+  contractFacesFromEffectiveInterface,
   contractParamNameSet,
   createHofCollectCtx,
   ctorArgDefinitelyInvalid,
   ctorNameOfRecv,
   currentExecPhi,
   definitelyNotNullishShape,
+  derefConstraint,
   div,
   drainPromiseMicros,
   emptyEnv,
@@ -304,6 +289,8 @@ import {
   falseConstraint,
   fillTuple,
   filterGateThrows,
+  fn,
+  fnConstraintToEntryReqs,
   fnOf,
   foldRequireSpecArg,
   foldStaticStringExpr,
@@ -326,12 +313,15 @@ import {
   getParseSourceCacheSize,
   getPropFlags,
   getSlot,
+  getTerm,
   gt,
   gtNum,
   hostBuiltinCtorName,
   hostFnCtorFacet,
   identBoundaryRegex,
   implies,
+  instantiateConstraint,
+  instantiateOnTerm,
   instantiateReturn,
   isAbsApplyResult,
   isAbsVal,
@@ -341,8 +331,10 @@ import {
   isDefinitelyTrue,
   isErrorCtorName,
   isExactLit,
+  isIntFlag,
   isMapAbs,
   isNudoBreak,
+  isNudoConstraint,
   isNudoContinue,
   isNudoReturn,
   isNudoThrow,
@@ -360,13 +352,17 @@ import {
   joinFunctions,
   joinObjects,
   joinValues,
+  lazy,
   le,
   leNum,
   leavePromiseExecutorScope,
+  lenTerm,
   leqAbs,
   lit,
+  litC,
   litTruth,
   litValue,
+  literalMeetsConstraint,
   locateContractParam,
   lookupObjAccessor,
   looseEqAbs,
@@ -409,18 +405,23 @@ import {
   noteEvalCallRecord,
   noteEvalFallback,
   notePromiseExecutorFork,
+  nullable,
   num,
   numLit,
   numVar,
+  number,
   obj,
   objOf,
   objectProtoBrand,
   objectProtoMethodAbs,
+  omit,
   or,
   pFalse,
   pTrue,
   parseSource,
+  partial,
   phiAnd,
+  pick,
   popCollectionArm,
   powAbs,
   predEquals,
@@ -457,6 +458,7 @@ import {
   setAddEntry,
   setApplyCallbackHost,
   setClearEntries,
+  setContractFaceResolver,
   setDeleteEntry,
   setElementsAbs,
   setEvalAssignCollector,
@@ -468,6 +470,7 @@ import {
   setMayThrowCollector,
   setPropFlags,
   setSizeAbs,
+  shape,
   shapeOfTerm,
   shapeOnlyFn,
   shapeToString,
@@ -479,6 +482,7 @@ import {
   str,
   strLit,
   strictEqAbs,
+  string,
   stringOfSymbol,
   stripStringsKeepComments,
   stripTypes,
@@ -493,6 +497,7 @@ import {
   termEquals,
   termToString,
   throwAbsToKinds,
+  throwConstraintToKinds,
   toNumberAbs,
   transpile,
   transpileBodyNode,
@@ -508,12 +513,13 @@ import {
   tryRunTranspiled,
   typeofAbs,
   undefAbs,
+  union,
   unknown,
   ushrAbs,
   v,
   withExecPhi,
   withVar
-} from "./chunk-MJP4P5J3.js";
+} from "./chunk-P6O5BXOA.js";
 
 // src/environment.ts
 function createEnvironment(parent, bindings = /* @__PURE__ */ new Map()) {
@@ -796,6 +802,15 @@ function provesBarePrimDomain(arm, constraint) {
   return arm.shape.k === "prim" && arm.shape.type === constraint.prim;
 }
 function assertImplies(ret, constraint, opts) {
+  if (constraint.lazy) {
+    const seen = opts?.seen;
+    if (seen?.has(constraint.lazy)) {
+      return unprovable("lazy constraint cycle");
+    }
+    const next = seen ? new Set(seen) : /* @__PURE__ */ new Set();
+    next.add(constraint.lazy);
+    return assertImplies(ret, derefConstraint(constraint), { ...opts, seen: next });
+  }
   const phi = opts?.phi ?? pTrue;
   if (ret.shape.k === "never") return proved();
   if (isAnyConstraint(constraint)) return proved();
@@ -881,7 +896,7 @@ function assertImpliesSingle(arm, constraint, opts, phi) {
   return assertScalar(arm, constraint, phi);
 }
 function isAnyConstraint(c) {
-  return !c.prim && c.preds.length === 0 && !c.fields && !c.element && !c.members && !c.fn && !isIntFlag(c);
+  return !c.prim && c.preds.length === 0 && !c.fields && !c.element && !c.members && !c.fn && !c.lazy && !isIntFlag(c);
 }
 function assertShapeFields(ret, constraint, opts) {
   let slots;
@@ -2142,43 +2157,142 @@ function checkSourceInScope(filePath, source, phi, opts) {
   resetAbsCallBudget();
   const prevTrunc = setAbsTruncationCollector((label) => truncated.add(label));
   try {
-    const report = checkSourceInner(
-      filePath,
-      source,
-      file,
-      phi,
-      callOpts,
-      issues,
-      signatures,
-      names,
-      truncated,
-      opts,
-      depsFp,
-      sidecarFp
+    const prevFaceResolver = setContractFaceResolver(
+      makeSameFileFaceResolver(callOpts, filePath, source, file)
     );
-    const diagIssues = sidecarDiagIssues([
-      ...takeRefineDiagsSince(refineSince),
-      ...takeInterfaceDiagsSince(ifaceSince)
-    ]);
-    if (diagIssues.length > 0) {
-      report.issues.push(...diagIssues);
-      const errors = report.issues.filter((i) => i.severity === "error").length;
-      const warnings = report.issues.filter((i) => i.severity === "warning").length;
-      const infos = report.issues.filter((i) => i.severity === "info").length;
-      report.ok = errors === 0;
-      report.summary = {
-        errors,
-        warnings,
-        infos,
-        functions: report.summary.functions
-      };
+    try {
+      attachCrossModuleContractFaces(callOpts, filePath);
+      const report = checkSourceInner(
+        filePath,
+        source,
+        file,
+        phi,
+        callOpts,
+        issues,
+        signatures,
+        names,
+        truncated,
+        opts,
+        depsFp,
+        sidecarFp
+      );
+      const diagIssues = sidecarDiagIssues([
+        ...takeRefineDiagsSince(refineSince),
+        ...takeInterfaceDiagsSince(ifaceSince)
+      ]);
+      if (diagIssues.length > 0) {
+        report.issues.push(...diagIssues);
+        const errors = report.issues.filter((i) => i.severity === "error").length;
+        const warnings = report.issues.filter((i) => i.severity === "warning").length;
+        const infos = report.issues.filter((i) => i.severity === "info").length;
+        report.ok = errors === 0;
+        report.summary = {
+          errors,
+          warnings,
+          infos,
+          functions: report.summary.functions
+        };
+      }
+      if (memoKey) checkMemoSet(memoKey, report, memoPaths);
+      return cloneCheckReport(report);
+    } finally {
+      setContractFaceResolver(prevFaceResolver);
     }
-    if (memoKey) checkMemoSet(memoKey, report, memoPaths);
-    return cloneCheckReport(report);
   } finally {
     setAbsTruncationCollector(prevTrunc);
   }
 }
+function makeSameFileFaceResolver(opts, filePath, source, file) {
+  const loadModule = opts.loadModule;
+  const fromFile = opts.fromFile ?? filePath;
+  const autoBind = opts.autoBind;
+  const projectDir = opts.projectDir;
+  const memo = /* @__PURE__ */ new Map();
+  return (fnName) => {
+    if (memo.has(fnName)) return memo.get(fnName);
+    let faces;
+    try {
+      const eff = effectiveInterface(source, fnName, {
+        ...loadModule ? { loadModule } : {},
+        fromFile,
+        ...autoBind !== void 0 ? { autoBind } : {},
+        ...projectDir !== void 0 ? { projectDir } : {}
+      });
+      if (eff) {
+        const params = extractFn(source, fnName, file)?.params ?? [];
+        faces = contractFacesFromEffectiveInterface(eff, params);
+      }
+    } catch {
+      faces = void 0;
+    }
+    memo.set(fnName, faces);
+    return faces;
+  };
+}
+function attachCrossModuleContractFaces(opts, filePath) {
+  const loadModule = opts.loadModule;
+  const fromFile = opts.fromFile ?? filePath;
+  if (!loadModule) return;
+  const tables = [];
+  for (const t of [opts.modules, opts.inject?.modules]) {
+    if (t && typeof t === "object" && !tables.includes(t)) tables.push(t);
+  }
+  if (tables.length === 0) return;
+  const autoBind = opts.autoBind;
+  const projectDir = opts.projectDir;
+  const facesCache = /* @__PURE__ */ new Map();
+  const facesFor = (depSource, depPath, name, paramNames) => {
+    const key = `${depPath}\0${name}`;
+    if (facesCache.has(key)) return facesCache.get(key);
+    let faces;
+    try {
+      const eff = effectiveInterface(depSource, name, {
+        loadModule,
+        fromFile: depPath,
+        ...autoBind !== void 0 ? { autoBind } : {},
+        ...projectDir !== void 0 ? { projectDir } : {}
+      });
+      if (eff) faces = contractFacesFromEffectiveInterface(eff, paramNames);
+    } catch {
+      faces = void 0;
+    }
+    facesCache.set(key, faces);
+    return faces;
+  };
+  const attachFnAbs = (v2, depSource, depPath, name) => {
+    if (!v2 || typeof v2 !== "object" || !("shape" in v2)) return;
+    const shape2 = v2.shape;
+    if (shape2.k !== "fn") return;
+    let paramNames;
+    try {
+      paramNames = extractFn(depSource, name)?.params ?? [];
+    } catch {
+      paramNames = [];
+    }
+    const faces = facesFor(depSource, depPath, name, paramNames);
+    if (faces) attachContractFaces(v2, faces);
+  };
+  for (const table of tables) {
+    for (const [spec, mod2] of Object.entries(table)) {
+      if (!mod2 || typeof mod2 !== "object") continue;
+      const named = mod2.named;
+      if (!named) continue;
+      let depSource;
+      try {
+        depSource = loadModule(spec, fromFile);
+      } catch {
+        depSource = void 0;
+      }
+      if (!depSource) continue;
+      const depPath = resolveDepPath(fromFile, spec);
+      for (const [name, v2] of Object.entries(named)) {
+        attachFnAbs(v2, depSource, depPath, name);
+      }
+      const def = mod2.default;
+      if (def !== void 0) attachFnAbs(def, depSource, depPath, "default");
+    }
+  }
+}
 function sidecarDiagIssues(diags) {
   const seen = /* @__PURE__ */ new Set();
   const out = [];
@@ -3188,6 +3302,7 @@ export {
   currentExecPhi,
   currentPhi,
   definitelyNotNullishShape,
+  derefConstraint,
   describePhi,
   div,
   drainPromiseMicros,
@@ -3311,6 +3426,7 @@ export {
   joinObjects,
   joinThenProject,
   joinValues,
+  lazy,
   le,
   leNum,
   leavePromiseExecutorScope,

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
-import { I as InterfaceSource, a as InterfaceTierOpts, p as parseSource, C as CheckIssue } from './projection-budget-CtwnzYLG.js';
-export { L as LeakBudget, b as LoadDepsFingerprint, M as MAX_PROMISE_MICROS, P as PROJECTION_MAX_DEPTH, c as ProjectionBudget, d as ProjectionStopReason, e as defaultLeakBudget, f as exceedsBudget, g as exportedNameOfLocal, h as extractAllLoadSpecs, i as getPromiseMicrosLength, l as leakIfNeeded, j as loadModuleDepsFingerprint, m as maybeLeak, n as normPath, r as resetLeakCounter, k as resolveDepPath, s as sidecarSpecsOf, o as stablePathKey, q as stablePathKeyGraph, t as termDepth, u as termNodes } from './projection-budget-CtwnzYLG.js';
+import { I as InterfaceSource, a as InterfaceTierOpts, p as parseSource, C as CheckIssue } from './projection-budget-vi5Ssjdr.js';
+export { L as LeakBudget, b as LoadDepsFingerprint, M as MAX_PROMISE_MICROS, P as PROJECTION_MAX_DEPTH, c as ProjectionBudget, d as ProjectionStopReason, e as defaultLeakBudget, f as exceedsBudget, g as exportedNameOfLocal, h as extractAllLoadSpecs, i as getPromiseMicrosLength, l as leakIfNeeded, j as loadModuleDepsFingerprint, m as maybeLeak, n as normPath, r as resetLeakCounter, k as resolveDepPath, s as sidecarSpecsOf, o as stablePathKey, q as stablePathKeyGraph, t as termDepth, u as termNodes } from './projection-budget-vi5Ssjdr.js';
 import { A as Abs, T as Term, c as AstEnv } from './run-DbDRo5z6.js';
 export { $ as $tryDigestSoft, d as $tryMarkSoft, e as $tryReleaseSoft, E as ERROR_FAMILY, f as EvalFallbackStats, M as MayThrowEffect, g as absLit, h as absNumLit, i as absStrLit, j as allAbsStr, k as clearPureCallMemo, l as clearPureMemo, m as enterEvalCallBudgetSession, n as errorTypeAbs, o as exitEvalCallBudgetSession, p as filterDeclaredThrows, q as filterGateThrows, r as filterIgnoredThrows, s as flushMayThrowEffects, t as formatThrowsAbs, u as getEvalCallBudgetState, v as getEvalFallbackStats, w as getMayThrowCollector, x as isThrowsIgnored, y as mayThrowEffectsToAbs, z as orphanMayThrowEffects, B as popMayThrowFrame, D as pushMayThrowFrame, F as recordMayThrow, G as resetEvalFallbackStats, H as runWithMayThrowSession, I as setMayThrowCollector, J as throwAbsToKinds, K as throwsKindCovered, N as withEvalBudgetOverride } from './run-DbDRo5z6.js';
 import { File, Node } from '@babel/types';

package/dist/internal.js

@@ -21,7 +21,7 @@ import {
   stableAnalyzeKeySource,
   stablePathKey,
   stablePathKeyGraph
-} from "./chunk-45WFXDZD.js";
+} from "./chunk-WT5J6QTZ.js";
 import {
   $tryDigestSoft,
   $tryMarkSoft,
@@ -169,7 +169,7 @@ import {
   withEvalBudgetOverride,
   withFnBudgetOverride,
   wrapPromise
-} from "./chunk-MJP4P5J3.js";
+} from "./chunk-P6O5BXOA.js";
 
 // src/algebra/inlay.ts
 function listFunctions(source) {

package/dist/{projection-budget-CtwnzYLG.d.ts → projection-budget-vi5Ssjdr.d.ts}

@@ -116,6 +116,12 @@ type NudoConstraint = {
     readonly members?: NudoConstraint[];
     /** 一等函数约束（fn() 构建器产出） */
     readonly fn?: NudoFnConstraint;
+    /**
+     * 自引用模板 thunk（issue #120）：侧车以真 JS 执行，thunk 闭包引用的
+     * const 在 derefConstraint 调用时已初始化——递归结构一句声明。
+     * 消费端按 LAZY_TEMPLATE_DEPTH 预算展开；derefConstraint 按 thunk 记忆化。
+     */
+    readonly lazy?: () => NudoConstraint | ConstraintBuilder;
 };
 /** fn(params, returns?, { throws? }) 的一等函数约束形态 */
 type NudoFnConstraint = {
@@ -178,11 +184,34 @@ declare function union(...cs: (NudoConstraint | ConstraintBuilder | number | str
  * 对不含 nullish 的契约（如 number().gt(0)）报 constraint-violated。
  */
 declare function nullable(c: NudoConstraint | ConstraintBuilder | number | string | boolean): ConstraintBuilder;
+/**
+ * lazy(() => constraint)：自引用约束模板（issue #120）。
+ * 侧车以真 JS 执行——thunk 闭包里引用的 const 在 derefConstraint 调用时
+ * 已初始化，递归结构一句声明：
+ *
+ *   export const astNode = shape({
+ *     type: string(),
+ *     object: lazy(() => astNode).optional(),
+ *   });
+ *
+ * 消费端（instantiate / entry Abs / 显示）按 LAZY_TEMPLATE_DEPTH 预算展开，
+ * 预算耗尽的字段位渲染为「缺席槽」——与手写有限层模板同语义，
+ * 守卫递归（`if (node.object == null) …`）在边界处干净剪枝。
+ */
+declare function lazy(thunk: () => NudoConstraint | ConstraintBuilder): ConstraintBuilder;
+/**
+ * 解一层 lazy：调用 thunk 一次、校验产物是约束、toPlainConstraint 归一化，
+ * 并按 thunk 记忆化（重复 deref 同一闭包 → 同一对象）。
+ * 不递归展开——递归层数由消费端的 depth 预算控制。
+ */
+declare function derefConstraint(c: NudoConstraint): NudoConstraint;
 /**
  * 契约域是否包含 nullish（null / undefined）。
  * union 任一成员含 nullish 即含；lit(null)/lit(undefined) 的 eq 谓词识别。
+ * lazy 包装先 deref；环经 seen（thunk 身份）终止——nullish 只出现在
+ * 有限位置，DFS-with-seen 判定可靠，无需层数预算。
  */
-declare function constraintAdmitsNullish(c: NudoConstraint): boolean;
+declare function constraintAdmitsNullish(c: NudoConstraint, seen?: Set<object>): boolean;
 /**
  * fn(params, returns?, { throws? })：一等函数约束。
  * Phase 1 只展示不执法：参数位 instantiate 恒真（pTrue），
@@ -197,11 +226,11 @@ declare function fn(params: Record<string, NudoConstraint | ConstraintBuilder |
  * prim 不一致或任一含 fields/element/members/fn → throw。
  */
 declare function andC(...cs: (NudoConstraint | ConstraintBuilder)[]): ConstraintBuilder;
-/** partial(c)：shape 全字段变可选；非 shape throw */
+/** partial(c)：shape 全字段变可选；非 shape throw（lazy 包装先解一层） */
 declare function partial(c: NudoConstraint | ConstraintBuilder): ConstraintBuilder;
-/** pick(c, keys)：shape 子形状（不存在的 key 忽略）；非 shape throw */
+/** pick(c, keys)：shape 子形状（不存在的 key 忽略）；非 shape throw（lazy 包装先解一层） */
 declare function pick(c: NudoConstraint | ConstraintBuilder, keys: string[]): ConstraintBuilder;
-/** omit(c, keys)：shape 去字段；非 shape throw */
+/** omit(c, keys)：shape 去字段；非 shape throw（lazy 包装先解一层） */
 declare function omit(c: NudoConstraint | ConstraintBuilder, keys: string[]): ConstraintBuilder;
 /**
  * 约束构建器表面名表（单一真源）：case 实参文法、mock 类型表达式识别与
@@ -224,14 +253,14 @@ declare const CONSTRAINT_BUILDER_NAMES: readonly string[];
  * 这类拼接可以借前缀骗过本正则并执行任意 JS。
  */
 declare const CONSTRAINT_EXPR_RE: RegExp;
-/** 把模板绑定到参数名：self → paramName；shape 展开为字段访问 Pred */
-declare function instantiateConstraint(c: NudoConstraint, paramName: string): Pred;
+/** 把模板绑定到参数名：self → paramName；shape 展开为字段访问 Pred（lazy 按 depth 预算展开） */
+declare function instantiateConstraint(c: NudoConstraint, paramName: string, depth?: number): Pred;
 /**
  * 契约 → 函数入口 param Abs（infer/hover 用）。
  * 标量：prim + pred；shape：obj slots 递归；union：成员 joinAbs；
  * fn 形态：一等 fn shape（paramTypes/returnType），供 refine→error / 展示。
  */
-declare function constraintToEntryAbs(c: NudoConstraint, paramName: string): Abs;
+declare function constraintToEntryAbs(c: NudoConstraint, paramName: string, depth?: number): Abs;
 /**
  * fn 约束 → 逐参约束表（interface 推导 / 入口签名消费）。
  * 非 fn() 形态 throw——调用方应先判 c.fn。
@@ -802,4 +831,4 @@ declare class ProjectionBudget {
     exit(): void;
 }
 
-export { array as $, type CheckJson as A, type CheckJsonMulti as B, type CheckIssue as C, type ConstraintBuilder as D, type EffectiveInterfaceOpts as E, type Diagnostic as F, type EffectiveInterface as G, type GitlabCodeQualityIssue as H, type InterfaceSource as I, type InterfaceDiag as J, type InterfaceTierInfo as K, type LeakBudget as L, MAX_PROMISE_MICROS as M, type NudoConstraint as N, type NamedImport as O, PROJECTION_MAX_DEPTH as P, type NudoField as Q, type NudoFnConstraint as R, NudoSidecarError as S, type NudoSig as T, type RefineDiag as U, type RefineEntry as V, type RefineResolveOpts as W, SELF as X, actionsForIssue as Y, andC as Z, any as _, type InterfaceTierOpts as a, takeRefineDiagsSince as a$, boolean as a0, checkArg as a1, checkCall as a2, constraintAdmitsNullish as a3, constraintToEntryAbs as a4, drainPromiseMicros as a5, effectiveInterface as a6, enterPromiseExecutorScope as a7, evalPromiseCtor as a8, evalPromiseMethod as a9, leavePromiseExecutorScope as aA, lenTerm as aB, litC as aC, localNamedExports as aD, notePromiseExecutorFork as aE, nullable as aF, number as aG, omit as aH, partial as aI, pick as aJ, queuePromiseMicro as aK, refineDiagCount as aL, refineToIndexedFull as aM, resetNudoModuleExecCache as aN, resetParseSourceCache as aO, resetSidecarLoadFailureCache as aP, serializeCheckJson as aQ, serializeCheckJsonMulti as aR, setInterfaceDiagCollector as aS, setRefineDiagCollector as aT, shape as aU, sidecarClosureFingerprint as aV, sidecarPathOf as aW, string as aX, takeInterfaceDiags as aY, takeInterfaceDiagsSince as aZ, takeRefineDiags as a_, evalPromiseStatic as aa, execNudoModule as ab, extractDeclaredThrows as ac, extractFnBudget as ad, extractNudoImports as ae, extractRefineReturnFromSource as af, extractRefinesFromSource as ag, fn as ah, fnConstraintToEntryReqs as ai, formatCheckReport as aj, formatConstraint as ak, formatDiagnostics as al, formatEffectiveInterfaceDisplay as am, formatGithubAnnotations as an, formatGitlabCodeQuality as ao, formatInterfaceTierLine as ap, generatedExportNames as aq, getParseSourceCacheSize as ar, getTerm as as, instantiateConstraint as at, interfaceDiagCount as au, interfaceSourceOf as av, interfaceTierOf as aw, isIntFlag as ax, isNodeModulesPath as ay, isNudoConstraint as az, type LoadDepsFingerprint as b, throwConstraintToKinds as b0, union as b1, ProjectionBudget as c, type ProjectionStopReason as d, defaultLeakBudget as e, exceedsBudget as f, exportedNameOfLocal as g, extractAllLoadSpecs as h, getPromiseMicrosLength as i, loadModuleDepsFingerprint as j, resolveDepPath as k, leakIfNeeded as l, maybeLeak as m, normPath as n, stablePathKey as o, parseSource as p, stablePathKeyGraph as q, resetLeakCounter as r, sidecarSpecsOf as s, termDepth as t, termNodes as u, type CheckReport as v, CONSTRAINT_BUILDERS as w, CONSTRAINT_BUILDER_NAMES as x, CONSTRAINT_EXPR_RE as y, type CheckAction as z };
+export { array as $, type CheckJson as A, type CheckJsonMulti as B, type CheckIssue as C, type ConstraintBuilder as D, type EffectiveInterfaceOpts as E, type Diagnostic as F, type EffectiveInterface as G, type GitlabCodeQualityIssue as H, type InterfaceSource as I, type InterfaceDiag as J, type InterfaceTierInfo as K, type LeakBudget as L, MAX_PROMISE_MICROS as M, type NudoConstraint as N, type NamedImport as O, PROJECTION_MAX_DEPTH as P, type NudoField as Q, type NudoFnConstraint as R, NudoSidecarError as S, type NudoSig as T, type RefineDiag as U, type RefineEntry as V, type RefineResolveOpts as W, SELF as X, actionsForIssue as Y, andC as Z, any as _, type InterfaceTierOpts as a, takeInterfaceDiagsSince as a$, boolean as a0, checkArg as a1, checkCall as a2, constraintAdmitsNullish as a3, constraintToEntryAbs as a4, derefConstraint as a5, drainPromiseMicros as a6, effectiveInterface as a7, enterPromiseExecutorScope as a8, evalPromiseCtor as a9, isNudoConstraint as aA, lazy as aB, leavePromiseExecutorScope as aC, lenTerm as aD, litC as aE, localNamedExports as aF, notePromiseExecutorFork as aG, nullable as aH, number as aI, omit as aJ, partial as aK, pick as aL, queuePromiseMicro as aM, refineDiagCount as aN, refineToIndexedFull as aO, resetNudoModuleExecCache as aP, resetParseSourceCache as aQ, resetSidecarLoadFailureCache as aR, serializeCheckJson as aS, serializeCheckJsonMulti as aT, setInterfaceDiagCollector as aU, setRefineDiagCollector as aV, shape as aW, sidecarClosureFingerprint as aX, sidecarPathOf as aY, string as aZ, takeInterfaceDiags as a_, evalPromiseMethod as aa, evalPromiseStatic as ab, execNudoModule as ac, extractDeclaredThrows as ad, extractFnBudget as ae, extractNudoImports as af, extractRefineReturnFromSource as ag, extractRefinesFromSource as ah, fn as ai, fnConstraintToEntryReqs as aj, formatCheckReport as ak, formatConstraint as al, formatDiagnostics as am, formatEffectiveInterfaceDisplay as an, formatGithubAnnotations as ao, formatGitlabCodeQuality as ap, formatInterfaceTierLine as aq, generatedExportNames as ar, getParseSourceCacheSize as as, getTerm as at, instantiateConstraint as au, interfaceDiagCount as av, interfaceSourceOf as aw, interfaceTierOf as ax, isIntFlag as ay, isNodeModulesPath as az, type LoadDepsFingerprint as b, takeRefineDiags as b0, takeRefineDiagsSince as b1, throwConstraintToKinds as b2, union as b3, ProjectionBudget as c, type ProjectionStopReason as d, defaultLeakBudget as e, exceedsBudget as f, exportedNameOfLocal as g, extractAllLoadSpecs as h, getPromiseMicrosLength as i, loadModuleDepsFingerprint as j, resolveDepPath as k, leakIfNeeded as l, maybeLeak as m, normPath as n, stablePathKey as o, parseSource as p, stablePathKeyGraph as q, resetLeakCounter as r, sidecarSpecsOf as s, termDepth as t, termNodes as u, type CheckReport as v, CONSTRAINT_BUILDERS as w, CONSTRAINT_BUILDER_NAMES as x, CONSTRAINT_EXPR_RE as y, type CheckAction as z };

package/package.json

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