@cliwant/mcp-sam-gov 1.3.0 → 1.5.0

package/src/cpsc.ts

@@ -0,0 +1,333 @@
+/**
+ * cpsc.ts — CPSC CONSUMER-PRODUCT RECALLS (www.saferproducts.gov) — the consumer
+ * goods / import product-safety vetting lane (ADR-0058). ONE keyless tool:
+ *   • cpsc_recalls — /RestWebServices/Recall?format=json + date/product/manufacturer/
+ *     recallNumber filters.
+ * The third leg of the cross-agency product-safety family alongside NHTSA (vehicles)
+ * and openFDA (medical/food): a manufacturer / product / hazard recall history for
+ * B2G supplier and import vetting.
+ *
+ * ★ KEYLESS — there is NO API key at all (no parameter, no header). This module
+ *   touches NO key seam (no KEY_REGISTRY / keys.ts / API_KEYS.md). It REUSES the
+ *   shared `getJson` (redirect:"error") / `driftError` fetch envelope, the `str`
+ *   coercion (null-never-empty-string), and `withMeta`/`buildMeta` — and mirrors
+ *   nhtsa.ts / datagov-catalog.ts's fixed-host SSRF idiom + schema_drift
+ *   catch-ladder verbatim.
+ *
+ * ★ THE HONESTY PILLARS (P1-P5, live-verified 2026-07-15):
+ *   P1: the /Recall response is a BARE JSON ARRAY with NO count field and NO server
+ *       pagination — it returns the COMPLETE set matching the filter. So
+ *       totalAvailable = results.length and complete:true, WITH a disclosing note
+ *       that CPSC reports no total-count field / no pagination. A total is NEVER
+ *       fabricated (there is no upstream total to trust; the honest total is the
+ *       length of the complete set).
+ *   P2: an empty array `[]` ⇒ an HONEST EMPTY (returned:0, complete:true) — a filter
+ *       that matches nothing is an honest no-match, NOT an error. A 4xx ⇒
+ *       invalid_input; a 5xx/timeout ⇒ THROW (never a fake empty); a 200 non-JSON
+ *       body OR a non-array body ⇒ schema_drift (never a fabricated empty).
+ *   P3: dates stay STRINGS (via `str`); NumberOfUnits is free text ("About 6,500")
+ *       kept as a STRING; nested arrays (Products/Manufacturers/Retailers/Hazards/
+ *       Remedies/Injuries/ManufacturerCountries) are flattened to string arrays by
+ *       extracting each object's `.Name` (★ManufacturerCountries uses `.Country`,
+ *       NOT `.Name`), SKIPPING an empty `{}` object (never a fabricated entry); a
+ *       genuinely-absent nested array ⇒ []; null-never-empty-string throughout.
+ *   P4: the top-level body MUST be an array — a non-array (object/string/null) ⇒
+ *       driftError (a broken response contract, never a fabricated empty).
+ *   DEFAULT-WINDOW: with NO filter given, the unfiltered result is huge, so the tool
+ *       defaults RecallDateStart to ~90 days ago and DISCLOSES the default in a note
+ *       — it NEVER silently fetches the whole dataset.
+ *   SSRF: fixed host `www.saferproducts.gov` (compile-time literal) + post-construction
+ *       hostname/protocol assertion + redirect:"error"; every filter rides a
+ *       module-built URLSearchParams (no raw passthrough); dates are ^\d{4}-\d{2}-\d{2}$;
+ *       recallNumber is charclass-validated (letters/digits/hyphen only), so a
+ *       `../` or `%` can never reach the fixed path.
+ */
+
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { str } from "./coerce.js";
+import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
+
+// ─── Fixed endpoint (SSRF core — compile-time CONSTANTS) ──────────
+export const CPSC_HOST = "www.saferproducts.gov";
+const CPSC_RECALL_PATH = "/RestWebServices/Recall";
+// HOST+path-only label (→ ToolError.upstreamEndpoint). Keyless ⇒ no token can ever
+// appear here regardless, but the label stays host+path for consistency.
+const CPSC_RECALL_LABEL = "cpsc:/RestWebServices/Recall";
+
+// ─── Input validation grammar (SSRF + injection guard) ────────────
+// dates: strict YYYY-MM-DD. recallNumber: letters/digits/hyphen only — rejects
+// `../`, `%`, `/`, `.`, spaces, quotes, so a value can never break out of the
+// URLSearchParams-encoded query onto the fixed host/path.
+export const CPSC_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+export const CPSC_RECALL_NUMBER_RE = /^[A-Za-z0-9-]+$/;
+
+// The default recent-window span (days) applied when NO filter is given, so an
+// unbounded whole-dataset fetch never happens silently.
+const CPSC_DEFAULT_WINDOW_DAYS = 90;
+
+const KEYLESS_NOTE =
+  "CPSC SaferProducts is a keyless public API (www.saferproducts.gov) — no API key is required or accepted.";
+// The P1 load-bearing honesty caveat carried on EVERY response.
+const CPSC_NO_PAGINATION_NOTE =
+  "CPSC returns the complete matching set (no server pagination or total-count field) — totalAvailable is the number of returned recalls (the size of the complete set), not an upstream-reported total.";
+
+// ─── Nested-array flatteners (P3) ─────────────────────────────────
+/**
+ * Flatten a CPSC nested array (Products/Manufacturers/Retailers/Hazards/Remedies/
+ * Injuries/ManufacturerCountries) to a string[] by extracting `field` from each
+ * object via `str` (null-never-empty-string). An empty `{}` object (or one whose
+ * `field` is absent/blank) is SKIPPED — never a fabricated entry. A non-array
+ * (absent nested array) ⇒ [].
+ */
+function extractField(x: unknown, field: string): string[] {
+  if (!Array.isArray(x)) return [];
+  const out: string[] = [];
+  for (const el of x) {
+    if (el === null || typeof el !== "object") continue;
+    const v = str((el as Record<string, unknown>)[field]);
+    if (v !== null) out.push(v);
+  }
+  return out;
+}
+
+/**
+ * The recall-level numberOfUnits (P3): CPSC carries NumberOfUnits per PRODUCT as
+ * FREE TEXT ("About 6,500"), so this returns the FIRST product's non-blank
+ * NumberOfUnits as a STRING (never numerically coerced), or null when none is
+ * present (null-never-empty-string).
+ */
+function firstNumberOfUnits(products: unknown): string | null {
+  if (!Array.isArray(products)) return null;
+  for (const p of products) {
+    if (p === null || typeof p !== "object") continue;
+    const v = str((p as Record<string, unknown>).NumberOfUnits);
+    if (v !== null) return v;
+  }
+  return null;
+}
+
+// ─── Curated row shape ────────────────────────────────────────────
+export type CpscRecall = {
+  recallNumber: string | null;
+  recallDate: string | null;
+  title: string | null;
+  description: string | null;
+  url: string | null;
+  products: string[];
+  numberOfUnits: string | null;
+  manufacturers: string[];
+  retailers: string[];
+  hazards: string[];
+  remedies: string[];
+  injuries: string[];
+  manufacturerCountries: string[];
+};
+
+/**
+ * Map ONE /Recall row → the curated recall shape. Scalars via `str`
+ * (null-never-empty-string; dates stay strings). Nested arrays flattened via
+ * `extractField` on `.Name` — EXCEPT ManufacturerCountries, which carries `.Country`.
+ */
+function mapRecall(row: unknown): CpscRecall {
+  const r = (row ?? {}) as Record<string, unknown>;
+  return {
+    recallNumber: str(r.RecallNumber),
+    recallDate: str(r.RecallDate),
+    title: str(r.Title),
+    description: str(r.Description),
+    url: str(r.URL),
+    products: extractField(r.Products, "Name"),
+    numberOfUnits: firstNumberOfUnits(r.Products),
+    manufacturers: extractField(r.Manufacturers, "Name"),
+    retailers: extractField(r.Retailers, "Name"),
+    hazards: extractField(r.Hazards, "Name"),
+    remedies: extractField(r.Remedies, "Name"),
+    injuries: extractField(r.Injuries, "Name"),
+    // ★ ManufacturerCountries objects carry `Country`, not `Name` (live-verified).
+    manufacturerCountries: extractField(r.ManufacturerCountries, "Country"),
+  };
+}
+
+// ─── Input validation (belt-and-suspenders behind the server Zod) ──
+export type CpscRecallsArgs = {
+  dateStart?: string;
+  dateEnd?: string;
+  productName?: string;
+  manufacturer?: string;
+  recallNumber?: string;
+};
+
+/**
+ * Validate the optional inputs PRE-fetch (0 network call). A DIRECT handler call
+ * bypasses the server Zod, so re-guard the SSRF-relevant grammars here: dates are
+ * ^\d{4}-\d{2}-\d{2}$; recallNumber is letters/digits/hyphen only. productName /
+ * manufacturer are free text (they ride URLSearchParams-encoded, so injection is
+ * neutralized by encoding — no charclass needed, but they are validated as strings).
+ */
+function validateArgs(args: CpscRecallsArgs): void {
+  const dateChecks: Array<[string, string | undefined]> = [
+    ["dateStart", args.dateStart],
+    ["dateEnd", args.dateEnd],
+  ];
+  for (const [name, value] of dateChecks) {
+    if (value !== undefined && (typeof value !== "string" || !CPSC_DATE_RE.test(value))) {
+      throw new ToolErrorCarrier({
+        kind: "invalid_input",
+        retryable: false,
+        message: `Invalid ${name} ${JSON.stringify(value)} — expected a YYYY-MM-DD date (^\\d{4}-\\d{2}-\\d{2}$), e.g. "2025-01-01".`,
+        upstreamEndpoint: CPSC_RECALL_LABEL,
+      });
+    }
+  }
+  if (
+    args.recallNumber !== undefined &&
+    (typeof args.recallNumber !== "string" || !CPSC_RECALL_NUMBER_RE.test(args.recallNumber))
+  ) {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `Invalid recallNumber ${JSON.stringify(args.recallNumber)} — expected letters/digits/hyphen only (^[A-Za-z0-9-]+$), e.g. "25088".`,
+      upstreamEndpoint: CPSC_RECALL_LABEL,
+    });
+  }
+  for (const [name, value] of [
+    ["productName", args.productName],
+    ["manufacturer", args.manufacturer],
+  ] as Array<[string, string | undefined]>) {
+    if (value !== undefined && typeof value !== "string") {
+      throw new ToolErrorCarrier({
+        kind: "invalid_input",
+        retryable: false,
+        message: `Invalid ${name} — expected a string.`,
+        upstreamEndpoint: CPSC_RECALL_LABEL,
+      });
+    }
+  }
+}
+
+// ─── SSRF-guarded fetch (fixed host + hostname assertion + redirect) ──
+/**
+ * GET the CPSC /Recall JSON on the FIXED host. Builds
+ * `https://www.saferproducts.gov/RestWebServices/Recall?${params}`, asserts the
+ * CONSTRUCTED URL's hostname === the fixed host over https (belt-and-suspenders),
+ * and sets `redirect:"error"` (fail closed on any off-host 3xx). Keyless — no
+ * header/token.
+ */
+async function getCpsc(params: URLSearchParams): Promise<unknown> {
+  const url = `https://${CPSC_HOST}${CPSC_RECALL_PATH}?${params.toString()}`;
+  const built = new URL(url);
+  if (built.hostname !== CPSC_HOST || built.protocol !== "https:") {
+    throw new ToolErrorCarrier({
+      kind: "invalid_input",
+      retryable: false,
+      message: `Constructed CPSC URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the fixed host ${JSON.stringify(CPSC_HOST)} over https — refusing to fetch (SSRF safety).`,
+      upstreamEndpoint: CPSC_RECALL_LABEL,
+    });
+  }
+  return getJson(url, { label: CPSC_RECALL_LABEL, redirect: "error" });
+}
+
+/** Compute an ISO YYYY-MM-DD `days` days before now (the default-window start). */
+function daysAgoIso(days: number): string {
+  return new Date(Date.now() - days * 86_400_000).toISOString().slice(0, 10);
+}
+
+// ─── Tool: cpsc_recalls ───────────────────────────────────────────
+/**
+ * Fetch CPSC consumer-product RECALLS → curated recall rows + honest `_meta`.
+ * KEYLESS. All filters are optional; with NO filter given, RecallDateStart defaults
+ * to ~90 days ago (disclosed in a note) so the whole dataset is never silently
+ * fetched. The response is a bare array with no total-count field / no pagination
+ * ⇒ totalAvailable = the number of returned recalls, complete:true. An empty array
+ * ⇒ an honest empty; a 4xx ⇒ invalid_input; a 5xx/timeout ⇒ THROW; a 200 non-JSON
+ * OR a non-array body ⇒ schema_drift.
+ */
+export async function recalls(args: CpscRecallsArgs): Promise<MetaBundle> {
+  validateArgs(args);
+
+  // ── Build the query from VALIDATED typed args, key-by-key (SSRF: no raw
+  //    passthrough). format=json is ALWAYS appended. ──
+  const params = new URLSearchParams();
+  params.set("format", "json");
+  const filtersApplied: string[] = [];
+  if (args.dateStart !== undefined) {
+    params.set("RecallDateStart", args.dateStart);
+    filtersApplied.push("dateStart");
+  }
+  if (args.dateEnd !== undefined) {
+    params.set("RecallDateEnd", args.dateEnd);
+    filtersApplied.push("dateEnd");
+  }
+  if (args.productName !== undefined) {
+    params.set("ProductName", args.productName);
+    filtersApplied.push("productName");
+  }
+  if (args.manufacturer !== undefined) {
+    params.set("Manufacturer", args.manufacturer);
+    filtersApplied.push("manufacturer");
+  }
+  if (args.recallNumber !== undefined) {
+    params.set("RecallNumber", args.recallNumber);
+    filtersApplied.push("recallNumber");
+  }
+
+  // ── DEFAULT-WINDOW: with NO filter, an unbounded fetch would return the WHOLE
+  //    dataset. Bound it to a ~90-day recent window (RecallDateStart) and DISCLOSE
+  //    the default — never silently fetch everything. ──
+  const notes: string[] = [KEYLESS_NOTE, CPSC_NO_PAGINATION_NOTE];
+  let defaultWindowApplied = false;
+  if (filtersApplied.length === 0) {
+    const defaultStart = daysAgoIso(CPSC_DEFAULT_WINDOW_DAYS);
+    params.set("RecallDateStart", defaultStart);
+    defaultWindowApplied = true;
+    notes.push(
+      `No filter was provided — to avoid silently fetching the ENTIRE recall dataset, results are bounded to a default recent window: RecallDateStart=${defaultStart} (~${CPSC_DEFAULT_WINDOW_DAYS} days ago). Pass dateStart/dateEnd, productName, manufacturer, or recallNumber for a scoped query.`,
+    );
+  }
+
+  // ── The typed catch-ladder (nhtsa.ts / datagov-catalog.ts shape, VERBATIM):
+  //    a ToolErrorCarrier (host-assert / 4xx-5xx taxonomy) rethrows FIRST
+  //    (preserving its kind); a 200 non-JSON `.json()` SyntaxError reclassifies to
+  //    schema_drift; a bare error rethrows LAST. ──
+  let body: unknown;
+  try {
+    body = await getCpsc(params);
+  } catch (e) {
+    if (e instanceof ToolErrorCarrier) throw e;
+    if (e instanceof SyntaxError)
+      throw driftError(
+        CPSC_RECALL_LABEL,
+        "CPSC /RestWebServices/Recall returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).",
+      );
+    throw e;
+  }
+
+  // ── P4: the top-level body MUST be an array (a non-array object/string/null is
+  //    drift, never a fabricated empty). ──
+  if (!Array.isArray(body)) {
+    throw driftError(
+      CPSC_RECALL_LABEL,
+      "CPSC /RestWebServices/Recall shape drift — the response must be a bare JSON array.",
+    );
+  }
+
+  const recalls = (body as unknown[]).map(mapRecall);
+  const returned = recalls.length;
+
+  return withMeta(
+    { recalls },
+    {
+      source: `${CPSC_HOST} /RestWebServices/Recall (CPSC consumer-product recalls; keyless)`,
+      keylessMode: true,
+      returned,
+      // P1 — no upstream total-count field / no pagination: the complete set IS the
+      // returned rows, so totalAvailable = returned and complete:true (derived).
+      totalAvailable: returned,
+      filtersApplied: defaultWindowApplied ? ["dateStart(default)"] : filtersApplied,
+      filtersDropped: [],
+      fieldsUnavailable: [],
+      notes,
+    } satisfies Partial<ResponseMeta>,
+  );
+}

package/src/datagov-catalog.ts

@@ -209,14 +209,19 @@ export async function searchDatasets(
   const params = new URLSearchParams();
   const filtersApplied: string[] = [];
   if (args.query !== undefined) {
-    params.set("_q", args.query);
+    // DRIFT FIX (dogfooding 2026-07-16): the data.gov v4 catalog renamed its
+    // free-text param `_q` → `q` (and `_size` → `size`). The old `_q` was SILENTLY
+    // IGNORED — every query returned the same default catalog page while
+    // filtersApplied still claimed "query", a confidently-wrong result. LIVE-VERIFIED:
+    // q=wildfire → wildfire datasets; _q=wildfire → the generic default list.
+    params.set("q", args.query);
     filtersApplied.push("query");
   }
   if (args.organization !== undefined) {
     params.set("organization", args.organization);
     filtersApplied.push("organization");
   }
-  params.set("_size", String(limit));
+  params.set("size", String(limit));
   if (args.cursor !== undefined) {
     params.set("after", args.cursor);
     filtersApplied.push("cursor");
@@ -271,6 +276,17 @@ export async function searchDatasets(
       "No filters were applied — this is an unscoped scan of the WHOLE data.gov catalog. Add `query` and/or `organization` for a meaningful scoped result set.",
     );
   }
+  // Behavior-driven limit-honesty (dogfooding 2026-07-16): the v4 catalog currently
+  // returns an upstream-FIXED page (~20) and ignores the `size` argument. Fire ONLY
+  // when the API returned MORE than requested (returned > limit) — a DEFINITIVE
+  // "limit ignored" signal that can't be confused with a genuine small result set
+  // (returned < limit could just be few matches). Behavior-driven, so if the API
+  // begins honoring `size` again (returned ≤ limit) the note self-suppresses.
+  if (returned > limit) {
+    notes.push(
+      `The requested limit (${limit}) was NOT honored — the data.gov v4 catalog returned MORE (${returned} rows): it currently serves an upstream-fixed page and ignores the size argument. Page through the full result set with _meta.nextCursor, not by raising limit.`,
+    );
+  }
 
   return withMeta(
     { datasets },

package/src/dol.ts

@@ -12,7 +12,7 @@
  *   • `dol_get_dataset` (KEY-REQUIRED, DOL_API_KEY) — GET
  *     /v4/get/{agency}/{endpoint}/json?… . The DATA endpoint has NO keyless tier, so
  *     with NO `DOL_API_KEY` this tool THROWS an invalid_input config error BEFORE any
- *     fetch (0 network call; the message names DOL_API_KEY + dol.gov/developer).
+ *     fetch (0 network call; the message names DOL_API_KEY + dataportal.dol.gov/registration).
  *   So DOL is the 4th REQUIRED key — but ONLY for the data tool; the catalog tool
  *   (and every other tool on the server) stays keyless.
  *
@@ -44,7 +44,7 @@
  *
  * ★HONESTY (ADR-0053 P1–P4 + KEY + SSRF):
  *   [KEY]  dol_get_dataset with NO DOL_API_KEY ⇒ invalid_input THROW pre-fetch (0
- *          fetch); the message names DOL_API_KEY + dol.gov/developer. The key rides the
+ *          fetch); the message names DOL_API_KEY + dataportal.dol.gov/registration. The key rides the
  *          `X-API-KEY` HEADER ONLY — NEVER the URL / label / _meta / notes / a log (the
  *          K-test). dol_list_datasets is keyless (no key read, no header).
  *   [P1]   catalog: totalAvailable = meta.total_count (the API's real catalog total)
@@ -103,7 +103,7 @@ const DEFAULT_LIST_LIMIT = 25;
 
 // ─── Honesty notes ────────────────────────────────────────────────
 const KEY_REQUIRED_NOTE =
-  "dol_get_dataset REQUIRES a free DOL_API_KEY (the DOL data endpoint has no keyless tier; the CATALOG — dol_list_datasets — and agency list are keyless). Get a key at https://dol.gov/developer. The key is sent ONLY in the X-API-KEY request header and is NEVER logged, echoed, or placed in this response.";
+  "dol_get_dataset REQUIRES a free DOL_API_KEY (the DOL data endpoint has no keyless tier; the CATALOG — dol_list_datasets — and agency list are keyless). Get a key at https://dataportal.dol.gov/registration. The key is sent ONLY in the X-API-KEY request header and is NEVER logged, echoed, or placed in this response.";
 const DATA_ENVELOPE_NOTE =
   "The DOL data-record envelope is key-gated and could not be verified live, so records are returned VERBATIM (each dataset has its own enforcement schema — field names and values are preserved as-is; a value is NOT coerced, so a genuine 0 stays 0 and a missing field stays null).";
 const DATA_NO_TOTAL_NOTE =
@@ -313,7 +313,7 @@ export async function getDataset(args: DolGetDatasetArgs): Promise<MetaBundle> {
       kind: "invalid_input",
       retryable: false,
       message:
-        "The DOL data endpoint requires a free DOL_API_KEY (the dataset CATALOG, dol_list_datasets, is keyless). Get one at https://dol.gov/developer and set DOL_API_KEY.",
+        "The DOL data endpoint requires a free DOL_API_KEY (the dataset CATALOG, dol_list_datasets, is keyless). Get one at https://dataportal.dol.gov/registration and set DOL_API_KEY.",
       upstreamEndpoint: label,
     });
   }
@@ -404,7 +404,7 @@ export async function getDataset(args: DolGetDatasetArgs): Promise<MetaBundle> {
           kind: "invalid_input",
           retryable: false,
           message:
-            "DOL rejected the request as unauthorized (HTTP 401/403) — DOL_API_KEY is missing or invalid. Check the key (free at https://dol.gov/developer).",
+            "DOL rejected the request as unauthorized (HTTP 401/403) — DOL_API_KEY is missing or invalid. Check the key (free at https://dataportal.dol.gov/registration).",
           upstreamStatus: status,
           upstreamEndpoint: label,
         });

package/src/ecfr.ts

@@ -52,16 +52,33 @@ export async function listTitles() {
       }[];
     };
     const json = await fetchJson<Resp>(`${ECFR}/versioner/v1/titles.json`);
-    return {
-      titles: (json.titles ?? []).map((t) => ({
-        number: t.number ?? 0,
-        name: t.name ?? "",
-        latestAmendedOn: t.latest_amended_on,
-        latestIssueDate: t.latest_issue_date,
-        upToDateAsOf: t.up_to_date_as_of,
-        reserved: !!t.reserved,
-      })),
-    };
+    const titles = (json.titles ?? []).map((t) => ({
+      number: t.number ?? 0,
+      name: t.name ?? "",
+      latestAmendedOn: t.latest_amended_on,
+      latestIssueDate: t.latest_issue_date,
+      upToDateAsOf: t.up_to_date_as_of,
+      reserved: !!t.reserved,
+    }));
+    // Carry the honesty envelope every other tool has (dogfooding 2026-07-15: this
+    // list tool previously returned a bare {titles} with no _meta). The titles
+    // endpoint returns the COMPLETE canonical CFR title set in one response — no
+    // pagination, no filter — so the count IS the total and complete derives true.
+    return withMeta(
+      { titles },
+      {
+        source: "ecfr.gov/api (versioner/v1/titles)",
+        keylessMode: true,
+        returned: titles.length,
+        totalAvailable: titles.length,
+        truncated: false,
+        filtersApplied: [],
+        filtersDropped: [],
+        notes: [
+          "Complete canonical list of all CFR titles — the endpoint returns every title in a single response (no pagination or filtering).",
+        ],
+      },
+    );
   });
 }
 

package/src/edgar.ts

@@ -241,20 +241,46 @@ async function tickerMap(): Promise<TickerEntry[]> {
  */
 async function resolveCik(
   cikOrTicker: string,
-): Promise<{ cik: string; ticker: string | null; title: string | null } | null> {
+): Promise<{
+  cik: string;
+  ticker: string | null;
+  title: string | null;
+  matchedBy: "cik" | "ticker" | "title";
+} | null> {
   const raw = cikOrTicker.trim();
   if (/^(cik)?\s*\d+$/i.test(raw)) {
-    return { cik: padCik(raw), ticker: null, title: null };
+    return { cik: padCik(raw), ticker: null, title: null, matchedBy: "cik" };
   }
   const map = await tickerMap();
   const upper = raw.toUpperCase();
   const exact = map.find((e) => e.ticker.toUpperCase() === upper);
-  if (exact) return { cik: exact.cik, ticker: exact.ticker, title: exact.title };
+  if (exact)
+    return { cik: exact.cik, ticker: exact.ticker, title: exact.title, matchedBy: "ticker" };
   const byName = map.find((e) => e.title.toUpperCase().includes(upper));
-  if (byName) return { cik: byName.cik, ticker: byName.ticker, title: byName.title };
+  if (byName)
+    return { cik: byName.cik, ticker: byName.ticker, title: byName.title, matchedBy: "title" };
   return null;
 }
 
+/**
+ * Disclosure note when resolveCik fell back to a case-insensitive TITLE SUBSTRING
+ * match (not an exact ticker/CIK). A substring silently resolves to the FIRST filer
+ * whose title contains the string — which can be the WRONG company (dogfooding
+ * 2026-07-16: "MICRO" → MICROSOFT, not Micron/AMD/Super Micro), and the data tools
+ * would then return that filer's financials as authoritative with no caveat. The
+ * data-returning tools (facts/filings/concept) MUST surface HOW the id resolved —
+ * exactly as edgar_lookup_cik already does. Returns null for exact ticker/CIK matches.
+ */
+function fuzzyResolveNote(
+  resolved: { title: string | null; cik: string; matchedBy: string },
+  input: string,
+): string | null {
+  if (resolved.matchedBy !== "title") return null;
+  return `Resolved "${input}" to ${
+    resolved.title ?? "this filer"
+  } (CIK ${resolved.cik}) by a case-insensitive TITLE SUBSTRING match, NOT an exact ticker/CIK — a substring can silently match the WRONG company. VERIFY this is the intended filer (use edgar_lookup_cik to list all matches, or pass an exact ticker or 10-digit CIK).`;
+}
+
 // ─── meta helper ──────────────────────────────────────────────────
 /**
  * Build a partial `_meta` with the EDGAR source + the mandatory CIK↔UEI caveat
@@ -549,6 +575,7 @@ export async function companyFilings(args: {
     );
   }
   const cik = resolved.cik;
+  const fuzzyNote = fuzzyResolveNote(resolved, args.cikOrTicker);
   let subm;
   try {
     subm = await fetchSubmissions(cik);
@@ -746,7 +773,7 @@ export async function companyFilings(args: {
         hasMore,
         nextOffset,
       },
-      notes,
+      notes: fuzzyNote ? [fuzzyNote, ...notes] : notes,
     }),
   );
 }
@@ -833,6 +860,7 @@ export async function companyFacts(args: {
     );
   }
   const cik = resolved.cik;
+  const fuzzyNote = fuzzyResolveNote(resolved, args.cikOrTicker);
   let doc: FactsDoc;
   try {
     doc = await fetchFacts(cik);
@@ -964,7 +992,7 @@ export async function companyFacts(args: {
       totalAvailable: concepts.length,
       complete: true,
       filtersApplied: latest ? ["concepts", "unit", "latest"] : ["concepts", "unit"],
-      notes,
+      notes: fuzzyNote ? [fuzzyNote, ...notes] : notes,
     }),
   );
 }
@@ -2771,6 +2799,7 @@ export async function companyConcept(args: {
     );
   }
   const cik = resolved.cik;
+  const fuzzyNote = fuzzyResolveNote(resolved, args.cikOrTicker);
   const taxonomy = args.taxonomy ?? "us-gaap";
   const concept = args.concept;
 
@@ -2873,6 +2902,7 @@ export async function companyConcept(args: {
         complete: true,
         filtersApplied: ["concept", "taxonomy"],
         notes: [
+          ...(fuzzyNote ? [fuzzyNote] : []),
           `The companyconcept document for CIK ${cik} / ${taxonomy} / ${concept} has no reported data points (units{} is empty). This is an honest empty — NOT a value of 0 and NOT an outage.`,
         ],
       }),
@@ -2943,7 +2973,9 @@ export async function companyConcept(args: {
   if (fyFilter !== null) filtersApplied.push("fy");
   if (canonicalOnly) filtersApplied.push("canonicalOnly");
 
-  const notes: string[] = [AMENDMENT_DISCLOSURE_NOTE];
+  const notes: string[] = fuzzyNote
+    ? [fuzzyNote, AMENDMENT_DISCLOSURE_NOTE]
+    : [AMENDMENT_DISCLOSURE_NOTE];
 
   // Unit-filter disclosure (Q2-c) — NEVER hide the other units.
   if (unitFilter !== null) {