tidaldb/docs/planning/milestone-4/phase-3.md

m4p3 — Policy Enforcement and Audit (✅ COMPLETE 2026-02-21)

Phase spec and acceptance criteria: ROADMAP · Milestone 4 · Phase 3. Milestone index: README.md. Backfilled record.

What shipped

1. Policy evaluation on the write path (tidal/src/session/policy.rs). Every session_signal call is checked before any state mutation. The evaluator returns a typed PolicyViolation { kind, .. } rather than a stringly-typed reason. The four kinds M4 shipped:

   PolicyViolationKind	Trigger
   Denied	signal type appears in denied_signals
   NotAllowed	allowed_signals is non-empty and the type is absent from it
   CountCap	signals_written reached max_signals_per_session
   Expired	wall clock passed max_session_duration

2. Error surface (tidal/src/db/sessions.rs:405-417). Expired maps to TidalError::SessionExpired; every other kind maps to TidalError::PolicyViolation (tidal/src/schema/error.rs:123). A rejected write mutates no session signal state — only the rejection counter and the audit log advance.

3. Bounded audit log (tidal/src/session/audit.rs). AuditEntry carries timestamp_ns, the signal type, an accepted flag, an AuditKind, and an optional reason. It is a VecDeque capped at MAX_AUDIT_ENTRIES = 10_000; past the cap the oldest entries are evicted and the snapshot's audit_truncated flag is set, so a reader can tell a complete log from a truncated one instead of silently believing a partial record.

4. db.session_audit(session_id) reads the live log for an active session; for a closed session the log ships inside the archived SessionSnapshot (audit_log field), so it is still readable after close and after restart.

Evidence

Criterion	Proof
A denied signal is rejected, counted, and audited with a reason	m4_uat.rs::step4_policy_rejects_denied_signal — asserts signals_rejected == 1, signals_written == 0, audit.len() == 1, !audit[0].accepted, audit[0].reason.is_some()
A signal absent from a non-empty allow list is rejected	m4_uat.rs::step5_policy_rejects_non_allowed_signal
Accepted writes are audited as accepted	m4_uat.rs::step3_session_signal_and_audit
Truncation is observable, not silent	session_durability.rs::audit_truncation_marker_set_when_cap_exceeded
Audit survives close	m4_uat.rs::step7_closed_session_snapshot, session_durability.rs::archived_session_readable_after_close_and_reopen

Divergence from the plan

• Typed kinds, not free-text reasons. The ROADMAP specified AuditEntry = { timestamp, signal_type, outcome: Accepted | Rejected(reason) } and a reason: String on the error. Shipped design keeps the human-readable reason but adds PolicyViolationKind and AuditKind enums, so callers branch on a variant instead of matching on prose. This is strictly better and is what M9/M10 later extended.
• The < 1 µs policy-evaluation criterion has no recorded measurement. The ROADMAP marks it [x] "(benchmarked)". It is a HashMap lookup on the write path, which makes the claim plausible, but no benchmark isolates it and no recorded run exists. tidal/benches/session.rs::session_signal measures the whole write including WAL, not policy evaluation alone. Treat the figure as unevidenced.
• The property test in the ROADMAP criteria is not present as a property test. "For any sequence of allowed and denied signal writes, the audit log exactly matches the write outcomes and no denied signal modifies session state" is proven by the concrete m4_uat.rs steps 3–5 and by session_durability.rs, not by a proptest. The invariant is covered; the stated form (randomized property test) was not built.

Extended later

M9/M10 governance (d8e4083) added seven further PolicyViolationKind variants — CommunityWriteDenied, CommunityWriteNotAllowed, ReadDenied, ReadNotAllowed, AttributeReadDenied, AttributeReadNotAllowed, ProfileOverrideNotAllowed — and the matching AuditKind variants (ReadDenied, AttributeReadDenied, ProfileOverrideRejected) plus the overrides_rejected counter on SessionSnapshot. The M4 mechanism is the one they extended: read-path and community policy reuse this evaluator and this audit log rather than adding a parallel one.