Skip to content
Merged
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ erl_crash.dump
*.jl.cov
*.jl.mem
/Manifest.toml
/test/ext/Manifest.toml

#
/lib/bs/
Expand Down
1 change: 1 addition & 0 deletions .machine_readable/root-allow.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 11 additions & 4 deletions CHANGELOG.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 17 additions & 3 deletions Project.toml
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,31 @@
# 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 <j.d.a.jewell@open.ac.uk>"]
license = "MPL-2.0"
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"
Expand All @@ -23,5 +36,6 @@ test = ["Test", "Aqua"]

[compat]
julia = "1.10"
AcceleratorGate = "0.1"
Test = "1.9"
Aqua = "0.8"
38 changes: 29 additions & 9 deletions docs/ecosystem/HYPERPOLYMATH-WIRING.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]`:
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down
77 changes: 77 additions & 0 deletions ext/AcceleratorGateExt.jl
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# SPDX-License-Identifier: MPL-2.0
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

"""
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
3 changes: 2 additions & 1 deletion src/CoprocessorRuntime.jl
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,8 @@ export Role,
projected_grade,
universal_hub_allowed,
HubCeilingRefusal,
kind_label
kind_label,
coprocessor_kind

include("Kinds.jl")
include("Grades.jl")
Expand Down
15 changes: 15 additions & 0 deletions src/Kinds.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
17 changes: 17 additions & 0 deletions test/ext/Project.toml
Original file line number Diff line number Diff line change
@@ -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"
64 changes: 64 additions & 0 deletions test/ext/runtests.jl
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# SPDX-License-Identifier: MPL-2.0
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

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
31 changes: 31 additions & 0 deletions test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading