pi-mega-compact 0.20.85 → 0.20.87

package/dist/src/recall/vote.js

@@ -0,0 +1,217 @@
+/**
+ * recall/vote.ts — the 3-independent-source recall vote (3WF-3).
+ *
+ * Three INDEPENDENT, read-only sources name candidate checkpoints:
+ *   A vector  — raw semantic hits (recall/readonly.ts), cosine 0..1 scale.
+ *   B fts5    — BM25 trigram hits (hydrated to checkpointIds), FTS5 BM25 scale
+ *               (negative score = better match; ranking order is what matters).
+ *   C recency — the N freshest checkpoints by timestamp, query-INDEPENDENT.
+ *               (NOT turn_recall / TurnReader — that would just echo already-
+ *               injected content, not an independent signal.)
+ *
+ * Each source is a different score scale, so they are NOT directly comparable.
+ * We normalize each source's scores to a 0..1 scale (per-source min-max) BEFORE
+ * combining. Averaging raw cosine (0..1) with raw BM25 (arbitrary negative
+ * magnitude) or a recency rank would be meaningless — the largest-magnitude
+ * scale would always dominate. Normalization makes each source a peer voter.
+ *
+ * Overlap rule: a checkpoint named by >=2 of 3 distinct sources short-circuits
+ * as a winner. Fallback (no 2/3 majority): rank all candidates by the
+ * cross-source MEAN of their normalized scores.
+ *
+ * Non-fatal throughout. Pi-agnostic: no pi runtime imports.
+ */
+import { openStore } from "../store/sqlite/utils.js";
+import { fts5SearchScoped, hydrateFts5Hits } from "../store/sqlite/fts5-search.js";
+// The SQLite store is the source of truth (src/store.ts's same-named helper
+// reads the LEGACY gzipped-JSON DR snapshot, which is empty for live sessions —
+// importing it here would silently starve sources B and C). Mirrors the import
+// in vector-search.ts + tieredRouter.ts.
+import { listCheckpoints } from "../store/sqlite.js";
+import { computeContentDigest } from "../dedup/digest.js";
+import { recallRawHits } from "./readonly.js";
+import { Logger } from "../log.js";
+/** Per-source normalization: map raw scores to 0..1 via min-max within source. */
+function normalizeScores(scores) {
+    const map = new Map();
+    if (scores.length === 0)
+        return map;
+    const min = Math.min(...scores);
+    const max = Math.max(...scores);
+    const span = max - min;
+    scores.forEach((s, i) => {
+        map.set(i, span === 0 ? 1 : (s - min) / span);
+    });
+    return map;
+}
+/**
+ * Run the three-source recall vote. Returns agreement winners + a per-id vote
+ * count + the names of sources that produced no winning candidate. Non-fatal:
+ * any search failure degrades to the remaining sources (empty winners allowed).
+ */
+export function voteRecall(opts, store) {
+    const logger = new Logger();
+    const limit = opts.limit ?? 3;
+    const recencyCount = opts.recencyCount ?? limit;
+    // ── Source A: vector (raw hits, cosine 0..1). ────────────────────────────
+    const vectorCands = recallRawHits({ sessionId: opts.sessionId, query: opts.query, limit }, store).map((h) => ({
+        checkpointId: h.checkpoint.checkpointId,
+        score: h.score,
+        source: "vector",
+    }));
+    // ── Source B: fts5 (BM25, hydrated to checkpointIds). ─────────────────────
+    // Dedup on L0 content digest so the SAME normalized text under two ids does
+    // not double-vote — collapse to one candidate per digest.
+    const fts5Cands = (() => {
+        try {
+            const reader = openStore(store.stateDir);
+            const hits = fts5SearchScoped(opts.query, reader, opts.sessionId, limit);
+            // FTS5 returns scores ordered best-first (bm25 asc); lower = better.
+            // We keep the raw score (negative-is-better) and flip in normalization.
+            const hydrated = hydrateFts5Hits(hits, opts.sessionId, store.stateDir);
+            // Dedup on checkpointId so the same checkpoint cannot double-count, AND
+            // on the L0 CONTENT digest so identical normalized text stored under two
+            // different ids collapses to one vote. The digest is taken over the
+            // joined `summary` (real content): hashing the id string would be a
+            // no-op tier, since ids are unique by definition.
+            const seenDigest = new Set();
+            const seenId = new Set();
+            const out = [];
+            for (const h of hydrated) {
+                if (seenId.has(h.checkpointId))
+                    continue;
+                seenId.add(h.checkpointId);
+                const digest = computeContentDigest(h.summary).contentHash;
+                if (seenDigest.has(digest))
+                    continue;
+                seenDigest.add(digest);
+                out.push({ checkpointId: h.checkpointId, score: h.score, source: "fts5" });
+            }
+            return out;
+        }
+        catch {
+            return [];
+        }
+    })();
+    // ── Source C: recency (N freshest checkpoints, query-independent). ────────
+    // Timestamp-ordered; the lower the index the fresher. Score = recency rank
+    // (fresh = high) so normalization treats newest as best.
+    const recencyCands = (() => {
+        try {
+            const cps = listCheckpoints(opts.sessionId, store.stateDir)
+                .filter((c) => c.dedupStatus !== "removed")
+                .sort((a, b) => (b.timestamp ?? 0) - (a.timestamp ?? 0))
+                .slice(0, recencyCount);
+            return cps.map((cp, i) => ({
+                checkpointId: cp.checkpointId,
+                // Fresher => higher raw score (recency rank). Normalized below.
+                score: cps.length - i,
+                source: "recency",
+            }));
+        }
+        catch {
+            return [];
+        }
+    })();
+    const sources = [
+        { name: "vector", cands: vectorCands },
+        { name: "fts5", cands: fts5Cands },
+        { name: "recency", cands: recencyCands },
+    ];
+    // Per-source normalization to 0..1 so the three scales are comparable.
+    const perSource = sources.map((s) => ({
+        name: s.name,
+        norm: normalizeScores(s.cands.map((c) => c.score)),
+    }));
+    // Aggregate: best normalized score per source per checkpointId + vote count.
+    const bestScoreBySource = new Map();
+    const seenIds = new Set();
+    for (const src of sources) {
+        const norm = perSource.find((p) => p.name === src.name).norm;
+        const bestByCp = new Map();
+        src.cands.forEach((c, i) => {
+            const n = norm.get(i) ?? 0;
+            const prev = bestByCp.get(c.checkpointId);
+            if (prev === undefined || n > prev)
+                bestByCp.set(c.checkpointId, n);
+            seenIds.add(c.checkpointId);
+        });
+        bestScoreBySource.set(src.name, bestByCp);
+    }
+    // Vote count = number of DISTINCT sources naming each checkpointId.
+    const votes = {};
+    const sumByCp = new Map();
+    for (const id of seenIds) {
+        let count = 0;
+        let sum = 0;
+        for (const src of sources) {
+            const m = bestScoreBySource.get(src.name);
+            if (m.has(id)) {
+                count++;
+                sum += m.get(id);
+            }
+        }
+        votes[id] = count;
+        sumByCp.set(id, sum);
+    }
+    /** Mean normalized score across the sources that named `id`. */
+    const meanScore = (id) => (sumByCp.get(id) ?? 0) / (votes[id] ?? 1);
+    // Short-circuit: >=2 of 3 distinct sources => winner (agreement). Ranked by
+    // vote count first (stronger agreement wins), then by mean normalized score —
+    // the validator consumes this list in order and takes the first that passes,
+    // so the ordering IS the ranking and must not be Set-insertion order.
+    const winners = [];
+    const divergent = new Set(sources.map((s) => s.name));
+    const agreed = [...seenIds]
+        .filter((id) => (votes[id] ?? 0) >= 2)
+        .sort((a, b) => (votes[b] ?? 0) - (votes[a] ?? 0) || meanScore(b) - meanScore(a));
+    for (const id of agreed) {
+        const cand = (() => {
+            for (const src of sources) {
+                const c = src.cands.find((x) => x.checkpointId === id);
+                if (c)
+                    return c;
+            }
+            return null;
+        })();
+        if (cand)
+            winners.push(cand);
+    }
+    if (winners.length === 0) {
+        // Fallback (no 2-of-3 agreement): rank by cross-source MEAN normalized score.
+        const ranked = [...seenIds].sort((a, b) => meanScore(b) - meanScore(a));
+        for (const id of ranked) {
+            const cand = (() => {
+                for (const src of sources) {
+                    const c = src.cands.find((x) => x.checkpointId === id);
+                    if (c)
+                        return c;
+                }
+                return null;
+            })();
+            if (cand)
+                winners.push(cand);
+        }
+    }
+    // Divergence = a source that named NONE of the winning checkpoints. This must
+    // be computed per SOURCE against the winning ID SET, not from `winner.source`
+    // (a winner is one candidate object carrying a single source label, so an id
+    // agreed on by all three sources would still credit only one of them).
+    const winningIds = new Set(winners.map((w) => w.checkpointId));
+    for (const src of sources) {
+        if (src.cands.some((c) => winningIds.has(c.checkpointId))) {
+            divergent.delete(src.name);
+        }
+    }
+    if (divergent.size > 0) {
+        logger.info("recall_vote_divergence", {
+            divergentSources: [...divergent],
+            winnerCount: winners.length,
+        });
+    }
+    return {
+        winners,
+        votes,
+        divergentSources: [...divergent],
+    };
+}

package/dist/src/store/sqlite/fts5-search.js

@@ -11,6 +11,7 @@
  * time automatically — no manual n-gram splitting needed. The BM25 rank from
  * fts5 ranks results by trigram-overlap density.
  */
+import { listCheckpoints } from "./checkpoints.js";
 /**
  * Search the context_chunks_trgm FTS5 table for checkpoints whose
  * `normalized_text` matches `query` via trigram similarity.
@@ -66,3 +67,28 @@ export function fts5SearchScoped(query, reader, sessionId, limit = 10) {
     // No session filter — plain FTS5 search across all sessions.
     return fts5Search(query, reader, limit);
 }
+/**
+ * Hydrate FTS5 hits (which only carry checkpoint `id` + BM25 `score`, with NO
+ * checkpoint object) by joining against the real stored checkpoints. Mirrors the
+ * private `hydrateHits` in tieredRouter.ts (listCheckpoints → Map on
+ * checkpointId → join, dropping ids with no checkpoint).
+ *
+ * The joined `summary` is returned alongside the id because the 3WF-3 voter
+ * dedups candidates on the L0 CONTENT digest — hashing the id string instead
+ * would be a no-op tier (ids are already unique), silently disabling the check.
+ *
+ * @param hits      Raw Fts5Hit rows (id + BM25 score).
+ * @param sessionId Session scope used to fetch the checkpoint set.
+ * @param stateDir  On-disk state dir for the sync store.
+ */
+export function hydrateFts5Hits(hits, sessionId, stateDir) {
+    const cps = listCheckpoints(sessionId, stateDir);
+    const cpMap = new Map(cps.map((cp) => [cp.checkpointId, cp]));
+    const out = [];
+    for (const h of hits) {
+        const cp = cpMap.get(h.id);
+        if (cp)
+            out.push({ checkpointId: h.id, score: h.score, summary: cp.summary });
+    }
+    return out;
+}

package/dist/src/store/sqlite/meta.js

@@ -36,6 +36,38 @@ export function getMetaNumber(key, stateDir = getStateDir()) {
     const n = raw == null ? 0 : Number(raw);
     return Number.isFinite(n) ? n : 0;
 }
+/**
+ * Upsert a single numeric meta key to an absolute value (NOT a cumulative
+ * counter). Follows the `addTokensSaved` INSERT-ON-CONFLICT pattern with a
+ * fully parameterized query (PREVENT-002: no SQL string concat — `key` and
+ * `value` are both bound, never interpolated). The only write is the standard
+ * ON CONFLICT upsert of THIS key's own value; no other key is touched, no
+ * DELETE is issued.
+ *
+ * Used by the 3WF-2 ThrashGuard to persist exactly two keys:
+ *  - `thrasguard.baseline_tokens` — the live-window token count at the moment
+ *    an ineffective compaction was observed (the baseline the guard re-arms from).
+ *  - `thrasguard.blocked_until` — the live-window token count below which
+ *    re-firing is refused (guard active).
+ *
+ * Non-finite input (NaN / ±Infinity) is rejected: the extension must never
+ * persist a non-number into the meta table (getMetaNumber would read it back as
+ * 0), so we return early, non-fatal. Best-effort: any store failure is swallowed.
+ */
+export function setMetaNumber(key, value, stateDir = getStateDir()) {
+    if (key.length === 0)
+        return;
+    if (!Number.isFinite(value))
+        return;
+    try {
+        const db = openStore(stateDir);
+        db.prepare(`INSERT INTO meta(key, value) VALUES(?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = ?`).run(key, String(value), String(value));
+    }
+    catch {
+        /* non-fatal: meta writes never break the agent loop */
+    }
+}
 /** Atomically add `delta` to an integer meta counter. */
 function incMeta(key, delta, stateDir = getStateDir()) {
     if (!(delta > 0))

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -241,6 +241,7 @@ export const SETTINGS: ReadonlyArray<SettingGroup> = [
 			num("MEGACOMPACT_L2_THRESHOLD", "L2 Cosine Threshold", "L2 semantic dedup firing point", 0.85, 0, 1),
 			num("MEGACOMPACT_L1_JACCARD", "L1 Jaccard Threshold", "L1 MinHash near-dup threshold", 0.8, 0, 1),
 			num("MEGACOMPACT_DEDUP_SIM", "Dedup Similarity", "Legacy content-similarity fallback", 0.9, 0, 1),
+			num("MEGACOMPACT_RECALL_MIN_COSINE", "Recall Min Cosine (same-repo)", "3WF-3 same-repo floor the 3-source validator applies to the top winner (cross-repo 0.90 stays separate)", 0.12, 0, 1),
 			num("MEGACOMPACT_MMR_LAMBDA", "MMR Lambda", "Maximal Marginal Relevance diversity", 0.5, 0, 1),
 			num("MEGACOMPACT_SEMDEDUP_COSINE", "SemDeDup Cosine", "Offline SemDeDup pair threshold", 0.95, 0, 1),
 			num("MEGACOMPACT_CONSOLIDATE_COSINE", "Consolidate Cosine", "Memory consolidation merge threshold", 0.7, 0, 1),
@@ -285,6 +286,14 @@ export const SETTINGS: ReadonlyArray<SettingGroup> = [
 				0.1,
 				0.95,
 			),
+			num(
+				"MEGACOMPACT_THRASH_REARM_PCT",
+				"Thrash Re-arm %",
+				"After an ineffective compaction (live window did not shrink), refuse to re-fire until the live window grows by this fraction of the effective threshold. Default 0.10 (10%)",
+				0.1,
+				0.01,
+				0.5,
+			),
 		],
 	},
 	VECTOR_CORTEX_SETTINGS,

package/extensions/mega-config-types.ts

@@ -119,6 +119,11 @@ export interface MegaConfig {
 	 *  tighter than same-repo so only genuinely-relevant cross-repo context is
 	 *  injected. */
 	crossRepoCosine: number;
+	/** Same-repo recall cosine floor (3WF-3). Default 0.12. SEPARATE from
+	 *  `crossRepoCosine` (S17, default 0.90 — stricter, cross-repo only). The
+	 *  3-source validator applies this to the top winner; hits below it are
+	 *  rejected in favor of the next-ranked candidate or the provenance floor. */
+	recallMinCosine: number;
 	/** Memory-RAG auto-review enabled (S20). Every memoryReviewInterval turns the
 	 *  conversation is auto-reviewed into durable add/replace/remove memories. */
 	memoryAutoReview: boolean;
@@ -140,6 +145,14 @@ export interface MegaConfig {
 	 *  session_start never fired, so every session has a staged block (recall hits,
 	 *  else a provenance floor). Default ON; OFF = byte-identical pre-sprint. */
 	threeWayFailback: boolean;
+	/** 3WF-2: ThrashGuard re-arm budget as a FRACTION of `effectiveThreshold`.
+	 *  After an ineffective compaction (live window did not shrink), the guard
+	 *  refuses to re-fire until the live window has grown by at least
+	 *  `rearmPct × effectiveThreshold` tokens past the observed baseline. Default
+	 *  0.10 (10% of the effective threshold). Env-overridable via
+	 *  MEGACOMPACT_THRASH_REARM_PCT. When the effective threshold is unknown
+	 *  (+Infinity), the guard skips arming (cannot compute N) and logs instead. */
+	thrashRearmPct: number;
 	/** A1 PLAN_V2 Phase 2: Message Separation — isolate user/assistant turns
 	 *  from volatile tool results so the prompt-cache prefix stays stable.
 	 *  PC-A: positive sprint flag, now default ON; flag-OFF (=0) is byte-identical

package/extensions/mega-config.ts

@@ -217,6 +217,12 @@ export function loadConfig(): MegaConfig {
 		autoWikiEnabled: envBool("MEGACOMPACT_AUTO_WIKI", true),
 		crossRepoEnabled: envBool("MEGACOMPACT_CROSSREPO_ENABLED", true),
 		crossRepoCosine: Number(process.env.MEGACOMPACT_CROSSREPO_COSINE ?? "0.90"),
+		// 3WF-3: SAME-repo recall cosine floor applied by the 3-source validator to
+		// the top winner. SEPARATE from crossRepoCosine (S17, default 0.90, stricter
+		// and cross-repo only). This same-repo floor is permissive by default (0.12)
+		// so recall still surfaces loosely-relevant within-repo context while
+		// rejecting effectively-unrelated hits. Mirrors src/config.ts RECALL_MIN_COSINE.
+		recallMinCosine: Number(process.env.MEGACOMPACT_RECALL_MIN_COSINE ?? "0.12"),
 		memoryAutoReview: envBool("MEGACOMPACT_MEMORY_AUTO_REVIEW", true),
 		memoryReviewInterval: envFlag("MEGACOMPACT_MEMORY_REVIEW_INTERVAL", 10),
 		recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
@@ -225,6 +231,12 @@ export function loadConfig(): MegaConfig {
 		// 3WF-1: TriggerGuard — guarantee a staged recall block on every context
 		// event even when session_start never fires. Default ON; OFF = byte-identical.
 		threeWayFailback: envBool("MEGACOMPACT_THREE_WAY_FAILBACK", true),
+		// 3WF-2: ThrashGuard re-arm budget as a fraction of effectiveThreshold.
+		// 0.10 default (10% of the effective threshold) — see mega-config-types.
+		// Clamped to [0.01, 0.5]: below 1% the guard is almost never armed (any
+		// growth re-fires, defeating the anti-thrash purpose); above 50% it would
+		// suppress legitimate re-fires for half the window. Env-overridable.
+		thrashRearmPct: clamp(envFlag("MEGACOMPACT_THRASH_REARM_PCT", 0.1), 0.01, 0.5),
 		// PC-A: positive sprint flag, default ON. =0 byte-identical to the
 		// pre-change OFF state (single gate lives at the call site in tailResult.ts).
 		messageSeparation: envBool("MEGACOMPACT_MESSAGE_SEPARATION", true),

package/extensions/mega-events/context-handler/gateCheck.ts

@@ -17,6 +17,7 @@ import {
 import { autoCompactCheck } from "../../../src/compact.js";
 import type { MegaRuntime } from "../../mega-runtime.js";
 import type { MegaConfig } from "../../mega-config.js";
+import { isThrashBlockedFor } from "./thrashGuard.js";
 
 /** Tail-injection closure shape produced by buildTailResult (tailResult.ts). */
 export type TailResultFn = (
@@ -31,6 +32,35 @@ export type GateOutcome =
 			perModelThreshold: { safetyMarginPct: number; firePointPct: number };
 	  };
 
+/**
+ * 3WF-2 ThrashGuard consult — refuse to fire a NEW compaction while the guard
+ * is armed. After an ineffective compaction (the live window did not shrink),
+ * `thrasguard.blocked_until` holds the live-token count the window must exceed
+ * before re-firing is allowed.
+ *
+ * WHY THIS IS NOT INSIDE `evaluateGate`: the fast gate runs BEFORE the cached
+ * replay path in context-handler.ts, and REPLAY MUST STAY EXEMPT. A replay is
+ * free (no compute, no new checkpoint) and re-stabilises the provider KV-cache
+ * prefix — suppressing it would cause the very cache invalidation the D.2/D.3
+ * replay design exists to prevent. The guard's job is to stop wasted NEW
+ * compaction work, not to withhold an already-computed view. So the consult is
+ * called from the handler AFTER the replay block and BEFORE the debounce +
+ * `invokePipeline` (the actual fire point), covering the percent branch and the
+ * token branch alike since both converge there.
+ *
+ * Umbrella OFF ⇒ always false (byte-identical to v0.20.83). Non-fatal: a store
+ * read error returns false — never refuse compaction on a store fault.
+ */
+export function thrashGuardBlocks(
+	runtime: MegaRuntime,
+	config: MegaConfig,
+	currentTokens: number | null | undefined,
+): boolean {
+	if (!config.threeWayFailback) return false;
+	if (currentTokens == null) return false;
+	return isThrashBlockedFor(runtime, currentTokens, runtime.currentStateDir);
+}
+
 /**
  * Evaluate whether the current context warrants compaction. Returns a tailed
  * view ("return") when the gate does not pass, or "proceed" with the resolved

package/extensions/mega-events/context-handler/thrashGuard.ts

@@ -0,0 +1,228 @@
+/**
+ * context-handler/thrashGuard.ts — 3WF-2 ReductionValidator + ThrashGuard.
+ *
+ * Production bug fixed here: compaction fired 496× freeing 0.0% of the live
+ * window. Root cause — correctness was judged by the STORED `saved` metric
+ * (a cumulative SQLite total that the dedup made look healthy every fire)
+ * while the LIVE context window (`currentTokens`) never shrank. This module
+ * judges correctness by the LIVE-WINDOW delta across consecutive `context`
+ * events, and after an ineffective compaction persists a meta-backed refusal
+ * so the guard will not re-fire until the window has grown meaningfully again.
+ *
+ * Everything is gated on the umbrella `config.threeWayFailback`
+ * (MEGACOMPACT_THREE_WAY_FAILBACK, default ON). Flag OFF ⇒ every entry point
+ * is an immediate no-op, so gateCheck + compactSession behave byte-identically
+ * to v0.20.83.
+ *
+ * Non-fatal EVERYWHERE: every store read/write is best-effort, swallowed on
+ * failure. Structured JSON logging only (runtime.logger.info with ts + event).
+ * No console.*, no network, no mocks.
+ */
+import type { MegaRuntime } from "../../mega-runtime.js";
+import type { MegaConfig } from "../../mega-config.js";
+import { getMetaNumber, setMetaNumber } from "../../../src/store/sqlite.js";
+import type { ReductionVerdict } from "../../../src/failback/types.js";
+
+/** Meta key holding the live-window baseline (tokens) at the ineffective fire. */
+export const THRASH_BASELINE_KEY = "thrasguard.baseline_tokens";
+/** Meta key holding the live-window token count below which re-firing is blocked. */
+export const THRASH_BLOCKED_KEY = "thrasguard.blocked_until";
+
+/**
+ * "Meaningful reduction" floor as a FRACTION of `liveBefore`. A compaction is
+ * only credited with freeing space when the live window shrank by at least this
+ * fraction of its pre-compaction size.
+ *
+ * Rationale (invented constant, calibrated + configurable-by-design): the model
+ * re-reports token counts on every context event with noise on the order of a
+ * percent or two, so a sub-1% wobble is not a real reduction — crediting it
+ * would suppress the guard on a genuine no-op fire (the exact bug we are
+ * fixing). 2% is a defensible "real shrink" threshold: it is well above typical
+ * re-estimation noise but low enough that a compaction that freed even a few
+ * percent of the window is not punished. A reduction of ≤0 tokens is
+ * unconditionally ineffective regardless of this floor.
+ */
+const MEANINGFUL_REDUCTION_PCT = 0.02;
+
+/** Pure reduction verdict for a live-window bracketing pair. */
+export const ReductionValidator = {
+	/**
+	 * Judge whether the LIVE window actually shrank between two consecutive
+	 * context events bracketing a compaction.
+	 *  - a reduction of ≤0 tokens ⇒ definitively ineffective.
+	 *  - otherwise effective only when the reduction is ≥ the small positive
+	 *    floor (MEANINGFUL_REDUCTION_PCT of liveBefore), so estimation noise on
+	 *    the model's re-reported token count is not mistaken for a real shrink.
+	 */
+	validateReduction(liveBefore: number, liveAfter: number): ReductionVerdict {
+		const reduction = liveBefore - liveAfter;
+		const floor = Math.max(1, Math.round(MEANINGFUL_REDUCTION_PCT * liveBefore));
+		const effective = Number.isFinite(reduction) && reduction > 0 && reduction >= floor;
+		return { effective, liveBefore, liveAfter };
+	},
+};
+
+/**
+ * Arm the ThrashGuard after an ineffective compaction. Persists:
+ *  - `thrasguard.baseline_tokens` = the live currentTokens at this (post-fire)
+ *    context event, so re-arm is measured from the window that failed to shrink.
+ *  - `thrasguard.blocked_until` = baseline + N, where N = `rearmPct ×
+ *    effectiveThreshold`. Re-firing is refused until the live window grows past
+ *    `blocked_until`.
+ *
+ * If `effectiveThreshold` is non-finite (+Infinity — the 3WF-2 invariant when
+ * the model window is unknown), N cannot be computed; we MUST NOT persist
+ * Infinity/NaN into meta (getMetaNumber would read it back as 0). Skip arming
+ * + log instead; the next over-threshold event simply re-fires (pre-sprint
+ * behavior) rather than corrupting the guard.
+ */
+export function armThrashGuard(
+	currentTokens: number,
+	rearmPct: number,
+	effectiveThreshold: number,
+	stateDir: string,
+	logger?: { info(event: string, fields?: Record<string, unknown>): void },
+): void {
+	if (!Number.isFinite(currentTokens) || currentTokens <= 0) return;
+	if (!Number.isFinite(rearmPct) || rearmPct <= 0) return;
+	if (!Number.isFinite(effectiveThreshold)) {
+		logger?.info("thrasguard_skip_arm", {
+			reason: "nonfinite_effective_threshold",
+			currentTokens,
+		});
+		return;
+	}
+	try {
+		const n = Math.round(rearmPct * effectiveThreshold);
+		setMetaNumber(THRASH_BASELINE_KEY, Math.round(currentTokens), stateDir);
+		setMetaNumber(THRASH_BLOCKED_KEY, Math.round(currentTokens + n), stateDir);
+		logger?.info("thrasguard_armed", {
+			baselineTokens: Math.round(currentTokens),
+			blockedUntilTokens: Math.round(currentTokens + n),
+			rearmTokens: n,
+		});
+	} catch {
+		/* non-fatal: best-effort meta write */
+	}
+}
+
+/**
+ * Consult the ThrashGuard for the current live-window token count. Returns true
+ * when compaction must be refused (the window is still below the armed
+ * `blocked_until`). A `blocked_until` of 0/absent ⇒ never blocked. When the
+ * live tokens have grown past `blocked_until`, the guard no longer blocks
+ * (caller re-fires normally). Pure read, best-effort — on any failure returns
+ * false (do not refuse compaction on a store error).
+ */
+export function isThrashBlocked(currentTokens: number, stateDir: string): boolean {
+	try {
+		const blockedUntil = getMetaNumber(THRASH_BLOCKED_KEY, stateDir);
+		if (blockedUntil <= 0) return false;
+		return Number.isFinite(currentTokens) && currentTokens < blockedUntil;
+	} catch {
+		return false; // non-fatal: never refuse compaction on a read error
+	}
+}
+
+/**
+ * Per-runtime one-shot session state for the live-window delta correlation.
+ * Like triggerGuard.ts, keyed by runtime in a WeakMap so it dies with the
+ * runtime and a test can pass a thin stub. Holds the live token count observed
+ * at the event that FIRED a compaction; consumed on the following context event
+ * to judge whether the window actually shrank.
+ */
+const sessionBefore = new WeakMap<MegaRuntime, { liveBefore: number }>();
+
+/**
+ * The live-token count of the event that most recently ARMED the guard, per
+ * runtime. The arming happens early in a context event (the live-delta consume
+ * point), but the guard consult runs LATER IN THAT SAME EVENT — and since
+ * `blocked_until = currentTokens + N`, a naive consult would always find
+ * `currentTokens < blocked_until` and swallow the very event that armed it.
+ * That is an off-by-one-event error: the guard's contract is to refuse
+ * SUBSEQUENT re-fires, not to cancel the compaction that revealed the problem.
+ * Recording the arming event's token count lets the consult skip exactly that
+ * one event. Cleared once the window grows past it.
+ */
+const armedOnEvent = new WeakMap<MegaRuntime, number>();
+
+/**
+ * Runtime-aware ThrashGuard consult: true when a NEW compaction must be refused.
+ *
+ * Reads the persisted `thrasguard.blocked_until` (see `isThrashBlocked`) but
+ * EXEMPTS the single event that armed the guard — otherwise, because arming sets
+ * `blocked_until = currentTokens + N` earlier in the very same context event, the
+ * consult would always fire and cancel the compaction that exposed the thrash.
+ * The guard exists to refuse SUBSEQUENT re-fires. Once the live window grows past
+ * the armed count the exemption is dropped, and normal blocking resumes until the
+ * window clears `blocked_until`.
+ *
+ * Best-effort: any failure returns false (never refuse on a store fault).
+ */
+export function isThrashBlockedFor(
+	runtime: MegaRuntime,
+	currentTokens: number,
+	stateDir: string,
+): boolean {
+	try {
+		if (!isThrashBlocked(currentTokens, stateDir)) return false;
+		const armedAt = armedOnEvent.get(runtime);
+		if (armedAt !== undefined && currentTokens === armedAt) {
+			// EXACTLY the event that armed the guard (same live-token reading): let it
+			// through once, then block normally from the next event onward. An exact
+			// match (not <=) is required so a genuinely lower or different live reading
+			// on a later event is still blocked.
+			armedOnEvent.delete(runtime);
+			return false;
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Record that a compaction fired at `liveBefore` tokens (call on the firing event). */
+export function markCompactionFired(runtime: MegaRuntime, liveBefore: number): void {
+	try {
+		if (Number.isFinite(liveBefore) && liveBefore > 0) {
+			sessionBefore.set(runtime, { liveBefore });
+		}
+	} catch {
+		/* non-fatal */
+	}
+}
+
+/**
+ * Consume a pending live-window delta on a subsequent context event. If a
+ * compaction fired on a prior event, compare THIS event's live tokens against
+ * that pre-fire baseline; an ineffective reduction arms the guard. The pending
+ * marker is consumed exactly once (cleared before any re-arm). No-op when no
+ * compaction is pending, when the umbrella flag is OFF, or on any error.
+ */
+export function evaluatePendingReduction(
+	runtime: MegaRuntime,
+	currentTokens: number,
+	config: MegaConfig,
+): void {
+	if (!config.threeWayFailback) return;
+	const pending = sessionBefore.get(runtime);
+	if (pending == null) return;
+	try {
+		sessionBefore.delete(runtime); // consume once, regardless of verdict
+		const verdict = ReductionValidator.validateReduction(pending.liveBefore, currentTokens);
+		if (!verdict.effective) {
+			// Remember which event armed us so the consult later in THIS SAME event
+			// does not swallow it (see armedOnEvent).
+			armedOnEvent.set(runtime, currentTokens);
+			armThrashGuard(
+				currentTokens,
+				config.thrashRearmPct,
+				runtime.effectiveThreshold,
+				runtime.currentStateDir,
+				runtime.logger,
+			);
+		}
+	} catch {
+		/* non-fatal */
+	}
+}