Vela is the protocol that moves scientific activity into state inside the Constellate ecosystem (open infrastructure for cumulative science). 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 full ecosystem stack:
| Layer | What it is |
|---|---|
| Constellate | The umbrella ecosystem; open infrastructure for cumulative science. |
| Vela | The protocol that moves activity into state. This repo. |
| Carina | The kernel of 17 primitive types and schemas. |
Atlas (vat_*) |
A living, versioned map of a scientific domain composed of one or more frontiers. |
Constellation (vco_*) |
A network of connected Atlases across domains. |
Frontier (vfr_*) |
The bounded, reviewable state over one scientific question. |
See docs/CONSTELLATE.md for the umbrella
doctrine and docs/MISSION_ATLAS.md
for how Atlases compose frontiers.
The demo
The fastest way to feel the substrate. Replace the assertion with your real claim if you have one:
That one command initializes a frontier, generates an Ed25519
keypair, registers the reviewer actor, and applies a first
finding under your identity. The next-steps banner points at
vela serve demo, vela ingest demo <paper.pdf>, and
vela log demo.
For the full six-step walkthrough showing each transition:
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:
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.
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.
# Rust CLI (the writing surface).
# Python client (the replay + verify mirror).
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.
Path note. Some Python distributions ship a homonym vela
script that shadows the cargo-installed binary if ~/.cargo/bin
is not first in your PATH. If vela runs but errors out with
a Python ImportError, invoke the cargo binary directly:
~/.cargo/bin/vela --help. Or fix the precedence:
export PATH="$HOME/.cargo/bin:$PATH".
Build from source:
PATH="/target/release:"
Tagged releases publish prebuilt vela-macos-aarch64,
vela-macos-x86_64, and vela-linux-x86_64 binaries with
SHA-256 checksums on
GitHub 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:
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 CLI with a
strict JSON schema. It reuses your local CLI session and does not require an
ANTHROPIC_API_KEY for that path.
FINDING_ID=
For the agent-inbox loop — Literature Scout, Notes Compiler, Code Analyst, Datasets, Reviewer, Contradiction Finder, Experiment Planner — see 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
and 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":
# 1. Scaffold a fresh frontier file (passes `check --strict` immediately)
# 2. Add findings (the CLI rejects schema-invalid types up front)
# 3. (Optional) compose with another hub frontier — declare the dep,
# then add a typed cross-frontier link
# 4. Sign and register your publisher identity
# 5. Publish to the public hub (or your own)
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
StateProposals into the frontier — never canonical findings. Humans review;
the CLI signs. Doctrine: agents propose, humans review, the CLI signs.
# Ingestion — point each agent at the corresponding artifact
# Review layer — runs after pending proposals exist
# Open the local Workbench to accept/reject through the UI
# Sign the staged accepts/rejects
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 servefor 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/inboxlists 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 itsneeds_reviewflag./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 aReplicationrecord (replicated / failed / partial / inconclusive)./review/prediction-add/{finding_id}deposits a falsifiablePredictionwith 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./onboardingguided first-frontier walkthrough./missionlong-form positioning./decisionsaccepted reviewer verdicts across the live frontiers./impactchange records that moved the field's working memory./conformancecross-implementation reducer agreement and gate status./frontiers/<slug>per-frontier reader view with theProofBadgecomponent verifying the latest sealed packet./sitemap.xmlmachine-readable index of the public surface.
Quick start
Inspect the focused release frontier:
|
|
Package the release assets locally:
Run the small paper-folder workflow:
FINDING_ID=
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:
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:
It works on a temporary copy of the BBB frontier and walks each primitive end-to-end:
- Finding review (Correction)
- Confidence revision (ConfidenceUpdate)
- NegativeResult deposit — registered_trial null with power + CI bounds
- NegativeResult deposit — exploratory wet-lab dead end
- Trajectory open + three steps (hypothesis → tried → ruled_out)
- Access-tier reclassification (Restricted)
- Replayable history surfaces every transition
- 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_revisedevents. - 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 kindshypothesis | tried | ruled_out | observed | refinedso 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 invela serveagainst the requesting actor'saccess_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 for the claim boundary and Protocol §6 + §13 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 and Holy shit demo.
Made with Vela
Six reference frontiers are bundled in this repo. All run end-to-end
out of a fresh git clone:
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/— additive combinatorics, Sidon sets, and N(h, k) bounds. 21 findings, 23 events, 1 Lean stub artifact. The 18 curriculum findings span Erdős-Turán 1941 through Bloom-Sisask 2020 (Behrend, Roth, Bourgain, Sanders, Szemerédi, Gowers, Plünnecke-Ruzsa, Freiman, Bohr neighborhoods, Croot-Lev-Pach, Ellenberg- Gijswijt). Three load-bearing findings (Erdős-Turán, Nathanson open problem, AI-drafted h-squared-dissociated improvement) carry the AI-attribution-doctrine demonstration. Built as a concrete answer to Timothy Gowers's 2026-05-08 blog post on AI-produced research; see docs/AI_ATTRIBUTION.md.examples/erdos-problems/— open Erdős problems test bed. Seed finding plus 16 agent-drafted proposals queued pending review (eight solved problems including Erdős-Ginzburg-Ziv 1961; eight open problems including Erdős-Straus, minimum overlap, distinct distances, Erdős-Szekeres). The EGZ n = 2 case has a machine-checked Lean proof atlean/Vela/EGZ.lean(Theorem 8 in the substrate bundle).examples/trial-evidence-packet/— synthetic phase 2 clinical-trial frontier. Seed finding plus 12 agent-drafted SYNTHETIC proposals across protocol, endpoints, safety, decisions, and substrate-internal categories. Aligned with the v0.6 CarinaTrialprimitive. Demonstrates that trial state machines fit Vela frontiers without new event kinds.examples/protein-design/— ML-driven structural biology test bed. Seed finding plus 13 agent-drafted proposals across method-validation (AlphaFold2 CASP14, ESMFold trade-off, RoseTTAFold All-Atom), failure modes (IDR, multimer heterogeneity, fold-switching), design challenges (RFdiffusion binders, miniprotein, hallucinated designs), and methodological bounds (MSA depth, training leakage, calibration). Demonstrates substrate breadth into ML-driven structural biology.examples/climate-attribution/— earth-science test bed. Seed finding plus 13 agent-drafted proposals across methodology foundations (FAR, CMIP6, ETCCDI), real attribution studies as evidence atoms (Pall 2011 UK floods, Otto / WWA heatwaves, Stott 2004 European heatwave), model limitations (internal variability, resolution, structural uncertainty), and methodological bounds (baseline sensitivity, compound events, detection-vs-attribution). Demonstrates substrate breadth into earth-science attribution under physical-model-bounded confidence.
Documentation
- Constellate - umbrella ecosystem doctrine; the verb framing, the hierarchy, the JSTOR disambiguation
- Mission: Atlas - Atlas as the higher-level construct above Vela's frontier primitive
- Core Doctrine - canonical v0 claim boundary
- Protocol - normative state and event semantics
- Event Log - guided walkthrough of the canonical event log with real excerpts and integrity-verification commands
- Carina - kernel primitive spec; 17 hand-authored JSON Schemas at
examples/carina-kernel/schemas/ - Relay - the four adapter shapes (paper, artifact, hypothesis, review) that turn outside activity into proposals
- AI attribution - the agent-vs-human-reviewer doctrine, citing Gowers (2026-05-08)
- crates.io release and PyPI release - publish ritual
- Publishing - end-to-end first-publish to the public hub
- CLI JSON - machine-readable command envelopes
- Proof - proof packet contract
- Trace Format -
proof-trace.json - Benchmarks and VelaBench - benchmark fixtures and the public agent leaderboard
- Hub and Registry - signed manifest distribution
- Workbench - read-only frontier viewer; live finding page + frontier-discord dashboard at https://vela-site.fly.dev/workbench/discord (point at a local
vela serve --http <port>with?api=http://localhost:<port>) - MCP and MCP Setup - serving over Model Context Protocol
- Python - Python bindings
- Theory - formal substrate core (16 sections, 8 machine-checked Lean theorems, counterexamples)
- Threat model - 17 numbered attack surfaces with status, defenses-by-primitive, deferred items
- Case study: review pressure - retrospective on 7 kernel bugs caught and fixed in v0.103 to v0.108
- Theory narrative and Math - non-normative companion notes
- State Transition Spec - non-normative typed transition design bridge
- Tiers - actor trust tiers
- Phase A Content Expansion - content runbook
- Schema Mismatch Note - validator allow-list rationale
Contributing
See 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 instead.
Status
- Rust workspace with the
velaCLI and MCP/HTTP server incrates/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-MIT)
Product and design canon
Voice and product language live in docs/PRODUCT.md.
Color, type, motion, and component rules live in 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 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.