Skip to content

docs(roadmap): consolidate B-series findings (B4, B6, B7, B8 + harness)#234

Merged
davydog187 merged 1 commit into
mainfrom
docs/b-series-consolidation
May 22, 2026
Merged

docs(roadmap): consolidate B-series findings (B4, B6, B7, B8 + harness)#234
davydog187 merged 1 commit into
mainfrom
docs/b-series-consolidation

Conversation

@davydog187
Copy link
Copy Markdown
Contributor

Consolidate B-series perf findings in ROADMAP.md

Pulls the lessons from the B4–B8 sweep up out of the ephemeral plan files into the strategic narrative, so they survive plan cleanup and are visible to anyone evaluating future perf work.

What changes

Status section: 1,420 → 1,705 tests, 5/29 → 6/29 suite files, date.

Done section: adds the three perf-related landings since the previous update:

Direction B section: completely rewritten. The previous bullets (B1/B2/B3) were ideas from before the B4–B8 plan files were scoped; they were never used as actual plan ids. The new structure:

  • Shipped: B8, bench harness.
  • Tried and deferred (with findings): B6 (hypothesis obsolete after perf(vm): fast-path the executor dispatch loop #223), B7 (tuple-copy crossover at scale), B4 (case-on-tuple-elem doesn't beat list-cons head-match on the BEAM).
  • What we learned: 4 takeaways — measure against today's profile, multi-n is essential for table workloads, BEAM optimizations are subtle, immutable data structures bound how fast we can be.
  • Remaining lever: B5 (compile to Erlang) with current status as paused and rationale.

What does NOT change

Direction A section is left untouched. It's also stale (lists A1/A2/A3 as "in review" but they shipped long ago) but strategic narrative is human-owned per the ship-a-plan skill convention; you'll want to update Direction A separately when you decide what its current shape is.

Companion PRs

This PR rolls up the same findings that live in the per-plan deferral PRs:

Those PRs are the per-plan source of truth (with full benchmark tables and the implementation discoveries). ROADMAP is the cross-plan synthesis.

Diff

 ROADMAP.md | 126 +++++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 110 insertions(+), 16 deletions(-)

Documentation-only; nothing to verify beyond reading.

Updates Status (test counts, suite count, date) and replaces the stale
B1/B2/B3 Direction B section with a consolidated summary of the
B4-B8 sweep:

  Shipped: B8 (numeric narrowing fast-path, #227),
  bench harness rework (#230).

  Tried and deferred with findings:
  - B6 (Map.fetch! elimination): profile after #223 no longer
    supported the hypothesis.
  - B7 (array+hash table split): wins at small n, regresses badly at
    large n; BEAM tuple-copy crossover is structural.
  - B4 (flat instruction stream): implemented end-to-end, fib(30)
    regressed 3%; case-on-tuple-elem doesn't beat list-cons head-match
    on the BEAM.

  What we learned: measure against today's profile, multi-n is
  essential for table workloads, BEAM optimizations are subtle,
  immutable data structures bound how fast we can be.

  Remaining lever: B5 (compile to Erlang) is paused. The
  Lua.Compiler.Linearize implementation from B4 is reusable as a
  compile-time input to B5 without touching the runtime executor.

Direction A is left untouched (also stale but human-owned per the
ship-a-plan convention).
@davydog187 davydog187 merged commit 8652a09 into main May 22, 2026
4 checks passed
@davydog187 davydog187 deleted the docs/b-series-consolidation branch May 22, 2026 10:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant