@farthershore/backend 0.20.0 → 0.21.0

package/dist/testing/index.js

@@ -194,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",
@@ -228,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",
@@ -248,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",
@@ -1281,185 +1285,6 @@ async function reportHealth(options) {
   }
 }
 
-// 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 fetchWithDeadline(
-          this.fetchImpl,
-          this.endpoint,
-          {
-            method: "POST",
-            headers: {
-              authorization: `Bearer ${this.config.credential}`,
-              "content-type": "application/json",
-              accept: "application/json"
-            },
-            body: JSON.stringify(event)
-          },
-          "metering"
-        );
-        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;
@@ -1471,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",
@@ -1495,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;
@@ -1507,7 +1375,7 @@ var PostStreamUsageClient = class {
   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));
@@ -1524,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(
@@ -1533,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),
@@ -1541,6 +1420,7 @@ 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) {
         let response;
         try {
@@ -1552,7 +1432,8 @@ var PostStreamUsageClient = class {
               headers: {
                 authorization: `Bearer ${this.config.credential}`,
                 "content-type": "application/json",
-                accept: "application/json"
+                accept: "application/json",
+                [RUNTIME_RESPONSE_METERING_CONTRACT.headers.signature]: headerSignature
               },
               body
             },
@@ -1569,7 +1450,7 @@ var PostStreamUsageClient = class {
         const retryable = requestNotFound || isRetryableStatus(response.status);
         const delayMs = this.retryDelayForAttempt(
           attempt,
-          retryAfterMs2(response.headers)
+          retryAfterMs(response.headers)
         );
         if (!retryable || delayMs === null) {
           throw new Error(`metering endpoint returned ${response.status}`);
@@ -1582,11 +1463,30 @@ var PostStreamUsageClient = class {
       return { ok: false, reason };
     }
   }
-  retryDelayForAttempt(attempt, retryAfterMs3) {
+  /** 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 (retryAfterMs3 === null) return fallback;
-    return Math.min(retryAfterMs3, this.maxRetryDelayMs);
+    if (retryAfterMs2 === null) return fallback;
+    return Math.min(retryAfterMs2, this.maxRetryDelayMs);
   }
 };
 async function isPostStreamRequestNotFound(response) {
@@ -1601,7 +1501,7 @@ async function isPostStreamRequestNotFound(response) {
 function isRetryableStatus(status) {
   return status === 429 || status >= 500 && status <= 599;
 }
-function retryAfterMs2(headers) {
+function retryAfterMs(headers) {
   const raw = headers.get("retry-after");
   if (!raw) return null;
   const seconds = Number(raw);
@@ -1618,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`
       );
@@ -1637,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;
@@ -2236,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(
@@ -2259,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,
@@ -2354,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);
@@ -2409,7 +2609,7 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.20.0".length > 0 ? "0.20.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;
@@ -2425,14 +2625,13 @@ var FartherShore = class {
   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;
@@ -2454,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,
@@ -2476,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,
@@ -2556,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(
@@ -2582,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"
+          };
         }
-        return this.reportUsage({
-          ...report,
-          requestId: report.requestId ?? context.requestId,
-          subscriptionId
+        const meters = {};
+        for (const measurement of measurements) {
+          for (const [meter, qty] of Object.entries(
+            rawDimsUnitsOf(measurement)
+          )) {
+            meters[meter] = (meters[meter] ?? 0) + qty;
+          }
+        }
+        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() {
@@ -2645,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) {
@@ -2690,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. */
@@ -2734,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;
 }
@@ -2769,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();
@@ -2784,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;
@@ -2824,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) {
@@ -2835,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) {
@@ -2899,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 : {};
@@ -3179,6 +3426,7 @@ function createDevRuntime(options) {
   }
   fs.middleware = middleware;
   fs.handler = createExpressHandler;
+  fs.authz = tracedAuthz;
   const devRuntime = {
     fs,
     asPersona: (name) => personaClient.asPersona(name),
@@ -3291,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,
@@ -3323,6 +3634,7 @@ export {
   readDevKeysFile,
   redactValue,
   signContextToken,
+  signWebhookForTesting,
   unreachableJwks,
   writeDevKeysFile
 };