F22.4 — Commons with explicit side effects
| State | Closed |
| Parent | E22 |
| Iteration | Release 9 |
| Start Date | 2026-11-14 |
| Closed Date | 2026-11-16 |
| Predecessors | F22.3 |
Stories: 5 Closed
| Story | State | Depends on |
|---|---|---|
| S22.4.1 — Protect logging composition | Closed (2026-11-14) | S22.4.5 |
| S22.4.2 — Report actual generation effects | Closed (2026-11-14) | — |
| S22.4.3 — Split only distinct responsibilities | Closed (2026-11-16) | S22.4.1 |
| S22.4.4 — Remove measured allocation and algorithm costs | Closed (2026-11-15) | S22.3.2 |
| S22.4.5 — Decide how brace records compose with other factories | Closed (2026-11-14) | — |
Simplify logging and generation around accurate contracts and a single owner for process-wide configuration.
Context
logging/logger.py has 1,138 lines. _register_levels_and_class replaces the
process LogRecord factory when it differs from BraceLogRecord; logger
acquisition calls this registration. generation/artifacts.py:250-252 reports
every change path as written, irrespective of action. fs/hashing.py:25 reads
complete files; task duplicate detection uses repeated list.count calls
(runtime/tasks.py:260-263), and deep merge recopies override subtrees
(lang/collections.py:430-438). These prove avoidable work, not user-visible
bottlenecks.
S22.4.1 — Protect logging composition
State: Closed (2026-11-14) · Depends on: S22.4.5
Separate one-time explicit configuration from ordinary retrieval, and compose brace records with other factories as S22.4.5 decided.
Acceptance:
- Per ADR-0016: a custom record factory, installed
before or after
initializeor any retrieval, survives, and its fields reachAppLoggerrecords.AppLoggerbrace messages format with or withoutinitialize. - Brace formatting, redaction, exception logging, caller attribution and concurrent retrieval retain behavioral tests; disabled levels do not inspect frames or format values unnecessarily.
- Record disabled/enabled-call and cold-import costs before and after; named application calls retain their actual source location rather than forwarding-wrapper locations.
Outcome: for 10,000 records, disabled calls fell from 6.3 to 1.0 ms and enabled calls from 0.58 to 0.22 s, with peak memory unchanged (about 0.88 MB); cold import fell from 152 to 118 ms.
S22.4.2 — Report actual generation effects
State: Closed (2026-11-14)
Make ApplyResult.written match its documented byte-change semantics. Define
deletion, dry-run, state-only forget and multiple-block behavior explicitly
before changing reporting.
Acceptance:
- Mixed CREATE/UPDATE/UNCHANGED/SKIP/FORGET/REMOVE and dry-run plans produce documented results, with unique paths where bytes changed.
- Atomic apply, CRLF preservation, drift detection, managed-block replacement and rollback failure cases retain coverage.
- Classification/reporting has one owner; reporting fixes do not cause new filesystem writes.
writtenfollowsPlan.writes: CREATE, INSERT, UPDATE, DELETE, REMOVE and approved DRIFT/CONFLICT/MISSING are listed. UNCHANGED, SKIP and FORGET are not. Each path is listed once, at its first plan position, and a dry run reports(). The action table is in the commons generation guide.
Outcome: an all-UNCHANGED apply still touches the state lock and writes a state backup. That is state-store behaviour this story left alone.
S22.4.3 — Split only distinct responsibilities
State: Closed (2026-11-16) · Depends on: S22.4.1
Separate logging record/configuration mechanics from convenience methods if it reduces coupling. Review collection/dataclass/document helpers against already adopted libraries; keep intentional contract wrappers.
Acceptance:
- Every moved responsibility has one implementation and the curated public API remains supported.
- The change lists removed duplicate logic and shows equivalent contract cases; no new dependency or new package is required.
- Optional template/Markdown/generation imports remain outside the base facade.
Settled contract: logging/logger.py stays one module; its mechanics never
reference AppLogger, so the dependency is already one-way and a split would
move documented classes for size alone. The dacite, asdict, tomlkit and
ruamel wrappers stay as contracts.
Outcome: JSON document text and dotted key-path joining each have one
private implementation (_json_document, _join_key_path), guarded by
exact-output tests.
S22.4.4 — Remove measured allocation and algorithm costs
State: Closed (2026-11-15) · Depends on: S22.3.2
Use standard-library streaming hashing for file digests. Measure duplicate detection and deep merge before replacing repeated scans/copies with one-pass or copy-on-assignment logic.
Acceptance:
- Empty, small and multi-chunk files have identical digests and preserve the missing-file contract; large-file peak memory no longer includes a complete archive copy.
- Task duplicate rejection preserves ordering/error behavior and configuration merges preserve mutation isolation, deletion and override semantics.
- Record time/memory at increasing input sizes; no new library or broad utility rewrite is required.
Outcome: ContentHash.of_file streams through hashlib.file_digest (traced
peak about 0.4 MB at 8–256 MiB, was the file size); duplicate names are counted
in one pass (16,000 names 1.73 → 0.28 s); DictUtils.merge copies only on
assignment (equal 65,536-leaf tree 0.58 → 0.07 s). Figures are in
Performance baselines.
S22.4.5 — Decide how brace records compose with other factories
State: Closed (2026-11-14)
Reproduce logger acquisition overwriting a consumer-installed record factory. Compare composing over the installed factory, an explicit opt-in install and a formatter-level brace style, against tracing and consumer factories.
Acceptance:
- A failing test reproduces the overwrite.
- An ADR records the chosen composition, when it is installed, and the rejected options.
Outcome: ADR-0016 (owner, 2026-11-14):
AppLogger brace-formats its own records over whatever factory is installed,
and nothing replaces the process factory. Reproductions are in
tests/logging/test_logger.py, marked strict xfail.
Acceptance
- S22.4.1: A custom record factory survives retrieval and initialization, and
AppLoggerbrace messages format with or withoutinitialize(ADR-0016). - S22.4.2: Mixed CREATE/UPDATE/UNCHANGED/SKIP/FORGET/REMOVE and dry-run plans produce documented results, with unique paths where bytes changed.
- S22.4.4: Hash, task and merge contracts pass with measured operation/allocation comparisons.
- S22.4.3: Every moved responsibility has one implementation and the curated public API remains supported.
- S22.4.5: An ADR records how brace records compose with other factories.