didbot_policy/

lib.rs

//! The policy machinery: what a policy declares, the tree that indexes it,
//! and deny-only evaluation over the ordered list the tree produces.
//!
//! This is the core `plan/policy.md` describes — not a policy language, not
//! an evaluator, not I/O. Two sibling crates use it: `didbot-policy-regex`
//! is a deterministic in-process [`Evaluator`], and `didbot-pds`'s write
//! path drives [`evaluate()`] per write, outside its store lock, and turns a
//! [`Verdict::Freeze`] into the queue-draining behaviour `plan/policy.md`
//! describes under "Outcomes" — this crate produces the verdict and stops
//! there.
//!
//! # What is here, and why
//!
//! - [`Subject`], [`WriteAction`], [`Diff`], [`Change`],
//!   [`SubjectAttributes`], [`AccountKind`], [`DeploymentAttributes`],
//!   [`Universal`] and [`ClientId`] — what a policy is asked about. Three
//!   subject shapes, one set of mechanics; a write's diff carries
//!   before/after values, not just paths, so a rule reads a changed value
//!   rather than only knowing that a path changed; and a subject is not
//!   always an agent — see [`AccountKind`].
//! - [`Applicability`], [`Scope`], [`ActionSet`], [`KindSet`],
//!   [`Predicate`], [`Revision`] and [`PolicyDeclaration`] — what a policy
//!   declares statically. This is what goes in the tree; a policy's actual
//!   judgement stays behind the [`Evaluator`] trait, opaque to this crate.
//!   `Predicate` is what lets a policy's applicability be known and
//!   scoped even when its predicate is not — see its doc comment for why
//!   that split matters once policies are independent records rather than
//!   a set.
//! - [`PolicyTree`] and [`PolicyTreeBuilder`] — the applicability index.
//!   Turns a subject into an ordered candidate list in time bounded by the
//!   subject's own diff, not by how many policies are registered.
//! - [`Outcome`], [`Staleness`], [`Observed`], [`Lifecycle`], [`EvalError`]
//!   and the [`Evaluator`] trait — the contract every evaluator implements.
//! - [`Language`] and [`KnownLanguage`] — the open union of policy languages
//!   this build can turn into a working [`Evaluator`]. A wrapper's loader
//!   resolves [`Language::Unknown`] to [`Predicate::Unusable`] rather than
//!   failing to parse the record; see [`Language`]'s doc comment.
//! - [`Verdict`], [`combine`] and [`evaluate()`] — ordered evaluation with
//!   deny-only semantics. [`combine`] is where monotonicity is structural
//!   rather than conventional: see its doc comment.
//!
//! # What is deliberately not here
//!
//! No I/O, no async, anywhere in this crate. Evaluators do the work — some
//! of them out of process, some of them with a model or a network
//! resolution in the loop — and this crate stays the thing that is testable
//! without a runtime and cheap to reason about under a deadline. See
//! [`Evaluator`]'s doc comment for what that implies for anyone implementing
//! one.
//!
//! No storage of policies, no polling, no wrapper metadata (source, format
//! version, which PDS a record applies to). `plan/policy.md` calls that "a
//! policy is not its wrapper" and leaves the wrapper's shape and the
//! lexicon that carries it unsettled; this crate only consumes the
//! [`PolicyDeclaration`] a wrapper resolves to, never the wrapper itself.
//!
//! No position on what a delete means. [`Diff`] makes exact every path
//! whose value differs between before and after, absence included as a
//! value, and [`WriteAction`] says which kind of write it was. A policy can
//! declare it applies only to deletes; an evaluator decides what a delete
//! means for its own rules.

#![forbid(unsafe_code)]

mod client_id;
mod evaluate;
mod index;
mod json;
mod language;
mod outcome;
mod policy;
mod subject;

pub use client_id::{is_local_origin, ClientId, ClientIdError};
pub use evaluate::{combine, evaluate, worst, Verdict};
pub use index::{PolicyTree, PolicyTreeBuilder};
pub use json::sorted_json;
pub use language::{KnownLanguage, Language};
pub use outcome::{
    CompileOutcome, EvalError, Evaluator, Lifecycle, Observed, Outcome, PolicyLifecycle, Staleness,
};
pub use policy::{
    ActionSet, Applicability, CompiledId, EvaluatorId, KindSet, PolicyDeclaration, PolicyId,
    Predicate, Revision, Scope,
};
pub use subject::{
    AccountKind, Asked, Change, DeploymentAttributes, Diff, Found, Lookup, Subject,
    SubjectAttributes, SubjectKind, Universal, WriteAction,
};

#[cfg(test)]
mod tests {
    use super::*;
    use std::sync::atomic::{AtomicUsize, Ordering};
    use std::sync::Arc;

    /// An evaluator that always returns the same outcome, and counts how
    /// many times it was asked.
    struct Fixed {
        outcome: Outcome,
        calls: AtomicUsize,
    }

    impl Fixed {
        fn new(outcome: Outcome) -> Self {
            Fixed {
                outcome,
                calls: AtomicUsize::new(0),
            }
        }
    }

    impl Evaluator for Fixed {
        fn compile(&self, _predicate: &serde_json::Value) -> CompileOutcome {
            CompileOutcome::Compiled(CompiledId(0))
        }
        fn evaluate(
            &self,
            _subject: &Subject<'_>,
            _compiled: CompiledId,
        ) -> Result<Outcome, EvalError> {
            self.calls.fetch_add(1, Ordering::SeqCst);
            Ok(self.outcome.clone())
        }
        fn observe(&self, _event: &Observed<'_>) {}
        fn lifecycle(&self, _event: &Lifecycle<'_>) {}
        fn staleness(&self) -> Staleness {
            Staleness::Linearized
        }
    }

    /// An evaluator that compiles cleanly and then fails at decision
    /// time -- the live counterpart to [`Predicate::Unusable`], which is a
    /// compile-time failure. Reachable in production wherever an evaluator
    /// answers a subject shape its policy was routed for but cannot judge.
    struct FailsAtDecisionTime;

    impl Evaluator for FailsAtDecisionTime {
        fn compile(&self, _predicate: &serde_json::Value) -> CompileOutcome {
            CompileOutcome::Compiled(CompiledId(0))
        }
        fn evaluate(
            &self,
            _subject: &Subject<'_>,
            _compiled: CompiledId,
        ) -> Result<Outcome, EvalError> {
            Err(EvalError::Failed("the evaluator is not answering".into()))
        }
        fn observe(&self, _event: &Observed<'_>) {}
        fn lifecycle(&self, _event: &Lifecycle<'_>) {}
        fn staleness(&self) -> Staleness {
            Staleness::Linearized
        }
    }

    /// A working evaluator that fails at decision time is fail-closed, and
    /// scoped by the tree exactly as a `Predicate::Unusable` is:
    /// `plan/policy.md`'s "fail closed per policy, not per deployment".
    /// Distinct from the `Unusable` case above -- that one never compiled,
    /// this one compiled and then stopped answering -- and the two reach
    /// `Reject` down different arms of `PolicyTree::decide`.
    #[test]
    fn an_evaluator_that_fails_denies_only_within_its_own_applicability() {
        let mut builder = PolicyTree::builder();
        let evaluator_id = builder.register_evaluator(Arc::new(FailsAtDecisionTime));
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Only(vec!["app.bsky.feed.post".into()]),
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Only(vec!["app.bsky.feed.post".into()]),
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(evaluator_id, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();

        let covered = write("app.bsky.feed.post", WriteAction::Create, &[]);
        assert!(
            matches!(
                evaluate(&covered, &tree),
                Verdict::Reject { ref reason, .. }
                    if reason.contains("the evaluator is not answering")
            ),
            "a failing evaluator must deny the writes it was routed, naming why"
        );

        let uncovered = write("bot.did.record", WriteAction::Create, &[]);
        assert_eq!(
            evaluate(&uncovered, &tree),
            Verdict::Allow,
            "one evaluator's failure must not widen into a blanket denial"
        );
    }

    /// `decide_detailed` tells a caller explaining a refusal to an operator
    /// whether the evaluator itself decided it, or whether this tree
    /// substituted a fail-closed refusal because the evaluator could not
    /// answer -- the distinction `didbot-policy-check`'s simulator draws
    /// between a policy that fired and a policy whose check could not
    /// complete. `decide` itself does not care, and returns the same
    /// `Outcome` either way.
    #[test]
    fn decide_detailed_tells_a_decision_apart_from_a_substituted_refusal() {
        let mut builder = PolicyTree::builder();
        let working = builder.register_evaluator(Arc::new(Fixed::new(Outcome::Reject {
            reason: "no".into(),
        })));
        let failing = builder.register_evaluator(Arc::new(FailsAtDecisionTime));
        let applicability = || Applicability::Write {
            kinds: KindSet::ALL,
            collections: Scope::Only(vec!["app.bsky.feed.post".into()]),
            actions: ActionSet::ALL,
            path_prefixes: Scope::Any,
        };
        let decided = builder.add_policy(PolicyDeclaration {
            applicability: applicability(),
            observes: applicability(),
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(working, CompiledId(0)),
            revision: Revision(1),
        });
        let substituted = builder.add_policy(PolicyDeclaration {
            applicability: applicability(),
            observes: applicability(),
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(failing, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();
        let subject = write("app.bsky.feed.post", WriteAction::Create, &[]);

        let (outcome, errored) = tree.decide_detailed(&subject, decided);
        assert!(matches!(outcome, Outcome::Reject { ref reason } if reason == "no"));
        assert!(
            !errored,
            "the evaluator's own decision is not a substituted refusal"
        );
        assert_eq!(tree.decide(&subject, decided), outcome);

        let (outcome, errored) = tree.decide_detailed(&subject, substituted);
        assert!(matches!(outcome, Outcome::Reject { .. }));
        assert!(errored, "a failed evaluate() call is a substituted refusal");
        assert_eq!(tree.decide(&subject, substituted), outcome);
    }

    /// A placeholder JSON value, for tests that only care which paths a
    /// diff touched, not what changed at them.
    fn dummy_value() -> &'static serde_json::Value {
        static VALUE: std::sync::OnceLock<serde_json::Value> = std::sync::OnceLock::new();
        VALUE.get_or_init(|| serde_json::Value::Bool(true))
    }

    /// Deployment attributes and a fixed instant, for tests that do not
    /// exercise a time- or deployment-shaped rule.
    fn test_universal() -> Universal<'static> {
        Universal {
            deployment: DeploymentAttributes {
                pds_did: "did:web:test.example",
                pds_hostname: "test.example",
                operator_did: None,
            },
            now: time::macros::datetime!(2026 - 01 - 01 0:00 UTC),
        }
    }

    /// Build a write [`Subject`] that touched exactly `paths`, each
    /// reported as newly present — enough for index-routing tests, which
    /// never inspect `before`/`after`.
    fn write<'a>(collection: &'a str, action: WriteAction, paths: &'a [&'a str]) -> Subject<'a> {
        let changes: Vec<Change<'a>> = paths
            .iter()
            .map(|&path| Change {
                path,
                before: None,
                after: Some(dummy_value()),
            })
            .collect();
        let changes: &'a [Change<'a>] = Box::leak(changes.into_boxed_slice());
        Subject::Write {
            account: "did:plc:agent",
            attributes: SubjectAttributes {
                kind: SubjectKind::Known(AccountKind::Agent),
                handle: None,
                depth: None,
            },
            universal: test_universal(),
            client_id: None,
            collection,
            action,
            diff: Diff { changes },
            before: None,
            after: None,
            lookups: &[],
        }
    }

    /// A write to a collection nothing is registered for costs only the
    /// tree walk: no evaluator is ever invoked, regardless of how many
    /// policies exist for *other* collections.
    #[test]
    fn empty_match_never_calls_an_evaluator() {
        let denier = Arc::new(Fixed::new(Outcome::Reject {
            reason: "no".into(),
        }));
        let mut builder = PolicyTree::builder();
        let evaluator_id = builder.register_evaluator(denier.clone());
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Only(vec!["app.bsky.feed.post".into()]),
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Only(vec!["app.bsky.feed.post".into()]),
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(evaluator_id, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();

        let subject = write("bot.did.record", WriteAction::Create, &["track"]);
        assert!(tree.decision_candidates(&subject).is_empty());

        let verdict = evaluate(&subject, &tree);
        assert_eq!(verdict, Verdict::Allow);
        assert_eq!(denier.calls.load(Ordering::SeqCst), 0);
    }

    /// A denying policy registered with `Scope::Any` collections applies
    /// everywhere, including a collection with no specific entry.
    #[test]
    fn a_wildcard_collection_policy_still_matches() {
        let denier = Arc::new(Fixed::new(Outcome::Reject {
            reason: "app denied".into(),
        }));
        let mut builder = PolicyTree::builder();
        let evaluator_id = builder.register_evaluator(denier);
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(evaluator_id, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();

        let subject = write("bot.did.record", WriteAction::Create, &[]);
        let verdict = evaluate(&subject, &tree);
        assert!(matches!(verdict, Verdict::Reject { .. }));
    }

    /// A policy declaring only `Delete` never fires on a `Create`, and vice
    /// versa — the core routes on the explicit action, taking no position
    /// on what a delete's diff contains.
    #[test]
    fn action_routing_is_exact() {
        let delete_denier = Arc::new(Fixed::new(Outcome::Reject {
            reason: "no deletes".into(),
        }));
        let mut builder = PolicyTree::builder();
        let evaluator_id = builder.register_evaluator(delete_denier);
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::of(&[WriteAction::Delete]),
                path_prefixes: Scope::Any,
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::of(&[WriteAction::Delete]),
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(evaluator_id, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();

        let create = write("bot.did.record", WriteAction::Create, &[]);
        assert_eq!(evaluate(&create, &tree), Verdict::Allow);

        let delete = write("bot.did.record", WriteAction::Delete, &[]);
        assert!(matches!(evaluate(&delete, &tree), Verdict::Reject { .. }));
    }

    /// A policy declared for agents only routes past a host's write
    /// entirely: the evaluator is never invoked, the same "no evaluator
    /// call" property `empty_match_never_calls_an_evaluator` demonstrates
    /// for an unregistered collection — kind is a filter the tree applies,
    /// not one every evaluator has to re-check and return `Allow` from.
    #[test]
    fn kind_routing_never_calls_an_evaluator_for_an_uncovered_kind() {
        let agent_only = Arc::new(Fixed::new(Outcome::Reject {
            reason: "agents only".into(),
        }));
        let mut builder = PolicyTree::builder();
        let evaluator_id = builder.register_evaluator(agent_only.clone());
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::of(&[AccountKind::Agent]),
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            observes: Applicability::Write {
                kinds: KindSet::of(&[AccountKind::Agent]),
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(evaluator_id, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();

        let agent_write = write("bot.did.record", WriteAction::Create, &[]);
        assert!(matches!(
            evaluate(&agent_write, &tree),
            Verdict::Reject { .. }
        ));
        assert_eq!(agent_only.calls.load(Ordering::SeqCst), 1);

        let host_write = Subject::Write {
            account: "did:plc:host",
            attributes: SubjectAttributes {
                kind: SubjectKind::Known(AccountKind::Host),
                handle: None,
                depth: None,
            },
            universal: test_universal(),
            client_id: None,
            collection: "bot.did.record",
            action: WriteAction::Create,
            diff: Diff { changes: &[] },
            before: None,
            after: None,
            lookups: &[],
        };
        assert!(tree.decision_candidates(&host_write).is_empty());
        assert_eq!(evaluate(&host_write, &tree), Verdict::Allow);
        // Still just the one call from the agent write above: the host's
        // write never reached this evaluator at all.
        assert_eq!(agent_only.calls.load(Ordering::SeqCst), 1);
    }

    /// Build a write [`Subject`] whose account kind is unrecognized —
    /// `bot.did.registration`'s `actor` union is open, so a subject can
    /// carry a kind this build has never heard of.
    fn write_with_unknown_kind<'a>(collection: &'a str, kind_name: &'a str) -> Subject<'a> {
        Subject::Write {
            account: "did:plc:from-the-future",
            attributes: SubjectAttributes {
                kind: SubjectKind::Unknown(kind_name),
                handle: None,
                depth: None,
            },
            universal: test_universal(),
            client_id: None,
            collection,
            action: WriteAction::Create,
            diff: Diff { changes: &[] },
            before: None,
            after: None,
            lookups: &[],
        }
    }

    /// A policy scoped to named kinds — even naming all four known ones —
    /// never matches a subject whose kind this build does not recognize.
    /// Naming `Agent` made a claim about agents; extending it to a kind
    /// nobody had seen when the policy was written would be a premise the
    /// author never established, so the tree routes an unknown kind past
    /// it exactly as it would an uncovered known one.
    #[test]
    fn an_unknown_kind_routes_past_a_policy_scoped_to_known_kinds() {
        let known_only = Arc::new(Fixed::new(Outcome::Reject {
            reason: "known kinds only".into(),
        }));
        let mut builder = PolicyTree::builder();
        let evaluator_id = builder.register_evaluator(known_only.clone());
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                // All four *known* kinds — and still, per KindSet's
                // contract, not a kind this build has never seen.
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(evaluator_id, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();

        let from_the_future = write_with_unknown_kind("bot.did.record", "oracle");
        assert!(tree.decision_candidates(&from_the_future).is_empty());
        assert_eq!(evaluate(&from_the_future, &tree), Verdict::Allow);
        assert_eq!(known_only.calls.load(Ordering::SeqCst), 0);
    }

    /// `KindSet::ANY` is the explicit opt-in: a policy declared with it
    /// reaches a subject of an unrecognized kind, because its author chose
    /// to cover kinds invented after the policy was written.
    #[test]
    fn kind_set_any_reaches_an_unknown_kind() {
        let any_kind = Arc::new(Fixed::new(Outcome::Reject {
            reason: "no kind is exempt".into(),
        }));
        let mut builder = PolicyTree::builder();
        let evaluator_id = builder.register_evaluator(any_kind.clone());
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::ANY,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            observes: Applicability::Write {
                kinds: KindSet::ANY,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(evaluator_id, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();

        let from_the_future = write_with_unknown_kind("bot.did.record", "oracle");
        assert_eq!(tree.decision_candidates(&from_the_future).len(), 1);
        assert!(matches!(
            evaluate(&from_the_future, &tree),
            Verdict::Reject { .. }
        ));
        assert_eq!(any_kind.calls.load(Ordering::SeqCst), 1);
    }

    /// A path-scoped policy matches a write that touches its prefix and not
    /// one that does not — "an agent may edit its bio but not its display
    /// name" from `plan/policy.md`.
    #[test]
    fn path_prefix_scoping() {
        let denier = Arc::new(Fixed::new(Outcome::Reject {
            reason: "displayName is locked".into(),
        }));
        let mut builder = PolicyTree::builder();
        let evaluator_id = builder.register_evaluator(denier);
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Only(vec!["app.bsky.actor.profile".into()]),
                actions: ActionSet::ALL,
                path_prefixes: Scope::Only(vec!["displayName".into()]),
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(evaluator_id, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();

        let bio_edit = write("app.bsky.actor.profile", WriteAction::Update, &["bio"]);
        assert_eq!(evaluate(&bio_edit, &tree), Verdict::Allow);

        let name_edit = write(
            "app.bsky.actor.profile",
            WriteAction::Update,
            &["displayName"],
        );
        assert!(matches!(
            evaluate(&name_edit, &tree),
            Verdict::Reject { .. }
        ));
    }

    /// A path-scoped policy guarding a field guards that field's array
    /// elements too. `didbot_pds::policy::diff` reports an array element
    /// as `tags[0]`, so a prefix of `tags` that did not treat the
    /// subscript as a segment boundary would route past it — the policy
    /// would silently enforce nothing the moment the field it named held
    /// an array, while the identical policy over a scalar field worked.
    #[test]
    fn a_path_prefix_reaches_its_field_s_array_elements() {
        let denier = Arc::new(Fixed::new(Outcome::Reject {
            reason: "tags are locked".into(),
        }));
        let mut builder = PolicyTree::builder();
        let evaluator_id = builder.register_evaluator(denier.clone());
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Only(vec!["tags".into()]),
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(evaluator_id, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();

        // The scalar shape, which has always worked.
        let scalar = write("app.bsky.actor.profile", WriteAction::Update, &["tags"]);
        assert!(matches!(evaluate(&scalar, &tree), Verdict::Reject { .. }));

        // The array shape the write path actually produces for the same
        // field.
        let element = write("app.bsky.actor.profile", WriteAction::Update, &["tags[0]"]);
        assert!(
            matches!(evaluate(&element, &tree), Verdict::Reject { .. }),
            "a policy guarding `tags` must reach `tags[0]`"
        );

        // A nested one, likewise.
        let nested = write(
            "app.bsky.actor.profile",
            WriteAction::Update,
            &["tags[2].label"],
        );
        assert!(matches!(evaluate(&nested, &tree), Verdict::Reject { .. }));

        // And a field whose name merely starts with the same letters is
        // still not covered: this widens the prefix's reach into its own
        // subscripts, not into its siblings.
        let sibling = write(
            "app.bsky.actor.profile",
            WriteAction::Update,
            &["tagsExtra"],
        );
        assert_eq!(evaluate(&sibling, &tree), Verdict::Allow);
    }

    /// A prefix may still name one specific element: the subscript
    /// segments the same way on the declaring side as on the matching
    /// one, so `tags[0]` covers `tags[0]` and not `tags[1]`.
    #[test]
    fn a_path_prefix_may_name_one_element() {
        let denier = Arc::new(Fixed::new(Outcome::Reject {
            reason: "the first tag is locked".into(),
        }));
        let mut builder = PolicyTree::builder();
        let evaluator_id = builder.register_evaluator(denier);
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Only(vec!["tags[0]".into()]),
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(evaluator_id, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();

        let first = write("app.bsky.actor.profile", WriteAction::Update, &["tags[0]"]);
        assert!(matches!(evaluate(&first, &tree), Verdict::Reject { .. }));
        let second = write("app.bsky.actor.profile", WriteAction::Update, &["tags[1]"]);
        assert_eq!(evaluate(&second, &tree), Verdict::Allow);
    }

    /// The observation surface is independent of the decision surface: a
    /// policy can be told about an attempt it has no say in deciding.
    #[test]
    fn observation_surface_is_independent_of_decision_surface() {
        let watcher = Arc::new(Fixed::new(Outcome::Allow));
        let mut builder = PolicyTree::builder();
        let evaluator_id = builder.register_evaluator(watcher);
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Only(vec!["app.bsky.feed.post".into()]),
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(evaluator_id, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();

        let subject = write("bot.did.record", WriteAction::Create, &[]);
        assert!(tree.decision_candidates(&subject).is_empty());
        assert_eq!(tree.observation_candidates(&subject).len(), 1);
    }

    /// Registration order is presentational order: with two rejecting
    /// policies over the same write, the reason reported is the
    /// first-registered one — and building the tree with the declarations
    /// in the opposite order changes only which reason is reported, never
    /// that the write is denied.
    #[test]
    fn registration_order_only_changes_which_reason_is_reported() {
        fn tree_with(first: &str, second: &str) -> PolicyTree {
            let mut builder = PolicyTree::builder();
            let e1 = builder.register_evaluator(Arc::new(Fixed::new(Outcome::Reject {
                reason: first.into(),
            })));
            let e2 = builder.register_evaluator(Arc::new(Fixed::new(Outcome::Reject {
                reason: second.into(),
            })));
            for evaluator in [e1, e2] {
                builder.add_policy(PolicyDeclaration {
                    applicability: Applicability::Write {
                        kinds: KindSet::ALL,
                        collections: Scope::Any,
                        actions: ActionSet::ALL,
                        path_prefixes: Scope::Any,
                    },
                    observes: Applicability::Write {
                        kinds: KindSet::ALL,
                        collections: Scope::Any,
                        actions: ActionSet::ALL,
                        path_prefixes: Scope::Any,
                    },
                    staleness: Staleness::Linearized,
                    predicate: Predicate::Evaluator(evaluator, CompiledId(0)),
                    revision: Revision(1),
                });
            }
            builder.build()
        }

        let subject = write("bot.did.record", WriteAction::Create, &[]);

        let a = tree_with("a fires first", "b fires first");
        assert!(matches!(
            evaluate(&subject, &a),
            Verdict::Reject { ref reason, .. } if reason == "a fires first"
        ));

        // Same two policies, evaluators registered in the opposite order:
        // still denied, only the reported reason changes.
        let b = tree_with("b fires first", "a fires first");
        assert!(matches!(
            evaluate(&subject, &b),
            Verdict::Reject { ref reason, .. } if reason == "b fires first"
        ));
    }

    /// A policy whose applicability parses but whose predicate is
    /// [`Predicate::Unusable`] denies every subject inside that
    /// applicability — fail-closed, scoped exactly like an unavailable
    /// evaluator — and leaves everything outside it untouched: a policy
    /// scoped to one collection being broken must not deny writes to a
    /// different collection nobody declared it covers.
    #[test]
    fn an_unusable_predicate_denies_only_within_its_own_applicability() {
        let mut builder = PolicyTree::builder();
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Only(vec!["app.bsky.feed.post".into()]),
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Only(vec!["app.bsky.feed.post".into()]),
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Unusable {
                reason: "names an engine this build does not have".into(),
            },
            revision: Revision(1),
        });
        let tree = builder.build();

        // Inside this policy's applicability: denied.
        let covered = write("app.bsky.feed.post", WriteAction::Create, &[]);
        assert!(matches!(
            evaluate(&covered, &tree),
            Verdict::Reject { ref reason, .. }
                if reason.contains("names an engine this build does not have")
        ));

        // Outside it — a different collection entirely — untouched: the
        // brokenness of one policy does not widen into a blanket denial.
        let uncovered = write("bot.did.record", WriteAction::Create, &[]);
        assert_eq!(evaluate(&uncovered, &tree), Verdict::Allow);
    }

    /// An `Unusable` predicate is a refusal, and a refusal must never
    /// outrank — or be outranked into silence by — a sibling's freeze. A
    /// freeze needs an operator and a rejection does not, so whichever
    /// order the two are registered in, the verdict is the freeze.
    #[test]
    fn an_unusable_predicate_never_downgrades_a_siblings_freeze() {
        fn tree_with_unusable_and_freeze(unusable_first: bool) -> PolicyTree {
            let applicability = || Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            };
            let mut builder = PolicyTree::builder();
            let freezer = builder.register_evaluator(Arc::new(Fixed::new(Outcome::Freeze {
                reason: "repeatedly tripped policy".into(),
            })));
            let mut add = |predicate: Predicate| {
                builder.add_policy(PolicyDeclaration {
                    applicability: applicability(),
                    observes: applicability(),
                    staleness: Staleness::Linearized,
                    predicate,
                    revision: Revision(1),
                });
            };
            let unusable = Predicate::Unusable {
                reason: "predicate did not compile".into(),
            };
            if unusable_first {
                add(unusable);
                add(Predicate::Evaluator(freezer, CompiledId(0)));
            } else {
                add(Predicate::Evaluator(freezer, CompiledId(0)));
                add(unusable);
            }
            builder.build()
        }

        let subject = write("bot.did.record", WriteAction::Create, &[]);
        for unusable_first in [true, false] {
            let tree = tree_with_unusable_and_freeze(unusable_first);
            assert!(
                matches!(
                    evaluate(&subject, &tree),
                    Verdict::Freeze { ref reason, .. }
                        if reason == "repeatedly tripped policy"
                ),
                "a freeze must outrank a broken sibling's refusal \
                 (unusable_first = {unusable_first})"
            );
        }
    }

    /// [`PolicyTree::evaluator`] has nothing to return for a policy whose
    /// predicate is [`Predicate::Unusable`] — there is no evaluator to call
    /// `observe` or `lifecycle` on.
    #[test]
    fn unusable_predicate_has_no_evaluator() {
        let mut builder = PolicyTree::builder();
        let policy = builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Unusable {
                reason: "bad syntax".into(),
            },
            revision: Revision(1),
        });
        let tree = builder.build();
        assert!(tree.evaluator(policy).is_none());
    }

    /// A real value-reading evaluator: *"displayName may not change to a
    /// different value once it has one"*. Written with no `WriteAction`
    /// arm at all — before/after resolves create and delete on their own,
    /// which is the whole point of carrying values in [`Diff`] instead of
    /// bare paths.
    struct NoRenaming;

    impl Evaluator for NoRenaming {
        fn compile(&self, _predicate: &serde_json::Value) -> CompileOutcome {
            CompileOutcome::Compiled(CompiledId(0))
        }
        fn evaluate(
            &self,
            subject: &Subject<'_>,
            _compiled: CompiledId,
        ) -> Result<Outcome, EvalError> {
            let Subject::Write { diff, .. } = subject else {
                return Ok(Outcome::Allow);
            };
            for change in diff.changes {
                if change.path == "displayName"
                    && change.before.is_some()
                    && change.after != change.before
                {
                    return Ok(Outcome::Reject {
                        reason: "displayName may not change".into(),
                    });
                }
            }
            Ok(Outcome::Allow)
        }
        fn observe(&self, _event: &Observed<'_>) {}
        fn lifecycle(&self, _event: &Lifecycle<'_>) {}
        fn staleness(&self) -> Staleness {
            Staleness::Linearized
        }
    }

    fn tree_with_evaluator(evaluator: Arc<dyn Evaluator>) -> PolicyTree {
        let mut builder = PolicyTree::builder();
        let evaluator_id = builder.register_evaluator(evaluator);
        builder.add_policy(PolicyDeclaration {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Only(vec!["displayName".into()]),
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(evaluator_id, CompiledId(0)),
            revision: Revision(1),
        });
        builder.build()
    }

    #[test]
    fn before_after_resolves_create_and_delete_without_an_action_arm() {
        let tree = tree_with_evaluator(Arc::new(NoRenaming));
        let old = serde_json::Value::String("alice".into());
        let new = serde_json::Value::String("bob".into());

        // Create: no prior value, so nothing to protect.
        let created = Change {
            path: "displayName",
            before: None,
            after: Some(&new),
        };
        let subject = Subject::Write {
            account: "did:plc:agent",
            attributes: SubjectAttributes {
                kind: SubjectKind::Known(AccountKind::Agent),
                handle: None,
                depth: None,
            },
            universal: test_universal(),
            client_id: None,
            collection: "app.bsky.actor.profile",
            action: WriteAction::Create,
            diff: Diff {
                changes: &[created],
            },
            before: None,
            after: None,
            lookups: &[],
        };
        assert_eq!(evaluate(&subject, &tree), Verdict::Allow);

        // Update to a different value: denied.
        let renamed = Change {
            path: "displayName",
            before: Some(&old),
            after: Some(&new),
        };
        let subject = Subject::Write {
            account: "did:plc:agent",
            attributes: SubjectAttributes {
                kind: SubjectKind::Known(AccountKind::Agent),
                handle: None,
                depth: None,
            },
            universal: test_universal(),
            client_id: None,
            collection: "app.bsky.actor.profile",
            action: WriteAction::Update,
            diff: Diff {
                changes: &[renamed],
            },
            before: None,
            after: None,
            lookups: &[],
        };
        assert!(matches!(evaluate(&subject, &tree), Verdict::Reject { .. }));

        // Delete: the value existed and is now gone — also denied, with no
        // `WriteAction::Delete` special case anywhere in `NoRenaming`.
        let deleted = Change {
            path: "displayName",
            before: Some(&old),
            after: None,
        };
        let subject = Subject::Write {
            account: "did:plc:agent",
            attributes: SubjectAttributes {
                kind: SubjectKind::Known(AccountKind::Agent),
                handle: None,
                depth: None,
            },
            universal: test_universal(),
            client_id: None,
            collection: "app.bsky.actor.profile",
            action: WriteAction::Delete,
            diff: Diff {
                changes: &[deleted],
            },
            before: None,
            after: None,
            lookups: &[],
        };
        assert!(matches!(evaluate(&subject, &tree), Verdict::Reject { .. }));
    }

    /// An "allowlist" policy — *"displayName may be set only to the
    /// account's own handle"* — is a deny rule like any other: it denies
    /// whenever the new value is not the handle. No allow variant is
    /// needed or used; this is [`SubjectAttributes`]'s worked example.
    struct HandleOnly;

    impl Evaluator for HandleOnly {
        fn compile(&self, _predicate: &serde_json::Value) -> CompileOutcome {
            CompileOutcome::Compiled(CompiledId(0))
        }
        fn evaluate(
            &self,
            subject: &Subject<'_>,
            _compiled: CompiledId,
        ) -> Result<Outcome, EvalError> {
            let Subject::Write {
                diff, attributes, ..
            } = subject
            else {
                return Ok(Outcome::Allow);
            };
            for change in diff.changes {
                if change.path != "displayName" {
                    continue;
                }
                let Some(after) = change.after else {
                    continue;
                };
                let allowed = attributes
                    .handle
                    .is_some_and(|handle| after.as_str() == Some(handle));
                if !allowed {
                    return Ok(Outcome::Reject {
                        reason: "displayName must be the account's handle".into(),
                    });
                }
            }
            Ok(Outcome::Allow)
        }
        fn observe(&self, _event: &Observed<'_>) {}
        fn lifecycle(&self, _event: &Lifecycle<'_>) {}
        fn staleness(&self) -> Staleness {
            Staleness::Linearized
        }
    }

    #[test]
    fn an_allowlist_is_expressed_as_a_deny_rule() {
        let tree = tree_with_evaluator(Arc::new(HandleOnly));
        let handle_value = serde_json::Value::String("alice.did.bot".into());
        let other_value = serde_json::Value::String("someone-else".into());

        let matches_handle = Change {
            path: "displayName",
            before: None,
            after: Some(&handle_value),
        };
        let subject = Subject::Write {
            account: "did:plc:agent",
            attributes: SubjectAttributes {
                kind: SubjectKind::Known(AccountKind::Agent),
                handle: Some("alice.did.bot"),
                depth: None,
            },
            universal: test_universal(),
            client_id: None,
            collection: "app.bsky.actor.profile",
            action: WriteAction::Update,
            diff: Diff {
                changes: &[matches_handle],
            },
            before: None,
            after: None,
            lookups: &[],
        };
        assert_eq!(evaluate(&subject, &tree), Verdict::Allow);

        let does_not_match = Change {
            path: "displayName",
            before: None,
            after: Some(&other_value),
        };
        let subject = Subject::Write {
            account: "did:plc:agent",
            attributes: SubjectAttributes {
                kind: SubjectKind::Known(AccountKind::Agent),
                handle: Some("alice.did.bot"),
                depth: None,
            },
            universal: test_universal(),
            client_id: None,
            collection: "app.bsky.actor.profile",
            action: WriteAction::Update,
            diff: Diff {
                changes: &[does_not_match],
            },
            before: None,
            after: None,
            lookups: &[],
        };
        assert!(matches!(evaluate(&subject, &tree), Verdict::Reject { .. }));
    }

    /// A policy on token issue is not asked at sign-in, and one on sign-in
    /// is not asked at token issue. An operator who denies a client only
    /// `oauth.authorize` lets its existing logins keep their tokens.
    #[test]
    fn a_grant_policy_and_a_token_policy_are_asked_apart() {
        let client = ClientId::parse("https://client.example/metadata.json").unwrap();
        let mut builder = PolicyTree::builder();
        let deny = builder.register_evaluator(Arc::new(Fixed::new(Outcome::Reject {
            reason: "no".into(),
        })));
        let at_token = Applicability::Token {
            client_ids: Scope::Only(vec![client.as_str().to_owned()]),
        };
        builder.add_policy(PolicyDeclaration {
            applicability: at_token.clone(),
            observes: at_token,
            staleness: Staleness::Linearized,
            predicate: Predicate::Evaluator(deny, CompiledId(0)),
            revision: Revision(1),
        });
        let tree = builder.build();

        let grant = Subject::Grant {
            universal: test_universal(),
            client_id: &client,
            requested_scopes: &["atproto"],
        };
        let token = Subject::Token {
            account: "did:plc:agent",
            attributes: SubjectAttributes {
                kind: SubjectKind::Known(AccountKind::Agent),
                handle: None,
                depth: None,
            },
            universal: test_universal(),
            client_id: &client,
            scopes: &["atproto"],
        };
        assert_eq!(evaluate(&grant, &tree), Verdict::Allow);
        assert!(matches!(evaluate(&token, &tree), Verdict::Reject { .. }));
    }
}