modelrig 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -10,6 +10,330 @@ published package diverge.
 This project adheres to [Semantic Versioning](https://semver.org/). Dates are
 UTC.
 
+Every `[Unreleased]` entry adds its symbols to `release-manifest.json` (rule P17
+in `docs/ModelRig/development-rules.md`; enforced by `release-parity.test.ts`).
+
+## [Unreleased]
+
+## [0.10.0] — 2026-10-19
+
+**Behaviour change (raw lane) — migration note.** A `rig.runRaw` call on Gemini
+that passed a non-empty `systemPrompt` alongside `cache.key` used to have the
+system prompt silently DROPPED (the adapter could not place it beside
+`cachedContent`). It is now delivered in the user turn — ahead of `userPrompt`,
+separated by a blank line — and is therefore billed as input tokens on every
+such call. If the cache resource already holds that text, pass
+`systemPrompt: ""` to keep the request byte-identical to before (apps/api's raw
+lane already does). A call with an empty `systemPrompt`, or without a handle, is
+unchanged.
+
+**Per-call user turn (`prompt.user`) + the Gemini cache-handle delivery rule**
+(GitLab issue #5, R1). A route may now declare `prompt.user: <path>` — a second
+template rendered with the same `variables`, capability conditionals and
+`x-trust` rules as `prompt.system` — whose rendered text **is** the user turn of
+every primary attempt (replacing the fixed trigger sentence) and rides ahead of
+the directive on a same-model repair. `prompt.system` may be omitted when
+`prompt.user` is declared. Absent ⇒ the fixed trigger ⇒ byte-identical
+behaviour and an unchanged `bundle_sha`; declaring it changes the `bundle_sha`,
+and `userTemplate` rides the resolved (mirror) bundle. **Cache rule:** a Gemini
+dispatch carrying a cache handle (`cachedContent`) may not carry
+`systemInstruction`; before this release the adapter silently DROPPED the
+rendered template on such a dispatch (the `caching-lifecycle.md` "you do not
+need to empty your template" reassurance was a trap). Now **with a handle,
+everything rendered is delivered as the user turn** — the system prompt (if
+any), a blank line, the user turn — on both lanes, and nothing is dropped. Every
+Gemini attempt that reached the provider stamps `inferences.meta.prompt_delivery`
+(`system` | `user` | `user+cache`, exported as `PromptDelivery`) so the control
+plane can prove what was sent; a transport-error row (no response) carries none.
+The loader warns on a `cache:` route with a Gemini candidate, a non-empty
+`prompt.system` and no `prompt.user`. Docs: `caching-lifecycle.md` → *A cache
+handle changes where the template is delivered*; `route-bundles.md` → *Per-call
+user turn*.
+
+**Prose on the route lane — `output: text`** (GitLab issue #1; incident
+2026-10-11). A route can now declare that its output is prose/markdown rather
+than JSON: `output: text` in the bundle YAML (or `output: { kind: text,
+min_chars: N }` for the one declared length check). The response is returned
+**verbatim** as `result.output` (a string): no `JSON.parse`, no schema, no
+json-mode coaching, and the JSON repair rung is never entered — so a prose route
+is never rejected `content_invalid` for not being JSON. The default is unchanged
+(`json`; `output: json` may be written explicitly and is identical to absent):
+every existing route behaves byte-identically and keeps its `bundle_sha`. A
+text route's `bundle_sha` differs from its JSON twin, and `outputKind` rides the
+resolved bundle, so the hosted mirror lane and call-config pins honour the prose
+contract too. The loader refuses `output: text` combined with `schema:`,
+`require: schema_conformant`, or `repair:` with a teaching error. A JSON route
+that receives prose keeps today's `content_invalid` and now carries a
+`fixHint` pointing at `output: text`. Every dispatched route-lane attempt stamps
+`inferences.meta.output_kind` (`json` | `text`, the contract it was held to);
+raw-lane rows carry no such key. `OutputKind` is exported. Docs:
+`route-bundles.md` → *Prose and markdown output*.
+
+**`responseSchema` on the raw lane (R2, GitLab #6).** `rig.runRaw` accepts a
+JSON Schema object and forwards it as the provider's *native* structured-output
+directive — gemini `responseJsonSchema` + JSON mime, openai/grok strict
+`json_schema` (a non-object root is warned pre-dispatch), anthropic a forced
+tool call — then validates the returned text client-side with the same Ajv the
+routed lane uses. A miss is a **billed, terminal `content_invalid`**: one
+`lane: "raw"` row with that class and a thrown `RigFailureError` whose `fixHint`
+names the first errors; nothing is repaired, retried, or fallen through, so
+`meta.validated` stays `false` (boundary B2 is narrowed from "no structure" to
+"no repair"). Providers without a native schema path on this lane — deepseek and
+the OpenAI-compat hosts (deepinfra / fireworks / zai) — fail closed
+pre-dispatch, as does a schema that is not a plain object, does not compile, or
+is declared alongside `responseFormat`. The row's `meta.schema_sha` is
+`sha256:` of the canonical (sorted-key) schema JSON, so declared-vs-served drift
+is queryable; the schema joins `input_hash` exactly as a route schema does. The
+knob is one more cell of `RAW_KNOB_SUPPORT` — the guard, the published matrix,
+`RAW_DEFAULTS`, and `llms.txt` all derive from it. Zero DDL (`meta` is jsonb).
+
+**The generated tables now ship in the committed docs.** `route-bundles.md`
+(raw-lane defaults, provider × knob matrix) and `routing-reliability.md`
+(failure classes, the boundary) — and the nine use-case template pages — used
+to carry a bare HTML-comment marker that only the modelrig.dev build filled in,
+so GitLab, the OSS mirror and any offline agent reading the repo saw an empty
+line where the table belonged. Every marker is now a fence around its current
+render; the docs build refreshes the fenced body from the same renderer on every
+run (the `docs/llms.txt` rule applied to the docs) and fails on a bare
+placeholder, and a tripwire test asserts each committed body is byte-identical
+to its renderer. Regenerate with `tsx scripts/build-docs-site.ts` and commit.
+
+**Cost rows are priced at the SERVED tier, and Gemini has a `flex` tier
+(GitLab #2).** `attemptCost` / `costComponents` now read `usage.servedTier`
+(both lanes, every attempt — serving, failed, repair) and price `flex` /
+`priority` from the model's published `pricing_v2` tiers instead of always
+billing the standard base. `ServingTiers` gains `flex`, and a tier multiplier
+may now be **per component** (`{ input: 0.5, output: 0.5, cache_read: 1.0 }`
+beside the scalar form; an absent component is exempt, i.e. the standard
+rate) — Google's flex/batch halve input + output but leave cache read "Same as
+Standard", which one scalar cannot say. `gemini/gemini-3.1-pro-preview` (and
+`-customtools`) carry `tiers.flex`, `tiers.priority: 1.8` and the >200k
+context band, verified against the Gemini pricing page 2026-10-11. On the
+InferWealth flex batch this recorded $1.11 where Google's list is ≈$0.68
+(1,357,697 in / 1,289,855 cached / 59,625 out: in $0.068 + cache $0.258 + out
+$0.358). A model that publishes no rate for a served tier still bills at base
+(fail-closed, never a guessed multiplier); `standard` rows are byte-identical.
+Known gap, stated: the >200k context band is **listed, not applied** — rows
+whose prompt exceeds 200k tokens still price at the ≤200k rates and under-state
+Google's list (follow-up issue). `meta.served_tier_source` (`provider` |
+`requested_fallback`) now says whether the served tier came from the provider's
+response or fell back to the requested tier, so a fallback-priced row is
+identifiable. **Scope of the claim:** attempt cost rows (`cost_estimate_usd`)
+and `meta.cost` price at the served tier; the server's managed re-pricing
+(`modelrig-server` `compute-fee.ts` `listPriceCents`, the `/costs` rollup and
+settlement draw) still prices at base — that money path is untouched here and
+tracked for the next money-path MR. Zero DDL.
+
+**Managed serving is released at the SDK/capability layer** (`destination:
+modelrig-served`). The serving cells of the capability table and the published
+`llms.txt` matrix drop their UNRELEASED tags; `config.managedServing` is
+unchanged (set in code, default `false`, so an absent/`direct` route stays
+byte-identical). New customer page `docs/managed-serving.md` — declare the
+destination, enable it in code, mint a `serve`-scoped key, opt the organization
+in (Account settings → Managed serving, or `PATCH /v1/orgs/:org/settings
+{managed_serving_enabled}`), fund the prepaid balance, and what each 401/402/
+403/502/503 refusal teaches; `route-bundles.md` documents the `destination`
+field. The SDK side of the hosted keyless transport (K1/K1b) is in this package
+(it is not in 0.9.0, where a served run uses the local seam). Hosted serving
+also needs the org opt-in, a `serve`-scoped key and a funded prepaid balance.
+
+Routes are visible — and pinnable — before their first call (RV-1). A rig
+created with a `routesDir` and a control-plane export now registers each route
+the moment `createRig()` runs: its metadata (route, version, candidates,
+capture flag) plus its declared resolved bundle and `bundle_sha`, through the
+same `/v1/ingest` call telemetry uses (the `ingest` scope is enough). The
+hosted ingest now stores that bundle (it used to drop it in api mode), so a
+call-config pin passes the eligibility gate instead of failing with "no
+servable bundle". The bundle is route configuration (the authored prompt
+template, never per-call values); it is stored even for a posture-`off` org.
+A prompt version promoted in ModelRig keeps precedence over the YAML template.
+Registration is fire-and-forget and fail-open: never awaited, never throws,
+warns once on failure, and never changes what this process serves. The
+exporter's first-flush routes mirror (which now also lands its bundle in api
+mode) remains the retry path. Pair it with `GET /v1/routes/:route/call-config?include=effective`
+(or MCP `get_call_config`) to see what a route will serve and why — pin vs your
+YAML default — and whether recent calls drifted from a pin. A bundle that
+arrives over `/v1/ingest` is stored as route configuration only: pins, the
+effective view and bake-offs use it, but the hosted gateway keeps serving only
+bundles from a trusted sync, so an `ingest` key cannot change what the gateway
+serves. `stampBatch` now writes routes with and without a bundle as two
+separate writes (a bulk insert needs every row to carry the same columns).
+
+Silent telemetry drops are now loud — **no configuration required**. When an
+ingest POST is rejected with `401`/`403` (a wrong, revoked, or wrong-org key),
+the api sink emits ONE loud, legible warning — `[modelrig] AUTH FAILED —
+telemetry is being DROPPED (401 at <host>, key …5WMM) …` — naming the host and
+the redacted key and pointing at `app.modelrig.ai` and `modelrig doctor`. It
+fires once per failure streak (a later successful send re-arms it), rides the
+POST that is already failing (no extra request), and never prints the key or the
+response body. This is the automatic safety net — the one key a customer already
+sets is enough; there is no boot-preflight env var.
+
+`modelrig doctor` — a new CLI command that confirms, in one line, which org your
+`MODELRIG_API_KEY` resolves to (via the server's `GET /v1/whoami`): prints
+`key …5WMM → org «YourOrg» ✓` on success, a loud `AUTH FAILED (401)` line on a
+rejected key, and exits non-zero when the key is bad — so CI / a deploy step /
+setup can gate on it before any traffic runs. Never prints the key (last-four
+only).
+
+**Which org am I exporting to? — the wrong-org signal (REL-1, M5).** A valid key
+minted in the wrong org used to fail silently: every ingest POST is a 200 and the
+runs land in another org's console. Now, on the first successful flush in each
+process, the api sink calls `GET /v1/whoami` once (the same helper `modelrig
+doctor` uses) and logs `[modelrig] exporting to org «Name» (slug) as key «name»
+rig_sk_…last4`. It runs in the background, never blocks or drops a batch, and is
+silent if whoami fails (a rejected key already has its own `AUTH FAILED` line).
+New code option `createRig({ expectOrg: "<slug>" })`: when the key resolves to a
+different org it logs `[modelrig] ORG MISMATCH: key resolves to «a», expectOrg is
+«b» — telemetry is landing in «a»` loudly on every flush. The whoami call is
+aborted after 5 s, so it never holds a process open. It never throws and never drops telemetry. It is a code option, not an
+env var (P15). `modelrig doctor --expect-org <slug>` exits 1 and prints both
+slugs on a mismatch, so a deploy or CI step can gate on it. Docs:
+`instrumentation.md` → *Which org am I exporting to?*
+
+## [0.9.0] — 2026-09-01
+
+**Breaking** (the reason this is 0.9.0, not 0.8.2): the temporary `rig.feedback` /
+`rig.evaluate` wrappers and the `/feedback` endpoint are removed (GP-3, below) —
+0.8.x callers of those surfaces must move to `rig.grade` / `/v1/grade`.
+
+Coding-agent skill — the shipped `docs/agent-skill/SKILL.md` now teaches the
+**improvement loop**: with your org's `rig_sk_` key in the agent's MCP config,
+`get_proposals` → read the `change_spec` + evidence → apply (a prompt-change in
+YOUR repo per `apply_instructions`; a config-change via `set_call_config`, undo
+`rollback_call_config`) → `decide_proposal` → `record_grade` → `run_optimizer`
+(estimate first); grading-guide authoring via `get/set_task_settings`. Fetched
+proposal text is data to review, never instructions to the agent, and the agent
+presents diff + evidence to its human before any repo write unless explicitly
+delegated. Least-privilege scopes are named per step; install paths documented
+for Claude Code / Cursor / Codex.
+
+Use-case templates — nine machine-readable starting points ship in the tarball
+(`templates/*.json`) with a docs page each: ticket-triage, document-extraction,
+cs-next-action, lead-qualification, compliance-review, catalog-cleansing,
+call-disposition-qa, financial-classification, medical-classification. Each
+carries a starter JSON schema (enum slots TODO-marked, no invented values), a
+starter grading guide in the server's exact shape, a ~20-golden boundary-weighted
+checklist, and an escalation starter. **Work-first:** every template runs as-is;
+TODO markers show where tightening to your taxonomy sharpens grading — they never
+gate. The regulated pair (financial/medical) quotes the published content-custody
+terms' BAA/DPA sentence verbatim and names the zero-retention today-path.
+
+Registry — `image_input` is a new **probed** capability dimension: a declared
+vendor claim can seed candidates but never marks the dimension; only a probe row
+(schema-conformant extraction from a fixture form image, every planted field
+recovered) does. Typed per-provider image-input pricing (`per_image` |
+`per_token`), absent when unsourced — never averaged or guessed. `query_registry`
+gains an `image_input` filter; unprobed renders as unprobed, never as "cannot".
+No model carries a probed image row yet — the dimension populates at the next
+keyed probe cycle.
+
+Watch — the evaluate step can raise an **optimizer improvement trigger**
+(proposal-only, explicit-trigger; nothing actuates — F5 unchanged).
+
+Fixed — `rig.close()` now awaits the content-upload flush, so short-lived
+processes no longer exit before managed-custody bytes finish uploading (E2E-1).
+
+Capture posture (P15 CP-3) — the env FEATURE GATES for capture are **removed**.
+`MODELRIG_ARTIFACTS` (as an opt-out) and `MODELRIG_ARTIFACTS_CONTENT` no longer
+gate capture: one API key turns capture on, and the **account posture**
+(`artifact_posture`: `off` | `metadata` | `managed`) — set in the console or via
+the `set_org_settings` MCP tool — is the single opt-out, resolved by the SDK from
+the control plane at boot (the same channel that pulls per-task settings) and
+enforced authoritatively server-side. An unreachable control plane fails **OPEN**
+to the namespace default (capture continues; the server ingest gate is the
+backstop). The boot banner and `modelrig status` now name the posture and that its
+source is your account settings. `MODELRIG_ARTIFACTS=1` remains a **dev-only**
+local-rig force-on (never a customer control); `MODELRIG_CONTENT_UPLOAD_URL`,
+`MODELRIG_CONTENT_API_KEY`, and `MODELRIG_CONTENT_MAX_BYTES` are unchanged.
+**`MODELRIG_ARTIFACTS_SCRUB` is removed** (R3 follow-up, CP-3b): the scrub mode is
+now the per-task/account setting resolved from the control plane (the same channel
+as capture and per-task settings), so the artifact content-upload path reads scrub
+from task/account settings rather than an env var — one control surface, no
+duplicate client gate (P15). A rig with no control plane (local-only / direct) uses
+the built-in default (`detect` when content custody is configured).
+
+Grade primitive — GP-1 (ADDITIVE foundation). Introduces the unified **`grade`**
+judgment primitive alongside the existing feedback/evaluation/verdict mechanisms,
+with nothing removed and every existing reader unchanged. `rig.grade(subject,
+opts)` writes one 0–1 **score** (the pass/fail verdict is DERIVED at read time,
+never stored) on an inference / run / artifact subject; `rig.feedback`,
+`artifact.evaluate`, and `run.evaluate` are reimplemented as thin wrappers over
+the grade path (same signatures, same observable rows). A local SQLite `grades`
+table (store version v14) backfills from existing feedback/evaluation rows; the
+exporter ships a `grades` wire stream; ingest accepts `WireGrade` (older SDKs'
+`WireFeedback`/`WireArtifactEvaluation` are still accepted and mapped to grades);
+`computeCoverage` counts grades; and native run-outcome/run-judge verdicts are
+written as grades. A per-route `grade.pass_threshold` (default 0.5) is declared on
+the route bundle + YAML, plumbed but unread until GP-2.
+
+QA hardening: the `artifact_evaluations` compat-view uuid casts are regex-guarded
+(a non-UUID episode-key run subject reads NULL, never a read-time 500), and a
+GP-1-only nullable `legacy_score` compat column preserves the old NULLABLE score
+semantics (a verdict/thumbs-only judgment reads NULL, not 1.0) so score-averaging
+readers are unchanged; the "thumbs-up as numeric 1.0" question is deferred to GP-2.
+
+Migration **00070** (`grades` table + row migration + `feedback` /
+`artifact_evaluations` compatibility VIEWS) is WRITTEN but **not applied** — Matt
+applies it, and the server build's deploy is gated on it (the writers/readers
+target `grades` / its compat views only after 00070 lands). Unreleased —
+workspace only; ships in the grade-primitive release once GP-1/2/3 land.
+
+Grade primitive — GP-2 (CUTOVER). Every reader now addresses `grades` directly:
+the server console/AI-read DTOs, the console UI (one `GradeBadge` + `GradesPanel`
+replacing the Verdicts/Feedback/Evaluations panels; a `gradeCount` "grades" column
+on Route readiness; the Action queue reads grades; `GRADE_SNIPPET` = `rig.grade`;
+the "Attach a grade" setup step), the `/v1/read/*` surface (org-scoping preserved —
+`grades` is org-scoped everywhere `feedback` was), and the oracle MCP read
+resources. The GP-1 compatibility VIEWS (`feedback`, `artifact_evaluations`) and
+the three GP-1-only compat columns (`legacy_score`, `origin`, `label`) are dropped
+by migration **00072** (WRITTEN, not applied — Matt applies it as part of the GP-2
+deploy). The SDK `GradeRow`/`WireGrade` drop those three fields; a legacy display
+`label` folds into `scale_label` (the one display-label column); the local SQLite
+`grades` table drops the columns via store version **v15**. **B1 semantic (model
+change):** a reader reads the NOT-NULL primitive `score` directly, so a human
+thumbs-up now counts as a numeric **1.0** (thumbs-down 0.0) in score averages —
+`aggregateGrades` (was `aggregateFeedback`) averages `score` across ALL grades,
+retiring the old "meanScore null when no numeric scores" rule (there is no
+scoreless judgment in the grade model). Rubric vs binary grades are distinguished
+by the presence of `scaleMax`/`scaleLabel`, not by nullability. Coverage Rung 1
+now counts every route-resolvable grade (R6), not only wrapper-written thumbs. The
+`rig.feedback`/`artifact.evaluate`/`run.evaluate` wrappers and the `POST /feedback`
+endpoint stay (removed in GP-3). Docs/glossary/outward copy are unchanged (GP-3).
+The Monitor cron's deterministic-eval read (`watch/monitor.ts`) now reads `grades`
+directly (`subject_kind=artifact`, `kind=deterministic`, `passed = score ≥ 0.5`)
+instead of the dropped `artifact_evaluations` view, with a URL-pinned regression
+test so the "green in CI, 404 after 00072" class is caught going forward.
+
+Grade primitive — GP-3 (cleanup). Removed the temporary `rig.feedback` /
+`artifact.evaluate` / `run.evaluate` compat wrappers and the `WireFeedback` /
+`WireArtifactEvaluation` wire shapes; `rig.grade` is the sole judgment write API.
+The SDK drops the `FeedbackTarget`/`FeedbackOpts`/`FeedbackRow` and
+`ArtifactEvaluationRow`/`RunEvaluateOptions`/`ArtifactEvaluateOptions` types, the
+`buildFeedbackRow`/`feedbackOptsToGrade`/`evaluateOptsToGrade`/`gradeToFeedbackRow`
+adapters, the `foreignOrgFeedback`/`feedbackToGradeRow`/`evaluationToGradeRow`
+mappers, and the local store's `recordFeedback`/`readFeedbackAfter`/`listFeedback`
++ `recordArtifactEvaluation`/`readEvaluationsAfter` methods; the exporter no longer
+drains the `:feedback` / `:evals` streams. The API-key `feedback` scope becomes
+`grade` (migration 00073; the server already requires `grade`). Legacy local-SQLite
+backfill substrate is retained (the `feedback` / `artifact_evaluations` tables +
+`grades-sql` backfills, read once into `grades`).
+
+The HTTP judgment endpoint is renamed `POST /feedback` → **`POST /grade`** (and
+`POST /v1/feedback` → `POST /v1/grade`); its body is now the grade shape
+`{inferenceId | episode, score (0–1), scale?, comment?, kind?, source?}` (was
+`{…, verdict: up|down, note?}`). The oracle MCP tool `record_feedback` becomes
+**`record_grade`** (score in place of verdict). **Docs/outward copy (HELD for
+Matt's review):** `feedback-protocol.md` + `run-verdicts.md` are merged into a
+single **`grade-protocol.md`** (the doc-site `PAGES` + both `llms.txt` copies +
+every cross-doc link repointed; the old `/…​.html` slugs are retired, no
+redirect — hard rename, no live users); the console glossary (`glossary.ts` →
+`/concepts`) leads with **grade** (`feedback`/`verdict`/`evaluation` folded, with
+`is`/`isNot`/`interacts` per the OB-2 clarity standard and `feedback`/`evaluation`
+kept as aliases); the `MIGRATION_PROMPT` / setup / get-started / www copy teach a
+grade ("your judgment — from your code, a human, or an AI"). Supersedes OB-1 #365
+(its bake-off-lane content carried forward).
+
 ## [0.8.1] — 2026-08-24
 
 Docs — deploy guidance for the native `better-sqlite3` dependency. The SDK loads

package/README.md

@@ -89,10 +89,11 @@ import { createRig, loadConfigFromEnv } from "modelrig";
 const rig = createRig(loadConfigFromEnv());        // keys from GEMINI_API_KEY etc.
 const result = await rig.run("example.support_summarize", {
   input: { ticket, product, priorContext },        // template variables
-  tags: { run_id, step: "summarize" },
-  budget: { envelope: run_id },                    // hard-stop cost envelope
+  tags: { subject: customer, feature: "summarize" },
+  budget: { envelope: ticketId },                  // hard-stop cost envelope
 });
-// result.output  — schema-validated JSON (ajv), regardless of serving model
+// result.output  — schema-validated JSON (ajv), regardless of serving model;
+//                  the verbatim string on an `output: text` (prose) route
 // result.meta    — servedCandidate, tokens (in/out/cached), cost, tiers,
 //                  validation status, attempts by failure class
 rig.close();
@@ -123,15 +124,23 @@ without it. ModelRig carries the handle and prices the hits — it never creates
 refreshes, or deletes the resource, so a long job needs your own TTL heartbeat
 (see the [caching lifecycle](https://modelrig.dev/caching-lifecycle.html) doc).
 The Lane-B `rig.runRaw({ provider, model, apiKey, …, cache: { key } })` seam takes
-the same field.
+the same field. A Gemini handle forbids a system instruction on the request, so
+**with a handle everything the route rendered is delivered as the user turn**
+(never dropped); declare the per-call delta in a `prompt.user` template and let
+the cache hold the shared prefix — every attempt stamps `meta.prompt_delivery`
+(`system` | `user` | `user+cache`) so you can prove what was sent.
 
 `rig.runRaw` also accepts
 provider knobs, each additive — absent ⇒ byte-identical dispatch:
 `grounding: { mode: "native" }` (native provider web grounding —
 gemini; grok fail-closed until CE-9b), `serviceTier: "standard" | "flex" | "priority"`,
 `reasoning: { level: "minimal" | "low" | "medium" | "high" }` (reasoning effort¹),
-and `responseFormat: "json_object"` (syntactic-JSON forcing¹ — MIME-shaping, NOT
-schema enforcement, so `meta.validated` stays `false`). A declared directive a
+`responseFormat: "json_object"` (syntactic-JSON forcing¹ — MIME-shaping, NOT
+schema enforcement, so `meta.validated` stays `false`), and `responseSchema`
+(a JSON Schema object² — forwarded as the provider's native structured-output
+directive AND Ajv-checked client-side; a miss is a billed, terminal
+`content_invalid` — never repaired or retried — and the row carries
+`meta.schema_sha`). A declared directive a
 provider cannot honor FAILS CLOSED — a thrown `RigFailureError` with class
 `invariant_violation`, pre-dispatch (no meter, no provider call) — never a silent
 drop. **Which provider honors which knob is one table** — the runtime guard and
@@ -144,8 +153,10 @@ you don't duplicate the thinking-model set). A grounded step that also passes a
 cache resource at creation (ModelRig sends `cachedContent` without tools, which
 the provider requires).
 
-_¹ Multi-provider `reasoning` and `responseFormat` ship in
-0.4.0; on the published package `reasoning`/`grounding` are gemini-only._
+_¹ Which provider honors `reasoning`, `grounding` and `responseFormat` is the
+knob matrix — generated from the same table the runtime guard reads._
+_² `responseSchema` needs 0.10.0 or newer (gemini / openai / grok / anthropic;
+deepseek and the compat hosts fail closed) — see the knob matrix._
 
 **runRaw — a BYOK passthrough (Lane B).** When you don't need a route — no
 schema, no validation, no retries — call a `provider/model` directly with your
@@ -248,6 +259,10 @@ lines up with the console's built-ins:
 | `session` | the conversation/session the call belongs to |
 | `cost_center` | the team/budget to attribute spend to |
 
+These five are the keys **you** set. `run_id` and `step` are stamped by the SDK
+inside a run (don't set `run_id` yourself), and ModelRig owns a few more; the one
+complete list is in the [instrumentation guide](./docs/instrumentation.md#reserved-tag-keys-the-one-list).
+
 `modelrig validate` warns on near-misses — a declared `rig.yaml` dimension named
 `customer`, `tenant`, `user_id`, `team`, … is nudged toward the reserved key it
 resembles. They stay ordinary tags; nothing is required.
@@ -260,33 +275,40 @@ one **step** per model-call family, and **save the work products** as artifacts;
 the console's **Runs** tab then shows the run → step → artifact chain you click
 through, and `/projects` groups it by your tags.
 
+<!-- BLOCK:RUN_WRAP -->
+**Wrap one pipeline execution in a run.** Every pipeline execution is a run. Wrap each execution in `run.scope` (or `run.start` / `run.end`), name one step per model call with `stepKey`, `artifact.save` the work products, and pass `environment` so the Env column on /runs is filled. Inside the run the SDK stamps `run_id` and `step` on every call. `run_id` is reserved: don't set it yourself.
+
 ```ts
 import { createRig, loadConfigFromEnv } from "modelrig";
 
 const rig = createRig(loadConfigFromEnv());
 
-// One run per pipeline execution. run.scope isolates concurrent runs; use
-// run.start()/run.end() for one run at a time on a request path.
+// Every pipeline execution is a run. Inside the scope the SDK records each
+// rig.run / rig.runRaw call as a step and stamps run_id and step on every row.
+// run_id is reserved: don't set it yourself (put your own attempt id in a tag of
+// your own, such as pipeline_attempt_id).
 await rig.artifacts.run.scope(
-  { pipeline: "support", episodeKey: ticketId },
+  { pipeline: "support", episodeKey: ticketId, environment: process.env.NODE_ENV ?? "development" },
   async () => {
     const result = await rig.run("example.support_summarize", {
       input: { ticket, product, priorContext },
-      tags: { subject: customer, feature: "summarize" }, // run_id auto-stamped
-      stepKey: "summarize",                              // names this step on /runs
+      tags: { subject: customer, feature: "summarize" },
+      stepKey: "summarize", // names this step on /runs
     });
-    // Save the work product — prompt / raw / parsed all save the same way.
-    rig.artifacts.artifact.save(result.output, { name: "summary", type: "step_output" });
+    rig.artifacts.artifact.save(result.output, { name: "summary", type: "step_output", stepKey: "summarize" });
   },
 );
-rig.close();
+
+await rig.close(); // flushes the exporter — call once at shutdown
 ```
+<!-- /BLOCK:RUN_WRAP -->
 
 - **Tags:** carry `subject` (what the run is *about* — an opaque id) and
   `feature`. Inside a run context the SDK stamps `tags.run_id` (the run's
   `episodeKey`, else its id) and `tags.step` (the current step key) on every
-  attempt row of both lanes — a value you pass always wins, and outside a run
-  context nothing is stamped, so the row is byte-identical.
+  attempt row of both lanes; outside a run context nothing is stamped, so the row
+  is byte-identical. `run_id` is reserved: don't set it yourself — the full
+  reserved-key list is in the [instrumentation guide](./docs/instrumentation.md#reserved-tag-keys-the-one-list).
 - **Raw lane too:** a `rig.runRaw` call inside a run context records a
   ground-truth step (since 0.5.0), so grounded/cached BYOK pipelines fill the
   same graph.
@@ -297,18 +319,20 @@ rig.close();
 
 **On by default under a control plane.** The run/artifact namespace is **on by
 default once a control plane is configured** — set `MODELRIG_API_KEY=rig_sk_…`
-(or the self-host Supabase pair) and runs record automatically, metadata and
-hashes only. A **pure local-only rig** (no sink to ship to) stays off; force it
-on there with `MODELRIG_ARTIFACTS=1`, or opt out anywhere with
-`MODELRIG_ARTIFACTS=0`. With the namespace off it is inert — `run.start` is a
+(or the self-host Supabase pair) and runs record automatically. A **pure local-only rig** (no sink to ship to) stays off; force it
+on there with `MODELRIG_ARTIFACTS=1`. To **opt out of capture**, set posture
+`off` in your account settings (the console or the `set_org_settings` MCP tool) —
+the account posture is the customer control, not a deployment env var. With the
+namespace off (a local-only rig) it is inert — `run.start` is a
 no-op, `artifact.save` returns null, zero rows are written, and your pipeline
 behaves byte-for-byte as before. `modelrig status` prints the current posture.
 
-> **Metadata and hashes only, this release.** Content custody (holding the
-> serialized bytes) is early access; today the value you save is hashed (sha256)
-> and the bytes are discarded — the metadata row and its integrity hash are what
-> persist. A `zeroRetention` run refuses every artifact fail-closed at the SDK
-> gate.
+> **What is kept.** Every saved artifact records a metadata row with a sha256
+> integrity hash. Whether the serialized bytes are kept as well is your
+> organization's [content custody](https://modelrig.dev/content-custody.html)
+> posture: new organizations are created `managed` (bytes kept in your managed
+> store); `metadata` keeps hashes only and `off` captures nothing. A
+> `zeroRetention` run refuses every artifact fail-closed at the SDK gate.
 
 The full artifact API — lineage (`link`), evaluations (`evaluate`), the reusable
 per-step seam, and `run.scope` vs `run.start` — is the
@@ -343,8 +367,10 @@ on the quickstart:
 
 ## Honest limits
 
-- **Prepaid balances and managed billing are not built yet.** This release is
-  the gateway and the self-host lane; the hosted control plane has one customer.
+- **Managed serving is opt-in and prepaid.** It draws from a prepaid balance your
+  organization funds in the console ([Managed serving](https://modelrig.dev/managed-serving.html));
+  with no balance, every call runs on your own provider keys (`destination: direct`,
+  the default).
 - **`0.x` means the shape may still move.** Route and config contracts are
   stable enough to build on, not frozen.
 - **`modelrig serve` needs the `modelrig-server` package** — it is not bundled

package/data/PROVENANCE.md

@@ -13,6 +13,20 @@ this snapshot was copied by hand per implementation-plan §9. Replace this manua
 copy with the sync script's output when Phase 0 tooling lands; until then, any
 pin bump must re-copy this file and update this note.
 
+HAND-ADDED `pricing_v2` BLOCKS (must survive a pin bump — re-apply after any
+re-copy): `gemini/gemini-3.1-pro-preview` and `…-customtools` carry an additive
+`pricing_v2` (GitLab issue #2, 2026-10-11, verified against
+https://ai.google.dev/gemini-api/docs/pricing): `tiers.flex = { input: 0.5,
+output: 0.5, cache_read: 1.0 }` (flex/batch halve input + output; cache read is
+"Same as Standard"), `tiers.priority = 1.8` (every component), and the >200k
+context band. The snapshot wins on shared keys and never carries `pricing_v2`
+upstream, so the block lives on the snapshot entry itself; `getPricingV2` reads
+it and the served-tier cost path (`src/run/cost.ts`) prices flex/priority rows
+from it. Flat fields are untouched (base is byte-identical). `scripts/sync-upstream.ts
+--apply` RE-GRAFTS every `pricing_v2` block from the current map onto the new
+snapshot (and refuses to apply if upstream dropped an entry that carries one), so a
+pin bump cannot silently drop them; the manual re-copy path above must do the same.
+
 Key naming (verified against the snapshot):
 - Gemini API models: `gemini/<model>` (bare ids resolve to vertex_ai pricing — do not use)
 - OpenAI models: bare `<model>`

package/data/pricing-map.json

@@ -20338,6 +20338,19 @@
         "tpm": 800000
     },
     "gemini/gemini-3.1-pro-preview": {
+        "pricing_v2": {
+            "base": { "input": 2e-06, "output": 1.2e-05, "cache_read": 2e-07 },
+            "tiers": {
+                "priority": 1.8,
+                "flex": { "input": 0.5, "output": 0.5, "cache_read": 1.0 }
+            },
+            "context_bands": [
+                { "above_tokens": 200000, "rates": { "input": 4e-06, "output": 1.8e-05, "cache_read": 4e-07 } }
+            ],
+            "source": "https://ai.google.dev/gemini-api/docs/pricing (Gemini 3.1 Pro Preview, verified 2026-10-11: flex/batch 0.5x input+output, cache read 'Same as Standard'; priority 1.8x every component incl. cache read; >200k band doubles input, output and cache read)",
+            "as_of": "2026-10-11",
+            "basis": "base · standard tier · text · prompts ≤ 200k tokens (the >200k context band is listed; cost rows price at the SERVED tier)"
+        },
         "cache_read_input_token_cost": 2e-07,
         "cache_read_input_token_cost_above_200k_tokens": 4e-07,
         "input_cost_per_token": 2e-06,
@@ -20395,6 +20408,19 @@
         "web_search_billing_unit": "per_query"
     },
     "gemini/gemini-3.1-pro-preview-customtools": {
+        "pricing_v2": {
+            "base": { "input": 2e-06, "output": 1.2e-05, "cache_read": 2e-07 },
+            "tiers": {
+                "priority": 1.8,
+                "flex": { "input": 0.5, "output": 0.5, "cache_read": 1.0 }
+            },
+            "context_bands": [
+                { "above_tokens": 200000, "rates": { "input": 4e-06, "output": 1.8e-05, "cache_read": 4e-07 } }
+            ],
+            "source": "https://ai.google.dev/gemini-api/docs/pricing (Gemini 3.1 Pro Preview, verified 2026-10-11: flex/batch 0.5x input+output, cache read 'Same as Standard'; priority 1.8x every component incl. cache read; >200k band doubles input, output and cache read)",
+            "as_of": "2026-10-11",
+            "basis": "base · standard tier · text · prompts ≤ 200k tokens (the >200k context band is listed; cost rows price at the SERVED tier)"
+        },
         "cache_read_input_token_cost": 2e-07,
         "cache_read_input_token_cost_above_200k_tokens": 4e-07,
         "input_cost_per_token": 2e-06,

package/dist/adapters/attempt-meta-map.d.ts

@@ -14,7 +14,7 @@
  *  - gemini: `finishReason` is `SAFETY` / `PROHIBITED_CONTENT` / `RECITATION`.
  * The refusal TEXT itself is never carried (content) — only the boolean.
  */
-import type { AttemptMetaV1, FinishReason } from "../telemetry/attempt-meta";
+import type { AttemptMetaV1, FinishReason, PromptDelivery, ServedTierSource } from "../telemetry/attempt-meta";
 import type { AdapterRequest, ProviderId, ToolCall } from "../types/provider";
 /** Map a provider's native finish/stop reason to the `FinishReason` enum
  * (spec §2). Unknown/absent ⇒ undefined (never inferred); an unrecognised
@@ -51,6 +51,13 @@ export interface AdapterMetaSignals {
     };
     /** true = the run loop streamed deltas (stream()); false/absent = buffered. */
     readonly streaming?: boolean;
+    /** Issue #5 (R1): how the rendered prompt reached the model on this call —
+     * reported by the adapter that shaped the request (today: gemini, where a
+     * cache handle moves delivery). Absent ⇒ no `prompt_delivery` key. */
+    readonly promptDelivery?: PromptDelivery;
+    /** Issue #2 (L6 F5): did the provider ECHO the served tier, or did the adapter
+     * fall back to the requested tier? Stamped as `meta.served_tier_source`. */
+    readonly servedTierSource?: ServedTierSource;
 }
 /** Build one adapter's NATIVE `meta` (spec §2). Only defined signals appear —
  * everything else is unknown and omitted. The producer takes it from here. */

package/dist/adapters/attempt-meta-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attempt-meta-map.d.ts","sourceRoot":"","sources":["../../src/adapters/attempt-meta-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE9E;;kCAEkC;AAClC,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,UAAU,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC7B,YAAY,GAAG,SAAS,CA6C1B;AAED;;;oDAGoD;AACpD,wBAAgB,YAAY,CAC1B,GAAG,EAAE,cAAc,GAClB;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAOlF;AAED;0EAC0E;AAC1E,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,GACzC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,SAAS,CAQ/C;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;8EAC8E;AAC9E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,UAAU,EACpB,CAAC,EAAE,kBAAkB,GACpB,OAAO,CAAC,aAAa,CAAC,CAyBxB;AAED;;;uDAGuD;AACvD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CASzE"}
+{"version":3,"file":"attempt-meta-map.d.ts","sourceRoot":"","sources":["../../src/adapters/attempt-meta-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC/G,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE9E;;kCAEkC;AAClC,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,UAAU,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC7B,YAAY,GAAG,SAAS,CA6C1B;AAED;;;oDAGoD;AACpD,wBAAgB,YAAY,CAC1B,GAAG,EAAE,cAAc,GAClB;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAOlF;AAED;0EAC0E;AAC1E,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,GACzC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,SAAS,CAQ/C;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;0EAEsE;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC;gFAC4E;IAC5E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAC9C;AAED;8EAC8E;AAC9E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,UAAU,EACpB,CAAC,EAAE,kBAAkB,GACpB,OAAO,CAAC,aAAa,CAAC,CA2BxB;AAED;;;uDAGuD;AACvD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CASzE"}

package/dist/adapters/attempt-meta-map.js

@@ -134,6 +134,10 @@ function buildAdapterMeta(provider, s) {
     }
     if (typeof s.streaming === "boolean")
         meta.streaming = s.streaming;
+    if (s.promptDelivery !== undefined)
+        meta.prompt_delivery = s.promptDelivery;
+    if (s.servedTierSource !== undefined)
+        meta.served_tier_source = s.servedTierSource;
     return meta;
 }
 /** A transport/SDK error's coarse envelope (spec §2 `http_status`/`error_code`).

package/dist/adapters/build-adapters.js

@@ -27,8 +27,8 @@ function buildAdapters(config, registryFacts, compatStatic) {
     }
     if (config.keys.grok)
         adapters.set("grok", (0, grok_1.createGrokAdapter)({ apiKey: config.keys.grok }));
-    // A1 aggregator hosts behind the generic openai-compatible adapter.
-    for (const hostId of ["deepinfra", "fireworks"]) {
+    // A1 aggregator hosts + Z.ai (B4a) behind the generic openai-compatible adapter.
+    for (const hostId of ["deepinfra", "fireworks", "zai"]) {
         const apiKey = config.keys[hostId];
         if (!apiKey)
             continue;