capscorp 0.1.0__py3-none-any.whl

capscorp-0.1.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: capscorp
+Version: 0.1.0
+Summary: A terminal catalogue of reproducible, pre-registered research capsules
+Author-email: Lenz Pracher <lenz.pracher@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/lenzpracher/capsule-corp
+Project-URL: Repository, https://github.com/lenzpracher/capsule-corp
+Keywords: research,reproducibility,pre-registration,llm,tui
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: textual>=0.80
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: tomlkit>=0.13
+Requires-Dist: rich>=13
+Requires-Dist: platformdirs>=4
+Requires-Dist: mcp<3,>=2.2
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+    <img src="docs/assets/logo.svg" alt="capsule" width="440">
+  </picture>
+</p>
+
+# capsule-corp
+
+Packaging reproducible research questions.
+
+A terminal catalogue where each **capsule** is one empirically testable research question,
+packaged so that it stays reproducible and honest: the question, a frozen pre-registration,
+the code, a pinned environment, the outputs, and a verification record.
+
+Capsules are primarily written by an LLM. Every artifact is plain text and editable by hand.
+
+## Why pre-registration
+
+The failure mode of LLM-generated research is not bad code — it is code that quietly gets
+rewritten until it agrees with the conclusion. capsule-corp splits a capsule into two phases
+with a lock in between:
+
+1. **Design.** An agent writes the question, the hypothesis, and a set of _machine-checkable_
+   assertions that would falsify it — before any implementation exists.
+2. **Freeze.** `prereg.toml` is hashed into `.prereg.lock` and committed. From here the
+   predictions and the checks cannot change.
+3. **Implement, run, verify.** A second agent writes the code. The hash is re-verified before
+   and after; if the pre-registration moved, the run fails.
+
+Verification then has two independent layers: the deterministic checks (no LLM involved, so
+they are a real gate), and a **blinded** LLM judge that sees the question, the code, and the
+outputs — but not the write-up or any of the author's claims.
+
+A capsule whose hypothesis is refuted is a _successful_ capsule. That outcome is recorded,
+not treated as a failure.
+
+## Status
+
+Early but complete end to end: catalogue, agent loop, pre-registered verification, TUI,
+remote execution, and the MCP server are all implemented. The Slurm, SSH and Modal
+backends are unit-tested but have not yet been pointed at real infrastructure — see
+[`docs/roadmap.md`](docs/roadmap.md).
+
+## Install
+
+```bash
+curl -fsSL https://lenzpracher.github.io/capsule-corp/install.sh | sh
+```
+
+This puts the `capsule` command in `~/.local/bin` using [uv](https://docs.astral.sh/uv/),
+in its own isolated environment. No sudo. As with any installer of this shape, read
+[the script](install.sh) before piping it to a shell.
+
+Or, equivalently:
+
+```bash
+uv tool install capscorp
+```
+
+The command is `capsule`; the package is `capscorp` and the repository is
+`capsule-corp`. Only the first is something you type.
+
+To hack on capsule-corp itself, clone it and install editable so the command tracks
+your working copy:
+
+```bash
+git clone https://github.com/lenzpracher/capsule-corp
+cd capsule-corp
+uv tool install --editable .
+pixi install && pixi run postinstall   # for the test and lint tasks
+```
+
+Then run `capsule doctor`. Two external tools do the real work:
+[pi](https://github.com/earendil-works/pi) writes the capsules, and
+[pixi](https://pixi.sh) manages each capsule's environment.
+
+## Use
+
+```bash
+capsule doctor                   # check pi, pixi and the compute backends
+capsule init ~/research          # create a catalogue
+capsule mkdir optimization       # organise it however you like
+
+capsule new "Does LR warmup lower final loss?" --folder optimization
+capsule design 0001              # write the pre-registration; re-run to revise it
+capsule freeze 0001              # lock it; predictions can no longer change
+capsule implement 0001           # write the code
+capsule run 0001 --on slurm      # local (default), slurm, ssh, or modal
+capsule verify 0001              # checks, then the blinded judge
+
+capsule open 0001                # read the code in VS Code
+capsule export 0001              # a supplementary-materials bundle for a paper
+capsule tui                      # browse and drive it interactively
+capsule mcp                      # serve the catalogue to any MCP client
+capsule search warmup
+```
+
+Commands are listed in `capsule --help` in the order you run them, grouped by purpose,
+because that sequence is the method rather than an implementation detail.
+
+## Interface
+
+`capsule tui` opens a Textual interface over the same library the CLI uses: a folder
+tree, a detail pane showing the pre-registration and the verdict, a settings view, and
+`r`un / `v`erify / `d`esign / `f`reeze / `i`mplement keybinds. Press `e` for a built-in
+file browser and editor with syntax highlighting, or `o` to open the capsule in
+VS Code. Phases run in worker threads, so the interface stays responsive while a model
+is working.
+
+Long phases stream their progress as they run — each file the agent writes, each
+command it runs, a live token count — so you can tell a working agent from a hung one.
+
+## Attaching capsules to papers
+
+```bash
+capsule export 0001                     # supplementary-materials zip
+capsule export 0001 --format markdown   # an appendix
+capsule export 0001 --format html       # one self-contained file
+```
+
+Every export carries the pre-registration hash and the provenance, and discloses any
+revision the registration went through after being frozen. See
+[`docs/export.md`](docs/export.md).
+
+## Running elsewhere
+
+Capsules run locally by default, and unchanged on Slurm, any SSH host with Docker, or
+Modal. See [`docs/compute.md`](docs/compute.md).
+
+## Driving it from an MCP client
+
+`capsule mcp` serves the catalogue over the Model Context Protocol, including
+`capsule://<id>` resources so an agent can read prior capsules as context. See
+[`docs/mcp.md`](docs/mcp.md).
+
+## A capsule on disk
+
+```
+capsules/optimization/0001-lr-warmup/
+  capsule.toml         manifest: id, status, provenance
+  QUESTION.md          the research question
+  prereg.toml          hypothesis, predictions, checks
+  .prereg.lock         sha256 of prereg.toml at freeze time
+  AGENTS.md            instructions for the implementing agent
+  .pi/settings.json    per-capsule pinned agent config
+  pixi.toml            per-capsule environment
+  src/  run.py         the implementation
+  results/             results.json + figures/
+  runs/<timestamp>/    transcript and provenance for each run
+  verification.json    check results + judge verdict
+  REPORT.md            the write-up
+```
+
+Files are the source of truth. The SQLite index is a cache and can be rebuilt at any time
+with `capsule reindex`.
+
+## Agent independence
+
+The coding agent is [`pi`](https://github.com/earendil-works/pi), which is open source and
+provider-agnostic — configure it for Claude, GPT, Gemini, or a local model. capsule-corp does
+not pin a model; it inherits whatever `pi` is configured with and records what was actually
+used in each capsule's manifest. The runner sits behind a protocol, so other agents can be
+plugged in.
+
+## Documentation
+
+<https://lenzpracher.github.io/capsule-corp>
+
+## License
+
+MIT
+
+## Disclaimer
+
+capsule-corp is an independent, unaffiliated open-source project. It is not
+associated with, endorsed by, or sponsored by Bird Studio, Shueisha, Toei Animation,
+or Capsule Corporation Tokyo. "Dragon Ball" and "Capsule Corporation" are trademarks
+of their respective owners; the name and mark here are an affectionate nod, and no
+rights-holder artwork is used.

capscorp-0.1.0.dist-info/RECORD

@@ -0,0 +1,38 @@
+capscorp-0.1.0.dist-info/licenses/LICENSE,sha256=k5Wbwh0Aiw-enxdfTlAh_CUvtaxPuVecj2Vb21DrlUE,1068
+capsule_corp/__init__.py,sha256=YHlveizhQS4fEpxxhp1WQnQbaecn2LSFlNUNy__WxiY,677
+capsule_corp/checks.py,sha256=ooqj_KPEb-aEUV4yHUSOA4MBoZ1gqiK0NtUwWUhqpcY,10134
+capsule_corp/cli.py,sha256=v1ugG6k4JD9wkZfBb3jk7N9qefdr9BUfgbF_6vDKIYA,27642
+capsule_corp/doctor.py,sha256=VbOwSMra8MG_E_LkFLwwPCtdLbK3Wn_kpS06C_0mlnQ,4824
+capsule_corp/editor.py,sha256=P13CwRk9IXG7Ep4l_uF1lVuQjZjKUzUvaph_dESC50g,2273
+capsule_corp/export.py,sha256=X8su3HyFg39thCaPoyC08iy4ZzrAhw2nttYacnrQ-fM,17210
+capsule_corp/index.py,sha256=wjT9oa72CfvLuFQQnLgl9YRVjbwga8TQBBEbWm7tyXY,4150
+capsule_corp/mcp_server.py,sha256=amjR0V4IGVCmFAqoMKG0JjHVM2RYk5ZLaMAtn_vHTCI,10975
+capsule_corp/models.py,sha256=esSrxjtH2Iqq7yCGkt9FuTNUe4Frl7hR6nXkp6z1Ng8,7547
+capsule_corp/progress.py,sha256=6OZ4zZAWchHp6xq4H5m6p5ApLx2rTkqnKLLzdM6cvEY,4770
+capsule_corp/prompts.py,sha256=JbGSMn5-i5P8as-wbF_agOcyH0_dJom649nskwg0hGg,8403
+capsule_corp/settings.py,sha256=gH7mXZ22PDIwFKP5cp8HY8wIoARIs1m0ZNFv6n6qorU,5494
+capsule_corp/store.py,sha256=YLJAg59OSRuBO3IRqjs1cyTiYlXUn0_hMyW5ERzURJQ,17723
+capsule_corp/ui.py,sha256=MrvsxPPmTR4dHofjbLC9p01d8lBWv1xoCb7NJMHnvLU,1205
+capsule_corp/executors/__init__.py,sha256=cBVaveJsVTk1bF_4xL4U_4pl33SqXXjjN3lGdHtbbgM,1992
+capsule_corp/executors/base.py,sha256=MxCvN1b7Kfj-yUDQf6qdmskLp2QFkkXQXxxot08_EfQ,1728
+capsule_corp/executors/local.py,sha256=4_iBbS9moW2a4OrFhoIO07t23QKsxQH7GPSoE5mvzqM,3433
+capsule_corp/executors/modal_exec.py,sha256=UPe24ePkH1ptrIw-9Xu24Uf0FX4J78BstXyfoqwrmaE,5896
+capsule_corp/executors/slurm.py,sha256=RPNB-W4wUG-436QINf_5UsyOAnhIhylppQ47_wrS5Tk,6722
+capsule_corp/executors/ssh_docker.py,sha256=TOUIbOlZIUkpNW-3PAPnELWykBobz_X2V47C5bkU6BA,4203
+capsule_corp/executors/transport.py,sha256=dunFZdUYRMaNp2BfIIrUtJixyum7XIDdVGjVFKIqiJQ,2831
+capsule_corp/phases/__init__.py,sha256=XrKBbgS0W6Upzn8Ru4D6D_Z_9dGV91sS5aeDHLP5Cxo,283
+capsule_corp/phases/design.py,sha256=jl6I2sqQcTDsivr8VGFeMpTQQ-iKfhcWRs8B6YHGWMo,4735
+capsule_corp/phases/implement.py,sha256=uCp2Z93x6PjH3vwcQ-PwEntLa8YgsmIHmfr151dFqXY,2525
+capsule_corp/phases/scaffold.py,sha256=wl-kI3w1JISTgWMhToA-bHkINOszDuasLqqzyjDrWJ0,4980
+capsule_corp/phases/verify.py,sha256=vF-b5kXVSzQXCwYbthIsOaGyM8hinkfO81KnOjL5B6I,8038
+capsule_corp/runners/__init__.py,sha256=g6kfDw4I9ploWfHzRrByIngJ5GBAv7HjNp4Z5-El2xk,446
+capsule_corp/runners/base.py,sha256=TtREmBqW86PaX83PBoMQNPVYCf5oWc5lN_woLryyfu8,2179
+capsule_corp/runners/pi.py,sha256=mL4r4zu8cZdfkZgXOLaFNe5kOiHJ2xmgacjF1wWMxvY,9064
+capsule_corp/tui/__init__.py,sha256=JxCYwLUsaQSLP_eUkjY6avafR-fIxzloU4h-AKuJmTU,110
+capsule_corp/tui/app.py,sha256=oBBAakTH8ke0roRQOllgv_nXcB0uypU-Ezz0cebrhJk,15768
+capsule_corp/tui/code.py,sha256=XiUFuPPzAwTzC7UuRaJC-_h5mwfhTv3F7FN5Ll7ivaU,5989
+capscorp-0.1.0.dist-info/METADATA,sha256=EI6t4o-wqTA56jCKYNPNA_cbmQT0xnLzo9hB8Mawtnk,7858
+capscorp-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+capscorp-0.1.0.dist-info/entry_points.txt,sha256=cc6iHH8K3XJtx7_esaH3mZTiZ9EtHZrA228JP9DZTAA,50
+capscorp-0.1.0.dist-info/top_level.txt,sha256=S9c9aYt2WucEqW3oQtWEX93-7pSkWrTc97iQ6-Ol20g,13
+capscorp-0.1.0.dist-info/RECORD,,

capscorp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

capscorp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+capsule = capsule_corp.cli:main

capscorp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lenzpracher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

capscorp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+capsule_corp

capsule_corp/__init__.py

@@ -0,0 +1,14 @@
+"""capsule-corp: a terminal catalogue of reproducible, pre-registered research capsules."""
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    # The argument is the *distribution* name from pyproject.toml, not the import
+    # package (capsule_corp). Single source of truth is the [project] version; reading it
+    # back from installed metadata keeps a capsule's recorded provenance honest
+    # rather than reporting a constant that drifts from what was released.
+    __version__ = _version("capscorp")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

capsule_corp/checks.py

@@ -0,0 +1,281 @@
+"""Evaluation of pre-registered deterministic checks.
+
+These checks are the hard gate: they decide whether a capsule's registered predictions
+held, with no language model involved. That only works if the expressions are evaluated
+safely and predictably, so this module walks the AST itself rather than calling
+``eval``. There is no code path here that can import a module, call an arbitrary
+function, or reach a dunder attribute.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import operator
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from capsule_corp.models import Check, CheckKind, Prereg
+
+# Only these builtins are reachable from a check expression.
+ALLOWED_FUNCTIONS: dict[str, Callable[..., Any]] = {
+    "abs": abs,
+    "all": all,
+    "any": any,
+    "len": len,
+    "max": max,
+    "min": min,
+    "round": round,
+    "sum": sum,
+}
+
+_BIN_OPS: dict[type[ast.operator], Callable[[Any, Any], Any]] = {
+    ast.Add: operator.add,
+    ast.Sub: operator.sub,
+    ast.Mult: operator.mul,
+    ast.Div: operator.truediv,
+    ast.FloorDiv: operator.floordiv,
+    ast.Mod: operator.mod,
+    ast.Pow: operator.pow,
+}
+
+_COMPARE_OPS: dict[type[ast.cmpop], Callable[[Any, Any], Any]] = {
+    ast.Eq: operator.eq,
+    ast.NotEq: operator.ne,
+    ast.Lt: operator.lt,
+    ast.LtE: operator.le,
+    ast.Gt: operator.gt,
+    ast.GtE: operator.ge,
+    ast.In: lambda a, b: a in b,
+    ast.NotIn: lambda a, b: a not in b,
+}
+
+_UNARY_OPS: dict[type[ast.unaryop], Callable[[Any], Any]] = {
+    ast.USub: operator.neg,
+    ast.UAdd: operator.pos,
+    ast.Not: operator.not_,
+}
+
+RESULTS_NAME = "results"
+
+
+class CheckEvaluationError(Exception):
+    """A check could not be evaluated. Distinct from a check that evaluated to False."""
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """Outcome of one pre-registered check."""
+
+    id: str
+    kind: CheckKind
+    passed: bool
+    description: str = ""
+    detail: str = ""
+    error: str | None = None
+
+    @property
+    def errored(self) -> bool:
+        return self.error is not None
+
+
+def evaluate_expression(expression: str, results: Any) -> Any:
+    """Evaluate a restricted expression against loaded results."""
+    try:
+        tree = ast.parse(expression, mode="eval")
+    except SyntaxError as exc:
+        raise CheckEvaluationError(f"could not parse expression: {exc}") from exc
+    return _eval(tree.body, results)
+
+
+def _eval(node: ast.AST, results: Any) -> Any:
+    """Evaluate one AST node.
+
+    Dispatch is table-driven and closed: a node type with no handler is refused rather
+    than falling through to something permissive. That is the property the safety of
+    this module rests on, so it is worth keeping the table easy to read.
+    """
+    handler = _HANDLERS.get(type(node))
+    if handler is None:
+        raise CheckEvaluationError(f"{type(node).__name__} is not permitted in a check expression")
+    return handler(node, results)
+
+
+def _eval_constant(node: ast.Constant, _results: Any) -> Any:
+    return node.value
+
+
+def _eval_name(node: ast.Name, results: Any) -> Any:
+    if node.id == RESULTS_NAME:
+        return results
+    if node.id in ALLOWED_FUNCTIONS:
+        return ALLOWED_FUNCTIONS[node.id]
+    raise CheckEvaluationError(
+        f"unknown name {node.id!r}; a check may only reference '{RESULTS_NAME}' and "
+        f"{', '.join(sorted(ALLOWED_FUNCTIONS))}"
+    )
+
+
+def _eval_attribute(node: ast.Attribute, results: Any) -> Any:
+    if node.attr.startswith("_"):
+        raise CheckEvaluationError(f"attribute {node.attr!r} is not permitted")
+    return _lookup(_eval(node.value, results), node.attr)
+
+
+def _eval_subscript(node: ast.Subscript, results: Any) -> Any:
+    return _lookup(_eval(node.value, results), _eval(node.slice, results))
+
+
+def _eval_compare(node: ast.Compare, results: Any) -> Any:
+    """Evaluate a comparison, including chains such as ``10.2 < results.ratio < 12.4``."""
+    left = _eval(node.left, results)
+    for op, comparator in zip(node.ops, node.comparators, strict=True):
+        handler = _COMPARE_OPS.get(type(op))
+        if handler is None:
+            raise CheckEvaluationError(f"comparison {type(op).__name__} is not permitted")
+        right = _eval(comparator, results)
+        if not handler(left, right):
+            return False
+        left = right
+    return True
+
+
+def _eval_boolop(node: ast.BoolOp, results: Any) -> Any:
+    values = [_eval(value, results) for value in node.values]
+    return all(values) if isinstance(node.op, ast.And) else any(values)
+
+
+def _eval_unaryop(node: ast.UnaryOp, results: Any) -> Any:
+    handler = _UNARY_OPS.get(type(node.op))
+    if handler is None:
+        raise CheckEvaluationError(f"unary operator {type(node.op).__name__} is not permitted")
+    return handler(_eval(node.operand, results))
+
+
+def _eval_binop(node: ast.BinOp, results: Any) -> Any:
+    handler = _BIN_OPS.get(type(node.op))
+    if handler is None:
+        raise CheckEvaluationError(f"operator {type(node.op).__name__} is not permitted")
+    return handler(_eval(node.left, results), _eval(node.right, results))
+
+
+def _eval_list(node: ast.List, results: Any) -> Any:
+    return [_eval(element, results) for element in node.elts]
+
+
+def _eval_tuple(node: ast.Tuple, results: Any) -> Any:
+    return tuple(_eval(element, results) for element in node.elts)
+
+
+def _eval_dict(node: ast.Dict, results: Any) -> Any:
+    return {
+        _eval(key, results): _eval(value, results)
+        for key, value in zip(node.keys, node.values, strict=True)
+        if key is not None
+    }
+
+
+def _eval_call(node: ast.Call, results: Any) -> Any:
+    """Evaluate a call, which may only target one of the allowed builtins by name."""
+    if not isinstance(node.func, ast.Name):
+        raise CheckEvaluationError("only direct calls to the allowed helper functions are permitted")
+    if node.func.id not in ALLOWED_FUNCTIONS:
+        raise CheckEvaluationError(
+            f"function {node.func.id!r} is not permitted; allowed: {', '.join(sorted(ALLOWED_FUNCTIONS))}"
+        )
+    if node.keywords:
+        raise CheckEvaluationError("keyword arguments are not permitted in a check expression")
+    arguments = [_eval(argument, results) for argument in node.args]
+    try:
+        return ALLOWED_FUNCTIONS[node.func.id](*arguments)
+    except Exception as exc:
+        raise CheckEvaluationError(f"{node.func.id}() failed: {exc}") from exc
+
+
+# The complete set of node types a check expression may contain. Anything absent here
+# is rejected by _eval.
+_HANDLERS: dict[type[ast.AST], Callable[[Any, Any], Any]] = {
+    ast.Attribute: _eval_attribute,
+    ast.BinOp: _eval_binop,
+    ast.BoolOp: _eval_boolop,
+    ast.Call: _eval_call,
+    ast.Compare: _eval_compare,
+    ast.Constant: _eval_constant,
+    ast.Dict: _eval_dict,
+    ast.List: _eval_list,
+    ast.Name: _eval_name,
+    ast.Subscript: _eval_subscript,
+    ast.Tuple: _eval_tuple,
+    ast.UnaryOp: _eval_unaryop,
+}
+
+
+def _lookup(container: Any, key: Any) -> Any:
+    """Look a key up in loaded JSON, with an error a researcher can act on."""
+    if isinstance(container, dict):
+        if key not in container:
+            available = ", ".join(sorted(str(k) for k in container)) or "(empty)"
+            raise CheckEvaluationError(f"results.json has no key {key!r}; available keys: {available}")
+        return container[key]
+    if isinstance(container, (list, tuple)) and isinstance(key, int):
+        try:
+            return container[key]
+        except IndexError as exc:
+            raise CheckEvaluationError(f"index {key} out of range (length {len(container)})") from exc
+    raise CheckEvaluationError(f"cannot look up {key!r} in a value of type {type(container).__name__}")
+
+
+# --------------------------------------------------------------------------- checks
+
+
+def load_results(capsule_dir: Path) -> Any:
+    """Load ``results/results.json`` from a capsule."""
+    path = capsule_dir / "results" / "results.json"
+    if not path.is_file():
+        raise CheckEvaluationError("results/results.json does not exist; run the capsule first")
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise CheckEvaluationError(f"results/results.json is not valid JSON: {exc}") from exc
+
+
+def evaluate_check(check: Check, capsule_dir: Path, results: Any) -> CheckResult:
+    """Evaluate one check, converting any failure into a reportable result."""
+    common: dict[str, Any] = {"id": check.id, "kind": check.kind, "description": check.description}
+    try:
+        if check.kind is CheckKind.EXPR:
+            assert check.expr is not None
+            value = evaluate_expression(check.expr, results)
+            return CheckResult(**common, passed=bool(value), detail=f"{check.expr} → {value!r}")
+
+        if check.kind is CheckKind.ARTIFACT:
+            assert check.path is not None
+            artifact = capsule_dir / check.path
+            if not artifact.is_file():
+                return CheckResult(**common, passed=False, detail=f"{check.path} does not exist")
+            if artifact.stat().st_size == 0:
+                return CheckResult(**common, passed=False, detail=f"{check.path} is empty")
+            return CheckResult(**common, passed=True, detail=f"{check.path} ({artifact.stat().st_size} bytes)")
+
+        return CheckResult(
+            **common,
+            passed=False,
+            detail="",
+            error="script checks are not implemented yet",
+        )
+    except CheckEvaluationError as exc:
+        return CheckResult(**common, passed=False, detail="", error=str(exc))
+
+
+def evaluate_checks(prereg: Prereg, capsule_dir: Path) -> list[CheckResult]:
+    """Evaluate every registered check against the capsule's results."""
+    try:
+        results = load_results(capsule_dir)
+    except CheckEvaluationError as exc:
+        return [
+            CheckResult(id=c.id, kind=c.kind, description=c.description, passed=False, error=str(exc))
+            for c in prereg.checks
+        ]
+    return [evaluate_check(check, capsule_dir, results) for check in prereg.checks]