ADR-033: Plugin Manifest + Render Contract (Panel + Case-Section)

Plugin discovery and rendering are reached only through a PluginSource trait — a Tier-O object-safe trait ([async_trait], the ADR-038 §1 default) living in a new craig-plugin-contracts crate. The craig-web BFF (and, later, the composition engine of ADR-035 (anticipated)) hold Arc<dyn PluginSource> and never name the discovery backend. v1 ships one implementation, CompileTimePluginSource, which walks a compile-time registry (§3); v2 adds WasmPluginSource (scanning sandboxed .wasm modules) as a drop-in with no call-site change. The [craig_plugin] macro and the compile-time slice (§3) are therefore v1 implementation details behind this trait, not part of the contract — they are replaceable wholesale when the WASM backend lands. This is the single most important decision in the ADR: it bounds the v2 migration’s blast radius to one crate.

A panel or case-section declares itself in a Plugin.toml (Contract 1). TOML is parseable by both the v1 and v2 backends, so the manifest format is backend-neutral.

The author-facing schema is Contract 1’s, enriched with name/version for identity, a [case_section.<slug>] subtable parallel to [panel.<slug>], and the [data].endpoints list (the routes the host fetches). display_name is a terminology key, not a literal — "{term.child_support}" resolves to the Fluent message term-child-support per ADR-034 §6. PluginManifest is a typed serde struct with a PluginManifestError enum and a validate() parser, all in craig-plugin-contracts. The exact full field set is finalized in Plan W (as ADR-036 deferred the full token list to the Theme Token Schema); this ADR fixes the load-bearing fields, their meaning, and the invariants of §6.

A plugin author annotates the plugin with [craig_plugin(slug = "…", manifest = "Plugin.toml")]. The macro — in a new craig-plugin-macros crate, CRAIG’s first first-party proc-macro and therefore its own crate (proc-macros must be) — expands to a [linkme::distributed_slice(CRAIG_PLUGINS)] static carrying the slug, the manifest text (include_str!, parsed lazily into the typed PluginManifest), and the plugin’s render entrypoint (§4). linkme becomes a workspace dependency (net-new). The slice is a linker-section concatenation resolved at link time — no life-before-main constructor, no runtime registration — so CompileTimePluginSource simply iterates CRAIG_PLUGINS. This ports canopy’s CANOPY_PLUGINS pattern (crates/canopy-composition/src/source.rs + crates/canopy-plugin-macros). Because discovery is reached only through PluginSource (§1), none of this mechanism is load-bearing on the contract.

A plugin does NOT perform I/O. The manifest declares a plugin’s data dependencies ([data], with context placeholders such as {case_id}); at render time the host (the craig-web BFF) executes those manifest-declared, context-parameterized fetches via OutboundTransport (ADR-032 §3.1 + Plan V), honoring the manifest’s auth/cache_ttl/timeout, against the jurisdiction’s own declared endpoint. The host is the sandbox’s I/O executor — it is NOT a data proxy: the endpoint and the data remain the jurisdiction’s (Contract 1: "endpoint is the jurisdiction’s, not core’s"); the host merely runs the call the manifest names. The plugin is then a pure function — it receives a serializable render context (the resolved item’s span/row, the locale, the resolved display_name, the worker’s identity: sub/role/jurisdiction) plus the fetch outcome (Data(json) | Empty | Error), and returns a rendered HTML fragment tagged with the panel state it represents. The plugin owns presentation: it renders the data/empty/error blocks of its compile-time #[derive(askama::Template)] view; the host shows the loading placeholder before the fetch resolves.

Every value crossing the plugin boundary — render context, fetch outcome, fragment + state — is serde-serializable from day one. In v1 these are passed in-process; in v2 they serialize across the WASM boundary with no contract change. This is the concrete debt-avoidance decision: a render entrypoint that took non-serializable Rust handles (an Arc<dyn OutboundTransport>, a live DB pool) could not move to a sandbox.

Two invariants protect this boundary, and Plan W must hold them. First, no value crossing it carries a non-serializable host capability — no Arc<dyn _>, no connection pool, no live handle; the render context carries resolved values only (a capability that cannot serialize cannot cross a sandbox, so admitting one would silently re-couple v1 to the in-process backend and break v2). Second, the plugin never receives credentials: the host resolves the manifest’s auth, owns the outbound call, and is responsible for enforcing jurisdiction boundaries — a worker in one jurisdiction must never be served another’s data, even when both jurisdictions' endpoints are reachable from the host. Relatedly, the plugin’s returned HTML is CSP-bounded, not runtime-sanitized: the strict CSP (no inline script or style) is the runtime defense and the build-time lint (§6) the author-time one; a plugin is trusted to emit token-styled, class-based markup, not arbitrary <script>/<style>.

This deliberately diverges from canopy, whose plugins do their own I/O (a fetch() taking ServiceClients). In-plugin I/O is not portable to a capability-free sandbox; host-fetches-pure-render is. It also refines the CRAIG_PLUGIN_TEMPLATES sibling-slice sketch the umbrella Step 17 anticipated: an Askama template is a type (a struct implementing Template), not a value that can live in a static slice, so "register the template" necessarily collapses into "register a render entrypoint that builds and renders the template from fetched data." v1 carries that entrypoint in the single CRAIG_PLUGINS registration alongside the manifest — there is no second template slice to keep in sync.

ADR-032 §4 and Contract 1 anticipated a plugins: Vec<PluginManifest> field on BundleContribution. This ADR does NOT add that field. With discovery sourced through PluginSource (the v1 slice; the v2 WASM loader), a hand-built Vec<PluginManifest> on the aggregate would be a second source of truth competing with both — a manifest baked into the slice by the macro and re-declared on the contribution would inevitably drift. Instead the BFF materializes a PluginRegistry once at boot by asking the active PluginSource, holding it in AppState exactly as it holds the materialized theme_css string and the I18n terminology table (ADR-036 §4 / ADR-034 §4: the consuming host materializes the axis it consumes). The boot orchestrator validates that registry in the same atomic pass it validates the rest of the aggregate (§6), so the plugin axis keeps the "validated alongside the aggregate" property Contract 1 requires without duplicating data.

Per ADR-038 §3 + ADR-032 A11, the registry shape is documented: the PluginRegistry is PRE-MATERIALIZED (a value, not a BootContext factory) — a plugin’s manifest and render entrypoint are known without any boot-time shared resource; the host supplies the transport and the render context per call, not at construction. This refinement is recorded as ADR-032 amendment A12 (A11 had listed the anticipated field as pre-materialized; the amendment records that the field is not added and the axis is sourced via the slice, the registry still pre-materialized). Cargo-feature gating — the established state-bundle mechanism — is the expected means of scoping the compiled-in v1 plugin set to the active jurisdiction; the exact wiring is a Plan W detail, not a contract guarantee.

At boot the BFF validates the active plugin set (the posture of ADR-036 §8 / ADR-034 §8): every slug is unique; every display_name terminology key resolves in the active bundle’s TerminologyContribution (a cross-axis check tying to ADR-034); every required_role resolves against the active jurisdiction’s role set (conditional on the role source Plan W settles — see Open questions; the other checks are unconditional); and each manifest is structurally complete (states_required fully declared, [data] and [permissions] present). A miss is a typed PluginBootError and craig-web refuses to start — a dangling role reference or an unresolved label must surface at the boundary, not as a broken panel an end user finds.

The presence of the four state blocks in a plugin’s template is a BUILD-TIME lint (xtask lints four-state-contract), not a boot check: templates are compile-time artifacts, so verifying their blocks belongs to the build, exactly as ADR-036 §8 keeps aesthetic checks (contrast, hardcoded hex) in a build-time lint off the boot path. Plan W implements both the boot validation and the lint.

Plugin authoring is a Rust task: core engineers and external contributors write a crate with #[craig_plugin] + Plugin.toml + a pure render function + an Askama template carrying the four state blocks. Jurisdiction operating is config only: an operator references plugin slugs in rulesets/<jurisdiction>/dashboards.toml — no Rust. The design language’s "everything is config" describes the operator experience; authoring remains Rust. This ADR fixes only that the operator surface selects plugins by slug; how dashboards.toml and its override layers resolve into a rendered page is the composition engine of ADR-035 (anticipated) / Plan X, out of scope here.