Plan X: Composition Layer Engine (child plan of Plan S umbrella)

Write-API surface shape — PUT-with-If-Match vs PATCH-append vs higher-level Studio verbs, and whether deletes archive (canopy keeps a *_archive table). X5/X8/X9 settle the concrete endpoints; the ADR-035 §5 schema + ETag concurrency are fixed.

CompositionContribution payload — the exact pre-materialized field contents (a surface registry; whether the compiled product-default rides on it or sits beside it in crates/craig-composition); ADR-035 §8 fixes the invariant (baselines runtime-loaded, never bundle-embedded), X1 settles the payload.

Baseline hot-reload — whether rulesets/<jurisdiction>/ composition baselines join the JDM-rulesets RMQ reload path or are read once at boot; X3 decides (the live-override layer already covers no-deploy changes).

Case-section (context-parameterized) plugins on composed surfaces — case-detail items whose [data] carries {case_id} need the page/case context the composition tree supplies; X7 wires the composed RenderCtx.item + context, extending Plan W’s context-free render route.

Per-jurisdiction role sets — role overrides + role-filtering use CRAIG’s fixed 6-role realm set (the Plan W v1 decision); a jurisdiction-contributed role registry is future work (the multi-jurisdiction authz arc).

Write-API shape (ADR-035 §9) — resolved at X5/X8/X9.

CompositionContribution payload (ADR-035 §8/§9) — resolved at X1.

Baseline hot-reload granularity (ADR-035 §9) — resolved at X3: baselines are read once at CompositionLoader boot and cached, NOT re-read per request and NOT joined to a hot-reload path. CRAIG’s existing JDM-ruleset "runtime load" reloads from the database over RabbitMQ (ruleset.changed.*, ADR-024), not from files — there is no file-reload precedent to join — and the live-override DB layer (X5/X6) already covers no-deploy changes, so a baseline file edit is an ops action taking effect on the next restart / reseed (exactly like the seeded JDM rulesets). The X6 composition.invalidated fanout remains the natural hook if cross-replica baseline refresh-without-restart is wanted later (additive, not required to mirror existing behavior).

Baseline file path/name — resolved at X3: the loader reads rulesets/<jurisdiction>/<surface>.toml where <surface> is the engine’s canonical ComposableSurface::as_snake_case() — i.e. dashboard.toml + case_detail.toml (singular dashboard, matching the compiled defaults/dashboard.json + the surface wire form). This supersedes the body’s earlier loose “dashboards.toml” (plural); the X3 + X10 cells were corrected. X3 establishes the .toml baseline convention (the loader reads it) but ships NO repo-root rulesets//.toml — the first land at X10; the X3 test fixture lives under the service’s tests/fixtures/. When the real baselines land they coexist per-jurisdiction with the .json JDM rulesets (the xtask rules check .json-only gate ignores .toml).

ComposedItem.required field — added at X3 (additive, #[serde(default, skip_serializing_if)]): the engine’s X1 ComposedItem { item, span, row } had no home for the ADR-035 §3 required = true floor, so X3 added required: bool to carry the baseline’s mandatory-placement flag through the merge into the resolved tree (omitted from the wire + content hash when false, so existing all-optional trees are unperturbed). The loader’s required-floor enforcement guards Steps 5/4’s override + delta layers; at X3 (no override/delta layers) it is a no-op guard, unit-tested directly.

ResourceType::Composition + authz rulesets — added at X3: a new ResourceType::Composition variant (so ruleset_name_for yields {jurisdiction}-authz-composition) plus the georgia/texas composition authz rulesets. Because the boot coverage check iterates ResourceType::iter() for EVERY service, the two rulesets are required for all services' coverage; composition read is granted to any authenticated worker (the post-merge role filter governs visible panels).

user_delta_v1 envelope + dashboard-only validate — resolved at X4: the envelope is a [serde(tag = "type")] enum with the V1 variant [serde(rename = "user_delta_v1")] (faithful to the canopy port — the wire tag IS the envelope name, so user_delta_v2 lands additively; supersedes the body’s loose “rename_all = snake_case” phrasing). apply_user_delta + validate_user_delta live in the engine (crates/craig-composition-engine/src/user_delta.rs, pure — Depends X1 only). validate_user_delta is dashboard-only (no surface param — case-detail user layers use RFC 6902, which the write endpoint routes away before calling validate) and scans PluginSource::list() for panel exports (CRAIG has no canopy find_panel). The required-panel floor is a CRAIG addition over canopy’s 4 arms — a UserDeltaError::RequiredPanelHidden arm enforces ADR-035 §3 against ComposedItem.required (the field X3 added; canopy’s ComposedItem had none). The loader integration of apply_user_delta on the dashboard user layer is the soft X3↔X4 enhancement that lands with X5’s DB override rows.

composition_overrides schema refinements — resolved at X5: the ADR-035 §5 UNIQUE (jurisdiction_code, role, user_sub, surface_key) is materialized as UNIQUE NULLS NOT DISTINCT (PostgreSQL 15+; CRAIG targets 18) — load-bearing, because a plain UNIQUE treats NULL`s as distinct, which would let two jurisdiction-live rows (both scope cols `NULL) coexist for one surface AND break the ON CONFLICT upsert’s conflict inference on the NULL-scope layers. A CHECK (role IS NULL OR user_sub IS NULL) enforces the three unambiguous layer shapes (a user-delta row is keyed by user_sub alone — the worker’s role is read from the request, never stored — so role + user_sub are never both set, keeping the fetch_db_layers user-arm user_sub = $4 exact). The write helpers use IS NOT DISTINCT FROM for NULL-safe scope matching (a plain = never matches a NULL scope column) and a GREATEST(clock_timestamp(), updated_at + interval '1 microsecond') monotonic guard so every write yields a fresh, strictly-ordered ETag.

Loader DB-layer wiring + the dashboard-user envelope-only decision — resolved at X5: resolve is now async (fetches the override rows via db::fetch_db_layers) and delegates to a pure resolve_with_layers(key, &[OverrideRow]) so the merge / role-filter / floor logic stays unit-testable with in-memory layers and no database (the I/O is isolated to fetch_db_layers). The jurisdiction-live + role layers (and the case-detail user layer) merge as RFC 6902 in value-space; the dashboard user layer is the user_delta_v1 envelope by design (Step 4), applied to the typed items after the role filter — and a dashboard user row that does NOT parse as a valid envelope fails closed (MalformedUserDelta) rather than being reinterpreted as index-based RFC 6902 ops (a deliberate divergence from canopy’s defensive try-envelope-then-RFC-6902 fallback, which would apply ambiguous index paths to a role-filtered subset). The X3 trusted/untrusted export-resolution distinction is now implemented: a baseline / jurisdiction-live (trusted) unknown slug hard-fails; a role / user (untrusted) stale slug is dropped with a warn.

required floor snapshotted from the trusted tier — resolved at X5 (X5 adversarial-review finding): the floor’s source of truth is the set of required = true slugs captured from the TRUSTED tier (baseline + jurisdiction-live) BEFORE the untrusted role / user layers apply — NOT from the fully-merged tree. Otherwise an untrusted RFC 6902 op could disarm the floor by flipping required to false (any surface) or remove-ing a required section (case-detail) before the post-merge snapshot, defeating the ADR-035 §3 "no override or delta may hide a required panel" invariant. The trusted tier includes jurisdiction-live (trusted ops config, co-equal with the baseline — it may legitimately add/relax a jurisdiction’s required panels); the role + user layers may not. Regression tests cover both vectors (role-flip-then-hide; case-detail required remove).

Write-API surface (append / delete / archive deferral) — resolved-in-part at X5: the step ships the core PUT-style upsert_override (create-if-absent + If-Match replace, the ETag + monotonic-guard machinery) needed to round-trip a write; canopy’s append / delete / archive write verbs are deferred to X8/X9, where the concrete Studio + user-delta endpoint shapes decide which they need (per this body’s "Write-API surface shape — X5/X8/X9 settle the concrete endpoints" deferral; YAGNI over porting all verbs speculatively). The write helpers ship behind a scoped ![allow(dead_code)] (staged-delivery, the services/craig-exchange/src/transitions.rs precedent) with a round-trip [ignore = "requires devstack"] integration test; no endpoint mounts them until X8/X9, and the dashboard read handler still resolves with user_sub = None until X9 wires personalization.

Cache structure + the memory model — resolved at X6: the per-replica cache (services/craig-composition/src/cache.rs) ports canopy’s RwLock<HashMap<CompositionKey, …>> structure + the invalidate_* methods, adding the bounded TTL canopy’s single-replica v1 lacked. It uses a std::sync::RwLock (not tokio) because no .await is held under the guard — get/insert/retain are synchronous — and recovers a poisoned lock via PoisonError::into_inner (the workspace denies expect/unwrap in production; the cache ops are panic-free so a poison cannot actually occur). Per the X6 adversarial review, insert sweeps the expired entries first, so the map is bounded by the active (within-TTL) keyset rather than growing with every key ever seen — material once user_sub keys go live (X9). Expiry is also lazy on read (an entry past the 10-minute TTL reads as a miss). The cache is consulted at the top of resolve (check → miss → fetch_db_layers + resolve_with_layers → insert); resolve_with_layers stays cache-free so the loader unit tests are unaffected. The invalidate_jurisdiction / invalidate_role / invalidate_user blast radii are each scoped to (jurisdiction, surface) (the event carries the surface, so eviction need not be jurisdiction-wide across surfaces).

composition.invalidated fanout (ADR-035 §6; ADR-022/ADR-024) — resolved at X6: an override write stages the event via the transactional outbox (craig_mq::stage_event inside the write txn — never a direct publisher.publish, so a broker outage cannot lose it relative to the write); the X2-spawned outbox worker drains it to craig.events. The routing key is composition.invalidated.<jurisdiction> and each replica subscribe_exclusive-binds that exact key on a per-instance auto-delete queue (craig.events is a topic exchange), so a peer in another jurisdiction never receives it. The emitter self-skips by instance_id (the envelope has no native origin field — the per-replica UUID rides in the payload, the craig-rules precedent). The subscriber’s handler (cache::handle_invalidation_event) parses the payload scope and evicts the matching entries; a malformed payload is a no-op (the TTL backstop still self-heals).

instance_id lives on the CompositionLoader — resolved at X6 (review finding 2): the per-replica id is minted once on the loader (the request-path Extension), not as a free-floating value, so the Step 8-9 write handlers stamp the SAME id (via loader.instance_id()) that this replica’s subscriber self-skips on — otherwise the self-skip would silently no-op. Mirrors how craig-rules holds its id on the engine.

Invalidate-on-write wiring + the cross-replica test are X8/X9 — resolved-in-part at X6: events::stage_invalidation (the publish primitive) ships staged behind a scoped ![allow(dead_code)] (no write endpoint until X8/X9, which also evict the writer’s own keys synchronously after commit). The shippable’s two-instance cross-replica integration test is deferred: a true two-replica test is not feasible in the single-instance devstack/e2e harness, and the ADR-024 subscribe_exclusive fan-out is already proven in production by craig-authz + craig-rules. X6 coverage instead = the cache unit tests (TTL, insert-sweep, the three blast radii), the handle_invalidation_event self-skip + dispatch + malformed-payload unit tests, an [ignore] outbox-stage round-trip DB test, and the pre-push devstack boot exercising the subscriber’s subscribe_exclusive declare/bind.

BFF reaches the engine via a typed-contract dep, not "no new deps" — resolved at X7: this body’s X7 cell said "no new deps on craig-web", but the BFF must deserialize the engine’s ComposedSurface wire type. craig-web takes a dep on craig-composition-engine — the PURE engine crate (serde + json-patch + sha2; NO sqlx/craig-mq/craig-db) — used only for that type, exactly as it already depends on craig-cases-contracts / craig-plugin-contracts for typed contracts. The load-bearing invariant is ADR-004 (no state dependency), NOT a literal zero-new-deps; a tests/architecture_invariants.rs grep enforces the real invariant (no sqlx/craig-mq/craig-db in the BFF manifest). The "reuse the shared reqwest::Client + Plan-E primitives" intent holds — the CompositionClient rides the existing Transport, adding no HTTP/identity machinery.

Composed grid span via CSS class, not inline style — resolved at X7 (X7 adversarial-review finding): the dashboard composed-grid cell sets its grid-column span via a per-breakpoint class (composed-grid__cell—​span-{1,2,3,4,6,12}), NOT an inline style="grid-column: span N". craig-web’s CSP locks style-src to 'self' with no 'unsafe-inline' (#414), so an inline style would be silently dropped by the browser and the engine-decided placement lost. The breakpoint set is finite (BREAKPOINT_SPANS), so a fixed class set covers every valid span. (The CSP probe inspects the response header only; it would not have caught a dead inline style — a template-grep lint for style=" is a sensible future hardening, noted not built.)

Case-detail surface rendering deferred — resolved-in-part at X7: the CompositionClient is surface-generic (resolve_surface(surface, …) works for dashboard + case_detail), but only the dashboard surface is wired into a route. Case-detail rendering needs case-section plugins + a case_detail baseline (neither exists until X10) AND the case-section context ({case_id}) substitution into the plugin endpoint — a distinct lift. Wiring an always-empty, untestable case-detail composed region now would be speculative (YAGNI); it lands with X8/X9/X10 when there is something to render. The body’s "renders the resolved surface (dashboards + case-detail)" is satisfied for the dashboard end-to-end; case-detail is plumbing-ready on the client side.

Composed dashboard is empty until X10 — noted at X7: with no GA baselines (rulesets/georgia/*.toml) and an empty force-linked plugin registry in craig-composition, the engine resolves the dashboard to the compiled product-default (grid shell, zero items). So X7 ships the full wiring + ADR-028 auth pass-through end-to-end, but the rendered grid is empty until X10 populates baselines + force-links plugins. The composed region renders only when non-empty, so the existing static dashboard tiles are unaffected meanwhile (no regression).

Studio scope at X8 = the dashboard-layout control, not panel reorder/hide — resolved at X8: the X8 cell’s shippable ("a jurisdiction admin reorders/hides a panel") presumes panels, but the composed surface is empty until X10 (no GA baselines, no force-linked plugins in craig-composition). So X8 ships the FULL backend write path (PUT/GET /v1/compositions/{surface}/override, write-time validation, same-txn invalidation, cache eviction, admin-gated authz) + a foundational authz-gated Studio surface whose concrete control is the jurisdiction dashboard layout (grid/stacked) — a real jurisdiction-live override (add /shell <layout>) that exercises the entire write→validate→invalidate→authz chain end-to-end WITHOUT panels. Per-panel reorder/hide is X10’s layer on top (when there are panels to manipulate + e2e). The e2e proves the authz boundary (admin 200 + layout round-trip; non-admin 403 + nav hidden) now. Building a panel-manipulation UI against an empty surface would be speculative (YAGNI).

Write-time validation = per-role dry-run resolve — resolved at X8 (the X5/X6 carry-forward): a jurisdiction-live override is role-agnostic but its floor/grid violations surface per-role at resolve time, so the write handler dry-runs loader.resolve_with_layers against EVERY realm role with the prospective override row; any resolution failure (removed required panel, over-budget row, span out of range, malformed delta, unknown export slug) is a 400 at write time. The realm-role set is a local const in the handler mirroring craig-web’s KNOWN_REALM_ROLES (no central role registry exists in craig-auth/craig-authz yet — the same duplication the BFF acknowledges).

Override write authz: admin-gated Action::Update, evaluated against the ACTOR — resolved at X8: the {jurisdiction}-authz-composition rulesets gain an i_admin ('admin' in claims.roles) input + an admin-full-access rule (read stays open to any worker; the service-caller rule is unchanged). The BFF calls with a client_credentials token + X-Craig-Actor, and craig-authz evaluates acting_worker().realm_access.roles with is_service = is_service() && actor.is_none() (engine.rs) — so a non-admin actor (e.g. caseworker) falls through to default-deny (403) and the service-caller rule only admits actor-less internal calls. Authz is enforced at BOTH the BFF (require_admin_only) and craig-composition. The override sub-resource (GET+PUT /override) is Action::Update-gated (admin-only); the resolved-surface read stays Action::Read (any worker).

Conditional-write transport + the staged write machinery go live — resolved at X8: the X5 db::write::upsert_override + the X6 events::stage_invalidation modules drop their staged #![allow(dead_code)] (now mounted on the write endpoint). The BFF write rides RFC 7232 conditional headers (If-Match to replace, If-None-Match: * to create) — which the six Transport verb helpers don’t shape — so CompositionClient builds its own request off Transport::http + a newly-pub(crate) Transport::apply_identity (still carrying the standard ADR-028 outbound identity). A 409 maps to a "reload" flash, a 400 surfaces the RFC 9457 detail. B4 ratcheted 86→87 for the new route module’s standard Askama filters-in-scope allow (identical to every existing route module).

Missing aud-craig-composition Keycloak audience mapper (an X2 service-add miss, latent through X7) — found + fixed at X8: every inbound bearer is audience-checked against the service’s own name (craig-api/src/bootstrap.rs with_audience(service_name), ADR-021), so a token reaching craig-composition must carry craig-composition in its aud. The devstack realm seeds a per-client oidc-audience-mapper for each service (aud-craig-rules … aud-craig-intake) but X2 never added aud-craig-composition, so EVERY call to craig-composition failed token validation: InvalidAudience. This was invisible through X7 because the dashboard’s composition resolve is best-effort (it degrades to the static tiles on error, and no X7 e2e asserted on the composed region); X8’s Studio write round-trip — which asserts the write succeeds — surfaced it. Fix: add the aud-craig-composition mapper to all 12 realm clients in devstack/keycloak/craig-realm.json (it takes effect on the next dev reseed, which wipes the keycloak volume + re-imports). This is the missing item in the X2 service-add gotcha list (a new backend service needs its audience mapper added to the realm, alongside the realm client + service role + RULES_ENGINE_URL).

User-delta authz = Action::Read (self-service), not a new action — resolved at X9: the user-delta GET+PUT /v1/compositions/{surface}/user-delta are gated by Action::Read, the same grant any worker already holds to view the surface — NOT Action::Update (which stays admin-only for the jurisdiction-live override). Personalizing one’s own view is not a privilege escalation over viewing it; the write is kept harmless by structure (the user_sub is ALWAYS claims.acting_worker()’s own — never request-supplied, so a worker cannot write another’s delta) and by scope (the X4 `validate_user_delta rejects any panel the role may not see). This needed NO new Action variant and NO ruleset change — the existing "any authenticated worker may read" rule covers it. The shared composition_user_sub(worker) derives the sub (rejecting service / non-UUID principals); the write path 400-rejects a None, the read path falls back to the role baseline.

Read-apply wiring (the X9 review catch) — resolved at X9 (adversarial-review finding, high): the X3 resolution read handler (compositions.rs) hardcoded user_sub: None, so the user-delta was write-only — it never applied on read, defeating "survives reload." Fixed by deriving user_sub via the shared composition_user_sub in resolve_surface, so the engine + cache (already keyed on user_sub) apply + isolate the worker’s layer. Once user_sub keys go live, the X6 insert-time cache sweep bounds memory by the active-worker set within the TTL (anticipated by the X6 errata).

Shared write/identity support extraction (DRY across X8/X9) — resolved at X9: the persistence shape is identical across the jurisdiction-live override and the user-delta write, so persist_override (write + same-txn stage_invalidation + cache eviction via cache::apply_invalidation, the blast radius dispatched by scope), map_write_error, parse_precondition, the OverrideView/OverrideWritten DTOs, composition_resource_ref, and composition_user_sub were extracted to api/write_support.rs; overrides.rs (X8) + user_delta.rs (X9) + compositions.rs (the read) all consume it. A new craig_common::ApiError::unprocessable(field, detail) constructor fills the gap where a semantic 422 (a business-rule violation like an invalid user delta) had no constructor outside garde.

Personalization UI scope at X9 = reset only (panel controls → X10) — resolved at X9 (mirrors the X8 layout-control deferral): the user_delta_v1 envelope is entirely panel-scoped (hide / re-span / reorder slugs), but the composed surface is empty until the X10 GA baselines, so the only panel-free control is a reset (write an empty envelope, clearing any prior personalization). X9 ships the full self-service write + read-apply path + validation end-to-end; the rich drag-to-reorder / pin / hide UI lands at X10 when there are panels on the surface to manipulate. The self-service /personalize/dashboard route is NOT admin-gated (unlike Studio) — every authenticated worker personalizes their own dashboard.

JCS/RFC 8785 crate choice (ADR-035 §6) — resolved at X1.

Engine crate name — ADR-035 + this body both named the engine lib crates/craig-composition and the service services/craig-composition, which collide on cargo package name. Resolved at X2 (!726-successor): the engine lib is renamed craig-composition → craig-composition-engine (git mv); the bare craig-composition name goes to the SERVICE, matching CRAIG’s taxonomy (services are bare; a domain lib that backs a service carries a role qualifier — craig-cases-contracts, craig-exchange-transport). Pre-1.0 with no consumers yet, the rename is mechanical. References to “crates/craig-composition” in the X1 cell + earlier ADR/CHANGELOG text predate this rename.

Plan S — Multi-Jurisdiction Foundation — the umbrella; this body is Step 20, execution is Step 21.

ADR-035 — the composition engine this plan implements: §1 the NEW service vs BFF; §2 the five layers + runtime-loaded baselines; §3 merge semantics + the user_delta_v1 envelope; §4 role-filter-after-merge; §5 the composition_overrides table; §6 cache + RFC 8785 + composition.invalidated fanout; §7 ADR-028 auth pass-through; §8 the compositions: CompositionContribution field.

ADR-033 + Plan W — supply the plugins being composed + the PluginSource registry the loader role-filters against + the GET /plugins/<slug> render route the composed surface drives.

ADR-032 — §4 + A11 the additive compositions: CompositionContribution field on BundleContribution.

ADR-038 — §3 the pre-materialized registry posture (the compositions field; the CompositionLoader is the boot-time service resource).

ADR-028 — the client_credentials + X-Craig-Actor on-behalf-of seam the BFF uses to reach craig-composition.

ADR-024 — the zen-engine RabbitMQ subscribe_exclusive cache-invalidation pattern reused for composition.invalidated.

ADR-022 — the transactional outbox staging the invalidation event.

ADR-023 — the authz stack the write endpoints (Studio + user-delta) enforce against.

ADR-004 — the stateless-BFF property X7 protects (the BFF stays an HTTP client, no DB/MQ).

Contract 3: Composition + persistence — the author-facing contract this plan realizes.

canopy crates/canopy-composition/ + canopy ADR-021 (external; ported, not consumed) — the working precedent for the loader, merge strategies, user_delta_v1 envelope, role filter, and invalidate-on-write cache; CRAIG diverges on true RFC 8785 hashing + the cross-replica fanout + the separate-service home.