[clhodapp]

Stacked on #141. Implements the NixOps4 part of section 21 of the design document and supersedes #139, which built NixOps4 machines as flake-time children.

The root. A deployment's root is a deferred composite declared at the flake top under the name of the output it fills: caisson.caisson-nixops4-composite.configurations.nixops4, or caisson.nixops4.configurations.nixops4 for upstream code. Its entry is published as the nixops4 output, { _type; rootFunction; getProviders; }. rootFunction calls the entry's finalize with the outputValues and resourceProviderSystem NixOps4 passes and returns the export. getProviders calls finalize with the system alone, so every output read throws, and builds the root's providers. Published names continue through members: nixops4, nixops4.web.

Native integrations.

• caisson-nixops4-composite and caisson-nixops4-resource are deferred configurations (caisson-core's mkDeferredConfiguration). A composite finalizes each member it declares by calling finalize on the member's entry, with { outputValues = args.outputValues.<member>; resourceProviderSystem; }, and returns the finalized members as its children.
• Composite and resource are two classes. A composite has NixOps4's providers option and no type. A resource has NixOps4's resource, type and providers options and no members.
• A composite's members module argument holds, for each member, outputs and absoluteMemberPath, built from the args and the declared names. No member's config is reachable through it, or through the composite's caisson.<integration>.configurations, which hold entries.
• argsNeeded lists the deploying system and, per member, one arg per name in a resource's outputsSkeleton. A resource lists the outputs a tool may cache in cacheableOutputs.
• The root's discoverArgs { system } is a program that runs nixops4 state dump for each resource named by a resource's state option, and prints the recorded outputs as outputValues, with the deploying system.
• The NixOS adapter (module nixos of the resource class, selected by its default module) deploys the NixOS configuration declared beneath a resource as nixops4-nixos does: nix copy and bin/apply switch over SSH, with the same SSH options, and bash from the package set caisson selects for the deploying system.
• The composite takes defaultPkgs, the package set the root's providers, discovery program and adapters run on.

Upstream-compatible integration.

• nixops4 takes root modules as written for NixOps4's mkRoot. The root and every member are evaluated by caisson with NixOps4's class nixops4Component.
• A composite decides each member's type with upstream's test (options.resourceType.isDefined), through a probe evaluation over NixOps4's base modules. A member that sets type and also declares members is refused.
• NixOps4's members option is declared again as deferred modules whose value is the finalized members' config, and members is the module argument of the same value, so config.members.x.outputs.y, members.x.outputs.y and state = members.x work as upstream. Every composite sets unsafeCrossChildReferences for nixops4Component, so the childless view reads the same config.
• A member that imports nixops4-nixos gets nixos.module evaluated as a caisson NixOS configuration beneath it. nixos.configuration is read-only, so the class module forces nixpkgs to a value whose lib.nixosSystem returns that configuration. The shell comes from caisson's package set.
• cacheableOutputs is an allow-list by member path.

Integrations builder. mkModuleConfiguration passes argsNeeded and discoverArgs from an integration's evaluate to the manifest, and takes children from it when the integration returns them. A deferred entry that carries exportsTo is published like a manifest.

Also.

• caisson-core is pinned to the head of Add deferred configurations, direct-children additions and cross-child references caisson-core#57.
• The nixops4-apply NixOS module and the test pins of NixOps4 (41858b4) and nixops4-nixos (4c7ceab) carry over from Integrate NixOps4 deployments as caisson-nixops4 #139.

Named errors. A composite whose member names or kinds read members or outputs, and a resource whose outputsSkeleton reads its own outputs, fail with an error naming the composite or resource. Without these errors, both cases end in an infinite recursion. The names are taken from an evaluation in which those reads throw, which costs one extra module evaluation per composite and resource.

Tests.

• The pinned-world probes cover the root's args and their sources, composites nested two levels deep (member paths, argsNeeded, argsSource, members of a composite member, a NixOS machine inside), a resource whose type depends on another member's output, the native members argument holding only outputs and member paths, the root's providers, a root inside a NixOS machine, entries no parent finalizes, upstream reads through members at two levels, a NixOS member built through nixops4-nixos that matches the system eval-config.nix builds from the same modules, and a second deferred integration beside nixops4 in one flake.
• The new check deferred-errors runs nix eval on eleven cases and matches the exact error text: a missing output at the root and inside nested composites (caisson-deferred: needs outputValues.a.b.source.stdout), members or kinds read from outputs, an outputsSkeleton read from its own outputs, a name declared as composite and resource, two roots, a root under another name, and output values that are not a set.
• The new check nixops4-discovery builds the root's discovery program for one and for two state resources, runs it against nixops4 state dump output recorded from a real deployment, and compares the JSON with the args argsNeeded names.
• A real nixops4 apply of a native and an upstream-compatible deployment with the local provider, run outside the test suite, applied in output order, passed the values through nested composites, was a no-op the second time, and reported a cycle through outputs as Cycle detected.
• At this head, pinned-world, deferred-errors, nixops4-discovery, nix-unit, eval-weight, argument-errors and treefmt pass locally. Every x86_64-linux check, the VM tests included, passed at a5204f8; the commits since change only the NixOps4 integrations and tests.

🤖 Generated with Claude Code