feat: record project role coverage changes in the snapshot change feed

When a publication changes a custom role's effective grants, either by
removing pairs or by changing selector coverage, the change is appended
to that snapshot's change feed as role:<key>, as CHI-907 section 13
requires.

Validated: the native role tests (13 on SQLite and PostgreSQL), the full
orchestration native suite (104) and make check-ci.

Author: kvlonge

crates/sqlbuild-orchestration/src/authorization/_helpers/custom_roles.rs

@@ -262,6 +262,45 @@ pub(crate) async fn current_role(
     ))
 }
 
+fn grants_digest(grants: Option<&[RoleGrant]>) -> Result<Option<String>, ControlError> {
+    let Some(grants) = grants else {
+        return Ok(None);
+    };
+    let text =
+        serde_json::to_string(grants).map_err(|error| ControlError::Invalid(error.to_string()))?;
+    Ok(Some(sha256_hex(text.as_bytes())))
+}
+
+/// Append an effective role's coverage change to the snapshot's change feed, after its node changes.
+pub(crate) async fn record_role_change(
+    transaction: ControlTransaction,
+    (snapshot_id, role_key): (Uuid, &str),
+    (before, after): (Option<&[RoleGrant]>, Option<&[RoleGrant]>),
+) -> Result<ControlTransaction, ControlError> {
+    let kind = if after.is_some() {
+        "changed"
+    } else {
+        "removed"
+    };
+    let (transaction, rows) = query(
+        transaction,
+        "SELECT COALESCE(MAX(change_seq) + 1, 0) AS next FROM sqb_snapshot_changes WHERE snapshot_id=$1",
+        vec![Parameter::Id(snapshot_id)],
+    )
+    .await?;
+    let sequence = rows
+        .first()
+        .and_then(|row| row["next"].as_i64())
+        .unwrap_or_default();
+    let (transaction, _) = query(transaction,
+        "INSERT INTO sqb_snapshot_changes (snapshot_id, change_seq, change_kind, subject_key, before_hash, after_hash) \
+         VALUES ($1,$2,$3,$4,$5,$6)",
+        vec![Parameter::Id(snapshot_id), Parameter::Integer(sequence), Parameter::Text(kind.into()),
+            Parameter::Text(format!("role:{role_key}")), Parameter::OptionalText(grants_digest(before)?),
+            Parameter::OptionalText(grants_digest(after)?)]).await?;
+    Ok(transaction)
+}
+
 pub(crate) async fn set_effective_role(
     mut transaction: ControlTransaction,
     (location_id, target, role_key): (Uuid, &str, &str),

crates/sqlbuild-orchestration/src/authorization/main/publish_custom_roles.rs

@@ -1,9 +1,10 @@
-//! Record each published custom role; removed pairs and selector coverage apply now, additions wait.
+//! Record each published custom role; removals and coverage apply now and enter the change feed; additions wait.
 
 use serde_json::Value;
 
 use crate::authorization::_helpers::custom_roles::{
-    decode_roles, effective_role, narrows, retained_grants, set_effective_role,
+    decode_grants, decode_roles, effective_role, narrows, record_role_change, retained_grants,
+    set_effective_role,
 };
 use crate::snapshots::models::SnapshotRecord;
 use crate::store::errors::ControlError;
@@ -20,15 +21,22 @@ pub(crate) async fn publish_custom_roles(
     let rows;
     (transaction, rows) = query(
         transaction,
-        "SELECT role_key FROM sqb_effective_roles WHERE location_id=$1 AND target=$2",
+        "SELECT role_key,resolved_grants_json FROM sqb_effective_roles WHERE location_id=$1 AND target=$2",
         vec![Parameter::Id(scope.0), Parameter::Text(scope.1.into())],
     )
     .await?;
-    for key in rows
+    for row in rows
         .iter()
-        .filter_map(|row| row["role_key"].as_str())
-        .filter(|key| !roles.contains_key(*key))
+        .filter(|row| !roles.contains_key(row["role_key"].as_str().unwrap_or_default()))
     {
+        let key = row["role_key"].as_str().unwrap_or_default();
+        let before = decode_grants(&row["resolved_grants_json"])?;
+        transaction = record_role_change(
+            transaction,
+            (record.snapshot_id, key),
+            (Some(&before), None),
+        )
+        .await?;
         (transaction, _) = query(
             transaction,
             "DELETE FROM sqb_effective_roles WHERE location_id=$1 AND target=$2 AND role_key=$3",
@@ -59,6 +67,14 @@ pub(crate) async fn publish_custom_roles(
         } else {
             digest.as_str()
         };
+        if next != grants {
+            transaction = record_role_change(
+                transaction,
+                (record.snapshot_id, key),
+                (Some(&grants), Some(&next)),
+            )
+            .await?;
+        }
         if next != grants || next_digest != digest {
             transaction =
                 set_effective_role(transaction, (scope.0, scope.1, key), (next_digest, &next))

crates/sqlbuild-orchestration/tests/credentials/roles/helpers.rs

@@ -217,6 +217,28 @@ pub(crate) async fn granting_role(
     authorize_member(store, fixture, (action, &[])).await.ok()
 }
 
+/// Custom role entries of the snapshot change feed, by publication generation.
+pub(crate) async fn role_changes(store: &ControlStore) -> Vec<(i64, String)> {
+    let transaction = begin(store, TransactionMode::Read).await.expect("read");
+    let (transaction, rows) = query(
+        transaction,
+        "SELECT s.generation, c.change_kind FROM sqb_snapshot_changes c JOIN sqb_snapshots s ON s.snapshot_id=c.snapshot_id \
+         WHERE c.subject_key='role:orders_support' ORDER BY s.generation, c.change_seq",
+        vec![],
+    )
+    .await
+    .expect("role changes");
+    commit(transaction).await.expect("commit");
+    rows.iter()
+        .map(|row| {
+            (
+                row["generation"].as_i64().unwrap_or_default(),
+                row["change_kind"].as_str().unwrap_or_default().into(),
+            )
+        })
+        .collect()
+}
+
 /// Role approval audit facts in commit order: action and recorded outcome.
 pub(crate) async fn role_audit(store: &ControlStore) -> Vec<(String, Value)> {
     let transaction = begin(store, TransactionMode::Read).await.expect("read");

crates/sqlbuild-orchestration/tests/credentials/test_project_roles.rs

@@ -9,7 +9,7 @@ use crate::authorization::main::compile_roles::compile_roles;
 use crate::credentials::models::{Action, RoleAssignmentRequest, RoleGrant, RoleKey};
 use crate::credentials::tests::role_helpers::{
     SUPPORT_ROLE, activate, assign, authorize_member, developer_grants, orders_grant,
-    publish_support_role, role_fixture, try_request,
+    publish_support_role, role_changes, role_fixture, try_request,
 };
 use crate::credentials::tests::test_types::{ProjectRoleTestCase, RolesFileTestCase};
 use crate::runs::tests::helpers::snapshot;
@@ -92,6 +92,12 @@ fn given_approved_selector_when_it_matches_more_nodes_then_coverage_grows_withou
                 "{}: coverage growth is not a widening to approve",
                 test_case.description
             );
+            assert_eq!(
+                role_changes(store).await,
+                [(2, "changed".to_owned()), (3, "changed".to_owned())],
+                "{}: the dropped view grant and the grown coverage enter the change feed",
+                test_case.description
+            );
             close_test_store(fixture).await;
         });
     }

src/sqlbuild/.agents/skills/sqlbuild/references/docs/cli/server.md

@@ -127,7 +127,8 @@ definition, and any publication that adds a selector and permission pair, takes
 an administrator requests it with `POST /api/admin/role-activations` and another administrator
 approves it with `POST /api/admin/role-approvals`. A sole administrator must confirm a
 self-approval. Removed pairs stop applying on publish. An unchanged selector covers new
-matching nodes on publish without approval. A denial lists the nodes the request was missing.
+matching nodes on publish without approval. Either change appears in the publication's change
+list as `role:<key>`. A denial lists the nodes the request was missing.
 
 ## Repair control views
 

website/src/content/docs/docs/cli/server.mdx

@@ -118,7 +118,8 @@ definition, and any publication that adds a selector and permission pair, takes
 an administrator requests it with `POST /api/admin/role-activations` and another administrator
 approves it with `POST /api/admin/role-approvals`. A sole administrator must confirm a
 self-approval. Removed pairs stop applying on publish. An unchanged selector covers new
-matching nodes on publish without approval. A denial lists the nodes the request was missing.
+matching nodes on publish without approval. Either change appears in the publication's change
+list as `role:<key>`. A denial lists the nodes the request was missing.
 
 ## Repair control views