@farthershore/backend 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -4,6 +4,145 @@ All notable changes to the runtime backend SDK are documented here. This SDK
 versions independently from the frontend and business SDKs. Pre-1.0: minor
 versions may include breaking changes.
 
+## [0.21.0] - 2026-09-05
+
+### Added — `@farthershore/backend/webhooks`: consuming platform webhooks is first class
+
+The platform now signs every builder webhook with the open
+[Standard Webhooks](https://www.standardwebhooks.com) format
+(`webhook-id` / `webhook-timestamp` / `webhook-signature: v1,<base64>` over
+`${id}.${timestamp}.${body}`, ±300 s) and delivers a typed envelope
+`{ id, type, createdAt, businessId, environmentId, data }`. The new subpath
+consumes it:
+
+- `createWebhookHandler({ secret | secrets, on, onUnknown?, onRejected?, onDuplicate?, nonceStore? })`
+  verifies the signature over the raw body (any `v1,` entry, so the
+  platform's 24 h dual-signing after a rotation just works), rejects stale /
+  future timestamps, deduplicates on `webhook-id` via a bounded delivery-id
+  lease store (claim before the handler, settle after — distinct from the
+  request verifier's nonce cache), parses the envelope, and routes to
+  typed per-event handlers. Unknown event types and duplicates are
+  acknowledged 2xx; a thrown handler is a 500 (the platform retries) and the
+  delivery id is released so that retry runs the handler again.
+- `.express()` (mount after `express.raw()`) and `.fetch` (Request → Response)
+  adapters; `handle()` is the framework-neutral core.
+- `verifyWebhook({ body, headers, secrets })` — the bare primitive.
+- Typed `WebhookEnvelope<T>` / `WebhookEventData` / `WEBHOOK_EVENT_NAMES`
+  (7 subscribable events + the synthetic `webhook.test`).
+- `signWebhookForTesting()` in `@farthershore/backend/testing` builds a
+  platform-identical signed delivery for receiver tests. Conformance is
+  proven both ways against the reference `standardwebhooks` library.
+
+### Removed — BREAKING: eleven unused constants from `@farthershore/backend/runtime`
+
+The `runtime` subpath previously re-stated the wire protocol as prose constant
+blobs, emitted by a codegen step from a `fern/runtime-contract.json` mirror.
+That mirror and its codegen are deleted; the constants nothing imported went
+with them, because they duplicated — and had drifted from — types this package
+already declares correctly.
+
+Removed: `RUNTIME_CONTRACT_VERSION`, `RUNTIME_TOKEN_ENV`,
+`RUNTIME_TOKEN_CONTRACT`, `RUNTIME_BOOTSTRAP_CONTRACT`,
+`RUNTIME_SIGNING_CONTRACT`, `RUNTIME_CANONICAL_FIELDS`, `RUNTIME_HEADERS`,
+`RUNTIME_REPLAY_CONTRACT`, `RUNTIME_METERING_CONTRACT`,
+`RUNTIME_HEALTH_CONTRACT`, `RUNTIME_TRANSPORT_CONTRACT`.
+
+**Replacements — all already exported from the package root (`.`), typed rather
+than stringly-described:**
+
+| removed                      | use instead                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RUNTIME_BOOTSTRAP_CONTRACT` | the `RuntimeBootstrapResponse` type                                                                                                                                                                                                                                                                                          |
+| `RUNTIME_TOKEN_ENV`          | `FS_RUNTIME_TOKEN_ENV`                                                                                                                                                                                                                                                                                                       |
+| `RUNTIME_HEADERS`            | `RUNTIME_HEADER_NAMES`                                                                                                                                                                                                                                                                                                       |
+| `RUNTIME_REPLAY_CONTRACT`    | `RUNTIME_CLOCK_SKEW_SECONDS`, `RUNTIME_REPLAY_WINDOW_SECONDS`                                                                                                                                                                                                                                                                |
+| `RUNTIME_CANONICAL_FIELDS`   | `buildCanonicalSigningString()` — exported at runtime, with the load-bearing field order baked in; the order is also specified in metering-runtime-spec §3. (`CanonicalSigningInput` types that function's input but is erased at runtime and carries no order, so it is NOT a replacement for callers that read the array.) |
+| `RUNTIME_SIGNING_CONTRACT`   | metering-runtime-spec §3 + `docs/superpowers/specs/fixtures/signing-vectors.json`                                                                                                                                                                                                                                            |
+| `RUNTIME_METERING_CONTRACT`  | metering-runtime-spec §8; for the post-stream callback, `postStreamUsageSchema` in `apps/core/src/routes/runtime.ts`                                                                                                                                                                                                         |
+| `RUNTIME_HEALTH_CONTRACT`    | the `RuntimeHealthReport` type                                                                                                                                                                                                                                                                                               |
+| `RUNTIME_TRANSPORT_CONTRACT` | the `TransportMode` type                                                                                                                                                                                                                                                                                                     |
+| `RUNTIME_CONTRACT_VERSION`   | no replacement — it versioned the deleted mirror, not the wire                                                                                                                                                                                                                                                               |
+| `RUNTIME_TOKEN_CONTRACT`     | `RUNTIME_TOKEN_PREFIXES`, `RUNTIME_TOKEN_OPERATIONS`                                                                                                                                                                                                                                                                         |
+
+`RUNTIME_ERROR_CODES`, `RuntimeErrorCode`, `RUNTIME_BODY_HASH_CONTRACT` and
+`RUNTIME_RESPONSE_METERING_CONTRACT` are UNCHANGED — they are imported by real
+code, and every field of them with a canonical owner in
+`@farthershore/contracts` is now pinned to it by
+`src/generated/runtime-contract-parity.test.ts`.
+
+### Changed — BREAKING: the reporting surface is now ONE verb (FAR-907)
+
+- **`ctx.report({ meter, values, dims?, quote? })`** on the verified context is
+  the only reporting surface. Backends report **measurements, never money**;
+  the platform owns what they cost.
+
+  - **Transport is an implementation detail.** Before the response is sent the
+    measurement rides signed in-band `x-fs-metering` headers (no network call);
+    after `res.end()`, or from a background job holding the context, it goes
+    over the attested post-stream channel with the SAME served identity. The
+    builder never chooses.
+  - **No identity ceremony.** Subscription/served identity is read off the
+    already-signed context, so the UNBILLED-by-forgotten-`subscriptionId`
+    failure mode is structurally unreachable. `report()` on a context the
+    runtime did not produce throws an error naming the fix.
+  - **`quote`** is the one bounded money channel: a PROPOSED rate input
+    (`{ currency, amountNanos }`) for a `backendQuoted` pricing rule. Core
+    clamps it to the repo-authored bounds; the SDK rejects only malformed input.
+
+- **Removed (hard cut, no shims):** `withUsage`, `createUsage`, `UsageReporter`,
+  `MeteringOptions`, `UsageMap`, `MeteringClient` (+ options/`MeterOptions`),
+  `fs.meter()`, `fs.reportUsage()`, `ctx.reportUsage()`, and the
+  `PostStreamUsageClient` public surface. The post-stream transport survives as
+  private machinery behind `report()`. `computeMeteringHeaders()` stays as the
+  framework-neutral wire recipe for non-JS backends.
+
+- **Wire (additive):** the signed metering payload and the post-stream event
+  gain `measurementsVersion: 1`, `measurements: [{ meter, values, dims? }]`, and
+  `quote` (non-negative — a quote is a proposed rate, never a credit).
+  `rawDimsUnits` / `meters` remain the flat structural projection the existing
+  settlement path reads, keyed by the METER id with the sum of the
+  measurement's measure values as its quantity (the gateway masks this lane by
+  the route's declared meter ids, so measure-keyed entries would be silently
+  discarded — UNBILLED). The runtime token's `allowedMeters` scope is enforced
+  on BOTH lanes independently: every `meters` key AND every
+  `measurements[].meter` must be in scope.
+
+## [0.20.0] - 2026-08-07
+
+### Changed
+
+- **An injected shared nonce store now fails closed on outage.** If you supply
+  `nonceStore`, a throw from it rejects the request instead of falling through
+  to "not a replay" — otherwise knocking that store over would switch
+  one-time-use enforcement off entirely. No effect on the default in-memory
+  cache, which cannot fail this way.
+
+  `fs.replayProtection()` reports whether enforcement is `"shared"`
+  (cross-replica) or `"single-instance"` (this process), for boot logging.
+
+  Replay protection remains **zero-config**: the signature's ~305s time window
+  is the always-on defense and needs nothing from you. A shared store is purely
+  an opt-in upgrade for builders who want one-time-use enforced across replicas
+  rather than within each one. (FAR-760)
+
+### Security
+
+- **A stale JWKS key set is no longer trusted forever.** The client held the
+  last successful fetch indefinitely, so during a prolonged Core/JWKS outage a
+  revoked signing key kept verifying. Stale-while-revalidate now has a ceiling:
+  fresh (<5m) → soft-stale (<15m, still served if refresh fails) → hard-stale
+  (fail closed). Adds an `onObservation` hook reporting
+  `fresh` / `soft_stale` / `hard_stale` / `cold`. (FAR-759)
+
+### Fixed
+
+- **Every outbound SDK call now has a deadline.** Bootstrap, JWKS refresh,
+  metering flush, post-stream usage, the health heartbeat and the drift report
+  all awaited without an `AbortSignal`; a half-open connection could wedge
+  request verification, boot, readiness, or usage reporting indefinitely.
+  Caller cancellation composes with the SDK deadline, timeouts are classifiable,
+  and parsed response bodies are byte-bounded. (FAR-785)
+
 ## [0.19.0]
 
 ### Added

package/README.md

@@ -12,7 +12,7 @@ graceful lifecycle (health + shutdown). Everything else — your business, backe
 and environment ids, the verification keys, and the metering endpoint — is
 fetched automatically from the token at startup.
 
-> **Status: `0.19.0`.** Pre-1.0: minor releases may include breaking changes, so
+> **Status: `0.21.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.
 
@@ -28,7 +28,7 @@ Requires Node 22+. The Express adapter has an optional `express` peer dependency
 ## Quick start (any Fetch-compatible handler)
 
 ```ts
-import { fartherShore, withUsage } from "@farthershore/backend";
+import { fartherShore } from "@farthershore/backend";
 
 const fs = fartherShore.initFromEnv(); // derives everything from FS_RUNTIME_TOKEN
 
@@ -38,7 +38,7 @@ export async function POST(request: Request) {
 
   // Fail-closed: throws a FartherShoreError if the request is not a genuine,
   // unmodified request signed by the gateway.
-  await fs.verifyRequest({
+  const ctx = await fs.verifyRequest({
     method: request.method,
     path: url.pathname,
     query: url.search,
@@ -48,10 +48,15 @@ export async function POST(request: Request) {
 
   const result = await runWorkflow(await request.json());
 
-  // Report usage on the way out — no extra network call.
-  return withUsage(request, Response.json(result), {
-    tokens_used: result.tokensUsed,
+  // ONE reporting verb. No identity argument (the verified context carries the
+  // served identity) and no transport argument (the SDK picks one).
+  await ctx.report({
+    meter: "model_usage",
+    values: { tokens_used: result.tokensUsed },
+    dims: { model: result.model },
   });
+
+  return Response.json(result);
 }
 ```
 
@@ -66,6 +71,12 @@ app.use(fs.middleware()); // fail-closed verify -> req.fartherShore
 
 app.post("/v1/runs", async (req, res) => {
   const result = await runWorkflow(req.body);
+
+  await req.fartherShore.report({
+    meter: "model_usage",
+    values: { tokens_used: result.tokensUsed },
+  });
+
   res.json(result);
 });
 
@@ -99,82 +110,246 @@ wrong-route / body-hash-mismatch / replayed-nonce / unknown-key /
 keys-unavailable) throws a typed `FartherShoreError` that maps to **HTTP 401**
 (413 for oversized bodies). There is no fail-open path.
 
-## Response-bound usage reporting
+### Replay protection (nothing to configure)
+
+A signed request is one-time-use, and two things enforce that:
+
+- **A time window, always on.** The gateway signs a timestamp into the request;
+  anything older than ~305s (replay window + clock skew) is rejected outright.
+  This holds for every deployment shape and needs nothing from you.
+- **A seen-id list.** Inside that window, the SDK remembers each
+  `X-Fs-Request-Id` it has accepted and rejects a second sighting. The default
+  list is in-memory and per-process.
 
-Use `withUsage()` (or the builder-style `createUsage()`) when you know the usage
-for a request while you are returning the response. These helpers make **no
-network call** — they sign the usage into internal response headers, and the
-gateway verifies, settles, and strips those headers before your subscriber sees
-the response.
+That default is deliberate: running more than one replica means each has its own
+list, so a captured request could be replayed once per replica **within the
+~305s window** — and closing that would mean asking you to provision and operate
+a distributed cache. We would rather keep your setup to one environment variable
+and let the time window bound the exposure.
+
+If you do want one-time-use enforced across replicas, inject a shared store:
 
 ```ts
-import { withUsage } from "@farthershore/backend";
+initFromEnv({ nonceStore: myStore }); // checkAndRemember(id) => boolean | Promise<boolean>
+```
 
-export async function POST(request: Request) {
-  const result = await runWorkflow(await request.json());
-  return withUsage(
-    request,
-    Response.json(result),
-    { tokens_used: result.tokensUsed },
-    {
-      measureContext: { model: result.model },
-      creditUnitsConsumed: { credits: result.creditsUsed },
-    },
-  );
+Make it TTL-bound to the signature validity window. If that store goes down,
+requests fail **closed** — it never degrades to "not a replay".
+`fs.replayProtection()` reports which mode is active (`"shared"` |
+`"single-instance"`) if you want it in your boot logs.
+
+## Authorization — the permission grammar & in-handler checks
+
+The edge `permission` constraint is the route-level security boundary: the
+gateway resolves the acting user's effective permissions at token mint and
+carries them in the signed `X-Fs-Context` claim. These SDK helpers exist for
+**finer-grained, in-handler** checks the route layer can't express (field- or
+record-level gating).
+
+### The grammar
+
+A permission is a plain string, checked with three rungs:
+
+- `*` — the global wildcard. Grants **every** key (org OWNER, RBAC disabled,
+  personal orgs — the gateway stamps an explicit `["*"]`).
+- `<subject>:*` — the subject wildcard, e.g. `widgets:*` grants `widgets:read`,
+  `widgets:write`, and any other `widgets:<verb>`. (A literal `*` subject never
+  takes this rung — only the bare `*` grant is global.)
+- exact keys — e.g. `widgets:write`. **Custom permission strings work**: any
+  `<subject>:<verb>` you invent is checked verbatim; there is no fixed verb
+  vocabulary at this layer.
+
+Route-shaped keys follow `routePermission(subject, method)` — `<subject>:read`
+for safe verbs (GET / HEAD / OPTIONS, any casing) and `<subject>:write` for
+everything else — the SAME helper the platform uses to derive a route's
+required permission, exported here so you never re-spell the suffix.
+
+**Fail-closed at the carrier**: an **absent** permission set
+(`ctx.permissions === undefined`) always **denies** — absence never means
+grant-all, even on a fully verified request. `[]` (authenticated, no grants)
+also denies. A route you don't want gated simply doesn't call a check.
+
+### Checking permissions
+
+```ts
+// Namespace form — dev (`rt.authz`, traced) and prod (`fs.authz`) match:
+app.post(
+  "/v1/widgets",
+  fs.middleware(),
+  fs.handler((ctx, req, res) => {
+    fs.authz.requirePermission(ctx, "widgets:write"); // throws 403 permission_denied
+    // or: if (fs.authz.hasPermission(ctx, "widgets:publish")) { ... }
+    res.json({ ok: true });
+  }),
+);
+
+// Declarative form — the handler options overload runs the same fail-closed
+// check BEFORE your callback:
+app.post(
+  "/v1/widgets",
+  fs.middleware(),
+  fs.handler({ permission: "widgets:write" }, (ctx, req, res) => {
+    res.json({ ok: true });
+  }),
+);
+```
+
+A failed check responds `403 { "error": "permission_denied" }` (a thrown
+`FartherShorePermissionError` is mapped by `fs.handler`). The standalone
+`hasPermission` / `requirePermission` / `permissionSatisfies` /
+`routePermission` exports are available for non-Express frameworks. In the dev
+runtime, use `rt.authz.*` — the same shape, with every decision recorded into
+the per-request trace (see `templates/3-simulated-authz.test.ts`).
+
+## Usage reporting — one verb
+
+`ctx.report({ meter, values, dims?, quote? })` on the verified context is the
+ONLY reporting surface. Backends report **measurements, never money**: `values`
+are observed facts (tokens, jobs, rows), `dims` name the catalog tuple they were
+produced under, and the platform owns what they cost.
+
+```ts
+await req.fartherShore.report({
+  meter: "model_usage",
+  values: { input_tokens: 1200, output_tokens: 850 },
+  dims: { model: "acme-4", cache_status: "hit" },
+});
+```
+
+**No identity ceremony.** The subscription and served release ride the signed
+context the gateway already sent, so there is no `subscriptionId` to forget —
+the "unbilled because the handler omitted an id" failure mode is unreachable.
+Hand the same `FartherShoreContext` to a background job and it keeps reporting
+against that same served identity:
+
+```ts
+import type { FartherShoreContext } from "@farthershore/backend";
+
+export async function runJob(job, fartherShore: FartherShoreContext) {
+  const result = await perform(job);
+  await fartherShore.report({
+    meter: "jobs",
+    values: { jobs: 1 },
+    dims: { queue: job.queue },
+  });
+  return result.output;
 }
 ```
 
-- `measureContext` is free-form pricing/analytics context persisted with the
-  usage event.
-- `creditUnitsConsumed` is a numeric map for credit-wallet style businesses; keys
-  and values are validated locally before signing.
+**Transport is an implementation detail.** Reported before the response is sent,
+the measurement rides signed `x-fs-metering` response headers — no extra network
+call; the gateway verifies, settles, and strips them before the subscriber sees
+the response. Reported after `res.end()` (a stream) or from a background job, it
+goes over the attested post-stream channel with the same served identity. The
+builder never picks; `report()` resolves `{ ok, transport }` if you want to know.
+
+**Multiple meters after the response is sent → ONE batched call.** A served
+request owns exactly ONE post-stream callback identity, so sequential awaited
+single-meter calls after the response cannot all be delivered — the first call
+flushes the callback and every later call resolves `{ ok: false }`. Pass an
+ARRAY to report several meters atomically through that single callback:
+
+```ts
+await fartherShore.report([
+  { meter: "model_usage", values: { output_tokens: 512 } },
+  { meter: "jobs", values: { jobs: 1 } },
+]);
+```
+
+All entries of a batch share one quote (supplying two different quotes throws)
+and one `dims` tuple — the request receipt rates under `(route, dims)`, so
+report each dims tuple on its own request. The same one-quote / one-dims rule
+applies to in-band accumulation before the response is sent.
+Before the response is sent this constraint does not exist — sequential in-band
+reports accumulate into the same signed response payload automatically.
+
+Malformed input (a bad meter/measure/dimension key, a negative or non-finite
+value, a malformed quote) **throws** — a dropped measurement is unbilled
+revenue. Delivery failures resolve `{ ok: false, reason }` instead of rejecting,
+so a metering hiccup never breaks your endpoint. Calling `report()` on a context
+that did not come from the runtime (the bare `verifyRequest()` primitive) throws
+an error naming the fix.
 
-The meter keys you report (e.g. `tokens_used`) must match meters declared in your
-business. Request-count style limits are enforced by the gateway and need no
-backend code.
+The meter keys you report must match meters declared in your business; the
+gateway validates them against the served release's measurement-emission schema.
+Request-count style limits are enforced by the gateway and need no backend code.
 
-## Async / background usage
+### Quotes: the one bounded money channel
 
-Use `fs.meter(meter, qty, { requestId, routeId })` only for usage that is **not**
-tied to a gateway response — background jobs, deferred billing, batch work. It
-enqueues an idempotent event and POSTs it to the platform's metering endpoint.
-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.
+`quote` is the sole exception to "never money": a **proposed rate input** for a
+pricing policy that declared the `backendQuoted` rule with repo-authored
+`{min,max}` bounds (dynamic upstream resale, bespoke jobs).
 
-## Post-stream usage reporting
+```ts
+await fartherShore.report({
+  meter: "jobs",
+  values: { jobs: 1 },
+  quote: { currency: "usd", amountNanos: "250000000" }, // $0.25
+});
+```
+
+Core **clamps** it to the declared bounds and flags an out-of-range proposal for
+dispute; contract modifiers and funding still apply on top, and the ledger only
+ever records core-rated charges. The SDK does not validate the bounds (it cannot
+know them) — it rejects only structurally malformed quotes.
+
+### Non-JS backends
+
+The wire recipe is language-neutral: any backend can stamp the same signed
+headers with a stdlib HMAC. See
+[`docs/response-metering-wire.md`](docs/response-metering-wire.md), or use
+`computeMeteringHeaders()` directly from a non-Express JS host.
+
+## Consuming platform webhooks
 
-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:
+Endpoints are created in the dashboard or CLI (`farthershore webhook create`);
+the SDK consumes what they deliver. `@farthershore/backend/webhooks` is
+standalone — a receiver needs only its `fswh_` signing secret, not a runtime
+token.
 
 ```ts
-const context = await fs.verifyRequest({ method, path, query, headers, body });
+import { createWebhookHandler } from "@farthershore/backend/webhooks";
 
-await streamResponse(context);
-await context.reportUsage?.({
-  meters: { output_tokens: 1280 },
-  measureContext: { model: "apsu-1" },
+const webhooks = createWebhookHandler({
+  secret: process.env.FS_WEBHOOK_SECRET!,
+  on: {
+    "subscription.created": async (event) => {
+      await provision(event.data.subscriptionId, event.businessId);
+    },
+    "payment.failed": async (event) => {
+      await flagAccount(event.data.subscriptionId);
+    },
+  },
 });
+
+// Express — mount after a RAW body parser so the signature can be checked:
+app.post(
+  "/webhooks/farthershore",
+  express.raw({ type: "*/*" }),
+  webhooks.express(),
+);
+// Fetch-style runtimes (Next.js route handlers, Hono, Workers):
+export const POST = webhooks.fetch;
 ```
 
-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.
+What the handler does for you, in order: verifies the
+[Standard Webhooks](https://www.standardwebhooks.com) signature over the raw
+body (`webhook-id.webhook-timestamp.body`, HMAC-SHA256, any `v1,` entry —
+so a platform-side rotation's dual signature just works, and you can pass
+`secrets: [current, previous]` while you roll your own copy); rejects
+timestamps outside ±5 minutes; deduplicates on `webhook-id` (a retry after a
+lost 2xx is acknowledged without re-running your code; pass a shared
+`nonceStore` on multi-instance receivers); parses the typed envelope
+`{ id, type, createdAt, businessId, environmentId, data }`; acknowledges
+unknown event types with 2xx (`onUnknown` to log them) so a newer platform
+never causes a 500 storm; and turns a thrown handler into a 500 so the
+platform retries (30 s / 5 min / 30 min) — the delivery id is released so
+that retry runs your handler again.
+
+`verifyWebhook({ body, headers, secrets })` is the bare primitive if you want
+to wire routing yourself, and `signWebhookForTesting()` from
+`@farthershore/backend/testing` produces a platform-identical signed delivery
+for your receiver tests.
 
 ## Lifecycle
 
@@ -237,37 +412,38 @@ See `templates/3-simulated-authz.test.ts` for the full fail-closed + usage flow.
 
 ## Key exports
 
-| Export                               | Purpose                                              |
-| ------------------------------------ | ---------------------------------------------------- |
-| `fartherShore.initFromEnv()`         | Create the runtime instance from `FS_RUNTIME_TOKEN`. |
-| `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).     |
+| Export                               | Purpose                                               |
+| ------------------------------------ | ----------------------------------------------------- |
+| `fartherShore.initFromEnv()`         | Create the runtime instance from `FS_RUNTIME_TOKEN`.  |
+| `fs.middleware()`                    | Express fail-closed verify → `req.fartherShore`.      |
+| `fs.verifyRequest({...})`            | Framework-neutral request verification.               |
+| `fs.handler({ permission? }, cb)`    | Verified-principal handler (+ declarative gate).      |
+| `fs.authz.requirePermission(ctx, k)` | In-handler authz (fail-closed; also `hasPermission`). |
+| `routePermission(subject, method)`   | Route-derived permission key (`:read`/`:write`).      |
+| `ctx.report({meter, values, …})`     | THE reporting verb (SDK picks the transport).         |
+| `computeMeteringHeaders()`           | Metering headers as a plain map — never throws.       |
+| `fs.health()` / `fs.shutdown()`      | Health report and graceful shutdown.                  |
+| `FartherShoreError`, `MeteringError` | Typed errors.                                         |
+| `@farthershore/backend/webhooks`     | `createWebhookHandler` / `verifyWebhook` (receivers). |
+| `@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.
+## Metering transports
+
+One verb, two transports — `ctx.report()` chooses; you never do:
+
+- **In-band** (signed `x-fs-metering` response headers) while the response is
+  still open: 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, then strips the headers. Wire recipe (any language):
+  [`docs/response-metering-wire.md`](docs/response-metering-wire.md).
+- **Post-stream** (the attested `POST /v1/metering/events` callback) once the
+  response is on the wire, or from a background job holding the context. It is
+  HMAC-attested and carries the same served identity, writes the sole billable
+  row for the reported units, and never mutates real-time enforcement windows —
+  so units unknown at admission cannot be hard-enforced.
 
 ## Learn more