pi-mega-compact 0.20.13 → 0.20.15

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

@@ -0,0 +1,80 @@
+/**
+ * vector-cortex/migrations/request-hash-v2.ts — M5 request-hash-v2 migration
+ * (COPY + VALIDATE + SWITCH).
+ *
+ * Delegate-shell: types + constants live in request-hash-v2-types.ts and the
+ * operational logic (copy/verify/switch/collision) lives in
+ * request-hash-v2-ops.ts. This file re-exports the public surface so callers
+ * import from a single module. Split to keep under the 300-line soft limit
+ * (soft-as-hard gate).
+ *
+ * M5 versions the canonical request hash: the predecessor hashed the outbound
+ * request under the v1 scheme; v2 folds in the provider profile's ECONOMICS
+ * version so a pricing/TTL/exclusion change cannot silently reuse a cache
+ * identity minted under different economics. Like M4/M6 it follows the
+ * copy/validate/switch contract:
+ *
+ *   - copy:     resumable per (profile, request) — an interrupted run resumes
+ *               without duplicate rows or active-pointer drift.
+ *   - validate: every v1 row has exactly one v2 row, every v2 digest re-hashes
+ *               from its own declared fields, the migration is IDENTITY-PRESERVING
+ *               (a v2 row carries the same `requestDigest` as its v1 source — v2
+ *               changes how a CACHE KEY is derived, never what the request IS), and
+ *               — the M5-specific invariant ADDED in VC7C — there are ZERO
+ *               collisions: no two distinct v1 rows may map to one v2 hash. A
+ *               collision (`M5_REQUEST_HASH_COLLISION`) means two different
+ *               conversations would share a cache key, the most dangerous outcome
+ *               in the subsystem, so it blocks the switch outright.
+ *   - switch:   ATOMICALLY flip the active pointer to v2 via `host.switchToV2()`.
+ *               VC7B deferred this; VC7C performs it — but ONLY after re-validating
+ *               against freshly-read host state at switch time.
+ *
+ * WHY THE COLLISION CHECK RUNS AT SWITCH TIME, NOT VALIDATE TIME. The brief's
+ * failure-injection contract is explicit: crash after M5 validation, inject a
+ * collision into host state, then resume — and the RESUMED run must detect
+ * `M5_REQUEST_HASH_COLLISION`. If the collision were detected only from the result
+ * of an earlier `m5Verify` call, the cached result would be replayed and the
+ * injected collision would be invisible. So `m5Switch` RE-READS the host (`v1Rows`,
+ * `existingV2`, `activeVersion`) and RE-RUNS the collision check against that live
+ * state. Validation is a precondition; the switch is the only place that proves the
+ * hazard is absent *right now*. This is the same resume-after-crash discipline as
+ * M4/M6: a migration that trusts a stale verification is a migration that loses
+ * data on restart.
+ *
+ * M6 INVALIDATION CONSUMPTION. A v2 request hash is only as trustworthy as the
+ * generation it was minted under. The switch consumes M6's structured invalidation
+ * keys via the REAL API (`invalidationKey` from `../topology/query.js`) rather than
+ * inventing one: when a v2 row's economics version maps to an invalidated router
+ * generation, that row cannot be promoted to active. We do not re-derive a
+ * generation here — topology is the authority on what generation is live — we only
+ * refuse to switch a row whose generation is dead. This keeps M5 from resurrecting
+ * cache identities tied to a generation the router has already invalidated.
+ *
+ * PREVENT-002/011/PI-004 honored.
+ */
+
+export {
+  REQUEST_HASH_V2_VERSION,
+  REQUEST_HASH_LEGACY_VERSION,
+  M5_FAIL,
+  M5_IDS,
+  M5_NAMED_IDS,
+} from "./request-hash-v2-types.js";
+export type {
+  M5MigrationCode,
+  RequestHashV1Row,
+  RequestHashV2Row,
+  M5Host,
+  M5ValidateResult,
+} from "./request-hash-v2-types.js";
+
+export {
+  deriveRequestHashV2,
+  deriveRequestHashRow,
+  detectCollision,
+  isGenerationInvalidated,
+  m5Copy,
+  m5Verify,
+  m5Switch,
+  migrateRequestHashV2,
+} from "./request-hash-v2-ops.js";

package/src/vector-cortex/provider/economics-ids.ts

@@ -0,0 +1,38 @@
+/**
+ * vector-cortex/provider/economics-ids.ts — VC7B conformance ID registrations.
+ *
+ * Extracted from economics.ts to keep that file under the 300-line soft limit
+ * (soft-as-hard gate). The ID ranges and named rows are pure data — splitting
+ * them out mirrors how vector-cortex-breakers.ts was extracted from
+ * vector-cortex.ts. economics.ts re-exports them so no consumer import path
+ * changes.
+ *
+ * Pi-agnostic, dependency-free (PREVENT-PI-004 / PREVENT-011).
+ */
+
+/**
+ * Registered VC7B cache-economics conformance ID range (CACHE-001..015). The
+ * acceptance aggregator reads these rows from the v2 manifest and asserts each
+ * returns its manifest `ok`/`code`.
+ */
+export const CACHE_IDS: readonly string[] = Array.from(
+  { length: 15 },
+  (_v, i) => `CACHE-${String(i + 1).padStart(3, "0")}`,
+);
+
+/**
+ * Registered VC7B provider-economics conformance rows (PRO-024..030), continuing
+ * VC7A's PRO-016..023. These pin the ECONOMICS half of a provider profile:
+ * pricing validity, the exclusion-proof rule, and TTL/min-prefix eligibility.
+ */
+export const ECONOMICS_PROVIDER_IDS: readonly string[] = Array.from(
+  { length: 7 },
+  (_v, i) => `PRO-${String(i + 24).padStart(3, "0")}`,
+);
+
+/** Named VC7B conformance assertions (the sprint's headline rows). */
+export const ECONOMICS_NAMED_IDS = [
+  "CACHE-COST-001",
+  "CACHE-EXCLUDE-002",
+  "CACHE-RANDOM-003",
+] as const;

package/src/vector-cortex/provider/economics.ts

@@ -0,0 +1,289 @@
+/**
+ * vector-cortex/provider/economics.ts — VC7B cache economics (ProviderProfileV1
+ * extension).
+ *
+ * VC7A proved a render can be FROZEN and reused. VC7B answers the question that
+ * immediately follows: is reusing it actually WORTH IT? Provider prompt caching
+ * is not free — a cache WRITE typically costs MORE than an uncached token, and a
+ * cache READ costs less. So a cache is profitable only when a written prefix is
+ * read back enough times, before its TTL expires, to repay the write premium.
+ * This file is that arithmetic and nothing else.
+ *
+ * THE NET-SAVINGS MODEL. For a prefix of `cachedTokens` tokens:
+ *
+ *   baseline (no cache) = cachedTokens * basePrice * (writes + hits)
+ *   actual (cached)     = cachedTokens * (writePrice * writes + readPrice * hits)
+ *   netSavings          = baseline - actual
+ *
+ * A NEGATIVE `netSavings` is a real, expected, and important outcome: it means
+ * the cache LOST money (a prefix written once and never re-read always does, by
+ * exactly the write premium). We report it rather than clamping it at zero,
+ * because a floor at zero would make every rollout look free and would hide the
+ * single failure mode this sprint exists to detect.
+ *
+ * EXACT ARITHMETIC, NO FLOATS IN THE MONEY PATH. Prices are integer
+ * MICRO-UNITS per token (1e-6 of the provider's currency unit), never floating
+ * point. `0.1 + 0.2 !== 0.3` is not an acceptable property for a cost ledger, and
+ * accumulating float error across millions of tokens produces aggregates that
+ * silently disagree with the provider's own bill. All money is integer; only the
+ * derived RATIO is a float, and it is finite-guarded.
+ *
+ * EVERY EXCLUSION NEEDS A FIXTURE (the sprint's headline safety rule). A provider
+ * profile may declare that some request field does not affect cache identity —
+ * but an UNPROVEN exclusion is how you get silent cache poisoning: the renderer
+ * folds a field the provider actually keys on, two different requests collapse to
+ * one cache entry, and one conversation is served another's prefix. So an
+ * exclusion without a `fixtureId` (or with a blank one) is REJECTED here —
+ * `ECON_EXCLUSION_UNPROVEN` — rather than trusted. There is no override.
+ *
+ * ESTIMATE VS MEASURED. Every result is labeled. Only telemetry from a
+ * RANDOMIZED live assignment may be called `measured` and fed into a causal
+ * interval; shadow or non-randomized numbers are `estimate` and are excluded
+ * from causal aggregates (see `experiments.ts`). Mixing the two would let a
+ * self-selected population masquerade as a controlled experiment.
+ *
+ * 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 `../cache/economics-emit.ts`.
+ */
+
+import type { ProviderProfileExclusion, ProviderProfileV1 } from "./types.js";
+
+/**
+ * Cache economics attached to a provider profile.
+ *
+ * Prices are integer MICRO-UNITS PER TOKEN (1e-6 currency units), so a provider
+ * charging $3.00 per million input tokens has `basePrice: 3`. Integers keep the
+ * money path exact; see the file header for why floats are refused.
+ */
+export interface ProviderEconomicsV1 {
+  readonly schema: "provider-economics-v1";
+  /** The `ProviderProfileV1.id` these economics belong to. */
+  readonly profileId: string;
+  /** Profile version — economics are versioned WITH the profile they price. */
+  readonly profileVersion: string;
+  /** Uncached price per token, integer micro-units. The savings baseline. */
+  readonly basePrice: number;
+  /** Cache-READ price per token, integer micro-units. Normally < basePrice. */
+  readonly readPrice: number;
+  /** Cache-WRITE price per token, integer micro-units. Normally > basePrice. */
+  readonly writePrice: number;
+  /** Cache entry lifetime in ms. A prefix older than this cannot be read back. */
+  readonly ttlMs: number;
+  /** Minimum cacheable prefix in tokens; a shorter prefix is never cached. */
+  readonly minPrefix: number;
+  /**
+   * Conformance fixture ID proving this profile's exclusion set is safe, or
+   * `null` when the profile declares NO exclusions (nothing to prove). A profile
+   * WITH exclusions and a null/blank id is rejected — see `validateEconomics`.
+   */
+  readonly exclusionFixtureId: string | null;
+}
+
+/** Observed (or shadow) cache traffic for one economics computation. */
+export interface CacheUsageV1 {
+  /** Tokens in the cached prefix. Must be a non-negative safe integer. */
+  readonly cachedTokens: number;
+  /** Number of cache WRITES (each pays the write premium). */
+  readonly writeCount: number;
+  /** Number of cache HITS (each pays the discounted read price). */
+  readonly hitCount: number;
+}
+
+/**
+ * Whether a figure may be used as causal evidence.
+ *
+ *   `measured` — from a RANDOMIZED live assignment; admissible in causal
+ *                intervals.
+ *   `estimate` — shadow, projected, or non-randomized; reportable but NEVER
+ *                admissible in a causal interval.
+ */
+export type EconomicsEvidence = "measured" | "estimate";
+
+/** VC7B economics failure codes. */
+export type EconomicsFailureCode =
+  /** A profile declares exclusions but names no proving fixture. */
+  | "ECON_EXCLUSION_UNPROVEN"
+  /** A price / TTL / prefix is negative, fractional, or not finite. */
+  | "ECON_PRICE_INVALID"
+  /** A usage count is negative, fractional, or not finite. */
+  | "ECON_USAGE_INVALID"
+  /** The computed result overflowed the exact-integer safe range. */
+  | "ECON_OVERFLOW";
+
+/** The computed economics of a cache decision. All money in micro-units. */
+export interface EconomicsResultV1 {
+  readonly profileId: string;
+  /** What the same traffic would have cost with no cache at all. */
+  readonly baselineCost: number;
+  /** What it actually cost: write premium on writes, discount on hits. */
+  readonly actualCost: number;
+  /** `baselineCost - actualCost`. NEGATIVE means the cache lost money. */
+  readonly netSavings: number;
+  /** Tokens billed at the discounted read price (the cache's token benefit). */
+  readonly tokenSavings: number;
+  /** `netSavings / baselineCost`, or 0 when the baseline is 0. Always finite. */
+  readonly savingsRatio: number;
+  /** Hits needed to break even on one write, or null when never profitable. */
+  readonly breakEvenHits: number | null;
+  /** Whether this figure may enter a causal interval. */
+  readonly evidence: EconomicsEvidence;
+}
+
+/** The verdict of an economics computation. */
+export type EconomicsResult =
+  | { readonly ok: true; readonly result: EconomicsResultV1 }
+  | { readonly ok: false; readonly codes: readonly EconomicsFailureCode[] };
+
+/** A non-negative safe integer — the only shape money and counts may take. */
+function isCount(n: number): boolean {
+  return Number.isSafeInteger(n) && n >= 0;
+}
+
+/**
+ * Validate a profile's economics, enforcing the exclusion-proof rule.
+ *
+ * An exclusion claims "this field cannot affect provider cache identity". That
+ * claim is only as good as the fixture that proves it, so a profile carrying
+ * exclusions MUST name a `exclusionFixtureId`, and every individual exclusion
+ * must carry its own `fixtureId` too (VC5B already models that field; VC7B makes
+ * a blank one fatal instead of decorative). Returns deduplicated codes in a
+ * deterministic order.
+ */
+export function validateEconomics(
+  econ: ProviderEconomicsV1,
+  exclusions: readonly ProviderProfileExclusion[],
+): readonly EconomicsFailureCode[] {
+  const codes = new Set<EconomicsFailureCode>();
+
+  for (const n of [econ.basePrice, econ.readPrice, econ.writePrice, econ.ttlMs, econ.minPrefix]) {
+    if (!isCount(n)) codes.add("ECON_PRICE_INVALID");
+  }
+
+  // The headline rule: exclusions without a proving fixture are never trusted.
+  if (exclusions.length > 0) {
+    const id = econ.exclusionFixtureId;
+    if (id === null || id.trim() === "") codes.add("ECON_EXCLUSION_UNPROVEN");
+    for (const ex of exclusions) {
+      if (ex.fixtureId.trim() === "") codes.add("ECON_EXCLUSION_UNPROVEN");
+    }
+  }
+
+  const order: EconomicsFailureCode[] = ["ECON_EXCLUSION_UNPROVEN", "ECON_PRICE_INVALID"];
+  return order.filter((c) => codes.has(c));
+}
+
+/**
+ * Validate a profile + its economics together. Convenience over
+ * `validateEconomics` for callers holding a whole `ProviderProfileV1`: the
+ * exclusion list is read from the profile itself, so the two can never disagree.
+ */
+export function validateProfileEconomics(
+  profile: ProviderProfileV1,
+  econ: ProviderEconomicsV1,
+): readonly EconomicsFailureCode[] {
+  return validateEconomics(econ, profile.excludedJsonPointers);
+}
+
+/**
+ * Hits required for ONE write to break even.
+ *
+ * One write costs `(writePrice - basePrice)` extra per token; each subsequent
+ * hit saves `(basePrice - readPrice)` per token. So break-even is the ceiling of
+ * premium/discount. Returns `null` when the cache can NEVER pay for itself
+ * (a read that costs at least as much as an uncached token) — reporting a huge
+ * number there would imply "just get more hits", which is false.
+ * Returns 0 when writing is already free or cheaper than not caching.
+ */
+export function breakEvenHits(econ: ProviderEconomicsV1): number | null {
+  const premium = econ.writePrice - econ.basePrice;
+  const discount = econ.basePrice - econ.readPrice;
+  if (premium <= 0) return 0;
+  if (discount <= 0) return null;
+  return Math.ceil(premium / discount);
+}
+
+/**
+ * Compute net cache savings for observed (or shadow) usage.
+ *
+ * Pure integer arithmetic in micro-units. The only float is `savingsRatio`, and
+ * it is zero-guarded so a zero baseline yields 0 rather than NaN/Infinity — the
+ * sprint invariant is that every reported aggregate is FINITE.
+ *
+ * `evidence` is supplied by the caller and simply carried through: this function
+ * cannot know whether its inputs came from a randomized arm, and guessing would
+ * be exactly the mislabeling the causal rules forbid.
+ */
+export function computeEconomics(
+  econ: ProviderEconomicsV1,
+  usage: CacheUsageV1,
+  evidence: EconomicsEvidence,
+): EconomicsResult {
+  const codes: EconomicsFailureCode[] = [];
+  for (const n of [econ.basePrice, econ.readPrice, econ.writePrice, econ.ttlMs, econ.minPrefix]) {
+    if (!isCount(n)) {
+      codes.push("ECON_PRICE_INVALID");
+      break;
+    }
+  }
+  for (const n of [usage.cachedTokens, usage.writeCount, usage.hitCount]) {
+    if (!isCount(n)) {
+      codes.push("ECON_USAGE_INVALID");
+      break;
+    }
+  }
+  if (codes.length > 0) return { ok: false, codes };
+
+  const { cachedTokens, writeCount, hitCount } = usage;
+  const baselineCost = cachedTokens * econ.basePrice * (writeCount + hitCount);
+  const actualCost = cachedTokens * (econ.writePrice * writeCount + econ.readPrice * hitCount);
+
+  // Exactness is the whole point of the integer model: if any product leaves the
+  // safe-integer range the result is silently wrong, so we fail instead.
+  if (!Number.isSafeInteger(baselineCost) || !Number.isSafeInteger(actualCost)) {
+    return { ok: false, codes: ["ECON_OVERFLOW"] };
+  }
+
+  const netSavings = baselineCost - actualCost;
+  // Tokens served at the discounted read price — the cache's token-level benefit,
+  // independent of price (a hit re-reads the whole prefix).
+  const tokenSavings = cachedTokens * hitCount;
+  const savingsRatio = baselineCost === 0 ? 0 : netSavings / baselineCost;
+
+  return {
+    ok: true,
+    result: {
+      profileId: econ.profileId,
+      baselineCost,
+      actualCost,
+      netSavings,
+      tokenSavings,
+      savingsRatio,
+      breakEvenHits: breakEvenHits(econ),
+      evidence,
+    },
+  };
+}
+
+/**
+ * Whether a prefix is eligible to be cached at all: it must meet the profile's
+ * minimum prefix, and it must still be within TTL. A prefix below `minPrefix` is
+ * not "a small win", it is not cacheable by the provider at all.
+ */
+export function isCacheEligible(
+  econ: ProviderEconomicsV1,
+  prefixTokens: number,
+  ageMs: number,
+): boolean {
+  if (!isCount(prefixTokens) || !isCount(ageMs)) return false;
+  return prefixTokens >= econ.minPrefix && ageMs < econ.ttlMs;
+}
+
+// Conformance ID ranges + named rows extracted to economics-ids.ts to keep this
+// file under the 300-line soft limit (soft-as-hard gate). Re-exported here so no
+// consumer import path changes.
+export {
+  CACHE_IDS,
+  ECONOMICS_PROVIDER_IDS,
+  ECONOMICS_NAMED_IDS,
+} from "./economics-ids.js";

package/src/vector-cortex/provider/experiments.ts

@@ -0,0 +1,248 @@
+/**
+ * vector-cortex/provider/experiments.ts — VC7B session-level cache experiments.
+ *
+ * To claim a cache strategy CAUSED a saving you need a randomized comparison,
+ * not a before/after. This file assigns each session to an experiment arm and
+ * guarantees the two properties that make the resulting telemetry admissible as
+ * causal evidence.
+ *
+ * 1. STABLE, JOURNAL-FREE ASSIGNMENT. The arm is a pure function of
+ *    `sha256(experimentId, sessionId)` — NOT a random draw recorded in a
+ *    journal. So the assignment survives anything: process restart, a lost or
+ *    corrupted journal, a different host, a replay months later. This is the
+ *    sprint's unique failure-injection case (lose the journal after the first
+ *    event, restart, and the same arm must come back), and a hash-derived arm
+ *    passes it by construction rather than by careful recovery code. A journal
+ *    can still be kept as an audit trail, but nothing DEPENDS on it.
+ *
+ *    The corollary matters just as much: every event in one session shares one
+ *    arm (CACHE-RANDOM-003). If a session could drift between arms mid-flight,
+ *    its rows would appear in both arms of the comparison and the contrast would
+ *    be measuring nothing.
+ *
+ * 2. RANDOMIZED ⇒ CAUSAL; EVERYTHING ELSE ⇒ ESTIMATE. Hashing a session id is
+ *    randomization only when the id itself is unpredictable and every session is
+ *    eligible. A FORCED arm (operator override), a SHADOW arm (computed but not
+ *    served), and a non-randomized rollout are all labeled `estimate` and are
+ *    excluded from causal intervals by `isCausallyAdmissible`. Shadow numbers are
+ *    genuinely useful — they are just not evidence of an effect.
+ *
+ * WHY 10_000 BUCKETS. Bucket granularity bounds how finely traffic can be split;
+ * 10k gives 0.01% resolution, matching VC5C's rollout bucketing so the two
+ * subsystems partition traffic on the same scale rather than on quietly
+ * different ones.
+ *
+ * PURE. No clock, no storage, no console, no network (PREVENT-PI-004 /
+ * PREVENT-011). `assignedAt` is an INJECTED timestamp, never `Date.now()` read
+ * here, so assignment is fully reproducible in tests and replays. Runs
+ * identically with `MEGACOMPACT_VC7B` on or off.
+ */
+
+import { createHash } from "node:crypto";
+
+/**
+ * Experiment arms.
+ *
+ *   A — control: the predecessor path, no VC7B crystal compiler.
+ *   B — treatment: provider-safe compiled crystal boundaries.
+ *   C — holdout: cache bypassed entirely, the uncached baseline that prices what
+ *       the cache is being compared AGAINST.
+ */
+export type ExperimentArm = "A" | "B" | "C";
+
+/** The registered arms, in canonical bucket order. */
+export const EXPERIMENT_ARMS: readonly ExperimentArm[] = ["A", "B", "C"] as const;
+
+/** Bucket space: 10k buckets = 0.01% resolution (matches VC5C rollout). */
+export const EXPERIMENT_BUCKETS = 10_000;
+
+/**
+ * How a session came to be in its arm. Only `randomized` is causal evidence.
+ *
+ *   `randomized` — derived from the stable hash over every eligible session.
+ *   `forced`     — an operator/test override; self-selected, never causal.
+ *   `shadow`     — computed for comparison but not served; never causal.
+ */
+export type AssignmentSource = "randomized" | "forced" | "shadow";
+
+/** A session's experiment assignment (VC7B contract type). */
+export interface CacheExperimentV1 {
+  readonly schema: "cache-experiment-v1";
+  /** Names the experiment; folded into the hash so arms differ per experiment. */
+  readonly experimentId: string;
+  /** The session this assignment belongs to. */
+  readonly sessionId: string;
+  /** The assigned arm. */
+  readonly arm: ExperimentArm;
+  /** The session's stable bucket in `[0, EXPERIMENT_BUCKETS)`. */
+  readonly bucket: number;
+  /** How the arm was chosen — gates causal admissibility. */
+  readonly source: AssignmentSource;
+  /** INJECTED assignment timestamp (epoch ms). Never read from a clock here. */
+  readonly assignedAt: number;
+}
+
+/** VC7B experiment failure codes. */
+export type ExperimentFailureCode =
+  /** A blank experiment id or session id — an unnamed experiment is unanalyzable. */
+  | "EXP_ID_INVALID"
+  /** An arm split that does not sum to the full bucket space. */
+  | "EXP_SPLIT_INVALID"
+  /** A forced arm that is not one of the registered arms. */
+  | "EXP_ARM_UNKNOWN";
+
+/** The verdict of an assignment. */
+export type ExperimentResult =
+  | { readonly ok: true; readonly assignment: CacheExperimentV1 }
+  | { readonly ok: false; readonly codes: readonly ExperimentFailureCode[] };
+
+/**
+ * Traffic split across arms, in buckets. Must sum to exactly
+ * `EXPERIMENT_BUCKETS`: a split that sums to less would leave sessions
+ * unassigned, and one that sums to more would make the last arm unreachable —
+ * both silently bias the comparison, so both are rejected.
+ */
+export interface ExperimentSplit {
+  readonly A: number;
+  readonly B: number;
+  readonly C: number;
+}
+
+/** Even three-way split (the default): 3334 / 3333 / 3333 = 10000. */
+export const EVEN_SPLIT: ExperimentSplit = { A: 3334, B: 3333, C: 3333 };
+
+/**
+ * Length-prefixed field framing, identical in spirit to the crystal key encoder:
+ * `<byteLength>:<value>` makes the concatenation injective, so experiment
+ * `"a"` + session `"b:c"` cannot collide with experiment `"a:b"` + session `"c"`.
+ * Without it, two different (experiment, session) pairs could share a bucket and
+ * a session could appear to switch arms when an experiment is renamed.
+ */
+function field(value: string): string {
+  return `${Buffer.byteLength(value, "utf8")}:${value}`;
+}
+
+/**
+ * The stable bucket for a session: the low 32 bits of
+ * `sha256(experimentId, sessionId)`, modulo the bucket space.
+ *
+ * Deterministic and storage-free — this is what makes a lost assignment journal
+ * a non-event. Reading 4 bytes (rather than the whole digest) keeps the value in
+ * exact integer range; SHA-256's avalanche means any 32 bits are equidistributed.
+ */
+export function experimentBucket(experimentId: string, sessionId: string): number {
+  const h = createHash("sha256")
+    .update(field(experimentId) + field(sessionId), "utf8")
+    .digest();
+  return h.readUInt32BE(0) % EXPERIMENT_BUCKETS;
+}
+
+/** Validate that a split covers the bucket space exactly once. */
+export function validateSplit(split: ExperimentSplit): boolean {
+  for (const n of [split.A, split.B, split.C]) {
+    if (!Number.isSafeInteger(n) || n < 0) return false;
+  }
+  return split.A + split.B + split.C === EXPERIMENT_BUCKETS;
+}
+
+/**
+ * Map a bucket to an arm under a split. Arms occupy contiguous bucket ranges in
+ * the fixed order A, B, C, so the mapping is stable: widening arm C's share can
+ * never reshuffle a session already sitting in arm A.
+ */
+export function armForBucket(bucket: number, split: ExperimentSplit): ExperimentArm {
+  if (bucket < split.A) return "A";
+  if (bucket < split.A + split.B) return "B";
+  return "C";
+}
+
+/**
+ * Assign a session to an experiment arm.
+ *
+ * The default path is `randomized`: bucket = stable hash, arm = bucket's range.
+ * Passing `forced` overrides the arm and downgrades the source (and therefore
+ * causal admissibility) — the bucket is still computed and reported so the
+ * override remains auditable against what the session WOULD have got.
+ *
+ * `assignedAt` is injected by the caller. Assignment is a pure function of its
+ * arguments, so the same session always yields the same arm no matter when, or
+ * how many times, it is asked.
+ */
+export function assignExperiment(input: {
+  readonly experimentId: string;
+  readonly sessionId: string;
+  readonly assignedAt: number;
+  readonly split?: ExperimentSplit;
+  readonly forced?: ExperimentArm;
+  readonly shadow?: boolean;
+}): ExperimentResult {
+  const codes: ExperimentFailureCode[] = [];
+  if (input.experimentId.trim() === "" || input.sessionId.trim() === "") {
+    codes.push("EXP_ID_INVALID");
+  }
+  const split = input.split ?? EVEN_SPLIT;
+  if (!validateSplit(split)) codes.push("EXP_SPLIT_INVALID");
+  if (input.forced !== undefined && !EXPERIMENT_ARMS.includes(input.forced)) {
+    codes.push("EXP_ARM_UNKNOWN");
+  }
+  if (codes.length > 0) return { ok: false, codes };
+
+  const bucket = experimentBucket(input.experimentId, input.sessionId);
+  const natural = armForBucket(bucket, split);
+  const arm = input.forced ?? natural;
+  // Precedence: a forced arm is self-selected, so it is never causal even when
+  // it happens to agree with the natural arm. Shadow is likewise non-causal.
+  const source: AssignmentSource =
+    input.forced !== undefined ? "forced" : input.shadow === true ? "shadow" : "randomized";
+
+  return {
+    ok: true,
+    assignment: {
+      schema: "cache-experiment-v1",
+      experimentId: input.experimentId,
+      sessionId: input.sessionId,
+      arm,
+      bucket,
+      source,
+      assignedAt: input.assignedAt,
+    },
+  };
+}
+
+/**
+ * Whether an assignment's telemetry may enter a causal interval.
+ *
+ * ONLY `randomized`. This single predicate is what keeps forced and shadow rows
+ * out of the causal aggregate; every consumer computing an interval must filter
+ * through it rather than re-deriving the rule.
+ */
+export function isCausallyAdmissible(a: CacheExperimentV1): boolean {
+  return a.source === "randomized";
+}
+
+/**
+ * Keep only causally admissible assignments. The complement is not discarded by
+ * the caller — it is reported as `estimate` — but it never reaches an interval.
+ */
+export function causalOnly(
+  assignments: readonly CacheExperimentV1[],
+): readonly CacheExperimentV1[] {
+  return assignments.filter(isCausallyAdmissible);
+}
+
+/**
+ * Whether every assignment for one session agrees on the arm (CACHE-RANDOM-003).
+ * A session that appears in two arms would contaminate both sides of the
+ * comparison, so this is asserted directly rather than assumed.
+ */
+export function sessionArmsConsistent(
+  assignments: readonly CacheExperimentV1[],
+): boolean {
+  const bySession = new Map<string, ExperimentArm>();
+  for (const a of assignments) {
+    const seen = bySession.get(a.sessionId);
+    if (seen !== undefined && seen !== a.arm) return false;
+    bySession.set(a.sessionId, a.arm);
+  }
+  return true;
+}