@cliwant/mcp-sam-gov 1.0.0 → 1.2.0

package/src/server.ts

@@ -54,6 +54,9 @@ import * as nih from "./nih.js";
 import * as nsf from "./nsf.js";
 import * as clinicaltrials from "./clinicaltrials.js";
 import * as census from "./census.js";
+import * as censusEconomic from "./census-economic.js";
+import * as fred from "./fred.js";
+import * as gsaPerdiem from "./gsa-perdiem.js";
 import * as fema from "./fema.js";
 import * as fdic from "./fdic.js";
 import * as bls from "./bls.js";
@@ -64,6 +67,7 @@ import * as cms from "./cms.js";
 import * as fac from "./fac.js";
 import * as usitc from "./usitc.js";
 import { fetchAttachmentText } from "./attachments.js";
+import * as keys from "./keys.js";
 import { toToolError, ToolErrorCarrier, errorFromResponse } from "./errors.js";
 import {
   buildMeta,
@@ -77,7 +81,7 @@ import { realpathSync } from "node:fs";
 const SERVER_NAME = "mcp-sam-gov";
 // Kept in lockstep with package.json / manifest.json / server.json.
 // Keep in sync with package.json "version" (asserted at release; see CHANGELOG).
-const SERVER_VERSION = "1.0.0";
+const SERVER_VERSION = "1.2.0";
 
 // ─── Tool input schemas (Zod) ────────────────────────────────────
 
@@ -3381,6 +3385,149 @@ const CensusGeographiesByCoordinatesInput = z
     path: ["latitude"],
   });
 
+// ─── US Census County Business Patterns (CBP) — the FIRST key-required source ──
+const CensusBusinessPatternsInput = z.object({
+  naics: z
+    .string()
+    .regex(/^\d{2,6}$/)
+    .optional()
+    .describe(
+      "A NAICS-2017 code (2–6 digits), e.g. '5415' (Computer Systems Design & Related Services) or '54' (Professional/Scientific/Technical). Omit to aggregate across all sectors. Validated ^\\d{2,6}$.",
+    ),
+  geography: z
+    .enum(["us", "state", "county"])
+    .optional()
+    .describe(
+      "The geography level (default 'us'). 'state' returns one row per state (or a single state when `state` is given); 'county' returns every county in a state and REQUIRES `state`.",
+    ),
+  state: z
+    .string()
+    .regex(/^\d{2}$/)
+    .optional()
+    .describe(
+      "A 2-digit state FIPS code, e.g. '06' (California), '48' (Texas). Optional filter for geography='state'; REQUIRED for geography='county' (the CBP `in=state:` predicate). Validated ^\\d{2}$.",
+    ),
+  year: z
+    .string()
+    .regex(/^\d{4}$/)
+    .optional()
+    .describe(
+      "The CBP data year (default '2022', the latest confirmed vintage). Validated ^\\d{4}$ (it rides in the request path).",
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe(
+      "OPTIONAL client-side top-N cap on the returned rows. CBP has NO server-side pagination, so this slices AFTER the full set is fetched and DISCLOSES the omission (totalAvailable stays the full count). Omit to return every matching row.",
+    ),
+});
+
+// ─── FRED (Federal Reserve Economic Data) — the SECOND key-required source ──
+// ADR-0048. Macro context (GDP/CPI/rates/unemployment/PPI). REQUIRES a free
+// FRED_API_KEY; without it both tools throw an honest config error (the other 112
+// tools stay keyless). The key rides &api_key= ONLY. Missing observations ('.') → null.
+const FredSearchSeriesInput = z.object({
+  query: z
+    .string()
+    .min(1)
+    .describe(
+      "The FRED search_text — free-text terms to discover economic series, e.g. 'unemployment rate', 'CPI', 'GDP', '10-year treasury'. Required.",
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(1000)
+    .optional()
+    .describe("Max series to return (default 25, max 1000). Offset-paginated."),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+});
+
+const FredSeriesObservationsInput = z.object({
+  seriesId: z
+    .string()
+    .regex(/^[A-Za-z0-9._-]+$/)
+    .describe(
+      "A FRED series id, e.g. 'GDP', 'CPIAUCSL' (CPI), 'UNRATE' (unemployment), 'DGS10' (10-yr Treasury), 'PPIACO' (PPI). Discover ids with fred_search_series. Validated ^[A-Za-z0-9._-]+$. Required.",
+    ),
+  startDate: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/)
+    .optional()
+    .describe("Earliest observation date (YYYY-MM-DD). Maps to FRED observation_start."),
+  endDate: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/)
+    .optional()
+    .describe("Latest observation date (YYYY-MM-DD). Maps to FRED observation_end."),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100000)
+    .optional()
+    .describe("Max observations to return (default 100, max 100000). Offset-paginated."),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Row offset for pagination (default 0). Page with _meta.pagination.nextOffset."),
+  sortOrder: z
+    .enum(["asc", "desc"])
+    .optional()
+    .describe("Observation date order: 'asc' (oldest first, FRED default) or 'desc' (newest first)."),
+});
+
+// ─── GSA Federal Travel Per-Diem (api.gsa.gov) — travel-cost lane ──
+// ADR-0050. Lodging + M&IE reimbursement ceilings by city/state OR zip for a year.
+// KEYLESS by default via the shared DEMO_KEY (datagovKey.ts seam); DATA_GOV_API_KEY
+// lifts the rate. EITHER (city+state) OR zip — both/neither ⇒ invalid_input, 0 fetch.
+const GsaPerdiemRatesInput = z
+  .object({
+    city: z
+      .string()
+      .regex(/^[A-Za-z .'\-]{1,60}$/)
+      .optional()
+      .describe(
+        "The city name (e.g. 'Washington', 'San Francisco'). Requires `state`. Validated ^[A-Za-z .'\\-]{1,60}$. Use EITHER (city + state) OR zip — not both.",
+      ),
+    state: z
+      .string()
+      .regex(/^[A-Za-z]{2}$/)
+      .optional()
+      .describe(
+        "The 2-letter state/territory code (e.g. 'DC', 'CA'). Required with `city`. Validated ^[A-Za-z]{2}$.",
+      ),
+    zip: z
+      .string()
+      .regex(/^\d{5}$/)
+      .optional()
+      .describe(
+        "A 5-digit ZIP code (e.g. '20001'). The alternative lookup mode to city+state. Validated ^\\d{5}$. Use EITHER zip OR (city + state) — not both.",
+      ),
+    year: z
+      .string()
+      .regex(/^\d{4}$/)
+      .optional()
+      .describe(
+        "The per-diem fiscal year (default '2025'). Validated ^\\d{4}$ (it rides in the request path).",
+      ),
+  })
+  .describe(
+    "Look up GSA per-diem rates by EITHER (city + state) OR zip. Supplying both, or neither, ⇒ invalid_input.",
+  );
+
+// api_key_status takes no input — it is a pure status query over process.env.
+const ApiKeyStatusInput = z.object({});
+
 // ─── Tool catalog ────────────────────────────────────────────────
 
 type ToolDef = {
@@ -4843,11 +4990,82 @@ export const TOOLS: ToolDef[] = [
     inputSchema: CensusGeographiesByCoordinatesInput,
     handler: (input) => census.geographiesByCoordinates(input),
   }),
+  // ━━━ US Census County Business Patterns — market sizing (1) ━━━ ADR-0047
+  // ★The server's FIRST KEY-REQUIRED source: the Census Data API removed its
+  // keyless tier, so WITHOUT a CENSUS_API_KEY this tool throws an honest
+  // invalid_input config error (the other 111 tools stay keyless). NAICS×geography
+  // establishments / employment / annual payroll — the demand-side market-sizing
+  // lane. Census negative suppression sentinels (-999999999 …) map to null (never
+  // a negative number / never 0). The 2D-array body is parsed by header name.
+  defineTool({
+    name: "census_business_patterns",
+    description:
+      "Market sizing by NAICS × geography — establishments, employment, and annual payroll from the US Census County Business Patterns (CBP) API (api.census.gov/data/{year}/cbp). ★REQUIRES a free CENSUS_API_KEY: the Census Data API has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://api.census.gov/data/key_signup.html; Census and FRED are the only key-required sources — every other tool is keyless). Input: optional `naics` (2–6 digit NAICS-2017, e.g. '5415'; omit to aggregate all sectors), `geography` (us|state|county, default us; county REQUIRES `state`), `state` (2-digit FIPS, e.g. '06'), `year` (default '2022'), optional `limit` (client-side top-N; CBP has no server pagination). Returns { rows:[{ name, geoId, naicsCode, naicsLabel, establishments, employees, annualPayrollUsd, state }] } + honest _meta. HONESTY: establishments/employees are integer counts and annualPayrollUsd is annual US dollars (×1000 from the source's $1,000-unit PAYANN); Census SUPPRESSED/withheld cells (large negative sentinels like -999999999) map to null — NEVER a negative number and NEVER 0 (a genuine 0 stays 0); geoId/naicsCode/state are STRINGS (leading zeros survive). CBP returns the COMPLETE geography set for the filter (no pagination) ⇒ totalAvailable = the row count, complete:true. A missing/invalid key ⇒ invalid_input (a 302 to the Missing-Key page); a header-only body ⇒ honest empty (returned:0); a 5xx ⇒ THROWS; a 200 non-JSON ⇒ schema_drift. The key rides ONLY in the &key= query param — never logged or echoed.",
+    inputSchema: CensusBusinessPatternsInput,
+    handler: (input) => censusEconomic.businessPatterns(input),
+  }),
+  // ━━━ FRED (Federal Reserve Economic Data) — macro context (2) ━━━ ADR-0048
+  // ★The server's SECOND KEY-REQUIRED source: FRED has NO keyless tier, so WITHOUT
+  // a FRED_API_KEY both tools throw an honest invalid_input config error (the other
+  // 112 tools stay keyless). GDP/CPI/rates/unemployment/PPI — the macro backdrop for
+  // bid escalation / market timing. A missing observation ('.') maps to null (never 0).
+  defineTool({
+    name: "fred_search_series",
+    description:
+      "Discover FRED economic series (GDP, CPI, interest rates, unemployment, PPI…) by free-text search (FRED /fred/series/search; api.stlouisfed.org). ★REQUIRES a free FRED_API_KEY: FRED has NO keyless tier, so without the key this tool THROWS an honest config error (get one at https://fred.stlouisfed.org/docs/api/api_key.html; this and fred_series_observations are the key-required macro tools — the other 112 tools stay keyless). Input: `query` (the search_text, required, e.g. 'unemployment rate' / 'CPI' / '10-year treasury'), optional `limit` (default 25, max 1000), `offset`. Returns { series:[{ id, title, frequency, frequencyShort, units, seasonalAdjustment, observationStart, observationEnd, lastUpdated, popularity }] } + honest _meta. Feed `id` into fred_series_observations for the time series. HONESTY: totalAvailable is FRED's EXACT reported `count` (offset pagination via hasMore/nextOffset — never fabricated); every scalar is null-never-empty-string; a genuine no-match ⇒ honest empty (returned:0); a 400 (bad/missing key) ⇒ invalid_input CARRYING FRED's error_message; a 5xx ⇒ THROWS; a 200 non-JSON / non-array `seriess` ⇒ schema_drift. The key rides ONLY in the &api_key= query param — never logged or echoed.",
+    inputSchema: FredSearchSeriesInput,
+    handler: (input) => fred.searchSeries(input),
+  }),
+  defineTool({
+    name: "fred_series_observations",
+    description:
+      "Fetch a FRED series' time series of date/value observations (FRED /fred/series/observations; api.stlouisfed.org). ★REQUIRES a free FRED_API_KEY (FRED has NO keyless tier — without it this tool THROWS an honest config error; get one at https://fred.stlouisfed.org/docs/api/api_key.html). Input: `seriesId` (required, e.g. 'GDP', 'CPIAUCSL', 'UNRATE', 'DGS10', 'PPIACO'; discover with fred_search_series), optional `startDate`/`endDate` (YYYY-MM-DD), `limit` (default 100, max 100000), `offset`, `sortOrder` (asc|desc). Returns { observations:[{ date, value }] } + honest _meta. ★MISSING-VALUE HONESTY (the crux): FRED encodes a missing observation as the literal '.', which maps to value:null (missing) — NEVER 0; a genuine reported 0 is preserved as 0. HONESTY: totalAvailable is FRED's EXACT `count` (offset pagination via hasMore/nextOffset — never fabricated); a 400 (bad seriesId / missing key) ⇒ invalid_input CARRYING FRED's error_message (never a fake empty); a genuine empty ⇒ honest empty; a 5xx ⇒ THROWS; a 200 non-JSON / non-array `observations` ⇒ schema_drift. seriesId is charclass-validated (^[A-Za-z0-9._-]+$) and dates are YYYY-MM-DD; the key rides ONLY in the &api_key= query param.",
+    inputSchema: FredSeriesObservationsInput,
+    handler: (input) => fred.seriesObservations(input),
+  }),
+  // ━━━ GSA Federal Travel Per-Diem (api.gsa.gov) — travel-cost lane (1) ━━━ ADR-0050
+  // The lodging + M&IE reimbursement ceilings the federal government pays for official
+  // travel, by city/state OR zip for a year. SAME host (api.gsa.gov) + SAME api.data.gov
+  // key seam (datagovKey.ts, X-Api-Key header) as datagov_search_datasets — KEYLESS by
+  // default via the shared DEMO_KEY, keylessMode:false. EITHER (city+state) OR zip; both
+  // or neither ⇒ invalid_input, 0 fetch. `value` (monthly lodging) / `meals` are null-
+  // never-0; standardRate/isOconus are STRING booleans coerced to real booleans.
+  defineTool({
+    name: "gsa_perdiem_rates",
+    description:
+      "Look up GSA Federal Travel PER-DIEM rates — the max lodging + Meals & Incidental Expenses (M&IE) reimbursement ceilings for official U.S. government travel (api.gsa.gov /travel/perdiem/v2, keyed — DATA_GOV_API_KEY or the shared DEMO_KEY). Input: EITHER `city` (e.g. 'Washington') + `state` (2-letter, e.g. 'DC') OR `zip` (5-digit) — supplying BOTH, or NEITHER, ⇒ invalid_input with 0 fetch; optional `year` (default '2025'). Returns { rates:[{ city, county, state, zip, year, isOconus, standardRate, mealsUsd, monthlyLodgingUsd:[{ month (1-12), monthName, lodgingUsd }] }] } + honest _meta. HONESTY: lodgingUsd (the API's monthly `value`) is the MAX nightly lodging ceiling for that month — it VARIES SEASONALLY (hence a per-month array), and mealsUsd is the daily M&IE ceiling; both are integer US dollars, null-when-withheld (NEVER 0 — a genuine 0 is preserved). standardRate/isOconus are booleans coerced from the API's string 'true'/'false' (an unrecognized value ⇒ null, never a fabricated false); the months array is preserved AS-IS (never padded to 12). The API returns the COMPLETE rate set (no pagination) ⇒ totalAvailable = the row count, complete:true. A genuine no-match (rates:[]/rate:[]) ⇒ honest empty (returned:0); the API's `errors` field non-null ⇒ invalid_input carrying the message (never a fake empty); a 429 (DEMO_KEY ~10 req/hr, hit quickly) ⇒ rate_limited THROWS; a 5xx/timeout ⇒ upstream_unavailable THROWS; a 200 non-JSON ⇒ schema_drift. DEMO_KEY ~10 req/hr shared ceiling — set DATA_GOV_API_KEY (free at api.data.gov/signup) for 1000/hr. The key rides ONLY in the X-Api-Key header (never the URL/_meta).",
+    inputSchema: GsaPerdiemRatesInput,
+    handler: (input) => gsaPerdiem.perdiemRates(input),
+  }),
+  // ━━━ Self-service key discovery (1) ━━━
+  // KEYLESS. A local status query — reads process.env (+ any .env auto-loaded at
+  // startup) and reports, per key, whether it is set (a BOOLEAN — the key VALUE is
+  // NEVER read into the output). Makes the 2-required + 5-optional key situation
+  // discoverable without reading source or docs.
+  defineTool({
+    name: "api_key_status",
+    description:
+      "List every API key this server can use, whether each is REQUIRED or OPTIONAL, the free signup URL + what it unlocks, and whether it is CURRENTLY configured — a boolean only; the key VALUE is NEVER shown. KEYLESS (no input). Most sources are keyless; only Census (census_business_patterns) and FRED (2 tools) REQUIRE a key (they throw without one), the other 5 keys are OPTIONAL (raise a rate limit or unlock one filter). Keys can be set as host env vars OR in a `.env` file in the server's working directory (auto-loaded at startup; real env wins over .env). Returns { keys:[{ envVar, sources[], required, signupUrl, unlocks, note, currentlySet }], requiredMissing:[envVars], optionalMissing:[envVars], allKeysFree:true }. This tool tells you the CONFIG state; to verify a key actually WORKS, call that source's own tool. Getting a key (creating the account at the signup URL) is your step — the server automates discovery + configuration, not signup.",
+    inputSchema: ApiKeyStatusInput,
+    handler: async () => keys.apiKeyStatus(),
+  }),
 ];
 
 // ─── Server bootstrap ────────────────────────────────────────────
 
 async function main() {
+  // Auto-load API keys from a `.env` in the working directory BEFORE anything
+  // reads process.env (tools read env at call time; SamGovClient below reads
+  // SAM_GOV_API_KEY immediately). Real env wins over .env (precedence); no .env
+  // present ⇒ zero change ⇒ byte-identical startup. We log only the COUNT — never
+  // which keys or their values.
+  const loadedFromEnvFile = keys.loadDotEnv();
+  if (loadedFromEnvFile > 0) {
+    console.error(
+      `[mcp-sam-gov] loaded ${loadedFromEnvFile} key(s) from .env`,
+    );
+  }
+
   const sam = new SamGovClient({
     apiKey: process.env.SAM_GOV_API_KEY?.trim() || undefined,
     logger: {
@@ -4964,6 +5182,8 @@ function synthesizeDefaultMeta(
     source = "gao.gov Legal Products RSS + decision pages (keyless)";
   } else if (toolName.startsWith("fpds_")) {
     source = "www.fpds.gov ezSearch ATOM (FPDS-NG, keyless)";
+  } else if (toolName === "api_key_status") {
+    source = "local (process.env + .env)";
   } else {
     source = "unknown";
   }

package/src/snapshot.ts

@@ -9,12 +9,15 @@
  * egress (an edge/WAF IP-reputation block). This module is that reader; it slots
  * into the Phase-1 `throughPathChain` as a LOWER-priority `ResiliencePath`.
  *
- * ★INERT BY DEFAULT (the pass/fail bar): the snapshot base URL comes from the
- * env var `SAMGOV_SNAPSHOT_BASE_URL`, which is UNSET by default. When unset,
- * `snapshotPath()` returns `null` — the path is simply NOT added to a source's
- * chain, so every source stays single-path (live-only) and its output is
- * byte-identical to today. A snapshot fallback exists ONLY when an operator
- * explicitly configures a base URL.
+ * ★DEFAULT-ON (resilience active out of the box): the snapshot base URL comes
+ * from the env var `SAMGOV_SNAPSHOT_BASE_URL`. When it is UNSET, the reader now
+ * resolves to `DEFAULT_SNAPSHOT_BASE_URL` — the public, weekly-refreshed GitHub
+ * mirror — so every user gets offline fallback with zero configuration. An
+ * operator can point at their own mirror (any custom URL) or DISABLE the
+ * fallback entirely (pure live-only) with a disable sentinel
+ * (`SAMGOV_SNAPSHOT_BASE_URL=off`); when disabled, `snapshotPath()` returns
+ * `null` — the path is simply NOT added to a source's chain, so every source
+ * stays single-path (live-only) and its output is byte-identical to today.
  *
  * ★POLICY BOUNDARY (ADR-0045 §"정책 경계", invariant — mirrors datasource.ts):
  *   • PUBLIC-ONLY (M3/m2): the builder writes ONLY public + redistributable data
@@ -52,27 +55,54 @@ export type SnapshotEnvelope<T = unknown> = {
 /** Env-driven resilience config. Read at CALL TIME so it is togglable per call. */
 export type ResilienceConfig = {
   /**
-   * The snapshot mirror base URL (no trailing slash), or `undefined` when the
-   * env var is unset/blank ⇒ snapshot DISABLED ⇒ every source stays live-only.
+   * The snapshot mirror base URL (no trailing slash) — the hosted default when
+   * the env var is unset, a custom mirror when set to a URL, or `undefined` when
+   * DISABLED via a sentinel (`off`) ⇒ every source stays live-only.
    */
   snapshotBaseUrl: string | undefined;
 };
 
+/**
+ * The public, weekly-refreshed snapshot mirror (see .github/workflows/snapshots.yml);
+ * read-only public reference data. This is the DEFAULT base URL when
+ * `SAMGOV_SNAPSHOT_BASE_URL` is unset. Disable the fallback with
+ * `SAMGOV_SNAPSHOT_BASE_URL=off`.
+ */
+export const DEFAULT_SNAPSHOT_BASE_URL =
+  "https://raw.githubusercontent.com/cliwant/mcp-sam-gov/snapshots";
+
+/** Case-insensitive disable sentinels: any of these (or a blank value) means
+ *  "snapshot DISABLED = live-only", resolving to `undefined`. */
+const SNAPSHOT_DISABLE_SENTINELS = new Set([
+  "off",
+  "none",
+  "false",
+  "0",
+  "disabled",
+]);
+
 /**
  * Resolve `SAMGOV_SNAPSHOT_BASE_URL` at CALL TIME (never cached at module load,
  * so a test — or an operator flipping the env — takes effect immediately, and so
- * importing this module has zero config side effects). Returns `undefined` when
- * the var is unset or blank (the INERT default: snapshot disabled). A trailing
- * slash is stripped so `${base}/${key}.json` is well-formed.
+ * importing this module has zero config side effects). The resolution is
+ * DEFAULT-ON:
+ *   • env UNSET ⇒ `DEFAULT_SNAPSHOT_BASE_URL` (resilience ON by default).
+ *   • env is a DISABLE sentinel — case-insensitive one of `off` / `none` /
+ *     `false` / `0` / `disabled`, OR blank after trim ⇒ `undefined` (snapshot
+ *     disabled = live-only, byte-identical to pre-ADR output).
+ *   • any other value ⇒ that custom mirror URL, trailing slash stripped so
+ *     `${base}/${key}.json` is well-formed.
  */
 export function resolveSnapshotBaseUrl(): string | undefined {
   const raw = process.env.SAMGOV_SNAPSHOT_BASE_URL;
-  if (raw === undefined) return undefined;
-  const trimmed = raw.trim().replace(/\/+$/, "");
-  return trimmed.length > 0 ? trimmed : undefined;
+  if (raw === undefined) return DEFAULT_SNAPSHOT_BASE_URL;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return undefined;
+  if (SNAPSHOT_DISABLE_SENTINELS.has(trimmed.toLowerCase())) return undefined;
+  return trimmed.replace(/\/+$/, "");
 }
 
-/** The env-driven resilience config (default = snapshot disabled). */
+/** The env-driven resilience config (default = hosted snapshot mirror ON). */
 export function resilienceConfig(): ResilienceConfig {
   return { snapshotBaseUrl: resolveSnapshotBaseUrl() };
 }
@@ -139,7 +169,7 @@ function parseSnapshotEnvelope<T>(
 
 /**
  * Build a `ResiliencePath` that reads the snapshot for `key` — or `null` when
- * the snapshot mirror is not configured (the INERT default).
+ * the snapshot mirror is DISABLED (`SAMGOV_SNAPSHOT_BASE_URL=off`).
  *
  * When configured, the path fetches `${base}/${key}.json` via the shipped
  * `getJson` with `redirect:"error"` (off-host redirect ⇒ TypeError ⇒ honest
@@ -149,16 +179,17 @@ function parseSnapshotEnvelope<T>(
  * `throughPathChain` reads `path.provenance` AFTER awaiting `run()`, so the
  * per-fetch `asOf` is captured (mirrors the `{body,provenance}` contract).
  *
- * ★A NULL return is how INERTness is achieved structurally: the Treasury pilot
- * builds `[livePath, snapshotPath(key)].filter(Boolean)`, so when this returns
- * null the chain is single-entry (live only) ⇒ `throughPathChain` fast-paths ⇒
+ * ★A NULL return is how the DISABLED (live-only) path stays byte-identical
+ * structurally: the Treasury pilot builds
+ * `[livePath, snapshotPath(key)].filter(Boolean)`, so when this returns null the
+ * chain is single-entry (live only) ⇒ `throughPathChain` fast-paths ⇒
  * byte-identical to today.
  */
 export function snapshotPath<T = unknown>(
   key: string,
 ): ResiliencePath<T> | null {
   const base = resolveSnapshotBaseUrl();
-  if (base === undefined) return null; // INERT: snapshot disabled ⇒ no path.
+  if (base === undefined) return null; // DISABLED (live-only) ⇒ no path.
   if (!SNAPSHOT_KEY_RE.test(key)) {
     // A bad key is a programming error, not a runtime data condition — refuse to
     // construct a path rather than build a URL that could traverse.