Skip to content

Nest every integration under lib.caisson.<target> with uniform names - #6

Open
clhodapp wants to merge 8 commits into
mainfrom
rename/integration-surface
Open

Nest every integration under lib.caisson.<target> with uniform names#6
clhodapp wants to merge 8 commits into
mainfrom
rename/integration-surface

Conversation

@clhodapp

@clhodapp clhodapp commented Sep 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Every integration now lives at lib.caisson.<target> and exports the same two names: mkModule (the class-bound caisson-core.mkModule) and mkConfiguration (evaluate the target's module system with the selected class modules). The flake-parts integration, which used to export flat under lib.caisson, moves to lib.caisson.flake-parts.

old new
lib.caisson.mkFlake lib.caisson.flake-parts.mkConfiguration
lib.caisson.mkFlakeModule lib.caisson.flake-parts.mkModule
lib.caisson.types lib.caisson.flake-parts.types
lib.caisson.nixos.mkSystem / mkSystemFull / mkSystemMinimal lib.caisson.nixos.mkConfiguration / mkConfigurationFull / mkConfigurationMinimal
lib.caisson.nixos.mkNixosModule lib.caisson.nixos.mkModule
lib.caisson.home-manager.mkHomeConfiguration / mkHomeConfigurationMinimal lib.caisson.home-manager.mkConfiguration / mkConfigurationMinimal
lib.caisson.home-manager.mkHomeManagerModule lib.caisson.home-manager.mkModule
lib.caisson.colmena.mkColmenaHive / mkColmenaModule lib.caisson.colmena.mkConfiguration / mkModule
lib.caisson.terranix.mkTerranixConfiguration / mkTerranixModule lib.caisson.terranix.mkConfiguration / mkModule
lib.caisson.system-manager.mkSystemConfig / mkSystemManagerModule lib.caisson.system-manager.mkConfiguration / mkModule

Every mkConfiguration also takes the same arguments now: ecosystemSrc, configModule (one module, required), moduleImports, specialArgs, and pkgSets where the target consumes a package set (nixos, home-manager); the rest forwards to the evaluator as before. Colmena, terranix and system-manager drop their modules list, terranix drops extraArgs, and home-manager's extraSpecialArgs (on mkConfiguration and mkNixosAdapter) becomes specialArgs. The evaluators still get their own names; the integration translates.

Each signature is the whole surface: an entry point takes exactly its caisson arguments and composes the evaluator's call from them. Nothing else forwards; an unknown argument is an error that names the caisson argument to use where one exists. That closes the ways an evaluator argument used to misbehave when handed in directly (modules overwritten, pkgs conflicting with the framework's nixpkgs.pkgs, baseModules overwritten by mkConfigurationFull, anything the minimal evaluator does not take dropped). The evaluator's full surface stays reachable on purpose through mkConfigurationWithEcosystemArgs (and mkConfigurationMinimalWithEcosystemArgs for nixos): the same arguments plus ecosystemArgs, merged over the composed call verbatim, last.

pkgSets is accepted everywhere (required for nixos, home-manager and terranix; the default for colmena's meta.nixpkgs and system-manager's nixpkgs.hostPlatform; forwarded by flake-parts). Colmena takes its nodes as nodes, with the config module as the hive's defaults. The minimal NixOS evaluator hands pkgSets.pkgs over as the pkgs module argument rather than defining nixpkgs.pkgs.

Colmena is regularized. lib.caisson.colmena.mkConfiguration evaluates a hive module (class colmena: meta and nodes) and projects it onto colmena's hive schema, the nine attributes its binary reads, asserting the schema version against the ecosystem source's own makeHive. The hive module receives mkNixosConfiguration as a module argument, closed over the hive's colmena source: nixos.mkConfiguration's signature and composition (so its ecosystemSrc is nixpkgs, as for any NixOS configuration) plus colmena's public node modules (deploymentOptions, keyChownModule, keyServiceModule, assertionModule). A node is an ordinary NixOS configuration that also declares deployment; a consumer that exports it as nixosConfigurations.<host> reads it back from hive.nodes, one evaluation for nixos-rebuild and colmena apply. Colmena's makeHive is no longer used, and there is no meta.nixpkgs, no defaults, and no separate package-set plumbing. Every node receives colmena's name and nodes special arguments (the hive extends each node with them, a lazy fixpoint), so modules written for colmena's own evaluator work unchanged, and node names are free: meta, defaults and network are ordinary names under nodes; the only names refused are the ones colmena's --on filter could never select (containing a comma, starting with @, or empty).

Breaking, with no compatibility layer: the old names and the old argument spellings are gone. lib.caisson.nixpkgs, the home-manager adapters and provenance helpers, and the tooling namespace are unchanged.

Verified with the full nix flake check (formatter, nix-unit, eval-weight gates, integration test flakes). The companion changes are in nix-caisson/caisson-compat and nix-caisson/nix-caisson.github.io, each on a branch named rename/integration-surface.

🤖 Generated with Claude Code

@clhodapp @claude
refactor(lib): nest every integration under lib.caisson.<target> with…
d9a46cd 
… uniform names

The flake-parts integration used to export its functions flat under
lib.caisson (mkFlake, mkFlakeModule, types) while the other integrations
each had a namespace, and every integration named its entry points
differently (mkSystem, mkHomeConfiguration, mkColmenaHive,
mkSystemConfig, mkTerranixConfiguration). Every integration now lives at
lib.caisson.<target> and exports the same two names: mkModule (the
class-bound caisson-core.mkModule) and mkConfiguration (evaluate the
target's module system with the selected class modules). Variants keep
the suffix (mkConfigurationFull, mkConfigurationMinimal); target-specific
helpers (the home-manager adapters, mkSourceMeta, assertSourceCoherence)
keep their names.

  lib.caisson.mkFlake                          -> lib.caisson.flake-parts.mkConfiguration
  lib.caisson.mkFlakeModule                    -> lib.caisson.flake-parts.mkModule
  lib.caisson.types                            -> lib.caisson.flake-parts.types
  lib.caisson.nixos.mkSystem{,Full,Minimal}    -> lib.caisson.nixos.mkConfiguration{,Full,Minimal}
  lib.caisson.nixos.mkNixosModule              -> lib.caisson.nixos.mkModule
  lib.caisson.home-manager.mkHomeConfiguration{,Minimal}
                                               -> lib.caisson.home-manager.mkConfiguration{,Minimal}
  lib.caisson.home-manager.mkHomeManagerModule -> lib.caisson.home-manager.mkModule
  lib.caisson.colmena.mkColmenaHive            -> lib.caisson.colmena.mkConfiguration
  lib.caisson.colmena.mkColmenaModule          -> lib.caisson.colmena.mkModule
  lib.caisson.terranix.mkTerranixConfiguration -> lib.caisson.terranix.mkConfiguration
  lib.caisson.terranix.mkTerranixModule        -> lib.caisson.terranix.mkModule
  lib.caisson.system-manager.mkSystemConfig    -> lib.caisson.system-manager.mkConfiguration
  lib.caisson.system-manager.mkSystemManagerModule
                                               -> lib.caisson.system-manager.mkModule

This is a breaking change with no compatibility layer: the old names
are gone. lib.caisson.nixpkgs and the tooling (eval-weight,
mkMemoizedDerivationRead) are unchanged.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@clhodapp clhodapp self-assigned this Sep 10, 2026
clhodapp and others added 7 commits September 9, 2026 23:07
@clhodapp @claude
refactor(lib): give every mkConfiguration the same argument shape
1de6f26 
The entry points now share one contract: ecosystemSrc, configModule
(the configuration's single top-level module, required), moduleImports,
specialArgs, and pkgSets where the target consumes a package set
(nixos, home-manager); anything else forwards to the evaluator as
before. That removes the per-target spellings: colmena, terranix and
system-manager took a `modules` list instead of configModule; terranix
took `extraArgs` and home-manager took `extraSpecialArgs` (on
mkConfiguration and mkNixosAdapter) where the others took specialArgs.
The evaluators still receive their own names; the translation happens
inside the integration.

Breaking, with no compatibility layer: `modules`, `extraArgs` and
`extraSpecialArgs` are gone from the caisson surface.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@clhodapp @claude
feat(lib): accept pkgSets on every mkConfiguration
1d4232e 
nixos and home-manager already took pkgSets because their evaluators
need a package set. The other four entry points now accept it too,
optionally: it is passed through as the `pkgSets` special argument
everywhere, and where the evaluator has a package-set slot of its own,
pkgSets.pkgs is that slot's default (terranix `pkgs`, colmena
`meta.nixpkgs`, system-manager's `nixpkgs.hostPlatform`); an explicit
value wins. flake-parts only forwards it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@clhodapp @claude
refactor(lib): close every mkConfiguration signature; add the unsuper…
86cb77d 
…vised twins

Each entry point now takes exactly the caisson arguments (ecosystemSrc,
configModule, moduleImports, specialArgs, pkgSets, and a target's own
few: nixos `system` or `prefix`, colmena `meta` and `nodes`) and
composes the evaluator's call from them. Nothing else forwards: an
unknown argument is an error naming the caisson argument to use where
one exists (`modules`, `pkgs`, `extraArgs`, `extraSpecialArgs`,
`inputs`, ...) and pointing at the twin otherwise. That removes the
ways an evaluator argument used to misbehave when handed in directly:
`modules` silently overwritten, anything the minimal evaluator does
not take silently dropped, `pkgs` conflicting with the framework's
`nixpkgs.pkgs`, `baseModules` overwritten by mkConfigurationFull.

The evaluator's full surface stays reachable on purpose through
mkConfigurationUnsupervised (and mkConfigurationMinimalUnsupervised
for nixos): the same arguments plus `evaluatorArgs`, merged over the
composed evaluator call verbatim, last, so anything the evaluator
accepts can be set or replaced there.

Also: the minimal NixOS evaluator hands pkgSets.pkgs over as the
`pkgs` module argument instead of defining `nixpkgs.pkgs`, which has
no declaring module there; colmena takes its nodes as `nodes` and the
config module becomes the hive's `defaults`; terranix requires pkgSets
in the closed form (it evaluates against a package set).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@clhodapp @claude
refactor(lib): name the open twins mkConfigurationWithEcosystemArgs
7959609 
The deliberate way to the evaluator's full surface is named for what
it takes: `ecosystemArgs`, the arguments of the ecosystem's own
evaluator, beside `ecosystemSrc`.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@clhodapp @claude
refactor(colmena): compose hive nodes as the NixOS configurations the…
099bd6b 
…y are

A colmena hive's nodes are NixOS configurations, but the integration
treated them as a module class of their own with separate package-set
plumbing, so a consumer had to mirror the nixos composition by hand
inside the hive (selection, package set, special arguments) and prove
afterwards that the two evaluations agreed.

The nixos composition now lives in one shared definition
(lib-overlays/nixos/compose.nix) that both integrations import: the
selected nixos-class modules, the hive-wide configModule and the
framework's nixpkgs.pkgs module become the hive's `defaults`, and each
`nodes.<name> = { configModule, deployment? }` adds its own module.
Colmena is handed the package set's identity (path, lib, stdenv) with
empty overlays and config, which is what it reads from meta.nixpkgs
and seeds every node with; nixpkgs only allows nixpkgs.pkgs beside
empty seeding, so the nodes then take the real instance the way every
other caisson NixOS evaluation does. A node's toplevel is therefore
the derivation lib.caisson.nixos.mkConfiguration builds from the same
modules, by construction.

The colmena module class and lib.caisson.colmena.mkModule are gone
(nothing registered under the class). meta.nixpkgs, meta.specialArgs
and their per-node forms are refused with hints; the per-node forms
remain reachable through mkConfigurationWithEcosystemArgs.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@clhodapp @claude
refactor(colmena): evaluate nodes as NixOS configurations; project th…
5334ae9 
…e hive

The integration no longer hands colmena a hive to evaluate. A node is
lib.caisson.colmena.mkNixosConfiguration: nixos.mkConfiguration's
signature and composition, plus colmena's public node modules
(deploymentOptions, keyChownModule, keyServiceModule, assertionModule)
from the colmena ecosystem source, so the result is an ordinary NixOS
configuration that also declares `deployment` and can be the host's
nixosConfigurations entry, one evaluation for nixos-rebuild and
colmena apply. In this namespace `ecosystemSrc` is colmena's; nixpkgs
resolves as nixos.mkConfiguration resolves it without an explicit
source.

The hive is a module of class `colmena` (meta: name, description,
machinesFile, allowApplyAll; nodes.<name>: configurations from
mkNixosConfiguration), evaluated by mkConfiguration and projected onto
colmena's hive schema, the nine attributes its binary reads. The
schema version is asserted against the ecosystem source's own
makeHive, so a colmena revision that moves it fails at evaluation. A
node that did not come from mkNixosConfiguration is refused. pkgSets
on the hive only serves `colmena eval`.

lib.makeHive, meta.nixpkgs, the package-set stub and the shared
composition file's colmena use are gone; the ecosystem-resolution unit
tests probe through the terranix adapter, which still returns its
evaluator's result.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@clhodapp @claude
refactor(colmena): the node constructor is a hive module argument
7b57bcd 
A NixOS configuration's ecosystem source is nixpkgs; colmena's is the
hive's. So mkNixosConfiguration leaves the namespace and reaches the
hive module as a module argument, closed over the hive's colmena
source, with nixos.mkConfiguration's signature: its `ecosystemSrc` is
nixpkgs like any other NixOS evaluation. Nodes are built inside the
hive module; a consumer that exports one as nixosConfigurations.<host>
reads it back from hive.nodes. mkNixosConfigurationWithEcosystemArgs
arrives the same way.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@clhodapp clhodapp

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@clhodapp