super-jev

# super-jev

A small TypeScript harness that connects **evidence → Jev judgments → permitted actions → verified outcomes**.

Domain-independent core. Pluggable data sources and tools. Local JSONL traces. Zero runtime dependencies. MIT licensed.

**Status: experimental V0.2.0.** Offline demos and mocked API tests pass. The organizer passed a live Jev smoke test with four synthetic records; the two original demos passed historical live smoke tests. This is an independent community project, not affiliated with TypeSafe AI. It contains no model weights.

## Run in a minute

Requires Node.js 24 or later. Node executes the TypeScript source directly; no install or build step is needed. Runtime tests do not perform static TypeScript checking.

```bash
npm run demo
npm run demo -- --documents
npm test
npm run replay -- runs/demo.jsonl
```

The default evaluator is a scripted fixture, clearly labeled in the console. Service recovery is simulated in memory. Document review writes a report into task state. Neither demo affects outside systems.

To use actual Jev decisions with those same local tools, set `TYPESAFE_API_KEY` in your environment, then:

```bash
npm run demo -- --live
npm run demo -- --live --documents
```

Alternatively copy `.env.example` to `.env`, fill it locally, and run `node --env-file=.env examples/demo.ts --live`. Never commit the filled file.

## What the harness does

1. Tracks a goal's domain state for one bounded run.
2. Calls the domain's `observe` hook to fetch fresh evidence and select context.
3. Sends a batch of typed questions to an interchangeable evaluator.
4. Validates answers, lets domain rules select an action, and checks its permissions and arguments.
5. Executes one registered tool, with cancellation signal and an idempotency key.
6. Reduces