@farthershore/backend 0.2.0 → 0.8.0

package/README.md

@@ -4,6 +4,10 @@ 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.0` (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.
+
 ## Install
 
 ```sh

package/dist/adapters/express.js

@@ -4,11 +4,17 @@ import { createRequire as __createRequire } from "node:module";const require=__c
 var FartherShoreError = class extends Error {
   code;
   status;
-  constructor(code, message, status) {
+  /** Present only when this error is a self-minted plan-limit deny (rare; the
+   *  backend usually relays the gateway's descriptor-bearing deny instead). */
+  limitDescriptor;
+  constructor(code, message, status, limitDescriptor) {
     super(message);
     this.name = "FartherShoreError";
     this.code = code;
     this.status = status ?? statusForCode(code);
+    if (limitDescriptor !== void 0) {
+      this.limitDescriptor = limitDescriptor;
+    }
   }
 };
 function statusForCode(code) {

package/dist/index.js

@@ -1,6 +1,285 @@
 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/generated/runtime-contract.ts
+var RUNTIME_BODY_HASH_CONTRACT = {
+  algorithm: "SHA-256",
+  encoding: "hex-lower",
+  source: "raw-request-bytes",
+  emptyBodyHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  maxBodyBytes: 10485760,
+  streamingExemptToken: "STREAM",
+  streamingExemptContentTypes: [
+    "text/event-stream",
+    "application/octet-stream",
+    "multipart/form-data"
+  ],
+  overMaxStatus: 413
+};
+var RUNTIME_ERROR_CODES = {
+  missingSignature: "missing_signature",
+  malformedSignature: "malformed_signature",
+  unknownKeyId: "unknown_key_id",
+  jwksUnavailable: "jwks_unavailable",
+  badSignature: "bad_signature",
+  bodyHashMismatch: "body_hash_mismatch",
+  routeMismatch: "route_mismatch",
+  clockSkew: "clock_skew",
+  expiredSignature: "expired_signature",
+  replayedNonce: "replayed_nonce",
+  bodyTooLarge: "body_too_large",
+  environmentMismatch: "environment_mismatch",
+  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/runtime-types.ts
+var RUNTIME_ERROR_CODE_TO_ERROR_CODE = {
+  // Credential / token presentation faults → UNAUTHORIZED (401).
+  [RUNTIME_ERROR_CODES.missingToken]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.invalidToken]: "UNAUTHORIZED",
+  // Signature / key faults → UNAUTHORIZED (401, fail-closed verification).
+  [RUNTIME_ERROR_CODES.missingSignature]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.malformedSignature]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.unknownKeyId]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.badSignature]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.expiredSignature]: "UNAUTHORIZED",
+  // Replay / freshness faults → UNAUTHORIZED (401).
+  [RUNTIME_ERROR_CODES.clockSkew]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.replayedNonce]: "UNAUTHORIZED",
+  // Request/route binding faults → UNAUTHORIZED (401, fail-closed).
+  [RUNTIME_ERROR_CODES.bodyHashMismatch]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.routeMismatch]: "UNAUTHORIZED",
+  [RUNTIME_ERROR_CODES.environmentMismatch]: "UNAUTHORIZED",
+  // JWKS fetch unavailable — dependency fault (still 401 to the client), but
+  // the canonical code keeps the "dependency down" semantic for callers.
+  [RUNTIME_ERROR_CODES.jwksUnavailable]: "SERVICE_UNAVAILABLE",
+  // The single non-401 (413) — oversized request body.
+  [RUNTIME_ERROR_CODES.bodyTooLarge]: "VALIDATION_ERROR"
+};
+function runtimeErrorToErrorCode(code) {
+  return RUNTIME_ERROR_CODE_TO_ERROR_CODE[code] ?? "INTERNAL_ERROR";
+}
 var FS_RUNTIME_TOKEN_ENV = "FS_RUNTIME_TOKEN";
 var RUNTIME_TOKEN_PREFIXES = {
   live: "fsrt_live_",
@@ -10,7 +289,13 @@ var RUNTIME_TOKEN_CAPABILITIES = [
   "gateway_verification",
   "metering",
   "health",
-  "tunnel"
+  "tunnel",
+  // Hand-maintained mirror of @farthershore/contracts RUNTIME_TOKEN_CAPABILITIES
+  // (`runtime.ts`). Bound to that source by the SET-EQUALITY + ORDER assertions
+  // in `deny-taxonomy-drift.test.ts` (test-only contracts devDep) — NOT by the
+  // generated runtime-contract.ts, which mirrors only RUNTIME_ERROR_CODES.
+  // `drift_report` is the opt-in capability for reporting route drift.
+  "drift_report"
 ];
 var RUNTIME_HEADER_NAMES = {
   signature: "x-fs-signature",
@@ -117,13 +402,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 = "";
@@ -159,11 +444,17 @@ var runtimeTokenKind2 = runtimeTokenKind;
 var FartherShoreError = class extends Error {
   code;
   status;
-  constructor(code, message, status) {
+  /** Present only when this error is a self-minted plan-limit deny (rare; the
+   *  backend usually relays the gateway's descriptor-bearing deny instead). */
+  limitDescriptor;
+  constructor(code, message, status, limitDescriptor) {
     super(message);
     this.name = "FartherShoreError";
     this.code = code;
     this.status = status ?? statusForCode(code);
+    if (limitDescriptor !== void 0) {
+      this.limitDescriptor = limitDescriptor;
+    }
   }
 };
 function statusForCode(code) {
@@ -345,10 +636,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(
@@ -402,8 +693,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();
@@ -1032,12 +1323,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
     );
   }
@@ -1046,7 +1337,8 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.2.0".length > 0 ? "0.2.0" : "0.0.0-dev";
+var SDK_VERSION = "0.8.0".length > 0 ? "0.8.0" : "0.0.0-dev";
+var CONTRACTS_FP = "af8995b9467842b6".length > 0 ? "af8995b9467842b6" : "0000000000000000";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -1117,6 +1409,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.
@@ -1229,75 +1575,6 @@ function readProcessEnv() {
   return maybeProcess?.env ?? {};
 }
 
-// src/generated/runtime-contract.ts
-var RUNTIME_BODY_HASH_CONTRACT = {
-  algorithm: "SHA-256",
-  encoding: "hex-lower",
-  source: "raw-request-bytes",
-  emptyBodyHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-  maxBodyBytes: 10485760,
-  streamingExemptToken: "STREAM",
-  streamingExemptContentTypes: [
-    "text/event-stream",
-    "application/octet-stream",
-    "multipart/form-data"
-  ],
-  overMaxStatus: 413
-};
-var RUNTIME_ERROR_CODES = {
-  missingSignature: "missing_signature",
-  malformedSignature: "malformed_signature",
-  unknownKeyId: "unknown_key_id",
-  jwksUnavailable: "jwks_unavailable",
-  badSignature: "bad_signature",
-  bodyHashMismatch: "body_hash_mismatch",
-  routeMismatch: "route_mismatch",
-  clockSkew: "clock_skew",
-  expiredSignature: "expired_signature",
-  replayedNonce: "replayed_nonce",
-  bodyTooLarge: "body_too_large",
-  environmentMismatch: "environment_mismatch",
-  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(
   RUNTIME_BODY_HASH_CONTRACT.streamingExemptContentTypes
@@ -1471,12 +1748,12 @@ function resolveToken(options) {
   }
   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" },
@@ -1485,7 +1762,7 @@ async function signPayload(payload, token) {
   );
   const signature = await crypto.subtle.sign(
     "HMAC",
-    key,
+    key2,
     new TextEncoder().encode(payload)
   );
   return base64url(new Uint8Array(signature));
@@ -1529,6 +1806,7 @@ export {
   REDACTED_TOKEN,
   RUNTIME_CLOCK_SKEW_SECONDS,
   RUNTIME_ERROR_CODES,
+  RUNTIME_ERROR_CODE_TO_ERROR_CODE,
   RUNTIME_HEADER_NAMES,
   RUNTIME_REPLAY_WINDOW_SECONDS,
   RUNTIME_TOKEN_CAPABILITIES,
@@ -1545,6 +1823,7 @@ export {
   initFromEnv2 as initFromEnv,
   nodeSpawn,
   reportHealth,
+  runtimeErrorToErrorCode,
   runtimeTokenKind2 as runtimeTokenKind,
   signCanonicalString2 as signCanonicalString,
   statusForCode,

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

@@ -1,12 +1,23 @@
 import type { RuntimeErrorCode } from "../generated/runtime-contract.js";
+import type { LimitDescriptor } from "../runtime-types.js";
 /**
  * A verification / runtime failure with a stable, cross-language `code` and the
  * fail-closed HTTP status the adapter should emit.
+ *
+ * Optionally carries a {@link LimitDescriptor} (`limitDescriptor`) when the
+ * failure is a plan-limit deny the backend chooses to surface itself, so SDKs
+ * can render an upgrade affordance from a backend-minted error. This is OPT-IN
+ * plumbing — the backend normally RELAYS the gateway's deny (which already
+ * carries the descriptor) rather than minting its own, so the field is absent on
+ * every verification/runtime failure. Additive; no behavior change.
  */
 export declare class FartherShoreError extends Error {
     readonly code: RuntimeErrorCode;
     readonly status: number;
-    constructor(code: RuntimeErrorCode, message: string, status?: number);
+    /** Present only when this error is a self-minted plan-limit deny (rare; the
+     *  backend usually relays the gateway's descriptor-bearing deny instead). */
+    readonly limitDescriptor?: LimitDescriptor;
+    constructor(code: RuntimeErrorCode, message: string, status?: number, limitDescriptor?: LimitDescriptor);
 }
 /**
  * Map a runtime error code to its fail-closed HTTP status. Oversized bodies are

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";
@@ -40,6 +41,7 @@ export type FartherShoreInitOptions = {
     instanceId?: string;
 };
 export declare const SDK_VERSION: string;
+export declare const CONTRACTS_FP: string;
 /**
  * The runtime instance. Lazily bootstraps; holds the JWKS client, nonce cache,
  * metering buffer, and shutdown hooks.
@@ -62,6 +64,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/index.d.ts

@@ -13,7 +13,7 @@ export { ShutdownManager, type ShutdownHook } from "./core/shutdown.js";
 export { CloudflaredSupervisor, nodeSpawn, REDACTED_TOKEN, type SpawnFn, type SpawnedTunnelProcess, type CloudflaredSupervisorOptions, type TunnelState, type TunnelStatus, } from "./core/tunnel.js";
 export type { FartherShoreTunnelOptions } from "./core/runtime.js";
 export { createExpressMiddleware, type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type ExpressNext, type MiddlewareOptions, } from "./adapters/express.js";
-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 { 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, RUNTIME_ERROR_CODE_TO_ERROR_CODE, runtimeErrorToErrorCode, type LimitDescriptor, type RuntimeMappedErrorCode, } 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 "./response-metering.js";

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/runtime-types.d.ts

@@ -1,11 +1,60 @@
+import type { RuntimeErrorCode } from "./generated/runtime-contract.js";
 export type { RuntimeErrorCode } from "./generated/runtime-contract.js";
+/**
+ * C-1 — the machine-readable limit descriptor on a limit-deny body. A backend
+ * that surfaces a plan-limit deny carries this so SDKs can render an upgrade
+ * affordance. Structurally identical to the contracts `LimitDescriptor`.
+ */
+export interface LimitDescriptor {
+    /** Stable identifier for the limit hit — a `limitCode` VALUE
+     *  (`quota` | `rate_limit` | `credit` | `resource:<name>`), NOT a wire code. */
+    limitCode: string;
+    /** Metered/resource dimension when known; null otherwise. */
+    dimension: string | null;
+    /** The cap the subscriber is at when known; null otherwise. */
+    currentCapacity: number | null;
+}
+/**
+ * C-1 (BE-1) — the RUNTIME field set of the SDK-local {@link LimitDescriptor}
+ * mirror. `satisfies Record<keyof LimitDescriptor, true>` makes the compiler
+ * reject this if it drifts from the local interface; the drift guard
+ * (`deny-taxonomy-drift.test.ts`) then asserts it deep-equals the canonical
+ * contracts `LIMIT_DESCRIPTOR_FIELDS` at RUNTIME — so a hand-copy that adds or
+ * drops a field fails a test that actually runs. (Contracts-free: this is a
+ * plain local constant, never the published-types path to contracts.) */
+export declare const LIMIT_DESCRIPTOR_FIELDS: {
+    limitCode: true;
+    dimension: true;
+    currentCapacity: 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}).
+ * The full core enum lives in the shared platform contracts; the SDK only needs
+ * the subset its bridge produces. Each is a verbatim core `ErrorCode` string —
+ * the drift guard asserts membership in the canonical enum.
+ */
+export type RuntimeMappedErrorCode = "UNAUTHORIZED" | "SERVICE_UNAVAILABLE" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
+/**
+ * C-2 — map every canonical {@link RuntimeErrorCode} (wire snake_case value) to
+ * the core `ErrorCode` it belongs to. Total over `RuntimeErrorCode` (the
+ * `Record<RuntimeErrorCode, …>` type makes a missing key a compile error). A
+ * faithful copy of contracts' `RUNTIME_ERROR_CODE_TO_ERROR_CODE`.
+ */
+export declare const RUNTIME_ERROR_CODE_TO_ERROR_CODE: Record<RuntimeErrorCode, RuntimeMappedErrorCode>;
+/**
+ * C-2 — translate a runtime code into the canonical core `ErrorCode`. Returns
+ * `INTERNAL_ERROR` for an unrecognized value (defensive; the map is total over
+ * known codes). Mirrors contracts' `runtimeErrorToErrorCode`.
+ */
+export declare function runtimeErrorToErrorCode(code: string): RuntimeMappedErrorCode;
 export declare const FS_RUNTIME_TOKEN_ENV: "FS_RUNTIME_TOKEN";
 export declare const RUNTIME_TOKEN_PREFIXES: {
     readonly live: "fsrt_live_";
     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 +142,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 +170,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,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.2.0",
+  "version": "0.8.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",
@@ -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"