modelrig 0.0.1 → 0.2.0

package/dist/run/resolve.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * Candidate resolution — plan §4. THE ONLY constructor of CandidateRef in the
+ * codebase (the candidate-set invariant is enforced here structurally).
+ * Phase 1 selection: first candidate whose static capability flags satisfy
+ * route.require, ordered by prefer:[cost] via the pricing snapshot; on a
+ * retryable failure the run loop asks for the next candidate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCandidates = resolveCandidates;
+exports.applyRunRequirements = applyRunRequirements;
+exports.candidateFilterFromOptions = candidateFilterFromOptions;
+exports.filterSummary = filterSummary;
+exports.mintRawCandidate = mintRawCandidate;
+exports.resolveDeclaredCandidate = resolveDeclaredCandidate;
+function satisfiesRequirements(route, flags, searchAvailable) {
+    for (const requirement of route.require) {
+        switch (requirement) {
+            case "schema_conformant":
+                // The native rung demands native strict enforcement; the json_mode
+                // rung accepts either mechanism (a native-capable model still serves
+                // a json_mode route).
+                if (route.policy.json === "native") {
+                    if (!flags.has("structured_native"))
+                        return false;
+                }
+                else if (!flags.has("structured_native") && !flags.has("json_mode")) {
+                    return false;
+                }
+                break;
+            case "grounded":
+                // Phase 3 WS3: a configured search provider satisfies `grounded` for
+                // candidates without native grounding — the run loop orchestrates
+                // search-and-inject for them.
+                if (!flags.has("grounded_native") && !searchAvailable)
+                    return false;
+                break;
+            case "trace_visible":
+                // Phase 3 WS6: reasoning-observability — the model's chain of thought
+                // is exposed to the caller (regulated/audit buyers hard-require this).
+                if (!flags.has("trace_visible"))
+                    return false;
+                break;
+            case "zero_retention":
+                // G-3: opt-in data-governance filter. Route only to endpoints the
+                // credential-scoped registry facts designate zero-retention (claims.ts
+                // → facts.ts materializes the flag under the managed/any scope). A hard
+                // capability filter exactly like trace_visible; the empty-set case falls
+                // through to the existing no-eligible-candidate path (fail-closed — never
+                // a silent non-ZDR dispatch). The claim ceiling: "route only to
+                // zero-retention–designated endpoints," never "verified non-retention."
+                if (!flags.has("zero_retention"))
+                    return false;
+                break;
+        }
+    }
+    return true;
+}
+function resolveCandidates(route, capabilities, costUsdPerMTok, searchAvailable = false, filter, shadowWarmth) {
+    // Filter order (spec §4.1): provider only → provider ignore → capability+ZDR
+    // → maxPrice → prefer:[cost]. When `filter` is absent every step is a no-op,
+    // so the path is byte-for-byte the pre-G-2 behavior (back-compat).
+    let pool = route.candidates;
+    if (filter?.only && filter.only.length > 0) {
+        const only = new Set(filter.only);
+        pool = pool.filter((c) => only.has(c.provider));
+    }
+    if (filter?.ignore && filter.ignore.length > 0) {
+        const ignore = new Set(filter.ignore);
+        pool = pool.filter((c) => !ignore.has(c.provider));
+    }
+    let eligible = pool.filter((c) => satisfiesRequirements(route, capabilities(c.provider, c.model), searchAvailable));
+    if (filter?.maxPriceUsdPerMTok != null) {
+        const cap = filter.maxPriceUsdPerMTok;
+        // Unknown cost + a ceiling set → DROP (fail-closed: we can't prove it is
+        // under the cap; same stance as the envelope on unpriced models).
+        eligible = eligible.filter((c) => {
+            const usd = costUsdPerMTok(c.provider, c.model);
+            return usd !== null && usd <= cap;
+        });
+    }
+    // prefer: [cost] — ascending, unknown cost sorts last, stable otherwise.
+    // "latency" is advisory in Phase 1 (no probe data): declared order stands.
+    const ordered = [...eligible];
+    if (route.prefer.includes("cost")) {
+        const cost = (c) => {
+            const usd = costUsdPerMTok(c.provider, c.model);
+            return usd === null ? Number.POSITIVE_INFINITY : usd;
+        };
+        ordered.sort((a, b) => cost(a) - cost(b));
+        // SHADOW MODE (spec §5.5, step 8): compute what ordering by cache-ADJUSTED
+        // effective cost would recommend, log chosen-vs-recommended, and DO NOTHING
+        // ELSE. `ordered` (the list-cost order) is what we return — warmth never
+        // flips a route this mission. A no-op when `shadowWarmth` is absent, so the
+        // returned order is byte-identical to the pre-WS-B resolver.
+        //
+        // WRAPPED so shadow-mode is STRICTLY non-interfering: this is the actuation
+        // path (the only CandidateRef minter). A throwing warmth/log callback is a
+        // shadow-observation bug and must NEVER take down live candidate resolution
+        // — swallow it. `ordered` is already fixed above; nothing here can change it.
+        if (shadowWarmth !== undefined) {
+            try {
+                const effCost = (c) => {
+                    const usd = shadowWarmth.effectiveCostUsdPerMTok(c.provider, c.model);
+                    return usd === null ? Number.POSITIVE_INFINITY : usd;
+                };
+                const recommended = [...eligible].sort((a, b) => effCost(a) - effCost(b));
+                const same = recommended.length === ordered.length &&
+                    recommended.every((c, i) => c.provider === ordered[i].provider && c.model === ordered[i].model);
+                shadowWarmth.log({
+                    route: route.route,
+                    chosen: ordered.map((c) => ({ provider: c.provider, model: c.model })),
+                    recommended: recommended.map((c) => ({ provider: c.provider, model: c.model })),
+                    diverged: !same,
+                });
+            }
+            catch {
+                // Shadow observation failed — intentionally ignored. Routing proceeds on
+                // the list-cost order exactly as if no warmth had been supplied.
+            }
+        }
+    }
+    // THE brand site — the only place in the codebase a CandidateRef may be
+    // minted. The cast below is the single sanctioned exception to the
+    // "no `as CandidateRef`" grep (scoped to run/resolve.ts in CI).
+    const refs = ordered.map((c) => Object.freeze({ provider: c.provider, model: c.model }));
+    let index = 0;
+    return {
+        next() {
+            return index < refs.length ? refs[index++] : null;
+        },
+    };
+}
+/**
+ * Per-run requirement opt-ins (G-3). A caller can demand zero-retention routing
+ * for a single run without editing the route bundle: `zero_retention` is unioned
+ * into the effective `require`, so the existing satisfiesRequirements filter, the
+ * no-eligible-candidate message, and the fail-closed empty-set path all apply
+ * unchanged. Additive only — a run opts INTO a stricter requirement, never OUT of
+ * a route's declared one (opting out would be a governance downgrade).
+ */
+function applyRunRequirements(route, zeroRetention) {
+    if (!zeroRetention || route.require.includes("zero_retention"))
+        return route;
+    return Object.freeze({
+        ...route,
+        require: Object.freeze([...route.require, "zero_retention"]),
+    });
+}
+/** Map a run's RunOptions to a CandidateFilter (G-2), or undefined when no knob
+ * is set — so the resolver takes the byte-identical pre-G-2 path (back-compat). */
+function candidateFilterFromOptions(opts) {
+    const only = opts.providers?.only;
+    const ignore = opts.providers?.ignore;
+    const max = opts.maxPriceUsdPerMTok;
+    if (max == null && (only?.length ?? 0) === 0 && (ignore?.length ?? 0) === 0)
+        return undefined;
+    return {
+        ...(max != null ? { maxPriceUsdPerMTok: max } : {}),
+        ...(only ? { only } : {}),
+        ...(ignore ? { ignore } : {}),
+    };
+}
+/** A human-readable suffix naming the binding request-time filters, for the
+ * existing no-eligible-candidate error (spec §4.3 — explainability, not a new
+ * error class). Empty when no filter is set. */
+function filterSummary(opts) {
+    const parts = [];
+    if (opts.maxPriceUsdPerMTok != null)
+        parts.push(`maxPrice ≤ $${opts.maxPriceUsdPerMTok}/MTok`);
+    if (opts.providers?.only?.length)
+        parts.push(`only=[${opts.providers.only.join(", ")}]`);
+    if (opts.providers?.ignore?.length)
+        parts.push(`ignore=[${opts.providers.ignore.join(", ")}]`);
+    return parts.length > 0 ? ` and request filters {${parts.join("; ")}}` : "";
+}
+/**
+ * Mint a CandidateRef for the RAW LANE (http-gateway spec §4.2) — a
+ * `provider/model` the caller named explicitly, dispatched at zero margin on
+ * the caller's own BYOK key with NO route and NO verified pipeline.
+ *
+ * The candidate-set invariant guards against substituting a model outside a
+ * ROUTE's declared list; a route-free, explicitly-named passthrough is outside
+ * that invariant's scope by construction (there is no list to escape). This is
+ * the ONE sanctioned brand site for it, so the "no `as CandidateRef`" grep stays
+ * clean and the brand stays centralized here. The authorization that replaces
+ * route membership lives server-side: the raw lane dispatches only after
+ * `resolveProviderKeyForCall` returns a BYOK key fail-closed (spec §4.2).
+ */
+function mintRawCandidate(provider, model) {
+    return Object.freeze({ provider, model });
+}
+/**
+ * Mint a CandidateRef for a SPECIFIC declared candidate (the repair rung's
+ * designated repair model — loader-validated to be in the route's candidate
+ * list; re-checked here). Same brand site, same sanctioned-cast scope.
+ */
+function resolveDeclaredCandidate(route, spec) {
+    const declared = route.candidates.some((c) => c.provider === spec.provider && c.model === spec.model);
+    if (!declared)
+        return null;
+    return Object.freeze({ provider: spec.provider, model: spec.model });
+}

package/dist/run/retry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Per-class retry accounting — spec §2, plan §4. Budgets are NON-FUNGIBLE:
+ * exhausting one class never consumes another. Terminal classes
+ * (budget_exhausted, invariant_violation) are never retried.
+ */
+import type { FailureClass } from "../types/failures";
+import type { RoutePolicy } from "../types/route";
+export interface RetryLedger {
+    /** True if a retry is permitted for this class (and consumes one unit). */
+    consume(cls: FailureClass): boolean;
+    remaining(cls: FailureClass): number;
+    snapshot(): Partial<Record<FailureClass, number>>;
+    /** Backoff before the retry the most recent consume() granted — per-class:
+     * exponential for capacity_shed (30s base, mirrors the production flex
+     * backoff ladder) and network (1s base); immediate for content classes. */
+    delayMs(cls: FailureClass): number;
+}
+export declare function createRetryLedger(policy: RoutePolicy): RetryLedger;
+//# sourceMappingURL=retry.d.ts.map

package/dist/run/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/run/retry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC;IACpC,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAAC;IACrC,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD;;+EAE2E;IAC3E,OAAO,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAAC;CACpC;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAsClE"}

package/dist/run/retry.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Per-class retry accounting — spec §2, plan §4. Budgets are NON-FUNGIBLE:
+ * exhausting one class never consumes another. Terminal classes
+ * (budget_exhausted, invariant_violation) are never retried.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRetryLedger = createRetryLedger;
+const failures_1 = require("../types/failures");
+const CAPACITY_BACKOFF_MS = [30000, 60000, 120000, 240000];
+const NETWORK_BACKOFF_BASE_MS = 1000;
+const NETWORK_BACKOFF_CAP_MS = 30000;
+function createRetryLedger(policy) {
+    const used = new Map();
+    function budget(cls) {
+        return policy.retries[cls] ?? 0;
+    }
+    return {
+        consume(cls) {
+            if (failures_1.TERMINAL_CLASSES.has(cls))
+                return false;
+            const attemptsUsed = used.get(cls) ?? 0;
+            if (attemptsUsed >= budget(cls))
+                return false;
+            used.set(cls, attemptsUsed + 1);
+            return true;
+        },
+        remaining(cls) {
+            if (failures_1.TERMINAL_CLASSES.has(cls))
+                return 0;
+            return Math.max(0, budget(cls) - (used.get(cls) ?? 0));
+        },
+        snapshot() {
+            const out = {};
+            for (const [cls, n] of used)
+                out[cls] = n;
+            return out;
+        },
+        delayMs(cls) {
+            const attempt = Math.max(0, (used.get(cls) ?? 1) - 1);
+            if (cls === "capacity_shed") {
+                return CAPACITY_BACKOFF_MS[Math.min(attempt, CAPACITY_BACKOFF_MS.length - 1)];
+            }
+            if (cls === "network") {
+                return Math.min(NETWORK_BACKOFF_BASE_MS * 2 ** attempt, NETWORK_BACKOFF_CAP_MS);
+            }
+            return 0;
+        },
+    };
+}

package/dist/run/run.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The run loop — spec §4, plan §4/step 6. State machine:
+ *   resolve → render → (envelope check) → dispatch → validate
+ *     → retry per failure class | advance candidate | fail typed | succeed
+ *   → record telemetry on every INFERENCE exit path (RouteConfigError exits
+ *     record nothing by design — config errors precede any dispatch; C1
+ *     ruling 2 / finding F3).
+ */
+import type { LoadedRoutes } from "../routes/loader";
+import type { ProviderAdapter } from "../types/provider";
+import type { RigManifest } from "../routes/manifest";
+import type { RunOptions, RunResult } from "../types/route";
+import type { TelemetryStore } from "../types/telemetry";
+import type { CaptureStore } from "../telemetry/capture";
+import type { CapabilityLookup } from "./resolve";
+import type { SearchProvider } from "./grounding";
+import type { StreamDeltaSink } from "./dispatch";
+import type { TaskSettingsResolver } from "../settings/task-settings";
+export interface RunDeps {
+    readonly routes: LoadedRoutes;
+    readonly adapters: ReadonlyMap<string, ProviderAdapter>;
+    readonly telemetry: TelemetryStore;
+    readonly capabilities: CapabilityLookup;
+    /** Budget for envelopes first opened by this rig (see envelope.ts default). */
+    readonly envelopeBudgetUsd?: number;
+    /** Addendum A1: USD per million tokens charged against an ACTIVE envelope
+     * when a model has no pricing entry — envelopes fail closed, never free.
+     * Deliberately generous-high by default. */
+    readonly unpricedRateUsdPerMTok?: number;
+    /** Rig manifest (declared dimensions) — null/omitted when no rig.yaml. */
+    readonly manifest?: RigManifest | null;
+    /** Local-only capture store (Phase 3 WS4) — writes gated per route by the
+     * bundle's `capture: true`; null/omitted disables capture entirely. */
+    readonly captures?: CaptureStore | null;
+    /** Search provider for the grounding-inject rung (Phase 3 WS3) —
+     * null/omitted means `require: grounded` resolves natively-grounded
+     * candidates only. */
+    readonly search?: SearchProvider | null;
+    /** Injectable backoff sleep — tests pass a no-op. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** Streaming side-channel (G-1/G-5 Phase A). When set AND the serving
+     * adapter can stream, the primary attempt forwards raw text deltas here as
+     * they arrive; the buffered terminal result still drives validation/telemetry
+     * unchanged. `rig.runStream()` wires this; `rig.run()` leaves it undefined. */
+    readonly onStreamDelta?: StreamDeltaSink;
+    /** Control-plane task-settings resolver (settings-plane §1.5) — present only
+     * in api mode. The capture-WRITE gate consults it: `effectiveCapture` lets a
+     * control-plane flip WIN over the YAML `capture:` flag (a console flip turns
+     * capture on/off with no redeploy), and the task's scrub setting governs
+     * content before a capture row is written. null/omitted = local-only (the
+     * YAML flag governs, no per-task scrub policy). */
+    readonly settings?: TaskSettingsResolver | null;
+}
+export declare function run(deps: RunDeps, routeName: string, opts: RunOptions): Promise<RunResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAMrD,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,mBAAmB,CAAC;AAGvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAsC,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAQlD,OAAO,KAAK,EAAE,cAAc,EAAoC,MAAM,aAAa,CAAC;AASpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC,+EAA+E;IAC/E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;gDAE4C;IAC5C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC;2EACuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACxC;;0BAEsB;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;mFAG+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,eAAe,CAAC;IACzC;;;;;uDAKmD;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACjD;AAsED,wBAAsB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAoiBhG"}