Glossary
// GUIDE · GLOSSARY
Words this project uses oddly.
Most terms here have ordinary meanings elsewhere; Vivarium pins them to specific roles. Lookup-friendly, alphabetised, cross-linked to the spec where the word is load-bearing.
// CORE
The handful you'll see in every other page.
- Bug reproduction
A repeatable sequence of inputs and an environment under which a previously-reported bug is observed to occur. Vivarium hosts these as runnable artefacts, not as written-up incident reports.
- Recipe
One reproduction. Lives in
src/layer{1,2,3}_*/<slug>/and ships as a runnable page (Layer 1) or pinned image instructions (Layers 2 / 3). One recipe targets one upstream bug. The catalogue is the set of all recipes this repository hosts.- Slug
Kebab-case identifier for a recipe — usually
<project>-<issue-number>(e.g.pandas-56679) when there is an upstream issue, or a descriptive phrase otherwise (e.g.bash-local-shadows-exit). Same shape as the directory name and theslugfield in Manifest v1.- Layer (1 / 2 / 3)
Which runtime a recipe lives on. Layer 1 = WASM in browser (instant). Layer 2 = Docker (full fidelity). Layer 3 = third way — record-replay, deterministic simulation, microVM. The choice is about which kind of bug the recipe can reproduce, not about which technology is fashionable. See Architecture for the long form.
- Verdict
The output of running a recipe — either
"reproduced"or"unreproduced". Reproduced means the upstream bug reproduces. Unreproduced means it does not. The values were originally"pass"/"fail"; renamed in Contract v1 Revision 3 (ADR-0029) so the literal name now matches its meaning. See verdict semantics.- Evidence
The supporting data behind a verdict — captured stdout / stderr, exit code, duration. Layer 1 publishes evidence inline on the page; Layer 2 / 3 ship it inside
verdict.json. Added in Contract v1 rev 2 (Phase 6 R.1) so the comparison page can show why, not just whether.
// SPEC SURFACES
The three things external repos and tools read.
- Contract (v1)
The runtime surface every reproduction page publishes — DOM attributes, JS globals, the meta tag, and the
verdict.jsonfile shape. The contract a Vivarium page signs by carrying<meta name="vivarium-contract" content="v1">. Locked at v1 since Phase 5; see Contract v1.- Manifest (v1)
The publication surface — a TOML file at
.vivarium/manifest.tomlthat an external repo ships to declare its own Vivarium-runnable reproduction. v1 stable since Phase 5; see Manifest v1. A manifest is what an external repo writes; a recipe (above) is what this repo hosts.- Recipes index (v1)
The machine-readable catalogue at
/api/recipes.json. Lists every recipe this repo hosts. Consumed by the MCP server, the gallery facet UI, and any external tool that wants to enumerate or filter recipes. Schema: recipes-index v1.
// WORKFLOWS
The verbs the spec pages keep referring to.
- Branch-fix
A candidate fix for the upstream bug, typically built from a contributor's branch (or AI agent's draft). The branch-fix verdict pipeline reproduces the recipe against the candidate fix; if the verdict flips from
reproducedtounreproduced, the fix is doing its job. See branch-fix pipeline.- AI-slop verification
The motivating workflow: a contributor (human or AI agent) produces a candidate fix, runs it against the recipe, and sees the comparison before opening a PR. "Did my AI's draft actually solve the bug, or does it just look right?" Phase 7 sub-stream B3 wires the existing branch-fix pipeline + comparison page + MCP tools into one walkthrough.
- Consumer workflow
The reusable GitHub Actions workflow at spec/consumer-workflow that an external repo invokes from its CI to capture a verdict for its own manifest's reproduction. Phase 5 sub-stream D.
// META
Words this project uses about itself.
- Phase
A coherent stretch of work measured in months-to-years, not sprints. Each phase has an opener ADR, a close ADR, and a roadmap entry. Closure is by partial-but-honest completion (precedent: ADR-0012), not by exhaustive feature list. See Roadmap.
- ADR (Architecture Decision Record)
Numbered design memo recording why a decision was made, what alternatives were considered, and what trade-offs were accepted. Lives privately under
_context/decisions/— load-bearing for AI agents and future maintainers; not part of the public docs surface.- Layer-uniform
A property describing surfaces that look the same regardless of which Layer (1 / 2 / 3) produced them. Contract v1 is layer-uniform: a verdict reads the same whether it came from Pyodide, Docker, or rr replay.
Found a term in the docs that isn't here? Open an issue — glossary gaps are bugs in the onboarding surface, not stylistic preferences.