Skip to content

Commit 4c821e0

Browse files
docs: seed docs/proof-debt.md per trusted-base policy (#148)
## Summary - Seeds `docs/proof-debt.md` enumerating the 3 known `Admitted`s in `formal/Semantics.v` (lines 4924, 5983, 6572) and their planned discharge. - Follows the schema defined by [standards#203](hyperpolymath/standards#203) (trusted-base reduction policy). - Closes part of Item-3 follow-up of the 2026-05-26 estate tech-debt audit. ## Entries (§(d) DEBT) | File:line | Lemma | Plan | |---|---|---| | `formal/Semantics.v:4924` | inside `step_preserves_type` | Discharge per `project_ephapax_preservation_closure_plan` (6-9 day plan, deadline 2026-09-01) | | `formal/Semantics.v:5983` | inside `step_output_context_eq` | Corollary of the strengthened `step_preserves_type` | | `formal/Semantics.v:6572` | inside `preservation` (top-level theorem) | Lands automatically once the two feeder lemmas close | ## What this PR does NOT do Discharge the proofs. That's separate, multi-PR work owned by the closure plan. This PR just makes the debt *visible* in the agreed schema so it's countable and so the future `scripts/check-trusted-base.sh` CI gate has something to validate against. ## Companion - standards#195 — estate proof-debt audit (the empirical motivation) - standards#203 — trusted-base reduction policy (the schema) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 3af7ae7 commit 4c821e0

1 file changed

Lines changed: 104 additions & 0 deletions

File tree

docs/proof-debt.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
<!--
2+
SPDX-License-Identifier: MPL-2.0
3+
SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
4+
-->
5+
6+
# Proof Debt — ephapax
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+
This file enumerates every soundness-relevant escape hatch in the ephapax
11+
codebase and its disposition under the trusted-base policy. Markers without
12+
an entry below count as undocumented debt and will be flagged by
13+
`scripts/check-trusted-base.sh` once that lands.
14+
15+
Markers in scope (from the 2026-05-26 estate proof-debt audit,
16+
standards#195):
17+
- Coq `Axiom`, `Admitted`, `admit.`
18+
- Idris2 `believe_me`, `assert_total`, top-level `partial`
19+
- `TODO PROOF` / `OWED:` / `FIXME PROOF` markers
20+
21+
## (a) DISCHARGED in this repo
22+
23+
*(None yet — entries move here when their proof lands.)*
24+
25+
## (b) BUDGETED — tested with a refutation budget
26+
27+
*(None — ephapax's proof targets are deductive, not property-tested. Items
28+
in this section would belong here if/when we add adversarial-test budgets
29+
for the Rust↔Idris2 ABI boundary code.)*
30+
31+
## (c) NECESSARY AXIOM
32+
33+
*(None — ephapax does not introduce any irreducible metatheoretic axioms
34+
in the working Coq logic. If future work adds e.g. `funExt`, list it here
35+
with a citation to its canonical formalisation.)*
36+
37+
## (d) DEBT — actively to be closed
38+
39+
### `formal/Semantics.v:4924``Admitted` inside `step_preserves_type`
40+
41+
- **Lemma**: `step_preserves_type` (declared at `formal/Semantics.v:3615`).
42+
- **Statement (informal)**: small-step semantics preserve typing.
43+
- **Owner**: @hyperpolymath
44+
- **Plan**: discharge as part of [project_ephapax_preservation_closure_plan](https://github.com/hyperpolymath/standards/blob/main/docs/audits/2026-05-26-estate-proof-debt.md). Estimated 6–9 days. ~40 goals split into sub-buckets A/B/C/D; start with A.
45+
- **Deadline**: 2026-09-01 (per closure plan).
46+
47+
### `formal/Semantics.v:5983``Admitted` inside `step_output_context_eq`
48+
49+
- **Lemma**: `step_output_context_eq` (declared at `formal/Semantics.v:4944`).
50+
- **Statement (informal)**: output context is preserved across a step
51+
(modulo region marking).
52+
- **Owner**: @hyperpolymath
53+
- **Plan**: discharged as a corollary of the strengthened
54+
`step_preserves_type` proof; depends on the preservation closure plan.
55+
- **Deadline**: 2026-09-01.
56+
57+
### `formal/Semantics.v:6572``Admitted` inside `preservation`
58+
59+
- **Theorem**: `preservation` (declared at `formal/Semantics.v:5985`).
60+
- **Statement (informal)**: the main preservation theorem for the ephapax
61+
region-aware operational semantics.
62+
- **Owner**: @hyperpolymath
63+
- **Plan**: this is the top-level theorem the other two Admitteds feed
64+
into. Discharge order: `step_preserves_type` first → then
65+
`step_output_context_eq` → then `preservation` lands automatically
66+
modulo wiring.
67+
- **Deadline**: 2026-09-01.
68+
69+
## Soundness-relevant escape hatches in non-Coq code
70+
71+
The 2026-05-26 audit also surfaced:
72+
- 1 `believe_me` reference (a comment in
73+
`src/formal/Ephapax/Formal/RegionLinear.idr:127` explicitly stating
74+
"This is a REAL proof — not (), not believe_me, not assert_total" —
75+
no actual `believe_me` use; the comment is documentation about NOT
76+
using it).
77+
- 1 `partial` (Idris2 totality waiver) — TBD if real or comment artefact.
78+
- 14 `TODO PROOF` / `OWED:` markers — these were not located in this
79+
repo by the per-repo scan; they likely cluster around the same
80+
Admitteds above.
81+
82+
When `scripts/check-trusted-base.sh` lands, any genuine occurrence of
83+
the above will require either a leading `TRUSTED:` / `AXIOM:` annotation
84+
or a `§(d) DEBT` entry here.
85+
86+
## How to update this file
87+
88+
After each PR that closes one of the entries above:
89+
90+
1. Move the entry from §(d) → §(a) DISCHARGED.
91+
2. Update the closure plan referenced.
92+
3. Run `git cliff --output CHANGELOG.md` to regenerate the changelog
93+
(see [standards#206](https://github.com/hyperpolymath/standards/pull/206) for
94+
the canonical workflow).
95+
96+
## Companion documents
97+
98+
- [standards#195](https://github.com/hyperpolymath/standards/pull/195) — estate proof-debt audit
99+
- [standards#203](https://github.com/hyperpolymath/standards/pull/203) — trusted-base reduction policy (the schema this file follows)
100+
- `project_ephapax_preservation_closure_plan` (maintainer memory) — 6–9 day discharge plan
101+
102+
---
103+
104+
🤖 Initial seed by Claude Code, 2026-05-26.

0 commit comments

Comments
 (0)