The brick never changes for this: it is used outside Vidocq and depends on no Vidocq SPI, in or out of a -dev module. The runtime extension keeps the startup-report section — it is not a dev tool, it prints in every mode, production logs included — and drops only the live half, sample/charts/actions, into the -dev module next to it, same parent, same version, artifact id suffixed -dev, JPMS module name suffixed .dev: vidocq-runtime-mansart-pool-extension-dev, module io.vidocq.runtime.extensions.jakartaee.web. mansart.pool.dev. Nothing else ever depends on the -dev module, and it is never a dependency of anything that gets packaged.

The -dev module declares a io.vidocq.runtime.spi.devconsole.LivePanel as a service, not a DevConsolePanel:

It writes no section of its own: id() names the startup-report section the runtime extension already writes, and the console pairs the two — the section for the title and the boot facts, the live panel for everything sampled. Its Javadoc’s rules: start and stop each run once per boot, a dev reload included, in that order around every sample; the rules of DevConsolePanel still apply to sample — memory only, never blocks, never creates a bean, no secret in a value. A live panel that has no matching section is never shown (VIDOCQ-DEVC-008); a section whose own contributor is already a DevConsolePanel loses to a live panel of the same id (VIDOCQ-DEVC-009) — never both.

Declared as any service, provides for the module path and the file for the class path:

The console loads every LivePanel it finds this way (uses io.vidocq.runtime.spi.devconsole.LivePanel; in its own module-info) and matches each to the section of the same id.

The runtime extension names its -dev companion in one file, so that an application declares nothing and vidocq:dev finds it on its own:

One line, the companion’s artifactId — its groupId and version are the runtime extension’s own, which vidocq:dev reads from the resolved jar itself. Blank lines and lines starting with # are ignored. A file holding more than one artifactId, or one that is not a valid Maven identifier, is unreadable: vidocq:dev logs a warning naming the jar, and that extension gets no companion — it never fails the goal.

The -dev module never reaches the runtime extension’s implementation packages — those stay closed. The runtime extension exports one small .live package to its companion only, exports <package>.live to <the -dev module>;, and nothing else sees it: a qualified export to a module that happens to be absent (every binary, every launch but vidocq:dev) is legal, so the runtime extension works alone.

What that package holds is either of two shapes, both public, read-only, and free of any Vidocq SPI type but ExtensionContext:

Either way, the -dev module’s own class — PoolsLivePanel, HealthLivePanel, RestLivePanel, MetricsLivePanel — stays package-private: only its LivePanel service registration, never a compile-time dependency, is what the console needs.

The -dev module’s pom.xml marks its own jar Vidocq-Dev-Only: true, the block every dev-only module in this repository carries (Dev tools and binaries):

That one entry is what vidocq:run, the packaging goals and vidocq:checkpom read: whatever the declaring scope, a jar that carries it never ships, and a project that declares it anyway is warned, never failed.

An extension with a VidocqExtension class implements DevConsolePanel next to it. It is found with no second declaration, and its section comes with those of the extensions, in the order they start:

This is the case of the Mansart pool extension, and of most extensions. The panel reads the fields the extension already fills in its lifecycle, and clears them in its onStop.

Some extensions have no Java class at all. The Knock, Dirac and Heisenberg extensions are wrappers: a pom.xml and a module-info that bring the component in, which then integrates through standard CDI and JAX-RS discovery alone.

Their panel goes into the wrapper all the same. For Knock, that is one adapter class, such as KnockHealthPanel, in vidocq-runtime-knock-health-extension itself, declared as a service through ServiceLoader: provides io.vidocq.runtime.spi.report.StartupReportContributor in the module-info, and the same class in META-INF/services. It is never a VidocqExtension, and it never goes into a new artifact beside the wrapper: that layout was weighed against this one and rejected, for the reasons above (Where the panel lives NEW).

Knock’s ADR-002 (docs/adr/ADR-002-vidocq-runtime-integration-strategy.md in the knock repository) is where the class-less shape is written down, and the panel departs from it, deliberately:

The rest of the wrapper’s shape stays: no VidocqExtension, no lifecycle and no priority, so option A stays rejected.

A wrapper around a component, Ledger, whose @ApplicationScoped LedgerStats bean keeps its counters in memory:

It is declared twice, as every service contributor is (Contributing to the startup report): provides for the module path, where the JDK ignores META-INF/services in a named module, and the file for the class path.

Every wrapper has the standard layout: module-info.java in src/main/java, compiled with the code, and the tests on the module path. (The Knock, Dirac and Heisenberg wrappers used to keep their module-info.java in a source root of their own, src/main/module-info, compiled late in prepare-package; that workaround was removed in 2026-10.) The first class therefore goes into src/main/java next to the others, and its provides into the wrapper’s module-info.java.

What changes for a service:

A wrapper that only has boot facts to show implements StartupReportContributor alone, declared the same way: every section is a panel of the console, with its boot facts. Knock’s KnockHealthPanel is such a case for now, a class of the wrapper like any other: its checks can be listed by probe, but their status is only known by running them, which a sample must not do (sample() reads memory only NEW), until Knock keeps its last result in memory. Implement DevConsolePanel when there is something to sample.

A section can offer to open something the application serves, such as a user interface or a document: section.link("Swagger UI", "default", "/openapi/ui/"). The log prints a row, the label then the absolute URL; the console shows a button under the panel’s title that opens it in a new tab.

A panel never writes a URL. It names a listener and a path, and Vidocq joins them with the address that listener really bound, as it does for route(): the http section declares the application’s listeners. A link whose listener no section declared is printed as its path and gets no button. The page only makes a link of an absolute http or https URL, opened with rel="noopener noreferrer".

A GET route with no template variable, such as GET /openapi, is a URL a browser can open as it is: its URL in the route table is a link too.

An extension that serves a page on a listener it does not describe itself advertises it instead, with ChappeMountPoint.instance().advertise(listener, label, path) from its onStart. The sections that describe that listener offer to open it without knowing the extension: the Swagger UI extension advertises /openapi/ui/, and the rest panel shows the button.

PanelAction.Argument.json(String name, String label, String schema) takes a JSON document rather than a string: schema is a JSON Schema, as the text of a JSON object of at most 32 KiB, checked when the argument is built, or the constructor throws. One action has at most one json argument, beside any oneOf and matching ones, and the value reaches call as its JSON text, in the same Map<String, String>. accepts(String) stays the only check: for a json argument it means "parses as a JSON object", whatever its length.

The page renders it as a form generated from the schema when the schema allows one, an object of scalars one level down included (the generated form NEW), and as the JSON editor NEW otherwise, which colours, checks and completes the value against the schema, whose keywords that page lists; the console never validates the value against the schema itself — the action’s target does. The MCP inspector’s own tool action is a short example (TestPanels.InspectorPanel’s `tool.weather):

A string property whose schema also says "format": "textarea" NEW is a field of several lines in that form rather than a one-line one: four lines of monospace text to start with, taller when dragged, its value sent as any other string’s.

Such a field whose schema also says "contentMediaType": "text/x-query" and "x-language": "<id>" NEW is the query editor, which colours, completes and checks a query with the vocabulary of the panel’s language of that id, and one that says "x-parameters-of": "<query property>" NEW is the JSON editor of that query’s parameters, its schema following the query (A query language for a panel). The Mansart Data panel’s JDQL tab uses both for its statement and its parameters (A JDQL console for Mansart Data):

Such a field whose schema also says "contentMediaType": "text/csv" NEW gets a Choose file input next to it: the file picked is read by the browser and replaces the field’s value, nothing being sent until the form is. It is read as UTF-8, then again as Windows-1252 when it is not UTF-8 (as a spreadsheet of a decimal-comma locale saves CSV), the line under the input saying read as Windows-1252 (not UTF-8). While the field still shows the file unedited, the form sends the file’s own text, its \r\n line ends kept. The same file can be chosen again; a file whose reading ends after the form was sent is dropped (the form was sent before the file was read: choose it again). A file larger than 60 KiB is not read, the file is larger than 60 KiB showing under the input. The console’s 64 KiB limit on a request stays the last word, and a CSV text grows a little once sent as JSON. The Mansart Data panel’s Import CSV uses it (CSV export and import for Mansart Data):

The 7-argument constructor, PanelAction(id, label, confirmation, arguments, call, group, description), takes a Function<Map<String, String>, ActionResult> call in place of run: call returns an ActionResult(summary, contentType, body, error, details) rather than one line.

A body or details longer than 256 KiB is truncated, ending with … truncated at 256 KiB.

The old constructors keep working unchanged: PanelAction(id, label, confirmation, arguments, run) and PanelAction(id, label, confirmation, run), with run still a Function<Map<String, String>, String>, wrap it as args → ActionResult.of(run.apply(args)) internally, and run() still returns a function to the summary line, so an action written before this section existed answers exactly {"result": "…​"}, as before.

The records themselves gained components, though: PanelAction is now (id, label, confirmation, arguments, call, group, description) and PanelAction.Argument (name, label, allowedValues, pattern, schema). Code that builds actions and calls run() is unaffected; a record deconstruction pattern such as case PanelAction(var id, var label, var confirmation, var arguments, var run), or reflection over the record components, written against the old records must be updated. equals now compares the internal call, and each constructor wraps an old run anew, so two actions built from the same run are no longer equal.

Two more optional fields, both on every constructor:

Past ten actions of a group, the page adds a text filter above its list; past ten ungrouped actions, one above the panel’s own buttons. A panel keeps 128 actions at most; an id seen again, or one past the 128th, is dropped, as an id actions() returns twice always was.

A table column headed PanelSample.REPLAY_COLUMN ("replay") turns each of its cells into a "Replay" button on the page: the cell is the id of an action of the same panel, a space, then a JSON object of its arguments by name, such as tool.weather {"arguments":{"city":"Paris"}}. The button fills that action’s form with those arguments and sends nothing; the user still has to submit. A value of "*" inside such a cell is left empty instead, for the user to type again — how the MCP inspector’s history marks an argument it masked as a secret.

The console keeps such a cell whole up to PanelSample.MAX_REPLAY_CELL, 4,096 characters, and empties a longer one rather than truncate it into something that would not parse. A cell of that column that is not of this form, or whose id is no action of the panel, is shown as text, cut at 200 characters as any other cell; the column keeps its header unless at least one of its cells is a Replay button.

When the panel’s actions have groups, the table is shown in the group sub-tabs rather than in Monitoring, each sub-tab keeping the rows whose cell names one of its own actions. A row whose cell names no action of the panel — one a dev reload orphaned, or a cell emptied for its length — is left out there.

No I/O, no network, no blocking call, no lock the application may hold, no bean created, nothing logged; well under a millisecond.

No bean created is the part that is easy to break. A panel that reads CDI beans keeps their Bean metadata, resolved once in onStart, and asks the bean’s Context for the instance it already has, with the single-argument Context.get, which returns null rather than creating one; holding a client proxy obtained at boot and calling it from sample creates the bean on the first poll of the page. McpExtension, in vidocq-runtime-langchain4j-cdi-mcp-extension, does it that way for a concrete reason: creating McpSessionManager starts its mcp-session-cleanup thread, so a panel that merely observes would start a thread, every second, on an application that asked for nothing (the mcp panel). A bean with no instance has no number to give, so the value is written absent with the reason — no request served yet, not created yet — never a zero.

Why: the page polls about once a second, per open tab, on the request threads, several at once. A panel that ran a query, called a service or ran the health checks on each poll would make the console a load generator, and its figures would measure the console. A panel that took a lock the application holds could stall the application’s own threads. A value that only I/O could give is left out, or written absent with the reason; when it matters, the component keeps it in memory and the panel reads that. contribute follows the same rule, for the report’s sake. The console times every sample and flags one above 5 ms slow.

What sample reads is one volatile field that holds an immutable value — a record, a List.copyOf — assigned once complete, and cleared first thing in onStop, before what it refers to is closed. sample reads the field once, into a local variable, and works from that.

Why: the polls arrive on Chappe’s virtual threads, while the boot thread fills the extension’s fields and, on a dev reload, tears the extension down. A volatile field makes what the boot thread wrote visible to the request threads; an immutable value never changes under the reader, so a poll never walks a collection that onStop is clearing (a ConcurrentModificationException); one read gives one consistent state, where two reads could straddle a reload; and clearing it before closing means a late poll finds nothing rather than a closed pool.

No static field holds a Class, a bean, a proxy or any object of the application.

Why: the SPI and the runtime extensions stay in the boot layer across dev reloads, while the application’s modules are loaded again in a new layer. A static field of an extension outlives the reload: holding a Class of the previous application, or an object whose class is one, keeps that whole layer in memory, and hands the next boot objects of classes it no longer uses. Keep per-boot state in instance fields; a static field may keep a plain value, as the console keeps the port it bound.

Why: the report goes to logs that are shared, pasted into issues and kept, and the page is served to a browser. A value that was never written cannot leak.

id() is the name of the section and of the panel, such as mansart-pool: lowercase, stable across boots and releases, and unique. startup, config, cdi, logs NEW, tests NEW, jvm and devconsole are the console’s. Chart ids and value keys follow the key rule, and stay the same from one boot to the next.

Why: the id is how a reader finds the section in a log, and how the report keeps a section from appearing twice: a second contributor with the same id is skipped as VIDOCQ-RPT-002, and so is one that takes startup, config, cdi, logs, tests or jvm. The history is keyed by panel, group and value key: a key that changes between two ticks starts a new curve.

A RuntimeException or a LinkageError thrown by sample drops that poll’s live values, never the page: the tab shows the class of the exception, never its message, which may carry a secret, and the boot facts stay. The console logs VIDOCQ-DEVC-005 once per panel and boot, its stack trace at DEBUG, and calls the panel again on the next poll. charts() that throws leaves the panel without charts. A failing contribute costs the section, as for any contributor (VIDOCQ-RPT-001).

MansartPoolExtension no longer implements DevConsolePanel: charts() and sample(PanelSample) moved out, and its module no longer requires io.vidocq.runtime.spi.devconsole at all — contribute, the boot facts below, is all a StartupReportContributor needs. PoolsLivePanel, in the -dev module, is the LivePanel service that makes the mansart-pool section live; see Step 4: the -dev module’s live values, one group per pool NEW.

One record per open pool, built once when the pool opens, that holds no secret — the URL is already redacted. This is unchanged by the split: it still feeds the boot facts of Step 3: the boot facts NEW.

The pools open in beforeStart, before the container, so that the extensions after this one find them. Once every pool is open, the extension publishes two things: its own views, for contribute, and, to MansartPoolsLive — the small public holder in the module’s qualified-exported .live package — the label and the MansartDataSource of each pool, for the -dev module’s panel:

and both are emptied before any pool is closed, the holder first — a dev console poll from that instant reads no pool:

MansartPoolsLive itself, in io.vidocq.runtime.extensions.jakartaee.web.mansart.pool.live, is the whole of what the -dev module ever reads from this extension — a holder, not a proxy, with no lifecycle of its own:

and the module exports that package to its companion only:

The unnamed pool is labelled @Default, which no pool name can be mistaken for, a pool named default included. Named pools follow in name order.

contribute reads the list once, writes the summary at every level, the rows of each pool at DETAILED only, then the anomalies found in onStart:

Every row of a pool starts with its label, which is how the page puts it on the pool’s card. The URL and the user are configuration values, written in a dev launch only; outside it, the pool’s row names the database kind:

The H2 example, launched in dev, logs:

In prod, the same rows read @Default h2 mem, and there is no user row.

PoolsLivePanel, in vidocq-runtime-mansart-pool-extension-dev, is the whole of the live half. It opens no pool and closes none — it only reads MansartPoolsLive.pools(), the holder Step 2 publishes and clears. Its sample writes one group per pool, from the pool’s own counters: MansartDataSource.snapshot() reads them without a lock and without I/O:

No start(ExtensionContext) override: MansartPoolsLive is filled and cleared entirely by the runtime extension’s own beforeStart/onStop, so the panel has nothing to resolve on its own when the console starts it. Once the holder is cleared — the boot stopped, or a dev reload is between two boots — sample writes no group at all: an empty loop, not an anomaly.

What the snapshot carries for one pool:

The panel’s documentation also says how not to read these gauges: maxSize - active - idle is not free capacity, since a borrower still opening its connection counts in none of them, and a snapshot is not atomic, since each figure is read on its own.

charts() moved to PoolsLivePanel too — the same two charts, unchanged:

connections stacks the idle connections on the active ones under the dashed maxSize, with the waiting borrowers as a line; throughput plots borrows and timeouts per second. Both are declared once and drawn on each pool’s card, since each group holds their keys.

PoolsLivePanel’s `module-info.java declares the service, and nothing else about the runtime extension’s own package:

and its descriptor is what the runtime extension carries, so that vidocq:dev finds this whole module on its own:

The recording section keeps the summary, the rows in order and the anomalies, a secret as the report prints it, configured or not configured; a StartupReportContext record gives the launch mode and the level. The tests drive the extension as Vidocq would — configure, beforeStart, onStart — and read what it wrote, exactly as before the split:

PoolsLivePanelTest, in vidocq-runtime-mansart-pool-extension-dev, drives PoolsLivePanel directly — never the extension’s sample/charts, which no longer exist — but still boots the real extension to open real pools through MansartPoolsLive, the holder Step 2 publishes:

boot(…​) still runs the real extension’s configure/beforeStart, since that is what fills MansartPoolsLive; panel.sample(…​) and panel.charts() are what the test actually calls now. afterTheHolderIsClearedTheSampleWritesNoGroup is the -dev form of "once stopped, the panel shows nothing": with a holder cleared by the extension’s own onStop, the equivalent check for a live bean recomputed from ExtensionContext (Knock’s, Dirac’s) is to call the panel’s own stop() and sample again.

The tests worth writing for any panel:

Then see it for real: run mvn vidocq:dev on an application that has your extension — and Chappe, so the console has something to serve it on — open the URL, and read GET /api/snapshot, the document the page draws, to check what your panel sends.