xiaoju
a7e6caf6e7
Rewrite documentation across all packages to reflect current architecture, APIs, and CLI commands. - README.md: fix reflex examples, add store package, update config - core/README.md: add Sense→workflow routing, IPC types - daemon/README.md: complete module table, crash recovery, createKernel - cli/README.md: add workflow/sense/store subcommands - store/README.md: new file documenting LogStore/BlobStore Fixes #95
49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
# @uncaged/nerve-store
|
|
|
|
Persistent storage for the [nerve](../../README.md) 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
|
|
|
|
```bash
|
|
pnpm add @uncaged/nerve-store
|
|
```
|
|
|
|
Requires Node.js ≥ 22.5 (same as the rest of the stack).
|
|
|
|
## License
|
|
|
|
MIT
|