ISO artifact: nixos.iso on Proxmox ISO storage. Dropbox holds nixos.iso.7z + nixos.iso.sha256 (ArchiveSync + SevenZipCommand pattern — see Serena compressed_image_driver_sync).

Bootstrap SSH: single master NETSetup keypair. Pubkey committed at src/NETSetup/nixos/netsetup-master.pub, baked into iso/iso.nix root authorized_keys. Privkey shipped with NETSetup binary under src/NETSetup/Resources/netsetup-master.key (embedded resource, extracted to /NETSetup/.ssh/netsetup-master.key chmod 0600 on use).

OS trigger: Machine.OperatingSystem.Name.StartsWith("Nix") → nix-backed. OS.NixOS (contracts) routes to NixHostTemplate. New NETSetup-local OS constants NixNextcloud, NixIPFS defined in NETSetup.Config.Nix.NetsetupOS (NOT in contracts lib).

Templates: abstract NixHostTemplate base + concrete NixNextcloudTemplate, NixIpfsTemplate. Templates expose GenerateDefaultNix() (host config body) and GenerateHardwareNix(). Content derived from src/NETSetup/nixos/hosts/default-nextcloud/default.nix and default-ipfs/default.nix. GenerateFlakeNix() exists but is no longer called by ProvisionNixosVm — see post-implementation pivot below.

Per-VM emit shape (post-pivot, 2026-04-30): flat config.nix + hardware.nix + sops secrets.yaml + .default.key at the per-VM generated dir root. No emitted flake.nix — the base nix tree at /iso/nixos-config/flake.nix already exposes nixosConfigurations.default = mkHost "default" ./config.nix (nixos/hosts.nix:113). Overlaying our flake stripped disko + lanzaboote + sops modules from sharedHostModules, causing disko-install to crash with artifacts[1]: unbound variable (no diskoScript artifact when disko module isn’t loaded). Reusing the base flake keeps every shared module in scope.

End-to-end test ISO bootstrap: ProxmoxNixosNextcloudTests self-bootstraps every prerequisite in [TestInitialize] plus nixos.iso per run:

Why wsl --import instead of wsl --install -d NixOS? The Microsoft Store catalogue version is not always the pinned NixOS-WSL build the flake expects (nixpkgs lock + cached flake inputs). Importing a tarball we publish ourselves keeps WSL state reproducible across dev boxes.

install.sh invoked with -h default (not the per-VM hostname). Per-VM OS hostname identity preserved via networking.hostName set inside the emitted config.nix by NixHostTemplate.

Installer SOPS age key: single committed pair at src/NETSetup/nixos/.sops/installer.{key,pub}. Public key pinned as ProvisionNixosVm.InstallerAgePublicKey constant. Private key shipped via csproj <Content CopyToOutputDirectory="Always" CopyToPublishDirectory="Always">, deployed to /NETSetup/.sops/installer.key (700/600) by netsetup-first-boot.sh section 4c. ProvisionNixosVm.EmitConfigBundle generates a random 32-byte hex LUKS password, encrypts it via SopsCommand to a per-VM secrets.yaml, and copies the installer private key into .default.key so install.sh L156 can decrypt during disko-install. Local generated dir is wiped on success (TryCleanupConfigDir).

Disk: plain btrfs (no LUKS). Default /dev/sda; VirtIO VMs use /dev/vda. NixHostTemplate takes device param.

Entry point: extend UpdateMethods.RunProxmoxUpdate (append EnsureCustomerVms(host, config) at end). InstallCommand.InstallStage.ProxmoxVMs stays a stub.

New commands live in NETSetup/NETCommand/ — no changes to shared osisa.NETCommand. NixRemoteInstallCommand composes LinuxCommandBase for ssh/scp. QmGuestCommand wraps Proxmox-API nodes/<node>/qemu/<vmid>/agent via corsinvest client (reuse existing Proxmox/Host wrappers from osisa.SystemManagement.Proxmox).

No System.IO: use AbsolutePath + PhysicalFileOperator. No raw Process: use NETCommand builders.

VM identification: reuse CreateVirtualMachines.IsForHost + GetOrderedVmsForHost (DC-first ordering preserved).

Local emission path for generated nix configs: AbsolutePath("/NETSetup/generated-nix") / vmName (Linux Proxmox host), wiped + rewritten each update cycle.

UPDATE (2026-07-13, IPFS cluster secrets - commit a997e484, live test green end-to-end): NixIPFS provision now GENERATE + EMIT its own sops secrets on top of luks_password. Per-VM secrets.yaml also carry ipfs/swarm_key (multiline psk block /key/swarm/psk/1.0.0/ + /base16/ + 64-lowercase-hex) and ipfs/cluster_secret (single line CLUSTER_SECRET=<64-lowercase-hex>, a systemd EnvironmentFile line), both nested under one ipfs: map. Those two are cluster-shared: IpfsClusterSecretsGenerator.EnsureOn(config) mint them ONCE per customer/cluster (RandomNumberGenerator.Fill(byte[32]) + Convert.ToHexStringLower), stash on new persisted NETSetupConfig.IpfsCluster (IpfsClusterOptions holding IpfsSwarmKey + IpfsClusterSecret Vogen VOs), STABLE across re-provision (regen would partition the cluster). Key strings ipfs/swarm_key / ipfs/cluster_secret are consts, MUST match ipfs-private-cluster.nix:297,304. NixIpfsTemplate.GetRequiredSecrets(config) throw MissingIpfsClusterSecretsException : NETSetupException when a NixIPFS host emit with config.IpfsCluster == null. luks stays UPPERCASE hex; ipfs entropy is LOWERCASE hex.

UPDATE (2026-07-13, secrets.yaml renderer): emission gain nested-key + block-scalar support via new pure SecretsYamlBuilder. Single-segment keys stay FLAT (luks back-compat); a/b keys nest (so both ipfs/* group under one ipfs: map). Multiline value → YAML block scalar | (content indent = key indent + 2); single-line → inline-quoted (\ + " escaped). SopsCommand now hold IReadOnlyList<NixSecretEntry> Entries (was flat dict Payload); RenderedYamlInput delegate to the builder. Templates declare their needs via new virtual NixHostTemplate.GetRequiredSecrets(config) (base = Array.Empty); EmitConfigBundle call EnsureOn(config) then loop GetRequiredSecrets into the same builder. InstallNixosVm.Run also call EnsureOn(config) at top (inline-built configs).

UPDATE (2026-07-13, non-interactive LUKS): encrypted disko-install is NOW non-interactive via passwordFile = "/tmp/luks.key" in disk-layouts.nix (both encrypted + dual-boot luks blocks; also disk/encrypted.nix + disk/dual-boot.nix). install.sh (L195-196) write the decrypted sops luks_password to /tmp/luks.key (chmod 600) BEFORE disko-install, delete it after TPM enroll (L306). WHY: without passwordFile disko prompt for the passphrase on stdin, get NOTHING over the ssh pipe, luksFormat abort, and the nix closure copy into the still-unmounted /mnt/disko-install-root RAM tmpfs → No space left on device. This is the root-cause of the earlier IPFS install failures.

UPDATE (2026-07-13, NixIPFS VM sizing): NixIPFS VM get 8 GiB RAM (installer build the closure in a RAM-backed tmpfs store - undersize = OOM) + 64 GiB disk (IPFS repo live on the system disk). Contrast: NixHostTemplate default 2 GiB / 32 GiB; NixNextcloudTemplate 8 GiB / 256 GiB.

UPDATE (2026-07-13): the ProxmoxNixosNextcloudTests ISO uploader connect to the Proxmox host by LAN IP, NOT the osisaLib03 hostname (DNS not resolvable from every dev box).

Full CRUD/UoW shape mirroring osisa.OPNSense - same DataStoreReference/UnitOfWork/Repository pattern for future osisa.Rest.Repository migration path

Project lives in netsetup repo: src/osisa.Mikrotik/ + src/osisa.Mikrotik.Tests/, added to src/NETSetup.sln

OPNsense-aligned repo method names: GetAllAsync, GetAsync, AddAsync, SetAsync, DeleteAsync

WiFi v7+ only (/interface/wifi package, not legacy /interface/wireless) - hAP ax2 runs RouterOS 7 only

Batch-then-push UoW: changes buffered in-memory, CommitAsync pushes all pending PUT/PATCH/DELETE in sequence. No rollback on failure - throw MikrotikException with Applied[] + Failed[] delta

Entity base tracks both .id (*N format) and Name (nullable) for human-readable converge diffs

Typed C# properties with custom MikrotikStringConverter (System.Text.Json) handling MikroTik’s "all values are strings" encoding (string to bool/int/long deserialization)

Auth via env file /etc/netsetup/mikrotik-api.env (MIKROTIK_URL, MIKROTIK_USER, MIKROTIK_PASSWORD) - same KEY=VALUE pattern as OPNsense

MikrotikDesiredState is flat typed DTO with arrays per resource family (BridgeSpec[], BridgePortSpec[], etc.)

v1 MikrotikDesiredStateBuilder populates full Liberator VLAN cutover: bridges, VLANs, ports, WiFi SSIDs, DHCP disable, NAT disable, bonding, system identity

Converge safety guard: only delete entries matching desired state or prefixed with "netsetup-" - never delete user-created resources

Contracts-only public surface: NETSetup sees only IMikrotikConverge + MikrotikConnection + MikrotikDesiredState + *Spec records. All repo/entity/UoW types are internal (InternalsVisibleTo osisa.Mikrotik.Tests)

MikroTik REST API reference: https://help.mikrotik.com/docs/spaces/ROS/pages/47579162/REST+API

Scaffold landed: src/osisa.Mikrotik/ + src/osisa.Mikrotik.Tests/ wired into src/NETSetup.sln. osisa.Mikrotik.csproj targets $(DefaultNetTargetFramework), pulls Microsoft.Extensions.DependencyInjection.Abstractions + Microsoft.Extensions.Logging.Abstractions + osisa.Validation, exposes internals via <InternalsVisibleTo Include="osisa.Mikrotik.Tests" />.

Public surface (namespace osisa.Mikrotik.Contracts): MikrotikConnection, MikrotikDesiredState, IMikrotikConverge, MikrotikConvergeResult, MikrotikResourceDelta, plus the 16 *Spec records (BridgeSpec, BridgePortSpec, BridgeVlanSpec, InterfaceSpec, BondingSpec, IpAddressSpec, IpRouteSpec, DhcpServerSpec, DhcpLeaseSpec, DnsSpec, FirewallNatRuleSpec, FirewallFilterRuleSpec, WifiConfigurationSpec, WifiSecuritySpec, UserSpec, SystemIdentitySpec). DI: osisa.Mikrotik.MikrotikServiceCollectionExtensions.AddMikrotik(IServiceCollection). Exception: osisa.Mikrotik.Exceptions.MikrotikException (carries StatusCode + ErrorMessage + Detail?, message format "MikroTik {status}: {message}" or "MikroTik {status}: {message} ({detail})").

Transport (Client/MikrotikHttpClient, internal sealed IDisposable): real impl. Basic auth "Basic " + base64(user + ":" + pw) exposed on internal AuthorizationHeader test seam. HttpClient.BaseAddress = BaseUrl + "/", paths built via "rest/" + path.TrimStart('/'). Verbs: GetAsync<T> (list, [] on empty), GetSingleAsync<T>, PutAsync<T> (add), PatchAsync(path,id,body), DeleteAsync(path,id), PostAsync<T> (action endpoints). 4xx-5xx responses parse {error,message,detail} → MikrotikException; non-JSON body keeps ReasonPhrase as message. Self-signed cert skip via HttpClientHandler.ServerCertificateCustomValidationCallback (default on). Shared JsonSerializerOptions with PropertyNamingPolicy=null + DefaultIgnoreCondition.WhenWritingNull + MikrotikStringConverter. Test-only constructor accepts a pre-wired HttpClient for FakeHttpMessageHandler.

JSON (Json/MikrotikStringConverter, internal sealed JsonConverterFactory): real impl. CanConvert claims exactly bool | int | long | string. CreateConverter yields per-type nested converters. Read tolerates BOTH the MikroTik all-strings form ("true", "42") AND raw JSON values (true, 42) - resilient to per-version drift. Write ALWAYS emits a quoted JSON string (writer.WriteStringValue); numeric values formatted with InvariantCulture to avoid German-locale thousands-separator regressions. String converter coerces raw True/False/Number tokens into "true"/"false"/decimal-string so MikroTik fields that occasionally come back as a raw number (e.g. pvid) still bind to a string? property.

Entity base (Entities/MikrotikEntity.cs, internal abstract): real impl. Two writable string properties - [JsonPropertyName(".id")] string? Id (literal MikroTik wire key ".id", dot-prefixed - non-negotiable) and [JsonPropertyName("name")] string? Name. Both nullable - new entities pre-PUT have Id == null, families without a name field leave Name == null. Concrete entities (task 4) inherit this base + add family-specific string?/bool?/int?/long? properties with [JsonPropertyName("kebab-case")] where MikroTik’s wire key diverges from C# PascalCase.

Repository base (Repositories/MikrotikRepositoryBase<T> : IMikrotikRepository<T> where T : MikrotikEntity, internal abstract): real impl. Concrete subclasses only override abstract string ResourcePath (e.g. "interface/bridge"). GetAllAsync delegates HttpClient.GetAsync<T>(ResourcePath, ct); GetAsync(id, ct) → HttpClient.GetSingleAsync<T>(ResourcePath + "/" + id, ct). Add/Set/Delete buffer PendingOperation records into a List<PendingOperation>; IsDirty == Pending.Count > 0. FlushAsync(ct) iterates pending ops in insertion order: Add → PutAsync (returns saved entity, Applied[] captures saved.Id ?? ""), Set → PatchAsync(ResourcePath, op.Id, body), Delete → DeleteAsync(ResourcePath, op.Id). Per-op try/catch over Exception captures into MikrotikFlushFailure(Id, Error); Pending.Clear() runs unconditionally after the loop. Result type MikrotikFlushResult(IReadOnlyList<string> Applied, IReadOnlyList<MikrotikFlushFailure> Failed). Pending op carries PendingOperationKind enum (Add | Set | Delete) + id (empty string for Add until device assigns) + nullable object? body. No retry, no rollback - caller decides via Applied/Failed split. GetAllAsync + Add + Set + Delete are virtual so singleton + read-only subclasses can override.

Entities + repositories (17 resource families): all internal sealed. Entities inherit MikrotikEntity and decorate properties with [JsonPropertyName("kebab-case")] where the MikroTik wire key diverges. The catalog (with REST paths + kebab keys + repo kind): Bridge (interface/bridge, vlan-filtering, protocol-mode); BridgePort (interface/bridge/port, bridge, interface, pvid, tagged); BridgeVlan (interface/bridge/vlan, bridge, tagged, untagged, vlan-ids); RouterInterface (interface - renamed to dodge the C# keyword clash; type, default-name, disabled, running, mac-address); Bonding (interface/bonding, slaves, mode, transmit-hash-policy, lacp-rate); IpAddress (ip/address, address, network, interface, disabled, comment); IpRoute (ip/route, dst-address, gateway, distance, comment); DhcpServer (ip/dhcp-server, interface, disabled, address-pool); DhcpLease (ip/dhcp-server/lease, address, mac-address, comment, disabled); DnsSettings SINGLETON (ip/dns, servers, allow-remote-requests); FirewallNatRule (ip/firewall/nat, chain, action, out-interface, in-interface, in-interface-list, disabled, comment); FirewallFilterRule (ip/firewall/filter, chain, action, protocol, dst-port, in-interface, in-interface-list, comment, disabled); WifiConfiguration (interface/wifi, ssid, country, channel, security); WifiSecurity (interface/wifi/security, authentication-types, passphrase); User (user, password, group); SystemIdentity SINGLETON (system/identity, hostname via inherited Name); SystemResource SINGLETON + READ-ONLY (system/resource, platform, board-name, version, uptime, free-memory : long?, total-memory : long? - Add/Set/Delete throw NotSupportedException). Singleton repos override GetAllAsync to wrap the single object in a one-entry array. Repository <→ Contracts spec name drift to bridge in the mapper (task 6): Bridge.Protocol → protocol-mode vs spec VlanFiltering (spec keeps only Name + VlanFiltering); BridgePort.Tagged (entity, literal wire key) vs BridgePortSpec.TaggedVlans (caller-friendly semantic).

Unit of work (UnitOfWork/IMikrotikUnitOfWork + MikrotikUnitOfWork, internal): real impl. Exposes one IMikrotikRepository<T> getter per resource family (17 props), all backed by a single MikrotikHttpClient injected in the ctor. CommitAsync(ct) iterates the 17 repos in declaration order via a private FlushIfDirtyAsync<T> helper: skips repos with !IsDirty, otherwise awaits FlushAsync and appends to the result list. Sequential (never parallel - shared HttpClient + MikroTik’s REST engine misorders rapid PATCH bursts). Caller is responsible for dependency ordering inside the desired state (bridges before bridge ports, etc.). Result is MikrotikCommitResult(IReadOnlyList<MikrotikFlushResult> Results) with HasFailures ⇒ Results.Any(r ⇒ r.Failed.Count > 0). Empty Results (no repos were dirty) != failure.

Data store + reference (DataStore/, all internal): real impl. MikrotikDataStore : IMikrotikDataStore, IDisposable is the canonical HttpClient owner - production ctor (MikrotikConnection) builds a fresh MikrotikHttpClient(connection, NullLogger.Instance) + a MikrotikUnitOfWork(httpClient) and disposes the HttpClient on Dispose() (idempotent via _disposed flag). Internal test-seam ctor accepts a pre-built HttpClient for FakeHttpMessageHandler. MikrotikDataStoreReference : IMikrotikDataStoreReference carries a MikrotikConnection and a Func<MikrotikConnection, MikrotikHttpClient> factory (defaults to new MikrotikHttpClient(connection, NullLogger.Instance); internal ctor lets tests inject). ExistsAsync(ct) probes GET /rest/system/resource via a throw-away HttpClient (using var http = _httpFactory(_connection)), returns true on any successful deserialization, false on any Exception (auth failure, timeout, JSON parse, cancellation - all reduce to "not reachable"). OpenDataStore() builds a fresh HttpClient + MikrotikDataStore (caller owns disposal). MikrotikDataStoreReferenceProvider is a stateless factory returning a new reference per call. Provider’s GetReference return type tightened from object to IMikrotikDataStoreReference in this commit.

Entity mapper (Mapping/MikrotikEntityMapper, internal static): real impl. 32 static methods - one ToEntity(XxxSpec) + one ToSpec(Xxx entity) per family for 16 spec families (SystemResource excluded - read-only, no Spec counterpart). Mechanical copy-property-to-property, no business logic. ToEntity projects spec record positionals to entity nullable properties as-is. ToSpec collapses entity nullables to spec record positionals via entity.X ?? string.Empty / entity.X ?? false / entity.Pvid ?? 0 (spec records are non-nullable positional records). The notable bridge: BridgePortSpec.TaggedVlans <→ BridgePort.Tagged (semantic spec name vs literal wire-key entity property). Bridge.Protocol is NOT in BridgeSpec and does not round-trip - the mapper writes nothing for it; future extension is additive.

Converge orchestrator (MikrotikConverge, internal sealed : IMikrotikConverge): real impl, replacing the scaffold-time NotImplementedException stub. Ctor takes IMikrotikDataStoreReferenceProvider + ILogger<MikrotikConverge>. RunAsync flow: (1) Precondition.NotNull on connection + desired; (2) reachability gate via reference.ExistsAsync(ct) → if false, log warning + return MikrotikConvergeResult(Reachable=false, Deltas=Array.Empty); (3) using var store = reference.OpenDataStore() → 16-repo UoW; (4) 16 RunResourceAsync(label, () ⇒ ConvergeXxxAsync(…​)) calls in fixed declaration order (Bridge → BridgePort → BridgeVlan → Interface → Bonding → IpAddress → IpRoute → DhcpServer → DhcpLease → FirewallNatRule → FirewallFilterRule → WifiConfiguration → WifiSecurity → User → Dns → SystemIdentity), each captured into the deltas list; (5) uow.CommitAsync(ct) wrapped in try/catch (warn + swallow on failure); (6) return MikrotikConvergeResult(true, deltas.ToArray()) with all 16 entries. RunResourceAsync<T> is the per-resource isolation seam: catches every Exception, logs warning with the family label, returns MikrotikResourceDelta(label, 0, 0, 0) so failures appear as zero-delta entries (3-layer failure pattern: per-op via FlushAsync.Failed, per-family via RunResourceAsync, global commit via the outer try/catch). Match keys per family: Name for Bridge/Interface/Bonding/Wifi*/User/DhcpServer; composite Bridge+Interface for BridgePort; composite Bridge+VlanIds for BridgeVlan; Address for IpAddress; composite DstAddress+Gateway for IpRoute; MacAddress (case-insensitive!) for DhcpLease; composite Chain+Comment for Firewall*; FirstOrDefault for Dns/SystemIdentity singletons. Delete safety guard via private const string NetsetupPrefix = "netsetup-" + IsNetsetupManaged(label): only 5 families have a delete loop (Bridge, Bonding, IpAddress, FirewallNatRule, FirewallFilterRule) and they only delete entries whose Name or Comment starts with netsetup- - manually-created MikroTik resources NEVER get touched. Singleton converges (ConvergeDnsAsync + ConvergeSystemIdentityAsync) treat null desired spec as a no-op zero-delta (so non-Liberator hosts can leave MikrotikDesiredState.Dns = null and SystemIdentity = null and the family is visited but does nothing). Interface and DhcpServer converges are Set-only (no Add path - device boots with a fixed set, converge toggles Disabled). IpRoute, FirewallFilterRule, WifiSecurity, User are Add-only (no Set, no Delete - reflects Liberator cutover semantics).

osisa.Mikrotik library is FEATURE-COMPLETE for adoc tasks 1-6 (Contracts + transport + JSON + entity catalog + UoW/DataStore + mapper + converge). NETSetup-side tasks 7 (credentials parser) + 8 (desired-state builder) + 9 (converge bridge + EnsureCustomerVms wire-in) are also done. All 9 RALPH tasks landed - feature COMPLETE. Single known follow-up: the task 9 wire-in chose EnsureCustomerVms.Run (paired with OpnsenseConvergeBridge.Run at lines 177-182) instead of the adoc-spec "explicit Phase 3e step 4 in RunProxmoxUpdate`" - operationally equivalent today since `EnsureCustomerVms runs inside RunProxmoxUpdate; revisit if/when explicit ConfigureProxmoxBridges + RewireVmNicsToVlans helpers are added.

NETSetup credentials parser (src/NETSetup/Helpers/MikrotikApiCredentials.cs, public static): real impl. public const string ApiEnvPath = "/etc/netsetup/mikrotik-api.env". TryLoad() → MikrotikConnection? reads the env file via (AbsolutePath)ApiEnvPath + path.FileExists()/path.ReadAllText() (osisa IO conventions); returns null if the file is missing. Parse(string) → MikrotikConnection? is a pure helper: empty/whitespace content returns null; per-line iteration over Split('\n', RemoveEmptyEntries) with Trim() strips CRLF, skip-on-blank-or-#, split on first =, value gets Trim('"') to support KEY="value" shell-style env files. Recognized keys: MIKROTIK_URL, MIKROTIK_USER, MIKROTIK_PASSWORD. Unknown keys silently ignored (forward-compat). Missing required key THROWS NETSetupException("<KEY> missing in mikrotik-api.env") - intentional divergence from OpnsenseApiCredentials (returns null on incomplete) because a present-but-malformed file means flash-mikrotik wrote it wrong, which is a real bug to surface. The resulting MikrotikConnection.AllowSelfSignedCertificate keeps its default true. NETSetup.csproj has a ProjectReference to osisa.Mikrotik.csproj enabling Contracts visibility. 10/10 tests green in MikrotikApiCredentialsTests covering valid parse + 3 missing-key throws + comments + quoted values + empty content + nonexistent file + unknown extra keys.

NETSetup converge bridge (src/NETSetup/Helpers/MikrotikConvergeBridge.cs, public static): real impl, FINAL task. public static void Run(ISystemHost host, NETSetupConfig config, IServiceProvider? services = null). Synchronous (.GetAwaiter().GetResult() on IMikrotikConverge.RunAsync) to match the synchronous EnsureCustomerVms flow. Best-effort: every failure path log + swallow, NEVER throws past the catch-all Exception handler. Phases: (1) ArgumentNullException on null host/config; (2) CredentialsProvider() (defaults to MikrotikApiCredentials.TryLoad, internal static Func<MikrotikConnection?> test seam) - null → info log "creds not found" + return; (3) LiberatorGate.IsFullLiberatorFlow(host, config) ? "Liberator" : "" + MikrotikDesiredStateBuilder.Build(config, hostDescription); (4) private IsEmptyState 4-property heuristic (Bridges.Length == 0 && SystemIdentity is null && WifiConfigurations.Length == 0 && Users.Length == 0) → info log "skipping …​ empty desired state" + return; (5) ResolveConverge(services) (DI lookup → fallback to self-built ServiceCollection with AddLogging() + AddMikrotik() if IMikrotikConverge not registered); (6) inside try: converge.RunAsync(connection, desired).GetAwaiter().GetResult() → !result.Reachable → warn "unreachable" + return, otherwise iterate result.Deltas info-logging "MikroTik converge {Resource}: +{Added}/~{Updated}/-{Deleted}"; (7) catch-all Exception → warn "converge threw - continuing" with exception attached. The LiberatorGate check lives INSIDE the bridge body (caller minimalism - EnsureCustomerVms calls unconditionally). Wired into src/NETSetup/Helpers/EnsureCustomerVms.cs at lines 177-182, immediately after OpnsenseConvergeBridge.Run, NOT inside RunProxmoxUpdate as the adoc spec suggested - the two REST-converge bridges paired side-by-side is more discoverable, and operational cadence is identical because EnsureCustomerVms itself runs inside RunProxmoxUpdate. 8/8 tests green covering null-creds skip, non-Liberator empty-state skip, unreachable warn, exception swallow, DI-vs-fallback ResolveConverge.

NETSetup desired-state builder (src/NETSetup/Helpers/MikrotikDesiredStateBuilder.cs, public static): real impl. Pure mapper, zero IO. public const string ManagedPrefix = "netsetup-" (matches delete-safety prefix) + public const string DefaultIdentityName = "Lib_AP". Build(NETSetupConfig config, string hostDescription) → MikrotikDesiredState. Non-Liberator (anything other than literal "Liberator" with StringComparison.Ordinal) returns new MikrotikDesiredState() = all-empty arrays + null singletons (no-op converge). Liberator branch emits the recipe: Bridges = [BridgeSpec("bridge1", "yes")] (VLAN filtering on, non-prefixed well-known name); BridgePorts 4 entries (ether2 + ether3 trunk with Pvid=1 + tagged "10,20,250,254"; ether4 + ether5 access with Pvid=20 + empty tagged); BridgeVlans 4 entries (VLAN 10/20/250/254 on bridge1, tagged on ether2+ether3, VLAN 20 also untagged on ether4+ether5); IpAddresses = [IpAddressSpec("10.0.250.1/24", "bridge1", "netsetup-mgmt")]; DhcpServers + FirewallNatRules + FirewallFilterRules empty (OPNsense owns DHCP/NAT/filter); WifiConfigurations 3 entries on wifi1/wifi2/wifi3 for SSIDs Liberator + Liberator-Guest + admin-oob-lib, country CH, channel 2ghz-onlyn,5ghz-ax / 2ghz-onlyn / 5ghz-ax, each Security field referencing a WifiSecuritySpec.Name; WifiSecurities 3 entries with PSK profiles (wpa2-psk,wpa3-psk for Liberator + open for Guest + wpa3-psk for admin-oob), passwords from config.LiberatorWifiPassword + config.MikrotikAdminPassword (null → empty placeholder); Users = [UserSpec("admin", adminPassword, "full")]; SystemIdentity = new SystemIdentitySpec(config.SelectedHostname ?? "Lib_AP"). New NETSetupConfig fields (added in this commit): LiberatorWifiPassword + MikrotikAdminPassword (both public string?; latter doubles as admin user pw AND admin-oob-lib WPA3 PSK - single source of truth). Adoc-spec drift: spec mentioned MachineName.Value, impl uses the real NETSetupConfig.SelectedHostname field. 18/18 tests green.

UPDATE (2026-05-29, dual-WAN inbound): the desired-state builder no longer leaves FirewallNatRules + FirewallFilterRules empty for inbound published services - it now emits per-ServedPort netsetup-dnat-{port} dst-nat + netsetup-allow-{port} forward-accept rules. New const MikrotikDesiredStateBuilder.WanInterfaceList = "WAN". Those rules set InInterfaceList = "WAN" with EMPTY InInterface (NOT literal ether1). Reason: behind an XGS-PON modem the WAN arrives tagged on VLAN 10 so ingress is ether1-vlan10, not ether1; an ether1-pinned port-forward would never match and inbound mail/nextcloud would be dead. Matching the WAN interface-list (which holds BOTH ether1 + ether1-vlan10) fires the rule on whichever iface carries the WAN. osisa.Mikrotik gained InInterfaceList on FirewallNatRuleSpec + FirewallFilterRuleSpec (+ entities + mapper + NAT drift-check). DEPENDENCY: the converge REFERENCES the WAN list but does NOT create it - it relies on the flash-mikrotik .rsc (MikrotikRscBuilder, new const WanVlanId = "10") having created the WAN interface-list + both members + a dhcp-client on each iface. Flash-then-update is the normal order. (OPNsense still owns the per-VLAN DHCP + outbound NAT + inter-VLAN filter; only the inbound published-service port-forwards live on the Mikrotik.)

Tests: 213 green (42 in `94c3e555`). Contracts + records (Connection, DesiredState, ConvergeResult, ResourceDelta, all 16 spec records, exception) + consolidated `MikrotikContractsTests` for DI + serialization shape. `MikrotikHttpClientTests` covers Basic auth header, 4xx/5xx -> exception mapping, JSON read-write round-trip, self-signed-cert toggle. `MikrotikStringConverterTests` covers raw-and-quoted Read and always-quoted Write per primitive. `MikrotikEntityTests` covers `.id` + `name` JSON round-trip and nullable defaults. `MikrotikRepositoryBaseTests` covers IsDirty transitions, GetAll/Get routing, FlushAsync verb dispatch (Add->PUT/Set->PATCH/Delete->DELETE), partial-fail capture (continue on per-op exception, Applied vs Failed split), Pending unconditional clear, empty-batch no-op. `MikrotikFlushResultTests` covers the result + failure record shapes. `MikrotikRepositoriesTests` (+32 in `d9af2b05`) asserts 17 `ResourcePath` strings + per-family entity JSON deserialization through `MikrotikStringConverter` (kebab-case keys, bool/long round-trip) + singleton-wrap behaviour for Dns/SystemIdentity/SystemResource + read-only `NotSupportedException` guard for SystemResource Add/Set/Delete. `MikrotikUnitOfWorkTests` ( in 311e7421) covers 17-repo getter non-null + CommitAsync with 0/1/3 dirty repos + sequential flush order + HasFailures propagation. MikrotikCommitResultTests covers HasFailures computation across mixed inner outcomes. MikrotikDataStoreReferenceTests covers ExistsAsync true on 200, false on refused/401/timeout/non-JSON, OpenDataStore returns a usable store, factory seam exercised. MikrotikServiceCollectionExtensionsTests asserts AddMikrotik registers IMikrotikConverge + IMikrotikDataStoreReferenceProvider as singletons (idempotent on multiple calls). MikrotikEntityMapperTests (+ in 94c3e555) covers ToEntity/ToSpec round-trip per family + null projection (string → "", bool → false, int → 0) + the BridgePortSpec.TaggedVlans <→ BridgePort.Tagged drift bridge. MikrotikConvergeTests (+ in 94c3e555) covers reachability-false short-circuit, golden-path mixed Add/Set/Delete, per-resource failure isolation (one family throws, others still run with correct deltas), netsetup--prefix delete safety, singleton Dns/SystemIdentity Set behaviour, null desired Dns = no-op zero-delta, all 16 families appear in the result. PhysicalMikrotikIntegrationTests (17 tests, Skip = "Requires a physical MikroTik device.") runs manually against a real hAP ax2 during commissioning - NOT executed in CI. TestInfrastructure/FakeHttpMessageHandler.cs route-keyed (mirrors osisa.OPNSense.Tests); TestInfrastructure/TestValues.cs hosts shared constants. (Test agent renamed the auth-header property assertion AuthHeader → AuthorizationHeader to match the shipped name.)

Is there already a UnitOfWork pattern here? YES - and it is reused, not reinvented. ISystemManagementUnitOfWork (ships in osisa.SystemManagement.Windows, built on DataStoreReferenceBase5 + DataStoreNameDependencyInjectionDataStoreReferenceBuilder5 + CanGetSingleUnitOfWorkDataStoreReferenceBase) is already consumed in this repo - see NETSetup.Tests/ExeTests/GetTests.cs and NETSetup.Tests/UEFIDriverTests.cs:

var provider = new MachineScopeProvider();
var dataStoreReference = provider.GetReferences().First();
var dataStore = dataStoreReference.OpenDataStore<ISystemManagementUnitOfWork>();
var unitOfWork = dataStore.GetUnitOfWork();
var repository = unitOfWork.GetRepository<IDisk>();
var disks = repository.ReadAll();

Suggested UnitOfWork interface - deliberately mirrors ISystemManagementUnitOfWork so the two read identically at the call site:

namespace osisa.VirtualMachines.Contracts;

/// <summary>
/// Unit of work over one virtualisation environment. The environment (Hyper-V scope,
/// Proxmox node) is the data store; a virtual machine is a record.
/// </summary>
public interface IVirtualizationUnitOfWork : IUnitOfWork
{
    /// <summary>Virtual machines in this environment. Insert / Update / Delete are buffered
    /// until <see cref="IUnitOfWork.Commit"/>.</summary>
    IVirtualMachineRepository VirtualMachines { get; }
}

/// <summary>Full-CRUD repository of virtual machines.</summary>
public interface IVirtualMachineRepository : IGenericRepository<VirtualMachineSettings>
{
    // inherits ICanRead / ICanInsert / ICanUpdate / ICanDelete<VirtualMachineSettings>
}

AddReference2 → the real API is AddReference3<TBuilder>(Action<TBuilder>) on DataStoreReferenceProvider3.Builder. osisa.Repository exposes exactly two: AddReference(Func<IServiceProvider, ICanGetAnyUnitOfWork>) (Shape A) and AddReference3<TBuilder>(Action<TBuilder>) (Shape B). There is no AddReference2. Both providers are registered on one builder, one call each:

_inner = new DataStoreReferenceProvider3.Builder(services)
    .AddReference3<HyperVVmDataStoreReference5.Builder>(b => b
        .WithDataStoreName(LocalHyperVStoreName)
        .WithManagementScope(LiveMethods.ConnectToLiveLocalSystem(@"root\virtualization\v2")))
    .AddReference3<ProxmoxVmDataStoreReference5.Builder>(b => b
        .WithDataStoreName(OsisaLib03StoreName)
        .WithHost(proxmox.GetHost(OsisaLib03StoreName)))
    .Build();

New projects: src/osisa.VirtualMachines/ + src/osisa.VirtualMachines.Tests/, both added to src/NETSetup.sln. Target $(DefaultNetTargetFramework). Test project name is {Source}.Tests - capital T, plural s - per netbase convention. Precedent to mirror for the library shape: osisa.Mikrotik (Contracts-only public surface, internal repositories/UoW/DataStore, InternalsVisibleTo for its .Tests).

Provider = environment. Two real providers plus one in-memory provider:

Provider constants live in NETSetup, NOT in netbase: WellKnownDataStoreProviders ships Sqlite/SqlServer/Memory/Mock/Excel/Postgres/Rest only. Add NetsetupDataStoreProviders (public static class) with HyperV, Proxmox, MemoryVm string constants, used by [DataStoreProvider(…​)] on each reference.

VirtualMachineSettings is a projection, not a competitor, of osisa.SystemManagement.Contracts.Interfaces.IVirtualMachine - the read-model both hypervisor libraries already share. A flat provider-neutral record is what lets one repository, one UoW and one test base span Hyper-V and Proxmox; the native types stay behind the operations seam.

Record identity: keyed by SerialNumber ({VMID}@{HostSerial}), NOT by MachineName. The serial is the already-existing primary key of the NETSetup VM model (CreateVirtualMachines.IsForHost parses it) and it survives a rename; a name change must read as an Update, not Delete + Insert. VirtualMachineKey is a Vogen VO wrapping the serial string. For a VM discovered on a host that carries no NETSetup serial (hand-created), the key falls back to {VmId}@{HostName} so ReadAll never drops a record it cannot name.

Change buffering (batch-then-commit, same as MikrotikUnitOfWork): Insert/Update/Delete mutate an in-memory pending list and flip IsDirty; nothing touches the hypervisor until Commit(). NoCommit therefore genuinely means "the VM was never touched" - that is the assertion that proves the transaction boundary is real. ReadAll is always live and unbuffered.

Commit ordering is fixed and asserted: Delete first, then Update, then Insert. Deleting before inserting frees vmids and MACs for the inserts in the same commit; inserting last means a failed insert cannot orphan a half-updated VM.

Update == stop → change → restart is the core semantic and is modelled explicitly, not implied:

VmCommitResult (public record) carries IReadOnlyList<VmOperationRecord> Operations (Key, Operation, Ordinal) plus Inserted/Updated/Deleted counts and Failed keys. Tests assert on this list - it is the observable proof of stop/change/restart.

Provider mapping of the six operations. No new hypervisor code - every verb already exists in the shipped libraries:

Test targets, from the existing in-repo infrastructure - do not invent new ones:

How "the correct VM count" is asserted. The count is environment-dependent, so a hard-coded number would be a false green on any other box. The oracle is the native API of the same provider: the DataStore count must equal scope.ReadAllVirtualMachines().Count() (Hyper-V) resp. pveHost.GetVirtualMachines().Count() (Proxmox). One abstract ExpectedVmCount on the base, one line in each derived class. The base additionally asserts the count is > 0 (an empty result would satisfy an equality-only oracle trivially) and TestContext.WriteLine`s every VM name so the run is diagnosable. Both live classes carry `[TestCategory("local")] and Assert.Inconclusive when their environment is absent - the suite must stay green on a build agent with no Hyper-V and no route to 192.168.3.233.

Commit() is fail-fast per record but aggregating across records: a failing record records its partial operations, is added to VmCommitResult.Failed, and the loop continues; Commit() throws VmDataStoreException at the end listing every failed key - same contract as EnsureCustomerVms.RunCore, so a future wire-in is a drop-in.

VmDesiredStateBuilder (NETSetup side, public static, pure, zero IO) reuses CreateVirtualMachines.GetOrderedVmsForHost verbatim so desired-state ordering (OPNsense → DC → rest → NixDns last) stays the same single source of truth as today’s provisioning order. No duplicated ordering logic.

VmDataStorePlanner (NETSetup side, public static, pure, zero IO) diffs desired vs live. Delete safety guard, mirroring MikrotikDesiredStateBuilder.ManagedPrefix: a live VM is only ever proposed for deletion when its serial is hosted on this host (CreateVirtualMachines.IsForHost). A hand-created VM, or one belonging to another host, is never in Deletes. VmChangePlan has no Apply in this iteration - the planner is read-only by design, and that is what keeps the spec behaviour-neutral.

No System.IO, no raw Process: AbsolutePath + PhysicalFileOperator and the NETCommand builders, per repo convention.

Test packages for src/osisa.VirtualMachines.Tests/: osisa.Repository, osisa.Repository.Contracts, osisa.Repository.TestInfrastructure, osisa.Domain.Mock, osisa.Specifications, osisa.TestInfrastructure, osisa.TestInfrastructure.Contracts, osisa.Hosting.TestInfrastructure, osisa.SystemManagement.HyperV, osisa.SystemManagement.Proxmox, MSTest + FluentAssertions. RISK: osisaRepositoryVersion is pinned at 0.19.0-ModelFeature.191 while the restored osisa.Repository.TestInfrastructure carrying DataStoreReference5TestBase is 0.19.0-ModelFeature.292+. If .191 does not ship DataStoreReference5TestBase, bump osisaRepositoryVersion to the netbase-current 0.19.0-ModelFeature.292 in one isolated commit and re-run the full suite BEFORE starting task 9.

Test values: src/osisa.VirtualMachines.Tests/TestInfrastructure/TestValues.cs with Some* constants only (SomeVmName, SomeOtherVmName, SomeHostSerial, SomeVmSerial, SomeMemoryBytes, SomeUpdatedMemoryBytes, SomeCoreCount, SingleItemCount, TwoItemCount, SixOperationCount, …​). No Value, no Integer1.

IPermanentDeletions<TEntity> left this repo. It now ship in netbase osisa.Repository.Contracts/Repositories/, derive IRepositoryBase<TEntity>, and keep the same two member (ReadSoftDeleted() + ExecutePermanentDeletionsAsync(ct)). The old osisa.Virtualization/Repositories/IPermanentDeletions[TEntity].cs is DELETED; consumer only repoint the using. Reason: a two-step deletion is a repository capability, so a netbase TEST BASE can gate on it - which is impossible while the interface live in a consumer library. Semantics unchanged, see the netsetup root NETSetup.adoc section "Deletion is two steps".

CRUD suites moved v3 → v4. Netbase gained UnitOfWorkRepositoryTestsBase4[…​] plus the […​,TKey] keyed variant: v3 plus SIX soft-delete case, gated on RepositorySupportsPermanentDeletions. VirtualMachineRepositoryCrudTestBase2 (and with it the HyperV + Proxmox live suites) sit on v4 now - 8 → 14 case per provider suite. ReadSoftDeletedCount() and ExecutePermanentDeletions() are virtual because a live hypervisor is a SHARED store; the base override both and filter through IsOwn, and the destroy route through the existing ExecuteOwnDeletions guard, which go Assert.Inconclusive rather than destroy a guest the suite did not create. New tests + a fake cover the contract in osisa.Repository.Contracts.Tests. NETConfigDataStoreTests2 deliberately STAY on v3: its store is JSON-backed, so the six cases would mark and destroy a config entry, not a guest.

BEHAVIOUR: Hyper-V firmware is now decided by the row OS and applied AT CREATION. New Operations/HyperVFirmware.cs + a changed HyperVVmOperations: a Windows-family row is created with Secure Boot ON and a vTPM, anything else with both OFF, passed as the VirtualBIOS constructor argument. Both halves are needed - Windows 11 demand the pair, and the Microsoft UEFI CA reject the unsigned nixos ISO the moment Secure Boot is on. New Contracts/OperatingSystemExtensions.Is(this OperatingSystem, OperatingSystemFamily) is the one place that answer "is this a Windows row".

BEHAVIOUR: osisa.OPNSense.Rest/UnitOfWork/FirewallGroupsUnitOfWork3.cs ported. Netbase UnitOfWorkBase3 take an ILogger instead of an ITransaction3 and declare an abstract OnCommit(); the transaction is HELD by the unit of work and flushed in OnCommit. This is the port the version hold recorded below (see the 2026-08-24 audit entry) said would be needed - it is done, and the hold in src/Directory.Packages.props is released.

PACKAGE VERSIONS in both repo currently point at LOCALLY PACKED builds. They are local-only and must not be committed, so no version number is written here - a doc that name an unpublished package send the next reader to a feed that does not have it.

BEHAVIOUR: Stages/0-Iso/S5NETSetupDev.UpdateISO fixed. Two defects, both of which produced a SILENT bad outcome:

A live suite that provision an INSTALL guest must disable ballooning / dynamic memory. WinPE have no balloon driver, so the guest get squeezed and the DISM apply HANG at zero bytes rather than fail. VirtualHyperVTestBase today call DisableDynamicMemory only for non-Windows rows - and a Windows row install through WinPE just the same, so the OS gate is the wrong gate.

The vTPM measurement behind the firmware change above. Enabling a vTPM after the guest have state give 0xC000A002 STATUS_AUTH_TAG_MISMATCH and is unrecoverable - already stated in the firmware bullet, repeated here because it is what makes "AT CREATION" non-negotiable.

DEFECT, creation path: default cpu=x86-64-v3 cannot start on a host without AVX2. osisaLib03 lack avx2/bmi1/bmi2/fma/movbe/abm and QEMU exit code 1. ProxmoxWindowsVmFactory, ProvisionNixosVm and ProxmoxVmOperations already override to host; any NEW creation path must, or the guest is created and never start.

CreateVirtualMachine can return true while qmcreate failed. The failure surface later as Failed to find VirtualMachine …​ Sequence contains no matching element from the round-trip read

devboxiso is the reason a Proxmox Win11 test take seconds. It is a CIFS mount of the dev box NETSetupISO share whose template\iso is a junction to C:\NETSetupDEV, so the host REFERENCE the 11.9 GB ISO. Offline → no guest can be created, and uploading is not a fallback (0.15 MB/s measured, ~20 h).

A [TestCategory("Prod")] test report GREEN having run nothing. src/Test.Build.props force local.runsettings, whose TestCategory!=Prod filter apply at DISCOVERY, so the method is never enumerated and an inherited base-class case pass instead. Use --settings src/prod.runsettings, and FullyQualifiedName~ (not Name=) because these methods are [DataRow]-driven. Any Prod result quoted in this file must have been produced that way.

Code landed in src/NETSetup/DataStore/ + src/NETSetup/Exceptions/VmDataStoreException.cs; test in src/NETSetup.Tests/DataStoreTests/. NOT a separate osisa.VirtualMachines project - NETSetup already reference osisa.SystemManagement.HyperV + .Proxmox, so only three PackageReference (osisa.Repository, osisa.Repository.Contracts, osisa.Specifications.Contracts) were added and no sln entry was needed. Splitting the library out stay a follow-up.

Reference base is CanGetSingleUnitOfWorkDataStoreReferenceBase<VmConnectionStringBuilder, TSelf, IVirtualizationUnitOfWork> (shared VmDataStoreReferenceBase<TSelf>), NOT DataStoreReferenceBase5 direct - a VM store serve exactly ONE unit of work type, which is the same reason MachineScopeReference5 use that base.

Builders are plain nested Builder class, not DataStoreNameDependencyInjectionDataStoreReferenceBuilder5: that base demand SetDataStore + DI plumbing this store does not need, and the live handle (management scope, Proxmox host) is injected, never serialised.

VirtualizationDataStoreReferenceProvider3 wrap each single-UoW reference in the netbase SingleAsAnyUnitOfWorkDataStoreReference<IVirtualizationUnitOfWork> so GetReferences() satisfy IDataStoreReferenceProvider3. AddReference2 does not exist in osisa.Repository - see the decision above.

VirtualMachineKey is a plain string on the record for now, not a Vogen VO. Vogen wrapping is a follow-up and does not change any signature above.

KEY DERIVATION BUG FOUND AND FIXED live: SerialNumber.From("9000@osisaLib03") yield Value == "osisaLib03" and HostedId == "9000" - the vmid is SPLIT OFF. Keying on .Value collide every NETSetup VM on a node onto one key. A hosted serial must be REASSEMBLED as {HostedId}@{Value}. Non-hosted guest report a hardware serial, "0" or "empty" (all non-unique), so they key on the node-qualified VM name instead. Hyper-V has no vmid and no unique BIOS serial, so it always key on the scope-qualified name. ReadAll_ShouldReturnUniquelyKeyedRecords is what caught it.

Still open from the task list below: the in-memory provider (task 4), the cross-provider GetReferences() walk (task 9), the netbase DataStoreReference5TestBase / UnitOfWorkRepositoryTestsBase3 suite (task 10), the stop-change-restart semantics test (task 11), VmDesiredStateBuilder (task 12), VmDataStorePlanner (task 13), the neutrality regression test (task 14) and the doc/puml task (task 15). Nothing in the landed code is called from netsetup update, so behaviour is unchanged by construction.

HOLDS, verified line by line. Insert/Update/Delete only Enqueue into _pending. All five mutating seam call (InsertAsync, DeleteAsync, StopAsync, ChangeAsync, StartAsync) live inside FlushAsync/ApplyUpdateAsync, and FlushAsync have exactly ONE caller repo-wide: CommitAsync. FlushAsync and Rollback are deliberately NOT on IVirtualMachineRepository, so no consumer can flush without committing. Read is live and unbuffered by design - a pending insert is invisible to ReadAll until commit, declared on the contract.

NOT PROVED BY DERIVING netbase UnitOfWorkRepositoryTestsBase3, which is what this repo normally use. Environment blocker, not a choice: osisaRepositoryVersion is pinned at 0.19.0-ModelFeature.191, NO csproj in netsetup consume osisa.Repository.TestInfrastructure so that version was never pulled into the local NuGet cache, and the GitHub Packages feed answer 403 without credential. VersionOverride to .300 fail too - its transitive osisa.Json / osisa.Strings at .300 are equally absent. DO NOT fix this by bumping osisaRepositoryVersion: this file record that .292 change the UnitOfWorkBase3 ctor and require porting osisa.OPNSense.Rest, and that the last attempt measured 188 build error and 0 runnable test. The real fix is a read:packages token plus a single PackageReference at .191 - every .191 transitive dep is already cached.

IN ITS PLACE VirtualMachineRepositoryCrudTests mirror the six base case test-for-test (Insert/Update/Delete x Commit/NoCommit), assert on READ-BACK STATE the way the base do, and add CommitAsync variant, an all-three-verbs-uncommitted case and the dispose case. Shaped so swapping to the real base is mechanical.

MUTATION TESTED, twice, because a guard nobody has seen fail is not a guard. (1) Making Insert apply immediately turn 8 test red. (2) Emptying Rollback() originally left ALL 48 GREEN - the two dispose test could not fail, one verifying through a fresh unit of work owning a different buffer, the other only asserting the fake had recorded nothing. Dispose_ShouldClearTheBufferItself assert the buffer directly and now catch it.

CommitAsync now refuse a DISPOSED unit of work (ObjectDisposedException). It used to flush, inert only as a side effect of Rollback clearing.

ChangeAsync DEFECT, fixed by refusing rather than pretending. Both provider apply NO field. Driven through the update path that mean: stop the guest, change nothing, restart, report Updated++ for work never done - and since nothing was applied the same difference persist, so EVERY reconciliation bounce the guest again. IVirtualMachineOperations.CanApplyChanges now declare the capability, both provider return FALSE, and the repository refuse the update BEFORE StopAsync. The ORDER is the point: throwing from inside ChangeAsync would leave the guest POWERED OFF, because a per-record failure is caught and the restart never run. Same rule the provider already follow for NetworkName / Storage / VmId - a provider that cannot honour a field say so instead of silently dropping it.

KNOWN LIMIT of the unit suite: the fake DOES apply a change, so Update_Commit_ShouldApplyTheChange prove the REPOSITORY buffering, never a provider’s CRUD. No provider apply fields yet, so there is nothing to prove on that side until ChangeAsync is implemented.

KEY MATCHING, round 3+4: a row built by VirtualMachineBuilder carry no key, and that is the NORMAL update path. Matching it needed three corrections. (1) The builder used to invent From(name), a third key shape no provider project - removed. (2) A name-based fallback compared case-SENSITIVELY (MachineName do not normalise) while the key path did not - removed. (3) Matching only the projected key missed every Proxmox guest carrying a NETSetup serial, because those project FromSerial while a keyless row key as env/name. Final shape: ResolveLive RE-KEY every live row as FromEnvironment(EnvironmentName, r.Name) and compare that, so there is ONE comparison and it is always a normalised VirtualMachineKey. Comparing the projected key as well would be dead code - a serial never contain the separator a re-keyed name always has.

MATCHING DEPEND ON UNIQUE NAMES. Proxmox do not enforce unique guest name, so the live suite assert ReadAll_ShouldReturnUniquelyNamedRecords alongside the key assertion. Two guest sharing a name on one node would make an update ambiguous.

REPORTING, round 4: "no live counterpart" and "nothing differs" used to share one silent return false, and THAT shared silence is what let all three matching bugs survive. VmCommitResult now carry NotFound, and ApplyUpdateAsync return an UpdateOutcome tri-state (Applied / Unchanged / NotFound) so a MISS is caller-visible and testable rather than only a log line.

NAMING, round 4: VmOperationRecord and VmCommitFailure now carry MachineName Name as well as the key, because the key is EMPTY for a keyless row - the documented path - so a key-only record rendered every operation of that path anonymous and a failure rendered as failed for: . naming nothing. VmCommitFailure.Describe() fall back to the name. Stop/Change/Start are keyed from the RESOLVED LIVE row, never the desired one.

LOGGER: CommitLogger ?? Logger ?? NullLogger.Instance - an explicitly configured logger WIN. The other order made WithLogger a no-op whenever the service provider happened to supply a logger. WithLogger is wired at all four live test call site.

ResolveIpAddress return IPAddress?, not a string. The Proxmox side already hold a typed address and used to throw the type away, which forced a hand-rolled dotted-quad check in the base.

STILL DEFERRED, deliberately: ChangeAsync on both provider only RESOLVE the machine, it apply no field - so an update currently stop and restart a guest without changing anything. That is the update spec’s work and it is documented at both call site. Also open: ICanReadAsync<T> / IGenericRepositoryAsync<T> are shipped by netbase but not implemented here, so the two Read overload stay sync-over-async; and VmConnectionStringBuilder / VirtualizationDataStoreReferenceProvider3 / VirtualizationDataStore have no dedicated unit test, being thin and covered end-to-end by the live suite.

LIBRARY: src/NETSetup/DataStore/ is GONE. Code now live in src/osisa.Virtualization/ (Contracts/ ValueObjects/ DataStore/ Operations/ Repositories/ UnitOfWork/ Exceptions/) plus src/osisa.Virtualization.Tests/, both registered in src/NETSetup.sln, consumed by NETSetup and NETSetup.Tests via ProjectReference (the in-solution convention - the PackageReference rule is for CROSS-solution deps). ONE project with a Contracts/ folder, following osisa.Mikrotik / osisa.OPNSense / osisa.Inventory rather than the two-assembly split. VmDataStoreException became VirtualizationException : Exception - a library must not depend on the app assembly.

VALUE OBJECTS: new Vogen VirtualMachineKey (IKeyOf<VirtualMachineSettings>, only two factories - FromSerial(SerialNumber) and FromEnvironment(MachineName, MachineName)), VmId, VirtualSwitchName, StorageName, WmiNamespace. REUSED rather than reinvented: MachineName, OperatingSystem, DataSize (twice). Cores stay int and AutoStart stay bool - a genuine count and a genuine two-state.

THE Iso SPLIT is the substantive design change. One string used to mean an absolute local path on Hyper-V and a storage-relative name on Proxmox, which is why the test base could only assert EndWith("nixos.iso"). The row now carry ISubPath Iso (the NAME) plus StorageName IsoStorage, and each provider resolve it against its own root - Proxmox against the storage, Hyper-V through the new IBootImageResolver (implemented by NETSetup.Helpers.BootImageResolver over the keyed operator). The identical row now go to both hypervisor unchanged.

ASYNC: IVirtualMachineOperations is Task-returning, the repository flush is async, and the unit of work implement ICanCommitAsync. CommitAsync is the real path; the synchronous Commit() delegate to it at the OUTER boundary only, because netbase IUnitOfWork declare a synchronous Commit. Only Commit() is genuinely FORCED (netbase declare it synchronous with no async counterpart); the two Read overload are a second and third sync-over-async point that could be lifted, because netbase also ship ICanReadAsync<T> / IGenericRepositoryAsync<T> - not implemented yet. The code comment name all three rather than claiming one.

SEVEN DEFECTS FIXED. The sharpest: the "empty diff is a no-op" guard never worked. It compared full record equality, but a read-back record never carry Iso / NetworkName / Storage, so a desired record built with an ISO ALWAYS compared unequal and every idempotent cycle stopped and restarted a healthy machine - the exact behaviour the code claimed to prevent. VirtualMachineSettings.DescribesSameMachineAs now compare only the fields Change can apply. Also: Proxmox insert now honour record.VmId (WithVmId(PickFreeVmId(…​)) used to be silently dropped); a failed record no longer escape Flush leaving the unit of work dirty; the real exception survive into VmCommitFailure and the aggregate throw; Hyper-V Stop/Start throw instead of silently no-op while the commit log claim they ran.

A provider that CANNOT honour a field now throw instead of discarding it silently - Hyper-V on Storage/IsoStorage/VmId, Proxmox on NetworkName. A field a provider drop without a word is the same class of lie as the dual-meaning Iso was.

VOGEN BUG FOUND: a [Instance] carrying backslashes is emitted into a NON-verbatim literal without re-escaping, so root\virtualization\v2 silently became rootirtualization2 (the \v pair read as a vertical tab) and every Hyper-V connection failed. Anything with a backslash must be built through From in a plain static property instead. WmiNamespace_HyperV_ShouldKeepItsBackslashes guard it.

KEY MATCHING, fixed after review: VirtualMachineBuilder must NOT invent a key. It used to default to From(name), a THIRD key shape neither provider ever project, so the repository could never match the row and every update of a built row was a silent no-op reported as a clean commit - the same defect as the empty-diff bug, re-entering through the builder. A built row now leave the key empty and the repository key it exactly the way a provider key a keyless guest, so there is ONE match path.

KEY CASE, fixed after review: VirtualMachineKey documented case-insensitive comparison but only an explicit ComparisonValue uppercased - the generated == / GetHashCode stayed ordinal, and the repository dictionary use the DEFAULT comparer. A Vogen NormalizeInput now lower-case on creation so every consumer obey one rule. Null is passed THROUGH that hook on purpose: Vogen run it BEFORE Validate, so coalescing there would turn From(null) into a silent empty key.

NETSetupFileOperators.Iso2 renamed to BootImages (+ DefaultBootImagesRoot / BootImagesRoot) - numbered names say nothing, and the key needed a five-line comment to justify itself.

The raw ProcessStartInfo in the Hyper-V test is gone. Two nested NETCommand facade command (GetVmNetworkAdapterCommand, NeighborLookupCommand) delegate to PowershellCommand.Builder().UseEncoded(), carry a RenderedShellCommand test seam, and set $ErrorActionPreference = 'Stop' so a cmdlet failure is distinguishable from an empty result - the old helper swallowed exit code and stderr entirely.

ADDRESS DISCOVERY, learned the hard way: do NOT use ArpScanner.FindIPByMAC to find a guest on the Default Switch. It actively ARP-SWEEP every address of the subnet, and that switch is a /20 - roughly 4000 synchronous SendARP calls, which crashed the test host unscoped and outlasted the whole boot timeout when scoped. READ the neighbour cache with Get-NetNeighbor instead; the guest is already in it by the time sshd is up. Hyper-V connect went from 6m50s (fail) to 48s (pass).

VirtualMachineBuilder (src/NETSetup/DataStore/VirtualMachineBuilder.cs) set every property through a With…​ call: WithName, WithKey, WithOperatingSystem, WithVmId, WithMemory/WithMemoryBytes, WithCores, WithDisk/WithDiskBytes, WithPowerState, WithIso, WithNetwork, WithStorage, WithIsoStorage, WithAutoStart. Create() start empty, From(record) start from an existing row, Build() demand a name.

VirtualMachineSettings gained OPTIONAL init property (Iso, NetworkName, Storage, IsoStorage, AutoStart). The positional signature is untouched, so every existing construction keep compiling - purely additive.

Insert on both provider now realise those value with the SAME hardware shape ProvisionNixosVm already use: Processor + RandomAccessModule + VMDisk on Proxmox, and the VirtualMachine(name, iso, switch, disk, cpu, ram) ctor on Hyper-V. The 4-arg Hyper-V ctor default to 4 cores / 4 GiB, so a WithCores / WithMemory would silently vanish - the wider overload is used whenever the row specify them.

Hyper-V gen 2 guest need TWO firmware knob before an unsigned Linux ISO boot: Secure Boot OFF and the optical drive FIRST. (UPDATED 2026-08-30: Secure Boot is no longer OFF for everybody - the row OS decide it, Windows family get Secure Boot + vTPM at CREATION. See the top status entry. The optical-drive-first rule is unchanged.) Both are set natively through Msvm_VirtualSystemSettingData + ModifySystemSettings (no PowerShell, no raw process). ComputerSystemMethods.ModifySettingData was tried first and fail with "failed to modify resources" - it target RESOURCE setting, not the SYSTEM setting where firmware knob live.

Boot source selection: the DVD and the hard disk BOTH describe themselves as EFI SCSI Device on a gen 2 guest, so a description match pick the wrong device. A boot source InstanceID is the drive own device path plus a trailing marker, so the DVD is matched on THAT.

IPFS node row (identical on both): 8 GiB RAM, 2 core, 64 GiB disk, nixos.iso, autostart. Verified on the Hyper-V guest: ProcessorCount 2, MemoryStartup 8 GiB.

CONNECT PROOF: a real ssh session as root, authenticated with netsetup-master.key (its public half is baked into nixos.iso root authorized_keys), then uname -a executed and asserted - a half-open socket cannot pass. Both guest answer Linux nixos-installer 6.12.78 …​ x86_64 GNU/Linux. TestIpfsNixProxmox on osisaLib03 and TestIpfsNixHyperV on the local Hyper-V are LEFT RUNNING on purpose so they stay connectable.

Address discovery is provider wiring: Proxmox use the existing DiscoverVmIpViaQmAgent (the ISO enable qemu-guest-agent); Hyper-V ask integration service first and fall back to adapter MAC → host arp cache, because the NixOS live image run no Hyper-V KVP daemon.

The local boot image live at C:\NETSetupImages\nixos.iso, NOT under C:\NETSetupDEV: the Stage0 dev-env test wipe that folder, and a running guest hold its mounted ISO locked - 15 Stage0 test failed with a sharing violation until the image moved out.

New project pair src/osisa.Inventory/ + src/osisa.Inventory.Tests/, wired into src/NETSetup.sln. Same shape as osisa.Mikrotik / osisa.OPNSense: packable lib (Package.Build.props), $(DefaultNetTargetFramework), InternalsVisibleTo the test project.

Three probe behind one IHostProbe interface, scanner run ALL per address and merge: ArpHostProbe (Win32 SendARP → MAC, Windows + same-segment only), IcmpHostProbe (Ping → round-trip, cross-segment but silent on ICMP-blocking host), TcpPortHostProbe (TcpClient over port list → open port, the one that feed classification). Rationale: no single technique see every device.

Probe NEVER throw for unreachable host - return HostProbeOutcome.NoResponse. Only bad INPUT throw. Address answering nothing is dropped from the result: a scan report device, never silence.

ScanTargetExpander COUNT before it materialize → mistyped /8 throw ScanTargetLimitExceededException instead of 16 million probe. Concurrency bounded via SemaphoreSlim from InventoryScanRequest.MaxConcurrency.

Reuse osisa VO for address / port / name: IP, Port, MachineName from osisa.SystemManagement.Contracts. New Vogen VO only where none exist: MacAddress (canonical AA:BB:CC:DD:EE:FF + FromAnyFormat for dash/dot/bare/lowercase wire input), OuiPrefix, VendorName (with Unknown instance).

MacAddress.TryFromAnyFormat use out MacAddress? NOT out MacAddress - Vogen VOG009 prohibit handing out default.

DeviceClassifier rule are ORDERED most-specific-first, port + vendor only. SMB+SSH → Nas BEFORE the Windows rule, else every NAS read as Windows.

OuiVendorTable.Default is a CURATED STARTER SET (~35 entry), NOT the IEEE registry, and NOT verified against it. Extensible by ctor injection. Full-registry file load deliberately not wired.

ArpHostProbe must qualify System.OperatingSystem.IsWindows() - osisa.SystemManagement.Contracts.Elements also define OperatingSystem.

Library stand ALONE: no CLI verb, no netsetup update hook, no NETSetupConfig feed. Deliberate - keep the scope to the project.

"Scan the whole network" need NO configured range: ILocalNetworkProvider / LocalNetworkProvider read the machine own NIC and emit CIDR specifier straight into InventoryScanRequest.Targets. Skip down link, loopback, tunnel, link-local 169.254.*, non-contiguous netmask, and anything wider than InventoryScanDefaults.MinimumLocalPrefixLength (/22). Floor exist because a NIC on a /16 is near always VPN or container bridge - nobody mean to walk 65k address.

Live-wire test gated the repo way: class-level [Ignore("manual: …​")] + [TestCategory("Integration")], same as PhysicalOpnsenseIntegrationTests. Never run in a normal dotnet test.

LocalNetworkProviderTests DO touch the real NIC but assert only SHAPE (prefix floor, no loopback, CIDR the expander agree with, own address inside own network) - suite stay green on any box, including one with no usable NIC.

PROXY-ARP GUARD (found by actually running the live sweep, NOT by design): Windows SendARP against an address routed at a VPN / TAP adapter get a SYNTHESIZED reply, so EVERY address answer with the same MAC. First live run on a dev box with an OpenVPN TAP adapter (MAC block 00:FF:*) report all 254 address of 192.168.4.0/24 as device. NetworkScanner.RemoveProxyArpArtifacts now drop a group when the address answered ARP ONLY and more than InventoryScanDefaults.MaxAddressesPerMacAddress (4) address share that MAC. Anything that ALSO answer ICMP/TCP is kept - real evidence outrank the heuristic, so the TAP gateway itself still appear. Discard logged at warning naming MAC + count, never silent.