Release v0.3.0-alpha.3

[hardbyte]

Third alpha of the v0.3 line. Consolidates everything merged since alpha.2 on crates.io (#37, #38, #39).

Summary

• Bump version 0.3.0-alpha.2 → 0.3.0-alpha.3 (pre-release).
• Convert CHANGELOG [Unreleased] → [0.3.0-alpha.3] - 2026-06-01.

What's new since alpha.2

API ergonomics

• PermissionChecker::check(subject, action, resource, context) — convenience wrapper for RBAC/ABAC-only callers; wraps evaluate_in_session(EvaluationSession::shared_empty(), ...).
• PermissionChecker::named(name) + name() accessor; records on tracing spans as checker.name so multi-checker audit pipelines can disambiguate.
• EvalCtx::grant / deny / grant_with_facts / deny_with_facts shortcut methods that build a PolicyEvalResult tagged with ctx.policy_type — no more re-passing self.policy_type() in policy bodies.
• AccessEvaluation test helpers: assert_granted_by, assert_denied, assert_denied_with_reason_containing, plus the trace-aware assert_denied_by(policy_type) (symmetric with assert_granted_by) and assert_trace_contains(needle) for per-policy reason matching in the multi-policy case.

Performance

• Policy::policy_type return type changed from &str to Cow<'static, str>. Static-name policies are zero-allocation end-to-end through the helper path.
• PolicyBuilder-built policies now override Policy::evaluate_batch to short-circuit the batch-shared axes (.subjects() / .actions()) once for the whole batch. Bench-measured: 13–32% throughput win vs the same shape through the serial-loop default, growing with batch size; trace volume drops from N events to 1 for subject- or action-discriminator policies.
• Single-item evaluation path moves the policy's policy_type straight into the EvalCtx instead of cloning, saving one allocation per evaluation for dynamic-name policies.

Combinators

• NotPolicy::evaluate_batch bug fix: previously forwarded the outer BatchEvalCtx unchanged, so wrapped policy's batch leaves were tagged with "NotPolicy". Now reconstructs the inner ctx with the wrapped policy's name.
• AndPolicy/OrPolicy/NotPolicy drop redundant Cow::Owned(self.policy_type().to_string()) wrapping now that policy_type() already returns Cow<'static, str>.

Method renames

• evaluate_batch_with_context_in_session_by → evaluate_batch_in_session_by_resource
• filter_authorized_with_context_in_session_by → filter_authorized_in_session_by_resource

Old names are removed (no deprecation aliases — pre-1.0 clean break). Migrate via:

s/evaluate_batch_with_context_in_session_by/evaluate_batch_in_session_by_resource/g
s/filter_authorized_with_context_in_session_by/filter_authorized_in_session_by_resource/g

Documentation

• PermissionChecker rustdoc gains "One checker per resource type" and "Modeling list/scope endpoints" recipes.
• PolicyBuilder rustdoc gains "Type-inference notes" — three patterns that anchor <S, R, A, C> and the misleading "type annotations needed for &_" closure error.
• Crate-level "When to populate the Context type" section with concrete shapes (time-of-day, MFA freshness, device/network trust, request-wide parameters, tenant overrides). EvalCtx::context rustdoc carries the "same subject, same resource, different calls → different decisions" heuristic on hover.
• New examples/mfa_freshness_context.rs — Context grounded in a concrete decision (high-value refund approval gated on MFA freshness).
• FactSource rustdoc gains a (subject, scope) → resolved-id example showing the trait isn't relationship-shaped. Policy::evaluate rustdoc signposts the "register a FactSource instead of calling the backing service directly" pattern.
• Policy::evaluate_batch rustdoc names the serial-by-default design choice explicitly and points at the override shapes (join_all, FuturesUnordered, semaphore-bounded).

MSRV

• rust-version = "1.82" pinned in Cargo.toml. The pin caught three accidental 1.87-stdlib usages in test code during this alpha cycle.

Breaking since alpha.2

• Policy::policy_type return type changed (&str → Cow<'static, str>). Migrate impls with one line each: fn policy_type(&self) -> Cow<'static, str> { Cow::Borrowed("MyPolicy") }. Dynamic-name policies now return Cow::Owned(self.name.clone()) and pay an allocation per call (the previous &str API let them return &self.name without allocating).
• EvalCtx / BatchEvalCtx gain a policy_type: Cow<'static, str> field. Custom Policy impls and tests that construct these directly need to populate it.
• DelegatingPolicy constructor policy_type parameter changed from impl Into<String> to impl Into<Cow<'static, str>>.
• The two batch method renames above; no deprecation aliases.

Validation

• cargo fmt --all --check ✅
• cargo clippy --all-targets --all-features -- -D warnings ✅
• cargo test --all-targets --all-features ✅
• cargo test --doc --all-features ✅
• cargo publish --dry-run --allow-dirty ✅ (packaged cleanly, 48 files / 700KB)

[Copilot]

Pull request overview

Release prep for v0.3.0-alpha.3 by updating crate metadata and recording the release in the changelog.

Changes:

• Bump crate version 0.3.0-alpha.2 → 0.3.0-alpha.3 in Cargo.toml and Cargo.lock.
• Add a 0.3.0-alpha.3 section to CHANGELOG.md dated 2026-06-01.

Reviewed changes

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

File	Description
CHANGELOG.md	Adds the 0.3.0-alpha.3 release heading and places the existing release notes under it.
Cargo.toml	Updates the crate version to 0.3.0-alpha.3.
Cargo.lock	Updates the locked gatehouse package version to 0.3.0-alpha.3.

---

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