diff --git a/.machine_readable/contractiles/README.adoc b/.machine_readable/contractiles/README.adoc index ce034e1..7c83255 100644 --- a/.machine_readable/contractiles/README.adoc +++ b/.machine_readable/contractiles/README.adoc @@ -4,11 +4,11 @@ :toc: :sectnums: -This directory contains the canonical contractile templates for the -hyperpolymath estate. `rsr-template-repo` mirrors the standards master -structure; copy `.machine_readable/contractiles/` into a new repo to -establish a consistent operational, validation, trust, recovery, -aspiration, and service-automation framework. +This directory holds this repository's copy of the estate contractile set. It +follows the structure of the standards master, by way of `rsr-template-repo` +(the repository this one was minted from). The same set can be copied into +another repo to establish a consistent operational, validation, trust, +recovery, aspiration, and service-automation framework. [IMPORTANT] ==== diff --git a/docs/AI_INSTALLATION_GUIDE.adoc b/docs/AI_INSTALLATION_GUIDE.adoc index ceb61fe..9a3dc2b 100644 --- a/docs/AI_INSTALLATION_GUIDE.adoc +++ b/docs/AI_INSTALLATION_GUIDE.adoc @@ -5,9 +5,9 @@ :toclevels: 3 :sectnums: -This guide is for an **AI agent** instantiating this template into a new -repository. A human following it will not be misled, but the ordering and the -warnings are written for an agent working non-interactively. +This guide is for an *AI agent* installing, using or verifying the Julia +package `CoprocessorRuntime.jl`. A human following it will not be misled; the +ordering and the warnings are written for an agent working non-interactively. [[ai-implementation]] == Implementation for an AI agent @@ -16,118 +16,93 @@ warnings are written for an agent working non-interactively. Read, in this order, before running anything: -. `*_chora.deed` (the repo deed) — the universal AI entry point at the repository root. -. `CLAUDE.md` — the generated arrival pack (estate doctrine + repo identity). -. `.machine_readable/descriptiles/STATE.a2ml` — current phase and completion. +. `*_chora.deed` (the repo deed) at the repository root. +. `CLAUDE.md` -- the generated arrival pack (estate doctrine and repo identity). +. `README.adoc` -- what the package is and is not. -Do not infer the repository's purpose from its name. If a fact is not written -down, record it as `UNASSIGNED` rather than inventing it. +Do not infer the package's capabilities from its name. It is a host-side +contract and evidence layer: it records launch semantics and does not run +accelerator kernels, select a backend, or prove CNO/OND. If a fact is not +written down, report it as unknown rather than inventing it. -=== 2. Obtain the template +=== 2. Install the package as a dependency -Always take the template from `origin/main`, never from a local working tree — -local checkouts across this estate are routinely stale or carry sweep debris. +The package is not in the Julia General registry. Install it by URL: -[source,bash] +[source,julia] ---- -git clone https://github.com/hyperpolymath/rsr-template-repo.git my-project -cd my-project -rm -rf .git && git init +using Pkg +Pkg.add(url="https://github.com/hyperpolymath/CoprocessorRuntime.jl") ---- -Alternatively, use GitHub's *Use this template* button, which produces a repo -with no git ancestry; `just repo-init` recovers the template tip via -`git ls-remote` and records it as the `parent-pin`. +It needs Julia 1.10 or later and has no dependencies of its own. +`AcceleratorGate.jl` is an optional weak dependency, also not in General; add it +by URL only if the `coprocessor_kind` mapping is wanted. + +=== 3. Or work on a checkout -=== 3. Run the instantiation +When no revision is requested, take the repository from `origin/main`, never +from a stale local working tree. When a pull request or branch is named, check +out and test that revision instead. [source,bash] ---- -just repo-init # or: just repo-init +git clone https://github.com/hyperpolymath/CoprocessorRuntime.jl.git +cd CoprocessorRuntime.jl +julia --project=. -e 'using Pkg; Pkg.test()' ---- -`just repo-init` renders every `{{TOKEN}}` in the tree, derives the repository -identity, writes the provenance files, and removes the template-only -directories. +`Pkg.test()` runs Aqua and the case files in `test/cases`. On Julia 1.11 it +also runs `test/ext` in a subprocess, which fetches `AcceleratorGate` from +GitHub; on Julia 1.10 that step is recorded as one `Broken` test. Set +`COPROCESSORRUNTIME_SKIP_EXT_TESTS=1` to skip it (it is then also recorded as +one `Broken` test, not dropped). [WARNING] ==== -**Do not set `RSR_NON_INTERACTIVE=1`.** It stubs the shell builtin `read` -globally, which also disables the two `while read -r file` loops that drive -substitution. The result is an infinite loop that performs zero substitution — -it does not fail, it never terminates. - -Drive it non-interactively by **piping answers to stdin** instead. Real `read` -stays intact, so the data loops work. -==== - -The prompts, in order, are: - -[cols="1,3",options="header"] -|=== -| # | Prompt - -| 1 | Project name -| 2 | Repository slug — validated against `^[a-z0-9]+(-[a-z0-9]+)*$`; no capitals, spaces or underscores (it must be a valid Guix package name) -| 3 | Owner -| 4 | Author full name -| 5 | Author email -| 6 | Author organisation -| 7 | Previous/alternate email -| 8 | Project description -| 9 | Forge domain -| 10 | Security email -| 11 | Conduct email -| 12 | Project type -| 13 | Website URL (blank = default) -| 14 | OpenSSF Best Practices ID (blank = none) -| 15 | Service name (blank = default) -| 16 | Primary port (blank = 8080) -| 17 | Container registry (blank = default) -| 18 | Proceed? — answer `y` -|=== - -[IMPORTANT] -==== -Prompts 15–17 are gated on the presence of the container directory, **not** on -the project type. The template always ships one, so they always fire. Supplying -only 15 answers makes `read` hit EOF, which returns 1 and kills the recipe under -`set -e`. +Running the tests on Julia 1.11 writes `test/ext/Manifest.toml`, and +`--project=.` use writes a root `Manifest.toml`. Both are listed in +`.gitignore`; do not force-add them. Use a scratch copy and a scratch +`JULIA_DEPOT_PATH` if the working tree must stay clean. ==== === 4. Verify the result -[source,bash] +[source,julia] ---- -just --list # every recipe resolves (imports are silent on failure) -just check-root-shape # root matches the allowlist -bash scripts/check-no-placeholders.sh . -just verify +using CoprocessorRuntime +s = open_session(GPUKind()) +r = issue_receipt(s; warrant = WarrantOnly, claim = "planned") +@assert !host_may_claim(r) +close_session!(s) ---- -A successful instantiation leaves **no** `{{TOKEN}}` anywhere in the tree, and -removes the template-only directories from the minted repository. If -`scripts/validate-template.sh` or the end-to-end instantiation test are still -present, the repository was not cured — they are the clearest single marker of -an un-instantiated repo. +A correct install loads without error and the assertion passes. See +`QUICKSTART.adoc` for a longer first run and its expected output. + +=== 5. What not to claim + +* Do not report a CNO or OND claim as proved. Status is `:unproved` or + `:model_checked`. +* Do not report a receipt as host knowledge unless `host_may_claim` is true. +* Do not treat `Idris`, `Zig` or other files under `src/interface/` as the + Julia API; that seam is not wired to this package (`src/README.adoc`). == Privacy -This template performs no telemetry and transmits nothing during installation. +The package performs no telemetry and makes no network requests: `src/` and +`ext/` contain no network or file I/O. -Note what instantiation *records*, all of it locally and in your own git history: +What does touch the network is installation and testing, not the package: -* The identity you supply at prompts 3–7 (owner, author name, both email - addresses, organisation) is written into source headers, `CITATION.cff`, - `.mailmap`, `CODEOWNERS` and the security contact. Treat the alternate email - as published data. -* `just repo-init` runs `git ls-remote` against the template's forge to resolve - the parent pin. This is a single outbound request; when it is unavailable the - pin is recorded as `UNASSIGNED` rather than guessed. -* The clade UUID is *derived*, never allocated: - `uuidgen --sha1 --namespace @url --name "//"`. It is a - function of the repository's name, so renaming the repository changes it and - registries must be regenerated rather than string-swapped. +* `Pkg.add(url=...)` and `git clone` fetch from GitHub. +* `Pkg.test()` on any supported Julia needs the Aqua test dependency + (`[extras]` and `[targets]` in `Project.toml`). With an empty depot, even on + Julia 1.10, where the extension tests are skipped, it can download Aqua and + the General registry data needed to resolve it. +* `Pkg.test()` on Julia 1.11 also fetches `AcceleratorGate.jl` from GitHub at + the commit pinned in `test/ext/Project.toml`, and may update the Julia General + registry. -If you are an agent acting on someone else's behalf, do not invent identity -values to satisfy a prompt. Leave them `UNASSIGNED` and report the gap. +Do not invent identity values (owner, author, email) when editing files; report +a gap instead. diff --git a/docs/EXPLAINME.adoc b/docs/EXPLAINME.adoc index c8ca0f6..7fbed03 100644 --- a/docs/EXPLAINME.adoc +++ b/docs/EXPLAINME.adoc @@ -1,115 +1,141 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -= RSR Template Repo - Explainme += CoprocessorRuntime.jl - Explainme image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] :toc: :icons: font -This file explains how the key template claims map to real files. +This file explains what `CoprocessorRuntime.jl` records, which source file holds +what, and where its claims stop. The `README.adoc` is the short version. -== Central Session Protocol Authority +== What it is -Claim: -Session protocols are centrally maintained and not duplicated in this template. +A host-side contract and evidence layer for coprocessor launches. It models +host and device roles, resource grades, transfer residues, launch receipts and +CNO/OND claims. It records launch semantics; it does not run accelerator +kernels, and it has no dependencies beyond Julia itself (`[deps]` in +`Project.toml` is empty). -How this is implemented: +It is a Julia library, not an application. It is installed by URL, not from the +General registry (see `QUICKSTART.adoc`). -* The local dispatcher (`session/dispatch.sh`) maps canonical commands to central - protocol paths in `standards/3-practice/session-management-standards`. -* Local files (`session/custom-checks.k9`, `session/local-hooks.sh`, - `coordination.k9`) are integration-only. +== What it records -Caveat: +[cols="1,2,2",options="header"] +|=== +| Question | Answer in this package | Source -* If `SESSION_STANDARDS_DIR` is unset and no adjacent standards checkout exists, - the dispatcher records the command but cannot resolve central checklist paths. +| Which endpoint am I? +| `HostRole` / `DeviceRole`, projected out of a `LaunchPlan` +| `src/Kinds.jl`, `src/Choreography.jl` -== Canonical Command Surface +| What is the worst-case cost? +| `ResourceGrade`: bytes, nanoseconds, joules; `tropical_seq` adds, `tropical_alt` takes the maximum +| `src/Grades.jl` -Claim: -Template bindings align to one canonical command model. +| What was lost in the transfer? +| `EchoResidue` on a `TransferMap` that is, or is not, injective and reversible +| `src/EchoLoss.jl` -How this is implemented: +| What may the host claim afterwards? +| `LaunchReceipt` with a standpoint, a `WarrantKind` and a `sound` flag +| `src/Receipts.jl` -* `Justfile` provides thin aliases (`intake-repo`, `checkpoint-change`, - `verify-maintenance`, `verify-substantial`, `verify-release`, `close-planned`, - `close-urgent`, `recover-repo`, `handover-*`). -* Every alias calls `session/dispatch.sh` with canonical verb-object pairs. +| Did a reset do nothing, and did a channel reveal nothing? +| `CNOClaim` and `ONDClaim`, whose `status` is meant to be `:unproved` or `:model_checked`; the constructors accept any `Symbol`, and only `observe_null` rejects other values +| `src/Nullity.jl` -Caveat: +| Can one adapter speak every vendor protocol? +| No: `universal_hub_allowed()` throws `HubCeilingRefusal` +| `src/Choreography.jl` +|=== -* Recipes are wrappers only. They do not replace protocol content from - the central standards repo. +== Where each piece lives -== Runtime State Is Local +`src/CoprocessorRuntime.jl` declares the module, the export list and the +`include` order. The seven files it includes: -Claim: -Session state is per-repository runtime output, not standards text. +[cols="1,3",options="header"] +|=== +| File | Holds -How this is implemented: +| `Kinds.jl` +| `Role` (`HostRole`, `DeviceRole`); `CoprocessorKind` (`CPUKind`, `GPUKind`, `NPUKind`, `TPUKind`, `FPGAKind`, `QPUKind`, `DSPKind`, `UnknownKind`); `kind_label`; the method-less function `coprocessor_kind` -* `session/dispatch.sh` writes command and continuity-core capture stubs to - `.session/LAST-CANONICAL-COMMAND.md` in the target repository path. +| `Grades.jl` +| `ResourceGrade` (rejects negative fields), `tropical_seq`, `tropical_alt`, `dominates` -Caveat: +| `EchoLoss.jl` +| `TransferMap`, `EchoResidue`, `injective_transfer`, `collapsing_transfer` -* Runtime files are intentionally lightweight and require human/agent completion. +| `Sessions.jl` +| `Session{K}`, `open_session`, `close_session!`, `isopen` -== Template Token Policy +| `Receipts.jl` +| `WarrantKind` (`Knowledge`, `Belief`, `WarrantOnly`, `Unsound`), `LaunchReceipt`, `issue_receipt`, `host_may_claim` -Claim: -Placeholders are explicit template content until initialization. +| `Nullity.jl` +| `CNOClaim`, `ONDClaim`, `InverseMeta`, `inversion_of`, `irreversible`, `reset_session!`, `observe_null` -How this is implemented: +| `Choreography.jl` +| `Endpoint`, `LaunchPlan`, `launch_plan`, `project`, `projected_grade`, `HubCeilingRefusal`, `universal_hub_allowed` +|=== -* `README.adoc` and bootstrap recipes keep `{{TOKEN}}` placeholders visible. -* `just init` performs token replacement. +`ext/AcceleratorGateExt.jl` is a package extension, described below. +`STATE-VISUALIZER.adoc` shows how these files depend on each other. -Caveat: +== Reading the claims honestly -* Uninitialized placeholders must not be treated as project-specific truth. - -== Dependency Updates (Dependabot) - -Claim: -Dependency bumps land fast and safely, without manual chasing. - -How this is implemented: - -* `dependabot.yml` watches the Dependabot-supported ecosystems the estate - actually uses: `github-actions`, `cargo`, `mix` (Elixir), `docker`. -* `dependabot-automerge.yml` auto-merges *every* bump (patch/minor/major, - security or routine) **once the required checks are green** — a broken bump - fails CI and stays open (you get an email); it never lands on a red `main`. - -Caveat: - -* Dependabot has **no or Bun ecosystem**, and `pnpm` only rides under the - `npm` ecosystem (itself banned). For this -first estate Dependabot cannot - watch the runtime dependencies; the `npm`/`pip` entries are retained only for - transitional/legacy manifests and are otherwise inert. dependency - currency is managed via `.json`/`.lock`, not Dependabot. -* Do **not** add Dependabot as a ruleset *bypass* actor: that lets bumps skip - the required checks (secret-scanning, SAST), removing the safety gate and the - "it broke" signal. Auto-merge-on-green gives fast merges without it. - -== Julia Registry Packages — Standalone Repo Requirement - -Claim: -If this template is used to create a Julia package, it must remain a standalone repository registered with the Julia package registry. - -How this is implemented: - -* Julia's package registry (General.jl or other) expects each package to be a standalone GitHub repository with `Project.toml` at the repository root. -* Installation via `Pkg.add()`, dependency resolution, and automated CI/CD all depend on this canonical structure. - -Caveat: - -* Do NOT move this repository into a monorepo or subdirectory, as this breaks registry registration and package discoverability. -* Julia packages published to a registry must each remain a standalone top-level repository (registry registration and package discovery require it). -* Non-registry Julia packages can be organized differently if they are not published to any registry. +These rules are in the code, and they are the point of the package: +* *A session is a handle.* `open_session` allocates nothing on a device and + does not prove a device exists (`src/Sessions.jl`). +* *Receipts default to unsound.* `issue_receipt` sets `sound = false` unless + told otherwise. `host_may_claim` is true only for a `:host` standpoint with + `Knowledge` warrant and `sound == true`. A `:device` standpoint with + `Knowledge` and no soundness check is refused with an `ArgumentError` + ("smuggling") (`src/Receipts.jl`). +* *CNO and OND are claims, not proofs.* `reset_session!` reports + `:model_checked` when the handle came back with the same id and open; that is + a host-side handle check, not a device reset. `observe_null` defaults to + `:unproved` and accepts only `:unproved` or `:model_checked` + (`src/Nullity.jl`). +* *Unstated energy is not free.* `joules == 0.0` means unstated, and unstated + energy does not dominate a stated energy (`src/Grades.jl`). +* *K-CUT stays open.* `project` always returns `kcut = :open`. It returns + `grade_eq = true` only when the plan's transfer map is injective, and + otherwise `warrant_bound = :open` (`src/Choreography.jl`). + +== The AcceleratorGate extension + +`AcceleratorGateExt` is loaded by Julia only when `AcceleratorGate.jl` is also +loaded (`[weakdeps]` and `[extensions]` in `Project.toml`). It adds methods of +`coprocessor_kind` that map an AcceleratorGate backend type to a +`CoprocessorKind`, so a session can be opened with +`open_session(coprocessor_kind(backend))`. It selects nothing and runs nothing. +Four backends (`PPUBackend`, `MathBackend`, `VPUBackend`, `CryptoBackend`) map +to `UnknownKind`, because this package has no kind for them. Without +AcceleratorGate loaded, `coprocessor_kind` has no methods and a call is a +`MethodError`, on purpose. + +== What it is not + +* Not an executor of CUDA, ROCm, Metal or TPU kernels: that is `CUDA.jl`, + `AMDGPU.jl`, `Metal.jl` and `KernelAbstractions.jl`. +* Not a backend selector: that is `AcceleratorGate.jl`. +* Not a healer of failing kernels: that is `HardwareResilience.jl`. +* Not a proof of CNO or OND: that is `absolute-zero`. Status here is + `:unproved` or `:model_checked`. +* Not a closure of K-CUT: that conjecture is open in `choreographic-types`. + +== Around the package + +The repository also carries estate scaffolding that is not part of the Julia +API: the local session bindings in `session/` (see `session/README.adoc`), the +`Justfile`, CI under `.github/workflows/`, and the machine-readable state under +`.machine_readable/`. `architecture/REPOSITORY-MAP.adoc` is the generated map +of the tree. == License diff --git a/docs/QUICKSTART.adoc b/docs/QUICKSTART.adoc index ce9198e..12a2a1c 100644 --- a/docs/QUICKSTART.adoc +++ b/docs/QUICKSTART.adoc @@ -3,24 +3,99 @@ = Quickstart :toc: preamble -Get up and running in 60 seconds. +Install `CoprocessorRuntime.jl` and record a first launch plan. This is a +library: nothing runs on a device, and nothing is started. == Prerequisites -* Git 2.40+ -* just (command runner) -* Your language toolchain (see Justfile for details) +* Julia 1.10 or later (`julia = "1.10"` in `Project.toml`). +* Network access to GitHub. The package is not in the Julia General registry, + so it is installed by URL. -== From Template (New Project) +== Install + +[source,julia] +---- +using Pkg +Pkg.add(url="https://github.com/hyperpolymath/CoprocessorRuntime.jl") +---- + +This resolves package version 0.1.0 from the `main` branch. The package has no +dependencies of its own. + +== First use + +[source,julia] +---- +using CoprocessorRuntime + +s = open_session(GPUKind()) +plan = launch_plan( + :matmul, + [Endpoint(HostRole(), CPUKind()), Endpoint(DeviceRole(), GPUKind())], + ResourceGrade(1 << 20, 10_000, 0.0), + EchoResidue(collapsing_transfer(:f32_to_f16), "mantissa fibre"), +) +local_view = project(plan, DeviceRole()) +@show local_view.kcut local_view.grade_eq local_view.warrant_bound + +receipt = issue_receipt(s; warrant = WarrantOnly, claim = "planned") +@show host_may_claim(receipt) + +cno = reset_session!(s) +@show cno.status + +close_session!(s) +@show isopen(s) +---- + +Expected output: + +---- +local_view.kcut = :open +local_view.grade_eq = false +local_view.warrant_bound = :open +host_may_claim(receipt) = false +cno.status = :model_checked +isopen(s) = false +---- + +Read it as follows. The transfer map is collapsing, so the projection does not +claim the grade equals the global grade (`grade_eq = false`), and K-CUT is not +claimed (`kcut = :open`). A receipt with `WarrantOnly` warrant is not a factive +claim. `:model_checked` for the reset means the host-side handle came back +open with the same id; it is not a device reset and not a proof. + +== Optional: AcceleratorGate backends + +With `AcceleratorGate.jl` also installed (it is not in General either, so add +it by URL), the package extension maps a backend to a kind: + +[source,julia] +---- +Pkg.add(url="https://github.com/hyperpolymath/AcceleratorGate.jl") +using CoprocessorRuntime, AcceleratorGate +coprocessor_kind(CUDABackend(0)) # GPUKind() +---- + +Without `AcceleratorGate` loaded, `coprocessor_kind` has no methods and a call +is a `MethodError`. + +== Run the package's own tests + +From a checkout of the repository: [source,bash] ---- -git clone https://github.com/hyperpolymath/rsr-template-repo my-project -cd my-project -rm -rf .git && git init -b main -just repo-init # interactive placeholder replacement +julia --project=. -e 'using Pkg; Pkg.test()' ---- -== Project Structure +On Julia 1.11 this also runs the extension tests in `test/ext`, which fetch +`AcceleratorGate` from GitHub. On Julia 1.10 that part is recorded as one +`Broken` test. See `status/TEST-NEEDS.adoc`. + +== Where next -See README.adoc in the root for the Dual-Track architecture summary. +* `EXPLAINME.adoc` for what each type records and what it does not. +* `STATE-VISUALIZER.adoc` for the file topology. +* `README.adoc` at the repository root. diff --git a/docs/RSR_OUTLINE.adoc b/docs/RSR_OUTLINE.adoc index 9bbe401..ded9fbb 100644 --- a/docs/RSR_OUTLINE.adoc +++ b/docs/RSR_OUTLINE.adoc @@ -1,258 +1,40 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -= RSR Template Repository - -image:https://img.shields.io/badge/Code-MPL--2.0-blue.svg[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[Docs licence: CC-BY-SA-4.0,link="https://creativecommons.org/licenses/by-sa/4.0/"] += RSR Outline :toc: -:sectnums: - -// Badges -image:https://img.shields.io/badge/RSR-Infrastructure-cd7f32[RSR Infrastructure] -image:https://img.shields.io/badge/Phase-Maintenance-brightgreen[Phase] -image:https://img.shields.io/badge/Guix-Primary-purple?logo=gnu[Guix] - -[IMPORTANT] -==== -*Superseded as an overview.* The root `README.adoc` is the entry point, and the -authoritative directory map is generated at -link:architecture/REPOSITORY-MAP.adoc[architecture/REPOSITORY-MAP.adoc]. - -This document is kept for its longer-form rationale, not as a second README. -Its hand-written directory tree was removed in 2026-08 after being found stale -in six places at once (a2ml files listed outside `descriptiles/`, `Trustfile.hs` -for `Trustfile.a2ml`, `docs/CITATIONS.adoc` and `docs/TOPOLOGY-GUIDE.adoc` which -do not exist, and `src/interface/Abi/` which was renamed to lowercase). -==== - -== Overview - -**The canonical template for RSR (Rhodium Standard Repository) projects.** - -This repository provides the standardized structure, configuration, and tooling for all RSR-compliant repos. Use it to: - -* Bootstrap new projects with RSR compliance -* Reference the standard directory structure -* Copy configuration templates (Justfile, STATE.a2ml, etc.) - -== Quick Start -[source,bash] ----- -# Clone the template -git clone https://github.com/hyperpolymath/RSR-template-repo my-project -cd my-project +`CoprocessorRuntime.jl` follows the Rhodium Standard Repository (RSR) +conventions of the hyperpolymath estate (badge in the root `README.adoc`). This +repository was minted from `rsr-template-repo`; it is *not* that template. It is +a Julia library, and the package itself is described in `README.adoc` and +`EXPLAINME.adoc`. -# Remove template git history -rm -rf .git -git init +This file used to be a copy of the template's own overview ("the canonical +template for RSR projects", with its quick start, recipe list and file +checklist). That text described the template, not this package, and has been +removed. The RSR outline itself is maintained upstream, in +`docs/RSR_OUTLINE.adoc` of https://github.com/hyperpolymath/standards[hyperpolymath/standards]. -# Interactive bootstrap — replaces all placeholders -just repo-init +== `.well-known` metadata -# Enter development environment -guix shell -D -f build/guix.scm +The RFC 8615 metadata files live in `www/.well-known/` in this repository: +`security.txt`, `ai.txt`, `humans.txt` and `aibdp.json`. A repository-root +`.well-known/` is the legacy location. This repository has none; +`scripts/migrate-wellknown-to-www.sh` moves one into `www/.well-known/` and +`scripts/sweep-wellknown.sh` drives that across repositories (`rsr-template-repo#53`). +`www/README.adoc` describes the `www/` bundle. -# Validate compliance -just validate-rsr ----- +== Where to look here instead -== What's Included - -[cols="1,3"] +[cols="1,2",options="header"] |=== -|File/Directory |Purpose - -|`.editorconfig` -|Editor configuration (indent, charset) - -|`.gitignore` -|Standard ignore patterns - -|`.gitattributes` -|Line endings, diff drivers, binary detection - -|`.guix-channel` -|Guix channel definition - -|`www/` -|Site-operations bundle; RFC-compliant metadata at `www/.well-known/` (security.txt, ai.txt, humans.txt) - -|`.machine_readable/` -|All machine-readable content: state files (6 a2ml), `bot_directives/`, `contractiles/` - -|`docs/` -|Documentation directory - -|`build/guix.scm` -|Guix package definition (canon 1.2.1 guix-primary names `build/`) - -|`Justfile` -|Task runner with 40+ recipes - -|`Containerfile` -|Container build (Wolfi base, Podman) - -|`LICENSE` -|MPL-2.0 (code) / CC-BY-SA-4.0 (docs) - -|`EXHIBIT-A-ETHICAL-USE.txt` -|MPL-2.0 source-code-form license notice (LICENSE Exhibit A) - -|`EXHIBIT-B-QUANTUM-SAFE.txt` -|Quantum-safe provenance spec (LICENSE Exhibit B) - -|`README.adoc` -|Project overview - -|`TOPOLOGY.md` -|Architecture diagram and completion dashboard - -|`PLACEHOLDERS.md` -|Template variable reference and replacement guide - -|`*_chora.deed` (repo deed) -|Universal AI agent entry point - -|`AI.a2ml` -|Claude-specific instructions - -|`src/interface/Abi/` -|Idris2 ABI definitions (Types, Layout, Foreign) - -|`ffi/zig/` -|Zig FFI implementation - -|`generated/abi/` -|Auto-generated C headers from Idris2 ABI +| Need | File + +| What the package is and is not | `README.adoc`, `EXPLAINME.adoc` +| Install and first use | `QUICKSTART.adoc` +| Module and file topology | `STATE-VISUALIZER.adoc` +| The directory map of the repository (generated, checked in CI) | `architecture/REPOSITORY-MAP.adoc` +| Repository identity and agent permissions | the `*_chora.deed` at the repository root +| Tests and what is missing | `status/TEST-NEEDS.adoc` +| Milestones | `status/ROADMAP.adoc` is where milestones go; it has not been filled in for this package yet (it is still the template's placeholder) |=== - -== Justfile Features - -The template Justfile provides: - -* **Combinatoric matrix recipes** for build, test, container, CI -* **Cookbook generation**: `just cookbook` -> `docs/just-cookbook.adoc` -* **Man page generation**: `just man` -> `docs/man/project.1` -* **RSR validation**: `just validate-rsr` -* **STATE.a2ml management**: `just state-touch`, `just state-phase` -* **Container support**: `just container-build`, `just container-push` -* **CI matrix**: `just ci-matrix [stage] [depth]` - -=== Key Recipes - -[source,bash] ----- -just # Show all recipes -just help # Detailed help -just info # Project info -just combinations # Show matrix options - -just build # Build (debug) -just test # Run tests -just quality # Format + lint + test -just ci # Full CI pipeline - -just validate # RSR + STATE validation -just docs # Generate all docs -just cookbook # Generate Justfile docs - -just guix-shell # Guix dev environment -just container-build # Build container ----- - -== Directory Structure - -[source] -See link:architecture/REPOSITORY-MAP.adoc[REPOSITORY-MAP.adoc] for the -directory map. It is generated from the tree and diffed in CI, so unlike the -hand-written tree that used to sit here it cannot go stale. - - -== RSR Compliance - -=== Language Tiers - -* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, , Gleam -* **Tier 2** (Silver): Nickel, Guile Scheme, Idris2, OCaml -* **Infrastructure**: Guix channels, derivations, Julia batch scripts - -=== Required Files - -* `.editorconfig` -* `.gitignore` -* `Justfile` -* `README.adoc` -* `LICENSE` (MPL-2.0) -* `.machine_readable/descriptiles/STATE.a2ml` -* `www/.well-known/security.txt` -* `www/.well-known/ai.txt` -* `www/.well-known/humans.txt` -* `build/guix.scm` - -=== Prohibited - -* Python outside `salt/` directory -* /JavaScript (use ) -* CUE (use Guile/Nickel) -* `Dockerfile` (use `Containerfile`) -* npm, Bun, pnpm, yarn (use ) -* Go (use Rust) - -== STATE.a2ml - -The STATE.a2ml file tracks project state: - -[source] ----- -# STATE — Project State Checkpoint -# Format: a2ml (AI-readable markup) - -project: v-graphql -version: 0.1.0 -last-updated: 2026-02-14 -status: active - -phase: implementation -maturity: beta - -ecosystem: - part-of: RSR Framework - depends-on: [] - -milestones: - - name: Initial setup - completion: 100 - - name: Core implementation - completion: 0 ----- - -== Badge Schema - -Generate badges from STATE.a2ml: - -[source,bash] ----- -just badges standard ----- - -See `docs/BADGE_SCHEMA.adoc` for the full badge taxonomy. - -== Ecosystem Integration - -This template is part of: - -* **STATE.a2ml Ecosystem**: Conversation checkpoints -* **RSR Framework**: Repository standards -* **Consent-Aware-HTTP**: .well-known compliance -* **Hypatia**: Neurosymbolic security scanning -* **gitbot-fleet**: Bot orchestration - -== License - -SPDX-License-Identifier: CC-BY-SA-4.0 - -== Links - -* https://github.com/hyperpolymath/elegant-STATE[elegant-STATE] - STATE tooling -* https://github.com/hyperpolymath/conative-gating[conative-gating] - Policy enforcement -* https://rhodium.sh[Rhodium Standard] - RSR documentation diff --git a/docs/STATE-VISUALIZER.adoc b/docs/STATE-VISUALIZER.adoc index 2e23ca3..bac8666 100644 --- a/docs/STATE-VISUALIZER.adoc +++ b/docs/STATE-VISUALIZER.adoc @@ -1,131 +1,92 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -= Project State Visualizer += CoprocessorRuntime.jl - Project Topology +:toc: + +The module and file topology of the package, taken from the `include`, `import` +and `using` statements in `src/CoprocessorRuntime.jl`, `ext/AcceleratorGateExt.jl` +and `test/runtests.jl`. It describes structure only; it carries no completion +percentages, because none has been measured. For status see `status/ROADMAP.adoc` +and `status/READINESS.adoc`. + +== Module and include order + +`src/CoprocessorRuntime.jl` declares `module CoprocessorRuntime`, exports the +public names, and includes seven files in this order. There are no `using` or +`import` statements in `src/`: the package has no dependencies and the files +share one module namespace. + +[source] +---- +module CoprocessorRuntime src/CoprocessorRuntime.jl + include("Kinds.jl") Role, CoprocessorKind, kind_label, coprocessor_kind + include("Grades.jl") ResourceGrade, tropical_seq/alt, dominates + include("EchoLoss.jl") TransferMap, EchoResidue + include("Sessions.jl") Session, open_session, close_session! + include("Receipts.jl") WarrantKind, LaunchReceipt + include("Nullity.jl") CNOClaim, ONDClaim, InverseMeta + include("Choreography.jl") Endpoint, LaunchPlan, project, HubCeilingRefusal +end +---- + +== Which file uses which + +An arrow `A --> B` means the code of `A` refers to a type defined in `B`. +Include order respects every arrow. [source] ---- - - - - -# RSR Template Repo — Project Topology - -## System Architecture - -``` - ┌─────────────────────────────────────────┐ - │ NEW REPOSITORY │ - │ (Consumer of this Template) │ - └───────────────────┬─────────────────────┘ - │ Scaffolding - ▼ - ┌─────────────────────────────────────────┐ - │ RSR TEMPLATE HUB │ - │ │ - │ ┌───────────┐ ┌───────────────────┐ │ - │ │ AI Gate- │ │ ABI / FFI │ │ - │ │ keeper │ │ Standard │ │ - │ │ (0-AI-M) │ │ (Idris2/Zig) │ │ - │ └─────┬─────┘ └────────┬──────────┘ │ - │ │ │ │ - │ ┌─────▼─────┐ ┌────────▼──────────┐ │ - │ │ Topology │ │ SCM / 6SCM │ │ - │ │ Guide │ │ Metadata │ │ - │ │ (Visual) │ │ (machine_read) │ │ - │ └─────┬─────┘ └────────┬──────────┘ │ - │ │ │ │ - │ ┌─────▼─────────────────▼──────────┐ │ - │ │ CONTAINER ECOSYSTEM │ │ - │ │ ┌──────────┐ ┌───────────────┐ │ │ - │ │ │ Podman / │ │ selur-compose │ │ │ - │ │ │ OCI │ │ cerro-torre │ │ │ - │ │ │ Build │ │ svalinn/vordr │ │ │ - │ │ └──────────┘ └───────────────┘ │ │ - │ │ ct-build.sh deploy.k9.ncl │ │ - │ └──────────────────────────────────┘ │ - └────────│─────────────────│──────────────┘ - │ │ - ▼ ▼ - ┌─────────────────────────────────────────┐ - │ PLATFORM INTEGRATION │ - │ ┌───────────┐ ┌───────────┐ ┌───────┐│ - │ │ GitHub │ │ GitLab │ │ Nix / ││ - │ │ Workflows │ │ CI/CD │ │ Guix ││ - │ └───────────┘ └───────────┘ └───────┘│ - └─────────────────────────────────────────┘ - - ┌─────────────────────────────────────────┐ - │ REPO INFRASTRUCTURE │ - │ Justfile / Mustfile .machine_readable/ │ - │ Codeowners / Reuse *_chora.deed (root) │ - └─────────────────────────────────────────┘ -``` - -## Completion Dashboard - -``` -COMPONENT STATUS NOTES -───────────────────────────────── ────────────────── ───────────────────────────────── -CORE STANDARDS - ABI/FFI Standard (Idris2/Zig) ██████████ 100% Universal interface stable - AI Gatekeeper (repo deed) ██████████ 100% Universal entry point active - TOPOLOGY.md Standard ██████████ 100% Visual summary guide active - 6SCM Metadata Structure ██████████ 100% Machine-readable state stable - -INFRASTRUCTURE - Justfile Automation ██████████ 100% Standard build/verify tasks - CI/CD Workflow Templates ██████████ 100% GH/GL scaffolding verified - Multi-Forge Sync ██████████ 100% Hub-and-spoke mirroring stable - -CONTAINER ECOSYSTEM (Phase 2) - Containerfile (OCI build) ██████████ 100% Multi-stage Chainguard base - selur-compose orchestration ██████████ 100% Template + concrete example - cerro-torre manifest ██████████ 100% Bundle metadata & signing - svalinn gateway policy ██████████ 100% .gatekeeper.yaml active - vordr runtime monitoring ██████████ 100% Runtime config template - k9-svc deployment (Nickel) ██████████ 100% Hunt-level deploy descriptor - ct-build.sh pipeline ██████████ 100% Build/sign/verify script - Justfile container-* recipes ██████████ 100% 8 recipes integrated - Trustfile CONTAINER_SUPPLY_CHAIN ██████████ 100% Supply chain section added - -REPO INFRASTRUCTURE - .machine_readable/ ██████████ 100% STATE/META/ECOSYSTEM active - Governance & License ██████████ 100% MPL-2.0 & Ethical use verified - Development Shells (Guix) ██████████ 100% Reproducible env stable - -───────────────────────────────────────────────────────────────────────────── -OVERALL: ██████████ 100% RSR Template Stable & Certified -``` - -## Key Dependencies - -``` -Philosophy ──────► RSR Standard ──────► Template Scaffolding ──► New Repo - │ │ │ │ - ▼ ▼ ▼ ▼ -CCCP Policy ─────► repo deed ────────────► Justfile ──────────► Compliance - │ - ▼ - Container Ecosystem - ┌──────────┼──────────┐ - ▼ ▼ ▼ - selur-compose cerro- svalinn/ - (orchestrate) torre vordr - (sign) (monitor) - │ - ▼ - k9-svc deploy -``` - -## Update Protocol - -This file is maintained by both humans and AI agents. When updating: - -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file - -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). + Receipts.jl Nullity.jl Choreography.jl + \ / / | \ + v v / | \ + Sessions.jl / | \ + | / | \ + v v v v + Kinds.jl <-------+ Grades.jl EchoLoss.jl + + Kinds.jl, Grades.jl and EchoLoss.jl refer to no other file. + Receipts.jl and Nullity.jl use Session; Choreography.jl uses + Role, CoprocessorKind, ResourceGrade and EchoResidue. ---- + +[cols="1,2",options="header"] +|=== +| File | Refers to + +| `Kinds.jl` | nothing +| `Grades.jl` | nothing +| `EchoLoss.jl` | nothing +| `Sessions.jl` | `Kinds.jl` (`CoprocessorKind`, `Role`, `HostRole`) +| `Receipts.jl` | `Sessions.jl` (`Session`, `isopen`) +| `Nullity.jl` | `Sessions.jl` (`Session`, in `reset_session!`); `EchoResidue` is named only in a docstring +| `Choreography.jl` | `Kinds.jl` (`Role`, `CoprocessorKind`), `Grades.jl` (`ResourceGrade`), `EchoLoss.jl` (`EchoResidue`) +|=== + +== The optional extension + +[source] +---- + AcceleratorGate.jl (weak dependency, [weakdeps] in Project.toml) + | + | both loaded + v + ext/AcceleratorGateExt.jl ----> CoprocessorRuntime (coprocessor_kind and the *Kind types) +---- + +`AcceleratorGateExt` imports `coprocessor_kind` and the eight kind types from +`CoprocessorRuntime`, and sixteen names from `AcceleratorGate` (`AbstractBackend` +and fifteen backend types). Julia loads it only when both packages are loaded. +Nothing in `src/` refers to it, so the core stays free of the dependency. + +== Tests + +[source] +---- +test/runtests.jl + Aqua.test_all(CoprocessorRuntime) + include test/cases/{smoke,grades,sessions,receipts,choreography}.jl + subprocess: julia --project=test/ext test/ext/runtests.jl (Julia 1.11 or later) + test/ext/Project.toml: AcceleratorGate (pinned git rev), CoprocessorRuntime (path ../..) +---- + +See `status/TEST-NEEDS.adoc` for what these run and what is missing. diff --git a/docs/status/TEST-NEEDS.adoc b/docs/status/TEST-NEEDS.adoc index c6d2e51..e648674 100644 --- a/docs/status/TEST-NEEDS.adoc +++ b/docs/status/TEST-NEEDS.adoc @@ -1,126 +1,94 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -= TEST-NEEDS: rsr-template-repo += TEST-NEEDS: CoprocessorRuntime.jl -== CRG Grade: C — ACHIEVED 2026-04-04 +What tests exist for the Julia package, what CI runs, and what is missing. +Every count below comes from a run of `julia --project=. -e 'using Pkg; Pkg.test()'` +with the test sets set to verbose, on Julia 1.11.7 and 1.10.10, at commit +`6ccf6c9`. Counts are of assertions that ran, not of lines or functions. -== Current State (Updated 2026-04-04) +== Grade -[cols="2,1,4", options="header"] +No CRG or TRG grade is established by this document. `status/READINESS.adoc` +carries `Current Grade: X` (not graded) and its per-component table is +unfilled. The test census below is evidence a grade assessment could use; it is +not an assessment, and it does not show coverage of the source. + +== Package tests (`test/`) + +`test/runtests.jl` runs seven test sets under one top-level `CoprocessorRuntime` +set. + +[cols="3,1,3",options="header"] |=== -| Category | Count | Details - -| *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 +| Test set | Assertions | Source + +| Aqua (`Aqua.test_all`) | 11 | `test/runtests.jl` +| smoke | 4 | `test/cases/smoke.jl` +| tropical grades | 10 | `test/cases/grades.jl` +| sessions and nullity | 10 | `test/cases/sessions.jl` +| epistemic receipts | 4 | `test/cases/receipts.jl` +| choreography and hub_ceiling | 7 | `test/cases/choreography.jl` +| AcceleratorGateExt (subprocess) | 1 | `test/runtests.jl` (runs `test/ext`) |=== -== Completed Work (CRG C - Testing & Benchmarking) - -=== Template Validation Script ✅ - -* [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) - -=== E2E Template Instantiation Test ✅ - -* [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 - -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) - -=== 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 `{{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) ✅ +Result on Julia 1.11.7: 47 passed of 47. Result on Julia 1.10.10: 46 passed, +1 broken, of 47; the broken one is the `AcceleratorGateExt` entry, recorded as +`@test_skip` because `test/ext` needs Julia 1.11 (`[sources]`). Setting +`COPROCESSORRUNTIME_SKIP_EXT_TESTS=1` on 1.11 gives the same 46 passed and +1 broken. + +=== Extension tests (`test/ext`) + +On Julia 1.11 the subprocess runs `test/ext/runtests.jl` in its own environment +(AcceleratorGate fetched by URL at a pinned commit). It has five test sets and +24 assertions, 24 passed of 24: the extension is loaded (2); the table covers +every AcceleratorGate backend subtype (1); each of the 15 backends maps to its +kind (15); the four backends with no kind here map to `:unknown` (4); a mapped +kind opens a session (2). + +== What CI runs + +`.github/workflows/julia-ci.yml` has three jobs, read from the file; this +document does not report their results: + +* Format: JuliaFormatter check over `src/` and `test/` including `test/cases` (not `ext/` or `test/ext`) (Julia `1`). +* Static analysis: `JET.test_package(CoprocessorRuntime)` (Julia `1`). +* Test: `Pkg.test()` (Test and Aqua) on Julia `1.10` and `1`, Ubuntu. + +Other workflows exist under `.github/workflows/` (for example `estate-rules.yml` +runs the repository-shape, AsciiDoc and session-contract checks). The shell +tests under `tests/` check repository structure and estate tooling. They do not +test the Julia sources in `src/` directly, and they were not run for this document. + +== What is not covered + +Stated from reading `src/` against `test/`; not measured. No coverage tool has +been run, and the census above has no denominator of source lines or branches. + +* No test of `EchoResidue` or `TransferMap` equality, nor of + `injective_transfer` on its own (they appear only as inputs to other tests). +* No test of `kind_label` for each of the eight kinds in `test/cases` (only + `GPUKind` is checked there). The `UnknownKind` method is exercised, by + `test/ext/runtests.jl` (Julia 1.11 or later, in the extension subprocess); the + generic `kind_label(::CoprocessorKind)` fallback (`src/Kinds.jl`) is not + tested. +* No test of `observe_null` rejecting an invalid status, as far as the case + files show. +* No property-based or fuzz tests. `tests/fuzz/README.adoc` says no harness is + configured. +* No benchmark of the package. `benches/template_bench.sh` is inherited from + the template and does not time Julia code. +* No formal proof. `verification/proofs/` holds inherited scaffolding; nothing + there is a proof about this package, and CNO/OND remain claims + (`:unproved` or `:model_checked`). +* No run on Julia 1.10 of the extension tests, by design of the `[sources]` + requirement. +* The Format and JET jobs were not run for this document, so their current + result is unknown here. + +== Next steps + +* [ ] Add tests for the gaps listed above, then record the new counts here. +* [ ] Decide whether to measure coverage and, if so, state it with its denominator. +* [ ] Fill `status/READINESS.adoc` from evidence, then link a grade here.