refactor(forks): decouple subspecs from forks.lstar (Stage 3 of #686)#698
Merged
tcoratger merged 1 commit intoMay 2, 2026
Conversation
…thereum#686) Subspecs no longer hard-import any concrete fork module. They reach fork-specific types through three channels: fork-stable types in `lean_spec.types`, structural protocols in `lean_spec.forks.protocol`, and re-exports of the active fork from `lean_spec.forks`. Concrete class pointers are injected through `ForkProtocol` (`fork.state_class`, `fork.block_class`, ...) for subspecs that construct or decode SSZ instances. `AggregationBits`, `ValidatorIndices`, and `VALIDATOR_REGISTRY_LIMIT` move into `lean_spec.types`; `subspecs.chain.config` re-exports the limit so existing call sites keep working. `SQLiteDatabase` now takes `state_class`, `block_class`, and `attestation_data_class` as constructor arguments instead of hard-importing `forks.lstar` containers. A new AST-walk test (`test_subspecs_do_not_import_concrete_fork`) guards the property going forward by asserting no file under `src/lean_spec/subspecs/` imports from `lean_spec.forks.lstar.*`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
38 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Stage 3 of the multi-fork architecture refactor (#686): make
src/lean_spec/subspecs/truly fork-agnostic.After this PR, no file under
src/lean_spec/subspecs/imports fromlean_spec.forks.lstar.*. Subspecs reach fork types through three channels:lean_spec.typesfor fork-stable primitives (Slot,ValidatorIndex,Checkpoint, plus the newly movedAggregationBits,ValidatorIndices, andVALIDATOR_REGISTRY_LIMIT).lean_spec.forks.protocolfor structuralSpec*Typeprotocols (enriched with@propertyaccessors and a sharedSpecSSZTypebase forencode_bytes/decode_bytes). Used in pure-typing surfaces like theDatabaseprotocol.lean_spec.forksfor re-exports of the active fork's concrete container classes. Used where structural protocols would lose the fidelity needed for concrete forkchoice calls (e.g.Store.on_block(SignedBlock)insubspecs/sync/).SQLiteDatabasenow acceptsstate_class,block_class, andattestation_data_classvia constructor (class-pointer injection) instead of hard-importingforks.lstarcontainers.VALIDATOR_REGISTRY_LIMITmoves tolean_spec.types(its natural home — it sizesAggregationBits.LIMITandValidatorIndices.LIMIT);subspecs.chain.configre-exports it so existing call sites keep working without churn.CI guard
A new AST-walk test (
tests/lean_spec/forks/test_fork_protocol.py::test_subspecs_do_not_import_concrete_fork) asserts that no file undersrc/lean_spec/subspecs/imports fromlean_spec.forks.lstar.*. This locks in the property going forward.Stage 3 checklist
subspecs/xmss/— uses fork-stable types fromlean_spec.types.subspecs/storage/—Databaseprotocol usesSpec*Type;SQLiteDatabasetakes class pointers.subspecs/sync/— importsStore,SignedBlock, etc. fromlean_spec.forksre-exports.subspecs/chain/— uses fork-stable re-exports.subspecs/validator/— uses fork-stable re-exports.subspecs/networking/— uses fork-stable re-exports.subspecs/genesis/— uses fork-stable re-exports.subspecs/node/node.py— accesses concrete classes viaconfig.fork.*_classand thelean_spec.forksre-exports.Test plan
uvx tox -e all-checks(ruff check + format + ty + codespell + mdformat) green.uv run pytest tests/lean_spec/— 2208 unit tests pass.uv run pytest tests/lean_spec/forks/— 18 fork tests pass, including the new CI guard.🤖 Generated with Claude Code