@metaharness/flywheel 0.1.7 → 0.1.8

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatAnalysis = exports.analyzeBundle = exports.verifyReplayBundle = exports.liftPoint = exports.computeLiftCurve = exports.InMemoryLineageStore = exports.canon = exports.verifyReceipt = exports.makeSigner = exports.gateFingerprint = exports.meetsPromotionRule = exports.runFlywheelGenerations = void 0;
+exports.formatAnalysis = exports.analyzeBundle = exports.verifyReplayBundle = exports.liftPoint = exports.computeLiftCurve = exports.InMemoryLineageStore = exports.canon = exports.verifyReceipt = exports.makeSigner = exports.withSequentialEvidence = exports.sequentialEvidence = exports.gateFingerprint = exports.meetsPromotionRule = exports.runFlywheelGenerations = void 0;
 // @metaharness/flywheel — a verifiable self-improvement loop for agent harnesses.
 // Freeze the model. Evolve the harness. Promote only what proves lift.
 //
@@ -12,6 +12,9 @@ Object.defineProperty(exports, "runFlywheelGenerations", { enumerable: true, get
 var gate_js_1 = require("./gate.js");
 Object.defineProperty(exports, "meetsPromotionRule", { enumerable: true, get: function () { return gate_js_1.meetsPromotionRule; } });
 Object.defineProperty(exports, "gateFingerprint", { enumerable: true, get: function () { return gate_js_1.gateFingerprint; } });
+var sequential_js_1 = require("./sequential.js");
+Object.defineProperty(exports, "sequentialEvidence", { enumerable: true, get: function () { return sequential_js_1.sequentialEvidence; } });
+Object.defineProperty(exports, "withSequentialEvidence", { enumerable: true, get: function () { return sequential_js_1.withSequentialEvidence; } });
 var receipts_js_1 = require("./receipts.js");
 Object.defineProperty(exports, "makeSigner", { enumerable: true, get: function () { return receipts_js_1.makeSigner; } });
 Object.defineProperty(exports, "verifyReceipt", { enumerable: true, get: function () { return receipts_js_1.verifyReceipt; } });

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,kFAAkF;AAClF,uEAAuE;AACvE,EAAE;AACF,uGAAuG;AACvG,yGAAyG;AACzG,2GAA2G;AAC3G,mCAAkD;AAAzC,gHAAA,sBAAsB,OAAA;AAG/B,qCAAgE;AAAvD,6GAAA,kBAAkB,OAAA;AAAE,0GAAA,eAAe,OAAA;AAC5C,6CAAiE;AAAxD,yGAAA,UAAU,OAAA;AAAE,4GAAA,aAAa,OAAA;AAAE,oGAAA,KAAK,OAAA;AACzC,2CAAiF;AAAxE,kHAAA,oBAAoB,OAAA;AAAE,8GAAA,gBAAgB,OAAA;AAAE,uGAAA,SAAS,OAAA;AAC1D,yCAAiD;AAAxC,+GAAA,kBAAkB,OAAA;AAE3B,2CAA6D;AAApD,2GAAA,aAAa,OAAA;AAAE,4GAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,kFAAkF;AAClF,uEAAuE;AACvE,EAAE;AACF,uGAAuG;AACvG,yGAAyG;AACzG,2GAA2G;AAC3G,mCAAkD;AAAzC,gHAAA,sBAAsB,OAAA;AAG/B,qCAAgE;AAAvD,6GAAA,kBAAkB,OAAA;AAAE,0GAAA,eAAe,OAAA;AAC5C,iDAA6E;AAApE,mHAAA,kBAAkB,OAAA;AAAE,uHAAA,sBAAsB,OAAA;AAEnD,6CAAiE;AAAxD,yGAAA,UAAU,OAAA;AAAE,4GAAA,aAAa,OAAA;AAAE,oGAAA,KAAK,OAAA;AACzC,2CAAiF;AAAxE,kHAAA,oBAAoB,OAAA;AAAE,8GAAA,gBAAgB,OAAA;AAAE,uGAAA,SAAS,OAAA;AAC1D,yCAAiD;AAAxC,+GAAA,kBAAkB,OAAA;AAE3B,2CAA6D;AAApD,2GAAA,aAAa,OAAA;AAAE,4GAAA,cAAc,OAAA"}

package/dist/cjs/sequential.js

@@ -0,0 +1,105 @@
+"use strict";
+// @metaharness/flywheel — anytime-valid sequential testing for promotion gates.
+//
+// WHY THIS EXISTS
+//
+// `meetsPromotionRule` is a single-shot conjunctive comparison, and it is the
+// right shape: frozen, fingerprintable, every clause load-bearing. But a
+// flywheel run evaluates MANY generations against the SAME holdout, and that is
+// uncontrolled multiple testing. Published measurements of greedy
+// "accept-if-the-score-improved" acceptance put the false-commit rate at
+// 30-42%, and found 13-21 spurious modifications made even when NO true gains
+// existed — degrading one agent by 4.9 points while every individual decision
+// looked locally justified.
+//
+// The conjunctive gate plus a frozen anchor already mitigates this with
+// multiple hurdles, which is real. It is not, however, anytime-valid: nothing
+// in it accounts for how many times you have looked.
+//
+// This module adds that missing property WITHOUT touching the default gate,
+// whose stability is itself the product. It composes: wrap any PromotionRule,
+// and a candidate must clear both the frozen clauses AND accumulated evidence.
+//
+// METHOD
+//
+// Testing-by-betting / e-processes. An e-value is a non-negative random
+// variable with expectation <= 1 under the null hypothesis ("this candidate is
+// no better than baseline"). By Ville's inequality, P(sup_t E_t >= 1/alpha)
+// <= alpha, so you may stop and reject at ANY time — no pre-registered sample
+// size, no alpha spending schedule, and no penalty for peeking. That is exactly
+// the property a flywheel needs, because it peeks by construction.
+//
+// The bet here is deliberately simple and assumption-light: per paired item,
+// a candidate win against a baseline loss multiplies the e-value up, the
+// reverse multiplies it down, and ties leave it unchanged.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sequentialEvidence = sequentialEvidence;
+exports.withSequentialEvidence = withSequentialEvidence;
+const DEFAULT_ALPHA = 0.05;
+const DEFAULT_LAMBDA = 0.5;
+/**
+ * Accumulate paired outcomes into an anytime-valid e-value.
+ *
+ * Only discordant pairs move the e-value: if both arms win or both lose, that
+ * item tells you nothing about which is better (this is the McNemar insight,
+ * carried over to the sequential setting).
+ */
+function sequentialEvidence(outcomes, config = {}) {
+    const alpha = config.alpha ?? DEFAULT_ALPHA;
+    const lambda = config.lambda ?? DEFAULT_LAMBDA;
+    if (!(alpha > 0 && alpha < 1))
+        throw new RangeError('alpha must be in (0, 1)');
+    if (!(lambda > 0 && lambda < 1))
+        throw new RangeError('lambda must be in (0, 1)');
+    const threshold = 1 / alpha;
+    let eValue = 1;
+    let informativePairs = 0;
+    for (const o of outcomes) {
+        if (o.candidateWon === o.baselineWon)
+            continue; // concordant: no information
+        informativePairs++;
+        // Under the null, a discordant pair favors either arm with probability 1/2,
+        // so E[multiplier] = 1 and the process is a non-negative martingale.
+        eValue *= o.candidateWon ? 1 + lambda : 1 - lambda;
+    }
+    return {
+        significant: eValue >= threshold,
+        eValue,
+        threshold,
+        informativePairs,
+        totalPairs: outcomes.length,
+    };
+}
+/**
+ * Compose a frozen gate with a sequential-evidence requirement.
+ *
+ * The returned rule is still a plain `PromotionRule`, so it fingerprints and
+ * freezes exactly like the default one. A candidate must satisfy BOTH: every
+ * clause of `baseRule`, and evidence strong enough to survive having been
+ * looked at repeatedly.
+ *
+ * Paired outcomes are read from `evidence.pairedOutcomes` when present. When
+ * absent the rule degrades to `baseRule` alone rather than silently blocking
+ * every promotion — a caller that has not wired up per-item outcomes yet should
+ * get the old behavior, not a permanently closed gate.
+ */
+function withSequentialEvidence(baseRule, config = {}) {
+    return function sequentialPromotionRule(evidence) {
+        const base = baseRule(evidence);
+        const outcomes = evidence
+            .pairedOutcomes;
+        if (!outcomes)
+            return base;
+        const verdict = sequentialEvidence(outcomes, config);
+        if (verdict.significant)
+            return base;
+        return {
+            promote: false,
+            reasons: [
+                ...base.reasons,
+                `insufficient_sequential_evidence(e=${verdict.eValue.toFixed(2)}<${verdict.threshold})`,
+            ],
+        };
+    };
+}
+//# sourceMappingURL=sequential.js.map

package/dist/cjs/sequential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequential.js","sourceRoot":"","sources":["../../src/sequential.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,EAAE;AACF,kBAAkB;AAClB,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,kEAAkE;AAClE,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,4BAA4B;AAC5B,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,qDAAqD;AACrD,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,+EAA+E;AAC/E,EAAE;AACF,SAAS;AACT,EAAE;AACF,wEAAwE;AACxE,+EAA+E;AAC/E,4EAA4E;AAC5E,8EAA8E;AAC9E,gFAAgF;AAChF,mEAAmE;AACnE,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,2DAA2D;;AA8C3D,gDA6BC;AAeD,wDAsBC;AA5ED,MAAM,aAAa,GAAG,IAAI,CAAC;AAC3B,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAChC,QAAyB,EACzB,SAA2B,EAAE;IAE7B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,aAAa,CAAC;IAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,cAAc,CAAC;IAE/C,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,yBAAyB,CAAC,CAAC;IAC/E,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,0BAA0B,CAAC,CAAC;IAElF,MAAM,SAAS,GAAG,CAAC,GAAG,KAAK,CAAC;IAC5B,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,gBAAgB,GAAG,CAAC,CAAC;IAEzB,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,WAAW;YAAE,SAAS,CAAC,6BAA6B;QAC7E,gBAAgB,EAAE,CAAC;QACnB,4EAA4E;QAC5E,qEAAqE;QACrE,MAAM,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IACrD,CAAC;IAED,OAAO;QACL,WAAW,EAAE,MAAM,IAAI,SAAS;QAChC,MAAM;QACN,SAAS;QACT,gBAAgB;QAChB,UAAU,EAAE,QAAQ,CAAC,MAAM;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,sBAAsB,CACpC,QAAuB,EACvB,SAA2B,EAAE;IAE7B,OAAO,SAAS,uBAAuB,CAAC,QAA2B;QACjE,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAChC,MAAM,QAAQ,GAAI,QAAqE;aACpF,cAAc,CAAC;QAElB,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAE3B,MAAM,OAAO,GAAG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACrD,IAAI,OAAO,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QAErC,OAAO;YACL,OAAO,EAAE,KAAK;YACd,OAAO,EAAE;gBACP,GAAG,IAAI,CAAC,OAAO;gBACf,sCAAsC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,SAAS,GAAG;aACxF;SACF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { runFlywheelGenerations } from './run.js';
 export type { FlywheelConfig, FlywheelResult } from './run.js';
 export { meetsPromotionRule, gateFingerprint } from './gate.js';
+export { sequentialEvidence, withSequentialEvidence } from './sequential.js';
+export type { PairedOutcome, SequentialConfig, SequentialVerdict } from './sequential.js';
 export { makeSigner, verifyReceipt, canon } from './receipts.js';
 export { InMemoryLineageStore, computeLiftCurve, liftPoint } from './lineage.js';
 export { verifyReplayBundle } from './replay.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7D,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/D,YAAY,EACV,MAAM,EACN,YAAY,EACZ,iBAAiB,EACjB,KAAK,EACL,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,KAAK,EACL,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,MAAM,EACN,aAAa,EACb,YAAY,EACZ,SAAS,EACT,SAAS,EACT,YAAY,EACZ,oBAAoB,EACpB,WAAW,GACZ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7D,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/D,YAAY,EACV,MAAM,EACN,YAAY,EACZ,iBAAiB,EACjB,KAAK,EACL,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,KAAK,EACL,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,MAAM,EACN,aAAa,EACb,YAAY,EACZ,SAAS,EACT,SAAS,EACT,YAAY,EACZ,oBAAoB,EACpB,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -6,6 +6,7 @@
 // evaluator, gate, holdouts, and cost/security rules; get the same auditable, replayable improvement loop.
 export { runFlywheelGenerations } from './run.js';
 export { meetsPromotionRule, gateFingerprint } from './gate.js';
+export { sequentialEvidence, withSequentialEvidence } from './sequential.js';
 export { makeSigner, verifyReceipt, canon } from './receipts.js';
 export { InMemoryLineageStore, computeLiftCurve, liftPoint } from './lineage.js';
 export { verifyReplayBundle } from './replay.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,uEAAuE;AACvE,EAAE;AACF,uGAAuG;AACvG,yGAAyG;AACzG,2GAA2G;AAC3G,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGlD,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,uEAAuE;AACvE,EAAE;AACF,uGAAuG;AACvG,yGAAyG;AACzG,2GAA2G;AAC3G,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGlD,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE7E,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/sequential.d.ts

@@ -0,0 +1,53 @@
+import type { PromotionRule } from './types.js';
+/** Per-item paired outcome: did candidate and baseline each succeed? */
+export interface PairedOutcome {
+    /** Suite item id. Pairing is by item — comparing unpaired sets is a different, weaker test. */
+    itemId: string;
+    candidateWon: boolean;
+    baselineWon: boolean;
+}
+export interface SequentialConfig {
+    /**
+     * Type-I error bound. Reject the null only when the e-value reaches 1/alpha.
+     * Default 0.05 => threshold 20.
+     */
+    alpha?: number;
+    /**
+     * Betting fraction in (0, 1). Higher detects large effects sooner but is
+     * slower on small ones. 0.5 is the Kelly-ish default and needs no tuning.
+     */
+    lambda?: number;
+}
+export interface SequentialVerdict {
+    /** True when accumulated evidence crosses 1/alpha. */
+    significant: boolean;
+    /** The e-value. Interpretable directly: 20 means "20:1 against the null". */
+    eValue: number;
+    threshold: number;
+    /** Items where the two arms disagreed — the only ones carrying information. */
+    informativePairs: number;
+    totalPairs: number;
+}
+/**
+ * Accumulate paired outcomes into an anytime-valid e-value.
+ *
+ * Only discordant pairs move the e-value: if both arms win or both lose, that
+ * item tells you nothing about which is better (this is the McNemar insight,
+ * carried over to the sequential setting).
+ */
+export declare function sequentialEvidence(outcomes: PairedOutcome[], config?: SequentialConfig): SequentialVerdict;
+/**
+ * Compose a frozen gate with a sequential-evidence requirement.
+ *
+ * The returned rule is still a plain `PromotionRule`, so it fingerprints and
+ * freezes exactly like the default one. A candidate must satisfy BOTH: every
+ * clause of `baseRule`, and evidence strong enough to survive having been
+ * looked at repeatedly.
+ *
+ * Paired outcomes are read from `evidence.pairedOutcomes` when present. When
+ * absent the rule degrades to `baseRule` alone rather than silently blocking
+ * every promotion — a caller that has not wired up per-item outcomes yet should
+ * get the old behavior, not a permanently closed gate.
+ */
+export declare function withSequentialEvidence(baseRule: PromotionRule, config?: SequentialConfig): PromotionRule;
+//# sourceMappingURL=sequential.d.ts.map

package/dist/sequential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequential.d.ts","sourceRoot":"","sources":["../src/sequential.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAwC,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtF,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,WAAW,EAAE,OAAO,CAAC;IACrB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAKD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,aAAa,EAAE,EACzB,MAAM,GAAE,gBAAqB,GAC5B,iBAAiB,CA0BnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,aAAa,EACvB,MAAM,GAAE,gBAAqB,GAC5B,aAAa,CAmBf"}

package/dist/sequential.js

@@ -0,0 +1,101 @@
+// @metaharness/flywheel — anytime-valid sequential testing for promotion gates.
+//
+// WHY THIS EXISTS
+//
+// `meetsPromotionRule` is a single-shot conjunctive comparison, and it is the
+// right shape: frozen, fingerprintable, every clause load-bearing. But a
+// flywheel run evaluates MANY generations against the SAME holdout, and that is
+// uncontrolled multiple testing. Published measurements of greedy
+// "accept-if-the-score-improved" acceptance put the false-commit rate at
+// 30-42%, and found 13-21 spurious modifications made even when NO true gains
+// existed — degrading one agent by 4.9 points while every individual decision
+// looked locally justified.
+//
+// The conjunctive gate plus a frozen anchor already mitigates this with
+// multiple hurdles, which is real. It is not, however, anytime-valid: nothing
+// in it accounts for how many times you have looked.
+//
+// This module adds that missing property WITHOUT touching the default gate,
+// whose stability is itself the product. It composes: wrap any PromotionRule,
+// and a candidate must clear both the frozen clauses AND accumulated evidence.
+//
+// METHOD
+//
+// Testing-by-betting / e-processes. An e-value is a non-negative random
+// variable with expectation <= 1 under the null hypothesis ("this candidate is
+// no better than baseline"). By Ville's inequality, P(sup_t E_t >= 1/alpha)
+// <= alpha, so you may stop and reject at ANY time — no pre-registered sample
+// size, no alpha spending schedule, and no penalty for peeking. That is exactly
+// the property a flywheel needs, because it peeks by construction.
+//
+// The bet here is deliberately simple and assumption-light: per paired item,
+// a candidate win against a baseline loss multiplies the e-value up, the
+// reverse multiplies it down, and ties leave it unchanged.
+const DEFAULT_ALPHA = 0.05;
+const DEFAULT_LAMBDA = 0.5;
+/**
+ * Accumulate paired outcomes into an anytime-valid e-value.
+ *
+ * Only discordant pairs move the e-value: if both arms win or both lose, that
+ * item tells you nothing about which is better (this is the McNemar insight,
+ * carried over to the sequential setting).
+ */
+export function sequentialEvidence(outcomes, config = {}) {
+    const alpha = config.alpha ?? DEFAULT_ALPHA;
+    const lambda = config.lambda ?? DEFAULT_LAMBDA;
+    if (!(alpha > 0 && alpha < 1))
+        throw new RangeError('alpha must be in (0, 1)');
+    if (!(lambda > 0 && lambda < 1))
+        throw new RangeError('lambda must be in (0, 1)');
+    const threshold = 1 / alpha;
+    let eValue = 1;
+    let informativePairs = 0;
+    for (const o of outcomes) {
+        if (o.candidateWon === o.baselineWon)
+            continue; // concordant: no information
+        informativePairs++;
+        // Under the null, a discordant pair favors either arm with probability 1/2,
+        // so E[multiplier] = 1 and the process is a non-negative martingale.
+        eValue *= o.candidateWon ? 1 + lambda : 1 - lambda;
+    }
+    return {
+        significant: eValue >= threshold,
+        eValue,
+        threshold,
+        informativePairs,
+        totalPairs: outcomes.length,
+    };
+}
+/**
+ * Compose a frozen gate with a sequential-evidence requirement.
+ *
+ * The returned rule is still a plain `PromotionRule`, so it fingerprints and
+ * freezes exactly like the default one. A candidate must satisfy BOTH: every
+ * clause of `baseRule`, and evidence strong enough to survive having been
+ * looked at repeatedly.
+ *
+ * Paired outcomes are read from `evidence.pairedOutcomes` when present. When
+ * absent the rule degrades to `baseRule` alone rather than silently blocking
+ * every promotion — a caller that has not wired up per-item outcomes yet should
+ * get the old behavior, not a permanently closed gate.
+ */
+export function withSequentialEvidence(baseRule, config = {}) {
+    return function sequentialPromotionRule(evidence) {
+        const base = baseRule(evidence);
+        const outcomes = evidence
+            .pairedOutcomes;
+        if (!outcomes)
+            return base;
+        const verdict = sequentialEvidence(outcomes, config);
+        if (verdict.significant)
+            return base;
+        return {
+            promote: false,
+            reasons: [
+                ...base.reasons,
+                `insufficient_sequential_evidence(e=${verdict.eValue.toFixed(2)}<${verdict.threshold})`,
+            ],
+        };
+    };
+}
+//# sourceMappingURL=sequential.js.map

package/dist/sequential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequential.js","sourceRoot":"","sources":["../src/sequential.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,EAAE;AACF,kBAAkB;AAClB,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,kEAAkE;AAClE,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,4BAA4B;AAC5B,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,qDAAqD;AACrD,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,+EAA+E;AAC/E,EAAE;AACF,SAAS;AACT,EAAE;AACF,wEAAwE;AACxE,+EAA+E;AAC/E,4EAA4E;AAC5E,8EAA8E;AAC9E,gFAAgF;AAChF,mEAAmE;AACnE,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,2DAA2D;AAoC3D,MAAM,aAAa,GAAG,IAAI,CAAC;AAC3B,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAyB,EACzB,SAA2B,EAAE;IAE7B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,aAAa,CAAC;IAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,cAAc,CAAC;IAE/C,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,yBAAyB,CAAC,CAAC;IAC/E,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,0BAA0B,CAAC,CAAC;IAElF,MAAM,SAAS,GAAG,CAAC,GAAG,KAAK,CAAC;IAC5B,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,gBAAgB,GAAG,CAAC,CAAC;IAEzB,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,WAAW;YAAE,SAAS,CAAC,6BAA6B;QAC7E,gBAAgB,EAAE,CAAC;QACnB,4EAA4E;QAC5E,qEAAqE;QACrE,MAAM,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IACrD,CAAC;IAED,OAAO;QACL,WAAW,EAAE,MAAM,IAAI,SAAS;QAChC,MAAM;QACN,SAAS;QACT,gBAAgB;QAChB,UAAU,EAAE,QAAQ,CAAC,MAAM;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAuB,EACvB,SAA2B,EAAE;IAE7B,OAAO,SAAS,uBAAuB,CAAC,QAA2B;QACjE,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAChC,MAAM,QAAQ,GAAI,QAAqE;aACpF,cAAc,CAAC;QAElB,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAE3B,MAAM,OAAO,GAAG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACrD,IAAI,OAAO,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QAErC,OAAO;YACL,OAAO,EAAE,KAAK;YACd,OAAO,EAAE;gBACP,GAAG,IAAI,CAAC,OAAO;gBACf,sCAAsC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,SAAS,GAAG;aACxF;SACF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaharness/flywheel",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "A verifiable self-improvement loop for agent harnesses. Freeze the model. Evolve the harness. Promote only what proves lift.",
   "type": "module",
   "main": "./dist/cjs/index.js",