@metrxbot/sdk 0.2.0 → 0.2.2

package/dist/routing.js

@@ -0,0 +1,685 @@
+/**
+ * SDK cascade routing module — `runWithPolicy()` (spec
+ * docs/roi-engine-cascade-sdk-phase1-spec.md §5, Phase 1 S2).
+ *
+ * Bring-your-own-caller: the customer supplies the function that calls their
+ * provider with THEIR keys; this module supplies policy consultation, the
+ * confidence gate, escalation, holdout randomization, and evidence emission.
+ *
+ * THE INVARIANT (throw-parity, §5.7): no code path in runWithPolicy throws an
+ * error that the customer's own `callModel(prodModel)` would not have thrown.
+ * Policy fetch, gate, candidate calls, and every emit fail OPEN; only the
+ * production-model call's own errors propagate.
+ *
+ * Streaming is OUT OF SCOPE for v1 (§5.1 H7): this contract handles complete
+ * responses only — keep streaming call sites on their original path.
+ */
+import { PolicyCache, normalizeAgentKey, } from './routing-policy-cache';
+import { runValidators, runChecker, withTimeout } from './routing-gate';
+import { currentTaskId } from './task';
+/** Bump with package.json (atomic-version rule). Server can force pass-through
+ * for known-bad versions via routing_policies.min_sdk_version (F10).
+ * 0.2.2 = the FIRST published version carrying WS1 (task-keyed holdout draw,
+ * #260) — required for `randomization_unit:'task'` policies to draw causal arms.
+ * The npm-published 0.2.1 predates WS1; min_sdk_version must be '0.2.2'+ to gate. */
+export const SDK_VERSION = '0.2.2';
+const EMIT_TIMEOUT_MS = 2000; // house SDK pattern: fire-and-forget, bounded
+const JUDGE_TIMEOUT_MS = 10000; // background judging; a hung judge must not pin flush() (M3)
+const BREAKER_ERROR_THRESHOLD = 5;
+const BREAKER_WINDOW_MS = 10 * 60 * 1000;
+const BREAKER_COOLDOWN_MS = 10 * 60 * 1000;
+const BREAKER_ESCALATION_WINDOW = 50;
+const BREAKER_ESCALATION_RATE = 0.9;
+/**
+ * WS1 (Phase 3): deterministic map of a string to a uniform value in [0, 1).
+ * FNV-1a (32-bit) — stable across runs/processes and well-distributed, so the
+ * empirical treatment fraction over many task ids matches `holdout_pct`. Used to
+ * make the holdout arm a function of the TASK id (whole-task treatment) so
+ * multi-request tasks are arm-consistent — the prerequisite for task-level
+ * causal value evidence (Phase 3 D10). Mirrors the gateway's deterministicBucket
+ * (apps/gateway/src/model-routing.ts) but returns a unit float, not a %-bucket.
+ */
+export function hashToUnit(input) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0) / 0x100000000;
+}
+export class MetrxRouter {
+    cfg;
+    cache;
+    now;
+    random;
+    fetchImpl;
+    breakers = new Map();
+    background = new Set();
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.now = cfg.now ?? Date.now;
+        this.random = cfg.random ?? Math.random;
+        this.fetchImpl = cfg.fetchImpl ?? fetch;
+        this.cache = new PolicyCache({
+            fetcher: this.makePolicyFetcher(),
+            ttlMs: cfg.policyTtlMs,
+            staleMaxMs: cfg.policyStaleMaxMs,
+            now: this.now,
+        });
+    }
+    /** Await all in-flight background work (emits, shadow calls, judging).
+     * For tests and graceful shutdown — never required for correctness. */
+    async flush() {
+        await this.cache.settle();
+        while (this.background.size > 0) {
+            await Promise.allSettled(Array.from(this.background));
+        }
+    }
+    async run(opts) {
+        const requestId = opts.requestId ?? cryptoRandomUUID();
+        // M1 (throw-parity): a non-string agentKey must degrade to pass-through,
+        // not throw before the customer's own call would have run.
+        const agentKey = normalizeAgentKey(typeof opts.agentKey === 'string' ? opts.agentKey : '');
+        // F10 kill switches: local config / env.
+        if (this.cfg.disabled || envDisabled()) {
+            return this.passThrough(opts, requestId, 'disabled');
+        }
+        // F1/F2/F3: unknown or malformed policy state → pass-through.
+        let policy;
+        try {
+            policy = this.cache.get(agentKey);
+        }
+        catch {
+            policy = undefined;
+        }
+        if (!policy || !isUsablePolicy(policy)) {
+            return this.passThrough(opts, requestId, 'pass_through');
+        }
+        if (policy.denied || !policy.enabled) {
+            return this.passThrough(opts, requestId, 'pass_through');
+        }
+        // F10: server-declared bad SDK version → pass-through.
+        if (policy.min_sdk_version && semverLt(SDK_VERSION, policy.min_sdk_version) !== false) {
+            return this.passThrough(opts, requestId, 'pass_through');
+        }
+        // F10: local circuit breaker.
+        if (this.breakerOpen(agentKey)) {
+            return this.passThrough(opts, requestId, 'pass_through');
+        }
+        switch (policy.mode) {
+            case 'shadow_sample':
+                return this.runShadowSample(opts, policy, requestId);
+            case 'cascade':
+                return this.runCascade(opts, policy, requestId);
+            case 'pass_through':
+            default: {
+                const result = await this.passThrough(opts, requestId, 'pass_through', policy.prod_model);
+                // Report-only decision emit — only when a policy row explicitly exists.
+                this.emitDecision(policy, requestId, {
+                    mode: 'report-only',
+                    propensity: 1.0,
+                    action: { model: policy.prod_model },
+                    candidate_set: [policy.prod_model],
+                });
+                return result;
+            }
+        }
+    }
+    // ── Modes ──
+    async passThrough(opts, requestId, mode, prodModel) {
+        // F6/F7: this call's errors are the customer's own — they propagate.
+        const result = await opts.callModel(prodModel ?? undefined, opts.input, {
+            requestId,
+            phase: 'primary',
+        });
+        return {
+            output: result.output,
+            servedModel: prodModel ?? undefined,
+            escalated: false,
+            requestId,
+            mode,
+        };
+    }
+    async runShadowSample(opts, policy, requestId) {
+        // Serve prod FIRST — shadow work never adds serving latency (§5.2).
+        const prodResult = await opts.callModel(policy.prod_model ?? undefined, opts.input, {
+            requestId,
+            phase: 'primary',
+        });
+        if (this.random() < (policy.sample_rate ?? 0)) {
+            this.spawnBackground(async () => {
+                // F9: any failure here skips the sample; serving already completed.
+                // M3: a hanging shadow call must not pin background work forever.
+                const candidateResult = await withTimeout(opts.callModel(policy.candidate_model, opts.input, {
+                    requestId,
+                    phase: 'shadow_candidate',
+                }), policy.max_extra_latency_ms ?? 15000, 'shadow-candidate');
+                const checkerCtx = { requestId, phase: 'checker' };
+                const [prodScore, candScore] = await Promise.all([
+                    this.judgeOutput(opts, policy, prodResult.output, policy.prod_model ?? '', checkerCtx),
+                    this.judgeOutput(opts, policy, candidateResult.output, policy.candidate_model ?? '', checkerCtx),
+                ]);
+                this.emitPair(policy, requestId, {
+                    provenance: 'shadow_sample',
+                    prod_cost_microcents: prodResult.costMicrocents ?? null,
+                    candidate_cost_microcents: candidateResult.costMicrocents ?? null,
+                    prod_quality: prodScore.score,
+                    candidate_quality: candScore.score,
+                    judge_model: prodScore.judgeModel,
+                    gate_score: null,
+                });
+                this.emitQuality(policy, requestId, prodScore.score, prodScore.judgeModel);
+            });
+        }
+        this.emitDecision(policy, requestId, {
+            mode: 'shadow',
+            propensity: 1.0,
+            // L1: sample_rate travels in the action so diagnostics can reconstruct
+            // the sampling design from decision rows alone.
+            action: {
+                model: policy.prod_model,
+                shadow: policy.candidate_model,
+                sample_rate: policy.sample_rate,
+            },
+            candidate_set: [policy.prod_model, policy.candidate_model],
+        });
+        return {
+            output: prodResult.output,
+            servedModel: policy.prod_model ?? undefined,
+            escalated: false,
+            requestId,
+            mode: 'shadow_sample',
+        };
+    }
+    /**
+     * WS1 (Phase 3): the holdout-arm uniform draw.
+     *
+     * DEFAULT (`gate_config.randomization_unit` unset or `'request'`): a per-request
+     * Bernoulli via `this.random()` — BYTE-IDENTICAL to pre-Phase-3 behaviour. This
+     * is the live cascade path for every policy, so it must not change unless the
+     * policy explicitly opts in.
+     *
+     * TASK unit (`gate_config.randomization_unit === 'task'`): a DETERMINISTIC
+     * function of the current task id, so every request inside one `task()` lands on
+     * the same arm (whole-task treatment) → multi-request tasks are arm-consistent →
+     * task-level value evidence becomes causal (Phase 3 D10). Salted with
+     * `experiment_id` so a judge/experiment rotation re-randomizes assignments.
+     *
+     * Falls back to the per-request draw when there is no task context OR no
+     * `experiment_id` (M2 — never silently salt with a literal 'null'): those
+     * requests stay the Phase-2 non-actionable stratum, no throw, no regression.
+     */
+    holdoutUniform(policy) {
+        if (policy.gate_config?.randomization_unit === 'task') {
+            const taskId = currentTaskId();
+            const experimentId = policy.experiment_id;
+            if (taskId && experimentId) {
+                return hashToUnit(`${taskId}:${experimentId}`);
+            }
+        }
+        return this.random();
+    }
+    async runCascade(opts, policy, requestId) {
+        // Randomized holdout: control = forced pass-through (the experiment's
+        // control arm — the rollout IS the experiment, §3). WS1 (Phase 3): task-keyed
+        // when the policy opts in (holdoutUniform); byte-identical per-request draw
+        // otherwise. propensity stays `holdout_pct`/`1-holdout_pct` (logged metadata,
+        // NOT an IPW weight — the estimand uses raw arm means); a `holdout_pct=0`
+        // policy never draws control so propensity=0 is never emitted (decisions API
+        // rejects it). ctx (v0.2.1, #259) is preserved.
+        if (this.holdoutUniform(policy) < (policy.holdout_pct ?? 0)) {
+            const controlCtx = {
+                requestId,
+                phase: 'primary',
+                arm: 'control',
+                experimentId: policy.experiment_id ?? undefined,
+            };
+            const result = await opts.callModel(policy.prod_model ?? undefined, opts.input, controlCtx);
+            this.emitDecision(policy, requestId, {
+                mode: 'active',
+                propensity: policy.holdout_pct,
+                holdout_arm: 'control',
+                experiment_id: policy.experiment_id,
+                action: { model: policy.prod_model },
+                candidate_set: [policy.candidate_model, policy.prod_model],
+            });
+            // C2: control-arm outputs MUST be judged or the holdout test can never run.
+            this.spawnBackground(async () => {
+                const scored = await this.judgeOutput(opts, policy, result.output, undefined, {
+                    requestId,
+                    phase: 'checker',
+                    arm: 'control',
+                    experimentId: policy.experiment_id ?? undefined,
+                });
+                this.emitQuality(policy, requestId, scored.score, scored.judgeModel);
+            });
+            return {
+                output: result.output,
+                servedModel: policy.prod_model ?? undefined,
+                escalated: false,
+                arm: 'control',
+                experimentId: policy.experiment_id ?? undefined,
+                requestId,
+                mode: 'cascade',
+            };
+        }
+        // Treatment arm: candidate → gate → serve-or-escalate.
+        const agentKey = normalizeAgentKey(typeof opts.agentKey === 'string' ? opts.agentKey : String(opts.agentKey ?? ''));
+        const budgetMs = policy.max_extra_latency_ms ?? 15000;
+        // H4: ONE deadline bounds candidate + gate combined — the cap is the cap.
+        const deadline = this.now() + budgetMs;
+        // Treatment arm always carries the same arm/experiment tags.
+        const experimentId = policy.experiment_id ?? undefined;
+        let candidateResult = null;
+        let gateScore = null;
+        let escalationReason = null;
+        // M2: gate feasibility depends only on policy + opts — check it BEFORE
+        // paying for a candidate call that can never be served.
+        const checkerModel = checkerModelOf(policy);
+        if (!opts.checkerCaller || !checkerModel) {
+            escalationReason = 'gate:no_checker';
+        }
+        else {
+            try {
+                candidateResult = await withTimeout(opts.callModel(policy.candidate_model, opts.input, {
+                    requestId,
+                    phase: 'candidate',
+                    arm: 'treatment',
+                    experimentId,
+                }), budgetMs, 'candidate');
+                const validators = (policy.gate_config?.validators ?? undefined);
+                const g1 = runValidators(candidateResult.output, validators);
+                if (!g1.pass) {
+                    escalationReason = g1.reason ?? 'g1';
+                }
+                else {
+                    const remainingMs = deadline - this.now();
+                    if (remainingMs <= 0) {
+                        escalationReason = 'gate:budget_exhausted';
+                    }
+                    else {
+                        gateScore = await runChecker({
+                            checkerCaller: opts.checkerCaller,
+                            checkerModel,
+                            input: opts.input,
+                            output: candidateResult.output,
+                            rubric: rubricOf(policy),
+                            timeoutMs: remainingMs,
+                            ctx: { requestId, phase: 'checker', arm: 'treatment', experimentId },
+                        });
+                        if (gateScore < (policy.confidence_threshold ?? 1)) {
+                            escalationReason = 'gate:below_threshold';
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                // F4/F5: candidate or gate failure → escalate. Count toward the breaker.
+                this.recordCandidateError(agentKey);
+                escalationReason = `candidate_or_gate_error:${err instanceof Error ? err.name : 'unknown'}`;
+            }
+        }
+        if (candidateResult && escalationReason === null && gateScore !== null) {
+            // Serve the candidate.
+            this.recordEscalation(agentKey, false);
+            this.emitDecision(policy, requestId, {
+                mode: 'active',
+                propensity: 1 - policy.holdout_pct,
+                holdout_arm: 'treatment',
+                experiment_id: policy.experiment_id,
+                action: { model: policy.candidate_model, escalated: false, gate_score: gateScore },
+                candidate_set: [policy.candidate_model, policy.prod_model],
+            });
+            // H3: quality must be comparable across arms. With a custom judge, score
+            // the served output with THAT judge post-response (the gate score stays
+            // in the decision row); otherwise the rubric'd checker score IS the
+            // judge score — the same instrument the control arm uses.
+            if (opts.judge) {
+                const servedOutput = candidateResult.output;
+                const servedModel = policy.candidate_model ?? '';
+                this.spawnBackground(async () => {
+                    const scored = await this.judgeOutput(opts, policy, servedOutput, servedModel, {
+                        requestId,
+                        phase: 'checker',
+                        arm: 'treatment',
+                        experimentId,
+                    });
+                    this.emitQuality(policy, requestId, scored.score, scored.judgeModel);
+                });
+            }
+            else {
+                this.emitQuality(policy, requestId, gateScore, checkerModel);
+            }
+            return {
+                output: candidateResult.output,
+                servedModel: policy.candidate_model ?? undefined,
+                escalated: false,
+                arm: 'treatment',
+                experimentId: policy.experiment_id ?? undefined,
+                requestId,
+                mode: 'cascade',
+            };
+        }
+        // Escalate to the production model. F6: THIS call's errors propagate —
+        // exactly what the customer's own call would have thrown.
+        this.recordEscalation(agentKey, true);
+        const prodResult = await opts.callModel(policy.prod_model ?? undefined, opts.input, {
+            requestId,
+            phase: 'escalation',
+            arm: 'treatment',
+            experimentId,
+        });
+        this.emitDecision(policy, requestId, {
+            mode: 'active',
+            propensity: 1 - policy.holdout_pct,
+            holdout_arm: 'treatment',
+            experiment_id: policy.experiment_id,
+            action: {
+                model: policy.prod_model,
+                escalated: true,
+                gate_score: gateScore,
+                esc_reason: escalationReason,
+            },
+            candidate_set: [policy.candidate_model, policy.prod_model],
+        });
+        // Escalation pair (biased pre-screen — provenance-labeled) + served quality (C2).
+        const candidateOutput = candidateResult;
+        this.spawnBackground(async () => {
+            const prodScored = await this.judgeOutput(opts, policy, prodResult.output, policy.prod_model ?? '', {
+                requestId,
+                phase: 'checker',
+                arm: 'treatment',
+                experimentId,
+            });
+            if (candidateOutput && gateScore !== null) {
+                this.emitPair(policy, requestId, {
+                    provenance: 'escalation',
+                    prod_cost_microcents: prodResult.costMicrocents ?? null,
+                    candidate_cost_microcents: candidateOutput.costMicrocents ?? null,
+                    prod_quality: prodScored.score,
+                    candidate_quality: gateScore,
+                    judge_model: prodScored.judgeModel,
+                    gate_score: gateScore,
+                });
+            }
+            this.emitQuality(policy, requestId, prodScored.score, prodScored.judgeModel);
+        });
+        return {
+            output: prodResult.output,
+            servedModel: policy.prod_model ?? undefined,
+            escalated: true,
+            arm: 'treatment',
+            experimentId: policy.experiment_id ?? undefined,
+            requestId,
+            mode: 'cascade',
+        };
+    }
+    // ── Judging (client-side — text never leaves the process, §5.4) ──
+    async judgeOutput(opts, policy, output, producedByModel, checkerCtx) {
+        if (opts.judge) {
+            // M3: a hanging customer judge must not pin background work forever.
+            return withTimeout(opts.judge({
+                input: opts.input,
+                output,
+                model: producedByModel ?? policy.prod_model ?? '',
+            }), JUDGE_TIMEOUT_MS, 'judge');
+        }
+        const checkerModel = checkerModelOf(policy);
+        if (!opts.checkerCaller || !checkerModel) {
+            throw new Error('no judge available (checkerCaller + gate_config.checker_model required)');
+        }
+        // H3: same instrument + same rubric as the gate — arms stay comparable.
+        const score = await runChecker({
+            checkerCaller: opts.checkerCaller,
+            checkerModel,
+            input: opts.input,
+            output,
+            rubric: rubricOf(policy),
+            timeoutMs: JUDGE_TIMEOUT_MS,
+            ctx: checkerCtx,
+        });
+        return { score, judgeModel: checkerModel };
+    }
+    // ── Evidence emission (fire-and-forget, ≤2s, F8) ──
+    emitDecision(policy, requestId, fields) {
+        this.fireAndForget('/api/v1/decisions', {
+            decisions: [
+                {
+                    request_id: requestId,
+                    agent_key: policy.agent_key,
+                    policy_id: `cascade-v1:${policy.id}`,
+                    occurred_at: new Date(this.now()).toISOString(),
+                    context_features: {
+                        agent_key: policy.agent_key,
+                        policy_version: policy.policy_version,
+                        sdk_version: SDK_VERSION,
+                    },
+                    action: fields.action,
+                    candidate_set: fields.candidate_set,
+                    propensity: fields.propensity,
+                    holdout_arm: fields.holdout_arm ?? null,
+                    experiment_id: fields.experiment_id ?? null,
+                    mode: fields.mode,
+                },
+            ],
+        });
+    }
+    emitPair(policy, requestId, fields) {
+        this.fireAndForget('/api/v1/paired-samples', {
+            pairs: [
+                {
+                    request_id: requestId,
+                    agent_key: policy.agent_key,
+                    policy_id: policy.id,
+                    policy_version: policy.policy_version,
+                    prod_model: policy.prod_model,
+                    candidate_model: policy.candidate_model,
+                    occurred_at: new Date(this.now()).toISOString(),
+                    ...fields,
+                },
+            ],
+        });
+    }
+    emitQuality(policy, requestId, score, judgeModel) {
+        this.fireAndForget('/api/v1/quality/metrics', {
+            metrics: [
+                {
+                    agent_key: policy.agent_key,
+                    metric_type: 'confidence_score',
+                    metric_value: score,
+                    request_id: requestId,
+                    metadata: { source: 'metrx-routing-sdk', judge_model: judgeModel },
+                },
+            ],
+        });
+    }
+    fireAndForget(path, body) {
+        this.spawnBackground(async () => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), EMIT_TIMEOUT_MS);
+            try {
+                await this.fetchImpl(`${this.cfg.apiUrl}${path}`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${this.cfg.apiKey}`,
+                    },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        });
+    }
+    /** F8/F9: background work never throws into the request path. */
+    spawnBackground(fn) {
+        const p = fn().catch(() => undefined);
+        this.background.add(p);
+        p.finally(() => this.background.delete(p));
+    }
+    // ── Circuit breaker (client-side, supplemental — the authoritative breaker
+    //    is the server-side ops cron auto-disable, §5.6 M5) ──
+    breakerFor(agentKey) {
+        let state = this.breakers.get(agentKey);
+        if (!state) {
+            // M5: bounded — an interpolated/per-request agentKey must not leak a
+            // Map entry per request in a long-lived process.
+            if (this.breakers.size >= 1000) {
+                return { errorTimestamps: [], escalationRing: [], cooldownUntil: 0 };
+            }
+            state = { errorTimestamps: [], escalationRing: [], cooldownUntil: 0 };
+            this.breakers.set(agentKey, state);
+        }
+        return state;
+    }
+    breakerOpen(agentKey) {
+        // Non-creating read (M5).
+        return (this.breakers.get(agentKey)?.cooldownUntil ?? 0) > this.now();
+    }
+    recordCandidateError(agentKey) {
+        const state = this.breakerFor(agentKey);
+        const nowMs = this.now();
+        state.errorTimestamps = state.errorTimestamps.filter((t) => nowMs - t < BREAKER_WINDOW_MS);
+        state.errorTimestamps.push(nowMs);
+        if (state.errorTimestamps.length >= BREAKER_ERROR_THRESHOLD) {
+            state.cooldownUntil = nowMs + BREAKER_COOLDOWN_MS;
+            state.errorTimestamps = [];
+        }
+    }
+    recordEscalation(agentKey, escalated) {
+        const state = this.breakerFor(agentKey);
+        state.escalationRing.push(escalated);
+        if (state.escalationRing.length > BREAKER_ESCALATION_WINDOW)
+            state.escalationRing.shift();
+        if (state.escalationRing.length === BREAKER_ESCALATION_WINDOW) {
+            const rate = state.escalationRing.filter(Boolean).length / BREAKER_ESCALATION_WINDOW;
+            if (rate >= BREAKER_ESCALATION_RATE) {
+                // Candidate is useless here — stop paying its latency (§7 break-even).
+                state.cooldownUntil = this.now() + BREAKER_COOLDOWN_MS;
+                state.escalationRing = [];
+            }
+        }
+    }
+    // ── Policy fetch ──
+    makePolicyFetcher() {
+        return async (etag) => {
+            const headers = {
+                Authorization: `Bearer ${this.cfg.apiKey}`,
+            };
+            // H1: the ETag embeds the org id — the SDK cannot reconstruct it. Echo
+            // the server's header back OPAQUELY or revalidation can never 304.
+            if (etag !== null)
+                headers['If-None-Match'] = etag;
+            const res = await this.fetchImpl(`${this.cfg.apiUrl}/api/v1/routing/policies`, {
+                method: 'GET',
+                headers,
+            });
+            if (res.status === 304)
+                return { policies: [], version: 0, notModified: true };
+            if (!res.ok)
+                throw new Error(`policy fetch failed: ${res.status}`);
+            const body = (await res.json());
+            return {
+                policies: body.policies ?? [],
+                version: body.version ?? 0,
+                etag: res.headers.get('ETag'),
+            };
+        };
+    }
+}
+// ── Convenience wrapper: one router per client instance ──
+const routers = new WeakMap();
+export function routerFor(client, overrides) {
+    let router = routers.get(client);
+    if (!router) {
+        const creds = client.getRoutingCredentials();
+        router = new MetrxRouter({ apiKey: creds.apiKey, apiUrl: creds.apiUrl, ...overrides });
+        routers.set(client, router);
+    }
+    return router;
+}
+/**
+ * Run one request under the agent's routing policy. Day 0 (no policy rows):
+ * behaves exactly like `opts.callModel(undefined, opts.input)`.
+ */
+export async function runWithPolicy(client, opts) {
+    return routerFor(client).run(opts);
+}
+// ── Helpers ──
+function inRange(v, lo, hi) {
+    return typeof v === 'number' && !isNaN(v) && v >= lo && v <= hi;
+}
+function isUsablePolicy(p) {
+    if (typeof p !== 'object' || p === null)
+        return false;
+    if (!['pass_through', 'shadow_sample', 'cascade'].includes(p.mode))
+        return false;
+    if (p.mode !== 'pass_through') {
+        // H2: a shadow/cascade policy without a prod_model would serve fine but
+        // every emitted pair is rejected server-side — a silent dead experiment.
+        if (typeof p.candidate_model !== 'string' || !p.candidate_model)
+            return false;
+        if (typeof p.prod_model !== 'string' || !p.prod_model)
+            return false;
+        // M4 (F3 fully applied): server-controlled numbers must be sane or the
+        // whole row is unusable → pass-through.
+        if (!inRange(p.sample_rate, 0, 1))
+            return false;
+        if (!inRange(p.holdout_pct, 0, 0.5))
+            return false;
+        if (typeof p.max_extra_latency_ms !== 'number' || p.max_extra_latency_ms <= 0)
+            return false;
+        if (p.mode === 'cascade' && !inRange(p.confidence_threshold, 0, 1))
+            return false;
+    }
+    return true;
+}
+function rubricOf(policy) {
+    return typeof policy.gate_config?.rubric === 'string'
+        ? policy.gate_config.rubric
+        : undefined;
+}
+function checkerModelOf(policy) {
+    const m = policy.gate_config?.checker_model;
+    return typeof m === 'string' ? m : null;
+}
+function envDisabled() {
+    try {
+        return typeof process !== 'undefined' && process?.env?.METRX_ROUTING_DISABLED === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Loose semver-ish comparison. Returns true when a < b, false when a >= b,
+ * and `undefined` when either side is unparseable — the caller treats
+ * "unknown" as pass-through (fail toward doing nothing).
+ */
+export function semverLt(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    if (pa.some(isNaN) || pb.some(isNaN) || pa.length === 0 || pb.length === 0)
+        return undefined;
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x < y)
+            return true;
+        if (x > y)
+            return false;
+    }
+    return false;
+}
+function cryptoRandomUUID() {
+    try {
+        return crypto.randomUUID();
+    }
+    catch {
+        // Extremely defensive: ancient runtimes without webcrypto.
+        return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 10)}`;
+    }
+}
+//# sourceMappingURL=routing.js.map