Add fact-load error helpers and PolicyBuilder::new_static

[hardbyte]

Summary

• AccessEvaluation::fact_load_errors() / denied_due_to_fact_load_error() — walk the evaluation trace for FactOutcome::Error provenance so callers can map infrastructure failure (e.g. HTTP 503) without hand-destructuring combinators. Authorization remains fail-closed; these helpers only expose why.
• PolicyBuilder::new_static(&'static str) — stores the policy name as Cow::Borrowed so fixed-name builder policies are zero-allocation end-to-end on the trace / ctx.grant path. PolicyBuilder::new remains the dynamic-name path.

Note: the undeclared-forbid tracing::warn! adoption guardrail from the original review is already on main (0.5).

Test plan

• Unit tests for fact-load helpers (backend error, missing fact, ordinary denial, grant)
• Unit tests for new_static (Cow::Borrowed) vs new (Cow::Owned) and grant-path name tagging
• cargo fmt --all
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test --all-targets --all-features
• doctests

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}

[Copilot]

Pull request overview

This PR adds convenience APIs to expose fact-loading failures from an evaluation trace (without changing fail-closed authorization semantics) and introduces PolicyBuilder::new_static to avoid allocations for fixed policy names by storing them as Cow::Borrowed.

Changes:

• Add AccessEvaluation::fact_load_errors() and AccessEvaluation::denied_due_to_fact_load_error() to surface FactOutcome::Error provenance across the full result tree.
• Add PolicyBuilder::new_static(&'static str) and convert builder/internal policy name storage from String to Cow<'static, str> to keep static names allocation-free on the trace path.
• Update docs/examples/bench comments and add unit tests covering the new helpers and new_static behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/tests.rs	Adds unit tests for fact-load error helpers and PolicyBuilder::new_static name storage/tagging.
src/results.rs	Implements trace-walking helpers for collecting/flagging fact-load errors from FactProvenance.
src/builder.rs	Introduces new_static and switches builder/internal policy name handling to Cow<'static, str>.
README.md	Updates examples and guidance to prefer PolicyBuilder::new_static for fixed names; documents new fact-load helpers.
MIGRATION.md	Notes new_static and the allocation accounting difference vs new.
examples/policy_builder.rs	Updates example policies to use new_static for fixed names.
CHANGELOG.md	Documents the newly added helper methods and new_static.
benches/permission_checker.rs	Updates commentary to reflect new_static availability and intended usage.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/results.rs:443

• denied_due_to_fact_load_error() currently allocates a Vec and walks the entire trace via fact_load_errors() just to compute a boolean. This can be implemented as an early-exit tree walk with no allocation, which matters when traces are large or on hot paths (e.g. per-request HTTP mapping).

    pub fn denied_due_to_fact_load_error(&self) -> bool {
        matches!(self, Self::Denied { .. }) && !self.fact_load_errors().is_empty()
    }

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.