@farthershore/backend 0.19.0 → 0.21.0

package/dist/types/adapters/express.d.ts

@@ -1,6 +1,6 @@
 import type { FartherShore } from "../core/runtime.js";
 import type { FartherShoreRequestContext } from "../core/verifyRequest.js";
-import type { ConsumerPrincipal } from "../core/verifyContext.js";
+import type { ConsumerPrincipal, FartherShoreSignedContext } from "../core/verifyContext.js";
 /** Minimal Express-shaped types so we don't hard-depend on @types/express. */
 export type ExpressRequestLike = {
     method: string;
@@ -18,6 +18,13 @@ export type ExpressResponseLike = {
     status(code: number): ExpressResponseLike;
     json(body: unknown): unknown;
     setHeader(name: string, value: string): void;
+    /**
+     * Node's `ServerResponse.headersSent`. This is what makes the reporting verb's
+     * transport choice AUTOMATIC: while it is false the measurement rides signed
+     * response headers (no network call); once the response is on the wire
+     * `ctx.report()` transparently switches to the post-stream channel.
+     */
+    headersSent?: boolean;
 };
 export type ExpressNext = (err?: unknown) => void;
 export type ExpressMiddleware = (req: ExpressRequestLike, res: ExpressResponseLike, next: ExpressNext) => void;
@@ -69,14 +76,27 @@ export type MiddlewareOptions = {
  */
 export type VerifiedPrincipalContext = FartherShoreRequestContext & {
     principal: ConsumerPrincipal;
+    signedContext: FartherShoreSignedContext;
 };
 /**
  * A route handler that runs only with a GUARANTEED verified PRINCIPAL. The first
- * argument is the {@link VerifiedPrincipalContext} — read `ctx.principal` (and
- * narrow with `requireMember`/`requireService`) without any optional-chaining.
+ * argument is the {@link VerifiedPrincipalContext} — read `ctx.principal` and
+ * `ctx.signedContext` (and narrow with `requireMember`/`requireService`)
+ * without any optional-chaining.
  * See {@link createExpressHandler}.
  */
 export type VerifiedExpressHandler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike> = (ctx: VerifiedPrincipalContext, req: Req, res: Res, next: ExpressNext) => void | Promise<void>;
+/** Options for the `fs.handler(options, cb)` overload. */
+export type HandlerOptions = {
+    /**
+     * Permission key the verified principal must hold (unified grammar:
+     * `*` / `<subject>:*` / exact — custom strings work). Checked with the
+     * FAIL-CLOSED carrier gate (`requirePermission`): an ABSENT permission set
+     * denies. On failure the wrapper responds `403 { error: "permission_denied" }`
+     * before the callback runs.
+     */
+    permission?: string;
+};
 /**
  * Build the Express middleware. Captures raw body bytes, calls verifyRequest,
  * and fail-closes on any error.
@@ -106,3 +126,12 @@ export declare function createExpressMiddleware(fs: FartherShore, options?: Midd
  * non-optional guarantee AND Express compatibility.
  */
 export declare function createExpressHandler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+/**
+ * Options-first overload: `fs.handler({ permission: "widgets:write" }, cb)`
+ * asserts the verified principal holds `permission` (via the fail-closed
+ * carrier gate — an absent permission set DENIES) BEFORE the callback runs,
+ * responding `403 permission_denied` otherwise. The key is checked with the
+ * unified grammar (`*` / `<subject>:*` / exact); derive route-shaped keys with
+ * `routePermission(subject, method)`.
+ */
+export declare function createExpressHandler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(options: HandlerOptions, handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;

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

@@ -12,6 +12,11 @@ export type BootstrapClientOptions = {
     now?: () => number;
     /** Minimum seconds between refreshes regardless of server hint. */
     minRefreshSeconds?: number;
+    /**
+     * Maximum age for cached bootstrap authorization metadata during transient
+     * refresh failures. Defaults to 5 minutes.
+     */
+    maxStaleSeconds?: number;
 };
 /**
  * Caches the bootstrap response and refreshes it lazily. `get()` returns the
@@ -24,6 +29,7 @@ export declare class BootstrapClient {
     private readonly fetchImpl;
     private readonly now;
     private readonly minRefreshSeconds;
+    private readonly maxStaleMs;
     private cached;
     private fetchedAt;
     private refreshAfterMs;
@@ -36,5 +42,7 @@ export declare class BootstrapClient {
     /** Last cached value without triggering a refresh (null until bootstrapped). */
     peek(): RuntimeBootstrapResponse | null;
     private isStale;
+    private isHardStale;
+    private cachedOrThrowOnHardStale;
     private doBootstrap;
 }

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

@@ -0,0 +1,80 @@
+import { FartherShoreError } from "./errors.js";
+/**
+ * Per-operation deadlines. Verification-path calls are tighter than reporting
+ * calls: JWKS sits in front of every inbound request, while a metering flush is
+ * a background economic report that is retried anyway.
+ */
+export declare const DEADLINE_MS: {
+    /** Boot-blocking; generous because it runs once and gates startup. */
+    readonly bootstrap: 10000;
+    /** On the inbound verification path — must not hold a request open. */
+    readonly jwks: 5000;
+    /** Background economic report, retried by the caller. */
+    readonly metering: 10000;
+    /** Background attested usage callback. */
+    readonly postStreamUsage: 10000;
+    /** Best-effort heartbeat; never blocks anything. */
+    readonly health: 5000;
+    /** Boot-time route drift report; fail-open at the caller. */
+    readonly report: 10000;
+};
+export type DeadlineOperation = keyof typeof DEADLINE_MS;
+/**
+ * Byte cap for response bodies the SDK parses. Core's JWKS and bootstrap
+ * documents are kilobytes; a megabyte is orders of magnitude of headroom while
+ * still refusing an unbounded stream.
+ */
+export declare const MAX_RESPONSE_BYTES = 1048576;
+/**
+ * True when `cause` is this module's deadline firing (as opposed to a caller
+ * cancellation or a transport error). `AbortSignal.timeout` rejects with a
+ * `TimeoutError` DOMException; we also accept our own typed marker.
+ */
+export declare function isDeadlineExceeded(cause: unknown): boolean;
+/** Raised when a bounded read exceeds {@link MAX_RESPONSE_BYTES}. */
+export declare class ResponseTooLargeError extends Error {
+    constructor(limit: number);
+}
+/** Marker for a deadline that fired, preserved across helper boundaries. */
+export declare class DeadlineExceededError extends Error {
+    readonly operation: DeadlineOperation;
+    constructor(operation: DeadlineOperation, timeoutMs: number);
+}
+export type DeadlineOptions = {
+    /** Host cancellation to compose with the SDK deadline. */
+    callerSignal?: AbortSignal;
+    /**
+     * Override the operation default. For callers with a tighter budget than the
+     * SDK default (and for tests, which cannot wait out a 10s deadline).
+     */
+    timeoutMs?: number;
+};
+/**
+ * Compose the SDK deadline for `operation` with an optional caller signal.
+ * Either aborting aborts the fetch, so host cancellation still works and the
+ * SDK can never outlive its own timeout.
+ */
+export declare function deadlineSignal(operation: DeadlineOperation, options?: DeadlineOptions): AbortSignal;
+/**
+ * `fetch` with a mandatory deadline. Every outbound SDK call goes through here;
+ * the CI guard (`fetch-timeouts:check:backend-sdk`) fails the build on a raw
+ * `fetch(` added anywhere else in the package.
+ *
+ * Rethrows a {@link DeadlineExceededError} when OUR timeout fired, so the
+ * failure is classifiable even though `AbortSignal.any` erases which input
+ * aborted. A caller-driven abort propagates unchanged.
+ */
+export declare function fetchWithDeadline(fetchImpl: typeof fetch, input: string, init: RequestInit, operation: DeadlineOperation, options?: DeadlineOptions): Promise<Response>;
+/**
+ * Read a response body as text, cancelling the stream once `limit` bytes have
+ * arrived. Returns the decoded text; throws {@link ResponseTooLargeError} when
+ * the cap is crossed so a caller never sees a silently truncated document.
+ */
+export declare function readBoundedText(response: Response, limit?: number): Promise<string>;
+/**
+ * Bounded JSON read. Same cap as {@link readBoundedText}; a body that is not
+ * valid JSON raises the underlying SyntaxError for the caller to classify.
+ */
+export declare function readBoundedJson<T>(response: Response, limit?: number): Promise<T>;
+/** Wrap a deadline failure in the SDK's typed error with a stable code. */
+export declare function deadlineError(operation: DeadlineOperation, cause: unknown): FartherShoreError;

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

@@ -1,28 +1,53 @@
 export type Jwk = JsonWebKey & {
     kid?: string;
 };
+/** Freshness of the key set backing a verification decision. */
+export type JwksCacheState = "fresh" | "soft_stale" | "hard_stale" | "cold";
+export type JwksObservation = {
+    state: JwksCacheState;
+    /** Age of the cached key set in ms (0 when cold). */
+    ageMs: number;
+    /** The `kid` being resolved, when the observation is tied to one. */
+    kid?: string;
+};
+/**
+ * Observability hook. Fires on every decision that depends on cache freshness,
+ * so an operator can alarm on `soft_stale` (Core is failing) long before
+ * `hard_stale` (requests are now being rejected).
+ */
+export type JwksObserver = (observation: JwksObservation) => void;
 export type JwksClientOptions = {
     jwksUrl: string;
     /** Injectable fetch (tests). Defaults to globalThis.fetch. */
     fetchImpl?: typeof fetch;
     /** How long a successful fetch stays fresh before a background refresh. */
     cacheTtlMs?: number;
+    /**
+     * Hard ceiling on serving a key set whose refresh is failing. Past this age
+     * the client FAILS CLOSED rather than vouching for keys it can no longer
+     * confirm. Must be ≥ cacheTtlMs.
+     */
+    hardStaleMs?: number;
     /** How long an unknown-kid result is negatively cached (avoids hammering). */
     negativeCacheMs?: number;
     /** Injectable clock (tests). */
     now?: () => number;
+    /** Freshness//staleness observations for metrics. */
+    onObservation?: JwksObserver;
 };
 /**
- * Caching JWKS client. Holds the last successful key set indefinitely as a
- * warm fallback (stale-while-revalidate) and only fails closed when it has
- * NEVER successfully fetched (cold cache).
+ * Caching JWKS client. Serves the last successful key set as a warm fallback
+ * while a refresh is failing, but only until {@link JwksClientOptions.hardStaleMs};
+ * fails closed on a cold cache and past the hard-stale ceiling.
  */
 export declare class JwksClient {
     private readonly jwksUrl;
     private readonly fetchImpl;
     private readonly cacheTtlMs;
+    private readonly hardStaleMs;
     private readonly negativeCacheMs;
     private readonly now;
+    private readonly onObservation;
     private keysByKid;
     private fetchedAt;
     private hasFetchedOnce;
@@ -31,18 +56,28 @@ export declare class JwksClient {
     constructor(options: JwksClientOptions);
     /**
      * Resolve a public JWK for `kid`, fail-closed. Throws FartherShoreError with
-     * `jwks_unavailable` (cold cache + fetch failed) or `unknown_key_id`.
+     * `jwks_unavailable` (cold cache, or a hard-stale cache whose refresh is
+     * failing) or `unknown_key_id`.
      */
     getKey(kid: string): Promise<Jwk>;
     /** Record a confirmed-missing kid, evicting the oldest if at capacity. */
     private rememberMissingKid;
+    private ageMs;
     private isStale;
+    private isHardStale;
+    /** Current freshness of the cached key set. */
+    private cacheState;
+    private observe;
+    /** Fail closed when the cached key set is past the hard-stale ceiling. */
+    private assertWithinHardStale;
     /** Single-flight refresh: concurrent callers share one fetch. */
     private refresh;
     private doFetch;
     /**
-     * Stale-while-revalidate: with a warm cache, swallow the refresh failure and
-     * keep serving the last-known keys. With a COLD cache, fail closed.
+     * BOUNDED stale-while-revalidate. A COLD cache fails closed. A warm cache
+     * inside the soft window swallows the failure and keeps serving. Past the
+     * hard-stale ceiling it fails closed too — availability is worth a bounded
+     * window of degraded trust, not an unbounded one.
      */
-    private failOnColdCache;
+    private handleRefreshFailure;
 }

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

@@ -13,21 +13,33 @@ export declare class FartherShorePermissionError extends Error {
     constructor(requiredPermission: string, message?: string);
 }
 /**
- * Pure grant check — a FAITHFUL COPY of the canonical `permissionGrants` in
- * `@farthershore/contracts` (`rbac.ts`). Over a DEFINED array: a `"*"` entry
- * grants everything, otherwise the key must be an exact member. Its
- * `undefined → true` codomain is the PRIMITIVE's contract (kept byte-identical
- * to contracts for parity); it is NOT the SDK's carrier policy. Under FAR-723
- * the carrier gate {@link hasPermission} DENIES an absent permission set before
- * this primitive is consulted, so absence never grants at the boundary.
+ * HTTP verbs that classify as `:read`. Everything else — including the
+ * route-catalog wildcard `*` — classifies as `:write`.
  *
- * The published SDK surface must stay contracts-free, so it can't import the
- * canonical primitive. A TEST-ONLY parity guard (`permissions-parity.test.ts`,
- * which CAN import contracts as a devDependency) asserts this copy agrees with
- * the canonical primitive across a shared golden vector table, so the copy
- * can't silently drift.
+ * FAITHFUL COPY of the canonical `READ_METHODS` in the permissions kernel
+ * (`@farthershore/authz/grammar/route`, re-exported by
+ * `@farthershore/contracts/rbac`); the published bundle is contracts-free, so
+ * `permissions-parity.test.ts` asserts agreement and the full corpus replay
+ * lives in packages/authz/test-node/sdk-copy-parity.test.ts.
  */
-export declare function permissionGrants(permissions: readonly string[] | undefined, key: string): boolean;
+export declare const READ_METHODS: ReadonlySet<string>;
+/**
+ * Derive the permission string a credential must hold to call a route:
+ * `<subject>:read` for safe verbs (GET / HEAD / OPTIONS, any casing),
+ * `<subject>:write` for every other method INCLUDING the route-catalog
+ * wildcard `*`. Use it to build in-handler permission keys from the same
+ * grammar the edge `permission` constraint enforces — never re-spell the
+ * `:read`/`:write` suffix locally.
+ *
+ * FAITHFUL COPY of the canonical `routePermission` in the permissions kernel
+ * (`@farthershore/authz/grammar/route`, re-exported by
+ * `@farthershore/contracts/rbac`); parity asserted as for {@link READ_METHODS}.
+ *
+ * @param subject the matched route's permission subject (used verbatim)
+ * @param method the REQUEST method (case-insensitive) or a route-catalog
+ *   method entry (`*` → `:write`)
+ */
+export declare function routePermission(subject: string, method: string): string;
 /**
  * Whether the granted `permissions` satisfy the required `key` under the
  * unified grammar: `"*"` (global), `"<subject>:*"` (subject wildcard), or the

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

@@ -5,10 +5,23 @@ export type ReportUsageInput = {
     meters: Record<string, number>;
     creditUnitsConsumed?: Record<string, number>;
     measureContext?: Record<string, unknown>;
-};
-export type RequestScopedReportUsageInput = Omit<ReportUsageInput, "requestId" | "subscriptionId"> & {
-    requestId?: string;
-    subscriptionId?: string;
+    /** Schema version of {@link measurements}; currently `1`. */
+    measurementsVersion?: number;
+    /**
+     * The measurement lane (`{ meter, values, dims }`) — the authoritative rating
+     * input `ctx.report()` emits. Additive over `meters`, which remains the flat
+     * projection core's existing settlement path reads.
+     */
+    measurements?: {
+        meter: string;
+        values: Record<string, number>;
+        dims?: Record<string, string>;
+    }[];
+    /** Proposed rate input for a `backendQuoted` pricing rule (core clamps it). */
+    quote?: {
+        currency: string;
+        amountNanos: string;
+    };
 };
 export type ReportUsageResult = {
     ok: true;
@@ -26,6 +39,8 @@ export type PostStreamUsageClientOptions = {
     sleep?: (delayMs: number) => Promise<void>;
     /** Backoff after each request-not-found response. */
     retryDelaysMs?: readonly number[];
+    /** Upper bound for Retry-After sleeps; defaults to 10 seconds. */
+    maxRetryDelayMs?: number;
 };
 /**
  * Best-effort, attested post-stream billing reporter. The callback is
@@ -40,6 +55,10 @@ export declare class PostStreamUsageClient {
     private readonly logger;
     private readonly sleep;
     private readonly retryDelaysMs;
+    private readonly maxRetryDelayMs;
     constructor(options: PostStreamUsageClientOptions);
     reportUsage(input: ReportUsageInput): Promise<ReportUsageResult>;
+    /** Enforce the token's meter scope + per-event bounds on the measurement lane. */
+    private validateMeasurements;
+    private retryDelayForAttempt;
 }

package/dist/types/core/replay-protection.d.ts

@@ -0,0 +1,28 @@
+import { type NonceStore } from "./nonceCache.js";
+/** How far one-time-use enforcement actually reaches. */
+export type ReplayProtectionMode = "shared" | "single-instance";
+export type ReplayProtectionDiagnostic = {
+    mode: ReplayProtectionMode;
+    /** True when replay is enforced across every replica, not just this process. */
+    crossReplica: boolean;
+};
+export type ResolveReplayProtectionInput = {
+    /** Shared store injected by the host, if any. */
+    nonceStore?: NonceStore | undefined;
+};
+export type ResolvedReplayProtection = {
+    store: NonceStore;
+    diagnostic: ReplayProtectionDiagnostic;
+};
+/**
+ * Select the replay store and report which mode it is. Never throws — the
+ * zero-config default is the in-memory cache, and the time window is what
+ * bounds exposure regardless.
+ */
+export declare function resolveReplayProtection(input?: ResolveReplayProtectionInput): ResolvedReplayProtection;
+/**
+ * Wrap an injected shared store so an OUTAGE fails closed. Only applies when a
+ * builder opted into a shared store; the in-memory default cannot fail this
+ * way.
+ */
+export declare function failClosed(store: NonceStore): NonceStore;

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

@@ -0,0 +1,133 @@
+import { type ResponseMeteringUsagePayload } from "../response-metering.js";
+/** Observed measurement values, keyed by measure key. */
+export type MeasurementValues = Record<string, number>;
+/** Catalog selectors the measurement was produced under, keyed by dimension. */
+export type MeasurementDimensions = Record<string, string>;
+/**
+ * The validated, transmitted quote — a PROPOSED rate input, never a charge.
+ * `amountNanos` is a decimal integer string of nanodollars **per unit of the
+ * entry's measure** (the platform's money unit is the nanodollar); core
+ * multiplies it by the measured quantity, clamps it into the pricing policy's
+ * declared per-unit `{min,max}`, and flags out-of-range proposals for dispute.
+ * Never send a total.
+ */
+export type QuoteProposal = {
+    currency: string;
+    amountNanos: string;
+};
+/**
+ * Authoring shape of {@link QuoteProposal}. `amountNanos` (nanodollars PER
+ * UNIT of the entry's measure) accepts a number, bigint, or decimal integer
+ * string; anything else is rejected.
+ */
+export type QuoteInput = {
+    currency: string;
+    amountNanos: number | bigint | string;
+};
+/** One measurement report. The complete argument surface of the verb. */
+export type ReportInput = {
+    /** Meter key as declared in the business release (plain string at the wire). */
+    meter: string;
+    /** Observed values keyed by measure key, e.g. `{ input_tokens: 1200 }`. */
+    values: MeasurementValues;
+    /** Catalog selectors, e.g. `{ model: "acme-4", cache_status: "hit" }`. */
+    dims?: MeasurementDimensions;
+    /**
+     * OPTIONAL money proposal for a `backendQuoted` pricing rule: a PER-UNIT
+     * rate in nanodollars (multiplied by the measured quantity — never a
+     * total). Opaque at the authoring boundary (a job result carries it through
+     * untyped); validated against {@link QuoteInput} here and transmitted as a
+     * {@link QuoteProposal}. Applies to every backend-quoted component of this
+     * report; ignored by rules that are not backend-quoted.
+     */
+    quote?: unknown;
+};
+/** Which channel actually carried the measurement. */
+export type ReportTransport = "in_band" | "post_stream";
+/**
+ * Delivery outcome. Validation faults THROW (a malformed report is a builder
+ * bug worth surfacing); delivery faults resolve `ok: false` so a metering
+ * hiccup never breaks the builder's endpoint. A served request may own only
+ * one post-stream callback identity, so later calls fail explicitly.
+ */
+export type ReportResult = {
+    ok: true;
+    transport: ReportTransport;
+} | {
+    ok: false;
+    transport: ReportTransport;
+    reason: string;
+};
+/** The wire shape of one validated measurement. */
+export type Measurement = {
+    meter: string;
+    values: MeasurementValues;
+    dims?: MeasurementDimensions;
+};
+/** Version of the `measurements` payload lane (additive over `rawDimsUnits`). */
+export declare const MEASUREMENTS_VERSION = 1;
+/** The transport seam a host adapter supplies for the in-band lane. */
+export type ResponseSink = {
+    /** True while headers can still be stamped onto the outgoing response. */
+    canStampHeaders(): boolean;
+    /** Stamp the signed metering headers onto the outgoing response. */
+    stampHeaders(headers: Record<string, string>): void;
+};
+/** Everything `report()` needs that only the runtime can provide. */
+export type ReportChannels = {
+    /** Sign the payload into `x-fs-metering*` headers (may resolve `{}`). */
+    computeHeaders(payload: ResponseMeteringUsagePayload): Promise<Record<string, string>>;
+    /** Deliver over the attested post-stream channel. */
+    postStream(input: {
+        measurements: Measurement[];
+        quote?: QuoteProposal;
+    }): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    /** Method/path of the served request, for the in-band payload binding. */
+    request?: {
+        method: string;
+        path: string;
+    };
+    /** Host-supplied response seam; absent ⇒ the post-stream lane is used. */
+    responseSink?: ResponseSink;
+};
+/**
+ * `report()` accepts one measurement or an ARRAY of measurements. The array
+ * form is the sanctioned way to report several meters after the response is
+ * sent: one served request owns exactly ONE post-stream callback identity, so
+ * sequential awaited single reports after the first flush cannot be delivered
+ * — a batch rides the single callback atomically. All entries of a batch
+ * share one quote (at most one distinct quote may be supplied).
+ */
+export type ReportFn = (input: ReportInput | readonly ReportInput[]) => Promise<ReportResult>;
+/**
+ * Build the bound `report()` verb for a verified context. The returned function
+ * validates, picks its own transport, and never asks the caller for identity.
+ */
+export declare function createReportFn(channels: ReportChannels): ReportFn;
+/**
+ * The `report()` stub attached to a context produced by the BARE
+ * `verifyRequest()` primitive (no runtime, therefore no metering channel). It
+ * throws an error that names the fix instead of pretending the measurement was
+ * delivered.
+ */
+export declare function unattachedReport(): ReportFn;
+/**
+ * Project a measurement into the flat `rawDimsUnits` lane the gateway's
+ * in-band settlement path consumes.
+ *
+ * PROJECTION RULE (P0-2): the projection keys the METER id, and its scalar is
+ * the sum of the measurement's measure values — the meter's structural
+ * quantity. The gateway masks `rawDimsUnits` by the matched route's declared
+ * METER ids (`maskCostMapByMeters`), so measure-keyed entries would be
+ * silently discarded at the edge (UNBILLED). Per-measure detail is NOT lost:
+ * the full `{ meter, values, dims }` measurement rides alongside in the
+ * versioned `measurements` lane, which is the authoritative rating input.
+ */
+export declare function rawDimsUnitsOf(measurement: Measurement): Record<string, number>;
+/** Validate one report input into its wire {@link Measurement}. */
+export declare function validateMeasurement(input: ReportInput): Measurement;
+/** Validate an opaque authored quote into its wire {@link QuoteProposal}. */
+export declare function validateQuote(quote: unknown): QuoteProposal;

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

@@ -1,8 +1,8 @@
 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 ResponseSink } from "./report.js";
 import { type NonceStore } from "./nonceCache.js";
+import { type ReplayProtectionDiagnostic } from "./replay-protection.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. */
@@ -21,10 +21,7 @@ export type FartherShoreTunnelOptions = {
 export type FartherShoreInitOptions = {
     /** Explicit runtime token. Defaults to process.env.FS_RUNTIME_TOKEN. */
     runtimeToken?: string;
-    /**
-     * Core base URL. Defaults to FS_CORE_URL / FARTHERSHORE_CORE_URL or
-     * https://core.farthershore.com.
-     */
+    /** Core base URL. Defaults to FS_CORE_URL or https://core.farthershore.com. */
     coreUrl?: string;
     /** Env map (tests). Defaults to process.env. */
     env?: Record<string, string | undefined>;
@@ -57,17 +54,28 @@ export type FartherShoreInitOptions = {
      */
     contextSecrets?: readonly string[];
     /**
-     * OPTIONAL shared replay-prevention store. The default is an IN-MEMORY,
-     * PER-PROCESS {@link NonceCache} — it stops replay against a single instance
-     * only. A horizontally-scaled backend (multiple replicas / serverless
-     * instances) where a captured, still-valid signed request could be replayed
-     * to a DIFFERENT replica should inject a SHARED store (Redis / Memcached /
-     * Cloudflare KV / Durable Object) implementing {@link NonceStore}. The signed
-     * request's ~300s validity window bounds the exposure either way, but a shared
-     * store closes the cross-replica gap. `checkAndRemember` may be async.
+     * OPTIONAL shared replay-prevention store. Not required: the signature's
+     * ~305s time window is the always-on defense, and the zero-config default is
+     * an in-memory per-process cache. Inject a shared atomic store (Redis /
+     * Memcached / Cloudflare KV / Durable Object) implementing {@link NonceStore}
+     * only if you want one-time-use enforced ACROSS replicas rather than within
+     * each one. `checkAndRemember` may be async, and should be TTL-bound to the
+     * signature validity window.
+     *
+     * If you do inject one, an outage of that store fails requests CLOSED — it
+     * never degrades to "not a replay".
      */
     nonceStore?: NonceStore;
 };
+/**
+ * Host-adapter seams for `verifyRequest`. An adapter that owns the outgoing
+ * response (the Express middleware) supplies a {@link ResponseSink} so
+ * `ctx.report()` can choose the zero-network in-band header transport while the
+ * response is still open. Without one, reports take the post-stream channel.
+ */
+export type VerifyRequestHostOptions = {
+    responseSink?: ResponseSink;
+};
 export declare const SDK_VERSION: string;
 /**
  * The runtime instance. Lazily bootstraps; holds the JWKS client, nonce cache,
@@ -85,9 +93,9 @@ export declare class FartherShore {
     /** OPTIONAL HS256 secret(s) — defense-in-depth over the cv=2 X-Fs-Context. */
     private readonly contextSecrets;
     private readonly nonceCache;
+    private readonly replayProtectionDiagnostic;
     private readonly shutdownManager;
     private jwks;
-    private meteringClient;
     private postStreamUsageClient;
     private tunnel;
     private bootstrapped;
@@ -115,7 +123,14 @@ export declare class FartherShore {
      * Framework-neutral verification primitive. Fail-closed: throws a typed
      * FartherShoreError on any verification failure. Returns the verified context.
      */
-    verifyRequest(input: VerifyRequestInput): Promise<FartherShoreRequestContext>;
+    verifyRequest(input: VerifyRequestInput, options?: VerifyRequestHostOptions): Promise<FartherShoreRequestContext>;
+    /**
+     * Bind the ONE reporting verb to a verified context. Identity comes from the
+     * context (`signedContext.subscriptionId` + `requestId`) — never from the
+     * caller — so a handler cannot forget it, and a background job that is handed
+     * this context keeps reporting against the SAME served identity.
+     */
+    private buildReportFn;
     /** Whether verification is required (bootstrap × opt-out). */
     verificationRequired(): Promise<boolean>;
     /**
@@ -129,10 +144,19 @@ export declare class FartherShore {
      * (request verification stays fail-closed regardless — a different axis).
      */
     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>;
+    /**
+     * PRIVATE transport for the post-stream lane of `ctx.report()`. Never rejects
+     * — a metering hiccup must not break a builder's endpoint. This is machinery,
+     * not surface: the ONE public reporting verb is `ctx.report()`.
+     */
+    private reportPostStreamUsage;
+    /**
+     * How far replay protection actually reaches — `"shared"` (enforced across
+     * every replica) or `"single-instance"` (this process only). Deployment
+     * diagnostic: log it at boot, or assert on it in a smoke test, so the mode is
+     * never a surprise. See {@link FartherShoreInitOptions.nonceStore}.
+     */
+    replayProtection(): ReplayProtectionDiagnostic;
     /** Current local health report. */
     health(): RuntimeHealthReport;
     /** Graceful shutdown: flush metering + send a stopping heartbeat. */