diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..3a3b7f2 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,34 @@ +# SPDX-License-Identifier: MPL-2.0 +# CODEOWNERS - Define code review assignments for GitHub +# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# Default: sole maintainer for all files +* @hyperpolymath + +# Security-sensitive files require explicit ownership +SECURITY.md @hyperpolymath +.github/workflows/ @hyperpolymath +.machine_readable/ @hyperpolymath +contractiles/ @hyperpolymath + +# License files +LICENSE @hyperpolymath +LICENSES/ @hyperpolymath + +# Configuration +.gitignore @hyperpolymath +.github/ @hyperpolymath + +# Documentation +README* @hyperpolymath +CONTRIBUTING* @hyperpolymath +CODE_OF_CONDUCT* @hyperpolymath +GOVERNANCE* @hyperpolymath +MAINTAINERS* @hyperpolymath +CHANGELOG* @hyperpolymath +ROADMAP* @hyperpolymath + +# Build and CI +Justfile @hyperpolymath +Makefile @hyperpolymath +*.sh @hyperpolymath diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 987aab6..45a6c02 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,3 +1,7 @@ + --- name: Bug report about: Create a report to help us improve diff --git a/.github/ISSUE_TEMPLATE/custom.md b/.github/ISSUE_TEMPLATE/custom.md index 48d5f81..99ebf00 100644 --- a/.github/ISSUE_TEMPLATE/custom.md +++ b/.github/ISSUE_TEMPLATE/custom.md @@ -1,3 +1,7 @@ + --- name: Custom issue template about: Describe this issue template's purpose here. diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md index 4fcb9f9..b1d16df 100644 --- a/.github/ISSUE_TEMPLATE/documentation.md +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -1,3 +1,7 @@ + --- name: Documentation about: Report unclear, missing, or incorrect documentation diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 3e8fa7e..a5a5693 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,3 +1,7 @@ + --- name: Feature request about: Suggest an idea for this project diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md index fd0e2a5..c2d1f57 100644 --- a/.github/ISSUE_TEMPLATE/question.md +++ b/.github/ISSUE_TEMPLATE/question.md @@ -1,3 +1,7 @@ + --- name: Question about: Ask a question about usage or behaviour diff --git a/.github/copilot/coding-agent.yml b/.github/copilot/coding-agent.yml new file mode 100644 index 0000000..a719a77 --- /dev/null +++ b/.github/copilot/coding-agent.yml @@ -0,0 +1,6 @@ +mcp_servers: + boj-server: + command: npx + args: ["-y", "@hyperpolymath/boj-server@latest"] + env: + BOJ_URL: http://localhost:7700 diff --git a/.github/workflows/boj-build.yml b/.github/workflows/boj-build.yml index 7868fbf..144e367 100644 --- a/.github/workflows/boj-build.yml +++ b/.github/workflows/boj-build.yml @@ -7,6 +7,7 @@ on: jobs: trigger-boj: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 diff --git a/.github/workflows/cargo-audit.yml b/.github/workflows/cargo-audit.yml index b3790ce..f938ce2 100644 --- a/.github/workflows/cargo-audit.yml +++ b/.github/workflows/cargo-audit.yml @@ -20,6 +20,7 @@ permissions: read-all jobs: audit: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4 @@ -35,6 +36,7 @@ jobs: # Optional: Create issues for vulnerabilities create-issue: runs-on: ubuntu-latest + timeout-minutes: 15 needs: audit if: failure() permissions: diff --git a/.github/workflows/casket-pages.yml b/.github/workflows/casket-pages.yml index 55d2a13..7e8cb6e 100644 --- a/.github/workflows/casket-pages.yml +++ b/.github/workflows/casket-pages.yml @@ -18,6 +18,7 @@ concurrency: jobs: build: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4 @@ -109,6 +110,7 @@ jobs: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest + timeout-minutes: 15 needs: build steps: - name: Deploy to GitHub Pages diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index e411645..964ef8c 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -1,4 +1,4 @@ -# SPDX-License-Identifier: PMPL-1.0 +# SPDX-License-Identifier: MPL-2.0 name: CodeQL Security Analysis on: @@ -7,7 +7,7 @@ on: pull_request: branches: [main, master] schedule: - - cron: '0 6 * * 1' + - cron: '0 6 1 * *' # monthly 1st 06:00 UTC # Estate guardrail: cancel superseded runs so re-pushes / rebased PR # updates do not pile up queued runs against the shared account-wide @@ -23,6 +23,7 @@ permissions: jobs: analyze: runs-on: ubuntu-latest + timeout-minutes: 15 permissions: contents: read security-events: write @@ -30,7 +31,12 @@ jobs: fail-fast: false matrix: include: - - language: javascript-typescript + # januskey has no JavaScript/TypeScript source — the + # javascript-typescript extractor errors with "no source code seen" + # (exit 32, configuration error). CodeQL's GitHub Actions analysis + # scans the workflow YAML that does exist here, keeping this a + # meaningful security check (same fix as oblibeny + maa-framework). + - language: actions build-mode: none steps: diff --git a/.github/workflows/dependabot-automerge.yml b/.github/workflows/dependabot-automerge.yml index ca86baa..3d0e8de 100644 --- a/.github/workflows/dependabot-automerge.yml +++ b/.github/workflows/dependabot-automerge.yml @@ -50,6 +50,7 @@ jobs: # Only run for PRs actually authored by Dependabot. if: github.actor == 'dependabot[bot]' && github.event.pull_request.user.login == 'dependabot[bot]' runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Fetch Dependabot metadata diff --git a/.github/workflows/dogfood-gate.yml b/.github/workflows/dogfood-gate.yml index 155980a..0868396 100644 --- a/.github/workflows/dogfood-gate.yml +++ b/.github/workflows/dogfood-gate.yml @@ -22,6 +22,7 @@ jobs: a2ml-validate: name: Validate A2ML manifests runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout repository @@ -66,6 +67,7 @@ jobs: k9-validate: name: Validate K9 contracts runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout repository @@ -115,6 +117,7 @@ jobs: empty-lint: name: Empty-linter (invisible characters) runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout repository @@ -179,6 +182,7 @@ jobs: groove-check: name: Groove manifest check runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Checkout repository @@ -237,6 +241,7 @@ jobs: dogfood-summary: name: Dogfooding compliance summary runs-on: ubuntu-latest + timeout-minutes: 15 needs: [a2ml-validate, k9-validate, empty-lint, groove-check] if: always() diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml index ab50602..85c4c62 100644 --- a/.github/workflows/e2e.yml +++ b/.github/workflows/e2e.yml @@ -14,6 +14,7 @@ jobs: rust-build-test: name: Rust Build + Unit Tests runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 - uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable @@ -30,6 +31,7 @@ jobs: benchmarks: name: Criterion Benchmarks runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 - uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable @@ -40,6 +42,7 @@ jobs: e2e-lifecycle: name: E2E Lifecycle Test runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 - uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable @@ -52,6 +55,7 @@ jobs: aspect-tests: name: Aspect Tests (Cross-Cutting) runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 - name: Run aspect tests @@ -60,6 +64,7 @@ jobs: zig-ffi: name: Zig FFI Build + Test runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 - name: Install Zig @@ -75,6 +80,7 @@ jobs: panic-attack: name: Panic Attack Security Scan runs-on: ubuntu-latest + timeout-minutes: 15 if: github.event_name == 'push' steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml index 653ef98..1b4e269 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -31,4 +31,5 @@ permissions: jobs: governance: - uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@main + uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@861b5e911d9e5dcfb3c0ab3dd2a9a3c8fd0a1613 + timeout-minutes: 10 diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml index c68b9ed..a711616 100644 --- a/.github/workflows/hypatia-scan.yml +++ b/.github/workflows/hypatia-scan.yml @@ -25,5 +25,6 @@ permissions: jobs: hypatia: - uses: hyperpolymath/standards/.github/workflows/hypatia-scan-reusable.yml@915139d73560e65a8240b8fc7768698658502c89 + uses: hyperpolymath/standards/.github/workflows/hypatia-scan-reusable.yml@6cd3772824e59c8c9affeab66061e25383544242 + timeout-minutes: 10 secrets: inherit diff --git a/.github/workflows/instant-sync.yml b/.github/workflows/instant-sync.yml index 228dc43..01646a7 100644 --- a/.github/workflows/instant-sync.yml +++ b/.github/workflows/instant-sync.yml @@ -14,6 +14,7 @@ permissions: jobs: dispatch: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Trigger Propagation uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v3 diff --git a/.github/workflows/mirror.yml b/.github/workflows/mirror.yml index 2083ca6..ee8ea02 100644 --- a/.github/workflows/mirror.yml +++ b/.github/workflows/mirror.yml @@ -12,4 +12,5 @@ permissions: jobs: mirror: uses: hyperpolymath/standards/.github/workflows/mirror-reusable.yml@e6b2884722350515934d443daf23442f2195796f + timeout-minutes: 10 secrets: inherit diff --git a/.github/workflows/scorecard-enforcer.yml b/.github/workflows/scorecard-enforcer.yml index 4919e50..582c0c0 100644 --- a/.github/workflows/scorecard-enforcer.yml +++ b/.github/workflows/scorecard-enforcer.yml @@ -23,6 +23,7 @@ permissions: jobs: scorecard: runs-on: ubuntu-latest + timeout-minutes: 15 permissions: security-events: write id-token: write # For OIDC @@ -61,6 +62,7 @@ jobs: # Check specific high-priority items check-critical: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 8a718f4..8d85e86 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -16,4 +16,5 @@ jobs: security-events: write id-token: write uses: hyperpolymath/standards/.github/workflows/scorecard-reusable.yml@e0caf11508a3989574713c78f5f444f2ce5e33ef + timeout-minutes: 10 secrets: inherit diff --git a/.github/workflows/secret-scanner.yml b/.github/workflows/secret-scanner.yml index 586cdc0..3817aa9 100644 --- a/.github/workflows/secret-scanner.yml +++ b/.github/workflows/secret-scanner.yml @@ -16,4 +16,5 @@ permissions: jobs: scan: uses: hyperpolymath/standards/.github/workflows/secret-scanner-reusable.yml@3e4bd4c93911750727e2e4c66dff859e00079da0 + timeout-minutes: 10 secrets: inherit diff --git a/.github/workflows/semgrep.yml b/.github/workflows/semgrep.yml index 79ee4d4..d213e6a 100644 --- a/.github/workflows/semgrep.yml +++ b/.github/workflows/semgrep.yml @@ -16,6 +16,7 @@ permissions: jobs: semgrep: runs-on: ubuntu-latest + timeout-minutes: 15 permissions: security-events: write contents: read diff --git a/.github/workflows/workflow-linter.yml b/.github/workflows/workflow-linter.yml index 1e594b4..994df98 100644 --- a/.github/workflows/workflow-linter.yml +++ b/.github/workflows/workflow-linter.yml @@ -15,6 +15,7 @@ permissions: read-all jobs: lint-workflows: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v4 diff --git a/.machine_readable/6a2/0-AI-MANIFEST.a2ml b/.machine_readable/6a2/0-AI-MANIFEST.a2ml new file mode 100644 index 0000000..6bf1f8c --- /dev/null +++ b/.machine_readable/6a2/0-AI-MANIFEST.a2ml @@ -0,0 +1,31 @@ +# AI Manifest for 6a2 Directory + +## Purpose + +This manifest declares the AI-assistant context for the 6a2 machine-readable metadata directory. + +## Canonical Locations + +The 6 core A2ML files MUST exist in this directory: +1. AGENTIC.a2ml +2. ECOSYSTEM.a2ml +3. META.a2ml +4. NEUROSYM.a2ml +5. PLAYBOOK.a2ml +6. STATE.a2ml + +## Invariants + +- No duplicate files in root directory +- Single source of truth: this directory is authoritative +- No stale metadata + +## Protocol + +When multiple agents may write to A2ML files concurrently: +1. Read file and record git-sha-at-read in [provenance] section +2. Lock by creating .lock- +3. Write updated file with new [provenance] metadata +4. Release by removing lock file +5. On conflict: re-read and retry if git-sha-at-read does not match HEAD + diff --git a/.machine_readable/6a2/META.a2ml b/.machine_readable/6a2/META.a2ml index 3c17964..0473e8f 100644 --- a/.machine_readable/6a2/META.a2ml +++ b/.machine_readable/6a2/META.a2ml @@ -7,3 +7,4 @@ project = "januskey" author = "Jonathan D.A. Jewell " license = "MPL-2.0" standard = "RSR 2026" +last-updated = "2026-06-12" diff --git a/.machine_readable/6a2/README.adoc b/.machine_readable/6a2/README.adoc new file mode 100644 index 0000000..bc033d7 --- /dev/null +++ b/.machine_readable/6a2/README.adoc @@ -0,0 +1,30 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell +# A2ML 6a2 Directory + +This directory contains the 6 core A2ML machine-readable metadata files for this repository. + +## Files + +- `AGENTIC.a2ml` - AI agent operational gating, safety controls +- `ECOSYSTEM.a2ml` - Project ecosystem position, relationships, explicit boundaries +- `META.a2ml` - Architecture decisions (ADRs), development practices, design rationale +- `NEUROSYM.a2ml` - Symbolic semantics, composition algebra +- `PLAYBOOK.a2ml` - Executable plans, operational runbooks +- `STATE.a2ml` - Project state, phase, milestones, session history + +## Standards Compliance + +These files follow the A2ML Format Family specification from: +https://github.com/hyperpolymath/standards/tree/main/a2ml + +## Generation + +These files may be generated from .scm source files using transpilation tools. +Source .scm files should be removed after successful transpilation. + +## See Also + +- [A2ML Repository Template](https://github.com/hyperpolymath/standards/blob/main/A2ML-REPO-TEMPLATE.adoc) +- [6A2 Format Family](https://github.com/hyperpolymath/standards#a2ml-format-family-7-formats) + diff --git a/.machine_readable/6a2/STATE.a2ml b/.machine_readable/6a2/STATE.a2ml index e7936a6..13bdcf4 100644 --- a/.machine_readable/6a2/STATE.a2ml +++ b/.machine_readable/6a2/STATE.a2ml @@ -1,36 +1,65 @@ # SPDX-License-Identifier: MPL-2.0 # STATE.a2ml — Project state checkpoint -# Updated 2026-04-04: CRG D→C blitz complete +# Updated 2026-06-12: governance checkpoint (estate-standardization merge + +# CI/license/metadata wave recorded). Previous update 2026-04-04 (CRG blitz). [metadata] project = "januskey" version = "1.0.0" -last-updated = "2026-04-04" +last-updated = "2026-06-12" status = "active" crg-grade = "D" [project-context] name = "januskey" completion-percentage = "60" -phase = "Core tests complete, ready for API stability review" +phase = "Core tests complete; 2026-04..06 wave was CI/governance/license hardening, not feature work; API stability review still pending" [recent-work] -session-date = "2026-04-04" -work = "CRG D→C blitz: added E2E, aspect/security, and concurrency tests" +session-date = "2026-06-12" +work = "Estate standardization merged (flat contractiles, bot_directives, 6a2/anchor, self-validating, GOVERNANCE/MAINTAINERS/CODEOWNERS, flake.nix removed); CodeQL cron weekly→monthly cherry-picked; governance checkpoint layer (STATE refresh, bot_directives trio, Dust/Bust flat port, k9 template set)" + +[recent-work.since-2026-04-04] +ci-standardization = "Reusable-workflow wrappers: rust-ci (#39), hypatia-scan (#40, canonical sync #31/#32, workdir fix #29, repin #46), mirror (#42), secret-scanner (#43), scorecard (#44, job-level perms #48); cargo-audit + workflow-linter prevention workflows; concurrency-cancel guards (#34/#35); SHA repins (#27/#28/#33/#50); Dependabot security path + auto-merge restored; actions bumps (#36/#47/#53)" +license = "PMPL-1.0-or-later → MPL-2.0 migration (a740439); Cargo.toml license aligned to LICENSE (#52)" +security = "MCP-exposure threat model drafted (1411b0f, status draft-pending-human-review); Trustfile hardened to crypto-minimal baseline (21c7658); .expect(\"TODO: handle error\") sweep — 166 sites cleared (a0b0bdd); personal-gmail scrub (2bc817d)" +proofs = "idrisiser Idris2 proof wrappers for the cryptographic core (07cd404); k9 Kennel guard for security invariants (c110c1c)" +docs = "CHANGELOG.md seeded, Keep-a-Changelog (#45); tech-debt audit recorded (#41); M2 estate audit report (49b855b); CLAUDE.md ReScript→AffineScript flip (#49); CRG grade/badge recipes (ca10100)" +structure = "contractiles: bust/ added + k9 → svc/ per ADR-001 2026-04-18 (4094646, 9f05e98); 6SCM → 6A2 metadata migration" [test-coverage] -unit-tests = "24" -p2p-property-tests = "6" -e2e-integration-tests = "7" -aspect-security-tests = "6" -concurrency-tests = "5" -total-tests = "56" -benchmarks = "8" -total-coverage = "64 verification points" +# As assessed in READINESS.md (2026-04-03); no test-suite changes landed since. +unit-tests = "36" +p2p-property-tests = "8" +e2e-integration-tests = "1 script (mostly skips without pre-built binary)" +property-tests = "9" +regression-tests = "5" +idris2-proofs = "30" +benchmarks = "5 Criterion groups" +total = "67 tests + 5 benchmark groups + 30 Idris2 proofs (READINESS.md matrix)" [test-categories-complete] +unit = true p2p = true -e2e = true -aspect-security = true -concurrency = true -benchmarks = true +property = true +regression = true +contract = true +smoke = true +e2e = false +fuzz = false +mutation = false +chaos = false +compatibility = false + +[blockers] +threat-model-signoff = "threat-model.a2ml status = draft-pending-human-review (since 2026-04-19); blocks any januskey-mcp cartridge" +homerolled-hmac = "attestation.rs SHA256(key||data) pattern flagged by threat model; must be replaced with a real HMAC primitive before MCP exposure (Trustfile no-homerolled-hmac)" +metadata-only-key-types = "Ed25519/X25519 enum entries lack real sign/DH implementations (threat-model flag)" +claude-md-maintainer-edits = ".claude/CLAUDE.md is guardrail-blocked for agents: line 46 still says 'Julia/Rust/ReScript' (leftover from #49); package-management section still cites flake.nix, removed by the estate wave" +idris2-in-ci = "just test-proofs requires the idris2 binary; proof check not yet wired as a CI gate (READINESS D→C promotion item)" + +[next-actions] +crg-d-to-c = "READINESS.md promotion path: wire Idris2 proof check in CI, per-directory annotation, real E2E with built binary, dogfood in one real workflow" +fuzz-targets = "Replace the removed fuzz placeholder with real cargo-fuzz targets (READINESS category 11)" +changelog-automation = "Adopt changelog-reusable.yml so CHANGELOG.md stays current automatically" +feature-matrix-audit = "Audit README Key Features against the test matrix (READINESS aspect 7 note)" diff --git a/.machine_readable/6a2/anchor/0-AI-MANIFEST.a2ml b/.machine_readable/6a2/anchor/0-AI-MANIFEST.a2ml new file mode 100644 index 0000000..0dd6825 --- /dev/null +++ b/.machine_readable/6a2/anchor/0-AI-MANIFEST.a2ml @@ -0,0 +1,21 @@ +# AI Manifest for Anchor Directory + +## Purpose + +This manifest declares the AI-assistant context for the anchor machine-readable metadata directory. + +## Canonical Locations + +ANCHOR.a2ml files MUST exist in this directory. + +## Multiple Versions + +Unlike other A2ML files, multiple versions of ANCHOR.a2ml with different dates MAY exist. +Each version represents a specific recalibration point. + +## Invariants + +- Multiple versions with different dates are permitted +- No other A2ML files in this directory +- Single source of truth for anchor documents + diff --git a/.machine_readable/6a2/anchor/ANCHOR.a2ml b/.machine_readable/6a2/anchor/ANCHOR.a2ml new file mode 100644 index 0000000..52a5ecd --- /dev/null +++ b/.machine_readable/6a2/anchor/ANCHOR.a2ml @@ -0,0 +1,25 @@ +# ⚓ ANCHOR: januskey +# This is the canonical authority for the januskey repository. + +id: "org.hyperpolymath.januskey" +version: "1.0.0" +clade: "unknown" +status: "active" + +# SSG Configuration (Unified boj-server build) +ssg: + engine: "casket" + output_dir: "public" + boj_trigger: true + cartridge: "ssg-mcp" + +# Relationships +parents: + - "org.hyperpolymath.boj-server" + +# Realignments +realignments: + - date: "2026-06-12" + what: "Governance checkpoint: estate-standardization-20260607 merged (flat contractiles, bot_directives rename, 6a2/anchor relocation, self-validating rename, GOVERNANCE/MAINTAINERS/CODEOWNERS, flake.nix removed); CodeQL cron monthly; STATE refreshed from git log since 2026-04-04; bot_directives trio added; Dust/Bust ported to flat contractiles; shared k9 template set adapted into self-validating/" + why: "Estate-wide standardization wave (estate branch supersedes the prior nested layout)" + evidence: "merge of origin/estate-standardization-20260607; cherry-pick of origin/cicd/codeql-cron-monthly; PRs #27-#53 summarized in 6a2/STATE.a2ml [recent-work.since-2026-04-04]" diff --git a/.machine_readable/6a2/anchor/README.adoc b/.machine_readable/6a2/anchor/README.adoc new file mode 100644 index 0000000..bd23e35 --- /dev/null +++ b/.machine_readable/6a2/anchor/README.adoc @@ -0,0 +1,25 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell +# A2ML Anchor Directory + +This directory contains ANCHOR.a2ml files for project recalibration and scope intervention. + +## Files + +- `ANCHOR.a2ml` - Project recalibration, scope intervention, canonical authority + +## Multiple Versions + +Unlike other A2ML files, multiple versions of ANCHOR.a2ml with different dates may exist. +Each version represents a specific recalibration point in the project history. + +## Standards Compliance + +These files follow the ANCHOR.a2ml specification from: +https://github.com/hyperpolymath/standards/tree/main/anchor-a2ml + +## See Also + +- [A2ML Repository Template](https://github.com/hyperpolymath/standards/blob/main/A2ML-REPO-TEMPLATE.adoc) +- [Anchor A2ML Spec](https://github.com/hyperpolymath/standards/tree/main/anchor-a2ml) + diff --git a/.machine_readable/ADJUST.contractile b/.machine_readable/ADJUST.contractile deleted file mode 100644 index 00acccb..0000000 --- a/.machine_readable/ADJUST.contractile +++ /dev/null @@ -1,126 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; ADJUST.contractile — Accessibility invariants for januskey -; "ADJUST" = Accessibility & Digital Justice for Universal Software & Technology -; -; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST -; This file is machine-readable. LLM/SLM agents MUST NOT violate these invariants. - -; ── Definitions ────────────────────────────────────────────────── -; -; ADJUST (noun/verb) -; The accessibility contractile. Defines how software must adapt to serve -; all users regardless of ability, device, or context. Named for the verb -; "adjust" — to make suitable, to adapt, to accommodate — which is the -; core action of accessible design. -; -; Scope: -; ADJUST governs all user-facing interfaces: GUI, TUI, CLI, web, mobile, -; documentation, error messages, and installation flows. It applies to -; both human users and assistive technologies (screen readers, switch -; devices, braille displays, voice control). -; -; Relationship to other contractiles: -; - MUST: ADJUST invariants are a subset of MUST — violating ADJUST -; is a MUST violation. ADJUST exists separately because accessibility -; rules are numerous enough to warrant their own file, and because -; LLMs frequently forget accessibility unless explicitly reminded. -; - TRUST: ADJUST does not affect trust levels. All trust tiers must -; respect ADJUST invariants equally. -; - DUST: Deprecating a feature does not exempt it from ADJUST until -; it is fully removed. Deprecated UI must remain accessible. -; - INTENT: ADJUST supports the anti-purpose "this software is NOT -; only for able-bodied users with modern hardware." -; -; Standard: WCAG 2.2 Level AA (minimum) -; https://www.w3.org/WAI/WCAG22/quickref/?levels=aaa -; -; Why a separate file: -; Experience shows LLMs and developers alike treat accessibility as an -; afterthought. By placing invariants in a contractile that is loaded -; at session start, we make it structurally impossible to forget. -; -; ── End Definitions ────────────────────────────────────────────── - -(adjust-contractile - (version "1.0.0") - (full-name "Accessibility & Digital Justice for Universal Software & Technology") - (standard "WCAG-2.2-AA") - (repo "januskey") - - (invariants - ; ── Visual ── - (adjust "colour-contrast-ratio >= 4.5:1 for normal text") - (adjust "colour-contrast-ratio >= 3:1 for large text (18pt+ or 14pt+ bold)") - (adjust "no information conveyed by colour alone") - (adjust "no flashing or strobing content (3 flashes/second max)") - (adjust "text resizable to 200% without loss of content or function") - (adjust "focus indicators visible on all interactive elements") - - ; ── Keyboard ── - (adjust "all interactive elements reachable via keyboard (Tab/Shift+Tab)") - (adjust "no keyboard traps — user can always Tab away") - (adjust "skip navigation link present on pages with repeated blocks") - (adjust "logical focus order follows visual reading order") - - ; ── Screen reader ── - (adjust "all images have meaningful alt text (or alt='' if decorative)") - (adjust "all form inputs have associated labels") - (adjust "ARIA landmarks used for page regions (main, nav, banner, etc.)") - (adjust "dynamic content updates announced via aria-live regions") - (adjust "semantic HTML used (headings, lists, tables) — not div soup") - - ; ── Interactive ── - (adjust "touch targets minimum 44x44px on mobile/touch interfaces") - (adjust "error messages identify the field and describe the error") - (adjust "error messages not conveyed by colour or position alone") - (adjust "form validation provides suggestions for correction") - - ; ── Media ── - (adjust "video has captions (closed or open)") - (adjust "audio-only content has text transcript") - (adjust "no autoplay of media with sound") - - ; ── Motion ── - (adjust "animations respect prefers-reduced-motion media query") - (adjust "no content depends on motion to convey meaning") - - ; ── CLI/TUI ── - (adjust "CLI output must not rely solely on colour (use symbols: [OK] [FAIL])") - (adjust "TUI must support high-contrast mode") - (adjust "all CLI commands support --help with plain-text output") - (adjust "error messages written in plain language, not jargon or codes alone") - - ; ── Documentation ── - (adjust "docs use clear language, short sentences, logical structure") - (adjust "code examples include comments explaining non-obvious steps") - (adjust "diagrams have text descriptions or alt text") - - ; ── Internationalisation (i18n) ── - (adjust "all user-facing strings externalisable for translation") - (adjust "no hardcoded English in error messages — use message keys") - (adjust "date/time/number formats locale-aware") - (adjust "RTL (right-to-left) layout support where applicable") - (adjust "Unicode handled correctly throughout (UTF-8 everywhere)") - ) - - (related-resources - ; LOL — super-parallel corpus crawler for 1500+ languages - ; Use for linguistic data, translation coverage, and i18n validation - (lol "standards/lol — multilingual NLP corpus, see README.adoc") - (polyglot-i18n "polyglot-i18n — i18n framework and WASM translation engine") - ) - - (enforcement - (ci "accessibility linting in quality.yml workflow") - (pr-block "PR blocked if accessibility regression detected") - (tool "axe-core or pa11y for automated checks on web UI") - (tool "CLI output inspected for colour-only signalling") - (manual "manual screen reader test before major releases") - ) - - (notes - "These are MINIMUM requirements. Exceeding them (AAA) is encouraged." - "When in doubt about an accessibility decision, ask — don't guess." - "Accessibility is not optional polish — it is a structural requirement." - ) -) diff --git a/.machine_readable/INTENT.contractile b/.machine_readable/INTENT.contractile deleted file mode 100644 index bc0893f..0000000 --- a/.machine_readable/INTENT.contractile +++ /dev/null @@ -1,72 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; INTENT.contractile — Purpose and scope for januskey -; Helps LLM/SLM agents understand what this repo IS and IS NOT. -; -; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST - -; ── Definitions ────────────────────────────────────────────────── -; -; INTENT (noun) -; The purpose contractile. Defines what this repository IS, what it is -; NOT (anti-purpose), and which architectural decisions are load-bearing. -; Without INTENT, LLMs drift into scope creep, reverse key decisions, -; or add features that belong in a different repo. -; -; Scope: -; INTENT governs the conceptual boundaries of the project — its reason -; for existing, its domain, and its relationship to the ecosystem. -; It does NOT specify implementation details (that's MUST and code). -; -; Relationship to other contractiles: -; - MUST: INTENT explains WHY certain MUSTs exist. If you don't -; understand a MUST, read INTENT first. -; - TRUST: The "ask-before-touching" section in INTENT maps directly -; to TRUST.trust-deny for the most sensitive areas. -; - ADJUST: INTENT's anti-purpose should include "this software is -; NOT only for users with perfect vision/hearing/mobility." -; - DUST: When INTENT changes (repo pivots), related DUST entries -; should be created for the abandoned direction. -; -; ── End Definitions ────────────────────────────────────────────── - -(intent-contractile - (version "1.0.0") - (repo "januskey") - - ; === Purpose (what this repo IS) === - (purpose - "{{ONE_PARAGRAPH_PURPOSE}}" - ) - - ; === Anti-Purpose (what this repo is NOT — prevents scope creep) === - (anti-purpose - "{{ONE_PARAGRAPH_ANTI_PURPOSE}}" - ; Examples: - ; "This is NOT a general-purpose database — it solves one specific problem." - ; "This is NOT a framework — it is a library with a focused API." - ; "This does NOT handle authentication — that is delegated to [other repo]." - ) - - ; === Key Architectural Decisions That Must Not Be Reversed === - (architectural-invariants - ; *REMINDER: List the foundational decisions* - ; ("Idris2 for ABI definitions — dependent types prove interface correctness") - ; ("Zig for FFI — zero-cost C ABI compatibility") - ; ("Elixir for supervision — OTP fault tolerance") - ) - - ; === Sensitive Areas (if in doubt, ask) === - (ask-before-touching - ; *REMINDER: List areas where LLMs should check before modifying* - ; "src/abi/ — formal proofs, changes require re-verification" - ; "ffi/zig/ — C ABI boundary, changes affect all language bindings" - ; ".machine_readable/ — checkpoint files, format is specified" - ) - - ; === Ecosystem Position === - (ecosystem - (belongs-to "{{MONOREPO_OR_STANDALONE}}") - (depends-on ("{{DEP1}}" "{{DEP2}}")) - (depended-on-by ("{{CONSUMER1}}" "{{CONSUMER2}}")) - ) -) diff --git a/.machine_readable/MUST.contractile b/.machine_readable/MUST.contractile deleted file mode 100644 index 2075748..0000000 --- a/.machine_readable/MUST.contractile +++ /dev/null @@ -1,91 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; MUST.contractile — Baseline invariants for januskey -; These constraints MUST NOT be violated. K9 validators enforce them. -; -; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST - -; ── Definitions ────────────────────────────────────────────────── -; -; MUST (noun/verb) -; The hard-constraint contractile. Defines invariants that are structurally -; required for the repository to function correctly and safely. Violating -; a MUST is always a bug — there are no "soft" MUSTs. -; -; Scope: -; MUST governs code, configuration, CI, and structure. It does NOT govern -; style, preference, or approach — those belong in CLAUDE.md or coding -; standards. MUST is for things that break the project if violated. -; -; Relationship to other contractiles: -; - TRUST: MUST is enforced regardless of trust level. Even maximal-trust -; agents cannot violate MUST constraints. -; - ADJUST: All ADJUST invariants are implicitly MUST invariants too. -; ADJUST exists separately for visibility. -; - INTENT: MUST protects the architectural decisions described in INTENT. -; - DUST: When a feature enters DUST (deprecation), its MUST constraints -; remain active until the feature is fully removed. -; -; Enforcement: -; K9 validators in contractiles/k9/ machine-check MUST constraints. -; CI runs these on every PR. Violations block merge. -; -; ── End Definitions ────────────────────────────────────────────── - -(must-contractile - (version "1.0.0") - (repo "januskey") - - ; === Universal Invariants (apply to ALL repos) === - - (invariants - ; Paths - (must "no hardcoded absolute paths (/home/*, /mnt/*, /var/mnt/*)") - (must "all paths use env vars, XDG dirs, or relative references") - - ; Language policy - (must "no new TypeScript files") - (must "no new Python files") - (must "no new Go files") - (must "no npm/bun/yarn/pnpm dependencies — Deno only") - - ; Dangerous patterns - (must "no believe_me (Idris2)") - (must "no assert_total (Idris2)") - (must "no Admitted (Coq)") - (must "no sorry (Lean)") - (must "no unsafeCoerce (Haskell)") - (must "no Obj.magic (OCaml)") - (must "no unsafe {} blocks without safety comment (Rust)") - - ; License - (must "SPDX-License-Identifier header on every source file") - (must "no removal or modification of LICENSE file") - - ; Structure - (must ".machine_readable/ directory preserved") - (must "0-AI-MANIFEST.a2ml preserved") - (must "no SCM files in repo root — only in .machine_readable/") - - ; CI - (must "no removal of CI workflows without explicit approval") - (must "all GitHub Actions SHA-pinned") - - ; Code quality - (must "tests must not be deleted or weakened") - (must "generated code in generated/ directory only") - (must "no introduction of OWASP top 10 vulnerabilities") - - ; ABI/FFI (if applicable) - (must "no modification of ABI contracts without proof update") - (must "no removal of formal verification proofs") - ) - - ; === Project-Specific Invariants === - ; *REMINDER: Add invariants specific to this repo* - ; (must "# Add project-specific invariants here") - - (enforcement - (k9-validator "contractiles/k9/must-check.k9.ncl") - (ci "quality.yml runs must-check on every PR") - ) -) diff --git a/.machine_readable/TRUST.contractile b/.machine_readable/TRUST.contractile deleted file mode 100644 index 6e2307e..0000000 --- a/.machine_readable/TRUST.contractile +++ /dev/null @@ -1,80 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; TRUST.contractile — Trust boundaries for januskey -; Defines what LLM/SLM agents are trusted to do without asking. -; -; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST - -; ── Definitions ────────────────────────────────────────────────── -; -; TRUST (noun/verb) -; The permission contractile. Defines the boundary between what an AI -; agent may do autonomously and what requires human approval. Trust is -; graduated — not binary — with four levels from minimal to maximal. -; -; Trust levels: -; - maximal: Agent may read, build, test, lint, format, heal freely. -; Only destructive/external actions require approval. -; - standard: Agent may read and build. Test/lint need approval. -; - restricted: Agent may read only. All modifications need approval. -; - minimal: Agent may read specific files only. Everything else blocked. -; -; Scope: -; TRUST governs AI agent behaviour only. It does not affect human -; contributors — humans follow CONTRIBUTING.md and GOVERNANCE.adoc. -; -; Relationship to other contractiles: -; - MUST: Trust never overrides MUST. Even at maximal trust, MUST -; violations are blocked. -; - ADJUST: Trust does not exempt from ADJUST. All trust tiers must -; produce accessible output. -; - INTENT: TRUST.trust-deny protects the sensitive areas listed in -; INTENT.ask-before-touching. -; - DUST: Deprecated features have the same trust rules as active ones. -; -; ── End Definitions ────────────────────────────────────────────── - -(trust-contractile - (version "1.0.0") - (repo "januskey") - - (trust-level "maximal") ; maximal | standard | restricted | minimal - - ; === Maximal Trust (default) === - ; LLM may freely do these without asking: - (trust-actions - "read" ; Read any file in the repo - "build" ; Run build commands - "test" ; Run test suites - "lint" ; Run linters and formatters - "format" ; Auto-format code - "doctor" ; Run self-diagnostics - "heal" ; Attempt automatic repair - "git-status" ; Check git status - "git-diff" ; View diffs - "git-log" ; View history - ) - - ; === Denied Actions (always require human approval) === - (trust-deny - "delete-branch" ; Could lose work - "force-push" ; Overwrites history - "modify-ci-secrets" ; Security sensitive - "publish" ; External visibility - "push-to-main" ; Protected branch - "delete-files-bulk" ; More than 5 files at once - "modify-license" ; Legal implications - "modify-security-policy" ; Security implications - "remove-proofs" ; Formal verification regression - "disable-ci-checks" ; Safety regression - ) - - ; === Trust Boundary === - (trust-boundary "repo") ; LLM confined to this repo unless explicitly told otherwise - - ; === Override === - ; Repos requiring tighter trust override these settings with justification: - ; (override - ; (trust-level "restricted") - ; (reason "Contains production secrets / handles PII / etc.") - ; ) -) diff --git a/.machine_readable/anchors/ANCHOR.a2ml b/.machine_readable/anchors/ANCHOR.a2ml deleted file mode 100644 index b1cb36b..0000000 --- a/.machine_readable/anchors/ANCHOR.a2ml +++ /dev/null @@ -1,18 +0,0 @@ -# ⚓ ANCHOR: januskey -# This is the canonical authority for the januskey repository. - -id: "org.hyperpolymath.januskey" -version: "1.0.0" -clade: "unknown" -status: "active" - -# SSG Configuration (Unified boj-server build) -ssg: - engine: "casket" - output_dir: "public" - boj_trigger: true - cartridge: "ssg-mcp" - -# Relationships -parents: - - "org.hyperpolymath.boj-server" diff --git a/.machine_readable/agent_instructions/README.adoc b/.machine_readable/bot_directives/README.adoc similarity index 51% rename from .machine_readable/agent_instructions/README.adoc rename to .machine_readable/bot_directives/README.adoc index 9bc2e24..f25723a 100644 --- a/.machine_readable/agent_instructions/README.adoc +++ b/.machine_readable/bot_directives/README.adoc @@ -1,10 +1,21 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -= Agent Instructions +// Copyright (c) Jonathan D.A. Jewell += Bot Directives :toc: preamble -Methodology-aware configuration for AI agents. Read by any AI agent -(Claude, Gemini, Copilot, etc.) at session start. +Per-repo directives for automated agents working on januskey, plus +methodology-aware configuration read by any AI agent (Claude, Gemini, +Copilot, etc.) at session start. + +== Precedence + +Maintainer instruction > these directives > bot defaults. + +== Scope + +These directives apply to the Hypatia scanner (`hypatia.a2ml`), the +gitbot fleet (`gitbot-fleet.a2ml`), and `.git-private-farm` propagation +(`git-private-farm.a2ml`), in addition to the methodology layer below. == Files @@ -12,6 +23,15 @@ Methodology-aware configuration for AI agents. Read by any AI agent |=== | File | Purpose +| `hypatia.a2ml` +| Hypatia scanner directives — ignore-file state, workflow pointer, accepted findings, prohibited actions + +| `gitbot-fleet.a2ml` +| Gitbot-fleet roster and roles, branch policy, never-touch paths, per-bot allow/deny + +| `git-private-farm.a2ml` +| Propagation to hyperpolymath/.git-private-farm — workflow, secret name, never-propagate list + | `methodology.a2ml` | Default mode, invariants, ring ceiling, priority weights, convergent budget @@ -32,7 +52,7 @@ Methodology-aware configuration for AI agents. Read by any AI agent == Relationship to Other Files * `AGENTIC.a2ml` says WHAT agents can do (permissions, gating) -* `agent_instructions/` says HOW agents should work (methodology) +* `bot_directives/` says HOW agents should work (methodology) * `bot_directives/` says what the gitbot-fleet does (fleet-specific) * `CLAUDE.md` says how Claude specifically should work (Claude-specific) diff --git a/.machine_readable/agent_instructions/coverage.a2ml b/.machine_readable/bot_directives/coverage.a2ml similarity index 100% rename from .machine_readable/agent_instructions/coverage.a2ml rename to .machine_readable/bot_directives/coverage.a2ml diff --git a/.machine_readable/agent_instructions/debt.a2ml b/.machine_readable/bot_directives/debt.a2ml similarity index 100% rename from .machine_readable/agent_instructions/debt.a2ml rename to .machine_readable/bot_directives/debt.a2ml diff --git a/.machine_readable/bot_directives/git-private-farm.a2ml b/.machine_readable/bot_directives/git-private-farm.a2ml new file mode 100644 index 0000000..2285a06 --- /dev/null +++ b/.machine_readable/bot_directives/git-private-farm.a2ml @@ -0,0 +1,24 @@ +# SPDX-License-Identifier: MPL-2.0 +# git-private-farm.a2ml — propagation directives for januskey + +[metadata] +repo = "januskey" +last-updated = "2026-06-12" +owner = "hyperpolymath" + +[propagation] +enabled = true +workflow = ".github/workflows/instant-sync.yml" +target = "hyperpolymath/.git-private-farm" +event-type = "propagate" +secret-name = "FARM_DISPATCH_TOKEN" +presence-gated = false +presence-gated-notes = "The dispatch step runs unconditionally on push to main/master and on published releases; there is no `if:` secret-presence gate, so the step fails (rather than skips) where the secret is absent (e.g. forks)." +triggers = ["push to main/master", "release published"] + +[never-propagate] +items = ["secrets", "unmerged branches", "work-in-progress"] + +[on-token-rotation] +command = "gh secret set FARM_DISPATCH_TOKEN --repo hyperpolymath/januskey" +notes = "Name only — never store a value in this file." diff --git a/.machine_readable/bot_directives/gitbot-fleet.a2ml b/.machine_readable/bot_directives/gitbot-fleet.a2ml new file mode 100644 index 0000000..811213c --- /dev/null +++ b/.machine_readable/bot_directives/gitbot-fleet.a2ml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: MPL-2.0 +# gitbot-fleet.a2ml — directives for the hyperpolymath gitbot fleet in januskey + +[metadata] +repo = "januskey" +last-updated = "2026-06-12" +owner = "hyperpolymath" + +[fleet] +bots = ["rhodibot", "echidnabot", "sustainabot", "glambot", "seambot", "finishbot"] +rhodibot = "git operations" +echidnabot = "code quality" +sustainabot = "dependency updates" +glambot = "documentation" +seambot = "integration" +finishbot = "task completion" + +[branch-policy] +working-branch-pattern = "claude/* | bots/* | chore/* | docs/* | cicd/* | dependabot/*" +draft-PRs-only = true +ci-green-before-merge = true +never-touch = [ + ".claude/CLAUDE.md", + "src/abi/", + "generated/idrisiser/", + ".machine_readable/threat-model.a2ml", + ".machine_readable/contractiles/Trustfile.a2ml", + "LICENSE", +] +never-touch-notes = "src/abi/ + generated/idrisiser/ are the Idris2 ABI proof surface (changes require proof re-verification); threat-model.a2ml awaits human sign-off; the Trustfile may never be widened by an agent (see its self-integrity rule)." + +[per-bot.sustainabot] +allow = ["Cargo.toml", "Cargo.lock", ".github/workflows (SHA bumps via grouped dependabot PRs only)"] +deny = ["crypto dependency major-version bumps without maintainer review"] +notes = "Crypto crates (aes-gcm, sha2, argon2 and kin) are security-sensitive; bumps need human eyes." + +[per-bot.echidnabot] +allow = ["clippy/rustfmt fixes", "test additions"] +deny = ["weakening or deleting tests", "touching never-touch paths"] + +[per-bot.glambot] +allow = ["docs/", "*.adoc", "*.md", "docs/wiki/"] +deny = ["changing reversibility claims without the 'formal proofs pending' qualifier"] diff --git a/.machine_readable/bot_directives/hypatia.a2ml b/.machine_readable/bot_directives/hypatia.a2ml new file mode 100644 index 0000000..16430fe --- /dev/null +++ b/.machine_readable/bot_directives/hypatia.a2ml @@ -0,0 +1,23 @@ +# SPDX-License-Identifier: MPL-2.0 +# hypatia.a2ml — directives for the Hypatia security scanner in januskey + +[metadata] +repo = "januskey" +last-updated = "2026-06-12" +owner = "hyperpolymath" + +[scanner] +ignore-file = ".hypatia-ignore" +ignore-file-present = false +workflow = ".github/workflows/hypatia-scan.yml" +workflow-notes = "Thin wrapper around hyperpolymath/standards hypatia-scan-reusable.yml (standards#191), SHA-pinned; synced to canonical via PRs #31/#32/#40, repinned to merge-commit SHA via #46. Local scan state lives in .hypatia/ (activity.jsonl, last-visit.json)." + +[accepted-findings] +status = "none-recorded" +notes = "No accepted false-positives are on record for januskey as of 2026-06-12. If the scanner flags caller-side properties of the reusable workflow wrappers (rust-ci, hypatia-scan, mirror, secret-scanner, scorecard are all thin `uses:` wrappers), evaluate against the reusable's own configuration in hyperpolymath/standards before accepting; record any acceptance here with a reason." + +[prohibited-actions] +auto-delete-branches = false +auto-merge = false +modify-workflows = false +escalation = "open an issue, do not spam PR comments" diff --git a/.machine_readable/agent_instructions/methodology.a2ml b/.machine_readable/bot_directives/methodology.a2ml similarity index 100% rename from .machine_readable/agent_instructions/methodology.a2ml rename to .machine_readable/bot_directives/methodology.a2ml diff --git a/.machine_readable/contractiles/Adjustfile.a2ml b/.machine_readable/contractiles/Adjustfile.a2ml new file mode 100644 index 0000000..2766399 --- /dev/null +++ b/.machine_readable/contractiles/Adjustfile.a2ml @@ -0,0 +1,94 @@ +# SPDX-License-Identifier: MPL-2.0 +# Adjustfile — Drift-tolerance and accessibility contract for januskey +# Author: Jonathan D.A. Jewell +# +# Cumulative-drift catchment: tolerance bands + corrective actions. +# Authority: advisory (Yard) — continue-with-warnings; auto_fix where deterministic. +# Run with: adjust check +# Fix with: adjust fix (applies deterministic patches; advisory otherwise) +# +# Provenance: populated 2026-06-12 from .machine_readable/ADJUST.contractile +# (ADJUST = Accessibility & Digital Justice for Universal Software & +# Technology, standard WCAG-2.2-AA; CLI/TUI + documentation invariants kept — +# januskey is a CLI tool, so the visual/web invariants of the generic list +# apply only if a UI is ever added) + repo-true drift items, replacing the +# rsr-template-repo stub. + +@abstract: +Drift tolerances and corrective actions for januskey. Unlike MUST (hard +gate), ADJUST tracks cumulative drift against tolerance bands and proposes +corrective actions. Advisory — it warns and trends, it does not block. +Standard: WCAG-2.2-AA (CLI/TUI profile). +@end + +## Accessibility (ADJUST invariants, CLI/TUI profile) + +### cli-output-not-colour-only +- description: CLI output must not rely solely on colour (use symbols: [OK] [FAIL]) +- tolerance: 0 colour-only status outputs +- corrective: Add symbol prefixes alongside colour +- severity: advisory + +### cli-help-plain-text +- description: All CLI commands support --help with plain-text output +- tolerance: every jk subcommand has --help +- corrective: Add missing help text via clap derive docs +- severity: advisory + +### error-messages-plain-language +- description: Error messages written in plain language, not jargon or codes alone; identify the field and describe the error +- tolerance: 0 bare error codes surfaced to users +- corrective: Wrap with context via error.rs types +- severity: advisory + +### docs-clarity +- description: Docs use clear language, short sentences, logical structure; code examples include comments explaining non-obvious steps; diagrams have text descriptions +- tolerance: READMEs and wiki pages pass a plain-language read-through +- corrective: Editorial pass on flagged pages +- severity: advisory + +## Documentation Drift + +### readme-feature-matrix-accuracy +- description: README feature claims must match tested reality (READINESS.md notes "Feature matrix vs README not audited"); reversibility claims must carry the "formal proofs pending" qualifier +- tolerance: 0 absolutist claims contradicted by READINESS.md +- corrective: Audit README Key Features against the test matrix +- severity: advisory + +### changelog-currency +- description: CHANGELOG.md should reflect merged PRs (seeded 2026-05-26, manual until changelog-reusable.yml is adopted) +- tolerance: no merged feat/fix PR older than 30 days missing +- corrective: Run git cliff with the canonical cliff.toml +- severity: advisory + +### adoc-not-md +- description: New prose docs should prefer AsciiDoc +- tolerance: New prose docs are *.adoc (existing *.md grandfathered) +- corrective: Author new docs as .adoc +- severity: advisory + +## Structural Drift + +### spdx-header-consistency +- description: All files have correct SPDX headers +- tolerance: 0 files missing SPDX-License-Identifier +- corrective: Add SPDX headers to files that need them +- severity: advisory + +### panic-pattern-drift +- description: No regression of the 2026-04 unwrap()/expect("TODO") sweeps in security-critical modules +- tolerance: 0 new bare unwrap() in crates/*/src and src/januskey/src +- corrective: Run `just assail` (panic-attacker pre-commit scan) +- severity: advisory + +### no-broken-symlinks +- description: No broken symbolic links in the tree +- tolerance: 0 broken symlinks +- corrective: Remove or repoint flagged links +- severity: advisory + +### state-file-currency +- description: 6a2/STATE.a2ml should be refreshed when a work-wave lands +- tolerance: last-updated within 90 days of the latest non-dependabot commit +- corrective: Refresh STATE.a2ml from git log +- severity: advisory diff --git a/.machine_readable/contractiles/Bustfile.a2ml b/.machine_readable/contractiles/Bustfile.a2ml new file mode 100644 index 0000000..d527449 --- /dev/null +++ b/.machine_readable/contractiles/Bustfile.a2ml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: MPL-2.0 +# Bustfile — Breakage and rollback contract for januskey +# Verb: bust +# +# Provenance: flat-layout port (2026-06-12) of the former nested +# .machine_readable/contractiles/bust/Bustfile.a2ml (a curly-brace +# template inherited from a meta-repo; rewritten as TOML-A2ML). The +# inherited submodule scenarios are recorded as not-applicable — +# januskey has no .gitmodules. Repo-true rollback procedures added +# from the repo's own discipline (Trustfile, threat model). + +[metadata] +repo = "januskey" +version = "1.1.0" +format = "a2ml" +last-updated = "2026-06-12" +description = "Rollback procedures when something breaks" +supersedes = ".machine_readable/contractiles/bust/Bustfile.a2ml + bust.ncl (nested, removed by estate flattening)" + +[scenarios.bad-merge-or-bump] +symptom = "A merged PR breaks CI or introduces a regression" +action = "git revert the merge commit on a branch; open a revert PR (reversible, low blast radius)" + +[scenarios.secret-or-key-material-leaked] +symptom = "Credential, passphrase, or key-like file lands in history" +action = "Hard-rotate the leaked secret immediately; git-filter-repo or BFG on the affected history; re-publication only after rotation completes. Trustfile no-key-material-in-tree exists to prevent this." + +[scenarios.ci-workflow-broken] +symptom = "A reusable-workflow pin or wrapper conversion breaks a check" +action = "Revert to the previous SHA pin (see PRs #46/#50 for the orphan-SHA precedent); never disable the check to go green" + +[scenarios.trust-widening-attempt] +symptom = "A change flips @trust-level from minimal or weakens a severity:critical check" +action = "Reject/revert unless the commit message contains the literal phrase 'human-approved trust widening' (Trustfile self-integrity rule)" + +[scenarios.inherited-not-applicable] +status = "not-applicable" +reason = "The prior nested Bustfile carried meta-repo submodule scenarios (bad-pointer-bump, missing-sha, orphan-after-local-commit). januskey has no submodules (.gitmodules absent); recorded here so the ported content is not silently lost." + +[escalation-ladder] +step-1 = "revert the offending commit (reversible, low blast radius)" +step-2 = "reset the local clone / re-fetch from origin (affects only local workspace)" +step-3 = "force-push to main — PROHIBITED without explicit user confirmation (violates branch protection)" +step-4 = "registry-level action (delete/archive the GitHub repo) — human-only action, never by AI" + +[backup-points] +github-history = "GitHub serves as the durable backup for repository history" +local-backup-tags = "Local backup tags (backup/pre--) retained on risky rewrites" +operation-metadata = "januskey's own append-only operation log is the rollback source for jk operations (application-level, not repo-level)" diff --git a/.machine_readable/contractiles/Dustfile.a2ml b/.machine_readable/contractiles/Dustfile.a2ml new file mode 100644 index 0000000..f42e16f --- /dev/null +++ b/.machine_readable/contractiles/Dustfile.a2ml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: MPL-2.0 +# Dustfile — Cleanup, hygiene, and deprecation contract for januskey +# Verb: dust +# +# Provenance: flat-layout port (2026-06-12) of the former nested +# .machine_readable/contractiles/dust/Dustfile.a2ml (content preserved +# verbatim below), extended with [metadata] and a deprecation register +# per the estate flat-contractile convention. TOML-A2ML. + +[metadata] +repo = "januskey" +version = "1.1.0" +format = "a2ml" +last-updated = "2026-06-12" +supersedes = ".machine_readable/contractiles/dust/Dustfile.a2ml (nested, removed by estate flattening)" + +[cleanup] +stale-branch-policy = "delete-after-merge" +artifact-retention = "90-days" +cache-policy = "clear-on-release" + +[hygiene] +linting = "required" +formatting = "required" +dead-code-removal = "encouraged" +todo-tracking = "tracked-in-issues" + +[reversibility] +backup-before-destructive = true +rollback-mechanism = "git-revert" +data-retention-policy = "preserve-30-days" + +# Deprecation register: features/files entering end-of-life. A feature in +# DUST keeps its MUST constraints active until fully removed. +[deprecations] +status = "none-active" +reason = "No januskey feature is currently deprecated. The 2026-06 estate flattening retired the nested contractile directories and the root *.contractile files; their content was ported into this flat set before removal (see each file's Provenance header)." + +[deprecations.retired-2026-06] +nested-contractile-dirs = "contractiles/{bust,dust,trust}/ — content ported to flat files" +root-contractile-files = "MUST/TRUST/INTENT/ADJUST.contractile — content ported to flat files" +flake-nix = "flake.nix removed by estate wave; guix.scm is the primary package definition" diff --git a/.machine_readable/contractiles/Intentfile.a2ml b/.machine_readable/contractiles/Intentfile.a2ml new file mode 100644 index 0000000..224b28a --- /dev/null +++ b/.machine_readable/contractiles/Intentfile.a2ml @@ -0,0 +1,108 @@ +# SPDX-License-Identifier: MPL-2.0 +# Intentfile (A2ML Canonical) — north-star contractile for januskey +# Author: Jonathan D.A. Jewell +# +# Paired runner: intend.ncl +# Verb: intend +# +# Semantics: North-star contractile. Declares BOTH concrete committed +# next-actions AND horizon aspirations the project wishes to +# become. Two sections share one file: +# [[intents]] — "we WILL do this; track progress" +# status: declared → in_progress → done | +# deferred | retired +# [[wishes]] — "we WISH this were true; revisit later" +# status: declared → in_progress → achieved | +# abandoned +# grouped by horizon: near / mid / far. +# Non-gating — this is a report, not a gate. See the `must` +# contractile for hard gates. +# +# Provenance: populated 2026-06-12 from contractiles/intend/Intentfile.a2ml +# (purpose/anti-purpose/if-in-doubt) + READINESS.md promotion path + +# threat-model.a2ml findings, replacing the rsr-template-repo stub. + +@abstract: +North-star contractile for januskey: reversible file operations and +passphrase-gated cryptographic key custody through Maximal Principle +Reduction (MPR) — vulnerability elimination by construction rather than +verification. Formal reversibility proofs are a target, not yet complete. +@end + +## Purpose + +JanusKey is a file-operation utility suite (Rust workspace: reversible-core ++ januskey-cli) whose operations carry sufficient metadata for inversion — +delete/modify/move/copy with undo, transactions with commit/rollback, +content-addressed storage (SHA-256), a tamper-evident audit log, and +passphrase-gated AEAD key custody. The Idris2 ABI layer (src/abi/) and Zig +FFI (ffi/zig/) define the verified interface boundary. + +## Anti-Purpose + +This project is NOT: +- A backup or sync system (recovery comes from operation metadata, not external state) +- A general-purpose cryptography library (it consumes RustCrypto primitives) +- A fork or wrapper around another tool +- A monorepo +- An MCP-exposed service yet (exposure is gated on human-approved threat model) + +## If In Doubt + +If you are unsure whether a change is in scope, ask. +Sensitive areas: ABI definitions (src/abi/), key-custody and audit-log code, +license headers, CI workflows, .machine_readable/threat-model.a2ml. + +## Committed Next-Actions + +### threat-model-signoff +- description: Human sign-off of the MCP-exposure threat model (status is draft-pending-human-review since 2026-04-19) +- probe: grep -q 'status\s*=\s*"draft-pending-human-review"' .machine_readable/threat-model.a2ml && echo pending +- status: declared +- notes: Maintainer-only action; blocks any januskey-mcp cartridge + +### fix-homerolled-hmac +- description: Replace SHA256(key || data) attestation pattern with a real HMAC primitive (threat-model flag, 2026-04-19) +- probe: cargo tree 2>/dev/null | grep -q hmac +- status: declared +- notes: Trustfile check no-homerolled-hmac enforces this before MCP exposure + +### crg-promotion-d-to-c +- description: CRG grade promotion per READINESS.md path — wire Idris2 proof check in CI, complete per-directory annotation, real E2E with built binary, dogfood in one real workflow +- probe: grep -q 'Current Grade' READINESS.md +- status: in_progress +- notes: unwrap()/expect() sweeps landed 2026-04 (166 sites); remaining items tracked in READINESS.md + +### real-fuzz-targets +- description: Replace removed fuzz placeholder with real cargo-fuzz targets +- probe: test -d tests/fuzz +- status: declared +- notes: READINESS.md category 11 is MISSING; fake placeholder was removed deliberately + +## Wishes + +### Near Horizon + +#### changelog-automation +- description: Adopt changelog-reusable.yml so CHANGELOG.md stays in sync automatically +- horizon: near +- status: declared + +### Mid Horizon + +#### formal-reversibility-proofs +- description: Complete the formal reversibility proofs backing the README claim (currently "proofs pending"); 30 Idris2 ABI proofs exist, the reversibility theorems do not yet +- horizon: mid +- status: in_progress + +#### mutation-testing +- description: cargo-mutants configuration (READINESS category 10) +- horizon: mid +- status: declared + +### Far Horizon + +#### mcp-cartridge +- description: januskey-mcp cartridge for boj-server, only after threat-model approval and the DO-NOT-EXPOSE list is enforced +- horizon: far +- status: declared diff --git a/.machine_readable/contractiles/Justfile b/.machine_readable/contractiles/Justfile new file mode 100644 index 0000000..db5a756 --- /dev/null +++ b/.machine_readable/contractiles/Justfile @@ -0,0 +1,179 @@ +# SPDX-License-Identifier: MPL-2.0 +# januskey - Development Tasks +set shell := ["bash", "-uc"] +set dotenv-load := true + +import? "contractile.just" + +project := "januskey" + +# Show all recipes +default: + @just --list --unsorted + +# Build all workspace crates (release) +build: + cargo build --workspace --release + +# Run all workspace tests +test: + cargo test --workspace + +# Clean build artefacts +clean: + cargo clean + +# Format all code +fmt: + cargo fmt --all + +# Lint all code with clippy +lint: + cargo clippy --workspace -- -D warnings + +# Run benchmarks +bench: + cargo bench --workspace + +# Run end-to-end tests (shell-based lifecycle) +test-e2e: + @echo "=== E2E Tests ===" + @if [ -x tests/e2e/lifecycle_e2e.sh ]; then bash tests/e2e/lifecycle_e2e.sh; else echo "SKIP: tests/e2e/lifecycle_e2e.sh not executable or missing"; fi + +# Run aspect / cross-cutting tests +test-aspect: + @echo "=== Aspect Tests ===" + @if [ -x tests/aspect/cross_cutting_test.sh ]; then bash tests/aspect/cross_cutting_test.sh; else echo "SKIP: tests/aspect/cross_cutting_test.sh not executable or missing"; fi + +# Run P2P component integration tests +test-p2p: + cargo test --package januskey --test p2p_test + +# Run regression tests +test-regressions: + cargo test --package reversible-core --test unwrap_safety_test + +# Run property-based tests +test-property: + cargo test --workspace -- --include-ignored proptest + +# Run FFI tests (placeholder — no FFI tests yet) +test-ffi: + @echo "=== FFI Tests ===" + @if [ -d ffi/zig/test ]; then echo "TODO: Run Zig FFI integration tests"; else echo "SKIP: No FFI tests present yet (see ffi/zig/)"; fi + +# Smoke test: build + version + help +smoke: + @echo "=== Smoke Test ===" + cargo build --workspace + @echo "--- jk --version ---" + @cargo run --package januskey --bin jk -- --version 2>/dev/null || echo "WARN: jk --version not yet implemented" + @echo "--- jk --help ---" + @cargo run --package januskey --bin jk -- --help 2>/dev/null || echo "WARN: jk --help not yet implemented" + @echo "Smoke test complete." + +# Validate contractile files parse correctly +test-contracts: + @echo "=== Contract Tests ===" + @if command -v must >/dev/null 2>&1; then must check; \ + else \ + echo "must not found — validating contractile files manually..."; \ + for f in contractiles/intend contractiles/must contractiles/trust; do \ + if [ -f "$$f" ]; then echo " [OK] $$f exists and is non-empty ($$(wc -c < $$f) bytes)"; \ + else echo " [FAIL] $$f missing"; fi; \ + done; \ + fi + +# Check Idris2 ABI proofs (requires idris2) +test-proofs: + @echo "=== Proof Regression ===" + @if command -v idris2 >/dev/null 2>&1; then \ + for f in src/abi/Types.idr src/abi/Layout.idr src/abi/Foreign.idr src/abi/Proofs.idr; do \ + if [ -f "$$f" ]; then \ + echo "Checking $$f..."; \ + idris2 --check "$$f" && echo " [OK] $$f" || echo " [FAIL] $$f"; \ + else \ + echo " [SKIP] $$f not found"; \ + fi; \ + done; \ + else \ + echo "SKIP: idris2 not installed. Install via: pack install-app idris2"; \ + fi + +# Run full test suite (all categories) +test-all: test test-p2p test-regressions test-e2e test-aspect test-contracts test-proofs smoke + +# [AUTO-GENERATED] Multi-arch / RISC-V target +build-riscv: + @echo "Building for RISC-V..." + cross build --target riscv64gc-unknown-linux-gnu + +# Run panic-attacker pre-commit scan +assail: + @command -v panic-attack >/dev/null 2>&1 && panic-attack assail . || echo "panic-attack not found — install from https://github.com/hyperpolymath/panic-attacker" + +# Self-diagnostic — checks dependencies, permissions, paths +doctor: + @echo "Running diagnostics for januskey..." + @echo "Checking required tools..." + @command -v just >/dev/null 2>&1 && echo " [OK] just" || echo " [FAIL] just not found" + @command -v git >/dev/null 2>&1 && echo " [OK] git" || echo " [FAIL] git not found" + @command -v cargo >/dev/null 2>&1 && echo " [OK] cargo" || echo " [FAIL] cargo not found" + @command -v rustc >/dev/null 2>&1 && echo " [OK] rustc ($$(rustc --version))" || echo " [FAIL] rustc not found" + @command -v idris2 >/dev/null 2>&1 && echo " [OK] idris2" || echo " [INFO] idris2 not found (optional, for proof checking)" + @echo "Checking for hardcoded paths..." + @grep -rn '$$HOME\|$$ECLIPSE_DIR' --include='*.rs' --include='*.ex' --include='*.res' --include='*.gleam' --include='*.sh' . 2>/dev/null | head -5 || echo " [OK] No hardcoded paths" + @echo "Diagnostics complete." + +# Auto-repair common issues +heal: + @echo "Attempting auto-repair for januskey..." + @echo "Fixing permissions..." + @find . -name "*.sh" -exec chmod +x {} \; 2>/dev/null || true + @echo "Cleaning stale caches..." + @rm -rf .cache/stale 2>/dev/null || true + @echo "Repair complete." + +# Guided tour of key features +tour: + @echo "=== januskey Tour ===" + @echo "" + @echo "1. Project structure:" + @ls -la + @echo "" + @echo "2. Available commands: just --list" + @echo "" + @echo "3. Read README.adoc for full overview" + @echo "4. Read EXPLAINME.adoc for architecture decisions" + @echo "5. Run 'just doctor' to check your setup" + @echo "" + @echo "Tour complete! Try 'just --list' to see all available commands." + +# Open feedback channel with diagnostic context +help-me: + @echo "=== januskey Help ===" + @echo "Platform: $(uname -s) $(uname -m)" + @echo "Shell: $SHELL" + @echo "" + @echo "To report an issue:" + @echo " https://github.com/hyperpolymath/januskey/issues/new" + @echo "" + @echo "Include the output of 'just doctor' in your report." + + +# Print the current CRG grade (reads from READINESS.md '**Current Grade:** X' line) +crg-grade: + @grade=$$(grep -oP '(?<=\*\*Current Grade:\*\* )[A-FX]' READINESS.md 2>/dev/null | head -1); \ + [ -z "$$grade" ] && grade="X"; \ + echo "$$grade" + +# Generate a shields.io badge markdown for the current CRG grade +# Looks for '**Current Grade:** X' in READINESS.md; falls back to X +crg-badge: + @grade=$$(grep -oP '(?<=\*\*Current Grade:\*\* )[A-FX]' READINESS.md 2>/dev/null | head -1); \ + [ -z "$$grade" ] && grade="X"; \ + case "$$grade" in \ + A) color="brightgreen" ;; B) color="green" ;; C) color="yellow" ;; \ + D) color="orange" ;; E) color="red" ;; F) color="critical" ;; \ + *) color="lightgrey" ;; esac; \ + echo "[![CRG $$grade](https://img.shields.io/badge/CRG-$$grade-$$color?style=flat-square)](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades)" diff --git a/.machine_readable/contractiles/Mustfile.a2ml b/.machine_readable/contractiles/Mustfile.a2ml new file mode 100644 index 0000000..21d3e66 --- /dev/null +++ b/.machine_readable/contractiles/Mustfile.a2ml @@ -0,0 +1,161 @@ +# SPDX-License-Identifier: MPL-2.0 +# Mustfile — Physical state contract for januskey +# Author: Jonathan D.A. Jewell +# +# What MUST be true about this repository. Hard requirements. +# Run with: must check (see also `just test-contracts`) +# Fix with: must fix (where a deterministic fix exists) +# +# Provenance: populated 2026-06-12 from the repo's prior contractile set — +# .machine_readable/MUST.contractile (universal invariants) and +# contractiles/must/Mustfile.a2ml (file-presence + banned checks) — replacing +# the rsr-template-repo stub supplied by estate-standardization-20260607. + +@abstract: +Physical-state invariants for januskey, a cryptographic key-custody and +reversible-file-operations tool. These are hard requirements — CI and +pre-commit hooks fail if any check fails. MUST is enforced regardless of +trust level: even maximal-trust agents cannot violate MUST constraints. +@end + +## File Presence + +### license-present +- description: LICENSE file must exist +- run: test -f LICENSE +- severity: critical + +### readme-present +- description: README must exist +- run: test -f README.adoc || test -f README.md +- severity: critical + +### security-policy +- description: SECURITY.md must exist +- run: test -f SECURITY.md +- severity: critical + +### ai-manifest +- description: 0-AI-MANIFEST.a2ml must exist +- run: test -f 0-AI-MANIFEST.a2ml +- severity: critical + +### governance-docs +- description: GOVERNANCE.adoc, MAINTAINERS.adoc, CODEOWNERS must exist +- run: test -f GOVERNANCE.adoc && test -f MAINTAINERS.adoc && test -f .github/CODEOWNERS +- severity: critical + +### machine-readable-dir +- description: .machine_readable/ directory must exist +- run: test -d .machine_readable +- severity: critical + +### threat-model-present +- description: threat-model.a2ml exists and is non-empty (MCP exposure is blocked without it) +- run: test -s .machine_readable/threat-model.a2ml +- severity: critical + +## Directory Structure + +### contractiles-flat-complete +- description: All seven flat contractile files exist (estate layout 2026-06) +- run: test -f .machine_readable/contractiles/Intentfile.a2ml && test -f .machine_readable/contractiles/Mustfile.a2ml && test -f .machine_readable/contractiles/Trustfile.a2ml && test -f .machine_readable/contractiles/Adjustfile.a2ml && test -f .machine_readable/contractiles/Dustfile.a2ml && test -f .machine_readable/contractiles/Bustfile.a2ml +- severity: critical + +### six-directory-present +- description: 6a2 directory exists with required files +- run: test -d .machine_readable/6a2 && test -f .machine_readable/6a2/META.a2ml && test -f .machine_readable/6a2/ECOSYSTEM.a2ml && test -f .machine_readable/6a2/STATE.a2ml && test -f .machine_readable/6a2/PLAYBOOK.a2ml && test -f .machine_readable/6a2/AGENTIC.a2ml && test -f .machine_readable/6a2/NEUROSYM.a2ml +- severity: critical + +### anchor-directory +- description: anchor directory exists in 6a2 (renamed from anchors/ in the estate wave) +- run: test -d .machine_readable/6a2/anchor && test -f .machine_readable/6a2/anchor/ANCHOR.a2ml +- severity: warning + +### self-validating-structure +- description: self-validating directory carries the shared k9 template set plus the januskey guard +- run: test -d .machine_readable/self-validating && test -f .machine_readable/self-validating/januskey-metadata.k9.ncl +- severity: warning + +## Language Policy + +### no-new-typescript +- description: No TypeScript files (use AffineScript per estate language policy) +- run: test -z "$(git ls-files '*.ts' '*.tsx' 2>/dev/null)" +- severity: critical + +### no-new-python +- description: No Python files (use Julia/Rust per estate language policy) +- run: test -z "$(git ls-files '*.py' 2>/dev/null)" +- severity: critical + +### no-new-go +- description: No Go files (use Rust per estate language policy) +- run: test -z "$(git ls-files '*.go' 2>/dev/null)" +- severity: critical + +### no-npm-lockfiles +- description: No npm/bun/yarn/pnpm dependency artefacts — Deno only for JS +- run: test ! -f package-lock.json && test ! -f bun.lockb && test ! -f yarn.lock && test ! -f pnpm-lock.yaml +- severity: critical + +## Banned Patterns + +### no-hardcoded-paths +- description: No hardcoded developer paths +- run: "! grep -rn '/home/hyper\|/mnt/eclipse' --include='*.rs' --include='*.zig' --include='*.idr' --include='*.sh' . 2>/dev/null | grep -v '.git/' | head -1 | grep -q ." +- severity: critical + +### no-dangerous-proof-escapes +- description: No believe_me / assert_total in Idris2 proof code +- run: "! grep -rnE 'believe_me|assert_total' src/abi/ generated/idrisiser/ 2>/dev/null | head -1 | grep -q ." +- severity: critical + +### no-unsafe-without-comment +- description: No unsafe {} blocks in Rust without a safety comment (crates forbid unsafe_code) +- run: "! grep -rn 'unsafe ' --include='*.rs' crates/ src/ 2>/dev/null | grep -v '// SAFETY' | head -1 | grep -q ." +- severity: critical + +### no-dockerfiles +- description: No Dockerfiles (use Containerfile / stapeln.toml) +- run: test ! -f Dockerfile +- severity: warning + +### no-makefiles +- description: No Makefiles (use Justfile) +- run: test ! -f Makefile +- severity: warning + +## License & Provenance + +### spdx-headers +- description: SPDX-License-Identifier header on every source file +- run: "! git ls-files '*.rs' '*.zig' '*.idr' '*.sh' | xargs grep -L 'SPDX-License-Identifier' 2>/dev/null | head -1 | grep -q ." +- severity: critical + +### license-not-removed +- description: No removal or modification of LICENSE file without maintainer approval +- run: test -f LICENSE && grep -q 'Mozilla Public License' LICENSE +- severity: critical + +## CI & Verification + +### ci-workflows-present +- description: Core CI workflows must not be removed without explicit approval +- run: test -f .github/workflows/rust-ci.yml && test -f .github/workflows/hypatia-scan.yml && test -f .github/workflows/codeql.yml +- severity: critical + +### abi-proofs-preserved +- description: Idris2 ABI definitions and proofs must not be removed (changes require proof update) +- run: test -f src/abi/Types.idr && test -f src/abi/Proofs.idr && test -f src/abi/Foreign.idr +- severity: critical + +### generated-code-in-generated +- description: Generated code lives in generated/ only +- run: test -d generated +- severity: warning + +### tests-not-deleted +- description: Test directories must not be deleted or emptied +- run: test -d tests && test -d crates/januskey-cli/tests +- severity: critical diff --git a/contractiles/trust/Trustfile.a2ml b/.machine_readable/contractiles/Trustfile.a2ml similarity index 77% rename from contractiles/trust/Trustfile.a2ml rename to .machine_readable/contractiles/Trustfile.a2ml index f02fcd0..e6589e0 100644 --- a/contractiles/trust/Trustfile.a2ml +++ b/.machine_readable/contractiles/Trustfile.a2ml @@ -1,25 +1,35 @@ # SPDX-License-Identifier: MPL-2.0 -# Trustfile (A2ML Canonical) — CRYPTOGRAPHIC TOOL, TIGHTENED -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# Trustfile — Trust boundaries and integrity invariants for januskey +# Author: Jonathan D.A. Jewell # -# Hardened 2026-04-19 against the generic "maximal by default" template. -# Januskey is a key-management tool: any LLM/agent interaction with it must -# treat every key, audit entry, and Trustfile rule as attacker-reachable. +# CRYPTOGRAPHIC TOOL, TIGHTENED. Hardened 2026-04-19 against the generic +# "maximal by default" template. Januskey is a key-management tool: any +# LLM/agent interaction with it must treat every key, audit entry, and +# Trustfile rule as attacker-reachable. +# +# Provenance: populated 2026-06-12 by porting the hardened +# contractiles/trust/Trustfile.a2ml (2026-04-19, removed by the estate +# flattening) plus the provenance/integrity keys of the old nested +# .machine_readable/contractiles/trust/Trustfile.a2ml and the deny-list of +# .machine_readable/TRUST.contractile. Replaces the rsr-template-repo stub +# (which wrongly declared trust level "maximal"). @abstract: -Trust and provenance verification for Januskey. +Trust and provenance verification for januskey. Crypto-minimal baseline: deny by default. Every allowed action is an explicit, justified exception. A key-management tool's Trustfile is among the tightest in the estate — if a rule seems convenient but -unjustified, it has no place here. +unjustified, it has no place here. Trust never overrides MUST. @end @trust-level: minimal @trust-boundary: repo-source-only @trust-actions: [read-source, build-no-net, test-no-net, lint, format] @trust-deny: [ - # Git-ops (inherited from previous template) - delete-branch, force-push, modify-ci-secrets, publish, + # Git-ops (inherited from the previous template) + delete-branch, force-push, push-to-main, modify-ci-secrets, publish, + delete-files-bulk, modify-license, modify-security-policy, + remove-proofs, disable-ci-checks, # Crypto-specific denials (added 2026-04-19) read-key-material, write-key-material, read-keystore, write-keystore, read-audit-log, write-audit-log, modify-trustfile, modify-threat-model, @@ -45,13 +55,25 @@ unjustified, it has no place here. docker, podman, nix-shell, guix ] -## Integrity — crypto-specific +## Provenance + +### source-control-provenance +- description: Source control is git on GitHub, CI-verified; commit signing preferred +- run: git log -1 --format='%ae' | grep -qE '(hyperpolymath|j\.d\.a\.jewell|noreply.github.com)' +- severity: warning ### license-content - description: LICENSE contains expected SPDX identifier -- run: grep -q 'SPDX\|License\|MIT\|Apache\|PMPL\|MPL' LICENSE +- run: grep -q 'SPDX\|License\|MPL' LICENSE +- severity: critical + +### dependency-pinning +- description: GitHub Actions are SHA-pinned; Cargo.lock is committed +- run: test -f Cargo.lock - severity: critical +## Integrity — crypto-specific + ### no-secrets-committed - description: No .env or credential files in repo - run: test ! -f .env && test ! -f credentials.json && test ! -f .env.local @@ -80,7 +102,7 @@ unjustified, it has no place here. # Passes when the current Trustfile still declares minimal trust level. # Any LLM attempt to flip this back to maximal must go through a # commit message containing the phrase "human-approved trust widening". - grep -q '^@trust-level: minimal' contractiles/trust/Trustfile.a2ml + grep -q '^@trust-level: minimal' .machine_readable/contractiles/Trustfile.a2ml - severity: critical ### threat-model-present @@ -151,6 +173,13 @@ unjustified, it has no place here. fi; \ done +## Verification goals (ported from the nested trust contractile) + +### reproducible-builds +- description: Reproducible builds are a goal; SBOM generation required; attestation sigstore-preferred +- severity: advisory +- run: echo "goal-tracking entry — see READINESS.md aspect matrix" + ## Notes for maintainers # Widening these rules requires: diff --git a/.machine_readable/contractiles/bust/Bustfile.a2ml b/.machine_readable/contractiles/bust/Bustfile.a2ml deleted file mode 100644 index 45f1201..0000000 --- a/.machine_readable/contractiles/bust/Bustfile.a2ml +++ /dev/null @@ -1,28 +0,0 @@ -// Bustfile.a2ml — meta-repo bust contractile (breakage / rollback) -// SPDX-License-Identifier: MPL-2.0 - -Bust { - name: "januskey" - version: "1.0.0" - description: "Rollback procedures when something breaks in the meta-repo" - - scenarios: { - "bad-pointer-bump": "git revert in meta-repo; child repo itself untouched" - "submodule-pointer-points-at-missing-sha": "git submodule update --init --checkout resets child to parent-recorded SHA; OR revert the stale bump commit" - "submodule-orphan-after-local-only-commit": "roll back locally with git reset to before the stranded commit; fix remote situation before re-attempting" - "accidental-private-repo-content-leaked-to-public-submodule": "hard-rotate the leaked secret immediately; git-filter-repo or BFG on the submodule's own history; public re-publication only after rotation complete" - } - - escalation-ladder: [ - "1. revert the meta-repo commit (reversible, low blast radius)", - "2. reset the local submodule clone (affects only local workspace)", - "3. force-push to main — PROHIBITED without explicit user confirmation (violates branch protection)", - "4. registry-level (delete/archive the GitHub repo) — human-only action, never by AI" - ] - - backup-points: [ - "GitHub serves as the durable backup for every submodule's own history", - "Meta-repo history on origin/main is the durable backup for pointer state", - "Local backup tags (backup/pre--) retained on risky rewrites" - ] -} diff --git a/.machine_readable/contractiles/bust/bust.ncl b/.machine_readable/contractiles/bust/bust.ncl deleted file mode 100644 index fc8cb8c..0000000 --- a/.machine_readable/contractiles/bust/bust.ncl +++ /dev/null @@ -1,66 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Bust — error-handling / failure-recovery runner -# -# Pairs with: Bustfile.a2ml (same directory) -# Verb: bust -# Semantics: every declared failure mode must have a recovery path that has -# been exercised. Runner injects failures (via declared probes) -# and verifies the recovery path works. Hard gate on any -# failure-mode with missing or broken recovery. -# CLI: `contractile bust check` → list failure modes + recovery status -# `contractile bust drill` → inject declared failures, verify recovery -# -# Anything else in this directory is human-only notes/archive; machines ignore. -# -# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema. -# See: docs/CONTRACTILE-SPEC.adoc - -let base = import "../_base.ncl" in - -{ - pedigree = base.pedigree_schema & { - contractile_verb = "bust", - semantics = "error handling + failure recovery", - security = { - leash = 'Kennel, - trust_level = "controlled failure injection; scoped to system-under-test", - allow_network = false, - allow_filesystem_write = true, # drills may write transient state (tmp dirs, test DBs) - allow_subprocess = true, - injection_scope = "system-under-test-only", - }, - metadata = { - name = "bust-runner", - version = "1.0.0", - description = "Exercises declared failure modes and verifies recovery paths. Hard-gates on any failure mode without working recovery.", - paired_xfile = "Bustfile.a2ml", - author = "Jonathan D.A. Jewell ", - }, - }, - - schema = { - failure_modes - | Array { - id | String, - description | String, - class | [| 'network, 'disk_full, 'oom, 'timeout, 'partial_write, 'panic, 'crash, 'rollback, 'concurrency |], - # TODO: migrate to base.probe_schema (structured probe) when CLI supports it - injection_probe | String, # command that deterministically causes this failure - # TODO: migrate to base.probe_schema (structured probe) when CLI supports it - recovery_probe | String, # command that verifies recovery (exit 0 = recovered) - expected_recovery_time_seconds | Number | default = 30, - # status_core values: 'declared, 'verified, 'failing; bust adds 'drilled - status | [| 'declared, 'drilled, 'verified, 'failing |] | default = 'declared, - notes | String | optional, - }, - }, - - # Runner behaviour — inherits from base.run_defaults. - # bust adds record_recovery_times for performance tier feeding. - run = base.run_defaults & { - on_any_fail = "exit-nonzero", # missing or broken recovery blocks merge - report_format = "a2ml", - emit_summary = true, - record_recovery_times = true, # feeds the performance tier - }, -} diff --git a/.machine_readable/contractiles/dust/Dustfile.a2ml b/.machine_readable/contractiles/dust/Dustfile.a2ml deleted file mode 100644 index 0d619ee..0000000 --- a/.machine_readable/contractiles/dust/Dustfile.a2ml +++ /dev/null @@ -1,22 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Dustfile — Cleanup and Hygiene Contract - -[dustfile] -version = "1.0.0" -format = "a2ml" - -[cleanup] -stale-branch-policy = "delete-after-merge" -artifact-retention = "90-days" -cache-policy = "clear-on-release" - -[hygiene] -linting = "required" -formatting = "required" -dead-code-removal = "encouraged" -todo-tracking = "tracked-in-issues" - -[reversibility] -backup-before-destructive = true -rollback-mechanism = "git-revert" -data-retention-policy = "preserve-30-days" diff --git a/.machine_readable/contractiles/trust/Trustfile.a2ml b/.machine_readable/contractiles/trust/Trustfile.a2ml deleted file mode 100644 index 0c95e15..0000000 --- a/.machine_readable/contractiles/trust/Trustfile.a2ml +++ /dev/null @@ -1,22 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Trustfile — Integrity and Provenance Contract - -[trustfile] -version = "1.0.0" -format = "a2ml" - -[provenance] -source-control = "git" -forge = "github" -ci-verified = true -signing-policy = "commit-signing-preferred" - -[integrity] -spdx-compliant = true -license-audit = "required" -dependency-pinning = "sha-pinned" - -[verification] -reproducible-builds = "goal" -sbom-generation = "required" -attestation = "sigstore-preferred" diff --git a/.machine_readable/self-validating/README.adoc b/.machine_readable/self-validating/README.adoc new file mode 100644 index 0000000..d5ddc34 --- /dev/null +++ b/.machine_readable/self-validating/README.adoc @@ -0,0 +1,193 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell += K9 Contractiles +:toc: left +:icons: font + +== What Are K9 Contractiles? + +K9 contractiles are self-validating components that combine configuration, validation, and deployment logic in a single file format. They implement the RSR principle of "self-describing artifacts" by embedding contracts and orchestration directly in the component. + +== The Three Security Levels + +K9 components declare their trust requirements using "The Leash" security model: + +[horizontal] +`'Kennel`:: Pure data, no execution (safest) +`'Yard`:: Nickel evaluation with contracts (medium trust) +`'Hunt`:: Full execution with Just recipes (requires signature) + +== januskey Components + +[horizontal] +`januskey-metadata.k9.ncl`:: Kennel-level guard carrying januskey's security +invariants (banned/required crypto algorithms, safety invariants for crypto +code, test thresholds, language policy, RSR compliance flags). +`methodology-guard.k9.ncl`:: Validator that checks agent work respects +`bot_directives/methodology.a2ml` (believe_me / assert_total ceilings — +januskey's Idris2 ABI proofs in `src/abi/` hold both at 0 — plus STATE +placeholder rejection and coverage staleness). + +Repo-real validation entry points the components point at: `just build` +(cargo build --workspace --release), `just test` (cargo test --workspace), +`just test-contracts`, `just test-proofs` (Idris2 ABI check). + +== Example Components + +This directory contains example K9 contractiles for common repository tasks: + +=== Kennel Level (Pure Data) + +**File:** `examples/project-metadata.k9.ncl` + +Pure configuration data with no execution. Safe to include in any repository. + +**Use cases:** +- Project metadata (name, version, description) +- Build configuration +- Tool settings +- Data schemas + +**Security:** No signature required, data-only. + +=== Yard Level (Validated Config) + +**File:** `examples/ci-config.k9.ncl` + +Configuration with Nickel contracts for runtime validation. Evaluated safely without I/O. + +**Use cases:** +- CI/CD configuration with validation +- Deployment parameters +- Database schemas with constraints +- API specifications + +**Security:** Signature recommended, Nickel evaluation only. + +=== Hunt Level (Full Execution) + +**File:** `examples/setup-repo.k9.ncl` + +Full execution with Just recipes. Can run shell commands and modify filesystem. + +**Use cases:** +- Repository setup scripts +- Deployment automation +- System configuration +- Package installation + +**Security:** **Signature required**, full system access. + +== Usage in Your Repository + +=== 1. Create K9 Components + +Choose the appropriate security level for your use case: + +[source,bash] +---- +# Kennel: Pure configuration +cp .machine_readable/self-validating/examples/project-metadata.k9.ncl config/metadata.k9.ncl + +# Yard: Validated configuration +cp .machine_readable/self-validating/examples/ci-config.k9.ncl .github/ci.k9.ncl + +# Hunt: Full automation +cp .machine_readable/self-validating/examples/setup-repo.k9.ncl scripts/setup.k9.ncl +---- + +=== 2. Validate Components + +[source,bash] +---- +# Validate Nickel syntax and contracts +nickel typecheck config/metadata.k9.ncl + +# Verify Hunt-level signature (if signed) +./must verify scripts/setup.k9.ncl +---- + +=== 3. Execute Components + +[source,bash] +---- +# Kennel: Export as JSON +nickel export config/metadata.k9.ncl > metadata.json + +# Yard: Evaluate with validation +nickel eval .github/ci.k9.ncl + +# Hunt: Run with Just (dry-run first!) +./must --dry-run run scripts/setup.k9.ncl +./must run scripts/setup.k9.ncl +---- + +== Integration with RSR + +K9 contractiles integrate with other RSR standards: + +**STATE.a2ml**:: K9 components can generate or validate STATE.a2ml +**ECOSYSTEM.a2ml**:: K9 can automate cross-repo operations +**META.a2ml**:: K9 can enforce architectural decisions + +== Security Best Practices + +=== For Kennel/Yard Components + +✅ **Safe to use without signatures** + +✅ **Review Nickel code before use** + +✅ **Validate contracts match expectations** + +=== For Hunt Components + +⚠️ **ALWAYS verify signatures** + +⚠️ **Review Just recipes carefully** + +⚠️ **Run dry-run mode first** + +⚠️ **Never run as root unless required** + +⚠️ **Sandbox external components** + +**See:** https://github.com/hyperpolymath/k9-svc/blob/main/docs/SECURITY-BEST-PRACTICES.adoc + +== Template Files + +Use these as starting points for your own K9 components: + +- `template-kennel.k9.ncl` - Pure data template +- `template-yard.k9.ncl` - Validated config template +- `template-hunt.k9.ncl` - Full execution template + +== Dependencies + +To use K9 contractiles in your repository: + +[source,bash] +---- +# Install Nickel (configuration language) +curl -L https://github.com/tweag/nickel/releases/latest/download/nickel-linux-x86_64 -o nickel +chmod +x nickel && sudo mv nickel /usr/local/bin/ + +# Install Just (task runner, for Hunt level) +cargo install just + +# Clone K9-SVC (for must shim and tooling) +git clone https://github.com/hyperpolymath/k9-svc.git +---- + +== Learn More + +- **K9-SVC Specification:** https://github.com/hyperpolymath/k9-svc/blob/main/SPEC.adoc +- **K9 User Guide:** https://github.com/hyperpolymath/k9-svc/blob/main/GUIDE.adoc +- **Security Documentation:** https://github.com/hyperpolymath/k9-svc/blob/main/docs/SECURITY-FAQ.adoc +- **IANA Media Type:** `application/vnd.k9+nickel` + +== Contributing + +When adding K9 contractiles to your repository: + +1. Use appropriate security level (Kennel > Yard > Hunt) +2. Document what each component does +3. Include validation contracts in Yard/Hunt components +4. Sign Hunt-level components before committing +5. Add K9 validation to CI/CD pipeline + +**Questions?** Open an issue on https://github.com/hyperpolymath/k9-svc diff --git a/.machine_readable/self-validating/examples/ci-config.k9.ncl b/.machine_readable/self-validating/examples/ci-config.k9.ncl new file mode 100644 index 0000000..9fe314e --- /dev/null +++ b/.machine_readable/self-validating/examples/ci-config.k9.ncl @@ -0,0 +1,126 @@ +K9! +# SPDX-License-Identifier: MPL-2.0 +# Example Yard-level K9 component: CI/CD configuration with validation +# Security Level: Yard (Nickel evaluation, contract validation) +# Signature recommended but not required + +{ + pedigree = { + schema_version = "1.0.0", + component_type = "ci-configuration", + security = { + leash = 'Yard, + trust_level = "validated-config", + allow_network = false, + allow_filesystem_write = false, + allow_subprocess = false, + }, + metadata = { + name = "ci-config", + version = "1.0.0", + description = "CI/CD configuration with runtime validation", + author = "Jonathan D.A. Jewell ", + }, + }, + + # CI/CD configuration with Nickel contracts + ci = { + # Platform must be a known CI provider + platform + | [| 'GitHubActions, 'GitLabCI, 'CircleCI, 'TravisCI |] + = 'GitHubActions, + + # Build matrix with validation + matrix = { + # Operating systems to test on + os + | Array String + | std.array.NonEmpty + = ["ubuntu-latest", "macos-latest"], + + # Language versions to test + versions + | Array String + | std.array.NonEmpty + = ["stable", "beta"], + }, + + # Workflow steps with validation + steps = [ + { + name = "Checkout", + action = "actions/checkout@v4", + # Version must be SHA-pinned for security + sha | String | std.string.NonEmpty = "b4ffde65f46336ab88eb53be808477a3936bae11", + }, + { + name = "Build", + run = "just build", + }, + { + name = "Test", + run = "just test", + }, + { + name = "Lint", + run = "just lint", + }, + ], + + # Deployment configuration + deploy = { + enabled | Bool = false, + + # Only deploy from main branch + branch + | String + | std.contract.from_predicate (fun b => b == "main" || b == "master") + = "main", + + # Deployment requires manual approval + requires_approval | Bool = true, + }, + + # Security scanning + security = { + enabled | Bool = true, + + scanners = [ + { + name = "CodeQL", + languages = ["rust", "javascript"], + }, + { + name = "OSSF Scorecard", + enabled = true, + }, + { + name = "TruffleHog", + scan_for = "secrets", + }, + ], + }, + + # Notification settings + notifications = { + on_success = "never", + on_failure = "always", + channels = ["email"], + }, + }, + + # Validation rules (enforced by Nickel) + validation = { + # At least one OS must be specified + check_os = std.array.length ci.matrix.os > 0, + + # At least one version must be tested + check_versions = std.array.length ci.matrix.versions > 0, + + # Must have at least build and test steps + check_steps = std.array.length ci.steps >= 2, + + # Security scanning must be enabled + check_security = ci.security.enabled == true, + }, +} diff --git a/.machine_readable/self-validating/examples/project-metadata.k9.ncl b/.machine_readable/self-validating/examples/project-metadata.k9.ncl new file mode 100644 index 0000000..fc64891 --- /dev/null +++ b/.machine_readable/self-validating/examples/project-metadata.k9.ncl @@ -0,0 +1,59 @@ +K9! +# SPDX-License-Identifier: MPL-2.0 +# Example Kennel-level K9 component: Project metadata +# Security Level: Kennel (pure data, no execution) +# No signature required + +{ + pedigree = { + schema_version = "1.0.0", + component_type = "project-metadata", + security = { + leash = 'Kennel, + trust_level = "data-only", + allow_network = false, + allow_filesystem_write = false, + allow_subprocess = false, + }, + metadata = { + name = "project-metadata", + version = "1.0.0", + description = "Pure data configuration for project metadata", + author = "Jonathan D.A. Jewell ", + }, + }, + + # Project configuration + project = { + name = "januskey", + version = "1.0.0", + description = "Reversible file operations (formal proofs pending) and passphrase-gated key custody through Maximal Principle Reduction", + + repository = { + url = "https://github.com/hyperpolymath/januskey", + type = "git", + }, + + author = { + name = "Jonathan D.A. Jewell", + email = "j.d.a.jewell@open.ac.uk", + organization = "hyperpolymath", + }, + + license = "MPL-2.0", + + keywords = [ + "rhodium-standard", + "rsr", + "hyperpolymath", + "reversible-operations", + "key-management", + ], + }, + + # Export as JSON for other tools + export = { + format = "json", + destination = "project-metadata.json", + }, +} diff --git a/.machine_readable/self-validating/examples/setup-repo.k9.ncl b/.machine_readable/self-validating/examples/setup-repo.k9.ncl new file mode 100644 index 0000000..d1fc8bb --- /dev/null +++ b/.machine_readable/self-validating/examples/setup-repo.k9.ncl @@ -0,0 +1,167 @@ +K9! +# SPDX-License-Identifier: MPL-2.0 +# Example Hunt-level K9 component: Repository setup automation +# Security Level: Hunt (full execution with Just recipes) +# ⚠️ SIGNATURE REQUIRED - DO NOT RUN WITHOUT VERIFICATION + +{ + pedigree = { + schema_version = "1.0.0", + component_type = "repository-setup", + security = { + leash = 'Hunt, + trust_level = "full-system-access", + allow_network = true, + allow_filesystem_write = true, + allow_subprocess = true, + signature_required = true, + }, + metadata = { + name = "setup-repo", + version = "1.0.0", + description = "Automated repository setup with RSR standards", + author = "Jonathan D.A. Jewell ", + }, + warnings = [ + "This component has full system access", + "Only run from trusted sources with verified signatures", + "Review Just recipes before execution", + "Use dry-run mode first: ./must --dry-run run setup-repo.k9.ncl", + ], + }, + + # Configuration with contracts + config = { + repo_name + | String + | std.string.NonEmpty + = "my-new-repo", + + repo_type + | [| 'Library, 'Application, 'Tool, 'Specification |] + = 'Application, + + primary_language + | String + | std.string.NonEmpty + = "rust", + + # RSR compliance features to enable + features = { + checkpoint_files | Bool = true, # STATE.a2ml, ECOSYSTEM.a2ml, META.a2ml + security_workflows | Bool = true, # CodeQL, Scorecard, etc. + quality_checks | Bool = true, # Linting, formatting + mirroring | Bool = false, # GitLab/Bitbucket mirrors + }, + + # Git configuration + git = { + default_branch = "main", + initial_commit | Bool = true, + remote_url | String = "", + }, + }, + + # Just recipes for execution + # These run when: ./must run setup-repo.k9.ncl + recipes = { + # Main entry point + default = { + recipe = "setup", + description = "Set up RSR-compliant repository", + }, + + # Individual setup tasks + setup = { + dependencies = ["check-env", "create-structure", "init-git", "setup-workflows"], + commands = [ + "echo '✅ Repository setup complete!'", + "echo 'Run: git status to see changes'", + ], + }, + + "check-env" = { + description = "Verify required tools are installed", + commands = [ + "command -v git || (echo 'ERROR: git not found' && exit 1)", + "command -v just || (echo 'ERROR: just not found' && exit 1)", + "command -v nickel || (echo 'ERROR: nickel not found' && exit 1)", + "echo '✓ All required tools present'", + ], + }, + + "create-structure" = { + description = "Create RSR directory structure", + commands = [ + "mkdir -p src/ docs/ tests/ scripts/", + "mkdir -p .github/workflows/", + "mkdir -p .machine_readable/contractiles/k9/", + "echo '✓ Directory structure created'", + ], + }, + + "init-git" = { + description = "Initialize Git repository", + commands = [ + "git init -b %{config.git.default_branch}", + "git config user.name 'Jonathan D.A. Jewell'", + "git config user.email 'j.d.a.jewell@open.ac.uk'", + "echo '✓ Git initialized'", + ], + }, + + "setup-workflows" = { + description = "Add RSR-compliant workflows", + commands = [ + # This would copy workflow templates + # In a real implementation, would fetch from rsr-template-repo + "echo '✓ Workflows configured'", + ], + }, + + "create-checkpoint-files" = { + description = "Create STATE.a2ml, ECOSYSTEM.a2ml, META.a2ml", + commands = [ + "echo '(state (version \"1.0.0\") (project \"%{config.repo_name}\"))' > STATE.a2ml", + "echo '(ecosystem (version \"1.0.0\") (name \"%{config.repo_name}\"))' > ECOSYSTEM.a2ml", + "echo '(meta (version \"1.0.0\") (project \"%{config.repo_name}\"))' > META.a2ml", + "echo '✓ Checkpoint files created'", + ], + }, + + "add-license" = { + description = "Add PMPL-1.0 license", + commands = [ + "curl -sL https://raw.githubusercontent.com/hyperpolymath/pmpl/main/LICENSE -o LICENSE", + "echo '✓ License added'", + ], + }, + + "add-readme" = { + description = "Create README.adoc from template", + commands = [ + "echo '= %{config.repo_name}' > README.adoc", + "echo '' >> README.adoc", + "echo 'Part of the Hyperpolymath ecosystem.' >> README.adoc", + "echo '✓ README created'", + ], + }, + + clean = { + description = "Remove generated files (careful!)", + commands = [ + "echo '⚠️ This will delete all generated files'", + "echo 'Press Ctrl+C to cancel, or wait 5 seconds...'", + "sleep 5", + "rm -f STATE.a2ml ECOSYSTEM.a2ml META.a2ml", + "echo '✓ Cleaned'", + ], + }, + }, + + # Validation (Yard-level checks before Hunt execution) + validation = { + check_repo_name = std.string.length config.repo_name > 0, + check_language = std.string.length config.primary_language > 0, + }, +} diff --git a/.machine_readable/svc/k9/januskey-metadata.k9.ncl b/.machine_readable/self-validating/januskey-metadata.k9.ncl similarity index 100% rename from .machine_readable/svc/k9/januskey-metadata.k9.ncl rename to .machine_readable/self-validating/januskey-metadata.k9.ncl diff --git a/.machine_readable/self-validating/methodology-guard.k9.ncl b/.machine_readable/self-validating/methodology-guard.k9.ncl new file mode 100644 index 0000000..128575e --- /dev/null +++ b/.machine_readable/self-validating/methodology-guard.k9.ncl @@ -0,0 +1,75 @@ +K9! +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# K9 Validator: Methodology Guard +# Checks that agent work respects methodology constraints declared in +# bot_directives/methodology.a2ml. +# +# Usage: k9 validate methodology-guard + +let methodology_guard = { + name = "methodology-guard", + version = "1.0.0", + description = "Validates that agent work respects declared methodology constraints", + + # Required by the repo's "Validate K9 contracts" gate: every .k9.ncl + # carries a pedigree. This guard only reads files and reports — data-only, + # no network / write / subprocess access. + pedigree = { + name = "methodology-guard", + schema_version = "1.0.0", + component_type = "methodology-validator", + security = { + leash = 'Kennel, + trust_level = "data-only", + allow_network = false, + allow_filesystem_write = false, + allow_subprocess = false, + }, + }, + + checks = { + divergent_invariant_language = { + description = "No files in languages violating the divergent language invariant", + severity = "error", + # When methodology.divergent-invariants.language-invariant is set, + # check that no new files introduce a different language for that purpose. + # Example: if language-invariant = "idris2", reject new .lean or .v files + # in the proof directories. + check_type = "file-extension-guard", + scope = "src/", + }, + + believe_me_ceiling = { + description = "believe_me count must not exceed declared ceiling", + severity = "error", + pattern = "believe_me", + ceiling_key = "methodology.divergent-invariants.believe-me-ceiling", + default_ceiling = 0, + }, + + assert_total_ceiling = { + description = "assert_total count must not exceed declared ceiling", + severity = "error", + pattern = "assert_total", + ceiling_key = "methodology.divergent-invariants.assert-total-ceiling", + default_ceiling = 0, + }, + + state_not_template = { + description = "STATE.a2ml must not contain template placeholders", + severity = "warning", + file = ".machine_readable/6a2/STATE.a2ml", + reject_patterns = ["{{PLACEHOLDER}}", "{{PROJECT}}", "rsr-template-repo"], + }, + + coverage_updated = { + description = "coverage.a2ml should be updated within 30 days", + severity = "info", + file = ".machine_readable/bot_directives/coverage.a2ml", + staleness_days = 30, + }, + }, +} +in methodology_guard diff --git a/.machine_readable/self-validating/template-hunt.k9.ncl b/.machine_readable/self-validating/template-hunt.k9.ncl new file mode 100644 index 0000000..b3fcb47 --- /dev/null +++ b/.machine_readable/self-validating/template-hunt.k9.ncl @@ -0,0 +1,136 @@ +K9! +# SPDX-License-Identifier: MPL-2.0 +# K9 Hunt-level template: Full execution with Just recipes +# Security Level: Hunt (full system access) +# ⚠️ SIGNATURE REQUIRED - Review carefully before use + +{ + pedigree = { + schema_version = "1.0.0", + component_type = "TODO: describe component type (e.g., 'deployment', 'setup-script')", + security = { + leash = 'Hunt, + trust_level = "full-system-access", + allow_network = true, + allow_filesystem_write = true, + allow_subprocess = true, + signature_required = true, + }, + metadata = { + name = "TODO: component-name", + version = "1.0.0", + description = "TODO: Detailed description of what this component does", + author = "Jonathan D.A. Jewell ", + }, + warnings = [ + "This component has full system access", + "Only run from trusted sources with verified signatures", + "Review all Just recipes before execution", + "Use dry-run mode first: ./must --dry-run run your-file.k9.ncl", + ], + side_effects = [ + "TODO: List what files/directories this creates or modifies", + "TODO: List what commands this executes", + "TODO: List what network access this requires", + ], + }, + + # Configuration with contracts (Yard-level validation) + config = { + # Add your configuration here with appropriate contracts + target_dir + | String + | std.string.NonEmpty + = "/tmp/k9-output", + + dry_run | Bool = false, + + # Add more config as needed + }, + + # Just recipes for execution + # These run when: ./must run your-file.k9.ncl + recipes = { + # Main entry point (runs by default) + default = { + recipe = "TODO: main-task", + description = "TODO: What the default recipe does", + }, + + # Define your recipes here + "main-task" = { + dependencies = ["check-prerequisites"], + commands = [ + "echo 'TODO: Add your commands here'", + # Example: Create directory + # "mkdir -p %{config.target_dir}", + # Example: Run a command + # "just build", + # Example: Conditional execution + # "@if [ \"%{config.dry_run}\" = \"true\" ]; then echo '[DRY-RUN] Would execute'; else actual-command; fi", + ], + }, + + "check-prerequisites" = { + description = "Verify required tools and permissions", + commands = [ + # Example: Check for required tools + # "command -v git || (echo 'ERROR: git not found' && exit 1)", + # Example: Check permissions + # "[ -w %{config.target_dir} ] || (echo 'ERROR: Cannot write to target directory' && exit 1)", + "echo '✓ Prerequisites checked'", + ], + }, + + # Add more recipes as needed + "build" = { + description = "Build the project", + commands = [ + "echo 'TODO: Add build commands'", + ], + }, + + "deploy" = { + description = "Deploy the application", + dependencies = ["build"], + commands = [ + "echo 'TODO: Add deployment commands'", + ], + }, + + "clean" = { + description = "Clean up generated files", + commands = [ + "echo '⚠️ This will delete files - waiting 3 seconds...'", + "sleep 3", + "echo 'TODO: Add cleanup commands'", + # "rm -rf %{config.target_dir}", + ], + }, + }, + + # Validation (Yard-level checks before Hunt execution) + validation = { + check_target_dir = std.string.length config.target_dir > 0, + # Add more validation as needed + }, +} + +# Usage: +# 1. Fill in TODO items above +# 2. Define configuration with contracts +# 3. Implement Just recipes with your commands +# 4. Test with dry-run: ./must --dry-run run your-file.k9.ncl +# 5. Review dry-run output carefully +# 6. Sign the component: ./must sign your-file.k9.ncl +# 7. Distribute with signature: your-file.k9.ncl.sig +# 8. Users verify and run: ./must verify && ./must run your-file.k9.ncl +# +# Security checklist: +# ✓ All TODO items filled in +# ✓ side_effects documented accurately +# ✓ Commands reviewed for safety +# ✓ No hardcoded secrets or credentials +# ✓ Proper error handling in recipes +# ✓ Tested in dry-run mode +# ✓ Component signed with trusted key diff --git a/.machine_readable/self-validating/template-kennel.k9.ncl b/.machine_readable/self-validating/template-kennel.k9.ncl new file mode 100644 index 0000000..4228b26 --- /dev/null +++ b/.machine_readable/self-validating/template-kennel.k9.ncl @@ -0,0 +1,54 @@ +K9! +# SPDX-License-Identifier: MPL-2.0 +# K9 Kennel-level template: Pure data configuration +# Security Level: Kennel (data-only, no execution) +# No signature required - safe for any use + +{ + pedigree = { + schema_version = "1.0.0", + component_type = "TODO: describe component type (e.g., 'build-config', 'metadata')", + security = { + leash = 'Kennel, + trust_level = "data-only", + allow_network = false, + allow_filesystem_write = false, + allow_subprocess = false, + }, + metadata = { + name = "TODO: component-name", + version = "1.0.0", + description = "TODO: Brief description of what this component contains", + author = "Jonathan D.A. Jewell ", + }, + }, + + # Your configuration data here + config = { + # Example: Pure data values + setting_1 = "value", + setting_2 = 42, + setting_3 = true, + + nested = { + key = "value", + }, + + list = [ + "item1", + "item2", + ], + }, + + # Optional: Export format specification + export = { + format = "json", # or "yaml", "toml" + destination = "output.json", + }, +} + +# Usage: +# 1. Fill in TODO items above +# 2. Add your configuration data to config = { ... } +# 3. Validate: nickel typecheck your-file.k9.ncl +# 4. Export: nickel export your-file.k9.ncl > output.json diff --git a/.machine_readable/self-validating/template-yard.k9.ncl b/.machine_readable/self-validating/template-yard.k9.ncl new file mode 100644 index 0000000..a723f5a --- /dev/null +++ b/.machine_readable/self-validating/template-yard.k9.ncl @@ -0,0 +1,84 @@ +K9! +# SPDX-License-Identifier: MPL-2.0 +# K9 Yard-level template: Configuration with validation +# Security Level: Yard (Nickel evaluation with contracts) +# Signature recommended but not required + +{ + pedigree = { + schema_version = "1.0.0", + component_type = "TODO: describe component type (e.g., 'validated-config', 'schema')", + security = { + leash = 'Yard, + trust_level = "validated-config", + allow_network = false, + allow_filesystem_write = false, + allow_subprocess = false, + }, + metadata = { + name = "TODO: component-name", + version = "1.0.0", + description = "TODO: Brief description with validation details", + author = "Jonathan D.A. Jewell ", + }, + }, + + # Configuration with Nickel contracts for validation + config = { + # Example: String that cannot be empty + name + | String + | std.string.NonEmpty + = "TODO: default value", + + # Example: Number with range constraint + port + | Number + | std.contract.from_predicate (fun p => p > 0 && p < 65536) + = 8080, + + # Example: Boolean flag + enabled | Bool = true, + + # Example: Enum (one of several values) + environment + | [| 'Development, 'Staging, 'Production |] + = 'Development, + + # Example: List with non-empty constraint + items + | Array String + | std.array.NonEmpty + = ["item1", "item2"], + + # Example: Nested object with contracts + database = { + host | String | std.string.NonEmpty = "localhost", + port | Number | std.contract.from_predicate (fun p => p > 0 && p < 65536) = 5432, + name | String | std.string.NonEmpty = "mydb", + }, + }, + + # Validation rules (additional cross-field checks) + validation = { + # Example: Check that at least one item exists + check_items = std.array.length config.items > 0, + + # Example: Check that production has secure settings + check_production = + if config.environment == 'Production then + config.enabled == true + else + true, + + # Add your custom validation rules here + }, +} + +# Usage: +# 1. Fill in TODO items above +# 2. Define your config with appropriate contracts +# 3. Add validation rules in validation = { ... } +# 4. Validate: nickel typecheck your-file.k9.ncl +# 5. Evaluate: nickel eval your-file.k9.ncl +# 6. If validation passes, use in your application diff --git a/.machine_readable/svc/README.adoc b/.machine_readable/svc/README.adoc index 48e9654..99e8d05 100644 --- a/.machine_readable/svc/README.adoc +++ b/.machine_readable/svc/README.adoc @@ -1,16 +1,10 @@ -= `.machine_readable/svc/` — Service components for januskey -:toc: +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell += `.machine_readable/svc/` — moved -Service-layer components that sit alongside the contractile trident -but are not themselves verbs. Per **ADR-001 (2026-04-18)**, K9 lives -here rather than under `contractiles/` so the contractile directory -stays a pure six-verb set (intend, trust, must, bust, adjust, dust). +The K9 self-validation components formerly under `svc/k9/` (ADR-001, +2026-04-18) now live at `.machine_readable/self-validating/` +(estate standardization, 2026-06). This directory is retained as a +pointer only. -== Contents - -* `k9/` — K9 self-validating templates and validators. - -== Pointer - -For the verb contractiles themselves, see -`.machine_readable/contractiles/`. +For the verb contractiles, see `.machine_readable/contractiles/`. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 66de7bd..60bcf5c 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,4 +1,7 @@ - + # JanusKey Architecture — Reversibility Stack Junction Point ## Lineage diff --git a/CHANGELOG.md b/CHANGELOG.md index 20eb800..edbc254 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,7 @@ - # Changelog All notable changes to `januskey` will be documented in this file. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 1f1548c..9020def 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,4 +1,7 @@ - + # Contributor Covenant Code of Conduct ## Our Pledge diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0640bb5..989a871 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,7 @@ + # Clone the repository git clone https://github.com/hyperpolymath/januskey.git cd januskey diff --git a/EXPLAINME.adoc b/EXPLAINME.adoc index eadd26e..a35cb2c 100644 --- a/EXPLAINME.adoc +++ b/EXPLAINME.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = JanusKey — Show Me The Receipts :toc: :icons: font diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..8bbf167 --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,162 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell += Governance Model +:toc: preamble + +This document describes the governance model for this repository. + +== Overview + +This repository follows a **Sole Maintainer Governance Model**: + +* 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 + +== Core Principles + +[cols="1,2"] +|=== +| Principle | Description + +| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input + +| **Meritocracy** | Contributions are judged on technical merit, not contributor identity + +| **Transparency** | All significant decisions are documented publicly + +| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary + +| **Open Contribution** | Anyone can contribute via fork and pull request + +|=== + +== Roles and Permissions + +[cols="1,2,2"] +|=== +| Role | Permissions | Assignment + +| **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 + +|=== + +== Decision Making Framework + +=== Routine Decisions + +* Bug fixes +* Documentation improvements +* Minor feature additions +* Dependency updates + +**Process**: Maintainer reviews and merges PRs that meet quality standards. + +=== 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 +|=== diff --git a/LICENSE b/LICENSE index 4a7f1aa..d0a1fa1 100644 --- a/LICENSE +++ b/LICENSE @@ -1,38 +1,3 @@ -SPDX-License-Identifier: MPL-2.0 -SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath) - ------------------------------------------------------------------------- -PREFERRED LICENCE: Palimpsest License (MPL-2.0) ------------------------------------------------------------------------- - -This work is governed by the Palimpsest License (MPL-2.0) as -its primary intended licence. MPL-2.0 extends the Mozilla -Public License 2.0 (MPL-2.0) with additional provisions for ethical use, -post-quantum cryptographic provenance, and emotional lineage protection. -The canonical PMPL text and stewardship information are maintained at: - https://github.com/hyperpolymath/palimpsest-license - ------------------------------------------------------------------------- -FALLBACK LICENCE: Mozilla Public License 2.0 (MPL-2.0) ------------------------------------------------------------------------- - -Because MPL-2.0 is not yet recognised by the Open Source -Initiative (OSI) or equivalent bodies, this work also carries MPL-2.0 -as its legally-recognised fallback licence. - -In any jurisdiction, platform, or context where MPL-2.0 is -not accepted as a valid licence, or where an OSI-approved licence is -required, this work is instead governed by the Mozilla Public License, -Version 2.0. - -MPL-2.0 was chosen as the fallback because MPL-2.0 is -explicitly based on and extends MPL-2.0; it is therefore the closest -recognised equivalent to the intended licence. - -The complete MPL-2.0 text follows below. - ------------------------------------------------------------------------- - Mozilla Public License Version 2.0 ================================== @@ -109,17 +74,17 @@ Mozilla Public License Version 2.0 means the form of the work preferred for making modifications. 1.14. "You" (or "Your") - means an individual or a legal entity exercising rights under - this License. For legal entities, "You" includes any entity that - controls, is controlled by, or is under common control with You. - For the purposes of this definition, "control" means (a) the power, - direct or indirect, to cause the direction or management of such - entity, whether by contract or otherwise, or (b) ownership of more - than fifty percent (50%) of the outstanding shares or beneficial + means an individual or a legal entity exercising rights under this + License. For legal entities, "You" includes any entity that + controls, is controlled by, or is under common control with You. For + purposes of this definition, "control" means (a) the power, direct + or indirect, to cause the direction or management of such entity, + whether by contract or otherwise, or (b) ownership of more than + fifty percent (50%) of the outstanding shares or beneficial ownership of such entity. 2. License Grants and Conditions ---------------------------------- +-------------------------------- 2.1. Grants @@ -144,11 +109,11 @@ distributes such Contribution. 2.3. Limitations on Grant Scope -The licenses granted in this Section 2 are the only rights granted -under this License. No additional rights or licenses will be implied -from the distribution or licensing of Covered Software under this -License. Notwithstanding Section 2.1(b) above, no patent license is -granted by a Contributor: +The licenses granted in this Section 2 are the only rights granted under +this License. No additional rights or licenses will be implied from the +distribution or licensing of Covered Software under this License. +Notwithstanding Section 2.1(b) above, no patent license is granted by a +Contributor: (a) for any code that a Contributor has removed from Covered Software; or @@ -158,19 +123,19 @@ granted by a Contributor: Contributions with other software (except as part of its Contributor Version); or -(c) under Patent Claims infringed by Covered Software in the absence - of its Contributions. +(c) under Patent Claims infringed by Covered Software in the absence of + its Contributions. -This License does not grant any rights in the trademarks, service -marks, or logos of any Contributor (except as may be necessary to -comply with the notice requirements in Section 3.4). +This License does not grant any rights in the trademarks, service marks, +or logos of any Contributor (except as may be necessary to comply with +the notice requirements in Section 3.4). 2.4. Subsequent Licenses No Contributor makes additional grants as a result of Your choice to distribute the Covered Software under a subsequent version of this -License (see Section 10.2) or under the terms of a Secondary License -(if permitted under the terms of Section 3.3). +License (see Section 10.2) or under the terms of a Secondary License (if +permitted under the terms of Section 3.3). 2.5. Representation @@ -186,11 +151,11 @@ equivalents. 2.7. Conditions -Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses -granted in Section 2.1. +Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted +in Section 2.1. 3. Responsibilities --------------------- +------------------- 3.1. Distribution of Source Form @@ -207,10 +172,10 @@ Form. If You distribute Covered Software in Executable Form then: (a) such Covered Software must also be made available in Source Code - Form, as described in Section 3.1, and You must inform recipients - of the Executable Form how they can obtain a copy of such Source - Code Form by reasonable means in a timely manner, at a charge no - more than the cost of distribution to the recipient; and + Form, as described in Section 3.1, and You must inform recipients of + the Executable Form how they can obtain a copy of such Source Code + Form by reasonable means in a timely manner, at a charge no more + than the cost of distribution to the recipient; and (b) You may distribute such Executable Form under the terms of this License, or sublicense it under different terms, provided that the @@ -222,8 +187,8 @@ If You distribute Covered Software in Executable Form then: You may create and distribute a Larger Work under terms of Your choice, provided that You also comply with the requirements of this License for the Covered Software. If the Larger Work is a combination of Covered -Software with a work governed by one or more Secondary Licenses, and -the Covered Software is not Incompatible With Secondary Licenses, this +Software with a work governed by one or more Secondary Licenses, and the +Covered Software is not Incompatible With Secondary Licenses, this License permits You to additionally distribute such Covered Software under the terms of such Secondary License(s), so that the recipient of the Larger Work may, at their option, further distribute the Covered @@ -241,28 +206,28 @@ the extent required to remedy known factual inaccuracies. 3.5. Application of Additional Terms You may choose to offer, and to charge a fee for, warranty, support, -indemnity or liability obligations to one or more recipients of -Covered Software. However, You may do so only on Your own behalf, and -not on behalf of any Contributor. You must make it absolutely clear -that any such warranty, support, indemnity, or liability obligation is -offered by You alone, and You hereby agree to indemnify every -Contributor for any liability incurred by such Contributor as a result -of warranty, support, indemnity or liability terms You offer. You may -include additional disclaimers of warranty and limitations of liability -specific to any jurisdiction. +indemnity or liability obligations to one or more recipients of Covered +Software. However, You may do so only on Your own behalf, and not on +behalf of any Contributor. You must make it absolutely clear that any +such warranty, support, indemnity, or liability obligation is offered by +You alone, and You hereby agree to indemnify every Contributor for any +liability incurred by such Contributor as a result of warranty, support, +indemnity or liability terms You offer. You may include additional +disclaimers of warranty and limitations of liability specific to any +jurisdiction. 4. Inability to Comply Due to Statute or Regulation ------------------------------------------------------ +--------------------------------------------------- If it is impossible for You to comply with any of the terms of this License with respect to some or all of the Covered Software due to statute, judicial order, or regulation then You must: (a) comply with the terms of this License to the maximum extent possible; and (b) -describe the limitations and the code they affect. Such description -must be placed in a text file included with all distributions of the -Covered Software under this License. Except to the extent prohibited -by statute or regulation, such description must be sufficiently -detailed for a recipient of ordinary skill to be able to understand it. +describe the limitations and the code they affect. Such description must +be placed in a text file included with all distributions of the Covered +Software under this License. Except to the extent prohibited by statute +or regulation, such description must be sufficiently detailed for a +recipient of ordinary skill to be able to understand it. 5. Termination -------------- @@ -271,27 +236,27 @@ detailed for a recipient of ordinary skill to be able to understand it. if You fail to comply with any of its terms. However, if You become compliant, then the rights granted under this License from a particular Contributor are reinstated (a) provisionally, unless and until such -Contributor explicitly and finally terminates Your grants, and (b) on -an ongoing basis, if such Contributor fails to notify You of the +Contributor explicitly and finally terminates Your grants, and (b) on an +ongoing basis, if such Contributor fails to notify You of the non-compliance by some reasonable means prior to 60 days after You have come back into compliance. Moreover, Your grants from a particular Contributor are reinstated on an ongoing basis if such Contributor -notifies You of the non-compliance by some reasonable means, this is -the first time You have received notice of non-compliance with this -License from such Contributor, and You become compliant prior to 30 -days after Your receipt of the notice. +notifies You of the non-compliance by some reasonable means, this is the +first time You have received notice of non-compliance with this License +from such Contributor, and You become compliant prior to 30 days after +Your receipt of the notice. -5.2. If You initiate litigation against any entity by asserting a -patent infringement claim (excluding declaratory judgment actions, +5.2. If You initiate litigation against any entity by asserting a patent +infringement claim (excluding declaratory judgment actions, counter-claims, and cross-claims) alleging that a Contributor Version directly or indirectly infringes any patent, then the rights granted to You by any and all Contributors for the Covered Software under Section 2.1 of this License shall terminate. 5.3. In the event of termination under Sections 5.1 or 5.2 above, all -end user license agreements (excluding distributors and resellers) -which have been validly granted by You or Your distributors under this -License prior to termination shall survive termination. +end user license agreements (excluding distributors and resellers) which +have been validly granted by You or Your distributors under this License +prior to termination shall survive termination. ************************************************************************ * * @@ -346,7 +311,7 @@ Nothing in this Section shall prevent a party's ability to bring cross-claims or counter-claims. 9. Miscellaneous ------------------ +---------------- This License represents the complete agreement concerning the subject matter hereof. If any provision of this License is held to be @@ -356,14 +321,14 @@ that the language of a contract shall be construed against the drafter shall not be used to construe this License against a Contributor. 10. Versions of the License ----------------------------- +--------------------------- 10.1. New Versions -Mozilla Foundation is the license steward. Except as provided in -Section 10.3, no one other than the license steward has the right to -modify or publish new versions of this License. Each version will be -given a distinguishing version number. +Mozilla Foundation is the license steward. Except as provided in Section +10.3, no one other than the license steward has the right to modify or +publish new versions of this License. Each version will be given a +distinguishing version number. 10.2. Effect of New Versions @@ -392,17 +357,17 @@ Exhibit A - Source Code Form License Notice This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this - file, You can obtain one at http://mozilla.org/MPL/2.0/. + file, You can obtain one at https://mozilla.org/MPL/2.0/. If it is not possible or desirable to put the notice in a particular file, then You may include the notice in a location (such as a LICENSE -file in a relevant directory) where a recipient would be likely to -look for such a notice. +file in a relevant directory) where a recipient would be likely to look +for such a notice. You may add additional accurate notices of copyright ownership. Exhibit B - "Incompatible With Secondary Licenses" Notice ----------------------------------------------------------- +--------------------------------------------------------- This Source Code Form is "Incompatible With Secondary Licenses", as defined by the Mozilla Public License, v. 2.0. diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc index a1c6544..becaa3e 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Maintainers :toc: preamble diff --git a/PALIMPSEST.adoc b/PALIMPSEST.adoc index ebaa6d0..9660f13 100644 --- a/PALIMPSEST.adoc +++ b/PALIMPSEST.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Palimpsest License :toc: :toc-placement!: diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md index 9483858..3a6891b 100644 --- a/PROOF-NEEDS.md +++ b/PROOF-NEEDS.md @@ -1,3 +1,7 @@ + # PROOF-NEEDS.md — januskey ## Current State diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc index b7d0e07..1eac376 100644 --- a/QUICKSTART-DEV.adoc +++ b/QUICKSTART-DEV.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // Template: QUICKSTART-DEV.adoc — clone → build → test → PR // Replace januskey, {{BUILD_CMD}}, {{TEST_CMD}}, {{LANG_STACK}} with actuals = januskey — Quick Start for Developers diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index 265b4ed..ef15f50 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // Template: QUICKSTART-MAINTAINER.adoc — packaging, deploying, and maintaining // Replace januskey, {{PACKAGE_NAME}}, {{DEPS}} with actuals = januskey — Quick Start for Platform Maintainers diff --git a/QUICKSTART-USER.adoc b/QUICKSTART-USER.adoc index 6e7582c..1107876 100644 --- a/QUICKSTART-USER.adoc +++ b/QUICKSTART-USER.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // Template: QUICKSTART-USER.adoc — 5-minute path to working software // Replace januskey, Januskey — See README.adoc for details., just run, Januskey started successfully. with actuals = januskey — Quick Start for Users diff --git a/READINESS.md b/READINESS.md index 77a4b0c..5f86e00 100644 --- a/READINESS.md +++ b/READINESS.md @@ -1,4 +1,7 @@ - + # Component Readiness Assessment — januskey **Assessed:** 2026-04-03 diff --git a/README.adoc b/README.adoc index e91a2de..56cb067 100644 --- a/README.adoc +++ b/README.adoc @@ -1,6 +1,10 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = JanusKey +image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=openssourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/januskey"] -image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] + +image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] @@ -22,13 +26,13 @@ toc::[] == Overview -JanusKey is a file operation utility suite that achieves complete reversibility through architectural design rather than logging or backups. Unlike traditional backup systems that restore from external state, JanusKey operations carry sufficient information for perfect inversion—making data loss architecturally impossible. +JanusKey is a file operation utility suite that pursues complete reversibility through architectural design rather than logging or backups. Unlike traditional backup systems that restore from external state, JanusKey operations carry sufficient information for inversion — the goal is to make data loss architecturally impossible (formal proofs pending). === Key Features -* *100% Reversible* - Every operation can be undone, always +* *Reversible by design* - Every operation carries inversion metadata (formal proofs pending) * *Instant Rollback* - Undo changes in milliseconds -* *Data Loss Impossible* - Not "unlikely"—architecturally impossible +* *Data loss impossible by construction* - the architectural goal the pending proofs are to establish * *Complete Audit Trail* - Every change tracked automatically * *Transaction Support* - Group operations, commit/rollback together * *Content-Addressed Storage* - SHA256 hashing with deduplication @@ -136,13 +140,13 @@ cargo install --path . == License -Licensed under MIT OR MPL-2.0. +This project is licensed under the Mozilla Public License, v. 2.0. See the `LICENSE` file for details. -See link:LICENSE.txt[LICENSE.txt] for details. +SPDX-License-Identifier: MPL-2.0 == Contributing -See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc]. +See link:CONTRIBUTING.md[CONTRIBUTING.md]. == Research diff --git a/ROADMAP.adoc b/ROADMAP.adoc index 91aeb33..4984742 100644 --- a/ROADMAP.adoc +++ b/ROADMAP.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Januskey Roadmap == Current Status diff --git a/SECURITY.md b/SECURITY.md index e52ff89..6019bc5 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,3 +1,7 @@ + # Security Policy ## Supported Versions diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md index cb4caf8..a628276 100644 --- a/TEST-NEEDS.md +++ b/TEST-NEEDS.md @@ -1,3 +1,7 @@ + # TEST-NEEDS.md — januskey ## CRG Grade: C — ACHIEVED 2026-04-04 diff --git a/TESTING-REPORT.adoc b/TESTING-REPORT.adoc index a529be3..b094401 100644 --- a/TESTING-REPORT.adoc +++ b/TESTING-REPORT.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell = JanusKey Testing Report diff --git a/TOPOLOGY.md b/TOPOLOGY.md index 90c2f1e..1adb827 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.md @@ -1,4 +1,7 @@ - + diff --git a/benches/januskey_benchmarks.rs b/benches/januskey_benchmarks.rs index 1ee9176..bee8f95 100644 --- a/benches/januskey_benchmarks.rs +++ b/benches/januskey_benchmarks.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // Criterion benchmarks for JanusKey operations // Measures: SHA256 hashing, content store, obliteration, transactions, key derivation diff --git a/contractiles/intend/Intentfile.a2ml b/contractiles/intend/Intentfile.a2ml deleted file mode 100644 index c2fd6bd..0000000 --- a/contractiles/intend/Intentfile.a2ml +++ /dev/null @@ -1,22 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Intentfile (A2ML Canonical) -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -@abstract: -Declared intent and purpose for Januskey. -@end - -## Purpose - -Januskey — Jonathan D.A. Jewell - -## Anti-Purpose - -This project is NOT: -- A fork or wrapper around another tool -- A monorepo (unless explicitly structured as one) - -## If In Doubt - -If you are unsure whether a change is in scope, ask. -Sensitive areas: ABI definitions, license headers, CI workflows. diff --git a/contractiles/must/Mustfile.a2ml b/contractiles/must/Mustfile.a2ml deleted file mode 100644 index 5022829..0000000 --- a/contractiles/must/Mustfile.a2ml +++ /dev/null @@ -1,42 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Mustfile (A2ML Canonical) -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -@abstract: -Physical State contract for Januskey. Baseline UX Manifesto invariants -that MUST hold at all times. -@end - -@requires: -- section: Core-Files -- section: Banned -@end - -## Core-Files - -### license-present -- description: LICENSE file must exist -- run: test -f LICENSE -- severity: critical - -### readme-present -- description: README must exist -- run: test -f README.adoc || test -f README.md -- severity: critical - -## Banned - -### no-hardcoded-paths -- description: No hardcoded developer paths -- run: "! grep -rn '/home/hyper\|/mnt/eclipse' --include='*.rs' --include='*.res' --include='*.ex' --include='*.gleam' --include='*.zig' --include='*.sh' . 2>/dev/null | grep -v '.git/' | grep -v 'ux-rollout.jl' | head -1" -- severity: critical - -### no-dockerfiles -- description: No Dockerfiles (use Containerfile) -- run: test ! -f Dockerfile -- severity: warning - -### no-makefiles -- description: No Makefiles (use Justfile) -- run: test ! -f Makefile -- severity: warning diff --git a/crates/januskey-cli/src/attestation.rs b/crates/januskey-cli/src/attestation.rs index 79b7d94..55f8a2b 100644 --- a/crates/januskey-cli/src/attestation.rs +++ b/crates/januskey-cli/src/attestation.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // JanusKey Attestation & Audit Log Module diff --git a/crates/januskey-cli/src/delta.rs b/crates/januskey-cli/src/delta.rs index 247ca4f..d1f6b13 100644 --- a/crates/januskey-cli/src/delta.rs +++ b/crates/januskey-cli/src/delta.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // Delta Storage: Efficient storage for file modifications diff --git a/crates/januskey-cli/src/keys.rs b/crates/januskey-cli/src/keys.rs index e895252..236a025 100644 --- a/crates/januskey-cli/src/keys.rs +++ b/crates/januskey-cli/src/keys.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // JanusKey Key Management Module diff --git a/crates/januskey-cli/src/keys_cli.rs b/crates/januskey-cli/src/keys_cli.rs index ba21b27..4bbf3c5 100644 --- a/crates/januskey-cli/src/keys_cli.rs +++ b/crates/januskey-cli/src/keys_cli.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // JanusKey Key Management CLI diff --git a/crates/januskey-cli/src/lib.rs b/crates/januskey-cli/src/lib.rs index 7a86ce3..2eaf363 100644 --- a/crates/januskey-cli/src/lib.rs +++ b/crates/januskey-cli/src/lib.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell // // JanusKey CLI: Provably Reversible File Operations diff --git a/crates/januskey-cli/src/main.rs b/crates/januskey-cli/src/main.rs index 1f22931..6c860d9 100644 --- a/crates/januskey-cli/src/main.rs +++ b/crates/januskey-cli/src/main.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // JanusKey CLI: Provably Reversible File Operations diff --git a/crates/januskey-cli/src/obliteration.rs b/crates/januskey-cli/src/obliteration.rs index 129c069..ee469b6 100644 --- a/crates/januskey-cli/src/obliteration.rs +++ b/crates/januskey-cli/src/obliteration.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // RMO: Obliterative Wipe Primitive diff --git a/crates/januskey-cli/src/operations.rs b/crates/januskey-cli/src/operations.rs index a5a4be5..ce8174e 100644 --- a/crates/januskey-cli/src/operations.rs +++ b/crates/januskey-cli/src/operations.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // Reversible File Operations diff --git a/crates/januskey-cli/tests/aspect_test.rs b/crates/januskey-cli/tests/aspect_test.rs index 3050d5d..bdc4890 100644 --- a/crates/januskey-cli/tests/aspect_test.rs +++ b/crates/januskey-cli/tests/aspect_test.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // Aspect tests: Security-critical obliteration verification // Tests: diff --git a/crates/januskey-cli/tests/concurrency_test.rs b/crates/januskey-cli/tests/concurrency_test.rs index ab1e745..10d8a4d 100644 --- a/crates/januskey-cli/tests/concurrency_test.rs +++ b/crates/januskey-cli/tests/concurrency_test.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // Concurrency tests: Verify thread-safety and transaction isolation // Tests: diff --git a/crates/januskey-cli/tests/e2e_test.rs b/crates/januskey-cli/tests/e2e_test.rs index 1a7e3e8..4de3071 100644 --- a/crates/januskey-cli/tests/e2e_test.rs +++ b/crates/januskey-cli/tests/e2e_test.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // E2E tests: Full key lifecycle and content store operations // Tests: key gen → store → attest → retrieve → obliterate diff --git a/crates/januskey-cli/tests/p2p_test.rs b/crates/januskey-cli/tests/p2p_test.rs index cf0cda8..d7381f7 100644 --- a/crates/januskey-cli/tests/p2p_test.rs +++ b/crates/januskey-cli/tests/p2p_test.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // Point-to-point integration tests: verify component interactions // Tests: content_store<->metadata, keys<->attestation, transaction<->operations diff --git a/crates/januskey-cli/tests/property_tests.rs b/crates/januskey-cli/tests/property_tests.rs index 5760007..424605b 100644 --- a/crates/januskey-cli/tests/property_tests.rs +++ b/crates/januskey-cli/tests/property_tests.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // Property-based tests for januskey-cli. // Tests obliteration and key derivation invariants. diff --git a/crates/reversible-core/src/content_store.rs b/crates/reversible-core/src/content_store.rs index 8543d16..b2ce8d1 100644 --- a/crates/reversible-core/src/content_store.rs +++ b/crates/reversible-core/src/content_store.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell // // Content-Addressed Storage with SHA256 hashing diff --git a/crates/reversible-core/src/error.rs b/crates/reversible-core/src/error.rs index a70f19c..d4f842e 100644 --- a/crates/reversible-core/src/error.rs +++ b/crates/reversible-core/src/error.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell // // Error types for reversible-core diff --git a/crates/reversible-core/src/lib.rs b/crates/reversible-core/src/lib.rs index ce9552f..d3b9c74 100644 --- a/crates/reversible-core/src/lib.rs +++ b/crates/reversible-core/src/lib.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell // // reversible-core: Shared types for provably reversible operations diff --git a/crates/reversible-core/src/manifest.rs b/crates/reversible-core/src/manifest.rs index a8bead5..9ddcaed 100644 --- a/crates/reversible-core/src/manifest.rs +++ b/crates/reversible-core/src/manifest.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell // // A2ML Manifest Emitter diff --git a/crates/reversible-core/src/metadata.rs b/crates/reversible-core/src/metadata.rs index 462274a..1c5b008 100644 --- a/crates/reversible-core/src/metadata.rs +++ b/crates/reversible-core/src/metadata.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell // // Metadata Store: Operation log with complete reverse information diff --git a/crates/reversible-core/src/transaction.rs b/crates/reversible-core/src/transaction.rs index f52e602..a21d473 100644 --- a/crates/reversible-core/src/transaction.rs +++ b/crates/reversible-core/src/transaction.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell // // Transaction types: Group operations with commit/rollback support diff --git a/crates/reversible-core/tests/property_tests.rs b/crates/reversible-core/tests/property_tests.rs index b4fbd7c..38a7107 100644 --- a/crates/reversible-core/tests/property_tests.rs +++ b/crates/reversible-core/tests/property_tests.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // Property-based tests for reversible-core. // Uses proptest to generate arbitrary inputs and verify invariants. diff --git a/crates/reversible-core/tests/unwrap_safety_test.rs b/crates/reversible-core/tests/unwrap_safety_test.rs index bd2248f..b97d35b 100644 --- a/crates/reversible-core/tests/unwrap_safety_test.rs +++ b/crates/reversible-core/tests/unwrap_safety_test.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // Regression tests: verify that known-bad inputs do not panic. // Each test here corresponds to a discovered issue. diff --git a/docs/CITATIONS.adoc b/docs/CITATIONS.adoc index 89abe97..c27d307 100644 --- a/docs/CITATIONS.adoc +++ b/docs/CITATIONS.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = januskey - Citation Guide :toc: diff --git a/docs/reports/audit/audit-2026-04-04.md b/docs/reports/audit/audit-2026-04-04.md index 8cd04dd..a4fe0c7 100644 --- a/docs/reports/audit/audit-2026-04-04.md +++ b/docs/reports/audit/audit-2026-04-04.md @@ -1,3 +1,7 @@ + # Audit Report — januskey (2026-04-04) ## Summary diff --git a/docs/security/KEY_LIFECYCLE.adoc b/docs/security/KEY_LIFECYCLE.adoc index 4f8dded..3f29aba 100644 --- a/docs/security/KEY_LIFECYCLE.adoc +++ b/docs/security/KEY_LIFECYCLE.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2024-2025 Jonathan D.A. Jewell = JanusKey Key Lifecycle Management :toc: left diff --git a/docs/security/THREAT_MODEL.adoc b/docs/security/THREAT_MODEL.adoc index 1b6a189..c0f7311 100644 --- a/docs/security/THREAT_MODEL.adoc +++ b/docs/security/THREAT_MODEL.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2024-2025 Jonathan D.A. Jewell = JanusKey Key Management Threat Model :toc: left diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md index 8aa0463..f698d48 100644 --- a/docs/tech-debt-2026-05-26.md +++ b/docs/tech-debt-2026-05-26.md @@ -1,8 +1,7 @@ - # Tech-Debt Audit — januskey — 2026-05-26 **Source:** estate-wide automated scan 2026-05-26. diff --git a/docs/wiki/Home.adoc b/docs/wiki/Home.adoc index 27eacdc..1308ba3 100644 --- a/docs/wiki/Home.adoc +++ b/docs/wiki/Home.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = JanusKey Wiki Jonathan D.A. Jewell :toc: left @@ -8,7 +10,20 @@ Jonathan D.A. Jewell == Welcome to JanusKey -JanusKey is a provably reversible file operations utility that achieves complete reversibility through architectural design rather than logging or backups. Unlike traditional backup systems that restore from external state, JanusKey operations carry sufficient information for perfect inversion—making data loss architecturally impossible. +JanusKey is a reversible file operations utility (formal proofs pending) that pursues complete reversibility through architectural design rather than logging or backups. Unlike traditional backup systems that restore from external state, JanusKey operations carry sufficient information for inversion — the goal is to make data loss architecturally impossible. 30 Idris2 ABI proofs are landed; the reversibility theorems themselves are a target, not yet complete. + +=== Project Status (2026-06-12) + +Landed since 2026-04: estate standardization merged (flat contractiles, +`bot_directives/`, `6a2/anchor/`, `self-validating/`, GOVERNANCE + +MAINTAINERS + CODEOWNERS); license migrated PMPL-1.0-or-later → MPL-2.0 +(Cargo.toml aligned in #52); CI converted to SHA-pinned reusable-workflow +wrappers (rust-ci #39, hypatia-scan #40/#46, mirror #42, secret-scanner #43, +scorecard #44/#48) with cargo-audit + workflow-linter prevention workflows; +CodeQL cron now monthly; CHANGELOG.md seeded (#45); MCP-exposure threat +model drafted (status: draft-pending-human-review); Trustfile hardened to +the crypto-minimal baseline; 166 `.expect("TODO: handle error")` sites +cleared. CRG grade remains D (promotion path in READINESS.md). === Core Philosophy @@ -25,7 +40,7 @@ JanusKey implements *Maximal Principle Reduction (MPR)*, a security methodology | Structural reversibility guarantee | Trust in operational processes -| Formal mathematical proofs +| Formal mathematical proofs (in progress — Idris2 ABI proofs landed, reversibility theorems pending) | Recovery from external state | Recovery from operation metadata @@ -62,11 +77,11 @@ JanusKey implements *Maximal Principle Reduction (MPR)*, a security methodology | Practical usage examples and patterns |=== -=== Key Guarantees +=== Key Guarantees (design targets — formal proofs pending) -1. **100% Reversibility**: Every operation can be undone, always +1. **Reversibility by design**: Every operation carries inversion metadata (formal proof of "always" is pending) 2. **Instant Rollback**: Undo changes in milliseconds, not hours -3. **Data Loss Impossible**: Not "unlikely"—architecturally impossible +3. **Data loss impossible by construction**: the architectural goal the pending proofs are to establish 4. **Complete Audit Trail**: Every change tracked automatically 5. **Transaction Support**: Group operations, commit/rollback together 6. **Content-Addressed Storage**: SHA256 hashing with deduplication diff --git a/docs/wiki/api/index.adoc b/docs/wiki/api/index.adoc index 4ad2766..5e28b2f 100644 --- a/docs/wiki/api/index.adoc +++ b/docs/wiki/api/index.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = API Reference :toc: left :toclevels: 3 diff --git a/docs/wiki/architecture/index.adoc b/docs/wiki/architecture/index.adoc index dc5d9d2..c2a6dd8 100644 --- a/docs/wiki/architecture/index.adoc +++ b/docs/wiki/architecture/index.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Architecture Overview :toc: left :toclevels: 3 diff --git a/docs/wiki/examples/index.adoc b/docs/wiki/examples/index.adoc index d7efe39..28bf453 100644 --- a/docs/wiki/examples/index.adoc +++ b/docs/wiki/examples/index.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Examples and Use Cases :toc: left :toclevels: 3 diff --git a/docs/wiki/formal-proofs/index.adoc b/docs/wiki/formal-proofs/index.adoc index e04a263..f73193a 100644 --- a/docs/wiki/formal-proofs/index.adoc +++ b/docs/wiki/formal-proofs/index.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Formal Proofs :toc: left :toclevels: 3 diff --git a/docs/wiki/guides/cli.adoc b/docs/wiki/guides/cli.adoc index ccebc93..35c4881 100644 --- a/docs/wiki/guides/cli.adoc +++ b/docs/wiki/guides/cli.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = CLI Commands Guide :toc: left :toclevels: 3 diff --git a/docs/wiki/guides/transactions.adoc b/docs/wiki/guides/transactions.adoc index 1042703..f4441bb 100644 --- a/docs/wiki/guides/transactions.adoc +++ b/docs/wiki/guides/transactions.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Transaction Guide :toc: left :toclevels: 3 diff --git a/docs/wiki/operations/index.adoc b/docs/wiki/operations/index.adoc index 01cf509..8436e06 100644 --- a/docs/wiki/operations/index.adoc +++ b/docs/wiki/operations/index.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Operations Reference :toc: left :toclevels: 3 diff --git a/docs/wiki/theory/formal-model.adoc b/docs/wiki/theory/formal-model.adoc index 1b2b6ee..76ccc61 100644 --- a/docs/wiki/theory/formal-model.adoc +++ b/docs/wiki/theory/formal-model.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Formal Model of File System State :toc: left :toclevels: 3 diff --git a/docs/wiki/theory/index.adoc b/docs/wiki/theory/index.adoc index 0c8d877..bc57ee0 100644 --- a/docs/wiki/theory/index.adoc +++ b/docs/wiki/theory/index.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Theoretical Foundations :toc: left :toclevels: 3 diff --git a/docs/wiki/theory/maa-framework.adoc b/docs/wiki/theory/maa-framework.adoc index 961400d..1d2fba4 100644 --- a/docs/wiki/theory/maa-framework.adoc +++ b/docs/wiki/theory/maa-framework.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Mutually Assured Accountability (MAA) Framework :toc: left :toclevels: 3 diff --git a/docs/wiki/theory/mpr.adoc b/docs/wiki/theory/mpr.adoc index 99b3978..0866057 100644 --- a/docs/wiki/theory/mpr.adoc +++ b/docs/wiki/theory/mpr.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = Maximal Principle Reduction (MPR) :toc: left :toclevels: 3 diff --git a/docs/wiki/theory/rmo-primitive.adoc b/docs/wiki/theory/rmo-primitive.adoc index 4ec3edd..8368fda 100644 --- a/docs/wiki/theory/rmo-primitive.adoc +++ b/docs/wiki/theory/rmo-primitive.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = RMO: Obliterative Wipe Primitive :toc: left :toclevels: 3 diff --git a/docs/wiki/theory/rmr-primitive.adoc b/docs/wiki/theory/rmr-primitive.adoc index 42d20c1..9e03899 100644 --- a/docs/wiki/theory/rmr-primitive.adoc +++ b/docs/wiki/theory/rmr-primitive.adoc @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell = RMR: Reversible Transaction Primitive :toc: left :toclevels: 3 diff --git a/ffi/zig/build.zig b/ffi/zig/build.zig index 1aec278..77a557d 100644 --- a/ffi/zig/build.zig +++ b/ffi/zig/build.zig @@ -1,6 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - +// Copyright (c) Jonathan D.A. Jewell const std = @import("std"); pub fn build(b: *std.Build) void { @@ -14,6 +13,9 @@ pub fn build(b: *std.Build) void { .target = target, .optimize = optimize, }); + // main.zig uses std.heap.c_allocator, which requires libc; the library + // is consumed from C anyway. + lib.linkLibC(); b.installArtifact(lib); // Install C header @@ -25,6 +27,12 @@ pub fn build(b: *std.Build) void { .target = target, .optimize = optimize, }); + tests.linkLibC(); + // Expose src/main.zig to the tests as @import("januskey") — relative + // imports outside test/ are rejected by the module system. + tests.root_module.addAnonymousImport("januskey", .{ + .root_source_file = b.path("src/main.zig"), + }); const run_tests = b.addRunArtifact(tests); const test_step = b.step("test", "Run integration tests"); test_step.dependOn(&run_tests.step); diff --git a/ffi/zig/include/januskey.h b/ffi/zig/include/januskey.h index 27b9bfc..3690a76 100644 --- a/ffi/zig/include/januskey.h +++ b/ffi/zig/include/januskey.h @@ -1,3 +1,5 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell /* SPDX-License-Identifier: MPL-2.0 */ /* Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) */ /* JanusKey C FFI Header — generated from src/abi/Foreign.idr */ diff --git a/ffi/zig/src/main.zig b/ffi/zig/src/main.zig index 625acd3..cf09ff0 100644 --- a/ffi/zig/src/main.zig +++ b/ffi/zig/src/main.zig @@ -1,9 +1,10 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // JANUSKEY FFI Implementation // // This module implements the C-compatible FFI declared in src/abi/Foreign.idr // All types and layouts must match the Idris2 ABI definitions. // -// SPDX-License-Identifier: MPL-2.0 const std = @import("std"); @@ -37,8 +38,10 @@ pub const Result = enum(c_int) { null_pointer = 4, }; -/// Library handle (opaque to prevent direct access) -pub const Handle = opaque { +/// Library handle. Opaque on the C side (the header only forward-declares +/// it); on the Zig side it must be a sized struct — `opaque` types cannot +/// have fields, and `allocator.create(Handle)` below needs a known size. +pub const Handle = struct { // Internal state hidden from C allocator: std.mem.Allocator, initialized: bool, diff --git a/ffi/zig/test/integration_test.zig b/ffi/zig/test/integration_test.zig index d22fa23..cd2fa99 100644 --- a/ffi/zig/test/integration_test.zig +++ b/ffi/zig/test/integration_test.zig @@ -1,11 +1,13 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // Integration tests for JanusKey Zig FFI // Tests: init/close, execute/undo, transactions, obliteration, error codes const std = @import("std"); -const jk = @import("../src/main.zig"); +// Provided as a named module by build.zig (addAnonymousImport) — a relative +// "../src/main.zig" import is outside the test module's path in Zig 0.13. +const jk = @import("januskey"); // ============================================================ // Layout verification (compile-time, matches Layout.idr) diff --git a/flake.nix b/flake.nix deleted file mode 100644 index 73bd2b2..0000000 --- a/flake.nix +++ /dev/null @@ -1,116 +0,0 @@ -{ - description = "januskey - {project-description}"; - - # *REMINDER: Update inputs with actual dependencies* - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; - flake-utils.url = "github:numtide/flake-utils"; - # Add language-specific inputs: - # rust-overlay.url = "github:oxalica/rust-overlay"; # For Rust - # fenix.url = "github:nix-community/fenix"; # Alternative Rust - }; - - outputs = { self, nixpkgs, flake-utils, ... }@inputs: - flake-utils.lib.eachDefaultSystem (system: - let - pkgs = import nixpkgs { - inherit system; - # overlays = [ (import inputs.rust-overlay) ]; # For Rust - }; - - # *REMINDER: Define build dependencies* - buildInputs = with pkgs; [ - # Language-specific dependencies: - # gnat13 # Ada - # cargo rustc # Rust - # elixir # Elixir - # For build tools: - just - podman - git - ]; - - # *REMINDER: Define development dependencies* - nativeBuildInputs = with pkgs; [ - # Development tools: - ripgrep # Code search - lychee # Link validation - # Language-specific: - # rustfmt clippy # Rust - # mix # Elixir - ]; - - in - { - # Development shell - devShells.default = pkgs.mkShell { - inherit buildInputs nativeBuildInputs; - - shellHook = '' - echo "🚀 januskey development environment" - echo "Language: rust" - echo "" - echo "Available commands:" - echo " just --list # Show all tasks" - echo " just setup # Set up environment" - echo " just build # Build project" - echo " just test # Run tests" - echo " just validate # RSR compliance" - echo "" - # *REMINDER: Add language-specific environment setup* - # export CARGO_HOME=$PWD/.cargo # Rust - # export MIX_HOME=$PWD/.mix # Elixir - ''; - }; - - # Packages - packages.default = pkgs.stdenv.mkDerivation { - pname = "januskey"; - version = "0.1.0"; - src = ./.; - - inherit buildInputs nativeBuildInputs; - - buildPhase = '' - # *REMINDER: Add build commands* - # For Rust: cargo build --release - # For Elixir: mix compile - # For Ada: gprbuild -P januskey.gpr -XMODE=release - ''; - - installPhase = '' - mkdir -p $out/bin - # *REMINDER: Add install commands* - # cp target/release/januskey $out/bin/ # Rust - # cp bin/januskey $out/bin/ # Ada - ''; - - meta = with pkgs.lib; { - description = "{project-description}"; - homepage = "{repo-url}"; - license = with licenses; [ mit ]; # MIT + Palimpsest - maintainers = [ "{maintainer-name}" ]; - platforms = platforms.unix; - }; - }; - - # Apps - apps.default = { - type = "app"; - program = "${self.packages.${system}.default}/bin/januskey"; - }; - - # Checks (CI/CD integration) - checks = { - build = self.packages.${system}.default; - # *REMINDER: Add test checks* - test = pkgs.runCommand "test-januskey" { - buildInputs = [ self.packages.${system}.default ]; - } '' - # Run tests here - touch $out - ''; - }; - } - ); -} diff --git a/generated/idrisiser/idris2/Januskey/Verified/key_derivation.idr b/generated/idrisiser/idris2/Januskey/Verified/key_derivation.idr index 6a69651..c18fa1e 100644 --- a/generated/idrisiser/idris2/Januskey/Verified/key_derivation.idr +++ b/generated/idrisiser/idris2/Januskey/Verified/key_derivation.idr @@ -1,4 +1,5 @@ -- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) Jonathan D.A. Jewell -- Auto-generated by idrisiser — do not edit manually. -- Interface: key-derivation (type-sig) -- Source: idrisiser/key-derivation.tsig diff --git a/generated/idrisiser/idris2/Januskey/Verified/key_generation.idr b/generated/idrisiser/idris2/Januskey/Verified/key_generation.idr index 1d0f137..a44f219 100644 --- a/generated/idrisiser/idris2/Januskey/Verified/key_generation.idr +++ b/generated/idrisiser/idris2/Januskey/Verified/key_generation.idr @@ -1,4 +1,5 @@ -- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) Jonathan D.A. Jewell -- Auto-generated by idrisiser — do not edit manually. -- Interface: key-generation (type-sig) -- Source: idrisiser/key-generation.tsig diff --git a/generated/idrisiser/idris2/Januskey/Verified/wrap_unwrap_round_trip.idr b/generated/idrisiser/idris2/Januskey/Verified/wrap_unwrap_round_trip.idr index 574cda5..c8d2cc4 100644 --- a/generated/idrisiser/idris2/Januskey/Verified/wrap_unwrap_round_trip.idr +++ b/generated/idrisiser/idris2/Januskey/Verified/wrap_unwrap_round_trip.idr @@ -1,4 +1,5 @@ -- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) Jonathan D.A. Jewell -- Auto-generated by idrisiser — do not edit manually. -- Interface: wrap-unwrap-round-trip (type-sig) -- Source: idrisiser/wrap-unwrap.tsig diff --git a/generated/idrisiser/zig/januskey_ffi.zig b/generated/idrisiser/zig/januskey_ffi.zig index c5f0675..cef0b13 100644 --- a/generated/idrisiser/zig/januskey_ffi.zig +++ b/generated/idrisiser/zig/januskey_ffi.zig @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // Auto-generated by idrisiser — do not edit manually. // Zig FFI bridge for project: januskey // Regenerate with: idrisiser generate diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md index 4370cfd..d856078 100644 --- a/llm-warmup-dev.md +++ b/llm-warmup-dev.md @@ -1,3 +1,7 @@ + # LLM Warmup — januskey (Developer) ## What is januskey? diff --git a/llm-warmup-user.md b/llm-warmup-user.md index a472ddf..aca04aa 100644 --- a/llm-warmup-user.md +++ b/llm-warmup-user.md @@ -1,3 +1,7 @@ + # LLM Warmup — januskey (User) ## What is januskey? diff --git a/src/abi/Foreign.idr b/src/abi/Foreign.idr index 97876d7..1520f8d 100644 --- a/src/abi/Foreign.idr +++ b/src/abi/Foreign.idr @@ -1,3 +1,5 @@ +-- SPDX-License-Identifier: MPL-2.0 +-- Copyright (c) Jonathan D.A. Jewell ||| SPDX-License-Identifier: MPL-2.0 ||| Foreign Function Interface Declarations for JANUSKEY ||| diff --git a/src/abi/Layout.idr b/src/abi/Layout.idr index 0c677cd..5a69502 100644 --- a/src/abi/Layout.idr +++ b/src/abi/Layout.idr @@ -1,5 +1,5 @@ -- SPDX-License-Identifier: MPL-2.0 --- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- Copyright (c) Jonathan D.A. Jewell -- -- JanusKey ABI Layout — Memory layout proofs and C-compatible structures -- Proves that Rust and Zig FFI representations are bit-compatible diff --git a/src/abi/Proofs.idr b/src/abi/Proofs.idr index f6bc290..d58caaf 100644 --- a/src/abi/Proofs.idr +++ b/src/abi/Proofs.idr @@ -1,5 +1,5 @@ -- SPDX-License-Identifier: MPL-2.0 --- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- Copyright (c) Jonathan D.A. Jewell -- -- JanusKey ABI Proofs — Standalone formal verification module -- Proves correctness properties for all JanusKey operations diff --git a/src/abi/Types.idr b/src/abi/Types.idr index f51f63e..d734694 100644 --- a/src/abi/Types.idr +++ b/src/abi/Types.idr @@ -1,5 +1,5 @@ -- SPDX-License-Identifier: MPL-2.0 --- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +-- Copyright (c) Jonathan D.A. Jewell -- -- JanusKey ABI Types — Idris2 formal definitions -- Implements TypeLL Levels 1-12 for provably reversible operations diff --git a/src/januskey/src/attestation.rs b/src/januskey/src/attestation.rs index 4eac1d0..7cbda3b 100644 --- a/src/januskey/src/attestation.rs +++ b/src/januskey/src/attestation.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // JanusKey Attestation & Audit Log Module diff --git a/src/januskey/src/content_store.rs b/src/januskey/src/content_store.rs index b58099c..9214023 100644 --- a/src/januskey/src/content_store.rs +++ b/src/januskey/src/content_store.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // Content-Addressed Storage with SHA256 hashing diff --git a/src/januskey/src/delta.rs b/src/januskey/src/delta.rs index 247ca4f..d1f6b13 100644 --- a/src/januskey/src/delta.rs +++ b/src/januskey/src/delta.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // Delta Storage: Efficient storage for file modifications diff --git a/src/januskey/src/error.rs b/src/januskey/src/error.rs index fc15a96..8e42e4a 100644 --- a/src/januskey/src/error.rs +++ b/src/januskey/src/error.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // JanusKey Error Types diff --git a/src/januskey/src/keys.rs b/src/januskey/src/keys.rs index c5ca03b..561bc6e 100644 --- a/src/januskey/src/keys.rs +++ b/src/januskey/src/keys.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // JanusKey Key Management Module diff --git a/src/januskey/src/keys_cli.rs b/src/januskey/src/keys_cli.rs index ba21b27..4bbf3c5 100644 --- a/src/januskey/src/keys_cli.rs +++ b/src/januskey/src/keys_cli.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // JanusKey Key Management CLI diff --git a/src/januskey/src/lib.rs b/src/januskey/src/lib.rs index baedb0b..adb19ca 100644 --- a/src/januskey/src/lib.rs +++ b/src/januskey/src/lib.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // JanusKey: Reversible File Operations (formal proofs pending) diff --git a/src/januskey/src/main.rs b/src/januskey/src/main.rs index 990cdd8..88f37ad 100644 --- a/src/januskey/src/main.rs +++ b/src/januskey/src/main.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // JanusKey CLI: Reversible File Operations (formal proofs pending) diff --git a/src/januskey/src/metadata.rs b/src/januskey/src/metadata.rs index 6665e37..fead27a 100644 --- a/src/januskey/src/metadata.rs +++ b/src/januskey/src/metadata.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // Metadata Store: Operation log with complete reverse information diff --git a/src/januskey/src/obliteration.rs b/src/januskey/src/obliteration.rs index efe95b7..dedb700 100644 --- a/src/januskey/src/obliteration.rs +++ b/src/januskey/src/obliteration.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // RMO: Obliterative Wipe Primitive diff --git a/src/januskey/src/operations.rs b/src/januskey/src/operations.rs index a5a4be5..ce8174e 100644 --- a/src/januskey/src/operations.rs +++ b/src/januskey/src/operations.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // Reversible File Operations diff --git a/src/januskey/src/transaction.rs b/src/januskey/src/transaction.rs index 10abf63..eddb86d 100644 --- a/src/januskey/src/transaction.rs +++ b/src/januskey/src/transaction.rs @@ -1,4 +1,5 @@ -// SPDX-License-Identifier: MIT OR MPL-2.0 +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell // // Transaction Manager: Group operations with commit/rollback support diff --git a/tests/aspect/cross_cutting_test.sh b/tests/aspect/cross_cutting_test.sh index 3ab8326..28f943c 100755 --- a/tests/aspect/cross_cutting_test.sh +++ b/tests/aspect/cross_cutting_test.sh @@ -12,7 +12,10 @@ JK_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)" PASS=0 FAIL=0 -check() { if eval "$2"; then echo "[PASS] $1"; ((PASS++)); else echo "[FAIL] $1"; ((FAIL++)); fi; } +# NB: use POSIX arithmetic assignment, not ((PASS++)) — under `set -e` a +# post-increment whose old value is 0 returns exit status 1 and kills the +# script after the very first check. +check() { if eval "$2"; then echo "[PASS] $1"; PASS=$((PASS+1)); else echo "[FAIL] $1"; FAIL=$((FAIL+1)); fi; } echo "=== JanusKey Aspect Tests ===" @@ -32,11 +35,16 @@ check "Zig SPDX headers (${zig_spdx}/${zig_total})" "[ '${zig_spdx}' -eq '${zig_ # --- Forbidden Patterns --- echo "--- Forbidden Patterns ---" -check "No believe_me in proofs" "! grep -rq 'believe_me' '${JK_DIR}/src/abi/' 2>/dev/null" -check "No assert_total in proofs" "! grep -rq 'assert_total' '${JK_DIR}/src/abi/' 2>/dev/null" +# NB: strip Idris '--' comment lines before matching, otherwise the header +# comment in Proofs.idr ("No believe_me, no assert_total ... fully total") +# matches the very greps that assert their absence. +check "No believe_me in proofs" "! grep -rh 'believe_me' '${JK_DIR}/src/abi/' 2>/dev/null | grep -v '^\s*--' | grep -q ." +check "No assert_total in proofs" "! grep -rh 'assert_total' '${JK_DIR}/src/abi/' 2>/dev/null | grep -v '^\s*--' | grep -q ." check "No postulate in proofs" "! grep -rq '^postulate' '${JK_DIR}/src/abi/' 2>/dev/null" -check "No sorry in proofs" "! grep -rq 'sorry' '${JK_DIR}/src/abi/' 2>/dev/null" -check "No unsafe in reversible-core" "! grep -rq 'unsafe' '${JK_DIR}/crates/reversible-core/src/' 2>/dev/null" +check "No sorry in proofs" "! grep -rh 'sorry' '${JK_DIR}/src/abi/' 2>/dev/null | grep -v '^\s*--' | grep -q ." +# NB: exclude the '#![forbid(unsafe_code)]' attribute (which BANS unsafe) +# and '//' comment lines from the unsafe check. +check "No unsafe in reversible-core" "! grep -rh 'unsafe' '${JK_DIR}/crates/reversible-core/src/' 2>/dev/null | grep -v 'forbid(unsafe_code)' | grep -v '^\s*//' | grep -q ." # --- Documentation --- echo "--- Documentation ---" diff --git a/tests/fuzz/README.adoc b/tests/fuzz/README.adoc index e708385..9891da3 100644 --- a/tests/fuzz/README.adoc +++ b/tests/fuzz/README.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell = Fuzz Testing diff --git a/tests/p2p/component_p2p_test.rs b/tests/p2p/component_p2p_test.rs index 2aefb5d..2f681cd 100644 --- a/tests/p2p/component_p2p_test.rs +++ b/tests/p2p/component_p2p_test.rs @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// Copyright (c) Jonathan D.A. Jewell // // Point-to-point tests: verify component interactions // Tests: content_store↔metadata, keys↔attestation, transaction↔operations diff --git a/tests/regressions/README.adoc b/tests/regressions/README.adoc index 87491ae..161010d 100644 --- a/tests/regressions/README.adoc +++ b/tests/regressions/README.adoc @@ -1,4 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell // SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell = Regression Tests