Fail secure default + agent version persistance

[rennf93]

Description

Adopts guard-core >= 3.0.0 and tracks its fail_secure default flip with a
matching major bump (3.0.0 → 4.0.0). Adds two purely additive surfaces on the
adapter:

• FlaskAPIGuard.agent_stats read-only @property exposing the agent's buffer
  drop counters and transport circuit-breaker state.
• flaskapi_guard.__version__ exported via importlib.metadata, with a
  "0.0.0+unknown" fallback when the package is not installed (development
  from source).

Mirrors fastapi-guard 7.0.0.

---

Related Issue

N/A — release tracking the upstream guard-core 3.0.0 default flip.

Fixes #

---

Motivation and Context

guard-core >= 3.0.0 flipped SecurityConfig.fail_secure to True by
default. Bugs in security checks that previously slipped past as silent
fail-open responses now surface as HTTP 500. Tracking the upstream change as a
flaskapi-guard major bump gives users a clear migration signal.

The two additive surfaces close existing gaps:

• App teams running enable_agent=True had no first-class way to surface
  buffer drops or circuit-breaker trips on a Flask health endpoint without
  reaching into guard.agent_handler.get_stats(). FlaskAPIGuard.agent_stats
  fixes that with a read-only property that returns {"enabled": False} when
  no agent is wired and {"enabled": True, **agent.get_stats()} otherwise.
• from flaskapi_guard import __version__ pairs with guard-core >= 3.0.0's
  new SecurityConfig.agent_guard_version field so SaaS-side telemetry can
  attribute events to the exact adapter release.

---

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation change
• Performance improvement
• Code cleanup or refactoring

The breaking change is upstream-only: SecurityConfig.fail_secure default
flips to True via guard-core >= 3.0.0. flaskapi-guard's own public surface
adds two members and changes nothing.

---

How Has This Been Tested

Five new tests added:

• tests/test_extension/test_agent_stats.py
  • test_agent_stats_returns_disabled_when_agent_handler_unset
  • test_agent_stats_returns_enabled_with_agent_handler_stats
  • test_agent_stats_reflects_live_drop_counter_increments
• tests/test_reexports.py
  • test_version_exported_matches_package_metadata
  • test_version_falls_back_when_package_metadata_missing

Quality gates run locally:

• uv run ruff format --check flaskapi_guard tests — clean
• uv run ruff check flaskapi_guard tests — clean
• uv run mypy flaskapi_guard tests — clean
• uv run vulture flaskapi_guard tests vulture_whitelist.py — clean
• uv run xenon --max-absolute B --max-modules A --max-average A flaskapi_guard — clean
• uv run pymarkdown scan CHANGELOG.md docs/release-notes.md README.md — clean
• REDIS_URL=redis://localhost:6379 uv run pytest -W error --cov=flaskapi_guard --cov-branch — 221 passed, zero warnings

Coverage on touched files:

• flaskapi_guard/__init__.py — 100% line, 100% branch
• flaskapi_guard/extension.py — 100% line, 100% branch

---

Screenshots (if appropriate)

---

Checklist

• My code follows the code style of this project (Mypy, Ruff)
• I have added tests to cover my changes
• All new and existing tests passed
• My change requires a change to the documentation
• I have updated the documentation accordingly
• I have checked that my changes don't introduce any new warnings or errors
• I have updated the version number if necessary
• I have added any new dependencies to the appropriate requirements file (no new dependencies — importlib.metadata is stdlib)