Skip to content

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 initialize or any retrieval, survives, and its fields reach AppLogger records. AppLogger brace messages format with or without initialize.
  • 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.
  • written follows Plan.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 AppLogger brace messages format with or without initialize (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.