@farthershore/backend 0.13.0 → 0.15.0

package/dist/testing/index.js

@@ -294,7 +294,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",
@@ -346,7 +346,7 @@ var CANONICAL_SIGNING_FIELDS = [
   "body-hash",
   "request-id",
   "timestamp",
-  "product-id",
+  "business-id",
   "backend-id",
   "route-id",
   "policy-version"
@@ -383,7 +383,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
@@ -608,7 +608,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"
@@ -620,7 +620,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,
@@ -742,13 +742,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",
@@ -776,7 +776,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,
@@ -786,7 +786,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,
@@ -861,11 +861,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",
@@ -913,7 +914,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);
       }
@@ -931,7 +935,8 @@ function createDevGateway(options) {
     fetchImpl,
     bootstrap,
     meterEvents,
-    productId,
+    reportUsageEvents,
+    businessId,
     backendId,
     jwksUrl: DEV_JWKS_URL
   };
@@ -1131,7 +1136,7 @@ var DEFAULT_MAX_RETRIES = 3;
 var MeteringClient = class {
   config;
   endpoint;
-  productId;
+  businessId;
   backendId;
   fetchImpl;
   maxRetries;
@@ -1145,7 +1150,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;
@@ -1208,13 +1213,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();
@@ -1269,6 +1275,152 @@ 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;
+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;
@@ -1775,12 +1927,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"
@@ -1816,10 +1968,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) {
@@ -1841,7 +1993,7 @@ async function verifyRequest(input, deps) {
     bodyHash: computedBodyHash,
     requestId,
     timestamp,
-    productId: signedProductId,
+    businessId: signedBusinessId,
     backendId: signedBackendId,
     routeId: signedRouteId,
     policyVersion
@@ -1881,10 +2033,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") {
@@ -1904,7 +2056,7 @@ async function verifyRequest(input, deps) {
   }
   return {
     requestId,
-    productId: signedProductId,
+    businessId: signedBusinessId,
     backendId: signedBackendId,
     routeId: signedRouteId,
     policyVersion,
@@ -1947,8 +2099,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;
@@ -1966,6 +2118,7 @@ var FartherShore = class {
   shutdownManager = new ShutdownManager();
   jwks = null;
   meteringClient = null;
+  postStreamUsageClient = null;
   tunnel = null;
   bootstrapped = false;
   constructor(options = {}) {
@@ -2016,11 +2169,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;
@@ -2092,10 +2250,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,
@@ -2107,6 +2265,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() {
@@ -2167,6 +2342,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();
@@ -2267,18 +2456,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;
-
 // src/testing/prodGuard.ts
 function isProductionEnv(env = readProcessEnv2()) {
   return (env.NODE_ENV ?? "").trim().toLowerCase() === "production";
@@ -2326,6 +2503,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 = {};
@@ -2437,7 +2624,7 @@ function personaClientFromKeysFile(path = DEFAULT_KEYS_FILE, options = {}) {
   const file = readDevKeysFile(path);
   const client = createPersonaClient({
     keys: file.keys,
-    productId: file.productId,
+    businessId: file.businessId,
     backendId: file.backendId,
     contextSecret: file.keys.contextSecret,
     contextKid: file.keys.contextKid,
@@ -2464,12 +2651,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({
@@ -2489,7 +2680,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,
@@ -2619,7 +2810,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)
   };
@@ -2632,7 +2823,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}`,

package/dist/types/core/metering.d.ts

@@ -2,6 +2,12 @@ import type { RuntimeMeteringConfig } from "../runtime-types.js";
 export type MeterOptions = {
     requestId?: string;
     routeId?: string;
+    /** Subscription to attribute the usage to (billing identity). Pass the
+     *  verified request context's `signedContext.subscriptionId` when metering
+     *  inside a request handler. Without it (and without `requestId`, which core
+     *  can resolve back to the served gateway request), core persists the event
+     *  UNBILLED and flags it unattributable. */
+    subscriptionId?: string;
     /** Override event_id (idempotency key). Defaults to a random uuid. */
     eventId?: string;
     /** Override the timestamp (ISO-8601). Defaults to now. */
@@ -9,7 +15,7 @@ export type MeterOptions = {
 };
 export type MeteringClientOptions = {
     config: RuntimeMeteringConfig;
-    productId: string;
+    businessId: string;
     backendId: string;
     /** Core base URL when the config endpoint is a relative path. */
     coreUrl?: string;
@@ -36,7 +42,7 @@ export type MeteringClientOptions = {
 export declare class MeteringClient {
     private readonly config;
     private readonly endpoint;
-    private readonly productId;
+    private readonly businessId;
     private readonly backendId;
     private readonly fetchImpl;
     private readonly maxRetries;

package/dist/types/core/post-stream-usage.d.ts

@@ -0,0 +1,45 @@
+import type { RuntimeMeteringConfig } from "../runtime-types.js";
+export type ReportUsageInput = {
+    requestId: string;
+    subscriptionId: string;
+    meters: Record<string, number>;
+    creditUnitsConsumed?: Record<string, number>;
+    measureContext?: Record<string, unknown>;
+};
+export type RequestScopedReportUsageInput = Omit<ReportUsageInput, "requestId" | "subscriptionId"> & {
+    requestId?: string;
+    subscriptionId?: string;
+};
+export type ReportUsageResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type PostStreamUsageClientOptions = {
+    config: RuntimeMeteringConfig;
+    coreUrl?: string;
+    fetchImpl?: typeof fetch;
+    newNonce?: () => string;
+    logger?: (message: string) => void;
+    /** Injectable for tests; defaults to a normal timer-backed delay. */
+    sleep?: (delayMs: number) => Promise<void>;
+    /** Backoff after each request-not-found response. */
+    retryDelaysMs?: readonly number[];
+};
+/**
+ * Best-effort, attested post-stream billing reporter. The callback is
+ * request-bound in Core but never settles a Durable Object enforcement window.
+ * Every failure resolves ok:false.
+ */
+export declare class PostStreamUsageClient {
+    private readonly config;
+    private readonly endpoint;
+    private readonly fetchImpl;
+    private readonly newNonce;
+    private readonly logger;
+    private readonly sleep;
+    private readonly retryDelaysMs;
+    constructor(options: PostStreamUsageClientOptions);
+    reportUsage(input: ReportUsageInput): Promise<ReportUsageResult>;
+}

package/dist/types/core/runtime.d.ts

@@ -1,6 +1,7 @@
 import { type RuntimeBootstrapResponse, type RuntimeHealthReport } from "../runtime-types.js";
 import type { ReconcileResult } from "../reflect/reconcile.js";
 import { type MeterOptions } from "./metering.js";
+import { type ReportUsageInput, type ReportUsageResult } from "./post-stream-usage.js";
 import { type SpawnFn } from "./tunnel.js";
 import { type FartherShoreRequestContext, type VerifyRequestInput } from "./verifyRequest.js";
 /** Advanced opt-in tunnel config. The embedded runner is the default DX. */
@@ -44,7 +45,7 @@ export type FartherShoreInitOptions = {
      * `X-Fs-Context` claim. These are the GATEWAY CONTEXT-SIGNING keyring values
      * (`CONTEXT_SIGNING_KEYS_JSON` — the keys `forward-upstream` stamps the
      * header with; supply every live key during rotation — try-all). They are
-     * NOT the product's `contextTokenSecret`, which signs `fsc_` INGRESS tokens
+     * NOT the business's `contextTokenSecret`, which signs `fsc_` INGRESS tokens
      * verified BY the gateway — setting that here would reject every valid
      * gateway request in `"required"` mode. When present, a VERIFIED context's
      * `permissions`/`roles` claims are the AUTHORITATIVE identity source
@@ -53,8 +54,8 @@ export type FartherShoreInitOptions = {
      *
      * NOTE (core-side dependency, FAR-723 publish gate): no bootstrap field
      * carries these keys yet, and handing the raw platform keyring to builder
-     * backends is NOT the end-state (it would allow cross-product context
-     * forgery). The distribution mechanism — per-product derived keys or an
+     * backends is NOT the end-state (it would allow cross-business context
+     * forgery). The distribution mechanism — per-business derived keys or an
      * asymmetric context signature verified via JWKS like the request
      * signature — is decided at the FAR-723 gate before the headers retire;
      * until then this option (or `FS_CONTEXT_SECRETS`) is the manual wiring for
@@ -95,6 +96,7 @@ export declare class FartherShore {
     private readonly shutdownManager;
     private jwks;
     private meteringClient;
+    private postStreamUsageClient;
     private tunnel;
     private bootstrapped;
     constructor(options?: FartherShoreInitOptions);
@@ -137,6 +139,8 @@ export declare class FartherShore {
     start(): Promise<void>;
     /** Record metering usage (billing-only). */
     meter(meter: string, qty: number, options?: MeterOptions): Promise<void>;
+    /** Best-effort attested post-stream usage callback. Never rejects. */
+    reportUsage(input: ReportUsageInput): Promise<ReportUsageResult>;
     /** Current local health report. */
     health(): RuntimeHealthReport;
     /** Graceful shutdown: flush metering + send a stopping heartbeat. */