@cliwant/mcp-sam-gov 0.3.0 → 1.0.0

package/dist/fac.js

@@ -0,0 +1,416 @@
+/**
+ * fac.ts — CMS/GSA Federal Audit Clearinghouse (FAC) Single Audit vetting
+ * (ADR-0038). A NEW keyless PostgREST adapter over `api.fac.gov` (fronted by
+ * api.data.gov), housing TWO purpose-built audit-RISK vetting tools:
+ *   - `fac_search_audits`  — the `general` table (entity Single Audit summaries)
+ *   - `fac_get_findings`   — the `findings` table (the audit-RISK flags)
+ * The B2G unlock: before teaming with / subcontracting to a partner, vet their
+ * Single Audit RISK (material weaknesses, questioned costs, repeat findings,
+ * modified opinions) — joinable to SAM/USAspending/EDGAR by UEI/EIN. DISTINCT
+ * from `src/far.ts` (FAR clause compliance — no filename / gate-key collision).
+ *
+ * ★ KEYLESS-FIRST via the DEMO_KEY doctrine (the 3rd consumer of `datagovKey.ts`
+ * after datagov.ts + govinfo.ts). A bare api.fac.gov request → HTTP 403
+ * (API_KEY_MISSING); the SAME request + `X-Api-Key: DEMO_KEY` → 200/206 real
+ * data. `keyHeader()` places the secret in the `X-Api-Key` header ONLY (never the
+ * URL / label / _meta / a log); `resolvedKey()` falls back to the public literal
+ * "DEMO_KEY" when DATA_GOV_API_KEY is unset. `keylessMode:false` (honest — it
+ * genuinely sends a key, exactly like datagov.ts/govinfo.ts); `_meta.source`
+ * discloses the key-MODE only.
+ *
+ * R2 consumer — reuses the shared port: `getJsonWithHeaders` (ADR-0038 M1 — the
+ * header-exposing sibling of getJson; the EXACT total is a RESPONSE HEADER, not a
+ * body field), `driftError` / `throughGate` (datasource.ts), `num`·`str`
+ * (coerce.ts), `withMeta` (meta.ts). It writes ZERO bespoke fetch — a hand-rolled
+ * fetch inside fac.ts would re-open `redirect:"error"` (a 3xx off api.fac.gov
+ * carrying the X-Api-Key to a foreign host = key egress), the hostname/https
+ * assert, and `keyHeader()` placement, all of which the shared port keeps
+ * structurally present and ADR-0007-K-test-covered.
+ *
+ * ★ HONESTY (P1–P4; ADR §Q2 + the v2 review):
+ *   (P1) The EXACT total is the `Content-Range` denominator (a RESPONSE HEADER
+ *     under `Prefer: count=exact`; 206-on-subset). `parseTotal` takes the
+ *     substring after the LAST `/`; a run of digits → num() EXACT; a `*`
+ *     ("count not computed") / non-number / absent header → totalAvailable:null +
+ *     a page-fullness `hasMore = returned >= limit` hedge + a disclosed note —
+ *     NEVER 0 (the null-never-0 rule applied to a header).
+ *   (P2) A genuine `[]` → honest empty (+ the M2 empty-findings note); a body
+ *     that is not a JSON array → driftError. 400/403/5xx/timeout/off-host-redirect
+ *     THROW via the port taxonomy (206 = success — `r.ok` covers 200-299). An
+ *     HTML/non-JSON 200 (r.json() SyntaxError) → reclassified to schema_drift
+ *     (S1) — never a fake empty.
+ *   (P3) `total_amount_expended` is a JSON number → num() null-never-0. The `is_*`
+ *     risk flags are STRINGS "Y"/"N" — surfaced verbatim (str → "Y"/"N"/null) AND
+ *     mapped to a tri-state `riskFlags` object ("Y"→true / "N"→false / blank /
+ *     absent / other → null=UNKNOWN). A null flag must NEVER read as false/"no
+ *     material weakness" (the OFAC/sam_check_exclusions false-CLEAR class).
+ *   (P4) Filters are server-side + self-policing: each caller filter maps to a
+ *     KNOWN column + a FIXED operator, value-validated + URLSearchParams-encoded;
+ *     a valid filter narrows the Content-Range total, a bad column → PostgREST 400
+ *     → invalid_input. So `filtersDropped` is ALWAYS empty (no silent-drop path).
+ *
+ * ★ THE PII CRUX (load-bearing — §PII boundary, LIVE-confirmed SOUND): the
+ * `select=` is a HARDCODED MODULE CONSTANT allowlist that SURFACES only entity +
+ * audit-risk fields and EXCLUDES all 6 personal-contact columns (auditee_email,
+ * auditee_phone, auditee_certify_name, auditee_certify_title, auditee_contact_name,
+ * auditee_contact_title). PostgREST WILL project auditee_email the instant
+ * `select=` names it (live-verified), so the tools accept NO caller-supplied
+ * `select`/`order`/free-column param — the inputs are ONLY structured, validated
+ * filters. Purpose-built tools bake the allowlist in by construction (the reason
+ * v1 rejects a generic `fac_query{select}`). The mapper also picks ONLY the
+ * allowlist keys, so even a drifted server that returns an extra column cannot
+ * leak it into the output.
+ *
+ * ★ SSRF: fixed host `api.fac.gov` (single-entry FAC_HOSTS allowlist + a Set.has
+ * recheck); the table name is a FIXED per-tool path CONSTANT (`general`/`findings`
+ * — never caller free-text); filter values ride URLSearchParams as
+ * `col=eq.VALUE`; `redirect:"error"`; a post-construction hostname/https assert.
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJsonWithHeaders, driftError, throughGate } from "./datasource.js";
+import { num, str } from "./coerce.js";
+import { keyHeader, keyModeLabel, pushKeyNote } from "./datagovKey.js";
+import { withMeta } from "./meta.js";
+// Re-export the shared honesty coercion (single audited copy in ./coerce.js) so
+// the fault suite's num-parity guard resolves fac.num === coerce.num, exactly
+// like fdic.num / cms.num / datagov.num.
+export { num };
+// ─── Constants (SSRF core) ─────────────────────────────────────────
+const FAC_HOST = "api.fac.gov";
+// Single-entry host allowlist (structured for a later host-add; the belt-and-
+// suspenders Set.has recheck runs in getFac).
+export const FAC_HOSTS = [FAC_HOST];
+const FAC_HOST_SET = new Set(FAC_HOSTS);
+// One host = one rate budget. A modest self-throttle — courtesy to a shared
+// api.data.gov-fronted host, doubly warranted by the ~10 req/hr DEMO_KEY ceiling.
+const FAC_MIN_INTERVAL_MS = 200;
+export const FAC_LABEL = "fac:" + FAC_HOST; // → ToolError.upstreamEndpoint (host-only)
+const GATE_KEY = "fac";
+// Fixed table path constants — the TOOL chooses these; NO caller value on the
+// path (SSRF core / no table-injection surface).
+const TABLE_GENERAL = "general";
+const TABLE_FINDINGS = "findings";
+// ★ The HARDCODED positive select-allowlists (the PII crux). These are the ONLY
+// columns ever named on the wire — every personal-contact column
+// (auditee_email/phone/certify_name/certify_title/contact_name/contact_title) is
+// STRUCTURALLY excluded. NO caller can supply a `select`/column param.
+export const GENERAL_SELECT = "report_id,auditee_uei,audit_year,auditee_name,auditee_ein,auditee_state,auditee_city,total_amount_expended,fac_accepted_date";
+export const FINDINGS_SELECT = "report_id,auditee_uei,audit_year,award_reference,reference_number,is_material_weakness,is_modified_opinion,is_questioned_costs,is_repeat_finding,is_significant_deficiency,is_other_findings,is_other_matters,type_requirement,prior_finding_ref_numbers";
+// Fixed default orders (deterministic offset windows; never caller-derived).
+const GENERAL_ORDER = "fac_accepted_date.desc";
+const FINDINGS_ORDER = "report_id.asc,reference_number.asc";
+// The 7 audit-RISK flags (STRING "Y"/"N"/blank live) mapped to the tri-state.
+const RISK_FLAG_COLUMNS = [
+    "is_material_weakness",
+    "is_modified_opinion",
+    "is_questioned_costs",
+    "is_repeat_finding",
+    "is_significant_deficiency",
+    "is_other_findings",
+    "is_other_matters",
+];
+// ─── Input grammars (belt-and-suspenders behind the server's Zod schemas — the
+// fault suite calls these functions directly, bypassing Zod, so re-validation
+// here is load-bearing for the SSRF/injection rejects). ────────────
+const UEI_RE = /^[A-Z0-9]{12}$/;
+const STATE_RE = /^[A-Z]{2}$/;
+const REPORT_ID_RE = /^[0-9A-Za-z-]+$/;
+const REPORT_ID_MAX = 64;
+function invalidInput(message) {
+    return new ToolErrorCarrier({ kind: "invalid_input", message, retryable: false });
+}
+// ─── Disclosure constants (honesty obligations — verbatim, fault-asserted) ──
+/**
+ * ★ §PII(d) — the mandatory not-a-determination caveat carried on EVERY response
+ * (mirrors OFAC_NOT_DETERMINATION_NOTE / NPPES_NOT_DETERMINATION_NOTE). Kept
+ * verbatim so the fault suite can assert it.
+ */
+export const FAC_NOT_DETERMINATION_NOTE = "Public Single Audit data (Federal Audit Clearinghouse; 2 CFR 200 Subpart F / Single Audit Act). Reports the independent auditor's findings, opinions, and questioned costs AS SUBMITTED — it is NOT a debarment, suspension, exclusion, or fitness determination, and an audit finding is the auditor's opinion, not proof of wrongdoing (many findings are routine and remediated). This tool DELIBERATELY EXCLUDES the auditee's personal-contact fields (email / phone / certifying-official name) — the vetting subject is the entity, not the individual. Cross-check SAM exclusions + OFAC and read the specific finding text before acting.";
+/** ★ P3 — the risk-flag typing disclosure carried on EVERY fac_get_findings response. */
+export const FAC_VALUE_TYPING_NOTE = "Risk flags (is_material_weakness, is_modified_opinion, is_questioned_costs, is_repeat_finding, is_significant_deficiency, is_other_findings, is_other_matters) are surfaced VERBATIM as the auditor reported them (\"Y\"/\"N\") plus a typed riskFlags tri-state; a blank/absent flag is UNKNOWN (null), NOT a \"no\" — never read a null flag as 'no finding'.";
+/** ★ M2 — the empty-findings ≠ clean-audit disclosure (any totalAvailable:0 / empty findings). */
+export const FAC_EMPTY_FINDINGS_NOTE = "An empty findings list means NO findings are ON RECORD for this UEI/report — it does NOT confirm a clean audit. The entity may not have filed a Single Audit (below the $750K threshold), the audit may predate FAC coverage, or the UEI may be wrong. Confirm the entity has an ACCEPTED audit via fac_search_audits before treating empty as clean.";
+/** P1 — the Content-Range hedge disclosure (a `*`/absent/non-numeric denominator). */
+const FAC_TOTAL_HEDGE_NOTE = "FAC did not return an exact Content-Range total (the denominator was '*', absent, or non-numeric); totalAvailable is UNKNOWN (null) and hasMore is inferred from page-fullness — page via offset until a short page confirms the end (never read this as 0 results).";
+function facSource() {
+    return `${FAC_HOST} via Federal Audit Clearinghouse API (${keyModeLabel()})`;
+}
+// ─── P1 — Content-Range EXACT-total parse (num-guarded, null-never-0) ──
+/**
+ * Parse the EXACT total from `Content-Range: <start>-<end>/<TOTAL>` — take the
+ * substring after the LAST `/` and `num()` it. A run of digits → the EXACT total
+ * (`0` denominator → 0, a genuine-empty total); a `*` (PostgREST "count not
+ * computed") / non-number / absent header → null (NEVER 0 — the null-never-0 rule
+ * on a header). Exported for the Content-Range-matrix fault fixture.
+ */
+export function parseTotal(contentRange) {
+    if (typeof contentRange !== "string")
+        return null;
+    const slash = contentRange.lastIndexOf("/");
+    if (slash < 0)
+        return null;
+    // num("*")→null, num("")→null, num("37144")→37144, num("0")→0 (genuine zero).
+    return num(contentRange.slice(slash + 1).trim());
+}
+// ─── P3 — risk-flag tri-state ("Y"→true / "N"→false / else → null=UNKNOWN) ──
+/**
+ * Map an FAC risk flag to an HONEST tri-state: "Y" → true, "N" → false, and a
+ * null / blank / absent / any-other value → null (UNKNOWN — NEVER false). A null
+ * `is_material_weakness` silently read as "no material weakness" is the false-CLEAR
+ * class OFAC/sam_check_exclusions forbid. Exported for the flag-type fault fixture.
+ */
+export function flagTri(v) {
+    const s = typeof v === "string" ? v.trim().toUpperCase() : v;
+    if (s === "Y")
+        return true;
+    if (s === "N")
+        return false;
+    return null;
+}
+// ─── SSRF-guarded fetch (fixed host + hostname assert + redirect) ──
+/**
+ * GET one FAC PostgREST table through the shared header-exposing port. `table` is
+ * a FIXED per-tool constant (general/findings) — NO caller value on the path. The
+ * key rides `X-Api-Key` ONLY (keyHeader), `Prefer: count=exact` requests the
+ * EXACT total, `redirect:"error"` refuses an off-host 3xx (no key egress), and the
+ * CONSTRUCTED URL's hostname must equal api.fac.gov over https (+ a Set.has
+ * recheck). Returns `{ body, contentRange }`. A 200 non-JSON body (r.json()
+ * SyntaxError, e.g. an HTML maintenance page) is reclassified to schema_drift
+ * (S1); the structured 400/403/429/5xx/timeout taxonomy propagates unchanged.
+ */
+async function getFac(table, params) {
+    const url = `https://${FAC_HOST}/${table}?${params.toString()}`;
+    const built = new URL(url);
+    if (built.hostname !== FAC_HOST ||
+        built.protocol !== "https:" ||
+        !FAC_HOST_SET.has(built.hostname)) {
+        throw invalidInput(`Constructed FAC URL host ${JSON.stringify(built.hostname)} (${built.protocol}) is not ${FAC_HOST} over https — refusing to fetch (SSRF safety).`);
+    }
+    try {
+        return await throughGate(GATE_KEY, FAC_MIN_INTERVAL_MS, () => getJsonWithHeaders(url, {
+            label: FAC_LABEL,
+            headers: { ...keyHeader(), Prefer: "count=exact" },
+            redirect: "error",
+        }));
+    }
+    catch (e) {
+        // Preserve the structured taxonomy (400/403/429/5xx/timeout/off-host-redirect).
+        if (e instanceof ToolErrorCarrier)
+            throw e;
+        // ★ S1 — a 200 non-JSON body makes getJsonWithHeaders' r.json() throw a
+        // SyntaxError → reclassify to schema_drift (an honest THROW, never a fake
+        // empty). The shared port stays byte-identical (reclassification is HERE).
+        if (e instanceof SyntaxError) {
+            throw driftError(FAC_LABEL, "FAC returned a non-JSON body at HTTP 2xx — treating as schema drift.");
+        }
+        throw e;
+    }
+}
+/** Assert the parsed body is a JSON array (P2 drift guard); else driftError. */
+function asArray(body, table) {
+    if (!Array.isArray(body)) {
+        throw driftError(FAC_LABEL, `FAC ${table} returned a non-array body — treating as schema drift (PostgREST returns a bare JSON array; never a fake empty).`);
+    }
+    return body;
+}
+function mapAudit(rec) {
+    return {
+        report_id: str(rec.report_id),
+        auditee_uei: str(rec.auditee_uei),
+        audit_year: str(rec.audit_year), // a STRING live ("2026")
+        auditee_name: str(rec.auditee_name),
+        auditee_ein: str(rec.auditee_ein), // a STRING live ("911767139")
+        auditee_state: str(rec.auditee_state),
+        auditee_city: str(rec.auditee_city),
+        total_amount_expended: num(rec.total_amount_expended), // JSON number, null-never-0
+        fac_accepted_date: str(rec.fac_accepted_date),
+    };
+}
+function mapFinding(rec) {
+    return {
+        report_id: str(rec.report_id),
+        auditee_uei: str(rec.auditee_uei),
+        audit_year: str(rec.audit_year),
+        award_reference: str(rec.award_reference),
+        reference_number: str(rec.reference_number),
+        // Flags surfaced VERBATIM ("Y"/"N"/null — str nulls ""/"null", so a blank
+        // flag is null=UNKNOWN, never "N").
+        is_material_weakness: str(rec.is_material_weakness),
+        is_modified_opinion: str(rec.is_modified_opinion),
+        is_questioned_costs: str(rec.is_questioned_costs),
+        is_repeat_finding: str(rec.is_repeat_finding),
+        is_significant_deficiency: str(rec.is_significant_deficiency),
+        is_other_findings: str(rec.is_other_findings),
+        is_other_matters: str(rec.is_other_matters),
+        type_requirement: str(rec.type_requirement),
+        prior_finding_ref_numbers: str(rec.prior_finding_ref_numbers),
+        riskFlags: {
+            materialWeakness: flagTri(rec.is_material_weakness),
+            modifiedOpinion: flagTri(rec.is_modified_opinion),
+            questionedCosts: flagTri(rec.is_questioned_costs),
+            repeatFinding: flagTri(rec.is_repeat_finding),
+            significantDeficiency: flagTri(rec.is_significant_deficiency),
+            otherFindings: flagTri(rec.is_other_findings),
+            otherMatters: flagTri(rec.is_other_matters),
+        },
+    };
+}
+void RISK_FLAG_COLUMNS; // documented flag inventory (mapper enumerates explicitly)
+// ─── Tool 1: fac_search_audits (the `general` table) ───────────────
+/**
+ * Search entity Single Audit summaries (`/general`). Structured filters (all
+ * optional, AND-combined): `auditeeUei` (^[A-Z0-9]{12}$), `auditeeState`
+ * (^[A-Z]{2}$), `auditYear` (int), `totalExpendedMin`/`totalExpendedMax` (finite
+ * → gte/lte on total_amount_expended). Plus `limit` (1..100, def 25) / `offset`.
+ * The `select=` is the HARDCODED GENERAL_SELECT allowlist (NO personal-contact
+ * columns; NO caller column param). Order is the fixed GENERAL_ORDER.
+ *
+ * HONESTY: totalAvailable is the EXACT Content-Range denominator (P1; a `*`/
+ * absent/non-numeric → null + a page-fullness hedge, never 0); a bad column ⇒
+ * PostgREST 400 ⇒ invalid_input (filtersDropped always empty, P4); a genuine `[]`
+ * ⇒ honest empty; 400/403/5xx/timeout/HTML(SyntaxError)/non-array THROW (P2, 206 =
+ * success). The FAC_NOT_DETERMINATION_NOTE rides every response.
+ */
+export async function searchAudits(args) {
+    const limit = args.limit ?? 25;
+    const offset = args.offset ?? 0;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw invalidInput("fac_search_audits: limit must be an integer in 1..100.");
+    if (!Number.isInteger(offset) || offset < 0)
+        throw invalidInput("fac_search_audits: offset must be an integer ≥ 0.");
+    const params = new URLSearchParams();
+    params.set("select", GENERAL_SELECT); // ★ hardcoded allowlist — never caller-derived
+    const filtersApplied = [];
+    if (args.auditeeUei !== undefined) {
+        if (!UEI_RE.test(args.auditeeUei))
+            throw invalidInput("fac_search_audits: auditeeUei must match ^[A-Z0-9]{12}$ (12-char UEI).");
+        params.append("auditee_uei", `eq.${args.auditeeUei}`);
+        filtersApplied.push("auditeeUei");
+    }
+    if (args.auditeeState !== undefined) {
+        if (!STATE_RE.test(args.auditeeState))
+            throw invalidInput("fac_search_audits: auditeeState must match ^[A-Z]{2}$ (2-letter state).");
+        params.append("auditee_state", `eq.${args.auditeeState}`);
+        filtersApplied.push("auditeeState");
+    }
+    if (args.auditYear !== undefined) {
+        if (!Number.isInteger(args.auditYear))
+            throw invalidInput("fac_search_audits: auditYear must be an integer.");
+        params.append("audit_year", `eq.${args.auditYear}`);
+        filtersApplied.push("auditYear");
+    }
+    if (args.totalExpendedMin !== undefined) {
+        if (!Number.isFinite(args.totalExpendedMin))
+            throw invalidInput("fac_search_audits: totalExpendedMin must be a finite number.");
+        params.append("total_amount_expended", `gte.${args.totalExpendedMin}`);
+        filtersApplied.push("totalExpendedMin");
+    }
+    if (args.totalExpendedMax !== undefined) {
+        if (!Number.isFinite(args.totalExpendedMax))
+            throw invalidInput("fac_search_audits: totalExpendedMax must be a finite number.");
+        params.append("total_amount_expended", `lte.${args.totalExpendedMax}`);
+        filtersApplied.push("totalExpendedMax");
+    }
+    params.set("order", GENERAL_ORDER);
+    params.set("limit", String(limit));
+    params.set("offset", String(offset));
+    const { body, contentRange } = await getFac(TABLE_GENERAL, params);
+    const rows = asArray(body, TABLE_GENERAL).map((r) => mapAudit((r ?? {})));
+    const returned = rows.length;
+    const totalAvailable = parseTotal(contentRange); // EXACT or null
+    const exact = totalAvailable !== null;
+    const hasMore = exact ? offset + returned < totalAvailable : returned >= limit;
+    const nextOffset = hasMore ? offset + returned : null;
+    const notes = [];
+    pushKeyNote(notes);
+    if (!exact)
+        notes.push(FAC_TOTAL_HEDGE_NOTE);
+    notes.push(FAC_NOT_DETERMINATION_NOTE);
+    return withMeta({ audits: rows }, {
+        source: facSource(),
+        keylessMode: false,
+        returned,
+        totalAvailable,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit, hasMore, nextOffset },
+        notes,
+    });
+}
+// ─── Tool 2: fac_get_findings (the `findings` table) ───────────────
+/**
+ * Drill into the audit-RISK findings (`/findings`) for a UEI and/or report. At
+ * least ONE of `auditeeUei` (^[A-Z0-9]{12}$) / `reportId` (^[0-9A-Za-z-]+$) is
+ * REQUIRED (empty → invalid_input, never a no-op full-table scan). Optional
+ * `auditYear` (int), `limit` (1..100, def 50), `offset`. The `select=` is the
+ * HARDCODED FINDINGS_SELECT allowlist (NO caller column param). Order is fixed.
+ *
+ * HONESTY: EXACT Content-Range total (P1); risk flags "Y"/"N" verbatim + the tri-
+ * state riskFlags (P3, null-is-UNKNOWN); a bad column ⇒ 400 ⇒ invalid_input (P4);
+ * 400/403/5xx/timeout/HTML/non-array THROW (P2); a genuine empty ⇒ honest empty +
+ * the ★M2 empty≠clean note. FAC_NOT_DETERMINATION_NOTE + FAC_VALUE_TYPING_NOTE
+ * ride every response.
+ */
+export async function getFindings(args) {
+    const limit = args.limit ?? 50;
+    const offset = args.offset ?? 0;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw invalidInput("fac_get_findings: limit must be an integer in 1..100.");
+    if (!Number.isInteger(offset) || offset < 0)
+        throw invalidInput("fac_get_findings: offset must be an integer ≥ 0.");
+    if (args.auditeeUei === undefined && args.reportId === undefined)
+        throw invalidInput("fac_get_findings: at least one of auditeeUei or reportId is REQUIRED (an empty query would scan the whole 670K-row findings table — refused).");
+    const params = new URLSearchParams();
+    params.set("select", FINDINGS_SELECT); // ★ hardcoded allowlist — never caller-derived
+    const filtersApplied = [];
+    if (args.auditeeUei !== undefined) {
+        if (!UEI_RE.test(args.auditeeUei))
+            throw invalidInput("fac_get_findings: auditeeUei must match ^[A-Z0-9]{12}$ (12-char UEI).");
+        params.append("auditee_uei", `eq.${args.auditeeUei}`);
+        filtersApplied.push("auditeeUei");
+    }
+    if (args.reportId !== undefined) {
+        if (!REPORT_ID_RE.test(args.reportId) || args.reportId.length > REPORT_ID_MAX)
+            throw invalidInput(`fac_get_findings: reportId must match ^[0-9A-Za-z-]+$ (≤ ${REPORT_ID_MAX} chars).`);
+        params.append("report_id", `eq.${args.reportId}`);
+        filtersApplied.push("reportId");
+    }
+    if (args.auditYear !== undefined) {
+        if (!Number.isInteger(args.auditYear))
+            throw invalidInput("fac_get_findings: auditYear must be an integer.");
+        params.append("audit_year", `eq.${args.auditYear}`);
+        filtersApplied.push("auditYear");
+    }
+    params.set("order", FINDINGS_ORDER);
+    params.set("limit", String(limit));
+    params.set("offset", String(offset));
+    const { body, contentRange } = await getFac(TABLE_FINDINGS, params);
+    const rows = asArray(body, TABLE_FINDINGS).map((r) => mapFinding((r ?? {})));
+    const returned = rows.length;
+    const totalAvailable = parseTotal(contentRange);
+    const exact = totalAvailable !== null;
+    const hasMore = exact ? offset + returned < totalAvailable : returned >= limit;
+    const nextOffset = hasMore ? offset + returned : null;
+    const notes = [];
+    pushKeyNote(notes);
+    if (!exact)
+        notes.push(FAC_TOTAL_HEDGE_NOTE);
+    // ★ M2 — an empty findings result is an AMBIGUOUS false-CLEAR; disclose that
+    // empty ≠ clean audit (fires on any empty page / totalAvailable:0).
+    if (returned === 0 || totalAvailable === 0)
+        notes.push(FAC_EMPTY_FINDINGS_NOTE);
+    notes.push(FAC_VALUE_TYPING_NOTE, FAC_NOT_DETERMINATION_NOTE);
+    return withMeta({ findings: rows }, {
+        source: facSource(),
+        keylessMode: false,
+        returned,
+        totalAvailable,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit, hasMore, nextOffset },
+        notes,
+    });
+}
+//# sourceMappingURL=fac.js.map

package/dist/fac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fac.js","sourceRoot":"","sources":["../src/fac.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAsC,MAAM,WAAW,CAAC;AAEzE,gFAAgF;AAChF,8EAA8E;AAC9E,yCAAyC;AACzC,OAAO,EAAE,GAAG,EAAE,CAAC;AAEf,sEAAsE;AACtE,MAAM,QAAQ,GAAG,aAAa,CAAC;AAC/B,8EAA8E;AAC9E,8CAA8C;AAC9C,MAAM,CAAC,MAAM,SAAS,GAAsB,CAAC,QAAQ,CAAC,CAAC;AACvD,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;AAC7D,4EAA4E;AAC5E,kFAAkF;AAClF,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAChC,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC,2CAA2C;AACvF,MAAM,QAAQ,GAAG,KAAK,CAAC;AAEvB,8EAA8E;AAC9E,iDAAiD;AACjD,MAAM,aAAa,GAAG,SAAS,CAAC;AAChC,MAAM,cAAc,GAAG,UAAU,CAAC;AAElC,gFAAgF;AAChF,iEAAiE;AACjE,iFAAiF;AACjF,uEAAuE;AACvE,MAAM,CAAC,MAAM,cAAc,GACzB,8HAA8H,CAAC;AACjI,MAAM,CAAC,MAAM,eAAe,GAC1B,0PAA0P,CAAC;AAE7P,6EAA6E;AAC7E,MAAM,aAAa,GAAG,wBAAwB,CAAC;AAC/C,MAAM,cAAc,GAAG,oCAAoC,CAAC;AAE5D,8EAA8E;AAC9E,MAAM,iBAAiB,GAAG;IACxB,sBAAsB;IACtB,qBAAqB;IACrB,qBAAqB;IACrB,mBAAmB;IACnB,2BAA2B;IAC3B,mBAAmB;IACnB,kBAAkB;CACV,CAAC;AAEX,gFAAgF;AAChF,8EAA8E;AAC9E,qEAAqE;AACrE,MAAM,MAAM,GAAG,gBAAgB,CAAC;AAChC,MAAM,QAAQ,GAAG,YAAY,CAAC;AAC9B,MAAM,YAAY,GAAG,iBAAiB,CAAC;AACvC,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,SAAS,YAAY,CAAC,OAAe;IACnC,OAAO,IAAI,gBAAgB,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AACpF,CAAC;AAED,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GACrC,onBAAonB,CAAC;AAEvnB,yFAAyF;AACzF,MAAM,CAAC,MAAM,qBAAqB,GAChC,iWAAiW,CAAC;AAEpW,kGAAkG;AAClG,MAAM,CAAC,MAAM,uBAAuB,GAClC,uVAAuV,CAAC;AAE1V,sFAAsF;AACtF,MAAM,oBAAoB,GACxB,sQAAsQ,CAAC;AAEzQ,SAAS,SAAS;IAChB,OAAO,GAAG,QAAQ,yCAAyC,YAAY,EAAE,GAAG,CAAC;AAC/E,CAAC;AAED,0EAA0E;AAC1E;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,YAA2B;IACpD,IAAI,OAAO,YAAY,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAClD,MAAM,KAAK,GAAG,YAAY,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC5C,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3B,8EAA8E;IAC9E,OAAO,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,+EAA+E;AAC/E;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,CAAU;IAChC,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,IAAI,CAAC;AACd,CAAC;AAED,sEAAsE;AACtE;;;;;;;;;GASG;AACH,KAAK,UAAU,MAAM,CACnB,KAAa,EACb,MAAuB;IAEvB,MAAM,GAAG,GAAG,WAAW,QAAQ,IAAI,KAAK,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;IAChE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,IACE,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAC3B,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAC3B,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,EACjC,CAAC;QACD,MAAM,YAAY,CAChB,4BAA4B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,KAAK,CAAC,QAAQ,YAAY,QAAQ,gDAAgD,CAClJ,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,WAAW,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG,EAAE,CAC3D,kBAAkB,CAAC,GAAG,EAAE;YACtB,KAAK,EAAE,SAAS;YAChB,OAAO,EAAE,EAAE,GAAG,SAAS,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE;YAClD,QAAQ,EAAE,OAAO;SAClB,CAAC,CACH,CAAC;IACJ,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,gFAAgF;QAChF,IAAI,CAAC,YAAY,gBAAgB;YAAE,MAAM,CAAC,CAAC;QAC3C,wEAAwE;QACxE,0EAA0E;QAC1E,2EAA2E;QAC3E,IAAI,CAAC,YAAY,WAAW,EAAE,CAAC;YAC7B,MAAM,UAAU,CACd,SAAS,EACT,sEAAsE,CACvE,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,SAAS,OAAO,CAAC,IAAa,EAAE,KAAa;IAC3C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,UAAU,CACd,SAAS,EACT,OAAO,KAAK,kHAAkH,CAC/H,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAgBD,SAAS,QAAQ,CAAC,GAA4B;IAC5C,OAAO;QACL,SAAS,EAAE,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC;QAC7B,WAAW,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC;QACjC,UAAU,EAAE,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,yBAAyB;QAC1D,YAAY,EAAE,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC;QACnC,WAAW,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,8BAA8B;QACjE,aAAa,EAAE,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC;QACrC,YAAY,EAAE,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC;QACnC,qBAAqB,EAAE,GAAG,CAAC,GAAG,CAAC,qBAAqB,CAAC,EAAE,4BAA4B;QACnF,iBAAiB,EAAE,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC;KAC9C,CAAC;AACJ,CAAC;AA6BD,SAAS,UAAU,CAAC,GAA4B;IAC9C,OAAO;QACL,SAAS,EAAE,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC;QAC7B,WAAW,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC;QACjC,UAAU,EAAE,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC;QAC/B,eAAe,EAAE,GAAG,CAAC,GAAG,CAAC,eAAe,CAAC;QACzC,gBAAgB,EAAE,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC;QAC3C,0EAA0E;QAC1E,oCAAoC;QACpC,oBAAoB,EAAE,GAAG,CAAC,GAAG,CAAC,oBAAoB,CAAC;QACnD,mBAAmB,EAAE,GAAG,CAAC,GAAG,CAAC,mBAAmB,CAAC;QACjD,mBAAmB,EAAE,GAAG,CAAC,GAAG,CAAC,mBAAmB,CAAC;QACjD,iBAAiB,EAAE,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAC7C,yBAAyB,EAAE,GAAG,CAAC,GAAG,CAAC,yBAAyB,CAAC;QAC7D,iBAAiB,EAAE,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAC7C,gBAAgB,EAAE,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC;QAC3C,gBAAgB,EAAE,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC;QAC3C,yBAAyB,EAAE,GAAG,CAAC,GAAG,CAAC,yBAAyB,CAAC;QAC7D,SAAS,EAAE;YACT,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;YACnD,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;YACjD,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;YACjD,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;YAC7C,qBAAqB,EAAE,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;YAC7D,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;YAC7C,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;SAC5C;KACF,CAAC;AACJ,CAAC;AACD,KAAK,iBAAiB,CAAC,CAAC,2DAA2D;AAEnF,sEAAsE;AACtE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAQlC;IACC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,GAAG;QACtD,MAAM,YAAY,CAAC,wDAAwD,CAAC,CAAC;IAC/E,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC;QACzC,MAAM,YAAY,CAAC,mDAAmD,CAAC,CAAC;IAE1E,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,+CAA+C;IACrF,MAAM,cAAc,GAAa,EAAE,CAAC;IAEpC,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC;YAC/B,MAAM,YAAY,CAAC,wEAAwE,CAAC,CAAC;QAC/F,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACtD,cAAc,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC;YACnC,MAAM,YAAY,CAAC,yEAAyE,CAAC,CAAC;QAChG,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QAC1D,cAAc,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC;YACnC,MAAM,YAAY,CAAC,kDAAkD,CAAC,CAAC;QACzE,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QACpD,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC;YACzC,MAAM,YAAY,CAAC,8DAA8D,CAAC,CAAC;QACrF,MAAM,CAAC,MAAM,CAAC,uBAAuB,EAAE,OAAO,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QACvE,cAAc,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC;YACzC,MAAM,YAAY,CAAC,8DAA8D,CAAC,CAAC;QACrF,MAAM,CAAC,MAAM,CAAC,uBAAuB,EAAE,OAAO,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QACvE,cAAc,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IAC1C,CAAC;IACD,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAErC,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAClD,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAA4B,CAAC,CAC/C,CAAC;IACF,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC;IAC7B,MAAM,cAAc,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,gBAAgB;IACjE,MAAM,KAAK,GAAG,cAAc,KAAK,IAAI,CAAC;IACtC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,GAAG,cAAc,CAAC,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC;IAC/E,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAEtD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,WAAW,CAAC,KAAK,CAAC,CAAC;IACnB,IAAI,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAEvC,OAAO,QAAQ,CACb,EAAE,MAAM,EAAE,IAAI,EAAE,EAChB;QACE,MAAM,EAAE,SAAS,EAAE;QACnB,WAAW,EAAE,KAAK;QAClB,QAAQ;QACR,cAAc;QACd,cAAc;QACd,cAAc,EAAE,EAAE;QAClB,iBAAiB,EAAE,EAAE;QACrB,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE;QAClD,KAAK;KAC0B,CAClC,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAMjC;IACC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,GAAG;QACtD,MAAM,YAAY,CAAC,uDAAuD,CAAC,CAAC;IAC9E,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC;QACzC,MAAM,YAAY,CAAC,kDAAkD,CAAC,CAAC;IACzE,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;QAC9D,MAAM,YAAY,CAChB,+IAA+I,CAChJ,CAAC;IAEJ,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,+CAA+C;IACtF,MAAM,cAAc,GAAa,EAAE,CAAC;IAEpC,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC;YAC/B,MAAM,YAAY,CAAC,uEAAuE,CAAC,CAAC;QAC9F,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACtD,cAAc,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,aAAa;YAC3E,MAAM,YAAY,CAChB,4DAA4D,aAAa,UAAU,CACpF,CAAC;QACJ,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAClD,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC;YACnC,MAAM,YAAY,CAAC,iDAAiD,CAAC,CAAC;QACxE,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QACpD,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACnC,CAAC;IACD,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IACpC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAErC,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACnD,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,CAA4B,CAAC,CACjD,CAAC;IACF,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC;IAC7B,MAAM,cAAc,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,cAAc,KAAK,IAAI,CAAC;IACtC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,GAAG,cAAc,CAAC,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC;IAC/E,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAEtD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,WAAW,CAAC,KAAK,CAAC,CAAC;IACnB,IAAI,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAC7C,6EAA6E;IAC7E,oEAAoE;IACpE,IAAI,QAAQ,KAAK,CAAC,IAAI,cAAc,KAAK,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IAChF,KAAK,CAAC,IAAI,CAAC,qBAAqB,EAAE,0BAA0B,CAAC,CAAC;IAE9D,OAAO,QAAQ,CACb,EAAE,QAAQ,EAAE,IAAI,EAAE,EAClB;QACE,MAAM,EAAE,SAAS,EAAE;QACnB,WAAW,EAAE,KAAK;QAClB,QAAQ;QACR,cAAc;QACd,cAAc;QACd,cAAc,EAAE,EAAE;QAClB,iBAAiB,EAAE,EAAE;QACrB,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE;QAClD,KAAK;KAC0B,CAClC,CAAC;AACJ,CAAC"}

package/dist/far.d.ts

@@ -0,0 +1,170 @@
+/**
+ * FAR / DFARS clause lookup (keyless) — the authoritative clause text + its
+ * prescription, from the eCFR **versioner full** endpoint.
+ *
+ * Why this exists (and why NOT `ecfr_search`)
+ * -------------------------------------------
+ * The shipped full-text `ecfr_search` mis-ranks EXACT clause numbers: a bare
+ * `52.212-4` query returns GSAM **552**.212-4 above the real FAR 52.212-4
+ * (doc-09 §1.2). A proposal writer needs the AUTHORITATIVE clause text AND the
+ * rule that says WHEN it applies ("As prescribed in …") — the exact pair. The
+ * clean path is the versioner full endpoint, which `src/ecfr.ts` does not call:
+ *
+ *   GET /api/versioner/v1/full/{date}/title-48.xml?section={clause}
+ *
+ * keyless, HTTP 200 (~40 KB XML) for a real clause, clean HTTP 404
+ * `{"error":"No matching content found."}` for an absent one. Title 48 = FAR.
+ * `{date}` defaults to Title 48 `up_to_date_as_of` (from listTitles, cached).
+ *
+ * TRUTHFULNESS invariants (a reviewer WILL try to break these):
+ *   - A DOWN/failing eCFR service must NEVER read as "clause not found": only a
+ *     genuine HTTP 404 maps to `not_found`; any other fetch error propagates
+ *     with fetchWithRetry's classification (retryable 5xx/network/etc.).
+ *   - A genuinely-absent clause is `not_found` (retryable:false), NEVER a fake
+ *     empty clause. Clause text is never silently dropped or fabricated.
+ *   - A prescription-section fetch failure is NON-FATAL: `prescription:null` +
+ *     disclosed in `_meta.notes`; it never crashes the clause result.
+ *   - `farOverhaulRisk` carries NO fabricated FAR-case numbers/dates — only the
+ *     fixed structural caveat + the real authoritative-list / deviation URLs.
+ *
+ * Self-contained: imports `getText` from ./datasource.js (the shared XML/text
+ * fetch port, ADR-0013) + ToolErrorCarrier from ./errors.js, memoize from
+ * ./cache.js, listTitles from ./ecfr.js, and withMeta from ./meta.js — the
+ * versioner XML parse lives here (ecfr.ts's stripHtml is private and stays
+ * private).
+ */
+/** The regulation family a clause number belongs to (from its prefix). */
+type Regulation = "FAR" | "DFARS" | "GSAM" | "other";
+/**
+ * The RFO (Revolutionary FAR Overhaul) currency caveat — an ALWAYS-PRESENT
+ * structural flag, NOT a per-clause claim. eCFR reflects the CODIFIED FAR only;
+ * the RFO is replacing FAR parts via agency class deviations that may not appear
+ * in eCFR, so a clause can be current in the CFR yet operationally superseded.
+ *
+ * This is the HONEST design (doc-09 §3 baked unverified FAR-case numbers/dates
+ * as [가설] — those go stale/wrong). We ship the never-stale-wrong version: no
+ * fabricated specifics, only the fixed caveat + the real authoritative-list and
+ * deviation URLs (all VERIFIED HTTP 200, 2026-07-04). `appliesTo` scopes the
+ * caveat to the clause's own regulation family.
+ */
+declare function buildFarOverhaulRisk(regulation: Regulation): {
+    note: string;
+    authoritativeList: string;
+    deviationSources: string[];
+    appliesTo: Regulation;
+};
+export declare function farClauseLookup(args: {
+    clauseNumber: string;
+    includePrescription?: boolean;
+    asOfDate?: string;
+}): Promise<import("./meta.js").MetaBundle<{
+    clauseNumber: string;
+    kind: "clause" | "provision";
+    regulation: Regulation;
+    heading: string | null;
+    revision: string | null;
+    text: string;
+    prescribedIn: string | null;
+    prescription: {
+        section: string;
+        heading: string | null;
+        text: string;
+    } | null;
+    ecfrUrl: string;
+    asOfDate: string;
+    titleUpToDateAsOf: string | null;
+    titleLatestAmendedOn: string | null;
+    isCurrent: boolean;
+    farOverhaulRisk: {
+        note: string;
+        authoritativeList: string;
+        deviationSources: string[];
+        appliesTo: Regulation;
+    };
+}>>;
+/** One resolved matrix row: farClauseLookup's honest fields + a gate flag. */
+type MatrixRow = {
+    clauseNumber: string;
+    kind: "clause" | "provision";
+    regulation: Regulation;
+    heading: string | null;
+    revision: string | null;
+    prescribedIn: string | null;
+    prescription: {
+        section: string;
+        heading: string | null;
+        text: string;
+    } | null;
+    text: string;
+    ecfrUrl: string;
+    farOverhaulRisk: ReturnType<typeof buildFarOverhaulRisk>;
+    /** The eligibility-gate label (from GATE_MAP), or null when not a mapped gate. */
+    gate: string | null;
+};
+/** A clause that did not resolve, with a disclosed reason. */
+type UnresolvedClause = {
+    clauseNumber: string;
+    reason: string;
+};
+export declare function farComplianceMatrix(args: {
+    clauses: string[];
+    asOfDate?: string;
+    includePrescription?: boolean;
+    flagGates?: boolean;
+}): Promise<import("./meta.js").MetaBundle<{
+    asOfDate: string;
+    rows: MatrixRow[];
+    unresolved: UnresolvedClause[];
+    errored: UnresolvedClause[];
+    summary: {
+        total: number;
+        resolved: number;
+        unresolved: number;
+        errored: number;
+        far: number;
+        dfars: number;
+        gsam: number;
+        other: number;
+        gates: number;
+    };
+}>>;
+/** Which regulation family a far_search scope targets. */
+type FarSearchScope = "far" | "dfars" | "both";
+/** One far_search result row. */
+type FarSearchRow = {
+    regulation: Regulation;
+    type: string;
+    /** The FAR/DFARS part as a number (null if unparseable), for partsOnly. */
+    part: number | null;
+    section: string;
+    headingPath: string;
+    excerpt: string;
+    score: number;
+    ecfrUrl: string;
+    effectiveOn: string;
+    endsOn: string | null;
+    /** endsOn==null ⇒ the CURRENT (in-force) version; false ⇒ a kept historical. */
+    isCurrent: boolean;
+};
+export declare function farSearch(args: {
+    query: string;
+    scope?: FarSearchScope;
+    dedupeVersions?: boolean;
+    partsOnly?: number[];
+    perPage?: number;
+}): Promise<import("./meta.js").MetaBundle<{
+    query: string;
+    scope: FarSearchScope;
+    rows: FarSearchRow[];
+    returned: number;
+    distinctSections: number;
+    titleUpToDateAsOf: string | null;
+    farOverhaulRisk: {
+        note: string;
+        authoritativeList: string;
+        deviationSources: string[];
+        appliesTo: Regulation;
+    };
+}>>;
+export {};
+//# sourceMappingURL=far.d.ts.map

package/dist/far.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"far.d.ts","sourceRoot":"","sources":["../src/far.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAUH,0EAA0E;AAC1E,KAAK,UAAU,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAiFrD;;;;;;;;;;;GAWG;AACH,iBAAS,oBAAoB,CAAC,UAAU,EAAE,UAAU;;;;;EAYnD;AAkED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;;;;;;;;;iBAmIgB,MAAM;iBAAW,MAAM,GAAG,IAAI;cAAQ,MAAM;;;;;;;;;;;;;IAsF5D;AA8CD,8EAA8E;AAC9E,KAAK,SAAS,GAAG;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC7B,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EACR;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GACzD,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC;IACzD,kFAAkF;IAClF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB,CAAC;AAEF,8DAA8D;AAC9D,KAAK,gBAAgB,GAAG;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA6BjE,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;;;;;;;;;;;;;;;;IAmLA;AA4BD,0DAA0D;AAC1D,KAAK,cAAc,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;AAQ/C,iCAAiC;AACjC,KAAK,YAAY,GAAG;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gFAAgF;IAChF,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAmFF,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;;;;;;;;;;;;;IAsJA"}