diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..693ac8d --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,129 @@ +== JanusKey Architecture — Reversibility Stack Junction Point + +=== Lineage + +.... +maa-framework (policy vision) + → absolute-zero (certified null operations — formal theory) + → januskey (development proof-of-concept — this repo) + → THREE downstream applications: + ├── ochrance — neurosymbolic filesystem verification (Idris2) + ├── valence-shell — formally verified reversible shell (Rust + 6 proof systems) + └── aletheia — reversible OS operations (early research) +.... + +JanusKey is the *junction point* where absolute-zero’s theoretical work +on Certified Null Operations (CNOs) was first applied to practical file +operations. The three downstream applications independently implemented +reversibility, but shared no code — until the `+reversible-core+` +extraction described below. + +=== Workspace Structure + +.... +januskey/ +├── crates/ +│ ├── reversible-core/ ← SHARED LIBRARY (the integration surface) +│ │ ├── content_store — SHA256 content-addressed storage +│ │ ├── metadata — OperationMetadata + MetadataStore (append-only log) +│ │ ├── transaction — Transaction lifecycle (begin/commit/rollback) +│ │ ├── manifest — A2ML emitter (bridge to ochrance verification) +│ │ ├── error — ReversibleError types +│ │ └── lib — ReversibleExecutor trait +│ │ +│ └── januskey-cli/ ← CLI TOOL (depends on reversible-core) +│ ├── operations — FileOperation executor (actual filesystem ops) +│ ├── keys — Key management (AES-GCM, Argon2) +│ ├── attestation — Audit trail +│ ├── obliteration — Secure deletion +│ ├── delta — Differential operations +│ ├── main — jk CLI binary +│ └── keys_cli — jk-keys CLI binary +.... + +=== reversible-core: The Shared Foundation + +`+reversible-core+` is a lean Rust library crate (no CLI deps) that +provides the types all three downstream applications share: + +==== ReversibleExecutor Trait + +[source,rust] +---- +pub trait ReversibleExecutor { + type Op; + type Metadata; + type Error; + + fn execute(&mut self, op: Self::Op) -> Result; + fn undo(&mut self, metadata_id: &str) -> Result; + fn generate_manifest(&self) -> Result; +} +---- + +This is the *Rust-side mirror* of ochrance’s `+VerifiedSubsystem+` +interface (Idris2). The `+generate_manifest+` method emits A2ML that +ochrance can parse and verify. + +==== CNO Correspondence + +Per absolute-zero, every `+OperationType+` has a known inverse: + +[cols=",,",options="header",] +|=== +|Operation |Inverse |Property +|Delete |Create |`+delete ; create ≡ CNO+` +|Create |Delete |`+create ; delete ≡ CNO+` +|Modify |Modify |Self-inverse (stores old+new content) +|Move |Move |Self-inverse (swap src/dst) +|Copy |Delete |`+copy ; delete_copy ≡ CNO+` +|Chmod |Chmod |Self-inverse (stores old mode) +|Chown |Chown |Self-inverse (stores old uid:gid) +|=== + +==== A2ML Bridge to Ochrance + +`+ManifestEmitter::generate()+` produces A2ML manifests containing: - +Manifest header (version, subsystem, timestamp, Merkle root) - Refs (one +per operation, with content hash) - Policy (verification mode) + +Ochrance parses these and produces `+VerificationProof+` witnesses: - +`+LaxProof+` — manifest is well-formed - `+CheckedProof+` — all content +hashes verified via BLAKE3 - `+AttestedProof+` — manifest is signed +(Ed25519) + +=== Integration Status + +==== Phase 1: reversible-core extraction ✅ DONE (2026-03-21) + +Extracted core types from januskey into `+reversible-core+`. Workspace +builds, 44 tests pass. januskey-cli re-exports all types for backward +compatibility. + +==== Phase 2: valence-shell integration — NEXT + +Wire valence-shell (`+impl/rust-cli/+`) to depend on +`+reversible-core+`: - Add `+ContentStore+` to `+ShellState+` for +content-addressed undo data - Replace inline +`+undo_data: Option>+` for large file content - Add +`+a2ml_emitter.rs+` for manifest generation - Replace +`+verification.rs+` stubs with `+ReversibleExecutor+` implementation + +==== Phase 3: ochrance ABI extension — PENDING + +Add reversibility types to ochrance’s Idris2 ABI: - +`+src/abi/Ochrance/ABI/Reversibility.idr+` — `+ReversibleOp+`, +`+ReversibilityProof+` - +`+ochrance-core/Ochrance/Subsystem/OperationLog.idr+` — +`+VerifiedSubsystem+` for op logs + +==== Phase 4: Cross-repo documentation — PENDING + +Update ARCHITECTURE.md and ECOSYSTEM.a2ml in all three repos with +cross-references. + +==== Deferred + +* *aletheia*: Too early (Phase 0 research, no operation types yet) +* *Merkle tree compatibility*: ochrance uses BLAKE3 height-indexed +trees; Rust side needs compatible implementation diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 252496f..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,124 +0,0 @@ - -# JanusKey Architecture — Reversibility Stack Junction Point - -## Lineage - -``` -maa-framework (policy vision) - → absolute-zero (certified null operations — formal theory) - → januskey (development proof-of-concept — this repo) - → THREE downstream applications: - ├── ochrance — neurosymbolic filesystem verification (Idris2) - ├── valence-shell — formally verified reversible shell (Rust + 6 proof systems) - └── aletheia — reversible OS operations (early research) -``` - -JanusKey is the **junction point** where absolute-zero's theoretical work on Certified -Null Operations (CNOs) was first applied to practical file operations. The three -downstream applications independently implemented reversibility, but shared no code — -until the `reversible-core` extraction described below. - -## Workspace Structure - -``` -januskey/ -├── crates/ -│ ├── reversible-core/ ← SHARED LIBRARY (the integration surface) -│ │ ├── content_store — SHA256 content-addressed storage -│ │ ├── metadata — OperationMetadata + MetadataStore (append-only log) -│ │ ├── transaction — Transaction lifecycle (begin/commit/rollback) -│ │ ├── manifest — A2ML emitter (bridge to ochrance verification) -│ │ ├── error — ReversibleError types -│ │ └── lib — ReversibleExecutor trait -│ │ -│ └── januskey-cli/ ← CLI TOOL (depends on reversible-core) -│ ├── operations — FileOperation executor (actual filesystem ops) -│ ├── keys — Key management (AES-GCM, Argon2) -│ ├── attestation — Audit trail -│ ├── obliteration — Secure deletion -│ ├── delta — Differential operations -│ ├── main — jk CLI binary -│ └── keys_cli — jk-keys CLI binary -``` - -## reversible-core: The Shared Foundation - -`reversible-core` is a lean Rust library crate (no CLI deps) that provides the types -all three downstream applications share: - -### ReversibleExecutor Trait - -```rust -pub trait ReversibleExecutor { - type Op; - type Metadata; - type Error; - - fn execute(&mut self, op: Self::Op) -> Result; - fn undo(&mut self, metadata_id: &str) -> Result; - fn generate_manifest(&self) -> Result; -} -``` - -This is the **Rust-side mirror** of ochrance's `VerifiedSubsystem` interface (Idris2). -The `generate_manifest` method emits A2ML that ochrance can parse and verify. - -### CNO Correspondence - -Per absolute-zero, every `OperationType` has a known inverse: - -| Operation | Inverse | Property | -|-----------|---------|----------| -| Delete | Create | `delete ; create ≡ CNO` | -| Create | Delete | `create ; delete ≡ CNO` | -| Modify | Modify | Self-inverse (stores old+new content) | -| Move | Move | Self-inverse (swap src/dst) | -| Copy | Delete | `copy ; delete_copy ≡ CNO` | -| Chmod | Chmod | Self-inverse (stores old mode) | -| Chown | Chown | Self-inverse (stores old uid:gid) | - -### A2ML Bridge to Ochrance - -`ManifestEmitter::generate()` produces A2ML manifests containing: -- Manifest header (version, subsystem, timestamp, Merkle root) -- Refs (one per operation, with content hash) -- Policy (verification mode) - -Ochrance parses these and produces `VerificationProof` witnesses: -- `LaxProof` — manifest is well-formed -- `CheckedProof` — all content hashes verified via BLAKE3 -- `AttestedProof` — manifest is signed (Ed25519) - -## Integration Status - -### Phase 1: reversible-core extraction ✅ DONE (2026-03-21) - -Extracted core types from januskey into `reversible-core`. Workspace builds, -44 tests pass. januskey-cli re-exports all types for backward compatibility. - -### Phase 2: valence-shell integration — NEXT - -Wire valence-shell (`impl/rust-cli/`) to depend on `reversible-core`: -- Add `ContentStore` to `ShellState` for content-addressed undo data -- Replace inline `undo_data: Option>` for large file content -- Add `a2ml_emitter.rs` for manifest generation -- Replace `verification.rs` stubs with `ReversibleExecutor` implementation - -### Phase 3: ochrance ABI extension — PENDING - -Add reversibility types to ochrance's Idris2 ABI: -- `src/abi/Ochrance/ABI/Reversibility.idr` — `ReversibleOp`, `ReversibilityProof` -- `ochrance-core/Ochrance/Subsystem/OperationLog.idr` — `VerifiedSubsystem` for op logs - -### Phase 4: Cross-repo documentation — PENDING - -Update ARCHITECTURE.md and ECOSYSTEM.a2ml in all three repos with cross-references. - -### Deferred - -- **aletheia**: Too early (Phase 0 research, no operation types yet) -- **Merkle tree compatibility**: ochrance uses BLAKE3 height-indexed trees; Rust side - needs compatible implementation diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..5e33ac5 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,84 @@ +== Changelog + +All notable changes to `+januskey+` will be documented in this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat(crg): add Current Grade badge anchor to READINESS.md +* feat: add idrisiser Idris2 proof wrappers for JanusKey cryptographic +core +* feat: blitz — wire all tests, add property-based + regression, fix +benchmarks, READINESS.md +* feat: add E2E, P2P, aspect tests + criterion benchmarks +* feat: add Zig FFI implementation + C header + integration tests +* feat: complete Idris2 ABI — Foreign.idr + Proofs.idr +* feat: add Idris2 ABI proofs — TypeLL Levels 1-12 +* feat: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure + +==== Fixed + +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#33) +* fix(ci): sync hypatia-scan.yml to canonical (#32) +* fix(ci): adopt canonical hypatia-scan.yml (#31) +* fix(ci): Phase-2 fleet submission must not fail the security gate +(#30) +* fix(ci): hypatia-scan workdir ($\{\{ env.HOME }} resolves empty) (#29) +* fix(januskey): sweep .expect("`TODO: handle error`") — 166 sites +cleared +* fix: replace 60 unwrap() calls with expect() in security-critical +modules +* fix: quote $$ and use printf in setup.sh +* fix: correct '`Provably Reversible`' claim — proofs are pending, not +done +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs(security): draft MCP-exposure threat model (AI-authored, pending +human sign-off) +* docs: add M2 estate audit report (2026-04-04) +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add ARCHITECTURE.md — reversibility stack junction point +* docs: update SCM files with project information +* docs: add CONTRIBUTING.md +* docs: add checkpoint files for state tracking + +==== CI + +* ci(rust): convert rust-ci.yml to thin wrapper (standards#174) (#39) +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#35) +* ci: bump actions/upload-artifact SHA to current v4 (#27) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci: restore Dependabot security path + wire auto-merge + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 36dbf2c..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,75 +0,0 @@ - -# Changelog - -All notable changes to `januskey` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat(crg): add Current Grade badge anchor to READINESS.md -- feat: add idrisiser Idris2 proof wrappers for JanusKey cryptographic core -- feat: blitz — wire all tests, add property-based + regression, fix benchmarks, READINESS.md -- feat: add E2E, P2P, aspect tests + criterion benchmarks -- feat: add Zig FFI implementation + C header + integration tests -- feat: complete Idris2 ABI — Foreign.idr + Proofs.idr -- feat: add Idris2 ABI proofs — TypeLL Levels 1-12 -- feat: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure - -### Fixed - -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#33) -- fix(ci): sync hypatia-scan.yml to canonical (#32) -- fix(ci): adopt canonical hypatia-scan.yml (#31) -- fix(ci): Phase-2 fleet submission must not fail the security gate (#30) -- fix(ci): hypatia-scan workdir (${{ env.HOME }} resolves empty) (#29) -- fix(januskey): sweep .expect("TODO: handle error") — 166 sites cleared -- fix: replace 60 unwrap() calls with expect() in security-critical modules -- fix: quote $$ and use printf in setup.sh -- fix: correct 'Provably Reversible' claim — proofs are pending, not done -- fix(scorecard): enforce granular permissions and add fuzzing placeholder - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs(security): draft MCP-exposure threat model (AI-authored, pending human sign-off) -- docs: add M2 estate audit report (2026-04-04) -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add ARCHITECTURE.md — reversibility stack junction point -- docs: update SCM files with project information -- docs: add CONTRIBUTING.md -- docs: add checkpoint files for state tracking - -### CI - -- ci(rust): convert rust-ci.yml to thin wrapper (standards#174) (#39) -- ci: redistribute concurrency-cancel guard to read-only check workflows (#35) -- ci: bump actions/upload-artifact SHA to current v4 (#27) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci: restore Dependabot security path + wire auto-merge - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index bbe9219..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,30 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..53ea74b --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/januskey.git cd januskey + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create januskey-dev toolbox enter januskey-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +januskey/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # Library code +(Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) ├── plugins/ +# Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) ├── docs/ # +Documentation (Perimeter 3) │ ├── architecture/ # ADRs, specs (Perimeter +2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ # Examples +(Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ # Test +suite (Perimeter 2-3) ├── .well-known/ # Protocol files (Perimeter 1-3) +├── .github/ # GitHub config (Perimeter 1) │ ├── ISSUE_TEMPLATE/ │ └── +workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md # +This file ├── GOVERNANCE.md ├── LICENSE ├── MAINTAINERS.md ├── +README.adoc ├── SECURITY.md ├── flake.nix # Nix flake (Perimeter 1) └── +Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/januskey/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/januskey/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/januskey/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/januskey/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index e5cf532..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/januskey.git -cd januskey - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create januskey-dev -toolbox enter januskey-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -januskey/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/januskey/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/januskey/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/januskey/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/januskey/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== 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/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..b471398 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,60 @@ +== PROOF-NEEDS.md — januskey + +=== Current State + +_Re-verified 2026-06-29 (idris2 0.8.0)._ + +* **src/abi/*.idr**: PRESENT but **placeholder** — +`+src/abi/Proofs.idr+` typechecks, but its theorems are +trivial/tautological (e.g. `+memoryDefeatsGPU : So (65536 >= 65536)+`, +`+timeCostMonotonic : So (a >= b) -> So (a >= b)+` returns its own +hypothesis). NOT the security proofs listed below. +* **generated/idrisiser/idris2/Januskey/Verified/*.idr**: **DO NOT +typecheck** — `+idris2 --check+` fails ("`Expected a capitalised +identifier, got: key`") because the generated module names are +lowercase. Despite the `+Verified/+` name, nothing there is currently +verified. +* *Dangerous patterns*: *265* `+unwrap()+` calls across the Rust +codebase. +* *LOC*: ~12,200 (Rust) +* *ABI layer*: present (`+src/abi/{Types,Foreign,Layout,Proofs}.idr+`) +but carries no load-bearing security proof yet — the real obligations +below are still open. + +=== What Needs Proving + +[width="100%",cols="51%,27%,22%",options="header",] +|=== +|Component |What |Why +|Obliteration correctness |Data erasure is complete and irreversible +|Core feature: must guarantee data is unrecoverable + +|Key derivation |Key generation produces cryptographically sound keys +|Weak keys break entire security model + +|Attestation chain |Chain of custody proofs are unforgeable |Tampered +attestations undermine trust + +|Content store integrity |Content-addressed storage never returns wrong +content |Hash collisions or bugs corrupt stored data + +|Transaction atomicity |Delta application is atomic and reversible +|Partial transactions corrupt state + +|reversible-core |Undo/redo preserves data integrity |Core crate used by +januskey-cli +|=== + +=== Recommended Prover + +*Idris2* — Create `+src/abi/+` with dependent type proofs for +obliteration completeness, attestation chain integrity, and transaction +atomicity. The 225 `+unwrap()+` calls should be systematically replaced +with proven error handling. + +=== Priority + +*HIGH* — JanusKey handles cryptographic key management, attestation +chains, and data obliteration. Any correctness bug in obliteration or +key derivation is a critical security vulnerability. Missing ABI layer +entirely. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index c06241f..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,41 +0,0 @@ - -# PROOF-NEEDS.md — januskey - -## Current State - -_Re-verified 2026-06-29 (idris2 0.8.0)._ - -- **src/abi/*.idr**: PRESENT but **placeholder** — `src/abi/Proofs.idr` typechecks, but its - theorems are trivial/tautological (e.g. `memoryDefeatsGPU : So (65536 >= 65536)`, - `timeCostMonotonic : So (a >= b) -> So (a >= b)` returns its own hypothesis). NOT the - security proofs listed below. -- **generated/idrisiser/idris2/Januskey/Verified/*.idr**: **DO NOT typecheck** — - `idris2 --check` fails ("Expected a capitalised identifier, got: key") because the - generated module names are lowercase. Despite the `Verified/` name, nothing there is - currently verified. -- **Dangerous patterns**: **265** `unwrap()` calls across the Rust codebase. -- **LOC**: ~12,200 (Rust) -- **ABI layer**: present (`src/abi/{Types,Foreign,Layout,Proofs}.idr`) but carries no - load-bearing security proof yet — the real obligations below are still open. - -## What Needs Proving - -| Component | What | Why | -|-----------|------|-----| -| Obliteration correctness | Data erasure is complete and irreversible | Core feature: must guarantee data is unrecoverable | -| Key derivation | Key generation produces cryptographically sound keys | Weak keys break entire security model | -| Attestation chain | Chain of custody proofs are unforgeable | Tampered attestations undermine trust | -| Content store integrity | Content-addressed storage never returns wrong content | Hash collisions or bugs corrupt stored data | -| Transaction atomicity | Delta application is atomic and reversible | Partial transactions corrupt state | -| reversible-core | Undo/redo preserves data integrity | Core crate used by januskey-cli | - -## Recommended Prover - -**Idris2** — Create `src/abi/` with dependent type proofs for obliteration completeness, attestation chain integrity, and transaction atomicity. The 225 `unwrap()` calls should be systematically replaced with proven error handling. - -## Priority - -**HIGH** — JanusKey handles cryptographic key management, attestation chains, and data obliteration. Any correctness bug in obliteration or key derivation is a critical security vulnerability. Missing ABI layer entirely. diff --git a/READINESS.adoc b/READINESS.adoc new file mode 100644 index 0000000..0acb094 --- /dev/null +++ b/READINESS.adoc @@ -0,0 +1,151 @@ +== Component Readiness Assessment — januskey + +*Assessed:* 2026-04-03 *Assessor:* Claude (automated) + Jonathan +(review) *Taxonomy:* +standards/testing-and-benchmarking/TESTING-TAXONOMY.adoc v1.0 + +*Current Grade:* D + +=== CRG Grade: D (Alpha — Unstable) + +*Justification:* Tests exist and pass (67 total), proofs exist (30 +Idris2, unchecked in CI), benchmarks exist (5 Criterion groups). But: no +fuzz testing, no mutation testing, 225 unwrap() calls, E2E mostly skips, +benchmarks measured fake crypto until this session. RSR compliance +present. Deep annotation incomplete (TOPOLOGY.md exists but +per-directory orientation missing → blocks C). + +*Promotion path D→C:* Fix unwrap() calls, wire Idris2 proof check in CI, +complete per-directory annotation, add real E2E with built binary, +dogfood in at least one real workflow. + +=== Test Category Matrix + +[width="100%",cols="9%,23%,18%,16%,18%,16%",options="header",] +|=== +|# |Category |Status |Count |Recipe |Notes +|1 |Unit |✓ |36 |`+just test+` |reversible-core + januskey-cli + +|2 |P2P |✓ |8 |`+just test-p2p+` |Component interaction across crates + +|3 |E2E |PARTIAL |1 script |`+just test-e2e+` |Mostly skips without +pre-built binary + +|4 |Build |✓ |CI |`+just build+` |cargo build –workspace –release + +|5 |Execution |N/A |— |— |Not an interpreter/VM + +|6 |Reflexive |✓ |1 |`+just doctor+` |Tool + path checks + +|7 |Lifecycle |PARTIAL |via P2P |— |Transaction begin/commit/rollback +tested; no resource cleanup tests + +|8 |Smoke |✓ |1 |`+just smoke+` |Build + version + help + +|9 |Property-based |✓ |9 |`+just test-property+` |proptest: roundtrip, +obliteration, key derivation, content store + +|10 |Mutation |MISSING |0 |— |cargo-mutants not yet configured + +|11 |Fuzz |MISSING |0 |— |Fake placeholder removed. Real fuzz not yet +implemented + +|12 |Contract |✓ |3 files |`+just test-contracts+` |Mustfile + Trustfile ++ Dustfile validated + +|13 |Regression |✓ |5 |`+just test-regressions+` |unwrap safety + error +handling + +|14 |Chaos |MISSING |0 |— |No resilience tests yet + +|15 |Compatibility |MISSING |0 |— |No version migration tests + +|16 |Proof regression |✓ |30 proofs |`+just test-proofs+` |Idris2 –check +(requires idris2 binary) +|=== + +*Total passing:* 67 tests + 5 benchmark groups + 30 Idris2 proofs *Total +missing:* Fuzz, mutation, chaos, compatibility + +=== Aspect Matrix + +[width="100%",cols="12%,27%,27%,34%",options="header",] +|=== +|# |Aspect |Status |Evidence +|1 |Dependability |PARTIAL |Transaction rollback tested. No crash +recovery tests. + +|2 |Security |PARTIAL |Obliteration tests, forbidden pattern checks. No +side-channel or memory-after-drop. + +|3 |Usability |PARTIAL |CLI exists. No user testing. + +|4 |Interoperability |PARTIAL |Zig FFI tests (15). No cross-language +integration test. + +|5 |Safety |✓ |0 believe_me, 0 assert_total. #![forbid(unsafe_code)]. +panic-attack assail passes. + +|6 |Performance |PARTIAL |5 Criterion benchmark groups. Baseline not yet +recorded in VeriSimDB. + +|7 |Functionality |PARTIAL |Core ops tested. Edge cases via proptest. +Feature matrix vs README not audited. + +|8 |Versability |MISSING |No version migration or semver compliance +tests. + +|9 |Accessibility |N/A |CLI tool. + +|10 |Maintainability |PARTIAL |TOPOLOGY.md exists. Per-directory +annotation incomplete. + +|11 |Privacy |N/A |Local tool, no network, no telemetry. + +|12 |Observability |MISSING |No structured logging. No tracing. + +|13 |Reproducibility |PARTIAL |Cargo.lock committed. Nix not configured. + +|14 |Portability |PARTIAL |Builds on Linux. macOS/Windows untested. +|=== + +=== Benchmark Classification + +[cols=",,",options="header",] +|=== +|Benchmark Group |Baseline (this run) |Classification +|Hashing |TBD — run `+just bench+` |Not yet baselined +|Content Store |TBD |Not yet baselined +|Obliteration |TBD |Not yet baselined +|Transactions |TBD |Not yet baselined +|Key Derivation |TBD |Not yet baselined +|=== + +Benchmarks now use real SHA256 (was DefaultHasher). First baseline needs +recording. + +=== Known Debt + +* 225 unwrap() calls (tracked in PROOF-NEEDS.md) +* E2E test needs pre-built binary to exercise full lifecycle +* Idris2 proofs not checked in CI (requires idris2 in CI image) +* No code coverage measurement +* No mutation testing +* Benchmarks not baselined in VeriSimDB + +=== Recipes + +.... +just test-all # Run everything +just test # Unit tests only +just test-p2p # Component interaction +just test-e2e # End-to-end (shell) +just test-aspect # Cross-cutting checks +just test-property # Property-based (proptest) +just test-regressions # Regression suite +just test-contracts # Contractile validation +just test-proofs # Idris2 proof regression +just bench # Criterion benchmarks +just smoke # Quick sanity check +just doctor # Self-diagnostic +.... diff --git a/READINESS.md b/READINESS.md deleted file mode 100644 index 04046d2..0000000 --- a/READINESS.md +++ /dev/null @@ -1,98 +0,0 @@ - -# Component Readiness Assessment — januskey - -**Assessed:** 2026-04-03 -**Assessor:** Claude (automated) + Jonathan (review) -**Taxonomy:** standards/testing-and-benchmarking/TESTING-TAXONOMY.adoc v1.0 - -**Current Grade:** D - -## CRG Grade: D (Alpha — Unstable) - -**Justification:** Tests exist and pass (67 total), proofs exist (30 Idris2, unchecked in CI), benchmarks exist (5 Criterion groups). But: no fuzz testing, no mutation testing, 225 unwrap() calls, E2E mostly skips, benchmarks measured fake crypto until this session. RSR compliance present. Deep annotation incomplete (TOPOLOGY.md exists but per-directory orientation missing → blocks C). - -**Promotion path D→C:** Fix unwrap() calls, wire Idris2 proof check in CI, complete per-directory annotation, add real E2E with built binary, dogfood in at least one real workflow. - -## Test Category Matrix - -| # | Category | Status | Count | Recipe | Notes | -|---|----------|--------|-------|--------|-------| -| 1 | Unit | ✓ | 36 | `just test` | reversible-core + januskey-cli | -| 2 | P2P | ✓ | 8 | `just test-p2p` | Component interaction across crates | -| 3 | E2E | PARTIAL | 1 script | `just test-e2e` | Mostly skips without pre-built binary | -| 4 | Build | ✓ | CI | `just build` | cargo build --workspace --release | -| 5 | Execution | N/A | — | — | Not an interpreter/VM | -| 6 | Reflexive | ✓ | 1 | `just doctor` | Tool + path checks | -| 7 | Lifecycle | PARTIAL | via P2P | — | Transaction begin/commit/rollback tested; no resource cleanup tests | -| 8 | Smoke | ✓ | 1 | `just smoke` | Build + version + help | -| 9 | Property-based | ✓ | 9 | `just test-property` | proptest: roundtrip, obliteration, key derivation, content store | -| 10 | Mutation | MISSING | 0 | — | cargo-mutants not yet configured | -| 11 | Fuzz | MISSING | 0 | — | Fake placeholder removed. Real fuzz not yet implemented | -| 12 | Contract | ✓ | 3 files | `just test-contracts` | Mustfile + Trustfile + Dustfile validated | -| 13 | Regression | ✓ | 5 | `just test-regressions` | unwrap safety + error handling | -| 14 | Chaos | MISSING | 0 | — | No resilience tests yet | -| 15 | Compatibility | MISSING | 0 | — | No version migration tests | -| 16 | Proof regression | ✓ | 30 proofs | `just test-proofs` | Idris2 --check (requires idris2 binary) | - -**Total passing:** 67 tests + 5 benchmark groups + 30 Idris2 proofs -**Total missing:** Fuzz, mutation, chaos, compatibility - -## Aspect Matrix - -| # | Aspect | Status | Evidence | -|---|--------|--------|----------| -| 1 | Dependability | PARTIAL | Transaction rollback tested. No crash recovery tests. | -| 2 | Security | PARTIAL | Obliteration tests, forbidden pattern checks. No side-channel or memory-after-drop. | -| 3 | Usability | PARTIAL | CLI exists. No user testing. | -| 4 | Interoperability | PARTIAL | Zig FFI tests (15). No cross-language integration test. | -| 5 | Safety | ✓ | 0 believe_me, 0 assert_total. #![forbid(unsafe_code)]. panic-attack assail passes. | -| 6 | Performance | PARTIAL | 5 Criterion benchmark groups. Baseline not yet recorded in VeriSimDB. | -| 7 | Functionality | PARTIAL | Core ops tested. Edge cases via proptest. Feature matrix vs README not audited. | -| 8 | Versability | MISSING | No version migration or semver compliance tests. | -| 9 | Accessibility | N/A | CLI tool. | -| 10 | Maintainability | PARTIAL | TOPOLOGY.md exists. Per-directory annotation incomplete. | -| 11 | Privacy | N/A | Local tool, no network, no telemetry. | -| 12 | Observability | MISSING | No structured logging. No tracing. | -| 13 | Reproducibility | PARTIAL | Cargo.lock committed. Nix not configured. | -| 14 | Portability | PARTIAL | Builds on Linux. macOS/Windows untested. | - -## Benchmark Classification - -| Benchmark Group | Baseline (this run) | Classification | -|-----------------|--------------------|----| -| Hashing | TBD — run `just bench` | Not yet baselined | -| Content Store | TBD | Not yet baselined | -| Obliteration | TBD | Not yet baselined | -| Transactions | TBD | Not yet baselined | -| Key Derivation | TBD | Not yet baselined | - -Benchmarks now use real SHA256 (was DefaultHasher). First baseline needs recording. - -## Known Debt - -- 225 unwrap() calls (tracked in PROOF-NEEDS.md) -- E2E test needs pre-built binary to exercise full lifecycle -- Idris2 proofs not checked in CI (requires idris2 in CI image) -- No code coverage measurement -- No mutation testing -- Benchmarks not baselined in VeriSimDB - -## Recipes - -``` -just test-all # Run everything -just test # Unit tests only -just test-p2p # Component interaction -just test-e2e # End-to-end (shell) -just test-aspect # Cross-cutting checks -just test-property # Property-based (proptest) -just test-regressions # Regression suite -just test-contracts # Contractile validation -just test-proofs # Idris2 proof regression -just bench # Criterion benchmarks -just smoke # Quick sanity check -just doctor # Self-diagnostic -``` diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..ffcf723 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,66 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|latest |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +If you discover a security vulnerability in this project, please report +it responsibly. + +==== How to Report + +[arabic] +. *Do NOT* create a public GitHub issue for security vulnerabilities +. Email: rhodium-standard@proton.me +. Or use GitHub’s private vulnerability reporting if enabled + +==== Include in Your Report + +* Description of the vulnerability +* Steps to reproduce +* Potential impact +* Suggested fix (optional) + +==== Response Timeline + +* *Acknowledgment*: Within 48 hours +* *Initial Assessment*: Within 7 days +* *Resolution Target*: Within 30 days for critical issues + +==== What to Expect + +[arabic] +. Acknowledgment of your report +. Regular updates on progress +. Credit in release notes (unless you prefer anonymity) +. Coordinated disclosure timeline + +=== Security Measures + +==== Supply Chain Security + +* All GitHub Actions pinned to SHA hashes +* SPDX license headers on source files +* Dependency auditing via Scorecard + +==== Code Security + +* HTTPS only for all external URLs +* No hardcoded secrets +* Automated secret scanning via TruffleHog + +=== Scope + +This security policy applies to: - The januskey project - Official +releases - Documentation + +=== Out of Scope + +* Third-party forks or modifications +* Vulnerabilities in dependencies (report to respective maintainers) diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index de264af..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,67 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| latest | :white_check_mark: | - -## Reporting a Vulnerability - -If you discover a security vulnerability in this project, please report it responsibly. - -### How to Report - -1. **Do NOT** create a public GitHub issue for security vulnerabilities -2. Email: rhodium-standard@proton.me -3. Or use GitHub's private vulnerability reporting if enabled - -### Include in Your Report - -- Description of the vulnerability -- Steps to reproduce -- Potential impact -- Suggested fix (optional) - -### Response Timeline - -- **Acknowledgment**: Within 48 hours -- **Initial Assessment**: Within 7 days -- **Resolution Target**: Within 30 days for critical issues - -### What to Expect - -1. Acknowledgment of your report -2. Regular updates on progress -3. Credit in release notes (unless you prefer anonymity) -4. Coordinated disclosure timeline - -## Security Measures - -### Supply Chain Security - -- All GitHub Actions pinned to SHA hashes -- SPDX license headers on source files -- Dependency auditing via Scorecard - -### Code Security - -- HTTPS only for all external URLs -- No hardcoded secrets -- Automated secret scanning via TruffleHog - -## Scope - -This security policy applies to: -- The januskey project -- Official releases -- Documentation - -## Out of Scope - -- Third-party forks or modifications -- Vulnerabilities in dependencies (report to respective maintainers) diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..d483fa3 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,123 @@ +== TEST-NEEDS.md — januskey + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +____ +Generated 2026-03-29 by punishing audit. Updated 2026-04-04 (CRG D→C +blitz). +____ + +=== Current State (CRG C - COMPLETE) + +[width="100%",cols="50%,25%,25%",options="header",] +|=== +|Category |Count |Notes +|Unit tests |24 |Inline `+#[test]+` in source: attestation(4), +content_store(4), delta(4), keys(4), metadata(3), obliteration(7), +operations(4), transaction(3), lib(1) + +|P2P (Property) |6 |`+crates/januskey-cli/tests/p2p_test.rs+`: +content↔metadata, keys↔attestation, transaction↔operations roundtrips + +|E2E |7 |`+crates/januskey-cli/tests/e2e_test.rs+`: full lifecycle, +multi-key txns, delta chains, roundtrips, error cases + +|Aspect (Security) |6 |`+crates/januskey-cli/tests/aspect_test.rs+`: +obliteration unrecoverability, DoD compliance, proof generation, +concurrent erasure + +|Concurrency |5 |`+crates/januskey-cli/tests/concurrency_test.rs+`: +concurrent key ops, transaction isolation, content store concurrency, +race condition safety + +|Benchmarks |8 |Criterion: hashing(6 sizes), content_store(3), +obliteration(3), transactions(2), key_derivation(1), attestation(3), +delta(2), metadata(2) +|=== + +*Source modules:* ~26 Rust source files across januskey crate + +=== What’s DONE (CRG C - COMPLETE) + +==== P2P (Property-Based) Tests ✅ + +* [x] Content↔metadata roundtrips with hash verification +* [x] Key↔attestation linkage and entry creation +* [x] Transaction↔operations grouping and consistency +* [x] Deduplication verification (content-addressed storage) +* [x] Attestation chain integrity (3-link verification) + +==== E2E Tests ✅ + +* [x] Full key lifecycle: generate → store → attest → retrieve +* [x] Multi-key transaction: 3 keys, 3 operations, commit verification +* [x] Delta chain: 3-version evolution with full history recovery +* [x] Content store roundtrip: write → verify hash → read → delete → +unrecoverable +* [x] Deduplication across multiple keys (single physical copy) +* [x] Error cases: nonexistent key reads, malformed JSON detection + +==== Aspect Tests (Security-Critical) ✅ + +* [x] *Obliteration unrecoverability*: 3-pass DoD 5220.22-M overwrites +verified, file deletion confirmed +* [x] *Revocation marking*: Obliterated keys marked "`revoked`" with +proof references +* [x] *DoD compliance*: Exactly 3 passes (0x00, 0xFF, 0x00) verified in +sequence +* [x] *Obliteration proofs*: Proofs generated with content hash, +timestamp, commitment +* [x] *Concurrent access*: Obliteration during concurrent reads doesn’t +leak data +* [x] *Independent obliteration*: Multiple keys can be obliterated +selectively without affecting others + +==== Concurrency Tests ✅ + +* [x] Concurrent key operations (10 threads): no deadlock, all succeed +* [x] Transaction isolation: uncommitted changes invisible until commit +* [x] Concurrent transactions: 5 independent transactions run +concurrently +* [x] Content store concurrency: 20 concurrent writers all succeed +without collision +* [x] Race condition safety: commit/rollback races don’t corrupt state + +==== Benchmarks ✅ + +* [x] *Hashing (sha2)*: 6 sizes from 32B to 1MB +* [x] *Content store*: write/retrieve/dedup ops with real SHA256 +* [x] *Obliteration*: 3-pass overwrite at 1KB/4KB/64KB sizes +* [x] *Transactions*: begin/commit overhead, operation log append +* [x] *Key derivation*: SHA256 PBKDF chain (1000 iterations) +* [x] *Attestation*: entry generation, audit log append, signature +verification +* [x] *Delta operations*: diff computation (3 sizes), 10-link chain +verification +* [x] *Metadata*: JSON serialization/deserialization roundtrips + +=== CRG Grades + +*ACHIEVED: CRG C* (from CRG D after 2026-04-04 blitz) + +* 24 unit tests (existing) +* 6 P2P property tests (new) +* 7 E2E integration tests (new) +* 6 aspect/security tests (new) — CRITICAL for key management +* 5 concurrency tests (new) +* 8 criterion benchmarks (extended) + +*Total: 56 tests + 8 benchmarks = 64 verification points* + +CRG C requirements met: ✅ P2P property tests (delta roundtrips, ACID +verification, attestation invariants) ✅ E2E tests (full key lifecycle, +multi-key transactions, content store roundtrips) ✅ Aspect tests +(security: obliteration, concurrency, isolation) ✅ Benchmarks baselined +(6+ categories, 20+ measurement points) + +=== 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 4ccefce..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,89 +0,0 @@ - -# TEST-NEEDS.md — januskey - -## CRG Grade: C — ACHIEVED 2026-04-04 - -> Generated 2026-03-29 by punishing audit. Updated 2026-04-04 (CRG D→C blitz). - -## Current State (CRG C - COMPLETE) - -| Category | Count | Notes | -|-------------|-------|-------| -| Unit tests | 24 | Inline `#[test]` in source: attestation(4), content_store(4), delta(4), keys(4), metadata(3), obliteration(7), operations(4), transaction(3), lib(1) | -| P2P (Property) | 6 | `crates/januskey-cli/tests/p2p_test.rs`: content↔metadata, keys↔attestation, transaction↔operations roundtrips | -| E2E | 7 | `crates/januskey-cli/tests/e2e_test.rs`: full lifecycle, multi-key txns, delta chains, roundtrips, error cases | -| Aspect (Security) | 6 | `crates/januskey-cli/tests/aspect_test.rs`: obliteration unrecoverability, DoD compliance, proof generation, concurrent erasure | -| Concurrency | 5 | `crates/januskey-cli/tests/concurrency_test.rs`: concurrent key ops, transaction isolation, content store concurrency, race condition safety | -| Benchmarks | 8 | Criterion: hashing(6 sizes), content_store(3), obliteration(3), transactions(2), key_derivation(1), attestation(3), delta(2), metadata(2) | - -**Source modules:** ~26 Rust source files across januskey crate - -## What's DONE (CRG C - COMPLETE) - -### P2P (Property-Based) Tests ✅ -- [x] Content↔metadata roundtrips with hash verification -- [x] Key↔attestation linkage and entry creation -- [x] Transaction↔operations grouping and consistency -- [x] Deduplication verification (content-addressed storage) -- [x] Attestation chain integrity (3-link verification) - -### E2E Tests ✅ -- [x] Full key lifecycle: generate → store → attest → retrieve -- [x] Multi-key transaction: 3 keys, 3 operations, commit verification -- [x] Delta chain: 3-version evolution with full history recovery -- [x] Content store roundtrip: write → verify hash → read → delete → unrecoverable -- [x] Deduplication across multiple keys (single physical copy) -- [x] Error cases: nonexistent key reads, malformed JSON detection - -### Aspect Tests (Security-Critical) ✅ -- [x] **Obliteration unrecoverability**: 3-pass DoD 5220.22-M overwrites verified, file deletion confirmed -- [x] **Revocation marking**: Obliterated keys marked "revoked" with proof references -- [x] **DoD compliance**: Exactly 3 passes (0x00, 0xFF, 0x00) verified in sequence -- [x] **Obliteration proofs**: Proofs generated with content hash, timestamp, commitment -- [x] **Concurrent access**: Obliteration during concurrent reads doesn't leak data -- [x] **Independent obliteration**: Multiple keys can be obliterated selectively without affecting others - -### Concurrency Tests ✅ -- [x] Concurrent key operations (10 threads): no deadlock, all succeed -- [x] Transaction isolation: uncommitted changes invisible until commit -- [x] Concurrent transactions: 5 independent transactions run concurrently -- [x] Content store concurrency: 20 concurrent writers all succeed without collision -- [x] Race condition safety: commit/rollback races don't corrupt state - -### Benchmarks ✅ -- [x] **Hashing (sha2)**: 6 sizes from 32B to 1MB -- [x] **Content store**: write/retrieve/dedup ops with real SHA256 -- [x] **Obliteration**: 3-pass overwrite at 1KB/4KB/64KB sizes -- [x] **Transactions**: begin/commit overhead, operation log append -- [x] **Key derivation**: SHA256 PBKDF chain (1000 iterations) -- [x] **Attestation**: entry generation, audit log append, signature verification -- [x] **Delta operations**: diff computation (3 sizes), 10-link chain verification -- [x] **Metadata**: JSON serialization/deserialization roundtrips - -## CRG Grades - -**ACHIEVED: CRG C** (from CRG D after 2026-04-04 blitz) - -- 24 unit tests (existing) -- 6 P2P property tests (new) -- 7 E2E integration tests (new) -- 6 aspect/security tests (new) — CRITICAL for key management -- 5 concurrency tests (new) -- 8 criterion benchmarks (extended) - -**Total: 56 tests + 8 benchmarks = 64 verification points** - -CRG C requirements met: -✅ P2P property tests (delta roundtrips, ACID verification, attestation invariants) -✅ E2E tests (full key lifecycle, multi-key transactions, content store roundtrips) -✅ Aspect tests (security: obliteration, concurrency, isolation) -✅ Benchmarks baselined (6+ categories, 20+ measurement points) - -## 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 84% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 1a81cbb..44317e6 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== JanusKey — Project Topology -# JanusKey — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ OPERATOR / CLI │ │ (jk delete, jk modify, jk undo) │ @@ -49,19 +42,21 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile / Cargo .machine_readable/ │ │ MAAF Integration 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -> **Source of truth:** `.machine_readable/6a2/STATE.a2ml` (completion 60%, -> CRG grade **D**) and `READINESS.md` (Grade **D — Alpha, Unstable**). This -> dashboard is a human-readable summary of those files; if they disagree, -> they win. Percentages below are qualitative, not measured coverage. -> This agreement is now **machine-enforced**: `just check-dashboard` -> (crate `crates/dashboard-check`, CI job `Dashboard Check`) fails the build -> if the `OVERALL` percentage or grade here drifts from STATE.a2ml. +____ +*Source of truth:* `+.machine_readable/6a2/STATE.a2ml+` (completion 60%, +CRG grade *D*) and `+READINESS.md+` (Grade *D — Alpha, Unstable*). This +dashboard is a human-readable summary of those files; if they disagree, +they win. Percentages below are qualitative, not measured coverage. This +agreement is now *machine-enforced*: `+just check-dashboard+` (crate +`+crates/dashboard-check+`, CI job `+Dashboard Check+`) fails the build +if the `+OVERALL+` percentage or grade here drifts from STATE.a2ml. +____ -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE ENGINE (RUST) @@ -93,25 +88,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████░░░░ ~60% Grade D — Alpha, Unstable (not v1.0) -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... jk command ──────► Inverse Meta ──────► Transaction Mgr ──────► Commit │ │ │ │ ▼ ▼ ▼ ▼ Source File ─────► SHA256 Store ─────► Metadata Log ───────► Rollback -``` +.... -## 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). diff --git a/docs/reports/audit/audit-2026-04-04.adoc b/docs/reports/audit/audit-2026-04-04.adoc new file mode 100644 index 0000000..2a53db3 --- /dev/null +++ b/docs/reports/audit/audit-2026-04-04.adoc @@ -0,0 +1,110 @@ +== Audit Report — januskey (2026-04-04) + +=== Summary + +JanusKey is a reversible file operations utility achieving complete +reversibility through architectural design. The codebase demonstrates +excellent RSR compliance, mature safety practices +(#![forbid(unsafe_code)]), and active proof coverage. Zero dangerous +patterns detected. A well-engineered, publication-ready +security-critical tool. + +=== Findings + +==== Critical + +* *ZERO dangerous patterns* — No believe_me, assert_total, Admitted, +sorry, unsafeCoerce, or Obj.magic detected +* *Forbid unsafe code* — #![forbid(unsafe_code)] enforced at crate root +* *RSR Certified* — All compliance artifacts present and maintained + +==== High + +None identified. + +==== Medium + +* Test infrastructure exists but full inventory needs discovery +* CI workflows active (14 files) with no obvious failures + +=== RSR Compliance + +* *EXPLAINME.adoc*: present ✓ +* *0-AI-MANIFEST.a2ml*: present ✓ +* *.machine_readable/*: present ✓ +* *SECURITY.md*: present ✓ +* *CONTRIBUTING.md*: present ✓ + +=== Test Coverage + +JanusKey includes comprehensive testing: + +* *Rust unit tests*: reversible_core, januskey libraries +* *Integration tests*: p2p_test, e2e_test, aspect_test, +concurrency_test, property_tests +* *Safety tests*: unwrap_safety_test (panic-free validation) +* *Benchmark suites*: januskey_benchmarks +* *Test infrastructure*: Comprehensive proptest/quickcheck coverage +* *Safety scanning*: panic-attack scan results documented in +READINESS.md (line 46) + +=== Proof Debt + +*Status: CLEAN* + +From READINESS.md (line 46): - "`0 believe_me, 0 assert_total. +#![forbid(unsafe_code)]. panic-attack assail passes.`" + +Dangerous pattern status: - believe_me: 0 (Idris2 ABI verified) - +assert_total: 0 (Idris2 ABI verified) - Admitted: 0 (Coq policies +enforced) - sorry: 0 (verified) - unsafeCoerce: 0 (Haskell ban enforced) +- Obj.magic: 0 (ReScript ban enforced) + +Proof practices enforced: - tests/aspect/cross_cutting_test.sh (line +35-36): Automated scanning for believe_me, assert_total - +Machine-readable policies (MUST.contractile): Bans dangerous patterns - +Idris2 ABI integrity documented + +=== Publication Safety + +*Explicit safety claim*: "`0 believe_me, 0 assert_total. +#![forbid(unsafe_code)]. panic-attack assail passes.`" + +This is fully backed by: 1. Rust forbid unsafe code at crate level 2. +Automated cross-cutting tests for dangerous patterns 3. Safety audit +results (panic-attack scan) 4. Test coverage for reversibility proofs + +*Evidence*: READINESS.md documents safety posture clearly. + +=== CI Health + +*Status: MATURE* + +Active workflows (14 files): - boj-build.yml — Build orchestration - +codeql.yml — CodeQL security scanning - quality.yml — Code quality +checks - semgrep.yml — Security pattern scanning - workflow-linter.yml — +CI integrity - npm-bun-blocker.yml, ts-blocker.yml — Language +enforcement - security-policy.yml, secret-scanner.yml — Security +scanning - scorecard.yml — OpenSSF scorecard validation - +wellknown-enforcement.yml — Standards compliance - instant-sync.yml — +Git mirroring + +*No failures detected*. All workflows properly configured with SHA pins. + +=== Verdict + +*PUBLISHABLE NOW* + +JanusKey is a mature, safety-engineered tool ready for production use. +The reversibility claims are backed by: 1. Comprehensive property-based +testing 2. Integration tests covering all operations 3. Safety +guarantees enforced via #![forbid(unsafe_code)] 4. Panic-safe validation +(panic-attack assail passes) 5. Complete RSR compliance + +No repairs needed. This project exemplifies responsible Rust systems +programming. + +''''' + +*Audited by*: M2 estate audit (2026-04-04) *Confidence*: HIGH +*Recommendation*: SHIP AS-IS diff --git a/docs/reports/audit/audit-2026-04-04.md b/docs/reports/audit/audit-2026-04-04.md deleted file mode 100644 index 33b9eb1..0000000 --- a/docs/reports/audit/audit-2026-04-04.md +++ /dev/null @@ -1,114 +0,0 @@ - -# Audit Report — januskey (2026-04-04) - -## Summary - -JanusKey is a reversible file operations utility achieving complete reversibility through architectural design. The codebase demonstrates excellent RSR compliance, mature safety practices (#![forbid(unsafe_code)]), and active proof coverage. Zero dangerous patterns detected. A well-engineered, publication-ready security-critical tool. - -## Findings - -### Critical - -- **ZERO dangerous patterns** — No believe_me, assert_total, Admitted, sorry, unsafeCoerce, or Obj.magic detected -- **Forbid unsafe code** — #![forbid(unsafe_code)] enforced at crate root -- **RSR Certified** — All compliance artifacts present and maintained - -### High - -None identified. - -### Medium - -- Test infrastructure exists but full inventory needs discovery -- CI workflows active (14 files) with no obvious failures - -## RSR Compliance - -- **EXPLAINME.adoc**: present ✓ -- **0-AI-MANIFEST.a2ml**: present ✓ -- **.machine_readable/**: present ✓ -- **SECURITY.md**: present ✓ -- **CONTRIBUTING.md**: present ✓ - -## Test Coverage - -JanusKey includes comprehensive testing: - -- **Rust unit tests**: reversible_core, januskey libraries -- **Integration tests**: p2p_test, e2e_test, aspect_test, concurrency_test, property_tests -- **Safety tests**: unwrap_safety_test (panic-free validation) -- **Benchmark suites**: januskey_benchmarks -- **Test infrastructure**: Comprehensive proptest/quickcheck coverage -- **Safety scanning**: panic-attack scan results documented in READINESS.md (line 46) - -## Proof Debt - -**Status: CLEAN** - -From READINESS.md (line 46): -- "0 believe_me, 0 assert_total. #![forbid(unsafe_code)]. panic-attack assail passes." - -Dangerous pattern status: -- believe_me: 0 (Idris2 ABI verified) -- assert_total: 0 (Idris2 ABI verified) -- Admitted: 0 (Coq policies enforced) -- sorry: 0 (verified) -- unsafeCoerce: 0 (Haskell ban enforced) -- Obj.magic: 0 (ReScript ban enforced) - -Proof practices enforced: -- tests/aspect/cross_cutting_test.sh (line 35-36): Automated scanning for believe_me, assert_total -- Machine-readable policies (MUST.contractile): Bans dangerous patterns -- Idris2 ABI integrity documented - -## Publication Safety - -**Explicit safety claim**: "0 believe_me, 0 assert_total. #![forbid(unsafe_code)]. panic-attack assail passes." - -This is fully backed by: -1. Rust forbid unsafe code at crate level -2. Automated cross-cutting tests for dangerous patterns -3. Safety audit results (panic-attack scan) -4. Test coverage for reversibility proofs - -**Evidence**: READINESS.md documents safety posture clearly. - -## CI Health - -**Status: MATURE** - -Active workflows (14 files): -- boj-build.yml — Build orchestration -- codeql.yml — CodeQL security scanning -- quality.yml — Code quality checks -- semgrep.yml — Security pattern scanning -- workflow-linter.yml — CI integrity -- npm-bun-blocker.yml, ts-blocker.yml — Language enforcement -- security-policy.yml, secret-scanner.yml — Security scanning -- scorecard.yml — OpenSSF scorecard validation -- wellknown-enforcement.yml — Standards compliance -- instant-sync.yml — Git mirroring - -**No failures detected**. All workflows properly configured with SHA pins. - -## Verdict - -**PUBLISHABLE NOW** - -JanusKey is a mature, safety-engineered tool ready for production use. The reversibility claims are backed by: -1. Comprehensive property-based testing -2. Integration tests covering all operations -3. Safety guarantees enforced via #![forbid(unsafe_code)] -4. Panic-safe validation (panic-attack assail passes) -5. Complete RSR compliance - -No repairs needed. This project exemplifies responsible Rust systems programming. - ---- - -**Audited by**: M2 estate audit (2026-04-04) -**Confidence**: HIGH -**Recommendation**: SHIP AS-IS diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..bccb564 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,88 @@ +== Tech-Debt Audit — januskey — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+LOW+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +Scanner counted the following markers in proof-bearing files of this +repo: + +.... +files= 7 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 1 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 +.... + +*Total markers:* 1. *Severity:* `+>01+`. + +*Marker types* (any non-zero counts above): - Coq `+Axiom+`/`+Admitted+` +— unconditional proof escapes. - Lean `+sorry+`/`+axiom+` — Lean’s +equivalent. - Agda `+postulate+` — accepted axiomatically. - Idris2 +`+believe_me+`/`+assert_total+` — runtime-safe coercion / totality +assumption. - Idris2 top-level `+partial+` — totality-check waived. - F* +`+assume val+`/`+admit_p+` — F* admit. - `+TODO PROOF+` / `+OWED:+` — +self-documented debt markers. - `+unsafePerformIO+`/`+unsafeCoerce+` — +soundness-relevant escape hatches in Haskell/Rust source. + +*Recommended next move:* triage each finding into one of: (a) discharge +by proof, (b) cover with property-tests + a documented refutation +budget, or (c) annotate as a known/necessary axiom (e.g. `+funExt+`) in +`+docs/proof-debt.md+`. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+MIT OR MPL-2.0+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |161 +|`+docs/+` files |18 +|`+docs/+` LoC |6288 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+LOW+` +|=== + +*Recommended next move:* `+docs/+` has only 18 file(s). Aim for ≥10 +organised docs (architecture, usage, contributing-guide, +troubleshooting, design-decisions). The user’s bar for a +"`heavily-developed and well-organised wiki`" is ≥10 files with topical +organisation. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 6d691de..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,72 +0,0 @@ - -# Tech-Debt Audit — januskey — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `LOW`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 7 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 1 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 -``` - -**Total markers:** 1. **Severity:** `>01`. - -**Marker types** (any non-zero counts above): -- Coq `Axiom`/`Admitted` — unconditional proof escapes. -- Lean `sorry`/`axiom` — Lean's equivalent. -- Agda `postulate` — accepted axiomatically. -- Idris2 `believe_me`/`assert_total` — runtime-safe coercion / totality assumption. -- Idris2 top-level `partial` — totality-check waived. -- F\* `assume val`/`admit_p` — F\* admit. -- `TODO PROOF` / `OWED:` — self-documented debt markers. -- `unsafePerformIO`/`unsafeCoerce` — soundness-relevant escape hatches in Haskell/Rust source. - -**Recommended next move:** triage each finding into one of: (a) discharge by proof, (b) cover with property-tests + a documented refutation budget, or (c) annotate as a known/necessary axiom (e.g. `funExt`) in `docs/proof-debt.md`. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `MIT OR MPL-2.0` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 161 | -| `docs/` files | 18 | -| `docs/` LoC | 6288 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `LOW` | - -**Recommended next move:** `docs/` has only 18 file(s). Aim for ≥10 organised docs (architecture, usage, contributing-guide, troubleshooting, design-decisions). The user's bar for a "heavily-developed and well-organised wiki" is ≥10 files with topical organisation. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..c30d282 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — januskey (Developer) + +=== What is januskey? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index e4ffe49..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — januskey (Developer) - -## What is januskey? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..28285f1 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — januskey (User) + +=== What is januskey? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 012064d..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — januskey (User) - -## What is januskey? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture