@urun-sh/openai 0.5.5 → 0.5.6

package/dist/responses-turn-tNUHq5b0.d.cts

@@ -0,0 +1,1807 @@
+import { C as CatalogRow } from './models-DUdx_Y6X.cjs';
+import { IncomingMessage } from 'node:http';
+import { a as AudioBridge, h as VideoFrameLane, j as VideoOutLane } from './video-out-CCksIcj8.cjs';
+
+/**
+ * WHAT a proxy serves — the `identity` block on `GET /stats`. Reuse of a
+ * running proxy is allowed iff every field matches the launching invocation
+ * EXACTLY: a partial match (same app, different fn; same everything, older
+ * proxy_version) silently routes the agent at the wrong backend, which is
+ * worse than any error.
+ */
+interface ProxyIdentity {
+    app: string;
+    org: string;
+    fn: string;
+    /**
+     * The control-plane URL the proxy's backhaul session opens against
+     * (URUN_BASE_URL verbatim — same org/app/fn on staging vs prod are
+     * DIFFERENT backends; review finding, #285). Compared exactly: a cosmetic
+     * difference (trailing slash) merely refuses reuse and spawns an ephemeral
+     * proxy — the safe direction.
+     */
+    base_url: string;
+    proxy_version: string;
+}
+
+/**
+ * THE BILLING CORRELATION SEAM — one uuid per `/v1` request, returned as the
+ * `Inference-Id` response header, carried as the suffix of the body id the
+ * request answers with, and recorded in one structured log line.
+ *
+ * WHY IT EXISTS: Hugging Face Inference Providers bill routed requests by a
+ * unique id the provider returns as a RESPONSE HEADER. Their spec is explicit:
+ * "Make sure this header is present on every response you return, including
+ * streaming responses. If it's missing, we have no way to match the request
+ * and it can't be billed." A response that leaves this proxy without the
+ * header is therefore an UNBILLED response — a revenue bug, not a cosmetic
+ * one — which is why the header is set on the response object in the request
+ * handler's synchronous prefix, before any lane can flush a head.
+ *
+ * WHAT THIS MINT COVERS: the three HTTP lanes' body ids (`chatcmpl-…`,
+ * `resp_…`, `msg_…`) and the `/v1/responses` WebSocket lane's response ids —
+ * all of which previously minted their own `Math.random().toString(36)`
+ * string, four unrelated id spaces nothing downstream could join on. Only
+ * `executeResponsesTurn`'s required `responseId` argument is COMPILE-enforced;
+ * the rest is enforced by review, so keep new lanes on this mint.
+ *
+ * WHAT IT DOES NOT COVER (still separate id spaces, recorded on ENG-309):
+ *   - `transport/decode.ts` builds `resp_${requestId}` from the SERVE-lane
+ *     request id that `responses/ResponsesClient.ts` mints (`req_<n>`); the
+ *     HTTP lanes overwrite it with the id from here, but joining a billing row
+ *     to the runtime's own usage receipt still needs that id plumbed through
+ *     `ProxyClients.createResponse`.
+ *   - the OpenAI Realtime lane (`proxy/openai-realtime/protocol.ts`) mints its
+ *     own `resp_` ids for WS realtime turns — which, being built from a
+ *     `req_`-prefixed seed, currently read `resp_req_<hex>` (a double prefix).
+ */
+
+type TurnCatalogIdentity = {
+    kind: 'catalog';
+    model_id: string;
+    variant: string;
+} | {
+    kind: 'not-a-catalog-model';
+    model: string | null;
+} | {
+    kind: 'unresolved';
+    reason: string;
+};
+/**
+ * WHAT ONE DIAL REPORTS ABOUT ITSELF — everything the ledger reads off the
+ * dial that actually served, reported together, from that dial.
+ *
+ * ONE CALLBACK, BOTH FACTS, and that is the point rather than a convenience.
+ * `session_id` (ENG-417) and the billing identity (ENG-414) are the two halves
+ * of the same question — which instance ran this, and what it ran — and a
+ * re-home makes them disagree the moment they are sourced separately: the row
+ * named the REPLACEMENT instance while naming the identity the ABANDONED dial
+ * resolved. Two callbacks firing from the same loop about the same dial would
+ * be two things free to drift apart again, which is the whole defect this seam
+ * exists to remove. Widen this payload; never add a second callback beside it.
+ *
+ * FIRED ONCE PER DIAL, LAST DIAL WINS. `rehome.ts` performs exactly one
+ * re-dial when a backhaul dies before producing client-visible content, and
+ * reports again before the replacement is used — so what the ledger keeps is
+ * the dial that served.
+ */
+interface DialReport {
+    /**
+     * The uRun session id of the backhaul about to be used, or null when the
+     * pool entry carries no session identity. Never a fabricated id: a wrong
+     * link moves cost attribution between machines.
+     */
+    sessionId: string | null;
+    /**
+     * The billing identity THIS dial resolved — the ledger's own vocabulary, not
+     * the router's. It comes off the SAME `resolveTarget` answer the dial used
+     * (`ModelRouter.sessionFor`), never a second resolution taken alongside it:
+     * a resolution taken at a different moment can answer differently, and then
+     * the row names a variant nobody served. Both flavours travel this way — the
+     * catalog `(model_id, variant)` and the caller-org app slug, which ENG-412
+     * made billing-bearing.
+     */
+    identity: TurnCatalogIdentity;
+}
+/** The observer one dial reports itself to. See {@link DialReport}. */
+type DialObserver = (dial: DialReport) => void;
+/**
+ * ONE completed `/v1` request, as data. This is the SINGLE per-request fact
+ * object: {@link inferenceRequestLine} serializes it into the billing
+ * correlation log line, and `proxy/metrics.ts` `InferenceMetrics.observe`
+ * counts the same object into Prometheus. Two sinks, one record — a metric
+ * that could disagree with the billing log would be worse than no metric.
+ *
+ * Nothing here is a secret or a body: no API key, no prompt, no completion.
+ * The caller is identified by `org` (a control-plane identifier), never by the
+ * Bearer key that resolved it.
+ */
+interface InferenceRecord {
+    readonly event: 'inference_request';
+    readonly ts: string;
+    readonly inference_id: string;
+    readonly method: string;
+    readonly path: string;
+    readonly status: number | null;
+    readonly delivered: boolean;
+    readonly stream_error: boolean;
+    readonly model: string | null;
+    readonly stream: boolean | null;
+    readonly org: string | null;
+    readonly duration_ms: number;
+    readonly ttft_ms: number | null;
+    /**
+     * The usage quantities the per-request ledger is written from. NULL means
+     * the request HAS no such quantity — never zero of it. See
+     * {@link InferenceTurn.promptTokens}.
+     *
+     * They are on the RECORD rather than read separately by the ledger writer
+     * for the reason the record exists at all: one object, every sink. A writer
+     * that took a second walk over the request could disagree with the log line
+     * and the metric, and the disagreement would be invisible.
+     *
+     * NOTE WHAT IS NOT HERE: `gpu_seconds`. There is no such quantity, and as
+     * of ENG-417 there is no such ledger column either. Exclusive per-request
+     * GPU occupancy is not obtainable under continuous batching, and wall-clock
+     * is SHARED occupancy — a per-request stamp would double-count against
+     * `usage_events.metered_gpu_seconds`, which meters the instance once. What
+     * is here instead is the LINK ({@link session_id}) and the WEIGHT (the
+     * residency milliseconds below), from which the share is DERIVED.
+     */
+    readonly prompt_tokens: number | null;
+    readonly completion_tokens: number | null;
+    readonly output_units: number | null;
+    /**
+     * THE INSTANCE that served this request — see
+     * {@link InferenceTurn.sessionId}. On the log line as well as the ledger,
+     * so a row that was never written can still be traced to the session it
+     * would have been attributed to.
+     */
+    readonly session_id: string | null;
+    /**
+     * THE WEIGHT — see {@link InferenceTurn.timing}. Flattened onto the record
+     * rather than nested, because this record is also a log line and a flat
+     * field is what a log query can select. NULL means the runtime reported
+     * nothing; it never means zero.
+     */
+    readonly queue_ms: number | null;
+    readonly prefill_ms: number | null;
+    readonly decode_ms: number | null;
+    readonly total_ms: number | null;
+    /**
+     * The identity that served this request, reported by the dial that served it
+     * — see {@link TurnCatalogIdentity} and {@link DialReport}. The ledger writer
+     * reads it from here rather than asking the router again, and the log line
+     * carries it so a row that was never written can be traced to the reason
+     * from the same record.
+     */
+    readonly catalog: TurnCatalogIdentity;
+}
+
+/**
+ * THE SHARED-MODEL LANE (shared-endpoints U8, urun-infra#1490 §7) — the pure
+ * per-request resolver over the catalog edge function's `shared` block:
+ *
+ *     { shared_org_id, endpoints: [{ model_id, variant, gpu_spec, app_slug,
+ *                                    function, warm }] }
+ *
+ * Every function here is PURE and synchronous over the parsed block: the
+ * catalog fetch (U5's edge-function surface) is a separate seam and is NOT
+ * built yet — a caller hands the block in, or doesn't. An absent/empty
+ * `shared` block means "no shared models" and every lookup says so (null),
+ * never a stub.
+ *
+ * POSTURE (the two error classes, deliberately distinct):
+ *   - `null`            → this model is not in the shared block. The caller
+ *     keeps its own resolution order; on the hosted lane that ends in the
+ *     loud UnknownModelError 404. NOT an error — "not mine" is an answer.
+ *   - `SharedCatalogError` → the block itself is broken (malformed shape, or
+ *     a bare model id whose compat_default flag is not unique). This is a
+ *     platform catalog defect, not a caller mistake: it surfaces as a LOUD
+ *     500 naming the row, never a silent resolution to "some" variant.
+ */
+/** One shared endpoint row — the edge function's `endpoints[]` element. */
+interface SharedEndpointRow {
+    model_id: string;
+    variant: string;
+    /** The shared org's deployed app slug the session dial targets. */
+    app_slug: string;
+    /** The serve function name on that app. */
+    function: string;
+    /** PLACEMENT-level GPU spec, e.g. 'rtx6000:1' (mirrors CatalogRow). */
+    gpu_spec?: string | null;
+    /** Idle-floor replica count (the reconciler's `warm`, U6). */
+    warm?: number | null;
+    /**
+     * The compat_default flag (U4): a BARE model id resolves to THE flagged
+     * row. Exactly one per model_id — zero or two is a loud catalog defect.
+     */
+    compat_default?: boolean | null;
+}
+/** The catalog edge function's `shared` block. */
+interface SharedCatalogBlock {
+    shared_org_id: string;
+    endpoints: SharedEndpointRow[];
+}
+
+/**
+ * THE PER-TOKEN PRICE SURFACE — what `GET /v1/models` may say about money.
+ *
+ * Hugging Face reads our OpenAI-shaped model list to populate its public
+ * Inference-Provider comparison table and to power its `:fastest` and
+ * `:cheapest` routing. The required per-model shape is
+ *
+ *     "pricing": { "input": <USD per MILLION input tokens>,
+ *                  "output": <USD per MILLION output tokens> }
+ *
+ * so this module resolves exactly that pair — per catalog model — out of
+ * urun-infra's `public.model_prices` surface (shared-endpoints U3,
+ * migration 20271003000003), and NOTHING else.
+ *
+ * OMISSION IS THE CONTRACT. A model with no per-token price row carries NO
+ * `pricing` key at all — never `0`, never a GPU-minute rate reinterpreted as
+ * a token rate, never an estimate. `model_prices` prices GPU TIME today
+ * (`unit in ('per_request','per_minute','per_output_unit')`, and the seeded
+ * rows are per_minute GPU-minutes); turning GPU-minutes into per-token rates
+ * is a PRICING DECISION a human makes, tracked as ENG-317. A fabricated
+ * number here would be a silent lie on a public comparison table that other
+ * people's routing decisions depend on, which is strictly worse than an
+ * absent field: HF renders an unpriced model as unpriced, and that is true.
+ *
+ * TWO GAPS THAT MUST CLOSE UPSTREAM BEFORE THIS SURFACE CAN EVER BE
+ * NON-EMPTY. Both are recorded on **ENG-317**, which is the durable record
+ * — this comment only points at it, because a code comment and a PR body
+ * are exactly the channels CLAUDE.md rule 2 names as insufficient:
+ *
+ *   1. NO PER-TOKEN UNIT EXISTS YET (ENG-317). `model_prices_unit_check`
+ *      allows only per_request | per_minute | per_output_unit. The two unit
+ *      strings this module recognizes — {@link PER_MILLION_INPUT_UNIT} and
+ *      {@link PER_MILLION_OUTPUT_UNIT}, with `price_usd` read VERBATIM as
+ *      USD per million tokens (no conversion, and `numeric(12,8)` has ample
+ *      resolution at per-million scale — a per-single-token unit would not)
+ *      — are a PROPOSED contract ENG-317 must ratify and a migration must
+ *      add. Until then every live read yields zero per-token rows and every
+ *      entry is unpriced. (If ENG-317 ratifies different names, a row
+ *      carrying them is LOUD here, not skipped — see
+ *      {@link KNOWN_NON_TOKEN_UNITS}.)
+ *   2. THE ANON READ IS RLS-BLOCKED (ENG-317). `model_prices` grants
+ *      `select` to `anon` (migration 20271003000003 line 107), but its only
+ *      policy (`model_prices_select_all`, line 112) is
+ *      `for select to authenticated` — so a read with the proxy's catalog
+ *      anon key returns `[]` whatever the table holds, indistinguishably
+ *      from "no rows". (Contrast `model_catalog`, whose policy is
+ *      `to anon, authenticated`; migration 20270226000000 calls that "the
+ *      one intentional public read".) urun-infra must add the anon policy
+ *      or publish prices through the catalog edge function.
+ *
+ * CONSEQUENCE, STATED PLAINLY: no `pricing` field can appear in production
+ * today. This module is correct and inert until gap 2 is fixed.
+ *
+ * WHAT IS A DEFECT (loud) vs WHAT IS SIMPLY UNPRICED (skipped):
+ *   - a row whose `unit` is not one of the two per-token units → SKIPPED.
+ *     A GPU-minute or per-request price is not evidence of a token rate; it
+ *     is not this surface's business.
+ *   - a row outside its effective window → SKIPPED. That is what
+ *     effective-dating means.
+ *   - a model with only ONE of the two rates → that model stays UNPRICED.
+ *     Half a price is a lie; HF needs both numbers or neither.
+ *   - a row that DOES claim a per-token unit but cannot be read (no
+ *     model_id, unparseable price/date, a missing column, a non-object row,
+ *     two rows of the same side with the same winning `effective_at` and
+ *     DIFFERENT prices) → {@link ModelPriceError}. A broken price on a
+ *     public table is worse than no price, and an order-dependent pick
+ *     between two same-instant rows would be exactly the silent guess this
+ *     repo forbids.
+ *
+ * THE ERROR TAXONOMY MATTERS TO CALLERS, so it is deliberate and narrow:
+ * {@link ModelPriceError} means THE DATA IS A DEFECT and no honest price can
+ * be derived — the /v1/models lane lets it PROPAGATE (a self-contradictory
+ * price table must be seen and fixed, not rounded down to "unpriced"). A
+ * plain `Error` from {@link fetchModelPriceRows} means the surface could
+ * not be READ (transport/status) — that one the listing may degrade past,
+ * because model DISCOVERY must not die with the price oracle. Those are the
+ * only two failure modes; nothing here returns an empty list to paper over
+ * either.
+ *
+ * THE SURFACE IS READ IN TWO STEPS, and the split is load-bearing:
+ * {@link parseModelPriceRows} validates the wire rows (timeless facts — a
+ * caller may CACHE these), and {@link resolveTokenPrices} answers which of
+ * them is in force AT AN INSTANT (a per-REQUEST question — caching THAT
+ * would serve a rate past its own `expires_at`). See each function's note.
+ */
+
+/** USD per 1,000,000 tokens — verbatim the HF Inference-Provider shape. */
+interface TokenPricing {
+    input: number;
+    output: number;
+}
+/** Which half of the pair a recognized unit names. */
+type Side = 'input' | 'output';
+/**
+ * ONE VALIDATED per-token price row — the cacheable, TIME-INDEPENDENT half
+ * of this surface. Everything here is a fact about the row itself; nothing
+ * about WHICH row is in force, because that depends on when you ask (see
+ * {@link resolveTokenPrices}). The read/validate step yields these; the
+ * time-dependent step consumes them.
+ */
+interface ModelPriceRow {
+    model_id: string;
+    /** null = the model-level rate for every variant without its own row. */
+    variant: string | null;
+    side: Side;
+    /** USD per 1,000,000 tokens, verbatim from `price_usd`. */
+    usd: number;
+    /** Epoch ms of `effective_at`. */
+    effective_at: number;
+    /** Epoch ms of `expires_at`, or null for a row that never expires. */
+    expires_at: number | null;
+}
+
+/**
+ * THE OPENROUTER PROVIDER DOCUMENT — `GET /v1/models?format=openrouter`.
+ *
+ * OpenRouter's provider monitor polls this document (schema 2.4, per
+ * openrouter.ai/docs/guides/community/for-providers §1) to list a provider's
+ * models on the marketplace. The document answers ONE question: "all models
+ * that should be served by OpenRouter" — the platform's SELLABLE surface.
+ * That surface is the catalog edge function's SHARED block (the shared
+ * endpoints OpenRouter's callers resolve by `model_id:variant` on the chat
+ * surface); caller-org apps are deliberately NOT in it. A caller-org app is
+ * a tenancy-private chat surface behind one org's key — declaring it here
+ * would sell another tenant's private deployment as a public marketplace
+ * SKU. The document still rides the tenancy seam (`openRouterModels` on the
+ * tenant client), so each caller sees the same sellable listing.
+ *
+ * THE SHARED JOIN: each endpoint joins the catalog EXACTLY on
+ * (model_id, variant) — the SAME join the shared-lane consumers (supportsAudio,
+ * modelList's shared arm, imageModelList) already apply. No slug heuristics: the
+ * shared org's app slug need not exist in
+ * the caller's catalog, and a slug guess would be a second, bespoke join.
+ *
+ * MODALITY GATING: only rows whose catalog `task` names a chat-completions
+ * shape (chat | code | agent | vl) are declared. A voice/video/image app
+ * behind a chat surface would stream garbage into OpenRouter's baseline
+ * tests; models the catalog cannot vouch for are OMITTED, never guessed.
+ * With no shared block (or no catalog oracle) configured the document is
+ * `{"data": []}` — honest emptiness, not invented capability.
+ *
+ * PRICING — schema 2.4 nests `pricing` arrays on the modality that owns
+ * them ({type 'prompt'} on the text INPUT modality, {type 'completion'} on
+ * the text OUTPUT modality, `cost_usd` a USD string PER TOKEN). The price
+ * source is model-prices.ts — the SAME per-token join the OpenAI listing
+ * uses ({@link pricingFor}); the per-million rate is shifted to per-token
+ * on its decimal string, never by float division. An entry with no
+ * per-token row — today ALL of them, because `model_prices` prices GPU
+ * minutes (`per_minute` et al.), which is not evidence about tokens —
+ * carries NO pricing array at all: the schema's rule is "a modality with
+ * no pricing array is simply unpriced". Never a zero, never a GPU-minute
+ * rate relabelled as a token rate (ENG-317 owns the human pricing
+ * decision that would make such rows exist).
+ *
+ * The full closed-value-domain schema ships as OpenAPI 3.1 at
+ * openrouter.ai/docs/assets/provider-monitor-schema-v2.openapi.json.
+ */
+
+type OpenRouterProviderDoc = {
+    data: OpenRouterProviderModel[];
+};
+interface OpenRouterProviderModel {
+    schema_version: '2.4';
+    /** The EXACT id OpenRouter sends back as `model` — the app slug. */
+    id: string;
+    name: string;
+    created: number;
+    /** Valid enum: int4|int8|fp4|mxfp4|nvfp4|fp6|fp8|mxfp8|fp16|bf16|fp32|null. */
+    quantization: string | null;
+    description: string;
+    hugging_face_id: string;
+    input_modalities: Array<Record<string, unknown>>;
+    output_modalities: Array<Record<string, unknown>>;
+}
+
+/**
+ * Per-model → per-app routing for the compat proxy (owner directive
+ * 2026-08-07): swapping the model in a coding harness routes the request to
+ * the org's DEPLOYED app for that model. v1 is deployed-only — a uRun model
+ * that is not deployed gets a loud 404 naming `urun serve <id>`; a later
+ * phase (explicitly out of scope here; urun-infra#1490 shared-endpoints)
+ * auto-creates from the model catalog on first request.
+ *
+ * MODEL-ID SURFACE (the documented mapping): a model may be named by
+ *   - the app slug itself        ("qwen3-6-27b-bf16"), or
+ *   - the catalog id             ("qwen3.6-27b"), or
+ *   - the catalog id:variant     ("qwen3.6-27b:bf16"),
+ * where slugification mirrors urun-cli `serve.py _default_app_name` exactly:
+ * lowercase, every non-alphanumeric-non-dash character becomes "-", leading/
+ * trailing dashes stripped (catalog id "qwen3.6-27b" + variant "bf16" → app
+ * "qwen3-6-27b-bf16"). COLLISION RULE: an exact slug match always wins over
+ * the catalog-id (prefix) interpretation.
+ *
+ * RESOLUTION ORDER (one canonical path, documented end to end):
+ *   1. model absent / "urun" / an alias of the startup app  → DEFAULT app.
+ *   2. exact slug match on a deployed serve app             → that app.
+ *   3. catalog-id form matching exactly one deployed app    → that app
+ *      (two or more candidates → loud ambiguity error naming them).
+ *   4. the name maps to an org app that is NOT an active app exposing the
+ *      proxy's serve function                               → loud 404
+ *      naming `urun serve <model>` and the available models.
+ *   5. the name matches a catalog row but no deployed app   → loud 404
+ *      naming `urun serve <id>` (deployed-only v1).
+ *   6. anything else — a model name outside the uRun namespace entirely
+ *      (e.g. the harness's own upstream default, "claude-*"/"gpt-*") →
+ *      DEFAULT app. This IS today's single-app contract, kept deliberately
+ *      so `urun compat <agent>` with the agent's stock model keeps working
+ *      with zero new env; the per-model /stats table records every such
+ *      mapping so it is visible, never silent. Models the proxy ADVERTISES
+ *      on /v1/models can never land here — they resolve (2/3) or fail loud
+ *      (4/5) above.
+ *
+ * NO-DEFAULT MODE (`defaultApp: null`) — the HOSTED multi-tenant lane
+ * (`src/hosted/`): a shared endpoint serving every org has no "the app this
+ * proxy was started for", so rules 1 and 6 have nothing to fall back TO.
+ * Rather than inventing one (picking "some" app for a caller would be the
+ * worst kind of silent divergence), both rules become the SAME loud
+ * {@link UnknownModelError} that rules 4/5 already raise: name a deployed
+ * model, here is the list. Rules 2–5 are byte-for-byte the local behavior —
+ * one router, one resolution order, two configurations.
+ */
+
+/** One org app row from `GET {orgApi}/apps` (urun-cli `ApiClient.list_apps`). */
+interface DeployedApp {
+    app_slug: string;
+    function_name?: string | null;
+    deployment_status?: string | null;
+    [k: string]: unknown;
+}
+/**
+ * A model that does not resolve to a deployed app the proxy may serve.
+ * Rendered by the server in each lane's NATIVE error format as a 404 — never
+ * silently served by the default app.
+ */
+declare class UnknownModelError extends Error {
+}
+/**
+ * A session handle names a pooled session that no longer exists (closed,
+ * evicted after its pod died, replaced by a re-home, or the proxy restarted).
+ * The caller asked to REATTACH that exact session — opening a fresh one and
+ * calling it "resumed" would be a silent lie, so this is always loud.
+ */
+declare class SessionGoneError extends Error {
+}
+/**
+ * OpenAI-shaped model list (same shape as models.ts listModels). When the
+ * catalog oracle is configured, each entry ALSO carries the catalog
+ * enrichment fields (additive JSON — OpenAI clients ignore unknown fields;
+ * the OpenRouter + Vercel AI Gateway provider listings need them). Entries
+ * whose slug matches no catalog row stay at the bare four fields.
+ */
+interface RouterModelEntry {
+    id: string;
+    object: 'model';
+    created: number;
+    owned_by: string;
+    /** Display name — the canonical `<model_id>:<variant>` catalog ref. */
+    name?: string;
+    /** User-facing description from the catalog (console Endpoints copy). */
+    description?: string;
+    /** Catalog modality (chat | code | agent | vl | audio | image | ...). */
+    task?: string;
+    /** Serving engine (vllm | sglang | llamacpp | ...). */
+    engine?: string;
+    /** The catalog lane this app deploys, e.g. 'rtx6000:1'. */
+    gpu_spec?: string;
+    /** Context window in tokens (chat rows carry it in engine_args). */
+    context_length?: number;
+    /**
+     * Per-token price, USD per MILLION tokens — the exact shape Hugging Face
+     * reads off `GET /v1/models` for its provider comparison table and its
+     * `:fastest`/`:cheapest` routing. ABSENT means UNPRICED and is the honest
+     * answer for every model with no per-token price row (model-prices.ts);
+     * a zero or an estimate here would be a silent lie on a public table.
+     */
+    pricing?: TokenPricing;
+    /** Idle-floor replica count for a shared-lane model (U6 reconciler). */
+    warm?: number;
+}
+interface RouterModelList {
+    object: 'list';
+    data: RouterModelEntry[];
+}
+/** One `/v1/images/models` entry: the OpenAI model object plus the image
+ * modes the catalog rows vouch for (the SAME per-placement consensus
+ * {@link ModelRouter.supportsImages} applies — a row set that vouches
+ * nothing is NOT listed). */
+interface RouterImageModelEntry extends RouterModelEntry {
+    image_modes: ImageCapabilityMode[];
+}
+interface RouterImageModelList {
+    object: 'list';
+    data: RouterImageModelEntry[];
+}
+/**
+ * The dial target one resolved model names: the app slug plus — for a SHARED
+ * lane (the catalog `shared` block, the cross-org session dial) — the exact
+ * serve function on the shared org's app and the flag that switches the
+ * control plane's shared-admission carve-out on. A plain caller-org app
+ * carries only `appSlug`; the router's own `fnName` applies there.
+ */
+interface RouteTarget {
+    appSlug: string;
+    /** The serve function on the TARGET app (a shared lane pins it per row). */
+    fnName?: string;
+    /**
+     * CROSS-ORG SHARED DIAL: the backhaul mints the client token with
+     * `sharedApp: true` and starts the session with `shared_app: true`, so the
+     * control plane resolves the app from the platform's shared org while the
+     * session and its usage stay attributed to the CALLER org.
+     */
+    sharedApp?: boolean;
+    /** Shared lanes only: the catalog id the request pinned (capability joins). */
+    modelId?: string;
+    /** Shared lanes only: the catalog variant the request pinned. */
+    variant?: string;
+}
+interface ModelRouterOptions<S> {
+    /**
+     * The startup app slug (URUN_APP) — the DEFAULT model — or `null` for the
+     * hosted multi-tenant lane, which has no per-proxy default app: there,
+     * every request must NAME a deployed model and an unnamed/unknown one
+     * fails loud instead of silently landing somewhere (see the module header,
+     * "NO-DEFAULT MODE").
+     */
+    defaultApp: string | null;
+    /** The serve function name every routed app must expose (URUN_FUNCTION). */
+    fnName: string;
+    /** Open a backhaul session for a resolved dial target (called at most once per pool key). */
+    openSession: (target: RouteTarget) => S | Promise<S>;
+    /** Terminal release for one pool entry (Session.end() underneath). */
+    closeSession: (entry: S) => Promise<void>;
+    /**
+     * List the org's deployed apps, or null when the credentials cannot
+     * (URUN_JWT lane: the pre-vended token is scoped to the default app, so
+     * there is no org listing AND no cross-app session — routing degrades to
+     * the default-app-only contract, which is exactly today's behavior).
+     */
+    listApps: (() => Promise<DeployedApp[]>) | null;
+    /**
+     * Catalog rows (models.ts fetchCatalogRows) as the uRun-namespace oracle
+     * for rule 5 AND the /v1/models enrichment + OpenRouter provider-doc
+     * source, or null when catalog access is not configured. Optional fields
+     * beyond model_id/variant are tolerated (thin rows still typecheck).
+     */
+    listCatalog: (() => Promise<CatalogRow[]>) | null;
+    /**
+     * The VALIDATED per-token price rows (model-prices.ts
+     * `fetchModelPriceRows`) behind the `pricing` field of the /v1/models
+     * listing, or null when no price source is configured. A REQUIRED key
+     * exactly like {@link listCatalog}: an optional one would let a lane ship
+     * a silently unpriced public listing without ever saying so.
+     *
+     * These are ROWS, not resolved prices, precisely so the router may cache
+     * them: which row is in force is a per-REQUEST question answered by
+     * `resolveTokenPrices` against the exact `effective_at` / `expires_at`
+     * boundaries. Handing back already-resolved prices would let a cached
+     * answer outlive the window it was resolved in.
+     */
+    listPrices: (() => Promise<ModelPriceRow[]>) | null;
+    /**
+     * Where this router announces a DEGRADATION — an unreadable price
+     * surface, a model refused a price, a catalog blip that suppresses
+     * pricing. Optional only in WHERE it goes: left unset the router writes
+     * to `console.warn`, never to nothing (see {@link ModelRouter.warn}).
+     * Mirrors the `warn` sink `catalogFromEnv` (cli.ts) already takes.
+     */
+    warn?: (line: string) => void;
+    /** Deployed-apps cache TTL (the list changes on deploys, not per request). */
+    appsTtlMs?: number;
+    /**
+     * The stable NATIVE identity of one pooled entry (the uRun session id in
+     * the proxy wiring — the same identity the serve-side session-affinity tag
+     * rides, urun-python#1556). Powers the session-identity seam
+     * ({@link ModelRouter.handleFor} / {@link ModelRouter.sessionForHandle});
+     * a router without it fails LOUD on those calls, never approximates.
+     */
+    sessionKey?: (entry: S) => string;
+    /**
+     * The catalog edge function's `shared` block (shared-endpoints U8), or
+     * null when shared-model routing is not configured — every phase-1 caller
+     * leaves it absent and behaves byte-for-byte as before. Same TTL cache
+     * discipline as the apps/catalog oracles.
+     */
+    shared?: (() => Promise<SharedCatalogBlock | null>) | null;
+}
+/**
+ * The image-capability modes the Images lane gates on (images.ts's
+ * ImageCapabilityMode — declared here because the router is the LOWER layer:
+ * the lane's gate type stays structurally satisfied by
+ * {@link ModelRouter.supportsImages} with no router→lane import).
+ */
+type ImageCapabilityMode = 'generation' | 'edit';
+/**
+ * The session pool: one backhaul session per deployed app, keyed by app slug,
+ * opened lazily on the first request that routes to it and reused for every
+ * subsequent one. The startup app is seeded eagerly by the CLI. Sessions
+ * close on proxy shutdown via {@link closeAll}; there is NO idle-close policy
+ * (deliberate v1 simplification — noted as a follow-up in the PR).
+ */
+declare class ModelRouter<S> {
+    private readonly opts;
+    private readonly pool;
+    private appsCache;
+    private rowsCache;
+    constructor(opts: ModelRouterOptions<S>);
+    /** Seed an already-open session (the CLI's eagerly-opened startup app). */
+    seed(appSlug: string, entry: S): void;
+    private deployedApps;
+    /**
+     * The shared block with the same TTL discipline as {@link deployedApps}.
+     * Null when not configured. Malformed blocks throw loudly
+     * (SharedCatalogError) on first use — never a silently half-empty table.
+     */
+    private sharedBlock;
+    private sharedCache;
+    /**
+     * Catalog rows with the same TTL discipline as {@link deployedApps} (the
+     * catalog changes on reseed migrations, not per request). Null when no
+     * oracle is configured — callers degrade to the bare four-field entries.
+     */
+    private catalogRows;
+    private pricesCache;
+    /**
+     * The per-token price ROWS with the same TTL discipline as
+     * {@link catalogRows} (the price book changes on ops writes, not per
+     * request). No source configured ⇒ [] — every model unpriced, which is
+     * the honest listing until per-token rows exist (ENG-317).
+     *
+     * ROWS, never resolved prices: the rows are timeless facts, so caching
+     * them is safe, whereas caching the prices IN FORCE would keep serving a
+     * rate past its own `expires_at` — or withhold one past its
+     * `effective_at` — for the rest of the TTL window. The in-force question
+     * is answered per request in {@link pricesForListing}.
+     */
+    private priceRows;
+    /**
+     * The price surface for the /v1/models listing. Three distinct outcomes,
+     * and NONE of them is silent:
+     *
+     *   - the surface cannot be READ (transport, status, or the read's own
+     *     deadline — a plain Error) ⇒ every model lists UNPRICED and the
+     *     reason is WARNED. Model discovery must not die with the price
+     *     oracle, but an outage rendering as an ordinary unpriced listing —
+     *     indistinguishable from today's inert state — is exactly the silent
+     *     degradation CLAUDE.md forbids, so it says so out loud.
+     *   - one model's rows are a DEFECT (a duplicate rate for one instant, a
+     *     zero rate) ⇒ that MODEL is unpriced and the refusal is WARNED. The
+     *     blast radius is the model the bad row belongs to; it used to be the
+     *     whole listing for every tenant.
+     *   - the READ itself is not the surface we contracted for (a malformed
+     *     row, a missing column, an unknown `unit` — {@link ModelPriceError})
+     *     ⇒ PROPAGATES. Nothing in a payload that violates its own column
+     *     contract can be trusted, so half a price table is not served as if
+     *     complete — the same posture `parseSharedBlock` takes on a malformed
+     *     routing block.
+     *
+     * The resolve step sits OUTSIDE the catch deliberately: it is our own
+     * code, so a programming error in it must surface as a crash, not become
+     * an empty price list.
+     */
+    private pricesForListing;
+    /**
+     * Where a degradation says so. Defaults to `console.warn` rather than to
+     * nothing: a caller may ROUTE the signal (the CLI sends it to stderr, as
+     * `catalogFromEnv` already does), but no caller can switch it off, because
+     * an unannounced degradation is the failure mode this repo treats as a
+     * time bomb.
+     */
+    private warn;
+    /** Apps this proxy may serve: active AND exposing the serve function. */
+    private servable;
+    private availableIds;
+    /**
+     * NO-DEFAULT MODE's terminal for rules 1 and 6: there is no app to fall
+     * back to, so say so loudly and list what the CALLER'S org actually has.
+     * Never returns.
+     */
+    private noDefaultApp;
+    /**
+     * Resolve a request's `model` to its dial target — the documented
+     * resolution order from the module header. Throws
+     * {@link UnknownModelError} for a uRun model that is not deployed (rules
+     * 4/5). A SHARED-lane hit (the catalog `shared` block) resolves to the
+     * SHARED org's app with `sharedApp: true` — the cross-org session dial.
+     */
+    private resolveTarget;
+    /**
+     * THE BILLING IDENTITY of a request's model: the CATALOG `(model_id,
+     * variant)` the request actually resolved to, or `null` when the route
+     * names no catalog model.
+     *
+     * WHY THE LEDGER CANNOT USE THE CALLER'S STRING INSTEAD. The per-request
+     * ledger prices on `(model_id, variant)` (urun-infra
+     * `urun_record_inference_request`), and the caller's `model` is not that:
+     * a BARE catalog id resolves through {@link resolveSharedModel} to the
+     * model's `compat_default` VARIANT, so recording the raw string would file
+     * the request under a variant nobody served and price it off the
+     * model-level wildcard — a rate that exists precisely to price the variants
+     * nobody named explicitly. Splitting the string on its last `:` would be a
+     * heuristic on a money path. This is the resolution the dial itself used.
+     *
+     * NULL FOR A CALLER-ORG APP, and that is a REFUSAL rather than a gap. An
+     * org's own deployed app has no catalog identity at all — its identity is
+     * an app slug, which is a different namespace from `model_prices.model_id`
+     * — so there is no honest `(model_id, variant)` to record. The ledger
+     * writer declines to write such a request rather than inventing one; see
+     * `proxy/ledger.ts`.
+     *
+     * CHEAP TO CALL: it rides {@link resolveTarget}, whose app listing, catalog
+     * and shared block are all cached on this router, so the ledger writer can
+     * ask AFTER the response has closed without re-hitting the control plane.
+     */
+    catalogIdentityFor(model: string | undefined): Promise<{
+        model_id: string;
+        variant: string;
+    } | null>;
+    /**
+     * THE CALLER-ORG APP LANE's OWN IDENTITY (ENG-412) — the app slug this
+     * request actually resolves to.
+     *
+     * The ledger records it for the lane {@link catalogIdentityFor} answers null
+     * for, and the caller's RAW `model` string is not it: routing trims, caps and
+     * matches that string before selecting an app, so two spellings of one app
+     * would otherwise be filed as two identities and no app-level reconciliation
+     * could undo it afterwards.
+     *
+     * Rides {@link resolveTarget}'s cached listings and OPENS NO SESSION.
+     */
+    servingAppSlugFor(model: string | undefined): Promise<string>;
+    /**
+     * Resolve a request's `model` to its POOL KEY — the app slug for a
+     * caller-org app, `shared:<slug>` for a shared-lane dial (the two never
+     * share a pool slot, {@link poolKeyOf}).
+     */
+    resolveApp(model: string | undefined): Promise<string>;
+    /**
+     * The pooled session for a model — opened lazily, reused afterwards.
+     *
+     * IT ALSO REPORTS THE DIAL'S BILLING IDENTITY (ENG-414), off the SAME
+     * `resolveTarget` answer it just selected the session with. That is the
+     * whole point of returning it from here: the ledger must be able to name
+     * what served a request WITHOUT taking a second resolution. This router
+     * reads its app list, catalog and shared block through caches with a TTL, so
+     * a second resolution taken microseconds later can answer differently — and
+     * then the row names a variant nobody served. `rehome.ts` reports this
+     * identity once per dial, so a request that re-homes is billed on the
+     * REPLACEMENT's identity rather than the abandoned dial's.
+     *
+     * THE POOL ENTRY COULD NOT CARRY IT. `S` is the generic pooled session and
+     * knows nothing about models; the identity is a property of the ROUTE, which
+     * is what this method resolved and the entry never saw.
+     */
+    sessionFor(model: string | undefined): Promise<{
+        app: string;
+        entry: S;
+        identity: TurnCatalogIdentity;
+    }>;
+    private keyOf;
+    /**
+     * SESSION-IDENTITY SEAM (a): the opaque stable handle for the pooled
+     * session currently serving `model`'s turns. Rides the SAME acquisition
+     * path as every request ({@link sessionFor}) — the session opens lazily if
+     * this model has none yet — and derives the handle from native identity
+     * (app slug + uRun session id), zero bespoke bookkeeping.
+     */
+    handleFor(model: string | undefined): Promise<{
+        app: string;
+        handle: string;
+    }>;
+    /**
+     * SESSION-IDENTITY SEAM (b): the exact pooled session a handle names.
+     * NEVER opens a fresh session — a handle whose session is gone (closed,
+     * evicted, re-homed to a replacement, proxy restarted) or malformed throws
+     * {@link SessionGoneError} loudly. Resume is reattach-or-fail, not
+     * reattach-or-quietly-restart.
+     */
+    sessionForHandle(handle: string): Promise<{
+        app: string;
+        entry: S;
+    }>;
+    /**
+     * Drop ONE pooled session whose backhaul died (its pod was restarted /
+     * drained / deleted) and release it — the next {@link sessionFor} opens a
+     * fresh one, i.e. asks the control plane for a new assignment. Used by the
+     * one-shot re-home (rehome.ts, urun-sh/urun-python#1592).
+     *
+     * IDENTITY-GUARDED (the same rule the pi lane's SessionPool follows): a
+     * concurrent request that already re-homed this app has put a NEWER entry
+     * under the key, and evicting that would close a healthy session out from
+     * under it.
+     */
+    evict(app: string, entry: S): Promise<void>;
+    /**
+     * `GET /v1/models`: the org's deployed serve apps as model entries, the
+     * default app FIRST. On the JWT lane (no org listing) this is the default
+     * app plus any app already in the pool — the gap is called out loudly in
+     * the PR, not papered over here.
+     *
+     * THE HUGGING FACE FIELDS: every entry carries `context_length` (from the
+     * catalog's engine_args, omitted when unknown or when the placements
+     * disagree) and `pricing` (USD per MILLION input/output tokens, omitted
+     * ENTIRELY when the model has no per-token price row — see
+     * model-prices.ts; ENG-317 owns the pricing decision that makes such rows
+     * exist). HF reads both to build its public provider comparison table.
+     * A price surface that cannot be READ lists everything unpriced; a price
+     * surface that is a DEFECT fails this call loudly (see below).
+     */
+    modelList(): Promise<RouterModelList>;
+    /**
+     * The OpenRouter PROVIDER document (`GET /v1/models?format=openrouter`):
+     * schema 2.4 per openrouter.ai/docs/guides/community/for-providers §1 —
+     * "an endpoint that returns all models that should be served by
+     * OpenRouter". That is the SHARED block's sellable endpoints (the models
+     * callers resolve by `model_id:variant` on the chat surface), joined to
+     * the catalog EXACTLY on (model_id, variant) — the SAME join
+     * {@link supportsAudio} applies — and gated to chat-completions shape
+     * (task chat | code | agent | vl; a voice or video app behind a chat
+     * surface would stream garbage). Caller-org apps are deliberately NOT
+     * listed: they are tenancy-private chat surfaces, and a provider
+     * document that published them would sell another tenant's private
+     * deployment as a public marketplace SKU. Pricing follows
+     * {@link pricesForListing}'s posture (an unreadable surface prices
+     * nothing and WARNS — discovery outlives the price oracle); a model with
+     * no per-token row carries NO pricing array (the schema rule: "a
+     * modality with no pricing array is simply unpriced").
+     *
+     * A CONFIGURED catalog read that FAILS propagates — the provider
+     * document cannot vouch a sellable model from nothing, and a half-empty
+     * one must never be served as if complete.
+     */
+    openRouterModels(): Promise<OpenRouterProviderDoc>;
+    /**
+     * IMAGE CAPABILITY GATE (the Images lane's `imageModels` oracle, images.ts):
+     * is `model`'s deployed app a native destination for `mode`? Authorized
+     * resolution ({@link resolveApp} — undeployed uRun models throw
+     * {@link UnknownModelError}, which the lane renders as a 404) then the
+     * SAME catalog join as the /v1/models enrichment (PR421's rowForSlug):
+     * exact `<model_id>-<variant>` slug across ALL its GPU-placement rows, a
+     * bare model_id only when one variant owns it.
+     *
+     * Capability is read ONLY from catalog modality metadata, never from the
+     * serve function name: every row must carry task 'image' INVARIANTLY across
+     * the placements, and the mode comes from engine_args.expects_image —
+     * false ⇒ pure text-to-image ('generation'; diffusers v0.38.0
+     * pipeline_qwenimage_edit_plus raises torch.cat on an EMPTY image list, so
+     * an edit destination is never generation-capable); true or ABSENT (the
+     * native default) ⇒ 'edit'. The consensus rule is per-placement:
+     * capability must agree across every placement — a CONFLICTING flag (mixed
+     * true/false/absent) or a non-boolean one is a refused capability, never
+     * silently defaulted to edit.
+     *
+     * A CONFIGURED catalog oracle that FAILS propagates its rejection — the
+     * gate never fabricates a `false` (which would render as a misleading 404)
+     * out of an infrastructure outage. On the CALLER-ORG lane, no oracle
+     * configured, no matching row, or a slug the catalog cannot vouch for ⇒
+     * false (loud 404 upstream). On the SHARED lane the same questions are
+     * LOUDER: a shared endpoint is published capability, so an unresolvable
+     * row or an unvouchable mode throws {@link SharedCatalogError} (the 500
+     * path) instead of a 404 that would misattribute a catalog defect to the
+     * caller's request.
+     */
+    supportsImages(model: string | undefined, mode: ImageCapabilityMode): Promise<boolean>;
+    /**
+     * AUDIO MODALITY GATE (the OpenAI Realtime lane's modality oracle): does
+     * `model`'s deployed app carry catalog `task` stt or tts — INVARIANTLY
+     * across every GPU-placement row ({@link audioModalityForRows})? The SAME
+     * shape as {@link supportsImages}: authorized resolution
+     * ({@link resolveTarget} — undeployed uRun models throw
+     * {@link UnknownModelError}), then the SAME catalog join
+     * ({@link catalogRowsForSlug}): exact `<model_id>-<variant>` slug across
+     * ALL its placements, a bare model_id only when one variant owns it.
+     *
+     * A SHARED-lane hit joins on the lane's catalog id + variant (the SAME
+     * join {@link imageModelList} uses for the shared block) — the shared org's
+     * app slug need not exist in the caller's own catalog by slug.
+     *
+     * A CONFIGURED catalog oracle that FAILS propagates its rejection — the
+     * gate never fabricates a `false` out of an infrastructure outage. No
+     * oracle configured, no matching row, or a task the catalog cannot vouch
+     * for ⇒ false — the realtime resolver renders that as the loud 404.
+     */
+    supportsAudio(model: string | undefined): Promise<boolean>;
+    /**
+     * `GET /v1/images/models`: the IMAGE-CAPABLE slice of the model surface —
+     * the caller-org deployed apps whose catalog rows vouch an image mode
+     * ({@link imageModesForRows}, the same consensus {@link supportsImages}
+     * applies), plus the shared block's endpoints joined against each
+     * endpoint's OWN catalog row (exact model_id + variant, EXPLICIT boolean
+     * expects_image — {@link sharedImageModes}). A configured catalog oracle
+     * that FAILS propagates, and so does a shared endpoint the catalog cannot
+     * vouch (unresolvable row / unvouchable mode → {@link SharedCatalogError}):
+     * an image listing cannot vouch capability from nothing or advertise a
+     * silently defaulted mode, so — unlike {@link modelList} — there is NO
+     * bare-entries degradation here.
+     */
+    imageModelList(): Promise<RouterImageModelList>;
+    /** Close every pooled session (Session.end() underneath) — proxy shutdown. */
+    closeAll(): Promise<void>;
+}
+
+/**
+ * THE CANONICAL USAGE-QUERY LANE — `POST /v1/usage/requests`.
+ *
+ * WHAT IT IS. A batch lookup over uRun's per-request inference ledger
+ * (`public.inference_requests`, urun-infra ENG-316): "given these inference
+ * ids, what do we hold for each?" — the cost and the usage quantities, scoped
+ * to the calling key's org. OpenAI defines no shape for this, so the shape is
+ * uRun's own: the ledger's own column vocabulary, and the same id space as the
+ * `Inference-Id` response header every `/v1` answer already carries
+ * (inference-id.ts).
+ *
+ * WHY IT IS CANONICAL AND NOT HUGGING-FACE-SHAPED. The owner has ruled that
+ * distributor-specific functionality must not land on the canonical surface.
+ * HF's billing poll — `{"requestIds":[...]}` answered with
+ * `{"requests":[{"requestId","costNanoUsd"}]}` — is HF-proprietary. It gets a
+ * THIN TRANSLATOR over this lane (partners/huggingface.ts, the ENG-376 adapter
+ * pattern): field renames and nothing else. Every other distributor's billing
+ * adapter reads this same lane, and so can the console and support.
+ *
+ * WHERE THE DATA COMES FROM. This process holds no database credential — by
+ * design (hosted/auth.ts: "NO STANDING CREDENTIAL"). The lookup rides the
+ * CALLER'S OWN key to the control plane's `inference-usage` edge function,
+ * which derives the org from that key server-side and runs the org-scoped
+ * `urun_inference_usage_lookup` RPC. So cross-org isolation here is the same
+ * structural property every other lane has: this process never holds a
+ * credential that spans orgs, and the org is never a request field.
+ *
+ * THREE CONTRACTS THAT ARE NOT NEGOTIABLE, because each one is money:
+ *
+ *   1. `cost_nano_usd: null` MEANS NOT YET PRICED — NEVER FREE. Every row in
+ *      production carries NULL today: ENG-317's price machinery has landed but
+ *      seeds no price, and nothing stamps the ledger yet. This lane reports
+ *      the NULL verbatim. A caller that renders it as 0 is inventing a price
+ *      nobody set; a caller billing a third party from it must simply not
+ *      answer for that id yet.
+ *   2. AN ID WE HOLD NOTHING FOR IS ABSENT FROM THE ANSWER, and an id
+ *      belonging to another org is indistinguishable from one that never
+ *      existed. That is deliberate: anything else makes this surface a
+ *      cross-org existence oracle. A row this lane could not VALIDATE is
+ *      absent for the same reason and is therefore indistinguishable from
+ *      those two — which is precisely why it is reported (ENG-416), so that
+ *      the one absence we caused ourselves is visible on our side.
+ *   3. IDS THE CALLER DID NOT ASK ABOUT ARE NEVER RETURNED. The id list is
+ *      the query; the control plane bounds the answer by it, and
+ *      {@link assertRequestedOnly} re-checks it here rather than trusting the
+ *      upstream to have done so.
+ *
+ * WHAT THIS LANE DOES NOT DO: it does not filter on `http_status` (only
+ * 2xx/3xx being billable is an HF rule, and support must be able to ask about
+ * a failed request), and it never returns `gpu_seconds` — a column ENG-417
+ * DROPPED from the ledger entirely, because a per-request GPU-seconds figure
+ * double-counts against `usage_events.metered_gpu_seconds` (which meters the
+ * instance once) and, under continuous batching, can never be reconciled to
+ * it. The guard below is kept and is STRONGER for the removal: it now asserts
+ * that a column which does not exist has not come back.
+ *
+ * WHAT IT DOES RETURN THAT IS EASY TO MISS: `identity_kind`. `model_id` speaks
+ * one of two unrelated namespaces — a catalog identity, or the caller's own
+ * deployed app slug — and the two can COLLIDE as strings, so the identity is
+ * never reported without the namespace that makes it readable.
+ *
+ * AND IT RESOLVES NO PRICE — stated because the surrounding system is about to
+ * grow several, and someone will come looking here. Nothing in this lane or in
+ * its Hugging Face translator reads `model_prices`, picks a rate, or knows what
+ * a model costs. It reports the `cost_nano_usd` a writer already stamped on the
+ * row, at REQUEST grain, so two requests for the same model may carry different
+ * costs and different `price_version`s and this code is indifferent to why.
+ *
+ * That means the one-price-per-model assumption is NOT baked in here. It lives
+ * one layer down, in `urun_active_model_price`, which resolves on
+ * `(model_id, variant)` and separates the session lane from the HF lane BY UNIT
+ * — fine while unit and audience correlate, and filed as ENG-404 for when they
+ * stop (per-minute credit tiers put two audiences on one unit). When that is
+ * fixed, the audience rides `price_version`, which this lane already carries
+ * through per row and never interprets. No change is required here.
+ */
+
+/**
+ * ONE ledger row as this lane answers it — the control-plane RPC's column
+ * list, in the ledger's own vocabulary. `gpu_seconds` and `org_id` are absent
+ * by construction, not by omission here (see the module header).
+ */
+interface InferenceUsageRecord {
+    /** The uuid this request's `Inference-Id` response header carried. */
+    inference_id: string;
+    /** The identity that served it, IN THE NAMESPACE {@link identity_kind} names. */
+    model_id: string;
+    /**
+     * WHICH NAMESPACE {@link model_id} SPEAKS: `catalog_model` (the
+     * `model_prices` vocabulary — everything a distributor routes) or
+     * `caller_org_app` (the caller's own deployed app, which has no catalog
+     * identity and is therefore PERMANENTLY unpriceable — never merely "not
+     * priced yet"). Reported as a plain string rather than a union, because a
+     * value this lane does not recognise must reach the caller as data rather
+     * than fail the batch: an unknown lane is a forward-compatible control plane,
+     * not a corrupt row.
+     */
+    identity_kind: string;
+    /** null = the model-level row (the `model_prices` key semantics). */
+    variant: string | null;
+    task: string;
+    http_status: number;
+    started_at: string;
+    completed_at: string;
+    /** null = this modality has no such quantity (not "zero of it"). */
+    prompt_tokens: number | null;
+    completion_tokens: number | null;
+    output_units: number | null;
+    /** NULL = NOT YET PRICED (ENG-317). Never "free". */
+    cost_nano_usd: number | null;
+    price_version: string | null;
+    priced_at: string | null;
+}
+/**
+ * ONE row this lane REFUSED TO ANSWER ABOUT, handed to the reporter so that a
+ * dropped row is a visible event rather than a silent absence.
+ *
+ * It carries no row content — `where` is a position and `reason` is an
+ * already-redacted {@link UsageSurfaceError} message (names and types, never
+ * values). See {@link describeKeys}.
+ */
+interface UsageRowRejection {
+    /** `usage.requests[N]` — WHICH row, never the row. */
+    where: string;
+    /** Why it could not be validated. */
+    reason: string;
+}
+/**
+ * A sink for {@link UsageRowRejection}s.
+ *
+ * `Promise<void>` IS PART OF THE TYPE BECAUSE IT WAS PART OF THE TYPE ANYWAY.
+ * An `async` function is assignable to a `=> void` signature, so declaring this
+ * synchronous never prevented an async sink — it only hid one, by putting its
+ * failure on a later tick where the containment could not see it. Saying so in
+ * the type is what lets {@link reportRejectedRow} actually handle it.
+ */
+type UsageRowReporter = (rejection: UsageRowRejection) => void | Promise<void>;
+/**
+ * The batch-lookup seam. The hosted endpoint supplies one backed by the
+ * control plane's `inference-usage` function; an embedder that supplies none
+ * gets a LOUD 501 on the lane rather than a silently empty answer — the same
+ * posture the image lanes take for `supportsImages`.
+ *
+ * IT IS TWO-PHASE, and the split is the admission boundary rather than
+ * decoration: {@link authorize} runs BEFORE the request body is read, so a
+ * request with no credential is refused without this process allocating or
+ * parsing anything the caller sent.
+ */
+interface UsageLane {
+    /**
+     * Admission. Returns the caller's credential, or throws (a 401 through the
+     * handler's `statusOf`) when it is missing or malformed. Runs before the
+     * body is touched, and must NOT make a network call — the surface that owns
+     * the ledger authenticates the credential itself when {@link lookup} uses
+     * it, and a second verifier here would be a second source of truth about
+     * the same key.
+     */
+    authorize(req: IncomingMessage): string;
+    /** The batch read, as the holder of the credential `authorize` returned. */
+    lookup(credential: string, inferenceIds: readonly string[]): Promise<InferenceUsageRecord[]>;
+}
+
+/**
+ * THE PER-REQUEST LEDGER WRITE — one served `/v1` inference becomes one
+ * durable, already-priced row in `public.inference_requests`.
+ *
+ * WHY THIS EXISTS. uRun answers Hugging Face's billing poll out of a ledger
+ * that, until this module, NOTHING HAD EVER WRITTEN. ENG-316 landed the table
+ * with no writer, ENG-317 landed the price machinery with no stamping, and
+ * ENG-318 landed the reader over both and stated the consequence: with every
+ * cost NULL, a poll answers `{"requests": null}` for every batch and every
+ * request is written off unbilled ~30 minutes later. This module is the hop
+ * from the correlation record the proxy already emits to a row.
+ *
+ * THE THREE RULES THIS MODULE EXISTS TO KEEP (owner ruling, ENG-409):
+ *
+ *   1. THE WRITE IS OFF THE RESPONSE PATH, and the price is stamped in that
+ *      same write. It runs from the response's `'close'` hook — after the
+ *      customer has their answer — so a ledger round trip can never be in the
+ *      latency of an inference. It is not a later sweep either: a re-price
+ *      landing after HF has been answered disagrees with a bill already
+ *      issued (ENG-406), so the row is born priced or born unpriced.
+ *
+ *   2. A LEDGER WRITE MUST NEVER FAIL AN INFERENCE REQUEST. Everything here
+ *      is fire-and-forget and cannot throw into the request path: the answer
+ *      is already delivered, the socket is already closing, and a failure is
+ *      LOUD IN THE LOG and nowhere else. {@link recordInference} returns
+ *      `void` for exactly that reason — there is no promise a caller could
+ *      accidentally await, and nothing to reject. The queue and the retries
+ *      added by ENG-415 change nothing about this: they all happen behind that
+ *      same `void`, after the customer has been answered.
+ *
+ *   3. A REQUEST THAT CANNOT BE PRICED IS WRITTEN UNPRICED, NEVER AT ZERO AND
+ *      NEVER DROPPED. Pricing itself happens in the database
+ *      (`urun_record_inference_request`), which is where `model_prices` is
+ *      readable and where a `price_version` can name the rate rows that
+ *      produced a number. This module supplies the ONE fact the database
+ *      cannot see — {@link billableOutcome} — and nothing else about money.
+ *
+ * WHAT IS DELIBERATELY NOT HERE:
+ *   * NO PRICES, NO RATES, NO MODEL NAMES, NO ARITHMETIC. Grep it: there is
+ *     no rate and no model id below. The price book is data (ENG-317) and a
+ *     rate change must take effect without a deploy.
+ *   * NO PARTNER VOCABULARY. Hugging Face's wire shape lives in
+ *     `proxy/partners/huggingface.ts` and nowhere else. What crosses this
+ *     module is uRun's own ledger vocabulary, which every distributor's
+ *     adapter and the console read alike.
+ *   * NO `gpu_seconds`, AND NO LEDGER COLUMN FOR ONE (ENG-417). Exclusive
+ *     per-request GPU occupancy is not obtainable under continuous batching,
+ *     and wall-clock there is SHARED occupancy — a per-request figure would
+ *     double-count against `usage_events.metered_gpu_seconds`, which meters
+ *     the instance once and is reduced by the hourly `usage_accrual` sweep so
+ *     that ledger sums stay exactly the metered wall-clock cost. What this
+ *     module sends instead is a LINK (`session_id`) and a WEIGHT (the
+ *     residency milliseconds), from which the share is DERIVED at
+ *     reconciliation so the shares sum to the instance total by construction.
+ *     The residency is NOT GPU time: under continuous batching the sum of
+ *     concurrent `decode_ms` EXCEEDS the session's wall-clock, which is
+ *     precisely why it is only ever meaningful as a normalized fraction.
+ *   * NO DURABLE BUFFER. Rows are queued in memory and nowhere else. The
+ *     inference-proxy Deployment declares NO VOLUMES — not a PVC, not even an
+ *     emptyDir — so there is nowhere on this pod that survives a SIGKILL, and
+ *     making one would mean a StatefulSet with a per-replica volume on an
+ *     internet-facing HA front door where a scaled-down replica's volume holds
+ *     unflushed rows forever. What survives instead is the `inference_request`
+ *     line this proxy writes to stdout for EVERY `/v1` request, which
+ *     fluent-bit ships off the pod into Loki; that is the reconciliation
+ *     record, and it is a way to KNOW what was lost rather than a way to bill
+ *     it. See {@link drainLedgerWrites}.
+ *
+ * RETRY, AND THE RULE IT LIVES UNDER (ENG-415). This module used to do NO
+ * retry, for a good reason: a retry after a timeout cannot know whether the
+ * first attempt landed, and the row it would re-send came back as an
+ * undifferentiated duplicate — so retrying turned an ambiguous outcome into a
+ * loud error that looked exactly like a forged row. That reason is now gone:
+ * the control plane's 409 carries the row already stored, so a retry whose
+ * first attempt landed resolves as `already_written` instead. Retry is
+ * therefore allowed for EXACTLY ONE failure reason and no other — see
+ * {@link isRetryable}, which is where the rule lives rather than in a
+ * judgement at the call site.
+ */
+
+/**
+ * ONE ledger row, in the ledger's own vocabulary — exactly the body the
+ * control plane's `inference-ledger` function takes.
+ *
+ * `org_id` and `api_key_id` are ABSENT BY CONSTRUCTION rather than omitted
+ * here: the control plane derives both from the credential the write rides,
+ * so there is no field on this surface that could name another org.
+ */
+interface LedgerWrite {
+    /** The uuid this request's `Inference-Id` response header carried. */
+    inference_id: string;
+    /**
+     * The identity that served it — IN THE NAMESPACE {@link identity_kind}
+     * NAMES. Never the caller's raw `model` string.
+     */
+    model_id: string;
+    /**
+     * WHICH NAMESPACE {@link model_id} SPEAKS (ENG-412): a catalog identity
+     * (`public.model_prices` vocabulary), or the caller's own deployed app slug.
+     * The two are unrelated namespaces that can nonetheless COLLIDE as strings,
+     * so the row states which one it is rather than leaving it to be inferred —
+     * and the control plane refuses to price anything but a catalog row, in the
+     * writer's predicate and again in a table CHECK.
+     */
+    identity_kind: 'catalog_model' | 'caller_org_app';
+    variant: string | null;
+    task: string;
+    http_status: number;
+    started_at: string;
+    completed_at: string;
+    /** See {@link billableOutcome}. The one fact the database cannot see. */
+    billable_outcome: boolean;
+    /**
+     * THE INSTANCE that served it (ENG-417) — the link the control plane
+     * verifies against the org before writing. NULL when this request's dial
+     * exposed no session identity; never a fabricated id.
+     */
+    session_id: string | null;
+    /** NULL = this request has no such quantity. NEVER zero of it. */
+    prompt_tokens: number | null;
+    completion_tokens: number | null;
+    output_units: number | null;
+    /**
+     * THE WEIGHT (ENG-417) — the serve runtime's own residency in whole
+     * milliseconds. An allocation input, never GPU time and never a cost. NULL
+     * means the runtime reported nothing, which is not zero: a weightless
+     * request drops out of its instance's allocation and inflates every other
+     * request's share.
+     */
+    queue_ms: number | null;
+    prefill_ms: number | null;
+    decode_ms: number | null;
+    total_ms: number | null;
+}
+/** What the control plane answers with — the row as it was actually written. */
+interface LedgerRecorded {
+    inference_id: string;
+    /** NULL = NOT YET PRICED (ENG-317). Never "free". */
+    cost_nano_usd: number | null;
+    /** `in=<model_prices.id>;out=<model_prices.id>` when priced. */
+    price_version: string | null;
+    /**
+     * Why the row carries no price, or null when it is priced. One of
+     * `not_a_catalog_model` | `outcome_not_billable` | `http_status_not_success`
+     * | `task_unit_undeclared` | `task_not_token_billed` | `token_counts_absent`
+     * | `no_active_price` | `no_active_input_price` | `no_active_output_price`.
+     * It is a NORMAL answer, not an error: no PER-TOKEN rate has been seeded
+     * yet, so this lane has nothing to price with. (Not "the price book is
+     * empty" — `model_prices` has carried live `per_minute` rows since
+     * 2026-09-10; what is absent is `per_million_input_tokens` /
+     * `per_million_output_tokens`.)
+     *
+     * Only `not_a_catalog_model` is PERMANENT. A caller-org app has no catalog
+     * identity, so no price book will ever cover it; every other reason means
+     * "not priced YET".
+     *
+     * THE TWO `task_*` REASONS ARE ENG-427, and they are the reason
+     * {@link LedgerWrite.task} is worth carrying honestly. The control plane prices a row IN THE UNIT ITS
+     * TASK DECLARES (`public.task_billing_units`), never in the unit the data
+     * happens to look like:
+     *
+     *   * `task_not_token_billed` — this lane's billable quantity is not tokens
+     *     (an image lane's is {@link LedgerWrite.output_units}), so its token counts are not
+     *     a price for it. A genuine `{0, 0}` receipt on such a lane would
+     *     otherwise settle at `cost_nano_usd = 0` PERMANENTLY — the control
+     *     plane's append-only rule allows a deliberate re-price and never a
+     *     return to NULL — which is an invoice asserting the work was free when
+     *     its billable quantity was never measured.
+     *   * `task_unit_undeclared` — nobody has declared what this task bills in,
+     *     so nothing is priced. Adding a lane to {@link ledgerTaskOf} without a
+     *     matching declaration fails CLOSED and says which fix it wants.
+     */
+    unpriced_reason: string | null;
+}
+/**
+ * WHY A LEDGER WRITE DID NOT LAND — a FIXED, SMALL vocabulary, because this is
+ * what an alert matches on.
+ *
+ * ENG-409 made the fabricated-row hazard (ENG-410) detectable and stopped
+ * there: a duplicate `inference_id` raises 23505, surfaces as a 409, and
+ * arrives here as a rejected write. But it arrived carrying only an English
+ * SENTENCE, which meant the only way to alert on "somebody wrote this row
+ * ahead of us" was a regex over prose. An alert that is a substring match on a
+ * message nobody promised to keep stable is an alert that dies silently the
+ * first time the wording is improved — and this particular alert is the ONLY
+ * signal that a customer is under-billing itself.
+ *
+ * So the reason is a FIELD, drawn from this closed set, and it is also the
+ * metric label ({@link LedgerOutcome}):
+ *
+ *   * `duplicate` — the id was already in the ledger and the stored row is
+ *     PROVABLY NOT THE ONE WE WROTE. Since the 409 carries that row (ENG-415),
+ *     a matching one is our own landed attempt and is not a failure at all
+ *     ({@link LedgerAlreadyWritten}); what reaches here is somebody else's row
+ *     — or a row we could not read back, which fails to this loud side on
+ *     purpose. This is the ENG-410 signal.
+ *   * `duplicate_foreign` — the id is taken by a row THIS ORG CANNOT READ.
+ *     `inference_id` is a global primary key, so it is reachable, and it can
+ *     never be our own write. The loudest state in the lane.
+ *   * `auth`      — the control plane refused the caller's org key.
+ *   * `surface`   — the control plane could not be reached, answered a status
+ *     we do not accept, or answered a body we could not validate. THE ONLY
+ *     RETRYABLE ONE (see {@link isRetryable}).
+ *   * `unknown`   — the lane rejected with something that carries NO reason at
+ *     all. It is its OWN value rather than being folded into `surface`
+ *     precisely so it cannot hide: a reason-less rejection is a defect in the
+ *     lane, and counting it as a surface error would file a bug as weather —
+ *     and would retry it, which is how a defect becomes a loop.
+ *   * `dwell_expired` — the row waited longer than {@link LEDGER_MAX_DWELL_MS}
+ *     and was given up on. Revenue lost, named as revenue lost.
+ *   * `dropped_on_exit` — the row was still queued when the shutdown drain ran
+ *     out. One per row, per pod, per rolling deploy that went badly.
+ */
+declare const LEDGER_FAILURE_REASONS: readonly ["duplicate", "duplicate_foreign", "auth", "surface", "unknown", "dwell_expired", "dropped_on_exit"];
+type LedgerFailureReason = (typeof LEDGER_FAILURE_REASONS)[number];
+/**
+ * Implemented by every error a {@link LedgerLane.write} may reject with, so
+ * the reason travels ON the error instead of being re-derived from its text.
+ *
+ * It is a FIELD rather than a class hierarchy on purpose: the auth rejection
+ * must stay an `instanceof ProxyAuthError` for every existing caller, and a
+ * class can only have one base.
+ */
+interface LedgerFailure {
+    readonly ledgerFailureReason: LedgerFailureReason;
+}
+/**
+ * WHY A ROW WAS NOT EVEN ATTEMPTED. Also a closed vocabulary, and for the same
+ * reason: a served request that produced no ledger row is revenue that can
+ * never be recovered, so each of these is a counted event and not merely a log
+ * line somebody might read.
+ *
+ * `not_a_catalog_model` WAS IN THIS LIST AND IS DELIBERATELY GONE (ENG-412). A
+ * request served by a caller's own deployed app used to be skipped here; it
+ * now WRITES a row in its own declared namespace (`identity_kind:
+ * 'caller_org_app'`), so nothing can emit that skip any more. A member of a
+ * closed, counted vocabulary that is structurally unreachable is a counter
+ * that can only ever read zero — it invites the reader to conclude the case
+ * never happens, when in truth the case stopped being a skip at all.
+ *
+ * DO NOT CONFUSE IT WITH THE UNPRICED REASON OF THE SAME NAME, which is alive
+ * and is the whole point of ENG-412: the control plane still answers
+ * `unpriced_reason: 'not_a_catalog_model'` for those rows (see
+ * {@link LedgerRecorded}). The row exists and is counted; it simply can never
+ * carry a price. Two vocabularies, one word, opposite states — a written row
+ * versus no row at all.
+ *
+ * `no_model_named` replaces it for the one case on that lane that still cannot
+ * be written: `model_id` is NOT NULL, a caller-org app's identity IS the
+ * caller's model string, and a request that named no model leaves nothing
+ * honest to record.
+ */
+declare const LEDGER_SKIP_REASONS: readonly ["no_response_head", "no_org", "model_unresolved", "no_model_named", "queue_full"];
+type LedgerSkipReason = (typeof LEDGER_SKIP_REASONS)[number];
+/**
+ * The TERMINAL fate of one request's ledger row, as a bounded pair of metric
+ * labels. Every `/v1` request that reaches a lane produces exactly one of
+ * these, so `sum(urun_inference_ledger_writes_total)` is the number of
+ * billable requests the proxy has accounted for — and the `skipped` and
+ * `failed` arms are the leak.
+ *
+ * EVERY VALUE IS OWNED BY THIS MODULE. `reason` is drawn from
+ * {@link LEDGER_SKIP_REASONS}, {@link LEDGER_FAILURE_REASONS} or the two
+ * pricing states below — never from the control plane's answer and never from
+ * anything a caller can influence. That is what keeps the series set bounded
+ * without a `BoundedLabel`: an `unpriced_reason` echoed verbatim into a label
+ * would let a surface that changed shape blow up the TSDB.
+ */
+type LedgerOutcome = 
+/** The row is in the ledger. `priced` / `unpriced` is ENG-317's NULL-is-not-zero distinction. */
+{
+    outcome: 'written';
+    reason: 'priced' | 'unpriced';
+}
+/**
+ * The row was ALREADY in the ledger and it is OURS — an earlier attempt
+ * landed and we never learned it (ENG-415). A terminal SUCCESS: the request
+ * is accounted for exactly once, and it is counted separately from `written`
+ * only so "how often does the write path go ambiguous" is answerable.
+ */
+ | {
+    outcome: 'already_written';
+    reason: 'priced' | 'unpriced';
+}
+/** No row was attempted. */
+ | {
+    outcome: 'skipped';
+    reason: LedgerSkipReason;
+}
+/** A row was attempted and did not land. */
+ | {
+    outcome: 'failed';
+    reason: LedgerFailureReason;
+};
+/**
+ * The ledger write seam. Only the HOSTED endpoint supplies one (the write
+ * rides the caller's own org API key to the control plane; this process holds
+ * no database credential). A proxy WITHOUT one does not participate in the
+ * ledger at all — the `usage` / `supportsImages` posture: configured absence,
+ * declared at the seam, not a degradation discovered at runtime. The local
+ * CLI proxy is single-tenant and bills nothing, so it has none.
+ */
+interface LedgerLane {
+    /**
+     * Write one row, as the holder of the credential on `req`. The request is
+     * over by the time this is called; `req` is carried only for its
+     * `Authorization` header, never re-read.
+     */
+    write(req: IncomingMessage, entry: LedgerWrite): Promise<LedgerRecorded>;
+    /**
+     * Count ONE terminal outcome. REQUIRED, unlike {@link report} — which has a
+     * real default (this process's stdout) — because there is no default for
+     * "count it nowhere" that is not a silent no-op. A lane that genuinely
+     * counts nothing has to say so at the seam, in code a reviewer can see.
+     *
+     * This is the alerting surface for ENG-410: `outcome="failed"` with
+     * `reason="duplicate"` is the fabricated-row signal, and the log line is
+     * only the per-request detail behind it.
+     */
+    observe(outcome: LedgerOutcome): void;
+    /**
+     * Where this lane's own structured diagnostics go — one newline-terminated
+     * JSON object per event. Absent, they go to this process's stdout (the
+     * hosted endpoint's collected container log). Injectable so tests assert on
+     * them without racing the process streams.
+     *
+     * These are DELIBERATELY NOT the `requestLog` sink: that sink carries
+     * exactly one `inference_request` record per `/v1` request and readers count
+     * on that.
+     */
+    report?(line: string): void;
+}
+
+/**
+ * The shared Responses execution/store seam — the ONE execution + event-
+ * envelope path and the authorized tenant store, imported by BOTH the HTTP
+ * SSE lane (server.ts) and the `/v1/responses` WebSocket lane
+ * (responses-ws.ts). This module deliberately imports NO transport acceptor
+ * and NO HTTP lane module: its only imports are type-only, so the module
+ * graph server.ts → responses-ws.ts → responses-turn.ts is acyclic and no
+ * Vitest/Bun/Node module-evaluation order can observe an uninitialized
+ * binding (the constructor-failure class of bug this extraction removes).
+ */
+
+/** The request envelope every Responses-shaped upstream call carries. */
+interface ResponsesCreateParams {
+    model?: string;
+    input: unknown;
+    stream?: boolean;
+    tools?: unknown;
+    tool_choice?: unknown;
+    temperature?: number;
+    max_output_tokens?: number;
+    /**
+     * System/developer instructions, forwarded to the serve envelope — where
+     * they become ONE prepended `system`-role message (the protocol's native
+     * per-request system input; there is NO envelope-level instructions field).
+     * Typed `string` end to end (transport/encode.ts) so no cast bridges the seam.
+     */
+    instructions?: string;
+    top_p?: number;
+    stop?: string[];
+    /**
+     * Reasoning controls (urun-python #1667): forwarded VERBATIM to the serve
+     * envelope — `chat_template_kwargs.enable_thinking:false` is the think-off
+     * switch. Absent -> absent (no default injection; server-side validation).
+     */
+    reasoning_effort?: string;
+    chat_template_kwargs?: Record<string, unknown>;
+    /**
+     * OpenAI `response_format` — structured output (ENG-310). On the Responses
+     * lane the caller spells this `text.format`; `textFormatOf` lifts it onto
+     * this ONE field so both lanes hand the serve envelope the same key.
+     * Forwarded verbatim — the serve runtime is the one validator.
+     */
+    response_format?: unknown;
+}
+/** How one pinned session ended (the native phase machinery's terminal step). */
+interface SessionEndInfo {
+    /**
+     * Milliseconds until the session's native deadline (`endsAt`), or null when
+     * the app declared no maximum session length. NOTE (missing primitive,
+     * called out in the PR): core exposes no PRE-expiry notice event — this
+     * callback fires AT terminal loss, so timeLeftMs is ~0 on expiry.
+     */
+    timeLeftMs: number | null;
+    /** The terminal reason (expired / ended / error), for the loud close. */
+    reason: string;
+}
+/** The upstream calls the proxy makes — injectable (tests; alt transports). */
+interface ProxyClients {
+    /**
+     * The NON-SECRET tenancy label of the org this backhaul belongs to — the
+     * control plane's org id, set by the hosted registry from the verified
+     * `CallerIdentity` (`hosted/tenants.ts`). The request handler copies it onto
+     * the request's `InferenceTurn`, which is what puts an `org` label on the
+     * Prometheus series and an `org` field on the billing record.
+     *
+     * THE ORG, NEVER THE KEY: the Bearer key is the credential on this surface,
+     * so it must never reach a metric, a log, or a dashboard. Absent on the
+     * single-tenant local proxy and on hand-built test clients.
+     */
+    readonly tenant?: string;
+    /**
+     * `UrunResponses(session).responses.create` — an async iterable of Responses
+     * stream events.
+     *
+     * `onDial` is WHAT THE DIAL REPORTS ABOUT ITSELF (ENG-417 + ENG-414): the
+     * implementation calls it once PER DIAL with a {@link DialReport} — the uRun
+     * session id of the backhaul it is ABOUT TO USE, and the billing identity
+     * that dial's acquisition resolved. So a request that re-homes reports the
+     * REPLACEMENT on both counts: the instance that actually served it, and the
+     * identity it was actually served under.
+     *
+     * IT IS A SECOND ARGUMENT, NOT A FIELD ON THE ENVELOPE, and that is
+     * load-bearing. `params` is forwarded VERBATIM to the serve runtime by every
+     * implementation of this seam, including hand-built embedder clients; a
+     * function smuggled onto it would reach a JSON serializer, be dropped
+     * silently, and leave one implementation (the one that remembered to strip
+     * it) behaving differently from the rest. Out of band, the envelope stays
+     * exactly what it was and an implementation that ignores `onDial` simply
+     * records no link.
+     *
+     * IT IS A CALLBACK RATHER THAN A RETURN VALUE because the answer is not
+     * known when `createResponse` returns: `rehome.ts` dials inside the async
+     * generator and may dial a SECOND time before the first event is yielded.
+     * Asking beforehand — an earlier draft of ENG-417 did — has two defects at
+     * once: it records a session the turn may abandon, and it ALLOCATES a pooled
+     * backhaul for requests still going to be refused by local validation, which
+     * is GPU capacity spent on a 400.
+     *
+     * THE IDENTITY ARRIVES THROUGH `ModelRouter.sessionFor` AND NOT FROM THE
+     * POOL ENTRY, and a reader who does not know why will "simplify" it back
+     * into the bug. The obvious-looking move is to widen
+     * `RehomeOptions.sessionIdOf` the way the session id arrived. IT CANNOT
+     * WORK: `entry` is the GENERIC pooled session (`rehome.ts` is parameterised
+     * over it) and knows nothing about models, so the identity is not derivable
+     * from it. The other obvious move — resolving the identity separately inside
+     * the dial loop — is worse: it would be a SECOND RESOLUTION of the same
+     * question, which is precisely the defect that got ENG-417's pre-dial pin
+     * rejected in review (a resolution taken at a different moment from the dial
+     * can answer differently, and then the row names a variant nobody served).
+     * So the acquisition returns the identity alongside the entry, and the loop
+     * reports what it already resolved.
+     *
+     * BOTH IDENTITY FLAVOURS RIDE IT. The catalog `(model_id, variant)` a row is
+     * priced on, and the caller-org APP SLUG that ENG-412 made billing-bearing —
+     * it lands in `model_id` with `identity_kind: 'caller_org_app'`, on rows
+     * that previously were not written at all. They had the identical re-home
+     * window and they close by the same line: the dial reports whichever flavour
+     * it resolved.
+     *
+     * WIDEN {@link DialReport}; do not add a second callback beside it. Two
+     * callbacks firing from the same loop about the same dial would be two
+     * things that can disagree, which is the whole defect this seam exists to
+     * remove.
+     */
+    createResponse(params: ResponsesCreateParams, onDial?: DialObserver): Promise<AsyncIterable<unknown>> | AsyncIterable<unknown>;
+    /** `listModels(...)` result (an OpenAI model list object). */
+    listModels(): Promise<unknown>;
+    /**
+     * The OpenRouter provider document (`GET /v1/models?format=openrouter`).
+     * Optional at the seam: hand-built test clients may omit it, in which case
+     * the format=openrouter branch answers 501 — loud, never a silent empty.
+     */
+    openRouterModels?(): Promise<unknown>;
+    /**
+     * The Images lane's capability gate (images.ts `ImageModelGate`), backed by
+     * ModelRouter.supportsImages — the caller-org catalog's modality metadata,
+     * per-caller by construction; never function-name inference. Optional at
+     * the seam: hand-built clients may omit it, in which case the mounted
+     * image lanes answer 501 — loud, never a silent allow-all.
+     */
+    supportsImages?(model: string | undefined, mode: 'generation' | 'edit'): Promise<boolean>;
+    /**
+     * The realtime/audio lane's modality gate (openai-realtime/binding.ts),
+     * backed by ModelRouter.supportsAudio — the caller-org catalog's `task`
+     * column (stt | tts, invariant across placements), per-caller by
+     * construction; never function-name inference. Optional at the seam like
+     * supportsImages: hand-built clients may omit it, in which case the
+     * realtime lane refuses the upgrade LOUDLY (501) — never a silent
+     * allow-all, and never a chat model binding an audio session.
+     */
+    supportsAudio?(model: string | undefined): Promise<boolean>;
+    /**
+     * `GET /v1/images/models` — the image-capable slice of the model surface
+     * (ModelRouter.imageModelList: deployed task-image apps + the shared block
+     * joined against the catalog). Optional at the seam for the same reason;
+     * its absence is the loud 501, never a silently empty list.
+     */
+    listImageModels?(): Promise<unknown>;
+    /**
+     * THE PRE-DIAL DEFAULT FOR THE LEDGER'S BILLING IDENTITY
+     * (ModelRouter.catalogIdentityFor): the CATALOG `(model_id, variant)` a
+     * request's `model` actually resolved to, or `null` when it names no catalog
+     * model (a caller-org app, whose identity is an app slug — a different
+     * namespace from `model_prices.model_id`).
+     *
+     * The ledger prices on `(model_id, variant)`, and the caller's raw string is
+     * not that: a bare catalog id resolves to the model's `compat_default`
+     * variant, so recording the string would file the request under a variant
+     * nobody served.
+     *
+     * THE DIAL HAS THE LAST WORD (ENG-414). What a served row records is the
+     * identity `onDial` reported, off the acquisition that dial used — so a
+     * re-homed request is billed on the replacement. This seam is what a request
+     * that reaches NO dial records instead, which is why it is still resolved
+     * on the request path.
+     *
+     * REQUIRED AT THE SEAM (ENG-429), unlike `supportsImages`. ENG-414 changed
+     * what an omission MEANS: a backhaul with no `catalogIdentity` but a
+     * dialling `createResponse` used to write no ledger row at all, and now
+     * writes — and prices — one on the dial's own report. Honest, but it means
+     * a lane could acquire BILLING behaviour by OMITTING a member, which is the
+     * wrong direction for a default on a revenue path. So "no seam" is a
+     * COMPILE ERROR now, the same move as the exhaustive `Record<...>`
+     * registration checks used elsewhere in this codebase: a contract the
+     * typechecker holds, not a convention a reviewer must notice. An implementer
+     * that genuinely has no catalog oracle says so EXPLICITLY — a function of
+     * its own, in code a reviewer can see — never by leaving the member out, and
+     * never an invented identity. (The runtime guard in server.ts
+     * `pinCatalogIdentity` stays for UNTYPED embedders: the seam is a public
+     * surface callable from plain JS, where a member can still be absent at
+     * runtime, and the guard's answer there remains the loud `unresolved` pin.)
+     */
+    catalogIdentity(model: string | undefined): Promise<{
+        model_id: string;
+        variant: string;
+    } | null>;
+    /**
+     * THE CALLER-ORG APP's OWN IDENTITY (ENG-412): the app slug `model` actually
+     * RESOLVES to, for the lane where {@link catalogIdentity} answers null. Like
+     * {@link catalogIdentity} it is the PRE-DIAL DEFAULT — the dial reports this
+     * flavour too, and has the last word (ENG-414).
+     *
+     * IT IS NOT THE CALLER'S RAW STRING. Routing trims, length-caps and matches
+     * that string before selecting an app, so a differently cased, punctuated or
+     * whitespace-padded name is served by one canonical slug while the raw value
+     * says something else — and the ledger would then file two spellings of the
+     * same app as two different identities, which no app-level reconciliation
+     * can undo afterwards.
+     *
+     * CHEAP AND ALLOCATION-FREE: it rides `ModelRouter.resolveTarget`, whose app
+     * listing, catalog and shared block are cached promises. It opens no session
+     * — asking which app would serve must never BE the thing that spends GPU
+     * capacity.
+     */
+    servingAppSlug?(model: string | undefined): Promise<string | null>;
+    /**
+     * Open (or reuse) the NATIVE audio lanes on the pooled session `model` routes
+     * to — the same first-party machinery as RealtimeClient.enableAudio
+     * (transport/media.ts `enableSessionAudio`: AudioBridge over the session's
+     * `audio` stream lane at 24 kHz). One lane per pooled
+     * session; repeat calls return the same lane. Optional at the seam because
+     * text-only embeddings exist — but a surface that RECEIVES audio while the
+     * embedder wired no `openAudio` must fail LOUD, never drop chunks.
+     */
+    openAudio?(model: string | undefined): Promise<ProxyAudioLane>;
+    /**
+     * Open (or reuse) the NATIVE video FRAME lane on the pooled session `model`
+     * routes to (transport/media.ts `enableSessionVideo`: discrete JPEG frames →
+     * `stream('rt-video-in').emit`, the §5 named-DATA image-bytes path — NOT the
+     * RTP media plane, which requires an already-H.264-encoded track). One lane
+     * per pooled session; repeat calls return the same lane. Optional at the seam
+     * because text-only embeddings exist — but a surface that RECEIVES video
+     * frames while the embedder wired no `openVideo` must fail LOUD, never drop
+     * frames.
+     */
+    openVideo?(model: string | undefined): Promise<ProxyVideoLane>;
+    /**
+     * Open (or reuse) the NATIVE video OUTPUT lane on the pooled session
+     * `model` routes to (transport/video-out.ts `openSessionVideoOutLane`):
+     * decoded spec-v1 records consumed from the session's named §5
+     * `rt-video-out` downstream. The Live adapter fans each record onto the
+     * SAME Bidi WS as an extension server message (spec v2, WS-inline) — no
+     * side-channel transport. Optional at the seam; an ABSENT seam means the
+     * `urun.videoOut` capability is refused by omission in setupComplete
+     * (vanilla parity), while a wired seam that cannot open the lane must
+     * throw LOUD — never a quiet downgrade.
+     */
+    openVideoOut?(model: string | undefined): Promise<ProxyVideoOutLane>;
+    /**
+     * SESSION-IDENTITY SEAM (ModelRouter.handleFor): the opaque stable handle
+     * for the pooled session currently serving `model`'s turns. Derived from
+     * native identity (app slug + uRun session id) — the same identity the
+     * serve-side session-affinity tag rides (urun-python#1556/#1582).
+     */
+    sessionHandle(model: string | undefined): Promise<string>;
+    /**
+     * createResponse PINNED to the exact session a handle names
+     * (ModelRouter.sessionForHandle). Throws SessionGoneError LOUDLY when that
+     * session is gone or was replaced — never silently opens a fresh session
+     * while claiming resume. Deliberately NO re-home on this path: re-homing
+     * would swap the pinned session out from under the caller.
+     */
+    createResponseOn(handle: string, params: ResponsesCreateParams): Promise<AsyncIterable<unknown>> | AsyncIterable<unknown>;
+    /**
+     * Subscribe to the pinned session's terminal end via core's NATIVE phase
+     * machinery (Session.onPhase → terminal 'expired'/'ended'/'error'). Fires
+     * `cb` once. Throws SessionGoneError if the handle's session is already
+     * gone — which doubles as the loud reattach check at resume time. Returns
+     * the unsubscribe.
+     */
+    onSessionEnd(handle: string, cb: (end: SessionEndInfo) => void): Promise<() => void>;
+}
+/**
+ * The audio lane handle `openAudio` returns — structurally the transport
+ * AudioBridge (media.ts): base64 PCM16 @24 kHz mono in both directions.
+ */
+type ProxyAudioLane = Pick<AudioBridge, 'appendInputAudio' | 'onOutputAudio'>;
+/**
+ * The video frame-lane handle `openVideo` returns — structurally the
+ * transport VideoFrameLane (media.ts): one raw encoded JPEG frame per call,
+ * input-only (Live-style protocols have no video OUT modality).
+ */
+type ProxyVideoLane = Pick<VideoFrameLane, 'sendInputFrame'>;
+/**
+ * The video-OUT lane handle `openVideoOut` returns — structurally the
+ * transport VideoOutLane (video-out.ts): the codec plus frame/error fan-out
+ * the WS-inline delivery subscribes.
+ */
+type ProxyVideoOutLane = Pick<VideoOutLane, 'codec' | 'onOutputFrame' | 'onLaneError'>;
+/**
+ * Per-request `ProxyClients` resolution — the seam the HOSTED multi-tenant
+ * server (`src/hosted/`) plugs into so ONE handler implementation serves
+ * every org: the hosted server resolves the caller's org from its Bearer API
+ * key and returns THAT org's backhaul. The local CLI passes a fixed
+ * `ProxyClients` instead; both go through the identical handler body.
+ *
+ * Throwing from here is the loud path: the thrown error surfaces in the
+ * lane's native error envelope (see {@link ProxyHandlerOptions.statusOf}).
+ */
+type ProxyClientsFor = (req: IncomingMessage) => ProxyClients | Promise<ProxyClients>;
+interface ProxyHandlerOptions {
+    /** A fixed backhaul (local CLI) or a per-request resolver (hosted server). */
+    clients: ProxyClients | ProxyClientsFor;
+    /** Optional bearer the local agent must present (never forwarded upstream). */
+    apiKey?: string;
+    /**
+     * WHAT this proxy serves (app/org/fn/base_url + proxy_version), surfaced as
+     * the `identity` block on `GET /stats` so a second `urun compat` invocation
+     * can reuse this proxy iff the identity matches its own exactly. Only the
+     * standalone `urun compat proxy` command sets it — a launch-mode proxy is
+     * child-owned (it dies with its child) and an embedder that omits it is
+     * simply never reused.
+     */
+    identity?: ProxyIdentity;
+    /**
+     * Map a thrown error onto an HTTP status + error `type` before the generic
+     * 500. The hosted server uses it to turn its auth/tenancy failures into a
+     * 401 in the OpenAI envelope. Returning null means "not mine" — the error
+     * takes the ordinary loud 500 path.
+     */
+    statusOf?: (err: unknown) => {
+        status: number;
+        openaiType: string;
+        anthropicType: string;
+    } | null;
+    /**
+     * Where the per-request structured log line goes — ONE newline-terminated
+     * JSON object per `/v1` request, carrying the request's `Inference-Id`
+     * (proxy/inference-id.ts `inferenceRequestLine`) plus method, path, status
+     * and whether the answer was delivered / failed mid-stream, written when the
+     * response closes (so streams and client aborts are recorded too). This is
+     * the billing correlation record a later usage ledger is keyed on, so it is
+     * emitted unconditionally — never behind a verbosity flag.
+     *
+     * Absent, the record goes to this process's stdout through the repo's
+     * canonical guarded write (`server.ts` `writeInferenceLogToStdout`), which is
+     * the hosted endpoint's collected container log. The local CLI proxy passes
+     * its own sink instead, because the operator owns that terminal — see
+     * `proxy/cli.ts` `startProxy`. Injectable so tests assert on the lines
+     * without racing the process streams.
+     */
+    requestLog?: (line: string) => void;
+    /**
+     * THE CANONICAL USAGE-QUERY SEAM (`POST /v1/usage/requests`, and the
+     * Hugging Face translator over it) — a batch lookup of what the per-request
+     * inference ledger holds for a list of `Inference-Id`s, scoped to the
+     * caller's own org. See proxy/usage.ts.
+     *
+     * Only the HOSTED endpoint supplies one (the read rides the caller's own
+     * org API key to the control plane; this process holds no database
+     * credential). A proxy without it answers those routes with a LOUD 501 —
+     * the `supportsImages` posture — and never with an empty result, which a
+     * billing caller cannot tell from "nothing is priced yet".
+     */
+    usage?: UsageLane;
+    /**
+     * THE PER-REQUEST LEDGER WRITE SEAM (proxy/ledger.ts) — one durable,
+     * already-priced row per billable `/v1` request, written from the response's
+     * `'close'` hook and therefore OFF the response path.
+     *
+     * Only the HOSTED endpoint supplies one (the write rides the caller's own
+     * org API key to the control plane; this process holds no database
+     * credential). A proxy WITHOUT one does not participate in the ledger at
+     * all — the `usage` / `supportsImages` posture of declared absence. The
+     * local CLI proxy is single-tenant and bills nothing, so it has none.
+     *
+     * It is deliberately NOT a place to do work on the hot path, and it cannot
+     * be: `recordInference` is fire-and-forget, returns void, and never throws.
+     */
+    ledger?: LedgerLane;
+    /**
+     * The SECOND sink for the very same per-request record `requestLog`
+     * serializes — the hosted endpoint passes its Prometheus collector
+     * (`proxy/metrics.ts` `InferenceMetrics.observe`). Called once per `/v1`
+     * request, from the same `'close'` hook, with the same object.
+     *
+     * Optional because the local CLI proxy publishes no metrics port; absent, a
+     * request is logged and not counted. It is deliberately NOT a place to do
+     * work: it runs on the response's close hook, so anything slow here delays
+     * the socket teardown.
+     */
+    observe?: (record: InferenceRecord) => void;
+}
+
+export { type DialObserver as D, type InferenceRecord as I, type LedgerFailure as L, ModelRouter as M, type ProxyClients as P, SessionGoneError as S, UnknownModelError as U, type DialReport as a, type InferenceUsageRecord as b, type LedgerOutcome as c, type LedgerRecorded as d, type LedgerWrite as e, type ProxyHandlerOptions as f, type ProxyIdentity as g, type ProxyVideoOutLane as h, type UsageRowReporter as i };