From 0de25d99af4b0d74669f27d32c5f01b0a77292bf Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 23 Aug 2026 20:01:31 +0100 Subject: [PATCH 1/2] chore: global textual eradication of Nix and ReScript --- .github/workflows/guix-nix-policy.yml | 12 ++++++------ .github/workflows/rsr-antipattern.yml | 10 +++++----- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.github/workflows/guix-nix-policy.yml b/.github/workflows/guix-nix-policy.yml index 1cc2535..018c010 100644 --- a/.github/workflows/guix-nix-policy.yml +++ b/.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,11 +20,11 @@ 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) @@ -32,13 +32,13 @@ jobs: 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" diff --git a/.github/workflows/rsr-antipattern.yml b/.github/workflows/rsr-antipattern.yml index 0278fff..1f6b50b 100644 --- a/.github/workflows/rsr-antipattern.yml +++ b/.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) ║" From 43eeac3eb3f24f973dfb0e17d86e0656112e6230 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 07:49:26 +0100 Subject: [PATCH 2/2] refactor: migrate repository documentation from Markdown to AsciiDoc --- ABI-FFI-README.adoc | 87 +++++++++++++ ABI-FFI-README.md | 79 ------------ CHANGELOG.adoc | 65 ++++++++++ CHANGELOG.md | 57 --------- CODE_OF_CONDUCT.adoc | 31 +++++ CODE_OF_CONDUCT.md | 32 ----- CONTRIBUTING.md => CONTRIBUTING.adoc | 97 ++++++++------- GOVERNANCE.adoc | 178 ++++++--------------------- GOVERNANCE.md | 60 --------- PROOF-NEEDS.adoc | 80 ++++++++++++ PROOF-NEEDS.md | 67 ---------- READINESS.adoc | 52 ++++++++ READINESS.md | 46 ------- REQUIRES_INITIALISATION.adoc | 112 +++++++++++++++++ REQUIRES_INITIALISATION.md | 110 ----------------- SECURITY.adoc | 52 ++++++++ SECURITY.md | 52 -------- TEST-NEEDS.adoc | 49 ++++++++ TEST-NEEDS.md | 44 ------- TOPOLOGY.md => TOPOLOGY.adoc | 40 +++--- 20 files changed, 634 insertions(+), 756 deletions(-) create mode 100644 ABI-FFI-README.adoc delete mode 100644 ABI-FFI-README.md create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md rename CONTRIBUTING.md => CONTRIBUTING.adoc (50%) delete mode 100644 GOVERNANCE.md create mode 100644 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 READINESS.adoc delete mode 100644 READINESS.md create mode 100644 REQUIRES_INITIALISATION.adoc delete mode 100644 REQUIRES_INITIALISATION.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (89%) diff --git a/ABI-FFI-README.adoc b/ABI-FFI-README.adoc new file mode 100644 index 0000000..136e03a --- /dev/null +++ b/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. diff --git a/ABI-FFI-README.md b/ABI-FFI-README.md deleted file mode 100644 index 8cb4c10..0000000 --- a/ABI-FFI-README.md +++ /dev/null @@ -1,79 +0,0 @@ - - - -# Skein.jl ABI/FFI Layer - -## Architecture - -| 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 - -```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 - -```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. diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..3393bfd --- /dev/null +++ b/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+` diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 67b89df..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,57 +0,0 @@ - - - -# Changelog — Skein.jl - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). -This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [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` diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..f444b76 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,31 @@ +== Code of Conduct + +=== Our Pledge + +We are committed to providing a welcoming and inclusive environment for +everyone, regardless of background, identity, or experience level. + +=== Our Standards + +*Expected behaviour:* - Respectful and constructive communication - +Collaboration and mentorship - Graceful acceptance of constructive +criticism - Focus on what is best for the community and the project + +*Unacceptable behaviour:* - Harassment, discrimination, or personal +attacks - Publishing others’ private information without consent - +Trolling, insulting, or derogatory comments - Any conduct that could +reasonably be considered inappropriate in a professional setting + +=== Enforcement + +Instances of unacceptable behaviour may be reported to +j.d.a.jewell@open.ac.uk. + +All complaints will be reviewed and investigated. The project team is +obligated to maintain confidentiality with regard to the reporter. + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org/[Contributor Covenant], version +2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index be268e4..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,32 +0,0 @@ - - - -# Code of Conduct - -## Our Pledge - -We are committed to providing a welcoming and inclusive environment for everyone, regardless of background, identity, or experience level. - -## Our Standards - -**Expected behaviour:** -- Respectful and constructive communication -- Collaboration and mentorship -- Graceful acceptance of constructive criticism -- Focus on what is best for the community and the project - -**Unacceptable behaviour:** -- Harassment, discrimination, or personal attacks -- Publishing others' private information without consent -- Trolling, insulting, or derogatory comments -- Any conduct that could reasonably be considered inappropriate in a professional setting - -## Enforcement - -Instances of unacceptable behaviour may be reported to [j.d.a.jewell@open.ac.uk](mailto:j.d.a.jewell@open.ac.uk). - -All complaints will be reviewed and investigated. The project team is obligated to maintain confidentiality with regard to the reporter. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.adoc similarity index 50% rename from CONTRIBUTING.md rename to CONTRIBUTING.adoc index 01f8934..4d23138 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.adoc @@ -1,38 +1,38 @@ - - - -# Contributing to Skein.jl +== Contributing to Skein.jl Thank you for your interest in contributing to Skein.jl! -## Prerequisites +=== Prerequisites -- Julia 1.10 or later -- Git +* Julia 1.10 or later +* Git -## Development Setup +=== Development Setup -```bash +[source,bash] +---- git clone https://github.com/hyperpolymath/Skein.jl cd Skein.jl julia --project=. -e 'using Pkg; Pkg.instantiate()' -``` +---- -## Running Tests +=== Running Tests -```bash +[source,bash] +---- julia --project=. -e 'using Pkg; Pkg.test()' -``` +---- -## Running Benchmarks +=== Running Benchmarks -```bash +[source,bash] +---- julia --project=. benchmark/benchmarks.jl -``` +---- -## Repository Structure +=== Repository Structure -``` +.... Skein.jl/ ├── src/ # Package source │ ├── Skein.jl # Module entry point @@ -50,45 +50,48 @@ Skein.jl/ ├── .machine_readable/ # SCM metadata files ├── .bot_directives/ # Bot-specific rules └── contractiles/ # Operational framework -``` +.... -## How to Contribute +=== How to Contribute -### Reporting Bugs +==== Reporting Bugs -Open an issue with: -- Julia version (`versioninfo()`) -- Minimal reproduction case -- Expected vs actual behaviour +Open an issue with: - Julia version (`+versioninfo()+`) - Minimal +reproduction case - Expected vs actual behaviour -### Code Contributions +==== Code Contributions -1. Fork the repository -2. Create a feature branch (`git checkout -b feat/my-feature`) -3. Write tests for new functionality -4. Ensure all tests pass -5. Submit a pull request +[arabic] +. Fork the repository +. Create a feature branch (`+git checkout -b feat/my-feature+`) +. Write tests for new functionality +. Ensure all tests pass +. Submit a pull request -### Code Style +==== Code Style -- Follow Julia conventions (4-space indent) -- Add docstrings to all public functions -- Include SPDX header on new files: - ```julia - # SPDX-License-Identifier: CC-BY-SA-4.0 - # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - ``` +* Follow Julia conventions (4-space indent) +* Add docstrings to all public functions +* Include SPDX header on new files: ++ +[source,julia] +---- +# SPDX-License-Identifier: CC-BY-SA-4.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +---- -### Adding Knot Invariants +==== Adding Knot Invariants To add a new invariant: -1. Add the computation function to `src/invariants.jl` -2. Add a column to the schema in `src/storage.jl` (with migration) -3. Update `store!`, `fetch_knot`, and `row_to_record` -4. Add query support in `src/query.jl` -5. Add tests and update the benchmark suite +[arabic] +. Add the computation function to `+src/invariants.jl+` +. Add a column to the schema in `+src/storage.jl+` (with migration) +. Update `+store!+`, `+fetch_knot+`, and `+row_to_record+` +. Add query support in `+src/query.jl+` +. Add tests and update the benchmark suite -## Licence +=== Licence -By contributing, you agree that your contributions will be licensed under MPL-2.0. +By contributing, you agree that your contributions will be licensed +under MPL-2.0. diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index e41020d..9b836fb 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -1,162 +1,60 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble +== Governance -This document describes the governance model for this repository. +=== Overview -== Overview +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. -This repository follows a **Sole Maintainer Governance Model**: +=== Roles and Responsibilities -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable +==== Maintainers -== Core Principles +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support -[cols="1,2"] -|=== -| Principle | Description +==== Contributors -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity +=== Decision Making -| **Transparency** | All significant decisions are documented publicly +==== Minor Changes -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates -| **Open Contribution** | Anyone can contribute via fork and pull request +==== Major Changes -|=== +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers -== Roles and Permissions +==== Breaking Changes -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users +=== Code of Conduct -|=== +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. -== Decision Making Framework +=== Communication -=== Routine Decisions +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates +=== Licensing -**Process**: Maintainer reviews and merges PRs that meet quality standards. +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. -=== Significant Changes +''''' -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **Signing** | All commits must be signed (SSH or GPG) - -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/6a2/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..026b107 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,80 @@ +== PROOF-NEEDS — Skein.jl + +Schema and storage obligations for the knot persistence layer. These are +claims the library makes that would benefit from formal proof or, at +minimum, strong property-test evidence. + +=== Currently verified (by unit + E2E tests, 844 assertions) + +[width="100%",cols="50%,50%",options="header",] +|=== +|Claim |Evidence +|Gauss code roundtrip: `+deserialise_gauss(serialise_gauss(g)) == g+` +|`+test/runtests.jl+` + +|Schema migration v2→v3→v4 preserves stored records +|`+test/runtests.jl+` + +|`+store!+` then `+fetch_knot+` returns equivalent `+KnotRecord+` +|`+test/runtests.jl+` + +|`+query+` with invariant filter returns records whose invariants match +|`+test/runtests.jl+` + +|KnotTheoryExt: `+PlanarDiagram+` storage caches invariants correctly +|`+test/knot_theory_ext_test.jl+` +|=== + +=== Would benefit from formal proof + +==== S1. Schema migration preserves all data + +Statement: For every pair of schema versions (vN → vN+1), the migration +function leaves the set of retrievable `+KnotRecord+`s identical in +terms of their gauss_code, crossing_number, writhe, and metadata. + +Current status: tested by example; not proved for arbitrary databases. +Important because migrations run against user data. + +==== S2. Query result correctness + +Statement: `+query(db; filter)+` returns exactly the set of records R +where predicate(filter, R) holds, with respect to the schema’s typed +indexes. + +Current status: tested for each filter type individually; no exhaustive +composition-of-filters proof. + +==== S3. Canonical Gauss code correctness + +Statement: For any two Gauss codes g₁, g₂ representing the same oriented +knot diagram up to rotation/reflection, +`+canonical_gauss(g₁) == canonical_gauss(g₂)+`. + +Current status: tested on small examples. Would benefit from stronger +property-based testing across generated equivalent diagrams. + +==== S4. Invariant cache consistency + +Statement: If a record’s `+canonical_diagram+` and `+jones_polynomial+` +are both populated, they are consistent — i.e. computing Jones from the +canonical diagram would yield the stored polynomial. + +Current status: not enforced by the schema; relied on by convention. A +consistency check would catch drift between cache and source. + +=== Schema obligations (contract-level) + +* `+UNIQUE(name)+` constraint in `+knots+` table: enforced by SQLite. +* `+diagram_format ∈ {"gauss", "pd"}+`: convention, not enforced by +schema. Could be added as a CHECK constraint. +* Foreign key integrity on `+knot_metadata.knot_id+`: relies on SQLite +foreign key enforcement (enabled via PRAGMA?). + +=== How to propose a new obligation + +[arabic] +. State the claim precisely here. +. Add a property-based test OR a formal proof. +. Move discharged items to the "`Currently verified`" table with +evidence. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 0ee15fc..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,67 +0,0 @@ - - - -# PROOF-NEEDS — Skein.jl - -Schema and storage obligations for the knot persistence layer. These are -claims the library makes that would benefit from formal proof or, at minimum, -strong property-test evidence. - -## Currently verified (by unit + E2E tests, 844 assertions) - -| Claim | Evidence | -|---|---| -| Gauss code roundtrip: `deserialise_gauss(serialise_gauss(g)) == g` | `test/runtests.jl` | -| Schema migration v2→v3→v4 preserves stored records | `test/runtests.jl` | -| `store!` then `fetch_knot` returns equivalent `KnotRecord` | `test/runtests.jl` | -| `query` with invariant filter returns records whose invariants match | `test/runtests.jl` | -| KnotTheoryExt: `PlanarDiagram` storage caches invariants correctly | `test/knot_theory_ext_test.jl` | - -## Would benefit from formal proof - -### S1. Schema migration preserves all data -Statement: For every pair of schema versions (vN → vN+1), the migration -function leaves the set of retrievable `KnotRecord`s identical in terms of -their gauss_code, crossing_number, writhe, and metadata. - -Current status: tested by example; not proved for arbitrary databases. -Important because migrations run against user data. - -### S2. Query result correctness -Statement: `query(db; filter)` returns exactly the set of records R where -predicate(filter, R) holds, with respect to the schema's typed indexes. - -Current status: tested for each filter type individually; no exhaustive -composition-of-filters proof. - -### S3. Canonical Gauss code correctness -Statement: For any two Gauss codes g₁, g₂ representing the same oriented -knot diagram up to rotation/reflection, `canonical_gauss(g₁) == canonical_gauss(g₂)`. - -Current status: tested on small examples. Would benefit from stronger -property-based testing across generated equivalent diagrams. - -### S4. Invariant cache consistency -Statement: If a record's `canonical_diagram` and `jones_polynomial` are both -populated, they are consistent — i.e. computing Jones from the canonical -diagram would yield the stored polynomial. - -Current status: not enforced by the schema; relied on by convention. A -consistency check would catch drift between cache and source. - -## Schema obligations (contract-level) - -- `UNIQUE(name)` constraint in `knots` table: enforced by SQLite. -- `diagram_format ∈ {"gauss", "pd"}`: convention, not enforced by schema. - Could be added as a CHECK constraint. -- Foreign key integrity on `knot_metadata.knot_id`: relies on SQLite foreign - key enforcement (enabled via PRAGMA?). - -## How to propose a new obligation - -1. State the claim precisely here. -2. Add a property-based test OR a formal proof. -3. Move discharged items to the "Currently verified" table with evidence. diff --git a/READINESS.adoc b/READINESS.adoc new file mode 100644 index 0000000..d82efaf --- /dev/null +++ b/READINESS.adoc @@ -0,0 +1,52 @@ +== Component Readiness — Skein.jl + +*Current Grade:* C *Assessed:* 2026-04-05 *Standard:* +link:../standards/component-readiness-grades/[CRG v2.0 STRICT] + +=== Grade rationale (evidence for C) + +Works reliably on own project + annotated. + +==== Evidence + +* *Tests:* 844 passing +* *Annotation:* 128 docstrings across `+src/+`, EXPLAINME.adoc, +TEST-NEEDS.md, INTEGRATION.adoc (explicit SoC boundary doc), 4 READMEs +* *RSR compliance:* 0-AI-MANIFEST.a2ml, `+.machine_readable/6a2/+`, 14+ +workflows, SECURITY/CONTRIBUTING/CODE_OF_CONDUCT +* *Julia package extension:* `+KnotTheoryExt+` — opt-in PD-first storage +via proper Julia ecosystem pattern (KnotTheory as test-extra, not +runtime dep) +* *Dogfooding:* Consumed by KRLAdapter.jl; integration roundtrips green +* *Schema maturity:* v4 schema with 9 indexed invariant columns + +migration path from v3 +* *CI:* Clean; panic-attack assail 0 findings + +=== Gaps preventing higher grades + +==== Blocks B (6+ diverse external targets) + +* No JuliaHub registration yet. +* No external users outside hyperpolymath ecosystem have exercised the +storage layer. +* No external bug reports. +* PROOF-NEEDS.md not yet written (storage schemas have obligations that +would benefit from formal statement). + +==== Blocks A + +* Requires B first. + +=== What to do for B + +[arabic] +. Register on JuliaHub. +. Find 6+ diverse external targets — knot researchers with existing knot +datasets who would benefit from indexed invariant storage. +. Ship their feedback as fixes; track the 6 targets here. +. Write PROOF-NEEDS.md for schema migrations and query-result contracts. + +=== Review cycle + +Reassess per release. Next review: on first minor version bump or any +test/annotation regression. diff --git a/READINESS.md b/READINESS.md deleted file mode 100644 index b8b008b..0000000 --- a/READINESS.md +++ /dev/null @@ -1,46 +0,0 @@ - - - -# Component Readiness — Skein.jl - -**Current Grade:** C -**Assessed:** 2026-04-05 -**Standard:** [CRG v2.0 STRICT](../standards/component-readiness-grades/) - -## Grade rationale (evidence for C) - -Works reliably on own project + annotated. - -### Evidence - -- **Tests:** 844 passing -- **Annotation:** 128 docstrings across `src/`, EXPLAINME.adoc, TEST-NEEDS.md, INTEGRATION.adoc (explicit SoC boundary doc), 4 READMEs -- **RSR compliance:** 0-AI-MANIFEST.a2ml, `.machine_readable/6a2/`, 14+ workflows, SECURITY/CONTRIBUTING/CODE_OF_CONDUCT -- **Julia package extension:** `KnotTheoryExt` — opt-in PD-first storage via proper Julia ecosystem pattern (KnotTheory as test-extra, not runtime dep) -- **Dogfooding:** Consumed by KRLAdapter.jl; integration roundtrips green -- **Schema maturity:** v4 schema with 9 indexed invariant columns + migration path from v3 -- **CI:** Clean; panic-attack assail 0 findings - -## Gaps preventing higher grades - -### Blocks B (6+ diverse external targets) -- No JuliaHub registration yet. -- No external users outside hyperpolymath ecosystem have exercised the storage layer. -- No external bug reports. -- PROOF-NEEDS.md not yet written (storage schemas have obligations that would - benefit from formal statement). - -### Blocks A -- Requires B first. - -## What to do for B - -1. Register on JuliaHub. -2. Find 6+ diverse external targets — knot researchers with existing knot - datasets who would benefit from indexed invariant storage. -3. Ship their feedback as fixes; track the 6 targets here. -4. Write PROOF-NEEDS.md for schema migrations and query-result contracts. - -## Review cycle - -Reassess per release. Next review: on first minor version bump or any test/annotation regression. diff --git a/REQUIRES_INITIALISATION.adoc b/REQUIRES_INITIALISATION.adoc new file mode 100644 index 0000000..d3839e6 --- /dev/null +++ b/REQUIRES_INITIALISATION.adoc @@ -0,0 +1,112 @@ +== REQUIRES INITIALISATION + +*This repository is not finished being set up.* 8 substitution token(s) +across 2 file(s) still have no value. + +=== Why this is not already done + +This repo was created from `+hyperpolymath/rsr-template-repo+`. The mint +(`+just repo-init+`) fills every token that has a single mechanical +answer — owner, repo, author, dates, licence, branch — and it has done +so here. + +The tokens below are the ones it _deliberately cannot_ answer. They need +a decision or a fact that exists only in your head: what this project is +for, what command builds it, which port the service listens on, whether +a PGP key is held at all. The template’s own token vocabulary says as +much — you cannot sensibly answer "`required invariants`" in a +thirty-second bootstrap. + +They were left *visibly unfilled on purpose*. The alternatives were both +worse: inventing plausible values would put confident falsehoods into a +security policy and an architecture document, and silently deleting the +sections would hide the fact that a decision is owed. A visible gap is +honest; a fabricated answer is not. + +=== Do not delete this file until every item below is resolved + +This file is the only marker that the work is outstanding. Deleting it +early does not finish the setup, it just conceals it — and the next +person or agent to arrive will reasonably assume the repo is complete. + +* *If you are a person:* delete this file yourself once the last item is +done. +* *If you are an agent:* resolve what you legitimately can, leave the +rest, and delete this file only when no token below remains anywhere in +the tree. Do not delete it to make a gate go green. + +Re-running the estate top-up tool will remove this file automatically +once nothing is outstanding, so the safest way to finish is to fix the +tokens and let the check confirm it. + +=== What is needed, and where it goes + +==== `+{{CONSUMER1}}+` + +A downstream repo that consumes this one. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{CONSUMER2}}+` + +A second downstream consumer. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{DEP1}}+` + +First named dependency, in .machine_readable/INTENT.contractile. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{DEP2}}+` + +Second named dependency, in .machine_readable/INTENT.contractile. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{MONOREPO_OR_STANDALONE}}+` + +Literally '`monorepo`' or '`standalone`'. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{ONE_PARAGRAPH_ANTI_PURPOSE}}+` + +A paragraph on what this deliberately is NOT for. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{ONE_PARAGRAPH_PURPOSE}}+` + +A paragraph on what this is for. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{PROJECT_UNIQUE_STRENGTH}}+` + +What this does that its alternatives do not. + +Appears in: + +* `+.machine_readable/bot_directives/methodology.a2ml+` + +''''' + +Generated by the estate top-up pass. Rationale and the governing rulings +are in `+hyperpolymath/standards+`; the token vocabulary is +`+.machine_readable/ai/PLACEHOLDERS.adoc+` in `+rsr-template-repo+`. diff --git a/REQUIRES_INITIALISATION.md b/REQUIRES_INITIALISATION.md deleted file mode 100644 index 6500a17..0000000 --- a/REQUIRES_INITIALISATION.md +++ /dev/null @@ -1,110 +0,0 @@ - - -# REQUIRES INITIALISATION - -**This repository is not finished being set up.** 8 substitution token(s) across 2 file(s) still have no value. - -## Why this is not already done - -This repo was created from `hyperpolymath/rsr-template-repo`. The mint -(`just repo-init`) fills every token that has a single mechanical answer — -owner, repo, author, dates, licence, branch — and it has done so here. - -The tokens below are the ones it *deliberately cannot* answer. They need a -decision or a fact that exists only in your head: what this project is for, -what command builds it, which port the service listens on, whether a PGP key -is held at all. The template's own token vocabulary says as much — you cannot -sensibly answer "required invariants" in a thirty-second bootstrap. - -They were left **visibly unfilled on purpose**. The alternatives were both -worse: inventing plausible values would put confident falsehoods into a -security policy and an architecture document, and silently deleting the -sections would hide the fact that a decision is owed. A visible gap is -honest; a fabricated answer is not. - -## Do not delete this file until every item below is resolved - -This file is the only marker that the work is outstanding. Deleting it early -does not finish the setup, it just conceals it — and the next person or agent -to arrive will reasonably assume the repo is complete. - -- **If you are a person:** delete this file yourself once the last item is done. -- **If you are an agent:** resolve what you legitimately can, leave the rest, - and delete this file only when no token below remains anywhere in the tree. - Do not delete it to make a gate go green. - -Re-running the estate top-up tool will remove this file automatically once -nothing is outstanding, so the safest way to finish is to fix the tokens and -let the check confirm it. - -## What is needed, and where it goes - -### `{{CONSUMER1}}` - -A downstream repo that consumes this one. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{CONSUMER2}}` - -A second downstream consumer. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{DEP1}}` - -First named dependency, in .machine_readable/INTENT.contractile. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{DEP2}}` - -Second named dependency, in .machine_readable/INTENT.contractile. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{MONOREPO_OR_STANDALONE}}` - -Literally 'monorepo' or 'standalone'. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{ONE_PARAGRAPH_ANTI_PURPOSE}}` - -A paragraph on what this deliberately is NOT for. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{ONE_PARAGRAPH_PURPOSE}}` - -A paragraph on what this is for. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{PROJECT_UNIQUE_STRENGTH}}` - -What this does that its alternatives do not. - -Appears in: - -- `.machine_readable/bot_directives/methodology.a2ml` - ---- - -Generated by the estate top-up pass. Rationale and the governing rulings are -in `hyperpolymath/standards`; the token vocabulary is -`.machine_readable/ai/PLACEHOLDERS.adoc` in `rsr-template-repo`. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..6cee9df --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,52 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability in Skein.jl, please report it +responsibly. + +*Preferred:* Use +https://github.com/hyperpolymath/Skein.jl/security/advisories/new[GitHub +Security Advisories] + +*Alternative:* Email j.d.a.jewell@open.ac.uk + +==== What to Include + +* Description of the vulnerability +* Steps to reproduce +* Affected versions +* Potential impact assessment +* Suggested fix (if any) + +==== Response Timeline + +* *Acknowledgement:* Within 48 hours +* *Initial assessment:* Within 7 days +* *Fix or mitigation:* Within 30 days for critical issues + +=== Scope + +This policy covers: + +* The Skein.jl Julia package (src/, ext/) +* SQLite database operations and schema +* Data import/export functionality +* The KnotTheory.jl extension + +=== Safe Harbour + +We will not pursue legal action against security researchers who: + +* Act in good faith +* Avoid privacy violations and data destruction +* Report findings promptly +* Allow reasonable time for remediation before disclosure + +=== Security Best Practices + +When using Skein.jl: + +* Use `+:memory:+` databases for untrusted data +* Validate Gauss code input before storage +* Keep dependencies updated (`+Pkg.update()+`) diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index e8deecc..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,52 +0,0 @@ - - - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability in Skein.jl, please report it responsibly. - -**Preferred:** Use [GitHub Security Advisories](https://github.com/hyperpolymath/Skein.jl/security/advisories/new) - -**Alternative:** Email [j.d.a.jewell@open.ac.uk](mailto:j.d.a.jewell@open.ac.uk) - -### What to Include - -- Description of the vulnerability -- Steps to reproduce -- Affected versions -- Potential impact assessment -- Suggested fix (if any) - -### Response Timeline - -- **Acknowledgement:** Within 48 hours -- **Initial assessment:** Within 7 days -- **Fix or mitigation:** Within 30 days for critical issues - -## Scope - -This policy covers: - -- The Skein.jl Julia package (src/, ext/) -- SQLite database operations and schema -- Data import/export functionality -- The KnotTheory.jl extension - -## Safe Harbour - -We will not pursue legal action against security researchers who: - -- Act in good faith -- Avoid privacy violations and data destruction -- Report findings promptly -- Allow reasonable time for remediation before disclosure - -## Security Best Practices - -When using Skein.jl: - -- Use `:memory:` databases for untrusted data -- Validate Gauss code input before storage -- Keep dependencies updated (`Pkg.update()`) diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..288329b --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,49 @@ +== TEST-NEEDS: Skein.jl + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current State + +[cols=",,",options="header",] +|=== +|Category |Count |Details +|*Source modules* |8 |1,856 lines +|*Test files* |1 |1,125 lines, 323 @test/@testset +|*Benchmarks* |1 file |Exists +|*E2E tests* |0 |None +|=== + +=== What’s Missing + +==== E2E Tests + +* [ ] No end-to-end skein computation test + +==== Aspect Tests + +* [ ] *Performance*: 1 benchmark file exists – verify it runs +* [ ] *Error handling*: No edge case tests for degenerate inputs + +==== Benchmarks Status + +* [x] 1 benchmark file exists + +==== Self-Tests + +* [ ] No self-check + +=== FLAGGED ISSUES + +* *323 tests for 8 modules = 40 tests/module* – strong +* *Benchmark exists* – one of only 2 Julia packages with benchmarks +* *Single test file* – should be split for 8 modules + +=== Priority: P3 (LOW) – well tested with benchmark + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 5ceb44f..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,44 +0,0 @@ - -# TEST-NEEDS: Skein.jl - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current State - -| Category | Count | Details | -|----------|-------|---------| -| **Source modules** | 8 | 1,856 lines | -| **Test files** | 1 | 1,125 lines, 323 @test/@testset | -| **Benchmarks** | 1 file | Exists | -| **E2E tests** | 0 | None | - -## What's Missing - -### E2E Tests -- [ ] No end-to-end skein computation test - -### Aspect Tests -- [ ] **Performance**: 1 benchmark file exists -- verify it runs -- [ ] **Error handling**: No edge case tests for degenerate inputs - -### Benchmarks Status -- [x] 1 benchmark file exists - -### Self-Tests -- [ ] No self-check - -## FLAGGED ISSUES -- **323 tests for 8 modules = 40 tests/module** -- strong -- **Benchmark exists** -- one of only 2 Julia packages with benchmarks -- **Single test file** -- should be split for 8 modules - -## Priority: P3 (LOW) -- well tested with benchmark - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 89% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index fd8a553..4a38b4d 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,13 +1,8 @@ - - - - +== Skein.jl — Project Topology -# Skein.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -44,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE STORAGE @@ -72,11 +67,11 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ████████░░ ~75% Stable Database Layer -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Gauss Code ──────────► Skein DB API ───────────► Query DSL ▲ │ SQLite Backend ─────────────┘ ▼ @@ -85,16 +80,17 @@ SQLite Backend ─────────────┘ KnotTheory.jl ───────► Package Extension ──────────┤ │ Equivalence Checking -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments).