From b14859b9726185ab873356390068e887b7f486d3 Mon Sep 17 00:00:00 2001
From: t <t@tjp.lol>
Date: Sun, 7 Jun 2026 11:35:49 -0600
Subject: R2: redesign session store with wire-format identity

Replace the single-session SessionManager seam with a directory-backed
catalog. session_manager.zig -> file_system_jsonl_store.zig; the old
machinery becomes internal SessionFile, and a new FileSystemJSONLStore
implements the redesigned SessionStore vtable (create/list/resolve/latest/
load/appendMessages) minting Session/SessionInfo handles.

Session logs now record wire-format provider identity
({api_style, base_url, model, reasoning}) instead of a single provider
string or CLI aliases; no api_key material is ever stored. Disk* content
types renamed Stored*; the rich audit-oriented write record is
PersistentMessage (in-memory Message + WireIdentity + provenance).

Agent.init now takes a Session; persist_provider/persist_model display
strings deleted (banner stays alias-based, resume picks default model).
Message.metadata round-trips. Dangling-prompt recovery dropped. CLI
migrated to the catalog store for run/resume/list. Clean break, no version
bump (old logs wiped).
---
 docs/libpanto-cleanup.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

(limited to 'docs/libpanto-cleanup.md')

diff --git a/docs/libpanto-cleanup.md b/docs/libpanto-cleanup.md
index 9906091..fbb4708 100644
--- a/docs/libpanto-cleanup.md
+++ b/docs/libpanto-cleanup.md
@@ -487,6 +487,36 @@ running loop reads the tool set from*.
 
 ### R2 — session-log format: wire-format identity, no config aliases
 
+> **Updated during implementation (R2 landed):**
+> - `session_manager.zig` → **`file_system_jsonl_store.zig`**; the old
+>   `SessionManager` single-session machinery is now the internal
+>   `SessionFile`, and a new directory-backed catalog struct
+>   **`FileSystemJSONLStore`** implements the redesigned `SessionStore`
+>   vtable (`create`/`list`/`freeSessionInfos`/`resolve`/`latest`/`load`/
+>   `appendMessages`). It caches open `SessionFile`s by id so the
+>   buffer-until-first-assistant write discipline survives the separate
+>   user/assistant appends of one turn.
+> - The on-disk *content* types keep the name **`Stored*`** (e.g.
+>   `StoredMessage`, `StoredContentBlock`) to avoid colliding with the rich
+>   store write record `PersistentMessage` (which wraps an in-memory
+>   `Message` + `WireIdentity` + provenance). `Disk*` → `Stored*`/
+>   `Persistent*` accordingly.
+> - Wire identity on disk is a `WireStamp { api_style, base_url, model,
+>   reasoning }` on each `MessageEntry` (null on system entries), replacing
+>   the single `provider` string. The agent derives it from
+>   `Config.provider.wireIdentity()`; **`persist_provider`/`persist_model`
+>   display strings are deleted** — the CLI banner stays alias-based and
+>   resume picks the default model (the `match` helper stays deferred).
+> - **`Agent.init` now takes a `Session`** (minted via `store.create()` or
+>   resolved via `resolve`/`latest`) rather than a raw `SessionStore`; the
+>   agent adopts and frees `session.info` in `deinit`.
+> - **Dangling-prompt recovery dropped** (resolved decision below).
+> - `PersistentMessage` carries the provenance fields (`conversation`,
+>   `tools_available`); the agent currently passes an **empty
+>   `tools_available`** (the FS store ignores it; a real tool-manifest
+>   snapshot is a follow-up). `Message.metadata` round-trips through the
+>   `Stored*` layer; `Conversation.metadata` is not yet wired.
+
 The on-disk session format records **wire-format** provider/model identity
 (`api_style`, `base_url`, `model`, `reasoning`), replacing today's single
 `provider` string and any CLI-alias coupling. `Disk*` types are renamed to
@@ -566,6 +596,10 @@ internally for linking, just un-re-exported):
 
 ## Resolved decisions (formerly open)
 
+0. **Dangling-prompt recovery — dropped (R2).** The old `LoadedSession`
+   split out a trailing crash-orphaned user prompt so resume wouldn't
+   auto-resend it. `Session.load()` returns a plain `Conversation`; a
+   trailing user message round-trips like any other.
 1. **Conversation-level persistence — Agent-only.** A bare `Conversation`
    mutation is in-memory; persistence is strictly the `Agent` turn-path's job.
    Append-only provenance is preserved because every `PersistentMessage`
-- 
cgit v1.3