diff --git a/AFFIRMATION.adoc b/AFFIRMATION.adoc new file mode 100644 index 0000000..e828a88 --- /dev/null +++ b/AFFIRMATION.adoc @@ -0,0 +1,195 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell += AFFIRMATION — Skein.jl, as of 2026-06-19 +:toc: macro +:toclevels: 2 + +_the No-Bullshit file: what we affirm was true and checkable at this moment_ + +[NOTE] +==== +*Genre.* An *affirmation* is a solemn declaration of the truth of a statement, +made by someone who _declines to swear an oath_ — our truth-as-best-believed at +a stamped instant, binding on our honesty, not a claim of infallibility. It is +not the README and not the EXPLAINME: + +[cols="1,3,2",options="header"] +|=== +| File | Answers | Tense +| `README.adoc` | _Where is this going, and why?_ — Skein.jl's purpose and steering | future / aspirational +| `EXPLAINME.adoc` | _How is it built, and what's the evidence?_ | descriptive / mechanism +| *`AFFIRMATION.adoc`* (this file) | _What can we honestly affirm was *true and checkable* at a stamped moment?_ | a frozen instant, falsifiable +|=== + +Every repo in the estate carries one, per the 2026-06-19 estate rule. +==== + +toc::[] + +== What this is, and how it is designed to work + +*What it is.* A short, dated, jointly-signed snapshot of what we can _honestly +and verifiably_ claim about the Skein.jl repo at one exact commit. + +*How it is designed to work.* + +. *Ground truth, not memory.* Every gate result below was produced by _running + the check this session_. *Material caveat (read it):* `just` is absent, so the + `contractiles/` Must/Trust logic was run *as bash*; and *`julia` is absent*, so + the Julia package and its test suite **were not executed** — see + <>. +. *A frozen anchor.* The file names the exact commit SHA, branch, and toolchain + (see <>). +. *A real signature.* Authoritatively landed by the maintainer's *signed git + commit*. The AI engineering party *cannot* GPG-sign and does not claim to. + +*We are fallible.* Best honest belief, not a proof of its own correctness. + +== The epistemic contract + +This document records our *best joint belief* at the timestamp below. *No +intentional overclaim:* where a check passed we say "PASS"; where the toolchain +was *absent* we say "not run", never "passed"; where the repo self-grades low we +report that grade. + +*Standing invitation to refute.* Reproduce <> at the stamped commit +and tell us where the discrepancy is. + +== Verifiable anchor + +[cols="1,3"] +|=== +| *Repo* | `hyperpolymath/Skein.jl` — the *computational / backend engine* of the KRL stack (computes invariants + equivalence checks; embedded SQLite store) +| *Branch* | `claude/practical-newton-9eFe2` (feature branch, based on the current `origin/main` which already carries the merged #20 grounding + #21 CI work) +| *Commit (HEAD)* | `ac5daca08a59dc70ae2e5b5da49d44d311601c25` +| *Permalink* | https://github.com/hyperpolymath/Skein.jl/tree/ac5daca08a59dc70ae2e5b5da49d44d311601c25 +| *Verified* | 2026-06-19 (checks run this session; precise UTC second not captured — date, not claimed instant) +| *Working-tree delta* | Clean (`git status --porcelain` empty) at verification, except this untracked `AFFIRMATION.adoc`. +| *Toolchain (present)* | `git`, `Agda 2.6.3`. *Absent this session:* `just`, `julia`, `deno`. +| *Run method* | `contractiles/` Must/Trust logic + RSR checks run as bash. *Julia package/tests not executed* (no `julia`). +| *HEAD commit signature* | *Not signed by the AI party.* Authoritative signature is the maintainer's signed commit that lands this file. +|=== + +== Companion documents and repo metadata (cross-check) + +* *`README.adoc`* — present and *cleanly instantiated*: title `= Skein.jl`. +* *`EXPLAINME.adoc`* — present and *cleanly instantiated*: `= Skein.jl — Show Me + The Receipts`. +* *`Project.toml`* — `name = "Skein"`, `version = "0.3.1"`. +* *`0-AI-MANIFEST.a2ml`* — present. *REUSE-compliant* (`REUSE.toml` + `LICENSES/`). +* *Template residue* — *2 files* with `{{PLACEHOLDER}}` tokens; *6 files* + reference the `rsr-template-repo` lineage. The `Justfile` itself is clean. + Minor instantiation debt — noted, not hidden. +* *GitHub repo description / topics* — *not fetched this session* (no `gh`). + +== The honest state (one breath) + +Skein.jl is a *real, shipping* Julia knot-theory engine — `Skein` v0.3.1, ~2522 +lines across `src/` (`types`, `polynomials`, `invariants`, `storage`, `query`, +`import_export`, `knot_table`, plus `abi/` and `backends/`), *13 package +extensions* (accelerator backends: CUDA / Metal / ROCm / TPU / NPU / FPGA / QPU / +VPU / PPU / DSP / Math / Crypto / KnotTheory), and a real test suite. It is the +*computational/backend engine* of the KRL stack (grounding merged in #20), is +cleanly instantiated and REUSE-compliant, and the `MUST`/`TRUST` gates pass. The +honest limits are about *assurance*, not scaffolding: it self-grades READINESS +*C*, its storage obligations are *example/property-tested* rather than proven, and +*its Julia test suite was not run this session* (no `julia`). + +== What is solid (and how we checked) + +* *MUST/TRUST-style checks — PASS.* Run as bash from `contractiles/`: LICENSE + present; no banned `Dockerfile`/`Makefile`; SPDX headers on a sampled 150 `.jl` + files (0 unheadered); LICENSE carries an SPDX/MPL identifier; no `.env` / + `credentials.json` committed. +* *Clean instantiation + REUSE compliance.* README + EXPLAINME carry the real + project name; `REUSE.toml` + `LICENSES/` present. +* *Real, substantial content.* A working Julia engine: `src/Skein.jl` plus the + invariant/persistence modules (~2522 lines); 13 `ext/Skein*Ext.jl` package + extensions; a real test tree (`test/runtests.jl`, `canonical_gauss_test.jl`, + `e2e_test.jl`, `knot_theory_ext_test.jl`, `property_test.jl`). This is shipped + engineering at version 0.3.1, not a template skeleton. + +== Known-incomplete but honestly fenced (loud, never silent) + +* *READINESS grade `C`.* `READINESS.md` self-assesses *Current Grade: C* — + reported as-is. +* *Obligations are tested, not proved.* `PROOF-NEEDS.md` records the storage/ + schema obligations as *"tested by example; not proved for arbitrary + databases"*, *"tested for each filter type … no exhaustive [proof]"*, *"tested + on small examples"*. No claim of formal proof. +* *The 13 accelerator extensions are present as code, not exercised here.* Their + existence is a fact; functional acceleration on real hardware/packages is *not* + something this session verified. +* *Minor residue:* 2 `{{PLACEHOLDER}}` files + 6 `rsr-template-repo` references. + +== Outstanding / not-run (no spin) [[Outstanding / not-run]] + +* *The Julia test suite was NOT executed this session.* `julia` is absent, so + `test/runtests.jl` and friends were *not run* (the package's own docs cite an + ~1089-test baseline; this session did not reproduce it). We affirm the test + *files exist*; we do *not* affirm, from this session, that they currently pass. + A `julia --project=. -e 'using Pkg; Pkg.test()'` run in-environment (with the + sibling path-deps `../AcceleratorGate.jl` + `../KnotTheory.jl`) is the + authoritative confirmation. +* *Accelerator extensions* require their respective backends/hardware and were + not loaded or tested. + +== Reproduce it yourself [[reproduce]] + +From the repo root, at the commit above: + +[source,bash] +---- +git rev-parse HEAD # expect ac5daca08a59dc70ae2e5b5da49d44d311601c25 +git status --porcelain # expect only this untracked AFFIRMATION.adoc + +# MUST / TRUST style (expect PASS): +test -f LICENSE; test ! -f Dockerfile -a ! -f Makefile +grep -q 'SPDX\|MPL' LICENSE; test ! -f .env + +# Real content present: +grep -E '^name|^version' Project.toml ; ls src/ ext/ test/ + +# NOT verifiable without julia (the honest gap): +# julia --project=. -e 'using Pkg; Pkg.test()' # needs julia + sibling path-deps +---- + +== One-line characterisation (quote this) + +"Skein.jl is the computational/backend engine of the KRL stack — a real shipping +Julia package (`Skein` v0.3.1; ~2522 lines across types/polynomials/invariants/ +storage/query; 13 accelerator package-extensions; REUSE-compliant; a real test +tree the docs cite at ~1089 tests) that self-grades READINESS `C` with example/ +property-tested (not formally proven) storage obligations. `MUST`/`TRUST` gates +pass and it is essentially clean of template residue (2 placeholder files, 6 +`rsr-template-repo` references). Honest gap: `julia` is absent this session, so +the test suite was *not run* — files exist, pass-state unconfirmed here; and the +13 accelerator extensions are present as code, not exercised. No intentional +overclaim." + +== Key concern + cross-repo wiring + +Skein.jl's *key concern* is being the *computational / backend engine* — it +computes, transforms, normalises, and evaluates invariants and equivalence +checks, with an embedded SQLite store; QuandleDB wraps it as the canonical +persistence + invariant/equivalence face. Per the 2026-06-19 estate rule, each +repo carries its own AFFIRMATION + scoped Must/Intend/Wish table; Skein.jl's lives +at `docs/identity-fabric/musts-intends-wishes.adoc`. Confirmed stack: *krl* +(surface DSL) → *tangle* (TangleIR + type-safe core) → *VerisimCore* (categorical +abstraction) → *Skein.jl* (this engine) / *quandledb* (storage + equivalence +face). Adjacent: *echo-types* — structured-loss theory + the identity-fabric +framing. The withdrawn knot-graph-edge-layer (schema v5) guardrail is retained. + +== Joint attestation + +To the best of our joint belief at the timestamp above, every claim in this file +is true and was checked as described — with no intentional overclaim and with the +un-run Julia suite stated rather than hidden. + +* *Engineering party (AI):* ran the gate/RSR checks recorded here as bash on + 2026-06-19 and stands behind this wording as a faithful report, including the + explicit `julia`-absent caveat (test suite not reproduced this session). +* *Owner / maintainer:* Jonathan D.A. Jewell — signs by committing this file with + `-S`; the signed git commit over this content, at the SHA above, is the + authoritative form. +* *Signed-off-date:* (fill on signing) diff --git a/docs/identity-fabric/musts-intends-wishes.adoc b/docs/identity-fabric/musts-intends-wishes.adoc new file mode 100644 index 0000000..8fdba32 --- /dev/null +++ b/docs/identity-fabric/musts-intends-wishes.adoc @@ -0,0 +1,70 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell += Skein.jl — Normative Scope (Must / Intend / Wish) +:toc: preamble +:revdate: 2026-06-19 + +[abstract] +Per-repo normative-scope record for Skein.jl (the computational / backend engine +of the KRL stack). Estate rule (2026-06-19): every repo carries its own scoped +table; crossover content is duplicated and marked until resolved, then wired into +the other relevant repos. `◇` marks proposals not yet canonical. + +== Confirmed stack placement (2026-06-19) + +[literal] +krl (surface DSL) → tangle (TangleIR + type-safe core) → VerisimCore (categorical +abstraction) → Skein.jl (this engine) / quandledb (storage + equivalence face) + +Skein.jl is the *engine*, not a KRL "leg" — the four KRL ops run against the +QuandleDB+Skein substrate (no op↔component 1:1 mapping; grounding merged in #20). + +== Levels + +* *MUST* — required to be what it is (RFC 2119 normative). +* *INTEND* — committed direction. +* *WISH* — aspirational. + +== Skein.jl (own) + +[cols="1,5", options="header"] +|=== +| Level | Skein.jl + +| *MUST* +| Be the *computational / backend engine* — compute / transform / normalise / + evaluate knot invariants (Jones, genus, Seifert circles) and equivalence + checks (R1/R2, Jones comparison), with an *embedded* SQLite store; store knots + as Gauss codes and auto-compute invariants on insert; honest engine grounding + (engine, *not* the "Retrieve leg"); SPDX/REUSE compliance on all files; the + test baseline (~1089 tests) green before any commit. + +| *INTEND* +| Raise READINESS above `C`; strengthen the storage/schema obligations from + *example/property-tested* toward proof where tractable (`PROOF-NEEDS.md`); keep + KnotTheory.jl a *weakdep only* (never a hard dependency); clear the residual + template debt (2 `{{PLACEHOLDER}}` files, 6 `rsr-template-repo` references); + mature the 13 accelerator extensions (CUDA/Metal/ROCm/TPU/NPU/FPGA/QPU/VPU/PPU/ + DSP) from present-as-code toward exercised-and-benchmarked ◇. + +| *WISH* +| Broader invariant coverage (e.g. Alexander polynomial — *not* implemented; + needs crossing-chirality data absent from basic Gauss codes); a re-grounded + next schema version (the v5 knot-relation edge layer was *withdrawn* — + mis-grounded on "KRL = query"; no committed next schema until re-grounded + against the 4-layer stack); real hardware-accelerated invariant computation ◇. +|=== + +== Cross-repo wiring + +Skein.jl is the *compute substrate*. QuandleDB wraps it as the canonical +persistence + invariant/equivalence face; the four KRL operations run against the +QuandleDB+Skein substrate. The load-bearing shared invariant across the stack is +*equivalence-integrity* (the `a = a` idem core) — Skein.jl is where equivalence +is *actually computed and checked*. + +Sibling repos' key concerns (keep in sync as crossover resolves): *krl* — the +resolution DSL surface; *tangle* — TangleIR + type-safe core; *quandledb* — +equivalence / identity face (wraps this engine; holds the canonical QuandleDB/KRL +crossover table); *echo-types* — structured-loss theory + the identity-fabric +framing (Conway·Fichte / Bruner / Ricoeur). See `../../AFFIRMATION.adoc`.