docs(grounding): reconcile Skein role to KRL stack — compute/backend engine

.claude/CLAUDE.md

@@ -10,15 +10,23 @@ Skein.jl is a knot-theoretic database for Julia. It stores knots as Gauss codes,
 computes invariants on insert (Jones polynomial, genus, Seifert circles), and
 provides querying by those invariants.
 
-Grounded role: Skein.jl is the persistence + semantic-indexing layer (layer 4) of
-the KRL stack. KRL = Knot Resolution Language (Construct/Transform/Resolve/Retrieve),
-*not* a query language. Skein serves KRL's Retrieve leg (indexed store) and persists
-knot/tangle records; QuandleDB is the Resolve layer. The "maths analogue of a graph
-database" is the user's aspirational framing; the earlier "typed knot-relation edge
-layer + traversal (schema v5)" realignment was authored on a mistaken "KRL = query
-language" model and is WITHDRAWN pending re-grounding against the KRL 4-layer
-architecture. See `.machine_readable/6a2/ECOSYSTEM.a2ml`, `ROADMAP.adoc`, and
-`.machine_readable/6a2/anchor/ANCHOR.a2ml`.
+Grounded role: Skein.jl is the computational/backend engine of the KRL stack — the
+library that computes, transforms, normalizes, and evaluates knot/tangle invariants
+(Jones, genus, Seifert circles) and equivalence checks, with an embedded SQLite store
+for what it computes. KRL = Knot Resolution Language (Construct/Transform/Resolve/
+Retrieve), a resolution DSL — *not merely* a query language. QuandleDB is the database
+application that wraps Skein and is the canonical persistence + invariant/equivalence
+face. The four KRL operations run against the QuandleDB+Skein substrate; no single op
+maps 1:1 to a component (Skein is *not* "the Retrieve leg"). KRL's Retrieve recovers
+resolution-relevant artefacts (presentations, invariants, witnesses, equivalence
+classes, prior resolutions, explanations, provenance), *not* arbitrary querying;
+generic query access over Skein's store is a legitimate engine-layer affordance. The
+"maths analogue of a graph database" is the user's aspirational framing; the earlier
+"typed knot-relation edge layer + traversal (schema v5)" realignment was authored on a
+mistaken "KRL = query language" model and is WITHDRAWN pending re-grounding against
+the KRL architecture. See `.machine_readable/6a2/ECOSYSTEM.a2ml`,
+`.machine_readable/6a2/anchor/ANCHOR.a2ml`, and krl
+`docs/decisions/0002-query-language-deferred.adoc`.
 
 ## Build & Test
 

.github/workflows/ci.yml

@@ -20,9 +20,8 @@ jobs:
       matrix:
         julia-version: ['1.10', '1.11']
         os: [ubuntu-latest]
-        include:
-          - julia-version: '1.11'
-            os: macos-latest
+        # macos-latest dropped 2026-06-19: macOS runner minutes exhausted -> ci.yml
+        # startup_failure blocked merges; ubuntu covers the matrix. Restore when available.
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: julia-actions/setup-julia@4c0cb0fce8556fdb04a90347310e5db8b1f98fb9 # v2

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -1,14 +1,15 @@
 # SPDX-License-Identifier: MPL-2.0
 # ECOSYSTEM.a2ml — Ecosystem position
 # Refreshed 2026-06-05 (corrected: KRL is a resolution language, NOT a query language)
+# Refreshed 2026-06-18 (reconcile: Skein = compute/backend engine; QuandleDB = persistence + invariant/equivalence DB; the four KRL ops are operations, not component labels)
 
 [metadata]
 project = "Skein.jl"
 ecosystem = "hyperpolymath"
 
 [position]
 type = "engine"
-role = "Persistence + semantic-indexing layer of the KRL stack (the knot database)"
+role = "Computational / backend engine of the KRL stack — the library that computes, transforms, normalizes, and evaluates knot/tangle invariants and equivalence checks, with an embedded SQLite store for what it computes. QuandleDB is the database application that wraps Skein and is the canonical persistence + invariant/equivalence face."
 
 # KRL = Knot Resolution Language: a COMPOSITIONAL language for Construct,
 # Transform, Resolve, Retrieve over tangles/knots/links. It is NOT a query
@@ -18,12 +19,13 @@ role = "Persistence + semantic-indexing layer of the KRL stack (the knot databas
 layer-1-surface = "KRL surface syntax + grammar (krl repo); canonical impl KRLAdapter.jl; server-side parser quandledb/server/krl/"
 layer-2-interchange = "TangleIR — canonical interchange object (defined in KRLAdapter.jl, consumed by hyperpolymath/tangle)"
 layer-3-core = "Tangle core — proven type-safe small-step semantics (hyperpolymath/tangle, Lean: proofs/Tangle.lean)"
-layer-4-persistence = "Skein.jl (this repo) + QuandleDB — persistence and semantic indexing"
+layer-4-substrate = "Skein.jl (this repo) = computational/backend engine; QuandleDB = persistence + invariant/equivalence database (the application that wraps Skein). The four KRL operations run against this substrate; no single op maps 1:1 to a component."
 
 [skein-role]
-serves = "the Retrieve operation of KRL — indexed store (find where jones = p, where crossing < 8) + persistence of knot/tangle records"
-knottheory = "weakdep — invariant engine (the Transform leg); loaded via ext/KnotTheoryExt.jl. (KRL's README calls the invariant engine JuliaKnot.jl — naming to reconcile.)"
-quandledb = "the Resolve layer (isotopy, quandle, equivalence class: equivalent?, classify, near) — paired with Skein at persistence/indexing; NOT an app that 'queries' Skein"
+engine = "the computational/backend library — computes/transforms/normalizes/evaluates knot invariants (Jones, genus, Seifert circles) and equivalence checks, with an embedded SQLite store. Generic query access over that store (find where jones = p, where crossing < 8) is a legitimate ENGINE-LAYER affordance, not KRL's identity. The four KRL ops are operations, not component labels — Skein is NOT 'the Retrieve leg'."
+retrieve-clause = "KRL's Retrieve recovers resolution-relevant artefacts (presentations, invariants, witnesses, equivalence classes, prior resolutions, explanations, provenance) — NOT arbitrary database querying. See krl docs/decisions/0002-query-language-deferred.adoc."
+knottheory = "weakdep — invariant engine; loaded via ext/KnotTheoryExt.jl. (KRL's README calls the invariant engine JuliaKnot.jl — naming to reconcile.)"
+quandledb = "the database application that wraps Skein — the canonical persistence + invariant/equivalence face (where presentations, invariants, fingerprints, equivalence classes, witnesses, results live), plus the equivalence/Resolve surface (equivalent?, classify, near). NOT 'an app that queries Skein'."
 
 # These three sibling database languages are each a DISTINCT paradigm.
 # Do NOT flatten any of them to SQL / 'query'.

.machine_readable/6a2/META.a2ml

@@ -15,7 +15,7 @@ representation = "Gauss codes (signed integer sequences); PD codes for planar-di
 extension-model = "KnotTheory.jl is a weakdep loaded via a package extension (ext/KnotTheoryExt.jl) — never a hard dependency"
 
 [decisions]
-adr-krl-stack-role = "2026-06: Skein's grounded role is layer 4 (persistence + semantic indexing) of the KRL stack — it serves KRL's Retrieve operation (indexed store) and persists knot/tangle records. KRL = Knot Resolution Language (Construct/Transform/Resolve/Retrieve), NOT a query language; QuandleDB is the Resolve layer. See 6a2/ECOSYSTEM.a2ml + 6a2/anchor/ANCHOR.a2ml."
+adr-krl-stack-role = "2026-06 (reconciled 2026-06-18): Skein's grounded role is the computational/backend engine of the KRL stack — it computes/transforms/normalizes/evaluates invariants and equivalence checks, with an embedded SQLite store. QuandleDB is the database application that wraps Skein (persistence + invariant/equivalence face). KRL = Knot Resolution Language (Construct/Transform/Resolve/Retrieve), a resolution DSL — NOT merely a query language. The four KRL ops run against the QuandleDB+Skein substrate, not 1:1 to components (Skein is not 'the Retrieve leg'). See 6a2/ECOSYSTEM.a2ml + 6a2/anchor/ANCHOR.a2ml + krl docs/decisions/0002-query-language-deferred.adoc."
 adr-graph-db-withdrawn = "2026-06: an earlier draft proposed realigning Skein into a knot graph database via a typed knot-relationship (edge) layer + traversal (connected-sum DAG, skein triples L+/L-/L0, mutation/crossing-change; schema v5). WITHDRAWN — it was authored on a mistaken 'KRL = query language' model. Skein-relation resolution belongs to the KRL surface / Tangle core / QuandleDB Resolve layer, not necessarily Skein's persistence layer. The 'maths analogue of a graph database' remains the user's aspirational framing; any edge/traversal or schema change must first be re-grounded against the KRL 4-layer architecture."
 adr-jones-from-pd = "Jones polynomial computed from canonical planar diagrams (Kauffman state sum), not bare Gauss codes, which cannot encode the planar embedding and would collapse distinct knots."
 adr-weakdep = "KnotTheory.jl integration via package extension so Skein stays usable standalone."

.machine_readable/6a2/STATE.a2ml

@@ -5,24 +5,24 @@
 [metadata]
 project = "Skein.jl"
 version = "0.1.0"
-last-updated = "2026-06-14"
+last-updated = "2026-06-18"
 status = "active"
 
 [project-context]
 name = "Skein.jl"
 completion-percentage = 75
-phase = "Beta — persistence + semantic-indexing layer (layer 4) of the KRL stack"
+phase = "Beta — computational/backend engine of the KRL stack (compute + embedded store)"
 
 [capabilities]
 storage = "SQLite backend, schema v4 (WAL mode), invariants auto-computed on insert; PD-native fields (diagram_format, canonical_diagram, pd_code)"
 invariants-standalone = "crossing_number, writhe, gauss_hash, Jones (<=15 crossings), genus, Seifert circles, canonical diagram"
 invariants-with-knottheory = "Alexander, determinant, signature via ext/KnotTheoryExt.jl"
-retrieve = "keyword (exact/range/set/meta) + composable & / | predicates; equivalence (find_equivalents, find_isotopic), duplicates, statistics, pagination. (This is KRL's Retrieve leg — one of four KRL operations.)"
+retrieve = "keyword (exact/range/set/meta) + composable & / | predicates; equivalence (find_equivalents, find_isotopic), duplicates, statistics, pagination. (Engine-layer query access over the embedded store; KRL's Retrieve operation recovers resolution-relevant artefacts and runs against the QuandleDB+Skein substrate — Skein is not 'the Retrieve leg'.)"
 data = "KnotInfo/Rolfsen import through 8 crossings; prime-knot table through 7 (knot_table.jl); CSV/JSON; DT-to-Gauss"
 tests = "1089 tests, all passing (test/runtests.jl + e2e / property / canonical / knot-theory-ext; verified green 2026-06-14)"
 
 [current-focus]
-direction = "Knot database as the maths analogue of a graph database (user framing). Skein = persistence + semantic-indexing layer of the KRL stack."
+direction = "Knot database as the maths analogue of a graph database (user framing). Skein = computational/backend engine of the KRL stack; QuandleDB = the persistence + invariant/equivalence database that wraps it."
 
 [withdrawn]
 # An earlier draft of this checkpoint proposed a Skein 'typed knot-relationship
@@ -42,4 +42,4 @@ alexander-standalone = "Alexander polynomial not computed standalone (needs PD/c
 julia-1_9 = "test (1.9) fails at Pkg.instantiate (dependency requires >= 1.10)"
 
 [notes]
-ecosystem = "Skein = persistence + semantic-indexing (layer 4) of the KRL stack; KRL = Knot Resolution Language (NOT a query language); QuandleDB = Resolve layer. See 6a2/ECOSYSTEM.a2ml."
+ecosystem = "Skein = computational/backend engine of the KRL stack; QuandleDB = persistence + invariant/equivalence database (wraps Skein); KRL = Knot Resolution Language, a resolution DSL (NOT merely a query language). The four KRL ops run against the substrate, not 1:1 to components. See 6a2/ECOSYSTEM.a2ml."

.machine_readable/6a2/anchor/ANCHOR.a2ml

@@ -7,12 +7,12 @@ clade: "fv"        # Julia-vocabulary clade (authoritative in CLADE.a2ml)
 status: "active"
 
 # Mission
-mission: "A knot-theoretic database for Julia — the persistence + semantic-indexing layer (layer 4) of the KRL stack. Stores knots/tangles as records with computed topological invariants and serves KRL's Retrieve operation (indexed lookup by invariant: jones, crossing, genus, ...). KRL = Knot Resolution Language (Construct/Transform/Resolve/Retrieve), NOT a query language; QuandleDB is the Resolve layer. The 'maths analogue of a graph database' is the user's aspirational framing, not a committed implementation — see the grounding note."
+mission: "A knot-theoretic database library for Julia — the computational/backend engine of the KRL stack. Computes, transforms, normalizes, and evaluates knot/tangle invariants (Jones, genus, Seifert circles) and equivalence checks, with an embedded SQLite store for what it computes. KRL = Knot Resolution Language (Construct/Transform/Resolve/Retrieve), a resolution DSL — NOT merely a query language. QuandleDB is the database application that wraps Skein and is the canonical persistence + invariant/equivalence face. The four KRL operations run against the QuandleDB+Skein substrate; no single op maps 1:1 to a component (Skein is not 'the Retrieve leg'). Generic query access over Skein's store is a legitimate engine-layer affordance. The 'maths analogue of a graph database' is the user's aspirational framing, not a committed implementation — see the grounding note."
 
 # Grounding (2026-06) — supersedes the earlier graph-DB "realignment"
 grounding:
-  date: "2026-06-14"
-  role: "Skein is layer 4 (persistence + semantic indexing) of the KRL stack. It serves the Retrieve leg (indexed store) and persists knot/tangle records; QuandleDB is the Resolve layer. See .machine_readable/6a2/ECOSYSTEM.a2ml."
+  date: "2026-06-18"
+  role: "Skein is the computational/backend engine of the KRL stack — it computes/transforms/normalizes/evaluates invariants and equivalence checks and carries an embedded SQLite store. QuandleDB is the database application that wraps Skein (persistence + invariant/equivalence face). The four KRL ops are operations run against the substrate, not component labels — Skein is NOT 'the Retrieve leg'. Retrieve recovers resolution-relevant artefacts, not arbitrary queries; generic store access is an engine-layer affordance. See .machine_readable/6a2/ECOSYSTEM.a2ml and krl docs/decisions/0002-query-language-deferred.adoc."
   withdrawn: "An earlier draft proposed a typed knot-relationship (edge) layer + traversal (connected-sum DAG, skein triples L+/L-/L0, mutation/crossing-change; schema v5). That was authored on a MISTAKEN 'KRL = query language' model and is WITHDRAWN. Skein-relation resolution belongs to the KRL surface / Tangle core / QuandleDB Resolve layer, not necessarily Skein's persistence layer. Any edge/traversal or schema change must be re-grounded against the KRL 4-layer architecture first."
 
 # SSG Configuration (Unified boj-server build)

0-AI-MANIFEST.a2ml

@@ -2,7 +2,7 @@
 ; 0-AI-MANIFEST.a2ml — Skein.jl
 
 [ai-contract]
-purpose = "Knot-theoretic database for Julia — the persistence + semantic-indexing layer (layer 4) of the KRL stack. Stores knots/tangles as records with computed topological invariants and serves KRL's Retrieve operation. KRL = Knot Resolution Language (Construct/Transform/Resolve/Retrieve), NOT a query language; QuandleDB is the Resolve layer."
+purpose = "Knot-theoretic database engine for Julia — the computational/backend engine of the KRL stack. Computes/transforms/normalizes/evaluates invariants and equivalence checks, with an embedded SQLite store. QuandleDB is the database application that wraps Skein (persistence + invariant/equivalence face). KRL = Knot Resolution Language (Construct/Transform/Resolve/Retrieve), a resolution DSL — NOT merely a query language. The four KRL ops run against the substrate, not 1:1 to components (Skein is not 'the Retrieve leg')."
 agent-may = "edit src/, test/, docs/, CHANGELOG.md, ROADMAP.adoc, .machine_readable/6a2/"
 agent-may-not = "edit LICENSE / SECURITY.md without explicit user confirmation; add KnotTheory.jl as a hard dependency (weakdep only); resurrect the withdrawn 'knot graph database / typed knot-relation edge layer / schema v5' framing (see .machine_readable/6a2/STATE.a2ml) without re-grounding against the KRL 4-layer architecture"
 agent-must-after = "code-edit -> real Pkg.test() run (tests must pass before commit)"

README.adoc

@@ -8,7 +8,7 @@
 image:https://img.shields.io/badge/Project-Topology-9558B2[Topology,link="TOPOLOGY.md"]
 image:https://img.shields.io/badge/Completion-75%25-yellow[75%,link="TOPOLOGY.md"]
 
-A knot-theoretic database for Julia. Store, index, and query knots by their topological invariants.
+A knot-theoretic database engine for Julia. Store, index, and query knots by their topological invariants.
 
 image:https://img.shields.io/badge/Julia-1.10+-blue.svg[Julia 1.10+]
 image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/Skein.jl"]
@@ -27,6 +27,19 @@ Works standalone, or as a persistence layer on top of https://github.com/hyperpo
 
 For explicit layer boundaries and interop guarantees, see link:INTEGRATION.adoc[INTEGRATION.adoc].
 
+[NOTE]
+====
+*Role in the KRL stack.* Skein.jl is the *computational / backend engine* of the
+https://github.com/hyperpolymath/krl[KRL] (Knot Resolution Language) stack: it
+computes, transforms, normalizes, and evaluates invariants and equivalence checks,
+with an embedded SQLite store. *QuandleDB* is the database application that wraps
+Skein and is the canonical persistence + invariant/equivalence face. The four KRL
+operations (construct / transform / resolve / retrieve) run against the
+QuandleDB+Skein substrate — no single op maps to one component. Generic query access
+here is an engine-layer affordance; KRL itself is a resolution DSL, *not merely* a
+query language.
+====
+
 == Quick start
 
 [source,julia]

ROADMAP.adoc

@@ -30,14 +30,19 @@
 * [x] Julia General registry compatibility (compat bounds for all deps)
 * [x] 493 tests passing
 
-== Current focus — Skein in the KRL stack (layer 4: persistence + semantic indexing)
-
-Skein.jl is the persistence + semantic-indexing layer (layer 4) of the KRL
-stack. KRL = Knot Resolution Language (Construct / Transform / Resolve /
-Retrieve) — *not* a query language. Skein serves KRL's **Retrieve** leg
-(indexed store: find where `jones = p`, where `crossing < 8`) and persists
-knot/tangle records; QuandleDB is the **Resolve** layer. See
-`.machine_readable/6a2/ECOSYSTEM.a2ml`.
+== Current focus — Skein in the KRL stack (computational/backend engine)
+
+Skein.jl is the *computational / backend engine* of the KRL stack — it
+computes, transforms, normalizes, and evaluates invariants and equivalence
+checks, with an embedded SQLite store. KRL = Knot Resolution Language
+(Construct / Transform / Resolve / Retrieve), a resolution DSL — *not merely* a
+query language. *QuandleDB* is the database application that wraps Skein and is
+the canonical persistence + invariant/equivalence face. The four KRL operations
+run against the QuandleDB+Skein substrate; no single op maps 1:1 to a component
+(Skein is *not* "the Retrieve leg"). Generic query access over the store
+(find where `jones = p`, where `crossing < 8`) is an engine-layer affordance.
+See `.machine_readable/6a2/ECOSYSTEM.a2ml` and krl
+`docs/decisions/0002-query-language-deferred.adoc`.
 
 * [ ] Alexander polynomial (standalone, via the PD / `pd_code` route)
 * [ ] Consolidate the Retrieve surface (range/set/meta predicates, pagination, statistics) against the KRL Retrieve spec