Skip to content

Commit e2e8d96

Browse files
hyperpolymathclaude
andcommitted
fix: EXPLAINME.adoc — quote README claims, brief format, evidence table
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 7fd0962 commit e2e8d96

1 file changed

Lines changed: 38 additions & 15 deletions

File tree

EXPLAINME.adoc

Lines changed: 38 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,50 @@
1-
= Tangle — EXPLAINME
2-
:toc: preamble
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
33

4-
This document backs up the claims made in README with evidence and rationale.
4+
= EXPLAINME: Tangle
55

6-
== What Is This?
6+
== "A Turing-Complete Topological Programming Language"
77

8-
Tangle is a hyperpolymath project. See README.adoc for usage.
8+
[quote, README.adoc]
9+
____
10+
TANGLE is an experimental, Turing-complete, topologically inspired programming
11+
language where programs are represented as tangles -- isotopy classes of braided
12+
strands in 3D space.
13+
____
914

10-
== Why These Choices?
15+
Programs are braids; equivalence is isotopy; crossings define operations.
16+
The type system separates matchable braid words (`Word[n]`) from extensional
17+
tangle morphisms (`Tangle[A,B]`), with implicit coercion between them.
18+
See link:docs/spec/FORMAL-SEMANTICS.md[Formal Semantics] for the full
19+
denotational model.
1120

12-
=== Language
21+
**Caveat:** This is an experimental research language. The compiler is
22+
early-stage and the formal semantics are still being refined. Turing
23+
completeness is established via recursive definitions and pattern matching,
24+
not via a traditional proof.
1325

14-
The language(s) used in this project were chosen per the hyperpolymath
15-
language policy (see CLAUDE.md for the full list of allowed/banned languages).
26+
[cols="2,3", options="header"]
27+
|===
28+
| Path | Proves
1629

17-
=== Architecture
30+
| `src/tangle.ebnf`
31+
| Core grammar exists and is specified in EBNF
1832

19-
Architecture decisions are documented in `.machine_readable/` checkpoint files.
33+
| `docs/spec/FORMAL-SEMANTICS.md`
34+
| Formal denotational semantics are documented
2035

21-
== Alternatives Considered
36+
| `src/abi/`
37+
| Idris2 ABI definitions for type-level guarantees
2238

23-
(To be filled in as the project matures.)
39+
| `src/rust/`
40+
| Rust implementation of the compiler pipeline
2441

25-
== Proof of Claims
42+
| `ffi/`
43+
| Zig FFI layer per hyperpolymath ABI/FFI standard
2644

27-
(Link formal verification results from the `proven` repo where applicable.)
45+
| `conformance/`
46+
| Conformance test suite for language behaviour
47+
48+
| `examples/`
49+
| Worked examples demonstrating language features
50+
|===

0 commit comments

Comments
 (0)