Parallax
What a review means
A finding is one mechanism with an evidence state and a confidence. This page gives the exact rule for each word on a review.
A finding is a mechanism
Several lenses and several reviewer seats read the same change. When two of them name the same defect, the review counts it once. Two findings are one mechanism when any of these holds:
- they carry the same patch: same file, same replaced text, same replacement, whitespace aside;
- their patches replace the same range: the same file and a shared non-trivial line (12 or more characters after trimming) of the replaced text;
- they name the same root cause in prose (named symbols overlap at 0.6, or the words of title and reason overlap at 0.5 Jaccard, both over six distinct words) and share at least one file.
One mechanism carries every lens and every seat that named it, and the strongest evidence any copy earned. It is suggested once, on the copy that carries that evidence. The headline counts mechanisms, never copies: a defect three lenses found is 1 finding, not three.
Source: packages/verdict/cards/verdict.json
Evidence states
Every finding with a patch is delivered. What changes is the label it carries, which says what the sandbox established about that exact patch. Verification is evidence; it is not a gate.
| state | the exact rule | × |
|---|---|---|
proven | The reproduction ran and passed: a new test failed on the code as it was and passed with the fix (for a doc-drift finding: the referent is really gone). Not contested by an adversary seat. Later suite results are reported separately and do not undo that proof. | 2.0 |
suite_green | The suite is green with the patch applied, and no failing-then-passing test was supplied. The patch did not break anything; nothing showed it fixes something. | 1.0 |
unverified | No reproduction established the claim: no test command, no executable change, a prose judgement, a proven finding an adversary contested, or a finding the lens's scope rule sent away. An untested patch that breaks the suite also stays unverified, with an unsafe-patch warning. | 0.8 |
could_not_run | The proof could not finish and refuted nothing: a missing toolchain, repository preparation failure, the review clock, a reproduction step that timed out, or a patch that did not apply. A red baseline blocks suite-only checks, but a reproduction can still prove a defect. The line names the reason. | 0.8 |
refuted | The reproduction ran and did not hold: the new test passes without the fix, or the fix fails to make that test pass. A suite-only performance check can also refute its rewrite. A later full-suite failure does not refute a successful defect reproduction. | 0.2 |
× is the multiplier the state applies to the confidence below. unverified and could_not_run share one value on purpose: nothing was learned either way.
Source: packages/lens/cards/delivery.json · packages/precheck/cards/precheck.output.json
Severity and reachability
Impact describes the consequence for a real caller: critical, high, moderate or low, with one line explaining how the caller reaches it. It is separate from confidence and proof. A proven edge case can be low impact; an unverified opt-out violation can be high impact. A mechanism described only as edge input only belongs under Cleanup, whatever its proof.
A missing rating is unrated. The verdict can fill omitted fields from a promise the fix restores, defaulting to high, only after it verifies the cited line at the reviewed commit. An invalid citation creates no rating, and explicit reviewer fields are preserved. The ledger’s severity counts include complete ratings supplied by reviewers; these inferred defaults are not counted there.
Source: packages/conformance/cards/conformance.input.json · packages/verdict/cards/verdict.json · packages/ledger/cards/ledger.output.json
Confidence
Each finding carries one number from 0 to 1, rounded to two decimals:
confidence = min(1, stated × seat × multiplier)
if proven: confidence = max(confidence, 0.90)- stated: the reviewer’s own 0–1 for the finding; 0.5 when it gave none.
- seat: the seat’s calibration on this lens, on your account, once it has five decided records. Until then the factor is 1: a confidence is never lowered without enough evidence.
- multiplier: the evidence state’s value from the table above.
A proven finding has a confidence floor of 0.90, even when its patch regresses the suite; the unsafe patch still cannot be applied with one click. A contested finding is unverified and has no floor. This is an evidence-weighted score, not a calibrated probability.
The seat score is a record of what that model’s findings on that lens turned into, on your repositories. It is one fraction:
score = (proven − contested + settled + 2·merged + 1)
/ (proven + settled + unsettled + rejected + 2·merged + closed + 2)A fix PR you merge counts twice in both places; one you close counts against. A proof another lab broke moves from the numerator to the denominator. With no record the score is 0.5, and a seat is only moved ahead of the router’s pick on a lens once it has three decided findings there and beats the other by 0.15. So calibration moves a confidence slowly, in the direction of your own merges and closes.
One more multiplier exists. When a finding recommends a change that a line in the repository explicitly contradicts, and the reviewer cited that line, the door re-reads the file at head and checks the quote sits within two lines of the citation. A verified contradiction multiplies the confidence by 0.2 and moves the finding to the notes (below). A citation that does not verify changes nothing; a label is dropped, never invented.
Source: packages/lens/cards/delivery.json · packages/calibration/src/index.ts · packages/verdict/cards/verdict.json
The comment
The check-run summary has one headline and a compact list grouped by evidence and purpose. The headline counts mechanisms in Review and Unverified candidates only; cleanup and notes are their own tokens, so 2 findings, 1 proven · 3 cleanup · 1 note is read without mixing them.
| section | holds |
|---|---|
| Review | defect and perf mechanisms with a finished verification: proven, suite green, and refuted (listed last, badge refuted). |
| Unverified candidates | defect and perf mechanisms with no finished verification: unverified and could not run, the reason on the line. |
| Notes | mechanisms demoted by a verified contract contradiction, delivered as prose with the line they contradict. |
| Cleanup | mechanisms whose copies are all hygiene, drift (docs and comments), or perf rewrites that claim no speed; also mechanisms whose strongest impact says edge input only. Whatever their evidence; a verified contract contradiction belongs in Notes. |
| Dead code | symbols the mechanical scan proved removable, shown after the mechanism groups and counted separately in the headline. |
| Partial review | present only when the review did not complete: which seats did not finish every lens, which shards were not reviewed, which lenses were skipped or cut. Facts, never a count. |
Within Review, Unverified candidates and Cleanup, mechanisms are ordered by impact, then evidence and confidence; refuted mechanisms are last in their section. The compact list shows at most 15 findings and dead-code entries; the check run’s details carry the rest. A partial review leads with Review incomplete, even when it proved a defect. If no reviewer read the diff and the run failed or was skipped, the headline says Review did not run. The collapsed How this review ran block records the reviewers, coverage, tests at head, clock, cost, failures and remaining work. Confidence in the headline is the mean of the Review and Unverified candidates mechanisms; elapsed time and settled cost follow it.
A finding with an applicable patch also gets a review comment on its exact lines. The first line is the label, Parallax · PROVEN · confidence 100%, then the lens and title, the reason, the proof steps that ran, and a ```suggestion block you can apply with one click. A refuted finding posts the same comment without the suggestion block: the sandbox watched that patch fail, and the comment says so rather than hiding it. A note or a patch that regresses the suite has no block either.
GitHub line annotations are separate: one per proven mechanism, with dead-code notices listed separately. An unverified comment is not a proven annotation, and incomplete coverage never reads as a clean review.
Source: packages/verdict/cards/verdict.json · packages/github/src/render.ts · packages/github/cards/github.output.json · packages/github/tests/fixtures/render/mixed-evidence.summary.md
The fix PR
Each source pull request has at most one follow-up, on parallax/review/<number>, refreshed as the source head changes. While a source PR in the same repository is open, the fix PR targets its head branch so you can merge the fixes into your change. After the source closes, or when its head lives in a fork, the target is the source’s base branch instead.
The fix plan gathers each seat’s candidate for a mechanism. When multiple seats propose fixes, they can challenge one another; among the remaining candidates, the router’s rank chooses one implementation, with evidence and confidence breaking ties. The body records the chosen patch, its label and the alternatives considered. Refuted and unsafe patches are never chosen. A patch that cannot apply after the earlier fixes is skipped with its reason. A review with nothing to deliver opens no PR.
A retry reuses the existing fix PR. Closing or merging it is final: Parallax never reopens it, overwrites a maintainer’s commit on its branch, or merges it for you.
With deliver: proven-only in parallax.yml, only proven patches reach the PR and the suggestions; the rest stay listed in the check run. On an end-of-session sweep, the cleanup lenses batch into one parallax/housekeeping/<day> PR per repository per day, one commit per finding.
Source: packages/server/cards/pr-followup.input.json · packages/server/cards/pr-followup.output.json · packages/converge/cards/converge.input.json · packages/converge/cards/converge.output.json · packages/deliver/cards/policy.json
First pass, deep pass
When automatic pull-request review is enabled, or you explicitly request a review, two passes share one check run. Automatic PR review is off by default; the operator enables it with PARALLAX_PR_REVIEW=on.
- First pass. One seat that passes the same quality floor as every other reviewer reads the diff alone: no transcript, no graph, no sandbox, no second seat. Its suggestions are on the PR within minutes, every one labelled
UNVERIFIED. The seat is chosen by measured latency on your account among the admitted candidates, never by asking a lesser model. - Deep pass. Clone, router-picked reviewers, regressions, the code graph, the cross-session horizon, your repository’s preference record, history, then the lenses (seats × shards × proofs in the sandbox), the precheck of the suite at head, dead code, one check-run post, then the suggestions. It refreshes the first pass’s comments in place by marker.
A first-pass suggestion is withdrawn in exactly one case: the deep pass refuted a patch on the same lines. A deep result that could not run, or a deep pass that did not find the mechanism again, leaves it standing.
Source: packages/latency/cards/latency.input.json · packages/server/cards/server.input.json
What to do with a review
Apply a suggestion from its comment, or merge or close the fix PR. Both are read back: an applied suggestion or a merged fix becomes a lesson for the repository, and a dismissed one (a reply refusing it, or a closed fix PR) becomes a suppression with your words as the reason. How that works is on Memory.
Source: packages/github/cards/acceptance.input.json · packages/continual/cards/write-back.input.json