Absorb search filter params + metadata fields (BC3 #12361 merged — gap doc trigger fired)

[jeremy]

Summary

The absorption precondition recorded in spec/api-gaps/search-filter-additions.md has been met: BC3 #12361 ("Search API: query-faithful params and root cache") is merged (f0d9387a58, 2026-07-22 09:58 −0700). The gap doc's stated trigger — "Wait for BC3 #12361 to merge, then re-derive the param list from the merged doc/api/sections/search.md and flip this entry to addressed-in-bc3-pr-12361" — is now satisfied, but the entry still reads partial-coverage and describes #12361 as open.

Filing this as a hand-off so an SDK-side session can pick up the absorption. This issue is coordination only — no SDK code was touched from the CLI session that surfaced it.

Context

The pinned SDK (v0.8.0) exposes only Q/Sort on SearchParams, so the CLI cannot offer project-scoped or typed search yet. CLI PR basecamp/basecamp-cli#557 (Fixes #470, Refs #546) ships the CLI-only surface: bounded default result cap, relevance/recency sort vocabulary, an honest interim rejection of --project/--in, and graceful handling of the drifted /searches/metadata.json response. It explicitly defers the project/type/since filters and real metadata fields to whatever SDK release absorbs this contract.

Missing SDK contract

Request params on the existing SearchInput (all additive @httpQuery, response shape unchanged), per the merged doc/api/sections/search.md:

• bucket_ids[] — project IDs (deprecated singular bucket_id retained)
• type_names[] — recording types (key values from metadata recording_search_types; deprecated singular type)
• creator_ids[] — creator person IDs (deprecated singular creator_id)
• file_type
• exclude_chat
• since — last_7_days | last_30_days | last_90_days | last_12_months | forever (default; unrecognized → forever)
• sort — best_match (default) | recency (unrecognized → recency ordering)

Metadata endpoint (GET /:account_id/searches/metadata.json) — model the current fields the SDK's SearchMetadata does not surface (verified against bc3 app/views/api/searches/metadata/index.json.jbuilder):

• recording_search_types — array of { key, value } (key = class string or null, value = human label)
• file_search_types — array of { key, value }
• default_creator_label, default_bucket_label, default_circle_label, default_file_type_label, default_type_label

Also apply the same input shape to the timelines/searches counterpart (GET /:account_id/timelines/searches.json), per the gap doc.

Absorption checklist (from the gap doc)

• Re-derive the final param list from merged doc/api/sections/search.md
• Extend Smithy SearchInput with the optional fields; same for the timeline-search input if separate
• Model the metadata response fields on SearchMetadata
• Regenerate + wrapper updates
• Canary: add a search call with ≥1 new filter param to live-my-surface.json
• Flip spec/api-gaps/search-filter-additions.md to addressed-in-bc3-pr-12361

Downstream CLI follow-up (after this lands)

make bump-sdk, then complete basecamp-cli#546: resolve --project via app.Names.ResolveProject into the new bucket-ID type, add --type/--since, expose real metadata fields, drop the interim --project rejection.

References

• BC3 #12361 (merged): f0d9387a58
• Closed SDK Search doesn't filter the results #324 (root cause of the "identical unrelated results" symptom)
• spec/api-gaps/search-filter-additions.md
• CLI PR Fix search timeout, sort vocabulary, and metadata handling basecamp-cli#557