feat(accel): exclusive capabilities, an open accel grammar, and the deprecated environment key removed from the manual - #562
Merged
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three things from the multi-device design
(
.agents/docs/2026-09-05-multi-device-ecosystem-design.md).1.
[package] exclusive— closing the same-symbol caseTwo packages providing one capability is usually fine and sometimes the point:
an OpenBLAS package and an MKL package both provide
blas, and a build thatlinks 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.
Reported as
exclusive-capabilityin--format json. A capability nobodydeclares 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
accelgrammar is openThe backend set was never closed, but the floor had only CUDA's spelling.
floor>=is now accepted alongsideptx>=for the same field.An architecture carrying no leading number —
gfx942— is compared byequality, because there is no ordering to read out of it. Reading
942out ofthe middle would invent a level AMD does not define.
3.
[xlings] depsremoved from the manual[xlings.workspace]has been the one table since 2026.9.3.1, anddepsishonoured 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.shasserts both halves, and the secondis the one that matters:
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:
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.