From 05890ea6fc10a6e63d7013b541787f5a20f99766 Mon Sep 17 00:00:00 2001 From: Christophe Pettus Date: Mon, 22 Jun 2026 22:18:37 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20record=20transaction.rs=20decomposition?= =?UTF-8?q?=20status=20=E2=80=94=20StagingTxn=20extraction=20deferred=20(I?= =?UTF-8?q?141)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 2026-06-22 review's god-module SMELL was worked through four unit extractions (SlotPacker #77, FreemapRecycle #78, CommitProtocol #79, FaultInjector #76); the final StagingTxn extraction is deliberately deferred. The candidate-prepare/install staging vocabulary 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 without dragging the delicate mutation paths through a mechanical wrapper change. Recorded as future work to be done incrementally if/when those paths are touched, not re-triggered from the SMELL alone. --- ISSUES.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/ISSUES.md b/ISSUES.md index 62585b6..1d437f7 100644 --- a/ISSUES.md +++ b/ISSUES.md @@ -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.