|
| 1 | +// SPDX-License-Identifier: CC-BY-SA-4.0 |
| 2 | +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk> |
| 3 | += AFFIRMATION — Skein.jl, as of 2026-06-19 |
| 4 | +:toc: macro |
| 5 | +:toclevels: 2 |
| 6 | + |
| 7 | +_the No-Bullshit file: what we affirm was true and checkable at this moment_ |
| 8 | + |
| 9 | +[NOTE] |
| 10 | +==== |
| 11 | +*Genre.* An *affirmation* is a solemn declaration of the truth of a statement, |
| 12 | +made by someone who _declines to swear an oath_ — our truth-as-best-believed at |
| 13 | +a stamped instant, binding on our honesty, not a claim of infallibility. It is |
| 14 | +not the README and not the EXPLAINME: |
| 15 | +
|
| 16 | +[cols="1,3,2",options="header"] |
| 17 | +|=== |
| 18 | +| File | Answers | Tense |
| 19 | +| `README.adoc` | _Where is this going, and why?_ — Skein.jl's purpose and steering | future / aspirational |
| 20 | +| `EXPLAINME.adoc` | _How is it built, and what's the evidence?_ | descriptive / mechanism |
| 21 | +| *`AFFIRMATION.adoc`* (this file) | _What can we honestly affirm was *true and checkable* at a stamped moment?_ | a frozen instant, falsifiable |
| 22 | +|=== |
| 23 | +
|
| 24 | +Every repo in the estate carries one, per the 2026-06-19 estate rule. |
| 25 | +==== |
| 26 | + |
| 27 | +toc::[] |
| 28 | + |
| 29 | +== What this is, and how it is designed to work |
| 30 | + |
| 31 | +*What it is.* A short, dated, jointly-signed snapshot of what we can _honestly |
| 32 | +and verifiably_ claim about the Skein.jl repo at one exact commit. |
| 33 | + |
| 34 | +*How it is designed to work.* |
| 35 | + |
| 36 | +. *Ground truth, not memory.* Every gate result below was produced by _running |
| 37 | + the check this session_. *Material caveat (read it):* `just` is absent, so the |
| 38 | + `contractiles/` Must/Trust logic was run *as bash*; and *`julia` is absent*, so |
| 39 | + the Julia package and its test suite **were not executed** — see |
| 40 | + <<Outstanding / not-run>>. |
| 41 | +. *A frozen anchor.* The file names the exact commit SHA, branch, and toolchain |
| 42 | + (see <<Verifiable anchor>>). |
| 43 | +. *A real signature.* Authoritatively landed by the maintainer's *signed git |
| 44 | + commit*. The AI engineering party *cannot* GPG-sign and does not claim to. |
| 45 | + |
| 46 | +*We are fallible.* Best honest belief, not a proof of its own correctness. |
| 47 | + |
| 48 | +== The epistemic contract |
| 49 | + |
| 50 | +This document records our *best joint belief* at the timestamp below. *No |
| 51 | +intentional overclaim:* where a check passed we say "PASS"; where the toolchain |
| 52 | +was *absent* we say "not run", never "passed"; where the repo self-grades low we |
| 53 | +report that grade. |
| 54 | + |
| 55 | +*Standing invitation to refute.* Reproduce <<reproduce>> at the stamped commit |
| 56 | +and tell us where the discrepancy is. |
| 57 | + |
| 58 | +== Verifiable anchor |
| 59 | + |
| 60 | +[cols="1,3"] |
| 61 | +|=== |
| 62 | +| *Repo* | `hyperpolymath/Skein.jl` — the *computational / backend engine* of the KRL stack (computes invariants + equivalence checks; embedded SQLite store) |
| 63 | +| *Branch* | `claude/practical-newton-9eFe2` (feature branch, based on the current `origin/main` which already carries the merged #20 grounding + #21 CI work) |
| 64 | +| *Commit (HEAD)* | `ac5daca08a59dc70ae2e5b5da49d44d311601c25` |
| 65 | +| *Permalink* | https://github.com/hyperpolymath/Skein.jl/tree/ac5daca08a59dc70ae2e5b5da49d44d311601c25 |
| 66 | +| *Verified* | 2026-06-19 (checks run this session; precise UTC second not captured — date, not claimed instant) |
| 67 | +| *Working-tree delta* | Clean (`git status --porcelain` empty) at verification, except this untracked `AFFIRMATION.adoc`. |
| 68 | +| *Toolchain (present)* | `git`, `Agda 2.6.3`. *Absent this session:* `just`, `julia`, `deno`. |
| 69 | +| *Run method* | `contractiles/` Must/Trust logic + RSR checks run as bash. *Julia package/tests not executed* (no `julia`). |
| 70 | +| *HEAD commit signature* | *Not signed by the AI party.* Authoritative signature is the maintainer's signed commit that lands this file. |
| 71 | +|=== |
| 72 | + |
| 73 | +== Companion documents and repo metadata (cross-check) |
| 74 | + |
| 75 | +* *`README.adoc`* — present and *cleanly instantiated*: title `= Skein.jl`. |
| 76 | +* *`EXPLAINME.adoc`* — present and *cleanly instantiated*: `= Skein.jl — Show Me |
| 77 | + The Receipts`. |
| 78 | +* *`Project.toml`* — `name = "Skein"`, `version = "0.3.1"`. |
| 79 | +* *`0-AI-MANIFEST.a2ml`* — present. *REUSE-compliant* (`REUSE.toml` + `LICENSES/`). |
| 80 | +* *Template residue* — *2 files* with `{{PLACEHOLDER}}` tokens; *6 files* |
| 81 | + reference the `rsr-template-repo` lineage. The `Justfile` itself is clean. |
| 82 | + Minor instantiation debt — noted, not hidden. |
| 83 | +* *GitHub repo description / topics* — *not fetched this session* (no `gh`). |
| 84 | + |
| 85 | +== The honest state (one breath) |
| 86 | + |
| 87 | +Skein.jl is a *real, shipping* Julia knot-theory engine — `Skein` v0.3.1, ~2522 |
| 88 | +lines across `src/` (`types`, `polynomials`, `invariants`, `storage`, `query`, |
| 89 | +`import_export`, `knot_table`, plus `abi/` and `backends/`), *13 package |
| 90 | +extensions* (accelerator backends: CUDA / Metal / ROCm / TPU / NPU / FPGA / QPU / |
| 91 | +VPU / PPU / DSP / Math / Crypto / KnotTheory), and a real test suite. It is the |
| 92 | +*computational/backend engine* of the KRL stack (grounding merged in #20), is |
| 93 | +cleanly instantiated and REUSE-compliant, and the `MUST`/`TRUST` gates pass. The |
| 94 | +honest limits are about *assurance*, not scaffolding: it self-grades READINESS |
| 95 | +*C*, its storage obligations are *example/property-tested* rather than proven, and |
| 96 | +*its Julia test suite was not run this session* (no `julia`). |
| 97 | + |
| 98 | +== What is solid (and how we checked) |
| 99 | + |
| 100 | +* *MUST/TRUST-style checks — PASS.* Run as bash from `contractiles/`: LICENSE |
| 101 | + present; no banned `Dockerfile`/`Makefile`; SPDX headers on a sampled 150 `.jl` |
| 102 | + files (0 unheadered); LICENSE carries an SPDX/MPL identifier; no `.env` / |
| 103 | + `credentials.json` committed. |
| 104 | +* *Clean instantiation + REUSE compliance.* README + EXPLAINME carry the real |
| 105 | + project name; `REUSE.toml` + `LICENSES/` present. |
| 106 | +* *Real, substantial content.* A working Julia engine: `src/Skein.jl` plus the |
| 107 | + invariant/persistence modules (~2522 lines); 13 `ext/Skein*Ext.jl` package |
| 108 | + extensions; a real test tree (`test/runtests.jl`, `canonical_gauss_test.jl`, |
| 109 | + `e2e_test.jl`, `knot_theory_ext_test.jl`, `property_test.jl`). This is shipped |
| 110 | + engineering at version 0.3.1, not a template skeleton. |
| 111 | + |
| 112 | +== Known-incomplete but honestly fenced (loud, never silent) |
| 113 | + |
| 114 | +* *READINESS grade `C`.* `READINESS.md` self-assesses *Current Grade: C* — |
| 115 | + reported as-is. |
| 116 | +* *Obligations are tested, not proved.* `PROOF-NEEDS.md` records the storage/ |
| 117 | + schema obligations as *"tested by example; not proved for arbitrary |
| 118 | + databases"*, *"tested for each filter type … no exhaustive [proof]"*, *"tested |
| 119 | + on small examples"*. No claim of formal proof. |
| 120 | +* *The 13 accelerator extensions are present as code, not exercised here.* Their |
| 121 | + existence is a fact; functional acceleration on real hardware/packages is *not* |
| 122 | + something this session verified. |
| 123 | +* *Minor residue:* 2 `{{PLACEHOLDER}}` files + 6 `rsr-template-repo` references. |
| 124 | + |
| 125 | +== Outstanding / not-run (no spin) [[Outstanding / not-run]] |
| 126 | + |
| 127 | +* *The Julia test suite was NOT executed this session.* `julia` is absent, so |
| 128 | + `test/runtests.jl` and friends were *not run* (the package's own docs cite an |
| 129 | + ~1089-test baseline; this session did not reproduce it). We affirm the test |
| 130 | + *files exist*; we do *not* affirm, from this session, that they currently pass. |
| 131 | + A `julia --project=. -e 'using Pkg; Pkg.test()'` run in-environment (with the |
| 132 | + sibling path-deps `../AcceleratorGate.jl` + `../KnotTheory.jl`) is the |
| 133 | + authoritative confirmation. |
| 134 | +* *Accelerator extensions* require their respective backends/hardware and were |
| 135 | + not loaded or tested. |
| 136 | + |
| 137 | +== Reproduce it yourself [[reproduce]] |
| 138 | + |
| 139 | +From the repo root, at the commit above: |
| 140 | + |
| 141 | +[source,bash] |
| 142 | +---- |
| 143 | +git rev-parse HEAD # expect ac5daca08a59dc70ae2e5b5da49d44d311601c25 |
| 144 | +git status --porcelain # expect only this untracked AFFIRMATION.adoc |
| 145 | +
|
| 146 | +# MUST / TRUST style (expect PASS): |
| 147 | +test -f LICENSE; test ! -f Dockerfile -a ! -f Makefile |
| 148 | +grep -q 'SPDX\|MPL' LICENSE; test ! -f .env |
| 149 | +
|
| 150 | +# Real content present: |
| 151 | +grep -E '^name|^version' Project.toml ; ls src/ ext/ test/ |
| 152 | +
|
| 153 | +# NOT verifiable without julia (the honest gap): |
| 154 | +# julia --project=. -e 'using Pkg; Pkg.test()' # needs julia + sibling path-deps |
| 155 | +---- |
| 156 | + |
| 157 | +== One-line characterisation (quote this) |
| 158 | + |
| 159 | +"Skein.jl is the computational/backend engine of the KRL stack — a real shipping |
| 160 | +Julia package (`Skein` v0.3.1; ~2522 lines across types/polynomials/invariants/ |
| 161 | +storage/query; 13 accelerator package-extensions; REUSE-compliant; a real test |
| 162 | +tree the docs cite at ~1089 tests) that self-grades READINESS `C` with example/ |
| 163 | +property-tested (not formally proven) storage obligations. `MUST`/`TRUST` gates |
| 164 | +pass and it is essentially clean of template residue (2 placeholder files, 6 |
| 165 | +`rsr-template-repo` references). Honest gap: `julia` is absent this session, so |
| 166 | +the test suite was *not run* — files exist, pass-state unconfirmed here; and the |
| 167 | +13 accelerator extensions are present as code, not exercised. No intentional |
| 168 | +overclaim." |
| 169 | + |
| 170 | +== Key concern + cross-repo wiring |
| 171 | + |
| 172 | +Skein.jl's *key concern* is being the *computational / backend engine* — it |
| 173 | +computes, transforms, normalises, and evaluates invariants and equivalence |
| 174 | +checks, with an embedded SQLite store; QuandleDB wraps it as the canonical |
| 175 | +persistence + invariant/equivalence face. Per the 2026-06-19 estate rule, each |
| 176 | +repo carries its own AFFIRMATION + scoped Must/Intend/Wish table; Skein.jl's lives |
| 177 | +at `docs/identity-fabric/musts-intends-wishes.adoc`. Confirmed stack: *krl* |
| 178 | +(surface DSL) → *tangle* (TangleIR + type-safe core) → *VerisimCore* (categorical |
| 179 | +abstraction) → *Skein.jl* (this engine) / *quandledb* (storage + equivalence |
| 180 | +face). Adjacent: *echo-types* — structured-loss theory + the identity-fabric |
| 181 | +framing. The withdrawn knot-graph-edge-layer (schema v5) guardrail is retained. |
| 182 | + |
| 183 | +== Joint attestation |
| 184 | + |
| 185 | +To the best of our joint belief at the timestamp above, every claim in this file |
| 186 | +is true and was checked as described — with no intentional overclaim and with the |
| 187 | +un-run Julia suite stated rather than hidden. |
| 188 | + |
| 189 | +* *Engineering party (AI):* ran the gate/RSR checks recorded here as bash on |
| 190 | + 2026-06-19 and stands behind this wording as a faithful report, including the |
| 191 | + explicit `julia`-absent caveat (test suite not reproduced this session). |
| 192 | +* *Owner / maintainer:* Jonathan D.A. Jewell — signs by committing this file with |
| 193 | + `-S`; the signed git commit over this content, at the SHA above, is the |
| 194 | + authoritative form. |
| 195 | +* *Signed-off-date:* (fill on signing) |
0 commit comments