Add extensible Egress Gate OpenShell middleware

[johnnygreco]

Summary

• add Egress Gate, extensible OpenShell pre-credentials middleware built around immutable HTTP request values and ordered custom gates
• ship regex detection, denial, and redaction as the sole built-in gate
• add an application-owned registry with lazy schema sealing, typed resources, and a concise function-gate helper
• support explicit proceed, allow, and deny control, validated body/header mutations, OpenShell-compatible findings, and atomic active-policy replacement
• add offline evaluation, runnable function-based and class-based custom-gate examples, registration tooling, documentation, and repository integration
• simplify capability declarations with immutable GateCapability sets and remove unnecessary shared caching and defensive wrappers

Why

The previous engine abstraction operated only on decoded request bodies and coupled observations to a global action. The new gate contract lets trusted extensions inspect the complete bounded OpenShell request, own their explicit behavior, and compose cleanly while keeping transport concerns in the service adapter.

The implementation deliberately favors a small readable package layout, exact typed configuration, and proportional validation. Deterministic network policy remains the responsibility of OpenShell, and semantic judgment is not included.

User and developer impact

Operators can configure the built-in regex gate for detection, denial, or redaction. Developers can implement a resource-free custom gate as one typed function registered on an application-owned registry, or use the full class-based API when initialization or typed resources are required. Legacy APIs and configuration are intentionally not preserved.

The examples now provide direct commands for inspecting and testing gates, adding or removing the default OpenShell gateway registration, and comparing the function and class extension APIs.

Validation

• full Egress Gate checks: 220 tests passed
• minimum Python 3.11 checks: 220 tests passed
• Ruff formatting and lint checks
• ty type checks and import audit
• dependency audit
• repository Dev Notes renderer tests
• strict documentation staging and build

[github-actions]

Documentation preview

The preview has been removed.

[johnnygreco]

Panel review — clean

Frozen target: base a5e007d, final head 6756086.

Three independent lenses covered correctness/security/concurrency/OpenShell integration and packaging; public API/extensibility/maintainability/tests; and documentation/CLI/adoption/repository integration. Data-migration and native/FFI lenses were not applicable.

Round 1 found one low-severity terminology issue: lifecycle guidance still said the registry was finalized after the API moved to automatic sealing. Commit 6756086 corrected that wording and the related test and schema docstrings. The affected documentation lens reran against the new head and returned clean. The other two lenses returned clean in round 1.

Validation is green: 219 tests in the default and Python 3.11 environments, formatting, lint, type and dependency checks, documentation build, Dev Notes tests, and all required PR checks. No unresolved panel findings remain within the stated readability-first ambition ceiling.

[johnnygreco]

Final holistic review

Reviewed the frozen range a5e007dd813c0678ee8331d1c440a3b9373a36e8..fcc1100 across core correctness, extension API and maintainability, documentation, operator workflow, accessibility, and repository integration.

Three independent follow-up reviewers returned clean after the final fixes. The review explicitly filtered out speculative hardening and broad defensive rewrites. We kept narrow contract and usability fixes, then removed two pieces of unnecessary enforcement: cancellation-aware cache publication and registry policing of trusted Pydantic configuration overrides.

Validation completed:

• make check — 232 tests passed
• make check-py311 — 232 tests passed
• python3 tests/test_render_dev_notes.py — 11 tests passed
• scripts/build-docs.sh — strict documentation build passed
• GitHub Actions — all required checks passed

No unresolved merge-blocking findings remain.