@farthershore/backend 0.1.0 → 0.3.0

package/README.md

@@ -1,9 +1,8 @@
 # @farthershore/backend
 
-The secure BYO-backend runtime SDK. Install one package, set one token
-(`FS_RUNTIME_TOKEN`), and Farther Shore protects (signs every gateway→backend
-request; the SDK verifies and rejects anything not from Farther Shore) and meters
-your backend.
+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.
 
 ## Install
 
@@ -11,20 +10,43 @@ your backend.
 npm install @farthershore/backend
 ```
 
-## Quick start (Express)
+## Quick start (Fetch-compatible handlers)
 
 ```ts
-import { fartherShore } from "@farthershore/backend";
+import { fartherShore, withUsage } from "@farthershore/backend";
 
 const fs = fartherShore.initFromEnv(); // derives everything from FS_RUNTIME_TOKEN
 
-app.use(fs.middleware()); // fail-closed verify → req.fartherShore
+export async function POST(request: Request) {
+  const url = new URL(request.url);
+  const body = new Uint8Array(await request.clone().arrayBuffer());
+
+  await fs.verifyRequest({
+    method: request.method,
+    path: url.pathname,
+    query: url.search,
+    headers: request.headers,
+    body,
+  });
+
+  const result = await runWorkflow(await request.json());
+  return withUsage(request, Response.json(result), {
+    tokens_used: result.tokensUsed,
+  });
+}
+```
+
+## Express verification
+
+```ts
+import { fartherShore } from "@farthershore/backend";
+
+const fs = fartherShore.initFromEnv();
+
+app.use(fs.middleware()); // fail-closed verify -> req.fartherShore
 
 app.post("/v1/runs", async (req, res) => {
   const result = await runWorkflow(req.body);
-  await fs.meter("tokens", result.tokensUsed, {
-    requestId: req.fartherShore.requestId,
-  });
   res.json(result);
 });
 
@@ -35,7 +57,7 @@ process.on("SIGTERM", () => void fs.shutdown());
 ## What `initFromEnv()` derives
 
 The builder configures exactly one thing: `FS_RUNTIME_TOKEN`. Everything else —
-product/backend/environment ids, the JWKS url, the metering endpoint and
+product/upstream/environment ids, the JWKS url, the metering endpoint and
 credential, verification config, transport — is fetched from
 `POST /v1/runtime/bootstrap` and cached in memory (refreshed lazily).
 
@@ -43,7 +65,7 @@ credential, verification config, transport — is fetched from
 
 `fs.middleware()` (Express) and the framework-neutral
 `fs.verifyRequest({ method, path, query, headers, body })` recompute the
-[canonical signing string](../../docs/superpowers/specs/backend-runtime-spec.md)
+[canonical signing string](../../docs/superpowers/specs/metering-runtime-spec.md)
 from the actual request and verify the gateway's Ed25519 signature against a
 JWKS-resolved public key. The plaintext `X-FS-*` headers are **untrusted** —
 identity comes only from a signature whose claims match the real request.
@@ -53,18 +75,50 @@ wrong-route / body-hash-mismatch / replayed-nonce / unknown-kid /
 jwks-unavailable) returns a typed `FartherShoreError` → **HTTP 401** (413 for
 oversized bodies). There is no fail-open branch.
 
-## Metering (billing-only)
+## Response-bound metering
+
+Use `withUsage()` or `createUsage()` when usage is known while returning a
+gateway-handled response. These helpers make no network call. They sign dynamic
+usage into internal response headers, and the gateway verifies, settles, and
+strips those headers before the subscriber receives the response.
+
+```ts
+import { withUsage } from "@farthershore/backend";
+
+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 },
+    },
+  );
+}
+```
+
+`measureContext` is free-form pricing/analytics context persisted with the usage
+event. `creditUnitsConsumed` is a numeric map for credit-wallet style products;
+keys and values are validated locally before signing. The gateway accepts actual
+request-bound usage only from the `x-fs-metering` response-header contract signed
+with `FS_RUNTIME_TOKEN`; retired `x-fs-usage` actual-report headers are stripped
+and ignored.
+
+## Async/background metering
 
-`fs.meter(meter, qty, { requestId, routeId })` enqueues an idempotent event and
+Use `fs.meter(meter, qty, { requestId, routeId })` only for async/background
+usage that is not tied to a gateway response. It enqueues an idempotent event and
 POSTs it to `/v1/metering/events` with a reusable bearer credential. Delivery is
 at-least-once; the `event_id` idempotency key keeps core's ingest safe. Values
 are tallied/billed post-cycle, not real-time enforced.
 
-## Migrating from `@farthershore/metering`
+The meter key is not hardcoded by the SDK. It must match a dynamic meter declared
+in the product contract, such as `tokens_used` in the Product SDK examples.
 
-`@farthershore/metering` is now a deprecated re-export shim of this package and
-will be removed after the metering cutover. Replace the import; for new code,
-prefer `fs.meter("tokens", n)` over the response-header signer.
+Product route defaults such as request counts remain platform-managed and
+require no upstream code.
 
 The signing primitives and contract constants are re-exported from
 `@farthershore/contracts/runtime`, the language-neutral source of truth every

package/dist/generated/runtime-contract.js

@@ -180,7 +180,44 @@ var RUNTIME_METERING_CONTRACT = {
   delivery: "at-least-once",
   billingOnly: true,
   realtimeEnforced: false,
-  trustModel: "backend-reported values are NOT cryptographically attested; a buggy or compromised backend can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert."
+  trustModel: "upstream-reported values are NOT cryptographically attested; a buggy or compromised upstream can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert."
+};
+var RUNTIME_RESPONSE_METERING_CONTRACT = {
+  headers: {
+    payload: "x-fs-metering",
+    signature: "x-fs-metering-sig",
+    token: "x-fs-metering-token"
+  },
+  token: {
+    environmentVariable: "FS_RUNTIME_TOKEN",
+    presentation: "x-fs-metering-token",
+    storage: "sha256-hash-only"
+  },
+  signature: {
+    algorithm: "HMAC-SHA256",
+    encoding: "base64url",
+    input: "payload-json",
+    secret: "presented-runtime-token"
+  },
+  payload: {
+    method: "string",
+    path: "string",
+    rawDimsUnits: "Record<string, number>",
+    measureContext: "Record<string, unknown>?",
+    creditUnitsConsumed: "Record<string, number>?"
+  },
+  errors: {
+    missingToken: "missing_token",
+    invalidMeterKey: "invalid_meter_key",
+    invalidMeterValue: "invalid_meter_value"
+  },
+  httpAdapter: {
+    input: "Request",
+    output: "Response",
+    networkCalls: false,
+    preserves: ["body", "headers", "status", "statusText"],
+    gatewayStripsInternalHeaders: true
+  }
 };
 var RUNTIME_HEALTH_CONTRACT = {
   endpoint: "/v1/runtime/health",
@@ -232,6 +269,7 @@ export {
   RUNTIME_HEALTH_CONTRACT,
   RUNTIME_METERING_CONTRACT,
   RUNTIME_REPLAY_CONTRACT,
+  RUNTIME_RESPONSE_METERING_CONTRACT,
   RUNTIME_SIGNING_CONTRACT,
   RUNTIME_TOKEN_CONTRACT,
   RUNTIME_TOKEN_ENV,

package/dist/index.js

@@ -1,4 +1,188 @@
 import { createRequire as __createRequire } from "node:module";const require=__createRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/reflect/route-canon.ts
+import { createHash } from "node:crypto";
+function normalizeSegment(seg) {
+  if (seg === "**") return "{rest}";
+  if (seg === "*") return "{splat}";
+  if (seg.startsWith(":")) return `{${seg.slice(1)}}`;
+  if (seg.startsWith("[") && seg.endsWith("]")) return `{${seg.slice(1, -1)}}`;
+  return seg;
+}
+function normalizePath(path) {
+  if (path === "/" || path === "") return "/";
+  const lead = path.startsWith("/");
+  const out = path.split("/").filter((s) => s.length > 0).map(normalizeSegment).join("/");
+  return lead ? `/${out}` : out;
+}
+function pathSpecificity(path) {
+  return path.split("/").filter(
+    (s) => s.length > 0 && !s.startsWith("{") && s !== "*" && s !== "**"
+  ).length;
+}
+function canonicalSort(routes) {
+  return [...routes].sort(
+    (a, b) => pathSpecificity(b.path) - pathSpecificity(a.path) || a.method.localeCompare(b.method) || a.path.localeCompare(b.path)
+  );
+}
+function surfaceHash(routes) {
+  const canonical = canonicalSort(routes).map(
+    (r) => `${r.method.toUpperCase()} ${r.path}`
+  );
+  const h = createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+  return `sha256:${h}`;
+}
+var init_route_canon = __esm({
+  "src/reflect/route-canon.ts"() {
+    "use strict";
+  }
+});
+
+// src/reflect/index.ts
+var reflect_exports = {};
+__export(reflect_exports, {
+  reflectRoutes: () => reflectRoutes,
+  reflectRoutesDetailed: () => reflectRoutesDetailed
+});
+function methodsOf(route) {
+  const out = /* @__PURE__ */ new Set();
+  if (route.methods) {
+    for (const [m, on] of Object.entries(route.methods))
+      if (on) out.add(m.toUpperCase());
+  }
+  for (const s of route.stack ?? []) {
+    if (typeof s.method === "string") out.add(s.method.toUpperCase());
+  }
+  return [...out].filter((m) => VALID_METHODS.has(m));
+}
+function rootStack(app) {
+  const a = app;
+  return a?.router?.stack ?? a?._router?.stack;
+}
+function prefixFromRegexp(re) {
+  if (!re) return void 0;
+  let s = re.source;
+  if (s === "^\\/?$" || s === "^\\/") return "";
+  s = s.replace(/^\^/, "").replace(/\\\/\?\(\?=\\\/\|\$\)$/, "").replace(/\(\?=\\\/\|\$\)$/, "").replace(/\\\/\?$/, "").replace(/\$$/, "");
+  s = s.replace(/\\\//g, "/");
+  if (/[()?:*+\[\]|]/.test(s)) return void 0;
+  return s.startsWith("/") ? s : `/${s}`;
+}
+function walk(stack, prefix, out, counters) {
+  for (const layer of stack) {
+    if (layer.route && typeof layer.route.path === "string") {
+      const path = normalizePath(`${prefix}${layer.route.path}`);
+      for (const method of methodsOf(layer.route)) {
+        out.push({ method, path });
+      }
+    } else if (layer.handle?.stack && Array.isArray(layer.handle.stack)) {
+      const sub = prefixFromRegexp(layer.regexp);
+      if (sub === void 0 && layer.name === "router") {
+        counters.unreflectable += layer.handle.stack.filter(
+          (l) => l.route
+        ).length;
+        continue;
+      }
+      walk(layer.handle.stack, `${prefix}${sub ?? ""}`, out, counters);
+    }
+  }
+}
+function reflectRoutesDetailed(app, _opts) {
+  const stack = rootStack(app);
+  if (!stack) return { routes: [], unreflectable: 0 };
+  const raw = [];
+  const counters = { unreflectable: 0 };
+  walk(stack, "", raw, counters);
+  const seen = /* @__PURE__ */ new Set();
+  const routes = [];
+  for (const r of raw) {
+    if (r.method === "HEAD") continue;
+    const key2 = `${r.method} ${r.path}`;
+    if (seen.has(key2)) continue;
+    seen.add(key2);
+    routes.push(r);
+  }
+  return { routes, unreflectable: counters.unreflectable };
+}
+function reflectRoutes(app, opts) {
+  return reflectRoutesDetailed(app, opts).routes;
+}
+var VALID_METHODS;
+var init_reflect = __esm({
+  "src/reflect/index.ts"() {
+    "use strict";
+    init_route_canon();
+    VALID_METHODS = /* @__PURE__ */ new Set([
+      "GET",
+      "POST",
+      "PUT",
+      "PATCH",
+      "DELETE",
+      "OPTIONS"
+    ]);
+  }
+});
+
+// src/reflect/reconcile.ts
+var reconcile_exports = {};
+__export(reconcile_exports, {
+  reconcileOnStartup: () => reconcileOnStartup
+});
+function key(r) {
+  return `${r.method.toUpperCase()} ${r.path}`;
+}
+async function reconcileOnStartup(args) {
+  const { reflected, bootstrap, report } = args;
+  const reflectedHash = surfaceHash(reflected);
+  const lockVersion = bootstrap.lock?.lockVersion ?? 0;
+  const inSync = bootstrap.lock?.surfaceHash === reflectedHash;
+  const result = {
+    inSync,
+    reportedDrift: false,
+    confirmedRouteIds: []
+  };
+  const servedKeys = new Set(reflected.map(key));
+  const confirmedRouteIds = (bootstrap.routes ?? []).filter(
+    (r) => r.pending === true && servedKeys.has(key(r)) && typeof r.id === "string"
+  ).map((r) => r.id);
+  try {
+    if (confirmedRouteIds.length > 0) {
+      await report.confirmServed({
+        backendId: bootstrap.backendId,
+        lockVersion,
+        servedRouteIds: confirmedRouteIds
+      });
+      result.confirmedRouteIds = confirmedRouteIds;
+    }
+    if (!inSync) {
+      await report.reportDrift({
+        backendId: bootstrap.backendId,
+        lockVersion,
+        reflectedSurfaceHash: reflectedHash,
+        routes: reflected.map((r) => ({ method: r.method, path: r.path }))
+      });
+      result.reportedDrift = true;
+    }
+  } catch (err) {
+    result.reportError = err instanceof Error ? err.message : String(err);
+  }
+  return result;
+}
+var init_reconcile = __esm({
+  "src/reflect/reconcile.ts"() {
+    "use strict";
+    init_route_canon();
+  }
+});
 
 // src/runtime-types.ts
 var FS_RUNTIME_TOKEN_ENV = "FS_RUNTIME_TOKEN";
@@ -10,7 +194,10 @@ var RUNTIME_TOKEN_CAPABILITIES = [
   "gateway_verification",
   "metering",
   "health",
-  "tunnel"
+  "tunnel",
+  // Mirror of @farthershore/contracts RUNTIME_TOKEN_CAPABILITIES — kept in
+  // lockstep (golden-vector test). Opt-in capability for reporting route drift.
+  "drift_report"
 ];
 var RUNTIME_HEADER_NAMES = {
   signature: "x-fs-signature",
@@ -30,6 +217,7 @@ var STREAMING_EXEMPT_BODY_HASH = "STREAM";
 var MAX_BODY_BYTES = 10 * 1024 * 1024;
 
 // ../contracts/dist/runtime.js
+var FS_RUNTIME_TOKEN_ENV2 = "FS_RUNTIME_TOKEN";
 var RUNTIME_TOKEN_PREFIXES2 = {
   live: "fsrt_live_",
   test: "fsrt_test_"
@@ -41,6 +229,16 @@ function runtimeTokenKind(token) {
     return "test";
   return null;
 }
+var RESPONSE_METERING_HEADER_NAMES = {
+  payload: "x-fs-metering",
+  signature: "x-fs-metering-sig",
+  token: "x-fs-metering-token"
+};
+var RESPONSE_METERING_TOKEN_CONTRACT = {
+  environmentVariable: FS_RUNTIME_TOKEN_ENV2,
+  presentation: RESPONSE_METERING_HEADER_NAMES.token,
+  storage: "sha256-hash-only"
+};
 var MAX_BODY_BYTES2 = 10 * 1024 * 1024;
 async function hashBody(body) {
   const bytes = new Uint8Array(body);
@@ -106,13 +304,13 @@ async function importEd25519PublicKey(jwk) {
   return crypto.subtle.importKey("jwk", { ...jwk, alg: void 0 }, { name: ED25519_ALGORITHM }, false, ["verify"]);
 }
 async function signCanonicalString(canonical, privateJwk) {
-  const key = await importEd25519PrivateKey(privateJwk);
-  const sig = await crypto.subtle.sign(ED25519_ALGORITHM, key, new TextEncoder().encode(canonical));
+  const key2 = await importEd25519PrivateKey(privateJwk);
+  const sig = await crypto.subtle.sign(ED25519_ALGORITHM, key2, new TextEncoder().encode(canonical));
   return base64UrlEncode(new Uint8Array(sig));
 }
 async function verifyCanonicalSignature(canonical, signatureB64Url, publicJwk) {
-  const key = await importEd25519PublicKey(publicJwk);
-  return crypto.subtle.verify(ED25519_ALGORITHM, key, base64UrlDecode(signatureB64Url), new TextEncoder().encode(canonical));
+  const key2 = await importEd25519PublicKey(publicJwk);
+  return crypto.subtle.verify(ED25519_ALGORITHM, key2, base64UrlDecode(signatureB64Url), new TextEncoder().encode(canonical));
 }
 function toHex(bytes) {
   let out = "";
@@ -334,10 +532,10 @@ var JwksClient = class {
       );
     }
     await this.refresh();
-    const key = this.keysByKid.get(kid);
-    if (key) {
+    const key2 = this.keysByKid.get(kid);
+    if (key2) {
       this.negativeKids.delete(kid);
-      return key;
+      return key2;
     }
     this.rememberMissingKid(kid);
     throw new FartherShoreError(
@@ -391,8 +589,8 @@ var JwksClient = class {
       return;
     }
     const next = /* @__PURE__ */ new Map();
-    for (const key of doc.keys ?? []) {
-      if (typeof key.kid === "string") next.set(key.kid, key);
+    for (const key2 of doc.keys ?? []) {
+      if (typeof key2.kid === "string") next.set(key2.kid, key2);
     }
     this.keysByKid = next;
     this.fetchedAt = this.now();
@@ -469,11 +667,19 @@ var MeteringClient = class {
         `meter '${meter}' is not in the token's allowedMeters`
       );
     }
-    if (options.routeId && this.config.allowedRoutes.length > 0 && !this.config.allowedRoutes.includes(options.routeId)) {
-      throw new FartherShoreError(
-        "invalid_token",
-        `route '${options.routeId}' is not in the token's allowedRoutes`
-      );
+    if (this.config.allowedRoutes.length > 0) {
+      if (!options.routeId) {
+        throw new FartherShoreError(
+          "invalid_token",
+          "routeId is required because this runtime token is route-scoped"
+        );
+      }
+      if (!this.config.allowedRoutes.includes(options.routeId)) {
+        throw new FartherShoreError(
+          "invalid_token",
+          `route '${options.routeId}' is not in the token's allowedRoutes`
+        );
+      }
     }
     if (this.config.perEventMax > 0 && qty > this.config.perEventMax) {
       throw new FartherShoreError(
@@ -521,9 +727,6 @@ var MeteringClient = class {
           body: JSON.stringify(event)
         });
         if (response.ok) return true;
-        if (response.status >= 400 && response.status < 500 && response.status !== 429) {
-          return true;
-        }
       } catch {
       }
     }
@@ -1016,12 +1219,12 @@ function headerGetter(headers) {
     return (name) => h.get(name) ?? void 0;
   }
   const lower = /* @__PURE__ */ new Map();
-  for (const [key, value] of Object.entries(
+  for (const [key2, value] of Object.entries(
     headers
   )) {
     if (value === void 0) continue;
     lower.set(
-      key.toLowerCase(),
+      key2.toLowerCase(),
       Array.isArray(value) ? value[0] ?? "" : value
     );
   }
@@ -1029,8 +1232,8 @@ function headerGetter(headers) {
 }
 
 // src/core/runtime.ts
-var DEFAULT_CORE_URL = "https://api.farthershore.com";
-var SDK_VERSION = "0.1.0";
+var DEFAULT_CORE_URL = "https://core.farthershore.com";
+var SDK_VERSION = "0.3.0".length > 0 ? "0.3.0" : "0.0.0-dev";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1101,6 +1304,60 @@ var FartherShore = class {
     this.bootstrapped = true;
     return config;
   }
+  /**
+   * Boot-time route reconciliation (call once, before `listen()`). Reflects the
+   * app's real route surface, diffs it against the declared lock from bootstrap,
+   * REPORTS drift to the platform, and CONFIRMS the declared `pending` routes
+   * this replica serves. Fail-OPEN: never throws / never blocks boot.
+   *
+   * 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).
+   *
+   * Returns the reconcile result (or null if reflection is unavailable / boot
+   * reporting failed). v1 reflects Express; `app` omitted → no-op.
+   */
+  async ready(app) {
+    try {
+      const config = await this.ensureBootstrapped();
+      if (app === void 0) return null;
+      const [{ reflectRoutes: reflectRoutes2 }, { reconcileOnStartup: reconcileOnStartup2 }] = await Promise.all([
+        Promise.resolve().then(() => (init_reflect(), reflect_exports)),
+        Promise.resolve().then(() => (init_reconcile(), reconcile_exports))
+      ]);
+      return await reconcileOnStartup2({
+        reflected: reflectRoutes2(app),
+        bootstrap: {
+          backendId: config.backend.id,
+          lock: config.lock,
+          routes: config.routes
+        },
+        report: this.buildReportSink()
+      });
+    } catch {
+      return null;
+    }
+  }
+  /** Outbound report sink for `ready()` — runtime-token-authed POSTs to core. */
+  buildReportSink() {
+    const post = async (path, body) => {
+      const base = this.coreUrl.replace(/\/$/, "");
+      const res = await this.fetchImpl(`${base}${path}`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.runtimeToken}`
+        },
+        body: JSON.stringify(body)
+      });
+      if (!res.ok) throw new Error(`runtime report ${path} -> ${res.status}`);
+    };
+    return {
+      reportDrift: (report) => post("/v1/runtime/drift", report),
+      confirmServed: (confirm) => post("/v1/runtime/health", confirm)
+    };
+  }
   /**
    * Framework-neutral verification primitive. Fail-closed: throws a typed
    * FartherShoreError on any verification failure. Returns the verified context.
@@ -1244,6 +1501,43 @@ var RUNTIME_ERROR_CODES = {
   missingToken: "missing_token",
   invalidToken: "invalid_token"
 };
+var RUNTIME_RESPONSE_METERING_CONTRACT = {
+  headers: {
+    payload: "x-fs-metering",
+    signature: "x-fs-metering-sig",
+    token: "x-fs-metering-token"
+  },
+  token: {
+    environmentVariable: "FS_RUNTIME_TOKEN",
+    presentation: "x-fs-metering-token",
+    storage: "sha256-hash-only"
+  },
+  signature: {
+    algorithm: "HMAC-SHA256",
+    encoding: "base64url",
+    input: "payload-json",
+    secret: "presented-runtime-token"
+  },
+  payload: {
+    method: "string",
+    path: "string",
+    rawDimsUnits: "Record<string, number>",
+    measureContext: "Record<string, unknown>?",
+    creditUnitsConsumed: "Record<string, number>?"
+  },
+  errors: {
+    missingToken: "missing_token",
+    invalidMeterKey: "invalid_meter_key",
+    invalidMeterValue: "invalid_meter_value"
+  },
+  httpAdapter: {
+    input: "Request",
+    output: "Response",
+    networkCalls: false,
+    preserves: ["body", "headers", "status", "statusText"],
+    gatewayStripsInternalHeaders: true
+  }
+};
 
 // src/adapters/express.ts
 var STREAMING_CONTENT_TYPES = new Set(
@@ -1311,24 +1605,13 @@ function headerValue(headers, name) {
   return value;
 }
 
-// src/generated/metering-contract.ts
-var METERING_HEADERS = {
-  payload: "x-fs-metering",
-  signature: "x-fs-metering-sig",
-  token: "x-fs-metering-token"
-};
-var METERING_TOKEN_ENV = "FARTHERSHORE_METERING_TOKEN";
-var METERING_ERROR_CODES = {
-  missingToken: "missing_token",
-  invalidMeterKey: "invalid_meter_key",
-  invalidMeterValue: "invalid_meter_value"
-};
-
-// src/legacy/metering.ts
-var METERING_PAYLOAD_HEADER = METERING_HEADERS.payload;
-var METERING_SIGNATURE_HEADER = METERING_HEADERS.signature;
-var METERING_TOKEN_HEADER = METERING_HEADERS.token;
-var DEFAULT_TOKEN_ENV = METERING_TOKEN_ENV;
+// src/response-metering.ts
+var RESPONSE_METERING_HEADERS = RUNTIME_RESPONSE_METERING_CONTRACT.headers;
+var RESPONSE_METERING_ERROR_CODES = RUNTIME_RESPONSE_METERING_CONTRACT.errors;
+var METERING_PAYLOAD_HEADER = RESPONSE_METERING_HEADERS.payload;
+var METERING_SIGNATURE_HEADER = RESPONSE_METERING_HEADERS.signature;
+var METERING_TOKEN_HEADER = RESPONSE_METERING_HEADERS.token;
+var DEFAULT_TOKEN_ENV = RUNTIME_RESPONSE_METERING_CONTRACT.token.environmentVariable;
 var MeteringError = class extends Error {
   code;
   constructor(code, message) {
@@ -1344,8 +1627,8 @@ function createUsage(request, options = {}) {
       usage[assertMeterKey(meter)] = assertMeterValue(meter, value);
       return reporter;
     },
-    async wrap(response) {
-      return signResponse(request, response, usage, options);
+    async wrap(response, wrapOptions = {}) {
+      return signResponse(request, response, usage, options, wrapOptions);
     }
   };
   return reporter;
@@ -1357,9 +1640,9 @@ async function withUsage(request, response, usage, options = {}) {
   }
   return reporter.wrap(response);
 }
-async function signResponse(request, response, usage, options) {
+async function signResponse(request, response, usage, options, wrapOptions) {
   const token = resolveToken(options);
-  const payload = buildPayload(request, usage);
+  const payload = buildPayload(request, usage, options, wrapOptions);
   const signature = await signPayload(payload, token);
   const headers = new Headers(response.headers);
   headers.set(METERING_PAYLOAD_HEADER, payload);
@@ -1371,12 +1654,20 @@ async function signResponse(request, response, usage, options) {
     headers
   });
 }
-function buildPayload(request, usage) {
+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 payload = {
     method: request.method.toUpperCase(),
     path: url.pathname,
-    rawDimsUnits: sortUsage(usage)
+    rawDimsUnits: sortUsage(usage),
+    ...measureContext ? { measureContext } : {},
+    ...creditUnitsConsumed ? {
+      creditUnitsConsumed: sortUsage(
+        validateUsageMap(creditUnitsConsumed, "creditUnitsConsumed")
+      )
+    } : {}
   };
   return JSON.stringify(payload);
 }
@@ -1385,10 +1676,18 @@ function sortUsage(usage) {
     Object.entries(usage).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
   );
 }
+function validateUsageMap(usage, label) {
+  return Object.fromEntries(
+    Object.entries(usage).map(([meter, value]) => [
+      assertMeterKey(meter),
+      assertMeterValue(`${label}.${meter}`, value)
+    ])
+  );
+}
 function assertMeterKey(meter) {
   if (!/^[a-z0-9_]{1,64}$/.test(meter)) {
     throw new MeteringError(
-      METERING_ERROR_CODES.invalidMeterKey,
+      RESPONSE_METERING_ERROR_CODES.invalidMeterKey,
       `meter key "${meter}" must be lowercase alphanumeric with underscores`
     );
   }
@@ -1397,7 +1696,7 @@ function assertMeterKey(meter) {
 function assertMeterValue(meter, value) {
   if (!Number.isFinite(value) || value < 0) {
     throw new MeteringError(
-      METERING_ERROR_CODES.invalidMeterValue,
+      RESPONSE_METERING_ERROR_CODES.invalidMeterValue,
       `meter "${meter}" value must be a non-negative finite number`
     );
   }
@@ -1407,18 +1706,18 @@ function resolveToken(options) {
   const token = options.token ?? options.env?.[DEFAULT_TOKEN_ENV] ?? processEnv(DEFAULT_TOKEN_ENV);
   if (!token) {
     throw new MeteringError(
-      METERING_ERROR_CODES.missingToken,
+      RESPONSE_METERING_ERROR_CODES.missingToken,
       `${DEFAULT_TOKEN_ENV} is required to sign Farther Shore metering reports`
     );
   }
   return token;
 }
-function processEnv(key) {
+function processEnv(key2) {
   const maybeProcess = globalThis.process;
-  return maybeProcess?.env?.[key];
+  return maybeProcess?.env?.[key2];
 }
 async function signPayload(payload, token) {
-  const key = await crypto.subtle.importKey(
+  const key2 = await crypto.subtle.importKey(
     "raw",
     new TextEncoder().encode(token),
     { name: "HMAC", hash: "SHA-256" },
@@ -1427,7 +1726,7 @@ async function signPayload(payload, token) {
   );
   const signature = await crypto.subtle.sign(
     "HMAC",
-    key,
+    key2,
     new TextEncoder().encode(payload)
   );
   return base64url(new Uint8Array(signature));

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

@@ -2,7 +2,7 @@ import { type RuntimeBootstrapRequest, type RuntimeBootstrapResponse } from "../
 /** Where to reach core's bootstrap endpoint. Derived from the token's coreUrl. */
 export type BootstrapClientOptions = {
     runtimeToken: string;
-    /** Core base URL, e.g. https://api.farthershore.com. */
+    /** Core base URL, e.g. https://core.farthershore.com. */
     coreUrl: string;
     /** Optional bootstrap request metadata. */
     request?: RuntimeBootstrapRequest;

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

@@ -1,4 +1,5 @@
 import { type RuntimeBootstrapResponse, type RuntimeHealthReport } from "../runtime-types.js";
+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";
@@ -20,7 +21,7 @@ export type FartherShoreInitOptions = {
     runtimeToken?: string;
     /**
      * Core base URL. Defaults to FS_CORE_URL / FARTHERSHORE_CORE_URL or
-     * https://api.farthershore.com.
+     * https://core.farthershore.com.
      */
     coreUrl?: string;
     /** Env map (tests). Defaults to process.env. */
@@ -39,6 +40,7 @@ export type FartherShoreInitOptions = {
     /** SDK metadata forwarded to bootstrap. */
     instanceId?: string;
 };
+export declare const SDK_VERSION: string;
 /**
  * The runtime instance. Lazily bootstraps; holds the JWKS client, nonce cache,
  * metering buffer, and shutdown hooks.
@@ -61,6 +63,23 @@ export declare class FartherShore {
     constructor(options?: FartherShoreInitOptions);
     /** Ensure bootstrap config is loaded; build the JWKS + metering clients. */
     ensureBootstrapped(): Promise<RuntimeBootstrapResponse>;
+    /**
+     * Boot-time route reconciliation (call once, before `listen()`). Reflects the
+     * app's real route surface, diffs it against the declared lock from bootstrap,
+     * REPORTS drift to the platform, and CONFIRMS the declared `pending` routes
+     * this replica serves. Fail-OPEN: never throws / never blocks boot.
+     *
+     * 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).
+     *
+     * Returns the reconcile result (or null if reflection is unavailable / boot
+     * reporting failed). v1 reflects Express; `app` omitted → no-op.
+     */
+    ready(app?: unknown): Promise<ReconcileResult | null>;
+    /** Outbound report sink for `ready()` — runtime-token-authed POSTs to core. */
+    private buildReportSink;
     /**
      * Framework-neutral verification primitive. Fail-closed: throws a typed
      * FartherShoreError on any verification failure. Returns the verified context.

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

@@ -156,7 +156,44 @@ export declare const RUNTIME_METERING_CONTRACT: {
     readonly delivery: "at-least-once";
     readonly billingOnly: true;
     readonly realtimeEnforced: false;
-    readonly trustModel: "backend-reported values are NOT cryptographically attested; a buggy or compromised backend can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert.";
+    readonly trustModel: "upstream-reported values are NOT cryptographically attested; a buggy or compromised upstream can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert.";
+};
+export declare const RUNTIME_RESPONSE_METERING_CONTRACT: {
+    readonly headers: {
+        readonly payload: "x-fs-metering";
+        readonly signature: "x-fs-metering-sig";
+        readonly token: "x-fs-metering-token";
+    };
+    readonly token: {
+        readonly environmentVariable: "FS_RUNTIME_TOKEN";
+        readonly presentation: "x-fs-metering-token";
+        readonly storage: "sha256-hash-only";
+    };
+    readonly signature: {
+        readonly algorithm: "HMAC-SHA256";
+        readonly encoding: "base64url";
+        readonly input: "payload-json";
+        readonly secret: "presented-runtime-token";
+    };
+    readonly payload: {
+        readonly method: "string";
+        readonly path: "string";
+        readonly rawDimsUnits: "Record<string, number>";
+        readonly measureContext: "Record<string, unknown>?";
+        readonly creditUnitsConsumed: "Record<string, number>?";
+    };
+    readonly errors: {
+        readonly missingToken: "missing_token";
+        readonly invalidMeterKey: "invalid_meter_key";
+        readonly invalidMeterValue: "invalid_meter_value";
+    };
+    readonly httpAdapter: {
+        readonly input: "Request";
+        readonly output: "Response";
+        readonly networkCalls: false;
+        readonly preserves: readonly ["body", "headers", "status", "statusText"];
+        readonly gatewayStripsInternalHeaders: true;
+    };
 };
 export declare const RUNTIME_HEALTH_CONTRACT: {
     readonly endpoint: "/v1/runtime/health";

package/dist/types/index.d.ts

@@ -16,7 +16,7 @@ export { createExpressMiddleware, type ExpressMiddleware, type ExpressRequestLik
 export { FS_RUNTIME_TOKEN_ENV, RUNTIME_TOKEN_PREFIXES, RUNTIME_TOKEN_CAPABILITIES, RUNTIME_HEADER_NAMES, RUNTIME_CLOCK_SKEW_SECONDS, RUNTIME_REPLAY_WINDOW_SECONDS, EMPTY_BODY_SHA256, STREAMING_EXEMPT_BODY_HASH, MAX_BODY_BYTES, type RuntimeErrorCode, type RuntimeTokenCapability, type CanonicalSigningInput, type RuntimeBootstrapResponse, type RuntimeMeteringEvent, type RuntimeHealthReport, type TransportMode, } from "./runtime-types.js";
 export { RUNTIME_ERROR_CODES } from "./generated/runtime-contract.js";
 export { hashBody, buildCanonicalSigningString, canonicalizeQuery, signCanonicalString, verifyCanonicalSignature, runtimeTokenKind, } from "./runtime-signing.js";
-export { createUsage, withUsage, MeteringError, METERING_PAYLOAD_HEADER, METERING_SIGNATURE_HEADER, METERING_TOKEN_HEADER, DEFAULT_TOKEN_ENV, type UsageMap, type UsageReporter, type MeteringOptions, } from "./legacy/metering.js";
+export { createUsage, withUsage, MeteringError, METERING_PAYLOAD_HEADER, METERING_SIGNATURE_HEADER, METERING_TOKEN_HEADER, DEFAULT_TOKEN_ENV, type UsageMap, type UsageReporter, type MeteringOptions, } from "./response-metering.js";
 /**
  * The conceptual public entrypoint. `fartherShore.initFromEnv()` mirrors the
  * language-neutral spec. The returned instance is augmented with `middleware()`

package/dist/types/reflect/index.d.ts

@@ -0,0 +1,16 @@
+import type { ReflectedRoute } from "./route-canon.js";
+export interface ReflectResult {
+    routes: ReflectedRoute[];
+    /** Count of sub-mounted routes that couldn't be reflected (Express-5 mount). */
+    unreflectable: number;
+}
+export interface ReflectOptions {
+    framework?: "express";
+}
+/** Reflect with diagnostics. Use `reflectRoutes` for just the canonical list. */
+export declare function reflectRoutesDetailed(app: unknown, _opts?: ReflectOptions): ReflectResult;
+/**
+ * Reflect the routes an Express app serves into the canonical `ReflectedRoute[]`.
+ * Deduped, HEAD-suppressed, canonical paths (`:id`→`{id}`).
+ */
+export declare function reflectRoutes(app: unknown, opts?: ReflectOptions): ReflectedRoute[];

package/dist/types/reflect/reconcile.d.ts

@@ -0,0 +1,42 @@
+import { type ReflectedRoute, type DriftReport, type PendingConfirm } from "./route-canon.js";
+/** The slice of the bootstrap response reconciliation needs. */
+export interface StartupBootstrap {
+    backendId: string;
+    lock?: {
+        surfaceHash: string;
+        lockVersion: number;
+    };
+    routes?: Array<{
+        id?: string;
+        method: string;
+        path: string;
+        pending?: boolean;
+    }>;
+}
+/** Where reconciliation sends its outbound reports (DI for tests + transport). */
+export interface ReportSink {
+    /** PR-opening drift report → `POST /v1/runtime/drift`. */
+    reportDrift(report: DriftReport): Promise<void> | void;
+    /** Confirm served pending routes → rides `/v1/runtime/health`. */
+    confirmServed(confirm: PendingConfirm): Promise<void> | void;
+}
+export interface ReconcileResult {
+    /** Reflected surface matched the declared lock. */
+    inSync: boolean;
+    /** A drift report was sent. */
+    reportedDrift: boolean;
+    /** Route ids confirmed served (pending → clearable). */
+    confirmedRouteIds: string[];
+    /** A report sink call failed (swallowed — boot never blocks on it). */
+    reportError?: string;
+}
+/**
+ * Reconcile the reflected surface against the declared lock at startup.
+ * Idempotent + multi-replica-safe (all replicas compute the same hash; confirm
+ * carries `lockVersion` for the server's optimistic-concurrency check).
+ */
+export declare function reconcileOnStartup(args: {
+    reflected: readonly ReflectedRoute[];
+    bootstrap: StartupBootstrap;
+    report: ReportSink;
+}): Promise<ReconcileResult>;

package/dist/types/reflect/route-canon.d.ts

@@ -0,0 +1,20 @@
+/** A reflected route — method + canonical path. Mirrors contracts ReflectedRoute. */
+export interface ReflectedRoute {
+    method: string;
+    path: string;
+}
+/** Backend → core drift report. Mirrors contracts DriftReport. */
+export interface DriftReport {
+    backendId: string;
+    lockVersion: number;
+    reflectedSurfaceHash: string;
+    routes: ReflectedRoute[];
+}
+/** Backend → core pending confirmation. Mirrors contracts PendingConfirm. */
+export interface PendingConfirm {
+    backendId: string;
+    lockVersion: number;
+    servedRouteIds: string[];
+}
+export declare function normalizePath(path: string): string;
+export declare function surfaceHash(routes: readonly ReflectedRoute[]): string;

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

@@ -0,0 +1,32 @@
+declare const RESPONSE_METERING_ERROR_CODES: {
+    readonly missingToken: "missing_token";
+    readonly invalidMeterKey: "invalid_meter_key";
+    readonly invalidMeterValue: "invalid_meter_value";
+};
+type ResponseMeteringErrorCode = (typeof RESPONSE_METERING_ERROR_CODES)[keyof typeof RESPONSE_METERING_ERROR_CODES];
+export declare const METERING_PAYLOAD_HEADER: "x-fs-metering";
+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 MeteringOptions = {
+    token?: string;
+    env?: Record<string, string | undefined>;
+    measureContext?: Record<string, unknown>;
+    creditUnitsConsumed?: UsageMap;
+};
+export type UsageWrapOptions = {
+    measureContext?: Record<string, unknown>;
+    creditUnitsConsumed?: UsageMap;
+};
+export type UsageReporter = {
+    report(meter: string, value: number): UsageReporter;
+    wrap(response: Response, options?: UsageWrapOptions): Promise<Response>;
+};
+export declare class MeteringError extends Error {
+    readonly code: ResponseMeteringErrorCode;
+    constructor(code: ResponseMeteringErrorCode, message: string);
+}
+export declare function createUsage(request: Request, options?: MeteringOptions): UsageReporter;
+export declare function withUsage(request: Request, response: Response, usage: UsageMap, options?: MeteringOptions): Promise<Response>;
+export {};

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

@@ -5,7 +5,7 @@ export declare const RUNTIME_TOKEN_PREFIXES: {
     readonly test: "fsrt_test_";
 };
 export type RuntimeTokenKind = keyof typeof RUNTIME_TOKEN_PREFIXES;
-export declare const RUNTIME_TOKEN_CAPABILITIES: readonly ["gateway_verification", "metering", "health", "tunnel"];
+export declare const RUNTIME_TOKEN_CAPABILITIES: readonly ["gateway_verification", "metering", "health", "tunnel", "drift_report"];
 export type RuntimeTokenCapability = (typeof RUNTIME_TOKEN_CAPABILITIES)[number];
 export declare const RUNTIME_HEADER_NAMES: {
     readonly signature: "x-fs-signature";
@@ -93,6 +93,14 @@ export type RuntimeRouteDescriptor = {
     method: string;
     path: string;
     backendId: string;
+    /** Declared-but-not-yet-confirmed-served route. `fs.ready()` confirms the ones
+     *  this replica actually serves so core can clear the flag and publish. */
+    pending?: boolean;
+};
+/** The declared route-surface lock the backend reconciles against at startup. */
+export type RuntimeLockDescriptor = {
+    surfaceHash: string;
+    lockVersion: number;
 };
 export type RuntimeBootstrapResponse = {
     product: {
@@ -113,6 +121,9 @@ export type RuntimeBootstrapResponse = {
     metering: RuntimeMeteringConfig;
     transport: RuntimeTransportConfig;
     routes: RuntimeRouteDescriptor[];
+    /** Reflected route-surface lock (surfaceHash + version). Present once core
+     *  serves it; `fs.ready()` diffs the reflected surface against it. */
+    lock?: RuntimeLockDescriptor;
     policyVersion: string;
     refreshAfterSeconds: number;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.1.0",
-  "description": "Farther Shore backend SDK: secure BYO-backend runtime — fail-closed gateway request verification, metering, health, and lifecycle, all derived from FS_RUNTIME_TOKEN",
+  "version": "0.3.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",
   "module": "./dist/index.js",
@@ -15,6 +15,10 @@
       "types": "./dist/types/adapters/express.d.ts",
       "import": "./dist/adapters/express.js"
     },
+    "./reflect": {
+      "types": "./dist/types/reflect/index.d.ts",
+      "import": "./dist/reflect/index.js"
+    },
     "./runtime": {
       "types": "./dist/types/generated/runtime-contract.d.ts",
       "import": "./dist/generated/runtime-contract.js"

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

@@ -1,36 +0,0 @@
-export declare const METERING_CONTRACT_VERSION: 1;
-export declare const METERING_HEADERS: {
-    readonly payload: "x-fs-metering";
-    readonly signature: "x-fs-metering-sig";
-    readonly token: "x-fs-metering-token";
-};
-export declare const METERING_TOKEN_ENV: "FARTHERSHORE_METERING_TOKEN";
-export declare const METERING_TOKEN_CONTRACT: {
-    readonly environmentVariable: "FARTHERSHORE_METERING_TOKEN";
-    readonly presentation: "x-fs-metering-token";
-    readonly storage: "sha256-hash-only";
-};
-export declare const METERING_SIGNATURE_CONTRACT: {
-    readonly algorithm: "HMAC-SHA256";
-    readonly encoding: "base64url";
-    readonly input: "payload-json";
-    readonly secret: "presented-metering-token";
-};
-export declare const METERING_ERROR_CODES: {
-    readonly missingToken: "missing_token";
-    readonly invalidMeterKey: "invalid_meter_key";
-    readonly invalidMeterValue: "invalid_meter_value";
-};
-export type MeteringErrorCode = (typeof METERING_ERROR_CODES)[keyof typeof METERING_ERROR_CODES];
-export declare const METERING_HTTP_ADAPTER_CONTRACT: {
-    readonly input: "Request";
-    readonly output: "Response";
-    readonly networkCalls: false;
-    readonly preserves: readonly ["body", "headers", "status", "statusText"];
-    readonly gatewayStripsInternalHeaders: true;
-};
-export type MeteringUsagePayload = {
-    method: string;
-    path: string;
-    rawDimsUnits: Record<string, number>;
-};

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

@@ -1,20 +0,0 @@
-import { type MeteringErrorCode } from "../generated/metering-contract.js";
-export declare const METERING_PAYLOAD_HEADER: "x-fs-metering";
-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: "FARTHERSHORE_METERING_TOKEN";
-export type UsageMap = Record<string, number>;
-export type MeteringOptions = {
-    token?: string;
-    env?: Record<string, string | undefined>;
-};
-export type UsageReporter = {
-    report(meter: string, value: number): UsageReporter;
-    wrap(response: Response): Promise<Response>;
-};
-export declare class MeteringError extends Error {
-    readonly code: MeteringErrorCode;
-    constructor(code: MeteringErrorCode, message: string);
-}
-export declare function createUsage(request: Request, options?: MeteringOptions): UsageReporter;
-export declare function withUsage(request: Request, response: Response, usage: UsageMap, options?: MeteringOptions): Promise<Response>;