[arch] Persistent, queryable krapper service (on-demand resolution)

[monkopedia-coder]

Epic: single krapper binary + ksrpc service interface to the compiler (Jason's direction, 2026-07-26). This is brick 3 of 3. Depends on #184, #185.

Once krapper is one binary behind a typed ksrpc channel (#184, #185), it can stay alive across a Gradle daemon session instead of being a one-shot batch process, and answer questions on demand.

Query surface (sketch)

• resolve(spec) — what does this C++ type/decl bind to?
• explainDrop(spec) — why is there no binding for this? (DropLedger already has the answer)
• instantiateNow(spec) — instantiate a template on demand, instead of pre-declaring it in a manifest
• diagnostics() — the structured stream from [arch] ksrpc service interface between the compiler and krapper (typed diagnostics, no stdout-scrape) #185

Why this matters beyond ergonomics

Two long-standing walls are consequences of the batch, parse-everything-up-front architecture:

• [clang-campaign] SCALE tail: broad-binding correctness (the 284-error / bare-enum-qualification thesis) #10 (scale). Forcing a broad surface drags in the whole transitive closure (~3745 classes for clang::Decl) because binding is eager and closed-world. A live service can bind lazily — materialize only what the consuming Kotlin code actually touches. The closure explosion stops being the shape of the problem.
• [clang-campaign] SCALE tail: broad-binding correctness (the 284-error / bare-enum-qualification thesis) #10 / fix(codegen): AST well-formedness gates — skip bindings needing an absent element == / a deleted default ctor (#10) #175 (the Sema wall). We concluded a live Sema probe "is NOT available in the read-the-AST architecture", so well-formedness gets approximated with AST-capability heuristics (docs/design/wellformedness-binding-gate.md). A persistent Clang instance answering queries has Sema — overload resolution, SFINAE, and instantiability become askable rather than guessable.

Template instantiation manifests (--instantiate pre-declaration) also stop being necessary.

Open (needs-decision)

• Process lifetime + ownership: Gradle daemon-scoped? build-scoped? Idle timeout?
• Determinism and caching: an incremental/lazy binder must still produce byte-identical output for the same inputs (featuregen SYNC is the gate).
• Memory: a persistent Clang instance holding ASTs across a daemon session.
• Whether the FIR compiler plugin becomes a second client of the same service (today it reads @krapper.CppBinding annotations statically and re-derives the name mangling), or stays annotation-driven.

[monkopedia-coder]

Owner decision (2026-07-28): the FIR plugin DOES become a live client

Jason ruled on the open fork: live client. The Kotlin compiler queries the krapper service during compilation rather than staying annotation-driven.

That settles the question that decided this issue's ambition. Today the FIR plugin reads @krapper.CppBinding off generated symbols and re-derives krapper's KotlinWriter name-mangling statically — there is no runtime channel to krapper at all. As a live client it can instead resolve bindings on demand, during compilation.

Why this matters beyond ergonomics

It removes the two premises #10 is parked on:

1. The closure explosion. Eager, closed-world binding is what makes forcing a broad surface drag in the whole transitive closure (~3745 classes for clang::Decl under INCLUDE_MISSING). Lazy binding materializes only what the consuming Kotlin code actually touches — the closure stops being enumerated at all.
2. The Sema wall. docs/design/wellformedness-binding-gate.md (the fix(codegen): AST well-formedness gates — skip bindings needing an absent element == / a deleted default ctor (#10) #175 design record) concluded that a live clang::Sema is not available in the read-the-AST architecture, so well-formedness is approximated with per-capability AST predicates and a keep-on-doubt rule. That document is explicit that this is the honest shape given no live Sema: "there is no single AST query that means 'will any arbitrary body compile' without a live Sema; there IS a cheap AST query for each concrete capability." A persistent Clang instance has Sema — overload resolution, SFINAE, and instantiability become askable rather than guessable, and the per-family predicate treadmill stops.

Defaults being taken on the remaining questions (say so if you disagree)

• Lifetime → Gradle-daemon-scoped with an idle timeout. Build-scoped discards the win; unbounded holds Clang ASTs indefinitely.
• Determinism → featuregen SYNC byte-identity remains the hard gate on any lazy binder. It has caught every generator regression to date, including two silent ones.
• Session watchdog → still deliberately absent (see [arch] ksrpc service interface between the compiler and krapper (typed diagnostics, no stdout-scrape) #185/feat(build)!: drive krapper over a ksrpc service channel with typed diagnostics (#185) #190): a hang hangs the build, same as pre-[arch] ksrpc service interface between the compiler and krapper (typed diagnostics, no stdout-scrape) #185, and a timeout that cannot accommodate a legitimately slow parse (v8 sync ≈ 4 min) is worse than none. Revisit if persistence changes the timing profile.

Sequencing

Bricks 1 and 2 are done and on main: #184 → b787196 (single :krapper binary), #185 → e75707b (ksrpc channel + typed diagnostics). This issue is the remaining brick.

Note the release-lag constraint still applies: the root build consumes the published plugin, so none of this reaches the repo's own modules until 0.3.4 ships. 0.3.4 is authorized and being cut now, after which the pinned plugin bumps and #187's transitional bridge in featuregen/cppfixture gets deleted. Design work here can proceed in parallel; implementation should land against the post-0.3.4 world.

[monkopedia-coder]

Label: needs-decision → blocked (2026-07-28)

needs-decision here meant "awaiting the owner's judgment." That judgment has been given, so the label was stale — and stale needs-decision is the one label that makes triage refuse to dispatch indefinitely.

What was decided: the fork this issue was actually parked on — whether the FIR plugin becomes a live client of the service, or stays annotation-driven — was settled on 2026-07-28: live client.

What is NOT awaiting him: the three remaining sub-questions are implementation choices, taken as stated defaults rather than escalated. They are recorded above and remain open to veto, not blocking:

• Lifetime → Gradle-daemon-scoped with an idle timeout
• Determinism → featuregen SYNC byte-identity stays the hard gate on any lazy binder
• Watchdog → still deliberately absent; revisit if persistence changes the timing profile

Why blocked rather than agent-workable: this is sequenced, not undecided. Two things must land first:

1. 0.3.4 must publish. The root build consumes the published plugin (settings.gradle.kts pins it), so nothing here reaches the repo's own modules until the release exists on the Portal. Release prep is PR chore(release): prepare 0.3.4 — version bump + commit the two design records #191, merge + cut pending the owner.
2. The post-publish migration must land — bump the consumed pin 0.3.3 → 0.3.4 and delete refactor(tool)!: merge :krapper_parse into :krapper_gen as a single :krapper binary (#184) #187's transitional featuregen/cppfixture sync bridge, explicitly marked "delete once the pinned plugin is 0.3.4+". Building this issue against a bridge that is about to be deleted would mean writing code twice.

Flip to agent-workable once the migration lands. Design work can proceed in the meantime; implementation should target the post-migration world.

Related: bricks 1 and 2 of this epic are done — #184 (b787196, single :krapper binary) and #185 (e75707b, ksrpc channel + typed diagnostics).

[monkopedia-coder]

Unblocked — both sequencing dependencies are met: v0.3.4 published (verified resolvable on the Plugin Portal + Central), and the migration landed as 34fb7a3 (PR #193 — consumed pin now 0.3.4, #187's transitional sync bridges deleted). Label flipped blocked → agent-workable.

The repo now self-hosts on the single-binary + ksrpc-channel plugin, so implementation here targets a clean base rather than a bridge that was about to be removed.

One thing to fold into the design: #194 — 0.3.4 has a plugin-classloader defect where a multi-project consumer gets the root classloader's coroutines 1.8.0 instead of the resolved 1.11.0, breaking ktor-io. It is worked around consumer-side today (apply false at the root), but a persistent service will lean harder on that runtime stack than a one-shot session does, so the proper fix (shade/relocate, or an isolated-classloader worker) is worth settling before building persistence on top of it.