feat(instrument): reconcile bounded family-scoped catalog

[seonghobae]

Why

Historical Draft #304 contains the unique family-scoped durable catalog query, but its parent branch belonged to now-closed predecessor #303. That leaves #304 with stale ancestry and a misleadingly huge stacked diff. Current-main replacement #422 is the active parent for the bounded startable-instrument catalog, so this PR carries only the family-scoped delta on top of unchanged exact #422 head 98a575f2422c2eb0edba7d2fadc783158acf9ef5.

TDD / reconciliation

• Historical source lineage: feat(instrument): scope durable catalog by family #304 RED b75c844ccc5baab4ceb73e68e4e589bb92dfb617 and GREEN ab2f73dbf054dcb5e7189d7a9533a6ac380dcd77.
• Current-parent RED 44925fa41e9377f0d9a4c0073b29c727d397df53 adds the family-scoped real-PostgreSQL contract before the API exists on feat(instrument): reconcile durable startable catalog onto current main #422.
• Current-parent GREEN 0813db3cf136aa16f8b2b58a3b81a6a4dbac2015 adds the narrow database-side family query without changing the parent catalog's global paging contract.
• Exact compare against feat(instrument): reconcile durable startable catalog onto current main #422 is 2 commits ahead / 0 behind and changes only src/postgres_instrument_catalog.rs plus tests/postgres_instrument_family_catalog.rs.

Product contract

• Validate the caller's family as one exact opaque instrument_ref, including fail-closed rejection of trim aliases, numeric-like references, controls, and Unicode default-ignorable aliases.
• Apply the exact family filter inside PostgreSQL instead of loading every published family into transport code.
• Return only currently published persisted releases, ordered deterministically by (locale, release_ref).
• Reconstruct every selected row through the same immutable published-release validation boundary as the parent catalog.
• Keep discovery non-locking and advisory; session start remains responsible for reloading/locking the exact release before minting a session.
• Preserve the parent's bounded query posture: one family compatibility call returns at most 100 releases and fails closed with PageRequired rather than truncating or running unbounded when the family exceeds one page.
• Add no locale fallback, HTTP transport, authorization expansion, session creation, scoring arithmetic, or cross-service database access.

Stack / supersession

This is a Draft child of #422. #422 must integrate first and this branch must then be reconciled to the integrated protected head before this PR can become merge-ready. It supersedes stale Draft #304 as the family-scoped landing vehicle; historical #304 checks/reviews do not transfer.

Acceptance

Do not merge until the unchanged exact final head is on the correct integrated parent, passes Runtime CI including the real PostgreSQL contract and exact owned statement/branch coverage, rustfmt/Clippy/rustdoc, Security/SAST, SPDX SBOM, supply-chain provenance, every live organization-required workflow, has zero valid unresolved findings, and satisfies qualifying independent non-author approval under the live ruleset. Pending, queued, skipped, cancelled, absent, stale, predecessor, synthetic, or model-only evidence is not passing. Never use administrator bypass or self-approval.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}