diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index d7ff294..efc19ec 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -9,9 +9,9 @@ Copyright (c) Jonathan D.A. Jewell TEMPLATE INSTRUCTIONS (delete this block before publishing) ============================================================================ Replace all {{PLACEHOLDER}} values: - rsr-template-repo - Your project name + CoprocessorRuntime.jl - Your project name hyperpolymath - GitHub/GitLab username or org - rsr-template-repo - Repository name + CoprocessorRuntime.jl - Repository name j.d.a.jewell@open.ac.uk - Email for conduct reports Jonathan D.A. Jewell - Name of conduct team/committee 7 days - Initial response SLA (e.g., 48 hours) @@ -26,7 +26,7 @@ Review and customise: ## Our Pledge -We as members, contributors, and leaders pledge to make participation in rsr-template-repo 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 as members, contributors, and leaders pledge to make participation in CoprocessorRuntime.jl 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. @@ -321,7 +321,7 @@ We thank these communities for their leadership in creating welcoming spaces. If you have questions about this Code of Conduct: -- Open a [Discussion](https://github.com/hyperpolymath/rsr-template-repo/discussions) (for general questions) +- Open a [Discussion](https://github.com/hyperpolymath/CoprocessorRuntime.jl/discussions) (for general questions) - Email j.d.a.jewell@open.ac.uk (for private questions) - Contact any maintainer directly diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 11cb1a4..87f9e20 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -4,15 +4,15 @@ Copyright (c) Jonathan D.A. Jewell --> ``` # Clone the repository -git clone https://github.com/hyperpolymath/rsr-template-repo.git -cd rsr-template-repo +git clone https://github.com/hyperpolymath/CoprocessorRuntime.jl.git +cd CoprocessorRuntime.jl # Using Guix (recommended for reproducibility) guix shell -D -f build/guix.scm # Or using toolbox/distrobox -toolbox create rsr-template-repo-dev -toolbox enter rsr-template-repo-dev +toolbox create CoprocessorRuntime.jl-dev +toolbox enter CoprocessorRuntime.jl-dev # Install dependencies manually # Verify setup @@ -72,10 +72,10 @@ Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) an Look for issues labelled: -- [`good first issue`](https://github.com/hyperpolymath/rsr-template-repo/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/rsr-template-repo/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/rsr-template-repo/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/rsr-template-repo/labels/perimeter-3) — Community sandbox scope +- [`good first issue`](https://github.com/hyperpolymath/CoprocessorRuntime.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/CoprocessorRuntime.jl/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/CoprocessorRuntime.jl/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/CoprocessorRuntime.jl/labels/perimeter-3) — Community sandbox scope --- diff --git a/.github/SECURITY.md b/.github/SECURITY.md index c9044dd..3ea7448 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -33,7 +33,7 @@ We take security seriously. We appreciate your efforts to responsibly disclose v The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/rsr-template-repo/security/advisories/new) +1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/CoprocessorRuntime.jl/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 @@ -187,7 +187,7 @@ If we cannot reach agreement on disclosure timing, we default to 90 days from yo The following are within scope for security research: -- This repository (`hyperpolymath/rsr-template-repo`) and all its code +- This repository (`hyperpolymath/CoprocessorRuntime.jl`) 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 @@ -306,7 +306,7 @@ Recognition includes: 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/rsr-template-repo/security/advisories) +- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/CoprocessorRuntime.jl/security/advisories) - **Release notes**: Security fixes noted in [CHANGELOG](../CHANGELOG.md) ### Update Policy @@ -332,7 +332,7 @@ To stay informed about security updates: ## Security Best Practices -When using rsr-template-repo, we recommend: +When using CoprocessorRuntime.jl, we recommend: ### General @@ -354,7 +354,7 @@ When using rsr-template-repo, we recommend: ## Additional Resources -- [Security Advisories](https://github.com/hyperpolymath/rsr-template-repo/security/advisories) +- [Security Advisories](https://github.com/hyperpolymath/CoprocessorRuntime.jl/security/advisories) - [Changelog](../CHANGELOG.md) - [Contributing Guidelines](CONTRIBUTING.md) - [CVE Database](https://cve.mitre.org/) @@ -366,8 +366,8 @@ When using rsr-template-repo, we recommend: | Purpose | Contact | |---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/rsr-template-repo/security/advisories/new) or j.d.a.jewell@open.ac.uk | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/rsr-template-repo/discussions) | +| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/CoprocessorRuntime.jl/security/advisories/new) or j.d.a.jewell@open.ac.uk | +| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/CoprocessorRuntime.jl/discussions) | | **Other enquiries** | See [README](../README.adoc) for contact information | --- @@ -382,7 +382,7 @@ This security policy may be updated from time to time. Significant changes will --- -*Thank you for helping keep rsr-template-repo and its users safe.* 🛡️ +*Thank you for helping keep CoprocessorRuntime.jl and its users safe.* 🛡️ --- diff --git a/.github/workflows/sonarqube.yml b/.github/workflows/sonarqube.yml index 40b5318..834c860 100644 --- a/.github/workflows/sonarqube.yml +++ b/.github/workflows/sonarqube.yml @@ -3,7 +3,7 @@ # SonarQube Cloud (SonarCloud) static analysis. Analysis scope + exclusions live # in sonar-project.properties. Requires the SONAR_TOKEN repository secret # (Settings -> Secrets and variables -> Actions) and a SonarCloud project: -# https://sonarcloud.io/project/overview?id=hyperpolymath_rsr-template-repo +# https://sonarcloud.io/project/overview?id=hyperpolymath_CoprocessorRuntime.jl # Mirrors the boj-server arrangement. # # WHY THE TOKEN GUARD (added 2026-07-28) diff --git a/.machine_readable/ai/AI.a2ml b/.machine_readable/ai/AI.a2ml index d25039f..416eaf2 100644 --- a/.machine_readable/ai/AI.a2ml +++ b/.machine_readable/ai/AI.a2ml @@ -3,7 +3,6 @@ # AI Assistant Instructions ## Repository Focus -- `rsr-template-repo` 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/arrival-pack/README.adoc b/.machine_readable/arrival-pack/README.adoc index a48f9fd..2729dac 100644 --- a/.machine_readable/arrival-pack/README.adoc +++ b/.machine_readable/arrival-pack/README.adoc @@ -10,27 +10,32 @@ the repo's own machine-readable truth. [source] ---- -a2ml (descriptiles) extract.sh arrival-pack.ncl CLAUDE.md -CLADE/ECOSYSTEM/ ──▶ (a2ml → JSON, ──▶ (Nickel projection ──▶ region between -AGENTIC/STATE/ANCHOR the thin reader) = the engine) BEGIN/END markers +_chora.deed extract.sh arrival-pack.ncl CLAUDE.md +(incl. its (anchor (deed → JSON, (Nickel projection region between + (golden-path))) ──▶ the thin reader) ──▶ = the engine) ──▶ BEGIN/END markers ---- Two halves of the generated region: * *Estate-common* — identical in every repo; the Manifesto doctrine + format-family - orientation + canon pointers + language policy. Pinned to a Manifesto SHA once + orientation + canon pointers + language policy + the proof guidance (which + prover for which obligation; moved in from hand-authored text on 2026-11-15 + so a wording fix reaches every repo by regenerating). Pinned to a Manifesto SHA once the wording is ratified (today: `DRAFT-unratified`). -* *Repo-specific* — projected from this repo's a2ml: identity, IS / IS-NOT, +* *Repo-specific* — projected from this repo's deed: identity, IS / IS-NOT, position, constraints, golden path, state. -The a2ml files remain the single source of truth. CLAUDE.md is a *view*. Content +The repo deed (`_chora.deed`) is the single source of truth; it took +over the former CLADE / ECOSYSTEM / AGENTIC / STATE records (rsr-template-repo#209), and +`extract.sh` reads it through `scripts/deed-field.sh`. The golden path +comes from its `(anchor (golden-path))` clause. CLAUDE.md is a *view*. Content outside the `ARRIVAL-PACK:BEGIN/END` markers is hand-authorable and preserved. == Files [cols="1,3"] |=== -| `extract.sh` | a2ml reader → deterministic `claude-md-data.json` (build artifact, git-ignored) +| `extract.sh` | deed reader → deterministic `claude-md-data.json` (build artifact, git-ignored) | `arrival-pack.ncl` | Nickel projection engine → the region string (`nickel export --format raw`) | `generate.sh` | orchestrator: extract → render → splice (Hunt-tier, writes CLAUDE.md) | `verify.sh` | drift check: regenerate + byte-compare committed region (Yard-tier) @@ -41,7 +46,7 @@ outside the `ARRIVAL-PACK:BEGIN/END` markers is hand-authorable and preserved. [source,console] ---- -just claude-md # (re)generate CLAUDE.md from a2ml +just claude-md # (re)generate CLAUDE.md from the repo deed just validate-claude-md # fail if the committed region drifted / was hand-edited ---- @@ -49,7 +54,14 @@ just validate-claude-md # fail if the committed region drifted / was hand-edit * Estate-common doctrine is a *DRAFT* in the agent's words — owner to ratify into his voice, then pin to a `hyperpolymath/manifesto` commit SHA. -* `ECOSYSTEM.what-this-is-not` is empty here, so IS-NOT renders as "not yet - declared". Populating it is the boundary-erosion fix (the `lith` lesson). -* `ANCHOR.a2ml` currently encodes semantic-authority + golden-path; the +* IS-NOT comes from the deed's `(ecosystem :not (…))`. When that list is empty, + IS-NOT renders as "not yet declared" and the deed should gain the list (the + boundary-erosion fix, the `lith` lesson). +* A repo's `(anchor (implementation-policy …))` renders as one "Anchor + override" line in the repo-specific part: what `:forbidden` lists, and any + language `:allowed` lists that the estate policy denies. An allowed language + the estate does not deny is no override and is not listed. The line is + hidden when there is neither. Controls: + `tests/workflows/arrival_pack_anchor_override_test.sh`. +* The `(anchor)` clause currently encodes semantic-authority + golden-path; the recognised-drift / re-anchor-ledger aspect is a pending standards change. diff --git a/.machine_readable/arrival-pack/arrival-pack.ncl b/.machine_readable/arrival-pack/arrival-pack.ncl index 0324990..205e332 100644 --- a/.machine_readable/arrival-pack/arrival-pack.ncl +++ b/.machine_readable/arrival-pack/arrival-pack.ncl @@ -3,16 +3,16 @@ # # arrival-pack.ncl — the projection ENGINE for the CLAUDE.md arrival pack. # -# Pure Nickel. Imports the deterministic JSON produced by extract.sh (the a2ml +# Pure Nickel. Imports the deterministic JSON produced by extract.sh (the deed # reader) and renders the generated CLAUDE.md region as a single string. # Emit with: nickel export --format raw --file arrival-pack.ncl # # Two halves (see ARRIVAL-PACK-DESIGN): # A. estate-common — identical everywhere; DRAFT doctrine, pinned to a # Manifesto SHA once ratified (today: DRAFT-unratified). -# B. repo-specific — projected from this repo's a2ml (data.*). +# B. repo-specific — projected from this repo's deed (data.*). # -# The a2ml files remain the single source of truth; this is a VIEW. Hand-editing +# The deed remains the single source of truth; this is a VIEW. Hand-editing # the emitted region is a flagged error (see claude-md.k9.ncl drift check). let data = import "claude-md-data.json" in @@ -20,11 +20,40 @@ let data = import "claude-md-data.json" in # owner's voice. Until then the estate-common block is explicitly DRAFT. let manifesto_pin = "DRAFT-unratified" in -let provenance = "CLADE@%{data.h_clade} ECOSYSTEM@%{data.h_eco} AGENTIC@%{data.h_agentic} STATE@%{data.h_state} ANCHOR@%{data.h_anchor}" +# The estate deny list, stated once: the language-policy line below prints it, +# and the anchor override compares the anchor's allowed list against it. +let estate_denied = ["Nix", "Python", "Go", "TypeScript", "ReScript", "AGPL"] in + +# An anchor overrides the estate policy for its repo in two ways: it forbids +# what the estate permits, and it allows what the estate denies. Both are +# rendered, or the pack would tell an agent that an estate denial applies in a +# repo whose anchor allows the language (Codex review of sholes#13). A language +# the anchor allows and the estate does not deny is no override and is not +# listed. Names are compared as written. +let anchor_allows_denied = + std.array.filter (fun l => std.array.elem l estate_denied) data.anchor_allowed +in +let anchor_override = + let allows = std.string.join ", " anchor_allows_denied in + let forbids = std.string.join ", " data.anchor_forbidden in + let has_allows = std.array.length anchor_allows_denied > 0 in + let has_forbids = std.array.length data.anchor_forbidden > 0 in + let lead = "\n- **Anchor override** (ANCHOR) — This repo's anchor " in + let tail = ". The anchor overrides the estate policy above." in + if has_allows && has_forbids then + "%{lead}allows, where the estate policy above denies: %{allows}; it forbids: %{forbids}%{tail}" + else if has_allows then + "%{lead}allows, where the estate policy above denies: %{allows}%{tail}" + else if has_forbids then + "%{lead}forbids: %{forbids}%{tail}" + else "" +in + +let provenance = "DEED@%{data.h_deed} ANCHOR@%{data.h_anchor}" in m%" - + # You are in the hyperpolymath estate — orient before acting @@ -46,45 +75,101 @@ If you are unsure what something is, **read the canon; do not guess** (guessing 13. **Equivalence as identity** — the estate's intellectual through-line. 14. **Solutions at source** — fix the canonical/upstream origin, never patch the downstream symptom; trace and respect every up- and down-stream before you act. 15. **Elegance by default** — treat the most elegant and correct long-term option as the default arm; when you put a choice to the owner, LABEL which option that is, and if you recommend another, name both arms and say why you depart. Binds unasked design calls too: report the departure, never absorb it. +16. **Cheap models for upkeep**: CI/CD, workflow, template-drift and status-file work does not get a top-tier model. If it needs real effort, stop and say so, then open a thread on cheaper models (Sonnet and Haiku). Keep top-tier models for proof work and hard design. ## The machine-readable substrate (read in this order on arrival) -**CLADE** → **ANCHOR** → **AGENTIC** → **ECOSYSTEM** → **STATE** +**CHORA** → **ANCHOR** → **AGENTIC** → **ECOSYSTEM** → **STATE** -> **NEUROSYM** -> **PLAYBOOK** + +ANCHOR, AGENTIC, ECOSYSTEM, STATE, NEUROSYM and PLAYBOOK are clauses of the CHORA deed — `(anchor)`, `(agentic)`, `(ecosystem)`, `(status)` and `(maturity)`, `(neurosym)`, `(playbook)` — not files; STATE's journal is `docs/status/ROADMAP.adoc`. There are no `.a2ml` files in this estate. The descriptive family (working name *descriptiles*) describes what-is; the **contractiles** are the normative set-point. | File | Answers | |---|---| -| `CLADE.a2ml` | *Identity / lineage* — what this repo IS (registers into `gv-clade-index`). | -| `ANCHOR.a2ml` | *Semantic authority + golden path* — what downstream may extend-not-redefine; if a recognised-drift / re-anchor marker is present, it **supersedes** accumulated context — read it first. | -| `META.a2ml` | *Concept / constitutional authority* — ADRs, what's permitted. | -| `AGENTIC.a2ml` | *May I act now?* — permissions, risk gating, fail-safe-deny. | -| `ECOSYSTEM.a2ml` | *Where it sits* — estate + external relations, and `what-this-is-not`. | -| `NEUROSYM.a2ml` | *Meaning* of operations — proof obligations. | -| `PLAYBOOK.a2ml` | *How* permitted actions run. | -| `STATE.a2ml` | *Where things are now* — progress, blockers, next-actions. | +| `%{data.deed}` | **CHORA**, the repo deed. Its header `:repo-uuid` is the repo's one id, and `(identity)` and `(lineage)` say what this repo IS; a `(clade)` clause, when present, records the repo's clade placements: identity facts about where it sits, never its id and never an edict. chora-registry (formerly `gv-clade-index`) is authoritative for them; this repo's validation checks only that a declared clade is one of the 12 shelves; `(meta)` the architecture axes; `(agentic)` *may I act now?*; `(ecosystem)` where it sits and what it is not; `(status)` and `(maturity)` where it is now. Read fields with `scripts/deed-field.sh`. | +| `(anchor)` | *Semantic authority + golden path* — what downstream may extend-not-redefine; if a recognised-drift / re-anchor marker is present, it **supersedes** accumulated context — read it first. | +| `(neurosym)` | *Meaning* of operations — proof obligations. | +| `(playbook)` | *How* permitted actions run. | +| `docs/status/ROADMAP.adoc` | *What is next* — milestones, blockers, next actions. | | contractiles | Normative doctrine: **Intend** (north-star) · **Must** (invariants) · **Trust** (security) · **Adjust** (accessibility / inclusive design) — the integral core that holds strong; plus **Dust** (exnovation drift) · **Bust** (failure / breakage, not drift). | | k9 | *Validation*. Kennel (data) / Yard (pure eval) / Hunt (guarded exec). | +**The chora and CLADE are different things** (owner, 2026-11-15; standards A1 CHORA-SPEC §11.1): +- **The chora is ontological/metaphysical**: what this repo *is* and is meant to be in its context, code as identity: its intension (what defines it) and its extension (what it is an instance of). A `(clade …)` placement in it is an identity fact, copied from chora-registry, and the registry wins; never take one from a legacy file. +- **`CLADE.deed` is logical/epistemological**: how this repo's own content is ordered. Its scheme may be strict (Linnaean), judgement or none; membership may be single or multiple; a category is decided by its criterion. It is a descriptile and never identity; none is created until A7 M3 `clade` lands. +- **The aesthetic spans both**: what one experiences of the repo from outside, and in its ordering within. +- A legacy `CLADE.a2ml`, or A2ML named `CLADE.deed`, feeds the chora and `STATE.deed` (standards `clade-to-repo-deed.adoc`), never a `CLADE.deed`. + ## Canon pointers -- `hyperpolymath/standards` — the canon source. · `hyperpolymath/gv-clade-index` — the estate map (identity registry). · `hyperpolymath/manifesto` — this doctrine. +Estate data-format route: **kyq** handles exactly **TOML, Dhall, KYAML, +I-JSON/JCS**. Preserve TOML/Dhall; migrate YAML/YML to KYAML and JSON variants +through kyq using **hyperpolymath/ijson-jcs**, the actual estate implementation +repository. **kyX** owns wider projection. DEED/K9/coordination keep their own +grammars. Canon: `metadatastician/standards/3-practice/DATA-FORMAT-ROUTING.adoc`. +Planned support is not operational evidence: retain explicit transitional +checks until a pinned kyq executable passes positive and negative tests. + +- `hyperpolymath/standards` — the canon source. · `hyperpolymath/gv-clade-index` (being renamed chora-registry) — the estate registry of repo identities and classification schemes. · `hyperpolymath/manifesto` — this doctrine. - **Before you invent, rename, or consolidate anything: STOP and check the map + IS-NOT.** ## Estate language policy (overridable per-repo via AGENTIC) -Deny: **Nix, Python, Go, TypeScript, AGPL**. (Guix, not Nix.) -JavaScript tooling order: **Bun** (default) > Deno (grandfathered) > pnpm > npm (last resort, permitted). -Use plain JavaScript when this tooling is needed. The "use ReScript" rule is retired — ReScript is no longer used in this estate. Do not migrate Bun to Deno. +Deny: **%{std.string.join ", " estate_denied}**. (Guix, not Nix.) +JavaScript runtime: **Bun** > Deno > pnpm > npm (last resort, permitted), from one `package.json` that carries every runtime's lock (`bun.lock`, `deno.lock`, `pnpm-lock.yaml`), all written by `js-runtimes regen` (owner ruling 2026-10-14, standards LANGUAGE-POLICY §1.3–§1.4). Deno is permitted again; `package-lock.json` stays refused. +Use plain JavaScript when this tooling is needed. TypeScript and ReScript migrate to AffineScript. + +## Asking the owner +Put every question that needs the owner's decision through the selector (the AskUserQuestion tool), not as prose at the end of a report. Batch up to four per call, offer concrete options with the recommended one first, and say what each option would cause. + +## Proofs — which prover for which obligation + +Normative source: `3-practice/PROOF-POLICY.adoc` in `hyperpolymath/standards`. +Read it there; `verification/proofs/README.adoc` maps it onto this repo. + +| Code or obligation | Verifier | +|---|---| +| Rust code | **Creusot** with **Pearlite** contracts, and **Verus**, by default and on the code (§1.2). Kani for `unsafe`/FFI seams and Aeneas for Rust that implements an Agda theorem run alongside, never instead | +| Ada code | **SPARK** | +| APIs, ABIs, engineering properties | **Idris2** | +| Theory | **Agda**, rechecked in **Rocq** and **Lean** (no Mathlib) | + +Always name Creusot, Pearlite and Verus in Rust verification plans and in +`docs/status/PROOF-STATUS.adoc`. Pearlite is Creusot's specification +language, not a third verifier. Plan scopes for both verifiers, and record +any that is unsupported, inapplicable or not yet run, with its reason; never +present an unexecuted check as a pass. Using both does not make two +independent witnesses (policy §1.2). + +Third-party code (crates such as Bevy, libraries, forks) is **not** converted +or re-proved. Where a proof relies on a dependency the prover does not check, +state the reliance as an `ASSUMED` boundary specification. Where the +dependency's whole import cone compiles under the prover's safe mode with zero +postulates, it is *checked, not assumed*: record the cone (root module, flags, +postulate count of zero, library name, version and pin) instead of an +`ASSUMED` row (policy §1.1). A cone with a postulate, or compiled outside safe +mode, is not checked. When choosing between dependencies that fit equally +well, prefer one that carries its own verification. A preference, not a gate. + +Proof Witness Grades are policy §8. They apply to *theory* theorems only: Agda +source, rechecked in Rocq and Lean (§8.1). Engineering proofs (Creusot, Verus, +SPARK, Idris2) are not graded on this ladder; they use the §5 tokens only. For +a theory theorem, `PWG-3` < `PWG-2i` < `PWG-2ii` < `PWG-1`, where `PWG-1` is +strongest. A theorem that does not reach `PWG-3` is `ungraded`, with no +qualifier. A grade is derived from receipts, never asserted. A "verified" or +"machine-checked" claim needs current receipts. Report a census with its +denominator, never a percentage. Always write the `PWG-` prefix: CRG, TRG, ARG +and FRG letters, and ECHIDNA's `TrustLevel`, are different schemes. --- -# This repo: `%{data.canonical_name}` · clade `%{data.prefixed_name}` +# This repo: `%{data.canonical_name}` -- **Identity** — uuid `%{data.uuid}`; clade `%{data.clade_primary}` (secondary `%{data.clade_secondary}`); born %{data.born}; forge `%{data.forge_gh}`. +- **Identity** — chora id `%{data.uuid}`; clade: %{data.clade_aid}; born %{data.born}; forge `%{data.forge_gh}`. - **IS** — %{data.purpose} - **IS-NOT** — %{data.isnot} - **Where it sits** — pipeline position **%{data.pipeline_pos}**; chain `%{data.chain}`; coordination = `%{data.coordination}`. -- **Constraints here** (AGENTIC) — fail-closed; evidence-per-step; no-silent-skip; rerun-after-fix; release-claim-requires-hard-pass. Never: banned langs (above), secrets, state files in repo root, AGPL. Details: `.machine_readable/bot_directives/{methodology,coverage,debt}.a2ml`. -- **Golden path** (ANCHOR) — `%{data.golden_smoke}` → %{data.golden_crit}. -- **State** — phase %{data.phase}; maturity %{data.maturity}; %{data.completion}% complete; status %{data.status}. +- **Constraints here** (AGENTIC) — fail-closed; evidence-per-step; no-silent-skip; rerun-after-fix; release-claim-requires-hard-pass. Never: banned langs (above), secrets, state files in repo root, AGPL. Details: the deed's `(bot-directives (methodology) (coverage) (debt))` clauses. +- **Golden path** (ANCHOR) — `%{data.golden_smoke}` → %{data.golden_crit}.%{anchor_override} +- **State** — phase %{data.phase}; maturity %{data.maturity}. Milestones and next actions: `docs/status/ROADMAP.adoc`. "% diff --git a/.machine_readable/arrival-pack/claude-md.k9.ncl b/.machine_readable/arrival-pack/claude-md.k9.ncl index d3fbb1c..6685d81 100644 --- a/.machine_readable/arrival-pack/claude-md.k9.ncl +++ b/.machine_readable/arrival-pack/claude-md.k9.ncl @@ -5,13 +5,14 @@ K9! # claude-md.k9.ncl — k9 contract for the CLAUDE.md arrival-pack drift check. # # Yard-tier (pure evaluation / comparison; no exec, no network, no FS write): -# the check regenerates the arrival-pack region from this repo's a2ml and asserts +# the check regenerates the arrival-pack region from this repo's deed and asserts # the committed CLAUDE.md region byte-matches it. The runnable side is verify.sh; # writing (Hunt-tier) is generate.sh. This record documents and validates the # contract shape. { pedigree = { schema_version = "1.0.0", + component_type = "drift-check:claude-md-arrival-pack", contractile_verb = "trust", # provenance: the view must equal its source semantics = "projection-fidelity", security = { @@ -19,12 +20,12 @@ K9! trust_level = "read-only comparison", allow_network = false, allow_filesystem_write = false, - allow_subprocess = true, # runs extract.sh + nickel to reproduce the view + allow_subprocess = false, # verify.sh runs extract.sh + nickel; this record does not }, metadata = { name = "claude-md-arrival-pack", version = "1.0.0", - description = "CLAUDE.md arrival pack is a faithful projection of this repo's a2ml.", + description = "CLAUDE.md arrival pack is a faithful projection of this repo's deed.", paired_runner = "verify.sh", writer = "generate.sh", author = "Jonathan D.A. Jewell ", @@ -33,12 +34,10 @@ K9! # Inputs the projection reads (single source of truth). inputs = { + # The repo deed (_chora.deed) is the only input; the golden path is + # its (anchor (golden-path)) clause (rsr-template-repo#209). descriptiles = [ - ".machine_readable/descriptiles/CLADE.a2ml", - ".machine_readable/descriptiles/ECOSYSTEM.a2ml", - ".machine_readable/descriptiles/AGENTIC.a2ml", - ".machine_readable/descriptiles/STATE.a2ml", - ".machine_readable/descriptiles/anchors/ANCHOR.a2ml", + "_chora.deed", ], estate_common = "hyperpolymath/manifesto@", # DRAFT-unratified today target = "CLAUDE.md", @@ -47,7 +46,7 @@ K9! # Checks (all must hold). checks = [ - { id = "inputs-exist", desc = "every descriptiles input file exists and parses" }, + { id = "inputs-exist", desc = "exactly one repo deed exists, parses and carries (anchor (golden-path))" }, { id = "region-present", desc = "CLAUDE.md contains exactly one BEGIN/END region" }, { id = "no-drift", desc = "committed region byte-equals freshly generated region" }, ], diff --git a/.machine_readable/arrival-pack/extract.sh b/.machine_readable/arrival-pack/extract.sh index c0adf70..3972306 100755 --- a/.machine_readable/arrival-pack/extract.sh +++ b/.machine_readable/arrival-pack/extract.sh @@ -2,88 +2,157 @@ # SPDX-License-Identifier: MPL-2.0 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # -# extract.sh — the thin a2ml *reader* for the arrival-pack compiler. +# extract.sh — the thin *reader* for the arrival-pack compiler. # -# Projects the scalar/array fields the CLAUDE.md arrival pack needs out of this -# repo's descriptive a2ml (the "descriptiles" family: CLADE/ECOSYSTEM/AGENTIC/STATE + -# anchors/ANCHOR) into a single deterministic JSON document on stdout. +# Projects the fields the CLAUDE.md arrival pack needs out of this repo's deed +# (_chora.deed: identity, clade, lineage, status, maturity, ecosystem, +# agentic, and the golden path in its (anchor) clause) into a single +# deterministic JSON document on stdout. Every deed read goes through +# scripts/deed-field.sh; there are no .a2ml inputs (rsr-template-repo#209). # -# This is a READER only — it authors nothing. The a2ml files remain the single +# This is a READER only — it authors nothing. The deed remains the single # source of truth; arrival-pack.ncl renders this JSON into the CLAUDE.md region. # Determinism (no timestamps) is required so the k9 drift check can byte-compare. set -euo pipefail +# A failed $(…) inside a function or assignment must stop the run, not read as "". +shopt -s inherit_errexit -DIR6A2="${1:-.machine_readable/descriptiles}" -CLADE="$DIR6A2/CLADE.a2ml" -ECO="$DIR6A2/ECOSYSTEM.a2ml" -AGENTIC="$DIR6A2/AGENTIC.a2ml" -STATE="$DIR6A2/STATE.a2ml" -ANCHOR="$DIR6A2/anchors/ANCHOR.a2ml" +ROOT="${1:-.}" +READ="$ROOT/scripts/deed-field.sh" -for f in "$CLADE" "$ECO" "$AGENTIC" "$STATE" "$ANCHOR"; do - [ -f "$f" ] || { echo "extract.sh: missing required a2ml: $f" >&2; exit 2; } -done +DEED="$(bash "$READ" --find "$ROOT")" \ + || { echo "extract.sh: need exactly one *_chora.deed in $ROOT" >&2; exit 2; } +bash "$READ" --has "$DEED" anchor/golden-path \ + || { echo "extract.sh: $(basename "$DEED") has no (anchor (golden-path)) clause" >&2; exit 2; } -# scalar KEY FILE -> first `KEY = "value"` or unquoted `KEY = value` (anchored) -scalar() { - local v - v="$(grep -oP "^$1 = \"\K[^\"]+" "$2" | head -1 || true)" - if [ -z "$v" ]; then - v="$(grep -oP "^$1 = \K[^\"#]+" "$2" | head -1 | sed 's/[[:space:]]*$//' || true)" - fi - printf '%s' "$v" +# field PATH KEY -> the deed value, or "" when the clause or key is absent +# (rc 1); an unreadable deed or a usage error (rc 2) fails the run instead +field() { + local rc=0 + bash "$READ" "$DEED" "$1" "$2" || rc=$? + [ "$rc" -le 1 ] || return "$rc" } -# arr KEY FILE SEP -> join all quoted strings in the `KEY = [ ... ]` block -# (inline `k = ["a","b"]` or multiline). SEP is a literal multi-char string. -arr() { - local key="$1" file="$2" sep="${3:-, }" out="" i - local -a items - mapfile -t items < <( - awk -v k="$key" ' - index($0, k" = [")==1 {grab=1} - grab {print} - grab && /\]/ {exit} - ' "$file" | grep -oP '"[^"]*"' | sed 's/^"//; s/"$//' || true - ) - for i in "${!items[@]}"; do - if [ "$i" -eq 0 ]; then out="${items[$i]}"; else out="$out$sep${items[$i]}"; fi - done +# items PATH KEY SEP -> the deed list :KEY ( … ) joined by the literal SEP, +# "" when absent; fails like field() when the deed cannot be read +items() { + local out="" item first=1 list rc=0 + list="$(bash "$READ" --list "$DEED" "$1" "$2")" || rc=$? + [ "$rc" -le 1 ] || return "$rc" + while IFS= read -r item; do + [ -n "$item" ] || continue + if [ "$first" -eq 1 ]; then out="$item"; first=0; else out="$out$3$item"; fi + done <<< "$list" + printf '%s' "$out" +} + +# lines PATH KEY -> the deed list :KEY ( … ), one item per line, "" when absent +lines() { + local out rc=0 + out="$(bash "$READ" --list "$DEED" "$1" "$2")" || rc=$? + [[ "$rc" -le 1 ]] || return "$rc" printf '%s' "$out" } -# short content hash (drift provenance) -sh() { sha256sum "$1" | cut -c1-12; } +# hash12 -> short content hash of stdin (drift provenance) +hash12() { sha256sum | cut -c1-12; } + +# The identity is the deed's own TYPED literal, printed as written: +# #uuid"" (minted once, A7 J11), or the computed #u8"". +# The pack never prints a derived hex form of a name literal: that once put a +# version 5 id in CLAUDE.md, which ADR-008's strict gate (owner ruling D320) +# rejects in every minted repo. The typed literal says what the identifier is, +# as ADR-008 asks. +uuid_name="$(field '' repo-uuid)" +uuid="" +if [[ -n "$uuid_name" ]]; then + # --typed keeps the tag and quotes, and reads the literal wherever the layout puts it + rc=0 + uuid="$(bash "$READ" --typed "$DEED" '' repo-uuid)" || rc=$? + [[ "$rc" -le 1 ]] || exit "$rc" + [[ "$uuid" =~ ^#u(uid|[0-9]+)\"[^\"]*\"$ ]] || uuid="" +fi +[ -z "$uuid_name" ] || [ -n "$uuid" ] \ + || { echo "extract.sh: $(basename "$DEED") :repo-uuid is not a typed #uuid\"...\" or #u\"...\" literal" >&2; exit 2; } +# A version 5 identity is reported, not refused, here: this is the arrival-pack +# reader, not the gate. Standards A1 v0.4.5 C10 and T30 (ruling Q2) make +# v5-identity and u5-identity errors in every mode, and `just validate-rsr` +# and estate-rules (scripts/check-identity.sh) refuse them. The chora id is the +# v8 id of the birth path. +case "$uuid" in + '#u5"'*|'#uuid"'????????-????-5*) + echo "extract.sh: v5-identity: $(basename "$DEED") :repo-uuid $uuid is a version 5 id; the chora id is #uuid\"\" (standards A1 V8)" >&2 ;; + *) ;; # any other identity is printed as written, with nothing to report +esac + +# read_clauses -> the clauses this pack reads, one token per line. Hashing only +# these keeps an unrelated deed edit (say a canon-pin bump) from reading as drift. +read_clauses() { + local c + bash "$READ" "$DEED" '' canonical-name + printf '%s\n' "$uuid_name" + for c in identity clade lineage forges status maturity ecosystem agentic; do + bash "$READ" --clause "$DEED" "$c" || [ "$?" -eq 1 ] || return 2 + done +} -# --- IS-NOT: present only if ECOSYSTEM declares `what-this-is-not` ------------ -isnot="$(arr 'what-this-is-not' "$ECO" ' · ')" -[ -n "$isnot" ] || isnot="(not yet declared — add ECOSYSTEM.what-this-is-not)" +isnot="$(items ecosystem not ' · ')" +[ -n "$isnot" ] || isnot="(not yet declared — add (ecosystem :not (…)) to the deed)" -golden_smoke="$(arr 'smoke-test-command' "$ANCHOR" ' && ')" -golden_crit="$(arr 'success-criteria' "$ANCHOR" '; ')" +# Each value is its own assignment so that a failed deed read stops the run; +# as a bare `--arg x "$(…)"` its exit status would be discarded. +canonical_name="$(field '' canonical-name)" +[ -n "$canonical_name" ] \ + || { echo "extract.sh: $(basename "$DEED") has no :canonical-name" >&2; exit 2; } +# Clade placements are identity facts about where the repo sits, never its id +# and never an edict; chora-registry is authoritative for them (standards A1 +# §11, ruling W10). The clause is optional. +clade_primary="$(field clade primary)" +clade_secondary="$(items clade secondary ', ')" +if [[ -z "$clade_primary" ]]; then + clade_aid="none declared (optional placement)" +elif [[ -n "$clade_secondary" ]]; then + clade_aid="$clade_primary (secondary $clade_secondary; placement)" +else + clade_aid="$clade_primary (placement)" +fi +born="$(field lineage born)" +forge_gh="$(field forges github)" +purpose="$(field ecosystem purpose)" +pipeline_pos="$(field ecosystem pipeline-position)" +chain="$(field ecosystem chain)" +coordination="$(field ecosystem coordination)" +phase="$(field status phase)" +maturity="$(field maturity level)" +golden_smoke="$(items anchor/golden-path smoke-test-command ' && ')" +golden_crit="$(items anchor/golden-path success-criteria '; ')" +# The anchor may override the estate language policy for this repo only. +anchor_forbidden="$(lines anchor/implementation-policy forbidden)" +anchor_allowed="$(lines anchor/implementation-policy allowed)" +anchor_clause="$(bash "$READ" --clause "$DEED" anchor)" +h_deed="$(read_clauses | hash12)" +h_anchor="$(printf '%s\n' "$anchor_clause" | hash12)" -jq -n \ - --arg canonical_name "$(scalar 'canonical-name' "$CLADE")" \ - --arg prefixed_name "$(scalar 'prefixed-name' "$CLADE")" \ - --arg uuid "$(scalar 'uuid' "$CLADE")" \ - --arg clade_primary "$(scalar 'primary' "$CLADE")" \ - --arg clade_secondary "$(arr 'secondary' "$CLADE" ', ')" \ - --arg born "$(scalar 'born' "$CLADE")" \ - --arg forge_gh "$(scalar 'github' "$CLADE")" \ - --arg purpose "$(scalar 'purpose' "$ECO")" \ +jq -cnS \ + --arg canonical_name "$canonical_name" \ + --arg clade_aid "$clade_aid" \ + --arg uuid "$uuid" \ + --arg born "$born" \ + --arg forge_gh "$forge_gh" \ + --arg purpose "$purpose" \ --arg isnot "$isnot" \ - --arg pipeline_pos "$(scalar 'position' "$ECO")" \ - --arg chain "$(scalar 'chain' "$ECO")" \ - --arg coordination "$(scalar 'coordination' "$ECO")" \ - --arg phase "$(scalar 'phase' "$STATE")" \ - --arg maturity "$(scalar 'maturity' "$STATE")" \ - --arg completion "$(scalar 'completion-percentage' "$STATE")" \ - --arg status "$(scalar 'status' "$STATE")" \ + --arg pipeline_pos "$pipeline_pos" \ + --arg chain "$chain" \ + --arg coordination "$coordination" \ + --arg phase "$phase" \ + --arg maturity "$maturity" \ + --arg deed "$(basename "$DEED")" \ --arg golden_smoke "$golden_smoke" \ --arg golden_crit "$golden_crit" \ - --arg h_clade "$(sh "$CLADE")" \ - --arg h_eco "$(sh "$ECO")" \ - --arg h_agentic "$(sh "$AGENTIC")" \ - --arg h_state "$(sh "$STATE")" \ - --arg h_anchor "$(sh "$ANCHOR")" \ - '$ARGS.named' + --arg h_deed "$h_deed" \ + --arg h_anchor "$h_anchor" \ + --arg anchor_forbidden "$anchor_forbidden" \ + --arg anchor_allowed "$anchor_allowed" \ + '$ARGS.named + | .anchor_forbidden |= (split("\n") | map(select(. != ""))) + | .anchor_allowed |= (split("\n") | map(select(. != "")))' diff --git a/.machine_readable/arrival-pack/generate.sh b/.machine_readable/arrival-pack/generate.sh index ac2a859..da27bed 100755 --- a/.machine_readable/arrival-pack/generate.sh +++ b/.machine_readable/arrival-pack/generate.sh @@ -3,7 +3,7 @@ # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # # generate.sh — compile the repo's CLAUDE.md arrival pack. -# extract.sh (a2ml -> JSON) -> arrival-pack.ncl (Nickel projection) -> splice. +# extract.sh (deed -> JSON) -> arrival-pack.ncl (Nickel projection) -> splice. # # The generated region lives between the ARRIVAL-PACK:BEGIN/END markers. Anything # OUTSIDE the markers in CLAUDE.md is hand-authorable and is preserved verbatim. @@ -13,7 +13,7 @@ ROOT="$(git rev-parse --show-toplevel)" AP="$ROOT/.machine_readable/arrival-pack" TARGET="$ROOT/CLAUDE.md" -bash "$AP/extract.sh" "$ROOT/.machine_readable/descriptiles" > "$AP/claude-md-data.json" +bash "$AP/extract.sh" "$ROOT" > "$AP/claude-md-data.json" nickel export --format raw "$AP/arrival-pack.ncl" > "$AP/.region.tmp" if [ -f "$TARGET" ] && grep -q 'ARRIVAL-PACK:BEGIN' "$TARGET"; then @@ -35,7 +35,7 @@ else echo "-->" echo "" echo "" + echo " repo's deed by \`just claude-md\` — do not hand-edit it. -->" echo cat "$AP/.region.tmp" } > "$TARGET" diff --git a/.machine_readable/arrival-pack/verify.sh b/.machine_readable/arrival-pack/verify.sh index 1d90acf..c26fb58 100755 --- a/.machine_readable/arrival-pack/verify.sh +++ b/.machine_readable/arrival-pack/verify.sh @@ -3,7 +3,7 @@ # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # # verify.sh — drift check for the CLAUDE.md arrival pack (the runnable side of -# claude-md.k9.ncl). Regenerates the region from a2ml and byte-compares it to the +# claude-md.k9.ncl). Regenerates the region from the deed and byte-compares it to the # committed region. Non-zero exit on drift or hand-edit. Wire into CI/pre-commit. set -euo pipefail @@ -13,12 +13,12 @@ TARGET="$ROOT/CLAUDE.md" [ -f "$TARGET" ] || { echo "DRIFT: CLAUDE.md missing — run \`just claude-md\`"; exit 1; } -bash "$AP/extract.sh" "$ROOT/.machine_readable/descriptiles" > "$AP/claude-md-data.json" +bash "$AP/extract.sh" "$ROOT" > "$AP/claude-md-data.json" fresh="$(nickel export --format raw "$AP/arrival-pack.ncl")" committed="$(awk '/ + repo's deed by `just claude-md` — do not hand-edit it. --> - + # You are in the hyperpolymath estate — orient before acting @@ -28,44 +28,100 @@ If you are unsure what something is, **read the canon; do not guess** (guessing 13. **Equivalence as identity** — the estate's intellectual through-line. 14. **Solutions at source** — fix the canonical/upstream origin, never patch the downstream symptom; trace and respect every up- and down-stream before you act. 15. **Elegance by default** — treat the most elegant and correct long-term option as the default arm; when you put a choice to the owner, LABEL which option that is, and if you recommend another, name both arms and say why you depart. Binds unasked design calls too: report the departure, never absorb it. +16. **Cheap models for upkeep**: CI/CD, workflow, template-drift and status-file work does not get a top-tier model. If it needs real effort, stop and say so, then open a thread on cheaper models (Sonnet and Haiku). Keep top-tier models for proof work and hard design. ## The machine-readable substrate (read in this order on arrival) **CHORA** → **ANCHOR** → **AGENTIC** → **ECOSYSTEM** → **STATE** -> **NEUROSYM** -> **PLAYBOOK** +ANCHOR, AGENTIC, ECOSYSTEM, STATE, NEUROSYM and PLAYBOOK are clauses of the CHORA deed — `(anchor)`, `(agentic)`, `(ecosystem)`, `(status)` and `(maturity)`, `(neurosym)`, `(playbook)` — not files; STATE's journal is `docs/status/ROADMAP.adoc`. There are no `.a2ml` files in this estate. + The descriptive family (working name *descriptiles*) describes what-is; the **contractiles** are the normative set-point. | File | Answers | |---|---| -| `CLADE.a2ml` | *Identity / lineage* — what this repo IS (registers into `gv-clade-index`). | -| `ANCHOR.a2ml` | *Semantic authority + golden path* — what downstream may extend-not-redefine; if a recognised-drift / re-anchor marker is present, it **supersedes** accumulated context — read it first. | -| `META.a2ml` | *Concept / constitutional authority* — ADRs, what's permitted. | -| `AGENTIC.a2ml` | *May I act now?* — permissions, risk gating, fail-safe-deny. | -| `ECOSYSTEM.a2ml` | *Where it sits* — estate + external relations, and `what-this-is-not`. | -| `NEUROSYM.a2ml` | *Meaning* of operations — proof obligations. | -| `PLAYBOOK.a2ml` | *How* permitted actions run. | -| `STATE.a2ml` | *Where things are now* — progress, blockers, next-actions. | +| `CoprocessorRuntime.jl_chora.deed` | **CHORA**, the repo deed. Its header `:repo-uuid` is the repo's one id, and `(identity)` and `(lineage)` say what this repo IS; a `(clade)` clause, when present, records the repo's clade placements: identity facts about where it sits, never its id and never an edict. chora-registry (formerly `gv-clade-index`) is authoritative for them; this repo's validation checks only that a declared clade is one of the 12 shelves; `(meta)` the architecture axes; `(agentic)` *may I act now?*; `(ecosystem)` where it sits and what it is not; `(status)` and `(maturity)` where it is now. Read fields with `scripts/deed-field.sh`. | +| `(anchor)` | *Semantic authority + golden path* — what downstream may extend-not-redefine; if a recognised-drift / re-anchor marker is present, it **supersedes** accumulated context — read it first. | +| `(neurosym)` | *Meaning* of operations — proof obligations. | +| `(playbook)` | *How* permitted actions run. | +| `docs/status/ROADMAP.adoc` | *What is next* — milestones, blockers, next actions. | | contractiles | Normative doctrine: **Intend** (north-star) · **Must** (invariants) · **Trust** (security) · **Adjust** (accessibility / inclusive design) — the integral core that holds strong; plus **Dust** (exnovation drift) · **Bust** (failure / breakage, not drift). | | k9 | *Validation*. Kennel (data) / Yard (pure eval) / Hunt (guarded exec). | +**The chora and CLADE are different things** (owner, 2026-11-15; standards A1 CHORA-SPEC §11.1): +- **The chora is ontological/metaphysical**: what this repo *is* and is meant to be in its context, code as identity: its intension (what defines it) and its extension (what it is an instance of). A `(clade …)` placement in it is an identity fact, copied from chora-registry, and the registry wins; never take one from a legacy file. +- **`CLADE.deed` is logical/epistemological**: how this repo's own content is ordered. Its scheme may be strict (Linnaean), judgement or none; membership may be single or multiple; a category is decided by its criterion. It is a descriptile and never identity; none is created until A7 M3 `clade` lands. +- **The aesthetic spans both**: what one experiences of the repo from outside, and in its ordering within. +- A legacy `CLADE.a2ml`, or A2ML named `CLADE.deed`, feeds the chora and `STATE.deed` (standards `clade-to-repo-deed.adoc`), never a `CLADE.deed`. + ## Canon pointers -- `hyperpolymath/standards` — the canon source. · `hyperpolymath/gv-clade-index` — the estate map (identity registry). · `hyperpolymath/manifesto` — this doctrine. +Estate data-format route: **kyq** handles exactly **TOML, Dhall, KYAML, +I-JSON/JCS**. Preserve TOML/Dhall; migrate YAML/YML to KYAML and JSON variants +through kyq using **hyperpolymath/ijson-jcs**, the actual estate implementation +repository. **kyX** owns wider projection. DEED/K9/coordination keep their own +grammars. Canon: `metadatastician/standards/3-practice/DATA-FORMAT-ROUTING.adoc`. +Planned support is not operational evidence: retain explicit transitional +checks until a pinned kyq executable passes positive and negative tests. + +- `hyperpolymath/standards` — the canon source. · `hyperpolymath/gv-clade-index` (being renamed chora-registry) — the estate registry of repo identities and classification schemes. · `hyperpolymath/manifesto` — this doctrine. - **Before you invent, rename, or consolidate anything: STOP and check the map + IS-NOT.** ## Estate language policy (overridable per-repo via AGENTIC) -Deny: **Nix, Python, Go, TypeScript, AGPL**. (Guix, not Nix.) -JavaScript tooling order: **Bun** (default) > Deno (being removed — owner ruling 2026-08-26, standards#655) > pnpm > npm (last resort, permitted). -Use plain JavaScript when this tooling is needed. The "use ReScript" rule is retired — ReScript is no longer used in this estate. Do not migrate Bun to Deno. +Deny: **Nix, Python, Go, TypeScript, ReScript, AGPL**. (Guix, not Nix.) +JavaScript runtime: **Bun** > Deno > pnpm > npm (last resort, permitted), from one `package.json` that carries every runtime's lock (`bun.lock`, `deno.lock`, `pnpm-lock.yaml`), all written by `js-runtimes regen` (owner ruling 2026-10-14, standards LANGUAGE-POLICY §1.3–§1.4). Deno is permitted again; `package-lock.json` stays refused. +Use plain JavaScript when this tooling is needed. TypeScript and ReScript migrate to AffineScript. + +## Asking the owner +Put every question that needs the owner's decision through the selector (the AskUserQuestion tool), not as prose at the end of a report. Batch up to four per call, offer concrete options with the recommended one first, and say what each option would cause. + +## Proofs — which prover for which obligation + +Normative source: `3-practice/PROOF-POLICY.adoc` in `hyperpolymath/standards`. +Read it there; `verification/proofs/README.adoc` maps it onto this repo. + +| Code or obligation | Verifier | +|---|---| +| Rust code | **Creusot** with **Pearlite** contracts, and **Verus**, by default and on the code (§1.2). Kani for `unsafe`/FFI seams and Aeneas for Rust that implements an Agda theorem run alongside, never instead | +| Ada code | **SPARK** | +| APIs, ABIs, engineering properties | **Idris2** | +| Theory | **Agda**, rechecked in **Rocq** and **Lean** (no Mathlib) | + +Always name Creusot, Pearlite and Verus in Rust verification plans and in +`docs/status/PROOF-STATUS.adoc`. Pearlite is Creusot's specification +language, not a third verifier. Plan scopes for both verifiers, and record +any that is unsupported, inapplicable or not yet run, with its reason; never +present an unexecuted check as a pass. Using both does not make two +independent witnesses (policy §1.2). + +Third-party code (crates such as Bevy, libraries, forks) is **not** converted +or re-proved. Where a proof relies on a dependency the prover does not check, +state the reliance as an `ASSUMED` boundary specification. Where the +dependency's whole import cone compiles under the prover's safe mode with zero +postulates, it is *checked, not assumed*: record the cone (root module, flags, +postulate count of zero, library name, version and pin) instead of an +`ASSUMED` row (policy §1.1). A cone with a postulate, or compiled outside safe +mode, is not checked. When choosing between dependencies that fit equally +well, prefer one that carries its own verification. A preference, not a gate. + +Proof Witness Grades are policy §8. They apply to *theory* theorems only: Agda +source, rechecked in Rocq and Lean (§8.1). Engineering proofs (Creusot, Verus, +SPARK, Idris2) are not graded on this ladder; they use the §5 tokens only. For +a theory theorem, `PWG-3` < `PWG-2i` < `PWG-2ii` < `PWG-1`, where `PWG-1` is +strongest. A theorem that does not reach `PWG-3` is `ungraded`, with no +qualifier. A grade is derived from receipts, never asserted. A "verified" or +"machine-checked" claim needs current receipts. Report a census with its +denominator, never a percentage. Always write the `PWG-` prefix: CRG, TRG, ARG +and FRG letters, and ECHIDNA's `TrustLevel`, are different schemes. --- -# This repo: `rsr-template-repo` · clade `rm-rsr-template-repo` +# This repo: `CoprocessorRuntime.jl` -- **Identity** — uuid `a5ea1382-a34c-5334-8a46-a2ebe904c810`; clade `rm` (secondary ``); born 2026-03-16; forge `hyperpolymath/rsr-template-repo`. -- **IS** — Canonical RSR-compliant repository template: scaffolding (CI/CD, AI manifests, ABI/FFI standards, container ecosystem, governance) that new hyperpolymath projects are instantiated from. -- **IS-NOT** — a project in its own right · Scaffoldia (the full-featured repo designer) · standards (the canon source this template operationalises) -- **Where it sits** — pipeline position **foundation**; chain `standards → rsr-template-repo → (every estate repo)`; coordination = `standards`. -- **Constraints here** (AGENTIC) — fail-closed; evidence-per-step; no-silent-skip; rerun-after-fix; release-claim-requires-hard-pass. Never: banned langs (above), secrets, state files in repo root, AGPL. Details: `.machine_readable/bot_directives/{methodology,coverage,debt}.a2ml`. -- **Golden path** (ANCHOR) — `just test && just quality` → Core tests pass; Quality gates pass; No unresolved critical security findings. -- **State** — phase maintenance; maturity production; 95% complete; status active. +- **Identity** — chora id `#uuid"d2c7544a-4b3e-80c4-a9d2-ea7e46aecac6"`; clade: none declared (optional placement); born 2026-09-26; forge `hyperpolymath/CoprocessorRuntime.jl`. +- **IS** — A host-side contract and evidence layer for coprocessor launches: models host/device roles, resource grades, transfer residues, launch receipts and CNO/OND claims. It records launch semantics; it does not run accelerator kernels. +- **IS-NOT** — an executor of CUDA / ROCm / Metal / TPU kernels: that is CUDA.jl, AMDGPU.jl, Metal.jl, KernelAbstractions.jl · a backend selector: that is AcceleratorGate.jl · a healer of failing kernels: that is HardwareResilience.jl · a proof of CNO/OND: that is absolute-zero; status here is :unproved or :model_checked · a closure of K-CUT: that conjecture is open in choreographic-types +- **Where it sits** — pipeline position **UNASSIGNED**; chain `UNASSIGNED`; coordination = `standards`. +- **Constraints here** (AGENTIC) — fail-closed; evidence-per-step; no-silent-skip; rerun-after-fix; release-claim-requires-hard-pass. Never: banned langs (above), secrets, state files in repo root, AGPL. Details: the deed's `(bot-directives (methodology) (coverage) (debt))` clauses. +- **Golden path** (ANCHOR) — `julia --project=. -e 'using Pkg; Pkg.test()'` → Package tests pass (test/runtests.jl, including the Aqua checks). +- **State** — phase incubating; maturity experimental. Milestones and next actions: `docs/status/ROADMAP.adoc`. - + diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 597c746..f453412 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,6 +1,6 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // SPDX-FileCopyrightText: Jonathan D.A. Jewell (hyperpolymath) -= Contributing — rsr-template-repo += Contributing — CoprocessorRuntime.jl :toc: left Contributors work on the *spine*: the template every RSR repo is minted @@ -12,15 +12,15 @@ is the estate's bar. [source,bash] ---- # Clone the repository -git clone https://github.com/hyperpolymath/rsr-template-repo.git -cd rsr-template-repo +git clone https://github.com/hyperpolymath/CoprocessorRuntime.jl.git +cd CoprocessorRuntime.jl # Using Guix (recommended for reproducibility) guix shell -D -f build/guix.scm # Or using toolbox/distrobox -toolbox create rsr-template-repo-dev -toolbox enter rsr-template-repo-dev +toolbox create CoprocessorRuntime.jl-dev +toolbox enter CoprocessorRuntime.jl-dev # Install dependencies manually # Verify setup @@ -80,10 +80,10 @@ and include: Look for issues labelled: -* https://github.com/hyperpolymath/rsr-template-repo/labels/good%20first%20issue[`good first issue`] — Simple Perimeter 3 tasks -* https://github.com/hyperpolymath/rsr-template-repo/labels/help%20wanted[`help wanted`] — Community help needed -* https://github.com/hyperpolymath/rsr-template-repo/labels/documentation[`documentation`] — Docs improvements -* https://github.com/hyperpolymath/rsr-template-repo/labels/perimeter-3[`perimeter-3`] — Community sandbox scope +* https://github.com/hyperpolymath/CoprocessorRuntime.jl/labels/good%20first%20issue[`good first issue`] — Simple Perimeter 3 tasks +* https://github.com/hyperpolymath/CoprocessorRuntime.jl/labels/help%20wanted[`help wanted`] — Community help needed +* https://github.com/hyperpolymath/CoprocessorRuntime.jl/labels/documentation[`documentation`] — Docs improvements +* https://github.com/hyperpolymath/CoprocessorRuntime.jl/labels/perimeter-3[`perimeter-3`] — Community sandbox scope == Development workflow diff --git a/CoprocessorRuntime.jl_chora.deed b/CoprocessorRuntime.jl_chora.deed index b32c09e..1764c72 100644 --- a/CoprocessorRuntime.jl_chora.deed +++ b/CoprocessorRuntime.jl_chora.deed @@ -1,20 +1,113 @@ ;; SPDX-License-Identifier: MPL-2.0 ; -; The repo deed of rsr-template-repo: one-deed-per-repo doctrine (standards#837, +; The repo deed of CoprocessorRuntime.jl: one-deed-per-repo doctrine (standards#837, ; owner ruling 2026-09-19, Option A). Folds the former ply manifest tree ; (0.N-AI-MANIFEST.a2ml, 82 directories) and the family-7 AI ; allocation manifest (root 0-AI-MANIFEST.a2ml) into deed clauses. ; Generated by the #837 pilot emitter; every byte gated by deed_lint.py. (repo-deed :schema-version "1.0.0" - :canonical-name "rsr-template-repo" - :beholding-chora #u5"estate/chora" - :repo-uuid #u5"github.com/hyperpolymath/rsr-template-repo" + :canonical-name "CoprocessorRuntime.jl" + :beholding-chora #uuid"0889b37b-defb-831f-973c-e119500db00e" + :repo-uuid #uuid"d2c7544a-4b3e-80c4-a9d2-ea7e46aecac6" + ; >>> repo-identity + ; Written by `just repo-init` from build/templates/identity.deed.in, in + ; place of the block the template repo ships (template issue #209). It replaces + ; descriptiles/CLADE.a2ml and ECOSYSTEM.a2ml; the mapping is standards + ; 1-formats/deed/mappings/clade-to-repo-deed.adoc and + ; meta-ecosystem-to-repo-deed.adoc. + ; + ; THE ID IS MINTED ONCE, NOT INVENTED. The header :repo-uuid is this repo's + ; chora id: the ADR-008 profile C UUIDv8 of its birth path in the domain + ; chora-registry (standards A1 rules U1 to U4, V8 and V9, A7 J11): + ; bash scripts/uuid-v8.sh chora-registry "github.com/hyperpolymath/CoprocessorRuntime.jl" + ; repo-init wrote it at mint. It is carried opaquely and never re-derived: + ; a transfer or rename does not change it. Do not edit it. + ; + ; THE ID IS THE CHORA, NOT THE CLADE (standards A1, ruling W10). The deed + ; header's :repo-uuid is the repo's id. A clade placement is an OPTIONAL + ; identity fact (where the repo sits), never the id and never an edict; + ; chora-registry is authoritative for it. No check requires one, and no name + ; prefix is required. When you do + ; choose one, add a clause beside (identity), for example + ; (clade :primary gm :primary-name "Games & Interactive" :secondary () + ; :assigned "YYYY-MM-DD" :rationale "why") + ; and `just validate-rsr` then checks that the code is one of the 12 and + ; agrees with its name. The 12, read off the RIGHT-HAND column, never off + ; the repository name (two real mis-choices read `pt` and `gv` as letters of + ; the slug): + ; fv Formal Verification & Proofs provable correctness, dependent types, theorem proving + ; nl Nextgen Languages compilers, runtimes, language tooling + ; rm Repo Management & Tooling scaffolding, graph analysis, bots, templates + ; gv Governance & Standards licensing, compliance, policy enforcement + ; db Databases database engines, query languages, storage + ; ap Applications end-user apps, web, desktop, services + ; ix Infrastructure & Cloud containers, deployment, sysadmin + ; dx Developer Ecosystem dev tools, package managers, editors, bindings + ; pt Protocols & Interop internet standards, protocol implementations + ; ax AI & Neurosymbolic ML, neural proof synthesis, AI governance + ; gm Games & Interactive game engines, interactive experiences + ; sc Security scanning, vulnerability management, access control + ; The primary clade reflects the project's core value proposition, not its + ; implementation: a game written in Idris2 is `gm`. + ; + ; REGISTRATION IS NOT DERIVATION. Registering means an entry in the + ; chora-registry (formerly gv-clade-index) seed. It is outward-facing + ; and it is the OWNER's act; an agent must not do it. + (identity + :primary-forge github + :owner "hyperpolymath") + (forges + :github "hyperpolymath/CoprocessorRuntime.jl") + ; :type is one of standalone monorepo monorepo-child inflated deflated hub + ; satellite. A hub COORDINATES an ecosystem family; a satellite is + ; coordinated by one and keeps :parent "" (parent names a monorepo parent, + ; never the coordinating hub). + (lineage + :type standalone + :parent "" + :born "2026-09-26" + :previous-names () + :instantiated-from "rsr-template-repo") + ; :phase is one of reserved incubating active dormant merged superseded + ; archived extinct. A repo created today has not proven anything yet. + (status + :phase incubating + :since "2026-09-26" + :present #t + :aliases () + :merged-into "" + :superseded-by "" + :successors () + :ended "" + (history + (entry :phase incubating :since "2026-09-26" :note "created from rsr-template-repo; not yet registered"))) + ; :level is one of experimental alpha beta production lts (standards + ; 1-formats/deed/vocabulary/maturity.adoc). + (maturity + :level experimental + :since "2026-09-26") + ; Fill in what this repo IS and IS NOT, and the repos it relates to. + ; :relationship is one of standard-source build-tooling validation-tooling + ; signing-tooling verification-tooling minted-from registry. + (ecosystem + :project "CoprocessorRuntime.jl" + :ecosystem "hyperpolymath" + :position-type "UNASSIGNED" + :purpose "A host-side contract and evidence layer for coprocessor launches: models host/device roles, resource grades, transfer residues, launch receipts and CNO/OND claims. It records launch semantics; it does not run accelerator kernels." + :not ("an executor of CUDA / ROCm / Metal / TPU kernels: that is CUDA.jl, AMDGPU.jl, Metal.jl, KernelAbstractions.jl" "a backend selector: that is AcceleratorGate.jl" "a healer of failing kernels: that is HardwareResilience.jl" "a proof of CNO/OND: that is absolute-zero; status here is :unproved or :model_checked" "a closure of K-CUT: that conjecture is open in choreographic-types") + :pipeline-position "UNASSIGNED" + :chain "UNASSIGNED" + :coordination standards + (related :name "rsr-template-repo" :relationship minted-from :notes "the template this repo was minted from by just repo-init") + ; The closed :relationship set has 16 terms, not the 7 above (standards meta-ecosystem-to-repo-deed.adoc, [related-projects] row; section 3.1 defines 5 of them). None says "extension of"; code-dependency (code is linked) is the nearest. + (related :name "AcceleratorGate.jl" :relationship code-dependency :notes "Kept as an extension of AcceleratorGate.jl (owner decision 2026-11-17); both repos stay and neither is released to the Julia General registry. The link is the optional weak dependency AcceleratorGate in Project.toml and the package extension ext/AcceleratorGateExt.jl, which maps each AcceleratorGate backend type to a CoprocessorKind (4 backend types map to UnknownKind). It records which kind a backend is; it does not select a backend or run anything.")) + ; <<< repo-identity (manifest :version "0.1.0" :last-updated "2026-09-26" - :project "[YOUR-REPO-NAME]" - :purpose "Canonical RSR (Rhodium Standard Repository) template — governance, CI/CD, machine-readable metadata, ABI/FFI seam and formal-verification scaffolding that hyperpolymath projects are instantiated from." + :project "CoprocessorRuntime.jl" + :purpose "A host-side contract and evidence layer for coprocessor launches: models host/device roles, resource grades, transfer residues, launch receipts and CNO/OND claims. It records launch semantics; it does not run accelerator kernels." (agent :name CLAUDE :role "proofs, compilers, repo-local implementation, CI/CD, formal verification, Rust/Idris2/Zig") (agent :name CHATGPT :role "prose, papers, publication review, standards docs, outreach drafts, letters") (agent :name GEMINI :role "estate audits, cross-repo sweeps, long-context triage, pattern detection") @@ -28,14 +121,12 @@ (ply (directory :ply 1 :path ".github") (directory :id "machine-readable-pillar" :ply 1 :path ".machine_readable" :description "Registry for all machine-readable metadata, policies, and internal\nautomation scripts." - (canonical-locations :agentic "descriptiles/AGENTIC.a2ml" :ai_configs "ai/" :anchors "descriptiles/anchors/" :clade "descriptiles/CLADE.a2ml" :compliance "compliance/" :ecosystem "descriptiles/ECOSYSTEM.a2ml" :meta "descriptiles/META.a2ml" :neurosym "descriptiles/NEUROSYM.a2ml" :playbook "descriptiles/PLAYBOOK.a2ml" :policies "policies/" :scripts "scripts/" :state "descriptiles/STATE.a2ml") - :invariants ("Metadata files MUST follow a2ml format" "Internal automation MUST live in scripts/ subfolder") + (canonical-locations :ai_configs "ai/" :anchor "CoprocessorRuntime.jl_chora.deed (anchor)" :compliance "compliance/" :neurosym "CoprocessorRuntime.jl_chora.deed (neurosym)" :playbook "CoprocessorRuntime.jl_chora.deed (playbook)" :policies "CoprocessorRuntime.jl_chora.deed (policies)" :scripts "scripts/") + :invariants ("Repo metadata MUST live in the repo deed (CoprocessorRuntime.jl_chora.deed) and follow the DEED grammar" "Internal automation MUST live in scripts/ subfolder") (directory :id "ai-registry" :ply 2 :path ".machine_readable/ai" :description "Sub-registry for ai metadata.") (directory :id "configs-registry" :ply 2 :path ".machine_readable/configs" :description "Sub-registry for configs metadata.") (directory :ply 0 :path ".machine_readable/descriptiles" :description "This manifest declares the AI-assistant context for the descriptiles machine-readable metadata directory." - :invariants ("No duplicate files in root directory" "Single source of truth: this directory is authoritative" "No stale metadata") - (directory :ply 0 :path ".machine_readable/descriptiles/anchors" :description "This manifest declares the AI-assistant context for the anchor machine-readable metadata directory." - :invariants ("Multiple versions with different dates are permitted" "No other A2ML files in this directory" "Single source of truth for anchor documents"))) + :invariants ("No duplicate files in root directory" "Single source of truth: this directory is authoritative" "No stale metadata")) (directory :id "policies-registry" :ply 2 :path ".machine_readable/policies" :description "Sub-registry for policies metadata.") (directory :id "automation-scripts-unit" :ply 2 :path ".machine_readable/scripts" :description "Internal automation logic for the project lifecycle, forge sync,\nverification triggers, and maintenance." (canonical-locations :forge "forge/" :lifecycle "lifecycle/" :maintenance "maintenance/" :verification "verification/") @@ -45,7 +136,7 @@ (directory :id "container-templates" :ply 1 :path "build/container" :version "1.0.0" :description "Container templates for the stapeln container ecosystem. This directory\nprovides Podman-Chainguard-stapeln templates that are customised via\n`just container-init` or `just repo-init` during project bootstrap.\n\nAll files use {{PLACEHOLDER}} tokens that are substituted with project-\nspecific values during initialisation." :purpose "Provide a complete, security-first container deployment story for any\nRSR-compliant repository. The templates cover the full lifecycle:\nbuild, sign, verify, deploy, monitor, and govern." :overview "The stapeln container ecosystem comprises six tools:\n\nselur — Container orchestration with zero-copy IPC. Reads compose.toml.\ncerro-torre — Verified container packaging (.ctp bundles), Ed25519 signing.\nsvalinn — Policy-driven edge gateway (auth, rate limits, CORS, trust).\nvordr — Runtime monitoring (health, crashes, resources, logs).\nrokur — Secrets management (runtime injection, no baked secrets).\nk9-svc — Nickel deployment components (Kennel/Yard/Hunt trust levels)." - :context ("https://a2ml.org/ns/v2" "https://stapeln.dev/ns/v1") + :context ("https://stapeln.dev/ns/v1") (canonical-locations :build_pipeline "build/container/stapeln/ct-build.sh" :compose "build/container/stapeln/compose.toml" :compose_example "build/container/stapeln/compose.example.toml" :compose_portable "build/container/compose.yaml" :compose_portable_example "build/container/compose.example.yaml" :containerfile "build/container/Containerfile" :containerignore "build/container/.containerignore" :deployment "build/container/stapeln/deploy.k9.ncl" :entrypoint "build/container/entrypoint.sh" :gatekeeper "build/container/stapeln/.gatekeeper.yaml" :just_module "build/just/container.just" :manifest "build/container/stapeln/manifest.toml" :monitoring "build/container/stapeln/vordr.toml" :secrets_gate "build/container/stapeln/rokur.toml") :invariants ("Base images MUST be cgr.dev/chainguard/wolfi-base or cgr.dev/chainguard/static" "Container runtime is Podman — never Docker" "Containerfile — never Dockerfile" "All images run as non-root (appuser or project-specific user)" ".ctp bundles are signed with Ed25519 via cerro-torre" "Health endpoints (/health, /ready) must always be public (no auth)") (file-relationships @@ -56,7 +147,7 @@ (file :name "ct-build.sh" :role "Build Pipeline" :description "Shell script implementing the 5-stage pipeline: build (Podman),\npack (cerro-torre .ctp), sign (Ed25519), verify, push (optional).\nDegrades gracefully when cerro-torre tools are not installed." :depends-on ("Containerfile" "manifest.toml")) (file :name "entrypoint.sh" :role "Container Entrypoint" :description "Startup script with signal handling (SIGTERM, SIGINT), logging, and\nexec into the main application process." :depends-on ()) (file :name "vordr.toml" :role "Runtime Monitoring" :description "Vordr monitoring configuration. Health endpoint probing, crash\ndetection, resource thresholds, and structured log output." :depends-on ()) - (file :name "deploy.k9.ncl" :role "Deployment Component" :description "k9-svc deployment specification at Hunt trust level. Full pedigree\n(L1-L5), environment configs, container config, and rolling\ndeployment strategy." :depends-on ("compose.toml" "ct-build.sh")) + (file :name "deploy.k9.ncl.in" :role "Deployment Component (template)" :description "k9-svc deployment component at the Hunt leash, K9 contract v1.0.0:\npedigree with capability grant, side effects and signature block;\nenvironment configs, container config, rolling deployment strategy,\ndeploy scripts and Just recipes. `just container-init` renders it to\ndeploy.k9.ncl once no placeholder token is left." :depends-on ("compose.toml" "ct-build.sh")) (file :name "compose.example.toml" :role "Example" :description "Fully-commented multi-service example (Rust API + Elixir worker +\nsvalinn gateway). Copy to compose.toml and customise." :depends-on ()) )) (directory :id "docs-pillar" :ply 1 :path "docs" :description "Technical documentation hub. The root contains high-level orientation\n(README, Quickstart, State-Visualizer). Specialized tracks live in\nsubdirectories." @@ -151,4 +242,18 @@ (directory :ply 2 :path "verification/tests") (directory :id "verification-unit-traceability" :ply 2 :path "verification/traceability" :description "High-assurance verification unit for traceability. \nCritical for safety-of-life and aerospace-grade deployment standards.")) ) + ; ANCHOR: only what the arrival pack and coaptation read, the golden path. The + ; rest of descriptiles/anchors/ANCHOR.a2ml is not converted here (conversion + ; belongs to kyX, owner ruling D313). The Justfile `test` recipe is still the + ; template's fail-loudly placeholder, so the golden path is the command + ; julia-ci.yml runs, not `just test`. + (anchor + :schema "hyperpolymath.anchor/1" + :repo "hyperpolymath/CoprocessorRuntime.jl" + :authority "upstream-canonical" + (golden-path + :smoke-test-command ("julia --project=. -e 'using Pkg; Pkg.test()'") + :success-criteria ( + "Package tests pass (test/runtests.jl, including the Aqua checks)" + ))) ) diff --git a/Justfile b/Justfile index 73d565d..a6148ad 100644 --- a/Justfile +++ b/Justfile @@ -590,7 +590,7 @@ assail: # Self-diagnostic — checks dependencies, permissions, paths doctor: - @echo "Running diagnostics for rsr-template-repo..." + @echo "Running diagnostics for CoprocessorRuntime.jl..." @echo "Checking required tools..." @command -v just >/dev/null 2>&1 && echo " [OK] just" || echo " [FAIL] just not found" @command -v git >/dev/null 2>&1 && echo " [OK] git" || echo " [FAIL] git not found" @@ -600,7 +600,7 @@ doctor: # Guided tour of key features tour: - @echo "=== rsr-template-repo Tour ===" + @echo "=== CoprocessorRuntime.jl Tour ===" @echo "" @echo "1. Project structure:" @ls -la @@ -615,12 +615,12 @@ tour: # Open feedback channel with diagnostic context help-me: - @echo "=== rsr-template-repo Help ===" + @echo "=== CoprocessorRuntime.jl Help ===" @echo "Platform: $(uname -s) $(uname -m)" @echo "Shell: $SHELL" @echo "" @echo "To report an issue:" - @echo " https://github.com/hyperpolymath/rsr-template-repo/issues/new" + @echo " https://github.com/hyperpolymath/CoprocessorRuntime.jl/issues/new" @echo "" @echo "Include the output of 'just doctor' in your report." diff --git a/build/guix.scm b/build/guix.scm index 5a769d6..a30ab35 100755 --- a/build/guix.scm +++ b/build/guix.scm @@ -9,12 +9,12 @@ (gnu packages bash)) (package - (name "rsr-template-repo") + (name "CoprocessorRuntime.jl") (version "0.1.0") (source #f) (build-system gnu-build-system) (inputs (list coreutils bash)) - (synopsis "rsr-template-repo") - (description "rsr-template-repo — part of the hyperpolymath ecosystem.") - (home-page "https://github.com/hyperpolymath/rsr-template-repo") + (synopsis "CoprocessorRuntime.jl") + (description "CoprocessorRuntime.jl — part of the hyperpolymath ecosystem.") + (home-page "https://github.com/hyperpolymath/CoprocessorRuntime.jl") (license (@ (guix licenses) mpl2.0))) diff --git a/ci/.pre-commit-config.yaml b/ci/.pre-commit-config.yaml index 8069164..f4ca0e4 100644 --- a/ci/.pre-commit-config.yaml +++ b/ci/.pre-commit-config.yaml @@ -62,12 +62,12 @@ repos: hooks: - id: gitleaks - # --- Arrival pack drift: CLAUDE.md must stay in sync with a2ml --- + # --- Arrival pack drift: CLAUDE.md must stay in sync with the repo deed --- - repo: local hooks: - id: validate-claude-md - name: CLAUDE.md arrival pack in sync with a2ml + name: CLAUDE.md arrival pack in sync with the repo deed entry: bash .machine_readable/arrival-pack/verify.sh language: system pass_filenames: false - files: '^(\.machine_readable/descriptiles/.*|CLAUDE\.md)$' + files: '^([^/]+_chora\.deed|\.machine_readable/arrival-pack/.*|CLAUDE\.md)$' diff --git a/docs/history/A2ML-IDENTITY-RESYNC.adoc b/docs/history/A2ML-IDENTITY-RESYNC.adoc new file mode 100644 index 0000000..9eb16c2 --- /dev/null +++ b/docs/history/A2ML-IDENTITY-RESYNC.adoc @@ -0,0 +1,107 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += Template identity removed from the A2ML files, 2026-11-17 + +This repository was minted from `rsr-template-repo` but kept the template's own +identity. The deed header and `CLAUDE.md` now state this repository's own +identity (`CoprocessorRuntime.jl_chora.deed`; the arrival pack is generated +from it). This record covers the `.a2ml` files that still declared the +template. It follows the shape of boj-server's `docs/history/A2ML-REMOVED.adoc`. + +A2ML is retired. The only edit made to any `.a2ml` file was deleting lines: no +line was added or changed, no file was created or restored, and nothing was +converted. Git history keeps the old content; read a file with +`git show 6ccf6c9:`. Size and sha256 prefix are of the file as it stood +at 6ccf6c9; the blob id is its git blob. + +== No `.a2ml` file was removed + +Removing `CLADE.a2ml` and `ECOSYSTEM.a2ml` was tried first and rejected. With +the files removed, `just validate-rsr`, `scripts/validate-template.sh`, the Must +clause `six-directory-present` and the coaptation tooling all fail. With +deletion-only stubs they all pass, except that the coaptation still fails as it +already did on main (see below). The two files are therefore kept as stubs. + +== Content deleted + +[cols="4,1,2,2,1,5",options="header"] +|=== +| Path | Size | sha256 (prefix) | Git blob id | Lines deleted | What was deleted, and where it went + +| `.machine_readable/descriptiles/CLADE.a2ml` +| 3567 +| `374291c947fbe584` +| `3acb193f1b73` +| 54 +| The banner "THIS IS rsr-template-repo's OWN IDENTITY", the template's uuid (`a5ea1382-…`), `canonical-name`, `prefixed-name`, the whole `[clade]` block (`rm`, rationale), `[forges]`, `born`, and the template's active phase, since and history entry. This repository's own values are in the deed's `(identity)`, `(forges)`, `(lineage)` and `(status)` clauses; it has no clade. What remains is generic: `primary-forge`, `primary-owner`, `type`, `parent`, `previous-names` and the empty `[status]` fields. + +| `.machine_readable/descriptiles/ECOSYSTEM.a2ml` +| 2729 +| `8680c941f9683eac` +| `9b2b53706bcd` +| 39 +| The template's `project`, `type = "repository-template"`, `purpose`, `what-this-is-not`, `[pipeline]` position, chain and notes, `[related-projects]` and the notes for consumers. This repository's values are in the deed's `(ecosystem)` clause. What remains: `ecosystem = "hyperpolymath"` and `coordination = "standards"`. + +| `.machine_readable/descriptiles/STATE.a2ml` +| 4358 +| `fad6192c73ea8dd2` +| `89c6f4ede6c0` +| 6 +| "This is the STATE file for rsr-template-repo itself" and the two lines after it, `project`, `name` and `purpose`. This repository's phase and maturity are in the deed's `(status)` and `(maturity)`. + +| `.machine_readable/rsr-profile.a2ml` +| 7616 +| `f62b3b2eb3d603a5` +| `1b02cb98f701` +| 8 +| One comment paragraph, "rsr-template-repo is deliberately MAXIMAL…". The `[canon]` block that `dogfood-gate.yml` reads is untouched; the gate's own `canon_key` reader gives the same version and both hashes before and after. + +| `.machine_readable/ai/AI.a2ml` +| 2290 +| `a013f6f89edf499d` +| `d25039f14476` +| 1 +| The line "`rsr-template-repo` is treated as a Rhodium Standard Repository…". + +| Contractile Xfiles: `intend/Intentfile.a2ml`, `must/Mustfile.a2ml`, `trust/Trustfile.a2ml`, `adjust/Adjustfile.a2ml`, `dust/Dustfile.a2ml`, `bust/Bustfile.a2ml` +| 3482, 4117, 4047, 2518, 3252, 2567 +| `b5248bb14c9b12d2`, `1efd686e70957332`, `44cb84cef597c43b`, `8faad9ca06500fc0`, `47cb31fdfb0691d8`, `dd6a53e1fc9b1223` +| `ef74f4529719`, `ddb572ac0922`, `e6eeed57b42a`, `6f01e89f678a`, `3dabca0f74b0`, `c7fec2bccc57` +| 16, 6, 9, 7, 8, 8 +| The title comment ("… for rsr-template-repo"), the `@abstract:` block that says this is the canonical template, the Intentfile "Purpose" section, the "This repository: rsr-template-repo is the canonical template" comments (Dustfile, Bustfile) and the Trustfile's "operates at trust level" sentence. No `###` clause was touched. +|=== + +== Readers, and what they see now + +* `build/just/validate.just` (`validate-rsr`), `assess.just`, `groove.just` and `scripts/validate-template.sh` test that `ECOSYSTEM.a2ml` exists. It does, so they pass. +* The Must clause `six-directory-present` tests that `ECOSYSTEM.a2ml` exists. It does, so it passes. +* `.github/hooks/validate-deed.sh` and the upstream `deed-ecosystem` validator accept all the edited files. +* `.machine_readable/coaptation/` reads `CLADE.a2ml`, `ECOSYSTEM.a2ml` and `STATE.a2ml`. Its committed receipt was already stale on main and still is. The stubs lose the facts `clade.*` and `ecosystem.type`, so a fresh run now reports the witness `must.six-directory-present` as refuted and the band as red (it was green fresh on main). This is not run in CI. Moving the coaptation to the deed needs the contractile K9 files moved off the missing `../k9/template-hunt.k9.ncl` first, which is a separate change; once done, the stubs can be deleted. + +== Residual mentions left in place + +[cols="3,5",options="header"] +|=== +| Path | Why it stays + +| `.machine_readable/coaptation/receipts/latest.a2ml` +| A historical receipt (`repo = "rsr-template-repo"`). It is generated output, not a declaration. + +| `.machine_readable/bot_directives/rra.a2ml` (`(file "rsr-template-repo_chora.deed")`) +| A stale file name in the root allow-list. Substituting is not allowed, and deleting the line would drop the deed from an allow-list read by an external bot that cannot be seen from this repository. Needs the owner. + +| `.machine_readable/bot_directives/methodology.a2ml` (`reject-if-contains`) +| A detection rule that names the template on purpose. + +| `contractiles/*/*.manifest.a2ml` (`context = "… canonical template in rsr-template-repo."`) +| Names the template as the source of the verb definition (upstream attribution), inside a required field. + +| `contractiles/dust/Dustfile.a2ml` and `bust/Bustfile.a2ml` clauses (`no references to rsr-template-repo…`, drift and injection probes) +| They are clauses about the template. Deleting one changes the coaptation clause set. +|=== + +== Where the identity went + +* `CoprocessorRuntime.jl_chora.deed`: header ids; `(identity)`, `(forges)`, `(lineage)`, `(status)`, `(maturity)`, `(ecosystem)` with its `(related …)` entries; a minimal `(anchor)`; `(ply)` at the template's text. The clade is left unassigned, since chora-registry is authoritative for it. +* `CLAUDE.md` "This repo" block: generated by `just claude-md` from the deed. +* Non-A2ML files that named the template as this repo (`CONTRIBUTING.adoc`, `.github/{CONTRIBUTING,SECURITY,CODE_OF_CONDUCT}.md`, `build/guix.scm`, `.machine_readable/contractiles/Justfile`, `docs/onboarding/*`, the Justfile echoes and the SonarCloud comment): rewritten by the template's own self-name rule from `build/just/repo-init.just`, with every hunk read. diff --git a/docs/onboarding/QUICKSTART-DEV.adoc b/docs/onboarding/QUICKSTART-DEV.adoc index 33918d6..8b7b366 100644 --- a/docs/onboarding/QUICKSTART-DEV.adoc +++ b/docs/onboarding/QUICKSTART-DEV.adoc @@ -1,104 +1,158 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -// Template: QUICKSTART-DEV.adoc — clone → build → test → PR -// Replace rsr-template-repo, julia --project=. -e 'using Pkg; Pkg.instantiate()', julia --project=. -e 'using Pkg; Pkg.test()', Julia (1.10+) with actuals -= rsr-template-repo — Quick Start for Developers += CoprocessorRuntime.jl — Quick Start for Developers :toc: :toclevels: 2 -== Tech Stack +== Tech stack -Julia (1.10+) +Julia 1.10 or later (`julia = "1.10"` in `Project.toml`). There are no runtime +dependencies. `AcceleratorGate` is a weak dependency used by one package +extension. The test environment adds `Test` and `Aqua`. -== Set Up Development Environment - -=== Option A: Guix (preferred) +== Set up [source,bash] ---- -guix shell +git clone https://github.com/hyperpolymath/CoprocessorRuntime.jl.git +cd CoprocessorRuntime.jl +julia --project=. -e 'using Pkg; Pkg.instantiate()' ---- -=== Option B: Manual +`Manifest.toml` is git-ignored; do not commit one. + +== Test [source,bash] ---- -git clone https://github.com/hyperpolymath/rsr-template-repo.git -cd rsr-template-repo -just setup-dev +julia --project=. -e 'using Pkg; Pkg.test()' ---- -== Build +This runs `test/runtests.jl`: the Aqua checks, then the cases under +`test/cases/` (`smoke`, `grades`, `sessions`, `receipts`, `choreography`), then +the extension tests. -[source,bash] ----- -julia --project=. -e 'using Pkg; Pkg.instantiate()' ----- +The extension tests (`AcceleratorGateExt`) run in their own environment, +`test/ext`, which fetches AcceleratorGate by URL from a pinned commit. That +needs Julia 1.11. On Julia 1.10 they are reported as one `Broken` test and a +message says why, so a 1.10 run shows `Broken 1`. To skip them deliberately, +set `COPROCESSORRUNTIME_SKIP_EXT_TESTS=1`. -== Test +== Checks CI runs -[source,bash] ----- -julia --project=. -e 'using Pkg; Pkg.test()' ----- +`.github/workflows/julia-ci.yml` runs three jobs on every pull request and on +pushes to `main` and `master`. To reproduce them, run the same commands. -== Project Structure +*Tests and Aqua* (Julia 1.10 and the latest 1.x): the `Pkg.test()` command above. -[source] +*Static analysis* (JET, latest 1.x): + +[source,bash] ---- -rsr-template-repo/ -├── src/ # Source code -├── src/interface/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 -├── build/ # Build orchestration (just/, guix.scm, container/) -└── *_chora.deed # repo deed: AI entry point (allocation + ply tree) +julia --project=. -e ' + using Pkg + Pkg.add("JET") + using JET + using CoprocessorRuntime + JET.test_package(CoprocessorRuntime)' ---- -== Key Recipes +*Format* (JuliaFormatter, check mode, latest 1.x). It covers `src/`, `test/` +and `test/cases/`: [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 ----- +julia --project=. -e ' + using Pkg + Pkg.add("JuliaFormatter") + using JuliaFormatter + for f in filter(f -> isfile(f) && endswith(f, ".jl"), collect(Iterators.flatten(( + [joinpath("src", x) for x in readdir("src")], + [joinpath("test", x) for x in readdir("test") if x != "cases"], + [joinpath("test", "cases", x) for x in readdir(joinpath("test", "cases"))], + )))) + text = read(f, String) + formatted = JuliaFormatter.format_text(text) + if text != formatted + @error "not formatted" file=f + exit(1) + end + end' +---- + +The last two commands run `Pkg.add`, which edits `Project.toml` in the +checkout. Run them in a throwaway copy, or restore the file afterwards with +`git checkout Project.toml`. + +== Project structure -== Before Submitting a PR +[source] +---- +CoprocessorRuntime.jl/ +├── Project.toml # package, weak dependency, compat +├── src/ # the package: one file per concept +│ ├── CoprocessorRuntime.jl # module and exports +│ ├── Kinds.jl # roles and coprocessor kinds +│ ├── Sessions.jl # sessions +│ ├── Grades.jl # tropical resource grades +│ ├── EchoLoss.jl # transfer residues +│ ├── Receipts.jl # launch receipts, warrants +│ ├── Nullity.jl # CNO / OND claims +│ └── Choreography.jl # launch plans, projection, hub ceiling +├── ext/AcceleratorGateExt.jl # optional AcceleratorGate mapping +├── test/ # runtests.jl, cases/, ext/ (extension environment) +├── docs/ # documentation +├── CoprocessorRuntime.jl_chora.deed # repo deed: identity, ecosystem, status +└── CLAUDE.md # arrival pack for AI assistants +---- + +The other directories under `src/` (`aspects/`, `interface/`, `bridges/` and +so on) are not loaded by the module, and the shell checks under `tests/` are +not run by `Pkg.test()`. +The generated map of every directory is +link:../architecture/REPOSITORY-MAP.adoc[REPOSITORY-MAP.adoc]. + +== The optional extension + +`ext/AcceleratorGateExt.jl` is a package extension (`[extensions]` in +`Project.toml`). It loads only when `AcceleratorGate` is also loaded, and it +maps each AcceleratorGate backend type to a `CoprocessorKind`. Four backend +types (`PPUBackend`, `MathBackend`, `VPUBackend`, `CryptoBackend`) have no kind +here and map to `UnknownKind`. Adding a kind is an API change to this package. + +== just recipes + +The root `Justfile` is largely template scaffolding. `just test`, `just build`, +`just run`, `just lint` and `just fmt` are placeholders; `just test` fails on +purpose until it is wired. Use the Julia commands above instead. These recipes +do real work: [source,bash] ---- -just lint # Format and lint -just test # All tests pass -just panic-scan # No new security issues +just repo-map # regenerate docs/architecture/REPOSITORY-MAP.adoc +just validate-repo-map # fail if the map is stale (CI diffs it) +just validate-claude-md # fail if CLAUDE.md drifted from the deed (needs nickel) ---- -== Contractile Invariants - -Read `.machine_readable/MUST.contractile` before making changes. -Key invariants that must never be violated: +Run `just --list` for the rest. -no vendor kernels; hub_ceiling refusal; receipts are not proofs +== Design commitments -== LLM/AI Agent Development +Taken from the README and the repo deed; do not weaken them: -If using an AI assistant, load the warmup context first: +* No vendor kernels are executed or selected here. +* There is no universal hub: `universal_hub_allowed()` throws `HubCeilingRefusal`. +* Receipts, CNO claims and OND claims are claims, not proofs. Their status is + `:unproved` or `:model_checked`. +* K-CUT stays `:open`. -[source,bash] ----- -just llm-context # Outputs role-appropriate context ----- +== Before opening a pull request -Or read the repo deed (`*_chora.deed` at root) and `.claude/CLAUDE.md` directly. +* Tests, JET and the format check above pass. +* Sign every commit. A ruleset requires signatures, and squash-merges pull + requests; see link:../../CONTRIBUTING.adoc[CONTRIBUTING]. +* Use Conventional Commits, for example `fix(grades): ...`. -== Get Help +== AI assistants -* **Architecture**: link:EXPLAINME.adoc[EXPLAINME.adoc] -* **Wiki**: https://github.com/hyperpolymath/rsr-template-repo/wiki -* **Report issue**: `just help-me` +Read `CLAUDE.md` and the repo deed (`CoprocessorRuntime.jl_chora.deed`) first. diff --git a/docs/onboarding/QUICKSTART-MAINTAINER.adoc b/docs/onboarding/QUICKSTART-MAINTAINER.adoc index 82b7557..fad80df 100644 --- a/docs/onboarding/QUICKSTART-MAINTAINER.adoc +++ b/docs/onboarding/QUICKSTART-MAINTAINER.adoc @@ -1,123 +1,78 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -// Template: QUICKSTART-MAINTAINER.adoc — packaging, deploying, and maintaining -// Replace rsr-template-repo, CoprocessorRuntime, Julia stdlib only; sibling packages are optional wiring, not hard deps with actuals -= rsr-template-repo — Quick Start for Platform Maintainers += CoprocessorRuntime.jl — Quick Start for Maintainers :toc: :toclevels: 2 == Overview -This guide covers packaging, deploying, and maintaining rsr-template-repo for -distribution on your platform. +CoprocessorRuntime.jl is a Julia library distributed as source from its Git +repository. There is nothing to package or deploy: no binary, no installer, no +container image, and no Guix or OPSM package. Users install it with +`Pkg.add(url=...)`. -== Runtime Dependencies +It is not in the Julia General registry and will not be released there, so +there is no registry release step and no version to register. -Julia stdlib only; sibling packages are optional wiring, not hard deps +== Dependencies -== Build from Source +* Runtime: none. The `[deps]` table in `Project.toml` is empty. +* Optional: `AcceleratorGate` is a weak dependency (compat `0.1`) behind the + package extension `AcceleratorGateExt`. AcceleratorGate is not in General + either, so `test/ext/Project.toml` fetches it by URL from a pinned commit + (`rev`). Moving that pin is a deliberate change: re-run the extension tests + on Julia 1.11 when you do. +* Test: `Test` and `Aqua`, declared under `[extras]`. +* Julia: `julia = "1.10"` is the floor. CI's oldest leg is 1.10, so raising or + lowering the floor means changing `[compat]` and the CI matrix together. -[source,bash] ----- -git clone https://github.com/hyperpolymath/rsr-template-repo.git -cd rsr-template-repo -just build-release ----- +== What CI gates -Output: `src/` +`.github/workflows/julia-ci.yml` runs on pull requests and on pushes to `main` +and `master`: -== Packaging - -=== Guix - -[source,bash] ----- -guix build -f build/guix.scm ----- - -=== Container (Stapeln) - -[source,bash] ----- -just stapeln-export # Generates Containerfile -podman build -t rsr-template-repo . ----- - -=== Manual Package - -[source,bash] ----- -just install --prefix=/usr/local ----- - -Files installed: - -[cols="1,2"] +[cols="1,3"] |=== -| Path | Contents - -| `$PREFIX/bin/` -| Executables +| Job | What it checks -| `$PREFIX/share/CoprocessorRuntime/` -| Data files, assets +| Format (JuliaFormatter) +| `src/`, `test/` and `test/cases/` are formatted. Check mode only; CI never writes. -| `$PREFIX/share/doc/CoprocessorRuntime/` -| Documentation +| Static analysis (JET) +| `JET.test_package(CoprocessorRuntime)`. -| `$PREFIX/share/applications/` -| .desktop file (Linux, if GUI) - -| `$PREFIX/share/man/man1/` -| Man pages +| Test (Test + Aqua) +| `Pkg.test()` on Julia 1.10 and the latest 1.x. The extension tests run only + on 1.11 or later and are reported as `Broken` on 1.10. |=== -== Configuration - -Default config location: `$XDG_CONFIG_HOME/CoprocessorRuntime/config.toml` - -Fallback: `$HOME/.config/CoprocessorRuntime/config.toml` - -== Health Checks - -[source,bash] ----- -just doctor # Full diagnostic -just run --version # Version check -just run --selftest # Built-in self-test ----- - -== Updating - -[source,bash] ----- -git pull -just build-release -just install --prefix=/usr/local ----- - -Or via OPSM: `opsm update CoprocessorRuntime` +The exact commands are in the +link:QUICKSTART-DEV.adoc#_checks_ci_runs[developer quick start]. Other workflows +in `.github/workflows/` are template-wide estate checks. -== Security Notes +== Merging -* License: MPL-2.0 (code) / CC-BY-SA-4.0 (docs) -* All dependencies SHA-pinned -* `panic-attacker` scan results: link:INSTALL-SECURITY-REPORT.adoc[] -* OpenSSF Scorecard: see badge in README +* Every commit must be signed. A ruleset (`.github/rulesets/base.json`) + requires signatures. See link:../../CONTRIBUTING.adoc[CONTRIBUTING] for how. +* Pull requests are squash-merged; that ruleset allows no other method. +* The ruleset's `required_status_checks` list is currently empty, so no + check is enforced by GitHub as required. Do not merge over a red Julia CI + run regardless. +* After a squash-merge, delete the feature branch and start follow-up work from + the current `main`. -== Multi-Instance Deployment +== Releases -For deploying multiple instances (e.g., different users or tenants): +There is no registry release. The repository has a generic `release.yml` that +fires on `v*` tags; it comes from the template and this guide does not cover +it. Record user-visible changes under `[Unreleased]` in `CHANGELOG.adoc`. -[source,bash] ----- -just install --prefix=/opt/CoprocessorRuntime-instance1 --config=/etc/CoprocessorRuntime/instance1.toml -just install --prefix=/opt/CoprocessorRuntime-instance2 --config=/etc/CoprocessorRuntime/instance2.toml ----- +== Security and conduct -Each instance has isolated config, data, and logs. +* Report vulnerabilities as `.github/SECURITY.md` describes. +* Licences: code is MPL-2.0, documentation is CC-BY-SA-4.0 (see `LICENSE` and + the README). Do not change licence headers or files without the owner. -== Reporting Issues +== Reporting issues -* Upstream: https://github.com/hyperpolymath/rsr-template-repo/issues -* With diagnostic: `just help-me` (pre-fills context) +https://github.com/hyperpolymath/CoprocessorRuntime.jl/issues diff --git a/docs/onboarding/QUICKSTART-USER.adoc b/docs/onboarding/QUICKSTART-USER.adoc index 0893e63..9316a1a 100644 --- a/docs/onboarding/QUICKSTART-USER.adoc +++ b/docs/onboarding/QUICKSTART-USER.adoc @@ -1,125 +1,121 @@ // SPDX-License-Identifier: CC-BY-SA-4.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 += CoprocessorRuntime.jl — Quick Start for Users :toc: :toclevels: 2 -== What is rsr-template-repo? +== What is CoprocessorRuntime.jl? -Rsr Template Repo — See README.adoc for details. +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. -== Prerequisites - -Before you begin, ensure you have: - -* **just** — task runner (https://github.com/casey/just[install guide]) -* Platform-specific requirements listed below +It is a Julia library. There is no application to start and no service to run: +you load it with `using CoprocessorRuntime` and call it from your own code. -[cols="1,3"] -|=== -| Platform | Additional Requirements +== What it is not -| Linux -| See README.adoc +* It does not execute CUDA, ROCm, Metal or TPU kernels. That is `CUDA.jl`, + `AMDGPU.jl`, `Metal.jl` or `KernelAbstractions.jl`. +* It does not select a backend. That is `AcceleratorGate.jl`. +* It does not heal a failing kernel. That is `HardwareResilience.jl`. +* It does not prove CNO/OND. That is `absolute-zero`. A claim here has status + `:unproved` or `:model_checked`. +* It does not close K-CUT. That conjecture is open in `choreographic-types`. -| macOS -| See README.adoc +== Prerequisites -| Windows -| See README.adoc -|=== +* Julia 1.10 or later. Continuous integration runs 1.10 and the latest 1.x. +* No other packages. `Project.toml` lists no runtime dependencies. == Install -=== Option 1: Standard Install (recommended) +The package is not in the Julia General registry and is not going to be +released there, so install it from its repository: -[source,bash] +[source,julia] ---- -# Clone and set up -git clone https://github.com/hyperpolymath/rsr-template-repo.git -cd rsr-template-repo -just setup +using Pkg +Pkg.add(url="https://github.com/hyperpolymath/CoprocessorRuntime.jl") ---- -The setup script will: +This installs the `main` branch. -* 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 +== First use -=== Option 2: Container (via Stapeln) +Save this as `first.jl` and run it with `julia --project=. first.jl` from the +environment you installed into: -[source,bash] ----- -just stapeln-run +[source,julia] ---- +using CoprocessorRuntime -=== Option 3: Portable (no system changes) +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"), +) -[source,bash] ----- -just install --portable --prefix=./rsr-template-repo-portable ----- +device_view = project(plan, DeviceRole()) +println("kcut: ", device_view.kcut) -== First Run +receipt = issue_receipt(s; warrant = WarrantOnly, claim = "planned") +println("host may claim: ", host_may_claim(receipt)) -[source,bash] ----- -just run +try + universal_hub_allowed() +catch err + println("refused: ", typeof(err)) +end + +close_session!(s) +println("session open: ", isopen(s)) ---- Expected output: [source] ---- -Rsr Template Repo started successfully. ----- - -== Self-Diagnostic - -If something isn't working: - -[source,bash] ----- -just doctor +kcut: open +host may claim: false +refused: HubCeilingRefusal +session open: false ---- -This checks all dependencies, permissions, paths, and connectivity. -If it finds issues, it will suggest fixes. +What it shows: -To attempt automatic repair: +* `project` gives one endpoint's view of the launch plan. The K-CUT field stays + `:open`: the package does not claim to have closed it. +* A receipt issued with `WarrantOnly` is not factive, so the host may not claim + the launch happened. +* `universal_hub_allowed()` always throws `HubCeilingRefusal`: one adapter + cannot speak every vendor protocol. -[source,bash] ----- -just heal ----- +== Optional: AcceleratorGate -== Get Help +If `AcceleratorGate.jl` is also loaded, the package extension +`AcceleratorGateExt` adds methods of `coprocessor_kind` that map an +AcceleratorGate backend to the `CoprocessorKind` a session is opened against. +It records which kind a backend is; it does not select a backend or check that +a device exists. -* **In-app**: `just run --help` -* **Guided tour**: `just tour` -* **Report a problem**: `just help-me` (pre-fills diagnostic context) -* **Wiki**: https://github.com/hyperpolymath/rsr-template-repo/wiki +== Run the tests -== Uninstall +From a clone of the repository (see the +link:QUICKSTART-DEV.adoc[developer quick start]): [source,bash] ---- -just uninstall +julia --project=. -e 'using Pkg; Pkg.test()' ---- -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 +== Where to read more -* 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 +* link:../../README.adoc[README] — what each part records. +* The docstrings in `src/` — one file per concept (`Kinds.jl`, `Sessions.jl`, + `Grades.jl`, `EchoLoss.jl`, `Receipts.jl`, `Nullity.jl`, `Choreography.jl`). +* link:../theory/TYPE-INFORMED-BACKENDS.adoc[Type-informed backend notes]. +* Problems and questions: https://github.com/hyperpolymath/CoprocessorRuntime.jl/issues diff --git a/docs/onboarding/llm-warmup-dev.adoc b/docs/onboarding/llm-warmup-dev.adoc index f12ada8..76e1d5b 100644 --- a/docs/onboarding/llm-warmup-dev.adoc +++ b/docs/onboarding/llm-warmup-dev.adoc @@ -1,21 +1,43 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -= LLM Warmup — rsr-template-repo (Developer) += LLM Warmup — CoprocessorRuntime.jl (Developer) -== What is rsr-template-repo? +== What is CoprocessorRuntime.jl? -See `README.adoc` for overview. +A Julia library (1.10+), host-side contract and evidence layer for coprocessor +launches. It records launch semantics; it does not run accelerator kernels. Read +`CLAUDE.md` and `CoprocessorRuntime.jl_chora.deed` first; they hold the repo's +identity, IS-NOT list and constraints. -== Key Commands +== Key commands -* `just setup` — set up development environment -* `just build` — build the project -* `just test` — run tests -* `just doctor` — diagnose issues -* `just heal` — attempt auto-repair +[source,bash] +---- +julia --project=. -e 'using Pkg; Pkg.instantiate()' +julia --project=. -e 'using Pkg; Pkg.test()' # Test + Aqua + extension tests +---- -== Quick Context +JET and JuliaFormatter commands are in link:QUICKSTART-DEV.adoc[QUICKSTART-DEV]. +In the root `Justfile`, `just test`, `build`, `run`, `lint` and `fmt` are +template placeholders (`just test` fails on purpose). Do not use them. -* License: MPL-2.0 -* Part of hyperpolymath ecosystem -* See `EXPLAINME.adoc` for architecture +== Layout + +* `src/` — the package: `Kinds.jl`, `Sessions.jl`, `Grades.jl`, `EchoLoss.jl`, + `Receipts.jl`, `Nullity.jl`, `Choreography.jl`, loaded by `CoprocessorRuntime.jl`. + The other directories under `src/` are not loaded by the module. +* `ext/AcceleratorGateExt.jl` — weak-dependency extension; its tests need Julia 1.11. +* `test/` — `runtests.jl`, `cases/`, `ext/`. + +== Rules that matter + +* Do not claim more than the code records: receipts, CNO and OND claims are + claims, not proofs; K-CUT stays `:open`; there is no universal hub. +* Never add a `.a2ml` file; no TypeScript, ReScript, Python, Go or Nix. +* No automated licence edits. Sign every commit. +* The package is not released to the Julia General registry. + +== Quick context + +* Licence: MPL-2.0 (code), CC-BY-SA-4.0 (docs). +* Part of the hyperpolymath ecosystem. Overview: link:../../README.adoc[README]. diff --git a/docs/onboarding/llm-warmup-user.adoc b/docs/onboarding/llm-warmup-user.adoc index 2127530..8448784 100644 --- a/docs/onboarding/llm-warmup-user.adoc +++ b/docs/onboarding/llm-warmup-user.adoc @@ -1,21 +1,40 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -= LLM Warmup — rsr-template-repo (User) += LLM Warmup — CoprocessorRuntime.jl (User) -== What is rsr-template-repo? +== What is CoprocessorRuntime.jl? -See `README.adoc` for overview. +A Julia library: 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. -== Key Commands +== How a user gets and uses it -* `just setup` — set up development environment -* `just build` — build the project -* `just test` — run tests -* `just doctor` — diagnose issues -* `just heal` — attempt auto-repair +* Julia 1.10 or later. No runtime dependencies. +* Install: `Pkg.add(url="https://github.com/hyperpolymath/CoprocessorRuntime.jl")`. + It is not in the Julia General registry and will not be released there. Do + not suggest `Pkg.add("CoprocessorRuntime")`. +* Use: `using CoprocessorRuntime`. There is no application, service, CLI or + container to run. +* Worked example and expected output: link:QUICKSTART-USER.adoc[QUICKSTART-USER]. -== Quick Context +== What it is not -* License: MPL-2.0 -* Part of hyperpolymath ecosystem -* See `EXPLAINME.adoc` for architecture +Do not describe it as any of these: + +* an executor of CUDA, ROCm, Metal or TPU kernels (that is `CUDA.jl`, + `AMDGPU.jl`, `Metal.jl`, `KernelAbstractions.jl`) +* a backend selector (`AcceleratorGate.jl`) +* a healer of failing kernels (`HardwareResilience.jl`) +* a proof of CNO/OND (`absolute-zero`); claims here are `:unproved` or + `:model_checked` +* a closure of K-CUT; that conjecture is open in `choreographic-types` + +`universal_hub_allowed()` throws `HubCeilingRefusal`: there is no universal +adapter. + +== Quick context + +* Licence: MPL-2.0 for code, CC-BY-SA-4.0 for documentation. +* Part of the hyperpolymath ecosystem. Overview: link:../../README.adoc[README]. diff --git a/scripts/deed-field.sh b/scripts/deed-field.sh new file mode 100755 index 0000000..914b560 --- /dev/null +++ b/scripts/deed-field.sh @@ -0,0 +1,221 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# deed-field.sh — read one field out of a deed (_chora.deed, or any +# *_praxis.deed: the root is the first form with an ABNF doc-head). +# +# The repo deed holds what the descriptiles CLADE / META / ECOSYSTEM / STATE / +# AGENTIC .a2ml files used to hold (rsr-template-repo#209). This is the one +# shell reader for it, so that every gate, extractor and recipe asks the same +# question the same way. It is a READER: it never writes the deed. +# +# Usage: +# deed-field.sh DEED PATH KEY first value of :KEY in the clause at PATH +# deed-field.sh --list DEED PATH KEY the items of the list :KEY ( … ), one per line +# deed-field.sh --clause DEED PATH the clause, one token per line (for hashing) +# deed-field.sh --has DEED PATH exit 0 iff the clause exists +# deed-field.sh --find [DIR] print the one *_chora.deed in DIR (default .) +# deed-field.sh --uuid DEED the repo uuid: the body of :repo-uuid #uuid"…" as +# written (#u8 is derived; a #u5 is derived only to +# read an old deed, and check-identity.sh refuses it) +# deed-field.sh --typed DEED PATH KEY like the first form, but a tagged literal keeps its +# tag and quotes: #u5"github.com/o/r" (a plain value +# prints as it does without --typed) +# +# PATH names clauses below (repo-deed …), slash-separated: `status`, +# `agentic/integrity`, `meta/maintenance-axes`. An empty PATH is (repo-deed …) +# itself, so `deed-field.sh DEED "" canonical-name` reads the header. +# +# KEY is matched only at the top level of that clause, never inside a nested +# clause: `status` :phase is the clause's own phase, not a (history (entry …)) +# phase. Comments (`;` to end of line, outside strings) are ignored, layout is +# irrelevant, string escapes \" \\ \n \t are decoded, and the booleans #t / #f +# print as true / false, because every caller is a shell test. A tagged +# literal prints its string: `:repo-uuid #u5"github.com/o/r"` gives +# github.com/o/r, the uuid5 name (uuidgen --sha1 --namespace @url --name …). +# +# --uuid prints the repo id. The chora id is minted once and carried opaquely +# as `:repo-uuid #uuid""` (standards A1 V8, A7 J11), so +# for that form it prints the body as written and NEVER re-derives it: a +# transfer or rename does not change the id (ruling U1). Legacy literals are +# still read, with a note on stderr: #u5"NAME" gives the uuid5 (RFC 9562, URL +# namespace) of NAME, through uuidgen with --sha1, else scripts/uuid5-url.sh, +# else bun; #u8"DOMAIN:NAME" gives the profile C id through scripts/uuid-v8.sh. +# It exits 2 when no tool is available or the result is not uuid-shaped: it +# never guesses. +# +# Exit: 0 found; 1 clause or key absent (nothing printed); 2 usage error or no +# readable deed. --find exits 1 unless exactly one deed is present. +set -euo pipefail + +mode=value +case "${1:-}" in + --list|--clause|--has|--uuid|--typed) mode="${1#--}"; shift ;; + --find) + shopt -s nullglob + deeds=("${2:-.}"/*_chora.deed) + [ "${#deeds[@]}" -eq 1 ] || exit 1 + printf '%s\n' "${deeds[0]}" + exit 0 ;; +esac + +deed="${1:-}"; path="${2-}"; key="${3:-}" +[ "$mode" != uuid ] || { path=""; key=repo-uuid; } +if [ -z "$deed" ] || [ ! -r "$deed" ]; then + echo "deed-field.sh: no readable deed: '${deed}'" >&2; exit 2 +fi +if [[ ( "$mode" = value || "$mode" = typed || "$mode" = list ) && -z "$key" ]]; then + echo "deed-field.sh: KEY is required" >&2; exit 2 +fi + +# read_deed MODE -> run the clause reader over $deed for $path / $key +read_deed() { +awk -v mode="$1" -v path="$path" -v key="$key" ' +BEGIN { RS = "\001" } +{ + # Tokenise: "(" ")" , S , A. Comments are dropped here. + s = $0; n = length(s); i = 1; nt = 0 + while (i <= n) { + c = substr(s, i, 1) + if (c == ";") { while (i <= n && substr(s, i, 1) != "\n") i++; continue } + if (c == "(" || c == ")") { tok[++nt] = c; i++; continue } + if (c == "\"") { + v = ""; i++ + while (i <= n) { + c = substr(s, i, 1) + if (c == "\\") { + d = substr(s, i + 1, 1) + if (d == "n") v = v "\n"; else if (d == "t") v = v "\t"; else v = v d + i += 2; continue + } + if (c == "\"") break + v = v c; i++ + } + i++; tok[++nt] = "S" v; continue + } + if (c == " " || c == "\t" || c == "\r" || c == "\n") { i++; continue } + v = "" + while (i <= n) { + c = substr(s, i, 1) + if (c == " " || c == "\t" || c == "\r" || c == "\n" || c == "(" || c == ")" || c == "\"" || c == ";") break + v = v c; i++ + } + tok[++nt] = "A" v + } +} +# Index of the ")" token that closes the clause opening at token o, or 0. +function close_of(o, d, t) { + d = 0 + for (t = o; t <= nt; t++) { + if (tok[t] == "(") d++ + else if (tok[t] == ")") { d--; if (d == 0) return t } + } + return 0 +} +# First direct child clause of the clause opening at o whose head is name. +function child(o, name, e, t, d) { + e = close_of(o); d = 0 + for (t = o + 1; t < e; t++) { + if (tok[t] == "(") { if (d == 0 && tok[t + 1] == "A" name) return t; d++ } + else if (tok[t] == ")") d-- + } + return 0 +} +# A value token rendered for output: the type tag dropped, #t/#f as true/false. +function show(x) { + x = substr(x, 2) + if (x == "#t") return "true" + if (x == "#f") return "false" + return x +} +END { + o = 0 + for (t = 1; t <= nt; t++) + if (tok[t] == "(" && tok[t + 1] ~ /^A(repo-deed|praxis-deed|estate-deed|estate-atlas-deed)$/) { o = t; break } + if (!o) exit 1 + if (path != "") { + np = split(path, part, "/") + for (p = 1; p <= np; p++) { o = child(o, part[p]); if (!o) exit 1 } + } + e = close_of(o) + if (!e) exit 2 + if (mode == "has") exit 0 + if (mode == "clause") { for (t = o; t <= e; t++) print tok[t]; exit 0 } + d = 0 + for (t = o + 1; t < e; t++) { + if (tok[t] == "(") { d++; continue } + if (tok[t] == ")") { d--; continue } + if (d != 0 || tok[t] != "A:" key) continue + nx = tok[t + 1] + if (mode == "value" || mode == "typed") { + if (nx == "(" || nx == ")" || nx == "") exit 1 + # A tagged literal such as #u5"github.com/o/r" prints its string. + if (nx ~ /^A#[a-z0-9]+$/ && substr(tok[t + 2], 1, 1) == "S") { + if (mode == "typed") { print substr(nx, 2) "\"" substr(tok[t + 2], 2) "\""; exit 0 } + nx = tok[t + 2] + } + print show(nx); exit 0 + } + if (nx != "(") exit 1 + le = close_of(t + 1); ld = 0 + for (u = t + 2; u < le; u++) { + if (tok[u] == "(") ld++ + else if (tok[u] == ")") ld-- + else if (ld == 0) print show(tok[u]) + } + exit 0 + } + exit 1 +} +' "$deed" +} + +# uuid5_url NAME -> the uuid5 of NAME in the RFC 9562 URL namespace +uuid5_url() { + if uuidgen --sha1 --namespace @url --name x >/dev/null 2>&1; then + uuidgen --sha1 --namespace @url --name "$1" + elif [ -f "$(dirname "${BASH_SOURCE[0]}")/uuid5-url.sh" ] && bash "$(dirname "${BASH_SOURCE[0]}")/uuid5-url.sh" x >/dev/null 2>&1; then + # The same derivation repo-init mints with (sha1sum, shasum or openssl). + bash "$(dirname "${BASH_SOURCE[0]}")/uuid5-url.sh" "$1" + elif command -v bun >/dev/null 2>&1; then + bun -e ' + const h = new Bun.CryptoHasher("sha1"); + h.update(Buffer.from("6ba7b8119dad11d180b400c04fd430c8", "hex")); + h.update(process.argv[1]); + const b = h.digest().subarray(0, 16); + b[6] = (b[6] & 0x0f) | 0x50; + b[8] = (b[8] & 0x3f) | 0x80; + const x = b.toString("hex"); + console.log([x.slice(0, 8), x.slice(8, 12), x.slice(12, 16), x.slice(16, 20), x.slice(20)].join("-")); + ' "$1" + else + echo "deed-field.sh: --uuid needs uuidgen with --sha1, sha1sum, shasum, openssl, or bun" >&2; return 2 + fi +} + +if [ "$mode" = uuid ]; then + lit="$(read_deed typed)" || exit $? + re_uuid='^[0-9a-f]{8}-[0-9a-f]{4}-[58][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$' + case "$lit" in + '#uuid"'*'"') + # The chora id, minted once: print it as written, never re-derive it. + id="${lit#\#uuid\"}"; id="${id%\"}" ;; + '#u5"'*'"') + name="${lit#\#u5\"}"; name="${name%\"}" + # Read only so an old deed can still be looked up: a #u5 in an identity + # field is u5-identity, an error in every mode (A1 v0.4.5 T30, Q2), and + # scripts/check-identity.sh refuses it. + echo "deed-field.sh: :repo-uuid is a #u5 literal, an error under A1 T30 (Q2); derived here only to read an old deed. Write #uuid\"\"." >&2 + id="$(uuid5_url "$name")" || exit 2 ;; + '#u8"'*:*'"') + body="${lit#\#u8\"}"; body="${body%\"}" + id="$(bash "$(dirname "${BASH_SOURCE[0]}")/uuid-v8.sh" "${body%%:*}" "${body#*:}")" || exit 2 ;; + *) echo "deed-field.sh: :repo-uuid is not a #uuid, #u5 or #u8 literal: '$lit'" >&2; exit 2 ;; + esac + [[ "$id" =~ $re_uuid ]] \ + || { echo "deed-field.sh: :repo-uuid is not a lowercase v5 or v8 uuid: '$id'" >&2; exit 2; } + printf '%s\n' "$id" + exit 0 +fi +read_deed "$mode" diff --git a/scripts/uuid-v8.sh b/scripts/uuid-v8.sh new file mode 100755 index 0000000..e6df425 --- /dev/null +++ b/scripts/uuid-v8.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# +# uuid-v8.sh DOMAIN NAME — the ADR-008 profile C UUIDv8 of NAME in DOMAIN, +# the same on every machine and equal to standards `scripts/uuid-v8.js c`: +# the first 16 bytes of SHA-256(DOMAIN ":" NAME), the version nibble set to 8 +# and the variant to 10xx. A repo's chora id is the profile C id of its birth +# path in the domain chora-registry (standards A1 rules V8 and V9, A7 J11); an +# id minted before V9 keeps its gv-clade-index id and is never reminted. +# SHA-256 comes from sha256sum, shasum or openssl, whichever is installed first. +# +# Exit: 0 printed; 2 usage, a DOMAIN that is empty or holds ":", or no +# SHA-256 tool (it never guesses). +set -euo pipefail +[ $# -eq 2 ] || { echo "usage: uuid-v8.sh DOMAIN NAME" >&2; exit 2; } +[[ "$1" =~ ^[!-9\;-~]+$ ]] \ + || { echo "uuid-v8.sh: DOMAIN must be non-empty printable ASCII without ':'" >&2; exit 2; } + +sha256() { + if command -v sha256sum >/dev/null 2>&1; then sha256sum + elif command -v shasum >/dev/null 2>&1; then shasum -a 256 + elif command -v openssl >/dev/null 2>&1; then openssl dgst -sha256 -r + else echo "uuid-v8.sh: needs sha256sum, shasum or openssl" >&2; return 2 + fi +} +h="$(printf '%s:%s' "$1" "$2" | sha256)" || exit 2 +[[ "$h" =~ ^[0-9a-f]{64} ]] || { echo "uuid-v8.sh: the SHA-256 tool printed '$h'" >&2; exit 2; } +printf '%s-%s-8%s-%x%s-%s\n' "${h:0:8}" "${h:8:4}" "${h:13:3}" \ + $(( (16#${h:16:1} & 3) | 8 )) "${h:17:3}" "${h:20:12}"