# Polyform

Polyform helps you keep one implementation bug from affecting every user.
You write and review one complete behavioral specification. Then
`polyform generate --count 5` uses Codex by default to create shared tests and
five independently structured implementations of every specified function.
Each installation runs a different combination. Small success/failure reports
show which implementations are tied to problems, and quarantine stops
distributing suspicious code.

Humans are not expected to hand-write all of those implementations. The idea
is practical now because coding agents can produce and test enough code to make
software diversity affordable. Diversity does not guarantee that every future
vulnerability is already fixed, but it can leave another implementation ready
to distribute when one approach proves unsafe.

The reference application is a real Rust ZIP reader/extractor—not a simulation.
It lists and safely extracts stored and DEFLATE archives while validating the
central directory, local headers, filenames, paths, sizes, and CRC-32.

## Quick start on macOS

Prerequisites: Rust/Cargo, Python 3.11+, Node.js 20+, npm, and `curl`. `uv` is
used when available; `setup.sh` falls back to a normal Python virtual
environment.

```bash
./setup.sh
./demo.sh
```

The demo registers the Rust implementation catalog through FastAPI, creates a
balanced diversified population, submits real HTTP executions and observable
failure telemetry, ranks suspect variants, and starts the dashboard at
<http://127.0.0.1:5173>. In an interactive terminal every workload batch adds
new clients with newly assigned balanced compositions, so both client exposure
and execution counts keep changing. The two controlled faults remain active so you can use
the dashboard's **Investigate** filter, quarantine one, and watch the measured
healthy-execution percentage change as post-quarantine work arrives. The
intervention graph adds a separate stage after every quarantine, and quarantined
rows can be restored to future assignment. The demo also runs several actual
`zipdiv` processes against real ZIP fault triggers.

The services and workload stream remain available until Ctrl-C. Set
`POLYFORM_DEMO_KEEP_RUNNING=0` for the deterministic one-shot experiment, which
also compares homogeneous, random, and balanced cohorts, automatically
quarantines both controlled faults, and exits.

The complete measured report is written to `artifacts/demo-results.json`.
Nothing is deployed and no domain settings are changed.

## Platform workflow

This is one public monorepo for both halves of Polyform. The small hosted half
serves the catalog, dashboard, composition assignments, and telemetry. The
`polyform` binary keeps expensive work on contributors' own machines:

```bash
cargo install --path crates/polyform-cli
polyform init
# Finish the complete specification created in specs/example.toml.
polyform generate --count 5              # Codex is the default coding agent
polyform check
polyform keygen                         # once; keep .polyform private
polyform publish --server https://polyform.example \
  --artifact-url https://github.com/OWNER/PROJECT/releases/download/v0.1.0/zipdiv

polyform install zipdiv --server https://polyform.example
polyform update zipdiv --server https://polyform.example
```

When a hosted server has `POLYFORM_ADMIN_TOKEN` configured, publishers set the
same environment variable locally. The dashboard asks for it only when an
operator quarantines or restores an implementation and keeps it in session
storage for that browser tab.

`generate` validates the complete specification, asks a test-author agent for
one shared conformance suite, asks separate implementation agents for every
candidate, and runs the declared checks after each candidate. `check` runs the
project's declared conformance and build commands locally and
hashes the open specification. `publish` requires current passing evidence,
signs the release metadata, and points the catalog at a GitHub Release artifact.
`install` and `update` verify both its checksum and Ed25519 signature. The
server never runs a contributor's build.

The boundaries are ordinary directories, not Git submodules:

- `crates/polyform-cli`: developer and end-user distribution tool
- `crates/polyform-runtime`: reusable application runtime client
- `backend`: hosted catalog, assignment, telemetry, and analysis API
- `dashboard`: hosted project/operator UI
- `schemas`: shared publishing contracts
- `deploy`: single-container shoestring server package
- `rust` + `specs`: open-source `zipdiv` example and specification

They can split into separate repositories later if ownership or release cadence
demands it. Initially, atomic changes and one issue tracker are much more useful.

## Use the ZIP CLI

```bash
cargo run --manifest-path rust/Cargo.toml -- list archive.zip
cargo run --manifest-path rust/Cargo.toml -- extract archive.zip output/
cargo run --manifest-path rust/Cargo.toml -- verify archive.zip
```

Without a server, the client uses a safe default composition. With
`--server`, `--release-id`, and `--installation-id`, it registers over HTTP,
uses the assigned composition, and reports execution metadata and failures.
The server URL is configurable and has no localhost assumption.

## Run components separately

```bash
./run_server.sh
./run_dashboard.sh
./test.sh
```

Useful component documentation:

- [Architecture and state rule](ARCHITECTURE.md)
- [Experiment interpretation](RESULTS.md)
- [ZIP contracts](specs/README.md)
- [Rust ZIP client/runtime](rust/README.md)
- [FastAPI backend](backend/README.md)
- [React dashboard](dashboard/README.md)
- [AI candidate generator](tools/README.md)

## Five components

1. **Programming framework.** Nine high-level Rust spec functions are runtime
   dispatched, with five accepted implementations per function (45 total and
   1,953,125 safe compositions). Only declared boundaries vary; private helpers
   do not. A single binary realizes the cross-product—no binary-per-composition
   explosion.
2. **Specification and tests.** TOML contracts define typed signatures,
   expected errors, behavioral requirements, and authority tests. Fifteen Rust
   tests cover every conforming variant plus whole-archive and malformed cases.
3. **AI generation.** `tools/generate_variants.py` supplies the selected
   contract and context to an agent adapter, compiles/tests the candidate, and
   admits only passing source while recording prompt/model/time/hash provenance.
4. **Distribution and analysis.** FastAPI + SQLite assign compositions, accept
   pseudonymous execution/telemetry reports, compute failure rates and relative
   risk, surface pairwise interactions, quarantine variants, and preserve exact
   historical-composition attribution across recomposition.
5. **Dashboard.** React/TypeScript makes diversity, blast radius, suspect
   localization, pair signals, quarantine, recomposition, and before/after
   health visible in one control room.

## Controlled faults and privacy

Normal release metadata excludes experiment variants. `demo.sh` opts in to two
narrow faults—long ZIP comments and valid deep extraction paths. Their ground
truth lives only in `rust/experiment/faulty_variants.json`; the analyzer never
loads it and works from assignments and outcomes alone.

Telemetry accepts categorical event labels, the active implementation, and a
bounded call history. Schemas forbid archive names, paths, bytes, and user file
contents. The prototype has no operator/client authentication and must not be
put directly on the public internet; `ARCHITECTURE.md` describes the additional
controls and SQLite-to-Postgres path needed for a future `omalled.com` service.

## Generate implementations

```bash
polyform generate --count 5
```

The installed Codex CLI is the default coding agent. Use `--function NAME` to
add candidates for one function, `--skip-test-generation` to reuse the existing
shared tests, or `--agent /path/to/agent` to use another agent program. Agents
must register their implementation in the application, and Polyform accepts a
candidate only after the project's shared checks pass.

## Scope and next steps

The supported ZIP subset intentionally excludes ZIP64, encryption, multi-disk
archives, and unusual compression methods. Statistical associations are
transparent diagnostics rather than causal proof. Production work includes
authentication/authorization, rate limiting, retention,
client credentials, sandboxed generation, confidence intervals or sparse
regularized models, pair-balanced assignment, and durable multi-worker storage.
