Company come from netbase (osisa.Enterprise.Entities), built by fluent builder. Vocabulary is small and it is NOT a hierarchy - it is an assignment graph. Measured shape plus the survey of organisation standards live in Company model: what we have today, and which standards exist.

Two netsetup-side stashes exist because the netbase Company has no slot for them. Both are process-static, keyed by company name, and both are LIFTED into the config by the translator:

WindowsDCTranslator (abstract base) run BEFORE any device is looked at:

Everything after this point only ADD to that seed. Config stay a public property on the translator, which is what let the customer .cs patch it afterwards.

LiberatorWithWinDCTranslator.Translate():

Order matter. Devices before employees, because EmployeeTranslator.EnsureAssociatedComputer expect the machine to exist already (and translate the device on the fly when the customer forgot the AddDevice). Stack injection before employees, so a name collision fail before any user wiring start.

translator.Config is public, so the tail of the customer .cs patch what a generic translation cannot know: the real osisaadmin password, PublicUri, GatewayIP (phase 1 = upstream port), real BIOS serials, pinned IPs, MoveVm(…​) to re-pin an implicit VM onto another host, mail / dns provider options. Customers/README.md carry ten worked examples.

Rule: an override SET a config value. It never introduce a literal that downstream code then re-invents. Value missing? Add it here or in the translator, and let the templates read it.

JsonSerializer.Serialize(config, NETSetupConfig.JsonSerializerOptions). Those options add the netbase system-management + windows converters and register the netsetup-derived machine types (NETSetupDC, NETSetupFirewall, NETSetupDnsServer, NETSetupMikrotik) as Machine subtypes. Without that registration a firewall or DC deserialise back as a plain machine and every GetSingle<IRouter>() style lookup miss it.

Each customer app write the JSON twice, same bytes: <Name>.json and #<ticket>.json. Both are committed. NETSetup.Tests link Customers/*.json as content and load them through CustomerConfig.LoadStaudt() / .Load("<name>") - so a stale JSON mean the tests assert against a config that no longer match the .cs. Re-run the app after every edit.

The config is not only an input file: it is also readable AS A DATABASE, which is what the next section is about - see Netconfig as a database: installation IS synchronisation.

A config plus an installer is a one-way, write-only story: code read fields off a config object and call provisioning routines. Every question a database answer for free has to be hand written - which machines differ, what would change, what changed, is it idempotent, did it fail per machine or per batch.

Model both sides as data stores and those answers come from the repository instead:

A reconciliation is then the ordinary set difference between two ReadAll() results, and "idempotent" stop being a property somebody has to remember to implement: a commit with nothing buffered do nothing, and an update whose applicable fields already match records nothing (VirtualMachineSettings.DescribesSameMachineAs).

NETSetup.DataStore.NETConfig is a V5 data store reference over ONE NETSetupConfig. Where a normal source database would sit on sqlite, this one sit on the customer JSON the translator produced.

Registration is one call, same as any other reference:

The store is keyed by config.ConfigName unless WithDataStoreName say otherwise - the customer name is already that config’s identity everywhere else, and a second name would only be a way for the two to disagree.

A delete that destroy immediately is unrecoverable, and the record that would tell you WHAT was destroyed die with it. So the two halves are separated, and only the second one is irreversible:

The contract live in NETBASE, not here. IPermanentDeletions<TEntity> (osisa.Repository.Contracts.Repositories, derive IRepositoryBase<TEntity>, two member - ReadSoftDeleted() + ExecutePermanentDeletionsAsync(ct)) MOVED out of osisa.Virtualization. A two-step deletion is a REPOSITORY capability, not a hypervisor quirk: any store that can mark a row instead of destroying it want the same two verbs, and a netbase test base can only gate on a netbase interface. NETSetup consumer only repoint the using; the semantics above are unchanged.

Two things the move cost, both worth knowing before touching the file:

Why the marker live in the NAME: it survive a restart, a reconnect and a different process, it is visible without any tooling, and it need no side table - which a marker held anywhere else would. Marking an already marked machine change nothing, so a synchronisation run twice never produce ##name.

Why a commit must not destroy: a synchronisation against a half-reachable environment would otherwise destroy the machines it merely failed to see. Marking is safe to do unattended; destroying is an act somebody perform on purpose.

Drive files. A soft-deleted machine KEEP its disks - that is what make it recoverable, and it is also what still occupy the storage. Reclaiming that storage is exactly what ExecuteDeletions is for: the hard delete take the disks with it (Hyper-V RemoveVirtualMachineAsync shut the guest down, delete its VHDX and destroy the machine). Anything worth keeping must be copied off BEFORE that call. A retention rule - how long a # machine may sit there before its storage is reclaimed - is a policy decision that does not exist yet.

Per provider:

The marker has TWO spellings, and both are recognised everywhere:

A marker only one side can write would leave marked guests invisible to the reader, so SoftDeleteMarker.IsMarked and .Unmark accept both, and only .Mark / .MarkDnsSafe differ.

VirtualMachineSettings.IsVirtualMachine. True by default - a row read from a hypervisor IS a virtual machine - and CALCULATED on the source side: a config machine is a virtual machine exactly when its serial is hosted, <vmid>@<hostSerial>.

That is not cosmetic. A NETSetupConfig hold physical machines too - domain controller, clients, MikroTik, printers - and no hypervisor can create any of them. Feeding them to a synchroniser would produce rows no target could ever satisfy, and every cycle would fail on the same machines. Of the 11 machines in ZH-Test, 5 are virtual (the implicit Liberator stack) and 6 are physical.

NETSetup.Tests.DataStoreTests.NETConfigDataStoreTests - no hypervisor touched, no environment gate, runs anywhere:

NETConfigDataStoreTests2 put the same store through the NETBASE base UnitOfWorkRepositoryTestsBase3<VirtualMachineSettings, IVirtualMachineRepository, IVirtualizationUnitOfWork>, so the netconfig is held to the generic osisa repository contract rather than only to hand-written claims. Three of its cases are OVERRIDDEN, and each override is a real divergence worth knowing:

The same base run against the REAL environments, wiring only, in NETSetup.Tests.DataStoreTests:

Neither suite override a case. They contribute setup and assertion hooks only - which machines are theirs, what a created row look like, what a read-back guest must carry - and every case is the netbase one, unchanged. Both environment can now apply a field change and mark a guest as deleted, so neither suite declare an exception any more.

Both suites moved from the v3 base to UnitOfWorkRepositoryTestsBase4 (through the shared VirtualMachineRepositoryCrudTestBase2). v4 is v3 plus SIX soft-delete cases - 8 → 14 cases per provider suite - and they only run when the repository under test implement the netbase IPermanentDeletions<TEntity>: the base gate on RepositorySupportsPermanentDeletions, the same way it already gate insert / update / delete on their capability interface. A store without the capability simply run the v3 set.

Only these two suites moved. NETConfigDataStoreTests2 above STAY on v3 on purpose: the netconfig store is JSON-backed, its "soft delete" is a renamed entry in a config file, and the six cases are about MARKING A REAL GUEST and then destroying it. Running them against a config file would prove nothing about the thing that can actually be lost.

Two of the v4 hooks are virtual for exactly this repo’s situation: ReadSoftDeletedCount() and ExecutePermanentDeletions(). A live hypervisor is a SHARED store - other people’s guests live there, some of them already marked - so a base that count every soft-deleted row, or destroy every one it find, would fail on a foreign machine or destroy it. VirtualMachineRepositoryCrudTestBase2 override both and filter them through IsOwn, so the count see only the suite’s own NETSetupCrudTest* guests and the destroy route through the existing ExecuteOwnDeletions guard - which go Assert.Inconclusive rather than destroy a machine the suite did not create. An inconclusive run is a cheap thing to fix; a destroyed foreign guest is not. That is the same rule as the delete/update victim selector below, applied to the second half of the deletion.

Both are destructive and [TestCategory("local")]. Every machine they touch is one they created, named NETSetupCrudTest*: the netbase base pick its delete and update victim with entities.Last(), which on a live host would be a real machine, so both selectors are overridden to the own set and the destroy step refuse to run while a foreign soft-deleted guest is present.

The guests each suite create are shaped per provider, and the shape is a virtual property rather than a constant:

The Hyper-V suite is GATED on its boot image: no image on this box, no run (Assert.Inconclusive), because the netbase VirtualMachine ctor refuse a guest with no ISO - a missing fixture would otherwise read as a repository failure. Set NETSETUP_KEEP_CRUD_GUESTS to keep the created guests after the run for inspection; unset (the default) they are destroyed, which is what keep the host at the same guest count it started with.

Another shape is one override per provider, added when it is known to work on that environment.

Cost: an on-purpose run, never something to hang off every build - Hyper-V pay for a real VHDX per guest and a slow WMI destroy. No suite time is quoted here on purpose. The Hyper-V guests are now Windows 11 shaped, 64 GB and BOOTING, and the suite grew from 8 to 14 cases, so it is materially slower than any figure measured on the old Minimal shape. MEASURE BEFORE QUOTING. Both suites still leave the host exactly as they found it - every guest they create, they destroy.

Proxmox turned out to carry the SAME class of defect, one field wide: netbase VMHardware(VmConfigQemu) construct RandomAccessModules as an empty list and never fill it, so every Proxmox guest read back as 0 B of memory - disks and processors are mapped, memory is not. ProxmoxVmOperations.Project now read Configuration.Memory, which Proxmox keep in mebibytes.

Both defects were invisible to the fake environment and to every count-based assertion. They only appeared once a test asked a real hypervisor what it had ACTUALLY created - which is the whole argument for running the contract against live providers.

Three constraints only a LIVE run could have found, all now encoded in the wiring:

NETSetup.Tests.TestInfrastructure.TestCompanyConfigBuilder build a test-only customer the normal way - a fluent company builder (devices, a Distributed Storage task, an employee who has it) that run the SAME LiberatorWithWinDCTranslator a customer app run. The company NEED an IPFS node, and the translation produce none: DeviceTranslator dispatch servers on the Description string and has no IPFS branch, so the config come out with the usual Liberator stack and nothing else.

Treating the config as a database close that gap without touching the translator:

The inserted row is a first-class machine afterwards: read back through the repository, carried by config.DirectoryService.Machines with the hosted serial 1030@ipfslib, flagged IsVirtualMachine, and selected by VirtualMachinesOn(liberatorSerial) - so the host that will have to create it already see it.

The KEY is what make that work. A netconfig machine IS its serial, and VirtualMachineKey.FromSerial reassemble the hosted form, so keying the row pin it to a host. A keyless row would land as a machine hosted nowhere.

The source store exist and is proven; the provisioning path is untouched - EnsureCustomerVms and the stages still read the config directly. What is not wired yet:

ProxmoxWindowsVmFactory read Machine.Hardware for BOTH the system disk and the RAM, and only fall back to its reference default (64 G / 4 G) when the config is silent. Existing customers are unaffected.

Sizing is applied IN MEMORY, never persisted - same IHardware reason as above:

Call them in the provisioning test / deploy path, on a config you are about to provision from - NEVER on one you serialize. Only the disk SIZE is taken from the config; the rest of the disk shape (bus, cache, discard) stay VMDisk.Default because it is Proxmox-specific.

Why the disk matter: devBuilder04 had 18.3 GB free of 63 GB against ~48 GB of Docker data measured on devBuilder02. That is not short by a rounding error, it is short by a factor, and no software config could fix it after the fact.

Every reusable node boot local:iso/NETSetup.iso, and the binary INSIDE it is the one that run the install. So a capability added in C# reach new nodes only after this ISO is rebuilt - until then every node need the same manual finish-up (WinRM, groups, WSL, Docker autostart) that devBuilder05 and devBuilder06 both needed.

--images / --drivers MUST match what the current ISO carry, or nodes lose the Windows image they install from. Read them off the live ISO rather than guessing: mount -o loop,ro /var/lib/vz/template/iso/NETSetup.iso /mnt/x && ls /mnt/x/NETSetup/Images /mnt/x/NETSetup/Drivers. Config/ MUST come out EMPTY - that is what make it reusable.

Keep the .bak - it is the rollback. Swapping by mv is safe even while a VM has the ISO attached: the rename keep the inode, so a running guest go on reading the old image until it is powered off.

For the second host, do NOT upload twice. Serve from the first host and pull host-to-host - measured 2026-09-02: 11.9 GB in 90 seconds at ~120 MB/s between hosts, against ~20 minutes from the dev box.

Rebuilt 2026-09-02 (sha256 fc2b5132…​92bd87, 11'946'061'824 bytes) onto BOTH osisaLib03 and Power-1, carrying WindowsCapabilities + DockerAutoStart. Verify a shipped ISO by size: the embedded NETSetup/NETSetup.exe must match src/NETSetup/publish/NETSetup.exe byte for byte. strings on it prove nothing - it is a compressed single-file bundle.

Customer configs used to carry "changeme".ToSecretString() for every domain and client administrator. That is a bad failure shape: the literal is committed, it is WRONG, and NOTHING complain - the config generate happily and the damage only surface hours later as a domain join failing 1355 on an unattended node.

Now every one of them call CustomerSecrets.PasswordFor("<username>"), which read NETSETUP_PW_<username> from the environment and throw CustomerSecretNotFoundException when it is missing. Failing to generate is strictly safer than generating something that cannot work, and the exception name the account, the variable, the KeePass title and the command to fix it.

Applied to #915, #9153, #9154, #9155. The other customer configs (Carrera, Saner, Schnell, Staudt) still carry literals - same treatment when someone touch them next.

Symptom: node come back up, docker CLI answer, engine do not. docker version show a Client block and nothing else, or docker desktop status say "Could not retrieve status."

Cause: Docker Desktop is a per-USER desktop application, not a service. Measured on devBuilder05 - EVERY com.docker.backend / Docker Desktop process sit in the interactive session (SessionId 2, the RDP logon) and die with it. com.docker.service being Stopped/Manual is NORMAL and is not the engine; it is only the privileged helper. And settings-store.json ship AutoStart=False, so Docker do not even start when somebody DO log on.

There is no supported headless mode. The engine need a session, so NETSetup make one. Declare it:

WindowsCapabilitiesApplier then read the password off that same User entity and DockerAutoStartHelper configure five things. Every one of them was needed - drop any and the node come back without an engine:

Three parallel lab configs, all derived from production #915, all on the real 192.168.3.x lab net (#915 pin DNS to a DC at 10.1.0.201 that do not answer here, so a #915 guest lose name resolution and fail the domain join with 1355). Do NOT edit #915 for lab runs - it drive the production site.

Serials are derived as OUI + vmid, and nothing else - see ProxmoxNodeIdentity.DeriveSerialNumber. The host is NOT part of it, so two nodes sharing a vmid on two different Proxmox hosts compute the SAME serial and fight over one map file. Allocate lab vmids GLOBALLY, not per host.

Each is driven by a Prod-category test: ProxmoxDevBuilder03ReinstallTests, ProxmoxDevBuilder05ReinstallTests, ProxmoxDevBuilder06ReinstallTests, ProxmoxDevRunner01ReinstallTests, ProxmoxDevRunner02ReinstallTests, HyperVDevRunner03ReinstallTests, ProxmoxDevRunner04ReinstallTests. They are [TestCategory("Prod")], so the default local.runsettings filter (TestCategory!=Prod) hide them and dotnet test --filter alone match NOTHING - the CLI filter is ANDed with the runsettings one, not substituted for it. Run them with --settings src\prod.runsettings, which carry no filter. The 05/06 tests assert the DECLARATION before they spend three hours installing against it - a config that forgot a capability produce the same dead end devBuilder04 did.

devRunner02 carry a SECOND test beside its reinstall one: ProxmoxDevRunner02DataStoreTests set the same node up the V5 way - read the node as a RECORD out of the netconfig store (AddReference3<NETConfig.DBBuilder> → OpenDataStore3<IVirtualizationUnitOfWork>), then one Insert plus one CommitAsync against ProxmoxVmDataStoreReference5, then GetByKey to read it back. An existing node is REUSED, never replaced. Watch the vmid: a reusable-ISO node carry the MAC-derived serial (BC2411000134), NOT <vmid>@<host>, so the store report VmId.None and the vmid is recovered with ProxmoxNodeIdentity.TryGetVmIdFromSerial - which only accept the UPPERCASE hex shape. A config declare RAM and disk but never a core count, and VirtualMachineBuilder.WithCores refuse a zero.

Five rules that change how a provisioning run behave, or how much you may TRUST it. All measured on osisaLib03 (192.168.3.233) plus the local Hyper-V bench. Full fingerprints + the command recipes: docs/winpe.adoc section "Deploy Blockers" and the netsetup-windows-node-proxmox skill reference references/deploy-blockers.md.

Most live suites are round-trips: they create, assert, destroy, and the host end at the guest count it started with. One deliberately does not, and mixing the two up is how a "leftover" guest get deleted by somebody tidying up.

Both Win11 suites EnsureRemove the machine name BEFORE provisioning, so Tests2 REPLACE its guest rather than accumulate them.

Dependency worth knowing before a Proxmox Windows test run: the Proxmox storage devboxiso is a CIFS mount of the dev box NETSetupISO share, whose template\iso is a junction to C:\NETSetupDEV. That indirection is why the offline Win11 test take ~5 s - the host REFERENCE the 11.9 GB ISO instead of receiving it. When it go offline the guest cannot be created at all, and uploading is not a fallback: measured 0.15 MB/s, about 20 h for 11.9 GB.

Model mirror the NixOS module system, not invent parallel vocabulary. NixOS module = three parts (imports, options, config). Every option is a PATH in one uniform tree, has a TYPE, and values MERGE by that type. Consequence: one path → value pair express everything - services., boot., security., vendor host., all identical shape. RFC-42 (the settings freeform attrset convention in nixpkgs) push same idea inside nix itself: stop minting one option per setting, carry structured value.

So the model carry a generic Options list plus a RECURSIVE NixValue - not 50 named C# properties. That is the whole design decision.

All under src/NETSetup/Config/Nix/Model/.

Two axes, two slots. Do not mix.

Do NOT fake packaging via SetOption("environment.systemPackages", …​). AddPackage exist so packages stay first-class list you can query and diff.

Raw emit verbatim, NO quotes. Nix distinguish string from PATH from expression:

Get wrong → nix eval-error, or worse, silently wrong config.

templateOverride is the ONLY production seam added - additive, defaults null, threaded through InstallNixosVm.Run → ProvisionNixosVm.CreateVmOnProxmox + EmitConfigBundle. When null, everything resolve via NixTemplateFactory.ForMachine(…​) exactly as before. No existing caller change. ISO build, SCP upload, bundle emit, sops encryption, disko-install over ssh: all unchanged. The model is a different way to DESCRIBE a host, not a different way to install one.

NixIpfsRole reproduce the FULL hand written NixIpfsTemplate: encrypted host.system.disk with nested btrfs subvolumes + retention, boot.initrd.systemd.enable, security.tpm2.enable, boot.initrd.luks.devices."cryptroot".crypttabExtraOpts, host.security.secrets with unquoted sopsFile path, host.services.ipfsPrivateCluster, both sops entries, 8 GiB / 64 GiB sizing.

Final state (2026-08-17): BOTH paths green, verified end to end.

Reaching that took SIX pre-existing defects out of the install path, each one masked by the previous: chroot path → missing wrapper command → PCR binding → unmounted target → missing age key → kubo AutoConf. All six are listed under Proxmox VM provisioning during update. NONE were caused by the entity model - the normalised render diff prove the model emit semantically identical nix, and the hand written template failed identically at every step. Reproducing a real role end to end is simply a far harder test than anything that existed before, which is what surfaced them.

Skill: /nixos-config carry the same guidance for module-level work.

The Chocolatey packages NETSetup installs are produced upstream by netbase-build’s MSI deployment method: netbase-build Push publishes the project, then shells out to the MSIBuild.exe tool (WixSharp), which generates the WiX authoring (.wxs) and drives the WiX toolset (wix build) to compile it into the .msi; an optional step wraps that .msi into the Chocolatey .nupkg pushed to netsetupprod.