pi-mega-compact 0.20.88 → 0.21.0

package/dist/extensions/dashboard-server/routes-rag-settings-helpers.js

@@ -134,6 +134,13 @@ export const SETTINGS = [
             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),
         ],
     },
+    {
+        name: "Three-Way Failback",
+        settings: [
+            boolDirect("MEGACOMPACT_THREE_WAY_FAILBACK", "Three-Way Failback", "Umbrella for the 3-way failback safety system: TriggerGuard (stages a recall block even when session_start never fires), the live-window ReductionValidator + persisted ThrashGuard (stops ineffective compaction re-fire loops), the 3-source read-only recall vote + same-repo relevance floor, and InjectionConfirm (asserts the staged block reached the message list pi sends). OFF = byte-identical pre-3WF behavior (v0.20.83). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).", true),
+            boolDirect("MEGACOMPACT_RECALL_TAIL_INJECT", "Recall Tail Inject", "Compose the staged recall block as a trailing user message on the context event (tail inject) instead of the legacy system-prompt prepend. Tail mode keeps the cache prefix stable and is the mode InjectionConfirm verifies against ContextEvent.messages; OFF falls back to the legacy prepend path (verified by string-contains). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).", true),
+        ],
+    },
     VECTOR_CORTEX_SETTINGS,
     {
         name: "Cost API",

package/dist/extensions/mega-events/context-handler/thrashGuard.js

@@ -48,8 +48,17 @@ export const ReductionValidator = {
  * 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.
+ *
+ * 3WF-5 telemetry: `logger` is the debug-gated runtime logger (mega-compact.log,
+ * silent unless config.debug) — which means the breadcrumb was invisible to the
+ * dashboard Events tab, whose SSE tail reads the repo's events.log. `emit` is
+ * the always-on events.log sink (MegaRuntime.appendEvent), so the armed
+ * breadcrumb lands in the same stream as the other 3WF events
+ * (three_way_guard_fired / three_way_floor_used / injection_confirmed /
+ * injection_recovered). Both sinks are optional + best-effort; passing neither
+ * keeps the pre-3WF-5 behavior.
  */
-export function armThrashGuard(currentTokens, rearmPct, effectiveThreshold, stateDir, logger) {
+export function armThrashGuard(currentTokens, rearmPct, effectiveThreshold, stateDir, logger, emit) {
     if (!Number.isFinite(currentTokens) || currentTokens <= 0)
         return;
     if (!Number.isFinite(rearmPct) || rearmPct <= 0)
@@ -65,11 +74,18 @@ export function armThrashGuard(currentTokens, rearmPct, effectiveThreshold, stat
         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", {
+        const fields = {
             baselineTokens: Math.round(currentTokens),
             blockedUntilTokens: Math.round(currentTokens + n),
             rearmTokens: n,
-        });
+        };
+        logger?.info("thrasguard_armed", fields);
+        try {
+            emit?.("thrasguard_armed", fields);
+        }
+        catch {
+            /* non-fatal: events.log sink must never break arming */
+        }
     }
     catch {
         /* non-fatal: best-effort meta write */
@@ -177,7 +193,13 @@ export function evaluatePendingReduction(runtime, currentTokens, config) {
             // 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);
+            // 3WF-5: also emit the breadcrumb on the always-on events.log sink so
+            // the dashboard Events tab sees it (runtime.logger is debug-gated).
+            // Optional-chained: a thin runtime stub without appendEvent stays valid.
+            const emit = typeof runtime.appendEvent === "function"
+                ? runtime.appendEvent.bind(runtime)
+                : undefined;
+            armThrashGuard(currentTokens, config.thrashRearmPct, runtime.effectiveThreshold, runtime.currentStateDir, runtime.logger, emit);
         }
     }
     catch {

package/dist/extensions/mega-events/context-handler/threeWayTelemetry.fixture.js

@@ -0,0 +1,128 @@
+/**
+ * context-handler/threeWayTelemetry.fixture.ts — shared fixtures for the 3WF-5
+ * telemetry verification tests.
+ *
+ * Split out so the test file stays under the soft cap, mirroring
+ * src/recall/recall3wf.fixture.ts (3WF-3) and injectionConfirm.fixture.ts (3WF-4).
+ *
+ * These are REAL fixtures, not mocks/stubs. The critical difference from the
+ * 3WF-1..4 fixtures: those record `appendEvent` calls into an in-memory array,
+ * which proves the CALL happened but says nothing about the wire format or the
+ * file the dashboard actually tails. Here `appendEvent` is wired to the REAL
+ * `appendEventImpl` (extensions/mega-runtime/append-event.ts) against a temp
+ * stateDir, so each breadcrumb is serialized to a real events.log exactly as it
+ * is in production. The tests then read that file back and parse the JSON — the
+ * `ts` + `event` shape is observed, never simulated.
+ */
+import { mkdtempSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { VectorStore } from "../../../src/vectorStore.js";
+import { compactSession } from "../../../src/engine.js";
+import { appendEventImpl } from "../../mega-runtime/append-event.js";
+/** Real EngineMessage fixture. */
+export function msg(role, text) {
+    return { role, text };
+}
+/** A user-role AgentMessage carrying `text` (the tail-block shape). */
+export function userMsg(text) {
+    return { role: "user", content: text, timestamp: 1 };
+}
+/** Fresh isolated state dir per VectorStore. */
+export function freshStore() {
+    const dir = mkdtempSync(join(tmpdir(), "mc-3wf5-"));
+    return { store: new VectorStore({ dedupSim: 0.9, stateDir: dir }), dir };
+}
+/** Persist N distinct checkpoints with ascending timestamps. */
+export function seed(store, topics, sid) {
+    topics.forEach((t, i) => {
+        compactSession({
+            sessionId: sid,
+            messages: [msg("user", t), msg("assistant", "ok")],
+            keepFrom: 2,
+            timestamp: i + 1,
+        }, store);
+    });
+}
+/**
+ * Read + JSON-parse every line of the REAL events.log written under `stateDir`.
+ * PREVENT-001: parse failures are surfaced as null and filtered, never thrown.
+ */
+export function readEventsLog(stateDir) {
+    const path = join(stateDir, "events.log");
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, "utf-8")
+        .split("\n")
+        .filter((l) => l.trim().length > 0)
+        .map((line) => {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed == null || typeof parsed !== "object")
+                return null;
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((e) => e != null);
+}
+/** Silent logger (the debug-gated sink is not under test here). */
+export const noopLogger = {
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+/**
+ * MegaRuntime whose `appendEvent` is the REAL events.log writer bound to
+ * `stateDir`. Only the fields the 3WF guards touch are populated.
+ */
+export function realEventRuntime(store, stateDir, over = {}) {
+    const self = {
+        store,
+        currentStateDir: stateDir,
+        pendingRecallBlock: over.pendingRecallBlock,
+        pendingMemoryRecallBlock: over.pendingMemoryRecallBlock,
+        effectiveThreshold: over.effectiveThreshold ?? 100_000,
+        lastCtxWindow: 0,
+        logger: noopLogger,
+        perfTurnStart: undefined,
+        rt: { recallInjectedThisTurn: false, lastCheckpointId: null },
+        appendEvent(event, fields) {
+            appendEventImpl({ currentStateDir: stateDir }, event, fields);
+        },
+    };
+    return self;
+}
+/** ctx stub with a configurable session id + latest-user query. */
+export function ctxStub(opts = {}) {
+    const sessionId = opts.sessionId ?? "sess_3wf5";
+    const query = opts.query ?? "dedupe race in store";
+    return {
+        cwd: "/tmp",
+        sessionManager: {
+            getSessionId: () => sessionId,
+            getEntries: () => [
+                {
+                    type: "message",
+                    id: "e1",
+                    parentId: null,
+                    timestamp: "1",
+                    message: { role: "user", content: query },
+                },
+            ],
+        },
+    };
+}
+/** Config stub: only the flags the 3WF guards read. */
+export function configStub(over = {}) {
+    return {
+        threeWayFailback: over.threeWayFailback ?? true,
+        recallTailInject: over.recallTailInject ?? true,
+        thrashRearmPct: over.thrashRearmPct ?? 0.1,
+        autoInlineK: 3,
+        tier: "custom",
+        tierPct: null,
+    };
+}

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

@@ -296,6 +296,23 @@ export const SETTINGS: ReadonlyArray<SettingGroup> = [
 			),
 		],
 	},
+	{
+		name: "Three-Way Failback",
+		settings: [
+			boolDirect(
+				"MEGACOMPACT_THREE_WAY_FAILBACK",
+				"Three-Way Failback",
+				"Umbrella for the 3-way failback safety system: TriggerGuard (stages a recall block even when session_start never fires), the live-window ReductionValidator + persisted ThrashGuard (stops ineffective compaction re-fire loops), the 3-source read-only recall vote + same-repo relevance floor, and InjectionConfirm (asserts the staged block reached the message list pi sends). OFF = byte-identical pre-3WF behavior (v0.20.83). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).",
+				true,
+			),
+			boolDirect(
+				"MEGACOMPACT_RECALL_TAIL_INJECT",
+				"Recall Tail Inject",
+				"Compose the staged recall block as a trailing user message on the context event (tail inject) instead of the legacy system-prompt prepend. Tail mode keeps the cache prefix stable and is the mode InjectionConfirm verifies against ContextEvent.messages; OFF falls back to the legacy prepend path (verified by string-contains). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).",
+				true,
+			),
+		],
+	},
 	VECTOR_CORTEX_SETTINGS,
 	{
 		name: "Cost API",

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

@@ -75,6 +75,15 @@ export const ReductionValidator = {
  * 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.
+ *
+ * 3WF-5 telemetry: `logger` is the debug-gated runtime logger (mega-compact.log,
+ * silent unless config.debug) — which means the breadcrumb was invisible to the
+ * dashboard Events tab, whose SSE tail reads the repo's events.log. `emit` is
+ * the always-on events.log sink (MegaRuntime.appendEvent), so the armed
+ * breadcrumb lands in the same stream as the other 3WF events
+ * (three_way_guard_fired / three_way_floor_used / injection_confirmed /
+ * injection_recovered). Both sinks are optional + best-effort; passing neither
+ * keeps the pre-3WF-5 behavior.
  */
 export function armThrashGuard(
 	currentTokens: number,
@@ -82,6 +91,7 @@ export function armThrashGuard(
 	effectiveThreshold: number,
 	stateDir: string,
 	logger?: { info(event: string, fields?: Record<string, unknown>): void },
+	emit?: (event: string, fields: Record<string, unknown>) => void,
 ): void {
 	if (!Number.isFinite(currentTokens) || currentTokens <= 0) return;
 	if (!Number.isFinite(rearmPct) || rearmPct <= 0) return;
@@ -96,11 +106,17 @@ export function armThrashGuard(
 		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", {
+		const fields = {
 			baselineTokens: Math.round(currentTokens),
 			blockedUntilTokens: Math.round(currentTokens + n),
 			rearmTokens: n,
-		});
+		};
+		logger?.info("thrasguard_armed", fields);
+		try {
+			emit?.("thrasguard_armed", fields);
+		} catch {
+			/* non-fatal: events.log sink must never break arming */
+		}
 	} catch {
 		/* non-fatal: best-effort meta write */
 	}
@@ -214,12 +230,20 @@ export function evaluatePendingReduction(
 			// Remember which event armed us so the consult later in THIS SAME event
 			// does not swallow it (see armedOnEvent).
 			armedOnEvent.set(runtime, currentTokens);
+			// 3WF-5: also emit the breadcrumb on the always-on events.log sink so
+			// the dashboard Events tab sees it (runtime.logger is debug-gated).
+			// Optional-chained: a thin runtime stub without appendEvent stays valid.
+			const emit =
+				typeof runtime.appendEvent === "function"
+					? runtime.appendEvent.bind(runtime)
+					: undefined;
 			armThrashGuard(
 				currentTokens,
 				config.thrashRearmPct,
 				runtime.effectiveThreshold,
 				runtime.currentStateDir,
 				runtime.logger,
+				emit,
 			);
 		}
 	} catch {

package/extensions/mega-events/context-handler/threeWayTelemetry.fixture.ts

@@ -0,0 +1,164 @@
+/**
+ * context-handler/threeWayTelemetry.fixture.ts — shared fixtures for the 3WF-5
+ * telemetry verification tests.
+ *
+ * Split out so the test file stays under the soft cap, mirroring
+ * src/recall/recall3wf.fixture.ts (3WF-3) and injectionConfirm.fixture.ts (3WF-4).
+ *
+ * These are REAL fixtures, not mocks/stubs. The critical difference from the
+ * 3WF-1..4 fixtures: those record `appendEvent` calls into an in-memory array,
+ * which proves the CALL happened but says nothing about the wire format or the
+ * file the dashboard actually tails. Here `appendEvent` is wired to the REAL
+ * `appendEventImpl` (extensions/mega-runtime/append-event.ts) against a temp
+ * stateDir, so each breadcrumb is serialized to a real events.log exactly as it
+ * is in production. The tests then read that file back and parse the JSON — the
+ * `ts` + `event` shape is observed, never simulated.
+ */
+import { mkdtempSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { VectorStore } from "../../../src/vectorStore.js";
+import { compactSession } from "../../../src/engine.js";
+import { appendEventImpl } from "../../mega-runtime/append-event.js";
+import type { MegaRuntime } from "../../mega-runtime.js";
+import type { MegaConfig } from "../../mega-config.js";
+import type { Logger } from "../../../src/log.js";
+
+/** Real EngineMessage fixture. */
+export function msg(role: "user" | "assistant", text: string): any {
+	return { role, text };
+}
+
+/** A user-role AgentMessage carrying `text` (the tail-block shape). */
+export function userMsg(text: string): AgentMessage {
+	return { role: "user", content: text, timestamp: 1 } as unknown as AgentMessage;
+}
+
+/** One parsed events.log line. `ts` + `event` are the contract the dashboard
+ *  Events tab (server.ts SSE tail of stateDir/events.log) consumes. */
+export interface LoggedEvent {
+	ts: unknown;
+	event: unknown;
+	[k: string]: unknown;
+}
+
+/** Fresh isolated state dir per VectorStore. */
+export function freshStore(): { store: VectorStore; dir: string } {
+	const dir = mkdtempSync(join(tmpdir(), "mc-3wf5-"));
+	return { store: new VectorStore({ dedupSim: 0.9, stateDir: dir }), dir };
+}
+
+/** Persist N distinct checkpoints with ascending timestamps. */
+export function seed(store: VectorStore, topics: string[], sid: string): void {
+	topics.forEach((t, i) => {
+		compactSession(
+			{
+				sessionId: sid,
+				messages: [msg("user", t), msg("assistant", "ok")],
+				keepFrom: 2,
+				timestamp: i + 1,
+			},
+			store,
+		);
+	});
+}
+
+/**
+ * Read + JSON-parse every line of the REAL events.log written under `stateDir`.
+ * PREVENT-001: parse failures are surfaced as null and filtered, never thrown.
+ */
+export function readEventsLog(stateDir: string): LoggedEvent[] {
+	const path = join(stateDir, "events.log");
+	if (!existsSync(path)) return [];
+	return readFileSync(path, "utf-8")
+		.split("\n")
+		.filter((l) => l.trim().length > 0)
+		.map((line): LoggedEvent | null => {
+			try {
+				const parsed: unknown = JSON.parse(line);
+				if (parsed == null || typeof parsed !== "object") return null;
+				return parsed as LoggedEvent;
+			} catch {
+				return null;
+			}
+		})
+		.filter((e): e is LoggedEvent => e != null);
+}
+
+/** Silent logger (the debug-gated sink is not under test here). */
+export const noopLogger: Logger = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+} as unknown as Logger;
+
+/**
+ * MegaRuntime whose `appendEvent` is the REAL events.log writer bound to
+ * `stateDir`. Only the fields the 3WF guards touch are populated.
+ */
+export function realEventRuntime(
+	store: VectorStore,
+	stateDir: string,
+	over: Partial<{
+		pendingRecallBlock: string | undefined;
+		pendingMemoryRecallBlock: string | undefined;
+		effectiveThreshold: number;
+	}> = {},
+): MegaRuntime {
+	const self = {
+		store,
+		currentStateDir: stateDir,
+		pendingRecallBlock: over.pendingRecallBlock,
+		pendingMemoryRecallBlock: over.pendingMemoryRecallBlock,
+		effectiveThreshold: over.effectiveThreshold ?? 100_000,
+		lastCtxWindow: 0,
+		logger: noopLogger,
+		perfTurnStart: undefined,
+		rt: { recallInjectedThisTurn: false, lastCheckpointId: null as string | null },
+		appendEvent(event: string, fields: Record<string, unknown>): void {
+			appendEventImpl({ currentStateDir: stateDir }, event, fields);
+		},
+	};
+	return self as unknown as MegaRuntime;
+}
+
+/** ctx stub with a configurable session id + latest-user query. */
+export function ctxStub(opts: { sessionId?: string; query?: string } = {}): any {
+	const sessionId = opts.sessionId ?? "sess_3wf5";
+	const query = opts.query ?? "dedupe race in store";
+	return {
+		cwd: "/tmp",
+		sessionManager: {
+			getSessionId: () => sessionId,
+			getEntries: () => [
+				{
+					type: "message",
+					id: "e1",
+					parentId: null,
+					timestamp: "1",
+					message: { role: "user", content: query },
+				},
+			],
+		},
+	};
+}
+
+/** Config stub: only the flags the 3WF guards read. */
+export function configStub(
+	over: Partial<{
+		threeWayFailback: boolean;
+		recallTailInject: boolean;
+		thrashRearmPct: number;
+	}> = {},
+): MegaConfig {
+	return {
+		threeWayFailback: over.threeWayFailback ?? true,
+		recallTailInject: over.recallTailInject ?? true,
+		thrashRearmPct: over.thrashRearmPct ?? 0.1,
+		autoInlineK: 3,
+		tier: "custom",
+		tierPct: null,
+	} as unknown as MegaConfig;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.88",
+  "version": "0.21.0",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",