@farthershore/backend 0.13.0 → 0.15.0

package/dist/index.js

@@ -306,7 +306,7 @@ var RUNTIME_HEADER_NAMES = {
   keyId: "x-fs-key-id",
   requestId: "x-fs-request-id",
   timestamp: "x-fs-timestamp",
-  productId: "x-fs-product-id",
+  businessId: "x-fs-business-id",
   backendId: "x-fs-backend-id",
   routeId: "x-fs-route-id",
   policyVersion: "x-fs-policy-version",
@@ -358,7 +358,7 @@ var CANONICAL_SIGNING_FIELDS = [
   "body-hash",
   "request-id",
   "timestamp",
-  "product-id",
+  "business-id",
   "backend-id",
   "route-id",
   "policy-version"
@@ -395,7 +395,7 @@ function buildCanonicalSigningString(input) {
     "body-hash": input.bodyHash,
     "request-id": input.requestId,
     timestamp: String(input.timestamp),
-    "product-id": input.productId,
+    "business-id": input.businessId,
     "backend-id": input.backendId,
     "route-id": input.routeId,
     "policy-version": input.policyVersion
@@ -761,7 +761,7 @@ var DEFAULT_MAX_RETRIES = 3;
 var MeteringClient = class {
   config;
   endpoint;
-  productId;
+  businessId;
   backendId;
   fetchImpl;
   maxRetries;
@@ -775,7 +775,7 @@ var MeteringClient = class {
   constructor(options) {
     this.config = options.config;
     this.endpoint = resolveEndpoint(options.config.endpoint, options.coreUrl);
-    this.productId = options.productId;
+    this.businessId = options.businessId;
     this.backendId = options.backendId;
     this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
@@ -838,13 +838,14 @@ var MeteringClient = class {
     }
     const event = {
       event_id: options.eventId ?? this.newId(),
-      product_id: this.productId,
+      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.requestId ? { request_id: options.requestId } : {},
+      ...options.subscriptionId ? { subscription_id: options.subscriptionId } : {}
     };
     this.buffer.push(event);
     await this.flush();
@@ -899,6 +900,300 @@ function resolveEndpoint(endpoint, coreUrl) {
   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;
+var devMeteringHooks = null;
+function __setDevMeteringHooks(hooks) {
+  devMeteringHooks = hooks;
+}
+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;
+  }
+};
+function createUsage(request, options = {}) {
+  const usage = {};
+  const reporter = {
+    report(meter, value) {
+      usage[assertMeterKey(meter)] = assertMeterValue(meter, value);
+      return reporter;
+    },
+    async wrap(response, wrapOptions = {}) {
+      return signResponse(request, response, usage, options, wrapOptions);
+    }
+  };
+  return reporter;
+}
+async function withUsage(request, response, usage, options = {}) {
+  const reporter = createUsage(request, options);
+  for (const [meter, value] of Object.entries(usage)) {
+    reporter.report(meter, value);
+  }
+  return reporter.wrap(response);
+}
+async function signResponse(request, response, usage, options, wrapOptions) {
+  const payload = buildPayload(request, usage, options, wrapOptions);
+  const requestId = request.headers.get("x-fs-request-id") ?? void 0;
+  const headers = await computeMeteringHeaders(payload, {
+    ...options.token !== void 0 ? { token: options.token } : {},
+    ...options.env !== void 0 ? { env: options.env } : {},
+    ...requestId ? { requestId } : {},
+    onSkip: () => {
+    }
+  });
+  if (Object.keys(headers).length === 0) {
+    throw new MeteringError(
+      RESPONSE_METERING_ERROR_CODES.missingToken,
+      `${DEFAULT_TOKEN_ENV} is required to sign Farther Shore metering reports`
+    );
+  }
+  const merged = new Headers(response.headers);
+  for (const [name, value] of Object.entries(headers)) merged.set(name, value);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: merged
+  });
+}
+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 buildPayload(request, usage, options, wrapOptions) {
+  const url = new URL(request.url);
+  const measureContext = wrapOptions.measureContext ?? options.measureContext;
+  const creditUnitsConsumed = wrapOptions.creditUnitsConsumed ?? options.creditUnitsConsumed;
+  const operationKey = wrapOptions.operationKey ?? options.operationKey;
+  const usagePolicyId = wrapOptions.usagePolicyId ?? options.usagePolicyId;
+  const payload = {
+    method: request.method.toUpperCase(),
+    path: url.pathname,
+    rawDimsUnits: sortUsage(usage),
+    ...measureContext ? { measureContext } : {},
+    ...creditUnitsConsumed ? {
+      creditUnitsConsumed: sortUsage(
+        validateUsageMap(creditUnitsConsumed, "creditUnitsConsumed")
+      )
+    } : {},
+    ...operationKey ? { operationKey: assertIdentifier(operationKey) } : {},
+    ...usagePolicyId ? { usagePolicyId: assertIdentifier(usagePolicyId) } : {}
+  };
+  return payload;
+}
+function sortUsage(usage) {
+  return Object.fromEntries(
+    Object.entries(usage).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+  );
+}
+function validateUsageMap(usage, label) {
+  return Object.fromEntries(
+    Object.entries(usage).map(([meter, value]) => [
+      assertMeterKey(meter),
+      assertMeterValue(`${label}.${meter}`, value)
+    ])
+  );
+}
+function assertMeterKey(meter) {
+  if (!/^[a-z0-9_]{1,64}$/.test(meter)) {
+    throw new MeteringError(
+      RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
+      `meter key "${meter}" must be lowercase alphanumeric with underscores`
+    );
+  }
+  return meter;
+}
+function assertMeterValue(meter, value) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new MeteringError(
+      RESPONSE_METERING_ERROR_CODES.invalidMeterValue,
+      `meter "${meter}" value must be a non-negative finite number`
+    );
+  }
+  return value;
+}
+function assertIdentifier(value) {
+  if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(value)) {
+    throw new MeteringError(
+      RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
+      `operation and usage policy identifiers must be 1-128 URL-safe characters`
+    );
+  }
+  return value;
+}
+function processEnv(key2) {
+  const maybeProcess = globalThis.process;
+  return maybeProcess?.env?.[key2];
+}
+async function signPayload(payload, token) {
+  const key2 = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(token),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key2,
+    new TextEncoder().encode(payload)
+  );
+  return base64url(new Uint8Array(signature));
+}
+function base64url(bytes) {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// src/core/post-stream-usage.ts
+var METER_KEY_RE2 = /^[a-z0-9_]{1,64}$/;
+var PostStreamUsageClient = class {
+  config;
+  endpoint;
+  fetchImpl;
+  newNonce;
+  logger;
+  sleep;
+  retryDelaysMs;
+  constructor(options) {
+    this.config = options.config;
+    this.endpoint = resolveEndpoint2(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];
+  }
+  async reportUsage(input) {
+    try {
+      if (!this.config.enabled) throw new Error("metering is not enabled");
+      if (!input.requestId) throw new Error("requestId is required");
+      if (!input.subscriptionId) throw new Error("subscriptionId is required");
+      const unsigned = {
+        requestId: input.requestId,
+        subscriptionId: input.subscriptionId,
+        nonce: this.newNonce(),
+        meters: validateAndSortUsage(input.meters, "meters", this.config, true),
+        ...input.creditUnitsConsumed ? {
+          creditUnitsConsumed: validateAndSortUsage(
+            input.creditUnitsConsumed,
+            "creditUnitsConsumed",
+            this.config,
+            false
+          )
+        } : {},
+        ...input.measureContext ? { measureContext: input.measureContext } : {}
+      };
+      const signature = await signPayload(
+        JSON.stringify(unsigned),
+        this.config.credential
+      );
+      const event = { ...unsigned, signature };
+      const body = JSON.stringify(event);
+      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
+        });
+        if (response.ok) return { ok: true };
+        const requestNotFound = await isPostStreamRequestNotFound(response);
+        const delayMs = this.retryDelaysMs[attempt];
+        if (!requestNotFound || delayMs === void 0) {
+          throw new Error(`metering endpoint returned ${response.status}`);
+        }
+        await this.sleep(delayMs);
+      }
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      this.logger(`post-stream usage report skipped: ${reason}`);
+      return { ok: false, reason };
+    }
+  }
+};
+async function isPostStreamRequestNotFound(response) {
+  if (response.status !== 422) return false;
+  try {
+    const body = await response.json();
+    return body.error?.code === "post_stream_request_not_found";
+  } catch {
+    return false;
+  }
+}
+function sleep(delayMs) {
+  return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+function validateAndSortUsage(usage, label, config, enforceMeterScope) {
+  const entries = Object.entries(usage).sort(
+    ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+  );
+  for (const [meter, qty] of entries) {
+    if (!METER_KEY_RE2.test(meter)) {
+      throw new Error(
+        `${label} key '${meter}' must be lowercase alphanumeric with underscores`
+      );
+    }
+    if (!Number.isFinite(qty) || qty < 0) {
+      throw new Error(`${label}.${meter} must be a non-negative finite number`);
+    }
+    if (enforceMeterScope && config.allowedMeters.length > 0 && !config.allowedMeters.includes(meter)) {
+      throw new Error(`meter '${meter}' is not in the token's allowedMeters`);
+    }
+    if (enforceMeterScope && config.perEventMax > 0 && qty > config.perEventMax) {
+      throw new Error(
+        `meter '${meter}' qty ${qty} exceeds the per-event max ${config.perEventMax}`
+      );
+    }
+  }
+  return Object.fromEntries(entries);
+}
+function resolveEndpoint2(endpoint, coreUrl) {
+  if (/^https?:\/\//.test(endpoint)) return endpoint;
+  if (!coreUrl) return endpoint;
+  return `${coreUrl.replace(/\/+$/, "")}${endpoint}`;
+}
+
 // src/core/nonceCache.ts
 var DEFAULT_MAX_ENTRIES = 1e5;
 var DEFAULT_TTL_MS = 6e5;
@@ -1411,12 +1706,12 @@ async function verifyRequest(input, deps) {
   const kid = h(RUNTIME_HEADER_NAMES.keyId);
   const requestId = h(RUNTIME_HEADER_NAMES.requestId);
   const timestampRaw = h(RUNTIME_HEADER_NAMES.timestamp);
-  const signedProductId = h(RUNTIME_HEADER_NAMES.productId);
+  const signedBusinessId = h(RUNTIME_HEADER_NAMES.businessId);
   const signedBackendId = h(RUNTIME_HEADER_NAMES.backendId);
   const signedRouteId = h(RUNTIME_HEADER_NAMES.routeId) ?? "";
   const policyVersion = h(RUNTIME_HEADER_NAMES.policyVersion);
   const signedBodyHash = h(RUNTIME_HEADER_NAMES.bodyHash);
-  if (!kid || !requestId || !timestampRaw || !signedProductId || !signedBackendId || policyVersion === void 0 || !signedBodyHash) {
+  if (!kid || !requestId || !timestampRaw || !signedBusinessId || !signedBackendId || policyVersion === void 0 || !signedBodyHash) {
     throw new FartherShoreError(
       "malformed_signature",
       "request is missing one or more required x-fs-* headers"
@@ -1452,10 +1747,10 @@ async function verifyRequest(input, deps) {
       "recomputed body hash does not match the signed x-fs-body-hash"
     );
   }
-  if (deps.productId !== void 0 && signedProductId !== deps.productId) {
+  if (deps.businessId !== void 0 && signedBusinessId !== deps.businessId) {
     throw new FartherShoreError(
       "route_mismatch",
-      "signed product-id does not match this backend's product"
+      "signed business-id does not match this backend's business"
     );
   }
   if (deps.backendId !== void 0 && signedBackendId !== deps.backendId) {
@@ -1477,7 +1772,7 @@ async function verifyRequest(input, deps) {
     bodyHash: computedBodyHash,
     requestId,
     timestamp,
-    productId: signedProductId,
+    businessId: signedBusinessId,
     backendId: signedBackendId,
     routeId: signedRouteId,
     policyVersion
@@ -1517,10 +1812,10 @@ async function verifyRequest(input, deps) {
       if (signedContext === null && deps.contextVerification === "required") {
         throw contextRequiredError("failed verification");
       }
-      if (signedContext && signedContext.productId !== signedProductId) {
+      if (signedContext && signedContext.productId !== signedBusinessId) {
         throw new FartherShoreError(
           "context_unverified",
-          "X-Fs-Context was minted for a different product than the signed request"
+          "X-Fs-Context was minted for a different business than the signed request"
         );
       }
     } else if (deps.contextVerification === "required") {
@@ -1540,7 +1835,7 @@ async function verifyRequest(input, deps) {
   }
   return {
     requestId,
-    productId: signedProductId,
+    businessId: signedBusinessId,
     backendId: signedBackendId,
     routeId: signedRouteId,
     policyVersion,
@@ -1583,8 +1878,8 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.13.0".length > 0 ? "0.13.0" : "0.0.0-dev";
-var CONTRACTS_FP = "220bea90107ed396".length > 0 ? "220bea90107ed396" : "0000000000000000";
+var SDK_VERSION = "0.15.0".length > 0 ? "0.15.0" : "0.0.0-dev";
+var CONTRACTS_FP = "4b6a36b4cb1f0b68".length > 0 ? "4b6a36b4cb1f0b68" : "0000000000000000";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1602,6 +1897,7 @@ var FartherShore = class {
   shutdownManager = new ShutdownManager();
   jwks = null;
   meteringClient = null;
+  postStreamUsageClient = null;
   tunnel = null;
   bootstrapped = false;
   constructor(options = {}) {
@@ -1652,11 +1948,16 @@ var FartherShore = class {
     if (!this.meteringClient && config.metering.enabled) {
       this.meteringClient = new MeteringClient({
         config: config.metering,
-        productId: config.product.id,
+        businessId: config.business.id,
         backendId: config.backend.id,
         coreUrl: this.coreUrl,
         fetchImpl: this.fetchImpl
       });
+      this.postStreamUsageClient = new PostStreamUsageClient({
+        config: config.metering,
+        coreUrl: this.coreUrl,
+        fetchImpl: this.fetchImpl
+      });
     }
     this.bootstrapped = true;
     return config;
@@ -1728,10 +2029,10 @@ var FartherShore = class {
       );
     }
     const knownRouteIds = new Set(config.routes.map((r) => r.id));
-    return verifyRequest(input, {
+    const context = await verifyRequest(input, {
       jwks: this.jwks,
       nonceCache: this.nonceCache,
-      productId: config.product.id,
+      businessId: config.business.id,
       backendId: config.backend.id,
       knownRouteIds,
       clockSkewSeconds: config.verification.clockSkewSeconds,
@@ -1743,6 +2044,23 @@ var FartherShore = class {
       contextSecrets: this.contextSecrets,
       contextVerification: this.contextVerification
     });
+    return {
+      ...context,
+      reportUsage: (report) => {
+        const subscriptionId = report.subscriptionId ?? context.signedContext?.subscriptionId;
+        if (!subscriptionId) {
+          return Promise.resolve({
+            ok: false,
+            reason: "subscriptionId is required"
+          });
+        }
+        return this.reportUsage({
+          ...report,
+          requestId: report.requestId ?? context.requestId,
+          subscriptionId
+        });
+      }
+    };
   }
   /** Whether verification is required (bootstrap × opt-out). */
   async verificationRequired() {
@@ -1803,6 +2121,20 @@ var FartherShore = class {
     }
     await this.meteringClient.meter(meter, qty, options);
   }
+  /** Best-effort attested post-stream usage callback. Never rejects. */
+  async reportUsage(input) {
+    try {
+      await this.ensureBootstrapped();
+      if (!this.meteringEnabledOverride || !this.postStreamUsageClient) {
+        return { ok: false, reason: "metering is not enabled" };
+      }
+      return await this.postStreamUsageClient.reportUsage(input);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      console.warn(`post-stream usage report skipped: ${reason}`);
+      return { ok: false, reason };
+    }
+  }
   /** Current local health report. */
   health() {
     const config = this.bootstrapClient.peek();
@@ -1903,188 +2235,6 @@ function headerValue(headers, name) {
   return value;
 }
 
-// src/response-metering.ts
-var RESPONSE_METERING_HEADERS = RUNTIME_RESPONSE_METERING_CONTRACT.headers;
-var RESPONSE_METERING_ERROR_CODES = RUNTIME_RESPONSE_METERING_CONTRACT.errors;
-var devMeteringHooks = null;
-function __setDevMeteringHooks(hooks) {
-  devMeteringHooks = hooks;
-}
-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;
-  }
-};
-function createUsage(request, options = {}) {
-  const usage = {};
-  const reporter = {
-    report(meter, value) {
-      usage[assertMeterKey(meter)] = assertMeterValue(meter, value);
-      return reporter;
-    },
-    async wrap(response, wrapOptions = {}) {
-      return signResponse(request, response, usage, options, wrapOptions);
-    }
-  };
-  return reporter;
-}
-async function withUsage(request, response, usage, options = {}) {
-  const reporter = createUsage(request, options);
-  for (const [meter, value] of Object.entries(usage)) {
-    reporter.report(meter, value);
-  }
-  return reporter.wrap(response);
-}
-async function signResponse(request, response, usage, options, wrapOptions) {
-  const payload = buildPayload(request, usage, options, wrapOptions);
-  const requestId = request.headers.get("x-fs-request-id") ?? void 0;
-  const headers = await computeMeteringHeaders(payload, {
-    ...options.token !== void 0 ? { token: options.token } : {},
-    ...options.env !== void 0 ? { env: options.env } : {},
-    ...requestId ? { requestId } : {},
-    onSkip: () => {
-    }
-  });
-  if (Object.keys(headers).length === 0) {
-    throw new MeteringError(
-      RESPONSE_METERING_ERROR_CODES.missingToken,
-      `${DEFAULT_TOKEN_ENV} is required to sign Farther Shore metering reports`
-    );
-  }
-  const merged = new Headers(response.headers);
-  for (const [name, value] of Object.entries(headers)) merged.set(name, value);
-  return new Response(response.body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers: merged
-  });
-}
-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 buildPayload(request, usage, options, wrapOptions) {
-  const url = new URL(request.url);
-  const measureContext = wrapOptions.measureContext ?? options.measureContext;
-  const creditUnitsConsumed = wrapOptions.creditUnitsConsumed ?? options.creditUnitsConsumed;
-  const operationKey = wrapOptions.operationKey ?? options.operationKey;
-  const usagePolicyId = wrapOptions.usagePolicyId ?? options.usagePolicyId;
-  const payload = {
-    method: request.method.toUpperCase(),
-    path: url.pathname,
-    rawDimsUnits: sortUsage(usage),
-    ...measureContext ? { measureContext } : {},
-    ...creditUnitsConsumed ? {
-      creditUnitsConsumed: sortUsage(
-        validateUsageMap(creditUnitsConsumed, "creditUnitsConsumed")
-      )
-    } : {},
-    ...operationKey ? { operationKey: assertIdentifier(operationKey) } : {},
-    ...usagePolicyId ? { usagePolicyId: assertIdentifier(usagePolicyId) } : {}
-  };
-  return payload;
-}
-function sortUsage(usage) {
-  return Object.fromEntries(
-    Object.entries(usage).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
-  );
-}
-function validateUsageMap(usage, label) {
-  return Object.fromEntries(
-    Object.entries(usage).map(([meter, value]) => [
-      assertMeterKey(meter),
-      assertMeterValue(`${label}.${meter}`, value)
-    ])
-  );
-}
-function assertMeterKey(meter) {
-  if (!/^[a-z0-9_]{1,64}$/.test(meter)) {
-    throw new MeteringError(
-      RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
-      `meter key "${meter}" must be lowercase alphanumeric with underscores`
-    );
-  }
-  return meter;
-}
-function assertMeterValue(meter, value) {
-  if (!Number.isFinite(value) || value < 0) {
-    throw new MeteringError(
-      RESPONSE_METERING_ERROR_CODES.invalidMeterValue,
-      `meter "${meter}" value must be a non-negative finite number`
-    );
-  }
-  return value;
-}
-function assertIdentifier(value) {
-  if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(value)) {
-    throw new MeteringError(
-      RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
-      `operation and usage policy identifiers must be 1-128 URL-safe characters`
-    );
-  }
-  return value;
-}
-function processEnv(key2) {
-  const maybeProcess = globalThis.process;
-  return maybeProcess?.env?.[key2];
-}
-async function signPayload(payload, token) {
-  const key2 = await crypto.subtle.importKey(
-    "raw",
-    new TextEncoder().encode(token),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"]
-  );
-  const signature = await crypto.subtle.sign(
-    "HMAC",
-    key2,
-    new TextEncoder().encode(payload)
-  );
-  return base64url(new Uint8Array(signature));
-}
-function base64url(bytes) {
-  let binary = "";
-  for (const byte of bytes) {
-    binary += String.fromCharCode(byte);
-  }
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-
 // src/testing/signers.ts
 import { generateKeyPairSync, randomBytes } from "node:crypto";
 var TEST_KID = "fs-runtime-test-2026";
@@ -2112,7 +2262,7 @@ async function makeSignedRequest(spec = {}) {
     bodyHash,
     requestId: spec.requestId ?? `req_${cryptoRandom()}`,
     timestamp: spec.timestamp ?? Math.floor(Date.now() / 1e3),
-    productId: spec.productId ?? "prod_test",
+    businessId: spec.businessId ?? "biz_test",
     backendId: spec.backendId ?? "be_test",
     routeId: spec.routeId ?? "route_test",
     policyVersion: spec.policyVersion ?? "pv_1"
@@ -2124,7 +2274,7 @@ async function makeSignedRequest(spec = {}) {
     [RUNTIME_HEADER_NAMES.keyId]: kid,
     [RUNTIME_HEADER_NAMES.requestId]: claim.requestId,
     [RUNTIME_HEADER_NAMES.timestamp]: String(claim.timestamp),
-    [RUNTIME_HEADER_NAMES.productId]: claim.productId,
+    [RUNTIME_HEADER_NAMES.businessId]: claim.businessId,
     [RUNTIME_HEADER_NAMES.backendId]: claim.backendId,
     [RUNTIME_HEADER_NAMES.routeId]: claim.routeId,
     [RUNTIME_HEADER_NAMES.policyVersion]: claim.policyVersion,
@@ -2225,13 +2375,13 @@ function mergeHeaders(initHeaders, signedHeaders) {
   }
   return headers;
 }
-function buildContextClaim(persona, productId) {
+function buildContextClaim(persona, businessId) {
   return {
     orgId: persona.orgId ?? "org_dev",
     actor: persona.actor ?? { type: "user", id: `user_${persona.name}` },
-    // Product binding: the signed context productId MUST equal the signed
-    // request productId or verifyRequest rejects it as tamper evidence.
-    productId,
+    // Business binding: the retained signed-context productId claim MUST equal
+    // the signed request businessId or verifyRequest rejects it as tamper evidence.
+    productId: businessId,
     compiledPlanId: persona.compiledPlanId ?? "plan_dev",
     subscriptionId: persona.subscriptionId ?? "sub_dev",
     subscriberId: persona.subscriberId ?? "subscriber_dev",
@@ -2259,7 +2409,7 @@ function createPersonaClient(ctx) {
       query: spec.query ?? "",
       body: spec.body ?? null,
       streamingExempt: spec.streamingExempt ?? false,
-      productId: ctx.productId,
+      businessId: ctx.businessId,
       backendId: ctx.backendId,
       routeId: spec.routeId ?? "",
       privateJwk: ctx.keys.privateJwk,
@@ -2269,7 +2419,7 @@ function createPersonaClient(ctx) {
     });
     const headers = { ...signed.headers };
     if (!persona.anonymous) {
-      const claim = buildContextClaim(persona, ctx.productId);
+      const claim = buildContextClaim(persona, ctx.businessId);
       headers["x-fs-context"] = await signContextToken(
         claim,
         ctx.contextSecret,
@@ -2342,11 +2492,12 @@ var DEV_CORE_URL = "https://dev-gateway.farthershore.local";
 var DEV_JWKS_URL = `${DEV_CORE_URL}/.well-known/jwks.json`;
 var DEV_METERING_ENDPOINT = `${DEV_CORE_URL}/v1/metering/events`;
 function createDevGateway(options) {
-  const productId = options.productId ?? "prod_dev";
+  const businessId = options.businessId ?? "biz_dev";
   const backendId = options.backendId ?? "be_dev";
   const meterEvents = [];
+  const reportUsageEvents = [];
   const bootstrap = {
-    product: { id: productId, slug: options.productSlug ?? "dev-product" },
+    business: { id: businessId, slug: options.businessSlug ?? "dev-business" },
     backend: {
       id: backendId,
       slug: options.backendSlug ?? "dev-backend",
@@ -2394,7 +2545,10 @@ function createDevGateway(options) {
     }
     if (url.includes("/v1/metering/events")) {
       const event = await readJsonBody(init, input);
-      if (event) {
+      if (event && "meters" in event) {
+        reportUsageEvents.push(event);
+        options.onReportUsage?.(event);
+      } else if (event) {
         meterEvents.push(event);
         options.onMeterEvent?.(event);
       }
@@ -2412,7 +2566,8 @@ function createDevGateway(options) {
     fetchImpl,
     bootstrap,
     meterEvents,
-    productId,
+    reportUsageEvents,
+    businessId,
     backendId,
     jwksUrl: DEV_JWKS_URL
   };
@@ -2488,6 +2643,16 @@ var DevUsageSink = class {
       at: Date.now()
     });
   }
+  /** Record an attested post-stream report captured by the dev gateway. */
+  recordReportUsage(event) {
+    this.events.push({
+      source: "reportUsage",
+      meters: { ...event.meters },
+      event,
+      requestId: event.requestId,
+      at: Date.now()
+    });
+  }
   /** Total quantity per meter key across every recorded event. */
   byMeter() {
     const out = {};
@@ -2604,12 +2769,16 @@ function createDevRuntime(options) {
   const gateway = createDevGateway({
     mode,
     keys,
-    ...options.productId ? { productId: options.productId } : {},
+    ...options.businessId ? { businessId: options.businessId } : {},
     ...options.backendId ? { backendId: options.backendId } : {},
     ...options.routes ? { routeIds: options.routes } : {},
     onMeterEvent: (event) => {
       usage.recordMeterEvent(event);
       options.usageJsonl?.(JSON.stringify({ source: "meter", event }));
+    },
+    onReportUsage: (event) => {
+      usage.recordReportUsage(event);
+      options.usageJsonl?.(JSON.stringify({ source: "reportUsage", event }));
     }
   });
   __setDevMeteringHooks({
@@ -2629,7 +2798,7 @@ function createDevRuntime(options) {
   const personas = buildPersonaMap(options.personas);
   const personaClient = createPersonaClient({
     keys,
-    productId: gateway.productId,
+    businessId: gateway.businessId,
     backendId: gateway.backendId,
     contextSecret: keys.contextSecret,
     contextKid: keys.contextKid,
@@ -2759,7 +2928,7 @@ function createDevRuntimeFromEnv(env = readProcessEnv3()) {
     version: 1,
     mode,
     keys,
-    productId: runtime.gateway.productId,
+    businessId: runtime.gateway.businessId,
     backendId: runtime.gateway.backendId,
     personas: mapToRecord(runtime.personas)
   };
@@ -2772,7 +2941,7 @@ function printBanner(mode, runtime, tracePath) {
     "============================================================",
     "  \u26A0  FARTHER SHORE DEV MODE ACTIVE \u2014 NOT FOR PRODUCTION",
     `     mode:      ${mode.toUpperCase()}`,
-    `     product:   ${runtime.gateway.productId}`,
+    `     business:  ${runtime.gateway.businessId}`,
     `     backend:   ${runtime.gateway.backendId}`,
     `     personas:  ${[...runtime.personas.keys()].join(", ")}`,
     `     usage log: ${USAGE_JSONL_PATH}`,
@@ -2858,6 +3027,7 @@ export {
   MeteringClient,
   MeteringError,
   NonceCache,
+  PostStreamUsageClient,
   REDACTED_TOKEN,
   RUNTIME_CLOCK_SKEW_SECONDS,
   RUNTIME_ERROR_CODES,