security(consensus): atomic Sophia epoch settlement (synthesis of #6757 + #6760)

[Scottcjn]

Atomic Sophia epoch settlement — synthesis of #6757 + #6760

@yyswhsccc (#6757) and @Ishant5436 (#6760) independently submitted the same sophia_elya_service.py settlement fix. This combines the best of both — yyswhsccc's fix + settlement test suite and Ishant5436's doc (MINE_YOUR_GRANDMAS_COMPUTER.md) — into one PR, with the tri-brain BLOCKINGs fixed.

What it does

• finalize_epoch: BEGIN IMMEDIATE + atomic claim (settled=1, finalized=1 WHERE COALESCE(settled,0)=0, rowcount-checked) — closes the double-settlement window on the Sophia path. Post-claim payout in try/except → rollback (no half-paid epoch). PRAGMA busy_timeout=5000 so concurrent block-ingest waits instead of erroring "database is locked".
• Migration: adds settled/settled_ts, normalizes NULL→0 (so a legacy/shared row can't become permanently unpayable), and backfills finalized→settled once (only when the column is first added — never on later startups, which could suppress a two-phase settle). ALTER wrapped against concurrent-startup races.
• inc_epoch_block: guard + busy_timeout so a late block can't inflate the count the reward was computed against.
• get_epoch now exposes settled/settled_ts (additive).

Tests (9, all green)

incl. idempotent-pays-once, NULL-settled-payable, inc-after-finalize-frozen.

Tri-brain (Codex + Grok; GPT-OSS offline) — 3 loops

Fixed: NULL consistency, busy_timeout, tx rollback, one-time backfill, ALTER TOCTOU.

⚠️ Scope

This fixes the Sophia path. Cross-module epoch_state coordination (rewards_implementation / anti_double_mining schema + the rolling-deploy mixed-version window) is the broader #6749 work — deploy all settlement instances together. Complements the main-node fix in #6748.

Co-authored-by: @yyswhsccc · @Ishant5436. Supersedes #6757 and #6760.

🤖 Generated with Claude Code

[github-actions]

✅ BCOS v2 Scan Results

Metric	Value
Trust Score	60/100
Certificate ID	BCOS-ffa45ed9
Tier	L1 (met)

What does this mean?

The BCOS (Beacon Certified Open Source) engine scans for:

• SPDX license header compliance
• Known CVE vulnerabilities (OSV database)
• Static analysis findings (Semgrep)
• SBOM completeness
• Dependency freshness
• Test infrastructure evidence
• Review attestation tier

Full report | What is BCOS?

---

BCOS v2 Engine - Free & Open Source (MIT) - Elyan Labs

[Scottcjn]

✅ Tri-brain review → MERGE (CHAOTIC-regime gate cleared)

Ran the recurrent-depth dev loop (Brain 2 Codex 5.5 + Brain 4 Grok; Brain 3 GPT-OSS down — loop ran degraded/dual-brain). Both brains raised BLOCKING findings; Brain 1 (Coda) resolved them against the repo, which the sandboxed brains could not read (Grok: node/ does not exist, 3 calls exhausted; Codex worked from diff text only).

Codex BLOCKING — migration assumes finalized ⟹ paid: ✅ resolved. The main node (rustchain_v2_integrated_v2.2.1_rip200.py) never writes epoch_state.finalized (grep empty) — its only settlement flag is settled (line 3685, identical WHERE settled=0 atomic claim). So finalized is Sophia-exclusive, and old Sophia set finalized=1 after crediting → finalized=1 ⟹ already-paid. No writer can produce a legit finalized=1, settled=0 needing payment. Backfill is sound.

Grok BLOCKING — settled column may not exist (crash on read/write): ✅ pre-existing main-node defect, mitigated by this PR. Main node references settled (3533/3685) but its CREATE TABLE (1425) omits it and it has no ALTER — a latent fresh-DB crash. This PR's _ensure_epoch_state_settlement_schema ALTER adds the column the main node needs.

Cross-path coordination is correct: main node and Sophia share the settled flag; whoever wins WHERE settled=0 settles+pays, the other gets already_settled → no double-pay.

Residual (money-safe, cosmetic): on the live DB the column already exists, so the one-time backfill is skipped; legacy finalized=1 rows stay settled=0. Those were already paid by old Sophia, so finalize correctly returns already_finalized and pays nobody — only the reason string differs. No funds at risk.

CI: the red test check is pre-existing on main (collection error no such column: bridge_fee_i64 in test_c11_bridge_confirm_unbounded_poc.py, unrelated). This PR's 9 money-unit tests pass locally.

Follow-ups filed under the #6749 cross-path-settlement design track: (1) main-node CREATE TABLE epoch_state should include settled/settled_ts; (2) fix the bridge_fee_i64 collection error so the test gate goes green.