Design scope

HeapDB ranks likely causes and explains each one. It is designed for the moment when a short, explained list beats reading everything: an error spike, a churned user, an agent turn that needs the right context. This page says what a ranking means and which tools pair well with it.

What a ranking means

A confirmation ("PR #4107 was reverted") adds evidence to the links of #4107's features for that effect. Over time migration → error_spike gets stronger if migrations keep being the thing that was reverted. That is a learned association used for ranking: it tells you where to look first, with the evidence for each result. For proven causal effects, pair HeapDB with experiments, bisection or causal-inference methods; HeapDB's ranking tells you which candidates to test first.

Timing narrows the search

The lag kernel says when a cause of this kind usually shows up. Timing alone would favor whatever happened at the right moment, so the score also uses links (what has caused this before), and feedback moves a well-timed but innocent change down. Timing narrows the search; links and feedback decide the order.

Correlated features

When two features usually appear together (AI-authored PRs are often large and reviewed fast), HeapDB keeps credit where it belongs:

• Proportional credit (EM for noisy-OR): a confirmation gives each feature credit in proportion to how much it already explained the effect, so a weak rider is not inflated alongside the real cause.
• Joint causes: features that have always co-occurred are reported as one cause (coffee+dairy) with an inseparable flag, instead of being credited arbitrarily.

Detecting partial overlap (two features that co-occur 80% of the time) is on the roadmap. See Learning and EXPLAIN.

Day one, before any feedback

With no feedback, ranking comes from the kernel, the dose and priors: per-effect priors you register (migrations start suspect, docs-only changes are blocked by a rule) and evidence pooled across entities (capped so it guides without overriding). Good priors give you a useful ranking from the first query, and feedback sharpens it from there.

How much feedback helps

That depends on how many distinct features you have, how often effects fire and how consistent the feedback is. heapdb-core's examples/code_changes.py (v0.3) simulates a week of about 150 PRs with hidden ground truth and prints attribution accuracy for the first and second half of the week, with and without feedback, averaged over seeds. In that simulation priors already do most of the work, and the clearest effect of feedback is that a confounded feature (ai_authored) stays low under proportional credit while uniform credit would inflate it.

How to read a score like 0.36

• It is a relative ranking score for one question: kernel × dose × noisy-OR of links × rules. A higher score means "more likely, given what HeapDB knows", within the same effect.
• It is a ranking score, not a probability or a percentage. A heavy dose can push a score above 1.
• Scores for the same effect compare roughly across entities, and precisely once calibrated.
• They become probability-like after calibration: every feedback call records the score each judged candidate had, and calibration_report(effect) (CALIBRATION OF effect) compares mean predicted score with the observed confirm rate per bin, with a Brier score. Automatic recalibration is on the roadmap.

Features and feedback drive quality

HeapDB ranks on what the events carry. Rich features (path:payments/retry, migration, review:fast) and feedback from reverts and postmortems are where most of the value comes from, and the connectors extract both automatically. Judging more than the top answer (rejecting the other top candidates too) keeps the links balanced.

What HeapDB is built for, and what to pair it with

• Built for ranking with evidence. When the most recent change is almost always the answer, a time sort is enough; HeapDB adds value when several candidates are plausible and timing, features and history together decide.
• Built to learn from feedback. Without confirmations or rejections, HeapDB still ranks with good defaults from kernels, doses and priors; feedback is what makes it improve over time.
• Pairs with causal methods. Use experiments, bisection or causal inference to prove an effect; HeapDB tells you where to look first.
• Pairs with your databases. Keep Postgres, your warehouse and your vector store for records and search. Run HeapDB in-process with JSONL snapshots, or as heapdb-server with a write-ahead log and snapshots on local disk or S3. A persistent LSM storage engine is on the roadmap.