@urun-sh/openai 0.5.5 → 0.6.0

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

@@ -0,0 +1,2394 @@
+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-BsuLqlID.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, ready, ready_runtimes,
+ *                                    ready_since }],
+ *       regions: [...], compliance: { zdr, hipaa } }
+ *
+ * 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 row's output-free opt-in (owner decision 2026-09-21, the
+     * `reflex-latest:bf16` decision lane): a ZERO per-token OUTPUT rate is a
+     * deliberate published price for this endpoint — the model is a
+     * non-generative decision/action surface whose tokens are billed on
+     * input alone, so the OpenRouter document emits `cost_usd: '0'`
+     * completion pricing instead of refusing it. Absent (pre-flag edge
+     * function) and null both mean NOT opted in — the zero-output refusal
+     * stands.
+     */
+    output_free?: boolean | null;
+    /**
+     * Runtime-plane readiness (up-debounce, down-immediate upstream). ABSENT
+     * on blocks from an edge function that predates the readiness seam — the
+     * OpenRouter document builder treats that as NOT ready, loudly (see
+     * openrouter-doc.ts); `null` is likewise unknown, not ready.
+     */
+    ready?: boolean | null;
+    /** How many ready runtimes stand behind `ready` (null when unknown). */
+    ready_runtimes?: number | null;
+    /** ISO 8601 instant the endpoint became (and stayed) ready; null when not. */
+    ready_since?: string | null;
+}
+/** The catalog edge function's `shared` block. */
+interface SharedCatalogBlock {
+    shared_org_id: string;
+    endpoints: SharedEndpointRow[];
+    /**
+     * Deployment-topology region codes (AWS-style, e.g. 'us-west-2') — the
+     * physical surface the shared endpoints serve from. Absent/empty means the
+     * topology is undeclared.
+     */
+    regions?: string[] | null;
+    /**
+     * Operator-declared data-handling posture (zero data retention, HIPAA).
+     * Present ONLY when an operator has declared BOTH flags — and nothing
+     * else: the wire contract is exactly {zdr, hipaa}, and the parser treats
+     * a further key as a catalog defect. ABSENT means UNDECLARED — never a
+     * default, because these are claims about where customer data goes.
+     */
+    compliance?: {
+        zdr: boolean;
+        hipaa: boolean;
+    } | null;
+}
+
+/**
+ * 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 MOST 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) — with ONE owner-ratified
+ * exception: `reflex-latest:bf16` is a non-generative decision lane whose
+ * catalog row declares `output_free` (owner decision 2026-09-21), so its
+ * ZERO completion rate is the published price (`cost_usd: '0'`), billed
+ * on input alone. The zero reaches this builder only through
+ * model-prices.ts's allowlist (routing resolves prices against the
+ * shared block's `output_free` set); the builder itself just renders
+ * whatever a resolved price says.
+ *
+ * The full closed-value-domain schema ships as OpenAPI 3.1 at
+ * openrouter.ai/docs/assets/provider-monitor-schema-v2.openapi.json.
+ *
+ * THE OPERATIONAL FIELDS (schema 2.4, the "launch control" surface):
+ * - `is_ready` is the shared endpoint's SELLABLE readiness:
+ *   `runtime ready AND priced` — `endpoint.ready === true` AND a per-token
+ *   price row for this exact (model_id, variant). Priced means the price
+ *   book RESOLVES a pair for the SKU: an output-free row's `{input: >0,
+ *   output: 0}` is a resolved pair (model-prices.ts's allowlist decides,
+ *   from the shared block's `output_free` flag), so an input-priced,
+ *   output-free, runtime-ready endpoint IS ready. An unpriced SKU is
+ *   never sellable: OpenRouter's `is_ready: false` keeps an endpoint
+ *   hidden, and we must never expose a model we cannot bill, so a ready
+ *   runtime without a price is emitted NOT ready. Runtime readiness is
+ *   THE ONE DELIBERATELY CONSERVATIVE DEFAULT
+ *   in this module: a block whose endpoints carry NO `ready` field at all
+ *   predates the readiness seam (the catalog edge function is not yet
+ *   redeployed), and UNKNOWN READINESS IS NOT READINESS — every such
+ *   endpoint is declared `is_ready: false` AND one loud warning per
+ *   document build names the missing seam, so the default is visible,
+ *   never silent. A `null` ready is likewise unknown, not ready. Endpoints
+ *   of the SAME identity follow the existing dedup rule (first occurrence
+ *   in the deterministic shared-block order wins).
+ * - `is_free` is `false` for every declared model: we bill. An unpriced row
+ *   is UNPRICED, not free — `is_free: true` would mint a `:free` SKU whose
+ *   every price OpenRouter ignores. The same holds for an output-free row:
+ *   its input side bills, so it is not a `:free` SKU either — the zero
+ *   lives in the completion `cost_usd`, nowhere else.
+ * - `deprecation_date` is OMITTED: the schema makes it optional and no
+ *   shared endpoint has a deprecation schedule to declare.
+ * - `datacenters` maps the block's deployment-topology region codes
+ *   (AWS-style) to the schema's `{ country_code, region }` elements through
+ *   an EXPLICIT region→country table (a country cannot be derived from a
+ *   prefix — sa-east-1 is BR). Unmappable codes are omitted and WARNED,
+ *   never guessed; absent/empty topology omits the field.
+ * - `compliance` is emitted ONLY when the block's `compliance` is present:
+ *   zdr/hipaa are claims about where customer data goes, DECLARED by an
+ *   operator — never inferred, never defaulted, and never half-emitted.
+ * - `tokenizer` names the model family the catalog row's `hf_repo`
+ *   carries (e.g. `Inferact/Qwen3.8-27B-NVFP4` → `Qwen`) through an
+ *   explicit, BOUNDED table over the repo's model-NAME tokens — whole
+ *   tokens only, version-aware for the families whose generations differ
+ *   (llama-2 is not llama-3); a repo that names no known family OMITS the
+ *   field.
+ */
+
+type OpenRouterProviderDoc = {
+    data: OpenRouterProviderModel[];
+};
+/** One schema-2.4 `datacenters` element: ISO 3166-1 alpha-2 country + region. */
+interface OpenRouterDatacenter {
+    country_code: string;
+    region?: string;
+}
+/** The operator-declared data-handling posture (schema-2.4 `compliance`). */
+interface OpenRouterCompliance {
+    zdr: boolean;
+    hipaa: boolean;
+}
+interface OpenRouterProviderModel {
+    schema_version: '2.4';
+    /**
+     * The EXACT id OpenRouter sends back as `model`: the verbatim
+     * `<model_id>:<variant>` external identity (see MODEL-IDENTITY.md) — never
+     * the deployment slug.
+     */
+    id: string;
+    name: string;
+    created: number;
+    /** Valid enum: int4|int8|fp4|mxfp4|nvfp4|fp6|fp8|mxfp8|fp16|bf16|fp32|null. */
+    quantization: string | null;
+    /** Tokenizer family name (e.g. 'Qwen'); omitted when the repo names none. */
+    tokenizer?: string;
+    description: string;
+    hugging_face_id: string;
+    /** SELLABLE readiness — `endpoint.ready === true` AND a per-token price. */
+    is_ready: boolean;
+    /** `false` always: we bill; an unpriced row is unpriced, not free. */
+    is_free: boolean;
+    input_modalities: Array<Record<string, unknown>>;
+    output_modalities: Array<Record<string, unknown>>;
+    /** Physical serving topology; omitted when the block declares none. */
+    datacenters?: OpenRouterDatacenter[];
+    /** Operator-declared posture; omitted entirely when undeclared. */
+    compliance?: OpenRouterCompliance;
+}
+/**
+ * The resolution of ONE tts model's voice set — ONE answer BOTH consumers
+ * read, so the lane can never drift from the listing:
+ *   - `published` is the set the model's /v1/models entry carries ([] =
+ *     publish none).
+ *   - `defect` is non-null ONLY when the catalog PRESENTED
+ *     `engine_args.voices` that could not be vouched (empty, malformed, or
+ *     not an identical non-empty string array on every GPU placement). The
+ *     publish side keeps its long-standing posture through a defect (the
+ *     card list for the qwen3 class, nothing otherwise — the listing is a
+ *     best-effort enrichment), but the speech lane must never silently
+ *     validate against the card's nine over a catalog that SPOKE — it fails
+ *     loud (500) on `defect` instead.
+ */
+interface SpeechVoicesResolution {
+    /** The voices the /v1/models entry publishes for this model ([] = none). */
+    readonly published: readonly string[];
+    /** Why the catalog's own voices value could not be vouched, when it presented one. */
+    readonly defect: string | null;
+}
+
+/**
+ * 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 app that declares serves="openai"   →
+ *      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 has NO function declaring the
+ *      serve protocol (`serves="openai"`)                   → 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;
+    /** The serve function the BACKHAUL dials on the app (URUN_FUNCTION); no
+     * longer a routing membership test — routing reads `serves`. */
+    function_name?: string | null;
+    /** Declared serve protocol (`"openai"`), or null/absent = undeclared = the
+     * proxy must not route this app. THE routing membership test. */
+    serves?: string | null;
+    deployment_status?: string | null;
+}
+/**
+ * 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;
+    /**
+     * The voices a `tts`-task model synthesizes under (ENG-331 — OpenAI's
+     * speech API names a voice per request, so a caller needs the list).
+     * Catalog-sourced from `engine_args.voices` when the row carries it;
+     * otherwise the qwen3 CustomVoice timbres for that one model class (see
+     * openrouter-doc.ts `QWEN3_CUSTOMVOICE_VOICES`). Absent on every non-tts
+     * entry, and on tts entries whose voices the catalog does not vouch.
+     */
+    voices?: string[];
+}
+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 `fnName` (the function the backhaul
+ * dials) 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;
+    /**
+     * Shared lanes only: the pod org (`shared.shared_org_id` of the block that
+     * resolved the lane). THE STATELESS DECISION TOKEN'S PROVIDER CLAIM — the
+     * decision intake's provider-aware org gate accepts tenant OR provider
+     * matching the pod org, and on a shared pod the caller-org tenant differs
+     * from the shared-org pod. Sourced from the SAME block that resolved the
+     * lane, never a second env spelling, so key and pod-org identity cannot
+     * drift.
+     */
+    sharedOrgId?: 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 the BACKHAUL dials on the resolved app (URUN_FUNCTION)
+     * — shared lanes may pin their own per-row function instead (RouteTarget
+     * fnName). NOT a routing membership test any more: routing reads the app's
+     * declared `serves` protocol (see {@link ModelRouter.servable}).
+     */
+    fnName: string;
+    /**
+     * Open a backhaul session for a resolved dial target (called at most once
+     * per pool key). The SECOND argument is the POOL KEY the entry will
+     * occupy — the same string `sessionFor`/`speechSessionFor` store it under
+     * — so an implementer can wire per-slot machinery (the backhaul's
+     * gone-watch eviction and the speech lane's subject scoping) against the
+     * slot the entry ACTUALLY holds: a lane-scoped open (`speech:<slug>`)
+     * that wired its eviction on the unscoped key would leave a dead entry
+     * stranded in the pool forever. Implementers that ignore it behave
+     * exactly as before.
+     */
+    openSession: (target: RouteTarget, poolKey: string) => 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;
+    /**
+     * OWNER RULING (2026-09-21, shared-endpoints inference-proxy): the model
+     * listing is the platform's SHARED surface and nothing else. When true,
+     * {@link ModelRouter.modelList} advertises ONLY the catalog `shared`
+     * block's endpoints and never the caller-org's deployed apps — the same
+     * id space {@link ModelRouter.openRouterModels} publishes, so every
+     * listing format agrees. The hosted lane (hosted/tenants.ts) sets this;
+     * the local `urun compat` lane leaves it absent and behaves
+     * byte-for-byte as before (a caller's own apps stay listed there).
+     * An absent shared block (or none configured) is an EMPTY listing —
+     * "no shared models" is an answer, never a fallback to the org's apps.
+     */
+    sharedOnlyListing?: boolean;
+}
+/**
+ * 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.
+     *
+     * `outputFree` is the shared block's EXACT `(model_id, variant)` opt-in
+     * set ({@link outputFreeKey} keys, built from `SharedEndpointRow.output_free`):
+     * the only rows whose zero OUTPUT rate the resolver may publish — see
+     * model-prices.ts for the one-flag-one-lane rule. Absent/empty set: every
+     * zero keeps the refusal.
+     *
+     * 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;
+    /**
+     * The EXACT `(model_id, variant)` pairs the shared block declares
+     * output-free ({@link outputFreeKey} keys) — the only allowlist
+     * resolveTokenPrices accepts a zero OUTPUT rate against. Only a
+     * `true` flag contributes: absent and null are the un-flagged default.
+     */
+    private outputFreeKeys;
+    /**
+     * 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 declaring the OpenAI-compatible
+     * serve protocol (`@app.function(serves="openai")`). The OLD rule — a
+     * function literally named `serve` — is GONE: the name carried no
+     * capability meaning (an app with a function named `serve_runtime` could
+     * never be routed), and the declaration is what the deploy actually knows.
+     * `fnName` survives only as the function the BACKHAUL dials.
+     */
+    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>;
+    /**
+     * THE STATELESS DIRECT PATH's resolution seam: the dial target for a
+     * model — the pure resolution (app slug, fn, shared flag) with NO session
+     * opened. The stateless decision dial (stateless-dispatch.ts) uses it to
+     * discover ready replicas for the resolved (org, app, fn) instead of
+     * minting a session; every public no-dial accessor above rides this same
+     * private resolution.
+     */
+    targetFor(model: string | undefined): Promise<RouteTarget>;
+    /**
+     * 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;
+    }>;
+    /**
+     * The SPEECH lane's pooled session for a model — the SAME resolution and
+     * acquisition as {@link sessionFor}, stored under a LANE-SCOPED pool key
+     * (`speech:` + the ordinary key) so the session a speech collector
+     * subscribes to is one NO interactive lane (text turns via
+     * `rehomingCreateResponse`/`sessionFor`, Realtime and Gemini Live via
+     * `openAudio`/`handleFor`) can ever resolve: the per-session AudioBridge
+     * broadcasts every untagged output frame to every subscriber, so a shared
+     * session is exactly the mixed-audio defect (greptile urun-ts#500). The
+     * entry's OWN lifecycle (gone-watch eviction, wedge re-salt, billing
+     * identity) is identical — only the slot differs, which is the whole point.
+     */
+    speechSessionFor(model: string | undefined): Promise<{
+        app: string;
+        entry: S;
+        identity: TurnCatalogIdentity;
+    }>;
+    /**
+     * The ONE acquisition path both lanes ride — opened lazily under exactly
+     * `key`, reused afterwards. A failed open never poisons the slot.
+     */
+    private acquire;
+    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 (a), SPEECH lane: the handle for the SPEECH-scoped
+     * pooled session ({@link speechSessionFor} — `speech:<key>` as the handle's
+     * pool key, so {@link sessionForHandle} resolves exactly the speech slot).
+     * The handle codec needs no change: it already carries whatever pool key
+     * minted it, and an interactive {@link handleFor} can never produce one.
+     */
+    speechHandleFor(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"), and the block's
+     * `output_free` endpoints are the ONLY rows whose zero OUTPUT rate
+     * prices as `cost_usd: '0'` — the allowlist resolves prices IN the
+     * pricing step below, so the document cannot emit a zero the catalog
+     * did not opt into.
+     *
+     * 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.
+     *
+     * The builder's own loud announcements (the absent readiness seam that
+     * conservatively declares every endpoint not ready, unmappable region
+     * codes) go through this router's {@link warn} sink, so a lane that
+     * routes degradations somewhere sees them too — never a default print.
+     */
+    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>;
+    /**
+     * THE SPEECH LANE'S GATE (proxy/speech.ts, `POST /v1/audio/speech`): does
+     * `model`'s deployed app carry catalog `task` **tts** — INVARIANTLY across
+     * every GPU-placement row ({@link audioModalityForRows} answering exactly
+     * `'tts'`)? The SAME shape as {@link supportsImages}/{@link supportsAudio}:
+     * authorized resolution ({@link resolveTarget} — undeployed uRun models
+     * throw {@link UnknownModelError}), then the SAME catalog join
+     * ({@link catalogRowsForSlug}); a SHARED-lane hit joins on the lane's exact
+     * catalog id + variant, exactly like {@link supportsAudio}.
+     *
+     * An `stt` verdict is deliberately NOT speech-capable: a transcription
+     * model must never be asked to synthesize, and a chat model on this route
+     * is the loud 404 the images lane renders for non-image models. A
+     * CONFIGURED catalog oracle that FAILS propagates its rejection — the gate
+     * never fabricates a `false` out of an infrastructure outage.
+     */
+    supportsSpeech(model: string | undefined): Promise<boolean>;
+    /**
+     * THE SPEECH LANE'S VOICE-SET RESOLUTION (proxy/speech.ts): the voice set
+     * `/v1/models` publishes for `model` — resolved by the SAME resolver the
+     * listing's enrichment applies (openrouter-doc.ts `speechVoicesFor`, via
+     * {@link speechVoicesForMatches}) over the SAME catalog join
+     * {@link supportsSpeech} uses (exact `(model_id, variant)` for a
+     * shared-lane hit, {@link catalogRowsForSlug} for a caller-org app), so
+     * the lane enforces exactly ONE list: the one the listing publishes — the
+     * catalog-vouched `engine_args.voices`, else the qwen3 CustomVoice card's
+     * nine for that one model class. A catalog that PRESENTS a voices value
+     * it cannot vouch answers WITH the defect set on the resolution — the
+     * lane fails loud (500) rather than silently validating against the card
+     * fallback. Undeployed uRun-namespace models throw
+     * {@link UnknownModelError} (the lane's 404), and a CONFIGURED catalog
+     * oracle that FAILS propagates — never a fabricated empty set.
+     */
+    speechVoices(model: string | undefined): Promise<SpeechVoicesResolution>;
+    /**
+     * `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>;
+}
+
+/** One ready replica row from the presence read. */
+interface RuntimePresenceRow {
+    runtime_id: string;
+    /** Base URL of the runtime's :8099 endpoint, e.g. `http://10.0.1.5:8099`. */
+    address: string;
+    ready: boolean;
+    /** ISO 8601 instant of the runtime's last presence heartbeat. */
+    last_seen: string;
+    status?: string | null;
+}
+/** One resolved dial target — the router's pure resolution (no session).
+ * The shared arm's fields ride through so the dial can mint the
+ * provider-aware token and the handlers can repin the CATALOG billing pair:
+ * `sharedOrgId` is the shared block's `shared_org_id` (the pod org). */
+interface DialTarget {
+    appSlug: string;
+    fnName?: string;
+    sharedApp?: boolean;
+    modelId?: string;
+    variant?: string;
+    sharedOrgId?: string;
+}
+interface StatelessDecisionDialOptions {
+    /** Resolve a request's model to its dial target WITHOUT opening a session. */
+    targetFor: (model: string | undefined) => Promise<DialTarget>;
+    apiUrl: string;
+    apiKey: string;
+    /** The caller org's id — the minted token's `tenant` claim. */
+    orgId: string;
+    /** The serve function name the resolved app must expose (the backhaul's
+     * URUN_FUNCTION default, 'serve'). */
+    fnName: string;
+    /** The shared secret render injects (URUN_SESSION_TOKEN_SECRET). */
+    secret: string;
+    /** THE SHARED LANE'S credential (URUN_SHARED_ORG_API_KEY): the shared
+     * org's API key, so discovery and decisions can reach the SHARED org's
+     * pods too. The provider org id comes from the resolved target's
+     * `sharedOrgId` (the block's `shared_org_id`), never a second env spelling
+     * of it — key and pod-org identity cannot drift apart. Absent ⇒ shared
+     * models keep the session lane (the v1 boundary narrows to "no shared
+     * credential mounted" instead of "shared never"). */
+    shared?: {
+        apiKey: string;
+    };
+    fetchImpl?: typeof fetch;
+    nowMs?: () => number;
+    /** Per-attempt POST budget override (test seam; production rides
+     * DECISION_TIMEOUT_MS). */
+    timeoutMs?: number;
+}
+/**
+ * The stateless decision dial. `decide` resolves the target, discovers ready
+ * replicas, picks the least-outstanding one, mints the scoped token and POSTs
+ * the flat body to the runtime's `/v1/decision` intake.
+ */
+declare class StatelessDecisionDial {
+    private readonly opts;
+    private readonly replicas;
+    private readonly nowMs;
+    /** Per-(presence key, app, fn) fresh listing, TTL-bounded to
+     * PRESENCE_FRESH_S. A per-DECISION control-plane read would be the same
+     * design error the session dial was — a network round-trip for state the
+     * runtime plane re-proves every ~5s heartbeat. The cache serves the
+     * caller from memory, refreshes in the BACKGROUND past half the TTL, and
+     * evicts a replica (or the whole entry) the moment a dial to its cached
+     * address fails. */
+    private readonly presenceCache;
+    constructor(opts: StatelessDecisionDialOptions);
+    /** Enabled = the pod secret is configured. Absent ⇒ the session lane serves
+     * (byte-for-byte behavior). */
+    get enabled(): boolean;
+    /**
+     * Resolve a request's lane target WITHOUT dialing: `null` for a SHARED-lane
+     * model when the dial holds NO shared credential — the caller keeps the
+     * session lane. WITH the shared key, a shared target is dialable and rides
+     * through with its full identity (modelId/variant for the billing repin,
+     * `sharedOrgId` for the provider-aware token). The HTTP handlers call this
+     * FIRST and route non-null targets into decide; decide re-resolves its own
+     * target so the one it reports is the one it actually dialed.
+     */
+    targetFor(model: string | undefined): Promise<DialTarget | null>;
+    /**
+     * One decision. Returns the intake's `(status, body)` plus the SYNTHESIZED
+     * completed body the lane stamps its billing receipt from — the runtime's
+     * chat body carries `usage` (OpenAI shape) and `urun_timing`; both are the
+     * exact fields the ledger's receipt stamper reads, mapped once here so the
+     * stateless lane prices identically to the session lane. The RESOLVED
+     * target rides along: the handlers repin the billing identity from it
+     * (the dial's own answer, handed out — never asked for again) before
+     * stamping.
+     */
+    decide(body: Record<string, unknown>, model: string | undefined): Promise<{
+        status: number;
+        body: unknown;
+        completed: unknown;
+        target: DialTarget & {
+            fnName: string;
+        };
+    }>;
+    /** Serve the caller from the cache; a MISS (or a TTL-expired entry) reads
+     * synchronously — the cold path is the one decision that pays the hop —
+     * and an entry past half the TTL fires a single-flight BACKGROUND refresh
+     * that never blocks this caller. */
+    private ensureRows;
+    private readPresence;
+    /** LEAST-OUTSTANDING: pick the ready replica with the fewest in-flight
+     * decisions (ties → the first), skipping replicas in failure cooldown. */
+    pick(rows: RuntimePresenceRow[]): string | null;
+    private post;
+}
+
+/**
+ * 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;
+    /**
+     * PROXY-OBSERVED TIME TO FIRST STREAMED CONTENT BYTE, in whole
+     * milliseconds — what the CALLER experienced, and therefore the number
+     * Hugging Face's 5s provider-listing gate is about (ENG-337).
+     *
+     * THE RECORD IS THE ONE SOURCE. This is {@link InferenceRecord.ttft_ms}
+     * carried through, measured at the one place TTFT was already measured
+     * (`ProxyStats.track` stamps `turn.ttftMs` on the first text delta) — the
+     * same number the billing log line and the `urun_inference_ttft_seconds`
+     * histogram already publish. The writer adds no second measurement, so the
+     * row cannot disagree with either sink.
+     *
+     * NULL FOR NON-STREAM, NULL FOR UNOBSERVED, NEVER ZERO FOR EITHER. The
+     * record stamps `ttft_ms` only for a streamed turn: a caller who receives
+     * one JSON body at the end was never shown a "first byte", and publishing
+     * the internal timing in its place would put flattering numbers into
+     * exactly the series the HF gate reads. A stream that produced no text
+     * delta before it ended was never observed at all. Null is the only honest
+     * spelling of both; a 0 here would assert a sub-millisecond first byte
+     * nobody measured. (A MEASURED sub-millisecond first byte does round to 0 —
+     * that is a measurement, not an unknown; which side of the `??` a value
+     * arrived on is the whole difference.)
+     *
+     * NOT THE RUNTIME'S `urun_timing.ttft_ms`, which is `queue_ms +
+     * prefill_ms` and still deliberately does not ride the row (see
+     * `TurnResidency`): that is the engine's view of its own internals, this
+     * is the wall-clock the caller saw — network, proxy, cold-wake and all.
+     * Neither can derive the other, so neither is a second spelling of the
+     * other.
+     */
+    ttft_ms: number | null;
+    /**
+     * PROXY-OBSERVED REQUEST RECEIPT → LAST BYTE, in whole milliseconds: the
+     * end-to-end latency the caller experienced for the whole answer
+     * (ENG-337).
+     *
+     * `Math.round` of the record's `duration_ms` — THE SAME MEASUREMENT
+     * {@link startedAtOf} derives the row's `started_at` from, so the row's
+     * window columns cannot disagree by construction: `started_at + e2e_ms`
+     * and `completed_at` describe one clock. Rounded HERE, at the one place
+     * the row is built, because the ledger's column
+     * (`urun_record_inference_request`'s `p_e2e_ms`) is an `integer` — never
+     * rounded a second time somewhere a new spelling could drift from this
+     * one.
+     *
+     * ALWAYS PRESENT on rows this writer produces, unlike {@link ttft_ms}: the
+     * duration is measured for every completed request, streamed or not,
+     * failed or not. The TYPE still admits null because the wire column is
+     * nullable — the contract is stated rather than implied by what this
+     * writer happens to emit today.
+     */
+    e2e_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 TWO PRICING STATES a landed row can be in — ENG-317's
+ * NULL-is-not-zero distinction, as a metric label value.
+ *
+ * A CONST ARRAY rather than an inline union because the vocabulary is now
+ * ENUMERATED, not merely constrained: {@link LEDGER_OUTCOMES} materialises
+ * every series this counter can ever produce, and a pricing state that existed
+ * only in a type could not be enumerated. Adding a third state here adds its
+ * series everywhere without a second edit.
+ */
+declare const LEDGER_PRICING_STATES: readonly ["priced", "unpriced"];
+type LedgerPricingState = (typeof LEDGER_PRICING_STATES)[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: LedgerPricingState;
+}
+/**
+ * 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: LedgerPricingState;
+}
+/** 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;
+    /**
+     * The SPEECH lane's per-request TTS voice (ENG-331, additive like `tools`):
+     * the speaker id a `tts`-task engine synthesizes under (qwen3 CustomVoice
+     * timbre, e.g. "Ryan"). Forwarded on the serve envelope so the runtime's
+     * speak bridge can apply it through the engine's own per-session override
+     * seam (`SpeakSessionConfig.voice` → `set_voice`, urun-python
+     * tts_engine.py). Absent -> key absent: the engine's catalog-configured
+     * default voice applies, today's behavior.
+     */
+    voice?: string;
+}
+/** 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>;
+    /**
+     * The speech lane's capability gate (proxy/speech.ts), backed by
+     * ModelRouter.supportsSpeech — the caller-org catalog's `task` column,
+     * which must vouch `tts` (NOT `stt`: a transcription model must never be
+     * asked to synthesize) INVARIANTLY across placements. Optional at the seam
+     * exactly like {@link supportsImages}: hand-built clients may omit it, in
+     * which case the mounted speech lane answers the loud 501 — never a
+     * silent allow-all, and never a chat model asked to speak.
+     */
+    supportsSpeech?(model: string | undefined): Promise<boolean>;
+    /**
+     * THE SPEECH LANE'S VOICE-SET RESOLUTION (proxy/speech.ts): the voices
+     * `/v1/models` publishes for `model` (ModelRouter.speechVoices — the SAME
+     * openrouter-doc resolver the listing's enrichment applies, over the SAME
+     * catalog join the tts gate uses), so the lane validates the requested
+     * `voice` against exactly the set the listing publishes — ONE list
+     * everywhere, never a second copy. The resolution also carries the catalog
+     * defect (`engine_args.voices` present but empty/malformed/disagreeing
+     * across placements), which the lane answers with the loud 500 — never a
+     * silent fallback to the qwen3 card's nine. Optional at the seam exactly
+     * like {@link supportsSpeech}: hand-built clients may omit it, in which
+     * case the mounted speech lane answers the loud 501 — skipping the check
+     * silently would downgrade the lane to unvalidated voices.
+     */
+    speechVoices?(model: string | undefined): Promise<SpeechVoicesResolution>;
+    /**
+     * `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.
+     *
+     * `signal` aborts when the CLIENT that asked for the lane went away while
+     * the lane's admission was still pending (the realtime lane's raw socket
+     * close) — the backhaul aborts its `whenLive` wait on it and hands the
+     * queued admission ticket back through core `Session.cancel()`, so a
+     * vanished client never holds the sense pod's one-session slot.
+     */
+    openAudio?(model: string | undefined, signal?: AbortSignal): Promise<ProxyAudioLane>;
+    /**
+     * THE PINNED AUDIO OPEN (speech lane): the NATIVE audio lane of the EXACT
+     * pooled session `handle` names (ModelRouter.sessionForHandle — a gone or
+     * replaced session throws {@link SessionGoneError} LOUDLY, never a fresh
+     * session opened behind the handle's back). The speech lane opens its
+     * audio collector here and dials its response turn on the SAME handle
+     * ({@link createResponseOn}), so BOTH legs are one session identity by
+     * construction: a re-home can never move the turn to a second session
+     * while the collector stays subscribed to the first (which missed the
+     * replacement's audio and answered a voiceless 502, or worse, served a
+     * concurrent collector another session's frames). Optional at the seam
+     * exactly like {@link openAudio}; the speech lane answers its absence
+     * with the loud 501 — never a voiceless downgrade.
+     */
+    openAudioOn?(handle: string): Promise<PinnedAudioLane>;
+    /**
+     * 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>;
+    /**
+     * THE SPEECH LANE'S OWN HANDLE (greptile urun-ts#500): the opaque handle
+     * for the SPEECH-SCOPED pooled session (`speech:<pool key>` — routing.ts
+     * {@link ModelRouter.speechSessionFor}), a slot no interactive lane can
+     * resolve. The speech lane resolves its collector AND its turn through
+     * THIS handle ({@link openAudioOn} + {@link createResponseOn} unchanged),
+     * because the per-session AudioBridge broadcasts every untagged output
+     * frame to every subscriber: a speech collection on the INTERACTIVE
+     * pooled session would stitch a concurrent Realtime/Gemini Live turn's
+     * frames into the returned WAV. Optional at the seam exactly like
+     * {@link openAudioOn}; the speech lane answers its absence with the loud
+     * 501 — NEVER a silent fall-back to the shared interactive session
+     * (that "fallback" is precisely the mixed-audio defect).
+     */
+    speechSessionHandle?(model: string | undefined): Promise<string>;
+    /**
+     * EVICT the SPEECH-scoped pooled session a handle names (CodeRabbit
+     * urun-ts#500, round 8) — through the pool's OWN identity-guarded
+     * eviction path (ModelRouter.evict under the handle's `speech:<key>`
+     * slot, never a bespoke close), so the NEXT speechSessionHandle acquire
+     * opens a FRESH session. The lane calls this after a collector failure
+     * that leaves the session's audio state unknown — above all a turn-cap
+     * timeout, where the serialized lane is released while the pinned
+     * session may still be emitting the timed-out turn's audio: a later
+     * request on the SAME entry would collect those stale frames into its
+     * own answer. Throws {@link SessionGoneError} when the handle names a
+     * session the pool no longer holds (the eviction's goal is then already
+     * true — the lane treats it as success). Optional at the seam exactly
+     * like {@link speechSessionHandle}; the speech lane answers its absence
+     * with the loud 501 — never a silent reuse of the possibly-stale entry.
+     */
+    evictSpeechSession?(handle: string): Promise<void>;
+    /**
+     * 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 STATELESS DIRECT PATH (stateless-dispatch.ts): the decision dial to
+     * the serving pods' `POST /v1/decision` intake, present only when the
+     * deployment carries the runtime scoped-token secret. Absent ⇒ every
+     * decision rides the session lane exactly as before (the staged rollout).
+     * Per-org: the HOSTED registry builds one per tenant so the minted token's
+     * tenant claim is always the CALLER's org.
+     */
+    readonly stateless?: StatelessDecisionDial;
+}
+/**
+ * The audio lane handle `openAudio` returns — structurally the transport
+ * AudioBridge (media.ts): base64 PCM16 @24 kHz mono in both directions.
+ * `sessionId` is the pooled uRun session the lane rides (core `Session.id`),
+ * when the backhaul reports it — the identity the realtime lane's structured
+ * lifecycle log carries so an orphaned session is traceable from the proxy
+ * log alone. Null is the HONEST ABSENCE (the same line {@link
+ * PinnedAudioLane.sessionId} and the re-homing dial's `sessionIdOf` take —
+ * an id-less session reports no id, never a fabricated one).
+ */
+type ProxyAudioLane = Pick<AudioBridge, 'appendInputAudio' | 'onOutputAudio'> & {
+    sessionId?: string | null;
+};
+/**
+ * The PINNED audio lane handle `openAudioOn` returns ({@link ProxyClients.openAudioOn}):
+ * the session's native audio lane PLUS the identity of the exact pooled session
+ * it is bound to — the two facts the speech lane needs to keep its collector and
+ * its response turn on ONE session identity.
+ */
+interface PinnedAudioLane extends ProxyAudioLane {
+    /**
+     * The uRun session id of the pooled session this lane is bound to — the
+     * honest instance link for a request whose collector and turn ride one
+     * handle, the same derivation the dial report's `sessionId` uses. Null
+     * when the entry carries no native session id; never a fabricated one.
+     */
+    readonly sessionId: string | null;
+}
+/**
+ * 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 };