session

Module: enforcement::session

Contents

Modules

• persistent - File-backed session-state store (AARM R2 G4).
• state - Per-session runtime state for Stage 2 quantitative constraint enforcement.

---

Module: persistent

File-backed session-state store (AARM R2 G4).

[PersistentSessionStateStore] is an alternative [SessionStateStore] backend that mirrors per-session runtime state to a local append-only JSONL file so state survives LRU eviction and process restart. Selected by constraint_enforcement.session_state_backend = "persistent".

Design

• An in-memory LruCache is the read path (signals() is a cache peek — no file read on the hot path), preserving the local-only, bounded-latency enforcement invariants.
• record_action() updates the cache AND appends one JSON line to the log file. The append is a single local write syscall into the OS page cache; there is no per-request fsync, so durability against power loss is best-effort. The goal is to outlive eviction and clean process restart, not power failure.
• On construction the log is replayed; the last record per session wins, rebuilding the cache. Sessions exceeding capacity are evicted from the cache exactly like the LRU backend, but their state remains in the log and is restored on the next restart / cache miss replay.

Failure modes

Session-state bookkeeping is a constraint input, not a policy decision. Consistent with the in-memory backend (which degrades to a fresh session on mutex poison), IO failures degrade gracefully rather than fail-closing all enforcement: a corrupt or unreadable log starts from an empty cache; a failed append leaves the in-memory cache as the authoritative source for the running process. Construction itself surfaces file-open errors so a misconfigured path fails to start (fail-closed at startup) rather than silently losing persistence.

Module: state

Per-session runtime state for Stage 2 quantitative constraint enforcement.

V1 stores action count and risk_score per SessionId. Storage is in-memory with LRU eviction by default; a file-backed persistent backend is available via [crate::enforcement::session::PersistentSessionStateStore] (selected by constraint_enforcement.session_state_backend = "persistent").

The default in-memory store (LruSessionStateStore) evicts the least-recently-used session when capacity is exceeded, resetting an evicted session’s counters on next access. Since Cedar policies in V1 are monotone (action_count > N denies as count grows), eviction can only move a denying session back toward allowing — acceptable for V1 scope. The capacity is configurable via constraint_enforcement.session_state_capacity; the persistent backend preserves state across eviction and restart.