modelrig 0.8.0 → 0.9.0

package/dist/routes/call-config.d.ts

@@ -0,0 +1,199 @@
+/**
+ * SDK-side live call-config resolution (live-routing-evals spec §4, R-1; LRE-1a).
+ *
+ * A route's live call-config (which model/provider + sampling) can be edited in
+ * the console WITHOUT a redeploy. The SDK reads it just-before-call through
+ * `GET /v1/routes/:route/call-config`, caches the policy (short TTL, ETag-
+ * revalidated), and MERGES the pin over the resolved (mirrored/deploy-time)
+ * bundle before `run()`. This is R-1's cached-policy model: no per-call network
+ * cost when fresh, and outage-safe.
+ *
+ * ── FAIL-OPEN, ALWAYS — the hot path never throws ─────────────────────────
+ * `getCallConfig` NEVER throws. On any error it returns the LAST-KNOWN-GOOD
+ * cached policy; if there is none, it returns null — and a null resolution means
+ * "serve the mirrored/pinned bundle unchanged". A route with no override
+ * resolves BYTE-IDENTICAL to today (the golden invariant): `applyCallConfig`
+ * returns the SAME bundle reference when there is nothing to merge.
+ *
+ * ── PHASE 1 = PIN ONLY ────────────────────────────────────────────────────
+ * `mode='experiment'` (local weighted arm draw) and `mode='live'` (strict per-
+ * call read) are TYPED here so the wire shape is complete, but they are INERT:
+ * `applyCallConfig` acts on `mode='pin'` only and passes everything else through
+ * unchanged. Experiments ship in LRE-2.
+ */
+import type { RouteBundle } from "../types/route";
+export type CallConfigMode = "pin" | "experiment" | "live";
+export type CallConfigSource = "user" | "optimizer" | "yaml-default";
+/** The on-the-wire sampling block (snake_case, as the endpoint returns it). */
+export interface CallConfigSampling {
+    readonly temperature?: number;
+    readonly top_p?: number;
+    readonly max_output_tokens?: number;
+}
+/** A `mode='pin'` config: a single model + optional sampling/variant. */
+export interface CallConfigPin {
+    readonly provider: string;
+    readonly model: string;
+    readonly sampling?: CallConfigSampling;
+    readonly variant?: string;
+}
+/** A resolved current config, as the resolver caches it. `version===0` and
+ * `mode===null` is the INERT default (no override) — resolution is byte-identical
+ * to the mirrored bundle. */
+export interface ResolvedCallConfig {
+    readonly version: number;
+    readonly mode: CallConfigMode | null;
+    readonly config: unknown;
+    readonly etag: string;
+}
+/** Pulls one route's current config from the control plane, ETag-aware. Returns
+ * the config, `"not-modified"` (304 — keep the cache), or null (miss / error —
+ * the resolver keeps last-known-good). NEVER throws. */
+export interface CallConfigFetcher {
+    fetch(route: string, etag: string | undefined): Promise<ResolvedCallConfig | "not-modified" | null>;
+}
+export interface CallConfigResolver {
+    /** The effective config for a route. Reads the cache when fresh (within TTL);
+     * otherwise revalidates (ETag) and folds the result in. Fail-open: on error,
+     * returns last-known-good, else null. NEVER throws. `null` ⇒ no override ⇒
+     * serve the mirrored bundle unchanged. */
+    getCallConfig(route: string): Promise<ResolvedCallConfig | null>;
+    /** A copy of every resolved route's last-known config — for status/boot. */
+    snapshot(): ReadonlyMap<string, ResolvedCallConfig>;
+}
+export interface CallConfigResolverConfig {
+    readonly fetcher: CallConfigFetcher;
+    /** Cache freshness window (spec §4: ~30–60s). Within it, no fetch. */
+    readonly ttlMs: number;
+    /** Injectable clock for tests; defaults to Date.now. */
+    readonly now?: () => number;
+}
+/** Narrow an unknown endpoint body into a `ResolvedCallConfig`, or null when the
+ * shape is not what the endpoint promises (a malformed 200 is a miss, not
+ * trusted — we never fabricate an override from junk). */
+export declare function parseCallConfig(body: unknown): ResolvedCallConfig | null;
+/** Narrow a config to a `CallConfigPin`, or null (T7 — jsonb is not proof of
+ * shape). The single place a pin's shape is trusted on the SDK side. */
+export declare function narrowPin(config: unknown): CallConfigPin | null;
+/** The pin carried by a resolved config, or null when there is no pin override
+ * (no override, or a non-pin mode — inert in Phase 1). */
+export declare function pinFromResolved(resolved: ResolvedCallConfig | null): CallConfigPin | null;
+/**
+ * Merge a resolved call-config over a bundle, returning a runnable bundle.
+ *
+ * INERT BY DEFAULT: when `resolved` is null, or its mode is not `pin`, or the pin
+ * does not narrow, the SAME `bundle` reference is returned — byte-identical to
+ * today (the golden invariant). Otherwise the pin REPLACES the candidate set with
+ * the single pinned model (eligibility was gated at write, so it satisfies the
+ * route `require`) and merges its sampling into the policy.
+ *
+ * `mode='experiment'` is INERT here (returns the bundle unchanged): an experiment
+ * resolves through {@link resolveCallConfigForRun}, which draws an arm and returns
+ * the arm name for `inferences.meta.arm`. `applyCallConfig` stays pin-only so the
+ * pin/golden path is byte-identical.
+ */
+export declare function applyCallConfig(bundle: RouteBundle, resolved: ResolvedCallConfig | null): RouteBundle;
+/** One arm of an experiment: a resolved pin config + a positive weight + an
+ * optional stable name (defaults to the pin's variant or `provider/model`). The
+ * `ref` is a `CallConfigPin` so an arm merges over the bundle exactly like a pin. */
+export interface ExperimentArm {
+    readonly ref: CallConfigPin;
+    readonly weight: number;
+    readonly name?: string;
+}
+/** A `mode='experiment'` config (spec §2.1): weighted arms, an optional
+ * stickiness key (names the input field whose VALUE keys deterministic
+ * assignment), and a fallback pin (served when the experiment cannot draw). */
+export interface CallConfigExperiment {
+    readonly arms: readonly ExperimentArm[];
+    readonly stickyKey?: string;
+    readonly fallback: CallConfigPin;
+}
+/** The stable arm name stamped on `inferences.meta.arm` — the caller-declared
+ * name, else the pin's variant, else `provider/model`. Kept meta-safe (short, no
+ * whitespace) by construction: providers/models/variants are identifiers. */
+export declare function armName(arm: ExperimentArm): string;
+/** Narrow a jsonb `config` to a `CallConfigExperiment`, or null (T7 — jsonb is
+ * not proof of shape). Requires ≥1 well-formed arm (each `ref` a valid pin, each
+ * `weight` a positive finite number) and a fallback pin. Fail-open: a malformed
+ * experiment narrows to null and the caller serves the mirrored bundle. */
+export declare function narrowExperiment(config: unknown): CallConfigExperiment | null;
+/** FNV-1a 32-bit hash of a string → a stable uint32. Pure, dependency-free — the
+ * sticky-assignment key so the SAME unit key always draws the SAME arm (an A/B is
+ * measured honestly). Not cryptographic; a fast, well-distributed bucket hash. */
+export declare function hashUnitKey(key: string): number;
+export interface DrawArmOptions {
+    /** A stickiness unit key (already resolved from the input). When present the
+     * draw is DETERMINISTIC by `hash(unitKey)` — the same unit always lands on the
+     * same arm. Absent ⇒ a weighted random draw. */
+    readonly unitKey?: string;
+    /** Injectable RNG in [0,1) for the weighted-random path (tests seed it);
+     * defaults to Math.random. Ignored when `unitKey` is supplied. */
+    readonly rng?: () => number;
+}
+/**
+ * Draw one arm from an experiment (spec §4). Weighted by `weight`: an arm's draw
+ * probability is `weight / Σweights`. DETERMINISTIC by `hash(unitKey)` when a
+ * unit key is supplied (sticky assignment); weighted-random otherwise. Returns
+ * null only when there are no positive-weight arms (⇒ the caller serves the
+ * fallback). Pure over its inputs (the RNG/hash are the only entropy).
+ */
+export declare function drawArm(experiment: CallConfigExperiment, opts?: DrawArmOptions): ExperimentArm | null;
+/** The resolved bundle for a run PLUS the chosen arm name (or null for pin / no
+ * override / a non-experiment mode). The arm name is stamped on
+ * `inferences.meta.arm` (thread it into `run` via `RunOptions.arm`). */
+export interface ResolvedForRun {
+    readonly bundle: RouteBundle;
+    readonly arm: string | null;
+}
+/**
+ * Resolve a route's call-config into a runnable bundle for ONE call, drawing an
+ * experiment arm locally when `mode='experiment'` (spec §4, R-1). FAIL-OPEN and
+ * byte-identical for pin: `mode='pin'` merges exactly like {@link applyCallConfig}
+ * (arm null), a null/`live`/malformed resolution returns the bundle unchanged
+ * (arm null), and a malformed experiment falls back to the experiment's own
+ * fallback pin, else the mirrored bundle. NEVER throws.
+ *
+ * For an experiment, the stickiness unit key is `opts.unitKey` when given, else
+ * the value of `input[experiment.stickyKey]` (resolved from the run's input) —
+ * so the SAME unit is served the SAME arm across calls.
+ */
+export declare function resolveCallConfigForRun(bundle: RouteBundle, resolved: ResolvedCallConfig | null, opts?: {
+    readonly unitKey?: string;
+    readonly input?: Record<string, unknown>;
+    readonly rng?: () => number;
+}): ResolvedForRun;
+/**
+ * Build the cached call-config resolver. Holds a per-route cache with a fetch
+ * timestamp + ETag; a read within `ttlMs` returns the cache with no network; a
+ * stale read revalidates (If-None-Match) and folds the result in. Every fetch is
+ * fail-open: a rejection or a null leaves the last-known value in place, and a
+ * route never yet resolved returns null (⇒ serve the mirrored bundle unchanged).
+ */
+export declare function createCallConfigResolver(config: CallConfigResolverConfig): CallConfigResolver;
+export interface ApiCallConfigFetcherConfig {
+    /** Base URL of the hosted control plane — the SAME `ingestUrl` the api sink
+     * uses (the call-config path hangs off the host). */
+    readonly ingestUrl: string;
+    /** `rig_sk_…` key. GET needs no special scope (a read rides the readable route
+     * + config rows). Header only, never a URL (C2). */
+    readonly apiKey: string;
+    readonly fetchFn?: typeof fetch;
+}
+/**
+ * The api-mode call-config fetcher: one authenticated, ETag-aware GET per route.
+ * Mirrors the api sink's leak discipline (status only, never the body/URL in an
+ * error — C2). NEVER throws: a network/HTTP failure resolves null, a 304 resolves
+ * "not-modified", a malformed 200 resolves null — so the resolver stays fail-open.
+ */
+export declare function createApiCallConfigFetcher(config: ApiCallConfigFetcherConfig): CallConfigFetcher;
+/**
+ * Convenience: resolve `route`'s config through the resolver, then merge it over
+ * `bundle`. NEVER throws (delegates to `getCallConfig`'s fail-open) and returns
+ * the SAME bundle reference when there is no override (byte-identical).
+ */
+export declare function getCallConfig(route: string, deps: {
+    readonly resolver: CallConfigResolver;
+    readonly bundle: RouteBundle;
+}): Promise<RouteBundle>;
+//# sourceMappingURL=call-config.d.ts.map

package/dist/routes/call-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-config.d.ts","sourceRoot":"","sources":["../../src/routes/call-config.ts"],"names":[],"mappings":"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"}

package/dist/routes/call-config.js

@@ -0,0 +1,343 @@
+"use strict";
+/**
+ * SDK-side live call-config resolution (live-routing-evals spec §4, R-1; LRE-1a).
+ *
+ * A route's live call-config (which model/provider + sampling) can be edited in
+ * the console WITHOUT a redeploy. The SDK reads it just-before-call through
+ * `GET /v1/routes/:route/call-config`, caches the policy (short TTL, ETag-
+ * revalidated), and MERGES the pin over the resolved (mirrored/deploy-time)
+ * bundle before `run()`. This is R-1's cached-policy model: no per-call network
+ * cost when fresh, and outage-safe.
+ *
+ * ── FAIL-OPEN, ALWAYS — the hot path never throws ─────────────────────────
+ * `getCallConfig` NEVER throws. On any error it returns the LAST-KNOWN-GOOD
+ * cached policy; if there is none, it returns null — and a null resolution means
+ * "serve the mirrored/pinned bundle unchanged". A route with no override
+ * resolves BYTE-IDENTICAL to today (the golden invariant): `applyCallConfig`
+ * returns the SAME bundle reference when there is nothing to merge.
+ *
+ * ── PHASE 1 = PIN ONLY ────────────────────────────────────────────────────
+ * `mode='experiment'` (local weighted arm draw) and `mode='live'` (strict per-
+ * call read) are TYPED here so the wire shape is complete, but they are INERT:
+ * `applyCallConfig` acts on `mode='pin'` only and passes everything else through
+ * unchanged. Experiments ship in LRE-2.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCallConfig = parseCallConfig;
+exports.narrowPin = narrowPin;
+exports.pinFromResolved = pinFromResolved;
+exports.applyCallConfig = applyCallConfig;
+exports.armName = armName;
+exports.narrowExperiment = narrowExperiment;
+exports.hashUnitKey = hashUnitKey;
+exports.drawArm = drawArm;
+exports.resolveCallConfigForRun = resolveCallConfigForRun;
+exports.createCallConfigResolver = createCallConfigResolver;
+exports.createApiCallConfigFetcher = createApiCallConfigFetcher;
+exports.getCallConfig = getCallConfig;
+function isMode(v) {
+    return v === "pin" || v === "experiment" || v === "live";
+}
+/** Narrow an unknown endpoint body into a `ResolvedCallConfig`, or null when the
+ * shape is not what the endpoint promises (a malformed 200 is a miss, not
+ * trusted — we never fabricate an override from junk). */
+function parseCallConfig(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const b = body;
+    if (typeof b.version !== "number" || !Number.isInteger(b.version))
+        return null;
+    if (typeof b.etag !== "string")
+        return null;
+    const mode = b.mode === null ? null : isMode(b.mode) ? b.mode : undefined;
+    if (mode === undefined)
+        return null;
+    return { version: b.version, mode, config: b.config ?? null, etag: b.etag };
+}
+/** Narrow a config to a `CallConfigPin`, or null (T7 — jsonb is not proof of
+ * shape). The single place a pin's shape is trusted on the SDK side. */
+function narrowPin(config) {
+    if (typeof config !== "object" || config === null || Array.isArray(config))
+        return null;
+    const c = config;
+    if (typeof c.provider !== "string" || c.provider === "")
+        return null;
+    if (typeof c.model !== "string" || c.model === "")
+        return null;
+    const pin = {
+        provider: c.provider,
+        model: c.model,
+    };
+    if (typeof c.sampling === "object" && c.sampling !== null && !Array.isArray(c.sampling)) {
+        const s = c.sampling;
+        const sampling = {};
+        if (typeof s.temperature === "number")
+            sampling.temperature = s.temperature;
+        if (typeof s.top_p === "number")
+            sampling.top_p = s.top_p;
+        if (typeof s.max_output_tokens === "number")
+            sampling.max_output_tokens = s.max_output_tokens;
+        pin.sampling = sampling;
+    }
+    if (typeof c.variant === "string")
+        pin.variant = c.variant;
+    return pin;
+}
+/** The pin carried by a resolved config, or null when there is no pin override
+ * (no override, or a non-pin mode — inert in Phase 1). */
+function pinFromResolved(resolved) {
+    if (resolved === null || resolved.mode !== "pin")
+        return null;
+    return narrowPin(resolved.config);
+}
+/** Map the wire sampling (snake_case) to the SDK's `SamplingParams` (camelCase),
+ * merged over the bundle's existing sampling. Only present keys override. */
+function mergeSampling(base, over) {
+    if (over === undefined)
+        return base;
+    const out = { ...(base ?? {}) };
+    if (over.temperature !== undefined)
+        out.temperature = over.temperature;
+    if (over.top_p !== undefined)
+        out.topP = over.top_p;
+    if (over.max_output_tokens !== undefined)
+        out.maxOutputTokens = over.max_output_tokens;
+    return out;
+}
+/** Merge a single narrowed pin over a bundle — REPLACES the candidate set with
+ * the pinned model (eligibility was gated at write) and folds its sampling into
+ * the policy. The one place a pin becomes a runnable bundle; shared by the pin
+ * path and the experiment arm-draw so both merge identically. */
+function applyPin(bundle, pin) {
+    const pinnedCandidate = {
+        provider: pin.provider,
+        model: pin.model,
+        trial: false,
+    };
+    const sampling = mergeSampling(bundle.policy.sampling, pin.sampling);
+    return {
+        ...bundle,
+        candidates: [pinnedCandidate],
+        policy: { ...bundle.policy, ...(sampling !== undefined ? { sampling } : {}) },
+    };
+}
+/**
+ * Merge a resolved call-config over a bundle, returning a runnable bundle.
+ *
+ * INERT BY DEFAULT: when `resolved` is null, or its mode is not `pin`, or the pin
+ * does not narrow, the SAME `bundle` reference is returned — byte-identical to
+ * today (the golden invariant). Otherwise the pin REPLACES the candidate set with
+ * the single pinned model (eligibility was gated at write, so it satisfies the
+ * route `require`) and merges its sampling into the policy.
+ *
+ * `mode='experiment'` is INERT here (returns the bundle unchanged): an experiment
+ * resolves through {@link resolveCallConfigForRun}, which draws an arm and returns
+ * the arm name for `inferences.meta.arm`. `applyCallConfig` stays pin-only so the
+ * pin/golden path is byte-identical.
+ */
+function applyCallConfig(bundle, resolved) {
+    const pin = pinFromResolved(resolved);
+    if (pin === null)
+        return bundle;
+    return applyPin(bundle, pin);
+}
+/** The stable arm name stamped on `inferences.meta.arm` — the caller-declared
+ * name, else the pin's variant, else `provider/model`. Kept meta-safe (short, no
+ * whitespace) by construction: providers/models/variants are identifiers. */
+function armName(arm) {
+    return arm.name ?? arm.ref.variant ?? `${arm.ref.provider}/${arm.ref.model}`;
+}
+/** Narrow a jsonb `config` to a `CallConfigExperiment`, or null (T7 — jsonb is
+ * not proof of shape). Requires ≥1 well-formed arm (each `ref` a valid pin, each
+ * `weight` a positive finite number) and a fallback pin. Fail-open: a malformed
+ * experiment narrows to null and the caller serves the mirrored bundle. */
+function narrowExperiment(config) {
+    if (typeof config !== "object" || config === null || Array.isArray(config))
+        return null;
+    const c = config;
+    if (!Array.isArray(c.arms) || c.arms.length === 0)
+        return null;
+    const fallback = narrowPin(c.fallback);
+    if (fallback === null)
+        return null;
+    const arms = [];
+    for (const raw of c.arms) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+            return null;
+        const r = raw;
+        const ref = narrowPin(r.ref);
+        if (ref === null)
+            return null;
+        if (typeof r.weight !== "number" || !Number.isFinite(r.weight) || r.weight <= 0)
+            return null;
+        const arm = { ref, weight: r.weight };
+        if (typeof r.name === "string" && r.name !== "")
+            arm.name = r.name;
+        arms.push(arm);
+    }
+    const exp = { arms, fallback };
+    if (typeof c.stickyKey === "string" && c.stickyKey !== "")
+        exp.stickyKey = c.stickyKey;
+    return exp;
+}
+/** FNV-1a 32-bit hash of a string → a stable uint32. Pure, dependency-free — the
+ * sticky-assignment key so the SAME unit key always draws the SAME arm (an A/B is
+ * measured honestly). Not cryptographic; a fast, well-distributed bucket hash. */
+function hashUnitKey(key) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < key.length; i += 1) {
+        h ^= key.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/**
+ * Draw one arm from an experiment (spec §4). Weighted by `weight`: an arm's draw
+ * probability is `weight / Σweights`. DETERMINISTIC by `hash(unitKey)` when a
+ * unit key is supplied (sticky assignment); weighted-random otherwise. Returns
+ * null only when there are no positive-weight arms (⇒ the caller serves the
+ * fallback). Pure over its inputs (the RNG/hash are the only entropy).
+ */
+function drawArm(experiment, opts = {}) {
+    const arms = experiment.arms.filter((a) => a.weight > 0);
+    if (arms.length === 0)
+        return null;
+    const total = arms.reduce((sum, a) => sum + a.weight, 0);
+    // A point in [0,total): a deterministic fraction of `total` from the unit-key
+    // hash (sticky), else a random fraction. NEVER lands exactly on `total` (the
+    // hash is divided by 2^32, and rng() < 1), so the last arm is not over-picked.
+    const fraction = opts.unitKey !== undefined ? hashUnitKey(opts.unitKey) / 0x100000000 : (opts.rng ?? Math.random)();
+    let point = fraction * total;
+    for (const arm of arms) {
+        point -= arm.weight;
+        if (point < 0)
+            return arm;
+    }
+    return arms[arms.length - 1]; // floating-point guard — the last arm owns the tail.
+}
+/**
+ * Resolve a route's call-config into a runnable bundle for ONE call, drawing an
+ * experiment arm locally when `mode='experiment'` (spec §4, R-1). FAIL-OPEN and
+ * byte-identical for pin: `mode='pin'` merges exactly like {@link applyCallConfig}
+ * (arm null), a null/`live`/malformed resolution returns the bundle unchanged
+ * (arm null), and a malformed experiment falls back to the experiment's own
+ * fallback pin, else the mirrored bundle. NEVER throws.
+ *
+ * For an experiment, the stickiness unit key is `opts.unitKey` when given, else
+ * the value of `input[experiment.stickyKey]` (resolved from the run's input) —
+ * so the SAME unit is served the SAME arm across calls.
+ */
+function resolveCallConfigForRun(bundle, resolved, opts = {}) {
+    try {
+        if (resolved === null || resolved.mode === "live")
+            return { bundle, arm: null };
+        if (resolved.mode === "pin")
+            return { bundle: applyCallConfig(bundle, resolved), arm: null };
+        // mode === "experiment"
+        const experiment = narrowExperiment(resolved.config);
+        if (experiment === null)
+            return { bundle, arm: null }; // fail-open: inert.
+        const unitKey = opts.unitKey ??
+            (experiment.stickyKey !== undefined && opts.input !== undefined && opts.input[experiment.stickyKey] !== undefined
+                ? String(opts.input[experiment.stickyKey])
+                : undefined);
+        const arm = drawArm(experiment, {
+            ...(unitKey !== undefined ? { unitKey } : {}),
+            ...(opts.rng !== undefined ? { rng: opts.rng } : {}),
+        });
+        if (arm === null)
+            return { bundle: applyPin(bundle, experiment.fallback), arm: null };
+        return { bundle: applyPin(bundle, arm.ref), arm: armName(arm) };
+    }
+    catch {
+        // The hot path never throws — an unexpected shape serves the mirrored bundle.
+        return { bundle, arm: null };
+    }
+}
+/**
+ * Build the cached call-config resolver. Holds a per-route cache with a fetch
+ * timestamp + ETag; a read within `ttlMs` returns the cache with no network; a
+ * stale read revalidates (If-None-Match) and folds the result in. Every fetch is
+ * fail-open: a rejection or a null leaves the last-known value in place, and a
+ * route never yet resolved returns null (⇒ serve the mirrored bundle unchanged).
+ */
+function createCallConfigResolver(config) {
+    const now = config.now ?? (() => Date.now());
+    const cache = new Map();
+    return {
+        async getCallConfig(route) {
+            const entry = cache.get(route);
+            if (entry !== undefined && now() - entry.fetchedAt < config.ttlMs) {
+                return entry.value;
+            }
+            try {
+                const result = await config.fetcher.fetch(route, entry?.value.etag);
+                if (result === "not-modified") {
+                    // Fresh again — bump the timestamp, keep the value.
+                    if (entry !== undefined)
+                        cache.set(route, { value: entry.value, fetchedAt: now() });
+                    return entry?.value ?? null;
+                }
+                if (result === null) {
+                    // Miss/error — fail-open to last-known-good (or null the first time).
+                    return entry?.value ?? null;
+                }
+                cache.set(route, { value: result, fetchedAt: now() });
+                return result;
+            }
+            catch {
+                // The hot path never throws — fail-open to last-known-good.
+                return entry?.value ?? null;
+            }
+        },
+        snapshot() {
+            const out = new Map();
+            for (const [route, entry] of cache)
+                out.set(route, entry.value);
+            return out;
+        },
+    };
+}
+/**
+ * The api-mode call-config fetcher: one authenticated, ETag-aware GET per route.
+ * Mirrors the api sink's leak discipline (status only, never the body/URL in an
+ * error — C2). NEVER throws: a network/HTTP failure resolves null, a 304 resolves
+ * "not-modified", a malformed 200 resolves null — so the resolver stays fail-open.
+ */
+function createApiCallConfigFetcher(config) {
+    const base = config.ingestUrl.replace(/\/$/, "");
+    const fetchFn = config.fetchFn ?? fetch;
+    return {
+        async fetch(route, etag) {
+            const url = `${base}/v1/routes/${encodeURIComponent(route)}/call-config`;
+            let response;
+            try {
+                response = await fetchFn(url, {
+                    method: "GET",
+                    headers: {
+                        authorization: `Bearer ${config.apiKey}`,
+                        ...(etag !== undefined ? { "if-none-match": etag } : {}),
+                    },
+                });
+            }
+            catch {
+                return null; // network throw — fail-open, keep last-known.
+            }
+            if (response.status === 304)
+                return "not-modified";
+            if (!response.ok)
+                return null;
+            const body = (await response.json().catch(() => null));
+            return parseCallConfig(body);
+        },
+    };
+}
+/**
+ * Convenience: resolve `route`'s config through the resolver, then merge it over
+ * `bundle`. NEVER throws (delegates to `getCallConfig`'s fail-open) and returns
+ * the SAME bundle reference when there is no override (byte-identical).
+ */
+async function getCallConfig(route, deps) {
+    const resolved = await deps.resolver.getCallConfig(route);
+    return applyCallConfig(deps.bundle, resolved);
+}

package/dist/routes/loader.js

@@ -404,10 +404,10 @@ function loadBundleFile(filePath) {
     // RB-1 (near-optimal spec §3): objective knob, reference arm + judge, value
     // checks — all additive; candidate-set invariant enforced in parseRb1Fields.
     const rb1 = (0, objective_loader_1.parseRb1Fields)(doc, route, candidates, problems);
-    // CS-1 Proven Masking (spec §3): resolve the `mask:` block + its local
-    // dictionary here so an unreadable dictionary or unknown type is a LOAD error.
-    // Absent / `mode: off` ⇒ undefined ⇒ byte-identical (the golden test).
+    // CS-1 `mask:` (spec §3) + SC-1a `screen:` (spec §4.1) + SC-2 `classification:`/`phi` posture gate (spec-sc2 §4): resolved here so an unreadable dictionary / unknown detector-or-action / loosening sources key / mis-postured PHI route is a LOAD error (absent / `mode: off` ⇒ undefined ⇒ byte-identical). Classification + phi-gate live in screen-loader.ts (LOC cap).
     const mask = (0, mask_loader_1.parseMaskBlock)(doc.mask, bundleDir, problems);
+    const screen = (0, screen_loader_1.parseScreenBlock)(doc.screen, problems);
+    const classification = (0, screen_loader_1.parseClassificationAndPhiGate)(doc.classification, { mask, screen, require }, problems);
     let systemTemplate = "";
     let variables = [];
     let variableTrust;
@@ -480,6 +480,8 @@ function loadBundleFile(filePath) {
         ...(groundingAssembly !== undefined ? { groundingAssembly } : {}),
         ...(variableTrust !== undefined ? { variableTrust } : {}),
         ...(mask !== undefined ? { mask } : {}),
+        ...(screen !== undefined ? { screen } : {}),
+        ...(classification !== undefined ? { classification } : {}),
         // Network-effect instrumentation (spec WS6): computed once at load,
         // stamped on every telemetry row for this route.
         fingerprintCell: (0, fingerprint_1.fingerprintSchema)(outputSchema)?.cellKey ?? null,

package/dist/routes/objective-loader.d.ts

@@ -13,7 +13,19 @@ export declare function parseRb1Fields(doc: Record<string, unknown>, route: stri
     objective?: RouteObjective;
     bakeoff?: BakeoffConfig;
     valueChecks?: readonly ValueCheck[];
+    grade?: {
+        passThreshold: number;
+    };
 };
+/** Default grade pass threshold when a route declares no `grade:` block (R2). */
+export declare const DEFAULT_GRADE_PASS_THRESHOLD = 0.5;
+/** Parse the optional `grade:` block (grade primitive, R2). Currently one knob,
+ * `pass_threshold` (0–1). Declared + validated here but UNREAD until GP-2 wires
+ * verdict derivation. Absent ⇒ undefined (⇒ the default 0.5 is applied downstream).
+ * A malformed value pushes a teaching problem, exactly like every other field. */
+export declare function parseGradeBlock(raw: unknown, problems: string[]): {
+    passThreshold: number;
+} | undefined;
 /** Parse the `objective:` block. Absent ⇒ undefined (the engine defaults to
  * quality-first with no bound: regret shown, nothing proposed). */
 export declare function parseObjective(raw: unknown, problems: string[]): RouteObjective | undefined;

package/dist/routes/objective-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"objective-loader.d.ts","sourceRoot":"","sources":["../../src/routes/objective-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EAGb,cAAc,EACd,UAAU,EACX,MAAM,gBAAgB,CAAC;AAExB;;2EAE2E;AAC3E,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,QAAQ,EAAE,MAAM,EAAE,GACjB;IAAE,SAAS,CAAC,EAAE,cAAc,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IAAC,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAe9F;AAoCD;mEACmE;AACnE,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,cAAc,GAAG,SAAS,CAqD3F;AAqCD;;2EAE2E;AAC3E,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,QAAQ,EAAE,MAAM,EAAE,GACjB,aAAa,GAAG,SAAS,CAwE3B;AAiCD;uCACuC;AACvC,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,UAAU,EAAE,GAAG,SAAS,CAqCpG;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAUvG"}
+{"version":3,"file":"objective-loader.d.ts","sourceRoot":"","sources":["../../src/routes/objective-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EAGb,cAAc,EACd,UAAU,EACX,MAAM,gBAAgB,CAAC;AAExB;;2EAE2E;AAC3E,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,QAAQ,EAAE,MAAM,EAAE,GACjB;IACD,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACpC,KAAK,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACnC,CAmBA;AAYD,iFAAiF;AACjF,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;kFAGkF;AAClF,wBAAgB,eAAe,CAC7B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAAE,GACjB;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAavC;AA0BD;mEACmE;AACnE,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,cAAc,GAAG,SAAS,CAqD3F;AAqCD;;2EAE2E;AAC3E,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,QAAQ,EAAE,MAAM,EAAE,GACjB,aAAa,GAAG,SAAS,CA+F3B;AAoED;uCACuC;AACvC,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,UAAU,EAAE,GAAG,SAAS,CAqCpG;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAUvG"}