@omnicross/core 0.1.2 → 0.1.4

package/dist/outbound-api.d.cts

@@ -1,24 +1,99 @@
-import { EndpointRoutingConfig, OutboundApiDeps, OutboundApiServerStatus, OutboundFormatUrls, OutboundApiServerConfig, OutboundKeyDb, OutboundApiKeyCreated, RequestRole } from './outbound-api/types.cjs';
-export { OutboundApiKeyInfo, OutboundEndpoint, OutboundKeyDbRow } from './outbound-api/types.cjs';
+import { VoucherConfig } from '@omnicross/contracts/voucher-types';
+import { e as KindMappedEndpoint, f as ModelKind, m as OutboundEndpoint, b as EndpointRoutingConfig, k as OutboundApiServerConfig, U as UserMessageQueueConfig, a as ConcurrencyQueueConfig, h as OutboundApiDeps, l as OutboundApiServerStatus, n as OutboundFormatUrls, A as AccountProbeConfig, F as FingerprintConfig, g as ModelPrefixTargets, r as OutboundProxyConfig, G as ModelRef, O as OutboundKeyDb, i as OutboundApiKeyCreated, R as RequestRole } from './types-B8Arpxn0.cjs';
+export { C as ChatDispatchMode, E as ENDPOINT_MODEL_KINDS, K as KeySpendReader, c as KeySpendSeeder, d as KeySpendTracker, M as MessagesModelKind, j as OutboundApiKeyInfo, o as OutboundKeyActivationMode, p as OutboundKeyDbRow, q as OutboundKeyPolicy, s as ResponsesModelKind, V as VoucherCreateInput, t as VoucherDb, u as computeVoucherGrant, v as generateVoucherCode, w as hashVoucherCode, x as newVoucherId, y as startOfLocalDay, z as startOfLocalWeek, B as toVoucherInfo, D as voucherCodePrefix } from './types-B8Arpxn0.cjs';
+import { ProxyConfig } from '@omnicross/contracts/account-tokens-types';
+import { AuditConfig } from '@omnicross/contracts/audit-types';
+import { BillingConfig } from '@omnicross/contracts/billing-types';
+import { WebhookDestination, WebhookConfig } from '@omnicross/contracts/webhook-types';
+export { AUDIT_REDACTED, redactAuditText } from './outbound-api/auditRedact.cjs';
+export { AuditCaptureContext, beginAuditCapture } from './outbound-api/auditCapture.cjs';
+export { BillingCaptureContext, beginBillingCapture } from './outbound-api/billingCapture.cjs';
+import { K as KeyCostLimits, M as ModelRestriction } from './keyPolicy-Cp0FntZl.cjs';
+export { a as KeyExpiryInput, b as KeyExpiryResult, c as KeySpend, Q as QuotaDecision, d as checkKeyQuota, e as computeKeyExpiry } from './keyPolicy-Cp0FntZl.cjs';
+import http from 'node:http';
 import { IngressFormat } from './provider-proxy/types.cjs';
-export { S as SUBSCRIPTION_PROVIDER_IDS, e as endpointSupportsSubscription, i as isSubscriptionProviderId, r as resolveRoute } from './routeResolver-BrbK6ja9.cjs';
+export { S as SUBSCRIPTION_PROVIDER_IDS, e as endpointSupportsSubscription, i as isSubscriptionProviderId, p as parseModelRef, a as pickModelRefFromList, r as resolveRoute } from './routeResolver-CB3tvJKy.cjs';
+import '@omnicross/contracts/health-logging-types';
+import './logger-4GvQNzhE.cjs';
 import './ports/provider-config-source.cjs';
 import '@omnicross/contracts/llm-config';
 import './transformer/types.cjs';
 import './transformer/TransformerService.cjs';
 import './ProviderProxy-CnMQYN59.cjs';
-import 'node:http';
 import '@omnicross/contracts/completion-types';
 import '@omnicross/contracts/subscription-types';
 import '@omnicross/contracts/usage-types';
 import './completion/ApiKeyPoolService.cjs';
-import './logger-4GvQNzhE.cjs';
 import './pipeline/AuthSource.cjs';
 import './pipeline/SubscriptionAuthSource.cjs';
 import './pipeline/SubscriptionAuthStrategy.cjs';
 import './ports/web-search-backend.cjs';
 import '@omnicross/contracts/websearch-types';
 
+/**
+ * kindDetection — classify an outbound request's model KIND for the kind-mapped
+ * endpoints (`messages`/`responses`) and validate their config completeness
+ * (`outbound-api-server`, model-kind-mapping contract).
+ *
+ * The kind-mapped endpoints route by a version-INDEPENDENT model KIND rather
+ * than by role: the user configures one upstream ref per kind
+ * ({@link ENDPOINT_MODEL_KINDS}) and an incoming versioned client id
+ * (`claude-opus-4-8-2026xxxx`) is classified to its kind (`opus`) so CLI
+ * upgrades need no reconfig. `chat`/`gemini` stay on `roleDetection`.
+ *
+ * Pure module — no I/O. The router decides, per endpoint, whether to call
+ * `detectModelKind` (messages/responses) or `detectRequestRole` (chat/gemini);
+ * the routing RESOLUTION and the startup-gate ENFORCEMENT live downstream.
+ *
+ * @module outbound-api/kindDetection
+ */
+
+/**
+ * Narrow an endpoint to the kind-mapped set (`messages`/`responses`). `chat`
+ * and `gemini` are role-based and return false.
+ */
+declare function isKindMappedEndpoint(endpoint: OutboundEndpoint): endpoint is KindMappedEndpoint;
+/** The canonical kinds for a kind-mapped endpoint (in declaration order). */
+declare function modelKindsForEndpoint(endpoint: KindMappedEndpoint): readonly ModelKind[];
+/**
+ * Extract the version-INDEPENDENT model KIND for a kind-mapped endpoint.
+ *  - `messages`: the FIRST id token that is one of {fable,opus,sonnet,haiku};
+ *    `undefined` when no token matches (the unmatched-kind fallback is SERVING's
+ *    decision, not core's).
+ *  - `responses`: `mini` when {@link isBackgroundTierModel}; else `codex`
+ *    (codex is the else-branch — a present id always resolves).
+ *  - Any empty/blank id ⇒ `undefined`.
+ *
+ * Reuses `normalizeModelId` + the shared `/[-._:/\s]+/` tokenizer
+ * (`modelTokens`) + the small-tier token set (`isBackgroundTierModel`) so the
+ * kind and role detectors stay token-boundary-consistent.
+ */
+declare function detectModelKind(endpoint: KindMappedEndpoint, requestedModelId: string | undefined): ModelKind | undefined;
+/**
+ * The kinds THIS endpoint declares but leaves unconfigured (blank/absent ref).
+ * Role-based endpoints (`chat`/`gemini`) have no declared kinds → `[]`.
+ * Absent and blank refs are treated identically; a malformed-but-non-blank ref
+ * is a serving-time concern, not a startup-gate one.
+ */
+declare function validateEndpointModelConfig(config: EndpointRoutingConfig): ModelKind[];
+/** One incomplete kind-mapped endpoint and the kinds it is missing. */
+interface EndpointModelConfigError {
+    endpoint: KindMappedEndpoint;
+    missingKinds: ModelKind[];
+}
+/**
+ * Server-level completeness, PER-ENDPOINT: a kind-mapped endpoint whose
+ * declared kinds are ALL blank/absent counts as UNCONFIGURED — the operator
+ * simply doesn't use that endpoint, so it does NOT block startup (its requests
+ * 503 per-request instead). Only a PARTIALLY configured endpoint (some kinds
+ * set, some blank — a real config mistake that would silently misroute) is
+ * returned as an error. Empty result ⇒ the config satisfies the startup gate.
+ *
+ * Serving consumes this for the gate ENFORCEMENT; it MAY tighten to an
+ * all-endpoints-strict policy by composing {@link validateEndpointModelConfig}.
+ */
+declare function validateServerModelConfig(config: OutboundApiServerConfig): EndpointModelConfigError[];
+
 /**
  * OutboundApiServer — the external-facing HTTP listener for the outbound API
  * server (`outbound-api-server`, design D1/D4/D5).
@@ -51,6 +126,24 @@ interface ApplyConfigInput {
     networkBinding: boolean;
     endpoints: EndpointRoutingConfig[];
     port?: number;
+    /** User-message serial-queue segment (normalized/defaulted by core). */
+    userMessageQueue?: UserMessageQueueConfig;
+    /** Per-key concurrency-queue segment (normalized/defaulted by core). */
+    concurrencyQueue?: ConcurrencyQueueConfig;
+    /** Voucher segment (voucher-redemption #9). Read live per request; absent ⇒
+     *  disabled ⇒ the `/redeem` endpoint is inert (zero regression). */
+    voucher?: VoucherConfig;
+}
+/**
+ * Thrown by {@link OutboundApiServer.applyConfig} when an ENABLED server is asked
+ * to bind with an INCOMPLETE model-kind map (the "未配置 → 无法启动接口服务" gate,
+ * design D6). Carries the per-endpoint missing kinds so the daemon/UI can render
+ * an actionable message; the server does NOT bind. Exported from the barrel so
+ * the daemon (surface) can `instanceof`-narrow it.
+ */
+declare class OutboundApiConfigError extends Error {
+    readonly missing: EndpointModelConfigError[];
+    constructor(missing: EndpointModelConfigError[]);
 }
 declare class OutboundApiServer {
     private readonly deps;
@@ -60,7 +153,25 @@ declare class OutboundApiServer {
     private boundPort;
     private boundAddr;
     private endpoints;
+    private userMessageQueue;
+    private concurrencyQueue;
+    private voucherConfig;
     private readonly rateLimiter;
+    /**
+     * Redeem-attempt limiter (voucher-redemption #9, design D6) — a SEPARATE bucket
+     * from the traffic `rateLimiter`, keyed by the authenticating key id, so
+     * brute-forcing `CC_` codes is throttled (a handful/min) without touching the
+     * per-key request rate. Conservative fixed defaults (10 / 60s).
+     */
+    private readonly redeemLimiter;
+    /**
+     * Per-key redeem mutex (voucher-redemption #9, MJ1 fix). One instance for the
+     * server's lifetime so concurrent redeem REQUESTS for the same key serialize
+     * (relative grant increments accumulate instead of clobbering a snapshot).
+     */
+    private readonly redeemMutex;
+    private readonly serialQueue;
+    private readonly concurrencyGate;
     constructor(deps: OutboundApiDeps, 
     /** Called when the actual bound port differs from the requested one. */
     onPortChange?: ((port: number) => void) | undefined);
@@ -76,10 +187,37 @@ declare class OutboundApiServer {
     private listen;
     /** Per-request handler. Auth is enforced on EVERY request (incl. loopback). */
     private onRequest;
+    /**
+     * Serve `GET|HEAD /health` (+ `/healthz`) from the injected provider, returning
+     * true when it handled the request. 200 when `ok`, else 503; secret-free body.
+     */
+    private tryServeHealth;
+    /** Route an info lifecycle line through the injected logger, else `console.log`
+     *  (byte-identical legacy fallback when no logger is wired). */
+    private logInfo;
+    /** Route an error lifecycle line through the injected logger, else `console.error`. */
+    private logError;
     /** Stop the listener and release the port. */
     stop(): Promise<void>;
     /** A live status snapshot for the Settings tab. */
     getStatus(): OutboundApiServerStatus;
+    /**
+     * Live queue-occupancy snapshot (only active entries). This getter's name +
+     * shape are FROZEN — `omnicross-uqc-daemon` spreads it into its `/status`
+     * response; the existing {@link getStatus} shape is deliberately NOT changed.
+     */
+    getQueueStatus(): {
+        serial: Array<{
+            providerId: string;
+            holding: boolean;
+            waiting: number;
+        }>;
+        concurrency: Array<{
+            apiKeyId: string;
+            active: number;
+            waiting: number;
+        }>;
+    };
 }
 /** Build the four format endpoint URLs for a base URL. */
 declare function formatUrls(base: string): OutboundFormatUrls;
@@ -90,20 +228,137 @@ declare function formatUrls(base: string): OutboundFormatUrls;
  *
  * The config (`{ enabled, networkBinding, endpoints, port }`) is persisted via
  * a small key/value store (the app SettingsService) under a single key, so it
- * survives restart. Defaults: disabled, loopback, four endpoints with empty
- * models + `useSubscription` OFF, default port. Shared by the router and the
- * bootstrap wiring so both read/write the same shape.
+ * survives restart. Defaults: disabled, loopback, four blank endpoints +
+ * `useSubscription` OFF, default port. The per-endpoint shape is heterogeneous:
+ * kind-mapped endpoints (`messages`/`responses`) carry a blank `modelMap` (one
+ * key per declared kind); role-based endpoints (`chat`/`gemini`) carry blank
+ * `defaultModel`/`backgroundModel`. NO legacy migration — `normalizeServerConfig`
+ * drops unknown/legacy fields (incl. `visionModel`) and fills blanks. Shared by
+ * the router and the bootstrap wiring so both read/write the same shape.
  *
  * @module outbound-api/apiServerConfig
  */
 
 /** The settings key the config persists under. */
 declare const OUTBOUND_API_SERVER_CONFIG_KEY = "outboundApiServer.config";
+/**
+ * Frozen defaults for the user-message serial queue segment (SSOT). Note the
+ * `waitTimeoutMs` default is **60000** — the office-hours draft's 30000 is
+ * superseded by the user's拍板 / planning-context §COMMITTED.
+ */
+declare const DEFAULT_USER_MESSAGE_QUEUE: UserMessageQueueConfig;
+/** Frozen defaults for the per-key concurrency queue segment (SSOT). */
+declare const DEFAULT_CONCURRENCY_QUEUE: ConcurrencyQueueConfig;
+/**
+ * Frozen defaults for the scheduled account-probe segment (SSOT,
+ * subscription-account-probe #8). Default OFF (zero regression); a 15-min cadence,
+ * multi-account-only, short timeout, small rolling history, staggered — every knob
+ * a load-safety valve (see `AccountProbeConfig`).
+ */
+declare const DEFAULT_ACCOUNT_PROBE: AccountProbeConfig;
+/** Fill + range-CLAMP the account-probe segment to the frozen defaults. */
+declare function normalizeAccountProbe(raw: Partial<OutboundApiServerConfig> | undefined | null): AccountProbeConfig;
+/**
+ * Fill + range-CLAMP the request-audit segment to the frozen defaults
+ * (request-audit-log, design D2). Lenient like the other segment normalizers:
+ * `enabled`/`captureBodies`/`trustForwardedFor` coerce to booleans (default
+ * false), `maxBodyBytes` clamps to `[256, 1_048_576]`, `retentionDays` clamps to
+ * `[1, 365]`. Default (all-off) ⇒ no capture ⇒ zero regression.
+ */
+declare function normalizeAudit(raw: Partial<OutboundApiServerConfig> | undefined | null): AuditConfig;
+/**
+ * Fill + range-CLAMP the billing segment to the frozen defaults
+ * (billing-event-stream, design D6). Lenient like `normalizeAudit`: `enabled`
+ * coerces to a boolean (default false); `endpoint`/`secret` are carried only when
+ * non-empty strings (a blank/absent `endpoint` ⇒ ledger-only mode); `maxRetryAgeMs`
+ * clamps to `[60_000, 30 days]`. Default (off) ⇒ no publish ⇒ zero regression.
+ */
+declare function normalizeBilling(raw: Partial<OutboundApiServerConfig> | undefined | null): BillingConfig;
+/**
+ * Frozen defaults for the client-fingerprint segment (SSOT,
+ * subscription-client-fingerprint #7). Default OFF ⇒ no capture/replay ⇒
+ * byte-identical outbound headers.
+ */
+declare const DEFAULT_FINGERPRINT: FingerprintConfig;
+/**
+ * Fill the client-fingerprint segment to the frozen defaults. Lenient like the
+ * other segment normalizers: `enabled` coerces to a boolean (default false); `ua`
+ * is carried only when a non-empty trimmed string (a blank/absent baseline stays
+ * absent). Default (off) ⇒ zero regression. Carries NO secret.
+ */
+declare function normalizeFingerprint(raw: Partial<OutboundApiServerConfig> | undefined | null): FingerprintConfig;
+/**
+ * Fill the voucher segment to the frozen defaults (voucher-redemption #9). Lenient
+ * like the other segment normalizers: `enabled` coerces to a boolean (default
+ * false). Default (off) ⇒ the redeem endpoint is inert ⇒ zero regression. Carries
+ * NO secret (codes are hashed at rest in the separate voucher store).
+ */
+declare function normalizeVoucher(raw: Partial<OutboundApiServerConfig> | undefined | null): VoucherConfig;
+/**
+ * Validate ONE `ProxyConfig` (upstream-proxy). Returns the cleaned descriptor or
+ * `undefined` (drop) when malformed. Lenient like the other segment normalizers:
+ *  - `{ url }`        — a non-empty string URL (trimmed).
+ *  - structured       — `type` ∈ {http,https,socks5} + non-empty `host` + a
+ *                       finite integer `port` in `1..65535`. `username`/`password`
+ *                       are non-empty-string-or-omit (may be `enc:`/`$ENV` at load
+ *                       — the secret box decrypts afterwards).
+ * Never throws.
+ */
+declare function normalizeProxyConfig(raw: unknown): ProxyConfig | undefined;
+/**
+ * Validate the optional `proxy` segment (upstream-proxy). Drops malformed entries
+ * (a bad `global` or a bad `byProvider[*]` value/key is dropped, never thrown).
+ * Returns `undefined` when nothing valid remains — a missing/empty proxy segment
+ * stays ABSENT (zero-config = direct fetch; unlike `accountHealth`, no default is
+ * synthesized).
+ */
+declare function normalizeProxySegment(raw: unknown): OutboundProxyConfig | undefined;
+/**
+ * Validate ONE webhook destination (webhook-notifications). Returns the cleaned
+ * descriptor or `undefined` (drop) when malformed — lenient like the proxy
+ * normalizer, never throws:
+ *  - `id`   — a non-empty trimmed string.
+ *  - `type` — ∈ {custom, feishu}.
+ *  - `url`  — a non-empty trimmed string.
+ *  - `secret` — non-empty-string-or-omit (may be `enc:`/`$ENV` at load — the
+ *               settings-store secret box decrypts afterwards).
+ *  - `events` — kept only when a non-empty array of known kinds (unknown kinds
+ *               dropped); an absent/empty filter means "all kinds".
+ *  - `enabled` — coerced boolean (default true — a destination in the list is on
+ *                unless explicitly disabled).
+ */
+declare function normalizeWebhookDestination(raw: unknown): WebhookDestination | undefined;
+/**
+ * Validate the optional `webhook` segment (webhook-notifications). Drops
+ * malformed destinations; `enabled` defaults false. Returns `undefined` when the
+ * segment is absent/non-object — a missing webhook segment stays ABSENT (no sink
+ * wired ⇒ zero regression), unlike `accountHealth` no default is synthesized. A
+ * present segment with `enabled` present OR any valid destination is kept.
+ */
+declare function normalizeWebhookSegment(raw: unknown): WebhookConfig | undefined;
+/**
+ * Fill + range-CLAMP the two queue segments to the frozen defaults. Lenient:
+ * out-of-range persisted numerics are clamped to the nearest bound, never
+ * thrown — strict validation is the daemon admin PUT's job. `enabled` coerces
+ * to a boolean (default false).
+ */
+declare function normalizeQueueSegments(raw: Partial<OutboundApiServerConfig> | undefined | null): {
+    userMessageQueue: UserMessageQueueConfig;
+    concurrencyQueue: ConcurrencyQueueConfig;
+};
 /** Structural subset of the settings store the config loader needs. */
 interface ApiServerSettingsStore {
     get<T = unknown>(key: string): Promise<T | undefined>;
     set<T = unknown>(key: string, value: T): Promise<void>;
 }
+/**
+ * Validate the optional `chat` prefix-target map (openai-chat-bridge #11). Keeps
+ * ONLY the three known prefixes (`claude`/`gpt`/`gemini`) whose value is a
+ * non-empty trimmed `"providerId,modelId"` string; drops everything else. Returns
+ * `undefined` when nothing valid remains (a prefix-mode chat endpoint with no
+ * targets simply routes nothing until configured). Never throws.
+ */
+declare function normalizePrefixTargets(raw: unknown): ModelPrefixTargets | undefined;
 /** The default server config: disabled, loopback, four blank endpoints. */
 declare function defaultServerConfig(): OutboundApiServerConfig;
 /**
@@ -119,6 +374,255 @@ declare function saveServerConfig(store: ApiServerSettingsStore, config: Outboun
 /** Apply a partial patch to a config, returning the merged whole. */
 declare function mergeServerConfig(current: OutboundApiServerConfig, patch: Partial<OutboundApiServerConfig>): OutboundApiServerConfig;
 
+/**
+ * modelPrefixDispatch — pure model-name PREFIX classification for the `chat`
+ * endpoint's opt-in `dispatchMode: 'prefix'` (openai-chat-bridge #11, design D2).
+ *
+ * In prefix mode the requested model's leading vendor token selects a configured
+ * target from {@link ModelPrefixTargets} (`claude-*` → `claude`, `gpt-*` → `gpt`,
+ * `gemini-*` → `gemini`), so an operator can serve many upstreams from a single
+ * `/v1/chat/completions` without an explicit per-model list entry. The match is
+ * case-insensitive and anchored at the START of the id (a token prefix, not a
+ * substring — `my-gpt-thing` does NOT classify as `gpt`). This is a ROUTING
+ * convenience layered on top of the existing conversion machinery; it changes
+ * only which upstream a model resolves to, never how the body is translated.
+ *
+ * @module outbound-api/modelPrefixDispatch
+ */
+
+/** The three core prefixes this dispatch vocabulary recognizes. */
+type ModelPrefixKind = 'claude' | 'gpt' | 'gemini';
+/**
+ * Classify a requested model id by its leading vendor token. Case-insensitive;
+ * anchored at the start (matches `<prefix>` exactly or `<prefix>-…`). Returns the
+ * matched {@link ModelPrefixKind}, or `null` when no known prefix applies (an
+ * empty/blank id also yields `null`).
+ *
+ * `gpt` also matches the OpenAI `o`-series reasoning ids (`o1`, `o3-mini`, …),
+ * which carry no `gpt` token but are the same OpenAI Chat-Completions family the
+ * `gpt` target serves.
+ */
+declare function classifyModelPrefix(model: string | undefined): ModelPrefixKind | null;
+/**
+ * Resolve the configured target ref for a requested model under prefix dispatch.
+ * Returns the `ModelRef` for the matched prefix, or `null` when the model has no
+ * known prefix OR the matched prefix has no configured target (both are
+ * "unroutable" — the caller surfaces a clear per-request error).
+ */
+declare function resolvePrefixTarget(targets: ModelPrefixTargets | undefined, model: string | undefined): {
+    kind: ModelPrefixKind;
+    ref: ModelRef;
+} | null;
+
+/**
+ * outboundConcurrencyGate — per-`apiKeyId` concurrency queue for the outbound
+ * API server (queue/concurrency, design D-CORE-2).
+ *
+ * An outbound key over its concurrency ceiling should WAIT its turn rather than
+ * get a hard 429. This primitive is a per-key counting semaphore (`limit` =
+ * the key's `maxConcurrency`) fronting a bounded FIFO wait queue: within limit
+ * → grant; over limit but under `max(limit*factor, minQueueSize)` → enqueue;
+ * beyond that → reject queue-full. Waiters resolve in strict FIFO order and a
+ * waiter can be CANCELLED (the wire layer binds this to `res.close` so a client
+ * that disconnects mid-queue frees its spot). Release + cancel are idempotent
+ * (guarded by a per-acquisition `settled` flag) so the wire's `finally` +
+ * `res.once('close')` double-fire is safe — this directly avoids the CRS #1130
+ * slot leak.
+ *
+ * Memory-only, injected clock, resets on restart. `limit <= 0` means unlimited
+ * (the wire layer bypasses the gate entirely for such keys; a defensive call
+ * here still grants immediately without bound).
+ *
+ * NOTE ON THE ACQUIRE SHAPE: the design task sketched `acquire → Promise<{
+ * release, cancel }>`, but the wire layer must be able to CANCEL a still-pending
+ * wait (bind `res.once('close', cancel)` BEFORE the grant resolves). A bare
+ * promise only hands back its value on grant, so `acquire` instead returns a
+ * synchronous {@link GateAcquisition} handle exposing both `cancel()` and a
+ * `granted` promise; the granted {@link GateSlot} also carries `release` AND
+ * `cancel` (the same idempotent fns) so the sketched shape is still satisfied
+ * post-grant. (Deviation recorded in the change return notes.)
+ *
+ * @module outbound-api/outboundConcurrencyGate
+ */
+/** A granted concurrency slot. `release` frees it; `cancel` is a post-grant no-op. */
+interface GateSlot {
+    release(): void;
+    cancel(): void;
+}
+/** The synchronous handle `acquire` returns (so a pending wait can be cancelled). */
+interface GateAcquisition {
+    /** Resolves with a {@link GateSlot} on grant; rejects on queue-full/timeout/cancel. */
+    granted: Promise<GateSlot>;
+    /** Cancel a still-pending wait (idempotent; no-op once granted). */
+    cancel(): void;
+}
+/** Options for one `acquire`. */
+interface GateAcquireOptions {
+    /** Per-key max queued = `max(limit*factor, minQueueSize)`. */
+    maxQueueSizeFactor: number;
+    /** Floor of the per-key max queued. */
+    minQueueSize: number;
+    /** Reject a queued waiter after this many ms (wire → 429). */
+    waitTimeoutMs: number;
+}
+/** A per-key snapshot entry (only keys with active slots or waiters). */
+interface GateStatusEntry {
+    apiKeyId: string;
+    active: number;
+    waiting: number;
+}
+/** Rejection thrown when a key's wait queue is full at acquire time. */
+declare class ConcurrencyQueueFullError extends Error {
+    readonly apiKeyId: string;
+    readonly maxQueueSize: number;
+    readonly code = "concurrency_queue_full";
+    constructor(apiKeyId: string, maxQueueSize: number);
+}
+/** Rejection thrown when a queued waiter exceeds `waitTimeoutMs`. */
+declare class ConcurrencyWaitTimeoutError extends Error {
+    readonly apiKeyId: string;
+    readonly waitTimeoutMs: number;
+    readonly code = "concurrency_wait_timeout";
+    constructor(apiKeyId: string, waitTimeoutMs: number);
+}
+/** Rejection thrown when a still-pending wait is cancelled (client disconnect). */
+declare class ConcurrencyWaitCancelledError extends Error {
+    readonly apiKeyId: string;
+    readonly code = "concurrency_wait_cancelled";
+    constructor(apiKeyId: string);
+}
+/** True for any rejection the gate produces on an acquire that never granted. */
+declare function isConcurrencyRejection(err: unknown): err is ConcurrencyQueueFullError | ConcurrencyWaitTimeoutError | ConcurrencyWaitCancelledError;
+/**
+ * Per-`apiKeyId` counting semaphore + bounded FIFO wait queue.
+ */
+declare class OutboundConcurrencyGate {
+    private readonly states;
+    private ensure;
+    /** Delete a key's state once it is fully idle (no active, no waiters). */
+    private gc;
+    /**
+     * Acquire a concurrency slot for `apiKeyId` under `limit`. Grants immediately
+     * when `active < limit`; else enqueues FIFO while under the per-key queue cap;
+     * else rejects queue-full. `limit <= 0` = unlimited (always granted).
+     */
+    acquire(apiKeyId: string, limit: number, options: GateAcquireOptions): GateAcquisition;
+    /** Build an idempotent granted slot (`release` decrements; `cancel` is a no-op). */
+    private makeSlot;
+    /** After a release freed a slot, grant the FIFO head if it fits under its cap. */
+    private dispatchNext;
+    /** Snapshot for observability — only keys with active slots or waiters. */
+    getStatus(): GateStatusEntry[];
+    /** Drop all state + pending timers (tests / teardown). */
+    reset(): void;
+}
+
+/**
+ * userMessageDetection — decide whether a parsed outbound request body is a
+ * REAL user-message turn (serialize it) vs a tool-loop continuation (bypass the
+ * serial queue) (queue/concurrency, design D-CORE-4).
+ *
+ * The serial queue protects a shared upstream account from looking like many
+ * concurrent humans. Only human-INITIATED turns should be serialized; a
+ * tool-loop turn (the client feeding a tool result back) must NOT be throttled
+ * or it stalls the agent. This module classifies the LAST turn per ingress
+ * format, aligned to claude-relay-service's `isUserMessageRequest` semantics but
+ * covering all four omnicross ingress formats.
+ *
+ * SAFETY BIAS: default `false` (bypass) on any shape it cannot POSITIVELY
+ * classify as a human turn. Under-serializing only costs the (opt-in, default-
+ * off) protection; over-serializing would stall real tool-loops.
+ *
+ * @module outbound-api/userMessageDetection
+ */
+
+/**
+ * Decide whether `parsedBody` for `endpoint` is a real user-message turn (→
+ * serialize) vs a tool-loop / non-user turn (→ bypass). Defaults `false` on any
+ * unclassifiable shape.
+ */
+declare function isUserMessageRequest(endpoint: OutboundEndpoint, parsedBody: unknown): boolean;
+
+/**
+ * userMessageSerialQueue — per-`providerId` user-message serial queue for the
+ * outbound API server (queue/concurrency, design D-CORE-1).
+ *
+ * A shared subscription account hit by concurrent user messages looks unlike a
+ * single human and trips upstream risk-control. This primitive serializes the
+ * REAL user-message turns for one upstream account (`providerId`): exactly one
+ * in-flight at a time, plus a `delayMs` minimum gap between one account's
+ * requests. Waiters resolve in strict FIFO order (correcting claude-relay-
+ * service's non-fair Redis polling); no jitter, no busy-poll — the residual
+ * `delayMs` gap is honored by a scheduled dispatch.
+ *
+ * Memory-only, resets on app restart (acceptable — the queue is a live
+ * throttle, not persisted state). The caller RELEASES on response start (not
+ * completion) so the next account request can begin while the prior response
+ * streams; the release timestamp seeds the `delayMs` gap for the next waiter.
+ * The wire layer (`omnicross-uqc-wire`) owns the `res` lifecycle; this module
+ * never touches HTTP.
+ *
+ * @module outbound-api/userMessageSerialQueue
+ */
+/** A held serial slot; `release()` frees it (idempotent). */
+interface SerialSlot {
+    release(): void;
+}
+/** Options for one `acquire`. */
+interface SerialAcquireOptions {
+    /** Reject the waiter after this many ms (wire → 503). */
+    waitTimeoutMs: number;
+    /** Minimum gap (ms) since this key's last release before the next grant. */
+    delayMs: number;
+    /** Clock reference for the immediate-grant decision (default `Date.now()`). */
+    now?: number;
+}
+/** A per-key snapshot entry (only keys with a held slot or non-empty queue). */
+interface SerialQueueStatusEntry {
+    providerId: string;
+    holding: boolean;
+    waiting: number;
+}
+/** Rejection thrown when a serial waiter exceeds `waitTimeoutMs`. */
+declare class SerialQueueTimeoutError extends Error {
+    readonly providerId: string;
+    readonly waitTimeoutMs: number;
+    readonly code = "serial_queue_timeout";
+    constructor(providerId: string, waitTimeoutMs: number);
+}
+/** True for a rejection produced by the serial queue wait-timeout. */
+declare function isSerialQueueTimeout(err: unknown): err is SerialQueueTimeoutError;
+/**
+ * Per-`providerId` single-slot mutex + `delayMs` spacing gate with a FIFO wait
+ * queue. `acquire` resolves when the key is free AND at least `delayMs` has
+ * elapsed since that key's last release.
+ */
+declare class UserMessageSerialQueue {
+    private readonly states;
+    private ensure;
+    /**
+     * Acquire the serial slot for `providerId`. Resolves immediately when the slot
+     * is free, no one is queued, and the `delayMs` gap since the last release has
+     * elapsed; otherwise enqueues FIFO and resolves in order (or rejects with a
+     * {@link SerialQueueTimeoutError} after `waitTimeoutMs`).
+     */
+    acquire(providerId: string, options: SerialAcquireOptions): Promise<SerialSlot>;
+    /** Build an idempotent release for a granted slot. */
+    private makeSlot;
+    /**
+     * Grant the head waiter when the slot is free and the head's `delayMs` gap has
+     * elapsed; otherwise schedule a dispatch for the residual gap. No-op while the
+     * slot is held (release re-invokes this) or the queue is empty.
+     */
+    private maybeDispatch;
+    /** Hand the slot to the FIFO head (if free and someone is waiting). */
+    private grantHead;
+    /** Snapshot for observability — only keys holding a slot or with waiters. */
+    getStatus(): SerialQueueStatusEntry[];
+    /** Drop all state + pending timers (tests / teardown). */
+    reset(): void;
+}
+
 /**
  * outboundApiKeyAuth — named-key generation, hashing, and verification for the
  * outbound API server (`outbound-api-server`).
@@ -131,6 +635,13 @@ declare function mergeServerConfig(current: OutboundApiServerConfig, patch: Part
  * @module outbound-api/outboundApiKeyAuth
  */
 
+/**
+ * Produce `count` UNBIASED base62 chars (t2). Uses rejection sampling — bytes in
+ * `[248, 256)` are discarded so the remaining `[0, 248)` map uniformly onto the
+ * 62 alphabet (each char equally likely), eliminating the `byte % 62` modulo
+ * bias. Draws fresh random bytes in batches until enough chars are accepted.
+ */
+declare function randomBase62(count: number): string;
 /** Hash a presented/generated secret (sha256 hex). */
 declare function hashKey(secret: string): string;
 /**
@@ -138,18 +649,90 @@ declare function hashKey(secret: string): string;
  * prefix are stored.
  */
 declare function createNamedKey(db: OutboundKeyDb, name: string): Promise<OutboundApiKeyCreated>;
-/** The id of a verified key (for rate-limiting + last-used bookkeeping). */
+/**
+ * A verified key + the enforcement inputs carried from the row so the wire layer
+ * runs its policy checks WITHOUT a second DB read (mirrors `maxConcurrency`).
+ */
 interface VerifiedKey {
     id: string;
+    /**
+     * The key's per-key concurrency ceiling, carried from the row so the wire
+     * layer keys the concurrency gate without a second DB read. Absent/`0` =
+     * unlimited (gate bypassed).
+     */
+    maxConcurrency?: number;
+    /**
+     * Per-key USD cost limits (outbound-key-policy). Absent when the key has no
+     * cost cap → the wire layer skips the cost-quota check entirely.
+     */
+    costLimits?: KeyCostLimits;
+    /**
+     * Per-key rate-limit override (outbound-key-policy). Absent when the key has no
+     * rate config → the limiter uses its default 60/60s window (byte-identical).
+     */
+    rateLimit?: {
+        maxRequests?: number;
+        windowMs?: number;
+    };
+    /**
+     * Per-key model restriction (outbound-key-policy #6). Populated ONLY when the
+     * row has `enableModelRestriction === true` → the wire layer's presence check
+     * is the zero-regression gate. Absent ⇒ NO model check runs for this key.
+     */
+    modelRestriction?: ModelRestriction;
 }
+/** The reason-bearing verify outcome (design D2). */
+type KeyVerification = {
+    status: 'ok';
+    key: VerifiedKey;
+} | {
+    status: 'invalid';
+} | {
+    status: 'expired';
+};
 /**
- * Verify a presented key against the DB. Matches by hash where the stored row
- * is enabled AND not revoked (the DB query enforces this). On success bumps
- * `lastUsedAt` (best-effort, fire-and-forget) and returns the key id; returns
- * `null` on any miss / disabled / revoked key.
+ * Verify a presented key against the DB, returning a REASON (design D2) so the
+ * wire layer can emit the right status + a clear body. Matches by hash where the
+ * stored row is enabled AND not revoked. On a valid, non-expired key: bumps
+ * `lastUsedAt` (best-effort) and, for an activation-mode key on its FIRST use,
+ * stamps `activatedAt` once (best-effort). A policy-less enabled key resolves to
+ * `{ status:'ok', key:{ id } }` — byte-identical to the pre-policy result.
+ */
+declare function verifyKey(db: OutboundKeyDb, presentedKey: string | undefined, now?: number): Promise<KeyVerification>;
+/**
+ * Thin id-or-null wrapper over {@link verifyKey} for callers not ready for the
+ * reason-bearing form: returns the `VerifiedKey` on success, `null` on any
+ * invalid/expired key (the exact pre-policy contract).
  */
 declare function verifyPresentedKey(db: OutboundKeyDb, presentedKey: string | undefined): Promise<VerifiedKey | null>;
 
+/**
+ * keyedMutex — a tiny per-key async mutex (voucher-redemption #9, MJ1 fix).
+ *
+ * Serializes async critical sections that share a key so they run
+ * one-after-another (each observing the previous one's committed effects),
+ * mirroring the subscription `RefreshMutex` "one in-flight op per key" pattern.
+ * Different keys never block each other.
+ *
+ * Used by the voucher redeem path to serialize a key's redemptions: two redeems
+ * for the SAME key run sequentially, so each reads the other's applied result and
+ * a RELATIVE grant increment accumulates instead of clobbering a shared snapshot.
+ *
+ * @module outbound-api/keyedMutex
+ */
+/** A per-key FIFO async mutex. In-memory; process-local. */
+declare class KeyedMutex {
+    /** key → the tail of the pending-op chain (resolves when the last op frees). */
+    private readonly tails;
+    /**
+     * Run `fn` exclusively for `key`: it starts only after every previously
+     * enqueued op for the SAME key has settled, and the next waiter starts only
+     * after `fn` settles. Returns `fn`'s result (or rejection). Never lets one op's
+     * failure wedge the queue (waiters proceed regardless).
+     */
+    runExclusive<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+
 /**
  * outboundRateLimiter — per-API-key in-memory sliding-window rate limiter for
  * the outbound API server (`outbound-api-server`, design D6).
@@ -184,29 +767,77 @@ declare class OutboundRateLimiter {
      * Record a request for `apiKeyId` and decide whether it is allowed. Prunes
      * timestamps older than the window first; when allowed, the request's
      * timestamp is appended.
+     *
+     * `override` (outbound-key-policy) supplies a PER-KEY window/max for this
+     * bucket, superseding the instance defaults for THAT key. Absent ⇒ the
+     * instance default 60/60s (byte-identical to before this change). An effective
+     * `maxRequests` of `0` means UNLIMITED — the request is allowed and NOT
+     * recorded (no bucket growth).
      */
-    check(apiKeyId: string, now?: number): RateLimitDecision;
+    check(apiKeyId: string, now?: number, override?: RateLimiterOptions): RateLimitDecision;
     /** Drop all recorded state (tests / teardown). */
     reset(): void;
 }
 
 /**
- * roleDetection — classify an outbound request's ROLE (vision / background /
- * default) so the route resolver can pick the endpoint's model for that role
+ * voucherRedeem — the key-authenticated `POST <base>/redeem` handler
+ * (voucher-redemption #9, design D1/D4/D5/D6; MJ1/M2/MJ2/M3 fix).
+ *
+ * A key presents its own outbound secret (already verified by the caller) plus a
+ * card `{ code }`; the card's value applies to THAT key. The critical section is
+ * SERIALIZED PER KEY (an async `KeyedMutex`) so two redemptions for the same key
+ * run one-after-another — the fix for concurrent value loss (MJ1). Each redeem:
+ *   1. RECONCILE any stranded (`redeemed && grantApplied !== true`) card for this
+ *      key FIRST — re-applying its recorded ABSOLUTE target and marking it — so a
+ *      prior card's grant settles BEFORE this redeem computes anything (M2: the
+ *      recorded absolute is therefore never stale).
+ *   2. hash the code → look up → require `unredeemed`.
+ *   3. compute the grant from the CURRENT policy read inside the mutex — this is
+ *      the intended final ABSOLUTE key value (`min(current + credit, cap)` /
+ *      `min(current + days, now + capDays)`). Because the mutex serialized step 1,
+ *      "current" already includes every earlier card, so concurrent DIFFERENT
+ *      cards accumulate correctly.
+ *   4. ATOMIC CAS flip `unredeemed → redeemed` recording that absolute +
+ *      `grantApplied = false` — the single-use guard.
+ *   5. apply `setPolicy(key, <recorded absolute>)`; on success set
+ *      `grantApplied = true`.
+ *
+ * Crash-safety WITHOUT double-credit (MJ2): the apply target is the recorded
+ * ABSOLUTE, applied idempotently on BOTH the first pass AND the reconcile — so a
+ * crash between the `setPolicy` and the `grantApplied` mark just re-applies the
+ * SAME absolute (a no-op), never a second credit. If the apply FAILS on the first
+ * pass (key revoked mid-redeem, M3) the flip is REVERTED and the holder gets an
+ * error. Redeem attempts are rate-limited (D6). The response reveals ONLY this
+ * key's own balance.
+ *
+ * @module outbound-api/voucherRedeem
+ */
+
+/** True for `POST <base>/redeem` (or `/v1/redeem`) — the redeem endpoint. */
+declare function isRedeemRequest(method: string | undefined, url: string | undefined): boolean;
+/**
+ * Handle a redeem request. `deps` carries the voucher store + the key DB; the key
+ * is ALREADY verified by the router (`verifiedKeyId` / `presentedKey`). Gated on
+ * `voucherEnabled` (disabled ⇒ inert). `redeemLimiter` throttles attempts (D6);
+ * `redeemMutex` serializes a key's redemptions (MJ1 fix).
+ */
+declare function handleVoucherRedeem(req: http.IncomingMessage, res: http.ServerResponse, deps: OutboundApiDeps, voucherEnabled: boolean, redeemLimiter: OutboundRateLimiter, verifiedKeyId: string, presentedKey: string, now: number, redeemMutex?: KeyedMutex): Promise<void>;
+
+/**
+ * roleDetection — classify an outbound request's ROLE (background / default) so
+ * the route resolver can pick the endpoint's model for that role
  * (`outbound-api-server`, design D2).
  *
- * Precedence: vision > background > default.
- *  - vision      — the body carries image/vision content parts (per-format
- *                  detection). The route resolver applies the vision→default
- *                  fallback when the endpoint has no vision model.
+ * Applies to the role-based endpoints (`chat`/`gemini`) only; the kind-mapped
+ * endpoints (`messages`/`responses`) classify by model KIND in `kindDetection`.
+ *
+ * Precedence: background > default.
  *  - background  — the requested model id is in the endpoint's optional
  *                  background-model-id override list (human decision after the
  *                  proposal), OR the registry small/haiku-class name signal
  *                  matches (Claude Code's haiku probe sends exactly this).
  *  - default     — everything else.
  *
- * Each ingress's body shape is handled here in ONE place.
- *
  * @module outbound-api/roleDetection
  */
 
@@ -214,8 +845,7 @@ declare class OutboundRateLimiter {
  * Detect the request's role. `backgroundModelIds` is the endpoint's optional
  * override list: when an incoming requested model id matches an entry there, the
  * request is BACKGROUND regardless of the name signal; otherwise the registry
- * small/haiku-class name signal is the baseline. Precedence vision > background
- * > default.
+ * small/haiku-class name signal is the baseline. Precedence background > default.
  */
 declare function detectRequestRole(ingressFormat: IngressFormat, body: Record<string, unknown>, options?: {
     backgroundModelIds?: string[];
@@ -245,4 +875,4 @@ declare function getOutboundApiServer(deps?: OutboundApiDeps, onPortChange?: (po
 /** Reset the singleton (tests / teardown only). */
 declare function __resetOutboundApiServerForTests(): void;
 
-export { type ApiServerSettingsStore, type ApplyConfigInput, DEFAULT_OUTBOUND_PORT, EndpointRoutingConfig, OUTBOUND_API_SERVER_CONFIG_KEY, OutboundApiDeps, OutboundApiKeyCreated, OutboundApiServer, OutboundApiServerConfig, OutboundApiServerStatus, OutboundFormatUrls, OutboundKeyDb, OutboundRateLimiter, RequestRole, __resetOutboundApiServerForTests, createNamedKey, defaultServerConfig, detectRequestRole, endpointToIngressFormat, formatUrls, getOutboundApiServer, hashKey, loadServerConfig, mergeServerConfig, normalizeServerConfig, saveServerConfig, verifyPresentedKey };
+export { AccountProbeConfig, type ApiServerSettingsStore, type ApplyConfigInput, ConcurrencyQueueConfig, ConcurrencyQueueFullError, ConcurrencyWaitCancelledError, ConcurrencyWaitTimeoutError, DEFAULT_ACCOUNT_PROBE, DEFAULT_CONCURRENCY_QUEUE, DEFAULT_FINGERPRINT, DEFAULT_OUTBOUND_PORT, DEFAULT_USER_MESSAGE_QUEUE, type EndpointModelConfigError, EndpointRoutingConfig, FingerprintConfig, type GateAcquireOptions, type GateAcquisition, type GateSlot, type GateStatusEntry, KeyCostLimits, type KeyVerification, KeyedMutex, KindMappedEndpoint, ModelKind, type ModelPrefixKind, ModelPrefixTargets, OUTBOUND_API_SERVER_CONFIG_KEY, OutboundApiConfigError, OutboundApiDeps, OutboundApiKeyCreated, OutboundApiServer, OutboundApiServerConfig, OutboundApiServerStatus, OutboundConcurrencyGate, OutboundEndpoint, OutboundFormatUrls, OutboundKeyDb, OutboundProxyConfig, OutboundRateLimiter, RequestRole, type SerialAcquireOptions, type SerialQueueStatusEntry, SerialQueueTimeoutError, type SerialSlot, UserMessageQueueConfig, UserMessageSerialQueue, type VerifiedKey, __resetOutboundApiServerForTests, classifyModelPrefix, createNamedKey, defaultServerConfig, detectModelKind, detectRequestRole, endpointToIngressFormat, formatUrls, getOutboundApiServer, handleVoucherRedeem, hashKey, isConcurrencyRejection, isKindMappedEndpoint, isRedeemRequest, isSerialQueueTimeout, isUserMessageRequest, loadServerConfig, mergeServerConfig, modelKindsForEndpoint, normalizeAccountProbe, normalizeAudit, normalizeBilling, normalizeFingerprint, normalizePrefixTargets, normalizeProxyConfig, normalizeProxySegment, normalizeQueueSegments, normalizeServerConfig, normalizeVoucher, normalizeWebhookDestination, normalizeWebhookSegment, randomBase62, resolvePrefixTarget, saveServerConfig, validateEndpointModelConfig, validateServerModelConfig, verifyKey, verifyPresentedKey };