Skip to content

Commit e897844

Browse files
docs(EXPLAINME): add L1/L3/L4 claim sections per PRESERVATION-DESIGN §12.3 (#257)
## Summary Executes [`formal/PRESERVATION-DESIGN.md` §12.3](../blob/main/formal/PRESERVATION-DESIGN.md) — the EXPLAINME rollout. ### What changed 1. **"Dyadic Type System" → "Dyadic Type System (L2)"** — labelled and cross-references the README four-layers section + `EPHAPAX-VISION.adoc`. Adds the Coq-side L2 evidence pointer (`linear_to_affine` Qed in `formal/Modality.v`). 2. **New claim: "Sibling-safe region capabilities (L1)"** — inserted after Region-Based Memory. Cites `Counterexample.v` + `has_type_l1` judgment + §3-§4 design rationale. Honestly labels 9 residual L1 admits as L2-integration debt. 3. **New claim: "Irreversibility residue is first-class (L3, planned)"** — upstream + local evidence pointers; integration honestly labelled planned. 4. **New claim: "Dyadic mode is project-level only (L4)"** — cites `formal/L4.v` definitions + `L4-DYADIC.md` design note; explicit "no theorems by design" claim. ### Honesty constraint preserved §12.3 explicitly says: *"the evidence is the design doc + counterexample, not a passing proof — say so honestly"*. The new sections follow that — where evidence is a design doc or planned, it is labelled as such. ### Scope Pure documentation. Companion to README #256 (§12.2 half). ## Test plan - [x] All claims back-cite a real artefact (verified each pointer exists in repo). - [x] GPG-signed commit. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 35d3b6f commit e897844

1 file changed

Lines changed: 59 additions & 1 deletion

File tree

EXPLAINME.adoc

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,12 @@ is used after being freed, no resource is leaked, and region-scoped
1616
allocations are deallocated in bulk at scope exit.
1717
____
1818

19-
== Claim: Dyadic Type System
19+
== Claim: Dyadic Type System (L2)
20+
21+
The dyad is L2 in the four-layer architecture (see
22+
`README.adoc#the-four-layers` and `docs/vision/EPHAPAX-VISION.adoc`).
23+
This section presents the Rust-side evidence for the L2 discipline;
24+
L1 / L3 / L4 evidence follows below.
2025

2126
*Evidence*: The type checker (`src/ephapax-typing/src/lib.rs`) tracks
2227
`BindingForm` per context entry:
@@ -29,6 +34,9 @@ Tests `test_let_allows_unconsumed_linear` and `test_let_bang_rejects_unconsumed`
2934
verify the distinction. `test_let_bang_rejects_unconsumed_unrestricted` proves
3035
that `let!` enforces exactly-once even for unrestricted types like `I32`.
3136

37+
The Coq-side L2 evidence is `linear_to_affine : Linear ≤ Affine` (Qed,
38+
zero axioms) in `formal/Modality.v`.
39+
3240
== Claim: Two-Layer AST (Surface + Core)
3341

3442
*Evidence*: Two separate crates:
@@ -77,6 +85,56 @@ demonstrate where they diverge on identical programs (e.g.
7785
Test `test_region_non_escaping` verifies escape detection.
7886
Test `test_region_string_allocation` verifies in-region allocation.
7987

88+
== Claim: Sibling-safe region capabilities (L1)
89+
90+
*Evidence*: Region capabilities are threaded as input/output
91+
environments through every compound typing rule. A sibling cannot
92+
reference a region a previous sibling has exited — this is the
93+
soundness invariant the legacy judgment was missing.
94+
95+
* Counterexample at `formal/Counterexample.v` (all three lemmas
96+
`Qed`) demonstrates the soundness gap the threading fixes.
97+
* The new `has_type_l1` judgment lives in `formal/TypingL1.v` and
98+
carries the R-threading directly. Step relation at
99+
`formal/Semantics_L1.v`.
100+
* Design rationale at `formal/PRESERVATION-DESIGN.md §3-§4`.
101+
* Status: judgment landed; 9 L1 supporting-lemma admits remain as
102+
L2-integration debt (tracked in `PROOF-NEEDS.md`).
103+
104+
== Claim: Irreversibility residue is first-class (L3, planned)
105+
106+
*Evidence (planned)*: Operations that erase information (region
107+
exit, drop) will produce typed residue witnesses, following the
108+
https://github.com/hyperpolymath/echo-types[echo-types]
109+
formulation. Linear mode requires the residue to be observed;
110+
Affine mode permits silent lowering.
111+
112+
* Upstream theory at
113+
`~/developer/repos/echo-types/proofs/agda/EchoLinear.agda` (lines
114+
30–101), already mechanised.
115+
* Local mirror at `formal/Echo.v` — the L3 calculus is mechanised
116+
here (modes, `LEcho`, `weaken`, `degrade_mode`, all `Qed`).
117+
* Forward-looking design at `formal/PRESERVATION-DESIGN.md §6`.
118+
* Status: **planned** integration — `Echo.v` is wired up
119+
internally, but no ephapax typing rule yet introduces `TEcho`.
120+
The L3 extension follows L1's residual admit closure.
121+
122+
== Claim: Dyadic mode is project-level only (L4)
123+
124+
*Evidence*: L4 is a labelling discipline, not a proof layer.
125+
`formal/L4.v` carries `ProgramMode` (three-constructor enum) and
126+
`program_mode_to_modality` (total mapping to L2's modality). No
127+
theorems, no admits, no axioms — by design.
128+
129+
* Companion design note: `formal/L4-DYADIC.md`.
130+
* Canonical design source: `formal/PRESERVATION-DESIGN.md §7`.
131+
* Surface syntax for the L4 declaration
132+
(`#![ephapax_linear]` / `#![ephapax_affine]` /
133+
`#![module_boundary_mix(...)]`) is not yet wired into the parser
134+
or borrow checker; the mechanical scaffold is a citable type for
135+
downstream tools (Idris2 ABI, Rust borrow checker, surface
136+
parser).
137+
80138
== Technology Choices
81139

82140
[cols="1,2"]

0 commit comments

Comments
 (0)