# burn_p2p

Distributed Burn training over a policy-gated peer-to-peer network.

Start new integrations from the public facade crate, `burn_p2p`. The workspace
also contains companion crates for bootstrap/operator, browser, metrics,
artifact-publication, portal, auth, social, and typed UI surfaces, plus a few
low-level crates that are published only to keep the facade’s dependency graph
registry-safe. For `0.21.0-pre.2`, the crates.io publish set is intentionally
limited to the reusable library crates; the bootstrap/browser/UI/service
companions remain internal workspace crates.

## Installation

```toml
[dependencies]
burn_p2p = "=0.21.0-pre.2"
```

Current status:

- Verified baseline: see [docs/stabilization-baseline.md](docs/stabilization-baseline.md)
  for the exact commands and results recorded on 2026-04-03.
- Supporting docs:
  [docs/architecture.md](docs/architecture.md),
  [docs/operator-runbook.md](docs/operator-runbook.md),
  [docs/browser-runtime-guide.md](docs/browser-runtime-guide.md),
  [docs/auth-setup-guide.md](docs/auth-setup-guide.md),
  [docs/backend-capability-matrix.md](docs/backend-capability-matrix.md),
  [docs/benchmark-gates.md](docs/benchmark-gates.md),
  [docs/browser-device-validation.md](docs/browser-device-validation.md),
  [docs/dataloader-adapters.md](docs/dataloader-adapters.md),
  [docs/dataloader-tuning.md](docs/dataloader-tuning.md),
  [docs/degraded-network-thresholds.md](docs/degraded-network-thresholds.md),
  [docs/artifact-publication.md](docs/artifact-publication.md),
  [docs/multi-workload-guide.md](docs/multi-workload-guide.md),
  [docs/metrics-plane.md](docs/metrics-plane.md),
  [docs/portal-mobile-review.md](docs/portal-mobile-review.md),
  [docs/runtime-events.md](docs/runtime-events.md),
  [docs/leaderboard-scoring.md](docs/leaderboard-scoring.md), and
  [docs/status.md](docs/status.md).
- Downstream integration guide: see
  [docs/downstream-burn-guide.md](docs/downstream-burn-guide.md) for the
  recommended Burn embedding path and current caveats. For families with more
  than one workload, see
  [docs/multi-workload-guide.md](docs/multi-workload-guide.md).
- Canonical public model: `burn_p2p` is now centered on
  `P2pProjectFamily` + `P2pWorkload` with workload selection through
  `NodeBuilder::with_network(...)` and `NodeBuilder::for_workload(...)`.
  Legacy `P2pProject` / `RuntimeProject` layers still exist only under
  `burn_p2p::compat` as compatibility adapters, but they are no longer the
  forward path for docs or new examples.
- Compatibility model: networks are pinned to one project family and one
  release train, with a bounded set of approved target artifacts inside that
  train. Native and browser builds can coexist only when they share the same
  release train and exact experiment/revision/schema gates.
- Native runtime baseline: `spawn()` starts a real runtime; native peers can
  discover, admit, sync snapshots and artifacts, train leased windows, validate
  candidate heads, advance certified heads, and recover persisted state after
  restart. TCP and QUIC native control-plane paths are exercised in tests.
- Checkpoint/data baseline: the workspace has a real filesystem CAS, streamed
  chunking/materialization, pinning/GC, resumable artifact sync state, manifest-
  backed local/http shard fetch, lease-scoped shard caching, and per-experiment
  rebudgeting from observed throughput.
- Artifact publication baseline: the optional `burn_p2p_publish` crate now
  tracks run- and experiment-scoped `latest/*` plus
  `best_val/{eval_protocol_id}/*` aliases from canonical heads and canonical
  head-eval reports, persists export/publication/ticket state, mirrors artifacts
  to filesystem and S3-compatible targets, and exposes user-triggered
  export/download flows through bootstrap, browser, and portal surfaces.
  Signed-URL delivery is supported for configured object-store targets, and
  artifact head/run views now expose alias transition history through both JSON
  APIs and dedicated portal HTML pages. Bootstrap and the browser client now
  also expose live artifact-publication events for alias updates, export job
  lifecycle transitions, and prune actions. The current repo-local slice has no
  remaining acceptance gaps; any further work here is backend breadth and
  operator polish, not missing first-class publication/download primitives.
- Security/admission baseline: admission is certificate-based and strict.
  Static principal sessions, node certificates bound to peer IDs, trusted issuer
  validation, revocation epochs, trust-bundle rollout, and exact release-train /
  target-artifact checks are implemented and tested.
- Control-plane and topology baseline: the live runtime publishes and consumes
  directory, head, lease, reducer, merge-window, aggregate, and reduction
  announcements. The replicated-rendezvous DAG merge policy, deterministic
  reducer assignment, aggregate evidence persistence, and validator promotion
  flow are all live and covered by simulation tests.
- Browser baseline: the bootstrap daemon now serves browser-edge snapshot
  surfaces (`/portal/snapshot`, `/directory/signed`, `/leaderboard`,
  `/leaderboard/signed`, `/trust`, `/reenrollment`), and the new
  `burn_p2p_browser` crate provides typed browser portal/enrollment/storage and
  worker-state client logic. The browser worker can select authorized
  assignments, run local verify/train flows, queue and submit receipts to the
  browser edge, and the wasm compile matrix is now exercised explicitly through
  testkit. The browser path now also has a real-browser Chrome probe for
  role-threshold and shard/checkpoint budget validation. Transport-backed
  browser promotion and mixed-fleet execution are covered in testkit; broader
  real-device and multi-browser sampling remains follow-on calibration work.
- Bootstrap/operator baseline: `burn-p2p-bootstrap` exposes `/status`,
  `/metrics`, `/events`, `/diagnostics/bundle`, `/heads`, `/receipts`,
  `/reducers/load`, `/admin`, and the browser-edge routes above. It supports
  embedded runtime mode, trust-bundle export, authority rotation, provider-
  specific auth routes, RBAC-backed operator sessions, a signed edge
  capability manifest at `/capabilities` and
  `/.well-known/burn-p2p-capabilities`, optional portal/social/browser-edge
  route gating, and startup validation when config requests services that were
  not compiled in. The `x-admin-token` path is now an explicit dev-only
  fallback behind `allow_dev_admin_token`.
- Social modularization baseline: leaderboard aggregation and badge rollups now
  live in the optional `burn_p2p_social` crate. `burn_p2p_bootstrap` consumes
  it through its `social` feature and falls back to an empty snapshot when that
  feature is not compiled in.
- Auth modularization baseline: provider-specific auth connectors now live in
  dedicated optional crates. `burn_p2p_security` retains certificate/admission
  core, static auth, connector traits, and revocation/release policy logic,
  while `burn_p2p_auth_github`, `burn_p2p_auth_oidc`,
  `burn_p2p_auth_oauth`, and `burn_p2p_auth_external` provide the optional
  edge-facing identity connectors.
- Portal modularization baseline: the reference portal HTML/rendering surface
  now lives in the optional `burn_p2p_portal` crate. `burn_p2p_bootstrap`
  consumes it through its `portal` feature and minimal builds can exclude the
  portal implementation entirely.
- Metrics plane baseline: decentralized metrics are now live end to end in a
  first vertical slice. `burn_p2p_core` carries head-scoped schemas,
  `burn_p2p_experiment` registers revision-level evaluation policy,
  `burn_p2p` persists peer-window/cohort/head-eval records and publishes shared
  live metrics announcements onto the experiment metrics overlay, the optional
  `burn_p2p_metrics` crate now persists raw envelopes plus durable
  snapshot/ledger views, bootstrap serves `/metrics/...` endpoints and can
  recover them on restart while preferring the live control-plane event stream,
  the browser client now fetches and stores catchup/live metrics state during
  worker sync, and the reference portal renders separate
  quality/progress/dynamics/branch/health panels with explicit
  scope/trust labeling. Browser sync now prefers shared control-plane metrics
  announcements, the portal exposes an explicit reducer-disagreement panel, and
  the indexer derives `bytes_per_accepted_token` from persisted reducer byte
  estimates. Bootstrap now also serves explicit disagreement routes, and the
  browser client can query both candidate and disagreement drilldowns directly
  while supporting native multi-event live-metrics SSE reads plus a wasm-safe
  latest-frame fallback. The browser client can also repeatedly pump live
  metrics frames into worker state without replaying duplicate updates. The
  browser metrics path now also has a bounded control-plane polling loop in the
  shared browser-edge client that seeds catchup once and applies newly
  observed latest-event frames without requiring the SSE route. The portal rows
  now also carry operator hints and
  drilldown links for
  branch/disagreement review. The latest slice also adds dedicated peer-window
  distribution summaries and `/metrics/peer-windows` routes, so the portal can
  show local loss/latency/lag spreads grouped by base head instead of skipping
  that diagnostic view. Those rows now also drill into
  `/metrics/peer-windows/:experiment_id/:revision_id/:base_head_id`, so browser
  and operator clients can inspect the exact raw windows behind one base-head
  rollup instead of stopping at the percentile summary. Raw metrics history is
  now also bounded by a role-aware `MetricsRetentionConfig`: trainer-heavy
  peers keep a smaller tail than validator or bootstrap/operator nodes, the
  runtime prunes old per-record metric JSON on write, only keeps a recent
  revision window per experiment for raw detail, the durable store compacts
  oversized `entries.jsonl` files on open, and drilldown responses are capped
  so long training runs stay near steady-state resource use instead of growing
  unbounded in memory. The live control-plane metrics event tail is now bounded
  as well, so repeated timestamped refresh announcements do not accumulate
  forever in long-lived runtimes.
- UI/testkit baseline: `burn_p2p_ui` remains a framework-neutral typed contract
  crate with portal, picker, trust, and participant views. `burn_p2p_testkit`
  provides topology simulation, mixed-fleet browser/native fixtures,
  deployment-profile build checks, multiprocess smoke tests, and soak/stress
  entrypoints.
- Portal product baseline: the reference `burn_p2p_portal` surface now renders
  join guidance, current heads, trust/release posture, transport hints, and
  receipt-driven leaderboards instead of acting as a thin placeholder page.

Known gaps:

- Past the current baseline, the longer roadmap is now mostly expansion work:
  broader cross-platform hardware sampling, additional provider presets, richer
  long-term portal assets, and more packaging/ops hardening.

Quick start surfaces:

- Library example: `cargo run -p burn_p2p --example synthetic_trainer`
- Minimal family/workload example:
  `cargo run -p burn_p2p --example family_workload_minimal`
- Burn facade example: `cargo run -p burn_p2p --example burn_ndarray_runtime --features burn`
- Bootstrap daemon: `cargo run -p burn_p2p_bootstrap --bin burn-p2p-bootstrap -- crates/burn_p2p_bootstrap/examples/local-bootstrap.json`
- Auth-enabled bootstrap daemon: `cargo run -p burn_p2p_bootstrap --bin burn-p2p-bootstrap -- crates/burn_p2p_bootstrap/examples/authenticated-bootstrap.json`
- Trusted-minimal example: `cargo run -p burn_p2p_bootstrap --bin burn-p2p-bootstrap -- crates/burn_p2p_bootstrap/examples/trusted-minimal.json`
- Enterprise SSO example: `cargo run -p burn_p2p_bootstrap --bin burn-p2p-bootstrap -- crates/burn_p2p_bootstrap/examples/enterprise-sso.json`
- Trusted-browser example: `cargo run -p burn_p2p_bootstrap --bin burn-p2p-bootstrap -- crates/burn_p2p_bootstrap/examples/trusted-browser.json`
- Community-web example: `cargo run -p burn_p2p_bootstrap --bin burn-p2p-bootstrap -- crates/burn_p2p_bootstrap/examples/community-web.json`
- Compose packaging examples:
  `deploy/compose/trusted-minimal.compose.yaml`,
  `deploy/compose/trusted-browser.compose.yaml`,
  `deploy/compose/enterprise-sso.compose.yaml`,
  and `deploy/compose/community-web.compose.yaml`
- Embedded validator daemon: `cargo run -p burn_p2p_bootstrap --bin burn-p2p-bootstrap -- crates/burn_p2p_bootstrap/examples/embedded-validator.json`
- Downstream-style embedded daemon example: `cargo run -p burn_p2p_bootstrap --example embedded_runtime_daemon`
- Edge capability manifest: `curl http://127.0.0.1:9000/capabilities`
- Browser client crate tests: `cargo test --manifest-path Cargo.toml -p burn_p2p_browser`
- Metrics foundation crate tests:
  `cargo test --manifest-path Cargo.toml -p burn_p2p_metrics`
- Social service crate tests: `cargo test --manifest-path Cargo.toml -p burn_p2p_social`
- Portal crate tests: `cargo test --manifest-path Cargo.toml -p burn_p2p_portal`
- Auth connector crate tests:
  `cargo test --manifest-path Cargo.toml -p burn_p2p_auth_external -p burn_p2p_auth_github -p burn_p2p_auth_oidc -p burn_p2p_auth_oauth`
- Browser client-to-edge HTTP e2e: `cargo test --manifest-path Cargo.toml -p burn_p2p_bootstrap --bin burn-p2p-bootstrap browser_portal_client_round_trips_against_live_http_router`
- Browser provider-exchange auth e2e: `cargo test --manifest-path Cargo.toml -p burn_p2p_bootstrap --bin burn-p2p-bootstrap browser_portal_client_completes_github_login_via_exchange_callback`
- Browser upstream-token auth e2e: `cargo test --manifest-path Cargo.toml -p burn_p2p_bootstrap --bin burn-p2p-bootstrap browser_portal_client_completes_github_login_via_upstream_token_exchange`
- Browser wasm matrix: `cargo test --manifest-path Cargo.toml -p burn_p2p_testkit --test browser_matrix`
- Deployment profile matrix: `cargo test --manifest-path Cargo.toml -p burn_p2p_testkit --test deployment_profiles`
- Example compile matrix: `cargo test --manifest-path Cargo.toml -p burn_p2p_testkit --test examples_compile`
- Mixed native+browser worker test: `cargo test --manifest-path Cargo.toml -p burn_p2p_testkit --test mixed_browser_worker`
- Browser swarm transport test: `cargo test --manifest-path Cargo.toml -p burn_p2p_testkit --test browser_swarm_transport`
- Trusted-minimal bootstrap compile: `cargo check --manifest-path Cargo.toml -p burn_p2p_bootstrap --no-default-features --features admin-http,metrics,auth-static`
- Trusted-minimal bootstrap tree hygiene:
  `cargo tree --manifest-path Cargo.toml -p burn_p2p_bootstrap --no-default-features --features admin-http,metrics,auth-static -e normal`
- Security-core dependency hygiene:
  `cargo tree --manifest-path Cargo.toml -p burn_p2p_security -e normal`
- Workspace tests: `cargo test --manifest-path Cargo.toml --workspace --features burn`
- Multi-process smoke test: `cargo test --manifest-path Cargo.toml -p burn_p2p_testkit --test multiprocess`
- Soak runner: `cargo run -p burn_p2p_testkit --bin burn-p2p-testkit-soak -- crates/burn_p2p_testkit/examples/native-soak.json`
- Merge-topology simulator tests: `cargo test --manifest-path Cargo.toml -p burn_p2p_testkit merge_topology`
- Checkpoint artifact pipeline benchmarks:
  `cargo bench --manifest-path Cargo.toml -p burn_p2p_checkpoint --bench artifact_pipeline`
- Burn module merge benchmarks:
  `cargo bench --manifest-path Cargo.toml -p burn_p2p_engine --bench module_merge`
- Merge-topology simulation benchmarks:
  `cargo bench --manifest-path Cargo.toml -p burn_p2p_testkit --bench merge_topology`
- Swarm control-plane benchmarks:
  `cargo bench --manifest-path Cargo.toml -p burn_p2p_swarm --bench control_plane`
- Dataloader planning benchmarks:
  `cargo bench --manifest-path Cargo.toml -p burn_p2p_dataloader --bench planning`
- Limits calibration benchmarks:
  `cargo bench --manifest-path Cargo.toml -p burn_p2p_limits --bench capability`
- Security auth/admission benchmarks:
  `cargo bench --manifest-path Cargo.toml -p burn_p2p_security --bench security`
- Browser path latency benchmarks:
  `cargo bench --manifest-path Cargo.toml -p burn_p2p_testkit --bench browser_path`
- Real-browser device probe:
  `node crates/burn_p2p_testkit/scripts/browser_real_device_probe.mjs`
- Real-browser probe test wrapper:
  `cargo test --manifest-path Cargo.toml -p burn_p2p_testkit --test browser_real_device -- --ignored`
- 32-trainer stress entrypoint:
  `cargo run -p burn_p2p_testkit --bin burn-p2p-testkit-soak -- crates/burn_p2p_testkit/examples/native-stress-32.json`
- Multi-process fan-in stress test: `cargo test --manifest-path Cargo.toml -p burn_p2p_testkit --test multiprocess validator_can_fan_in_many_process_trainers`
- Multi-process soak test entrypoints:
  `cargo test --manifest-path Cargo.toml -p burn_p2p_testkit --test multiprocess native_process_soak_runner_reports_multi_window_progress`
  and
  `cargo test --manifest-path Cargo.toml -p burn_p2p_testkit --test multiprocess native_process_soak_runner_reports_concurrent_round_progress`
