Skip to content

Crossing Scopes

Every entity resolves in its own scope: one for the host igloo, one for each user on it (tux, pingu), one for each guest or VM a policy resolves under it. This page covers how content and context move between those scopes.

There are two directions:

  • Content goes up only through a delivery that names its receiver.
  • Context goes down through policy.resolve. Child scopes see what their ancestors published.

An entity’s class content belongs to that entity. A user that sits on a host does not give the host its nixos, darwin or os content just by sitting there.

den.hosts.x86_64-linux.igloo.users.tux.classes = [ "homeManager" ];
den.aspects.tux = {
homeManager.programs.git.enable = true; # tux's home
user.extraGroups = [ "wheel" ]; # users.users.tux on igloo
nixos.services.openssh.enable = true; # stays in tux, does not reach igloo
};

The homeManager and user lines reach their targets because den’s own channels deliver them. The nixos line has no delivery. It stays in tux’s scope. While the transition defaults are on, one of them still carries it to the host, with a warning.

The same holds for anything tux includes and for a parametric den.aspects.tux = { user, ... }: { nixos = …; }. Those run in tux’s scope.

Three things do not change:

  • Content written on the host (den.aspects.igloo, its includes, den.schema.host.includes) lands on the host.
  • den.default is every entity’s include, so it is also the host’s. A { host, ... } function there fires in every user scope too, and its content lands on the host once, from the host scope. A { host, user, ... } function there that writes nixos lands on the host as well: the host registered it, and a policy applies to the entity it is registered on, below.
  • A policy registered on the host applies to the host, wherever it fires.

A policy applies to the entity it is registered on, its registrant: the host for den.aspects.igloo.includes or den.schema.host.includes, the user for den.aspects.tux.includes. Fired at a user below its host, a host’s { host, user, ... } policy still puts its host-class part on the host and the rest on the user.

The registrant is matched by the binding, not by tree position. A policy registered at an entity applies wherever a scope binds that entity for its kind, by id_hash, or by value for a record without one. So a policy registered on an environment reaches a guest that binds environment = dev even though the guest sits under a prod host, and a guest that rebinds environment to another one stops getting the first environment’s policies. One entity resolved at two places (igloo under dev and under prod) is two placements: a policy registered at one applies only there.

To move content from a scope to an ancestor, a delivery names the entity that receives it: receiver = host. Three delivery forms take receiver: den.lib.policy.provide, den.lib.policy.route and den.batteries.forward. Without receiver a delivery stays in its source scope.

Each user adds a message to igloo’s /etc. The policy fires once per user scope, and each user’s module lands on the host.

den.policies.user-motd =
{ host, user, ... }:
[
(den.lib.policy.provide {
class = host.class;
module.environment.etc."motd.d/${user.userName}".text = "Hello, ${user.userName}";
receiver = host;
})
];
den.schema.user.includes = [ den.policies.user-motd ];

igloo.environment.etc."motd.d/tux".text is "Hello, tux". Two users get two separate entries. A provide from one policy at several user scopes is kept once per user, not once in total.

policy.route: a class that lands on the host

Section titled “policy.route: a class that lands on the host”

A custom firewall class lets a user say which ports it needs. A route moves the user’s firewall content into the host’s networking.firewall. This is the same shape den’s own user class uses.

den.classes.firewall.description = "Firewall ports a user needs on its host";
den.policies.firewall-to-host =
{
host,
user,
home ? null,
...
}:
lib.optional (host ? class && home == null) (
den.lib.policy.route {
fromClass = "firewall";
intoClass = host.class;
path = [ "networking" "firewall" ];
receiver = host;
}
);
den.schema.user.includes = [ den.policies.firewall-to-host ];
den.aspects.tux.firewall.allowedTCPPorts = [ 8080 ];

The guard host ? class && home == null keeps the route inert for a standalone home. A standalone home binds a host that is not its ancestor, so receiver = host would fail there (see below). Den’s own batteries carry the same guard.

den.batteries.forward: the same class, as a forward

Section titled “den.batteries.forward: the same class, as a forward”

forward takes receiver as one of its arguments. This forward moves a user’s account class into users.users.<name> on the host:

den.classes.account.description = "Settings for the user's account on its host";
den.schema.user.includes = [
(
{ host, user }:
den.batteries.forward {
each = [ user ];
fromClass = _: "account";
intoClass = _: host.class;
intoPath = u: [ "users" "users" u.userName ];
receiver = host;
}
)
];
den.aspects.tux.account.description = "Tux";

igloo.users.users.tux.description is "Tux". Den’s Home Manager, hjem and maid integrations are forwards of this kind, each with receiver = host.

receiver is an entity record: host, user, or any record your schema declares. Den looks for that record on the source scope’s chain of ancestors, starting at the source itself. The first scope whose own entity is that record receives the delivery.

A record is matched by its identity, not by its name or kind. A copy of a record made with // keeps the original’s identity, so it delivers to the original’s scope.

A receiver that is not on the chain is an error. A user on igloo cannot deliver to iceberg:

receiver = config.den.hosts.x86_64-linux.iceberg;
den: delivery receiver 'iceberg' is not an entity on the chain of scope '…' —
`receiver` must name the source entity or one of its ancestors

A value without an identity (not an entity record) is also an error. To reach an entity that is not an ancestor, deliver from a scope that has it as an ancestor, or let a pipe carry data across.

Some scopes bind host without being a host. The microvm template resolves a microvm-guest scope under each host, and binds host to the real host there. That scope has no entity of its own, so the search passes over it. A receiver = host delivery from a microvm guest lands on the real host.

A guest kind can bind host to the guest itself, so that host batteries and policies treat the guest as a host. Inside that scope, host is the guest, and receiver = host delivers into the guest, not into its parent.

The guest’s delivery must name the parent record. Capture it in the policy that resolves the guest, where host is still the parent:

den.schema.guest = {
isEntity = true;
parent = "host";
};
deliverGuest =
parent:
den.lib.policy.mkPolicy "deliver-guest" (
{ ... }@args:
lib.optionals (!(args ? user) && !(args ? home)) [
(den.lib.policy.route {
fromClass = "nixos";
intoClass = "nixos";
collectSubtree = true;
reinstantiate = true;
path = [ "microvm" "vms" "cuda" "config" ];
receiver = parent; # igloo, not the guest
})
]
);
den.policies.resolve-guests =
{ host, ... }:
lib.optionals (host.name == "igloo") [
(den.lib.policy.resolve.to.withIncludes "guest" [ (deliverGuest host) ] {
guest = cuda;
host = cuda;
})
];
den.schema.host.includes = [ den.policies.resolve-guests ];

Here cuda is the guest’s record. The guest’s nixos lands at igloo.microvm.vms.cuda.config, and none of it reaches igloo’s own config. Users inside the guest see host = cuda, so their user class and Home Manager config reach the guest, and the guest’s delivery carries them on to igloo’s microvm.vms.cuda.

Crossing down: context through policy.resolve

Section titled “Crossing down: context through policy.resolve”

Context flows the other way. policy.resolve with keys that are not entity kinds adds those keys to the current scope’s context. Every child scope sees them too.

den.policies.office-site =
{ host, ... }:
lib.optional (host.name == "igloo") (den.lib.policy.resolve { site = "office"; });
den.schema.host.includes = [ den.policies.office-site ];
den.aspects.tux.includes = [
({ site, ... }: { homeManager.home.sessionVariables.SITE = site; })
];

tux on igloo gets SITE=office. An aspect that takes site only runs where site is bound, so tux on a host without the policy skips it. This publishes data, not modules. It moves no class content. See Enrichment vs entity resolution.

The two batteries below use this. Each is a host-side policy that publishes “this host accepts its users’ content” as context. mutual-provider’s delivery, at each user scope, reads it and delivers with receiver = host if the user’s own host published it. For user-aspects, den reads it when it assembles the host: an accepted user’s scope is not a boundary, so its content merges into the host as before. The published value is tied to the host’s identity. A guest nested under an accepting host inherits the context, but its users see host = guest, which did not publish it, so nothing is delivered into a guest that did not opt in.

Two batteries deliver a user’s host-class content to its hosts. They differ in what they carry and in who chooses.

Delivers what a user explicitly provides to its hosts: provides.to-hosts (every host the user is on) and provides.<host> (one host).

den.aspects.tux.provides.to-hosts.nixos.services.openssh.enable = true;
den.aspects.tux.provides.igloo.nixos.programs.emacs.enable = true;

Only the host-class part (nixos on igloo) crosses to the host. Other classes in the provided aspect, such as homeManager, stay with the user and reach the user’s home as before. Host to user (provides.to-users, provides.<user>) needs no battery.

Include it on the hosts that should receive what their users provide:

den.schema.host.includes = [ den.batteries.mutual-provider ];

While the transition defaults are on, it is also on by default. To opt out on one host or on every host, exclude it; the exclude covers its default too:

den.aspects.igloo.excludes = [ den.batteries.mutual-provider ]; # one host
den.schema.host.excludes = [ den.batteries.mutual-provider ]; # every host

Once the transition defaults are off (acknowledged, or after they are removed), an excluded host no longer receives to-hosts content. While they are on, user-aspects’ default form still lifts the user’s whole host-class output, to-hosts content included, so excluding mutual-provider alone leaves it arriving. Exclude both to stop it during the transition:

den.aspects.igloo.excludes = [
den.batteries.mutual-provider
den.batteries.user-aspects
];

Lets a host accept everything its users produce for it, as before #694. While the transition defaults are on, it is on by default; include it explicitly to keep it. It carries their own nixos, darwin and os, what they include, custom classes they route or forward into the host’s class, what their policies provide in their own scope, and a host-rooted den.lib.aspects.resolve. It is opt-in and declared on the host side only. A user excluded by den.schema.user.isolated stays isolated.

den.aspects.igloo.includes = [ den.batteries.user-aspects ]; # every user on igloo
den.aspects.igloo.includes = [ (den.batteries.user-aspects { users = [ "tux" ]; }) ]; # only tux
den.schema.host.includes = [ den.batteries.user-aspects ]; # every host, every user

With { users = [ "tux" ]; }, pingu’s host-class content is not accepted. Including the battery twice, or with the same list twice, accepts once. Including it on a user (den.aspects.tux.includes) or in den.schema.user.includes does nothing: a user cannot opt itself into a host.

SituationUse
A user aspect states what it adds to hostsmutual-provider on the host, with provides.to-hosts / provides.<host>
The host trusts its users’ nixos / darwin / os as writtenuser-aspects on the host
Only some users may change the hostuser-aspects { users = [ … ]; }
A fleet wants the old behaviour everywhere while migratingden.schema.host.includes = [ den.batteries.user-aspects ]
The setting is about the user’s own accountthe user class, no battery
One policy computes a setting per userpolicy.provide { receiver = host; }, no battery
A host must not take to-hosts contentexclude mutual-provider on that host

The two are independent. With mutual-provider excluded and user-aspects included, a user’s to-hosts content still arrives through user-aspects.

Content an aspect placed on a user writes to its host’s class (nixos, darwin, os) stays with the user. That is by design: an aspect can carry host-class content for when it is placed on a host, and a home part for when it is placed on a user.

To give configs time to move, den keeps two transition defaults on every host (and on any nested kind with its own class, such as a guest): den.batteries.user-aspects and den.batteries.mutual-provider, each through a default form of its own. With them a config behaves as before #694. They stay on until you acknowledge the migration (below), or until a den release planned for 2027-01-01 removes them. The date names that release; nothing in den reads the clock, so updating den is what changes behaviour. A host warns once, listing the host-class content that reaches it only through a default:

den: igloo receives nixos content only through den's transition default, which ends 2027-01-01:
- from tux (steam)
- from tux (tux/to-hosts)
If the host should have it, include the aspect on the host or add the battery explicitly: `den.schema.host.includes = [ den.batteries.user-aspects ];` for a user's own content, `den.schema.host.includes = [ den.batteries.mutual-provider ];` for `provides.to-hosts`. If it's meant to stay with the user, set `den.migrations.user-host-content.acknowledged = true;` to adopt the new behaviour now. See https://github.com/denful/den/issues/694.

Each entry names the nested entity (usually a user) and the aspect that wrote the content. The warning covers the host’s class only: content in another class, such as a custom class a host route collects, changes without an entry when the defaults go. Content a host also receives another way, such as a { host, ... } function in den.default that runs at the host scope too, is not listed. Neither is the content of a nested entity with its own class, such as a guest that is its own host.

When every entry is meant to stay with the user, or the host now receives what it needs another way, set the migration flag once:

den.migrations.user-host-content.acknowledged = true;

It turns both transition defaults off. Batteries included explicitly still apply, and the warning stops. The release that removes the defaults also removes the warning and the flag; setting the flag after that release is an error that asks you to remove it.

Include the batteries the host should keep, explicitly. That gives the same result with the defaults on and after acknowledging, and the host gives no warning for that content:

den.schema.host.includes = [
den.batteries.user-aspects
den.batteries.mutual-provider
];
den.aspects.tux = {
nixos.boot.kernelModules = [ "own" ];
provides.to-hosts.nixos.boot.kernelModules = [ "provided" ];
};

Both modules reach igloo either way. Then set the acknowledgement; nothing changes for that content.

  1. Include den.batteries.user-aspects on the host, optionally with { users = [ … ]; }. This keeps the content as written and makes the host’s acceptance explicit.
  2. Use provides.to-hosts or provides.<host>, with den.batteries.mutual-provider included on the host.
  3. Move account settings to the user class. nixos.users.users.tux.* on tux becomes user.*:
    den.aspects.tux.user.extraGroups = [ "wheel" ];
  4. Deliver host-wide settings with policy.provide { receiver = host; } (above), or move them to the host’s own aspect (den.aspects.igloo).

A common older pattern is a user policy that includes host content from the user’s scope:

den.aspects.tux.policies.to-hosts =
{ host, user, ... }:
[ (den.lib.policy.include { nixos.services.openssh.enable = true; }) ];
den.aspects.tux.includes = [ den.aspects.tux.policies.to-hosts ];

policy.include adds the aspect to the scope the policy fires in, which is tux’s. Its nixos stays with tux. Write it as a provide instead, which mutual-provider delivers when the host includes it:

den.aspects.tux.provides.to-hosts.nixos.services.openssh.enable = true;

Or include den.batteries.user-aspects on the host.

  • A policy.exclude from a policy another policy delivers removes nothing. The exclude effect of a policy that is itself delivered by another policy’s include is registered when that policy dispatches, after the includes it names were gated, so it takes effect too late. It is the same on releases before #694. Write the exclude on the aspect that includes what it removes (excludes = [ … ]), or return it from a policy listed directly in that aspect’s includes. A later den release fixes it.
# Removes nothing: `ex` is delivered by `outer`'s include.
den.aspects.igloo.includes = [
den.aspects.plain
(den.lib.policy.mkPolicy "outer" ({ host, ... }: [
(den.lib.policy.include
(den.lib.policy.mkPolicy "ex" ({ host, ... }: [ (den.lib.policy.exclude den.aspects.plain) ])))
]))
];
# Either of these removes it.
den.aspects.igloo.excludes = [ den.aspects.plain ];
den.aspects.igloo.includes = [
den.aspects.plain
(den.lib.policy.mkPolicy "ex" ({ host, ... }: [ (den.lib.policy.exclude den.aspects.plain) ]))
];

den.schema.<kind>.isolated = true is deprecated, and den warns when a kind sets it. Every entity already keeps its content to itself, so the flag adds nothing for entity scopes. What it still does:

  • It keeps the kind’s content out of its ancestors, also for a scope of that kind that has no entity of its own.
  • It never blocks a delivery that names its receiver. Those still cross.
  • Content of an isolated kind that no delivery carries stays with that kind, without a transition-default warning, as before.
ContributeCommunitySponsor