@nudojs/core 1.2.2 → 1.3.0

package/dist/index.js

@@ -9,12 +9,14 @@ import {
   buildArgsFromAssume,
   canSkipLiteralCallScan,
   collectAbsFreeVars,
+  constraintAdmitsNullish,
   constraintToEntryAbs,
   effectiveInterface,
   evictGeneralizeMemoForPaths,
   execNudoModule,
   extractDeclaredThrows,
   extractFn,
+  extractFnBudget,
   extractNudoImports,
   extractRefineReturnFromSource,
   extractRefinesFromSource,
@@ -30,6 +32,7 @@ import {
   getTerm,
   hashSource,
   instantiateConstraint,
+  instantiateOnTerm,
   interfaceDiagCount,
   interfaceSourceOf,
   interfaceTierOf,
@@ -44,6 +47,7 @@ import {
   loadModuleDepsFingerprint,
   localNamedExports,
   normPath,
+  nullable,
   number,
   omit,
   partial,
@@ -53,6 +57,7 @@ import {
   resetGeneralizeMemo,
   resetHashSourceCache,
   resetNudoModuleExecCache,
+  resetSidecarLoadFailureCache,
   scanLiteralCalls,
   setInterfaceDiagCollector,
   setRefineDiagCollector,
@@ -67,7 +72,7 @@ import {
   takeRefineDiagsSince,
   throwConstraintToKinds,
   union
-} from "./chunk-TOURNNEA.js";
+} from "./chunk-5YNR4Q7E.js";
 import {
   $add,
   $arguments,
@@ -189,6 +194,8 @@ import {
   NudoThrow,
   NudoUnsupportedError,
   OBJECT_PROTO_METHOD_NAMES,
+  PROMISE_MICRO_ERROR_LABEL,
+  PROMISE_MICRO_OVERFLOW_LABEL,
   RUNTIME_IMPORT_RE,
   TYPEOF_NAMES,
   abs,
@@ -206,10 +213,12 @@ import {
   asAbs,
   asAbsVal,
   assignSourceSlots,
+  assumeFinite,
   attachFnImpl,
   beginCollectionFork,
   betaOf,
   bigintLit,
+  bindImports,
   bindingsOf,
   bitandAbs,
   bitnotAbs,
@@ -228,6 +237,7 @@ import {
   clearCollectionTables,
   clearStaleTermPred,
   cmp,
+  collectAbsExports,
   collectionElementJoin,
   collectionExactLen,
   confJoin,
@@ -275,6 +285,7 @@ import {
   foldRequireSpecArg,
   foldStaticStringExpr,
   formalParamDisplayNames,
+  formalParamSignatureNames,
   formalParamsFromNodes,
   formatAbs,
   formatAbsMultiline,
@@ -295,6 +306,7 @@ import {
   gt,
   gtNum,
   hostBuiltinCtorName,
+  identBoundaryRegex,
   implies,
   instantiateReturn,
   isArrMutator,
@@ -357,6 +369,7 @@ import {
   migrateNullProto,
   mod,
   mul,
+  namespaceAbsOf,
   namespaceNameOf,
   ne,
   negAbs,
@@ -438,6 +451,7 @@ import {
   strLit,
   strictEqAbs,
   stringOfSymbol,
+  stripStringsKeepComments,
   stripTypes,
   sub,
   substAbs,
@@ -470,7 +484,7 @@ import {
   v,
   withExecPhi,
   withVar
-} from "./chunk-4V3CRVSD.js";
+} from "./chunk-CKH6GQAI.js";
 
 // src/environment.ts
 function createEnvironment(parent, bindings = /* @__PURE__ */ new Map()) {
@@ -703,6 +717,252 @@ function formatDiagnostics(diags) {
   }).join("\n");
 }
 
+// src/algebra/postcondition.ts
+function proved() {
+  return { status: "proved" };
+}
+function disproved(reason) {
+  return { status: "disproved", reason };
+}
+function unprovable(reason) {
+  return { status: "unprovable", reason };
+}
+var RET_ANCHOR = "__nudo_return__";
+function retAnchorTerm(ret) {
+  return ret.term ?? v(RET_ANCHOR);
+}
+function isValueSetUnknown(ret) {
+  if (ret.conf === "opaque" || ret.conf === "widened" || ret.conf === "mock") {
+    return true;
+  }
+  if (ret.shape.k === "unknown" && !ret.term) return true;
+  if (ret.shape.k === "any") return true;
+  return false;
+}
+function isBoundedEvidenceMissing(ret, constraint) {
+  if (constraint.preds.length === 0 && !constraint.members) return false;
+  if (ret.term?.op === "lit") return false;
+  if (ret.pred && ret.pred.op !== "true") return false;
+  return true;
+}
+function assertImplies(ret, constraint, opts) {
+  const phi = opts?.phi ?? pTrue;
+  if (ret.shape.k === "never") return proved();
+  if (isAnyConstraint(constraint)) return proved();
+  const nullishOk = constraintAdmitsNullish(constraint);
+  if (isNullishLitAbs(ret)) {
+    return nullishOk ? proved() : disproved(`nullish return \u22AD ${formatConstraint(constraint)}`);
+  }
+  let sumMembers;
+  if (ret.shape.k === "sum") {
+    const members = ret.shape.members;
+    const nullishMembers = members.filter((m) => isNullishLitAbs(m));
+    if (nullishMembers.length > 0 && !nullishOk) {
+      return disproved(
+        `nullish return arm \u22AD ${formatConstraint(constraint)} (contract does not admit nullish)`
+      );
+    }
+    sumMembers = members.filter((m) => !isNullishLitAbs(m));
+  }
+  if (isValueSetUnknown(ret)) {
+    return unprovable(
+      ret.shape.k === "any" ? "any does not establish the return contract" : "inference failure (unknown/opaque) \u2014 cannot prove the return contract"
+    );
+  }
+  if (constraint.members && constraint.members.length > 0) {
+    let sawUnprovable = false;
+    for (const m of constraint.members) {
+      const r = assertImplies(ret, m, opts);
+      if (r.status === "proved") return proved();
+      if (r.status === "unprovable") sawUnprovable = true;
+    }
+    return sawUnprovable ? unprovable("union: no member proved the return contract") : disproved(`return \u22AD union(${constraint.members.map((m) => formatConstraint(m)).join(", ")})`);
+  }
+  if (sumMembers && constraint.fields) {
+    let sawUnprovable = false;
+    for (const m of sumMembers) {
+      if (isValueSetUnknown(m)) continue;
+      const r = assertImplies(m, constraint, opts);
+      if (r.status === "disproved") return r;
+      if (r.status === "unprovable") sawUnprovable = true;
+    }
+    return sawUnprovable ? unprovable("sum: some arms unprovable") : proved();
+  }
+  if (constraint.fields) {
+    return assertShapeFields(ret, constraint, opts);
+  }
+  if (constraint.element) {
+    if (ret.shape.k !== "arr" && ret.shape.k !== "tuple") {
+      return disproved(`return shape ${ret.shape.k} \u22AD array(...)`);
+    }
+    return proved();
+  }
+  if (constraint.fn) return proved();
+  return assertScalar(ret, constraint, phi);
+}
+function isAnyConstraint(c) {
+  return !c.prim && c.preds.length === 0 && !c.fields && !c.element && !c.members && !c.fn && !isIntFlag(c);
+}
+function assertShapeFields(ret, constraint, opts) {
+  let slots;
+  if (ret.shape.k === "obj") {
+    slots = ret.shape.slots;
+  } else if (ret.shape.k === "brand") {
+    const inner = ret.shape.shape;
+    if (inner.shape.k === "obj") slots = inner.shape.slots;
+  }
+  if (!slots) {
+    return disproved(`return shape ${ret.shape.k} \u22AD object shape`);
+  }
+  for (const [key, field] of Object.entries(constraint.fields)) {
+    const slot = getSlot(slots, key);
+    if (!slot) {
+      if (!field.optional && !field.constraint.isOptional) {
+        return disproved(`missing field ${key}`);
+      }
+      continue;
+    }
+    const r = assertImplies(slot.value, field.constraint, opts);
+    if (r.status === "disproved") {
+      return disproved(`field ${key}: ${r.reason}`);
+    }
+    if (r.status === "unprovable") {
+      return unprovable(`field ${key}: ${r.reason}`);
+    }
+  }
+  return proved();
+}
+function assertScalar(ret, constraint, phi) {
+  if (constraint.prim) {
+    const retPrim = primOfAbs(ret);
+    if (retPrim && retPrim !== constraint.prim) {
+      return disproved(`typeof return = "${retPrim}" \u22AD "${constraint.prim}"`);
+    }
+    if (!retPrim && ret.shape.k !== "sum" && ret.shape.k !== "never") {
+    }
+  }
+  if (isIntFlag(constraint) && constraint.prim === "number") {
+    const lv2 = litValue(ret);
+    if (typeof lv2 === "number" && !Number.isInteger(lv2)) {
+      return disproved(`return ${lv2} \u22AD int`);
+    }
+  }
+  const t = retAnchorTerm(ret);
+  const constraintPred = instantiateOnTerm(constraint, t);
+  const retPred = ret.pred && ret.pred.op !== "true" ? phi.op === "true" ? ret.pred : and(phi, ret.pred) : phi;
+  if (constraint.preds.length === 0 && constraintPred.op === "true") {
+    return proved();
+  }
+  if (constraint.preds.length === 0 && constraintPred.op === "typeof" && constraint.prim) {
+    return proved();
+  }
+  if (constraintPred.op !== "true") {
+    if (implies(retPred, constraintPred)) return proved();
+    if (ret.pred && ret.pred.op !== "true" && numericBoundsImplyLocal(ret.pred, constraintPred)) {
+      return proved();
+    }
+    if (isBoundedEvidenceMissing(ret, constraint)) {
+      return unprovable(
+        `cannot prove return satisfies ${formatConstraint(constraint)} (no bound evidence on the return value)`
+      );
+    }
+  }
+  const lv = litValue(ret);
+  if (lv !== void 0 && (typeof lv === "number" || typeof lv === "string" || typeof lv === "boolean" || lv === null)) {
+    if (literalMeetsConstraint(lv, constraint)) {
+      return proved();
+    }
+    const boundDesc = describeBoundViolation(lv, constraint);
+    return disproved(
+      boundDesc ?? `return ${JSON.stringify(lv)} \u22AD ${formatConstraint(constraint)}`
+    );
+  }
+  if (ret.term?.op === "lit" && ret.term.value === void 0) {
+    return proved();
+  }
+  if (constraintPred.op !== "true" || constraint.preds.length > 0) {
+    if (isBoundedEvidenceMissing(ret, constraint)) {
+      return unprovable(
+        `cannot prove return satisfies ${formatConstraint(constraint)} (no bound evidence on the return value)`
+      );
+    }
+    return disproved(
+      `return (${formatAbs(ret)}) \u22AD ${formatConstraint(constraint)} (postcondition not implied)`
+    );
+  }
+  return proved();
+}
+function numericBoundsImplyLocal(src, tgt) {
+  const one = (p) => p.op === "gt" || p.op === "ge" || p.op === "lt" || p.op === "le";
+  if (!one(src) || !one(tgt)) return false;
+  if (src.op !== tgt.op) {
+    if (src.op === "gt" && tgt.op === "ge") {
+      return sameTermSide(src, tgt) && litGE(src.b, tgt.b);
+    }
+    if (src.op === "lt" && tgt.op === "le") {
+      return sameTermSide(src, tgt) && litLE(src.b, tgt.b);
+    }
+    return false;
+  }
+  if (!sameTermSide(src, tgt)) return false;
+  const sb = src.b.op === "lit" ? src.b.value : void 0;
+  const tb = tgt.b.op === "lit" ? tgt.b.value : void 0;
+  if (typeof sb !== "number" || typeof tb !== "number") return false;
+  if (src.op === "gt" || src.op === "ge") return sb >= tb;
+  return sb <= tb;
+}
+function sameTermSide(a, b) {
+  return a.a.op === b.a.op && termEquals(a.a, b.a);
+}
+function litGE(a, b) {
+  if (a.op !== "lit" || b.op !== "lit") return false;
+  return typeof a.value === "number" && typeof b.value === "number" && a.value >= b.value;
+}
+function litLE(a, b) {
+  if (a.op !== "lit" || b.op !== "lit") return false;
+  return typeof a.value === "number" && typeof b.value === "number" && a.value <= b.value;
+}
+function primOfAbs(a) {
+  if (a.shape.k === "prim") return a.shape.type;
+  const lv = litValue(a);
+  if (typeof lv === "number") return "number";
+  if (typeof lv === "string") return "string";
+  if (typeof lv === "boolean") return "boolean";
+  if (typeof lv === "bigint") return "bigint";
+  return void 0;
+}
+function describeBoundViolation(lv, constraint) {
+  const opSym = { gt: ">", ge: "\u2265", lt: "<", le: "\u2264" };
+  for (const p of constraint.preds) {
+    for (const atom of p.op === "and" ? p.args : [p]) {
+      if (atom.op !== "gt" && atom.op !== "ge" && atom.op !== "lt" && atom.op !== "le") continue;
+      if (atom.b.op !== "lit" || typeof atom.b.value !== "number") continue;
+      const n = atom.b.value;
+      const sym = opSym[atom.op];
+      if (typeof lv === "number") {
+        let ok = true;
+        if (atom.op === "gt") ok = lv > n;
+        if (atom.op === "ge") ok = lv >= n;
+        if (atom.op === "lt") ok = lv < n;
+        if (atom.op === "le") ok = lv <= n;
+        if (!ok) return `return ${sym} ${n}`;
+      }
+      if (typeof lv === "string" && isLengthSelfTerm(atom.a)) {
+        let ok = true;
+        if (atom.op === "gt") ok = lv.length > n;
+        if (atom.op === "ge") ok = lv.length >= n;
+        if (atom.op === "lt") ok = lv.length < n;
+        if (atom.op === "le") ok = lv.length <= n;
+        if (!ok) return `length(self) ${sym} ${n}`;
+      }
+    }
+  }
+  return void 0;
+}
+function isLengthSelfTerm(t) {
+  return t.op === "app" && t.fn === "length" && t.args.length === 1 && t.args[0].op === "var" && t.args[0].id === SELF;
+}
+
 // src/algebra/projection.ts
 var PROJECTABLE_CONF = /* @__PURE__ */ new Set(["exact", "path"]);
 var ARR_FALLBACK_CONF = /* @__PURE__ */ new Set([
@@ -1137,8 +1397,9 @@ function estimateEntryParamCount(source, fnName, file) {
     }
   } catch {
   }
+  const name = identBoundaryRegex(fnName);
   const re = new RegExp(
-    `(?:function\\s+${fnName}\\s*\\(([^)]*)\\)|${fnName}\\s*=\\s*(?:async\\s*)?function(?:\\s+${fnName})?\\s*\\(([^)]*)\\)|${fnName}\\s*=\\s*(?:async\\s*)?\\(([^)]*)\\)\\s*=>)`
+    `(?:function\\s+${name}\\s*\\(([^)]*)\\)|${name}\\s*=\\s*(?:async\\s*)?function(?:\\s+${name})?\\s*\\(([^)]*)\\)|${name}\\s*=\\s*(?:async\\s*)?\\(([^)]*)\\)\\s*=>)`
   );
   const m = re.exec(source);
   if (m) {
@@ -1149,13 +1410,15 @@ function estimateEntryParamCount(source, fnName, file) {
   return 1;
 }
 function isDefaultExportName(source, fnName) {
+  const name = identBoundaryRegex(fnName);
   const re = new RegExp(
-    `export\\s+default\\s+(?:async\\s+)?(?:function\\s+${fnName}\\b|${fnName}\\b)`
+    `export\\s+default\\s+(?:async\\s+)?(?:function\\s+${name}|${name})`
   );
   return re.test(source);
 }
 function formatEntrySigLine(name, g, throws) {
-  const ps = g.params.map((p, i) => {
+  const names = g.formals && g.formals.length > 0 ? formalParamSignatureNames(g.formals) : g.params;
+  const ps = names.map((p, i) => {
     const t = g.typeParams[i]?.value;
     const shown = !t ? "any" : t.shape.k === "unknown" ? "unknown" : formatShape(t);
     return `${p}: ${shown}`;
@@ -1219,6 +1482,7 @@ function resetCheckSourceMemo() {
   checkKeyDeps.clear();
   checkDepIndex.clear();
   resetHashSourceCache();
+  resetSidecarLoadFailureCache();
 }
 function loadModuleId(fn2) {
   if (!fn2) return 0;
@@ -1525,8 +1789,9 @@ function projectCaseArgField(arg, field) {
 }
 function scanCaseInconsistency(source, knownFns, opts) {
   const out = [];
-  if (!source.includes("@nudo:case")) return out;
-  const hasContractOrigin = source.includes("@nudo:contract") || source.includes("@nudo:contract") || opts.sidecarPresent === true;
+  const directiveSrc = stripStringsKeepComments(source);
+  if (!directiveSrc.includes("@nudo:case")) return out;
+  const hasContractOrigin = directiveSrc.includes("@nudo:contract") || opts.sidecarPresent === true;
   if (!hasContractOrigin) return out;
   const file = opts.file ?? parseSource(source);
   const parseLitArg = (s) => {
@@ -1749,6 +2014,7 @@ function checkSource(filePath, source, phi = pTrue, opts = {}) {
   }
   setRefineDiagCollector(null);
   setInterfaceDiagCollector(null);
+  resetSidecarLoadFailureCache();
   const refineSince = refineDiagCount();
   const ifaceSince = interfaceDiagCount();
   const useMemo = phi.op === "true";
@@ -1824,7 +2090,7 @@ function sidecarDiagIssues(diags) {
   return out;
 }
 function checkSourceInner(filePath, source, file, phi, opts, issues, signatures, names, truncated, identityOpts = opts, depsFp, sidecarFp) {
-  const hasRefineDirective = source.includes("@nudo:contract") || source.includes("@nudo:contract");
+  const hasRefineDirective = stripStringsKeepComments(source).includes("@nudo:contract");
   const exportedNames = sidecarFp !== void 0 ? localNamedExports(source) : void 0;
   const entryNames = localNamedExports(source);
   const entryThrowsMode = opts.entryThrows ?? "error";
@@ -1889,7 +2155,7 @@ function checkSourceInner(filePath, source, file, phi, opts, issues, signatures,
           eff.returns.constraint,
           declared
         );
-        if (retIssues.length > 0) returnViolated.add(name);
+        if (retIssues.some((i) => i.severity === "error")) returnViolated.add(name);
         issues.push(...retIssues);
       }
       continue;
@@ -1935,7 +2201,7 @@ function checkSourceInner(filePath, source, file, phi, opts, issues, signatures,
             message: `${name} (export): may throw ${gateDisplay}`,
             actual: `${name}(\u2026)    throws ${gateDisplay}`,
             expected: "entry total, or @nudo:throws / try-catch",
-            suggestion: first.cause ? `${first.cause} \u2192 ${first.kind === "ReferenceError" ? "re-export `export { x } from` \u4E0D\u662F\u5C40\u90E8\u7ED1\u5B9A\u2014\u2014\u6539 `import { x }` / @nudo:throws ReferenceError" : `@nudo:throws ${first.kind} / refine / guard / try-catch`}` : first.kind === "ReferenceError" ? "re-export `export { x } from` \u4E0D\u662F\u5C40\u90E8\u7ED1\u5B9A\u2014\u2014\u6539 `import { x }` / @nudo:throws ReferenceError" : `@nudo:throws ${first.kind} / refine / guard / try-catch`,
+            suggestion: first.cause ? `${first.cause} \u2192 ${first.kind === "ReferenceError" ? "re-export `export { x } from` \u4E0D\u662F\u5C40\u90E8\u7ED1\u5B9A\u2014\u2014\u6539 `import { x }` / @nudo:throws ReferenceError" : `@nudo:throws ${first.kind} / sidecar fn({ \u2026 }) contract / refine / guard / try-catch`}` : first.kind === "ReferenceError" ? "re-export `export { x } from` \u4E0D\u662F\u5C40\u90E8\u7ED1\u5B9A\u2014\u2014\u6539 `import { x }` / @nudo:throws ReferenceError" : `@nudo:throws ${first.kind} / sidecar fn({ \u2026 }) contract / refine / guard / try-catch`,
             fn: name,
             ...loc.line !== void 0 ? { line: loc.line } : {},
             ...loc.column !== void 0 ? { column: loc.column } : {}
@@ -1980,7 +2246,7 @@ function checkSourceInner(filePath, source, file, phi, opts, issues, signatures,
           message: `${name} (export): may throw ${gateDisplay}`,
           actual: `${formatEntrySigLine(name, g, gateDisplay)}`,
           expected: "entry total, or @nudo:throws / try-catch",
-          suggestion: first.cause ? `${first.cause} \u2192 ${first.kind === "ReferenceError" ? "re-export `export { x } from` \u4E0D\u662F\u5C40\u90E8\u7ED1\u5B9A\u2014\u2014\u6539 `import { x }` / @nudo:throws ReferenceError" : `@nudo:throws ${first.kind} / refine / guard / try-catch`}` : first.kind === "ReferenceError" ? "re-export `export { x } from` \u4E0D\u662F\u5C40\u90E8\u7ED1\u5B9A\u2014\u2014\u6539 `import { x }` / @nudo:throws ReferenceError" : `@nudo:throws ${first.kind} / refine / guard / try-catch`,
+          suggestion: first.cause ? `${first.cause} \u2192 ${first.kind === "ReferenceError" ? "re-export `export { x } from` \u4E0D\u662F\u5C40\u90E8\u7ED1\u5B9A\u2014\u2014\u6539 `import { x }` / @nudo:throws ReferenceError" : `@nudo:throws ${first.kind} / sidecar fn({ \u2026 }) contract / refine / guard / try-catch`}` : first.kind === "ReferenceError" ? "re-export `export { x } from` \u4E0D\u662F\u5C40\u90E8\u7ED1\u5B9A\u2014\u2014\u6539 `import { x }` / @nudo:throws ReferenceError" : `@nudo:throws ${first.kind} / sidecar fn({ \u2026 }) contract / refine / guard / try-catch`,
           fn: name,
           ...loc.line !== void 0 ? { line: loc.line } : {},
           ...loc.column !== void 0 ? { column: loc.column } : {}
@@ -1998,7 +2264,8 @@ function checkSourceInner(filePath, source, file, phi, opts, issues, signatures,
     });
     signatures.push({
       name,
-      params: g.params,
+      // 解构形参展示 `{ grade, findings }`，不落 `_p0`（#64：契约要上屏）
+      params: g.formals && g.formals.length > 0 ? formalParamSignatureNames(g.formals) : g.params,
       paramTypes,
       abs: g.symbolic,
       display: throwsDisplay ? `${fmt.display} throws ${throwsDisplay}` : fmt.display,
@@ -2078,7 +2345,7 @@ function checkSourceInner(filePath, source, file, phi, opts, issues, signatures,
           eff.returns.constraint,
           g.symbolic
         );
-        if (retIssues.length > 0) returnViolated.add(name);
+        if (retIssues.some((i) => i.severity === "error")) returnViolated.add(name);
         issues.push(...retIssues);
       }
       if (eff && eff.source === "generated") {
@@ -2105,7 +2372,25 @@ function checkSourceInner(filePath, source, file, phi, opts, issues, signatures,
         severity: "info",
         code: "nudo:fork-truncated",
         message: `Branch expansion was truncated (fork budget); affected results widened to unknown#opaque (budget)`,
-        suggestion: "optional: simplify branching or raise nudo.analysis.maxForks \u2014 non-blocking"
+        suggestion: "optional: raise nudo.analysis.maxForks, or @nudo:budget forks=\u2026 on the function \u2014 non-blocking"
+      });
+      continue;
+    }
+    if (label === PROMISE_MICRO_OVERFLOW_LABEL) {
+      issues.push({
+        severity: "info",
+        code: "nudo:promise-micro-truncated",
+        message: `Promise microtask queue hit its hard cap; further then/catch callbacks were dropped (results stay fail-closed)`,
+        suggestion: "optional: reduce top-level Promise.then fan-out \u2014 non-blocking"
+      });
+      continue;
+    }
+    if (label === PROMISE_MICRO_ERROR_LABEL) {
+      issues.push({
+        severity: "info",
+        code: "nudo:promise-micro-error",
+        message: `A promise microtask threw while draining; the error was recorded and did not rewrite the synchronous return value`,
+        suggestion: "optional: inspect the then/catch callback for a throw path \u2014 non-blocking"
       });
       continue;
     }
@@ -2124,7 +2409,7 @@ function checkSourceInner(filePath, source, file, phi, opts, issues, signatures,
       severity: "info",
       code: "nudo:recursion-truncated",
       message: `Recursive evaluation of '${label}' was truncated (depth/size budget); result widened to unknown#opaque (budget \u2014 not inference debt)`,
-      suggestion: "narrow the recursion base case or declare an explicit @nudo:contract return contract",
+      suggestion: "raise the function budget with @nudo:budget calls=\u2026 depth=\u2026 (or narrow the recursion base case / declare @nudo:contract return)",
       fn: label
     });
   }
@@ -2187,7 +2472,7 @@ function checkSourceInner(filePath, source, file, phi, opts, issues, signatures,
         rc.constraint,
         rec.result
       );
-      if (retIssues.length > 0) returnViolated.add(rec.fnName);
+      if (retIssues.some((i) => i.severity === "error")) returnViolated.add(rec.fnName);
       issues.push(...retIssues);
     }
   }
@@ -2246,118 +2531,33 @@ function checkSourceInner(filePath, source, file, phi, opts, issues, signatures,
   };
 }
 function checkReturnConstraint(fnName, cName, constraint, ret) {
-  const out = [];
-  if (ret.shape.k === "unknown" && !ret.term) return out;
-  if (ret.shape.k === "any") return out;
-  if (isNullishLitAbs(ret)) return out;
-  if (ret.shape.k === "sum" && constraint.fields) {
-    const seen = /* @__PURE__ */ new Set();
-    for (const m of ret.shape.members) {
-      for (const issue of checkReturnConstraint(fnName, cName, constraint, m)) {
-        const key = `${issue.message}\0${issue.actual ?? ""}\0${issue.expected ?? ""}`;
-        if (seen.has(key)) continue;
-        seen.add(key);
-        out.push(issue);
-      }
-    }
-    return out;
-  }
-  const push = (actual, expected, suggestion) => {
-    out.push({
-      severity: "error",
-      code: "nudo:constraint-violated",
+  const proof = assertImplies(ret, constraint);
+  if (proof.status === "proved") return [];
+  const push = (severity, actual, expected, suggestion) => [
+    {
+      severity,
+      code: severity === "error" ? "nudo:constraint-violated" : "nudo:unproven-return",
       message: `${fnName}: return value \u22AD @nudo:contract return ${cName}`,
       actual,
       expected,
       suggestion,
       fn: fnName
-    });
-  };
-  if (constraint.fields) {
-    const slots = ret.shape.k === "obj" ? ret.shape.slots : void 0;
-    if (!slots) {
-      if (ret.shape.k !== "never") {
-        push(formatAbs(ret), `object shape (${cName})`, `return an object satisfying the ${cName} shape`);
-      }
-      return out;
     }
-    for (const [key, field] of Object.entries(constraint.fields)) {
-      const slot = getSlot(slots, key);
-      if (!slot) {
-        if (!field.optional && !field.constraint.isOptional) {
-          push(formatAbs(ret), `missing field ${key}`, `add the missing field ${key} to the return value`);
-        }
-        continue;
-      }
-      if (field.constraint.prim && slot.value.shape.k === "prim") {
-        const actualPrim = slot.value.shape.type;
-        if (actualPrim !== field.constraint.prim) {
-          push(
-            formatAbs(slot.value),
-            `typeof ${key} = "${field.constraint.prim}"`,
-            `change the return value's ${key} to ${field.constraint.prim}`
-          );
-          continue;
-        }
-      }
-      const lv2 = litValue(slot.value);
-      if (lv2 !== void 0 && typeof lv2 === "number") {
-        for (const p of field.constraint.preds) {
-          const flat = p.op === "and" ? p.args : [p];
-          for (const atom of flat) {
-            if ((atom.op === "gt" || atom.op === "ge" || atom.op === "lt" || atom.op === "le") && atom.b.op === "lit" && typeof atom.b.value === "number") {
-              const n = atom.b.value;
-              let ok = true;
-              if (atom.op === "gt") ok = lv2 > n;
-              if (atom.op === "ge") ok = lv2 >= n;
-              if (atom.op === "lt") ok = lv2 < n;
-              if (atom.op === "le") ok = lv2 <= n;
-              if (!ok) {
-                const opSym = { gt: ">", ge: "\u2265", lt: "<", le: "\u2264" }[atom.op];
-                push(
-                  formatAbs(slot.value),
-                  `${key} ${opSym} ${n}`,
-                  `the return value's ${key} should satisfy ${key} ${opSym} ${n}`
-                );
-              }
-            }
-          }
-        }
-      }
-    }
-    return out;
-  }
-  if (constraint.prim && ret.shape.k === "prim") {
-    const actualPrim = ret.shape.type;
-    if (actualPrim !== constraint.prim) {
-      push(formatAbs(ret), `typeof return = "${constraint.prim}"`, `return ${constraint.prim}`);
-      return out;
-    }
-  }
-  const lv = litValue(ret);
-  if (lv !== void 0 && typeof lv === "number") {
-    for (const p of constraint.preds) {
-      const flat = p.op === "and" ? p.args : [p];
-      for (const atom of flat) {
-        if ((atom.op === "gt" || atom.op === "ge" || atom.op === "lt" || atom.op === "le") && atom.b.op === "lit" && typeof atom.b.value === "number") {
-          const n = atom.b.value;
-          let ok = true;
-          if (atom.op === "gt") ok = lv > n;
-          if (atom.op === "ge") ok = lv >= n;
-          if (atom.op === "lt") ok = lv < n;
-          if (atom.op === "le") ok = lv <= n;
-          if (!ok) {
-            const opSym = { gt: ">", ge: "\u2265", lt: "<", le: "\u2264" }[atom.op];
-            push(formatAbs(ret), `return ${opSym} ${n}`, `return a value satisfying ${opSym} ${n}`);
-          }
-        }
-      }
-    }
-  }
-  if (lv !== void 0 && (typeof lv === "number" || typeof lv === "string" || typeof lv === "boolean") && ((constraint.members?.length ?? 0) > 0 || constraint.preds.some((p) => p.op === "eq") || typeof lv === "string" && constraint.preds.length > 0) && !literalMeetsConstraint(lv, constraint)) {
-    push(formatAbs(ret), formatConstraint(constraint), `return a value satisfying ${formatConstraint(constraint)}`);
+  ];
+  if (proof.status === "disproved") {
+    return push(
+      "error",
+      formatAbs(ret),
+      proof.reason,
+      proof.reason.includes("nullish") ? `use nullable(${formatConstraint(constraint)}) or union(..., lit(null)) to allow nullish returns` : `return a value satisfying ${formatConstraint(constraint)}`
+    );
   }
-  return out;
+  return push(
+    "warning",
+    formatAbs(ret),
+    formatConstraint(constraint),
+    `${proof.reason}; add a precondition, narrow the return expression, or relax the return contract`
+  );
 }
 
 // src/algebra/check-report.ts
@@ -2393,6 +2593,12 @@ function actionsForIssue(i) {
       ];
     case "nudo:entry-may-throw":
       return [
+        {
+          kind: "draft",
+          command: "nudo contract --draft",
+          label: "narrow the entry with a sidecar fn({ \u2026 }) param contract \u2014 most honest fix for helpers (also tightens the signature)",
+          ...i.fn ? { hint: i.fn } : {}
+        },
         {
           kind: "relax",
           label: "declare intentional fail-fast: @nudo:throws Error (or case `!! throws`)",
@@ -2406,8 +2612,7 @@ function actionsForIssue(i) {
           kind: "ignore-throws",
           command: "nudo check --ignore-throws TypeError",
           label: "migration switch: ignore this throw class on L2"
-        },
-        draft
+        }
       ];
     case "nudo:unknown-inference":
     case "nudo:opaque-result":
@@ -2424,10 +2629,12 @@ function actionsForIssue(i) {
       ];
     case "nudo:fork-truncated":
     case "nudo:recursion-truncated":
+    case "nudo:promise-micro-truncated":
+    case "nudo:promise-micro-error":
       return [
         {
           kind: "info",
-          label: "results widened to unknown \u2014 raise budget or narrow control flow"
+          label: "results widened to unknown \u2014 raise budget (@nudo:budget forks/calls/depth on the function) or narrow control flow"
         }
       ];
     case "nudo:host-effect-blocked":
@@ -2661,107 +2868,6 @@ function formatGitlabCodeQuality(r, opts = {}) {
     };
   });
 }
-
-// src/algebra/abs-modules.ts
-function bindImports(node, env, modules) {
-  const mod2 = modules[node.source.value];
-  if (!mod2) {
-    for (const s of node.specifiers) {
-      env.vars.set(s.local.name, unknown);
-    }
-    return;
-  }
-  for (const s of node.specifiers) {
-    if (s.type === "ImportDefaultSpecifier") {
-      env.vars.set(s.local.name, mod2.default ?? unknown);
-    } else if (s.type === "ImportSpecifier") {
-      const imported = s.imported.type === "Identifier" ? s.imported.name : String(s.imported);
-      env.vars.set(s.local.name, mod2.named[imported] ?? unknown);
-    } else if (s.type === "ImportNamespaceSpecifier") {
-      const slots = {};
-      for (const [k, v2] of Object.entries(mod2.named)) slots[k] = { value: v2 };
-      if (mod2.default) slots["default"] = { value: mod2.default };
-      env.vars.set(s.local.name, obj(slots));
-    }
-  }
-}
-function fnToAbs(env, name) {
-  const impl = env.fns.get(name);
-  if (!impl) return void 0;
-  return absFunction(impl.params, {
-    body: impl.body,
-    async: impl.async,
-    env
-  });
-}
-function lookupExport(env, name) {
-  if (env.vars.has(name)) return env.vars.get(name);
-  return fnToAbs(env, name);
-}
-function collectAbsExports(file, env, modules) {
-  const named = {};
-  let defaultExport;
-  for (const stmt of file.program.body) {
-    if (stmt.type === "ExportNamedDeclaration") {
-      if (stmt.source && modules) {
-        const mod2 = modules[stmt.source.value];
-        if (mod2) {
-          for (const spec of stmt.specifiers) {
-            if (spec.type !== "ExportSpecifier") continue;
-            const local = spec.local.type === "Identifier" ? spec.local.name : spec.local.value;
-            const exported = spec.exported.type === "Identifier" ? spec.exported.name : spec.exported.value;
-            const v2 = local === "default" ? mod2.default : mod2.named[local];
-            if (v2 === void 0) continue;
-            if (exported === "default") defaultExport = v2;
-            else named[exported] = v2;
-          }
-        }
-        continue;
-      }
-      const decl = stmt.declaration;
-      if (decl) {
-        if (decl.type === "FunctionDeclaration" && decl.id) {
-          const v2 = lookupExport(env, decl.id.name);
-          if (v2) named[decl.id.name] = v2;
-        } else if (decl.type === "ClassDeclaration" && decl.id) {
-          const v2 = lookupExport(env, decl.id.name);
-          if (v2) named[decl.id.name] = v2;
-        } else if (decl.type === "VariableDeclaration") {
-          for (const d of decl.declarations) {
-            if (d.id.type === "Identifier") {
-              const v2 = lookupExport(env, d.id.name);
-              if (v2) named[d.id.name] = v2;
-            }
-          }
-        }
-      }
-      for (const spec of stmt.specifiers) {
-        if (spec.type !== "ExportSpecifier") continue;
-        const local = spec.local.type === "Identifier" ? spec.local.name : spec.local.value;
-        const exported = spec.exported.type === "Identifier" ? spec.exported.name : spec.exported.value;
-        const v2 = lookupExport(env, local);
-        if (v2) named[exported] = v2;
-      }
-    } else if (stmt.type === "ExportAllDeclaration" && stmt.source && modules) {
-      const mod2 = modules[stmt.source.value];
-      if (mod2?.named) {
-        for (const [k, v2] of Object.entries(mod2.named)) named[k] = v2;
-      }
-    } else if (stmt.type === "ExportDefaultDeclaration") {
-      const d = stmt.declaration;
-      if (d.type === "FunctionDeclaration") {
-        defaultExport = lookupExport(env, d.id ? d.id.name : "default");
-      } else if (d.type === "ClassDeclaration" && d.id) {
-        defaultExport = lookupExport(env, d.id.name);
-      } else if (d.type === "Identifier") {
-        defaultExport = lookupExport(env, d.name);
-      }
-    }
-  }
-  const result = { named };
-  if (defaultExport) result.default = defaultExport;
-  return result;
-}
 export {
   $add,
   $arguments,
@@ -2905,6 +3011,7 @@ export {
   asAbs,
   asAbsVal,
   assignSourceSlots,
+  assumeFinite,
   attachFnImpl,
   beginCollectionFork,
   betaOf,
@@ -2938,6 +3045,7 @@ export {
   collectionElementJoin,
   collectionExactLen,
   confJoin,
+  constraintAdmitsNullish,
   constraintToEntryAbs,
   contractParamNameSet,
   createEnvironment,
@@ -2984,6 +3092,7 @@ export {
   extStateOf,
   extractDeclaredThrows,
   extractFn,
+  extractFnBudget,
   extractNudoImports,
   extractRefineReturnFromSource,
   extractRefinesFromSource,
@@ -2995,6 +3104,7 @@ export {
   foldRequireSpecArg,
   foldStaticStringExpr,
   formalParamDisplayNames,
+  formalParamSignatureNames,
   formalParamsFromNodes,
   formatAbs,
   formatAbsMultiline,
@@ -3100,6 +3210,7 @@ export {
   mock,
   mod,
   mul,
+  namespaceAbsOf,
   namespaceNameOf,
   ne,
   negAbs,
@@ -3111,6 +3222,7 @@ export {
   noteEvalCallRecord,
   noteEvalFallback,
   notePromiseExecutorFork,
+  nullable,
   num,
   numLit,
   numVar,
@@ -3160,6 +3272,7 @@ export {
   resetNudoModuleExecCache,
   resetParseSourceCache,
   resetPhi,
+  resetSidecarLoadFailureCache,
   runTranspiled,
   runTranspiledOptionsMemoKey,
   runWithLoopExits,