feat(sdk): Zod-first param schemas that validate, type, and document request params from one source

[mikec-ai]

What

Closes #1.

Makes a Zod schema the single source of truth for every object-param endpoint's request contract. Each schema simultaneously validates inputs in the SDK client method (a one-line, path-qualified ValidationError is thrown before the HTTP call), defines the TS types (z.infer, replacing the hand-written interfaces; same exported names, no call-shape changes), and renders the agent-facing params contract now returned by describe_schema and search_api and indexed by BM25. This closes the discoverability gap described in #1 (agents reverse-engineering conditions shapes by trial-and-error) and turns the significant: true silent-wrong-count footgun into an instant, explanatory local error.

Measured on the built artifact (Claude Opus agents, 3 tasks, pre/post, 3 reps each, live APIs): mean execute calls down 56%, failed calls down 100%, discoverability 2.67 to 5.0 out of 5, 18/18 correct vs gold. Consistent with the original injected-docs A/B in #1 (58% / 80% / 2.6 to 5.0).

How

Notes for a reviewer, in reading order:

• src/sdk/validate.ts: the one seam every client method uses. Formats ZodError into a single line (up to 3 issues) here, because the sandbox RPC boundary (dispatch in src/sdk/runtime.ts) copies only {name, message, status}; an unformatted ZodError.message is a JSON dump.
• src/sdk/fr-client.ts / ecfr-client.ts: interfaces become Zod schemas. Non-obvious decisions:
  • .strict() everywhere, calibrated against the live APIs. Both FR and eCFR return HTTP 400 on unknown keys (verified live), so strictness converts a guaranteed remote 400 into a local error; it relaxes nothing. The allow-lists were swept against the APIs' full documented param sets, which added honored keys the old interfaces omitted: sections, regulation_id_number, agency_ids, correction, near. Never default (strip) mode: stripping silently drops typo'd keys and runs the query unfiltered, the same silent-wrong-answer class as the footgun.
  • significant / correction: 0 | 1 with a custom error map rejecting booleans (live-verified: 551/6 correct vs 2393/12 silently wrong).
  • type is union([array(enum), enum]) with no .transform(): both forms are accepted by the API as-is, and skipping normalization keeps z.infer honest (input type = output type).
  • All eCFR search sub-endpoints share EcfrSearchParamsSchema: results, counts, and suggestions accept the same param vocabulary (live-verified; a narrower pick rejected honored date / last_modified_* filters).
  • ancestry / full stay open (z.record): genuinely free-form node selectors.
  • facets now validates the bucket enum and encodes it into the path (it was interpolated raw before).
• src/sdk/renderParams.ts: Zod to readable contract text. Unwraps Optional/Default/Effects while keeping the nearest .describe() (a .describe().optional() description must survive), parenthesizes array-of-union, and renders unknown node types as a loud unsupported<T> token that a coverage test asserts never ships.
• src/sdk/paramSchemas.ts: the endpoint-id to schema registry; getCorpus() renders each registered schema into the entry's params at load time. No committed generated artifact, no build step, nothing to drift.
• schema/field-dictionary.json: the ecfr.versions example moves from the pre-flattened 'issue_date[gte]' form to the nested form the typed SDK signature always specified; two missing corrections entries added; quoting-semantics note on eCFR search.
• Tests (62 total): calibration tests assert every live-verified accepted form parses and the footgun rejects; wire-level tests assert the parse-then-flatten integration produces the exact bracketed query strings; a drift guard asserts every object-param endpoint has a registered schema, renders a non-empty contract, and mechanically parses its own dictionary example (acorn-extracted, so examples can't silently diverge from schemas).

Test plan

• pnpm typecheck
• pnpm lint
• pnpm test
• pnpm build
• If HTTP-visible: added a case in test/http-integration.spec.ts asserting the params contract on describe_schema and search_api results survives the streamable-HTTP transport
• If sandbox-visible: validation errors cross dispatch as structured {name: 'ValidationError', message} (covered in test/sdk.spec.ts; the sandbox surface itself is unchanged)
• If new SDK method: no new methods; two missing dictionary entries added (ecfr.admin.corrections, ecfr.admin.corrections_for_title)

Risk

• Back-compat (the real one): call shapes are unchanged, but the stable fr.* / ecfr.* globals get stricter at runtime: significant: true, misspelled or unknown keys, and the pre-flattened versions key form now throw locally instead of reaching the API. In practice those inputs were already broken (silent wrong data or an upstream 400), with one exception: the old documented example for ecfr.versions used the flattened form, which worked by accident. CHANGELOG documents all of it with migration guidance.
• Over-strict rejection of honored params: the named risk of .strict(). Mitigated by calibrating the allow-lists against the APIs' full documented param sets (not the old TS interfaces) and encoding every verified form in calibration tests. If an honored key was still missed, the failure is loud (a clear local error naming the key), not silent.
• Security: none; validation is host-side and the sandbox boundary is untouched. facets path interpolation is now enum-validated and encoded (slight hardening).
• Perf: per-call .parse() is microseconds against a network round-trip it can prevent; corpus rendering happens once at load.