Skip to content

README.md

Latest commit

 

History

History
131 lines (110 loc) · 6.54 KB

README.md

File metadata and controls

131 lines (110 loc) · 6.54 KB

Overlay

Specification-first Rust workspace for a censorship-resistant overlay network.

Current Stage

The current repository stage is milestone-28-production-gates-packaging-safety-hardening.

Milestones 0-26 are landed baseline work. Current tasks should stay narrow: maintain the hardened bootstrap and bounded recovery boundary, keep the release/packaging docs honest, tighten bounded production gates, and improve safety validation without widening protocol scope.

Current Green Path

Use this repository in the current stage with one sign-off flow:

  1. run the applicable commands in VALIDATION.md;
  2. run ./devnet/run-production-gate.sh on the same commit;
  3. use docs/PILOT_RUNBOOK.md to collect separate-host evidence before claiming bounded production release status on that commit;
  4. generate the ship artifact with ./devnet/package-release.sh on that same validated commit.

./devnet/run-first-user-acceptance.sh remains the landed functional acceptance component inside that production flow. ./devnet/run-launch-gate.sh and ./devnet/run-distributed-pilot-checklist.sh remain the landed component scripts inside that acceptance flow. ./devnet/run-pilot-checklist.sh is retained only as the older Milestone 18 localhost rehearsal pack.

Current Acceptance Surface

The current validated surface includes:

  • node identity, wire framing, handshake, transport/session, peer/bootstrap, presence publish, exact lookup by node_id, relay fallback, path scoring, service registration/open, and structured metrics/logs;
  • overlay-cli run, status, status --summary, doctor, inspect, bootstrap-serve, bootstrap-sign, publish, lookup, open-service, and relay-intro;
  • ./devnet/run-production-gate.sh, ./devnet/run-production-soak.sh, ./devnet/run-packaging-check.sh, and ./devnet/package-release.sh for bounded production release validation and operator packaging;
  • repo-local proof paths in devnet/run-smoke.sh, devnet/run-distributed-smoke.sh, devnet/run-multihost-smoke.sh, devnet/run-launch-gate.sh, devnet/run-first-user-acceptance.sh, and devnet/run-distributed-pilot-checklist.sh;
  • bounded per-source bootstrap diagnostics in runtime_status.health.bootstrap with last_attempt_summary and last_sources, including explicit unavailable, integrity_mismatch, trust_verification_failed, stale, and empty_peer_set outcomes;
  • bounded restart recovery from persisted bootstrap-source preference, last-known active bootstrap peers, and local service registration intent embedded in runtime_status, plus continued bootstrap retry until a live source succeeds again;
  • a bounded operator inspection surface through overlay-cli inspect, which combines one local persisted status/doctor report with an explicit set of requested lookup, open-service, and relay-intro probes in one machine-readable result;
  • an explicit acceptance pack covering fresh join, service publish/open, deterministic three-relay candidate proof, one-bootstrap-down startup, one-relay-down service open, repeated relay-bind failure recovery, ordinary restart recovery, and stale-state cleanup;
  • the dedicated distributed pilot pack under devnet/pilot/.

Bounded Production Boundary

The current repo may be described as a bounded production release only within this claim:

  • ./devnet/run-production-gate.sh passed on the same commit;
  • the exact acceptance scenarios in docs/FIRST_USER_ACCEPTANCE.md remain green on that same commit as a production-gate component;
  • operators use static signed bootstrap artifacts over http://, pinned signer keys with optional SHA-256 pins, explicit bounded operator surfaces, reproducible checked release packages, and the checked-in bounded three-relay pilot topology;
  • expected degraded cases remain explicit, including one failed primary relay-intro during relay-unavailable rehearsal, two failed relay-intro attempts before tertiary recovery in the repeated-failure rehearsal, and rejected tampered bootstrap artifacts;
  • separate-host evidence from docs/PILOT_RUNBOOK.md is still attached before the claim is used for a release note.

Primary Docs

  • HANDOFF.md: current stage summary and first-task guidance
  • IMPLEMENT.md: repository stage history and current execution boundaries
  • VALIDATION.md: required validation commands and current sign-off order
  • docs/PRODUCTION_CHECKLIST.md: bounded production release gate
  • docs/PRODUCTION_RELEASE_TEMPLATE.md: bounded production release note template
  • docs/KNOWN_LIMITATIONS.md: limitations that must ship with every release
  • docs/FIRST_USER_ACCEPTANCE.md: exact acceptance scenarios and boundary
  • docs/LAUNCH_CHECKLIST.md: current launch gate and localhost sign-off flow
  • docs/PILOT_RUNBOOK.md: separate-host pilot execution and evidence
  • docs/DEVNET.md: checked-in devnet layouts and proof wrappers
  • docs/OPEN_QUESTIONS.md: conservative defaults for underspecified areas

Remaining Limitations After Milestone 28

  • bootstrap is still static signed artifact delivery over http://, not HTTPS or a public trust framework
  • operator surfaces remain explicit and operator-directed; overlay-cli inspect bundles requested remote probes, but the repo still has no general distributed control plane or discovery layer
  • release packages are validated and installable, but they still target operator-managed hosts with Rust-free binary distribution only; there is no platform matrix, service manager integration, or auto-updater
  • restart recovery remains bounded to bootstrap-source state, last-known active bootstrap peers, and local service registration intent; presence records, service-open sessions, relay tunnels, and path probes are still rebuilt
  • relay fallback is proven for the checked-in bounded three-relay pilot topology, not arbitrary relay graphs or public-network conditions
  • off-box evidence still must be collected on the validated commit before a release note can claim bounded production release status

Stage Marker Discipline

The repository stage marker lives in the root REPOSITORY_STAGE file and in overlay_core::REPOSITORY_STAGE. Keep README.md, HANDOFF.md, IMPLEMENT.md, VALIDATION.md, docs/FIRST_USER_ACCEPTANCE.md, docs/PRODUCTION_CHECKLIST.md, docs/PILOT_RUNBOOK.md, docs/DEVNET.md, docs/LAUNCH_CHECKLIST.md, and docs/OPEN_QUESTIONS.md synchronized with that marker whenever the stage changes.

In sandboxed Linux-on-Windows environments, set TMPDIR=/tmp for commands that link test binaries if the default temp directory is not writable.