#169 — check-engine walking skeleton: heuristics! registry + supersedes pipeline + grain.unique-key-unbacked

[cmbays]

Summary

Closes #169 (Lane-A of epic #168). The coverage-intelligence check engine walking skeleton at the payload level — NO template/render-surface changes (the findings surface is #170).

What landed

• heuristics! single-source macro (src/domain/checks.rs): one central block declares each check's spec metadata + detector fn adjacently and generates the HeuristicId enum, SPECS (one HeuristicSpec per variant, declaration order), and the id→detector pairing as an exhaustive no-wildcard match. Spec-without-detector / detector-without-spec fails macro expansion; a dangling supersedes entry references a nonexistent enum variant and fails to compile.
• Verdict model (per the feature: check-engine walking skeleton — heuristics! registry + supersedes pipeline + byte-gated ledger + grain.unique-key-unbacked #169 founder comment): a Finding is a verdict per (construct, check) — Covered { by: [test ids] } (attribution from day one) / Uncovered (recommendation fires) / Unknown (honest tier, never nagged). SUPPRESSED is display-layer only and deliberately not a variant. Finding::new denormalizes tier/instrument/recommendation from the spec so detectors cannot mislabel them.
• Fixed pipeline order: evaluate_all (every registered check, always) → resolve_supersedes (drop findings superseded by another fired finding on the same (model, construct); shallow, no chaining) → filter_for_display (downstream). The required invariant is pinned: disabling the superseding check does NOT resurrect the superseded finding. Supersedes acyclicity is a total unit test (a deliberately-cyclic macro-generated registry proves the gate detects cycles).
• grain.unique-key-unbacked (TOTAL tier, data-test instrument): fires on config.unique_key (new typed NodeConfig::unique_key() accessor — string OR list-of-strings, with a tolerant Unrecognized arm → UNKNOWN verdict); satisfied by any enabled uniqueness data test attached to the model whose column set ⊆ the key (case-folded). dbt_utils.unique_combination_of_columns stays composite — fusion's PK inference flattens it per column, which would be unsound here.
• Generated byte-gated ledger: heuristics/registry.toml + book/src/checks/{index,grain.unique-key-unbacked}.md are generated from SPECS with a GENERATED header; tests/heuristics_ledger.rs compares byte-identity in default mode and writes in GEN_HEURISTICS_LEDGER=1 mode; new heuristics-ledger CI job (regenerate-and-diff, the example-report-check pattern) + the matching lefthook.yml pre-push mirror.
• Payload exposure: ModelPayload.findings (serde-skipped when empty), computed during payload assembly via the fixed pipeline — the parse_ctes precedent for run-loop work happening one stage downstream.
• Dogfood: dbt-project/models/marts/customer_order_days.sql — incremental delete+insert at the composite (customer_id, order_date) grain with deliberately NO uniqueness test (the list wire form; order_events_incremental remains the COVERED-with-attribution example). Source files only; no target/root_path artifact.

dbt-fusion verification (source-first)

Pinned to dbt-fusion 9977b6cbb1b761065536300037560d8e3c037011:

• DbtUniqueKey = untagged Single(String) | Multiple(Vec<String>) (dbt-schemas/src/schemas/common.rs; carried as Option<DbtUniqueKey> on the model config).
• Test-kwargs extraction + enabled-with-default semantics mirror dbt-parser/src/resolve/resolve_tests/../primary_key_inference.rs (kwargs.column_name string for unique; kwargs.combination_of_columns string array for the composite) — except the flattening, which is deliberately not copied.
• Verified against the real committed playground-current.json fusion fixture (tests/check_engine.rs): composite-key UNCOVERED (fct_encounters_monthly), string-key COVERED with attribution (fct_encounters_incremental), and the real dbt_utils.unique_combination_of_columns on fct_patient_summary correctly NOT attributing at the single-column grain. Plus an insta snapshot pinning the findings payload contract feature: report findings surface — per-model coverage checklist + tiered findings + suppressed-count #170 consumes.

Builder's calls (Discovery items)

• gen-registry is test-mode write+compare (GEN_HEURISTICS_LEDGER=1 cargo test --test heuristics_ledger), not a bin target — zero new binary surface, runs inside the normal test battery in default mode, CI job does regenerate-and-diff.
• HeuristicSpec field set: id (variant) / id_str / name / group / tier / instrument / supersedes / evidence / conditions / exclusions / recommendation / rationale.
• Book wiring done in this PR (SUMMARY gains a Checks section; tests/heuristics_ledger.rs pins every generated page is SUMMARY-listed and no stale pages exist) — no mdbook follow-up needed.
• New BDD file features/coverage_checks.feature (a new product surface rather than extending an existing feature's contract): feature-count bumped 12 → 13 in both ci.yml and lefthook.yml.
• Engine pipeline is generic over a CheckId trait implemented only by macro expansion — that is how multi-check supersedes/suppression behaviour is tested (synthetic macro-generated registries) while the production registry holds one check.

Goldens

examples/playground-report.html + examples/diff-showcase-report.html regenerated: their fixture models carry unique_key, so they gain findings entries. Verified findings-payload-only: payload-minus-findings and the full non-payload chrome are byte-equal to the previous artifacts; examples/jaffle-shop-report.html (no unique_key anywhere) is untouched. All three re-verified byte-identical to fresh renderer output.

Gates (run directly — lefthook skips in fresh worktrees)

• cargo fmt --all --check ✅
• cargo clippy --all-targets --locked -- -D warnings ✅ (exit 0)
• cargo nextest run --all-targets --locked ✅ 844 passed
• cargo test --test bdd ✅ 13 features / 92 scenarios / 580 steps, all passed
• cargo test --test headless_zero_egress --locked -- --ignored ✅; headless_toggle ✅ 29 passed (untouched-green)
• RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --document-private-items --locked ✅
• cargo deny check ✅
• mdbook build book ✅
• dbt-fusion 2.0.0-preview.177 dbt compile on dbt-project ✅ (8 models / 23 tests / 3 seeds)
• heuristics ledger byte-gate ✅ (regenerate-and-diff clean)

Note for the orchestrator

The new heuristics-ledger CI job is not a required branch-protection context yet — wire it post-merge.

🤖 Generated with Claude Code

---

[coderabbitai]

Warning

Review limit reached

@cmbays, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 10 minutes and 31 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

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.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a8ac471b-80f1-4b4a-85ea-a27d70f073e0

📥 Commits

Reviewing files that changed from the base of the PR and between fc6e1d4 and 216bde8.

⛔ Files ignored due to path filters (1)

• tests/snapshots/check_engine__playground_unique_key_findings.snap is excluded by !**/*.snap

📒 Files selected for processing (21)

• .github/workflows/ci.yml
• book/src/SUMMARY.md
• book/src/checks/grain.unique-key-unbacked.md
• book/src/checks/index.md
• dbt-project/models/marts/_incremental__models.yml
• dbt-project/models/marts/customer_order_days.sql
• examples/diff-showcase-report.html
• examples/playground-report.html
• features/coverage_checks.feature
• heuristics/registry.toml
• lefthook.yml
• src/adapters/render.rs
• src/domain/checks.rs
• src/domain/manifest.rs
• src/domain/mod.rs
• tests/check_engine.rs
• tests/heuristics_ledger.rs
• tests/steps/builders.rs
• tests/steps/coverage_checks.rs
• tests/steps/mod.rs
• tests/steps/world.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature-169-check-engine-skeleton

---

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 and usage tips.}

[ghost]

Ready to review this PR? Stage has broken it down into 8 individual chapters for you:

	Title
1	Define unique key types and accessors
2	Implement the core heuristic check engine
3	Wire findings into the model payload
4	Verify check engine with real fixtures
5	Generate and gate the heuristics ledger
6	Add acceptance tests for coverage checks
7	Update examples and dogfooding project
8	Other changes

_{Chapters generated by Stage for commit 216bde8 on Jun 10, 2026 4:04pm UTC.}

[gemini-code-assist]

Code Review

This pull request introduces the coverage-intelligence check engine, implementing the grain.unique-key-unbacked check to identify models with declared unique keys that lack backing uniqueness tests. It adds the core pipeline for evaluating checks, resolving supersedes, and filtering findings, along with automated ledger generation, documentation, and comprehensive integration tests. Feedback on the changes suggests an improvement in src/domain/manifest.rs to parse the unique_key string array more idiomatically and avoid unnecessary string allocations by using into_iter and collecting into an Option.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[github-actions]

📄 Rendered report preview

All golden examples regenerated cleanly.

🟡 Golden examples

Committed to examples/ and byte-identity gated — the canonical reports contributors and consumers browse. Stable across PRs.

Report	View	Download
diff-showcase-report.html	▶ Open ↗	⬇ Download
playground-report.html	▶ Open ↗	⬇ Download
jaffle-shop-report.html	▶ Open ↗	⬇ Download

🐶 Live dogfood preview

This PR's own dbt-project/ diff, freshly compiled by fusion into an ephemeral manifest (never committed) and rendered with --pr-diff. Regenerated every PR — the live self-dogfood, not a committed example.

Report	View	Download
dbt-project-report.html	▶ Open ↗	⬇ Download

▶ Open ↗ opens the report in your browser in one click —
published to this repo's GitHub Pages under /pr-186/.
⬇ Download fetches the same self-contained HTML as a workflow
artifact (auth-gated; works fully offline). Either way the report
makes zero external resource requests.

The Pages preview may take ~1 min to update after this comment
posts. On PRs from forks the Open link is unavailable (read-only
token) — use Download.

Alternative: GitHub CLI

# gh CLI >= 2.63 extracts into ./report-preview-playground/.
gh run download 27288984654 -R breezy-bays-labs/cute-dbt -n report-preview-playground
open report-preview-playground/playground-report.html

---

_{Posted by report-preview.yml for 216bde8f3973c5242cc937061efd8994231ca192. Affordance only — never blocks merge.}