feat(policy): ACL push-down at retrieval — AclPolicyEngine (Step 6.3)

[officialCodeWork]

Summary

Step 6.3 — ACL push-down at retrieval: enforce label-based ACLs so a principal only retrieves chunks they're cleared for. Built as a single PR.

Step 6.1 resolved each tenant's acl_labels onto RequestContext.principal.acl_labels, but nothing enforced them — filter_pushdown scoped tenant_id only, so any principal in a tenant could read every chunk. 6.3 fixes that.

• AclPolicyEngine (rag-policy) — a thin decorator (like QuotaPolicyEngine, Step 4.5) that And-merges any_in("acl_labels", sorted(principal.acl_labels)) into every read_chunk push-down; a chunk is retrievable only when its labels overlap the principal's. Everything else delegates to the inner engine, so it composes with a production PDP rather than absorbing it.
• Overlap via the existing AnyIn predicate — the semantics the codebase already assumed (the FilterExpr docstring, the policy-engine extension example, the filter tests), and every backend translator already speaks it (pgvector &&, Qdrant MatchAny, Cypher ANY(), the noop evaluate). So no new predicate and no translator changes. Injected at the canonical HybridRetriever read_chunk PDP site (which already merges filter_pushdown), so no new call site / coverage-linter entry.
• Fail-closed: the clause is uniform — any_in([]) matches nothing — so a label-less principal retrieves nothing rather than everything. Public data is modeled as a shared label (e.g. public) granted to all principals (no special predicate). Each label-less request emits one PII-free acl.egress_denied event (the pre-registered EVT_ACL_DENIED).
• Opt-in via new cfg.acl.enabled (default false → pre-6.3 behaviour, tenant scoping only), because enforcement changes which chunks a principal can retrieve. build_app(acl_enabled=…) wraps the engine; build_app_from_config reads cfg.acl.

AclConfig → rag.schema (config-only; no dist/schemas or proto churn).

Scope & boundaries (see ADR-0035)

• Overlap (not subset) semantics — a principal needs one matching label, not all of a chunk's.
• Push-down enforcement only — post-retrieval egress re-verification is Step 6.4; graph edge ACLs (edge_filter) are deferred (only node_filter carries the clause today).

Documentation

• ADR-0035 — the decision + trade-offs
• docs/architecture/policy-engine.md — built-in ACL push-down note
• docs/reference/tenancy.md — ACL enforcement (6.3) section
• docs/README.md — ADR-0035 entry
• TRACKER.md — 6.3 ✅, Phase 6 3/10, overall 67/84, next action → 6.4, PR history

Test plan

• ruff check + ruff format --check clean
• mypy --strict clean (294 source files)
• RAG001 logging gate clean
• schema-drift regenerated (committed); policy-coverage + log-schema/event-registry pass
• full suite 2546 passed, 4 skipped
• ~17 new tests: an end-to-end ACL red-team through HybridRetriever — overlap / disjoint-labels / fail-closed / public-label / no-tenant-bypass (tests/redteam/test_acl_isolation.py); AclPolicyEngine unit + acl.egress_denied emission (tests/policy/test_acl_engine.py); config + gateway wiring (apps/gateway/tests/test_acl.py)

🤖 Generated with Claude Code