Skip to content

Commit 60ac2d4

Browse files
hyperpolymathclaude
andcommitted
docs: document echo/product OCaml pipeline integration + expand wiki (PRs #45–46)
- CHANGELOG.md: add echo OCaml pipeline block; fixed exhaustiveness bullets - PROOF-NEEDS.md: TG-4 → LANDED; update rule counts (16→26 HasType, 31→57 Step); TG-10 coverage expanded to include echoAdd/echoEq/product - PROOF-NARRATIVE.md: update HasType/Step rule lists; add §2.6 OCaml completeness table; add product/echoAdd/echoEq rows to §2.5 table; TG-4 → LANDED - FEATURE-COVERAGE.md: add 9 echo/product rows; update coverage summary (27→36); date bump - FORMAL-SEMANTICS.md: extend §1.2 BNF; add §1.5 extended types; add §3.16 echo/product typing rules; add §4.10 echo/product eval rules; renumber downstream sections - STATE.a2ml: update session/last-updated/milestones/blockers/next-actions/maintenance-status - tangle.directives.a2ml: date bump to 2026-06-14 - docs/echo-types-ocaml-pipeline.md: new developer wiki page for echo/product integration Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 67b50f6 commit 60ac2d4

8 files changed

Lines changed: 420 additions & 39 deletions

File tree

.machine_readable/6a2/STATE.a2ml

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@
55
[metadata]
66
project = "tangle"
77
version = "0.2.0-dev"
8-
last-updated = "2026-06-05"
8+
last-updated = "2026-06-14"
99
status = "active"
10-
session = "echo-types realignment + decidability + CI bootstrap — 2026-06-05"
10+
session = "echo OCaml pipeline complete (PR #45+#46) — 2026-06-14"
1111

1212
[project-context]
1313
name = "Tangle"
@@ -30,27 +30,24 @@ milestones = [
3030
"DONE (TG-2): decidability — infer ≡ HasType, type uniqueness, Decidable instance",
3131
"DONE: reproducible Lean toolchain bootstrap (proofs/bootstrap-lean.sh) + SessionStart hook; CI consolidated onto it",
3232
"NEXT (TG-1): extend type safety to let-binding (full de Bruijn substitution)",
33-
"NEXT: generalise echo to add/eq (needs a product/residue type in Ty)",
33+
"DONE: generalise echo to add/eq product type (Ty.prod), echoAdd/echoEq in Lean+OCaml (PR #45)",
3434
"NEXT: thread echo residue into TangleIR (coordinate with quandledb)",
35-
"NEXT: full OCaml echo pipeline (ast/typecheck/eval/parser/pretty)",
35+
"DONE: full OCaml echo pipeline (ast/typecheck/eval/parser/pretty) — PR #45; build fixed PR #46",
3636
"LATER (TG-3): OCaml typecheck.ml refines the Lean HasType spec",
3737
"LATER (TG-5/6/7): compositional rewriter preservation; WASM semantic preservation; braid-group eqBraids",
3838
]
3939

4040
[blockers-and-issues]
41-
issues = [
42-
"DESIGN (open, user): echo value shape — uniform `echoVal (residue,result)` (faithful to Echo=Σ, reworks merged capstones to multi-step Step*) vs per-operation lower/residue rules. Blocks the echo generalisation to add/eq.",
43-
]
41+
issues = []
4442

4543
[critical-next-actions]
4644
actions = [
47-
"Resolve the echo value-shape design fork (A vs B), then add the product type",
48-
"TG-1: let-binding type safety via de Bruijn substitution",
49-
"Generalise echo to add/eq; thread residue into TangleIR with the quandledb session",
50-
"Extend the OCaml typechecker (typecheck.ml/ast.ml) with echo types",
45+
"TG-1: let-binding type safety via de Bruijn substitution (Lean 4; ~150 LoC per PROOF-NARRATIVE §TG-1)",
46+
"TG-3: formal refinement proof — OCaml typecheck.ml vs Lean HasType",
47+
"TangleIR: thread echo residue into TangleIR schema; coordinate with quandledb session",
5148
]
5249

5350
[maintenance-status]
54-
last-run-utc = "2026-06-05T00:00:00Z"
51+
last-run-utc = "2026-06-14T03:00:00Z"
5552
last-result = "pass" # unknown | pass | warn | fail
56-
notes = "lean-proofs oracle GREEN (PR #34, #36 merged); Tangle.lean 0 errors, no sorry/axiom/admit"
53+
notes = "dune build + dune test (548/548) GREEN after PR #46; lean-proofs CI GREEN; Tangle.lean 26 HasType rules / 57 Step rules, 0 errors, no sorry/axiom/admit"

.machine_readable/bot_directives/tangle.directives.a2ml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
# tangle.directives.a2ml — directives for the bot fleet on hyperpolymath/tangle
55
[metadata]
66
version = "1.0.0"
7-
last-updated = "2026-06-05"
7+
last-updated = "2026-06-14"
88
applies-to = ["hypatia", "gitbot-fleet", "git-private-farm"]
99

1010
[development]

CHANGELOG.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
1313

1414
## [Unreleased]
1515

16+
### Echo types OCaml pipeline (PR #45 + #46)
17+
1618
### Added
19+
- Echo/product type system fully landed in the OCaml pipeline (PR #45 + #46):
20+
- `ast.ml`: 8 new `expr` constructors (`echoClose`, `lower`, `residue`, `pair`, `fst`, `snd`, `echoAdd`, `echoEq`); 2 new `ty` constructors (`TProd`, `TEcho`)
21+
- `typecheck.ml`: 8 new `infer_expr` rules mirroring Lean `HasType` (`T-Echo-Close`, `T-Lower`, `T-Residue`, `T-Pair`, `T-Fst`, `T-Snd`, `T-Echo-Add`, `T-Echo-Eq`); `pp_ty` made `rec`
22+
- `eval.ml`: `VEcho`/`VPair` value forms; 8 new `eval_expr` arms; `pp_value` made `rec`
23+
- `lexer.mll` + `parser.mly` + `token.ml`: keyword tokens and grammar productions for all 8 surface forms (`echoClose(e)`, `lower(e)`, `residue(e)`, `pair(a,b)`, `fst(e)`, `snd(e)`, `echoAdd(a,b)`, `echoEq(a,b)`)
24+
- `pretty.ml`: pretty-printers for all 8 forms; round-trips through parser
25+
- TG-4 (pretty-print/parse round-trip) discharged: `test_roundtrip.ml` extended with 16 new TG-4 entries covering every echo/product constructor (PR #46)
26+
- `docs/spec/ECHO-TANGLEIR-THREADING.md`: cross-repo contract for how echo residue threads through TangleIR to QuandleDB (PR #45)
1727
- Compositional PD compiler API (`compositional.ml` / `.mli`):
1828
`expr`, `planar_diagram`, `compiled`, `skein_payload` types
1929
- `pdv1_blob_of_pd`: canonical text serialisation format
@@ -29,6 +39,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
2939
- Zig ABI layer modernized
3040

3141
### Fixed
42+
- `compiler/bin/main.ml` debug token printer: add 8 missing echo keyword token arms (Warning 8 exhaustiveness, PR #46)
43+
- `compiler/lib/typecheck.ml` `strand_type_of_ty`: add `TProd`/`TEcho` arms (Warning 8 exhaustiveness, PR #46)
3244
- EXPLAINME.adoc section heading quotes
3345

3446
## Earlier commits (no versions tagged)

PROOF-NARRATIVE.md

Lines changed: 39 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Tangle is the **semantic core** of a four-layer federated stack:
3131
3232
┌─────────────────────────────────────────────────────────┐
3333
│ Tangle CORE (THIS REPO) │
34-
│ proofs/Tangle.lean — 16 mechanised results
34+
│ proofs/Tangle.lean — mechanised results (26 HasType, 57 Step)
3535
│ compiler/lib/*.ml — OCaml implementation │
3636
│ compiler/tangle-wasm — WASM backend │
3737
│ compiler/tangle-lsp — LSP server │
@@ -51,8 +51,8 @@ delivered slice and the remaining gap explicit.
5151

5252
## 2. Proven now
5353

54-
All 16 results live in [`proofs/Tangle.lean`](proofs/Tangle.lean)
55-
(Lean 4, ~570 LoC, no `sorry`, no `axiom`).
54+
All results live in [`proofs/Tangle.lean`](proofs/Tangle.lean)
55+
(Lean 4, no `sorry`, no `axiom`).
5656

5757
**Build oracle.** As of 2026-06-01 (PR closing TG-0, hyperpolymath/tangle#32),
5858
the file is verified at every push/PR by `.github/workflows/lean-proofs.yml`,
@@ -116,11 +116,13 @@ themselves proofs of the form "these are the rules"):
116116
- **`Expr`** — the AST (mirrors `compiler/lib/ast.ml`)
117117
- **`Ty`**`num`, `str`, `bool`, `word n`
118118
- **`IsValue`** — value predicate
119-
- **`HasType`** — typing judgment, 16 rules (`tNum`, `tStr`, `tBool`,
119+
- **`HasType`** — typing judgment, 26 rules: 13 base (`tNum`, `tStr`, `tBool`,
120120
`tIdentity`, `tBraid`, `tComposeWord`, `tTensorWord`, `tPipeline`,
121-
`tCloseWord`, `tAddNum`, `tEqWord`, `tEqNum`, `tEqStr`, plus the echo
122-
rules `tEchoClose`, `tLower`, `tResidue`)
123-
- **`Step`** — small-step semantics, 31 rules (26 base + 5 echo)
121+
`tCloseWord`, `tAddNum`, `tEqWord`, `tEqNum`, `tEqStr`); 4 echo-close
122+
(`tEchoClose`, `tLower`, `tResidue`, `tEchoVal`); 7 product+echo-binary
123+
(`tPair`, `tFst`, `tSnd`, `tEchoAdd`, `tEchoEqWord`, `tEchoEqNum`,
124+
`tEchoEqStr`); 2 let/var (`tVar`, `tLet`)
125+
- **`Step`** — small-step semantics, 57 rules: 27 base, 9 echo-close/lower/residue, 6 product, 11 echoAdd/echoEq, 2 let, 2 StepStar
124126

125127
These are the formal spec the OCaml implementation is meant to refine
126128
(see TG-3 below).
@@ -145,6 +147,11 @@ type system*.
145147
| `echoClose e` | `Word[n] → Echo (Word[n]) (Word[0])` | `echo-intro close` |
146148
| `lower e` | `Echo ρ τ → τ` — project to result (forget residue) | the collapse / `proj₂` |
147149
| `residue e` | `Echo ρ τ → ρ` — recover the witness braid | `proj₁` |
150+
| `pair(a, b)` | `α → β → α × β` — product introduction | `Echo.Pair` (product as residue carrier) |
151+
| `fst(e)` | `α × β → α` — first projection | `proj₁` |
152+
| `snd(e)` | `α × β → β` — second projection | `proj₂` |
153+
| `echoAdd(a, b)` | `Num → Num → Echo (Num × Num) Num` — addition with summand residue | `echo-intro add` |
154+
| `echoEq(a, b)` | `ρ → ρ → Echo (ρ × ρ) Bool` — equality with operand residue | `echo-intro eq` |
148155

149156
**Metatheory.** Progress, Preservation, Determinism, and Type Safety all
150157
cover `echoClose`/`lower`/`residue` (the inductions are exhaustive over
@@ -167,6 +174,27 @@ its residue `v` is.
167174

168175
Tracked as obligation **TG-10** in PROOF-NEEDS.md (landed).
169176

177+
## 2.6 OCaml implementation completeness
178+
179+
As of 2026-06-14 (PRs #45#46), the OCaml pipeline (`compiler/lib/`) covers the
180+
complete echo + product fragment described in §2.5:
181+
182+
| Layer | Echo/product coverage |
183+
|-------|-----------------------|
184+
| `ast.ml` | `EchoClose`, `Lower`, `Residue`, `Pair`, `Fst`, `Snd`, `EchoAdd`, `EchoEq` in `expr`; `TProd`, `TEcho` in `ty` |
185+
| `typecheck.ml` | 8 `infer_expr` rules matching Lean `HasType`; `pp_ty` made `rec` |
186+
| `eval.ml` | `VEcho`, `VPair` values; 8 `eval_expr` arms; `pp_value` made `rec` |
187+
| `lexer.mll` / `parser.mly` / `token.ml` | Keyword tokens + grammar productions for all 8 surface forms |
188+
| `pretty.ml` | Pretty-printers for all 8 forms |
189+
| `test_roundtrip.ml` | TG-4 round-trip property test: 36 entries including all 8 echo/product constructors |
190+
191+
**Build oracle**: `dune build` + `dune test` (548/548) green since PR #46. The
192+
pre-PR #46 `main` did not compile due to two `Warning 8` exhaustiveness gaps
193+
(both fixed: `strand_type_of_ty` in `typecheck.ml`; debug token printer in `bin/main.ml`).
194+
195+
**TG-3 gap remains**: the OCaml typechecker is not yet proven to refine `HasType`;
196+
the correspondence is validated by the test suite, not by a formal translation.
197+
170198
## 3. Remaining obligations (the narrative arc)
171199

172200
What's not yet proven, why it matters, and what assumption each rests on.
@@ -234,6 +262,9 @@ claim is unchecked.
234262

235263
### TG-4 — Pretty-print/parse round-trip
236264

265+
**Status: LANDED** (PR #46). `compiler/test/test_roundtrip.ml` extended with
266+
36 entries including all 8 echo/product constructors; 548/548 tests pass.
267+
237268
**Claim.** `parse(pretty e) = e` for every closed value `e`.
238269

239270
**Why valuable.** Free fuzz oracle. Also the foundation of any "IR
@@ -245,7 +276,7 @@ viewer" tooling that re-parses what `pretty` emitted.
245276
- [[A-TG-4.2]] Lexer never strips information needed by the parser
246277
(e.g. whitespace within braid literals).
247278

248-
**How to discharge.** Property test in `compiler/test/`.
279+
**How to discharge.** Property test in `compiler/test/` — discharged.
249280

250281
### TG-5 — `compositional.ml` rewriter preserves types
251282

PROOF-NEEDS.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,9 @@ and `proofs/Tangle.lean`:
4040
**Coverage:** the **let-free fragment** of core Tangle, comprising
4141
`Num`, `Str`, `Bool`, `Identity`, `BraidLit`, `Compose`, `Tensor`,
4242
`Pipeline`, `Close`, `Add`, `Eq`, plus the **echo-types fragment**
43-
(`EchoClose`, `Lower`, `Residue` with type former `Echo[ρ,τ]`). 16 typing
44-
rules, 31 step rules. All four theorems cover the echo fragment (TG-10).
43+
(`EchoClose`, `Lower`, `Residue`, `EchoAdd`, `EchoEq`) and the **product type**
44+
(`Pair`, `Fst`, `Snd` with type former `ρ × σ`). 26 typing rules, 57 step rules.
45+
All four theorems cover the echo fragment (TG-10).
4546

4647
## What remains
4748

@@ -52,13 +53,13 @@ Cross-referenced to [PROOF-NARRATIVE.md §3](PROOF-NARRATIVE.md#3-remaining-obli
5253
| TG-1 | Extend Progress/Preservation/Determinism/TypeSafety to `let`-binding | TP | Lean 4 | P1 | 3d | NOT STARTED (acknowledged in Tangle.lean header) |
5354
| TG-2 | Type checking is decidable: define `infer : Expr → Option Ty` proven equivalent to `HasType` | ALG | Lean 4 | P1 | 1d | NOT STARTED |
5455
| TG-3 | OCaml `typecheck.ml` refines the Lean `HasType` spec | TP | Lean 4 + translation validation | P1 | 5d | NOT STARTED |
55-
| TG-4 | Pretty-print/parse round-trip on closed values | INV | OCaml property test (cheap) | P2 | 4h | NOT STARTED |
56+
| TG-4 | Pretty-print/parse round-trip on closed values | INV | OCaml property test (cheap) | P2 | 4h | **LANDED** (PR #46 — OCaml property test in `compiler/test/test_roundtrip.ml`, 36 entries including 16 echo/product forms) |
5657
| TG-5 | `compositional.ml` (418 LoC) rewriter preserves types | TP | Lean 4 + OCaml test file | P2 | 3d | NOT STARTED (B6: no test file yet) |
5758
| TG-6 | WASM compilation preserves semantics (source eval ≡ wasm exec) | TP / ALG | Lean 4 bisimulation | P1 | 3w (research-grade) | NOT STARTED |
5859
| TG-7 | `Step.eqBraids` decides braid-group equivalence (not list equality) | ALG / DOM | OCaml + Lean 4 | P2 | 2w | NOT STARTED (current impl is soundness-floor, not completeness) |
5960
| TG-8 | Each dialect (braid-calculus, quantum-circuit, skein-algebra, string-diagram, virtual-knot) is a conservative extension of core | TP | Lean 4 per-dialect | P3 | 1w each | NOT STARTED |
6061
| TG-9 | LSP diagnostics are a subset of `HasType` failures (no LSP-only diagnostics) | INV | Audit + refactor | P2 | 1d | NOT STARTED |
61-
| TG-10 | Echo-types integrated into the type system: `Echo[ρ,τ]` former + `echoClose`/`lower`/`residue`, with Progress/Preservation/Determinism/TypeSafety extended to cover them and the non-injectivity / residue-recovery capstones proven | TP / DOM | Lean 4 | P1 || **LANDED** (`proofs/Tangle.lean` §ECHO-TYPES) |
62+
| TG-10 | Echo-types integrated into the type system: `Echo[ρ,τ]` former + `echoClose`/`lower`/`residue`/`echoAdd`/`echoEq` + product type (`pair`/`fst`/`snd`), with Progress/Preservation/Determinism/TypeSafety extended to cover them and the non-injectivity / residue-recovery capstones proven | TP / DOM | Lean 4 | P1 || **LANDED** (`proofs/Tangle.lean` §ECHO-TYPES) |
6263

6364
For full per-obligation statements, _why valuable_, and the
6465
assumptions each rests on, see PROOF-NARRATIVE.md.

docs/echo-types-ocaml-pipeline.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
<!--
2+
SPDX-License-Identifier: MPL-2.0
3+
Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
-->
5+
# Echo Types — OCaml Pipeline Integration
6+
7+
> **Status**: Complete (PRs #45, #46, merged 2026-06-14).
8+
> This page is the developer reference for the echo/product type integration
9+
> in the OCaml compiler pipeline. For the formal metatheory see
10+
> [PROOF-NARRATIVE.md §2.5](../PROOF-NARRATIVE.md) and
11+
> [`proofs/Tangle.lean` §ECHO-TYPES](../proofs/Tangle.lean).
12+
> For the cross-repo contract with QuandleDB see
13+
> [ECHO-TANGLEIR-THREADING.md](spec/ECHO-TANGLEIR-THREADING.md).
14+
15+
---
16+
17+
## 1. What are echo types?
18+
19+
Echo types make structured loss **recoverable at the type level**. Tangle's
20+
canonical lossy operation is `close : Word[n] → Word[0]`, which collapses any
21+
braid to the identity, discarding the word. An `Echo ρ τ` value is a pair:
22+
23+
- **result** (`τ`) — what the lossy operation produces
24+
- **residue** (`ρ`) — the pre-closure braid, retained in the type
25+
26+
The design mirrors `Echo f y := Σ (x : A), f x ≡ y` from
27+
`hyperpolymath/echo-types` (`Echo.agda`) in Tangle's simply-typed setting.
28+
29+
The **product type** `ρ × σ` serves as the residue carrier for binary lossy
30+
operations: `echoAdd` keeps both summands, `echoEq` keeps both operands.
31+
32+
---
33+
34+
## 2. Surface syntax
35+
36+
| Expression | Type | Meaning |
37+
|------------|------|---------|
38+
| `echoClose(e)` | `Word[n] → Echo (Word[n]) (Word[0])` | Close a braid, retaining the original as residue |
39+
| `lower(e)` | `Echo ρ τ → τ` | Project to the result (forget the residue) |
40+
| `residue(e)` | `Echo ρ τ → ρ` | Recover the witness braid |
41+
| `pair(a, b)` | `α → β → α × β` | Construct a product |
42+
| `fst(e)` | `α × β → α` | First projection |
43+
| `snd(e)` | `α × β → β` | Second projection |
44+
| `echoAdd(a, b)` | `Num → Num → Echo (Num × Num) Num` | Addition retaining summand pair as residue |
45+
| `echoEq(a, b)` | `ρ → ρ → Echo (ρ × ρ) Bool` | Equality retaining operand pair as residue |
46+
47+
---
48+
49+
## 3. OCaml pipeline layers
50+
51+
### 3.1 AST (`compiler/lib/ast.ml`)
52+
53+
```ocaml
54+
type expr =
55+
...
56+
| EchoClose of expr
57+
| Lower of expr
58+
| Residue of expr
59+
| Pair of expr * expr
60+
| Fst of expr
61+
| Snd of expr
62+
| EchoAdd of expr * expr
63+
| EchoEq of expr * expr
64+
65+
type ty =
66+
...
67+
| TProd of ty * ty (* ρ × σ — product residue carrier *)
68+
| TEcho of ty * ty (* Echo ρ τ *)
69+
```
70+
71+
### 3.2 Typechecker (`compiler/lib/typecheck.ml`)
72+
73+
Eight new `infer_expr` cases, all mirroring Lean `HasType`:
74+
75+
| OCaml rule | Lean rule | Type produced |
76+
|-----------|-----------|--------------|
77+
| `EchoClose e` | `tEchoClose` | `TEcho (TEcho(Word[n], inferred_width), TWord 0)` → simplified to `TEcho(ρ, TWord 0)` |
78+
| `Lower e` | `tLower` | `τ` (from `TEcho ρ τ`) |
79+
| `Residue e` | `tResidue` | `ρ` (from `TEcho ρ τ`) |
80+
| `Pair(a, b)` | `tPair` | `TProd(α, β)` |
81+
| `Fst e` | `tFst` | `α` (from `TProd α β`) |
82+
| `Snd e` | `tSnd` | `β` (from `TProd α β`) |
83+
| `EchoAdd(a, b)` | `tEchoAdd` | `TEcho(TProd(TNum, TNum), TNum)` |
84+
| `EchoEq(a, b)` | `tEchoEqWord/Num/Str` | `TEcho(TProd(ρ, ρ), TBool)` |
85+
86+
### 3.3 Evaluator (`compiler/lib/eval.ml`)
87+
88+
New value forms:
89+
90+
```ocaml
91+
type value =
92+
...
93+
| VEcho of value * value (* (residue, result) — Option B uniform form *)
94+
| VPair of value * value (* product value *)
95+
```
96+
97+
Echo values use the **Option B** uniform shape: `VEcho(residue, result)` in all
98+
cases. `echoClose` produces `VEcho(braid_value, VIdentity)`. `echoAdd` produces
99+
`VEcho(VPair(n1, n2), VNum(n1 + n2))`. `echoEq` produces `VEcho(VPair(v1, v2),
100+
VBool(v1 = v2))`.
101+
102+
### 3.4 Lexer / parser / tokens
103+
104+
Tokens (`compiler/lib/token.ml`):
105+
`ECHOCLOSE`, `LOWER`, `RESIDUE`, `PAIR`, `FST`, `SND`, `ECHOADD`, `ECHOEQ`
106+
107+
All 8 keywords are registered in the lexer (`lexer.mll`) and have dedicated
108+
grammar productions in `parser.mly` following the existing unary
109+
(`KW LPAREN expr RPAREN`) and binary (`KW LPAREN expr COMMA expr RPAREN`) patterns.
110+
111+
### 3.5 Pretty printer (`compiler/lib/pretty.ml`)
112+
113+
All 8 forms pretty-print to the same surface syntax that the parser accepts,
114+
satisfying the TG-4 round-trip obligation.
115+
116+
---
117+
118+
## 4. Round-trip guarantee (TG-4)
119+
120+
`compiler/test/test_roundtrip.ml` tests `parse(pretty(e)) = e` and
121+
`pretty(parse(pretty(parse(s)))) = pretty(parse(s))` for every constructor.
122+
123+
Echo/product entries:
124+
`echoClose`, `lower`, `residue`, `pair`, `fst`, `snd`, `echoAdd`, `echoEq`
125+
— 16 test cases (8 basic + 8 idempotent), all passing as of PR #46.
126+
127+
---
128+
129+
## 5. Proof coverage
130+
131+
The formal spec (`proofs/Tangle.lean`) covers the complete echo+product fragment:
132+
133+
| Lean theorem | Coverage |
134+
|-------------|----------|
135+
| `T-Progress` | All 8 echo/product expression forms |
136+
| `T-Preservation` | All 8 echo/product expression forms |
137+
| `T-Determinism` | All 8 echo/product expression forms |
138+
| `T-TypeSafety` | Corollary (progress + preservation) |
139+
| `echo_lower_collapses` | Every closed braid lowers to `identity` |
140+
| `echo_residue_recovers` | `residue(echoClose(braid[gs])) →* braid[gs]` |
141+
| `echo_distinguishes_collapsed` | Distinct braids keep distinct residues after `lower` |
142+
| `echo_roundtrip_typed` | Round-trip is well-typed |
143+
144+
The OCaml typechecker is not yet formally proven to refine `HasType` (TG-3,
145+
open). Correspondence is validated by the test suite (548/548 passing).
146+
147+
---
148+
149+
## 6. Known gaps and future work
150+
151+
| Gap | Tracking |
152+
|-----|----------|
153+
| TG-3: formal OCaml–Lean refinement proof | PROOF-NEEDS.md TG-3 |
154+
| TG-1: type safety extended to `let` | PROOF-NEEDS.md TG-1 |
155+
| TangleIR: thread echo residue into schema | ECHO-TANGLEIR-THREADING.md |
156+
| `echoClose` in WASM backend | tangle-wasm (not yet implemented) |

0 commit comments

Comments
 (0)