Contracts: add sub-vendor / subcontractor fields for M/WBE subcontracting analysis

[noneck]

Gap

The MCP's Contracts default column set requests no sub-vendor / subcontractor fields, and search_contracts exposes no contract_includes_sub_vendors filter — even though the CheckbookNYC Contracts API documents a full sub-vendor column set. This blocks M/WBE subcontracting analysis, a common BetaNYC and press use case.

Documented API field(s)

Columns we omit (all documented on the Contracts API page):
sub_vendor, sub_vendor_mwbe_category, sub_contract_purpose, sub_contract_status, sub_contract_current_amount, sub_contract_original_amount, sub_vendor_paid_to_date, sub_contract_registration_date, sub_contract_industry, sub_woman_owned_business, sub_emerging_business.

Filter we omit: contract_includes_sub_vendors.

Source: Contracts API — CheckbookNYC

Value

Enables analysis of subcontracting relationships and M/WBE participation at the sub-vendor level — who is actually doing the work under a prime contract, and how much M/WBE subcontracting a prime reports.

Notes

Mostly additive: sub_* columns are pure column-list additions to the Contracts request, plus one new documented filter. Audit suggests folding this into the scoped v1.2.0 Contracts enrichment alongside G1 and G4.

Reference

See the API audit: team/engineering/2026-07-09-checkbook-2.0-api-audit.md (gap G3, MEDIUM).

[noneck]

Addressed in #3 (v1.2.0). search_contracts gains an opt-in include_sub_vendors boolean; when set on a registered-contracts search, the response is enriched with the 11 documented sub-vendor columns (sub_vendor, sub_vendor_mwbe_category, sub_contract_purpose, sub_contract_status, sub_contract_current_amount, sub_contract_original_amount, sub_vendor_paid_to_date, sub_contract_registration_date, sub_contract_industry, sub_woman_owned_business, sub_emerging_business). All tokens confirmed against the Contracts API table (2026-07-09). Fixture tests cover the column selection and XML emission. No live API calls.

One piece deferred, not guessed: the contract_includes_sub_vendors filter. The docs document its name but describe its accepted value as a 2-character status code (String, ≤2 chars — not a simple boolean), and the code enumeration isn't reliably confirmable from the docs. Per the build-against-docs rule I did not hardcode a value mapping for it. The sub-vendor columns (the core of this issue — who is doing the work under a prime) are fully delivered. Can wire the filter once the status-code enumeration is confirmed (docs table or an authorized error-1101 probe).

[noneck]

Filter remainder addressed in #14 (open for review).

Confirmed against the CheckbookNYC open-source API config (NYCComptroller/Checkbook → checkbook_api/src/config/contracts.json):

• Criterion confirmed: contracts_active_expense.requestParameters.contract_includes_sub_vendors = {"valueType":"value","dataType":"text","maxLength":"2"} (searchCriteriaMap contract_includes_sub_vendors → scntrc_status). Registered configs only.
• Enumeration still deferred: the config declares it as text/max-2 with no allowedValues (contrast category, which lists them). The accepted 2-char status codes are genuinely not published in the config, so per the build-against-docs rule they are not guessed.

Implemented: an optional contract_includes_sub_vendors value filter (gated to status=registered) that passes the caller-supplied code through verbatim, with the parameter description stating the codes are not enumerated in the published config. Fixture test added. Partially resolved (criterion wired; value enumeration remains unconfirmed). The sub-vendor response columns already shipped in #3/v1.2.0.