Gather requirements for release after v1.12.2

[mparrett]

Tracking issue to scope the next cut after v1.12.2 (2026-07-20), modeled on #275 / #545. About 55 commits have landed on main since that tag (through #628, f3ca5f9b, 2026-08-11), with another ~20 open PRs in flight. Freeze scope here, draft the upgrade notes, run the pre-release checks, and list blockers before we tag.

#545 still tracks the v1.12.0 cut that already shipped (v1.12.0–v1.12.2). Close or retarget it so release tracking has one live home.

Scope snapshot

Range v1.12.2..main @ f3ca5f9b: 55 merged PRs (~54k insertions / ~8k deletions across ~237 files). Headline arcs:

• VM / call path. Explicit frame chain for direct bytecode calls (vm: make direct bytecode calls non-recursive with an explicit frame chain #645): stack-safe deep lg→lg recursion (vm: Frame.Run is Go-recursive — deep lg→lg recursion aborts the process #644), with a measured per-invoke cost tracked in vm: bytecode invoke is ~1.7x costlier since #645 (explicit frame chain) #700. Follow-ups: vm: drop leaveFrame's unused *Frame parameter to unpin f from memory #706, Design: constant-space tail calls on the explicit-frame VM (closures, multi-arity, apply) #620, perf(vm): re-evaluate static self-call shortcut after shared frame transitions #646.
• Native / registrar surface. Hot clojure.core direct-call natives (perf(rt): direct-call natives for the hot clojure.core surface #613); hoist of 222 primitives to //lg:native (feat(rt): hoist 222 clojure.core primitives to named //lg:native decls #639); per-package registrar (feat: per-package //lg:native registrar surface (migrate corefns) #640). Shadowed reduce registration fixed in perf(rt): restore reduce's ArrayVector and Range fast paths #686; remaining guard gaps in Three generated-primitive guards pass when their premise breaks #704 / Retire the twelve hand registrations the generated registrar shadows #696 / Drain the remaining hand registrations in pkg/rt onto //lg:native #697.
• IR / AOT. Catalog-driven op and form-head dispatch (perf(ir): catalog-driven op dispatch — generated OpByKeyword string switch (§1/§2/§2b) #612, refactor(ir): catalog-driven form-head dispatch with load-time coherence check #667); strict-mode census (feat(ir): *ir-compile-strict* + a bytecode-path coverage census (70.7% vs the 99.5% we were measuring) #580); lower correctness (fix(ir/lower): block-junk agreement + RPO block order + deferrable-branch guards #648, fix(ir): give function-level recur its own op and lower it to OP_RECUR_FN #642, fix(ir): treat a return-hinted arity vector as one arity (#598) #661); typed-return override registration (fix(aot): register a boxed override for typed-return fns (#554) #653); self-recursive typed seed (feat(ir): seed self-recursive calls from a declared return type (#599) #662); native-entry Go frame via lg-compile --entry-frame (feat(aot): generate native-entry Go frame from main/-main (#425 Item 1) #628, closes AOT native-entry: generate the Go entry frame, self-contain gogen, and stop the silent perf-cliff #425 Item 1 / AOT entry frame: recover the lowered signature from gogen as data, not by string-matching rendered Go #657). Silent fallback and strict Tier-2 fixtures: Lowering falls back to bytecode silently, and only the bench harness notices #660, strict-mode AOT: 6/16 gold-aot fixtures only run via silent fallback — binding conveyance, @f deref rot, closure capture untracked #678; parity gate PR test(parity): gate complete-corpus strict capability and engine output #681.
• WASM / host. SPSC ring + held-key coalesce for SAB key input (feat(wasm): SPSC ring buffer + held-key coalesce for SAB key input #595); RGBA surface capability (feat(rt): surface host capability — RGBA frame sink (graphics, #255) #572); TinyGo lane (feat: TinyGo support: small-footprint WASM and native builds #522) with CI follow-ups (ci(tinygo): failed wasmtime install passes and breaks the boot step #682, ci(tinygo): pin wasmtime and verify it landed on PATH #685).
• Toolchain / bundles. go.mod toolchain go1.26.5 (build: single-source Go toolchain via go.mod toolchain directive #677); named capability rejects (feat(bytecode): actionable hint on capability-mask reject #608, feat(bytecode): name capabilities in reject errors and lg -v #622); Var metadata bundle round-trip + clojure.repl / clojure.pprint (feat(clojure): add clojure.repl / clojure.pprint, fix Var metadata bundle round-trip #668); lg_no_http build tag (build: add lg_no_http to drop net/http from the runtime (#652) #658).
• Embedder API. lg.IsIncomplete (feat(api): IsIncomplete — sanctioned incomplete-input check for REPL loops #602); lg.NS / Def / DefShadowing (feat(api): namespace facade — lg.NS with Def/DefShadowing #603).

Behavior changes to note for the release

Consumer- and embedder-facing; confirm wording before the tag:

• Breaking (Go API): chore(rt): drop 34 unreferenced per-file core embeds superseded by coreFS #604 removes 34 exported per-file core-embed symbols (rt.SetSrc, rt.TestSrc, …) superseded by coreFS. No known public callers found at review time; still name it in the upgrade notes.
• Toolchain floor: builds expect Go 1.26.5 via the toolchain directive (build: single-source Go toolchain via go.mod toolchain directive #677).
• RunExecUnit load path (feat(aot): generate native-entry Go frame from main/-main (#425 Item 1) #628): even without --entry-frame, RunExecUnit now loads via LoadProgramNamespaces (NSOrder replay + ApplyGoOverrides drain) and RunProgramMainChunk. Orchestrators that assumed the old MainChunk-skip loop should re-check (Gloat lower-vm; see also AOT lower-vm: embedded VM-fallback bundle rejected by its own runtime — unsupported capability mask 0x1 (supported: 0x0) #607).
• --entry-frame: opt-in native-entry main.go; default lg-compile remains package-only for orchestrators that own their own frame.
• WASM key input (feat(wasm): SPSC ring buffer + held-key coalesce for SAB key input #595): single-slot SAB input replaced by an SPSC ring (drop when full; held-key coalesce). Hosts that assumed oldest-pending-wins single-slot semantics should revalidate interactive / held-key paths.
• .lgb / Var metadata (feat(clojure): add clojure.repl / clojure.pprint, fix Var metadata bundle round-trip #668): :arglists / source location metadata round-trips through the bundle; core bundle regenerated.
• Capability reject messages (feat(bytecode): actionable hint on capability-mask reject #608, feat(bytecode): name capabilities in reject errors and lg -v #622): clearer errors / lg -v naming; mask compatibility rules unchanged in intent. Verify against AOT lower-vm: embedded VM-fallback bundle rejected by its own runtime — unsupported capability mask 0x1 (supported: 0x0) #607 before advertising lower-vm.

Known open items that touch the cut

Already filed; decide accept / fix / defer before tagging:

Issue	Why it matters for the cut
#700	Bytecode invoke ~1.7× costlier since #645; explains residual reduce / some / etc. cost after #686
#663	Startup ~5 ms → ~9 ms unnoticed; ratchet not in the everyday loop
#705	Perf gate can report green through a regression (budget, filter, soft-else)
#704	Generated-primitive guards can pass when their premise breaks
#660 / #678	Silent AOT fallback; 6/16 gold-aot fixtures Tier-2 under strict
#607	lower-vm embedded fallback rejected (capability mask 0x1 vs 0x0); Gloat regression
#636	Self tail call lowers to a Go call (stack growth once AOT), constant-space on VM
#681 (PR)	Phase-1 backend parity / strict-mode audit: makes the #660/#678 frontier visible in CI

In-flight PRs worth naming in scope freeze (not a full queue): #681, #706, #649, #675, #692, #501/#502, #624, #641, #683, #713.

Downstream dependencies

• WASM game / interactive hosts should revalidate key input after feat(wasm): SPSC ring buffer + held-key coalesce for SAB key input #595 before bumping past v1.12.2.
• Gloat / other RunExecUnit or lower-vm consumers should exercise tip with and without --entry-frame, and confirm AOT lower-vm: embedded VM-fallback bundle rejected by its own runtime — unsupported capability mask 0x1 (supported: 0x0) #607 status.
• No additional hard pin floor identified beyond the Go 1.26.5 toolchain and the chore(rt): drop 34 unreferenced per-file core embeds superseded by coreFS #604 embed API removal.

Pre-release checklist

• Scope frozen — list squeeze-ins still allowed vs deferred to the next tag
• Close or retarget Gather requirements for release v1.12.0 #545 so this issue is the live release home
• Size + perf audit vs v1.12.2: startup (lg -e '(+ 1 1)'), reduce / invoke micros (vm: bytecode invoke is ~1.7x costlier since #645 (explicit frame chain) #700), WASM, make bench-ratchet / interleaved A/B where relevant
• Confirm Three gaps that let the perf gate report green through a regression #705 holes are either fixed or explicitly accepted for this cut
• AOT matrix: default lg-compile, --entry-frame, lower-vm (AOT lower-vm: embedded VM-fallback bundle rejected by its own runtime — unsupported capability mask 0x1 (supported: 0x0) #607), strict Tier-1 vs Tier-2 (strict-mode AOT: 6/16 gold-aot fixtures only run via silent fallback — binding conveyance, @f deref rot, closure capture untracked #678 / test(parity): gate complete-corpus strict capability and engine output #681)
• Release hook green — go test -short path that tag-push runs
• Upgrade notes: breaking chore(rt): drop 34 unreferenced per-file core embeds superseded by coreFS #604, toolchain build: single-source Go toolchain via go.mod toolchain directive #677, #595 host input, #628 RunExecUnit / --entry-frame
• Draft release + announcement; attribution pass
• Tag (version TBD below)

Open questions

• Version: v1.13.0 (minor: features + one Go API removal), or a v1.12.3 patch if the cut is intentionally narrow?
• Accept vm: bytecode invoke is ~1.7x costlier since #645 (explicit frame chain) #700's invoke cost for this tag, or require a mitigation (vm: drop leaveFrame's unused *Frame parameter to unpin f from memory #706 / Design: constant-space tail calls on the explicit-frame VM (closures, multi-arity, apply) #620) first?
• Is AOT lower-vm: embedded VM-fallback bundle rejected by its own runtime — unsupported capability mask 0x1 (supported: 0x0) #607 a release blocker for advertising AOT / lower-vm, or a known-limitation note?
• How much of the open frontier (~20 PRs) freezes into this cut vs the next?

Add other release-worthy items or blockers below.

[mparrett]

@nooga Suggesting this one, too, depending on the cut (documentation freshening): #717

[mparrett]

Probe results vs v1.12.2 + proposed dispositions

Local tip @ f3ca5f9b (includes #628) vs tag v1.12.2, same machine (darwin/arm64). Cut-relevant subset only.

Perf (hyperfine)

Workload	v1.12.2	tip	tip/base
startup lg -e '(+ 1 1)' (quiet, N=50)	9.4 ± 1.6 ms	11.8 ± 1.5 ms	1.25×
(reduce + 0 (range 1e6)) N=20	37.8 ms	41.3 ms	1.09×
(some pred (range 1e6)) N=20	72.4 ms	100.3 ms	1.39×
map/filter/reduce (1e5) N=20	51.2 ms	66.4 ms	1.30×

• #686 held: reduce is near parity; residual matches vm: bytecode invoke is ~1.7x costlier since #645 (explicit frame chain) #700, not a reopened reduce is 1.75x slower than v1.12.2 — bisected to #639 #656.
• #700 shows clearly on callback-heavy shapes (some, pipeline).
• #663 directionally confirmed (~1.25× startup). Absolute ms differ from the issue’s 5→9 (machine floor); the ratio is the signal.

Registrar shadows

TestNoNewShadowedHandRegistrations and the reduce fast-path tests PASS. reduce is no longer double-registered. 12 names remain in the accepted shadow set (conj, deref, get, int, name, namespace, nth, pop-binding!, push-binding!, some, str, subs). #704’s three soft guards are still open; adjacent drain work is #696 / #697.

WASM key input (#595) × xsofy shell

Same shipping shell; tip vs v1.12.2 host JS:

Bundle	Sync burst of 10 'l' via _lgKey
v1.12.2 (single-slot)	1 accepted / 9 dropped
tip (SPSC ring, cap 8)	7–8 accepted (3 runs); burst=20 caps at 8

Neither path busy-spins here (both return false when full). The win is acceptance. Paced LetGoHost.sendInput movement (10 keys @ 80 ms): 10/10 accepted; COI + SAB OK.

AOT / Gloat (#628, #607)

• --entry-frame fib demo: OK (55 / 5702887; fib(34) ~0.11 s).
• lg-compile without the flag: packages only, no main.go (summary still reports native entry).
• rt / e2e / entry_frame tests: PASS.
• Gloat -E let-go-lower-vm and -E let-go-vm with LET-GO-SRC = tip: OK (fib 10/34).
• Gloat lower-vm with LET-GO-SRC = v1.12.2: OK.
• Gloat does not pass --entry-frame; it keeps its skip-MainChunk + override-drain template. Ownership split holds.
• AOT lower-vm: embedded VM-fallback bundle rejected by its own runtime — unsupported capability mask 0x1 (supported: 0x0) #607 not reproduced when encoder and embedded runtime share one LET-GO-SRC. That matches the existing diagnosis: dual-knob skew in gloat (pin vs fork checkout), not a tip #628 regression.

Proposed dispositions for this cut

Answering the open questions on this issue:

1. Version: lean v1.13.0 (features + #604 Go API removal). Not a narrow patch.
2. vm: bytecode invoke is ~1.7x costlier since #645 (explicit frame chain) #700 invoke cost: accept for this tag, with the numbers above in the notes. Mitigation stays on vm: drop leaveFrame's unused *Frame parameter to unpin f from memory #706 / Design: constant-space tail calls on the explicit-frame VM (closures, multi-arity, apply) #620; don’t block the cut on reclaiming the ~1.3–1.4× callback tax unless someone wants that bar raised.
3. AOT lower-vm: embedded VM-fallback bundle rejected by its own runtime — unsupported capability mask 0x1 (supported: 0x0) #607: known limitation / gloat-side, not a let-go tip blocker when sources agree. Link the dual-knob notes; don’t hold the tag on it.
4. Frontier (~20 open PRs): freeze lightly — land gate/hygiene if ready (#681, #706 if cheap); keep IR/codegen and bundle-format stacks (#649, #675, #501/#624, …) for after unless already approved.
5. Performance measurement status: ratchet is not consulted; startup regressed 5ms -> 9ms unnoticed #663 startup (~1.25×): accept with an explicit note; recovery remains under Performance measurement status: ratchet is not consulted; startup regressed 5ms -> 9ms unnoticed #663 / measurement discipline (Three gaps that let the perf gate report green through a regression #705).
6. Three generated-primitive guards pass when their premise breaks #704 / Retire the twelve hand registrations the generated registrar shadows #696 / Drain the remaining hand registrations in pkg/rt onto //lg:native #697: not cut-blocking; drain/guard work before more //lg:native migration, not before the tag.
7. Gather requirements for release v1.12.0 #545: still open for the already-shipped v1.12.0 cut — close or retarget so this issue is the live home.

Upgrade-notes checklist from the probes: #604 embed API removal, toolchain go1.26.5, #595 ring contract, #628 RunExecUnit / --entry-frame split, plus the accepted #700 / #663 costs if we take (2) and (5).

Happy to adjust any of these stances, especially (2) if #706 is close enough to fold in.