Specification
// SPEC · v1
Vivarium specification.
The reproduction-verdict contract — a small, stable surface that describes 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 · CURRENT SURFACES
Three surfaces, one contract.
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
.
// 03 · TOOLING
Reusable workflows that consume the contract.
Consumer workflow
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.
// 04 · SCOPE
What this spec is — and is not.
What this spec is for
- Reproduction pages (Layer 1, Layer 2, Layer 3) under
aletheia-works/vivariumdeclare conformance via the meta tag and the JSON envelope. - External tools (CI, IDE plugins, AI reviewers, third-party reproduction definitions) read the same surface to know whether a page reproduces today.
- Vivarium-compatible reproductions hosted outside this repo can declare conformance the same way.
What this spec is not
- It is not a full reproduction protocol — it covers the verdict surface, not how the reproduction itself is constructed (that is per-layer convention, in the layer READMEs).