|
| 1 | +<!-- |
| 2 | +SPDX-License-Identifier: MPL-2.0 |
| 3 | +SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) |
| 4 | +--> |
| 5 | + |
| 6 | +# Proof Debt — boj-server |
| 7 | + |
| 8 | +**Schema**: [hyperpolymath/standards `TRUSTED-BASE-REDUCTION-POLICY.adoc`](https://github.com/hyperpolymath/standards/blob/main/docs/TRUSTED-BASE-REDUCTION-POLICY.adoc) (standards#203). |
| 9 | + |
| 10 | +boj-server is the **reference implementation** for the estate trusted-base |
| 11 | +reduction policy (cited as such in standards#203). The 5 class-J axioms |
| 12 | +this repo isolates in `src/abi/Boj/SafetyLemmas.idr` are the canonical |
| 13 | +example of disposition §(c) NECESSARY AXIOM, and the |
| 14 | +`docs/backend-assurance/` per-axiom files are the canonical example of |
| 15 | +external validation under §(b)-style discipline. |
| 16 | + |
| 17 | +This `docs/proof-debt.md` is a thin schema-aligned index. The substantive |
| 18 | +content lives in: |
| 19 | + |
| 20 | +- **[`PROOF-NEEDS.md`](../PROOF-NEEDS.md)** (repo root) — full audit table |
| 21 | + with type signatures, classification rationale, and external-validation |
| 22 | + pointers. |
| 23 | +- **[`docs/backend-assurance/`](./backend-assurance/)** — per-primitive |
| 24 | + property tests + BEAM-side validation evidence |
| 25 | + (`prim__eqChar.md`, `prim__strToCharList.md`, `prim__strAppend.md`, |
| 26 | + `prim__strSubstr.md`). |
| 27 | + |
| 28 | +## (a) DISCHARGED in this repo |
| 29 | + |
| 30 | +*(None — the 5 class-J axioms are genuinely unavoidable in Idris2 0.8.0. |
| 31 | +Items would move here if a future Idris2 version exposes in-language |
| 32 | +soundness principles for `Char` / `String` primitives.)* |
| 33 | + |
| 34 | +## (b) BUDGETED — tested with a refutation budget |
| 35 | + |
| 36 | +The 5 axioms below are documented under §(c) (NECESSARY) rather than §(b) |
| 37 | +(BUDGETED) because they cannot be discharged in-language. **However**, |
| 38 | +each one is *externally validated* via the |
| 39 | +[backend-assurance harness](./backend-assurance/) — property tests |
| 40 | +running against the real BEAM runtime, exercising the Erlang/Elixir |
| 41 | +implementations of the underlying primitive operations. |
| 42 | + |
| 43 | +This dual-discipline (axiom-in-Idris2 + property-tested-externally) is |
| 44 | +the reference pattern the estate trusted-base policy recommends for |
| 45 | +extraction-boundary code. |
| 46 | + |
| 47 | +## (c) NECESSARY AXIOM |
| 48 | + |
| 49 | +All 5 are class-J ("genuinely unavoidable") per |
| 50 | +[PROOF-NEEDS.md §Axiom Audit](../PROOF-NEEDS.md) (2026-05-18). Each |
| 51 | +reduces to the same root cause: Idris2 0.8.0 treats `Char` and `String` |
| 52 | +as opaque primitive types whose operations are foreign functions with no |
| 53 | +constructors and no induction principle. |
| 54 | + |
| 55 | +| # | Site | Signature | External validation | |
| 56 | +|---|------|-----------|---------------------| |
| 57 | +| 1 | `src/abi/Boj/SafetyLemmas.idr:60` | `charEqSound : (c1,c2 : Char) -> c1 == c2 = True -> c1 = c2` | [`docs/backend-assurance/prim__eqChar.md`](./backend-assurance/prim__eqChar.md) | |
| 58 | +| 2 | `src/abi/Boj/SafetyLemmas.idr:67` | `charEqSym : (x,y : Char) -> (x == y) = (y == x)` | [`docs/backend-assurance/prim__eqChar.md`](./backend-assurance/prim__eqChar.md) | |
| 59 | +| 3 | `src/abi/Boj/SafetyLemmas.idr:218` | `unpackLength : length (unpack s) = length s` | [`docs/backend-assurance/prim__strToCharList.md`](./backend-assurance/prim__strToCharList.md) | |
| 60 | +| 4 | `src/abi/Boj/SafetyLemmas.idr:226` | `appendLengthSum : length (s ++ t) = length s + length t` | [`docs/backend-assurance/prim__strAppend.md`](./backend-assurance/prim__strAppend.md) | |
| 61 | +| 5 | `src/abi/Boj/SafetyLemmas.idr:233` | `substrLengthBound : LTE (length (substr start len s)) len` | [`docs/backend-assurance/prim__strSubstr.md`](./backend-assurance/prim__strSubstr.md) | |
| 62 | + |
| 63 | +Citation: see standards#203 §"Precedent" — boj-server's harness is the |
| 64 | +reference implementation the estate trusted-base policy directs other |
| 65 | +proof-bearing repos to adopt. |
| 66 | + |
| 67 | +## (d) DEBT — actively to be closed |
| 68 | + |
| 69 | +*(None in the Idris2 ABI layer. The 5 class-J axioms above are §(c), |
| 70 | +not §(d); they are not "to be closed" — they are load-bearing |
| 71 | +assumptions about the trusted base.)* |
| 72 | + |
| 73 | +Future work that would generate §(d) entries: |
| 74 | + |
| 75 | +- Migration to a future Idris2 version exposing in-language soundness |
| 76 | + principles for primitive types — would let entries #1–#5 move from |
| 77 | + §(c) → §(a) via discharge. |
| 78 | +- New `believe_me` introduced in non-SafetyLemmas.idr files — these |
| 79 | + must be classified as §(a)/§(b)/§(c) before merge or land here as |
| 80 | + §(d) with a deadline. |
| 81 | + |
| 82 | +## How to update this file |
| 83 | + |
| 84 | +When `src/abi/Boj/SafetyLemmas.idr` changes: |
| 85 | + |
| 86 | +1. Cross-check against `PROOF-NEEDS.md` — keep the per-site row counts |
| 87 | + in sync. |
| 88 | +2. If a new `believe_me` is introduced anywhere outside that module, |
| 89 | + add an entry here under §(d) or §(b) with an audit table entry in |
| 90 | + `PROOF-NEEDS.md`. |
| 91 | +3. The future `scripts/check-trusted-base.sh` |
| 92 | + ([standards trusted-base policy](https://github.com/hyperpolymath/standards/blob/main/docs/TRUSTED-BASE-REDUCTION-POLICY.adoc)) |
| 93 | + greps for naked `believe_me` outside `SafetyLemmas.idr` and fails CI |
| 94 | + if it's not annotated or enumerated here. |
| 95 | + |
| 96 | +## Companion documents |
| 97 | + |
| 98 | +- [`PROOF-NEEDS.md`](../PROOF-NEEDS.md) — substantive audit table. |
| 99 | +- [`docs/backend-assurance/`](./backend-assurance/) — external-validation evidence. |
| 100 | +- [standards#195](https://github.com/hyperpolymath/standards/pull/195) — estate proof-debt audit. |
| 101 | +- [standards#203](https://github.com/hyperpolymath/standards/pull/203) — trusted-base reduction policy (the schema this file follows). |
| 102 | +- Memory: `project_boj_server_backend_assurance_harness.md` — long-term reduction plan (~3 months, ~1 PR per primitive). |
| 103 | + |
| 104 | +--- |
| 105 | + |
| 106 | +🤖 Schema-conformant index seeded by Claude Code, 2026-05-26. boj-server is the |
| 107 | +reference implementation the estate trusted-base policy cites. |
0 commit comments