@farthershore/backend 0.19.0 → 0.21.0

package/dist/testing/index.js

@@ -1,8 +1,13 @@
 import { createRequire as __createRequire } from "node:module";const require=__createRequire(import.meta.url);
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -189,20 +194,6 @@ var init_reconcile = __esm({
 import { generateKeyPairSync, randomBytes } from "node:crypto";
 
 // src/generated/runtime-contract.ts
-var RUNTIME_BODY_HASH_CONTRACT = {
-  algorithm: "SHA-256",
-  encoding: "hex-lower",
-  source: "raw-request-bytes",
-  emptyBodyHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-  maxBodyBytes: 10485760,
-  streamingExemptToken: "STREAM",
-  streamingExemptContentTypes: [
-    "text/event-stream",
-    "application/octet-stream",
-    "multipart/form-data"
-  ],
-  overMaxStatus: 413
-};
 var RUNTIME_ERROR_CODES = {
   missingSignature: "missing_signature",
   malformedSignature: "malformed_signature",
@@ -223,6 +214,20 @@ var RUNTIME_ERROR_CODES = {
   serviceSubjectRequired: "service_subject_required",
   surfaceNotAllowed: "surface_not_allowed"
 };
+var RUNTIME_BODY_HASH_CONTRACT = {
+  algorithm: "SHA-256",
+  encoding: "hex-lower",
+  source: "raw-request-bytes",
+  emptyBodyHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  maxBodyBytes: 10485760,
+  streamingExemptToken: "STREAM",
+  streamingExemptContentTypes: [
+    "text/event-stream",
+    "application/octet-stream",
+    "multipart/form-data"
+  ],
+  overMaxStatus: 413
+};
 var RUNTIME_RESPONSE_METERING_CONTRACT = {
   headers: {
     payload: "x-fs-metering",
@@ -243,14 +248,18 @@ var RUNTIME_RESPONSE_METERING_CONTRACT = {
   payload: {
     method: "string",
     path: "string",
-    rawDimsUnits: "Record<string, number>",
+    rawDimsUnits: "Record<string, number>?",
     measureContext: "Record<string, unknown>?",
-    creditUnitsConsumed: "Record<string, number>?"
+    creditUnitsConsumed: "Record<string, number>?",
+    measurementsVersion: "1?",
+    measurements: "Array<{ meter: string; values: Record<string, number>; dims?: Record<string, string> }>?",
+    quote: "{ currency: string; amountNanos: string }?"
   },
   errors: {
     missingToken: "missing_token",
     invalidMeterKey: "invalid_meter_key",
-    invalidMeterValue: "invalid_meter_value"
+    invalidMeterValue: "invalid_meter_value",
+    invalidQuote: "invalid_quote"
   },
   httpAdapter: {
     input: "Request",
@@ -452,16 +461,106 @@ function statusForCode(code) {
   return 401;
 }
 
+// src/core/deadline.ts
+var DEADLINE_MS = {
+  /** Boot-blocking; generous because it runs once and gates startup. */
+  bootstrap: 1e4,
+  /** On the inbound verification path — must not hold a request open. */
+  jwks: 5e3,
+  /** Background economic report, retried by the caller. */
+  metering: 1e4,
+  /** Background attested usage callback. */
+  postStreamUsage: 1e4,
+  /** Best-effort heartbeat; never blocks anything. */
+  health: 5e3,
+  /** Boot-time route drift report; fail-open at the caller. */
+  report: 1e4
+};
+var MAX_RESPONSE_BYTES = 1048576;
+var ResponseTooLargeError = class extends Error {
+  constructor(limit) {
+    super(`response body exceeded ${limit} bytes and was cancelled`);
+    this.name = "ResponseTooLargeError";
+  }
+};
+var DeadlineExceededError = class extends Error {
+  operation;
+  constructor(operation, timeoutMs) {
+    super(`${operation} exceeded its ${timeoutMs}ms deadline`);
+    this.name = "TimeoutError";
+    this.operation = operation;
+  }
+};
+async function fetchWithDeadline(fetchImpl, input, init, operation, options = {}) {
+  const timeoutMs = options.timeoutMs ?? DEADLINE_MS[operation];
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const signal = options.callerSignal ? AbortSignal.any([options.callerSignal, timeout]) : timeout;
+  try {
+    return await fetchImpl(input, { ...init, signal });
+  } catch (cause) {
+    if (options.callerSignal?.aborted) throw cause;
+    if (timeout.aborted) throw new DeadlineExceededError(operation, timeoutMs);
+    throw cause;
+  }
+}
+async function readBoundedText(response, limit = MAX_RESPONSE_BYTES) {
+  const body = response.body;
+  if (!body) {
+    const text = await response.text();
+    if (byteLength(text) > limit) throw new ResponseTooLargeError(limit);
+    return text;
+  }
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      total += value.byteLength;
+      if (total > limit) {
+        await reader.cancel();
+        throw new ResponseTooLargeError(limit);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const joined = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    joined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(joined);
+}
+async function readBoundedJson(response, limit = MAX_RESPONSE_BYTES) {
+  return JSON.parse(await readBoundedText(response, limit));
+}
+function byteLength(text) {
+  return new TextEncoder().encode(text).byteLength;
+}
+
 // src/core/jwks.ts
 var DEFAULT_CACHE_TTL_MS = 5 * 6e4;
+var DEFAULT_HARD_STALE_MS = 15 * 6e4;
 var DEFAULT_NEGATIVE_CACHE_MS = 3e4;
+function finiteMsOr(value, fallback) {
+  if (value === void 0) return fallback;
+  if (!Number.isFinite(value) || value < 0) return fallback;
+  return value;
+}
 var MAX_NEGATIVE_KIDS = 1e3;
 var JwksClient = class {
   jwksUrl;
   fetchImpl;
   cacheTtlMs;
+  hardStaleMs;
   negativeCacheMs;
   now;
+  onObservation;
   keysByKid = /* @__PURE__ */ new Map();
   fetchedAt = 0;
   hasFetchedOnce = false;
@@ -470,21 +569,34 @@ var JwksClient = class {
   constructor(options) {
     this.jwksUrl = options.jwksUrl;
     this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
-    this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    this.cacheTtlMs = finiteMsOr(options.cacheTtlMs, DEFAULT_CACHE_TTL_MS);
+    this.hardStaleMs = Math.max(
+      finiteMsOr(options.hardStaleMs, DEFAULT_HARD_STALE_MS),
+      this.cacheTtlMs
+    );
     this.negativeCacheMs = options.negativeCacheMs ?? DEFAULT_NEGATIVE_CACHE_MS;
     this.now = options.now ?? (() => Date.now());
+    this.onObservation = options.onObservation;
   }
   /**
    * Resolve a public JWK for `kid`, fail-closed. Throws FartherShoreError with
-   * `jwks_unavailable` (cold cache + fetch failed) or `unknown_key_id`.
+   * `jwks_unavailable` (cold cache, or a hard-stale cache whose refresh is
+   * failing) or `unknown_key_id`.
    */
   async getKey(kid) {
     const cached = this.keysByKid.get(kid);
-    if (cached && !this.isStale()) return cached;
+    if (cached && !this.isStale()) {
+      this.observe("fresh", kid);
+      return cached;
+    }
     const negAt = this.negativeKids.get(kid);
     if (negAt !== void 0 && this.now() - negAt < this.negativeCacheMs) {
       const warm = this.keysByKid.get(kid);
-      if (warm) return warm;
+      if (warm) {
+        this.assertWithinHardStale();
+        this.observe(this.cacheState(), kid);
+        return warm;
+      }
       throw new FartherShoreError(
         "unknown_key_id",
         `signing key '${kid}' is not present in the JWKS`
@@ -494,6 +606,7 @@ var JwksClient = class {
     const key2 = this.keysByKid.get(kid);
     if (key2) {
       this.negativeKids.delete(kid);
+      this.observe(this.cacheState(), kid);
       return key2;
     }
     this.rememberMissingKid(kid);
@@ -513,8 +626,37 @@ var JwksClient = class {
     }
     this.negativeKids.set(kid, this.now());
   }
+  ageMs() {
+    return this.now() - this.fetchedAt;
+  }
   isStale() {
-    return this.now() - this.fetchedAt >= this.cacheTtlMs;
+    return this.ageMs() >= this.cacheTtlMs;
+  }
+  isHardStale() {
+    return this.ageMs() >= this.hardStaleMs;
+  }
+  /** Current freshness of the cached key set. */
+  cacheState() {
+    if (!this.hasFetchedOnce) return "cold";
+    if (this.isHardStale()) return "hard_stale";
+    if (this.isStale()) return "soft_stale";
+    return "fresh";
+  }
+  observe(state, kid) {
+    this.onObservation?.({
+      state,
+      ageMs: this.hasFetchedOnce ? this.ageMs() : 0,
+      ...kid !== void 0 ? { kid } : {}
+    });
+  }
+  /** Fail closed when the cached key set is past the hard-stale ceiling. */
+  assertWithinHardStale() {
+    if (!this.isHardStale()) return;
+    this.observe("hard_stale");
+    throw new FartherShoreError(
+      "jwks_unavailable",
+      `JWKS key set is ${Math.round(this.ageMs() / 1e3)}s old, past the ${Math.round(this.hardStaleMs / 1e3)}s hard-stale limit, and cannot be refreshed; refusing to vouch for keys that may have been revoked`
+    );
   }
   /** Single-flight refresh: concurrent callers share one fetch. */
   async refresh() {
@@ -527,24 +669,27 @@ var JwksClient = class {
   async doFetch() {
     let response;
     try {
-      response = await this.fetchImpl(this.jwksUrl, {
-        headers: { accept: "application/json" }
-      });
+      response = await fetchWithDeadline(
+        this.fetchImpl,
+        this.jwksUrl,
+        { headers: { accept: "application/json" } },
+        "jwks"
+      );
     } catch (cause) {
-      this.failOnColdCache(cause);
+      this.handleRefreshFailure(cause);
       return;
     }
     if (!response.ok) {
-      this.failOnColdCache(
+      this.handleRefreshFailure(
         new Error(`JWKS endpoint returned HTTP ${response.status}`)
       );
       return;
     }
     let doc;
     try {
-      doc = await response.json();
+      doc = await readBoundedJson(response);
     } catch (cause) {
-      this.failOnColdCache(cause);
+      this.handleRefreshFailure(cause);
       return;
     }
     const next = /* @__PURE__ */ new Map();
@@ -557,15 +702,27 @@ var JwksClient = class {
     this.negativeKids.clear();
   }
   /**
-   * Stale-while-revalidate: with a warm cache, swallow the refresh failure and
-   * keep serving the last-known keys. With a COLD cache, fail closed.
+   * BOUNDED stale-while-revalidate. A COLD cache fails closed. A warm cache
+   * inside the soft window swallows the failure and keeps serving. Past the
+   * hard-stale ceiling it fails closed too — availability is worth a bounded
+   * window of degraded trust, not an unbounded one.
    */
-  failOnColdCache(cause) {
-    if (this.hasFetchedOnce) return;
-    throw new FartherShoreError(
-      "jwks_unavailable",
-      `JWKS unavailable on a cold cache: ${stringifyCause(cause)}`
-    );
+  handleRefreshFailure(cause) {
+    if (!this.hasFetchedOnce) {
+      this.observe("cold");
+      throw new FartherShoreError(
+        "jwks_unavailable",
+        `JWKS unavailable on a cold cache: ${stringifyCause(cause)}`
+      );
+    }
+    if (this.isHardStale()) {
+      this.observe("hard_stale");
+      throw new FartherShoreError(
+        "jwks_unavailable",
+        `JWKS refresh failed and the cached key set is ${Math.round(this.ageMs() / 1e3)}s old, past the ${Math.round(this.hardStaleMs / 1e3)}s hard-stale limit: ${stringifyCause(cause)}`
+      );
+    }
+    this.observe("soft_stale");
   }
 };
 function stringifyCause(cause) {
@@ -968,6 +1125,7 @@ import { dirname as dirname2 } from "node:path";
 // src/core/bootstrap.ts
 var BOOTSTRAP_PATH = "/v1/runtime/bootstrap";
 var DEFAULT_MIN_REFRESH_SECONDS = 30;
+var DEFAULT_MAX_STALE_SECONDS = 300;
 var BootstrapClient = class {
   runtimeToken;
   endpoint;
@@ -975,6 +1133,7 @@ var BootstrapClient = class {
   fetchImpl;
   now;
   minRefreshSeconds;
+  maxStaleMs;
   cached = null;
   fetchedAt = 0;
   refreshAfterMs = 0;
@@ -998,6 +1157,7 @@ var BootstrapClient = class {
     this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
     this.now = options.now ?? (() => Date.now());
     this.minRefreshSeconds = options.minRefreshSeconds ?? DEFAULT_MIN_REFRESH_SECONDS;
+    this.maxStaleMs = (options.maxStaleSeconds ?? DEFAULT_MAX_STALE_SECONDS) * 1e3;
   }
   /** Cached config when fresh; otherwise refreshes. */
   async get() {
@@ -1019,20 +1179,37 @@ var BootstrapClient = class {
   isStale() {
     return this.now() - this.fetchedAt >= this.refreshAfterMs;
   }
+  isHardStale() {
+    return this.now() - this.fetchedAt >= this.maxStaleMs;
+  }
+  cachedOrThrowOnHardStale(reason) {
+    if (this.cached && !this.isHardStale()) return this.cached;
+    throw new FartherShoreError(
+      "jwks_unavailable",
+      `bootstrap refresh failed with stale cached authorization metadata: ${reason}`
+    );
+  }
   async doBootstrap() {
     let response;
     try {
-      response = await this.fetchImpl(this.endpoint, {
-        method: "POST",
-        headers: {
-          authorization: `Bearer ${this.runtimeToken}`,
-          "content-type": "application/json",
-          accept: "application/json"
+      response = await fetchWithDeadline(
+        this.fetchImpl,
+        this.endpoint,
+        {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${this.runtimeToken}`,
+            "content-type": "application/json",
+            accept: "application/json"
+          },
+          body: JSON.stringify(this.request)
         },
-        body: JSON.stringify(this.request)
-      });
+        "bootstrap"
+      );
     } catch (cause) {
-      if (this.cached) return this.cached;
+      if (this.cached) {
+        return this.cachedOrThrowOnHardStale(stringify(cause));
+      }
       throw new FartherShoreError(
         "jwks_unavailable",
         `bootstrap request failed: ${stringify(cause)}`
@@ -1045,13 +1222,15 @@ var BootstrapClient = class {
       );
     }
     if (!response.ok) {
-      if (this.cached) return this.cached;
+      if (this.cached) {
+        return this.cachedOrThrowOnHardStale(`HTTP ${response.status}`);
+      }
       throw new FartherShoreError(
         "jwks_unavailable",
         `bootstrap returned HTTP ${response.status}`
       );
     }
-    const body = await response.json();
+    const body = await readBoundedJson(response);
     this.cached = body;
     this.fetchedAt = this.now();
     const refreshSeconds = Math.max(
@@ -1084,197 +1263,28 @@ async function reportHealth(options) {
   const fetchImpl = options.fetchImpl ?? globalThis.fetch;
   const endpoint = `${options.coreUrl.replace(/\/+$/, "")}${HEALTH_PATH}`;
   try {
-    const response = await fetchImpl(endpoint, {
-      method: "POST",
-      headers: {
-        authorization: `Bearer ${options.runtimeToken}`,
-        "content-type": "application/json"
+    const response = await fetchWithDeadline(
+      fetchImpl,
+      endpoint,
+      {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${options.runtimeToken}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify({
+          status: options.status,
+          ...options.instanceId ? { instanceId: options.instanceId } : {}
+        })
       },
-      body: JSON.stringify({
-        status: options.status,
-        ...options.instanceId ? { instanceId: options.instanceId } : {}
-      })
-    });
+      "health"
+    );
     return response.ok;
   } catch {
     return false;
   }
 }
 
-// src/core/backoff.ts
-function computeBackoff(attempt, options) {
-  const { baseMs, maxMs, jitter = "equal", random = Math.random } = options;
-  const exponent = Math.max(0, attempt - 1);
-  const cap = Math.min(baseMs * 2 ** exponent, maxMs);
-  switch (jitter) {
-    case "none":
-      return cap;
-    case "full":
-      return random() * cap;
-    case "equal":
-    default:
-      return cap / 2 + random() * (cap / 2);
-  }
-}
-
-// src/core/metering.ts
-var METER_KEY_RE = /^[a-z0-9_]{1,64}$/;
-var DEFAULT_BASE_DELAY_MS = 200;
-var DEFAULT_MAX_DELAY_MS = 1e4;
-function isTransientStatus(status) {
-  return status === 429 || status >= 500;
-}
-function retryAfterMs(headers) {
-  const raw = headers.get("retry-after");
-  if (raw === null) return null;
-  const trimmed = raw.trim();
-  if (!/^\d+$/.test(trimmed)) return null;
-  const secs = Number(trimmed);
-  return Number.isFinite(secs) ? secs * 1e3 : null;
-}
-var DEFAULT_MAX_RETRIES = 3;
-var MeteringClient = class {
-  config;
-  endpoint;
-  businessId;
-  backendId;
-  fetchImpl;
-  maxRetries;
-  baseDelayMs;
-  maxDelayMs;
-  sleep;
-  random;
-  newId;
-  now;
-  buffer = [];
-  constructor(options) {
-    this.config = options.config;
-    this.endpoint = resolveEndpoint(options.config.endpoint, options.coreUrl);
-    this.businessId = options.businessId;
-    this.backendId = options.backendId;
-    this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
-    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
-    this.baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
-    this.maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
-    this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-    this.random = options.random ?? Math.random;
-    this.newId = options.newId ?? (() => crypto.randomUUID());
-    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
-  }
-  /**
-   * Record `qty` of `meter`. Enforces meter-key shape, non-negative finite qty,
-   * the bootstrap allowedMeters/allowedRoutes scope, and the per-event sanity
-   * max, then enqueues and flushes (best-effort; failures stay buffered).
-   */
-  async meter(meter, qty, options = {}) {
-    if (!this.config.enabled) {
-      throw new FartherShoreError(
-        "invalid_token",
-        "metering is not enabled for this runtime token"
-      );
-    }
-    if (!METER_KEY_RE.test(meter)) {
-      throw new FartherShoreError(
-        "invalid_token",
-        `meter key '${meter}' must be lowercase alphanumeric with underscores`
-      );
-    }
-    if (!Number.isFinite(qty) || qty < 0) {
-      throw new FartherShoreError(
-        "invalid_token",
-        `meter '${meter}' qty must be a non-negative finite number`
-      );
-    }
-    if (this.config.allowedMeters.length > 0 && !this.config.allowedMeters.includes(meter)) {
-      throw new FartherShoreError(
-        "invalid_token",
-        `meter '${meter}' is not in the token's allowedMeters`
-      );
-    }
-    if (this.config.allowedRoutes.length > 0) {
-      if (!options.routeId) {
-        throw new FartherShoreError(
-          "invalid_token",
-          "routeId is required because this runtime token is route-scoped"
-        );
-      }
-      if (!this.config.allowedRoutes.includes(options.routeId)) {
-        throw new FartherShoreError(
-          "invalid_token",
-          `route '${options.routeId}' is not in the token's allowedRoutes`
-        );
-      }
-    }
-    if (this.config.perEventMax > 0 && qty > this.config.perEventMax) {
-      throw new FartherShoreError(
-        "invalid_token",
-        `meter '${meter}' qty ${qty} exceeds the per-event max ${this.config.perEventMax}`
-      );
-    }
-    const event = {
-      event_id: options.eventId ?? this.newId(),
-      business_id: this.businessId,
-      backend_id: this.backendId,
-      meter,
-      qty,
-      timestamp: options.timestamp ?? this.now().toISOString(),
-      ...options.routeId ? { route_id: options.routeId } : {},
-      ...options.requestId ? { request_id: options.requestId } : {},
-      ...options.subscriptionId ? { subscription_id: options.subscriptionId } : {}
-    };
-    this.buffer.push(event);
-    await this.flush();
-  }
-  /** Drain the buffer. Events that fail all retries stay buffered (at-least-once). */
-  async flush() {
-    const pending = this.buffer.splice(0, this.buffer.length);
-    const stillPending = [];
-    for (const event of pending) {
-      const sent = await this.sendWithRetry(event);
-      if (!sent) stillPending.push(event);
-    }
-    if (stillPending.length > 0) this.buffer.unshift(...stillPending);
-  }
-  /** Buffered-but-unsent count (observability/tests). */
-  get pending() {
-    return this.buffer.length;
-  }
-  async sendWithRetry(event) {
-    for (let attempt = 0; attempt < this.maxRetries; attempt += 1) {
-      let retryAfter = null;
-      try {
-        const response = await this.fetchImpl(this.endpoint, {
-          method: "POST",
-          headers: {
-            authorization: `Bearer ${this.config.credential}`,
-            "content-type": "application/json",
-            accept: "application/json"
-          },
-          body: JSON.stringify(event)
-        });
-        if (response.ok) return true;
-        if (!isTransientStatus(response.status)) return false;
-        retryAfter = retryAfterMs(response.headers);
-      } catch {
-      }
-      const isLast = attempt === this.maxRetries - 1;
-      if (isLast) break;
-      const delay = retryAfter !== null ? Math.min(retryAfter, this.maxDelayMs) : computeBackoff(attempt + 1, {
-        baseMs: this.baseDelayMs,
-        maxMs: this.maxDelayMs,
-        random: this.random
-      });
-      await this.sleep(delay);
-    }
-    return false;
-  }
-};
-function resolveEndpoint(endpoint, coreUrl) {
-  if (/^https?:\/\//.test(endpoint)) return endpoint;
-  if (!coreUrl) return endpoint;
-  return `${coreUrl.replace(/\/+$/, "")}${endpoint}`;
-}
-
 // src/response-metering.ts
 var RESPONSE_METERING_HEADERS = RUNTIME_RESPONSE_METERING_CONTRACT.headers;
 var RESPONSE_METERING_ERROR_CODES = RUNTIME_RESPONSE_METERING_CONTRACT.errors;
@@ -1286,6 +1296,49 @@ var METERING_PAYLOAD_HEADER = RESPONSE_METERING_HEADERS.payload;
 var METERING_SIGNATURE_HEADER = RESPONSE_METERING_HEADERS.signature;
 var METERING_TOKEN_HEADER = RESPONSE_METERING_HEADERS.token;
 var DEFAULT_TOKEN_ENV = RUNTIME_RESPONSE_METERING_CONTRACT.token.environmentVariable;
+var MeteringError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "MeteringError";
+    this.code = code;
+  }
+};
+async function computeMeteringHeaders(payload, options = {}) {
+  try {
+    const token = resolveTokenSoft(options);
+    if (!token) {
+      skip(`${DEFAULT_TOKEN_ENV} is not set`, options);
+      return {};
+    }
+    const json2 = JSON.stringify(payload);
+    const signature = await signPayload(json2, token);
+    devMeteringHooks?.record?.(payload, options.requestId);
+    return {
+      [METERING_PAYLOAD_HEADER]: json2,
+      [METERING_SIGNATURE_HEADER]: signature,
+      [METERING_TOKEN_HEADER]: token
+    };
+  } catch (error) {
+    skip(error instanceof Error ? error.message : String(error), options);
+    return {};
+  }
+}
+function skip(reason, options) {
+  if (options.onSkip) {
+    options.onSkip(reason);
+  } else {
+    console.warn(`metering headers skipped: ${reason}`);
+  }
+  devMeteringHooks?.onSkip?.(reason, options.requestId);
+}
+function resolveTokenSoft(options) {
+  return options.token ?? options.env?.[DEFAULT_TOKEN_ENV] ?? processEnv(DEFAULT_TOKEN_ENV) ?? devMeteringHooks?.fallbackToken?.();
+}
+function processEnv(key2) {
+  const maybeProcess = globalThis.process;
+  return maybeProcess?.env?.[key2];
+}
 async function signPayload(payload, token) {
   const key2 = await crypto.subtle.importKey(
     "raw",
@@ -1310,7 +1363,7 @@ function base64url(bytes) {
 }
 
 // src/core/post-stream-usage.ts
-var METER_KEY_RE2 = /^[a-z0-9_]{1,64}$/;
+var METER_KEY_RE = /^[a-z0-9_]{1,64}$/;
 var PostStreamUsageClient = class {
   config;
   endpoint;
@@ -1319,14 +1372,16 @@ var PostStreamUsageClient = class {
   logger;
   sleep;
   retryDelaysMs;
+  maxRetryDelayMs;
   constructor(options) {
     this.config = options.config;
-    this.endpoint = resolveEndpoint2(options.config.endpoint, options.coreUrl);
+    this.endpoint = resolveEndpoint(options.config.endpoint, options.coreUrl);
     this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
     this.newNonce = options.newNonce ?? (() => crypto.randomUUID());
     this.logger = options.logger ?? ((message) => console.warn(message));
     this.sleep = options.sleep ?? sleep;
     this.retryDelaysMs = options.retryDelaysMs ?? [100, 250, 500];
+    this.maxRetryDelayMs = options.maxRetryDelayMs ?? 1e4;
   }
   async reportUsage(input) {
     try {
@@ -1337,6 +1392,11 @@ var PostStreamUsageClient = class {
         requestId: input.requestId,
         subscriptionId: input.subscriptionId,
         nonce: this.newNonce(),
+        // The token's `allowedMeters` scope is enforced on BOTH lanes
+        // independently (P0-1): `meters` is the flat METER-keyed projection
+        // (the billed lane), so its keys must be in scope regardless of
+        // whether the measurement lane is also present; `measurements[].meter`
+        // is scoped in validateMeasurements below.
         meters: validateAndSortUsage(input.meters, "meters", this.config, true),
         ...input.creditUnitsConsumed ? {
           creditUnitsConsumed: validateAndSortUsage(
@@ -1346,7 +1406,13 @@ var PostStreamUsageClient = class {
             false
           )
         } : {},
-        ...input.measureContext ? { measureContext: input.measureContext } : {}
+        ...input.measureContext ? { measureContext: input.measureContext } : {},
+        // Key ORDER is load-bearing: core recomputes the HMAC over
+        // JSON.stringify(unsigned) rebuilt in its zod schema's field order, so
+        // these additive fields must sit in the same position on both sides.
+        ...input.measurementsVersion !== void 0 ? { measurementsVersion: input.measurementsVersion } : {},
+        ...input.measurements ? { measurements: this.validateMeasurements(input.measurements) } : {},
+        ...input.quote ? { quote: input.quote } : {}
       };
       const signature = await signPayload(
         JSON.stringify(unsigned),
@@ -1354,20 +1420,39 @@ var PostStreamUsageClient = class {
       );
       const event = { ...unsigned, signature };
       const body = JSON.stringify(event);
+      const headerSignature = await signPayload(body, this.config.credential);
       for (let attempt = 0; ; attempt += 1) {
-        const response = await this.fetchImpl(this.endpoint, {
-          method: "POST",
-          headers: {
-            authorization: `Bearer ${this.config.credential}`,
-            "content-type": "application/json",
-            accept: "application/json"
-          },
-          body
-        });
+        let response;
+        try {
+          response = await fetchWithDeadline(
+            this.fetchImpl,
+            this.endpoint,
+            {
+              method: "POST",
+              headers: {
+                authorization: `Bearer ${this.config.credential}`,
+                "content-type": "application/json",
+                accept: "application/json",
+                [RUNTIME_RESPONSE_METERING_CONTRACT.headers.signature]: headerSignature
+              },
+              body
+            },
+            "postStreamUsage"
+          );
+        } catch (cause) {
+          const delayMs2 = this.retryDelayForAttempt(attempt, null);
+          if (delayMs2 === null) throw cause;
+          await this.sleep(delayMs2);
+          continue;
+        }
         if (response.ok) return { ok: true };
         const requestNotFound = await isPostStreamRequestNotFound(response);
-        const delayMs = this.retryDelaysMs[attempt];
-        if (!requestNotFound || delayMs === void 0) {
+        const retryable = requestNotFound || isRetryableStatus(response.status);
+        const delayMs = this.retryDelayForAttempt(
+          attempt,
+          retryAfterMs(response.headers)
+        );
+        if (!retryable || delayMs === null) {
           throw new Error(`metering endpoint returned ${response.status}`);
         }
         await this.sleep(delayMs);
@@ -1378,6 +1463,31 @@ var PostStreamUsageClient = class {
       return { ok: false, reason };
     }
   }
+  /** Enforce the token's meter scope + per-event bounds on the measurement lane. */
+  validateMeasurements(measurements) {
+    const allowed = this.config.allowedMeters;
+    for (const measurement of measurements) {
+      if (allowed.length > 0 && !allowed.includes(measurement.meter)) {
+        throw new Error(
+          `meter '${measurement.meter}' is not in the token's allowedMeters`
+        );
+      }
+      for (const [measure, value] of Object.entries(measurement.values)) {
+        if (this.config.perEventMax > 0 && value > this.config.perEventMax) {
+          throw new Error(
+            `measure '${measure}' value ${value} exceeds the per-event max ${this.config.perEventMax}`
+          );
+        }
+      }
+    }
+    return measurements;
+  }
+  retryDelayForAttempt(attempt, retryAfterMs2) {
+    const fallback = this.retryDelaysMs[attempt];
+    if (fallback === void 0) return null;
+    if (retryAfterMs2 === null) return fallback;
+    return Math.min(retryAfterMs2, this.maxRetryDelayMs);
+  }
 };
 async function isPostStreamRequestNotFound(response) {
   if (response.status !== 422) return false;
@@ -1388,6 +1498,18 @@ async function isPostStreamRequestNotFound(response) {
     return false;
   }
 }
+function isRetryableStatus(status) {
+  return status === 429 || status >= 500 && status <= 599;
+}
+function retryAfterMs(headers) {
+  const raw = headers.get("retry-after");
+  if (!raw) return null;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  const dateMs = Date.parse(raw);
+  if (!Number.isFinite(dateMs)) return null;
+  return Math.max(0, dateMs - Date.now());
+}
 function sleep(delayMs) {
   return new Promise((resolve) => setTimeout(resolve, delayMs));
 }
@@ -1396,7 +1518,7 @@ function validateAndSortUsage(usage, label, config, enforceMeterScope) {
     ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
   );
   for (const [meter, qty] of entries) {
-    if (!METER_KEY_RE2.test(meter)) {
+    if (!METER_KEY_RE.test(meter)) {
       throw new Error(
         `${label} key '${meter}' must be lowercase alphanumeric with underscores`
       );
@@ -1415,12 +1537,303 @@ function validateAndSortUsage(usage, label, config, enforceMeterScope) {
   }
   return Object.fromEntries(entries);
 }
-function resolveEndpoint2(endpoint, coreUrl) {
+function resolveEndpoint(endpoint, coreUrl) {
   if (/^https?:\/\//.test(endpoint)) return endpoint;
   if (!coreUrl) return endpoint;
   return `${coreUrl.replace(/\/+$/, "")}${endpoint}`;
 }
 
+// src/core/report.ts
+var MEASUREMENTS_VERSION = 1;
+var KEY_RE = /^[a-z0-9_]{1,64}$/;
+var DIMENSION_VALUE_RE = /^[\w.:-]{1,128}$/;
+var CURRENCY_RE = /^[A-Za-z]{3}$/;
+var DECIMAL_INTEGER_RE = /^\d{1,30}$/;
+function createReportFn(channels) {
+  let stampedMeasurements = [];
+  let stampedQuote;
+  let inBandTail = Promise.resolve();
+  let postStreamFinalized = false;
+  let pendingPostStreamBatch = null;
+  const deliverPostStream = async (reported, quote) => {
+    if (pendingPostStreamBatch) {
+      if (!quotesEqual(pendingPostStreamBatch.quote, quote)) {
+        return {
+          ok: false,
+          transport: "post_stream",
+          reason: "quote conflicts with this request's pending post-stream batch: one served request carries one quote across all measurements"
+        };
+      }
+      if (reported.some(
+        (measurement) => !dimsEqual(
+          pendingPostStreamBatch.measurements[0]?.dims,
+          measurement.dims
+        )
+      )) {
+        return {
+          ok: false,
+          transport: "post_stream",
+          reason: "dims conflict with this request's pending post-stream batch: the request receipt rates under ONE dims tuple"
+        };
+      }
+      pendingPostStreamBatch.measurements.push(...reported);
+      return pendingPostStreamBatch.flush;
+    }
+    if (postStreamFinalized) {
+      return {
+        ok: false,
+        transport: "post_stream",
+        reason: "the served request already used its post-stream callback; report multiple meters in ONE call \u2014 ctx.report([a, b]) \u2014 or before the flush"
+      };
+    }
+    if (stampedMeasurements.length > 0) {
+      return {
+        ok: false,
+        transport: "post_stream",
+        reason: "this request already reported in-band; every report on one request must share the stamped aggregate (same quote, before the response is sent)"
+      };
+    }
+    postStreamFinalized = true;
+    const batch = {
+      measurements: [...reported],
+      quote,
+      flush: void 0
+    };
+    batch.flush = new Promise((resolve) => setTimeout(resolve, 0)).then(
+      async () => {
+        pendingPostStreamBatch = null;
+        const result = await channels.postStream({
+          measurements: batch.measurements,
+          ...batch.quote ? { quote: batch.quote } : {}
+        });
+        return result.ok ? { ok: true, transport: "post_stream" } : {
+          ok: false,
+          transport: "post_stream",
+          reason: result.reason ?? "post-stream delivery failed"
+        };
+      }
+    );
+    pendingPostStreamBatch = batch;
+    return batch.flush;
+  };
+  const tryInBand = (reported, quote) => {
+    const run = inBandTail.then(async () => {
+      const sink = channels.responseSink;
+      if (!sink || !channels.request || !sink.canStampHeaders()) return null;
+      if (postStreamFinalized) return null;
+      if (!quotesEqual(stampedQuote, quote) && stampedMeasurements.length > 0) {
+        return null;
+      }
+      if (stampedMeasurements.length > 0 && reported.some(
+        (measurement) => !dimsEqual(stampedMeasurements[0].dims, measurement.dims)
+      )) {
+        return null;
+      }
+      const measurements = [...stampedMeasurements, ...reported];
+      const payload = buildInBandPayload(channels.request, measurements, quote);
+      const headers = await channels.computeHeaders(payload);
+      if (Object.keys(headers).length === 0 || !sink.canStampHeaders()) {
+        return null;
+      }
+      sink.stampHeaders(headers);
+      stampedMeasurements = measurements;
+      stampedQuote = quote;
+      return { ok: true, transport: "in_band" };
+    });
+    inBandTail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  };
+  return async (input) => {
+    const inputs = Array.isArray(input) ? input : [input];
+    if (inputs.length === 0) {
+      throw new MeteringError(
+        RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
+        "report([]) is empty: a batched report needs at least one measurement"
+      );
+    }
+    const measurements = inputs.map((entry) => validateMeasurement(entry));
+    for (const measurement of measurements) {
+      if (!dimsEqual(measurements[0].dims, measurement.dims)) {
+        throw new MeteringError(
+          RESPONSE_METERING_ERROR_CODES.invalidMeterValue,
+          "a batched report carries ONE dims tuple: the request receipt rates under (route, dims), so mixed dims are unratable \u2014 report each dims tuple on its own request"
+        );
+      }
+    }
+    let quote;
+    for (const entry of inputs) {
+      if (entry.quote === void 0) continue;
+      const validated = validateQuote(entry.quote);
+      if (quote === void 0) {
+        quote = validated;
+      } else if (!quotesEqual(quote, validated)) {
+        throw new MeteringError(
+          RESPONSE_METERING_ERROR_CODES.invalidQuote,
+          "a batched report carries ONE quote: two entries supplied different quotes"
+        );
+      }
+    }
+    const inBand = await tryInBand(measurements, quote);
+    if (inBand) return inBand;
+    return deliverPostStream(measurements, quote);
+  };
+}
+function unattachedReport() {
+  return () => Promise.reject(
+    new MeteringError(
+      RESPONSE_METERING_ERROR_CODES.missingToken,
+      "report() has no metering channel on this context: verify through the runtime (fs.middleware() / fs.verifyRequest()) instead of the bare verifyRequest() primitive, and pass that context to background jobs"
+    )
+  );
+}
+function rawDimsUnitsOf(measurement) {
+  let total = 0;
+  for (const value of Object.values(measurement.values)) total += value;
+  return { [measurement.meter]: total };
+}
+function buildInBandPayload(request, measurements, quote) {
+  const rawDimsUnits = {};
+  for (const measurement of measurements) {
+    for (const [meter, units] of Object.entries(rawDimsUnitsOf(measurement))) {
+      rawDimsUnits[meter] = (rawDimsUnits[meter] ?? 0) + units;
+    }
+  }
+  return {
+    method: request.method.toUpperCase(),
+    path: request.path,
+    rawDimsUnits,
+    measurementsVersion: MEASUREMENTS_VERSION,
+    measurements,
+    ...quote ? { quote } : {}
+  };
+}
+function dimsEqual(left, right) {
+  const l = Object.entries(left ?? {}).sort(([a], [b]) => a < b ? -1 : 1);
+  const r = Object.entries(right ?? {}).sort(([a], [b]) => a < b ? -1 : 1);
+  if (l.length !== r.length) return false;
+  return l.every(([k, v], i) => r[i][0] === k && r[i][1] === v);
+}
+function quotesEqual(left, right) {
+  return left === right || left !== void 0 && right !== void 0 && left.currency === right.currency && left.amountNanos === right.amountNanos;
+}
+function validateMeasurement(input) {
+  if (!input || typeof input !== "object") {
+    throw invalidKey("report() requires a { meter, values } object");
+  }
+  const meter = assertKey(input.meter, "meter");
+  const values = assertValues(input.values);
+  const dims = input.dims === void 0 ? void 0 : assertDims(input.dims);
+  return {
+    meter,
+    values,
+    ...dims && Object.keys(dims).length > 0 ? { dims } : {}
+  };
+}
+function validateQuote(quote) {
+  if (!quote || typeof quote !== "object" || Array.isArray(quote)) {
+    throw invalidQuote(
+      "quote must be an object of the form { currency, amountNanos }"
+    );
+  }
+  const { currency, amountNanos } = quote;
+  if (typeof currency !== "string" || !CURRENCY_RE.test(currency)) {
+    throw invalidQuote("quote.currency must be a 3-letter currency code");
+  }
+  return {
+    currency: currency.toLowerCase(),
+    amountNanos: assertAmountNanos(amountNanos)
+  };
+}
+function assertAmountNanos(value) {
+  if (typeof value === "bigint") {
+    if (value < 0n) throw negativeAmountNanos();
+    return value.toString();
+  }
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value)) {
+      throw invalidQuote(
+        "quote.amountNanos must be a safe integer number of nanodollars (pass a string or bigint for larger amounts)"
+      );
+    }
+    if (value < 0) throw negativeAmountNanos();
+    return String(value);
+  }
+  if (typeof value === "string") {
+    if (/^-/.test(value)) throw negativeAmountNanos();
+    if (DECIMAL_INTEGER_RE.test(value)) return value;
+  }
+  throw invalidQuote(
+    "quote.amountNanos must be a non-negative integer number of nanodollars"
+  );
+}
+function negativeAmountNanos() {
+  return invalidQuote(
+    "quote.amountNanos must be non-negative: a quote is a proposed rate, never a credit \u2014 refunds are platform operations"
+  );
+}
+function assertValues(values) {
+  if (!values || typeof values !== "object" || Array.isArray(values)) {
+    throw invalidKey("report() requires a values object");
+  }
+  const entries = Object.entries(values).sort(
+    ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+  );
+  if (entries.length === 0) {
+    throw invalidKey("report() requires at least one measure in values");
+  }
+  const out = {};
+  for (const [measure, value] of entries) {
+    assertKey(measure, "measure");
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+      throw new MeteringError(
+        RESPONSE_METERING_ERROR_CODES.invalidMeterValue,
+        `values.${measure} must be a non-negative safe integer`
+      );
+    }
+    out[measure] = value;
+  }
+  return out;
+}
+function assertDims(dims) {
+  if (!dims || typeof dims !== "object" || Array.isArray(dims)) {
+    throw invalidKey("report() dims must be an object of dimension selectors");
+  }
+  const entries = Object.entries(dims).sort(
+    ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+  );
+  const out = {};
+  for (const [dimension, value] of entries) {
+    assertKey(dimension, "dimension");
+    if (typeof value !== "string" || !DIMENSION_VALUE_RE.test(value)) {
+      throw invalidKey(
+        `dims.${dimension} must be a 1-128 character selector value`
+      );
+    }
+    out[dimension] = value;
+  }
+  return out;
+}
+function assertKey(value, label) {
+  if (typeof value !== "string" || !KEY_RE.test(value)) {
+    throw invalidKey(
+      `${label} key ${JSON.stringify(value)} must be 1-64 lowercase alphanumeric characters or underscores`
+    );
+  }
+  return value;
+}
+function invalidKey(message) {
+  return new MeteringError(
+    RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
+    message
+  );
+}
+function invalidQuote(message) {
+  return new MeteringError(RESPONSE_METERING_ERROR_CODES.invalidQuote, message);
+}
+
 // src/core/nonceCache.ts
 var DEFAULT_MAX_ENTRIES = 25e4;
 var DEFAULT_TTL_MS = (RUNTIME_REPLAY_WINDOW_SECONDS + RUNTIME_CLOCK_SKEW_SECONDS) * 1e3;
@@ -1463,6 +1876,37 @@ var NonceCache = class {
   }
 };
 
+// src/core/replay-protection.ts
+function resolveReplayProtection(input = {}) {
+  if (input.nonceStore) {
+    return {
+      // An opted-in shared store that is DOWN must not degrade to "no replay
+      // check" — that would make knocking it over a way to switch the
+      // protection off entirely.
+      store: failClosed(input.nonceStore),
+      diagnostic: { mode: "shared", crossReplica: true }
+    };
+  }
+  return {
+    store: new NonceCache(),
+    diagnostic: { mode: "single-instance", crossReplica: false }
+  };
+}
+function failClosed(store) {
+  return {
+    async checkAndRemember(id) {
+      try {
+        return await store.checkAndRemember(id);
+      } catch (cause) {
+        throw new FartherShoreError(
+          "replayed_nonce",
+          `replay store is unavailable, refusing the request rather than skipping one-time-use enforcement: ${cause instanceof Error ? cause.message : String(cause)}`
+        );
+      }
+    }
+  };
+}
+
 // src/core/shutdown.ts
 var ShutdownManager = class {
   hooks = [];
@@ -1983,22 +2427,7 @@ async function verifyRequest(input, deps) {
       "x-fs-timestamp is not an integer"
     );
   }
-  const skew = deps.clockSkewSeconds ?? RUNTIME_CLOCK_SKEW_SECONDS;
-  const window = deps.replayWindowSeconds ?? RUNTIME_REPLAY_WINDOW_SECONDS;
-  const now = (deps.nowSeconds ?? (() => Math.floor(Date.now() / 1e3)))();
-  const delta = now - timestamp;
-  if (Math.abs(delta) > window) {
-    if (Math.abs(delta) <= window + skew) {
-      throw new FartherShoreError(
-        "clock_skew",
-        "x-fs-timestamp is outside the replay window but within clock-skew tolerance"
-      );
-    }
-    throw new FartherShoreError(
-      "expired_signature",
-      "x-fs-timestamp is outside the replay window"
-    );
-  }
+  assertTimestampWithinWindow(timestamp, deps);
   const computedBodyHash = await computeBodyHash(input);
   if (signedBodyHash !== computedBodyHash) {
     throw new FartherShoreError(
@@ -2006,31 +2435,7 @@ async function verifyRequest(input, deps) {
       "recomputed body hash does not match the signed x-fs-body-hash"
     );
   }
-  if (deps.businessId !== void 0 && signedBusinessId !== deps.businessId) {
-    throw new FartherShoreError(
-      "route_mismatch",
-      "signed business-id does not match this backend's business"
-    );
-  }
-  if (deps.backendIds !== void 0 && deps.backendIds.size > 0) {
-    if (!deps.backendIds.has(signedBackendId)) {
-      throw new FartherShoreError(
-        "route_mismatch",
-        "signed backend-id is not one this deployment serves"
-      );
-    }
-  } else if (deps.backendId !== void 0 && signedBackendId !== deps.backendId) {
-    throw new FartherShoreError(
-      "route_mismatch",
-      "signed backend-id does not match this backend"
-    );
-  }
-  if (deps.knownRouteIds !== void 0 && signedRouteId !== "" && !deps.knownRouteIds.has(signedRouteId)) {
-    throw new FartherShoreError(
-      "route_mismatch",
-      "signed route-id is not served by this backend"
-    );
-  }
+  assertClaimBinding(deps, signedBusinessId, signedBackendId, signedRouteId);
   const contextToken = h("x-fs-context") ?? null;
   const canonicalInput = {
     method: input.method,
@@ -2101,9 +2506,57 @@ async function verifyRequest(input, deps) {
     ...principal ? { principal } : {},
     ...permissions !== void 0 ? { permissions } : {},
     ...roles !== void 0 ? { roles } : {},
-    ...signedContext ? { signedContext } : {}
+    ...signedContext ? { signedContext } : {},
+    // The bare primitive has no metering channel; the runtime facade replaces
+    // this with the real bound verb (see FartherShore.verifyRequest).
+    report: unattachedReport()
   };
 }
+function assertTimestampWithinWindow(timestamp, deps) {
+  const skew = deps.clockSkewSeconds ?? RUNTIME_CLOCK_SKEW_SECONDS;
+  const window = deps.replayWindowSeconds ?? RUNTIME_REPLAY_WINDOW_SECONDS;
+  const now = (deps.nowSeconds ?? (() => Math.floor(Date.now() / 1e3)))();
+  const delta = now - timestamp;
+  if (Math.abs(delta) > window) {
+    if (Math.abs(delta) <= window + skew) {
+      throw new FartherShoreError(
+        "clock_skew",
+        "x-fs-timestamp is outside the replay window but within clock-skew tolerance"
+      );
+    }
+    throw new FartherShoreError(
+      "expired_signature",
+      "x-fs-timestamp is outside the replay window"
+    );
+  }
+}
+function assertClaimBinding(deps, signedBusinessId, signedBackendId, signedRouteId) {
+  if (deps.businessId !== void 0 && signedBusinessId !== deps.businessId) {
+    throw new FartherShoreError(
+      "route_mismatch",
+      "signed business-id does not match this backend's business"
+    );
+  }
+  if (deps.backendIds !== void 0 && deps.backendIds.size > 0) {
+    if (!deps.backendIds.has(signedBackendId)) {
+      throw new FartherShoreError(
+        "route_mismatch",
+        "signed backend-id is not one this deployment serves"
+      );
+    }
+  } else if (deps.backendId !== void 0 && signedBackendId !== deps.backendId) {
+    throw new FartherShoreError(
+      "route_mismatch",
+      "signed backend-id does not match this backend"
+    );
+  }
+  if (deps.knownRouteIds !== void 0 && signedRouteId !== "" && !deps.knownRouteIds.has(signedRouteId)) {
+    throw new FartherShoreError(
+      "route_mismatch",
+      "signed route-id is not served by this backend"
+    );
+  }
+}
 async function resolveSignedContext(contextToken, contextSecrets, signedBusinessId) {
   if (!contextToken) return null;
   const signedContext = decodeContextClaims(contextToken);
@@ -2156,7 +2609,7 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.19.0".length > 0 ? "0.19.0" : "0.0.0-dev";
+var SDK_VERSION = "0.21.0".length > 0 ? "0.21.0" : "0.0.0-dev";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -2169,16 +2622,16 @@ var FartherShore = class {
   /** OPTIONAL HS256 secret(s) — defense-in-depth over the cv=2 X-Fs-Context. */
   contextSecrets;
   nonceCache;
+  replayProtectionDiagnostic;
   shutdownManager = new ShutdownManager();
   jwks = null;
-  meteringClient = null;
   postStreamUsageClient = null;
   tunnel = null;
   bootstrapped = false;
   constructor(options = {}) {
     const env = options.env ?? readProcessEnv();
     const runtimeToken = options.runtimeToken ?? env[FS_RUNTIME_TOKEN_ENV] ?? "";
-    const coreUrl = options.coreUrl ?? env.FS_CORE_URL ?? env.FARTHERSHORE_CORE_URL ?? DEFAULT_CORE_URL;
+    const coreUrl = options.coreUrl ?? env.FS_CORE_URL ?? DEFAULT_CORE_URL;
     this.runtimeToken = runtimeToken;
     this.coreUrl = coreUrl;
     this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
@@ -2186,7 +2639,9 @@ var FartherShore = class {
     this.meteringEnabledOverride = options.metering?.enabled ?? true;
     this.tunnelOptions = options.tunnel ?? {};
     this.instanceId = options.instanceId;
-    this.nonceCache = options.nonceStore ?? new NonceCache();
+    const replay = resolveReplayProtection({ nonceStore: options.nonceStore });
+    this.nonceCache = replay.store;
+    this.replayProtectionDiagnostic = replay.diagnostic;
     this.contextSecrets = options.contextSecrets ?? parseContextSecrets(env.FS_CONTEXT_SECRETS);
     this.bootstrapClient = new BootstrapClient({
       runtimeToken,
@@ -2198,9 +2653,6 @@ var FartherShore = class {
         ...options.instanceId ? { instanceId: options.instanceId } : {}
       }
     });
-    this.shutdownManager.register(async () => {
-      await this.meteringClient?.flush();
-    });
     this.shutdownManager.register(async () => {
       await reportHealth({
         runtimeToken: this.runtimeToken,
@@ -2220,14 +2672,7 @@ var FartherShore = class {
         fetchImpl: this.fetchImpl
       });
     }
-    if (!this.meteringClient && config.metering.enabled) {
-      this.meteringClient = new MeteringClient({
-        config: config.metering,
-        businessId: config.business.id,
-        backendId: config.backend.id,
-        coreUrl: this.coreUrl,
-        fetchImpl: this.fetchImpl
-      });
+    if (!this.postStreamUsageClient && config.metering.enabled) {
       this.postStreamUsageClient = new PostStreamUsageClient({
         config: config.metering,
         coreUrl: this.coreUrl,
@@ -2276,14 +2721,19 @@ var FartherShore = class {
   buildReportSink() {
     const post = async (path, body) => {
       const base = this.coreUrl.replace(/\/$/, "");
-      const res = await this.fetchImpl(`${base}${path}`, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          authorization: `Bearer ${this.runtimeToken}`
+      const res = await fetchWithDeadline(
+        this.fetchImpl,
+        `${base}${path}`,
+        {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${this.runtimeToken}`
+          },
+          body: JSON.stringify(body)
         },
-        body: JSON.stringify(body)
-      });
+        "report"
+      );
       if (!res.ok) throw new Error(`runtime report ${path} -> ${res.status}`);
     };
     return {
@@ -2295,7 +2745,7 @@ var FartherShore = class {
    * Framework-neutral verification primitive. Fail-closed: throws a typed
    * FartherShoreError on any verification failure. Returns the verified context.
    */
-  async verifyRequest(input) {
+  async verifyRequest(input, options = {}) {
     const config = await this.ensureBootstrapped();
     if (!this.jwks) {
       throw new FartherShoreError(
@@ -2321,21 +2771,52 @@ var FartherShore = class {
     });
     return {
       ...context,
-      reportUsage: (report) => {
-        const subscriptionId = report.subscriptionId ?? context.signedContext?.subscriptionId;
+      report: this.buildReportFn(context, input, options.responseSink)
+    };
+  }
+  /**
+   * Bind the ONE reporting verb to a verified context. Identity comes from the
+   * context (`signedContext.subscriptionId` + `requestId`) — never from the
+   * caller — so a handler cannot forget it, and a background job that is handed
+   * this context keeps reporting against the SAME served identity.
+   */
+  buildReportFn(context, input, responseSink) {
+    const channels = {
+      request: { method: input.method, path: input.path },
+      ...responseSink ? { responseSink } : {},
+      computeHeaders: (payload) => computeMeteringHeaders(payload, {
+        token: this.runtimeToken,
+        requestId: context.requestId,
+        onSkip: () => {
+        }
+      }),
+      postStream: async ({ measurements, quote }) => {
+        const subscriptionId = context.signedContext?.subscriptionId;
         if (!subscriptionId) {
-          return Promise.resolve({
+          return {
             ok: false,
-            reason: "subscriptionId is required"
-          });
+            reason: "this request carries no subscription identity, so late usage cannot be attributed \u2014 report before the response is sent, or serve the route through a subscribed surface"
+          };
+        }
+        const meters = {};
+        for (const measurement of measurements) {
+          for (const [meter, qty] of Object.entries(
+            rawDimsUnitsOf(measurement)
+          )) {
+            meters[meter] = (meters[meter] ?? 0) + qty;
+          }
         }
-        return this.reportUsage({
-          ...report,
-          requestId: report.requestId ?? context.requestId,
-          subscriptionId
+        return this.reportPostStreamUsage({
+          requestId: context.requestId,
+          subscriptionId,
+          meters,
+          measurementsVersion: MEASUREMENTS_VERSION,
+          measurements,
+          ...quote ? { quote } : {}
         });
       }
     };
+    return createReportFn(channels);
   }
   /** Whether verification is required (bootstrap × opt-out). */
   async verificationRequired() {
@@ -2384,20 +2865,12 @@ var FartherShore = class {
     });
     await supervisor.start();
   }
-  /** Record metering usage (billing-only). */
-  async meter(meter, qty, options = {}) {
-    await this.ensureBootstrapped();
-    if (!this.meteringEnabledOverride) return;
-    if (!this.meteringClient) {
-      throw new FartherShoreError(
-        "invalid_token",
-        "metering is not enabled for this runtime token"
-      );
-    }
-    await this.meteringClient.meter(meter, qty, options);
-  }
-  /** Best-effort attested post-stream usage callback. Never rejects. */
-  async reportUsage(input) {
+  /**
+   * PRIVATE transport for the post-stream lane of `ctx.report()`. Never rejects
+   * — a metering hiccup must not break a builder's endpoint. This is machinery,
+   * not surface: the ONE public reporting verb is `ctx.report()`.
+   */
+  async reportPostStreamUsage(input) {
     try {
       await this.ensureBootstrapped();
       if (!this.meteringEnabledOverride || !this.postStreamUsageClient) {
@@ -2410,6 +2883,15 @@ var FartherShore = class {
       return { ok: false, reason };
     }
   }
+  /**
+   * How far replay protection actually reaches — `"shared"` (enforced across
+   * every replica) or `"single-instance"` (this process only). Deployment
+   * diagnostic: log it at boot, or assert on it in a smoke test, so the mode is
+   * never a surprise. See {@link FartherShoreInitOptions.nonceStore}.
+   */
+  replayProtection() {
+    return this.replayProtectionDiagnostic;
+  }
   /** Current local health report. */
   health() {
     const config = this.bootstrapClient.peek();
@@ -2420,7 +2902,7 @@ var FartherShore = class {
       // fs.start() launches an embedded tunnel; otherwise the supervisor state.
       tunnel: this.tunnel ? this.tunnel.healthString() : null,
       verification: this.verificationEnabled && config !== null,
-      metering: this.meteringClient !== null
+      metering: this.postStreamUsageClient !== null
     });
   }
   /** Graceful shutdown: flush metering + send a stopping heartbeat. */
@@ -2464,7 +2946,12 @@ function permissionSatisfies(required, granted) {
   const idx = required.indexOf(":");
   if (idx > 0 && idx < required.length - 1) {
     const subject = required.slice(0, idx);
-    if (granted.includes(`${subject}:${WILDCARD}`)) return true;
+    if (subject !== WILDCARD && granted.includes(`${subject}:${WILDCARD}`))
+      return true;
+    if (required.slice(idx + 1) === WILDCARD && subject !== WILDCARD) {
+      const prefix = `${subject}:`;
+      return granted.some((permission) => permission.startsWith(prefix));
+    }
   }
   return false;
 }
@@ -2499,14 +2986,17 @@ async function runMiddleware(fs, options, req, res, next) {
     const contentType = headerValue(req.headers, "content-type");
     const streamingExempt = isStreamingExempt(contentType);
     const body = streamingExempt ? null : extractRawBody(req);
-    const ctx = await fs.verifyRequest({
-      method: req.method,
-      path,
-      query,
-      headers: req.headers,
-      body,
-      streamingExempt
-    });
+    const ctx = await fs.verifyRequest(
+      {
+        method: req.method,
+        path,
+        query,
+        headers: req.headers,
+        body,
+        streamingExempt
+      },
+      { responseSink: expressResponseSink(res) }
+    );
     req.fartherShore = ctx;
     stripFartherShoreHeaders(req);
     next();
@@ -2514,6 +3004,16 @@ async function runMiddleware(fs, options, req, res, next) {
     fail(res, error, options, req);
   }
 }
+function expressResponseSink(res) {
+  return {
+    canStampHeaders: () => res.headersSent !== true,
+    stampHeaders: (headers) => {
+      for (const [name, value] of Object.entries(headers)) {
+        res.setHeader(name, value);
+      }
+    }
+  };
+}
 function fail(res, error, options, req) {
   const code = error instanceof FartherShoreError ? error.code : "bad_signature";
   const status = error instanceof FartherShoreError ? error.status : 401;
@@ -2554,7 +3054,12 @@ function stripFartherShoreHeaders(req) {
     withRaw.rawHeaders = cleaned;
   }
 }
-function createExpressHandler(handler) {
+function createExpressHandler(optionsOrHandler, maybeHandler) {
+  const options = typeof optionsOrHandler === "function" ? {} : optionsOrHandler;
+  const handler = typeof optionsOrHandler === "function" ? optionsOrHandler : maybeHandler;
+  if (typeof handler !== "function") {
+    throw new TypeError("fs.handler(options, cb) requires a handler callback");
+  }
   return (req, res, next) => {
     const ctx = req.fartherShore;
     if (!ctx) {
@@ -2565,10 +3070,22 @@ function createExpressHandler(handler) {
       res.status(401).json({ error: "principal_required" });
       return;
     }
+    if (!ctx.signedContext) {
+      res.status(401).json({ error: "context_unverified" });
+      return;
+    }
     const verified = ctx;
-    void Promise.resolve().then(
-      () => handler(verified, req, res, next)
-    ).catch((error) => failHandler(res, next, error));
+    void Promise.resolve().then(() => {
+      if (options.permission !== void 0) {
+        requirePermission(verified, options.permission);
+      }
+      return handler(
+        verified,
+        req,
+        res,
+        next
+      );
+    }).catch((error) => failHandler(res, next, error));
   };
 }
 function failHandler(res, next, error) {
@@ -2629,7 +3146,7 @@ function readProcessEnv2() {
 // src/testing/usageSink.ts
 var DevUsageSink = class {
   events = [];
-  /** Record a signed response-metering payload (withUsage / computeMeteringHeaders). */
+  /** Record a signed response-metering payload (report() in-band / computeMeteringHeaders). */
   recordResponse(payload, requestId) {
     const raw = payload.rawDimsUnits;
     const meters = raw && typeof raw === "object" ? raw : {};
@@ -2909,6 +3426,7 @@ function createDevRuntime(options) {
   }
   fs.middleware = middleware;
   fs.handler = createExpressHandler;
+  fs.authz = tracedAuthz;
   const devRuntime = {
     fs,
     asPersona: (name) => personaClient.asPersona(name),
@@ -3021,6 +3539,69 @@ function splitUrl2(req) {
   if (qIndex === -1) return { path: raw, query: "" };
   return { path: raw.slice(0, qIndex), query: raw.slice(qIndex + 1) };
 }
+
+// ../contracts/dist/webhooks/standard-webhooks.js
+import { createHmac, randomBytes as randomBytes2, timingSafeEqual } from "node:crypto";
+var WEBHOOK_ID_HEADER = "webhook-id";
+var WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+var WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+var WEBHOOK_SIGNATURE_VERSION = "v1";
+var WEBHOOK_SECRET_PREFIX = "fswh_";
+function webhookSecretKeyBytes(secret) {
+  const key2 = secret.startsWith(WEBHOOK_SECRET_PREFIX) ? Buffer.from(secret.slice(WEBHOOK_SECRET_PREFIX.length), "base64") : secret.startsWith("whsec_") ? Buffer.from(secret.slice("whsec_".length), "base64") : Buffer.from(secret, "utf8");
+  if (key2.length === 0) {
+    throw new Error("webhook secret resolves to an empty signing key \u2014 the configured secret must be a non-empty fswh_ value");
+  }
+  return key2;
+}
+function webhookSignedContent(id, timestamp, body) {
+  return `${id}.${timestamp}.${body}`;
+}
+function signWebhookContent(secret, id, timestamp, body) {
+  const mac = createHmac("sha256", webhookSecretKeyBytes(secret)).update(webhookSignedContent(id, timestamp, body)).digest("base64");
+  return `${WEBHOOK_SIGNATURE_VERSION},${mac}`;
+}
+function signWebhook(input) {
+  if (input.secrets.length === 0) {
+    throw new Error("signWebhook: at least one secret is required");
+  }
+  const signature = input.secrets.map((secret) => signWebhookContent(secret, input.id, input.timestamp, input.body)).join(" ");
+  return {
+    [WEBHOOK_ID_HEADER]: input.id,
+    [WEBHOOK_TIMESTAMP_HEADER]: String(input.timestamp),
+    [WEBHOOK_SIGNATURE_HEADER]: signature
+  };
+}
+
+// src/testing/webhooks.ts
+function signWebhookForTesting(input) {
+  const secrets = typeof input.secret === "string" ? [input.secret] : [...input.secret];
+  const id = input.id ?? `test_${crypto.randomUUID()}`;
+  const envelope = {
+    id,
+    type: input.type,
+    createdAt: input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    businessId: input.businessId ?? "biz_test",
+    environmentId: input.environmentId ?? null,
+    data: input.data
+  };
+  const body = JSON.stringify(envelope);
+  const timestamp = input.timestamp ?? Math.floor(Date.now() / 1e3);
+  const signed = signWebhook({ id, timestamp, body, secrets });
+  const headers = {
+    "content-type": "application/json",
+    ...signed,
+    "x-fs-webhook-event": input.type
+  };
+  return {
+    envelope,
+    body,
+    headers,
+    request(url = "https://receiver.test/webhooks/farthershore") {
+      return new Request(url, { method: "POST", headers, body });
+    }
+  };
+}
 export {
   CONTEXT_HEADER_NAME,
   DEFAULT_KEYS_FILE,
@@ -3053,6 +3634,7 @@ export {
   readDevKeysFile,
   redactValue,
   signContextToken,
+  signWebhookForTesting,
   unreachableJwks,
   writeDevKeysFile
 };