Skip to content

fix: WSLC x64-only requirements, actionable errors, shared just modules and purview.dev docs layout - #29

Merged
kieronlanning merged 14 commits into
mainfrom
fix/wslc-requirements
Nov 18, 2026
Merged

kieronlanning merged 14 commits into
mainfrom
fix/wslc-requirements

Conversation

@kieronlanning

Copy link
Copy Markdown
Contributor

Stacked on #28 (it includes #28's commits until that merges; review the last six commits). It targets main so the PR checks run.

WSL Containers backend

  • x64 only. The Windows implementation was compiled for x64 but also shipped under payload/win-arm64, where it could not load. The package now ships payload/win-x64 only. PCC0002 rejects non-x64 Windows consumers, and in a non-x64 process the facade reports the backend unavailable, so selection falls through to Docker.
  • WSL floor enforced. MinimumWslVersion follows the SDK pin (3.0.5) in Directory.Packages.props, is stamped into the assembly, and is checked at run time.
  • Actionable failures. A new WslRequirements class maps missing components, version mismatches and HRESULTs (WSL_E_OS_NOT_SUPPORTED, optional component, class not registered, missing wslcsdk.dll) to messages that say what to do.
  • wslc location. The CLI is found on PATH or at %ProgramFiles%\WSL\wslc.exe.
  • Docker probe. The ping deadline now starts after endpoint discovery, so a slow discovery no longer reports a healthy daemon as not responding.

CI

  • Both workflows install WSL with plain wsl --update; WSL Containers has been in the stable channel since 3.0.1. The job fails if the runner's WSL is below the floor.

Build

  • Adopted the shared just modules (.build/just/). The root Justfile keeps only the repo's own recipes and the serial, retrying test override that WSLC needs.
  • Local tooling: oxfmt/oxlint dev dependencies, plus a refreshed skills-lock.json.

Docs

  • Host requirements. One authoritative section in Consumer Requirements: x64, WSL 3.0.5+, Windows wherever WSL 2 runs, virtualisation. The incorrect "Windows 11 22H2+" and "no Windows 10" claims are gone.
  • purview.dev layout. Pages are grouped into guide/ and contributing/ with _redirects.yml, and index.md is folded into Home.md. The ASCII diagrams are replaced with a LikeC4 model plus Mermaid. The site assessment went from 1 error and 6 warnings to clean.
  • Catalogue record. Home is no longer excluded, the module and consumer-check counts are correct, the description now mentions the wslc fallback, and the four missing packages are added.

Validation (local, Windows 11 23H2, WSL 3.0.5)

  • just pipeline-pack-validate: build, lint, unit tests and pack pass; 30/30 packages valid.
  • just verify-consumers: 28/28.
  • WSLC contract suite (real containers): 48/48.
  • Docker integration suite: 26/26.
  • Site assessment: 0 findings. likec4 validate passes. No broken relative links.
  • Not covered: ARM64 is verified at build time only (no ARM64 machine), and an older WSL only through unit tests.

BuildSdk 2.2.0 makes runtime-async and the C# 15 updated memory-safety
rules opt-in, so enable both explicitly for the net11.0 builds. Select
the Supported target-framework set (net10.0;net11.0) repo-wide and
derive the WSL backend's portable and Windows targets from it.

Guard the memory-safety rules alongside runtime-async in
BuildFeatureTests, and update the docs that described them as SDK
defaults. Also bumps the purview.build and dotnet-inspect tools.
Aspire.Hosting 17.0.0, Testcontainers 4.17.0,
Microsoft.Extensions.Telemetry.Abstractions 11.0.0,
Purview.Telemetry.SourceGenerator 6.0.1, SourceLink 11.0.100, TUnit
1.87.0 and the test-only clients. Every shipped dependency still ships
a net10.0 asset, so the .NET 10 floor is unchanged.
…build

Testcontainers returns a null endpoint when no daemon is discovered, so
every Docker call site failed with a bare NullReferenceException.
Resolve it in one place (DockerEndpoint) and throw a
ContainerBackendUnavailableException that says how to fix it;
GetInfoAsync also names the endpoint on a timeout or refused ping.

AutoSample copies Wsl's net10.0-windows output but nothing ordered that
build first, so a parallel solution build could fail with "The Windows
implementation is not built". Add a build-only project reference.
pr.yml now also runs on push to main, so main's status reflects what was
merged. Main runs are never cancelled by a newer one; PR runs still are.
A push to main never publishes.
PackageProjectUrl now points at https://purview.dev/projects/containers/,
matching the homepage in package.json.
Remove the experimental, preview and no-support-guarantee notices from
the README, wiki, package READMEs and skills. Versions stay on a
-prerelease.N suffix until the stable 1.0.0, which includes the WSL
Containers backend. Refresh stale version examples to prerelease.14 and
describe the push-to-main build.
…ionable

Drop ARM64: the Windows implementation was compiled for x64 yet shipped
under payload/win-arm64, where it could not load. Ship payload/win-x64
only; PCC0002 now rejects any non-x64 Windows consumer, and the portable
facade reports the backend unavailable in a non-x64 process so selection
falls through to Docker.

Add WslRequirements: the minimum WSL (MinimumWslVersion, following the
SDK pin in Directory.Packages.props and stamped into the assembly) is
checked at run time, and every missing component, version mismatch and
HRESULT (WSL_E_OS_NOT_SUPPORTED, optional component, class not
registered, missing wslcsdk.dll) is reported with its fix instead of a
bare enum name. wslc is found on PATH or at %ProgramFiles%\WSL.

verify-consumers gains cases 26-28 (arm64 rejected, x64 payload copied).
Testcontainers can spend several seconds probing providers before it
settles on an endpoint, which used up the 10 second ping budget and
reported a healthy daemon as not responding.
WSL Containers is generally available in the stable WSL channel (3.0.1
and later), so drop --pre-release and fail the job when the runner's WSL
is older than the floor read from Directory.Packages.props.
Import .build/just/index.just (copied verbatim from the
purview-buildsdk-justfile skill) and keep only this repository's own
recipes in the root Justfile: the serial, retrying test override that
the WSLC image-store lock requires, verify-consumers, the samples and
code.
Local tooling: oxfmt/oxlint dev dependencies with their bun.lock, the
refreshed skills-lock.json, and a trailing newline in .gitignore.
…yout

Requirements: one authoritative Host requirements section in Consumer
Requirements (x64 only, WSL 3.0.5+ from the stable channel, Windows
wherever WSL 2 runs, virtualisation), with the short form everywhere
else; drops the incorrect Windows 11 22H2 and "no Windows 10" claims.

Layout: group pages into guide/ and contributing/ with git mv, keeping
the catalogue deep-linked pages at the root, and record every move in
_redirects.yml. Fold index.md into Home.md as the single hub, rebuild
_Sidebar.md, replace the ASCII diagrams with a LikeC4 model plus Mermaid
and tables, label every fence, and use GitHub alerts.

Catalogue record: Home is no longer excluded; nine modules,
twenty-eight consumer checks, the bounded wslc fallback, the x64 limit,
and the four packages it was missing.
… Linux

The WslRequirements Describe(Component ...) tests failed on the Linux CI
agent with TypeInitializationException: touching any
Microsoft.WSL.Containers type runs that assembly's module initializer,
which loads the Windows-only native wslcsdk.dll.

Mirror the SDK's Component flags as WslComponent, with values taken
from the SDK's own enum constants (folded at compile time, so they cannot
drift and nothing loads the SDK), and convert at the one call site in
WslContainerRuntime. AGENTS.md now states the rule and how to reproduce
the Linux condition locally.
…4 majors

GitHub deprecated Node.js 20 for actions and was forcing checkout@v4
and setup-dotnet@v4 onto Node.js 24 with a warning. Use checkout@v7 and
setup-dotnet@v6, which target Node.js 24 natively, in the workflows and
in the CI examples in Backends.md. A self-hosted runner needs 2.327.1
or later, now listed in the Testing prerequisites.
@kieronlanning
kieronlanning merged commit 74d2085 into main Nov 18, 2026
3 checks passed
@kieronlanning
kieronlanning deleted the fix/wslc-requirements branch November 18, 2026 17:14
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.

1 participant