diff --git a/.gitignore b/.gitignore index afbe851..6ac87cc 100644 --- a/.gitignore +++ b/.gitignore @@ -39,6 +39,7 @@ erl_crash.dump *.jl.cov *.jl.mem /Manifest.toml +/test/ext/Manifest.toml # /lib/bs/ diff --git a/.machine_readable/root-allow.txt b/.machine_readable/root-allow.txt index 909f7b0..c0d7772 100644 --- a/.machine_readable/root-allow.txt +++ b/.machine_readable/root-allow.txt @@ -76,6 +76,7 @@ test/ # Pkg.test() in Julia runs test/runtests.jl; Pkg look ?sonar-project.properties # only where the repo is analysed by SonarCloud ?benches/ # Cargo-conventional at package root ?examples/ # Cargo-conventional at package root +?ext/ # Julia package extensions: Julia loads an [extensions] entry from ext/ at the package root, so it cannot move; present only where Project.toml declares one ?features/ # optional feature packs ?verification/ # proofs; only where formal-proofs is declared ?CONTRIBUTING.md # accepted at root OR .github/; .github/ is the canonical estate location diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index cebca7c..8d016f3 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -10,10 +10,17 @@ https://semver.org/spec/v2.0.0.html[Semantic Versioning]. ==== Added -* Julia package `CoprocessorRuntime` (uuid - `54e4c7d3-acab-5c3f-ab09-6ee0d181492b`): session contracts, tropical - resource grades, echo residues, epistemic receipts, CNO/OND claims, - choreographic projection with `kcut = :open`, and `HubCeilingRefusal`. +* Julia package `CoprocessorRuntime` (uuid in `Project.toml`): session + contracts, tropical resource grades, echo residues, epistemic receipts, + CNO/OND claims, choreographic projection with `kcut = :open`, and + `HubCeilingRefusal`. +* Package extension `AcceleratorGateExt` and `coprocessor_kind`: maps an + AcceleratorGate.jl `AbstractBackend` onto the `CoprocessorKind` a session + is opened against. `PPUBackend`, `MathBackend`, `VPUBackend` and + `CryptoBackend` map to `UnknownKind` because there is no kind for them + here. AcceleratorGate stays a weak dependency (`[weakdeps]`, compat + `0.1`). The extension is tested in `test/ext` against a pinned + AcceleratorGate commit, which needs Julia 1.11 (Broken on older Julia). * `docs/theory/TYPE-INFORMED-BACKENDS.adoc` — what was taken from the `-type` repos and what was deliberately not forced. * `docs/ecosystem/HYPERPOLYMATH-WIRING.adoc` — exact sibling-repo patches diff --git a/Project.toml b/Project.toml index b6c2882..2658b92 100644 --- a/Project.toml +++ b/Project.toml @@ -2,11 +2,18 @@ # minted by: arena/01a0de6b-coprocessorruntime-jl (2026) # owner: hyperpolymath # -# uuid is UUIDv5(repo-uuid, "julia:CoprocessorRuntime.jl") where -# repo-uuid = UUIDv5(URL namespace, "github.com/hyperpolymath/CoprocessorRuntime.jl") +# uuid below is the UUIDv8 re-mint of the package identity (ADR-008 +# amendment D320: an unregistered Julia package's own uuid re-mints as +# version 8). It is profile C, domain julia-package-identity, name +# github.com/hyperpolymath/CoprocessorRuntime.jl, so it is reproducible: +# bun scripts/uuid-v8.js c julia-package-identity github.com/hyperpolymath/CoprocessorRuntime.jl +# (standards' scripts/uuid-v8.js), minted 2026-11-14 on an explicit owner +# ruling for this one id. It supersedes the mint-time UUIDv5 literal (in git +# history; not spelled out here because the strict UUIDv8 scanner reads every +# hyphenated literal, comments included). name = "CoprocessorRuntime" -uuid = "54e4c7d3-acab-5c3f-ab09-6ee0d181492b" +uuid = "30bdb74d-6d6a-8e6d-a17e-2d6824776af8" description = "Coprocessor support base library for Julia — session contracts, tropical grades, echo residues, epistemic receipts, CNO/OND claims. Not a kernel runtime." authors = ["Jonathan D.A. Jewell "] license = "MPL-2.0" @@ -14,6 +21,12 @@ version = "0.1.0" [deps] +[weakdeps] +AcceleratorGate = "59f742c7-270d-4a76-95d4-a853ae16cc71" + +[extensions] +AcceleratorGateExt = "AcceleratorGate" + [extras] Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595" Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" @@ -23,5 +36,6 @@ test = ["Test", "Aqua"] [compat] julia = "1.10" +AcceleratorGate = "0.1" Test = "1.9" Aqua = "0.8" diff --git a/docs/ecosystem/HYPERPOLYMATH-WIRING.adoc b/docs/ecosystem/HYPERPOLYMATH-WIRING.adoc index 35a4ff3..6c267e3 100644 --- a/docs/ecosystem/HYPERPOLYMATH-WIRING.adoc +++ b/docs/ecosystem/HYPERPOLYMATH-WIRING.adoc @@ -12,15 +12,23 @@ Hyperpolymath.jl is the metapackage. It already re-exports the metal layer (`LowLevel`, `SiliconCore`, `AcceleratorGate`, `QuantumCircuit`, `HardwareResilience`, `FirmwareAudit`) and does **not** yet name this package. -Generate a fresh UUID-compat line using this package's published uuid -`54e4c7d3-acab-5c3f-ab09-6ee0d181492b`. +Generate a fresh UUID-compat line using this package's uuid +`30bdb74d-6d6a-8e6d-a17e-2d6824776af8`. It is the UUIDv8 re-mint of the +package identity (ADR-008 amendment D320), profile C, domain +`julia-package-identity`, name +`github.com/hyperpolymath/CoprocessorRuntime.jl`, so it can be recomputed with +`bun scripts/uuid-v8.js c julia-package-identity github.com/hyperpolymath/CoprocessorRuntime.jl` +in standards. The mint-time UUIDv5 is in git history. A new uuid is a different +package to a Julia registry; this package is not in General (checked +2026-11-14), and a code search of the default branches visible that day found +no consumer of the old id. The patches below were never applied. === `Project.toml` Add to `[deps]`: ---- -CoprocessorRuntime = "54e4c7d3-acab-5c3f-ab09-6ee0d181492b" +CoprocessorRuntime = "30bdb74d-6d6a-8e6d-a17e-2d6824776af8" ---- Add to `[compat]`: @@ -69,13 +77,15 @@ FirmwareAudit.jl — firmware attestation as an epistemic warrant source == AcceleratorGate.jl -No hard dependency either way. Optional later: a package extension -`AcceleratorGateExt` in *this* repo mapping `AbstractBackend` → -`CoprocessorKind`. Not in v0.1: AcceleratorGate backends are env-flag -stubs, and a forced extension would look like integration that is not -there. +No hard dependency either way. The package extension `AcceleratorGateExt` +(`ext/AcceleratorGateExt.jl`, in *this* repo, loaded when both packages are) +adds the methods of `coprocessor_kind`, mapping `AbstractBackend` → +`CoprocessorKind`, so a session can be opened against the kind a backend +selection produced. AcceleratorGate backends are env-flag selections, so the +mapping records a *kind*; it does not detect a device or run anything. -Suggested mapping when the extension is written: +The mapping, which `test/ext/runtests.jl` states a second time and checks +against every `AbstractBackend` subtype: ---- JuliaBackend / RustBackend / ZigBackend → CPUKind @@ -85,8 +95,18 @@ NPUBackend → NPUKind FPGABackend → FPGAKind QPUBackend → QPUKind DSPBackend → DSPKind +PPUBackend / MathBackend / VPUBackend / CryptoBackend → UnknownKind ---- +The last row is a decision: CoprocessorRuntime has no kind for those four +backends, and adding one is an API change here, not a guess in the extension. +A backend AcceleratorGate adds later makes the extension's test fail until it +is given a row. + +AcceleratorGate is not in the General registry, so the extension's tests fetch +it by URL from a pinned commit (`test/ext/Project.toml`, `[sources]`), which +needs Julia 1.11. On older Julia the test is recorded as Broken, not dropped. + == EchoTypes.jl / EpistemicTypes.jl Optional, not required. diff --git a/ext/AcceleratorGateExt.jl b/ext/AcceleratorGateExt.jl new file mode 100644 index 0000000..a808655 --- /dev/null +++ b/ext/AcceleratorGateExt.jl @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +""" + AcceleratorGateExt + +Package extension: maps an AcceleratorGate.jl `AbstractBackend` onto the +`CoprocessorKind` a CoprocessorRuntime session is opened against. + +It records which *kind* a backend is. It does not select a backend, check that +a device exists, or run anything: AcceleratorGate's backends are env-flag +selections, and this mapping claims no more than that. + +Four AcceleratorGate backends have no kind in CoprocessorRuntime and map to +`UnknownKind`: `PPUBackend`, `MathBackend`, `VPUBackend`, `CryptoBackend`. +Adding a kind for one of them is an API change to CoprocessorRuntime, not a +guess to make here. +""" +module AcceleratorGateExt + +import CoprocessorRuntime: + coprocessor_kind, + CPUKind, + GPUKind, + NPUKind, + TPUKind, + FPGAKind, + QPUKind, + DSPKind, + UnknownKind +import AcceleratorGate: + AbstractBackend, + JuliaBackend, + RustBackend, + ZigBackend, + CUDABackend, + ROCmBackend, + MetalBackend, + TPUBackend, + NPUBackend, + DSPBackend, + FPGABackend, + QPUBackend, + PPUBackend, + MathBackend, + VPUBackend, + CryptoBackend + +# Host-language implementations run on the CPU. +coprocessor_kind(::JuliaBackend) = CPUKind() +coprocessor_kind(::RustBackend) = CPUKind() +coprocessor_kind(::ZigBackend) = CPUKind() + +# GPU vendors. +coprocessor_kind(::CUDABackend) = GPUKind() +coprocessor_kind(::ROCmBackend) = GPUKind() +coprocessor_kind(::MetalBackend) = GPUKind() + +# Coprocessor families CoprocessorRuntime has a kind for. +coprocessor_kind(::TPUBackend) = TPUKind() +coprocessor_kind(::NPUBackend) = NPUKind() +coprocessor_kind(::FPGABackend) = FPGAKind() +coprocessor_kind(::QPUBackend) = QPUKind() +coprocessor_kind(::DSPBackend) = DSPKind() + +# Coprocessor families CoprocessorRuntime has no kind for: named, not guessed. +coprocessor_kind(::PPUBackend) = UnknownKind() +coprocessor_kind(::MathBackend) = UnknownKind() +coprocessor_kind(::VPUBackend) = UnknownKind() +coprocessor_kind(::CryptoBackend) = UnknownKind() + +# A backend type AcceleratorGate adds later: total, and honest about it. The +# extension's tests fail when a backend subtype is missing from the table +# above, so a new backend gets a mapping decision instead of this default. +coprocessor_kind(::AbstractBackend) = UnknownKind() + +end # module AcceleratorGateExt diff --git a/src/CoprocessorRuntime.jl b/src/CoprocessorRuntime.jl index 077b59c..e808ac2 100644 --- a/src/CoprocessorRuntime.jl +++ b/src/CoprocessorRuntime.jl @@ -83,7 +83,8 @@ export Role, projected_grade, universal_hub_allowed, HubCeilingRefusal, - kind_label + kind_label, + coprocessor_kind include("Kinds.jl") include("Grades.jl") diff --git a/src/Kinds.jl b/src/Kinds.jl index 47af34d..71284d7 100644 --- a/src/Kinds.jl +++ b/src/Kinds.jl @@ -37,3 +37,18 @@ kind_label(::QPUKind) = :qpu kind_label(::DSPKind) = :dsp kind_label(::UnknownKind) = :unknown kind_label(::CoprocessorKind) = :unknown + +""" + coprocessor_kind(backend) -> CoprocessorKind + +The [`CoprocessorKind`](@ref) that an AcceleratorGate.jl `AbstractBackend` +names, so a session can be opened against the kind a backend selection +produced: `open_session(coprocessor_kind(backend))`. + +This function has no methods until AcceleratorGate.jl is loaded. The methods +live in the package extension `AcceleratorGateExt`, so CoprocessorRuntime keeps +no hard dependency on AcceleratorGate (selection stays there; this package only +records what a launch may claim). Calling it without AcceleratorGate loaded is +a `MethodError` on purpose, never a silent default. +""" +function coprocessor_kind end diff --git a/test/ext/Project.toml b/test/ext/Project.toml new file mode 100644 index 0000000..b3a8b45 --- /dev/null +++ b/test/ext/Project.toml @@ -0,0 +1,17 @@ +# SPDX-License-Identifier: MPL-2.0 +# Test environment for the AcceleratorGateExt package extension. AcceleratorGate +# is not in the General registry, so it is fetched by URL from a pinned commit +# through [sources], which needs Julia 1.11. test/runtests.jl runs this +# environment in a subprocess and records a visible Broken test on older Julia. +[deps] +AcceleratorGate = "59f742c7-270d-4a76-95d4-a853ae16cc71" +CoprocessorRuntime = "30bdb74d-6d6a-8e6d-a17e-2d6824776af8" +InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240" +Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" + +[sources] +AcceleratorGate = {url = "https://github.com/hyperpolymath/AcceleratorGate.jl", rev = "9b8919326ef3b7cd31424e24041325cc3689b182"} +CoprocessorRuntime = {path = "../.."} + +[compat] +julia = "1.11" diff --git a/test/ext/runtests.jl b/test/ext/runtests.jl new file mode 100644 index 0000000..33778ca --- /dev/null +++ b/test/ext/runtests.jl @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +using Test +using InteractiveUtils: subtypes +using CoprocessorRuntime +using AcceleratorGate + +# The mapping the extension must implement. It is written out here, in full, so +# the test is a second statement of the table and not a restatement of the code. +const EXPECTED = Dict{DataType,DataType}( + JuliaBackend => CPUKind, + RustBackend => CPUKind, + ZigBackend => CPUKind, + CUDABackend => GPUKind, + ROCmBackend => GPUKind, + MetalBackend => GPUKind, + TPUBackend => TPUKind, + NPUBackend => NPUKind, + FPGABackend => FPGAKind, + QPUBackend => QPUKind, + DSPBackend => DSPKind, + PPUBackend => UnknownKind, + MathBackend => UnknownKind, + VPUBackend => UnknownKind, + CryptoBackend => UnknownKind, +) + +# Backends take no argument, a library path, or a device number. +make(::Type{JuliaBackend}) = JuliaBackend() +make(T::Type{<:Union{RustBackend,ZigBackend}}) = T("") +make(T::Type{<:AbstractBackend}) = T(0) + +@testset "AcceleratorGateExt" begin + @testset "the extension is loaded" begin + @test Base.get_extension(CoprocessorRuntime, :AcceleratorGateExt) !== nothing + @test hasmethod(coprocessor_kind, Tuple{JuliaBackend}) + end + + @testset "the table covers every AcceleratorGate backend" begin + # A backend AcceleratorGate adds later must get a mapping decision here, + # not fall through to the extension's UnknownKind default unseen. + @test Set(subtypes(AbstractBackend)) == Set(keys(EXPECTED)) + end + + @testset "each backend maps to its kind" begin + for (backend, kind) in EXPECTED + @test coprocessor_kind(make(backend)) isa kind + end + end + + @testset "kinds the runtime does not model are Unknown, not guessed" begin + for T in (PPUBackend, MathBackend, VPUBackend, CryptoBackend) + @test kind_label(coprocessor_kind(make(T))) === :unknown + end + end + + @testset "a mapped kind opens a session" begin + s = open_session(coprocessor_kind(CUDABackend(0))) + @test isopen(s) + close_session!(s) + @test !isopen(s) + end +end diff --git a/test/runtests.jl b/test/runtests.jl index a418e76..40903ec 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -14,4 +14,35 @@ using CoprocessorRuntime include(joinpath(@__DIR__, "cases", "sessions.jl")) include(joinpath(@__DIR__, "cases", "receipts.jl")) include(joinpath(@__DIR__, "cases", "choreography.jl")) + + # AcceleratorGate is not in General, so the extension is tested in its own + # environment (test/ext) that fetches it by URL through [sources], which + # needs Julia 1.11. It runs in a subprocess so the main test environment + # stays resolvable on older Julia. A run that cannot happen is recorded as + # a visible Broken test, never dropped silently. + @testset "AcceleratorGateExt" begin + ext_dir = joinpath(@__DIR__, "ext") + if get(ENV, "COPROCESSORRUNTIME_SKIP_EXT_TESTS", "") == "1" + @info "AcceleratorGateExt tests skipped: COPROCESSORRUNTIME_SKIP_EXT_TESTS=1" + @test_skip false + elseif VERSION < v"1.11" + @info "AcceleratorGateExt tests need Julia 1.11 ([sources]); running Julia $VERSION" + @test_skip false + else + # The directory is passed as an argument and read from ARGS, never + # spliced into the generated source: a path with a backslash (any + # Windows path), a quote or a `$` is not valid inside a string literal. + script = "import Pkg; Pkg.instantiate(); include(joinpath(ARGS[1], \"runtests.jl\"))" + cmd = `$(Base.julia_cmd()) --startup-file=no --project=$ext_dir -e $script $ext_dir` + # Pkg.test sets JULIA_LOAD_PATH for the sandbox it makes; the + # subprocess must resolve its own environment, not inherit that one. + @test success( + pipeline( + addenv(cmd, "JULIA_LOAD_PATH" => nothing); + stdout = stdout, + stderr = stderr, + ), + ) + end + end end