durable

Documentation

Overview

Package durable is rawclaw's transcript vault: the raw, rawclaw-OWNED copy of every session it indexes, plus the small sidecar of index facts that copy cannot carry by itself. It exists so the index databases are a rebuildable CACHE rather than the only place retained history lives — today a session whose source file was purged upstream survives solely as rows in a db, which makes deleting that db a silent, unrecoverable history loss.

The on-disk shape is the one the claude-web import already writes: one JSONL file per session in Claude record shape, staged in a temp file and committed by rename so a crash mid-write can never leave a half-transcript in the tree. Content blocks are stored VERBATIM wherever the source is already in that shape (a byte copy), so a rebuilt index is byte-identical to the live one.

Index

• func Has(id string) bool
• func PathFor(id string) (string, error)
• func Remove(id string) error
• func Root() string
• func SetOnlyCopySince(id string, since float64) error
• func StoreFile(m Meta, src string) error
• func StoreMessages(m Meta, msgs []model.Message) error
• type Meta
  • func (m *Meta) UnmarshalJSON(data []byte) error
• type Session
  • func List() ([]Session, error)

Functions

func Has

func Has(id string) bool

Has reports whether a session is already vaulted.

func PathFor

func PathFor(id string) (string, error)

PathFor is the vault transcript path for a session id. A subagent id is lineage-namespaced ("parent/child"), so its slashes nest as directories the same way the source tools nest their own trees.

func Remove

func Remove(id string) error

Remove deletes a session's durable copy. This is the delete path for a real user delete (an explicit tombstone): retention prunes the row, and the vault must not hold a copy that a later rebuild would resurrect.

func Root

func Root() string

Root is the vault directory. Resolved per call rather than cached, because a test (and a user moving XDG_DATA_HOME) must be able to redirect it.

func SetOnlyCopySince

func SetOnlyCopySince(id string, since float64) error

SetOnlyCopySince records (since > 0) or clears (since == 0) the retention watermark on a vaulted session, indicating RawClaw is now the only copy after the CLI deleted its transcript. A session that was never vaulted is not an error: there is simply no durable copy to annotate.

func StoreFile

func StoreFile(m Meta, src string) error

StoreFile vaults a source file that is ALREADY in Claude record shape, by copying its bytes verbatim. Verbatim rather than re-serialized because the index is built by re-parsing this file: any normalization we applied here would show up as a diff between the live index and the rebuilt one. A source whose fingerprint already matches the vaulted copy is not rewritten, only un-flagged: a full reindex re-offers every file rawclaw has ever seen, and copying an unchanged corpus byte for byte on each one is pure cost. The un-flag is not optional though — reaching here means the file was just read off disk, so a stale "its source is gone" watermark in the sidecar would outlive the truth and mislabel a live session after the next rebuild.

func StoreMessages

func StoreMessages(m Meta, msgs []model.Message) error

StoreMessages vaults a session whose source is NOT Claude-shaped (a Codex rollout, say) by rendering its already-flattened messages INTO that shape. One format for the whole vault, so the rebuild has exactly one reader.

Types

type Meta

type Meta struct {
	ID            string  `json:"id"`
	Source        string  `json:"source"`
	Origin        string  `json:"origin,omitempty"`
	Project       string  `json:"project,omitempty"`
	CWD           string  `json:"cwd,omitempty"`
	IsSubagent    bool    `json:"is_subagent,omitempty"`
	ParentID      string  `json:"parent_id,omitempty"`
	SourcePath    string  `json:"source_path,omitempty"`
	SourceMTime   float64 `json:"source_mtime,omitempty"`
	SourceSize    int64   `json:"source_size,omitempty"`
	SourceFP      string  `json:"source_fp,omitempty"`
	OnlyCopySince float64 `json:"only_copy_since,omitempty"`
	StoredAt      float64 `json:"stored_at,omitempty"`
}

Meta is what the transcript itself cannot carry: where the session came from, which db columns were derived outside the file, and the retention watermark.

SourcePath/SourceMTime/SourceSize/SourceFP are recorded so a rebuild can restore the file_index watermark keyed on the ORIGINAL source path. Keying it on the vault path instead would be actively harmful: the next live pass compares file_index paths against the source walk, so a vault-keyed row reads as "source absent" and would stamp only_copy_since on a perfectly live session.

func (*Meta) UnmarshalJSON

func (m *Meta) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals Meta, supporting legacy sidecars carrying missing_since.

type Session

type Session struct {
	Meta
	Transcript string
}

Session is one vaulted session: its meta plus the transcript's absolute path, so a caller enumerating the vault can read the transcript without rebuilding the path from the id.

func List

func List() ([]Session, error)

List enumerates every vaulted session, sorted by id so a rebuild is deterministic. A transcript whose sidecar is missing or unreadable is still returned, with the id recovered from its path — a stranded transcript is history, and dropping it would defeat the point of the vault.