Skip to content

docs: de-conflate Tangle from KRL; drop two dead Jekyll Pages workflows#78

Merged
hyperpolymath merged 3 commits into
mainfrom
fix/part1-deconflation
Jul 21, 2026
Merged

docs: de-conflate Tangle from KRL; drop two dead Jekyll Pages workflows#78
hyperpolymath merged 3 commits into
mainfrom
fix/part1-deconflation

Conversation

@hyperpolymath

Copy link
Copy Markdown
Owner

The tangle half of a coordinated two-repo de-conflation pass. The krl half is hyperpolymath/krl#53 (merged) and hyperpolymath/krl#54.

The three projects are separate

Tangle is a general language for knot mathematics — topological, algebraic, geometric, logical. QuandleDB is a knot database. KRL is QuandleDB's resolution language, developed jointly with it. They share a subject matter, not an architecture.

Documentation here presented Tangle as the substrate of a KRL compilation stack. That is false in both directions, and the connecting layer does not exist:

TangleIR appears in NO source file in this repository — 0 hits across .rs, .zig and .leanand in NO source file in the KRL implementation. It existed only in prose, in both repos.

The relationship between the projects is left intact. What is removed is a claimed architectural dependency that was never built.

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 line.
  • Removed the KRL → TangleIR → Tangle core → QuandleDB + Skein.jl ladder.
  • Removed the == KRL — Knot Resolution Language section, which restated KRL's four operations as though KRL were this project's surface language.
  • Strengthened the formal core with a result rather than a claim (below).
  • Added an explicit note that only the Lean proofs are CI-gated.

The formal core is real — and now verified

I ran the repository's own documented oracle:

$ cd proofs && lean Tangle.lean
$ echo $?
0
Check Result
lean Tangle.lean (pinned leanprover/lean4:v4.14.0) exit 0, no errors
sorry count 0
axiom count 0
import lines 0 — self-contained, no Mathlib
progress, preservation, determinism, type_safety, infer_sound, infer_complete, infer_iff_hasType all present with real proof terms

This is worth stating precisely: an axiom stub compiles cleanly while proving nothing, so "the Lean build is green" and "the theorems are proved" are different claims in general. Here they coincide, and that was checked rather than assumed. This is Tangle's strongest asset and the README now leads with it.

AFFIRMATION.adoc — erratum, not edit

An affirmation is a dated claim about a past state (102499d, 2026-06-19); amending it in place would falsify a record. So the original text is untouched and an erratum is appended. It corrects the "maintainer-confirmed" KRL → TangleIR → VerisimCore → Skein/QuandleDB stack, and flags that the quotable one-line characterisation shouldn't be quoted while it calls Tangle "the … TangleIR of the KRL stack".

It also 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 is now closed, with command and exit code recorded.

READINESS.md — Grade C → D

Grade C means self-validated in the home context; the D → C trigger is "dogfood it hard in the home context." The assessment cited exactly one piece of dogfooding evidence:

Dogfooding: Used internally as host for the KRL (Knot Resolution Language) DSL

That is false — KRL is not built on Tangle. With it withdrawn, C is unsupported. Two further corrections:

  • "CI: Clean" was falsemain was failing Governance and both Jekyll workflows.
  • The test suites are not run by CI. Eight OCaml test files exist under compiler/test/, but no workflow invokes dune or cargo test.

The cheapest available uplift is named explicitly: add a workflow running dune build && dune test. Eight suites already exist and nothing executes them.

dialects/README.md

  • Removed KRL from the dialect table — it was listed as a dialect that had "graduated", and it was never a Tangle dialect.
  • Replaced the dead absolute path /var/mnt/eclipse/repos/krl (another machine) with the GitHub URL.
  • Dropped "wire through to TangleIR" from the maturation pattern.

Workflows — two deleted

jekyll.yml and jekyll-gh-pages.yml are GitHub's sample Jekyll workflows. This repo has no _config.yml and no Gemfile — there is no Jekyll site to build, so both fail on every push. pages.yml (Ddraig SSG, #73) is the real one; three workflows were competing for the same Pages deployment.

⚠️ Owner action — GitHub Pages is not enabled

pages.yml will still fail at the deploy step after this PR. Its build succeeds and certifies a11y, but:

GET /repos/hyperpolymath/tangle/pages  ->  404 Not Found

which surfaces as HttpError: Not Found / Creating Pages deployment failed. The same is true of hyperpolymath/krl. Pages needs enabling with source = GitHub Actions on both. That publishes a public site, so I've left it to you rather than doing it.

Verified on this branch

actionlint 0 errors · asciidoctor renders README.adoc and AFFIRMATION.adoc clean · lean Tangle.lean exit 0

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.
…tandards pins

Both Governance failures on this branch are the same two faults found and fixed
in krl (#56), so the same remedy applies here.

Workflow security linter

  * pages.yml carried no SPDX header. Every other workflow in the repo has one;
    this was the only omission. Added.
  * pages.yml used floating tags where every other workflow pins by SHA:
      actions/checkout@v7             -> 3d3c42e5... # v7
      actions/upload-pages-artifact@v5 -> fc324d35... # v5
      actions/deploy-pages@v5         -> cd2ce8fc... # v5
    Kept on the same major versions, so this changes pinning only, not
    behaviour.

Check Workflow Staleness

  * governance-reusable.yml, hypatia-scan-reusable.yml and
    scorecard-reusable.yml were pinned at d7c22711e830 — 63 commits / 24 days
    behind standards HEAD, outside the gate's recency window. Refreshed to
    f9dca6ded2cad8ab54044c1cb0489b558ae2682b (full 40-char SHA).

Not touched: mirror-reusable.yml (d135b05) and secret-scanner-reusable.yml
(c65436e). Neither was flagged, and the secret-scanner pin should not move
independently of the gitleaks allowlist work.

Verified: all workflows carry an SPDX header; no unpinned third-party actions
remain; actionlint 0 errors.
Refreshing hypatia-scan-reusable.yml to standards HEAD turned the run into a
startup_failure — zero jobs, no log. The newer reusable declares

  permissions:
    contents: read
    security-events: write

because it uploads SARIF, while the caller granted security-events: read. A
called workflow cannot escalate beyond its caller's grant, so GitHub rejects
the whole run at parse time rather than failing a job.

This is the failure mode where refreshing a pin BREAKS a caller that was
previously fine: the old pin needed only read. Checked the other two bumped
reusables the same way — governance-reusable and scorecard-reusable both
declare only contents: read, which the callers already grant, so no change
was needed there.
@hyperpolymath
hyperpolymath marked this pull request as ready for review July 21, 2026 17:13
@hyperpolymath
hyperpolymath merged commit f559826 into main Jul 21, 2026
23 checks passed
@hyperpolymath
hyperpolymath deleted the fix/part1-deconflation branch July 21, 2026 17:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant