From a318fa2fcf493f2460ca830d53f05bd2ddb7e541 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 16 Jun 2026 18:12:30 +0100 Subject: [PATCH 01/11] chore(gitignore): ignore Agda/Zig/bench/priv build artifacts Stops six untracked build outputs from cluttering the tree: Agda .agdai interface files, benches/eval_tmp + eval_results.json, demo guest wasm, priv/snif_eval.json, and zig/buffer_abi_build. All are regenerated by the proof/bench/build recipes. Co-Authored-By: Claude Opus 4.8 (1M context) --- .gitignore | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.gitignore b/.gitignore index 54b42a2..ee0a5dc 100644 --- a/.gitignore +++ b/.gitignore @@ -114,3 +114,11 @@ deps/ .cache/ build/ dist/ + +# Proof + guest build artifacts (snifs) +*.agdai +/benches/eval_tmp/ +/benches/eval_results.json +/demo/priv/*.wasm +/priv/snif_eval.json +/zig/buffer_abi_build/ From 37c2e184acb43b237636f8a4ca1ce304d447fbc7 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 16 Jun 2026 18:12:39 +0100 Subject: [PATCH 02/11] chore(ci): track bag-of-actions ci-checks.exs (owned-compute gate manifest) The manifest the bag-of-actions `mix bag.report` dispatcher runs to execute the snifs proof + ABI gates on an owned nix-capable node and post each verdict back as a GitHub commit status (snifs-proofs -> 'bag / Formal proofs (owned compute)', snifs-abi -> 'bag / ABI conformance (owned compute)'). Both Justfile recipes it names (proof-check-all, abi-conformance) exist. Pairs with bag-of-actions PR #7. Co-Authored-By: Claude Opus 4.8 (1M context) --- ci-checks.exs | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 ci-checks.exs diff --git a/ci-checks.exs b/ci-checks.exs new file mode 100644 index 0000000..24ef7af --- /dev/null +++ b/ci-checks.exs @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) Jonathan D.A. Jewell +# +# bag-of-actions CI manifest for snifs — runs the proof gate + ABI conformance on +# OWNED compute (a `nix`-capable estate node, e.g. mesh-server-1) with ZERO GitHub +# Actions minutes, and posts each verdict back to the PR commit as a status that +# satisfies a branch-protection required check. +# +# Run on the node, from the snifs repo root, after `git fetch`/checkout of the PR head: +# +# GITHUB_REPOSITORY=hyperpolymath/snifs GITHUB_SHA= \ +# mix bag.report /path/to/snifs/ci-checks.exs +# +# (`mix bag.report` lives in bag-of-actions; run it from there with this manifest +# path, or `cd` into bag and pass an absolute path.) +# +# `required_cap: "nix"` routes each check to a node that has the `nix` capability; +# the commands fetch the actual toolchain (idris2/lean4/agda/zig/wasm-tools/python/just) +# via `nix shell` at run time. `github_context` is the required-status-check NAME the +# verdict posts to — point branch-protection's required contexts at these. +[ + %{ + check_id: "snifs-proofs", + command: [ + "bash", + "-lc", + "nix shell nixpkgs#idris2 nixpkgs#lean4 nixpkgs#agda nixpkgs#just --command bash -c 'just proof-check-all'" + ], + required_cap: "nix", + github_context: "bag / Formal proofs (owned compute)" + }, + %{ + check_id: "snifs-abi", + command: [ + "bash", + "-lc", + "nix shell nixpkgs#zig nixpkgs#wasm-tools nixpkgs#python3 nixpkgs#just --command bash -c 'just abi-conformance'" + ], + required_cap: "nix", + github_context: "bag / ABI conformance (owned compute)" + } +] From baa2ad217f4d460719bc56eea29e8e8bc29b58c4 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 16 Jun 2026 18:14:02 +0100 Subject: [PATCH 03/11] docs(manifests): add nested AI manifests to benches/demo/rust/rust-guest/zig/docs-templates Closes the manifest-hierarchy gap: every substantive top-level source dir now declares its scope and invariants via a nested 0.N-AI-MANIFEST.a2ml, matching the estate convention already followed by docs/, src/, features/, container/, examples/. docs/templates notes that the load-bearing contractiles live under .machine_readable/contractiles/ (this is the template copy). Co-Authored-By: Claude Opus 4.8 (1M context) --- benches/0.1-AI-MANIFEST.a2ml | 21 +++++++++++++++++++++ demo/0.1-AI-MANIFEST.a2ml | 22 ++++++++++++++++++++++ docs/templates/0.2-AI-MANIFEST.a2ml | 18 ++++++++++++++++++ rust-guest/0.1-AI-MANIFEST.a2ml | 20 ++++++++++++++++++++ rust/0.1-AI-MANIFEST.a2ml | 23 +++++++++++++++++++++++ zig/0.1-AI-MANIFEST.a2ml | 23 +++++++++++++++++++++++ 6 files changed, 127 insertions(+) create mode 100644 benches/0.1-AI-MANIFEST.a2ml create mode 100644 demo/0.1-AI-MANIFEST.a2ml create mode 100644 docs/templates/0.2-AI-MANIFEST.a2ml create mode 100644 rust-guest/0.1-AI-MANIFEST.a2ml create mode 100644 rust/0.1-AI-MANIFEST.a2ml create mode 100644 zig/0.1-AI-MANIFEST.a2ml diff --git a/benches/0.1-AI-MANIFEST.a2ml b/benches/0.1-AI-MANIFEST.a2ml new file mode 100644 index 0000000..7d95aa7 --- /dev/null +++ b/benches/0.1-AI-MANIFEST.a2ml @@ -0,0 +1,21 @@ +# SPDX-License-Identifier: MPL-2.0 +--- +### [META] +id: "benches" +level: 1 +parent: "../0-AI-MANIFEST.a2ml" + +--- +### [AI_MANIFEST] +description: | + Benchmark and safety-assertion harness for the SNIF guest. Drives the + ReleaseSafe-vs-ReleaseFast comparison and the metamorphic eval. + +canonical_locations: + safety_assertion: "assert_safer.py" + eval_driver: "snif_eval.sh" + template_bench: "template_bench.sh" + +invariants: + - "Generated outputs (eval_results.json, eval_tmp/) are build artifacts and MUST NOT be committed." + - "ReleaseSafe is the trust baseline; benches assert it is no less safe than ReleaseFast." diff --git a/demo/0.1-AI-MANIFEST.a2ml b/demo/0.1-AI-MANIFEST.a2ml new file mode 100644 index 0000000..b48db4f --- /dev/null +++ b/demo/0.1-AI-MANIFEST.a2ml @@ -0,0 +1,22 @@ +# SPDX-License-Identifier: MPL-2.0 +--- +### [META] +id: "demo" +level: 1 +parent: "../0-AI-MANIFEST.a2ml" + +--- +### [AI_MANIFEST] +description: | + In-BEAM demonstrator. An Elixir/Mix application (snif_demo) that loads SNIF + guest wasm via wasmex and exercises crash-isolation: a guest trap returns + {:error, _} and the BEAM survives. + +canonical_locations: + application: "lib/snif_demo/" + tests: "test/" + bench: "bench/snif_bench.exs" + +invariants: + - "NEVER use raw NIFs here; guests load only through the SNIF/wasmex path." + - "Guest wasm under priv/ is a build artifact (gitignored); regenerate via the build recipes." diff --git a/docs/templates/0.2-AI-MANIFEST.a2ml b/docs/templates/0.2-AI-MANIFEST.a2ml new file mode 100644 index 0000000..2ea33e3 --- /dev/null +++ b/docs/templates/0.2-AI-MANIFEST.a2ml @@ -0,0 +1,18 @@ +# SPDX-License-Identifier: MPL-2.0 +--- +### [META] +id: "templates" +level: 2 +parent: "../0.1-AI-MANIFEST.a2ml" + +--- +### [AI_MANIFEST] +description: | + Template assets for the repository. contractiles/ holds the must/trust/bust/dust + contractile templates and their README. + +canonical_locations: + contractiles: "contractiles/" + +invariants: + - "These are template copies; the load-bearing contractiles the Mustfile checks live under .machine_readable/contractiles/." diff --git a/rust-guest/0.1-AI-MANIFEST.a2ml b/rust-guest/0.1-AI-MANIFEST.a2ml new file mode 100644 index 0000000..175fc08 --- /dev/null +++ b/rust-guest/0.1-AI-MANIFEST.a2ml @@ -0,0 +1,20 @@ +# SPDX-License-Identifier: MPL-2.0 +--- +### [META] +id: "rust-guest" +level: 1 +parent: "../0-AI-MANIFEST.a2ml" + +--- +### [AI_MANIFEST] +description: | + Standalone single-crate Rust wasm32 guest example. Sibling to the workspace + member rust/crates/demo-guest; the dual-source relationship is tracked for + reconciliation in the Dustfile (kept-for-now, not yet collapsed). + +canonical_locations: + guest_source: "src/lib.rs" + readme: "README.adoc" + +invariants: + - "wasm32 guest only; mirrors the demo-guest crate's exported surface." diff --git a/rust/0.1-AI-MANIFEST.a2ml b/rust/0.1-AI-MANIFEST.a2ml new file mode 100644 index 0000000..0ed4cf7 --- /dev/null +++ b/rust/0.1-AI-MANIFEST.a2ml @@ -0,0 +1,23 @@ +# SPDX-License-Identifier: MPL-2.0 +--- +### [META] +id: "rust" +level: 1 +parent: "../0-AI-MANIFEST.a2ml" + +--- +### [AI_MANIFEST] +description: | + Cargo workspace for the Rust wasm32 guests and the shared ABI crate. Compiled + to wasm32 and run as SNIF guests; no host-native Rust ships. + +canonical_locations: + abi_crate: "crates/snif-abi/" + logic_crate: "crates/snif-logic/" + demo_guest: "crates/demo-guest/" + build: "build-wasm.sh" + supply_chain: "deny.toml" + +invariants: + - "Guests compile to wasm32 only; no host-native Rust artifacts are shipped." + - "Sibling single-crate guest lives in ../rust-guest/ (dual-source tracked in the Dustfile)." diff --git a/zig/0.1-AI-MANIFEST.a2ml b/zig/0.1-AI-MANIFEST.a2ml new file mode 100644 index 0000000..926dfb3 --- /dev/null +++ b/zig/0.1-AI-MANIFEST.a2ml @@ -0,0 +1,23 @@ +# SPDX-License-Identifier: MPL-2.0 +--- +### [META] +id: "zig" +level: 1 +parent: "../0-AI-MANIFEST.a2ml" + +--- +### [AI_MANIFEST] +description: | + Zig source for the SNIF guest: the safe-NIF kernel, the multi-value buffer + ABI, and the burble FFT. Compiled to wasm32-freestanding -OReleaseSafe. + +canonical_locations: + safe_nif: "src/safe_nif.zig" + buffer_abi: "src/buffer_abi.zig" + burble_fft: "src/burble_fft.zig" + build: "build.zig" + buffer_abi_build: "buffer_abi_build.sh" + +invariants: + - "Guests target wasm32-freestanding; ReleaseSafe is the trust baseline (traps, not UB)." + - "buffer_abi_build/ is a build artifact (gitignored)." From 9092f0c67c37e15b4c259ac4c5b9a41be86518d3 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 16 Jun 2026 18:16:52 +0100 Subject: [PATCH 04/11] docs: bring README/EXPLAINME to the authoring standard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README: add the required :toc: preamble + :icons: font header attributes and a Documentation section linking EXPLAINME/PROOF-STATUS/CONTRIBUTING/SECURITY/CHANGELOG/paper. EXPLAINME: add the two required sections it lacked — a Dogfooded-Across-The-Account table (Idris2 ABI proofs, Zig wasm32 guests, --safe Agda; cross-referenced to bag-of-actions/proven/gossamer/echo-types) and an honest Known-gaps section (SEC-1 TCB boundary, ABI 15/20, dual-sourced Rust guest). Co-Authored-By: Claude Opus 4.8 (1M context) --- EXPLAINME.adoc | 43 +++++++++++++++++++++++++++++++++++++++++++ README.adoc | 11 +++++++++++ 2 files changed, 54 insertions(+) diff --git a/EXPLAINME.adoc b/EXPLAINME.adoc index 8c8eb9f..1640b21 100644 --- a/EXPLAINME.adoc +++ b/EXPLAINME.adoc @@ -78,3 +78,46 @@ ambition lives in groove/cleave, not here. | `verification/proofs/agda/SnifVerdict.agda` | Residue-clean (deniability) + non-forgery at the boundary. | `verification/tools/abi_conformance.py` | Model↔binary ABI drift gate (interface-level). |=== + +== Dogfooded Across The Account + +[cols="1,2,2", options="header"] +|=== +| Technology / Pattern | Used here | Also used in + +| Idris2 ABI / capability proofs +| `verification/proofs/idris2/ABI/` models each guest's export signature; the conformance gate fails on model↔binary drift. +| link:https://github.com/hyperpolymath/bag-of-actions[bag-of-actions] (capability `Protocol.idr`), link:https://github.com/hyperpolymath/proven[proven] (Idris2 proven-library) + +| Zig → wasm32-freestanding (`-OReleaseSafe`) guests +| The SNIF kernel (`zig/src/safe_nif.zig`) compiles to a trapping wasm guest — UB becomes a trap, not a silent wrong answer. +| link:https://github.com/hyperpolymath/bag-of-actions[bag-of-actions] (`estate.zig` FFI), link:https://github.com/hyperpolymath/gossamer[gossamer] (Zig ABI) + +| `--safe` machine-checked proofs +| SEC-1 crash-isolation is mechanised in `--safe --without-K` Agda (`SnifIsolation.agda`). +| link:https://github.com/hyperpolymath/echo-types[echo-types] (loss-with-residue, constructive Agda) +|=== + +== Known gaps + +[CAUTION] +==== +*SEC-1 is proven modulo an explicit TCB.* The crash-isolation theorem holds +relative to the `FaithfulRuntime` record hypothesis (the wasmtime/wasmex runtime +behaves as modelled). This is an honest assumption boundary, not a postulate — +see `PROOF-STATUS.md` for the trusted-base statement. +==== + +[CAUTION] +==== +*ABI conformance gates 15 of ~20 Zig export sites.* `buffer_abi` is fully +modelled (7/7); `safe_nif` coverage is partial. Tracked in `PROOF-NEEDS.md` +(ABI-7). +==== + +[CAUTION] +==== +*The Rust→wasm32 guest path is wired but dual-sourced.* `rust/crates/demo-guest` +(workspace) and `rust-guest/` (standalone) are not yet reconciled; the +exit/keep decision is recorded in the repo's Dustfile. +==== diff --git a/README.adoc b/README.adoc index a10b8f5..e8cad00 100644 --- a/README.adoc +++ b/README.adoc @@ -3,6 +3,8 @@ // SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell = SNIFs: Safer Native Implemented Functions for the BEAM via WebAssembly Sandboxing +:toc: preamble +:icons: font image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/snifs"] image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] @@ -178,6 +180,15 @@ Requires Zig 0.15+. `docs/whitepapers/academic/snif.pdf` — also available on Zenodo (DOI pending). +== Documentation + +* link:EXPLAINME.adoc[EXPLAINME] — claim-to-implementation evidence and honest caveats. +* link:PROOF-STATUS.md[Proof status] — what is proven, what is tested, what is trusted. +* link:CONTRIBUTING.md[Contributing] +* link:SECURITY.md[Security policy] +* link:CHANGELOG.md[Changelog] +* link:docs/whitepapers/academic/snif.pdf[Paper (PDF)] + == License This project is licensed under the Mozilla Public License, v. 2.0. See the `LICENSE` file for details. From d2f7f3bd8e2f491b6e7e925856377a28c60c55d4 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 16 Jun 2026 18:33:36 +0100 Subject: [PATCH 05/11] docs: de-template root manifest, QUICKSTARTs, and contractiles README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The root 0-AI-MANIFEST.a2ml and the three QUICKSTART-*.adoc files still carried RSR-template placeholders (rsr-template-repo, {{LANG_STACK}}, {{BUILD_CMD}}, and phantom recipes like `just setup`/`heal`/`panic-scan`/ `stapeln-*`). Replace with snifs-specific content using only recipes that actually exist (verified against `just --list`): build-wasm, assail, container-build, proof-check-all, abi-conformance, etc. Reframe the three role quickstarts around snifs's real flows (run the demo / contribute / cut a release) and drop the inapplicable app install/uninstall/heal/ multi-tenant scaffolding. Fix the load-bearing .machine_readable/contractiles/README.adoc stale names (Trustfile.hs, lust/Intentfile) to the files actually present (Trustfile.a2ml, Adjustfile.a2ml, Intentfile.a2ml, bust/, dust/) and drop the "copy into a new repo" framing — this is the real load-bearing instance, not the template (that lives in docs/templates/contractiles/). Co-Authored-By: Claude Opus 4.8 (1M context) --- .machine_readable/contractiles/README.adoc | 49 ++++++-- 0-AI-MANIFEST.a2ml | 55 ++++++--- QUICKSTART-DEV.adoc | 95 ++++++++-------- QUICKSTART-MAINTAINER.adoc | 125 +++++++-------------- QUICKSTART-USER.adoc | 123 ++++++-------------- 5 files changed, 194 insertions(+), 253 deletions(-) diff --git a/.machine_readable/contractiles/README.adoc b/.machine_readable/contractiles/README.adoc index 2b8aed7..523b3c6 100644 --- a/.machine_readable/contractiles/README.adoc +++ b/.machine_readable/contractiles/README.adoc @@ -1,21 +1,46 @@ // SPDX-License-Identifier: MPL-2.0 // Copyright (c) Jonathan D.A. Jewell -= Contractiles Template Set += snifs Contractiles (Load-Bearing) :toc: :sectnums: -This directory contains the generalized contractiles templates. Copy the `.machine_readable/contractiles/` directory into a new repo to establish a consistent operational, validation, trust, recovery, and intent framework. +This directory holds the **load-bearing** contractiles for snifs — the operational, +validation, trust, recovery, intent, and adjustment contracts that the `Mustfile` +checks and that CI / the pre-commit hook enforce. These are the real instances, not +templates; blank templates live under `docs/templates/contractiles/`. -== Fill-In Instructions +== Contents -1. Update the Mustfile to reflect your real invariants (paths, schema versions, ports). -2. Replace Trustfile.hs placeholders with your actual key paths and verification commands. -3. Adjust Dustfile handlers to match your rollback and recovery tooling. -4. Update Intentfile to mirror the roadmap you want the system to evolve toward. +[cols="1,3", options="header"] +|=== +| File | Role -== Contents +| `Mustfile.a2ml` +| Required physical-state invariants and validations (hard requirements — CI and the + pre-commit hook fail if any check fails). + +| `Trustfile.a2ml` +| Cryptographic verification steps (signing keys, commit-verification posture). + +| `Adjustfile.a2ml` +| Moving-adjustment posture — the live floor that graduates toward `Mustfile`. + +| `Intentfile.a2ml` +| Declared future intent and roadmap direction. + +| `bust/Bustfile.a2ml` +| Design aetiology → causal help/error/removal scripts (not bandaids). + +| `dust/Dustfile.a2ml` +| Exnovation, rollback, and recovery semantics. + +| `Justfile` +| Contractile task runner (drives `must check`, `bust`, `dust`, etc.). +|=== + +== Notes -* `must/Mustfile` - required invariants and validations. -* `trust/Trustfile.hs` - cryptographic verification steps. -* `dust/Dustfile` - rollback and recovery semantics. -* `lust/Intentfile` - future intent and roadmap direction. +* The canonical estate contractile layout is the per-verb subdir trident master in + `hyperpolymath/standards`; this directory tracks snifs's current realized set. +* Changing a `Mustfile` check changes what CI enforces — treat edits here as + load-bearing, not cosmetic. diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml index 485c907..d3369b8 100644 --- a/0-AI-MANIFEST.a2ml +++ b/0-AI-MANIFEST.a2ml @@ -1,14 +1,26 @@ -# RSR Template AI Manifest (Read First) +# SPDX-License-Identifier: MPL-2.0 +# Owner: Jonathan D.A. Jewell -This is the root AI manifest for the template repository. +# snifs — Root AI Manifest (Read First) -## Template Status +This is the root AI manifest for **snifs** — *Safer Native Implemented Functions* +for the BEAM via WebAssembly sandboxing. snifs keeps the NIF *interface* (call a +native-implemented function, get a value) but sandboxes the *implementation*: the +guest is compiled to `wasm32-freestanding` (Zig and Rust today) and run under +`wasmtime` via `wasmex`, so a guest fault becomes a catchable `{:error, reason}` +tuple and the calling BEAM process survives. -This repository intentionally contains template placeholders before bootstrap. -Examples: `hyperpolymath`, `snif`, `{{PROJECT_NAME}}`, `[YOUR-REPO-NAME]`. +This repository is **bootstrapped** (not a template). It contains no +`{{PLACEHOLDER}}` tokens; treat every path and command below as real. -Do not invent project-specific values unless the operator runs template -initialization (for example `just init`) or explicitly provides values. +## What snifs is (and is not) + +- snifs realizes a residue-clean cleave **instance** at one boundary (BEAM host ↔ + native guest). It is *an* instance of a cleave, not "the cleave". The graduated + integration / capability-negotiation ambition lives in the separate *cleave* and + *groove* layers, not here (see `EXPLAINME.adoc`). +- Scope ceiling by design: SNIF stops at NIF-parity + crash-isolation. It does not + extend the NIF interface. ## Authority Split @@ -41,21 +53,30 @@ initialization (for example `just init`) or explicitly provides values. 1. Keep protocol text centralized; do not duplicate full protocol specs here. 2. Keep local policy and hook behavior local to this repo. 3. Write runtime session artifacts in working repos (typically `.session/`). -4. Keep README/AUDIT/manifest claims synchronized with actual files. -5. Mark stubs and placeholders explicitly. +4. Keep README/EXPLAINME/AUDIT/manifest claims synchronized with actual files. +5. Always compile Zig WASM guests with `-OReleaseSafe` (`ReleaseFast` turns faults + into silent wrong answers — the negative control). +6. NEVER use raw NIFs (`erlang:load_nif`); the whole point of this repo is to not + need them. ## Key Local Files +- `README.adoc` (orientation, scope, benchmarks) +- `EXPLAINME.adoc` (claim-to-implementation map + honest caveats) - `AUDIT.adoc` (local audit gate summary) -- `README.adoc` (template orientation) -- `EXPLAINME.adoc` (claim-to-implementation map) -- `session/README.md` (session-binding usage) -- `.machine_readable/` (machine-readable repo policy/state files) +- `PROOF-STATUS.md` / `PROOF-NEEDS.md` (what is proven, what is tested, what is owed) +- `zig/src/safe_nif.zig` (the SNIF kernel — trapped failure modes) +- `demo/` (Mix project: wasmex loader + ExUnit crash-isolation suite) +- `verification/proofs/` (Idris2 / Lean4 / Agda proof artifacts) +- `verification/tools/abi_conformance.py` (model↔binary ABI drift gate) +- `session/README.adoc` (session-binding usage) +- `.machine_readable/` (machine-readable repo policy/state + contractiles) ## Startup Checklist For Agents -1. Read `0-AI-MANIFEST.a2ml`. -2. Read `AUDIT.adoc`. -3. Confirm whether placeholders have been initialized. +1. Read `0-AI-MANIFEST.a2ml` (this file). +2. Read `README.adoc`, then `EXPLAINME.adoc`, then `AUDIT.adoc`. +3. Read `PROOF-STATUS.md` before making any claim about what is proven. 4. Use canonical session commands through `session/dispatch.sh` or Just aliases. -5. Avoid claiming files/paths exist unless verified in this repository. +5. Do not claim files/paths/recipes exist unless verified in this repository + (`just --list` for recipes). diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc index 02957ea..0a7f5e5 100644 --- a/QUICKSTART-DEV.adoc +++ b/QUICKSTART-DEV.adoc @@ -1,112 +1,107 @@ // SPDX-License-Identifier: MPL-2.0 // Copyright (c) Jonathan D.A. Jewell -// Template: QUICKSTART-DEV.adoc — clone → build → test → PR -// Replace rsr-template-repo, {{BUILD_CMD}}, {{TEST_CMD}}, {{LANG_STACK}} with actuals -= rsr-template-repo — Quick Start for Developers += snifs — Quick Start for Developers :toc: :toclevels: 2 == Tech Stack -{{LANG_STACK}} +* **Host**: Elixir / BEAM (OTP 25+), `wasmex` → `wasmtime` sandbox. +* **Guests**: Zig and Rust compiled to `wasm32-freestanding` (`-OReleaseSafe`). +* **Proofs**: Idris2 (ABI + capability), Lean4 (API), Agda (`--safe --without-K` + crash-isolation + verdict). +* **Tooling**: `just` task runner; Guix/Nix dev shells; `panic-attacker` security scan. -== Set Up Development Environment +== Set Up the Development Environment === Option A: Guix (preferred) [source,bash] ---- -guix shell +just guix-shell ---- === Option B: Nix (fallback) [source,bash] ---- -nix develop +just nix-shell ---- === Option C: Manual [source,bash] ---- -git clone https://github.com/hyperpolymath/rsr-template-repo.git -cd rsr-template-repo -just setup-dev +git clone https://github.com/hyperpolymath/snifs.git +cd snifs +just deps # install / check toolchain dependencies ---- -== Build +== Build & Test [source,bash] ---- -{{BUILD_CMD}} +just build-wasm # compile the Zig/Rust guests to priv/*.wasm (ReleaseSafe) +cd demo && mix deps.get && mix test # 21/21 ExUnit crash-isolation suite ---- -== Test +== Check the Proofs [source,bash] ---- -{{TEST_CMD}} +just proof-check-all # Idris2 ABI + Lean4 API + Agda SEC-1 + dangerous-pattern scan +just abi-conformance # model ↔ shipped-binary ABI drift gate (required check) +just proof-status # summary of proven / tested / trusted ---- == Project Structure [source] ---- -rsr-template-repo/ -├── src/ # Source code -├── src/abi/ # Idris2 ABI definitions (if applicable) -├── ffi/zig/ # Zig FFI bridge (if applicable) -├── tests/ # Test suite -├── docs/ # Documentation -├── .machine_readable/ # Checkpoint files (STATE, META, ECOSYSTEM) -├── Justfile # Task runner recipes -├── guix.scm # Guix environment -├── flake.nix # Nix environment (fallback) -└── 0-AI-MANIFEST.a2ml # AI agent entry point +snifs/ +├── zig/src/safe_nif.zig # the SNIF kernel — six trapped crash modes +├── zig/ # safe_nif / buffer_abi / burble_fft guests +├── rust/ , rust-guest/ # Rust→wasm32 guests (dual-sourced; see Dustfile) +├── demo/ # Mix project: wasmex loader + ExUnit suite +├── verification/proofs/ # Idris2 / Lean4 / Agda proof artifacts +├── verification/tools/ # abi_conformance.py and friends +├── benches/ # benchmark harness +├── docs/ # paper, ADRs, proof/tech-debt ledgers +├── .machine_readable/ # 6a2 checkpoint files + load-bearing contractiles +├── Justfile # task runner recipes +└── 0-AI-MANIFEST.a2ml # AI agent entry point ---- == Key Recipes [source,bash] ---- -just build # Build the project -just test # Run tests -just doctor # Self-diagnostic -just lint # Lint and format -just panic-scan # Security scan via panic-attacker -just tour # Guided tour of the codebase +just build-wasm # Build the WASM guests +just test # Run the host test suite (alias for the demo suite) +just doctor # Self-diagnostic +just lint # Lint +just fmt # Format all source files +just assail # panic-attacker pre-commit security scan +just tour # Guided tour of the codebase ---- == Before Submitting a PR [source,bash] ---- -just lint # Format and lint -just test # All tests pass -just panic-scan # No new security issues +just quality # fmt-check + lint + test +just proof-check-all # all proofs still check +just assail # no new security findings ---- -== Contractile Invariants +Commits must be **signed**. See `CONTRIBUTING.md` for the signing-key policy. -Read `.machine_readable/MUST.contractile` before making changes. -Key invariants that must never be violated: +== LLM / AI Agent Development -{{MUST_INVARIANTS}} - -== LLM/AI Agent Development - -If using an AI assistant, load the warmup context first: - -[source,bash] ----- -just llm-context # Outputs role-appropriate context ----- - -Or read `0-AI-MANIFEST.a2ml` and `.claude/CLAUDE.md` directly. +Read `0-AI-MANIFEST.a2ml` and `.claude/CLAUDE.md` first, then `PROOF-STATUS.md` +before making any claim about what is proven. == Get Help * **Architecture**: link:EXPLAINME.adoc[EXPLAINME.adoc] -* **Wiki**: https://github.com/hyperpolymath/rsr-template-repo/wiki * **Report issue**: `just help-me` diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index b42ffd3..1cc56fd 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -1,130 +1,83 @@ // SPDX-License-Identifier: MPL-2.0 // Copyright (c) Jonathan D.A. Jewell -// Template: QUICKSTART-MAINTAINER.adoc — packaging, deploying, and maintaining -// Replace rsr-template-repo, {{PACKAGE_NAME}}, {{DEPS}} with actuals -= rsr-template-repo — Quick Start for Platform Maintainers += snifs — Quick Start for Maintainers :toc: :toclevels: 2 == Overview -This guide covers packaging, deploying, and maintaining rsr-template-repo for -distribution on your platform. +This guide covers building, verifying, packaging, and releasing snifs. snifs is a +research + reference repository (paper + BEAM/WASM implementation + proofs), so +"release" means: green proofs and tests, a rebuilt paper, a signed container bundle, +and a tagged version on Zenodo — not shipping an installable end-user application. == Runtime Dependencies -{{DEPS}} +* Elixir 1.15+ on OTP 25+ (host); `wasmex` → `wasmtime` (sandbox). +* Zig 0.15+ and a Rust→wasm32 toolchain (to rebuild guests). +* Idris2 / Lean4 / Agda (to re-check proofs); `just`; Guix or Nix. == Build from Source [source,bash] ---- -git clone https://github.com/hyperpolymath/rsr-template-repo.git -cd rsr-template-repo -just build-release +git clone https://github.com/hyperpolymath/snifs.git +cd snifs +just build-wasm # guests → priv/*.wasm (ReleaseSafe) +just build-release # release build ---- -Output: `{{BUILD_OUTPUT_PATH}}` - -== Packaging - -=== Guix - -[source,bash] ----- -guix build -f guix.scm ----- - -=== Nix +== Pre-Release Gate [source,bash] ---- -nix build +just quality # fmt-check + lint + test +just proof-check-all # all proofs check +just abi-conformance # model ↔ binary ABI drift gate +just assail # panic-attacker security scan +just deps-audit # dependency vulnerability audit +just sbom # generate the software bill of materials ---- -=== Container (Stapeln) +== The Paper [source,bash] ---- -just stapeln-export # Generates Containerfile -podman build -t rsr-template-repo . +just paper # build docs/whitepapers/academic/snif.pdf ---- -=== Manual Package +== Container (cerro-torre pipeline) [source,bash] ---- -just install --prefix=/usr/local +just container-build # build the image +just container-verify # verify the compose configuration +just container-sign # build + pack + sign + verify the bundle +just container-push # push the signed bundle to the registry ---- -Files installed: - -[cols="1,2"] -|=== -| Path | Contents - -| `$PREFIX/bin/` -| Executables - -| `$PREFIX/share/{{PACKAGE_NAME}}/` -| Data files, assets - -| `$PREFIX/share/doc/{{PACKAGE_NAME}}/` -| Documentation - -| `$PREFIX/share/applications/` -| .desktop file (Linux, if GUI) - -| `$PREFIX/share/man/man1/` -| Man pages -|=== - -== Configuration +The container build keys off the repo-root `Containerfile`; the +`dogfood-gate` workflow checks for it there — do not relocate it. -Default config location: `$XDG_CONFIG_HOME/{{PACKAGE_NAME}}/config.toml` - -Fallback: `$HOME/.config/{{PACKAGE_NAME}}/config.toml` - -== Health Checks - -[source,bash] ----- -just doctor # Full diagnostic -just run --version # Version check -just run --selftest # Built-in self-test ----- - -== Updating +== Cutting a Release [source,bash] ---- -git pull -just build-release -just install --prefix=/usr/local +just changelog-preview # preview unreleased changelog entries (no write) +just changelog # generate CHANGELOG.md with git-cliff +just release-tag ---- -Or via OPSM: `opsm update {{PACKAGE_NAME}}` +Tags and the Zenodo DOI are how downstream consumers cite a fixed version (see the +`Citation` block in `README.adoc`). == Security Notes -* License: MPL-2.0 (Palimpsest License) -* All dependencies SHA-pinned -* `panic-attacker` scan results: link:INSTALL-SECURITY-REPORT.adoc[] -* OpenSSF Scorecard: see badge in README - -== Multi-Instance Deployment - -For deploying multiple instances (e.g., different users or tenants): - -[source,bash] ----- -just install --prefix=/opt/{{PACKAGE_NAME}}-instance1 --config=/etc/{{PACKAGE_NAME}}/instance1.toml -just install --prefix=/opt/{{PACKAGE_NAME}}-instance2 --config=/etc/{{PACKAGE_NAME}}/instance2.toml ----- - -Each instance has isolated config, data, and logs. +* License: MPL-2.0. +* Dependencies SHA-pinned; `just deps-audit` + `just sbom` gate each release. +* Security policy and disclosure process: link:SECURITY.md[SECURITY.md]. == Reporting Issues -* Upstream: https://github.com/hyperpolymath/rsr-template-repo/issues -* With diagnostic: `just help-me` (pre-fills context) +* Upstream: https://github.com/hyperpolymath/snifs/issues +* With diagnostic context: `just help-me` diff --git a/QUICKSTART-USER.adoc b/QUICKSTART-USER.adoc index 4992e32..74361fb 100644 --- a/QUICKSTART-USER.adoc +++ b/QUICKSTART-USER.adoc @@ -1,125 +1,72 @@ // SPDX-License-Identifier: MPL-2.0 // Copyright (c) Jonathan D.A. Jewell -// Template: QUICKSTART-USER.adoc — 5-minute path to working software -// Replace rsr-template-repo, Rsr Template Repo — See README.adoc for details., just run, Rsr Template Repo started successfully. with actuals -= rsr-template-repo — Quick Start for Users += snifs — Quick Start for Users :toc: :toclevels: 2 -== What is rsr-template-repo? +== What is snifs? -Rsr Template Repo — See README.adoc for details. +snifs — *Safer Native Implemented Functions* — gives the BEAM crash-isolated native +interfaces. A normal NIF runs native code *inside* the VM's address space, so any +fault (out-of-bounds access, overflow, `@panic`) kills the entire BEAM VM. A SNIF +keeps the NIF's *interface* but compiles the guest to WebAssembly (Zig and Rust +today) and runs it under `wasmtime` via `wasmex`, so a guest fault becomes a +catchable `{:error, reason}` tuple and the calling process survives. -== Prerequisites +This is a research + reference repository (the SNIF architecture paper, a working +BEAM + WASM implementation, integration tests, and formal-verification artifacts) — +not a standalone installable application. The fastest way to "use" snifs is to run +the demo and watch the BEAM survive a guest crash. -Before you begin, ensure you have: +== Prerequisites * **just** — task runner (https://github.com/casey/just[install guide]) -* Platform-specific requirements listed below - -[cols="1,3"] -|=== -| Platform | Additional Requirements - -| Linux -| See README.adoc - -| macOS -| See README.adoc +* **Elixir 1.15+** on **OTP 25+** (the precompiled `wasmex` `nif-2.15` artifact loads + on OTP 25 through 28) +* **Zig 0.15+** — only if you want to rebuild the `.wasm` guests yourself + (pre-built binaries ship in `priv/`) -| Windows -| See README.adoc -|=== - -== Install - -=== Option 1: Standard Install (recommended) +== Run the demo [source,bash] ---- -# Clone and set up -git clone https://github.com/hyperpolymath/rsr-template-repo.git -cd rsr-template-repo -just setup +git clone https://github.com/hyperpolymath/snifs.git +cd snifs/demo +mix deps.get +mix test ---- -The setup script will: - -* Detect your platform and shell -* Install missing dependencies (with your permission) -* Configure the application -* Offer install location choices -* Run a self-diagnostic to verify everything works - -=== Option 2: Container (via Stapeln) - -[source,bash] ----- -just stapeln-run ----- - -=== Option 3: Portable (no system changes) - -[source,bash] ----- -just install --portable --prefix=./rsr-template-repo-portable ----- +The ExUnit suite triggers every guest failure mode — out-of-bounds, `@panic`, +overflow, divide-by-zero — and asserts that each returns `{:error, _}` while the +caller process stays alive. That is crash isolation, demonstrated. -== First Run +== Rebuild the WASM guests (optional) [source,bash] ---- -just run +just build-wasm ---- -Expected output: +Always built with `-OReleaseSafe`; `ReleaseFast` turns the same faults into silent +wrong answers and is kept only as a negative control. -[source] ----- -Rsr Template Repo started successfully. ----- - -== Self-Diagnostic +== Self-diagnostic If something isn't working: [source,bash] ---- -just doctor ----- - -This checks all dependencies, permissions, paths, and connectivity. -If it finds issues, it will suggest fixes. - -To attempt automatic repair: - -[source,bash] ----- -just heal +just doctor # checks dependencies, permissions, paths ---- == Get Help -* **In-app**: `just run --help` +* **Architecture & evidence**: link:EXPLAINME.adoc[EXPLAINME] +* **What is proven vs tested vs trusted**: link:PROOF-STATUS.md[PROOF-STATUS] * **Guided tour**: `just tour` * **Report a problem**: `just help-me` (pre-fills diagnostic context) -* **Wiki**: https://github.com/hyperpolymath/rsr-template-repo/wiki - -== Uninstall - -[source,bash] ----- -just uninstall ----- - -You will be asked: - -1. Which uninstall tier (Bennett reversible, parameter-based, standard, or secure) -2. Whether to include or exclude your data -3. Whether to clear caches and LLM models == Next Steps -* Read the link:README.adoc[README] for full feature overview -* Read the link:EXPLAINME.adoc[EXPLAINME] for architecture and design decisions -* Try `just tour` for a guided walkthrough +* Read the link:README.adoc[README] for scope, benchmarks, and the honesty boundary. +* Read the paper: `docs/whitepapers/academic/snif.pdf` (also on Zenodo). From 669206bf8f61eb691eb498945918431eb0bedc52 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 16 Jun 2026 18:48:57 +0100 Subject: [PATCH 06/11] docs: convert proof-debt/tech-debt/session-README to AsciiDoc; relocate invariants scan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Estate DOC-FORMAT rule + the docs/ pillar manifest both require AsciiDoc as the primary documentation format ("if .adoc exists, don't also have .md"). Convert three lingering .md docs to .adoc: docs/proof-debt.md -> docs/proof-debt.adoc docs/tech-debt-2026-05-26.md -> docs/tech-debt-2026-05-26.adoc session/README.md -> session/README.adoc Markdown -> AsciiDoc (headings, lists, tables, listing blocks, links) and the SPDX comment delimiter -> //. The new .adoc files carry the full owner SPDX + literal owner string the pre-commit hook requires (the source .md SPDX-FileCopyrightText used the "(hyperpolymath)" form, not the <…@open.ac.uk> form the hook greps for). Fix the one inbound reference (tech-debt -> proof-debt) to the new .adoc path. Relocate the tracked README.adoc.invariants.md (an Invariant-Path scan output) out of the repo root into verification/, where verification tooling output belongs. No content change; zero inbound references. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/proof-debt.adoc | 56 +++++++++++++ docs/proof-debt.md | 58 -------------- docs/tech-debt-2026-05-26.adoc | 78 +++++++++++++++++++ docs/tech-debt-2026-05-26.md | 72 ----------------- session/README.adoc | 45 +++++++++++ session/README.md | 46 ----------- .../README.adoc.invariants.md | 0 7 files changed, 179 insertions(+), 176 deletions(-) create mode 100644 docs/proof-debt.adoc delete mode 100644 docs/proof-debt.md create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 session/README.adoc delete mode 100644 session/README.md rename README.adoc.invariants.md => verification/README.adoc.invariants.md (100%) diff --git a/docs/proof-debt.adoc b/docs/proof-debt.adoc new file mode 100644 index 0000000..5f8865a --- /dev/null +++ b/docs/proof-debt.adoc @@ -0,0 +1,56 @@ +// SPDX-License-Identifier: MPL-2.0 +// Owner: Jonathan D.A. Jewell +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += Proof Debt — snifs +:toc: + +*Schema*: link:https://github.com/hyperpolymath/standards/blob/main/docs/TRUSTED-BASE-REDUCTION-POLICY.adoc[hyperpolymath/standards `TRUSTED-BASE-REDUCTION-POLICY.adoc`] (standards#203). + +== Current state + +*Zero soundness-relevant escape hatches* in this repo as of 2026-05-26. + +Verified by `scripts/check-trusted-base.sh` from +link:https://github.com/hyperpolymath/standards[hyperpolymath/standards] — +all matches found by syntactic scan were inside docstrings explicitly +stating the file does NOT use `believe_me` / `assert_total` / +`postulate` / `sorry` / `Admitted` (the "no escape hatches" +discipline pattern). + +== (a) DISCHARGED in this repo + +_(None — never any to discharge.)_ + +== (b) BUDGETED — tested with a refutation budget + +_(None.)_ + +== (c) NECESSARY AXIOM + +_(None.)_ + +== (d) DEBT — actively to be closed + +_(None.)_ + +== Preservation contract + +This file exists to assert the *zero-debt invariant* for the +`scripts/check-trusted-base.sh` CI gate (standards#211). Any future PR +that introduces a soundness-relevant escape hatch MUST either: + +. annotate the call site with a leading `TRUSTED:` / `AXIOM:` + comment, OR +. add an entry to this file under §(b) / §(c) / §(d). + +PRs that introduce un-annotated escape hatches will fail CI. + +== Companion documents + +* link:https://github.com/hyperpolymath/standards/pull/195[standards#195] — estate proof-debt audit. +* link:https://github.com/hyperpolymath/standards/pull/203[standards#203] — trusted-base reduction policy (the schema this file follows). +* link:https://github.com/hyperpolymath/standards/pull/211[standards#211] — `check-trusted-base.sh` CI enforcement. + +''' + +🤖 Initial seed by Claude Code, 2026-05-26. diff --git a/docs/proof-debt.md b/docs/proof-debt.md deleted file mode 100644 index 70175f3..0000000 --- a/docs/proof-debt.md +++ /dev/null @@ -1,58 +0,0 @@ - -SPDX-License-Identifier: MPL-2.0 -SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) ---> - -# Proof Debt — snifs - -**Schema**: [hyperpolymath/standards `TRUSTED-BASE-REDUCTION-POLICY.adoc`](https://github.com/hyperpolymath/standards/blob/main/docs/TRUSTED-BASE-REDUCTION-POLICY.adoc) (standards#203). - -## Current state - -**Zero soundness-relevant escape hatches** in this repo as of 2026-05-26. - -Verified by `scripts/check-trusted-base.sh` from -[hyperpolymath/standards](https://github.com/hyperpolymath/standards) — -all matches found by syntactic scan were inside docstrings explicitly -stating the file does NOT use `believe_me` / `assert_total` / -`postulate` / `sorry` / `Admitted` (the "no escape hatches" -discipline pattern). - -## (a) DISCHARGED in this repo - -*(None — never any to discharge.)* - -## (b) BUDGETED — tested with a refutation budget - -*(None.)* - -## (c) NECESSARY AXIOM - -*(None.)* - -## (d) DEBT — actively to be closed - -*(None.)* - -## Preservation contract - -This file exists to assert the **zero-debt invariant** for the -`scripts/check-trusted-base.sh` CI gate (standards#211). Any future PR -that introduces a soundness-relevant escape hatch MUST either: - -1. annotate the call site with a leading `TRUSTED:` / `AXIOM:` - comment, OR -2. add an entry to this file under §(b) / §(c) / §(d). - -PRs that introduce un-annotated escape hatches will fail CI. - -## Companion documents - -- [standards#195](https://github.com/hyperpolymath/standards/pull/195) — estate proof-debt audit. -- [standards#203](https://github.com/hyperpolymath/standards/pull/203) — trusted-base reduction policy (the schema this file follows). -- [standards#211](https://github.com/hyperpolymath/standards/pull/211) — `check-trusted-base.sh` CI enforcement. - ---- - -🤖 Initial seed by Claude Code, 2026-05-26. diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..37108c9 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,78 @@ +// SPDX-License-Identifier: MPL-2.0 +// Owner: Jonathan D.A. Jewell +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += Tech-Debt Audit — snifs — 2026-05-26 +:toc: + +*Source:* estate-wide automated scan 2026-05-26. + +*Companion:* link:https://github.com/hyperpolymath/standards/tree/main/docs/audits[`hyperpolymath/standards` 2026-05-26-estate-*-debt audits]. + +*Combined severity:* `LOW`. + +This file records the _raw findings_ — it does not by itself fix the debt. Each +section ends with a 'Recommended next move' line; closing the debt is follow-up work. + +== 1. Proof debt + +Scanner counted the following markers in proof-bearing files of this repo: + +---- +files= 13 | Coq-Axm/Adm= 0 | Lean-srry/ax= 1 | Agda-pst= 0 | Idr-blv= 6 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 +---- + +*Total markers:* 7. *Severity:* `>07`. + +*Marker types* (any non-zero counts above): + +* Coq `Axiom`/`Admitted` — unconditional proof escapes. +* Lean `sorry`/`axiom` — Lean's equivalent. +* Agda `postulate` — accepted axiomatically. +* Idris2 `believe_me`/`assert_total` — runtime-safe coercion / totality assumption. +* Idris2 top-level `partial` — totality-check waived. +* F\* `assume val`/`admit_p` — F\* admit. +* `TODO PROOF` / `OWED:` — self-documented debt markers. +* `unsafePerformIO`/`unsafeCoerce` — soundness-relevant escape hatches in Haskell/Rust source. + +*Recommended next move:* triage each finding into one of: (a) discharge by proof, (b) cover with property-tests + a documented refutation budget, or (c) annotate as a known/necessary axiom (e.g. `funExt`) in `docs/proof-debt.adoc`. + +== 2. Licence debt + +[cols="1,1", options="header"] +|=== +| Field | Value +| LICENSE file | `LICENSE` +| SPDX header | `NONE` +| Manifest licence | `NONE` +| Body classifier | `MPL-2.0-pure` +| Severity | `ok` +|=== + +*Recommended next move:* none for licence. + +== 3. Documentation debt + +[cols="1,1", options="header"] +|=== +| Field | Value +| README lines | 98 +| `docs/` files | 54 +| `docs/` LoC | 2238 +| CHANGELOG.md | Y +| CONTRIBUTING.md | Y +| CODE_OF_CONDUCT.md | Y +| SECURITY.md | Y +| Severity | `OK` +|=== + +*Recommended next move:* none for docs. + +== 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 32f969a..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,72 +0,0 @@ - -SPDX-License-Identifier: MPL-2.0 -SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) ---> - -# Tech-Debt Audit — snifs — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `LOW`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 13 | Coq-Axm/Adm= 0 | Lean-srry/ax= 1 | Agda-pst= 0 | Idr-blv= 6 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 -``` - -**Total markers:** 7. **Severity:** `>07`. - -**Marker types** (any non-zero counts above): -- Coq `Axiom`/`Admitted` — unconditional proof escapes. -- Lean `sorry`/`axiom` — Lean's equivalent. -- Agda `postulate` — accepted axiomatically. -- Idris2 `believe_me`/`assert_total` — runtime-safe coercion / totality assumption. -- Idris2 top-level `partial` — totality-check waived. -- F\* `assume val`/`admit_p` — F\* admit. -- `TODO PROOF` / `OWED:` — self-documented debt markers. -- `unsafePerformIO`/`unsafeCoerce` — soundness-relevant escape hatches in Haskell/Rust source. - -**Recommended next move:** triage each finding into one of: (a) discharge by proof, (b) cover with property-tests + a documented refutation budget, or (c) annotate as a known/necessary axiom (e.g. `funExt`) in `docs/proof-debt.md`. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `NONE` | -| Manifest licence | `NONE` | -| Body classifier | `MPL-2.0-pure` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 98 | -| `docs/` files | 54 | -| `docs/` LoC | 2238 | -| CHANGELOG.md | Y | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `OK` | - -**Recommended next move:** none for docs. - -## 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/session/README.adoc b/session/README.adoc new file mode 100644 index 0000000..5c59774 --- /dev/null +++ b/session/README.adoc @@ -0,0 +1,45 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) Jonathan D.A. Jewell += Session Bindings (Thin Local Layer) +:toc: + +This directory provides local integration for central session-management standards. + +Authoritative protocols live in: + +* `../standards/session-management-standards/` (or `$SESSION_STANDARDS_DIR`) + +This repo keeps only thin bindings: + +* `dispatch.sh` maps canonical commands to central protocol paths. +* `custom-checks.k9` defines repo-local policy checks. +* `local-hooks.sh` provides optional repo-specific hook behavior. + +== Canonical Commands + +* `intake repo ` +* `checkpoint change ` +* `verify maintenance ` +* `verify substantial ` +* `verify release ` +* `close planned ` +* `close urgent ` +* `recover repo ` +* `handover full ` +* `handover split ` +* `handover model ` +* `handover human ` + +== Justfile Aliases + +Run `just session-help` to list aliases, then use recipes such as: + +* `just intake-repo path=.` +* `just checkpoint-change path=.` +* `just verify-maintenance path=.` +* `just close-planned path=.` +* `just handover-model path=.` + +== Runtime Artifacts + +Runtime files are generated per repository in `.session/` and are not canonical standards text. diff --git a/session/README.md b/session/README.md deleted file mode 100644 index ee83d59..0000000 --- a/session/README.md +++ /dev/null @@ -1,46 +0,0 @@ - -# Session Bindings (Thin Local Layer) - -This directory provides local integration for central session-management standards. - -Authoritative protocols live in: - -- `../standards/session-management-standards/` (or `$SESSION_STANDARDS_DIR`) - -This repo keeps only thin bindings: - -- `dispatch.sh` maps canonical commands to central protocol paths. -- `custom-checks.k9` defines repo-local policy checks. -- `local-hooks.sh` provides optional repo-specific hook behavior. - -## Canonical Commands - -- `intake repo ` -- `checkpoint change ` -- `verify maintenance ` -- `verify substantial ` -- `verify release ` -- `close planned ` -- `close urgent ` -- `recover repo ` -- `handover full ` -- `handover split ` -- `handover model ` -- `handover human ` - -## Justfile Aliases - -Run `just session-help` to list aliases, then use recipes such as: - -- `just intake-repo path=.` -- `just checkpoint-change path=.` -- `just verify-maintenance path=.` -- `just close-planned path=.` -- `just handover-model path=.` - -## Runtime Artifacts - -Runtime files are generated per repository in `.session/` and are not canonical standards text. diff --git a/README.adoc.invariants.md b/verification/README.adoc.invariants.md similarity index 100% rename from README.adoc.invariants.md rename to verification/README.adoc.invariants.md From 399efc156fb9c591dc40ed2f0814150695cc2aee Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 16 Jun 2026 18:53:18 +0100 Subject: [PATCH 07/11] chore(tidy): remove .github template community-health files, placeholder CITATION, archive audit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GitHub community-health precedence is .github/ > root > docs/. The .github/ copies of CODE_OF_CONDUCT.md, CONTRIBUTING.md, and SECURITY.md were never bootstrapped — they still carry literal "TEMPLATE INSTRUCTIONS (delete this block before publishing)" blocks, unfilled {{PROJECT_NAME}}/{{SECURITY_EMAIL}}/ {{AUTHOR}} placeholders, and the wrong repo slug (`snif`, not `snifs`). Because of the precedence rule, GitHub has been serving that placeholder cruft publicly and shadowing the clean, filled root copies. Remove the five .github community- health files so GitHub falls back to the root copies: .github/CODE_OF_CONDUCT.md (root CODE_OF_CONDUCT.md is the filled Contributor Covenant) .github/CONTRIBUTING.md (root CONTRIBUTING.md is filled) .github/SECURITY.md (root SECURITY.md is filled) .github/GOVERNANCE.md (dupe of root GOVERNANCE.adoc) .github/MAINTAINERS (unfilled {{AUTHOR}} placeholder; root MAINTAINERS.adoc is filled) .github/CODEOWNERS is kept (the Mustfile requires it). Also remove docs/attribution/CITATION.cff — an unfilled placeholder ({{AUTHOR_LAST}}/{{PROJECT_NAME}}, slug `snif`) that duplicates the filled, canonical root CITATION.cff (real DOI 10.5281/zenodo.19520245). Archive the point-in-time TEMPLATE-STANDARDS-AUDIT.adoc (v1.0, 2026-04-07) out of the repo root into docs/archive/ with a level-2 manifest marking the directory as frozen, append-only history. No inbound references. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/CODE_OF_CONDUCT.md | 331 -------------- .github/CONTRIBUTING.md | 125 ------ .github/GOVERNANCE.md | 160 ------- .github/MAINTAINERS | 10 - .github/SECURITY.md | 410 ------------------ docs/archive/0.2-AI-MANIFEST.a2ml | 20 + .../archive/TEMPLATE-STANDARDS-AUDIT.adoc | 0 docs/attribution/CITATION.cff | 17 - 8 files changed, 20 insertions(+), 1053 deletions(-) delete mode 100644 .github/CODE_OF_CONDUCT.md delete mode 100644 .github/CONTRIBUTING.md delete mode 100644 .github/GOVERNANCE.md delete mode 100644 .github/MAINTAINERS delete mode 100644 .github/SECURITY.md create mode 100644 docs/archive/0.2-AI-MANIFEST.a2ml rename TEMPLATE-STANDARDS-AUDIT.adoc => docs/archive/TEMPLATE-STANDARDS-AUDIT.adoc (100%) delete mode 100644 docs/attribution/CITATION.cff diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md deleted file mode 100644 index c203f78..0000000 --- a/.github/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 {{PROJECT_NAME}} 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/snif/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: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index c0fbf56..0000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,125 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/snif.git -cd snif - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create snif-dev -toolbox enter snif-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -snif/ -├── 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) -├── .machine_readable/ # ALL machine-readable content (Perimeter 1) -│ ├── *.a2ml # State files (STATE, META, ECOSYSTEM, etc.) -│ ├── bot_directives/ # Bot configs -│ └── contractiles/ # Policy contracts (k9, dust, lust, must, trust) -├── .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 — fallback (Perimeter 1) -├── guix.scm # Guix package — primary (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_BRANCH}}` -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/snif/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/snif/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/snif/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/snif/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/.github/GOVERNANCE.md b/.github/GOVERNANCE.md deleted file mode 100644 index c676f81..0000000 --- a/.github/GOVERNANCE.md +++ /dev/null @@ -1,160 +0,0 @@ - -# Project Governance - -This document describes the governance model for **{{PROJECT_NAME}}**. - ---- - -## Project Governance Model - -{{PROJECT_NAME}} follows a **Benevolent Dictator For Life (BDFL)** governance model. -This model is well-suited for solo maintainers and small project teams where rapid, -consistent decision-making is more valuable than formal consensus processes. - -The BDFL has final authority on all project decisions, including technical direction, -release schedules, contributor access, and community standards. - -> **Transition clause:** When the core team exceeds three active maintainers, this -> project should transition to a **consensus-based governance model** with documented -> voting procedures. That transition should itself be recorded as an Architecture -> Decision Record (ADR) in `docs/decisions/`. - ---- - -## Decision Making - -### Day-to-day decisions - -- The BDFL makes final decisions on all matters. -- Routine decisions (bug fixes, dependency updates, minor improvements) may be made - by any maintainer with commit access. -- Maintainers are expected to use good judgement and seek input on non-trivial changes. - -### Proposing changes - -- Contributors can propose changes by opening issues or pull requests. -- Significant changes (new features, breaking changes, architectural shifts) should - be discussed in an issue before implementation begins. -- The BDFL will provide a clear accept/reject decision with reasoning. - -### Architecture Decision Records (ADRs) - -- Significant technical decisions are documented as ADRs in `docs/decisions/`. -- ADR statuses: `proposed`, `accepted`, `deprecated`, `superseded`, `rejected`. -- ADRs provide a historical record of why decisions were made and what alternatives - were considered. -- See `.machine_readable/META.a2ml` for the machine-readable ADR index. - ---- - -## Roles - -### BDFL (Benevolent Dictator For Life) - -- The project creator and ultimate decision-maker. -- Sets the project's technical direction and long-term vision. -- Has final say on all matters, including maintainer appointments and removals. -- Responsible for ensuring the project adheres to RSR standards. - -### Maintainer - -- Has commit access to the repository. -- Reviews and merges pull requests. -- Triages issues and manages releases. -- Upholds code quality, security standards, and the Code of Conduct. -- Listed in [MAINTAINERS.md](MAINTAINERS.md). - -### Contributor - -- Anyone who submits pull requests, opens issues, or participates in discussions. -- Does not have direct commit access. -- Contributions are reviewed by maintainers before merging. -- All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md). - -### Bot - -- Automated agents managed via your bot orchestration system. -- Perform automated code review, security scanning, dependency updates, and - standards enforcement. -- Bot actions are subject to the same quality and review standards as human - contributions. -- Configure your bots in `.machine_readable/bot_directives/`. - ---- - -## Becoming a Maintainer - -A contributor may be nominated to become a maintainer when they demonstrate: - -1. **Sustained quality contributions** -- a track record of well-crafted pull requests - that follow project conventions and require minimal revision. -2. **Understanding of RSR standards** -- familiarity with the Repository Structure - Requirements, security policies, and CI/CD workflows used across the project. -3. **Constructive participation** -- helpful issue triage, thoughtful code review - comments, and mentoring of other contributors. -4. **Reliability** -- consistent engagement over a meaningful period (typically 3+ - months of active contribution). - -### Process - -1. An existing maintainer nominates the candidate by opening a private discussion - with the BDFL. -2. The BDFL reviews the candidate's contribution history and community interactions. -3. The BDFL approves or declines the nomination, with reasoning provided to the - nominator. -4. If approved, the new maintainer is added to [MAINTAINERS.md](MAINTAINERS.md) and - granted appropriate repository access. - ---- - -## Removing a Maintainer - -A maintainer may be removed under the following circumstances: - -- **Inactivity**: No meaningful contributions or reviews for 12 or more consecutive - months. The maintainer will be contacted before removal and offered the option to - move to emeritus status voluntarily. -- **Code of Conduct violation**: Behaviour that violates the - [Code of Conduct](CODE_OF_CONDUCT.md), as determined through the enforcement - process described therein. -- **BDFL discretion**: The BDFL may remove a maintainer for other reasons (e.g., - repeated disregard for project standards, loss of trust). Reasoning will be - documented privately. - -Removed maintainers are moved to the Emeritus section of -[MAINTAINERS.md](MAINTAINERS.md) unless removal was due to a serious Code of Conduct -violation. - ---- - -## Code of Conduct - -All participants in this project are expected to follow the -[Code of Conduct](CODE_OF_CONDUCT.md). The Code of Conduct applies to all project -spaces, including issues, pull requests, discussions, and any forum where the project -is represented. - -Enforcement of the Code of Conduct is described in that document. The BDFL serves as -the final arbiter in conduct disputes. - ---- - -## Amendments - -This governance document may be amended by the BDFL at any time. All amendments will -be: - -1. Documented as an ADR in `docs/decisions/` explaining the rationale for the change. -2. Committed to the repository with a clear commit message. -3. Communicated to existing maintainers and contributors via the project's usual - channels. - -Substantive changes (e.g., changing the governance model itself) should be discussed -with the community before adoption, even though the BDFL retains final authority. - ---- - -Copyright (c) {{CURRENT_YEAR}} hyperpolymath. Licensed under MPL-2.0. diff --git a/.github/MAINTAINERS b/.github/MAINTAINERS deleted file mode 100644 index 145c4e9..0000000 --- a/.github/MAINTAINERS +++ /dev/null @@ -1,10 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# MAINTAINERS - Project maintainers and contact information -# -# Format: Name (role) -# Replace placeholders with actual maintainer information. - -{{AUTHOR}} <{{AUTHOR_EMAIL}}> (Lead Maintainer) - -# Additional maintainers: -# Name (role) diff --git a/.github/SECURITY.md b/.github/SECURITY.md deleted file mode 100644 index 22bee96..0000000 --- a/.github/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/snif/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** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} 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/snif`) 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/snif/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 {{PROJECT_NAME}}, 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/snif/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/snif/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/snif/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 {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/docs/archive/0.2-AI-MANIFEST.a2ml b/docs/archive/0.2-AI-MANIFEST.a2ml new file mode 100644 index 0000000..f7a284b --- /dev/null +++ b/docs/archive/0.2-AI-MANIFEST.a2ml @@ -0,0 +1,20 @@ +# SPDX-License-Identifier: MPL-2.0 +--- +### [META] +id: "archive" +level: 2 +parent: "../0.1-AI-MANIFEST.a2ml" + +--- +### [AI_MANIFEST] +description: | + Frozen historical documents kept for provenance — point-in-time audits and + superseded snapshots. Files here are NOT maintained; their claims reflect the + date they were written, not current repository state. + +canonical_locations: + template_standards_audit: "TEMPLATE-STANDARDS-AUDIT.adoc" + +invariants: + - "Archived documents are append-only history; do not edit their content to match current state." + - "If a current equivalent exists, link to it rather than updating the archived copy." diff --git a/TEMPLATE-STANDARDS-AUDIT.adoc b/docs/archive/TEMPLATE-STANDARDS-AUDIT.adoc similarity index 100% rename from TEMPLATE-STANDARDS-AUDIT.adoc rename to docs/archive/TEMPLATE-STANDARDS-AUDIT.adoc diff --git a/docs/attribution/CITATION.cff b/docs/attribution/CITATION.cff deleted file mode 100644 index 6930c2d..0000000 --- a/docs/attribution/CITATION.cff +++ /dev/null @@ -1,17 +0,0 @@ -cff-version: 1.2.0 -message: "If you use this software, please cite it as below." -authors: -- family-names: "{{AUTHOR_LAST}}" - given-names: "{{AUTHOR_FIRST}}" - orcid: "https://orcid.org/0000-0000-0000-0000" # Placeholder -title: "{{PROJECT_NAME}}" -version: 0.1.0 -date-released: {{CURRENT_DATE}} -url: "https://github.com/hyperpolymath/snif" -repository-code: "https://github.com/hyperpolymath/snif" -license: MPL-2.0 -keywords: - - "rsr" - - "formal-verification" - - "neurosymbolic" - - "provenance" From a0cceae80033e8dec7ce6977027b08b10a07abd1 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 16 Jun 2026 18:56:13 +0100 Subject: [PATCH 08/11] chore(tidy): archive superseded paper draft, drop duplicate MAINTAINERS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/papers/snifs.tex is a complete but SUPERSEDED paper draft: the canonical paper is the richer docs/whitepapers/academic/snif.tex (+ snif.pdf), and this earlier draft carries stale figures (it claims 11/11 tests and 7 proofs; the repo is now at 21/21 in-BEAM tests and 10 machine-checked proofs). Per owner decision, archive it for provenance rather than delete: git mv into docs/archive/ (recorded in the frozen-history manifest) and remove the now-empty, undeclared docs/papers/ directory. Remove docs/attribution/MAINTAINERS.adoc — a filled but redundant second copy of the canonical root MAINTAINERS.adoc (which the Mustfile requires at root). One maintainers file, no drift surface. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/archive/0.2-AI-MANIFEST.a2ml | 1 + docs/{papers => archive}/snifs.tex | 0 docs/attribution/MAINTAINERS.adoc | 48 ------------------------------ 3 files changed, 1 insertion(+), 48 deletions(-) rename docs/{papers => archive}/snifs.tex (100%) delete mode 100644 docs/attribution/MAINTAINERS.adoc diff --git a/docs/archive/0.2-AI-MANIFEST.a2ml b/docs/archive/0.2-AI-MANIFEST.a2ml index f7a284b..6113f59 100644 --- a/docs/archive/0.2-AI-MANIFEST.a2ml +++ b/docs/archive/0.2-AI-MANIFEST.a2ml @@ -14,6 +14,7 @@ description: | canonical_locations: template_standards_audit: "TEMPLATE-STANDARDS-AUDIT.adoc" + superseded_paper: "snifs.tex" invariants: - "Archived documents are append-only history; do not edit their content to match current state." diff --git a/docs/papers/snifs.tex b/docs/archive/snifs.tex similarity index 100% rename from docs/papers/snifs.tex rename to docs/archive/snifs.tex diff --git a/docs/attribution/MAINTAINERS.adoc b/docs/attribution/MAINTAINERS.adoc deleted file mode 100644 index 51e8f31..0000000 --- a/docs/attribution/MAINTAINERS.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Maintainers -:toc: preamble - -This document lists the maintainers of this project and their responsibilities. - -== Current Maintainers - -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact - -| {{AUTHOR}} -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] -|=== - -== Responsibilities - -Maintainers are responsible for: - -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct - -== Becoming a Maintainer - -Contributors who demonstrate: - -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health - -May be invited to become maintainers at the discretion of existing maintainers. - -== Decision Making - -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation - -== Contact - -For questions about project governance, open an issue or contact the maintainers listed above. From 3244104f39df1bbee920ec22ff0b1e9f6669eb64 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 16 Jun 2026 19:13:36 +0100 Subject: [PATCH 09/11] fix(docs): correct README header + crash-mode counts + dangling refs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adversarial verification of the tidy caught defects in files this branch already touched: README.adoc — the Tier-B "authoring standard" edit left a botched, duplicated document header: a second :toc:/:source-highlighter: attribute block sitting AFTER body content (so it was inert and rendered as stray text), a stray mid-body author line, and an orphan bare DOI URL citing the WRONG Zenodo record (19680824 vs the canonical 19520245 used by the badge, the Citation block, and CITATION.cff). Collapse to a single clean header: attributes before any body, all badges grouped, one correct DOI. Factual fixes (verified against zig/src/safe_nif.zig, which has 8 exports of which FIVE are crash_*): "six crash modes" -> "five" in README repo-layout and QUICKSTART-DEV project-structure. Make the benchmark command's working directory explicit (run from demo/). Drop the dangling `.claude/CLAUDE.md` reference in QUICKSTART-DEV (no such file in this repo) and the inaccurate "signing-key policy" pointer (CONTRIBUTING.md documents the contribution flow, not keys). NOT touched: the residual PMPL-1.0 license badge in README is left verbatim for manual owner review (licence markup is owner-only; flagged, not auto-edited). Co-Authored-By: Claude Opus 4.8 (1M context) --- QUICKSTART-DEV.adoc | 6 +++--- README.adoc | 13 ++++--------- 2 files changed, 7 insertions(+), 12 deletions(-) diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc index 0a7f5e5..9c38d80 100644 --- a/QUICKSTART-DEV.adoc +++ b/QUICKSTART-DEV.adoc @@ -59,7 +59,7 @@ just proof-status # summary of proven / tested / trusted [source] ---- snifs/ -├── zig/src/safe_nif.zig # the SNIF kernel — six trapped crash modes +├── zig/src/safe_nif.zig # the SNIF kernel — five trapped crash modes ├── zig/ # safe_nif / buffer_abi / burble_fft guests ├── rust/ , rust-guest/ # Rust→wasm32 guests (dual-sourced; see Dustfile) ├── demo/ # Mix project: wasmex loader + ExUnit suite @@ -94,11 +94,11 @@ just proof-check-all # all proofs still check just assail # no new security findings ---- -Commits must be **signed**. See `CONTRIBUTING.md` for the signing-key policy. +Commits must be *signed*. See `CONTRIBUTING.md` for the contribution flow. == LLM / AI Agent Development -Read `0-AI-MANIFEST.a2ml` and `.claude/CLAUDE.md` first, then `PROOF-STATUS.md` +Read `0-AI-MANIFEST.a2ml` first, then `PROOF-STATUS.md` before making any claim about what is proven. == Get Help diff --git a/README.adoc b/README.adoc index e8cad00..6175f4a 100644 --- a/README.adoc +++ b/README.adoc @@ -5,23 +5,18 @@ = SNIFs: Safer Native Implemented Functions for the BEAM via WebAssembly Sandboxing :toc: preamble :icons: font +:source-highlighter: highlight.js image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/snifs"] image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] image:https://api.thegreenwebfoundation.org/greencheckimage/github.com[Green Web,link="https://www.thegreenwebfoundation.org/green-web-check/?url=github.com"] - -https://doi.org/10.5281/zenodo.19680824 +image:https://zenodo.org/badge/DOI/10.5281/zenodo.19520245.svg[DOI,link=https://doi.org/10.5281/zenodo.19520245] This repository contains: (1) the SNIF architecture paper, (2) a working BEAM + WASM implementation, (3) integration tests and benchmarking, (4) formal verification artifacts. -Jonathan D.A. Jewell -:toc: -:source-highlighter: highlight.js - -image:https://zenodo.org/badge/DOI/10.5281/zenodo.19520245.svg[DOI,link=https://doi.org/10.5281/zenodo.19520245] image:https://img.shields.io/badge/license-PMPL--1.0--or--later-blue[License] == Overview @@ -84,7 +79,7 @@ workload: | *Marshalling* | ∝ bytes: copying buffers into/out of linear memory. Dominates *data-heavy* calls; mitigated by keeping buffers resident across calls. |=== -Measured in-BEAM (OTP 25, `fibonacci(20)`, n=2000; `mix run bench/snif_bench.exs`): +Measured in-BEAM (OTP 25, `fibonacci(20)`, n=2000; from `demo/`, `mix run bench/snif_bench.exs`): ---- case mean_µs p50_µs p99_µs @@ -150,7 +145,7 @@ verified — see paper). == Repository layout ---- -zig/src/safe_nif.zig Zig source with six crash modes + fibonacci +zig/src/safe_nif.zig Zig source with five crash modes + fibonacci priv/*.wasm Pre-built WASM binaries (ReleaseSafe + ReleaseFast) demo/ Mix project with wasmex loader + ExUnit test suite docs/whitepapers/ LaTeX paper + compiled PDF From 4647b1052ea362c6fbe883e1f23ce5711ed8364e Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 16 Jun 2026 19:34:10 +0100 Subject: [PATCH 10/11] chore(readme): remove residual PMPL-1.0 licence badge (owner-authorized) The README carried a leftover RSR-template badge declaring "license-PMPL--1.0--or--later", contradicting the repo's actual MPL-2.0 licence (asserted by the SPDX header, the MPL-2.0 badge, and the License section) and violating the estate rule that PMPL appears only in palimpsest-license / palimpsest-plasma / consent-aware-http. Owner explicitly authorized removing this badge this occasion. No LICENSE file or SPDX-License-Identifier is changed; only the incorrect badge markup is deleted (the correct MPL-2.0 badge already exists). Co-Authored-By: Claude Opus 4.8 (1M context) --- README.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/README.adoc b/README.adoc index 6175f4a..564a89c 100644 --- a/README.adoc +++ b/README.adoc @@ -17,7 +17,6 @@ This repository contains: (2) a working BEAM + WASM implementation, (3) integration tests and benchmarking, (4) formal verification artifacts. -image:https://img.shields.io/badge/license-PMPL--1.0--or--later-blue[License] == Overview From 43eb2938bd9bcfa9ed655d963d577f91ee13b18c Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 16 Jun 2026 19:34:27 +0100 Subject: [PATCH 11/11] chore(identity): de-template machine-readable identity strings to snifs (safe subset) Verification found the machine-readable identity/config layer still declared the repo as "rsr-template-repo" or "snif" while the human-facing surface was already de-templated. Per owner decision, fix the SAFE, non-load-bearing identity strings now and defer the load-bearing + identity-sensitive parts to a plan: .machine_readable/CLADE.a2ml canonical-name + forge URLs + lineage -> snifs .machine_readable/ECOSYSTEM.a2ml name snif -> snifs; fill {{REPO_DESCRIPTION}} .machine_readable/6a2/ECOSYSTEM.a2ml name rsr-template-repo -> snifs; fill purpose .machine_readable/ai/AI.a2ml rsr-template-repo -> snifs .machine_readable/6a2/anchor/ANCHOR.a2ml fill identity block (project/kind/one-sentence/ domain), repo hyperpolymath/snif -> snifs, copyright + date placeholders stapeln.toml / selur-compose.toml / eclexiaiser.toml name -> snifs .machine_readable/configs/git-cliff/cliff.toml remote URLs snif -> snifs; copyright DEFERRED to a follow-up plan (NOT touched here): CLADE prefixed-name + [clade] block (needs the real gv-clade-index entry), the load-bearing root Justfile (project :=) and contractile Mustfile/Trustfile/Intentfile/Adjustfile gate logic, all template-doc deletions (RSR_OUTLINE/QUICKSTART/PLACEHOLDERS), the READINESS.md format conversion, and the 5 pre-existing manifest-parent defects. Co-Authored-By: Claude Opus 4.8 (1M context) --- .machine_readable/6a2/ECOSYSTEM.a2ml | 4 ++-- .machine_readable/6a2/anchor/ANCHOR.a2ml | 14 +++++++------- .machine_readable/CLADE.a2ml | 11 ++++++----- .machine_readable/ECOSYSTEM.a2ml | 4 ++-- .machine_readable/ai/AI.a2ml | 2 +- .machine_readable/configs/git-cliff/cliff.toml | 6 +++--- eclexiaiser.toml | 2 +- selur-compose.toml | 4 ++-- stapeln.toml | 10 +++++----- 9 files changed, 29 insertions(+), 28 deletions(-) diff --git a/.machine_readable/6a2/ECOSYSTEM.a2ml b/.machine_readable/6a2/ECOSYSTEM.a2ml index d11c37f..c25a113 100644 --- a/.machine_readable/6a2/ECOSYSTEM.a2ml +++ b/.machine_readable/6a2/ECOSYSTEM.a2ml @@ -9,8 +9,8 @@ version = "0.1.0" last-updated = "2026-04-11" [project] -name = "rsr-template-repo" -purpose = "" # TODO: describe project purpose +name = "snifs" +purpose = "Safer NIFs: crash-isolated native interfaces for the BEAM via WebAssembly sandboxing." role = "" # TODO: describe project role # e.g. ffi-infrastructure, cli-tool, library, service [position-in-ecosystem] diff --git a/.machine_readable/6a2/anchor/ANCHOR.a2ml b/.machine_readable/6a2/anchor/ANCHOR.a2ml index 63c400d..5fb18a4 100644 --- a/.machine_readable/6a2/anchor/ANCHOR.a2ml +++ b/.machine_readable/6a2/anchor/ANCHOR.a2ml @@ -1,15 +1,15 @@ # SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} (hyperpolymath) <{{AUTHOR_EMAIL}}> +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # # ANCHOR.a2ml - authoritative anchor for this repository [metadata] version = "1.0.0" -last-updated = "{{CURRENT_DATE}}" +last-updated = "2026-06-16" [anchor] schema = "hyperpolymath.anchor/1" -repo = "hyperpolymath/snif" +repo = "hyperpolymath/snifs" authority = "upstream-canonical" purpose = [ @@ -19,10 +19,10 @@ purpose = [ ] [identity] -project = "{{PROJECT_NAME}}" -kind = "{{PROJECT_KIND}}" # language | library | service | tool -one-sentence = "{{PROJECT_PURPOSE}}" -domain = "{{PROJECT_DOMAIN}}" +project = "snifs" +kind = "library" # language | library | service | tool +one-sentence = "Safer NIFs: crash-isolated native interfaces for the BEAM via WebAssembly sandboxing." +domain = "BEAM / WebAssembly / native-interface safety" [semantic-authority] policy = "canonical" diff --git a/.machine_readable/CLADE.a2ml b/.machine_readable/CLADE.a2ml index b14389c..0272179 100644 --- a/.machine_readable/CLADE.a2ml +++ b/.machine_readable/CLADE.a2ml @@ -6,7 +6,8 @@ uuid = "a5ea1382-a34c-5334-8a46-a2ebe904c810" primary-forge = "github" primary-owner = "hyperpolymath" -canonical-name = "rsr-template-repo" +canonical-name = "snifs" +# prefixed-name + [clade] block pending the real gv-clade-index entry for snifs prefixed-name = "rm-rsr-template-repo" [clade] @@ -16,11 +17,11 @@ assigned = "2026-03-16" rationale = "" [forges] -github = "hyperpolymath/rsr-template-repo" -gitlab = "hyperpolymath/rsr-template-repo" -bitbucket = "hyperpolymath/rsr-template-repo" +github = "hyperpolymath/snifs" +gitlab = "hyperpolymath/snifs" +bitbucket = "hyperpolymath/snifs" [lineage] type = "standalone" -parent = "RSR template — scaffold for new repos" +parent = "rsr-template-repo (bootstrapped from the RSR standard scaffold)" born = "2026-03-16" diff --git a/.machine_readable/ECOSYSTEM.a2ml b/.machine_readable/ECOSYSTEM.a2ml index c398ce1..dc4bbb0 100644 --- a/.machine_readable/ECOSYSTEM.a2ml +++ b/.machine_readable/ECOSYSTEM.a2ml @@ -2,7 +2,7 @@ ;; Ecosystem position and relationships (ecosystem (version "1.0.0") - (name "snif") + (name "snifs") (type "library") - (purpose "{{REPO_DESCRIPTION}}") + (purpose "Safer NIFs: crash-isolated native interfaces for the BEAM via WebAssembly sandboxing.") (related-projects)) diff --git a/.machine_readable/ai/AI.a2ml b/.machine_readable/ai/AI.a2ml index c4da8df..726fcb2 100644 --- a/.machine_readable/ai/AI.a2ml +++ b/.machine_readable/ai/AI.a2ml @@ -2,7 +2,7 @@ # AI Assistant Instructions ## Repository Focus -- `rsr-template-repo` is treated as a Rhodium Standard Repository; obey the Rhodium policies and keep `.machine_readable/` authoritative. +- `snifs` is treated as a Rhodium Standard Repository; obey the Rhodium policies and keep `.machine_readable/` authoritative. - All machine-readable content lives under `.machine_readable/` — state files (a2ml), bot directives, and contractiles. - Prefer to keep generated files out of source control, and regenerate them with the documented commands before committing. diff --git a/.machine_readable/configs/git-cliff/cliff.toml b/.machine_readable/configs/git-cliff/cliff.toml index f6cfc7d..3560d4e 100644 --- a/.machine_readable/configs/git-cliff/cliff.toml +++ b/.machine_readable/configs/git-cliff/cliff.toml @@ -1,5 +1,5 @@ # SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} (hyperpolymath) <{{AUTHOR_EMAIL}}> +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # # git-cliff configuration for conventional commit changelog generation. # https://git-cliff.org/docs/configuration @@ -21,7 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 # https://keats.github.io/tera/docs/#introduction body = """ {%- macro remote_url() -%} - https://github.com/hyperpolymath/snif + https://github.com/hyperpolymath/snifs {%- endmacro -%} {% if version -%} @@ -57,7 +57,7 @@ body = """ # Template for the changelog footer footer = """ {%- macro remote_url() -%} - https://github.com/hyperpolymath/snif + https://github.com/hyperpolymath/snifs {%- endmacro -%} {% for release in releases -%} diff --git a/eclexiaiser.toml b/eclexiaiser.toml index df7ace4..1c2e916 100644 --- a/eclexiaiser.toml +++ b/eclexiaiser.toml @@ -2,7 +2,7 @@ # SPDX-License-Identifier: MPL-2.0 [project] -name = "rsr-template-repo" +name = "snifs" [[functions]] name = "build" diff --git a/selur-compose.toml b/selur-compose.toml index 960ddbe..34356ec 100644 --- a/selur-compose.toml +++ b/selur-compose.toml @@ -1,14 +1,14 @@ # SPDX-License-Identifier: MPL-2.0 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # -# Stapeln service definition for rsr-template-repo +# Stapeln service definition for snifs # # Usage: # podman-compose -f selur-compose.toml up -d # just stack-up [project] -name = "rsr-template-repo" +name = "snifs" [services.app] build = { context = ".", dockerfile = "Containerfile" } diff --git a/stapeln.toml b/stapeln.toml index eb3785e..b8eba6b 100644 --- a/stapeln.toml +++ b/stapeln.toml @@ -1,13 +1,13 @@ # SPDX-License-Identifier: MPL-2.0 -# stapeln.toml — Layer-based container build for rsr-template-repo +# stapeln.toml — Layer-based container build for snifs # # stapeln builds containers as composable layers (German: "to stack"). # Each layer is independently cacheable, verifiable, and signable. [metadata] -name = "rsr-template-repo" +name = "snifs" version = "0.1.0" -description = "rsr-template-repo container service" +description = "snifs container service" author = "Jonathan D.A. Jewell " license = "MPL-2.0" registry = "ghcr.io/hyperpolymath" @@ -32,7 +32,7 @@ packages = [] cache = true [layers.build] -description = "rsr-template-repo build" +description = "snifs build" extends = "toolchain" commands = [] @@ -43,7 +43,7 @@ packages = ["ca-certificates", "curl"] copy-from = [ { layer = "build", src = "/app/", dst = "/app/" }, ] -entrypoint = ["/app/rsr-template-repo"] +entrypoint = ["/app/snifs"] user = "nonroot" # ── Security ───────────────────────────────────────────────────