@uncaged/nerve-store

Persistent storage for the nerve daemon — append-only structured logs, optional JSONL cold archive, and content-addressable blobs.

LogStore (createLogStore, log-store.ts)

• Append-only log table — rows with source, type, refId, payload, ts (string payloads for ad hoc fields)
• SQLite WAL — DatabaseSync from node:sqlite
• Workflow run tracking — materialized workflow_runs table plus helpers to list active runs, upsert status transitions, and read thread messages / role rounds for CLI and crash recovery
• Meta key-value — small meta table (e.g. archive watermarks)

Public exports include LogStore, LogEntry, LogQuery, WorkflowRun, WorkflowRunStatus, ThreadRoundRow, GetThreadRoundsParams, and archive-related types re-exported from log-archive.

WorkflowRunStatus

Runs progress through a small state machine. Typical paths:

1. queued → started when a worker picks up the thread
2. started → completed | failed | crashed | interrupted | dropped

Semantics in the daemon/store layer:

• completed / failed — normal terminal outcomes from the workflow worker
• crashed — worker exited unexpectedly; manager may respawn and resume-thread eligible started runs
• interrupted — e.g. hot-reload drain killed an in-flight thread after timeout
• dropped — concurrency overflow: drop rejected a new run, or overflow: queue evicted an queued item when the queue was full

LogArchive (log-archive.ts)

• archiveLogs / helpers — export eligible UTC days of old rows to data/archive/logs/YYYY-MM-DD.jsonl, delete archived rows from SQLite, optional VACUUM
• Used by nerve store archive in @uncaged/nerve-cli

BlobStore (createBlobStore, blob-store.ts)

• Content-addressable storage — write returns lowercase sha256 hex; files live under data/blobs/<2-hex>/<62-hex>
• read / exists — path must match digest on disk (tamper detection)

Install

pnpm add @uncaged/nerve-store

Requires Node.js ≥ 22.5 (same as the rest of the stack).

License

MIT