# Preconfirmation and Event-Sync Invariant Reference Map

This map links each invariant to behavior-level source anchors.

The `WLP` invariant prefix is kept for continuity. Scope includes `crates/driver`, `crates/whitelist-preconfirmation-driver`, and `crates/rpc`.

## Coverage Matrix

| Invariant     | Local Rust Behavior Anchors (`taiko-client-rs`)                                                                                                                                                                                                                                                                                                                                                                                        | External Behavior Anchors (`alethia-reth` / protocol)                                                                                                                                                                                                                                       |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WLP-INV-001` | `crates/driver/src/sync/event.rs` (safe resume source resolution; no unsafe latest fallback)<br>`crates/driver/src/sync/event.rs` (finalized-bounded event replay start)<br>`crates/driver/src/sync/error.rs` (explicit fail-closed resume-source errors)                                                                                                                                                                              | `alethia-reth/crates/rpc/src/eth/eth.rs` (public head/per-block origin queries used by resume assumptions)                                                                                                                                                                                  |
| `WLP-INV-002` | `crates/driver/src/sync/event.rs` (scanner-live + confirmed-sync gating before ingress opens)<br>`crates/driver/src/sync/confirmed_sync.rs` (strict readiness model)<br>`crates/driver/src/preconf_ingress_sync.rs` (whitelist importer blocks on ingress readiness)<br>`crates/whitelist-preconfirmation-driver/src/importer/mod.rs` (importer readiness adds genesis exception: `head_l1_origin.is_some() \|\| nextProposalId == 1`) | `alethia-reth/crates/rpc/src/eth/auth.rs` (batch-to-last-block and related lookup behavior for readiness inputs)                                                                                                                                                                            |
| `WLP-INV-003` | `crates/driver/src/sync/event.rs` (stale checks before enqueue and during ingress)<br>`crates/whitelist-preconfirmation-driver/src/importer/cache_import.rs` (drops cached stale payloads; missing `head_l1_origin` treated as genesis boundary 0)<br>`crates/whitelist-preconfirmation-driver/src/importer/ingress.rs` (does not serve unsafe responses at/below confirmed boundary)                                                  | `alethia-reth/crates/rpc/src/eth/eth.rs` (`head_l1_origin` is available as stale-boundary signal)                                                                                                                                                                                           |
| `WLP-INV-004` | `crates/driver/src/sync/event.rs` (confirmed-boundary stale enforcement around preconf ingress)<br>`crates/whitelist-preconfirmation-driver/src/importer/cache_import.rs` (parent recovery constrained by confirmed boundary)                                                                                                                                                                                                          | `alethia-reth/crates/rpc/src/eth/error.rs` (uncertain/lookback-protection semantics for batch-last-block resolution)                                                                                                                                                                        |
| `WLP-INV-005` | `crates/driver/src/sync/confirmed_sync.rs` (target/head consistency readiness rule)<br>`crates/driver/src/sync/event.rs` (confirmed-sync snapshot built from protocol + custom tables)                                                                                                                                                                                                                                                 | `alethia-reth/crates/rpc/src/eth/auth.rs` (batch-to-last-block resolution path including fallback/uncertainty behavior)                                                                                                                                                                     |
| `WLP-INV-006` | `crates/driver/src/derivation/pipeline/shasta/pipeline/payload.rs` (writes per-block origin, head pointer, and batch mapping via RPC)<br>`crates/rpc/src/l1_origin.rs` (public origin/head RPC method bindings)<br>`crates/rpc/src/auth.rs` (authenticated writes for origin/head/batch mapping)                                                                                                                                       | `alethia-reth/crates/db/src/model.rs` (separate table definitions)<br>`alethia-reth/crates/rpc/src/eth/eth.rs` (public reads)<br>`alethia-reth/crates/rpc/src/eth/auth.rs` (authenticated writes/reads)                                                                                     |
| `WLP-INV-007` | `crates/driver/src/sync/beacon.rs` (beacon-sync catch-up flow submits blocks/forkchoice without payload attributes)                                                                                                                                                                                                                                                                                                                    | `alethia-reth/crates/rpc/src/engine/api.rs` (custom table persistence tied to payload-attributes path)                                                                                                                                                                                      |
| `WLP-INV-008` | `crates/driver/src/sync/event.rs` (event startup and readiness checks can encounter missing batch mappings/custom-table gaps)<br>`crates/driver/src/sync/confirmed_sync.rs` (readiness stays fail-closed until table-backed signals are consistent)                                                                                                                                                                                    | `alethia-reth/crates/rpc/src/eth/auth.rs` (batch-last-block fallback/uncertainty behavior)<br>`alethia-reth/crates/rpc/src/eth/error.rs` (uncertain/lookback-exceeded responses)                                                                                                            |
| `WLP-INV-009` | `crates/driver/src/sync/event.rs` (event-stream canonical processing and ingress gate progression)<br>`crates/whitelist-preconfirmation-driver/src/importer/cache_import.rs` (preconf parent/branch recovery and staged imports)<br>`crates/whitelist-preconfirmation-driver/src/importer/ingress.rs` (unsafe request/response path for ancestry recovery)                                                                             | `../protocol/contracts/layer1/preconf/iface/IPreconfWhitelist.sol` (operator-selection interface assumptions)<br>`../protocol/contracts/layer1/preconf/impl/LookaheadStore.sol` (lookahead/proposer-context assumptions)                                                                    |
| `WLP-INV-010` | `crates/driver/src/sync/event.rs` (core event/preconf orchestration assumptions)                                                                                                                                                                                                                                                                                                                                                       | `alethia-reth/crates/rpc/src/engine/api.rs` (engine-side persistence assumptions)<br>`../protocol/contracts/layer1/preconf/impl/PreconfWhitelist.sol` (whitelist proposer assumptions)<br>`../protocol/contracts/layer1/preconf/iface/ILookaheadStore.sol` (lookahead validity assumptions) |

## Notes For Agents

- Treat this file as an index, not a substitute for reading the linked code.
- For behavior changes, verify both local anchors and at least one external anchor from the same row.
- Before checking `alethia-reth` anchors, ask for the local path in the current environment.
- If any anchor becomes stale due to refactors, update this file in the same PR.
