Storage

efr-store is the only crate that opens SQLite. This file describes what is on disk. The schema lands with efr-store in milestone 1; the tables below are the plan.

Directory layout

EFR_DATA_DIR and the matching variables for the other roots override each root, which is how tests and just run use temporary directories. Without its own variable, a root is below EFR_HOME when that is set ($EFR_HOME/config, data, state, runtime), else the XDG directory above; the runtime root falls back to /run/user/<uid>/efr when XDG_RUNTIME_DIR is unset and /run/user/<uid> is the user's own with mode 0700. efr paths shows each root and where it came from. The zsh plugin follows EFR_RUNTIME_DIR too, so a shell pointed at a just run daemon shows its notices. It drops a notice file whose time is before the shell loaded the plugin, unseen: such a file is for an earlier terminal with the same name, such as one before a reboot. The time of the file is the time of its last line, so one new line shows the older lines of the file too. config.toml may be a symbolic link (into a dotfiles repository); the daemon watches the directory of its target too, and efr config set writes the target and keeps the link.

Inside a call of the auto sandbox, the data, state and runtime roots are empty: only the conversation's $SCRATCH comes back, with $SCRATCH/jobs read-only, and the database reads as missing. So a sandboxed command cannot read the call files, the nonce, the cache layers of other conversations or the daemon's socket. The config root stays readable and read-only. efr paths names the launcher and the sandbox's state and runtime directories; docs/sandbox.md tells what each part does.

SQLite access

• rusqlite with the bundled feature, opened only through efr_store::db::open (clippy's disallowed-methods routes rusqlite::Connection::open* there).
• Pragmas: journal_mode=WAL, synchronous=NORMAL, busy_timeout=5000, foreign_keys=ON, journal_size_limit=64MiB, temp_store=MEMORY.
• One writer: StoreWriter is an actor that owns the only read-write connection. append(Batch) -> Seq writes events, projections, receipts and outbox rows in one transaction, then broadcasts the new events. Publishing in commit order needs no extra lock.
• Readers: a few read-only connections behind Readers::with(|conn| ...), used from spawn_blocking. Whether one reader thread beats a small pool is still open.
• Search: the reads of conversation search never take one of these readers, so a burst of keys in the picker cannot slow a prompt. SearchLanes has 3 read-only connections of its own (the terminal's list, its preview and a phone at one time), with a semaphore of their own; the permit goes back only when the blocking work ends. efrd's search indexer has one more read-only connection (IndexReader), outside that semaphore. Each of these 4 connections sets a page cache of 512 KiB. That is no hard cap: the bundled SQLite puts the page caches of all connections in one group whose limit is the sum of their sizes, so a lane can also use the room that the writer and the readers leave. They open on first use. An in-memory store runs them on the writer's connection.

Schema

• events(seq INTEGER PRIMARY KEY, conversation_id, turn_id, kind TEXT, payload JSON, created_at). seq is global and only grows. Triggers refuse each UPDATE and each DELETE, except the delete of an event of a deleted conversation from before its tombstone (migration 10, below). Events carry full state, never deltas, so a subscriber can resume from after_seq without the projections. The payload is the serde form of efr_protocol::Event; an unknown kind reads back as Event::Unknown { kind, payload } so old readers keep advancing.

• Projections conversations, turns, approvals, shells, compactions, jobs and job_notices are rebuilt from events by cargo xtask rebuild-projections, and a test asserts the rebuild matches. They serve listing and paging; they are not a second source of truth.

• receipts(command_id PRIMARY KEY, method, result JSON, seq, created_at). A duplicate command_id returns the stored result; a rejected one stays rejected; nothing is replayed automatically after a reconnect.

• outbox(id, kind, payload, replay_safe INTEGER, claimed_at, done_at). Replay-safe rows survive a restart; process-bound rows are cancelled at startup.

• recording_segments(pty_id, start_seq, path, bytes, started_at, closed_at) indexes the recording files. The collector reads all rows in one scan in the order of the primary key, with the shells row of each PTY, so it needs no index of its own. It deletes the rows in one writer transaction and unlinks the files after the commit. A stop between the two leaves only files without a row, and the next pass removes them. When the whole recording of a PTY goes, one row without a file stays at the offset after its last byte.

• turn_messages(conversation_id, turn_id, position, provider, model, message JSON, turn_seq), keyed by (turn_id, position): the exact messages of a finished turn with the provider's own items (provider_raw), which no event holds. Saved in the batch of the turn's terminal event (turn_seq is its sequence number); each conversation keeps every turn that no summary covers yet. Not a projection: the log cannot rebuild it, so a rebuild leaves it alone and it has no foreign key to turns. A conversation_compacted with a summary deletes the rows of the turns before its cut in the same batch.

• compactions(seq, conversation_id, compaction_id, has_summary, compaction JSON): one row per conversation_compacted event, a projection. A turn reads the newest row with a summary and the newest row of any kind with a query of their own, never from the page of newest events.

• jobs(conversation_id, number, turn_id, call_id, command, launch, state, started_at, ends_by, ended_at, exit_code, stopped_by, output_bytes, launcher_pid, launcher_start, start_seq, info JSON), keyed by (conversation_id, number): one row per background job, from job_started, job_ended and job_watch_matched. A restart of efrd reads the launcher's pid and start time here, never from a file that a job can write, and the job ids go on from the highest number. job_notices has one row per event that a notice tells about, so a start of efrd finds the notices that no turn took. turns.wake is 1 for a turn that a job notice started; the limits of wake turns per hour count these rows, also over a restart.

• conversations.route, shell_pid and routed_seq (migration 8): the slots of the terminals. A terminal keeps one conversation per scope key, a registered project or everything outside projects. A row with a tty is the conversation of that terminal's slot for its route (the JSON of efr_protocol::RouteScope); shell_pid is the shell that holds the slot, and routed_seq the slot's newest routed event, so the terminal's current conversation is its row with the highest. conversation_created with a tty and a route takes the slot from the row of the same tty and route; one from before routing by scope has no route and takes every row of its tty, as the daemon of then did. terminal_attached moves a conversation into a slot. A prompt_queued whose context names the row's tty sets routed_seq, and shell_pid only when it is unknown. turn_started gives a row without a route the key of its scope. efrd reads every slot at its start from these columns in one query. The index conversations_tty covers (tty, route), and conversations_route finds the newest conversation of a key. Only a row with a routed_seq, which a terminal held, can be picked up.

• The search index (migration 9): search_docs(seq, conversation_id, kind, text), one doc per indexed event, keyed by its sequence number: the text of a prompt (kind 0), a steer (1), an answer of the model (2) or the command line of a shell call (3), without the bodies of heredocs. search_fts is an FTS5 table over it: external content, unicode61 remove_diacritics 2, a prefix index of 3 characters, and merges in short steps (automerge 8, leaves of 1,000 bytes). search_titles(conversation_id, title, first_seq) holds the title of each conversation from its first indexed prompt. search_state holds the cursor (indexed_seq) and the version of the redaction. efrd writes these tables only from text that it cut, cleaned and redacted (the index never holds a secret that the redaction recognises, a control character, the output of a command or the contents of a file). They are not projections: the log cannot give them back without efrd's redaction, so a rebuild of the projections leaves them alone. The batch that ends a turn writes nothing here. The index conversations_updated (updated_at, last_seq) gives the recent list and the titles of a search newest first with no sort. The delete of a conversation deletes its search_docs rows, each with an FTS5 'delete', and its search_titles row; a page of the indexer that it read before the delete writes no doc of a deleted conversation.

• The deletes of conversations (migration 10): conversation_deletes(conversation_id, seq, requested_at, parts JSON, rows_done_at, done_at), the tombstone of each deleted conversation. conversation.delete goes in this order, so a stop of efrd at any point never leaves a part of the conversation visible:

  1. efrd stops the conversation's actor, its background jobs (it waits for their ends) and its hidden shell;
  2. the event conversation_deleted commits with the method's receipt. Its batch writes the tombstone row, with the PTYs and the undos that the conversation's events name (parts), and deletes the conversation's rows of the projections (conversations, turns, approvals, shells, compactions, jobs, job_notices). From this commit on, no list, search or read shows the conversation, and every later event of it fails its batch;
  3. writer jobs of at most 2,000 events each delete its events before the tombstone, their search_docs rows and the receipts that name them; the last job deletes its turn_messages, its search_titles row, its outbox rows (by the conversation_id of their payload) and the recording_segments of its PTYs, and sets rows_done_at;
  4. efrd deletes its snapshot refs in every store (refs/efr/<conversation>/, refs/efr-mirror/<conversation>/, refs/efr-undo/<conversation>/ and the home copies) and each root store that holds refs of no other conversation, such as the store of its $SCRATCH; then its files: recordings/<pty_id>/ of each PTY, each $SCRATCH dir whose marker names it, $XDG_STATE_HOME/efr/sandbox/<conversation>/, $XDG_RUNTIME_DIR/efr/sbx/<conversation>/, file-backups/<conversation>/ and undo-trash/<undo-id>/ of each of its undos;
  5. done_at marks the end. Each start of efrd finishes the deletes without done_at, before the socket opens. The tombstone event and the tombstone row stay: they hold no text, and the event keeps the sequence numbers above every event that went, so a number never names two events. A rebuild of the projections skips every event of a deleted conversation. The loose objects of the snapshot stores that only the deleted refs reached go with the prune of the delete when they are older than an hour, else at a later collection. The database file keeps the deleted bytes in its free pages until SQLite writes them again (no secure_delete), the FTS5 segments keep the tokens of the deleted docs, which no query matches any more, until a merge, and each copy of backups/ from before the delete keeps the conversation.

• The enrolled devices (migration 11): devices(device_id, name, public_key BLOB, key_fingerprint, node_stable_id, user_id, tailnet_stable_id, scopes JSON, created_at, last_seen_at, revoked_at), one row per device such as a phone. efrd writes the row only after the user confirms the pairing in the terminal. The public key is the 65-byte X9.63 form of a P-256 key. node_stable_id and user_id are the Tailscale Node.StableID and UserProfile.ID of the pairing connection, and tailnet_stable_id is efrd's own CurrentTailnet.StableID; each later connection of the device must show the same three. scopes is a JSON array of scope names and never holds admin. A revoke sets revoked_at and keeps the row; a revoked device never comes back. The partial unique index devices_active_key allows one device that is not revoked per key. Not a projection: no event holds a device, so a rebuild leaves the table alone.

Migrations

• SQL files in crates/efr-store/src/migrations/, named NNNN_<noun>.sql, embedded with include_str! and applied by rusqlite_migration (tracked in PRAGMA user_version, forward-only, one transaction per file).
• Before migrating, the daemon copies the database to backups/. The socket opens only after migrations finish.
• Milestone 1 ships 0001_events.sql, 0002_conversations.sql, 0003_receipts_outbox.sql, 0004_shells_recordings.sql, 0005_turn_messages.sql, 0006_compactions.sql, 0007_jobs.sql (the jobs of phase C), 0008_routes.sql (the route columns of the conversations, v0.0.4) and 0009_search.sql (the search index, v0.0.4), 0010_deletes.sql (the tombstones of deleted conversations, v0.0.5) and 0011_devices.sql (the enrolled devices of the remote milestone). Each step has a flag that says whether it changes a projection. The first start of an efrd with such a migration rebuilds the projections from the log once: about 3 s for 100,000 events in a debug build. 0009_search.sql, 0010_deletes.sql and 0011_devices.sql have no flag, so they rebuild nothing.
• 0009_search.sql creates the search tables empty, with the cursor at 0. After the start, efrd's indexer fills them in the background from the log (the backfill): it reads a page of at most 32 texts, 32 KiB of text or 20,000 events, cleans and redacts it, and writes it with one short writer job. After each page it waits 4 times the time of the job, at least 10 ms, so the backfill takes at most a fifth of the writer; while a turn runs, it writes at most one page per second. During the wait it already reads and cleans the next page. When a round wrote more than one page, it then merges the index's segments in steps at the same duty, until a step does no work. A store of 20,000 turns takes about two minutes. Until the backfill ends, a search finds fewer conversations and says how far the index is. After the commit of a search job, when the write-ahead log holds 500 frames or more, SQLite runs a passive checkpoint in that job. A turn's commit runs one at 1,000 frames, as before; beside the indexer it seldom reaches that.
• The index only grows. It takes at most 10 MB per 1,000 turns of the bench corpus (whose text has long answers and heredocs), so at 20 turns a day about 73 MB a year. The file never gets smaller (no auto_vacuum), and each backup of backups/ before a migration holds the index too. A change of what the redaction replaces increases REDACTION_VERSION (efr-conversation), and the next start empties the index and builds it again from the start of the log: a full backfill. The free pages of the old index are used again.
• A migration never edits an earlier file. New columns use ALTER TABLE ... ADD COLUMN with a default so old projections keep reading.
• Tests call Migrations::validate() and migrate a copy of every fixture database in crates/efr-store/fixtures/db/.

Recording format

Each PTY's output is appended to segment files where the byte offset is the stream sequence. Every chunk has a 16-byte header with a kind and a timestamp, followed by its bytes: kind 1 holds raw output bytes, kind 2 holds a new size of the PTY (columns and rows) at the offset of the next output byte, and takes no stream bytes. A recording from before kind 2 reads as before. A segment rotates at 8 MiB; a segment that holds sizes alone never rotates. pty.attach(since_seq) and the shell tool's output slices read through efr_store::recording::read_range(pty_id, start, end). Shell marks carry recording offsets, so the output of one command is the range between its OSC 133 C and D marks.

A recording is a resume buffer and a record of recent output, not a permanent record. When the collector deleted the first segments of a PTY, a read reports a later start (RecordedRange::start): the offset of the first segment that is left, or for a recording that went whole, the offset after its last byte. pty.attach with an older since_seq then starts with a screen snapshot for a running shell, and replays only what is left for an exited one.