pi-mega-compact 0.17.0 → 0.18.0

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

@@ -2,45 +2,32 @@
  * mega-events/context-handler.ts — the context event handler (auto-trigger).
  *
  * Delegate-shell (extensions split): handles the live-trim compaction pipeline —
- * DB-mirror append, fast-gate threshold check, pipeline invocation, legacy
- * durable compact, and the live-trim message reconstruction that feeds pi's
- * transformContext. The extracted pieces live in ./context-handler/:
+ * DB-mirror append, fast-gate threshold check, replay/debounce, pipeline
+ * invocation, legacy durable compact, and the live-trim message reconstruction
+ * that feeds pi's transformContext. The extracted pieces live in ./context-handler/:
  *  - messageText.ts    (messageContentText — best-effort text extraction)
  *  - tailResult.ts     (buildTailResult — recall-tail injection factory)
  *  - afterCompact.ts   (persistEpochAndMaintain — epoch/wiki/seed/dedup writes)
+ *  - dbMirrorAppend.ts (appendMirrorAndLedger — mirror + VC1B ledger append)
+ *  - gateCheck.ts      (evaluateGate — S29 fast-gate threshold evaluation)
+ *  - pipelineRun.ts    (invokePipeline — adaptive-compression runCompact)
+ *  - liveTrim.ts       (buildLiveTrimView — S16 live-trim reconstruction + cap)
  */
 import type {
 	ExtensionAPI,
 	ExtensionContext,
 	ContextEvent,
 } from "@earendil-works/pi-coding-agent";
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import {
-	openStore,
-	resolveModelThreshold,
-	DEFAULT_SAFETY_MARGIN_PCT,
-	DEFAULT_FIRE_POINT_PCT,
-} from "../../src/store/sqlite.js";
-import { autoCompactCheck } from "../../src/compact.js";
-import {
-	estimateSessionTokens,
-	estimateBlockTokens,
-	estimateMessageTokens,
-} from "../../src/tokens.js";
+import { estimateSessionTokens } from "../../src/tokens.js";
 import type { MegaRuntime } from "../mega-runtime.js";
-import { runCompact, piCompactWouldNoop } from "../mega-pipeline.js";
-import {
-	pressureFromPct,
-	pressureRatio,
-	type MegaConfig,
-} from "../mega-config.js";
-import { appendMirrorMessages } from "./mirror-append.js";
-import { appendMessagesToLedger } from "../mega-runtime/vector-cortex-ledger.js";
-import { epochIdFor } from "../../src/mirror/epoch.js";
-import { computeLiveTrimCut, liveTrimSummaryMessage } from "../mega-trim.js";
-import { messageContentText } from "./context-handler/messageText.js";
+import { piCompactWouldNoop } from "../mega-pipeline.js";
+import type { MegaConfig } from "../mega-config.js";
 import { buildTailResult } from "./context-handler/tailResult.js";
 import { persistEpochAndMaintain } from "./context-handler/afterCompact.js";
+import { appendMirrorAndLedger } from "./context-handler/dbMirrorAppend.js";
+import { evaluateGate } from "./context-handler/gateCheck.js";
+import { invokePipeline } from "./context-handler/pipelineRun.js";
+import { buildLiveTrimView } from "./context-handler/liveTrim.js";
 
 /** Register the context event handler (live-trim auto-trigger). */
 export function registerContextHandler(
@@ -101,122 +88,14 @@ export function registerContextHandler(
 
 		const view = viewForFallback ?? runtime.engineView(messages);
 
-		// S27 DB-mirror: append incoming messages to raw_transcript.
-		// Runs BEFORE fast-gate so every message is captured, even if we
-		// don't compact this turn. Append is idempotent (content_hash PK).
-		// F3: high-water mark (mirror-append.ts) skips already-processed
-		// messages on subsequent events. On fork/rewind (shorter list or
-		// boundary hash mismatch) the mark is dropped, falling back to a
-		// full reprocess.
-		if (config.dbMirror) {
-			try {
-				const db = openStore(runtime.currentStateDir);
-				appendMirrorMessages(
-					db,
-					messages,
-					runtime.rt.sessionId,
-					epochIdFor(runtime.rt.sessionId),
-					runtime.currentTurn,
-				);
-				// P2.2: populate conversation_thread + tool_results tables for
-				// prompt-cache analytics and durable separation. The live-array
-				// separation (buildSeparatedPrompt / buildCacheOptimizedPrompt in
-				// tailResult above) is sufficient for the prompt-construction path;
-				// these DB writes persist the split for post-hoc analysis, dashboard
-				// queries, and future readers. Non-fatal — failure here never breaks
-				// the agent loop (PREVENT-PI-004: zero network, local SQLite only).
-				{
-					const sid = runtime.rt.sessionId;
-					const turn = runtime.currentTurn;
-					const now = Date.now();
-					const threadStmt = db.prepare(
-						"INSERT OR IGNORE INTO conversation_thread (conversation_id, role, content, turn_index, timestamp) VALUES (?, ?, ?, ?, ?)",
-					);
-					const toolStmt = db.prepare(
-						"INSERT OR IGNORE INTO tool_results (conversation_id, role, content, turn_index, timestamp) VALUES (?, ?, ?, ?, ?)",
-					);
-					for (const m of messages) {
-						const role = m.role;
-						const content = messageContentText(m);
-						if (role === "user" || role === "assistant") {
-							threadStmt.run(sid, role, content, turn, now);
-						} else if (role === "toolResult" || role === "bashExecution") {
-							toolStmt.run(sid, role, content, turn, now);
-						}
-					}
-				}
-			} catch (e) {
-				runtime.logger.warn("db-mirror-append-fail", { error: String(e) });
-			}
-		}
+		// S27 DB-mirror + VC1B ledger append. Runs BEFORE the fast-gate so every
+		// message is captured, even if we don't compact this turn. Non-fatal.
+		appendMirrorAndLedger(runtime, config, messages);
 
-		// VC1B (S1): canonical messages -> v2 ledger occurrences. Flag-OFF opens
-		// no DB (byte-identical predecessor); non-fatal. onFailure surfaces
-		// per-append rejections (e.g. EVT_SEQ_REGRESSION on rewind/fork) as
-		// structured warnings rather than swallowing them silently.
-		try {
-			appendMessagesToLedger(
-				runtime.currentStateDir,
-				runtime.rt.sessionId,
-				messages,
-				runtime.logger,
-			);
-		} catch (e) {
-			runtime.logger.warn("vc1b-ledger-append-fail", { error: String(e) });
-		}
-
-		// S52 / v0.16.1: per-model threshold override. The user can tune the
-		// fire point + safety margin PER MODEL (different providers' models range
-		// 8K-1M+ context, so one global tier % is wrong). Falls back to env/default
-		// when no override row exists. Computed once here + reused in the tail cap
-		// below; the lookup is a single SQLite PK hit (cheap; cached after the
-		// first read in a session).
-		const _modelIdForThreshold = runtime.currentModel?.modelId ?? null;
-		const _perModelThreshold = resolveModelThreshold(_modelIdForThreshold, {
-			safetyMarginFallback: DEFAULT_SAFETY_MARGIN_PCT,
-			firePointFallback:
-				config.tierPct != null
-					? Math.round(config.tierPct * 100)
-					: DEFAULT_FIRE_POINT_PCT,
-			stateDir: runtime.currentStateDir,
-		});
-		// S29 FAST GATE: drive the auto-trigger off the context % (the number the
-		// menu bar shows), NOT the token count — the model under-reports tokens,
-		// so a token-only gate misses the overshoot that causes max-output-tokens
-		// truncation. The fire point is the per-model override when present,
-		// otherwise the tier's percent threshold (tierPct) unless overridden by
-		// MEGACOMPACT_AUTO_PCT_TRIGGER. `custom` (absolute
-		// MEGACOMPACT_THRESHOLD_TOKENS, tierPct null) is an explicit opt-out of
-		// percent scaling — it keeps the token gate. When pct is unavailable
-		// (window unknown / a model that doesn't report percent) a tiered config
-		// falls back to the token gate (S27 boot-fallback guarantee) instead of
-		// skipping compaction — a percent-only gate would regress that.
-		let gatePassed = false;
-		if (config.tierPct != null && pct != null) {
-			// Per-model override is a % (10-90); tierPct is a fraction (0.1-1.0).
-			// Prefer the override; fall back to autoPctTrigger + tierPct.
-			const tierPctFraction = config.autoPctTrigger ?? config.tierPct;
-			const perModelFraction = _perModelThreshold.firePointPct / 100;
-			const firePct =
-				_modelIdForThreshold != null ? perModelFraction : tierPctFraction;
-			gatePassed = pct / 100 >= firePct;
-		} else {
-			// custom tier OR tiered-but-pct-unavailable → token gate (S27 fallback).
-			if (currentTokens < runtime.effectiveThreshold) {
-				runtime.diagCtxFastGate++;
-				return tailResult() ?? undefined;
-			}
-			const check = autoCompactCheck(currentTokens, runtime.effectiveThreshold); // SERVER-STYLE CONFIRM (local)
-			if (!check.shouldCompact) {
-				runtime.diagCtxNoCompact++;
-				return tailResult() ?? undefined;
-			}
-			gatePassed = true;
-		}
-		if (!gatePassed) {
-			runtime.diagCtxFastGate++;
-			return tailResult() ?? undefined;
-		}
+		// S29 FAST GATE: drive the auto-trigger off the context percent (see
+		// gateCheck.ts). Returns a tailed view when the gate does not pass.
+		const gate = evaluateGate(runtime, config, { pct, currentTokens, tailResult });
+		if (gate.kind === "return") return gate.view;
 
 		// D.2: Replay MUST be exempt from debounce — replay is free (no compute,
 		// no re-write) and prevents unnecessary KV-cache invalidation. Check
@@ -266,40 +145,20 @@ export function registerContextHandler(
 		}
 		runtime.debounceUntil = now + 2000;
 
-		// Adaptive compression (Fix E): scale compression strength + keepFrom depth
-		// with how close we are to the model context limit. Null-safe: when the
-		// token-fallback path ran (pct unavailable) use the token-basis pressure
-		// (the same basis the runtime `pressure` getter uses for custom/no-window).
-		const pressure =
-			pct != null
-				? pressureFromPct(pct)
-				: pressureRatio(currentTokens, runtime.effectiveThreshold);
-		const ran = runCompact(pi, runtime, config, ctx, messages, {
-			compressionPressure: pressure,
+		// Adaptive-compression pipeline invocation (see pipelineRun.ts). Returns a
+		// tailed view ("return") when compaction skipped; otherwise "proceed" with
+		// the result + pressure consumed by the live-trim stage below.
+		const pipeline = invokePipeline(pi, runtime, config, ctx, {
+			messages,
+			pct,
+			currentTokens,
+			tailResult,
 		});
-		// D.3: skip paths fall back to replay instead of returning empty.
-		// If runCompact skipped and we have a valid trimCache, replay it
-		// (free stability win) — otherwise defer to the next event.
-		if (ran.skipped) {
-			runtime.diagCtxRunSkipped++;
-			if (
-				runtime.trimCache &&
-				runtime.trimCache.checkpointId === runtime.rt.lastCheckpointId &&
-				runtime.trimCache.cut <= messages.length
-			) {
-				const recent = messages.slice(runtime.trimCache.cut); // guardrails-allow PREVENT-PI-002: cached `cut` was sanitized by computeLiveTrimCut (src/boundary.ts); replayed verbatim, transcript only grows within an epoch.
-				runtime.diagLiveTrimFires++;
-				runtime.diagLiveTrimReplays++;
-				runtime.snapshot(ctx);
-				const skipView = [{ ...runtime.trimCache.summaryAgentMsg }, ...recent];
-				return tailResult(skipView) ?? { messages: skipView };
-			}
-			return tailResult() ?? undefined;
-		}
+		if (pipeline.kind === "return") return pipeline.view;
 
 		// S27 DB-mirror: write checkpoint_epoch + stamp turn epochs + auto-wiki +
 		// topic seed + fire-and-forget dedup. Best-effort + non-fatal.
-		await persistEpochAndMaintain(runtime, config, ran);
+		await persistEpochAndMaintain(runtime, config, pipeline.ran);
 
 		// LEGACY path (rollback): v0.4.28 ctx.compact() + the no-op gate. The
 		// manual compact path aborts the in-flight turn — only used behind the flag.
@@ -351,180 +210,19 @@ export function registerContextHandler(
 		}
 
 		// S16 LIVE trim: collapse the compacted region to a summary + recent anchor.
-		// Non-destructive: pi keeps the real transcript; only this LLM call sees the
-		// trimmed window. We compute the cut on the engine view (pure, tested) then
-		// slice the ORIGINAL pi AgentMessage[] from that index (lossless alignment,
-		// mirroring dropCompactedRange) and prepend a user-role summary message.
-		// A build failure or unsafe cut returns nothing (no trim this call — the
-		// next context event retries). The anchor floor is read live from env (the
-		// config value is the cached default) so it can be tuned per-test / per-run
-		// without reloading the module.
-		try {
-			const anchorEnv = process.env.MEGACOMPACT_ANCHOR_USER_MESSAGES;
-			const anchorUserMessages =
-				anchorEnv != null &&
-				anchorEnv !== "" &&
-				Number.isFinite(Number(anchorEnv))
-					? Number(anchorEnv)
-					: config.anchorUserMessages;
-			const cut = computeLiveTrimCut(view, {
-				compactedFrom: ran.result.compactedFrom,
-				summary: ran.result.summary,
-				anchorUserMessages,
-				// CRITICAL-OVER ESCAPE HATCH: when context is at/over ~90% of the
-				// window, relief takes priority over the anchor floor. Without this,
-				// computeLiveTrimCut bails to null (can't satisfy the floor) and the
-				// model is fed a raw overflow that errors every turn — the
-				// "Already compacted" + overflow death-spiral (2026-08-01 incident).
-				// A thin anchor is recoverable; an overflowed session is not.
-				//
-				// CRITICAL: pct is null for OpenAI-compatible providers that don't
-				// report usage.percent (e.g. neuralwatt). Without the token-pressure
-				// fallback the hatch never armed → cut=null → raw overflow → 400
-				// "conversation too long even after compaction" (2026-08-03 incident
-				// on glm-5.2-short, 200K window). Now also fires on pressure >= 0.9
-				// (token-basis) so the hatch arms regardless of whether the provider
-				// reports pct.
-				criticalOver: (pct ?? 0) >= 90 || pressure >= 0.9,
-			});
-			if (cut === null) {
-				runtime.diagCtxCutNull++;
-				runtime.logger.info("live-trim-skip", {
-					sessionId: runtime.rt.sessionId,
-					compactedFrom: ran.result.compactedFrom,
-					viewLen: view.length,
-					anchorUserMessages,
-					criticalOver: (pct ?? 0) >= 90,
-				});
-				return tailResult() ?? undefined; // unsafe / below anchor floor — no trim this call
-			}
-			const summaryMsg = liveTrimSummaryMessage({
-				compactedFrom: ran.result.compactedFrom,
-				summary: ran.result.summary,
-				anchorUserMessages: config.anchorUserMessages,
-			});
-			// Synthesize a user-role AgentMessage carrying the compacted summary.
-			const summaryAgentMsg = {
-				role: "user" as const,
-				content: summaryMsg.text,
-				// v0.8.6: stable timestamp across the epoch (NOT Date.now()) so the
-				// summary message bytes — and thus the KV-cache prefix — don't drift
-				// on every replay within the same compaction epoch.
-				timestamp: runtime.rt.lastCompactAt ?? Date.now(),
-			} as unknown as AgentMessage;
-			const recentRaw = messages.slice(cut); // guardrails-allow PREVENT-PI-002: `cut` is the pre-sanitized `compactedFrom` produced by src/boundary.ts computeDropRange, so the preserved run begins on a toolPair-safe index.
-
-			// FIX 2 (2026-08-03 incident): TOKEN-BUDGET CAP on the live-trim view.
-			// Compaction fires at tier% of the window (140K for a 200K window),
-			// but a SINGLE turn can inject a huge tool output (file read, bash) that
-			// jumps context from 139K → 199K+ before the next gate fires. When that
-			// happens [summary + preserved tail] can STILL exceed the model window,
-			// and the provider rejects with 400 "conversation too long even after
-			// compaction". The anchor floor (PREVENT-PI-001) keeps ≥N user messages
-			// but has NO token cap, so a 2-message tail of two 80K bash outputs sails
-			// right past the window.
-			//
-			// Cap: when the model context window is known, reserve room for the
-			// summary + the model's max output tokens + a 10% safety margin, then
-			// drop oldest preserved messages from the front of `recentRaw` until the
-			// tail fits. Never drops below the FINAL message (always keep the latest
-			// turn so the agent can respond). This is a last-resort HARD cap — it
-			// only fires when the preserved tail alone is oversized, which is rare.
-			const ctxWindow = runtime.lastCtxWindow;
-			// Reuse the per-model threshold resolved at the gate (single lookup).
-			const modelThreshold = _perModelThreshold;
-			// Reserve room for output tokens. Use the model's reported max output
-			// when known; fall back to 10% of the window (scales with any model —
-			// 20K for a 200K window, 100K for a 1M window) so we never let the
-			// preserved tail eat the model's output budget when maxTokens is unknown.
-			const maxOutput =
-				runtime.currentModel?.maxTokens && runtime.currentModel.maxTokens > 0
-					? runtime.currentModel.maxTokens
-					: Math.ceil(ctxWindow * 0.1);
-			let recent = recentRaw;
-			if (ctxWindow > 0 && recentRaw.length > 1) {
-				const summaryTokens = estimateBlockTokens(summaryMsg.text);
-				// Reserve: summary + max output + per-model safety margin (0-20%).
-				const safetyMargin = Math.ceil(
-					ctxWindow * (modelThreshold.safetyMarginPct / 100),
-				);
-				const budget = ctxWindow - maxOutput - safetyMargin - summaryTokens;
-				if (budget > 0) {
-					// Walk recent from the front, dropping oldest first until the
-					// remaining tail fits. Use the AgentMessage→engine-text estimate via
-					// messageContentText (already imported) + estimateMessageTokens.
-					let tailTokens = 0;
-					for (let i = recentRaw.length - 1; i >= 0; i--) {
-						const m = recentRaw[i];
-						tailTokens += estimateMessageTokens({
-							text: messageContentText(m),
-						});
-						if (tailTokens > budget) {
-							// Keep from i+1 onward; but never fewer than the final message.
-							const startIdx = Math.min(i + 1, recentRaw.length - 1);
-							if (startIdx > 0) {
-								recent = recentRaw.slice(startIdx);
-								runtime.logger.warn("live-trim-tail-cap", {
-									sessionId: runtime.rt.sessionId,
-									dropped: startIdx,
-									tailTokens,
-									safetyMarginPct: modelThreshold.safetyMarginPct,
-									budget,
-									ctxWindow,
-								});
-							}
-							break;
-						}
-					}
-				}
-			}
-
-			// v0.8.6: cache the trim view so subsequent gated calls in this epoch
-			// replay it verbatim (stabilizing the KV-cache prefix) instead of
-			// regenerating a fresh summary + sentinel every fire.
-			runtime.trimCache = {
-				// v0.8.7: key the replay cache on the STABLE epoch signal
-				// (rt.lastCheckpointId) instead of ran.result.checkpointId, which is
-				// dedup-volatile: on a re-compact that dedups onto a DIFFERENT existing
-				// checkpoint, result.checkpointId is the matched id (engine.ts:188) while
-				// lastCheckpointId is only updated on a genuinely new checkpoint
-				// (compact.ts:100-104). Keying on result.checkpointId would make
-				// trimCache.checkpointId != rt.lastCheckpointId forever after that
-				// dedup fire, disabling replay for the rest of the epoch (the
-				// alternating cache-miss that 0.8.6 meant to fix). Prefer the stable
-				// signal; fall back to result.checkpointId then the epoch timestamp
-				// only for the no-checkpoint edge case.
-				checkpointId:
-					runtime.rt.lastCheckpointId ??
-					ran.result.checkpointId ??
-					`epoch-${runtime.rt.lastCompactAt ?? Date.now()}`,
-				cut,
-				summaryAgentMsg,
-				ctxPct: pct ?? null,
-				ctxTokens: currentTokens,
-			};
-			runtime.snapshot(ctx);
-			// DIAG (team-run relief): confirm the live trim actually fires + how big
-			// the window still is. The return is non-durable (per-LLM-call only), so
-			// this is the signal that the model is being fed a compacted view while
-			// the on-disk transcript + context meter keep growing.
-			runtime.diagLiveTrimFires++;
-			runtime.logger.info("live-trim", {
-				sessionId: runtime.rt.sessionId,
-				inputMsgs: messages.length,
-				outputMsgs: recent.length + 1,
-				compactedFrom: cut,
-				ctxPct: pct,
-				ctxTokens: usage?.tokens ?? null,
-			});
-			return (
-				tailResult([summaryAgentMsg, ...recent]) ?? {
-					messages: [summaryAgentMsg, ...recent],
-				}
-			);
-		} catch {
-			runtime.diagCtxThrown++;
-			return tailResult() ?? undefined; // non-fatal: no trim this call; the next context event retries
-		}
+		// See liveTrim.ts. Non-destructive: pi keeps the real transcript; only this
+		// LLM call sees the trimmed window. Returns undefined on unsafe cut/throw —
+		// the next context event retries.
+		return buildLiveTrimView(runtime, config, ctx, {
+			messages,
+			view,
+			pct,
+			currentTokens,
+			usageTokens: usage?.tokens,
+			pressure: pipeline.pressure,
+			ran: pipeline.ran,
+			perModelThreshold: gate.perModelThreshold,
+			tailResult,
+		});
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "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/config/vector-cortex.ts

@@ -58,6 +58,28 @@ export const VC1B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1B");
  */
 export const VC0C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0C");
 
+/**
+ * VC1C — cross-language conformance v2 (FixtureManifestV2 / DowngradeReport /
+ * MinHashV2 + M4 minhash-v2 migration).
+ * Default ON. `MEGACOMPACT_VC1C=0` disables and is byte-identical to the
+ * predecessor (mode C: a v2 conformance runner that accepts authority fixtures
+ * and the manifest validator idle; the sync dedup scan stays on the v1 path;
+ * zero `vector_cortex_*` VC1C emissions). The real consumers are the conformance
+ * emit seam, the minhash-v2 backfill seam and the downgrade-export seam.
+ */
+export const VC1C_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1C");
+
+/**
+ * VC2A — offline model runtime and asset decision (ModelManifestV1 /
+ * EncoderRuntime).
+ * Default ON. `MEGACOMPACT_VC2A=0` disables and is byte-identical to the
+ * predecessor (mode C: no asset manifest is read/verified, the encoder runtime
+ * idles in mode C, zero `vector_cortex_encoder_*` emissions; the trigram/lexical
+ * paths are unchanged). The real consumers are the encoder emit seam and the
+ * encoder runtime's A/B/C selection.
+ */
+export const VC2A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC2A");
+
 // ---------------------------------------------------------------------------
 // Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
 // Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.

package/src/config.ts

@@ -156,6 +156,8 @@ export {
   VC1A_ENABLED,
   VC0C_ENABLED,
   VC1B_ENABLED,
+  VC1C_ENABLED,
+  VC2A_ENABLED,
   BREAKER_WINDOW_MS,
   BREAKER_MIN_ATTEMPTS,
   BREAKER_PERF_FAILURES,

package/src/dedup/l1-lsh-v2.ts

@@ -0,0 +1,78 @@
+/**
+ * l1-lsh-v2.ts — Locality-Sensitive Hashing banding over MinHashV2 signatures
+ * (VC1C, M4 minhash-v2).
+ *
+ * Splits the frozen 2048-byte v2 signature (256 x u64 LE slots) into 64 bands
+ * of FOUR u64 values each. Each band yields a deterministic bucket key derived
+ * from its 4 u64 little-endian bytes (32 bytes) hashed with a 64-bit FNV-1a,
+ * scoped by session id and the frozen v2 version tag so buckets never collide
+ * across sessions or the v1 path. Deterministic: same (sessionId,
+ * signatureBytes) -> same 64 bucket keys, every run, every language.
+ *
+ * Mixed v1/v2 comparison and bucket mixing is REJECTED upstream with
+ * `MINHASH_VERSION_MISMATCH` (see minhash-v2 migration); this module only ever
+ * bands a v2 signature.
+ *
+ * Pure compute, no deps, no storage, no network (PREVENT-PI-004 / PREVENT-011).
+ */
+
+import {
+  MINHASH_VERSION,
+  NUM_HASHES_V2,
+  U64_BYTES,
+} from "./l1-minhash-v2.js";
+
+/** Number of bands (frozen). */
+export const BANDS_V2 = 64 as const;
+
+/** u64 slots per band (frozen): 64 * 4 = 256 total slots. */
+export const VALUES_PER_BAND_V2 = 4 as const;
+
+/** Band byte length: 4 u64 LE = 32 bytes. */
+export const BAND_BYTES_V2 = VALUES_PER_BAND_V2 * U64_BYTES;
+
+/** Total signature byte length this scheme expects (256 * 8 = 2048). */
+export const SIGNATURE_BYTES_EXPECTED_V2 = NUM_HASHES_V2 * U64_BYTES;
+
+const MASK64 = 0xffffffffffffffffn;
+
+/** 64-bit FNV-1a over a byte buffer. */
+function fnv1a64Bytes(buf: Uint8Array): bigint {
+  let h = 0xcbf29ce484222325n;
+  for (let i = 0; i < buf.length; i++) {
+    h ^= BigInt(buf[i] ?? 0);
+    h = (h * 0x100000001b3n) & MASK64;
+  }
+  return h;
+}
+
+/**
+ * Compute the 64 LSH bucket keys for a v2 signature within a session. `bytes`
+ * is the 2048-byte little-endian signature (see encodeSignatureV2). Each bucket
+ * key is the hex of an 8-byte little-endian FNV-1a-64 over the band's 32 bytes
+ * prefixed by `<sessionId>|v2|band-` — so the "bucket bytes" are deterministic
+ * and reproducible across languages.
+ */
+export function lshBandsV2(
+  bytes: Uint8Array,
+  sessionId: string,
+  version: number = MINHASH_VERSION,
+): string[] {
+  if (bytes.length !== SIGNATURE_BYTES_EXPECTED_V2) {
+    throw new Error(
+      `lshBandsV2: expected ${SIGNATURE_BYTES_EXPECTED_V2} signature bytes, got ${bytes.length}`,
+    );
+  }
+  const keys: string[] = [];
+  const prefix = Buffer.from(`${sessionId}|v${version}|`, "utf8");
+  for (let band = 0; band < BANDS_V2; band++) {
+    const start = band * BAND_BYTES_V2;
+    const bandBytes = bytes.slice(start, start + BAND_BYTES_V2);
+    const combined = Buffer.concat([prefix, Buffer.from(bandBytes)]);
+    const h = fnv1a64Bytes(combined);
+    const out = Buffer.allocUnsafe(U64_BYTES);
+    out.writeBigUInt64LE(h, 0);
+    keys.push(`b${band}:${out.toString("hex")}`);
+  }
+  return keys;
+}