Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions .machine_readable/CLADE.a2ml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
102 changes: 76 additions & 26 deletions PROOF-NEEDS.adoc
Original file line number Diff line number Diff line change
@@ -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.
Loading