feat(services): adopt the filter contract with real facets (PR C)

[BigSimmo]

Summary

• Services gains its first real filtering, replacing six query-replacing "quick filters" (a navigate-kind defect docs/filter-contract.md exists to remove — each called router.push and discarded the search with no warning).
• Five typed CatalogServiceTags dimensions (catchments, age_groups, setting_flags, acuity_flags, housing_flags) become facets with union counts (OR within group, AND across groups); substance_flags ships as a lens — it's an exact partition (every one of the 219 catalogue services carries exactly one of general/aod), so a facet would falsely claim a service could be both.
• A typed facet carrier (ServiceRecord.facets) is populated at both entry points into ServiceRecord (the static/demo mapper and the live registry row mapper), derived from catalog_payload.tags/CatalogService.tags rather than the flattened ServiceRecord.tags array — flattenTags merges five dimensions plus sections/aliases/id into one deduped array, so a token like "general" (which means three different things across setting_flags/substance_flags/housing_flags) collapses to one indistinguishable entry there. A facet filter built on the flattened array would be wrong by construction.
• A scope segment (These results N | All items N) escapes a filtered-to-zero state without discarding the query, per docs/filter-contract.md §4.
• The shared filter renderer (ResultFilterSheet/ResultFilterFacetChips) grows a dense tier — find-a-filter plus collapse-by-default — for services' 5 groups / 24 options, resolving /issues #309 (now closed). Below the density threshold nothing changes (formulation's existing 9-option group still renders as a plain chip row).
• The OR-within-group/AND-across-group selection algorithm is extracted from document-tags.ts into a new src/lib/facet-selection.ts so services and documents share one counting rule rather than each inventing their own — document-tags.ts now imports it back with no behavioral change (its own 23-test suite still passes unchanged).
• docs/filter-contract.md §5 updated to describe the two states actually implemented (documents' own dense boolean never shipped a distinct three-tier scheme either).

Verification

• npm run verify:pr-local — full run, all steps green: check:runtime, check:installed-lock-parity, format:changed, sitemap:check, docs:check-index, docs:check-inventory, docs:check-scripts, docs:check-links, check:branch-review-ledger, check:outstanding-issues, lint, typecheck, test, build, check:rag:fixtures. test reported Test Files 565 passed (565) / Tests 6165 passed | 4 skipped (6169), and the full suite was re-run after merging origin/main in: Test Files 566 passed (566) / Tests 6172 passed | 4 skipped (6176).
• npm run check:bundle-budget after a clean rm -rf .next && npm run build — production 1307.9 KiB gzip (baseline 1279.1 KiB, within the 10% tolerance), mockups 294.5 KiB gzip (baseline 267.5 KiB, within the 25% tolerance).
• npm run verify:ui cannot run in this environment (/issues #255 — Playwright wants chromium-1234, only chromium-1194 installed). Proved UI directly: a Playwright script from the repo root with executablePath: "/opt/pw-browsers/chromium-1194/chrome-linux/chrome" against a real dev server — facet sheet opens, a facet toggle narrows results while leaving q untouched, Clear filters removes facets/substance without touching q, the scope segment renders when catalogue (219) > results and "All items" clears back to the full catalogue, the search-shortcut chips still run a query-replacing search, 0px horizontal overflow at 1440/800/390/320. 8/8 checks passed.
• The two Playwright specs in tests/ui-tools.spec.ts that exercised the old query-replacing "Quick filters" radio were rewritten for the new facet/chip behavior and run against a real production build via node scripts/run-playwright.mjs with the same executable override — both pass.
• New unit tests: tests/service-facets.test.ts (facet index derivation, OR/AND selection, projected-count semantics, a live guard that substance_flags is still an exact partition across the real 219-service catalogue), plus extended coverage in tests/services-catalog.test.ts and a new tests/registry-records.test.ts for the facets derivation at both ServiceRecord entry points (including conservative degrade to all-empty dimensions on missing/malformed catalog_payload).

Risk and rollout

• Risk: Low-to-moderate. No Supabase schema/migration change and no new write path — this reads an existing JSONB column. classifyPullRequestFiles returns clinicalRisk: true for this diff, but by inspection that's driven by src/lib/service-ranker.ts's filename containing "rank" (the pattern matches on path, not content) — the actual change there is additive-only (a new optional facets field on ServiceRecord), not a change to ranking/scoring logic.
• Rollback: Revert the single squash commit; no data migration to unwind.
• Provider or production effects: None. No Supabase/OpenAI/GitHub calls were made or modified.
• Outstanding, flagged explicitly for review: this PR was built and verified entirely offline/demo-mode (no live Supabase credentials in this session). registry-seed.ts/registry-fixtures.ts confirm the fixture/demo seeding path populates catalog_payload with the full typed tags, but live verification that the production registry's service rows actually carry catalog_payload.tags with all six dimensions populated has not been done.rowToServiceRecord degrades conservatively (all-empty facet dimensions, never a throw) if it isn't — so the worst case in production is an empty filter sheet, not a crash — but this should be confirmed against the live Clinical KB Database project before or shortly after merge.

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use — unaffected, no citation/source-rendering logic touched.
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval — this PR touches service-catalogue filtering only, no document/patient workflow.
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy) — no Supabase config changed.
• Service-role keys and private document access remain server-only — unaffected; this reads registry rows through the existing authorized client path only.
• Demo/synthetic content remains clearly separated from real clinical sources — unaffected.
• Source metadata, review status, and outdated/unknown-source behavior remain conservative — unaffected; the new facet-degrade path is itself conservative (empty, not fabricated).
• Deployment classification/TGA SaMD impact was checked when clinical decision-support behavior changed — not applicable; this is catalogue/filter UI, not decision-support output.

Notes

• Two decisions made without live user confirmation, flagged for review at merge time:
  1. Density-mode approach: grew the shared renderer's dense tier now (matching services before documents, per the rollout's own stated order) rather than doing PR F's documents port first. /issues #309 records the reasoning.
  2. Live-Supabase verification: proceeded on the fixture-verified assumption per the Risk section above; genuinely unverified against the production project in this session.
• docs/outstanding-issues.md conflicted with origin/main during a routine merge (two new rows, #310/#311, landed on main while this branch's #309 closure was in flight) — resolved by hand per AGENTS.md's no-merge-driver rule for that file: kept both sides' content (my #309 archival, plus #310/#311 from main), verified with npm run check:outstanding-issues.

---

Generated by Claude Code

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in:57 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 89d38c76-61ea-4203-91aa-ab64cb1e36b6

📥 Commits

Reviewing files that changed from the base of the PR and between d30a9de and feef719.

📒 Files selected for processing (17)

• docs/design-system/COMPONENTS.md
• docs/design-system/adoption-manifest.json
• docs/filter-contract.md
• docs/outstanding-issues.md
• src/components/clinical-dashboard/result-filter-control.tsx
• src/components/services/services-navigator-page.tsx
• src/lib/document-tags.ts
• src/lib/facet-selection.ts
• src/lib/registry-records.ts
• src/lib/service-catalog-mapper.ts
• src/lib/service-catalog.ts
• src/lib/service-facets.ts
• src/lib/service-ranker.ts
• tests/registry-records.test.ts
• tests/service-facets.test.ts
• tests/services-catalog.test.ts
• tests/ui-tools.spec.ts

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:f93c2639e3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[BigSimmo]

@codex resolve actionable Codex review findings for this pull request and current head using the repository instructions. This is the pull request's single automatic repair pass: do not perform a fresh review, create new standalone findings, or request another review. Work only the existing unresolved Codex threads on the current head. The only repository destination is BigSimmo/Database, and the only branch destination is the pull request head branch claude/artifact-build-ygfit8 at starting commit 6098a53; never publish fixes to a detached or synthetic work branch and never create a stacked pull request. Use the authenticated GitHub connector to commit each approved fix to BigSimmo/Database:claude/artifact-build-ygfit8, then verify that the pull request head contains the published commit before reporting success. Always fix P0 and P1 findings. For P2 and lower findings, fix only clear, scoped, low-risk issues; otherwise disposition them with a concise reason. For a fixed thread, reply with as the first line and as the second line. For a no-code disposition, use followed by . These result markers authorize the workflow to close that exact thread only after it verifies a fixed commit is the pull request head; a local-only commit is not a fix. If publication or verification fails, do not use either result marker, do not claim success, and leave the thread open with the blocker. If human input or new authorization is required, do the same. Finish only after every actionable thread is fixed or dispositioned and closed, or explicitly left open for a human decision. Do not update the branch from main, address unrelated reviews, broaden scope, or create more than one scoped fix commit. Do not use external APIs, paid services, credentials, dependency changes, or broad refactors unless explicitly authorized. Add targeted tests where behavior changes and run the narrowest relevant validation.

[BigSimmo]

Fixed the current services findings on the exact head: widening to All items now preserves q/query while clearing only narrowing scope, facet projections are computed from the active substance lens population, and the focused UI journey verifies scope widening, query preservation, facet reapplication, and independent clearing. The actionable threads are resolved. The failed Secret Scan was an Install Gitleaks infrastructure failure, so its failed job was rerun; CI remains in progress on the new head.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit:6098a53be4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

CI triage

CI failed on this PR. Automated classification of the 2 failed job(s):

• Static PR checks — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.
• PR required — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.

Compared with main CI run #10259 (success).

Classification is evidence routing, not permission to ignore a failure. Exact quarantined Playwright identities remain governed by the flake ledger.

[BigSimmo]

@claude Repair only the exact-head CI regressions currently proven on PR #1882 head ad8d5a375a99457324c8bad7141632744d0d5aad. Hosted CI shows (1) changed-file formatting failure in tests/ui-tools.spec.ts, and (2) build/typecheck errors in src/components/services/services-navigator-page.tsx where facetFilteredMatches is referenced but not defined at the current lines ~645/650/658, with resulting implicit-any callback parameters. Verify against current head, make the smallest correct services-filter fix, format the changed test, run format/typecheck plus focused services tests/browser journey as proportionate, and inspect the exact previously failing UI jobs only for PR-introduced fallout. Push fixes to this PR branch and report the pushed SHA and verification. Do not merge, close, rebase, force-push, deploy, alter auto-merge, or broaden scope.

[claude]

Claude encountered an error after 2s —— View job

---

I'll analyze this and get back to you.

[github-actions]

Hi @BigSimmo — thanks for the @claude mention.

Open this in Claude Code on the web to continue here: https://claude.ai/code

Context: BigSimmo/Database · #1882

_{Automated backlink from the Claude backlink workflow. Claude Code can pick up the mention and push a scoped fix to the branch.}

[BigSimmo]

@claude The exact-head CI repair is already on head 1fec577fa29bb04155127481331416dd1fbc4886 with the review threads resolved, but the PR is now mergeable_state: dirty against current main. Fetch current main and merge it into this PR branch without rebasing or force-pushing. Resolve only merge conflicts, preserving the facetFilteredMatches/format fixes and all newer main changes. Run conflict-adjacent format/typecheck plus focused service-facet tests and the services UI journey as proportionate, push the merge-resolution commit, and report the pushed SHA and verification. Do not merge or close the PR, deploy, alter auto-merge, or broaden scope.

[github-actions]

Hi @BigSimmo — thanks for the @claude mention.

Open this in Claude Code on the web to continue here: https://claude.ai/code

Context: BigSimmo/Database · #1882

_{Automated backlink from the Claude backlink workflow. Claude Code can pick up the mention and push a scoped fix to the branch.}

[claude]

Claude encountered an error after 2s —— View job

---

I'll analyze this and get back to you.

[BigSimmo]

Formatted the two files reported by the exact-head static check (src/components/services/services-navigator-page.tsx and tests/ui-tools.spec.ts) with the repository Prettier configuration. The PR remains blocked by GitHub's reported merge conflict; no rebase or force-push was performed.

[BigSimmo]

@claude Please main-sync this PR from exact head feef71954e2ce4da48a24c8939651202fe7670c7: merge the latest main once (never rebase), resolve all conflicts minimally, commit and push. Do not merge/close the PR, force-push, alter auto-merge, or touch unrelated files.

This is an older competing Services filter-contract implementation; preserve its current tested behavior and all already-fixed review findings (query preservation, active care-lens projections), while retaining every newer main shared-filter, registry, service mapper/ranker, navigation, accessibility, performance and payload-safety change. For docs/filter-contract.md, design-system docs/manifest and docs/outstanding-issues.md, take current main as authoritative and reapply only still-current PR-specific rollout/adoption status through proper tooling; do not overwrite #1878 or newer rollout state.

Run the focused service facets/catalog/registry tests, search-results DOM tests, the relevant Services UI selector, design-system/adoption checks if applicable, typecheck and format. Report the new head and exact outcomes.

[github-actions]

Hi @BigSimmo — thanks for the @claude mention.

Open this in Claude Code on the web to continue here: https://claude.ai/code

Context: BigSimmo/Database · #1882

_{Automated backlink from the Claude backlink workflow. Claude Code can pick up the mention and push a scoped fix to the branch.}

[claude]

Claude encountered an error after 2s —— View job

---

I'll analyze this and get back to you.

[BigSimmo]

@copilot Merge main at 0709965e66e04173ec0b0de1d121e85ac1ff7e04 into current head feef71954e2ce4da48a24c8939651202fe7670c7, resolve conflicts minimally, and push the merge commit to claude/artifact-build-ygfit8. Never rebase or force-push. Do not merge/close the PR, deploy, alter auto-merge, or touch unrelated files.

This is an older competing Services filter implementation. Preserve its already-fixed query-preservation and active care-lens count projections, but retain every newer current-main shared filter, registry, mapper/ranker, navigation, accessibility, performance and payload-safety change. For docs/filter-contract.md, design-system docs/manifest and docs/outstanding-issues.md, current main is authoritative; do not overwrite #1878 or newer rollout status. Keep immutable records/history and reapply only still-current PR status using repository tooling.

Run focused service facets/catalog/registry tests, search-results DOM tests, relevant Services UI selector, design-system/adoption and ledger/issues integrity/write-discipline checks, typecheck and format. Report the pushed 40-character SHA and exact outcomes.

[BigSimmo]

Final review status

• State change: PR feat(services): adopt the filter contract with real facets (PR C) #1882 was merged by GitHub while this review was in progress. I stopped all branch writes once the state changed and did not perform the merge.
• Final refs: PR head ad00b237c8ab9b67a5836fbdf5e247d9c03b6a90; merge-time base 1fbcc2340a305e6aae172a0c30274cd2400ad39b; squash merge commit on main2ae5a0aa5d339a7dc9089db134c2d9d0220444ae.
• Sync / merge-tree state: the final head is 12 commits ahead of the merge-time base but has an identical tree, with zero changed files. The squash merge commit is likewise zero files different from its parent. The competing branch was resolved by retaining current main, where PR feat(filters): services adopts the filter contract (PR C, rebased — supersedes #1866) #1878 had already delivered the newer Services implementation and subsequent fixes.
• Issues and scope: no remaining net PR feat(services): adopt the filter contract with real facets (PR C) #1882 delta existed to modify at the final head. The previously reported P2 query-preservation and care-lens projection issues had already been addressed; all three inline review threads are resolved and outdated. No additional P0/P1 finding remained on the final no-diff head. Unrelated pre-existing debt was left out of scope.
• Adversarial review: CodeRabbit was unavailable because the organisation had reached its review limit/spending cap. A separate manual adversarial pass covered correctness, URL/filter semantics, projection counts, compatibility, security/privacy, regression risk and missing-test risk. Potential concerns in the superseded pre-sync implementation were not carried into the final head because its tree exactly matched current main.
• Local verification: before the PR state changed, targeted TypeScript syntax and focused facet/lens/scope regression probes were run against the pre-sync delta. These are supporting evidence only and are not presented as verification of the changed final head. Final-head GitHub CI is authoritative.
• Exact-head required CI:Static PR checkssuccess; PR requiredsuccess. No required gate was pending or failed at merge. Production UI completed as skipped, not green/run, because the final head had no file delta. Other path-gated jobs were also skipped under the zero-diff classification.
• Advisory CI: CI workflow success; SAST success; Secret Scan success. Supabase preview was ignored because no supabase directory changes were detected. CodeRabbit remained unavailable/rate-limited.
• Ledger: no ledger-only tip was pushed. Because the PR merged during review, no post-merge ledger mutation was made. The final merged tree does not contain a new immutable PR feat(services): adopt the filter contract with real facets (PR C) #1882 review record; this is a residual process note, not a code blocker.
• Residual risk: live verification that production service registry rows contain fully populated catalog_payload.tags remains outstanding, as already disclosed in the PR body. No live/provider-backed or production checks were run by this review.

Merge notice: the PR was already merged externally while this review was in progress. No merge action was performed by this review.