@cliwant/mcp-sam-gov 0.3.0 → 1.0.0

package/src/sam-gov/client.ts

@@ -13,6 +13,7 @@
  * to layer 2 transparently. Callers don't have to care.
  */
 
+import { ToolErrorCarrier } from "../errors.js";
 import type {
   EntitySearchResult,
   SamGovClientOptions,
@@ -41,13 +42,26 @@ export class SamGovClient {
     this.logger = options.logger ?? {};
   }
 
+  /**
+   * True when no SAM API key is configured, i.e. requests fall back to the
+   * keyless HAL layer. The keyless list endpoint ignores the structured
+   * facet filters (NAICS / set-aside / state / org) and nulls those fields,
+   * so tools use this to populate an honest `_meta` (filtersDropped /
+   * fieldsUnavailable). See docs/research/02-truthful-outputs-spec.md §1.2.
+   */
+  get isKeyless(): boolean {
+    return !this.apiKey;
+  }
+
   /**
    * Search SAM.gov opportunities.
    *
    * Three-tier fallback:
    *   1. Authenticated v2 search (if `apiKey` configured)
-   *   2. Keyless HAL search
-   *   3. Empty result (caller can decide how to surface "no data")
+   *   2. Keyless HAL search — returned AS-IS (a genuine 0 or an empty page
+   *      past the end is an honest result, not a fallback trigger)
+   *   3. Only if EVERY tier throws (total outage): an empty result carrying
+   *      `degraded` so the caller surfaces an outage, NOT a confirmed zero.
    */
   async searchOpportunities(
     filters: SamSearchFilters,
@@ -65,17 +79,26 @@ export class SamGovClient {
       }
     }
     try {
-      const r = await this.searchPublic(filters);
-      if (r.opportunitiesData.length > 0) return r;
+      // Return the public result AS-IS — even 0 rows. A genuine zero
+      // (source healthy, query matched nothing) and a real `totalRecords>0`
+      // but empty page (paging past the end) are both HONEST outcomes and
+      // must not be replaced by a hardcoded 0. Only a THROW below (all tiers
+      // failed) is an outage, which we mark `degraded` so callers can tell it
+      // apart from a genuine zero instead of silently reporting "0, complete".
+      return await this.searchPublic(filters);
     } catch (err) {
       this.warn("public search failed", err);
+      return {
+        totalRecords: 0,
+        limit: filters.limit ?? 25,
+        offset: filters.offset ?? 0,
+        opportunitiesData: [],
+        degraded: {
+          reason:
+            "SAM opportunity search is unavailable (all access tiers failed).",
+        },
+      };
     }
-    return {
-      totalRecords: 0,
-      limit: filters.limit ?? 25,
-      offset: filters.offset ?? 0,
-      opportunitiesData: [],
-    };
   }
 
   /**
@@ -106,7 +129,18 @@ export class SamGovClient {
           const hit = json.opportunitiesData?.[0];
           if (hit) {
             if (!hit.resourceLinks || hit.resourceLinks.length === 0) {
-              hit.resourceLinks = await this.getPublicResourceLinks(noticeId);
+              // Same DOWN-reads-as-absent guard on the keyed path: a failed
+              // resource-list fetch is an outage, not "no attachments" —
+              // record the degradation instead of silently returning `[]`.
+              hit.resourceLinks = await this.getPublicResourceLinks(
+                noticeId,
+              ).catch(() => {
+                hit.enrichmentDegraded = [
+                  ...(hit.enrichmentDegraded ?? []),
+                  "attachments",
+                ];
+                return [];
+              });
             }
             return hit;
           }
@@ -115,11 +149,25 @@ export class SamGovClient {
         this.warn("auth getOpportunity failed, trying public", err);
       }
     }
+    // getOpportunityPublic returns null ONLY for a genuine not-found (401/404);
+    // an outage (5xx/network/timeout/hollow-200) THROWS a classified
+    // ToolErrorCarrier. That throw MUST propagate — collapsing it to null would
+    // make the wrapper render a DOWN service as found:false (a fabricated
+    // absence). A genuine null still passes through unchanged.
     try {
       return await this.getOpportunityPublic(noticeId);
     } catch (err) {
       this.warn("public getOpportunity failed", err);
-      return null;
+      if (err instanceof ToolErrorCarrier) throw err;
+      // A raw/unclassified error must not become a silent null either —
+      // classify it as a retryable outage so the caller learns the truth.
+      throw new ToolErrorCarrier({
+        kind: "upstream_unavailable",
+        message: `SAM detail lookup for ${noticeId} failed: ${(err as Error).message}. This is an outage, not a confirmed absence. Retry.`,
+        retryable: true,
+        retryAfterSeconds: 30,
+        upstreamEndpoint: "sam:opps/v2/opportunities",
+      });
     }
   }
 
@@ -153,7 +201,19 @@ export class SamGovClient {
     }
     try {
       const r = await this.fetchImpl(finalUrl, { headers });
-      if (!r.ok) return "Description not available.";
+      // A DOWN description fetch must ERROR, never fabricate a "not available"
+      // placeholder that reads as "this description doesn't exist". THROW a
+      // classified retryable outage; the wrapper propagates it to a tool error.
+      if (!r.ok) {
+        throw new ToolErrorCarrier({
+          kind: "upstream_unavailable",
+          message: `SAM description fetch returned HTTP ${r.status} for ${finalUrl} — the service is unavailable, NOT an absent description. Retry.`,
+          retryable: true,
+          retryAfterSeconds: 60,
+          upstreamStatus: r.status,
+          upstreamEndpoint: "sam:description",
+        });
+      }
       const ct = r.headers.get("content-type") ?? "";
       if (ct.includes("application/json") || ct.includes("application/hal+json")) {
         const json = (await r.json()) as {
@@ -181,7 +241,18 @@ export class SamGovClient {
         .trim();
     } catch (err) {
       this.warn("fetchOpportunityDescription failed", err);
-      return "Description not available.";
+      // A classified outage (from the !r.ok throw above) propagates as-is. A raw
+      // network/parse fault must ALSO error (not fabricate "not available") —
+      // classify it as a retryable outage so a DOWN fetch is never read as an
+      // absent description.
+      if (err instanceof ToolErrorCarrier) throw err;
+      throw new ToolErrorCarrier({
+        kind: "upstream_unavailable",
+        message: `SAM description fetch for ${finalUrl} failed: ${(err as Error).message}. This is an outage, not an absent description. Retry.`,
+        retryable: true,
+        retryAfterSeconds: 30,
+        upstreamEndpoint: "sam:description",
+      });
     }
   }
 
@@ -288,14 +359,41 @@ export class SamGovClient {
     url.searchParams.set("sort", "-modifiedDate");
     url.searchParams.set("size", String(filters.limit ?? 25));
     url.searchParams.set("is_active", "true");
+    // Keyless HAL facet params — VERIFIED LIVE (2026-07). The list endpoint
+    // honors these server-side: result counts drop correctly AND every returned
+    // notice's detail matches the filter (e.g. naics=236220 → all hits carry
+    // primary NAICS 236220). The param NAMES differ from the authenticated v2
+    // API's, and a wrong name is SILENTLY IGNORED (returns the full firehose):
+    //   NAICS         → `naics`     (NOT `naics_code`/`ncode` — both ignored)
+    //   place-of-perf → `pop_state` (NOT `place_of_performance_state`; value
+    //                                must be the UPPER-CASE 2-letter code)
+    //   set-aside     → `set_aside` (repeatable; SAM codes: SBA/8A/HZS/HZC/
+    //                                SDVOSBC/WOSB/EDWOSB/VSA/VSS — all verified)
+    //   keyword       → `q`
+    // Organization-name has NO keyless filter param (organization_name and
+    // organizationName are both ignored) — sent best-effort; the tool's `_meta`
+    // flags it as dropped so the AI never treats the set as org-filtered.
     if (filters.query) url.searchParams.set("q", filters.query);
-    if (filters.ncode) url.searchParams.append("naics_code", filters.ncode);
+    if (filters.ncode) url.searchParams.append("naics", filters.ncode);
     if (filters.organizationName)
       url.searchParams.set("organization_name", filters.organizationName);
     if (filters.setAside?.length)
       for (const sa of filters.setAside) url.searchParams.append("set_aside", sa);
     if (filters.state)
-      url.searchParams.set("place_of_performance_state", filters.state);
+      url.searchParams.set("pop_state", filters.state.toUpperCase());
+    // Notice-type facet — VERIFIED LIVE (2026-07): the keyless list endpoint
+    // filters SERVER-SIDE on `notice_type` (comma-joined multi-value). Codes:
+    // r=Sources Sought, p=Presolicitation, s=Special Notice, k=Combined
+    // Synopsis/Solicitation, i=Intent to Bundle, u=Justification(J&A),
+    // o=Solicitation, a=Award. (e.g. notice_type=r → 3,641; r,p,s → 10,603;
+    // p&naics=541512 → 8 — counts drop correctly and every row matches.) The
+    // keyless param is `notice_type` — NOT `ptype` (the AUTHENTICATED endpoint's
+    // name, sent by buildAuthSearchUrl). ADDITIVE: existing callers that don't
+    // set `ptype` (e.g. sam_search_opportunities) send nothing here, so their
+    // behavior is UNCHANGED. Powers the pre-solicitation shaping radar
+    // (sam_search_shaping).
+    if (filters.ptype?.length)
+      url.searchParams.set("notice_type", filters.ptype.join(","));
 
     const r = await this.fetchImpl(url.toString(), {
       headers: this.publicHeaders(),
@@ -317,7 +415,21 @@ export class SamGovClient {
         }[];
       };
     };
-    const totalRecords = json.page?.totalElements ?? 0;
+    // A 200 whose body lacks a well-formed HAL `page` block is NOT a genuine
+    // zero — it's a hollow/degraded response (a CloudFront/Envoy cached error
+    // envelope, a `{"message":"Access Denied"}` 200, or a dropped-`page` proxy
+    // body; the endpoint sits behind CloudFront→istio-envoy). A GENUINE empty
+    // result always carries `page.totalElements` (0); a healthy hit carries a
+    // positive one. So treat a non-finite `totalElements` as an OUTAGE (throw)
+    // — searchOpportunities' catch then marks it `degraded` instead of emitting
+    // the "0 notices, complete" lie. Mirrors far.ts's hollow-200 guard.
+    const totalElements = json.page?.totalElements;
+    if (!Number.isFinite(totalElements)) {
+      throw new Error(
+        "SAM.gov public search returned HTTP 200 without a valid page.totalElements — hollow/degraded body, not a genuine zero.",
+      );
+    }
+    const totalRecords = totalElements as number;
     const results = json._embedded?.results ?? [];
     const data: SamOpportunity[] = results.map((r) => {
       const hierarchy = (r.organizationHierarchy ?? [])
@@ -355,8 +467,57 @@ export class SamGovClient {
     noticeId: string,
   ): Promise<SamOpportunity | null> {
     const url = `${PUBLIC_BASE}/opps/v2/opportunities/${encodeURIComponent(noticeId)}`;
-    const r = await this.fetchImpl(url, { headers: this.publicHeaders() });
-    if (!r.ok) return null;
+    // A network-level fault (DNS/socket/timeout) must surface as a classified
+    // retryable outage, NOT collapse to null (which the wrapper renders as
+    // "notice not found"). Mirrors far.ts/fetchWithRetry's network branch.
+    let r: Response;
+    try {
+      r = await this.fetchImpl(url, { headers: this.publicHeaders() });
+    } catch (err) {
+      throw new ToolErrorCarrier({
+        kind: "upstream_unavailable",
+        message: `Network error reaching the SAM detail endpoint for ${noticeId}: ${(err as Error).message}. This is an outage, not a confirmed absence. Retry.`,
+        retryable: true,
+        retryAfterSeconds: 30,
+        upstreamEndpoint: "sam:opps/v2/opportunities",
+      });
+    }
+    // LIVE-GROUNDED mapping (re-verified 2026-07-04): a real 32-hex id → 200 +
+    // data2.title, STABLE; the endpoint's ABSENT vocabulary (across ~20 bogus/
+    // malformed/hostile ids, incl. SQLi/XSS/traversal) is STRICTLY:
+    //   • 401 UNAUTHORIZED "Error occured while get..." (most bogus/malformed ids)
+    //   • 400 BAD_REQUEST  "Record not found / Invalid request data"
+    //   • 404 (documented not-found)
+    // and its OUTAGE vocabulary is 5xx (a hostile payload live-returned a 502).
+    // 403 was NEVER emitted; a 403 here would be a CDN/WAF block = an OUTAGE, not
+    // an absence. So ONLY the three CONFIRMED absent statuses {400,401,404} → null
+    // (→ wrapper found:false); 429 → rate_limited (a retryable throttle, not an
+    // absence); and EVERY OTHER non-2xx — 403, other 4xx (410/422/451/…), all 5xx,
+    // network, timeout, hollow-200 — THROWS upstream_unavailable. This honors the
+    // invariant "a DOWN service must NEVER read as absent" and errs toward
+    // retryable-outage for any ambiguous status (the safe direction: a spurious
+    // "retry" is far less harmful than a fabricated "does not exist").
+    if (r.status === 429) {
+      throw new ToolErrorCarrier({
+        kind: "rate_limited",
+        message: `SAM detail endpoint rate-limited (HTTP 429) for ${noticeId}. Retry after a short back-off.`,
+        retryable: true,
+        retryAfterSeconds: 30,
+        upstreamStatus: 429,
+        upstreamEndpoint: "sam:opps/v2/opportunities",
+      });
+    }
+    if (r.status === 400 || r.status === 401 || r.status === 404) return null;
+    if (!r.ok) {
+      throw new ToolErrorCarrier({
+        kind: "upstream_unavailable",
+        message: `SAM detail endpoint returned HTTP ${r.status} for ${noticeId} — the service is unavailable, NOT a confirmed absence. Retry.`,
+        retryable: true,
+        retryAfterSeconds: 60,
+        upstreamStatus: r.status,
+        upstreamEndpoint: "sam:opps/v2/opportunities",
+      });
+    }
     type DetailResp = {
       data2?: {
         title?: string;
@@ -380,13 +541,57 @@ export class SamGovClient {
       };
       description?: { body?: string }[];
     };
-    const detail = (await r.json()) as DetailResp;
+    let detail: DetailResp;
+    try {
+      detail = (await r.json()) as DetailResp;
+    } catch (err) {
+      // A 200 whose body won't parse is a hollow/degraded response (CDN/proxy),
+      // NOT a genuine absence — classify as a retryable outage.
+      throw new ToolErrorCarrier({
+        kind: "upstream_unavailable",
+        message: `SAM detail endpoint returned HTTP 200 for ${noticeId} but the body could not be parsed as JSON (${(err as Error).message}) — hollow/degraded response, NOT a confirmed absence. Retry.`,
+        retryable: true,
+        retryAfterSeconds: 60,
+        upstreamStatus: 200,
+        upstreamEndpoint: "sam:opps/v2/opportunities",
+      });
+    }
     const d = detail.data2 ?? {};
-    if (!d.title) return null;
+    // A 200 WITHOUT a usable notice body (no data2.title) is a hollow/degraded
+    // response — a CDN/proxy cached error envelope or dropped body — NOT a real
+    // "this notice does not exist". Real notices are stably 200+title; absent
+    // ids 401. So THROW (retryable), mirroring the searchPublic/far hollow-200
+    // guards, instead of returning null (which the wrapper would render as
+    // found:false — a fabricated absence over an outage).
+    if (!d.title) {
+      throw new ToolErrorCarrier({
+        kind: "upstream_unavailable",
+        message: `SAM detail returned HTTP 200 without a usable notice body (no data2.title) for ${noticeId} — hollow/degraded response, NOT a confirmed absence. Retry.`,
+        retryable: true,
+        retryAfterSeconds: 60,
+        upstreamStatus: 200,
+        upstreamEndpoint: "sam:opps/v2/opportunities",
+      });
+    }
+    // Each enrichment sub-fetch is caught INDIVIDUALLY: an outage on one must
+    // neither sink the notice (the primary fields still return) nor silently
+    // zero the field (a swallowed `[]`/`""` would read as "no attachments"/"no
+    // org"). We record WHICH bucket degraded so the wrapper can disclose an
+    // honest `_meta.degraded` + a note ("MAY have attachments; retry — NOT a
+    // confirmation it has none"), and never flag the OTHER (healthy) enrichment.
+    const enrichmentDegraded: string[] = [];
     const [resourceLinks, fullParentPathName] = await Promise.all([
-      this.getPublicResourceLinks(noticeId),
+      this.getPublicResourceLinks(noticeId).catch((e) => {
+        this.warn("resourceLinks enrichment failed", e);
+        enrichmentDegraded.push("attachments");
+        return [] as string[];
+      }),
       d.organizationId
-        ? this.getPublicOrgName(d.organizationId)
+        ? this.getPublicOrgName(d.organizationId).catch((e) => {
+            this.warn("orgName enrichment failed", e);
+            enrichmentDegraded.push("organization");
+            return "";
+          })
         : Promise.resolve(""),
     ]);
     return {
@@ -410,54 +615,71 @@ export class SamGovClient {
       pointOfContact: d.pointOfContact ?? [],
       uiLink: `https://sam.gov/opp/${noticeId}/view`,
       resourceLinks,
+      enrichmentDegraded: enrichmentDegraded.length
+        ? enrichmentDegraded
+        : undefined,
     };
   }
 
+  /**
+   * Fetch the public attachment-download URLs for a notice.
+   *
+   * TRUTHFULNESS (DOWN-reads-as-absent guard): this is called ONLY after the
+   * detail endpoint already 200'd (the notice exists). The resources endpoint
+   * then returns HTTP 200 for every real notice — a genuine NO-attachment
+   * notice is 200 with an empty list. So any non-200 (or a network fault) here
+   * is an OUTAGE, never a genuine "no attachments", and MUST NOT be swallowed
+   * into `[]` — that would let a DOWN list-fetch read as "no documents" and an
+   * AI skip a solicitation whose RFP it could have read. We THROW on non-200
+   * and let a network error propagate; the caller (getOpportunityPublic / the
+   * auth tier) catches it INDIVIDUALLY and records the degradation. A 200 →
+   * the genuine links, which MAY be `[]` (an honest empty, disclosed as such).
+   */
   private async getPublicResourceLinks(noticeId: string): Promise<string[]> {
-    try {
-      const url = `${PUBLIC_BASE}/opps/v3/opportunities/${encodeURIComponent(noticeId)}/resources`;
-      const r = await this.fetchImpl(url, { headers: this.publicHeaders() });
-      if (!r.ok) return [];
-      type Resp = {
-        _embedded?: {
-          opportunityAttachmentList?: {
-            attachments?: { resourceId?: string; name?: string }[];
-          }[];
-        };
+    const url = `${PUBLIC_BASE}/opps/v3/opportunities/${encodeURIComponent(noticeId)}/resources`;
+    const r = await this.fetchImpl(url, { headers: this.publicHeaders() });
+    if (!r.ok) throw new Error(`resources HTTP ${r.status}`);
+    type Resp = {
+      _embedded?: {
+        opportunityAttachmentList?: {
+          attachments?: { resourceId?: string; name?: string }[];
+        }[];
       };
-      const json = (await r.json()) as Resp;
-      const attachments =
-        json._embedded?.opportunityAttachmentList?.[0]?.attachments ?? [];
-      return attachments
-        .filter((a) => a.resourceId)
-        .map((a) => this.publicDownloadUrl(a.resourceId!));
-    } catch (err) {
-      this.warn("getPublicResourceLinks failed", err);
-      return [];
-    }
+    };
+    const json = (await r.json()) as Resp;
+    const attachments =
+      json._embedded?.opportunityAttachmentList?.[0]?.attachments ?? [];
+    return attachments
+      .filter((a) => a.resourceId)
+      .map((a) => this.publicDownloadUrl(a.resourceId!));
   }
 
+  /**
+   * Resolve an awarding-organization id to its canonical path/name.
+   *
+   * TRUTHFULNESS (same guard as getPublicResourceLinks): a genuine org with no
+   * path → 200 + empty field; a non-200/network fault → an OUTAGE. Do NOT
+   * swallow the outage into `""` (that reads as "no organization" when the
+   * fetch was DOWN). THROW on non-200; let a network error propagate. The
+   * caller catches it INDIVIDUALLY and records the degradation. A 200 → the
+   * name, which MAY be `""` (an honest empty).
+   */
   private async getPublicOrgName(orgId: string): Promise<string> {
-    try {
-      const url = `${PUBLIC_BASE}/federalorganizations/v1/organizations/${encodeURIComponent(orgId)}`;
-      const r = await this.fetchImpl(url, { headers: this.publicHeaders() });
-      if (!r.ok) return "";
-      type Resp = {
-        _embedded?: {
-          org?: {
-            fullParentPathName?: string;
-            agencyName?: string;
-            name?: string;
-          };
-        }[];
-      };
-      const json = (await r.json()) as Resp;
-      const org = json._embedded?.[0]?.org;
-      return org?.fullParentPathName ?? org?.agencyName ?? org?.name ?? "";
-    } catch (err) {
-      this.warn("getPublicOrgName failed", err);
-      return "";
-    }
+    const url = `${PUBLIC_BASE}/federalorganizations/v1/organizations/${encodeURIComponent(orgId)}`;
+    const r = await this.fetchImpl(url, { headers: this.publicHeaders() });
+    if (!r.ok) throw new Error(`org HTTP ${r.status}`);
+    type Resp = {
+      _embedded?: {
+        org?: {
+          fullParentPathName?: string;
+          agencyName?: string;
+          name?: string;
+        };
+      }[];
+    };
+    const json = (await r.json()) as Resp;
+    const org = json._embedded?.[0]?.org;
+    return org?.fullParentPathName ?? org?.agencyName ?? org?.name ?? "";
   }
 
   private publicHeaders(): HeadersInit {
@@ -472,6 +694,66 @@ export class SamGovClient {
   }
 }
 
+// ─── Shaping-radar pure helpers (exported for offline unit testing) ──────────
+
+/**
+ * Whole days from `now` to an ISO `responseDeadline`. Returns null when the
+ * deadline is missing/unparseable (a null day count is COUNTED, never hidden —
+ * the shaping radar surfaces deadline-less notices rather than dropping them).
+ * Uses UTC-midnight flooring on both ends so the count is a stable whole number
+ * regardless of intraday time-of-day. Negative when the deadline is in the past.
+ */
+export function daysUntilResponse(
+  deadline: string | null | undefined,
+  now: Date = new Date(),
+): number | null {
+  if (!deadline) return null;
+  const then = new Date(deadline);
+  const t = then.getTime();
+  if (Number.isNaN(t)) return null;
+  const dayMs = 86_400_000;
+  const nowUtc = Date.UTC(
+    now.getUTCFullYear(),
+    now.getUTCMonth(),
+    now.getUTCDate(),
+  );
+  const thenUtc = Date.UTC(
+    then.getUTCFullYear(),
+    then.getUTCMonth(),
+    then.getUTCDate(),
+  );
+  return Math.round((thenUtc - nowUtc) / dayMs);
+}
+
+/**
+ * Client-side response-deadline WINDOW filter for the shaping radar.
+ *
+ * The keyless SGS feed IGNORES rdlfrom/rdlto (VERIFIED LIVE 2026-07: a
+ * notice_type=r query with rdlfrom/rdlto returns the same total and deadlines
+ * outside the requested window), so a response-deadline window MUST be applied
+ * over the already-fetched page and DISCLOSED (the server flags
+ * `_meta.filtersDropped:["responseDeadline"]`). Bounds are inclusive ISO dates.
+ *
+ * A notice with NO deadline is EXCLUDED from a windowed query (it cannot be
+ * proven inside the window) — the caller discloses this. When neither bound is
+ * given, the page is returned unchanged (no window requested).
+ */
+export function applyResponseDeadlineWindow<
+  T extends { responseDeadline?: string | null },
+>(notices: T[], from?: string, to?: string): T[] {
+  if (!from && !to) return notices;
+  const fromMs = from ? Date.parse(from) : null;
+  const toMs = to ? Date.parse(to) : null;
+  return notices.filter((n) => {
+    if (!n.responseDeadline) return false; // no deadline ⇒ not provably in-window
+    const ms = Date.parse(n.responseDeadline);
+    if (Number.isNaN(ms)) return false;
+    if (fromMs !== null && !Number.isNaN(fromMs) && ms < fromMs) return false;
+    if (toMs !== null && !Number.isNaN(toMs) && ms > toMs) return false;
+    return true;
+  });
+}
+
 // ─── Helpers ────────────────────────────────────────────────────
 
 function formatSamDate(date: Date): string {

package/src/sam-gov/index.ts

@@ -14,7 +14,11 @@
  *
  * Canonical home: https://github.com/cliwant/mcp-sam-gov
  */
-export { SamGovClient } from "./client.js";
+export {
+  SamGovClient,
+  daysUntilResponse,
+  applyResponseDeadlineWindow,
+} from "./client.js";
 export type {
   SamOpportunity,
   SamSearchFilters,

package/src/sam-gov/types.ts

@@ -75,6 +75,17 @@ export type SamOpportunity = {
   placeOfPerformance?: SamLocation | null;
   uiLink?: string;
   resourceLinks?: string[] | null;
+  /**
+   * Which enrichment sub-fetches DEGRADED on an outage (subset of
+   * ["attachments", "organization"]). Set ONLY when a sub-fetch's HTTP call
+   * failed (non-200 / network / timeout) — the corresponding field
+   * (`resourceLinks` / `fullParentPathName`) is then empty but UNKNOWN, NOT
+   * confirmed-absent. Additive + optional: a healthy notice (incl. a genuine
+   * 200-empty attachment list or empty org path) NEVER sets it. Tool wrappers
+   * read it to emit an honest `_meta.degraded` + a disclosing note instead of
+   * a silent "no attachments"/"no organization" lie.
+   */
+  enrichmentDegraded?: string[];
 };
 
 export type SamSearchFilters = {
@@ -100,6 +111,17 @@ export type SamSearchResult = {
   limit: number;
   offset: number;
   opportunitiesData: SamOpportunity[];
+  /**
+   * Set ONLY when the search could not run at all (every access tier threw:
+   * HAL down / network / 5xx-after-retry). It disambiguates a TOTAL OUTAGE
+   * from a GENUINE zero — both otherwise present as
+   * `{ totalRecords: 0, opportunitiesData: [] }`. Additive + optional:
+   * existing readers that ignore it are unaffected; a healthy search (incl.
+   * a real 0 or an empty page past the end) NEVER sets it. Tool wrappers use
+   * it to emit an honest `_meta` (`complete:false`, `totalAvailable:null`,
+   * a disclosing note) instead of the silent "0 notices, complete" lie.
+   */
+  degraded?: { reason: string };
 };
 
 export type EntitySearchResult = {