|
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> |
3 | 3 |
|
4 | | -This document backs up the claims made in README with evidence and rationale. |
| 4 | += EXPLAINME: Tangle |
5 | 5 |
|
6 | | -== What Is This? |
| 6 | +== "A Turing-Complete Topological Programming Language" |
7 | 7 |
|
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 | +____ |
9 | 14 |
|
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. |
11 | 20 |
|
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. |
13 | 25 |
|
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 |
16 | 29 |
|
17 | | -=== Architecture |
| 30 | +| `src/tangle.ebnf` |
| 31 | +| Core grammar exists and is specified in EBNF |
18 | 32 |
|
19 | | -Architecture decisions are documented in `.machine_readable/` checkpoint files. |
| 33 | +| `docs/spec/FORMAL-SEMANTICS.md` |
| 34 | +| Formal denotational semantics are documented |
20 | 35 |
|
21 | | -== Alternatives Considered |
| 36 | +| `src/abi/` |
| 37 | +| Idris2 ABI definitions for type-level guarantees |
22 | 38 |
|
23 | | -(To be filled in as the project matures.) |
| 39 | +| `src/rust/` |
| 40 | +| Rust implementation of the compiler pipeline |
24 | 41 |
|
25 | | -== Proof of Claims |
| 42 | +| `ffi/` |
| 43 | +| Zig FFI layer per hyperpolymath ABI/FFI standard |
26 | 44 |
|
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