Warm-singleton resolve headroom

[lesnik512]

The C2 warm-singleton gap against the slot-memoized rivals stays open — the memo-swap technique that targeted it was measured and dropped, and closing it now requires removing the resolve_provider dispatch floor itself.

modern-di's warm singleton hit is the one scenario where it sits clearly behind
the field. Two levers were identified; both have since been ruled on, and what
remains open is narrower than the original item.

Why it is open

The single-path compiled resolver (#334) replaced the interpreted recursion with
one memoized per-provider closure — a clean win everywhere (transient −37%, warm
singleton −31%, deep chain −61%, wide −62%). It left the warm hit still paying
resolver_for dispatch, the override front-guard, and fetch_cache_item on
every call.

3.1.2 then inlined the two dict-lookup hit paths (resolver_for and
fetch_cache_item), calling the method only on a miss. That cut the warm hit
~25% — 170 → 128 ns by reference — and every top-level resolve benefits, since
one of the two sits in resolve_provider.

What stays open: the gap to the slot-memoized rivals. dependency-injector
reads a C-level slot on a Cython core, that-depends a lock-free slot,
wireup a self-modifying closure. Pure Python does not reach a C-level slot
read, so part of this gap is a floor, not a defect. The live comparative
numbers are in performance.md,
regenerated by just bench-report — read that, not a snapshot here.

Two levers, both now settled:

• The memo-swap (swap the cached provider's resolver for a bare
  return value closure) was built, fully tested, measured at ~1.6x, and
  dropped — see
  0015-warm-singleton-memo-swap-dropped.
  The decisive finding is that resolve_provider's dispatch floor is upstream of
  the swap and unremovable by it, so the technique provably cannot reach
  "near-free".
• The codegen ceiling on transient and deep-chain is the cost of staying
  exec-free: dishka and wireup inline dependency calls into generated source,
  removing the per-node closure-call frame modern-di keeps. Re-declined — see
  0017-exec-hot-path-declined.
  The supporting measurement: closures already capture ~80-90% of the available
  ceiling, and exec buys a further 0-4% at fixed arity. So being modestly
  behind the codegen leaders on construction-heavy graphs is an accepted floor,
  not a bug.

A third step was considered during the 3.1.2 work and deliberately not taken: an
APP-scoped resolver could close over its CacheItem and reach ~16 ns, but the
target is only invariant because one registry belongs to one root — so the
registry would have to reference its root container, reintroducing the reference
cycle removed in 3.1.1. That needs a weakref and a proof, for a margin that
performance.md is the only place to read.

Revisit trigger

A user-reported warm-singleton bottleneck, plus a design that removes the
dispatch floor itself. Re-proposing the memo-swap unchanged is settled; so is
exec codegen. A that-depends-style per-APP-container slot array is the one
untried direction and would need its own measurement against the same bar.

[lesnik512]

This was generated by AI during triage.

Triage outcome: ready-for-human

Kept open as real-but-unscheduled work. Not delegable to an AFK agent — see "Why this cannot be delegated" below. An agent that picks this up will re-propose something ADR 0015 or ADR 0017 already settled.

Human Brief

Category: enhancement
Summary: One untried direction remains on the C2 warm-singleton gap — a per-APP-container slot array — behind a two-part gate that is not currently satisfied.

Current behavior:

A warm singleton hit pays resolve_provider dispatch, the override front-guard, and the cache fetch. 3.1.2 inlined the two dict-lookup hit paths, calling the methods only on a miss. modern-di now leads the by-type comparison and trails the two slot-memoized rivals by reference.

Read the live figures from the Performance page, regenerated by just bench-report — not from any number quoted in this issue's body or its comments. Those are snapshots from 3.1.2 and the cells have moved twice since. (The same snapshot problem in ROADMAP.md is #438.)

Part of the remaining gap is a floor, not a defect: dependency-injector reads a C-level slot on a Cython core, which pure Python does not reach.

The one direction still open:

A that-depends-style per-APP-container slot array. An APP-scoped resolver could close over its CacheItem and reach roughly a bare slot read. The obstruction is ownership: that target is only invariant because one registry belongs to one root container, so the registry would have to hold a reference to its root — reintroducing the container reference cycle removed in 3.1.1. Making that safe needs a weakref and a proof that the cycle stays gone.

The gate — both conditions, not either:

1. A user-reported warm-singleton bottleneck in a real application. Resolution is a small fraction of request work, so this is a demand signal that has not appeared.
2. A design that removes the resolve_provider dispatch floor itself. ADR 0015 established that the floor sits upstream of the cached value, so a technique that only makes the cached read cheaper cannot reach "near-free".

Settled — do not re-propose:

• The resolver memo-swap (swapping a cached provider's resolver for a bare return value closure). Built, fully tested, measured, dropped: ADR 0015. It provably cannot clear the dispatch floor.
• exec codegen on the resolve hot path. Re-declined: ADR 0017. Closures already capture ~80-90% of the available ceiling; exec buys a further 0-4% at fixed arity. Trailing the codegen frameworks on construction-heavy graphs is an accepted floor.

Why this cannot be delegated:

• The gate's first condition is a judgment call on demand. Only a human reading user reports and issues can decide that a real bottleneck has appeared. An agent has no way to evaluate it and will treat the issue as a licence to optimize.
• It requires a design that does not yet exist. This is not an implementation task with a known shape — ADR 0015 ruled out the obvious approach, and what replaces it has to be invented and argued.
• Verification needs a controlled machine. Confirming a change moves the published cell requires reproducing the page's methodology (paired runs on a quiet machine with published IQRs). GitHub's shared runners are too noisy; the guard-tier CI benchmark is non-gating and modern-di-only.
• It touches the container reference-cycle guarantee. Reintroducing a registry-to-root reference is a correctness question about object lifetime, not a perf tweak, and it needs a proof rather than a passing test run.

If the gate is ever satisfied, done looks like:

• The published C2 by-reference cell moves materially, measured under the Performance page's stated methodology and republished with the change.
• No container reference cycle is reintroduced — demonstrated, not asserted.
• The design is written up as an ADR before implementation, stating what it does that the memo-swap could not.

Out of scope:

• Re-proposing the memo-swap or exec codegen in any form (ADRs 0015, 0017).
• Any change justified only by a benchmark number, absent condition 1 of the gate.
• Editing ROADMAP.md's copy of the comparative ratios — that is ROADMAP.md's "Under consideration" duplicates the issue queue #438.
• Refreshing the Performance page — that is The performance page implies its numbers are current #437.