pi-mega-compact 0.16.3 → 0.17.1

package/extensions/mega-runtime/vector-cortex-ledger.ts

@@ -0,0 +1,165 @@
+/**
+ * vector-cortex-ledger.ts — VC1B occurrence-ledger writer wiring (S1).
+ *
+ * Wires ONLY the `LedgerWriter` capability into message ingestion: each
+ * canonical message that flows through the compaction pipeline becomes an
+ * occurrence in the v2 ledger. The wiring is writer-only (never reader/admin
+ * here — the dashboard GET owns the reader), matching the capability-gated
+ * CONTRACTS §Store rule. A tool RESULT occurrence references exactly one
+ * earlier call via `toolCallId` (the ledger enforces EVT_TOOL_CALL_MISSING).
+ *
+ * When MEGACOMPACT_VC1B is OFF the seam opens NO ledger DB at all — and even if
+ * a caller already holds a store, its write path is inert (S2 flag-gate in
+ * store.ts) — so the OFF behavior is byte-identical to the pre-VC1B predecessor.
+ *
+ * Local-only (PREVENT-PI-004), no `any` (PREVENT-011), no console.log (events
+ * go through the ledger emit seam); non-fatal — a ledger write failure never
+ * breaks the agent loop.
+ */
+import { createHash } from "node:crypto";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { VC1B_ENABLED } from "../../src/config/vector-cortex.js";
+import {
+	createLedgerStore,
+	type LedgerWriter,
+} from "../../src/vector-cortex/ledger/store.js";
+
+/** A single canonical message mapped to a ledger occurrence input. */
+export interface LedgerMessageInput {
+	readonly session: string;
+	readonly seq: bigint;
+	readonly eventId: string;
+	readonly kind: string;
+	readonly toolCallId?: string;
+	readonly sourceBytes: Uint8Array;
+}
+
+/** The writer handle handed to ingestion. */
+export interface LedgerWriterHandle {
+	readonly writer: LedgerWriter;
+	readonly close: () => void;
+}
+
+/** Open the ledger writer for ingestion, or null when VC1B is disabled. */
+export function openLedgerWriter(stateDir: string): LedgerWriterHandle | null {
+	if (!VC1B_ENABLED()) return null;
+	const store = createLedgerStore({ stateDir });
+	return { writer: store.writer(), close: () => store.close() };
+}
+
+/**
+ * Append one occurrence for a canonical message. `kind` is the neutral kind;
+ * when `toolCallId` is present the ledger enforces exactly-one reference to an
+ * earlier call. Flag-OFF (null handle) and the writer's own inert path are
+ * no-ops. Non-fatal: never throws to the loop — a failure is surfaced as
+ * `{ ok: false, code }` so the caller can log the reason (Q02).
+ */
+export function appendLedgerMessage(
+	handle: LedgerWriterHandle,
+	input: LedgerMessageInput,
+): { ok: boolean; code?: string } {
+	try {
+		const res = handle.writer.append(input);
+		return res.ok ? { ok: true } : { ok: false, code: res.code };
+	} catch (e) {
+		return { ok: false, code: String(e) };
+	}
+}
+
+/** Structured logger sink for seam append failures (wired by the extension). */
+export interface LedgerAppendLogger {
+	readonly warn: (event: string, fields: Record<string, unknown>) => void;
+}
+
+/**
+ * Append one occurrence per canonical message in `messages` (session-scoped,
+ * sequence = 1-based index). Opens the writer, appends each, closes the handle.
+ * Returns the number of accepted occurrences (0 when disabled OR when every
+ * append was a non-fatal no-op). This is the S1 ingestion seam.
+ *
+ * Monotonic-prefix assumption (Q02): the FIRST accepted append establishes the
+ * per-session high-water, and each subsequent append must carry `seq =
+ * highWater + 1`. Append order here follows `messages` array order with 1-based
+ * indices, so a shorter/mid-removal/reordered `messages` list after a prior
+ * taller run (rewind/fork) can drive `seq` backwards and be rejected with
+ * `EVT_SEQ_REGRESSION`. Such appends fail on the ledger and, without `onFailure`,
+ * are swallowed silently — so the caller should pass `onFailure` to log them.
+ */
+export function appendMessagesToLedger(
+	stateDir: string,
+	sessionId: string,
+	messages: AgentMessage[],
+	onFailure?: Readonly<LedgerAppendLogger>,
+): number {
+	const ledger = openLedgerWriter(stateDir);
+	if (!ledger) return 0;
+	try {
+		let accepted = 0;
+		for (let i = 0; i < messages.length; i++) {
+			const input = messageToLedgerInput(messages[i]!, sessionId, i);
+			const res = appendLedgerMessage(ledger, input);
+			if (res.ok) {
+				accepted++;
+			} else if (onFailure) {
+				onFailure.warn("vc1b-ledger-append-skip", {
+					session: sessionId,
+					seq: input.seq.toString(),
+					eventId: input.eventId,
+					kind: input.kind,
+					reason: res.code ?? "unknown",
+				});
+			}
+		}
+		return accepted;
+	} finally {
+		ledger.close();
+	}
+}
+
+/**
+ * Map an AgentMessage to a ledger occurrence input. `eventId` is the stable
+ * content digest so re-observed identical messages are (event_id,digest)-deduped;
+ * `kind` mirrors the canonical role. `toolCallId` is intentionally NOT set here:
+ * pi discriminates messages by `role` only and the tool-call id lives in
+ * variant-specific `.content`/`.tool_calls` we must not reach into, so the
+ * exactly-one tool back-edge (EVT_TOOL_CALL_MISSING) is exercised at the
+ * store/acceptance level and the full live mapping is deferred to the VC1
+ * producer-wiring sprint.
+ */
+export function messageToLedgerInput(
+	msg: AgentMessage,
+	session: string,
+	indexInSession: number,
+): LedgerMessageInput {
+	const m = msg as { role?: string; id?: string };
+	const text = messageText(msg);
+	const role = m.role ?? "unknown";
+	const digest = `sha256:${createHash("sha256").update(text).digest("hex")}`;
+	return {
+		session,
+		seq: BigInt(indexInSession + 1),
+		eventId: m.id ?? digest,
+		kind: role,
+		sourceBytes: new TextEncoder().encode(text),
+	};
+}
+
+/** Best-effort text extraction from an AgentMessage (string or part array). */
+function messageText(msg: AgentMessage): string {
+	const content = (msg as { content?: unknown }).content;
+	if (content == null) return "";
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		return content
+			.map((p) => {
+				const part = p as { type?: string; text?: string };
+				return typeof part.text === "string" ? part.text : "";
+			})
+			.join("\n");
+	}
+	if (typeof content === "object") {
+		const maybe = (content as Record<string, unknown>).text;
+		if (typeof maybe === "string") return maybe;
+	}
+	return "";
+}

package/extensions/mega-runtime/vector-cortex-safety.ts

@@ -0,0 +1,181 @@
+/**
+ * vector-cortex-safety.ts — VC0C live safety envelope (VC0C, task 4 + 5).
+ *
+ * Owns the live triad selection BEFORE provider invocation: select mode A
+ * (optimized/learned), then independent mode B (deterministic local spool
+ * deriving directly from authority), then unchanged mode C (continuity, not
+ * semantic completeness — C uses only the exact current transcript and reports
+ * that limitation). A manual reset clears cooldown but NEVER evidence.
+ *
+ * This adapter composes the resilience seams (`resilience/breaker.ts`,
+ * `resilience/spool.ts`, `resilience/emit.ts`) into the health/reset API the
+ * dashboard owns (`GET /api/vector-cortex/health`, admin
+ * `POST /api/vector-cortex/breakers/reset`). It is the pi-runtime-adjacent shell;
+ * all durable state is owned by the src/ resilience modules. Non-fatal: any
+ * breaker/spool noise degrades to mode C (unchanged host transcript), and the
+ * agent loop is never broken.
+ *
+ * Local-only (PREVENT-PI-004); no `any` (PREVENT-011); no console.log — events
+ * go through the injected resilience reporter / Logger.
+ *
+ * LIVENESS HONESTY (VC0C-Q01/Q06): the breaker composed here is PER-PROCESS /
+ * IN-MEMORY and EPHEMERAL — `createVectorCortexSafety` builds a fresh instance on
+ * every dashboard request (GET /health, POST /reset). There is NO persistent
+ * breaker runtime and NO live producer wiring (the real circuit-breaker that runs
+ * around the actual compaction loop is DEFERRED to the producer-wiring sprint,
+ * carried VC0B-I08 -> VC0D). Consequently GET /health always reflects a brand-new
+ * CLOSED_A instance and POST /reset mutates an instance that vanishes when the
+ * request returns: the endpoints are ILLUSTRATIVE until VC0D wires a persistent
+ * instance. The health payload therefore carries `stateSource:"ephemeral"` so the
+ * dashboard/README never present it as a live breaker. Frontier-frozen / spool-lag
+ * are owned by the DURABLE spool but have no live per-session handle here, so they
+ * are surfaced as static/non-live until VC0D (with authorityOutage mirrored from
+ * the host context when supplied).
+ */
+
+import { join } from "node:path";
+import { createResilienceReporter, type ResilienceReporter } from "../../src/vector-cortex/resilience/emit.js";
+import { createBreaker } from "../../src/vector-cortex/resilience/breaker.js";
+import { createSpool, type Spool } from "../../src/vector-cortex/resilience/spool.js";
+import type { BreakerRecord, Mode, TriadResult } from "../../src/vector-cortex/resilience/types.js";
+import { BREAKER_WINDOW_MS, VC0C_ENABLED } from "../../src/config/vector-cortex.js";
+
+/** Daily/health context the safety adapter needs from its host. */
+export interface VectorCortexSafetyContext {
+  /** State directory hosting the durable breaker/spool state. */
+  readonly stateDir: string;
+  /** Monotonic clock for windows/cooldowns (fake-clock testable). */
+  readonly now?: () => number;
+  /** Wall-clock supplier for record timestamps (default ISO now). */
+  readonly wallNow?: () => string;
+  /** True while the mode-A authority (SQLite ledger) is in OUTAGE. */
+  readonly authorityOutage?: () => boolean;
+}
+
+/** Health-card aggregate (dashboard contract). */
+export interface VectorCortexHealthSummary {
+  readonly enabled: boolean;
+  readonly mode: Mode;
+  readonly state: string;
+  readonly subsystem: string;
+  readonly sinceMs: number;
+  readonly reason?: string;
+  readonly windowMs: number;
+  readonly probeCount: number;
+  readonly backoffDelayMs: number;
+  readonly frontierFrozen: boolean;
+  readonly authorityOutage: boolean;
+  readonly spoolLag: number;
+  readonly attempts: number;
+  readonly failures: number;
+  readonly p95Ms: number;
+  readonly failureRate: number;
+  readonly updatedAt: string;
+  /** "ephemeral" => per-process/in-memory breaker; "live" => persistent (VC0D). */
+  readonly stateSource: "ephemeral" | "live";
+}
+
+export interface TriadProvider<T> {
+  readonly session: string;
+  readonly subsystem: string;
+  readonly inputDigest: string;
+  /** Mode A — optimized/learned. */
+  readonly runA: () => T;
+  /** Mode B — deterministic local spool, derives directly from authority. */
+  readonly runB: () => T;
+  /** Mode C — unchanged current transcript (continuity, NOT completeness). */
+  readonly runC: () => T;
+  readonly validate: (v: T) => boolean;
+}
+
+export interface VectorCortexSafety {
+  /**
+   * Select A, then independent B, then unchanged C BEFORE provider invocation.
+   * Demotes on live failure; the selected mode's output is the only thing served
+   * (probe output is never served).
+   */
+  select<T>(provider: TriadProvider<T>): TriadResult<T>;
+  /** Reader-only aggregate for GET /api/vector-cortex/health. */
+  health(): VectorCortexHealthSummary;
+  /** The mode-B durable spool (append before provider; drain on recovery). */
+  readonly spool: Spool;
+  /** Admin reset: clears cooldown, never evidence. Returns the new record. */
+  reset(subsystem: string): BreakerRecord;
+  /** Manual halt with a required reason (authority/digest/causal corruption). */
+  halt(reason: string): BreakerRecord;
+}
+
+/** Build the live safety envelope, wiring the emit seam into the breaker. */
+export function createVectorCortexSafety(
+  ctx: VectorCortexSafetyContext,
+  emit?: (event: string, fields: Record<string, unknown>) => void,
+): VectorCortexSafety {
+  const reporter: ResilienceReporter = createResilienceReporter(emit);
+  const wallNow = ctx.wallNow ?? (() => new Date().toISOString());
+  const breaker = createBreaker({ now: ctx.now, reporter, wallNow });
+  const spool = createSpool({
+    dir: join(ctx.stateDir, "spool"),
+    authorityOutage: ctx.authorityOutage,
+    // Wire the resilience emit seam (incl. vector_cortex_frontier_frozen) into
+    // the mode-B spool so a real authority-frontier freeze is observable.
+    reporter,
+  });
+
+  return {
+    spool,
+    select<T>(provider: TriadProvider<T>): TriadResult<T> {
+      const { subsystem, inputDigest, runA, runB, runC, validate } = provider;
+      // Thin delegation to the breaker: it selects the highest healthy mode
+      // (A, else independent B, else unchanged C) BEFORE provider invocation and
+      // records the attempt/trip. Across invocations A-failure demotes to B and
+      // B-failure demotes to C (continuity — unchanged transcript).
+      return breaker.execute(
+        subsystem,
+        inputDigest,
+        { A: runA, B: runB, C: runC },
+        validate,
+      );
+    },
+
+    health(): VectorCortexHealthSummary {
+      const rec = breaker.snapshot("provider");
+      const enabled = VC0C_ENABLED();
+      // LIVENESS HONESTY (VC0C-Q01/Q06): this breaker is created fresh per request
+      // and is ephemeral — declare it explicitly so the dashboard never presents it
+      // as a live breaker. `authorityOutage` is mirrored from the host context when
+      // supplied (otherwise false). `frontierFrozen` (rec.frozenFrontier) and
+      // `spoolLag` are owned by the DURABLE spool, which has no live per-session
+      // handle here — they stay static/no-op until VC0D wires a persistent breaker
+      // instance; stateSource:"ephemeral" is the signal that they are not live.
+      return {
+        enabled,
+        mode: rec.state === "MANUAL_HALT" ? "C" : rec.state === "CLOSED_A" ? "A" : "B",
+        state: rec.state,
+        subsystem: "provider",
+        sinceMs: rec.transitionedAtMs,
+        reason: rec.manualReason,
+        windowMs: BREAKER_WINDOW_MS,
+        probeCount: rec.probeCount,
+        backoffDelayMs: rec.retryDelayMs,
+        frontierFrozen: rec.frozenFrontier,
+        authorityOutage: ctx.authorityOutage?.() ?? false,
+        spoolLag: 0,
+        attempts: rec.attempts,
+        failures: rec.failures,
+        p95Ms: rec.p95Ms,
+        failureRate: rec.failureRate,
+        updatedAt: wallNow(),
+        stateSource: "ephemeral",
+      };
+    },
+
+    reset(subsystem: string): BreakerRecord {
+      return breaker.reset(subsystem);
+    },
+
+    halt(reason: string): BreakerRecord {
+      return breaker.manualHalt(reason);
+    },
+  };
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.16.3",
+  "version": "0.17.1",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",
@@ -47,6 +47,7 @@
     "clean": "rm -rf dist",
     "prebuild": "npm run clean",
     "build": "tsc -p tsconfig.json",
+    "postbuild": "node scripts/vector-cortex-publish-acceptance.mjs",
     "build:dashboard": "cd extensions/dashboard-client && npx vite build",
     "test:dashboard-smoke": "node scripts/dashboard-tab-smoke.mjs",
     "lint": "tsc --noEmit && node scripts/guardrails-scan.mjs && node scripts/semantic-scan.mjs",

package/src/config/vector-cortex.ts

@@ -0,0 +1,98 @@
+/**
+ * config/vector-cortex.ts — vector-cortex feature flags + breaker/triad constants.
+ *
+ * Every sprint ships one positive `MEGACOMPACT_<SPRINT>` flag, default ON and
+ * `=0`/`_DISABLED` off. Flag-OFF is byte-identical to the predecessor sprint's
+ * behavior (for VC0A: mode C — observer absent, zero evaluation writes).
+ *
+ * The breaker/triad constants (TRIAD_RESILIENCE.md) live here so VC0C consumes
+ * them without re-declaring the ownership boundary. Pi-agnostic, dependency-free.
+ */
+
+/** Positive sprint flag: `=0` or `_DISABLED=true` disables (default ON). */
+function sprintFlag(name: string): boolean {
+  const v = process.env[name];
+  if (v === "0" || v === "false") return false;
+  const disabled = process.env[name + "_DISABLED"];
+  if (disabled === "true" || disabled === "1") return false;
+  return true;
+}
+
+/** VC0A — baseline observability (MetricEventV1 / AnnotationV1). Default ON. */
+export const VC0A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0A");
+
+/**
+ * VC0B — replay correctness (ReplayCutV2 / ReplayReportV2, M3 effective-cut-v2).
+ * Default ON. `MEGACOMPACT_VC0B=0` disables and is byte-identical to the
+ * predecessor (legacy capped-replay behavior preserved; the v2 cut/replay is
+ * only consulted on the vector-cortex path).
+ */
+export const VC0B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC0B");
+
+/**
+ * VC1A — canonical byte events (EventV2 / EventCodec).
+ * Default ON. `MEGACOMPACT_VC1A=0` disables and is byte-identical to the
+ * predecessor (mode C: ledger absent, current transcript codec unchanged).
+ * The single real consumer is the ledger emit seam (`ledger/emit.ts`): flag OFF
+ * gates zero observability writes.
+ */
+export const VC1A_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1A");
+
+/**
+ * VC1B — occurrence ledger + tool identity + compat journal (LedgerReader/
+ * Writer/Admin, CompatJournalV1, M2 occurrence-v2 migration).
+ * Default ON. `MEGACOMPACT_VC1B=0` disables and is byte-identical to the
+ * predecessor (mode C: the neutral occurrence ledger is not written, no
+ * journal rows, zero `vector_cortex_occurrence_appended` emissions). The real
+ * consumers are the ledger write integration seam and the compat-journal
+ * switch seam.
+ */
+export const VC1B_ENABLED = (): boolean => sprintFlag("MEGACOMPACT_VC1B");
+
+/**
+ * VC0C — live safety envelope (TriadResult / Breaker / KillDecision + durable
+ * spool). Default ON. `MEGACOMPACT_VC0C=0` disables and is byte-identical to
+ * the predecessor (mode C: selected before provider invocation, unchanged host
+ * transcript, breaker/spool idle and emitting nothing). The single real
+ * consumer is the resilience emit seam + the safety adapter's triad selection.
+ */
+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");
+
+// ---------------------------------------------------------------------------
+// Breaker state machine constants (TRIAD_RESILIENCE.md §breaker).
+// Rolled numbers for one 60s window; VC0C consumes these at its breaker seam.
+// ---------------------------------------------------------------------------
+
+/** Rolling eligibility window (milliseconds). */
+export const BREAKER_WINDOW_MS = 60_000;
+/** Minimum attempts before a breaker may trip or promote. */
+export const BREAKER_MIN_ATTEMPTS = 20;
+/** Performance trip: ≥ this many failures in window, or ≥ this fraction. */
+export const BREAKER_PERF_FAILURES = 5;
+export const BREAKER_PERF_FAILURE_RATE = 0.1;
+/** Correctness trip trips on the first correctness failure. */
+export const BREAKER_CORRECTNESS_FAILURES = 1;
+/** Cooldown before an open breaker may probe (milliseconds). */
+export const BREAKER_COOLDOWN_MS = 30_000;
+/** Consecutive successful probes required to advance a state. */
+export const BREAKER_PROBE_COUNT = 3;
+/** Exponential retry base: 30s * 2^attempt, capped, ±10% jitter. */
+export const BREAKER_RETRY_BASE_MS = 30_000;
+export const BREAKER_RETRY_CAP_MS = 15 * 60_000;
+export const BREAKER_RETRY_JITTER = 0.1;
+/** Promotion hysteresis: failure rate must be < this and p95 within budget. */
+export const BREAKER_HYSTERESIS_FAILURE_RATE = 0.02;
+export const BREAKER_HYSTERESIS_BUDGET_P95_MS = 50;
+/** Minimum healthy residence before a further promotion (milliseconds). */
+export const BREAKER_MIN_HEALTHY_RESIDENCE_MS = 5 * 60_000;

package/src/config.ts

@@ -143,3 +143,31 @@ export const RAG_HYDE_ENABLED = (): boolean =>
 
 /** Spec 1: vbrainstorm visual design migration for the dashboard. */
 export const NEW_UI = (): boolean => ragEnabled("MEGACOMPACT_NEW_UI");
+
+// ---------------------------------------------------------------------------
+// Vector-cortex flags + breaker constants (VC0A+). Positive sprint flags,
+// default ON, `=0`/`_DISABLED` off. Re-exported from src/config/vector-cortex.ts
+// so root consumers share one source of truth.
+// ---------------------------------------------------------------------------
+
+export {
+  VC0A_ENABLED,
+  VC0B_ENABLED,
+  VC1A_ENABLED,
+  VC0C_ENABLED,
+  VC1B_ENABLED,
+  VC1C_ENABLED,
+  BREAKER_WINDOW_MS,
+  BREAKER_MIN_ATTEMPTS,
+  BREAKER_PERF_FAILURES,
+  BREAKER_PERF_FAILURE_RATE,
+  BREAKER_CORRECTNESS_FAILURES,
+  BREAKER_COOLDOWN_MS,
+  BREAKER_PROBE_COUNT,
+  BREAKER_RETRY_BASE_MS,
+  BREAKER_RETRY_CAP_MS,
+  BREAKER_RETRY_JITTER,
+  BREAKER_HYSTERESIS_FAILURE_RATE,
+  BREAKER_HYSTERESIS_BUDGET_P95_MS,
+  BREAKER_MIN_HEALTHY_RESIDENCE_MS,
+} from "./config/vector-cortex.js";

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;
+}