<p align="center">
<img src="assets/brand/vela-logo-wordmark.svg" alt="Vela" height="44">
</p>
<p align="center">
<em>Version control for scientific state.</em>
</p>
<p align="center">
<a href="https://github.com/vela-science/vela/actions/workflows/ci.yml"><img src="https://github.com/vela-science/vela/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://github.com/vela-science/vela/actions/workflows/conformance.yml"><img src="https://github.com/vela-science/vela/actions/workflows/conformance.yml/badge.svg" alt="Conformance"></a>
<a href="https://crates.io/crates/vela-cli"><img src="https://img.shields.io/crates/v/vela-cli?label=crates.io%20%C2%B7%20vela-cli" alt="crates.io"></a>
<a href="https://pypi.org/project/vela-state/"><img src="https://img.shields.io/pypi/v/vela-state?label=PyPI%20%C2%B7%20vela-state" alt="PyPI"></a>
<a href="https://github.com/vela-science/vela/blob/main/LICENSE-APACHE"><img src="https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue.svg" alt="License"></a>
<a href="https://vela-site.fly.dev"><img src="https://img.shields.io/badge/site-vela--site.fly.dev-C9A227" alt="Site"></a>
<a href="https://github.com/vela-science/vela/releases"><img src="https://img.shields.io/github/v/release/vela-science/vela?display_name=tag" alt="Release"></a>
</p>
---
Vela turns papers, agent artifacts, hypotheses, and lab outputs into
reviewable scientific state transitions. One paper becomes one signed,
replayable canonical event under a reviewer's identity. The current state
of a frontier is the deterministic replay of its event log.
## The demo
```bash
vela init demo --name "BBB pericyte loss in early Alzheimer's"
vela ingest examples/paper-folder/papers/focused-ultrasound.pdf --frontier demo
vela propose demo <vf_id> --status accepted --reviewer reviewer:you --reason "..." --apply
vela diff <vpr_id> --frontier demo
vela accept demo <vpr_id> --reviewer reviewer:you --reason "applied"
vela serve --path demo
```
`vela diff <vpr_id>` shows the proposal-vs-frontier delta. The accepted
events on the early-AD reference frontier weld byte-for-byte across the
chain. From `examples/early-ad/.vela/events/`:
```
asserted vev_b4908222150d4693
before_hash: sha256:0000…
after_hash: sha256:9f6a…
reviewed vev_8cb9b3daa9db5064 needs_revision
before_hash: sha256:9f6a…
after_hash: sha256:9f6a… (no state change)
span_repaired vev_3790dc7f05c5f13a
before_hash: sha256:9f6a…
after_hash: sha256:decf…
reviewed vev_50ecd1186170042f accepted
before_hash: sha256:decf…
after_hash: sha256:decf… (status only)
```
The `before_hash` of each event equals the `after_hash` of the previous
event applied to that finding. Replay is deterministic. Verify it yourself:
```bash
vela lineage demo vf_8f2d8f546976dcb3
vela integrity demo --json
```
A *finding bundle* is the primary state object: an assertion with its
evidence, conditions, entities, confidence, and provenance. Findings live
inside a *frontier*, which is a bounded, reviewable state over one
scientific question. Corrections enter as *proposals*. Reviewers accept
or reject; acceptance writes a signed canonical event. A *proof packet*
seals the current state so another party can re-verify it offline.
For the full walkthrough, see [`docs/EVENT_LOG.md`](docs/EVENT_LOG.md).
## Install
The Vela CLI ships as the `vela-cli` crate (binary name `vela`).
The Python client ships as `vela-state` on PyPI. Both halves
move together on the same release tag.
```bash
# Rust CLI (the writing surface).
cargo install vela-cli
# Python client (the replay + verify mirror).
pip install vela-state
vela --help
python3 -c "from vela_loader import load_frontier_repo; print('ok')"
```
The `vela` package name on crates.io and PyPI is taken by
unrelated projects (a Lua game framework and a Gemini server,
respectively); `vela-cli` and `vela-state` are the agreed
fallbacks. The binary stays `vela`. See
`docs/CRATES_IO_RELEASE.md` and `docs/PYPI_RELEASE.md` for the
publish ritual.
Build from source:
```bash
cargo build --release --bin vela
PATH="$PWD/target/release:$PATH"
vela --help
```
Tagged releases publish prebuilt `vela-macos-aarch64`,
`vela-macos-x86_64`, and `vela-linux-x86_64` binaries with
SHA-256 checksums on
[GitHub Releases](https://github.com/vela-science/vela/releases).
## Why this matters
Borrowed Light names the missing layer: science preserves artifacts better
than it preserves the current state of a question. AI makes papers, reviews,
artifacts, and experiment plans cheaper to produce, but those outputs do not
compound unless someone can inspect what changed.
Vela's release proof is the smallest concrete version of that layer:
```text
scientific activity
-> proposed frontier change
-> reviewer decision
-> canonical event
-> replayable state
-> proof packet
```
That is the first demo to understand. The artifact does not become truth. It
becomes a proposed change. Accepted events update the frontier; rejected
proposals remain visible as part of the field's memory.
## Release asset pack
The release asset pack centers the focused anti-amyloid translation frontier:
`anti-amyloid-translation.json`, the sealed
`anti-amyloid-translation-proof-packet.tar.gz`, decision brief, trial summary,
source verification, source-ingest plan, check report, and `SHA256SUMS`.
`bbb-alzheimer.json` remains in the pack as a compact protocol example.
The optional agent-inbox path (`vela scout`, `compile-notes`, etc.) shells out
to the [`claude`](https://docs.anthropic.com/claude/docs/claude-code) CLI with a
strict JSON schema. It reuses your local CLI session and does not require an
`ANTHROPIC_API_KEY` for that path.
```bash
cp examples/paper-folder/expected/frontier.json /tmp/frontier.json
vela check /tmp/frontier.json --strict --json
vela normalize /tmp/frontier.json --out /tmp/frontier.normalized.json
FINDING_ID=$(jq -r '.findings[0].id' /tmp/frontier.json)
vela review /tmp/frontier.normalized.json "$FINDING_ID" \
--status contested --reason "Mouse-only evidence" \
--reviewer reviewer:demo --apply
vela history /tmp/frontier.normalized.json "$FINDING_ID"
vela proof /tmp/frontier.normalized.json --out /tmp/proof-packet
vela serve /tmp/frontier.normalized.json --workbench --http 3848
```
For the agent-inbox loop — Literature Scout, Notes Compiler, Code Analyst,
Datasets, Reviewer, Contradiction Finder, Experiment Planner — see [Agent
Inbox](#agent-inbox) below.
Vela does not claim to be a lab runtime, federation network, autonomous agent
loop, desktop app, or complete science operating environment. Those remain roadmap
or thesis items. v0 proves state, not extraction: scientific work can become
inspectable, correctable, replayable frontier state.
A public hub at <https://vela-hub.fly.dev> serves signed frontier state
over HTTPS. Anyone with an Ed25519 key can publish their own `vfr_id`. The
signature is the bind, not access control. See [docs/HUB.md](docs/HUB.md)
and [docs/PUBLISHING.md](docs/PUBLISHING.md) for the end-to-end first-publish
walkthrough.
## Publish your own frontier
The minimum-viable path from "I have a bounded scientific question" to "my
signed frontier is on the public hub":
```bash
# 1. Scaffold a fresh frontier file (passes `check --strict` immediately)
vela frontier new ./frontier.json --name "Your bounded question"
# 2. Add findings (the CLI rejects schema-invalid types up front)
vela finding add ./frontier.json \
--assertion "Your one-sentence claim, scoped narrowly" \
--type therapeutic --evidence-type experimental \
--source "Author et al., 2024" --source-type published_paper \
--author "reviewer:you" --confidence 0.5 --apply
# 3. (Optional) compose with another hub frontier — declare the dep,
# then add a typed cross-frontier link
vela frontier add-dep ./frontier.json vfr_<hex> \
--locator https://… --snapshot <sha256>
vela link add ./frontier.json \
--from vf_<your> --to vf_<remote>@vfr_<remote> --type extends
# 4. Sign and register your publisher identity
vela sign generate-keypair --out keys
vela actor add ./frontier.json reviewer:you --pubkey "$(cat keys/public.key)"
# 5. Publish to the public hub (or your own)
vela registry publish ./frontier.json \
--owner reviewer:you --key keys/private.key \
--to https://vela-hub.fly.dev
```
The hub verifies the signed manifest, decomposes the frontier into
event/projection tables, and serves promoted frontier state. A compromised
hub can withhold but cannot fabricate because clients verify locally on read.
## Agent inbox
The agent layer lives in `vela-scientist`. Each agent reads the researcher's
local material, calls `claude -p` with a strict JSON schema, and emits
`StateProposal`s into the frontier — never canonical findings. Humans review;
the CLI signs. Doctrine: **agents propose, humans review, the CLI signs.**
```bash
# Ingestion — point each agent at the corresponding artifact
vela scout workspace/papers --frontier ./frontier.json
vela compile-notes workspace/notes --frontier ./frontier.json
vela compile-code workspace/code --frontier ./frontier.json
vela compile-data workspace/data --frontier ./frontier.json
# Review layer — runs after pending proposals exist
vela review-pending --frontier ./frontier.json # scores each proposal
vela find-tensions --frontier ./frontier.json # cross-finding pairs
vela plan-experiments --frontier ./frontier.json # for open questions
# Open the local Workbench to accept/reject through the UI
vela serve ./frontier.json --workbench --http 3848
open "http://localhost:4321/frontiers/view?api=http://localhost:3848"
# Sign the staged accepts/rejects
vela queue sign --actor reviewer:you --key ./keys/private.key --yes-to-all
```
Each agent run is tagged with an `AgentRun` (model, run id, started_at) so
proposals are auditable by source. Cap per-call cost with `--max-budget-usd`
(default 0.20).
## What it does
The substrate's current scope: 7 reviewer write surfaces, 8 canonical event
kinds covering the kernel primitives, three live frontiers, federation
push-resolution between hubs, and public proof verification rendered through
the `ProofBadge` component on every published frontier page.
- Bootstrap candidate frontier state from local corpora.
- Check frontier state before use as proof or agent context.
- Correct state through proposal-first reviews, caveats, revisions, rejections,
finding additions, and retractions.
- Deposit **NegativeResults** (`vnr_*`, v0.49) — registered-trial nulls with
power and effect-size bounds, or exploratory wet-lab dead ends with the
(reagent, condition, observation) tuple.
- Open **Trajectories** (`vtr_*`, v0.50) — the search path that produced (or
did not produce) a finding, append-only steps for hypothesis / tried /
ruled_out / observed / refined.
- Reclassify into **access tiers** (v0.51) — public / restricted / classified —
with read-side gating in `vela serve` for dual-use deposits.
- Inspect findings with source, evidence, condition, confidence, provenance,
links, proposals, and canonical event history.
- Surface candidate gaps, bridges, tensions, and review queues as derived
signals.
- Export proof packets and serve the same state over MCP/HTTP.
Candidate gaps, bridges, tensions, observer rerankings, and PubMed prior-art
checks are review surfaces, not scientific conclusions.
## Writing surfaces
The Workbench binds to `127.0.0.1` and exposes seven reviewer write routes.
Public hubs and the Astro site stay read-only by design.
- `/review/inbox` lists pending repair targets and conflicts (index, not a write).
- `/review/locator-repair/{atom_id}` attaches a missing locator to one evidence
atom and clears the matching caveat.
- `/review/span-repair/{finding_id}` appends a `{section, text}` span to a
finding's evidence after a re-fetch from the source.
- `/review/entity-resolve/{finding_id}` sets the canonical id on a named
entity and clears its `needs_review` flag.
- `/review/promote/{finding_id}` promotes a candidate finding into accepted
core under the configured reviewer identity.
- `/review/conflict-resolve/{conflict_event_id}` records the reviewer's
verdict on a previously detected federation conflict.
- `/review/replication-add/{finding_id}` deposits a `Replication` record
(replicated / failed / partial / inconclusive).
- `/review/prediction-add/{finding_id}` deposits a falsifiable `Prediction`
with deadline, criterion, and prior belief.
## Public surfaces
The site at <https://vela-site.fly.dev> is the read-only public face.
- `/` mission and substrate overview.
- `/onboarding` guided first-frontier walkthrough.
- `/mission` long-form positioning.
- `/decisions` accepted reviewer verdicts across the live frontiers.
- `/impact` change records that moved the field's working memory.
- `/conformance` cross-implementation reducer agreement and gate status.
- `/frontiers/<slug>` per-frontier reader view with the `ProofBadge`
component verifying the latest sealed packet.
- `/sitemap.xml` machine-readable index of the public surface.
## Quick start
Inspect the focused release frontier:
```bash
cargo build --release --bin vela
./target/release/vela stats projects/anti-amyloid-translation
./target/release/vela decision-brief projects/anti-amyloid-translation --json \
| jq '.projection.rows | length'
./target/release/vela search "lecanemab CDR-SB ARIA APOE4" \
--source projects/anti-amyloid-translation --limit 5
./target/release/vela proof projects/anti-amyloid-translation \
--out /tmp/anti-amyloid-proof
./target/release/vela packet validate /tmp/anti-amyloid-proof
```
Package the release assets locally:
```bash
./scripts/package-release-assets.sh /tmp/vela-release-assets
jq '.canonical_frontier, .canonical_proof_packet' \
/tmp/vela-release-assets/RELEASE_MANIFEST.json
```
Run the small paper-folder workflow:
```bash
cargo build --release --bin vela
cp examples/paper-folder/expected/frontier.json /tmp/frontier.json
./target/release/vela check /tmp/frontier.json --strict --json
./target/release/vela normalize /tmp/frontier.json --out /tmp/frontier.normalized.json
FINDING_ID=$(jq -r '.findings[0].id' /tmp/frontier.json)
./target/release/vela review /tmp/frontier.normalized.json "$FINDING_ID" --status contested --reason "Fixture review" --reviewer reviewer:demo --apply
./target/release/vela history /tmp/frontier.normalized.json "$FINDING_ID"
./target/release/vela proof /tmp/frontier.normalized.json --out /tmp/proof-packet
./target/release/vela serve /tmp/frontier.normalized.json --check-tools
```
The paper-folder fixture keeps `compile-report.json`, `quality-table.json`, and
`frontier-quality.md` under `examples/paper-folder/expected/`. Those files are
review aids, not trust anchors. Reviewed and accepted state transitions are the
boundary for frontier state.
For the checked-in BBB/Alzheimer protocol example:
```bash
vela stats frontiers/bbb-alzheimer.json
vela search "LRP1 RAGE amyloid" --source frontiers/bbb-alzheimer.json
vela tensions frontiers/bbb-alzheimer.json --both-high
vela gaps rank frontiers/bbb-alzheimer.json --top 5
vela proof frontiers/bbb-alzheimer.json --out /tmp/vela-proof-packet
```
`frontiers/bbb-alzheimer.json` is the compact public BBB example. It is a
protocol demo for state, review, replay, and proof mechanics, not a scientific
authority on Alzheimer's BBB delivery. The broad Alzheimer/BBB reservoir is
`vfr_06cfcbe7c449d86a` on the hub and mirrored in
`projects/bbb-flagship/`. That project directory is a portable frontier working
copy with thousands of content-addressed objects. It is intentionally JSON-heavy
because the protocol store is meant to be diffable and reproducible; the hub,
Workbench, CLI summaries, proof packets, and curation notes are the reader
surfaces.
`vela proof` exports and validates a packet without modifying the input
frontier. Use `--record-proof-state` only for local bookkeeping when you want to
save the latest packet state back into that frontier.
For the kernel primitive demo touching every v0 state transition, run:
```bash
./demo/v0-state-proof-demo.sh
```
It works on a temporary copy of the BBB frontier and walks each primitive
end-to-end:
1. Finding review (Correction)
2. Confidence revision (ConfidenceUpdate)
3. NegativeResult deposit — registered_trial null with power + CI bounds
4. NegativeResult deposit — exploratory wet-lab dead end
5. Trajectory open + three steps (hypothesis → tried → ruled_out)
6. Access-tier reclassification (Restricted)
7. Replayable history surfaces every transition
8. Proof packet goes stale, then refreshes for the corrected state
Each primitive prints its `vev_*` event id so you can read the canonical event
log with `vela history`. Open the Workbench at the end to see findings, nulls,
trajectories, audit, and tiers rendered side-by-side.
## Core concepts
The eight kernel primitives (the Constellations essay's primitive list, all
landed by v0.50):
- **Frontier:** a bounded, reviewable frontier state over a scientific
question.
- **Finding bundle** (`vf_*`): the primary state object; an assertion with
evidence, conditions, entities, confidence, provenance, and links.
- **Evidence:** the exact span, row, table, measurement, run, metric, or weak
provenance unit bearing on a finding.
- **Source:** the artifact a finding came from, such as a paper, dataset, note,
agent trace, benchmark output, notebook entry, or log.
- **Condition (Scope):** the boundary where a claim stops — species, assay,
comparator, exposure/efficacy scope, endpoint, translation scope.
- **Confidence (ConfidenceUpdate):** bounded frontier epistemic support for
the finding as currently represented, not truth probability or extraction
accuracy. Mutated through `finding.confidence_revised` events.
- **NegativeResult** (`vnr_*`, v0.49): registered-trial null with power and
effect-size bounds, OR exploratory wet-lab dead end with the (reagent,
condition, observation) tuple. The shape that lets an *informative null*
(adequate power, CI excluding MCID) round-trip distinctly from an
*uninformative* one through downstream confidence math.
- **Trajectory** (`vtr_*`, v0.50): the search path that produced (or did not
produce) a finding. Append-only steps with kinds
`hypothesis | tried | ruled_out | observed | refined` so the next agent
doesn't re-derive what the last one already ruled out.
- **Correction (typed link / dependency edge):** review verdicts (accepted /
contested / needs_revision / rejected), caveats, retractions, and
dependency-cascade events.
Plus the v0.51 dual-use channel:
- **Access tier:** `public` (default), `restricted` (IBC review level),
`classified` (DURC + frontier-lab capability gates). Read-side gating in
`vela serve` against the requesting actor's `access_clearance`.
And the substrate plumbing:
- **Canonical event:** the authoritative state-transition record. Three
reducer implementations (Rust, Python, TypeScript) agree byte-for-byte
on per-kind mutation rules across findings, negative_results, and
trajectories (v0.53).
- **Proposal:** the public write boundary for truth-changing corrections.
v0.52 extends to NegativeResult and Trajectory through the same
agent-inbox-review-gated flow as findings.
- **Proof packet:** a portable review artifact with packet manifest, source
and evidence tables, signals, event/replay data, proposals, and proof
trace.
See [Core Doctrine](docs/CORE_DOCTRINE.md) for the claim boundary and
[Protocol §6 + §13](docs/PROTOCOL.md) for the event lifecycle and access
tier model.
## Proof target
The v0 proof claim is narrow:
> A replayable frontier is a better working memory for AI-accelerated science
> than papers, logs, notebooks, and private agent memory alone.
The public demo path is the focused anti-amyloid translation frontier. It must
show that a serious viewer can move from bounded answer, to finding bundles, to
trial records and artifacts, to caveats, gaps, tensions, and a correction path.
The BBB proof path remains the compact protocol example for replay and proof
freshness. See [Proof](docs/PROOF.md) and
[Holy shit demo](docs/HOLY-SHIT-DEMO.md).
## Made with Vela
Two reference frontiers are bundled in this repo. Both run end-to-end
out of a fresh `git clone`:
- [`examples/early-ad/`](examples/early-ad/) — early Alzheimer's
biomarker calibration. 9 findings, 29 events. The README's
six-command demo runs against this frontier.
- [`examples/sidon-sets/`](examples/sidon-sets/) — additive
combinatorics, Sidon sets, and N(h, k) bounds. 3 findings,
5 events, 1 Lean stub artifact. Built as a concrete answer
to Timothy Gowers's 2026-05-08 blog post on AI-produced
research; see [docs/AI_ATTRIBUTION.md](docs/AI_ATTRIBUTION.md).
## Documentation
- [Core Doctrine](docs/CORE_DOCTRINE.md) - canonical v0 claim boundary
- [Protocol](docs/PROTOCOL.md) - normative state and event semantics
- [Event Log](docs/EVENT_LOG.md) - guided walkthrough of the canonical event log with real excerpts and integrity-verification commands
- [Carina](docs/CARINA.md) - kernel primitive spec; 14 hand-authored JSON Schemas at `examples/carina-kernel/schemas/`
- [Relay](docs/RELAY.md) - the four adapter shapes (paper, artifact, hypothesis, review) that turn outside activity into proposals
- [AI attribution](docs/AI_ATTRIBUTION.md) - the agent-vs-human-reviewer doctrine, citing Gowers (2026-05-08)
- [crates.io release](docs/CRATES_IO_RELEASE.md) and [PyPI release](docs/PYPI_RELEASE.md) - publish ritual
- [Publishing](docs/PUBLISHING.md) - end-to-end first-publish to the public hub
- [CLI JSON](docs/CLI_JSON.md) - machine-readable command envelopes
- [Proof](docs/PROOF.md) - proof packet contract
- [Trace Format](docs/TRACE_FORMAT.md) - `proof-trace.json`
- [Benchmarks](docs/BENCHMARKS.md) and [VelaBench](docs/VELABENCH.md) - benchmark fixtures and the public agent leaderboard
- [Hub](docs/HUB.md) and [Registry](docs/REGISTRY.md) - signed manifest distribution
- [Workbench](docs/WORKBENCH.md) - read-only frontier viewer
- [MCP](docs/MCP.md) and [MCP Setup](docs/MCP_SETUP.md) - serving over Model Context Protocol
- [Python](docs/PYTHON.md) - Python bindings
- [Theory](docs/THEORY.md) and [Math](docs/MATH.md) - non-normative appendices
- [State Transition Spec](docs/STATE_TRANSITION_SPEC.md) - non-normative typed transition design bridge
- [Tiers](docs/TIERS.md) - actor trust tiers
- [Phase A Content Expansion](docs/PHASE_A_CONTENT_EXPANSION.md) - content runbook
- [Schema Mismatch Note](docs/SCHEMA_MISMATCH_AGENT_OUTPUTS.md) - validator allow-list rationale
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for the developer onboarding path:
repository layout, local setup, the substrate doctrine, the lockstep
checklist for adding a canonical event kind, and the pre-merge gates.
Scientific reviewers running a frontier should start at
[REVIEWER_QUICKSTART](docs/REVIEWER_QUICKSTART.md) instead.
## Status
- Rust workspace with the `vela` CLI and MCP/HTTP server in
`crates/vela-protocol`
- focused anti-amyloid translation frontier under
`projects/anti-amyloid-translation`
- compact checked-in BBB/Alzheimer protocol example under `frontiers/`
- local paper-folder compile path with quality reports
- public Workbench defaulting to the anti-amyloid decision console
- proof packets, replay checks, proposal records, and proof freshness
- dual-licensed Apache-2.0 OR MIT (see [LICENSE-APACHE](LICENSE-APACHE) /
[LICENSE-MIT](LICENSE-MIT))
## Product and design canon
Voice and product language live in [docs/PRODUCT.md](docs/PRODUCT.md).
Color, type, motion, and component rules live in [docs/DESIGN.md](docs/DESIGN.md).
Design tokens are in `web/styles/{tokens,workbench}.css`, used by every
Vela surface: the site, the hub, and the workbench. The Astro
project under `site/` is the live source for everything served from
<https://vela-site.fly.dev>. (`vela.science` belongs to a third party
since 2014; we don't own that domain.)
## Borrowed Light
[**Borrowed Light**](https://borrowedlight.org) is the long-form essay
this substrate was built for — *Constellations of Borrowed Light*, an
argument that science is missing the continuity layer that lets
knowledge, correction, and experimental state survive long enough to
compound. Borrowed Light is the philosophical layer; Vela is the
working substrate. They cross-link because they're the same project
served to different audiences.