diff --git a/.machine_readable/CLADE.a2ml b/.machine_readable/CLADE.a2ml index 629d30c..ef1c175 100644 --- a/.machine_readable/CLADE.a2ml +++ b/.machine_readable/CLADE.a2ml @@ -26,9 +26,7 @@ parent = "Deterministic, typed policy engine (Rust)" born = "2026-03-16" # Lifecycle status (added by clade-status-backfill; see gv-clade-index ADR 0006). -# Identity (uuid) and status are SEPARATE layers: uuid follows the GitHub path -# (a move or rename there mints a new one, gv-clade-index ADR 0007; a mirror -# move or a phase change never does); phase is a mutable pointer. No phase is +# Identity (uuid) and status are SEPARATE layers: phase is a mutable pointer. No phase is # terminal (extinct -> active is a legal "Gitassic Park" transition on the same # uuid). A prefixed-name (clade code) change with the GitHub path unchanged is # NOT a phase change — the old prefixed-name goes to aliases[], uuid and phase diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc index 65b9c2d..d6ba421 100644 --- a/PROOF-NEEDS.adoc +++ b/PROOF-NEEDS.adoc @@ -1,39 +1,89 @@ -== PROOF-NEEDS.md — palimpsest-plasma += PROOF-NEEDS — palimpsest-plasma +:toc: preamble -=== Current State +What this repository needs proved, which verifier each obligation belongs +to, and where each one stands. Verifier choices follow +https://github.com/hyperpolymath/standards/blob/main/3-practice/PROOF-POLICY.adoc[PROOF-POLICY]: +first-party Rust is verified with *Creusot* (contracts written in *Pearlite*, +Creusot's specification language) and with *Verus*, both by default (§1.2); +*Idris2* is for APIs and ABIs. Status words are the closed §5 vocabulary. -* **src/abi/*.idr**: NO -* *Dangerous patterns*: 18 `+unwrap()+` in Rust code -* *LOC*: ~6,900 (Rust) -* *ABI layer*: Missing +== Current state -=== What Needs Proving +* *Machine-checked proofs:* none. No crate has a Pearlite contract + (`#[requires]`/`#[ensures]`) or Verus code (`verus!`). +* *Creusot:* `.github/workflows/creusot-gate.yml` calls the estate gate. With + no contracts in the tree it reports "nothing was proved"; that is a notice, + not assurance. +* *Verus:* no gate yet. +* *Idris2:* no ABI is exposed, so no Idris2 obligation exists today. +* *Census:* https://github.com/hyperpolymath/mathesis[mathesis] lists this + repository with no proof files of its own, which matches the above. +* *Panic sites:* 69 `unwrap()` calls outside tests (2026-11-17). -[width="100%",cols="51%,27%,22%",options="header",] +== Obligations + +Every obligation is on first-party Rust, so each is planned for both +default verifiers. None has a contract yet. + +[cols="2,3,2,2,1",options="header"] |=== -|Component |What |Why -|SPDX parser correctness |Parser accepts all valid SPDX expressions and -rejects invalid ones |Wrong SPDX parsing causes license -misidentification +|Obligation |Entrypoint |Creusot (Pearlite) |Verus |Status -|License family registry |Family classification is complete and -consistent |Misclassified licenses create compliance risk +|SPDX expression parsing is sound and complete for the SPDX 2.3 expression +grammar: it accepts every valid expression and rejects every invalid one. +|`plasma_parser::spdx::parse_spdx_expr` +|Pearlite model of the grammar; `ensures` relating the `SpdxExpr` result +to that model +|The same property as a Verus spec over the lexer and parser +|`OPEN` -|Union policy parser |Policy composition preserves individual license -requirements |Composed policies must not lose restrictions +|The licence family registry is complete and consistent over the six named +variants (`PMPL`, `PAGPL`, `PGPL`, `PAPL`, `PBSD`, `PEUPL`): each has exactly +one entry, `published_variants` is a subset of `all_variants`, and +`lookup_variant` returns `None` for every `PalimpsestVariant::Other(_)`. +|`plasma_parser::family::registry::{lookup_variant, all_variants, published_variants}` +|`ensures` on the lookup functions over the static table +|Verus spec over the same table +|`OPEN` -|Content audit |Audit detection is sound (no false negatives) |Missed -license violations create legal exposure +|Licence zone assignment is specified for overlaps. `assign_zone` returns the +first zone, in declaration order, with a matching pattern, so a file in two +zones silently gets the first one's requirements. The obligation is that +`detect_overlaps` reports every file that matches more than one zone, so no +silent first-match is left unreported. `validate_zones` reports duplicate +zone names. Open question for the owner: should an invalid glob, which both +functions skip without error, be reported? +|`plasma_parser::zone::policy::{assign_zone, detect_overlaps, validate_zones}` +|Pearlite predicates for zone coverage and overlap +|Verus spec for the same predicates +|`OPEN` + +|Content audit has no false negatives for the licence texts it claims to +recognise. +|`plasma_parser::audit::content::detect_license_from_content` +|Contracts for the matching functions, with the recognised set as a model +|Verus spec, or a bounded check recorded as `TESTED` +|`OPEN` |=== -=== Recommended Prover +*Note:* an earlier version of this file listed a "union policy parser". No +such parser exists in the tree. The property it described, that a file in +several zones meets every one of their licence requirements, is not what the +zone row covers: the code assigns the first matching zone and only reports +the overlap. Whether overlapping zones should instead combine their +requirements, or be rejected outright, is a design decision for the owner; +until it is made, that property has no obligation here. + +== Next actions -*Idris2* — Create `+src/abi/+` with SPDX expression grammar proofs -(completeness and soundness). License family classification could use -algebraic data types with exhaustive matching. +. Add Pearlite contracts to `parse_spdx_expr` first; it carries the highest + risk, because a wrong parse misidentifies a licence. +. Add a Verus gate beside the Creusot gate, so both default verifiers run. +. Record each result here with the tool and solver versions, the revision + and the trust boundary (PROOF-POLICY §1.2, §5–§7). -=== Priority +== Priority -*LOW* — License parsing and auditing tool. The 18 unwrap() calls should -be addressed, but the overall risk is limited to incorrect license -reports. +*Low.* This is a licence parsing and auditing tool. A fault produces a wrong +report rather than unsafe behaviour.