@urun-sh/openai 0.5.6 → 0.6.0

package/dist/{responses-turn-tNUHq5b0.d.cts → responses-turn-BfdBbey8.d.cts}

@@ -1,6 +1,6 @@
 import { C as CatalogRow } from './models-DUdx_Y6X.cjs';
 import { IncomingMessage } from 'node:http';
-import { a as AudioBridge, h as VideoFrameLane, j as VideoOutLane } from './video-out-CCksIcj8.cjs';
+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
@@ -183,7 +183,9 @@ interface InferenceRecord {
  * per-request resolver over the catalog edge function's `shared` block:
  *
  *     { shared_org_id, endpoints: [{ model_id, variant, gpu_spec, app_slug,
- *                                    function, warm }] }
+ *                                    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
@@ -217,11 +219,50 @@ interface SharedEndpointRow {
      * 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;
 }
 
 /**
@@ -371,32 +412,125 @@ interface ModelPriceRow {
  * source is model-prices.ts — the SAME per-token join the OpenAI listing
  * uses ({@link pricingFor}); the per-million rate is shifted to per-token
  * on its decimal string, never by float division. An entry with no
- * per-token row — today ALL of them, because `model_prices` prices GPU
+ * 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).
+ * 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 app slug. */
+    /**
+     * 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;
 }
 
 /**
@@ -419,11 +553,12 @@ interface OpenRouterProviderModel {
  *
  * RESOLUTION ORDER (one canonical path, documented end to end):
  *   1. model absent / "urun" / an alias of the startup app  → DEFAULT app.
- *   2. exact slug match on a deployed serve app             → that app.
+ *   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 is NOT an active app exposing the
- *      proxy's serve function                               → loud 404
+ *   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).
@@ -449,9 +584,13 @@ interface OpenRouterProviderModel {
 /** 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;
-    [k: string]: unknown;
 }
 /**
  * A model that does not resolve to a deployed app the proxy may serve.
@@ -502,6 +641,15 @@ interface RouterModelEntry {
     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';
@@ -523,7 +671,8 @@ interface RouterImageModelList {
  * lane (the catalog `shared` block, the cross-org session dial) — the exact
  * serve function on the shared org's app and the flag that switches the
  * control plane's shared-admission carve-out on. A plain caller-org app
- * carries only `appSlug`; the router's own `fnName` applies there.
+ * carries only `appSlug`; the router's `fnName` (the function the backhaul
+ * dials) applies there.
  */
 interface RouteTarget {
     appSlug: string;
@@ -540,6 +689,16 @@ interface RouteTarget {
     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> {
     /**
@@ -550,10 +709,25 @@ interface ModelRouterOptions<S> {
      * "NO-DEFAULT MODE").
      */
     defaultApp: string | null;
-    /** The serve function name every routed app must expose (URUN_FUNCTION). */
+    /**
+     * 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). */
-    openSession: (target: RouteTarget) => S | Promise<S>;
+    /**
+     * 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>;
     /**
@@ -609,6 +783,19 @@ interface ModelRouterOptions<S> {
      * 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
@@ -681,11 +868,24 @@ declare class ModelRouter<S> {
      *     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
@@ -694,7 +894,14 @@ declare class ModelRouter<S> {
      * time bomb.
      */
     private warn;
-    /** Apps this proxy may serve: active AND exposing the serve function. */
+    /**
+     * 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;
     /**
@@ -754,6 +961,15 @@ declare class ModelRouter<S> {
      * 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
@@ -782,6 +998,28 @@ declare class ModelRouter<S> {
         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
@@ -794,6 +1032,17 @@ declare class ModelRouter<S> {
         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,
@@ -849,11 +1098,20 @@ declare class ModelRouter<S> {
      * {@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").
+     * 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>;
     /**
@@ -907,6 +1165,40 @@ declare class ModelRouter<S> {
      * 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
@@ -925,6 +1217,117 @@ declare class ModelRouter<S> {
     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`.
  *
@@ -1220,6 +1623,58 @@ interface LedgerWrite {
     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 {
@@ -1341,6 +1796,18 @@ interface LedgerFailure {
  */
 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
@@ -1359,7 +1826,7 @@ type LedgerOutcome =
 /** The row is in the ledger. `priced` / `unpriced` is ENG-317's NULL-is-not-zero distinction. */
 {
     outcome: 'written';
-    reason: 'priced' | 'unpriced';
+    reason: LedgerPricingState;
 }
 /**
  * The row was ALREADY in the ledger and it is OURS — an earlier attempt
@@ -1369,7 +1836,7 @@ type LedgerOutcome =
  */
  | {
     outcome: 'already_written';
-    reason: 'priced' | 'unpriced';
+    reason: LedgerPricingState;
 }
 /** No row was attempted. */
  | {
@@ -1463,6 +1930,16 @@ interface ResponsesCreateParams {
      * 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 {
@@ -1571,6 +2048,31 @@ interface ProxyClients {
      * 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
@@ -1643,8 +2145,29 @@ interface ProxyClients {
      * session; repeat calls return the same lane. Optional at the seam because
      * text-only embeddings exist — but a surface that RECEIVES audio while the
      * embedder wired no `openAudio` must fail LOUD, never drop chunks.
-     */
-    openAudio?(model: string | undefined): Promise<ProxyAudioLane>;
+     *
+     * `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 →
@@ -1675,6 +2198,38 @@ interface ProxyClients {
      * 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
@@ -1687,16 +2242,48 @@ interface ProxyClients {
      * 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.
-     */
+    * 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.
  */
-type ProxyAudioLane = Pick<AudioBridge, 'appendInputAudio' | 'onOutputAudio'>;
+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,