@urun-sh/openai 0.5.5 → 0.6.0

package/dist/hosted/index.d.cts

@@ -1,10 +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-BfdBbey8.cjs';
 import { createClientToken } from '@urun-sh/core';
-import { U as UrunResponses } from '../ResponsesClient-Dft3bg3b.cjs';
-import { b as UrunSessionLike } from '../types-lsVTbNcH.cjs';
-import { S as SessionGoneError, P as ProxyClients, M as ModelRouter } from '../responses-turn-OrO4euEN.cjs';
-import '../models-NYMZrklp.cjs';
-import '../video-out-D20UuJ8G.cjs';
+import { U as UrunResponses } from '../ResponsesClient-_OZERUjH.cjs';
+import { b as UrunSessionLike } from '../types-CHPtJx6d.cjs';
+import '../models-DUdx_Y6X.cjs';
+import '../video-out-BsuLqlID.cjs';
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+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)";
+/**
+ * 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.
+ */
+declare const MAX_MODEL_LABELS = 64;
+/**
+ * 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 const MAX_ORG_LABELS = 128;
+/** Collapse a client-supplied path onto the bounded lane label. */
+declare function laneOf(path: string): string;
+/**
+ * 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);
+    /**
+     * @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.
+     */
+    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 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 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;
+    });
+    /**
+     * Count ONE terminal ledger outcome — the third sink for a request that
+     * `proxy/ledger.ts` already logs, counted so it can be alerted on.
+     *
+     * 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.
+     */
+    observeLedger(outcome: LedgerOutcome): void;
+    /**
+     * Count ONE completed `/v1` request. Takes the very record
+     * `inferenceRequestLine` serializes, so the counters and the billing log can
+     * never drift apart.
+     */
+    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.
@@ -128,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`
@@ -220,6 +364,19 @@ type OwnedSession = UrunSessionLike & {
         name: string;
         reason?: string;
     }) => void) => () => void;
+    whenLive?: (options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    /**
+     * Core's NATIVE admission-ticket cancel (`Session.cancel`): hands back the
+     * claim a still-QUEUED call waits on — once the call HAS a session, the
+     * installed handler refuses loudly. Optional here because only the
+     * client-gone abandon path requires it; that path falls back to the native
+     * `detach` when a session object lacks it (the queued shape does not exist
+     * there), and never approximates with `end()`.
+     */
+    cancel?: () => Promise<unknown>;
 };
 /**
  * One pooled backhaul: the session, its (stateful) Responses client, and the
@@ -301,6 +458,24 @@ interface TenantRegistryOptions {
     apiUrl: string;
     /** The model-catalog oracle for routing rule 5, or null. */
     catalog: CatalogConfig | null;
+    /**
+     * THE STATELESS DIRECT PATH (urun-ts #497): present ⇒ every tenant's
+     * clients carry a per-caller decision dial — discovery over the CALLER'S
+     * own key (`GET {apiUrl}/runtimes`), tokens minted with the caller's
+     * org/app/fn, the flat body POSTed to the ready runtime's `:8099/v1/decision`.
+     * `shared` (the shared org's API key, when mounted) extends the same dial
+     * to SHARED-catalog models: discovery under the shared key, the token's
+     * `tenant` stays the caller and `provider` names the pod org from the
+     * block's `shared_org_id` (the intake's provider-aware org gate). Absent
+     * ⇒ shared models keep the session dial. Absent ⇒ no dial exists and every
+     * decision rides the session lane byte-for-byte.
+     */
+    decisionIntake?: {
+        secret: string;
+        shared?: {
+            apiKey: string;
+        };
+    };
     /** Injected in tests; production builds real uRun backhauls. */
     build?: (caller: CallerIdentity) => {
         router: ModelRouter<PoolEntry>;
@@ -319,6 +494,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;
@@ -443,6 +636,243 @@ declare class ConversationBackhauls {
     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.
  *
@@ -491,6 +921,39 @@ interface HostedConfig {
     apiUrl: string;
     /** The `model_catalog` oracle for routing rule 5, or null when unconfigured. */
     catalog: CatalogConfig | null;
+    /**
+     * THE STATELESS DIRECT PATH's credential (URUN_SESSION_TOKEN_SECRET) — the
+     * runtime scoped-token signing secret the decision intake verifies
+     * (urun-python decision_intake). A SECRET input, not a behavior knob: it is
+     * the mandate's allowed env class, and it is the SAME predicate the local
+     * lane enables on (cli.ts statelessDialEnabled), so the two lanes can never
+     * disagree. Absent ('') the stateless lane does not exist and every
+     * decision rides the session lane byte-for-byte. Present, decisions for
+     * CALLER-ORG serves="openai" apps dispatch straight to a ready runtime's
+     * `:8099/v1/decision`: discovery rides the CALLER'S OWN key
+     * (`GET {apiUrl}/runtimes`), and the per-decision token is minted with the
+     * caller's org/app/fn identity. Shared-catalog models keep the session
+     * dial — the v1 boundary #497 declares (the dial's own targetFor refuses
+     * them).
+     *
+     * OPTIONAL on this bag because legacy constructors may omit it
+     * (resolveHostedConfig always supplies it — '' when the env is absent);
+     * consumers read it as `?? ''`.
+     */
+    decisionSecret?: string;
+    /**
+     * THE SHARED LANE'S credential (URUN_SHARED_ORG_API_KEY): the shared org's
+     * API key, so the decision dial can discover — and its tokens can name via
+     * the block's `shared_org_id` — the SHARED org's pods. Optional: absent ⇒
+     * shared models keep the session dial (the stateless boundary narrows to
+     * "no shared credential mounted"). URUN_SHARED_ORG_ID must ride WITH it
+     * (both-or-neither, loud) purely as the identity statement of the key —
+     * the dial never re-spells the pod org; it reads `shared_org_id` from the
+     * block that resolved the lane, so key and pod org cannot drift.
+     */
+    sharedOrgKey?: string;
+    /** Identity statement accompanying `sharedOrgKey` (URUN_SHARED_ORG_ID). */
+    sharedOrgId?: string;
 }
 /**
  * Read and VALIDATE the deployment's external inputs. Every failure is loud
@@ -520,11 +983,23 @@ 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.
+ *   *    /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).
  *
@@ -555,6 +1030,40 @@ interface HostedProxyOptions extends HostedConfig {
     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,
@@ -565,8 +1074,192 @@ interface HostedProxyOptions extends HostedConfig {
  */
 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;
+    /**
+     * The tenant registry this proxy built (production wiring). Tests assert
+     * the per-caller stateless dial through it; production code goes through
+     * `callerOf`, never here.
+     */
+    registry: TenantRegistry;
     closeAll: () => Promise<void>;
     closeWebSockets: () => Promise<void>;
 };
 
-export { BIND_HOST, type CallerIdentity, ControlPlaneUnavailableError, type ConversationBackhaulOptions, ConversationBackhauls, ConversationCapacityError, DEFAULT_PORT, type HostedConfig, type HostedProxyOptions, MAX_CACHED_KEYS, MAX_CONVERSATIONS, MAX_CONVERSATION_HANDLES, MAX_TENANTS, ORG_BINDING_TTL_MS, OrgResolver, type OrgResolverOptions, type PrivateConversationBackhaul, type PrivateConversationConnection, 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 };