@farthershore/backend 0.13.0 → 0.14.0

package/README.md

@@ -12,7 +12,7 @@ graceful lifecycle (health + shutdown). Everything else — your product, backen
 and environment ids, the verification keys, and the metering endpoint — is
 fetched automatically from the token at startup.
 
-> **Status: `0.13.0`.** Pre-1.0: minor releases may include breaking changes, so
+> **Status: `0.14.0`.** Pre-1.0: minor releases may include breaking changes, so
 > pin this package to an exact version (or a patch-only range) and upgrade
 > deliberately.
 
@@ -142,6 +142,40 @@ Delivery is at-least-once; the event idempotency key keeps ingestion safe.
 Background usage is tallied and billed after the cycle, not enforced in
 real time.
 
+## Post-stream usage reporting
+
+Use `fs.reportUsage()` when a gateway request streams its response and the
+billable total is known only after the stream completes. Declare that route
+with `postStreamBilling: true`, then report from the request-scoped verified
+context so the SDK retains the attested subscription subject:
+
+```ts
+const context = await fs.verifyRequest({ method, path, query, headers, body });
+
+await streamResponse(context);
+await context.reportUsage?.({
+  meters: { output_tokens: 1280 },
+  measureContext: { model: "apsu-1" },
+});
+```
+
+The callback is HMAC-attested and requires a subscription subject. Core binds it
+to the immutable gateway request row and writes one billable `UsageEvent` with
+the gateway-known request units merged with reported actual units, the served
+plan, served route, and served request time. The gateway evidence row is
+unbilled and omits only response-derived dimensions. This is a billing-only channel: it
+does not settle or mutate Durable Object enforcement windows, so units that are
+unknown at admission cannot be hard-enforced. Knowable request dimensions still
+follow the normal admission path and are billed once on the merged callback.
+
+Gateway evidence is published asynchronously. If the callback arrives first,
+Core parks the verified payload and the SDK retries only
+`post_stream_request_not_found` with bounded backoff, reusing the exact signed
+payload and nonce. A maintenance pass binds any remaining parked callback once
+evidence lands and durably alerts if it expires. The SDK method is best-effort and resolves
+`{ ok: false, reason }` instead of rejecting, so handle or log a failed report
+according to your service's delivery policy.
+
 ## Lifecycle
 
 - `fs.health()` returns the current local health report (token present, bootstrap
@@ -211,6 +245,7 @@ See `templates/3-simulated-authz.test.ts` for the full fail-closed + usage flow.
 | `withUsage()` / `createUsage()`      | Response-bound usage reporting (no network call).    |
 | `computeMeteringHeaders()`           | Metering headers as a plain map — never throws.      |
 | `fs.meter(meter, qty, opts)`         | Async/background usage event.                        |
+| `fs.reportUsage(input)`              | Attested post-stream usage callback.                 |
 | `fs.health()` / `fs.shutdown()`      | Health report and graceful shutdown.                 |
 | `FartherShoreError`, `MeteringError` | Typed errors.                                        |
 | `@farthershore/backend/testing`      | Dev-mode + persona test harness (dev/test only).     |
@@ -220,12 +255,17 @@ types directly if you prefer to wire the middleware yourself.
 
 ## Metering channels
 
-Two usage channels exist and are **not** interchangeable:
+Three usage channels exist and are **not** interchangeable:
 
 - **Response-bound** (`withUsage` / `createUsage` / `computeMeteringHeaders`) is
   the attested, request-bound settlement channel: the gateway verifies the HMAC
   and settles the reported units against the request's lease in the same
   lifecycle. Wire recipe (any language): [`docs/response-metering-wire.md`](docs/response-metering-wire.md).
+- **Post-stream** (`fs.reportUsage` or the request-scoped
+  `context.reportUsage`) is attested and request-bound for streaming routes
+  declared with `postStreamBilling: true`. It writes the sole billable row for
+  gateway-known plus reported actual units and never mutates real-time
+  enforcement windows.
 - **Background** (`fs.meter`) is a billing-only, unattested, post-cycle tally for
   usage not tied to a gateway response. It never settles a lease.
 

package/dist/generated/runtime-contract.js

@@ -173,14 +173,29 @@ var RUNTIME_METERING_CONTRACT = {
     backend_id: "string",
     route_id: "string?",
     request_id: "string?",
+    requestId: "string?",
+    subscriptionId: "string",
+    nonce: "string?",
     meter: "string",
     qty: "number",
     timestamp: "string"
   },
+  postStreamEvent: {
+    requestId: "string",
+    subscriptionId: "string?",
+    nonce: "string",
+    meters: "Record<string, number>",
+    creditUnitsConsumed: "Record<string, number>?",
+    measureContext: "Record<string, unknown>?",
+    signature: "string"
+  },
   idempotencyKey: "event_id",
   delivery: "at-least-once",
   billingOnly: true,
   realtimeEnforced: false,
+  postStreamBillingOnly: true,
+  postStreamRealtimeEnforced: false,
+  postStreamTrustModel: "HMAC-attested and bound to one served postStreamBilling gateway request. Core writes one billable UsageEvent using the served plan and time. The callback never mutates Durable Object enforcement windows.",
   trustModel: "upstream-reported values are NOT cryptographically attested; a buggy or compromised upstream can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert."
 };
 var RUNTIME_RESPONSE_METERING_CONTRACT = {

package/dist/index.js

@@ -899,6 +899,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;
@@ -1583,8 +1877,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.14.0".length > 0 ? "0.14.0" : "0.0.0-dev";
+var CONTRACTS_FP = "1feb5a4a80b447ad".length > 0 ? "1feb5a4a80b447ad" : "0000000000000000";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1602,6 +1896,7 @@ var FartherShore = class {
   shutdownManager = new ShutdownManager();
   jwks = null;
   meteringClient = null;
+  postStreamUsageClient = null;
   tunnel = null;
   bootstrapped = false;
   constructor(options = {}) {
@@ -1657,6 +1952,11 @@ var FartherShore = class {
         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,7 +2028,7 @@ 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,
@@ -1743,6 +2043,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 +2120,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 +2234,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";
@@ -2345,6 +2494,7 @@ function createDevGateway(options) {
   const productId = options.productId ?? "prod_dev";
   const backendId = options.backendId ?? "be_dev";
   const meterEvents = [];
+  const reportUsageEvents = [];
   const bootstrap = {
     product: { id: productId, slug: options.productSlug ?? "dev-product" },
     backend: {
@@ -2394,7 +2544,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,6 +2565,7 @@ function createDevGateway(options) {
     fetchImpl,
     bootstrap,
     meterEvents,
+    reportUsageEvents,
     productId,
     backendId,
     jwksUrl: DEV_JWKS_URL
@@ -2488,6 +2642,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 = {};
@@ -2610,6 +2774,10 @@ function createDevRuntime(options) {
     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({
@@ -2858,6 +3026,7 @@ export {
   MeteringClient,
   MeteringError,
   NonceCache,
+  PostStreamUsageClient,
   REDACTED_TOKEN,
   RUNTIME_CLOCK_SKEW_SECONDS,
   RUNTIME_ERROR_CODES,

package/dist/testing/index.js

@@ -864,6 +864,7 @@ function createDevGateway(options) {
   const productId = options.productId ?? "prod_dev";
   const backendId = options.backendId ?? "be_dev";
   const meterEvents = [];
+  const reportUsageEvents = [];
   const bootstrap = {
     product: { id: productId, slug: options.productSlug ?? "dev-product" },
     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,6 +935,7 @@ function createDevGateway(options) {
     fetchImpl,
     bootstrap,
     meterEvents,
+    reportUsageEvents,
     productId,
     backendId,
     jwksUrl: DEV_JWKS_URL
@@ -1269,6 +1274,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;
@@ -1947,8 +2098,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.14.0".length > 0 ? "0.14.0" : "0.0.0-dev";
+var CONTRACTS_FP = "1feb5a4a80b447ad".length > 0 ? "1feb5a4a80b447ad" : "0000000000000000";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1966,6 +2117,7 @@ var FartherShore = class {
   shutdownManager = new ShutdownManager();
   jwks = null;
   meteringClient = null;
+  postStreamUsageClient = null;
   tunnel = null;
   bootstrapped = false;
   constructor(options = {}) {
@@ -2021,6 +2173,11 @@ var FartherShore = class {
         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,7 +2249,7 @@ 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,
@@ -2107,6 +2264,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 +2341,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 +2455,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 +2502,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 = {};
@@ -2470,6 +2656,10 @@ function createDevRuntime(options) {
     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({

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. */
@@ -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. */

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

@@ -1,3 +1,4 @@
+import type { ReportUsageResult, RequestScopedReportUsageInput } from "./post-stream-usage.js";
 import { type FartherShoreSignedContext } from "./verifyContext.js";
 import type { JwksClient } from "./jwks.js";
 import type { NonceCache } from "./nonceCache.js";
@@ -48,6 +49,8 @@ export type FartherShoreRequestContext = {
     signedContext?: FartherShoreSignedContext;
     /** Managed-RBAC role keys the acting user holds (display/audit only). */
     roles?: string[];
+    /** Request-bound post-stream reporter, attached by the runtime facade. */
+    reportUsage?: (input: RequestScopedReportUsageInput) => Promise<ReportUsageResult>;
 };
 export type VerifyRequestDeps = {
     jwks: JwksClient;

package/dist/types/generated/runtime-contract.d.ts

@@ -149,14 +149,29 @@ export declare const RUNTIME_METERING_CONTRACT: {
         readonly backend_id: "string";
         readonly route_id: "string?";
         readonly request_id: "string?";
+        readonly requestId: "string?";
+        readonly subscriptionId: "string";
+        readonly nonce: "string?";
         readonly meter: "string";
         readonly qty: "number";
         readonly timestamp: "string";
     };
+    readonly postStreamEvent: {
+        readonly requestId: "string";
+        readonly subscriptionId: "string?";
+        readonly nonce: "string";
+        readonly meters: "Record<string, number>";
+        readonly creditUnitsConsumed: "Record<string, number>?";
+        readonly measureContext: "Record<string, unknown>?";
+        readonly signature: "string";
+    };
     readonly idempotencyKey: "event_id";
     readonly delivery: "at-least-once";
     readonly billingOnly: true;
     readonly realtimeEnforced: false;
+    readonly postStreamBillingOnly: true;
+    readonly postStreamRealtimeEnforced: false;
+    readonly postStreamTrustModel: "HMAC-attested and bound to one served postStreamBilling gateway request. Core writes one billable UsageEvent using the served plan and time. The callback never mutates Durable Object enforcement windows.";
     readonly trustModel: "upstream-reported values are NOT cryptographically attested; a buggy or compromised upstream can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert.";
 };
 export declare const RUNTIME_RESPONSE_METERING_CONTRACT: {

package/dist/types/index.d.ts

@@ -11,6 +11,7 @@ export { JwksClient, type Jwk, type JwksClientOptions } from "./core/jwks.js";
 export { NonceCache, type NonceCacheOptions } from "./core/nonceCache.js";
 export { BootstrapClient, type BootstrapClientOptions, } from "./core/bootstrap.js";
 export { MeteringClient, type MeteringClientOptions, type MeterOptions, } from "./core/metering.js";
+export { PostStreamUsageClient, type PostStreamUsageClientOptions, type ReportUsageInput, type RequestScopedReportUsageInput, type ReportUsageResult, } from "./core/post-stream-usage.js";
 export { buildHealthReport, reportHealth, type HealthSnapshot, type HealthStatus, type HeartbeatOptions, } from "./core/health.js";
 export { ShutdownManager, type ShutdownHook } from "./core/shutdown.js";
 export { CloudflaredSupervisor, nodeSpawn, REDACTED_TOKEN, type SpawnFn, type SpawnedTunnelProcess, type CloudflaredSupervisorOptions, type TunnelState, type TunnelStatus, } from "./core/tunnel.js";

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

@@ -255,6 +255,16 @@ export type RuntimeMeteringEvent = {
     qty: number;
     timestamp: string;
 };
+/** Attested, request-bound billing callback sent after a stream completes. */
+export type RuntimePostStreamUsageEvent = {
+    requestId: string;
+    subscriptionId: string;
+    nonce: string;
+    meters: Record<string, number>;
+    creditUnitsConsumed?: Record<string, number>;
+    measureContext?: Record<string, unknown>;
+    signature: string;
+};
 export declare const RUNTIME_READINESS_STATES: readonly ["UNKNOWN", "WAITING", "READY", "DEGRADED", "OFFLINE"];
 export type RuntimeReadinessState = (typeof RUNTIME_READINESS_STATES)[number];
 export type RuntimeHealthReport = {

package/dist/types/testing/devGateway.d.ts

@@ -1,4 +1,4 @@
-import { type RuntimeBootstrapResponse, type RuntimeMeteringEvent } from "../runtime-types.js";
+import { type RuntimeBootstrapResponse, type RuntimeMeteringEvent, type RuntimePostStreamUsageEvent } from "../runtime-types.js";
 import type { DevMode } from "./traceSink.js";
 import type { DevSignerKeys } from "./signers.js";
 export declare const DEV_CORE_URL = "https://dev-gateway.farthershore.local";
@@ -15,6 +15,8 @@ export type DevGatewayOptions = {
     routeIds?: string[];
     /** Called for each captured metering event (at-least-once ACK). */
     onMeterEvent?: (event: RuntimeMeteringEvent) => void;
+    /** Called for each captured attested post-stream report. */
+    onReportUsage?: (event: RuntimePostStreamUsageEvent) => void;
 };
 export type DevGateway = {
     /** Inject this as `fetchImpl` when constructing the FartherShore runtime. */
@@ -23,6 +25,8 @@ export type DevGateway = {
     bootstrap: RuntimeBootstrapResponse;
     /** Every captured background metering event (a capture == an ACK). */
     meterEvents: RuntimeMeteringEvent[];
+    /** Every captured attested post-stream usage report. */
+    reportUsageEvents: RuntimePostStreamUsageEvent[];
     productId: string;
     backendId: string;
     jwksUrl: string;

package/dist/types/testing/usageSink.d.ts

@@ -1,4 +1,4 @@
-import type { RuntimeMeteringEvent } from "../runtime-types.js";
+import type { RuntimeMeteringEvent, RuntimePostStreamUsageEvent } from "../runtime-types.js";
 /** One recorded usage observation. `source` distinguishes the two channels. */
 export type DevUsageEvent = {
     source: "response";
@@ -16,6 +16,12 @@ export type DevUsageEvent = {
     event: RuntimeMeteringEvent;
     requestId?: string;
     at: number;
+} | {
+    source: "reportUsage";
+    meters: Record<string, number>;
+    event: RuntimePostStreamUsageEvent;
+    requestId: string;
+    at: number;
 };
 /** In-memory, assertable sink for all dev usage. */
 export declare class DevUsageSink {
@@ -24,6 +30,8 @@ export declare class DevUsageSink {
     recordResponse(payload: Record<string, unknown>, requestId?: string): void;
     /** Record a background `fs.meter()` event captured by the dev gateway. */
     recordMeterEvent(event: RuntimeMeteringEvent): void;
+    /** Record an attested post-stream report captured by the dev gateway. */
+    recordReportUsage(event: RuntimePostStreamUsageEvent): void;
     /** Total quantity per meter key across every recorded event. */
     byMeter(): Record<string, number>;
     /** Clear all recorded usage. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Farther Shore backend SDK for builder upstreams: signed response usage, fail-closed gateway request verification, health, and lifecycle from FS_RUNTIME_TOKEN",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,8 +37,8 @@
   },
   "optionalDependencies": {
     "@farthershore/cloudflared-linux-x64": "0.0.0",
-    "@farthershore/cloudflared-darwin-arm64": "0.0.0",
     "@farthershore/cloudflared-linux-arm64": "0.0.0",
+    "@farthershore/cloudflared-darwin-arm64": "0.0.0",
     "@farthershore/cloudflared-darwin-x64": "0.0.0"
   },
   "peerDependencies": {