The substrate in five steps

Vela does not accept anonymous writes. Before a reviewer or an agent can land an event on a frontier, they bind an Ed25519 public key to an actor id with vela actor add. Every later event references that actor id and is signed by the matching private key. There is no "system" identity that edits findings without leaving a trace.

Register the reviewer

vela actor add projects/early-ad-biomarker-calibration \
  reviewer:will-blair \
  --pubkey "$(cat keys/public.key)"

The CLI invocation pattern is the one documented in docs/REVIEWER_QUICKSTART.md and reused across every project in this repo.

The actor registry that results

After registration, the registered actors live in the frontier's .vela/actors.json. A fresh clone can verify any signed event against this list without contacting an outside service.

// projects/early-ad-biomarker-calibration/.vela/actors.json
[
  {
    "id": "reviewer:will-blair",
    "public_key": "31e5e7caf7d463ec98ed69a20e189b38d308490cded047930568fab034a4add7",
    "algorithm": "ed25519",
    "created_at": "2026-05-08T22:54:04.448362+00:00"
  },
  {
    "id": "agent:vela-curation-bot-2026-05-09",
    "public_key": "45e84511df02649919e7819b3ad2dc2add1505fd2a9388e664bb4e01f2f912f6",
    "algorithm": "ed25519",
    "created_at": "2026-05-08T23:25:22.672139+00:00"
  }
]

A signed canonical event from this frontier

Once the actor is registered, every action lands as one canonical event in .vela/events/. Below is one real finding.reviewed event, written by agent:vela-curation-bot-2026-05-09, returning the verdict needs_revision on a draft finding.

// projects/early-ad-biomarker-calibration/.vela/events/vev_237dd104193b4e45.json
{
  "schema": "vela.event.v0.1",
  "id": "vev_237dd104193b4e45",
  "kind": "finding.reviewed",
  "target": { "type": "finding", "id": "vf_3f801642feaf736a" },
  "actor": {
    "id": "agent:vela-curation-bot-2026-05-09",
    "type": "human"
  },
  "timestamp": "2026-05-08T23:33:32.535396+00:00",
  "reason": "Span carries study design (n=1325, A+T+ vs A+T- vs A-T- comparison in CU individuals) but does not literally state the progression result direction. Assertion is supported by the paper as a whole but not by the attached span. Needs a results-section span before promotion to accepted.",
  "before_hash": "sha256:868b1d03f778d0bf00a4136828c44cdf8e56a41157b270dde5e1cd25eff3dc7b",
  "after_hash": "sha256:9fb4dfc23fc08e75e70ad447a2eda8d6f141fd916861b175de2489700c8eaeee",
  "payload": {
    "proposal_id": "vpr_d1ee9f4d3998c5f6",
    "status": "needs_revision"
  },
  "caveats": []
}

The before_hash and after_hash chain the event to the finding's canonical bytes. A fresh clone replays the chain and reaches the same materialized state, or the proof packet fails verification.

The Workbench is a localhost-only review surface that ships with the same binary. It reads the frontier the reviewer is looking at and surfaces every queue that needs attention: proposals waiting for a verdict, evidence atoms missing locators, findings missing spans, findings without a recorded review verdict, and federation conflicts. The headings below are quoted verbatim from the rendering code in crates/vela-protocol/src/workbench.rs; the public site does not render the inbox itself, but the markup is the same one a reviewer sees on their machine.

Inbox section headings (rendered code)

// crates/vela-protocol/src/workbench.rs
<h3>Throughput, last 7 days</h3>
<h3>Locator gaps</h3>
<h3>Span gaps</h3>
<h3>Entity gaps</h3>
<h3>Link gaps (findings without typed links)</h3>
<h3>Findings pending review</h3>
<h3>Federation conflicts</h3>

The "findings pending review" attribution

The reviewer is told, in the same panel, exactly what their click will produce. The text below is quoted from the inbox renderer.

Each promote submission lands as a signed canonical finding.review event under the configured reviewer id. No bulk affordance; one finding per submission.

The throughput dashboard

The same panel reports a 7-day throughput summary with applied-percent and median proposal-to-event latency, so the reviewer sees their own loop closing in real time. The rendering code lives at workbench.rs:3041.

A reviewer who agrees with a draft finding promotes it to accepted-core. The localhost Workbench has a paired form for this; on the public site we show only its source. The form posts to /review/promote on the local Workbench and emits one signed finding.review event.

Promote form fields (rendered code, localhost only)

// crates/vela-protocol/src/workbench.rs:3546
// (form action shown as text; not a live form on this page)
//   method: POST
//   action: /review/promote
//   fields:
//     finding_id    (hidden)
//     status        (select: accepted | contested | needs_revision | rejected)
//     reviewer      (text, defaults to configured reviewer id)
//     reason        (text, required: cite evidence span and calibration anchor)
//
// The same panel tells the reviewer:
//   "Submission lands as a signed canonical finding.review event
//    under the configured reviewer id. No silent edits; the event
//    is replayable from .vela/events/."

The accepted event the form produced

Below is the real finding.review event that landed when the curation bot accepted finding vf_8b47d4846c86bc8f on the early-AD biomarker calibration frontier. Note "status": "accepted" in the payload.

// projects/early-ad-biomarker-calibration/.vela/events/vev_85621cac7ca02583.json
{
  "schema": "vela.event.v0.1",
  "id": "vev_85621cac7ca02583",
  "kind": "finding.reviewed",
  "target": { "type": "finding", "id": "vf_8b47d4846c86bc8f" },
  "actor": {
    "id": "agent:vela-curation-bot-2026-05-09",
    "type": "human"
  },
  "timestamp": "2026-05-08T23:26:34.327816+00:00",
  "reason": "Evidence span verbatim backs the assertion. Centiloid working group standardization, 0 to 100 anchor convention (CL=0 young controls, CL=100 typical AD), and cross-tracer comparability are all in the abstract text. Methodological consensus paper, foundational reference.",
  "before_hash": "sha256:c30bc9bf0237a6dc23311d1f48fa024ec65e46547b69130b68fec296795d9f5d",
  "after_hash": "sha256:11244dc98f9be54fdc0b4e0b45c5162e6493d21687266433774bed8835d25a85",
  "payload": {
    "proposal_id": "vpr_1239df3e9393e02c",
    "status": "accepted"
  },
  "caveats": []
}

Promotion does not edit the original finding in place. It appends a verdict event whose after_hash is the new canonical state. Every prior verdict on this finding stays in the log, visible to anyone running step 4.

Any reader can replay the full history of a finding without permission, network access, or a running server. The event log is the audit trail; vela history is the reader. Below is the real output for the same finding, captured against the live repo.

Two events, one chain

The reviewed event in step 3 chains directly to the original assertion event. Compare the hashes:

vev_ca838e5dd2d80967  finding.asserted
  before_hash: sha256:null
  after_hash : sha256:c30bc9bf0237a6dc23311d1f48fa024ec65e46547b69130b68fec296795d9f5d

vev_85621cac7ca02583  finding.reviewed
  before_hash: sha256:c30bc9bf0237a6dc23311d1f48fa024ec65e46547b69130b68fec296795d9f5d
  after_hash : sha256:11244dc98f9be54fdc0b4e0b45c5162e6493d21687266433774bed8835d25a85

The reviewed event's before_hash is the asserted event's after_hash. A chain validator can confirm that exactly the named finding changed and exactly the named verdict was applied. No silent rewrites of the prior verdict are possible; the substrate appends new state and keeps every earlier state addressable.

vela history vf_8b47d4846c86bc8f

$ vela history projects/early-ad-biomarker-calibration vf_8b47d4846c86bc8f
vela history
  finding: vf_8b47d4846c86bc8f
  assertion: The Centiloid Project standardizes quantitative amyloid PET measures
  across tracers and centers by anchoring the scale to 0 (typical young controls)
  and 100 (typical Alzheimer disease), enabling cross-tracer and cross-cohort
  comparability of amyloid burden.
  confidence: 0.700
  review events:      1
  confidence updates: 0
  annotations:        0
  sources:            1
  evidence atoms:     1
  condition records:  0
  proposals:          1
  canonical events:   2
  - 2026-05-08T23:26:34Z vev_85621cac7ca02583 Evidence span verbatim backs the
    assertion. Centiloid working group standardization, 0 to 100 anchor convention
    (CL=0 young controls, CL=100 typical AD), and cross-tracer comparability are
    all in the abstract text. Methodological consensus paper, foundational reference.

The substrate records reviewed state. It never silently rewrites prior verdicts. The history reader is implemented at crates/vela-protocol/src/cli.rs:12641 and runs offline against the local event log.

A frontier is not a single hub. Once a peer is declared, every reconciliation between hubs travels as the same canonical event log. vela federation sync fetches a peer's signed manifest, diffs the resulting frontier against the local one, and appends one frontier.synced_with_peer event plus one frontier.conflict_detected event per disagreement. Sync never writes finding.reviewed or any other truth-changing kind; conflict resolution happens through subsequent reviewer-signed proposals on either side.

A real frontier.synced_with_peer event

The event below is from the anti-amyloid translation frontier (vfr_5076e7b3ff8e6b0f), recording a clean sync with peer:vela-hub-fly-dev: divergence count zero, both hubs converged on the same snapshot hash.

// projects/anti-amyloid-translation/.vela/events/vev_fbbfef016ee51a0b.json
{
  "schema": "vela.event.v0.1",
  "id": "vev_fbbfef016ee51a0b",
  "kind": "frontier.synced_with_peer",
  "target": {
    "type": "frontier_observation",
    "id": "vfr_5076e7b3ff8e6b0f"
  },
  "actor": { "id": "federation", "type": "system" },
  "timestamp": "2026-05-08T22:32:18.723072+00:00",
  "reason": "synced with peer peer:vela-hub-fly-dev",
  "before_hash": "sha256:null",
  "after_hash": "sha256:null",
  "payload": {
    "divergence_count": 0,
    "our_snapshot_hash": "a0211bd5cfeec1a4e652e68d5c8dac730c3791c9871a66abd164a7d193b8c90d",
    "peer_id": "peer:vela-hub-fly-dev",
    "peer_snapshot_hash": "b1ecc2128a5e813ddf191e867647fa0cf870bddbe69ede640644034729dccbd7"
  },
  "caveats": []
}

Every verdict on a frontier propagates to peer hubs through the same event log. The full federation doctrine, the peer registry, the manifest format, and the two-hub deployment shape live in docs/FEDERATION.md. A reproducible prototype against the production hub at https://vela-hub.fly.dev ships at scripts/federation-prototype.sh.