@crewhaus/canary-controller 0.4.0 → 0.5.0

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+import { CrewhausError } from "@crewhaus/errors";
+/**
+ * Canary/experiment configuration error. Lives in its own module so both the
+ * controller (`index.ts`) and the E50 experiment surface (`experiment.ts`)
+ * can throw the SAME class without importing each other — the public export
+ * remains `@crewhaus/canary-controller`'s `CanaryError`, unchanged.
+ */
+export declare class CanaryError extends CrewhausError {
+    readonly name = "CanaryError";
+    constructor(message: string, cause?: unknown);
+}

package/dist/errors.js

@@ -0,0 +1,13 @@
+import { CrewhausError } from "@crewhaus/errors";
+/**
+ * Canary/experiment configuration error. Lives in its own module so both the
+ * controller (`index.ts`) and the E50 experiment surface (`experiment.ts`)
+ * can throw the SAME class without importing each other — the public export
+ * remains `@crewhaus/canary-controller`'s `CanaryError`, unchanged.
+ */
+export class CanaryError extends CrewhausError {
+    name = "CanaryError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}

package/dist/experiment.d.ts

@@ -0,0 +1,159 @@
+/** Default location of the experiment ledgers, relative to cwd. */
+export declare const DEFAULT_EXPERIMENTS_DIR: string;
+/** Suffix of an experiment's append-only outcome ledger. */
+export declare const EXPERIMENT_LEDGER_SUFFIX = ".jsonl";
+/** Suffix of an experiment's variant-assignment manifest. */
+export declare const EXPERIMENT_ASSIGNMENT_SUFFIX = ".assignment.json";
+export type ExperimentVariant = {
+    /** The spec-registry version this variant serves. */
+    readonly version: string;
+    /** Integer 1..100 — percent of the request-key space this variant owns. */
+    readonly weight: number;
+};
+export type ExperimentConfig = {
+    readonly name: string;
+    /** Two or more variants whose weights are positive integers summing to 100. */
+    readonly variants: ReadonlyArray<ExperimentVariant>;
+    /**
+     * Optional stable salt mixed into the hash before bucketing (a tenant id,
+     * or a rotation token when an operator deliberately wants a fresh split).
+     * Absent ⇒ the empty salt, matching `CanaryController.route()` without a
+     * tenant.
+     */
+    readonly salt?: string;
+};
+export type ExperimentSelection = {
+    readonly version: string;
+    /** Hash bucket value, 0-99 — the same space `route()` buckets into. */
+    readonly bucket: number;
+    /** 0-based index of the selected variant in `config.variants`. */
+    readonly index: number;
+};
+/**
+ * The hash bucket a request key lands in: `sha256(salt|requestKey)`, first
+ * 4 bytes as a uint32, mod 100. Shared with `CanaryController.route()` so
+ * the two-version canary and the N-variant experiment can never disagree
+ * about which side of the split a given key is on.
+ */
+export declare function requestBucket(salt: string | undefined, requestKey: string): number;
+/**
+ * Validate an {@link ExperimentConfig}. Weights are integers because the
+ * bucket space is exactly 100 wide: fractional weights would silently round,
+ * and a rounded split is not the split the operator declared.
+ */
+export declare function validateExperimentConfig(config: ExperimentConfig): void;
+/**
+ * Deterministically select the variant serving `requestKey`. Pure: the same
+ * (config, key) pair always yields the same version, in any process, with no
+ * shared state — which is what makes the assignment sticky for a user across
+ * requests and reproducible for an operator debugging one.
+ */
+export declare function selectExperimentVariant(config: ExperimentConfig, requestKey: string): ExperimentSelection;
+export type ExperimentAssignment = ExperimentConfig & {
+    /** ISO timestamp of the last write. */
+    readonly updatedAt: string;
+    /** Optional environment the variants are pinned for (informational). */
+    readonly env?: string;
+    /**
+     * Free-text note recording HOW the assignment is expected to be consumed.
+     * Written by `deploy canary --traffic-split` so a file found on disk months
+     * later still states its own boundary.
+     */
+    readonly note?: string;
+};
+/** Filesystem-safe form of an experiment name (path traversal floor). */
+export declare function experimentFileName(name: string): string;
+export declare function writeExperimentAssignment(assignment: ExperimentAssignment, dir?: string): string;
+/**
+ * Retire an experiment's variant assignment. Returns true when a file was
+ * actually removed.
+ *
+ * A split is a TEMPORARY state: once the ramp concludes — promotion (100%
+ * candidate) or rollback (100% baseline) — the env pin is single-version and
+ * any surviving `[{v1,50},{v2,50}]` on disk would keep a compliant serving
+ * integration sending half its keys to a version nobody is running. There is
+ * no representable "100% one version" assignment ({@link
+ * validateExperimentConfig} requires ≥2 variants summing to 100, deliberately
+ * — a one-variant split is not a split), so a concluded experiment REMOVES
+ * the file and lets the env pin do the talking. `crewhaus experiment assign`
+ * then fails loudly instead of routing on a stale split.
+ */
+export declare function removeExperimentAssignment(name: string, dir?: string): boolean;
+export declare function readExperimentAssignment(name: string, dir?: string): ExperimentAssignment | undefined;
+export type ExperimentOutcomeRecord = {
+    /** ISO timestamp of the observation. */
+    readonly ts: string;
+    readonly experiment: string;
+    /** The variant version this outcome is attributed to. */
+    readonly version: string;
+    readonly outcome: "success" | "failure";
+    /** The stable request key that selected the version, when known. */
+    readonly requestKey?: string;
+    /** A normalized 0..1 quality score (eval/judge score), when known. */
+    readonly score?: number;
+    /** A human rating on its own scale (1-5, thumbs as 0/1, …), when known. */
+    readonly rating?: number;
+    /** Where the observation came from — `eval`, `serving`, `cli`, … */
+    readonly source?: string;
+};
+export declare function appendExperimentOutcomes(records: ReadonlyArray<ExperimentOutcomeRecord>, dir?: string): number;
+export declare function appendExperimentOutcome(record: ExperimentOutcomeRecord, dir?: string): void;
+/**
+ * Read an experiment's ledger. Torn/partial lines are SKIPPED rather than
+ * throwing: a crashed writer must degrade the tally by one observation, not
+ * make the whole experiment unreadable.
+ */
+export declare function readExperimentOutcomes(name: string, dir?: string): ReadonlyArray<ExperimentOutcomeRecord>;
+/** Every experiment name with a ledger under `dir`, sorted. */
+export declare function listExperiments(dir?: string): ReadonlyArray<string>;
+export type VariantTally = {
+    readonly version: string;
+    /** Observations recorded for this version. */
+    readonly n: number;
+    readonly successes: number;
+    readonly failures: number;
+    /** successes / n; 0 when n is 0. */
+    readonly successRate: number;
+    /** Mean of the recorded 0..1 scores. Absent when none carried a score. */
+    readonly meanScore?: number;
+    /** How many observations carried a score. */
+    readonly scoredN: number;
+    /** Mean of the recorded human ratings. Absent when none carried a rating. */
+    readonly meanRating?: number;
+    /** How many observations carried a rating. */
+    readonly ratedN: number;
+    /**
+     * Observation count per `source` (`eval` / `serving` / `cli` / …; records
+     * without a source fold into `"unknown"`). A reader must be able to tell an
+     * n built from offline eval re-runs from one built from live serving
+     * outcomes — they are not the same evidence.
+     */
+    readonly sources: Readonly<Record<string, number>>;
+};
+/**
+ * Collapse REPEATED MEASUREMENTS of the same unit so a tally cannot mistake
+ * them for independent observations.
+ *
+ * The motivating case is `deploy canary --traffic-split`: an eval observation
+ * is keyed by DATASET SAMPLE, and a ramp (or a re-invoked ramp under the same
+ * experiment name) grades the same fixed sample against the same version more
+ * than once. Four ramp steps over an 8-sample dataset would otherwise report
+ * n=32 per version and shrink a Wilson half-width ~2×, naming a "winner" on
+ * evidence that is inconclusive at the real sample size.
+ *
+ * Scope is deliberately narrow: only records with `source: "eval"` AND a
+ * `requestKey` collapse, last-write-wins per (version, requestKey). Serving
+ * records pass through untouched — there a request key is commonly a STICKY
+ * user/session id, so repeats are genuinely separate requests and collapsing
+ * them would destroy real data.
+ */
+export declare function dedupeExperimentOutcomes(records: ReadonlyArray<ExperimentOutcomeRecord>): {
+    readonly records: ReadonlyArray<ExperimentOutcomeRecord>;
+    /** How many records were dropped as repeat measurements. */
+    readonly collapsed: number;
+};
+/**
+ * Fold outcome records per version, in first-appearance order (so the first
+ * version written — the control/baseline in a canary — leads the table).
+ */
+export declare function tallyExperimentOutcomes(records: ReadonlyArray<ExperimentOutcomeRecord>): ReadonlyArray<VariantTally>;

package/dist/experiment.js

@@ -0,0 +1,359 @@
+/**
+ * E50 — N-variant online experiments: deterministic per-request version
+ * selection plus per-version outcome accounting.
+ *
+ * HONEST BOUNDARY (read this before claiming "traffic splitting"). This
+ * module ships the two halves of an A/B experiment that CrewHaus can
+ * actually reach today:
+ *
+ *   1. SELECTION — {@link selectExperimentVariant} maps a stable request key
+ *      to exactly one variant version, deterministically (sha256 of
+ *      `salt|requestKey`, mod 100, walked over the declared weights). Same
+ *      key ⇒ same version, forever, in every process, with no shared state.
+ *      This is the same hash `CanaryController.route()` uses, generalized
+ *      from two versions to N.
+ *   2. ACCOUNTING — {@link appendExperimentOutcome} records one outcome per
+ *      (experiment, version) observation into an append-only JSONL, and
+ *      {@link tallyExperimentOutcomes} folds it per version.
+ *
+ * What this module DOES NOT do: it does not intercept live requests. Nothing
+ * in CrewHaus's serving surfaces (gateway-server's `RunHandler`, the managed
+ * daemon, the channel bots) consults an assignment today — a genuine
+ * request-level split needs a consumer at each shape's serving boundary, and
+ * `target: cli` has no live request stream at all. So an operator gets the
+ * decision function and the ledger; wiring them into a serving boundary is
+ * an explicit integration, not something a flag silently turns on. Every
+ * user-facing string in this feature says exactly that.
+ *
+ * Storage is an append-only JSONL per experiment under
+ * `.crewhaus/experiments/`, mirroring the alert-watchdog's session-metrics
+ * history: readers tolerate torn/partial lines (a crashed writer must not
+ * make the ledger unreadable), and validation is hand-rolled rather than zod
+ * so this package stays a dependency-light leaf.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { CanaryError } from "./errors";
+/** Default location of the experiment ledgers, relative to cwd. */
+export const DEFAULT_EXPERIMENTS_DIR = join(".crewhaus", "experiments");
+/** Suffix of an experiment's append-only outcome ledger. */
+export const EXPERIMENT_LEDGER_SUFFIX = ".jsonl";
+/** Suffix of an experiment's variant-assignment manifest. */
+export const EXPERIMENT_ASSIGNMENT_SUFFIX = ".assignment.json";
+/**
+ * The hash bucket a request key lands in: `sha256(salt|requestKey)`, first
+ * 4 bytes as a uint32, mod 100. Shared with `CanaryController.route()` so
+ * the two-version canary and the N-variant experiment can never disagree
+ * about which side of the split a given key is on.
+ */
+export function requestBucket(salt, requestKey) {
+    const seed = `${salt ?? ""}|${requestKey}`;
+    const hash = createHash("sha256").update(seed).digest();
+    const v = ((hash[0] ?? 0) << 24) | ((hash[1] ?? 0) << 16) | ((hash[2] ?? 0) << 8) | (hash[3] ?? 0);
+    return Math.abs(v) % 100;
+}
+/**
+ * Validate an {@link ExperimentConfig}. Weights are integers because the
+ * bucket space is exactly 100 wide: fractional weights would silently round,
+ * and a rounded split is not the split the operator declared.
+ */
+export function validateExperimentConfig(config) {
+    if (config.name.trim() === "") {
+        throw new CanaryError("experiment name must be a non-empty string");
+    }
+    if (config.variants.length < 2) {
+        throw new CanaryError(`experiment "${config.name}" needs at least 2 variants; got ${config.variants.length}`);
+    }
+    const seen = new Set();
+    let total = 0;
+    for (const v of config.variants) {
+        if (v.version.trim() === "") {
+            throw new CanaryError(`experiment "${config.name}" has a variant with an empty version`);
+        }
+        if (seen.has(v.version)) {
+            throw new CanaryError(`experiment "${config.name}" lists version "${v.version}" more than once`);
+        }
+        seen.add(v.version);
+        if (!Number.isInteger(v.weight) || v.weight < 1 || v.weight > 100) {
+            throw new CanaryError(`experiment "${config.name}" variant "${v.version}" weight must be an integer in 1..100; got ${v.weight}`);
+        }
+        total += v.weight;
+    }
+    if (total !== 100) {
+        throw new CanaryError(`experiment "${config.name}" weights must sum to exactly 100; got ${total}`);
+    }
+}
+/**
+ * Deterministically select the variant serving `requestKey`. Pure: the same
+ * (config, key) pair always yields the same version, in any process, with no
+ * shared state — which is what makes the assignment sticky for a user across
+ * requests and reproducible for an operator debugging one.
+ */
+export function selectExperimentVariant(config, requestKey) {
+    validateExperimentConfig(config);
+    const bucket = requestBucket(config.salt, requestKey);
+    let cursor = 0;
+    for (let i = 0; i < config.variants.length; i += 1) {
+        const variant = config.variants[i];
+        if (variant === undefined)
+            continue;
+        cursor += variant.weight;
+        if (bucket < cursor) {
+            return { version: variant.version, bucket, index: i };
+        }
+    }
+    // Unreachable while the weights sum to 100 (validated above); the last
+    // variant is the honest fallback rather than a throw on a hot path.
+    const last = config.variants[config.variants.length - 1];
+    return { version: last.version, bucket, index: config.variants.length - 1 };
+}
+/** Filesystem-safe form of an experiment name (path traversal floor). */
+export function experimentFileName(name) {
+    const safe = name.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "_");
+    // A name that sanitizes to punctuation only ("///", "..") would collide
+    // with every other such name and read as a traversal attempt — refuse it
+    // rather than silently writing to `___.jsonl`.
+    if (!/[A-Za-z0-9]/.test(safe)) {
+        throw new CanaryError(`experiment name "${name}" has no filesystem-safe characters`);
+    }
+    return safe;
+}
+export function writeExperimentAssignment(assignment, dir = DEFAULT_EXPERIMENTS_DIR) {
+    validateExperimentConfig(assignment);
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${experimentFileName(assignment.name)}${EXPERIMENT_ASSIGNMENT_SUFFIX}`);
+    // Small single-writer manifest — a plain write is fine here; the ledger
+    // beside it is the append-only surface that must survive a torn write.
+    writeFileSync(path, `${JSON.stringify(assignment, null, 2)}\n`, "utf-8");
+    return path;
+}
+/**
+ * Retire an experiment's variant assignment. Returns true when a file was
+ * actually removed.
+ *
+ * A split is a TEMPORARY state: once the ramp concludes — promotion (100%
+ * candidate) or rollback (100% baseline) — the env pin is single-version and
+ * any surviving `[{v1,50},{v2,50}]` on disk would keep a compliant serving
+ * integration sending half its keys to a version nobody is running. There is
+ * no representable "100% one version" assignment ({@link
+ * validateExperimentConfig} requires ≥2 variants summing to 100, deliberately
+ * — a one-variant split is not a split), so a concluded experiment REMOVES
+ * the file and lets the env pin do the talking. `crewhaus experiment assign`
+ * then fails loudly instead of routing on a stale split.
+ */
+export function removeExperimentAssignment(name, dir = DEFAULT_EXPERIMENTS_DIR) {
+    const path = join(dir, `${experimentFileName(name)}${EXPERIMENT_ASSIGNMENT_SUFFIX}`);
+    if (!existsSync(path))
+        return false;
+    rmSync(path, { force: true });
+    return true;
+}
+export function readExperimentAssignment(name, dir = DEFAULT_EXPERIMENTS_DIR) {
+    const path = join(dir, `${experimentFileName(name)}${EXPERIMENT_ASSIGNMENT_SUFFIX}`);
+    if (!existsSync(path))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const rec = parsed;
+    const variants = rec["variants"];
+    if (typeof rec["name"] !== "string" || !Array.isArray(variants))
+        return undefined;
+    const cleaned = [];
+    for (const v of variants) {
+        if (typeof v !== "object" || v === null)
+            return undefined;
+        const entry = v;
+        if (typeof entry["version"] !== "string" || typeof entry["weight"] !== "number") {
+            return undefined;
+        }
+        cleaned.push({ version: entry["version"], weight: entry["weight"] });
+    }
+    return {
+        name: rec["name"],
+        variants: cleaned,
+        updatedAt: typeof rec["updatedAt"] === "string" ? rec["updatedAt"] : "",
+        ...(typeof rec["salt"] === "string" ? { salt: rec["salt"] } : {}),
+        ...(typeof rec["env"] === "string" ? { env: rec["env"] } : {}),
+        ...(typeof rec["note"] === "string" ? { note: rec["note"] } : {}),
+    };
+}
+function ledgerPath(name, dir) {
+    return join(dir, `${experimentFileName(name)}${EXPERIMENT_LEDGER_SUFFIX}`);
+}
+export function appendExperimentOutcomes(records, dir = DEFAULT_EXPERIMENTS_DIR) {
+    if (records.length === 0)
+        return 0;
+    mkdirSync(dir, { recursive: true });
+    // Group by experiment so a mixed batch still lands one append per file.
+    const byExperiment = new Map();
+    for (const rec of records) {
+        const lines = byExperiment.get(rec.experiment) ?? [];
+        lines.push(JSON.stringify(rec));
+        byExperiment.set(rec.experiment, lines);
+    }
+    for (const [name, lines] of byExperiment) {
+        appendFileSync(ledgerPath(name, dir), `${lines.join("\n")}\n`, "utf-8");
+    }
+    return records.length;
+}
+export function appendExperimentOutcome(record, dir = DEFAULT_EXPERIMENTS_DIR) {
+    appendExperimentOutcomes([record], dir);
+}
+/**
+ * Read an experiment's ledger. Torn/partial lines are SKIPPED rather than
+ * throwing: a crashed writer must degrade the tally by one observation, not
+ * make the whole experiment unreadable.
+ */
+export function readExperimentOutcomes(name, dir = DEFAULT_EXPERIMENTS_DIR) {
+    const path = ledgerPath(name, dir);
+    if (!existsSync(path))
+        return [];
+    let text;
+    try {
+        text = readFileSync(path, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof parsed !== "object" || parsed === null)
+            continue;
+        const rec = parsed;
+        const version = rec["version"];
+        const outcome = rec["outcome"];
+        if (typeof version !== "string" || (outcome !== "success" && outcome !== "failure"))
+            continue;
+        out.push({
+            ts: typeof rec["ts"] === "string" ? rec["ts"] : "",
+            experiment: typeof rec["experiment"] === "string" ? rec["experiment"] : name,
+            version,
+            outcome,
+            ...(typeof rec["requestKey"] === "string" ? { requestKey: rec["requestKey"] } : {}),
+            ...(typeof rec["score"] === "number" && Number.isFinite(rec["score"])
+                ? { score: rec["score"] }
+                : {}),
+            ...(typeof rec["rating"] === "number" && Number.isFinite(rec["rating"])
+                ? { rating: rec["rating"] }
+                : {}),
+            ...(typeof rec["source"] === "string" ? { source: rec["source"] } : {}),
+        });
+    }
+    return out;
+}
+/** Every experiment name with a ledger under `dir`, sorted. */
+export function listExperiments(dir = DEFAULT_EXPERIMENTS_DIR) {
+    if (!existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((f) => f.endsWith(EXPERIMENT_LEDGER_SUFFIX))
+        .map((f) => f.slice(0, -EXPERIMENT_LEDGER_SUFFIX.length))
+        .sort();
+}
+/**
+ * Collapse REPEATED MEASUREMENTS of the same unit so a tally cannot mistake
+ * them for independent observations.
+ *
+ * The motivating case is `deploy canary --traffic-split`: an eval observation
+ * is keyed by DATASET SAMPLE, and a ramp (or a re-invoked ramp under the same
+ * experiment name) grades the same fixed sample against the same version more
+ * than once. Four ramp steps over an 8-sample dataset would otherwise report
+ * n=32 per version and shrink a Wilson half-width ~2×, naming a "winner" on
+ * evidence that is inconclusive at the real sample size.
+ *
+ * Scope is deliberately narrow: only records with `source: "eval"` AND a
+ * `requestKey` collapse, last-write-wins per (version, requestKey). Serving
+ * records pass through untouched — there a request key is commonly a STICKY
+ * user/session id, so repeats are genuinely separate requests and collapsing
+ * them would destroy real data.
+ */
+export function dedupeExperimentOutcomes(records) {
+    const lastIndex = new Map();
+    for (let i = 0; i < records.length; i += 1) {
+        const rec = records[i];
+        if (rec.source !== "eval" || rec.requestKey === undefined)
+            continue;
+        lastIndex.set(`${rec.version}${rec.requestKey}`, i);
+    }
+    const kept = [];
+    let collapsed = 0;
+    for (let i = 0; i < records.length; i += 1) {
+        const rec = records[i];
+        if (rec.source === "eval" && rec.requestKey !== undefined) {
+            if (lastIndex.get(`${rec.version}${rec.requestKey}`) !== i) {
+                collapsed += 1;
+                continue;
+            }
+        }
+        kept.push(rec);
+    }
+    return { records: kept, collapsed };
+}
+/**
+ * Fold outcome records per version, in first-appearance order (so the first
+ * version written — the control/baseline in a canary — leads the table).
+ */
+export function tallyExperimentOutcomes(records) {
+    const order = [];
+    const acc = new Map();
+    for (const rec of records) {
+        let entry = acc.get(rec.version);
+        if (entry === undefined) {
+            entry = { n: 0, successes: 0, scoreSum: 0, scoredN: 0, ratingSum: 0, ratedN: 0, sources: {} };
+            acc.set(rec.version, entry);
+            order.push(rec.version);
+        }
+        entry.n += 1;
+        const source = rec.source ?? "unknown";
+        entry.sources[source] = (entry.sources[source] ?? 0) + 1;
+        if (rec.outcome === "success")
+            entry.successes += 1;
+        if (rec.score !== undefined) {
+            entry.scoreSum += rec.score;
+            entry.scoredN += 1;
+        }
+        if (rec.rating !== undefined) {
+            entry.ratingSum += rec.rating;
+            entry.ratedN += 1;
+        }
+    }
+    return order.map((version) => {
+        const e = acc.get(version);
+        return {
+            version,
+            n: e.n,
+            successes: e.successes,
+            failures: e.n - e.successes,
+            successRate: e.n > 0 ? e.successes / e.n : 0,
+            scoredN: e.scoredN,
+            ratedN: e.ratedN,
+            sources: e.sources,
+            ...(e.scoredN > 0 ? { meanScore: e.scoreSum / e.scoredN } : {}),
+            ...(e.ratedN > 0 ? { meanRating: e.ratingSum / e.ratedN } : {}),
+        };
+    });
+}

package/dist/index.d.ts

@@ -1,11 +1,37 @@
+/**
+ * Section 28 — `canary-controller`. Shifts a configurable percentage of
+ * incoming requests to a new version of a spec. Hash routing on
+ * `(tenantId, requestId-hash mod 100 < trafficPercent)` so a given user
+ * stays on the same side of the canary across requests.
+ *
+ * After `evalIntervalMs` elapses, runs an eval-spec against both versions
+ * in parallel and gates promotion on `regression-runner` (Section 29 —
+ * `gate(baseline, candidate)` over two `EvalRunSummary` results).
+ *
+ * The real gate is wired by the caller (item 29 — `crewhaus deploy canary`):
+ * canary-controller stays dependency-inverted (it does NOT import
+ * `regression-runner`/`eval-runner`, keeping this a leaf package). Callers
+ * build a `RegressionGate` with {@link makeRegressionGate}, injecting the
+ * per-step "eval both versions, then compare" closure. {@link PASSING_GATE}
+ * is retained ONLY as an explicit always-pass stub for tests and manual
+ * dry-runs — it is no longer the wired production default.
+ *
+ * Without an eval gate (manual mode), the controller waits for an
+ * explicit `crewhaus deploy promote` call.
+ *
+ * E50 — the N-variant generalization (deterministic per-request version
+ * selection + per-version outcome accounting) lives in `./experiment`, which
+ * shares this module's hash so a two-version canary and an N-variant
+ * experiment can never disagree about which side of the split a key is on.
+ * Read that module's HONEST BOUNDARY note before describing any of this as
+ * live traffic splitting: nothing here intercepts a request.
+ */
 import type { AuditLog } from "@crewhaus/audit-log";
 import type { DeploymentController } from "@crewhaus/deployment-controller";
-import { CrewhausError } from "@crewhaus/errors";
 import type { RegistryAdapter } from "@crewhaus/spec-registry";
-export declare class CanaryError extends CrewhausError {
-    readonly name = "CanaryError";
-    constructor(message: string, cause?: unknown);
-}
+import { CanaryError } from "./errors";
+export { CanaryError };
+export { DEFAULT_EXPERIMENTS_DIR, EXPERIMENT_ASSIGNMENT_SUFFIX, EXPERIMENT_LEDGER_SUFFIX, appendExperimentOutcome, appendExperimentOutcomes, dedupeExperimentOutcomes, experimentFileName, listExperiments, readExperimentAssignment, readExperimentOutcomes, removeExperimentAssignment, requestBucket, selectExperimentVariant, tallyExperimentOutcomes, validateExperimentConfig, writeExperimentAssignment, type ExperimentAssignment, type ExperimentConfig, type ExperimentOutcomeRecord, type ExperimentSelection, type ExperimentVariant, type VariantTally, } from "./experiment";
 export type CanaryRoutingDecision = {
     readonly version: string;
     /** Whether this request is on the canary side. */

package/dist/index.js

@@ -1,32 +1,7 @@
-/**
- * Section 28 — `canary-controller`. Shifts a configurable percentage of
- * incoming requests to a new version of a spec. Hash routing on
- * `(tenantId, requestId-hash mod 100 < trafficPercent)` so a given user
- * stays on the same side of the canary across requests.
- *
- * After `evalIntervalMs` elapses, runs an eval-spec against both versions
- * in parallel and gates promotion on `regression-runner` (Section 29 —
- * `gate(baseline, candidate)` over two `EvalRunSummary` results).
- *
- * The real gate is wired by the caller (item 29 — `crewhaus deploy canary`):
- * canary-controller stays dependency-inverted (it does NOT import
- * `regression-runner`/`eval-runner`, keeping this a leaf package). Callers
- * build a `RegressionGate` with {@link makeRegressionGate}, injecting the
- * per-step "eval both versions, then compare" closure. {@link PASSING_GATE}
- * is retained ONLY as an explicit always-pass stub for tests and manual
- * dry-runs — it is no longer the wired production default.
- *
- * Without an eval gate (manual mode), the controller waits for an
- * explicit `crewhaus deploy promote` call.
- */
-import { createHash } from "node:crypto";
-import { CrewhausError } from "@crewhaus/errors";
-export class CanaryError extends CrewhausError {
-    name = "CanaryError";
-    constructor(message, cause) {
-        super("config", message, cause);
-    }
-}
+import { CanaryError } from "./errors";
+import { requestBucket } from "./experiment";
+export { CanaryError };
+export { DEFAULT_EXPERIMENTS_DIR, EXPERIMENT_ASSIGNMENT_SUFFIX, EXPERIMENT_LEDGER_SUFFIX, appendExperimentOutcome, appendExperimentOutcomes, dedupeExperimentOutcomes, experimentFileName, listExperiments, readExperimentAssignment, readExperimentOutcomes, removeExperimentAssignment, requestBucket, selectExperimentVariant, tallyExperimentOutcomes, validateExperimentConfig, writeExperimentAssignment, } from "./experiment";
 /**
  * EXPLICIT always-pass stub. NOT the wired production default anymore
  * (item 29): the CLI builds a real gate via {@link makeRegressionGate} that
@@ -63,7 +38,7 @@ export function createCanaryController(opts) {
                 config.trafficPercent > 100) {
                 throw new CanaryError(`trafficPercent must be in 0..100; got ${config.trafficPercent}`);
             }
-            const bucket = computeBucket(config.tenantId, requestId);
+            const bucket = requestBucket(config.tenantId, requestId);
             const isCanary = bucket < config.trafficPercent;
             return {
                 version: isCanary ? config.toVersion : config.fromVersion,
@@ -137,10 +112,3 @@ export function createCanaryController(opts) {
         },
     };
 }
-function computeBucket(tenantId, requestId) {
-    const seed = `${tenantId ?? ""}|${requestId}`;
-    const hash = createHash("sha256").update(seed).digest();
-    // Take first 4 bytes as uint32, mod 100.
-    const v = ((hash[0] ?? 0) << 24) | ((hash[1] ?? 0) << 16) | ((hash[2] ?? 0) << 8) | (hash[3] ?? 0);
-    return Math.abs(v) % 100;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/canary-controller",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Percent-of-traffic rollout with eval-gated promotion. Hash-routes requests across two pinned versions and auto-rolls-back on regression.",
   "main": "dist/index.js",
@@ -15,10 +15,10 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/audit-log": "0.4.0",
-    "@crewhaus/deployment-controller": "0.4.0",
-    "@crewhaus/errors": "0.4.0",
-    "@crewhaus/spec-registry": "0.4.0"
+    "@crewhaus/audit-log": "0.5.0",
+    "@crewhaus/deployment-controller": "0.5.0",
+    "@crewhaus/errors": "0.5.0",
+    "@crewhaus/spec-registry": "0.5.0"
   },
   "license": "Apache-2.0",
   "author": {