@farthershore/backend 0.12.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.12.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
@@ -149,6 +183,58 @@ real time.
 - `fs.shutdown()` flushes any buffered metering and sends a `stopping` heartbeat.
   Call it on `SIGTERM` / `SIGINT` for graceful shutdown.
 
+## Local development & testing — the mode ladder
+
+You do not need the platform to test a backend that runs behind it. Pick the
+lowest tier that answers your question — each is a superset of the one below.
+
+**Tier 0 — off (needs NOTHING from the SDK).** Unit-test your business logic
+directly. The gateway sits in front of you in production; your pure handlers
+don't import Farther Shore to be tested. There is no SDK step at this tier — see
+`templates/1-unit.test.ts`.
+
+**Tier 1 — passthrough.** Run your real app over HTTP with `fs.middleware()`
+mounted but verification OFF, matching the pre-keystone deploy order: the
+middleware passes requests through without attaching a context, so your routes
+run normally. Activate with `FS_DEV_MODE=passthrough`. See
+`templates/2-passthrough-http.test.ts`.
+
+**Tier 2 — simulated.** A real runtime wired to an in-process gateway with
+fail-closed verification ON and SIGNED personas driving requests. Assert the
+fail-closed boundary (a persona without a permission gets 403) and that usage is
+metered. Activate with `FS_DEV_MODE=simulated`, or construct explicitly:
+
+```ts
+import { createDevRuntime, definePersona } from "@farthershore/backend/testing";
+
+const rt = createDevRuntime({
+  mode: "simulated",
+  personas: {
+    creator: definePersona({
+      name: "creator",
+      permissions: ["widgets:create"],
+    }),
+  },
+});
+
+// Sign a request as a persona and drive your app (supertest, fetch, or inject):
+const headers = await rt.asPersona("creator").headers({ path: "/v1/widgets" });
+// rt.usage.byMeter()   → assert reported usage
+// rt.trace.forRequest(id) → why a request verified / was denied
+```
+
+`@farthershore/backend/testing` gives you signed personas (owner / admin /
+member / anonymous, plus your own), an in-process gateway fixture, and
+assertable `usage` + per-request `trace` side channels. It is dev/test tooling
+only — **it throws when `NODE_ENV=production`**, and `FS_DEV_MODE` is never a
+required-at-boot variable. When `FS_DEV_MODE` is set, `initFromEnv()`
+self-constructs the simulator (ephemeral keys, a loud banner, JSONL usage/trace
+logs under `.farthershore/`, and a mode-600 `.farthershore/dev-keys.json` so a
+separate test-runner process can sign against a running service via
+`personaClientFromKeysFile`).
+
+See `templates/3-simulated-authz.test.ts` for the full fail-closed + usage flow.
+
 ## Key exports
 
 | Export                               | Purpose                                              |
@@ -157,13 +243,32 @@ real time.
 | `fs.middleware()`                    | Express fail-closed verify → `req.fartherShore`.     |
 | `fs.verifyRequest({...})`            | Framework-neutral request verification.              |
 | `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).     |
 
 A subpath export, `@farthershore/backend/express`, exposes the Express adapter
 types directly if you prefer to wire the middleware yourself.
 
+## Metering channels
+
+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.
+
 ## Learn more
 
 - Platform documentation: https://docs.farthershore.com

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 = {