@metaharness/flywheel 0.1.0 → 0.1.7

package/dist/cjs/replay.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyReplayBundle = verifyReplayBundle;
+// @metaharness/flywheel — independent replay. Given ONLY a ReplayBundle (and, optionally, the pinned
+// gate fingerprint + the gate rule itself), an external reviewer establishes the run with no trust in the
+// producer:
+//   (1) every promotion receipt verifies (Ed25519, recompute canon vs the embedded key);
+//   (2) the promoted lineage reconstructs current → gen-0 immutable root, contiguously;
+//   (3) every commit on the promoted chain is actually PROMOTED (no rejected node smuggled in);
+//   (4) the gate fingerprint matches the pinned value ⇒ the promotion rule was UNCHANGED;
+//   (5) [ADR-235] if the reviewer supplies the (fingerprint-matched) rule, every PROMOTED commit is
+//       RE-GATED on its sealed baseline+candidate scores and must STILL promote — trust the gate re-run,
+//       not the logged verdict. Catches a signed-but-forged promotion the fingerprint check cannot.
+const receipts_js_1 = require("./receipts.js");
+const gate_js_1 = require("./gate.js");
+function verifyReplayBundle(bundle, opts = {}) {
+    const failures = [];
+    const chain = bundle.chain;
+    const receipts = chain.length > 0 && chain.every((c) => (0, receipts_js_1.verifyReceipt)(c.receipt));
+    if (!receipts)
+        failures.push('receipts');
+    const root = chain[chain.length - 1];
+    const reachesRoot = !!root && root.parents.length === 0 && root.id === bundle.root_id;
+    if (!reachesRoot)
+        failures.push('reachesRoot');
+    let contiguousParents = chain.length > 0;
+    for (let i = 0; i < chain.length - 1; i++) {
+        if (!chain[i].parents.includes(chain[i + 1].id))
+            contiguousParents = false;
+    }
+    if (!contiguousParents)
+        failures.push('contiguousParents');
+    // Every non-root commit on the promoted chain must be PROMOTED (no rejected node smuggled in). An
+    // HONEST-NULL run — the flywheel found no improvement, so the chain is just the immutable gen-0 root —
+    // is VALID and replayable: an empty set of non-root commits satisfies this VACUOUSLY. (Requiring
+    // ≥1 promotion here was a bug: it failed replay on a legitimate 0-promotion result, e.g. a weak model
+    // that resolves nothing — the negative is a real, verifiable outcome, not an invalid bundle.)
+    const promos = chain.filter((c) => c.verdict !== 'ROOT');
+    const allPromoted = promos.every((c) => c.verdict === 'PROMOTED');
+    if (!allPromoted)
+        failures.push('allPromoted');
+    const gateUnchanged = opts.pinnedGateFingerprint ? bundle.gate_fingerprint === opts.pinnedGateFingerprint : true;
+    if (!gateUnchanged)
+        failures.push('gateUnchanged');
+    // (5) RE-EXECUTE the gate. Only when the reviewer supplies the rule (otherwise unchecked → true, so
+    // existing fingerprint-only callers are unaffected). The supplied rule must be the SAME one (its
+    // fingerprint must match the pinned/bundled value) or re-execution is meaningless. Then every PROMOTED
+    // commit that carries its sealed scores must RE-PASS the rule — a logged promotion the frozen gate would
+    // NOT grant is a forgery.
+    let gateReExecutes = true;
+    if (opts.promotionRule) {
+        const suppliedFp = (0, gate_js_1.gateFingerprint)(opts.promotionRule);
+        const expectedFp = opts.pinnedGateFingerprint ?? bundle.gate_fingerprint ?? undefined;
+        if (expectedFp && suppliedFp !== expectedFp) {
+            gateReExecutes = false; // wrong rule supplied — cannot re-execute the run's gate
+        }
+        else {
+            const seen = new Set();
+            for (const c of [...chain, ...bundle.all_commits]) {
+                if (seen.has(c.id))
+                    continue;
+                seen.add(c.id);
+                if (c.verdict === 'PROMOTED' && c.baselineScore && c.candidateScore) {
+                    if (!opts.promotionRule({ baseline: c.baselineScore, candidate: c.candidateScore }).promote) {
+                        gateReExecutes = false;
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    if (!gateReExecutes)
+        failures.push('gateReExecutes');
+    return {
+        pass: failures.length === 0,
+        checks: { receipts, reachesRoot, contiguousParents, allPromoted, gateUnchanged, gateReExecutes },
+        failures,
+        chainSummary: chain.map((c) => `gen${c.generation}${c.mutation ? `(${c.mutation.target})` : '(root)'}`).join(' → '),
+    };
+}
+//# sourceMappingURL=replay.js.map

package/dist/cjs/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../src/replay.ts"],"names":[],"mappings":"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"}

package/dist/cjs/run.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFlywheelGenerations = runFlywheelGenerations;
+// @metaharness/flywheel — runFlywheelGenerations(): the promotion LOOP. run → measure → mutate → verify
+// → promote, generation after generation, each re-basing on the previous promoted winner so verified
+// wins COMPOUND into an auditable lineage. Host- and benchmark-agnostic: everything specific enters via
+// the injected `proposer` / `evaluator` / `promotionRule`. The gate selects the winner on the HOLDOUT;
+// the FROZEN anchor is a separate survival check (never optimized against — the anti-Goodhart guard).
+const lineage_js_1 = require("./lineage.js");
+const gate_js_1 = require("./gate.js");
+async function runFlywheelGenerations(cfg) {
+    const rule = cfg.promotionRule ?? gate_js_1.meetsPromotionRule;
+    const targets = cfg.mutationTargets ?? Object.keys(cfg.rootPolicy);
+    const store = cfg.lineageStore ?? new lineage_js_1.InMemoryLineageStore();
+    const now = cfg.now ?? ((g) => `gen-${g}`);
+    const rootId = cfg.rootId ?? 'root';
+    const anchorOf = async (p) => cfg.anchor ? (await cfg.evaluator(p, cfg.anchor)).primary : null;
+    let rootScore;
+    let rootAnchor;
+    let parentId;
+    let policy;
+    let score;
+    const allCommits = [];
+    let generationsRun = 0;
+    let startGen = 1;
+    if (cfg.resumeFrom) {
+        // ── RESUME: re-seed the prior lineage and restore the mutable state; DON'T re-evaluate the root. ──
+        const r = cfg.resumeFrom;
+        for (const c of r.priorCommits)
+            await store.append(c);
+        allCommits.push(...r.priorCommits.filter((c) => c.verdict !== 'ROOT')); // allCommits excludes the root
+        rootScore = r.rootScore;
+        rootAnchor = r.rootAnchor;
+        parentId = r.parentId;
+        policy = { ...r.policy };
+        score = r.score;
+        generationsRun = r.fromGeneration;
+        startGen = r.fromGeneration + 1;
+    }
+    else {
+        // ── gen-0: the immutable root. Evaluate it once (the baseline) + its anchor (the frozen bar). ──
+        rootScore = await cfg.evaluator(cfg.rootPolicy, cfg.holdout);
+        rootAnchor = await anchorOf(cfg.rootPolicy);
+        await store.append({
+            id: rootId, generation: 0, parents: [], mutation: null, primaryDelta: 0, anchorScore: rootAnchor,
+            verdict: 'ROOT', failureReasons: [], receipt: cfg.signer.sign({ kind: 'root', root: rootId }), createdAt: now(0),
+        });
+        parentId = rootId;
+        policy = { ...cfg.rootPolicy };
+        score = rootScore;
+    }
+    // Assemble a self-consistent replay bundle for the run SO FAR (or final). Pure over the current
+    // lineage; used both for the per-generation checkpoint and the final return so the two can never
+    // diverge. `rootScore`, `rootAnchor`, `allCommits`, `rule`, `rootId`, `cfg` are captured by closure.
+    const buildBundle = (chainNow, createdAt) => {
+        const promoted = chainNow.filter((c) => c.verdict === 'PROMOTED');
+        const verifiedN = promoted.filter((c) => c.primaryDelta > 0).length;
+        const anchorSurvivingN = promoted.filter((c) => c.primaryDelta > 0 && (rootAnchor === null || (c.anchorScore ?? -Infinity) >= rootAnchor)).length;
+        return {
+            data_source: cfg.dataSource ?? 'UNSPECIFIED',
+            root_id: rootId,
+            chain: chainNow,
+            all_commits: allCommits,
+            lift_curve: (0, lineage_js_1.computeLiftCurve)(chainNow, rootScore.primary),
+            gate_fingerprint: (0, gate_js_1.gateFingerprint)(rule),
+            verified_improvements: verifiedN,
+            anchor_surviving_improvements: anchorSurvivingN,
+            milestone_reached: anchorSurvivingN >= 2,
+            created_at: createdAt,
+        };
+    };
+    for (let gen = startGen; gen <= cfg.maxGenerations; gen++) {
+        if (cfg.budget && cfg.budget.spent() >= cfg.budget.total)
+            break;
+        generationsRun = gen;
+        // propose + evaluate one candidate per mutation target, gate each on the HOLDOUT.
+        const base = { id: parentId, generation: gen, parents: [parentId], policy };
+        const cands = [];
+        for (const target of targets) {
+            const proposed = await cfg.proposer(base, target);
+            const candPolicy = { ...policy, [target]: proposed };
+            const candScore = await cfg.evaluator(candPolicy, cfg.holdout);
+            const decision = rule({ baseline: score, candidate: candScore });
+            cands.push({ target, policy: candPolicy, score: candScore, reasons: decision.reasons, promote: decision.promote });
+        }
+        // winner = highest primary among the promotable; then verify it survives the FROZEN anchor.
+        const promotable = cands.filter((c) => c.promote).sort((a, b) => b.score.primary - a.score.primary);
+        const winner = promotable[0] ?? null;
+        const winnerAnchor = winner ? await anchorOf(winner.policy) : null;
+        const anchorSurvives = winner ? (rootAnchor === null || (winnerAnchor ?? -Infinity) >= rootAnchor) : false;
+        // A winner that regresses the anchor is NOT promoted (Goodhart guard) — it becomes a rejection.
+        const promotedWinner = winner && anchorSurvives ? winner : null;
+        for (const c of cands) {
+            const isWinner = c === promotedWinner;
+            const id = `${parentId}__${c.target}_gen${gen}`;
+            const primaryDelta = c.score.primary - score.primary;
+            const commit = {
+                id, generation: gen, parents: [parentId],
+                mutation: { target: c.target, summary: `adapt ${c.target}` },
+                primaryDelta,
+                anchorScore: isWinner ? winnerAnchor : c === winner ? winnerAnchor : null,
+                verdict: isWinner ? 'PROMOTED' : 'REJECTED',
+                failureReasons: isWinner ? [] : c === winner && !anchorSurvives ? ['anchor_regressed'] : c.reasons,
+                receipt: cfg.signer.sign({ kind: 'candidate', id, target: c.target, verdict: isWinner ? 'PROMOTED' : 'REJECTED', primaryDelta }),
+                createdAt: now(gen),
+                baselineScore: score, // ADR-235 — sealed so the gate can be re-run in replay
+                candidateScore: c.score,
+            };
+            await store.append(commit);
+            allCommits.push(commit);
+        }
+        if (promotedWinner) {
+            parentId = `${parentId}__${promotedWinner.target}_gen${gen}`;
+            policy = promotedWinner.policy;
+            score = promotedWinner.score;
+        }
+        // Per-generation checkpoint — a fully assembled, replay-verifiable bundle for the run so far, so a
+        // long run can persist incremental progress. Fail-safe: a throwing hook must NOT kill a valid run.
+        if (cfg.onGeneration) {
+            try {
+                const partialChain = await store.walkToRoot(parentId);
+                const info = {
+                    generation: gen,
+                    generationsRun,
+                    partialBundle: buildBundle(partialChain, now(gen)),
+                    spent: cfg.budget ? cfg.budget.spent() : 0,
+                    resumeState: {
+                        rootScore, rootAnchor, parentId, policy, score,
+                        fromGeneration: gen,
+                        priorCommits: await store.list(), // root + every candidate — re-seeds the store on resume
+                    },
+                };
+                await cfg.onGeneration(info);
+            }
+            catch { /* checkpoint is observational — never let it abort a valid run */ }
+        }
+    }
+    const chain = await store.walkToRoot(parentId);
+    const replayBundle = buildBundle(chain, now(cfg.maxGenerations));
+    const promotions = chain.filter((c) => c.verdict === 'PROMOTED');
+    return {
+        liftCurve: replayBundle.lift_curve, promotions, lineage: store, replayBundle,
+        generationsRun,
+        milestoneReached: replayBundle.milestone_reached, finalPolicy: policy,
+    };
+}
+//# sourceMappingURL=run.js.map

package/dist/cjs/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"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"}

package/dist/cjs/types.js

@@ -0,0 +1,10 @@
+"use strict";
+// @metaharness/flywheel — the abstract API surface.
+//
+// DESIGN RULE (load-bearing): this package must NOT know about any host, model, or benchmark — no
+// Claude Code, no SWE-bench, no GLM/Sonnet/Fable, no code-repair. It knows only CANDIDATES, SCORES,
+// GATES, RECEIPTS, and PROMOTION LINEAGE. Everything host- or benchmark-specific enters through the
+// injected `Proposer` / `Evaluator` (and, if you like, a custom `PromotionRule`). If you find yourself
+// wanting a benchmark-specific branch in here, it belongs in the caller, not the flywheel.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA,oDAAoD;AACpD,EAAE;AACF,kGAAkG;AAClG,oGAAoG;AACpG,oGAAoG;AACpG,uGAAuG;AACvG,2FAA2F"}

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+export interface CliResult {
+    code: number;
+    lines: string[];
+}
+export declare function dispatch(sub: string | undefined, args: string[]): Promise<CliResult>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AA8ED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAa1F"}

package/dist/cli.js

@@ -0,0 +1,103 @@
+// @metaharness/flywheel — CLI dispatch (consumed by `metaharness flywheel <sub>`). Returns
+// { code, lines } to match the sibling package convention (weight-eft / redblue). Three verbs:
+//   run <config.mjs>   — run the loop from a user config module (its own proposer/evaluator/suites)
+//   replay <bundle>    — independently verify a proof bundle (receipts + lineage + frozen gate)
+//   graph <bundle>     — print the lineage chain + the compounding lift curve
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { runFlywheelGenerations } from './run.js';
+import { verifyReplayBundle } from './replay.js';
+import { makeSigner } from './receipts.js';
+import { analyzeBundle, formatAnalysis } from './analyze.js';
+const USAGE = [
+    'metaharness flywheel — a verifiable self-improvement loop for agent harnesses.',
+    '',
+    '  metaharness flywheel run <config.mjs> [--out bundle.json] [--generations N]',
+    '      Run the loop. <config.mjs> default-exports a FlywheelConfig (your proposer/evaluator/suites).',
+    '  metaharness flywheel replay <proof-bundle.json> [--gate-fingerprint <hex>]',
+    '      Independently verify a bundle: receipts + lineage-to-root + (optional) frozen-gate fingerprint.',
+    '  metaharness flywheel graph <proof-bundle.json>',
+    '      Print the promoted lineage chain and the compounding lift curve.',
+    '  metaharness flywheel analyze <proof-bundle.json>',
+    '      F-P2 mutation-effectiveness: which policy levers earn promotions and how much lift each produces.',
+];
+function loadBundle(path) {
+    if (!path)
+        throw new Error('a proof-bundle.json path is required');
+    return JSON.parse(readFileSync(path, 'utf-8'));
+}
+function flag(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+async function replay(args) {
+    const bundle = loadBundle(args[0]);
+    const v = verifyReplayBundle(bundle, { pinnedGateFingerprint: flag(args, '--gate-fingerprint') });
+    const lines = [
+        `Replaying ${args[0]}  [data_source=${bundle.data_source}]`,
+        `  chain:  ${v.chainSummary}`,
+        `  receipts verify (Ed25519, embedded key): ${v.checks.receipts ? 'PASS' : 'FAIL'}`,
+        `  reconstructs to gen-0 root:               ${v.checks.reachesRoot ? 'PASS' : 'FAIL'}`,
+        `  each generation re-bases on the winner:   ${v.checks.contiguousParents ? 'PASS' : 'FAIL'}`,
+        `  every chain node is a promotion:          ${v.checks.allPromoted ? 'PASS' : 'FAIL'}`,
+        `  gate UNCHANGED (fingerprint):             ${flag(args, '--gate-fingerprint') ? (v.checks.gateUnchanged ? 'PASS' : 'FAIL') : 'skipped (no --gate-fingerprint)'}`,
+        `  verified improvements: ${bundle.verified_improvements}  |  anchor-surviving: ${bundle.anchor_surviving_improvements}  |  milestone: ${bundle.milestone_reached}`,
+        '',
+        `ACCEPTANCE: ${v.pass ? 'PASS' : 'FAIL (' + v.failures.join(', ') + ')'}`,
+    ];
+    return { code: v.pass ? 0 : 1, lines };
+}
+function analyze(args) {
+    const bundle = loadBundle(args[0]);
+    return { code: 0, lines: formatAnalysis(analyzeBundle(bundle), `${args[0]}  [data_source=${bundle.data_source}]`) };
+}
+function graph(args) {
+    const bundle = loadBundle(args[0]);
+    const max = Math.max(1, ...bundle.lift_curve.map((p) => p.primary));
+    const lines = [`Lineage + lift curve — ${args[0]}  [root=${bundle.root_id}]`, ''];
+    for (const p of bundle.lift_curve) {
+        const bar = '█'.repeat(Math.round((p.primary / max) * 32));
+        lines.push(`  gen${String(p.generation).padStart(2)}  ${String(p.primary).padStart(4)}  ${bar} ${p.delta > 0 ? `(+${p.delta})` : ''}${p.anchor !== null ? `  anchor=${p.anchor}` : ''}`);
+    }
+    lines.push('', `  promoted chain: ${bundle.chain.map((c) => `gen${c.generation}${c.mutation ? `(${c.mutation.target})` : '(root)'}`).join(' → ')}`);
+    return { code: 0, lines };
+}
+async function run(args) {
+    const cfgPath = args[0];
+    if (!cfgPath)
+        return { code: 2, lines: ['Usage: metaharness flywheel run <config.mjs> [--out bundle.json] [--generations N]'] };
+    const abs = isAbsolute(cfgPath) ? cfgPath : resolve(process.cwd(), cfgPath);
+    const mod = (await import(pathToFileURL(abs).href));
+    const partial = mod.default ?? mod.flywheelConfig;
+    if (!partial || !partial.rootPolicy || !partial.proposer || !partial.evaluator || !partial.holdout) {
+        return { code: 2, lines: [`${cfgPath} must default-export a FlywheelConfig with at least { rootPolicy, proposer, evaluator, holdout }.`] };
+    }
+    const gens = Number(flag(args, '--generations')) || partial.maxGenerations || 10;
+    const result = await runFlywheelGenerations({ maxGenerations: gens, signer: partial.signer ?? makeSigner(), dataSource: partial.dataSource ?? 'LIVE', ...partial });
+    const out = flag(args, '--out');
+    const lines = [`Ran ${result.generationsRun} generations.`];
+    for (const p of result.liftCurve)
+        lines.push(`  gen${p.generation}: primary=${p.primary} ${p.delta > 0 ? `(+${p.delta})` : ''}`);
+    lines.push(`verified improvements: ${result.replayBundle.verified_improvements} | anchor-surviving: ${result.replayBundle.anchor_surviving_improvements} | milestone: ${result.milestoneReached}`);
+    if (out) {
+        writeFileSync(out, JSON.stringify(result.replayBundle, null, 2));
+        lines.push(`replay bundle written: ${out}`);
+    }
+    return { code: 0, lines };
+}
+export async function dispatch(sub, args) {
+    switch (sub) {
+        case 'replay': return replay(args);
+        case 'graph': return graph(args);
+        case 'analyze': return analyze(args);
+        case 'run': return run(args);
+        case undefined:
+        case 'help':
+        case '--help':
+            return { code: 0, lines: USAGE };
+        default:
+            return { code: 2, lines: [`Unknown flywheel subcommand: ${sub}`, '', ...USAGE] };
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -5,5 +5,7 @@ export { makeSigner, verifyReceipt, canon } from './receipts.js';
 export { InMemoryLineageStore, computeLiftCurve, liftPoint } from './lineage.js';
 export { verifyReplayBundle } from './replay.js';
 export type { ReplayVerdict } from './replay.js';
-export type { Policy, PolicyGenome, CandidateMutation, Score, PromotionEvidence, PromotionDecision, PromotionRule, Suite, HoldoutSuite, AnchorSuite, Proposer, Evaluator, PromotionReceipt, Signer, LineageCommit, LineageStore, LiftPoint, LiftCurve, ReplayBundle, } from './types.js';
+export { analyzeBundle, formatAnalysis } from './analyze.js';
+export type { BundleAnalysis, TargetStat } from './analyze.js';
+export type { Policy, PolicyGenome, CandidateMutation, Score, PromotionEvidence, PromotionDecision, PromotionRule, Suite, HoldoutSuite, AnchorSuite, Proposer, Evaluator, PromotionReceipt, Signer, LineageCommit, LineageStore, LiftPoint, LiftCurve, ReplayBundle, GenerationCheckpoint, ResumeState, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

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;AAEjD,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,GACb,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,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

@@ -9,4 +9,5 @@ export { meetsPromotionRule, gateFingerprint } from './gate.js';
 export { makeSigner, verifyReceipt, canon } from './receipts.js';
 export { InMemoryLineageStore, computeLiftCurve, liftPoint } from './lineage.js';
 export { verifyReplayBundle } from './replay.js';
+export { analyzeBundle, formatAnalysis } from './analyze.js';
 //# sourceMappingURL=index.js.map

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"}
+{"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"}

package/dist/replay.d.ts

@@ -1,4 +1,4 @@
-import type { ReplayBundle } from './types.js';
+import type { ReplayBundle, PromotionRule } from './types.js';
 export interface ReplayVerdict {
     pass: boolean;
     checks: {
@@ -7,11 +7,13 @@ export interface ReplayVerdict {
         contiguousParents: boolean;
         allPromoted: boolean;
         gateUnchanged: boolean;
+        gateReExecutes: boolean;
     };
     failures: string[];
     chainSummary: string;
 }
 export declare function verifyReplayBundle(bundle: ReplayBundle, opts?: {
     pinnedGateFingerprint?: string;
+    promotionRule?: PromotionRule;
 }): ReplayVerdict;
 //# sourceMappingURL=replay.d.ts.map

package/dist/replay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE;QACN,QAAQ,EAAE,OAAO,CAAC;QAClB,WAAW,EAAE,OAAO,CAAC;QACrB,iBAAiB,EAAE,OAAO,CAAC;QAC3B,WAAW,EAAE,OAAO,CAAC;QACrB,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,GAAE;IAAE,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,aAAa,CA8BrH"}
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AAE7E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE;QACN,QAAQ,EAAE,OAAO,CAAC;QAClB,WAAW,EAAE,OAAO,CAAC;QACrB,iBAAiB,EAAE,OAAO,CAAC;QAC3B,WAAW,EAAE,OAAO,CAAC;QACrB,aAAa,EAAE,OAAO,CAAC;QACvB,cAAc,EAAE,OAAO,CAAC;KACzB,CAAC;IACF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,IAAI,GAAE;IAAE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,aAAa,CAAA;CAAO,GAC3E,aAAa,CA8Df"}

package/dist/replay.js

@@ -1,10 +1,15 @@
 // @metaharness/flywheel — independent replay. Given ONLY a ReplayBundle (and, optionally, the pinned
-// gate fingerprint), an external reviewer establishes the run with no trust in the producer:
+// gate fingerprint + the gate rule itself), an external reviewer establishes the run with no trust in the
+// producer:
 //   (1) every promotion receipt verifies (Ed25519, recompute canon vs the embedded key);
 //   (2) the promoted lineage reconstructs current → gen-0 immutable root, contiguously;
 //   (3) every commit on the promoted chain is actually PROMOTED (no rejected node smuggled in);
-//   (4) the gate fingerprint matches the pinned value ⇒ the promotion rule was UNCHANGED.
+//   (4) the gate fingerprint matches the pinned value ⇒ the promotion rule was UNCHANGED;
+//   (5) [ADR-235] if the reviewer supplies the (fingerprint-matched) rule, every PROMOTED commit is
+//       RE-GATED on its sealed baseline+candidate scores and must STILL promote — trust the gate re-run,
+//       not the logged verdict. Catches a signed-but-forged promotion the fingerprint check cannot.
 import { verifyReceipt } from './receipts.js';
+import { gateFingerprint } from './gate.js';
 export function verifyReplayBundle(bundle, opts = {}) {
     const failures = [];
     const chain = bundle.chain;
@@ -22,16 +27,50 @@ export function verifyReplayBundle(bundle, opts = {}) {
     }
     if (!contiguousParents)
         failures.push('contiguousParents');
+    // Every non-root commit on the promoted chain must be PROMOTED (no rejected node smuggled in). An
+    // HONEST-NULL run — the flywheel found no improvement, so the chain is just the immutable gen-0 root —
+    // is VALID and replayable: an empty set of non-root commits satisfies this VACUOUSLY. (Requiring
+    // ≥1 promotion here was a bug: it failed replay on a legitimate 0-promotion result, e.g. a weak model
+    // that resolves nothing — the negative is a real, verifiable outcome, not an invalid bundle.)
     const promos = chain.filter((c) => c.verdict !== 'ROOT');
-    const allPromoted = promos.length > 0 && promos.every((c) => c.verdict === 'PROMOTED');
+    const allPromoted = promos.every((c) => c.verdict === 'PROMOTED');
     if (!allPromoted)
         failures.push('allPromoted');
     const gateUnchanged = opts.pinnedGateFingerprint ? bundle.gate_fingerprint === opts.pinnedGateFingerprint : true;
     if (!gateUnchanged)
         failures.push('gateUnchanged');
+    // (5) RE-EXECUTE the gate. Only when the reviewer supplies the rule (otherwise unchecked → true, so
+    // existing fingerprint-only callers are unaffected). The supplied rule must be the SAME one (its
+    // fingerprint must match the pinned/bundled value) or re-execution is meaningless. Then every PROMOTED
+    // commit that carries its sealed scores must RE-PASS the rule — a logged promotion the frozen gate would
+    // NOT grant is a forgery.
+    let gateReExecutes = true;
+    if (opts.promotionRule) {
+        const suppliedFp = gateFingerprint(opts.promotionRule);
+        const expectedFp = opts.pinnedGateFingerprint ?? bundle.gate_fingerprint ?? undefined;
+        if (expectedFp && suppliedFp !== expectedFp) {
+            gateReExecutes = false; // wrong rule supplied — cannot re-execute the run's gate
+        }
+        else {
+            const seen = new Set();
+            for (const c of [...chain, ...bundle.all_commits]) {
+                if (seen.has(c.id))
+                    continue;
+                seen.add(c.id);
+                if (c.verdict === 'PROMOTED' && c.baselineScore && c.candidateScore) {
+                    if (!opts.promotionRule({ baseline: c.baselineScore, candidate: c.candidateScore }).promote) {
+                        gateReExecutes = false;
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    if (!gateReExecutes)
+        failures.push('gateReExecutes');
     return {
         pass: failures.length === 0,
-        checks: { receipts, reachesRoot, contiguousParents, allPromoted, gateUnchanged },
+        checks: { receipts, reachesRoot, contiguousParents, allPromoted, gateUnchanged, gateReExecutes },
         failures,
         chainSummary: chain.map((c) => `gen${c.generation}${c.mutation ? `(${c.mutation.target})` : '(root)'}`).join(' → '),
     };

package/dist/replay.js.map

@@ -1 +1 @@
-{"version":3,"file":"replay.js","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,6FAA6F;AAC7F,yFAAyF;AACzF,wFAAwF;AACxF,gGAAgG;AAChG,0FAA0F;AAC1F,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAgB9C,MAAM,UAAU,kBAAkB,CAAC,MAAoB,EAAE,OAA2C,EAAE;IACpG,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAE3B,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAClF,IAAI,CAAC,QAAQ;QAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAEzC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrC,MAAM,WAAW,GAAG,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,EAAE,KAAK,MAAM,CAAC,OAAO,CAAC;IACtF,IAAI,CAAC,WAAW;QAAE,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAE/C,IAAI,iBAAiB,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,EAAE,CAAC;YAAE,iBAAiB,GAAG,KAAK,CAAC;IAC/E,CAAC;IACD,IAAI,CAAC,iBAAiB;QAAE,QAAQ,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAE3D,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC;IACzD,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC;IACvF,IAAI,CAAC,WAAW;QAAE,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAE/C,MAAM,aAAa,GAAG,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,KAAK,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC;IACjH,IAAI,CAAC,aAAa;QAAE,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAEnD,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC;QAC3B,MAAM,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE;QAChF,QAAQ;QACR,YAAY,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;KACpH,CAAC;AACJ,CAAC"}
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"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"}

package/dist/run.d.ts

@@ -1,4 +1,4 @@
-import type { Policy, Proposer, Evaluator, PromotionRule, Signer, HoldoutSuite, AnchorSuite, LineageStore, LineageCommit, LiftCurve, ReplayBundle } from './types.js';
+import type { Policy, Proposer, Evaluator, PromotionRule, Signer, HoldoutSuite, AnchorSuite, LineageStore, LineageCommit, LiftCurve, ReplayBundle, GenerationCheckpoint, ResumeState } from './types.js';
 export interface FlywheelConfig {
     /** The gen-0 policy — the immutable root every promotion chains back to. */
     rootPolicy: Policy;
@@ -22,6 +22,16 @@ export interface FlywheelConfig {
     now?: (generation: number) => string;
     /** Stamped on the replay bundle — 'SYNTHETIC' | 'LIVE' | …. NEVER a benchmark name. */
     dataSource?: string;
+    /** Optional per-generation checkpoint hook — called at the END of each generation with a fully
+     *  assembled replay bundle for the run so far. Lets a long (multi-hour) run persist incremental
+     *  progress so a crash keeps the completed generations. Observation-only: never affects promotion.
+     *  Errors thrown by the hook are swallowed (a bad checkpoint must not kill a valid run). */
+    onGeneration?: (info: GenerationCheckpoint) => void | Promise<void>;
+    /** Resume a crashed run from a persisted {@link GenerationCheckpoint.resumeState}. When set, the gen-0
+     *  root is NOT re-evaluated or re-created — the prior lineage is re-seeded and the loop continues from
+     *  `resumeFrom.fromGeneration + 1`. Unset ⇒ a fresh run (identical to before). The caller is
+     *  responsible for restoring any external spend counter from the checkpoint's `spent`. */
+    resumeFrom?: ResumeState;
     lineageStore?: LineageStore;
     rootId?: string;
 }

package/dist/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,MAAM,EAAgB,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAChE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAChF,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;IACrB,uGAAuG;IACvG,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,OAAO,EAAE,YAAY,CAAC;IACtB,qGAAqG;IACrG,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,sFAAsF;IACtF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,MAAM,CAAA;KAAE,CAAC;IAChD,sFAAsF;IACtF,GAAG,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,uFAAuF;IACvF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,2CAA2C;IAC3C,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,OAAO,EAAE,YAAY,CAAC;IACtB,YAAY,EAAE,YAAY,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CA2FzF"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,MAAM,EAAgB,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAChE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAC/E,oBAAoB,EAAE,WAAW,EAClC,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;IACrB,uGAAuG;IACvG,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,OAAO,EAAE,YAAY,CAAC;IACtB,qGAAqG;IACrG,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,sFAAsF;IACtF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,MAAM,CAAA;KAAE,CAAC;IAChD,sFAAsF;IACtF,GAAG,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,uFAAuF;IACvF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;gGAG4F;IAC5F,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;8FAG0F;IAC1F,UAAU,CAAC,EAAE,WAAW,CAAC;IACzB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,2CAA2C;IAC3C,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,OAAO,EAAE,YAAY,CAAC;IACtB,YAAY,EAAE,YAAY,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAuIzF"}