jsonl

Overview ¶

Package jsonl is the default durable thread.Storage: one directory, one <id>.jsonl file per session — the header line first, then one entry per line in append order (ADR 0011). A session file is what the format is: readable with jq, backup-able with cp, append-only.

The durability rules (ADR 0011 §4–§5): Create writes the header and fsyncs the file and the directory; Append writes all of its entries in one write and fsyncs (FsyncOnFlush defers that to Flush). One writer per session, enforced with an advisory lock held from a session's first write until the process exits or the session is deleted — a second writer, in this process or another, fails with thread.ErrLocked. Readers never lock: Load and List read at any time, and a load that catches a torn final line (a crash mid-write) drops it and says so in the LoadReport.