pi-mega-compact 0.21.1 → 0.21.3

package/extensions/mega-compact-child.ts

@@ -0,0 +1,129 @@
+/**
+ * mega-compact-child.ts — minimal extension loaded ONLY into dispatched child
+ * pi subprocesses (spawned by ithacus with a second `-e` flag).
+ *
+ * Design: a child is a FRESH pi process started with `--no-extensions -e <this
+ * file>` (see ithacus-spawn.ts). It does NOT receive the parent's MegaConfig and
+ * is a separate process, so it reads its two control env vars directly and owns
+ * its own bridge. It gives children recall-at-start + compaction-on-shutdown via
+ * the mega-compact bridge, with NO tools and NO console output, so it never
+ * pollutes the child's `--mode json` JSONL stdout that ithacus-spawn parses.
+ *
+ * Per the teammate brief this mirrors ithacus-child-mailbox.ts (default export,
+ * no console, dispose on session_shutdown) but registers ZERO tools — registering
+ * any tool risks a pi duplicate-tool-name hard-fail and children need none.
+ *
+ * PREVENT-PI-004: no network. The bridge is a same-repo relative import over a
+ * local sqlite store; the only I/O is the read-only `git rev-parse` inside
+ * repoStateDir. Nothing to flag.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
+import { createMegaBridge } from "../src/bridge.js";
+import type {
+	MegaBridge,
+	BridgeMessage,
+} from "../src/bridge.js";
+import { repoStateDir } from "./mega-config.js";
+import { STATE_DIR_DEFAULT } from "../src/config.js";
+
+/** Default-ON env bool: only `=false`/`=0` disables (matches mega-config envBool). */
+function envBool(name: string, fallback: boolean): boolean {
+	const v = process.env[name];
+	if (v == null || v === "") return fallback;
+	return v === "true" || v === "1";
+}
+
+/** Extract a recall query from a single AgentMessage (string or content blocks). */
+function messageToText(m: { content: unknown }): string {
+	const c = (m as { content: unknown }).content;
+	if (typeof c === "string") return c;
+	if (Array.isArray(c)) return c.map((b: { text?: string }) => b.text ?? "").join(" ");
+	return "";
+}
+
+/** Convert a session's AgentMessages into the bridge's lightweight shape. */
+function toBridgeMessages(ctx: ExtensionContext): BridgeMessage[] {
+	const out: BridgeMessage[] = [];
+	try {
+		for (const entry of ctx.sessionManager.getEntries()) {
+			for (const m of sessionEntryToContextMessages(entry as never)) {
+				if (m.role === "user" || m.role === "assistant") {
+					out.push({ role: m.role, text: messageToText(m) });
+				}
+			}
+		}
+	} catch {
+		/* non-fatal: a child without a session manager yields no messages */
+	}
+	return out;
+}
+
+export default function (pi: ExtensionAPI): void {
+	// Flag read at LOAD time: a flag-OFF child registers nothing and a flag-ON
+	// child that never fires a hook pays zero cost (bridge is built lazily).
+	if (!envBool("MEGACOMPACT_ITHACUS_BRIDGE", true)) return;
+
+	let bridge: MegaBridge | undefined;
+
+	// Build the bridge lazily on first hook fire so cost is opt-in by usage.
+	const getBridge = (): MegaBridge => {
+		if (!bridge) {
+			bridge = createMegaBridge({
+				stateDir: repoStateDir(process.cwd(), STATE_DIR_DEFAULT),
+			});
+		}
+		return bridge;
+	};
+
+	// S52-style recall injection: prepend staged checkpoints + durable memories
+	// to the system prompt, mirroring the main entry's before_agent_start path.
+	// 4th-layer stability guard: an unset/empty sessionId makes recall silently
+	// useless (the openclaw Date.now() gotcha), so skip outright.
+	pi.on("before_agent_start", async (event) => {
+		try {
+			const sessionId = process.env.ITHACUS_MEGA_SESSION_ID;
+			if (!sessionId || sessionId === "") return undefined;
+
+			// Prefer the event's raw prompt; fall back to a generic query.
+			const query = event.prompt && event.prompt.trim() ? event.prompt.trim() : "";
+			if (query === "") return undefined;
+
+			const b = getBridge();
+			const cp = b.recallCheckpoints({ sessionId, query, limit: 3 });
+			const mem = await b.recallMemories({ query, limit: 5 });
+
+			const blocks: string[] = [];
+			if (!cp.empty && cp.block) blocks.push(cp.block);
+			if (!mem.empty && mem.block) blocks.push(mem.block);
+			if (blocks.length === 0) return undefined;
+
+			return { systemPrompt: `${event.systemPrompt ?? ""}\n\n${blocks.join("\n\n")}` };
+		} catch {
+			// layer b: non-fatal — never break the agent loop. No injection.
+			return undefined;
+		}
+	});
+
+	// Compaction on shutdown: persist the session's messages as a checkpoint.
+	// Best-effort; non-fatal. Releases the sqlite handle via close().
+	// The bridge is constructed lazily here too: a child that only compacts (no
+	// recall fired) still persists its session. Best-effort; non-fatal.
+	pi.on("session_shutdown", async (_event, ctx) => {
+		try {
+			const sessionId = process.env.ITHACUS_MEGA_SESSION_ID;
+			if (!sessionId || sessionId === "") return;
+			const messages = toBridgeMessages(ctx);
+			if (messages.length === 0) return;
+			await getBridge().compact({ sessionId, messages });
+		} catch {
+			/* non-fatal */
+		} finally {
+			if (bridge) {
+				bridge.close();
+				bridge = undefined;
+			}
+		}
+	});
+}

package/extensions/mega-compact.ts

@@ -98,6 +98,16 @@ export default function (pi: ExtensionAPI) {
 		);
 		config.poisonedContextRepeatThreshold = 3;
 	}
+	// E1: validate similarity thresholds — NaN or out of range silently disables
+	// recall dedup (anything >= NaN is false). envFlag guards NaN; clamp the rest.
+	if (!(config.dedupSim > 0 && config.dedupSim <= 1)) {
+		console.warn("[mega-compact] MEGACOMPACT_DEDUP_SIM must be in (0,1]; using default 0.9");
+		config.dedupSim = 0.9;
+	}
+	if (!(config.crossRepoCosine >= 0 && config.crossRepoCosine <= 1)) {
+		console.warn("[mega-compact] MEGACOMPACT_CROSSREPO_COSINE must be in [0,1]; using default 0.9");
+		config.crossRepoCosine = 0.9;
+	}
 	const runtime = new MegaRuntime(config);
 	registerEventHandlers(pi, runtime, config);
 	registerCommands(pi, runtime, config);

package/extensions/mega-config-types.ts

@@ -159,6 +159,11 @@ export interface MegaConfig {
 	 *  to the pre-change OFF state. The single gate lives at the call site
 	 *  (tailResult.ts, config.messageSeparation), not inside buildSeparatedPrompt. */
 	messageSeparation: boolean;
+	/** Sprint A: Mega↔ithacus bridge — gate the child extension + bridge usage
+	 *  that tie this extension to ithacus's durable compaction. Positive sprint
+	 *  flag, default ON; flag-OFF (=0/`=false`) is byte-identical to pre-bridge
+	 *  behavior (the bridge is only consulted when this is ON). */
+	ithacusBridge: boolean;
 	/** P3: Cache-aware striping (PLAN_V2 Phase 3). Inserts stability-ordered
 	 *  cache stripes between summaries and thread. Default OFF. */
 	cacheStriping: boolean;

package/extensions/mega-config.ts

@@ -207,7 +207,7 @@ export function loadConfig(): MegaConfig {
 		advisoryChannel: envBool("MEGACOMPACT_ADVISORY_CHANNEL", true),
 		autoPctTrigger,
 		autoInlineK: envFlag("MEGACOMPACT_AUTO_INLINE_K", 3),
-		dedupSim: Number(process.env.MEGACOMPACT_DEDUP_SIM ?? "0.9"),
+		dedupSim: envFlag("MEGACOMPACT_DEDUP_SIM", 0.9),
 		raptorEnabled: envBool("MEGACOMPACT_RAPTOR_ENABLED", true),
 		legacyDurableTrim: envBool("MEGACOMPACT_LEGACY_DURABLE_TRIM", false),
 		dbMirror: envBool("MEGACOMPACT_DB_MIRROR", false),
@@ -216,13 +216,16 @@ export function loadConfig(): MegaConfig {
 		turnsDbEnabled: envBool("MEGACOMPACT_TURNS_DB", true),
 		autoWikiEnabled: envBool("MEGACOMPACT_AUTO_WIKI", true),
 		crossRepoEnabled: envBool("MEGACOMPACT_CROSSREPO_ENABLED", true),
-		crossRepoCosine: Number(process.env.MEGACOMPACT_CROSSREPO_COSINE ?? "0.90"),
+		crossRepoCosine: envFlag("MEGACOMPACT_CROSSREPO_COSINE", 0.9),
 		// 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"),
+		// E1 follow-up (PR #18 review): envFlag (Number.isFinite-guarded) like the
+		// dedupSim/crossRepoCosine fix in PR #18 — a typo'd env var must fall back
+		// to 0.12, not yield NaN.
+		recallMinCosine: envFlag("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),
@@ -231,6 +234,11 @@ 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),
+		// Sprint A: Mega↔ithacus bridge — gate the child extension + bridge usage.
+		// Default ON; OFF (=0/`=false`) = byte-identical pre-bridge behavior.
+		// Runtime reads envBool(plain key), mirroring threeWayFailback (plain-write
+		// convention, not _DISABLED).
+		ithacusBridge: envBool("MEGACOMPACT_ITHACUS_BRIDGE", 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.21.1",
+  "version": "0.21.3",
   "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/bridge/factory.ts

@@ -0,0 +1,231 @@
+/**
+ * bridge/factory.ts — `createMegaBridge(opts)` implementation.
+ *
+ * A thin, pi-agnostic wrapper over the engine's compaction / recall / memory /
+ * fork / vector APIs. Stores are constructed lazily on first use (a consumer
+ * that only calls recallMemories pays no VectorStore cost). Exceptions
+ * propagate from every method except `fork` (catches ForkError by design) and
+ * `close` (swallows best-effort cleanup), so failures surface in tests.
+ */
+import { compactSession } from "../engine.js";
+import {
+  recallAndInline,
+  recallAndInlineAsync,
+  recallMemoriesAndInline,
+} from "../recall.js";
+import type {
+  RecallInjectOptions,
+  RecallInjectResult,
+  MemoryRecallInjectOptions,
+} from "../recall/types.js";
+import { forkFromConversation, ForkError } from "../fork.js";
+import { createTurnStore } from "../store/turns/index.js";
+import type { TurnStore, TurnEntry } from "../store/turns/types.js";
+import { addMemory } from "../store/sqlite/memories.js";
+import { VectorStore, vectorSearch } from "../vectorStore.js";
+import type { SearchHit } from "../vectorStore.js";
+import { repoKey } from "../store/repoKey.js";
+import type {
+  BridgeOptions,
+  BridgeCompactInput,
+  BridgeCompactResult,
+  BridgeRecallOptions,
+  BridgeRecallResult,
+  BridgeMemoryRecallOptions,
+  BridgeMemoryRecallResult,
+  BridgeForkOptions,
+  BridgeForkResult,
+  BridgeCortexOptions,
+  BridgeCortexResult,
+  BridgeAddMemoryInput,
+  BridgeRecordTurnInput,
+  MegaBridge,
+} from "./types.js";
+
+/** Map a RecallInjectResult to the bridge's slimmer result contract. */
+function mapRecallResult(r: RecallInjectResult): BridgeRecallResult {
+  return {
+    block: r.block,
+    report: r.report,
+    hitCount: r.toInject.length,
+    empty: r.empty,
+  };
+}
+
+/** Map the memoryRecallAndInline tuple result to the bridge contract. */
+function mapMemoryResult(
+  r: { empty: boolean; block: string; report: string[] },
+): BridgeMemoryRecallResult {
+  return {
+    block: r.block,
+    report: r.report,
+    hitCount: r.report.length,
+    empty: r.empty,
+  };
+}
+
+/** Map vectorSearch hits to the cortex result contract. */
+function mapCortexHits(hits: SearchHit[], limit: number): BridgeCortexResult {
+  const top = hits.slice(0, limit);
+  return {
+    results: top.map((h) => ({
+      checkpointId: h.checkpoint.checkpointId,
+      score: h.score,
+      summary: h.checkpoint.summary,
+    })),
+    hitCount: top.length,
+  };
+}
+
+/**
+ * Create a MegaBridge over a single stateDir.
+ *
+ * The VectorStore and TurnStore are lazy: constructed on first use and cached
+ * in closures. The stateDir is retained for memory recall, which needs it
+ * directly.
+ */
+export function createMegaBridge(opts: BridgeOptions): MegaBridge {
+  const stateDir = opts.stateDir;
+  let vectorStore: VectorStore | undefined;
+  let turnStore: TurnStore | undefined;
+
+  const getVectorStore = (): VectorStore => {
+    if (!vectorStore) vectorStore = new VectorStore({ stateDir });
+    return vectorStore;
+  };
+  const getTurnStore = (): TurnStore => {
+    if (!turnStore) turnStore = createTurnStore({ stateDir });
+    return turnStore;
+  };
+
+  return {
+    compact(input: BridgeCompactInput): BridgeCompactResult {
+      const result = compactSession(
+        {
+          sessionId: input.sessionId,
+          messages: input.messages,
+          keepFrom: input.keepFrom,
+          summary: input.summary,
+          keyDecisions: input.keyDecisions,
+          nextSteps: input.nextSteps,
+          filesModified: input.filesModified,
+          compressionPressure: input.compressionPressure,
+        },
+        getVectorStore(),
+      );
+      return {
+        skipped: result.skipped,
+        deduped: result.deduped,
+        summary: result.summary,
+        checkpointId: result.checkpointId,
+        tokenEstimate: result.tokenEstimate,
+        originalTokenEstimate: result.originalTokenEstimate,
+        compactedFrom: result.compactedFrom,
+      };
+    },
+
+    recallCheckpoints(opts: BridgeRecallOptions): BridgeRecallResult {
+      const recallOpts: RecallInjectOptions = {
+        sessionId: opts.sessionId,
+        query: opts.query,
+        limit: opts.limit ?? 3,
+        source: "command",
+        skipInjected: opts.skipInjected,
+        recallMaxTokens: opts.recallMaxTokens,
+      };
+      return mapRecallResult(recallAndInline(recallOpts, getVectorStore()));
+    },
+
+    async recallMemories(opts: BridgeMemoryRecallOptions): Promise<BridgeMemoryRecallResult> {
+      const memOpts: MemoryRecallInjectOptions = {
+        query: opts.query,
+        stateDir,
+        limit: opts.limit,
+        minSimilarity: opts.minSimilarity,
+        crossRepo: opts.crossRepo,
+        crossRepoCosine: opts.crossRepoCosine,
+        recallMaxTokens: opts.recallMaxTokens,
+      };
+      const r = await recallMemoriesAndInline(memOpts);
+      return mapMemoryResult(r);
+    },
+
+    async recallAndInlineAsync(opts: BridgeRecallOptions): Promise<BridgeRecallResult> {
+      const recallOpts: RecallInjectOptions = {
+        sessionId: opts.sessionId,
+        query: opts.query,
+        limit: opts.limit ?? 3,
+        source: "command",
+        skipInjected: opts.skipInjected,
+        recallMaxTokens: opts.recallMaxTokens,
+      };
+      const r = await recallAndInlineAsync(recallOpts, getVectorStore());
+      return mapRecallResult(r);
+    },
+
+    fork(opts: BridgeForkOptions): BridgeForkResult {
+      try {
+        const outcome = forkFromConversation(
+          getTurnStore(),
+          opts.parentConversationId,
+          opts.turnIndex,
+        );
+        return {
+          childConversationId: outcome.childConversationId,
+          checkpointIds: outcome.checkpointIds,
+          forkTurnIndex: opts.turnIndex,
+        };
+      } catch (e) {
+        if (e instanceof ForkError) {
+          return { error: e.code };
+        }
+        throw e;
+      }
+    },
+
+    cortexQuery(opts: BridgeCortexOptions): BridgeCortexResult {
+      const limit = opts.limit ?? 3;
+      const scope = opts.repo ?? repoKey(stateDir);
+      const hits = vectorSearch(getVectorStore(), scope, opts.query, limit);
+      return mapCortexHits(hits, limit);
+    },
+
+    addMemory(input: BridgeAddMemoryInput): number | void {
+      // repo === null ⇒ stateDir-scoped durable memory (matches recallMemories).
+      return addMemory(
+        {
+          kind: input.kind,
+          content: input.content,
+          tags: input.tags,
+          category: input.category,
+        },
+        null,
+        stateDir,
+      );
+    },
+
+    recordTurn(input: BridgeRecordTurnInput): void {
+      const turn: TurnEntry = {
+        conversationId: input.conversationId,
+        sessionId: input.sessionId,
+        turnIndex: input.turnIndex,
+        role: (input.role as TurnEntry["role"]) ?? "assistant",
+        endedAt: input.endedAt ?? Date.now(),
+        ctxTokens: input.ctxTokens,
+        ctxPercent: input.ctxPercent,
+        model: input.model,
+      };
+      getTurnStore().asWriter().appendTurn(turn);
+    },
+
+    close(): void {
+      if (turnStore) {
+        try {
+          turnStore.close();
+        } catch {
+          /* best-effort */
+        }
+      }
+    },
+  };
+}

package/src/bridge/types.ts

@@ -0,0 +1,138 @@
+/**
+ * bridge/types.ts — contract types for the bidirectional mega-compact bridge.
+ *
+ * A pi-agnostic, unit-testable adapter surface that wraps the engine's
+ * compaction / recall / memory / fork / vector APIs behind one factory so an
+ * external host (ithacus) can drive them without importing pi-runtime types.
+ * Every type here mirrors a real engine signature (see factory.ts for the
+ * wiring).
+ */
+
+import type { EngineMessage } from "../types.js";
+
+/** Same shape as the engine's internal message. Identity re-export. */
+export type BridgeMessage = EngineMessage;
+
+/** Bridge construction options. */
+export interface BridgeOptions {
+  stateDir: string;
+}
+
+/** Input to compact a message slice into a checkpoint. */
+export interface BridgeCompactInput {
+  sessionId: string;
+  messages: BridgeMessage[];
+  keepFrom?: number;
+  summary?: string;
+  keyDecisions?: string[];
+  nextSteps?: string[];
+  filesModified?: string[];
+  compressionPressure?: number;
+}
+
+/** Useful subset of CompactResult. */
+export interface BridgeCompactResult {
+  skipped: boolean;
+  deduped: boolean;
+  summary: string;
+  checkpointId?: string;
+  tokenEstimate: number;
+  originalTokenEstimate?: number;
+  compactedFrom?: number;
+}
+
+/** Options for checkpoint recall (per-session). */
+export interface BridgeRecallOptions {
+  sessionId: string;
+  query: string;
+  limit?: number;
+  recallMaxTokens?: number;
+  skipInjected?: boolean;
+}
+
+/** Mapped from RecallInjectResult. */
+export interface BridgeRecallResult {
+  block: string;
+  report: string[];
+  hitCount: number;
+  empty: boolean;
+}
+
+/** Options for durable memory recall (stateDir-scoped, no sessionId). */
+export interface BridgeMemoryRecallOptions {
+  query: string;
+  limit?: number;
+  minSimilarity?: number;
+  crossRepo?: boolean;
+  crossRepoCosine?: number;
+  recallMaxTokens?: number;
+}
+
+export interface BridgeMemoryRecallResult {
+  block: string;
+  report: string[];
+  hitCount: number;
+  empty: boolean;
+}
+
+/** Options to fork a child conversation off a parent turn. */
+export interface BridgeForkOptions {
+  parentConversationId: string;
+  turnIndex: number;
+}
+
+/** Fork result: success variant OR a graceful error variant. */
+export interface BridgeForkSuccess {
+  childConversationId: string;
+  checkpointIds: string[];
+  forkTurnIndex: number;
+}
+export interface BridgeForkError {
+  error: "TURN_NOT_FOUND" | "NO_RECALL";
+}
+export type BridgeForkResult = BridgeForkSuccess | BridgeForkError;
+
+/** Options for a top-k corpus / vector query. */
+export interface BridgeCortexOptions {
+  query: string;
+  limit?: number;
+  repo?: string;
+}
+
+export interface BridgeCortexResult {
+  results: Array<{ checkpointId: string; score: number; summary?: string }>;
+  hitCount: number;
+}
+
+/** Input to persist a durable memory. */
+export interface BridgeAddMemoryInput {
+  content: string;
+  kind?: string;
+  tags?: string[];
+  category?: string;
+}
+
+/** Input to record a turn fact. */
+export interface BridgeRecordTurnInput {
+  conversationId: string;
+  sessionId: string;
+  turnIndex: number;
+  role?: string;
+  endedAt?: number;
+  ctxTokens?: number;
+  ctxPercent?: number;
+  model?: string;
+}
+
+/** The bridge surface exposed to the host. */
+export interface MegaBridge {
+  compact(input: BridgeCompactInput): BridgeCompactResult;
+  recallCheckpoints(opts: BridgeRecallOptions): BridgeRecallResult;
+  recallMemories(opts: BridgeMemoryRecallOptions): Promise<BridgeMemoryRecallResult>;
+  recallAndInlineAsync(opts: BridgeRecallOptions): Promise<BridgeRecallResult>;
+  fork(opts: BridgeForkOptions): BridgeForkResult;
+  cortexQuery(opts: BridgeCortexOptions): BridgeCortexResult;
+  addMemory(input: BridgeAddMemoryInput): number | void;
+  recordTurn(input: BridgeRecordTurnInput): void;
+  close(): void;
+}

package/src/bridge.ts

@@ -0,0 +1,24 @@
+/**
+ * bridge.ts — public barrel for the mega-compact bidirectional bridge.
+ *
+ * Hosts import only this file. The factory and all contracts live under
+ * src/bridge/ (kept thin per the delegate-shell pattern).
+ */
+export type {
+  MegaBridge,
+  BridgeOptions,
+  BridgeMessage,
+  BridgeCompactInput,
+  BridgeCompactResult,
+  BridgeRecallOptions,
+  BridgeRecallResult,
+  BridgeMemoryRecallOptions,
+  BridgeMemoryRecallResult,
+  BridgeForkOptions,
+  BridgeForkResult,
+  BridgeCortexOptions,
+  BridgeCortexResult,
+  BridgeAddMemoryInput,
+  BridgeRecordTurnInput,
+} from "./bridge/types.js";
+export { createMegaBridge } from "./bridge/factory.js";

package/src/config.ts

@@ -152,9 +152,18 @@ export const NEW_UI = (): boolean => ragEnabled("MEGACOMPACT_NEW_UI");
 // effectively-unrelated hits. Call-time read so tests can set the env per-test.
 // ---------------------------------------------------------------------------
 
-/** Same-repo recall cosine floor: top winner must be >= this to be injected. */
-export const RECALL_MIN_COSINE = (): number =>
-	Number(process.env.MEGACOMPACT_RECALL_MIN_COSINE ?? "0.12");
+/**
+ * Same-repo recall cosine floor: top winner must be >= this to be injected.
+ *
+ * E1 follow-up (PR #18 review): NaN-safe + clamped to [0,1]. A typo'd env var
+ * yielded NaN before; `cosine < NaN` is false, which disabled gate 1 entirely
+ * (every candidate passed). Non-finite falls back to 0.12; out-of-range clamps.
+ */
+export const RECALL_MIN_COSINE = (): number => {
+	const n = Number(process.env.MEGACOMPACT_RECALL_MIN_COSINE ?? "0.12");
+	if (!Number.isFinite(n)) return 0.12;
+	return Math.min(1, Math.max(0, n));
+};
 
 // ---------------------------------------------------------------------------
 // Vector-cortex flags + breaker constants (VC0A+). Positive sprint flags,

package/src/dedup/l1-minhash.ts

@@ -21,6 +21,7 @@ export const SHINGLE_SIZE = 5; // char 5-grams
 const MAX_SHINGLES = 50_000; // QA #7/#15 complexity cap
 const SEED = 0xdeadbeef;
 const P = 2147483647; // 2^31 - 1, Mersenne prime
+const PBigInt = 2147483647n; // BigInt twin for overflow-safe modular reduction
 
 /** Per-index universal-hashing coefficients, derived deterministically from SEED. */
 function coeffA(i: number): number {
@@ -69,10 +70,10 @@ export function minhashSignature(text: string): number[] {
     const b = coeffB(i);
     let min = P;
     for (const x of grams) {
-      // (a*x + b) mod p — use Number math; a,x < 2^31 so a*x < 2^62, within
-      // double-precision integer range (2^53) only if reduced; reduce a*x first.
-      const ax = (a * (x % P)) % P;
-      const h = (ax + b) % P;
+      // (a*x + b) mod p. a, x < 2^31 so a*x < 2^62 — EXCEEDS 2^53. The naive
+      // (a*(x%P))%P loses precision (verified: a=x=p-1 → lossy 2147483644 vs
+      // exact 1). BigInt is correct + cheap (~5ms per signature).
+      const h = Number((BigInt(a) * BigInt(x % P) + BigInt(b)) % PBigInt);
       if (h < min) min = h;
     }
     sig[i] = min;

package/src/recall/validator.ts

@@ -113,7 +113,14 @@ export function validateRecall(
 				// No comparable cosine available => cannot clear a cosine gate.
 				continue;
 			}
-			if (cosine < floor) continue;
+			// E1 follow-up (PR #18 review): NaN/Infinity must NEVER clear the floor.
+			// `NaN < floor` is false, so an unguarded comparison lets a NaN cosine
+			// PASS gate 1 and inject — one NaN source poisons the whole 3WF-3
+			// quorum. Reject non-finite scores explicitly; the candidate is skipped
+			// and, if all fail, the provenance floor ("no recall") is returned —
+			// never a zero-score injection. The default TrigramEmbedder cannot
+			// produce NaN (zero-norm guard), but a BYO localhost embedder can.
+			if (!Number.isFinite(cosine) || cosine < floor) continue;
 
 			// Gate 2: not already resident in the live window.
 			if (liveVecs.length > 0) {