ordainer 1.0.0 → 1.2.4

package/index.js

@@ -0,0 +1,1012 @@
+'use strict';
+// ordainer: call Ordainer's POST /v1/decide before your tool handler runs.
+// Zero dependencies. Node 20+ (global fetch, AbortSignal.timeout).
+//
+//   const { Ordainer } = require('ordainer');
+//   const ordainer = new Ordainer({ apiKey: process.env.ORDAINER_KEY });
+//   app.post('/research', ordainer.middleware({ tool: 'research.run' }), handler);
+//
+// Rules:
+// - decide() never throws. A policy deny is a normal result.
+// - Mode (what to do with a deny):
+//     unset (default): follow the plan's mode from the Ordainer console, so you
+//       can switch shadow -> enforce with no deploy;
+//     'shadow': never block; log/report "would deny";
+//     'enforce': block on deny.
+// - Fail mode (what to do when Ordainer can't answer: timeout, network error,
+//   5xx, or a 200 that isn't a decision): 'open' (default) lets the call run;
+//   'closed' blocks it. ONLY those. A 4xx answer (400, 401, 403, 409, 429, ...)
+//   and a missing agent key are never an unchecked allow: the call is blocked
+//   (plan_check_rejected: 500, or 403 for billing; or 429 rate_limited) whatever
+//   failMode says, and result.rejected is true (QA S2, Q2). The one exception,
+//   403 subscription_inactive, follows billingLapse (below).
+// - 403 subscription_inactive (the vendor's own Ordainer subscription is inactive) is a
+//   billing state, not an outage. It follows ONLY the billing-lapse setting
+//   (billingLapse, Terms 10.3(b), Tyler Oct 3: Option A), never failMode:
+//   'open' (default) lets the call run, unchecked (result.allowed, not failOpen);
+//   'closed' (opt-in) blocks it with 403 plan_check_rejected, no Retry-After and the
+//   neutral end-user message (result.rejected). Both: its own rate-limited warning,
+//   result.billingInactive, result.billingLapse and onBillingInactive on every call.
+// - 403 subscription_required (a live key, never paid) is blocked like any other
+//   4xx, also with the billing warning, result.billingInactive and onBillingInactive.
+// - deny `test_limit_reached` (the vendor's account used its free monthly
+//   test-key decisions) is a real deny from Ordainer, not an error: failMode
+//   doesn't apply. Enforce: blocked, 429 test_limit_reached with Retry-After.
+//   Shadow (1.2.0, the server answers mode 'shadow'): shadow never blocks, so the
+//   call runs as a would-deny. Both: its own rate-limited warning,
+//   result.testLimitReached, onTestLimit.
+// - 429 safety_limit_reached (1.2.0: shadow calls past the server's safety ceiling,
+//   10x the account's monthly test limit) is a safety limit, not a deny: the call
+//   RUNS in every failMode (like billingLapse 'open'), unchecked. result.allowed,
+//   result.safetyLimited (failOpen false), its own rate-limited warning, onSafetyLimit.
+// - The base URL's host doesn't resolve (ENOTFOUND / EAI_AGAIN): failMode applies as
+//   for any network error, and the first time per host one loud error-level line
+//   (not throttled) names the host and says to set ORDAINER_BASE_URL.
+// - 429 rate_limited (this agent key is over Ordainer's per-key abuse limit) is a
+//   rate limit, not an outage: blocked with 429 rate_limited + Retry-After in
+//   any failMode, and never silent: its own rate-limited warning,
+//   result.rateLimited, result.retryAfterSec and onRateLimited on every such call.
+// - 429 concurrency_limited (this agent key has too many decides in flight at once,
+//   Ordainer's per-key concurrency limit) is handled exactly like 429 rate_limited
+//   (result.rateLimited, reason 'concurrency_limited', error.limitScope
+//   'per_key_concurrency', the end user gets 429 rate_limited + Retry-After). Never a fail-open.
+// - 429 too_many_failed_auth (Ordainer's per-address limit on missing/unknown keys;
+//   never sent for a valid key) is a bad key, not a rate problem: rejected, with
+//   result.error.limitScope 'per_address' and its own warning (H3). rateLimited stays false.
+// - Idempotency: every decide sends a key. The middleware NEVER forwards the
+//   incoming request's Idempotency-Key header (an agent could replay one key to
+//   get one stored allow many times, QA S1): each incoming request gets a fresh
+//   random key unless you pass idempotencyKey(req) built from your own trusted
+//   data. Use one key per real operation. retries (default 1) retries a timeout,
+//   network error or 503 with the SAME key, so a retry is replayed, not counted.
+// - Blocked calls get 429 for quota_exceeded (with Retry-After until the plan
+//   resets), 403 for other denies, 503 ordainer_unavailable only for a real
+//   outage under failMode 'closed' (with Retry-After: 5). Retry-After only where
+//   a retry can work: quota/test limit (until the reset), 429 rate_limited, and
+//   that outage. A block a retry can't fix (Q2) is plan_check_rejected with no
+//   Retry-After and no "try again": 403 for billing (subscription_required, or
+//   the subscription_inactive lapse under billingLapse 'closed'; neutral message), 500 for everything else
+//   (missing, unknown or revoked key, too_many_failed_auth, 400, 409, other 4xx).
+// - Sticky deny (QA N7-3 remainder): after a quota_exceeded deny for an (agent key, tool), a later call for the
+//   same pair that would fail open (timeout, network error, 5xx, malformed answer) is denied instead (429
+//   plan_limit_reached, result.stickyDeny) until stickyDenyMs (default 60 s, max 5 min, 0 = off) or the plan's
+//   reset passes, or an allow arrives for the pair. Shadow (requested, or the plan's mode on that deny) still
+//   runs the call and reports it (result.stickyDeny, wouldDeny). One agent key is one customer, so the pair is
+//   (customer, tool). In memory, per Ordainer instance.
+// - Result flags, distinct: failOpen = failMode 'open' let it run without a
+//   decision; failClosed = failMode 'closed' blocked it (no decision); rejected
+//   = Ordainer refused it (4xx) or it couldn't be sent, blocked in any failMode.
+const crypto = require('crypto');
+const { version: SDK_VERSION } = require('./package.json'); // npm pack always ships package.json
+
+// Brand strings in one place ("Ordainer" is a working name; the rename sweep edits this block).
+const BRAND = Object.freeze({
+  name: 'Ordainer',
+  baseUrl: 'https://api.ordainer.dev', // docs-site download (the npm release defaults to the launch host)
+  envKey: 'ORDAINER_KEY',
+  envBaseUrl: 'ORDAINER_BASE_URL',
+  logPrefix: '[ordainer]',
+  userAgent: `ordainer-node/${SDK_VERSION}`,
+  unavailableCode: 'ordainer_unavailable', // error.code for a real outage under failMode 'closed' (503 + Retry-After)
+  rejectedCode: 'plan_check_rejected', // error.code for a block a retry can't fix (Q2): 403 billing, 500 otherwise
+});
+const DEFAULT_BASE_URL = BRAND.baseUrl;
+const DEFAULT_TIMEOUT_MS = 300;
+const MODES = new Set(['enforce', 'shadow']);
+const FAIL_MODES = new Set(['open', 'closed']);
+// Terms 10.3(b): the billing-lapse setting, separate from failMode. Default 'open'.
+const BILLING_LAPSE_MODES = FAIL_MODES;
+// Legal-approved (Oct 3, 5:23 PM ET; tech/billing-lapse-scope.md item 2), verbatim: what a blocked end user sees when
+// the vendor's Ordainer billing blocks the call. No mention of billing or of Ordainer, no retry hint.
+const BILLING_BLOCKED_MESSAGE = "This action isn't available right now. This is a setup issue on the service's side; retrying won't help.";
+const BILLING_WARNING_INTERVAL_MS = 60_000;
+const BILLING_CODES = new Set(['subscription_inactive', 'subscription_required']);
+const TEST_LIMIT_REASON = 'test_limit_reached';
+// 429 from the server's per-key in-flight cap (QA round 3 M-1); handled like rate_limited.
+const CONCURRENCY_CODE = 'concurrency_limited';
+const LIMIT_SCOPES = new Set(['per_key', 'per_address', 'per_key_concurrency', 'org_safety']);
+// 429 from the server's shadow safety ceiling (1.2.0): a safety limit, not a deny. The call runs in any failMode.
+const SAFETY_LIMIT_CODE = 'safety_limit_reached';
+// Host lookup failures on the configured base URL (a typo or a missing ORDAINER_BASE_URL): loud on first occurrence.
+const DNS_CODES = new Set(['ENOTFOUND', 'EAI_AGAIN']);
+// The server rejects idempotency keys longer than this (400 invalid_idempotency_key).
+const MAX_IDEMPOTENCY_LEN = 255;
+const MAX_RETRIES = 5;
+const RETRY_DELAY_MS = 50;
+// Architecture review #1: one retry by default, only for a timeout, a network error or a 503 (the server's
+// fast decide_timeout / db_timeout / db_unavailable / outage answers), and only inside a small total time budget for the
+// whole decide() (all attempts and the pauses between them). 4xx and other 5xx are never retried.
+const DEFAULT_RETRIES = 1;
+const DEFAULT_RETRY_BUDGET_MS = 650; // one 300 ms attempt + 50 ms pause + one more 300 ms attempt
+const MIN_ATTEMPT_MS = 50; // a retry with less time left than this isn't started
+const DEFAULT_STICKY_DENY_MS = 60_000;
+const MAX_STICKY_DENY_MS = 300_000;
+const MAX_STICKY_ENTRIES = 10_000;
+
+/**
+ * The idempotency key actually sent for `raw`. Deterministic, so a retry with the
+ * same raw key always maps to the same sent key (and is replayed, not counted).
+ * - prefixTool: the middleware form `${tool}:${raw}`.
+ * - If the key would be longer than 255 characters, send `${tool}:` + sha256hex(raw)
+ *   instead, or the bare sha256hex(raw) if even that is too long. Without this an
+ *   oversized key got a 400 from the server, the SDK failed open, and a call that
+ *   should have been denied at the cap ran uncounted.
+ * - QA N8-3: the same when the key holds characters the server refuses (control
+ *   characters U+0000-U+001F, U+007F, or an unpaired surrogate), so a shadow-mode
+ *   caller with such a key is not blocked by a 400. Unpaired surrogates are hashed
+ *   from the UTF-16 code units (UTF-8 would turn them all into U+FFFD, so two
+ *   different keys could collide and one be replayed instead of counted).
+ */
+const BAD_KEY_TEXT = /[\u0000-\u001f\u007f]|[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
+const LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
+function idempotencyKeyFor(tool, raw, { prefixTool = false } = {}) {
+  const candidate = prefixTool ? `${tool}:${raw}` : raw;
+  if (candidate.length <= MAX_IDEMPOTENCY_LEN && !BAD_KEY_TEXT.test(candidate)) return candidate;
+  const bytes = LONE_SURROGATE.test(raw) ? Buffer.from(raw, 'utf16le') : Buffer.from(raw, 'utf8');
+  const digest = crypto.createHash('sha256').update(bytes).digest('hex');
+  const withTool = `${tool}:${digest}`;
+  return withTool.length <= MAX_IDEMPOTENCY_LEN && !BAD_KEY_TEXT.test(withTool) ? withTool : digest;
+}
+
+class OrdainerDeniedError extends Error {
+  constructor(result) {
+    const response = denyResponse(result);
+    super(response.body.error.message);
+    this.name = 'OrdainerDeniedError';
+    this.result = result;
+    this.status = response.status;
+    this.headers = response.headers;
+    this.body = response.body;
+  }
+}
+
+function checkMode(mode, where) {
+  if (mode !== undefined && mode !== null && !MODES.has(mode)) {
+    throw new TypeError(`${where}: mode must be "enforce", "shadow" or unset`);
+  }
+}
+
+function checkFailMode(failMode, where) {
+  if (failMode !== undefined && !FAIL_MODES.has(failMode)) {
+    throw new TypeError(`${where}: failMode must be "open" or "closed"`);
+  }
+}
+
+function checkBillingLapse(billingLapse, where) {
+  if (billingLapse !== undefined && !BILLING_LAPSE_MODES.has(billingLapse)) {
+    throw new TypeError(`${where}: billingLapse must be "open" or "closed"`);
+  }
+}
+
+// Quota denies answer 429 Too Many Requests (default) or 402 Payment Required.
+// Anything else is a typo that would confuse the agent, so it throws up front.
+const DENY_STATUSES = new Set([429, 402]);
+function checkRetries(retries, where) {
+  if (retries !== undefined && (!Number.isInteger(retries) || retries < 0 || retries > MAX_RETRIES)) {
+    throw new TypeError(`${where}: retries must be an integer from 0 to ${MAX_RETRIES}`);
+  }
+}
+
+function checkDenyStatus(denyStatus, where) {
+  if (denyStatus !== undefined && denyStatus !== null && !DENY_STATUSES.has(denyStatus)) {
+    throw new TypeError(`${where}: denyStatus must be 429 or 402 (got ${JSON.stringify(denyStatus)})`);
+  }
+}
+
+// Caller-facing text for a 429 rate_limited / concurrency_limited block (Content & DevRel, Oct 18). Only the message differs:
+// the code field stays rate_limited for both, and status, Retry-After and retry_after are unchanged.
+const RATE_LIMITED_MESSAGE = "The service is getting too many requests on this key right now, so this call was held back. Please wait a moment and try again. (rate_limited)";
+const CONCURRENCY_LIMITED_MESSAGE = "The service is handling too many calls on this key at once, so this call was held back. Please wait a moment and try again. (concurrency_limited)";
+
+// T18-P40: the caller-facing sentence for a block a retry can't fix (500 plan_check_rejected). Plain words first, the
+// API's own code last, for the service's team (the code field stays plan_check_rejected; nothing else changes: status,
+// headers, allowed/rejected). Only the human message depends on the cause. The code is echoed only if it looks like one
+// of the API's codes (lowercase letters and _ only, <= 40 chars), so a strange answer can't inject text.
+const KEY_NOT_RECOGNIZED_CODES = new Set(['unknown_key', 'old_key_format', 'too_many_failed_auth']);
+// Content & DevRel final wording (Oct 18, content/persona-2-2026-10-18/p40-sdk-key-messages.md): no "plan-check key"
+// (our jargon; the reader is the service's customer), no "It isn't an outage" (not always true: a too_many_failed_auth
+// for a key the server couldn't check in time, or a restore on our side), and "setup issue on the service's side" to match
+// the Legal-approved billing message. too_many_failed_auth stays in the key-not-recognized group: the API answers the
+// "couldn't check this key just now" case with the same status, code, limit_scope and headers; only its English message
+// differs (src/app.js FAILED_AUTH_MESSAGE vs POSSIBLE_WRONG_DENY_MESSAGE), and the SDK doesn't parse messages.
+const REJECTED_TAIL = "It isn't something you did, and retrying won't help until the service";
+function rejectedMessage(code) {
+  let msg;
+  if (code === 'missing_key') {
+    msg = `This call wasn't run. This is a setup issue on the service's side: a key it needs is missing. ${REJECTED_TAIL} adds the key.`;
+  } else if (code === 'revoked_key') {
+    msg = `This call wasn't run. This is a setup issue on the service's side: one of its keys has been turned off. ${REJECTED_TAIL} switches to a new key.`;
+  } else if (KEY_NOT_RECOGNIZED_CODES.has(code)) {
+    msg = `This call wasn't run. This is a setup issue on the service's side: one of its keys isn't recognized. ${REJECTED_TAIL} fixes the key.`;
+  } else {
+    msg = `This call wasn't run because of a setup issue on the service's side. ${REJECTED_TAIL} fixes it.`;
+  }
+  return typeof code === 'string' && /^[a-z][a-z_]{0,39}$/.test(code) ? `${msg} (For the service's team: ${code}.)` : msg;
+}
+
+// P95R-N3 (Content & DevRel, Oct 18, content/persona-2-2026-10-18/p40-sdk-key-messages.md Addendum 3): caller-facing
+// text for the 503 fail-closed outage, the 429 test allowance and the 403 plan deny. No product name and none of our
+// terms; same bytes as the Ruby SDK. Only the message changes: status, code (ordainer_unavailable is kept), headers and
+// the other fields are unchanged. Text replaced by the PM's final wording (Oct 18); codes and fields are as before.
+const UNAVAILABLE_MESSAGE = "This call wasn't run. The service couldn't finish a safety check it does before each call, so it stopped instead of going ahead without it. Nothing is wrong on your side. Please try again in a minute."
+  + ` (${BRAND.unavailableCode})`;
+// Addendum 3 amendment (Oct 18, CoS): the reset day as "<Month D>" in UTC (full English month, day without a leading
+// zero, no year), e.g. "2026-11-01T00:00:00.000Z" -> "November 1". Only for a string that is a valid ISO-8601 date-time
+// (YYYY-MM-DDTHH:MM:SS, optional .fraction, then Z or +HH:MM/-HH:MM); anything else (missing, null, "", 0, false, a
+// number, garbage, trailing text, an impossible date) gives null and the sentence is left out. Fixed month array and
+// integer UTC math only (no Date.parse, no locale APIs), so the bytes match the Ruby SDK's reset_day_utc exactly.
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+const ISO_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(?:Z|([+-])(\d{2}):(\d{2}))$/;
+function resetDayUtc(v) {
+  if (typeof v !== 'string') return null;
+  const m = ISO_DATE_TIME.exec(v);
+  if (!m) return null;
+  const [y, mo, d, h, mi, s] = m.slice(1, 7).map(Number);
+  const leap = (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
+  const dim = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  if (mo < 1 || mo > 12 || d < 1 || d > dim[mo - 1] || h > 23 || mi > 59 || s > 59) return null;
+  let off = 0;
+  if (m[7]) {
+    const oh = Number(m[8]);
+    const om = Number(m[9]);
+    if (oh > 23 || om > 59) return null;
+    off = (m[7] === '-' ? -1 : 1) * (oh * 60 + om);
+  }
+  // Minutes from local midnight, shifted to UTC; at most one day either way.
+  const mins = h * 60 + mi - off;
+  let uy = y; let um = mo; let ud = d;
+  if (mins < 0) {
+    ud -= 1;
+    if (ud < 1) { um -= 1; if (um < 1) { um = 12; uy -= 1; } ud = dim[um - 1]; } // Feb only from Mar 1 (same year)
+  } else if (mins >= 1440) {
+    ud += 1;
+    if (ud > dim[mo - 1]) { ud = 1; um += 1; if (um > 12) { um = 1; uy += 1; } }
+  }
+  return `${MONTHS[um - 1]} ${ud}`;
+}
+function testLimitMessage(resetsAt) {
+  const day = resetDayUtc(resetsAt);
+  return "This call wasn't run. This service's test calls for the month are used up."
+    + (day ? ` They reset on ${day} (UTC).` : '')
+    + " Nothing is wrong on your side, and trying again won't help until they reset. If you need it sooner, contact the service's team. (test_limit_reached)";
+}
+// PM final wording (Oct 18). tool_not_in_plan names the tool the SDK sent in decide(), in double quotes, only when it
+// looks like a plain tool name (^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$); otherwise (missing, not a string, spaces, quotes,
+// control or bidi characters, 65+ chars) "this action". Any other reason is echoed in brackets only if it looks like one
+// of the API's codes (same guard as rejectedMessage). Same bytes as the Ruby SDK.
+const TOOL_NAME_SHAPE = /^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$/;
+// QA P95F-N3: nothing URL-like is echoed either: no "//" anywhere and no leading "scheme:" (RFC 3986 shape).
+const TOOL_SCHEME_PREFIX = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+function showableTool(tool) {
+  return typeof tool === 'string' && TOOL_NAME_SHAPE.test(tool) && !tool.includes('//') && !TOOL_SCHEME_PREFIX.test(tool);
+}
+function planDeniedMessage(reason, tool) {
+  if (reason === 'tool_not_in_plan') {
+    const what = showableTool(tool) ? `"${tool}"` : 'this action';
+    return `This call wasn't run because your plan doesn't include ${what}. If you need it, ask whoever manages your plan. (tool_not_in_plan)`;
+  }
+  const msg = "This call wasn't run because it isn't allowed on your account right now. If you need it, contact the service's team.";
+  return typeof reason === 'string' && /^[a-z][a-z_]{0,39}$/.test(reason) ? `${msg} (${reason})` : msg;
+}
+
+// T18-P39: the agent key's name (label) from a deny answer, made safe for a JSON body, a sentence and a log line:
+// control (C0, DEL and C1 U+0080-U+009F), lone-surrogate and invisible/format characters removed, whitespace collapsed, at most MAX_LABEL_LENGTH
+// characters (a cut label ends with "…"). null when there's no usable label. The server cleans it too; this doesn't
+// trust that.
+const MAX_LABEL_LENGTH = 64;
+const STRIP_LABEL = /[\u0000-\u001f\u007f-\u009f]|[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]|[\p{Cf}\u115f\u1160\u3164\uffa0\ufe00-\ufe0f\u{e0000}-\u{e007f}\u{e0100}-\u{e01ef}]/gu;
+function safeKeyLabel(v) {
+  if (typeof v !== 'string' || !v) return null;
+  const clean = v.replace(/\s+/gu, ' ').replace(STRIP_LABEL, '').replace(/ {2,}/g, ' ').trim();
+  if (!clean) return null;
+  const chars = Array.from(clean);
+  return chars.length <= MAX_LABEL_LENGTH ? clean : `${chars.slice(0, MAX_LABEL_LENGTH - 1).join('').trimEnd()}…`;
+}
+
+// What a blocked call should answer. Safe to return verbatim to the agent.
+// Same conventions as the Ordainer API: an X-Request-Id header and
+// {"error": {"code", "message", "request_id", ...}}.
+function denyResponse(result, now = Date.now()) {
+  const requestIdHeader = result.requestId ? { 'X-Request-Id': result.requestId } : {};
+  // 429 rate_limited: a real "slow down", so Retry-After (the server's value).
+  if (!result.allowed && result.rateLimited) {
+    const retry = String(result.retryAfterSec || 1);
+    return {
+      status: 429,
+      headers: { 'Retry-After': retry, ...requestIdHeader },
+      body: {
+        error: {
+          code: 'rate_limited',
+          // Content & DevRel (Oct 18): plain words for the service's customers; no product name. Retry-After still carries the seconds.
+          message: result.reason === CONCURRENCY_CODE ? CONCURRENCY_LIMITED_MESSAGE : RATE_LIMITED_MESSAGE,
+          request_id: result.requestId || null,
+          retry_after: Number(retry),
+        },
+      },
+    };
+  }
+  // G5/Q2: a block a retry can't fix (missing/unknown/revoked key, any other
+  // rejected 4xx, or the vendor's billing): plan_check_rejected, never 503 (a 503
+  // says "outage, retry"), no Retry-After and no "try again", so agents don't
+  // hammer it. 403 when it's the vendor's billing (subscription_required, or the
+  // subscription_inactive lapse under billingLapse 'closed'), with the neutral
+  // Legal-approved message (Terms 10.3(b)); 500 otherwise (a key, config, 400 or
+  // 409 problem on the vendor's side).
+  if (result.rejected || (result.failClosed && result.billingInactive)) {
+    const billing = result.billingInactive;
+    return {
+      status: billing ? 403 : 500,
+      headers: { ...requestIdHeader },
+      body: {
+        error: {
+          code: BRAND.rejectedCode,
+          message: billing
+            ? BILLING_BLOCKED_MESSAGE
+            : rejectedMessage(result.error && result.error.code),
+          request_id: result.requestId || null,
+        },
+      },
+    };
+  }
+  // A real outage (timeout, network error, 5xx, malformed answer) under failMode 'closed'.
+  if (result.failClosed) {
+    return {
+      status: 503,
+      headers: { 'Retry-After': '5', ...requestIdHeader },
+      body: {
+        error: {
+          code: BRAND.unavailableCode,
+          message: UNAVAILABLE_MESSAGE,
+          request_id: result.requestId || null,
+        },
+      },
+    };
+  }
+  if (result.reason === TEST_LIMIT_REASON) {
+    const resets = result.resetsAt ? Date.parse(result.resetsAt) : NaN;
+    const headers = { ...requestIdHeader };
+    if (Number.isFinite(resets)) headers['Retry-After'] = String(Math.max(1, Math.ceil((resets - now) / 1000)));
+    return {
+      status: 429,
+      headers,
+      body: {
+        error: {
+          code: TEST_LIMIT_REASON,
+          message: testLimitMessage(result.resetsAt),
+          request_id: result.requestId,
+          reason: result.reason,
+          resets_at: result.resetsAt,
+        },
+      },
+    };
+  }
+  if (result.reason === 'quota_exceeded') {
+    const label = safeKeyLabel(result.label);
+    const resets = result.resetsAt ? Date.parse(result.resetsAt) : NaN;
+    const headers = { ...requestIdHeader };
+    if (Number.isFinite(resets)) headers['Retry-After'] = String(Math.max(1, Math.ceil((resets - now) / 1000)));
+    return {
+      status: result.denyStatus || 429,
+      headers,
+      body: {
+        error: {
+          code: 'plan_limit_reached',
+          // T18-P39: name the agent when the API sent its key's label (and exposeKeyLabel isn't false).
+          message: (label
+            ? `This agent (${label}) has reached its plan limit (${result.remaining ?? 0} of ${result.limit ?? '?'} left).`
+            : `This agent's plan limit is reached (${result.remaining ?? 0} of ${result.limit ?? '?'} left).`)
+            + (result.resetsAt ? ` It resets at ${result.resetsAt}.` : '')
+            + ' Retrying before then will not succeed. This call was not run.',
+          ...(label ? { label } : {}),
+          request_id: result.requestId,
+          reason: result.reason,
+          remaining: result.remaining,
+          limit: result.limit,
+          resets_at: result.resetsAt,
+        },
+      },
+    };
+  }
+  return {
+    status: 403,
+    headers: { ...requestIdHeader },
+    body: {
+      error: {
+        code: 'plan_denied',
+        message: planDeniedMessage(result.reason, result.tool),
+        request_id: result.requestId,
+        reason: result.reason,
+      },
+    },
+  };
+}
+
+function sendDeny(res, result) {
+  const { status, headers, body } = denyResponse(result);
+  const payload = JSON.stringify(body);
+  res.statusCode = status;
+  for (const [k, v] of Object.entries(headers)) res.setHeader(k, v);
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  res.setHeader('Content-Length', Buffer.byteLength(payload));
+  res.end(payload);
+}
+
+// Hooks must never break the request.
+function callHook(hook, result) {
+  if (!hook) return;
+  try {
+    const p = hook(result);
+    if (p && typeof p.catch === 'function') p.catch(() => {});
+  } catch {
+    // ignored
+  }
+}
+
+// ENOTFOUND / EAI_AGAIN from fetch (undici puts the system error in err.cause), else null.
+function dnsErrorCode(err) {
+  for (let e = err, depth = 0; e && depth < 4; e = e.cause, depth += 1) {
+    if (DNS_CODES.has(e.code)) return e.code;
+  }
+  return null;
+}
+
+async function resolve(value, ...args) {
+  return typeof value === 'function' ? value(...args) : value;
+}
+
+class Ordainer {
+  /**
+   * @param {object} [opts]
+   * @param {string|function} [opts.apiKey]  agent key (ord_test_/ord_live_), or (…args) => key. Default env ORDAINER_KEY.
+   * @param {string} [opts.baseUrl]          default env ORDAINER_BASE_URL or https://api.ordainer.dev
+   * @param {number} [opts.timeoutMs]        default 300
+   * @param {'enforce'|'shadow'} [opts.mode] unset = follow the plan's mode in the console
+   * @param {'open'|'closed'} [opts.failMode] default 'open'. Applies ONLY to timeouts, network errors, 5xx and malformed
+   *                                       answers; any 4xx or a missing key always blocks (result.rejected), except
+   *                                       403 subscription_inactive, which follows billingLapse.
+   * @param {'open'|'closed'} [opts.billingLapse] default 'open' (Terms 10.3(b)). What to do when the API answers
+   *                                       403 subscription_inactive (your Ordainer subscription is inactive): 'open' runs
+   *                                       the call unchecked; 'closed' blocks it (403 plan_check_rejected, no Retry-After,
+   *                                       neutral message). Separate from failMode. Override per call/route.
+   * @param {number} [opts.retries]          extra attempts after a timeout, network error or 503 (default 1, max 5; 0 = off).
+   *                                       Each retry sends the SAME idempotency key, so it is replayed, never counted twice.
+   *                                       4xx and other 5xx are never retried.
+   * @param {number} [opts.retryBudgetMs]    total time for all attempts of one decide() (default 650). A retry starts only
+   *                                       with at least 50 ms left, and its timeout is cut to the time left.
+   * @param {number} [opts.stickyDenyMs]   after a quota_exceeded deny for an (agent key, tool), deny a would-be fail-open for
+   *                                       that pair for this long (default 60000, 0 = off, max 300000; ends early at the
+   *                                       plan's reset or on an allow). Shadow still runs the call and reports it.
+   * @param {429|402} [opts.denyStatus]     HTTP status for quota denies: 429 (default) or 402. Anything else throws
+   *                                       here. Override per route with middleware({ denyStatus }).
+   * @param {function} [opts.onDecision]     called with every result (never throws into your request)
+   * @param {function} [opts.onBillingInactive] called with the result whenever the API answers 403 subscription_inactive
+   *                                       (subscription ended) or 403 subscription_required (live key, no paid
+   *                                       subscription yet). Both set result.billingInactive; check result.error.code.
+   * @param {function} [opts.onTestLimit]  called with the result whenever the API denies with test_limit_reached
+   * @param {function} [opts.onRateLimited] called with the result whenever the API answers 429 rate_limited
+   * @param {function} [opts.onSafetyLimit] called with the result whenever the API answers 429 safety_limit_reached
+   *                                       (shadow calls past the safety ceiling; the call runs in any failMode)
+   * @param {number} [opts.warningIntervalMs] min gap between log warnings of one kind (fail-open/fail-closed per error code,
+   *                                       billing, test limit, rate limit, safety limit), default 60000. Old name: billingWarningIntervalMs
+   * @param {object|false} [opts.logger]     { warn(msg), error?(msg) }, default console; false = silent. error() (else warn())
+   *                                       gets the one-time "base URL host doesn't resolve" line
+   * @param {function} [opts.fetch]          fetch implementation (tests)
+   */
+  constructor(opts = {}) {
+    checkMode(opts.mode, BRAND.name);
+    checkFailMode(opts.failMode, BRAND.name);
+    checkBillingLapse(opts.billingLapse, BRAND.name);
+    checkDenyStatus(opts.denyStatus, BRAND.name);
+    checkRetries(opts.retries, BRAND.name);
+    this.retries = opts.retries ?? DEFAULT_RETRIES;
+    if (opts.retryBudgetMs !== undefined && (!Number.isInteger(opts.retryBudgetMs) || opts.retryBudgetMs < 0)) {
+      throw new TypeError(`${BRAND.name}: retryBudgetMs must be an integer >= 0`);
+    }
+    this.retryBudgetMs = opts.retryBudgetMs ?? DEFAULT_RETRY_BUDGET_MS;
+    if (opts.stickyDenyMs !== undefined && (!Number.isInteger(opts.stickyDenyMs) || opts.stickyDenyMs < 0 || opts.stickyDenyMs > MAX_STICKY_DENY_MS)) {
+      throw new TypeError(`${BRAND.name}: stickyDenyMs must be an integer from 0 (off) to ${MAX_STICKY_DENY_MS}`);
+    }
+    this.stickyDenyMs = opts.stickyDenyMs ?? DEFAULT_STICKY_DENY_MS;
+    this._sticky = new Map(); // sha256(key)\0tool -> { until, mode, limit, resetsAt }
+    this._sleep = opts.sleep || ((ms) => new Promise((r) => setTimeout(r, ms))); // tests
+    this.apiKey = opts.apiKey ?? process.env[BRAND.envKey];
+    this.baseUrl = String(opts.baseUrl || process.env[BRAND.envBaseUrl] || DEFAULT_BASE_URL).replace(/\/+$/, '');
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.mode = opts.mode || undefined;
+    this.failMode = opts.failMode || 'open';
+    this.billingLapse = opts.billingLapse || 'open';
+    this.denyStatus = opts.denyStatus || 429;
+    // T18-P39: put the agent key's label (from a deny answer) in the 429 plan_limit_reached body and sentence.
+    // Labels are yours to choose; set false if they are internal names your callers shouldn't see.
+    if (opts.exposeKeyLabel !== undefined && typeof opts.exposeKeyLabel !== 'boolean') {
+      throw new TypeError(`${BRAND.name}: exposeKeyLabel must be true or false`);
+    }
+    this.exposeKeyLabel = opts.exposeKeyLabel === true; // Tyler (Oct 18 2026, via CoS): off by default; opt in with true.
+    this.onDecision = opts.onDecision || null;
+    this.onBillingInactive = opts.onBillingInactive || null;
+    // How often each kind of warning may be logged (fail-open/closed per error code,
+    // billing, rate limit, test limit). billingWarningIntervalMs is the old name.
+    this.billingWarningIntervalMs = opts.warningIntervalMs ?? opts.billingWarningIntervalMs ?? BILLING_WARNING_INTERVAL_MS;
+    this._now = opts.now || Date.now; // tests
+    this.onTestLimit = opts.onTestLimit || null;
+    this.onRateLimited = opts.onRateLimited || null;
+    this.onSafetyLimit = opts.onSafetyLimit || null;
+    this._warned = new Map(); // kind -> { at, suppressed }
+    this._dnsReported = new Set(); // hosts already reported as not resolving (loud once each)
+    this.logger = opts.logger === false ? null : (opts.logger || console);
+    this.fetch = opts.fetch || globalThis.fetch;
+    if (typeof this.fetch !== 'function') throw new Error(`${BRAND.name} needs Node 20+ (global fetch) or opts.fetch`);
+  }
+
+  /**
+   * Ask Ordainer whether this call may run. Never throws.
+   * @returns {Promise<DecideResult>}
+   */
+  async decide({ tool, apiKey, idempotencyKey, mode, failMode, billingLapse, retries } = {}) {
+    checkMode(mode, 'decide');
+    checkFailMode(failMode, 'decide');
+    checkBillingLapse(billingLapse, 'decide');
+    checkRetries(retries, 'decide');
+    const started = Date.now();
+    const key = apiKey ?? (typeof this.apiKey === 'function' ? undefined : this.apiKey);
+    const effectiveFailMode = failMode || this.failMode;
+    const effectiveBillingLapse = billingLapse || this.billingLapse;
+    const requestedMode = mode || this.mode;
+    const rawIdem = typeof idempotencyKey === 'number' ? String(idempotencyKey) : idempotencyKey;
+    const idem = typeof rawIdem === 'string' && rawIdem
+      ? idempotencyKeyFor(typeof tool === 'string' ? tool : '', rawIdem)
+      : (rawIdem || crypto.randomUUID());
+    const base = {
+      tool, idempotencyKey: idem, decision: null, reason: null, remaining: null, limit: null, resetsAt: null,
+      requestId: null, mode: requestedMode || null, wouldDeny: false, failOpen: false, failClosed: false,
+      error: null, denyStatus: this.denyStatus, billingInactive: false, testLimitReached: false,
+      rateLimited: false, retryAfterSec: null, rejected: false, replayed: false, attempts: 0, stickyDeny: false,
+      billingLapse: null, safetyLimited: false, label: null,
+    };
+
+    let result;
+    if (!key) {
+      result = this._rejected(base, { code: 'missing_key', message: `No ${BRAND.name} agent key (apiKey / ${BRAND.envKey}).` });
+    } else if (typeof tool !== 'string' || !tool) {
+      result = this._rejected(base, { code: 'invalid_request', message: 'tool is required.' });
+    } else {
+      // Retries reuse `idem`, so the server replays instead of counting again.
+      const maxAttempts = 1 + (retries ?? this.retries);
+      const budgetEnd = started + this.retryBudgetMs;
+      let timeoutMs = this.timeoutMs;
+      for (let attempt = 1; ; attempt += 1) {
+        result = await this._call(base, { key, tool, idem, requestedMode, effectiveFailMode, effectiveBillingLapse, timeoutMs });
+        result.attempts = attempt;
+        if (!result.retryable || attempt >= maxAttempts) break;
+        const pause = RETRY_DELAY_MS * 2 ** (attempt - 1);
+        const left = budgetEnd - Date.now() - pause;
+        if (left < MIN_ATTEMPT_MS) break; // out of budget: failMode applies now
+        timeoutMs = Math.min(this.timeoutMs, left);
+        await this._sleep(pause);
+      }
+      delete result.retryable;
+      result = this._applyStickyDeny(result, { key, tool, requestedMode });
+    }
+    result.latencyMs = Date.now() - started;
+    this._report(result);
+    return result;
+  }
+
+  async _call(base, { key, tool, idem, requestedMode, effectiveFailMode, effectiveBillingLapse = this.billingLapse, timeoutMs = this.timeoutMs }) {
+    let res;
+    try {
+      const body = { tool, idempotency_key: idem };
+      if (requestedMode) body.mode = requestedMode;
+      res = await this.fetch(`${this.baseUrl}/v1/decide`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json', 'User-Agent': BRAND.userAgent },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (err) {
+      const timedOut = err && (err.name === 'TimeoutError' || err.name === 'AbortError');
+      const dnsCode = timedOut ? null : dnsErrorCode(err);
+      const failure = this._failure(base, effectiveFailMode, {
+        code: timedOut ? 'timeout' : 'network_error',
+        message: timedOut ? `${BRAND.name} did not answer within ${timeoutMs}ms`
+          : dnsCode ? `${String(err && err.message)} (${dnsCode}: host ${this._host()} not found)` : String(err && err.message),
+      });
+      if (dnsCode) {
+        failure.error.dnsCode = dnsCode;
+        this._reportDns(dnsCode, effectiveFailMode);
+      }
+      failure.retryable = true;
+      return failure;
+    }
+    const header = (name) => (res.headers && typeof res.headers.get === 'function' ? res.headers.get(name) : null);
+    let json = null;
+    try {
+      json = await res.json();
+    } catch {
+      // fall through: treated as a failure below
+    }
+    if (res.status !== 200 || !json || (json.decision !== 'allow' && json.decision !== 'deny')) {
+      const env = json && json.error ? json.error : {};
+      const error = {
+        code: env.code || (res.status >= 500 ? 'server_error' : 'bad_response'),
+        message: env.message || `${BRAND.name} answered HTTP ${res.status}`,
+        status: res.status,
+        requestId: env.request_id || header('x-request-id') || null,
+      };
+      // H3: which limit a 429 came from ('per_key' | 'per_address'), from the server's
+      // error.limit_scope (or, from an older server, inferred from the code). Named
+      // limitScope, not limit: result.limit is the plan's cap (number | null).
+      if (res.status === 429) {
+        error.limitScope = LIMIT_SCOPES.has(env.limit_scope) ? env.limit_scope
+          : env.code === 'too_many_failed_auth' ? 'per_address' : env.code === 'rate_limited' ? 'per_key'
+            : env.code === CONCURRENCY_CODE ? 'per_key_concurrency' : env.code === SAFETY_LIMIT_CODE ? 'org_safety' : undefined;
+      }
+      // 1.2.0: 429 safety_limit_reached (shadow calls past the safety ceiling, 10x the account's monthly test limit) is a
+      // safety limit, not a deny: the call runs in ANY failMode, like billingLapse 'open'. Not failOpen (failMode didn't
+      // decide it), not rejected.
+      if (res.status === 429 && env.code === SAFETY_LIMIT_CODE) {
+        const secs = Number.parseInt(header('retry-after'), 10);
+        return {
+          ...base,
+          allowed: true,
+          failOpen: false,
+          failClosed: false,
+          safetyLimited: true,
+          reason: SAFETY_LIMIT_CODE,
+          resetsAt: typeof env.resets_at === 'string' ? env.resets_at : null,
+          retryAfterSec: Number.isFinite(secs) && secs > 0 ? secs : null,
+          requestId: error.requestId,
+          error: { code: error.code, message: error.message, status: error.status, limitScope: 'org_safety' },
+        };
+      }
+      // failMode covers "Ordainer couldn't answer" only: 5xx and malformed
+      // answers. A 4xx is Ordainer answering "no" (bad key, revoked, billing,
+      // rate limit, conflict): never an unchecked allow (QA S2).
+      const is4xx = res.status >= 400 && res.status < 500;
+      // Terms 10.3(b) (Option A, Tyler Oct 3): 403 subscription_inactive (the vendor's subscription is inactive)
+      // follows only the billing-lapse setting, never failMode.
+      const lapse = res.status === 403 && env.code === 'subscription_inactive';
+      const failure = lapse ? this._lapse(base, effectiveBillingLapse, error)
+        : is4xx ? this._rejected(base, error) : this._failure(base, effectiveFailMode, error);
+      // Only a 503 (decide_timeout, db_timeout, db_unavailable, an outage) is retried; a 500 or another 5xx is not.
+      if (res.status === 503) failure.retryable = true;
+      // Billing state, not an outage.
+      if (res.status === 403 && BILLING_CODES.has(env.code)) {
+        failure.billingInactive = true;
+        failure.reason = env.code;
+      }
+      // Per-key rate limit, not an outage; never silent. (The per-address
+      // too_many_failed_auth 429 is a bad key, not a rate problem: rejected, with
+      // its own warning; rateLimited stays false.)
+      // 429 concurrency_limited (QA round 3 M-1: too many decides in flight for this key)
+      // is the same kind of "slow down": blocked in any failMode, never a fail-open.
+      if (res.status === 429 && (env.code === 'rate_limited' || env.code === CONCURRENCY_CODE)) {
+        const raw = header('retry-after');
+        const secs = Number.parseInt(raw, 10);
+        failure.rateLimited = true;
+        failure.reason = env.code;
+        failure.retryAfterSec = Number.isFinite(secs) && secs > 0 ? secs : 1;
+      }
+      return failure;
+    }
+    const testLimitReached = json.decision === 'deny' && json.reason === TEST_LIMIT_REASON;
+    // test_limit_reached is Ordainer's own limit, not the plan's. From 1.2.0 the server answers it with mode 'shadow'
+    // for a shadow call (shadow never blocks: the call runs as a would-deny); anything else blocks (an older server
+    // answers mode 'enforce' even on a shadow plan).
+    const effectiveMode = testLimitReached ? (json.mode === 'shadow' ? 'shadow' : 'enforce')
+      : (json.mode === 'shadow' || json.mode === 'enforce' ? json.mode : (requestedMode || 'enforce'));
+    const denied = json.decision === 'deny';
+    // 1.2.2: wouldDeny means what the docs say, a shadow deny (Ordainer said deny and the call ran anyway). An enforce
+    // deny is a real deny: allowed false, wouldDeny false. 1.2.1 and earlier set it on every deny.
+    const wouldDeny = denied && effectiveMode === 'shadow';
+    return {
+      ...base,
+      testLimitReached,
+      allowed: !denied || effectiveMode === 'shadow',
+      decision: json.decision,
+      reason: json.reason,
+      remaining: json.remaining,
+      limit: json.limit,
+      resetsAt: json.resets_at,
+      requestId: json.request_id,
+      mode: effectiveMode,
+      wouldDeny,
+      // T18-P39: the server sends the key's label on denies only.
+      label: denied && this.exposeKeyLabel ? safeKeyLabel(json.label) : null,
+      // The server answered from a stored decision for this idempotency key (not counted again).
+      replayed: header('idempotent-replayed') === 'true',
+    };
+  }
+
+  // Sticky deny: remember a quota_exceeded deny per (key, tool); a later would-be fail-open for the pair is denied.
+  _applyStickyDeny(result, { key, tool, requestedMode }) {
+    if (!this.stickyDenyMs) return result;
+    const id = `${crypto.createHash('sha256').update(String(key)).digest('hex').slice(0, 32)}\u0000${tool}`;
+    const now = this._now();
+    if (result.decision === 'deny' && result.reason === 'quota_exceeded') {
+      const resets = result.resetsAt ? Date.parse(result.resetsAt) : NaN;
+      const until = Math.min(now + this.stickyDenyMs, Number.isFinite(resets) ? resets : Infinity);
+      if (until > now) {
+        this._sticky.delete(id);
+        if (this._sticky.size >= MAX_STICKY_ENTRIES) {
+          for (const [k, v] of this._sticky) if (v.until <= now) this._sticky.delete(k);
+          if (this._sticky.size >= MAX_STICKY_ENTRIES) this._sticky.delete(this._sticky.keys().next().value);
+        }
+        this._sticky.set(id, { until, mode: result.mode, limit: result.limit, resetsAt: result.resetsAt, label: result.label });
+      }
+      return result;
+    }
+    if (result.decision === 'allow') {
+      this._sticky.delete(id);
+      return result;
+    }
+    if (!result.failOpen || result.billingInactive) return result;
+    const entry = this._sticky.get(id);
+    if (!entry) return result;
+    if (entry.until <= now) {
+      this._sticky.delete(id);
+      return result;
+    }
+    const shadow = requestedMode === 'shadow' || (!requestedMode && entry.mode === 'shadow');
+    if (shadow) return { ...result, stickyDeny: true, wouldDeny: true, mode: 'shadow', label: entry.label || null }; // still runs, reported
+    return {
+      ...result,
+      allowed: false,
+      failOpen: false,
+      stickyDeny: true,
+      wouldDeny: false, // 1.2.2: blocked, so a real deny, not a would-deny
+      reason: 'quota_exceeded',
+      remaining: 0,
+      limit: entry.limit,
+      resetsAt: entry.resetsAt,
+      label: entry.label || null,
+      mode: 'enforce',
+    };
+  }
+
+  // Ordainer answered with a 4xx (or the call can't be made: no key, no tool).
+  // Blocked whatever failMode says: these are answers, not outages. G5:
+  // failClosed stays false (failMode didn't decide this); rejected says why.
+  _rejected(base, error) {
+    return {
+      ...base,
+      allowed: false,
+      failOpen: false,
+      failClosed: false,
+      rejected: true,
+      requestId: error.requestId || null,
+      error: { code: error.code, message: error.message, status: error.status, ...(error.limitScope ? { limitScope: error.limitScope } : {}) },
+    };
+  }
+
+  // 403 subscription_inactive under the billing-lapse setting. 'open': the call runs, unchecked (allowed, but not
+  // failOpen: failMode didn't decide it). 'closed': blocked like a rejection (403 plan_check_rejected, no Retry-After).
+  _lapse(base, billingLapse, error) {
+    const result = billingLapse === 'closed' ? this._rejected(base, error) : {
+      ...base,
+      allowed: true,
+      failOpen: false,
+      failClosed: false,
+      requestId: error.requestId || null,
+      error: { code: error.code, message: error.message, status: error.status },
+    };
+    result.billingLapse = billingLapse;
+    return result;
+  }
+
+  _failure(base, failMode, error) {
+    return {
+      ...base,
+      allowed: failMode === 'open',
+      failOpen: failMode === 'open',
+      failClosed: failMode === 'closed',
+      requestId: error.requestId || null,
+      error: { code: error.code, message: error.message, status: error.status },
+    };
+  }
+
+  _report(result) {
+    if (result.safetyLimited) {
+      this._reportSafetyLimit(result);
+    } else if (result.billingInactive) {
+      this._reportBillingInactive(result);
+    } else if (result.rateLimited) {
+      this._reportRateLimited(result);
+    } else if (result.error && result.error.limitScope === 'per_address') {
+      this._reportFailedAuth(result);
+    } else if (result.testLimitReached) {
+      this._reportTestLimit(result);
+    } else if (this.logger) {
+      if (result.stickyDeny) {
+        this._rateLimitedWarn(`sticky_deny:${result.error.code}`, () => `${BRAND.logPrefix} sticky deny: ${result.error.code} while tool=${result.tool} was at its plan limit`
+          + ` (quota_exceeded within the last ${Math.round(this.stickyDenyMs / 1000)}s): `
+          + (result.allowed ? 'shadow, call allowed (would deny)' : 'call blocked (429 plan_limit_reached), not failed open')
+          + ` X-Request-Id=${result.requestId || 'none'}`);
+      } else if (result.error) {
+        // One line per failure mode and error code per interval (an outage would
+        // otherwise log once per call), with the suppressed count.
+        const kind = `${result.rejected ? 'rejected' : result.failOpen ? 'fail_open' : 'fail_closed'}:${result.error.code}`;
+        const what = result.rejected ? 'rejected (call blocked in any failMode)'
+          : result.failOpen ? 'fail-open (call allowed)' : 'fail-closed (call blocked)';
+        // N4: with X-Request-Id, like the billing and rate-limit lines, so Support can match the server's log line.
+        this._rateLimitedWarn(kind, () => `${BRAND.logPrefix} ${what}: ${result.error.code}: ${result.error.message} X-Request-Id=${result.requestId || 'none'} tool=${result.tool}`);
+      } else if (result.wouldDeny && result.mode === 'shadow') {
+        this.logger.warn(`${BRAND.logPrefix} shadow: would deny tool=${result.tool}${result.label ? ` label=${JSON.stringify(result.label)}` : ''} reason=${result.reason} remaining=${result.limit === null ? 'no cap' : `${result.remaining}/${result.limit}`} request_id=${result.requestId} (call allowed)`);
+      }
+    }
+    callHook(this.onDecision, result);
+  }
+
+  // At most one warning of each kind per billingWarningIntervalMs (default: once
+  // a minute), with a count of what was suppressed, so the logs say what's going
+  // on without flooding.
+  _rateLimitedWarn(kind, build) {
+    if (!this.logger) return;
+    const now = this._now();
+    const state = this._warned.get(kind);
+    if (state && now - state.at < this.billingWarningIntervalMs) {
+      state.suppressed += 1;
+      return;
+    }
+    const suppressed = state ? state.suppressed : 0;
+    this._warned.set(kind, { at: now, suppressed: 0 });
+    this.logger.warn(build()
+      + (suppressed ? ` (${suppressed} more since the last warning)` : '')
+      + ` (next warning in ${Math.round(this.billingWarningIntervalMs / 1000)}s at most)`);
+  }
+
+  _reportBillingInactive(result) {
+    callHook(this.onBillingInactive, result);
+    if (result.reason === 'subscription_required') {
+      // H3: its own wording (never "subscription inactive"): the account has never paid.
+      this._rateLimitedWarn('billing', () => `${BRAND.logPrefix} subscription required: this ${BRAND.name} account has no paid subscription yet, so its live key gets 403 subscription_required.`
+        + ` This is a billing state, not an outage. Calls with this live key are blocked in any failMode (test keys still work).`
+        + ` Subscribe in the ${BRAND.name} console under Billing. X-Request-Id=${result.requestId || 'none'} tool=${result.tool}`);
+      return;
+    }
+    // Terms 10.3(b): subscription_inactive follows the billing-lapse setting, not failMode.
+    const doing = result.allowed
+      ? "Calls are being let through, unchecked, because billingLapse is 'open' (the default)"
+      : "Calls are being blocked (403 plan_check_rejected) because billingLapse is 'closed'";
+    // QA CC-L3 (Oct 6): UI/UX-approved wording, exactly; the "doing" clause (what the SDK did with the call) sits
+    // right after the first sentence. The "subscription inactive:" tag and the X-Request-Id/tool fields are log
+    // fields, not wording. Pinned in test/sdk.test.js (BILLING_INACTIVE_WARNING).
+    this._rateLimitedWarn('billing', () => `${BRAND.logPrefix} subscription inactive: ${BRAND.name} refused this live key because of a billing problem on your account.`
+      + ` ${doing}.`
+      + ` To fix this, sign in to the ${BRAND.name} console and open Billing. If Billing shows an unpaid invoice, pay it and these same live keys turn back on. If your subscription has ended, subscribe again under Billing, then issue new live keys under Keys.`
+      + ` X-Request-Id=${result.requestId || 'none'} tool=${result.tool}`);
+  }
+
+  _reportRateLimited(result) {
+    callHook(this.onRateLimited, result);
+    const doing = 'Calls are being blocked (429 rate_limited) in any failMode';
+    if (result.reason === CONCURRENCY_CODE) {
+      this._rateLimitedWarn('concurrency', () => `${BRAND.logPrefix} concurrency limited: this agent key has too many plan checks in flight at once (${BRAND.name}'s per-key concurrency limit, 429 ${CONCURRENCY_CODE}).`
+        + ` This is a rate limit, not an outage. ${doing}. Send fewer calls in parallel: retry after ${result.retryAfterSec}s.`
+        + ` X-Request-Id=${result.requestId || 'none'} tool=${result.tool}`);
+      return;
+    }
+    this._rateLimitedWarn('rate_limit', () => `${BRAND.logPrefix} rate limited: this agent key is over ${BRAND.name}'s per-key request limit (429 rate_limited).`
+      + ` This is a rate limit, not an outage. ${doing}. Slow down: retry after ${result.retryAfterSec}s.`
+      + ` X-Request-Id=${result.requestId || 'none'} tool=${result.tool}`);
+  }
+
+  // H3: the per-address limit (429 too_many_failed_auth). Never "per-key": it fires
+  // only for missing or unrecognized keys, so the fix is the key, not the traffic.
+  _reportFailedAuth(result) {
+    this._rateLimitedWarn('failed_auth', () => `${BRAND.logPrefix} rejected (call blocked in any failMode): too many requests with a missing or unrecognized agent key from this server's address`
+      + ` (${BRAND.name}'s per-address limit, 429 ${result.error.code}). Check the agent key (apiKey / ${BRAND.envKey}); calls with a valid key are not affected by this limit.`
+      + ` X-Request-Id=${result.requestId || 'none'} tool=${result.tool}`);
+  }
+
+  _reportTestLimit(result) {
+    callHook(this.onTestLimit, result);
+    if (result.allowed) {
+      // Shadow (1.2.0): the call ran; the server counted it and recorded a would-deny.
+      this._rateLimitedWarn('test_limit_shadow', () => `${BRAND.logPrefix} test limit reached (shadow): this ${BRAND.name} account has used its free test-key decisions for this month (UTC).`
+        + ' Shadow calls keep running: each is counted and recorded as would deny test_limit_reached, up to a safety ceiling of 10 times the limit (then 429 safety_limit_reached, and calls still run).'
+        + ` Enforce calls with test keys are blocked until ${result.resetsAt || 'the 1st of next month'}. Live keys are not affected.`
+        + ` X-Request-Id=${result.requestId || 'none'} tool=${result.tool}`);
+      return;
+    }
+    this._rateLimitedWarn('test_limit', () => `${BRAND.logPrefix} test limit reached: this ${BRAND.name} account has used its free test-key decisions for this month (UTC).`
+      + ` Calls with test keys are being blocked (429 test_limit_reached) until ${result.resetsAt || 'the 1st of next month'}, in enforce mode and regardless of failMode (shadow calls still run).`
+      + ` This is a sandbox limit, not an outage and not your customer's plan. Live keys are not affected.`
+      + ` X-Request-Id=${result.requestId || 'none'} tool=${result.tool}`);
+  }
+
+  // 1.2.0: 429 safety_limit_reached. The call ran (any failMode); one warning per warningIntervalMs.
+  _reportSafetyLimit(result) {
+    callHook(this.onSafetyLimit, result);
+    this._rateLimitedWarn('safety_limit', () => `${BRAND.logPrefix} safety limit reached: this ${BRAND.name} account passed the safety ceiling for shadow calls (10 times its monthly test limit; 429 ${SAFETY_LIMIT_CODE}).`
+      + ` This is a safety limit, not a deny: calls are being let through, unchecked and not recorded, in any failMode, until ${result.resetsAt || 'the start of next month (UTC)'}.`
+      + ` X-Request-Id=${result.requestId || 'none'} tool=${result.tool}`);
+  }
+
+  _host() {
+    try {
+      return new URL(this.baseUrl).host;
+    } catch {
+      return this.baseUrl;
+    }
+  }
+
+  // The configured base URL's host doesn't resolve. Loud (error level, never throttled) the first time per host per
+  // instance: it is almost always a typo or a missing ORDAINER_BASE_URL, and failing open would otherwise hide it behind
+  // the once-a-minute fail-open warning. Later calls fall back to that normal (throttled) warning.
+  _reportDns(code, failMode) {
+    const host = this._host();
+    if (!this.logger || this._dnsReported.has(host)) return;
+    this._dnsReported.add(host);
+    const line = `${BRAND.logPrefix} ERROR: cannot resolve the ${BRAND.name} API host "${host}" (${code}) from baseUrl ${this.baseUrl}.`
+      + ` Check the URL and set ${BRAND.envBaseUrl} (or the baseUrl option) to your ${BRAND.name} API URL.`
+      + ` Until then every plan check fails: calls are ${failMode === 'closed' ? 'blocked (failMode \'closed\')' : 'let through unchecked (failMode \'open\')'}.`;
+    (typeof this.logger.error === 'function' ? this.logger.error : this.logger.warn).call(this.logger, line);
+  }
+
+  /**
+   * Express/Connect-style middleware (also works with plain http handlers that call next).
+   * Sets req.ordainer to the result. On a blocked call it answers 429/402/403/500/503 itself,
+   * or calls opts.onDeny(req, res, result) if given.
+   * opts.denyStatus (429 or 402) overrides the client's denyStatus for this route's quota denies.
+   *
+   * opts.tool, opts.apiKey, opts.idempotencyKey may be values or (req) => value (sync or async).
+   * Default idempotency key: a fresh random key per incoming request. The incoming
+   * request's Idempotency-Key header is NEVER forwarded: the agent controls it, and
+   * replaying one key would get one stored allow many times without counting (QA S1).
+   * Pass idempotencyKey(req) only from your own trusted data (e.g. your job id),
+   * one key per real operation. Keys over 255 characters are hashed (idempotencyKeyFor).
+   */
+  middleware(opts = {}) {
+    checkMode(opts.mode, 'middleware');
+    checkFailMode(opts.failMode, 'middleware');
+    checkBillingLapse(opts.billingLapse, 'middleware');
+    checkDenyStatus(opts.denyStatus, 'middleware');
+    checkRetries(opts.retries, 'middleware');
+    if (!opts.tool) throw new TypeError('middleware: tool is required');
+    return (req, res, next) => {
+      (async () => {
+        const tool = await resolve(opts.tool, req);
+        const apiKey = await resolve(opts.apiKey ?? this.apiKey, req);
+        // Vendor-supplied only (trusted data). Never req.headers['idempotency-key'].
+        const idempotencyKey = await resolve(opts.idempotencyKey, req);
+        const result = await this.decide({ tool, apiKey, idempotencyKey, mode: opts.mode, failMode: opts.failMode, billingLapse: opts.billingLapse, retries: opts.retries });
+        if (opts.denyStatus) result.denyStatus = opts.denyStatus;
+        req.ordainer = result;
+        if (result.allowed) return next();
+        if (opts.onDeny) return opts.onDeny(req, res, result);
+        sendDeny(res, result);
+      })().catch(next);
+    };
+  }
+
+  /**
+   * Wrap a plain async function. The wrapped function runs only if allowed;
+   * otherwise it throws OrdainerDeniedError (or returns opts.onDeny(result, ...args)).
+   * opts.tool / opts.apiKey / opts.idempotencyKey may be values or (...args) => value.
+   */
+  wrap(fn, opts = {}) {
+    checkMode(opts.mode, 'wrap');
+    checkFailMode(opts.failMode, 'wrap');
+    checkBillingLapse(opts.billingLapse, 'wrap');
+    checkRetries(opts.retries, 'wrap');
+    if (!opts.tool) throw new TypeError('wrap: tool is required');
+    const self = this;
+    return async function ordainerWrapped(...args) {
+      const result = await self.decide({
+        tool: await resolve(opts.tool, ...args),
+        apiKey: await resolve(opts.apiKey ?? self.apiKey, ...args),
+        idempotencyKey: await resolve(opts.idempotencyKey, ...args),
+        mode: opts.mode,
+        failMode: opts.failMode,
+        billingLapse: opts.billingLapse,
+        retries: opts.retries,
+      });
+      if (result.allowed) return fn.apply(this, args);
+      if (opts.onDeny) return opts.onDeny(result, ...args);
+      throw new OrdainerDeniedError(result);
+    };
+  }
+}
+
+module.exports = { Ordainer, OrdainerDeniedError, denyResponse, safeKeyLabel, MAX_LABEL_LENGTH, rejectedMessage, sendDeny, idempotencyKeyFor, DEFAULT_TIMEOUT_MS, BILLING_WARNING_INTERVAL_MS, TEST_LIMIT_REASON, SAFETY_LIMIT_CODE, MAX_IDEMPOTENCY_LEN, MAX_RETRIES, BRAND, BILLING_BLOCKED_MESSAGE, RATE_LIMITED_MESSAGE, CONCURRENCY_LIMITED_MESSAGE };