# Polyform architecture

Polyform is a research prototype for **combinatorially diversified software**.
It treats selected functions as stable behavioral contracts with several valid
implementations, assigns a different implementation vector to each client, and
uses population-level failures to localize suspect variants.

The ZIP application is intentionally real: it locates and parses the central
directory and local headers, decodes names, validates paths, supports stored and
DEFLATE payloads, checks CRC-32, lists entries, and writes extracted files.

## System map

```text
specs/zipdiv.toml ──► AI candidate tool ──► build + contract + regression gate
       │                                           │ accepted variants
       ▼                                           ▼
 Rust traits/types ◄──────────────────── runtime implementation registry
       │                                           ▲
       │ composition over HTTP                     │ variant metadata
       ▼                                           │
 FastAPI + SQLite ◄──── execution/failure events ── ZIP clients
       │
       ├──► assignment + quarantine policy
       ├──► relative-risk + pair-interaction analysis
       └──► React dashboard and population simulator
```

## 1. Programming framework

Only functions declared in `specs/zipdiv.toml` are swappable. Rust exposes a
stable registry and runtime dispatcher. A composition is simply a map from each
spec-function name to one registered implementation ID. The application carries
the selected map in an explicit context and routes calls through it. Private
helpers stay inside their implementation modules and do not become accidental
variation points.

The framework does not require purity. A variant may read an archive, write an
output file, or use a declared database. It must obey this state rule:

> An implementation must not retain hidden implementation-local persistent
> state on which another spec function or a future invocation depends.

State crossing a dispatch boundary belongs in arguments, results, explicit
shared context, or a named external resource. This constraint prevents an
apparently interchangeable function from silently depending on the history or
identity of a neighboring variant.

No binary is generated per combination. One binary contains the implementation
pool, and the server-issued composition selects entries at runtime. If function
`f1` has 3 choices, `f2` has 4, and `f3` has 2, the binary can realize 24
compositions without 24 builds.

## 2. Specifications and validation

`specs/zipdiv.toml` records signatures, input/output meaning, expected error
classes, behavioral requirements, and relevant test names. It points to the
PKWARE APPNOTE as the external ZIP authority while deliberately excluding
multi-disk ZIPs, encryption, ZIP64, and obscure extensions from the prototype.

Validation has four levels:

1. contract tests exercise one variant at a time;
2. interchangeability tests apply the same corpus to every non-fault-injection
   variant;
3. archive regression tests exercise complete stored/DEFLATE and malformed
   archives through composed dispatch;
4. end-to-end tests cross HTTP assignment, client execution, telemetry,
   analysis, quarantine, and replacement assignment.

Controlled fault variants are excluded from conformance acceptance and enabled
only for experiments. Their trigger conditions are ground truth for the
simulator, not features supplied to the analyzer.

## 3. AI implementation generation

`tools/generate_variants.py` reads any TOML application contract using the same
schema, selects a function, adds requested source/test context, and constructs a
prompt containing the interchangeability rule. The installed Codex CLI is the
default non-interactive agent; an injected command adapter can replace it, so
the orchestration also works with other local tools or hosted coding agents.

Each candidate receives a SHA-256 identity and provenance record containing the
agent, model, exact prompt, UTC time, invocation, source destination, and check
outcomes. Admission requires formatting, all-target build, targeted tests, and
the archive regression suite. Failed candidates are removed; their provenance
and diagnostics remain. Prompts omit earlier implementations and explicitly ask
for independent algorithm/control-flow choices to discourage cosmetic forks.

## 4. Distribution, telemetry, and analysis

FastAPI exposes versioned HTTP endpoints and persists state in SQLite. A release
declares its spec functions and implementation pool. Registration gives a
pseudonymous client ID a composition using either random selection or a balanced
strategy that chooses underrepresented variants and combinations. The protocol
uses a configurable base URL and has no localhost assumption.

Variant IDs are release-scoped in storage. They remain unchanged in composition
payloads, allowing a Rust implementation catalog to keep stable names across
application versions, while status changes carry a release ID to avoid
ambiguity. Startup includes an in-place migration from the prototype's original
globally keyed SQLite schema.

Clients report an execution outcome and hard observable events only: panic,
spec error, contract violation, timeout, integrity failure, or extraction
failure. Events identify the active implementation and contain a bounded recent
call history. The schema intentionally disallows filenames, extraction paths,
archive bytes, or file contents.

For every implementation, analysis reports exposure count, execution count,
failures, failure rate, baseline failure rate among alternatives, relative risk,
and an association score. Pairwise analysis compares clients/executions exposed
to a pair against the rest and applies minimum-support thresholds so a rare
coincidence is not presented as strong evidence. These are transparent
associations, not claims of causality; assignment strategy and sample size
remain visible.

Quarantine is an explicit operator action. A quarantined implementation is
excluded from future assignment. Every affected client receives a new
composition generation immediately, and the change is recorded with reason
`quarantine`. The dashboard divides executions into a baseline and one interval
after each quarantine, so health changes remain attributable to the intervention
sequence. An operator may restore a quarantined implementation to eligibility;
restoration does not force existing clients back onto it.

## 5. Dashboard

The React dashboard consumes one summary endpoint plus telemetry and mutation
endpoints. It presents population size, variation points, pool sizes,
theoretical composition count, actual distribution, variant associations,
pairwise signals, quarantine history, recompositions, and healthy execution rate
at every stage of the quarantine sequence.
The explanatory flow links diversity to localization rather than showing an
undifferentiated monitoring console.

Its backend URL is configured at build/run time. Local development uses Vite;
public hosting could serve the static build from any CDN or web server.

## Population experiment

The simulator is an HTTP client of the real service, not an in-process shortcut.
It creates releases and clients, requests assignments, submits workload
executions/events, asks the analysis endpoints for suspects, performs quarantine,
refreshes clients, and measures the next epoch. It can compare:

- homogeneous deployment, where one fault can reach the full population;
- random combinatorial assignment, which limits blast radius but may correlate
  choices in a small sample;
- balanced combinatorial assignment, which improves coverage and attribution.

Several real `zipdiv` processes can use the same endpoints and composition
format. The large virtual population exists to obtain useful statistics quickly.

## Public deployment path (not performed here)

The backend is already an ordinary ASGI application. A later deployment at
`omalled.com` would place it behind TLS and a reverse proxy, configure its public
base URL and CORS allow-list, store SQLite on durable single-instance storage or
migrate to Postgres for multiple workers, and serve the dashboard's static build.
Operational work would also add authentication for quarantine actions, rate
limits, retention, backups, structured logs, and secret management. None of
that infrastructure or domain configuration is part of this repository task.

## Security and limitations

This prototype demonstrates fault localization, not generic exploit detection.
Its deliberately bad variants contain bounded parsing/integrity mistakes and no
weaponized payload. Production use would need signed release manifests,
authenticated clients and operators, sandboxed generation, stronger privacy and
retention controls, resource isolation, robust update delivery, larger samples,
multiple-testing correction, and adversarial evaluation.
