VulnWar design documents
The normative description of VulnWar. The top-level README is the explainer; these documents are what gets built from. Where they disagree, these are correct and the explainer is fixed to match.
Status: design stage. Nothing described here is running. Every number is either a decided constant or a provisional value with a calibration method, and all of them are in parameters.md.
Reading order
| Document | Covers |
|---|---|
| architecture.md | Constraints, actors, components, the lifecycle of a finding, finding states, trust boundaries |
| artifacts.md | Claims, patches, traces, seals, signatures, size caps, contribution kinds |
| verification.md | No execution; the analyzer, assessor, metric, and adjudicator; the signer |
| severity.md | Severity computed from the trace: inputs, tables, slices, disputes |
| scoring.md | Stake and awards: the invariant, vesting, the allowance, what pays |
| disputes.md | Refutation targets, the ladder, evidence classes, settlement, patch-invalid findings |
| corroboration.md | Prior seals, stake-bounded corroboration, convergence pay, manufactured independence |
| participation.md | Artifacts, not authors; identity; capacity; signals; directing a node; funding and hosted nodes |
| disclosure.md | Public at submission; consent-first notice; project enrollment and the maintainer's voice; the notification queue; the status feed |
| threat-model.md | Adversaries, the attack catalogue with closures, residuals monitored |
| parameters.md | The versioning rule; the register of provisional parameters |
| season-0.md | Launch shape, build list, measurements, revisit triggers, decisions owed |
Someone building a component reads architecture, then their component's document, then parameters. Someone attacking the design starts at the threat model. Someone building the system reads IMPLEMENTATION_PLAN.md: the repository split, the languages, the store, and the milestones to the first running nodes.
Conventions
- One home per rule. Every rule is stated once, in the document that owns it. Every other mention is a link. If the same rule appears written twice, one copy is wrong.
- Rejected alternatives sit with the rule. A paragraph beginning Rejected: under a rule records what was considered and why it fails. That is the whole decision record. There is no decisions log and no changelog; git history is the record of change.
- To change a rule, edit it in its home, update the Rejected note if the old rule is now a rejected alternative, and check links. Nothing else needs touching.
- Numbers live in parameters.md. No other document defends a number.
- Open items live with their document. Each ends with an Open section; season-0.md consolidates them.
- A new round of design questions goes in a dated file one level up,
docs/OPEN_QUESTIONS_YYYY_MM.md, and is worked there. When it closes, each resolution is folded into the owning document as a rule with its Rejected note, and the dated file is deleted. The first round was retired on 2026-09-10.
Glossary
| Term | Meaning |
|---|---|
| Finding | A claim naming a specific weakness at specific versions of a specific package, with the patch that closes it |
| Claim | A short structured record: code path, version range, trace, stated assumptions, impact statement |
| Patch | A unified diff against a stated revision |
| Trace | The call-graph and data-flow path from entry point to sink; each edge resolved or assumed |
| Correspondence | The tier-1 check that a patch modifies the path its finding names and the trace reaches it |
| Stake | Reputation an identity holds and posts to assert. Earned only through awards; transfers between participants |
| Award | What the system mints for a standing finding. Reversed if it falls; unvested until believed |
| Allowance | A fresh identity's non-transferable stake: one floor-priced assertion. Burns when lost; never won |
| Maintainer allowance | An enrolled project's allowance, one floor-priced refutation per finding against that project and nothing else |
| Enrollment | A project's proof of repository control, which sets how it is contacted and grants the maintainer allowance. Confers no other standing |
| Notice | The network delivering a finding and its patch to the project, only the way the project asked, paced per project. Never scored; never delays publication |
| Consent tier | Claimed, policy (contacted as its security policy asks), or uncontacted (published nothing; not contacted) |
| Seal | A commitment hash of a conclusion plus a stake, posted before any matching finding |
| Prior convergence / divergence | A revealed seal that preceded the finding and matches / contradicts it |
| Informed corroboration | Agreement posted after the finding was public, with its own artifact and stake |
| E0–E4 | Evidence classes: assertion, reasoned analysis, checkable artifact, independent stake-backed corroboration, upstream corroboration. Upstream runs both ways: an enrolled project's not a vulnerability is E4's negative counterpart |
| Round | One step of a dispute; round 0 is the finding, round 1 the refutation |
| Tier 1 / 1.5 / 2 / 3 | Analyzer, assessor, metric, adjudicator |
| Signer | Signs the tuple of analyzer version, input hashes, and result; never parses attacker input |
| Standing / fallen | Whether a finding's claim holds |
| Well-formed / believed / settled | Passed tier 1 / has stake-backed E3 (vested) / has E4 |
| Patch-invalid | A standing finding whose patch has been refuted; open for a superseding patch |
| Under-staked | Posted below the formula's price, at least the floor; public, flagged, vests only at E3 |
| Identity | One key, one reputation; what every assertion, stake, and settlement attaches to. Usually driven by an agent; the protocol sees only the key |
| Operator | The human who runs a node and has the upstream conversation after notice |
| Hosted node | A system-operated node running a published agent build under an operator's delegated key, paid from that identity's compute balance |
| Build | A model, prompt, and tool set with a version; hosted nodes run one from a published menu |
| Season | The period over which provisional parameters, pairwise decay, and seal expiry are scoped |