modelrig 0.8.1 → 0.10.0

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/destination-loader.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Serving-`destination` route-field validation (Unified Route U2, ruling D-2).
+ * Extracted from loader.ts so loader.ts holds under the 700-LOC cap (same reason
+ * loader-warnings.ts / screen-loader.ts were carved out). Hand-written validation
+ * mirroring the loader's PROVIDERS/TIERS pattern: a route's `destination:` is
+ * checked against the DESTINATIONS vocabulary (the ONE source of truth in
+ * run/destination.ts — no second list to drift); an unknown value pushes a
+ * teaching problem (the caller turns it into a RouteConfigError). Absent ⇒
+ * undefined ⇒ resolves to `direct` at run time ⇒ BYTE-IDENTICAL.
+ */
+import type { Destination } from "../run/destination";
+/** Validate a route bundle's `destination:` value. Absent/null ⇒ undefined
+ * (defaults to `direct`); a known value ⇒ that `Destination`; an unknown value ⇒
+ * a pushed problem and undefined. */
+export declare function parseDestination(raw: unknown, problems: string[]): Destination | undefined;
+//# sourceMappingURL=destination-loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"destination-loader.d.ts","sourceRoot":"","sources":["../../src/routes/destination-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMtD;;qCAEqC;AACrC,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,WAAW,GAAG,SAAS,CAO1F"}

package/dist/routes/destination-loader.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Serving-`destination` route-field validation (Unified Route U2, ruling D-2).
+ * Extracted from loader.ts so loader.ts holds under the 700-LOC cap (same reason
+ * loader-warnings.ts / screen-loader.ts were carved out). Hand-written validation
+ * mirroring the loader's PROVIDERS/TIERS pattern: a route's `destination:` is
+ * checked against the DESTINATIONS vocabulary (the ONE source of truth in
+ * run/destination.ts — no second list to drift); an unknown value pushes a
+ * teaching problem (the caller turns it into a RouteConfigError). Absent ⇒
+ * undefined ⇒ resolves to `direct` at run time ⇒ BYTE-IDENTICAL.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDestination = parseDestination;
+const destination_1 = require("../run/destination");
+/** The serving-`destination` vocabulary as a lookup set, mirroring the loader's
+ * PROVIDERS/TIERS ReadonlySets. */
+const DESTINATIONS = new Set(destination_1.DESTINATIONS);
+/** Validate a route bundle's `destination:` value. Absent/null ⇒ undefined
+ * (defaults to `direct`); a known value ⇒ that `Destination`; an unknown value ⇒
+ * a pushed problem and undefined. */
+function parseDestination(raw, problems) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "string" || !DESTINATIONS.has(raw)) {
+        problems.push(`destination "${String(raw)}" is not one of [${[...DESTINATIONS].join(", ")}]`);
+        return undefined;
+    }
+    return raw;
+}

package/dist/routes/draft.d.ts

@@ -34,6 +34,13 @@ export interface RouteDraftSpec {
     readonly variables: readonly string[];
     /** JSON Schema for the output; null drafts an unstructured route. */
     readonly outputSchema: object | null;
+    /** `output: text` (issue #1) — a prose/markdown route, returned verbatim.
+     * Absent / `"json"` ⇒ nothing is emitted (the loader default). `text` with a
+     * non-null `outputSchema` is refused here, as the loader would refuse it. */
+    readonly outputKind?: "json" | "text";
+    /** `prompt.user` (issue #5, R1) — the per-call user-turn template, written
+     * to `prompts/<name>.user.md` and declared beside `prompt.system`. */
+    readonly userPrompt?: string;
     readonly require?: readonly string[];
     readonly prefer?: readonly string[];
     readonly policy?: {

package/dist/routes/draft.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"draft.d.ts","sourceRoot":"","sources":["../../src/routes/draft.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;IAC/C;wCACoC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KACrD,CAAC;IACF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;6EACyE;IACzE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,SAAS;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC;AAmBD,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CAgGhE;AAMD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE;IACF,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1D,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1D,EACD,IAAI,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;IAAC,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAAE,GAC7E,gBAAgB,CAclB"}
+{"version":3,"file":"draft.d.ts","sourceRoot":"","sources":["../../src/routes/draft.ts"],"names":[],"mappings":"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"}

package/dist/routes/draft.js

@@ -40,10 +40,15 @@ function buildRouteDraft(spec) {
         throw new Error(`route draft "${spec.route}" has no candidates — a route with nothing allowed to serve it ` +
             "cannot run. Name at least one provider/model.");
     }
+    if (spec.outputKind === "text" && spec.outputSchema !== null) {
+        throw new Error(`route draft "${spec.route}" declares output: text AND a schema — a prose route has no schema. ` +
+            "Drop the schema, or draft a JSON route.");
+    }
     const name = slug(spec.route);
     const files = [];
     const schemaRef = spec.outputSchema === null ? null : `./schemas/${name}.schema.json`;
     const promptRef = `./prompts/${name}.system.md`;
+    const userPromptRef = spec.userPrompt === undefined ? null : `./prompts/${name}.user.md`;
     const lines = [
         "# ModelRig route bundle — DRAFT. Nothing in your app calls this yet.",
         "# Read it, edit it, move it up one directory into modelrig/routes/, then",
@@ -55,6 +60,8 @@ function buildRouteDraft(spec) {
             lines.push(`# ${line}`);
     }
     lines.push("#", "# Candidates are ordered incumbent-first: the model you already use leads,", "# so the first run reproduces today's behavior. The cheaper probed", "# alternatives below it are what a bake-off would put to the test.", "#", "# `prefer` is empty ON PURPOSE. Adding `cost` re-sorts these candidates by", "# price, which would hand the first run to the cheapest model rather than", "# to your incumbent — the opposite of a like-for-like migration. Prove a", "# cheaper model with a bake-off, then switch to it deliberately.", `route: ${yamlString(spec.route)}`, "version: 1");
+    if (spec.outputKind === "text")
+        lines.push("output: text   # prose/markdown, returned verbatim (no schema:)");
     if (schemaRef !== null)
         lines.push(`schema: ${schemaRef}`);
     lines.push("candidates:");
@@ -78,6 +85,8 @@ function buildRouteDraft(spec) {
     lines.push(`prefer: [${(spec.prefer ?? []).map(yamlString).join(", ")}]`);
     lines.push("prompt:");
     lines.push(`  system: ${promptRef}`);
+    if (userPromptRef !== null)
+        lines.push(`  user: ${userPromptRef}   # per-call user turn (the delta next to a cache handle)`);
     lines.push(`  variables: [${spec.variables.map(yamlString).join(", ")}]` +
         (spec.variables.length === 0 ? "   # no {{variables}} detected — the prompt is static" : ""));
     const policy = spec.policy ?? {};
@@ -105,6 +114,9 @@ function buildRouteDraft(spec) {
         });
     }
     files.push({ path: `prompts/${name}.system.md`, contents: ensureTrailingNewline(spec.systemPrompt) });
+    if (spec.userPrompt !== undefined) {
+        files.push({ path: `prompts/${name}.user.md`, contents: ensureTrailingNewline(spec.userPrompt) });
+    }
     return { route: spec.route, files };
 }
 function ensureTrailingNewline(text) {

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

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/routes/loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAKV,WAAW,EAGZ,MAAM,gBAAgB,CAAC;AAWxB,OAAO,EAAE,sBAAsB,EAAE,kCAAkC,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC;AAE/H;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAO;CAOxF;AAiCD,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC,IAAI,IAAI,SAAS,WAAW,EAAE,CAAC;CAChC;AAscD;;;;;;;GAOG;AACH;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CAItF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,YAAY,CAyB1F;AAED;;yBAEyB;AACzB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CA6CtE;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CA2C1D"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/routes/loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,KAAK,EAKV,WAAW,EAGZ,MAAM,gBAAgB,CAAC;AAaxB,OAAO,EAAE,sBAAsB,EAAE,kCAAkC,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC;AAE/H;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAO;CAOxF;AA+BD,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC,IAAI,IAAI,SAAS,WAAW,EAAE,CAAC;CAChC;AA2aD;;;;;;;GAOG;AACH;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,CAItF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,YAAY,CAyB1F;AAED;;yBAEyB;AACzB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CA6CtE;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CA2C1D"}

package/dist/routes/loader.js

@@ -14,13 +14,17 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const yaml_1 = require("yaml");
 const failures_1 = require("../types/failures");
+const provider_1 = require("../types/provider");
 const fingerprint_1 = require("../registry/fingerprint");
 const cache_lint_1 = require("./cache-lint");
+const destination_loader_1 = require("./destination-loader"); // U2 (D-2): validated `destination` field (carved out for the LOC cap)
 const sampling_config_1 = require("./sampling-config");
 const loader_warnings_1 = require("./loader-warnings");
 const screen_loader_1 = require("./screen-loader");
+const prompt_loader_1 = require("./prompt-loader"); // issue #5 (R1): `prompt.user` + the prompt block (moved out for the LOC cap)
 const mask_loader_1 = require("./mask-loader");
 const objective_loader_1 = require("./objective-loader");
+const output_loader_1 = require("./output-loader"); // issue #1: `output: text` (prose) + the schema reader (moved out for the LOC cap)
 // Re-exported so existing importers of "./loader" keep resolving these advisories
 // (they live in ./loader-warnings to hold loader.ts under the 700-LOC cap).
 var loader_warnings_2 = require("./loader-warnings");
@@ -43,13 +47,11 @@ class RouteConfigError extends Error {
     }
 }
 exports.RouteConfigError = RouteConfigError;
-const PROVIDERS = new Set([
-    "gemini",
-    "openai",
-    "deepseek",
-    "anthropic",
-    "grok",
-]);
+// Provider allow-set for routable candidates and repair models (M-S1) — every
+// known ProviderId, now INCLUDING the ModelRig-hosted aggregator hosts
+// (fireworks/deepinfra/zai). Sourced from PROVIDER_IDS so it stays in lockstep
+// with the union (compacted from an inline literal to hold the 700-LOC cap).
+const PROVIDERS = new Set(provider_1.PROVIDER_IDS);
 const REQUIREMENTS = new Set([
     "schema_conformant",
     "grounded",
@@ -314,31 +316,6 @@ function parseVariants(raw, routeCandidates, problems) {
     }
     return out;
 }
-function readSchema(schemaRaw, bundleDir, problems) {
-    if (schemaRaw === null || schemaRaw === undefined)
-        return null;
-    if (typeof schemaRaw !== "string" || schemaRaw === "") {
-        problems.push("schema must be a relative path or null");
-        return null;
-    }
-    const schemaPath = (0, node_path_1.resolve)(bundleDir, schemaRaw);
-    if (!(0, node_fs_1.existsSync)(schemaPath)) {
-        problems.push(`schema file not found: ${schemaRaw}`);
-        return null;
-    }
-    try {
-        const parsed = JSON.parse((0, node_fs_1.readFileSync)(schemaPath, "utf8"));
-        if (!isRecord(parsed)) {
-            problems.push(`schema file ${schemaRaw} must contain a JSON object`);
-            return null;
-        }
-        return parsed;
-    }
-    catch (err) {
-        problems.push(`schema file ${schemaRaw} is not valid JSON: ${err.message}`);
-        return null;
-    }
-}
 function loadBundleFile(filePath) {
     const problems = [];
     let doc;
@@ -365,12 +342,14 @@ function loadBundleFile(filePath) {
     const candidates = parseCandidates(doc.candidates, problems);
     const require = parseStringList(doc.require, "require", REQUIREMENTS, problems);
     const prefer = parseStringList(doc.prefer, "prefer", PREFERENCES, problems);
-    const outputSchema = readSchema(doc.schema, bundleDir, problems);
+    const outputSchema = (0, output_loader_1.readSchema)(doc.schema, bundleDir, problems);
     const policy = parsePolicy(doc.policy, problems);
     // Phase 3 (bundle v2, all additive): variants, repair, capture opt-in,
     // grounding-inject query template.
     const variants = parseVariants(doc.variants, candidates, problems);
     const repair = parseRepair(doc.repair, "repair", candidates, problems);
+    // Issue #1: `output: text` (prose) — a load error when it contradicts schema:/require:/repair:.
+    const output = (0, output_loader_1.parseOutputBlock)(doc.output, { outputSchema, schemaDeclared: doc.schema !== undefined && doc.schema !== null, require, repair, variants }, problems);
     const capture = doc.capture ?? false;
     if (typeof capture !== "boolean") {
         problems.push("capture must be a boolean");
@@ -404,30 +383,16 @@ 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);
-    let systemTemplate = "";
-    let variables = [];
-    let variableTrust;
-    if (!isRecord(doc.prompt) || typeof doc.prompt.system !== "string") {
-        problems.push("prompt.system must be a relative path");
-    }
-    else {
-        const promptPath = (0, node_path_1.resolve)(bundleDir, doc.prompt.system);
-        if (!(0, node_fs_1.existsSync)(promptPath)) {
-            problems.push(`prompt.system file not found: ${doc.prompt.system}`);
-        }
-        else {
-            systemTemplate = (0, node_fs_1.readFileSync)(promptPath, "utf8");
-        }
-        // Screening S2 (SC-0 B3): parse names + optional per-variable x-trust.
-        const parsed = (0, screen_loader_1.parseVariables)(doc.prompt.variables ?? [], problems);
-        variables = parsed.names;
-        variableTrust = parsed.trust;
-    }
-    (0, screen_loader_1.pushUndeclaredVariableProblems)(systemTemplate, groundingQuery, variables, problems);
+    const screen = (0, screen_loader_1.parseScreenBlock)(doc.screen, problems);
+    const classification = (0, screen_loader_1.parseClassificationAndPhiGate)(doc.classification, { mask, screen, require }, problems);
+    const destination = (0, destination_loader_1.parseDestination)(doc.destination, problems); // Unified Route U2 (D-2)
+    // `prompt.system` / `prompt.user` (issue #5, R1) / `prompt.variables` (+ S2
+    // x-trust) — parsed in prompt-loader.ts; both templates are files relative to
+    // the bundle and share one declared-variable list.
+    const { systemTemplate, userTemplate, variables, variableTrust } = (0, prompt_loader_1.parsePromptBlock)(doc.prompt, bundleDir, problems);
+    (0, screen_loader_1.pushUndeclaredVariableProblems)(systemTemplate, groundingQuery, variables, problems, userTemplate);
     if (problems.length > 0) {
         throw new RouteConfigError("invalid route bundle", { file: filePath, problems });
     }
@@ -462,14 +427,22 @@ function loadBundleFile(filePath) {
     const xTrustWarning = (0, loader_warnings_1.untrustedShapedVariableWarning)(route, variables, variableTrust);
     if (xTrustWarning !== null)
         console.warn(`modelrig: ${xTrustWarning}`);
+    // Issue #5 (R1) advisory: a cached route with a Gemini candidate, a non-empty
+    // system template and no `prompt.user` — a handle would deliver the template
+    // as the user turn (never dropped); name the rule so the shape is deliberate.
+    const cachedPromptWarning = (0, prompt_loader_1.cachedRouteSystemOnlyWarning)(route, cache, candidates, systemTemplate, userTemplate);
+    if (cachedPromptWarning !== null)
+        console.warn(`modelrig: ${cachedPromptWarning}`);
     return Object.freeze({
         route: route,
         version: version,
         outputSchema: outputSchema === null ? null : Object.freeze(outputSchema),
+        ...output, // outputKind/outputMinChars — present ONLY for `output: text` (json ⇒ nothing added)
         candidates: Object.freeze(candidates),
         require: Object.freeze(require),
         prefer: Object.freeze(prefer),
         systemTemplate,
+        ...(userTemplate !== undefined ? { userTemplate } : {}), // issue #5 (R1): present ONLY when declared (absent ⇒ unchanged bundle_sha)
         variables: Object.freeze(variables),
         policy,
         ...(repair !== undefined ? { repair } : {}),
@@ -480,6 +453,8 @@ function loadBundleFile(filePath) {
         ...(groundingAssembly !== undefined ? { groundingAssembly } : {}),
         ...(variableTrust !== undefined ? { variableTrust } : {}),
         ...(mask !== undefined ? { mask } : {}),
+        ...(screen !== undefined ? { screen } : {}),
+        ...(classification !== undefined ? { classification } : {}), ...(destination !== undefined ? { destination } : {}),
         // 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;