denful · sini · Jun 15, 2026 · May 20, 2026 · May 21, 2026 · May 21, 2026
diff --git a/docs/src/content/docs/explanation/parametric.mdx b/docs/src/content/docs/explanation/parametric.mdx
@@ -46,6 +46,35 @@ den.aspects.firewall = {
 };
 ```
 
+## The binding rule
+
+When a parametric aspect at some scope **S** destructures an **entity-kind** arg
+(`host`, `user`, `home`, …), exactly one of three things happens:
+
+1. **In-context → bind once at S.** If the kind is already in S's context (e.g.
+   a `{ user, … }` aspect included at a user scope), the arg binds and the aspect
+   emits once, at S.
+2. **Schema-DAG descendant → fan out, emit at S.** If the kind is a *descendant*
+   of S in the entity schema (e.g. a `{ user, … }` aspect included at the **host**
+   scope — users live under hosts), the aspect fans out once per matching
+   descendant, each emitting **class-locally at S**. This is how a host-scope
+   `{ user, … }` aspect produces per-user content on the host.
+3. **Neither → inert, silently.** If the kind is neither in-context nor a
+   descendant of S — including a misplaced arg, or **any entity-kind arg at the
+   root/flake scope** — the aspect contributes nothing. There is **no warning**
+   (a warning was considered and deliberately rejected: legitimate fan-out and
+   misplacement are indistinguishable without whole-fleet context, so a warning
+   would fire on correct code).
+
+<Aside type="caution" title="The silent-inert footgun">
+Because case 3 is silent, a parametric aspect that destructures an entity kind
+**not reachable from where it is included** simply does nothing — no error, no
+warning. If a parametric aspect "isn't applying," check that the arg's kind is
+in-context or a schema descendant of the include scope. Cross-entity delivery
+(e.g. a host wanting to configure a *sibling* host) is **not** expressible this
+way — use `provides` or a policy.
+</Aside>
+
 ## Where Parametric Args Work
 
 <Aside type="tip" title="Aspect level only">

diff --git a/docs/src/content/docs/guides/debug.md b/docs/src/content/docs/guides/debug.md
@@ -131,12 +131,14 @@ nix-repl> cfg.networking.hostName
 from `den.default`, but parametric functions in `den.default.includes`
 run at every context stage. The pipeline handles dispatch automatically
 based on function argument shape — write a bare function with the context
-args you need. (`den.lib.perHost` is deprecated.)
+args you need. The `den.lib.perHost`, `perUser`, and `perHome` shims still
+exist but are deprecated (they warn and forward to the current binding rule);
+prefer plain parametric aspects:
 
 ```nix
-# Deprecated: den.lib.perHost ({ host }: { nixos.x = 1; })
-# Modern — bare function; only runs in host contexts:
-({ host }: { nixos.x = 1; })
+# Deprecated (warns): den.lib.perHost, den.lib.perUser, den.lib.perHome
+# Preferred — plain parametric aspect; binds host at its scope / fans out:
+({ host, ... }: { nixos.x = 1; })
 ```
 
 **Missing attribute**: The context does not have the expected parameter.

diff --git a/docs/src/content/docs/guides/home-manager.mdx b/docs/src/content/docs/guides/home-manager.mdx
@@ -236,3 +236,16 @@ den.hosts.x86_64-linux.laptop = {
 
 Both `homeManager` and `hjem` configurations from `den.aspects.alice` will
 be forwarded to their respective targets.
+
+## Host-scope parametric aspects no longer deliver homeManager content to users
+
+Earlier releases let a `{ user, ... }` aspect at host scope leak its
+`homeManager` content to each of the host's users. A host-scope parametric
+aspect now fans out over the users but emits class-locally **on the host**,
+where `homeManager` is inert -- so that content never reaches the users'
+Home Manager evaluation. This matches the resolver's emission rule: the bound
+user is the arg source, not the output target.
+
+If you were relying on that leak to push home content from a host-scope aspect,
+route it through an explicit `to-users` policy, `provides`, or the host-aspects
+battery instead.
diff --git a/docs/src/content/docs/reference/lib-deprecated.mdx b/docs/src/content/docs/reference/lib-deprecated.mdx
@@ -105,22 +105,32 @@ helper (does not warn).
 
 ## Context shortcuts
 
-Run an aspect only at a specific context level. Each returns a parametric wrapper
-(declaring deeper context keys as optional) that yields `{}` when resolved at a
-deeper level, and warns. Prefer a plain function with the level's keys, e.g.
-`({ host, user, ... }: { ... })`.
+Wrap an aspect so it requires a specific set of context keys. Each returns a
+parametric wrapper and **warns**. They are now thin aliases for a plain function
+with the same keys — i.e. `den.lib.perHost f` behaves as `({ host, ... }: f { … })`:
+the arg binds once at the emitting scope if in-ctx, fans out class-locally over
+that scope's descendants otherwise, and is inert if misplaced. Prefer the plain
+function form, e.g. `({ host, user, ... }: { ... })`.
+
+<Aside type="caution" title="Semantics changed">
+Earlier releases made these wrappers *self-suppress* — yield `{}` when resolved
+at a deeper context level. That was the cross-scope-deferral behavior fixed in
+the binding-half rewrite (see [Parametric Aspects](/explanation/parametric/)).
+The shims no longer self-suppress; they deliver the current binding rule. A
+config that relied on the old silent `{}` will now see the wrapped aspect bind.
+</Aside>
 
 ### `den.lib.perHost aspect`
 
-Run `aspect` only in `{ host }` contexts.
+Wrap `aspect` to require `{ host }`.
 
 ### `den.lib.perUser aspect`
 
-Run `aspect` only in `{ host, user }` contexts.
+Wrap `aspect` to require `{ host, user }`.
 
 ### `den.lib.perHome aspect`
 
-Run `aspect` only in `{ home }` contexts.
+Wrap `aspect` to require `{ home }`.
 
 ## `den.lib.resolveStage`
 

diff --git a/docs/src/content/docs/reference/policies.mdx b/docs/src/content/docs/reference/policies.mdx
@@ -66,9 +66,47 @@ Remove an aspect via the constraint registry:
 policy.exclude den.aspects.unwanted
 ```
 
+### `policy.deliver spec`
+
+The user-facing **delivery primitive**: declare one delivery edge from a source
+into a target class at a path, with an explicit mode. `route` and `provide`
+(below) are sugar shims over `deliver`.
+
+```nix
+# Class source — move a class's collected content (the `route` case):
+policy.deliver {
+  from = "myClass";              # class name → collect that class's bucket
+  to = "nixos";                  # target class
+  at = [ "services" "myService" ]; # attrpath ([] = merge at the class root)
+  mode = "nest";                 # "merge" | "nest" | "verbatim"
+}
+
+# Module source — inject a NEW module (the `provide` case):
+policy.deliver {
+  from = { module = { pkgs, ... }: { ... }; };
+  to = "nixos";
+}
+```
+
+`mode` is exhaustive and explicit:
+
+- `merge` (default) — union into the target class bucket (use with `at = []`).
+- `nest` — evaluate and place the source at `at`.
+- `verbatim` — place the collected module wrappers _by reference_ so a target
+  whose option `merge` re-instantiates them (e.g. a microvm guest config) sees
+  the live modules together with its base modules. There is **no
+  `reinstantiate` flag** — verbatim is requested by `mode` directly. `verbatim`
+  applies only to class sources, not module sources.
+
+`deliver` deliberately does **not** expose `appendToParent` (parent-targeting is
+constructor-internal) — use a class source whose `to` already names the target.
+
 ### `policy.route spec`
 
-Route class or quirk content from one scope partition into a target class:
+Route class or quirk content from one scope partition into a target class. A
+permanent sugar shim over [`policy.deliver`](#policydeliver-spec) —
+`fromClass`→`from`, `intoClass`→`to`, `path`→`at`, and `reinstantiate = true`→
+`mode = "verbatim"`:
 
 ```nix
 policy.route {
@@ -80,7 +118,10 @@ policy.route {
 
 ### `policy.provide spec`
 
-Deliver a module directly to a target class, bypassing the aspect tree:
+Deliver a module directly to a target class, bypassing the aspect tree. A
+permanent sugar shim over [`policy.deliver`](#policydeliver-spec) with a module
+source (`class`→`to`, `module`→`from.module`, `path`→`at`; `mode` is derived
+from `path` — `merge` at the root, `nest` under a non-empty `path`):
 
 ```nix
 policy.provide { class = "nixos"; module = { pkgs, ... }: { ... }; }

@@ -8,6 +8,45 @@ let
 
   entityModule =
     { config, ... }:
+    let
+      # Prefer `classes` (list), fall back to `[class]`, else error.
+      classes =
+        config.classes or (
+          if config ? class then
+            [ config.class ]
+          else
+            throw "den.schema.conf.hasAspect: entity has no `class` or `classes`"
+        );
+      primaryClass =
+        if classes == [ ] then
+          throw "den.schema.conf.hasAspect: entity has empty `classes` list"
+        else
+          lib.head classes;
+      # Lazy thunk throwing at call time (not attribute access), so the
+      # accessors can be referenced safely by tooling and only fire when
+      # actually invoked.
+      err = throw (
+        "hasAspect: ${config.name or "<unnamed entity>"} has no config.resolved "
+        + "(no matching den.schema.<kind> defined)."
+      );
+      # Shared record: `hasAspect` (functor) and `aspects` (node list) are both
+      # read off `info`, so the per-class fxFullResolve runs once and is reused.
+      info =
+        if config ? resolved then
+          den.lib.aspects.mkEntityHasAspect {
+            tree = config.resolved;
+            inherit primaryClass classes;
+          }
+        else
+          {
+            __functor = _: _: err;
+            forClass = _: _: err;
+            forAnyClass = _: err;
+            aspects = err;
+            aspectsForClass = _: err;
+            allAspects = err;
+          };
+    in
     {
       options.hasAspect = lib.mkOption {
         description = ''
@@ -30,40 +69,32 @@ let
         readOnly = true;
         type = lib.types.raw;
         defaultText = lib.literalMD "Computed from `config.resolved` and the entity's class/classes.";
-        default =
-          let
-            # Prefer `classes` (list), fall back to `[class]`, else error.
-            classes =
-              config.classes or (
-                if config ? class then
-                  [ config.class ]
-                else
-                  throw "den.schema.conf.hasAspect: entity has no `class` or `classes`"
-              );
-            primaryClass =
-              if classes == [ ] then
-                throw "den.schema.conf.hasAspect: entity has empty `classes` list"
-              else
-                lib.head classes;
-            # Lazy thunk throwing at call time (not attribute access), so
-            # entity.hasAspect / .forClass / .forAnyClass can be referenced
-            # safely by tooling and only fire when actually invoked.
-            err = throw (
-              "hasAspect: ${config.name or "<unnamed entity>"} has no config.resolved "
-              + "(no matching den.schema.<kind> defined)."
-            );
-          in
-          if config ? resolved then
-            den.lib.aspects.mkEntityHasAspect {
-              tree = config.resolved;
-              inherit primaryClass classes;
-            }
-          else
-            {
-              __functor = _: _: err;
-              forClass = _: _: err;
-              forAnyClass = _: err;
-            };
+        default = info;
+      };
+
+      options.aspects = lib.mkOption {
+        description = ''
+          The flat list of all resolved aspect nodes on this entity (every
+          depth), each the resolved node augmented with:
+            .identity     # base FQN, ctx-stripped — e.g. "roles/workstation"
+            .identityKey  # full unique key incl {ctxId} (distinguishes anons)
+            .isNamed      # false for anonymous aspects
+
+          Each node also retains its `.name`, `.meta`, and `.includes` (its
+          resolved subtree), so callers can inspect, navigate, and re-include
+          it. Excludes the entity root and excluded/tombstoned aspects;
+          anonymous aspects are included.
+
+          Same cyclic caveat as `hasAspect`: do not use to decide an aspect's
+          own `includes`. Reading it post-resolution (module bodies, batteries)
+          is safe.
+        '';
+        internal = true;
+        visible = false;
+        readOnly = true;
+        type = lib.types.raw;
+        defaultText = lib.literalMD "Computed from `config.resolved` and the entity's primary class.";
+        default = info.aspects;
       };
     };
 in

@@ -1,45 +1,41 @@
-# DEPRECATED: scheduled for removal after first stable release post-fx-pipeline merge.
-# Migration: use den.schema.host / den.schema.user directly.
-# Deprecated context-level guards.
-# Under handler-based resolution, bind.fn resolves each arg independently.
-# Optional args with no handler are skipped (nix-effects c7931d7), so
-# the function body can detect context level by checking which keys
-# were resolved.
+# DEPRECATED context guards — kept as a thin compatibility shim.
+#
+# `den.lib.perHost` / `perUser` / `perHome` shipped in earlier releases. They
+# are RESTORED here as aliases over the current binding rule so existing configs
+# keep evaluating (and get a deprecation warning steering them to plain
+# functions). Migration: use a plain function — `({ host, ... }: { ... })`.
+#
+# IMPORTANT — semantics changed (this is the #609 fix): the old shim returned
+# `{}` whenever a deeper context key was present (a self-suppressing emulation
+# of cross-scope deferral). That behavior was the bug the binding-half rewrite
+# removed. The restored shim drops the self-suppression: an entity-kind arg now
+# binds once at the emitting scope if in-ctx, fans out class-locally over the
+# scope's descendants otherwise, and is inert if misplaced — exactly as a plain
+# `{ host, ... }:` function does. So `den.lib.perHost f` is now an alias for
+# `{ host, ... }: f { inherit host; }`, not the old suppress-at-deeper-scope
+# guard. Configs relying on the old silent suppression were relying on #609.
 { lib, ... }:
 let
-  # Known context keys. Keys not in the required set are declared as
-  # optional — if their handlers exist (deeper level), the function
-  # detects the extras and returns {} (no-op).
-  allContextKeys = [
-    "host"
-    "user"
-    "home"
-  ];
-
+  # Build a parametric wrapper requiring exactly `requiredKeys` (all required —
+  # no optional "extra" keys, hence no self-suppression). The fx bind handler
+  # binds these per the current rule and applies `__fn` with the resolved args.
   perCtx =
     requiredKeys: aspect:
     let
-      reqKeysSorted = builtins.sort builtins.lessThan requiredKeys;
-      extraKeys = builtins.filter (k: !(builtins.elem k reqKeysSorted)) allContextKeys;
-      # Required keys as required (false), extra keys as optional (true)
-      funcArgs = lib.genAttrs reqKeysSorted (_: false) // lib.genAttrs extraKeys (_: true);
+      reqSorted = builtins.sort builtins.lessThan requiredKeys;
     in
     lib.warn
-      "den.lib.perCtx [${lib.concatStringsSep "," reqKeysSorted}] is deprecated — use a plain function ({ ${lib.concatStringsSep ", " reqKeysSorted}, ... }: ...) instead; handler-based resolution resolves context args automatically"
+      "den.lib.perCtx [${lib.concatStringsSep "," reqSorted}] is deprecated — use a plain function ({ ${lib.concatStringsSep ", " reqSorted}, ... }: ...) instead; handler-based resolution binds context args automatically"
       {
+        __args = lib.genAttrs reqSorted (_: false);
         __fn =
           resolvedArgs:
-          let
-            # If any extra key was resolved (handler exists), we're at a deeper level
-            hasExtras = builtins.any (k: resolvedArgs ? ${k}) extraKeys;
-          in
-          if hasExtras then
-            { }
-          else if lib.isFunction aspect && !builtins.isAttrs aspect then
-            aspect (lib.intersectAttrs (lib.genAttrs reqKeysSorted (_: null)) resolvedArgs)
+          if lib.isFunction aspect && !builtins.isAttrs aspect then
+            aspect (lib.intersectAttrs (lib.genAttrs reqSorted (_: null)) resolvedArgs)
           else
             aspect;
-        __args = funcArgs;
+        name = aspect.name or "<perCtx>";
+        meta = aspect.meta or { };
       };
 
   perHost = perCtx [ "host" ];