vela-protocol 0.77.0

Core library for the Vela scientific knowledge protocol: replayable frontier state, signed canonical events, and proof packets.
Documentation

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

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:

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.

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).
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:

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.

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.

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 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)
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 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
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:

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.questions | length'
./target/release/vela trial-summary 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:

./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:

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:

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:

./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 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

Two reference frontiers are bundled in this repo. Both 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. 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.

Documentation

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 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-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.