@farthershore/backend 0.13.0 → 0.15.0

package/README.md

@@ -1,6 +1,6 @@
 # @farthershore/backend
 
-The runtime SDK for your own backend. When you run a software product on Farther
+The runtime SDK for your own backend. When you run a software business on Farther
 Shore with a bring-your-own-backend, the platform's edge gateway sits in front of
 your service. This package lets your backend **trust the gateway** (verify that
 each request really came from it) and **report usage** back for metering and
@@ -8,11 +8,11 @@ billing — from a single token, `FS_RUNTIME_TOKEN`.
 
 Install one package, set one environment variable, and you get fail-closed
 gateway-to-upstream request verification, response-bound usage reporting, and
-graceful lifecycle (health + shutdown). Everything else — your product, backend,
+graceful lifecycle (health + shutdown). Everything else — your business, backend,
 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.15.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.
 
@@ -76,7 +76,7 @@ process.on("SIGTERM", () => void fs.shutdown());
 ## What `initFromEnv()` derives
 
 You configure exactly one thing: `FS_RUNTIME_TOKEN` (mint it for your backend
-with the Farther Shore CLI or dashboard). Everything else — product / backend /
+with the Farther Shore CLI or dashboard). Everything else — business / backend /
 environment ids, the JWKS url used to verify signatures, the metering endpoint
 and credential, and verification settings — is fetched from the platform at
 startup and cached in memory. The token is validated eagerly, so a
@@ -126,11 +126,11 @@ export async function POST(request: Request) {
 
 - `measureContext` is free-form pricing/analytics context persisted with the
   usage event.
-- `creditUnitsConsumed` is a numeric map for credit-wallet style products; keys
+- `creditUnitsConsumed` is a numeric map for credit-wallet style businesses; keys
   and values are validated locally before signing.
 
 The meter keys you report (e.g. `tokens_used`) must match meters declared in your
-product. Request-count style limits are enforced by the gateway and need no
+business. Request-count style limits are enforced by the gateway and need no
 backend code.
 
 ## Async / background usage
@@ -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

@@ -83,7 +83,7 @@ var RUNTIME_SIGNING_CONTRACT = {
       "body-hash",
       "request-id",
       "timestamp",
-      "product-id",
+      "business-id",
       "backend-id",
       "route-id",
       "policy-version"
@@ -95,7 +95,7 @@ var RUNTIME_SIGNING_CONTRACT = {
       "body-hash": "Lowercase hex SHA-256 of the RAW request body bytes. For an empty body, the SHA-256 of zero bytes (e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855). Streaming-exempt requests use the literal token 'STREAM'.",
       "request-id": "Opaque unique request id minted by the gateway (also the replay-cache nonce).",
       timestamp: "Integer Unix epoch seconds (UTC) at signing time, as a base-10 string with no padding.",
-      "product-id": "Product id the request is routed to.",
+      "business-id": "Business id the request is routed to.",
       "backend-id": "Backend id the route binds to.",
       "route-id": "Resolved route id; empty string if the route is unresolved.",
       "policy-version": "Tenant artifact / policy version the gateway signed under."
@@ -109,7 +109,7 @@ var RUNTIME_CANONICAL_FIELDS = [
   "body-hash",
   "request-id",
   "timestamp",
-  "product-id",
+  "business-id",
   "backend-id",
   "route-id",
   "policy-version"
@@ -133,7 +133,7 @@ var RUNTIME_HEADERS = {
   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",
@@ -169,18 +169,33 @@ var RUNTIME_METERING_CONTRACT = {
   credential: "reusable-bearer",
   event: {
     event_id: "string",
-    product_id: "string",
+    business_id: "string",
     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 = {