Merge nucleic/olive-jade-civet-rznt into dev

2026-07-29 00:14:32 -07:00
parent b342860779
commit 140b358da6
6 changed files with 127 additions and 80 deletions
@@ -4,10 +4,29 @@ using Microsoft.WSL.Containers;
 namespace NucleicBroker.Wslc;

 // The REAL Microsoft.WSL.Containers adapter (docs/WINDOWS_PORT.md §1.5, §3.2), compiled
-// only with -p:UseWslc=true on Windows. The API is public preview (GA fall 2026) and its
-// exact shapes are validated by the M1 wslc spike — every mapping below that spikes prove
-// wrong gets fixed HERE, never above the IWslc seam. Until M1 runs on real hardware, treat
-// this file as the best-effort transcription of the documented object model:
+// only with -p:UseWslc=true on Windows.
+//
+// !! KNOWN WRONG AS WRITTEN — DO NOT BUILD ON IT. !!
+//
+// M1 spike (a) has run (docs/WINDOWS_PORT.md §13.1) and the real API differs from this
+// transcription in roughly twenty places. Most are renames that belong exactly here and
+// nowhere else, which is what the IWslc seam is for: GetVersion not GetServiceVersion,
+// `new Session(settings)` + Start() not CreateOrOpen, MemorySizeInMB, HostName, ImageName,
+// CreateProcess-then-Start rather than RunProcess, DeleteContainerOption, a named Signal
+// enum, RegistryAuth as a string, ImageInfo.Name/.Sha256, and two separate output events
+// instead of one with a stderr flag.
+//
+// Three differences are NOT renames and need decisions before this file is finished:
+//   1. there is no container enumeration at all, so §2.3 broker reattach and the
+//      container.list RPC have no API behind them;
+//   2. there is no per-container statistics call, so container.stats must exec cgroup
+//      reads inside the container instead;
+//   3. there is no pty and no uid/gid on ProcessSettings, so §7's Terminal panel loses
+//      tty mode and exec wraps argv in setpriv/su (which §3.2 already anticipated).
+//
+// Read §13.1 before touching this file. Fixing it is the next step of item 5, and it is
+// now a fast loop: the package restores, so `dotnet build -p:UseWslc=true` compiles it.
+//
 //   WslcService (components) → Session (VM host, images) → Container → Process.
 public sealed class WslcFacade : IWslc
 {