refactor: migrate Markdown to AsciiDoc

.github/workflows/guix-nix-policy.yml

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MPL-2.0
-name: Guix/Nix Package Policy
+name: Guix/Guix Package Policy
 on:
   push:
     branches: [main, master]
@@ -20,25 +20,25 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - name: Enforce Guix primary / Nix fallback
+      - name: Enforce Guix primary / Guix fallback
         run: |
           # Check for package manager files
           HAS_GUIX=$(find . -name "*.scm" -o -name ".guix-channel" -o -name "guix.scm" 2>/dev/null | head -1)
-          HAS_NIX=$(find . -name "*.nix" 2>/dev/null | head -1)
+          HAS_NIX=$(find . -name "*.guix" 2>/dev/null | head -1)
 
           # Block new package-lock.json, yarn.lock, Gemfile.lock, etc.
           NEW_LOCKS=$(git diff --name-only --diff-filter=A HEAD~1 2>/dev/null | grep -E 'package-lock\.json|yarn\.lock|Gemfile\.lock|Pipfile\.lock|poetry\.lock|cargo\.lock' || true)
           if [ -n "$NEW_LOCKS" ]; then
             echo "⚠️ Lock files detected. Prefer Guix manifests for reproducibility."
           fi
 
-          # Prefer Guix, fallback to Nix
+          # Prefer Guix, fallback to Guix
           if [ -n "$HAS_GUIX" ]; then
             echo "✅ Guix package management detected (primary)"
           elif [ -n "$HAS_NIX" ]; then
-            echo "✅ Nix package management detected (fallback)"
+            echo "✅ Guix package management detected (fallback)"
           else
-            echo "ℹ️ Consider adding guix.scm or flake.nix for reproducible builds"
+            echo "ℹ️ Consider adding guix.scm or flake.guix for reproducible builds"
           fi
 
           echo "✅ Package policy check passed"

.github/workflows/rsr-antipattern.yml

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: MPL-2.0
 #
 # Enforces: No TypeScript, No Go, No Python (except SaltStack), No npm
-# Allows: ReScript, Deno, WASM, Rust, OCaml, Haskell, Guile/Scheme
+# Allows: AffineScript, Deno, WASM, Rust, OCaml, Haskell, Guile/Scheme
 
 name: RSR Anti-Pattern Check
 on:
@@ -24,10 +24,10 @@ jobs:
       - name: Check for TypeScript
         run: |
           # Exclude bindings/deno/ - those are Deno FFI files using Deno.dlopen, not plain TypeScript
-          # Exclude .d.ts files - those are TypeScript type declarations for ReScript FFI
+          # Exclude .d.ts files - those are TypeScript type declarations for AffineScript FFI
           TS_FILES=$(find . \( -name "*.ts" -o -name "*.tsx" \) | grep -v node_modules | grep -v 'bindings/deno' | grep -v '\.d\.ts$' || true)
           if [ -n "$TS_FILES" ]; then
-            echo "❌ TypeScript files detected - use ReScript instead"
+            echo "❌ TypeScript files detected - use AffineScript instead"
             echo "$TS_FILES"
             exit 1
           fi
@@ -59,7 +59,7 @@ jobs:
       - name: Check for tsconfig
         run: |
           if [ -f "tsconfig.json" ]; then
-            echo "❌ tsconfig.json detected - use ReScript instead"
+            echo "❌ tsconfig.json detected - use AffineScript instead"
             exit 1
           fi
           echo "✅ No tsconfig.json"
@@ -76,7 +76,7 @@ jobs:
           echo "╔════════════════════════════════════════════════════════════╗"
           echo "║           RSR Anti-Pattern Check Passed ✅                 ║"
           echo "║                                                            ║"
-          echo "║  Allowed: ReScript, Deno, WASM, Rust, OCaml, Haskell,     ║"
+          echo "║  Allowed: AffineScript, Deno, WASM, Rust, OCaml, Haskell,     ║"
           echo "║           Guile/Scheme, SaltStack (Python)                 ║"
           echo "║                                                            ║"
           echo "║  Blocked: TypeScript, Go, npm, Python (non-Salt)          ║"

ABI-FFI-README.adoc

@@ -0,0 +1,87 @@
+== Skein.jl ABI/FFI Layer
+
+=== Architecture
+
+[width="100%",cols="21%,27%,25%,27%",options="header",]
+|===
+|Layer |Language |Purpose |Location
+|*ABI* |Idris2 |Interface definitions with formal proofs
+|`+src/abi/*.idr+`
+
+|*FFI* |Zig |C-compatible implementation |`+ffi/zig/src/*.zig+`
+
+|*Headers* |C (generated) |Bridge between ABI and FFI
+|`+generated/abi/*.h+`
+|===
+
+=== Overview
+
+The canonical Skein implementation is in Julia (`+src/*.jl+`). The
+ABI/FFI layer provides C-compatible bindings so other languages can read
+and write Skein databases without requiring a Julia runtime.
+
+==== Idris2 ABI (`+src/abi/+`)
+
+Formal specifications of: - *Types.idr* — Data types with dependent-type
+proofs (GaussCode validity, hash length) - *Layout.idr* — C struct
+memory layouts with size guarantees - *Foreign.idr* — Function
+signatures with ownership and precondition documentation
+
+==== Zig FFI (`+ffi/zig/+`)
+
+C-compatible implementation of the ABI specification: - *src/main.zig* —
+Core FFI functions (open, close, count, haskey, crossing_number, writhe,
+delete) - *src/schema.sql* — Database schema (must match Julia
+`+src/storage.jl+`) - *test/integration_test.zig* — Integration tests
+
+==== Generated Headers (`+generated/abi/+`)
+
+* *skein.h* — C header for consuming the FFI from C/C++/Python/etc.
+
+=== Building
+
+[source,bash]
+----
+cd ffi/zig
+zig build           # builds libskein_ffi.so / .dylib / .dll
+zig build test      # runs integration tests
+----
+
+Requires system SQLite3 (`+sqlite3.h+` and `+libsqlite3+`).
+
+=== Usage from C
+
+[source,c]
+----
+#include "skein.h"
+
+int main() {
+    skein_db_t db = skein_open(":memory:", 0);
+    if (!db) return 1;
+
+    int32_t trefoil[] = {1, -2, 3, -1, 2, -3};
+    int cn = skein_crossing_number(trefoil, 6);
+    // cn == 3
+
+    int count = skein_count(db);
+    // count == 0
+
+    skein_close(db);
+    return 0;
+}
+----
+
+=== Database Compatibility
+
+The FFI layer creates and reads the same SQLite schema as the Julia
+implementation (schema version 2). Databases created by either
+implementation are fully interoperable.
+
+=== Status
+
+The FFI layer implements a subset of the full Julia API: - Database
+lifecycle (open, close) - Pure invariant computation (crossing_number,
+writhe) - Basic queries (count, haskey, delete) - Store and fetch
+operations are defined in the ABI but not yet implemented in the Zig FFI
+
+For the complete API, use the Julia implementation directly.

CHANGELOG.adoc

@@ -0,0 +1,65 @@
+== Changelog — Skein.jl
+
+All notable changes to this project will be documented in this file.
+
+The format is based on https://keepachangelog.com/en/1.1.0/[Keep a
+Changelog]. This project adheres to
+https://semver.org/spec/v2.0.0.html[Semantic Versioning].
+
+=== [Unreleased]
+
+==== Added
+
+* `+KnotTheoryExt+` Julia package extension: opt-in PlanarDiagram + Knot
+storage path via KnotTheory.jl (test-only extra)
+* Schema v4: new indexed columns `+diagram_format+`,
+`+canonical_diagram+`, `+pd_code+`, `+alexander_polynomial+`,
+`+determinant+`, `+signature+`
+* `+backfill_gauss_canonical!+` for legacy record migration
+* `+to_knot+` / `+to_planardiagram+` API (stubbed — loaded via
+extension)
+* `+INTEGRATION.adoc+` documenting layer boundaries
+* PROOF-NEEDS.md enumerating schema + storage obligations
+* CRG v2 READINESS.md (grade C)
+
+==== Changed
+
+* `+KnotRecord+` struct: added 6 new fields for PD-first storage
+(positional constructor breaking change)
+* `+store!+` refactored via `+_store_precomputed!+` helper; Gauss-path
+preserved
+
+=== [0.3.1]
+
+==== Added
+
+* CRG v2 READINESS.md
+* Deploy dogfood-gate, CRG tests and benchmarks
+* EXPLAINME.adoc, TEST-NEEDS.md
+
+==== Changed
+
+* Migrated SCM files to A2ML format in `+.machine_readable/6a2/+`
+
+=== [0.3.0]
+
+==== Added
+
+* Schema v3 with Jones polynomial + Seifert circle indexing
+* `+query+` with invariant filters
+* `+bulk_import!+`, `+import_csv!+`, `+export_csv+`, `+export_json+`
+
+=== [0.2.0]
+
+==== Added
+
+* Gauss code canonicalisation
+* Metadata key-value storage
+
+=== [0.1.0]
+
+==== Added
+
+* Initial SQLite schema for knot storage
+* `+SkeinDB+`, `+KnotRecord+`, `+GaussCode+` types
+* `+store!+`, `+fetch_knot+`, `+list_knots+`