Skip to content

Commit 12d6fd6

Browse files
docs(policy): fill in trusted-base policy — Lean + Idris2 OWED + #211 cross-link (#222)
## Summary Fills three gaps in the trusted-base reduction policy (standards#203, merged) so per-repo proof-debt triage prompts can classify cleanly: - **Idris2 `||| OWED:` + `0`-multiplicity form** added as the canonical axiom annotation (disposition (c)). Distinguishes proof-only declarations from the run-time `believe_me` form already documented under (b). - **Lean annotation block** added (was missing). Shows `axiom` for necessary-axiom (c) and named `sorry` for debt (d). - **Marker disambiguation**: `TRUSTED:` (run-time soundness break / (b)), `AXIOM:` (named top-level axiom / (c)), `OWED:` (erased / cross-language debt / (c) or (d)). - **Enforcement section** rewired to cross-link standards#211 (merged) with the concrete script path, marker set, and 5-line annotation window — replacing the "future PR" placeholder. - **Status table** updated: #203 merged, #211 merged, #213 seeded `standards`' own `proof-debt.md`. `:status:` PROPOSED → ADOPTED. - Companion documents expanded to link #211 and #213. ## Why The per-repo proof-debt triage prompts queued behind this (followup chain #8/#9/#10) need a concrete classification grammar and annotation syntax for every prover the estate uses. Without the Lean example, the OWED erased form, and the cross-link to the actual enforcement script, the prompts fall back to ad-hoc judgment per repo and the trusted base won't shrink coherently. ## Scope Single doc file; no code, no CI changes. The Companion PRs (#211 enforcement, #213 schema-example seed) have already merged — this is purely the in-policy fill-in those merges enabled. ## Test plan - [ ] Asciidoctor render is well-formed (no broken cross-refs, source blocks close). - [ ] `scripts/check-trusted-base.sh` on a sample repo recognises `OWED:`, `TRUSTED:`, and `AXIOM:` markers as documented (already verified per #211 PR body). - [ ] CI green on PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 5eb28d7 commit 12d6fd6

1 file changed

Lines changed: 87 additions & 21 deletions

File tree

docs/TRUSTED-BASE-REDUCTION-POLICY.adoc

Lines changed: 87 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
// SPDX-License-Identifier: MPL-2.0
22
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
33
= Trusted-Base Reduction Policy
4-
:revdate: 2026-05-26
5-
:status: PROPOSED
4+
:revdate: 2026-05-27
5+
:status: ADOPTED
66
:audit: hyperpolymath/standards#195
77
:audit-licence: hyperpolymath/standards#196
88
:audit-docs: hyperpolymath/standards#197
9+
:enforcement: hyperpolymath/standards#211
910
:precedent: hyperpolymath/boj-server backend-assurance harness
1011

1112
This document is the canonical estate-wide policy for managing
@@ -129,6 +130,41 @@ wasm_marshal_u64 : Bits64 -> ByteArray
129130
wasm_marshal_u64 x = believe_me ...
130131
----
131132

133+
For Idris2 *axioms* (disposition (c)), prefer the canonical form: a
134+
doc-comment header (`|||`) starting with `OWED:` and a `0`-multiplicity
135+
(erased) declaration. The erased multiplicity makes the term proof-only —
136+
it cannot escape into runtime code and disappears from compiled output —
137+
so the unproven assumption is structurally scoped to type-level reasoning:
138+
139+
[source,idris]
140+
----
141+
||| OWED: function extensionality at the typed-wasm export interface.
142+
||| Necessary; not derivable in Idris2 0.8.0 without UIP.
143+
||| See docs/proof-debt.md §(c) entry "funExtTW".
144+
||| Citation: echo-types `Echo.FunExt`, Mathlib4 `Function.funext_iff`.
145+
0 funExtTW : (f, g : a -> b) -> ((x : a) -> f x = g x) -> f = g
146+
----
147+
148+
The `OWED:` token is recognised by `scripts/check-trusted-base.sh`
149+
alongside `TRUSTED:` and `AXIOM:`. Use `OWED:` for proof-only erased
150+
declarations (Idris2 0-multiplicity, Coq `Axiom`-of-Prop, Lean `axiom` in
151+
`Prop`) and `TRUSTED:` for run-time soundness breaks (`believe_me`,
152+
`unsafePerformIO`, `unsafe`).
153+
154+
[source,lean]
155+
----
156+
-- AXIOM: function extensionality; necessary; see docs/proof-debt.md §(c).
157+
-- Citation: Mathlib4 `Function.funext_iff` (commit abc1234).
158+
axiom funExt {α β : Type} (f g : α → β) :
159+
(∀ x, f x = g x) → f = g
160+
161+
-- For debt-style markers (disposition (d)), prefer the named sorry:
162+
-- DEBT: substitution preservation; owner @maintainer; deadline 2026-08-01.
163+
-- See docs/proof-debt.md §(d) entry "subst_preservation".
164+
theorem subst_preservation : ∀ {Γ τ e e'}, Subst e e' → Typed Γ e τ → Typed Γ e' τ :=
165+
sorry
166+
----
167+
132168
[source,coq]
133169
----
134170
(* AXIOM: function extensionality.
@@ -145,25 +181,51 @@ postulate
145181
∥_∥ : Set → Set
146182
----
147183

148-
The leading-comment marker (`TRUSTED:` / `AXIOM:`) is itself part of the
149-
contract — the audit script in section "Enforcement" below greps for it.
184+
The leading-comment marker (`TRUSTED:` / `AXIOM:` / `OWED:`) is itself
185+
part of the contract — the audit script in section "Enforcement" below
186+
greps for it. Choose the marker by run-time vs proof-time scope:
187+
188+
* `TRUSTED:` — run-time soundness break (`believe_me`, `unsafe`,
189+
`unsafePerformIO`, `assume val`, `:axiom`). Pair with disposition (b)
190+
BUDGETED and a property-test budget.
191+
* `AXIOM:` — top-level named axiom (Coq `Axiom`, Lean `axiom`, Agda
192+
`postulate`). Pair with disposition (c) NECESSARY AXIOM and a
193+
citation.
194+
* `OWED:` — Idris2-style erased (`0`-multiplicity) axiom or any
195+
cross-language self-documented debt marker. Pair with either (c)
196+
NECESSARY AXIOM (with citation) or (d) DEBT (with deadline and
197+
owner).
150198

151199
== Enforcement
152200

153-
A future PR will wire `scripts/check-trusted-base.sh` into
154-
`governance-reusable.yml`. The script:
155-
156-
. Counts every soundness-relevant escape hatch in the caller repo.
157-
. Verifies each is either preceded by a `TRUSTED:` or `AXIOM:` comment,
158-
OR enumerated in `docs/proof-debt.md`.
201+
Enforcement landed at link:{enforcement}[standards#211] as
202+
`scripts/check-trusted-base.sh`, wired into `governance-reusable.yml`
203+
as a `trusted-base` job. The script:
204+
205+
. Greps every soundness-relevant escape hatch in the caller repo
206+
(`Axiom`, `Admitted`, `admit.`, `axiom`, `sorry`, top-level `postulate`,
207+
`believe_me`, `really_believe_me`, `assert_total`, top-level `partial`,
208+
`assume val`, `admit_p`, `:axiom`, plus cross-language `TODO PROOF` /
209+
`OWED:` / `FIXME PROOF` markers in soundness-relevant positions).
210+
. Verifies each is either preceded within 5 lines by a `TRUSTED:`,
211+
`AXIOM:`, or `OWED:` leading comment, OR enumerated by path in
212+
`docs/proof-debt.md` (or `.adoc`).
159213
. Fails CI when a marker is naked (no annotation AND no proof-debt.md
160214
entry).
161-
. Optionally fails CI when `docs/proof-debt.md` §(d) DEBT entries are
162-
past their deadline.
215+
. No-ops cleanly on repos with zero proof-bearing files (true for most
216+
of the estate).
217+
218+
A follow-up may extend it to fail CI when `docs/proof-debt.md` §(d) DEBT
219+
entries are past their stated deadline.
220+
221+
This is the same shape as `check-licence-consistency.sh` (standards#201)
222+
— local script, called from the governance bundle, no network
223+
dependencies.
163224

164-
This is the same shape as `check-licence-consistency.sh`
165-
(standards#201) — local script, called from the governance bundle, no
166-
network dependencies.
225+
The seed `docs/proof-debt.md` for the `standards` repo itself landed at
226+
standards#213 as the canonical example of the schema in action (15
227+
markers triaged, 11 §(d) entries with named owners and discharge
228+
recipes).
167229

168230
== Precedent: boj-server backend-assurance harness
169231

@@ -193,10 +255,10 @@ first (rough P0/P1/P2 ordering):
193255

194256
| P0 | `ephapax` | 1 `Admitted` in `formal/Semantics.v` (`preservation`); was 3 at audit time, 2 discharged via https://github.com/hyperpolymath/ephapax/pull/146[ephapax#146]. Discharge plan in `ROADMAP.adoc` § "Preservation closure plan" + `formal/PRESERVATION-DESIGN.md` (four-layer redesign on branch `proof/l1-region-threading-design`). Migration filed: https://github.com/hyperpolymath/ephapax/pull/164[ephapax#164].
195257
| P0 | `boj-server` | Reference implementation — formalise the existing harness as the canonical example.
196-
| P1 | `absolute-zero` | 72 Coq + 315 Lean markers across 6638 proof files; needs the schema before any single-repo close-out is tractable.
258+
| P1 | `absolute-zero` | Phase-1 triage MERGED via https://github.com/hyperpolymath/absolute-zero/pull/58[absolute-zero#58] + https://github.com/hyperpolymath/absolute-zero/pull/59[#59]: **72 Coq Axioms classified** (52 §(c) + 17 §(a)-backlog + 3 §(b)). Remaining outside Phase 1: **52 Lean `axiom` decls + 7 Idris2 `postulate`s + 124 Lean `sorry`s** (canonical count via `check-trusted-base.sh`; the audit-time "315 Lean across 6638 proof files" figure was debunked — no source reproduces 315). Phase 2 work tracked in absolute-zero.
197259
| P1 | `maa-framework` | 134 markers in 25 files (high density); investigate whether vendored or original.
198260
| P1 | `betlang` | Single named axiom (`substTop_preserves_typing`) — clean (b) or (c) classification.
199-
| P1 | `proven` | 372 `TODO PROOF` markers; convert to §(d) entries with deadlines.
261+
| P1 | `proven` | Real debt surface (per Phase-1 triage 2026-05-27, `docs/proof-debt-triage.md`): **280 `\|\|\| OWED:` annotations** across 44 `Proofs.idr` modules (Fork A form), **4 `@ Assumed:` postulate tags** in `src/Proven/SafeDigest.idr` (needs migration to Fork A), and **~70 `Safe*.idr` modules** with `Prevents:`/`Guarantees:` overclaim docs and no discharged theorem. ("372 `TODO PROOF`" from the original audit prompt does not match the codebase — the string `TODO PROOF` is absent; 280 OWED is the canonical count.)
200262
| P2 | `standards` | 4 Agda postulate + 11 Idris partial — set the example for downstream.
201263
| P2 | `typed-wasm`, `stapeln`, `vcl-ut`, `hypatia`, `snifs`, `somethings-fishy` | Each 5–15 `believe_me`; audit and classify in a single PR each.
202264
|===
@@ -207,14 +269,18 @@ first (rough P0/P1/P2 ordering):
207269
|===
208270
| Date | Event
209271

210-
| 2026-05-26 | Policy filed (standards#202).
211-
| TBD | `scripts/check-trusted-base.sh` filed (separate PR).
212-
| TBD | Per-repo `docs/proof-debt.md` files seeded across P0 repos.
272+
| 2026-05-26 | Policy filed and merged (standards#203).
273+
| 2026-05-26 | `scripts/check-trusted-base.sh` filed and merged (standards#211); wired into `governance-reusable.yml` as the `trusted-base` job.
274+
| 2026-05-26 | Seed `docs/proof-debt.md` landed for `standards` itself (standards#213) as the schema reference.
275+
| 2026-05-27 | Fill-in pass: Idris2 `OWED:` + 0-multiplicity form, Lean annotation block, Enforcement cross-link to #211 (this PR). Status promoted from PROPOSED → ADOPTED.
276+
| TBD | Per-repo `docs/proof-debt.md` files seeded across P0/P1 repos via the triage prompts that this policy unblocks.
213277
|===
214278

215279
== Companion documents
216280

217281
* link:{audit}[standards#195] — estate proof-debt audit (the empirical motivation)
218282
* link:{audit-licence}[standards#196] — estate licence-debt audit
219283
* link:{audit-docs}[standards#197] — estate documentation-debt audit
220-
* `scripts/check-licence-consistency.sh` (standards#201) — the precedent for the eventual `check-trusted-base.sh`
284+
* link:{enforcement}[standards#211] — `scripts/check-trusted-base.sh` and the `trusted-base` job in `governance-reusable.yml`
285+
* https://github.com/hyperpolymath/standards/pull/213[standards#213] — seed `docs/proof-debt.md` for the `standards` repo itself (canonical schema example)
286+
* `scripts/check-licence-consistency.sh` (standards#201) — the structural precedent for `check-trusted-base.sh`

0 commit comments

Comments
 (0)