Skip to content

feat(accel): exclusive capabilities, an open accel grammar, and the deprecated environment key removed from the manual - #562

Merged
Sunrisepeak merged 1 commit into
mainfrom
feat/multi-device
Sep 5, 2026
Merged

feat(accel): exclusive capabilities, an open accel grammar, and the deprecated environment key removed from the manual#562
Sunrisepeak merged 1 commit into
mainfrom
feat/multi-device

Conversation

@Sunrisepeak

Copy link
Copy Markdown
Member

Three things from the multi-device design
(.agents/docs/2026-09-05-multi-device-ecosystem-design.md).

1. [package] exclusive — closing the same-symbol case

Two packages providing one capability is usually fine and sometimes the point:
an OpenBLAS package and an MKL package both provide blas, and a build that
links one program against each is legitimate. The manual says so.

What is not fine is two implementations of one accelerator interface in one
link — they define the same symbols, and the link resolves every call to
whichever archive it reached first. The manual documents that failure too, with
a measured multiple definition of 'cap_probe'.

The engine cannot tell those apart: seeing the symbol overlap needs object files
that do not exist when capabilities are bound. So the package says it.

provides  = ["gpu-blas"]
exclusive = ["gpu-blas"]
error: capability 'gpu-blas' is provided by more than one package, and they
       declare it EXCLUSIVE.
         providers: [gpublas-a, gpublas-b]
         exclusive: [gpublas-a, gpublas-b]
       Two implementations of one interface define the same symbols, so the
       link would resolve every call to whichever archive it reached first.
       Keep one of them — a `[capabilities]` pin selects a provider for a
       REQUIREMENT and cannot make two definitions of one symbol safe.

Reported as exclusive-capability in --format json. A capability nobody
declares exclusive behaves exactly as before.

A list rather than a flag, because a package may provide several capabilities
and be the sole provider of only some. An entry naming a capability the package
does not supply is a schema warning — exclusivity is a claim about this
package's own symbols, and a silent no-op is how a typo survives.

2. The accel grammar is open

The backend set was never closed, but the floor had only CUDA's spelling.
floor>= is now accepted alongside ptx>= for the same field.

vulkan1.3+{spirv1.6} floor>=1.4
sycl2020+{spir64,nvptx64-sm_89}
hip6.4+{gfx942}

An architecture carrying no leading number — gfx942 — is compared by
equality, because there is no ordering to read out of it. Reading 942 out of
the middle would invent a level AMD does not define.

3. [xlings] deps removed from the manual

[xlings.workspace] has been the one table since 2026.9.3.1, and deps is
honoured with a warning that names the replacement. The manual still taught the
old spelling in fourteen places in English and ten in Chinese, and
examples/09-cuda-kernel — shipped in 2026.9.5.1 — was written with it.

A deprecated form that still works is exactly the one a reader copies, so the
documentation no longer offers it. The parser's compatibility path is
untouched.

Verified

tests/e2e/601_exclusive_capability.sh asserts both halves, and the second
is the one that matters:

two providers, both declaring exclusive refused, naming the capability and both
the same graph with no claim still builds

Without that control the test would also pass against an engine that refused
every duplicate provider — the behaviour the key exists to avoid.

100 test binaries pass. The three new manifest tests and five new grammar tests
were run individually to confirm they execute rather than merely being counted:

[  PASSED  ] 3 tests.     ManifestExclusive.*
[  PASSED  ] 5 tests.     AccelOpenGrammar.*

Companion

Payloads land separately in openxlings/xim-pkgindex#759 (25 packages: the CUDA
toolkit split by upstream component, plus DPC++). They do not depend on this
change and this change does not depend on them.

…eprecated environment key removed from the manual

Three things, all of which come out of the multi-device design in
.agents/docs/2026-09-05-multi-device-ecosystem-design.md.

## `[package] exclusive`

Two packages providing one capability is usually fine and sometimes the point:
an OpenBLAS package and an MKL package both provide `blas`, and a build that
links one program against each is legitimate. What is not fine is two
implementations of ONE accelerator interface in one link, because they define
the same symbols and the link resolves every call to whichever archive it
reached first.

The engine cannot tell those apart. Seeing the symbol overlap needs object
files that do not exist when capabilities are bound, and refusing every
duplicate provider as a rule would break the BLAS case the manual documents.

So the package says it:

    provides  = ["gpu-blas"]
    exclusive = ["gpu-blas"]

Two such packages in one graph are refused when capabilities are bound, before
anything is compiled, naming the capability and both providers, and reporting
`exclusive-capability` in `--format json`. A capability nobody declares
exclusive behaves exactly as before.

It is a list rather than a flag because a package may provide several
capabilities and be the sole provider of only some. An entry naming a
capability the package does not supply is a schema warning: exclusivity is a
claim about this package's own symbols, and a silent no-op is how a typo
survives.

## The `accel` grammar is open

`cuda`, `hip`, `vulkan` and `sycl` were never a closed set, but the floor had
only CUDA's spelling. `floor>=` is now accepted alongside `ptx>=` for the same
field, so a backend whose portable form is SPIR-V does not have to borrow
NVIDIA's word for it. The existing spelling still parses -- asserted, because
descriptors written before this exist.

Tests cover `vulkan1.3+{spirv1.6} floor>=1.4`, `sycl2020+{spir64,...}` and
`hip6.4+{gfx942}`, including that an architecture carrying no leading number is
compared by equality rather than by a level invented from its middle digits.

## `[xlings] deps` is gone from the manual

`[xlings.workspace]` has been the one table since 2026.9.3.1, and `deps` is
honoured with a warning. The manual still taught the old spelling in fourteen
places in English and ten in Chinese, and `examples/09-cuda-kernel` -- shipped
in 2026.9.5.1 -- was written with it. A deprecated form that still works is
exactly the one a reader will copy, so the documentation no longer offers it.
The compatibility path in the parser is untouched: a project that has it keeps
building and is told what to write.

## Verified

`tests/e2e/601_exclusive_capability.sh` asserts both halves, and the second
half is the one that matters: the same graph without the claim still builds.
Without it this test would also pass against an engine that refused every
duplicate provider, which is the behaviour the key exists to avoid.

100 test binaries pass. The three new manifest tests and five new grammar tests
were run individually to confirm they execute rather than being counted.
@Sunrisepeak
Sunrisepeak merged commit 1e2137b into main Sep 5, 2026
36 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants