modelrig 0.0.1 → 0.1.0

package/dist/registry/select.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * Model selection — the capability-first question, answered once.
+ *
+ * "Which models can serve strict JSON under $1/M?" is asked in three places:
+ * the console's query box, the MCP oracle's `query_registry` tool, and the
+ * docs. Phase 5 plan §10 names the risk by name — oracle answers drifting
+ * from console answers — so the grammar and the predicates live HERE and
+ * both surfaces call in. If this file changes, every surface changes.
+ *
+ * Dependency-free on purpose: the console imports this source directly (its
+ * tsconfig path alias) and must not drag SQLite or the adapters into a
+ * browser bundle.
+ *
+ * Bars are the registry's own, not new judgments: 0.9 conformance (the
+ * discrepancy detector's bar) and 0.5 grounding (facts.ts's GROUNDED_BAR).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREDICATE_GLOSS = exports.ALL_CAPABILITY_PREDICATES = void 0;
+exports.hasCapability = hasCapability;
+exports.parseCapabilityQuery = parseCapabilityQuery;
+exports.selectModels = selectModels;
+exports.explainEmptySelection = explainEmptySelection;
+exports.ALL_CAPABILITY_PREDICATES = [
+    "structured-native",
+    "structured-coached",
+    "grounding",
+    "caching",
+];
+/** Plain-language gloss per predicate — the explainability layer travels
+ * WITH the answer (console-explainability.md §1), it is not a separate doc. */
+exports.PREDICATE_GLOSS = {
+    "structured-native": "the provider enforces your JSON Schema on its side — probed native rung rate above zero",
+    "structured-coached": "output matched the schema at least 90% of probed samples, whether or not the provider enforced it natively",
+    grounding: "at least half of probed answers cited real retrieved sources rather than answering from memory",
+    caching: "repeat calls actually reported cached input tokens — a measured discount, not a claim",
+};
+const CONFORMANCE_BAR = 0.9;
+const GROUNDED_BAR = 0.5;
+function hasCapability(row, cap) {
+    switch (cap) {
+        case "structured-native":
+            return (row.nativeRungRate ?? 0) > 0;
+        case "structured-coached":
+            return (row.conformRate ?? 0) >= CONFORMANCE_BAR;
+        case "grounding":
+            return (row.groundedRate ?? 0) >= GROUNDED_BAR;
+        case "caching":
+            return (row.cacheHitRate ?? 0) > 0;
+    }
+}
+/** Question scaffolding. A search box gets keywords; the MCP oracle gets a
+ * whole sentence ("which models can serve strict JSON under $1/M?"), and
+ * without this every one of those words would become a substring filter on
+ * the model key and match nothing. Dropping them is strictly safer than
+ * matching them: no model key contains "which". */
+const STOP_WORDS = new Set([
+    "a", "about", "an", "and", "any", "are", "avail", "available", "be", "best", "can", "cheapest", "do",
+    "does", "find", "for", "give", "has", "have", "how", "i", "is", "it", "list", "me", "model",
+    "models", "need", "of", "or", "provider", "providers", "serve", "serves", "show", "some",
+    "support", "supports", "that", "the", "their", "them", "there", "these", "they", "this",
+    "those", "to", "use", "using", "want", "what", "whats", "which", "who", "will", "with",
+]);
+/** Punctuation a question drags in — stripped so "json?" is still "json". */
+function normalizeWord(word) {
+    return word.replace(/^[^a-z0-9./_-]+|[^a-z0-9./_-]+$/g, "");
+}
+const CAP_WORDS = [
+    [["json", "strict", "structured", "schema"], "structured-native"],
+    [["grounded", "grounding", "search", "web"], "grounding"],
+    [["cache", "caching", "cached"], "caching"],
+];
+/** The tiny grammar behind the query box and the oracle's free-text input:
+ * capability words + an "under $N/M" price cap; everything else is a
+ * substring match on the model key. Small on purpose — a question we cannot
+ * parse should fall through to text, not guess. */
+function parseCapabilityQuery(query) {
+    const caps = [];
+    const text = [];
+    const priceMatch = query.match(/under\s+\$?(\d+(?:\.\d+)?)\s*\/?\s*m/i);
+    const maxInputUsdPerMtok = priceMatch ? Number(priceMatch[1]) : null;
+    const cleaned = query.replace(/under\s+\$?\d+(?:\.\d+)?\s*\/?\s*m\w*/i, "");
+    for (const raw of cleaned.toLowerCase().split(/\s+/)) {
+        const word = normalizeWord(raw);
+        if (word === "" || STOP_WORDS.has(word))
+            continue;
+        const match = CAP_WORDS.find(([words]) => words.includes(word));
+        if (match === undefined) {
+            text.push(word);
+            continue;
+        }
+        if (!caps.includes(match[1]))
+            caps.push(match[1]);
+    }
+    return { caps, maxInputUsdPerMtok, text };
+}
+function selectModels(rows, criteria = {}) {
+    const caps = criteria.caps ?? [];
+    const text = criteria.text ?? [];
+    let out = rows.filter((row) => {
+        if (criteria.provider != null && criteria.provider !== "" && row.provider !== criteria.provider) {
+            return false;
+        }
+        if (criteria.discrepanciesOnly === true && row.discrepancies === 0)
+            return false;
+        if (caps.some((cap) => !hasCapability(row, cap)))
+            return false;
+        if (criteria.maxInputUsdPerMtok != null) {
+            // A model with no published input price cannot be proven under a cap —
+            // absence is not "cheap enough".
+            if (row.inputUsdPerMtok === null || row.inputUsdPerMtok > criteria.maxInputUsdPerMtok) {
+                return false;
+            }
+        }
+        if (text.length > 0 && !text.every((w) => row.key.toLowerCase().includes(w)))
+            return false;
+        return true;
+    });
+    if (criteria.sortByEffectiveCost !== false) {
+        out = [...out].sort((a, b) => (a.effectiveUsdPer1k ?? Number.POSITIVE_INFINITY) -
+            (b.effectiveUsdPer1k ?? Number.POSITIVE_INFINITY));
+    }
+    if (criteria.limit !== undefined && criteria.limit > 0)
+        out = out.slice(0, criteria.limit);
+    return out;
+}
+/** Why a question found nothing — the difference between "no such model" and
+ * "we have not probed one yet" is the whole point of the demand meter. */
+function explainEmptySelection(criteria) {
+    const parts = [];
+    for (const cap of criteria.caps ?? [])
+        parts.push(exports.PREDICATE_GLOSS[cap]);
+    if (criteria.maxInputUsdPerMtok != null) {
+        parts.push(`input price at or under $${criteria.maxInputUsdPerMtok}/M tokens`);
+    }
+    const asked = parts.length > 0 ? parts.join("; and ") : "the requested filters";
+    return (`No probed model in the registry satisfies ${asked}. ` +
+        "This means no model we have MEASURED qualifies — not that none exists. " +
+        "Unprobed models are absent from these answers by design; open a probe request " +
+        "if you need a specific model covered.");
+}

package/dist/registry/staleness.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Probe-data freshness — addendum A2 (TrustedRouter pattern 3): never serve
+ * stale-as-fresh. The SLO is 7-day-on-change / monthly; without per-entry
+ * change-detection timestamps the enforceable bound is the monthly one, so
+ * staleness = newest probed as_of older than 31 days. Stale data stays
+ * visible — bannered and dated, never hidden.
+ */
+export declare const PROBE_FRESHNESS_SLO_DAYS = 31;
+export interface ProbeFreshness {
+    readonly stale: boolean;
+    /** Newest probed as_of across the corpus — the banner's date. */
+    readonly newestAsOf: string | null;
+    readonly daysOld: number | null;
+}
+export declare function probeFreshness(asOfDates: ReadonlyArray<string | null | undefined>, now?: Date): ProbeFreshness;
+/** The banner sentence (brand guide §7: plain, dated, never hidden). */
+export declare function stalenessSentence(freshness: ProbeFreshness): string;
+//# sourceMappingURL=staleness.d.ts.map

package/dist/registry/staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.d.ts","sourceRoot":"","sources":["../../src/registry/staleness.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,wBAAgB,cAAc,CAC5B,SAAS,EAAE,aAAa,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EACnD,GAAG,GAAE,IAAiB,GACrB,cAAc,CAgBhB;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,cAAc,GAAG,MAAM,CASnE"}

package/dist/registry/staleness.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Probe-data freshness — addendum A2 (TrustedRouter pattern 3): never serve
+ * stale-as-fresh. The SLO is 7-day-on-change / monthly; without per-entry
+ * change-detection timestamps the enforceable bound is the monthly one, so
+ * staleness = newest probed as_of older than 31 days. Stale data stays
+ * visible — bannered and dated, never hidden.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROBE_FRESHNESS_SLO_DAYS = void 0;
+exports.probeFreshness = probeFreshness;
+exports.stalenessSentence = stalenessSentence;
+exports.PROBE_FRESHNESS_SLO_DAYS = 31;
+function probeFreshness(asOfDates, now = new Date()) {
+    const parsed = asOfDates
+        .filter((d) => typeof d === "string" && d !== "")
+        .map((d) => new Date(d).getTime())
+        .filter((t) => Number.isFinite(t));
+    if (parsed.length === 0) {
+        // No probe data at all is its own kind of stale — banner with no date.
+        return { stale: true, newestAsOf: null, daysOld: null };
+    }
+    const newest = Math.max(...parsed);
+    const daysOld = Math.floor((now.getTime() - newest) / 86400000);
+    return {
+        stale: daysOld > exports.PROBE_FRESHNESS_SLO_DAYS,
+        newestAsOf: new Date(newest).toISOString(),
+        daysOld,
+    };
+}
+/** The banner sentence (brand guide §7: plain, dated, never hidden). */
+function stalenessSentence(freshness) {
+    if (freshness.newestAsOf === null) {
+        return "No probe data yet — nothing on this page has been verified.";
+    }
+    return (`This probe data exceeded its freshness window (${exports.PROBE_FRESHNESS_SLO_DAYS} days): ` +
+        `newest result ${freshness.newestAsOf.slice(0, 10)}, ${freshness.daysOld} days old. ` +
+        "The data below is still shown, clearly dated — a rerun is due.");
+}

package/dist/routes/draft.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Route-bundle drafting — the shared emitter behind BOTH `modelrig init`
+ * (WS2) and the oracle's `create_route` act tool (WS1).
+ *
+ * A route bundle is three files, not one: the YAML, its JSON Schema, and its
+ * system prompt. A "draft" that emitted only the YAML would not load, so
+ * this builds the whole set.
+ *
+ * PURE: it returns file contents and writes nothing. Every caller that
+ * touches the disk does so through `writeRouteDraft`, which refuses to
+ * overwrite — drafts are proposals for a human to read, never edits.
+ *
+ * The YAML is hand-emitted rather than serialized by the `yaml` package on
+ * purpose: drafts are read by humans first, and the comments explaining WHERE
+ * each candidate came from are the most valuable lines in the file.
+ */
+export interface DraftCandidate {
+    readonly provider: string;
+    readonly model: string;
+    /** Why this candidate is here — rendered as a trailing comment. */
+    readonly note?: string;
+}
+export interface RouteDraftSpec {
+    /** Route handle, e.g. "research.growth_scenarios". */
+    readonly route: string;
+    readonly candidates: readonly DraftCandidate[];
+    /** Incumbent first is the caller's job; this records which one it was so
+     * the draft can say so out loud. */
+    readonly incumbent?: {
+        readonly provider: string;
+        readonly model: string;
+    } | null;
+    readonly systemPrompt: string;
+    readonly variables: readonly string[];
+    /** JSON Schema for the output; null drafts an unstructured route. */
+    readonly outputSchema: object | null;
+    readonly require?: readonly string[];
+    readonly prefer?: readonly string[];
+    readonly policy?: {
+        readonly timeoutMs?: number;
+        readonly tier?: string;
+        readonly json?: string;
+        readonly retries?: Readonly<Record<string, number>>;
+    };
+    readonly capture?: boolean;
+    /** Provenance lines rendered as a header comment — "found at src/x.ts:42".
+     * SD8: customer-zero provenance is labeled, never hardcoded behavior. */
+    readonly provenance?: readonly string[];
+}
+export interface DraftFile {
+    /** Path relative to the drafts directory. */
+    readonly path: string;
+    readonly contents: string;
+}
+export interface RouteDraft {
+    readonly route: string;
+    readonly files: readonly DraftFile[];
+}
+export declare function buildRouteDraft(spec: RouteDraftSpec): RouteDraft;
+export interface WriteDraftResult {
+    readonly written: readonly string[];
+    /** Files that already existed and were left alone. */
+    readonly skipped: readonly string[];
+}
+/**
+ * Write a draft into `draftsDir`. Two rules, both deliberate:
+ *  - It writes ONLY under the drafts directory. Nothing here can touch the
+ *    caller's source, their live routes, or the control plane (spec §4:
+ *    drafts-only is permanent this phase).
+ *  - It never overwrites. A second run reports what it skipped instead of
+ *    silently discarding edits a human made to a draft.
+ */
+export declare function writeRouteDraft(draft: RouteDraft, draftsDir: string, fs: {
+    existsSync: (p: string) => boolean;
+    mkdirSync: (p: string, o: {
+        recursive: boolean;
+    }) => void;
+    writeFileSync: (p: string, c: string, e: "utf8") => void;
+}, path: {
+    join: (...parts: string[]) => string;
+    dirname: (p: string) => string;
+}): WriteDraftResult;
+//# sourceMappingURL=draft.d.ts.map

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

@@ -0,0 +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"}

package/dist/routes/draft.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Route-bundle drafting — the shared emitter behind BOTH `modelrig init`
+ * (WS2) and the oracle's `create_route` act tool (WS1).
+ *
+ * A route bundle is three files, not one: the YAML, its JSON Schema, and its
+ * system prompt. A "draft" that emitted only the YAML would not load, so
+ * this builds the whole set.
+ *
+ * PURE: it returns file contents and writes nothing. Every caller that
+ * touches the disk does so through `writeRouteDraft`, which refuses to
+ * overwrite — drafts are proposals for a human to read, never edits.
+ *
+ * The YAML is hand-emitted rather than serialized by the `yaml` package on
+ * purpose: drafts are read by humans first, and the comments explaining WHERE
+ * each candidate came from are the most valuable lines in the file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRouteDraft = buildRouteDraft;
+exports.writeRouteDraft = writeRouteDraft;
+/** YAML string quoting: quote unless the value is unambiguously a plain
+ * scalar. Model ids carry dots, colons and dashes — the cases that bite. */
+function yamlString(value) {
+    if (/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value))
+        return value;
+    return JSON.stringify(value);
+}
+function slug(route) {
+    return route.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+const DEFAULT_RETRIES = {
+    content_invalid: 2,
+    network: 4,
+    capacity_shed: 3,
+};
+function buildRouteDraft(spec) {
+    if (spec.route.trim() === "")
+        throw new Error("a route draft needs a route name");
+    if (spec.candidates.length === 0) {
+        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.");
+    }
+    const name = slug(spec.route);
+    const files = [];
+    const schemaRef = spec.outputSchema === null ? null : `./schemas/${name}.schema.json`;
+    const promptRef = `./prompts/${name}.system.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",
+        "# switch the call site to rig.run(\"" + spec.route + "\", …).",
+    ];
+    if (spec.provenance !== undefined && spec.provenance.length > 0) {
+        lines.push("#");
+        for (const line of spec.provenance)
+            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 (schemaRef !== null)
+        lines.push(`schema: ${schemaRef}`);
+    lines.push("candidates:");
+    for (const candidate of spec.candidates) {
+        lines.push(`  - provider: ${yamlString(candidate.provider)}`);
+        lines.push(`    model: ${yamlString(candidate.model)}` +
+            (candidate.note !== undefined ? `   # ${candidate.note}` : ""));
+    }
+    const require = spec.require ?? (spec.outputSchema === null ? [] : ["schema_conformant"]);
+    if (require.length > 0) {
+        lines.push("require:");
+        for (const r of require)
+            lines.push(`  - ${yamlString(r)}`);
+    }
+    else {
+        lines.push("require: []");
+    }
+    // Default EMPTY, not [cost]: `prefer: [cost]` re-sorts candidates by price
+    // at resolve time, so the incumbent-first ordering above would be silently
+    // overridden and the first run would NOT reproduce today's behavior.
+    lines.push(`prefer: [${(spec.prefer ?? []).map(yamlString).join(", ")}]`);
+    lines.push("prompt:");
+    lines.push(`  system: ${promptRef}`);
+    lines.push(`  variables: [${spec.variables.map(yamlString).join(", ")}]` +
+        (spec.variables.length === 0 ? "   # no {{variables}} detected — the prompt is static" : ""));
+    const policy = spec.policy ?? {};
+    const retries = policy.retries ?? DEFAULT_RETRIES;
+    lines.push("policy:");
+    lines.push(`  retries: { ${Object.entries(retries)
+        .map(([k, v]) => `${k}: ${v}`)
+        .join(", ")} }`);
+    lines.push(`  timeout_ms: ${policy.timeoutMs ?? 120000}`);
+    lines.push(`  tier: ${yamlString(policy.tier ?? "standard")}`);
+    // json only means something for a schema'd route; the loader defaults it,
+    // so an unstructured draft says nothing rather than saying something wrong.
+    if (spec.outputSchema !== null || policy.json !== undefined) {
+        lines.push(`  json: ${yamlString(policy.json ?? "native")}`);
+    }
+    if (spec.capture === true) {
+        lines.push("# capture: replay inputs are stored LOCALLY only — never exported.");
+        lines.push("capture: true");
+    }
+    files.push({ path: `${name}.yaml`, contents: `${lines.join("\n")}\n` });
+    if (spec.outputSchema !== null) {
+        files.push({
+            path: `schemas/${name}.schema.json`,
+            contents: `${JSON.stringify(spec.outputSchema, null, 2)}\n`,
+        });
+    }
+    files.push({ path: `prompts/${name}.system.md`, contents: ensureTrailingNewline(spec.systemPrompt) });
+    return { route: spec.route, files };
+}
+function ensureTrailingNewline(text) {
+    return text.endsWith("\n") ? text : `${text}\n`;
+}
+/**
+ * Write a draft into `draftsDir`. Two rules, both deliberate:
+ *  - It writes ONLY under the drafts directory. Nothing here can touch the
+ *    caller's source, their live routes, or the control plane (spec §4:
+ *    drafts-only is permanent this phase).
+ *  - It never overwrites. A second run reports what it skipped instead of
+ *    silently discarding edits a human made to a draft.
+ */
+function writeRouteDraft(draft, draftsDir, fs, path) {
+    const written = [];
+    const skipped = [];
+    for (const file of draft.files) {
+        const full = path.join(draftsDir, file.path);
+        if (fs.existsSync(full)) {
+            skipped.push(full);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, file.contents, "utf8");
+        written.push(full);
+    }
+    return { written, skipped };
+}

package/dist/routes/loader.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Routes-as-code loader — spec §3, plan step 3.
+ * Scans a routes directory for *.yaml bundles, validates structurally,
+ * resolves schema/prompt paths relative to the bundle file, freezes.
+ */
+import type { RouteBundle } from "../types/route";
+/**
+ * Structured config error thrown for any invalid bundle (never a raw Error).
+ * Load-time problems are deliberately NOT RigFailures — the failure taxonomy
+ * classifies inference attempts; a malformed bundle means the rig was never
+ * runnable for that route.
+ */
+export declare class RouteConfigError extends Error {
+    readonly file: string | null;
+    readonly problems: readonly string[];
+    constructor(message: string, opts?: {
+        file?: string;
+        problems?: readonly string[];
+    });
+}
+export interface LoadedRoutes {
+    get(route: string): RouteBundle;
+    list(): readonly RouteBundle[];
+}
+export declare function loadRoutes(routesDir: string): LoadedRoutes;
+//# sourceMappingURL=loader.d.ts.map

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

@@ -0,0 +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;AAIxB;;;;;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;AAkXD,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CA2C1D"}