@cliwant/mcp-sam-gov 1.0.0 → 1.2.0

package/dist/snapshot.d.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
@@ -49,20 +52,33 @@ 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 declare const DEFAULT_SNAPSHOT_BASE_URL = "https://raw.githubusercontent.com/cliwant/mcp-sam-gov/snapshots";
 /**
  * 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 declare function resolveSnapshotBaseUrl(): string | undefined;
-/** The env-driven resilience config (default = snapshot disabled). */
+/** The env-driven resilience config (default = hosted snapshot mirror ON). */
 export declare function resilienceConfig(): ResilienceConfig;
 /**
  * P5 provenance → `_meta` partial (ADR-0045 B2/M1). The SHARED threading helper
@@ -79,7 +95,7 @@ export declare function resilienceConfig(): ResilienceConfig;
 export declare function provenanceMeta(provenance: Provenance | undefined): Partial<ResponseMeta>;
 /**
  * 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
@@ -89,9 +105,10 @@ export declare function provenanceMeta(provenance: Provenance | undefined): Part
  * `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 declare function snapshotPath<T = unknown>(key: string): ResiliencePath<T> | null;

package/dist/snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAuB,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI;IAC1C,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,IAAI,EAAE,CAAC,CAAC;CACT,CAAC;AAEF,mFAAmF;AACnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;OAGG;IACH,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,GAAG,SAAS,CAK3D;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,IAAI,gBAAgB,CAEnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,UAAU,GAAG,SAAS,GACjC,OAAO,CAAC,YAAY,CAAC,CAKvB;AAyCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EACtC,GAAG,EAAE,MAAM,GACV,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAiC1B"}
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAuB,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI;IAC1C,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,IAAI,EAAE,CAAC,CAAC;CACT,CAAC;AAEF,mFAAmF;AACnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,oEAC6B,CAAC;AAYpE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,GAAG,SAAS,CAO3D;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,IAAI,gBAAgB,CAEnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,UAAU,GAAG,SAAS,GACjC,OAAO,CAAC,YAAY,CAAC,CAKvB;AAyCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EACtC,GAAG,EAAE,MAAM,GACV,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAiC1B"}

package/dist/snapshot.js

@@ -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
@@ -28,21 +31,46 @@
  *     note + gates `complete` off. A snapshot body can NEVER be labelled live.
  */
 import { getJson, driftError } from "./datasource.js";
+/**
+ * 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() {
     const raw = process.env.SAMGOV_SNAPSHOT_BASE_URL;
     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;
-    const trimmed = raw.trim().replace(/\/+$/, "");
-    return trimmed.length > 0 ? trimmed : 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() {
     return { snapshotBaseUrl: resolveSnapshotBaseUrl() };
 }
@@ -96,7 +124,7 @@ function parseSnapshotEnvelope(raw, label) {
 }
 /**
  * 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
@@ -106,15 +134,16 @@ function parseSnapshotEnvelope(raw, label) {
  * `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(key) {
     const base = resolveSnapshotBaseUrl();
     if (base === undefined)
-        return null; // INERT: snapshot disabled ⇒ no path.
+        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.

package/dist/snapshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAwC,MAAM,iBAAiB,CAAC;AA8B5F;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC;IACjD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC/C,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB;IAC9B,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,UAAkC;IAElC,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,QAAQ,KAAK,MAAM;QAAE,OAAO,EAAE,CAAC;IAC7D,MAAM,IAAI,GAA0B,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC;IACtE,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;IAC/D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;sEACsE;AACtE,MAAM,eAAe,GAAG,cAAc,CAAC;AAEvC;;;;;;GAMG;AACH,SAAS,qBAAqB,CAC5B,GAAY,EACZ,KAAa;IAEb,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,UAAU,CAAC,KAAK,EAAE,YAAY,KAAK,wBAAwB,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,GAAG,GAAG,GAAmC,CAAC;IAChD,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,MAAM,UAAU,CACd,KAAK,EACL,YAAY,KAAK,8EAA8E,CAChG,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,UAAU,CAAC,KAAK,EAAE,YAAY,KAAK,qBAAqB,CAAC,CAAC;IAClE,CAAC;IACD,4EAA4E;IAC5E,gFAAgF;IAChF,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,GAAG,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;QAClE,MAAM,UAAU,CACd,KAAK,EACL,YAAY,KAAK,mBAAmB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,0DAA0D,CAC9H,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAS,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAC1B,GAAW;IAEX,MAAM,IAAI,GAAG,sBAAsB,EAAE,CAAC;IACtC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,CAAC,sCAAsC;IAC3E,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,6EAA6E;QAC7E,gEAAgE;QAChE,MAAM,UAAU,CACd,YAAY,GAAG,EAAE,EACjB,wBAAwB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,gBAAgB,eAAe,IAAI,CAC/E,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,GAAG,OAAO,CAAC;IAClC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1B,MAAM,KAAK,GAAG,YAAY,IAAI,EAAE,CAAC;IACjC,4EAA4E;IAC5E,0EAA0E;IAC1E,MAAM,UAAU,GAAe,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;IACxD,OAAO;QACL,IAAI;QACJ,UAAU;QACV,GAAG,EAAE,KAAK,IAAI,EAAE;YACd,qEAAqE;YACrE,iDAAiD;YACjD,IAAI,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;gBAC/B,MAAM,UAAU,CAAC,KAAK,EAAE,kCAAkC,IAAI,GAAG,CAAC,CAAC;YACrE,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAU,GAAG,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;YACtE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,qBAAqB,CAAI,GAAG,EAAE,KAAK,CAAC,CAAC;YAC5D,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cliwant/mcp-sam-gov",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "mcpName": "io.github.cliwant/mcp-sam-gov",
   "description": "Most comprehensive keyless MCP server for US federal contracting + spending + regulation: SAM.gov, USAspending, Federal Register, eCFR, Grants.gov. 52 tools, no API key, plug into Claude Desktop / Claude Code / Codex CLI / Cursor / Continue / Gemini CLI.",
   "keywords": [

package/src/census-economic.ts

@@ -0,0 +1,425 @@
+/**
+ * US Census — County Business Patterns (CBP) — the MARKET-SIZING lane
+ * (ADR-0047, Wave-4 source #1). NAICS × geography establishments / employment /
+ * annual payroll — the demand-side complement to BLS-QCEW + USAspending in the
+ * B2G market-sizing set.
+ *
+ * ★ THIS IS THE SERVER'S FIRST KEY-REQUIRED SOURCE. The Census Data API removed
+ *   its keyless tier — a request WITHOUT a key is 302-redirected to a "Missing
+ *   Key" HTML page. So, honestly: with NO `CENSUS_API_KEY` this tool THROWS an
+ *   `invalid_input` config error BEFORE any fetch (never a fake-empty, never a
+ *   keyless-pretend). The other 111 tools stay keyless — this key is scoped to
+ *   this one source. (Contrast the OPTIONAL keys of datagov/bls/nvd, which lift a
+ *   tier but are not required.)
+ *
+ * DIFFERENT HOST than census.ts (the geocoder, geocoding.geo.census.gov): the
+ * DATA API is `api.census.gov/data/{year}/cbp`. This module COPIES (does NOT
+ * import) the census.ts fixed-host SSRF idiom (a single host const + a
+ * post-construction `new URL().hostname` assertion + `redirect:"error"`) and does
+ * NOT touch census_geocode.
+ *
+ * Coercion/meta code is REUSED (`driftError`, `errorFromResponse`, `num`
+ * coerce.ts null-never-0, `withMeta`/`buildMeta`). The ONE bespoke bit is the
+ * fetch: a single `fetch(redirect:"manual")` (NOT the shared getJson) so a
+ * missing/invalid-key 302 surfaces as an INSPECTABLE opaque-redirect → honest
+ * invalid_input, instead of undici's redirect:"error" TypeError that
+ * fetchWithRetry would mask as a retryable outage (see the fetch block). The
+ * optional-key leak discipline is MIRRORED from datagovKey.ts/bls.ts — but here
+ * the key is REQUIRED and rides ONLY in the `&key=` query param, NOWHERE else
+ * (never the label, `_meta.source`, notes, or a log — the K-test).
+ *
+ *   GET https://api.census.gov/data/{year}/cbp
+ *       ?get=NAME,NAICS2017_LABEL,ESTAB,EMP,PAYANN,GEO_ID
+ *       &for=<geoClause>            (us:* | state:* | state:NN | county:*)
+ *       &in=state:NN                (county queries only)
+ *       &NAICS2017=<naics>          (optional NAICS filter)
+ *       &key=<CENSUS_API_KEY>       (REQUIRED)
+ *   → a 2D JSON ARRAY: row 0 = column headers, rows 1..N = data. e.g.
+ *     [["NAME","ESTAB","EMP","PAYANN","NAICS2017","NAICS2017_LABEL","state"],
+ *      ["California","39755","...","...","5415","...","06"], ...]
+ *
+ * ★ HONESTY (ADR-0047 P1–P5):
+ *   [KEY]  no key ⇒ invalid_input THROW pre-fetch (0 fetch); the message names
+ *          CENSUS_API_KEY + the free-signup URL. A wire 302 (a key that IS set but is
+ *          invalid → the Missing-Key page) is caught via redirect:"manual" as an
+ *          opaque-redirect ⇒ invalid_input "check CENSUS_API_KEY" (never a
+ *          fake-empty, never a masked outage).
+ *   [P1]   CBP returns the COMPLETE geography set for the filter (no server
+ *          pagination) ⇒ totalAvailable = the row count, complete:true. NEVER
+ *          fabricated (RED if totalAvailable = header-length or invented).
+ *   [P3]   ★the sentinel→null crux: Census suppresses/withholds cells with large
+ *          NEGATIVE sentinels (-999999999 / -888888888 / -666666666 …). `censusNum`
+ *          maps any value ≤ -100000000 to **null** (withheld) — NEVER a negative
+ *          number, NEVER 0. A genuine 0 stays 0. `annualPayrollUsd = PAYANN×1000`
+ *          (PAYANN is in $1,000 units), null-preserving.
+ *   [P2]   a 302 ⇒ invalid_input (key); a header-only body ⇒ honest empty
+ *          (returned:0, complete:true); a 5xx ⇒ upstream_unavailable THROW; a 200
+ *          non-JSON ⇒ schema_drift.
+ *   [P4]   a body that is not an array, or whose row 0 is not a string[] header
+ *          row ⇒ driftError (never a fabricated empty).
+ *   [SSRF] fixed host; `year` re-guarded ^\d{4}$ (it rides in the PATH); `naics`
+ *          ^\d{2,6}$; `state` ^\d{2}$; geography enum {us,state,county}. All
+ *          predicate VALUES ride in URLSearchParams. The key rides `&key=` ONLY.
+ */
+
+import { ToolErrorCarrier, errorFromResponse } from "./errors.js";
+import { driftError } from "./datasource.js";
+import { num, str } from "./coerce.js";
+import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
+
+// Re-export the shared honesty coercion (single audited copy in ./coerce.js —
+// ADR-0005 v2 FIX-C) so a num regression fails together across sources. NO local
+// num/str.
+export { num };
+
+// ─── SSRF core: the single fixed host (DIFFERENT from census.ts) ──
+const CENSUS_DATA_HOST = "api.census.gov";
+const CENSUS_DATA_LABEL = "census:/data/cbp"; // host-only ToolError surface; NO token, NO key
+
+// ─── Validation charclasses (SSRF + "verify the input" honesty) ───
+const YEAR_RE = /^\d{4}$/; // rides in the PATH — strict 4-digit (no path injection)
+const NAICS_RE = /^\d{2,6}$/; // 2–6 digit NAICS-2017 sector/code
+const STATE_FIPS_RE = /^\d{2}$/; // 2-digit state FIPS
+const GEOGRAPHIES = new Set(["us", "state", "county"]);
+
+// The Census suppression/withhold sentinel floor. Census encodes a suppressed or
+// unavailable cell as a large NEGATIVE value (-999999999 / -888888888 /
+// -666666666 …). Establishment/employment/payroll counts are non-negative, so any
+// value at/below this floor is a sentinel, NOT data.
+const CENSUS_SENTINEL_FLOOR = -100000000;
+
+const DEFAULT_YEAR = "2022"; // the latest confirmed CBP vintage (ADR-0047)
+
+// ─── Honesty notes (ADR-0047 required set) ────────────────────────
+const KEY_REQUIRED_NOTE =
+  "This source REQUIRES a free CENSUS_API_KEY (the Census Data API has no keyless tier). The key is sent ONLY as the &key= query parameter to api.census.gov and is NEVER logged, echoed, or placed in this response.";
+const PAYROLL_UNITS_NOTE =
+  "annualPayrollUsd is ANNUAL payroll in US dollars, converted from the Census PAYANN field's $1,000 units (×1000). establishments and employees are integer counts (as-of the reference year).";
+const SUPPRESSED_NOTE =
+  "Census suppresses cells for confidentiality/reliability using large negative sentinels (e.g. -999999999); such values are mapped to null (withheld) — NEVER a negative number and NEVER 0. A genuine 0 is preserved as 0.";
+const NO_PAGINATION_NOTE =
+  "CBP returns the COMPLETE set of geographies matching the filter (no server-side pagination); totalAvailable equals the number of rows returned. Narrow with naics / geography to reduce the row count.";
+
+// ─── The key seam (REQUIRED; value NEVER leaked past the &key= param) ──
+/** Read CENSUS_API_KEY from env; trim; return the value or undefined (unset/blank). */
+export function censusApiKey(): string | undefined {
+  const raw = process.env.CENSUS_API_KEY;
+  const trimmed = typeof raw === "string" ? raw.trim() : "";
+  return trimmed ? trimmed : undefined;
+}
+
+// ─── Curated row shape ────────────────────────────────────────────
+export type CbpRow = {
+  name: string | null; // the geography NAME (e.g. "California")
+  geoId: string | null; // GEO_ID (a STRING — leading zeros survive)
+  naicsCode: string | null; // NAICS2017 (a STRING — sector codes carry structure)
+  naicsLabel: string | null; // NAICS2017_LABEL
+  establishments: number | null; // ESTAB — null when suppressed (NEVER negative/0-lie)
+  employees: number | null; // EMP — null when suppressed
+  annualPayrollUsd: number | null; // PAYANN×1000 — null when suppressed
+  state: string | null; // state FIPS (a STRING — leading zeros survive)
+};
+
+/** num(), but map the Census negative suppression sentinel family → null (withheld). */
+function censusNum(v: unknown): number | null {
+  const n = num(v);
+  if (n === null) return null;
+  // A large-negative sentinel is a WITHHELD/suppressed cell, never data. A genuine
+  // 0 (n > floor) passes through as 0.
+  if (n <= CENSUS_SENTINEL_FLOOR) return null;
+  return n;
+}
+
+/** Annual payroll: PAYANN is in $1,000 units → ×1000; null-preserving. */
+function mul1000(n: number | null): number | null {
+  return n === null ? null : n * 1000;
+}
+
+export type CensusBusinessPatternsArgs = {
+  naics?: string;
+  geography?: string; // us | state | county (default us)
+  state?: string; // 2-digit FIPS (required for county; optional filter for state)
+  year?: string; // ^\d{4}$ (default 2022)
+  limit?: number; // OPTIONAL client-side top-N slice (CBP has no server pagination)
+};
+
+/**
+ * Fetch County Business Patterns rows for a NAICS × geography filter → normalized
+ * establishment / employment / annual-payroll rows + honest `_meta`. REQUIRES
+ * CENSUS_API_KEY (throws invalid_input pre-fetch when unset). The 2D-array body is
+ * parsed by HEADER NAME (order-independent); suppressed cells map to null.
+ */
+export async function businessPatterns(
+  args: CensusBusinessPatternsArgs,
+): Promise<MetaBundle> {
+  // ── [KEY] REQUIRED key — throw an honest config error BEFORE any fetch. ──
+  const key = censusApiKey();
+  if (key === undefined) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message:
+        "Census Data API requires a free key. Get one at https://api.census.gov/data/key_signup.html and set CENSUS_API_KEY.",
+      upstreamEndpoint: CENSUS_DATA_LABEL,
+    });
+  }
+
+  // ── Validate + default the inputs (belt-and-suspenders behind the server Zod;
+  //    a DIRECT handler call bypasses Zod). ──
+  const year = args.year ?? DEFAULT_YEAR;
+  if (!YEAR_RE.test(year)) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `Invalid year ${JSON.stringify(year)} — expected a 4-digit year (^\\d{4}$), e.g. "2022". (year rides in the request PATH; it is strictly validated.)`,
+      upstreamEndpoint: CENSUS_DATA_LABEL,
+    });
+  }
+
+  const geography = args.geography ?? "us";
+  if (!GEOGRAPHIES.has(geography)) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `Invalid geography ${JSON.stringify(geography)} — expected one of us, state, county.`,
+      upstreamEndpoint: CENSUS_DATA_LABEL,
+    });
+  }
+
+  if (args.state !== undefined && !STATE_FIPS_RE.test(args.state)) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `Invalid state ${JSON.stringify(args.state)} — expected a 2-digit state FIPS code (^\\d{2}$), e.g. "06" (California).`,
+      upstreamEndpoint: CENSUS_DATA_LABEL,
+    });
+  }
+
+  if (args.naics !== undefined && !NAICS_RE.test(args.naics)) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `Invalid naics ${JSON.stringify(args.naics)} — expected a 2–6 digit NAICS-2017 code (^\\d{2,6}$), e.g. "5415" (Computer Systems Design).`,
+      upstreamEndpoint: CENSUS_DATA_LABEL,
+    });
+  }
+
+  // ── Resolve the geography clause (for=… [+ in=state:…]). ──
+  let forClause: string;
+  let inClause: string | undefined;
+  let geoFilter: string;
+  if (geography === "us") {
+    forClause = "us:*";
+    geoFilter = "geography:us";
+  } else if (geography === "state") {
+    forClause = args.state !== undefined ? `state:${args.state}` : "state:*";
+    geoFilter = `geography:state:${args.state ?? "*"}`;
+  } else {
+    // county — requires a state (the CBP `in=state:` predicate is mandatory).
+    if (args.state === undefined) {
+      throw new ToolErrorCarrier({
+        kind: "invalid_input",
+        retryable: false,
+        message:
+          "geography 'county' requires `state` (a 2-digit FIPS) — CBP county queries need an `in=state:NN` predicate. Pass state, e.g. state:'06'.",
+        upstreamEndpoint: CENSUS_DATA_LABEL,
+      });
+    }
+    forClause = "county:*";
+    inClause = `state:${args.state}`;
+    geoFilter = `geography:county:* in state:${args.state}`;
+  }
+
+  // ── Build the query (all VALUES via URLSearchParams — no host/path steer; the
+  //    REQUIRED key rides ONLY here in &key=). ──
+  const params = new URLSearchParams();
+  params.set("get", "NAME,NAICS2017_LABEL,ESTAB,EMP,PAYANN,GEO_ID");
+  params.set("for", forClause);
+  if (inClause !== undefined) params.set("in", inClause);
+  if (args.naics !== undefined) params.set("NAICS2017", args.naics);
+  params.set("key", key);
+
+  const url = `https://${CENSUS_DATA_HOST}/data/${year}/cbp?${params.toString()}`;
+  // Belt-and-suspenders: the fixed host + strictly-validated path leave nothing to
+  // steer the authority; assert the built URL cannot have been moved off-host.
+  const built = new URL(url);
+  if (built.hostname !== CENSUS_DATA_HOST || built.protocol !== "https:") {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `Constructed Census Data URL host ${JSON.stringify(built.hostname)} (${built.protocol}) is not ${CENSUS_DATA_HOST} over https — refusing to fetch (SSRF safety).`,
+      upstreamEndpoint: CENSUS_DATA_LABEL,
+    });
+  }
+
+  // ── Fetch with redirect:"manual" — the KEY-ERROR DETECTION crux. A missing or
+  //    invalid key makes the Census Data API 302-redirect to its "Missing Key" page
+  //    (live-verified: `HTTP 302` + `Location: /data/missing_key.html` +
+  //    `X-DataWebAPI-KeyError: 1`). We must NOT use redirect:"error" via getJson
+  //    here: undici rejects an "error"-mode redirect with a TypeError that the
+  //    shared fetchWithRetry catch reclassifies to a *retryable upstream_unavailable*
+  //    — masking a key-config error as a transient outage. redirect:"manual" instead
+  //    yields an INSPECTABLE opaque-redirect (type "opaqueredirect", status 0), so
+  //    the missing/invalid key surfaces as an honest invalid_input. This is a
+  //    SINGLE classified attempt (no auto-retry): a transient 5xx THROWS
+  //    upstream_unavailable — re-invoke the tool to retry. The 5xx/404/400 taxonomy
+  //    is delegated to the shared errors.ts `errorFromResponse`; a 200 non-JSON body
+  //    ⇒ r.json() SyntaxError ⇒ schema_drift. The redirect is NEVER followed, so no
+  //    off-host hop can occur (a stronger SSRF posture than redirect:"error"). ──
+  let res: Response;
+  try {
+    res = await fetch(built.toString(), {
+      redirect: "manual",
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (e) {
+    // Timeout/abort ⇒ non-retryable (the same aborted signal would re-reject);
+    // a genuine network TypeError ⇒ retryable upstream_unavailable. NEVER empty.
+    if (
+      e instanceof Error &&
+      (e.name === "TimeoutError" || e.name === "AbortError")
+    ) {
+      throw new ToolErrorCarrier({
+        kind: "upstream_unavailable",
+        message: `Request to ${CENSUS_DATA_LABEL} timed out.`,
+        retryable: false,
+        upstreamEndpoint: CENSUS_DATA_LABEL,
+      });
+    }
+    throw new ToolErrorCarrier({
+      kind: "upstream_unavailable",
+      message: `Network error reaching ${CENSUS_DATA_LABEL}: ${e instanceof Error ? e.message : String(e)}`,
+      retryable: true,
+      retryAfterSeconds: 30,
+      upstreamEndpoint: CENSUS_DATA_LABEL,
+    });
+  }
+
+  // [KEY] A redirect (opaque-redirect via redirect:"manual", or a raw 3xx status) ⇒
+  // the missing/invalid-key "Missing Key" page ⇒ an honest key-config error, NEVER
+  // a fake-empty (swallowing this as empty ⇒ RED in the fault suite).
+  if (res.type === "opaqueredirect" || (res.status >= 300 && res.status < 400)) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message:
+        "Census Data API redirected the request to its 'Missing Key' page — CENSUS_API_KEY is missing or invalid. Get or check a free key at https://api.census.gov/data/key_signup.html.",
+      upstreamEndpoint: CENSUS_DATA_LABEL,
+    });
+  }
+
+  // [P2] 404/429/5xx/4xx ⇒ the shared errors.ts taxonomy (a DOWN service is NEVER
+  // an empty result; 400 → invalid_input, 5xx → upstream_unavailable, …).
+  if (!res.ok) {
+    throw new ToolErrorCarrier(errorFromResponse(res, CENSUS_DATA_LABEL));
+  }
+
+  // [P4] 200 ⇒ parse JSON; a non-JSON body (an HTML error page at 200) makes
+  // r.json() throw a SyntaxError ⇒ schema_drift (never read as an empty result).
+  let body: unknown;
+  try {
+    body = await res.json();
+  } catch (e) {
+    if (e instanceof SyntaxError) {
+      throw driftError(
+        CENSUS_DATA_LABEL,
+        "Census CBP returned a non-JSON body at HTTP 200 (likely an HTML 'Missing Key' / error page) — treating as schema drift (never read as an empty result).",
+      );
+    }
+    throw e;
+  }
+
+  // ── [P4] Parse the 2D array: row 0 = string[] header, rows 1..N = data. ──
+  if (!Array.isArray(body) || body.length === 0) {
+    throw driftError(
+      CENSUS_DATA_LABEL,
+      "Census CBP returned a body that is not a non-empty 2D array — treating as schema drift (never a fabricated empty).",
+    );
+  }
+  const header = body[0];
+  if (
+    !Array.isArray(header) ||
+    header.length === 0 ||
+    !header.every((h) => typeof h === "string")
+  ) {
+    throw driftError(
+      CENSUS_DATA_LABEL,
+      "Census CBP row 0 is not a string[] header row — treating as schema drift (the 2D-array contract changed; never a fabricated empty).",
+    );
+  }
+
+  // Header-name → column index (order-independent; a missing column ⇒ index -1 ⇒
+  // the field maps to null, never a positional mis-read).
+  const idx = new Map<string, number>();
+  (header as string[]).forEach((h, i) => idx.set(h, i));
+  const col = (row: unknown[], name: string): unknown => {
+    const i = idx.get(name);
+    return i === undefined || i < 0 ? undefined : row[i];
+  };
+
+  const allRows: CbpRow[] = [];
+  for (let i = 1; i < body.length; i++) {
+    const raw = body[i];
+    if (!Array.isArray(raw)) {
+      throw driftError(
+        CENSUS_DATA_LABEL,
+        `Census CBP data row ${i} is not an array — treating as schema drift (never a fabricated empty).`,
+      );
+    }
+    const row = raw as unknown[];
+    allRows.push({
+      name: str(col(row, "NAME")),
+      geoId: str(col(row, "GEO_ID")),
+      naicsCode: str(col(row, "NAICS2017")),
+      naicsLabel: str(col(row, "NAICS2017_LABEL")),
+      establishments: censusNum(col(row, "ESTAB")),
+      employees: censusNum(col(row, "EMP")),
+      annualPayrollUsd: mul1000(censusNum(col(row, "PAYANN"))),
+      state: str(col(row, "state")),
+    });
+  }
+
+  // ── [P1] The COMPLETE set for the filter (no server pagination). An OPTIONAL
+  //    client-side top-N slice is disclosed (totalAvailable stays the full count,
+  //    so buildMeta derives truncated/complete honestly). ──
+  const totalAvailable = allRows.length;
+  const notes: string[] = [
+    KEY_REQUIRED_NOTE,
+    PAYROLL_UNITS_NOTE,
+    SUPPRESSED_NOTE,
+    NO_PAGINATION_NOTE,
+  ];
+
+  let rows = allRows;
+  if (
+    typeof args.limit === "number" &&
+    Number.isFinite(args.limit) &&
+    args.limit >= 0 &&
+    args.limit < allRows.length
+  ) {
+    rows = allRows.slice(0, args.limit);
+    notes.push(
+      `Returned the first ${rows.length} of ${totalAvailable} rows (client-side limit=${args.limit}); CBP has NO server-side pagination, so the remaining ${totalAvailable - rows.length} are not fetched separately — raise limit or narrow the filter to see them.`,
+    );
+  }
+
+  const filtersApplied = [
+    args.naics !== undefined ? `naics:${args.naics}` : "naics:(all)",
+    geoFilter,
+    `year:${year}`,
+  ];
+
+  const meta: Partial<ResponseMeta> = {
+    // MODE only — never the key value (K-test).
+    source: `api.census.gov /data/${year}/cbp (County Business Patterns; CENSUS_API_KEY)`,
+    keylessMode: false, // ★KEYED — the first key-required source
+    returned: rows.length,
+    totalAvailable,
+    filtersApplied,
+    filtersDropped: [],
+    fieldsUnavailable: [],
+    notes,
+  };
+
+  return withMeta({ rows }, meta);
+}