@farthershore/backend 0.8.1 → 0.9.0

package/README.md

@@ -4,9 +4,9 @@ Runtime metering and gateway-verification SDK for builder upstreams. Install one
 package, set one token (`FS_RUNTIME_TOKEN`), and Farther Shore handles signed
 gateway-to-upstream request verification plus response-bound usage reporting.
 
-> **Status: `0.8.1` (lockstep SDK family).** Published at the SAME version as
-> `@farthershore/farthershore-js` and `@farthershore/product` — pin the three
-> together. Pre-1.0: minor bumps may break.
+> **Status: `0.8.2`.** Versions independently from
+> `@farthershore/farthershore-js` and `@farthershore/business`. Pre-1.0: minor
+> bumps may break, so pin this package exactly or use a patch-only range.
 
 ## Install
 

package/dist/generated/runtime-contract.js

@@ -54,8 +54,8 @@ var RUNTIME_BOOTSTRAP_CONTRACT = {
       perEventMax: "number"
     },
     transport: {
-      mode: "public_origin | mtls | cloudflare_tunnel",
-      runner: "managed_cloudflared | sidecar | null",
+      mode: "direct | tunnel",
+      runner: "embedded | sidecar | null",
       originUrl: "string?",
       originHostname: "string?",
       localTarget: "string?",
@@ -247,17 +247,16 @@ var RUNTIME_HEALTH_CONTRACT = {
 };
 var RUNTIME_TRANSPORT_CONTRACT = {
   modes: {
-    public_origin: "Gateway fetches the builder's public origin URL; the SDK middleware fail-closed-verifies every request. Provisions zero Cloudflare objects. Standard tier; also the dev path.",
-    mtls: "Gateway presents a Farther-Shore-issued platform-wide client cert; the builder's ingress requires + verifies it. Channel-level mutual auth; provisions zero Cloudflare objects. Standard-plus / self-hosted tier.",
-    cloudflare_tunnel: "Farther Shore provisions a private outbound Cloudflare Tunnel; no inbound port. The only Production-secure tier. Consumes Cloudflare tunnel/route slots."
+    direct: "Gateway fetches the builder's public origin URL; the SDK middleware fail-closed-verifies every request via Ed25519 request signing. Provisions zero Cloudflare objects. Available on all tiers; also the dev path.",
+    tunnel: "Farther Shore provisions a private outbound Cloudflare Tunnel; no inbound port. The Production-secure tier. Consumes Cloudflare tunnel/route slots."
   },
   runners: {
-    managed_cloudflared: "fs.start() supervises cloudflared as a child process (default DX).",
+    embedded: "fs.start() supervises cloudflared as a child process (default DX).",
     sidecar: "Vanilla cloudflare/cloudflared container beside the app (production / non-Node)."
   },
-  channelTrust: ["mtls", "cloudflare_tunnel"],
+  channelTrust: ["tunnel"],
   requestTrust: "x-fs-signature",
-  invariant: "Channel trust (mtls/tunnel) and request trust (the X-FS-* signature) are distinct layers; both always apply. CF-Access-* headers are transport-layer only and are IGNORED by the SDK."
+  invariant: "Channel trust (tunnel) and request trust (the X-FS-* signature) are distinct layers; both always apply. CF-Access-* headers are transport-layer only and are IGNORED by the SDK."
 };
 export {
   RUNTIME_BODY_HASH_CONTRACT,

package/dist/index.js

@@ -719,8 +719,37 @@ function stringifyCause(cause) {
   return String(cause);
 }
 
+// src/core/backoff.ts
+function computeBackoff(attempt, options) {
+  const { baseMs, maxMs, jitter = "equal", random = Math.random } = options;
+  const exponent = Math.max(0, attempt - 1);
+  const cap = Math.min(baseMs * 2 ** exponent, maxMs);
+  switch (jitter) {
+    case "none":
+      return cap;
+    case "full":
+      return random() * cap;
+    case "equal":
+    default:
+      return cap / 2 + random() * (cap / 2);
+  }
+}
+
 // src/core/metering.ts
 var METER_KEY_RE = /^[a-z0-9_]{1,64}$/;
+var DEFAULT_BASE_DELAY_MS = 200;
+var DEFAULT_MAX_DELAY_MS = 1e4;
+function isTransientStatus(status) {
+  return status === 429 || status >= 500;
+}
+function retryAfterMs(headers) {
+  const raw = headers.get("retry-after");
+  if (raw === null) return null;
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) return null;
+  const secs = Number(trimmed);
+  return Number.isFinite(secs) ? secs * 1e3 : null;
+}
 var DEFAULT_MAX_RETRIES = 3;
 var MeteringClient = class {
   config;
@@ -729,6 +758,10 @@ var MeteringClient = class {
   backendId;
   fetchImpl;
   maxRetries;
+  baseDelayMs;
+  maxDelayMs;
+  sleep;
+  random;
   newId;
   now;
   buffer = [];
@@ -739,6 +772,10 @@ var MeteringClient = class {
     this.backendId = options.backendId;
     this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    this.maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    this.random = options.random ?? Math.random;
     this.newId = options.newId ?? (() => crypto.randomUUID());
     this.now = options.now ?? (() => /* @__PURE__ */ new Date());
   }
@@ -821,6 +858,7 @@ var MeteringClient = class {
   }
   async sendWithRetry(event) {
     for (let attempt = 0; attempt < this.maxRetries; attempt += 1) {
+      let retryAfter = null;
       try {
         const response = await this.fetchImpl(this.endpoint, {
           method: "POST",
@@ -832,8 +870,18 @@ var MeteringClient = class {
           body: JSON.stringify(event)
         });
         if (response.ok) return true;
+        if (!isTransientStatus(response.status)) return false;
+        retryAfter = retryAfterMs(response.headers);
       } catch {
       }
+      const isLast = attempt === this.maxRetries - 1;
+      if (isLast) break;
+      const delay = retryAfter !== null ? Math.min(retryAfter, this.maxDelayMs) : computeBackoff(attempt + 1, {
+        baseMs: this.baseDelayMs,
+        maxMs: this.maxDelayMs,
+        random: this.random
+      });
+      await this.sleep(delay);
     }
     return false;
   }
@@ -918,6 +966,7 @@ var ShutdownManager = class {
 
 // src/core/tunnel.ts
 import { spawn as nodeChildSpawn } from "node:child_process";
+import { createRequire } from "node:module";
 var REDACTED_TOKEN = "***REDACTED***";
 var CLOUDFLARED_RUN_ARGS = [
   "tunnel",
@@ -925,12 +974,12 @@ var CLOUDFLARED_RUN_ARGS = [
   "run",
   "--token"
 ];
-var DEFAULT_BINARY_CANDIDATES = [
-  "cloudflared",
-  "/usr/local/bin/cloudflared",
-  "/usr/bin/cloudflared",
-  "/opt/cloudflared/cloudflared"
-];
+var CLOUDFLARED_BINARY_PACKAGES = {
+  "linux-x64": "@farthershore/cloudflared-linux-x64",
+  "linux-arm64": "@farthershore/cloudflared-linux-arm64",
+  "darwin-arm64": "@farthershore/cloudflared-darwin-arm64",
+  "darwin-x64": "@farthershore/cloudflared-darwin-x64"
+};
 var DEFAULT_BASE_BACKOFF_MS = 1e3;
 var DEFAULT_MAX_BACKOFF_MS = 6e4;
 var DEFAULT_BINARY = "cloudflared";
@@ -945,6 +994,8 @@ var CloudflaredSupervisor = class {
   failClosed;
   baseBackoffMs;
   maxBackoffMs;
+  backoffJitter;
+  random;
   setTimeoutFn;
   clearTimeoutFn;
   childEnv;
@@ -972,6 +1023,8 @@ var CloudflaredSupervisor = class {
     this.failClosed = options.failClosed ?? false;
     this.baseBackoffMs = options.baseBackoffMs ?? DEFAULT_BASE_BACKOFF_MS;
     this.maxBackoffMs = options.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+    this.backoffJitter = options.backoffJitter ?? "equal";
+    this.random = options.random ?? Math.random;
     this.setTimeoutFn = options.setTimeoutFn ?? ((cb, ms) => setTimeout(cb, ms));
     this.clearTimeoutFn = options.clearTimeoutFn ?? ((h) => clearTimeout(h));
     this.childEnv = options.childEnv;
@@ -1048,15 +1101,24 @@ var CloudflaredSupervisor = class {
     child.on("exit", (code, signal) => this.handleExit(code, signal));
   }
   /**
-   * Resolve the cloudflared binary path. Explicit `binaryPath` wins; otherwise
-   * the injected locator runs (Linux-first). Missing ⇒ a clear, redacted error.
+   * Resolve the cloudflared binary path. Order:
+   *   1. an installed `@farthershore/cloudflared-<platform>` optional-dependency
+   *      matching process.platform+arch (the injected locator), then
+   *   2. an explicit `binaryPath` supplied by the host, then
+   *   3. the bare `cloudflared` name on PATH (resolved at spawn time).
+   *
+   * On an unsupported arch (no optional dep, no binaryPath) AND no usable PATH
+   * fallback, this raises a clear, redacted error pointing at the sidecar — it
+   * NEVER downloads a binary at runtime. (Cross-platform binary management is the
+   * optional-dep packages' job, populated at publish time.)
    */
   resolveBinary() {
-    if (this.binaryPath) return this.binaryPath;
     const located = this.locateBinary();
     if (located) return located;
+    if (this.binaryPath) return this.binaryPath;
+    if (currentBinaryPackageName() !== null) return DEFAULT_BINARY;
     throw new Error(
-      "cloudflared binary not found \u2014 install it in the image, supply binaryPath, or run the sidecar runner instead. (Linux container is the V1 supported target.)"
+      "cloudflared binary not found for this platform/arch \u2014 install an @farthershore/cloudflared-<platform> package, supply binaryPath, or run the sidecar runner instead (no binary is downloaded at runtime)."
     );
   }
   /** Pipe stdout/stderr to the logger with the tunnel token redacted. */
@@ -1185,8 +1247,30 @@ function nodeProcess() {
   const proc = globalThis.process;
   return proc && typeof proc.on === "function" ? proc : null;
 }
+function currentBinaryPackageName() {
+  const proc = globalThis.process;
+  if (!proc?.platform || !proc.arch) return null;
+  return CLOUDFLARED_BINARY_PACKAGES[`${proc.platform}-${proc.arch}`] ?? null;
+}
 function defaultLocateBinary() {
-  return DEFAULT_BINARY_CANDIDATES[0] ?? DEFAULT_BINARY;
+  const pkg = currentBinaryPackageName();
+  if (!pkg) return null;
+  try {
+    const require2 = createRequire(import.meta.url);
+    const manifestPath = require2.resolve(`${pkg}/package.json`);
+    return resolvePackageBinary(require2, pkg, manifestPath);
+  } catch {
+    return null;
+  }
+}
+function resolvePackageBinary(require2, pkg, manifestPath) {
+  const sep = manifestPath.includes("\\") ? "\\" : "/";
+  const root = manifestPath.slice(0, manifestPath.lastIndexOf(sep));
+  const manifest = require2(manifestPath);
+  const binField = manifest.bin;
+  const relative = typeof binField === "string" ? binField : binField?.cloudflared ?? `bin${sep}cloudflared`;
+  const normalized = relative.replace(/^\.[\\/]/, "");
+  return `${root}${sep}${normalized}`;
 }
 
 // src/core/verifyRequest.ts
@@ -1338,8 +1422,8 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.8.1".length > 0 ? "0.8.1" : "0.0.0-dev";
-var CONTRACTS_FP = "3c1f8e3d44799bd4".length > 0 ? "3c1f8e3d44799bd4" : "0000000000000000";
+var SDK_VERSION = "0.9.0".length > 0 ? "0.9.0" : "0.0.0-dev";
+var CONTRACTS_FP = "bd767c2d91739744".length > 0 ? "bd767c2d91739744" : "0000000000000000";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1419,7 +1503,7 @@ var FartherShore = class {
    * The reflection code is dynamically imported so it stays OFF the per-request
    * verification hot path (the runtime stays route-unaware there). The report is
    * an OUTBOUND backend→core call (same channel as bootstrap/metering), so it
-   * works for every transport (public_origin / mTLS / cloudflare_tunnel).
+   * works for every transport (direct / tunnel).
    *
    * Returns the reconcile result (or null if reflection is unavailable / boot
    * reporting failed). v1 reflects Express; `app` omitted → no-op.
@@ -1494,11 +1578,11 @@ var FartherShore = class {
     return config.verification.required;
   }
   /**
-   * Start the managed runner. For a `cloudflare_tunnel` backend whose runner is
-   * `managed_cloudflared`, this supervises `cloudflared` as a child process
+   * Start the embedded runner. For a `tunnel` backend whose runner is
+   * `embedded`, this supervises `cloudflared` as a child process
    * (spawned via the injected/default spawner) using the tunnel token from
-   * bootstrap. For every other transport (`public_origin`, `mtls`, or the
-   * `sidecar` runner) it is a no-op — there is no SDK-managed process to run.
+   * bootstrap. For every other transport (`direct`, or the `sidecar` runner)
+   * it is a no-op — there is no SDK-managed process to run.
    *
    * Fail-open by default: a tunnel that cannot start does NOT crash the host app
    * (request verification stays fail-closed regardless — a different axis).
@@ -1507,7 +1591,7 @@ var FartherShore = class {
     if (this.tunnelOptions.enabled === false) return;
     const config = await this.ensureBootstrapped();
     const transport = config.transport;
-    if (transport.mode !== "cloudflare_tunnel" || transport.runner !== "managed_cloudflared") {
+    if (transport.mode !== "tunnel" || transport.runner !== "embedded") {
       return;
     }
     const tunnelToken = transport.cloudflared?.tunnelToken;
@@ -1515,7 +1599,7 @@ var FartherShore = class {
       if (this.tunnelOptions.failClosed) {
         throw new FartherShoreError(
           "invalid_token",
-          "managed cloudflared runner requires a tunnel token from bootstrap"
+          "embedded cloudflared runner requires a tunnel token from bootstrap"
         );
       }
       return;
@@ -1552,8 +1636,8 @@ var FartherShore = class {
     return buildHealthReport({
       runtimeToken: this.runtimeToken.length > 0,
       bootstrap: this.bootstrapped && config !== null,
-      // Populated by the managed-cloudflared supervisor (Slice 3). Null until
-      // fs.start() launches a managed tunnel; otherwise the supervisor state.
+      // Populated by the embedded-cloudflared supervisor (Slice 3). Null until
+      // fs.start() launches an embedded tunnel; otherwise the supervisor state.
       tunnel: this.tunnel ? this.tunnel.healthString() : null,
       verification: this.verificationEnabled && config !== null,
       metering: this.meteringClient !== null
@@ -1695,6 +1779,8 @@ 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,
@@ -1704,7 +1790,9 @@ function buildPayload(request, usage, options, wrapOptions) {
       creditUnitsConsumed: sortUsage(
         validateUsageMap(creditUnitsConsumed, "creditUnitsConsumed")
       )
-    } : {}
+    } : {},
+    ...operationKey ? { operationKey: assertIdentifier(operationKey) } : {},
+    ...usagePolicyId ? { usagePolicyId: assertIdentifier(usagePolicyId) } : {}
   };
   return JSON.stringify(payload);
 }
@@ -1739,6 +1827,15 @@ function assertMeterValue(meter, value) {
   }
   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 resolveToken(options) {
   const token = options.token ?? options.env?.[DEFAULT_TOKEN_ENV] ?? processEnv(DEFAULT_TOKEN_ENV);
   if (!token) {

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

@@ -0,0 +1,30 @@
+/** The jitter strategy applied to the capped exponential delay. */
+export type JitterStrategy = 
+/** No jitter — the raw capped exponential (deterministic). */
+"none"
+/** Equal jitter — `cap/2 + random()*cap/2` (the DEFAULT). */
+ | "equal"
+/** Full jitter — `random()*cap` (max spread, no minimum floor). */
+ | "full";
+export interface BackoffOptions {
+    /** The base delay for attempt 1 (ms). Doubles each subsequent attempt. */
+    baseMs: number;
+    /** The delay ceiling (ms) — the exponential is capped here BEFORE jitter. */
+    maxMs: number;
+    /** The jitter strategy. Defaults to `equal`. */
+    jitter?: JitterStrategy;
+    /** Injectable uniform random in [0, 1). Defaults to Math.random. */
+    random?: () => number;
+}
+/**
+ * Compute the backoff delay (ms) for `attempt` (1-based: attempt 1 is the first
+ * retry/restart). The capped exponential is `min(baseMs * 2^(attempt-1), maxMs)`;
+ * the chosen {@link JitterStrategy} (default `equal`) is then applied. The result
+ * is always in `[0, maxMs]`.
+ *
+ *   - `none`  → the raw capped exponential.
+ *   - `equal` → `cap/2 + random()*cap/2`  — a guaranteed half-cap floor plus a
+ *               randomized half (the default; avoids lockstep re-collision).
+ *   - `full`  → `random()*cap`            — maximum spread, no floor.
+ */
+export declare function computeBackoff(attempt: number, options: BackoffOptions): number;

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

@@ -16,6 +16,15 @@ export type MeteringClientOptions = {
     fetchImpl?: typeof fetch;
     /** Max retry attempts per flush before re-buffering. */
     maxRetries?: number;
+    /** Base for the exponential inter-attempt backoff (ms). Default 200. */
+    baseDelayMs?: number;
+    /** Ceiling on any single inter-attempt wait (ms) — caps both backoff and a
+     *  `Retry-After` hint. Default 10000. */
+    maxDelayMs?: number;
+    /** Injectable delay primitive (tests pass a no-op; default is a timer). */
+    sleep?: (ms: number) => Promise<void>;
+    /** Injectable uniform random in [0,1) for the backoff jitter (tests pin it). */
+    random?: () => number;
     /** Injectable id generator (tests). */
     newId?: () => string;
     now?: () => Date;
@@ -31,6 +40,10 @@ export declare class MeteringClient {
     private readonly backendId;
     private readonly fetchImpl;
     private readonly maxRetries;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly sleep;
+    private readonly random;
     private readonly newId;
     private readonly now;
     private readonly buffer;

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

@@ -3,9 +3,9 @@ import type { ReconcileResult } from "../reflect/reconcile.js";
 import { type MeterOptions } from "./metering.js";
 import { type SpawnFn } from "./tunnel.js";
 import { type FartherShoreRequestContext, type VerifyRequestInput } from "./verifyRequest.js";
-/** Advanced opt-in tunnel config. The managed runner is the default DX. */
+/** Advanced opt-in tunnel config. The embedded runner is the default DX. */
 export type FartherShoreTunnelOptions = {
-    /** Opt out of the managed cloudflared runner (e.g. sidecar mode). */
+    /** Opt out of the embedded cloudflared runner (e.g. sidecar mode). */
     enabled?: boolean;
     /** Injected spawner (tests/non-default hosts). Defaults to node:child_process. */
     spawn?: SpawnFn;
@@ -35,7 +35,7 @@ export type FartherShoreInitOptions = {
     metering?: {
         enabled?: boolean;
     };
-    /** Managed-cloudflared runner config (advanced opt-in; default DX is on). */
+    /** Embedded-cloudflared runner config (advanced opt-in; default DX is on). */
     tunnel?: FartherShoreTunnelOptions;
     /** SDK metadata forwarded to bootstrap. */
     instanceId?: string;
@@ -73,7 +73,7 @@ export declare class FartherShore {
      * The reflection code is dynamically imported so it stays OFF the per-request
      * verification hot path (the runtime stays route-unaware there). The report is
      * an OUTBOUND backend→core call (same channel as bootstrap/metering), so it
-     * works for every transport (public_origin / mTLS / cloudflare_tunnel).
+     * works for every transport (direct / tunnel).
      *
      * Returns the reconcile result (or null if reflection is unavailable / boot
      * reporting failed). v1 reflects Express; `app` omitted → no-op.
@@ -89,11 +89,11 @@ export declare class FartherShore {
     /** Whether verification is required (bootstrap × opt-out). */
     verificationRequired(): Promise<boolean>;
     /**
-     * Start the managed runner. For a `cloudflare_tunnel` backend whose runner is
-     * `managed_cloudflared`, this supervises `cloudflared` as a child process
+     * Start the embedded runner. For a `tunnel` backend whose runner is
+     * `embedded`, this supervises `cloudflared` as a child process
      * (spawned via the injected/default spawner) using the tunnel token from
-     * bootstrap. For every other transport (`public_origin`, `mtls`, or the
-     * `sidecar` runner) it is a no-op — there is no SDK-managed process to run.
+     * bootstrap. For every other transport (`direct`, or the `sidecar` runner)
+     * it is a no-op — there is no SDK-managed process to run.
      *
      * Fail-open by default: a tunnel that cannot start does NOT crash the host app
      * (request verification stays fail-closed regardless — a different axis).

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

@@ -1,4 +1,5 @@
 import type { EventEmitter } from "node:events";
+import type { JitterStrategy } from "./backoff.js";
 /** A line emitter — the subset of a child stdio stream we consume. */
 type StdioStream = Pick<EventEmitter, "on">;
 /**
@@ -58,6 +59,14 @@ export type CloudflaredSupervisorOptions = {
     baseBackoffMs?: number;
     /** Backoff ceiling. */
     maxBackoffMs?: number;
+    /** Jitter strategy for the restart backoff. Defaults to `equal` (the shared
+     *  backoff default) — half the capped exponential is fixed, half randomized,
+     *  so multiple supervisors don't re-collide in lockstep after a shared
+     *  outage. Pass `none` for a deterministic schedule. */
+    backoffJitter?: JitterStrategy;
+    /** Injectable uniform random in [0, 1) for the jitter (tests pin it). Defaults
+     *  to Math.random. */
+    random?: () => number;
     /** Injectable timer (tests use fake timers / a custom scheduler). */
     setTimeoutFn?: (cb: () => void, ms: number) => unknown;
     clearTimeoutFn?: (handle: unknown) => void;
@@ -86,6 +95,8 @@ export declare class CloudflaredSupervisor {
     private readonly failClosed;
     private readonly baseBackoffMs;
     private readonly maxBackoffMs;
+    private readonly backoffJitter;
+    private readonly random;
     private readonly setTimeoutFn;
     private readonly clearTimeoutFn;
     private readonly childEnv;
@@ -121,8 +132,16 @@ export declare class CloudflaredSupervisor {
     healthString(): string;
     private spawnChild;
     /**
-     * Resolve the cloudflared binary path. Explicit `binaryPath` wins; otherwise
-     * the injected locator runs (Linux-first). Missing ⇒ a clear, redacted error.
+     * Resolve the cloudflared binary path. Order:
+     *   1. an installed `@farthershore/cloudflared-<platform>` optional-dependency
+     *      matching process.platform+arch (the injected locator), then
+     *   2. an explicit `binaryPath` supplied by the host, then
+     *   3. the bare `cloudflared` name on PATH (resolved at spawn time).
+     *
+     * On an unsupported arch (no optional dep, no binaryPath) AND no usable PATH
+     * fallback, this raises a clear, redacted error pointing at the sidecar — it
+     * NEVER downloads a binary at runtime. (Cross-platform binary management is the
+     * optional-dep packages' job, populated at publish time.)
      */
     private resolveBinary;
     /** Pipe stdout/stderr to the logger with the tunnel token redacted. */

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

@@ -51,8 +51,8 @@ export declare const RUNTIME_BOOTSTRAP_CONTRACT: {
             readonly perEventMax: "number";
         };
         readonly transport: {
-            readonly mode: "public_origin | mtls | cloudflare_tunnel";
-            readonly runner: "managed_cloudflared | sidecar | null";
+            readonly mode: "direct | tunnel";
+            readonly runner: "embedded | sidecar | null";
             readonly originUrl: "string?";
             readonly originHostname: "string?";
             readonly localTarget: "string?";
@@ -214,15 +214,14 @@ export declare const RUNTIME_HEALTH_CONTRACT: {
 };
 export declare const RUNTIME_TRANSPORT_CONTRACT: {
     readonly modes: {
-        readonly public_origin: "Gateway fetches the builder's public origin URL; the SDK middleware fail-closed-verifies every request. Provisions zero Cloudflare objects. Standard tier; also the dev path.";
-        readonly mtls: "Gateway presents a Farther-Shore-issued platform-wide client cert; the builder's ingress requires + verifies it. Channel-level mutual auth; provisions zero Cloudflare objects. Standard-plus / self-hosted tier.";
-        readonly cloudflare_tunnel: "Farther Shore provisions a private outbound Cloudflare Tunnel; no inbound port. The only Production-secure tier. Consumes Cloudflare tunnel/route slots.";
+        readonly direct: "Gateway fetches the builder's public origin URL; the SDK middleware fail-closed-verifies every request via Ed25519 request signing. Provisions zero Cloudflare objects. Available on all tiers; also the dev path.";
+        readonly tunnel: "Farther Shore provisions a private outbound Cloudflare Tunnel; no inbound port. The Production-secure tier. Consumes Cloudflare tunnel/route slots.";
     };
     readonly runners: {
-        readonly managed_cloudflared: "fs.start() supervises cloudflared as a child process (default DX).";
+        readonly embedded: "fs.start() supervises cloudflared as a child process (default DX).";
         readonly sidecar: "Vanilla cloudflare/cloudflared container beside the app (production / non-Node).";
     };
-    readonly channelTrust: readonly ["mtls", "cloudflare_tunnel"];
+    readonly channelTrust: readonly ["tunnel"];
     readonly requestTrust: "x-fs-signature";
-    readonly invariant: "Channel trust (mtls/tunnel) and request trust (the X-FS-* signature) are distinct layers; both always apply. CF-Access-* headers are transport-layer only and are IGNORED by the SDK.";
+    readonly invariant: "Channel trust (tunnel) and request trust (the X-FS-* signature) are distinct layers; both always apply. CF-Access-* headers are transport-layer only and are IGNORED by the SDK.";
 };

package/dist/types/response-metering.d.ts

@@ -9,15 +9,24 @@ export declare const METERING_SIGNATURE_HEADER: "x-fs-metering-sig";
 export declare const METERING_TOKEN_HEADER: "x-fs-metering-token";
 export declare const DEFAULT_TOKEN_ENV: "FS_RUNTIME_TOKEN";
 export type UsageMap = Record<string, number>;
+export type BillableUsageMap = UsageMap;
 export type MeteringOptions = {
     token?: string;
     env?: Record<string, string | undefined>;
     measureContext?: Record<string, unknown>;
-    creditUnitsConsumed?: UsageMap;
+    creditUnitsConsumed?: BillableUsageMap;
+    /** Gateway-validated operation identity hint. The SDK signs and transports it
+     *  but never decides billing or policy from it. */
+    operationKey?: string;
+    /** Gateway-validated policy hint. Advisory identity only; the gateway remains
+     *  authoritative for customerBillable/provider-cost decisions. */
+    usagePolicyId?: string;
 };
 export type UsageWrapOptions = {
     measureContext?: Record<string, unknown>;
-    creditUnitsConsumed?: UsageMap;
+    creditUnitsConsumed?: BillableUsageMap;
+    operationKey?: string;
+    usagePolicyId?: string;
 };
 export type UsageReporter = {
     report(meter: string, value: number): UsageReporter;

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

@@ -27,6 +27,71 @@ export declare const LIMIT_DESCRIPTOR_FIELDS: {
     dimension: true;
     currentCapacity: true;
 };
+/**
+ * F1 — the closed usage-limit class set. Structurally identical to the contracts
+ * `LimitClass`. A backend that surfaces a usage-limit deny carries this so SDKs
+ * can branch on the limit's semantic class.
+ */
+export type LimitClass = "quota" | "rate" | "concurrency" | "capacity" | "spend" | "adaptive";
+/** Recommended client reaction to a limit deny. Mirrors contracts
+ *  `LimitReaction`. */
+export type LimitReaction = "none" | "backoff_retry" | "wait_then_retry" | "queue" | "reduce_then_retry" | "fallback" | "upgrade";
+/** Where a limit was decided. Mirrors contracts `LimitOrigin`. */
+export type LimitOrigin = "platform" | "provider";
+/**
+ * F1 — the `_fs` deny envelope a backend stamps on a usage-limit deny body.
+ * Structurally identical to the contracts `FsDenyEnvelope`.
+ */
+export interface FsDenyEnvelope {
+    limitClass: LimitClass;
+    scope?: string;
+    metric?: string;
+    reset?: number;
+    remaining?: number;
+    used?: number;
+    limit?: number;
+    retrySafe: boolean;
+    mustModify: boolean;
+    providerReason?: string;
+    limitOrigin: LimitOrigin;
+    userAction?: string;
+    devAction?: string;
+    requestId: string;
+    decisionId: string;
+    /** Which exact constraint denied (projects from `LimitDecision.blockingConstraintId`). */
+    blockingConstraintId?: string;
+    reaction: LimitReaction;
+    envelopeVersion: number;
+}
+/**
+ * F1 — the RUNTIME field set of the SDK-local {@link FsDenyEnvelope} mirror.
+ * `satisfies Record<keyof FsDenyEnvelope, true>` makes the compiler reject this
+ * if it drifts from the local interface; the drift guard then asserts it
+ * deep-equals the canonical contracts `DENY_ENVELOPE_FIELDS` at RUNTIME — so a
+ * hand-copy that adds or drops a field fails a test that actually runs.
+ * (Contracts-free: a plain local constant, never the published path to
+ * contracts.)
+ */
+export declare const DENY_ENVELOPE_FIELDS: {
+    limitClass: true;
+    scope: true;
+    metric: true;
+    reset: true;
+    remaining: true;
+    used: true;
+    limit: true;
+    retrySafe: true;
+    mustModify: true;
+    providerReason: true;
+    limitOrigin: true;
+    userAction: true;
+    devAction: true;
+    requestId: true;
+    decisionId: true;
+    blockingConstraintId: true;
+    reaction: true;
+    envelopeVersion: true;
+};
 /**
  * C-2 — the canonical core `ErrorCode` VALUES this backend can map a
  * `RuntimeErrorCode` onto (the codomain of {@link RUNTIME_ERROR_CODE_TO_ERROR_CODE}).
@@ -103,8 +168,8 @@ export type CanonicalSigningInput = {
     policyVersion: string;
 };
 export type RuntimeEnvironmentKind = RuntimeTokenKind;
-export type TransportMode = "public_origin" | "mtls" | "cloudflare_tunnel";
-export type TransportRunner = "managed_cloudflared" | "sidecar";
+export type TransportMode = "direct" | "tunnel";
+export type TransportRunner = "embedded" | "sidecar";
 export type RuntimeBootstrapRequest = {
     instanceId?: string;
     sdkVersion?: string;
@@ -135,7 +200,6 @@ export type RuntimeTransportConfig = {
         tunnelToken: string;
         version: string;
     };
-    mtlsClientCertRef?: string;
 };
 export type RuntimeRouteDescriptor = {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.8.1",
+  "version": "0.9.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",
@@ -31,6 +31,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "optionalDependencies": {
+    "@farthershore/cloudflared-linux-x64": "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": {
     "express": "^4.0.0 || ^5.0.0"
   },