netsky-db 0.1.6

netsky observability database
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

# netsky-db

Pure Rust observability database for messages, ticks, sessions, workspaces, clone dispatches, harvests, tool calls, git operations, directives, token usage, and watchdog events.

## Stack

- OLTP: redb key-value tables at `~/.netsky/meta.db`.
- OLAP: DataFusion SQL over Arrow `RecordBatch` snapshots.
- Bridge: redb JSON rows decode into typed Rust structs, then register as DataFusion `MemTable`s.

## Usage

```rust
use netsky_db::Db;
let db = Db::open()?;
db.migrate()?;
let rows = db.query("SELECT COUNT(*) AS n FROM messages")?;
```

CLI:

```sh
netsky query "SELECT source, COUNT(*) AS n FROM messages GROUP BY source"
```

## Schema v2

- `messages`: inbound and outbound bus, iMessage, email, iroh, and demo source messages.
- `cli_invocations`: command, argv JSON, exit code, duration, and host.
- `crashes`: crash kind, agent, and detail JSON.
- `ticks`: ticker and watchdog tick detail JSON.
- `workspaces`: workspace create/delete lifecycle.
- `sessions`: agent up/down/note events.
- `clone_dispatches`: clone lifecycle, brief metadata, branch, status, exit code, and detail JSON.
- `harvest_events`: source branch, target branch, commit SHA, status, conflicts, and detail JSON.
- `communication_events`: normalized iMessage/email/agent communications with source, tool, direction, IDs, handle, agent, body, status, and detail JSON.
- `mcp_tool_calls`: source, tool, agent, start/end, duration, success, error, timeout-race flag, and request/response JSON.
- `git_operations`: git operation, repo, branch, remote, from/to SHAs, status, and detail JSON.
- `owner_directives`: source, chat ID, raw owner text, resolved action, agent, status, and detail JSON.
- `token_usage`: session ID, agent, model, input/output/cached tokens, cost in USD micros, and detail JSON.
- `watchdog_events`: watchdog event name, agent, severity, status, and detail JSON.

## Writer APIs

- `Db::record_message(MessageRecord)`: source message envelope.
- `Db::record_cli(...)`: CLI invocation metadata.
- `Db::record_crash(...)`: crash event.
- `Db::record_tick(...)`: ticker or watchdog tick.
- `Db::record_workspace(...)`: workspace lifecycle event.
- `Db::record_session(...)`: agent session event.
- `Db::record_clone_dispatch(CloneDispatchRecord)`: clone lifecycle and brief metadata.
- `Db::record_harvest_event(HarvestEventRecord)`: cherry-pick and harvest results.
- `Db::record_communication_event(CommunicationEventRecord)`: high-level communication audit events.
- `Db::record_mcp_tool_call(McpToolCallRecord)`: MCP tool timing, success, errors, and timeout races.
- `Db::record_git_operation(GitOperationRecord)`: local git mutations and pushes.
- `Db::record_owner_directive(OwnerDirectiveRecord)`: trusted owner directives and resolved actions.
- `Db::record_token_usage(TokenUsageRecord)`: model token and cost accounting.
- `Db::record_watchdog_event(WatchdogEventRecord)`: watchdog state transitions and escalations.

## Query surface

`netsky query` registers every schema table in DataFusion:

```sh
netsky query "SELECT COUNT(*) FROM clone_dispatches"
netsky query "SELECT agent, SUM(input_tokens) FROM token_usage GROUP BY agent"
```

## Compatibility

The `Db::record_*` writer API remains stable. Legacy SQLite `meta.db` files are archived to `meta.sqlite-v1-<timestamp>.bak` before redb creates the new store.