perf(context): lazy event-context seeding — skip stack work on untouched polls

[bodymindarts]

Motivation

Follow-up to the review discussion on #163. Benchmarking that PR's two changes in isolation (criterion suite included here; A/B protocol below) showed:

• an im::HashMap clone is a flat ~3.4 ns regardless of size — clone cost was never the problem, structural sharing already makes it O(1)
• of the wrapper's ~21 ns/poll cost, ~18 ns is the seed/drop machinery itself — 3 thread-local accesses, a per-poll Rc::new(()) heap allocation, and a stack push/pop — which is independent of the container and survives perf(context): eliminate per-poll context clone overhead #163 unchanged (perf(context): eliminate per-poll context clone overhead #163 lands at ~18.6 ns/poll)

So this PR keeps im and instead removes the machinery cost for the polls that don't need it — which is almost all of them: EventContext is observed once at request setup (the #[es_event_context] macro's inserts) and once per event persist, while the wrapper's poll runs at every .await resumption.

Design

EventContextFuture::poll no longer eagerly creates a context-stack entry. Instead it parks its ContextData on a thread-local pending-seed stack (a move — no clone, no allocation) and pops it on exit:

• Untouched poll (fast path): the data is taken back unchanged. Zero heap allocations, zero clones, zero CONTEXT_STACK traffic — just two thread-local Vec push/pops.
• Observed poll: EventContext::current() / seed() first materialize all pending seeds (in push order) into real stack entries, then proceed exactly as before. On poll exit the wrapper harvests ctx.data() from the materialized entry — identical write-back semantics, including the entry surviving if the inner future kept a handle across the poll.

Ordering invariant: pending seeds always sit logically above every entry that existed when they were parked; since every push path (current/seed/fork) materializes first, nested wrappers, forks, and direct seeds interleave identically to eager seeding.

Panic safety: a guard pops the pending record on unwind and drops any materialized handle through the normal EventContext drop path — write-back skipped, matching eager behavior. (Re-polling an EventContextFuture after a panicked poll now panics with an explicit message; futures are contractually dead after a panic.)

Measured effect

Criterion, Apple Silicon, --baseline im = current main (reproduce: cargo bench --bench context -- --save-baseline im on main + the bench commit, then -- --baseline im here):

	main (im, eager)	#163 (Arc<Vec>)	this PR (im, lazy)
wrapper cost per poll (raw driver)	21.4 ns	18.6 ns (−13%)	12.6 ns (−41%)
wrapped 65-yield tokio task	1.91 µs	1.72 µs (−9%)	0.89 µs (−54%) — ~5.8 ns/poll added
heap allocs per untouched poll	1 (Rc::new)	1 (Rc::new)	0
clones per untouched poll	2	1	0
EntityEvents::push persist path	177 ns	123 ns	179 ns (unchanged, p > 0.05)
explicit EventContext::seed()	17.8 ns	16.7 ns	19.7 ns (+10%, materialize check)

Trade-offs, honestly: direct seed() and first-observation polls pay a ~2 ns materialize check; the persist path is unchanged (this PR deliberately doesn't touch ContextData — container/serialization changes can be argued separately on hygiene grounds).

Scale disclaimer (why this is framed as hygiene, not throughput): even at 1M poll resumptions/sec the eager machinery costs ~2% of one core. What this PR does eliminate at any rate is the per-poll allocation and clone traffic — the malloc/free and LocalKey::try_with signals visible in the lana-bank stress-run profile.

Testing

• New unit tests: untouched-poll fast path (stacks provably untouched), fork-under-wrapper materialization ordering, panic-unwind balance; existing spawned-context tests updated for the lazy depth semantics (entries appear on first observation).
• nix run .#nextest green (full DB-backed integration suite against live process-compose Postgres); all 37 lib tests + doctests pass; cargo clippy --workspace --all-features clean; cargo fmt --check clean.
• The criterion bench suite (benches/context.rs, structured after cala-perf) is included so the numbers are reproducible on any branch — it only uses public API, so it cherry-picks onto main and perf(context): eliminate per-poll context clone overhead #163 alike.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes async context propagation semantics (lazy vs eager stack depth) across spawned tasks and panics; behavior is heavily tested but ordering bugs could affect event context on persist.

Overview
with_event_context no longer eagerly seeds the context stack on every poll. Each poll parks ContextData on a thread-local pending-seed stack; a real stack entry is created only when the inner future calls EventContext::current() or seed() (via materialize_pending_seeds). Untouched polls avoid Rc allocation, ContextData clone, and CONTEXT_STACK push/pop.

EventContext::seed / current materialize pending seeds before proceeding; stack pushes go through a new private push_entry. SeedGuard handles normal write-back and panic unwind so stacks stay balanced.

Adds benches/context (Criterion) for per-poll overhead, tokio yield, clone, lifecycle, and persist paths, plus tests for lazy depth, untouched polls, fork ordering, and panic cleanup.

^{Reviewed by Cursor Bugbot for commit 03274df. Bugbot is set up for automated code reviews on this repo. Configure here.}