Skip to content

Commit f398065

Browse files
docs: seed docs/proof-debt.md per trusted-base policy (#161)
## Summary - Adds `docs/proof-debt.md` — schema-conformant index for the trusted-base reduction policy ([standards#203](hyperpolymath/standards#203)). - boj-server is the **reference implementation** cited in standards#203. ## Sections | § | Content | |---|---| | (a) DISCHARGED | None — 5 class-J axioms unavoidable in Idris2 0.8.0. | | (b) BUDGETED | Reference to `docs/backend-assurance/` (BEAM-side validation). | | (c) NECESSARY | Table of all 5 axioms in `src/abi/Boj/SafetyLemmas.idr`. | | (d) DEBT | None in ABI layer. | ## What this PR does NOT duplicate Substantive content lives in `PROOF-NEEDS.md` + `docs/backend-assurance/*`. This file references them. ## Companion - standards#195, #203 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 8888353 commit f398065

1 file changed

Lines changed: 107 additions & 0 deletions

File tree

docs/proof-debt.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
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

Comments
 (0)