@cliwant/mcp-sam-gov 0.3.0 → 1.0.0

package/src/usaspending.ts

@@ -66,8 +66,259 @@ function buildFilters(args: {
   return filters;
 }
 
-import { fetchWithRetry } from "./errors.js";
+/**
+ * VQ-6 (C79 dogfooding): derive the honest `_meta.filtersApplied` labels from the
+ * ACTUAL filter object sent upstream. Reading the built `filters` (not the args)
+ * means it can NEVER drift from what was really applied. `award_type_codes` is
+ * always present (contracts-only A/B/C/D). Every buildFilters-based tool previously
+ * reported `filtersApplied:[]` even when naics/agency/fiscalYear WAS applied — an
+ * agent verifying via `_meta` could not confirm its filter took effect.
+ */
+function filtersAppliedFromFilters(f: UsasFilters): string[] {
+  // UsasFilters is Record<string, unknown>, so narrow each value to a non-empty
+  // array before treating it as "applied".
+  const has = (k: string): boolean => {
+    const v = f[k];
+    return Array.isArray(v) && v.length > 0;
+  };
+  const applied: string[] = [];
+  // Label the ACTUAL award-type scope. A/B/C/D = contracts; 02/03/04/05 = grants
+  // (searchCfdaSpending). Adversarial-review SHIP-BLOCKER: a value-blind label
+  // made the grants tool falsely claim "contracts A/B/C/D".
+  const atc = f["award_type_codes"];
+  if (Array.isArray(atc) && atc.length > 0) {
+    const codes = atc.map(String);
+    applied.push(
+      codes.includes("A")
+        ? "awardType(contracts A/B/C/D)"
+        : `awardType(${codes.join("/")})`,
+    );
+  }
+  if (has("agencies")) applied.push("agency");
+  if (has("naics_codes")) applied.push("naics");
+  if (has("time_period")) applied.push("fiscalYear");
+  if (has("set_aside_type_codes")) applied.push("setAside");
+  if (has("psc_codes")) applied.push("pscCodes");
+  if (has("recipient_search_text")) applied.push("recipientSearchText");
+  return applied;
+}
+
+import { fetchWithRetry, ToolErrorCarrier, errorFromResponse } from "./errors.js";
+import {
+  throughPathChain,
+  CircuitBreaker,
+  type ResiliencePath,
+  type Provenance,
+} from "./datasource.js";
+import { snapshotPath, provenanceMeta } from "./snapshot.js";
 import { memoize } from "./cache.js";
+import { withMeta, type MetaBundle, type ResponseMeta } from "./meta.js";
+
+// ─── Resilience wiring (ADR-0045 pilot expansion — INERT by default) ───────
+// The USAspending live host + a per-host circuit breaker keyed on the FIXED set
+// {this host} (bounded — m3-regression). CONSULTED only by `throughPathChain`
+// for a ≥2-path chain; when SAMGOV_SNAPSHOT_BASE_URL is unset the chain is
+// single-path (live only), the breaker is a pure no-op, and every opted-in
+// reference tool is BYTE-IDENTICAL to before this ADR. Only the three
+// SLOW-CHANGING, canonical/queryless REFERENCE reads opt in (toptier agencies,
+// the top-level NAICS tree, the glossary); the search/aggregate tools stay
+// live-only (a snapshot can't cover free queries). See datasource.ts §"RESILIENCE
+// PORT" and the policy boundary (no route-around / public-only / no-proxy).
+const USAS_HOST = "api.usaspending.gov";
+let usasBreaker = new CircuitBreaker([USAS_HOST]);
+
+/**
+ * Test-only: reset the resilience circuit breaker between OFFLINE fixtures (the
+ * breaker is module-level process state; a fresh instance isolates cases).
+ * Mirrors treasury.ts's `_resetTreasuryBreakerForTests`.
+ */
+export function _resetUsasBreakerForTests(): void {
+  usasBreaker = new CircuitBreaker([USAS_HOST]);
+}
+
+const SPENDING_BY_AWARD_SOURCE =
+  "usaspending.gov/api/v2 search/spending_by_award";
+const SPENDING_BY_CATEGORY_RECIPIENT_SOURCE =
+  "usaspending.gov/api/v2 search/spending_by_category/recipient";
+const SPENDING_OVER_TIME_SOURCE =
+  "usaspending.gov/api/v2 search/spending_over_time";
+
+/**
+ * `page_metadata` shape for the `spending_by_category/*` endpoints. These are
+ * cursor/page-paginated: the block carries `hasNext` but NO grand total
+ * (empirically verified 2026-07-03 for psc/state_territory/cfda/federal_account/
+ * awarding_agency/awarding_subagency — every one returns only
+ * `{page, next, previous, hasNext, hasPrevious}`). So a truthful aggregate
+ * `_meta` uses `hasNext` as the truncation signal and sets
+ * `totalAvailable: null` — never the page length (spec §3.3).
+ */
+type CategoryPageMeta = {
+  page?: number;
+  next?: number | null;
+  hasNext?: boolean;
+};
+
+/**
+ * Build the `_meta` for a top-N `spending_by_category/*` aggregate. These
+ * category endpoints report no grand total, so `totalAvailable` is always
+ * `null` (honest "unknown" — never the returned count). Truncation is the
+ * endpoint's own `hasNext` when present, else `returned >= limit`.
+ */
+function categoryAggregateMeta(opts: {
+  source: string;
+  returned: number;
+  limit: number;
+  hasNext?: boolean;
+  fieldsUnavailable?: string[];
+  extraNotes?: string[];
+  filters?: UsasFilters;
+}): Partial<ResponseMeta> {
+  const truncated = opts.hasNext ?? opts.returned >= opts.limit;
+  const notes: string[] = [];
+  if (truncated) {
+    notes.push(
+      `Capped at the top ${opts.limit} categories by amount; more categories may exist. This endpoint reports no grand total, so the true number of categories is unknown (totalAvailable is null, NOT the returned count). These extra categories are NOT page-reachable — all six callers post page:1 with NO offset/page input (nextOffset is null). Raise limit (up to 50) or narrow filters to see the rest.`,
+    );
+  }
+  if (opts.extraNotes) notes.push(...opts.extraNotes);
+  return {
+    source: opts.source,
+    keylessMode: true,
+    returned: opts.returned,
+    // spec §3.3: the spending_by_category/* endpoints expose no total → null.
+    totalAvailable: null,
+    truncated,
+    pagination: {
+      offset: 0,
+      limit: opts.limit,
+      // W3-8 (honesty; mirrors awardPagination :488 / searchRecipients M1): all SIX
+      // callers (searchPscSpending / searchStateSpending / searchCfdaSpending /
+      // searchFederalAccountSpending / searchAgencySpending / searchSubAgencySpending)
+      // hardcode page:1 and expose ONLY `limit` (no offset/page arg) — so `nextOffset`
+      // is NOT consumable. Emitting `opts.returned` (the page length) made an agent
+      // re-fetch the SAME top-N forever while ranked-below-`limit` categories stayed
+      // unreachable. Emit null unconditionally; `truncated`/`hasMore` stay honest — the
+      // extras are reachable ONLY by raising `limit` (≤50) or narrowing filters.
+      nextOffset: null,
+      hasMore: truncated,
+    },
+    filtersApplied: opts.filters ? filtersAppliedFromFilters(opts.filters) : [],
+    filtersDropped: [],
+    fieldsUnavailable: opts.fieldsUnavailable ?? [],
+    notes,
+  };
+}
+
+/**
+ * Build the `_meta` for a reference / autocomplete tool. These are the
+ * anti-hallucination lookups (NAICS/recipient autocomplete, NAICS hierarchy,
+ * glossary, toptier agencies). Completeness rule (spec §2.3): a page that
+ * came back SHORT of the requested `limit` is the whole result set
+ * (`truncated:false`); a FULL page means more may exist (`truncated:true`).
+ * When the endpoint reports a real total (glossary), pass it so truncation is
+ * derived from `returned < total` instead. All are served from a 5-min TTL
+ * cache (see cache.ts) — noted so the AI knows the data may be up to 5 min old.
+ * [가설] we can't tell a cache HIT from a MISS here, so the note is
+ * unconditional rather than hit-specific.
+ */
+function referenceMeta(opts: {
+  source: string;
+  returned: number;
+  limit: number;
+  totalAvailable: number | null;
+  limitHonored?: boolean; // false ⇒ endpoint ignores `limit` (e.g. toptier)
+  extraNotes?: string[];
+}): Partial<ResponseMeta> {
+  const { source, returned, limit, totalAvailable } = opts;
+  const limitHonored = opts.limitHonored ?? true;
+  let truncated: boolean;
+  let hasMore: boolean;
+  if (totalAvailable !== null) {
+    truncated = returned < totalAvailable;
+    hasMore = truncated;
+  } else if (!limitHonored) {
+    // Endpoint ignores `limit` and returns the full set → complete.
+    truncated = false;
+    hasMore = false;
+  } else {
+    truncated = returned >= limit;
+    hasMore = truncated;
+  }
+  const notes: string[] = [
+    "Reference lookup served from a 5-minute TTL cache; values may be up to 5 minutes stale.",
+  ];
+  if (truncated) {
+    notes.push(
+      totalAvailable !== null
+        ? `Showing ${returned} of ${totalAvailable} total; raise limit to see more.`
+        : `A full page of ${returned} was returned; more matches may exist — raise limit to widen the result.`,
+    );
+  }
+  if (opts.extraNotes) notes.push(...opts.extraNotes);
+  return {
+    source,
+    keylessMode: true,
+    returned,
+    totalAvailable,
+    truncated,
+    pagination: {
+      // W3-8 (honesty; mirrors govinfo.ts:406-408 "no numeric offset"): the three
+      // callers (autocompleteNaics / autocompleteRecipient / glossary) forward only
+      // searchText/search + limit — NO offset/page input — so these reference lookups
+      // are not offset-pageable AT ALL. Emit BOTH offset:null and nextOffset:null;
+      // emitting `returned` for nextOffset made an agent re-fetch the SAME page forever.
+      // `hasMore`/`truncated` stay honest — the truncation notes already say "raise
+      // limit" (the only real way to widen), so no page cursor is implied.
+      offset: null,
+      limit,
+      nextOffset: null,
+      hasMore,
+    },
+    filtersApplied: [],
+    filtersDropped: [],
+    fieldsUnavailable: [],
+    notes,
+  };
+}
+
+/**
+ * True total for a `spending_by_award` query, via the companion
+ * `spending_by_award_count` endpoint.
+ *
+ * WHY a companion query (not `page_metadata.total`): the `spending_by_award`
+ * response uses cursor-style pagination — its `page_metadata` carries only
+ * `page`/`hasNext`/`last_record_*`, NOT a `total` (empirically verified
+ * 2026-07-03; the spec's assumption that it mirrors `recipient/`'s
+ * `page_metadata.total` was wrong for this endpoint). The only honest source
+ * of a real count is `spending_by_award_count`, which returns per-award-type
+ * buckets; we sum them. Returns `null` on any failure — NEVER a page length
+ * (spec §3.3: never substitute page size for an unknown total).
+ */
+async function awardCount(
+  filters: UsasFilters,
+  mode: "awards" | "subawards",
+): Promise<number | null> {
+  try {
+    type CountResp = { results?: Record<string, number> };
+    const body: Record<string, unknown> = { filters };
+    if (mode === "subawards") body.subawards = true;
+    const json = await postUsas<CountResp>(
+      "search/spending_by_award_count/",
+      body,
+    );
+    const results = json.results;
+    if (!results) return null;
+    // Awards → contracts+idvs+direct_payments+grants+loans+other.
+    // Subawards → subcontracts+subgrants. Sum every numeric bucket so we stay
+    // correct if the endpoint adds categories.
+    return Object.values(results).reduce(
+      (s, v) => s + (typeof v === "number" ? v : 0),
+      0,
+    );
+  } catch {
+    return null;
+  }
+}
 
 async function postUsas<T>(
   endpoint: string,
@@ -95,6 +346,34 @@ async function getUsas<T>(endpoint: string): Promise<T> {
   return (await r.json()) as T;
 }
 
+/**
+ * getUsas THROUGH the resilience path-chain (ADR-0045 pilot expansion). The LIVE
+ * path is byte-identical to a bare `getUsas(endpoint)` — same URL, same init
+ * ({signal} only), same label — so with no snapshot configured the chain is
+ * SINGLE-ENTRY and `throughPathChain` fast-paths (no breaker consult, no
+ * overhead) ⇒ output BYTE-IDENTICAL to before this ADR (the INERT guarantee).
+ *
+ * A snapshot fallback is added ONLY when (a) `snapshotKey` is provided (the
+ * caller declares this read is a canonical/queryless reference the builder can
+ * pre-fetch) AND (b) SAMGOV_SNAPSHOT_BASE_URL is configured (else `snapshotPath`
+ * returns null). When either is absent the chain stays live-only. The snapshot's
+ * `data` is the RAW upstream JSON (same shape as the live body), so the caller's
+ * existing mapping applies unchanged to both paths.
+ */
+async function getUsasResilient<T>(
+  endpoint: string,
+  snapshotKey?: string,
+): Promise<{ body: T; provenance: Provenance }> {
+  const livePath: ResiliencePath<T> = {
+    host: USAS_HOST,
+    provenance: { dataPath: "live" },
+    run: () => getUsas<T>(endpoint),
+  };
+  const snap = snapshotKey ? snapshotPath<T>(snapshotKey) : null;
+  const paths = snap ? [livePath, snap] : [livePath];
+  return throughPathChain<T>(paths, usasBreaker);
+}
+
 // ─── Aggregate share-of-wallet ───────────────────────────────────
 
 export async function searchAwards(args: {
@@ -106,21 +385,45 @@ export async function searchAwards(args: {
   const filters = buildFilters(args);
   type Resp = {
     results?: { name?: string; amount?: number; count?: number }[];
+    page_metadata?: { total?: number; count?: number };
   };
+  const limit = 10;
   const json = await postUsas<Resp>(
     "search/spending_by_category/recipient",
-    { filters, limit: 10, page: 1 },
+    { filters, limit, page: 1 },
   );
   const results = json.results ?? [];
-  return {
-    totalAwards: results.reduce((s, r) => s + (r.count ?? 0), 0),
+  // B1 (spec §1.3, §3.4): the spending_by_category/recipient endpoint returns
+  // `amount` but NOT a per-recipient award `count`. The old code defaulted the
+  // missing count to 0, so every recipient reported `awards:0` and
+  // `totalAwards:0` while `totalValue` was billions — a self-contradictory lie
+  // ("0 contracts worth $3.45B"). Emit `null` (explicit "not available"), NOT
+  // 0, and flag it in `_meta.fieldsUnavailable`. `amount`/`value` unchanged.
+  const data = {
+    totalAwards: null as number | null,
     totalValue: results.reduce((s, r) => s + (r.amount ?? 0), 0),
     topRecipients: results.map((r) => ({
       name: r.name ?? "—",
       value: r.amount ?? 0,
-      awards: r.count ?? 0,
+      awards: null as number | null,
     })),
   };
+  return withMeta(data, {
+    source: SPENDING_BY_CATEGORY_RECIPIENT_SOURCE,
+    keylessMode: true,
+    returned: results.length,
+    // This is a landscape/top-N aggregate: the recipient tail is capped at
+    // `limit` and the category endpoint reports no grand total → unknown.
+    totalAvailable: null,
+    truncated: results.length >= limit,
+    filtersApplied: filtersAppliedFromFilters(filters),
+    filtersDropped: [],
+    fieldsUnavailable: ["awards", "totalAwards"],
+    notes: [
+      "Per-recipient award COUNTS are not available from the spending_by_category/recipient endpoint (it returns obligated amount only) — `awards` and `totalAwards` are null, not 0. For a real contract count use usas_search_awards_by_recipient (its _meta.totalAvailable) or usas_get_recipient_profile.",
+      "Only contract award types (A/B/C/D) are included; grants/IDVs are excluded from this share-of-wallet view.",
+    ],
+  });
 }
 
 // ─── Line-item awards ─────────────────────────────────────────────
@@ -140,38 +443,123 @@ export async function searchIndividualAwards(args: {
       "Award Amount"?: number;
       "Awarding Agency"?: string;
       "Awarding Sub Agency"?: string;
+      NAICS?: { code?: string; description?: string };
       "Place of Performance State Code"?: string;
+      "Place of Performance City Code"?: string;
+      "Place of Performance Country Code"?: string;
+      "Place of Performance Zip5"?: string;
       Description?: string;
       generated_internal_id?: string;
     }[];
+    page_metadata?: { hasNext?: boolean };
   };
-  const json = await postUsas<Resp>("search/spending_by_award", {
-    filters,
-    fields: [
-      "Award ID",
-      "Recipient Name",
-      "Award Amount",
-      "Awarding Agency",
-      "Awarding Sub Agency",
-      "Place of Performance State Code",
-      "Description",
-    ],
-    limit: args.limit ?? 10,
-    page: 1,
-    subawards: false,
-  });
-  return {
-    awards: (json.results ?? []).map((r) => ({
+  const limit = args.limit ?? 10;
+  // D1/D2 field-parity (spec §3.2): "NAICS" and the "Place of Performance …"
+  // fields are valid `spending_by_award` field names (empirically verified
+  // 2026-07-03 + confirmed against the API contract) and cost NO extra request
+  // — USAspending returns whatever fields you ask for. Set-aside is NOT a
+  // requestable field on this endpoint (filter-only) → documented as
+  // detail-only in `_meta.fieldsUnavailable`.
+  const [json, total] = await Promise.all([
+    postUsas<Resp>("search/spending_by_award", {
+      filters,
+      fields: [
+        "Award ID",
+        "Recipient Name",
+        "Award Amount",
+        "Awarding Agency",
+        "Awarding Sub Agency",
+        "NAICS",
+        "Place of Performance State Code",
+        "Place of Performance City Code",
+        "Place of Performance Country Code",
+        "Place of Performance Zip5",
+        "Description",
+      ],
+      limit,
+      page: 1,
+      subawards: false,
+    }),
+    awardCount(filters, "awards"),
+  ]);
+  const results = json.results ?? [];
+  const data = {
+    awards: results.map((r) => ({
       awardId: r["Award ID"] ?? "",
-      recipient: r["Recipient Name"] ?? "",
-      amount: r["Award Amount"] ?? 0,
-      awardingAgency: r["Awarding Agency"] ?? "",
+      recipient: r["Recipient Name"] || null,
+      // F2 (P3 null-never-0): an ABSENT Award Amount → null, NEVER a fabricated
+      // $0 (a null-amount IDV/loan-type row must not read as "a $0 award"). A
+      // genuine 0 still survives — `??` fires only on null/undefined.
+      amount: r["Award Amount"] ?? null,
+      awardingAgency: r["Awarding Agency"] || null,
       awardingSubAgency: r["Awarding Sub Agency"],
+      // D1: NAICS now returned (parity with usas_search_awards_by_recipient).
+      naicsCode: r.NAICS?.code,
+      naicsDescription: r.NAICS?.description,
       placeOfPerformanceState: r["Place of Performance State Code"],
+      placeOfPerformanceCity: r["Place of Performance City Code"],
+      placeOfPerformanceCountry: r["Place of Performance Country Code"],
+      placeOfPerformanceZip: r["Place of Performance Zip5"],
       description: r.Description,
       generatedInternalId: r.generated_internal_id ?? "",
     })),
   };
+  const pagination = awardPagination(
+    0,
+    limit,
+    results.length,
+    total,
+    json.page_metadata?.hasNext ?? false,
+  );
+  const notes = [
+    "Set-aside type is NOT available from the spending_by_award search endpoint (it can only be FILTERED, not returned) — call usas_get_award_detail (setAsideType/setAsideDescription) per award via generatedInternalId.",
+  ];
+  // W3-7: when more matches exist than this single ranked page holds, say so AND
+  // that they are not page-reachable (nextOffset is null — no offset input here).
+  if (pagination.hasMore) {
+    notes.push(
+      `Showing ${limit} of ${total ?? "more"} matching awards. These extra matches are NOT page-reachable — this tool returns one ranked page with no offset input (nextOffset is null). Raise limit (up to 50) or narrow the filters to see more.`,
+    );
+  }
+  return withMeta(data, {
+    source: SPENDING_BY_AWARD_SOURCE,
+    keylessMode: true,
+    returned: results.length,
+    totalAvailable: total,
+    pagination,
+    filtersApplied: filtersAppliedFromFilters(filters),
+    filtersDropped: [],
+    // Set-aside is not a `spending_by_award` output field; PoP city is often a
+    // numeric code (or null) rather than a name. Both live in detail.
+    fieldsUnavailable: ["setAside", "setAsideDescription"],
+    notes,
+  });
+}
+
+/** hasMore for cursor-paginated award search: prefer the real total. */
+function awardPagination(
+  offset: number,
+  limit: number,
+  returned: number,
+  total: number | null,
+  upstreamHasNext: boolean,
+): NonNullable<MetaBundle["meta"]["pagination"]> {
+  const hasMore =
+    total !== null ? offset + returned < total : upstreamHasNext;
+  return {
+    offset,
+    limit,
+    // W3-7 (honesty; mirrors searchRecipients M1): ALL THREE callers
+    // (searchIndividualAwards / searchAwardsByRecipient / searchSubawards) request
+    // the upstream `page:1` with NO offset/page input in their tool schemas — so
+    // `nextOffset` is NOT consumable. Emitting `offset + returned` (the page length)
+    // made an agent re-fetch the SAME top-N forever while ranked-below-`limit` rows
+    // stayed unjoinable. Emit null unconditionally; `hasMore` stays honest (more
+    // matches DO exist) — the extras are reachable ONLY by raising `limit` (≤50) or
+    // narrowing the filters. (No offset-capable caller exists — verified: all 3 pass 0.)
+    nextOffset: null,
+    hasMore,
+  };
 }
 
 // ─── Recipient win history ────────────────────────────────────────
@@ -193,40 +581,92 @@ export async function searchAwardsByRecipient(args: {
       "Awarding Agency"?: string;
       "Awarding Sub Agency"?: string;
       NAICS?: { code?: string; description?: string };
+      "Place of Performance State Code"?: string;
+      "Place of Performance City Code"?: string;
+      "Place of Performance Country Code"?: string;
+      "Place of Performance Zip5"?: string;
       Description?: string;
       generated_internal_id?: string;
     }[];
+    page_metadata?: { hasNext?: boolean };
   };
-  const json = await postUsas<Resp>("search/spending_by_award", {
-    filters,
-    fields: [
-      "Award ID",
-      "Recipient Name",
-      "Award Amount",
-      "Awarding Agency",
-      "Awarding Sub Agency",
-      "NAICS",
-      "Description",
-    ],
-    limit: args.limit ?? 15,
-    page: 1,
-    subawards: false,
-  });
+  const limit = args.limit ?? 15;
+  const [json, total] = await Promise.all([
+    postUsas<Resp>("search/spending_by_award", {
+      filters,
+      fields: [
+        "Award ID",
+        "Recipient Name",
+        "Award Amount",
+        "Awarding Agency",
+        "Awarding Sub Agency",
+        "NAICS",
+        "Place of Performance State Code",
+        "Place of Performance City Code",
+        "Place of Performance Country Code",
+        "Place of Performance Zip5",
+        "Description",
+      ],
+      limit,
+      page: 1,
+      subawards: false,
+    }),
+    awardCount(filters, "awards"),
+  ]);
   const results = json.results ?? [];
-  return {
+  const data = {
     awards: results.map((r) => ({
       awardId: r["Award ID"] ?? "",
-      recipient: r["Recipient Name"] ?? "",
-      amount: r["Award Amount"] ?? 0,
-      awardingAgency: r["Awarding Agency"] ?? "",
+      recipient: r["Recipient Name"] || null,
+      // F2 (P3 null-never-0): an ABSENT Award Amount → null, NEVER a fabricated
+      // $0 (a null-amount IDV/loan-type row must not read as "a $0 award"). A
+      // genuine 0 still survives — `??` fires only on null/undefined.
+      amount: r["Award Amount"] ?? null,
+      awardingAgency: r["Awarding Agency"] || null,
       awardingSubAgency: r["Awarding Sub Agency"],
       naicsCode: r.NAICS?.code,
       naicsDescription: r.NAICS?.description,
+      placeOfPerformanceState: r["Place of Performance State Code"],
+      placeOfPerformanceCity: r["Place of Performance City Code"],
+      placeOfPerformanceCountry: r["Place of Performance Country Code"],
+      placeOfPerformanceZip: r["Place of Performance Zip5"],
       description: r.Description,
       generatedInternalId: r.generated_internal_id ?? "",
     })),
-    totalRecords: results.length,
+    // C5 (spec §1.4, §3.3): the OLD value was `results.length` — the PAGE SIZE,
+    // not the true count. A recipient with 400 awards but a 15-row page
+    // reported `totalRecords:15` (an order-of-magnitude lie). Now the REAL
+    // upstream total (via spending_by_award_count), or null if that companion
+    // query failed — never the page length.
+    totalRecords: total,
   };
+  const pagination = awardPagination(
+    0,
+    limit,
+    results.length,
+    total,
+    json.page_metadata?.hasNext ?? false,
+  );
+  const notes = [
+    "Set-aside type is NOT available from the spending_by_award search endpoint (filter-only) — call usas_get_award_detail per award for setAsideType/setAsideDescription.",
+  ];
+  // W3-7: extra matches beyond this ranked page are not page-reachable (nextOffset null).
+  if (pagination.hasMore) {
+    notes.push(
+      `Showing ${limit} of ${total ?? "more"} matching awards for this recipient. These extra matches are NOT page-reachable — this tool returns one ranked page with no offset input (nextOffset is null). Raise limit (up to 50) or narrow the filters to see more.`,
+    );
+  }
+  return withMeta(data, {
+    source: SPENDING_BY_AWARD_SOURCE,
+    keylessMode: true,
+    returned: results.length,
+    totalAvailable: total,
+    pagination,
+    filtersApplied: filtersAppliedFromFilters(filters),
+    filtersDropped: [],
+    fieldsUnavailable: ["setAside", "setAsideDescription"],
+    notes,
+  });
 }
 
 // ─── Subaward enumeration ─────────────────────────────────────────
@@ -248,47 +688,140 @@ export async function searchSubawards(args: {
       "Sub-Award Recipient"?: string;
       "Sub-Award Amount"?: number;
       "Sub-Award Date"?: string;
+      NAICS?: { code?: string; description?: string };
       prime_award_generated_internal_id?: string;
     }[];
+    page_metadata?: { hasNext?: boolean };
   };
-  const json = await postUsas<Resp>("search/spending_by_award", {
-    filters,
-    fields: [
-      "Sub-Award ID",
-      "Sub-Award Recipient",
-      "Sub-Award Amount",
-      "Sub-Award Date",
-      "Sub-Award NAICS",
-    ],
-    limit: args.limit ?? 15,
-    page: 1,
-    subawards: true,
-  });
-  return {
-    subawards: (json.results ?? []).map((r) => ({
+  const limit = args.limit ?? 15;
+  // A3 (spec §1.2, §3.2): the OLD code requested "Sub-Award NAICS", which is
+  // NOT a valid field name on this endpoint — `spending_by_award` echoes an
+  // unknown field back as `null` (verified 2026-07-03), so the arg looked
+  // honored but silently returned nothing. The valid field for subaward NAICS
+  // is "NAICS" (returns {code,description} — the PRIME award's NAICS, which is
+  // what USAspending exposes on subaward rows). Swap to it and map it.
+  const [json, total] = await Promise.all([
+    postUsas<Resp>("search/spending_by_award", {
+      filters,
+      fields: [
+        "Sub-Award ID",
+        "Sub-Award Recipient",
+        "Sub-Award Amount",
+        "Sub-Award Date",
+        "NAICS",
+      ],
+      limit,
+      page: 1,
+      subawards: true,
+    }),
+    awardCount(filters, "subawards"),
+  ]);
+  const results = json.results ?? [];
+  const data = {
+    subawards: results.map((r) => ({
       subAwardId: r["Sub-Award ID"] ?? "",
-      subRecipient: r["Sub-Award Recipient"] ?? "(name redacted)",
-      amount: r["Sub-Award Amount"] ?? 0,
+      // minor m2 (W3-1 honesty): an ABSENT Sub-Award Recipient → null, NOT a
+      // fabricated "(name redacted)". The old sentinel asserted a specific PRIVACY
+      // reason on ANY nullish value (schema gap / null echo / genuine redaction
+      // alike) — internally inconsistent with the null-never-fabricate discipline
+      // this same function applies to `amount` below. Honest null; the caller
+      // reads absence, not an invented redaction cause.
+      subRecipient: r["Sub-Award Recipient"] ?? null,
+      // F2 (P3 null-never-0): an ABSENT Sub-Award Amount → null, NEVER a
+      // fabricated $0. A genuine 0 still survives (`??` fires only on null).
+      amount: r["Sub-Award Amount"] ?? null,
       actionDate: r["Sub-Award Date"] ?? "",
+      // A3: prime-award NAICS on the subaward row (the only NAICS the endpoint
+      // exposes for subawards). null when the row genuinely lacks it.
+      naicsCode: r.NAICS?.code,
+      naicsDescription: r.NAICS?.description,
       primeAwardId: r.prime_award_generated_internal_id ?? "",
     })),
   };
+  const pagination = awardPagination(
+    0,
+    limit,
+    results.length,
+    total,
+    json.page_metadata?.hasNext ?? false,
+  );
+  const notes = [
+    "The `naicsCode`/`naicsDescription` on each subaward is the PRIME award's NAICS (USAspending does not expose a distinct sub-award NAICS on this endpoint). A subaward-specific NAICS is not available keyless.",
+  ];
+  // W3-7: extra subawards beyond this ranked page are not page-reachable (nextOffset null).
+  if (pagination.hasMore) {
+    notes.push(
+      `Showing ${limit} of ${total ?? "more"} matching subawards. These extra matches are NOT page-reachable — this tool returns one ranked page with no offset input (nextOffset is null). Raise limit (up to 50) or narrow the filters to see more.`,
+    );
+  }
+  return withMeta(data, {
+    source: SPENDING_BY_AWARD_SOURCE,
+    keylessMode: true,
+    returned: results.length,
+    totalAvailable: total,
+    pagination,
+    filtersApplied: filtersAppliedFromFilters(filters),
+    filtersDropped: [],
+    fieldsUnavailable: [],
+    notes,
+  });
 }
 
 // ─── Per-award detail ─────────────────────────────────────────────
 
+/**
+ * Parse USAspending's `number_of_offers_received` to a real number|null.
+ *
+ * LIVE-VERIFIED 2026-07-03: this field is a STRING on competed awards (e.g.
+ * "1", "2", "3") but is genuinely `null` on some delivery orders — so the
+ * previous typing/mapping (`number_of_offers_received?: string`, passed
+ * through raw) exposed a string where a numeric compare was expected. Coerce
+ * to a number; return null for null/empty/non-numeric so a missing value is
+ * an honest "unknown", never 0 or "".
+ */
+function parseOffers(raw: unknown): number | null {
+  if (raw === null || raw === undefined) return null;
+  const n = typeof raw === "number" ? raw : Number.parseInt(String(raw), 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** A parent-award / IDV linkage as returned on awards/{id} (all optional). */
+export type AwardParentIdv = {
+  piid: string | null;
+  generatedUniqueAwardId: string | null;
+  idvTypeDescription: string | null;
+  multipleOrSingleAwardDescription: string | null;
+};
+
 export async function getAwardDetail(generatedInternalId: string) {
   try {
     const r = await fetch(
       `${USAS}/awards/${encodeURIComponent(generatedInternalId)}/`,
       { signal: AbortSignal.timeout(10_000) },
     );
-    if (!r.ok) return null;
+    // 404 = the id genuinely doesn't resolve → null (a real "not found").
+    // 429/5xx = a RETRYABLE upstream fault, NOT a missing award → throw a
+    // classified error so callers never mislabel an outage as not_found.
+    if (r.status === 404) return null;
+    if (!r.ok) {
+      throw new ToolErrorCarrier({
+        kind: r.status === 429 ? "rate_limited" : "upstream_unavailable",
+        message: `usaspending awards/{id} returned ${r.status}`,
+        retryable: true,
+        upstreamStatus: r.status,
+        upstreamEndpoint: `awards/${generatedInternalId}`,
+      });
+    }
     type Resp = {
       piid?: string;
       description?: string;
       total_obligation?: number;
       base_and_all_options?: number;
+      base_exercised_options?: number;
+      subaward_count?: number;
+      type?: string;
+      type_description?: string;
+      category?: string;
       period_of_performance?: {
         start_date?: string;
         end_date?: string;
@@ -298,10 +831,20 @@ export async function getAwardDetail(generatedInternalId: string) {
         type_set_aside?: string;
         type_set_aside_description?: string;
         extent_competed?: string;
-        number_of_offers_received?: string;
+        extent_competed_description?: string;
+        number_of_offers_received?: string | number | null;
         naics?: string;
         naics_description?: string;
+        product_or_service_code?: string;
+        product_or_service_description?: string;
       };
+      psc_hierarchy?: { base_code?: { code?: string; description?: string } };
+      parent_award?: {
+        piid?: string;
+        generated_unique_award_id?: string;
+        idv_type_description?: string;
+        multiple_or_single_aw_desc?: string;
+      } | null;
       awarding_agency?: {
         toptier_agency?: { name?: string };
         subtier_agency?: { name?: string };
@@ -310,11 +853,43 @@ export async function getAwardDetail(generatedInternalId: string) {
     };
     const json = (await r.json()) as Resp;
     const ltc = json.latest_transaction_contract_data ?? {};
+    // PSC: prefer the ltc code, fall back to the psc_hierarchy base code (the
+    // ltc-level product_or_service_code is often absent while the hierarchy
+    // carries it — LIVE-VERIFIED 2026-07-03).
+    const pscCode =
+      ltc.product_or_service_code ?? json.psc_hierarchy?.base_code?.code ?? null;
+    const pscDescription =
+      ltc.product_or_service_description ??
+      json.psc_hierarchy?.base_code?.description ??
+      null;
+    const parent = json.parent_award ?? null;
+    const parentIdv: AwardParentIdv | null = parent
+      ? {
+          piid: parent.piid ?? null,
+          generatedUniqueAwardId: parent.generated_unique_award_id ?? null,
+          idvTypeDescription: parent.idv_type_description ?? null,
+          multipleOrSingleAwardDescription:
+            parent.multiple_or_single_aw_desc ?? null,
+        }
+      : null;
     return {
       awardId: json.piid ?? "",
-      recipient: json.recipient?.recipient_name ?? "",
-      totalObligation: json.total_obligation ?? 0,
-      baseAndAllOptions: json.base_and_all_options ?? 0,
+      // Identity field is null (UNKNOWN) when absent OR blank — never "" (which
+      // reads as "no recipient"). `|| null` catches both a missing recipient_name
+      // and a present-but-empty one. Consistent with analyzeIncumbent's incumbent
+      // field (#43) and the money fields below.
+      recipient: json.recipient?.recipient_name || null,
+      // Money fields are null (UNKNOWN) when USAspending omits them — never 0.
+      // A null base_and_all_options is common and legitimate (IDVs/BPAs carry
+      // the ceiling at the vehicle level, grants/loans have no ceiling concept);
+      // rendering it as 0 would read as "a $0 ceiling", a data-absence-as-present
+      // masquerade. Consistent with baseExercisedOptions, which already nulls.
+      totalObligation: json.total_obligation ?? null,
+      baseAndAllOptions: json.base_and_all_options ?? null,
+      baseExercisedOptions: json.base_exercised_options ?? null,
+      subawardCount: json.subaward_count ?? null,
+      // Award type + human description (e.g. "C" / "DELIVERY ORDER").
+      contractAwardType: json.type_description ?? json.type ?? null,
       periodOfPerformance: {
         startDate: json.period_of_performance?.start_date ?? null,
         endDate: json.period_of_performance?.end_date ?? null,
@@ -324,87 +899,751 @@ export async function getAwardDetail(generatedInternalId: string) {
       setAsideType: ltc.type_set_aside,
       setAsideDescription: ltc.type_set_aside_description,
       competitionExtent: ltc.extent_competed,
-      numberOfOffers: ltc.number_of_offers_received,
+      competitionExtentDescription: ltc.extent_competed_description ?? null,
+      // E-type-hygiene fix: number_of_offers_received is now a parsed
+      // number|null, not the raw string it arrives as.
+      numberOfOffers: parseOffers(ltc.number_of_offers_received),
       awardingAgency: json.awarding_agency?.toptier_agency?.name,
       awardingSubAgency: json.awarding_agency?.subtier_agency?.name,
       naicsCode: ltc.naics,
       naicsDescription: ltc.naics_description,
+      pscCode,
+      pscDescription,
+      parentIdv,
     };
+  } catch (e) {
+    // A classified upstream error (429/5xx) must propagate so the caller can
+    // retry and never mislabel it as not_found. A network/timeout/parse fault
+    // is likewise retryable — surface it, don't collapse it to a false null.
+    if (e instanceof ToolErrorCarrier) throw e;
+    throw new ToolErrorCarrier({
+      kind: "upstream_unavailable",
+      message: `usaspending awards/{id} fetch failed: ${e instanceof Error ? e.message : String(e)}`,
+      retryable: true,
+      upstreamEndpoint: `awards/${generatedInternalId}`,
+    });
+  }
+}
+
+// ─── Per-award transaction (modification) count ───────────────────
+
+/**
+ * Bounded modification-count for a single award via the keyless
+ * `POST transactions/` endpoint (`{award_id, limit:100, page:1}`).
+ *
+ * WHY bounded, not paged: this endpoint's `page_metadata` carries only
+ * `hasNext` — there is NO grand total (LIVE-VERIFIED 2026-07-03). So we read
+ * ONE 100-row page and return its length. If `hasNext` is true the true count
+ * exceeds 100, so we return `{ count: <len>, atLeast: true }` — a LOWER BOUND,
+ * never an unbounded fan-out. `modification_number` on the latest transaction
+ * is an unreliable proxy (it was `undefined` on the test award) and is not
+ * used. Returns `null` count on failure so the caller degrades honestly.
+ */
+async function transactionsCount(
+  generatedInternalId: string,
+): Promise<{ count: number | null; atLeast: boolean }> {
+  try {
+    type Resp = {
+      results?: unknown[];
+      page_metadata?: { hasNext?: boolean };
+    };
+    const json = await postUsas<Resp>("transactions/", {
+      award_id: generatedInternalId,
+      limit: 100,
+      page: 1,
+    });
+    const rows = json.results ?? [];
+    return { count: rows.length, atLeast: json.page_metadata?.hasNext === true };
   } catch {
-    return null;
+    return { count: null, atLeast: false };
   }
 }
 
+// ─── Per-award incumbent + public recompete-pressure analysis ─────
+
+const ANALYZE_INCUMBENT_SOURCE =
+  "usaspending.gov awards/{id} + transactions + spending_by_award (keyless)";
+
+/**
+ * The public fields that are decision-relevant for a recompete but are NOT
+ * in any keyless (or any public) source — declared in `_meta.fieldsUnavailable`
+ * so the AI hedges instead of inventing a vulnerability score.
+ */
+const ANALYZE_FIELDS_UNAVAILABLE = [
+  "past_performance_cpars",
+  "protest_history",
+  "option_exercise_intent",
+];
+
+/**
+ * Per-award incumbent + PUBLIC recompete-pressure analysis (design doc 04
+ * §5.2). Given ONE award (`generatedInternalId`) it assembles, from keyless
+ * data only:
+ *   - the incumbent identity + the award's agency/NAICS/PSC/vehicle,
+ *   - PUBLIC recompete-pressure SIGNALS (obligated-vs-ceiling consumption, mod
+ *     count, competition extent + number of offers, set-aside, days to the
+ *     current PoP end, and option-extendable days), and
+ *   - (optionally) the incumbent's other awards in the same agency.
+ *
+ * DESIGN — bounded & keyless, NO N+1 fan-out:
+ *   1 `awards/{id}` detail  +  1 `transactions/` page (mod count, capped at
+ *   100 → lower bound)  +  (optional) 1 `searchAwardsByRecipient` call. That is
+ *   at most 3 upstream calls regardless of award size.
+ *
+ * HONEST CEILING (mandatory): it emits INDIVIDUAL public signals + `pressureHints`
+ * (e.g. "single_offer", "ceiling_nearly_exhausted", "hard_stop_no_options") that
+ * are HINTS, never a score. It NEVER emits a composite "vulnerability score" —
+ * the most decision-relevant input (past performance / CPARS), protest history,
+ * and the incumbent's option-exercise intent are not public, and are declared
+ * in `_meta.fieldsUnavailable`. A not-found award raises a structured not_found
+ * error (never `{ok:true, data:null}`).
+ */
+export async function analyzeIncumbent(args: {
+  generatedInternalId: string;
+  includeOtherAwards?: boolean;
+  otherAwardsLimit?: number;
+}) {
+  const includeOtherAwards = args.includeOtherAwards ?? true;
+  const otherAwardsLimit = Math.min(
+    50,
+    Math.max(1, Math.floor(args.otherAwardsLimit ?? 15)),
+  );
+
+  // --- 1. Award detail (throws not_found if the id doesn't resolve) ------
+  const detail = await getAwardDetail(args.generatedInternalId);
+  if (!detail) {
+    throw new ToolErrorCarrier({
+      kind: "not_found",
+      message: `No award found for generatedInternalId '${args.generatedInternalId}' on usaspending.gov awards/{id}. Resolve a valid id via usas_search_individual_awards or usas_search_awards_by_recipient (each result carries a generatedInternalId).`,
+      retryable: false,
+      upstreamEndpoint: `awards/${args.generatedInternalId}`,
+    });
+  }
+
+  const nowMs = Date.now();
+  let enrichmentCalls = 1; // the detail fetch
+
+  // --- 2. Bounded mod count (1 transactions page) -----------------------
+  const mods = await transactionsCount(args.generatedInternalId);
+  enrichmentCalls++;
+
+  // --- 3. Signals (all PUBLIC, individual — never combined into a score) -
+  const obligated = detail.totalObligation;
+  const ceiling = detail.baseAndAllOptions;
+  // pctConsumed only when BOTH obligated is a number AND the ceiling is a usable
+  // positive number; a null/absent obligated or a 0/absent/negative ceiling → null
+  // (never a divide-by-zero, a null-coerced-to-0 ratio, or a nonsensical negative).
+  const pctConsumed =
+    typeof obligated === "number" && typeof ceiling === "number" && ceiling > 0
+      ? obligated / ceiling
+      : null;
+
+  const currentEndDate = detail.periodOfPerformance.endDate;
+  const potentialEndDate = detail.periodOfPerformance.potentialEndDate;
+  const daysUntilCurrentEnd = daysUntil(currentEndDate, nowMs);
+  const daysUntilPotentialEnd = daysUntil(potentialEndDate, nowMs);
+  // extendableDays = runway the unexercised options would add. Null when
+  // either end date is unusable.
+  const extendableDays =
+    daysUntilPotentialEnd !== null && daysUntilCurrentEnd !== null
+      ? daysUntilPotentialEnd - daysUntilCurrentEnd
+      : null;
+
+  const numberOfOffers = detail.numberOfOffers; // already number|null
+
+  const signals = {
+    obligatedVsCeiling: {
+      obligated,
+      baseAndAllOptions: ceiling,
+      baseExercisedOptions: detail.baseExercisedOptions,
+      pctConsumed,
+    },
+    modCount: mods.count,
+    modCountAtLeast: mods.atLeast,
+    setAside: detail.setAsideType ?? null,
+    setAsideDescription: detail.setAsideDescription ?? null,
+    extentCompeted: detail.competitionExtent ?? null,
+    extentCompetedDescription: detail.competitionExtentDescription ?? null,
+    numberOfOffers,
+    currentEndDate,
+    potentialEndDate,
+    extendableDays,
+    daysUntilCurrentEnd,
+    vehicle: {
+      contractAwardType: detail.contractAwardType,
+      parentIdvPiid: detail.parentIdv?.piid ?? null,
+      idvType: detail.parentIdv?.idvTypeDescription ?? null,
+      singleOrMultiple:
+        detail.parentIdv?.multipleOrSingleAwardDescription ?? null,
+    },
+  };
+
+  // --- pressureHints: individual PUBLIC flags — HINTS, never a score -----
+  const pressureHints: string[] = [];
+  if (numberOfOffers === 1) pressureHints.push("single_offer");
+  if (pctConsumed !== null && pctConsumed >= 0.9)
+    pressureHints.push("ceiling_nearly_exhausted");
+  if (extendableDays !== null && extendableDays <= 0)
+    pressureHints.push("hard_stop_no_options");
+
+  // --- 4. Incumbent's other awards in the same agency (1 bounded call) ---
+  let incumbentOtherAwards:
+    | Awaited<ReturnType<typeof searchAwardsByRecipient>>["data"]["awards"]
+    | undefined;
+  let otherAwardsFailed = false;
+  if (includeOtherAwards && detail.recipient) {
+    enrichmentCalls++; // count the attempt (whether or not it succeeds)
+    try {
+      const other = await searchAwardsByRecipient({
+        recipientName: detail.recipient,
+        agency: detail.awardingAgency,
+        naics: detail.naicsCode,
+        limit: otherAwardsLimit,
+      });
+      // Drop the award we're analyzing from its own "other awards" list.
+      incumbentOtherAwards = other.data.awards.filter(
+        (a) => a.generatedInternalId !== args.generatedInternalId,
+      );
+    } catch {
+      // Non-fatal, but MUST be disclosed: an empty list here means "the search
+      // failed", NOT "the incumbent has no other awards". (D1)
+      incumbentOtherAwards = [];
+      otherAwardsFailed = true;
+    }
+  }
+
+  // The award record carries no recipient_name → the incumbent identity is
+  // UNKNOWN. Two masquerades to avoid: (1) `incumbent: ""` reads as "none"
+  // rather than "unknown"; (2) with includeOtherAwards, the recipient search is
+  // SKIPPED (the `detail.recipient` guard above is falsy) so `incumbentOtherAwards`
+  // stays undefined → `?? []` emits an empty list that reads as "no other awards"
+  // when the search never ran. Same class as the D1 otherAwardsFailed disclosure.
+  const incumbentUnknown = !detail.recipient;
+
+  const data = {
+    award: {
+      awardId: detail.awardId,
+      incumbent: detail.recipient || null,
+      awardingAgency: detail.awardingAgency ?? null,
+      awardingSubAgency: detail.awardingSubAgency ?? null,
+      naicsCode: detail.naicsCode ?? null,
+      pscCode: detail.pscCode ?? null,
+      contractAwardType: detail.contractAwardType,
+      startDate: detail.periodOfPerformance.startDate,
+      currentEndDate,
+      potentialEndDate,
+    },
+    signals,
+    pressureHints,
+    ...(includeOtherAwards ? { incumbentOtherAwards: incumbentOtherAwards ?? [] } : {}),
+  };
+
+  // --- Truthful _meta ---------------------------------------------------
+  // The offers value being null means single_offer could not be evaluated —
+  // declare number_of_offers_received unavailable so the AI knows.
+  const fieldsUnavailable = [...ANALYZE_FIELDS_UNAVAILABLE];
+  if (numberOfOffers === null) {
+    fieldsUnavailable.push("number_of_offers_received");
+  }
+  if (incumbentUnknown) {
+    fieldsUnavailable.push("recipient_name");
+  }
+  // Null money fields are UNKNOWN, not $0 — disclose so an AI never cites a
+  // fabricated zero (the values themselves are now null in obligatedVsCeiling).
+  if (obligated === null) fieldsUnavailable.push("total_obligation");
+  if (ceiling === null) fieldsUnavailable.push("base_and_all_options");
+
+  // List ONLY the calls actually attempted — never assert a recipient search
+  // that failed or was skipped (D1). enrichmentCalls stays in lockstep with
+  // this list: detail + transactions are always attempted; the recipient call
+  // is attempted iff includeOtherAwards && a recipient name exists.
+  const callList = ["awards/{id} detail", "1 transactions page"];
+  if (includeOtherAwards && detail.recipient) callList.push("1 recipient search");
+  const transactionsFailed = mods.count === null;
+
+  const notes: string[] = [
+    "HONEST CEILING: PUBLIC signals only; no composite vulnerability score. Past-performance/CPARS ratings, protest history, and the incumbent's option-exercise intent are NOT public — judge the recompete with off-platform intelligence.",
+    `Bounded keyless design: ${enrichmentCalls} upstream call(s) (${callList.join(" + ")}); no per-record fan-out.`,
+  ];
+  if (mods.atLeast) {
+    notes.push(
+      `modCount is a LOWER BOUND: this award has more than 100 transactions (the transactions endpoint reports no total, so only one 100-row page is read). modCountAtLeast is true.`,
+    );
+  }
+  if (transactionsFailed) {
+    notes.push(
+      "modCount is null because the transactions call FAILED (not because the award has no modifications) — the modification count is unknown, not zero.",
+    );
+  }
+  if (otherAwardsFailed) {
+    notes.push(
+      "incumbentOtherAwards could not be retrieved (the recipient search FAILED) and is shown as an EMPTY list — this is NOT a confirmation that the incumbent has no other awards.",
+    );
+  }
+  if (incumbentUnknown) {
+    notes.push(
+      "The award record carries no recipient_name — the incumbent identity is UNKNOWN (returned as null), NOT 'none'. Incumbent-specific analysis (identity, other awards) cannot be performed on this record.",
+    );
+    if (includeOtherAwards) {
+      notes.push(
+        "incumbentOtherAwards is an EMPTY list because there is no recipient name to search by — the recipient search was SKIPPED, not run and found empty. This is NOT a confirmation that the incumbent has no other awards.",
+      );
+    }
+  }
+  if (pctConsumed === null) {
+    notes.push(
+      "obligatedVsCeiling.pctConsumed is null because the obligated amount or the award's ceiling (base_and_all_options) is absent (null), zero, or a negative data-entry value — consumption cannot be computed.",
+    );
+  }
+  if (numberOfOffers === null) {
+    notes.push(
+      "number_of_offers_received is null on this award, so the 'single_offer' hint could not be evaluated (absence of the hint does NOT imply competition).",
+    );
+  }
+
+  // A failed secondary enrichment means this is NOT the complete picture →
+  // force complete:false so an AI never reads partial data as complete (D1/D2).
+  // A blank recipient with includeOtherAwards is the same class: the emitted
+  // empty incumbentOtherAwards would otherwise read as complete.
+  const degraded =
+    transactionsFailed ||
+    otherAwardsFailed ||
+    (includeOtherAwards && incumbentUnknown);
+
+  return withMeta(data, {
+    source: ANALYZE_INCUMBENT_SOURCE,
+    keylessMode: true,
+    complete: degraded ? false : undefined,
+    returned: 1,
+    totalAvailable: 1,
+    truncated: false,
+    filtersApplied: [],
+    filtersDropped: [],
+    fieldsUnavailable,
+    enrichedCount: enrichmentCalls,
+    notes,
+  });
+}
+
 // ─── Recompete radar ──────────────────────────────────────────────
 
+/**
+ * Set-aside → USAspending `set_aside_type_codes` filter code. The
+ * `spending_by_award` endpoint DOES honor `set_aside_type_codes` server-side
+ * (LIVE-VERIFIED 2026-07-03: VA×541512 base 696 → SDVOSBC 182, SBA 19, WOSB 1
+ * — genuine reductions; the wrong keys `type_set_aside`/`set_aside` are
+ * silently IGNORED, returning the unfiltered 696). Set-aside is a FILTER only,
+ * never a requestable output field (verified: it comes back absent). So we
+ * filter by it but cannot read a per-row set-aside VALUE from search — that
+ * lives in usas_get_award_detail.
+ */
+const SET_ASIDE_CODES = new Set([
+  "SBA",
+  "8A",
+  "HZS",
+  "SDVOSBC",
+  "WOSB",
+  "EDWOSB",
+  "VSA",
+  "VSS",
+]);
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * A `spending_by_award` row as returned when we request the recompete field
+ * set. Every value is optional/nullable — USAspending echoes unknown fields
+ * back as `null`, and PoP end dates are legitimately null on some rows.
+ */
+type RecompeteRow = {
+  "Award ID"?: string | null;
+  "Recipient Name"?: string | null;
+  "Award Amount"?: number | null;
+  "Awarding Agency"?: string | null;
+  "Awarding Sub Agency"?: string | null;
+  "Start Date"?: string | null;
+  "End Date"?: string | null;
+  NAICS?: { code?: string; description?: string } | null;
+  PSC?: { code?: string; description?: string } | null;
+  "Contract Award Type"?: string | null;
+  "Last Modified Date"?: string | null;
+  "Period of Performance Potential End Date"?: string | null;
+  generated_internal_id?: string | null;
+};
+
+/**
+ * Parse a PoP end date to "whole days from today" (UTC midnight). Returns
+ * `null` for null/empty/unparseable/absurd values so the caller can COUNT the
+ * row (never silently drop it) and treat it as out-of-window. Guards against
+ * the far-future data-entry errors USAspending carries (e.g. year 2108).
+ */
+function daysUntil(dateStr: string | null | undefined, nowMs: number): number | null {
+  if (!dateStr) return null;
+  const t = new Date(dateStr).getTime();
+  if (Number.isNaN(t)) return null;
+  const year = new Date(t).getUTCFullYear();
+  // Sanity clamp: PoP end dates outside [1990, 2200] are data errors.
+  if (year < 1990 || year > 2200) return null;
+  return Math.ceil((t - nowMs) / MS_PER_DAY);
+}
+
+/** UTC "today minus N years" as YYYY-MM-DD, for the action_date lower bound. */
+function isoYearsAgo(nowMs: number, years: number): string {
+  const d = new Date(nowMs);
+  d.setUTCFullYear(d.getUTCFullYear() - years);
+  return d.toISOString().slice(0, 10);
+}
+
+const RECOMPETE_SOURCE =
+  "usaspending.gov spending_by_award (keyless)";
+
+const RECOMPETE_FIELDS_UNAVAILABLE = [
+  "past_performance_cpars",
+  "protest_history",
+  "option_exercise_intent",
+];
+
+/**
+ * Recompete radar — federal contracts whose current period of performance
+ * ends inside a window around today, so you can see what's coming up for
+ * recompete. Replaces the broken `searchExpiringContracts` internals.
+ *
+ * MECHANISM (LIVE-VERIFIED 2026-07-03 across VA×541512 and DoD×541330):
+ * `spending_by_award` returns the current PoP end date directly under the
+ * field ALIAS `"End Date"` (the canonical string
+ * "Period of Performance Current End Date" is NOT a recognized field — it
+ * comes back always null, and is not in the sort mappings → HTTP 400 if you
+ * sort by it). Gold-standard confirmed: search `"End Date"` ===
+ * `awards/{generated_internal_id}`.period_of_performance.end_date.
+ *
+ * We CANNOT filter by PoP end date server-side (`time_period.date_type` only
+ * supports action_date/date_signed/last_modified_date/new_awards_only). So:
+ *   1. server-side SORT by `"End Date"` DESC (the alias — the only PoP-end
+ *      value in the sort mappings),
+ *   2. an action_date `time_period` lower bound (LOAD-BEARING: prunes inactive
+ *      records and much of the far-future data-entry garbage so DESC reaches
+ *      the window sooner),
+ *   3. a CLIENT-SIDE window filter with pagination + a safe early-stop (DESC ⇒
+ *      once a row is earlier than the window start, every later row is earlier
+ *      too), bounded by `scanBudgetPages`.
+ *
+ * TRUTHFULNESS: rows with a null `"End Date"` are COUNTED (`missingEndDate`),
+ * never silently dropped. If the scan budget is exhausted before the early-stop
+ * fires, `scanTruncated` is set and `totalAvailable` becomes null (the returned
+ * set is a lower bound, not the complete window). This tool emits PUBLIC
+ * signals only — it never fabricates a composite "vulnerability" score;
+ * past-performance/CPARS, protest history, and option-exercise intent are not
+ * public and are declared in `_meta.fieldsUnavailable`.
+ */
+export async function searchRecompetes(args: {
+  agency?: string;
+  naics?: string;
+  pscCodes?: string[];
+  setAside?: string;
+  windowStartDays?: number;
+  windowEndDays?: number;
+  minAwardValue?: number;
+  includePotentialEnd?: boolean;
+  actionDateLookbackYears?: number;
+  page?: number;
+  pageSize?: number;
+  scanBudgetPages?: number;
+}) {
+  const nowMs = Date.now();
+  const windowStartDays = args.windowStartDays ?? -90;
+  const windowEndDays = args.windowEndDays ?? 548; // ~18 months
+  const minAwardValue = args.minAwardValue ?? 0;
+  const includePotentialEnd = args.includePotentialEnd ?? false;
+  const actionDateLookbackYears = args.actionDateLookbackYears ?? 3;
+  const page = Math.max(1, Math.floor(args.page ?? 1));
+  const pageSize = Math.min(100, Math.max(1, Math.floor(args.pageSize ?? 25)));
+  const scanBudgetPages = Math.min(20, Math.max(1, Math.floor(args.scanBudgetPages ?? 8)));
+
+  // --- Build filters (only what we can send truthfully) -----------------
+  const filters: UsasFilters = { award_type_codes: ["A", "B", "C", "D"] };
+  const filtersApplied: string[] = ["awardType(contracts A/B/C/D)"];
+  const filtersDropped: string[] = [];
+  if (args.agency) {
+    filters.agencies = [{ type: "awarding", tier: "toptier", name: args.agency }];
+    filtersApplied.push("agency");
+  }
+  if (args.naics) {
+    filters.naics_codes = [args.naics];
+    filtersApplied.push("naics");
+  }
+  if (args.pscCodes?.length) {
+    filters.psc_codes = args.pscCodes;
+    filtersApplied.push("pscCodes");
+  }
+  // Set-aside: `set_aside_type_codes` is honored server-side (verified). Only
+  // send a code we know the endpoint recognizes; otherwise record it dropped.
+  if (args.setAside) {
+    if (SET_ASIDE_CODES.has(args.setAside)) {
+      filters.set_aside_type_codes = [args.setAside];
+      filtersApplied.push("setAside");
+    } else {
+      filtersDropped.push("setAside");
+    }
+  }
+  // action_date lower bound — the default date_type is action_date, so no
+  // explicit date_type is needed (and passing one is optional).
+  const lookbackStart = isoYearsAgo(nowMs, actionDateLookbackYears);
+  const todayIso = new Date(nowMs).toISOString().slice(0, 10);
+  filters.time_period = [{ start_date: lookbackStart, end_date: todayIso }];
+  filtersApplied.push(`actionDateLookback(${actionDateLookbackYears}y)`);
+
+  const fields = [
+    "Award ID",
+    "Recipient Name",
+    "Award Amount",
+    "Awarding Agency",
+    "Awarding Sub Agency",
+    "Start Date",
+    "End Date",
+    "NAICS",
+    "PSC",
+    "Contract Award Type",
+    "Last Modified Date",
+    "generated_internal_id",
+  ];
+  if (includePotentialEnd) {
+    fields.push("Period of Performance Potential End Date");
+  }
+
+  type SearchResp = {
+    results?: RecompeteRow[];
+    page_metadata?: { hasNext?: boolean; page?: number };
+  };
+
+  // --- Scan pages (DESC by End Date) with early-stop + budget ----------
+  type Shaped = {
+    awardId: string;
+    generatedInternalId: string;
+    incumbent: string;
+    amount: number;
+    currentEndDate: string;
+    daysUntilCurrentEnd: number;
+    potentialEndDate?: string | null;
+    extendableDays?: number | null;
+    awardingAgency: string;
+    awardingSubAgency: string | null;
+    naicsCode: string | null;
+    pscCode: string | null;
+    contractAwardType: string | null;
+    setAsideDescription: string | null;
+    startDate: string | null;
+    description: string | null;
+  };
+
+  const results: Shaped[] = [];
+  let scanned = 0;
+  let missingEndDate = 0;
+  let pastWindow = false;
+  let scanTruncated = false;
+
+  for (let p = 1; p <= scanBudgetPages; p++) {
+    const resp = await postUsas<SearchResp>("search/spending_by_award", {
+      filters,
+      fields,
+      sort: "End Date",
+      order: "desc",
+      limit: 100,
+      page: p,
+      subawards: false,
+    });
+    const rows = resp.results ?? [];
+    for (const row of rows) {
+      scanned++;
+      const end = row["End Date"] ?? null;
+      const d = daysUntil(end, nowMs);
+      if (d === null) {
+        // Null/unparseable/absurd end date — COUNT it, never silently drop.
+        missingEndDate++;
+        continue;
+      }
+      if (d > windowEndDays) continue; // far future (incl. data errors) → skip
+      if (d < windowStartDays) {
+        // DESC ⇒ everything after this row is earlier ⇒ safe to stop.
+        pastWindow = true;
+        break;
+      }
+      const amount = row["Award Amount"] ?? 0;
+      if (amount < minAwardValue) continue;
+      const potentialEnd = includePotentialEnd
+        ? row["Period of Performance Potential End Date"] ?? null
+        : undefined;
+      let extendableDays: number | null | undefined;
+      if (includePotentialEnd) {
+        const pd = daysUntil(potentialEnd ?? null, nowMs);
+        extendableDays = pd === null ? null : pd - d;
+      }
+      results.push({
+        awardId: row["Award ID"] ?? "",
+        generatedInternalId: row.generated_internal_id ?? "",
+        incumbent: row["Recipient Name"] ?? "",
+        amount,
+        currentEndDate: end as string,
+        daysUntilCurrentEnd: d,
+        ...(includePotentialEnd
+          ? { potentialEndDate: potentialEnd ?? null, extendableDays }
+          : {}),
+        awardingAgency: row["Awarding Agency"] ?? "",
+        awardingSubAgency: row["Awarding Sub Agency"] ?? null,
+        naicsCode: row.NAICS?.code ?? null,
+        pscCode: row.PSC?.code ?? null,
+        contractAwardType: row["Contract Award Type"] ?? null,
+        // Set-aside VALUE is not a search output field (filter-only) → null
+        // here; the caller reads it per-award via usas_get_award_detail.
+        setAsideDescription: null,
+        startDate: row["Start Date"] ?? null,
+        description: null,
+      });
+    }
+    if (pastWindow) break;
+    if (!resp.page_metadata?.hasNext) break;
+    if (p === scanBudgetPages && !pastWindow) scanTruncated = true;
+  }
+
+  // Deterministic order: current end date ascending (soonest recompete first),
+  // tiebreak by descending amount then awardId so paging is stable.
+  results.sort((a, b) => {
+    if (a.daysUntilCurrentEnd !== b.daysUntilCurrentEnd)
+      return a.daysUntilCurrentEnd - b.daysUntilCurrentEnd;
+    if (b.amount !== a.amount) return b.amount - a.amount;
+    return a.awardId.localeCompare(b.awardId);
+  });
+
+  const totalInWindow = results.length; // EXACT iff not scanTruncated
+  const startIdx = (page - 1) * pageSize;
+  const pageSlice = results.slice(startIdx, startIdx + pageSize);
+
+  // --- Truthful _meta ---------------------------------------------------
+  // totalAvailable is a REAL count only when we scanned the whole window
+  // (early-stop fired). If the scan budget truncated, it is unknown → null,
+  // and the returned set is a lower bound.
+  const totalAvailable = scanTruncated ? null : totalInWindow;
+  const nextOffset = startIdx + pageSize;
+  const hasMore = scanTruncated
+    ? true // more may exist beyond the scanned pages
+    : nextOffset < totalInWindow;
+  const truncated = hasMore || scanTruncated;
+
+  const notes: string[] = [
+    `Completeness boundary: only contracts with a recorded action in the last ${actionDateLookbackYears} year(s) are included (an action_date lower bound is required to make the End-Date sort reach the window; contracts with no action in that span are not returned).`,
+    "Recompete window is applied client-side on the current period-of-performance END date; the API cannot filter by PoP end date server-side, so results are sorted by End Date (desc) and windowed here.",
+    "HONEST CEILING: this tool emits PUBLIC signals only. Past-performance/CPARS ratings, protest history, and the incumbent's option-exercise intent are NOT public — it never emits a composite 'recompete vulnerability' score. Judge each row with off-platform intelligence.",
+  ];
+  if (missingEndDate > 0) {
+    notes.push(
+      `${missingEndDate} scanned award(s) had no usable current PoP end date and were counted but excluded from the window (never silently dropped).`,
+    );
+  }
+  if (scanTruncated) {
+    notes.push(
+      `Scan budget of ${scanBudgetPages} page(s) (${scanned} awards) was exhausted before reaching the end of the window, so totalAvailable is unknown (null) and the returned recompetes are a LOWER BOUND. This agency×NAICS slice has a very large tail of long-duration/far-future contracts — narrow it (add pscCodes, a higher minAwardValue, a set-aside, or a tighter agency/sub-agency) or raise scanBudgetPages to get an exact window count.`,
+    );
+  }
+  if (filtersDropped.includes("setAside")) {
+    notes.push(
+      `The requested set-aside code is not a recognized USAspending set_aside_type_code and was NOT applied (results are unfiltered on set-aside). Valid codes: ${[...SET_ASIDE_CODES].join(", ")}.`,
+    );
+  }
+
+  const data = {
+    recompetes: pageSlice,
+    page,
+    pageSize,
+  };
+
+  return withMeta(data, {
+    source: RECOMPETE_SOURCE,
+    keylessMode: true,
+    returned: pageSlice.length,
+    totalAvailable,
+    truncated,
+    pagination: {
+      offset: startIdx,
+      limit: pageSize,
+      nextOffset: hasMore ? nextOffset : null,
+      hasMore,
+    },
+    filtersApplied,
+    filtersDropped,
+    fieldsUnavailable: [
+      ...RECOMPETE_FIELDS_UNAVAILABLE,
+      "setAsideDescription(search-omits; use usas_get_award_detail)",
+    ],
+    notes,
+  });
+}
+
+/**
+ * DEPRECATED alias — kept working so existing callers of
+ * `usas_search_expiring_contracts` don't break. Maps the old params onto
+ * `searchRecompetes` and re-shapes the output to the legacy `{ contracts,
+ * searchedCount }` keys the smoke/edge tests assert on. Prefer
+ * `usas_search_recompetes`.
+ */
 export async function searchExpiringContracts(args: {
   agency?: string;
   naics?: string;
-  fiscalYear?: number;
+  // M2 (W3-1 honesty): `fiscalYear` is deliberately ABSENT. The recompete radar
+  // windows on the current PoP end date around TODAY, not an obligation FY, so a
+  // fiscalYear was inapplicable — it was validated by the input schema then
+  // silently discarded (never forwarded to searchRecompetes), with empty
+  // filtersDropped, i.e. zero signal to the caller. Removed from BOTH this arg
+  // type and UsasExpiringInput (server.ts) so it can no longer be
+  // validated-then-dropped. Use usas_search_recompetes' window controls instead.
   monthsUntilExpiry?: number;
   minAwardValue?: number;
   limit?: number;
 }) {
-  const filters = buildFilters(args);
-  type SearchResp = {
-    results?: {
-      "Award ID"?: string;
-      "Recipient Name"?: string;
-      "Award Amount"?: number;
-      generated_internal_id?: string;
-    }[];
-  };
-  const search = await postUsas<SearchResp>("search/spending_by_award", {
-    filters,
-    fields: ["Award ID", "Recipient Name", "Award Amount"],
-    limit: 50,
+  const windowEndDays = Math.round((args.monthsUntilExpiry ?? 12) * 30.44);
+  const pageSize = args.limit ?? 10;
+  const bundle = await searchRecompetes({
+    agency: args.agency,
+    naics: args.naics,
+    windowStartDays: -30, // legacy tool dropped rows expired > 30d ago
+    windowEndDays,
+    minAwardValue: args.minAwardValue ?? 100_000,
+    pageSize,
     page: 1,
-    subawards: false,
-    sort: "Award Amount",
-    order: "desc",
   });
 
-  const candidates = (search.results ?? []).filter(
-    (r) =>
-      (r["Award Amount"] ?? 0) >= (args.minAwardValue ?? 100_000) &&
-      r.generated_internal_id,
-  );
-
-  // Enrich up to 8 in parallel — be polite to USAspending.
-  const enrich = candidates.slice(0, 8);
-  const details = await Promise.all(
-    enrich.map((r) => getAwardDetail(r.generated_internal_id!)),
-  );
+  // Re-shape to the legacy contract row + keep the truthful _meta, appending a
+  // deprecation note.
+  type Recompete = (typeof bundle.data.recompetes)[number];
+  const contracts = bundle.data.recompetes.map((r: Recompete) => ({
+    awardId: r.awardId,
+    recipient: r.incumbent,
+    amount: r.amount,
+    endDate: r.currentEndDate,
+    potentialEndDate: r.potentialEndDate ?? null,
+    awardingAgency: r.awardingAgency,
+    awardingSubAgency: r.awardingSubAgency ?? undefined,
+    naicsCode: r.naicsCode ?? undefined,
+    setAsideDescription: r.setAsideDescription ?? undefined,
+    description: r.description ?? undefined,
+    daysUntilExpiry: r.daysUntilCurrentEnd,
+    generatedInternalId: r.generatedInternalId,
+  }));
 
-  const now = Date.now();
-  const cutoffDays = (args.monthsUntilExpiry ?? 12) * 30;
-  const contracts = details
-    .map((d, idx) => {
-      if (!d || !d.periodOfPerformance.endDate) return null;
-      const end = new Date(d.periodOfPerformance.endDate).getTime();
-      if (Number.isNaN(end)) return null;
-      const days = Math.ceil((end - now) / (24 * 60 * 60 * 1000));
-      if (days < -30 || days > cutoffDays) return null;
-      const orig = enrich[idx] ?? {};
-      return {
-        awardId: d.awardId || orig["Award ID"] || "",
-        recipient: d.recipient || orig["Recipient Name"] || "",
-        amount: d.totalObligation || orig["Award Amount"] || 0,
-        endDate: d.periodOfPerformance.endDate,
-        potentialEndDate: d.periodOfPerformance.potentialEndDate,
-        awardingAgency: d.awardingAgency ?? "",
-        awardingSubAgency: d.awardingSubAgency,
-        naicsCode: d.naicsCode,
-        setAsideDescription: d.setAsideDescription,
-        description: d.description,
-        daysUntilExpiry: days,
-      };
-    })
-    .filter((x): x is NonNullable<typeof x> => x !== null)
-    .slice(0, args.limit ?? 10)
-    .sort((a, b) => a.daysUntilExpiry - b.daysUntilExpiry);
+  const data = {
+    contracts,
+    // Legacy field: previously the count of value-filtered candidates. Now the
+    // number of in-window recompetes returned on this page (honest, non-zero
+    // where data exists).
+    searchedCount: contracts.length,
+  };
 
-  return { contracts, searchedCount: candidates.length };
+  const meta: Partial<ResponseMeta> = {
+    ...bundle.meta,
+    notes: [
+      "deprecated: use usas_search_recompetes — this alias re-shapes the corrected recompete-radar output onto the legacy { contracts, searchedCount } keys.",
+      ...(bundle.meta.notes ?? []),
+    ],
+  };
+  return withMeta(data, meta);
 }
 
 // ─── Aggregate analysis: time series ──────────────────────────────
@@ -426,20 +1665,89 @@ export async function spendingOverTime(args: {
       Idv_Obligations?: number;
     }[];
   };
+  const group = args.group ?? "fiscal_year";
   const json = await postUsas<Resp>("search/spending_over_time/", {
-    group: args.group ?? "fiscal_year",
+    group,
     filters,
   });
-  return {
-    group: json.group,
-    timeline: (json.results ?? []).map((r) => ({
-      timePeriod: r.time_period ?? {},
-      total: r.aggregated_amount ?? 0,
-      contractObligations: r.Contract_Obligations ?? 0,
-      grantObligations: r.Grant_Obligations ?? 0,
-      idvObligations: r.Idv_Obligations ?? 0,
-    })),
+  const results = json.results ?? [];
+
+  const timeline = results.map((r) => ({
+    timePeriod: r.time_period ?? {},
+    // `total` and `contractObligations` are IDENTICAL: buildFilters restricts to
+    // contract award types A/B/C/D, so aggregated_amount IS the contract
+    // obligation (LIVE-VERIFIED: aggregated_amount === Contract_Obligations for
+    // every bucket). The `?? r.aggregated_amount` fallback keeps that identity true
+    // ONLY while buildFilters enforces contracts-only — if this tool ever sends a
+    // wider award-type filter, revisit (aggregated_amount would be a MIXED total,
+    // not the contract figure). `total`'s `?? 0` is a genuine zero (endpoint silent
+    // on a bucket ⇒ no contract spend that period), NOT a masked-out category.
+    total: r.aggregated_amount ?? 0,
+    contractObligations: r.Contract_Obligations ?? r.aggregated_amount ?? 0,
+    // Grant/IDV obligations are EXCLUDED by that contract-only filter — they are
+    // NOT zero. The endpoint returns 0 for them here purely because A/B/C/D omits
+    // grants (award types 02–05) and IDVs (IDV_*); an agency's real grant/IDV
+    // spend can be billions per period (LIVE: DoD grants ~$4.8B in FY2008). Emit
+    // null, never a fabricated 0 that reads as "no grant/IDV spending" (DA-1 class).
+    grantObligations: null as number | null,
+    idvObligations: null as number | null,
+  }));
+
+  // spending_over_time returns the FULL timeline for the filter (no cursor/total),
+  // so what we return IS the complete set. Read the span for disclosure. Format
+  // each period label unambiguously per grouping (FY2024 / FY2024-Q1 / FY2024-M10)
+  // so the span note can't be misread ("2024 1" as month-vs-quarter).
+  const fmtPeriod = (
+    p: { fiscal_year?: string; quarter?: string; month?: string } | undefined,
+  ): string | null => {
+    if (!p) return null;
+    const fy = p.fiscal_year ? `FY${p.fiscal_year}` : null;
+    if (p.quarter) return fy ? `${fy}-Q${p.quarter}` : `Q${p.quarter}`;
+    if (p.month) return fy ? `${fy}-M${p.month}` : `M${p.month}`;
+    return fy;
   };
+  const spanStart = fmtPeriod(timeline[0]?.timePeriod);
+  const spanEnd = fmtPeriod(timeline[timeline.length - 1]?.timePeriod);
+
+  const filtersApplied = ["awardType(contracts A/B/C/D)"];
+  if (args.agency) filtersApplied.push("agency");
+  if (args.naics) filtersApplied.push("naics");
+  if (args.setAside) filtersApplied.push("setAside");
+
+  const notes: string[] = [
+    "This timeline counts CONTRACT obligations only (award types A/B/C/D), matching the other usas_search_*_spending tools — so `total` equals `contractObligations`.",
+    "Grant, IDV, loan, direct, and other obligation types are EXCLUDED by that filter. grantObligations/idvObligations are null (NOT 0) so an agency's real grant/IDV spending — which can run billions per period — is never misread as zero here.",
+    spanStart && spanEnd
+      ? `The timeline spans the full range the endpoint returned for this filter (${spanStart} … ${spanEnd}); a period showing 0 is a genuine zero for CONTRACT obligations in that period.`
+      : "A period showing 0 is a genuine zero for CONTRACT obligations in that period.",
+  ];
+  // Completeness caveat: no-cap is LIVE-VERIFIED only for fiscal_year (19 buckets,
+  // FY2008–2026). spending_over_time carries NO pagination envelope, so a very long
+  // month/quarter series could hit a silent server cap we could not detect — disclose
+  // that rather than assert a completeness we can't prove for those granularities.
+  if (group !== "fiscal_year") {
+    notes.push(
+      `Completeness for group='${group}': this endpoint returns no pagination envelope, and no-truncation is verified only for fiscal_year granularity — a very long ${group} series could in principle be capped server-side without a signal. Confirm the span (${spanStart ?? "?"} … ${spanEnd ?? "?"}) covers your expected range.`,
+    );
+  }
+
+  return withMeta(
+    { group: json.group ?? group, timeline },
+    {
+      source: SPENDING_OVER_TIME_SOURCE,
+      keylessMode: true,
+      returned: timeline.length,
+      totalAvailable: timeline.length,
+      truncated: false,
+      filtersApplied,
+      filtersDropped: [],
+      fieldsUnavailable: [
+        "grantObligations (excluded by the contract-only A/B/C/D filter — not zero)",
+        "idvObligations (excluded by the contract-only A/B/C/D filter — not zero)",
+      ],
+      notes,
+    },
+  );
 }
 
 // ─── Aggregate analysis: PSC spending ─────────────────────────────
@@ -453,18 +1761,31 @@ export async function searchPscSpending(args: {
   const filters = buildFilters(args);
   type Resp = {
     results?: { code?: string; name?: string; amount?: number }[];
+    page_metadata?: CategoryPageMeta;
   };
+  const limit = args.limit ?? 10;
   const json = await postUsas<Resp>(
     "search/spending_by_category/psc",
-    { filters, limit: args.limit ?? 10, page: 1 },
+    { filters, limit, page: 1 },
   );
-  return {
-    psc: (json.results ?? []).map((r) => ({
+  const results = json.results ?? [];
+  const data = {
+    psc: results.map((r) => ({
       pscCode: r.code ?? "",
       pscName: r.name ?? "",
       amount: r.amount ?? 0,
     })),
   };
+  return withMeta(
+    data,
+    categoryAggregateMeta({
+      source: "usaspending.gov/api/v2 search/spending_by_category/psc",
+      returned: results.length,
+      limit,
+      hasNext: json.page_metadata?.hasNext,
+      filters,
+    }),
+  );
 }
 
 // ─── Aggregate analysis: state / territory ─────────────────────────
@@ -478,18 +1799,35 @@ export async function searchStateSpending(args: {
   const filters = buildFilters(args);
   type Resp = {
     results?: { code?: string; name?: string; amount?: number }[];
+    page_metadata?: CategoryPageMeta;
   };
+  const limit = args.limit ?? 10;
   const json = await postUsas<Resp>(
     "search/spending_by_category/state_territory",
-    { filters, limit: args.limit ?? 10, page: 1 },
+    { filters, limit, page: 1 },
   );
-  return {
-    states: (json.results ?? []).map((r) => ({
+  const results = json.results ?? [];
+  const data = {
+    states: results.map((r) => ({
       stateCode: r.code ?? "",
       stateName: r.name ?? "",
       amount: r.amount ?? 0,
     })),
   };
+  return withMeta(
+    data,
+    categoryAggregateMeta({
+      source:
+        "usaspending.gov/api/v2 search/spending_by_category/state_territory",
+      returned: results.length,
+      limit,
+      hasNext: json.page_metadata?.hasNext,
+      filters,
+      extraNotes: [
+        "There are ~59 U.S. states/territories total; a capped result is a top-N by amount, not all places that received funding.",
+      ],
+    }),
+  );
 }
 
 // ─── Aggregate analysis: CFDA (grants) ─────────────────────────────
@@ -518,18 +1856,34 @@ export async function searchCfdaSpending(args: {
   }
   type Resp = {
     results?: { code?: string; name?: string; amount?: number }[];
+    page_metadata?: CategoryPageMeta;
   };
+  const limit = args.limit ?? 10;
   const json = await postUsas<Resp>(
     "search/spending_by_category/cfda",
-    { filters, limit: args.limit ?? 10, page: 1 },
+    { filters, limit, page: 1 },
   );
-  return {
-    programs: (json.results ?? []).map((r) => ({
+  const results = json.results ?? [];
+  const data = {
+    programs: results.map((r) => ({
       cfdaCode: r.code ?? "",
       programName: r.name ?? "",
       amount: r.amount ?? 0,
     })),
   };
+  return withMeta(
+    data,
+    categoryAggregateMeta({
+      source: "usaspending.gov/api/v2 search/spending_by_category/cfda",
+      returned: results.length,
+      limit,
+      hasNext: json.page_metadata?.hasNext,
+      filters,
+      extraNotes: [
+        "This is a grants view (award types 02/03/04/05); contracts are excluded.",
+      ],
+    }),
+  );
 }
 
 // ─── Aggregate analysis: federal account (TAS) ─────────────────────
@@ -543,18 +1897,32 @@ export async function searchFederalAccountSpending(args: {
   const filters = buildFilters(args);
   type Resp = {
     results?: { code?: string; name?: string; amount?: number }[];
+    page_metadata?: CategoryPageMeta;
   };
+  const limit = args.limit ?? 10;
   const json = await postUsas<Resp>(
     "search/spending_by_category/federal_account",
-    { filters, limit: args.limit ?? 10, page: 1 },
+    { filters, limit, page: 1 },
   );
-  return {
-    accounts: (json.results ?? []).map((r) => ({
+  const results = json.results ?? [];
+  const data = {
+    accounts: results.map((r) => ({
       tasCode: r.code ?? "",
       accountName: r.name ?? "",
       amount: r.amount ?? 0,
     })),
   };
+  return withMeta(
+    data,
+    categoryAggregateMeta({
+      source:
+        "usaspending.gov/api/v2 search/spending_by_category/federal_account",
+      returned: results.length,
+      limit,
+      hasNext: json.page_metadata?.hasNext,
+      filters,
+    }),
+  );
 }
 
 // ─── Aggregate analysis: awarding agency ──────────────────────────
@@ -573,19 +1941,33 @@ export async function searchAgencySpending(args: {
       amount?: number;
       agency_slug?: string;
     }[];
+    page_metadata?: CategoryPageMeta;
   };
+  const limit = args.limit ?? 10;
   const json = await postUsas<Resp>(
     "search/spending_by_category/awarding_agency",
-    { filters, limit: args.limit ?? 10, page: 1 },
+    { filters, limit, page: 1 },
   );
-  return {
-    agencies: (json.results ?? []).map((r) => ({
+  const results = json.results ?? [];
+  const data = {
+    agencies: results.map((r) => ({
       name: r.name ?? "",
       code: r.code ?? "",
       slug: r.agency_slug ?? "",
       amount: r.amount ?? 0,
     })),
   };
+  return withMeta(
+    data,
+    categoryAggregateMeta({
+      source:
+        "usaspending.gov/api/v2 search/spending_by_category/awarding_agency",
+      returned: results.length,
+      limit,
+      hasNext: json.page_metadata?.hasNext,
+      filters,
+    }),
+  );
 }
 
 // ─── Sub-agency breakdown ─────────────────────────────────────────
@@ -597,18 +1979,42 @@ export async function searchSubAgencySpending(args: {
   const filters = buildFilters(args);
   type Resp = {
     results?: { name?: string; amount?: number; count?: number }[];
+    page_metadata?: CategoryPageMeta;
   };
+  const limit = 10;
   const json = await postUsas<Resp>(
     "search/spending_by_category/awarding_subagency",
-    { filters, limit: 10, page: 1 },
+    { filters, limit, page: 1 },
   );
-  return {
-    subAgencies: (json.results ?? []).map((r) => ({
+  const results = json.results ?? [];
+  // The awarding_subagency endpoint returns `amount` but NOT a per-subagency
+  // award `count` (verified 2026-07-03). Emitting `awards: 0` would be a
+  // FABRICATED count (0 reads as "zero contracts", not "unknown") — the exact B1
+  // class. So `awards` is `null` (honest "unavailable"), consistent with
+  // searchAwards' B1 fix, AND flagged in `_meta.fieldsUnavailable` + a note. An
+  // AI that ignores `_meta` still sees null, never a fake 0.
+  const data = {
+    subAgencies: results.map((r) => ({
       name: r.name ?? "",
       amount: r.amount ?? 0,
-      awards: r.count ?? 0,
+      awards: null as number | null,
     })),
   };
+  return withMeta(
+    data,
+    categoryAggregateMeta({
+      source:
+        "usaspending.gov/api/v2 search/spending_by_category/awarding_subagency",
+      returned: results.length,
+      limit,
+      hasNext: json.page_metadata?.hasNext,
+      filters,
+      fieldsUnavailable: ["awards"],
+      extraNotes: [
+        "Per-subagency award COUNTS are not returned by this endpoint — the `awards` field is null for every row (unavailable, NOT a real count and NOT 0). Use amount for ranking; do not report `awards` as a contract count.",
+      ],
+    }),
+  );
 }
 
 // ─── Agency profile ───────────────────────────────────────────────
@@ -625,6 +2031,18 @@ export async function getAgencyProfile(toptierCode: string) {
     congressional_justification_url?: string;
   };
   const json = await getUsas<Resp>(`agency/${toptierCode}/`);
+  // minor m1 (W3-1 honesty) hollow-200 guard — mirror getRecipientProfile: a real
+  // agency/{code} 200 always echoes a toptier_code and/or name. A 200 with NEITHER
+  // is a degraded/hollow response (CDN/WAF interstitial, upstream hiccup) — do NOT
+  // map it into a fabricated { name:undefined } "complete" profile; throw schema_drift.
+  if (!json.toptier_code && !json.name) {
+    throw new ToolErrorCarrier({
+      kind: "schema_drift",
+      message: `usaspending agency/${toptierCode} returned a 200 with no toptier_code or name — a hollow/degraded response, not a real agency profile. Retry, or resolve the code via usas_lookup_agency.`,
+      retryable: true,
+      upstreamEndpoint: `agency/${toptierCode}`,
+    });
+  }
   return {
     fiscalYear: json.fiscal_year,
     toptierCode: json.toptier_code,
@@ -652,13 +2070,47 @@ export async function getAgencyAwardsSummary(args: {
   const json = await getUsas<Resp>(
     `agency/${args.toptierCode}/awards/?fiscal_year=${fy}`,
   );
-  return {
+  // M3 (W3-1 honesty) hollow-200 guard — mirror getRecipientProfile: a real
+  // agency/{code}/awards 200 always carries transaction_count and/or obligations
+  // as numbers. A valid-JSON but degraded/renamed 200 with NEITHER as a number is
+  // a hollow response — do NOT map it into a confident false "$0 obligations, 0
+  // transactions". Surface it as retryable schema_drift (a typed carrier).
+  if (
+    typeof json.transaction_count !== "number" &&
+    typeof json.obligations !== "number"
+  ) {
+    throw new ToolErrorCarrier({
+      kind: "schema_drift",
+      message: `usaspending agency/${args.toptierCode}/awards returned a 200 with neither transaction_count nor obligations for FY${fy} — a hollow/degraded response, not a real summary. Do NOT read it as $0; retry, or verify the toptier code via usas_lookup_agency.`,
+      retryable: true,
+      upstreamEndpoint: `agency/${args.toptierCode}/awards`,
+    });
+  }
+  const data = {
     fiscalYear: json.fiscal_year,
     toptierCode: json.toptier_code,
-    transactionCount: json.transaction_count ?? 0,
-    obligations: json.obligations ?? 0,
+    // null-never-0: an individually-absent field is null (unknown), NOT a
+    // fabricated 0. A genuine numeric 0 survives (`??` fires only on nullish).
+    transactionCount: json.transaction_count ?? null,
+    obligations: json.obligations ?? null,
     latestActionDate: json.latest_action_date,
   };
+  // VQ-2 (C80 dogfooding): `obligations`/`transactionCount` from agency/{code}/awards
+  // span ALL award types, NOT contracts only. Disclose scope so an agent doesn't
+  // misread it as the procurement market (live: VA FY2024 = $238B all-awards vs
+  // $66.9B contracts — a benefit-heavy agency's figure is dominated by direct
+  // benefit payments, not procurement).
+  return withMeta(data, {
+    source: "usaspending.gov/api/v2 agency/{code}/awards",
+    keylessMode: true,
+    returned: 1,
+    // FILT-1 consistency (adversarial review): this tool filters by URL params, not
+    // buildFilters, so filtersAppliedFromFilters can't reach it — declare them here.
+    filtersApplied: ["toptierCode", "fiscalYear"],
+    notes: [
+      "SCOPE: `obligations` and `transactionCount` cover ALL award types (contracts, grants, direct payments incl. benefits, loans) for this agency — NOT prime contracts only. For a benefit-heavy agency (VA/SSA/HHS) direct benefit payments DOMINATE this figure (VA FY2024: ~$238B all-awards vs ~$67B prime contract awards A/B/C/D); for a procurement-heavy agency (DoD/DHS) obligations closely tracks contract spending. For the CONTRACTS-only obligation use usas_spending_over_time (contractObligations) or usas_search_*_spending — those filter by the agency's canonical NAME, so first resolve it from this toptierCode via usas_get_agency_profile (→ name).",
+    ],
+  });
 }
 
 export async function getAgencyBudgetFunction(args: {
@@ -667,6 +2119,7 @@ export async function getAgencyBudgetFunction(args: {
   limit?: number;
 }) {
   const fy = args.fiscalYear ?? new Date().getUTCFullYear();
+  const limit = args.limit ?? 10;
   type Resp = {
     toptier_code?: string;
     fiscal_year?: number;
@@ -678,14 +2131,32 @@ export async function getAgencyBudgetFunction(args: {
         gross_outlay_amount?: number;
       }[];
     }[];
+    // Unlike the spending_by_category/* endpoints, agency/budget_function
+    // DOES report a real grand total in page_metadata.total (verified
+    // 2026-07-03: e.g. DoD → total:6 while a 3-row page has hasNext:true).
+    page_metadata?: { page?: number; total?: number; hasNext?: boolean };
   };
   const json = await getUsas<Resp>(
-    `agency/${args.toptierCode}/budget_function/?fiscal_year=${fy}&limit=${args.limit ?? 10}`,
+    `agency/${args.toptierCode}/budget_function/?fiscal_year=${fy}&limit=${limit}`,
   );
-  return {
+  const results = json.results ?? [];
+  // minor m1 (W3-1 honesty) hollow-200 guard — a real budget_function 200 echoes
+  // toptier_code + fiscal_year and carries results. A 200 with NONE of the three is
+  // a degraded/hollow response — do NOT map it into a fabricated empty budget
+  // (which reads as "this agency has no budget functions"); throw schema_drift.
+  if (!json.toptier_code && !json.fiscal_year && results.length === 0) {
+    throw new ToolErrorCarrier({
+      kind: "schema_drift",
+      message: `usaspending agency/${args.toptierCode}/budget_function returned a 200 with no toptier_code, fiscal_year, or results for FY${fy} — a hollow/degraded response, not a real budget. Retry.`,
+      retryable: true,
+      upstreamEndpoint: `agency/${args.toptierCode}/budget_function`,
+    });
+  }
+  const total = json.page_metadata?.total ?? null;
+  const data = {
     toptierCode: json.toptier_code,
     fiscalYear: json.fiscal_year,
-    functions: (json.results ?? []).map((r) => ({
+    functions: results.map((r) => ({
       name: r.name ?? "",
       programs: (r.children ?? []).map((c) => ({
         name: c.name ?? "",
@@ -694,6 +2165,34 @@ export async function getAgencyBudgetFunction(args: {
       })),
     })),
   };
+  const hasMore =
+    total !== null ? results.length < total : (json.page_metadata?.hasNext ?? false);
+  return withMeta(data, {
+    source: "usaspending.gov/api/v2 agency/{code}/budget_function",
+    keylessMode: true,
+    returned: results.length,
+    // Real total from the endpoint (budget-function count for the FY).
+    totalAvailable: total,
+    truncated: hasMore,
+    pagination: {
+      offset: 0,
+      limit,
+      // W3-7 (honesty; mirrors searchRecipients M1 / awardPagination): this tool has
+      // NO offset/page input (page hardcoded to the `limit` slice) — so `nextOffset`
+      // is NOT consumable. Emitting `results.length` made an agent re-fetch the SAME
+      // top-N forever. Emit null; `hasMore` stays honest (more functions DO exist).
+      nextOffset: null,
+      hasMore,
+    },
+    filtersApplied: [],
+    filtersDropped: [],
+    fieldsUnavailable: [],
+    notes: hasMore
+      ? [
+          `Showing the top ${limit} budget functions; ${total ?? "more"} exist for FY${fy}. These extra functions are NOT page-reachable — this tool has no offset input (nextOffset is null). Raise limit to see the rest.`,
+        ]
+      : [],
+  });
 }
 
 // ─── Recipient list + profile ─────────────────────────────────────
@@ -714,18 +2213,28 @@ export async function searchRecipients(args: {
       amount?: number;
     }[];
   };
+  const limit = args.limit ?? 10;
   const body: Record<string, unknown> = {
     keyword: args.keyword,
-    limit: args.limit ?? 10,
+    limit,
     page: 1,
   };
   if (args.recipientLevel) {
     body.recipient_level = args.recipientLevel;
   }
   const json = await postUsas<Resp>("recipient/", body);
-  return {
-    totalRecords: json.page_metadata?.total ?? 0,
-    recipients: (json.results ?? []).map((r) => ({
+  const results = json.results ?? [];
+  // recipient/ DOES report a real grand total in page_metadata.total
+  // (verified 2026-07-03: "booz" → total:512). Keep it in _meta.totalAvailable
+  // and derive truncation from returned < total. null (not 0) when absent so
+  // we never claim a total the endpoint didn't give.
+  const total = json.page_metadata?.total ?? null;
+  const data = {
+    // F3 (P1): mirror the honest null `_meta.totalAvailable` — an OMITTED total
+    // must NOT default to 0 in the data field (a 200-with-rows-but-no-total then
+    // says "0 records" while rows exist and _meta says null: a self-contradiction).
+    totalRecords: total,
+    recipients: results.map((r) => ({
       id: r.id ?? "",
       duns: r.duns,
       uei: r.uei,
@@ -734,6 +2243,35 @@ export async function searchRecipients(args: {
       totalAmount: r.amount ?? 0,
     })),
   };
+  const hasMore = total !== null ? results.length < total : results.length >= limit;
+  return withMeta(data, {
+    source: "usaspending.gov/api/v2 recipient/",
+    keylessMode: true,
+    returned: results.length,
+    totalAvailable: total,
+    truncated: hasMore,
+    pagination: {
+      offset: 0,
+      limit,
+      // M1 (W3-1 honesty): this tool has NO offset/page input — page is hardcoded
+      // to 1 (see body above) — so `nextOffset` is NOT consumable. Emitting
+      // `results.length` made an agent re-fetch the SAME top-N forever while
+      // ranked-below-`limit` recipients stayed unjoinable. Emit null
+      // unconditionally (mirror edgar.ts:656 / the FTS beyond-window pattern:
+      // hasMore stays true while nextOffset is null). The extra matches are
+      // reachable ONLY by raising `limit` (≤50) or narrowing the keyword.
+      nextOffset: null,
+      hasMore,
+    },
+    filtersApplied: [],
+    filtersDropped: [],
+    fieldsUnavailable: [],
+    notes: hasMore
+      ? [
+          `Showing the top ${limit} recipients by amount; ${total ?? "more"} match the keyword. These extra matches are NOT page-reachable — this tool has no offset input (nextOffset is null). Raise limit (up to 50) or narrow the keyword to see more.`,
+        ]
+      : [],
+  });
 }
 
 export async function getRecipientProfile(recipientId: string) {
@@ -757,9 +2295,64 @@ export async function getRecipientProfile(recipientId: string) {
     total_transaction_amount?: number;
     total_transactions?: number;
   };
-  const json = await getUsas<Resp>(
-    `recipient/${encodeURIComponent(recipientId)}/`,
-  );
+  // NOT via getUsas: USAspending signals a NONEXISTENT recipient with HTTP 400 +
+  // `detail: "Recipient ID not found: '...'"` (LIVE-VERIFIED 2026-07-06 — NOT a
+  // 404, and NOT a malformed-input 400). Through fetchWithRetry/errorFromResponse
+  // that 400 becomes `invalid_input` ("Bad request"), telling a caller its
+  // recipient_id was MALFORMED when the recipient simply does not exist. Read the
+  // body to distinguish that not-found from a genuine bad-input 400 and classify
+  // honestly (mirrors getAwardDetail's explicit status handling).
+  let r: Response;
+  try {
+    r = await fetch(`${USAS}/recipient/${encodeURIComponent(recipientId)}/`, {
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (e) {
+    // A network-level fault (DNS/reset/timeout) is an OUTAGE, not a missing
+    // recipient — classify as retryable rather than surfacing the generic `unknown`.
+    if (e instanceof ToolErrorCarrier) throw e;
+    throw new ToolErrorCarrier({
+      kind: "upstream_unavailable",
+      message: `usaspending recipient/{id} fetch failed: ${e instanceof Error ? e.message : String(e)}. This is an outage, not a missing recipient. Retry.`,
+      retryable: true,
+      upstreamEndpoint: `recipient/${recipientId}`,
+    });
+  }
+  if (!r.ok) {
+    let detail = "";
+    try {
+      detail = ((await r.json()) as { detail?: string }).detail ?? "";
+    } catch {
+      /* non-JSON error body → detail stays "" and we fall through to errorFromResponse */
+    }
+    if (
+      r.status === 404 ||
+      (r.status === 400 && /recipient\s*(id\s+)?not found/i.test(detail))
+    ) {
+      throw new ToolErrorCarrier({
+        kind: "not_found",
+        message: `No recipient profile found for recipient_id '${recipientId}' on usaspending.gov${detail ? ` (upstream: ${detail})` : ""}. Resolve a valid recipient_id via usas_search_recipients — each result carries an id. This is a genuine not-found, NOT a malformed input.`,
+        retryable: false,
+        upstreamStatus: r.status,
+        upstreamEndpoint: `recipient/${recipientId}`,
+      });
+    }
+    // Any other non-2xx (a genuine bad-input 400, 429, 5xx) → the shared matrix.
+    throw new ToolErrorCarrier(errorFromResponse(r, `recipient/${recipientId}`));
+  }
+  const json = (await r.json()) as Resp;
+  // Defensive hollow-200 guard (cf. sam_lookup_organization / grants / opportunity):
+  // a real recipient 200 always carries a name and/or recipient_id. A 200 with
+  // NEITHER is a degraded/hollow response (CDN/WAF interstitial, upstream hiccup) —
+  // do NOT map it into a fabricated { name:"" } profile; surface it as schema_drift.
+  if (!json.recipient_id && !json.name) {
+    throw new ToolErrorCarrier({
+      kind: "schema_drift",
+      message: `usaspending recipient/{id} returned a 200 with no recipient_id or name for '${recipientId}' — a hollow/degraded response, not a real profile. Retry, or verify the id via usas_search_recipients.`,
+      retryable: true,
+      upstreamEndpoint: `recipient/${recipientId}`,
+    });
+  }
   return {
     name: json.name ?? "",
     alternateNames: json.alternate_names ?? [],
@@ -782,14 +2375,6 @@ export async function lookupAgency(searchText: string) {
   // Cache: agency lookups are extremely repeat-prone (`VA`, `DHS`, etc.)
   // and effectively static across a session.
   return memoize(`usas:agency:${searchText.toLowerCase()}`, async () => {
-  try {
-    const r = await fetch(`${USAS}/autocomplete/funding_agency/`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ search_text: searchText, limit: 5 }),
-      signal: AbortSignal.timeout(10_000),
-    });
-    if (!r.ok) return { matches: [] };
     type Resp = {
       results?: {
         toptier_flag?: boolean;
@@ -800,7 +2385,15 @@ export async function lookupAgency(searchText: string) {
         };
       }[];
     };
-    const json = (await r.json()) as Resp;
+    // Via postUsas (fetchWithRetry) so a DOWN service THROWS upstream_unavailable
+    // instead of returning `{ matches: [] }` — which an AI reads as "no such
+    // agency" when the endpoint is merely down. This was the last silent-empty-
+    // on-outage in the codebase; now consistent with autocompleteNaics/Recipient
+    // (a GENUINE no-match still returns an honest empty `matches`).
+    const json = await postUsas<Resp>("autocomplete/funding_agency/", {
+      search_text: searchText,
+      limit: 5,
+    });
     return {
       matches: (json.results ?? []).map((r) => ({
         name: r.toptier_agency?.name ?? "",
@@ -809,9 +2402,6 @@ export async function lookupAgency(searchText: string) {
         isToptier: !!r.toptier_flag,
       })),
     };
-  } catch {
-    return { matches: [] };
-  }
   });
 }
 
@@ -819,8 +2409,9 @@ export async function autocompleteNaics(args: {
   searchText: string;
   limit?: number;
 }) {
+  const limit = args.limit ?? 10;
   return memoize(
-    `usas:naics:${args.searchText.toLowerCase()}:${args.limit ?? 10}`,
+    `usas:naics:${args.searchText.toLowerCase()}:${limit}`,
     async () => {
       type Resp = {
         results?: {
@@ -831,15 +2422,24 @@ export async function autocompleteNaics(args: {
       };
       const json = await postUsas<Resp>("autocomplete/naics/", {
         search_text: args.searchText,
-        limit: args.limit ?? 10,
+        limit,
       });
-      return {
-        naics: (json.results ?? []).map((r) => ({
+      const results = json.results ?? [];
+      const data = {
+        naics: results.map((r) => ({
           code: r.naics ?? "",
           description: r.naics_description ?? "",
           retired: !!r.year_retired,
         })),
       };
+      return withMeta(data, referenceMeta({
+        source: "usaspending.gov/api/v2 autocomplete/naics",
+        returned: results.length,
+        limit,
+        // autocomplete/naics returns only {results} — no total (verified
+        // 2026-07-03). A full page means more matches likely exist.
+        totalAvailable: null,
+      }));
     },
   );
 }
@@ -848,10 +2448,16 @@ export async function autocompleteRecipient(args: {
   searchText: string;
   limit?: number;
 }) {
+  const limit = args.limit ?? 10;
   return memoize(
-    `usas:recipient:${args.searchText.toLowerCase()}:${args.limit ?? 10}`,
+    `usas:recipient:${args.searchText.toLowerCase()}:${limit}`,
     async () => {
       type Resp = {
+        // NOTE: this endpoint's top-level `count` equals the RETURNED row
+        // count (verified 2026-07-03: 5 asked → count:5), NOT a grand total —
+        // so it is NOT a usable totalAvailable (spec §3.3: never substitute
+        // page size for an unknown total). Left as null.
+        count?: number;
         results?: {
           recipient_name?: string;
           uei?: string;
@@ -860,67 +2466,168 @@ export async function autocompleteRecipient(args: {
       };
       const json = await postUsas<Resp>("autocomplete/recipient/", {
         search_text: args.searchText,
-        limit: args.limit ?? 10,
+        limit,
       });
-      return {
-        recipients: (json.results ?? []).map((r) => ({
+      const results = json.results ?? [];
+      const data = {
+        recipients: results.map((r) => ({
           name: r.recipient_name ?? "",
           uei: r.uei,
           duns: r.duns,
         })),
       };
+      return withMeta(data, referenceMeta({
+        source: "usaspending.gov/api/v2 autocomplete/recipient",
+        returned: results.length,
+        limit,
+        totalAvailable: null,
+      }));
     },
   );
 }
 
 export async function naicsHierarchy(args: { naicsFilter?: string }) {
   return memoize(`usas:naics-hierarchy:${args.naicsFilter ?? ""}`, async () => {
-    type Resp = {
-      results?: {
-        naics?: string;
-        naics_description?: string;
-        count?: number;
-        children?: unknown[];
-      }[];
+    type NaicsNode = {
+      naics?: string;
+      naics_description?: string;
+      count?: number;
+      children?: NaicsNode[];
     };
+    type Resp = { results?: NaicsNode[] };
+    // VQ-4 (C81 dogfooding): DRILL-DOWN is the PATH param references/naics/{code}/
+    // (returns the node WITH its `children`), NOT `?filter=` — `filter` is a keyword
+    // search (live: filter=54 fuzzy-matched sectors 32/45/48/54, and the top-level
+    // response omits `children` so hasChildren was ALWAYS false). Unfiltered returns
+    // the top-level 2-digit sectors.
     const path = args.naicsFilter
-      ? `references/naics/?filter=${encodeURIComponent(args.naicsFilter)}`
+      ? `references/naics/${encodeURIComponent(args.naicsFilter)}/`
       : "references/naics/";
-    const json = await getUsas<Resp>(path);
-    return {
-      hierarchy: (json.results ?? []).map((r) => ({
-        code: r.naics ?? "",
-        description: r.naics_description ?? "",
-        count: r.count ?? 0,
-        hasChildren: !!(r.children && r.children.length > 0),
-      })),
+    // Snapshot ONLY the canonical UNFILTERED top-level NAICS tree (a single,
+    // well-defined queryless read the builder can pre-fetch). A drill-down
+    // (`naicsFilter` set) passes no key ⇒ live only. Even unfiltered, the
+    // snapshot is INERT unless SAMGOV_SNAPSHOT_BASE_URL is configured.
+    const snapshotKey = args.naicsFilter ? undefined : "usas_naics_hierarchy";
+    const { body: json, provenance } = await getUsasResilient<Resp>(
+      path,
+      snapshotKey,
+    );
+    const results = json.results ?? [];
+    // NAICS levels are 2→4→6 digit (USAspending skips 3/5); only a 6-digit code is a
+    // leaf. The top-level response carries no `children`, so hasChildren is derived
+    // from code length — an honest structural signal, never a blanket false.
+    const toRow = (r: NaicsNode) => ({
+      code: r.naics ?? "",
+      description: r.naics_description ?? "",
+      count: r.count ?? 0,
+      hasChildren: (r.naics ?? "").length < 6,
+    });
+    // Filtered: results[0] is the requested node; its `children` are the drill-down
+    // level. Unfiltered: results ARE the top-level sectors.
+    const node = args.naicsFilter ? results[0] : undefined;
+    const level = args.naicsFilter ? (node?.children ?? []) : results;
+    const notes: string[] = [];
+    if (args.naicsFilter && !node) {
+      notes.push(
+        `NAICS '${args.naicsFilter}' was NOT found in the USAspending reference dataset — no hierarchy returned (nothing fabricated). Confirm it is a current 2/4/6-digit NAICS code.`,
+      );
+    } else if (args.naicsFilter && node && level.length === 0) {
+      // Adversarial review F2: derive the digit count instead of hardcoding "6-digit"
+      // (a 4-digit code with no children in USAspending's data would else mislabel).
+      const digits = (node.naics ?? args.naicsFilter).length;
+      notes.push(
+        `NAICS ${node.naics ?? args.naicsFilter} is a leaf (${digits}-digit — no child codes in USAspending's reference). The node's own row is in \`parent\`.`,
+      );
+    } else {
+      notes.push(
+        "Drill into any row with hasChildren:true by calling again with its `code` as naicsFilter. Levels are 2→4→6 digit (USAspending skips 3/5-digit).",
+      );
+    }
+    const data = {
+      filter: args.naicsFilter ?? null,
+      // Adversarial review F3: structured found signal — a leaf (found, no children)
+      // and a nonexistent code both yield hierarchy:[], so `returned` alone can't
+      // distinguish them. found:true/false disambiguates; null when unfiltered.
+      found: args.naicsFilter ? node !== undefined : null,
+      parent: node
+        ? { code: node.naics ?? "", description: node.naics_description ?? "", count: node.count ?? 0 }
+        : null,
+      hierarchy: level.map(toRow),
     };
+    // references/naics has NO limit param and NO total — the returned level IS the
+    // complete set for that node.
+    return withMeta(data, {
+      ...referenceMeta({
+        source: "usaspending.gov/api/v2 references/naics",
+        returned: data.hierarchy.length,
+        limit: data.hierarchy.length,
+        totalAvailable: data.hierarchy.length,
+        limitHonored: false,
+        extraNotes: notes,
+      }),
+      filtersApplied: args.naicsFilter ? ["naicsFilter(direct-children)"] : [],
+      // P5 provenance: threaded ONLY when NON-live (snapshot) — live ⇒ {} ⇒
+      // byte-identical _meta (provenanceMeta returns the empty object).
+      ...provenanceMeta(provenance),
+    });
   });
 }
 
+const GLOSSARY_DEFAULT_LIMIT = 25;
+
 export async function glossary(args: { limit?: number; search?: string }) {
-  return memoize(`usas:glossary:${args.search ?? ""}:${args.limit ?? 25}`, async () => {
+  const limit = args.limit ?? GLOSSARY_DEFAULT_LIMIT;
+  return memoize(`usas:glossary:${args.search ?? ""}:${limit}`, async () => {
     type Resp = {
+      // references/glossary DOES report a real grand total in
+      // page_metadata.count (verified 2026-07-03: 151, stable across limits).
       page_metadata?: { count?: number };
       results?: { term?: string; slug?: string; plain?: string }[];
     };
     const params = new URLSearchParams();
-    params.set("limit", String(args.limit ?? 25));
+    params.set("limit", String(limit));
     if (args.search) params.set("search", args.search);
-    const json = await getUsas<Resp>(`references/glossary/?${params.toString()}`);
-    return {
-      totalRecords: json.page_metadata?.count ?? 0,
-      terms: (json.results ?? []).map((r) => ({
+    // Snapshot ONLY the canonical read — NO search term AND the default limit —
+    // which is the exact query the builder pre-fetches (references/glossary/
+    // ?limit=25). A search or a non-default limit passes no key ⇒ live only, so
+    // the served snapshot can never desync `returned` from what was asked. INERT
+    // unless SAMGOV_SNAPSHOT_BASE_URL is configured.
+    const snapshotKey =
+      !args.search && limit === GLOSSARY_DEFAULT_LIMIT
+        ? "usas_glossary"
+        : undefined;
+    const { body: json, provenance } = await getUsasResilient<Resp>(
+      `references/glossary/?${params.toString()}`,
+      snapshotKey,
+    );
+    const results = json.results ?? [];
+    const total = json.page_metadata?.count ?? null;
+    const data = {
+      // F3 (P1): mirror the honest null `_meta.totalAvailable` — an OMITTED count
+      // must NOT default to 0 in the data field (that would contradict the null meta).
+      totalRecords: total,
+      terms: results.map((r) => ({
         term: r.term ?? "",
         slug: r.slug ?? "",
         definition: r.plain ?? "",
       })),
     };
+    return withMeta(data, {
+      ...referenceMeta({
+        source: "usaspending.gov/api/v2 references/glossary",
+        returned: results.length,
+        limit,
+        totalAvailable: total,
+      }),
+      // P5 provenance — threaded ONLY when NON-live ⇒ live stays byte-identical.
+      ...provenanceMeta(provenance),
+    });
   });
 }
 
 export async function listToptierAgencies(args: { limit?: number }) {
-  return memoize(`usas:toptier:${args.limit ?? 50}`, async () => {
+  const limit = args.limit ?? 50;
+  return memoize(`usas:toptier:${limit}`, async () => {
     type Resp = {
       results?: {
         agency_name?: string;
@@ -931,11 +2638,17 @@ export async function listToptierAgencies(args: { limit?: number }) {
         obligated_amount?: number;
       }[];
     };
-    const json = await getUsas<Resp>(
-      `references/toptier_agencies/?limit=${args.limit ?? 50}`,
+    // The toptier list is canonical + the endpoint IGNORES `limit` (returns the
+    // COMPLETE ~111-agency set for any limit — verified 2026-07-03), so the
+    // snapshot is limit-independent and always opted in (key stable). INERT
+    // unless SAMGOV_SNAPSHOT_BASE_URL is configured.
+    const { body: json, provenance } = await getUsasResilient<Resp>(
+      `references/toptier_agencies/?limit=${limit}`,
+      "usas_toptier_agencies",
     );
-    return {
-      agencies: (json.results ?? []).map((r) => ({
+    const results = json.results ?? [];
+    const data = {
+      agencies: results.map((r) => ({
         name: r.agency_name ?? "",
         abbreviation: r.abbreviation,
         toptierCode: r.toptier_code,
@@ -944,5 +2657,24 @@ export async function listToptierAgencies(args: { limit?: number }) {
         obligatedAmount: r.obligated_amount ?? 0,
       })),
     };
+    // IMPORTANT: this endpoint IGNORES the `limit` param (verified 2026-07-03:
+    // limit=3 AND limit=1000 both return all 111 toptier agencies). So the
+    // response is ALWAYS the complete set — truncated:false, and the returned
+    // count IS the total. Deriving truncation from `returned >= limit` would be
+    // a false positive, so limitHonored:false forces complete.
+    return withMeta(data, {
+      ...referenceMeta({
+        source: "usaspending.gov/api/v2 references/toptier_agencies",
+        returned: results.length,
+        limit,
+        totalAvailable: results.length,
+        limitHonored: false,
+        extraNotes: [
+          "The toptier_agencies endpoint returns the COMPLETE list of ~111 toptier agencies regardless of the `limit` value (limit is ignored upstream).",
+        ],
+      }),
+      // P5 provenance — threaded ONLY when NON-live ⇒ live stays byte-identical.
+      ...provenanceMeta(provenance),
+    });
   });
 }