Add the NixOps4 integrations, native and upstream-compatible

README.md

@@ -134,6 +134,9 @@ source by.
 | `facter` | none | a `facter.json` as nixos-facter writes it, with the NixOS configurations that run on it declared inside it; a machine gets it as `hardware.facter.reportPath` |
 | `caisson-microvm` | `microvm` | microvm.nix guests declared inside the NixOS host that runs them, each guest a NixOS configuration declared inside it that sets its own `microvm.*` options and gets microvm.nix's guest module by default; the host selects caisson's `microvm-host` NixOS module, which defines microvm.nix's `microvm.vms.<guest>` from them; the microvm integration we recommend for new configurations |
 | `microvm` | `microvm` | a microvm.nix guest written as microvm.nix reads it, a NixOS configuration that sets its `microvm.*` options itself, declared inside the NixOS host that runs it; for porting an existing guest |
+| `caisson-nixops4-composite` | `nixops4` | a composite of a NixOps4 deployment, evaluated when NixOps4 deploys, with its members, composites and resources, declared beneath it; it declares providers and reads the outputs of its members; the composite declared under the name `nixops4` where no composite holds it is the root, published as the `nixops4` output the NixOps4 command reads; the NixOps4 integration we recommend for new configurations |
+| `caisson-nixops4-resource` | `nixops4` | a resource of a NixOps4 deployment, evaluated when NixOps4 deploys, holding the caisson configurations it deploys; a NixOS configuration declared inside it is deployed over SSH as nixops4-nixos deploys one |
+| `nixops4` | `nixops4` | the root modules of a NixOps4 deployment, written as NixOps4 users write them for `mkRoot`, each component evaluated by caisson and each nixops4-nixos machine a caisson NixOS configuration; the configuration named `nixops4` is published as the `nixops4` output; for porting an existing deployment |
 | `treefmt` | `treefmt-nix` | the formatters of a tree, as treefmt-nix modules; the configuration named `formatter` is published as the `formatter.<system>` that `nix fmt` runs |
 | `nvf` | `nvf` | a Neovim written as nvf modules, published as `nvfConfigurations.<system>.<name>`, in the shape `neovimConfiguration` returns, kept in a separate Nix profile that the machine, home-manager configuration or hjem configuration it is declared inside activates |
 | `nixvim` | `nixvim` | a Neovim written as nixvim modules, published as `nixvimConfigurations.<system>.<name>`, kept in a profile as an nvf configuration is |

configs/flake/caisson/partitions/checks.nix

@@ -234,6 +234,14 @@
                     caisson = self;
                   };
                 };
+                # The discovery program of a NixOps4 root, built and run
+                # against recorded state dumps, with a stand-in for
+                # NixOps4 that prints them (tests/nixops4-discovery).
+                nixops4-discovery = import (self.outPath + "/tests/nixops4-discovery") {
+                  inputs = inputs // {
+                    caisson = self;
+                  };
+                };
                 # A machine booted in a VM that activates the
                 # home-manager configurations, the hjem configurations
                 # and the profiles declared inside it, and a standalone
@@ -264,6 +272,26 @@
                         --impure --extra-experimental-features nix-command
                       touch $out
                     '';
+                # The errors of deferred configurations and the NixOps4
+                # integrations, read as text by the real evaluator, as
+                # a tool that finalizes a deferred configuration reads
+                # them. It runs as the argument-error check does, on
+                # the same library.
+                deferred-errors =
+                  pkgs.runCommand "deferred-errors"
+                    {
+                      nativeBuildInputs = [ pkgs.nix ];
+                    }
+                    ''
+                      export HOME="$(realpath .)"
+                      unset NIX_STORE
+                      export NIX_STORE_DIR=${builtins.storeDir}
+                      export NIX_REMOTE="$HOME/storedata"
+                      bash ${self.outPath}/tests/deferred-errors/check.sh ${lib.escapeShellArg argumentErrorsLib} \
+                        ${inputs.nixops4.outPath} \
+                        --impure --extra-experimental-features nix-command
+                      touch $out
+                    '';
                 minimal-consumer-all-outputs = builtins.seq minimalConsumerOutputs.flakeModule (
                   builtins.seq minimalConsumerOutputs.lib (
                     pkgs.runCommand "minimal-consumer-all-outputs" { } "touch $out"

docs/development/repository-structure.md

@@ -28,7 +28,9 @@ The layer users reach for: the integrations (`structural`,
 `flake-parts`, `nixpkgs`, `nixos`, `nixos-minimal`, `home-manager`,
 `home-manager-minimal`, `darwin`, `hjem`, `caisson-colmena`, `colmena`,
 `caisson-disko`, `disko`, `caisson-facter`, `facter`,
-`caisson-microvm`, `microvm`, `terranix`, `system-manager`, `treefmt`,
+`caisson-microvm`, `microvm`, `caisson-nixops4-composite`,
+`caisson-nixops4-resource`, `nixops4`,
+`terranix`, `system-manager`, `treefmt`,
 `nvf`, `nixvim`, `topology`, `kubenix`, `nixidy`), each
 a library overlay
 contributing its `lib.caisson` namespace, registering its module

docs/development/testing-architecture.md

@@ -320,4 +320,6 @@ The checks partition merges outputs from all test and example flakes into the
 | `system-manager-vm-<distribution>` | `checks.nix` + `tests/system-manager/vm.nix` | A system-manager machine, activated through sequences of changes in a VM of Ubuntu 22.04 or Debian 12 booted from the cloud image of the distribution, applies its profiles, its home-manager configurations and its hjem configuration, and a home-manager configuration activated by hand for another version warns of the drift |
 | `containerTests.x86_64-linux.system-manager-<distribution>` (not a check) | `checks.nix` + `tests/system-manager/container.nix` | The same sequences in a container of each distribution of `tests/system-manager/container-distros.nix`; the container needs `auto-allocate-uids`, so the `system-manager-container` job of the check workflow builds each by name |
 | `argument-errors` | `checks.nix` + `tests/argument-errors/` | The argument error of every entry point comes from Nix itself, raised at the call site with no frame of caisson |
+| `deferred-errors` | `checks.nix` + `tests/deferred-errors/` | The errors of deferred configurations and the NixOps4 integrations carry their text: `caisson-deferred: needs <path>` with the member path from the root, and the errors that refuse members or outputs named from outputs, a name declared as composite and resource, and a second root |
+| `nixops4-discovery` | `checks.nix` + `tests/nixops4-discovery/` | The discovery program of a NixOps4 root builds, with one state resource and with two, and prints, from recorded state dumps, the output values at the paths the root names in `argsNeeded` |
 | `eval-weight` | `checks.nix` + `tests/eval-weight/` | Framework evaluation cost held to committed ceilings ([guide](https://nix-caisson.github.io/docs/eval-weight.html)) |

docs/development/testing.md

@@ -76,6 +76,25 @@ plumbing works.
     'let f = builtins.getFlake "path:'"$PWD"'"; in f.lib' --impure
   ```
 
+## Deferred Configuration Errors (Message Text)
+
+- **Scope:** The text of the errors of deferred configurations and the
+  NixOps4 integrations. A tool tells an arg it lacks from a failure by
+  `caisson-deferred: needs <path>`, and `builtins.tryEval` in the
+  pinned-world suite sees only that an evaluation failed.
+- **Location:** `tests/deferred-errors/check.sh` and its cases in
+  `tests/deferred-errors/cases.nix`.
+- **Mechanism:** the script runs `nix eval` on each case and looks for
+  the line of the message the case names. The `deferred-errors` check
+  runs it in the sandbox over the library of the `argument-errors`
+  check and the NixOps4 source.
+- **Execution against the flake's library, from a checkout:**
+  ```bash
+  tests/deferred-errors/check.sh \
+    'let f = builtins.getFlake "path:'"$PWD"'"; in f.lib' \
+    <path of the NixOps4 source> --impure
+  ```
+
 ## Integration Testing (Test Flakes)
 
 - **Scope:** Module composition, end-to-end evaluation, and build success.