diff --git a/lib/attrsets.nix b/lib/attrsets.nix
index ed2fa9770410d..a362e5b00d9ac 100644
--- a/lib/attrsets.nix
+++ b/lib/attrsets.nix
@@ -2258,4 +2258,223 @@ rec {
       ) intersection;
     in
     (x // y) // mask;
+
+  /**
+    Determine whether a value is a leaf node when traversing a `nestedAttrsOf elemType` structure.
+
+    `isNestedAttrsLeaf :: ((String -> Bool) -> [String] -> Bool) -> OptionType -> Any -> Bool`
+
+    For scalar element types (e.g. `int`, `str`), uses the type's `.check`.
+    For submodule types, given their native type check works only after merge,
+    instead check key presence, controlled by `predicate` (`lib.any` or `lib.all`)
+    depending on whether the element submodule should allow additional keys.
+
+    # Inputs
+
+    `predicate`
+
+    : 1\. A predicate combinator: `lib.any` treats a value as a leaf if *any* key matches a declared option; `lib.all` requires *all* keys to match
+
+    `elemType`
+
+    : 2\. The element option type of the `nestedAttrsOf` structure
+
+    `v`
+
+    : 3\. The value to test
+
+    # Example
+
+    ```nix
+    let
+      elementType = types.submodule { options.result = mkOption { type = types.int; }; };
+    in
+      isNestedAttrsLeaf lib.any elementType { result = 1; }
+      # => true
+      isNestedAttrsLeaf lib.any elementType { a.b = { result = 1; }; }
+      # => false (intermediate attrset, no key matches "result")
+    ```
+  */
+  isNestedAttrsLeaf =
+    predicate: elemType: v:
+    let
+      # Top-level option names of the element type, used to detect leaves.
+      # Mirrors the heuristic in `nestedAttrsOf.merge`.
+      elemOptAttrs = elemType.getSubOptions [ ];
+    in
+    if elemOptAttrs == { } then
+      elemType.check v
+    else
+      lib.isAttrs v && predicate (k: elemOptAttrs ? ${k}) (lib.attrNames v);
+
+  /**
+    Map a function over all leaves in a `nestedAttrsOf` structure.
+
+    `mapNestedAttrsWith :: ((String -> Bool) -> [String] -> Bool) -> nestedAttrsOf a -> (a -> b) -> nestedAttrsOf a -> nestedAttrsOf b`
+
+    Traverses the nested attribute set recursively, applying `fn` only at leaf
+    values as determined by `isNestedAttrsLeaf predicate`. Intermediate attrset
+    nodes are preserved as-is in the output structure.
+
+    # Inputs
+
+    `predicate`
+
+    : 1\. Leaf-detection combinator: `lib.any` or `lib.all`
+
+    `type`
+
+    : 2\. A `nestedAttrsOf` option type whose element type identifies leaves
+
+    `fn`
+
+    : 3\. Function applied to each leaf value
+
+    `value`
+
+    : 4\. The nested attribute set (or leaf) to traverse
+
+    # Example
+
+    ```nix
+    mapNestedAttrsWith lib.any (types.nestedAttrsOf types.int) (x: x * 2) { a.b = 1; a.c = 3; d = 5; }
+    # => { a.b = 2; a.c = 6; d = 10; }
+    ```
+  */
+  mapNestedAttrsWith =
+    predicate:
+    let
+      recurse =
+        type: fn: value:
+        if isNestedAttrsLeaf predicate type.nestedTypes.elemType value then
+          fn value
+        else
+          mapAttrs (_: recurse type fn) value;
+    in
+    recurse;
+
+  /**
+    Map a function over all leaves in a `nestedAttrsOf` structure, preserving the structure.
+
+    `mapNestedAttrs' :: nestedAttrsOf a -> (a -> b) -> nestedAttrsOf a -> nestedAttrsOf b`
+
+    Traverses the nested attribute set recursively,
+    applying `fn` only at leaf values.
+    Intermediate attrset nodes are preserved as-is.
+    For submodule element types allowing additional keys,
+    while presuming no key of the nestred attrset structure is contained in the element submodule type.
+
+    # Inputs
+
+    `type`
+
+    : 1\. A `nestedAttrsOf` option type whose element type identifies leaves
+
+    `fn`
+
+    : 2\. Function applied to each leaf value; result replaces the leaf in the output
+
+    `value`
+
+    : 3\. The nested attribute set to traverse
+
+    # Example
+
+    ```nix
+    mapNestedAttrs' (types.nestedAttrsOf types.int) (x: x * 2) { a.b = 1; a.c = 3; d = 5; }
+    # => { a.b = 2; a.c = 6; d = 10; }
+    ```
+  */
+  mapNestedAttrs' = mapNestedAttrsWith lib.any;
+
+  /**
+    Like `concatMapNestedAttrs'`, but with a configurable leaf-detection predicate.
+
+    `concatMapNestedAttrsWith :: ((String -> Bool) -> [String] -> Bool) -> nestedAttrsOf elemType -> ([String] -> elemType -> AttrSet b) -> nestedAttrsOf elemType -> AttrSet b`
+
+    The `predicate` argument controls how submodule-typed leaves are detected from
+    intermediate namespace attrsets: pass `lib.any` (used by `concatMapNestedAttrs'`)
+    to treat a value as a leaf if *any* of its keys is a declared option of the element
+    type, or `lib.all` to require *all* keys to match.
+
+    # Inputs
+
+    `predicate`
+
+    : 1\. Leaf-detection combinator: `lib.any` or `lib.all`
+
+    `type`
+
+    : 2\. A `nestedAttrsOf` option type whose element type identifies leaves
+
+    `fn`
+
+    : 3\. Function called at each leaf: receives the path (list of strings) and leaf value, returns an attrset
+
+    `attrs`
+
+    : 4\. The nested attribute set to traverse
+
+    # Example
+
+    ```nix
+    concatMapNestedAttrsWith lib.all (nestedAttrsOf (submodule { options.result = mkOption { type = int; }; }))
+      (path: v: { ${concatStringsSep "." path} = v.result; })
+      { a.b = { result = 1; }; a.c = { result = 2; }; }
+    # => { "a.b" = 1; "a.c" = 2; }
+    ```
+  */
+  concatMapNestedAttrsWith =
+    predicate: type: fn:
+    let
+      recurse =
+        path: attrs:
+        lib.concatMapAttrs (
+          name: v:
+          if isNestedAttrsLeaf predicate type.nestedTypes.elemType v then
+            fn (path ++ [ name ]) v
+          else
+            recurse (path ++ [ name ]) v
+        ) attrs;
+    in
+    recurse [ ];
+
+  /**
+    Like `concatMapAttrs`, but recurses into nested attribute sets, calling `fn`
+    only at leaves as determined by the element type of the given `nestedAttrsOf` type.
+
+    The function `fn` receives the full path (as a list of strings) to the leaf
+    and the leaf value, and must return an attribute set to be merged into the result.
+
+    Leaf detection mirrors `nestedAttrsOf.merge`: for simple element types (e.g. `int`)
+    `elemType.check` is used directly; for submodule element types (whose `check = isAttrs`
+    cannot distinguish leaves from intermediate nodes) a value is treated as a leaf when
+    all of its keys are declared options of the element type.
+
+    `concatMapNestedAttrs' :: nestedAttrsOf elemType -> ([String] -> elemType -> AttrSet b) -> nestedAttrsOf elemType -> AttrSet b`
+
+    # Inputs
+
+    `type`
+
+    : 1\. A `nestedAttrsOf` option type whose element type identifies leaves
+
+    `fn`
+
+    : 2\. Function called at each leaf: receives the path (list of strings) and leaf value, returns an attrset
+
+    `attrs`
+
+    : 3\. The nested attribute set to traverse
+
+    # Example
+
+    ```nix
+    concatMapNestedAttrs' (nestedAttrsOf (submodule { options.result = mkOption { type = int; }; }))
+      (path: v: { ${concatStringsSep "." path} = v.result; })
+      { a.b = { result = 1; }; a.c = { result = 2; }; }
+    # => { "a.b" = 1; "a.c" = 2; }
+    ```
+  */
+  concatMapNestedAttrs' = concatMapNestedAttrsWith lib.any;
 }
diff --git a/lib/contracts/default.nix b/lib/contracts/default.nix
new file mode 100644
index 0000000000000..6c8b098438bf1
--- /dev/null
+++ b/lib/contracts/default.nix
@@ -0,0 +1,11 @@
+# set of utilities for using contracts.
+# templates of individual contracts are stored in `./templates`.
+{ lib, ... }:
+let
+  callLibs = file: import file { inherit lib; };
+in
+{
+  module = ./module.nix;
+  definitionType = callLibs ./definition-type.nix;
+}
+// callLibs ./helpers.nix
diff --git a/lib/contracts/definition-type.nix b/lib/contracts/definition-type.nix
new file mode 100644
index 0000000000000..79f6284c1da09
--- /dev/null
+++ b/lib/contracts/definition-type.nix
@@ -0,0 +1,329 @@
+{ lib, ... }:
+let
+  inherit (lib) mkOption types;
+  inherit (types)
+    attrs
+    attrsOf
+    functionTo
+    listOf
+    optionDeclaration
+    optionType
+    raw
+    str
+    submodule
+    ;
+in
+submodule (contract: {
+  options = {
+    meta = mkOption {
+      description = ''
+        Useful information about the contract and its maintenance.
+      '';
+      type = submodule {
+        options = {
+          description = mkOption {
+            description = ''
+              Description of the contract.
+            '';
+            type = str;
+          };
+          maintainers = mkOption {
+            description = ''
+              Maintainers of the contract.
+            '';
+            type = listOf attrs;
+          };
+        };
+      };
+    };
+    interface = mkOption {
+      description = ''
+        Interface describing the types used in the contract.
+      '';
+      default = { };
+      type =
+        let
+          type = attrsOf optionDeclaration;
+          default = { };
+        in
+        submodule {
+          options = {
+            request = mkOption {
+              description = "Request type of the contract.";
+              inherit type default;
+            };
+            result = mkOption {
+              description = "Result type of the contract.";
+              inherit type default;
+            };
+            extraImports = mkOption {
+              description = "Extra imports for the request and result submodules (e.g. rename shims).";
+              default = { };
+              type = submodule {
+                options = lib.genAttrs [ "request" "result" ] (
+                  k:
+                  mkOption {
+                    description = "Extra imports for the ${k} submodule.";
+                    type = listOf raw;
+                    default = [ ];
+                  }
+                );
+              };
+            };
+          };
+        };
+    };
+    mkContract = mkOption {
+      description = ''
+        Augment the contract interface's type using a set of overrides.
+
+        `contract.mkContract :: attrs -> optionType`
+
+        **Inputs:**
+
+        `overrides`
+
+        : 1\. A (recursive) attrset of fields to add to the contract interface submodule type
+
+        **Example:**
+
+        ```nix
+        { config, lib, ... }:
+        let
+          inherit (lib) mkOption contract types;
+        in
+        {
+          options.foo = mkOption {
+            default = { };
+            type = config.contractType."<contract>".mkContract
+              {
+                bar = {
+                  default = 10;
+                  defaultText = "10";
+                };
+              };
+          };
+        }
+        ```
+      '';
+      type = functionTo optionType;
+      readOnly = true;
+      default =
+        overrides:
+        let
+          inherit (contract.config) interface;
+        in
+        lib.extendSubmodule overrides (submodule {
+          options = lib.mapAttrs (
+            k: options:
+            mkOption {
+              description = "The ${k} of the contract instance.";
+              type = submodule {
+                imports = interface.extraImports.${k};
+                inherit options;
+              };
+            }
+          ) (lib.getAttrs [ "request" "result" ] interface);
+        });
+    };
+    _mkProviderType = mkOption {
+      description = ''
+        Create a `nestedAttrsOf` type for provider instances.
+
+        Note that this should not be used directly, as `defaults` specified get lost once any value gets set manually.
+        Instead, use `config.contracts.<contract>.mkProviderType`.
+
+        `<contract>._mkProviderType :: { providerOptions?, overrides?, fulfill?, fulfill'? } -> optionType`
+
+        **Inputs:**
+
+        `overrides`
+
+        : 1\. Overrides for `{ request, result }` submodule types (to e.g. add defaults)
+
+        `providerOptions`
+
+        : 2\. Additional option declarations of the provider outside of the contract's request/result.
+
+        `fulfill`
+
+        : 3\. Optional function `request -> result` that derives result values
+        from request values. Applied with `mkDefault` priority so explicit
+        result settings take precedence. Use `fulfill'` if the result also
+        needs the instance `name`.
+
+        `fulfill'`
+
+        : 4\. Optional function `{ request, name, instance } -> result`. Lower-level
+        variant of `fulfill` exposing the instance `name` and the full submodule
+        `instance` (including provider-specific options). At most one of
+        `fulfill` / `fulfill'` may be set.
+
+        `_requests`
+
+        : 5\. Internal. Pre-bound by `contracts.<contract>.mkProviderType`, which is the
+        recommended call site for providers. Forwards consumer `want` request data
+        into each leaf at `mkDefault` priority (1000) so provider-specific options
+        do not silently mask consumer wants via `nestedAttrsOf` leaf-priority filtering.
+
+        **Example:**
+
+        ```nix
+        { lib, config, options, ... }:
+        let
+          inherit (config.contracts) arithmetic;
+        in
+        {
+          imports = [
+            # simple dummy contract with request/result both shaped `{ value: int }`
+            <nixpkgs/nixos/tests/contracts/arithmetic-contract.nix>
+          ];
+          options.services.increment.arithmetic = lib.mkOption {
+            default = arithmetic.providerRequests.increment;
+            type = arithmetic.mkProviderType {
+              fulfill = request: {
+                value = request.value + 1;
+              };
+            };
+          };
+          config = {
+            contracts.arithmetic.providers.increment.module = options.services.increment.arithmetic;
+          };
+        }
+        ```
+      '';
+      type = functionTo optionType;
+      readOnly = true;
+      default =
+        {
+          providerOptions ? { },
+          overrides ? { },
+          fulfill ? null,
+          fulfill' ? null,
+          _requests ? null,
+        }:
+        assert lib.assertMsg (
+          fulfill == null || fulfill' == null
+        ) "mkProviderType: at most one of `fulfill` and `fulfill'` may be set.";
+        let
+          fulfill'' = if fulfill != null then ({ request, ... }: fulfill request) else fulfill';
+          inherit (contract.config) interface;
+          mkExtended =
+            k:
+            lib.extendSubmodule (overrides.${k} or { }) (submodule {
+              imports = interface.extraImports.${k};
+              options = interface.${k};
+            });
+        in
+        types.nestedAttrsOf (
+          types.submodule (
+            [
+              {
+                options = {
+                  request = mkOption {
+                    description = "Request of the contract instance.";
+                    type = mkExtended "request";
+                  };
+                  result = mkOption {
+                    description = "Result of the contract instance.";
+                    default = { };
+                    type = mkExtended "result";
+                  };
+                }
+                // providerOptions;
+              }
+              # Forward consumer `want` request data at `mkDefault` (priority 1000)
+              # so it beats `overrides.request.<field>.default` (`mkOptionDefault`,
+              # priority 1500) but loses to explicit deployer writes (normal, 100).
+              # Without this, writing any provider-specific option causes
+              # `nestedAttrsOf`'s leaf-level priority filtering to drop the outer
+              # `mkOptionDefault` default that carried the consumer's want,
+              # leaving `overrides.request.<field>.default` as the only surviving
+              # value -- silently masking the consumer's declared overrides.
+              #
+              # The path-split search strips the provider option path prefix from
+              # `options.request.loc` to recover the leaf's position within
+              # `_requests` (the want-derived request tree pre-bound by the caller).
+              (
+                { options, ... }:
+                if _requests == null then
+                  { }
+                else
+                  {
+                    config.request =
+                      let
+                        leafPath = lib.init options.request.loc;
+                        matchN = lib.findFirst (
+                          n:
+                          let
+                            v = lib.attrByPath (lib.drop n leafPath) null _requests;
+                          in
+                          v != null && v ? request
+                        ) null (lib.range 0 (lib.length leafPath));
+                        wantRequest =
+                          if matchN != null then (lib.attrByPath (lib.drop matchN leafPath) null _requests).request else null;
+                      in
+                      lib.mkIf (wantRequest != null) (lib.mkDefault wantRequest);
+                  }
+              )
+            ]
+            ++ lib.optional (fulfill'' != null) (
+              { config, name, ... }:
+              {
+                config.result = lib.mkDefault (fulfill'' {
+                  inherit (config) request;
+                  inherit name;
+                  instance = config;
+                });
+              }
+            )
+          )
+        );
+    };
+    behaviorTest = mkOption {
+      description = ''
+        Test used to ensure all `providers` of the contract behave the same way.
+
+        For an example of how to write a test for a contract,
+        see the `behaviorTest` in `lib/contracts/file-secrets.nix`.
+      '';
+      # The type should be more precise of course.
+      # There should actually be a NixOSTest type.
+      # And we can probably do something fancy with the `request` and `result` modules.
+      type = functionTo attrs;
+      default =
+        {
+          name,
+          extraModules ? [ ],
+        }:
+        {
+          name = "contracts_<contract>_${name}";
+          containers.machine =
+            { ... }:
+            {
+              imports = extraModules;
+            };
+          testScript =
+            { ... }:
+            ''
+              machine.succeed("echo 'please define a test!' >&2; exit 1")
+            '';
+        };
+      defaultText = lib.literalExpression ''
+        {
+          name,
+          extraModules ? [ ],
+        }:
+        {
+          name = "contracts_<contract>_''${name}";
+          containers.machine =
+            { ... }:
+            {
+              imports = extraModules;
+            };
+          testScript = { ... }: "";
+        }
+      '';
+    };
+  };
+})
diff --git a/lib/contracts/definitions/default.nix b/lib/contracts/definitions/default.nix
new file mode 100644
index 0000000000000..19507fcd26a72
--- /dev/null
+++ b/lib/contracts/definitions/default.nix
@@ -0,0 +1,9 @@
+# collection of contract templates, defined in `lib` so we can still build the manual.
+# declarations of individual contracts follow the type in `./definition-type.nix`.
+{ lib, ... }:
+lib.mapAttrs (
+  _name: path:
+  lib.evalOption (lib.mkOption {
+    type = lib.contract.definitionType;
+  }) (import path { inherit lib; })
+) { fileSecrets = ./file-secrets.nix; }
diff --git a/lib/contracts/definitions/file-secrets.nix b/lib/contracts/definitions/file-secrets.nix
new file mode 100644
index 0000000000000..d3898b0d0c61e
--- /dev/null
+++ b/lib/contracts/definitions/file-secrets.nix
@@ -0,0 +1,129 @@
+{
+  lib,
+  ...
+}:
+let
+  inherit (lib) mkOption types;
+  inherit (types) str;
+in
+{
+  meta = {
+    description = ''
+      Contract for secrets handling where a consumer requests a secret
+      and a provider provides it at runtime at a given file path.
+    '';
+    maintainers = with lib.maintainers; [
+      ibizaman
+      kiara
+    ];
+  };
+  interface = {
+    request = {
+      mode = mkOption {
+        description = ''
+          Mode the secret file must have.
+        '';
+        type = str;
+        default = "0400";
+      };
+
+      owner = mkOption {
+        description = ''
+          Linux user that must own the secret file.
+        '';
+        type = str;
+      };
+
+      group = mkOption {
+        description = ''
+          Linux group that must own the secret file.
+        '';
+        type = str;
+      };
+    };
+    result = {
+      path = mkOption {
+        type = str;
+        description = ''
+          Path to the file containing the secret generated out of band.
+
+          This path will exist after deploying to a target host,
+          it is not available through the nix store.
+        '';
+      };
+    };
+  };
+  behaviorTest =
+    {
+      name,
+      wantPath,
+      extraModules ? [ ],
+    }:
+    lib.contract.mkBehaviorTest {
+      contractName = "fileSecrets";
+      testName = name;
+      inherit wantPath extraModules;
+      nodeModule =
+        { config, ... }:
+        {
+          options.test = {
+            owner = mkOption {
+              type = str;
+              default = "root";
+            };
+
+            group = mkOption {
+              type = str;
+              default = "root";
+            };
+
+            mode = mkOption {
+              type = str;
+              default = "0400";
+            };
+
+            content = mkOption {
+              type = str;
+              default = "a super secret secret!";
+            };
+          };
+
+          config = lib.mkMerge [
+            (lib.mkIf (config.test.owner != "root") {
+              users.users.${config.test.owner}.isNormalUser = true;
+            })
+            (lib.mkIf (config.test.group != "root") {
+              users.groups.${config.test.group} = { };
+            })
+          ];
+        };
+      requestOf = config: { inherit (config.test) owner group mode; };
+      testScript =
+        { result, nodes }:
+        let
+          cfg = nodes.machine;
+        in
+        ''
+          owner = machine.succeed("stat -c '%U' ${result.path}").strip()
+          print(f"Got owner {owner}")
+          if owner != "${cfg.test.owner}":
+              raise Exception(f"Owner should be '${cfg.test.owner}' but got '{owner}'")
+
+          group = machine.succeed("stat -c '%G' ${result.path}").strip()
+          print(f"Got group {group}")
+          if group != "${cfg.test.group}":
+              raise Exception(f"Group should be '${cfg.test.group}' but got '{group}'")
+
+          mode = str(int(machine.succeed("stat -c '%a' ${result.path}").strip()))
+          print(f"Got mode {mode}")
+          wantedMode = str(int("${cfg.test.mode}"))
+          if mode != wantedMode:
+              raise Exception(f"Mode should be '{wantedMode}' but got '{mode}'")
+
+          content = machine.succeed("cat ${result.path}").strip()
+          print(f"Got content {content}")
+          if content != "${cfg.test.content}":
+              raise Exception(f"Content should be '${cfg.test.content}' but got '{content}'")
+        '';
+    };
+}
diff --git a/lib/contracts/helpers.nix b/lib/contracts/helpers.nix
new file mode 100644
index 0000000000000..d12b728c0bc21
--- /dev/null
+++ b/lib/contracts/helpers.nix
@@ -0,0 +1,126 @@
+{ lib, ... }:
+{
+  /**
+    Whether a value is a contract instance (an attrset with `request` and `result`).
+
+    Useful when an option accepts both a contract type and a plain value
+    (e.g. `types.oneOf [ types.path contractType ]` or `types.nullOr contractType`)
+    and the consumer needs to branch on which was provided.
+
+    lib.contract.isInstance :: a -> bool
+
+    # Example
+
+    ```nix
+    if lib.contract.isInstance cfg.passwordFile
+    then cfg.passwordFile.result.path
+    else cfg.passwordFile
+    ```
+  */
+  isInstance = v: lib.isAttrs v && v ? result;
+
+  /**
+    Rebind every contract's `mkProviderType` against a NixOS module's `config`,
+    returning an attrset shaped like `lib.contracts` extended with any
+    contracts defined inline on `config.contractDefinitions`.
+
+    This makes for the idiomatic way to access `mkProviderType` for providers subject
+    to the sandboxing used in builds of the NixOS manual.
+    In other cases, one may instead use `config.contracts.<contract>.mkProviderType`.
+
+    For each contract, prefers the bridge (`config.contracts.<name>.mkProviderType`)
+    when available - the bridge pre-binds `_requests` so consumer `want` request
+    data is forwarded into each leaf (see `_mkProviderType`'s `_requests`
+    parameter in `./definition-type.nix`). Falls back to the pure lib function
+    when `config.contracts` is absent (e.g. inside the manual docs build's
+    per-module sandbox, where the contracts module is not imported); the lib
+    version produces an identical option type shape, only without runtime want
+    forwarding, which is irrelevant to rendered docs.
+
+    Use this in provider modules to bind one or more contracts at once,
+    including contracts defined inline on `config.contractDefinitions`:
+
+    ```nix
+    inherit (lib.contract.forModule config) fileSecrets databaseConnection;
+    # then: type = fileSecrets.mkProviderType { ... };
+    #       type = databaseConnection.mkProviderType { ... };
+    ```
+
+    lib.contract.forModule :: moduleConfig -> { <contractName> = contract; ... }
+  */
+  forModule =
+    moduleConfig:
+    let
+      contracts = lib.contracts // (moduleConfig.contractDefinitions or { });
+    in
+    lib.mapAttrs (
+      name: contract:
+      contract
+      // {
+        mkProviderType = moduleConfig.contracts.${name}.mkProviderType or contract._mkProviderType;
+      }
+    ) contracts;
+
+  /**
+    Generic skeleton for a contract `behaviorTest`.
+
+    Abstracts the contract-name prefix, want-path wiring, and result extraction,
+    leaving only per-contract pieces (test options, request shape, nodeConfig,
+    testScript body) to the caller.
+
+    lib.contract.mkBehaviorTest :: { contractName, testName, wantPath, ... } -> NixOSTest
+
+    # Arguments
+
+    - `contractName`: attrset key under `config.contracts` (e.g. `"fileSecrets"`)
+    - `testName`: test-name suffix; produces `contracts_<contractName>_<testName>`
+    - `wantPath`: attr-path list into `contracts.<contractName>.want`
+    - `extraModules`: extra NixOS modules for the test machine (optional, default `[]`)
+    - `nodeModule`: NixOS module that defines per-contract `options` and their config
+      (e.g. `options.test.*`, user/group autocreation)
+    - `requestOf`: `config -> request` - derive the contract request attrset from
+      the evaluated node config
+    - `testScript`: `{ result, nodes } -> string` - return the Python test script;
+      `result` is the already-resolved result attrset for `wantPath`
+  */
+  mkBehaviorTest =
+    {
+      contractName,
+      testName,
+      wantPath,
+      extraModules ? [ ],
+      nodeModule,
+      requestOf,
+      testScript,
+    }:
+    {
+      name = "contracts_${contractName}_${testName}";
+      nodes.machine =
+        { config, ... }:
+        {
+          imports = extraModules ++ [ nodeModule ];
+          config = lib.setAttrByPath (
+            [
+              "contracts"
+              contractName
+              "want"
+            ]
+            ++ wantPath
+            ++ [ "request" ]
+          ) (requestOf config);
+        };
+      testScript =
+        { nodes, ... }:
+        testScript {
+          result = lib.getAttrFromPath (
+            [
+              "contracts"
+              contractName
+              "results"
+            ]
+            ++ wantPath
+          ) nodes.machine;
+          inherit nodes;
+        };
+    };
+}
diff --git a/lib/contracts/module.nix b/lib/contracts/module.nix
new file mode 100644
index 0000000000000..ecebbfc807793
--- /dev/null
+++ b/lib/contracts/module.nix
@@ -0,0 +1,741 @@
+{ lib, config, ... }:
+let
+  inherit (lib) mkOption types;
+  inherit (types)
+    attrsOf
+    enum
+    nestedAttrsOf
+    nullOr
+    raw
+    submodule
+    ;
+  # `or` fallback allows the docs build sandbox to evaluate this module:
+  # the sandbox passes a fake `config` via `specialArgs` that lacks this attribute.
+  contractDefinitions = config.contractDefinitions or lib.contracts;
+
+  # A provider *reference* (`{ module, contract? }`) like `raw`, but mergeable:
+  # multiple definitions are allowed as long as they all agree on
+  # `module.loc` (the only field routing reads -- `routedName` matches a
+  # reference to a provider by its `module.loc`). `raw`'s `mergeOneOption`
+  # throws on any second definition; `mergeEqualOption` cannot help because two
+  # references to the same provider differ in `module.value` (a thunk/function,
+  # never `==`). Comparing only `module.loc` lets the legitimate duplicates a
+  # node can accumulate -- e.g. a host that co-locates several apps, each of
+  # whose routing modules sets the same node-wide `defaultProvider` -- collapse
+  # to one, while still rejecting a genuine conflict (two different providers).
+  # Used for the single-reference `defaultProvider` option; the nested
+  # `instances` tree uses `mergeableRaw` (see below) at its leaves instead.
+  providerRefType = lib.mkOptionType {
+    name = "providerRef";
+    description = "contract provider reference";
+    # Same permissive check as `raw`: a reference is an opaque `{ module; ... }`.
+    check = lib.types.raw.check;
+    merge =
+      loc: defs:
+      let
+        locOf = def: def.value.module.loc or null;
+        first = lib.head defs;
+        firstLoc = locOf first;
+        allAgree = lib.all (def: locOf def == firstLoc) defs;
+      in
+      if allAgree then
+        first.value
+      else
+        throw "The option `${lib.showOption loc}' has conflicting provider references (different `module.loc`) from: ${
+          lib.concatMapStringsSep ", " (def: def.file) defs
+        }.";
+  };
+
+  # `raw` for a provider-reference tree, but with a proper leaf merge: agreeing
+  # duplicate definitions collapse, genuine conflicts throw. `raw`'s own merge
+  # is `mergeOneOption`, which rejects any second definition -- even an identical
+  # one -- so a combined node whose co-located apps each route a shared instance
+  # to the same provider would spuriously fail. `mergeEqualOption` is the
+  # standard nixpkgs "merge properly" for such opaque leaves. `instances` leaves
+  # are provider references that `nestedAttrsOf` recurses into (their sub-tree
+  # keys `module`/`contract` are opaque to `raw`), so this merge only fires at
+  # the genuine scalar leaves, where identical references are byte-equal and a
+  # real conflict differs.
+  mergeableRaw = raw // {
+    merge = lib.mergeEqualOption;
+  };
+in
+{
+  options = {
+    contractDefinitions = mkOption {
+      description = ''
+        Types of contracts.
+        For info on how to instantiate these, see `config.contracts`.
+
+        To create a new contract type, add an instance of `config.contractDefinitions."<name>"`
+        defining `meta` and `interface` options, or when adding to nixpkgs,
+        preferably adding one in `lib/contracts`.
+
+        Nixpkgs-shipped contract types (`lib.contracts`) are available automatically
+        via a fallback in `contracts` option generation. Additional (user-defined)
+        contract types added here are merged alongside the lib-shipped ones.
+
+        **Integrating into a new module system** (e.g. home-manager, nix-darwin):
+
+        1\. Import this module (`lib.contract.module`).
+
+        2\. Seed `config.contractDefinitions` with `lib.contracts` so that nixpkgs-shipped
+        contract definitions are available alongside any user-defined types.
+
+        Both steps are combined in a thin wrapper module; see
+        `nixos/modules/contracts/default.nix` for the reference implementation.
+      '';
+      # types are in `lib` as the docs build's sandbox has no `config`.
+      type = attrsOf lib.contract.definitionType;
+    };
+    contracts = mkOption {
+      description = ''
+        Contract instances, keyed by contract type.
+
+        This option is system-agnostic - it works identically in NixOS
+        and any module system that imports `lib.contract.module`.
+
+        Consumers set `contracts.<type>.want`, providers set `contracts.<type>.providers`,
+        and results are read from `contracts.<type>.results`.
+      '';
+      type = submodule {
+        options = lib.mapAttrs (
+          contractName: contractType:
+          let
+            inherit (contractType) meta interface;
+            wantType = nestedAttrsOf (submodule {
+              options = {
+                request = mkOption {
+                  description = ''
+                    The request parameters.
+                    Must match the `${contractName}` contract interface's request type.
+                  '';
+                  type = submodule {
+                    imports = interface.extraImports.request;
+                    options = interface.request;
+                  };
+                };
+                result = mkOption {
+                  description = ''
+                    Result returned to the request by the provider's side of the `${contractName}` contract.
+                    Must match the `${contractName}` contract interface's result type.
+                  '';
+                  type = submodule {
+                    imports = interface.extraImports.result;
+                    options = interface.result;
+                  };
+                };
+              };
+            });
+          in
+          mkOption {
+            description = ''
+              ${meta.description}
+
+              Providers for the contract may be implemented by defining an option as follows:
+
+              ```nix
+              { lib, config, ... }:
+              let
+                inherit (lib.contract.forModule config) ${contractName};
+                # or, outside of modules NixOS wants to build sandboxed for the manual:
+                # inherit (config.contracts) ${contractName};
+              in
+              {
+                options = {
+                  ${contractName} = lib.mkOption {
+                    description = ${"'"}'
+                      Instances of contract `${contractName}`, including contract request/result and provider-specific options.
+
+                      Option `config.contracts.${contractName}.instances` refers to providers' options like this one.
+                    ${"'"}';
+                    example = lib.literalExpression ${"'"}'
+                      {
+                        "<consumer>"."<instance>" = {
+                          request = {
+                            # options shared between any provider of the `${contractName}` contract
+                            # "<attr>" = ...;
+                          };
+                          # provider-specific options:
+                          # "<opt>" = ...;
+                        };
+                      }
+                    ${"'"}';
+                    type = ${contractName}.mkProviderType {
+                      # overrides.request = { "<attr>".default = ...; };
+                      # overrides.result  = { "<attr>".default = ...; };
+                      # providerOptions = {
+                      #   "<opt>" = lib.mkOption {
+                      #     type = lib.types."<type>";
+                      #     description = "A provider-specific option.";
+                      #   };
+                      # };
+                      fulfill = request: {
+                        # "<attr>" = ...;
+                      };
+                      # fulfill' = { request, name }: { ... };  # variant exposing instance name
+                    };
+                  };
+                };
+              }
+              ```
+            '';
+            type = submodule (
+              contract:
+              let
+                # Resolve a provider reference (`{ module, contract? }`) to the
+                # provider's contract instances - the `instances` apply, lifted
+                # out so `resolvedInstances` and `providerRequests` share it.
+                resolveRef =
+                  v:
+                  if v.contract or null != null then
+                    lib.getAttrFromPath v.contract v.module.value
+                  else if v.module.value ? ${contractName} then
+                    v.module.value.${contractName}
+                  else
+                    v.module.value;
+                # The `providers` key whose registration references the same
+                # option as `ref` (matched on `module.loc`, a list of strings
+                # cheap to force - unlike the provider's value, which may not
+                # even evaluate outside its own NixOS context). `null` when no
+                # provider matches (e.g. a hand-written resolved instance).
+                routedName =
+                  ref:
+                  lib.findFirst (
+                    name: contract.config.providers.${name}.module.loc or null == ref.module.loc or null
+                  ) null (lib.attrNames contract.config.providers);
+                # Walk the `instances` ref tree, applying `f path ref` at each
+                # leaf (`v ? module`). Path-aware so a ref nested above several
+                # leaves resolves per leaf. Non-ref attrsets recurse; non-attrs
+                # (already-resolved leaves) pass through.
+                resolveInstanceTree =
+                  f:
+                  let
+                    walk =
+                      path: v:
+                      if !lib.isAttrs v then
+                        v
+                      else if v ? module then
+                        f path v
+                      else
+                        lib.mapAttrs (n: walk (path ++ [ n ])) v;
+                  in
+                  walk [ ] contract.config.instances;
+                # Path-aware filter over a `nestedAttrsOf` tree, preserving
+                # structure: keep each leaf (per `wantType`'s leaf detection)
+                # only when `keep path leaf`, and prune now-empty namespaces.
+                filterNestedAttrs =
+                  keep:
+                  let
+                    recurse =
+                      path: v:
+                      if lib.isNestedAttrsLeaf lib.any wantType.nestedTypes.elemType v then
+                        lib.optionalAttrs (keep path v) v
+                      else
+                        lib.filterAttrs (_: sub: sub != { }) (lib.mapAttrs (n: recurse (path ++ [ n ])) v);
+                  in
+                  recurse [ ];
+              in
+              {
+                options = {
+                  want = mkOption {
+                    description = ''
+                      Requests declared by consumers of the `${contractName}` contract, consisting of
+                      request inputs and (once fulfilled) the provider's returned results.
+
+                      `want` uses `nestedAttrsOf`, so consumers can organize entries at any depth:
+
+                      ```nix
+                      contracts.${contractName}.want."<consumer>" = {
+                        secret = cfg.secret;                   # flat
+                        db.primary = cfg.primaryDb;             # grouped
+                        caches.region-a.fast = cfg.fastCache;   # deeply nested
+                      };
+                      ```
+
+                      Results mirror the same structure:
+                      `config.contracts.${contractName}.results."<consumer>".db.primary`, etc.
+
+                      **NixOS module consumer:**
+
+                      ```nix
+                      { lib, config, ... }:
+                      let
+                        cfg = config.services."<consumer>";
+                        inherit (lib.contracts) ${contractName};
+                      in
+                      {
+                        options.services."<consumer>"."<option>" = lib.mkOption {
+                          default = config.contracts.${contractName}.requests;
+                          type = ${contractName}.mkContract {
+                            request = {
+                              # "<attr>".default = ...;
+                            };
+                          };
+                        };
+
+                        config = {
+                          # NixOS modules namespace their own entries:
+                          contracts.${contractName}.want."<consumer>" = {
+                            inherit (cfg) <option>;
+                          };
+
+                          services."<consumer>"."<option>".result =
+                            config.contracts.${contractName}.results."<consumer>"."<option>";
+                        };
+                      }
+                      ```
+
+                      **Naming restrictions:**
+
+                      `want` uses `nestedAttrsOf`, which distinguishes namespace keys from leaf
+                      entries by checking whether an attrset's keys match the leaf submodule's
+                      option names. Because each leaf has options `request` and `result`,
+                      namespace keys (consumer names, option names) must not be literally
+                      `request` or `result` - otherwise they would be misidentified as leaves.
+
+                      See `providers` for how providers register themselves.
+                    '';
+                    type = wantType;
+                    default = { };
+                  };
+                  requests = mkOption {
+                    description = ''
+                      Request data for the `${contractName}` contract, with `result` attributes filtered out.
+
+                      Providers read from this option to get consumer requests.
+
+                      Only canonical request options (those declared in `interface.request`) are included.
+                      Deprecated aliases added via `interface.extraImports.request` are intentionally excluded.
+                    '';
+                    type = nestedAttrsOf raw;
+                    default = lib.mapNestedAttrs' wantType (v: {
+                      request = lib.getAttrs (lib.attrNames interface.request) v.request;
+                    }) contract.config.want;
+                    defaultText = lib.literalExpression ''
+                      lib.mapNestedAttrs' wantType
+                        (v: { request = lib.getAttrs (lib.attrNames interface.request) v.request; })
+                        contract.config.want
+                    '';
+                  };
+                  providers = mkOption {
+                    description = ''
+                      Where to find instances of a provider of the `${contractName}` contract that can take request inputs to return results.
+
+                      Each entry is `{ module, contract? }` where `module` is
+                      the provider's option set (so `.loc` is reachable for GUI
+                      generation) and `contract` is the relative path within
+                      `module.value` to the contract instances. `contract` is
+                      inferred when omitted: `[ "${contractName}" ]` if
+                      `module.value` has that attribute (the conventional
+                      sub-option naming), otherwise `[ ]` (i.e. `module` is
+                      itself the contract-typed option).
+
+                      ```nix
+                      contracts.${contractName}.providers."<provider>".module = options."<provider>";
+                      ```
+
+                      Per-instance overrides are written by setting an
+                      `instances.<consumer>.<...>` leaf to a provider entry
+                      directly; the `instances` option's `apply` resolves the
+                      reference at the matching path.
+
+                      For an easier way to pick a single provider for every
+                      instance, consider `defaultProvider` / `defaultProviderName`.
+                    '';
+                    type = attrsOf raw;
+                  };
+                  defaultProvider = mkOption {
+                    description = ''
+                      The default provider for the `${contractName}` contract, alongside its configuration.
+                      Like `providers.<name>`, this is conventionally
+                      `{ module, contract? }` (with `module.value`/`module.loc`),
+                      not the resolved config value directly.
+
+                      Setting this for a contract means you no longer need to set providers for individual `instances`:
+
+                      ```nix
+                      contracts.${contractName}.defaultProvider = config.contracts.${contractName}.providers."<provider>";
+                      ```
+
+                      May also be set indirectly via `defaultProviderName`.
+                    '';
+                    type = nullOr providerRefType;
+                    default =
+                      if contract.config.defaultProviderName == null then
+                        null
+                      else
+                        contract.config.providers.${contract.config.defaultProviderName};
+                    defaultText = lib.literalExpression ''
+                      if contracts.${contractName}.defaultProviderName == null then null
+                      else contracts.${contractName}.providers.''${contracts.${contractName}.defaultProviderName}
+                    '';
+                    example = lib.literalExpression ''
+                      config.contracts.fileSecrets.providers.hardcoded-secret
+                    '';
+                  };
+                  defaultProviderName = mkOption {
+                    description = ''
+                      The name of the default provider for the `${contractName}` contract.
+                      Convenience alias for `defaultProvider`: picks `providers."<name>"` by
+                      name rather than reference.
+
+                      ```nix
+                      contracts.${contractName}.defaultProviderName = "<provider>";
+                      ```
+                    '';
+                    type = nullOr (enum (lib.attrNames contract.config.providers));
+                    default = null;
+                  };
+                  instances = mkOption {
+                    description = ''
+                      Instances of the `${contractName}` contract.
+                      By default extracts the contract instances from
+                      `defaultProvider.module.value` (using `defaultProvider.contract`,
+                      defaulting to `[ "${contractName}" ]`), if set, but may be
+                      overridden per instance.
+
+                      Each leaf is a provider reference `{ module, contract? }`
+                      (same shape as `providers.<name>`); `resolvedInstances`
+                      resolves it path-aware to the provider's instance at the
+                      matching path, and `providerRequests` resolves it to the
+                      routed provider's name. GUIs read the override as a typed
+                      reference rather than an opaque value.
+
+                      Per-instance overrides compose against the
+                      `defaultProvider`-derived tree without
+                      `lib.recursiveUpdate`: `nestedAttrsOf` runs priority
+                      filtering at each leaf, so a `mkDefault` /
+                      `mkOptionDefault`-priority default at one path is
+                      preserved when another module sets a normal-priority
+                      override at a sibling path.
+
+                      ```nix
+                      contracts.${contractName}.defaultProvider = config.contracts.${contractName}.providers."<default>";
+                      contracts.${contractName}.instances."<consumer>"."<instance>" =
+                        config.contracts.${contractName}.providers."<other>";
+                      ```
+
+                      Used in the consumer like:
+
+                      ```nix
+                      { lib, ... }:
+                      let
+                        inherit (lib.contracts) ${contractName};
+                        inherit (config.contracts.${contractName}.results."<consumer>") <instance>;
+                      in
+                      {
+                        options = {
+                          "<instance>" = lib.mkOption {
+                            description = ${"'"}'
+                              An instance of contract `${contractName}`.
+                              See `contracts.${contractName}.want.<name>.<name>.result`
+                              for documentation on the type of its `.result` attribute.
+                              Information specific to the provider may be set like:
+
+                              ```nix
+                              services."<provider>".${contractName}."<consumer>"."<instance>"."<attr>" = ...;
+                              ```
+                            ${"'"}';
+                            default.result = <instance>;
+                            defaultText = lib.literalExpression ${"'"}'
+                              { result = config.contracts.${contractName}.results."<consumer>"."<instance>"; }
+                            ${"'"}';
+                            type = ${contractName}.mkContract {
+                              request = {
+                                # "<attr>".default = ...;
+                              };
+                            };
+                          };
+                        };
+                      }
+                      ```
+                    '';
+                    # Holds the per-leaf provider references (no `apply`): both
+                    # `resolvedInstances` (ref -> instance value) and
+                    # `providerRequests` (ref -> routed provider name) derive from
+                    # this ref tree, so the routing decision has a single source
+                    # of truth that retains the reference (hence its `module.loc`,
+                    # needed to recover the provider name).
+                    #
+                    # `mergeableRaw` (not plain `raw`) at the leaf: this is the
+                    # only `contracts.*` tree that takes definitions from multiple
+                    # modules at once (the others -- `requests`,
+                    # `resolvedInstances`, `providerRequests` -- are computed from a
+                    # single default), so it is the only one that needs leaves to
+                    # merge rather than reject a second definition. A combined node
+                    # co-locating several apps has each app's routing module route
+                    # a shared instance (e.g. `mail.<group>`) to the same provider;
+                    # `raw`'s `mergeOneOption` would reject the identical second
+                    # definition. `mergeEqualOption` (via `mergeableRaw`) collapses
+                    # agreeing definitions and still throws on a genuine conflict.
+                    type = nestedAttrsOf mergeableRaw;
+                    # No option-level default: the docs build sandbox evaluates
+                    # option defaults, and the assertion below must not fire there.
+                    # The actual default is provided via `config.instances` in the
+                    # submodule's config block (only evaluated at config time).
+                  };
+                  resolvedInstances = mkOption {
+                    description = ''
+                      Resolved instances of the `${contractName}` contract: the
+                      `instances` provider-reference tree with each leaf resolved
+                      path-aware to the provider's instance at its path.
+
+                      A computed, read-only view of `instances`. Already-resolved
+                      instance attrsets at leaves pass through unchanged - the
+                      resolution can't tell them apart from values produced by
+                      resolving a ref higher up - but writing them by hand defeats
+                      GUI introspection and is discouraged.
+                    '';
+                    type = nestedAttrsOf raw;
+                    # Resolve provider-reference leaves (`{ module, contract? }`)
+                    # to the provider's instance at the matching path. Path-aware
+                    # so a ref at `<consumer>.<instance>` resolves to that
+                    # provider's specific consumer/instance, not its full tree.
+                    # Computed but overridable (like `requests` / `results`) so a
+                    # cross-eval bridge can force-inject the containing system's
+                    # resolution (see `lib/services/lib.nix`).
+                    default = resolveInstanceTree (path: ref: lib.getAttrFromPath path (resolveRef ref));
+                    defaultText = lib.literalExpression ''
+                      <config.contracts.${contractName}.instances with each provider reference resolved to its instance>
+                    '';
+                  };
+                  providerRequests = mkOption {
+                    description = ''
+                      Request data for the `${contractName}` contract, grouped by
+                      the provider each request is routed to.
+
+                      `providerRequests."<provider>"` mirrors `requests` but
+                      contains only the leaves whose `instances` reference resolves
+                      to `"<provider>"` (honoring both `defaultProviderName` /
+                      `defaultProvider` and per-instance `instances` overrides).
+                      Every declared provider gets an entry, empty when no request
+                      routes to it.
+
+                      A provider option's `default` should read its own slice so it
+                      gathers only the requests routed to it:
+
+                      ```nix
+                      default = config.contracts.${contractName}.providerRequests."<provider>";
+                      ```
+                    '';
+                    type = attrsOf (nestedAttrsOf raw);
+                    # For each declared provider, keep the `requests` leaves whose
+                    # resolved routing names that provider. `routedName` resolves a
+                    # leaf reference to the matching `providers` key by comparing
+                    # `module.loc` (cheap to force, unlike the provider's value).
+                    # Computed but overridable (like `requests` / `results`) so a
+                    # cross-eval bridge can force-inject the containing system's
+                    # routing (see `lib/services/lib.nix`).
+                    default =
+                      let
+                        providerNames = lib.attrNames contract.config.providers;
+                        routedNames = resolveInstanceTree (_path: routedName);
+                      in
+                      lib.genAttrs providerNames (
+                        providerName:
+                        filterNestedAttrs (
+                          path: _request: (lib.attrByPath path null routedNames) == providerName
+                        ) contract.config.requests
+                      );
+                    defaultText = lib.literalExpression ''
+                      <config.contracts.${contractName}.requests grouped by routed provider name>
+                    '';
+                  };
+                  results = mkOption {
+                    description = ''
+                      Result data for the `${contractName}` contract, with `request` attributes filtered out.
+
+                      A computed option that extracts the result values from fulfilled contracts.
+                      It mirrors `requests` which filters to just request data for providers.
+
+                      **NixOS module consumer** - results are under the consumer name chosen in `want`:
+
+                      ```nix
+                      { lib, config, ... }:
+                      let
+                        inherit (lib.contracts) ${contractName};
+                        inherit (config.contracts.${contractName}.results."<consumer>") <option>;
+                      in
+                      {
+                        options.services."<consumer>"."<option>" = lib.mkOption {
+                          description = ${"'"}'
+                            An instance of contract `${contractName}`.
+                            See `contracts.${contractName}.want.<name>.<name>.result`
+                            for documentation on the type of its `.result` attribute.
+                            Information specific to the provider may be set like:
+
+                            ```nix
+                            services."<provider>".${contractName}."<consumer>"."<option>"."<attr>" = ...;
+                            ```
+                          ${"'"}';
+                          default.result = <option>;
+                          defaultText = lib.literalExpression ${"'"}'
+                            { result = config.contracts.${contractName}.results."<consumer>"."<option>"; }
+                          ${"'"}';
+                          type = ${contractName}.mkContract {
+                            request = {
+                              # "<attr>".default = ...;
+                            };
+                          };
+                        };
+                      }
+                      ```
+                    '';
+                    type = nestedAttrsOf raw;
+                    default =
+                      if contract.config.defaultProvider == null && contract.config.want == { } then
+                        # No consumers and no provider (e.g. docs sandbox) -- safe empty.
+                        { }
+                      else
+                        lib.mapNestedAttrs' wantType (v: v.result) contract.config.resolvedInstances;
+                    defaultText = lib.literalExpression ''
+                      lib.mapNestedAttrs' wantType
+                        (v: v.result)
+                        config.contracts.${contractName}.resolvedInstances
+                    '';
+                  };
+                  mkProviderType = mkOption {
+                    description = ''
+                      Make the type for an option to provider for the ${contractName} contract.
+
+                      Note that, for options that must work in the sandbox of the NixOS manual builds,
+                      one should instead use `(lib.contract.forModule config).${contractName}.mkProviderType`.
+
+                      Unlike `contractDefinitions.${contractName}._mkProviderType`, automatically
+                      forwards consumer `want` request data into each leaf at `mkDefault` priority (1000),
+                      so provider-specific options do not silently mask consumer `want`s via
+                      `nestedAttrsOf` leaf-level priority filtering.
+
+                      `config.contracts.<contract>.mkProviderType :: { providerOptions?, overrides?, fulfill?, fulfill'? } -> optionType`
+
+                      **Inputs:**
+
+                      `overrides`
+
+                      : 1\. Overrides for `{ request, result }` submodule types (to e.g. add defaults)
+
+                      `providerOptions`
+
+                      : 2\. Additional option declarations of the provider outside of the contract's request/result.
+
+                      `fulfill`
+
+                      : 3\. Optional function `request -> result` that derives result values
+                      from request values. Applied with `mkDefault` priority so explicit
+                      result settings take precedence. Use `fulfill'` if the result also
+                      needs the instance `name`.
+
+                      `fulfill'`
+
+                      : 4\. Optional function `{ request, name } -> result`. Lower-level
+                      variant of `fulfill` exposing the instance `name`. At most one of
+                      `fulfill` / `fulfill'` may be set.
+
+                      `_requests`
+
+                      : 5\. Internal. Pre-bound by `contracts.<contract>.mkProviderType`, which is the
+                      recommended call site for providers. Forwards consumer `want` request data
+                      into each leaf at `mkDefault` priority (1000) so provider-specific options
+                      do not silently mask consumer wants via `nestedAttrsOf` leaf-priority filtering.
+
+                      **Example:**
+
+                      ```nix
+                      { lib, config, options, ... }:
+                      let
+                        inherit (config.contracts) arithmetic;
+                      in
+                      {
+                        imports = [
+                          # simple dummy contract with request/result both shaped `{ value: int }`
+                          <nixpkgs/nixos/tests/contracts/arithmetic-contract.nix>
+                        ];
+                        options.services.increment.arithmetic = lib.mkOption {
+                          default = arithmetic.providerRequests.increment;
+                          type = arithmetic.mkProviderType {
+                            fulfill = request: {
+                              value = request.value + 1;
+                            # };
+                          };
+                        };
+                        config = {
+                          contracts.arithmetic.providers.increment.module = options.services.increment.arithmetic;
+                        };
+                      }
+                      ```
+                    '';
+                    type = types.functionTo types.optionType;
+                    readOnly = true;
+                    default = args: contractType._mkProviderType (args // { _requests = contract.config.requests; });
+                  };
+                };
+                # Provide the asserting default for `instances` via config rather
+                # than on the option itself: the docs build sandbox evaluates option
+                # defaults but does not evaluate submodule config blocks.
+                #
+                # `defaultProvider` is conventionally a provider reference
+                # `{ module, contract? }` (resolved path-aware by
+                # `resolvedInstances` / `providerRequests`) but may also be a raw
+                # `nestedAttrsOf` tree of pre-resolved instances. Either way: walk
+                # each `want`-leaf path and set a `mkOptionDefault`-priority value
+                # at that path - either the whole providerRef (resolution picks the
+                # per-path slice) or the tree's value at that path. Wrapping each leaf
+                # individually (rather than the whole tree) lets per-leaf
+                # overrides from other modules compose against the default
+                # via `nestedAttrsOf`'s leaf-level priority handling.
+                config.instances =
+                  let
+                    provider = contract.config.defaultProvider;
+                    # Walk `want` with explicit recursion (vs.
+                    # `concatMapNestedAttrs'` whose `mergeAttrs` fold loses
+                    # sibling leaves at depth > 1) to produce a tree mirroring
+                    # `want` with `mkOptionDefault`-wrapped leaves - `resolvedInstances` /
+                    # `providerRequests` then resolve each leaf path-aware.
+                    #
+                    # Each leaf's `mkOptionDefault` carries the `defaultProvider`
+                    # reference, so a leaf left unset falls back to the default
+                    # provider. When there is no `defaultProvider`, the leaf's
+                    # default is instead an "unrouted" marker: a per-instance
+                    # `instances` override (normal priority) at that leaf wins and
+                    # replaces it, so instances-only routing is allowed; a leaf
+                    # routed by neither a default nor an override stays unrouted.
+                    # This is per-leaf, so the unrouted state never affects leaves
+                    # that *are* routed by an override -- unlike a single
+                    # whole-tree `assert want == {}`, which rejected any `want` the
+                    # moment `defaultProvider` was unset.
+                    #
+                    # The marker is shaped like a provider reference (`{ module = {
+                    # loc; value; }; }`) so it is a leaf to `resolveInstanceTree`
+                    # (`v ? module`) without forcing anything: `routedName` forces
+                    # only `module.loc` (a sentinel matching no provider, so the
+                    # leaf is absent from every `providerRequests` -- routedness is
+                    # safe to read), while `resolvedInstances`/`results` force
+                    # `module.value` and surface the error -- only when a result
+                    # for the unrouted leaf is actually demanded.
+                    leafDefault =
+                      if provider != null then
+                        assert lib.assertMsg (
+                          provider ? module
+                        ) "contracts.${contractName}.defaultProvider must be a provider reference `{ module, contract? }`.";
+                        lib.mkOptionDefault provider
+                      else
+                        lib.mkOptionDefault {
+                          module = {
+                            loc = [ "<contracts.${contractName}: unrouted>" ];
+                            value = throw "contracts.${contractName}: an instance is `want`ed but routed to no provider. Set `contracts.${contractName}.defaultProvider`/`defaultProviderName`, or route this instance via `contracts.${contractName}.instances`.";
+                          };
+                        };
+                    buildDefaultTree =
+                      subWant: if subWant ? request then leafDefault else lib.mapAttrs (_: buildDefaultTree) subWant;
+                  in
+                  buildDefaultTree contract.config.want;
+              }
+            );
+          }
+        ) contractDefinitions;
+      };
+    };
+  };
+
+}
diff --git a/lib/default.nix b/lib/default.nix
index 751738a98965d..64f202fa33e93 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -72,6 +72,10 @@ let
       options = callLibs ./options.nix;
       types = callLibs ./types.nix;
 
+      # contracts
+      contract = callLibs ./contracts;
+      contracts = callLibs ./contracts/definitions;
+
       # constants
       licenses = callLibs ./licenses;
       sourceTypes = callLibs ./source-types.nix;
@@ -256,6 +260,11 @@ let
         isAttrs
         intersectAttrs
         removeAttrs
+        isNestedAttrsLeaf
+        mapNestedAttrs'
+        mapNestedAttrsWith
+        concatMapNestedAttrsWith
+        concatMapNestedAttrs'
         ;
       inherit (self.lists)
         singleton
@@ -473,6 +482,9 @@ let
         ;
       inherit (self.modules)
         evalModules
+        evalOption
+        extendOption
+        extendSubmodule
         setDefaultModuleLocation
         unifyModuleSyntax
         applyModuleArgsIfFunction
diff --git a/lib/modules.nix b/lib/modules.nix
index c5c935144ea64..42e5e761057f8 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -1435,6 +1435,48 @@ let
         inherit highestPrio;
       };
 
+  /**
+    Run the module-system property pipeline (`mkMerge` / `mkIf`
+    discharging followed by `mkOverride` priority filtering) on a list
+    of definitions.
+
+    Intended for option types that handle their own per-leaf priority
+    composition - e.g. tree-shaped types like `nestedAttrsOf` whose
+    `merge` walks into sub-paths that the top-level pipeline (run by
+    `mergeDefinitions`) doesn't reach. Returns the same shape as
+    `filterOverrides'`: a `values` list of definitions stripped of
+    their override wrappers, plus the surviving `highestPrio`.
+
+    `lib.modules.applyLeafProperties :: [{ file; value }] -> { values; highestPrio }`
+
+    # Inputs
+
+    `defs`
+
+    : 1\. List of `{ file, value }` definitions for one logical leaf.
+
+    # Example
+
+    ```nix
+    # Inside an option type's `merge`:
+    let
+      processed = lib.modules.applyLeafProperties subDefs;
+    in
+    elemType.merge loc processed.values
+    ```
+  */
+  applyLeafProperties =
+    defs:
+    filterOverrides' (
+      concatMap (
+        d:
+        map (v: {
+          inherit (d) file;
+          value = v;
+        }) (dischargeProperties d.value)
+      ) defs
+    );
+
   /**
     Sort a list of properties.  The sort priority of a property is
     defaultOrderPriority by default, but can be overridden by wrapping the property
@@ -2143,6 +2185,153 @@ let
     config = lib.importTOML file;
   };
 
+  /**
+    Evaluate a configuration in the context of a corresponding module system option.
+
+    lib.evalOption :: option -> attrs -> attrs
+
+    # Inputs
+
+    `option`
+
+    : 1\. Module system option in which to evaluate the configuration
+
+    `conf`
+
+    : 2\. Configuration to evaluate within the option
+
+    # Example
+
+    ```nix
+    lib.evalOption
+      (lib.mkOption {
+        default = { };
+        type = lib.types.submodule {
+          options.foo = lib.mkOption { type = lib.types.int; };
+        };
+      })
+      { foo = 1; }
+    # => { foo = 1; }
+    ```
+  */
+  evalOption =
+    option: conf:
+    (evalModules {
+      modules = [
+        {
+          options.opt = option;
+          config.opt = conf;
+        }
+      ];
+    }).config.opt;
+
+  /**
+    Extend a (sub-)module option with a set of overrides.
+
+    lib.extendOption :: attrs -> option -> option
+
+    # Inputs
+
+    `overrides`
+
+    : 1\. A (recursive) attrset of fields to add to the option
+
+    `opt`
+
+    : 2\. Option to extend with `overrides`
+
+    # Example
+
+    ```nix
+    lib.extendOption
+      { bar.default = 10; }
+      (lib.mkOption {
+        type = lib.types.submodule {
+          options.bar = lib.mkOption { type = lib.types.int; };
+        };
+      })
+    ```
+  */
+  extendOption =
+    overrides: opt:
+    let
+      inherit (opt) type;
+      isSubmodule = lib.isOptionType type && type.name == "submodule";
+      # (deduplicated) keys from submodules to iterate over
+      # we don't need the values, but attrset offers O(1) containment checks
+      subOptions = optionalAttrs isSubmodule (
+        lib.attrsets.mergeAttrsList (map (mod: mod.options or { }) type.getSubModules)
+      );
+      subOverrides = lib.filterAttrs (k: _: subOptions ? ${k}) overrides;
+      directOverrides = lib.filterAttrs (k: _: !(subOptions ? ${k})) overrides;
+    in
+    mkOption (
+      # re-wrap existing option attributes
+      (removeAttrs opt [ "_type" ])
+      # if we are annotating something that isn't a sub-module,
+      # just override relevant attributes on the option
+      // directOverrides
+      # to annotate a sub-module, presume we should just annotate its sub-options,
+      # which we iterate over to reconstruct with relevant annotations.
+      // optionalAttrs isSubmodule {
+        default = { };
+        type = lib.types.submoduleWith (
+          # meta we will not change
+          type.functor.payload
+          # modules are the parameter that will change as per our overrides
+          // {
+            modules = [
+              {
+                options = mapAttrs (
+                  k: _:
+                  let
+                    # option for the attribute in question: for now presume just one sub-module had it
+                    attrOpt = (head (filter (m: (m.options or { }) ? ${k}) type.getSubModules)).options.${k};
+                    # any overrides for the attribute in question
+                    attrOverrides = subOverrides.${k} or { };
+                  in
+                  # recurse until we have no more overrides to annotate the option with
+                  if attrOverrides != { } then extendOption attrOverrides attrOpt else attrOpt
+                ) subOptions;
+              }
+            ];
+          }
+        );
+      }
+    );
+
+  /**
+    Extend a (sub-)module type with a set of overrides.
+
+    lib.extendSubmodule :: attrs -> optionType -> optionType
+
+    # Inputs
+
+    `overrides`
+
+    : 1\. A (recursive) attrset of fields to add to the option
+
+    `mod`
+
+    : 2\. A (sub-)module type to extend with `overrides`
+
+    # Example
+
+    ```nix
+    lib.extendSubmodule
+      { bar.default = 10; }
+      (lib.types.submodule {
+        options.bar = lib.mkOption { type = lib.types.int; };
+      })
+    ```
+  */
+  extendSubmodule =
+    overrides: mod:
+    (extendOption overrides (mkOption {
+      default = { };
+      type = mod;
+    })).type;
+
   private =
     mapAttrs
       (
@@ -2292,11 +2481,15 @@ private
   #       are just needed by types.nix, but are not meant to be consumed
   #       externally.
   inherit
+    applyLeafProperties
     defaultOrderPriority
     defaultOverridePriority
     doRename
     evalModules
+    evalOption
     evalOptionValue # for use by lib.types
+    extendOption
+    extendSubmodule
     filterOverrides
     filterOverrides'
     fixMergeModules
diff --git a/lib/services/lib.nix b/lib/services/lib.nix
index 02587b6bc810d..7599507874eb2 100644
--- a/lib/services/lib.nix
+++ b/lib/services/lib.nix
@@ -8,6 +8,198 @@ let
     ;
 in
 rec {
+  /**
+    Jointly evaluate a set of modular services so their contracts resolve against each other.
+
+    Contract resolution is peer-to-peer across the `services` set.
+    As such, this is compatible with environments without a parent evaluation context (e.g. OCI).
+
+    Each service must import the contract-type modules it uses. The helper unions
+    contract type definitions across the peer set and handles `want`/`provider` aggregation.
+
+    A service that wants to be the default provider for a contract type sets
+    `contracts.<type>.defaultProvider` in its own module.
+    If multiple services declare a default for the same type, evaluation fails.
+
+    lib.services.evalServices :: { services: AttrSet } -> AttrSet
+
+    # Inputs
+
+    `services`
+
+    : 1\. An attrset mapping service slot names (strings) to service modules or lists of
+      modules. The slot name is each service's identity for contract resolution
+      (`want` entries are nested under it in the joint namespace).
+
+    # Example
+
+    ```nix
+    let
+      portable-lib = import <nixpkgs/lib/services/lib.nix> { inherit lib; };
+      result = portable-lib.evalServices {
+        services = {
+          consumer = ./consumer-service.nix;
+          provider = ./provider-service.nix;
+        };
+      };
+    in
+    result.contracts.myContract.results.consumer.myOption.someField
+    ```
+  */
+  evalServices =
+    { services }:
+    let
+      toModules = v: if lib.isList v then v else [ v ];
+
+      baseModules =
+        name: serviceModules:
+        toModules serviceModules
+        ++ [
+          (lib.modules.importApply ./service.nix {
+            pkgs = throw "evalServices: pkgs is not available in this evaluation context";
+          })
+          { _module.args.name = name; }
+        ];
+
+      # Per-service configs without upstream seeding. Used for joint computation
+      # (`want`/`providers`/`contractDefinitions`) so that accessing these write-side
+      # options does not create a dependency on the joint contracts being resolved.
+      baseEvaluated = lib.mapAttrs (
+        name: serviceModules:
+        (lib.evalModules {
+          class = "service";
+          modules = baseModules name serviceModules;
+        }).config
+      ) services;
+
+      # Union of contract type definitions declared across the peer set.
+      # Each service must import the contract-type modules it uses so that
+      # `contractDefinitions` is populated without depending on `joint`.
+      jointContractDefinitions = lib.foldl' (
+        acc: service:
+        acc // lib.mapAttrs (_: def: { inherit (def) meta interface; }) service.contractDefinitions
+      ) { } (lib.attrValues baseEvaluated);
+
+      # Aggregate `want`/`providers`/`defaultProviderName` per type across all peers,
+      # then resolve via the contracts module's own logic. `want` is nested under
+      # each service's slot name to match the `results.<slot>.*` structure.
+      joint =
+        (lib.evalModules {
+          modules = [
+            lib.contract.module
+            {
+              options.meta = lib.mkOption {
+                type = lib.types.attrs;
+                default = { };
+              };
+            }
+            { contractDefinitions = jointContractDefinitions; }
+            (
+              { config, ... }:
+              {
+                contracts = lib.mapAttrs (
+                  contractType: _:
+                  let
+                    # `want` and `defaultProvider[Name]` come from `baseEvaluated` (no upstream)
+                    # so that collecting them does not force `joint` resolution.
+                    perServiceBase = lib.mapAttrsToList (serviceName: service: {
+                      inherit serviceName;
+                      want = service.contracts.${contractType}.want or { };
+                      defaultProviderName = service.contracts.${contractType}.defaultProviderName or null;
+                    }) baseEvaluated;
+                    # `providers` come from `evaluated` (with upstream) so provider instances
+                    # see all consumers' requests when resolving results. Laziness breaks the
+                    # apparent mutual dependency: `joint.requests` is computed from `want`
+                    # (`baseEvaluated`) and never forces `joint.instances` or `joint.results`.
+                    perServiceEval = lib.mapAttrsToList (serviceName: service: {
+                      providers = service.contracts.${contractType}.providers or { };
+                    }) evaluated;
+                    defaultProviderName = lib.filter (e: e.defaultProviderName != null) perServiceBase;
+                    # Detect services that set `defaultProvider` directly (not via `defaultProviderName`).
+                    # In `baseEvaluated` (no upstream injection), `defaultProvider` is non-null
+                    # only when the user assigned it explicitly. Exclude services that already
+                    # set `defaultProviderName` (handled above) to avoid double-counting.
+                    # Detection uses `baseEvaluated`; the VALUE is read from `evaluated` so the
+                    # provider module's `module.value` reflects upstream-seeded requests. This
+                    # does not create a cycle because `evaluated` does not seed `defaultProvider`
+                    # from `joint` (only `requests` and `results` are seeded): the service's own
+                    # `defaultProvider = providers.increment` assignment resolves locally within
+                    # `evaluated` using its seeded `requests`.
+                    perServiceDefaultProvider = lib.filter (e: e.detected) (
+                      lib.mapAttrsToList (serviceName: service: {
+                        inherit serviceName;
+                        detected =
+                          service.contracts.${contractType}.defaultProviderName or null == null
+                          && service.contracts.${contractType}.defaultProvider or null != null;
+                      }) baseEvaluated
+                    );
+                  in
+                  {
+                    want = lib.listToAttrs (map (e: lib.nameValuePair e.serviceName e.want) perServiceBase);
+                    providers = lib.foldl' (acc: e: acc // e.providers) { } perServiceEval;
+                  }
+                  // lib.optionalAttrs (defaultProviderName != [ ]) {
+                    defaultProviderName =
+                      assert lib.assertMsg (lib.length defaultProviderName == 1)
+                        "evalServices: multiple services declared `defaultProviderName` for `${contractType}`: ${
+                          lib.concatMapStringsSep ", " (e: e.serviceName) defaultProviderName
+                        }";
+                      (lib.head defaultProviderName).defaultProviderName;
+                  }
+                  // lib.optionalAttrs (perServiceDefaultProvider != [ ]) {
+                    defaultProvider =
+                      assert lib.assertMsg (lib.length perServiceDefaultProvider == 1)
+                        "evalServices: multiple services declared `defaultProvider` for `${contractType}`: ${
+                          lib.concatMapStringsSep ", " (e: e.serviceName) perServiceDefaultProvider
+                        }";
+                      (evaluated.${(lib.head perServiceDefaultProvider).serviceName})
+                      .contracts.${contractType}.defaultProvider;
+                  }
+                ) config.contractDefinitions;
+              }
+            )
+          ];
+        }).config;
+
+      # Per-service configs, evaluated lazily. Each service's `contracts.*` is
+      # seeded from the joint resolution so it reads results by option name directly
+      # (no manual prefix). The seed propagates `requests` and `results` from the
+      # joint resolution; `defaultProvider` is intentionally NOT seeded so that
+      # services which set `defaultProvider = providers.<name>` can be read from
+      # `evaluated` in the `perServiceDefaultProvider` block above without creating
+      # a cycle (seeding `defaultProvider` from `joint` would depend on `evaluated`
+      # which would depend on `joint` again). Write-side options (`want`, `providers`)
+      # also remain local to each service.
+      #
+      # Enumerated over `jointContractDefinitions` (not `joint.contracts`) so that
+      # key enumeration does not force joint resolution.
+      evaluated = lib.mapAttrs (
+        name: serviceModules:
+        (lib.evalModules {
+          class = "service";
+          modules = baseModules name serviceModules ++ [
+            {
+              config.contracts = lib.mapAttrs (contractType: _: {
+                requests = lib.mkForce joint.contracts.${contractType}.requests;
+                results = lib.mkForce (joint.contracts.${contractType}.results.${name} or { });
+                # Seed the joint routing so a provider whose option `default`
+                # reads `providerRequests.<self>` gathers the requests routed
+                # to it. The provider registration (`providers`) is local to
+                # the service, but routing lives in the joint eval; depends on
+                # `joint` only (not `evaluated`), so it is cycle-safe like
+                # `requests`.
+                providerRequests = lib.mkForce joint.contracts.${contractType}.providerRequests;
+              }) jointContractDefinitions;
+            }
+          ];
+        }).config
+      ) services;
+    in
+    {
+      services = evaluated;
+      contracts = joint.contracts;
+    };
+
   flattenMapServicesConfigToList =
     f: loc: config:
     f loc config
@@ -41,8 +233,8 @@ rec {
 
     Each containing system (NixOS, ...) calls `configure` to
     obtain a `serviceSubmodule` type for its services option. The returned submodule
-    includes the portable service base and any service-manager-specific modules
-    passed via `extraRootModules`.
+    includes the portable service base, contract integration, and any
+    service-manager-specific modules passed via `extraRootModules`.
 
     **Implementing for a new system** (e.g. home-manager, nix-darwin):
 
@@ -57,16 +249,22 @@ rec {
         extraRootModules = [
           ./launchd-service.nix    # launchd-specific options (plist generation, etc.)
         ];
+        inherit (config) contracts;
+        upstreamContractDefinitions = config.contractDefinitions;
       };
     in
     {
+      imports = [
+        ./contracts-bridge.nix   # collects want/providers from services (see below)
+      ];
+
       options.services = lib.mkOption {
         type = lib.types.attrsOf modularServiceConfiguration.serviceSubmodule;
         default = { };
       };
 
       config = {
-        # Convert service tree -> launchd plists, assertions, etc.
+        # Convert service tree → launchd plists, assertions, etc.
         # (analogous to how NixOS converts to systemd units)
         launchd.agents = ...;
         assertions = ...;
@@ -75,25 +273,51 @@ rec {
     }
     ```
 
+    The bridge module auto-nests each service's `contracts.<type>.want` entries under
+    the service's tree path, then collects them (along with `providers`) into the
+    containing system's contract namespace. This prevents collisions between
+    independent services. See `nixos/modules/system/service/nixos-contracts-bridge.nix`
+    for the reference.
+
+    Services set `contracts.<type>.want`:
+
+    ```nix
+    contracts.fileSecrets.want = { inherit (cfg) mySecret; };
+    cfg.mySecret.result = config.contracts.fileSecrets.results.mySecret;
+    ```
+
+    The bridge handles namespacing transparently.
+    Contract state propagates automatically to sub-services at any nesting depth.
+
     lib.services.configure :: AttrSet -> { serviceSubmodule :: SubmoduleType }
 
     # Inputs
 
     `serviceManagerPkgs`
 
-    : 1\. A Nixpkgs instance used for built-in logic such as converting
+    : A Nixpkgs instance used for built-in logic such as converting
     `configData.<path>.text` to a store path.
 
     `extraRootModules`
 
-    : 2\. Modules to be loaded into the "root" service submodule, but not
+    : Modules to be loaded into the "root" service submodule, but not
     into its sub-`services`. That's the modules' own responsibility.
     Typically contains service-manager-specific option modules
     (e.g. systemd unit options, launchd plist options).
 
     `extraRootSpecialArgs`
 
-    : 3\. Fixed module arguments provided alongside `extraRootModules`.
+    : Fixed module arguments provided alongside `extraRootModules`.
+
+    `contracts`
+
+    : The containing system's `config.contracts` - injected into each service's
+    `contracts.*` options so services can read aggregated results and `defaultProvider`.
+
+    `upstreamContractDefinitions`
+
+    : The containing system's `config.contractDefinitions` - propagated into
+    each service's module system so user-defined contract types are available.
 
     # Output
 
@@ -106,14 +330,65 @@ rec {
       serviceManagerPkgs,
       extraRootModules ? [ ],
       extraRootSpecialArgs ? { },
+      contracts ? { },
+      # All NixOS-level contract type definitions (meta + interface), so services
+      # can use `contracts.<type>.*` for both lib-level and user-defined contract types.
+      upstreamContractDefinitions ? { },
     }:
     let
+      # Seeds the service's module system with upstream contract state.
+      #
+      # Injects resolved `results` and `defaultProvider` from the containing system
+      # directly into each service's `contracts.*` options. Results are scoped
+      # to this service's namespace so the service can read results via just the
+      # option name (no manual prefix needed).
+      #
+      # Write-side options (`want`, `providers`) remain local to the service.
+      # The system's contracts bridge reads these and lifts them to the containing system.
+      # A reference implementation for the NixOS case may be found at
+      # `nixos/modules/system/service/contracts-bridge.nix`.
+      upstreamSeedModule =
+        {
+          lib,
+          name,
+          config,
+          ...
+        }:
+        {
+          config = {
+
+            # Propagate contract type definitions so user-defined types are available.
+            # `mkDefault` lets service-declared definitions take precedence when present.
+            contractDefinitions = lib.mkDefault (
+              lib.mapAttrs (_: contract: {
+                inherit (contract) meta interface;
+              }) upstreamContractDefinitions
+            );
+
+            # Inject read-side contract options from the containing system,
+            # scoped to this service's namespace so the service can read
+            # results via just the option name (no manual prefix needed).
+            # Enumerate over the service's own `contractDefinitions` (not the full upstream
+            # set) so we only inject for types the service actually declares — avoids
+            # setting undeclared options and the error-message cycle that would follow.
+            contracts = lib.mapAttrs (contractType: _: {
+              requests = lib.mkForce contracts.${contractType}.requests;
+              results = lib.mkForce (contracts.${contractType}.results.${name} or { });
+              defaultProvider = lib.mkForce contracts.${contractType}.defaultProvider;
+              # Routing from the containing system, so a provider whose option
+              # `default` reads `providerRequests.<self>` gathers its routed
+              # requests (the provider registration is local to the service).
+              providerRequests = lib.mkForce contracts.${contractType}.providerRequests;
+            }) config.contractDefinitions;
+
+          };
+        };
       modules = [
         (lib.modules.importApply ./service.nix { pkgs = serviceManagerPkgs; })
       ];
       serviceSubmodule = types.submoduleWith {
         class = "service";
-        modules = modules ++ extraRootModules;
+        modules = modules ++ [ upstreamSeedModule ] ++ extraRootModules;
         specialArgs = extraRootSpecialArgs;
       };
     in
diff --git a/lib/services/service.nix b/lib/services/service.nix
index 1bcf0845f0d7e..07fd9673f6e79 100644
--- a/lib/services/service.nix
+++ b/lib/services/service.nix
@@ -1,11 +1,24 @@
 # Non-module arguments
 # These are separate from the module arguments to avoid implicit dependencies.
 # This makes service modules self-contains, allowing mixing of Nixpkgs versions.
+#
+# Portable service base module - imported into every modular service's module system.
+#
+# Defines the core service interface (`process.argv`, sub-`services`, `configData`)
+# and imports the contracts module. This is system-agnostic: it works regardless of
+# whether the containing system is NixOS, home-manager, or similar systems.
+#
+# Contract state propagates from parent services to sub-services automatically,
+# with `contracts.*.results` scoped to each service's own entries via direct injection.
+#
+# Service-manager-specific options (systemd units, launchd plists, etc.) are added
+# via `extraRootModules` in `lib/services/lib.nix`'s `configure` function, not here.
 { pkgs }:
 
 # The module
 {
   lib,
+  config,
   ...
 }:
 let
@@ -19,6 +32,7 @@ in
     ../../modules/generic/meta-maintainers.nix
     ../../nixos/modules/misc/assertions.nix
     (lib.modules.importApply ./config-data.nix { inherit pkgs; })
+    lib.contract.module
   ];
   options = {
     services = mkOption {
@@ -26,6 +40,20 @@ in
         types.submoduleWith {
           modules = [
             (lib.modules.importApply ./service.nix { inherit pkgs; })
+            # Propagate contract state to sub-services, scoping results
+            # so sub-service results are accessible via just the option name.
+            (
+              { name, ... }:
+              {
+                config = {
+                  inherit (config) contractDefinitions;
+                  contracts = lib.mapAttrs (contractType: _: {
+                    results = lib.mkForce (config.contracts.${contractType}.results.${name} or { });
+                    defaultProvider = lib.mkForce config.contracts.${contractType}.defaultProvider;
+                  }) config.contractDefinitions;
+                };
+              }
+            )
           ];
         }
       );
diff --git a/lib/tests/misc.nix b/lib/tests/misc.nix
index 6c254cae232b1..e61b113ca1d8b 100644
--- a/lib/tests/misc.nix
+++ b/lib/tests/misc.nix
@@ -78,6 +78,11 @@ let
     makeIncludePath
     makeOverridable
     mapAttrs
+    isNestedAttrsLeaf
+    mapNestedAttrsWith
+    mapNestedAttrs'
+    concatMapNestedAttrs'
+    concatMapNestedAttrsWith
     mapAttrsToListRecursive
     mapAttrsToListRecursiveCond
     mapCartesianProduct
@@ -2179,6 +2184,211 @@ runTests {
     };
   };
 
+  # mapNestedAttrsWith: flat input (no nesting) - fn applied directly to each value
+  testMapNestedAttrsFlat = {
+    expr = mapNestedAttrsWith lib.any (types.nestedAttrsOf types.int) (x: x * 2) {
+      a = 1;
+      b = 3;
+    };
+    expected = {
+      a = 2;
+      b = 6;
+    };
+  };
+
+  # mapNestedAttrsWith: nested input - fn applied only at leaves, attrset nodes preserved
+  testMapNestedAttrsNested = {
+    expr = mapNestedAttrsWith lib.any (types.nestedAttrsOf types.int) (x: x * 2) {
+      a.b = 1;
+      a.c = 3;
+      d = 5;
+    };
+    expected = {
+      a.b = 2;
+      a.c = 6;
+      d = 10;
+    };
+  };
+
+  # mapNestedAttrsWith: empty input
+  testMapNestedAttrsEmpty = {
+    expr = mapNestedAttrsWith lib.any (types.nestedAttrsOf types.int) (x: x + 1) { };
+    expected = { };
+  };
+
+  # mapNestedAttrs': flat input - equivalent to mapNestedAttrsWith lib.any
+  testMapNestedAttrsFlat' = {
+    expr = mapNestedAttrs' (types.nestedAttrsOf types.int) (x: x * 2) {
+      a = 1;
+      b = 3;
+    };
+    expected = {
+      a = 2;
+      b = 6;
+    };
+  };
+
+  # mapNestedAttrs': nested input - structure preserved, apply `fn` only at leaves
+  testMapNestedAttrsNested' = {
+    expr = mapNestedAttrs' (types.nestedAttrsOf types.int) (x: x * 2) {
+      a.b = 1;
+      a.c = 3;
+      d = 5;
+    };
+    expected = {
+      a.b = 2;
+      a.c = 6;
+      d = 10;
+    };
+  };
+
+  # mapNestedAttrs': multiple siblings at same level all transformed
+  testMapNestedAttrsSiblings' = {
+    expr =
+      let
+        elementType = types.submodule { options.v = lib.mkOption { type = types.int; }; };
+      in
+      mapNestedAttrs' (types.nestedAttrsOf elementType) (x: x.v) {
+        ns.a.v = 1;
+        ns.b.v = 2;
+        ns.c.v = 3;
+      };
+    expected = {
+      ns.a = 1;
+      ns.b = 2;
+      ns.c = 3;
+    };
+  };
+
+  # concatMapNestedAttrs': flat input - fn receives single-element path and leaf value
+  testConcatMapNestedAttrsFlat = {
+    expr =
+      concatMapNestedAttrs' (types.nestedAttrsOf types.int)
+        (path: x: { ${lib.concatStringsSep "." path} = x * 2; })
+        {
+          a = 1;
+          b = 3;
+        };
+    expected = {
+      a = 2;
+      b = 6;
+    };
+  };
+
+  # concatMapNestedAttrs': nested input - fn receives full path list and leaf value, result is flat
+  testConcatMapNestedAttrsNested = {
+    expr =
+      concatMapNestedAttrs' (types.nestedAttrsOf types.int)
+        (path: x: { ${lib.concatStringsSep "." path} = x; })
+        {
+          a.b = 1;
+          a.c = 2;
+          d = 3;
+        };
+    expected = {
+      "a.b" = 1;
+      "a.c" = 2;
+      d = 3;
+    };
+  };
+
+  # concatMapNestedAttrs': empty input
+  testConcatMapNestedAttrsEmpty' = {
+    expr = concatMapNestedAttrs' (types.nestedAttrsOf types.int) (path: x: {
+      ${lib.head path} = x;
+    }) { };
+    expected = { };
+  };
+
+  # isNestedAttrsLeaf: scalar type - leaf detected by elemType.check
+  testIsNestedAttrsLeafScalar = {
+    expr = isNestedAttrsLeaf lib.any types.int 42;
+    expected = true;
+  };
+
+  # isNestedAttrsLeaf: scalar type - non-leaf (attrset where int expected)
+  testIsNestedAttrsLeafScalarNonLeaf = {
+    expr = isNestedAttrsLeaf lib.any types.int { a = 1; };
+    expected = false;
+  };
+
+  # isNestedAttrsLeaf: submodule type with lib.any - leaf when any key matches declared option
+  testIsNestedAttrsLeafSubmoduleAny = {
+    expr =
+      let
+        elementType = types.submodule { options.foo = lib.mkOption { type = types.int; }; };
+      in
+      isNestedAttrsLeaf lib.any elementType {
+        foo = 1;
+        extra = "x";
+      };
+    expected = true;
+  };
+
+  # isNestedAttrsLeaf: submodule type with lib.all - non-leaf when not all keys match declared options
+  testIsNestedAttrsLeafSubmoduleAllFalse = {
+    expr =
+      let
+        elementType = types.submodule { options.foo = lib.mkOption { type = types.int; }; };
+      in
+      isNestedAttrsLeaf lib.all elementType {
+        foo = 1;
+        extra = "x";
+      };
+    expected = false;
+  };
+
+  # isNestedAttrsLeaf: submodule type - intermediate attrset not a leaf (no keys match)
+  testIsNestedAttrsLeafSubmoduleIntermediate = {
+    expr =
+      let
+        elementType = types.submodule { options.foo = lib.mkOption { type = types.int; }; };
+      in
+      isNestedAttrsLeaf lib.any elementType {
+        a.foo = 1;
+      };
+    expected = false;
+  };
+
+  # concatMapNestedAttrsWith: lib.all predicate - only detects leaves where all keys match declared options
+  testConcatMapNestedAttrsWithAll = {
+    expr =
+      let
+        elementType = types.submodule { options.foo = lib.mkOption { type = types.int; }; };
+      in
+      concatMapNestedAttrsWith lib.all (types.nestedAttrsOf elementType)
+        (path: v: { ${lib.concatStringsSep "." path} = v.foo; })
+        {
+          a = {
+            b.foo = 1;
+            c.foo = 2;
+          };
+        };
+    expected = {
+      "a.b" = 1;
+      "a.c" = 2;
+    };
+  };
+
+  # concatMapNestedAttrsWith: lib.any predicate - detects leaves even with extra keys alongside declared options
+  testConcatMapNestedAttrsWithAny = {
+    expr =
+      let
+        elementType = types.submodule { options.foo = lib.mkOption { type = types.int; }; };
+      in
+      concatMapNestedAttrsWith lib.any (types.nestedAttrsOf elementType)
+        (path: v: { ${lib.concatStringsSep "." path} = v.foo; })
+        {
+          a = {
+            foo = 1;
+            extra = "x";
+          };
+        };
+    expected = {
+      a = 1;
+    };
+  };
+
   testFilterAttrs = {
     expr = filterAttrs (n: v: n != "a" && (v.hello or false) == true) {
       a.hello = true;
diff --git a/lib/tests/modules.sh b/lib/tests/modules.sh
index 94aeea299e040..20f9d9f5220d8 100755
--- a/lib/tests/modules.sh
+++ b/lib/tests/modules.sh
@@ -135,6 +135,29 @@ checkExpression() {
   }
 }
 
+checkConfigWarning() {
+    local warningContains=$1
+    local err=""
+    shift
+    if ! err="$(evalConfig "$@" 2>&1 >/dev/null)"; then
+        logStartFailure
+        echo "ACTUAL: non-zero exit code, stderr:"
+        echo "$err"
+        echo "EXPECTED: exit code 0 with warning matching '$warningContains'"
+        logFailure
+        logEndFailure
+    elif echo "$err" | grep -E --silent "$warningContains" ; then
+        ((++pass))
+    else
+        logStartFailure
+        echo "ACTUAL stderr:"
+        echo "$err"
+        echo "EXPECTED: warning matching '$warningContains'"
+        logFailure
+        logEndFailure
+    fi
+}
+
 checkConfigError() {
     local errorContains=$1
     local err=""
@@ -438,6 +461,11 @@ checkConfigOutput '^"hello"$' config.packageInvalidIdentifier.pname ./declare-mk
 checkConfigOutput '^"pkgs\.\\"123\\"\.\\"with\\\\\\"quote\\"\.hello"$' options.packageInvalidIdentifier.defaultText.text ./declare-mkPackageOption.nix
 checkConfigOutput '^"pkgs\.\\"123\\"\.\\"with\\\\\\"quote\\"\.hello"$' options.packageInvalidIdentifierExample.example.text ./declare-mkPackageOption.nix
 
+# Check nestedAttrsOf
+checkConfigOutput '^3$' config.value.b.d.e ./declare-nested-attrs.nix
+checkConfigError 'A definition for option .* is not of type .*' config.value.b.f ./declare-nested-attrs-unsound.nix
+checkConfigError 'expected an attribute set with keys from \[request, result\]' config.value.consumer ./declare-nested-attrs-misshapen.nix
+
 # submoduleWith
 
 ## specialArgs should work
@@ -787,6 +815,10 @@ checkConfigOutput '^true$' config.viaConfig ./mkDefinition.nix
 checkConfigOutput '^true$' config.mkMerge ./mkDefinition.nix
 checkConfigOutput '^true$' config.mkForce ./mkDefinition.nix
 
+checkConfigOutput '2' config.bar.baz ./evalOption.nix
+checkConfigError 'not of type' config.foo.boo.bar ./extendOption.nix
+checkConfigError 'not of type' config.foo.boo.bar ./extendSubmodule.nix
+
 # specialArgs._class
 checkConfigOutput '"nixos"' config.nixos.config.foo ./specialArgs-class.nix
 checkConfigOutput '"bar"' config.conditionalImportAsNixos.config.foo ./specialArgs-class.nix
@@ -859,6 +891,71 @@ checkConfigError 'the-defs-file\.nix' config.argv ./attrList-valueMeta-definitio
 # attrListOf does not support type merging
 checkConfigError 'The option .merged. in .*/declare-attrList-type-merge.nix. is already declared in .*/declare-attrList-type-merge.nix' config.merged ./declare-attrList-type-merge.nix
 
+# contracts: basic want -> instances -> results round-trip (no mkContract or mkProviderType)
+checkConfigOutput '^6$' config.contracts.basic.results.consumer.x.value ./contracts-basic.nix
+
+# contracts: provider selection mechanisms
+# byRef: non-overridden instance falls back to defaultProvider (increment: 5 + 1 = 6)
+checkConfigOutput '^6$' config.result.default ./contracts-provider-selection.nix
+# by reference: per-instance override (double: 5 * 2 = 10)
+checkConfigOutput '^10$' config.result.override ./contracts-provider-selection.nix
+# by name: defaultProviderName enum (increment: 5 + 1 = 6)
+checkConfigOutput '^6$' config.result.by ./contracts-provider-selection.nix
+# instances-only routing: a leaf routed via an `instances` override resolves
+# even with no defaultProvider (increment: 5 + 1 = 6)
+checkConfigOutput '^6$' config.result.instancesOnly ./contracts-provider-selection.nix
+# unrouted leaf (no default, no override): accessing its result errors clearly
+checkConfigError 'contracts\.noProvider: an instance is .want.ed but routed to no provider' config.contracts.noProvider.results.consumer.unrouted.value ./contracts-provider-selection.nix
+# duplicate `instances` leaf definitions (mergeableRaw): two modules routing the
+# same leaf to the same provider collapse (5 + 1 = 6), including references built
+# from independent thunks.
+checkConfigOutput '^6$' config.result.dupAgree ./contracts-provider-selection.nix
+checkConfigOutput '^6$' config.result.dupAgreeThunks ./contracts-provider-selection.nix
+# a genuine two-provider conflict at one leaf still throws: forcing the routed
+# slice reads the doubly-defined `module.loc`, where `mergeEqualOption` errors.
+checkConfigError 'conflicting definition values' config.contracts.dupConflict.providerRequests.increment ./contracts-provider-selection.nix
+# providerRequests: each provider's slice gathers only the requests routed to it
+# (default increment gets every instance but the `consumer.fast` override; double gets only it).
+checkConfigOutput '^"instance,slow"$' config.routed.increment ./contracts-provider-selection.nix
+checkConfigOutput '^"fast"$' config.routed.double ./contracts-provider-selection.nix
+# the routed slice mirrors `requests`, so request values survive
+checkConfigOutput '^"5"$' config.routed.incrementValue ./contracts-provider-selection.nix
+
+# contracts: deployer write at a `providerOptions` leaf must not mask consumer wants
+# (regression for the `_requests` re-application at `mkDefault` in mkProviderType).
+checkConfigOutput '^12$' config.contracts.wantForwarding.results.consumer.instance.value ./contracts-partial-overrides.nix
+
+# contracts: mkContract propagates request option defaults via extendSubmodule
+checkConfigOutput '^42$' config.result ./contracts-mkcontract.nix
+
+# contracts: varying nesting depths in want (flat, grouped, deeply nested)
+checkConfigOutput '^2$' config.contracts.arithmetic.results.myapp.simple.value ./contracts-nesting-consumer.nix
+checkConfigOutput '^11$' config.contracts.arithmetic.results.myapp.db.primary.value ./contracts-nesting-consumer.nix
+checkConfigOutput '^21$' config.contracts.arithmetic.results.myapp.db.replica.value ./contracts-nesting-consumer.nix
+checkConfigOutput '^101$' config.contracts.arithmetic.results.myapp.caches.region-a.fast.value ./contracts-nesting-consumer.nix
+checkConfigOutput '^201$' config.contracts.arithmetic.results.myapp.caches.region-b.fast.value ./contracts-nesting-consumer.nix
+
+# contracts: providers' contract option may live at any nesting depth
+checkConfigOutput '^6$' config.contracts.depth0.results.consumer.instance.value ./contracts-nesting-provider.nix
+checkConfigOutput '^15$' config.contracts.depth1.results.consumer.instance.value ./contracts-nesting-provider.nix
+checkConfigOutput '^105$' config.contracts.depth2.results.consumer.instance.value ./contracts-nesting-provider.nix
+
+# contracts: request values are type-checked (string where int expected)
+checkConfigError 'is not of type.*signed integer' config.contracts.arithmetic.results.consumer.instance.value ./contracts-request-typecheck.nix
+
+# contracts: submodule-typed request options survive the want -> requests -> results round-trip
+checkConfigOutput '^"postgresql://db.example.com:5432"$' config.contracts.connection.results.myapp.db.url ./contracts-submodule-request.nix
+
+# contracts: using a renamed contract name emits a deprecation warning in config.warnings
+checkConfigOutput 'oldName.*renamed.*newName' config.result ./contracts-contract-rename.nix
+# contracts: using a renamed contract name still produces the correct result
+checkConfigOutput '^6$' config.contracts.oldName.results.consumer.instance.value ./contracts-contract-rename.nix
+
+# contracts: using a renamed request option still forwards the value correctly
+checkConfigOutput '^6$' config.contracts.versioned.results.consumer.instance.value ./contracts-rename-warning.nix
+# contracts: using a renamed request option emits a deprecation warning on stderr
+checkConfigWarning 'request\.oldValue.*renamed.*request\.newValue' config.contracts.versioned.results.consumer.instance.value ./contracts-rename-warning.nix
+
 cat <<EOF
 ====== module tests ======
 $pass Pass
diff --git a/lib/tests/modules/contracts-arithmetic-contract.nix b/lib/tests/modules/contracts-arithmetic-contract.nix
new file mode 100644
index 0000000000000..cf89219f8d6ad
--- /dev/null
+++ b/lib/tests/modules/contracts-arithmetic-contract.nix
@@ -0,0 +1,33 @@
+# Shared module: defines the `arithmetic` contract type for use in lib-level tests.
+# Imports the generic contracts module directly (not the NixOS wrapper) so these
+# tests work in the CI sandbox which only has lib/.
+{ lib, ... }:
+let
+  inherit (lib) mkOption types;
+in
+{
+  imports = [ lib.contract.module ];
+
+  # Stub for the NixOS-level `meta` option expected by the contracts module.
+  options.meta = mkOption {
+    type = types.attrs;
+    default = { };
+  };
+
+  config.contractDefinitions.arithmetic = {
+    meta = {
+      description = "A contract for arithmetic operations, used for testing.";
+      maintainers = [ ];
+    };
+    interface = {
+      request.value = mkOption {
+        description = "Input value.";
+        type = types.int;
+      };
+      result.value = mkOption {
+        description = "Output value.";
+        type = types.int;
+      };
+    };
+  };
+}
diff --git a/lib/tests/modules/contracts-basic.nix b/lib/tests/modules/contracts-basic.nix
new file mode 100644
index 0000000000000..b230d9c1bb8ed
--- /dev/null
+++ b/lib/tests/modules/contracts-basic.nix
@@ -0,0 +1,52 @@
+# Tests the basic want -> instances -> results round-trip.
+# The contract type is defined inline; instances are wired manually rather than
+# through a provider reference, so no defaultProvider is needed.
+{
+  lib,
+  config,
+  ...
+}:
+let
+  inherit (lib) mkOption types;
+in
+{
+  imports = [ lib.contract.module ];
+
+  options.meta = mkOption {
+    type = types.attrs;
+    default = { };
+  };
+
+  options.result = mkOption {
+    type = types.int;
+  };
+
+  config = {
+    contractDefinitions.basic = {
+      meta = {
+        description = "Arithmetic contract for basic round-trip tests.";
+        maintainers = [ ];
+      };
+      interface = {
+        request.value = mkOption {
+          description = "Input value.";
+          type = types.int;
+        };
+        result.value = mkOption {
+          description = "Output value.";
+          type = types.int;
+        };
+      };
+    };
+
+    # Consumer: one instance with a request.
+    contracts.basic.want.consumer.x.request.value = 5;
+
+    # Provider: wire instances directly
+    contracts.basic.instances.consumer.x = {
+      result.value = 6;
+    };
+
+    result = config.contracts.basic.results.consumer.x.value;
+  };
+}
diff --git a/lib/tests/modules/contracts-contract-rename.nix b/lib/tests/modules/contracts-contract-rename.nix
new file mode 100644
index 0000000000000..2b9c0b8d95a58
--- /dev/null
+++ b/lib/tests/modules/contracts-contract-rename.nix
@@ -0,0 +1,90 @@
+# Tests that using a renamed contract name emits a deprecation warning in config.warnings.
+#
+# mkRenamedOptionModule cannot be used for contracts.<name> because `contracts` is a single
+# submodule-typed option — doRename cannot find or declare sub-options within it.
+# Instead, a rename is implemented as a NixOS module that:
+#   1. Defines the old contractType independently (same interface, separate declaration)
+#   2. Adds a config.warnings entry when the old contract's `want` is non-empty
+{
+  lib,
+  config,
+  options,
+  ...
+}:
+let
+  sharedInterface = {
+    request.value = lib.mkOption { type = lib.types.int; };
+    result.value = lib.mkOption { type = lib.types.int; };
+  };
+  inherit (config.contracts) oldName;
+in
+{
+  imports = [
+    lib.contract.module
+    # Rename warning: emits config.warnings when contracts.oldName is used.
+    (
+      { config, lib, ... }:
+      {
+        warnings = lib.optional (
+          config.contracts.oldName.want != { }
+        ) "The contract `oldName` has been renamed to `newName`. Please update your configuration.";
+      }
+    )
+  ];
+
+  # meta is a NixOS-level option; provide a stub so the contracts module's
+  # `meta.buildDocsInSandbox = false` is accepted in this bare evalModules context.
+  options.meta = lib.mkOption {
+    type = lib.types.attrs;
+    default = { };
+  };
+  options.warnings = lib.mkOption {
+    type = lib.types.listOf lib.types.str;
+    default = [ ];
+  };
+  options.result = lib.mkOption {
+    type = lib.types.str;
+    default = "";
+  };
+
+  # Provider option for the deprecated contract: increments request value by 1.
+  options.services.increment.oldName = lib.mkOption {
+    default = oldName.providerRequests.increment;
+    type = oldName.mkProviderType {
+      fulfill =
+        { value }:
+        {
+          value = value + 1;
+        };
+    };
+  };
+
+  config = {
+    contractDefinitions.newName = {
+      meta = {
+        description = "New contract name (test).";
+        maintainers = [ ];
+      };
+      interface = sharedInterface;
+    };
+    # Old contract type: same interface, declared independently to avoid self-reference.
+    # (contractDefinitions.oldName = config.contractDefinitions.newName would cause infinite recursion
+    # because config.contractDefinitions is built from all contractDefinitions definitions including oldName.)
+    contractDefinitions.oldName = {
+      meta = {
+        description = "Deprecated: renamed to newName.";
+        maintainers = [ ];
+      };
+      interface = sharedInterface;
+    };
+
+    # Consumer uses the old (renamed) contract name.
+    contracts.oldName.want.consumer.instance.request.value = 5;
+
+    # Provider wiring uses the GUI-discoverable `{ module, contract? }` shape.
+    contracts.oldName.providers.increment.module = options.services.increment.oldName;
+    contracts.oldName.defaultProvider = oldName.providers.increment;
+
+    result = lib.concatStringsSep "%" config.warnings;
+  };
+}
diff --git a/lib/tests/modules/contracts-mkcontract.nix b/lib/tests/modules/contracts-mkcontract.nix
new file mode 100644
index 0000000000000..b32faddc2c317
--- /dev/null
+++ b/lib/tests/modules/contracts-mkcontract.nix
@@ -0,0 +1,30 @@
+# Tests that mkContract applies request option overrides correctly.
+# `mkContract { request = { value.default = 42; }; }` must propagate the
+# default through extendSubmodule to the generated option type.
+{
+  lib,
+  config,
+  ...
+}:
+let
+  inherit (lib) mkOption types;
+in
+{
+  imports = [ ./contracts-arithmetic-contract.nix ];
+
+  options = {
+    consumer.myOpt = mkOption {
+      default = { };
+      type = config.contractDefinitions.arithmetic.mkContract {
+        request = {
+          value.default = 42;
+        };
+      };
+    };
+    result = mkOption {
+      type = types.int;
+    };
+  };
+
+  config.result = config.consumer.myOpt.request.value;
+}
diff --git a/lib/tests/modules/contracts-nesting-consumer.nix b/lib/tests/modules/contracts-nesting-consumer.nix
new file mode 100644
index 0000000000000..5d45e3c93305c
--- /dev/null
+++ b/lib/tests/modules/contracts-nesting-consumer.nix
@@ -0,0 +1,54 @@
+# Tests that NixOS module consumers can use varying nesting depths in `want`.
+#
+# The `nestedAttrsOf` type supports arbitrary depth. A consumer can organize
+# its contract options flat or grouped:
+#
+#   want.myapp.secret              (2 layers: consumer + option)
+#   want.myapp.db.primary          (3 layers: consumer + group + option)
+#   want.myapp.db.caches.fast      (4 layers: consumer + group + subgroup + option)
+#
+# All depths coexist in the same `want` tree and the provider fulfills them all.
+{
+  lib,
+  config,
+  options,
+  ...
+}:
+let
+  inherit (lib) mkOption;
+  inherit (config.contracts) arithmetic;
+in
+{
+  imports = [ ./contracts-arithmetic-contract.nix ];
+
+  options.services.increment.arithmetic = mkOption {
+    default = arithmetic.providerRequests.increment;
+    type = arithmetic.mkProviderType {
+      fulfill =
+        { value }:
+        {
+          value = value + 1;
+        };
+    };
+  };
+
+  config = {
+    # -- Consumer: varying nesting depths in want --
+
+    # 2 layers: consumer + option (flat)
+    contracts.arithmetic.want.myapp.simple.request.value = 1;
+
+    # 3 layers: consumer + group + option
+    contracts.arithmetic.want.myapp.db.primary.request.value = 10;
+    contracts.arithmetic.want.myapp.db.replica.request.value = 20;
+
+    # 4 layers: consumer + group + subgroup + option
+    contracts.arithmetic.want.myapp.caches.region-a.fast.request.value = 100;
+    contracts.arithmetic.want.myapp.caches.region-b.fast.request.value = 200;
+
+    # -- Provider --
+    contracts.arithmetic.providers.increment.module = options.services.increment.arithmetic;
+    contracts.arithmetic.defaultProvider = arithmetic.providers.increment;
+
+  };
+}
diff --git a/lib/tests/modules/contracts-nesting-provider.nix b/lib/tests/modules/contracts-nesting-provider.nix
new file mode 100644
index 0000000000000..447df264610df
--- /dev/null
+++ b/lib/tests/modules/contracts-nesting-provider.nix
@@ -0,0 +1,115 @@
+# Tests that a provider's contract option may live at any *submodule nesting
+# depth* inside the provider's root option:
+#
+#   depth 0: the provider's root option IS the contract option
+#            (`options.depth0 = mkOption { type = mkProviderType ...; }`).
+#   depth 1: the contract option lives one submodule deep, inside the
+#            provider's root submodule.
+#   depth 2: the contract option lives two submodules deep.
+#
+# This is distinct from namespace-style attribute paths
+# (`options.foo.bar.contract`), which are just chained attr access and don't
+# introduce any wrapping option.
+#
+# Three contract types (each sharing the arithmetic interface) with their
+# default providers' contract options placed at depths 0, 1, and 2. Each
+# provider returns `request.value + N` (with a different N per depth) so we
+# can tell which one fulfilled which contract.
+{
+  lib,
+  config,
+  options,
+  ...
+}:
+let
+  inherit (lib) mkOption types;
+  inherit (config.contracts)
+    arithmetic
+    depth0
+    depth1
+    depth2
+    ;
+
+  arithmeticInterface = (config.contractDefinitions.arithmetic).interface;
+
+  mkProviderOpt =
+    add:
+    mkOption {
+      type = arithmetic.mkProviderType {
+        fulfill =
+          { value }:
+          {
+            value = value + add;
+          };
+      };
+    };
+in
+{
+  imports = [ ./contracts-arithmetic-contract.nix ];
+
+  # depth 0: the provider's root option *is* the contract option.
+  options.depth0 = mkProviderOpt 1;
+
+  # depth 1: the contract option lives one submodule level inside the root.
+  options.depth1 = mkOption {
+    type = types.submodule {
+      options.arithmetic = mkProviderOpt 10;
+    };
+  };
+
+  # depth 2: the contract option lives two submodule levels inside the root.
+  options.depth2 = mkOption {
+    type = types.submodule {
+      options.inner = mkOption {
+        type = types.submodule {
+          options.arithmetic = mkProviderOpt 100;
+        };
+      };
+    };
+  };
+
+  config = {
+    # Three distinct contract types sharing the arithmetic interface, so
+    # each can have its own default provider.
+    contractDefinitions = lib.genAttrs [ "depth0" "depth1" "depth2" ] (_: {
+      meta = {
+        description = "Arithmetic contract for provider-nesting tests.";
+        maintainers = [ ];
+      };
+      interface = arithmeticInterface;
+    });
+
+    # -- Consumers: same request (value = 5) across all three contract types --
+    contracts.depth0.want.consumer.instance.request.value = 5;
+    contracts.depth1.want.consumer.instance.request.value = 5;
+    contracts.depth2.want.consumer.instance.request.value = 5;
+
+    # -- Providers: feed routed requests, register at each depth --
+    depth0 = depth0.providerRequests.p;
+    depth1.arithmetic = depth1.providerRequests.p;
+    depth2.inner.arithmetic = depth2.providerRequests.p;
+
+    # depth 0: option *is* the contract option; inferred `contract = [ ]`.
+    contracts.depth0.providers.p.module = options.depth0;
+    contracts.depth0.defaultProvider = depth0.providers.p;
+
+    # depth 1: contract option lives inside a wrapping submodule named
+    # `arithmetic`, not matching the contract type name (`depth1`), so
+    # `contract` must be set explicitly.
+    contracts.depth1.providers.p = {
+      module = options.depth1;
+      contract = [ "arithmetic" ];
+    };
+    contracts.depth1.defaultProvider = depth1.providers.p;
+
+    # depth 2: contract option lives two submodules deep.
+    contracts.depth2.providers.p = {
+      module = options.depth2;
+      contract = [
+        "inner"
+        "arithmetic"
+      ];
+    };
+    contracts.depth2.defaultProvider = depth2.providers.p;
+  };
+}
diff --git a/lib/tests/modules/contracts-partial-overrides.nix b/lib/tests/modules/contracts-partial-overrides.nix
new file mode 100644
index 0000000000000..2714577f1074f
--- /dev/null
+++ b/lib/tests/modules/contracts-partial-overrides.nix
@@ -0,0 +1,90 @@
+# Regression test for the want-forwarding leakage in `mkProviderType`.
+#
+# When a provider type declares `providerOptions` and the deployer writes
+# one such option at a contract instance, `nestedAttrsOf`'s leaf-level
+# priority handling drops the `mkOptionDefault`-priority value carrying the
+# consumer's `want` request data. `contracts.<name>.mkProviderType` re-applies
+# those wants at `mkDefault` priority via `_requests` to keep them visible
+# alongside the deployer-written provider option. This test exercises that
+# path eval-only: a provider with `providerOptions.extra`, a consumer want
+# overriding one request field while leaving another at its default, and a
+# deployer write at the provider's `extra` leaf -- the result must reflect
+# both the overridden and defaulted request fields.
+{
+  lib,
+  config,
+  options,
+  ...
+}:
+let
+  inherit (lib) mkOption types;
+
+  wantForwardingInterface = {
+    meta = {
+      description = "Contract for want-forwarding regression tests.";
+      maintainers = [ ];
+    };
+    interface = {
+      request.a = mkOption {
+        description = "First addend; consumer overrides this.";
+        type = types.int;
+        default = 1;
+      };
+      request.b = mkOption {
+        description = "Second addend; consumer leaves at default.";
+        type = types.int;
+        default = 2;
+      };
+      result.value = mkOption {
+        description = "Sum of request fields.";
+        type = types.int;
+      };
+    };
+  };
+
+in
+{
+  imports = [ lib.contract.module ];
+
+  options.meta = mkOption {
+    type = types.attrs;
+    default = { };
+  };
+
+  # Use `config.contracts.<name>.mkProviderType` (not the raw
+  # `contractDefinitions` one) so `_requests` is pre-bound -- that pre-binding
+  # is exactly the want-forwarding mechanism under test.
+  # Mirror real providers (e.g. `testing.hardcoded-secret`) by setting the
+  # provider's routed-requests tree as the option's `default`. That places the
+  # want-derived values at `mkOptionDefault` priority -- exactly what
+  # `nestedAttrsOf` leaf filtering drops when a deployer-written provider leaf
+  # appears at the same instance, unless `_requests` re-applies them at `mkDefault`.
+  options.services.myProvider.wantForwarding = mkOption {
+    default = config.contracts.wantForwarding.providerRequests.myProvider;
+    type = config.contracts.wantForwarding.mkProviderType {
+      providerOptions.extra = mkOption {
+        description = "Provider-specific leaf whose deployer write triggers the leakage path.";
+        type = types.int;
+      };
+      fulfill = request: {
+        value = request.a + request.b;
+      };
+    };
+  };
+
+  config = {
+    contractDefinitions.wantForwarding = wantForwardingInterface;
+
+    # Consumer overrides `a`, leaves `b` at its default of 2.
+    contracts.wantForwarding.want.consumer.instance.request.a = 10;
+
+    # Deployer write at the provider-specific leaf, normal priority. This is
+    # the write that, pre-fix, causes the `want`s under the option's default to
+    # be dropped from the same instance.
+    services.myProvider.wantForwarding.consumer.instance.extra = 999;
+
+    # Register the provider and select it as the default.
+    contracts.wantForwarding.providers.myProvider.module = options.services.myProvider.wantForwarding;
+    contracts.wantForwarding.defaultProvider = config.contracts.wantForwarding.providers.myProvider;
+  };
+}
diff --git a/lib/tests/modules/contracts-provider-selection.nix b/lib/tests/modules/contracts-provider-selection.nix
new file mode 100644
index 0000000000000..07b7d6ba1bb9c
--- /dev/null
+++ b/lib/tests/modules/contracts-provider-selection.nix
@@ -0,0 +1,199 @@
+# Tests provider selection mechanisms:
+# - instances-only routing: a `want` leaf routed via a per-instance `instances`
+#   override resolves even with no `defaultProvider` set; a sibling leaf routed
+#   by neither a default nor an override stays unrouted (per-leaf routing)
+# - by reference: `defaultProvider` reference for the default + a per-instance
+#   override at one `instances` leaf (the other falls through to the default)
+# - by name: `defaultProviderName` enum
+{
+  lib,
+  config,
+  options,
+  ...
+}:
+let
+  inherit (lib) mkOption types;
+
+  # Inline definition needed because this test creates two contract types
+  # sharing the same interface, and referencing config.contractDefinitions.arithmetic
+  # inside contractDefinitions would cause infinite recursion.
+  arithmeticInterface = {
+    meta = {
+      description = "Arithmetic contract for provider selection tests.";
+      maintainers = [ ];
+    };
+    interface = {
+      request.value = mkOption {
+        description = "Input value.";
+        type = types.int;
+      };
+      result.value = mkOption {
+        description = "Output value.";
+        type = types.int;
+      };
+    };
+  };
+
+  # evaluated = lib.evalOption (mkOption { type = lib.contract.definitionType; }) arithmeticInterface;
+  # Uses the raw `_mkProviderType` rather than the `forModule` wrapper because
+  # the single `services.increment.arithmetic` option absorbs requests from
+  # three sibling contract types (`noProvider`, `by`) via
+  # `lib.mkMerge` below; the wrapped form would pre-bind one contract's
+  # `_requests`, which would be wrong for the other two.
+  inherit (lib.contract.forModule config) arithmetic;
+
+  mkProvider =
+    f:
+    mkOption {
+      type = arithmetic.mkProviderType {
+        fulfill =
+          { value }:
+          {
+            value = f value;
+          };
+      };
+    };
+in
+{
+  imports = [
+    ./contracts-arithmetic-contract.nix
+
+    # -- Duplicate `instances` leaf definitions (mergeableRaw) --
+    # Two modules routing the SAME instance to the SAME provider must collapse to
+    # one (no spurious "defined multiple times"). This is what lets a combined
+    # node co-locating several apps have each app's routing module route a shared
+    # domain to the same provider. `raw`'s `mergeOneOption` would reject the
+    # identical second definition; `mergeableRaw`'s `mergeEqualOption` collapses.
+
+    # 1. duplicate agree: both route `x` to `increment`.
+    ({ config, ... }: { contracts.dupAgree.instances.consumer.x = config.contracts.dupAgree.providers.increment; })
+    ({ config, ... }: { contracts.dupAgree.instances.consumer.x = config.contracts.dupAgree.providers.increment; })
+
+    # 2. distinct thunks agree: two references built independently (each its own
+    # `module.value` thunk) still collapse -- the merge fires at the scalar
+    # sub-leaves under `nestedAttrsOf` recursion, where identical references are
+    # equal. This is the real combined-node case a byte-identity check would
+    # spuriously reject.
+    ({ config, ... }: { contracts.dupAgree.instances.consumer.thunky = { inherit (config.contracts.dupAgree.providers.increment) module; }; })
+    ({ config, ... }: { contracts.dupAgree.instances.consumer.thunky = { inherit (config.contracts.dupAgree.providers.increment) module; }; })
+
+    # 3. genuine conflict: two DIFFERENT providers at one leaf still throws -- the
+    # merge tolerates agreement, not disagreement. The conflict is on `module.loc`
+    # (the field routing reads), so forcing `dupConflict.providerRequests`
+    # triggers it. Asserted by demanding that path directly (not via an exposed
+    # `attrsOf`-typed attr, whose type check would force the error into unrelated
+    # assertions) -- same isolation pattern as `noProvider`'s `unrouted`.
+    ({ config, ... }: { contracts.dupConflict.instances.consumer.x = config.contracts.dupConflict.providers.increment; })
+    ({ config, ... }: { contracts.dupConflict.instances.consumer.x = config.contracts.dupConflict.providers.double; })
+  ];
+
+  options.services.increment.arithmetic = mkProvider (v: v + 1);
+  options.services.double.arithmetic = mkProvider (v: v * 2);
+
+  options.result = mkOption {
+    type = types.attrsOf types.int;
+  };
+
+  # Routing view: which consumer instances each provider's `providerRequests`
+  # slice gathers (sorted, dot-joined), and a request value carried through it.
+  options.routed = mkOption {
+    type = types.attrsOf types.str;
+  };
+
+  config = {
+    # Additional contract types sharing the arithmetic interface.
+    contractDefinitions.noProvider = arithmeticInterface;
+    contractDefinitions.by = arithmeticInterface;
+    # `dupAgree`/`dupConflict` exercise duplicate `instances` leaf definitions:
+    # `mergeableRaw` (via `mergeEqualOption`) collapses agreeing duplicates and
+    # still throws on a genuine conflict.
+    contractDefinitions.dupAgree = arithmeticInterface;
+    contractDefinitions.dupConflict = arithmeticInterface;
+
+    # -- Providers: feed requests, compute results --
+
+    services.increment.arithmetic = lib.mkMerge [
+      config.contracts.by.requests
+      config.contracts.noProvider.requests
+      # dupConflict needs no wiring: its error fires during `instances` merge,
+      # before provider computation, and laziness keeps it from affecting the
+      # other assertions (same pattern as `noProvider`'s `unrouted`).
+      config.contracts.dupAgree.requests
+    ];
+    services.double.arithmetic = config.contracts.by.requests;
+
+    # Register providers.
+    contracts.by.providers.increment.module = options.services.increment.arithmetic;
+    contracts.by.providers.double.module = options.services.double.arithmetic;
+    # `noProvider` gets a registered provider but no `defaultProvider`, so its
+    # leaves are only routed by explicit `instances` overrides.
+    contracts.noProvider.providers.increment.module = options.services.increment.arithmetic;
+    # Both providers registered for the duplicate-merge contract types.
+    contracts.dupAgree.providers.increment.module = options.services.increment.arithmetic;
+    contracts.dupAgree.providers.double.module = options.services.double.arithmetic;
+    contracts.dupConflict.providers.increment.module = options.services.increment.arithmetic;
+    contracts.dupConflict.providers.double.module = options.services.double.arithmetic;
+
+    # -- Consumers --
+
+    # `routed` is routed via a per-instance `instances` override (no default);
+    # `unrouted` is routed by neither, so demanding its result errors.
+    contracts.noProvider.want.consumer.routed.request.value = 5;
+    contracts.noProvider.want.consumer.unrouted.request.value = 5;
+    contracts.noProvider.instances.consumer.routed = config.contracts.noProvider.providers.increment;
+    # Two instances under one consumer so the override only touches one of them.
+    contracts.by.want.consumer.fast.request.value = 5;
+    contracts.by.want.consumer.slow.request.value = 5;
+    contracts.by.want.consumer.instance.request.value = 5;
+
+    # Duplicate-merge consumers: each `want` leaf is routed by two modules (see
+    # the `imports` below). `x` uses `value = 5` so a collapsed route yields 6.
+    contracts.dupAgree.want.consumer.x.request.value = 5;
+    contracts.dupAgree.want.consumer.thunky.request.value = 5;
+    contracts.dupConflict.want.consumer.x.request.value = 5;
+
+    # -- Provider selection --
+
+    # by: defaultProvider reference picks "increment" for everything
+    # (so `slow` -> 6), and a per-instance override at `consumer.fast`
+    # picks "double" (5 * 2 = 10) by reading the provider's instance at
+    # the matching path. Per-leaf priority handling in `nestedAttrsOf`
+    # lets the override compose against the `defaultProvider`-derived
+    # tree without `recursiveUpdate`.
+    contracts.by.defaultProvider = config.contracts.by.providers.increment;
+    contracts.by.instances.consumer.fast = config.contracts.by.providers.double;
+
+    # by: set defaultProviderName to "increment" (5 + 1 = 6)
+    contracts.by.defaultProviderName = "increment";
+
+    # -- Collect results --
+    result = {
+      default = config.contracts.by.results.consumer.slow.value;
+      override = config.contracts.by.results.consumer.fast.value;
+      by = config.contracts.by.results.consumer.instance.value;
+      # instances-only routing: resolves via the `instances` override despite
+      # `noProvider` having no `defaultProvider` (5 + 1 = 6).
+      instancesOnly = config.contracts.noProvider.results.consumer.routed.value;
+
+      # duplicate agree: two modules routing `x` to `increment` collapse; the
+      # single surviving route resolves (5 + 1 = 6).
+      dupAgree = config.contracts.dupAgree.results.consumer.x.value;
+      # distinct thunks agree: independently-built references still collapse.
+      dupAgreeThunks = config.contracts.dupAgree.results.consumer.thunky.value;
+    };
+
+    # -- providerRequests routing --
+    # `increment` is the default, so it gathers every instance except the
+    # `consumer.fast` override; `double` gathers only that override. Each
+    # provider's slice mirrors `requests`, so the request values survive.
+    routed = {
+      increment = lib.concatStringsSep "," (
+        lib.sort (a: b: a < b) (lib.attrNames config.contracts.by.providerRequests.increment.consumer)
+      );
+      double = lib.concatStringsSep "," (
+        lib.sort (a: b: a < b) (lib.attrNames config.contracts.by.providerRequests.double.consumer)
+      );
+      incrementValue = toString config.contracts.by.providerRequests.increment.consumer.slow.request.value;
+    };
+  };
+}
diff --git a/lib/tests/modules/contracts-rename-warning.nix b/lib/tests/modules/contracts-rename-warning.nix
new file mode 100644
index 0000000000000..27176a8a2326a
--- /dev/null
+++ b/lib/tests/modules/contracts-rename-warning.nix
@@ -0,0 +1,75 @@
+# Tests that a renamed contract request option:
+# - still forwards the value correctly (old name → new name)
+# - emits a lib.warn on stderr
+{
+  lib,
+  config,
+  options,
+  ...
+}:
+let
+  inherit (lib) mkOption types;
+  inherit (config.contracts) versioned;
+in
+{
+  imports = [ lib.contract.module ];
+
+  # meta is a NixOS-level option; provide a stub so the contracts module's
+  # `meta.buildDocsInSandbox = false` is accepted in this bare evalModules context.
+  options.meta = mkOption {
+    type = types.attrs;
+    default = { };
+  };
+
+  config.contractDefinitions.versioned = {
+    meta = {
+      description = "A test contract to verify rename warning behavior.";
+      maintainers = [ ];
+    };
+    interface = {
+      request.newValue = mkOption {
+        description = "Input value (renamed from oldValue).";
+        type = types.int;
+      };
+      result.value = mkOption {
+        description = "Output value.";
+        type = types.int;
+      };
+      extraImports.request = [
+        (
+          { config, options, ... }:
+          {
+            options.oldValue = mkOption {
+              description = "Deprecated alias for newValue.";
+              type = types.int;
+              visible = false;
+              apply = lib.warn "The option `request.oldValue` has been renamed to `request.newValue`. Please update your configuration.";
+            };
+            config = lib.mkIf options.oldValue.isDefined {
+              newValue = lib.mkDefault config.oldValue;
+            };
+          }
+        )
+      ];
+    };
+  };
+
+  options.services.increment.versioned = mkOption {
+    default = versioned.providerRequests.increment;
+    type = versioned.mkProviderType {
+      fulfill =
+        { newValue }:
+        {
+          value = newValue + 1;
+        };
+    };
+  };
+
+  config = {
+    # Consumer uses the old (renamed) option name.
+    contracts.versioned.want.consumer.instance.request.oldValue = 5;
+
+    contracts.versioned.providers.increment.module = options.services.increment.versioned;
+    contracts.versioned.defaultProvider = versioned.providers.increment;
+  };
+}
diff --git a/lib/tests/modules/contracts-request-typecheck.nix b/lib/tests/modules/contracts-request-typecheck.nix
new file mode 100644
index 0000000000000..84e1540c09e10
--- /dev/null
+++ b/lib/tests/modules/contracts-request-typecheck.nix
@@ -0,0 +1,36 @@
+# Tests that contract requests are type-checked: setting a request option to
+# the wrong type (e.g. a string where an int is expected) must produce an
+# evaluation error.
+{
+  lib,
+  config,
+  options,
+  ...
+}:
+let
+  inherit (lib) mkOption;
+  inherit (config.contracts) arithmetic;
+in
+{
+  imports = [ ./contracts-arithmetic-contract.nix ];
+
+  options.services.increment.arithmetic = mkOption {
+    default = arithmetic.providerRequests.increment;
+    type = arithmetic.mkProviderType {
+      fulfill =
+        { value }:
+        {
+          value = value + 1;
+        };
+    };
+  };
+
+  config = {
+    # Wrong type: "abc" is a string, but request.value expects an int.
+    contracts.arithmetic.want.consumer.instance.request.value = "abc";
+
+    # Provider
+    contracts.arithmetic.providers.increment.module = options.services.increment.arithmetic;
+    contracts.arithmetic.defaultProvider = arithmetic.providers.increment;
+  };
+}
diff --git a/lib/tests/modules/contracts-submodule-request.nix b/lib/tests/modules/contracts-submodule-request.nix
new file mode 100644
index 0000000000000..78d071888534a
--- /dev/null
+++ b/lib/tests/modules/contracts-submodule-request.nix
@@ -0,0 +1,87 @@
+# Tests that contract requests support submodule-typed options.
+#
+# Defines a contract whose request has a `connection` submodule (with `host`
+# and `port` sub-options) alongside a flat `name` option.  The provider reads
+# both and produces a result string, verifying the full structure survives the
+# want -> requests -> provider -> results round-trip.
+{
+  lib,
+  config,
+  options,
+  ...
+}:
+let
+  inherit (lib) mkOption types;
+
+  connectionContractDef = {
+    meta = {
+      description = "Contract with a submodule-typed request for testing.";
+      maintainers = [ ];
+    };
+    interface = {
+      request = {
+        name = mkOption {
+          description = "Service name.";
+          type = types.str;
+        };
+        connection = mkOption {
+          description = "Connection parameters.";
+          type = types.submodule {
+            options = {
+              host = mkOption {
+                description = "Hostname.";
+                type = types.str;
+              };
+              port = mkOption {
+                description = "Port number.";
+                type = types.int;
+              };
+            };
+          };
+        };
+      };
+      result.url = mkOption {
+        description = "Constructed URL.";
+        type = types.str;
+      };
+    };
+  };
+
+  inherit (lib.contract.forModule config) connection;
+in
+{
+  imports = [ lib.contract.module ];
+
+  options.meta = mkOption {
+    type = types.attrs;
+    default = { };
+  };
+
+  options.services.urlbuilder.connection = mkOption {
+    default = config.contracts.connection.providerRequests.urlbuilder;
+    type = connection.mkProviderType {
+      fulfill =
+        { name, connection }:
+        {
+          url = "${name}://${connection.host}:${toString connection.port}";
+        };
+    };
+  };
+
+  config = {
+    contractDefinitions.connection = connectionContractDef;
+
+    contracts.connection.want.myapp.db = {
+      request = {
+        name = "postgresql";
+        connection = {
+          host = "db.example.com";
+          port = 5432;
+        };
+      };
+    };
+
+    contracts.connection.providers.urlbuilder.module = options.services.urlbuilder.connection;
+    contracts.connection.defaultProvider = config.contracts.connection.providers.urlbuilder;
+  };
+}
diff --git a/lib/tests/modules/declare-nested-attrs-misshapen.nix b/lib/tests/modules/declare-nested-attrs-misshapen.nix
new file mode 100644
index 0000000000000..5f74092abc060
--- /dev/null
+++ b/lib/tests/modules/declare-nested-attrs-misshapen.nix
@@ -0,0 +1,22 @@
+{ lib, ... }:
+{
+  options.value = lib.mkOption {
+    type = lib.types.nestedAttrsOf (
+      lib.types.submodule {
+        options = {
+          request = lib.mkOption {
+            type = lib.types.int;
+            default = 0;
+          };
+          result = lib.mkOption {
+            type = lib.types.int;
+            default = 0;
+          };
+        };
+      }
+    );
+    default = { };
+  };
+  # Misshapen: scalar where an attrset `{ request = ...; result = ...; }` was expected.
+  config.value.consumer = 1;
+}
diff --git a/lib/tests/modules/declare-nested-attrs-unsound.nix b/lib/tests/modules/declare-nested-attrs-unsound.nix
new file mode 100644
index 0000000000000..4cc3ff23035eb
--- /dev/null
+++ b/lib/tests/modules/declare-nested-attrs-unsound.nix
@@ -0,0 +1,17 @@
+{ lib, ... }:
+
+{
+  options = {
+    value = lib.mkOption {
+      type = lib.types.nestedAttrsOf lib.types.int;
+      default = {
+        a = 1;
+        b = {
+          c = 2;
+          d.e = 3;
+          f = "4";
+        };
+      };
+    };
+  };
+}
diff --git a/lib/tests/modules/declare-nested-attrs.nix b/lib/tests/modules/declare-nested-attrs.nix
new file mode 100644
index 0000000000000..c10b357a2cee7
--- /dev/null
+++ b/lib/tests/modules/declare-nested-attrs.nix
@@ -0,0 +1,16 @@
+{ lib, ... }:
+
+{
+  options = {
+    value = lib.mkOption {
+      type = lib.types.nestedAttrsOf lib.types.int;
+      default = {
+        a = 1;
+        b = {
+          c = 2;
+          d.e = 3;
+        };
+      };
+    };
+  };
+}
diff --git a/lib/tests/modules/evalOption.nix b/lib/tests/modules/evalOption.nix
new file mode 100644
index 0000000000000..d3c4ae0f60c5b
--- /dev/null
+++ b/lib/tests/modules/evalOption.nix
@@ -0,0 +1,29 @@
+{ lib, ... }:
+let
+  inherit (lib) mkOption types;
+in
+{
+  options.bar = mkOption {
+    default =
+      lib.evalOption
+        (mkOption {
+          default = { };
+          type = types.submodule (
+            { config, ... }:
+            {
+              options = {
+                foo = mkOption {
+                  type = types.int;
+                };
+                baz = mkOption {
+                  default = config.foo + 1;
+                };
+              };
+            }
+          );
+        })
+        {
+          foo = 1;
+        };
+  };
+}
diff --git a/lib/tests/modules/extendOption.nix b/lib/tests/modules/extendOption.nix
new file mode 100644
index 0000000000000..b69db158067c4
--- /dev/null
+++ b/lib/tests/modules/extendOption.nix
@@ -0,0 +1,21 @@
+{ lib, ... }:
+{
+  options.foo =
+    lib.extendOption
+      {
+        boo.bar.default = "baz";
+      }
+      (
+        lib.mkOption {
+          default = { };
+          type = lib.types.submodule {
+            options.boo = lib.mkOption {
+              default = { };
+              type = lib.types.submodule {
+                options.bar = lib.mkOption { type = lib.types.int; };
+              };
+            };
+          };
+        }
+      );
+}
diff --git a/lib/tests/modules/extendSubmodule.nix b/lib/tests/modules/extendSubmodule.nix
new file mode 100644
index 0000000000000..cf2700881244a
--- /dev/null
+++ b/lib/tests/modules/extendSubmodule.nix
@@ -0,0 +1,21 @@
+{ lib, ... }:
+{
+  options.foo = lib.mkOption {
+    default = { };
+    type =
+      lib.extendSubmodule
+        {
+          boo.bar.default = "baz";
+        }
+        (
+          lib.types.submodule {
+            options.boo = lib.mkOption {
+              default = { };
+              type = lib.types.submodule {
+                options.bar = lib.mkOption { type = lib.types.int; };
+              };
+            };
+          }
+        );
+  };
+}
diff --git a/lib/tests/modules/types.nix b/lib/tests/modules/types.nix
index 6b11defbae362..d1da9d457d0b7 100644
--- a/lib/tests/modules/types.nix
+++ b/lib/tests/modules/types.nix
@@ -540,6 +540,7 @@ in
       # json & toml
       assert json.description == "JSON value";
       assert toml.description == "TOML value";
+      assert (types.nestedAttrsOf types.int).description == "nested attribute set of signed integer";
       # done
       "ok";
   };
diff --git a/lib/types.nix b/lib/types.nix
index f9ae3c82a1720..a4eb8f0f452d3 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -1795,6 +1795,105 @@ rec {
       nestedTypes.finalType = finalType;
     };
 
+  # `nestedAttrsOf elemType`: an attribute set nested to arbitrary depth whose
+  # leaves are of `elemType`. Namespace nodes recurse; leaves delegate to
+  # `elemType.merge`, so the element type owns how duplicate definitions at one
+  # leaf combine. A leaf that must tolerate agreeing duplicates simply uses an
+  # element type whose `merge` does so (e.g. `mergeEqualOption` instead of `raw`'s
+  # `mergeOneOption`) -- the nested type stays generic and hard-codes no duplicate
+  # handling of its own.
+  nestedAttrsOf =
+    elemType:
+    let
+      self = lib.types.mkOptionType {
+        name = "nestedAttrsOf";
+        description = "nested attribute set of ${elemType.description}";
+        descriptionClass = "composite";
+        nestedTypes.elemType = elemType;
+        check =
+          value: elemType.check value || (lib.isAttrs value && lib.all self.check (lib.attrValues value));
+
+        # Merge a list of definitions at a given location.
+        merge =
+          loc: defs:
+          let
+            # Collect all attribute names mentioned across every definition.
+            allNames = lib.unique (lib.concatMap (def: lib.attrNames def.value) defs);
+
+            # Top-level option names of the element type, used to detect leaves.
+            elemOptAttrs = elemType.getSubOptions [ ];
+
+            mergeAttr =
+              name:
+              let
+                # Narrow to the definitions that actually set this attribute,
+                # then run the module-system property pipeline on them so
+                # per-leaf priority wrappers
+                # (`mkOverride`/`mkDefault`/`mkOptionDefault`/`mkMerge`/`mkIf`)
+                # compose like they do at the top of an option. Without this,
+                # a tree-level `mkOptionDefault someTree` from one module is
+                # wiped out entirely by a normal-priority leaf override from
+                # another, and callers have to compose with
+                # `lib.recursiveUpdate` themselves.
+                rawSubDefs = lib.concatMap (
+                  def:
+                  lib.optional (def.value ? ${name}) {
+                    inherit (def) file;
+                    value = def.value.${name};
+                  }
+                ) defs;
+                subDefs = (lib.modules.applyLeafProperties rawSubDefs).values;
+
+                # Decide whether to recurse or delegate to the element type.
+                # We consider a value a leaf if its keys match the element type's known options.
+                # Otherwise it is an intermediate namespace attrset and we recurse.
+                # This is a way to cope with submodule types, as their `check` function accepts any attrset.
+                # While it would be nice to check their elements' types as well,
+                # the elements' types would only be available after merge.
+                isLeafLike = d: lib.all (k: elemOptAttrs ? ${k}) (lib.attrNames d.value);
+                goDeeper = lib.all (d: lib.isAttrs d.value && !isLeafLike d) subDefs;
+
+                # When the element type is a structured submodule (has known options)
+                # and a definition supplies a non-attrset, non-path value, throw a
+                # clear error instead of letting submodule.merge try to import it as
+                # a module path, which produces cryptic "doesn't represent an absolute
+                # path" or "No such file or directory" messages.
+                misshapen =
+                  if elemOptAttrs == { } then
+                    null
+                  else
+                    lib.findFirst (d: !lib.isAttrs d.value && !builtins.isPath d.value) null subDefs;
+              in
+              if misshapen != null then
+                throw ''
+                  In `${lib.options.showOption (loc ++ [ name ])}` (from ${misshapen.file}):
+                  expected an attribute set with keys from [${
+                    lib.concatStringsSep ", " (lib.filter (k: k != "_module") (lib.attrNames elemOptAttrs))
+                  }],
+                  but got a ${builtins.typeOf misshapen.value}.
+                  This usually means a level of nesting is missing — the body was written directly at the parent path instead of being wrapped under one of the expected keys.
+                ''
+              else if goDeeper then
+                self.merge (loc ++ [ name ]) subDefs
+              else
+                elemType.merge (loc ++ [ name ]) subDefs;
+          in
+          lib.genAttrs allNames mergeAttr;
+
+        # Forward sub-option/module machinery to the element type so that
+        # tooling (e.g. `nixos-option`) can still introspect leaf values.
+        getSubOptions = prefix: elemType.getSubOptions (prefix ++ [ "<name>" ]);
+        getSubModules = elemType.getSubModules;
+        substSubModules = m: nestedAttrsOf (elemType.substSubModules m);
+
+        # Standard functor so the type integrates with lib.types combinators.
+        functor = (lib.types.defaultFunctor "nestedAttrsOf") // {
+          wrapped = elemType;
+        };
+      };
+    in
+    self;
+
   /**
     Augment the given type with an additional type check function.
 
diff --git a/nixos/doc/manual/development/contracts.md b/nixos/doc/manual/development/contracts.md
new file mode 100644
index 0000000000000..ec559656861f7
--- /dev/null
+++ b/nixos/doc/manual/development/contracts.md
@@ -0,0 +1,267 @@
+# Contracts {#contracts}
+
+A *contract* is a typed interface between a *consumer* and a *provider* of a resource. The consumer declares what it needs (a `request`); the provider declares how it fulfills any such request (a `result`). Both sides talk to a shared option tree, `config.contracts.<type>`, instead of to each other directly. This decouples the consumer from any particular implementation: as long as the contract type matches, any provider can satisfy any consumer.
+
+Status: in development. This functionality is new in NixOS 26.05, and significant changes should be expected. Feedback is welcome in <https://github.com/NixOS/nixpkgs/pull/506343>.
+
+The motivating example is secrets. A web app may need a password file owned by a specific user with `0400` permissions; it shouldn't have to know whether that file was produced by [`agenix`](https://github.com/ryantm/agenix), [`sops-nix`](https://github.com/Mic92/sops-nix), or written out at activation time. With a `fileSecrets` contract, the web app declares the request (owner, mode, etc.) and reads the resulting `result.path`; switching providers becomes a one-line `defaultProvider` change.
+
+The same machinery works in [Home Manager](https://github.com/nix-community/home-manager) and any other module system that imports the generic contracts module.
+
+## Concepts {#contracts-concepts}
+
+For each contract type, `config.contracts.<type>` exposes:
+
+- `want.<consumer>.<...>`: entries declared by consumers, each carrying a `request` (typed by the contract's interface) and (once fulfilled) a `result`.
+- `requests`: read-side view of `want`, with everything except canonical request fields stripped. Providers read this.
+- `providers.<name>`: registered providers (see below).
+- `defaultProvider` / `defaultProviderName`: pick which provider fulfills `want` entries when no per-instance override is set.
+- `instances`: the resolved provider for each consumer/option pair (defaults to `defaultProvider`).
+- `results.<consumer>.<...>`: the read-side view of `instances`, with `request` fields stripped. Consumers read this.
+
+Contract type definitions live in `lib/contracts/definitions/`; the registry is `lib.contracts`. NixOS auto-seeds `config.contractDefinitions` from there, and other module systems can do the same by importing `lib.contract.module` and setting `config.contractDefinitions = lib.contracts`.
+
+## Consumers {#contracts-consumers}
+
+A consumer registers entries under `contracts.<type>.want` and reads from `contracts.<type>.results`.
+
+```nix
+# nixos/modules/services/web-apps/stash.nix
+{ lib, config, ... }:
+let
+  cfg = config.services.stash;
+  inherit (contracts) fileSecrets;
+in
+{
+  options.services.stash = {
+    passwordFile = lib.mkOption {
+      type = lib.types.nullOr (
+        fileSecrets.mkContract {
+          request = {
+            owner.default = cfg.user;
+            group.default = cfg.group;
+          };
+        }
+      );
+    };
+  };
+
+  config = {
+    contracts.fileSecrets.want.stash = {
+      inherit (cfg) passwordFile;
+    };
+
+    services.stash.passwordFile.result = config.contracts.fileSecrets.results.stash.passwordFile;
+  };
+}
+```
+
+`mkContract` returns a `submodule` type with the contract's `request` and `result` fields. `nestedAttrsOf` lets `want` be flat (`want.stash.secret`), grouped (`want.stash.db.primary`), or arbitrarily deep — `results` mirrors the same structure.
+
+## Providers {#contracts-providers}
+
+A provider implements `mkProviderType` and registers itself under `contracts.<type>.providers.<name>`.
+
+```nix
+# nixos/modules/testing/hardcoded-secret.nix (excerpt)
+{
+  config,
+  lib,
+  options,
+  pkgs,
+  ...
+}:
+let
+  inherit (lib.contracts) fileSecrets;
+in
+{
+  options.testing.hardcoded-secret = lib.mkOption {
+    type = lib.types.submodule {
+      options.fileSecrets = lib.mkOption {
+        default = config.contracts.fileSecrets.providerRequests.hardcoded-secret;
+        defaultText = lib.literalExpression "config.contracts.fileSecrets.providerRequests.hardcoded-secret";
+        type = fileSecrets.mkProviderType {
+          overrides.request = {
+            owner.default = "root";
+            group.default = "root";
+          };
+          providerOptions.content = lib.mkOption { type = lib.types.str; };
+          fulfill' =
+            { name, ... }:
+            {
+              path = "/run/hardcodedsecrets/${name}";
+            };
+        };
+      };
+    };
+  };
+
+  config.contracts.fileSecrets.providers.hardcoded-secret.module = options.testing.hardcoded-secret;
+}
+```
+
+`mkProviderType { fulfill, ... }` produces a `nestedAttrsOf submodule` type whose entries each have `request`, `result`, and any `providerOptions` declared on the provider. `fulfill` (`request -> result`) or its lower-level variant `fulfill'` (`{ request, name } -> result`) computes the result from the request at `mkDefault` priority.
+
+A provider's option `default` is its own slice of [`providerRequests`](#contracts-provider-selection) (`config.contracts.<type>.providerRequests.<name>`), the requests routed to that provider, rather than the whole `requests` tree. A non-selected provider's option is then empty, so any side-effects it gates on a non-empty option stay dormant.
+
+`providers.<name>` stores `{ module, contract? }`:
+
+- `module` is the provider's *option set* (typically `options.services.<service>`), so downstream tooling can introspect `.loc`/`.type` for GUI generation, schema export, etc.
+- `contract` is the path within `module.value` that holds the contract instances. It defaults to `[ "<contract-type>" ]` if `module.value` has that attribute (the conventional sub-option naming), and to `[ ]` when `module` itself is the contract-typed option.
+
+For lib-only providers that don't need a wrapping submodule, the option is itself the contract option:
+
+```nix
+{
+  lib,
+  config,
+  options,
+  ...
+}:
+{
+  options.services.increment.arithmetic = lib.mkOption {
+    type = config.contracts.arithmetic.mkProviderType {
+      fulfill =
+        { value }:
+        {
+          value = value + 1;
+        };
+    };
+  };
+  config.contracts.arithmetic.providers.increment.module = options.services.increment.arithmetic;
+}
+```
+
+The `contract` path is inferred as `[ ]` here, since `module.value` has no `.arithmetic` attribute.
+
+## Provider Selection {#contracts-provider-selection}
+
+A consumer's request is fulfilled by exactly one provider per instance. There are three ways to pick one:
+
+- `contracts.<type>.defaultProviderName = "<name>"` — by name (an enum over the registered providers).
+- `contracts.<type>.defaultProvider = config.contracts.<type>.providers."<name>"` — by reference (e.g. for renamed contracts where the name changed).
+- `contracts.<type>.instances."<consumer>"."<option>" = config.contracts.<type>.providers."<name>"` — per-instance override, written as a provider reference (`{ module, contract? }`); `resolvedInstances` resolves it to the provider's instance at the matching path, and `providerRequests` resolves it to that provider's name. GUIs read references as typed values rather than opaque ones.
+
+If none of the three is set and any consumer reads `results`, evaluation fails with `contracts.<type>.defaultProvider is unset`.
+
+Per-instance overrides compose against the `defaultProvider`-derived tree without `lib.recursiveUpdate`: `nestedAttrsOf` runs priority filtering at each leaf, so a `mkDefault` / `mkOptionDefault`-priority default at one path is preserved when another module sets a normal-priority override at a sibling path.
+
+`contracts.<type>.providerRequests."<name>"` exposes the `requests` tree filtered to the leaves routed to `<name>` (honoring all three selection mechanisms above). A provider's option `default` reads its own slice so it gathers only its routed requests; see [Providers](#contracts-providers).
+
+## Adding a Contract Type {#contracts-new-type}
+
+A contract type lives under `lib/contracts/definitions/` and exposes `meta` plus an `interface` of `request` and `result` options:
+
+```nix
+# lib/contracts/definitions/my-contract.nix
+{ lib, ... }:
+let
+  inherit (lib) mkOption types;
+in
+{
+  meta = {
+    description = "What this contract is for.";
+    maintainers = with lib.maintainers; [
+      # ...
+    ];
+  };
+  interface = {
+    request.someInput = mkOption { type = types.str; };
+    result.someOutput = mkOption { type = types.str; };
+  };
+}
+```
+
+Register it in `lib/contracts/definitions/default.nix`:
+
+```nix
+lib.mapAttrs
+  (
+    _: path:
+    lib.evalOption (lib.mkOption { type = lib.contract.definitionType; }) (import path { inherit lib; })
+  )
+  {
+    fileSecrets = ./file-secrets.nix;
+    myContract = ./my-contract.nix;
+  }
+```
+
+User-defined contract types — added directly to `config.contractDefinitions.<name>` rather than to nixpkgs — are also picked up automatically.
+
+## Chaining {#contracts-chaining}
+
+Providers can themselves be consumers. A `databaseConnection` provider can consume `fileSecrets` for credentials:
+
+```nix
+{
+  lib,
+  config,
+  options,
+  ...
+}:
+{
+  options.services.pgProvider.databaseConnection = lib.mkOption {
+    type = dbContract.mkProviderType {
+      fulfill =
+        { dbName }:
+        {
+          connectionString = "postgresql:///${dbName}?password_file=${config.contracts.fileSecrets.results.pgProvider.credential.path}";
+        };
+    };
+  };
+
+  config = {
+    contracts.databaseConnection.providers.pgProvider.module =
+      options.services.pgProvider.databaseConnection;
+    contracts.fileSecrets.want.pgProvider.credential = {
+      request = {
+        owner = "postgres";
+        group = "postgres";
+      };
+    };
+  };
+}
+```
+
+Nix's lazy evaluation resolves the chain automatically — no explicit ordering is needed.
+
+## Cross-Node Contracts {#contracts-cross-node}
+
+A contract spanning two NixOS nodes has no shared `config.contracts`. Evaluate the contract once in a shared `let` block and inject the resolved value into each node:
+
+```nix
+{ lib, ... }:
+let
+  shared =
+    (lib.evalModules {
+      modules = [
+        ./arithmetic-contract.nix
+        consumerModule
+        providerModule
+      ];
+    }).config;
+  resultValue = shared.contracts.arithmetic.results.consumer.operation.value;
+in
+{
+  nodes.consumer = {
+    imports = [
+      ./arithmetic-contract.nix
+      consumerModule
+    ];
+    environment.etc."result".text = toString resultValue;
+  };
+  nodes.provider = providerConfig;
+}
+```
+
+Because contracts are an evaluation-time mechanism, this produces the value at derivation-build time; each node sees its slice as a literal.
+
+## Versioning and Renames {#contracts-renames}
+
+Renaming a request option is done with an alias module in `interface.extraImports.request`; the `requests` view filters aliases out so providers only see the canonical name. Renaming a contract type can't use `mkRenamedOptionModule` (`contracts` is one submodule-typed option), so it's done by declaring the deprecated type alongside the new one and emitting a `warnings` entry when the old `want` is non-empty. See the corresponding tests under `lib/tests/modules/contracts-{rename-warning,contract-rename}.nix` for the patterns.
+
+## Reference {#contracts-reference}
+
+- Generic module: [`lib/contracts/module.nix`](https://github.com/NixOS/nixpkgs/blob/master/lib/contracts/module.nix)
+- NixOS wrapper: [`nixos/modules/contracts/default.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/contracts/default.nix)
+- Test reference: [`lib/tests/modules/contracts-*.nix`](https://github.com/NixOS/nixpkgs/tree/master/lib/tests/modules) and [`nixos/tests/contracts/`](https://github.com/NixOS/nixpkgs/tree/master/nixos/tests/contracts)
diff --git a/nixos/doc/manual/development/development.md b/nixos/doc/manual/development/development.md
index 37762afb41dab..54051397eccc5 100644
--- a/nixos/doc/manual/development/development.md
+++ b/nixos/doc/manual/development/development.md
@@ -13,4 +13,5 @@ nixos-tests.chapter.md
 developing-the-test-driver.chapter.md
 testing-installer.chapter.md
 modular-services.md
+contracts.md
 ```
diff --git a/nixos/doc/manual/redirects.json b/nixos/doc/manual/redirects.json
index fa6f1989ba71e..7d3f90b4f8702 100644
--- a/nixos/doc/manual/redirects.json
+++ b/nixos/doc/manual/redirects.json
@@ -2847,5 +2847,38 @@
   ],
   "sec-release-13.10": [
     "release-notes.html#sec-release-13.10"
+  ],
+  "module-contracts": [
+    "index.html#module-contracts"
+  ],
+  "contracts": [
+    "index.html#contracts"
+  ],
+  "contracts-concepts": [
+    "index.html#contracts-concepts"
+  ],
+  "contracts-consumers": [
+    "index.html#contracts-consumers"
+  ],
+  "contracts-providers": [
+    "index.html#contracts-providers"
+  ],
+  "contracts-provider-selection": [
+    "index.html#contracts-provider-selection"
+  ],
+  "contracts-new-type": [
+    "index.html#contracts-new-type"
+  ],
+  "contracts-chaining": [
+    "index.html#contracts-chaining"
+  ],
+  "contracts-cross-node": [
+    "index.html#contracts-cross-node"
+  ],
+  "contracts-renames": [
+    "index.html#contracts-renames"
+  ],
+  "contracts-reference": [
+    "index.html#contracts-reference"
   ]
 }
diff --git a/nixos/doc/manual/release-notes/rl-2605.section.md b/nixos/doc/manual/release-notes/rl-2605.section.md
index 0da2ba935bccf..b19a6f222a397 100644
--- a/nixos/doc/manual/release-notes/rl-2605.section.md
+++ b/nixos/doc/manual/release-notes/rl-2605.section.md
@@ -41,6 +41,10 @@
   The default location of system.nix is `/etc/nixos/system.nix` and can be changed by setting the `<nixos-system>` search path.
   `nixos-rebuild` and `nixos-install` can now also load a system.nix file in the current directory (only if `--attr` is used) or from a directory specified with `--file`.
 
+- A new [contracts](#contracts) system lets services declare typed `request`/`result` interfaces, with consumers and providers wired through `config.contracts.<type>` rather than to each other directly.
+  Provider entries carry `module` references to the underlying option set, so GUI tooling can derive JSON schemas from them.
+  Currently ships one contract type, `fileSecrets`, with a `hardcoded-secret` test provider; the `services.stash` module is the first consumer.
+
 - The default kernel package has been updated from 6.12 to 6.18. All supported kernels remain available.
 
 - The default D-Bus implementation has been switched from `dbus` to `dbus-broker`. dbus-broker provides
diff --git a/nixos/modules/contracts/contracts.md b/nixos/modules/contracts/contracts.md
new file mode 100644
index 0000000000000..c7201da429385
--- /dev/null
+++ b/nixos/modules/contracts/contracts.md
@@ -0,0 +1,5 @@
+# Contracts {#module-contracts}
+
+The contracts wrapper exposes `config.contracts.<type>` and `config.contractDefinitions` to NixOS, seeded with the contract types defined in `lib.contracts`. Through these options, services declare typed `request`/`result` interfaces and providers register implementations, decoupling consumers from any particular implementation.
+
+For motivation, the consumer/provider patterns, provider selection, chaining, cross-node usage, and how to add a new contract type, see the [Contracts](#contracts) chapter in *Development*.
diff --git a/nixos/modules/contracts/default.nix b/nixos/modules/contracts/default.nix
new file mode 100644
index 0000000000000..2bc93fd74c6cb
--- /dev/null
+++ b/nixos/modules/contracts/default.nix
@@ -0,0 +1,34 @@
+# NixOS contracts wrapper - imports the generic contracts module and seeds
+# nixpkgs-shipped contract types so they appear in `config.contractDefinitions`
+# alongside any user-defined types.
+#
+# `lib.contracts` are also used as a fallback directly in `contracts` option
+# generation (see `lib/contracts/module.nix`), making this module safe for
+# the docs build sandbox.
+#
+# To add contracts support to another module system (home-manager, nix-darwin),
+# create an equivalent module:
+#
+#   { lib, ... }:
+#   {
+#     imports = [ lib.contract.module ];
+#     config.contractDefinitions = lib.mapAttrs (_: contract: {
+#       inherit (contract) meta interface behaviorTest;
+#     }) lib.contracts;
+#   }
+#
+# This gives the system `config.contracts.*` with all nixpkgs contract types.
+# To also support modular services, add a bridge module and a service manager
+# integration; see `nixos/modules/system/service/` for the NixOS reference.
+{ lib, ... }:
+{
+  imports = [ lib.contract.module ];
+  meta.doc = ./contracts.md;
+  # Seed nixpkgs-shipped contract types so they appear in `config.contractDefinitions`
+  # alongside any user-defined types.
+  # Only settable fields are listed here; `_mkProviderType` and `mkContract` are
+  # `readOnly` options whose defaults must not be overridden from config.
+  config.contractDefinitions = lib.mapAttrs (_: contract: {
+    inherit (contract) meta interface behaviorTest;
+  }) lib.contracts;
+}
diff --git a/nixos/modules/module-list.nix b/nixos/modules/module-list.nix
index a9dcefebf99f3..09e92eea85ed3 100644
--- a/nixos/modules/module-list.nix
+++ b/nixos/modules/module-list.nix
@@ -48,6 +48,7 @@
   ./config/xdg/sounds.nix
   ./config/xdg/terminal-exec.nix
   ./config/zram.nix
+  ./contracts/default.nix
   ./hardware/acpilight.nix
   ./hardware/all-firmware.nix
   ./hardware/all-hardware.nix
@@ -2013,6 +2014,7 @@
   ./tasks/stratis.nix
   ./tasks/swraid.nix
   ./tasks/trackpoint.nix
+  ./testing/hardcoded-secret.nix
   ./testing/service-runner.nix
   ./virtualisation/amazon-options.nix
   ./virtualisation/appvm.nix
diff --git a/nixos/modules/services/web-apps/stash.nix b/nixos/modules/services/web-apps/stash.nix
index e4e1c65d09327..ce4f1add6af58 100644
--- a/nixos/modules/services/web-apps/stash.nix
+++ b/nixos/modules/services/web-apps/stash.nix
@@ -6,6 +6,7 @@
 }:
 let
   inherit (lib)
+    contracts
     getExe
     literalExpression
     mkEnableOption
@@ -16,6 +17,8 @@ let
     toUpper
     types
     ;
+  inherit (contracts) fileSecrets;
+  inherit (config.contracts.fileSecrets.results.stash) jwtSecretKey sessionStoreKey;
 
   cfg = config.services.stash;
 
@@ -366,8 +369,35 @@ let
             done
           '';
     };
+
+  secretOptionType =
+    let
+      contractSecretsType = fileSecrets.mkContract {
+        request = {
+          owner.default = cfg.user;
+          group.default = cfg.group;
+        };
+      };
+    in
+    types.oneOf [
+      types.path
+      contractSecretsType
+    ];
+
+  inherit (lib.contract) isInstance;
 in
 {
+  imports = [
+    (lib.mkRenamedOptionModule
+      [ "services" "stash" "jwtSecretKeyFile" ]
+      [ "services" "stash" "jwtSecretKey" ]
+    )
+    (lib.mkRenamedOptionModule
+      [ "services" "stash" "sessionStoreKeyFile" ]
+      [ "services" "stash" "sessionStoreKey" ]
+    )
+  ];
+
   meta = {
     buildDocsInSandbox = false;
     maintainers = with lib.maintainers; [ DrakeTDL ];
@@ -418,7 +448,7 @@ in
       };
 
       passwordFile = mkOption {
-        type = types.nullOr types.path;
+        type = types.nullOr secretOptionType;
         default = null;
         example = "/path/to/password/file";
         description = ''
@@ -431,13 +461,21 @@ in
         '';
       };
 
-      jwtSecretKeyFile = mkOption {
-        type = types.path;
+      jwtSecretKey = mkOption {
+        type = secretOptionType;
         description = "Path to file containing a secret used to sign JWT tokens.";
+        default.result = jwtSecretKey;
+        defaultText = ''
+          { result = config.contracts.fileSecrets.results.stash.jwtSecretKey; }
+        '';
       };
-      sessionStoreKeyFile = mkOption {
-        type = types.path;
+      sessionStoreKey = mkOption {
+        type = secretOptionType;
         description = "Path to file containing a secret for session store.";
+        default.result = sessionStoreKey;
+        defaultText = ''
+          { result = config.contracts.fileSecrets.results.stash.sessionStoreKey; }
+        '';
       };
 
       mutableSettings = mkOption {
@@ -473,6 +511,12 @@ in
       }
     ];
 
+    contracts.fileSecrets.want.stash = {
+      passwordFile = if isInstance cfg.passwordFile then cfg.passwordFile else { };
+      jwtSecretKey = if isInstance cfg.jwtSecretKey then cfg.jwtSecretKey else { };
+      sessionStoreKey = if isInstance cfg.sessionStoreKey then cfg.sessionStoreKey else { };
+    };
+
     services.stash.settings = {
       username = mkIf (cfg.username != null) cfg.username;
       plugins_path = mkIf (!cfg.mutablePlugins) cfg.plugins;
@@ -514,9 +558,15 @@ in
               install -d ${cfg.settings.generated}
               if [[ -z "${toString cfg.mutableSettings}" || ! -f ${cfg.dataDir}/config.yml ]]; then
                 env \
-                  password=$(< ${cfg.passwordFile}) \
-                  jwtSecretKeyFile=$(< ${cfg.jwtSecretKeyFile}) \
-                  sessionStoreKeyFile=$(< ${cfg.sessionStoreKeyFile}) \
+                  password=$(< ${
+                    if isInstance cfg.passwordFile then cfg.passwordFile.result.path else cfg.passwordFile
+                  }) \
+                  jwtSecretKeyFile=$(< ${
+                    if isInstance cfg.jwtSecretKey then cfg.jwtSecretKey.result.path else cfg.jwtSecretKey
+                  }) \
+                  sessionStoreKeyFile=$(< ${
+                    if isInstance cfg.sessionStoreKey then cfg.sessionStoreKey.result.path else cfg.sessionStoreKey
+                  }) \
                   ${lib.getExe pkgs.yq-go} '
                     .jwt_secret_key = strenv(jwtSecretKeyFile) |
                     .session_store_key = strenv(sessionStoreKeyFile) |
diff --git a/nixos/modules/testing/hardcoded-secret.nix b/nixos/modules/testing/hardcoded-secret.nix
new file mode 100644
index 0000000000000..e6156a6b639b5
--- /dev/null
+++ b/nixos/modules/testing/hardcoded-secret.nix
@@ -0,0 +1,135 @@
+{
+  config,
+  lib,
+  options,
+  pkgs,
+  ...
+}:
+let
+  cfg = config.testing.hardcoded-secret;
+
+  inherit (lib)
+    mkOption
+    ;
+  inherit (lib.types)
+    str
+    submodule
+    ;
+  inherit (pkgs) writeText;
+  contract = "fileSecrets";
+  providerName = "hardcoded-secret";
+  inherit (lib.contract.forModule config) fileSecrets;
+in
+{
+  options.testing.hardcoded-secret = mkOption {
+    description = ''
+      Hardcoded file secrets. These should only be used in tests.
+
+      They aim to replace the usage of pkgs.writeText in NixOS VM tests
+      as those make the file world readable
+      while this module set runtime permissions on the file.
+      This makes the tests more accurate, ensuring the permissions
+      set by the contract consumer are correct.
+    '';
+    type = submodule (hardcoded-secret: {
+      options = {
+        directory = mkOption {
+          description = "The directory to store the secrets at.";
+          type = str;
+          default = "/run/hardcodedsecrets";
+        };
+        ${contract} = mkOption {
+          description = ''
+            Instances of the fileSecrets contract, including secret content and contract request/result.
+          '';
+          example = lib.literalExpression ''
+            {
+              my.secret = {
+                request = {
+                  owner = "me";
+                  mode = "0400";
+                };
+                content = "My Secret";
+              };
+            }
+          '';
+          default = config.contracts.${contract}.providerRequests.${providerName};
+          defaultText = lib.literalExpression "config.contracts.${contract}.providerRequests.${providerName}";
+          type = fileSecrets.mkProviderType {
+            overrides.request = {
+              owner.default = "root";
+              group.default = "root";
+            };
+            providerOptions.content = mkOption {
+              type = str;
+              description = ''
+                Content of the secret as a string.
+
+                This will be stored in the nix store and should only be used for testing or maybe in dev.
+              '';
+            };
+            fulfill' =
+              { name, ... }:
+              {
+                path = "${hardcoded-secret.config.directory}/${name}";
+              };
+          };
+        };
+      };
+    });
+  };
+
+  config = {
+    contracts.${contract}.providers.hardcoded-secret.module = options.testing.hardcoded-secret;
+
+    systemd.services = lib.mkMerge [
+      # Oneshot services that materialize each secret after users and sysusers are ready.
+      (lib.concatMapNestedAttrs'
+        (options.testing.hardcoded-secret.type.getSubOptions [ ]).${contract}.type
+        (
+          path: cfg':
+          let
+            name = lib.concatStringsSep "_" path;
+            source = writeText "hardcodedsecret_${name}_content" cfg'.content;
+            inherit (cfg') request result;
+          in
+          {
+            "hardcoded-secret-${name}" = {
+              description = "Materialize hardcoded test secret ${name}";
+              wantedBy = [ "multi-user.target" ];
+              before = [ "multi-user.target" ];
+              after = [
+                "systemd-sysusers.service"
+                "nixos-activation.service"
+              ];
+              serviceConfig = {
+                Type = "oneshot";
+                RemainAfterExit = true;
+              };
+              script = ''
+                install -D -m ${request.mode} -o ${request.owner} -g ${request.group} \
+                  ${source} "${result.path}"
+              '';
+            };
+          }
+        )
+        cfg.${contract}
+      )
+
+      # Make each top-level consumer service wait for all its secret services.
+      # Assumes secrets are keyed as `<appName>.<secretName>` matching `<appName>.service`.
+      (lib.mapAttrs (
+        appName: appSecrets:
+        let
+          secretSvcs = lib.mapAttrsToList (
+            secretName: _: "hardcoded-secret-${appName}_${secretName}.service"
+          ) appSecrets;
+        in
+        {
+          after = secretSvcs;
+          requires = secretSvcs;
+        }
+      ) cfg.${contract})
+    ];
+  };
+}
diff --git a/nixos/tests/all-tests.nix b/nixos/tests/all-tests.nix
index 378db6403e129..b302a306e6ac2 100644
--- a/nixos/tests/all-tests.nix
+++ b/nixos/tests/all-tests.nix
@@ -416,6 +416,9 @@ in
   containers-restart_networking = runTest ./containers-restart_networking.nix;
   containers-tmpfs = runTest ./containers-tmpfs.nix;
   containers-unified-hierarchy = runTest ./containers-unified-hierarchy.nix;
+  contracts = import ./contracts {
+    inherit runTest;
+  };
   convos = runTest ./convos.nix;
   coredns = runTest ./coredns.nix;
   corerad = runTest ./corerad.nix;
diff --git a/nixos/tests/contracts/arithmetic-contract.nix b/nixos/tests/contracts/arithmetic-contract.nix
new file mode 100644
index 0000000000000..36ee8ddcf5036
--- /dev/null
+++ b/nixos/tests/contracts/arithmetic-contract.nix
@@ -0,0 +1,25 @@
+# Defines the `arithmetic` contract type for use in contract tests.
+# This module can be imported in both NixOS tests and bare lib.evalModules tests
+# (the latter must also import `nixos/modules/contracts/default.nix` separately).
+{ lib, ... }:
+let
+  inherit (lib) mkOption types;
+in
+{
+  config.contractDefinitions.arithmetic = {
+    meta = {
+      description = "A contract for arithmetic operations, used for testing.";
+      maintainers = [ ];
+    };
+    interface = {
+      request.value = mkOption {
+        description = "Input value.";
+        type = types.int;
+      };
+      result.value = mkOption {
+        description = "Output value.";
+        type = types.int;
+      };
+    };
+  };
+}
diff --git a/nixos/tests/contracts/arithmetic-increment-provider.nix b/nixos/tests/contracts/arithmetic-increment-provider.nix
new file mode 100644
index 0000000000000..f5e0371097d39
--- /dev/null
+++ b/nixos/tests/contracts/arithmetic-increment-provider.nix
@@ -0,0 +1,32 @@
+# Modular service provider for the arithmetic contract: returns request.value + 1.
+# Pure provider with no default-selection opinion -- consumers select the default themselves.
+# Shared across contract tests that need an increment provider as a modular service.
+{
+  lib,
+  config,
+  options,
+  ...
+}:
+let
+  inherit (lib) mkOption;
+  inherit (config.contracts) arithmetic;
+in
+{
+  _class = "service";
+  imports = [ ./arithmetic-contract.nix ];
+  options.arithmetic = mkOption {
+    description = "Arithmetic contract instances fulfilled by this increment provider.";
+    default = arithmetic.providerRequests.increment;
+    type = arithmetic.mkProviderType {
+      fulfill =
+        { value }:
+        {
+          value = value + 1;
+        };
+    };
+  };
+  config = {
+    contracts.arithmetic.providers.increment.module = options.arithmetic;
+    process.argv = [ "/run/current-system/sw/bin/true" ];
+  };
+}
diff --git a/nixos/tests/contracts/chaining.nix b/nixos/tests/contracts/chaining.nix
new file mode 100644
index 0000000000000..5f1f899348ab7
--- /dev/null
+++ b/nixos/tests/contracts/chaining.nix
@@ -0,0 +1,139 @@
+# Tests contract chaining: a provider that is also a consumer.
+#
+# Chain: webapp <-[databaseConnection]-- pgProvider <--[fileSecret]-- hardcoded-secret
+#
+# - `webapp` (consumer): requests a database connection via the
+#   `databaseConnection` contract and reads `result.connectionString`.
+# - `pgProvider` (provider + consumer): fulfills `databaseConnection`
+#   requests, but itself consumes `fileSecrets` to get a credential file.
+#   The connection string embeds the credential path from `fileSecrets`.
+# - `hardcoded-secret` (provider): fulfills `fileSecrets` requests by
+#   writing secret content to files with the requested permissions.
+#
+# Nix lazy evaluation resolves the chain automatically -- no explicit
+# ordering is needed. The test verifies both the eval-time plumbing
+# (assertions) and the runtime result (credential file exists with
+# correct content).
+{ lib, ... }:
+let
+  inherit (lib) mkOption types;
+
+  # Database connection contract, defined inline for the test.
+  dbContractDef = {
+    meta = {
+      description = ''
+        Contract for database connections where a consumer requests a named
+        database and a provider returns a connection string.
+      '';
+      maintainers = [ ];
+    };
+    interface = {
+      request.dbName = mkOption {
+        description = "Name of the database to connect to.";
+        type = types.str;
+      };
+      result.connectionString = mkOption {
+        description = "Connection string for the database.";
+        type = types.str;
+      };
+    };
+  };
+
+in
+{
+  name = "contracts-chaining";
+
+  nodes.machine =
+    {
+      config,
+      options,
+      ...
+    }:
+    let
+      credentialPath = config.contracts.fileSecrets.results.pgProvider.credential.path;
+      expectedConnectionString = "postgresql:///webappdb?password_file=${credentialPath}";
+      inherit (lib.contract.forModule config) databaseConnection;
+    in
+    {
+      imports = [
+        # Provides the hardcoded-secret fileSecrets provider.
+        ../../modules/testing/hardcoded-secret.nix
+      ];
+
+      # --- WEBAPP: consumer of databaseConnection ---
+
+      options.services.webapp.db = mkOption {
+        description = "Database connection for the webapp.";
+        type = databaseConnection.mkContract {
+          request.dbName.default = "webappdb";
+        };
+      };
+
+      # --- PGPROVIDER: provides databaseConnection, consumes fileSecrets ---
+
+      options.services.pgProvider.databaseConnection = mkOption {
+        description = "Database connection instances fulfilled by this provider.";
+        default = config.contracts.databaseConnection.providerRequests.pgProvider;
+        type = databaseConnection.mkProviderType {
+          fulfill =
+            { dbName }:
+            {
+              connectionString = "postgresql:///${dbName}?password_file=${credentialPath}";
+            };
+        };
+      };
+
+      config = {
+        contractDefinitions.databaseConnection = dbContractDef;
+
+        # Consumer wiring: register want, read result.
+        contracts.databaseConnection.want.webapp.db = config.services.webapp.db;
+        services.webapp.db.result = config.contracts.databaseConnection.results.webapp.db;
+
+        # Provider wiring: register provider.
+        contracts.databaseConnection.providers.pgProvider.module =
+          options.services.pgProvider.databaseConnection;
+
+        # Chain: the database provider also consumes fileSecrets for credentials.
+        contracts.fileSecrets.want.pgProvider.credential = {
+          request = {
+            owner = "root";
+            group = "root";
+          };
+        };
+
+        # Set up credential content for the hardcoded-secret provider.
+        testing.hardcoded-secret.fileSecrets.pgProvider.credential.content = "s3cret-db-password";
+
+        # Default providers.
+        contracts.databaseConnection.defaultProvider =
+          config.contracts.databaseConnection.providers.pgProvider;
+        contracts.fileSecrets.defaultProvider = config.contracts.fileSecrets.providers.hardcoded-secret;
+
+        # --- ASSERTIONS ---
+
+        assertions = [
+          {
+            assertion = config.services.webapp.db.result.connectionString == expectedConnectionString;
+            message = ''
+              chaining: webapp should receive connection string
+              '${expectedConnectionString}'
+              but got '${config.services.webapp.db.result.connectionString}'
+            '';
+          }
+        ];
+      };
+    };
+
+  testScript = ''
+    machine.start()
+    machine.wait_for_unit("multi-user.target")
+
+    # The credential file from the fileSecrets chain should exist with the right content.
+    content = machine.succeed("cat /run/hardcodedsecrets/credential").strip()
+    assert content == "s3cret-db-password", \
+        f"Expected credential content 's3cret-db-password', got '{content}'"
+  '';
+
+  meta.maintainers = with lib.maintainers; [ kiara ];
+}
diff --git a/nixos/tests/contracts/cross-node-modular-services.nix b/nixos/tests/contracts/cross-node-modular-services.nix
new file mode 100644
index 0000000000000..4709aa154f8d5
--- /dev/null
+++ b/nixos/tests/contracts/cross-node-modular-services.nix
@@ -0,0 +1,96 @@
+# Tests contracts spanning separate NixOS nodes, with both consumer and provider
+# implemented as modular services.
+#
+# Mirrors `cross-node.nix` but demonstrates that the cross-node pattern works
+# equally well when each side is a modular service rather than a plain NixOS module.
+#
+# The shared eval uses `lib.services.evalServices` to resolve contracts across
+# the two peer services without a parent system. Each node then bakes the
+# eval-time `resultValue` into static config.
+#
+# Exercises the `defaultProviderName` code path in `lib/services/lib.nix::evalServices`.
+# See `cross-node-modular-services-direct.nix` for the `defaultProvider` path.
+{ lib, ... }:
+let
+  portable-lib = import ../../../lib/services/lib.nix { inherit lib; };
+
+  arithmeticContract = ./arithmetic-contract.nix;
+
+  consumerServiceModule =
+    { lib, config, ... }:
+    {
+      _class = "service";
+      imports = [ arithmeticContract ];
+      options.consumer.operation = lib.mkOption {
+        default.result = config.contracts.arithmetic.results.operation;
+        type = config.contractDefinitions.arithmetic.mkContract { };
+      };
+      config = {
+        consumer.operation.request.value = 5;
+        contracts.arithmetic.want = { inherit (config.consumer) operation; };
+        process.argv = [ "/run/current-system/sw/bin/true" ];
+      };
+    };
+
+  providerNode = {
+    imports = [ arithmeticContract ];
+    system.services.increment.imports = [
+      ./arithmetic-increment-provider.nix
+      { contracts.arithmetic.defaultProviderName = "increment"; }
+    ];
+  };
+
+  evaluated = portable-lib.evalServices {
+    services = {
+      consumer = consumerServiceModule;
+      increment = providerNode.system.services.increment;
+    };
+  };
+
+  resultValue = evaluated.contracts.arithmetic.results.consumer.operation.value;
+in
+{
+  name = "contracts-cross-node-modular-services";
+
+  nodes = {
+    provider =
+      { pkgs, ... }:
+      {
+        imports = [
+          providerNode
+          {
+            systemd.services.arithmetic-server = {
+              wantedBy = [ "multi-user.target" ];
+              script = ''
+                mkdir -p /run/arithmetic
+                echo -n ${lib.escapeShellArg (toString resultValue)} > /run/arithmetic/result
+                exec ${pkgs.python3}/bin/python3 -m http.server 8080 --directory /run/arithmetic
+              '';
+            };
+            networking.firewall.allowedTCPPorts = [ 8080 ];
+          }
+        ];
+      };
+
+    consumer =
+      { ... }:
+      {
+        imports = [ arithmeticContract ];
+        system.services.instance.imports = [ consumerServiceModule ];
+        environment.etc."arithmetic-expected".text = toString resultValue;
+      };
+  };
+
+  testScript = ''
+    provider.wait_for_unit("arithmetic-server.service")
+    consumer.wait_for_unit("multi-user.target")
+
+    expected = consumer.succeed("cat /etc/arithmetic-expected").strip()
+    assert expected == "${toString resultValue}", f"contract result mismatch: got {expected!r}"
+
+    served = consumer.succeed("curl -sf http://provider:8080/result").strip()
+    assert served == expected, f"provider served {served!r}, consumer expected {expected!r}"
+  '';
+
+  meta.maintainers = with lib.maintainers; [ kiara ];
+}
diff --git a/nixos/tests/contracts/cross-node.nix b/nixos/tests/contracts/cross-node.nix
new file mode 100644
index 0000000000000..3bdf7d7481e16
--- /dev/null
+++ b/nixos/tests/contracts/cross-node.nix
@@ -0,0 +1,132 @@
+# Tests contracts spanning separate NixOS nodes.
+#
+# Since contracts are a Nix evaluation-time mechanism, cross-node wiring is done
+# by evaluating contracts once in a shared `let` block, then injecting the results
+# into each node's configuration:
+#
+# - `consumerModule` and `incrementProviderModule` define each side's contract role.
+# - Each node imports its respective module plus `./arithmetic-contract.nix` (the contract type).
+# - `sharedContracts` composes both modules in a single `lib.evalModules` call.
+# - The consumer node is configured with the result injected from the shared evaluation.
+# - The test verifies the consumer's value matches what the provider serves at runtime.
+{ pkgs, lib, ... }:
+let
+  # Consumer: declares a request for an arithmetic operation with value = 5.
+  consumerModule =
+    { ... }:
+    {
+      contracts.arithmetic.want.consumer.operation.request.value = 5;
+    };
+
+  # Provider: fulfills arithmetic requests by incrementing the value by 1.
+  incrementProviderModule =
+    {
+      lib,
+      config,
+      options,
+      ...
+    }:
+    let
+      inherit (lib) mkOption;
+      inherit (config.contracts) arithmetic;
+    in
+    {
+      options.services.increment.arithmetic = mkOption {
+        default = arithmetic.providerRequests.increment;
+        type = arithmetic.mkProviderType {
+          fulfill =
+            { value }:
+            {
+              value = value + 1;
+            };
+        };
+      };
+      config = {
+        contracts.arithmetic.providers.increment.module = options.services.increment.arithmetic;
+        contracts.arithmetic.defaultProvider = arithmetic.providers.increment;
+      };
+    };
+
+  # Shared contracts evaluation: composes consumer and provider, producing results
+  # that both node configs are derived from.
+  # Both `consumerModule` and `incrementProviderModule` are reused from the node definitions
+  # above, so the shared evaluation stays in sync with what each node imports.
+  sharedContracts =
+    (lib.evalModules {
+      modules = [
+        # Bundles the contracts module + arithmetic type for bare `lib.evalModules` contexts.
+        ../../../lib/tests/modules/contracts-arithmetic-contract.nix
+        # meta stub: `nixos/modules/contracts/default.nix` sets `meta.buildDocsInSandbox = false`
+        # because `contracts` options are dynamically typed from `config.contractDefinitions`, making
+        # the docs sandbox unable to evaluate them. `meta` itself is a NixOS-level option not
+        # present in a bare `lib.evalModules` context, so we stub it out here.
+        {
+          options.meta = lib.mkOption {
+            type = lib.types.attrs;
+            default = { };
+          };
+        }
+        consumerModule
+        incrementProviderModule
+      ];
+    }).config;
+
+  resultValue = sharedContracts.contracts.arithmetic.results.consumer.operation.value;
+in
+{
+  name = "contracts-cross-node";
+
+  nodes = {
+    # Provider node: imports its role module; `./arithmetic-contract.nix` makes
+    # `contracts.arithmetic.*` options available without re-importing the contracts module
+    # (already in the NixOS module list). The node has no consumer `want` entries, so
+    # `contracts.arithmetic.requests` is empty — the bridge assertion stays dormant.
+    provider =
+      { pkgs, ... }:
+      {
+        imports = [
+          ./arithmetic-contract.nix
+          incrementProviderModule
+        ];
+        # Expose the computed result over HTTP so the consumer can verify it at runtime.
+        # In a real use case this would be a proper service (e.g. a secrets manager).
+        systemd.services.arithmetic-server = {
+          wantedBy = [ "multi-user.target" ];
+          script = ''
+            mkdir -p /run/arithmetic
+            echo -n ${lib.escapeShellArg (toString resultValue)} > /run/arithmetic/result
+            exec ${pkgs.python3}/bin/python3 -m http.server 8080 --directory /run/arithmetic
+          '';
+        };
+        networking.firewall.allowedTCPPorts = [ 8080 ];
+      };
+
+    # Consumer node: imports its role module; uses `resultValue` from the shared evaluation
+    # since its own NixOS evaluation has no provider to fulfill its `want` entries.
+    consumer =
+      { ... }:
+      {
+        imports = [
+          ./arithmetic-contract.nix
+          consumerModule
+        ];
+        # In a real use case this would configure a service (e.g. a database URL or file path).
+        environment.etc."arithmetic-expected".text = toString resultValue;
+      };
+  };
+
+  testScript = ''
+    provider.wait_for_unit("arithmetic-server.service")
+    consumer.wait_for_unit("multi-user.target")
+
+    # Contract result is baked into the consumer's config at evaluation time.
+    expected = consumer.succeed("cat /etc/arithmetic-expected").strip()
+    assert expected == "${toString resultValue}", f"contract result mismatch: got {expected!r}"
+
+    # At runtime, the consumer retrieves the value served by the provider node.
+    served = consumer.succeed("curl -sf http://provider:8080/result").strip()
+    assert served == expected, f"provider served {served!r}, consumer expected {expected!r}"
+  '';
+
+  meta.maintainers = with lib.maintainers; [ kiara ];
+}
diff --git a/nixos/tests/contracts/default.nix b/nixos/tests/contracts/default.nix
new file mode 100644
index 0000000000000..f940f2766bb23
--- /dev/null
+++ b/nixos/tests/contracts/default.nix
@@ -0,0 +1,7 @@
+{ runTest }:
+{
+  chaining = runTest ./chaining.nix;
+  cross-node = runTest ./cross-node.nix;
+  cross-node-modular-services = runTest ./cross-node-modular-services.nix;
+  filesecrets-hardcoded-secret = runTest ./filesecrets/hardcoded-secret.nix;
+}
diff --git a/nixos/tests/contracts/filesecrets/hardcoded-secret.nix b/nixos/tests/contracts/filesecrets/hardcoded-secret.nix
new file mode 100644
index 0000000000000..bef88255f7587
--- /dev/null
+++ b/nixos/tests/contracts/filesecrets/hardcoded-secret.nix
@@ -0,0 +1,21 @@
+{
+  lib,
+  ...
+}:
+{
+  meta.maintainers = [ lib.maintainers.ibizaman ];
+}
+// lib.contracts.fileSecrets.behaviorTest {
+  name = "hardcoded-secret";
+  wantPath = [ "mysecret" ];
+  extraModules = [
+    ../../../modules/testing/hardcoded-secret.nix
+    (
+      { config, ... }:
+      {
+        contracts.fileSecrets.defaultProvider = config.contracts.fileSecrets.providers.hardcoded-secret;
+        testing.hardcoded-secret.fileSecrets."mysecret".content = config.test.content;
+      }
+    )
+  ];
+}
diff --git a/nixos/tests/contracts/filesecrets/test.nix b/nixos/tests/contracts/filesecrets/test.nix
new file mode 100644
index 0000000000000..00d2bdf251df8
--- /dev/null
+++ b/nixos/tests/contracts/filesecrets/test.nix
@@ -0,0 +1,89 @@
+{
+  lib,
+  config,
+  pkgs,
+  ...
+}:
+let
+  inherit (lib) getAttrFromPath setAttrByPath;
+  inherit (lib) mkOption types;
+in
+{
+  name,
+  providerRoot,
+  extraModules ? [ ],
+}:
+{
+  name = "contracts_filesecrets_${name}";
+
+  nodes.machine =
+    { config, ... }:
+    {
+      imports = extraModules;
+
+      options.test = {
+        owner = mkOption {
+          type = types.str;
+          default = "root";
+        };
+
+        group = mkOption {
+          type = types.str;
+          default = "root";
+        };
+
+        mode = mkOption {
+          type = types.str;
+          default = "0400";
+        };
+
+        content = mkOption {
+          type = types.str;
+          default = "a super secret secret!";
+        };
+      };
+
+      config = lib.mkMerge [
+        (setAttrByPath providerRoot {
+          input = {
+            inherit (config.test) owner group mode;
+          };
+        })
+        (lib.mkIf (config.test.owner != "root") {
+          users.users.${config.test.owner}.isNormalUser = true;
+        })
+        (lib.mkIf (config.test.group != "root") {
+          users.groups.${config.test.group} = { };
+        })
+      ];
+    };
+
+  testScript =
+    { nodes, ... }:
+    let
+      cfg = nodes.machine;
+      inherit (getAttrFromPath providerRoot nodes.machine) output;
+    in
+    ''
+      owner = machine.succeed("stat -c '%U' ${output.path}").strip()
+      print(f"Got owner {owner}")
+      if owner != "${cfg.test.owner}":
+          raise Exception(f"Owner should be '${cfg.test.owner}' but got '{owner}'")
+
+      group = machine.succeed("stat -c '%G' ${output.path}").strip()
+      print(f"Got group {group}")
+      if group != "${cfg.test.group}":
+          raise Exception(f"Group should be '${cfg.test.group}' but got '{group}'")
+
+      mode = str(int(machine.succeed("stat -c '%a' ${output.path}").strip()))
+      print(f"Got mode {mode}")
+      wantedMode = str(int("${cfg.test.mode}"))
+      if mode != wantedMode:
+          raise Exception(f"Mode should be '{wantedMode}' but got '{mode}'")
+
+      content = machine.succeed("cat ${output.path}").strip()
+      print(f"Got content {content}")
+      if content != "${cfg.test.content}":
+          raise Exception(f"Content should be '${cfg.test.content}' but got '{content}'")
+    '';
+}
diff --git a/nixos/tests/stash.nix b/nixos/tests/stash.nix
index 838a5e8a43c6d..364ae5803c2f5 100644
--- a/nixos/tests/stash.nix
+++ b/nixos/tests/stash.nix
@@ -9,61 +9,66 @@ import ./make-test-python.nix (
     name = "stash";
     meta.maintainers = pkgs.stash.meta.maintainers;
 
-    nodes.machine = {
-      services.stash = {
-        inherit dataDir;
-        enable = true;
+    nodes.machine =
+      { config, ... }:
+      {
+        services.stash = {
+          inherit dataDir;
+          enable = true;
 
-        username = "test";
-        passwordFile = pkgs.writeText "stash-password" "MyPassword";
+          username = "test";
 
-        jwtSecretKeyFile = pkgs.writeText "jwt_secret_key" "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
-        sessionStoreKeyFile = pkgs.writeText "session_store_key" "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+          plugins =
+            let
+              src = pkgs.fetchFromGitHub {
+                owner = "stashapp";
+                repo = "CommunityScripts";
+                rev = "9b6fac4934c2fac2ef0859ea68ebee5111fc5be5";
+                hash = "sha256-PO3J15vaA7SD4r/LyHlXjnpaeYAN9Q++O94bIWdz7OA=";
+              };
+            in
+            [
+              (pkgs.runCommand "stashNotes" { inherit src; } ''
+                mkdir -p $out/plugins
+                cp -r $src/plugins/stashNotes $out/plugins/stashNotes
+              '')
+              (pkgs.runCommand "Theme-Plex" { inherit src; } ''
+                mkdir -p $out/plugins
+                cp -r $src/themes/Theme-Plex $out/plugins/Theme-Plex
+              '')
+            ];
 
-        plugins =
-          let
-            src = pkgs.fetchFromGitHub {
-              owner = "stashapp";
-              repo = "CommunityScripts";
-              rev = "9b6fac4934c2fac2ef0859ea68ebee5111fc5be5";
-              hash = "sha256-PO3J15vaA7SD4r/LyHlXjnpaeYAN9Q++O94bIWdz7OA=";
-            };
-          in
-          [
-            (pkgs.runCommand "stashNotes" { inherit src; } ''
-              mkdir -p $out/plugins
-              cp -r $src/plugins/stashNotes $out/plugins/stashNotes
-            '')
-            (pkgs.runCommand "Theme-Plex" { inherit src; } ''
-              mkdir -p $out/plugins
-              cp -r $src/themes/Theme-Plex $out/plugins/Theme-Plex
-            '')
-          ];
+          mutableScrapers = true;
+          scrapers =
+            let
+              src = pkgs.fetchFromGitHub {
+                owner = "stashapp";
+                repo = "CommunityScrapers";
+                rev = "2ece82d17ddb0952c16842b0775274bcda598d81";
+                hash = "sha256-AEmnvM8Nikhue9LNF9dkbleYgabCvjKHtzFpMse4otM=";
+              };
+            in
+            [
+              (pkgs.runCommand "FTV" { inherit src; } ''
+                mkdir -p $out/scrapers/FTV
+                cp -r $src/scrapers/FTV.yml $out/scrapers/FTV
+              '')
+            ];
 
-        mutableScrapers = true;
-        scrapers =
-          let
-            src = pkgs.fetchFromGitHub {
-              owner = "stashapp";
-              repo = "CommunityScrapers";
-              rev = "2ece82d17ddb0952c16842b0775274bcda598d81";
-              hash = "sha256-AEmnvM8Nikhue9LNF9dkbleYgabCvjKHtzFpMse4otM=";
-            };
-          in
-          [
-            (pkgs.runCommand "FTV" { inherit src; } ''
-              mkdir -p $out/scrapers/FTV
-              cp -r $src/scrapers/FTV.yml $out/scrapers/FTV
-            '')
-          ];
+          settings = {
+            inherit host port;
 
-        settings = {
-          inherit host port;
-
-          stash = [ { path = "/srv"; } ];
+            stash = [ { path = "/srv"; } ];
+          };
+          passwordFile.result = config.contracts.fileSecrets.results.stash.passwordFile;
+        };
+        contracts.fileSecrets.defaultProvider = config.contracts.fileSecrets.providers.hardcoded-secret;
+        testing.hardcoded-secret.fileSecrets.stash = {
+          passwordFile.content = "MyPassword";
+          jwtSecretKey.content = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+          sessionStoreKey.content = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
         };
       };
-    };
 
     testScript = ''
       machine.wait_for_unit("stash.service")