Worker portal redesign — Stage 3 MR1 (DB migrations + composition loader)

[plugin]
slug = "snap-overpayment-summary"        # required; ^[a-z][a-z0-9-]*[a-z0-9]$
name = "SNAP Overpayment Summary"        # required; human-readable
version = "1.0.0"                        # required; semver
author = "canopy-core"                   # required; free-form
license = "AGPL-3.0-or-later"            # required; SPDX
canopy_min = "0.1.0"                     # required; semver compat lower bound

[plugin.exports]
panels = ["snap-overpayment-summary-panel"]
case_sections = []

[panels.snap-overpayment-summary-panel]
display_name_key = "panels.snap_overpayment_summary.title"   # required; i18n key
icon = "💰"                                                  # required; unicode glyph
programs = ["snap"]                                          # required; ⊆ {snap, tanf, medicaid, caps, wic}
default_span = 4                                             # required; ∈ allowed_spans
allowed_spans = [3, 4, 6, 12]                                # required; ⊆ {1, 2, 3, 4, 6, 12} (ADR-021 line 192 breakpoint set)
required_states = ["empty", "loading", "error", "populated"] # required; ⊆ {empty, loading, error, populated}

[data]
source = "canopy-snap"                                       # required; canopy service slug
auth = "service_class"                                       # required; ∈ {none, service_class, user_jwt}
cache_ttl_seconds = 30                                       # required; u32 ≥ 0
timeout_ms = 5000                                            # required; u32 > 0
endpoints = ["/v1/overpayments/summary?household_id={household_id}"]  # required; non-empty

[permissions]
required_roles = ["eligibility_worker", "supervisor"]        # required; non-empty
audit = "read"                                               # required; ∈ {none, read, write}

[i18n]
default = "en"                                               # required
catalogs = ["en", "es"]                                      # required; non-empty; contains default

# idp.toml — IDP and role configuration for {jurisdiction}.
# v1 (Stage 3 of #460): roles section only. Stage 4 (#493) adds
# [providers], [discovery], and [local_accounts] sections without
# replacing the existing [roles] schema. Uses serde(deny_unknown_fields).

default_role = "eligibility_worker"

[roles.eligibility_worker]
display_name = "Eligibility Worker"
description = "Front-line caseworker"

[roles.supervisor]
display_name = "Supervisor"
description = "Reviews caseworker decisions; can override"

[roles.jurisdiction_admin]
display_name = "Jurisdiction Admin"
description = "Manages live composition overrides for this jurisdiction"

[roles.qc]
display_name = "Quality Control"
description = "Read-only QC reviewer"

{
  "shell": "grid",
  "items": []
}

// SPDX-License-Identifier: AGPL-3.0-or-later

use serde::{Deserialize, Serialize};
use std::sync::Arc;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, sqlx::Type)]
#[sqlx(type_name = "composition_surface", rename_all = "snake_case")]
#[serde(rename_all = "snake_case")]
pub enum ComposableSurface {
    WorkerDashboard,
    SupervisorDashboard,
    AnalystDashboard,
    CaseDetail,
    SignIn,
}

/// Per-surface shell layout enum. Each surface's `ComposedSurface.shell`
/// uses a different variant set; we encode this as a tagged enum.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "surface", rename_all = "snake_case")]
pub enum ShellSpec {
    #[serde(rename = "worker_dashboard")]
    WorkerDashboard { layout: WorkerDashboardLayout },
    #[serde(rename = "supervisor_dashboard")]
    SupervisorDashboard { layout: WorkerDashboardLayout },
    #[serde(rename = "analyst_dashboard")]
    AnalystDashboard { layout: WorkerDashboardLayout },
    #[serde(rename = "case_detail")]
    CaseDetail { shell: CaseDetailShell },
    #[serde(rename = "sign_in")]
    SignIn,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WorkerDashboardLayout { Grid, Stacked }

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CaseDetailShell { Scroll, CardGrid, Tabs }

/// Plugin identity from `[plugin].slug` in Plugin.toml. Composition items
/// do NOT reference this directly — they reference `ItemSlug`s (panel or
/// case_section keys from `[panels.*]` / `[case_sections.*]`). The mapping
/// from `ItemSlug` → plugin is established by the plugin's
/// `[plugin.exports]` table.
#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)]
#[serde(transparent)]
pub struct PluginSlug(pub String);

/// Slug of a composition item — matches a key in `[panels.*]` (for
/// dashboard surfaces) or `[case_sections.*]` (for case_detail) of some
/// plugin's Plugin.toml. NOT the plugin slug. ADR-021 line 132's
/// "panel for dashboards, section for case-detail" uses this concept.
#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)]
#[serde(transparent)]
pub struct ItemSlug(pub String);

#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)]
#[serde(transparent)]
pub struct RoleSlug(pub String);

#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)]
#[serde(transparent)]
pub struct JurisdictionSlug(pub String);

// UserId reuses canopy-common's `define_id!` convention (UUID v7, sqlx
// transparent, utoipa-schema-aware) so it composes with the rest of canopy.
canopy_common::define_id!(
    /// Worker user identity used as scope_key for the `user` layer.
    UserId
);

/// Loader-facing key. `Hash + Eq` is used by the composition cache.
#[derive(Debug, Clone, Hash, PartialEq, Eq)]
pub struct CompositionKey {
    pub jurisdiction: JurisdictionSlug,
    pub role: RoleSlug,
    pub user_id: Option<UserId>,
    pub surface: ComposableSurface,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ComposedItem {
    /// Export slug — matches a `[panels.*]` or `[case_sections.*]` key
    /// in the exporting plugin's Plugin.toml. The composition system
    /// resolves this to a plugin via `PluginSource::find_panel` /
    /// `find_case_section`. Different from the plugin's `[plugin].slug`.
    pub item: ItemSlug,
    pub span: u8,
    pub row: u8,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ComposedSurface {
    pub surface: ComposableSurface,
    pub shell: ShellSpec,
    pub items: Vec<ComposedItem>,
    /// First 8 bytes of SHA-256 of canonical RFC 8785 JSON of the resolved
    /// composition doc (post-merge, post-role-filter, pre-version-stamp).
    /// Per ADR-021 line 133.
    pub version: u64,
}

/// Intermediate post-merge shape *before* `version` is computed and
/// *before* `shell` is mapped to its typed `ShellSpec` variant. The
/// loader deserializes the merged JSON tree into this; `shell` is a
/// raw string (e.g., "tabs", "scroll", "card_grid", "grid", "default")
/// because defaults / baseline TOMLs author shell as a string scalar.
/// The loader maps `raw.shell` to `ShellSpec` per the request's
/// `ComposableSurface` before assembling the final `ComposedSurface`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RawComposition {
    /// Shell variant name as a string. Surface-specific valid values:
    /// - WorkerDashboard / Supervisor / Analyst: "grid" | "stacked"
    /// - CaseDetail: "scroll" | "card_grid" | "tabs"
    /// - SignIn: ignored (no shell)
    #[serde(default)]
    pub shell: String,
    pub items: Vec<ComposedItem>,
}

#[derive(Debug, thiserror::Error)]
pub enum CompositionLoadError {
    #[error("plugin slug `{slug}` referenced by composition is not registered")]
    UnknownPlugin { slug: String },
    #[error("item span {span} is outside plugin `{slug}`'s allowed_spans {allowed:?}")]
    SpanOutOfRange { slug: String, span: u8, allowed: Vec<u8> },
    #[error("row {row} exceeds 12-column budget: total span = {total}")]
    RowOverflow { row: u8, total: u32 },
    #[error("role `{role}` is not defined in `{jurisdiction}`'s idp.toml")]
    RoleNotFound { jurisdiction: String, role: String },
    #[error("jurisdiction slug `{slug}` not found in JurisdictionRegistry")]
    UnknownJurisdiction { slug: String },
    /// `json_patch::patch` returns one error for the entire op list (the
    /// crate does not expose per-op index); the `layer` field identifies
    /// which of {jurisdiction_live, role, user} failed.
    #[error("RFC 6902 patch failed at layer `{layer}`: {source}")]
    PatchFailed { layer: &'static str, #[source] source: json_patch::PatchError },
    /// Carries an owned `String` (not `&ManifestError`) because the
    /// underlying `toml::de::Error` is not `Clone`; the loader's
    /// pre-validation pass calls `.to_string()` on the ManifestError
    /// reference returned by `Plugin::manifest()`.
    #[error("manifest parse error: {0}")]
    ManifestParse(String),
    #[error("idp.toml parse error: {0}")]
    IdpParse(#[from] crate::idp::IdpError),
    #[error("post-merge doc failed to deserialize into ComposedSurface: {0}")]
    PostMergeShape(serde_json::Error),
    #[error("database error: {0}")]
    Db(#[from] sqlx::Error),
    #[error("io error: {0}")]
    Io(#[from] std::io::Error),
}

// SPDX-License-Identifier: AGPL-3.0-or-later

use crate::types::PluginSlug;
use crate::manifest::Manifest;
use std::sync::OnceLock;

/// Minimal trait every plugin handler implements. `PluginRegistration`
/// is the v1 implementer; Stage 5+ may add `render`, `audit_event`, etc.
/// methods with default impls so existing plugins don't break.
///
/// `manifest()` returns `Result` because v1's `#[canopy_plugin]` macro
/// does NOT validate the embedded TOML at compile time (Decision 2);
/// the first call parses + caches the result. A follow-up issue
/// promotes validation to compile-time per ADR-021 lines 47-50.
pub trait Plugin: Send + Sync {
    fn slug(&self) -> &str;
    fn manifest(&self) -> Result<&Manifest, &crate::manifest::ManifestError>;
}

/// Per-plugin runtime metadata. Populated by `#[canopy_plugin]`.
pub struct PluginRegistration {
    pub slug: &'static str,
    pub manifest_toml: &'static str,
    pub manifest_cache: OnceLock<Result<Manifest, crate::manifest::ManifestError>>,
}

impl Plugin for PluginRegistration {
    fn slug(&self) -> &str { self.slug }
    fn manifest(&self) -> Result<&Manifest, &crate::manifest::ManifestError> {
        self.manifest_cache
            .get_or_init(|| crate::manifest::Manifest::parse(self.manifest_toml))
            .as_ref()
    }
}

#[linkme::distributed_slice]
pub static CANOPY_PLUGINS: [PluginRegistration] = [..];

pub trait PluginSource: Send + Sync {
    /// Look up by plugin's `[plugin].slug`. Returns `None` if no plugin
    /// with this identity is registered.
    fn get_plugin(&self, slug: &PluginSlug) -> Option<&dyn Plugin>;

    /// Find the plugin exporting `panel_slug` in its `[plugin.exports].panels`
    /// list AND defining `[panels.<panel_slug>]`. Returns the plugin handle
    /// plus a reference to the panel's definition. Used by the composition
    /// loader to resolve dashboard items.
    fn find_panel(&self, panel_slug: &ItemSlug) -> Option<(&dyn Plugin, &PanelDef)>;

    /// Same shape as `find_panel` but for `[case_sections.<slug>]`. Used
    /// for the CaseDetail surface.
    fn find_case_section(&self, section_slug: &ItemSlug) -> Option<(&dyn Plugin, &CaseSectionDef)>;

    fn iter(&self) -> Box<dyn Iterator<Item = &dyn Plugin> + '_>;
}

pub struct CompileTimePluginSource;

impl PluginSource for CompileTimePluginSource {
    fn get_plugin(&self, slug: &PluginSlug) -> Option<&dyn Plugin> {
        CANOPY_PLUGINS.iter()
            .find(|p| p.slug == slug.0)
            .map(|p| p as &dyn Plugin)
    }

    fn find_panel(&self, panel_slug: &ItemSlug) -> Option<(&dyn Plugin, &PanelDef)> {
        for p in CANOPY_PLUGINS.iter() {
            // Silently skip plugins whose manifest fails to parse — they
            // can't contribute exports. Loader surfaces UnknownPlugin if
            // the requested slug is not exported by any *valid* plugin.
            let Ok(m) = p.manifest() else { continue };
            if m.plugin.exports.panels.iter().any(|s| s == &panel_slug.0)
                && m.panels.contains_key(&panel_slug.0)
            {
                return Some((p as &dyn Plugin, &m.panels[&panel_slug.0]));
            }
        }
        None
    }

    fn find_case_section(&self, section_slug: &ItemSlug) -> Option<(&dyn Plugin, &CaseSectionDef)> {
        for p in CANOPY_PLUGINS.iter() {
            let Ok(m) = p.manifest() else { continue };
            if m.plugin.exports.case_sections.iter().any(|s| s == &section_slug.0)
                && m.case_sections.contains_key(&section_slug.0)
            {
                return Some((p as &dyn Plugin, &m.case_sections[&section_slug.0]));
            }
        }
        None
    }

    fn iter(&self) -> Box<dyn Iterator<Item = &dyn Plugin> + '_> {
        Box::new(CANOPY_PLUGINS.iter().map(|p| p as &dyn Plugin))
    }
}

#[linkme::distributed_slice(::canopy_composition::CANOPY_PLUGINS)]
static __CANOPY_PLUGIN_REGISTRATION_<slug-as-uppercase-underscored>: ::canopy_composition::PluginRegistration =
    ::canopy_composition::PluginRegistration {
        slug: "snap-overpayment-summary",
        manifest_toml: include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/", "Plugin.toml")),
        manifest_cache: ::std::sync::OnceLock::new(),
    };

crates/canopy-composition/
├── Cargo.toml
├── src/
│   ├── lib.rs                # SPDX header; #![forbid(unsafe_code)]; public re-exports
│   ├── types.rs              # see Core type vocabulary above
│   ├── source.rs             # see PluginSource + plugin registration above
│   ├── manifest.rs           # Plugin.toml schema (Manifest + nested types + ManifestError)
│   ├── idp.rs                # idp.toml schema (Idp + Role + IdpError)
│   ├── defaults.rs           # system_defaults(surface) -> &'static Value via LazyLock + include_str!
│   ├── merge.rs              # apply_merge_patch_7396 + apply_json_patch_6902 (thin json-patch wrappers)
│   ├── role_filter.rs        # filter_items_by_role
│   ├── cache.rs              # CompositionCache (tokio RwLock<HashMap<...>>)
│   ├── jurisdiction.rs       # JurisdictionRegistry trait + StaticJurisdictionRegistry impl
│   ├── audit.rs              # AuditEmitter trait + NoopAuditEmitter impl
│   ├── db.rs                 # fetch_db_layers(pool, ...) -> Vec<(layer, scope_key, patch_ops)>
│   └── loader.rs             # load_composition (orchestrates all of above)
├── defaults/
│   ├── worker_dashboard.json
│   ├── supervisor_dashboard.json
│   ├── analyst_dashboard.json
│   ├── case_detail.json
│   └── sign_in.json          # {"shell": "", "items": []} — Stage 4 fills
├── fixtures/
│   └── Plugin.toml           # canonical test fixture (NOT production location)
└── tests/
    ├── manifest_test.rs
    ├── idp_test.rs
    ├── merge_test.rs
    ├── role_filter_test.rs
    ├── cache_test.rs
    └── loader_test.rs

crates/canopy-plugin-macros/
├── Cargo.toml                # [lib] proc-macro = true
└── src/
    └── lib.rs                # #[canopy_plugin(slug=…, manifest=…)] expansion

-- Stage 3 of #460 / epic &51. Closes #489. ADR-022 storage layering.
-- Forward-only per ADR-016.

CREATE TYPE composition_layer AS ENUM ('user', 'role', 'jurisdiction_live');

CREATE TYPE composition_surface AS ENUM (
    'worker_dashboard',
    'supervisor_dashboard',
    'analyst_dashboard',
    'case_detail',
    'sign_in'
);

CREATE TABLE composition_documents (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    jurisdiction_id UUID NOT NULL,
    layer           composition_layer NOT NULL,
    scope_key       TEXT NOT NULL,
    surface         composition_surface NOT NULL,
    patch_ops       JSONB NOT NULL,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
    created_by      UUID NOT NULL,
    UNIQUE (jurisdiction_id, layer, scope_key, surface)
);

CREATE INDEX composition_documents_lookup_idx
    ON composition_documents (jurisdiction_id, surface, layer, scope_key);

CREATE TABLE composition_documents_archive (
    LIKE composition_documents INCLUDING DEFAULTS INCLUDING IDENTITY,
    archived_at  TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
    archived_by  UUID NOT NULL
);

CREATE INDEX composition_documents_archive_lookup_idx
    ON composition_documents_archive (jurisdiction_id, surface, archived_at DESC);

* *Worker portal Stage 3 MR1 — composability runtime + DB migrations (closes \#489, \#490; refs \#460 / epic \&51).* New crate +crates/canopy-composition/+ wraps the 5-layer composition resolver (system defaults via +LazyLock+ → jurisdiction baseline TOML via RFC 7396 → jurisdiction_live → role → user via RFC 6902 op lists per ADR-022) + `PluginSource` trait + `CompileTimePluginSource` (linkme distributed_slice) + invalidate-on-write `tokio::sync::RwLock` cache. New +crates/canopy-plugin-macros/+ provides the +#[canopy_plugin]+ proc-macro for compile-time plugin registration. Forward-only migration creates +composition_documents+ + +composition_documents_archive+ tables (ADR-022 schema verbatim). Roles-only +idp.toml+ schema lands here (Stage 4 #493 extends with IDP providers). Fixture Georgia jurisdiction TOMLs ship for worker_dashboard + case_detail + sign_in surfaces. 41 named tests cover parsers + merge + role-filter + cache + loader end-to-end (including post-merge span/row/plugin/role validation). HTTP write APIs (#491) ship in MR2. Stage-3 implementation plan at +docs/modules/ROOT/pages/plans/archive/worker-portal-redesign-stage3-composition-runtime.adoc+.