Specification
// SPEC · v1
Vivarium specification.
The reproduction-verdict contract and the catalogue surfaces — a small, stable set of files describing whether the upstream bug reproduces against today's runtime.
// 01 · OVERVIEW
A versioned surface.
The Vivarium specification is the small set of files that lets a reproduction page declare itself, lets external tools read the verdict, and lets external repos publish their own reproductions without bespoke glue.
Reproduction pages declare conformance via
<meta name="vivarium-contract" content="v1">; external tools read the same surface to know whether a page reproduces today.
// 02 · WHAT TO READ
A reading map by audience.
The spec has different entry points for different readers. The cards below are role-based shortcuts — start where you actually need to be, skip the rest.
If you're writing a reproduction
The verdict.json wire shape, and how to declare a reproduction from your own repo. Contract v1 + Manifest v1.
02 · CONSUMEIf you're driving the catalogue
The machine-readable list of every recipe Vivarium hosts — used by AI agents and external catalogue tooling. Recipes index v1.
03 · CIIf you're verifying in CI
Reusable GitHub Actions workflows for verdict capture and the branch-fix verdict comparison pipeline.
// 03 · SURFACES
Three spec docs + two tooling workflows.
Contract v1 — verdict surface
Contract v1 defines what every reproduction page promises: a verdict DOM band, a structured result envelope on window.VIVARIUM_RESULT, and the same reproduced / unreproduced / pending semantics across all three layers. The Layer 2 / 3 verdict snapshot file follows verdict.schema.json (JSON Schema draft 2020-12).
Manifest v1 — publication surface
Manifest v1 is the TOML manifest that an external repo ships at .vivarium/manifest.toml to declare a Vivarium-runnable reproduction. Schema: manifest.schema.json.
Recipes index v1 — catalogue endpoint
Recipes index v1 is the machine-generated JSON listing of every reproduction this repository hosts. Consumed by the Vivarium MCP server and other programmatic catalogue tooling. Schema: recipes.schema.json.
Consumer workflow (reusable CI)
Consumer workflow — a reusable GitHub Actions workflow any repo can uses: to verify a Vivarium-hosted reproduction in their own CI.
Branch-fix verdict pipeline
Branch-fix verdict pipeline — a workflow_dispatch workflow that captures a verdict for a contributor-supplied branch-fix Docker image and bundles it alongside the deployed original for side-by-side comparison. The Layer 1 source-substitution variant (Path A) runs directly from /repro/compare.
// 04 · SCOPE
What this spec covers.
The spec covers the verdict surface — the meta tag and JSON envelope a reproduction page declares, the external repo's manifest.toml, the machine-readable catalogue, and the CI workflows that consume them. It does not specify how the reproduction itself is constructed; that is per-layer convention, documented in the layer READMEs. Pages that satisfy the verdict surface, hosted inside or outside Vivarium, are Vivarium-compatible.