Filesystem

Filesystem Session Store

Bundled reference Session Store. One file per session. Write + read in the same contract. Default store when no other is configured.

Reference only. Normative contract in Session Store.

---

Where sessions live

Sessions are stored under a directory chosen by config; default is under ~/.stud/sessions/. Each session is a directory:

~/.stud/sessions/<sessionId>/
  manifest.json     # append-only revisions
  journal.log       # ordered event-to-snapshot journal
  state/            # per-extension state slots
  audit/            # audit records

The exact file shapes are implementation details; the wiki does not specify them.

---

Semantics

Property	Value
Cardinality	Exactly one active per session.
Read + write	Both owned by this store for this session.
Reload	never — cannot change mid-session.
Cross-store resume	Not supported.

A session whose manifest declares this store must be resumed through this store. Attempting to resume from a different store fails fast with ResumeMismatch. See Persistence and Recovery.

---

Persistence model

flowchart LR
    Turn[turn boundary] --> Snapshot[write snapshot]
    Event[observable event] --> Journal[append to journal]
    Approval[approval decision] --> Audit[append to audit]
    Snapshot --> Disk
    Journal --> Disk
    Audit --> Disk

Loading

• Snapshot on turn boundaries (default) or on critical events (configurable).
• Journal captures ordering-sensitive state updates between snapshots.
• Audit records are durable independent of journaling.

Recovery replays journal from the last snapshot.

---

Atomicity

• Writes use temp files + rename.
• Fsync on close to survive power loss.
• Audit writes happen before the logical action they audit (audit-before-act discipline). See Audit Trail.

---

Retention

The filesystem store does not auto-expire sessions. The user manages ~/.stud/sessions/ manually or via their own tooling. A session that failed to terminate cleanly leaves state on disk; stud sessions list / /sessions enumerate.

---

Concurrency

• One process per session. The store locks the session directory to prevent concurrent writers.
• A stale lock (left over after a crash) is detected and removed after verification that no process holds it.

---

Security

• Files are user-readable by default; mode 0600 for manifest and journal.
• Resolved secrets never land in the manifest (see Session Manifest). They also do not land in journal or audit as values — only as references.
• Backups / syncs are the user's choice. A filesystem session is a regular directory; treat it as the sensitive log it is.

---

Related pages

• Session Store (contract)
• Session Manifest
• Persistence and Recovery
• Audit Trail
• Configuration Scopes