pi-mega-compact 0.20.13 → 0.20.15

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

@@ -0,0 +1,280 @@
+/**
+ * vector-cortex/cache/compiler.ts — VC7B provider-safe crystal boundary compiler.
+ *
+ * A provider caches a PREFIX of the request. So where you cut the prompt into
+ * cacheable segments determines whether anything is reusable at all: cut too
+ * finely and every segment falls under the provider's `minPrefix` and nothing is
+ * cacheable; cut in the wrong place and a segment that changes every turn sits
+ * in front of one that never changes, invalidating everything behind it. This
+ * file turns validated source ranges plus a profile's limits into boundaries
+ * that the provider can actually cache.
+ *
+ * THE ONE INVARIANT THAT OUTRANKS EVERYTHING: THE COMPILER NEVER CHANGES
+ * REQUEST IDENTITY. It selects where boundaries FALL; it never reorders, never
+ * merges across a session, never drops a range, never rewrites bytes. The
+ * concatenation of the compiled boundaries covers exactly the same ranges, in
+ * exactly the same canonical order, as the input — so the VC5B canonical request
+ * digest and the VC7A crystal key are byte-identical before and after
+ * compilation. `boundariesPreserveIdentity()` states this as an executable
+ * check, and the acceptance suite runs it on every compiled row. If compilation
+ * could alter identity it would be a cache-poisoning engine rather than an
+ * optimizer: two different conversations could compile to one cache key.
+ *
+ * WHY MERGE FORWARD, AND ONLY WITHIN A SESSION. Ranges below `minPrefix` are not
+ * independently cacheable, so the compiler merges each undersized range into the
+ * one that FOLLOWS it in canonical order — forward, so the merged segment keeps
+ * the earlier range's start and the prefix relationship is preserved. Merging is
+ * confined to a single session because ranges from different sessions cover
+ * disjoint byte streams; a cross-session segment would claim a contiguity that
+ * does not exist. A trailing undersized run with nothing to merge into is
+ * emitted as its own boundary marked `cacheable: false` — reported honestly as
+ * uncacheable rather than padded, dropped, or silently attached backwards.
+ *
+ * BOUNDED. `maxSegments` caps the output so a caller-shaped range list cannot be
+ * turned into an unbounded segmentation (`COMP_SEGMENT_LIMIT`).
+ *
+ * PURE. No clock, no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011). Runs identically with `MEGACOMPACT_VC7B` on or off — the flag
+ * gates only the reporter/dashboard seam in `./economics-emit.ts`.
+ */
+
+import { createHash } from "node:crypto";
+
+import { compareSpans, sortSpans, validateRanges } from "./crystal.js";
+import type { CrystalKeyV1, DagSpan } from "./types.js";
+
+/**
+ * One compiled, provider-safe cache boundary: a contiguous run of covered ranges
+ * within a SINGLE session that the provider may treat as one cacheable segment.
+ */
+export interface CrystalBoundaryV1 {
+  readonly schema: "crystal-boundary-v1";
+  /** The session these ranges belong to (a boundary never spans sessions). */
+  readonly sessionId: string;
+  /** The covered ranges in this segment, in canonical order. */
+  readonly ranges: readonly DagSpan[];
+  /** Total covered bytes in the segment. */
+  readonly byteCount: number;
+  /** Approximate token count used against `minPrefix` (see `tokensForBytes`). */
+  readonly tokenCount: number;
+  /**
+   * Whether the provider can actually cache this segment: it meets `minPrefix`.
+   * A `false` segment is still emitted and still rendered — it is simply priced
+   * as uncached rather than pretended to be a hit.
+   */
+  readonly cacheable: boolean;
+  /** `sha256:` digest over the segment's ranges — a segment-level content pin. */
+  readonly digest: string;
+}
+
+/** Profile-derived limits the compiler must respect. */
+export interface CompilerLimits {
+  /** Minimum cacheable prefix in tokens (`ProviderEconomicsV1.minPrefix`). */
+  readonly minPrefix: number;
+  /** Maximum number of compiled segments. Bounds the output. */
+  readonly maxSegments: number;
+  /** Bytes per token used for the token estimate. Must be >= 1. */
+  readonly bytesPerToken: number;
+}
+
+/** Conventional default limits (4 bytes/token is the usual English estimate). */
+export const DEFAULT_COMPILER_LIMITS: CompilerLimits = {
+  minPrefix: 1024,
+  maxSegments: 64,
+  bytesPerToken: 4,
+};
+
+/** VC7B compiler failure codes. */
+export type CompilerFailureCode =
+  /** The input ranges failed VC7A validation (empty/malformed/overlapping). */
+  | "COMP_RANGE_INVALID"
+  /** Compilation would exceed `maxSegments`. */
+  | "COMP_SEGMENT_LIMIT"
+  /** A limit is negative, fractional, or otherwise unusable. */
+  | "COMP_LIMIT_INVALID"
+  /** The compiled boundaries did not re-cover the input exactly (never expected). */
+  | "COMP_IDENTITY_DRIFT";
+
+/** The verdict of a compilation. */
+export type CompileResult =
+  | {
+      readonly ok: true;
+      readonly boundaries: readonly CrystalBoundaryV1[];
+      /** Segments the provider can actually cache (`cacheable: true`). */
+      readonly cacheableCount: number;
+      /** Covered tokens sitting in cacheable segments. */
+      readonly cacheableTokens: number;
+    }
+  | { readonly ok: false; readonly codes: readonly CompilerFailureCode[] };
+
+/** Covered bytes of one range. */
+function spanBytes(s: DagSpan): number {
+  return s.endByte - s.startByte;
+}
+
+/**
+ * Byte→token estimate. Deliberately a floor: under-estimating tokens can only
+ * make the compiler MORE conservative about calling a segment cacheable, which
+ * fails safe (a wrongly-cacheable segment would be priced as a hit it never got).
+ */
+export function tokensForBytes(bytes: number, bytesPerToken: number): number {
+  return Math.floor(bytes / bytesPerToken);
+}
+
+/** `sha256:` digest over a segment's ranges — length-prefixed, so injective. */
+function boundaryDigest(ranges: readonly DagSpan[]): string {
+  const h = createHash("sha256");
+  for (const s of ranges) {
+    const parts = [
+      s.sessionId,
+      s.startSeq.toString(),
+      s.endSeq.toString(),
+      String(s.startByte),
+      String(s.endByte),
+      s.digest,
+    ];
+    for (const p of parts) h.update(`${Buffer.byteLength(p, "utf8")}:${p}`, "utf8");
+  }
+  return `sha256:${h.digest("hex")}`;
+}
+
+/** Build one boundary from a contiguous same-session run of ranges. */
+function makeBoundary(
+  ranges: readonly DagSpan[],
+  limits: CompilerLimits,
+): CrystalBoundaryV1 {
+  const byteCount = ranges.reduce((n, s) => n + spanBytes(s), 0);
+  const tokenCount = tokensForBytes(byteCount, limits.bytesPerToken);
+  const first = ranges[0];
+  return {
+    schema: "crystal-boundary-v1",
+    sessionId: first === undefined ? "" : first.sessionId,
+    ranges,
+    byteCount,
+    tokenCount,
+    cacheable: tokenCount >= limits.minPrefix,
+    digest: boundaryDigest(ranges),
+  };
+}
+
+function validLimits(l: CompilerLimits): boolean {
+  return (
+    Number.isSafeInteger(l.minPrefix) &&
+    l.minPrefix >= 0 &&
+    Number.isSafeInteger(l.maxSegments) &&
+    l.maxSegments > 0 &&
+    Number.isSafeInteger(l.bytesPerToken) &&
+    l.bytesPerToken >= 1
+  );
+}
+
+/**
+ * Compile validated ranges into provider-safe cache boundaries.
+ *
+ * Ranges are first put in canonical order (the SAME `sortSpans` order the VC7A
+ * key encoder uses — sharing the comparator is what keeps the two subsystems
+ * from disagreeing about what "canonical" means). They are then grouped by
+ * session, and within each session an undersized run is merged FORWARD until it
+ * meets `minPrefix`.
+ *
+ * Identity is verified before returning: the flattened output must equal the
+ * canonical input exactly. That check should never fire — it is a guard against
+ * a future edit to the merge loop quietly reordering or dropping a range.
+ */
+export function compileCrystalBoundaries(
+  ranges: readonly DagSpan[],
+  limits: CompilerLimits = DEFAULT_COMPILER_LIMITS,
+): CompileResult {
+  if (!validLimits(limits)) return { ok: false, codes: ["COMP_LIMIT_INVALID"] };
+
+  // Reuse VC7A's validator verbatim: the compiler must never accept a range set
+  // the crystal key would reject, or the two would disagree about what is legal.
+  const rangeCodes = validateRanges(ranges);
+  if (rangeCodes.length > 0) return { ok: false, codes: ["COMP_RANGE_INVALID"] };
+
+  const sorted = sortSpans(ranges);
+  const boundaries: CrystalBoundaryV1[] = [];
+
+  let run: DagSpan[] = [];
+  const flushRun = (): void => {
+    if (run.length > 0) {
+      boundaries.push(makeBoundary(run, limits));
+      run = [];
+    }
+  };
+
+  for (const span of sorted) {
+    const head = run[0];
+    // A session change always closes the run: a boundary never spans sessions,
+    // because two sessions' byte streams are not contiguous with each other.
+    if (head !== undefined && head.sessionId !== span.sessionId) flushRun();
+    run.push(span);
+    const bytes = run.reduce((n, s) => n + spanBytes(s), 0);
+    // Close as soon as the run is independently cacheable; anything smaller keeps
+    // absorbing the next range (merge-forward).
+    if (tokensForBytes(bytes, limits.bytesPerToken) >= limits.minPrefix) flushRun();
+  }
+  // A trailing undersized run has nothing left to merge into: emit it honestly
+  // as a non-cacheable boundary rather than padding or dropping it.
+  flushRun();
+
+  if (boundaries.length > limits.maxSegments) {
+    return { ok: false, codes: ["COMP_SEGMENT_LIMIT"] };
+  }
+  if (!boundariesPreserveIdentity(sorted, boundaries)) {
+    return { ok: false, codes: ["COMP_IDENTITY_DRIFT"] };
+  }
+
+  let cacheableCount = 0;
+  let cacheableTokens = 0;
+  for (const b of boundaries) {
+    if (b.cacheable) {
+      cacheableCount += 1;
+      cacheableTokens += b.tokenCount;
+    }
+  }
+  return { ok: true, boundaries, cacheableCount, cacheableTokens };
+}
+
+/**
+ * The executable form of the sprint's headline invariant: flattening the
+ * compiled boundaries must reproduce the canonical input ranges EXACTLY — same
+ * ranges, same order, same pinned digests.
+ *
+ * Comparison is field-by-field on identity (session, seq bounds, byte bounds,
+ * digest), never by count or by digest alone: a compiler bug that swapped two
+ * equal-length ranges would keep the count and the byte total identical while
+ * changing what the request means.
+ */
+export function boundariesPreserveIdentity(
+  input: readonly DagSpan[],
+  boundaries: readonly CrystalBoundaryV1[],
+): boolean {
+  const flat: DagSpan[] = [];
+  for (const b of boundaries) flat.push(...b.ranges);
+  const canonical = sortSpans(input);
+  if (flat.length !== canonical.length) return false;
+  for (let i = 0; i < flat.length; i += 1) {
+    const a = flat[i];
+    const b = canonical[i];
+    if (a === undefined || b === undefined) return false;
+    if (compareSpans(a, b) !== 0) return false;
+    // compareSpans intentionally ignores the pinned digest (it orders by source
+    // position). Identity includes the covered bytes, so check it explicitly.
+    if (a.digest !== b.digest) return false;
+  }
+  return true;
+}
+
+/**
+ * Compile the ranges of an existing crystal key. Returns the boundaries plus the
+ * UNCHANGED key: compilation is an optimization of how the render is segmented,
+ * never a re-keying. Returning the same key object makes that explicit at the
+ * call site — a caller cannot accidentally pick up a "compiled key" that differs.
+ */
+export function compileForKey(
+  key: CrystalKeyV1,
+  limits: CompilerLimits = DEFAULT_COMPILER_LIMITS,
+): { readonly key: CrystalKeyV1; readonly compiled: CompileResult } {
+  return { key, compiled: compileCrystalBoundaries(key.sourceRanges, limits) };
+}

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

@@ -0,0 +1,116 @@
+/**
+ * vector-cortex/cache/economics-emit.ts — VC7B event reporter seam.
+ *
+ * Mirrors `./crystal-emit.ts`: a thin `safe()` wrapper around an optional
+ * injected `emit` (unit tests pass `undefined` and stay pure), and the two event
+ * names the sprint spec requires verbatim:
+ *   - `vector_cortex_cache_experiment_assigned` — a session entered an arm.
+ *   - `vector_cortex_cache_economics_estimated` — net savings were computed.
+ *
+ * FLAG SEMANTICS. `computeEconomics`, `compileCrystalBoundaries` and
+ * `assignExperiment` are PURE and run REGARDLESS of `MEGACOMPACT_VC7B`. The flag
+ * gates ONLY this reporting + dashboard seam: with the flag off a session still
+ * hashes to the SAME arm, the compiler still produces the SAME boundaries, and
+ * the same net savings are still computed — we just do not announce them under
+ * the VC7B event namespace, and the dashboard reports `enabled:false` + mode C.
+ * That is what makes flag-off byte-identical to VC7A: the arithmetic is never
+ * skipped, only the emission.
+ *
+ * PAYLOAD DISCIPLINE. These events carry the ARM, the BUCKET, integer money
+ * AGGREGATES, and the evidence label — never a session id, never covered ranges,
+ * never frozen bytes, never a request or covered digest. A session id here would
+ * re-identify a user's conversation in a log file, and the bucket already carries
+ * everything needed to audit the split (SECURITY_PRIVACY — the exact ledger is
+ * not diagnostic data). The `evidence` label travels WITH every economics event
+ * so a downstream aggregator can never mistake a shadow estimate for a measured,
+ * randomized result.
+ *
+ * No console, no storage, no network (PREVENT-PI-004 / PREVENT-011). Every line
+ * is a structured JSON event with `ts` + `event`.
+ */
+
+import { VC7B_ENABLED } from "../../config/vector-cortex.js";
+import type { EconomicsEvidence } from "../provider/economics.js";
+import type { AssignmentSource, ExperimentArm } from "../provider/experiments.js";
+
+/** The two structured events the VC7B reporter emits. */
+export type EconomicsEventName =
+  | "vector_cortex_cache_experiment_assigned"
+  | "vector_cortex_cache_economics_estimated";
+
+/** Optional emit fn injected by the runtime; tests pass `undefined`. */
+export type EconomicsEmit = (name: string, payload: unknown) => void;
+
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(emit: EconomicsEmit | undefined, fn: (emit: EconomicsEmit) => void): void {
+  if (emit === undefined) return;
+  try {
+    fn(emit);
+  } catch {
+    // Non-fatal: a reporting failure must never break the agent loop.
+  }
+}
+
+/** The event names VC7B emits, exported for the dashboard seam and tests. */
+export const ECONOMICS_EVENT_NAMES: readonly EconomicsEventName[] = [
+  "vector_cortex_cache_experiment_assigned",
+  "vector_cortex_cache_economics_estimated",
+] as const;
+
+/**
+ * Report a session's experiment assignment.
+ *
+ * Arm + bucket + source only. The bucket is sufficient to audit that the split
+ * is being honored; the SESSION ID is deliberately absent so the event log
+ * cannot be used to reconstruct who was in which arm.
+ */
+export function reportCacheExperimentAssigned(
+  emit: EconomicsEmit | undefined,
+  payload: {
+    readonly experimentId: string;
+    readonly arm: ExperimentArm;
+    readonly bucket: number;
+    readonly source: AssignmentSource;
+  },
+): void {
+  if (!VC7B_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_cache_experiment_assigned", {
+      ts: undefined,
+      event: "vector_cortex_cache_experiment_assigned",
+      experimentId: payload.experimentId,
+      arm: payload.arm,
+      bucket: payload.bucket,
+      source: payload.source,
+    }),
+  );
+}
+
+/**
+ * Report computed cache economics.
+ *
+ * Integer micro-unit aggregates plus the evidence label. `netSavings` may be
+ * NEGATIVE and is reported as such — a cache that lost money is the outcome this
+ * telemetry exists to surface, so it is never clamped on the way out.
+ */
+export function reportCacheEconomicsEstimated(
+  emit: EconomicsEmit | undefined,
+  payload: {
+    readonly profileId: string;
+    readonly netSavings: number;
+    readonly tokenSavings: number;
+    readonly evidence: EconomicsEvidence;
+  },
+): void {
+  if (!VC7B_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_cache_economics_estimated", {
+      ts: undefined,
+      event: "vector_cortex_cache_economics_estimated",
+      profileId: payload.profileId,
+      netSavings: payload.netSavings,
+      tokenSavings: payload.tokenSavings,
+      evidence: payload.evidence,
+    }),
+  );
+}

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

@@ -0,0 +1,195 @@
+/**
+ * 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>();
+  for (const v1 of host.v1Rows()) {
+    const row = deriveRequestHashRow(host, v1);
+    const prior = byHash.get(row.hash);
+    if (
+      prior !== undefined &&
+      prior !== identity(v1.profileId, v1.requestDigest)
+    ) {
+      return true;
+    }
+    byHash.set(row.hash, identity(v1.profileId, v1.requestDigest));
+  }
+  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);
+    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] };
+  }
+  const verify = m5Verify(host);
+  if (!verify.ok) return verify;
+  if (detectCollision(host))
+    return { ok: false, codes: [M5_FAIL.REQUEST_HASH_COLLISION] };
+  host.switchToV2();
+  return { ok: true, codes: [] };
+}
+
+export function migrateRequestHashV2(host: M5Host): M5ValidateResult {
+  m5Copy(host);
+  return m5Switch(host);
+}

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

@@ -0,0 +1,87 @@
+/**
+ * request-hash-v2-types.ts — M5 request-hash-v2 migration types.
+ *
+ * Extracted from request-hash-v2.ts to keep the parent file under the 300-line
+ * soft limit (soft-as-hard gate). Pure type + constant definitions; no logic.
+ * PREVENT-002/011/PI-004 honored.
+ */
+
+/** The active-version value the v2 pointer is switched to. */
+export const REQUEST_HASH_V2_VERSION = 2;
+/** The legacy (predecessor) active version. */
+export const REQUEST_HASH_LEGACY_VERSION = 1;
+
+/** M5 failure codes. */
+export const M5_FAIL = {
+  COPY_PARTIAL: "M5_COPY_PARTIAL",
+  COUNT_MISMATCH: "M5_COUNT_MISMATCH",
+  DIGEST_MISMATCH: "M5_DIGEST_MISMATCH",
+  IDENTITY_DRIFT: "M5_IDENTITY_DRIFT",
+  /** Two distinct v1 rows map to the same v2 hash — blocks the switch. (VC7C) */
+  REQUEST_HASH_COLLISION: "M5_REQUEST_HASH_COLLISION",
+  /** The active pointer is not on v1; switching would be a no-op or a regression. */
+  NOT_ON_LEGACY: "M5_NOT_ON_LEGACY",
+} as const;
+export type M5MigrationCode = (typeof M5_FAIL)[keyof typeof M5_FAIL];
+
+/**
+ * Registered M5 conformance IDs (M5-001..020). The acceptance test reads these
+ * rows from the v2 `migrations/` domain and asserts each returns its manifest
+ * bytes or exactly its listed failure code. Mirrors M6_IDS / M4_IDS.
+ */
+export const M5_IDS: readonly string[] = Array.from(
+  { length: 20 },
+  (_v, i) => `M5-${String(i + 1).padStart(3, "0")}`,
+);
+
+/** Named M5 rows surfaced by the conformance corpus (mirrors M6_NAMED_IDS). */
+export const M5_NAMED_IDS = ["M5-COLLIDE-002"] as const;
+
+/** A predecessor (v1) request-hash row. */
+export interface RequestHashV1Row {
+  readonly profileId: string;
+  /** BARE lowercase hex canonical request digest (VC5B convention). */
+  readonly requestDigest: string;
+  /** The v1 cache-identity hash derived from the request. */
+  readonly hash: string;
+}
+
+/**
+ * A v2 request-hash row. Identity is `(profileId, requestDigest)` — unchanged
+ * from v1, which is the point: only `hash` is re-derived, now folding in the
+ * economics version.
+ */
+export interface RequestHashV2Row {
+  readonly profileId: string;
+  readonly requestDigest: string;
+  /** Economics version folded into the v2 hash (absent in v1). */
+  readonly economicsVersion: string;
+  /** The v2 cache-identity hash. */
+  readonly hash: string;
+}
+
+/** The host the migration reads from / writes to (capability-shaped). */
+export interface M5Host {
+  /** Every predecessor row being migrated. */
+  readonly v1Rows: () => readonly RequestHashV1Row[];
+  /** The economics version to fold in, per profile. */
+  readonly economicsVersionOf: (profileId: string) => string;
+  /** The session a profile belongs to, for M6 generation invalidation lookup. */
+  readonly sessionOf: (profileId: string) => string;
+  /** The currently live M6 generation for a session (for invalidation checks). */
+  readonly liveGenerationOf: (session: string) => bigint;
+  /** Persisted v2 rows already written (for resume). */
+  readonly existingV2: () => readonly RequestHashV2Row[];
+  /** Idempotent write of v2 rows (never mutates v1 rows). */
+  readonly putV2: (rows: readonly RequestHashV2Row[]) => void;
+  /** The currently ACTIVE version (1 = legacy; only v1 → v2 switching). */
+  readonly activeVersion: () => number;
+  /** Atomically flip the active pointer to v2. Mirrors M6Host.switchToV2. */
+  readonly switchToV2: () => void;
+}
+
+/** An M5 validation result. */
+export interface M5ValidateResult {
+  readonly ok: boolean;
+  readonly codes: readonly M5MigrationCode[];
+}