# Polyform backend

FastAPI + SQLite control plane for releases, pseudonymous clients, balanced or random composition assignment, telemetry, statistical analysis, and quarantine-driven recomposition.

## Run

```bash
cd backend
uv sync --extra test
POLYFORM_DB=polyform.db .venv/bin/polyform-server
```

The API and OpenAPI explorer are available at `http://127.0.0.1:8000/docs`. CORS permits the local Vite dashboard by default; set `POLYFORM_CORS_ORIGINS` to a comma-separated allowlist for other origins.
Set `POLYFORM_RANDOM_SEED` only for reproducible experiments; normal service
runs use system randomness.

Seed the reference ZIP implementation pool and run an experiment through the real HTTP API:

```bash
.venv/bin/polyform-seed
.venv/bin/polyform-simulate --release 1 --clients 100 --runs 10 \
  --mode diversified --strategy balanced \
  --bad locate_end_of_central_directory.faulty_short_comment
```

Use `--mode homogeneous` for a single-composition cohort, `--strategy random` to compare assignment strategies, and `--bad-pair ID_A ID_B` to model an interaction fault.

The Python API also exposes `run_quarantine_experiment(...)`, which runs the
same pseudonymous cohort before quarantine, quarantines the selected variants
through HTTP, refreshes their assignments, and runs a post-quarantine epoch.

## API

- `GET /health`
- `POST|GET /api/v1/releases`, `GET /api/v1/releases/{id}`
- `POST /api/v1/clients`, `GET /api/v1/clients/{id}/composition`
- `POST /api/v1/executions`
- `POST|GET /api/v1/telemetry`
- `PUT /api/v1/implementations/{id}/status`
- `GET /api/v1/stats/implementations`
- `GET /api/v1/stats/interactions`
- `GET /api/v1/dashboard/summary`

Quarantining an implementation immediately excludes it from new assignments and recomposes every active affected client. Restoring it to `active` makes it eligible for future assignments without forcing current clients to adopt it. The dashboard summary reports a baseline plus one healthy-execution interval after every quarantine. Composition and telemetry payloads align with the authority schemas in `specs/`; telemetry accepts operational labels only, never archive paths, names, bytes, or file contents.

Implementation IDs are stable within a release and may be reused by later
versions. Pass `release_id` on the status endpoint when an ID exists in more
than one release; the dashboard and simulator do this automatically. Existing
databases created by the original globally keyed schema migrate in place at
startup.

Execution reports must include the `composition_revision` returned with the
assignment. The backend retains historical compositions so work already in
flight remains attributable after a quarantine-driven recomposition. Telemetry
may reference the same historical revision and execution. Call histories are
accepted only when every spec-function/implementation pair belongs to that
revision. `GET /api/v1/telemetry` accepts an optional `release_id` filter.

## Test

```bash
cd backend
.venv/bin/pytest
```
