feat(policy): ACL egress verifier — defense-in-depth re-check (Step 6.4)

[officialCodeWork]

Summary

Step 6.4 adds the ACL egress verifier — a post-retrieval re-check that backstops the Step 6.3 ACL push-down. The push-down is the primary, source-side layer (re-implemented by each backend translator); this is the independent second layer the tests/policy/coverage.py linter docstring already anticipated.

• AclEgressVerifier.verify(ctx, refs) (rag_policy.egress) keeps only returned ChunkRefs whose acl_labels overlap the principal's — the same overlap semantics as the push-down, so it's a no-op on a correctly-filtered result and only ever acts on a genuine leak. Reads ChunkRef.acl_labels (populated by every backend regardless of the filter applied) → no re-hydration, O(results) set-intersection.
• Independent of the PolicyEngine (consults only ctx.principal.acl_labels), so a filter-translation bug, a backend that ignores the predicate, or a path wired without the engine can't leak an over-privileged chunk.
• Layered at the retrieval router boundary via a thin SupportsRoute wrapper (AclEgressVerifyingRouter, kept in the gateway so rag-retrieval stays free of rag-policy) around app.state.retrieval_router — query / retrieve / corpus / OpenAI / agent all inherit it, a layer above HybridRetriever.
• Opt-in, on-by-default behind ACL: cfg.acl.verify_egress (default true) gated on cfg.acl.enabled; set false to run the push-down alone. app.state.acl_verify_egress reports the effective state.
• acl.egress_violation event (EVT_ACL_EGRESS_VIOLATION, error level, PII-free: tenant / principal / counts / dropped chunk ids) on a caught leak — the unexpected push-down failure, distinct from 6.3's expected acl.egress_denied. A clean pass is silent.

Scope / deferred: covers the gateway retrieval surfaces; trusts the labels the backend reports on each ChunkRef (catching a mislabelling backend needs authoritative re-hydration — deferred); per-tenant/per-label violation metrics deferred to the 6.x governance dashboards.

Tests & gates

• ~21 new tests: verifier unit (tests/policy/test_acl_egress.py), red-team zero-violation-rate gate (tests/redteam/test_acl_egress_verifier.py — bypassed push-down + a leaky backend → verifier drops every violation), gateway wiring + behavioral drop (apps/gateway/tests/test_acl.py), event-schema registry.
• Full suite: 2299 passed, 1 skipped. Green: ruff, mypy --strict (296 files), RAG001, policy-coverage linter, log-schema/event-registry, config schema-drift (dist/rag.schema.* regenerated for verify_egress).

Documentation

• New ADR-0036 — ACL egress verifier (the decision + the two-layer model).
• docs/reference/tenancy.md — new "ACL egress verifier (Step 6.4)" section + scope bullet.
• docs/architecture/policy-engine.md — second-layer note; corrected the stale "Step 6.4 superseded" line.
• docs/README.md — ADR-0036 row, tenancy ref + ADR-0005 note updated.

Test plan

• uv run pytest tests/ packages/ -m "not integration" — 2299 passed, 1 skipped
• uv run ruff check + ruff format --check — clean
• uv run mypy packages/ apps/gateway/ — no issues (296 files)
• RAG001 + policy-coverage + event-schema + config schema-drift gates
• Red-team gate proves zero escaped-violation rate with the push-down bypassed

🤖 Generated with Claude Code