Skip to content

Commit 558f631

Browse files
committed
docs: de-conflate Tangle from KRL; drop two dead Jekyll Pages workflows
Tangle, KRL and QuandleDB are three separate projects that share a subject matter. Documentation here presented Tangle as the substrate of a KRL compilation stack, which is not true in either direction. README.adoc * Retitled from "Tangle / KRL — Topological Programming Language" to "Tangle — a general language for knot mathematics". Removed "Tangle (via KRL — Knot Resolution Language) is ..." from the opening sentence and the "Tangle/KRL" framing from the status and summary sections. * Removed the architecture ladder KRL -> TangleIR -> Tangle core -> QuandleDB + Skein.jl. `TangleIR` appears in NO source file in this repository (0 hits across .rs, .zig and .lean) and in NO source file in the KRL implementation. It existed only in prose, in both repositories. * Removed the "== KRL — Knot Resolution Language" section, which restated KRL's four operations as though KRL were this project's surface language. Replaced with a "Relationship to KRL and QuandleDB" section stating the three projects' actual boundaries. The relationship is left intact — what is removed is a claimed architectural dependency that does not exist. * Strengthened the formal-core section with a result rather than a claim: the repository's own oracle, `cd proofs && lean Tangle.lean`, was executed on 2026-07-21 and exits 0. The proofs are self-contained (Tangle.lean has no import lines, so no Mathlib) and contain 0 `sorry` and 0 `axiom` across 2,128 lines, with progress, preservation, determinism, type_safety, infer_sound, infer_complete and infer_iff_hasType all carrying real proof terms. "Builds" and "proved" coincide here, which is not automatic. * Added an explicit note that only the Lean proofs are CI-gated: the OCaml compiler, the Rust components and the Zig components are built by no workflow. AFFIRMATION.adoc * Appended an erratum rather than editing the text. An affirmation is a dated claim about a past state; amending it in place would falsify a record. * Corrects the "maintainer-confirmed" stack KRL -> TangleIR -> VerisimCore -> Skein/QuandleDB, and flags that the quotable one-line characterisation should not be quoted while it describes Tangle as "the ... TangleIR of the KRL stack". * Discharges one of the affirmation's own acknowledged gaps. It recorded "OCaml + Lean not run (absent)" and concluded "structure + the repo's proof records are confirmed, not a fresh green build". The Lean half of that gap is now closed, with the command and exit code recorded. READINESS.md — grade C -> D * Grade C means self-validated in the home context, and the D -> C trigger is "dogfood it hard in the home context". The assessment cited exactly one piece of dogfooding evidence: "Used internally as host for the KRL DSL". That is false, so C is unsupported. * "CI: Clean" was also false — main was failing Governance and both Jekyll Pages workflows. * The 8 OCaml test suites under compiler/test/ are real but are run by no workflow, so their passing state is unverified by this repo's own CI. * Recorded the verified Lean result as the evidence that does hold, and named the cheapest uplift: add a workflow that runs `dune build && dune test`. dialects/README.md * Removed KRL from the dialect table. It was listed as a dialect that had "graduated" to its own repo; it was never a Tangle dialect. * Replaced the dead absolute path /var/mnt/eclipse/repos/krl with the GitHub URL. * Dropped "wire through to TangleIR" from the maturation pattern, and noted that no dialect has yet made that journey, so there is no precedent. * Softened the multi-DSL-host claim: the sketches set out what such a host would cover, but nothing is implemented and nothing is built on Tangle, so they do not yet evidence it. Workflows * Deleted .github/workflows/jekyll.yml and .github/workflows/jekyll-gh-pages.yml. Both are GitHub's sample Jekyll workflows; this repository has no _config.yml and no Gemfile, so there is no Jekyll site to build and both fail on every push to main. pages.yml (Ddraig SSG, landed in #73) is the real one, and three workflows were competing for the same Pages deployment. NOTE: pages.yml will still fail at the deploy step. Its build succeeds and certifies a11y, but GitHub Pages is not enabled for this repository — /repos/hyperpolymath/tangle/pages returns 404, which surfaces as "HttpError: Not Found / Creating Pages deployment failed". That is a repository setting, not a code change, and is left for the owner.
1 parent a89fd47 commit 558f631

6 files changed

Lines changed: 299 additions & 273 deletions

File tree

.github/workflows/jekyll-gh-pages.yml

Lines changed: 0 additions & 48 deletions
This file was deleted.

.github/workflows/jekyll.yml

Lines changed: 0 additions & 62 deletions
This file was deleted.

AFFIRMATION.adoc

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -220,3 +220,67 @@ un-run toolchains stated rather than implied.
220220
`-S`; the signed git commit over this content, at the SHA above, is the
221221
authoritative form.
222222
* *Signed-off-date:* (fill on signing)
223+
224+
'''
225+
226+
== Erratum — 2026-07-21
227+
228+
This section corrects the affirmation above. The original text is left intact:
229+
an affirmation is a dated claim about a past state, and amending it in place
230+
would falsify a record. Two of its claims have since been shown to be wrong,
231+
and one of its acknowledged gaps has since been closed.
232+
233+
=== Correction 1 — the stack does not exist
234+
235+
The affirmation records, as *maintainer-confirmed*, the ladder:
236+
237+
[literal]
238+
KRL -> TangleIR -> VerisimCore -> Skein/QuandleDB
239+
240+
`TangleIR` does not exist. The identifier appears in *no source file* in this
241+
repository (0 hits across `.rs`, `.zig` and `.lean`) and in *no source file* in
242+
the KRL implementation at `quandledb/server/krl/`. It existed only in prose, in
243+
both repositories, and has been removed from `README.adoc`.
244+
245+
Nor is KRL a surface language for Tangle. KRL is QuandleDB's resolution
246+
language, developed jointly with QuandleDB; it neither compiles to nor depends
247+
on Tangle. The three projects share a subject matter, not an architecture.
248+
249+
The confirmation recorded on 2026-06-19 was a confirmation of the README's
250+
diagram, and that diagram was wrong. Nothing here suggests bad faith — the
251+
affirmation is careful, and states plainly which of its checks were not run.
252+
253+
=== Correction 2 — the "one-line characterisation" should not be quoted as-is
254+
255+
The characterisation invites quotation. It should not be quoted while it
256+
describes Tangle as "the proven type-safe small-step core + TangleIR of the KRL
257+
stack". Everything else in that sentence survives: the OCaml compiler, the Rust
258+
LSP/WASM targets, the Lean 4 proofs and the five dialects are all real.
259+
260+
=== Discharge — the Lean proofs have now been run
261+
262+
The affirmation states: *"OCaml + Lean not run (absent)"*, and concludes that
263+
*"structure + the repo's proof records are confirmed, not a fresh green build"*.
264+
265+
That gap is now closed for Lean. On 2026-07-21 the repository's own documented
266+
oracle was executed:
267+
268+
[source,console]
269+
----
270+
$ cd proofs && lean Tangle.lean
271+
$ echo $?
272+
0
273+
----
274+
275+
Exit 0, no errors, using the pinned toolchain from `proofs/lean-toolchain`
276+
(`leanprover/lean4:v4.14.0`). The proofs are self-contained — `Tangle.lean` has
277+
no `import` lines at all, so no Mathlib — and contain *zero* occurrences of
278+
`sorry` and *zero* `axiom` declarations across 2,128 lines. `progress`,
279+
`preservation`, `determinism`, `type_safety`, `infer_sound`, `infer_complete`
280+
and `infer_iff_hasType` are all present with real proof terms.
281+
282+
This matters because "the Lean build is green" and "the theorems are proved" are
283+
not the same claim in general: an `axiom` stub compiles cleanly while proving
284+
nothing. Here they coincide, and that was checked rather than assumed.
285+
286+
The OCaml compiler remains unbuilt — no workflow in this repository builds it.

READINESS.md

Lines changed: 93 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -6,45 +6,116 @@ Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
66

77
# Component Readiness — Tangle (language)
88

9-
**Current Grade:** C
10-
**Assessed:** 2026-04-05
9+
**Current Grade:** D
10+
**Assessed:** 2026-07-21 (demoted C → D)
1111
**Standard:** [CRG v2.0 STRICT](../standards/component-readiness-grades/)
1212

13-
## Grade rationale (evidence for C)
13+
## Why the grade moved C → D
1414

15-
Works reliably on own project + annotated. Tangle is a Turing-complete
16-
topological programming language with a compiler, LSP, and wasm backend.
15+
Grade C means *self-validated in the home context*; the D → C promotion trigger
16+
is *"dogfood it hard in the home context."* The previous assessment cited
17+
exactly one piece of dogfooding evidence:
1718

18-
### Evidence
19+
> **Dogfooding:** Used internally as host for the KRL (Knot Resolution Language) DSL
1920
20-
- **Tests:** 6 dune test suites (parser, typecheck, eval, e2e, property, compositional)
21-
- **Annotation:** 8 per-directory READMEs across compiler/, lib/, examples/, docs/
22-
- **Dogfooding:** Used internally as host for the KRL (Knot Resolution Language) DSL
23-
- **RSR compliance:** 0-AI-MANIFEST.a2ml, `.machine_readable/6a2/`, 14+ workflows, SECURITY/CONTRIBUTING/CODE_OF_CONDUCT, EXPLAINME.adoc, TEST-NEEDS.md, PROOF-NEEDS.md
24-
- **Formal proofs:** Lean 4 proofs for progress, preservation, determinism
25-
- **WASM backend:** Compositional PD compiler with wasm codegen
26-
- **CI:** Clean; panic-attack assail 0 findings
21+
**That is not true.** KRL is not built on Tangle. KRL is QuandleDB's resolution
22+
language, developed jointly with QuandleDB; it neither compiles to nor depends
23+
on Tangle, and the `TangleIR` layer that was supposed to connect them does not
24+
exist in any source file in either repository. See the erratum in
25+
`AFFIRMATION.adoc`.
26+
27+
With that claim withdrawn there is no dogfooding evidence, so C is not
28+
supported. Two further corrections to the previous assessment:
29+
30+
- **"CI: Clean" was false.** At the time of this assessment `main` was failing
31+
Governance and both Jekyll Pages workflows.
32+
- **The test suites are not run by CI.** Eight OCaml test files exist under
33+
`compiler/test/`, but no workflow in this repository invokes `dune` or
34+
`cargo test`. Their passing state is unverified by this repository's own CI.
35+
36+
This is a correction to the record, not a regression in the work. The formal
37+
core in particular got *stronger* this cycle — see below.
38+
39+
---
40+
41+
## Grade rationale (evidence for D)
42+
43+
Grade D: *"works on some inputs, some cases, or some configurations, but not
44+
systematically … either needs to be narrowed in scope so that its documented
45+
capabilities match its actual capabilities, or needs the inconsistencies
46+
fixed."* Narrowing the documented scope is exactly what this revision does.
47+
48+
### Verified evidence
49+
50+
| Artefact | Check | Result |
51+
|---|---|---|
52+
| `proofs/Tangle.lean` | `cd proofs && lean Tangle.lean` (the repo's own documented oracle) | **exit 0, no errors** |
53+
| `proofs/Tangle.lean` | `sorry` count | **0** |
54+
| `proofs/Tangle.lean` | `axiom` count | **0** |
55+
| Theorems | `progress`, `preservation`, `determinism`, `type_safety`, `infer_sound`, `infer_complete`, `infer_iff_hasType` | all present with real proof terms |
56+
| Dependencies | `import` lines in `Tangle.lean` | **0** — self-contained, no Mathlib |
57+
58+
Run on 2026-07-21 with the pinned toolchain (`leanprover/lean4:v4.14.0`). This
59+
is worth stating precisely: a Lean file full of `axiom` stubs compiles cleanly
60+
while proving nothing, so "the build is green" and "the theorems are proved" are
61+
different claims. Here they coincide, and that was checked.
62+
63+
### Present but unverified
64+
65+
- **OCaml compiler** (`compiler/`) — lexer, parser, AST, typechecker, evaluator,
66+
pretty-printer, REPL, braid equivalence, LSP and WASM targets. Not built by
67+
any workflow.
68+
- **Test suites** — 8 files under `compiler/test/` (`test_parser`,
69+
`test_typecheck`, `test_eval`, `test_e2e`, `test_property`,
70+
`test_compositional`, `test_check`, `test_roundtrip`) plus `tg3`/`tg5`/`tg7`/
71+
`tg8` directories. Not run by any workflow.
72+
- **Rust / Zig components** — 18 `.rs`, 3 `.zig`. Not built by any workflow.
73+
- **Five dialects** — grammar sketches only.
74+
75+
### Structural evidence
76+
77+
- Per-directory README annotation across `compiler/`, `dialects/`, `docs/`.
78+
- RSR compliance: `0-AI-MANIFEST.a2ml`, `.machine_readable/6a2/`, workflows,
79+
SECURITY / CONTRIBUTING / CODE_OF_CONDUCT, `EXPLAINME.adoc`, `TEST-NEEDS.md`,
80+
`PROOF-NEEDS.md`.
81+
82+
---
2783

2884
## Gaps preventing higher grades
2985

86+
### Blocks C (self-validated in the home context)
87+
88+
1. **No CI gate on the implementation.** The OCaml compiler, its 8 test suites,
89+
and the Rust and Zig components are not built or run by any workflow. Until
90+
they are, "works reliably" is not an evidenced claim. This is the single
91+
highest-value fix available to this repository.
92+
2. **No dogfooding.** Nothing is currently built on Tangle. The previous claim
93+
to the contrary was false.
94+
3095
### Blocks B (6+ diverse external targets)
96+
3197
- No external language users outside hyperpolymath.
32-
- KRL is the only DSL built on Tangle so far — need 5 more distinct domain DSLs
33-
to demonstrate the host-language claim.
3498
- No external submissions to language research venues confirming the phase
3599
separation or compositional PD model.
36100

37101
### Blocks A
102+
38103
- Requires B first.
39104

40-
## What to do for B
105+
---
106+
107+
## What to do next
41108

42-
1. Build 5 more DSLs on top of Tangle (not just KRL) — e.g. a braid-group
43-
calculus, a category-theory calculus, a quantum-circuit calculus.
44-
2. Get external feedback on the surface syntax and compiler from language
45-
researchers.
46-
3. Track the 6 targets here.
109+
1. **Add a workflow that runs `dune build && dune test`.** Eight test suites
110+
already exist; nothing executes them. This is the cheapest available uplift
111+
and is a precondition for any claim above D.
112+
2. Add a workflow that builds the Rust and Zig components.
113+
3. Build something real on Tangle, in its own right — a braid-group calculus, a
114+
category-theory calculus, a quantum-circuit calculus. The five dialects are
115+
the natural candidates and currently exist only as grammar sketches.
116+
Note that this must be genuine dogfooding of *Tangle*; KRL does not count and
117+
never did.
47118

48119
## Review cycle
49120

50-
Reassess per release. Next review: on any compiler/LSP/wasm behavioural change.
121+
Reassess when the compiler is built and its tests are run by CI.

0 commit comments

Comments
 (0)