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 the slug field 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.json file 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.toml that 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 reproduced to unreproduced, 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.

// NEXT

Read the architecture

Once the words make sense, the three-layer architecture is the next thing to internalise.

VIVARIUM IS PART OF ALETHEIA-WORKS · OPEN THE SOURCE ON GITHUB →