Kerberos v3.1: Add Query Plans (planResources)

[Alex-Dolid]

This pull request introduces a major feature release for @alexify/kerberos (v3.1.0), adding a Cerbos-compatible resources query plan API (planResources) and related infrastructure, improving wire safety, and enhancing documentation and tooling. It also updates CI to track bundle size and expands lint/format coverage. The most important changes are summarized below.

---

Major Feature: Query Planning

• Added kerberos.planResources(args), a Cerbos-compatible resources query plan API that partially evaluates policies and returns a filter tree for unknown resource fields, supporting complex policy features and full parity with isAllowed. Includes partial evaluator, ReBAC bridge, multi-action planning, and observability/metrics.
• Introduced supporting infrastructure in src/planning/ for plan node modeling, partial evaluation, and ReBAC operand expansion, with detailed documentation and invariants in CLAUDE.md.
• Public API and documentation updated to include planResources, with a new section in CLAUDE.md and expanded README references. [1] [2]

Wire Safety, Security, and Stability

• Ensured query-plan filters only emit JSON-safe values; conditions with unsafe values degrade to the opaque operator. Compiled $expr ASTs are now deeply frozen at parse time to prevent mutation attacks. Documented these guarantees and security implications in SECURITY.md. [1] [2]
• Fixed plan construction to handle circular principal attributes, and ensured JSON round-trip safety for filters.

Tooling and CI Enhancements

• Added a pnpm size script (using esbuild) to measure browser bundle size, with CI integration for smoke testing and visibility in logs. [1] [2] [3] [4]
• Lint and format scripts now cover scripts/ and bench/ directories for improved code quality.

Benchmarks and Examples

• Added a benchmark scenario for planResources in bench/bench.js, demonstrating partial evaluation and filter generation for complex policies.

Documentation and Versioning

• Updated CHANGELOG.md for v3.1.0 with a comprehensive list of features and fixes.
• Updated package version to 3.1.0 and clarified supported versions in SECURITY.md. [1] [2]

---

These changes significantly expand Kerberos.js's capabilities for query planning and Cerbos compatibility, while improving safety, observability, and developer experience.