diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index a3ebf6a..71ba396 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -3,6 +3,8 @@ # Docs: https://gh.io/actions-lockfile version: 'v0.0.3' workflows: + '.github/workflows/bactrian.yml': + - 'actions/checkout@v7.0.1' '.github/workflows/build-notification.yml': - 'actions/checkout@v7.0.1' '.github/workflows/codeql.yml': diff --git a/.github/workflows/bactrian.yml b/.github/workflows/bactrian.yml new file mode 100644 index 0000000..d7c5dc3 --- /dev/null +++ b/.github/workflows/bactrian.yml @@ -0,0 +1,46 @@ +# This workflow is managed by gh actions-lock. +# SPDX-License-Identifier: MPL-2.0 +# bactrian.yml - runs the Bactrian readiness preflight test and checks that the +# preflight still reports BLOCKED. It does not run any proof or verifier. +name: Bactrian readiness + +on: + pull_request: + push: + branches: + - main + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + readiness: + name: Bactrian readiness gate + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: read + steps: + - name: Checkout + uses: actions/checkout@v7.0.1 + with: + persist-credentials: false + + - name: Run the preflight test + run: bash tests/bactrian/doctor_test.sh + + - name: Require the preflight to stay blocked + # While the authorities are unpinned, doctor.sh must exit with status 2. + # This expectation must flip when WP-00 pins the authorities. + run: | + status=0 + bash scripts/bactrian/doctor.sh || status=$? + if [ "$status" -ne 2 ]; then + echo "Expected preflight exit status 2 (BLOCKED), got $status" >&2 + exit 1 + fi diff --git a/README.adoc b/README.adoc index efc1b0b..6c0439d 100644 --- a/README.adoc +++ b/README.adoc @@ -5,208 +5,101 @@ :toc: :toc-placement: preamble -// ── Licensing ─────────────────────────────────────────────────────────────── image:https://img.shields.io/badge/Code-MPL--2.0-blue.svg?logo=mozilla[Code licence: MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] image:https://img.shields.io/badge/Docs-CC--BY--SA--4.0-blue.svg?logo=creativecommons[Docs licence: CC-BY-SA-4.0,link="https://creativecommons.org/licenses/by-sa/4.0/"] -image:https://img.shields.io/badge/Provenance-Quantum--Safe-blueviolet[Quantum-Safe Provenance,link="docs/legal/EXHIBIT-B-QUANTUM-SAFE.txt"] - -// ── Standard & quality gates ──────────────────────────────────────────────── -image:https://img.shields.io/badge/RSR-Rhodium_Standard-9C27B0[Rhodium Standard Repository,link="https://github.com/hyperpolymath/rhodium-standard-repositories"] image:https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/hyperpolymath/bactrian/governance-badges/badges/k9.json[K9 conformance,link="https://github.com/hyperpolymath/bactrian/actions/workflows/dogfood-gate.yml"] image:https://api.scorecard.dev/projects/github.com/hyperpolymath/bactrian/badge[OpenSSF Scorecard,link="https://scorecard.dev/viewer/?uri=github.com/hyperpolymath/bactrian"] -image:https://sonarcloud.io/api/project_badges/measure?project=hyperpolymath_bactrian&metric=alert_status[SonarQube Quality Gate,link="https://sonarcloud.io/summary/new_code?id=hyperpolymath_bactrian"] -image:https://archive.softwareheritage.org/badge/origin/https://github.com/hyperpolymath/bactrian/[Archived in Software Heritage,link="https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hyperpolymath/bactrian"] - -// ── Provenance & ecosystem ────────────────────────────────────────────────── -image:https://img.shields.io/badge/Idris-Inside-5E5086?logo=idris&logoColor=white[Idris Inside,link="https://github.com/hyperpolymath/proven"] -image:https://img.shields.io/badge/Zig-Zero--overhead-F7A41D?logo=zig&logoColor=black[Zig Zero-overhead FFI,link="https://github.com/hyperpolymath/typed-wasm"] -image:https://api.thegreenwebfoundation.org/greencheckimage/github.com[Green Web,link="https://www.thegreenwebfoundation.org/green-web-check/?url=github.com"] -Research-stage verification suite for a pure OCaml subset, BEAM actor protocols, and Idris2/Zig FFI boundaries. Targets Why3/SMT, Apalache, and checked proof receipts. Current contents are architecture, an implementation roadmap, and fail-closed readiness tooling; the proof engine is not yet implemented. +Bactrian is a planned verification suite for a deliberately restricted, pure +subset of OCaml, for BEAM-style actor protocols, and for Idris2 and Zig foreign +function boundaries. It aims to route proof obligations to Why3 with SMT +solvers, to Apalache, and to checked proof receipts. The design is a research +proposal. [IMPORTANT] ==== -*This file is a template.* You are reading `README.adoc` from the *RSR template repo* -(or a freshly-cloned copy of it). Run `just repo-init` to replace every `{{PLACEHOLDER}}` -token with your project's details, then delete this admonition. Until you do, the -`{{...}}` markers below are intentional placeholders, not content. +*Status: research stage.* + +* Bactrian has no proof engine. +* The repository contains no OCaml code, no Dune project and no Why3 file. +* The only executable is a readiness preflight. It cannot establish a proof. +* No verification result exists. Do not read any file here as a proof. +* Files under `verification/proofs/` and `src/interface/` are scaffold from the + repository template. They are not Bactrian proofs. ==== -== What this is +== What exists today -A new repository scaffolded from the *Rhodium Standard Repository (RSR)* template: -a batteries-included starting point that ships with CI/CD, machine-readable project -metadata, an AI-agent gatekeeper protocol, a formally-typed ABI/FFI seam -(Idris2 + Zig), container and reproducible-build scaffolding, and governance -infrastructure — all wired and passing the RSR validators on day one. +* `docs/architecture/BACTRIAN-VERIFICATION-SPEC.adoc`: the architecture and + soundness contract. +* `docs/architecture/BACTRIAN-IMPLEMENTATION-PLAN.adoc`: the milestones 0 to 6. +* `docs/status/BACTRIAN-ULTRAPLAN.adoc`: work packages WP-00A to WP-09 and + gates G0 to G5. +* `scripts/bactrian/doctor.sh`: the readiness preflight. It checks required + tools, the ECHIDNA adapter setting, the authority lock and the planned source + files. +* `tests/bactrian/doctor_test.sh`: the test of the preflight. +* `.machine_readable/bactrian/authorities.lock`: eight upstream authority rows. + All eight are `UNPINNED`. -Replace this section with a description of *your* project once initialised. - -== Quick start +== Run the preflight [source,bash] ---- -# 1. Create a repo from this template (or clone it), then from the repo root: -mise trust # allow this repository's mise.toml (needed without a TTY) -mise install # the toolchain, including the yq repo-init needs -mise exec -- just repo-init # interactive bootstrap: fills every {{PLACEHOLDER}} - -# 2. See the available tasks: -mise exec -- just # lists all phases (build, test, validate, audit, ...) - -# 3. Check the repo still satisfies the RSR shape: -mise exec -- just validate # structure + metadata checks +bash scripts/bactrian/doctor.sh +bash tests/bactrian/doctor_test.sh ---- -`mise exec --` puts the toolchain on `PATH` for that one command. Once mise is -activated in your shell (`eval "$(mise activate bash)"`, or your shell's -equivalent), plain `just` works and the prefix can be dropped. - -`just repo-init` prompts for the project name, owner, author, licence contact, and the -other values listed in `.machine_readable/ai/PLACEHOLDERS.adoc`, substitutes them -across the tree, validates the result, and (if available) runs the `k9-svc` checks. +`doctor.sh` prints one line per check. It exits with status 2 and prints +"Preflight BLOCKED" while tools or authorities are missing. This is the +expected result today. A green exit would still not mean that anything is +proved. -[[ai-install]] -== AI-Assisted Installation (Recommended) +`doctor_test.sh` tests the preflight itself. It uses synthetic fixtures. A pass +means the preflight behaves as designed. It says nothing about Bactrian proofs. -=== Just say it +CI runs both commands in `.github/workflows/bactrian.yml`. -Say this to any AI assistant that can read a URL and run commands (or give you -commands to paste): +== Planned layers -[source,text] ----- -Create a new repository from https://github.com/hyperpolymath/bactrian ----- +* *Layer A:* a sequential, pure OCaml subset. The plan uses Why3 and SMT + solvers, with strict Dedukti witnesses. +* *Layer B:* actor, mailbox and protocol models. The plan uses K-CUT artifacts + from `choreographic-types` and Apalache bounded model checking. +* *Layer C:* a verified foreign boundary. The plan uses an Idris2 ABI manifest + and a Zig implementation checked by Idris2 QTT and ZigProve. -The URL is the key: it leads the assistant to -link:docs/AI_INSTALLATION_GUIDE.adoc[`docs/AI_INSTALLATION_GUIDE.adoc`], the -complete step-by-step recipe. The assistant checks your system, installs the -prerequisites, instantiates the template with `just repo-init`, and verifies the -result with `just doctor`. +None of these layers is implemented. -* "Set up bactrian so I can work on the template itself — https://github.com/hyperpolymath/bactrian" -* `./launcher.sh --ai-setup` (or `just ai-setup`) prints the line and the guide path. +== Plan -=== What you will be asked +* link:docs/architecture/BACTRIAN-VERIFICATION-SPEC.adoc[Verification specification] +* link:docs/architecture/BACTRIAN-IMPLEMENTATION-PLAN.adoc[Implementation plan] +* link:docs/plan/ULTRAPLAN.adoc[Plan to v1.0.0]: gates, order, models and effort +* link:docs/status/BACTRIAN-ULTRAPLAN.adoc[Ultra-plan] +* link:docs/status/ROADMAP.adoc[Roadmap] -. Your operating system (Linux, macOS, or Windows via WSL2). -. The new project's name, owner, author and licence contact (the values listed in - `.machine_readable/ai/PLACEHOLDERS.adoc`). -. To confirm the privacy notice below. +== Working in this repository -=== Privacy and security +The repository was created from the Rhodium Standard Repository template and +keeps its tooling. The Justfile provides these recipes, among others: -[IMPORTANT] -==== -Setting up bactrian clones this repository and installs its developer -tools per-user with mise (no administrator rights, nothing sent anywhere). -`just repo-init` rewrites files only inside the new checkout; it creates no -remote repository and pushes nothing until you do. -==== +[source,bash] +---- +mise trust && mise install # install the pinned developer tools +mise exec -- just doctor # check the developer environment +mise exec -- just validate # run the template validation suite +---- -=== Minting without a terminal - -Agents and CI can mint non-interactively: set `RSR_NON_INTERACTIVE=1` and pass -the answers as environment variables named like the prompts' variables in -`build/just/repo-init.just` (`PROJECT_NAME`, `REPO`, `OWNER`, `AUTHOR` and -`AUTHOR_EMAIL` are required; any other answer left unset is blank or takes its -default). Piping the answers to stdin in prompt order also works. - -=== Troubleshooting - -Run `just doctor`; each FAIL carries a code explained in -link:docs/SETUP.adoc#troubleshooting[`docs/SETUP.adoc` §Troubleshooting], and -`just heal` applies the automatic fixes. Prefer to do it yourself? The full -manual route is link:docs/SETUP.adoc[`docs/SETUP.adoc`]; developers and -maintainers can brief an AI with `just ai-warmup dev` / `just ai-warmup maintainer`. - -== What you get - -* *Machine-readable metadata* (`.machine_readable/descriptiles/`) — `STATE`, `META`, - `ECOSYSTEM`, `PLAYBOOK`, `AGENTIC`, `NEUROSYM`, `CLADE`, and `anchors/ANCHOR`, - in deed, so tools and agents can read the project's state and boundaries. -* *AI gatekeeper protocol* — `bactrian_chora.deed` (the repo deed) is the - universal entry point that tells an AI agent how to work in this repo before it - touches anything; it carries the AI allocation policy and the ply directory tree. -* *Typed ABI/FFI seam* — `src/interface/Abi/` (Idris2 type + layout proofs) over - `src/interface/ffi/` (Zig implementation), with generated C headers. -* *CI/CD* — GitHub Actions for quality, security (CodeQL, Scorecard, secret - scanning), multi-forge mirroring, and RSR anti-pattern enforcement. -* *Supply-chain & reproducibility* — container layering (stapeln), Guix shells, - SBOM, and signing hooks. -* *Governance* — `GOVERNANCE.adoc`, `MAINTAINERS.adoc`, `.github/` community health - files, and a release `AUDIT.adoc` gate. - -== Governance badges - -The *K9 conformance* badge in the row at the top becomes live after -`just repo-init` replaces the owner and repository placeholders in its URL -and an eligible push to `main` publishes it. It is published by -`.github/workflows/dogfood-gate.yml` to a generated *orphan* branch called -`governance-badges`, and read back through the shields endpoint. - -[cols="1,3",options="header"] -|=== -| Badge | What it means - -| green `success` -| The K9 lane ran for that commit on `main` and passed. - -| red `failure` -| The K9 lane ran for that commit on `main` and failed. - -| grey `skipped`, `cancelled`, `unavailable`, `unknown` -| That commit produced *no trustworthy* K9 result. Grey is not "pending" and - not a stale green: a skipped, cancelled or unavailable lane replaces an - earlier green badge with grey. -|=== - -* `governance-badges` is *generated output*. It deliberately has *no common - ancestor with `main`*, it has no pull request, and it must *never be merged*. - Recent pushes to it are ordinary badge refreshes. -* A run that would publish the same bytes makes *no commit at all*. -* Nothing in the badge pipeline can turn a failing validation green: only a - lane that ran and passed, with its artifact present, renders brightgreen. - -The full operational contract - the exact state table, how API errors are -classified, how concurrent publications are serialised, and how to repair a bad -file - is in link:.github/workflows/README.adoc[`.github/workflows/README.adoc`]. - -== Repository map - -The authoritative map is generated, so it cannot drift from the tree: -link:docs/architecture/REPOSITORY-MAP.adoc[docs/architecture/REPOSITORY-MAP.adoc] -(regenerate with `just repo-map`; CI fails if it is stale). - -The short version: - -[cols="1,3"] -|=== -| Path | What lives there - -| `README.adoc`, `CLAUDE.md` | Start here - humans and AI agents respectively. -| `src/`, `tests/` | The code and its tests. -| `docs/` | Human documentation, including the full map above. -| `.machine_readable/` | Manifests, contractiles and policies that tools read. -| `build/`, `Justfile` | Every task runs through `just`; phases live in `build/just/`. -| `ci/`, `.github/` | CI configuration; GitHub reads `.github/` and no other path. -|=== - -== Where to go next - -* link:docs/architecture/REPOSITORY-MAP.adoc[The repository map] — generated; what every directory is for. -* link:docs/EXPLAINME.adoc[EXPLAINME] — the engineering deep-dive: how the pieces actually work. -* link:docs/AFFIRMATION.adoc[AFFIRMATION] — the dated, signed honesty snapshot of the repo's true state. -* link:docs/AUDIT.adoc[AUDIT] — the release audit gate. -* link:docs/AI_INSTALLATION_GUIDE.adoc[AI installation guide] — for agents instantiating this template. -* link:.machine_readable/ai/PLACEHOLDERS.adoc[PLACEHOLDERS] — the full placeholder reference. +Template recipes such as `just readiness` are not yet wired to Bactrian. The +repository map is generated at +link:docs/architecture/REPOSITORY-MAP.adoc[docs/architecture/REPOSITORY-MAP.adoc]. +Contributors should read link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] and +link:CODE_OF_CONDUCT.adoc[CODE_OF_CONDUCT.adoc]. Report security issues as +described in link:.github/SECURITY.md[.github/SECURITY.md]. == Licence Code, configuration and scripts are link:LICENSE[Mozilla Public License 2.0] -(`MPL-2.0`); prose documentation is `CC-BY-SA-4.0`. Both texts live in -`LICENSES/`, and per-file `SPDX-License-Identifier` headers are authoritative. -The GitHub-detected licence is MPL-2.0 (the root `LICENSE`). Long-term -attribution uses Quantum-Safe Provenance — see -link:docs/legal/EXHIBIT-B-QUANTUM-SAFE.txt[the Quantum-Safe Provenance exhibit]. +(`MPL-2.0`). Prose documentation is `CC-BY-SA-4.0`. Both texts live in +`LICENSES/`. Per-file `SPDX-License-Identifier` headers are authoritative. diff --git a/docs/plan/ULTRAPLAN.adoc b/docs/plan/ULTRAPLAN.adoc new file mode 100644 index 0000000..d1f8c9e --- /dev/null +++ b/docs/plan/ULTRAPLAN.adoc @@ -0,0 +1,100 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell += Bactrian: plan to v1.0.0 +:revdate: 2026-11-15 +:toc: + +Bactrian is at research stage. It has design documents and a readiness +preflight. It has no proof engine and no OCaml code. This plan is the +execution layer. The work packages WP-00A to WP-09 and the gates G0 to G5 stay +in link:../status/BACTRIAN-ULTRAPLAN.adoc[the detailed plan]. The milestones 0 +to 6 stay in link:../architecture/BACTRIAN-IMPLEMENTATION-PLAN.adoc[the +implementation plan]. This file adds the v1.0.0 gates, the models and the +effort. + +The work that is shared with the sibling verifiers (`atoma`, `quintessence`, +`Apodeixis.jl`, `canonry`, `chancel`) is in the family plan, +`docs/plan/FAMILY-ULTRAPLAN.adoc` in `hyperpolymath/atoma`. IDs F1 to F12 and +waves W0 to W5 come from that plan. + +== Measured state on 2026-11-15 + +* `bash tests/bactrian/doctor_test.sh`: PASS. +* `bash scripts/bactrian/doctor.sh`: exit 2, "Preflight BLOCKED". This is the + designed result while the tools and the 8 authorities are not pinned. +* No product code exists, so no other check applies. + +== Open items that block all other work + +[cols="1,4,2",options="header"] +|=== +| ID | Item | Owner +| B0 | WP-00A: the maintainer decides that this repository is the product repository, not a customised template. The README now describes the product. The deed still has UNASSIGNED fields. | Owner (F2) +| B1 | The 8 upstream authorities in `.machine_readable/bactrian/authorities.lock` are UNPINNED. | Lead, WP-00 +| B2 | `mise.toml` lists Zig as `latest`, not a fixed version. Idris2 is not in it: it comes from pack. OCaml, Dune, Why3, Apalache, Dedukti, Coq and Lean have no source and no pin. | Lead, WP-00, F6 +| B3 | The ECHIDNA call interface was recorded as unknown. It is known now: `echidna prove --output json`, schema `echidna.prove.result/1`. That command checks one backend and verifies no certificate, so its result alone is not replay evidence (see "Replay" below). | Interface known; replay path open (B-2) +|=== + +== Definition of v1.0.0 + +The detailed plan ends at gate G5 (a COMPLETE receipt). v1.0.0 is G5 for all +three layers, plus the seven family gates. The text below is the Bactrian +reading. + +[cols="1,4,3",options="header"] +|=== +| Gate | Acceptance | Falsifier +| Language boundary | Closed pure OCaml subset. Effects, `Obj.magic`, exceptions outside the model and unlisted externals fail closed. | An excluded construct passes the subset check. +| Source connection | Obligations come from the typed tree of the compiled unit, bound to the compiler version and the dependency closure. | A body-only mutant keeps the old evidence. +| Semantics | Layer A through Why3. Layer B protocol rules. Layer C ABI obligations. The trusted computing base is published. | A protocol violation or an ABI layout error is accepted. +| Replay | A Why3 or SMT result becomes evidence only after two steps: an `echidna prove` result on a pinned ECHIDNA revision, and an independent kernel check of the same proof artifact. | UNKNOWN or a timeout becomes COMPLETE. A prove result with no kernel check is recorded as replay. +| Practical coverage | Three pilots, one for each layer. | A second project needs special cases. +| Assurance | Mutation and vacuity checks through ECHIDNA. The preflight and the gate run in CI. | A mutant survives because a gate did not run. +| Release and estate | Deed identity set. README, changelog and claims true. | The repository describes itself as a template. +|=== + +== Sequence + +[cols="1,4,1,1,3",options="header"] +|=== +| Stage | Work | Lead | Size | Exit evidence +| B-0 Truth (W0) | B0, B1, B2. WP-00A and WP-00. Pin the authorities and the tools. Flip the expected preflight status in `bactrian.yml`. | Owner for B0; Sonnet for pins | M | `doctor.sh` exits 0 on a pinned runner. Gate G0. +| B-1 Evidence spine (W1) | Adopt the family kit (F3) and the ECHIDNA client (F7). Do not write a local receipt format. Maps to WP-01. | Sonnet from the Opus kit | S | The preflight writes its result through the kit. +| B-2 Layer A, first obligation (W2) | One pure OCaml function: subset check, Why3 obligation, then replay as defined below. Maps to WP-02 to WP-05 and milestones 1 to 3. | Opus | L | The W2 family exit evidence, with the reuse measures. Gates G1 and G2. +| B-3 Layer C through `atoma` (W3, F8) | The Idris2 and Zig FFI seam. Zig code goes to `atoma`. Maps to WP-08. | Opus | L | A layout or ownership defect is rejected. +| B-4 Layer B after `quintessence` (W3, F9) | The actor protocol layer. Reuse the protocol rules and the Apalache model that `quintessence` builds. Add the OCaml front end only. Maps to WP-07. | Opus, advisor review | L | A protocol violation is rejected with a trace. +| B-5 Kernel chain and release (W4, W5) | Full proof transport, WP-06 and WP-09, milestone 6. Three pilots. Release audit (F12). | Opus; Sonnet for release | XL (split first) | Gate G5 for each layer. All seven gates pass. +|=== + +Bactrian is last in the family order for Layers B and C on purpose. It has no +code to protect, so it gains most from the kit and from the sibling results. +Start B-2 only after `atoma` or `Apodeixis.jl` closes W2 with the kit. + +Sonnet does the implementation tasks inside each stage from an Opus brief. +Haiku runs the scout pass before each step. The advisor reviews the close of +each stage and each change to a status word. + +== What "replay" means here + +`echidna prove` checks one backend and verifies no certificate. Its contract +(`docs/PROVE-RESULT-CONTRACT.adoc` in ECHIDNA) says so, and its +`trust.confidence` field is always `null` today. So a prove result alone is +not replay evidence. + +In this plan, replay is the two-step pattern that `atoma` runs in +`scripts/atoma-replay.sh`: an `echidna prove` result with the Coq backend, +then an independent `coqchk` pass and an audit of assumptions on the same +artifact. The receipt status stays INCOMPLETE. + +Before B-2 starts, the lead must record three things: the pinned ECHIDNA +revision, the proof artifact that Why3 hands over, and the independent checker +for it. If Why3 cannot produce an artifact that a kernel can check, B-2 exit +evidence is a prove result only. The plan must then say so, and gates G1 and +G2 must not call it replay. + +== Stop points + +* Do not write product code before B-0 closes. +* If Why3 cannot express the chosen subset, narrow the subset. Do not add a + second proof route. +* Do not start B-5 before it is split into parts of size L or smaller. diff --git a/docs/status/BACTRIAN-ULTRAPLAN.adoc b/docs/status/BACTRIAN-ULTRAPLAN.adoc index 1821008..6db7932 100644 --- a/docs/status/BACTRIAN-ULTRAPLAN.adoc +++ b/docs/status/BACTRIAN-ULTRAPLAN.adoc @@ -70,12 +70,14 @@ repo's declared identity and intended template/product role. The available check-run metadata identifies the failing steps but the job-log archive was unavailable to the workspace during this run. The recorded job -references are link:https://github.com/hyperpolymath/Bactrian/actions/runs/39815613568/job/119953305648[Canon lockstep], -link:https://github.com/hyperpolymath/Bactrian/actions/runs/39815613568/job/119953305493[RSR oracle], -link:https://github.com/hyperpolymath/Bactrian/actions/runs/39815613363/job/119953304259[estate audit], -and link:https://github.com/hyperpolymath/Bactrian/actions/runs/39815612574/job/119953301356[OpenSSF placeholder check]. +references are link:https://github.com/hyperpolymath/bactrian/actions/runs/39815613568/job/119953305648[Canon lockstep], +link:https://github.com/hyperpolymath/bactrian/actions/runs/39815613568/job/119953305493[RSR oracle], +link:https://github.com/hyperpolymath/bactrian/actions/runs/39815613363/job/119953304259[estate audit], +and link:https://github.com/hyperpolymath/bactrian/actions/runs/39815612574/job/119953301356[OpenSSF placeholder check]. Run IDs are historical evidence, not a guarantee these checks are still failing. +_Note (2026-11-15):_ re-checked locally: `bash scripts/check-no-placeholders.sh .` now passes. The other three hazards were not re-checked. + == Operating rules for every contributor === Start-of-task checklist diff --git a/docs/status/PROOF-NEEDS.adoc b/docs/status/PROOF-NEEDS.adoc index fc7e5d5..1b08ef3 100644 --- a/docs/status/PROOF-NEEDS.adoc +++ b/docs/status/PROOF-NEEDS.adoc @@ -1,6 +1,5 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -// Template: rsr-template-repo/docs/status/PROOF-NEEDS.adoc // Authoritative master list: ~/Desktop/PROOF-REQUIREMENTS-MASTER.adoc = Proof Requirements — BACTRIAN @@ -127,4 +126,3 @@ verification/proofs/ * Master list: `~/Desktop/PROOF-REQUIREMENTS-MASTER.adoc` * Proof status tracking: `PROOF-STATUS.adoc` (this repo) * Proven library: `proven` repo (Idris2 verified foundations) -* Template: `rsr-template-repo/docs/status/PROOF-NEEDS.adoc` diff --git a/docs/status/PROOF-STATUS.adoc b/docs/status/PROOF-STATUS.adoc index 8b47f09..8ec0975 100644 --- a/docs/status/PROOF-STATUS.adoc +++ b/docs/status/PROOF-STATUS.adoc @@ -1,6 +1,5 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -// Template: rsr-template-repo/docs/status/PROOF-STATUS.adoc // The per-claim proof record. Obligations are in PROOF-NEEDS.adoc. = Proof Status — bactrian diff --git a/docs/status/READINESS.adoc b/docs/status/READINESS.adoc index c142a3c..d957a42 100644 --- a/docs/status/READINESS.adoc +++ b/docs/status/READINESS.adoc @@ -5,7 +5,7 @@ *Standard:* link:https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades[Component Readiness Grades (CRG) v2.0 STRICT] + *Assessed:* 2026-11-12 + *Assessor:* Jonathan D.A. Jewell + -*Previous assessment:* __ +*Previous assessment:* none *Current Grade:* X @@ -65,14 +65,14 @@ Below B, any publication must be explicitly abstract or provisional. |=== | Metric | Value | Source -| Test count | __ | `docs/status/ROADMAP.adoc` or CI -| Formal-verification posture | __ | grep of proof dirs -| Dangerous patterns (`assert_total`, `unsafeCoerce`, `Obj.magic`) | __ | grep 2026-11-12 -| Per-unit README coverage | __ | filesystem scan of unit dirs -| CI status | __ | `.github/workflows/` -| RSR mandatory workflows | __ | `.github/workflows/` -| Third-party badges (if any) | __ | external -| LIVE deployment (if any) | __ | production +| Test count | not assessed | `docs/status/ROADMAP.adoc` or CI +| Formal-verification posture | not assessed | grep of proof dirs +| Dangerous patterns (`assert_total`, `unsafeCoerce`, `Obj.magic`) | not assessed | grep 2026-11-12 +| Per-unit README coverage | not assessed | filesystem scan of unit dirs +| CI status | not assessed | `.github/workflows/` +| RSR mandatory workflows | not assessed | `.github/workflows/` +| Third-party badges (if any) | not assessed | external +| LIVE deployment (if any) | none | production |=== ''' @@ -87,9 +87,7 @@ unless noted. |=== | Component | Grade | Posture | Evidence Summary | Promotion blocker | Last Assessed -| __ | X/F/E/D/C/B/A | __ | __ | __ | 2026-11-12 -| __ | … | … | … | … | 2026-11-12 -| __ | … | … | … | … | 2026-11-12 +| Preflight (`scripts/bactrian/doctor.sh`) | X | not assessed | Not assessed in this file. The only project test is `tests/bactrian/doctor_test.sh`. | Not assessed | not assessed |=== *Rules of thumb for populating this table:* @@ -109,8 +107,8 @@ unless noted. CRG v2.0 requires two new pieces of evidence on top of D: . *Active dogfooding in home context with no known home-context failures.* -** Start date: __. -** Home context: __. +** Start date: not started. +** Home context: not assessed. ** "No known failures" is a moving claim — must hold continuously across the evidence window (recommended: 4 weeks, daily use). ** Populate `== Dogfooding status` in `docs/status/ROADMAP.adoc` with one entry @@ -166,9 +164,9 @@ Real-world external feedback confirming value. Populate == 7. Summary (2026-11-12) -* Project grade: __. Why: _<1-2 line justification>_. -* Delta since last assessment: __. -* Next milestone: __. +* Project grade: X. No grade is awarded. No component has been assessed against the CRG criteria. +* Delta since last assessment: none (first assessment). +* Next milestone: not assessed. * Machine-readable grade line present (§ header) for `just crg-grade` / `just crg-badge`. ''' diff --git a/docs/status/ROADMAP.adoc b/docs/status/ROADMAP.adoc index e50b20d..6c688ef 100644 --- a/docs/status/ROADMAP.adoc +++ b/docs/status/ROADMAP.adoc @@ -4,20 +4,44 @@ == Current Status -Initial development phase. +Bootstrap, before any minimum viable product. The repository holds the +architecture, the plans and a fail-closed readiness preflight. It has no Dune +project, no OCaml code and no proof engine. No verification result exists. +All eight authority rows in `.machine_readable/bactrian/authorities.lock` are +`UNPINNED`. -== Milestones +Sources: +link:../architecture/BACTRIAN-IMPLEMENTATION-PLAN.adoc[implementation plan] and +link:BACTRIAN-ULTRAPLAN.adoc[ultra-plan]. The ultra-plan checklist controls +what counts as done. -=== v0.1.0 - Foundation -* [ ] Core functionality -* [ ] Basic documentation -* [ ] CI/CD pipeline +== Done -=== v1.0.0 - Stable Release -* [ ] Full feature set -* [ ] Comprehensive tests -* [ ] Production ready +* [x] Architecture specification and soundness contract documented. +* [x] Implementation sequence documented. +* [x] Readiness preflight `scripts/bactrian/doctor.sh` and its test + `tests/bactrian/doctor_test.sh`. The preflight is not a proof check. -== Future Directions +== Milestones (implementation plan) -_To be determined based on community feedback._ +* [ ] Milestone 0: pin inputs and provision the build. +* [ ] Milestone 1: Dune skeleton and fail-closed command model. +* [ ] Milestone 2: Layer A smallest useful proof. +* [ ] Milestone 3: capability and TINI integration. +* [ ] Milestone 4: Layer B protocol vertical slice. +* [ ] Milestone 5: Layer C one primitive. +* [ ] Milestone 6: full proof transport and release gate. + +== Work packages (ultra-plan) + +* [ ] WP-00A: reconcile repository identity and CI baseline. +* [ ] WP-00: select target, owners and assurance boundary. +* [ ] WP-01: pin tools, authorities and integration formats. +* [ ] WP-02: Dune project and command/status shell. +* [ ] WP-03: stable Core Spec IR and provenance. +* [ ] WP-04: compiler-libs PPX firewall and typed frontend. +* [ ] WP-05: contracts, totality, Why3 VCs and first theorem. +* [ ] WP-06: MPR capability footprints and TINI/R5. +* [ ] WP-07: actor protocol frontend, occupancy, K-CUT and Apalache. +* [ ] WP-08: Idris2/QTT, ZigProve and OCaml GC ABI. +* [ ] WP-09: ECHIDNA closure, mutations, cache and release profile. diff --git a/docs/status/TEST-NEEDS.adoc b/docs/status/TEST-NEEDS.adoc index 699d886..465cbc7 100644 --- a/docs/status/TEST-NEEDS.adoc +++ b/docs/status/TEST-NEEDS.adoc @@ -2,125 +2,42 @@ // Copyright (c) Jonathan D.A. Jewell = TEST-NEEDS: bactrian -== CRG Grade: C — ACHIEVED 2026-04-04 +This file lists the tests that exist in this repository and the tests that +Bactrian still needs. No readiness grade is awarded here. -== Current State (Updated 2026-04-04) +== Project test -[cols="2,1,4", options="header"] -|=== -| Category | Count | Details +* `tests/bactrian/doctor_test.sh` tests `scripts/bactrian/doctor.sh`. +* It covers the blocked state, bad arguments and duplicate lock rows. +* CI runs it through `.github/workflows/bactrian.yml`. -| *Source modules* | 6 | 3 Idris2 ABI (Foreign, Layout, Types), 2 Zig FFI (build, main), 1 Zig integration test template -| *Unit tests* | 0 | None in main source (inline tests in main.zig) -| *Integration tests* | 1 | `test/integration_test.zig` (documented template, 1 placeholder test) -| *E2E tests* | 1 | `tests/e2e/template_instantiation_test.sh` (full instantiation + validation) -| *Workflow tests* | 1 | `tests/workflows/validate_workflows_test.sh` (21 workflows validated) -| *Validation tests* | 1 | `scripts/validate-template.sh` (8-phase comprehensive validation) -| *Benchmarks* | 5 | `benches/template_bench.sh` (validation, Zig build, tests, workflows, instantiation) -| *Fuzz tests* | 0 | `README.adoc` scaffold with harness instructions -|=== +== Inherited template tests -== Completed Work (CRG C - Testing & Benchmarking) +The estate template supplies the other tests. They check repository shape, +workflows and tooling. They do not test Bactrian logic. -=== Template Validation Script ✅ +* `tests/workflows/*_test.sh` +* `tests/shape/*_test.sh` +* `tests/e2e/`, `tests/e2e.sh` and `tests/aspect_tests.sh` +* `benches/template_bench.sh` (a benchmark of the template, not of Bactrian) -* [x] `scripts/validate-template.sh` — 8-phase validation -** Phase 1: Core repository structure (root files, directories) -** Phase 2: Machine-readable metadata (`.machine_readable/`) -** Phase 3: GitHub Actions workflows (17 required + all present) -** Phase 4: Idris2 ABI and Zig FFI source files -** Phase 5: Placeholder token replacement (skipped in template) -** Phase 6: SPDX license headers (100% coverage, 6/6 files) -** Phase 7: Build system verification (`zig build` + `idris2` syntax check) -** Phase 8: Documentation requirements (TOPOLOGY, ABI-FFI-README, etc) -* Status: *PASSING* (0 errors, 3 warnings about template placeholders) +The Zig test `src/interface/ffi/test/integration_test.zig` is template +scaffold. It contains a placeholder test. It has not been run in this +assessment. Bactrian has no Zig code of its own yet. -=== E2E Template Instantiation Test ✅ +== Tests Bactrian still needs -* [x] `tests/e2e/template_instantiation_test.sh` — full workflow -** Clones template to temp directory -** Runs the real `just repo-init` (never a second copy of its substitution list) -** Validates resulting structure with `scripts/validate-template.sh` -** Verifies Zig build works after instantiation -** Checks no placeholder survives, via `scripts/check-no-placeholders.sh` -** Cleans up temp directory +Each item waits on the work package named in +link:BACTRIAN-ULTRAPLAN.adoc[the ultra-plan]. -NOTE: this entry read `[x]` from the day it was written until 2026-07-17, while -the test aborted at its first substitution line (`file: unbound variable`) on -every invocation. Nothing noticed: CI ran `tests/e2e.sh`, which did not call it, -and its only caller — `benches/template_bench.sh` — pipes it to `/dev/null` and -appends `|| true`, so it was timing a script that died instantly. The tick was -copied from the test's intent, not from a run. Tick these boxes from observed -output only. -* Status: *READY TO TEST* (can be verified by CI) +* Status machine and command tests (WP-02). +* Core Spec IR and provenance tests (WP-03). +* AST firewall tests (WP-04). +* First Layer A theorem through ECHIDNA (WP-05). +* Capability and TINI tests (WP-06). +* Actor protocol, K-CUT and Apalache tests (WP-07). +* ABI manifest and Zig boundary tests (WP-08). +* Cross-layer mutation tests (WP-09). -=== Workflow Validation Test ✅ - -* [x] `tests/workflows/validate_workflows_test.sh` -** Validates all 21 workflows exist and have proper structure -** Checks SPDX headers, `name` field -** Verifies all 15 required workflows present -* Status: *PASSING* (0 errors, 15/15 required workflows found) - -=== Zig FFI Tests ✅ - -* [x] `src/interface/ffi/test/integration_test.zig` — template with examples -** Converted from the lowercase project placeholders to "template" namespace -** Added comprehensive comments for how to instantiate -** Tests grouped by category (lifecycle, operations, strings, errors, version, memory safety, threading) -** Compiles and passes placeholder test -* Status: *PASSING* (1 test: `placeholder_test_implementation_required` passes) - -=== Benchmarks ✅ - -* [x] `benches/template_bench.sh` — 5 benchmark suites -** Validation script: ~5.8s average (3 runs) -** Zig build: ~19ms (clean build) -** Zig tests: ~20ms -** Workflow validation: ~117ms -** Template instantiation: ~427ms -* Formats: human, json, csv -* Status: *PASSING* (all benchmarks execute) - -=== Build System ✅ - -* [x] `src/interface/ffi/build.zig` — updated for Zig 0.15.2 -** Simplified to test-only configuration -** Supports both unit tests and integration tests -** Works with `zig build` without errors -* Status: *PASSING* (builds successfully) - -== Test Results Summary - ----- -Validation Script: PASS (0 errors, 3 warnings) -Workflow Validation: PASS (21/21 workflows valid) -Integration Tests: PASS (1/1 placeholder test) -E2E Instantiation: READY (needs CI confirmation) -Benchmarks: PASS (5/5 benchmark suites) -Build System: PASS (zig build succeeds) ----- - -== CRG C Compliance - -* *Coverage*: 6/6 test categories (unit, integration, E2E, workflow, validation, benchmarks) -* *Documentation*: All test files have SPDX headers + inline documentation -* *Author Attribution*: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> -* *License*: MPL-2.0 on all new files -* *Automation*: All scripts executable + working - -== FLAGGED ISSUES - ALL RESOLVED - -* [.line-through]#*Template repo used by ALL new repos has 0 validation tests*# → FIXED: 4 test suites + validation script -* [.line-through]#*fuzz/placeholder.txt*# → FIXED: replaced with `README.adoc` containing real harness instructions -* [.line-through]#*No E2E tests for template instantiation*# → FIXED: full E2E test suite -* [.line-through]#*Zig FFI integration tests are placeholders*# → FIXED: converted to documented template format - -== Next Steps (Future Sessions) - -* [ ] Integrate test scripts into CI/CD workflows -* [ ] Generate test coverage reports -* [ ] Add more specialized benchmarks (memory, threading stress) -* [ ] Document test instantiation patterns for new repos - -== Priority: P0 (COMPLETE) ✅ +Unit tests, integration tests, fuzz tests and benchmarks for Bactrian: not +assessed, because no executable product code exists.