Phase 4a: execution context — documentation and phase record

[Wahbeh-Mohammad]

Closes #14. Third of three phase 4a PRs — the documentation and the phase record for #57 and #58. Targets #58's branch. The same rebase-and-reprove note as #57 applies: CLAUDE.md, the READMEs, architecture.md and the roadmap's status notes here were written against main before 4b landed and are re-derived on the rebased tip.

What lands

15 files, +934 / −46, all Markdown.

• The checklist, docs/work/mvp/phase4/phase4a/2026-09-08-phase4a-execution-context-checklist.md, written from the build: 20 rows, CTX-1–CTX-20, every one ✅ with its task and the test that proves it (the design's disposition table defers nothing). Plus what was built, the guards run red (eighteen mutations with their messages, and the rows the two fix rounds added), the audit groups run, seventeen deviations from the plan's text (none lowers a gate), the findings routed, and the postponed work re-read (the store cap's configuration source → phase 5a Task 13; the no-op span and tracer protocols → phase 5c Tasks 3–5; nothing new postponed).
• The phase 4a design's ledger gains an "As built" addendum: P4-3 (the two private constants' sig/ mirrors), P4-8 (#tracer's five-parameter arity re-read from the gem), P4-10 (the eighth cop, not the seventh), P4-11 (the private #validate_context!), and one new row, P4-60 — _ContextHost, the self-type interface strict Steep needs for Context#close. It was numbered P4-40 while 4a and 4b ran as parallel lanes; 4b merged first with P4-40–P4-49, P4-50–P4-59 are 4c's, and the addendum, the checklist and the roadmap note say so, so no two rows share a number on main. docs/sdk-design-ruby/ §5.4, §8.1 and §10 are frozen; their addenda and the consolidation are a human's, stated in the roadmap note as 3a, 3b and 4b did.
• docs/sdk-documentation/execution-context.md — new as-built page for the correlation model (65 annotations, every fence run verbatim on 4.0.6 and 3.2.11 by the reviewer); architecture.md, quality-gates.md (the eighth cop), the core README, README.md and docs/README.md updated to point at it.
• The roadmap's execution step 5 and the phase 3, 4, 5, 6 and 8 segmentation designs — the "a phase returns to main as one phase-level pull request" sentence corrected in place, dated 2026-09-16, old wording kept visible, the way the mvp → main correction of 2026-09-14 was made: each sub-phase returns as its own code → tests → docs stack, merged bottom-up. That is what phases 1, 2, 3a, 3b and 4b actually did and what 4a, 4b and 4c are doing in parallel. Phase 8's design leans on "the phase-level PR" as a mechanism in three further sentences; those are recorded in the checklist for phase 8's execution to restate against its three stacks and are not edited here.
• CLAUDE.md — the built-phases sentence, the lib-file count (63 → 75 under lib/dexpace/), the sig/ and test/ mirror clauses (hooks.rb, bounded_map.rb and context/call_key.rb the files with no test/ mirror), the cop count where the seventh was named, and the "Constraints that will bite" list. The roadmap gains the phase 4a status note and a thirty-eighth phase-10 inbound bullet (phase 0's plan amendment still says the keyword-splat cop carries no ordinal and 4a's is the seventh; the documentation half only).

Verification

• bundle exec rake on Ruby 4.0.6 at this tip: exit 0, all seventeen gates green (1,272 / 6,889, 99.96%, YARD 0 undocumented).
• ruby .claude/skills/housekeeping/probe.rb: no drift, all eight checks — including after the renumber commit; verify_knowledge_structure.rb OK; the housekeeping and knowledge suites green.
• Empty diff under docs/product-spec/, docs/sdk-design-ruby/, docs/knowledge/ (harvested and notes — the design's two notes stand; notes/observability.md's 2026-09-13 entry quotes P4-8's two-positional recommendation where the build ships the gem's five, and is left for phase 10's plan Task 16, which already owns its next rewording), docs/deviations.md (phase 10 flips it), docs/first-release.md (the IO-38 row's CTX-7/CTX-8 sentence, added at planning, reads true of the build and is unchanged) and every earlier phase's documents beyond the dated step-5 sentences.
• The final reviewer re-derived every count CLAUDE.md and the status note state against the tree, read 22 checklist rows against their tests (all proven), re-ran the CTX-13 and CTX-19 experiments and the two thread tests, and ran every execution-context.md fence by hand on both interpreters.

Known follow-up from the review (not blocking)

• R2-1 — "Guards run red" rows 2, 3 and 8 carry the first build's failure counts (4, 6 and 3), one short of what the same mutation yields since round 1 added the real-promotion CTX-13 case (5, 7, and 3 failures plus 7 errors on 4.0.6). Refresh the three counts, or qualify them "on the first build" the way rows 19–24 date themselves.
• When this stack is rebased onto main for the merge, the two lanes' shared prose — the built-phases paragraph, the file counts, the constraints list, the status notes — is reconciled with 4b's, and the surface manifest is regenerated on the rebased tip rather than hand-merged.

[Wahbeh-Mohammad]

Review record for the phase 4a stack (#57 → #58 → #59)

Three 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; two fix rounds between them. 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 third because it approved. The stack was then rebased onto main (4b and 4c had merged first) and re-proven by the manager — that pass, with its one extra fix commit, is recorded on #57.

Round	Verdict	Blocking	Should-fix	Nits	Disposition
0	changes required	0	3	2	all 5 fixed
1	changes required	0	1	0	fixed
2 (final)	approve	0	0	1	carried into the PR bodies

No finding was ever blocking; nothing was skipped or disputed. Three of the four should-fixes were tests that did not reach far enough — a claim resting on the fake rather than a real chain, a load-time property asserted only by identity, a guard covering one carrier of three — and the reviewers found each by a mutation that survived or by reading the test against the design's own sentence. The fourth was a real argument-boundary gap in shipped code.

Round 0 → fixed in round 1

• R0-1 should-fix — CTX-13's "a promotion re-setting a key does not refresh its eviction position" was proven only through ContextStore#set on the fake; a #promote_to_exchange that called store.release(self) before store.set(ctx) survived all four context suites. Fixed on Phase 4a: execution context — tests and the fake #58: a real-chain case (cap 3, chains a/b/c promoted to request, a promoted to exchange before d arrives, survivors asserted as a key list) that goes red under the release-then-set mutation on 4.0.6 and 3.2.11 — Expected ["b", "c", "d"] Actual ["a", "c", "d"].
• R0-2 should-fix — a memoised ContextStore.default (@default ||= new, the load-time assignment deleted) survived every suite, although the design says eager assignment is what keeps CTX-17's "construction registers nothing" inert and the source comment names XCUT-11 as the reason. Fixed on Phase 4a: execution context — tests and the fake #58: a fresh-process case — Open3.capture3(RbConfig.ruby, …, 'require "dexpace"; print Dexpace::ContextStore.instance_variable_defined?(:@default)') — red under the memoised form on both interpreters.
• R0-3 should-fix — the Fiber[] boundary test's setup guard asserted the Fiber[:probe] / Thread.current[:probe] pair on the main fiber and in a child Fiber only, where the design's testing strategy names three carriers. Fixed on Phase 4a: execution context — tests and the fake #58: the guard writes both slots on the main fiber and asserts [:fiber_storage, nil] inside a child Fiber, a new ::Thread and an Enumerator's internal fiber; 8 assertions alone, no warning under -w -W:deprecated.
• R0-4 nit — dispatch_context.rbs's comment still named the plan's public Context.validate!, renamed in the build to the private #validate_context!. Reworded on Phase 4a: execution context — the context layer #57. R0-5 nit — the cop's head comment claimed the require forms tools/require_scan.rb reads, but its matcher does not see autoload :WeakRef, "weakref" (verified over a scratch adapter-gem file: no offense). Closed by narrowing the comment to the three require spellings it matches, per the design's R1 list; any later use must name WeakRef, which on_const flags.

Round 1 → fixed in round 2

• R1-1 should-fix — a pinned call_key or an operation_name was never checked to be a String: by hand against the docs tip, DispatchContext.build(bundle: NONE, call_key: :sym, store: st) succeeded with a Symbol key (st[:sym] resolving, st["sym"] nil), promote_to_request(operation_name: :GetUser) succeeded, and .build(call_key: 5) / operation_name: 7 leaked NoMethodError (Integer#empty?) rather than InvalidArgumentError — Model.frozen_string passes a frozen Symbol or Integer through untouched. Fixed on Phase 4a: execution context — the context layer #57: Context#validate_context! raises the field-named call_key must be a String between the required and empty checks, and CTX-16's two-state rule is hoisted from the two flavours' initializers into one private Context#validate_operation_name! (nil / non-String → operation_name must be a String; "" → must not be empty), declared in context.rbs; because the guard lives in initialize, it covers .build, #with and both promotions. Four cases on Phase 4a: execution context — tests and the fake #58 across context_test.rb, dispatch_context_test.rb, request_context_test.rb and exchange_context_test.rb, each asserting the exact message on :sym/5 and :GetUser/7; four mutations (each guard deleted; the helper's call removed from either flavour alone) red on 4.0.6 and 3.2.11 on exactly those cases.

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

• R2-1 nit — "Guards run red" rows 2, 3 and 8 in the checklist carry the first build's failure counts (4, 6 and 3), one short of what the same mutation yields since round 1 added the real-promotion CTX-13 case (5, 7, and 3 failures plus 7 errors on 4.0.6). Listed on Phase 4a: execution context — documentation and phase record #59.

What the final reviewer verified, in its own runs

1. Gates — Phase 4a: execution context — the context layer #57 tip d8cf132: all seventeen individually on 4.0.6, all green including the SimpleCov floor (1,154 runs / 6,094 assertions, 97.61%; the tolerated red the layering rule permits was not needed), the honest RuboCop run 240 files clean, cops:test 129 cases, steep clean over the strict core target, YARD 402 methods / 0 undocumented; the matrix set and cops:test on 3.2.11 (97.58%). Phase 4a: execution context — tests and the fake #58 tip 409d2c7: full bundle exec rake green on 4.0.6 in 245 s (1,272 runs / 6,889 assertions, 3,231 / 3,232 lines, 99.96%; test:gates 130 / 538), RuboCop 251 files clean, the matrix set on 3.2.11, 3.3.12 and 3.4.10, the core suite on seeds 1, 99991, 424242 on 4.0.6 and 8675309 on 3.2.11 at 1,255 runs every time, each of the ten suites alone under -w -W:deprecated on both interpreters (4/9/20/14/3/5/20/21/14/8 = 118 runs, 0 warnings). Phase 4a: execution context — documentation and phase record #59 tip 90199be: full rake green, probe exit 0 on all eight checks and on --only registers,citations, knowledge verifier OK.
2. Every prior finding individually — R1-1 by hand on both interpreters across .build, #with and both promotions (every path raising the field-named message; a failed promotion registering nothing) and by re-applying the four round-2 mutations; round 1 had done the same for all five round-0 findings (the two new store cases red under the re-applied mutations, the three-carrier guard read and run alone, the sig comment by grep, the cop comment by scratch files).
3. The mutation battery — 24 single-edit mutants applied by the reviewer itself, 23 caught on 4.0.6 and 3.2.11; the one survivor is the plan's documented while→if drain equivalent, and it survived exactly as the plan's "open questions, resolved" item 6 says. Across the run: 18 by the implementer, then 18, 20 and 24 by the three reviewers. The ones that matter: #release comparing == (the CTX-9 trap); the drain evicting two per insert, and deleted; #put as an overwrite; a promotion rebuilding the bundle (only assert_same catches it); the key derived from the bundle alone; one counter per flavour (caught by the strictly-increasing case the implementer strengthened after the weaker form survived its own battery); the store's Hash swapped for ObjectSpace::WeakMap (3 failures, 7 errors, the floor-specific NoMethodError on 3.2.11); Bundle#valid? ignoring the sentinels; an uppercase span id; a W3C pattern without timeout:; #release raising KeyError on an absent slot; #tracer allocating per call; the release-then-set promotion and the memoised .default (round 0's two survivors); the operation name folded into the store key; .build registering what it builds; the cop's Include narrowed to core (caught by test/gates/rubocop_config_test.rb, since CopCase structurally cannot see .rubocop.yml).
4. Concurrency — the 32-thread CTX-8 race and the 16×1,000 CTX-7 burst run individually ten times on 4.0.6 and five on 3.2.11 under timeout 120: 1 winner / 31 ContextConflictErrors each naming the key, and 16,000 entries, every run; no flake, no hang, no warning. Every synchronize block read: BoundedMap's insert-and-drain, CallKey's increment, the store's lookup and release — each a hash write or a counter, never across a callback.
5. The layer by experiment, identical on 4.0.6 and 3.2.11: CTX-19 — 1,000 contexts registered inside a method, locals dropped, three GC.starts, size 1,000 and a sampled key resolving; the same script with bounded_map.rb's Hash swapped for ObjectSpace::WeakMap — size 0, key nil, and the shipped test red on the same edit; ObjectSpace::WeakKeyMap undefined on 3.2.11 while cops:test still parses and rejects the spelling there, and the cop over a scratch adapter-gem file flags WeakKeyMap.new, WeakRef.new and ::ObjectSpace::WeakMap.new; #with re-validating on all five Data types (<name> is required on both interpreters — Data#with skips initialize on 3.2 and Model#with is what re-validates); CTX-5/6/15/16/17 by hand (two default contexts not ==; the pinned pair ==, eql?, hash-equal; three flavours from one counter with consecutive suffixes; two keys from the same equal? Bundle::NONE differing; store.size 0 after every .build, the dispatch→request promotion the registering one); CTX-13 with cap 3 through real promotions; Bundle::NONE's pair exactly OBS-26's 32 hex zeros and 16 zeros, DATADOG.invalid_trace_id "0" and its rendering 2**64 − 1, the renders?/valid_trace_id? property over 256 seeded draws, Bundle.build(**bundle.to_h) == bundle, "B" * 16 refused with span_id must be 16 lowercase hex chars (OBS-26), all five patterns carrying timeout: 1.0 with Regexp.timeout nil; NO_TRACER_FACTORY#tracer called five ways returning the same NO_TRACER with #parameters matching opentelemetry-api 1.11.0's five; the private constants absent from constants and refused qualified (and const_get reaching them, as Ruby does for phase 2's Hooks — not a finding).
6. Layering — main ⊂ d8cf132 ⊂ 409d2c7 ⊂ 90199be; ten commits, the right prefixes, no attribution lines; every file in each diff classified (30 code, 12 tests, 15 docs); sig/ mirrors lib/ 77/77 with the two private constants carrying hooks.rbs's comment; the manifest's +65 rows exactly the reviewer's own derivation from the object model (2+2+8+6+8+1+14+3+13+8), 0 removed; no 4b file touched (error.rb, hooks.rb, closeable.rb unchanged from main); empty diffs under the frozen trees, docs/deviations.md, docs/first-release.md and tools/; the only earlier-phase edits the dated step-5 sentences in the roadmap and the five segmentation designs, plus the roadmap's own status note and 38th inbound bullet.
7. Global constraints by script over the 24 new .rb — both header lines; only require_relative under core lib/; no weakref/WeakMap/WeakKeyMap/WeakRef or ObjectSpace in any gem lib/ outside comments (the seventh and eighth cops each 0 over all 87 gem lib files); every Regexp.new with timeout: and no Regexp.timeout=; no Enumerator.new; no Fiber[]/Thread.current[] write in lib/; no Closeable on a context; Dexpace::ArgumentError never defined.
8. Plan and spec coverage — the 9 tasks' files; each Scope bullet of Phase 4a: Execution Context #14 mapped; all 20 rows ✅ with the cited test read for 17 of them (all proven; CTX-13 had been partially proven in round 0 and is proven since round 1); the corpus consulted for the sample (--req CTX-9,CTX-13,CTX-16,CTX-19: 20 of 20 substantive, 0 roll-ups, 0 gaps); the ledger addendum's numbering re-derived from the tree; the findings routed as the design asks — the Data-readers finding recorded as closed by phase 0 as built and not routed, the ParameterLists count already applied by phase 0, the drain measurement already on the IO-38 row.
9. Phase record — execution-context.md's fences executed statement by statement, 65 annotations, 0 mismatches on both interpreters; CLAUDE.md counts re-derived from git ls-tree (75 lib/ files beside version.rb, 77 sig mirrors, test mirrors for all but hooks.rb, bounded_map.rb and context/call_key.rb, 8 cops, 6 checklists, 11 phase directories, 40 harvested topics, the 580-row manifest); the status note's numbers against the runs; the step-5 correction present and dated in all six documents with the old wording kept visible, saying nothing false about 4b.
10. Report discrepancies — one, explained: the fix report and round 1 claimed the tests tip's 3.2.11 matrix run at 3,189 / 3,189 (100.00%); the final reviewer's run of the same command at 409d2c7 gave 3,188 / 3,189, and 3.3.12 the same. The uncovered line is phase 2's registry.rb:253, a thread-scheduling-dependent branch main's own suite covers or not run to run — not 4a code and not a 4a test. Every other number in the fix report reproduced exactly.

Run: workflow wf_a6129983-b32, 6 agents (1 implementer, 3 reviewers, 2 fixers), 2.3M tokens, 3.8 h.