npm package: @relayplane/ledger
Description: Learning Ledger - immutable event store for agent operations
Author: RelayPlane
Latest version: 0.1.0

# @relayplane/ledger

Learning Ledger — the immutable event store for agent operations.

## Overview

The Ledger is the foundation of RelayPlane Agent Ops, capturing every run with full context including:

- **Auth tracking**: `auth_type`, `execution_mode`, `auth_risk`, `policy_override`, `compliance_mode`
- **Metrics**: `latency_ms`, `ttft_ms`, `input_tokens`, `output_tokens`, `cost_usd`
- **Decision audit**: Policy decisions, routing decisions, error details
- **Event log**: Append-only event stream for each run

## Installation

```bash
pnpm add @relayplane/ledger
```

## Quick Start

```typescript
import { createLedger } from '@relayplane/ledger';

const ledger = createLedger();

// Start a run
const runId = await ledger.startRun({
  workspace_id: 'ws_123',
  agent_id: 'agent_456',
  provider: 'anthropic',
  model: 'claude-3-5-sonnet',
  auth_type: 'api',
  execution_mode: 'interactive',
  compliance_mode: 'recommended',
});

// Complete the run with metrics
await ledger.completeRun(runId, {
  status: 'completed',
  input_tokens: 1000,
  output_tokens: 500,
  total_tokens: 1500,
  cost_usd: 0.015,
  latency_ms: 2500,
  ttft_ms: 150,
});

// Query runs
const runs = await ledger.queryRuns({
  workspace_id: 'ws_123',
  auth_type: 'consumer',
  execution_mode: 'background',
});

// Get usage statistics
const stats = await ledger.getUsageStats('ws_123', '2024-01-01', '2024-12-31');
console.log(`Auth risk runs: ${stats.auth_risk_runs}`);
```

## Auth Risk Tracking

The Ledger tracks auth risk for compliance monitoring:

| Field | Description |
|-------|-------------|
| `auth_type` | `'api'` or `'consumer'` |
| `execution_mode` | `'interactive'`, `'background'`, or `'scheduled'` |
| `auth_risk` | `true` if consumer auth used in non-interactive mode |
| `policy_override` | `true` if user explicitly overrode restrictions |
| `compliance_mode` | `'recommended'` or `'permissive'` at time of run |

## Event Types

The ledger captures these event types:

- `run.started` — Run initiated
- `run.auth_validated` — Auth check completed
- `run.policy_evaluated` — Policies evaluated
- `run.routed` — Provider/model selected
- `run.provider_called` — Request sent to provider
- `run.completed` — Run finished successfully
- `run.failed` — Run failed
- `run.retried` — Retry attempted
- `run.cancelled` — Run cancelled

## Storage Backends

### SQLite (default)

Local-first storage using SQLite with WAL mode:

```typescript
import { createLedger, getDefaultLedgerPath } from '@relayplane/ledger';

// Default: ~/.relayplane/ledger.db
const ledger = createLedger();

// Custom path
const ledger = createLedger({ dbPath: '/path/to/ledger.db' });
```

### Postgres (coming in Phase 2)

For cloud deployments with Supabase:

```typescript
// Coming soon
import { createLedger, PostgresLedger } from '@relayplane/ledger';

const ledger = createLedger({
  storage: new PostgresLedger({ connectionString: '...' }),
});
```

## API Reference

### Ledger Class

#### Run Lifecycle

- `startRun(options)` — Start a new run, returns `run_id`
- `completeRun(run_id, options)` — Complete a run with metrics
- `recordAuthValidation(run_id, payload)` — Record auth check result
- `recordPolicyEvaluation(run_id, decisions)` — Record policy decisions
- `recordRouting(run_id, decision)` — Record routing decision
- `recordProviderCall(run_id, payload)` — Record provider call timing
- `recordRetry(run_id, payload)` — Record retry attempt

#### Queries

- `getRun(run_id)` — Get single run by ID
- `queryRuns(options)` — Query runs with filters
- `countRuns(options)` — Count matching runs
- `getRunEvents(run_id)` — Get all events for a run
- `queryEvents(options)` — Query events with filters
- `getUsageStats(workspace_id, from, to)` — Get usage statistics

## License

MIT