BootUI v2 Plan: from panels to runtime understanding

This document plans BootUI 2.0. The v1 plan, PLAN.md, keeps governing the 1.x line on main. All v2 work happens on the long-lived v2 branch, and nothing from it is released before 2.0.0 (§4). Section numbers are stable identifiers: cite them as PLAN-v2.md §5.1, and never renumber or reuse them. An item is 📋 Planned, 🚧 In progress, ✅ Delivered, 💤 Deferred, or ❌ Cut.

This revision incorporates three independent audits, on product strategy, technical feasibility, and adoption and agent value, and the reordered v1 plan. Appendix A records every proposal and what was done with it.

1. Strategy

1.1 The problem

BootUI 1.x ships 60 panels. Each panel is precise about its own source: SQL Trace about statements, Traces about spans, Security about authentication events, Transactions about transactions. The questions developers and their AI agents actually ask cross those sources:

• Why is this route slow, across all its requests rather than in one trace?
• What does my change touch, and how much real traffic goes through it?
• Did my last change make anything slower, or break anything?
• Which work ran without a request, and why?
• Can an anonymous user reach data that only administrators should see?

Today a developer answers these by joining panels in their head. Where BootUI joins sources itself (Live Activity nesting, the request profiler, SQL route attribution), the join is re-derived after the fact from trace ids, serving threads, and time windows. A proof of concept on the Spring MVC sample app measured the gaps:

Spring WebFlux and Quarkus already stamp trace ids on some of these records, but none of the stacks has a request identity that works without tracing.

The M0 correlation scenario (§5.1) then measured the same gap in CI, with tracing on, by sending identical requests paced like a developer clicking, back-to-back like a test loop, and simultaneously like parallel calls:

On Spring, any two identical requests within ±50 ms of each other lose their link, which a test suite or a page's parallel calls do all the time. Quarkus is exact because BootUI owns its exchange capture and stamps the trace id directly, which is the design §5.1 extends to every stack.

After M1 (M1-6f), the extended scenario, which adds a Kafka send, a raw executor, and runners with tracing off, measures:

No child is nested under a request that was not running when it happened, work on the raw executor is reported and never nested, and no request-thread profile is approximate. The scenario enforces all of it in CI.

Once the PoC joined the same events exactly, it surfaced findings no single panel shows:

• secured routes spending 94 % of their time before the controller, in HTTP Basic password hashing;
• the 7 beans and 571 requests that a change to one repository reaches;
• a transaction holding its connection while doing almost no database work;
• 90 statements that lost their request context on an executor;
• a search route whose median moved from 2 ms to 9.5 ms between two runs, which the comparison must attribute to the switch from H2 to PostgreSQL rather than report as a regression.

1.2 The v2 thesis

Stamp every runtime event with exact keys when it happens, keep it in a bounded local journal, and turn it into a few trustworthy observations exactly where developers and agents already look. BootUI 2.0 delivers three outcomes:

1. Exact. Every event knows its request, trace, span, transaction, and run, with or without tracing. Live Activity, the profiler, and route attribution stop guessing (§5.1).
2. Remembered. Evidence outlives the 200-entry window and survives a DevTools restart or Quarkus live reload, so "what changed since the last run?" has an answer (§5.2, §5.3, §5.8).
3. Explained. Observations answer the questions in §1.1 in one sentence with numbers, a sample size, and a concrete check, in Live Activity, a Runtime Insights panel, and agent tools (§5.4–§5.9, §5.12).

The graph from the study remains the conceptual model: requests, routes, beans, tables, transactions, and messages, joined by typed relations. With exact keys, most joins become indexed group-bys maintained as events arrive. The rest walk a small in-memory typed runtime model (§5.4), so 2.0 needs neither a graph database nor a general graph engine.

1.3 What does not change

The five v1 priorities stay in force: safety and local-only operation, easy installation, useful runtime explanations, a polished but simple UI, and testable architecture. In addition:

• No new infrastructure. No graph database, external process, or new heavy dependency.
• Instrumentation stays optional. Every capability in §5.1–§5.12 works from framework hooks alone. The BootUI Java agent (§5.13) is a separate artifact the developer attaches on purpose; it deepens the same evidence and never becomes a prerequisite.
• A runtime view, not an advisor. Observations carry no severity, no score, and no effect on the Scorecard, like the PostgreSQL and MySQL panels. They do say what to check.
• Nothing expensive on page load. Observations are projections over aggregates the journal maintains as events arrive, read the way Live Activity already computes its KPI strip. Opening a panel or calling a read tool never starts a capture, a scan, a database read, or a network call.
• Nothing leaves the machine. The journal is local, bounded, and governed by the live exposure policy. BootUI still collects no telemetry about its users.
• Honest across stacks. Spring MVC stays the reference. Spring WebFlux and Quarkus report each capability they cannot provide as unavailable, with a reason.

1.4 Positioning

The differentiator is in-process, zero-infrastructure, framework-aware runtime evidence, the same on Spring MVC, Spring WebFlux, and Quarkus, readable by humans and agents alike.

2. Business value and success measures

2.1 Jobs to be done

2.2 How success is measured

BootUI collects no usage telemetry, and v2 does not change that. Success is measured with evidence the project controls:

The M0-3 overhead baseline (CaptureOverheadBenchmarkTest, opt-in) measured today's capture cost on Spring MVC, on a worst-case route that answers in about 0.7 ms: with BootUI on, the sample app sustains a median 83 % of the throughput it reaches with BootUI off, and its p99 latency rises from 1.81 ms to 2.52 ms, with tracing sampling every request in both configurations. Slower, realistic requests dilute this cost. The journal target above is measured on top of this baseline, with BootUI on in both runs, and M1 and M2 must not make the BootUI-on figure worse. After M1, the same benchmark, on JDK 26, measures a median 87 % of the BootUI-off throughput, with p99 latency rising from 1.25 ms to 1.54 ms, so M1's request ids, execution ids, phases, and thread kinds cost no measurable throughput. After M2-3, with every request and statement also recorded in the runtime journal, it measures 84.4 %, with p99 latency rising from 1.29 ms to 1.65 ms: the journal costs about 3 points of throughput on this worst-case route, inside the 5 % target. The absolute ratio drifts by several points between sessions on the same machine, so a slice is compared against its predecessor in the same session. After M2-4c, three commits measured back to back give 75.4 % for M2-3c, 76.0 % for M2-4b, and 74.9 % for M2-4c: transactions, log events, connections, and application frames cost no measurable throughput beyond that drift.

2.3 Gates

• After M1. If exact correlation stays below 95 % on Spring MVC or Quarkus, fix capture before building on it. Passed: the M1-6f scenario measures 100 % on every stack, in every phase, with and without tracing (§1.1).
• After M3. If fewer than 50 % of external-application observations are judged useful, stop adding observations and fold the useful ones into the existing panels they belong to. Tripped: the first validation run measured 14 % (16 of 116 observations; first published as 115, corrected by M4-20a), and an estimated 14–23 % after the fixes merged since. The maintainer chose to freeze new observation kinds, cut default-visible noise, register a per-kind protocol, rerun with holdout applications, and apply this gate per kind (D35, D36, M4-19, M4-20). If the rerun's default-visible score is under 30 %, or the holdout applications score more than 20 points below the tuned ones, every kind that misses its per-kind gate folds into its existing panel as this gate first said.
• Before 2.0.0. Record whether the journal overhead target was met and any maintainer-directed exception in the release sign-off. A missed target does not by itself change the journal's default; D51 records the decision for the measured miss.

2.4 Feedback without releases

Nothing is published before 2.0.0 (§4.3), so feedback comes from outside the release channel:

• the external-validation report on five open-source applications (§2.2);
• a scripted three-minute demo on the sample apps, recorded at the end of M3;
• documented early-adopter builds of the v2 branch into a local Maven repository;
• a pinned GitHub discussion for v2 feedback, linked from the README once M3 lands.

3. Relationship to the v1 plan

The v1 plan's diagnostics workstream (PLAN.md §2) shapes evidence BootUI already captures. BootUI 1.x is in maintenance since 2026-09-30: its foundations (✅) are delivered on main and merged into v2, only §3.25 and §3.18 remain planned there, and the rest of its roadmap was dropped. Where v2 relied on a dropped item, v2 now builds what it needs itself, as the last column states. v2 builds exact keys, the journal, and observations on top of it. Each shared capability has one implementation and one owner. A v1 foundation is delivered on main in its wave and merged into v2; v2 extends it instead of duplicating it.

Three design points shape how v2 reuses v1 foundations:

• §3.20's tiers stay as fallbacks once REQUEST_ID exists.
• The journal follows §3.24's reservation for evidence rows only. Route and statement statistics come from aggregates counted before eviction, so retention never biases percentiles (§5.2).
• v2 CLI commands follow §3.25's naming rule: unique paths, never a prefix of another path.

4. Roadmap, branch, and releases

4.1 Order of work

M0–M4 total about 179–230 engineer-days, roughly seven to nine months with two developers who also maintain 1.x. Opt-in JFR attribution (§5.11, D17) adds 6–9 engineer-days to M4, so M0–M4 come to about 185–239 engineer-days with it. D35's M4-19 to M4-23 add 17–23, bringing M0–M4 to about 202–262. §5.18's journal coverage adds about 15–21 engineer-days for the slices §5.8 and §5.9 need (M3-8, M3-9, M4-5, M4-6) and 25–35 for the others (M4-7 to M4-10), which D29 places. M5 is estimated separately and does not gate 2.0.0 (D20): its slices land on v2 as they are ready, what is merged when M4 meets its gates ships in 2.0.0, and the rest follows in 2.x. The v1 foundations are estimated in their own plan. Before v1 wave 1 lands, v2 works on M0 and the spikes.

M0 is split into four items:

M3 is split into slices, each one pull request to v2. Only the agent tools and Copy for AI need v1 §3.25, so they come last and everything before them proceeds without it:

M4's slices are defined as M3 completes, each one pull request to v2. M4-1 and M4-2 make the behavior diff possible: today a run summary keeps routes, statements, exception groups, and transactional methods, but not the runtime model's edges, and every summary lives in the in-memory run history, so a full JVM restart leaves nothing to compare against.

M4-18b's comparison portion is delivered: executions beside routes, gone fingerprints when bounded evidence permits, no EVALUATED check with no eligible work in its own unit (requests, executions, or collections), and an optional comparison id (OPTIONAL_ID, default previous) on MCP and CLI. Its agent-latency and change-impact work remains separate.

M4-5 and M4-6 are prerequisites of §5.8 and §5.9, which cannot be delivered as written without them. Per D29, M4-5, M4-6, M3-8, and M3-9 join 2.0; M4-8 and M4-9 join it if capacity allows, their observations only once their counterexample fixtures pass; M4-7 and M4-10 by capacity. What is merged when M4 meets its gates ships, and the rest follows in 2.x. The order follows the gates: M4-1, M4-2, M4-5, M4-11, M4-6, M4-12, M4-13, M4-14, M4-15, M4-3, M4-4, then M4-7 to M4-10, with M4-16 and M4-17 closing the milestone. After the post-M3 gate tripped (D35), M4-18 and M4-19 come first, then M4-21 and M4-22, then M4-20's rerun; M4-25 (MCP progress and cancellation, #1340), a 2.0.0 gate, is delivered; M4-23 and M4-17 close the milestone.

M5 is split into slices ordered by business value, each one pull request to v2 unless its row says otherwise (D37). The spike comes first; each later slice depends on M5-1, and on the milestone named:

M5-1/M5-2 lifecycle guarantees delivered: pending submissions from overlapping claim generations retain their count and become sticky-ambiguous, never taking a newer run's snapshot (D32); direct fork/join rejections (including already-completed tasks) and failed thread-per-task starts release their keyed submissions. Fork/join cleanup stays at the admission boundary, without double-releasing an application failure from invoke's subsequent join. Both sensors supersede queued releases and reinstall after an in-flight reset when reclaimed (D34), with deterministic worker-gated regression tests in both orderings. Threads transformers restore their own historical package set before a changed-package reclaim installs its replacement, proved against real transformed subclasses. Executor skip counters stop while disarmed, omitted from the current claim, or disabled by the self-test. Retained tasks removed without a release hook can stay ambiguous until collected; a generation change deliberately does not clear them.

M5 implementation steps

The slices above, broken into the steps each pull request takes. They carry the constraints of two rubber-duck reviews on Claude Opus 5.5: of the M5-0 spike (§5.13, M5-0 spike, first pass) and of this plan itself. They are a plan, not a contract: each slice's design is reviewed again before it is implemented, and its implementation before it is committed, as the maintainer asked. Every review covers class loading and bridge survival across restarts and reloads, retransformation safety, coexistence with other agents, overhead, and failure isolation.

Every slice also: keeps §5.1–§5.12 unchanged without the agent; makes each observation that needs the agent NOT_APPLICABLE with "requires the BootUI agent" and the -javaagent line; adds its sensor to bootui.agent.sensors and its journal source as agent.<sensor> to bootui.runtime-journal.sources, with drop counters; ships on Spring MVC, WebFlux, and Quarkus in JVM mode, and reports the agent unavailable in native mode; moves panels, API contracts, MCP tools, CLI commands, and documentation in lockstep (PLAN.md §4, the e2e panel lists, the contract catalog); pre-aggregates per request before the journal; and re-measures overhead cumulatively, per sensor, against a budget, with an agent-heavy route (executor fan-out, file reads, environment reads) on Spring MVC and Quarkus, run back to back with and without the agent in one session, since the §2.2 route exercises none of what the sensors instrument.

Rules for the bridge and advice, since the bridge runs inside advised java.base methods, possibly while java.lang.invoke itself is bootstrapping: no lambdas, method references, invokedynamic string concatenation (compile with -XDstringConcat=inline), VarHandle, or synchronized (which pins virtual threads); a per-thread re-entrancy guard that never calls ThreadLocal.set; class names, never Class objects, in any status or listener; advice on hot JDK methods inlined as a single static call into a bridge method (delegation through the bootstrap bridge, since Byte Buddy's inline = false needs the advice class itself visible to the bootstrap loader), so a JDK method grows by a few bytes and never past the JIT's inlining limits; suppress = Throwable.class on every advice, timing advice included.

M5-0, second pass (✅ done, 2026-10-03; spike code kept outside the repository): the identity-preserving prototype against wrapping, with a foreign wrapper and virtual threads; JMH of both mechanisms; the claim's timing; coexistence in both agent orders; an agent-rooted heap-walk leak test with mutations; and both packaging candidates. Its results, the two defects it found, and the limits it accepted are in §5.13, M5-0 spike, second pass; the decisions are D32 and D33.

M5-1 — Agent foundation and the Java Agent panel (18–22 days, re-estimated; the transport ring moves to M5-3 and self-attach after M5-4, both per the plan review):

1. Modules bootui-agent-bridge (Java 17, JDK types only, no dependency) and bootui-agent (Byte Buddy relocated under io.github.jdubois.bootui.agent.shaded, packaged per D33), with an enforcer rule or architecture test that neither depends on Spring, Quarkus, or the engine. Only bootui-agent is published; the bridge ships inside it, so no application classpath carries a child-first copy. Publishing changes the release machinery, so the release workflow, check-release-integrity.sh, and the published-artifact list move together through the bootui-release agent's process, never as a release.
2. The bridge: a VERSION constant; one immutable claim record (generation, token, configuration, capture and reopen held through WeakReference, with the engine's AgentClaim holding the only strong reference) in a single volatile field, replaced by compare-and-set; a token-checked release; first claimant wins, except that a claim whose weak references were cleared is abandoned and taken over, and a dev application takes over from a test application, so a test-context cache, Quarkus continuous testing, or a failed DevTools refresh never locks the application out; counters per thread or as LongAdders; Instrumentation kept inside the agent.
3. The agent, in D33's layout: premain and agentmain behind the launcher, which catches Throwable, checks the bridge's loader is the bootstrap loader, keeps a second agent dormant with a status (reading a version mismatch from the -javaagent jars' manifests, since the first jar's launcher runs for every one of them), and installs nothing until claimed. On the first claim, one resettable AgentBuilder with DECORATE, batches of 64 split down to one class, and a redefinition listener that names each class still failing and reports an unsupported class-file version (each new JDK needs a BootUI release, as Byte Buddy is relocated); matchers that read the current claim, so a changed package list applies to classes loaded later; the installed flag set before retransformation, which runs off the startup thread, is cancelled on release, and reports its completion; the ignore list of §5.13.
4. D34's claim lifecycle: claimed as early as each adapter can (below), armed across DevTools restarts and Quarkus live reloads so reloaded classes are transformed as they load, with recording off between a run's end and the next claim, and fully released, with matchers matching nothing, when BootUI is disabled or the JVM exits.
5. The engine package javaagent (the name agent is taken by the Copilot sessions): AgentClaim, which finds the bridge with Class.forName(name, false, null) and calls it through method handles, catching LinkageError; AgentStatus; and bootui.agent.* properties on Spring and Quarkus, in PROPERTIES.md.
6. Adapters: Spring claims from an EnvironmentPostProcessor once BootUI's activation is resolved, passing the main application class's packages and the properties, and refines the claim with bean classes when the context is refreshed; it also disarms from destroy as well as on context close, and releases, with no token, when BootUI resolves to disabled (D34). Quarkus claims from a STATIC_INIT recorder in dev and test launch modes, passing the application archive's packages, and refines it on StartupEvent. The dependency catalog and SBOM views recognize the agent jar.
7. The Java Agent panel (java-agent, Developer tools, always available): status, versions, JDK, load mode, the claim (armed, recording, abandoned, or held by another application), sensors with their classes, exclusions, and failures, the claim's and each retransformation's cost, and the setup snippets of §5.13 and D23 for the build tool detected, with Copy. GET {api}/java-agent on all three stacks, its contract-catalog entry, get_agent_status (NONE) and bootui agent status, the e2e panel lists, and the documentation pages.
8. Tests: bridge unit tests (two claimants, an abandoned claim taken over after GC, dev over test, stale generations, release races); forked-JVM tests that a dormant agent installs nothing, that BootUI disabled or a Quarkus production build installs nothing, that a misplaced, duplicate, or mismatched agent never aborts the JVM, and that a failing advice never reaches the application; the second pass's heap-walk test in CI; and a CI job running the sample apps' browser suites with the agent beside the OpenTelemetry agent and JaCoCo, on JDK 17, 21, and the newest.
9. Acceptance items carried from the M5-0 reviews (the M5-1 design review moved those that need executor hooks to M5-2, those that need a sensor on application classes to M5-3, and startup reads to M5-5, as marked):
   • D32's snapshot map: counted entries with sticky ambiguity, with the "A, B, run, C" and "A, A, run, B" behaviors, and a unit test that a payload holding a Class, a collection, or a nested array is refused (M5-2, with the map);
   • the bootstrap-only fallback type pool under OpenTelemetry with timing advice on application packages: 0 failed transformations, and no class loaded by the fallback outside the bootstrap loader (done in M5-1a, with the diagnostic probe);
   • the version-gated privileged install, and every agent thread (off-thread retransformation, the self-test) created inside it, daemon, with a null context class loader, and terminating; the leak test run with both on JDK 17 and 21 (done in M5-1a);
   • the leak test's roots extended to every instance of an agent class, Instrumentation's transformer list, agent threads, and agent ThreadLocal values; JVM-wide threads (the common pool, DelayScheduler, Delayer) carrying no BootUI correlation after each restart (M5-2); every mutation caught on every JDK in the matrix; a real DevTools restart through the adapter's claim; and a minimal Quarkus application with a sentinel and mutations (agent classes, instances, and threads as roots, done in M5-1a; agent ThreadLocal values still to add);
   • overhead: an unowned submission against a populated map, the cost after release, virtual-thread park and unpark throughput, and the eight-producer case profiled (JFR lock events, -prof gc) with producers plus workers within the core count (M5-2);
   • a behavioral self-test per hook and per JDK, reporting whether each hook fired; JDK 22 to 25 run in CI or report "unsupported" (M5-2);
   • two agent jars of different versions, with a correct status (done in M5-1a);
   • pools whose workers started before the claim reported in the panel (M5-2); Spring PetClinic's retransformation against §8's one-second target (M5-3); the early claim's timing (M5-1) and the startup hits and environment reads it sees (M5-5); IntelliJ's debugger agent in both orders and HotSwap, and Mockito's inline mock maker beside the agent (M5-1); Mockito spying a claimed ThreadPoolExecutor (M5-2); and the agent/engine protocol version, distinct from the jar version (done in M5-1a).

M5-2 — Executor propagation and work after the response (8–10 days). The design review (Claude Opus 5.5) split it into M5-2a, the agent's executors sensor; M5-2b, the engine, adapters, panel, and observation; and M5-2c, a separate threads sensor for Thread.start and virtual-thread starts, kept apart because java.lang.Thread is the riskiest class to retransform (keyed at start entry and released on failure, applied only by member substitution in Thread.run on 17 and Thread.runWith on 21 and later, never by advice, so scoped-value bindings keep their frame slot; never keyed inside ThreadPoolExecutor.addWorker or a fork/join worker's creation, so a pool worker never inherits its creator's request). Parallel-stream subtasks run by other workers stay unowned: only root submissions and fork() from non-workers are keyed. As delivered, M5-2c keys a thread, platform or virtual, only when the first caller of start() outside the JDK is in the claimed packages, looked up with a StackWalker only inside owned work; this replaces step 1's task-class rule below, which an application lambda passed to a library's thread factory defeated.

As delivered, M5-2b distinguishes task-body completion from the full handoff lifetime: a plain Runnable is marked at its return, and a confirmed JDK result marker runs before publication releases waiters. An explicitly early-published JDK body is instead marked at its later return, including fork/join bodies whose exec() returns false; external completion and cancellation do not invent a body marker. A raw promise-signalling runnable keeps its own return boundary, including its synchronous completion callbacks, not the hidden future's publication. An early failure's outcome retains its own response ordering. work-after-response keeps earlier I/O as evidence when that body ends after the response. Fast tasks starting after the response use the actual response boundary, never a boundary recovered from their own lifetime. Result-publication tails still count by their late I/O; without a confirmed body marker, earlier I/O followed only by computation remains indistinguishable from handoff-close bookkeeping (Java Agent, follow-up to #1218).

1. The D32 mechanism, on D32's key and apply points (ThreadPoolExecutor's addWorker and workQueue.offer, ScheduledThreadPoolExecutor.delayedExecute for one-shot tasks, a periodic task not propagated and marked as such), extended to the JDK 25 and later ForkJoinPool delayed tasks, fork() and invokeAll from threads that are not the pool's workers, and root submissions to a ForkJoinPool from threads that are not its workers (so a parallel stream is one child execution per worker and request, not one per subtask, and work-stealing or invoke on the caller's thread opens nothing), ThreadPerTaskExecutor (virtual threads, and CompletableFuture when parallelism is below 2), virtual-thread starts, and Thread.start when the Runnable or the Thread subclass is in the claimed packages, read from Thread.target on JDK 17 and Thread.holder.task on JDK 21 and later. Library threads started lazily inside a request (a pool filler, a client's I/O thread, an asynchronous appender) and the virtual-thread scheduler's own tasks are never propagated. A child execution is capped in duration.
2. Already-propagating work is detected by name, from strings in the claim's configuration: wrapper classes (M4-15's decorator, Micrometer's ContextPropagatingTaskDecorator), executor classes and thread names (Reactor's schedulers, Vert.x's workers), plus a check at reopen that the same request is not already open on the thread. Snapshots carry the claim's generation and JDK types only (D32), a stale one is never reopened, and the map is never cleared, since the claim stays armed across restarts (D34). A propagated task is attributed but not metered as its own segment (D32's metering policy).
3. Each handoff a child execution of its own, linked to the submitting request: an ASYNC_HANDOFF event with its start, end, thread, and outcome, and after response when it was still running once the request's response was committed (§5.1's phases). Work that ends after its request was profiled attaches late, within a bound, in ExecutionProfileAssembler and the Live Activity feed.
4. The PROPAGATED tier after REQUEST_ID in ExecutionProfileAssembler; handoffs nested in Live Activity and the request profile with an after response badge; work-after-response (§5.17) with a seed and a counterexample.
5. The correlation scenario's executor route: 100 % of its statements owned with the PROPAGATED tier with the agent, unowned without; regression tests for every behavior of the second pass's step 1, with -XX:ActiveProcessorCount=2, and with virtual threads on JDK 21.

M5-3 — Code Inventory: executed and changed methods, dependency use (10–12 days):

1. The transport ring, with this first consumer: per-thread buffers of fixed-size records of longs and interned string ids, flushed when a request's scope closes and when the dispatcher drains, published to a bounded multi-producer ring in the bridge; a bounded intern table that drops and counts overflow; drops counted per sensor; the §5.2 dispatcher drains it as the agent.<sensor> journal sources. Virtual threads write straight to the ring rather than to a buffer of their own.
2. The inventory sensor: method ids keyed by class, name, and descriptor, so HotSwap and restarts do not grow them, with a hit flag per method in bridge-held arrays (advice cannot add fields under DECORATE); a method's first call records its id, request, and route, and later calls cost one array read. With D34's early claim, startup's first hits are seen.
3. Method hashes over resolved, symbolic instructions without debug attributes, never raw constant-pool bytes, so a class hashed at load and at retransformation, or with OpenTelemetry's or JaCoCo's transformations present, hashes the same (a test asserts it); each class's method set, kept per run as a long[] of (method key, hash) pairs in the run history, within 1 MB; changed, added, and removed methods after a DevTools restart or a Quarkus live reload, with no git repository needed.
4. Dependency use from each loaded class's code source: classes loaded per jar, at startup or later, and the first route that loaded one; a jar with none is not loaded in this run, never unused.
5. The Code Inventory panel and its API, get_code_inventory and bootui code inventory, changed-code-not-executed ("your change has not run yet"), and verify_after_change starting from get_code_inventory with changed.
6. Acceptance: one edited method of the sample app listed as changed, executed or not according to the requests sent; a seeded never-called method; a declared but never-loaded jar.

M5-4 — Code Paths: component-boundary timing and route trees (12–15 days):

1. The code-paths sensor on the public and protected methods of application bean classes and of call-site classes, writing enter and exit marks to a per-thread shadow stack; adaptive exclusion (more than 50,000 calls a second under 2 µs each) decided at method entry, so enter and exit stay balanced, through a per-method flag in the bridge.
2. The engine's request tree (512 nodes, depth 32, an Other node, overlapping children unioned), flushed once when the request's scope closes as a CODE_PATH event; property-based tests for the merge, the union, and the exclusion.
3. SQL, REST client, cache, and AI events stamped with the innermost open instrumented method, read from the shadow stack when they are recorded, an exact join by stack.
4. Route trees per route and run (2,000 nodes, an Other bucket, a histogram per node), invokes edges between beans in the runtime model, with the ReverseClosure allowlist decided explicitly.
5. Blocking handlers only: on WebFlux, reactive Quarkus endpoints, and asynchronous servlets, a shadow stack times the pipeline's assembly, not its execution, and the scope closes on another thread, so their trees are marked assembly only and kept out of route-time-breakdown's handler split.
6. The Code Paths panel (routes, the tree with SQL, REST, cache, and AI children, callers, and Beans at runtime), its API, get_code_paths and bootui code paths, route-time-breakdown's handler split, and repeated-selects naming the issuing method; the seeded slow blocking route names its slowest method within 5 % of the handler phase.

M5-5 — Side Effects (16–20 days, first planned as three pull requests and split into seven by D37: a shared sensor base, then one per sensor group, each preceded by a check that Byte Buddy retransforms its JDK classes on JDK 17, 21, and the newest, with delegating advice on every hot JDK target). The seven pull requests are a shared sensor base (exclusions, aggregation, drop counters, coverage, and a switch per sensor), then network, blocking, files with environment, processes with thread activity, thread-locals, and resources; the items below describe what each group records, and their observations ship as Side Effects rows first (D36):

1. network and blocking: connects and lookups with the client recognized from frames and not captured by any panel when no event matches; blocking calls started on an adapter-identified event loop, reported, never thrown; hidden-outbound-calls, and event-loop-blocking extended beyond JDBC. Thread.sleep and Object.wait are native on JDK 17 and cannot be advised there without adding methods, which retransformation forbids: on JDK 17 they are recorded at their call sites in application classes only, and the panel states the gap.
2. files, processes, and environment: normalized path patterns, command file names, and variable names, never contents, arguments, or values; with D34's early claim, environment reads at startup are seen.
3. threads, thread-locals, and resources: threads and executors per route; thread locals left set on pooled platform threads, found by scanning the thread's ThreadLocalMap when the request's scope closes rather than by advising ThreadLocal.set, excluding BootUI's own and the agent's thread locals, a null value counting as cleared; resources a request or a job opened left open past the request, and reclaimed without close(), through weak references the drain thread polls, registered only for resources a request or a job opened (D46); thread-local-left-set, resource-not-closed, and threads-per-request.
4. Each: engine normalization and aggregation, model nodes and edges (§5.16), the Side Effects tab, a seed and a counterexample per sensor, a per-sensor overhead budget (D37 keeps thread-locals, resources, and environment opt-in until theirs is measured; D47 turned resources on by default once its A/B passed), and get_side_effects and bootui side-effects with the first pull request.

M5-6 — Caught exceptions and security sinks (10–12 days):

1. CAUGHT_EXCEPTION from exception-handler entry in application classes, through a Byte Buddy ASM visitor on handler labels, since advice cannot hook catch blocks, computing maximum stack sizes only, since recomputing frames loads classes inside the transformer; catch-any, finally, and synthetic handlers skipped. The caught type, the catch site, and whether it was rethrown or logged at WARN or above, matched by the identity of the exception and its chain against log and reported-exception events, whatever request they carry; exceptions-caught-in-code, and evidence (e) of errors-behind-2xx.
2. The security-sinks sensor, opt-in (D37): request parameter values of at least 4 characters, held in a request-bound value holder reviewed before any sink is instrumented, never copied into executor snapshots or kept past the response, with caps on their count, length, and matching work, compared at a sink and never stored; deserialization without an ObjectInputFilter; weak algorithms requested by application frames; trust managers and hostname verifiers installed by application code; request-input-in-sink, worded as a fact, with a concatenating route and a parameterized counterexample.

M5-7 — Change impact by method and comparison led by code changes (6–8 days, in two parts since D37). M5-7a: change impact accepts a method, and its observed routes become those whose requests executed the changed code, read from route-specific trees, never from global invokes edges composed across requests, structural reach staying a separate count; late fragments amend their route's aggregates or mark them partial; run comparison leads with changed, added, and removed methods, executed or not and where, and boundary methods no longer executed on routes exercised in both runs. M5-7b, after the relevant M5-5 groups: new hosts, file patterns, processes, and variables in the comparison.

M5-8 — Method probes (8–10 days): a probe retransforms one method on demand through the resettable transformer and restores it when it ends; its bound (20 invocations or 60 seconds, five probes at most, ending with the run) is enforced in the advice through a per-probe flag and counter in the bridge, so it holds even if restoring fails; metadata first (invocations, durations, outcomes, and request ids), shipped with its approval guidance (D37); argument and return shapes later, from an allowlist of safe types and never through an arbitrary toString(), opt-in per probe, by the live exposure (D44: none under METADATA_ONLY, value-derived details under FULL only), and never returned to MCP or the CLI; blocked by read-only policy; started from a Code Paths node, an exception frame, or a bean; start_method_probe and get_method_probe.

M5-9 — Vulnerable code reach (8–10 days; dynamic access recording cut by D41). M5-9a: the Vulnerabilities panel's Runtime reach column and filter (NOT_LOADED, LOADED, AFFECTED_CLASS_LOADED), with scores, severities, and Scorecard penalties identical with the agent on and off, once the inventory keeps bounded class-name evidence and advisories are normalized to symbols; an unknown reach never reads as NOT_LOADED. M5-9b, dynamic access recording for the GraalVM panel, was cut after its spike (D41).

M5-10 — Agent tools, prompts, benchmark, and documentation (5–7 days): the remaining tools of §5.17 with their CLI commands and manifest, diagnose_runtime_issue suggesting get_code_paths and wording reach and verbatim-match facts as checks rather than vulnerability verdicts, verify_after_change naming start_method_probe as its next step when the test still did not execute the edited method, McpGuidance.instructions adding get_agent_status as a check before relying on an agent-only tool, assess_application naming start_method_probe among the tools needing separate approval, the scripted investigation "did my change to OrderService run?" and a refusal fixture against misreading NOT_APPLICABLE: requires the BootUI agent as healthy, both in the §2.2 benchmark, the consumer skill (and its Claude Code plugin mirror) documenting the verify-then-probe workflow, AI-AGENTS.md, a setup page for the agent, and a final pass that every §5.1–§5.12 acceptance criterion still holds with the agent detached. Self-attach is revisited here, after M5-4: jdk.attach.allowAttachSelf is read once at JVM start and a late attach always pays a full retransformation, so it adds little over the -javaagent line.

Critical path: the second pass, then M5-1, then M5-2 and M5-3 in either order, then M5-4, then M5-7 and M5-8; M5-5 and M5-6 follow M5-3 (the transport ring), and M5-9 follows M5-3. M5-10 follows M5-6, M5-8, and M5-9, since its prompt and skill updates name start_method_probe, request-input-in-sink, and vulnerable code reach. Before 2.0.0 (D20), the target is M5-0 to M5-3. With the review's re-estimates, M5 comes to about 111–140 engineer-days.

The remaining-plan audit of 2026-10-04 (Appendix A) reordered what follows M5-4b, beside M4 (D38). M5-4c shipped before the planned M5-1 open checks, M5-11, and M5-12; those remain. M5-1's open checks include the nested SpringApplication that releases the main run's claim, Quarkus's report reading the build-time bootui.agent.enabled, the GraalVM scan listing the agent jar, and the leak tests through a real DevTools restart and Quarkus live reload. M5-11 and M5-12 follow to align the evidence contract and acceptance matrix with the shipped stamps: one owner submitting the same task from two methods has no single submitter, and a stamp is captured where the operation starts. M5-5 to M5-9 then follow as D37 reshapes them: M5-7a builds on M5-4c, M5-7b after the relevant M5-5 groups; M5-9b is cut (D41). M5-11 and M5-12 bring M5 to about 118–152 engineer-days.

graph LR
  W0["v1 3.27 Log exposure"] --> M2
  W1a["v1 3.20a Shared assembler"] --> M1
  W1b["v1 3.24a Retention"] --> M1
  W1c["v1 3.22 Route rankings"] --> M2
  M0["M0 Readiness"] --> M1["M1 Exact correlation"]
  M1 --> M2["M2 Journal and Live Activity"]
  M2 --> M3["M3 Runtime Insights"]
  W2a["v1 3.25 Agent profiles"] --> M3
  M3 --> M4["M4 Change loop"]
  W2b["v1 3.18 Data access map"] --> M4
  M4 --> R["2.0.0"]
  M3 --> M5["M5 BootUI Java agent"]
  M4 -.change loop upgrades.-> M5
  M5 -.slices ready by then.-> R

4.2 Branch strategy

• v2 is a shared, long-lived branch created from main. It is never rebased or force-pushed.

• main keeps the 1.x line and the v1 plan. main is merged into v2 at least weekly and after every 1.x release, with merge commits, so v1 fixes and foundations reach v2 continuously.

• Before starting any new v2 work, sync first:

  1. merge the latest main into v2 and resolve conflicts;
  2. review what changed in PLAN.md and in the v1 items this plan depends on (§3);
  3. update this plan when those changes affect it, in its own documentation commit, before the work begins.

  Examples include a shipped or reordered wave, a changed v1 specification, a new shared helper, or a new cross-cutting rule.

• v2 pull requests target v2, stay small, and pass the same gates as main pull requests (§9, §11).

• M0-1 extends .github/workflows/build.yml push and pull-request filters to v2, so the full build, conformance runners, and browser suites run on every v2 change.

• Existing 1.x bugs found by this work are fixed on main as 1.x patches, not held for 2.0 (D8). Both found so far are fixed and merged into v2: Live Activity persistence on MySQL and Oracle (#1144), and call sites in the sample apps (#1143).

4.3 Releases

• Nothing is published from v2 before 2.0.0, a maintainer decision (D5). The release workflow accepts only major.minor.patch versions, so there are no preview coordinates on Maven Central.
• When M4 meets its gates, v2 is merged into main and 2.0.0 is released from main.
• Before 2.0.0, the release path must allow later 1.x patches. release.yml computes the next version from the newest stable tag in the whole repository, so after v2.0.0 a 1.x patch would be rejected, and every release redeploys the documentation site at its tag. M4 changes both, in lockstep with .github/scripts/check-release-integrity.sh:
  • compute the next version within the source branch's major version;
  • redeploy documentation only when the release is the newest major.
• 2.0.0 removes what 1.x deprecates, each with a migration note in CHANGELOG.md (✅ M4-16):
  • TraceIdProvider, replaced by CorrelationContextProvider (§5.1);
  • the Live Activity poller, replaced by the journal subscriber (§5.3).
• Java 17, Spring Boot 4, and the newest Quarkus LTS remain the baselines.
• Merging v2 into main must not publish the 2.0 documentation before the signed 2.0.0 tag and its Maven Central artifacts exist: pages.yml deploys on every push to main, so M4-23 guards that trigger and rehearses the merge on a non-publishing candidate.
• A 1.x maintenance branch is cut from main's last 1.x commit before v2 merges, and later 1.x fixes and patch releases target it (D40, M4-23).
• The release sign-off in the validation report records each §2.2 measure against its target, the per-kind gates, and every exception; "done" is not "passed" (M4-23).

5. Feature specifications

5.1 Exact correlation — Cross-cutting ✅ Delivered

Every runtime event should know, when it happens, which request, trace, span, and run it belongs to, with or without tracing. Before M1, the Spring MVC exchange's trace id was re-derived by HttpExchangeTraceRegistry.match (method and path, ±50 ms, unique candidate only), exceptions and security events on Spring MVC carried no trace id, and no stack had a request identity that worked without tracing. M1 delivered it (§1.1 has the measurements). Adding fields is the easy part; propagating the context across thread, Reactor, and Vert.x boundaries is the critical engineering problem.

Scope:

• Add CorrelationContext to the engine: a BootUI-generated requestId, traceId, spanId, routeTemplate, handler, an optional transactionId context slot (not populated by the current transaction listener), an optional dataSource context slot (the JDBC proxy instead stamps its named pool directly on SQL), an executionId for scheduled and consumed-message anchors.
• Add a CorrelationContextProvider SPI that replaces TraceIdProvider, and a scope-based holder that always restores the previous context. 1.x adapters keep TraceIdProvider as a fallback until 2.0.0 removes it.
• Stamp the context at the existing capture points of exchanges, SQL, transactions, exceptions, security events, REST client calls, cache accesses, logs, scheduled runs, Kafka, RabbitMQ, JMS, email, fault tolerance, and AI calls.
• Record exception occurrences as immutable events with their own identity, not the updated exception group.
• Snapshot the context before a message send and read producer metadata in the send callback. On consume, open a child context from traceparent when present. Metadata only, never payloads.
• Add a REQUEST_ID tier ahead of §3.20's tiers in the shared profile assembler.
• Add a run identity per application-context start, so a DevTools restart or Quarkus live reload starts a new run inside the same JVM, and publish instanceId and runId in /overview metadata.
• Add nullable, additive requestId fields (and spanId, transactionId, dataSource, thread where missing) to the affected DTOs, each with a secondary constructor matching today's canonical one.
• Record the thread kind of every event (pooled worker, virtual thread, Reactor Netty or Vert.x event loop, Reactor scheduler, or other), classified by the adapter that owns the thread rather than guessed from its name later. For an operation, record the kind of the thread it started on, not the one it completed on.
• Record request phase markers in the context: handler dispatch and handler return, and the start of response writing and view rendering. Spring MVC uses HandlerInterceptor and ResponseBodyAdvice, and Quarkus JAX-RS filters and a WriterInterceptor. WebFlux marks neither: its correlation filter begins the request's marker timeline before the chain is assembled and ends it when the chain terminates, including cancellation, so what is observed about the request is recorded while its handler and response phases stay unknown rather than guessed. Where Spring Security's authentication observation is active, an ObservationHandler records the authentication interval, as ScheduledTaskRunObservationHandler already does for scheduled runs.
• Record the Spring for GraphQL operation type and name from its graphql.request observation, so each operation is a route of its own.
• Keep the port in Live Activity REST client summaries, so two local services on different ports stay distinct.

Architecture:

• Spring MVC. RequestCorrelationFilter opens the scope before chain.doFilter and fills the route template and handler after routing. Async dispatch reopens the scope from a request attribute and closes it on completion, timeout, error, and cancellation. The exchange is stamped in §3.24a's BootUI-owned HttpExchangeRepository, whose add Actuator's HttpExchangesFilter calls synchronously on the request thread after doFilter (verified on Spring Boot 4.1.1). An application-provided repository is never wrapped: its exchanges keep the registry match and report their tier.
• Spring WebFlux. A BootUI WebFilter creates the request's CorrelationContext, stores it on the ServerWebExchange, writes it into the Reactor context, and exposes it through a Micrometer ThreadLocalAccessor backed by BootUI's scoped holder. BootUI contributes spring.reactor.context-propagation=auto as an overridable default whenever exact correlation is on, not only when OpenTelemetry is present as today, so blocking JDBC, cache, logging, and transaction callbacks read the request id synchronously. The BootUI-owned HttpExchangeRepository reads it in add, which Spring Boot 4.1.1's HttpExchangesWebFilter calls inside beforeCommit. An application-provided repository is not wrapped and keeps its fallback tier. Work outside Reactor and Spring-managed execution stays unowned, never guessed.
• Quarkus. QuarkusHttpExchangeCaptureFilter owns exchange capture, so it stamps the exchange directly, stores the context on the Vert.x RoutingContext, and restores it around worker dispatch and Mutiny hops it controls.
• Transactions. BootUiTransactionExecutionListener tracks nested blocking PlatformTransactionManager transactions on the invoking thread, including those run by WebFlux applications. It records each completed transaction with its request or execution id; SQL events do not carry a transaction id, so statement membership is inferred from recorded transaction intervals on that thread, not captured as an exact identity. R2DBC and Quarkus transactions stay unavailable.
• Every adapter keeps optional types (OpenTelemetry, messaging, security) in gated classes.

Out of scope:

• Generating, replacing, or propagating correlation headers on behalf of the application.
• @Async, CompletableFuture, and executor instrumentation. Work on unwrapped executors stays visible as unowned work (§5.5), with the TaskDecorator the application can add. The optional BootUI agent propagates the context through executors (§5.13).

Baseline (M0-2). AbstractCorrelationCoverageTest in bootui-conformance runs on all three stacks. It reads only the public Live Activity feed and writes its report to target/correlation-coverage/. Besides the table in §1.1, it found:

• Exchange ids collide. HttpExchangesService hashes an exchange's millisecond timestamp, method, displayed URI, status, and duration into its id, so identical requests that start in the same millisecond and take as long share an id, and their profiles become ambiguous. The scenario observed it on Spring MVC and Spring WebFlux. M1 gives each request its own identity.
• Exceptions appear once per group. Live Activity shows one EXCEPTION row per exception group, dated by its last occurrence, so repeated failures of one route nest at most once. M1 records immutable occurrences.
• since is ignored on Quarkus without persistence, while Spring honors it. The scenario filters by window itself.
• Tracing could not be switched off with management.tracing.enabled=false in a Spring Boot 4 test, so the tracing-off baseline moves to M1, together with the secured, Kafka, and raw-executor routes.

Acceptance criteria:

• The correlation scenario, extended with tracing off, Kafka sends, and a raw executor, enforces the §2.2 target as its floors on Spring MVC and Quarkus in every phase, and WebFlux reports its measured coverage.
• Contexts never leak between requests on reused platform threads, virtual threads, Reactor schedulers, or Vert.x worker hops, including after async timeouts and cancellations.
• A DevTools restart and a Quarkus live reload each produce a new runId.
• Every new DTO field is nullable and additive, and BootUiApiContractCatalog and the three conformance runners pass.
• The request profiler no longer marks request-thread work approximate.

Delivery slices, each one pull request to v2 with its own tests and documentation:

5.2 Runtime journal — Diagnostics ✅ Delivered

Each panel keeps its own ring buffer, and Live Activity persistence polls a 200-entry merged window, so bursts lose events. This item records every runtime event once in a push-based, bounded, in-memory journal, and maintains the aggregates that observations read.

Scope:

• A RuntimeEvent envelope: instance, run, sequence, stable event id, type, time, duration, request, execution, trace, span, thread, and correlation tier, with a small immutable payload per prioritized source (HTTP, SQL, transaction, exception occurrence, security, REST client, cache, messaging, scheduled run, and log).
• A RuntimeEventSink called right after each recorder's existing ring-buffer write, through a non-blocking offer into a bounded queue drained by one bootui-journal-dispatch daemon thread. On overflow the event is dropped and counted per source; the application thread never blocks.
• Incremental aggregates maintained by the dispatcher, before any eviction: per route (count, status classes, latency histogram, time split), per statement fingerprint (count, time, N+1 groups, call sites), per exception group and route, per transactional method, per thread family without a request, and per run. Every aggregate has a cardinality cap with an overflow bucket.
• Evidence rows: the retained events, bounded by max-events (50,000) and max-bytes (the smaller of 32 MB and 5 % of the maximum heap), with §3.24's reserved share for failed and slow events. Aggregates, not retained rows, feed percentiles.
• Run summaries: a bounded (≤ 256 KB) summary of each run's aggregates, kept across application-context restarts in the same JVM (§5.8).
• Self-exclusion of BootUI's threads, paths, and JDBC (BootUiJdbcCaptureGuard), including BootUI's own PostgreSQL, MySQL, and Database Advisor reads.
• A journal status block (events, bytes, drops per source, evictions, oldest retained event) in Live Activity's persistence disclosure, and a confirmation-gated Clear recording action that read-only policy blocks.
• Per-request CPU time, allocated bytes, and GC pauses, measured by §5.11's scope readings: summed over every segment a request runs on a thread, including thread hops, and unavailable, with the reason, on virtual threads.
• Connection checkout and release timestamps and the pool of each logical connection, from the JDBC proxy, which already intercepts getConnection, so connection wait, connection holding, and connections per request are measured.
• Up to four interned application frames per SQL, REST client, and cache event, with their method types, where 1.x keeps one call site.
• For framework loggers, the unformatted message template of each WARN and ERROR event, so warnings group exactly without storing their arguments.
• Properties under bootui.runtime-journal.*: enabled, max-events, max-bytes, queue-capacity, and sources, which also accepts gc and resources (§5.11).

Architecture:

• The journal is a sibling SPI to ActivityStore in a new journal engine package. It reuses sequencing, instance ids, and the capture guard.
• Sequences are unique per (instanceId, runId), so a restart never collides with a previous run.
• The dispatcher owns aggregation, so the application thread only snapshots, allocates the envelope, and offers.

Storage design decisions (settled before M2; defaults are properties unless noted):

Out of scope for 2.0:

• A JDBC event journal. Live Activity persistence keeps its existing bootui_activity table, now fed by a journal subscriber instead of the poller (§5.3). A durable event store is revisited only on demand (§5.10).
• Payloads of messages, request bodies, bind values, and email bodies, subjects, or recipients.

Acceptance criteria:

• The PoC scenario (767 requests in about 22 s) records every event with zero drops at default settings on all three stacks.
• A burst beyond the queue drops and reports the drops, and a test proves request latency is unaffected by a stalled dispatcher.
• Aggregates reconcile with every event published, including events evicted from the retained rows.
• BootUI's own traffic and SQL never enter the journal.

Delivery slices for M2, which covers this item, §5.3, and §5.11's scope readings, GC by id, CPU ledger, and resource track. Each slice is one pull request to v2 with its own tests and documentation:

5.3 Live Activity on the journal — Home ✅ Delivered

Live Activity is where developers already connect events, and where the missing links show. This item serves it from the journal and extends its request profile, behind parity tests, before the poller is retired.

Scope:

• Serve the Live Activity feed, Live Flow, and SSE stream from the journal. Live Activity persistence writes the existing bootui_activity rows from a journal subscriber, so bursts are no longer lost and no table changes. The subscriber never writes rows less masked than MASKED (§8).
• Nest children by REQUEST_ID first, then §3.20's tiers, so request-thread SQL, security, cache, exception, log, and Kafka rows sit under their request.
• Add transaction, log, and AI call rows on the stacks that capture them. AI calls, which carry only their span's trace id, nest under the request recorded with it whose time span contains their start (M2-8e3).
• Add filters for route template, run, and request id, and show work with no request under a No request filter, with its thread family and reason.
• Extend the request profile, additively, with:
  • a unified timeline of spans, SQL, transactions, cache accesses, and log lines on one axis, with a GC lane naming the collections that completed during the request (§5.11);
  • a route comparison: this request against its route's p50 and p95 from the aggregates;
  • touched resources: tables, transactions, caches, messages, and log lines;
  • why this route is slow: the route's route-time-breakdown observation when it exists (§5.5).

Architecture:

• LiveActivityAssembler keeps its severity and KPI logic and reads journal events instead of polling buffers.
• Route comparison reuses §3.22's percentile helper over the journal's histograms.
• The poller path remains available until parity passes on all three stacks, and 2.0.0 removes it.

Acceptance criteria:

• Parity tests on the same fixture cover KPIs, ordering, SSE, clear and toggle behavior, profiles, and disabled sources, against the 1.x feed.
• Existing Live Activity API consumers keep working: DTO changes are additive.

5.4 Runtime projections and runtime model — Engine ✅ Delivered

Observations need joins across sources. With exact keys, those joins are lookups in the journal's aggregates and small indexes, so this item replaces the draft's general graph engine with bounded projections and one small typed graph.

Scope:

• Per-request, per-route, per-table, and per-bean indexes over retained events, maintained by the dispatcher. As delivered (M3-5), the per-route aggregates are maintained by the dispatcher, while the runtime model and the per-request and per-table joins are built on read from the retained events within the read budget below.
• Structure from existing providers only: mappings, beans and their dependencies, repositories, and ArC injection edges on Quarkus. Snapshot the structure per run, so an observation never joins one run's events with another run's mappings or beans.
• Table references from §3.18's extraction, computed once per statement fingerprint on the dispatcher, never on the capture path. As delivered (M2-8e4), fingerprints and tables are computed once per distinct statement by a bounded cache (SqlShapes, 4,096 statements and about 1 MiB, cleared by Clear recording and after a run's last events) shared by the aggregates, the model, the request profile, and the observations, on read or on the dispatcher, never on capture.
• A runtime model: typed nodes (route, GraphQL operation, scheduled job, bean, repository, table, cache, outbound host, topic or queue, AI model, and exception group) and typed edges (depends on, handled by, reads, writes, calls, publishes, consumes, and raises). Each edge carries per-run counts, first and last seen, and its provenance: declared by structure, observed in an owned execution, or inferred from shared access to a resource. The dispatcher builds it from the aggregates, within the cardinality caps and the byte budget: about 5,000 nodes and 30,000 edges at most. As delivered (M3-5), the model is not maintained by the dispatcher: RuntimeModelProjection builds it on read from the retained events within the 250 ms read budget, returning a partial model when it stops early. Its observed SQL write edges name only confidently identified DML targets, with read-side sources retained as reads; ambiguous lexical write candidates and zero-duration unverified preparations are not asserted as writes or reads, and the retained model names this limitation. Earlier run summaries' table edges cannot be compared after this attribution correction (summary version 11). Observed edge counts and first and last seen therefore cover the evidence window, not the whole run, so change impact (§5.7) reports traffic the window still holds, and run comparison (§5.8) compares run summaries, which outlive the window, rather than two models.
• Three small algorithms with property-based tests: reverse closure over an allowlist of edge types, depth ≤ 5 (change impact); interval unions (timeline breakdowns); and edge-set differences between runs (behavior diff).
• A read budget of 250 ms per projection over a full journal. Exceeding it returns a PARTIAL result with the reason.
• Every join carries its correlation tier, and each observation declares the minimum tier it accepts.

Architecture:

• Structural reach, observed execution, and shared-resource access are never merged into one claim. A path through a shared table means two routes used the same table, never that one read the rows the other wrote.
• The model is an in-memory adjacency structure of interned ids, not a database: it has no query language, and agents reach it only through named tools (§5.6).

Out of scope for 2.0:

• A graph database, graph query languages, community detection, and centrality (§5.10).

Acceptance criteria:

• Projections over 50,000 retained events and full aggregates stay within the read budget on a reference machine, pinned by a tagged, generously margined timed test.
• The PoC evidence, converted into a Java fixture builder, reproduces the PoC's findings that 2.0 keeps.
• A fixture where two routes share only a table never reports a path between their executions.

5.5 Runtime Insights panel — Home ✅ Delivered

A new panel, runtime-insights, titled Runtime Insights, in the Home group directly after Live Activity. It lists the current observations and is reachable from where developers already are.

Scope:

• GET {api}/runtime-insights returns the current observations, projected on read from the journal's aggregates. There is no analyze action, so there is no busy state and no read-only exception.
• GET {api}/runtime-insights/insights/{id} returns one observation's evidence: the top 20 rows, a truncation count, and deep links.
• The report carries its window (runs, time range, events per source, drops, evictions), a correlation coverage breakdown per source, the observations, a Not exercised in this run list of declared routes, and limitations.
• Each observation carries a stable id (kind:subject, surviving refreshes), a status (OBSERVED, INSUFFICIENT, NOT_APPLICABLE, NOT_COMPARABLE, or PARTIAL), one measured sentence, the eligible and affected request counts, the minimum tier used, What to check (one to three imperatives with panel links), at most three exemplar request ids, bounded masked evidence, and limitations. Insufficient evidence names what is missing, for example "GET /api/orders: 2 of 5 requests needed".
• Evidence completeness comes first. Each observation reports the coverage of the sources it reads and their drops. Drops, capture pauses, cardinality overflow, or incomplete correlation make an absence claim PARTIAL. Minimum counts decide when an observation is shown, not how confident it is: a single exact event can establish a fact, and repetition establishes recurrence, never a cause.
• The first request of each route in a run is reported apart as cold (for example "first request 412 ms; warm median 11 ms") and excluded from percentiles.
• A Spring for GraphQL operation is a route of its own: its type and name, from the graphql.request observation, subdivide POST /graphql, so route-level observations stay meaningful for GraphQL applications.
• Observations in M3:

• gc-inflated-latency and heap-growth-after-gc (§5.11) joined these checks in M4-3 (D18).
• Entry points where developers already look:
  • the Live Activity request profile's why this route is slow section (§5.3);
  • a link from Live Activity's slowest-request KPI to its route's observation;
  • the No request filter in Live Activity, which lists work that ran without a request by thread family;
  • command-palette keywords: why slow, slow, what changed, impact, new exceptions, blocking, tokens, open session, connections.
• The UI, following DESIGN.md:
  • the header states the window and What this run did that no single panel shows., with Export offering JSON and Copy for AI (Markdown through §3.25's helper), and no observation count;
  • a correlation coverage strip with text labels, so the reliability of everything below is visible first;
  • a search field by route, table, bean, or thread, then theme chips: time, queries, errors, transactions, framework, AI, security, and change;
  • a master-detail list: observations in sentence-case groups on the left; on the right the sentence, What to check, the evidence table, limits, source-panel links, and the equivalent CLI command. The request timeline is the only chart;
  • empty states for an empty journal, a disabled journal, needs-more-traffic, and partial windows.

┌ Runtime Insights ─────────────── Run 3 · 18,412 events · last 9 min · 0 dropped      [Export ▾] [Copy for AI] ┐
│ What this run did that no single panel shows.                                                                 │
│ Linked by  request id ██████████████████░ 96 %  trace id █ 2 %  background (expected) ░ 1 %  none ░ 1 %       │
├──────────────────────────────┬────────────────────────────────────────────────────────────────────────────────┤
│ Search routes, tables, beans │ GET /api/secure/products spends 96 of 101 ms in authentication                 │
│ [Time] [Queries] [Errors] …  │ 30 warm requests · request id · HTTP Basic re-authenticated 30 of 30 requests  │
│ Time                         │ What to check                                                                  │
│ ▸ /api/secure/products 95 %  │  1. HTTP Basic verifies the password on every call: compare a session or token │
│ Queries                      │  2. Check the password encoder's cost for the dev profile  → Security, Config  │
│   Repeated SELECT, 40 × req  │ Evidence (20 of 30 rows) · Limits · CLI: bootui insights show <id>             │
│ Transactions                 │                                                                                │
│   2 connections per request  │                                                                                │
└──────────────────────────────┴────────────────────────────────────────────────────────────────────────────────┘

Architecture:

• Observations are pure engine classes (id(), minimumTier(), availability(snapshot), project(indexes)), each with fixtures for a justified observation, a plausible counterexample, and insufficient evidence. Unknown never reads as healthy.
• Projections are cached per journal watermark, clear generation, per-source drop counters, panel visibility, SQL capture, and exposure policy, so a drop before the next dispatched event refreshes completeness and a live exposure change never serves a stale, less-masked result. Completeness counts recorded, visible anchors for the kinds of work an observation examines (HTTP, scheduled runs, messaging, and WebSocket handlers), deduplicated with its required and available optional sources; collection and Code Inventory checks count no execution anchors.
• Sentences name what was counted, never a cause, a severity, or a patch. What to check stays conditional ("if these writes must succeed together…").
• Human text and agent text differ. The panel's What to check may suggest a design alternative. The agent payload's verify line only says how to confirm the fact: open one exemplar request, and do not apply a fix from this row alone (§5.6).
• Thin adapters: a Spring MVC controller, a WebFlux controller on boundedElastic where projection work could block, and a Quarkus resource registered in BootUiQuarkusProcessor. Quarkus registers nothing in LaunchMode.NORMAL.
• The panel is available when the journal is enabled, and otherwise unavailable with the property to set.

Out of scope for 2.0:

• Severities, scores, Scorecard contributions, rule catalogs, and free-form query languages.

Acceptance criteria:

• Opening the panel or a profile starts no capture, scan, database read, or network call.
• The demo scenario on each stack, with tracing off, shows the route-time-breakdown observation for the secured route, opens its evidence, and follows a deep link.
• Every observation's unavailable state names its missing capability instead of returning an empty success.
• The sample apps seed one case for every observation, and a counterexample for each that must not fire: a public catalog read, an intentional fallback, an asynchronous client completing on an event loop, and an audit write on GET.

5.6 Runtime Insights for agents — Developer tools ✅ Delivered

Agents need short, stable, diffable facts that can refuse to answer, not a dashboard. Passing raw traces or pass/fail results to agents leads to wrong repairs, so every tool returns compact observations. All tools are read tools on existing McpToolSchema names, which the published CLI binds, and add no schema.

• INSUFFICIENT, NOT_APPLICABLE, NOT_COMPARABLE, and PARTIAL are statuses an agent cannot collapse into success, and an empty list never means "healthy". requests counts completed HTTP exchanges only; zero is not proof nothing ran when an observation names a request or execution, a non-HTTP limitation, or eviction says otherwise. A run-level observation with no exemplar does not. The empty query includes latency rows and omits only an insufficient repeated-selects row under 50 ms that ran fewer than 10 times in any request; a limitation names how many. Since M4-24, the empty query lists only the kinds that passed their external validation or stayed silent on it, and names the kinds of the rows it returns that are not externally validated.
• McpGuidance.diagnose_runtime_issue starts with get_runtime_insights, then one get_request_profile. get_live_activity's description changes to: "Newest events and entry ids only. For why a route is slow, what a reload changed, or what a test run did not exercise, call get_runtime_insights or get_runtime_run_comparison first."
• A new verify_after_change prompt: run the tests, call get_runtime_insights with query=repeated-selects and, since M4-24, query=lazy-sql-after-handler (the default list no longer lists either kind), then get_runtime_run_comparison with previous, and stop. Do not edit from a latency row, and do not treat a missing observation as proof that a behavior is gone.
• A documented analyze after tests workflow: run the application's integration or browser tests, then bootui insights list --json. Tests are where realistic traffic comes from.
• Quarkus Dev MCP registration of these four read tools joins M3 if it is only a registration, so that Quarkus agents discover them where they already look.
• As validated end to end on the Spring MVC sample's seeded run, through MCP and the CLI: a call without limit gets the 8-row default (the dispatcher had replaced it with max-results); past the limit every kind is listed once before any kind twice, so one route-by-table kind cannot hide the others; the list carries the run's HTTP requests and up to 8 notExercised routes; previous selects the newest kept run, even one that served no request, as DevTools leaves when it restarts twice for one change; and the agent comparison lists the kept runs an agent may name instead.

Acceptance criteria:

• Every tool moves in lockstep as PLAN.md §4 requires, and ToolManifestGeneratorTests and mcpToolCatalogIsDocumentedInEveryCanonicalToolList pass.
• A 1.x CLI binary keeps its commands against a 2.0 application; new commands need a 2.x CLI.
• The ten scripted agent investigations in §2.2 pass, and so do five refusal fixtures that an agent fails by editing: H2 against PostgreSQL (NOT_COMPARABLE before any delta), ten-sample p50 jitter below the noise floor, a public catalog read, an intentional fallback behind a 2xx, and virtual-thread CPU reported as unavailable.

5.7 Change impact — Runtime Insights ✅ Delivered

"Is my change safe?" is asked by an agent that just edited a class, so the input is a symbol and the output is a checklist, not a node list.

Scope:

• Resolve a bean name, simple class name, repository name, table, cache, or outbound host to exactly one node of the runtime model (§5.4). Ambiguity returns AMBIGUOUS with candidates, never a guessed closure.
• Report, as separate lists capped at 8 rows each with a total count:
  • observed routes: routes reached through the reverse dependency closure (depth ≤ 5) that ran in this run, with request, anonymous, and error counts, exemplar request ids, and the tables they read and wrote;
  • not exercised: mapped routes in the closure with no traffic in this run, each with one check;
  • through shared resources: routes outside the closure that read the tables or caches, or call the hosts, that the changed code writes or calls. They share a resource with it, not code.
• A route is a symbol too: it is its own impact, listed itself with the routes that share what it touched.
• The impact box suggests, as the developer types, the routes, beans, repositories, tables, caches, hosts, and events of the run's model, each labelled with its kind (GET /runtime-insights/impact/symbols?query=); picking one asks for KIND name, which names exactly one node.
• Structural reach is a count, never a node dump, and it stays apart from observed execution: route traffic does not prove that a request went through the changed bean.
• Word the result as what was and was not exercised, never as "safe".

Acceptance criteria:

• Spring MVC and WebFlux use the bean graph; Quarkus uses ArC injection edges and reports them unavailable, not empty, when it cannot read them.
• Changing ProductRepository in the sample app lists its observed routes, the unexercised route, and a route that reads sample_products through another repository.

5.8 Run comparison — Runtime Insights ✅ Delivered

A developer changes code, the application reloads, and the developer wants to know what moved. This is the inner loop, so comparison must work without a database. On a laptop, warmup and noise dominate latency, while the counts identical requests produce are stable, so the comparison leads with behavior and reports latency last.

Scope:

• Compare the current run with the previous run, or with a chosen run. Behavior rows come first, per route: statements per request, new and gone statement fingerprints, REST and AI calls, new outbound hosts, new exception groups, the status-class mix, routes newly hit, tokens, cache misses, and median allocated bytes; and runtime-model edges that are new or gone, such as "run 5 added OrderService → pay.internal:8443, 15 calls". A count shift needs ≥ 3 requests on each side; a new item appears at its first occurrence. Scheduled jobs and consumed messages compare per execution beside routes. Source-specific facts and edges require the source in both runs and an enabled, available owning panel from JournalSourcePanels. ORM counters compare positive counts against zero when both runs' start facts record the ORM source; summaries without both start facts conservatively require ORM events in both runs. A run with no ORM events names the capture-listener assumption instead of claiming capture was verified. Disabled source facts and their roots/edges are not shown; a limitation names each disabled panel. Broker panels gate their own messaging roots and edges independently. HTTP Exchanges policy also hides every run reference's request count (0 in the stable JSON field, explicitly labelled hidden in the UI); configuration comparability facts and restart timings remain independent of source-panel evidence. Summary codec v10 retains bounded allocation histograms and execution aggregates and persists only literal-free SQL shapes; v8/v9 remain readable with SQL fingerprints sanitized on read, and v8's missing allocation and execution facts explicitly unavailable. Masking-indistinguishable statements share a group, never a persisted hash of a value.
• Restart cost: after a DevTools restart, the context's time to ready and the beans whose initialization moved by ≥ 200 ms and ≥ 50 %, compared only with the immediately preceding restart in the same JVM, never with the first cold start or a baseline file. Quarkus restart timing is unavailable: StartupEvent supplies neither the complete live-reload duration nor its start timestamp, so BootUI cannot honestly reconstruct the total. Spring timing comes from the run-start facts of §5.18 (M4-5).
• Latency comes last and is labelled noisy: the warm p50 only, with ≥ 10 warm samples on each side, reported when it moved by ≥ 50 % and ≥ 20 ms. A p95 appears only with ≥ 60 warm samples on each side, as sparse tail evidence.
• Keep run summaries across DevTools restarts and Quarkus live reloads in the engine's static run history (D26), which keeps each summary as an encoded byte array, a JDK type, never an application, framework, or BootUI object that would pin the previous class loader. The M0-4 spike showed that a dependency jar stays in DevTools' base class loader and in Quarkus's Base Runtime ClassLoader, so its state survives the next application-context start by default. M2-5 delivers this history.
• When DevTools restart.include, IDE or reactor output directories, or Quarkus quarkus.class-loading.reloadable-artifacts make the holder reloadable, the holder detects that its own class loader is the reloadable one, and comparison reports that previous runs are unavailable, with the reason and the baseline file as the remedy.
• Mark a comparison NOT_COMPARABLE, with the reason first, when the active profiles, datasource URL shape, or cache enablement differ; list configuration differences as limitations. These facts are recorded when the run starts (§5.18, M4-5); a previous run that kept none is compared with that limitation.
• Count the runtime model's observed edges in the aggregates as events arrive, never from the retained window, and keep that edge set in each run summary, so the behavior diff compares whole runs (M4-1).
• Offer an opt-in bootui.runtime-journal.baseline-file (M4-2) that writes one run summary into the build output directory (target/ or build/), so a comparison survives a full JVM restart. It holds only route templates, statement fingerprints, outbound hosts, exception-group ids, status-class and per-route counts, histograms, and the top bean initialization times, and the edge set: never principals, literals, or SQL text.

Acceptance criteria:

• Reloading the sample app after a change that adds a query to a route reports the new fingerprint and the higher statement count after 3 requests, without any property set.
• A comparison with too few samples returns INSUFFICIENT, never "no change".
• Switching the sample app from H2 to PostgreSQL returns NOT_COMPARABLE with the datasource difference first.

5.9 Anonymous access — Runtime Insights ✅ Delivered

The draft's data-exposure flagged a table read by both anonymous and protected routes. That is the normal public-catalog-plus-admin pattern, including the sample app's own sample_products, so it would teach users to ignore the panel. Both observations here report facts, never vulnerability verdicts.

Scope:

• Authentication is three-valued: anonymous, authenticated, or unknown. A missing principal means anonymous only where the adapter's capture establishes it. The journal's security source records only authentication results and authorization failures, so a granted anonymous request leaves no trace there; the authorization source of §5.18 (M4-6) records each decision with its authentication class and rule, and is what both observations read. Without it, every request is unknown.
• anonymous-data-reach reports anonymous successful requests that executed INSERT, UPDATE, DELETE, or MERGE, reading every statement in a JDBC batch preview. When a single target can be confidently read at a statement head, it never promotes INSERT … SELECT sources, subquery tables, or UPDATE … FROM sources to writes. Ambiguous dialect forms, including multi-table DELETE/UPDATE and FROM/USING aliases, retain all lexically identified names as explicitly labelled candidates, not proven writes; these can include read-side tables or aliases. CTE-headed statements are not parsed. Anonymous and protected reads of the same table stay in §3.18's data access map as exploration, not as an observation. The evidence counts captured DML texts, not affected rows or prepared-batch executions. Statement batches retain only five previews, each truncated at 256 characters; prepared batches retain one SQL text. Truncation can hide targets, so findings state these bounds and checks explicitly flag requests with possibly truncated SQL. Truncation-marked captures, unparsed hash syntax, and nested or executable block comments yield candidates only; a truncated literal cannot hide later previews separated by the capture's truncation marker and batch boundary. Proven targets and ambiguous candidates are reported separately rather than downgrading a known write. On Quarkus, Hibernate SQL is captured at preparation time: a prepared statement is never a proven write, even when its session executed other statements. Preparations with a metered session that executed nothing, or with Hibernate evidence hidden, are omitted; timed JDBC executions remain judgeable.
• anonymous-success-on-restricted-route reports a 2xx answered to a proven-anonymous request on a route whose first matching declared security rule requires authentication or a role. If a preceding filter chain cannot be read, it reports nothing. Worded: "a successful anonymous response, not proof that the rule is wrong". As delivered (M4-12), a route counts as restricted from this run's own decisions on it, another anonymous caller denied or an authority required, rather than from the declared rules, which BootUI does not yet read per route; the finding says so.
• Agent verify lines say "do not add authorization from this row alone". Evidence links to Security and §3.18's data access map.
• The sample apps gain two seeded cases: an anonymous debug endpoint that writes a table otherwise written only by administrators, and a route declared protected but reachable anonymously through a matcher mistake. As delivered (M3-6), the mistake is an exact, case-sensitive matcher in front of a handler that matches names case-insensitively.

Acceptance criteria:

• Both seeded cases are found on every stack with security. Anonymous reads and authenticated writes produce no anonymous-write finding; intended anonymous writes such as registration or contact forms are reported as facts, with the explicit check that public writes are often intended, not treated as vulnerabilities.
• Every stack, including Quarkus, counts anonymity only where its authorization capture proves it. Requests with no decision or an unknown authentication class are outside the eligible count. With the required sources recorded and visible, checks report INSUFFICIENT with zero eligible requests when none proves anonymity, following the shared eligible-work policy; they do not fabricate anonymous requests or per-route findings. A missing required source makes the check NOT_APPLICABLE.

5.10 After 2.0 💤 Deferred and ❌ Cut

5.11 Resource correlation — Diagnostics ✅ Delivered

BootUI shows CPU, heap, and GC in the JVM panels, and requests in Live Activity, but never links them: nothing says which request allocated the most, which work outside requests burns CPU, or which collections completed while a slow request ran. Joining them by time is misleading under concurrency. This item links resources by identity, not by timestamp: each resource fact is attached at the moment it is measured, on the thread and in the scope that owns it, and time is kept only for display. The hook is §5.1's scope-based CorrelationContext holder, which opens and closes a scope whenever request work runs on a thread, so one engine change covers all three stacks.

Scope, verified on JDK 27 by the resource-correlation research (Appendix A):

1. Scope readings (exact, on by default). When a scope opens and closes on a thread, read that thread's CPU time, allocated bytes, and each pause collector's collection count, and add the deltas to the request. A request that hops threads sums its segments, which lifts the "same platform thread" limit. Each segment costs about 0.85 µs. The JVM returns -1 for both CPU time and allocated bytes on virtual threads, so their segments record CPU and allocation as unavailable, with the reason, while still recording GC.
2. GC by id (exact, on by default). A gc journal source built on GarbageCollectionNotificationInfo publishes one event per collection, keyed by collector and GcInfo.getId(), with its cause, duration, and heap before and after. That id equals the collector's collection count (verified on G1 and ZGC), so the counts read in (1) name the exact collections that completed during a request, whenever their notification arrives (2–30 ms late). Collections are classified as pauses or concurrent cycles with MemoryCollector's existing logic: ZGC and Shenandoah "Cycles" beans report concurrent time, never a pause. Durations are whole milliseconds.
3. CPU ledger (once a second). For each Java thread, its CPU time minus what scopes already credited to requests goes to its thread family, named from the thread's name as §5.2's aggregates name work outside requests; §5.1's thread kind classifies only the calling thread, so a sampler cannot use it for others. Virtual threads' CPU time appears in their carriers' family. Process CPU minus all Java threads is JVM internals (GC, JIT, VM). Requests, thread families, and JVM internals sum to process CPU, a built-in consistency check. Under an allocation-heavy probe, JVM internals used 73 % of process CPU. A full sweep costs about 0.4 ms at 300 threads, so the sampler caps the threads it reads per sweep.
4. Resource track (once a second). Heap used and committed, heap after the last collection, process CPU, allocation rate, and thread counts, in fixed rings of about 900 points in the aggregates, outside the evidence budget. Each point stores the journal sequence number, which places it among events by order rather than by clock.
5. JFR attribution (opt-in, user-triggered, bounded). A custom bootui.ExecutionSegment JFR event carries the request id of each scope segment; it costs under 100 ns while no recording runs. During a Profile resources session, bounded by jfr.max-duration, CPU and allocation samples are joined to segments by Java thread id and interval inside JFR's own clock, virtual threads included. That lifts the virtual-thread CPU limit of route-time-breakdown and adds the hot frames of a route. jdk.CPUTimeSample is used where available (Linux, JDK 25 and later), and the report says which sampler ran. Starting JFR costs about 330 ms and 42 MB of process memory and writes a repository to the temporary directory, so it never starts on its own or on page load. Its milestone is M4-4 (D17).

Surfaces:

• The request profile gains CPU time, allocated bytes, and GC pauses (count, milliseconds, and collection ids), each with its availability and reason (§5.3), and a GC lane on the unified timeline.
• Live Activity gains a resource lane and a Work outside requests breakdown: request work, each thread family, BootUI's own threads, and JVM internals.
• Resource observations, in M4-3 (D18):

Architecture:

• A new engine resources package, dependency-free and classloading-safe: SegmentMeter (scope readings, called by the §5.1 holder), GcEventSource, ResourceSampler (ledger and track, on one self-excluding BootUI daemon thread), ResourceTrack, and JfrAttribution with ExecutionSegmentEvent. com.sun.management and jdk.jfr are reached only through guarded classes that report unavailable when absent, for example on runtimes without JFR.
• The adapters add little beyond §5.1's scopes: each HTTP publisher begins a request's measurement and takes its usage when it publishes the request, and each adapter already classifies its threads' kind. Quarkus REST runs a blocking method on a worker thread that no thread scope covers, because Quarkus keeps the request's context on its duplicated Vert.x context, so its existing request filter opens the worker's segment there. That segment stays open through serialization, until the response is written and the usage is taken (M2-6).
• DTO changes are additive and nullable: request-profile cpuNanos, allocatedBytes, gcPauses, and resourceAvailability, and a new resource-track and ledger DTO, with contract-catalog entries on all three stacks.
• Properties: bootui.runtime-journal.sources gains gc and resources; bootui.resources.sample-interval (1 s), bootui.resources.max-threads, and bootui.resources.jfr.max-duration.

Out of scope for 2.0:

• Per-request blame for process-wide effects: a pause is reported as completed during a request, never as its cause.
• Continuous JFR recording, and any JFR recording started without the developer's action.
• Native memory tracking and off-heap attribution.

Acceptance criteria:

• Scope arithmetic holds across thread hops, async redispatches, Reactor hops, and Vert.x worker dispatch, and virtual threads report CPU and allocation as unavailable, never zero.
• GC joins by id are exact with late and out-of-order notifications, on G1, Parallel, Serial, ZGC, and Shenandoah, and concurrent cycles never count as pauses.
• Requests, thread families, and JVM internals sum to process CPU within 1 % per ledger interval.
• A synthetic JFR recording joins samples to the right request, including on a virtual thread.
• The overhead scenario (§2.2) measures scope readings on and off and stays within its budget.

5.12 Proxy bypass — Runtime Insights ✅ Delivered

Spring applies @Transactional, @Cacheable, and @Async through proxies, so a call from inside the same bean, a private or final method, or an instance created with new silently skips them. These are among the most viewed Spring questions on Stack Overflow (together more than 480,000 views). The Architecture advisor's self-invocation rule can only say that a call may bypass the proxy; runtime evidence shows that it did.

Scope:

• proxy-bypass reports an annotated method that ran without its effect, in the same request:
  • @Transactional, with a propagation that requires a transaction, while no open transaction had that boundary;
  • @Cacheable for cache X, with no access to cache X before the method ran; sync = true and a nonblank condition are not judged, because a synchronous miss is recorded after its loader and a condition can skip cache access entirely. unless remains judgeable because it only vetoes the later put;
  • @Async, running on the calling request's own thread.
• Each finding names the method, the route, the affected and eligible request counts, and the calling frame, and links the static self-invocation finding when there is one. Minimum: 1 request, REQUEST_ID tier only.
• What to check: "Call the method through the bean: inject it, or move it to another bean."

Architecture:

• SQL, REST client, and cache events keep up to four interned application frames, with their method types for exact overload resolution (§5.2). A Spring adapter SPI resolves the boundary annotations of a frame once, on the dispatcher, with Spring's merged-annotation lookup, so annotations inherited from interfaces count.
• AspectJ weaving mode is detected and reported not applicable. TransactionTemplate boundaries, which have no method, are skipped.

Acceptance criteria:

• The sample app's seeded self-invocation of a @Transactional method is found, while calls through the bean are not.
• A synchronous cache miss whose SQL precedes its MISS event and a condition-skipped cache call produce no cache bypass finding; other judgeable annotations on the same method still count.
• Quarkus reports not applicable, because ArC intercepts self-invocation by design.

5.13 BootUI Java agent — Developer tools 🚧 In progress

Everything in §5.1–§5.12 comes from framework hooks: filters, observations, DataSource proxies, listeners, and JDK management beans. They see what the framework sees, and stop there. Four questions stay out of reach, and the research behind this item (Appendix A, Agent research) found each answered by a Java agent elsewhere:

• What ran inside the handler? §5.5's handler phase is a black box between SQL and REST calls. Glowroot, Pinpoint, and Arthas's trace time application methods; Digma turns OpenTelemetry-agent spans into code-level insights.
• Did the code I just changed run? Change impact (§5.7) proves route traffic, never that a request went through the changed bean. JaCoCo and Azul Code Inventory record which methods executed; Azul Vulnerability Detection uses the same evidence to say whether a vulnerable class was ever loaded.
• What did the application touch that no panel captures? Sockets opened by SDKs, files, processes, environment variables, threads, and executors that bypass Spring and Quarkus hooks. The OpenTelemetry agent instruments over 100 libraries, BlockHound instruments blocking JDK methods, and Kohsuke's file-leak-detector records who opened a file.
• Where did the request go after it left the thread? §5.1 leaves @Async, CompletableFuture, and executors out of scope, and the PoC found 90 of 425 statements on pool-N-thread-N with no owner. Every APM agent propagates context through executors by instrumenting them.

This item adds an optional agent, bootui-agent, that feeds the same correlation context, journal, runtime model, and observations as the rest of v2. Without it, BootUI behaves exactly as §5.1–§5.12 specify. With it, the new panels in §5.14–§5.16 become available and existing observations gain evidence (§5.17). It is not an APM agent: it is local, development-only, dormant until BootUI claims it, and it never exports anything.

Scope:

• A new published artifact, bootui-agent: a -javaagent jar with Premain-Class, Agent-Class, and Can-Retransform-Classes, compiled for Java 17, with Byte Buddy relocated under io.github.jdubois.bootui.agent.shaded. It has no Spring, Quarkus, or BootUI engine dependency, and it is never a dependency of the starters or the Quarkus extension, so the "no new heavy dependency" rule (§1.3) holds for every application that does not opt in.
• A tiny bootui-agent-bridge module of JDK-typed classes only, the contract between the agent and the engine. The agent appends it to the bootstrap class loader search, so JDK classes, library classes, and application classes all see one copy. The engine never links it from its own class path, which would define a second, inert copy under self-attach or Quarkus's class loaders: it looks the bridge up on the bootstrap loader only and reports "not attached" when absent (M5-0). Like §5.8's run history, it holds only strings, numbers, arrays, JDK collections, and JDK functional interfaces, never an application, framework, or engine class that would pin a discarded class loader.
• Dormant until claimed. premain stores the Instrumentation instance and installs nothing. Only when BootUI activates under its existing rules (Spring activation, Quarkus dev and test launch modes) does the engine claim the agent, passing the enabled sensors, the application's package prefixes, and its bean classes. The agent then installs its transformers and retransforms the matching classes already loaded. A production JVM that keeps the flag by mistake, a JVM without BootUI, or a run with BootUI disabled pays for premain only. A DevTools restart or Quarkus live reload stops recording until the next run claims it again, while the claim stays armed, so reloaded application classes are transformed as they load; the claim is made as early as each adapter can (D34).
• The engine and the agent's bridge speak a protocol version (AgentBridge.PROTOCOL, the jar's BootUI-Agent-Protocol manifest entry). Another protocol leaves the agent unused, with both versions in the status; a different agent version on the same protocol is shown as a warning.
• Transport. Advice writes fixed-size records of longs and interned string ids into per-thread buffers, published to a bounded multi-producer ring in the bridge. The engine drains that ring on one thread per claim: executor handoffs become one more journal source (agent.executors), and the inventory and code-paths records feed bounded stores outside the journal, under the agent evidence contract (§5.17). The ring never blocks: on overflow a record is dropped and counted per sensor, exactly like the journal queue. Advice never calls engine code on the application thread, except the correlation reads below.
• Correlation. The engine installs, in the bridge, a Supplier that returns the current CorrelationContext snapshot through the engine's CorrelationSource (the thread scope, or the Vert.x context on Quarkus), and a thread kind flag that §5.1's adapters already classify. Recording advice reads them at most once per flushed record; propagation must capture on every submit, so its capture reads only the raw thread-local or Vert.x context, never filling in trace ids (M5-0).
• Context propagation through executors, the first sensor and the one that closes §5.1's largest gap. Advice on ThreadPoolExecutor.execute, ScheduledThreadPoolExecutor.schedule*, ForkJoinPool.execute and submit, and Thread.start for a thread created with a Runnable wraps the task with the submitting thread's context snapshot and reopens it, as a child execution, around the task. Work handed to an executor now carries its request id and its own executionId, and the event records that it ran on another thread. Spring's ContextPropagatingTaskDecorator, Reactor schedulers, and Vert.x, which already propagate, are detected and never wrapped twice. Work still running after its request's response was committed is marked after response.
• A new CorrelationTier, PROPAGATED, after REQUEST_ID in ExecutionProfileAssembler, so a profile says which of its children reached it through an executor handoff.
• Self-protection. Every advice suppresses its own exceptions; a class that fails to transform is skipped, counted, and named in the status; BootUI, the agent, Byte Buddy, JDK internals, Spring CGLIB and AOT proxies, ArC's generated _Subclass, _ClientProxy, and _Bean classes, and Hibernate's enhanced proxies are never instrumented. Advice only inlines code at method entry, exit, and exception handlers, and never changes a class's shape, so releasing the claim needs no reverse transformation. Retransformation still fails for some classes: the agent uses Byte Buddy's DECORATE type strategy, splits failing batches down to one class, and names each class still failing, since Byte Buddy's default listener swallows those errors (M5-0).
• Adaptive exclusion. An instrumented method called more than 50,000 times a second with a mean under 2 µs is switched off in its advice and listed as excluded, as Glowroot and Kieker do, so a getter loop never dominates.
• Activation. The recommended path is an explicit -javaagent: flag, which JEP 451 never restricts. The Java Agent panel shows the resolved path of the jar and a copy-paste line for the Spring Boot Maven plugin's agents parameter, Gradle's bootRun JVM arguments, Quarkus dev mode's -Djvm.args, the Surefire and Failsafe argLine (appended to @{argLine}, so JaCoCo keeps working), and IDE run configurations. An opt-in bootui.agent.self-attach attaches at startup through the Attach API. On JDK 21 and later that prints JEP 451's warning unless the JVM runs with -XX:+EnableDynamicAgentLoading, and a future JDK may refuse it, which the panel says; it is never the default.
• Properties under bootui.agent.*: enabled (claim the agent when present, default true), sensors (an allowlist, like bootui.runtime-journal.sources), packages (application package prefixes, detected by default from @SpringBootApplication or the Quarkus application artifact), excluded-classes, ring-capacity, and self-attach.

Surfaces:

• A new panel, java-agent, titled Java Agent, in the Developer tools group. It is always available, because its first job is to explain how to attach the agent:
  • status: not attached, attached and dormant, active for this run, or failed, with the reason; agent and BootUI versions; JDK; and whether it was loaded by -javaagent or self-attach;
  • sensors, each with its state, instrumented classes and methods, adaptively excluded methods, records, drops, and transformation errors;
  • the claim's cost: retransformed classes and the time retransformation took;
  • the setup snippets above, for the build tool BootUI detects, with Copy.
• The route-time-breakdown observation, Live Activity, and the request profile show handoffs as child executions, with an after response badge.

Architecture:

• New modules bootui-agent-bridge (JDK only) and bootui-agent (the jar, in D33's layout, with the bridge inside it), and a new engine package javaagent (the name agent is taken by the Copilot sessions): AgentClaim, AgentJournalSource, AgentStatus, and one reader per sensor. Adapters only contribute their bean classes and application packages at claim. The engine always looks the bridge up in the bootstrap loader (Class.forName(name, false, null)), so a copy any other class loader defines, such as one of Quarkus's, is never used.
• Agent evidence is either journal-backed, as executor handoffs are (an additive RuntimeEvent payload), or kept in bounded stores outside the journal, as Code Paths' trees and Code Inventory's first calls are, read, cleared, and counted under the agent evidence contract (§5.17, M5-11). Nothing in §5.1–§5.12 depends on either.
• An M5-0 spike proves, before any sensor is built: one bridge class across Spring DevTools restarts and Quarkus live reloads; retransformation cost on the sample apps and Spring PetClinic; coexistence with the OpenTelemetry Java agent, JaCoCo, IntelliJ's debugger agent, and Mockito's inline mock maker; and the overhead of executor propagation.

M5-0 spike, first pass (2026-10-02, spike code outside the repository, reviewed by a rubber-duck agent on Claude Opus 5.5 at the maintainer's request):

• Proven: one bootstrap AgentBridge class served a start and ten DevTools restarts, and a start and ten Quarkus live reloads, each run claiming and releasing it; executor propagation put 8 of 8 raw-pool statements of /api/sample/pool-stress under their request on Spring MVC and Quarkus, against 0 of 8 without the agent; the agent claimed and propagated beside the OpenTelemetry Java agent 2.31.1, JaCoCo 0.8.15, and IntelliJ's debugger agent, and the Spring autoconfigure suite (2,594 tests, Mockito's inline mock maker) passed with it claimed in 162 contexts, except for the dependency catalog counting the agent jar itself, which M5-1 must recognize.
• Found: REDEFINE silently failed Quarkus's only retransformation batch ("attempted to change the class modifiers"), so DECORATE, batch splitting, and a redefinition-error listener are required; the engine's existing agent package (Copilot sessions) means M5's engine package needs another name, such as javaagent.
• Not proven, and corrected in its report: no class loader pinned (the Spring sample retains every restart loader by itself, so the comparison could not fail); the overhead (+40 ns a task is a lower bound with a stub scope, not SegmentMeter); coexistence beyond starting and propagating BootUI's context; JDK 17 and 21; Spring PetClinic.
• Design constraints for M5-1 and M5-2, from the review: one jar that appends its embedded bridge from premain behind a trampoline, catches Throwable, refuses a duplicate or mismatched agent, and suppresses every advice's exceptions; one immutable claim record with a generation and a token-checked release, so two BootUI instances in one JVM (a test-context cache, Quarkus continuous testing) never disable each other; capture and reopen held weakly by the bridge; matchers that match nothing while released; identity-preserving propagation (submit-time snapshots in a weak identity map, applied where the task runs) instead of wrapping, so remove, purge, afterExecute, shutdownNow, and ForkJoinTask identity keep working; never propagating into executor worker threads, the virtual-thread scheduler, or JDK tasks; and no global counters in advice.
• Second pass, before M5-1: a heap-walk test on a minimal application with a mutation check and a queued task at restart; JMH with the real scope and SegmentMeter, several producers, fan-out, and p99 on JDK 17, 21, and the newest; Spring PetClinic's retransformation cost; OpenTelemetry parent spans inside pool tasks in both agent orders; and -XX:ActiveProcessorCount=2.

M5-0 spike, second pass (2026-10-02 to 2026-10-03, JDK 17, 21, and 26, spike code outside the repository, reviewed twice more by a rubber-duck agent on Claude Opus 5.5, each finding fixed and re-measured, every new check shown able to fail by a mutation):

• Mechanism (D32): identity-preserving propagation passes every executor behavior on JDK 17, 21, and 26 (28 with the OpenTelemetry API on the class path), including remove, purge, shutdownNow, rejection handlers, afterExecute, ForkJoinTask identity, a shared task object submitted by several owners, virtual threads, and -XX:ActiveProcessorCount=2; wrapping fails 9 of the first 17. It keys where ThreadPoolExecutor hands the task over (addWorker, workQueue.offer), not at execute's entry, because the OpenTelemetry agent replaces lambdas with its own wrapper there; with OpenTelemetry 2.31.1 in both orders, BootUI's context and OpenTelemetry's trace both reach the task, and on the Spring sample 8 of 8 pooled statements are owned while OpenTelemetry's 8 JDBC spans stay in their request's trace.
• Two defects found and fixed: with OpenTelemetry first, Byte Buddy could not read the bootstrap interface OpenTelemetry adds to JDK classes as they load, so transformations failed silently on all three JDKs (a type pool falling back to bootstrap-loaded types fixes it); and on JDK 17 to 23, Byte Buddy's transformer captured the claiming stack's access control context, pinning the first run's class loader for the JVM's life (installing in a privileged block fixes it).
• Retention: the first pass's saturated baseline was soft references (Spring's caches), plus one-time pins of the first run (Spring Boot's shutdown-hook thread, H2's static exception, the JDK delay scheduler's thread, and on JDK 23 and earlier every new Thread()'s access control context). An agent-rooted walk of the heap (what the agent's own statics strongly reach) replaces loader counting: after ten DevTools restarts the agent reaches only the base loader and the current run, with BootUI in the restart loader or not, on JDK 17, 21, and 26; engine-typed payloads, a careless transformer, an unprivileged install, and an application object in a bridge static are each caught. Quarkus: 7 class loaders after 11 live reloads, with and without the agent.
• Claim timing: the first claim costs 239 to 512 ms (Byte Buddy's start and the loaded-class scan), once per JVM; later claims cost nothing, and restart and live-reload times are unchanged.
• Overhead: with one producer, propagation adds about 100 to 150 ns a task; reopening each task as a metered segment adds about 1 to 1.5 µs (SegmentMeter.switchTo reads CPU time, allocation, and every collector, and opens a JFR event under the request's monitor), so propagated tasks are not metered individually (D32). Thread CPU time costs 592 ns a read on macOS. Eight producers add about 1.7 µs of latency a task, unexplained yet; M5-2 profiles it.
• Packaging (D33): OpenTelemetry's layout works under -javaagent on JDK 17, 21, and 26, keeps a second copy dormant, needs no temporary file or writable directory, and shows JaCoCo two launcher classes instead of about 775 relocated Byte Buddy classes.
• Accepted limits, recorded in D32: hooks verified on JDK 17, 21, and 26 only; fork() from a non-worker, invokeAll, and JDK 25 and later ForkJoinPool delayed tasks not keyed until M5-2; pool workers started before the first claim never apply snapshots; a task handed over by a drain or serializing executor carries the handing thread's context.

Out of scope:

• GraalVM native executables and Quarkus native mode, where no agent can run. Their panels report the agent unavailable.
• Structural hot reload or live patching (JRebel, DCEVM, Arthas's redefine): DevTools and Quarkus already own reload.
• Remote attach to another JVM, and any control channel other than the application's own BootUI API.

Acceptance criteria:

• With the agent attached and BootUI disabled, or in a Quarkus production build, no transformer is installed.
• The correlation scenario gains an executor route: with the agent, 100 % of its statements carry their request id and the PROPAGATED tier; without it, they stay unowned, as today.
• Ten DevTools restarts and ten Quarkus live reloads with the agent claimed leave no previous application class loader reachable, proven by a heap-walk test like M0-4's.
• The sample apps start and pass their browser suites with the agent attached, beside the OpenTelemetry Java agent and JaCoCo, on Java 17, 21, and the newest JDK the build supports.
• The overhead scenario (§2.2) with the agent's default sensors claimed stays within 10 % of the same scenario without the agent, on top of the BootUI-on baseline.
• Overhead note (2026-10-07): each benchmark report now carries a distribution-free 95 % interval of its median. One run's cumulative I/O-route median moves by about 2 points on unchanged sensors (3.6–11.4 % over 33 CI runs), so the 10.7 % and 11.7 % of #1326's resources A/B (intervals [7.2, 12.7] and [4.2, 12.9] %) were runner noise, not a regression: no default sensor's own leave-one-out increment had an interval above zero on one machine (15 pairs each), and the runs before and after #1299 and #1323 averaged 7.6 % and 8.5 % (t = 1.3). D48 adopts the rule this suggests: a cumulative check fails only when its median interval's lower bound is above 10 %, and own-increment gates stay at 3 %. M5-5c's blocking check applies it, on 9 pairs instead of 5; the opt-in sensors' checks follow when one is proposed for the defaults, and the I/O route's cumulative figure still only warns (Java Agent). Follow-up (2026-10-08): the blocking check's cumulative run measures 15 pairs, every enforced cumulative check reads the interval, and D48 now states what it detects; with files on by default (D49), its own increment is enforced at 3 % by the same interval rule, and so would environment's be, were it on by default.

5.14 Code Paths — Diagnostics 🚧 In progress

Business value: the handler is where developers spend their time, and today BootUI can only say how long it took. Code Paths names the application methods a route spends that time in, across all its warm requests, and shows which bean calls which at runtime. It turns "handler 80 ms" into "PricingService.quote 55 ms, 40 of them in TaxClient.rate", without tracing, spans, or a profiler session, and it gives change impact (§5.7) its missing proof.

Scope:

• Component-boundary timing. With the code-paths sensor, the agent instruments the public and protected methods of application bean classes (Spring beans and ArC beans in the application packages, passed at claim), and the methods of application classes that SQL, REST client, and cache events already name as call sites (§5.2). It does not instrument every method: a JDK, framework, or library method appears only as the time of its caller.
• A per-thread shadow stack of System.nanoTime() enter and exit marks builds a per-request call tree merged by (parent, method), capped at 512 nodes and depth 32, with an Other node. Each thread flushes its fragment of the tree when the request's scope or the executor's task closes on it, stamped with its correlation context, and the engine merges a request's fragments into its tree. Children reached through an executor (§5.13) attach to the submitting node, and overlapping children are unioned (§5.4) so self time is never negative.
• SQL, REST client, cache, and AI events attach to the innermost instrumented method open on their thread when they run, an exact join by stack, not by time.
• The engine merges each settled request tree, once the journal named its request's route, into a route tree per route and run (count, total, self time, and a latency histogram per node), capped at 2,000 nodes per route with an Other bucket, and the runtime model reads an observed bean → bean invokes edge per call pair from the route trees.
• Storage. Request trees (the recent ones, each route's slowest and latest failed, and those waiting for their exchange) and route trees are kept in bounded stores of the run, outside the journal: there is no CODE_PATH event. They follow the agent evidence contract (§5.17): every read, get_code_paths, Beans at runtime, the handler split, and repeated-selects' issuing method resolve once whether the Code Paths panel and HTTP Exchanges are visible; Clear recording drops every tree and any fragment flushed before it, leaving a request that lost one out whole; and their estimated bytes are reported beside the journal's, bounded by bootui.runtime-journal.agent-evidence-max-bytes.
• Method probes (user-triggered, bounded). From a Code Paths node, an exception frame, or a bean, the developer starts a probe on class#method (with its descriptor for overloads). The agent retransforms that one method and records the next 20 invocations, or 60 seconds, whichever comes first: duration, thread kind, request id, outcome (return or the exception's type), and the calling frame. Started with them (opt-in per probe), a probe also records argument and return shapes (D37, D44): runtime types, nullness, and, by exact JDK class, collection, map, and array sizes and Optional presence, read without calling any application method, never a toString(); under MASKED exposure, those; under FULL, also a string's length, a char[] or byte[] length, and an enum constant's name; under METADATA_ONLY, none. At most five probes run at once. Probes are actions: read-only policy blocks them, and they end with the run. This is the useful core of Arthas's watch and Lightrun's snapshots, without a shell, expression language, or variable capture.
• GET {api}/code-paths returns the routes with a tree; GET {api}/code-paths/routes/{route} returns one route tree, paged by depth; GET {api}/code-paths/probes lists probes; and POST {api}/code-paths/probes starts one.

The UI:

• A route list ranked by warm p50, then the selected route's tree as an indented table (method, calls per request, total, self, share of the handler), with SQL, REST, cache, and AI children shown under the method that ran them. Selecting a method shows its callers, the routes that reach it, and Probe this method.
• A Beans at runtime tab: the observed invokes edges with call counts, beside the Beans panel's declared dependencies, with a filter for declared dependencies never called in this run.

Architecture:

• The tree merge, the interval union, and the adaptive exclusion are engine code with property-based tests; the agent only writes marks. The Spring and Quarkus adapters contribute bean classes at claim, and a thin controller or resource.
• route-time-breakdown (§5.5) splits its handler phase into the route tree's top methods by self time when the agent is active, with the rest shown as other handler time.

Acceptance criteria:

• On the sample apps, the seeded slow route names its slowest application method, and the tree's times reconcile with the handler phase within 5 %, overlap shown apart.
• A probe never outlives its bound, is blocked by read-only policy, never runs an application method for a shape, and never returns a shape under METADATA_ONLY, a value-derived detail below FULL, or any shape to MCP or the CLI.
• Without the agent, the panel is unavailable with the -javaagent line as its remedy.

5.15 Code Inventory — Diagnostics 🚧 In progress

Business value: this is the answer an AI agent needs most after an edit, and the one no BootUI signal gives today: did the code I changed actually run, and on which routes? The same evidence says which application code a run or a test suite never exercised, which dependencies were never loaded, and whether a vulnerable dependency's classes were ever loaded at all, which Azul reports cuts vulnerability noise by orders of magnitude.

Scope:

• Executed methods. With the inventory sensor, every method of every application class carries a one-time hit flag, as JaCoCo's probes do but at method granularity: after the first call it costs one static field read. The first hit records the method, its first request id and route, and the time. Each run keeps a bitset of executed methods. Line and branch coverage stay JaCoCo's job, and both agents run together.
• Changed methods, without git. The transformer already sees every application class's bytes as it loads, so it hashes each method's instructions (excluding line numbers and other debug attributes) and each class's method set. After a DevTools restart or a Quarkus live reload, comparing those hashes with the previous run's gives the exact set of changed, added, and removed methods, even for changes an IDE compiled without a commit. The previous run's hashes are kept as a long[] of (method key, code hash) pairs in the run history (§5.8), about 16 bytes per method and at most 1 MB, outside the 256 KB run summary.
• For each changed or added method: executed in this run or not, requests and routes that executed it (through §5.14's route trees when the method is a component boundary), and its callers. Removed methods are a count.
• Dependency use. The agent records the code source of every loaded class, so each dependency jar gets: classes loaded, loaded during startup or later, and the first route whose request loaded one. Jars with no class loaded in the run are listed as not loaded in this run, never as unused, with the run's traffic as the caveat.
• Vulnerable code reach. The Vulnerabilities panel gains a Runtime reach column and filter when the agent is active: NOT_LOADED, LOADED (with the class count and first route), or, where an OSV advisory names affected classes or methods, AFFECTED_CLASS_LOADED. Reach never changes a finding's severity, score, or Scorecard penalty: a class not loaded in this run may load in another.
• GET {api}/code-inventory returns the run's summary; GET {api}/code-inventory/changes, /methods, and /dependencies return paged lists.

The UI:

• A header stating the run and N of M application methods executed, then three tabs: Changed since the previous run (first, when there is a previous run), Application code (packages and classes with executed and never executed counts, filterable to never executed), and Dependencies.

Architecture:

• Hashes, bitsets, and diffs are engine code over JDK types, so the run holder never pins a class loader. The agent only sets flags and emits load and first-hit records.

Acceptance criteria:

• Editing one method of the sample app and letting DevTools restart lists exactly that method as changed, executed or not executed according to the requests sent, with no git repository present.
• A seeded never-called service method is listed as never executed, and a jar the sample app declares but never loads is listed as not loaded in this run.
• The Vulnerabilities panel's scores are identical with the agent on and off.

5.16 Side Effects — Diagnostics 📋 Planned

Business value: what an application touches is a design, security, and deployment question at once: which hosts it calls, which files it reads and writes, which processes it starts, which environment variables it needs, and which threads and thread locals it leaves behind. BootUI sees only what goes through the clients it hooks. Side Effects shows the rest, per route and call site, with the request that did it, and finds a class of bugs no framework hook can: blocking calls on event loops beyond JDBC, thread locals leaking data between requests, streams never closed, and request input pasted into SQL or a command.

Scope, one agent sensor per row, each aggregated per (route or thread family, kind, target, call site) with counts before it reaches the journal:

• Request parameter values for (a) are held in the correlation context only while the request runs, compared only when a sink is reached, and never stored, logged, or displayed. Bodies and headers are never read.
• Since D37, thread-locals, resources, environment, and security-sinks' request-value matching are opt-in until their overhead budgets are measured; the other sensors are on by default once their JDK retransformation check and budget pass. D47 makes resources on by default, an exception to D37, after its A/B passed. Their findings are Side Effects rows until each passes the per-kind gate (D36).
• thread-activity is not M5-2c's threads sensor, which carries a request's context into the threads its work starts. It is off by default until a same-runner A/B of the agent's overhead benchmark passes the overhead rule (its own median increment at most 3 %, the cumulative median at most 10 %), then on.
• GET {api}/side-effects returns the counts per sensor; GET {api}/side-effects/{sensor} returns its paged rows.
• The runtime model (§5.4) gains host, file pattern, process, and environment variable nodes, and opens, spawns, and reads edges from routes, jobs, and application methods.

The UI:

• One tab per sensor group: Network, Files and processes, Environment, Threads and leaks, Blocking, and Security sinks, each a table by route or thread family, target, and call site, with counts, the exemplar request id, and links to Live Activity. Security sinks are worded as facts ("the value of name appeared in this SQL text"), never as vulnerabilities.

Architecture:

• Target normalization, recognition of clients from frames, and every aggregation are engine code; advice only records the operation, target, call-site id, and outcome.

Acceptance criteria:

• The sample apps seed one case per sensor and a counterexample for each: an SDK call to a local host no panel captures; a report written outside the temporary directory; a ThreadLocal left set after a request (and a ThreadLocal cleared in finally, which must not appear); a FileInputStream never closed; a Thread.sleep on an event loop; and a search route concatenating its parameter into SQL (and a parameterized one, which must not appear).
• Sensor values never appear in any mode: no payload, file content, argument, environment value, or matched parameter.

5.17 Agent evidence in the journal, Runtime Insights, and agent tools — Cross-cutting 🚧 In progress

The agent is only worth its setup if its evidence joins everything else by request id. This item wires §5.13–§5.16 into the v2 core, so the same observations, comparisons, and agent tools become more exact when the agent is present, and stay exactly as specified when it is not.

Agent evidence takes one of two paths. Evidence that is an event of a unit of work, with its own time and owner, is journal-backed: executor handoffs (ASYNC_HANDOFF, the agent.executors source), and later caught exceptions. Evidence that aggregates many requests, or that the agent marks once a run, is kept in bounded stores of the run outside the journal: Code Paths' request and route trees (§5.14) and Code Inventory's first calls and loads (§5.15) since M5-4 and M5-3, and Side Effects rows (§5.16) and method-probe hits (§5.14) when they ship. There is no CODE_PATH or CODE_CHANGE event: Code Inventory's changes come from its disk scan and the run history's method hashes.

The agent evidence contract (M5-11). One engine projection, AgentEvidence, applies to every store outside the journal what the journal applies to its own events (§8), in one place:

• Source-panel visibility. A read resolves once whether the store's own panel and HTTP Exchanges, which owns requests and routes, are visible, and derives its answer, its cache key, and its reason from that one read; Runtime Insights resolves it once per projection and passes it to every Code Paths and Code Inventory read it makes. While the store's panel is disabled, its evidence is neither shown nor counted, in its panel, its MCP tool and CLI command, or the observations that read it; while HTTP Exchanges is, no request or route of it is shown. A predicate that fails reads as hidden, and the agent's own unavailable reason comes first.
• Live exposure. The stores keep method keys, route templates or observed paths masked when written, request ids, times, and counts, never a value. Exports cannot carry more than the reads return, and every field the Code Paths and Code Inventory reads can return is listed and reviewed as metadata in a test, so a new field, such as a Side Effects target, must be reviewed against the live policy before it ships; masking a target or an argument shape belongs to the projection that reads it.
• Clear recording. The projection is a journal listener: every clear of the journal, Clear recording after its confirmation and under read-only policy, or Free BootUI memory, clears every store in the same step, under the journal's lock. A store drops what it recorded before the clear, what is still queued in the agent's ring included; Code Paths leaves a request that lost a fragment to the clear out whole. Counts since the claim, adaptive exclusions, and what the agent marks once a run (which methods executed, which jars loaded) are kept, and the stores say when they were cleared.
• Export rules. The panels, Runtime Insights' Export JSON and Copy for AI, the MCP tools, and the CLI carry only what the stores' reads return under one read; no surface serializes a store, nothing of them is written to disk except, in the opt-in baseline file (bootui.runtime-journal.baseline-file), the run summary's masked side-effect keys (D45), and M5-8's argument and return shapes never reach an export, MCP, or the CLI, in any exposure mode.
• Memory accounting. The journal status reports the stores' estimated bytes, beside the journal's own, against bootui.runtime-journal.agent-evidence-max-bytes: by default the sum of the stores' fixed caps, about 55 MB, so it changes nothing; a smaller bound shrinks the scalable stores (Code Paths' trees) in proportion, and a store bounded elsewhere, as Code Inventory's first calls by the agent's method limit, is only counted. A hidden store adds its bytes to the total without its own figures.

Journal (§5.2):

• Journal-backed agent evidence is additive RuntimeEvent types, each with the standard envelope and a small interned payload: ASYNC_HANDOFF (a child execution's start and end), and, when M5-6 ships, CAUGHT_EXCEPTION. Side Effects rows (SIDE_EFFECT, THREAD_LOCAL_LEFTOVER, RESOURCE_LEAK, BLOCKING_CALL, SINK_MATCH) and probe hits (PROBE_HIT) were first planned as journal types; each is decided journal-backed or a store under the contract above when its slice ships.
• CAUGHT_EXCEPTION comes from exception-handler entry in application classes, instrumented by the agent: the caught type, the catch site, and whether the handler rethrew, logged at WARN or above, or did neither. Only application code is instrumented, so the cost is paid on the exception path only.
• bootui.runtime-journal.sources accepts agent.<sensor>. Agent records count against the same evidence budget, the same cardinality caps, and the same per-source drop counters, and are pre-aggregated per request so a loop of identical operations is one row with a count.

Runtime model (§5.4):

• Node types method (component boundaries and changed methods only, capped at 5,000), dependency, file pattern, process, and environment variable; edge types invokes, executes, opens, spawns, reads, and hands off to. Agent edges carry the provenance "observed in an owned execution", like other observed edges, with the agent named as their source.

Change impact (§5.7) and run comparison (§5.8):

• Change impact accepts a method as well as a bean or class. With the agent, observed routes become routes whose requests executed the changed code, from the route trees and invokes edges, instead of routes merely reachable through the bean graph; structural reach stays a separate count.
• Run comparison leads with code changes when the agent is active: changed, added, and removed methods, which of them executed, and on which routes. Its behavior rows gain new hosts, file patterns, processes, and environment variables, and bean-boundary methods executed in the previous run but not in this one, reported only for routes exercised in both runs.

Observations (§5.5), each NOT_APPLICABLE with the reason "requires the BootUI agent" when it is absent:

• Since D36, each new observation above ships first as rows in its panel (Side Effects, Code Inventory, or Code Paths) and becomes a Runtime Insights kind only after its seeded case and counterexample pass and an agent-attached external run passes the per-kind gate (§2.3, M4-20). work-after-response and changed-code-not-executed, merged before D36, are judged by M4-20's rerun under the same rule.
• event-loop-blocking extends from JDBC to every blocking operation of the blocking sensor when the agent is active.
• route-time-breakdown gains the handler split of §5.14, and repeated-selects names the application method that issued the repeats.

Agent tools (§5.6), on existing schemas only, each moving in lockstep as PLAN.md §4 requires:

• The verify_after_change prompt (§5.6) starts with get_code_inventory and changed when the agent is active: an agent that finds its edited method not executed runs the test that reaches it, or says so, before reading any latency. When the method still was not executed after that test, the prompt names start_method_probe as the next step: with separate approval, start a probe on the method, rerun the candidate test or route, then read get_method_probe; no hits is evidence the candidate path never reaches the method (wrong route, wrong bean, never wired).
• diagnose_runtime_issue suggests get_code_paths on the exemplar's route after get_request_profile. Wherever get_side_effects's sink matches (§5.16) or get_code_inventory's dependency and reach results (§5.15, vulnerable code reach) surface a finding, it states plainly that these are checks, not a vulnerability verdict: verify against source and configuration before treating a request-input-in-sink or reach result as actionable.
• McpGuidance.instructions gains one line: call get_agent_status once before relying on an agent-only tool or observation, so an agent learns up front whether Code Paths, Code Inventory, and Side Effects questions are answerable at all, instead of discovering NOT_APPLICABLE one tool call at a time.
• assess_application's "Discover and collect" step names start_method_probe beside memory_scan, pentest_scan, vulnerabilities_scan, and database_advisor_scan as needing separate approval before it starts, since it is the one M5 agent tool that acts, even gated by read-only policy.
• The consumer skill (skills/bootui/SKILL.md, mirrored into the Claude Code plugin payload) documents the verify-then-probe workflow as a named step, not just the tool list, so skill-based agents gain the same "did my change run" workflow MCP-native agents get from the prompt text.

Acceptance criteria:

• Every observation above has a seeded case and a counterexample in the sample apps, and is NOT_APPLICABLE with the reason, never empty, without the agent.
• A scripted agent investigation, "did my change to OrderService run?", is answered correctly from tool output alone, and joins the benchmark in §2.2, together with a refusal fixture where an agent must not treat a NOT_APPLICABLE: requires the BootUI agent observation as "nothing to worry about" and ship unverified.
• With the agent detached, every §5.1–§5.12 acceptance criterion still passes unchanged.

5.18 Journal event coverage — Cross-cutting ✅ Delivered

The journal records fifteen event sources, but an audit of what each one records against what §5.5–§5.9 read found two planned features with no evidence to read, and whole kinds of work the journal never sees. This item closes those gaps with framework hooks only, as §1.3 requires. The agent's event types (§5.17) are not repeated here. The audit read v2 after M3-5, together with M2-8e3 and M2-8e4, whose fixes it does not repeat.

What the journal records, and who reads it:

Gaps in the existing sources:

• Authorization is not recorded. security carries only an event type. Spring audits authentication results and authorization failures; Quarkus's capture drops AuthorizationSuccessEvent. A granted anonymous request therefore leaves no trace, and §5.9 has nothing to read.
• Runs carry no comparability facts or startup cost. RunSummary.Header holds ids, times, and counts, while §5.8's NOT_COMPARABLE and restart cost need profiles, data source shapes, cache type, and startup steps.
• Quarkus ORM statements have no duration or connection: the StatementInspector sees them at prepare time, and Hibernate reaches Agroal through its own registry, not BootUI's wrapped pool.
• Reactive data access is invisible: R2DBC on WebFlux, and Vert.x clients and Hibernate Reactive on Quarkus.
• Transactions drop facts the recorder already has: read-only, isolation, and the cause of a rollback.
• Insights project only requests. Scheduled runs and consumed messages have execution ids since M1-6b, but InsightsSnapshot never groups them, so repeated-selects or safe-method-dml stay silent for jobs and listeners.
• AI calls need tracing, because they come from GenAI spans joined by trace id, and jobs are not covered.
• route-time-breakdown leaves AI calls and synchronous sends in "other handler work", although §5.5 names them.
• WebSocket messages are not journaled and open no correlation, so the SQL of a @MessageMapping handler is work with no owner on clientInboundChannel-N.
• spanId is always null: nothing that creates a CorrelationContext sets it.
• Application events, Hibernate's own work, and BootUI's own actions are not recorded: a listener skipped for lack of a transaction, an auto-flush before every query, or a cache cleared from the Cache panel in the middle of a run.

New sources, each recorded only as metadata and each one a bootui.runtime-journal.sources name:

Payloads:

record AuthorizationPayload(String target /* REQUEST or METHOD */, String subject /* route or Class#method */,
        String rule, String authentication /* ANONYMOUS, AUTHENTICATED, NONE, UNKNOWN */, boolean granted,
        int authorities /* a count */) {}
record LifecyclePayload(String kind /* RUN_STARTED, CONTROL, AVAILABILITY, CONFIG_REFRESHED, SHUTDOWN */,
        String target /* logger, cache, or property name; never a value */, Long readyNanos,
        List<StartupStep> slowestSteps, ComparabilityFacts facts) {}
record AppEventPayload(String kind /* PUBLISHED or LISTENER */, String eventType, String listener,
        String phase /* IMMEDIATE, BEFORE_COMMIT, AFTER_COMMIT, AFTER_ROLLBACK, AFTER_COMPLETION, ASYNC */,
        String outcome /* RAN, SKIPPED_NO_TRANSACTION, DEFERRED, FAILED */, String exceptionClass, int listeners) {}
record OrmPayload(String persistenceUnit, int statements, long statementNanos, int connectionAcquisitions,
        long acquisitionNanos, int flushes, long flushNanos, int partialFlushes, long partialFlushNanos,
        int dirtyEntities, int entitiesInContext, int l2Hits, int l2Misses, int l2Puts) {}
record WebSocketPayload(String endpoint, String kind /* OPEN, CLOSE, MESSAGE */, boolean inbound,
        String destination /* a template such as /app/chat/{room} */, long payloadBytes, String closeStatus,
        boolean failed) {}

Never recorded: principals, authority names, or the secured method's arguments; an event's fields or toString(); entity ids or field values; configuration values; credentials or hosts beyond a data source URL's shape (jdbc:postgresql://localhost); WebSocket payloads or session ids beyond the recorder's opaque hash. Framework events (ServletRequestHandledEvent, context, audit, and security events) are excluded from app-event by package.

How each source joins the rest of v2:

Payload enrichments that need no new source, each additive:

Architecture, the same steps for every new source:

1. A JournalSource constant and property name, and a payload with estimatedBytes() and interned(...), published through RuntimeEvent.of(...) (M2-8e4), guarded so publishing never throws into the application, and only while the source is recorded, whatever the panel's capture state.
2. The recorder is a RuntimeEventPublisher, installed by RuntimeEventPublisherInstaller on Spring and by the startup observer on Quarkus; optional types stay in gated classes, as messaging's do.
3. Correlation from CorrelationSource; anchors (messages, listeners) open CorrelationContext.forExecution.
4. Add a capped aggregate dimension with an Other bucket when the source needs a dedicated roll-up. app-event and websocket currently contribute observed edges to run summaries but no dedicated per-type or per-destination count dimension.
5. A feed row type, its masked detail in JournalRowDetails, its persisted form in JournalActivityCapture, and its filter and icon in the UI, leaving the 1.x buffers' feed untouched.
6. Timeline and touched resources in RequestJournalProfiles, with additive DTO fields and contract-catalog entries.
7. Node and edge types in the runtime model, counted in the aggregates once M4-1 lands, with the ReverseClosure allowlist decided explicitly.
8. Source coverage in InsightsSnapshot, and each new observation as a pure class with justified, counterexample, and insufficient fixtures, NOT_APPLICABLE with a reason on a stack that cannot record it, and its theme chip and command-palette keywords.

Out of scope:

• A catch-all source for every Micrometer observation: unbounded shapes and duplicates of dedicated sources. Observations are used as hooks for specific sources instead.
• INFO and DEBUG logs, HTTP headers, and cookies.
• Health status transitions, which would need polling.
• Executor propagation, unless D30 brings Spring's and Quarkus's managed executors in before the agent (M5-2).

Acceptance criteria:

• Every new source is in bootui.runtime-journal.sources, documented in PROPERTIES.md, reported unavailable with a reason where its stack or dependency cannot record it, and counted in the journal status with its drops.
• A DevTools restart and a Quarkus live reload each record one RUN_STARTED with its facts, a profile switch makes a comparison NOT_COMPARABLE, and a data source URL with a user and password records neither.
• A permit-all public route records ANONYMOUS and a protected one AUTHENTICATED on all three stacks, in the conformance runners, and a missing observation registry records UNKNOWN, never ANONYMOUS.
• The sample apps seed a @TransactionalEventListener fired outside a transaction (and one inside, which must not be reported), an AFTER_COMMIT listener that saves an entity, a route with repeated auto-flushes, and a STOMP handler that queries; 100 requests record no framework event as an app-event.
• The correlation scenario nests 100 % of a STOMP handler's SQL under its message on Spring MVC.
• The overhead scenario stays within §8's budgets with every new source on.

6. Architecture

flowchart TB
  subgraph Adapters
    MVC[Spring MVC filter and BootUI-owned exchange repository]
    FLUX[WebFlux context bridge]
    QK[Quarkus Vert.x capture filter]
    HOOKS[Existing capture hooks]
  end
  subgraph Agent[Optional bootui-agent, dormant until claimed]
    ADV[Advice: executors, methods, I/O, sinks]
    BR[bootui-agent-bridge ring, JDK types only]
  end
  subgraph Engine[bootui-engine]
    CC[correlation]
    REC[Existing recorders and ring buffers]
    SINK[journal sink]
    DISP[dispatcher: aggregates, indexes, run summaries]
    J[(Retained evidence rows)]
    P[runtimeinsights projections]
  end
  MVC --> CC
  FLUX --> CC
  QK --> CC
  HOOKS --> REC
  CC -.snapshot.-> REC
  REC --> SINK --> DISP
  DISP --> J
  STRUCT[Structure providers, snapshot per run] --> P
  DISP --> P
  J --> P
  J --> LA[Live Activity feed, profile, persistence subscriber]
  P --> API[REST, UI, MCP, and CLI]
  P --> LA
  CC -.context supplier.-> BR
  ADV --> BR --> DISP

New engine packages: correlation, journal, resources, runtimeinsights, and agent, plus the CorrelationContextProvider SPI. The optional agent adds two modules outside the engine: bootui-agent-bridge, which depends only on the JDK and which the engine depends on, and the bootui-agent jar, which no starter or extension depends on. The dependency direction core <- engine <- adapters is unchanged, as packages since bootui-core folded into bootui-engine (D50), and no shared module gains a Spring, Quarkus, or JSON dependency.

7. Cross-stack availability

Each unavailable cell is returned as availability with a reason and documented in docs/QUARKUS-SUPPORT.md and docs/WEBFLUX-SUPPORT.md.

8. Safety, privacy, and performance

The journal follows the model the 1.x buffers and §3.27 already use: store bounded raw evidence in memory, apply the live exposure policy at read time, and never write to disk anything less masked than MASKED.

9. Cross-cutting work

Every v2 item follows PLAN.md §4, "Every item", and the Runtime Insights panel also follows "Adding a panel". v2 adds:

• the correlation and overhead scenarios in the sample apps, run by CI on v2;
• counterexample fixtures for every observation;
• Spring AOT runtime hints for the new DTOs, and Quarkus production and native absence tests, because Quarkus native BootUI stays out of scope;
• CHANGELOG.md migration notes for every 2.0.0 removal.

10. Risks

11. Validation checklist

Before starting each v2 item, v2 contains the latest main and this plan reflects it (§4.2). Run after each v2 item lands on v2 and before 2.0.0:

• [ ] PLAN.md §6's checklist passes on v2, on Java 17.
• [ ] The correlation scenario meets §2.2's target on every stack, or reports its measured gap.
• [ ] The overhead and projection budgets in §8 hold.
• [ ] Runtime Insights and Live Activity handle empty, unavailable, needs-more-traffic, and partial states with clear reasons.
• [ ] Nothing captures, scans, reads a database, or calls a network on page load.
• [ ] Every exposure mode, and a live change between them, holds in the journal, observations, exports, and MCP output.
• [ ] Every observation passes its counterexample fixtures.
• [ ] With the BootUI agent detached, every panel and observation behaves as without M5; with it attached, the sample apps' browser suites pass, and nothing is instrumented when BootUI does not claim it.
• [ ] Every default-visible observation kind passes its per-kind gate, or is folded into its panel or hidden (D35).
• [ ] Agent evidence kept outside the journal honors the live exposure policy, source-panel visibility, and Clear recording (M5-11).
• [ ] Before 2.0.0: the external-validation report and the agent benchmark pass §2.2's targets under M4-20's registered protocol, with D35's folding applied to every kind that misses its gate; the release sign-off records the results; the release-path changes (M4-16, M4-23) are done.

12. Decisions

Appendix A. Review log

The first draft was audited independently by three models, each with a primary lens and a shared brief to maximize business value: Claude Opus 5.5 (product strategy, S), GPT-6.1 Sol (technical feasibility, F), and Grok 4.7 (adoption and agent value, A). The draft was then reconciled with the reordered v1 plan (commit be7762ab1). A later design review of storage and algorithms (Design review) settled the journal's storage decisions before M2. Two research reviews then assessed new insights (Insights research) and graph or search storage (Storage research). Three insight audits followed, again one per model: GPT-6.1 Sol (evidence and false positives, E), Claude Opus 5.5 (developer value, V), and Grok 4.7 (agents, security, and a contrarian view, G). At the maintainer's request, each also challenged the "no graph database" decision. A later survey of Java agents (Agent research) shaped the optional agent of §5.13–§5.17. An audit of the journal's event types (Journal audit) shaped §5.18. After the first validation run, a remaining-plan audit (Remaining-plan audit, 2026-10-04: Claude Opus 5.5 on value, GPT-6.1 Sol on the agent's feasibility, and GPT-6 Sol on release readiness) and a memo on the post-M3 gate (Gate memo) shaped D35 to D40, M4-19 to M4-23, M5-11, and M5-12.

Appendix B. Proof-of-concept evidence

The proof of concept ran the Spring MVC sample app on JDK 26 twice: with H2 (655 requests), and with PostgreSQL, Redis, Kafka, and Ollama (767 requests). It read 30 BootUI endpoints, built a graph of 7,589 nodes and 14,093 edges, and found twelve patterns. Six of them survive the audit into 2.0 as route time breakdown, transaction hold, unowned work, change impact, run comparison, and anonymous data reach. Its weaknesses define M1: joins by time and thread, a trace id recovered from root spans within ±3 ms, and authentication inferred from span names.