pi-mega-compact 0.20.14 → 0.20.16

package/src/vector-cortex/cache/_diagnostics-fixture.ts

@@ -0,0 +1,32 @@
+/**
+ * cache/_diagnostics-fixture.ts — VC7C acceptance-test fixture helpers.
+ *
+ * Reads conformance fixtures from the v2 `cache-diagnostics/` domain and provides
+ * a flag-toggling wrapper for VC7C parity tests. Mirrors `_economics-fixture.ts`.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const V2 = join(here, "..", "..", "..", "conformance", "vector-cortex", "v2");
+const DIR = join(V2, "cache-diagnostics");
+
+/** Read + parse one conformance fixture by ID. */
+export function diagnosticsFixture(id: string): Record<string, unknown> {
+  const raw = readFileSync(join(DIR, `${id}.json`), "utf8");
+  return JSON.parse(raw);
+}
+
+/** Run `fn` with MEGACOMPACT_VC7C set to `value`, restoring the prior value after. */
+export function withVc7cFlag<T>(value: string, fn: () => T): T {
+  const prior = process.env.MEGACOMPACT_VC7C;
+  process.env.MEGACOMPACT_VC7C = value;
+  try {
+    return fn();
+  } finally {
+    if (prior === undefined) delete process.env.MEGACOMPACT_VC7C;
+    else process.env.MEGACOMPACT_VC7C = prior;
+  }
+}

package/src/vector-cortex/cache/breaker.ts

@@ -0,0 +1,124 @@
+/**
+ * cache/breaker.ts — VC7C cache-serve breaker (composes VC0C's createBreaker).
+ *
+ * This file does NOT reinvent a state machine. It wraps the TRIAD breaker from
+ * `../resilience/breaker-core.js` (VC0C) — the same CLOSED_A / OPEN_B / OPEN_C /
+ * PROBE_* / MANUAL_HALT states that protect every other subsystem — and adds the
+ * ONE cache-specific decision: whether a classified miss should block a cache
+ * SERVE before it can answer from a stale or invalid identity.
+ *
+ * TRIP KIND CLASSIFICATION (per team-lead correction + TRIAD_RESILIENCE §breaker):
+ * The four cache demotion conditions map onto `BreakerTripKind` as follows:
+ *
+ *   CORRECTNESS trips (trip on the FIRST failure, no rolling window):
+ *     - profile mismatch     — the crystal was minted under a different provider
+ *                              profile; serving it would return bytes for the wrong
+ *                              model tier. This is never "recovered from" by waiting.
+ *     - range mismatch       — the crystal's covered digest differs from the
+ *                              request's; the crystal covers different spans and
+ *                              serving it would return another conversation's frozen
+ *                              bytes. (Includes digest failure / collision.)
+ *     - request mismatch     — the request digest differs; the crystal was built
+ *                              for a different request entirely.
+ *
+ *   PERFORMANCE trips (accumulated over a rolling window before opening):
+ *     - dependency advanced   — the dependency high-water moved past the crystal's
+ *                              cached position. The crystal is stale but not WRONG;
+ *                              a single advance is normal churn. Repeated advances
+ *                              across a window indicate the cache is systematically
+ *                              behind the frontier — that is a performance signal.
+ *     - generation invalidated — the M6 router generation was invalidated. A single
+ *                              invalidation is expected during a router cut; repeated
+ *                              invalidations indicate a systematic generation
+ *                              instability.
+ *
+ * The distinction matters because a CORRECTNESS trip opens the breaker IMMEDIATELY
+ * (first failure), while a PERFORMANCE trip requires BREAKER_PERF_FAILURES within
+ * BREAKER_WINDOW_MS. The VC0C breaker-core already implements this via
+ * `BreakerTripKind`; we map each miss class to its trip kind and let breaker-core
+ * handle the window/threshold logic.
+ *
+ * "PROBE OUTPUT IS NEVER SERVED" (TRIAD_RESILIENCE line 13): when the breaker is in
+ * PROBE_A or PROBE_B, the probe is a TEST serve — its output must not be returned
+ * to the caller. `decideCacheServe` enforces this: PROBE_* states always return
+ * `block: true` and the fallback mode, never serving from cache.
+ *
+ * The decision is a CORRECTNESS behavior and is NEVER flag-gated (unlike the
+ * reporter seam in `./diagnostics-emit.ts`): flag-off must be byte-identical to
+ * the predecessor. `breakerRetryDelay()` from VC0C already implements the
+ * deterministic +-10% jitter from the subsystem digest — we use it, don't re-derive.
+ *
+ * PREVENT-002/011/PI-004 honored.
+ */
+
+import { createBreaker, type ConcreteBreaker } from "../resilience/breaker-core.js";
+import type { BreakerRecord, BreakerTripKind, Mode } from "../resilience/types.js";
+import type { MissClass } from "./diagnostics-types.js";
+
+/** The cache subsystem the breaker tracks (one triad state machine). */
+export const CACHE_SUBSYSTEM = "vector-cortex-cache-serve";
+
+/** Build the cache breaker. Composes VC0C — no parallel state machine here. */
+export function createCacheBreaker(opts?: {
+  now?: () => number;
+  onEvent?: (event: Record<string, unknown>) => void;
+}): ConcreteBreaker {
+  return createBreaker({ now: opts?.now, onEvent: opts?.onEvent });
+}
+
+/**
+ * Map a miss class to its breaker trip kind. Profile, range (digest/collision),
+ * and request mismatches are CORRECTNESS trips — they trip on the FIRST failure
+ * because serving a crystal with the wrong identity is never safe, no matter how
+ * rarely it happens. Dependency advance and generation invalidation are
+ * PERFORMANCE trips — a single occurrence is normal churn; only repeated
+ * failures within a window indicate a systematic problem.
+ */
+export function tripKindForMiss(missClass: MissClass): BreakerTripKind {
+  switch (missClass) {
+    case "profile":
+    case "range":
+    case "request":
+      return "correctness";
+    case "dependency":
+    case "generation":
+      return "performance";
+    case "unknown":
+      return "performance";
+  }
+}
+
+/**
+ * Whether a classified miss must block the cache serve. Pure over the class; the
+ * ONLY thing that is allowed to demote an otherwise-healthy cache is a real
+ * disagreement between what was cached and what the request now requires.
+ * `unknown` is not auto-blocked — the triad's own performance window handles it.
+ */
+export function shouldBlockServe(missClass: MissClass): boolean {
+  return missClass !== "unknown";
+}
+
+/**
+ * Decide the triad mode to render under, given a classified miss and the live
+ * breaker. A blockable miss forces mode B (fresh render) unless the breaker is
+ * already in a deeper open state (C = all-cache bypass) — never contradicting the
+ * triad's own resilience verdict. PROBE_* states are NEVER served from cache
+ * (TRIAD_RESILIENCE line 13: "probe output is never served").
+ */
+export function decideCacheServe(
+  missClass: MissClass,
+  breaker: ConcreteBreaker,
+): { block: boolean; fallbackMode: Mode; tripKind: BreakerTripKind } {
+  const tripKind = tripKindForMiss(missClass);
+  if (!shouldBlockServe(missClass)) {
+    return { block: false, fallbackMode: breaker.modeFor(CACHE_SUBSYSTEM), tripKind };
+  }
+  const record: BreakerRecord = breaker.snapshot(CACHE_SUBSYSTEM);
+  if (record.state === "OPEN_C" || record.state === "MANUAL_HALT") {
+    return { block: true, fallbackMode: "C", tripKind };
+  }
+  if (record.state === "PROBE_A" || record.state === "PROBE_B") {
+    return { block: true, fallbackMode: record.state === "PROBE_A" ? "C" : "B", tripKind };
+  }
+  return { block: true, fallbackMode: "B", tripKind };
+}

package/src/vector-cortex/cache/diagnostics-emit.ts

@@ -0,0 +1,90 @@
+/**
+ * cache/diagnostics-emit.ts — VC7C reporter seam (FLAG-GATED).
+ *
+ * Mirrors `./economics-emit.ts`: a thin `safe()` wrapper around an optional
+ * injected `emit`, and the two event names the sprint spec requires verbatim:
+ *   - `vector_cortex_cache_miss_classified` — a miss was classified.
+ *   - `vector_cortex_cache_serve_blocked` — a cache serve was blocked by a
+ *     breaker condition before it could answer from a stale/invalid identity.
+ *
+ * FLAG SEMANTICS. `classifyMiss` (`./diagnostics.ts`) is PURE and runs REGARDLESS
+ * of `MEGACOMPACT_VC7C`. The flag gates ONLY this reporting + dashboard seam:
+ * with the flag off the classifier still returns the SAME class, the breaker
+ * still blocks the SAME serve — we just do not announce them under the VC7C
+ * event namespace, and the dashboard reports `enabled:false` + mode C. That is
+ * what makes flag-off byte-identical to the predecessor (VC7B): the arithmetic
+ * and the correctness decision are never skipped, only the emission. (NOTE the
+ * asymmetry vs VC7B: VC7B gated pure telemetry; here the blocked-serve DECISION
+ * is a correctness behavior and is never flag-gated — only its announcement is.)
+ *
+ * PAYLOAD DISCIPLINE. These events carry the `missClass` and the payload-free
+ * `evidence` booleans/counts (see `./diagnostics-types.ts`) — never a session
+ * id, never a covered range, never a request or covered digest. The classifier
+ * is payload-free by construction, so there is no slot to leak into
+ * (SECURITY_PRIVACY — the exact ledger is not diagnostic data).
+ *
+ * No console, no storage, no network (PREVENT-PI-004 / PREVENT-011). Every line
+ * is a structured JSON event with `ts` + `event`.
+ */
+
+import { VC7C_ENABLED } from "../../config/vector-cortex.js";
+import type { CacheDiagnosticV1, MissClass } from "./diagnostics-types.js";
+
+/** The two structured events the VC7C reporter emits. */
+export type CacheDiagnosticEventName =
+  | "vector_cortex_cache_miss_classified"
+  | "vector_cortex_cache_serve_blocked";
+
+/** Optional emit fn injected by the runtime; tests pass `undefined`. */
+export type CacheDiagnosticEmit = (name: string, payload: unknown) => void;
+
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(
+  emit: CacheDiagnosticEmit | undefined,
+  fn: (emit: CacheDiagnosticEmit) => void,
+): void {
+  if (emit === undefined) return;
+  try {
+    fn(emit);
+  } catch {
+    // Non-fatal: a reporting failure must never break the agent loop.
+  }
+}
+
+/** Report a classified miss. Gated only by the reporter/dashboard flag. */
+export function reportCacheMissClassified(
+  emit: CacheDiagnosticEmit | undefined,
+  diagnostic: CacheDiagnosticV1,
+): void {
+  if (!VC7C_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_cache_miss_classified", {
+      ts: undefined,
+      event: "vector_cortex_cache_miss_classified",
+      schema: diagnostic.schema,
+      missClass: diagnostic.missClass,
+      evidence: diagnostic.evidence,
+    }),
+  );
+}
+
+/** Report a cache serve that was blocked before answering. Gated by the flag. */
+export function reportCacheServeBlocked(
+  emit: CacheDiagnosticEmit | undefined,
+  blocked: {
+    readonly missClass: MissClass;
+    readonly triadState: string;
+    readonly reason: string;
+  },
+): void {
+  if (!VC7C_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_cache_serve_blocked", {
+      ts: undefined,
+      event: "vector_cortex_cache_serve_blocked",
+      missClass: blocked.missClass,
+      triadState: blocked.triadState,
+      reason: blocked.reason,
+    }),
+  );
+}

package/src/vector-cortex/cache/diagnostics-types.ts

@@ -0,0 +1,87 @@
+/**
+ * cache/diagnostics-types.ts — VC7C cache miss-diagnostic contract types.
+ *
+ * Single source of truth for the miss-classification vocabulary. Kept separate
+ * from the arithmetic (`diagnostics.ts`) so the dashboard client, the emit layer
+ * and the acceptance test all import ONE definition. No logic here; pure types
+ * + the registered ID lists. PREVENT-011 honored (no `any`).
+ */
+
+/** The exclusive miss classes, in the order the classifier ranks them. */
+export type MissClass =
+  | "profile"
+  | "range"
+  | "dependency"
+  | "request"
+  | "generation"
+  | "unknown";
+
+/**
+ * Payload-free by construction. Every field is a boolean or a bounded,
+ * non-negative count — there is no string slot into which a request body, a
+ * session id, or a covered range of user content could be placed. See
+ * SECURITY_PRIVACY: a diagnostic that carried the offending payload would leak
+ * it to the dashboard.
+ */
+export interface MissEvidence {
+  readonly profileMismatch: boolean;
+  readonly rangeMismatch: boolean;
+  readonly dependencyAdvanced: boolean;
+  readonly requestMismatch: boolean;
+  readonly generationInvalidated: boolean;
+  /** Ranges the caller asked for (always observable, even on a cold key). */
+  readonly requestedRangeCount: number;
+  /** Ranges the cache could serve; 0 on a cold key (no crystal). */
+  readonly cachedRangeCount: number;
+  /** max(0, requestHighWater - cachedHighWater), saturated at MAX_SAFE_INTEGER. */
+  readonly dependencyDelta: number;
+  /** True when nothing was cached for this key (null cached fields). */
+  readonly absent: boolean;
+}
+
+/**
+ * A single observation fed to the classifier. A `null` cached field means that
+ * piece of state was never persisted — "absence is not a mismatch". Digests
+ * follow convention: `coveredDigest` is `sha256:<hex>` (WITH prefix);
+ * `requestDigest` is BARE lowercase hex (NO prefix).
+ */
+export interface MissObservation {
+  readonly requestProfileId: string;
+  readonly requestProfileVersion: string;
+  readonly cachedProfileId: string | null;
+  readonly cachedProfileVersion: string | null;
+  readonly requestCoveredDigest: string;
+  readonly cachedCoveredDigest: string | null;
+  readonly requestedRangeCount: number;
+  readonly cachedRangeCount: number | null;
+  readonly requestDigest: string;
+  readonly cachedRequestDigest: string | null;
+  /** Dependency validation high-water (monotonic frontier), as a bigint. */
+  readonly requestDependencyHighWater: bigint;
+  readonly cachedDependencyHighWater: bigint | null;
+  readonly generationInvalidated: boolean;
+}
+
+/** The versioned diagnostic record emitted for every classified miss. */
+export interface CacheDiagnosticV1 {
+  readonly schema: "cache-diagnostic-v1";
+  readonly missClass: MissClass;
+  readonly evidence: MissEvidence;
+}
+
+/** Registered conformance IDs (CACHE-016..030). */
+export const CACHE_DIAGNOSTIC_IDS: readonly string[] = Array.from(
+  { length: 15 },
+  (_v, i) => `CACHE-${String(i + 16).padStart(3, "0")}`,
+);
+
+/** Named headlines surfaced by the conformance corpus. */
+export const CACHE_DIAGNOSTIC_NAMED_IDS = [
+  "CACHE-MISS-001",
+  "CACHE-STALE-003",
+] as const;
+
+/** Event names this subsystem emits (gated by MEGACOMPACT_VC7C). */
+export type CacheDiagnosticEventName =
+  | "vector_cortex_cache_miss_classified"
+  | "vector_cortex_cache_serve_blocked";

package/src/vector-cortex/cache/diagnostics.ts

@@ -0,0 +1,119 @@
+/**
+ * cache/diagnostics.ts — VC7C pure miss classification (flag-independent).
+ *
+ * The classifier is PURE arithmetic: given a `MissObservation` it returns
+ * exactly ONE `MissClass` and the payload-free `MissEvidence`. It is NOT gated by
+ * MEGACOMPACT_VC7C — flag-off must be byte-identical to the predecessor, so the
+ * SAME class a user sees today, they see tomorrow. The flag gates only the
+ * reporter/dashboard seam (see `diagnostics-emit.ts`).
+ *
+ * Exclusive ranking: profile -> range -> dependency -> request -> generation ->
+ * unknown. First match wins; the ranking itself is the contract and is pinned by
+ * CACHE-016..030. "Absence is not a mismatch": a cold key (null cached fields)
+ * classifies `unknown`, never `profile`. PREVENT-002/011/PI-004 honored.
+ */
+
+import type {
+  CacheDiagnosticV1,
+  MissClass,
+  MissEvidence,
+  MissObservation,
+} from "./diagnostics-types.js";
+
+/** A cached field is present iff it is non-null. */
+function isPresent(value: string | number | bigint | null): boolean {
+  return value !== null;
+}
+
+/**
+ * Clamp the dependency delta to a non-negative, safe-integer count. A request
+ * BEHIND the cached frontier is not an advance (delta 0); a huge advance
+ * saturates rather than losing precision.
+ */
+function advanceDelta(
+  request: bigint,
+  cached: bigint | null,
+): { advanced: boolean; delta: number } {
+  if (cached === null) return { advanced: false, delta: 0 };
+  if (request <= cached) return { advanced: false, delta: 0 };
+  const diff = request - cached;
+  if (diff > BigInt(Number.MAX_SAFE_INTEGER)) {
+    return { advanced: true, delta: Number.MAX_SAFE_INTEGER };
+  }
+  return { advanced: true, delta: Number(diff) };
+}
+
+/** Collect the payload-free evidence from one observation. */
+export function collectEvidence(o: MissObservation): MissEvidence {
+  const profileMismatch =
+    isPresent(o.cachedProfileId) &&
+    isPresent(o.cachedProfileVersion) &&
+    (o.cachedProfileId !== o.requestProfileId ||
+      o.cachedProfileVersion !== o.requestProfileVersion);
+
+  const rangeMismatch =
+    (isPresent(o.cachedCoveredDigest) &&
+      o.cachedCoveredDigest !== o.requestCoveredDigest) ||
+    (isPresent(o.cachedRangeCount) &&
+      o.cachedRangeCount !== o.requestedRangeCount);
+
+  const dep = advanceDelta(
+    o.requestDependencyHighWater,
+    o.cachedDependencyHighWater,
+  );
+
+  const requestMismatch =
+    isPresent(o.cachedRequestDigest) &&
+    o.cachedRequestDigest !== o.requestDigest;
+
+  const absent =
+    !isPresent(o.cachedProfileId) &&
+    !isPresent(o.cachedCoveredDigest) &&
+    !isPresent(o.cachedRequestDigest) &&
+    !isPresent(o.cachedDependencyHighWater);
+
+  return {
+    profileMismatch,
+    rangeMismatch,
+    dependencyAdvanced: dep.advanced,
+    requestMismatch,
+    generationInvalidated: o.generationInvalidated,
+    requestedRangeCount: o.requestedRangeCount,
+    // Nothing was cached when the observation is absent, so a stale
+    // cachedRangeCount on the observation is not real — report 0.
+    cachedRangeCount:
+      o.cachedRangeCount === null || absent ? 0 : o.cachedRangeCount,
+    dependencyDelta: dep.delta,
+    absent,
+  };
+}
+
+/** The exclusive ranking: first true cause wins. */
+export function classFor(e: MissEvidence): MissClass {
+  if (e.profileMismatch) return "profile";
+  if (e.rangeMismatch) return "range";
+  if (e.dependencyAdvanced) return "dependency";
+  if (e.requestMismatch) return "request";
+  if (e.generationInvalidated) return "generation";
+  return "unknown";
+}
+
+/** Classify one observation: exactly one deterministic class. */
+export function classifyMiss(o: MissObservation): CacheDiagnosticV1 {
+  const evidence = collectEvidence(o);
+  return {
+    schema: "cache-diagnostic-v1",
+    missClass: classFor(evidence),
+    evidence,
+  };
+}
+
+/**
+ * A miss a caller can self-heal on the next turn (re-fetch under a fresh
+ * profile / a new generation), so a triad recovery path may treat it as
+ * transient. Only profile + generation qualify; the rest are hard mismatches.
+ * An `unknown` miss is NEVER transient.
+ */
+export function isTransientMiss(d: CacheDiagnosticV1): boolean {
+  return d.missClass === "profile" || d.missClass === "generation";
+}

package/src/vector-cortex/migrations/request-hash-v2-ops.ts

@@ -0,0 +1,201 @@
+/**
+ * request-hash-v2-ops.ts — M5 migration operational logic (copy/verify/switch).
+ *
+ * Extracted from request-hash-v2.ts to keep the parent file under the 300-line
+ * soft limit (soft-as-hard gate). Pure logic over an injected M5Host;
+ * deterministic + testable; no console. PREVENT-002/011/PI-004 honored.
+ */
+import { createHash } from "node:crypto";
+import { invalidationKey } from "../topology/query.js";
+import type {
+  M5Host,
+  M5MigrationCode,
+  M5ValidateResult,
+  RequestHashV1Row,
+  RequestHashV2Row,
+} from "./request-hash-v2-types.js";
+import {
+  M5_FAIL,
+  REQUEST_HASH_LEGACY_VERSION,
+} from "./request-hash-v2-types.js";
+
+/** Length-prefixed framing so the folded fields cannot alias. */
+function field(value: string): string {
+  return `${Buffer.byteLength(value, "utf8")}:${value}`;
+}
+
+const identity = (profileId: string, requestDigest: string): string =>
+  `${profileId}::${requestDigest}`;
+
+/**
+ * The authoritative v2 hash: SHA-256 over the version tag, profile, request
+ * digest, and economics version. Length-prefixed for injectivity, exactly as the
+ * crystal key encoder frames its fields.
+ */
+export function deriveRequestHashV2(
+  profileId: string,
+  requestDigest: string,
+  economicsVersion: string,
+): string {
+  return createHash("sha256")
+    .update(
+      field("request-hash-v2") +
+        field(profileId) +
+        field(requestDigest) +
+        field(economicsVersion),
+      "utf8",
+    )
+    .digest("hex");
+}
+
+/** Derive the v2 row for one v1 row. */
+export function deriveRequestHashRow(
+  host: M5Host,
+  v1: RequestHashV1Row,
+): RequestHashV2Row {
+  const economicsVersion = host.economicsVersionOf(v1.profileId);
+  return {
+    profileId: v1.profileId,
+    // IDENTITY-PRESERVING: carried through verbatim, never re-derived.
+    requestDigest: v1.requestDigest,
+    economicsVersion,
+    hash: deriveRequestHashV2(v1.profileId, v1.requestDigest, economicsVersion),
+  };
+}
+
+/**
+ * Economics versions encode the generation they were minted under. We treat the
+ * trailing numeric segment as the generation; if it is not numeric the row is
+ * considered tied to generation 0 (always live unless explicitly invalidated).
+ */
+function generationFromEconomics(economicsVersion: string): bigint {
+  const match = /(\d+)$/.exec(economicsVersion);
+  return match ? BigInt(match[1]) : 0n;
+}
+
+export function detectCollision(host: M5Host): boolean {
+  const byHash = new Map<string, string>();
+  const seenIdentities = new Set<string>();
+  for (const v1 of host.v1Rows()) {
+    const row = deriveRequestHashRow(host, v1);
+    const id = identity(v1.profileId, v1.requestDigest);
+    // Two distinct v1 rows (different v1 hash) with the same v2 hash collide,
+    // even if they share an identity — the v2 table cannot distinguish them.
+    if (seenIdentities.has(id)) return true;
+    seenIdentities.add(id);
+    const prior = byHash.get(row.hash);
+    if (prior !== undefined && prior !== id) return true;
+    byHash.set(row.hash, id);
+  }
+  return false;
+}
+
+export function isGenerationInvalidated(
+  host: M5Host,
+  row: RequestHashV2Row,
+): boolean {
+  const session = host.sessionOf(row.profileId);
+  const live = host.liveGenerationOf(session);
+  const keyForLive = invalidationKey(session, live);
+  const keyForRow = invalidationKey(
+    session,
+    generationFromEconomics(row.economicsVersion),
+  );
+  return keyForLive !== keyForRow;
+}
+
+export function m5Copy(host: M5Host): {
+  readonly written: readonly RequestHashV2Row[];
+  readonly all: readonly RequestHashV2Row[];
+} {
+  const existing = new Map(
+    host.existingV2().map((r) => [identity(r.profileId, r.requestDigest), r]),
+  );
+  const wanted: RequestHashV2Row[] = [];
+  for (const v1 of host.v1Rows()) {
+    const fresh = deriveRequestHashRow(host, v1);
+    if (isGenerationInvalidated(host, fresh)) continue;
+    const stored = existing.get(identity(v1.profileId, v1.requestDigest));
+    if (
+      stored !== undefined &&
+      stored.hash === fresh.hash &&
+      stored.economicsVersion === fresh.economicsVersion
+    ) {
+      continue;
+    }
+    wanted.push(fresh);
+  }
+  if (wanted.length > 0) host.putV2(wanted);
+  return { written: wanted, all: [...host.existingV2()] };
+}
+
+function dedupe(codes: readonly M5MigrationCode[]): M5MigrationCode[] {
+  const out: M5MigrationCode[] = [];
+  for (const c of codes) if (!out.includes(c)) out.push(c);
+  return out;
+}
+
+export function m5Verify(host: M5Host): M5ValidateResult {
+  const codes: M5MigrationCode[] = [];
+  const stored = host.existingV2();
+  const v1Rows = host.v1Rows();
+
+  const counts = new Map<string, number>();
+  for (const r of stored) {
+    const id = identity(r.profileId, r.requestDigest);
+    counts.set(id, (counts.get(id) ?? 0) + 1);
+  }
+
+  const expected = new Set<string>();
+  for (const v1 of v1Rows) {
+    const id = identity(v1.profileId, v1.requestDigest);
+    // Dead-generation rows are intentionally skipped by copy; do not flag.
+    const fresh = deriveRequestHashRow(host, v1);
+    if (isGenerationInvalidated(host, fresh)) continue;
+    expected.add(id);
+    const n = counts.get(id) ?? 0;
+    if (n === 0) codes.push(M5_FAIL.COPY_PARTIAL);
+    if (n > 1) codes.push(M5_FAIL.COUNT_MISMATCH);
+  }
+
+  const v1Digests = new Set(
+    v1Rows.map((r) => identity(r.profileId, r.requestDigest)),
+  );
+  for (const r of stored) {
+    const fresh = deriveRequestHashV2(
+      r.profileId,
+      r.requestDigest,
+      r.economicsVersion,
+    );
+    if (r.hash !== fresh) codes.push(M5_FAIL.DIGEST_MISMATCH);
+    const id = identity(r.profileId, r.requestDigest);
+    if (!v1Digests.has(id)) {
+      codes.push(
+        expected.size > 0 ? M5_FAIL.IDENTITY_DRIFT : M5_FAIL.COUNT_MISMATCH,
+      );
+    }
+  }
+
+  if (detectCollision(host)) codes.push(M5_FAIL.REQUEST_HASH_COLLISION);
+
+  return { ok: codes.length === 0, codes: dedupe(codes) };
+}
+
+export function m5Switch(host: M5Host): M5ValidateResult {
+  if (host.activeVersion() !== REQUEST_HASH_LEGACY_VERSION) {
+    return { ok: false, codes: [M5_FAIL.NOT_ON_LEGACY] };
+  }
+  // Collision check runs before copy-completeness verify: a structural
+  // collision is a switch-blocker regardless of copy state.
+  if (detectCollision(host))
+    return { ok: false, codes: [M5_FAIL.REQUEST_HASH_COLLISION] };
+  const verify = m5Verify(host);
+  if (!verify.ok) return verify;
+  host.switchToV2();
+  return { ok: true, codes: [] };
+}
+
+export function migrateRequestHashV2(host: M5Host): M5ValidateResult {
+  m5Copy(host);
+  return m5Switch(host);
+}