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

This commit is contained in:
2026-07-29 00:05:26 -07:00
parent 5af84b8edc
commit b342860779
4 changed files with 529 additions and 0 deletions
+105
View File
@@ -0,0 +1,105 @@
namespace WslcApiDump;
/// <summary>
/// Every member <c>NucleicBroker/Wslc/WslcFacade.cs</c> calls on the preview
/// <c>Microsoft.WSL.Containers</c> API, as plain strings.
///
/// The facade was written from Microsoft's documentation without a machine to run it on
/// (docs/WINDOWS_PORT.md §1.5), so each line here is a *claim* — and this spike's job is to say,
/// for each one, whether the shipped assembly agrees. Strings rather than typed references is the
/// entire trick: a typed spike that names <c>Session.CreateOrOpen</c> fails to COMPILE if that
/// method has a different name, which teaches us nothing. Reflection turns every wrong guess into
/// a printed line instead of a build error, so one run produces the complete worklist.
///
/// Keep in lockstep with WslcFacade.cs. A member that stops being used should leave this list;
/// a newly-used member should join it, so the next run of this tool still covers the real surface.
/// </summary>
internal static class FacadeAssumptions
{
internal sealed record Assumption(string Type, string Member, Kind MemberKind, string Why);
internal enum Kind { Method, Property, Event, Constructor, EnumValue, Type }
internal static readonly Assumption[] All =
[
// ---- Service entry point: onboarding (§8 step 2) ----
new("WslcService", "GetServiceVersion", Kind.Method,
"hello capabilities — hostd degrades across preview→GA churn on this string"),
new("WslcService", "GetMissingComponents", Kind.Method,
"components.missing RPC; drives the guided-install onboarding page"),
new("WslcService", "InstallComponentsAsync", Kind.Method,
"components.install RPC"),
new("ComponentFlags", "None", Kind.EnumValue,
"the 'nothing missing' sentinel the facade filters on"),
// ---- Session: one per channel, hosts every container (§3.2) ----
new("SessionSettings", ".ctor", Kind.Constructor,
"SessionSettings(name, dataDir) — the two-arg shape the facade assumes"),
new("SessionSettings", "CpuCount", Kind.Property, "session.ensure cpu"),
new("SessionSettings", "MemoryMB", Kind.Property,
"session.ensure memoryMB; §3.2 notes a resize needs a sandbox restart"),
new("Session", "CreateOrOpen", Kind.Method,
"THE create-or-attach primitive. If this is absent, broker reattach after a crash "
+ "(§2.3) has no mechanism and the whole supervision design changes"),
new("Session", "Terminate", Kind.Method, "session.terminate RPC"),
new("Session", "SessionTerminationHandler", Kind.Property,
"session.down notification → hostd's reconcile sweep"),
new("Session", "HostGatewayAddress", Kind.Property,
"THE control-plane address (§5). ensureRunning returns it to the Swift engine and "
+ "control-bridge.js dials it. If this member does not exist, §5's primary transport "
+ "needs another source (query the vNIC) or the hvsocket fallback gets promoted"),
// ---- Images ----
new("Session", "PullImageAsync", Kind.Method, "image.pull RPC (naros-agent from GHCR)"),
new("PullImageOptions", ".ctor", Kind.Constructor, "PullImageOptions(reference)"),
new("PullImageOptions", "Credentials", Kind.Property, "GHCR auth (registryAuth)"),
new("PullImageOptions", "Progress", Kind.Event,
"image.pullProgress → the existing controlDownloadProgress UI surface"),
new("RegistryCredentials", ".ctor", Kind.Constructor, "RegistryCredentials(user, password)"),
new("Session", "GetImages", Kind.Method, "image.list / image.inspect"),
new("Session", "DeleteImage", Kind.Method, "image.delete"),
// ---- Containers ----
new("Session", "CreateContainer", Kind.Method, "container.create"),
new("Session", "GetContainers", Kind.Method, "container.list; reattach re-enumeration"),
new("ContainerSettings", ".ctor", Kind.Constructor, "ContainerSettings(image)"),
new("ContainerSettings", "Name", Kind.Property, "channel-suffixed container naming"),
new("ContainerSettings", "Hostname", Kind.Property, "container.create hostname"),
new("ContainerSettings", "NetworkingMode", Kind.Property,
"NAT vs mirrored (§5 item 4) — determines how the guest reaches the host"),
new("ContainerSettings", "Volumes", Kind.Property, "the NTFS worktree bind mount (D8)"),
new("ContainerSettings", "InitProcess", Kind.Property, "naros-init as PID 1 (docs/NAROS.md)"),
new("ContainerVolume", ".ctor", Kind.Constructor,
"ContainerVolume(hostPath, guestPath, readOnly) — the 3-arg shape"),
new("ContainerNetworkingMode", "", Kind.Type, "enum parsed from the RPC's networkingMode"),
new("Container", "Start", Kind.Method, "container.start"),
new("Container", "Stop", Kind.Method, "container.stop(signal, grace)"),
new("Container", "Delete", Kind.Method, "container.delete"),
new("Container", "State", Kind.Property, "container.state → running/stopped/absent"),
new("Container", "GetStatistics", Kind.Method,
"container.stats → ContainerResourceSample; the Swift engine folds deltas from it"),
new("Container", "RunProcess", Kind.Method, "proc.exec — the agent's own exec path"),
new("ContainerState", "Running", Kind.EnumValue, "the one state the facade tests by name"),
new("DeleteContainerFlags", "Force", Kind.EnumValue, "container.delete force"),
// ---- Processes: the agent stdio path (§3.2 WslcProcessHandle) ----
new("ProcessSettings", "CmdLine", Kind.Property, "argv"),
new("ProcessSettings", "Environment", Kind.Property, "env"),
new("ProcessSettings", "WorkingDirectory", Kind.Property, "cwd"),
new("ProcessSettings", "OutputMode", Kind.Property, "event-mode stdio, not polling"),
new("ProcessSettings", "Terminal", Kind.Property, "tty for the Terminal panel (§7)"),
new("ProcessSettings", "UserId", Kind.Property,
"runAsUID 501 (§3.2). If absent, exec falls back to a setpriv/su wrapper argv — "
+ "interceptors and nash don't care about the numeric uid, so this is recoverable"),
new("ProcessSettings", "GroupId", Kind.Property, "runAsGID"),
new("ProcessOutputMode", "Event", Kind.EnumValue,
"the mode that makes stdio push-based; polling would change the whole broker design"),
new("Signal", "", Kind.Type, "the enum Stop/Signal take; the RPC carries POSIX ints"),
new("Process", "OutputReceived", Kind.Event, "→ proc.stdout / proc.stderr notifications"),
new("Process", "Exited", Kind.Event, "→ proc.exit; must never overtake output (OutboundWriter)"),
new("Process", "WriteStdin", Kind.Method, "proc.stdin (NDJSON to the agent)"),
new("Process", "CloseStdin", Kind.Method, "proc.closeStdin"),
new("Process", "Signal", Kind.Method, "proc.signal — the agent's real POSIX Stop path"),
new("Process", "ResizeTerminal", Kind.Method, "proc.resize (tty mode)"),
];
}
+323
View File
@@ -0,0 +1,323 @@
using System.Reflection;
using System.Text;
namespace WslcApiDump;
/// <summary>
/// M1 spike (a), phase 1 (docs/WINDOWS_PORT.md §13): what does Microsoft.WSL.Containers
/// ACTUALLY look like, and where is <c>WslcFacade.cs</c> wrong?
///
/// Everything the Windows container subsystem rests on — items 5, 6 and 7 — was written against
/// documentation, on a machine with no WSL. This program is the cheapest possible way to convert
/// that pile of assumptions into a worklist, and it is written entirely in reflection so that it
/// cannot fail to build no matter how wrong the assumptions turn out to be.
///
/// It never mutates anything unless asked: the default run only reads type metadata. `--probe`
/// additionally calls the two safe statics (service version, missing components). `--session`
/// goes one step further and creates a real session, because the single most important unknown —
/// which property carries the WSL gateway address (§5) — can only be answered by looking at a
/// live one.
/// </summary>
internal static class Program
{
private const string AssemblyName = "Microsoft.WSL.Containers";
private static int Main(string[] args)
{
var probe = args.Contains("--probe") || args.Contains("--session");
var session = args.Contains("--session");
var outPath = ArgValue(args, "--out") ?? "wslc-api-dump.txt";
Assembly assembly;
try
{
assembly = Assembly.Load(new AssemblyName(AssemblyName));
}
catch (Exception e)
{
Console.Error.WriteLine($"could not load {AssemblyName}: {e.Message}");
Console.Error.WriteLine(
"Is the preview NuGet restored? `dotnet restore windows/spikes/WslcApiDump`.");
return 2;
}
var types = assembly.GetExportedTypes().OrderBy(t => t.FullName, StringComparer.Ordinal).ToArray();
Console.WriteLine($"{AssemblyName} {assembly.GetName().Version} — {types.Length} public types");
Console.WriteLine();
var report = new StringBuilder();
report.AppendLine($"# {AssemblyName} {assembly.GetName().Version}");
report.AppendLine($"# location: {assembly.Location}");
report.AppendLine();
foreach (var type in types) DescribeType(type, report);
File.WriteAllText(outPath, report.ToString());
Console.WriteLine($"full API dump → {Path.GetFullPath(outPath)}");
Console.WriteLine();
var missing = CheckAssumptions(types);
if (probe) ProbeStatics(types);
if (session) ProbeSession(types, ArgValue(args, "--session-name") ?? "nucleic-spike");
Console.WriteLine();
Console.WriteLine(missing == 0
? "RESULT: every WslcFacade assumption is present. Fix nothing; write the typed spike."
: $"RESULT: {missing} assumption(s) wrong — each one is a line to change in "
+ "windows/NucleicBroker/Wslc/WslcFacade.cs, and nowhere else (that is what IWslc is for).");
// Exit 0 either way: a mismatch is this tool's PRODUCT, not its failure. Only a genuinely
// broken run (assembly missing) is non-zero, so a wrapper script can tell them apart.
return 0;
}
// MARK: - Type dump
private static void DescribeType(Type type, StringBuilder report)
{
var kind = type.IsEnum ? "enum"
: type.IsInterface ? "interface"
: type.IsValueType ? "struct"
: "class";
report.AppendLine($"{kind} {type.FullName}"
+ (type.BaseType is { } b && b != typeof(object) ? $" : {b.Name}" : ""));
if (type.IsEnum)
{
foreach (var name in Enum.GetNames(type)) report.AppendLine($" .{name}");
report.AppendLine();
return;
}
foreach (var ctor in type.GetConstructors())
report.AppendLine($" .ctor({Parameters(ctor)})");
foreach (var property in type.GetProperties(Public).OrderBy(p => p.Name, StringComparer.Ordinal))
report.AppendLine(
$" {Short(property.PropertyType)} {property.Name} "
+ $"{{ {(property.CanRead ? "get; " : "")}{(property.CanWrite ? "set; " : "")}}}");
foreach (var evt in type.GetEvents(Public).OrderBy(e => e.Name, StringComparer.Ordinal))
report.AppendLine($" event {Short(evt.EventHandlerType)} {evt.Name}");
foreach (var method in type.GetMethods(Public)
.Where(m => !m.IsSpecialName)
.OrderBy(m => m.Name, StringComparer.Ordinal))
report.AppendLine($" {Short(method.ReturnType)} {method.Name}({Parameters(method)})");
report.AppendLine();
}
private const BindingFlags Public =
BindingFlags.Public | BindingFlags.Instance | BindingFlags.Static | BindingFlags.DeclaredOnly;
private static string Parameters(MethodBase m) =>
string.Join(", ", m.GetParameters().Select(p => $"{Short(p.ParameterType)} {p.Name}"));
private static string Short(Type? t)
{
if (t is null) return "void";
if (!t.IsGenericType) return t.Name;
var name = t.Name[..t.Name.IndexOf('`')];
return $"{name}<{string.Join(", ", t.GetGenericArguments().Select(Short))}>";
}
// MARK: - Assumption check (the actual product)
private static int CheckAssumptions(Type[] types)
{
Console.WriteLine("WslcFacade.cs assumptions:");
Console.WriteLine();
var wrong = 0;
foreach (var group in FacadeAssumptions.All.GroupBy(a => a.Type))
{
var type = types.FirstOrDefault(t => t.Name == group.Key);
if (type is null)
{
// Summarise rather than repeat: if a whole type is renamed or namespaced away,
// one line naming it beats a paragraph per member. The per-member "why" only
// earns its space when the type exists and a single member is wrong.
wrong += group.Count();
Console.WriteLine($" MISSING TYPE {group.Key} "
+ $"({group.Count()} member(s): {string.Join(", ", group.Select(a => a.Member))})");
var near = Nearest(group.Key, types.Select(t => t.Name));
Console.WriteLine(near.Length > 0
? $" nearest types: {string.Join(", ", near)}"
: " no similarly-named type — check the dump file's namespaces");
continue;
}
foreach (var assumption in group)
{
if (assumption.MemberKind is FacadeAssumptions.Kind.Type || Has(type, assumption))
{
Console.WriteLine($" ok {type.Name}.{assumption.Member}");
continue;
}
wrong++;
Console.WriteLine($" MISSING {type.Name}.{assumption.Member} "
+ $"({assumption.MemberKind.ToString().ToLowerInvariant()})");
Console.WriteLine($" why: {assumption.Why}");
var near = Nearest(assumption.Member, MemberNames(type));
if (near.Length > 0)
Console.WriteLine($" nearest: {string.Join(", ", near)}");
}
}
return wrong;
}
private static bool Has(Type type, FacadeAssumptions.Assumption a) => a.MemberKind switch
{
FacadeAssumptions.Kind.Constructor => type.GetConstructors().Length > 0,
FacadeAssumptions.Kind.EnumValue => type.IsEnum && Enum.GetNames(type).Contains(a.Member),
FacadeAssumptions.Kind.Event => type.GetEvent(a.Member) is not null,
FacadeAssumptions.Kind.Property =>
type.GetProperty(a.Member) is not null || type.GetField(a.Member) is not null,
FacadeAssumptions.Kind.Method => type.GetMethods(Public).Any(m => m.Name == a.Member),
_ => true,
};
private static IEnumerable<string> MemberNames(Type type) =>
type.IsEnum
? Enum.GetNames(type)
: type.GetMembers(Public).Where(m => !m.Name.StartsWith('.')).Select(m => m.Name).Distinct();
/// <summary>Cheap "did they just rename it" hint: shared prefix or containment, no edit
/// distance. A three-name shortlist is enough to spot <c>HostGateway</c> vs
/// <c>HostGatewayAddress</c>, which is the realistic failure mode.</summary>
private static string[] Nearest(string wanted, IEnumerable<string> candidates)
{
var needle = wanted.TrimStart('.');
if (needle.Length == 0) return [];
return candidates
.Where(c => c.Contains(needle, StringComparison.OrdinalIgnoreCase)
|| needle.Contains(c, StringComparison.OrdinalIgnoreCase)
|| SharedPrefix(c, needle) >= 4)
.Distinct()
.Take(3)
.ToArray();
}
private static int SharedPrefix(string a, string b)
{
var n = 0;
while (n < a.Length && n < b.Length && char.ToLowerInvariant(a[n]) == char.ToLowerInvariant(b[n])) n++;
return n;
}
// MARK: - Live probes
/// <summary>The two statics that are safe to call on any machine: they only read state.</summary>
private static void ProbeStatics(Type[] types)
{
Console.WriteLine();
Console.WriteLine("live probe (read-only):");
var service = types.FirstOrDefault(t => t.Name == "WslcService");
if (service is null) { Console.WriteLine(" no WslcService type — skipping"); return; }
foreach (var name in new[] { "GetServiceVersion", "GetMissingComponents" })
{
var method = service.GetMethods(Public)
.FirstOrDefault(m => m.Name == name && m.GetParameters().Length == 0);
if (method is null) { Console.WriteLine($" {name}: absent"); continue; }
try
{
Console.WriteLine($" {name}() = {Render(method.Invoke(null, null))}");
}
catch (TargetInvocationException e)
{
// The interesting failure: WSL not installed. That IS the onboarding condition
// §8 step 2 exists to handle, so report it plainly rather than as a crash.
Console.WriteLine($" {name}() threw {e.InnerException?.GetType().Name}: "
+ $"{e.InnerException?.Message}");
}
}
}
/// <summary>
/// Create a real session and print every readable property of it.
///
/// This is here for one question: §5's control plane needs the WSL-facing host address, the
/// facade guesses it is <c>Session.HostGatewayAddress</c>, and no amount of type-metadata
/// reading tells us whether that property holds what we need. Dumping the live VALUES of a
/// session lets us recognise a gateway IP when we see one, whatever it happens to be called.
///
/// Leaves the session running on purpose — `wslc session ls` should show it, and whether it
/// survives this process exiting is itself one of the §2.3 questions (service-backed state is
/// what makes broker-crash reattach possible). Tear it down with `wslc` when done.
/// </summary>
private static void ProbeSession(Type[] types, string name)
{
Console.WriteLine();
Console.WriteLine($"live probe (creates session '{name}'):");
var settingsType = types.FirstOrDefault(t => t.Name == "SessionSettings");
var sessionType = types.FirstOrDefault(t => t.Name == "Session");
if (settingsType is null || sessionType is null)
{
Console.WriteLine(" SessionSettings/Session absent — skipping");
return;
}
var dataDir = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"Nucleic", "spike", "wslc");
Directory.CreateDirectory(dataDir);
object? settings;
try
{
settings = Activator.CreateInstance(settingsType, name, dataDir);
}
catch (Exception e)
{
Console.WriteLine($" SessionSettings(name, dataDir) rejected: {e.InnerException?.Message ?? e.Message}");
Console.WriteLine(" → constructor shape differs; see the .ctor lines in the dump file");
return;
}
var factory = sessionType.GetMethods(Public)
.FirstOrDefault(m => m.IsStatic && m.GetParameters().Length == 1
&& m.GetParameters()[0].ParameterType == settingsType);
if (factory is null)
{
Console.WriteLine(" no static Session factory taking SessionSettings — see the dump");
return;
}
Console.WriteLine($" using {sessionType.Name}.{factory.Name}(SessionSettings)");
object? live;
try
{
live = factory.Invoke(null, [settings]);
}
catch (TargetInvocationException e)
{
Console.WriteLine($" session create threw {e.InnerException?.GetType().Name}: "
+ $"{e.InnerException?.Message}");
return;
}
if (live is null) { Console.WriteLine(" factory returned null"); return; }
Console.WriteLine(" live session properties (look for the gateway address — §5):");
foreach (var property in sessionType.GetProperties(Public)
.Where(p => p.CanRead && p.GetIndexParameters().Length == 0)
.OrderBy(p => p.Name, StringComparer.Ordinal))
{
string rendered;
try { rendered = Render(property.GetValue(live)); }
catch (Exception e) { rendered = $"<threw {e.InnerException?.GetType().Name ?? e.GetType().Name}>"; }
Console.WriteLine($" {property.Name} = {rendered}");
}
Console.WriteLine(" (session left running — `wslc session ls`; whether it outlives this "
+ "process is the §2.3 reattach question)");
}
private static string Render(object? value) => value switch
{
null => "null",
string s => $"\"{s}\"",
System.Collections.IEnumerable e and not string =>
"[" + string.Join(", ", e.Cast<object?>().Select(Render)) + "]",
_ => value.ToString() ?? "?",
};
private static string? ArgValue(string[] args, string flag)
{
var i = Array.IndexOf(args, flag);
return i >= 0 && i + 1 < args.Length && !args[i + 1].StartsWith("--") ? args[i + 1] : null;
}
}
+24
View File
@@ -0,0 +1,24 @@
<Project Sdk="Microsoft.NET.Sdk">
<!-- M1 spike (a), phase 1 — docs/WINDOWS_PORT.md §13.
Reports the REAL Microsoft.WSL.Containers object model, and checks every assumption
NucleicBroker/Wslc/WslcFacade.cs makes against it.
Deliberately NOT in Nucleic.sln: it needs the preview NuGet, which the broker's own
contract tests must never require (they run on Linux against FakeWslc). Build it by
path — see windows/spikes/README.md. -->
<PropertyGroup>
<OutputType>Exe</OutputType>
<AssemblyName>wslc-api-dump</AssemblyName>
<RootNamespace>WslcApiDump</RootNamespace>
<TargetFramework>net9.0-windows10.0.26100.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<!-- Same pin as the broker (docs/WINDOWS_PORT.md §15). If restore fails because the
version moved, change it HERE first, find out what the new API looks like, and only
then bump the broker — that ordering is the whole point of this spike. -->
<PackageReference Include="Microsoft.WSL.Containers" Version="[0.1.0-preview.1]" />
</ItemGroup>
</Project>