@omnicross/core 0.1.3 → 0.1.5

package/dist/keyPolicy-Cp0FntZl.d.ts

@@ -0,0 +1,90 @@
+/**
+ * keyPolicy — PURE decision helpers for the outbound key-policy envelope
+ * (`outbound-key-policy`, design D2/D4). Expiry/activation resolution +
+ * cost-quota decision. No I/O, no clock ownership (the caller passes `now`), so
+ * these are trivially unit-testable and reused by both the auth path
+ * (`verifyKey`) and the wire path (`outboundApiRouter`).
+ *
+ * The #6 (`restrictedModels`) and #9 (voucher) children EXTEND the key-policy
+ * schema; they must not change the shapes frozen here.
+ *
+ * @module outbound-api/keyPolicy
+ */
+/** The expiry/activation subset of a key row `computeKeyExpiry` reads. */
+interface KeyExpiryInput {
+    /** Fixed-mode absolute expiry (epoch ms). */
+    expiresAt?: number | null;
+    /** Expiry mode; absent ⇒ `'fixed'`. */
+    activationMode?: 'fixed' | 'activation';
+    /** Activation-mode lifetime in days (absent/null ⇒ never expires). */
+    activationDays?: number | null;
+    /** First-use activation stamp (epoch ms); null ⇒ not yet activated. */
+    activatedAt?: number | null;
+}
+/** Result of {@link computeKeyExpiry}. */
+interface KeyExpiryResult {
+    expired: boolean;
+    /** The resolved absolute expiry (epoch ms), when the key has one. */
+    effectiveExpiresAt?: number;
+    /**
+     * True when this is an activation-mode key that has NOT been activated yet, so
+     * the caller SHOULD stamp the activation (best-effort) on a successful verify.
+     */
+    needsActivation?: boolean;
+}
+/**
+ * Resolve whether a key is past its effective expiry (design D2).
+ *  - `fixed`: expired when `expiresAt != null && now >= expiresAt`.
+ *  - `activation`: while `activatedAt == null` the key is NOT expired (it
+ *    activates on THIS use → `needsActivation`); once activated, expired when
+ *    `now >= activatedAt + activationDays*DAY`. A null `activationDays` never
+ *    expires.
+ * A key with no expiry configured never expires.
+ */
+declare function computeKeyExpiry(row: KeyExpiryInput, now: number): KeyExpiryResult;
+/** Per-key USD cost limits carried on the verified key (absent scope ⇒ no cap). */
+interface KeyCostLimits {
+    dailyUsd?: number;
+    totalUsd?: number;
+    weeklyUsd?: number;
+}
+/** In-memory per-key accumulated spend snapshot (see `keySpendTracker`). */
+interface KeySpend {
+    dailyUsd: number;
+    /** Local-midnight boundary the `dailyUsd` window opened at (epoch ms). */
+    dailyWindowStart: number;
+    weeklyUsd: number;
+    /** Local week-start boundary the `weeklyUsd` window opened at (epoch ms). */
+    weeklyWindowStart: number;
+    totalUsd: number;
+}
+/** Decision returned by {@link checkKeyQuota}. */
+type QuotaDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    scope: 'daily' | 'weekly' | 'total';
+    limitUsd: number;
+    spentUsd: number;
+};
+/**
+ * Decide whether the key's accumulated spend already meets/exceeds any
+ * configured cost limit (design D4). `allowed:false` when a scope's PRIOR spend
+ * is `>= limit` (the triggering request's own cost is unknown pre-flight →
+ * bounded one-request overage, CRS-equivalent). An unconfigured scope is never
+ * gated; a `limits`-less key always passes.
+ */
+declare function checkKeyQuota(limits: KeyCostLimits | undefined, spend: KeySpend): QuotaDecision;
+/**
+ * Per-key model restriction carried on the verified key (outbound-key-policy #6).
+ * Present ONLY when the key has `enableModelRestriction === true` — so the wire
+ * layer's presence check (`if (key.modelRestriction) …`) is the zero-regression
+ * gate.
+ */
+interface ModelRestriction {
+    mode: 'blacklist' | 'allowlist';
+    /** Bare modelIds the mode acts on. Empty allowlist denies every model. */
+    models: string[];
+}
+
+export { type KeyCostLimits as K, type ModelRestriction as M, type QuotaDecision as Q, type KeyExpiryInput as a, type KeyExpiryResult as b, type KeySpend as c, checkKeyQuota as d, computeKeyExpiry as e };

package/dist/outbound-api/auditCapture.cjs

@@ -0,0 +1,9 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkUNWKG6EIcjs = require('../chunk-UNWKG6EI.cjs');
+require('../chunk-FCR77GYM.cjs');
+require('../chunk-AEOZIDEB.cjs');
+require('../chunk-XSVNC2UD.cjs');
+
+
+exports.beginAuditCapture = _chunkUNWKG6EIcjs.beginAuditCapture;

package/dist/outbound-api/auditCapture.d.cts

@@ -0,0 +1,54 @@
+import http from 'node:http';
+
+/**
+ * auditCapture — the outbound server's post-response audit capture hook
+ * (request-audit-log, design D1/D3/D5).
+ *
+ * {@link beginAuditCapture} is called at the TOP of `handleOutboundRequest`. It
+ * reads the active capture config from the core slot; when audit is DISABLED it
+ * returns `null` immediately (one slot read — no assembly, no listener, zero
+ * regression). When enabled it:
+ *  - registers a one-shot `res.on('close')` listener that, at response end,
+ *    assembles the {@link AuditRecord} from the http `req` (IP via the socket, or
+ *    a trusted `X-Forwarded-For` only when configured — LEAD OQ1 anti-spoof; UA;
+ *    method; path with the query string DROPPED), the response `statusCode`, the
+ *    elapsed ms, and the fields the handler fills in (keyId / model / provider /
+ *    error / bodies) — then hands it to the fire-and-forget `recordAudit`;
+ *  - when `captureBodies` is ALSO on, wraps `res.write`/`res.end` to accumulate
+ *    the response body. Bodies are captured IN FULL (no truncation) and a
+ *    streaming `text/event-stream` response is captured too — the earlier
+ *    metadata-only/bounded behavior made a codex (streaming) reply invisible,
+ *    which defeated debugging. See `upstreamTrace.ts` for the upstream leg.
+ *
+ * Request HEADERS are NEVER read into a record (Authorization / x-api-key live
+ * there). Every stored body passes through {@link redactAuditText}. The assembly
+ * is wrapped so a capture failure can never surface into the relay path.
+ *
+ * @module @omnicross/core/outbound-api/auditCapture
+ */
+
+/**
+ * The mutable context the request handler enriches as it progresses. `null` is
+ * returned by {@link beginAuditCapture} when audit is disabled — the handler
+ * guards every write with `if (audit)`.
+ */
+interface AuditCaptureContext {
+    /** Outbound key id (set after auth). NEVER the key material. */
+    keyId?: string | null;
+    /** Resolved upstream model (set after route resolution). */
+    model?: string;
+    /** Upstream provider id (set after route resolution). */
+    provider?: string;
+    /** Sanitized error message (set on a relay/dispatch failure). */
+    error?: string;
+    /** Stash the raw request body for capture (a no-op unless `captureBodies`). */
+    setRequestBody(raw: string): void;
+}
+/**
+ * Begin audit capture for one request. Returns a mutable context the handler
+ * enriches, or `null` when audit is disabled (zero-cost path). The record is
+ * emitted on response `close` via the fire-and-forget sink.
+ */
+declare function beginAuditCapture(req: http.IncomingMessage, res: http.ServerResponse, now: number): AuditCaptureContext | null;
+
+export { type AuditCaptureContext, beginAuditCapture };

package/dist/outbound-api/auditCapture.d.ts

@@ -0,0 +1,54 @@
+import http from 'node:http';
+
+/**
+ * auditCapture — the outbound server's post-response audit capture hook
+ * (request-audit-log, design D1/D3/D5).
+ *
+ * {@link beginAuditCapture} is called at the TOP of `handleOutboundRequest`. It
+ * reads the active capture config from the core slot; when audit is DISABLED it
+ * returns `null` immediately (one slot read — no assembly, no listener, zero
+ * regression). When enabled it:
+ *  - registers a one-shot `res.on('close')` listener that, at response end,
+ *    assembles the {@link AuditRecord} from the http `req` (IP via the socket, or
+ *    a trusted `X-Forwarded-For` only when configured — LEAD OQ1 anti-spoof; UA;
+ *    method; path with the query string DROPPED), the response `statusCode`, the
+ *    elapsed ms, and the fields the handler fills in (keyId / model / provider /
+ *    error / bodies) — then hands it to the fire-and-forget `recordAudit`;
+ *  - when `captureBodies` is ALSO on, wraps `res.write`/`res.end` to accumulate
+ *    the response body. Bodies are captured IN FULL (no truncation) and a
+ *    streaming `text/event-stream` response is captured too — the earlier
+ *    metadata-only/bounded behavior made a codex (streaming) reply invisible,
+ *    which defeated debugging. See `upstreamTrace.ts` for the upstream leg.
+ *
+ * Request HEADERS are NEVER read into a record (Authorization / x-api-key live
+ * there). Every stored body passes through {@link redactAuditText}. The assembly
+ * is wrapped so a capture failure can never surface into the relay path.
+ *
+ * @module @omnicross/core/outbound-api/auditCapture
+ */
+
+/**
+ * The mutable context the request handler enriches as it progresses. `null` is
+ * returned by {@link beginAuditCapture} when audit is disabled — the handler
+ * guards every write with `if (audit)`.
+ */
+interface AuditCaptureContext {
+    /** Outbound key id (set after auth). NEVER the key material. */
+    keyId?: string | null;
+    /** Resolved upstream model (set after route resolution). */
+    model?: string;
+    /** Upstream provider id (set after route resolution). */
+    provider?: string;
+    /** Sanitized error message (set on a relay/dispatch failure). */
+    error?: string;
+    /** Stash the raw request body for capture (a no-op unless `captureBodies`). */
+    setRequestBody(raw: string): void;
+}
+/**
+ * Begin audit capture for one request. Returns a mutable context the handler
+ * enriches, or `null` when audit is disabled (zero-cost path). The record is
+ * emitted on response `close` via the fire-and-forget sink.
+ */
+declare function beginAuditCapture(req: http.IncomingMessage, res: http.ServerResponse, now: number): AuditCaptureContext | null;
+
+export { type AuditCaptureContext, beginAuditCapture };

package/dist/outbound-api/auditCapture.js

@@ -0,0 +1,9 @@
+import {
+  beginAuditCapture
+} from "../chunk-IFXJ2BG7.js";
+import "../chunk-K5NM7VAH.js";
+import "../chunk-WNY4WMRF.js";
+import "../chunk-OZFM4X3S.js";
+export {
+  beginAuditCapture
+};

package/dist/outbound-api/auditRedact.cjs

@@ -0,0 +1,8 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+var _chunkFCR77GYMcjs = require('../chunk-FCR77GYM.cjs');
+
+
+
+exports.AUDIT_REDACTED = _chunkFCR77GYMcjs.AUDIT_REDACTED; exports.redactAuditText = _chunkFCR77GYMcjs.redactAuditText;

package/dist/outbound-api/auditRedact.d.cts

@@ -0,0 +1,30 @@
+/**
+ * auditRedact — the pure secret-redaction pass for captured audit bodies
+ * (request-audit-log, design D3/D7).
+ *
+ * Body capture is opt-in and inherently sensitive: a prompt or tool argument can
+ * embed a secret. {@link redactAuditText} is run over EVERY captured body (and
+ * any other free text stored in a record) BEFORE it is persisted — defense in
+ * depth on top of "request headers are NEVER captured" (so an Authorization /
+ * x-api-key HEADER value never enters a record in the first place).
+ *
+ * It masks the obvious, high-confidence secret shapes ONLY (frozen list) — never
+ * a broad heuristic that would gut a legitimate prompt:
+ *  - `sk-…` API keys (covers `sk-ant-…`, `sk-omnicross-…`, `sk-proj-…`, OpenAI).
+ *  - `Bearer <token>` authorization values.
+ *  - `x-api-key` / `api-key` / `authorization` values written inline as text.
+ *  - Google `AIza…` API keys.
+ *
+ * Pure + allocation-light + never throws.
+ *
+ * @module @omnicross/core/outbound-api/auditRedact
+ */
+/** The sentinel a masked secret is replaced with. */
+declare const AUDIT_REDACTED = "***REDACTED***";
+/**
+ * Mask obvious secrets in `text`. Pure; returns the input unchanged when it holds
+ * no recognized secret shape. Never throws (a bad input returns `''`).
+ */
+declare function redactAuditText(text: string): string;
+
+export { AUDIT_REDACTED, redactAuditText };

package/dist/outbound-api/auditRedact.d.ts

@@ -0,0 +1,30 @@
+/**
+ * auditRedact — the pure secret-redaction pass for captured audit bodies
+ * (request-audit-log, design D3/D7).
+ *
+ * Body capture is opt-in and inherently sensitive: a prompt or tool argument can
+ * embed a secret. {@link redactAuditText} is run over EVERY captured body (and
+ * any other free text stored in a record) BEFORE it is persisted — defense in
+ * depth on top of "request headers are NEVER captured" (so an Authorization /
+ * x-api-key HEADER value never enters a record in the first place).
+ *
+ * It masks the obvious, high-confidence secret shapes ONLY (frozen list) — never
+ * a broad heuristic that would gut a legitimate prompt:
+ *  - `sk-…` API keys (covers `sk-ant-…`, `sk-omnicross-…`, `sk-proj-…`, OpenAI).
+ *  - `Bearer <token>` authorization values.
+ *  - `x-api-key` / `api-key` / `authorization` values written inline as text.
+ *  - Google `AIza…` API keys.
+ *
+ * Pure + allocation-light + never throws.
+ *
+ * @module @omnicross/core/outbound-api/auditRedact
+ */
+/** The sentinel a masked secret is replaced with. */
+declare const AUDIT_REDACTED = "***REDACTED***";
+/**
+ * Mask obvious secrets in `text`. Pure; returns the input unchanged when it holds
+ * no recognized secret shape. Never throws (a bad input returns `''`).
+ */
+declare function redactAuditText(text: string): string;
+
+export { AUDIT_REDACTED, redactAuditText };

package/dist/outbound-api/auditRedact.js

@@ -0,0 +1,8 @@
+import {
+  AUDIT_REDACTED,
+  redactAuditText
+} from "../chunk-K5NM7VAH.js";
+export {
+  AUDIT_REDACTED,
+  redactAuditText
+};

package/dist/outbound-api/billingCapture.cjs

@@ -0,0 +1,8 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkAPYG5QD7cjs = require('../chunk-APYG5QD7.cjs');
+require('../chunk-L74VDN4A.cjs');
+require('../chunk-XSVNC2UD.cjs');
+
+
+exports.beginBillingCapture = _chunkAPYG5QD7cjs.beginBillingCapture;

package/dist/outbound-api/billingCapture.d.cts

@@ -0,0 +1,61 @@
+import http from 'node:http';
+
+/**
+ * billingCapture — the outbound server's post-response billing capture hook
+ * (billing-event-stream, design D1/D4).
+ *
+ * {@link beginBillingCapture} is called at the TOP of `handleOutboundRequest`. It
+ * reads the active billing config from the core slot; when billing is DISABLED it
+ * returns `null` immediately (one slot read — no assembly, no listener, zero
+ * regression). When enabled it registers a one-shot `res.close` listener that
+ * assembles a {@link BillingEvent} from the handler-filled context (keyId / model
+ * / provider / authMode), the response `statusCode`, and this request's METERED
+ * FACTS (token counts + the ALREADY-COMPUTED cost) — then hands it to the
+ * no-throw {@link publishBillingEvent}.
+ *
+ * COST REUSE (design D3 — no double pricing): the metered facts are read from the
+ * per-request usage stash the usage tap populates ({@link readAuditUsage} — the
+ * SAME stash `usage-events.jsonl` correlation uses, populated UNCONDITIONALLY by
+ * the taps, independent of whether request-audit is enabled). Token counts are
+ * stashed SYNCHRONOUSLY at `record()`; the cost lands on the recorder's deferred
+ * pricing tick (scheduled BEFORE the response closes). So the assembly is deferred
+ * one macrotask past `close` — by then the earlier-scheduled pricing tick has run
+ * and stashed the computed cost we REUSE (we never re-price).
+ *
+ * BILLABLE-ONLY: an event is emitted ONLY when the request produced usage (an
+ * upstream call was billed). Auth failures / rate-limit / model-restriction
+ * rejections return before dispatch, stash no usage, and emit NO billing event.
+ *
+ * @module @omnicross/core/outbound-api/billingCapture
+ */
+
+/**
+ * The mutable context the request handler enriches as it progresses. `null` is
+ * returned by {@link beginBillingCapture} when billing is disabled — the handler
+ * guards every write with `if (billing)`.
+ */
+interface BillingCaptureContext {
+    /** Outbound key id (set after auth). NEVER the key material. */
+    keyId?: string | null;
+    /** Resolved upstream model (set after route resolution). */
+    model?: string;
+    /** Upstream provider id (set after route resolution). */
+    provider?: string;
+    /** Re-auth mode the request billed under (set after route resolution). */
+    authMode?: 'byo' | 'subscription';
+}
+/**
+ * Deferral used to schedule the event assembly one macrotask past `close`, so the
+ * usage tap's earlier-scheduled pricing tick has stashed the cost we reuse.
+ * Injectable ONLY for deterministic tests; production uses a zero-delay timer.
+ */
+type BillingDefer = (fn: () => void) => void;
+/**
+ * Begin billing capture for one request. Returns a mutable context the handler
+ * enriches, or `null` when billing is disabled (zero-cost path). The event is
+ * emitted on response `close` via the no-throw sink — but ONLY when the request
+ * produced usage (a billable request).
+ */
+declare function beginBillingCapture(_req: http.IncomingMessage, res: http.ServerResponse, now: number, defer?: BillingDefer): BillingCaptureContext | null;
+
+export { type BillingCaptureContext, type BillingDefer, beginBillingCapture };

package/dist/outbound-api/billingCapture.d.ts

@@ -0,0 +1,61 @@
+import http from 'node:http';
+
+/**
+ * billingCapture — the outbound server's post-response billing capture hook
+ * (billing-event-stream, design D1/D4).
+ *
+ * {@link beginBillingCapture} is called at the TOP of `handleOutboundRequest`. It
+ * reads the active billing config from the core slot; when billing is DISABLED it
+ * returns `null` immediately (one slot read — no assembly, no listener, zero
+ * regression). When enabled it registers a one-shot `res.close` listener that
+ * assembles a {@link BillingEvent} from the handler-filled context (keyId / model
+ * / provider / authMode), the response `statusCode`, and this request's METERED
+ * FACTS (token counts + the ALREADY-COMPUTED cost) — then hands it to the
+ * no-throw {@link publishBillingEvent}.
+ *
+ * COST REUSE (design D3 — no double pricing): the metered facts are read from the
+ * per-request usage stash the usage tap populates ({@link readAuditUsage} — the
+ * SAME stash `usage-events.jsonl` correlation uses, populated UNCONDITIONALLY by
+ * the taps, independent of whether request-audit is enabled). Token counts are
+ * stashed SYNCHRONOUSLY at `record()`; the cost lands on the recorder's deferred
+ * pricing tick (scheduled BEFORE the response closes). So the assembly is deferred
+ * one macrotask past `close` — by then the earlier-scheduled pricing tick has run
+ * and stashed the computed cost we REUSE (we never re-price).
+ *
+ * BILLABLE-ONLY: an event is emitted ONLY when the request produced usage (an
+ * upstream call was billed). Auth failures / rate-limit / model-restriction
+ * rejections return before dispatch, stash no usage, and emit NO billing event.
+ *
+ * @module @omnicross/core/outbound-api/billingCapture
+ */
+
+/**
+ * The mutable context the request handler enriches as it progresses. `null` is
+ * returned by {@link beginBillingCapture} when billing is disabled — the handler
+ * guards every write with `if (billing)`.
+ */
+interface BillingCaptureContext {
+    /** Outbound key id (set after auth). NEVER the key material. */
+    keyId?: string | null;
+    /** Resolved upstream model (set after route resolution). */
+    model?: string;
+    /** Upstream provider id (set after route resolution). */
+    provider?: string;
+    /** Re-auth mode the request billed under (set after route resolution). */
+    authMode?: 'byo' | 'subscription';
+}
+/**
+ * Deferral used to schedule the event assembly one macrotask past `close`, so the
+ * usage tap's earlier-scheduled pricing tick has stashed the cost we reuse.
+ * Injectable ONLY for deterministic tests; production uses a zero-delay timer.
+ */
+type BillingDefer = (fn: () => void) => void;
+/**
+ * Begin billing capture for one request. Returns a mutable context the handler
+ * enriches, or `null` when billing is disabled (zero-cost path). The event is
+ * emitted on response `close` via the no-throw sink — but ONLY when the request
+ * produced usage (a billable request).
+ */
+declare function beginBillingCapture(_req: http.IncomingMessage, res: http.ServerResponse, now: number, defer?: BillingDefer): BillingCaptureContext | null;
+
+export { type BillingCaptureContext, type BillingDefer, beginBillingCapture };

package/dist/outbound-api/billingCapture.js

@@ -0,0 +1,8 @@
+import {
+  beginBillingCapture
+} from "../chunk-WLYIIEAF.js";
+import "../chunk-TKJMZBAH.js";
+import "../chunk-OZFM4X3S.js";
+export {
+  beginBillingCapture
+};

package/dist/outbound-api/quotaWarn.cjs

@@ -0,0 +1,12 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+var _chunk4YINUUKQcjs = require('../chunk-4YINUUKQ.cjs');
+
+
+
+
+
+exports.WEBHOOK_QUOTA_WARN_RATIO = _chunk4YINUUKQcjs.WEBHOOK_QUOTA_WARN_RATIO; exports.__resetQuotaWarnGuardForTests = _chunk4YINUUKQcjs.__resetQuotaWarnGuardForTests; exports.computeQuotaWarnings = _chunk4YINUUKQcjs.computeQuotaWarnings; exports.markQuotaWarnedOnce = _chunk4YINUUKQcjs.markQuotaWarnedOnce;

package/dist/outbound-api/quotaWarn.d.cts

@@ -0,0 +1,43 @@
+import { K as KeyCostLimits, c as KeySpend } from '../keyPolicy-Cp0FntZl.cjs';
+
+/**
+ * quotaWarn — the key.quotaWarning threshold helper (webhook-notifications,
+ * design D3, Phase 2).
+ *
+ * A PURE crossing detector ({@link computeQuotaWarnings}) + a tiny module-level
+ * "already warned this window" guard ({@link markQuotaWarnedOnce}). The wire
+ * path (`outboundApiRouter`) computes warnings alongside the existing quota
+ * check and emits `key.quotaWarning` ONCE per window-crossing — so a key sitting
+ * above the warn ratio doesn't spam a webhook every request. The guard is keyed
+ * by `keyId + scope + windowStart`, so a NEW day/week window re-arms the warning
+ * naturally (its `windowStart` differs).
+ *
+ * @module @omnicross/core/outbound-api/quotaWarn
+ */
+
+/** Warn when accumulated spend reaches this fraction of a scope's limit (design OQ2). */
+declare const WEBHOOK_QUOTA_WARN_RATIO = 0.8;
+/** A per-scope warning crossing (not-yet-exceeded, at/over the warn ratio). */
+interface QuotaWarning {
+    scope: 'daily' | 'weekly' | 'total';
+    limitUsd: number;
+    spentUsd: number;
+    /** The window boundary (epoch ms; `0` for the window-less `total` scope). */
+    windowStart: number;
+}
+/**
+ * Detect which cost scopes have crossed the warn ratio but are NOT yet exceeded
+ * (an EXCEEDED scope is handled by `checkKeyQuota` → `key.quotaExceeded`, not a
+ * warning). Pure — the caller owns the emit + the dedupe guard.
+ */
+declare function computeQuotaWarnings(limits: KeyCostLimits, spend: KeySpend, ratio?: number): QuotaWarning[];
+/**
+ * Record a warning for `(keyId, scope, windowStart)` and return whether THIS is
+ * the first time (⇒ the caller should emit). Subsequent calls in the same window
+ * return `false` (deduped). A new window (different `windowStart`) re-arms.
+ */
+declare function markQuotaWarnedOnce(keyId: string, scope: string, windowStart: number): boolean;
+/** TEST SEAM — clear the dedupe guard between suites. */
+declare function __resetQuotaWarnGuardForTests(): void;
+
+export { type QuotaWarning, WEBHOOK_QUOTA_WARN_RATIO, __resetQuotaWarnGuardForTests, computeQuotaWarnings, markQuotaWarnedOnce };

package/dist/outbound-api/quotaWarn.d.ts

@@ -0,0 +1,43 @@
+import { K as KeyCostLimits, c as KeySpend } from '../keyPolicy-Cp0FntZl.js';
+
+/**
+ * quotaWarn — the key.quotaWarning threshold helper (webhook-notifications,
+ * design D3, Phase 2).
+ *
+ * A PURE crossing detector ({@link computeQuotaWarnings}) + a tiny module-level
+ * "already warned this window" guard ({@link markQuotaWarnedOnce}). The wire
+ * path (`outboundApiRouter`) computes warnings alongside the existing quota
+ * check and emits `key.quotaWarning` ONCE per window-crossing — so a key sitting
+ * above the warn ratio doesn't spam a webhook every request. The guard is keyed
+ * by `keyId + scope + windowStart`, so a NEW day/week window re-arms the warning
+ * naturally (its `windowStart` differs).
+ *
+ * @module @omnicross/core/outbound-api/quotaWarn
+ */
+
+/** Warn when accumulated spend reaches this fraction of a scope's limit (design OQ2). */
+declare const WEBHOOK_QUOTA_WARN_RATIO = 0.8;
+/** A per-scope warning crossing (not-yet-exceeded, at/over the warn ratio). */
+interface QuotaWarning {
+    scope: 'daily' | 'weekly' | 'total';
+    limitUsd: number;
+    spentUsd: number;
+    /** The window boundary (epoch ms; `0` for the window-less `total` scope). */
+    windowStart: number;
+}
+/**
+ * Detect which cost scopes have crossed the warn ratio but are NOT yet exceeded
+ * (an EXCEEDED scope is handled by `checkKeyQuota` → `key.quotaExceeded`, not a
+ * warning). Pure — the caller owns the emit + the dedupe guard.
+ */
+declare function computeQuotaWarnings(limits: KeyCostLimits, spend: KeySpend, ratio?: number): QuotaWarning[];
+/**
+ * Record a warning for `(keyId, scope, windowStart)` and return whether THIS is
+ * the first time (⇒ the caller should emit). Subsequent calls in the same window
+ * return `false` (deduped). A new window (different `windowStart`) re-arms.
+ */
+declare function markQuotaWarnedOnce(keyId: string, scope: string, windowStart: number): boolean;
+/** TEST SEAM — clear the dedupe guard between suites. */
+declare function __resetQuotaWarnGuardForTests(): void;
+
+export { type QuotaWarning, WEBHOOK_QUOTA_WARN_RATIO, __resetQuotaWarnGuardForTests, computeQuotaWarnings, markQuotaWarnedOnce };

package/dist/outbound-api/quotaWarn.js

@@ -0,0 +1,12 @@
+import {
+  WEBHOOK_QUOTA_WARN_RATIO,
+  __resetQuotaWarnGuardForTests,
+  computeQuotaWarnings,
+  markQuotaWarnedOnce
+} from "../chunk-3QFXFCHG.js";
+export {
+  WEBHOOK_QUOTA_WARN_RATIO,
+  __resetQuotaWarnGuardForTests,
+  computeQuotaWarnings,
+  markQuotaWarnedOnce
+};

package/dist/outbound-api/routeResolver.cjs

@@ -3,7 +3,7 @@
 
 
 
-var _chunkSVXC36MUcjs = require('../chunk-SVXC36MU.cjs');
+var _chunkVACWOIREcjs = require('../chunk-VACWOIRE.cjs');
 require('../chunk-QBZJ7P2T.cjs');
 require('../chunk-4IH4EL7M.cjs');
 
@@ -11,4 +11,4 @@ require('../chunk-4IH4EL7M.cjs');
 
 
 
-exports.isSubscriptionProviderId = _chunkSVXC36MUcjs.isSubscriptionProviderId; exports.parseModelRef = _chunkSVXC36MUcjs.parseModelRef; exports.pickModelRefFromList = _chunkSVXC36MUcjs.pickModelRefFromList; exports.resolveRoute = _chunkSVXC36MUcjs.resolveRoute;
+exports.isSubscriptionProviderId = _chunkVACWOIREcjs.isSubscriptionProviderId; exports.parseModelRef = _chunkVACWOIREcjs.parseModelRef; exports.pickModelRefFromList = _chunkVACWOIREcjs.pickModelRefFromList; exports.resolveRoute = _chunkVACWOIREcjs.resolveRoute;

package/dist/outbound-api/routeResolver.d.cts

@@ -1,7 +1,7 @@
 import '../ports/provider-config-source.cjs';
 import '../provider-proxy/types.cjs';
-import '../types-aBFFXoBz.cjs';
-export { R as RouteResolveError, b as RouteResolveResult, i as isSubscriptionProviderId, p as parseModelRef, a as pickModelRefFromList, r as resolveRoute } from '../routeResolver-CbG5uBgm.cjs';
+import '../types-B8Arpxn0.cjs';
+export { R as RouteResolveError, b as RouteResolveResult, i as isSubscriptionProviderId, p as parseModelRef, a as pickModelRefFromList, r as resolveRoute } from '../routeResolver-CB3tvJKy.cjs';
 import '@omnicross/contracts/llm-config';
 import '../transformer/types.cjs';
 import '../transformer/TransformerService.cjs';
@@ -23,3 +23,4 @@ import '@omnicross/contracts/health-logging-types';
 import '@omnicross/contracts/voucher-types';
 import '@omnicross/contracts/webhook-types';
 import '../ProviderProxy-CnMQYN59.cjs';
+import '../keyPolicy-Cp0FntZl.cjs';

package/dist/outbound-api/routeResolver.d.ts

@@ -1,7 +1,7 @@
 import '../ports/provider-config-source.js';
 import '../provider-proxy/types.js';
-import '../types-6OUY_xfA.js';
-export { R as RouteResolveError, b as RouteResolveResult, i as isSubscriptionProviderId, p as parseModelRef, a as pickModelRefFromList, r as resolveRoute } from '../routeResolver-B1NglTfe.js';
+import '../types-lgPYQuZS.js';
+export { R as RouteResolveError, b as RouteResolveResult, i as isSubscriptionProviderId, p as parseModelRef, a as pickModelRefFromList, r as resolveRoute } from '../routeResolver-C4T7yClx.js';
 import '@omnicross/contracts/llm-config';
 import '../transformer/types.js';
 import '../transformer/TransformerService.js';
@@ -23,3 +23,4 @@ import '@omnicross/contracts/health-logging-types';
 import '@omnicross/contracts/voucher-types';
 import '@omnicross/contracts/webhook-types';
 import '../ProviderProxy-C-xqrkKi.js';
+import '../keyPolicy-Cp0FntZl.js';

package/dist/outbound-api/routeResolver.js

@@ -3,7 +3,7 @@ import {
   parseModelRef,
   pickModelRefFromList,
   resolveRoute
-} from "../chunk-CZHZGRU7.js";
+} from "../chunk-UHGVBFU3.js";
 import "../chunk-AQ5TNQB7.js";
 import "../chunk-XEKD23J5.js";
 export {

package/dist/outbound-api/types.d.cts

@@ -8,7 +8,7 @@ import '../logger-4GvQNzhE.cjs';
 import '../ports/provider-config-source.cjs';
 import '../ProviderProxy-CnMQYN59.cjs';
 import '../provider-proxy/types.cjs';
-export { T as AccountHealthConfig, A as AccountProbeConfig, C as ChatDispatchMode, a as ConcurrencyQueueConfig, E as ENDPOINT_MODEL_KINDS, b as EndpointRoutingConfig, F as FingerprintConfig, i as KindMappedEndpoint, M as MessagesModelKind, j as ModelKind, k as ModelPrefixTargets, P as ModelRef, l as OutboundApiDeps, m as OutboundApiKeyCreated, n as OutboundApiKeyInfo, o as OutboundApiServerConfig, p as OutboundApiServerStatus, q as OutboundEndpoint, r as OutboundFormatUrls, s as OutboundKeyActivationMode, O as OutboundKeyDb, t as OutboundKeyDbRow, W as OutboundKeyModelRestrictionMode, u as OutboundKeyPolicy, v as OutboundProxyConfig, R as RequestRole, w as ResponsesModelKind, U as UserMessageQueueConfig } from '../types-aBFFXoBz.cjs';
+export { H as AccountHealthConfig, A as AccountProbeConfig, C as ChatDispatchMode, a as ConcurrencyQueueConfig, E as ENDPOINT_MODEL_KINDS, b as EndpointRoutingConfig, F as FingerprintConfig, e as KindMappedEndpoint, M as MessagesModelKind, f as ModelKind, g as ModelPrefixTargets, G as ModelRef, h as OutboundApiDeps, i as OutboundApiKeyCreated, j as OutboundApiKeyInfo, k as OutboundApiServerConfig, l as OutboundApiServerStatus, m as OutboundEndpoint, n as OutboundFormatUrls, o as OutboundKeyActivationMode, O as OutboundKeyDb, p as OutboundKeyDbRow, I as OutboundKeyModelRestrictionMode, q as OutboundKeyPolicy, r as OutboundProxyConfig, R as RequestRole, s as ResponsesModelKind, U as UserMessageQueueConfig } from '../types-B8Arpxn0.cjs';
 import '@omnicross/contracts/llm-config';
 import '../transformer/types.cjs';
 import '../transformer/TransformerService.cjs';
@@ -22,3 +22,4 @@ import '../pipeline/SubscriptionAuthSource.cjs';
 import '../pipeline/SubscriptionAuthStrategy.cjs';
 import '../ports/web-search-backend.cjs';
 import '@omnicross/contracts/websearch-types';
+import '../keyPolicy-Cp0FntZl.cjs';