Skip to content

docs: record transaction.rs decomposition status — StagingTxn deferred (I141) #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Xof merged 1 commit into from
Jun 23, 2026
Merged

docs: record transaction.rs decomposition status — StagingTxn deferred (I141) #80

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions ISSUES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1692,3 +1692,12 @@ Suggested order for this cluster: **I108** (CI lint hole) and **I111** (radix pr
**Direction of fix:** update or delete the comment.

**Fixed (2026-06-21):** dropped the stale "PyO3 0.22 … only needs 1.63" specifics for "PyO3 has a lower MSRV of its own, but the path-dep on the root crate makes its 1.82 floor ours too" — version-agnostic, so it can't drift again.

#### I141. `transaction.rs` god-module — decomposed through the unit extractions; the final StagingTxn extraction deliberately deferred [deepdive 2026-06-22] — **P3** ⏸ DEFERRED 2026-06-22
**Where:** `src/transaction/` (the directory module split out of the former `transaction.rs`)

**Problem:** The 2026-06-22 review tagged `transaction.rs` (~2.6k prod lines) a god-module (filed DESIGN, verifier-adjusted to **SMELL**): every durability invariant (3-fsync ordering, I18 freemap window, BUG#2 atomic staging, R1 cursor accounting, watermark rollback) encoded as prose comments + cross-references rather than types/module boundaries, with test-only `Cell` flags on the production struct.

**Disposition (decomposed, then deliberately stopped):** Worked incrementally — a directory-module split by concern plus four extracted units: `SlotPacker` (R1 packing, #77), `FreemapRecycle` (structural recycle + persist/reclaim, #78), `CommitProtocol` (the 3-fsync sequence, #79), and a `#[cfg(test)] FaultInjector` (#76). All behavior-preserving (the existing suite is the oracle; FreemapRecycle additionally passed a 4-lens adversarial review). The planned final unit — `StagingTxn` (the BUG#2 atomic `allocate_inner` prepare/install) — was **deliberately NOT extracted**: the candidate-prepare/install vocabulary (`handle_table_insert_candidate`, `membership_insert_candidate`, `membership_remove_candidate`, `abort_allocate_prepare`, `inject_membership_failure`, `insert_into_data_page`) is **shared across `allocate_inner` (staging.rs) AND `update_inner`/`delete_inner` (mutate.rs)**, so a context-based extraction cannot be contained to staging.rs — it would force the most delicate mutation paths + packing.rs through a mechanical wrapper change for little cohesion gain. `staging.rs` is already a focused, holdable-in-context concern file.

**Future work (incremental only):** if/when the staging paths are touched for a real reason, fold the shared vocabulary into a `StagingTxn` unit at that point. Do NOT re-trigger a standalone extraction from the SMELL alone — the engine passes every test; on a green, pre-production engine a below-bug structural finding is the lowest-value, highest-risk change (this whole decomposition was a large undertaking driven by one SMELL). The remaining `transaction.rs` SMELL items below the extraction (the test-only flags) are already addressed by the `FaultInjector` split.
Loading