pi-mega-compact 0.20.83 → 0.20.84

package/dist/extensions/mega-config.js

@@ -167,6 +167,9 @@ export function loadConfig() {
         recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
         windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
         recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
+        // 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),
         // 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/dist/extensions/mega-events/context-handler/triggerGuard.js

@@ -0,0 +1,86 @@
+import { normalizeSessionId } from "../../../src/store.js";
+import { recall } from "../../../src/engine.js";
+import { formatRecallBlock } from "../../../src/recall.js";
+import { vectorStats, vectorList } from "../../../src/vectorStore.js";
+import { recentUserQuery } from "../../mega-runtime.js";
+/** One-shot completion marker per MegaRuntime (dies with the runtime). */
+const guardDone = new WeakMap();
+/**
+ * Run the TriggerGuard for this context event. Best-effort: never throws; any
+ * failure degrades to the pre-sprint path (no staged block).
+ */
+export function runTriggerGuard(runtime, config, ctx) {
+    try {
+        // Flag OFF => byte-identical pre-sprint behavior (no touch, no telemetry).
+        if (!config.threeWayFailback)
+            return;
+        // session_start already staged a block => the normal path wins, no-op.
+        if (runtime.pendingRecallBlock != null)
+            return;
+        // One-shot: we've already decided for this runtime.
+        if (guardDone.has(runtime))
+            return;
+        // recentUserQuery only reads sessionManager.getEntries(); the structural
+        // GuardCtx satisfies it at runtime (cast to the full type it expects).
+        const query = recentUserQuery(ctx);
+        if (!query) {
+            guardDone.set(runtime, { done: true });
+            return;
+        }
+        const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+        const stats = vectorStats(runtime.store, sid);
+        // Empty store => genuinely new session; not a recall failure. Mark done so
+        // we don't re-check forever, stage nothing (no crash, no floor).
+        if (stats.checkpointCount <= 0) {
+            guardDone.set(runtime, { done: true });
+            return;
+        }
+        // Read-only recall: search + rank only; skipInjected:false means we keep
+        // hits already injected this session, but we never call vectorMarkInjected
+        // ourselves (A1) — formatRecallBlock does the same as session_start uses.
+        const hits = recall({ sessionId: sid, query, limit: config.autoInlineK, skipInjected: false }, runtime.store).hits;
+        if (hits.length > 0) {
+            runtime.pendingRecallBlock = formatRecallBlock(hits);
+            guardDone.set(runtime, { done: true });
+            runtime.appendEvent("three_way_guard_fired", {
+                source: "recall",
+                hitCount: hits.length,
+                topScore: hits[0]?.score ?? null,
+            });
+            return;
+        }
+        // Store HAS checkpoints but recall found nothing relevant: stage a
+        // provenance floor built from the newest checkpoint summary rather than
+        // silence (the incident's "recall silently never ran" shape).
+        const floor = buildFloorBlock(runtime, sid);
+        runtime.pendingRecallBlock = floor;
+        guardDone.set(runtime, { done: true });
+        runtime.appendEvent("three_way_floor_used", { basis: "lastCheckpoint" });
+    }
+    catch {
+        /* never throws; best-effort guard */
+    }
+}
+/** Build the provenance floor string from the session's newest checkpoint. */
+function buildFloorBlock(runtime, sid) {
+    try {
+        const cps = vectorList(runtime.store, sid);
+        let newest = cps[0];
+        for (const cp of cps) {
+            if (!newest || (cp.timestamp ?? 0) > (newest.timestamp ?? 0))
+                newest = cp;
+        }
+        const summary = newest?.summary?.trim();
+        if (summary) {
+            return ("The following compacted context is the most recent checkpoint from " +
+                "this session (recall found no query-relevant match):\n\n" + summary);
+        }
+        return ("This session has compacted context but recall could not surface a " +
+            "checkpoint relevant to the current request; the most recent checkpoint " +
+            "summary is unavailable.");
+    }
+    catch {
+        return ("This session has compacted context but recall could not surface a " +
+            "checkpoint relevant to the current request.");
+    }
+}

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

@@ -1,6 +1,7 @@
 import { estimateSessionTokens } from "../../src/tokens.js";
 import { piCompactWouldNoop } from "../mega-pipeline.js";
 import { buildTailResult } from "./context-handler/tailResult.js";
+import { runTriggerGuard } from "./context-handler/triggerGuard.js";
 import { persistEpochAndMaintain } from "./context-handler/afterCompact.js";
 import { appendMirrorAndLedger } from "./context-handler/dbMirrorAppend.js";
 import { evaluateGate } from "./context-handler/gateCheck.js";
@@ -26,6 +27,17 @@ export function registerContextHandler(pi, runtime, config) {
         const usage = ctx.getContextUsage();
         const pct = usage?.percent;
         const messages = event.messages;
+        // 3WF-1 TriggerGuard: guarantee a staged recall block on this event even
+        // when session_start never fired. One-shot per session; a block already
+        // staged by session_start takes precedence (no-op). Run BEFORE building the
+        // tail factory so a freshly staged block is composed into THIS event's view.
+        // Best-effort — a failure falls through to the pre-sprint path.
+        try {
+            runTriggerGuard(runtime, config, ctx);
+        }
+        catch {
+            /* non-fatal */
+        }
         // S53: helper to inject the staged recall/memory block as a user-role
         // tail message at any view-return point. Returns undefined when nothing
         // is staged (or the flag is OFF) so the caller falls through to its

package/dist/src/failback/types.js

@@ -0,0 +1,11 @@
+/**
+ * src/failback/types.ts — 3WF Three-Way Failback contract types (contract-first).
+ *
+ * Pure, pi-agnostic interfaces describing the staged-recall guarantee chain:
+ * every session should have a staged recall block even when `session_start`
+ * never fires. 3WF-1 (TriggerGuard) is the first consumer; 3WF-2/3/4 extend
+ * these shapes for the compaction ladder, the 3-source recall vote, and
+ * InjectionConfirm. No pi runtime imports, no store mutation — these are the
+ * shape contract only.
+ */
+export {};

package/extensions/mega-config-types.ts

@@ -136,6 +136,10 @@ export interface MegaConfig {
 	 *  the tail of the view when auto is OFF AND no trim action is needed. Default ON
 	 *  (true). When false, restores the pre-sprint systemPrompt prepend behavior. */
 	recallTailInject: boolean;
+	/** 3WF-1: TriggerGuard — re-stage a recall block at the context event seam when
+	 *  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;
 	/** 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

@@ -203,6 +203,9 @@ export function loadConfig(): MegaConfig {
 		recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
 		windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
 		recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
+		// 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),
 		// 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/triggerGuard.ts

@@ -0,0 +1,137 @@
+/**
+ * extensions/mega-events/context-handler/triggerGuard.ts — 3WF-1 TriggerGuard.
+ *
+ * Production-incident fix: `session_start` can silently never fire (pi host
+ * behavior), so the only recall staging point (session-handlers.ts) is skipped
+ * and a session replays with NO recall block and NO telemetry. TriggerGuard
+ * re-stages at the `context` event seam — the one place that ALWAYS runs and
+ * where the staged block is composed into the model view on this same event.
+ *
+ * Stack position (context-handler.ts): run DIRECTLY BEFORE `buildTailResult` is
+ * built, so a freshly staged block is picked up by the existing tail machinery
+ * (recall-tail.ts) with zero changes to it.
+ *
+ * Contract:
+ *  - one-shot per MegaRuntime (WeakMap) — recall does NOT re-run on every event.
+ *  - if runtime.pendingRecallBlock != null already, no-op (session_start won).
+ *  - read-only recall via engine.recall -> formatRecallBlock; no vectorMarkInjected,
+ *    no S43 telemetry, no turn writes (this is a guard, not an inline).
+ *  - an empty store (checkpointCount == 0) is a genuinely new session: no crash,
+ *    no floor staged, just marked done.
+ *  - a store WITH checkpoints whose recall returns nothing: stage the provenance
+ *    floor (newest checkpoint summary) instead of silence.
+ *  - never throws (whole body guarded), non-fatal, PREVENT-PI-003 (block is plain
+ *    text; role decided downstream by withRecallTail as user).
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { MegaRuntime } from "../../mega-runtime.js";
+import type { MegaConfig } from "../../mega-config.js";
+import { normalizeSessionId } from "../../../src/store.js";
+import { recall } from "../../../src/engine.js";
+import { formatRecallBlock } from "../../../src/recall.js";
+import { vectorStats, vectorList } from "../../../src/vectorStore.js";
+import { recentUserQuery } from "../../mega-runtime.js";
+
+/** One-shot completion marker per MegaRuntime (dies with the runtime). */
+const guardDone = new WeakMap<MegaRuntime, { done: true }>();
+
+/** The minimal ctx surface the guard reads (query + session id). Accepted instead
+ *  of the full ExtensionContext so tests can pass a thin stub without a full
+ *  pi ctx; structurally satisfied by the real ExtensionContext. */
+interface GuardCtx {
+	sessionManager: { getSessionId(): string };
+}
+
+
+/**
+ * Run the TriggerGuard for this context event. Best-effort: never throws; any
+ * failure degrades to the pre-sprint path (no staged block).
+ */
+export function runTriggerGuard(
+	runtime: MegaRuntime,
+	config: MegaConfig,
+	ctx: GuardCtx,
+): void {
+	try {
+		// Flag OFF => byte-identical pre-sprint behavior (no touch, no telemetry).
+		if (!config.threeWayFailback) return;
+		// session_start already staged a block => the normal path wins, no-op.
+		if (runtime.pendingRecallBlock != null) return;
+		// One-shot: we've already decided for this runtime.
+		if (guardDone.has(runtime)) return;
+
+		// recentUserQuery only reads sessionManager.getEntries(); the structural
+		// GuardCtx satisfies it at runtime (cast to the full type it expects).
+		const query = recentUserQuery(ctx as unknown as ExtensionContext);
+		if (!query) {
+			guardDone.set(runtime, { done: true });
+			return;
+		}
+
+		const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+		const stats = vectorStats(runtime.store, sid);
+		// Empty store => genuinely new session; not a recall failure. Mark done so
+		// we don't re-check forever, stage nothing (no crash, no floor).
+		if (stats.checkpointCount <= 0) {
+			guardDone.set(runtime, { done: true });
+			return;
+		}
+
+		// Read-only recall: search + rank only; skipInjected:false means we keep
+		// hits already injected this session, but we never call vectorMarkInjected
+		// ourselves (A1) — formatRecallBlock does the same as session_start uses.
+		const hits = recall(
+			{ sessionId: sid, query, limit: config.autoInlineK, skipInjected: false },
+			runtime.store,
+		).hits;
+
+		if (hits.length > 0) {
+			runtime.pendingRecallBlock = formatRecallBlock(hits);
+			guardDone.set(runtime, { done: true });
+			runtime.appendEvent("three_way_guard_fired", {
+				source: "recall",
+				hitCount: hits.length,
+				topScore: hits[0]?.score ?? null,
+			});
+			return;
+		}
+
+		// Store HAS checkpoints but recall found nothing relevant: stage a
+		// provenance floor built from the newest checkpoint summary rather than
+		// silence (the incident's "recall silently never ran" shape).
+		const floor = buildFloorBlock(runtime, sid);
+		runtime.pendingRecallBlock = floor;
+		guardDone.set(runtime, { done: true });
+		runtime.appendEvent("three_way_floor_used", { basis: "lastCheckpoint" });
+	} catch {
+		/* never throws; best-effort guard */
+	}
+}
+
+/** Build the provenance floor string from the session's newest checkpoint. */
+function buildFloorBlock(runtime: MegaRuntime, sid: string): string {
+	try {
+		const cps = vectorList(runtime.store, sid);
+		let newest = cps[0];
+		for (const cp of cps) {
+			if (!newest || (cp.timestamp ?? 0) > (newest.timestamp ?? 0)) newest = cp;
+		}
+		const summary = newest?.summary?.trim();
+		if (summary) {
+			return (
+				"The following compacted context is the most recent checkpoint from " +
+				"this session (recall found no query-relevant match):\n\n" + summary
+			);
+		}
+		return (
+			"This session has compacted context but recall could not surface a " +
+			"checkpoint relevant to the current request; the most recent checkpoint " +
+			"summary is unavailable."
+		);
+	} catch {
+		return (
+			"This session has compacted context but recall could not surface a " +
+			"checkpoint relevant to the current request."
+		);
+	}
+}

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

@@ -23,6 +23,7 @@ import type { MegaRuntime } from "../mega-runtime.js";
 import { piCompactWouldNoop } from "../mega-pipeline.js";
 import type { MegaConfig } from "../mega-config.js";
 import { buildTailResult } from "./context-handler/tailResult.js";
+import { runTriggerGuard } from "./context-handler/triggerGuard.js";
 import { persistEpochAndMaintain } from "./context-handler/afterCompact.js";
 import { appendMirrorAndLedger } from "./context-handler/dbMirrorAppend.js";
 import { evaluateGate } from "./context-handler/gateCheck.js";
@@ -53,6 +54,16 @@ export function registerContextHandler(
 		const usage = ctx.getContextUsage();
 		const pct = usage?.percent;
 		const messages = event.messages;
+		// 3WF-1 TriggerGuard: guarantee a staged recall block on this event even
+		// when session_start never fired. One-shot per session; a block already
+		// staged by session_start takes precedence (no-op). Run BEFORE building the
+		// tail factory so a freshly staged block is composed into THIS event's view.
+		// Best-effort — a failure falls through to the pre-sprint path.
+		try {
+			runTriggerGuard(runtime, config, ctx);
+		} catch {
+			/* non-fatal */
+		}
 		// S53: helper to inject the staged recall/memory block as a user-role
 		// tail message at any view-return point. Returns undefined when nothing
 		// is staged (or the flag is OFF) so the caller falls through to its

package/package.json

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

package/src/failback/types.ts

@@ -0,0 +1,46 @@
+/**
+ * src/failback/types.ts — 3WF Three-Way Failback contract types (contract-first).
+ *
+ * Pure, pi-agnostic interfaces describing the staged-recall guarantee chain:
+ * every session should have a staged recall block even when `session_start`
+ * never fires. 3WF-1 (TriggerGuard) is the first consumer; 3WF-2/3/4 extend
+ * these shapes for the compaction ladder, the 3-source recall vote, and
+ * InjectionConfirm. No pi runtime imports, no store mutation — these are the
+ * shape contract only.
+ */
+
+/** One-shot guard state for a session (observable result of a TriggerGuard run). */
+export interface TriggerGuardState {
+	/** True once a recall/floor attempt has run for this session. */
+	recallRan: boolean;
+	/** The block staged into runtime.pendingRecallBlock (null when nothing staged). */
+	stagedBlock: string | null;
+	/** True when the provenance floor (not a recall hit) was staged. */
+	usedFloor: boolean;
+}
+
+/** A provenance floor string built from the newest checkpoint / session basis. */
+export interface FloorBlock {
+	/** The model-visible floor text. */
+	text: string;
+	/** Why this floor was produced. */
+	basis: "lastCheckpoint" | "sessionProvenance" | "none";
+}
+
+/** Result of a single TriggerGuard evaluation (for tests + telemetry). */
+export interface GuardRunResult {
+	/** How the block (or non-block) was produced. */
+	source: "already-staged" | "recall" | "floor" | "none";
+	/** The staged block text; null when nothing was staged. */
+	block: string | null;
+}
+
+/** Options the TriggerGuard needs to run a staged recall. */
+export interface GuardOpts {
+	/** The latest user message used as the recall query; empty => 'none'. */
+	query: string | null;
+	/** Normalized session id. */
+	sessionId: string;
+	/** Max hits to recall (mirrors autoInlineK). */
+	limit: number;
+}