modelrig 0.9.0 → 0.10.0

package/dist/run/run.js

@@ -8,6 +8,8 @@
  *     ruling 2 / finding F3).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_DIRECTIVE = void 0;
+exports.userTurnFor = userTurnFor;
 exports.run = run;
 const loader_1 = require("../routes/loader");
 const serveability_1 = require("../routes/serveability");
@@ -18,9 +20,12 @@ const failures_1 = require("../types/failures");
 const manifest_1 = require("../routes/manifest");
 const resolve_1 = require("./resolve");
 const variant_1 = require("./variant");
+const resolve_destination_1 = require("./resolve-destination");
+const serve_client_1 = require("../gateway/serve-client");
 const envelope_1 = require("./envelope");
 const retry_1 = require("./retry");
 const repair_1 = require("./repair");
+const repair_attempt_1 = require("./repair-attempt");
 const grounding_1 = require("./grounding");
 const validate_1 = require("./validate");
 const dispatch_1 = require("./dispatch");
@@ -34,10 +39,18 @@ const capture_write_1 = require("./capture-write");
 /** Phase 1 prompt convention: the bundle's system template carries the whole
  * task (constitution, data, step instructions); the user turn is a terse
  * trigger. Providers treat long system prompts + short user turns well, and
- * it keeps the single-template bundle contract of spec §3. */
-const USER_DIRECTIVE = "Produce the required output now, following the system instructions exactly.";
-/** User turn for repair calls (WS2) — same terse-trigger convention. */
-const REPAIR_DIRECTIVE = "Produce the corrected JSON object now, following the system instructions exactly.";
+ * it keeps the single-template bundle contract of spec §3. Issue #5 (R1): a
+ * route that declares `prompt.user` replaces this trigger with its rendered
+ * user template — the per-call delta a cache handle cannot carry in the system
+ * slot (see `userTurnFor`). */
+exports.USER_DIRECTIVE = "Produce the required output now, following the system instructions exactly.";
+/** The user turn for one primary attempt (issue #5, R1): the route's rendered
+ * `prompt.user` template when declared — same variables, capability
+ * conditionals and `x-trust` removal as the system template — else the fixed
+ * trigger (byte-identical to pre-R1). Pure; exported for the run tests. */
+function userTurnFor(route, ctx) {
+    return route.userTemplate === undefined ? exports.USER_DIRECTIVE : (0, template_1.renderTemplate)(route.userTemplate, ctx);
+}
 /** prefer:[cost] ordering metric — combined input+output USD per million
  * tokens from the pricing snapshot; null (unknown) sorts last in resolve. */
 function costPerMTok(provider, model) {
@@ -46,13 +59,14 @@ function costPerMTok(provider, model) {
         return null;
     return (pricing.inputUsdPerTok + pricing.outputUsdPerTok) * 1000000;
 }
-const DEFAULT_SLEEP = (ms) => ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms));
+const DEFAULT_SLEEP = (ms) => (ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms)));
 async function run(deps, routeName, opts) {
     const mode = deps.mode ?? "live";
     const baseRoute = deps.routes.get(routeName);
     const variant = (0, variant_1.resolveVariant)(baseRoute, opts.variant, mode);
     const servedVariant = variant?.name ?? null;
     const route = (0, resolve_1.applyRunRequirements)((0, variant_1.effectiveRoute)(baseRoute, variant), opts.zeroRetention === true);
+    const destination = (0, resolve_destination_1.resolveDestination)(route.destination, opts.destination); // U2 (D-2): RunOptions > route > `direct`. Guard runs below, once the serving provider is resolved (U3).
     // RC-1: inside a run context the SDK stamps `run_id` (episodeKey, else run id)
     // when the caller passed none — the bridge between tags and the run graph.
     const runCtx = (0, run_context_1.getActiveRunContext)();
@@ -96,7 +110,7 @@ async function run(deps, routeName, opts) {
         autoStepKey,
         cache: opts.cache,
         droppedCacheHandle,
-        ladder, ...(opts.arm !== undefined ? { arm: opts.arm } : {}),
+        ladder, destination, ...(opts.arm !== undefined ? { arm: opts.arm } : {}),
     });
     function failRun(candidate, failure, latencyMs, screen) {
         // N1 (spec §5, SC-1b req 2): a pre-dispatch enforce `block` must still record
@@ -112,135 +126,14 @@ async function run(deps, routeName, opts) {
     // Repair rung (WS2): variant repair config wins over the route's; its own
     // budget, never fungible with the content_invalid class budget.
     const repairLedger = (0, repair_1.createRepairLedger)(variant?.repair ?? baseRoute.repair);
-    /** One repair dispatch. Returns {done} on schema-valid output, {invalid}
-     * with the newest output+errors for chaining, or null when the dispatch
-     * itself failed (adapter failure / unmintable repair candidate). */
-    async function attemptRepair(step, original, originalSystemPrompt, invalidText, errors) {
-        let repairCandidate;
-        let systemPrompt;
-        if (step.kind === "same_model") {
-            repairCandidate = original;
-            systemPrompt = originalSystemPrompt + (0, repair_1.repairFeedbackBlock)(errors);
-        }
-        else {
-            // Declare-first backstop (spec §4.4): the loader rejects a `trial` candidate
-            // as `repair_model`, but a programmatically-built bundle (runBundle) could
-            // bypass the loader — so refuse to mint a trial candidate for LIVE repair
-            // here too (the primary ladder's trial-drop has no repair-path equivalent).
-            if (mode === "live" &&
-                route.candidates.some((c) => c.provider === step.model.provider && c.model === step.model.model && c.trial === true)) {
-                return null;
-            }
-            // Brand stays in resolve.ts; loader validated repairModel ⊆ declared.
-            const minted = (0, resolve_1.resolveDeclaredCandidate)(route, step.model);
-            if (minted === null)
-                return null;
-            repairCandidate = minted;
-            systemPrompt = (0, repair_1.repairModelPrompt)(invalidText, errors, route.outputSchema);
-        }
-        const repairedBy = `${repairCandidate.provider}/${repairCandidate.model}`;
-        const adapter = deps.adapters.get(repairCandidate.provider);
-        if (adapter === undefined)
-            return null;
-        if (guard !== null) {
-            // A1: unpriced repair models fail closed exactly like primaries.
-            const breach = guard.precheck((0, cost_1.dispatchEstimateUsd)(repairCandidate.provider, repairCandidate.model, systemPrompt.length + REPAIR_DIRECTIVE.length, unpricedRatePerTok));
-            if (breach !== null) {
-                failRun(repairCandidate, breach, 0);
-            }
-        }
-        const started = Date.now();
-        const result = await adapter.call((0, dispatch_1.buildRepairAdapterRequest)(route, repairCandidate, systemPrompt, REPAIR_DIRECTIVE));
-        const latencyMs = Date.now() - started;
-        if (!result.ok) {
-            let cost = 0;
-            let repairFailurePricingMissing = false;
-            if (result.usage !== undefined) {
-                const settled = (0, cost_1.attemptCost)(repairCandidate.provider, repairCandidate.model, result.usage, unpricedRatePerTok);
-                cost = settled.costUsd;
-                repairFailurePricingMissing = settled.pricingMissing;
-                guard?.settle(settled.envelopeChargeUsd);
-            }
-            recordAttempt({
-                candidate: repairCandidate,
-                servedTier: result.usage?.servedTier ?? route.policy.tier,
-                tokensIn: result.usage?.tokensIn ?? 0,
-                tokensOut: result.usage?.tokensOut ?? 0,
-                tokensCached: result.usage?.tokensCached ?? 0,
-                tokensCacheWrite: result.usage?.tokensCacheWrite ?? 0,
-                tokensCacheWrite1h: result.usage?.tokensCacheWrite1h ?? 0,
-                costUsd: cost,
-                latencyMs,
-                ...(result.usage?.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
-                failure: result.failure,
-                repairedBy,
-                pricingMissing: repairFailurePricingMissing,
-                metaInputs: (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: REPAIR_DIRECTIVE, outputSchema: route.outputSchema, result }),
-            });
-            if (failures_1.TERMINAL_CLASSES.has(result.failure.class)) {
-                throw new failures_1.RigFailureError(result.failure);
-            }
-            return null;
-        }
-        const { costUsd, envelopeChargeUsd, pricingMissing: repairPricingMissing, } = (0, cost_1.attemptCost)(repairCandidate.provider, repairCandidate.model, result.usage, unpricedRatePerTok);
-        guard?.settle(envelopeChargeUsd);
-        const outcome = (0, validate_1.validateOutput)(route, result.text);
-        const failure = outcome.valid
-            ? null
-            : {
-                class: "content_invalid",
-                message: `repair output failed schema validation: ${outcome.errors.join("; ")}`,
-                provider: repairCandidate.provider,
-                model: repairCandidate.model,
-            };
-        const inferenceId = recordAttempt({
-            candidate: repairCandidate,
-            servedTier: result.usage.servedTier,
-            tokensIn: result.usage.tokensIn,
-            tokensOut: result.usage.tokensOut,
-            tokensCached: result.usage.tokensCached,
-            tokensCacheWrite: result.usage.tokensCacheWrite ?? 0,
-            tokensCacheWrite1h: result.usage.tokensCacheWrite1h ?? 0,
-            costUsd,
-            latencyMs,
-            ...(result.usage.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
-            failure,
-            repairedBy,
-            pricingMissing: repairPricingMissing,
-            metaInputs: (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: REPAIR_DIRECTIVE, outputSchema: route.outputSchema, result }),
-        });
-        captureAttempt(inferenceId, result.text);
-        if (!outcome.valid) {
-            return { invalid: { text: result.text, errors: outcome.errors } };
-        }
-        return {
-            done: {
-                output: outcome.parsed,
-                meta: {
-                    inferenceId,
-                    route: route.route,
-                    routeVersion: route.version,
-                    provider: repairCandidate.provider,
-                    model: repairCandidate.model,
-                    requestedTier: route.policy.tier,
-                    servedTier: result.usage.servedTier,
-                    tokensIn: result.usage.tokensIn,
-                    tokensOut: result.usage.tokensOut,
-                    tokensCached: result.usage.tokensCached,
-                    costEstimateUsd: costUsd,
-                    latencyMs,
-                    validated: true,
-                    attemptsByClass: ledger.snapshot(),
-                    servedVariant,
-                    repairedBy,
-                    callId: ladder.callId,
-                    ...(injectedSources !== null
-                        ? (0, grounding_1.groundingMeta)(result.text, injectedSources)
-                        : {}),
-                },
-            },
-        };
-    }
+    // Repair dispatch (WS2), extracted to ./repair-attempt.ts (U4) to keep run.ts
+    // under the LOC cap — a factory over this run's per-call state, mirroring
+    // createRecordAttempt. The run loop's current `injectedSources` is passed in at
+    // the call site (below) rather than closed over.
+    const attemptRepair = (0, repair_attempt_1.createAttemptRepair)({
+        adapters: deps.adapters, guard, unpricedRatePerTok, route, mode,
+        recordAttempt, captureAttempt, ledger, servedVariant, ladder, destination, failRun,
+    });
     const searchAvailable = deps.search !== undefined && deps.search !== null;
     const iter = (0, resolve_1.resolveCandidates)(route, deps.capabilities, costPerMTok, searchAvailable, (0, resolve_1.candidateFilterFromOptions)(opts), undefined, mode);
     // Advance the iterator AND publish the served candidate's index to the ladder,
@@ -255,6 +148,28 @@ async function run(deps, routeName, opts) {
         throw new loader_1.RouteConfigError(`route "${route.route}" has no eligible candidate — none of the declared candidates ` +
             `satisfy require=[${route.require.join(", ")}] with json=${route.policy.json}${(0, resolve_1.filterSummary)(opts)}`);
     }
+    (0, resolve_destination_1.assertDestinationServable)(destination, deps.managedServingEnabled === true, candidate.provider); // U3 (D-2): serving guard, now the provider is resolved. `direct` passes (byte-identical); `modelrig-served` passes only with the flag ON AND a served-capable provider, else throws pre-dispatch (no provider call, no telemetry row).
+    // K1 (managed-serving-keyless §2/§3): the resolved destination is
+    // `modelrig-served` AND the flag is on (the guard above just confirmed a
+    // served-capable provider) ⇒ serve the run through the HOSTED gateway on
+    // ModelRig's managed key (serve-client.ts), NOT the local adapter loop. The
+    // gateway resolves the org's mirrored bundle BY SLUG and drives the SAME
+    // verified pipeline server-side; its provenance (provider/model/cost/
+    // inference-id/validated) is carried into `RunResult.meta`. No local telemetry
+    // row is written here — the authoritative inference row lives server-side and
+    // `meta.inferenceId` points at it (anti-cheat: the SDK never double-meters a
+    // server-measured call). Fail-closed-but-discoverable inside serve-client; no
+    // silent fall back to `direct`/local key. `direct` (and flag-off) NEVER reach
+    // this branch, so every other path is byte-identical to today.
+    if (destination === "modelrig-served" && deps.managedServingEnabled === true) {
+        return (0, serve_client_1.serveViaGateway)({
+            route,
+            opts,
+            servedVariant,
+            serve: deps.serve,
+            ...(deps.serveFetch !== undefined ? { fetchFn: deps.serveFetch } : {}),
+        });
+    }
     let lastFailure = null;
     // Grounding-inject (WS3): one search per run, cached across candidates and
     // retries; cost accrues to the envelope and its own telemetry row.
@@ -287,10 +202,15 @@ async function run(deps, routeName, opts) {
         }
         // Render against the SERVING candidate's capability flags.
         const flags = deps.capabilities(candidate.provider, candidate.model);
-        let systemPrompt = (0, template_1.renderTemplate)(route.systemTemplate, {
+        const renderCtx = {
             variables: opts.input,
             capabilities: flags, variableTrust: (0, grounding_1.systemSlotRemoval)(route.variableTrust, opts.proxyTrust),
-        });
+        };
+        let systemPrompt = (0, template_1.renderTemplate)(route.systemTemplate, renderCtx);
+        // Issue #5 (R1): the user turn — the route's `prompt.user` when declared
+        // (rendered with the SAME context, so an untrusted variable is removed from
+        // it too and arrives via the spotlight block), else the fixed trigger.
+        const userPrompt = userTurnFor(route, renderCtx);
         // Variant augmentation (WS1): appended after capability-conditionals,
         // before json coaching — promptAppend first, then the reasoning scaffold.
         if (variant?.promptAppend !== undefined) {
@@ -354,7 +274,7 @@ async function run(deps, routeName, opts) {
         // pricing snapshot (prompt-length input + full output budget).
         if (guard !== null) {
             // A1: an unpriced model must never precheck at $0 (fail closed).
-            const breach = guard.precheck((0, cost_1.dispatchEstimateUsd)(candidate.provider, candidate.model, systemPrompt.length + USER_DIRECTIVE.length, unpricedRatePerTok));
+            const breach = guard.precheck((0, cost_1.dispatchEstimateUsd)(candidate.provider, candidate.model, systemPrompt.length + userPrompt.length, unpricedRatePerTok));
             if (breach !== null) {
                 failRun(candidate, breach, 0);
             }
@@ -366,7 +286,7 @@ async function run(deps, routeName, opts) {
         // + dispatch as ONE seam; both guards null ⇒ byte-identical. The untrusted
         // appends + screening live in the seam so run.ts stays under the LOC cap.
         const dispatched = await (0, dispatch_1.buildDispatchMaybeMasked)(adapter, {
-            route, candidate, systemPrompt, userDirective: USER_DIRECTIVE,
+            route, candidate, systemPrompt, userDirective: userPrompt,
             nativeGrounded, opts, suppressCustomerCache: suppressed, injectedSources,
         }, deps.onStreamDelta, guards);
         if (!dispatched.result.ok && (dispatched.maskRefusal !== undefined || dispatched.screenRefusal !== undefined))
@@ -387,12 +307,12 @@ async function run(deps, routeName, opts) {
                     attemptsByClass: ledger.snapshot(),
                     servedVariant,
                     pricingMissing,
-                    callId: ladder.callId,
-                    metaInputs: (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: USER_DIRECTIVE, outputSchema: route.outputSchema, result, tools: opts.tools }),
+                    callId: ladder.callId, destination,
+                    metaInputs: (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: userPrompt, outputSchema: route.outputSchema, outputKind: route.outputKind, result, tools: opts.tools }),
                 });
             }
             const outcome = (0, validate_1.validateOutput)(route, result.text);
-            const metaInputs = (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: USER_DIRECTIVE, outputSchema: route.outputSchema, result, tools: opts.tools });
+            const metaInputs = (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: userPrompt, outputSchema: route.outputSchema, outputKind: route.outputKind, result, tools: opts.tools });
             if (outcome.valid) {
                 // Q1 quality gate (spec §4.1): a schema-valid output must still clear the
                 // builder's bar before it is accepted. Tool-call turns never reach here;
@@ -425,19 +345,23 @@ async function run(deps, routeName, opts) {
                 captureAttempt(inferenceId, result.text);
                 const meta = (0, accept_1.buildSuccessMeta)({
                     inferenceId, route, candidate, usage: result.usage, costUsd, latencyMs,
-                    attemptsByClass: ledger.snapshot(), servedVariant, callId: ladder.callId,
+                    attemptsByClass: ledger.snapshot(), servedVariant, callId: ladder.callId, destination,
                     ...(injectedSources !== null ? (0, grounding_1.groundingMeta)(result.text, injectedSources) : {}),
                     ...(gate !== null ? { quality: { score: gate.score, verdict: "pass", judgedBy: null } } : {}),
                     ...(maskReceipt !== undefined ? { mask: maskReceipt } : {}), ...(screenReceipt !== undefined ? { screen: screenReceipt } : {}),
                 });
                 return { output, meta };
             }
-            // Schema-invalid output — a real (billed) attempt that failed.
+            // Schema-invalid output — a real (billed) attempt that failed. On an
+            // `output: text` route this is ONLY a declared min_chars miss (issue #1 —
+            // prose is never JSON-parsed); `fixHint` teaches when the CONTRACT is the
+            // cause (prose arriving on a json route ⇒ "declare output: text").
             const failure = {
                 class: "content_invalid",
                 message: `output failed schema validation: ${outcome.errors.join("; ")}`,
                 provider: candidate.provider,
                 model: candidate.model,
+                ...(outcome.fixHint !== undefined ? { fixHint: outcome.fixHint } : {}),
             };
             const invalidId = recordAttempt({
                 candidate,
@@ -458,13 +382,16 @@ async function run(deps, routeName, opts) {
             lastFailure = failure;
             // Repair rung (WS2): consumed BEFORE any content_invalid retry, from
             // its own budget. Chain: same-model error feedback, then the
-            // designated repair model on the newest invalid output.
-            if (route.outputSchema !== null) {
+            // designated repair model on the newest invalid output. JSON-only by
+            // construction: an `output: text` route has no schema (loader-enforced),
+            // so prose is never sent for JSON repair (issue #1) — a min_chars miss
+            // falls straight through to the content_invalid retry below.
+            if (route.outputSchema !== null && route.outputKind !== "text") {
                 let latestText = result.text;
                 let latestErrors = outcome.errors;
                 let repairStep = repairLedger.next();
                 while (repairStep !== null) {
-                    const repairOutcome = await attemptRepair(repairStep, candidate, systemPrompt, latestText, latestErrors);
+                    const repairOutcome = await attemptRepair(repairStep, candidate, systemPrompt, latestText, latestErrors, injectedSources, userPrompt);
                     if (repairOutcome?.done !== undefined) {
                         return repairOutcome.done;
                     }
@@ -505,7 +432,7 @@ async function run(deps, routeName, opts) {
             ...(result.usage?.ttfbMs !== undefined ? { ttfbMs: result.usage.ttfbMs } : {}),
             failure,
             pricingMissing: failurePricingMissing,
-            metaInputs: (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: USER_DIRECTIVE, outputSchema: route.outputSchema, result, tools: opts.tools }),
+            metaInputs: (0, dispatch_1.attemptMetaInputs)({ systemPrompt, userDirective: userPrompt, outputSchema: route.outputSchema, outputKind: route.outputKind, result, tools: opts.tools }),
         });
         if (failures_1.TERMINAL_CLASSES.has(failure.class)) {
             throw new failures_1.RigFailureError(failure);

package/dist/run/telemetry-row.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The ONE telemetry row builder both dispatch lanes feed (Unified Route U4,
+ * spec §4 U4 / plan U4 Step 1). Before U4 the persisted `inferences` row was
+ * assembled — and its `tagsJson` serialized — in FOUR places (research §1c):
+ * the routed recorder (`record-attempt.ts`), the raw recorder (`raw-finalize.ts`
+ * `recordRawRow`), the grounding-inject search-cost recorder (`dispatch.ts`
+ * `recordSearchCostRow`), and the native-search cost recorder
+ * (`raw-search-cost.ts`). A new cross-lane tag therefore cost four edits and
+ * drifted. This module collapses them onto one builder: every field is placed
+ * ONCE, and `tagsJson` is serialized in exactly ONE place — {@link stampRowTags}.
+ *
+ * BEHAVIOR-PRESERVING: `buildTelemetryRow` takes every field the caller already
+ * resolved (raw's former hardcodes — `routeVersion: 0`, `attemptsJson: "{}"`,
+ * `servedVariant: null`, `attemptSeq: 1`, `candidateIndex: 0`, `lane: "raw"` —
+ * are now EXPLICIT inputs, not literals hidden in one lane's recorder), so the
+ * emitted row is byte-identical to what each recorder produced before. `meta`
+ * and `mask` are placed only when the caller passes them (conditional spread),
+ * preserving each lane's exact key-presence (the search-cost row omits `meta`;
+ * the raw search-cost row sets `meta: null`).
+ *
+ * No route/registry/capability-gate dependency — types only — so the raw lane's
+ * no-hard-hot-path-dependency invariant is preserved when raw-finalize.ts and
+ * raw-search-cost.ts feed this builder.
+ */
+import type { FailureClass } from "../types/failures";
+import type { RunTags } from "../types/route";
+import type { AttemptMetaV1 } from "../telemetry/attempt-meta";
+import type { MaskReceipt } from "../mask/types";
+import type { TelemetryRow, TelemetryRung } from "../types/telemetry";
+/**
+ * THE single point where a telemetry row's `tags_json` is serialized (U4). Every
+ * row writer stamps its tags here, so a NEW cross-lane tag is a ONE-FILE edit:
+ * add it to the object assembled below and it appears on every lane's rows at
+ * once (proven by `telemetry-row.test.ts`). Key order is preserved exactly as
+ * the former inline sites had it — `{ ...baseTags, ...extraTags, rung }` — and
+ * `rung` is stamped LAST so a caller's `extraTags` can never override the
+ * recorder-owned rung.
+ */
+export declare function stampRowTags(baseTags: RunTags | Record<string, string>, rung: TelemetryRung, extraTags?: Record<string, string>): string;
+/** Inputs to the one row builder. Mirrors {@link TelemetryRow} field-for-field,
+ * except `tagsJson` is assembled from (`baseTags`, `extraTags?`, `rung`) via
+ * {@link stampRowTags}. `meta` / `mask` are placed only when present (undefined
+ * ⇒ the key is omitted), matching each caller's former shape exactly. */
+export interface TelemetryRowInput {
+    readonly id: string;
+    readonly route: string;
+    readonly routeVersion: number;
+    readonly provider: string;
+    readonly model: string;
+    readonly requestedTier: string;
+    readonly servedTier: string;
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly tokensCached: number;
+    readonly tokensCacheWrite: number;
+    readonly tokensCacheWrite1h: number;
+    readonly costEstimateUsd: number;
+    readonly latencyMs: number;
+    readonly ttfbMs: number | null;
+    readonly failureClass: FailureClass | null;
+    readonly attemptsJson: string;
+    /** Base tags stamped on the row (routed: `{...step, ...effectiveTags}`; raw:
+     * the lane tags incl. `lane:"raw"`). Serialized via {@link stampRowTags}. */
+    readonly baseTags: RunTags | Record<string, string>;
+    /** SDK-owned extra tags merged after `baseTags`, before `rung` (Q1 quality
+     * tags on the routed accept path). Absent on every other site. */
+    readonly extraTags?: Record<string, string>;
+    readonly rung: TelemetryRung;
+    readonly fingerprintCell: string | null;
+    readonly servedVariant: string | null;
+    readonly repairedBy: string | null;
+    readonly pricingMissing: boolean;
+    readonly cacheKey: string | null;
+    readonly prefixFingerprint: string | null;
+    readonly callId: string | null;
+    readonly attemptSeq: number | null;
+    readonly candidateIndex: number | null;
+    /** WI-1 attempt envelope. Placed only when present — the grounding-inject
+     * search-cost row omits it entirely; the raw search-cost row sets it to null. */
+    readonly meta?: AttemptMetaV1 | null;
+    /** CS-1 mask receipt. Placed only when present (routed masked route only). */
+    readonly mask?: MaskReceipt;
+}
+/**
+ * Assemble the persisted `inferences` row (U4). One object literal, one
+ * `tags_json` serialization ({@link stampRowTags}). `ts` is stamped here (all
+ * former recorders stamped `new Date().toISOString()` at row-build time — this
+ * is the same instant). `meta` / `mask` are placed only when the caller passes
+ * them, preserving each lane's exact key-presence.
+ */
+export declare function buildTelemetryRow(input: TelemetryRowInput): TelemetryRow;
+//# sourceMappingURL=telemetry-row.d.ts.map

package/dist/run/telemetry-row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-row.d.ts","sourceRoot":"","sources":["../../src/run/telemetry-row.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEtE;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1C,IAAI,EAAE,aAAa,EACnB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,MAAM,CAER;AAED;;;yEAGyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;iFAC6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD;sEACkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;qFACiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAiCxE"}

package/dist/run/telemetry-row.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * The ONE telemetry row builder both dispatch lanes feed (Unified Route U4,
+ * spec §4 U4 / plan U4 Step 1). Before U4 the persisted `inferences` row was
+ * assembled — and its `tagsJson` serialized — in FOUR places (research §1c):
+ * the routed recorder (`record-attempt.ts`), the raw recorder (`raw-finalize.ts`
+ * `recordRawRow`), the grounding-inject search-cost recorder (`dispatch.ts`
+ * `recordSearchCostRow`), and the native-search cost recorder
+ * (`raw-search-cost.ts`). A new cross-lane tag therefore cost four edits and
+ * drifted. This module collapses them onto one builder: every field is placed
+ * ONCE, and `tagsJson` is serialized in exactly ONE place — {@link stampRowTags}.
+ *
+ * BEHAVIOR-PRESERVING: `buildTelemetryRow` takes every field the caller already
+ * resolved (raw's former hardcodes — `routeVersion: 0`, `attemptsJson: "{}"`,
+ * `servedVariant: null`, `attemptSeq: 1`, `candidateIndex: 0`, `lane: "raw"` —
+ * are now EXPLICIT inputs, not literals hidden in one lane's recorder), so the
+ * emitted row is byte-identical to what each recorder produced before. `meta`
+ * and `mask` are placed only when the caller passes them (conditional spread),
+ * preserving each lane's exact key-presence (the search-cost row omits `meta`;
+ * the raw search-cost row sets `meta: null`).
+ *
+ * No route/registry/capability-gate dependency — types only — so the raw lane's
+ * no-hard-hot-path-dependency invariant is preserved when raw-finalize.ts and
+ * raw-search-cost.ts feed this builder.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stampRowTags = stampRowTags;
+exports.buildTelemetryRow = buildTelemetryRow;
+/**
+ * THE single point where a telemetry row's `tags_json` is serialized (U4). Every
+ * row writer stamps its tags here, so a NEW cross-lane tag is a ONE-FILE edit:
+ * add it to the object assembled below and it appears on every lane's rows at
+ * once (proven by `telemetry-row.test.ts`). Key order is preserved exactly as
+ * the former inline sites had it — `{ ...baseTags, ...extraTags, rung }` — and
+ * `rung` is stamped LAST so a caller's `extraTags` can never override the
+ * recorder-owned rung.
+ */
+function stampRowTags(baseTags, rung, extraTags) {
+    return JSON.stringify({ ...baseTags, ...(extraTags ?? {}), rung });
+}
+/**
+ * Assemble the persisted `inferences` row (U4). One object literal, one
+ * `tags_json` serialization ({@link stampRowTags}). `ts` is stamped here (all
+ * former recorders stamped `new Date().toISOString()` at row-build time — this
+ * is the same instant). `meta` / `mask` are placed only when the caller passes
+ * them, preserving each lane's exact key-presence.
+ */
+function buildTelemetryRow(input) {
+    return {
+        id: input.id,
+        ts: new Date().toISOString(),
+        route: input.route,
+        routeVersion: input.routeVersion,
+        provider: input.provider,
+        model: input.model,
+        requestedTier: input.requestedTier,
+        servedTier: input.servedTier,
+        tokensIn: input.tokensIn,
+        tokensOut: input.tokensOut,
+        tokensCached: input.tokensCached,
+        tokensCacheWrite: input.tokensCacheWrite,
+        tokensCacheWrite1h: input.tokensCacheWrite1h,
+        costEstimateUsd: input.costEstimateUsd,
+        latencyMs: input.latencyMs,
+        ttfbMs: input.ttfbMs,
+        failureClass: input.failureClass,
+        attemptsJson: input.attemptsJson,
+        tagsJson: stampRowTags(input.baseTags, input.rung, input.extraTags),
+        fingerprintCell: input.fingerprintCell,
+        servedVariant: input.servedVariant,
+        repairedBy: input.repairedBy,
+        pricingMissing: input.pricingMissing,
+        cacheKey: input.cacheKey,
+        prefixFingerprint: input.prefixFingerprint,
+        callId: input.callId,
+        attemptSeq: input.attemptSeq,
+        candidateIndex: input.candidateIndex,
+        ...(input.meta !== undefined ? { meta: input.meta } : {}),
+        ...(input.mask !== undefined ? { mask: input.mask } : {}),
+    };
+}

package/dist/run/validate.d.ts

@@ -2,14 +2,25 @@
  * Output validation — plan §4. Ajv compiled once per (route, version), cached.
  * Phase 1 checks schema conformance; value-accuracy gates arrive with the
  * bake-off in Phase 3.
+ *
+ * Two output kinds (issue #1, incident 2026-10-11):
+ *   json (default) — JSON.parse, then ajv against `outputSchema` when declared.
+ *     A schema-less json route still requires parseable JSON (unchanged).
+ *   text           — NO parse: `parsed` is the response string VERBATIM
+ *     (untrimmed). The only check is the declared `min_chars` floor.
  */
 import type { RouteBundle } from "../types/route";
 export interface ValidationOutcome {
     readonly valid: boolean;
     /** ajv error summaries, capped, human- and agent-readable. */
     readonly errors: readonly string[];
-    /** Parsed output when text was JSON-parseable (even if schema-invalid). */
+    /** Parsed output when text was JSON-parseable (even if schema-invalid); the
+     * verbatim string on an `output: text` route. */
     readonly parsed: unknown;
+    /** P4 (errors teach): the one-line fix for a failure whose cause is the
+     * route CONTRACT rather than the model — carried onto the `content_invalid`
+     * RigFailure as `fixHint`. */
+    readonly fixHint?: string;
 }
 export declare function validateOutput(route: RouteBundle, text: string): ValidationOutcome;
 //# sourceMappingURL=validate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/run/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAwBD,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CA6BlF"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/run/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAIlD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;qDACiD;IACjD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;kCAE8B;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAkDD,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CA+BlF"}

package/dist/run/validate.js

@@ -3,10 +3,38 @@
  * Output validation — plan §4. Ajv compiled once per (route, version), cached.
  * Phase 1 checks schema conformance; value-accuracy gates arrive with the
  * bake-off in Phase 3.
+ *
+ * Two output kinds (issue #1, incident 2026-10-11):
+ *   json (default) — JSON.parse, then ajv against `outputSchema` when declared.
+ *     A schema-less json route still requires parseable JSON (unchanged).
+ *   text           — NO parse: `parsed` is the response string VERBATIM
+ *     (untrimmed). The only check is the declared `min_chars` floor.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateOutput = validateOutput;
+const output_loader_1 = require("../routes/output-loader");
 const ajv_1 = require("./ajv");
+/** A prose-looking response on a json route: the incident shape (`# CoStar…`),
+ * or any body that does not even open like a JSON value. */
+function looksLikeProse(text) {
+    const first = text.trimStart().charAt(0);
+    return first !== "{" && first !== "[";
+}
+const PROSE_ON_JSON_ROUTE_HINT = "this route expects JSON (the default output kind). If the task returns prose/markdown, declare " +
+    `\`output: text\` in the route bundle — the response is then returned verbatim and never JSON-parsed. See ${output_loader_1.PROSE_DOCS_ANCHOR}`;
+function validateTextOutput(route, text) {
+    const floor = route.outputMinChars;
+    if (floor !== undefined && text.length < floor) {
+        return {
+            valid: false,
+            errors: [`output is ${text.length} characters, below the route's output.min_chars floor of ${floor}`],
+            parsed: text,
+            fixHint: "the model returned too little text for this prose route — the attempt is retried from the " +
+                "content_invalid budget (never JSON-repaired); lower output.min_chars if the floor is wrong",
+        };
+    }
+    return { valid: true, errors: [], parsed: text };
+}
 // Mirrors the production probe harness (packages/modelrig-probes/src/harness.ts):
 // an Ajv-2020 instance with the draft-07 meta added for back-compat — the two
 // must enforce identically, or a fixture would score differently than it serves.
@@ -26,6 +54,8 @@ function validatorFor(route) {
     return compiled;
 }
 function validateOutput(route, text) {
+    if (route.outputKind === "text")
+        return validateTextOutput(route, text); // issue #1: prose is never parsed
     let parsed;
     try {
         parsed = JSON.parse(text);
@@ -35,6 +65,7 @@ function validateOutput(route, text) {
             valid: false,
             errors: [`output is not valid JSON: ${err.message}`],
             parsed: undefined,
+            ...(looksLikeProse(text) ? { fixHint: PROSE_ON_JSON_ROUTE_HINT } : {}),
         };
     }
     if (route.outputSchema === null) {