58 lines
2.2 KiB
Markdown
58 lines
2.2 KiB
Markdown
# @uncaged/nerve-daemon
|
|
|
|
The observation engine runtime for [nerve](../../README.md) — runs senses, routes signals, schedules reflexes, and manages workflows.
|
|
|
|
## Architecture
|
|
|
|
| Module | Responsibility |
|
|
|--------|---------------|
|
|
| **Kernel** | Top-level orchestrator — spawns workers, wires up signal bus, scheduler, and workflow manager. Supports hot reload and graceful shutdown. |
|
|
| **Sense Runtime** | Per-sense SQLite database (via `node:sqlite` + Drizzle ORM), migration runner, peer DB read access. |
|
|
| **Sense Worker** | Forked child process — one per sense group. Runs compute functions in isolation. |
|
|
| **Signal Bus** | In-memory pub/sub. Sense computes emit signals; reflexes and workflows subscribe. |
|
|
| **Reflex Scheduler** | Drives compute triggers — interval timers, signal-based events, throttle/coalesce logic. |
|
|
| **Workflow Manager** | Concurrency control (drop/queue), thread lifecycle, worker process management (RFC-002). |
|
|
| **Log Store** | Structured log storage in WAL-mode SQLite. Supports retention policies, archival to JSONL, and workflow run tracking. |
|
|
| **Blob Store** | Binary artifact storage for workflow outputs. |
|
|
| **File Watcher** | Watches `nerve.yaml` and sense files for hot reload. |
|
|
| **Daemon IPC** | Unix socket server for CLI ↔ daemon communication. |
|
|
|
|
## Key Design Decisions
|
|
|
|
- **One worker process per sense group** — isolation between groups, shared compute within a group
|
|
- **`node:sqlite` (DatabaseSync)** — zero native addons, WAL mode, built into Node.js ≥ 22.5
|
|
- **Throttle + coalesce** — if compute is in-flight, at most one pending trigger is queued (no unbounded accumulation)
|
|
- **Log ≠ Signal** — logs are queryable data assets but cannot trigger reflexes (prevents feedback loops)
|
|
|
|
## Usage
|
|
|
|
The daemon is typically started via the CLI (`nerve daemon start`), but can be used programmatically:
|
|
|
|
```typescript
|
|
import { createKernel } from "@uncaged/nerve-daemon";
|
|
|
|
const kernel = await createKernel(nerveRoot);
|
|
await kernel.ready;
|
|
|
|
// Trigger a sense manually
|
|
kernel.triggerSense("cpu-usage");
|
|
|
|
// Check health
|
|
const health = kernel.getHealth();
|
|
|
|
// Graceful shutdown
|
|
await kernel.stop();
|
|
```
|
|
|
|
## Install
|
|
|
|
```bash
|
|
pnpm add @uncaged/nerve-daemon
|
|
```
|
|
|
|
Requires Node.js ≥ 22.5 (for `node:sqlite`).
|
|
|
|
## License
|
|
|
|
MIT
|