# Jev Lab

Private direct-TypeSafe evaluation workbench. Origin: https://jev-lab.jessald.fairystack.com

The editor's state and question map are the core object. Presets contain illustrative input only; they are not observed Jev results. The app uses POST https://api.typesafe.ai/v1/systemone directly. No BrightWrapper or alternate-model fallback is involved.

## Authentication

AuthReturn app slug `jev-lab`. Browser uses the canonical AuthReturn component. APIs require the app's bearer JWT, verified locally against the live registered Cognito pool and audience. Runs are scoped to the verified subject. No token in links. Missing/invalid auth is 401; cross-account and unknown run IDs are 404. Private signup is disabled. FairyStack's ordinary app link supplies agent login.

## API

- GET /api/health: public process health, not provider connectivity.
- GET /api/version: public semantic version and deployed revision.
- GET /api/config: authenticated viewer identity, key configuration status, default model, deadline and temporary secure setup link. Configured means readable credential, not successful provider connectivity.
- POST /api/runs: JSON `{request_id,state,questions,model}`. `request_id` is a caller-generated UUID. Returns HTTP 202 with a persisted run, even on duplicate delivery. Identical IDs with different inputs return 409. One active evaluation per account; four globally. At most 32 questions and 64 KB per validated request.
- GET /api/runs: `{runs:[...]}`, last 100 current-user records, newest first.
- GET /api/runs/{id}: complete saved run, exact request, timestamps, model response, error and measured server elapsed time.
- POST /api/runs/{id}/cancel: `{}`. Stops owned observation/request and saves cancelled. The provider may already have processed or billed it.

Question contracts: Choice takes a description map (2–255 options in this workbench); Score takes 2–10 ordered descriptions; Noul takes a yes/no instruction and optional true/false descriptions. The direct API request and response contract is documented at https://docs.typesafe.ai/api . Response types, distributions, choice keys, score ranges and token usage are validated before completed status.

## Execution ownership and recovery

A single Node process owns execution. Runs are atomically written into the service-account DATA_DIR, mode 0600. States are queued → running → completed / failed / timed_out / cancelled. Each record has created_at, updated_at, started_at, finished_at, deadline_at, current step, and exact input. Time values are Unix milliseconds. Queued is persisted before work begins.

The provider call has a 15-second total timeout covering headers and body. A separate 20-second run deadline abandons even a dependency ignoring cancellation. Status reads reconcile overdue records. Startup fails unfinished runs with worker_lost; calls are never retried automatically. Late results cannot replace terminal records. No guessed progress percentages.

The browser has 10-second API deadlines and a 35-second observation limit. It shows disconnected/observation errors and a refresh action, restores controls, and keeps a run permalink for reload recovery. Refresh reads saved status and never resubmits. Uncertain POST delivery reuses the same request ID. A deliberate subsequent run uses a new ID. Drafts are kept per signed-in subject in tab-local sessionStorage. Server updates do not replace editor nodes.

## Provider credential

Only `/opt/secrets/typesafe.json` is read, freshly for every run. Expected `api_key` or `token` string. Install via FairyStack encrypted secret handoff, canonical SOPS store, sync, and manifest secret declaration. Never paste a key into the state/question editors, chat, source, or URL. Missing keys fail at credentials with no provider call. The temporary setup link expires; it is a transfer to the current session agent, not self-service provider installation.

## Evidence and cost

Successful results are actual validated provider responses. Failed runs retain the concrete error and failed step. Probability and Choice/Score confidence are separately labeled. No accuracy claim is derived from confidence. Cost is explicitly an estimate based on reported input tokens at $0.042/M, output free (official model docs checked 2026-09-20); not a billing receipt. Elapsed time is measured by this server and includes local overhead, not provider-only latency.

## Resource links

- `/`: current editable experiment and private notebook. Public shell; sign in for API reads and runs.
- `/?run={uuid}`: immutable request and terminal result for a recorded run. UUIDs are returned by POST/GET /api/runs, not guessed. While active, the same link shows current status; after termination, evidence does not change. Normal owner authentication is required; unknown/cross-owner IDs return 404. Example syntax: `/?run=550e8400-e29b-41d4-a716-446655440000` (illustrative, not a real run).
- `/#how-it-works`: living explanation of purpose, owner, decision types, deadlines and recovery; explanatory material, not a live provider-status report.
- `/agent-guide.md`: this API and resource contract, public, contains no private inputs or secrets.

## Verification boundaries

Offline automated tests use explicit fixtures and never populate the live notebook with simulated successes. A real successful Jev smoke test requires an installed, valid TypeSafe key. Until then only direct unauthenticated error behavior and the app's missing-key path can be verified live.