Skip to content

Decide trust from a stated cause, never by elimination - #15

Merged
khalidsaidi merged 2 commits into
mainfrom
fix/canonical-outage-buries-finding
Nov 17, 2026
Merged

khalidsaidi merged 2 commits into
mainfrom
fix/canonical-outage-buries-finding

Conversation

@khalidsaidi

@khalidsaidi khalidsaidi commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Two bugs of the same shape, the second introduced while fixing the first.

1. An unreadable head buried a confirmed finding

main() returned 2 on not history.canonical before comparing any observed transfer against the ledger, so a budget exhausted at the final identity check turned a confirmed unaccounted movement into a CI deferral — a green build over real evidence.

Two unlike causes cleared that one flag: the head changed (positive proof the snapshot's basis is gone) and the head could not be read (an outage, which says nothing about what was already observed).

2. ...and the fix called a contradictory source an outage

The first fix decided by elimination: not a reorg, therefore an outage. But HistoryConflict returns before the head re-check runs, so a source that contradicted itself was indistinguishable from one that was unreachable — and its observations, which @gjwang's handler deliberately discards ("do not preserve a finding produced by the contradictory records"), came back as a violation.

Reproduced on 06b39f3, an unledgered movement committed by an early page and a later page binding a block hash already bound to another number:

exit code: 1
history not re-confirmed: conflicting block number/hash in history
RESULT: FAIL — ...which is an outage and not a reason to withhold it.

It was not an outage. The code said so because nothing had said otherwise.

The fix

Every cause that makes observations untrustworthy sets invalidated explicitly; the verdict reads that flag instead of deducing it. A future cause that forgets to set it is inconclusive at worst — before, anything unanticipated defaulted to "trust the observations and report a violation".

Three outcomes, now distinct and each tested:

situation exit reason given
head replaced under the snapshot 2 Observations are tied to a head the chain has replaced.
source contradicts itself 2 The source served records that contradict each other.
re-confirmation unreadable, violation observed 1 the check that would have re-confirmed it could not be completed
re-confirmation unreadable, nothing observed 2 inconclusive

Tests

script/test_canonical_outage.py — 5 cases. Three fail without the first fix, one errors without the second. The pre-existing history-scan tests pass either way: they cover a failed page and a changed head, never an unreadable or self-contradictory one holding an observed violation. @gjwang's test_head_change_invalidates_unconfirmed_observations still passes.

136 Python, 11 Solidity. Verified live against Base mainnet: a real transfer removed from the ledger is still exit 1; the real ledger still passes.

Neither bug is evidence of an actual unaccounted live transfer — the full scan on main is green.

🤖 Generated with Claude Code

https://claude.ai/code/session_012mggwNhgEyvfn1q6Lrdk3Q

An unaccounted movement observed in a complete, successfully scanned history
could be reported as a CI deferral — a green build over real evidence.

main() returned 2 on `not history.canonical` before it had compared a single
observed transfer against the ledger, and two unlike causes both cleared that
flag:

  * the fixed head's hash CHANGED — positive proof the snapshot's basis is
    gone, so observations tied to it say nothing about the current chain
  * the head could NOT BE READ — an outage, which says nothing at all about
    what was already observed

Collapsing them meant a budget running out at the final identity check buried
a confirmed finding. That is issue #10 at a different gate: the run goes quiet
about evidence it already has because a later read failed. It is also the
defect @gjwang reported in the allowance handler, which this code fixed there
and reintroduced here.

The decision now happens after the observations exist and names the cause. A
changed head still returns 2 and says the basis was replaced. An unreadable
head with an observed violation returns 1 and says the re-read failed. An
unreadable head with nothing observed stays inconclusive, as it must.

Reproduced on ff43856 before the change; script/test_canonical_outage.py
fails three ways without it. Verified live against Base mainnet: a real
transfer removed from the ledger is still exit 1, the clean ledger still
passes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012mggwNhgEyvfn1q6Lrdk3Q
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T00:41:19.861271Z 32d8b3f PR opened
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 32d8b3f49c

ℹ️ 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".

Comment thread script/verify_ledger.py
Comment on lines +767 to +772
if not history.canonical and unaccounted:
print(f"history not re-confirmed: {history.error}")
print("\nRESULT: FAIL — unaccounted movement observed in complete, "
"matching history; the head could not be re-read, which is an "
"outage and not a reason to withhold it.")
return 1

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep contradictory history separate from head-read outages

If an earlier page contains an unledgered movement and a later page raises HistoryConflict, derive_transfers() returns immediately with canonical=False and head_changed=False, retaining the earlier transfers. This branch now reports an accounting violation even though the history was explicitly invalidated, rather than returning 2 as before. This includes a log at the fixed head having a different block hash, not just duplicate-record conflicts. I reproduced exit 1 using an unledgered transfer in the first page and conflicting copies of one log in a later page. Preserve a distinct invalid-history outcome and exclude it from the outage-only failure path.

Useful? React with 👍 / 👎.

The previous commit let an observed violation survive a head it could not
re-read, and decided that by elimination: not a reorg, therefore an outage.
HistoryConflict returns before the head re-check ever runs, so a source that
CONTRADICTED itself was indistinguishable from one that was merely
unreachable, and its discarded observations came back as a violation.

That inverts the guarantee gjwang wrote into the conflict handler — "do not
preserve a finding produced by the contradictory records" — which this commit
had quietly overridden.

Reproduced on 06b39f3: an unledgered movement committed by an early page,
then a later page binding a block hash already bound to another number.

  exit code: 1
  history not re-confirmed: conflicting block number/hash in history
  RESULT: FAIL — ...which is an outage and not a reason to withhold it.

It was not an outage. The code said so because nothing had said otherwise.

Every cause that makes observations untrustworthy now sets `invalidated`
explicitly, and the verdict reads that flag instead of deducing it. A future
cause that forgets to set it will be inconclusive at worst; before, anything
unanticipated defaulted to "trust the observations and report a violation".

The three outcomes are now distinct and tested as such: a replaced head and a
self-contradictory source are both 2 with different reasons, an unreadable
check with an observed violation stays 1.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012mggwNhgEyvfn1q6Lrdk3Q
@khalidsaidi khalidsaidi changed the title A head we could not re-read is not a head that changed Decide trust from a stated cause, never by elimination Nov 17, 2026
@khalidsaidi
khalidsaidi merged commit e31fd27 into main Nov 17, 2026
4 checks passed
@khalidsaidi
khalidsaidi deleted the fix/canonical-outage-buries-finding branch November 17, 2026 05:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant