Documentation · Block Audit · Medusa

Medusa Audit

v0.7.12 — Medusa · stamped against H.1.65

When 3 chainweb containers share a single SSD, each container's disk subscore is the drive's benchmark divided by 3. Add a 4th, all four get bench/4 on the next scoring tick. Move one to a different drive, the others' divisors update automatically. Sum across siblings on a drive always equals the drive's raw benchmark — no double-credit, no shortfall.

Proven invariants

1. Drive divisor honesty: sum(disk subscores across N siblings) === drive_bench — fast-check property, 200 random scenarios, f64-exact at our scale.
2. Linear-in-slice: doubling a slice's CPU contribution doubles the ServerScore's CPU component. Same for RAM. Integration-tested.
3. Cgroups emission: every segregated row's compose render includes deploy.resources.limits + top-level cpus + mem_limit (compose-v2 binary fallback). Operator can't lie about the slice because docker inspect reports the same values.
4. Per-drive commitment cap: sum of committed_gb on a drive can't exceed capacity − 5%. Enforced at every install + convert + migrate boundary.
5. Score persistence in breach: a node in commitment breach keeps its benchmarked ServerScore; accrual halts. UI surfaces the score in red + Pending shows ⏸ paused. Hardware fact preserved.

Test suite

• 5 segregated-tier tests — classifyHostTier edge cases at 6 GB / 3 vCPU minimums.
• 3 drive-divisor property tests with fast-check, 200+ random cases each.
• 6 fleet-counter tests — `a/b` and `a+b` format exactness (Rule 7).
• 4 cgroups-emission tests — compose render contract for segregated rows.
• 7 host-drives helper tests — resolveDriveForPath, upsertHostDrive, committedGbOnDrive, countChainwebsOnDrive.
• 6 slice-aware-score integration tests — gating, 1/2/3-sharer divisors, linear-in-CPU.
• 18 install-gate tests — every Rule 1-4 path including composite first-failure.

Coinage compatibility

Medusa plugs into Coinage's existing exact-Decimal contract. ServerScore inputs (CPU bench, RAM bandwidth, drive bench) stay f64 because they're measurements, not balances. The multiplication BASE_POINTS_PER_SEC × server_score × tick_seconds runs through mulStoicism(); the f64 server_score is promoted to Decimal at that boundary. Stoicism credit is exact-Decimal forever after.

Sign-off

All gates green. Medusa is ready for production.

Source-controlled audit record: docs/medusa-reference.md in the repo commits this audit alongside the code that produced it.