pi-mega-compact 0.20.87 → 0.20.88

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

@@ -0,0 +1,63 @@
+/**
+ * context-handler/injectionConfirm.fixture.ts — shared fixtures for the 3WF-4
+ * InjectionConfirm tests.
+ *
+ * Split out so each test file stays under the extensions/300-soft-cap the way
+ * src/recall/recall3wf.fixture.ts does for 3WF-3. These are REAL fixtures, not
+ * mocks/stubs: a REAL VectorStore over a temp stateDir with REAL checkpoints
+ * persisted via compactSession; the MegaRuntime is a minimal typed stub exposing
+ * only the fields confirmInjection touches (store, pendingRecallBlock,
+ * pendingMemoryRecallBlock, appendEvent), matching the triggerGuard/thrashGuard
+ * test conventions.
+ */
+import { mkdtempSync } 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";
+/** 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-inject-"));
+    return { store: new VectorStore({ dedupSim: 0.9, stateDir: dir }), dir };
+}
+/** Persist N distinct checkpoints with ascending timestamps. */
+export function seed(store, topics, sid = "sess_inject") {
+    topics.forEach((t, i) => {
+        compactSession({
+            sessionId: sid,
+            messages: [msg("user", t), msg("assistant", "ok")],
+            keepFrom: 2,
+            timestamp: i + 1,
+        }, store);
+    });
+}
+/** Minimal MegaRuntime stub exposing only the confirmInjection touch-points. */
+export function runtimeStub(store, over = {}) {
+    const events = [];
+    const runtime = {
+        store,
+        pendingRecallBlock: over.pendingRecallBlock,
+        pendingMemoryRecallBlock: over.pendingMemoryRecallBlock,
+        perfTurnStart: undefined,
+        rt: { recallInjectedThisTurn: false },
+        appendEvent: (name, payload) => {
+            events.push({ name, payload });
+        },
+    };
+    return { runtime, events };
+}
+/** Config stub: only the flags confirmInjection reads. */
+export function configStub(over = {}) {
+    return {
+        threeWayFailback: over.threeWayFailback ?? true,
+        recallTailInject: over.recallTailInject ?? true,
+    };
+}

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

@@ -0,0 +1,107 @@
+import { vectorList } from "../../../src/vectorStore.js";
+import { normalizeSessionId } from "../../../src/store.js";
+import { buildFloorBlock } from "../../../src/failback/floor.js";
+import { withRecallTail } from "../recall-tail.js";
+import { messageContentText } from "./messageText.js";
+/**
+ * The marker substring used to locate a staged block inside a message. The
+ * block's first non-empty line, capped, so prompt reshapes (cache striping /
+ * message separation) that regroup messages cannot defeat the match, while a
+ * genuinely dropped block still fails it.
+ */
+export function blockMarker(block) {
+    const line = block
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    return (line ?? "").slice(0, 80);
+}
+/**
+ * PURE decision function: did the staged block land in this view, and if not,
+ * which rung should repair it? Takes the already-extracted message texts so it
+ * stays free of pi types and is directly unit-testable.
+ */
+export function decideInjection(input, messageTexts, hasPendingBlocks) {
+    const marker = input.staged ? blockMarker(input.staged) : "";
+    // Nothing staged => nothing to assert; NOT a miss. Injecting a floor here
+    // would push provenance text into sessions that never had recall to lose.
+    if (!marker)
+        return { landed: true, recovered: "none" };
+    const landed = messageTexts.some((t) => t.includes(marker));
+    if (landed)
+        return { landed: true, recovered: "none" };
+    // Absent: recompose when the runtime still holds pending blocks, else floor.
+    return { landed: false, recovered: hasPendingBlocks ? "recomposed" : "floor" };
+}
+/** Append `text` as a user-role tail message (same shape as recall-tail.ts). */
+function withFloorTail(view, text) {
+    const tailMsg = {
+        role: "user",
+        content: text,
+        timestamp: Date.now(),
+    };
+    return { messages: [...view.messages, tailMsg] };
+}
+/**
+ * Thin caller: verify (and if needed repair) one composed view. Returns the view
+ * to actually return from the handler. `sessionId` sources the floor checkpoints.
+ *
+ * The recompose rung deliberately re-appends via `withRecallTail` onto the
+ * ALREADY-COMPOSED view rather than re-running `buildTailResult`: the reshape
+ * stages (cache striping / message separation) are the realistic way a tail
+ * message gets regrouped away, and re-running the same composition would
+ * reproduce the same loss. Appending after the reshape is the actual repair, and
+ * it keeps the PREVENT-PI-001/002 tail-append invariant (a single user-role
+ * message after a complete prefix can never split a toolCall/toolResult pair).
+ */
+export function confirmInjection(runtime, config, view, sessionId) {
+    try {
+        if (!config.threeWayFailback)
+            return view;
+        // What the tail composition was supposed to inject. BOTH staged blocks
+        // count: withRecallTail joins recall + memory blocks into one tail
+        // message, so either one going missing is a real injection failure.
+        const staged = runtime.pendingRecallBlock ?? runtime.pendingMemoryRecallBlock ?? null;
+        // Can the recompose rung actually re-append? Only when a block is still
+        // staged on the runtime. When it is not (blocks consumed between
+        // composition and this check), or when withRecallTail declines to append,
+        // the ladder falls through to the floor rung below.
+        const hasPending = runtime.pendingRecallBlock != null ||
+            runtime.pendingMemoryRecallBlock != null;
+        // Legacy prepend mode: the block is not expected in the message list —
+        // verify our composed return value contains it instead (A3 degrade path).
+        if (!config.recallTailInject) {
+            const composed = view.messages.map(messageContentText).join("\n");
+            const marker = staged ? blockMarker(staged) : "";
+            runtime.appendEvent("injection_confirmed", {
+                mode: "prepend",
+                landed: marker ? composed.includes(marker) : true,
+            });
+            return view;
+        }
+        const verdict = decideInjection({ staged, tailMode: true }, view.messages.map(messageContentText), hasPending);
+        if (verdict.landed) {
+            runtime.appendEvent("injection_confirmed", { mode: "tail", landed: true });
+            return view;
+        }
+        if (verdict.recovered === "recomposed") {
+            const rebuilt = withRecallTail(view.messages, runtime, config);
+            // withRecallTail returns the input array unchanged on failure; only
+            // treat a genuine append as a recovery.
+            if (rebuilt.length > view.messages.length) {
+                runtime.appendEvent("injection_recovered", { via: "recomposed" });
+                return { messages: rebuilt };
+            }
+        }
+        const floor = buildFloorBlock(vectorList(runtime.store, normalizeSessionId(sessionId)));
+        runtime.appendEvent("injection_recovered", {
+            via: "floor",
+            basis: floor.basis,
+        });
+        return withFloorTail(view, floor.text);
+    }
+    catch {
+        // Non-fatal: return the unverified view (pre-sprint behavior).
+        return view;
+    }
+}

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

@@ -2,6 +2,7 @@ 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 { buildFloorBlock as sharedFloorBlock, FLOOR_UNAVAILABLE_TEXT, } from "../../../src/failback/floor.js";
 import { recentUserQuery } from "../../mega-runtime.js";
 /** One-shot completion marker per MegaRuntime (dies with the runtime). */
 const guardDone = new WeakMap();
@@ -61,26 +62,19 @@ export function runTriggerGuard(runtime, config, ctx) {
         /* never throws; best-effort guard */
     }
 }
-/** Build the provenance floor string from the session's newest checkpoint. */
+/**
+ * Build the provenance floor string from the session's newest checkpoint.
+ *
+ * 3WF-4: the text construction moved to the SHARED pure builder
+ * (src/failback/floor.ts) — this keeps the store read (`vectorList`, unfiltered,
+ * exactly as 3WF-1 shipped) and the string return type, so output is
+ * byte-identical to the pre-refactor version.
+ */
 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.");
+        return sharedFloorBlock(vectorList(runtime.store, sid)).text;
     }
     catch {
-        return ("This session has compacted context but recall could not surface a " +
-            "checkpoint relevant to the current request.");
+        return FLOOR_UNAVAILABLE_TEXT;
     }
 }

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

@@ -2,6 +2,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 { confirmInjection } from "./context-handler/injectionConfirm.js";
 import { persistEpochAndMaintain } from "./context-handler/afterCompact.js";
 import { appendMirrorAndLedger } from "./context-handler/dbMirrorAppend.js";
 import { evaluateGate, thrashGuardBlocks } from "./context-handler/gateCheck.js";
@@ -43,7 +44,22 @@ export function registerContextHandler(pi, runtime, config) {
         // 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
         // normal return.
-        const tailResult = buildTailResult(runtime, config, messages);
+        const composeTail = buildTailResult(runtime, config, messages);
+        // 3WF-4 InjectionConfirm: wrap the tail factory so EVERY return point of
+        // this handler (gate / replay / debounce / thrash-guard / pipeline /
+        // live-trim) is verified — the staged block's marker must be present in
+        // the message list pi will send (tail mode), else we re-compose from the
+        // runtime's pending blocks and finally fall back to the shared floor.
+        // A composition that yields nothing staged (undefined) is passed through
+        // untouched, so flag-OFF and no-recall paths are byte-identical.
+        const tailResult = config.threeWayFailback
+            ? (msgs) => {
+                const view = composeTail(msgs);
+                if (!view)
+                    return view;
+                return confirmInjection(runtime, config, view, ctx.sessionManager.getSessionId());
+            }
+            : composeTail;
         // Always track context for the dashboard/widget, even when auto is off.
         // (v0.8 regression: !config.auto gate sat above this, leaving ctx stats
         // null -> widget '?% / ?/?' when auto disabled. Track first, THEN gate.)

package/dist/src/failback/floor.js

@@ -0,0 +1,35 @@
+/** Floor text when the newest checkpoint summary is available (prefix). */
+const WITH_SUMMARY_PREFIX = "The following compacted context is the most recent checkpoint from " +
+    "this session (recall found no query-relevant match):\n\n";
+/** Floor text when checkpoints exist but no usable summary does. */
+const NO_SUMMARY_TEXT = "This session has compacted context but recall could not surface a " +
+    "checkpoint relevant to the current request; the most recent checkpoint " +
+    "summary is unavailable.";
+/** Floor text when the checkpoint read itself failed (hard last resort). */
+export const FLOOR_UNAVAILABLE_TEXT = "This session has compacted context but recall could not surface a " +
+    "checkpoint relevant to the current request.";
+/** The newest checkpoint by timestamp (first element wins ties, as before). */
+export function newestCheckpoint(cps) {
+    let newest = cps[0];
+    for (const cp of cps) {
+        if (!newest || (cp.timestamp ?? 0) > (newest.timestamp ?? 0))
+            newest = cp;
+    }
+    return newest;
+}
+/**
+ * Build the provenance floor from an already-read checkpoint list. Pure: the
+ * caller owns the read (and any dedup-status filtering), so both legacy call
+ * sites keep byte-identical output.
+ */
+export function buildFloorBlock(cps) {
+    const summary = newestCheckpoint(cps)?.summary?.trim();
+    if (summary) {
+        return { text: WITH_SUMMARY_PREFIX + summary, basis: "lastCheckpoint" };
+    }
+    return { text: NO_SUMMARY_TEXT, basis: "lastCheckpoint" };
+}
+/** The hard last-resort floor (checkpoint read unavailable or threw). */
+export function unavailableFloorBlock() {
+    return { text: FLOOR_UNAVAILABLE_TEXT, basis: "none" };
+}

package/dist/src/recall/validator.js

@@ -26,36 +26,22 @@ import { defaultEmbedder, cosineSimilarity } from "../embedder.js";
 // [] for live sessions). Mirrors vector-search.ts / tieredRouter.ts.
 import { listCheckpoints } from "../store/sqlite.js";
 import { RECALL_MIN_COSINE } from "../config.js";
-/** Build the provenance floor block from the session's newest checkpoint. */
+import { buildFloorBlock as sharedFloorBlock, unavailableFloorBlock, } from "../failback/floor.js";
+/**
+ * Build the provenance floor block from the session's newest checkpoint.
+ *
+ * 3WF-4: the text construction moved to the SHARED pure builder
+ * (src/failback/floor.ts). This wrapper keeps THIS call site's read semantics —
+ * `listCheckpoints` filtered to `dedupStatus !== "removed"` — so the output is
+ * byte-identical to the pre-refactor 3WF-3 version.
+ */
 function buildFloorBlock(sessionId, store) {
     try {
         const cps = listCheckpoints(sessionId, store.stateDir).filter((c) => c.dedupStatus !== "removed");
-        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 {
-                text: "The following compacted context is the most recent checkpoint from " +
-                    "this session (recall found no query-relevant match):\n\n" + summary,
-                basis: "lastCheckpoint",
-            };
-        }
-        return {
-            text: "This session has compacted context but recall could not surface a " +
-                "checkpoint relevant to the current request; the most recent checkpoint " +
-                "summary is unavailable.",
-            basis: "lastCheckpoint",
-        };
+        return sharedFloorBlock(cps);
     }
     catch {
-        return {
-            text: "This session has compacted context but recall could not surface a " +
-                "checkpoint relevant to the current request.",
-            basis: "none",
-        };
+        return unavailableFloorBlock();
     }
 }
 /**

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

@@ -0,0 +1,90 @@
+/**
+ * context-handler/injectionConfirm.fixture.ts — shared fixtures for the 3WF-4
+ * InjectionConfirm tests.
+ *
+ * Split out so each test file stays under the extensions/300-soft-cap the way
+ * src/recall/recall3wf.fixture.ts does for 3WF-3. These are REAL fixtures, not
+ * mocks/stubs: a REAL VectorStore over a temp stateDir with REAL checkpoints
+ * persisted via compactSession; the MegaRuntime is a minimal typed stub exposing
+ * only the fields confirmInjection touches (store, pendingRecallBlock,
+ * pendingMemoryRecallBlock, appendEvent), matching the triggerGuard/thrashGuard
+ * test conventions.
+ */
+import { mkdtempSync } 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 type { MegaRuntime } from "../../mega-runtime.js";
+import type { MegaConfig } from "../../mega-config.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;
+}
+
+/** Recorded appendEvent calls, for telemetry assertions. */
+export interface RecordedEvent {
+	name: string;
+	payload: Record<string, unknown>;
+}
+
+/** Fresh isolated state dir per VectorStore. */
+export function freshStore(): { store: VectorStore; dir: string } {
+	const dir = mkdtempSync(join(tmpdir(), "mc-inject-"));
+	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 = "sess_inject"): void {
+	topics.forEach((t, i) => {
+		compactSession(
+			{
+				sessionId: sid,
+				messages: [msg("user", t), msg("assistant", "ok")],
+				keepFrom: 2,
+				timestamp: i + 1,
+			},
+			store,
+		);
+	});
+}
+
+/** Minimal MegaRuntime stub exposing only the confirmInjection touch-points. */
+export function runtimeStub(
+	store: VectorStore,
+	over: Partial<{
+		pendingRecallBlock: string | undefined;
+		pendingMemoryRecallBlock: string | undefined;
+	}> = {},
+): { runtime: MegaRuntime; events: RecordedEvent[] } {
+	const events: RecordedEvent[] = [];
+	const runtime = {
+		store,
+		pendingRecallBlock: over.pendingRecallBlock,
+		pendingMemoryRecallBlock: over.pendingMemoryRecallBlock,
+		perfTurnStart: undefined,
+		rt: { recallInjectedThisTurn: false },
+		appendEvent: (name: string, payload: Record<string, unknown>) => {
+			events.push({ name, payload });
+		},
+	} as unknown as MegaRuntime;
+	return { runtime, events };
+}
+
+/** Config stub: only the flags confirmInjection reads. */
+export function configStub(
+	over: Partial<{ threeWayFailback: boolean; recallTailInject: boolean }> = {},
+): MegaConfig {
+	return {
+		threeWayFailback: over.threeWayFailback ?? true,
+		recallTailInject: over.recallTailInject ?? true,
+	} as unknown as MegaConfig;
+}

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

@@ -0,0 +1,168 @@
+/**
+ * context-handler/injectionConfirm.ts — 3WF-4 InjectionConfirm.
+ *
+ * QA amendment A3 (binding): pi exposes NO prompt readback API, so the only
+ * verifiable proxy for what the provider will actually receive is the pre-LLM
+ * message list. In DEFAULT tail mode (`recallTailInject` ON) the staged recall
+ * block rides in as a user-role tail message, so we assert the block's marker
+ * text is present in the message list we are about to return. In LEGACY prepend
+ * mode (`recallTailInject` OFF) the block never enters the message list at all,
+ * so the guard degrades to a string-contains check over our own composed return
+ * value and never reports a false miss.
+ *
+ * Recovery ladder when the marker is absent (tail mode only):
+ *   1. recomposed — rebuild the view from the runtime's pending blocks via the
+ *      SAME `buildTailResult` composition the handler uses (self-repair on this
+ *      event; the user sees nothing).
+ *   2. floor — nothing pending either: append the shared provenance floor text
+ *      (src/failback/floor.ts) as a user-role tail message so the model is never
+ *      silently left with no compacted-context provenance at all.
+ *
+ * Stack position: wraps the `tailResult` closure returned by buildTailResult, so
+ * EVERY return point of the context handler (gate / replay / debounce /
+ * thrash-guard / pipeline / live-trim) is verified with one wiring point.
+ *
+ * Non-fatal everywhere: any throw degrades to the unverified view (pre-sprint
+ * behavior). Flag OFF => the wrapper is never installed (byte-identical).
+ */
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { MegaRuntime } from "../../mega-runtime.js";
+import type { MegaConfig } from "../../mega-config.js";
+import type { InjectionVerdict } from "../../../src/failback/types.js";
+import { vectorList } from "../../../src/vectorStore.js";
+import { normalizeSessionId } from "../../../src/store.js";
+import { buildFloorBlock } from "../../../src/failback/floor.js";
+import { withRecallTail } from "../recall-tail.js";
+import { messageContentText } from "./messageText.js";
+
+/** A composed context view (the shape every handler return point produces). */
+export interface TailView {
+	messages: AgentMessage[];
+}
+
+/** The staged blocks + mode this pass verifies (pure inputs, no pi runtime). */
+export interface ConfirmInput {
+	/** The staged block text expected to have landed (null => nothing to verify). */
+	staged: string | null;
+	/** False in legacy prepend mode: verify the return string, not the list. */
+	tailMode: boolean;
+}
+
+/**
+ * The marker substring used to locate a staged block inside a message. The
+ * block's first non-empty line, capped, so prompt reshapes (cache striping /
+ * message separation) that regroup messages cannot defeat the match, while a
+ * genuinely dropped block still fails it.
+ */
+export function blockMarker(block: string): string {
+	const line = block
+		.split("\n")
+		.map((l) => l.trim())
+		.find((l) => l.length > 0);
+	return (line ?? "").slice(0, 80);
+}
+
+/**
+ * PURE decision function: did the staged block land in this view, and if not,
+ * which rung should repair it? Takes the already-extracted message texts so it
+ * stays free of pi types and is directly unit-testable.
+ */
+export function decideInjection(
+	input: ConfirmInput,
+	messageTexts: readonly string[],
+	hasPendingBlocks: boolean,
+): InjectionVerdict {
+	const marker = input.staged ? blockMarker(input.staged) : "";
+	// Nothing staged => nothing to assert; NOT a miss. Injecting a floor here
+	// would push provenance text into sessions that never had recall to lose.
+	if (!marker) return { landed: true, recovered: "none" };
+	const landed = messageTexts.some((t) => t.includes(marker));
+	if (landed) return { landed: true, recovered: "none" };
+	// Absent: recompose when the runtime still holds pending blocks, else floor.
+	return { landed: false, recovered: hasPendingBlocks ? "recomposed" : "floor" };
+}
+
+/** Append `text` as a user-role tail message (same shape as recall-tail.ts). */
+function withFloorTail(view: TailView, text: string): TailView {
+	const tailMsg = {
+		role: "user" as const,
+		content: text,
+		timestamp: Date.now(),
+	} as unknown as AgentMessage;
+	return { messages: [...view.messages, tailMsg] };
+}
+
+/**
+ * Thin caller: verify (and if needed repair) one composed view. Returns the view
+ * to actually return from the handler. `sessionId` sources the floor checkpoints.
+ *
+ * The recompose rung deliberately re-appends via `withRecallTail` onto the
+ * ALREADY-COMPOSED view rather than re-running `buildTailResult`: the reshape
+ * stages (cache striping / message separation) are the realistic way a tail
+ * message gets regrouped away, and re-running the same composition would
+ * reproduce the same loss. Appending after the reshape is the actual repair, and
+ * it keeps the PREVENT-PI-001/002 tail-append invariant (a single user-role
+ * message after a complete prefix can never split a toolCall/toolResult pair).
+ */
+export function confirmInjection(
+	runtime: MegaRuntime,
+	config: MegaConfig,
+	view: TailView,
+	sessionId: string,
+): TailView {
+	try {
+		if (!config.threeWayFailback) return view;
+		// What the tail composition was supposed to inject. BOTH staged blocks
+		// count: withRecallTail joins recall + memory blocks into one tail
+		// message, so either one going missing is a real injection failure.
+		const staged =
+			runtime.pendingRecallBlock ?? runtime.pendingMemoryRecallBlock ?? null;
+		// Can the recompose rung actually re-append? Only when a block is still
+		// staged on the runtime. When it is not (blocks consumed between
+		// composition and this check), or when withRecallTail declines to append,
+		// the ladder falls through to the floor rung below.
+		const hasPending =
+			runtime.pendingRecallBlock != null ||
+			runtime.pendingMemoryRecallBlock != null;
+		// Legacy prepend mode: the block is not expected in the message list —
+		// verify our composed return value contains it instead (A3 degrade path).
+		if (!config.recallTailInject) {
+			const composed = view.messages.map(messageContentText).join("\n");
+			const marker = staged ? blockMarker(staged) : "";
+			runtime.appendEvent("injection_confirmed", {
+				mode: "prepend",
+				landed: marker ? composed.includes(marker) : true,
+			});
+			return view;
+		}
+		const verdict = decideInjection(
+			{ staged, tailMode: true },
+			view.messages.map(messageContentText),
+			hasPending,
+		);
+		if (verdict.landed) {
+			runtime.appendEvent("injection_confirmed", { mode: "tail", landed: true });
+			return view;
+		}
+		if (verdict.recovered === "recomposed") {
+			const rebuilt = withRecallTail(view.messages, runtime, config);
+			// withRecallTail returns the input array unchanged on failure; only
+			// treat a genuine append as a recovery.
+			if (rebuilt.length > view.messages.length) {
+				runtime.appendEvent("injection_recovered", { via: "recomposed" });
+				return { messages: rebuilt };
+			}
+		}
+		const floor = buildFloorBlock(
+			vectorList(runtime.store, normalizeSessionId(sessionId)),
+		);
+		runtime.appendEvent("injection_recovered", {
+			via: "floor",
+			basis: floor.basis,
+		});
+		return withFloorTail(view, floor.text);
+	} catch {
+		// Non-fatal: return the unverified view (pre-sprint behavior).
+		return view;
+	}
+}

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

@@ -30,6 +30,10 @@ 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 {
+	buildFloorBlock as sharedFloorBlock,
+	FLOOR_UNAVAILABLE_TEXT,
+} from "../../../src/failback/floor.js";
 import { recentUserQuery } from "../../mega-runtime.js";
 
 /** One-shot completion marker per MegaRuntime (dies with the runtime). */
@@ -108,30 +112,18 @@ export function runTriggerGuard(
 	}
 }
 
-/** Build the provenance floor string from the session's newest checkpoint. */
+/**
+ * Build the provenance floor string from the session's newest checkpoint.
+ *
+ * 3WF-4: the text construction moved to the SHARED pure builder
+ * (src/failback/floor.ts) — this keeps the store read (`vectorList`, unfiltered,
+ * exactly as 3WF-1 shipped) and the string return type, so output is
+ * byte-identical to the pre-refactor version.
+ */
 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."
-		);
+		return sharedFloorBlock(vectorList(runtime.store, sid)).text;
 	} catch {
-		return (
-			"This session has compacted context but recall could not surface a " +
-			"checkpoint relevant to the current request."
-		);
+		return FLOOR_UNAVAILABLE_TEXT;
 	}
 }

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

@@ -24,6 +24,7 @@ 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 { confirmInjection } from "./context-handler/injectionConfirm.js";
 import { persistEpochAndMaintain } from "./context-handler/afterCompact.js";
 import { appendMirrorAndLedger } from "./context-handler/dbMirrorAppend.js";
 import { evaluateGate, thrashGuardBlocks } from "./context-handler/gateCheck.js";
@@ -72,7 +73,21 @@ export function registerContextHandler(
 		// 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
 		// normal return.
-		const tailResult = buildTailResult(runtime, config, messages);
+		const composeTail = buildTailResult(runtime, config, messages);
+		// 3WF-4 InjectionConfirm: wrap the tail factory so EVERY return point of
+		// this handler (gate / replay / debounce / thrash-guard / pipeline /
+		// live-trim) is verified — the staged block's marker must be present in
+		// the message list pi will send (tail mode), else we re-compose from the
+		// runtime's pending blocks and finally fall back to the shared floor.
+		// A composition that yields nothing staged (undefined) is passed through
+		// untouched, so flag-OFF and no-recall paths are byte-identical.
+		const tailResult: typeof composeTail = config.threeWayFailback
+			? (msgs) => {
+					const view = composeTail(msgs);
+					if (!view) return view;
+					return confirmInjection(runtime, config, view, ctx.sessionManager.getSessionId());
+				}
+			: composeTail;
 		// Always track context for the dashboard/widget, even when auto is off.
 		// (v0.8 regression: !config.auto gate sat above this, leaving ctx stats
 		// null -> widget '?% / ?/?' when auto disabled. Track first, THEN gate.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.20.87",
+  "version": "0.20.88",
   "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/floor.ts

@@ -0,0 +1,71 @@
+/**
+ * src/failback/floor.ts — the SHARED pure provenance-floor builder (3WF-4).
+ *
+ * Consolidation refactor (ZERO behavior change). Before this module the same
+ * floor text was built twice:
+ *   (a) `extensions/mega-events/context-handler/triggerGuard.ts` (3WF-1) —
+ *       read checkpoints via `vectorList` (unfiltered), returned a bare string;
+ *   (b) `src/recall/validator.ts` (3WF-3) — read checkpoints via
+ *       `listCheckpoints` filtered to `dedupStatus !== "removed"`, returned a
+ *       `FloorBlock`.
+ * The three text variants were byte-identical between the two; only the
+ * checkpoint READ differed. So this module takes the already-read checkpoint
+ * list from the caller (staying pure — no store, no pi types, no I/O) and each
+ * call site keeps its own read semantics. Output is byte-identical to both.
+ *
+ * 3WF-4's InjectionConfirm is the third consumer: when neither the message list
+ * nor the runtime's pending blocks yield a block, it needs the SAME last-resort
+ * floor text rather than a fourth copy.
+ *
+ * Non-fatal by construction: every branch returns a `FloorBlock`; the `none`
+ * basis carries the shortest text (used when the checkpoint read itself threw).
+ */
+import type { StoredCheckpoint } from "../store.js";
+import type { FloorBlock } from "./types.js";
+
+/** Floor text when the newest checkpoint summary is available (prefix). */
+const WITH_SUMMARY_PREFIX =
+	"The following compacted context is the most recent checkpoint from " +
+	"this session (recall found no query-relevant match):\n\n";
+
+/** Floor text when checkpoints exist but no usable summary does. */
+const NO_SUMMARY_TEXT =
+	"This session has compacted context but recall could not surface a " +
+	"checkpoint relevant to the current request; the most recent checkpoint " +
+	"summary is unavailable.";
+
+/** Floor text when the checkpoint read itself failed (hard last resort). */
+export const FLOOR_UNAVAILABLE_TEXT =
+	"This session has compacted context but recall could not surface a " +
+	"checkpoint relevant to the current request.";
+
+/** The newest checkpoint by timestamp (first element wins ties, as before). */
+export function newestCheckpoint(
+	cps: readonly StoredCheckpoint[],
+): StoredCheckpoint | undefined {
+	let newest = cps[0];
+	for (const cp of cps) {
+		if (!newest || (cp.timestamp ?? 0) > (newest.timestamp ?? 0)) newest = cp;
+	}
+	return newest;
+}
+
+/**
+ * Build the provenance floor from an already-read checkpoint list. Pure: the
+ * caller owns the read (and any dedup-status filtering), so both legacy call
+ * sites keep byte-identical output.
+ */
+export function buildFloorBlock(
+	cps: readonly StoredCheckpoint[],
+): FloorBlock {
+	const summary = newestCheckpoint(cps)?.summary?.trim();
+	if (summary) {
+		return { text: WITH_SUMMARY_PREFIX + summary, basis: "lastCheckpoint" };
+	}
+	return { text: NO_SUMMARY_TEXT, basis: "lastCheckpoint" };
+}
+
+/** The hard last-resort floor (checkpoint read unavailable or threw). */
+export function unavailableFloorBlock(): FloorBlock {
+	return { text: FLOOR_UNAVAILABLE_TEXT, basis: "none" };
+}

package/src/failback/types.ts

@@ -103,6 +103,22 @@ export interface RecallCandidate {
 	source: "vector" | "fts5" | "recency";
 }
 
+/**
+ * Verdict of an InjectionConfirm pass (3WF-4). There is NO prompt readback API
+ * in pi, so the only verifiable proxy for what the provider will receive is the
+ * pre-LLM message list (`ContextEvent.messages`, transformed). `landed` is true
+ * when the staged block's text was found there (tail mode) or in the composed
+ * return string (legacy prepend mode). `recovered` records which repair rung
+ * this event used: none (already landed), recomposed (rebuilt from the runtime's
+ * pending blocks), or floor (last-resort provenance text).
+ */
+export interface InjectionVerdict {
+	/** True when the staged block text is present in the verified view. */
+	landed: boolean;
+	/** Which repair rung ran to make the block present. */
+	recovered: "none" | "recomposed" | "floor";
+}
+
 /**
  * Outcome of the three-source recall vote. `winners` are the agreed candidates
  * (ranked), `votes` counts how many distinct sources named each checkpointId,

package/src/recall/validator.ts

@@ -28,6 +28,10 @@ import { listCheckpoints } from "../store/sqlite.js";
 import { RECALL_MIN_COSINE } from "../config.js";
 import type { VectorStore } from "../vectorStore.js";
 import type { RecallCandidate, FloorBlock } from "../failback/types.js";
+import {
+	buildFloorBlock as sharedFloorBlock,
+	unavailableFloorBlock,
+} from "../failback/floor.js";
 
 /** Options for the recall validator. */
 export interface ValidateOptions {
@@ -54,39 +58,22 @@ export type ValidationOutcome =
 	| { kind: "candidate"; candidate: RecallCandidate }
 	| { kind: "floor"; floor: FloorBlock };
 
-/** Build the provenance floor block from the session's newest checkpoint. */
+/**
+ * Build the provenance floor block from the session's newest checkpoint.
+ *
+ * 3WF-4: the text construction moved to the SHARED pure builder
+ * (src/failback/floor.ts). This wrapper keeps THIS call site's read semantics —
+ * `listCheckpoints` filtered to `dedupStatus !== "removed"` — so the output is
+ * byte-identical to the pre-refactor 3WF-3 version.
+ */
 function buildFloorBlock(sessionId: string, store: VectorStore): FloorBlock {
 	try {
 		const cps = listCheckpoints(sessionId, store.stateDir).filter(
 			(c) => c.dedupStatus !== "removed",
 		);
-		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 {
-				text:
-					"The following compacted context is the most recent checkpoint from " +
-					"this session (recall found no query-relevant match):\n\n" + summary,
-				basis: "lastCheckpoint",
-			};
-		}
-		return {
-			text:
-				"This session has compacted context but recall could not surface a " +
-				"checkpoint relevant to the current request; the most recent checkpoint " +
-				"summary is unavailable.",
-			basis: "lastCheckpoint",
-		};
+		return sharedFloorBlock(cps);
 	} catch {
-		return {
-			text:
-				"This session has compacted context but recall could not surface a " +
-				"checkpoint relevant to the current request.",
-			basis: "none",
-		};
+		return unavailableFloorBlock();
 	}
 }