@rulvar/evals 1.18.0 → 1.20.0

package/dist/index.js

@@ -20,27 +20,67 @@ import { createHash } from "node:crypto";
 * invocation and is never persisted.
 *
 * Accounting is integer micro-USD and conservative at the
-* representation boundary (v1.17.0 review P1-4): the cap converts DOWN
-* (floor), every debit converts UP (ceil), and a cap below one
-* micro-USD is rejected outright, so for any admitted sequence the sum
-* of the ORIGINAL ceilings can never exceed maxTotalUsd and no
-* positive ceiling ever debits zero. Amounts that are integer
+* representation boundary (v1.17.0 review P1-4, hardened by the
+* v1.18.0 review P1-4 and the v1.19.0 review P1-3): the cap converts
+* DOWN (floor), every debit converts UP (ceil), only ULP-scale
+* representation noise may snap to the neighboring integer, amounts at
+* or above 2^49 micro-USD (about $563M, where the noise window would
+* reach half a micro and the nearest integer would stop being unique)
+* are rejected, and a cap below one micro-USD is rejected outright.
+*
+* The exact input interpretation: every USD amount is a JavaScript
+* double, and the envelope interprets a double within SNAP_ULPS ULPs
+* of an integer micro value AS that integer; anything farther rounds
+* in the conservative direction. Under that interpretation the sum of
+* admitted ceilings can never exceed maxTotalUsd, and no positive
+* ceiling ever debits zero. The honest raw-double bound: each admitted
+* amount's double may sit below its interpreted integer by at most the
+* noise window (4 ULPs, always under half a micro in-domain), so the
+* sum of raw doubles can exceed the cap by at most half a micro-USD
+* per admitted amount; distinguishing finer than that is impossible in
+* double precision at the top of the domain. Amounts that are integer
 * micro-USD up to float noise stay exact, so 0.1 + 0.2 against a 0.3
 * envelope is a fit, not a float rejection.
 */
 const MICRO = 1e6;
 /**
-* Relative tolerance for float noise around an integer micro-USD
-* amount: 0.3 * 1e6 is 299999.99999999994 and MUST count as 300000,
-* while a genuinely sub-micro 0.4 must not.
+* Directed-rounding snap window, in ULPs of the product `usd * 1e6`:
+* only genuine IEEE-754 representation noise may snap to the neighboring
+* integer (0.3 * 1e6 is 299999.99999999994, about 6e-11 away, and MUST
+* count as 300000), while a genuinely sub-micro fraction like 0.4 must
+* round in the conservative direction. The window scales with the ULP,
+* never with a relative fraction of the amount: the v1.17.0 fix used a
+* 1e-6 RELATIVE tolerance, which already reaches half a micro-USD at
+* $0.50 and turned directed rounding into round-to-nearest, admitting
+* aggregates above the cap (v1.18.0 review P1-4).
 */
-const MICRO_NOISE = 1e-6;
+const SNAP_ULPS = 4;
 function microOf(usd, direction) {
 	const raw = usd * MICRO;
 	const nearest = Math.round(raw);
-	if (Math.abs(raw - nearest) <= MICRO_NOISE * Math.max(1, Math.abs(nearest))) return nearest;
+	if (Math.abs(raw - nearest) <= SNAP_ULPS * Math.abs(raw) * Number.EPSILON) return nearest;
 	return direction === "floor" ? Math.floor(raw) : Math.ceil(raw);
 }
+/**
+* The accounting domain is integer micro-USD strictly below 2^49
+* (at most $562,949,953.421311). Two limits meet there. Outside the
+* safe integer range the arithmetic silently degrades: a
+* Number.MAX_VALUE cap overflowed to Infinity and admitted EVERYTHING
+* with remainingUsd NaN (v1.18.0 review P1-4). Well before that, from
+* 2^49 micro upward, the SNAP_ULPS window reaches half a micro-USD:
+* the nearest integer stops being unique and the snap absorbs genuine
+* sub-micro remainders, so a ceil debit could round DOWN and admit an
+* aggregate whose raw doubles sum above the cap by more than the
+* documented noise bound (v1.19.0 review P1-3). Below 2^49 the window
+* stays strictly under half a micro, the snap target is unique, and
+* only representation noise is absorbed. Out-of-domain amounts are
+* rejected up front.
+*/
+const MAX_MICRO_EXCLUSIVE = 2 ** 49;
+function requireDomainMicro(micro, what, usd) {
+	if (!Number.isSafeInteger(micro) || micro >= MAX_MICRO_EXCLUSIVE) throw new ConfigError(`${what} ${String(usd)} USD is outside the micro-USD accounting domain (at most \$562949953.421311)`);
+	return micro;
+}
 /** Thrown when authorizing a run's ceiling would exceed the envelope. */
 var SweepBudgetError = class extends Error {
 	/** What was about to start, e.g. `eval target 'sweep-math'`. */
@@ -71,7 +111,7 @@ var SpendEnvelope = class {
 	constructor(maxTotalUsd) {
 		if (!Number.isFinite(maxTotalUsd) || maxTotalUsd <= 0) throw new ConfigError(`SpendEnvelope maxTotalUsd must be a positive finite number, got ${String(maxTotalUsd)}`);
 		this.maxTotalUsd = maxTotalUsd;
-		this.maxMicroUsd = microOf(maxTotalUsd, "floor");
+		this.maxMicroUsd = requireDomainMicro(microOf(maxTotalUsd, "floor"), "SpendEnvelope maxTotalUsd", maxTotalUsd);
 		if (this.maxMicroUsd < 1) throw new ConfigError(`SpendEnvelope maxTotalUsd ${String(maxTotalUsd)} is below the 1 micro-USD accounting granularity (\$0.000001); such an envelope could never admit a run`);
 	}
 	/** Total authorized so far (debit-only; never decreases). */
@@ -89,7 +129,7 @@ var SpendEnvelope = class {
 	*/
 	authorize(ceilingUsd, runLabel) {
 		if (ceilingUsd === void 0 || !Number.isFinite(ceilingUsd) || ceilingUsd <= 0) throw new ConfigError(`the spend envelope requires an explicit positive per-run ceiling for ${runLabel}; got ${String(ceilingUsd)} (an unbounded run under an aggregate envelope would be unaccountable)`);
-		const micro = Math.max(1, microOf(ceilingUsd, "ceil"));
+		const micro = requireDomainMicro(Math.max(1, microOf(ceilingUsd, "ceil")), `per-run ceiling for ${runLabel}`, ceilingUsd);
 		if (this.authorizedMicroUsd + micro > this.maxMicroUsd) throw new SweepBudgetError(runLabel, ceilingUsd, this.authorizedUsd, this.maxTotalUsd);
 		this.authorizedMicroUsd += micro;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/evals",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "Rulvar evals: eval cases, golden outputs, rubric and judge graders, matrix sweeps, canary fingerprint.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,8 +22,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.18.0",
-    "@rulvar/testing": "1.18.0"
+    "@rulvar/core": "1.20.0",
+    "@rulvar/testing": "1.20.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",