Phase 5a: configuration and the clock — the configuration layer

[Wahbeh-Mohammad]

Part of #18. First PR of the nine-PR phase-5 stack — phase 5a's code. Its tests are the next PR up and the phase record the one after; phase 5c's three PRs (#20) sit on 5a's docs tip and phase 5b's three (#19) on 5c's.

Base note. This stack was cut from main at 993c439 (phase 4 complete). Phase 5a and phase 5c were built in parallel off that commit and each was approved by independent review; 5c's stack was then rebased onto 5a's docs tip and reconciled (the entry file's two phase-5 blocks in sub-phase order, the manifest regenerated on the combined tree, CLAUDE.md/READMEs/roadmap counts re-derived), and 5b was built on the combined tip. Merge bottom-up; each docs PR is the tip at which that sub-phase's documentation is consistent.

What lands

The configuration layer and the clock in dexpace-core — 51 files, +2,552 / −77: the four-tier configuration chain every later limit reads from, the injectable time seam every later wait routes through, the environment-driven proxy model, and §16.6's five free-standing utilities. All thirty-eight CFG IDs. The only plain requires added are time and uri (both allowlisted; rbconfig avoided, so the require allowlist does not grow); the gemspec keeps zero add_dependency lines; the only blocking primitive anywhere is ::Thread::Queue#pop(timeout:) at three sites; every Regexp is built with timeout:.

• Dexpace::Configuration with ::Builder, ::Keys (seven CFG-14 names, including the retry-attempt cap RETRY-12 reads) and ::Sources (ENVIRONMENT, NONE, .from_hash) — four tiers with a substituted third source (design §10.16): call-site override → ENV → configure defaults → caller default, preserved even where it inverts Ruby convention because CFG-1 is normative. The CFG-3 normalised accessor and the CFG-4 raw exact-name accessor stay distinct; CFG-2's emptiness is the environment tier's alone (a chain-wide reading was a guard run red); the parsers (CFG-5–CFG-7, three duration grammars, a bare number as milliseconds) and the deep-value comparison (CFG-33/CFG-34: NaN folds equal, signed zeros unequal with a matching hash, cycle-safe; the container clause inapplicable per §11.15) are private_constants asserted at their call sites. Builder.new validates every seed and both seams through the setters' own guards (from the review).
• Dexpace.configure / .configuration / .reset_config! (CFG-8, CFG-13) — one frozen reference swapped under a ::Thread::Mutex, read lock-free; the builder and the block run outside the lock.
• Dexpace::Clock and Clock::SYSTEM (CFG-15–CFG-17) — #now, #monotonic, #sleep(duration, cancellation:) as a per-call Queue#pop(timeout:) woken by the token's on_cancel push, the token re-checked after the wake (CFG-17's re-assertion is the token's own state), never Kernel#sleep (design §10.17). Dexpace::Async.delay (CFG-18) — scheduler-conditional: unmounts the fiber under a registered Fiber.scheduler, and raises SeamError without one rather than claiming not to block a thread while blocking one (P5-9; settles with true, P5-52).
• The pivot's deadline: keyword, picked up from phase 2 — Future#value/#wait and Completer#await gain deadline: and clock: (the positional cancellation kept; NFR-4 widening only): a timed gate pop inside Completer#await ending in phase 2's own request_cancel(:deadline_expired), never a raise from #await and never Cancellation.any composition; validation runs before the settled short-circuit (from the review).
• Dexpace::Proxy, ::Type (a closed set in Pipeline::Stage's shape — .of the only lookup, #with refuses), ::HostPattern (CFG-23: \A…\z, escaped, IGNORECASE, compiled once at construction) and the private_constant ProxyResolution behind Proxy.resolve (CFG-24–CFG-28): never raises — every malformed input yields nil plus one Kernel#warn (phase 2's P2-6 precedent; 5b adds an event beside each), an out-of-range port likewise, NO_PROXY/http.nonProxyHosts with CFG-26's escaped separators, a blank HTTPS_PROXY from any tier no longer masking HTTP_PROXY (from the review). Proxy#to_s/#inspect mask both credentials — CFG-22's "never emit username/password in cleartext" (review round 0's should-fix; the plan's fence printed the username).
• §16.6's utilities — Dexpace::HTTPDate (CFG-29: Time#httpdate formats; CFG-30/CFG-31: an owned anchored grammar accepting GMT/UTC/+0000/+00:00, tolerating a wrong weekday, refusing blank input and a missing comma, and refusing what Time.utc would silently normalise — 31 Nov, 29 Feb 1995, hour 24, second 60 — P5-54; Time.parse stays cop-banned); Dexpace::UUID (CFG-32: v4 from a per-thread ::Random in Thread.current[], never SecureRandom — XCUT-21's path stays separate); Dexpace::Retryability.retryable_status? (CFG-35's status half as XCUT-5's single shared classifier — 408, 429, 5xx except 501/505; the throwable half is phase 6a Task 3's and no stub for it exists); Dexpace::BuildInfo (CFG-36: every token non-blank, RUBY_ENGINE/RUBY_ENGINE_VERSION/RUBY_PLATFORM, no rbconfig, loads under --disable-gems).
• The two wirings earlier phases postponed here, each a decision recorded rather than a silent edit: ContextStore.default is built on its first call under one ::Thread::Mutex with the cap read from the chain (Keys::MAX_TRACKED_CONTEXTS, non-positive → MAX_TRACKED_CONTEXTS), the chain read outside the lock and a lock-free fast path in front, so no caller seam runs under the mutex and a promotion after the first takes no lock — phase 4a's load-time assignment and its fresh-process test are replaced on this branch (option (b), P5-55; an unsynchronised ||= gives sixteen stores to sixteen first callers, a guard run red on both interpreters). Dexpace::IO.max_materialized_bytes(configuration = Dexpace.configuration) is read per call by the five value-readers of MAX_MATERIALIZED_BYTES (TypedReads#guard_materialization!, Body.clamp_cap, StreamBody#replayable?, BufferBody#==), so Dexpace.configure governs the live ceiling and a refusal names the limit that applied; the constant stays the default and no ceiling: keyword exists anywhere (option B, P5-56 — a "configurable" ceiling no reader consults is not configurable).
• sig/ mirrors lib/ one file per file — seventeen new mirrors, the three private_constants carrying hooks.rbs's comment (P5-57); _Clock, _ConfigSource and _RetryableStatus declared; sig/dexpace.rbs unchanged. The surface manifest regenerated once (730 → 814, all 84 rows read against the object model; no row for a private constant or helper). Three gate-read test files ride here because the code change invalidates them: phase 4a's context_store_test.rb fresh-process case, phase 2's seam_surface_test.rb stdlib-feature count (three → four, time), and the smoke suite's constant list.

Decisions taken in the open, against the plan's text

Ledger rows P5-51–P5-58 and the checklist's "Deviations from the plan" (26 items) itemise them: Configuration::Builder in its own file (P5-51); Async.delay settling with true (P5-52); HostPattern a one-member Data with the compiled pattern an ivar (P5-53); HTTPDate's component round-trip (P5-54); the context-store cap's construction shape (P5-55); the ceiling readers moved (P5-56); the private constants' sig/ mirrors and three private helper modules (P5-57); the doubles renamed and top-level (P5-58 — the plan's FakeSource and ProbeScheduler collide with phase 3a's and phase 2's files). Proxy::Type takes P4-56's closed-set shape rather than phase 1's Status shape.

Layering

Each tip of the stack is green under every gate on its own tree. This branch is green on the SimpleCov floor too — 93.45% on 4.0.6 (93.42% on 3.2.11; 1,553 runs, 0 failures). The tests PR takes the same tree to 99.97%.

Verification

• Independent reviewer, one fix round: nine round-0 findings (1 blocking, 1 should-fix, 7 nits), each verified resolved individually on re-review with its own reproduction and a regression mutation, then a full second pass — approve, 0 blocking / 0 should_fix / 2 nits.
• Mutations. 36 run red by the implementer (seven on 3.2.11 too) and 47 / 53 applied by the two reviewers themselves, every one caught (the pop-without-timeout mutant hangs by construction and was killed): the tier order swapped; normalisation dropped; downcase(:turkic) (the cop); a bare number as seconds; the builder aliasing the caller's hash; the slot assigned outside the mutex; the wait as Kernel.sleep; the token not re-asserted; #monotonic via Time.now; the deadline raising a bare CancelledError; CFG-19 re-raising a copy; the glob unanchored, unescaped, case-sensitive; the resolver raising on garbage; port 65536 accepted; the escape lookbehind dropped; the zone group reduced to GMT; blank input answered with the epoch; SecureRandom.uuid; the version and variant nibbles wrong; NaN by == with two distinct objects; 0.0 == -0.0; NaN hashed unfolded; 501 retryable; 408 not; a blank BuildInfo token; a bare ArgumentError from a guard; an unsynchronised ||= on the store; a Regexp without timeout:; a ceiling reader back on the constant; chain-wide emptiness.
• By experiment on both interpreters: the four tiers removed one at a time; Clock::SYSTEM.sleep(5, cancellation:) cancelled from another thread returning in 0.050 s; the bounded wait over an unsettled Completer with a FakeClock and with the real one; Async.delay under the parking scheduler (#block fires, #kernel_sleep never); the proxy resolver over hand-built sources with exactly one warning per malformed input; all four zone tokens parsing to one instant; 10,000 distinct v4 UUIDs, 8 threads × 1,000, three distinct Random objects across a fiber and a thread; DeepValue through module Dexpace (NaN pair equal and hash-equal, [1] != [1.0], a cycle returning); BuildInfo loading under --disable-gems on all four Rubies; 16 threads configuring and reading with no torn observation; proxy/type and configuration/keys loaded first raising superclass mismatch, as the plan says.

Known follow-ups from the review (not blocking)

• R1-2 — every Dexpace.configure { |c| c.property(...) } over the live slot wraps the inherited property seam in one more closure, so repeated reconfiguration without a reset_config! grows the lookup chain without bound (measured 1157× on raw_property("missing") after 2,000 configures, every earlier table retained). Fix shape: flatten @properties over an inherited table the builder itself made into one Sources.from_hash table, composing only over a caller-installed seam. Code branch. Worth fixing before phase 6 reads the chain in a hot path.
• R1-1 — one BuilderContractTest assertion reads the host's K through the default env seam (Builder.new(property_source: nil)); the case is about property_source: nil, so pass env_source: Sources::NONE. Tests branch.
• Phase 3a's and 3b's own materialisation suites read the ceiling through the slot with no fake seam and would fail on a host exporting MAX_MATERIALIZED_BYTES — stated in io_ceiling_test.rb's header and the IO-9 row rather than fixed, because those suites are their phases'; a phase-10 inbound candidate.
• A standalone require "dexpace/io/buffer" or "dexpace/context_store" now fails on Dexpace.configuration where it loaded on main — the same call-time pattern main already has elsewhere (body.rb → BytesBody, completer.rb → Future); the entry file is the load path.
• The design's §8.2/§8.3/§10.16/§10.17 addenda and the consolidation of P5-1–P5-15 and P5-51–P5-58 into design §10 are a human's (frozen chapters); no frozen sentence is contradicted.