rename internal implementation to declare, mirroring apply

note that i worked around the question of how to delegate part of the
options to the consumer by creating aliases for different parts of the
function slot filling.
i've been pretty arbitrary about this so far tho, and mostly to preserve
existing interfaces, rather than out of conscious UX design per se.
so the interface can def change still, but at least the _user_'s side is
more DRY now!

default.nix

@@ -11,7 +11,8 @@ let
     ;
   inherit (pkgs) lib;
   inherit (import sources.flake-inputs) import-flake;
-  inherit ((import-flake { src = ./.; }).inputs) nixops4;
+  inputs = (import-flake { src = ./.; }).inputs;
+  inherit (inputs) nixops4;
   panel = import ./panel { inherit sources system; };
   pre-commit-check =
     (import "${git-hooks}/nix" {
@@ -78,6 +79,7 @@ in
   # re-export inputs so they can be overridden granularly
   # (they can't be accessed from the outside any other way)
   inherit
+    inputs
     sources
     system
     pkgs

deployment/data-model-test.nix

@@ -1,7 +1,7 @@
 let
   inherit (import ../default.nix { }) pkgs inputs;
   inherit (pkgs) lib;
-  inherit (lib) mkOption;
+  inherit (lib) mkOption types;
   eval =
     module:
     (lib.evalModules {
@@ -13,17 +13,83 @@ let
         ./data-model.nix
       ];
     }).config;
+  nixops4Deployment = inputs.nixops4.modules.nixops4Deployment.default;
+  inherit (inputs.nixops4.lib) mkDeployment;
 in
 {
   _class = "nix-unit";
 
   test-eval = {
+    /**
+      This tests a very simple arrangement that features all ingredients of the Fediversity business logic:
+      application, resource, environment, deployment; and wires it all up in one end-to-end exercise.
+      - The dummy resource is a login shell made available for some user.
+      - The dummy application is `hello` that requires a shell to be deployed.
+      - The dummy environment is a single NixOS VM that hosts one login shell, for the operator.
+      - The dummy configuration enables the `hello` application.
+      This will produce a NixOps4 deployment for a NixOS VM with a login shell for the operator and `hello` available.
+    */
     expr =
       let
         fediversity = eval (
           { config, ... }:
           {
             config = {
+              resources.login-shell = {
+                description = "The operator needs to be able to log into the shell";
+                request =
+                  { ... }:
+                  {
+                    _class = "fediversity-resource-request";
+                    options = {
+                      wheel = mkOption {
+                        description = "Whether the login user needs root permissions";
+                        type = types.bool;
+                        default = false;
+                      };
+                      packages = mkOption {
+                        description = "Packages that need to be available in the user environment";
+                        type = with types; attrsOf package;
+                      };
+                    };
+                  };
+                policy =
+                  { config, ... }:
+                  {
+                    _class = "fediversity-resource-policy";
+                    options = {
+                      username = mkOption {
+                        description = "Username for the operator";
+                        type = types.str; # TODO: use the proper constraints from NixOS
+                      };
+                      wheel = mkOption {
+                        description = "Whether to allow login with root permissions";
+                        type = types.bool;
+                        default = false;
+                      };
+                    };
+                    config = {
+                      resource-type = types.raw; # TODO: splice out the user type from NixOS
+                      apply =
+                        requests:
+                        let
+                          # Filter out requests that need wheel if policy doesn't allow it
+                          validRequests = lib.filterAttrs (
+                            _name: req: !req.login-shell.wheel || config.wheel
+                          ) requests.resources;
+                        in
+                        lib.optionalAttrs (validRequests != { }) {
+                          ${config.username} = {
+                            isNormalUser = true;
+                            packages =
+                              with lib;
+                              attrValues (concatMapAttrs (_name: request: request.login-shell.packages) validRequests);
+                            extraGroups = lib.optional config.wheel "wheel";
+                          };
+                        };
+                    };
+                  };
+              };
               applications.hello =
                 { ... }:
                 {
@@ -31,14 +97,38 @@ in
                   module =
                     { ... }:
                     {
-                      options = {
-                        enable = lib.mkEnableOption "Hello in the shell";
-                      };
+                      options.enable = lib.mkEnableOption "Hello in the shell";
                     };
                   implementation =
                     cfg:
                     lib.optionalAttrs cfg.enable {
-                      dummy.login-shell.packages.hello = pkgs.hello;
+                      resources.hello.login-shell.packages.hello = pkgs.hello;
+                    };
+                };
+              environments.single-nixos-vm =
+                { config, ... }:
+                {
+                  resources.operator-environment.login-shell.username = "operator";
+                  implementation =
+                    requests:
+                    { providers, ... }:
+                    {
+                      providers = {
+                        inherit (inputs.nixops4.modules.nixops4Provider) local;
+                      };
+                      resources.the-machine = {
+                        type = providers.local.exec;
+                        imports = [
+                          inputs.nixops4-nixos.modules.nixops4Resource.nixos
+                        ];
+                        nixos.module =
+                          { ... }:
+                          {
+                            users.users = config.resources.shell.login-shell.apply (
+                              lib.filterAttrs (_name: value: value ? login-shell) requests
+                            );
+                          };
+                      };
                     };
                 };
             };
@@ -51,20 +141,64 @@ in
                   applications.hello.enable = true;
                 };
               };
+              example-deployment = mkOption {
+                type = types.submodule nixops4Deployment;
+                readOnly = true;
+                default = config.environments.single-nixos-vm.deployment config.example-configuration;
+              };
             };
           }
         );
+        resources = fediversity.applications.hello.resources fediversity.example-configuration.applications.hello;
+        hello-shell = resources.resources.hello.login-shell;
+        environment = fediversity.environments.single-nixos-vm.resources.operator-environment.login-shell;
+        result = mkDeployment {
+          modules = [
+            (fediversity.environments.single-nixos-vm.deployment fediversity.example-configuration)
+          ];
+        };
+
       in
       {
-        inherit (fediversity)
-          example-configuration
-          ;
+        number-of-resources = with lib; length (attrNames fediversity.resources);
+        inherit (fediversity) example-configuration;
+        hello-package-exists = hello-shell.packages ? hello;
+        wheel-required = hello-shell.wheel;
+        wheel-allowed = environment.wheel;
+        operator-shell =
+          let
+            operator = (environment.apply resources).operator;
+          in
+          {
+            inherit (operator) isNormalUser;
+            packages = map (p: "${p.pname}") operator.packages;
+            extraGroups = operator.extraGroups;
+          };
+        deployment = {
+          inherit (result) _type;
+          deploymentFunction = lib.isFunction result.deploymentFunction;
+          getProviders = lib.isFunction result.getProviders;
+        };
       };
     expected = {
+      number-of-resources = 1;
       example-configuration = {
         enable = true;
         applications.hello.enable = true;
       };
+      hello-package-exists = true;
+      wheel-required = false;
+      wheel-allowed = false;
+      operator-shell = {
+        isNormalUser = true;
+        packages = [ "hello" ];
+        extraGroups = [ ];
+      };
+      deployment = {
+        _type = "nixops4Deployment";
+        deploymentFunction = true;
+        getProviders = true;
+      };
     };
   };
 }

deployment/data-model.nix

@@ -1,6 +1,7 @@
 {
   lib,
   config,
+  inputs,
   ...
 }:
 let
@@ -15,19 +16,73 @@ let
     ;
 
   functionType = import ./function.nix;
-  application-resources = {
+  application-resources = submodule {
     options.resources = mkOption {
       # TODO: maybe transpose, and group the resources by type instead
       type = attrsOf (
-        attrTag (lib.mapAttrs (_name: resource: mkOption { type = resource.request; }) config.resources)
+        attrTag (
+          lib.mapAttrs (_name: resource: mkOption { type = submodule resource.request; }) config.resources
+        )
       );
     };
   };
+  nixops4Deployment = types.deferredModuleWith {
+    staticModules = [
+      inputs.nixops4.modules.nixops4Deployment.default
+
+      {
+        _class = "nixops4Deployment";
+        _module.args = {
+          resourceProviderSystem = builtins.currentSystem;
+          resources = { };
+        };
+      }
+    ];
+  };
 in
 {
-  _class = "nixops4Deployment";
-
   options = {
+    resources = mkOption {
+      description = "Collection of deployment resources that can be required by applications and policed by hosting providers";
+      type = attrsOf (
+        submodule (
+          { ... }:
+          {
+            _class = "fediversity-resource";
+            options = {
+              description = mkOption {
+                description = "Description of the resource to help application module authors and hosting providers to work with it";
+                type = types.str;
+              };
+              request = mkOption {
+                description = "Options for declaring resource requirements by an application, a description of how the resource is consumed or accessed";
+                type = deferredModuleWith { staticModules = [ { _class = "fediversity-resource-request"; } ]; };
+              };
+              policy = mkOption {
+                description = "Options for configuring the resource policy for the hosting provider, a description of how the resource is made available";
+                type = deferredModuleWith {
+                  staticModules = [
+                    (policy: {
+                      _class = "fediversity-resource-policy";
+                      options.resource-type = mkOption {
+                        description = "The type of resource this policy configures";
+                        type = types.optionType;
+                      };
+                      # TODO(@fricklerhandwerk): we may want to make the function type explict here: `request -> resource-type`
+                      # and then also rename this to be consistent with the application's resource mapping
+                      options.apply = mkOption {
+                        description = "Apply the policy to a request";
+                        type = functionTo policy.config.resource-type;
+                      };
+                    })
+                  ];
+                };
+              };
+            };
+          }
+        )
+      );
+    };
     applications = mkOption {
       description = "Collection of Fediversity applications";
       type = attrsOf (
@@ -48,23 +103,89 @@ in
             };
             resources = mkOption {
               description = "Compute resources required by an application";
-              type = functionTo application.config.config-mapping.output-type;
+              type = application.config.config-mapping.function-type;
               readOnly = true;
-              default = input: (application.config.implementation input).output;
+              default = application.config.config-mapping.apply;
             };
+            # TODO(@fricklerhandwerk): this needs a better name
             config-mapping = mkOption {
-              description = "Function type for the mapping from application configuration to required resources";
+              description = "Compute resources required by an application";
               type = submodule functionType;
               readOnly = true;
               default = {
-                input-type = application.config.module;
+                input-type = submodule application.config.module;
                 output-type = application-resources;
+                declare = application.config.implementation;
               };
             };
           };
         })
       );
     };
+    environments = mkOption {
+      description = "Run-time environments for Fediversity applications to be deployed to";
+      type = attrsOf (
+        submodule (environment: {
+          _class = "fediversity-environment";
+          options = {
+            resources = mkOption {
+              description = ''
+                Resources made available by the hosting provider, and their policies.
+
+                Setting this is optional, but provides a place to declare that information for programmatic use in the resource mapping.
+              '';
+              # TODO: maybe transpose, and group the resources by type instead
+              type = attrsOf (
+                attrTag (
+                  lib.mapAttrs (_name: resource: mkOption { type = submodule resource.policy; }) config.resources
+                )
+              );
+            };
+            implementation = mkOption {
+              description = "Mapping of resources required by applications to available resources; the result can be deployed";
+              type = environment.config.resource-mapping.function-type;
+            };
+            resource-mapping = mkOption {
+              description = "Function type for the mapping from resources to a (NixOps4) deployment";
+              type = submodule functionType;
+              readOnly = true;
+              default = {
+                input-type = application-resources;
+                output-type = nixops4Deployment;
+                declare = environment.config.implementation;
+              };
+            };
+            config-mapping = mkOption {
+              description = "Mapping from a configuration to a deployment";
+              type = submodule functionType;
+              readOnly = true;
+              default = {
+                input-type = config.configuration;
+                output-type = nixops4Deployment;
+                declare =
+                  cfg:
+                  # TODO: check cfg.enable.true
+                  let
+                    required-resources = lib.mapAttrs (
+                      name: application-settings: config.applications.${name}.resources application-settings
+                    ) cfg.applications;
+                  in
+                  environment.config.resource-mapping.apply required-resources;
+              };
+            };
+            # TODO(@fricklerhandwerk): maybe this should be a separate thing such as `fediversity-setup`,
+            # which makes explicit which applications and environments are available.
+            # then the deployments can simply be the result of the function application baked into this module.
+            deployment = mkOption {
+              description = "Generate a deployment from a configuration, by applying an environment's resource policies to the applications' resource mappings";
+              type = environment.config.config-mapping.function-type;
+              readOnly = true;
+              default = environment.config.config-mapping.apply;
+            };
+          };
+        })
+      );
+    };
     configuration = mkOption {
       description = "Configuration type declaring options to be set by operators";
       type = optionType;

deployment/function.nix

@@ -5,7 +5,6 @@
 let
   inherit (lib) mkOption types;
   inherit (types)
-    deferredModule
     submodule
     functionTo
     optionType
@@ -14,24 +13,46 @@ in
 {
   options = {
     input-type = mkOption {
-      type = deferredModule;
+      type = optionType;
     };
     output-type = mkOption {
-      type = deferredModule;
+      type = optionType;
     };
     function-type = mkOption {
+      type = optionType;
+      readOnly = true;
+      default = functionTo config.output-type;
+    };
+    wrapper-type = mkOption {
       type = optionType;
       readOnly = true;
       default = functionTo (submodule {
         options = {
           input = mkOption {
-            type = submodule config.input-type;
+            type = config.input-type;
           };
           output = mkOption {
-            type = submodule config.output-type;
+            type = config.output-type;
           };
         };
       });
     };
+    declare = mkOption {
+      type = config.function-type;
+      default = _: { };
+    };
+    wrapper = mkOption {
+      type = config.wrapper-type;
+      readOnly = true;
+      default = input: fn: {
+        inherit input;
+        output = config.implementation fn.config.input;
+      };
+    };
+    apply = mkOption {
+      type = config.function-type;
+      readOnly = true;
+      default = input: (config.wrapper input).output;
+    };
   };
 }