# M2b task 05: sessions on disk

**Branch:** `m2b` (run `git switch m2b`; `git status --short` must be empty, otherwise stop)
**Commit subject:** `Add the session store: baseline file and append-only log`

## Goal

A session is a directory: `sessions/<id>/0.baseline.json` and `sessions/<id>/0.jsonl`. This task
creates, opens, appends and resumes. The log is the state; there is no other file.

## Context

From the spec: "Nothing is written for a request until its completion is final, so the log always
ends at a record boundary." A log that does not is refused at resume, with the file and line named.
Nothing is repaired silently. The same rule as the audit log in the pre-M1 spec.

## Files

- Copy: `crates/loopd/tests/session.rs`
- Create: `crates/loopd/src/session.rs`
- Modify: `crates/loopd/src/lib.rs`, `docs/implementer-log.md`

## Interfaces

```rust
pub enum SessionError {
    Exists(SessionId),
    NotFound(SessionId),
    Io(PathBuf, std::io::Error),
    Torn { path: PathBuf, line: usize, why: String },    // lines start at 1; Display shows "<path>:<line>: …"
    Baseline(BaselineError),
    Encode(serde_json::Error),
}   // Debug; Display; std::error::Error

pub struct Session { /* private: id, dir, baseline, records, the open log file, next_call */ }
impl Session {
    pub fn dir_for(home: &Path, id: &SessionId) -> PathBuf;          // <home>/sessions/<id>
    pub fn create(home: &Path, id: SessionId, baseline: Baseline, slot: u32) -> Result<Session, SessionError>;
    pub fn open(home: &Path, id: SessionId) -> Result<Session, SessionError>;
    pub fn id(&self) -> &SessionId;
    pub fn dir(&self) -> &Path;
    pub fn baseline(&self) -> &Baseline;
    pub fn records(&self) -> &[LogRecord];
    pub fn append(&mut self, record: LogRecord) -> Result<(), SessionError>;
    pub fn next_call(&mut self) -> CallId;                           // 1, 2, 3, … within a session
    pub fn last_usage(&self) -> Option<proto::Usage>;                // the latest Usage record's numbers
}
```

Rules:

1. `create`: the directory must not exist (`Exists`). Create it, write `0.baseline.json` from
   `to_json()`, open `0.jsonl` with `create_new` and append, then append a `SessionStart` record
   with `Timestamp::now()`, epoch 0, the slot, and `baseline.hash()`.
2. `open`: `0.jsonl` must exist (`NotFound`). Read the baseline from `0.baseline.json`. Read the
   log: every line must end in `\n` and parse as a `LogRecord`, else `Torn` with its 1-based
   line number and the reason. `next_call` becomes one more than the highest `call` of any
   `ToolResult` in the log, or 1.
3. `append`: encode the record as one line, write it, `sync_data()`, and only then push it to the
   in-memory list. A record is never in memory without being on disk.
4. No `unwrap`. Every I/O error carries the path it concerns.

## Steps

- [ ] **1. Copy.** `git switch m2b`, then
  `cp docs/plans/M2b/files/crates/loopd/tests/session.rs crates/loopd/tests/`
- [ ] **2. See the test fail.** `cargo test -p loopd --test session`. Expected: it does not compile.
- [ ] **3. Write `session.rs`** and add `pub mod session;` to `lib.rs`. Run `cargo fmt --all`.
- [ ] **4. See the tests pass.** `cargo test -p loopd --test session`. Expected: `7 passed`.
- [ ] **5. Run the gate.** `make gate`. Expected last line: `gate: ok`.
- [ ] **6. Log and commit.** `git add crates/loopd docs/implementer-log.md && git commit`

## Done when

- `cargo test -p loopd --test session` reports 7 passed; `make gate` prints `gate: ok`.

## Stop and report if

- `a_torn_log_is_refused_with_the_line_number` cannot pass without editing the log on disk.