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.
Content stays where it was written
Section titled “Content stays where it was written”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.defaultis 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 writesnixoslands 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.
Where a policy applies
Section titled “Where a policy applies”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.
Crossing up: name the receiver
Section titled “Crossing up: name the receiver”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.
policy.provide: a module for the host
Section titled “policy.provide: a module for the host”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.
How the receiver is found
Section titled “How the receiver is found”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 ancestorsA 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.
Scopes without their own entity
Section titled “Scopes without their own entity”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.
Guests that rebind host
Section titled “Guests that rebind 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.
mutual-provider and user-aspects
Section titled “mutual-provider and user-aspects”Two batteries deliver a user’s host-class content to its hosts. They differ in what they carry and in who chooses.
den.batteries.mutual-provider
Section titled “den.batteries.mutual-provider”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 hostden.schema.host.excludes = [ den.batteries.mutual-provider ]; # every hostOnce 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];den.batteries.user-aspects
Section titled “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 iglooden.aspects.igloo.includes = [ (den.batteries.user-aspects { users = [ "tux" ]; }) ]; # only tuxden.schema.host.includes = [ den.batteries.user-aspects ]; # every host, every userWith { 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.
Which one
Section titled “Which one”| Situation | Use |
|---|---|
| A user aspect states what it adds to hosts | mutual-provider on the host, with provides.to-hosts / provides.<host> |
The host trusts its users’ nixos / darwin / os as written | user-aspects on the host |
| Only some users may change the host | user-aspects { users = [ … ]; } |
| A fleet wants the old behaviour everywhere while migrating | den.schema.host.includes = [ den.batteries.user-aspects ] |
| The setting is about the user’s own account | the user class, no battery |
| One policy computes a setting per user | policy.provide { receiver = host; }, no battery |
A host must not take to-hosts content | exclude 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.
The transition defaults
Section titled “The transition defaults”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.
Adopting the end state
Section titled “Adopting the end state”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.
A migration that works both ways
Section titled “A migration that works both ways”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.
When the host needs it
Section titled “When the host needs it”- Include
den.batteries.user-aspectson the host, optionally with{ users = [ … ]; }. This keeps the content as written and makes the host’s acceptance explicit. - Use
provides.to-hostsorprovides.<host>, withden.batteries.mutual-providerincluded on the host. - Move account settings to the
userclass.nixos.users.users.tux.*on tux becomesuser.*:den.aspects.tux.user.extraGroups = [ "wheel" ]; - Deliver host-wide settings with
policy.provide { receiver = host; }(above), or move them to the host’s own aspect (den.aspects.igloo).
A user’s policies.to-hosts
Section titled “A user’s policies.to-hosts”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.
Known limits
Section titled “Known limits”- A
policy.excludefrom a policy another policy delivers removes nothing. The exclude effect of a policy that is itself delivered by another policy’sincludeis 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’sincludes. 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) ]))];isolated is deprecated
Section titled “isolated is deprecated”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.
See also
Section titled “See also”- Where Does My Config Land?: scope rules for each class
- Choosing a Mechanism
- Policies and the policy effects reference
- Host↔User Mutual Config
- Batteries reference