@urun-sh/openai 0.5.4 → 0.5.6

package/dist/hosted/index.d.cts

@@ -1,283 +1,147 @@
 import { Server } from 'node:http';
+import * as _prometheus_io_client from '@prometheus-io/client';
+import { Registry } from '@prometheus-io/client';
+import { c as LedgerOutcome, I as InferenceRecord, S as SessionGoneError, P as ProxyClients, M as ModelRouter, i as UsageRowReporter, b as InferenceUsageRecord, e as LedgerWrite, d as LedgerRecorded, L as LedgerFailure } from '../responses-turn-tNUHq5b0.cjs';
 import { createClientToken } from '@urun-sh/core';
-import { U as UrunResponses } from '../ResponsesClient-Dft3bg3b.cjs';
+import { U as UrunResponses } from '../ResponsesClient-DjZWjlFH.cjs';
 import { b as UrunSessionLike } from '../types-lsVTbNcH.cjs';
-import { C as CatalogRow } from '../models-NYMZrklp.cjs';
-import { P as ProxyClients } from '../server-wmUnMewW.cjs';
-import '../video-out-D20UuJ8G.cjs';
+import '../models-DUdx_Y6X.cjs';
+import '../video-out-CCksIcj8.cjs';
 
 /**
- * THE OPENROUTER PROVIDER DOCUMENT — `GET /v1/models?format=openrouter`.
+ * The container's metrics port — a MODULE CONSTANT, not an env var, per the
+ * hosted config mandate (`hosted/config.ts`: "env vars are NOT a config
+ * mechanism"). 9464 is the Prometheus exporter port the OpenTelemetry
+ * ecosystem registered, and it is the interface contract the deployment chart
+ * and its ServiceMonitor are built against.
  *
- * OpenRouter's provider monitor polls this document (schema 2.4, per
- * openrouter.ai/docs/guides/community/for-providers) to list a provider's
- * models on the marketplace. The `id` field is the EXACT model identifier
- * OpenRouter sends back as `model` on chat completions — which here is the
- * app slug, the same id the OpenAI surface lists. One id space, two views.
- *
- * 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 catalog oracle configured the document is `{"data": []}` — honest
- * emptiness, not invented capability (the chart turns the oracle on).
- *
- * PRICING is deliberately omitted entirely: the schema's rule is "a modality
- * with no pricing array is simply unpriced", OpenRouter configures pricing
- * during provider onboarding, and the per-model price surface is
- * urun-infra U3 (model_prices) — when that lands, this module grows a
- * `prices` input and emits the input/output pricing arrays.
- *
- * The full closed-value-domain schema ships as OpenAPI 3.1 at
- * openrouter.ai/docs/assets/provider-monitor-schema-v2.openapi.json.
+ * PRIVATE, and private STRUCTURALLY rather than by convention: the public
+ * HTTPRoute allowlist (`k8s-manifests` `_public-matches.tpl`) routes only
+ * `/v1` to the Service's 8080 port, so nothing on this port is reachable from
+ * the internet. It is served by its OWN `http.Server`
+ * ({@link createMetricsServer}) rather than as a route on the main server, so
+ * a future public path can never accidentally expose it.
  */
-
-type OpenRouterProviderDoc = {
-    data: OpenRouterProviderModel[];
-};
-interface OpenRouterProviderModel {
-    schema_version: '2.4';
-    /** The EXACT id OpenRouter sends back as `model` — the app slug. */
-    id: string;
-    name: string;
-    created: number;
-    /** Valid enum: int4|int8|fp4|mxfp4|nvfp4|fp6|fp8|mxfp8|fp16|bf16|fp32|null. */
-    quantization: string | null;
-    description: string;
-    hugging_face_id: string;
-    input_modalities: Array<Record<string, unknown>>;
-    output_modalities: Array<Record<string, unknown>>;
-}
-
+declare const METRICS_PORT = 9464;
+/** The path the ServiceMonitor scrapes. */
+declare const METRICS_PATH = "/metrics";
+/** The label value every bounded label collapses to once its budget is spent. */
+declare const OTHER_LABEL = "(other)";
+/** The label value for a request that named no model. */
+declare const NO_MODEL_LABEL = "(none)";
 /**
- * Per-model → per-app routing for the compat proxy (owner directive
- * 2026-08-07): swapping the model in a coding harness routes the request to
- * the org's DEPLOYED app for that model. v1 is deployed-only — a uRun model
- * that is not deployed gets a loud 404 naming `urun serve <id>`; a later
- * phase (explicitly out of scope here; urun-infra#1490 shared-endpoints)
- * auto-creates from the model catalog on first request.
- *
- * MODEL-ID SURFACE (the documented mapping): a model may be named by
- *   - the app slug itself        ("qwen3-6-27b-bf16"), or
- *   - the catalog id             ("qwen3.6-27b"), or
- *   - the catalog id:variant     ("qwen3.6-27b:bf16"),
- * where slugification mirrors urun-cli `serve.py _default_app_name` exactly:
- * lowercase, every non-alphanumeric-non-dash character becomes "-", leading/
- * trailing dashes stripped (catalog id "qwen3.6-27b" + variant "bf16" → app
- * "qwen3-6-27b-bf16"). COLLISION RULE: an exact slug match always wins over
- * the catalog-id (prefix) interpretation.
- *
- * RESOLUTION ORDER (one canonical path, documented end to end):
- *   1. model absent / "urun" / an alias of the startup app  → DEFAULT app.
- *   2. exact slug match on a deployed serve app             → that app.
- *   3. catalog-id form matching exactly one deployed app    → that app
- *      (two or more candidates → loud ambiguity error naming them).
- *   4. the name maps to an org app that is NOT an active app exposing the
- *      proxy's serve function                               → loud 404
- *      naming `urun serve <model>` and the available models.
- *   5. the name matches a catalog row but no deployed app   → loud 404
- *      naming `urun serve <id>` (deployed-only v1).
- *   6. anything else — a model name outside the uRun namespace entirely
- *      (e.g. the harness's own upstream default, "claude-*"/"gpt-*") →
- *      DEFAULT app. This IS today's single-app contract, kept deliberately
- *      so `urun compat <agent>` with the agent's stock model keeps working
- *      with zero new env; the per-model /stats table records every such
- *      mapping so it is visible, never silent. Models the proxy ADVERTISES
- *      on /v1/models can never land here — they resolve (2/3) or fail loud
- *      (4/5) above.
- *
- * NO-DEFAULT MODE (`defaultApp: null`) — the HOSTED multi-tenant lane
- * (`src/hosted/`): a shared endpoint serving every org has no "the app this
- * proxy was started for", so rules 1 and 6 have nothing to fall back TO.
- * Rather than inventing one (picking "some" app for a caller would be the
- * worst kind of silent divergence), both rules become the SAME loud
- * {@link UnknownModelError} that rules 4/5 already raise: name a deployed
- * model, here is the list. Rules 2–5 are byte-for-byte the local behavior —
- * one router, one resolution order, two configurations.
+ * Distinct `model` values that get their own series. Above this the label
+ * collapses to {@link OTHER_LABEL} — a caller sending a fresh random model
+ * string per request must not be able to grow this process's series set (and
+ * therefore Prometheus's) without bound.
  */
-
-/** One org app row from `GET {orgApi}/apps` (urun-cli `ApiClient.list_apps`). */
-interface DeployedApp {
-    app_slug: string;
-    function_name?: string | null;
-    deployment_status?: string | null;
-    [k: string]: unknown;
-}
+declare const MAX_MODEL_LABELS = 64;
 /**
- * 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.
+ * Distinct `org` values that get their own series. Bounded for the same reason
+ * even though org ids come from the control plane rather than the caller: the
+ * number of orgs is unbounded over time, and a metric's cardinality must be a
+ * property of the code, not of how successful sales were.
  */
-declare class SessionGoneError extends Error {
-}
+declare const MAX_ORG_LABELS = 128;
+/** Collapse a client-supplied path onto the bounded lane label. */
+declare function laneOf(path: string): string;
 /**
- * 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;
-}
-interface RouterModelList {
-    object: 'list';
-    data: RouterModelEntry[];
-}
-interface ModelRouterOptions<S> {
-    /**
-     * The startup app slug (URUN_APP) — the DEFAULT model — or `null` for the
-     * hosted multi-tenant lane, which has no per-proxy default app: there,
-     * every request must NAME a deployed model and an unnamed/unknown one
-     * fails loud instead of silently landing somewhere (see the module header,
-     * "NO-DEFAULT MODE").
-     */
-    defaultApp: string | null;
-    /** The serve function name every routed app must expose (URUN_FUNCTION). */
-    fnName: string;
-    /** Open a backhaul session for an app slug (called at most once per app). */
-    openSession: (appSlug: 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;
-    /** Deployed-apps cache TTL (the list changes on deploys, not per request). */
-    appsTtlMs?: number;
+ * The status class label. `none` is its own class rather than being folded
+ * into 5xx: it means NO head ever flushed (an aborted upload, a client that
+ * vanished during the body read), which `inferenceRequestRecord` records as a
+ * null status precisely so nothing downstream invents a 200 the client was
+ * never sent.
+ */
+declare function statusClassOf(status: number | null): string;
+/**
+ * A label whose distinct-value budget is FIXED at construction. The first
+ * `max` distinct values are ADMITTED; everything after is {@link OTHER_LABEL},
+ * permanently. Deliberately NOT an LRU: an LRU would let a flooding caller
+ * evict the real models and quietly rewrite history in the TSDB, where each
+ * admitted-then-evicted-then-readmitted value leaves a broken series behind.
+ *
+ * ADMISSION IS EARNED, AND THAT IS THE WHOLE DEFENCE. A budget alone does not
+ * protect anything: one authenticated caller sending `MAX_MODEL_LABELS`
+ * requests naming random models — every one of them answered 404, because an
+ * unknown model is refused — would spend the entire budget and collapse every
+ * REAL model onto `(other)` until the pod restarts. That kills the per-model
+ * TTFT and rate panels, which are exactly the two the Hugging Face latency
+ * gate is read from. So a value is admitted only when `admit` is true, and the
+ * caller passes `admit` for answers that were actually served; a refusal can
+ * still be COUNTED (under `(other)`) but can never consume budget.
+ */
+declare class BoundedLabel {
+    private readonly max;
+    private readonly admitted;
+    private overflows;
+    constructor(max: 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.
+     * @param admit whether this observation may spend budget on a new value.
+     *   False for refused requests, so a caller cannot blind the label by naming
+     *   models that do not exist.
      */
-    sessionKey?: (entry: S) => string;
+    of(value: string | null, admit?: boolean): string;
+    /** Distinct values admitted so far — published as a gauge (see below). */
+    get size(): number;
+    /** Admissible observations refused because the budget was spent. */
+    get overflowCount(): number;
 }
 /**
- * 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).
+ * The hosted proxy's metric set, over its OWN {@link Registry} rather than the
+ * library's global `register`. Per-instance because the alternative is
+ * process-global mutable state that two tests (or two embedders) silently
+ * share — `Counter` construction on an already-registered name throws, so a
+ * global registry would make the second `createHostedProxy` in a process fail.
  */
-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;
+declare class InferenceMetrics {
+    readonly registry: Registry<_prometheus_io_client.RegistryContentType>;
+    private readonly modelLabel;
+    private readonly orgLabel;
+    private readonly requests;
+    private readonly duration;
+    private readonly ttft;
+    private readonly streamErrors;
+    private readonly undelivered;
+    private readonly ledgerWrites;
+    private readonly ledgerQueue;
+    private readonly labelCardinality;
+    private readonly labelOverflows;
+    constructor(options?: {
+        defaultMetrics?: boolean;
+    });
     /**
-     * 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;
-    /** Apps this proxy may serve: active AND exposing the serve function. */
-    private servable;
-    private availableIds;
-    /**
-     * NO-DEFAULT MODE's terminal for rules 1 and 6: there is no app to fall
-     * back to, so say so loudly and list what the CALLER'S org actually has.
-     * Never returns.
-     */
-    private noDefaultApp;
-    /**
-     * Resolve a request's `model` to an app slug — the documented resolution
-     * order from the module header. Throws {@link UnknownModelError} for a uRun
-     * model that is not deployed (rules 4/5).
-     */
-    resolveApp(model: string | undefined): Promise<string>;
-    /** The pooled session for a model — opened lazily, reused afterwards. */
-    sessionFor(model: string | undefined): Promise<{
-        app: string;
-        entry: S;
-    }>;
-    private keyOf;
-    /**
-     * SESSION-IDENTITY SEAM (a): the opaque stable handle for the pooled
-     * session currently serving `model`'s turns. Rides the SAME acquisition
-     * path as every request ({@link sessionFor}) — the session opens lazily if
-     * this model has none yet — and derives the handle from native identity
-     * (app slug + uRun session id), zero bespoke bookkeeping.
-     */
-    handleFor(model: string | undefined): Promise<{
-        app: string;
-        handle: string;
-    }>;
-    /**
-     * SESSION-IDENTITY SEAM (b): the exact pooled session a handle names.
-     * NEVER opens a fresh session — a handle whose session is gone (closed,
-     * evicted, re-homed to a replacement, proxy restarted) or malformed throws
-     * {@link SessionGoneError} loudly. Resume is reattach-or-fail, not
-     * reattach-or-quietly-restart.
-     */
-    sessionForHandle(handle: string): Promise<{
-        app: string;
-        entry: S;
-    }>;
-    /**
-     * Drop ONE pooled session whose backhaul died (its pod was restarted /
-     * drained / deleted) and release it — the next {@link sessionFor} opens a
-     * fresh one, i.e. asks the control plane for a new assignment. Used by the
-     * one-shot re-home (rehome.ts, urun-sh/urun-python#1592).
+     * Count ONE terminal ledger outcome — the third sink for a request that
+     * `proxy/ledger.ts` already logs, counted so it can be alerted on.
      *
-     * 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.
+     * Takes the very {@link LedgerOutcome} the log line carries, for the same
+     * reason {@link observe} takes the record verbatim: a counter derived from a
+     * second walk would eventually disagree with the billing log, and the
+     * disagreement would be invisible.
      */
-    modelList(): Promise<RouterModelList>;
+    observeLedger(outcome: LedgerOutcome): void;
     /**
-     * The OpenRouter PROVIDER document (`GET /v1/models?format=openrouter`):
-     * schema 2.4 per openrouter.ai/docs/guides/community/for-providers. Only
-     * chat-completions-shaped models are declared (task chat | code | agent |
-     * vl — a voice or video app behind a chat surface would stream garbage);
-     * models the catalog cannot vouch for are OMITTED, never guessed. Pricing
-     * is deliberately omitted entirely (schema rule: "A modality with no
-     * pricing array is simply unpriced" — OpenRouter configures pricing during
-     * provider onboarding; the per-model price surface is urun-infra U3).
+     * Count ONE completed `/v1` request. Takes the very record
+     * `inferenceRequestLine` serializes, so the counters and the billing log can
+     * never drift apart.
      */
-    openRouterModels(): Promise<OpenRouterProviderDoc>;
-    /** Close every pooled session (Session.end() underneath) — proxy shutdown. */
-    closeAll(): Promise<void>;
+    observe(record: InferenceRecord): void;
+    /** The exposition text a scrape answers with. */
+    scrape(): Promise<string>;
+    /** The `Content-Type` that exposition must be served under. */
+    get contentType(): string;
 }
+/**
+ * The PRIVATE metrics listener — its own `http.Server` on
+ * {@link METRICS_PORT}, serving exactly `GET /metrics` and 404 for everything
+ * else.
+ *
+ * A SEPARATE SERVER, not a route on the main one, is the whole point: the
+ * public gateway forwards only to the main port, so "not public" is a property
+ * of the socket rather than a rule the `/v1` router has to keep remembering.
+ * It also means a scrape can still be answered while the main server is
+ * draining, which is exactly when the numbers matter most.
+ */
+declare function createMetricsServer(metrics: InferenceMetrics): Server;
 
 /**
  * HOSTED AUTH — the Bearer key IS the identity AND the tenancy.
@@ -401,17 +265,24 @@ declare class OrgResolver {
  *      `consecutiveFailures` resets on every healthy sync, so a recovered
  *      blip never trips this.
  *
- *   2. Core Session's own phase surface (`Session.onPhase` → 'paused' /
- *      'error') — the compute binding the pool already tracks (the same signal
- *      cli.ts `onSessionEnd` rides).
+ *      Core Session's own phase surface (`Session.onPhase` → 'live' /
+ *      'paused' / 'error'). The verdict arms ONLY on a `live` sighting: a
+ *      binding must EXIST before it can be lost. A session born into its
+ *      pre-live wait (the cold wake) or re-attached in `error` (resume runs
+ *      the function from the top, session-semantics.md) is ACQUIRING
+ *      compute, never losing it — core's own whenLive gate treats both as
+ *      WAITABLE, and the unguarded latch 502-looped every shared chat/agent
+ *      model on exactly those sightings (prod 2026-09-14: the entry was
+ *      evicted before it ever served, and "retry to get a fresh session"
+ *      re-dialed into the same verdict forever).
  *
- *      NOTE what "gone" means HERE, because it is narrower than it reads: this
- *      pool holds a session with COMPUTE BOUND to it, and a `paused` phase says
- *      that binding is gone. The session ITSELF is not gone — it is parked,
- *      listed, and attachable by name (see
- *      urun-python/docs/design/session-semantics.md). The eviction is correct
- *      because the POOL ENTRY is what became unusable; nothing here is entitled
- *      to conclude the session is over.
+ *      NOTE what "gone" means HERE, because it is narrower than it reads:
+ *      this pool holds a session with COMPUTE BOUND to it, and a post-live
+ *      `paused` phase says that binding is gone. The session ITSELF is not
+ *      gone — it is parked, listed, and attachable by name (see
+ *      urun-python/docs/design/session-semantics.md). The eviction is
+ *      correct because the POOL ENTRY is what became unusable; nothing here
+ *      is entitled to conclude the session is over.
  *
  * Consumers (cli.ts):
  *   - {@link watchSessionGone} per pooled entry; `onGone` → `router.evict`
@@ -479,12 +350,24 @@ interface CatalogConfig {
  */
 type OwnedSession = UrunSessionLike & {
     end: () => Promise<unknown>;
+    /**
+     * The SDK's NATIVE local release (core `Session.detach`): drop the media
+     * transport and decrement the reference count while the named session
+     * stays live and attachable. Optional here because only the
+     * `release: 'detach'` lane requires it — that lane fails LOUD when a
+     * session object lacks it (no approximation, no fake detach).
+     */
+    detach?: () => void;
     id?: string;
     endsAt?: Date | null;
     onPhase?: (handler: (phase: {
         name: string;
         reason?: string;
     }) => void) => () => void;
+    whenLive?: (options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }) => Promise<void>;
 };
 /**
  * One pooled backhaul: the session, its (stateful) Responses client, and the
@@ -584,6 +467,24 @@ declare class TenantRegistry {
     /** Insertion-ordered = LRU order, because a hit re-inserts at the end. */
     private readonly tenants;
     constructor(opts: TenantRegistryOptions);
+    /**
+     * THE NON-SECRET TENANCY LABEL, attached by the REGISTRY rather than by
+     * whichever builder produced the backhaul.
+     *
+     * The caller's org id is what the per-request record and the Prometheus
+     * series are broken down by (`proxy/responses-turn.ts` `ProxyClients.tenant`)
+     * — never `caller.apiKey`, which is the credential on this surface and would
+     * become a credential on every dashboard. Attaching it here means a backhaul
+     * can never come back unlabelled because a builder forgot.
+     *
+     * `Object.create`, not a mutation and not a spread: the source object keeps
+     * its identity and its prototype (so a class-based `ProxyClients` keeps its
+     * methods), and no other caller's backhaul is touched. Done ONCE per tenant,
+     * at build time — the returned object is then cached and reused for every
+     * later request from that key, which matters because the `/v1/responses`
+     * thread store is keyed on this very object identity.
+     */
+    private label;
     private build;
     /** The backhaul for THIS caller, opened on first use and reused after. */
     clientsFor(caller: CallerIdentity): ProxyClients;
@@ -592,6 +493,358 @@ declare class TenantRegistry {
     /** Shutdown: end every pooled session through `Session.end()`. */
     closeAll(): Promise<void>;
 }
+/** The most distinct LIVE conversations one replica keeps private backhauls for. */
+declare const MAX_CONVERSATIONS = 512;
+/** The most resume handles the conversation index remembers (bounded memory). */
+declare const MAX_CONVERSATION_HANDLES = 1024;
+/**
+ * Every conversation slot holds a conversation (active or resumable) — a NEW
+ * bootstrap/setup is refused. Explicit and honest: never an LRU-detach of
+ * someone else's conversation to admit a new one.
+ */
+declare class ConversationCapacityError extends Error {
+    constructor();
+}
+/**
+ * One conversation's private backhaul. Its pooled sessions are reachable by
+ * NO other conversation of any caller: the token subject is conversation-
+ * unique, so the platform's own session dedupe never coalesces them.
+ */
+interface PrivateConversationBackhaul {
+    clients: ProxyClients;
+    /**
+     * LOCAL release of every pooled session — `release: 'detach'` underneath,
+     * i.e. core's NATIVE `Session.detach()`: the media transport drops, the
+     * refcount decrements, the NAMED session stays live and attachable. Never
+     * `Session.end()`: no caller has explicitly ended anything.
+     */
+    release(): Promise<void>;
+}
+interface ConversationBackhaulOptions {
+    /** The session-gateway base sessions are opened against. */
+    baseUrl: string;
+    /** The org control-plane API base (`GET {apiUrl}/apps`). */
+    apiUrl: string;
+    /** The model-catalog oracle for routing rule 5, or null. */
+    catalog: CatalogConfig | null;
+    /** Injected in tests; production builds real uRun backhauls. */
+    build?: (caller: CallerIdentity, conversation: {
+        id: string;
+        subject: string;
+    }) => PrivateConversationBackhaul;
+}
+/**
+ * The per-CONNECTION Live/realtime seam — transport-neutral (Gemini Live,
+ * OpenAI Realtime, ...). `clients` lazily opens the caller's PRIVATE
+ * conversation backhaul on first use; `bindResumeHandle` indexes each handle
+ * the protocol lane mints; `clientsForResume` re-attaches the conversation a
+ * handle belongs to — SAME native identity, owner binding enforced, loud
+ * SessionGoneError when the conversation is gone; `release` drops THIS
+ * attachment when the socket closes.
+ */
+interface PrivateConversationConnection {
+    clients: ProxyClients;
+    bindResumeHandle(handle: string): void;
+    clientsForResume(handle: string): Promise<ProxyClients>;
+    /**
+     * Release THIS attachment: called by the surface when its socket closes.
+     * When the LAST attachment of a conversation goes, its native transport is
+     * detached immediately — while the conversation's native session
+     * REFERENCES (and its resume handles) are RETAINED, so a later resume
+     * re-attaches the SAME named session through canonical attach-by-name.
+     * Idempotent.
+     */
+    release(): Promise<void>;
+}
+/**
+ * Process-local registry of per-conversation private backhauls, bounded by
+ * {@link MAX_CONVERSATIONS}. A conversation whose last attachment closes
+ * KEEPS its entry: its native session references + resume handles survive so
+ * a later resume re-attaches the SAME named session (canonical
+ * attach-by-name). At capacity, only such DETACHED entries are evicted
+ * (oldest first — their resume capability is the only thing lost, the named
+ * sessions stay attachable server-side); ACTIVE conversations are never
+ * touched, and when every slot is active a new bootstrap/setup is refused
+ * with an explicit capacity error. NO HA CLAIM: this registry is
+ * per-process; a replica restart loses every conversation (loud gone), and
+ * no other replica can serve one.
+ */
+declare class ConversationBackhauls {
+    private readonly opts;
+    /** apiKey → conversationId → entry (insertion-ordered = LRU). */
+    private readonly byCaller;
+    /** resume handle → owning conversation (the owner binding's index). */
+    private readonly byHandle;
+    constructor(opts: ConversationBackhaulOptions);
+    private build;
+    /** Find (LRU-refresh) or create the conversation entry, then ATTACH to it. */
+    private attachEntry;
+    private get conversationCount();
+    /**
+     * Free a slot for a NEW conversation: evict the OLDEST DETACHED
+     * conversation (one whose last attachment already closed — only its resume
+     * metadata is lost, no live transport is touched, no session is ended).
+     * ACTIVE conversations are never evicted. When every slot holds an active
+     * conversation, refuse LOUD with an explicit capacity error — the new
+     * bootstrap/setup fails, existing callers are untouched.
+     */
+    private evictOverflow;
+    private dropHandleIndexFor;
+    /**
+     * The per-upgrade seam for one authenticated caller — ONE attachment. The
+     * conversation backhaul opens on the FIRST seam call of a fresh connection;
+     * a resumed connection replaces `clients` wholesale via `clientsForResume`
+     * before any seam call, so the lazy path is never taken on resume. The
+     * attachment is released by `release()` (the socket's close path): when the
+     * LAST attachment of a conversation goes, its native transport is detached
+     * immediately and its resume metadata is retained — no resource keepalive,
+     * no resume loss.
+     */
+    connectionFor(caller: CallerIdentity): PrivateConversationConnection;
+    /**
+     * Drain-time LOCAL release: detach every conversation's sessions (native
+     * detach — the named sessions pause server-side, nothing is ended). Handles
+     * and conversations are forgotten; process exit is the conversation's end.
+     */
+    detachAll(): Promise<void>;
+}
+
+/**
+ * THE HOSTED USAGE READ — the control-plane half of the canonical usage lane.
+ *
+ * The proxy holds no database credential and no standing platform secret
+ * (hosted/auth.ts). So the ledger read rides the CALLER'S OWN org API key to
+ * the control plane's `inference-usage` edge function — the same mechanism and
+ * the same credential `TenantRegistry` uses for `GET {apiUrl}/apps` — and the
+ * control plane derives the org from that key server-side and runs the
+ * org-scoped `urun_inference_usage_lookup` RPC.
+ *
+ * THAT IS WHY THIS LANE DOES NOT PRE-VERIFY THE KEY WITH `OrgResolver`. The
+ * surface that owns the data authenticates the key itself, so a second
+ * verification here would be a second source of truth about the same
+ * credential — and the org binding it produced would not be the one the read
+ * was actually scoped by. `bearerFrom` still runs at the call site, so a
+ * missing or malformed Authorization header is a loud 401 without a round trip.
+ *
+ * EVERY FAILURE IS LOUD. There is no shape of failure that answers with an
+ * empty `requests` list, because "we hold nothing for these ids" is precisely
+ * the answer that makes a billing caller stop asking — Hugging Face writes a
+ * request off ~30 minutes after it was served — so an outage that could wear
+ * that costume would be an invisible revenue hole.
+ */
+
+interface UsageClientOptions {
+    /** The org control-plane API base (`{apiUrl}`) the function is mounted under. */
+    apiUrl: string;
+    /** Injected in tests; production uses the platform fetch. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Where a row this lane REFUSED TO ANSWER ABOUT is reported (ENG-416).
+     *
+     * A malformed ledger row is isolated rather than allowed to 502 the whole
+     * 10,000-id batch, and the row it dropped is then MISSING from the answer —
+     * which a billing caller cannot tell apart from an id we do not hold, and
+     * reads as "not priced yet" until the request is written off unbilled. So
+     * the drop must be an event somebody can alert on. Absent, it goes to this
+     * process's stdout (`parseUsageRecords`'s own default), never nowhere.
+     *
+     * It may be async — a sink that ships the line somewhere usually is — and a
+     * rejected promise from it is contained exactly as a synchronous throw is.
+     */
+    onRejectedRow?: UsageRowReporter;
+}
+/** The batch ledger read, as one call per request. */
+declare class UsageClient {
+    private readonly opts;
+    private readonly fetchImpl;
+    constructor(opts: UsageClientOptions);
+    /**
+     * Look up what we hold for these ids, as the holder of `apiKey`.
+     *
+     * Three outcomes, all explicit:
+     *   - the control plane answers      → validated {@link InferenceUsageRecord}s;
+     *   - it rejects the key (401/403)   → {@link ProxyAuthError} (401);
+     *   - anything else                  → {@link UsageSurfaceError} (502).
+     */
+    lookup(apiKey: string, inferenceIds: readonly string[]): Promise<InferenceUsageRecord[]>;
+}
+
+/**
+ * THE HOSTED LEDGER WRITE — the control-plane half of the per-request ledger.
+ *
+ * The proxy holds no database credential and no standing platform secret
+ * (hosted/auth.ts: "NO STANDING CREDENTIAL... every upstream call it makes
+ * rides the CALLER'S OWN key"). So the ledger write rides the caller's own org
+ * API key to the control plane's `inference-ledger` function — the same
+ * mechanism and the same credential the ENG-318 read already uses — and the
+ * control plane derives the org AND the api_key_id from that key server-side
+ * before calling `urun_record_inference_request`.
+ *
+ * THAT PROPERTY IS SOUND ON THE READ AND INVERTED ON THE WRITE, and it is
+ * stated here because it is invisible in the code. On a read, riding the
+ * caller's key is precisely what enforces org scoping. On a WRITE TO A BILLING
+ * LEDGER it means the party being billed is the party authenticated to write
+ * the bill: a caller can read its `Inference-Id` off a streaming response head
+ * and race a fabricated row in ahead of this one. The control plane refuses
+ * the second write rather than upserting, so the attempt is LOUD instead of
+ * silent — see {@link LedgerDuplicateError}.
+ *
+ * ============================ THE ENG-410 RULING ============================
+ *
+ * That is a DETECTION, and it is the DELIBERATE, OWNER-APPROVED choice — not a
+ * gap somebody failed to close. The decision and the condition that reopens it
+ * are recorded here because the next person to read this file will otherwise
+ * re-derive the wrong answer from first principles.
+ *
+ * WHAT THE ATTACK ACTUALLY IS, bounded honestly. `org_id` and `api_key_id` are
+ * derived from the credential and the control-plane surface REFUSES both as
+ * body fields, so cross-tenant billing INJECTION is structurally impossible: a
+ * forged row can only ever land in the forger's OWN org. The only rational
+ * attack is therefore SELF-under-billing, it is not really a race (the header
+ * flushes at the head of a stream and this write happens on close, so the
+ * attacker has the whole generation), and it cannot be made quiet — every
+ * stolen request costs the attacker one refused write and one error line.
+ *
+ * REJECTED — GIVE THE PROXY A STANDING PLATFORM CREDENTIAL FOR THE WRITE. This
+ * is the obvious-sounding move and it is STRICTLY WORSE THAN THE FLAW. For a
+ * platform credential to REPLACE the caller's key on this write, `org_id` has
+ * to come back into the request body — there is nothing else left to carry
+ * tenancy. That deletes the one structural property that makes this surface
+ * safe at all, and it converts a proxy compromise from "whatever caller keys
+ * happen to be in flight" into "arbitrary billing rows for EVERY org, written
+ * from an internet-facing pod". The generalised rule, which outlives this
+ * module: A CREDENTIAL MAY BE ADDITIVE TO THE CALLER'S KEY, NEVER A
+ * REPLACEMENT FOR IT, because the caller's key is what carries tenancy.
+ *
+ * REJECTED — HAVE THE CONTROL PLANE DERIVE MORE AND TRUST THE BODY LESS. It
+ * already derives everything it can (`org_id`, `api_key_id`) and refuses what
+ * it must (`gpu_seconds`). Of what is left, the fields that DECIDE MONEY are
+ * exactly the fields it has no independent source for: nothing in the platform
+ * reports per-request token counts anywhere except this wire, and the
+ * `inference_id` is minted here. Authenticating the id would not help either —
+ * the attacker holds a LEGITIMATE id, read from its own response head.
+ *
+ * DEFERRED, WITH A TRIGGER — MAKE THE ROW UNFORGEABLE (a proxy-held key that
+ * signs the row's CONTENT, verified by the control plane, ADDITIVE to the
+ * caller's key so tenancy is untouched). This is the real fix and its blast
+ * radius is small: a stolen signing key only restores today's position,
+ * because the row still lands in whatever org the thief's own key names. It is
+ * NOT built yet because its own failure mode is worse than the flaw's while
+ * nothing bills off this table: a misconfigured or badly-rotated key takes
+ * 100% OF LEDGER ROWS TO ZERO ACROSS EVERY ORG, where the flaw takes some rows
+ * to zero for one customer attacking itself, loudly. Fitting a cryptographic
+ * gate to a writer that has never once run in production, in the week it first
+ * writes a row, is how a remedy costs more than the bug.
+ *
+ *   THE TRIGGER, EXPLICITLY: BUILD IT BEFORE ANY PRODUCT BILLS OFF
+ *   `public.inference_requests`. Today HF traffic authenticates as HF's own
+ *   org (the end user never holds a uRun key) and self-serve is billed off
+ *   `usage_events`, so no party both can run the attack and benefits from it.
+ *   The credits / concurrency-tier / retention-tier product is the moment that
+ *   stops being true, and it must not be the moment this is discovered.
+ *
+ * UNTIL THEN THE DETECTION IS THE CONTROL, so it is built to be OPERATED
+ * rather than merely to exist: the refusal carries a machine-readable
+ * `ledgerFailureReason` (`proxy/ledger.ts` {@link LedgerFailure}) that reaches
+ * both the structured log line and a Prometheus counter, so the alert is a
+ * field match and not a regex over this paragraph's prose.
+ *
+ * ===========================================================================
+ *
+ * EVERY FAILURE IS LOUD AND NONE OF THEM REACHES THE CUSTOMER. This runs from
+ * the response's `'close'` hook, after the answer is delivered, so there is no
+ * request left to fail: `proxy/ledger.ts` catches everything here and writes
+ * one structured log line. A write that did not land is revenue that was never
+ * recorded, which is exactly the thing that must never be silent.
+ */
+
+/**
+ * The control-plane route this writes. Relative to the org control-plane API
+ * base (`{apiUrl}`, i.e. `https://api.urun.sh/v1`), which the deployment's
+ * gateway rewrites onto the Supabase Edge Functions host — the same base and
+ * the same rewrite `GET {apiUrl}/apps` and the usage read already ride.
+ */
+declare const LEDGER_FUNCTION_PATH = "/inference-ledger";
+/**
+ * How long one write may take before it is abandoned. A single-row insert plus
+ * two indexed price lookups is milliseconds; this bound exists so a stalled
+ * socket becomes a log line rather than a promise retained for the life of the
+ * pod. Deliberately TIGHTER than the usage read's 15s: that read answers a
+ * live poller that is waiting, while this write has nobody waiting on it and
+ * every second it holds is a slot in the in-flight bound.
+ */
+declare const LEDGER_WRITE_TIMEOUT_MS = 10000;
+/**
+ * The row was already in the ledger. Its own type because it is not a fault
+ * and must not be logged as one: it means somebody wrote this `inference_id`
+ * before us, which is either a double-write defect in this proxy or a row
+ * fabricated by the org being billed. Nothing was written and nothing was
+ * overwritten.
+ */
+declare class LedgerDuplicateError extends Error implements LedgerFailure {
+    /**
+     * THE ENG-410 SIGNAL, as a field an alert can match.
+     *
+     * `duplicate` now means PROVABLY NOT OURS. Since the 409 carries the stored
+     * row (ENG-415), a conflict whose row matches what we are re-sending is our
+     * OWN earlier attempt and resolves as {@link LedgerAlreadyWrittenError}
+     * instead — so what is left here is a row somebody else wrote, or a row we
+     * could not read back to check. Both fail to the LOUD side on purpose.
+     *
+     * `duplicate_foreign` is the loudest state in the lane: the id is taken by a
+     * row THIS ORG CANNOT READ. `inference_requests.inference_id` is a global
+     * primary key, so it is reachable, and it can never be our own write.
+     */
+    readonly ledgerFailureReason: 'duplicate' | 'duplicate_foreign';
+    constructor(message: string, reason?: 'duplicate' | 'duplicate_foreign');
+}
+/** The control-plane write surface could not be reached or refused the row. */
+declare class LedgerSurfaceError extends Error implements LedgerFailure {
+    readonly ledgerFailureReason: "surface";
+    constructor(message: string);
+}
+interface LedgerClientOptions {
+    /** The org control-plane API base (`{apiUrl}`) the function is mounted under. */
+    apiUrl: string;
+    /** Injected in tests; production uses the platform fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Validate the control plane's answer into the record the caller logs.
+ *
+ * IT IS VALIDATED RATHER THAN TRUSTED because what it carries is a COST. A
+ * surface that changed shape under us must not be able to produce a log line
+ * claiming a request was priced at a number nobody returned — and
+ * `unpriced_reason` is what tells an operator that traffic is being served
+ * that nobody can bill, so a missing one is not a detail.
+ */
+declare function parseLedgerRecorded(raw: unknown, where: string): LedgerRecorded;
+/** One ledger row, written as the holder of the caller's own org API key. */
+declare class LedgerClient {
+    private readonly opts;
+    private readonly fetchImpl;
+    constructor(opts: LedgerClientOptions);
+    /**
+     * Write one row. Five outcomes, all explicit:
+     *   - the control plane records it → the validated {@link LedgerRecorded},
+     *     priced or with an `unpriced_reason`;
+     *   - the id is already there AND the stored row is OURS (409) →
+     *     {@link LedgerAlreadyWrittenError}, which is a SUCCESS: an earlier
+     *     attempt landed;
+     *   - the id is already there and the row is NOT ours, or cannot be read
+     *     back to check (409) → {@link LedgerDuplicateError};
+     *   - it rejects the key (401/403)  → {@link LedgerAuthError};
+     *   - anything else                 → {@link LedgerSurfaceError}.
+     *
+     * THE CALLER RETRIES, NOT THIS METHOD (ENG-415). One call is one attempt;
+     * `proxy/ledger.ts` owns the queue, the backoff and the dwell bound, and it
+     * retries only the one reason that is safe to retry. What makes any of it
+     * safe is the fifth outcome above: a retry whose first attempt secretly
+     * landed comes back as {@link LedgerAlreadyWrittenError}, not as something
+     * indistinguishable from a forged row.
+     */
+    write(apiKey: string, entry: LedgerWrite): Promise<LedgerRecorded>;
+}
 
 /**
  * The hosted endpoint's configuration.
@@ -670,8 +923,25 @@ declare function resolveHostedConfig(env?: NodeJS.ProcessEnv): HostedConfig;
  *                  reachable, because a replica that cannot verify API keys
  *                  or list apps can serve nothing and must be pulled out of
  *                  the Service rather than answering 502s.
- *   *    /v1/...   the compat surface, org-scoped by the Bearer key.
- *   *    anything else → 404 in the OpenAI error envelope.
+ *   *    /v1/...   the compat surface, org-scoped by the Bearer key, including
+ *                  the canonical usage-query lane POST /v1/usage/requests
+ *                  (proxy/usage.ts — a batch read of the per-request
+ *                  inference ledger).
+ *   POST /partners/<name>/...  the ENG-376 partner ADAPTER surface: a
+ *                  partner's own wire shape translated onto a canonical lane,
+ *                  sharing its auth and error mapping. Today: the Hugging
+ *                  Face billing poll. Ingress/charts must allowlist it.
+ *   WS   /ws/google.ai.generativelanguage.v1beta.GenerativeService.
+ *        BidiGenerateContent — the Gemini Live surface, org-scoped by the
+ *        Gemini credential (x-goog-api-key / Authorization: Bearer; `?key=`
+ *        refused). Ingress/charts must allowlist that path.
+ *   WS   /v1/realtime — the OpenAI Realtime surface (GA protocol subset),
+ *        org-scoped by the SAME Bearer api key as the /v1 lane; the
+ *        caller-org catalog's `task` column (stt | tts) gates which models
+ *        may bind an audio session. Ingress/charts must allowlist that
+ *        path too.
+ *   *    anything else → 404 in the OpenAI error envelope (unclaimed WS
+ *        upgrades get their own final refusal).
  *
  * WHAT IS DELIBERATELY NOT HERE: `/stats`. The local proxy exposes it for the
  * launcher's reuse probe; on a shared endpoint it would publish one tenant's
@@ -698,14 +968,232 @@ interface HostedProxyOptions extends HostedConfig {
     resolver?: OrgResolver;
     /** Injected in tests so backhauls are stubbed at the seam. */
     registry?: TenantRegistry;
+    /** Injected in tests so conversation backhauls are stubbed at the seam. */
+    conversations?: ConversationBackhauls;
+    /**
+     * Injected in tests so the canonical usage lane is exercised without a
+     * control plane. Production builds one against `apiUrl` — the same base and
+     * the same caller-key credential `GET {apiUrl}/apps` rides.
+     */
+    usageClient?: UsageClient;
+    /**
+     * Injected in tests so the per-request LEDGER WRITE is exercised without a
+     * control plane. Production builds one against `apiUrl` — the same base and
+     * the same caller-key credential the usage read and `GET {apiUrl}/apps`
+     * ride.
+     */
+    ledgerClient?: LedgerClient;
+    /**
+     * Sink for the ledger lane's own structured diagnostics (proxy/ledger.ts:
+     * one JSON object per write, skip or failure). DELIBERATELY SEPARATE from
+     * {@link requestLog}, which carries exactly one `inference_request` record
+     * per `/v1` request and whose readers count on that. Production leaves it
+     * unset, which is this container's stdout.
+     */
+    ledgerLog?: (line: string) => void;
+    /**
+     * Sink for the shared handler's per-request billing log line (the
+     * `Inference-Id` record — proxy/responses-turn.ts `ProxyHandlerOptions`).
+     * Injected in tests; production leaves it unset, which is this container's
+     * stdout — the log stream the platform collects.
+     */
+    requestLog?: (line: string) => void;
+    /**
+     * Collect Node process metrics (event-loop lag, heap, GC) alongside the
+     * request metrics. Production leaves it on; tests turn it off so an
+     * assertion on the exposition text is not swamped by process noise.
+     */
+    defaultMetrics?: boolean;
 }
 /**
- * Build (not listen) the hosted endpoint. The caller owns listen/close, and
- * `closeAll` releases every pooled backhaul through `Session.end()`.
+ * Build (not listen) the hosted endpoint. The caller owns listen/close,
+ * `closeAll` releases every pooled backhaul through `Session.end()`, and
+ * `closeWebSockets` gracefully closes every attached WS surface — a drain
+ * must run it BEFORE `server.close()`/`closeAllConnections()` (see
+ * {@link drainServer}).
  */
 declare function createHostedProxy(options: HostedProxyOptions): {
     server: Server;
+    /**
+     * The PRIVATE Prometheus listener (`proxy/metrics.ts` — GET /metrics on
+     * {@link METRICS_PORT}). Its own server, not a route on the one above, so
+     * "the metrics port is not public" is a property of the socket rather than
+     * a rule the `/v1` router must keep remembering. The caller owns
+     * listen/close, exactly as it does for `server`.
+     */
+    metricsServer: Server;
+    metrics: InferenceMetrics;
+    /**
+     * The PRIVATE ext-auth listener the edge calls to turn the caller's Bearer
+     * key into a non-secret bucket id (`hosted/edge-identity.ts`). Its own
+     * socket for the same reason the metrics port is: the public HTTPRoutes
+     * forward only to the `/v1` port, so it cannot be reached from outside.
+     * The caller owns listen/close.
+     */
+    edgeIdentityServer: Server;
     closeAll: () => Promise<void>;
+    closeWebSockets: () => Promise<void>;
 };
 
-export { BIND_HOST, type CallerIdentity, ControlPlaneUnavailableError, DEFAULT_PORT, type HostedConfig, type HostedProxyOptions, MAX_CACHED_KEYS, MAX_TENANTS, ORG_BINDING_TTL_MS, OrgResolver, type OrgResolverOptions, ProxyAuthError, READINESS_TIMEOUT_MS, READINESS_TTL_MS, SERVE_FUNCTION, TenantRegistry, type TenantRegistryOptions, bearerFrom, createHostedProxy, resolveHostedConfig, tenantSubject };
+/**
+ * THE EDGE IDENTITY SURFACE — the one thing Envoy cannot compute for itself.
+ *
+ * WHY IT EXISTS. Envoy Gateway's per-caller rate limiting needs a DISTINCT
+ * bucket per caller, and the only caller identity on this endpoint is the
+ * Bearer org API key (`hosted/auth.ts`: "the Bearer key IS the identity AND
+ * the tenancy"). Envoy Gateway can key a global rate limit on a header's
+ * distinct values — but the descriptor VALUE is what the rate-limit service
+ * sends to Redis and what Redis stores as part of its key. Keying directly on
+ * `Authorization` would therefore park live customer API keys, in plaintext,
+ * in an in-cluster Redis whose NetworkPolicy is inert on both prod clusters
+ * today (the VPC CNI node agent runs without `--enable-network-policy`, as the
+ * valkey chart already documents). That is a credential store nobody designed,
+ * audited, or rotates.
+ *
+ * Envoy's Lua filter has no hashing primitive and its rate-limit actions have
+ * no transform, so SOMETHING has to turn the key into a non-secret id before
+ * the rate-limit filter runs. Envoy Gateway's own mechanism for that is
+ * `SecurityPolicy.extAuth`, whose response headers are merged into the request
+ * ("coexisting headers will be overridden") before the later rate-limit filter
+ * reads them. This module is that service.
+ *
+ * IT IS NOT AN AUTHORIZATION GATE, AND IT MUST NEVER BECOME ONE. It answers
+ * 200 to everything. Authentication stays where it already is — in the proxy,
+ * which alone can answer 401 in the lane's native error envelope with the
+ * `Inference-Id` header HF bills on. A deny here would instead produce Envoy's
+ * bodiless refusal, which an OpenAI SDK surfaces as an unparseable error.
+ *
+ * IT HAS NO DEPENDENCIES, ON PURPOSE. Read a header, hash it, answer. No
+ * control-plane call, no cache, no I/O, nothing that can be slow or down. It
+ * sits in the request path of `inference.urun.sh`, so the only acceptable
+ * failure budget is none — and the `SecurityPolicy` that calls it is
+ * additionally configured `failOpen`, so even losing it entirely degrades to
+ * "no rate limiting", never to "no inference".
+ */
+
+/**
+ * The container's edge-identity port — a MODULE CONSTANT, not an env var, per
+ * the hosted config mandate (`hosted/config.ts`). Its own socket, like the
+ * metrics port: private by construction, since the public HTTPRoutes forward
+ * only to the `/v1` port.
+ */
+declare const EDGE_IDENTITY_PORT = 9465;
+/**
+ * THE BUCKET ID. Envoy Gateway's `BackendTrafficPolicy` keys the caller's
+ * rate-limit counter on this header's DISTINCT values, which means the value
+ * here IS the input the rate-limit service builds its Redis counter key from.
+ *
+ * THAT IS WHY IT MUST NOT BE THE VALUE COMMITTED IN `values.yaml`. The tier
+ * fingerprint below is written into a git-tracked manifest so an operator can
+ * give one caller its own limit. If the bucket id were the same digest, then
+ * ANYONE WHO CAN READ THE REPO could reconstruct a tiered caller's counter key
+ * — and the counter store is reachable by any pod in the cluster with
+ * `+incrby` and `+expire` granted, so they could spend Hugging Face's
+ * allowance or stretch the window and hold HF's own probe at 429. That is the
+ * delisting event this whole pair exists to prevent, and non-invertibility of
+ * SHA-256 does nothing about it: the attacker never needs the key, only the
+ * digest, and the digest was published on purpose.
+ *
+ * So the two digests are DIFFERENT one-way functions of the same token, split
+ * by domain separator ({@link BUCKET_DOMAIN} vs {@link TIER_DOMAIN}). Knowing
+ * the tier fingerprint gives no path to the bucket id: getting there would
+ * require recovering the token from its digest, which is a preimage attack on
+ * SHA-256 over 256 bits of `randomBytes` entropy.
+ */
+declare const EDGE_KEY_ID_HEADER = "x-urun-key-id";
+/**
+ * THE TIER SELECTOR — matched with `Exact` / `RegularExpression` in the
+ * BackendTrafficPolicy to decide WHICH limit applies, never to bucket.
+ *
+ * This is the digest an operator commits to `rateLimit.tiers[].keyIdSha256` in
+ * k8s-manifests, so treat it as PUBLIC: everything about the design has to
+ * hold when an attacker knows it.
+ *
+ * WHY A SECOND HEADER AT ALL. An Envoy Gateway rate-limit rule needs both
+ * kinds of match on the caller at once: `Distinct` (give this caller their own
+ * counter) AND an exact/inverted match (is this the partner key, or everyone
+ * else). Whether a single selector may list the SAME header name under two
+ * different match types is not something this repo can verify without a
+ * cluster, and getting it wrong means Envoy Gateway rejects the policy —
+ * which, on a fail-open limiter, is indistinguishable from "rate limiting
+ * works" until somebody floods us. Two headers remove the question; carrying
+ * two DIFFERENT digests is what makes publishing one of them safe.
+ */
+declare const EDGE_KEY_FINGERPRINT_HEADER = "x-urun-key-fingerprint";
+/**
+ * Domain separator for the BUCKET digest. Never appears in a manifest, a log,
+ * or a metric — the bucket id is derived here and read only by Envoy.
+ */
+declare const BUCKET_DOMAIN = "urun-ratelimit-bucket:";
+/**
+ * Domain separator for the TIER digest — the one an operator reproduces from a
+ * key with `printf 'urun-ratelimit-tier:%s' "$KEY" | sha256sum | cut -d' ' -f1`.
+ *
+ * A plain `sha256sum "$KEY"` would be the OLD, unsafe value: identical to the
+ * bucket id, and therefore a published counter key. The separator is what
+ * keeps the two apart, so it is part of the operator contract and cannot drift.
+ */
+declare const TIER_DOMAIN = "urun-ratelimit-tier:";
+/**
+ * The bucket every request WITHOUT a Bearer token shares. A single shared
+ * bucket rather than no bucket at all: unauthenticated floods must be limited
+ * too, and they have no identity to spread across. They cannot consume a real
+ * caller's bucket because no real key hashes to this value.
+ */
+declare const ANONYMOUS_KEY_ID = "anonymous";
+/**
+ * The caller's BUCKET id — `sha256(BUCKET_DOMAIN || token)`, hex.
+ *
+ * SECRET BY CONSTRUCTION, not because the digest is one-way but because the
+ * only published digest is a DIFFERENT one. This value is the input Envoy's
+ * rate-limit descriptor carries, so it is what the counter key in the
+ * rate-limit cache is built from; publishing it would publish a writable
+ * counter key (see {@link EDGE_KEY_ID_HEADER}).
+ */
+declare function edgeBucketId(bearerToken: string): string;
+/**
+ * The caller's TIER fingerprint — `sha256(TIER_DOMAIN || token)`, hex.
+ *
+ * PUBLIC BY DESIGN: this is the value an operator commits to
+ * `rateLimit.tiers[].keyIdSha256`. The runbook is
+ * `printf 'urun-ratelimit-tier:%s' "$KEY" | sha256sum | cut -d' ' -f1`.
+ *
+ * The domain prefix is not decoration — a bare `sha256sum "$KEY"` reproduces
+ * the BUCKET id, which is exactly the value that must never be committed. The
+ * `cut` is load-bearing too: `sha256sum` prints the digest, two spaces, then
+ * the input name, and a tier carrying that trailing `  -` matches nothing and
+ * silently leaves the caller on the default limit.
+ */
+declare function edgeTierFingerprint(bearerToken: string): string;
+/**
+ * The bearer token of an `Authorization` header, or null.
+ *
+ * Deliberately NOT `hosted/auth.ts` `bearerFrom`: that one THROWS a 401-shaped
+ * error for a missing or malformed header, which is the correct behaviour for
+ * the lane that authenticates. Here a malformed header must produce the
+ * anonymous bucket and a 200, because refusing is the proxy's job and this
+ * service must never refuse.
+ */
+declare function bearerTokenOf(headerValue: string | undefined): string | null;
+/**
+ * The PRIVATE ext-auth listener. Answers 200 to every method and every path —
+ * Envoy appends the ORIGINAL request path to the configured ext-auth path, so
+ * this service sees `/ratelimit-identity/v1/chat/completions` and friends and
+ * must not care.
+ *
+ * The response carries exactly the two identity headers below, and the
+ * `SecurityPolicy` forwards exactly those two (`headersToBackend`). Nothing
+ * about the caller's request, and certainly not their key, is echoed.
+ *
+ * A CALLER CANNOT PRESENT THEIR OWN. `headersToBackend` is documented as
+ * overriding coexisting headers, so whatever a client sent under these names is
+ * replaced on every request this service answers. There is deliberately NO
+ * `ClientTrafficPolicy` stripping them at the listener: that policy would
+ * attach to the shared `public-gw` (api.urun.sh rides it too) to close a gap
+ * that grants nothing — in the only case where a client value survives, the
+ * ext-auth hop has already failed open, and fail-open grants MORE than any
+ * spoofed bucket could. The k8s half records the same decision.
+ */
+declare function createEdgeIdentityServer(): Server;
+
+export { ANONYMOUS_KEY_ID, BIND_HOST, BUCKET_DOMAIN, BoundedLabel, type CallerIdentity, ControlPlaneUnavailableError, type ConversationBackhaulOptions, ConversationBackhauls, ConversationCapacityError, DEFAULT_PORT, EDGE_IDENTITY_PORT, EDGE_KEY_FINGERPRINT_HEADER, EDGE_KEY_ID_HEADER, type HostedConfig, type HostedProxyOptions, InferenceMetrics, LEDGER_FUNCTION_PATH, LEDGER_WRITE_TIMEOUT_MS, LedgerClient, type LedgerClientOptions, LedgerDuplicateError, LedgerSurfaceError, MAX_CACHED_KEYS, MAX_CONVERSATIONS, MAX_CONVERSATION_HANDLES, MAX_MODEL_LABELS, MAX_ORG_LABELS, MAX_TENANTS, METRICS_PATH, METRICS_PORT, NO_MODEL_LABEL, ORG_BINDING_TTL_MS, OTHER_LABEL, OrgResolver, type OrgResolverOptions, type PrivateConversationBackhaul, type PrivateConversationConnection, ProxyAuthError, READINESS_TIMEOUT_MS, READINESS_TTL_MS, SERVE_FUNCTION, TIER_DOMAIN, TenantRegistry, type TenantRegistryOptions, bearerFrom, bearerTokenOf, createEdgeIdentityServer, createHostedProxy, createMetricsServer, edgeBucketId, edgeTierFingerprint, laneOf, parseLedgerRecorded, resolveHostedConfig, statusClassOf, tenantSubject };