Merge nucleic/lucid-river-toad-6efj into dev

spikes/WslcApiDump/FacadeAssumptions.cs

@@ -28,7 +28,12 @@ internal static class FacadeAssumptions
             "hello capabilities — hostd degrades across preview→GA churn on this"),
         new("WslcService", "GetMissingComponents", Kind.Method,
             "components.missing RPC; returns IReadOnlyList<Component>, NOT a flags enum"),
-        new("WslcService", "InstallWithDependencies", Kind.Method, "components.install RPC"),
+        new("WslcService", "InstallWithDependenciesAsync", Kind.Method,
+            "components.install RPC — the ASYNC form, because only it carries InstallProgress"),
+        new("InstallProgress", "Component", Kind.Property,
+            "which component is installing → components.installProgress status"),
+        new("InstallProgress", "Total", Kind.Property,
+            "denominator for the install percentage (Progress/Total)"),
         new("Component", "WslPackage", Kind.EnumValue,
             "one of the three components onboarding can report missing"),
         new("ServiceVersion", "Major", Kind.Property, "the version triple reported in hello"),
@@ -40,9 +45,13 @@ internal static class FacadeAssumptions
             "session.ensure memoryMB — NOT MemoryMB; a resize needs a sandbox restart (§3.2)"),
         new("SessionSettings", "Timeout", Kind.Property, "idle timeout for the whole session VM"),
         new("Session", ".ctor", Kind.Constructor,
-            "there is NO CreateOrOpen — construction is the only entry point, and whether a second "
-            + "construction with an existing name attaches or throws Error.SessionReserved is the "
-            + "open question broker reattach (§2.3) hangs on"),
+            "there is NO CreateOrOpen — construction is the only entry point, and it is LAZY: a "
+            + "second construction with an existing name succeeds and means nothing. Start() is "
+            + "where the service is consulted, and it refuses with ERROR_ALREADY_EXISTS, which is "
+            + "why broker reattach (§2.3) cannot be served from this surface"),
+        new("Session", "ProcessCrashed", Kind.Event,
+            "ProcessCrashInformation — the only crash detail wslc offers, and what makes a "
+            + "SIGKILLed agent explicable in the host log (the Swift diagnoseKill seam)"),
         new("Session", "Start", Kind.Method, "brings the session VM up after construction"),
         new("Session", "Terminate", Kind.Method, "session.terminate RPC"),
         new("Session", "Terminated", Kind.Event,
@@ -51,18 +60,24 @@ internal static class FacadeAssumptions
             "distinguishes a crash from an orderly shutdown in the session.down reason"),
 
         // ---- Images ----
-        new("Session", "PullImage", Kind.Method, "image.pull RPC (naros-agent from GHCR), sync form"),
         new("Session", "PullImageAsync", Kind.Method,
-            "the async form, which is where pull PROGRESS comes from (ImageProgress)"),
+            "image.pull RPC (naros-agent from GHCR). The async form specifically: the sync "
+            + "PullImage reports no progress at all"),
         new("PullImageOptions", ".ctor", Kind.Constructor, "PullImageOptions(uri)"),
         new("PullImageOptions", "RegistryAuth", Kind.Property,
             "GHCR auth — a STRING, not a credentials object"),
+        new("Session", "Authenticate", Kind.Method,
+            "where that string COMES FROM: Authenticate(registryUri, user, password) mints the "
+            + "identity token PullImageOptions.RegistryAuth wants. Without this the auth field "
+            + "has no documented producer and a private GHCR pull cannot work"),
         new("ImageProgress", "CurrentBytes", Kind.Property,
             "→ image.pullProgress → the existing controlDownloadProgress UI surface"),
         new("ImageProgressStatus", "Downloading", Kind.EnumValue, "pull progress phase"),
         new("Session", "GetImages", Kind.Method, "image.list / image.inspect"),
         new("ImageInfo", "Name", Kind.Property, "image ref — NOT .Reference"),
-        new("ImageInfo", "Sha256", Kind.Property, "image digest — NOT .Digest"),
+        new("ImageInfo", "Sha256", Kind.Property,
+            "image digest — NOT .Digest, and an IBuffer of raw bytes rather than a string, so the "
+            + "facade hex-encodes it into the sha256:<hex> the rest of Nucleic speaks"),
         new("Session", "DeleteImage", Kind.Method, "image.delete"),
 
         // ---- Containers ----
@@ -85,9 +100,17 @@ internal static class FacadeAssumptions
         new("Container", "Inspect", Kind.Method,
             "the ONLY per-container introspection there is — there is no GetStatistics(), so "
             + "container.stats has to exec cgroup reads instead (§13.1 finding 2)"),
+        // NOTE the absence: there is no Container.Name and no Session.GetContainers(), so a
+        // container is only ever reachable through the handle CreateContainer returned. That is
+        // why the facade keeps its own name→handle roster, and why container.list cannot see
+        // anything created before a broker restart (§13.1 finding 1).
+        new("Container", "Id", Kind.Property,
+            "the only identity the SDK gives back — there is NO Name property to match on"),
         new("Container", "CreateProcess", Kind.Method,
             "proc.exec — NOT RunProcess, and it does not start the process"),
         new("ContainerState", "Running", Kind.EnumValue, "the one state the facade tests by name"),
+        new("ContainerState", "Deleted", Kind.EnumValue,
+            "folds to \"absent\" — a deleted handle is gone as far as the Swift policy layer cares"),
         new("DeleteContainerOption", "Force", Kind.EnumValue, "container.delete force"),
         new("Error", "ContainerNotFound", Kind.EnumValue,
             "structured failure codes — a better source for the RPC's data.kind than string matching"),
@@ -107,7 +130,8 @@ internal static class FacadeAssumptions
             "→ proc.stderr — a SEPARATE event, not a stderr flag on one handler"),
         new("Process", "Exited", Kind.Event, "→ proc.exit; must never overtake output (OutboundWriter)"),
         new("Process", "GetInputStream", Kind.Method,
-            "proc.stdin — a WinRT stream, not a WriteStdin call; closing it is proc.closeStdin"),
+            "proc.stdin — a WinRT IOutputStream written through a DataWriter, not a WriteStdin "
+            + "call; disposing the STREAM is what the guest sees as EOF, i.e. proc.closeStdin"),
         new("Process", "Signal", Kind.Method, "proc.signal — the agent's real POSIX Stop path"),
         new("Signal", "SIGKILL", Kind.EnumValue,
             "signals are a NAMED enum; the RPC carries POSIX ints, so the broker maps them, and "