diff --git a/.claude/PROJECT.adoc b/.claude/PROJECT.adoc new file mode 100644 index 0000000..4ad036d --- /dev/null +++ b/.claude/PROJECT.adoc @@ -0,0 +1,33 @@ +== Ochrance - Claude Code Instructions + +This repository contains the Ochrance project. + +=== Project Structure + +.... +ochrance/ +├── .claude/ # AI assistant instructions +├── .git/ # Version control +├── .gitignore # Git ignore rules +├── .editorconfig # Editor configuration +└── ... # Project files +.... + +=== Build Commands + +Refer to project-specific documentation. + +=== Coding Conventions + +* Follow hyperpolymath standards +* All code must have SPDX license headers +* Use approved languages only (see CLAUDE.md) +* Document all non-obvious decisions + +=== Security + +* No hardcoded secrets +* All secrets through environment variables or secret management +* SHA-pinned dependencies where applicable +* HTTPS only, no HTTP URLs +* No MD5/SHA1 for security purposes diff --git a/.claude/PROJECT.md b/.claude/PROJECT.md deleted file mode 100644 index 0af3f04..0000000 --- a/.claude/PROJECT.md +++ /dev/null @@ -1,37 +0,0 @@ - -# Ochrance - Claude Code Instructions - -This repository contains the Ochrance project. - -## Project Structure - -``` -ochrance/ -├── .claude/ # AI assistant instructions -├── .git/ # Version control -├── .gitignore # Git ignore rules -├── .editorconfig # Editor configuration -└── ... # Project files -``` - -## Build Commands - -Refer to project-specific documentation. - -## Coding Conventions - -- Follow hyperpolymath standards -- All code must have SPDX license headers -- Use approved languages only (see CLAUDE.md) -- Document all non-obvious decisions - -## Security - -- No hardcoded secrets -- All secrets through environment variables or secret management -- SHA-pinned dependencies where applicable -- HTTPS only, no HTTP URLs -- No MD5/SHA1 for security purposes diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 57% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index cffea82..dbfdf90 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,25 +1,21 @@ - -# Ochrance ABI/FFI Documentation +== Ochrance ABI/FFI Documentation -## Overview +=== Overview -**Ochrance** is a neurosymbolic filesystem verification framework. Its -cryptographic core follows the **Hyperpolymath RSR Standard** for ABI and FFI -design: +*Ochrance* is a neurosymbolic filesystem verification framework. Its +cryptographic core follows the *Hyperpolymath RSR Standard* for ABI and +FFI design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal - proofs — `src/abi/Ochrance/ABI/` -- **FFI (Foreign Function Interface)** implemented in **Zig** for C - compatibility — `ffi/zig/src/main.zig` -- **Idris2 FFI declarations** in the core library bridge into the Zig - shared object — `ochrance-core/Ochrance/FFI/Crypto.idr` +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs — `+src/abi/Ochrance/ABI/+` +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility — `+ffi/zig/src/main.zig+` +* *Idris2 FFI declarations* in the core library bridge into the Zig +shared object — `+ochrance-core/Ochrance/FFI/Crypto.idr+` -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/Ochrance/ABI/ │ @@ -60,62 +56,75 @@ design: │ - A2ML manifest attestation │ │ - ECHIDNA neural proof synthesis (future) │ └─────────────────────────────────────────────────┘ -``` +.... -## ABI Definitions (Idris2) +=== ABI Definitions (Idris2) -### Types.idr — Core ABI Types +==== Types.idr — Core ABI Types -| Type | Description | -|------|-------------| -| `Platform` | Compile-time target: Linux, Windows, MacOS, BSD, WASM | -| `Result` | Security check outcome: Ok, Error, InvalidParam, OutOfMemory, NullPointer | -| `Handle` | Opaque non-null pointer with type-level `So (ptr /= 0)` proof | +[width="100%",cols="32%,68%",options="header",] +|=== +|Type |Description +|`+Platform+` |Compile-time target: Linux, Windows, MacOS, BSD, WASM -```idris +|`+Result+` |Security check outcome: Ok, Error, InvalidParam, +OutOfMemory, NullPointer + +|`+Handle+` |Opaque non-null pointer with type-level `+So (ptr /= 0)+` +proof +|=== + +[source,idris] +---- -- Non-null handle guaranteed at the type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle -``` +---- -### Layout.idr — Memory Layout Proofs +==== Layout.idr — Memory Layout Proofs -Provides `Layout` records (size + alignment) and two key proof types: +Provides `+Layout+` records (size + alignment) and two key proof types: -- **`PlatformIndependent`** — witnesses that a layout is portable across - architectures -- **`CCompatible`** — proves a type matches C struct packing rules, safe for - FFI +* *`+PlatformIndependent+`* — witnesses that a layout is portable across +architectures +* *`+CCompatible+`* — proves a type matches C struct packing rules, safe +for FFI -Also includes `generateCDecl` for emitting C `typedef` declarations from -proven layouts. +Also includes `+generateCDecl+` for emitting C `+typedef+` declarations +from proven layouts. -### Foreign.idr — FFI Declarations +==== Foreign.idr — FFI Declarations -Declares `prim__blake3` and `prim__sha256` using `%foreign "C:...,libochrance"` -with `Buffer`-based signatures matching the Zig exports. +Declares `+prim__blake3+` and `+prim__sha256+` using +`+%foreign "C:...,libochrance"+` with `+Buffer+`-based signatures +matching the Zig exports. -## Zig FFI Implementation +=== Zig FFI Implementation -All functions in `ffi/zig/src/main.zig` use Zig's `std.crypto` library: +All functions in `+ffi/zig/src/main.zig+` use Zig’s `+std.crypto+` +library: -### Hash Functions +==== Hash Functions All three hash functions share the same ABI contract: -```c +[source,c] +---- void hash_fn(const uint8_t* data, size_t len, uint8_t out[32]); -``` +---- -| Function | Algorithm | Output | -|----------|-----------|--------| -| `blake3_hash` | BLAKE3 | 32 bytes | -| `sha256_hash` | SHA-256 | 32 bytes | -| `sha3_256_hash` | SHA3-256 | 32 bytes | +[cols=",,",options="header",] +|=== +|Function |Algorithm |Output +|`+blake3_hash+` |BLAKE3 |32 bytes +|`+sha256_hash+` |SHA-256 |32 bytes +|`+sha3_256_hash+` |SHA3-256 |32 bytes +|=== -### Signature Verification +==== Signature Verification -```c +[source,c] +---- int ed25519_verify( const uint8_t signature[64], const uint8_t public_key[32], @@ -123,27 +132,29 @@ int ed25519_verify( size_t msg_len ); // Returns: 1 if valid, 0 if invalid -``` - -## How They Connect - -1. **Zig compiles** `ffi/zig/src/main.zig` into `libochrance.so` (shared - library with C-compatible exports) -2. **Idris2 FFI declarations** in `Ochrance.FFI.Crypto` use - `%foreign "C:blake3_hash,libochrance"` to bind primitives -3. **Buffer management** in `Crypto.idr` allocates `Data.Buffer` objects, - writes input bytes, calls the FFI primitive, reads output bytes -4. **Public API** (`blake3`, `sha256`, `sha3_256`, `ed25519Verify`) wraps - everything in `HasIO io` for safe usage -5. **Merkle tree** (`Ochrance.Filesystem.Merkle`) calls `hashPairBlake3` - which delegates to `blake3` for cryptographic tree hashing -6. **ABI modules** (`src/abi/`) provide the formal foundation: type - definitions with dependent-type proofs, memory layout verification, - and C-header generation - -## Directory Structure - -``` +---- + +=== How They Connect + +[arabic] +. *Zig compiles* `+ffi/zig/src/main.zig+` into `+libochrance.so+` +(shared library with C-compatible exports) +. *Idris2 FFI declarations* in `+Ochrance.FFI.Crypto+` use +`+%foreign "C:blake3_hash,libochrance"+` to bind primitives +. *Buffer management* in `+Crypto.idr+` allocates `+Data.Buffer+` +objects, writes input bytes, calls the FFI primitive, reads output bytes +. *Public API* (`+blake3+`, `+sha256+`, `+sha3_256+`, `+ed25519Verify+`) +wraps everything in `+HasIO io+` for safe usage +. *Merkle tree* (`+Ochrance.Filesystem.Merkle+`) calls +`+hashPairBlake3+` which delegates to `+blake3+` for cryptographic tree +hashing +. *ABI modules* (`+src/abi/+`) provide the formal foundation: type +definitions with dependent-type proofs, memory layout verification, and +C-header generation + +=== Directory Structure + +.... ochrance/ ├── src/abi/Ochrance/ABI/ # Idris2 ABI definitions │ ├── Types.idr # Platform, Result, Handle @@ -168,81 +179,88 @@ ochrance/ ├── Filesystem/Merkle.idr # Uses hashPairBlake3 for tree hashing ├── Filesystem/Verify.idr # Uses blake3 for block verification └── A2ML/ # A2ML manifest parsing/validation -``` +.... -## Building +=== Building -### Build the Zig FFI Library +==== Build the Zig FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug (libochrance.so) zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run Zig unit tests -``` +---- -### Build the Idris2 Core +==== Build the Idris2 Core -```bash +[source,bash] +---- # Ensure libochrance.so is on LD_LIBRARY_PATH export LD_LIBRARY_PATH="$PWD/ffi/zig/zig-out/lib:$LD_LIBRARY_PATH" # Type-check and build (the core package includes the filesystem subsystem) idris2 --build ochrance.ipkg -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-linux zig build -Dtarget=aarch64-macos -``` +---- -## Testing +=== Testing -### Zig Unit Tests +==== Zig Unit Tests The Zig source includes inline tests for all four FFI functions: -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -Tests cover: empty string hashing (BLAKE3, SHA-256, SHA3-256), known-answer -tests ("abc" for BLAKE3), valid Ed25519 signature verification, and invalid -signature rejection. +Tests cover: empty string hashing (BLAKE3, SHA-256, SHA3-256), +known-answer tests ("`abc`" for BLAKE3), valid Ed25519 signature +verification, and invalid signature rejection. -### Idris2 Integration Tests +==== Idris2 Integration Tests -```bash +[source,bash] +---- idris2 --install ochrance.ipkg idris2 --build tests/integration/tests.ipkg ./tests/integration/build/exec/integration-tests -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI types** (`src/abi/Ochrance/ABI/Types.idr`) — add or modify - type definitions with proofs -2. **Update FFI declarations** (`ochrance-core/Ochrance/FFI/Crypto.idr`) — - add `%foreign` declarations and buffer management -3. **Update Zig implementation** (`ffi/zig/src/main.zig`) — implement the - C-compatible function matching the declaration -4. **Add tests** — Zig inline tests for the new function, Idris2 integration - tests for the wrapper -5. **Verify totality** — all Idris2 modules must pass `%default total` +[arabic] +. *Update ABI types* (`+src/abi/Ochrance/ABI/Types.idr+`) — add or +modify type definitions with proofs +. *Update FFI declarations* (`+ochrance-core/Ochrance/FFI/Crypto.idr+`) +— add `+%foreign+` declarations and buffer management +. *Update Zig implementation* (`+ffi/zig/src/main.zig+`) — implement the +C-compatible function matching the declaration +. *Add tests* — Zig inline tests for the new function, Idris2 +integration tests for the wrapper +. *Verify totality* — all Idris2 modules must pass `+%default total+` -## License +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..293a120 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,89 @@ +== Changelog + +All notable changes to `+ochrance+` will be documented in this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add stapeln.toml layer-based container definitionfrom existing +Containerfile to stapeln format.Chainguard base, security hardening, +SBOM generation.-Authored-By: Claude Opus 4.6 (1M context) +noreply@anthropic.com +* feat: deploy UX Manifesto infrastructure +* feat: add first seam record (ochrance-januskey) +* feat: merge Progressive.idr, Containerfile, flake.nix from +ochrance-framework +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat: complete Phase 1 - dependent types, linear types, FFI buffers, +end-to-end test +* feat: implement hex string parsing for Ed25519 signatures +* feat: add Ed25519 signature verification to FFI +* feat: successful Phase 1 build with Idris2 + Zig FFI + +==== Fixed + +* fix(ci): Phase-2 fleet submission must not fail the security gate +(#12) +* fix(ci): hypatia-scan workdir ($\{\{ env.HOME }} resolves empty) (#11) +* fix(ci): hypatia-scan.yml – pass GITHUB_TOKEN, use –exit-zero +(hyperpolymath/hypatia#213) (#6) +* fix(ci): bump erlef/setup-beam SHA for ubuntu24 runner support (#7) +* fix(ci): repair YAML block-scalar in workflow-linter Check Permissions +step (#8) +* fix(ci): move secret-scanner Cargo.toml gate from job-level if: to +step-level (#9) +* fix(ci): resolve 6 workflow failures across CI pipeline +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: correct email jonathan.jewell → j.d.a.jewell + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) +* refactor: fix SCM file duplication and update documentation + +==== Documentation + +* docs: update TEST-NEEDS.md with session 9 E2E CI additions +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add TEST-NEEDS.md and/or PROOF-NEEDS.md from audit +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add ARCHITECTURE.md with reversibility stack + reposystem +boundary +* docs: resolve P0 tangle — document complementary relationship with +ochrance-framework +* docs: update STATE.scm - Phase 1 complete, Phase 2 started +* docs: add AI Gatekeeper Protocol notes and foundations status + +==== CI + +* ci(secret-scanner): drop duplicate –fail from trufflehog extra_args +(#5) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci: restore Dependabot security path + wire auto-merge +* ci(e2e): add just e2e recipe wired to tests/e2e_test.sh +* ci: add E2E/property/aspect CI workflow + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 6f7d8fe..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,77 +0,0 @@ - - -# Changelog - -All notable changes to `ochrance` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add stapeln.toml layer-based container definition\n\nConverted from existing Containerfile to stapeln format.\nIncludes Chainguard base, security hardening, SBOM generation.\n\nCo-Authored-By: Claude Opus 4.6 (1M context) -- feat: deploy UX Manifesto infrastructure -- feat: add first seam record (ochrance-januskey) -- feat: merge Progressive.idr, Containerfile, flake.nix from ochrance-framework -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat: complete Phase 1 - dependent types, linear types, FFI buffers, end-to-end test -- feat: implement hex string parsing for Ed25519 signatures -- feat: add Ed25519 signature verification to FFI -- feat: successful Phase 1 build with Idris2 + Zig FFI - -### Fixed - -- fix(ci): Phase-2 fleet submission must not fail the security gate (#12) -- fix(ci): hypatia-scan workdir (${{ env.HOME }} resolves empty) (#11) -- fix(ci): hypatia-scan.yml -- pass GITHUB_TOKEN, use --exit-zero (hyperpolymath/hypatia#213) (#6) -- fix(ci): bump erlef/setup-beam SHA for ubuntu24 runner support (#7) -- fix(ci): repair YAML block-scalar in workflow-linter Check Permissions step (#8) -- fix(ci): move secret-scanner Cargo.toml gate from job-level if: to step-level (#9) -- fix(ci): resolve 6 workflow failures across CI pipeline -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: correct email jonathan.jewell → j.d.a.jewell - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) -- refactor: fix SCM file duplication and update documentation - -### Documentation - -- docs: update TEST-NEEDS.md with session 9 E2E CI additions -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add TEST-NEEDS.md and/or PROOF-NEEDS.md from audit -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add ARCHITECTURE.md with reversibility stack + reposystem boundary -- docs: resolve P0 tangle — document complementary relationship with ochrance-framework -- docs: update STATE.scm - Phase 1 complete, Phase 2 started -- docs: add AI Gatekeeper Protocol notes and foundations status - -### CI - -- ci(secret-scanner): drop duplicate --fail from trufflehog extra_args (#5) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci: restore Dependabot security path + wire auto-merge -- ci(e2e): add just e2e recipe wired to tests/e2e_test.sh -- ci: add E2E/property/aspect CI workflow - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..c0e2406 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Ochrance a harassment-free experience for everyone, regardless of age, +body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/ochrance/discussions[Discussion] (for +general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index e3d4b34..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,331 +0,0 @@ - -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Ochrance a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/ochrance/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..920dc73 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/ochrance.git cd ochrance + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create ochrance-dev toolbox enter ochrance-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +ochrance/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # Library code +(Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) ├── plugins/ +# Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) ├── docs/ # +Documentation (Perimeter 3) │ ├── architecture/ # ADRs, specs (Perimeter +2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ # Examples +(Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ # Test +suite (Perimeter 2-3) ├── .well-known/ # Protocol files (Perimeter 1-3) +├── .github/ # GitHub config (Perimeter 1) │ ├── ISSUE_TEMPLATE/ │ └── +workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md # +This file ├── GOVERNANCE.md ├── LICENSE ├── MAINTAINERS.md ├── +README.adoc ├── SECURITY.md ├── flake.nix # Nix flake (Perimeter 1) └── +Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/ochrance/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/ochrance/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/ochrance/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/ochrance/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 98bf4c0..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/ochrance.git -cd ochrance - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create ochrance-dev -toolbox enter ochrance-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -ochrance/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/ochrance/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/ochrance/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/ochrance/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/ochrance/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index f893c5c..9b836fb 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -1,162 +1,60 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble +== Governance -This document describes the governance model for this repository. +=== Overview -== Overview +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. -This repository follows a **Sole Maintainer Governance Model**: +=== Roles and Responsibilities -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable +==== Maintainers -== Core Principles +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support -[cols="1,2"] -|=== -| Principle | Description +==== Contributors -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity +=== Decision Making -| **Transparency** | All significant decisions are documented publicly +==== Minor Changes -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates -| **Open Contribution** | Anyone can contribute via fork and pull request +==== Major Changes -|=== +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers -== Roles and Permissions +==== Breaking Changes -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users +=== Code of Conduct -|=== +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. -== Decision Making Framework +=== Communication -=== Routine Decisions +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates +=== Licensing -**Process**: Maintainer reviews and merges PRs that meet quality standards. +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. -=== Significant Changes +''''' -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **Signing** | All commits must be signed (SSH or GPG) - -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/descriptiles/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..7d4addc --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,39 @@ +== PROOF-NEEDS.md — ochrance + +=== Current State + +* **src/abi/*.idr**: YES — `+Ochrance/+` subdirectory +* *Dangerous patterns*: 0 (1 hit is in echidnabot.scm documentation) +* *LOC*: ~6,300 +* *ABI layer*: Idris2 ABI present in Ochrance subdirectory + +=== What Needs Proving + +[width="100%",cols="51%,27%,22%",options="header",] +|=== +|Component |What |Why +|Protection policy evaluation |Policy decisions are deterministic and +total |Inconsistent protection decisions leave gaps + +|Guard state machine |State transitions cover all edge cases |Missed +transitions leave system unprotected + +|Alert classification |Threat classification is sound (no false +negatives for critical threats) |Missing critical alerts is a security +failure + +|Audit trail integrity |Audit log entries are append-only and +tamper-evident |Compromised audit trail hides attacks +|=== + +=== Recommended Prover + +*Idris2* — ABI layer present. Protection policy evaluation and guard +state machines are natural fits for dependent types with exhaustive +pattern matching. + +=== Priority + +*MEDIUM* — Security guardian tool. Policy evaluation correctness is the +highest-value proof target. False negatives in threat classification are +the most dangerous failure mode. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index f26ff91..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,29 +0,0 @@ - -# PROOF-NEEDS.md — ochrance - -## Current State - -- **src/abi/*.idr**: YES — `Ochrance/` subdirectory -- **Dangerous patterns**: 0 (1 hit is in echidnabot.scm documentation) -- **LOC**: ~6,300 -- **ABI layer**: Idris2 ABI present in Ochrance subdirectory - -## What Needs Proving - -| Component | What | Why | -|-----------|------|-----| -| Protection policy evaluation | Policy decisions are deterministic and total | Inconsistent protection decisions leave gaps | -| Guard state machine | State transitions cover all edge cases | Missed transitions leave system unprotected | -| Alert classification | Threat classification is sound (no false negatives for critical threats) | Missing critical alerts is a security failure | -| Audit trail integrity | Audit log entries are append-only and tamper-evident | Compromised audit trail hides attacks | - -## Recommended Prover - -**Idris2** — ABI layer present. Protection policy evaluation and guard state machines are natural fits for dependent types with exhaustive pattern matching. - -## Priority - -**MEDIUM** — Security guardian tool. Policy evaluation correctness is the highest-value proof target. False negatives in threat classification are the most dangerous failure mode. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..e2d70a8 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/ochrance/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |6759885+hyperpolymath@users.noreply.github.com +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+[PGP fingerprint not set]+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint 6759885+hyperpolymath@users.noreply.github.com + +# Encrypt your report +gpg --armor --encrypt --recipient 6759885+hyperpolymath@users.noreply.github.com report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/ochrance+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/ochrance/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using Ochrance, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/hyperpolymath/ochrance/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/ochrance/security/advisories/new[Report +via GitHub] or 6759885+hyperpolymath@users.noreply.github.com + +|*General questions* +|https://github.com/hyperpolymath/ochrance/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep Ochrance and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 196f022..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,410 +0,0 @@ - -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/ochrance/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | 6759885+hyperpolymath@users.noreply.github.com | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `[PGP fingerprint not set]` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint 6759885+hyperpolymath@users.noreply.github.com - -# Encrypt your report -gpg --armor --encrypt --recipient 6759885+hyperpolymath@users.noreply.github.com report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/ochrance`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/ochrance/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using Ochrance, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/hyperpolymath/ochrance/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/ochrance/security/advisories/new) or 6759885+hyperpolymath@users.noreply.github.com | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/ochrance/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep Ochrance and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..0b26504 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,94 @@ +== TEST-NEEDS.md — ochrance + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +____ +Generated 2026-03-29 by punishing audit. +____ + +=== Current State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Unit tests |0 |None +|Integration |1 |ffi/zig/test/integration_test.zig +|E2E |0 |None +|Benchmarks |0 |None +|=== + +*Source modules:* 32 Idris2 files total including ABI (Types, Layout, +Foreign), 5 Zig files. Core logic appears to be in Idris2 formal +specifications. + +=== What’s Missing + +==== P2P (Property-Based) Tests + +* [ ] ABI layout: property tests for struct alignment invariants +* [ ] Type encoding: property tests for Idris2->Zig type mapping + +==== E2E Tests + +* [ ] Full ochrance workflow: define -> compile -> verify -> deploy +* [ ] ABI/FFI round-trip: Idris2 spec -> C header -> Zig impl -> +verification + +==== Aspect Tests + +* *Security:* No tests for formal specification bypass, FFI boundary +safety +* *Performance:* No compilation or verification benchmarks +* *Concurrency:* N/A +* *Error handling:* No tests for invalid specifications, malformed ABI +definitions + +==== Build & Execution + +* [ ] Idris2 compilation of all 32 .idr files +* [ ] Zig build + test + +==== Benchmarks Needed + +* [ ] Idris2 type checking time +* [ ] FFI call overhead + +==== Self-Tests + +* [ ] All Idris2 proofs type-check successfully +* [ ] ABI version agreement + +=== Priority + +*HIGH.* 32 Idris2 formal specification files with 0 unit tests and 1 FFI +integration test. The formal proofs should be self-verifying +(type-checking IS testing for Idris2), but there should be explicit test +suites validating the properties claimed by the specifications. + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage + +=== Session 9 additions (2026-04-04) + +==== What Was Added + +[width="100%",cols="22%,44%,34%",options="header",] +|=== +|Area |Tests Added |Location +|CI runner |GitHub Actions workflow for existing E2E tests +|`+.github/workflows/e2e.yml+` +|=== + +==== Updated Test Counts + +[cols=",,",options="header",] +|=== +|Suite |Count |Status +|E2E tests |1 |Existing test suite now wired to CI +|CI workflows |21 |Running e2e suite +|=== diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 22e8226..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,73 +0,0 @@ - -# TEST-NEEDS.md — ochrance - -## CRG Grade: C — ACHIEVED 2026-04-04 - -> Generated 2026-03-29 by punishing audit. - -## Current State - -| Category | Count | Notes | -|-------------|-------|-------| -| Unit tests | 0 | None | -| Integration | 1 | ffi/zig/test/integration_test.zig | -| E2E | 0 | None | -| Benchmarks | 0 | None | - -**Source modules:** 32 Idris2 files total including ABI (Types, Layout, Foreign), 5 Zig files. Core logic appears to be in Idris2 formal specifications. - -## What's Missing - -### P2P (Property-Based) Tests -- [ ] ABI layout: property tests for struct alignment invariants -- [ ] Type encoding: property tests for Idris2->Zig type mapping - -### E2E Tests -- [ ] Full ochrance workflow: define -> compile -> verify -> deploy -- [ ] ABI/FFI round-trip: Idris2 spec -> C header -> Zig impl -> verification - -### Aspect Tests -- **Security:** No tests for formal specification bypass, FFI boundary safety -- **Performance:** No compilation or verification benchmarks -- **Concurrency:** N/A -- **Error handling:** No tests for invalid specifications, malformed ABI definitions - -### Build & Execution -- [ ] Idris2 compilation of all 32 .idr files -- [ ] Zig build + test - -### Benchmarks Needed -- [ ] Idris2 type checking time -- [ ] FFI call overhead - -### Self-Tests -- [ ] All Idris2 proofs type-check successfully -- [ ] ABI version agreement - -## Priority - -**HIGH.** 32 Idris2 formal specification files with 0 unit tests and 1 FFI integration test. The formal proofs should be self-verifying (type-checking IS testing for Idris2), but there should be explicit test suites validating the properties claimed by the specifications. - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage - -## Session 9 additions (2026-04-04) - -### What Was Added - -| Area | Tests Added | Location | -|------|-------------|----------| -| CI runner | GitHub Actions workflow for existing E2E tests | `.github/workflows/e2e.yml` | - -### Updated Test Counts - -| Suite | Count | Status | -|-------|-------|--------| -| E2E tests | 1 | Existing test suite now wired to CI | -| CI workflows | 21 | Running e2e suite | diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 85% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index a80eef7..0915000 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== Ochránce — Project Topology -# Ochránce — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ OPERATOR / ADMIN │ │ (Filesystem Audit / Verification)│ @@ -50,17 +43,19 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile Automation .machine_readable/ │ │ Idris2 ipkg 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -> Percentages track **proof / verification completeness** — the honest axis for a -> verification framework — **not** "code exists". `docs/PROOFS.adoc` is the -> authoritative ledger; this dashboard only summarises it. Where an implementation -> exists but its correctness is unproven (or is a stub), the bar reflects the -> *proof*, not the code. +____ +Percentages track *proof / verification completeness* — the honest axis +for a verification framework — *not* "`code exists`". +`+docs/PROOFS.adoc+` is the authoritative ledger; this dashboard only +summarises it. Where an implementation exists but its correctness is +unproven (or is a stub), the bar reflects the _proof_, not the code. +____ -``` +.... COMPONENT STATUS NOTES (proof / verification axis) ─────────────────────────────────── ────────────── ──────────────────────────────────────────── CORE VERIFICATION (IDRIS2) @@ -101,30 +96,32 @@ REPO INFRASTRUCTURE OVERALL (proof axis): ███████░░░ ~70% Stages 1–3 done (mod named hypotheses); Stage 4 open: Merkle completeness, monotonicity cases, VerifiedSubsystem law. See docs/PROOFS.adoc. -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... A2ML Manifest ───► Idris2 Parser ───► Merkle Root ───► Attestation │ │ │ │ ▼ ▼ ▼ ▼ Linear Repr ─────► Verified FS ──────► C FFI ───────► ECHIDNA (ML) -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). -The bars track **proof / verification completeness** against `docs/PROOFS.adoc` -(the authoritative ledger), not whether code merely exists. Do not raise a bar to -100% on the strength of an implementation alone — a component is "done" only when -its correctness is proven or honestly bounded per the ledger. +The bars track *proof / verification completeness* against +`+docs/PROOFS.adoc+` (the authoritative ledger), not whether code merely +exists. Do not raise a bar to 100% on the strength of an implementation +alone — a component is "`done`" only when its correctness is proven or +honestly bounded per the ledger. diff --git a/docs/ARCHITECTURE.adoc b/docs/ARCHITECTURE.adoc new file mode 100644 index 0000000..fe1845a --- /dev/null +++ b/docs/ARCHITECTURE.adoc @@ -0,0 +1,185 @@ +== Architecture: Ochrance and the Reversibility Stack + +This document addresses tangles P0-P2 from the repo tangle assessment, +clarifying canonical ownership, the reversibility stack layering, and +the reposystem boundary. + +''''' + +=== P0: Canonical Repository Status + +*ochrance* is the canonical repository for verified subsystem integrity +work. + +The former `+ochrance-framework+` repository has been archived with a +redirect notice. All valuable content (Progressive.idr, Containerfile, +flake.nix) was merged into this repo before archival. The framework repo +originally envisioned a broader four-subsystem architecture (Filesystem, +Memory, Network, Crypto), but the concrete filesystem verification +implementation here in ochrance is the active, thesis-scope work. + +Going forward, any new subsystem modules (Memory, Network, Crypto) will +be developed as peer repos implementing the `+VerifiedSubsystem+` +interface defined in `+ochrance-core/Ochrance/Framework/Interface.idr+`, +not in a separate framework repo. + +''''' + +=== P1: The Reversibility Stack + +Three repositories form a layered reversibility stack. Each layer is +self-contained but designed to compose upward: + +.... ++------------------------------------------------------------+ +| ochrance | +| Filesystem verification with dependent types (Idris2) | +| Merkle trees, A2ML manifests, progressive assurance | +| "Is the filesystem still what we said it was?" | ++------------------------------------------------------------+ + | consumes reversibility primitives from + v ++------------------------------------------------------------+ +| valence-shell (vsh) | +| Formally verified shell with proven reversibility | +| 250+ theorems across 6 proof systems, MAA framework | +| "Every shell operation can be undone, always" | ++------------------------------------------------------------+ + | built on theory from + v ++------------------------------------------------------------+ +| januskey | +| Reversible file operations via Maximal Principle Reduction | +| Content-addressed storage, transaction support (Rust) | +| "Data loss is architecturally impossible" | ++------------------------------------------------------------+ +.... + +==== Layer Boundaries + +*januskey* (bottom layer – theory and primitives): - Provides the +foundational reversibility guarantee: every file operation carries +sufficient metadata for perfect inversion. - Implements +content-addressed storage with SHA256 deduplication. - Transaction +manager groups operations for atomic commit/rollback. - Language: Rust. +Interface: CLI (`+jk+` commands). - Key property: _data loss is +architecturally impossible_ – not unlikely, but structurally prevented +by storing inverse metadata with every operation. + +*valence-shell* (middle layer – shell/CLI reversibility): - Extends +reversibility from file operations to full shell semantics. - Proves +reversibility theorems in 6 independent proof systems (Coq, Lean 4, +Agda, Isabelle/HOL, Mizar, Z3) for cross-validation. - MAA (Mutually +Assured Accountability) framework provides provable audit trails. - Key +theorems: `+rmdir(mkdir(p, fs)) = fs+`, operation sequence composition +reversal. - Language: Rust CLI + formal proofs. Status: advanced +research prototype (v0.9.0). - Trust boundary: formal proofs operate on +abstract models; the Lean-to-Rust extraction gap is not yet formally +verified. + +*ochrance* (top layer – filesystem verification): - Uses dependent types +(Idris2) for mathematically proven filesystem integrity. - Progressive +strictness: Lax (structure only) / Checked (hash verification) / +Attested (full dependent type proofs). - A2ML (Attestation & Audit +Markup Language) manifests describe verified state. - Integrates with +ECHIDNA for neural proof synthesis. - Architecture: L0 Hardware -> L1 C +Shims -> L2 Idris2 Proofs -> L3 Repair -> L4 Policy -> L5 TUI. + +==== How They Relate + +* *januskey* answers: "`Can I undo this file operation?`" (yes, always) +* *valence-shell* answers: "`Can I undo this shell session?`" (yes, with +proofs) +* *ochrance* answers: "`Has anything changed that shouldn’t have?`" +(verified) + +januskey provides the _operational_ reversibility (undo what you did). +valence-shell extends this to _shell-level_ reversibility with formal +guarantees. ochrance provides _verification_ that the filesystem matches +its declared state, using a different technique (dependent type proofs +over Merkle trees rather than operation-level inversion). + +The stack is loosely coupled: each layer is independently useful, but +together they provide a complete story from "`operations are +reversible`" through "`the shell proves it`" to "`the filesystem is +verified.`" + +==== See also: the receipt / residue reading + +A complementary, *documentation-only* reading of this stack treats +ochrance as the _receipt layer_ for valence-shell’s accountable state +transitions, with +https://github.com/hyperpolymath/echo-types[echo-types] supplying the +_semantics of the residue/loss_ those transitions expose (recoverable / +constrained / lossy / obliterative). That bridge is *not mechanised* and +makes no cryptographic-integrity, GDPR, or end-to-end-correctness claim. +See link:VALENCE_SHELL_BRIDGE.adoc[`+VALENCE_SHELL_BRIDGE.adoc+`] and +its machine-readable companion +`+.machine_readable/integrations/valence-shell-bridge.a2ml+` for the +trust boundaries and caveats. + +''''' + +=== P2: Reposystem Boundary + +==== Inside reposystem (monorepo subdirectories) + +The https://github.com/hyperpolymath/reposystem[reposystem] monorepo +contains tools that form the "`railway yard`" for multi-repo ecosystem +management: + +[width="100%",cols="22%,78%",options="header",] +|=== +|Subdirectory |Purpose +|*contractiles* |Contract-based CLI system (must/trust/dust/intend/k9) +|*bitfuckit* |Bitbucket API integration and forge tooling +|*claim-forge* |Repository claiming and ownership verification +|*scaffoldia* |Project scaffolding and template validation +|=== + +These belong inside reposystem because they are all _repo infrastructure +tools_ – they operate on repositories as first-class objects, they share +the graph/slot/provider data model, and they feed into the reposystem +TUI and scenario comparison views. + +==== Standalone (outside reposystem) + +*checky-monkey* and *grim-repo* overlap with reposystem’s concerns but +remain standalone for the following reasons: + +*checky-monkey* (userscript validation platform): - Operates on a +fundamentally different domain: userscripts, userstyles, and browser +extensions – not git repositories. - Has its own persistence layer (CUBS +content-addressed database), its own API (GraphQL + REST), and its own +distribution mechanism (IPFS). - The overlap with reposystem is limited +to sharing the validation/quality-gate pattern. checky-monkey validates +_scripts_; reposystem validates _repo structure_. - Technology stack +diverges: Haskell core, Lua plugins, PostgreSQL – versus reposystem’s +Rust CLI + ReScript data model. - Standalone because: *different domain, +different data model, different tech stack.* + +*grim-repo* (audit-grade repo tooling): - Provides modular auditing +(structure bootstrapping, community standards, golden registry checks) +that could theoretically live inside reposystem. - Remains standalone +because it is designed as a _userscript/browser extension_ that runs on +forge web UIs (GitLab, GitHub, Bitbucket pages), not as a CLI or library +consumed by reposystem. - Its deployment model (browser injection via +Tampermonkey/Violentmonkey) is incompatible with being a reposystem +subdirectory. - It follows a progression model (Raw -> Golden -> +Rhodium) that is complementary to but independent of reposystem’s +scenario/aspect system. - Standalone because: *different deployment +model (browser extension vs CLI), different user interaction pattern +(forge web UI vs terminal).* + +==== Decision Criteria + +A tool belongs inside reposystem if it: 1. Operates on git repositories +as its primary domain object. 2. Shares the slot/provider/scenario data +model. 3. Is consumed as a library or CLI component (not a browser +extension). 4. Benefits from the shared graph view and scenario +comparison. + +A tool remains standalone if it: 1. Has a fundamentally different domain +(scripts, not repos). 2. Has an incompatible deployment model (browser +vs terminal). 3. Has its own persistence and API requirements. 4. Would +create unnecessary coupling if embedded. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md deleted file mode 100644 index 8e61a49..0000000 --- a/docs/ARCHITECTURE.md +++ /dev/null @@ -1,179 +0,0 @@ - - - -# Architecture: Ochrance and the Reversibility Stack - -This document addresses tangles P0-P2 from the repo tangle assessment, clarifying -canonical ownership, the reversibility stack layering, and the reposystem boundary. - ---- - -## P0: Canonical Repository Status - -**ochrance** is the canonical repository for verified subsystem integrity work. - -The former `ochrance-framework` repository has been archived with a redirect notice. -All valuable content (Progressive.idr, Containerfile, flake.nix) was merged into this -repo before archival. The framework repo originally envisioned a broader four-subsystem -architecture (Filesystem, Memory, Network, Crypto), but the concrete filesystem -verification implementation here in ochrance is the active, thesis-scope work. - -Going forward, any new subsystem modules (Memory, Network, Crypto) will be developed -as peer repos implementing the `VerifiedSubsystem` interface defined in -`ochrance-core/Ochrance/Framework/Interface.idr`, not in a separate framework repo. - ---- - -## P1: The Reversibility Stack - -Three repositories form a layered reversibility stack. Each layer is self-contained -but designed to compose upward: - -``` -+------------------------------------------------------------+ -| ochrance | -| Filesystem verification with dependent types (Idris2) | -| Merkle trees, A2ML manifests, progressive assurance | -| "Is the filesystem still what we said it was?" | -+------------------------------------------------------------+ - | consumes reversibility primitives from - v -+------------------------------------------------------------+ -| valence-shell (vsh) | -| Formally verified shell with proven reversibility | -| 250+ theorems across 6 proof systems, MAA framework | -| "Every shell operation can be undone, always" | -+------------------------------------------------------------+ - | built on theory from - v -+------------------------------------------------------------+ -| januskey | -| Reversible file operations via Maximal Principle Reduction | -| Content-addressed storage, transaction support (Rust) | -| "Data loss is architecturally impossible" | -+------------------------------------------------------------+ -``` - -### Layer Boundaries - -**januskey** (bottom layer -- theory and primitives): -- Provides the foundational reversibility guarantee: every file operation carries - sufficient metadata for perfect inversion. -- Implements content-addressed storage with SHA256 deduplication. -- Transaction manager groups operations for atomic commit/rollback. -- Language: Rust. Interface: CLI (`jk` commands). -- Key property: *data loss is architecturally impossible* -- not unlikely, but - structurally prevented by storing inverse metadata with every operation. - -**valence-shell** (middle layer -- shell/CLI reversibility): -- Extends reversibility from file operations to full shell semantics. -- Proves reversibility theorems in 6 independent proof systems (Coq, Lean 4, Agda, - Isabelle/HOL, Mizar, Z3) for cross-validation. -- MAA (Mutually Assured Accountability) framework provides provable audit trails. -- Key theorems: `rmdir(mkdir(p, fs)) = fs`, operation sequence composition reversal. -- Language: Rust CLI + formal proofs. Status: advanced research prototype (v0.9.0). -- Trust boundary: formal proofs operate on abstract models; the Lean-to-Rust - extraction gap is not yet formally verified. - -**ochrance** (top layer -- filesystem verification): -- Uses dependent types (Idris2) for mathematically proven filesystem integrity. -- Progressive strictness: Lax (structure only) / Checked (hash verification) / - Attested (full dependent type proofs). -- A2ML (Attestation & Audit Markup Language) manifests describe verified state. -- Integrates with ECHIDNA for neural proof synthesis. -- Architecture: L0 Hardware -> L1 C Shims -> L2 Idris2 Proofs -> L3 Repair -> - L4 Policy -> L5 TUI. - -### How They Relate - -- **januskey** answers: "Can I undo this file operation?" (yes, always) -- **valence-shell** answers: "Can I undo this shell session?" (yes, with proofs) -- **ochrance** answers: "Has anything changed that shouldn't have?" (verified) - -januskey provides the *operational* reversibility (undo what you did). valence-shell -extends this to *shell-level* reversibility with formal guarantees. ochrance provides -*verification* that the filesystem matches its declared state, using a different -technique (dependent type proofs over Merkle trees rather than operation-level -inversion). - -The stack is loosely coupled: each layer is independently useful, but together they -provide a complete story from "operations are reversible" through "the shell proves it" -to "the filesystem is verified." - -### See also: the receipt / residue reading - -A complementary, **documentation-only** reading of this stack treats ochrance as -the *receipt layer* for valence-shell's accountable state transitions, with -[echo-types](https://github.com/hyperpolymath/echo-types) supplying the -*semantics of the residue/loss* those transitions expose (recoverable / -constrained / lossy / obliterative). That bridge is **not mechanised** and makes -no cryptographic-integrity, GDPR, or end-to-end-correctness claim. See -[`VALENCE_SHELL_BRIDGE.adoc`](VALENCE_SHELL_BRIDGE.adoc) and its machine-readable -companion `.machine_readable/integrations/valence-shell-bridge.a2ml` for the trust boundaries -and caveats. - ---- - -## P2: Reposystem Boundary - -### Inside reposystem (monorepo subdirectories) - -The [reposystem](https://github.com/hyperpolymath/reposystem) monorepo contains tools -that form the "railway yard" for multi-repo ecosystem management: - -| Subdirectory | Purpose | -|----------------|------------------------------------------------------------| -| **contractiles** | Contract-based CLI system (must/trust/dust/intend/k9) | -| **bitfuckit** | Bitbucket API integration and forge tooling | -| **claim-forge** | Repository claiming and ownership verification | -| **scaffoldia** | Project scaffolding and template validation | - -These belong inside reposystem because they are all *repo infrastructure tools* -- -they operate on repositories as first-class objects, they share the graph/slot/provider -data model, and they feed into the reposystem TUI and scenario comparison views. - -### Standalone (outside reposystem) - -**checky-monkey** and **grim-repo** overlap with reposystem's concerns but remain -standalone for the following reasons: - -**checky-monkey** (userscript validation platform): -- Operates on a fundamentally different domain: userscripts, userstyles, and browser - extensions -- not git repositories. -- Has its own persistence layer (CUBS content-addressed database), its own API - (GraphQL + REST), and its own distribution mechanism (IPFS). -- The overlap with reposystem is limited to sharing the validation/quality-gate - pattern. checky-monkey validates *scripts*; reposystem validates *repo structure*. -- Technology stack diverges: Haskell core, Lua plugins, PostgreSQL -- versus - reposystem's Rust CLI + ReScript data model. -- Standalone because: **different domain, different data model, different tech stack.** - -**grim-repo** (audit-grade repo tooling): -- Provides modular auditing (structure bootstrapping, community standards, golden - registry checks) that could theoretically live inside reposystem. -- Remains standalone because it is designed as a *userscript/browser extension* - that runs on forge web UIs (GitLab, GitHub, Bitbucket pages), not as a CLI or - library consumed by reposystem. -- Its deployment model (browser injection via Tampermonkey/Violentmonkey) is - incompatible with being a reposystem subdirectory. -- It follows a progression model (Raw -> Golden -> Rhodium) that is complementary - to but independent of reposystem's scenario/aspect system. -- Standalone because: **different deployment model (browser extension vs CLI), - different user interaction pattern (forge web UI vs terminal).** - -### Decision Criteria - -A tool belongs inside reposystem if it: -1. Operates on git repositories as its primary domain object. -2. Shares the slot/provider/scenario data model. -3. Is consumed as a library or CLI component (not a browser extension). -4. Benefits from the shared graph view and scenario comparison. - -A tool remains standalone if it: -1. Has a fundamentally different domain (scripts, not repos). -2. Has an incompatible deployment model (browser vs terminal). -3. Has its own persistence and API requirements. -4. Would create unnecessary coupling if embedded. diff --git a/docs/OSTREE-INTEGRATION-NOTES.adoc b/docs/OSTREE-INTEGRATION-NOTES.adoc new file mode 100644 index 0000000..4e0a406 --- /dev/null +++ b/docs/OSTREE-INTEGRATION-NOTES.adoc @@ -0,0 +1,129 @@ +== OSTree Integration Notes (Phase 4 Preparation) + +Preparation document for Ochrance Phase 4 (v1.0.0) OSTree integration. +This is a living document — update as the OSTree API evolves. + +=== Planned API Surface + +Based on the ROADMAP.adoc Phase 4 plan, Ochrance will interact with +OSTree via: + +==== Transaction Hooks (`+/etc/ostree/hooks/+`) + +[width="100%",cols="50%,50%",options="header",] +|=== +|Hook Point |Ochrance Action +|*Pre-transaction* |Snapshot current Merkle tree state, validate +manifest signatures + +|*Post-transaction* |Rebuild Merkle tree for updated deployment, verify +integrity +|=== + +==== Systemd Integration + +* *Continuous verification service*: Periodic Merkle tree +re-verification +* *Journal logging*: Structured audit logs for verification results +(pass/fail/repair) + +==== OSTree CLI / Library Calls + +Ochrance will invoke or link against: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|API |Purpose |Stability +|`+ostree admin deploy+` exit hooks |Trigger post-deploy verification +|Stable (hook dirs) + +|`+ostree ls+` / `+ostree diff+` |Enumerate deployment contents for +Merkle input |Stable + +|`+ostree commit+` metadata |Embed Ochrance attestation in commit +metadata |Stable + +|`+libostree+` GObject API (`+OstreeRepo+`, `+OstreeSysroot+`) |Direct +library access (if FFI proves necessary) |Stable, versioned +|=== + +=== Current Stable OSTree API Version + +As of 2026, the relevant stable releases: + +* *libostree*: 2025.x series (year-based versioning since 2023) +* *API stability*: libostree follows a strict ABI stability policy — +symbols are never removed from stable releases +* *GObject Introspection*: Full GIR bindings available +(`+OSTree-1.0.gir+`) + +Key version note: libostree moved to year-based versioning (e.g., +`+2024.1+`, `+2025.3+`). Pin to a minimum of `+2024.1+` for any direct +library linking. + +=== Known Deprecations and Upcoming Changes + +[arabic] +. *GPG signing deprecated in favour of Ed25519 (signapi)* +* `+ostree sign+` now prefers Ed25519 over GPG +* Ochrance already uses Ed25519 (via Zig FFI) — this is aligned +* Migration: Use `+ostree sign --sign-type=ed25519+` when signing +commits +. *Composefs integration (experimental → stabilising)* +* OSTree is gaining native composefs (erofs+overlayfs) support +* This changes how deployments are mounted but NOT the commit/metadata +API +* Impact on Ochrance: Merkle verification inputs may come from composefs +manifests rather than traditional checkout directories +* Action: Monitor `+ostree_repo_checkout_composefs()+` API stability +. *Boot counting / rollback changes* +* Automatic rollback on failed boots is becoming standard +* Ochrance should integrate with boot-counting to trigger verification +on first boot of a new deployment +. *No planned removals* of `+ostree ls+`, `+ostree diff+`, or hook +directories + +=== Migration Strategy + +==== If OSTree Hook API Changes + +Current plan uses simple hook scripts in `+/etc/ostree/hooks/+`. If this +mechanism changes: + +[arabic] +. *Fallback to systemd path units*: Watch `+/ostree/deploy/+` for +changes using `+systemd.path+` units — this is +OSTree-version-independent +. *Fallback to inotify*: Direct filesystem monitoring of sysroot +. *libostree signal handlers*: Connect to GObject signals if using +direct library integration + +==== If Composefs Becomes Default + +[arabic] +. Ochrance Merkle tree inputs should abstract over the deployment source +. Define a `+DeploymentSource+` interface in Idris2 that can read from: +* Traditional OSTree checkout directories +* Composefs manifest files (erofs images) +. Phase 4 implementation should build both backends + +==== If Ed25519 Signing API Changes + +Ochrance’s Ed25519 FFI is self-contained (Zig stdlib, not linked to +libostree). If OSTree changes its Ed25519 wire format: + +[arabic] +. The Zig FFI functions (`+ed25519_verify+`) operate on raw bytes — +format-agnostic +. Only the integration layer that reads OSTree commit signatures would +need updating +. Keep signature parsing separate from verification logic + +=== References + +* https://ostreedev.github.io/ostree/[libostree API reference] +* https://github.com/ostreedev/ostree/blob/main/doc/composefs.md[OSTree +composefs design] +* https://ostreedev.github.io/ostree/signing/[Ed25519 sign API] +* https://fedoraproject.org/kinoite/[Fedora Kinoite] — primary +deployment target diff --git a/docs/OSTREE-INTEGRATION-NOTES.md b/docs/OSTREE-INTEGRATION-NOTES.md deleted file mode 100644 index 76ec4d6..0000000 --- a/docs/OSTREE-INTEGRATION-NOTES.md +++ /dev/null @@ -1,105 +0,0 @@ - - -# OSTree Integration Notes (Phase 4 Preparation) - -Preparation document for Ochrance Phase 4 (v1.0.0) OSTree integration. -This is a living document — update as the OSTree API evolves. - -## Planned API Surface - -Based on the ROADMAP.adoc Phase 4 plan, Ochrance will interact with OSTree via: - -### Transaction Hooks (`/etc/ostree/hooks/`) - -| Hook Point | Ochrance Action | -|---|---| -| **Pre-transaction** | Snapshot current Merkle tree state, validate manifest signatures | -| **Post-transaction** | Rebuild Merkle tree for updated deployment, verify integrity | - -### Systemd Integration - -- **Continuous verification service**: Periodic Merkle tree re-verification -- **Journal logging**: Structured audit logs for verification results (pass/fail/repair) - -### OSTree CLI / Library Calls - -Ochrance will invoke or link against: - -| API | Purpose | Stability | -|---|---|---| -| `ostree admin deploy` exit hooks | Trigger post-deploy verification | Stable (hook dirs) | -| `ostree ls` / `ostree diff` | Enumerate deployment contents for Merkle input | Stable | -| `ostree commit` metadata | Embed Ochrance attestation in commit metadata | Stable | -| `libostree` GObject API (`OstreeRepo`, `OstreeSysroot`) | Direct library access (if FFI proves necessary) | Stable, versioned | - -## Current Stable OSTree API Version - -As of 2026, the relevant stable releases: - -- **libostree**: 2025.x series (year-based versioning since 2023) -- **API stability**: libostree follows a strict ABI stability policy — symbols are never removed from stable releases -- **GObject Introspection**: Full GIR bindings available (`OSTree-1.0.gir`) - -Key version note: libostree moved to year-based versioning (e.g., `2024.1`, `2025.3`). -Pin to a minimum of `2024.1` for any direct library linking. - -## Known Deprecations and Upcoming Changes - -1. **GPG signing deprecated in favour of Ed25519 (signapi)** - - `ostree sign` now prefers Ed25519 over GPG - - Ochrance already uses Ed25519 (via Zig FFI) — this is aligned - - Migration: Use `ostree sign --sign-type=ed25519` when signing commits - -2. **Composefs integration (experimental → stabilising)** - - OSTree is gaining native composefs (erofs+overlayfs) support - - This changes how deployments are mounted but NOT the commit/metadata API - - Impact on Ochrance: Merkle verification inputs may come from composefs manifests - rather than traditional checkout directories - - Action: Monitor `ostree_repo_checkout_composefs()` API stability - -3. **Boot counting / rollback changes** - - Automatic rollback on failed boots is becoming standard - - Ochrance should integrate with boot-counting to trigger verification - on first boot of a new deployment - -4. **No planned removals** of `ostree ls`, `ostree diff`, or hook directories - -## Migration Strategy - -### If OSTree Hook API Changes - -Current plan uses simple hook scripts in `/etc/ostree/hooks/`. If this mechanism -changes: - -1. **Fallback to systemd path units**: Watch `/ostree/deploy/` for changes - using `systemd.path` units — this is OSTree-version-independent -2. **Fallback to inotify**: Direct filesystem monitoring of sysroot -3. **libostree signal handlers**: Connect to GObject signals if using - direct library integration - -### If Composefs Becomes Default - -1. Ochrance Merkle tree inputs should abstract over the deployment source -2. Define a `DeploymentSource` interface in Idris2 that can read from: - - Traditional OSTree checkout directories - - Composefs manifest files (erofs images) -3. Phase 4 implementation should build both backends - -### If Ed25519 Signing API Changes - -Ochrance's Ed25519 FFI is self-contained (Zig stdlib, not linked to libostree). -If OSTree changes its Ed25519 wire format: - -1. The Zig FFI functions (`ed25519_verify`) operate on raw bytes — format-agnostic -2. Only the integration layer that reads OSTree commit signatures would need updating -3. Keep signature parsing separate from verification logic - -## References - -- [libostree API reference](https://ostreedev.github.io/ostree/) -- [OSTree composefs design](https://github.com/ostreedev/ostree/blob/main/doc/composefs.md) -- [Ed25519 sign API](https://ostreedev.github.io/ostree/signing/) -- [Fedora Kinoite](https://fedoraproject.org/kinoite/) — primary deployment target diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..79786bd --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,70 @@ +== Tech-Debt Audit — ochrance — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+2026-05-22+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +Scanner counted the following markers in proof-bearing files of this +repo: + +.... +files= 32 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 +.... + +*Total markers:* 0. *Severity:* `+>00+`. + +*Recommended next move:* none — no proof-debt markers detected. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+MPL-2.0 MPL-2.0 MPL-2.0+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |87 +|`+docs/+` files |3 +|`+docs/+` LoC |302 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+readme=87 docs=3/302+` +|=== + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 50ccde2..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,62 +0,0 @@ - - -# Tech-Debt Audit — ochrance — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `2026-05-22`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 32 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 -``` - -**Total markers:** 0. **Severity:** `>00`. - -**Recommended next move:** none — no proof-debt markers detected. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `MPL-2.0 MPL-2.0 MPL-2.0` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 87 | -| `docs/` files | 3 | -| `docs/` LoC | 302 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `readme=87 docs=3/302` | - - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..b11de16 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — ochrance (Developer) + +=== What is ochrance? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 530f5b5..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — ochrance (Developer) - -## What is ochrance? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..2eef6df --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — ochrance (User) + +=== What is ochrance? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 4ff5f44..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — ochrance (User) - -## What is ochrance? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/src/abi/README.adoc b/src/abi/README.adoc new file mode 100644 index 0000000..378d163 --- /dev/null +++ b/src/abi/README.adoc @@ -0,0 +1,112 @@ +== Ochránce ABI Layer + +Formally verified Application Binary Interface (ABI) for cryptographic +hashing operations. + +=== Architecture + +.... +Idris2 (ABI) → C Headers → Zig (FFI) + ↓ ↓ +Type Proofs Memory-Safe Impl +.... + +=== Modules + +==== `+Ochrance.ABI.Types+` + +* *HashAlg n* - Hash algorithms indexed by output size +* *HashValue n* - Exactly n bytes with size proof +* *HashDigest* - Algorithm + value with consistency proof +* *StableABI* - Proof of platform-independent layout + +==== `+Ochrance.ABI.Layout+` + +* Memory layout descriptors +* Alignment constraints +* Platform independence proofs +* C compatibility verification + +==== `+Ochrance.ABI.Foreign+` + +* FFI function signatures +* Type-safe wrappers with size guarantees +* Determinism assertions +* Test vectors for ABI compliance + +=== Guarantees + +[arabic] +. *Size Safety*: Hash output size encoded in types ++ +[source,idris] +---- +blake3Hash : Vect n Byte -> IO (HashValue 32) -- Always 32 bytes +---- +. *No Padding*: Byte arrays are tightly packed ++ +[source,idris] +---- +hashValueNoPadding : NoPadding (HashValue n) +---- +. *Platform Independent*: Layout doesn’t depend on architecture ++ +[source,idris] +---- +hashValueLayoutIndependent : PlatformIndependent (hashValueLayout n) +---- +. *C Compatible*: Matches `+uint8_t data[n]+` layout ++ +[source,idris] +---- +hashValueCCompatible : CCompatible (HashValue n) +---- + +=== Building + +==== Build Idris2 ABI + +[source,bash] +---- +idris2 --build ochrance-abi.ipkg +---- + +==== Build Zig FFI + +[source,bash] +---- +cd ffi/zig +zig build +---- + +==== Run Tests + +[source,bash] +---- +zig build test # Zig unit tests +idris2 --build ochrance-abi.ipkg # Idris2 type checking +---- + +=== FFI Contract + +[width="100%",cols="31%,21%,24%,24%",options="header",] +|=== +|Function |Input |Output |Safety +|`+blake3_hash+` |`+const uint8_t*, size_t+` |`+uint8_t[32]+` |Buffer +overflow impossible (Zig slice) + +|`+sha256_hash+` |`+const uint8_t*, size_t+` |`+uint8_t[32]+` |Buffer +overflow impossible (Zig slice) + +|`+sha3_256_hash+` |`+const uint8_t*, size_t+` |`+uint8_t[32]+` |Buffer +overflow impossible (Zig slice) +|=== + +=== Test Vectors + +Empty string hashes (for ABI verification): - BLAKE3: +`+af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262+` - +SHA-256: +`+e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855+` - +SHA3-256: +`+a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a+` diff --git a/src/abi/README.md b/src/abi/README.md deleted file mode 100644 index e90ac53..0000000 --- a/src/abi/README.md +++ /dev/null @@ -1,91 +0,0 @@ - -# Ochránce ABI Layer - -Formally verified Application Binary Interface (ABI) for cryptographic hashing operations. - -## Architecture - -``` -Idris2 (ABI) → C Headers → Zig (FFI) - ↓ ↓ -Type Proofs Memory-Safe Impl -``` - -## Modules - -### `Ochrance.ABI.Types` -- **HashAlg n** - Hash algorithms indexed by output size -- **HashValue n** - Exactly n bytes with size proof -- **HashDigest** - Algorithm + value with consistency proof -- **StableABI** - Proof of platform-independent layout - -### `Ochrance.ABI.Layout` -- Memory layout descriptors -- Alignment constraints -- Platform independence proofs -- C compatibility verification - -### `Ochrance.ABI.Foreign` -- FFI function signatures -- Type-safe wrappers with size guarantees -- Determinism assertions -- Test vectors for ABI compliance - -## Guarantees - -1. **Size Safety**: Hash output size encoded in types - ```idris - blake3Hash : Vect n Byte -> IO (HashValue 32) -- Always 32 bytes - ``` - -2. **No Padding**: Byte arrays are tightly packed - ```idris - hashValueNoPadding : NoPadding (HashValue n) - ``` - -3. **Platform Independent**: Layout doesn't depend on architecture - ```idris - hashValueLayoutIndependent : PlatformIndependent (hashValueLayout n) - ``` - -4. **C Compatible**: Matches `uint8_t data[n]` layout - ```idris - hashValueCCompatible : CCompatible (HashValue n) - ``` - -## Building - -### Build Idris2 ABI -```bash -idris2 --build ochrance-abi.ipkg -``` - -### Build Zig FFI -```bash -cd ffi/zig -zig build -``` - -### Run Tests -```bash -zig build test # Zig unit tests -idris2 --build ochrance-abi.ipkg # Idris2 type checking -``` - -## FFI Contract - -| Function | Input | Output | Safety | -|----------|-------|--------|--------| -| `blake3_hash` | `const uint8_t*, size_t` | `uint8_t[32]` | Buffer overflow impossible (Zig slice) | -| `sha256_hash` | `const uint8_t*, size_t` | `uint8_t[32]` | Buffer overflow impossible (Zig slice) | -| `sha3_256_hash` | `const uint8_t*, size_t` | `uint8_t[32]` | Buffer overflow impossible (Zig slice) | - -## Test Vectors - -Empty string hashes (for ABI verification): -- BLAKE3: `af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262` -- SHA-256: `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855` -- SHA3-256: `a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a`