Phase 5b: logging facade and redaction — documentation and phase record

[Wahbeh-Mohammad]

Closes #19. Ninth and last PR of the phase-5 stack — the documentation and the phase record for phase 5b's two PRs below it. Targets the tests PR's branch. Its CLAUDE.md, READMEs, architecture.md and roadmap text are written on top of the reconciled 5a + 5c tip, so this is the tip at which the whole phase-5 stack's documentation is consistent; merging bottom-up lands it last.

What lands

13 files, +1,872 / −69, all Markdown.

• The checklist, docs/work/mvp/phase5/phase5b/2026-09-09-phase5b-logging-and-redaction-checklist.md, written from the build: 28 own rows — 26 ✅, each naming its task and the test that proves it, with OBS-24 and OBS-10 stating the Ruby 3.2 floor's behaviour in the row (5c's P5-72, applied as P5-97); OBS-19 ⏳ to phase 8c Tasks 7, 9 and 15 (the header-drop policy's subject is a transport that drops; P5-32); OBS-37 ⏳ post-v1 with the async adapters (docs/first-release.md's OBS-32/OBS-37 entry). Plus fourteen cross-reference rows (XCUT-19's five clauses, XCUT-20, XCUT-11, CFG-24/CFG-25, CFG-21, CFG-14, CFG-16, SEAM-25 event shape only, BODY-19/BODY-22/BODY-34, BODY-20, OBS-23, PIPE-28, NFR-11) the way 4b, 4c, 5a and 5c carried theirs; what was built; the guards run red (48 mutations plus each review round's repair mutations, both interpreters); the audit groups run; thirty-one deviations from the plan's text (none lowers a gate); the findings routed; the postponed work; and one paragraph per review round recording its repair (the shape 5a's record used).
• The phase 5b design's ledger gains an "As built" addendum, P5-91–P5-109: the split-reassembly redactor that never calls URI#to_s; Instrumentation.diagnostic; the async step's scope and settlement shape; one redactor per logging path; Keys::MESSAGE; the floor's compaction and restore; the top-level doubles; the step's span naming; then the four review rounds' rows — userinfo on every header route, unmatchable bad names and opaque queries, the structural header-name gate, the proxy URL shown through the redactor, the reserved-key table over all three OBS-5 sources, leading OWS, the UTF-8 fallback for a charset with no converter, every //-authority scrubbed per run, per-value header redaction, the async settlement on the source future. Numbering follows the phase-5 blocks fixed at dispatch. docs/sdk-design-ruby/ §8.1 and §10 are frozen; the consolidation of P5-16–P5-39 and P5-91–P5-109 and the addenda are a human's, stated in the roadmap note as every phase has. No frozen sentence is contradicted, so no C15.
• docs/sdk-documentation/logging-and-redaction.md — new as-built page, sixteen fences run top to bottom as one script on 4.0.6 and 3.2.11 (122 checks, 0 fails, no credential in any printed result); architecture.md, the core README, README.md and docs/README.md updated to point at it. Three earlier as-built pages had described this layer as unbuilt and are corrected in place: tracing-and-metrics.md ("no pipeline step exists yet"), configuration.md (seven keys; "waits for that layer"), body.md ("nothing in core constructs either").
• docs/first-release.md — one line corrected: the CTX-16 entry said the step "probes request.respond_to?(:context)"; as built the step probes nothing and names its span by the method token (P5-99). Nothing else in the file changes.
• CLAUDE.md — the built-phases sentence now "Phases 0, 1, 2, 3a, 3b, 4a, 4b, 4c, 5a, 5b and 5c are built", the opening paragraph gains the logging layer, the lib-file count (126 → 141 under lib/dexpace/), the test-mirror exceptions (nine → eleven: instrumentation/render.rb, instrumentation/emitter.rb), the checklist count (eleven), and four lines in "Constraints that will bite" (redaction runs at #field and never at the sink; the sink is a duck type and core never requires logger; the emit-once latch releases its mutex before the sink call; a log-emission site is contained and a tracer or meter call never is). The roadmap gains the phase-5b status note after 5c's, naming what phases 2, 3b and 4 postponed here that landed (close_quietly's second route — the phase-2 comment asserting the drop is what changed; Hooks.notify's diagnostic; the body-logging caps' two wirings completing the item 5a half-supplied; P5-8 discharged), what it half-supplies (SEAM-25's shape only), the four review rounds, and three new inbound bullets for phase 10 (the design's stale verified facts 6 and 13; the unused-block warning the one-process gate cannot see; the four 3b/4b ceiling-reading tests).

Verification

• bundle exec rake on Ruby 4.0.6 at this tip: exit 0, all seventeen gates green (2,050 / 58,450, 99.98%, YARD 0 undocumented), honest RuboCop 401 files clean.
• ruby .claude/skills/housekeeping/probe.rb: no drift, all eight checks; verify_knowledge_structure.rb OK; the housekeeping and knowledge suites green.
• Empty diff under docs/product-spec/, docs/sdk-design-ruby/, docs/knowledge/, docs/deviations.md, every earlier phase's documents, the phase-5 charter, and 5a's and 5c's documents.
• The final reviewer re-derived every count CLAUDE.md and the status note state against the tree (141 lib files beside version.rb, 141 sig mirrors, eleven test-mirror exceptions, eleven checklists — the probe does not read the spelled-out lib count, so it was counted), read 28 checklist rows against their tests (26 proven; CFG-24/CFG-25 and CFG-16 partially — R3-1 and R3-2), confirmed the phase-8c tasks and the first-release.md entries exist where cited, and ran every page fence by hand on both interpreters.

Known follow-ups from the final review (not blocking)

• The CFG-24/CFG-25 row's "the credential in neither channel" and P5-103's "the proxy URL through the redactor and never raw" hold for 30 of 38 spellings; R3-1's eight parsed-path spellings (on the code PR) need a ledger row beside P5-103/P5-107 and those two sentences re-scoped once the belt is per-run. R3-2's repair needs P5-109 and the AsyncStep class comment's "the order the sync path emits" paragraph updated — true of the log event, not yet of the instruments at BODY.
• The roadmap note and this checklist record the review rounds as of round 2's repair; the round-3 findings are carried here and on the two PRs below, not in the record.
• The as-built page uses a hand-rolled ArraySink and CountingMeter rather than the suite's doubles, so a reader needs nothing from test/support/.

[Wahbeh-Mohammad]

Review record for the phase 5b stack (#69 → #70 → #71)

Four independent reviews, each by a fresh agent with no memory of the previous one, each re-running the gates itself on every tip and both interpreters, with a fix round by a fresh agent between each. The stack was cut from phase 5c's docs tip 032986b — itself rebased onto phase 5a's docs tip d5df0ca by a reconciliation agent at the start of the same run — and both bases were pinned and confirmed unchanged by every agent at start and finish. Every finding got a stable id, a severity, a file:line and the command output that was its evidence. approve required zero blocking and zero should-fix; the run was capped at four reviews and stopped at the fourth with its verdict still changes_requested, so the round-3 findings are carried into the PR bodies rather than fixed by the run.

Round	Verdict	Blocking	Should-fix	Nits	Disposition
0	changes required	3	1	4	all 8 fixed
1	changes required	1	5	1	all 7 fixed
2	changes required	1	3	0	all 4 fixed (one dispute accepted for a sub-class)
3 (final)	changes required	1	1	2	carried into the PR bodies

Nothing was skipped. The pattern across the four rounds is the point of the record: each round's blocking finding was a new layer of the redaction surface reached by the reviewer's own hostile inputs rather than by a mutation — a Location header's userinfo on the relative route (R0-3), the proxy warning's message field (R1-1), a non-whitespace prefix before the scheme (R2-1), the resolver's anchored belt (R3-1) — and each fix closed its class, after which the next reviewer found the next channel.

Round 0 → fixed in round 1

• R0-1 blocking — logging_matrix_facts_test.rb's fact-3 case was order-dependent on the 3.2 floor (an earlier teardown's nil residue) and failed the 3.2.11 matrix row at the tests tip. Fixed on tests (f460c03): the case states each row's expected map, the same whether or not residue is present.
• R0-2 blocking — the code tip was red under the honest RuboCop run (one 102-column line in the minimal diagnostics_test.rb repair). Fixed on code (6859bd4).
• R0-3 blocking — OBS-11: Redactor#header_value('Location', '//user:secret@h/x') and 'http://user:secret@h/p x' returned the userinfo verbatim on the relative, surgery and sentinel-fallback routes, reaching the sink through the step at HEADERS. Fixed on code: the relative route rebuilds a network-path reference's authority with the placeholder; the surgery route substitutes the userinfo through an anchored per-pattern-timeout Regexp before cutting; the sentinel fallback runs that surgery (P5-100).
• R0-4 should-fix — OBS-18's header-name gate lived only in the private Emitter, so event.field('http.request.header.authorization', 'Bearer SECRET') logged the value, and the as-built page showed it. Fixed on code: the gate is structural at Event#field by the reserved prefix (P5-102).
• R0-5 nit — the as-built page's fence 8 results were false when the fences ran top to bottom (fence 5 left span.id in Fiber storage). Fixed on docs. R0-6 nit — the roadmap note's departure count. Fixed. R0-7 nit — a bad percent-encoding in a parameter name sentinelled the whole URL. Fixed on code (unmatchable name, value ***; P5-101). R0-8 nit — an opaque URI's query tail round-tripped unredacted. Fixed (P5-101).

Round 1 → fixed in round 2

• R1-1 blocking — every malformed-proxy-URL path interpolated the raw URL into the warning text, and 5b's new http.instrumentation.config diagnostic carried it under Keys::MESSAGE, not a reserved key — HTTPS_PROXY=http://user:secret@proxy.corp wrote the credential into both channels. Fixed on code (5fd11af): the URL shown through Redactor::DEFAULT#header_value plus CFG-24's grammar belt, and the parser's message that repeated the value no longer quoted (P5-103).
• R1-2 should-fix — reserved keys supplied through the logger's global context or the diagnostic fold bypassed the redactor. Fixed: the private ReservedKeys table applied to all three of OBS-5's sources (P5-104).
• R1-3 should-fix — a leading space, tab or control before the scheme defeated the anchored surgery pattern. Fixed: a leading run of SP/HTAB/C0/DEL tolerated (P5-105).
• R1-4 should-fix — Preview.render raised Encoding::ConverterNotFoundError for charset=utf-7, and the step's response event was lost to a diagnostic. Fixed: an EncodingError falls back to a UTF-8 decode with replacements (P5-106).
• R1-5, R1-6 should-fix — two surviving mutations: the async failure event's OBS-24 bridge across a settling thread, and BODY-35's −1 declared-size filter. Fixed on tests with a case each.
• R1-7 nit — P5-100 named only one non-authority spelling. Fixed on docs.

Round 2 → fixed in round 3

• R2-1 blocking — any non-whitespace prefix before scheme://user:secret@host defeated the surgery pattern: a quoted HTTPS_PROXY wrote the client's own credential into the sink, and a bracketed Location reached it through the step. Fixed on code (fc93a29): the pattern is the unanchored //[^/?#]*@ applied with gsub, so every //-authority's userinfo is scrubbed wherever it sits in a parser-rejected value — <…>, quotes, parentheses, %20, +, @, NBSP, U+2028, obs-text, a doubled URL — linear to 1 MiB (P5-107). Dispute accepted for one sub-class: a value the parser accepts with credential-shaped text in its path (http:///user:pw@h/p, /http://…, a valid URI whose path spells a second authority) stays verbatim on the Location route, because OBS-14 forbids altering a path and RFC 3986 gives those no authority — documented and asserted.
• R2-2 should-fix — a multi-valued Location was joined with ", " before redaction, so only the first value's userinfo was scrubbed. Fixed: per-value redaction before the join (P5-108).
• R2-3 should-fix — on the async path a throwing meter was silently swallowed at BODY with a later settlement, and on an already-settled future the span was finished and the counter added twice. Fixed: the settlement work registered on the source future at every level, outside Future#then's rescue; add and finish exactly once in all six level/settlement combinations.
• R2-4 should-fix — the OBS-1 zero-allocation assertion was flaky on 3.2.11 with a negative once-per-process delta. Fixed on tests: 5c's shared AllocationDelta helper now reports the figure two consecutive measurements agree on (0/60 after; a deviation recorded, 5c's suites re-run green).

Round 3 (final) — open, carried into the PR bodies

• R3-1 blocking — proxy/resolution.rb:178: the resolver's belt CREDENTIAL_BEFORE_AT = \A[^/?#]*@ is anchored at the start of the shown value, so a proxy URL the parser accepts with the credential in its path — http:/user:secret@proxy.corp:3128 (a single-slash typo), http:///…, /http://…, //@…, socks5:/…, http:/ /…, http:/\… — 8 of 38 spellings, writes the operator's password into Kernel#warn and the http.instrumentation.config sink record on 4.0.6 and 3.2.11. The other 30 show ***:***@ or resolve. The reviewer prototyped a per-run gsub belt and reverted it: all 38 spellings clean with both owning suites green. R1-1's class through the one channel the two repairs did not reach; a proxy URL has no path worth preserving in a warning. Listed on the code PR; to be fixed there before merge.
• R3-2 should-fix — async_step.rb:107: at BODY the derived future is fulfilled before the step's finish (then registered before on_settle), so a caller's 2 s continuation lands in http.request.duration and the span (2,000 ms at BODY; 0 ms at HEADERS and on the sync path). Fix: register the settlement on the source before deriving. Listed on the code PR.
• R3-3 nit — the OBS-8 race test catches an unsynchronised latch probabilistically on 3.2.11 (4 of 5 re-runs). Listed on the tests PR.
• R3-4 nit — the Redactor's YARD never says where it is applied. Listed on the code PR.

What the final reviewer verified, in its own runs

1. Gates — code tip fc93a29: all seventeen individually on 4.0.6, all green including the SimpleCov floor (1,849 runs, 94.81%), honest RuboCop 385 files clean; the matrix set on 3.2.11 (94.83%). Tests tip 36952b4: full bundle exec rake green on 4.0.6 (2,050 runs / 58,450 assertions, 99.98%), RuboCop 401 files clean, three seeds identical, the matrix set on 3.2.11 and 3.4.10, the OBS-1 assertion 0/30 whole-file and 0/30 alone on the floor. Docs tip d98191e: full rake green, probe and knowledge verifiers clean, all sixteen page fences run as one script on both interpreters (122 checks, 0 fails, no credential in any result). The only non-pass in any round was the hostile-environment run's four pre-existing 3b/4b tests that read the live materialisation ceiling (phase 10 inbound bullet 42), unchanged across all four rounds and no 5b suite among them.
2. Every prior finding individually — R2-1 through 17 prefixed Location spellings via the redactor and via a real pipeline at HEADERS, and a quoted/bracketed/doubled HTTPS_PROXY through the resolver, with M35–M37 red on both interpreters; R2-2 with M38/M39; R2-3 in all six level/settlement combinations with M40/M41/M56; R2-4 by 0/30 + 0/30 + 0/5 at the reviewer's seed with the helper still catching M02.
3. The mutation battery — 56 single-edit mutants applied by the reviewer (47, 53 and 56 in the earlier rounds), every one caught, ten on 3.2.11 as well; M07 (the latch flip without the mutex) probabilistically on the floor (R3-3).
4. The redaction battery by hand, both interpreters — 65 inputs through Redactor#url, 78 through #header_value, 25 hostile Location values through a real pipeline at HEADERS, 38 HTTPS_PROXY spellings through Proxy.resolve with Kernel#warn captured (the 8 leaks of R3-1); linearity of the surgery pattern on six adversarial shapes at 10 KiB, 100 KiB and 1 MiB.
5. The layer by experiment — OBS-1 as identity and a 0.0 delta; OBS-6/OBS-7; OBS-8 with 16 threads and a re-entrant sink under a 10 s join; OBS-10/OBS-24 floor-aware; OBS-20 through a real pipeline (a raising sink → the transport's response and two http.instrumentation.log diagnostics; raising #info and #warn → the response, nothing emitted); the HEADERS payload, NONE, BODY with the cap from configuration, iso-8859-1 and octet-stream bodies; OBS-35; the four wirings; the step and the async step through real pipelines; 5c's independence subprocess (1 run, 0 failures) and diagnostics.rb alone defining only Diagnostics; the # Phase 5b: block moved above 5c's by hand.
6. Layering — main ⊂ d5df0ca ⊂ 032986b ⊂ fc93a29 ⊂ 36952b4 ⊂ d98191e, all three bases unchanged; fifteen single-parent commits, subjects 45–68 characters, no attribution lines; every file in its layer (the code branch's test/ changes exactly the six pins a code change invalidated plus the manifest at 956 rows, 16 Keys and 8 Events rows equal to the constant counts, no row for Render, Emitter, ReservedKeys or CollisionLatch); the only earlier-phase lib files changed are Task 14's and Task 6's set, each a widening; sig/ 141 == 141; empty diffs under the frozen trees, docs/deviations.md, every earlier phase's documents, the charter, 5a's and 5c's.
7. Report discrepancies — the fixer's "closed for its class" claim for R2-1, P5-103 and the CFG-24/CFG-25 row are false for the eight parsed-path proxy spellings (R3-1); the fixer's "the order the sync path emits" claim for P5-109 is true of the log event and not of the instruments at BODY (R3-2); assertion counts off by the registry-claim race branch; fence check counts differ by extractor.

Run: workflow wf_5509525a-dfc, 9 agents (1 reconciler, 1 implementer, 4 reviewers, 3 fixers), 4.3M tokens, 9.2 h.