@nudojs/core 1.13.0 → 1.14.0

package/dist/{chunk-V2XC3V72.js → chunk-N7AGFMSD.js}

@@ -47,7 +47,7 @@ import {
   withEvalBudgetOverride,
   withExecPhi,
   withFnBudgetOverride
-} from "./chunk-A2PLG2QV.js";
+} from "./chunk-W3Z77Y2I.js";
 
 // src/algebra/directive-scan.ts
 function cleanDirectiveLine(raw, kind) {
@@ -622,6 +622,14 @@ function scanAssumeSegments(lines) {
   }
   return out;
 }
+function scanInvariantSegments(lines) {
+  const out = [];
+  for (const line of lines) {
+    const m = line.match(/^@nudo:invariant\s+(.+)$/);
+    if (m) out.push(m[1].trim().replace(/\*\/$/, "").trim());
+  }
+  return out;
+}
 function scanThrowsDecl(lines) {
   const kinds = /* @__PURE__ */ new Set();
   let any = false;
@@ -1516,6 +1524,35 @@ function extractAssumeSegs(source, fnName) {
   }
   return out;
 }
+var INVARIANT_SEG_REGEX = /^([A-Za-z_$][\w$]*)((?:\[\*\]|\.[A-Za-z_$][\w$]*)*)\s*(>=|<=|>|<)\s*(-?\d+(?:\.\d+)?)$/;
+function extractInvariantSegs(source, fnName) {
+  if (!stripStringsKeepComments(source).includes("@nudo:invariant")) return [];
+  const out = [];
+  for (const seg of scanInvariantSegments(fnDirectiveCommentLines(source, fnName))) {
+    const m = seg.match(INVARIANT_SEG_REGEX);
+    if (!m) {
+      out.push({ kind: "bad", raw: seg });
+      continue;
+    }
+    const pathStr = m[2] ?? "";
+    const path = [];
+    for (const pm of pathStr.matchAll(/\[\*\]|\.[A-Za-z_$][\w$]*/g)) {
+      const t = pm[0];
+      if (t === "[*]") path.push({ k: "idx" });
+      else path.push({ k: "prop", name: t.slice(1) });
+    }
+    const relTxt = m[3];
+    out.push({
+      kind: "ok",
+      name: m[1],
+      path,
+      rel: relTxt === ">=" ? "ge" : relTxt === "<=" ? "le" : relTxt === ">" ? "gt" : "lt",
+      value: Number(m[4]),
+      display: `${m[1]}${pathStr} ${relTxt} ${m[4]}`
+    });
+  }
+  return out;
+}
 function fnTopLevelLocalNames(body) {
   const block = body;
   if (!block || block.type !== "BlockStatement" || !Array.isArray(block.body)) return [];
@@ -5568,6 +5605,7 @@ export {
   execNudoModule,
   resetNudoModuleExecCache,
   extractAssumeSegs,
+  extractInvariantSegs,
   fnTopLevelLocalNames,
   extractRefinesFromSource,
   refineToIndexedFull,

package/dist/{chunk-A2PLG2QV.js → chunk-W3Z77Y2I.js}

@@ -28,6 +28,27 @@ function termEquals(a, b) {
   }
   return false;
 }
+var DETERMINISTIC_APP_FNS = /* @__PURE__ */ new Set([
+  "Math.max",
+  "Math.min",
+  "Math.abs",
+  "Math.round",
+  "Math.floor",
+  "Math.ceil",
+  "Math.trunc",
+  "Math.sign",
+  "+",
+  "-",
+  "*",
+  "/",
+  "%"
+]);
+var LEN_TERM_ID_RE = /^len#\d+$/;
+function isDeterministicTerm(t) {
+  if (t.op === "lit") return true;
+  if (t.op === "var") return LEN_TERM_ID_RE.test(t.id);
+  return DETERMINISTIC_APP_FNS.has(t.fn) && t.args.every(isDeterministicTerm);
+}
 function litKeyString(v2) {
   if (typeof v2 === "number" && Object.is(v2, -0)) return "-0";
   return String(v2);
@@ -4471,6 +4492,19 @@ function withAssumePremises(p, body) {
     assumePremises = prev;
   }
 }
+var invariantSpecs = [];
+function currentInvariantSpecs() {
+  return invariantSpecs;
+}
+function withInvariantSpecs(specs, body) {
+  const prev = invariantSpecs;
+  invariantSpecs = specs;
+  try {
+    return body();
+  } finally {
+    invariantSpecs = prev;
+  }
+}
 var noBody2 = { type: "BlockStatement", body: [], directives: [] };
 var hostGlobalFnCall;
 function setHostGlobalFnCall(bridge) {
@@ -4511,8 +4545,11 @@ function $absVal(v2) {
   return asAbsVal(v2);
 }
 function callAtFunctionBoundary(body) {
-  if (assumePremises !== pTrue) {
-    return withAssumePremises(pTrue, () => boundaryBody(body));
+  if (assumePremises !== pTrue || invariantSpecs.length > 0) {
+    return withAssumePremises(
+      pTrue,
+      () => withInvariantSpecs([], () => boundaryBody(body))
+    );
   }
   return boundaryBody(body);
 }
@@ -5043,6 +5080,16 @@ function bumpEvalForkBudget() {
   return false;
 }
 
+// src/algebra/len-sharing.ts
+var domainShared = /* @__PURE__ */ new WeakSet();
+function markDomainShared(a) {
+  domainShared.add(a);
+  return a;
+}
+function isDomainShared(a) {
+  return domainShared.has(a);
+}
+
 // src/algebra/exec/match-iter.ts
 var tables = /* @__PURE__ */ new WeakMap();
 function registerMatchIter(val, elements) {
@@ -6585,6 +6632,12 @@ function makeArrayCtorAbs(args) {
   }
   return abs({ k: "tuple", elements: [a0] }, void 0, void 0, "exact");
 }
+var fromIdxSeq = 0;
+function fromIdxAbs(lenTerm2, lenNumeric = false) {
+  const t = v(`fromIdx#${fromIdxSeq++}`);
+  const pred = lenNumeric && lenTerm2 ? and(ge(t, lit(0)), lt(t, lenTerm2)) : ge(t, lit(0));
+  return abs({ k: "prim", type: "number" }, t, pred, "path");
+}
 function evalArrayFrom(args) {
   if (args[0] && typeof args[0] === "object" && args[0].shape.k === "brand" && (args[0].shape.name === "Arguments" || args[0].shape.name === "Proxy")) {
     args = [args[0].shape.shape, ...args.slice(1)];
@@ -6609,6 +6662,7 @@ function evalArrayFrom(args) {
     if (!hasMapFn) return el;
     return applyCallbackValue(mapFn, [el, i], emptyEnv(), pTrue, defaultLeakBudget);
   };
+  const idxOrDrop = (lenTerm2, lenNumeric = false) => hasMapFn ? fromIdxAbs(lenTerm2, lenNumeric) : unknown;
   if (isSetAbs(a0) || isMapAbs(a0)) {
     const els = isSetAbs(a0) ? setElementsAbs(a0) : mapEntriesAbs(a0);
     if (els.length === 0) {
@@ -6643,7 +6697,7 @@ function evalArrayFrom(args) {
   }
   const k = a0.shape.k;
   if (k === "arr") {
-    const el = mapOne(a0.shape.element, numPrim());
+    const el = mapOne(markDomainShared(a0.shape.element), idxOrDrop());
     return abs({ k: "arr", element: el }, void 0, void 0, "path");
   }
   if (k === "tuple") {
@@ -6717,16 +6771,19 @@ function evalArrayFrom(args) {
         }
         return abs({ k: "tuple", elements: els }, void 0, void 0, "exact");
       }
-      let el2 = mapOne(undefAbs(), numLit(0));
-      for (const v2 of allIdxSlotValues()) el2 = joinAbs(el2, mapOne(v2, numPrim()));
-      if (open) el2 = joinAbs(el2, mapOne(unknown, numPrim()));
+      const iAbs = idxOrDrop(lit(nLit), true);
+      let el2 = mapOne(undefAbs(), iAbs);
+      for (const vv of allIdxSlotValues()) el2 = joinAbs(el2, mapOne(vv, iAbs));
+      if (open) el2 = joinAbs(el2, mapOne(unknown, iAbs));
       return abs({ k: "arr", element: el2 }, void 0, void 0, "path");
     }
+    const lenT = lenAbs?.term;
+    const lenNum = !!lenT && lenAbs.shape.k === "prim" && lenAbs.shape.type === "number";
     const idxValues = allIdxSlotValues();
     let el = idxValues.length > 0 ? idxValues.reduce((x, y) => joinAbs(x, y)) : undefAbs();
     el = joinAbs(el, undefAbs());
     if (open) el = joinAbs(el, unknown);
-    el = mapOne(el, numPrim());
+    el = mapOne(markDomainShared(el), idxOrDrop(lenT, lenNum));
     return abs({ k: "arr", element: el }, void 0, void 0, "path");
   }
   return unknown;
@@ -13700,7 +13757,7 @@ function $add(a, b) {
   return add(a, b, currentExecPhi());
 }
 function $sub(a, b) {
-  return sub(a, b, currentExecPhi());
+  return sub(a, b, currentExecPhi(), currentAssumePremises());
 }
 function $mul(a, b) {
   return mul(a, b, currentExecPhi());
@@ -15445,6 +15502,80 @@ function primOf(a) {
   return void 0;
 }
 
+// src/algebra/exec/runtime/invariant-apply.ts
+var mintSeq = 0;
+function strengthenLeaf(a, spec) {
+  const s = a.shape;
+  if (s.k !== "prim" || s.type !== "number") return a;
+  if (a.term?.op === "lit") return a;
+  const term = a.term ?? v(`inv#${mintSeq++}`);
+  const bound = lit(spec.value);
+  const rel = spec.rel === "ge" ? ge(term, bound) : spec.rel === "le" ? le(term, bound) : spec.rel === "gt" ? gt(term, bound) : lt(term, bound);
+  return abs(s, term, a.pred ? and(a.pred, rel) : rel, "path");
+}
+function drill(v2, path, spec) {
+  if (path.length === 0) return strengthenLeaf(v2, spec);
+  const [step, ...rest] = path;
+  const s = v2.shape;
+  if (step.k === "idx") {
+    if (s.k === "arr") {
+      const element = drill(s.element, rest, spec);
+      return element === s.element ? v2 : abs({ k: "arr", element }, void 0, void 0, v2.conf);
+    }
+    if (s.k === "tuple") {
+      let changed = false;
+      const elements = s.elements.map((e) => {
+        const w = drill(e, rest, spec);
+        if (w !== e) changed = true;
+        return w;
+      });
+      return changed ? abs({ ...s, elements }, void 0, void 0, v2.conf) : v2;
+    }
+    if (s.k === "sum") {
+      let changed = false;
+      const members = s.members.map((m) => {
+        const w = drill(m, rest, spec);
+        if (w !== m) changed = true;
+        return w;
+      });
+      return changed ? abs({ k: "sum", members }, void 0, void 0, v2.conf) : v2;
+    }
+    return v2;
+  }
+  if (s.k === "obj") {
+    const slot = s.slots[step.name];
+    if (!slot) return v2;
+    const w = drill(slot.value, rest, spec);
+    if (w === slot.value) return v2;
+    return abs(
+      { ...s, slots: { ...s.slots, [step.name]: { ...slot, value: w } } },
+      void 0,
+      void 0,
+      v2.conf
+    );
+  }
+  return v2;
+}
+function applyInvariantsToPack(pack) {
+  const specs = currentInvariantSpecs();
+  if (specs.length === 0) return pack;
+  const s = pack.shape;
+  if (s.k !== "obj") return pack;
+  let slots;
+  let changed = false;
+  for (const spec of specs) {
+    const cur = (slots ?? s.slots)[spec.name];
+    if (!cur) continue;
+    const w = drill(cur.value, spec.path, spec);
+    if (w === cur.value) continue;
+    if (!slots) slots = { ...s.slots };
+    slots[spec.name] = { ...cur, value: w };
+    changed = true;
+  }
+  if (!changed) return pack;
+  return abs({ ...s, slots }, void 0, void 0, pack.conf);
+}
+
 // src/algebra/exec/runtime/loop-widen.ts
 function mergeGrowth(a, b) {
   if (a === true || b === true) return true;
@@ -15730,9 +15861,9 @@ function makeLoopWidener() {
       const base = acc ?? final;
       const g = interrupted ? true : growth;
       if (g === null) {
-        return collapseArrSums(base);
+        return applyInvariantsToPack(collapseArrSums(base));
       }
-      return widenWithPath(normalizeForWiden(base, g), g);
+      return applyInvariantsToPack(widenWithPath(normalizeForWiden(base, g), g));
     }
   };
 }
@@ -16364,7 +16495,7 @@ function $idx(a, i, opts) {
     if (idx === void 0) {
       return joinAbs(a.shape.element, oobUndef());
     }
-    return a.shape.element;
+    return markDomainShared(a.shape.element);
   }
   if (a.shape.k === "brand") {
     const elem = TYPED_ARRAY_ELEMENT[a.shape.name ?? ""];
@@ -16528,7 +16659,7 @@ function abstractLen(a) {
   let t = lenTermMemo.get(a);
   if (!t) {
     t = { op: "var", id: `len#${lenVarSeq++}` };
-    lenTermMemo.set(a, t);
+    if (!isDomainShared(a)) lenTermMemo.set(a, t);
   }
   return abs({ k: "prim", type: "number" }, t, ge(t, lit(0)), "path");
 }
@@ -16960,7 +17091,7 @@ function $tpl(cooked, raw) {
 }
 function elemsOf(a) {
   if (a.shape.k === "tuple") return [...a.shape.elements];
-  if (a.shape.k === "arr") return [a.shape.element];
+  if (a.shape.k === "arr") return [markDomainShared(a.shape.element)];
   if (isSetAbs(a)) return setElementsAbs(a);
   if (isMapAbs(a)) return mapEntriesAbs(a);
   const drained = drainGenElements(a);
@@ -18082,6 +18213,9 @@ function $for(init, test, step, body, maxIters = DEFAULT_MAX_LOOP_ITERS, opts) {
   return exitJoin !== void 0 ? counterWiden.widenFinal(exitJoin) : state;
 }
 function widenLoopJoin(a) {
+  return applyInvariantsToPack(widenLoopJoinInner(a));
+}
+function widenLoopJoinInner(a) {
   const widenValue = (v2) => {
     if (v2.shape.k !== "sum") return v2;
     const members = v2.shape.members;
@@ -22030,7 +22164,7 @@ function invokeArrMethod(arr, method, args) {
         "path"
       );
     }
-    const out = callFn(args[0], args[1], shape2.element, unknownIdx(), arr);
+    const out = callFn(args[0], args[1], markDomainShared(shape2.element), fromIdxAbs(), arr);
     const el = mapElementFallback(asAbs(args[0]), shape2.element, out);
     const conf = el === out ? confJoin(arr.conf, out.conf) : "partial";
     return abs({ k: "arr", element: el }, void 0, void 0, conf);
@@ -22067,7 +22201,7 @@ function invokeArrMethod(arr, method, args) {
       }
       return acc;
     }
-    return callFn(fn2, void 0, acc, shape2.element, unknownIdx(), arr);
+    return callFn(fn2, void 0, acc, markDomainShared(shape2.element), fromIdxAbs(), arr);
   }
   if (method === "reduceRight") {
     validateCallableArg(args[0], "reduceRight callback may not be callable");
@@ -22103,7 +22237,7 @@ function invokeArrMethod(arr, method, args) {
         cause: "reduceRight of possibly-empty array with no initial value"
       });
     }
-    return callFn(fn2, void 0, acc, shape2.element, unknownIdx(), arr);
+    return callFn(fn2, void 0, acc, markDomainShared(shape2.element), fromIdxAbs(), arr);
   }
   if (method === "filter") {
     validateCallableArg(args[0], "filter callback may not be callable");
@@ -22148,7 +22282,7 @@ function invokeArrMethod(arr, method, args) {
       );
       return projectFlatMapResult(arr.conf, mapped);
     }
-    const out = callFn(args[0], args[1], shape2.element, unknownIdx(), arr);
+    const out = callFn(args[0], args[1], markDomainShared(shape2.element), fromIdxAbs(), arr);
     return projectFlatMapResult(arr.conf, [out]);
   }
   if (method === "forEach") {
@@ -22158,7 +22292,7 @@ function invokeArrMethod(arr, method, args) {
         if (!isHole(i)) callFn(args[0], args[1], el, $lit(i), arr);
       });
     } else {
-      callFn(args[0], args[1], shape2.element, unknownIdx(), arr);
+      callFn(args[0], args[1], markDomainShared(shape2.element), fromIdxAbs(), arr);
     }
     return undefAbs();
   }
@@ -22177,7 +22311,7 @@ function invokeArrMethod(arr, method, args) {
         if (method === "every" && !t) return boolLit(false);
       }
     } else {
-      const t = callbackTruth(callFn(args[0], args[1], shape2.element, unknownIdx(), arr));
+      const t = callbackTruth(callFn(args[0], args[1], markDomainShared(shape2.element), fromIdxAbs(), arr));
       if (t === void 0) return bool();
       if (method === "some" && t) return boolLit(true);
       if (method === "every" && !t) return boolLit(false);
@@ -22202,8 +22336,8 @@ function invokeArrMethod(arr, method, args) {
       }
       return undefAbs();
     }
-    const el = shape2.element;
-    const t = callbackTruth(callFn(args[0], args[1], el, unknownIdx(), arr));
+    const el = markDomainShared(shape2.element);
+    const t = callbackTruth(callFn(args[0], args[1], el, fromIdxAbs(), arr));
     if (t === true) return el;
     if (t === false) return undefAbs();
     return joinAbs(el, undefAbs());
@@ -22220,7 +22354,7 @@ function invokeArrMethod(arr, method, args) {
       if (undecided) return joinAbs(unknownIdx(), $lit(-1));
       return $lit(-1);
     }
-    const t = callbackTruth(callFn(args[0], args[1], shape2.element, unknownIdx(), arr));
+    const t = callbackTruth(callFn(args[0], args[1], markDomainShared(shape2.element), fromIdxAbs(), arr));
     if (t === true) return unknownIdx();
     if (t === false) return $lit(-1);
     return joinAbs(unknownIdx(), $lit(-1));
@@ -22241,7 +22375,7 @@ function invokeArrMethod(arr, method, args) {
       }
       return wantIndex ? $lit(-1) : undefAbs();
     }
-    const t = callbackTruth(callFn(args[0], args[1], shape2.element, unknownIdx(), arr));
+    const t = callbackTruth(callFn(args[0], args[1], markDomainShared(shape2.element), fromIdxAbs(), arr));
     if (wantIndex) {
       if (t === true) return unknownIdx();
       if (t === false) return $lit(-1);
@@ -22291,7 +22425,7 @@ function invokeArrMethod(arr, method, args) {
     }
     return abstractSeqIteratorAbs(
       abs(
-        { k: "tuple", elements: [unknownIdx(), shape2.element] },
+        { k: "tuple", elements: [fromIdxAbs(), markDomainShared(shape2.element)] },
         void 0,
         void 0,
         "partial"
@@ -28018,11 +28152,75 @@ function collectExclusionsFromPhi(phi2, id, acc) {
     noteStrictExclusion(p, isTarget, acc);
   }
 }
-function sub(a, b, phi2 = pTrue) {
+function isNonNaN(a, phi2) {
+  if (a.term?.op === "lit") {
+    return typeof a.term.value === "number" && !Number.isNaN(a.term.value);
+  }
+  if (a.shape.k === "sum") {
+    return a.shape.members.every(
+      (m) => isNonNaN(m, phi2)
+    );
+  }
+  const hasNonNaNFact = (p) => {
+    if (!p) return false;
+    if (p.op === "and") return p.args.some(hasNonNaNFact);
+    if (p.op === "assumeFinite") {
+      return !!a.term && termEquals(p.t, a.term);
+    }
+    if (p.op === "ne") {
+      if (p.b.op === "lit" && typeof p.b.value === "number" && Number.isNaN(p.b.value) && a.term && termEquals(p.a, a.term)) {
+        return true;
+      }
+    }
+    if (p.op === "gt" || p.op === "ge" || p.op === "lt" || p.op === "le") {
+      if (a.term && (termEquals(p.a, a.term) || termEquals(p.b, a.term))) return true;
+    }
+    return false;
+  };
+  if (hasNonNaNFact(a.pred)) return true;
+  if (a.term?.op === "var") {
+    const id = a.term.id;
+    const conjs = phi2.op === "and" ? phi2.args : [phi2];
+    for (const p of conjs) {
+      if (p.op === "assumeFinite" && p.t.op === "var" && p.t.id === id) {
+        return true;
+      }
+      if (p.op === "ne") {
+        const b = p.b;
+        if (b.op === "lit" && typeof b.value === "number" && Number.isNaN(b.value) && p.a.op === "var" && p.a.id === id) {
+          return true;
+        }
+      }
+      if (p.op === "gt" || p.op === "ge" || p.op === "lt" || p.op === "le") {
+        const sides = [p.a, p.b];
+        if (sides.some((t) => t.op === "var" && t.id === id) && sides.some((t) => t.op === "lit" && typeof t.value === "number")) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+function subAssumeBounds(a, b, resultTerm, assume) {
+  const premises = assumePremiseList(assume);
+  if (premises.length === 0) return void 0;
+  if (!a.term || !b.term) return void 0;
+  const facts = [];
+  for (const p of premises) {
+    if (p.op !== "le") continue;
+    if (termEquals(p.a, a.term) && termEquals(p.b, b.term)) {
+      facts.push(le(resultTerm, lit(0)));
+    } else if (termEquals(p.a, b.term) && termEquals(p.b, a.term)) {
+      facts.push(ge(resultTerm, lit(0)));
+    }
+  }
+  return facts.length ? and(...facts) : void 0;
+}
+function sub(a, b, phi2 = pTrue, assume) {
   {
     const fa = builtinBrandToPrimitive(a, "number");
     const fb = builtinBrandToPrimitive(b, "number");
-    if (fa || fb) return sub(fa ?? a, fb ?? b, phi2);
+    if (fa || fb) return sub(fa ?? a, fb ?? b, phi2, assume);
   }
   if (isSymbolAbs(a) || isSymbolAbs(b)) {
     throw new NudoThrow(errorTypeAbs("TypeError"));
@@ -28041,6 +28239,12 @@ function sub(a, b, phi2 = pTrue) {
     return numLit(Number(ra.value) - Number(rb.value));
   }
   if (isNumericLike(a) && isNumericLike(b) && a.term && b.term) {
+    if (termEquals(a.term, b.term) && isDeterministicTerm(a.term) && // 域共享门（len-sharing.ts，第二类洞）：同一带项 Abs 经元素域分发
+    // 到两个下标位（xs.map(s=>s.length) 的 a[0] 与 a[1]）——term 结构
+    // 相同但代表不同具体值，$idx/回调实参分发位已标记，此处拒绝折叠。
+    !isDomainShared(a) && !isDomainShared(b)) {
+      return isNonNaN(a, phi2) || isNonNaN(b, phi2) ? numLit(0) : makeSum(numLit(NaN), numLit(0));
+    }
     const term = simplifyTerm(app("-", [a.term, b.term]));
     const ab = numericBounds(a, phi2);
     const bb = numericBounds(b, phi2);
@@ -28059,6 +28263,8 @@ function sub(a, b, phi2 = pTrue) {
         facts.push(strict ? lt(term, lit(hi)) : le(term, lit(hi)));
       }
     }
+    const assumePred = subAssumeBounds(a, b, term, assume);
+    if (assumePred) facts.push(assumePred);
     const conf = term.op === "lit" ? "exact" : confJoin(confJoin(a.conf, b.conf), facts.length ? "path" : "path");
     return abs({ k: "prim", type: "number" }, term, facts.length ? and(...facts) : void 0, conf);
   }
@@ -28071,7 +28277,7 @@ function sub(a, b, phi2 = pTrue) {
   if (isAnyLike(a) || isAnyLike(b)) {
     return toNumberResult(a, b, "-");
   }
-  const distributed = distributeSumBinOp("-", a, b, phi2, sub);
+  const distributed = distributeSumBinOp("-", a, b, phi2, (x, y, p) => sub(x, y, p, assume));
   if (distributed) return distributed;
   noteAbstractArithMayThrow(a, b);
   return abs({ k: "unknown" }, void 0, void 0, "partial");
@@ -28531,55 +28737,6 @@ function mathMethod(name) {
   const impl = Math[name];
   return typeof impl === "function" ? impl : void 0;
 }
-function isNonNaN(a, phi2) {
-  if (a.term?.op === "lit") {
-    return typeof a.term.value === "number" && !Number.isNaN(a.term.value);
-  }
-  if (a.shape.k === "sum") {
-    return a.shape.members.every(
-      (m) => isNonNaN(m, phi2)
-    );
-  }
-  const hasNonNaNFact = (p) => {
-    if (!p) return false;
-    if (p.op === "and") return p.args.some(hasNonNaNFact);
-    if (p.op === "assumeFinite") {
-      return !!a.term && termEquals(p.t, a.term);
-    }
-    if (p.op === "ne") {
-      if (p.b.op === "lit" && typeof p.b.value === "number" && Number.isNaN(p.b.value) && a.term && termEquals(p.a, a.term)) {
-        return true;
-      }
-    }
-    if (p.op === "gt" || p.op === "ge" || p.op === "lt" || p.op === "le") {
-      if (a.term && (termEquals(p.a, a.term) || termEquals(p.b, a.term))) return true;
-    }
-    return false;
-  };
-  if (hasNonNaNFact(a.pred)) return true;
-  if (a.term?.op === "var") {
-    const id = a.term.id;
-    const conjs = phi2.op === "and" ? phi2.args : [phi2];
-    for (const p of conjs) {
-      if (p.op === "assumeFinite" && p.t.op === "var" && p.t.id === id) {
-        return true;
-      }
-      if (p.op === "ne") {
-        const b = p.b;
-        if (b.op === "lit" && typeof b.value === "number" && Number.isNaN(b.value) && p.a.op === "var" && p.a.id === id) {
-          return true;
-        }
-      }
-      if (p.op === "gt" || p.op === "ge" || p.op === "lt" || p.op === "le") {
-        const sides = [p.a, p.b];
-        if (sides.some((t) => t.op === "var" && t.id === id) && sides.some((t) => t.op === "lit" && typeof t.value === "number")) {
-          return true;
-        }
-      }
-    }
-  }
-  return false;
-}
 function ieeeBoundNum(n) {
   return Number.isFinite(n) || n === Infinity || n === -Infinity ? n : void 0;
 }
@@ -28984,6 +29141,7 @@ export {
   withExecPhi,
   currentAssumePremises,
   withAssumePremises,
+  withInvariantSpecs,
   asAbsVal,
   $absVal,
   callAtFunctionBoundary,

package/dist/exec.js

@@ -206,7 +206,7 @@ import {
   withAssumePremises,
   withEvalBudgetOverride,
   withExecPhi
-} from "./chunk-A2PLG2QV.js";
+} from "./chunk-W3Z77Y2I.js";
 export {
   $absVal,
   $add,

package/dist/index.d.ts

@@ -255,7 +255,7 @@ declare function asAbs(v: unknown): Abs | undefined;
 
 declare function add(a: Abs, b: Abs, phi?: Phi): Abs;
 /** 减法：a - b = a + (-b)，数值上做单调性 */
-declare function sub(a: Abs, b: Abs, phi?: Phi): Abs;
+declare function sub(a: Abs, b: Abs, phi?: Phi, assume?: Phi): Abs;
 /** 乘法：字面量直接求值；×正数同向缩放；×负数翻转不等式；×0 归零 */
 declare function mul(a: Abs, b: Abs, phi?: Phi): Abs;
 /**

package/dist/index.js

@@ -14,6 +14,7 @@ import {
   extractFileEnvNames,
   extractFn,
   extractFnBudget,
+  extractInvariantSegs,
   extractMockModuleRecords,
   extractNudoImportRecords,
   extractNudoImports,
@@ -66,7 +67,7 @@ import {
   takeInterfaceDiagsSince,
   takeRefineDiags,
   takeRefineDiagsSince
-} from "./chunk-V2XC3V72.js";
+} from "./chunk-N7AGFMSD.js";
 import {
   $add,
   $arguments,
@@ -525,8 +526,9 @@ import {
   v,
   withAssumePremises,
   withExecPhi,
+  withInvariantSpecs,
   withVar
-} from "./chunk-A2PLG2QV.js";
+} from "./chunk-W3Z77Y2I.js";
 
 // src/environment.ts
 function createEnvironment(parent, bindings = /* @__PURE__ */ new Map()) {
@@ -2413,6 +2415,49 @@ function assumePremisesPhiOf(name, source, file, issues) {
   if (preds.length === 0) return void 0;
   return { phi: and(...preds), display };
 }
+function invariantSpecsOf(name, source, file, issues) {
+  const segs = extractInvariantSegs(source, name);
+  if (segs.length === 0) return void 0;
+  const meta = extractFn(source, name, file);
+  const bindable = /* @__PURE__ */ new Set([
+    ...contractParamNameSet(meta?.formals ?? []),
+    ...meta?.params ?? [],
+    ...fnTopLevelLocalNames(meta?.body)
+  ]);
+  const surface = [...bindable].join(", ");
+  const specs = [];
+  const display = [];
+  for (const seg of segs) {
+    if (seg.kind === "bad") {
+      issues.push({
+        severity: "warning",
+        code: "nudo:invariant-invalid",
+        message: `${name}: malformed @nudo:invariant '${seg.raw}' (expected <name><path> <rel> <number>; path = [*] or .member steps)`,
+        actual: seg.raw,
+        expected: "<name><path> <rel> <number>",
+        suggestion: "loop-carried bounds: @nudo:invariant dp[*][*] >= 0 \u2014 scalar: @nudo:invariant last >= 1",
+        fn: name
+      });
+      continue;
+    }
+    if (!bindable.has(seg.name)) {
+      issues.push({
+        severity: "warning",
+        code: "nudo:invariant-invalid",
+        message: `${name}: @nudo:invariant name not bound as a parameter or top-level local (${seg.name})`,
+        actual: seg.name,
+        expected: surface || "(no params/locals)",
+        suggestion: `reference one of: ${surface || "(no params or top-level locals)"}`,
+        fn: name
+      });
+      continue;
+    }
+    specs.push({ name: seg.name, path: seg.path, rel: seg.rel, value: seg.value });
+    display.push(seg.display);
+  }
+  if (specs.length === 0) return void 0;
+  return { specs, display };
+}
 function checkSourceInner(filePath, source, file, phi, opts, issues, signatures, names, truncated, identityOpts = opts, depsFp, sidecarFp) {
   const hasRefineDirective = stripStringsKeepComments(source).includes("@nudo:contract");
   const entryNames = localNamedExports(source);
@@ -2441,7 +2486,11 @@ function checkSourceInner(filePath, source, file, phi, opts, issues, signatures,
   };
   for (const name of names) {
     const assumePhi = assumePremisesPhiOf(name, source, file, issues);
-    const runSeeded = (body) => assumePhi === void 0 ? body() : withAssumePremises(assumePhi.phi, body);
+    const inv = invariantSpecsOf(name, source, file, issues);
+    const runSeeded = (body) => {
+      if (assumePhi === void 0 && inv === void 0) return body();
+      return withAssumePremises(assumePhi?.phi ?? pTrue, () => withInvariantSpecs(inv?.specs ?? [], body));
+    };
     if (opts.skips?.has(name)) {
       const declared = opts.skips.get(name) ?? null;
       const meta = extractFn(source, name, file);
@@ -2676,7 +2725,8 @@ function checkSourceInner(filePath, source, file, phi, opts, issues, signatures,
           display,
           eff.returns.constraint,
           g.symbolic,
-          assumePhi?.display
+          assumePhi?.display,
+          inv?.display
         );
         if (retIssues.some((i) => i.severity === "error")) returnViolated.add(name);
         issues.push(...retIssues);
@@ -2877,23 +2927,33 @@ function checkSourceInner(filePath, source, file, phi, opts, issues, signatures,
     budget: { ...budget }
   };
 }
-function checkReturnConstraint(fnName, cName, constraint, ret, assumeDisplay) {
+function checkReturnConstraint(fnName, cName, constraint, ret, assumeDisplay, invariantDisplay) {
   const proof = assertImplies(ret, constraint);
   if (proof.status === "proved") {
+    const relied = [];
     if (assumeDisplay && assumeDisplay.length > 0) {
-      return [
-        {
-          severity: "info",
-          code: "nudo:assume-relied",
-          message: `${fnName}: return contract proved via @nudo:assume ${assumeDisplay.join("; ")}`,
-          actual: `proof relies on user lemma${assumeDisplay.length > 1 ? "s" : ""}`,
-          expected: "engine verifies the obligation, not the lemma itself",
-          suggestion: "@nudo:assume is a user-supplied axiom \u2014 falsify it with concrete @nudo:case runs (nudo test)",
-          fn: fnName
-        }
-      ];
+      relied.push({
+        severity: "info",
+        code: "nudo:assume-relied",
+        message: `${fnName}: return contract proved via @nudo:assume ${assumeDisplay.join("; ")}`,
+        actual: `proof relies on user lemma${assumeDisplay.length > 1 ? "s" : ""}`,
+        expected: "engine verifies the obligation, not the lemma itself",
+        suggestion: "@nudo:assume is a user-supplied axiom \u2014 falsify it with concrete @nudo:case runs (nudo test)",
+        fn: fnName
+      });
+    }
+    if (invariantDisplay && invariantDisplay.length > 0) {
+      relied.push({
+        severity: "info",
+        code: "nudo:invariant-relied",
+        message: `${fnName}: return contract proved via @nudo:invariant ${invariantDisplay.join("; ")}`,
+        actual: `proof relies on user invariant${invariantDisplay.length > 1 ? "s" : ""}`,
+        expected: "engine verifies the obligation, not the loop invariant itself",
+        suggestion: "@nudo:invariant is a user-supplied axiom \u2014 falsify it with concrete @nudo:case runs (nudo test)",
+        fn: fnName
+      });
     }
-    return [];
+    return relied;
   }
   const push = (severity, actual, expected, suggestion) => [
     {

package/dist/internal.js

@@ -21,7 +21,7 @@ import {
   stableAnalyzeKeySource,
   stablePathKey,
   stablePathKeyGraph
-} from "./chunk-V2XC3V72.js";
+} from "./chunk-N7AGFMSD.js";
 import {
   $tryDigestSoft,
   $tryMarkSoft,
@@ -169,7 +169,7 @@ import {
   withEvalBudgetOverride,
   withFnBudgetOverride,
   wrapPromise
-} from "./chunk-A2PLG2QV.js";
+} from "./chunk-W3Z77Y2I.js";
 
 // src/algebra/inlay.ts
 function listFunctions(source) {

package/package.json

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