feat: align product config vocabulary (actsAs, label, holiday sets)

Aligns configuration vocabulary that differed between products; the product is pre-1.0. Every renamed key has a `config.removed-key` entry naming its replacement, a CFG-NAME-5 row, a `BREAKING:` line in the product CHANGELOG, a note in `release/notes/config-conventions/`, and updated examples, fixtures, docs and regenerated schemas. No migration code.

BREAKING:

- Casework, Documents and Messaging access profiles: `role` is renamed `actsAs`; values unchanged. The schema definitions `CaseworkRole` and `AccessRole` become `CaseworkActsAs` and `ActsAs`, and the Casework diagnostic `casework.access-profile.missing-role` becomes `casework.access-profile.missing-acts-as`. BReg profiles and the data sense of `role` (event records, Evidence subjects) are unchanged.
- Coordinator: `title` is renamed `label` on a project, function, operation and step; the explain member `presentation.title` becomes `presentation.label`; the duplicate-title diagnostics become `...duplicate-function-label`, `...duplicate-operation-label` and `...duplicate-step-label`.
- Casework holiday-set file: `holidaySet` is renamed `id`, and an optional `label` is allowed. A calendar's `holidaySet` member, which names the set it uses, is unchanged.
- Scheduling: a holiday set's `because` is renamed `label`, and `label` is now optional (the id names a set that writes none), as in the Casework holiday-set file. The schema definition `HolidaySetPolicy` becomes `HolidaySet`. `because` stays on every other Scheduling item.
- `caseworkctl dev` report: a client names `actsAs` where it named `role`.
- Upgrade: this release does not read state stored by 0.45.0 or earlier. Start Casework and Scheduling on a new database; finish Coordinator runs before upgrading. A stored document that holds a removed member is refused with a message that says it was stored by an earlier release and names the member.

Additive:

- Coordinator event triggers accept an optional `label` and `description`, stored under `presentation.eventTriggers.<id>`, reported by `check --explain`, and outside the semantic revision (a wording edit keeps `workflowRevision`). Closes #2549.
- Casework, Documents, Messaging and Evidence access profiles accept an optional `label` and `description` (BReg profiles already have `display`). They are accepted for authoring and tooling. Casework keeps them in the review policy description, which any caller who may read that description, requesters included, can see, and they do not change a policy's behavioral binding. Evidence drops them at compile; Documents and Messaging only parse them, and none serve them until a view exists.

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>

Author: jeremi

crates/registry-adapter-job/tests/support/casework_native_service.rs

@@ -172,10 +172,10 @@ impl Casework {
                 "kind": "CaseworkProject",
                 "project": {"id": "adapter-ingestion-review", "version": "1"},
                 "accessProfiles": {
-                    "staff": {"principalClaim": "sub", "requiredScopes": ["casework:staff"], "role": "staff"},
-                    "supervisor": {"principalClaim": "sub", "requiredScopes": ["casework:supervisor"], "role": "supervisor"},
-                    "administrator": {"principalClaim": "sub", "requiredScopes": ["casework:admin"], "role": "administrator"},
-                    "coordinator-producer": {"principalClaim": "sub", "requiredScopes": ["casework:review"], "role": "requester"}
+                    "staff": {"principalClaim": "sub", "requiredScopes": ["casework:staff"], "actsAs":"staff"},
+                    "supervisor": {"principalClaim": "sub", "requiredScopes": ["casework:supervisor"], "actsAs":"supervisor"},
+                    "administrator": {"principalClaim": "sub", "requiredScopes": ["casework:admin"], "actsAs":"administrator"},
+                    "coordinator-producer": {"principalClaim": "sub", "requiredScopes": ["casework:review"], "actsAs":"requester"}
                 },
                 "queues": {"applications": {"label": "Household ingestion reviews"}},
                 "teams": {"reviewers": {"label": "Household reviewers", "serves": ["applications"], "memberProfiles": ["staff"], "supervisorProfiles": ["supervisor"]}},

crates/registry-casework-client/tests/http_boundary.rs

@@ -3549,7 +3549,7 @@ fn fixture_closure(policy: ReviewPolicy) -> registry_casework_client::ReviewPoli
         .remove("id");
     let project: registry_casework_core::CaseworkProject = serde_json::from_value(json!({
         "apiVersion":"id.registrystack.org/formats/casework/project/v1alpha1", "kind":"CaseworkProject", "project":{"id":"client-fixture","version":"1"},
-        "accessProfiles":{"supervisor":{"role":"supervisor","principalClaim":"sub","requiredScopes":["casework:supervisor"]},"administrator":{"role":"administrator","principalClaim":"sub","requiredScopes":["casework:admin"]},"staff":{"role":"staff","principalClaim":"sub","requiredScopes":["casework:staff"]},"requester":{"role":"requester","principalClaim":"sub","requiredScopes":["casework:request"]}},
+        "accessProfiles":{"supervisor":{"actsAs":"supervisor","principalClaim":"sub","requiredScopes":["casework:supervisor"]},"administrator":{"actsAs":"administrator","principalClaim":"sub","requiredScopes":["casework:admin"]},"staff":{"actsAs":"staff","principalClaim":"sub","requiredScopes":["casework:staff"]},"requester":{"actsAs":"requester","principalClaim":"sub","requiredScopes":["casework:request"]}},
         "queues":queues, "reviewPolicies":{policy.id.clone(): policy_body}, "contextProviders":providers,
         "trustedProducers":{"requester":{"profile":"requester","issuer":"https://issuer.example","subject":"producer","sourceNamespaces":["registry"],"reviewPolicies":[policy.id],"retention":{"receiptRetentionDays":30}}}
     })).expect("fixture project");

crates/registry-casework-core/src/config.rs

@@ -12,7 +12,7 @@ use serde::{Deserialize, Serialize};
 use thiserror::Error;
 
 use crate::finding::{ConfigFinding, Findings, IDENTIFIER_ACTION, IDENTIFIER_MESSAGE};
-use crate::CaseworkRole;
+use crate::CaseworkActsAs;
 use crate::ReviewPolicy;
 use crate::MAXIMUM_RECEIPT_RETENTION_DAYS;
 use crate::{clock_policy_findings, routing_policy_findings, CalendarPolicy, ClockPolicy};
@@ -316,7 +316,11 @@ pub const CASEWORK_PROJECT_FORMAT: FormatSpec<'static> = FormatSpec {
         },
         RemovedKey {
             pointer: "/accessProfiles/*/id",
-            replacement: "Write accessProfiles as a mapping from each id to the rest of its entry, accessProfiles: {PROFILE_ID: {role: ...}}, with no id member. See row F4 of the format table in the Casework CHANGELOG.",
+            replacement: "Write accessProfiles as a mapping from each id to the rest of its entry, accessProfiles: {PROFILE_ID: {actsAs: ...}}, with no id member. See row F4 of the format table in the Casework CHANGELOG.",
+        },
+        RemovedKey {
+            pointer: "/accessProfiles/*/role",
+            replacement: "Write the same value as actsAs.",
         },
         RemovedKey {
             pointer: "/queues/*/id",
@@ -1033,19 +1037,23 @@ impl CaseworkProject {
                 );
             }
             for (name, ids, role) in [
-                ("memberProfiles", &team.member_profiles, CaseworkRole::Staff),
+                (
+                    "memberProfiles",
+                    &team.member_profiles,
+                    CaseworkActsAs::Staff,
+                ),
                 (
                     "supervisorProfiles",
                     &team.supervisor_profiles,
-                    CaseworkRole::Supervisor,
+                    CaseworkActsAs::Supervisor,
                 ),
             ] {
                 if ids.is_empty()
                     || ids.iter().any(|id| {
                         !self
                             .access_profiles
                             .iter()
-                            .any(|profile| profile.id == *id && profile.role == role)
+                            .any(|profile| profile.id == *id && profile.acts_as == role)
                     })
                 {
                     findings.push(
@@ -1172,20 +1180,20 @@ impl CaseworkProject {
             }
         }
         for (role, name) in [
-            (CaseworkRole::Staff, "staff"),
-            (CaseworkRole::Supervisor, "supervisor"),
-            (CaseworkRole::Administrator, "administrator"),
+            (CaseworkActsAs::Staff, "staff"),
+            (CaseworkActsAs::Supervisor, "supervisor"),
+            (CaseworkActsAs::Administrator, "administrator"),
         ] {
             if !self
                 .access_profiles
                 .iter()
-                .any(|profile| profile.role == role)
+                .any(|profile| profile.acts_as == role)
             {
                 findings.push(
-                    "casework.access-profile.missing-role",
+                    "casework.access-profile.missing-acts-as",
                     "/accessProfiles",
-                    format!("no access profile has role {name}"),
-                    format!("Declare an access profile with role: {name}."),
+                    format!("no access profile acts as {name}"),
+                    format!("Declare an access profile with actsAs: {name}."),
                 );
             }
         }
@@ -1251,14 +1259,17 @@ impl CaseworkProject {
                         .iter()
                         .find(|profile| profile.id == *profile_id)
                         .is_none_or(|profile| {
-                            !matches!(profile.role, CaseworkRole::Staff | CaseworkRole::Supervisor)
+                            !matches!(
+                                profile.acts_as,
+                                CaseworkActsAs::Staff | CaseworkActsAs::Supervisor
+                            )
                         })
                     {
                         findings.push(
                             "casework.review-policy.ineligible-deciding-profile",
                             format!("{stage_at}/decidingProfiles/{profile_index}"),
                             "no staff or supervisor access profile has this id",
-                            "Name an access profile with role staff or supervisor.",
+                            "Name an access profile with actsAs staff or supervisor.",
                         );
                     }
                 }
@@ -1324,18 +1335,18 @@ impl CaseworkProject {
                 .access_profiles
                 .iter()
                 .find(|profile| profile.id == producer.profile)
-                .is_none_or(|profile| profile.role != CaseworkRole::Requester)
+                .is_none_or(|profile| profile.acts_as != CaseworkActsAs::Requester)
             {
                 findings.push(
                     "casework.review-producer.not-a-requester-profile",
                     format!("{at}/profile"),
                     "no requester access profile has this id",
-                    "Name an access profile with role requester.",
+                    "Name an access profile with actsAs requester.",
                 );
             }
             if let Some(initiator_profile) = &producer.initiator_profile {
                 let requester_profile = self.access_profiles.iter().any(|profile| {
-                    profile.id == *initiator_profile && profile.role == CaseworkRole::Requester
+                    profile.id == *initiator_profile && profile.acts_as == CaseworkActsAs::Requester
                 });
                 let producer_profile = self
                     .trusted_producers
@@ -1773,24 +1784,24 @@ fn project_integrity_diagnostics(decoded: &mut Decoded<CaseworkProject>) -> Vec<
 /// lower role. A profile that requires no scope is reported as such and not
 /// here.
 fn profiles_without_a_separate_scope(profiles: &[AccessProfile]) -> Vec<usize> {
-    fn role_rank(role: CaseworkRole) -> u8 {
+    fn role_rank(role: CaseworkActsAs) -> u8 {
         match role {
-            CaseworkRole::Requester => 0,
-            CaseworkRole::Staff => 1,
-            CaseworkRole::Supervisor => 2,
-            CaseworkRole::Administrator => 3,
+            CaseworkActsAs::Requester => 0,
+            CaseworkActsAs::Staff => 1,
+            CaseworkActsAs::Supervisor => 2,
+            CaseworkActsAs::Administrator => 3,
         }
     }
     profiles
         .iter()
         .enumerate()
         .filter(|(target_index, target)| {
-            let target_rank = role_rank(target.role);
+            let target_rank = role_rank(target.acts_as);
             let other_same_or_lower_scopes: BTreeSet<&String> = profiles
                 .iter()
                 .enumerate()
                 .filter(|(index, profile)| {
-                    index != target_index && role_rank(profile.role) <= target_rank
+                    index != target_index && role_rank(profile.acts_as) <= target_rank
                 })
                 .flat_map(|(_, profile)| profile.required_scopes.iter())
                 .collect();
@@ -1811,14 +1822,36 @@ pub struct AccessProfile {
     #[serde(deserialize_with = "crate::typed::local_id")]
     #[cfg_attr(feature = "schema", schemars(with = "registry_platform_yaml::LocalId"))]
     pub id: String,
+    /// A name for the profile, accepted for authoring and tooling; never matched against a caller. Part of the review policy description, which any caller who may read that description can see.
+    #[serde(
+        default,
+        deserialize_with = "registry_platform_yaml::optional_display_text",
+        skip_serializing_if = "Option::is_none"
+    )]
+    #[cfg_attr(
+        feature = "schema",
+        schemars(with = "Option<registry_platform_yaml::DisplayText>")
+    )]
+    pub label: Option<String>,
+    /// What the profile is for, accepted for authoring and tooling; never matched against a caller. Part of the review policy description, which any caller who may read that description can see.
+    #[serde(
+        default,
+        deserialize_with = "registry_platform_yaml::optional_display_text",
+        skip_serializing_if = "Option::is_none"
+    )]
+    #[cfg_attr(
+        feature = "schema",
+        schemars(with = "Option<registry_platform_yaml::DisplayText>")
+    )]
+    pub description: Option<String>,
     pub principal_claim: String,
     #[serde(deserialize_with = "crate::typed::unique_list")]
     #[cfg_attr(
         feature = "schema",
         schemars(with = "registry_platform_yaml::UniqueList<String>", length(min = 1))
     )]
     pub required_scopes: Vec<String>,
-    pub role: CaseworkRole,
+    pub acts_as: CaseworkActsAs,
 }
 
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]

crates/registry-casework-core/src/fixture.rs

@@ -3,7 +3,7 @@ use crate::HolidaySetDocument;
 use chrono::{DateTime, NaiveDate, Utc};
 use registry_platform_yaml::{
     ApiVersion, BoundedU64, Decoded, EnvelopeRule, Expect, ForeignValue, FormatSpec, Invalid,
-    LocalId, Reader, Report, RetiredApiVersion, UniqueList,
+    LocalId, Reader, RemovedKey, Report, RetiredApiVersion, UniqueList,
 };
 use serde::{Deserialize, Deserializer};
 use std::fmt;
@@ -19,7 +19,10 @@ pub const CASEWORK_HOLIDAY_SET_FORMAT: FormatSpec<'static> = FormatSpec {
         api_versions: &[ApiVersion::current(CASEWORK_HOLIDAY_SET_API_VERSION)],
         retired_api_versions: &[],
     },
-    removed_keys: &[],
+    removed_keys: &[RemovedKey {
+        pointer: "/holidaySet",
+        replacement: "Write the set's identifier as id.",
+    }],
 };
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)]
 pub struct Timestamp(DateTime<Utc>);
@@ -91,8 +94,18 @@ pub struct CaseworkHolidaySet {
     pub api_version: String,
     pub kind: String,
     /// The holiday set a calendar names in `holidaySet`.
-    pub holiday_set: LocalId,
+    pub id: LocalId,
     pub revision: BoundedU64<1, MAXIMUM_HOLIDAY_SET_REVISION>,
+    /// An optional human label for the set.
+    #[serde(
+        default,
+        deserialize_with = "registry_platform_yaml::optional_display_text"
+    )]
+    #[cfg_attr(
+        feature = "schema",
+        schemars(with = "Option<registry_platform_yaml::DisplayText>")
+    )]
+    pub label: Option<String>,
     /// The dates that are not working days, at most 3660.
     #[cfg_attr(feature = "schema", schemars(length(max = 3660)))]
     pub dates: UniqueList<CalendarDate>,
@@ -128,7 +141,7 @@ impl CaseworkHolidaySet {
     /// The revision as the runtime's holiday-set document.
     pub fn to_document(&self) -> HolidaySetDocument {
         HolidaySetDocument {
-            holiday_set: self.holiday_set.to_string(),
+            holiday_set: self.id.to_string(),
             revision: self.revision.get(),
             dates: self.dates.iter().map(ToString::to_string).collect(),
         }

crates/registry-casework-core/src/model.rs

@@ -73,7 +73,7 @@ mod directory_member_tests {
 #[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
 #[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 #[serde(rename_all = "kebab-case")]
-pub enum CaseworkRole {
+pub enum CaseworkActsAs {
     Staff,
     Supervisor,
     Administrator,
@@ -86,7 +86,7 @@ pub enum CaseworkRole {
 pub struct ActorContext {
     pub principal: IssuerPrincipal,
     pub profile_id: String,
-    pub role: CaseworkRole,
+    pub role: CaseworkActsAs,
 }
 
 /// A bearer credential may exist only for the duration of one request.

crates/registry-casework-core/src/review.rs

@@ -774,6 +774,10 @@ impl ReviewPolicy {
                 }
             }
         }
+        for profile in &mut dependencies.access_profiles {
+            profile.label = None;
+            profile.description = None;
+        }
         if let Some(provider) = &mut dependencies.context_provider {
             provider.description = None;
         }

crates/registry-casework-core/src/task_grant.rs

@@ -1,6 +1,6 @@
 //! Governed task delegation policy and immutable source-bound authorization.
 use crate::finding::{ConfigFinding, Findings};
-use crate::{CaseworkProject, CaseworkRole, IssuerPrincipal};
+use crate::{CaseworkActsAs, CaseworkProject, IssuerPrincipal};
 use serde::{Deserialize, Deserializer, Serialize};
 use serde_json::Value;
 use std::{collections::BTreeMap, fmt};
@@ -476,7 +476,10 @@ impl TaskTemplate {
         for (index, id) in self.eligible_profiles.iter().enumerate() {
             let eligible = project.access_profiles.iter().any(|profile| {
                 profile.id == *id
-                    && matches!(profile.role, CaseworkRole::Staff | CaseworkRole::Supervisor)
+                    && matches!(
+                        profile.acts_as,
+                        CaseworkActsAs::Staff | CaseworkActsAs::Supervisor
+                    )
             });
             if !eligible {
                 findings.push(

crates/registry-casework-core/tests/format_alignment.rs

@@ -169,7 +169,7 @@ fn two_of_each(order: [usize; 2]) -> String {
     };
     format!(
         "apiVersion: {CASEWORK_API_VERSION}\nkind: {CASEWORK_KIND}\nproject: {{id: review-project, version: \"1\"}}\n\
-         accessProfiles:\n  reviewer: {{role: staff, principalClaim: principal, requiredScopes: [\"casework:review\"]}}\n  supervisor: {{role: supervisor, principalClaim: principal, requiredScopes: [\"casework:supervise\"]}}\n  administrator: {{role: administrator, principalClaim: principal, requiredScopes: [\"casework:admin\"]}}\n  producer: {{role: requester, principalClaim: principal, requiredScopes: [\"casework:request\"]}}\n\
+         accessProfiles:\n  reviewer: {{actsAs: staff, principalClaim: principal, requiredScopes: [\"casework:review\"]}}\n  supervisor: {{actsAs: supervisor, principalClaim: principal, requiredScopes: [\"casework:supervise\"]}}\n  administrator: {{actsAs: administrator, principalClaim: principal, requiredScopes: [\"casework:admin\"]}}\n  producer: {{actsAs: requester, principalClaim: principal, requiredScopes: [\"casework:request\"]}}\n\
          queues: {{reviews: {{label: Reviews}}}}\n\
          teams: {{review-team: {{label: Review team, serves: [reviews], memberProfiles: [reviewer], supervisorProfiles: [supervisor]}}}}\n\
          contextProviders:\n{}\
@@ -270,6 +270,73 @@ fn an_elapsed_budget_names_exactly_one_unit() {
     }
 }
 
+#[test]
+fn an_access_profile_role_is_refused_and_names_acts_as() {
+    let diagnostics =
+        read(&replaced("actsAs: staff", "role: staff")).expect_err("the old spelling is refused");
+    assert!(
+        diagnostics
+            .iter()
+            .any(|diagnostic| diagnostic.code == "config.removed-key"
+                && diagnostic.path == "/accessProfiles/staff/role"
+                && diagnostic.suggested_action.contains("actsAs")),
+        "no removed-key diagnostic names actsAs: {diagnostics:#?}"
+    );
+}
+
+#[test]
+fn a_holiday_set_file_reads_id_and_refuses_holiday_set() {
+    let file = |first: &str| {
+        format!(
+            "apiVersion: {CASEWORK_HOLIDAY_SET_API_VERSION}\nkind: {CASEWORK_HOLIDAY_SET_KIND}\n{first}: office-holidays\nrevision: 7\nlabel: Office holidays\ndates: [2026-09-07]\n"
+        )
+    };
+    let read = |text: String| CaseworkHolidaySet::read("holiday-set.yaml", text.as_bytes());
+    let decoded = read(file("id")).expect("id reads").value;
+    assert_eq!(decoded.id.to_string(), "office-holidays");
+    assert_eq!(decoded.label.as_deref(), Some("Office holidays"));
+    let diagnostics = read(file("holidaySet")).expect_err("holidaySet is refused");
+    assert!(
+        diagnostics
+            .diagnostics()
+            .iter()
+            .any(|d| d.code == "config.removed-key"
+                && d.path == "/holidaySet"
+                && d.suggested_action.contains("id")),
+        "{diagnostics:#?}"
+    );
+}
+
+#[test]
+fn an_access_profile_reads_acts_as() {
+    let project = read(EXAMPLE).expect("the example reads");
+    assert!(project
+        .access_profiles
+        .iter()
+        .any(|profile| profile.acts_as == CaseworkActsAs::Staff));
+}
+
+#[test]
+fn an_access_profile_reads_a_label_and_a_description() {
+    let project = read(&replaced(
+        "requiredScopes: [casework:staff], actsAs: staff}",
+        "requiredScopes: [casework:staff], actsAs: staff, label: Reviewer, description: Decides review tasks}",
+    ))
+    .expect("the labelled profile reads");
+    let profile = project
+        .access_profiles
+        .iter()
+        .find(|profile| profile.acts_as == CaseworkActsAs::Staff)
+        .expect("the staff profile");
+    assert_eq!(profile.label.as_deref(), Some("Reviewer"));
+    assert_eq!(profile.description.as_deref(), Some("Decides review tasks"));
+    let unlabelled = read(EXAMPLE).expect("the example reads");
+    assert!(unlabelled
+        .access_profiles
+        .iter()
+        .all(|profile| profile.label.is_none() && profile.description.is_none()));
+}
+
 #[test]
 fn every_old_spelling_is_refused_with_its_replacement_and_table_row() {
     assert_refused(