fix: don't re-declare forward adapters in host-aspects spawns

A custom class built with `_.forward` fails to evaluate when the
`host-aspects` battery is also included:

  The option `home-manager.users.<u>.den.fwd."<from>/<into>/<path>"'
  is already declared

#603 made a spawned node apply the parent pipeline's subtree routes, so
a user-schema route (homeLinux->homeManager) fires against the content
the spawn re-emits. Adapter-bearing routes are not safe under that rule:
`mkAdapterAspect` / `mkAdapterFunctor` materialize an option
DECLARATION, and the parent pipeline already materializes the same route
at the same scope. Both folds land in one home-manager evaluation, so
the second declaration is a hard conflict — content definitions merge,
declarations do not.

Exclude declaration-bearing parent routes from the spawn's route merge,
leaving the parent's copy as the single owner. That copy is always there
to take over: an excluded route is by construction inside the spawned
subtree, and the redundant-root suppression only fires on a route at the
fold root. Simple routes keep re-applying, preserving #603.

Four regression cases (user-defined content, host-defined content,
host-defined across two users, and a no-battery control); the three
battery cases fail at the parent commit with the reported error.

Reported in discussion #642.

Author: sini

nix/lib/aspects/fx/spawn-node.nix

@@ -161,6 +161,27 @@ in
         allScopeIds = spawnAllScopeIds;
       }) (_: true);
 
+      # A route that materializes an adapter DECLARES `options.den.fwd.<key>` in
+      # the target bucket (handlers/forward.nix mkAdapterAspect, edges/route.nix
+      # mkAdapterFunctor). Content definitions merge; an option DECLARATION does
+      # not — a second one in the same evalModules is a hard "already declared"
+      # error. Of buildForwardAspect's three arms only mkAdapterAspect declares:
+      # the top-level adapter arm evaluates inline and mkDirectAspect places
+      # content, so both stay.
+      #
+      # Testing __complexForward FIRST is load-bearing, not stylistic: every
+      # complex forward carries an adapterKey (lib/forward.nix always builds
+      # one), so a bare `adapterKey != null` would also exclude non-declaring
+      # forwards — among them the home-manager battery's own delivery route.
+      # The simple-route arm is defensive: adapterKey has one in-tree producer
+      # (lib/forward.nix), which only builds complex-forward specs.
+      declaresForwardOption =
+        r:
+        if r.__complexForward or false then
+          (r.needsAdapter or false) && !(r.needsTopLevelAdapter or false)
+        else
+          (r.adapterKey or null) != null;
+
       # DELIBERATE: parent-pipeline routes sourced inside the spawned
       # subtree MUST re-apply — the spawn re-emits class content at the same scope
       # ids but never re-fires schema policies, so without them a user-schema route
@@ -171,6 +192,24 @@ in
       # simple route would re-nest content in fresh keyless wrappers and conflict
       # at the target). Order/precedence preserved exactly: freshParent (parent
       # routes whose key ∉ spawn keys) ++ spawnHere.
+      #
+      # Declaration-bearing parent routes are excluded outright, leaving the
+      # parent's copy as the single owner of that declaration: the parent
+      # materializes the same route at the same scope and both folds land in one
+      # target (the user's home-manager evaluation), so re-applying here emits a
+      # second `den.fwd.<key>` declaration.
+      #
+      # The parent's copy is always present to take over — an excluded route is
+      # by construction inside the spawned subtree, and `suppressionVerdicts`'
+      # redundant-root rule only fires on a route AT the fold root, which for the
+      # parent is an ancestor of spawnRoot.
+      #
+      # For a forward-only custom class the parent's copy also carries what the
+      # spawn would have forwarded, because `getCollectedSource` pulls root-scope
+      # content for it. That is NOT general: `filterRootModules` narrows root
+      # content to `den.default` modules once fromClass is an entity-owned class,
+      # and the parent collects the host bucket unprojected where the spawn would
+      # have re-resolved it per user.
       spawnRoutes = result.state.scopedRoutes null;
       parentSubtreeRoutes = lib.filterAttrs (sid: _: subtreeSet ? ${sid}) parentState.scopedRoutes;
       mergedSpawnRoutes =
@@ -180,7 +219,9 @@ in
           let
             spawnHere = spawnRoutes.${sid} or [ ];
             spawnKeys = lib.genAttrs (map (routeKey sid) spawnHere) (_: true);
-            freshParent = builtins.filter (r: !(spawnKeys ? ${routeKey sid r})) parentRoutes;
+            freshParent = builtins.filter (
+              r: !(spawnKeys ? ${routeKey sid r}) && !(declaresForwardOption r)
+            ) parentRoutes;
           in
           freshParent ++ spawnHere
         ) parentSubtreeRoutes;

templates/ci/modules/deadbugs/issue-642-host-aspects-custom-class.nix

@@ -0,0 +1,152 @@
+# Discussion #642: a custom class defined via `_.forward` double-emits its
+# forwarded content when the `host-aspects` battery is also included, producing
+# an "already declared" option conflict on `den.fwd."<aspect>/<class>/<path>"`.
+#
+# The battery's spawn re-applied the parent pipeline's own forward route, so the
+# adapter's `options.den.fwd.<key>` declaration was materialized by two folds
+# that both land in the user's home-manager evaluation.
+{ denTest, ... }:
+let
+  # One definition, threaded per test — each `denTest` gets its own `den`/`lib`.
+  obsidianClass =
+    den: lib:
+    { class, aspect-chain }:
+    den._.forward {
+      each = lib.singleton class;
+      fromClass = _: "obsidian";
+      intoClass = _: "homeManager";
+      intoPath = _: [
+        "programs"
+        "obsidian"
+      ];
+      fromAspect = _: lib.last aspect-chain;
+      guard = { options, ... }: options ? programs.obsidian;
+    };
+in
+{
+  flake.tests.deadbugs.issue-642-host-aspects-custom-class = {
+
+    # The reported shape: user-defined content through the custom class, with
+    # the battery on.
+    test-custom-class-with-host-aspects = denTest (
+      {
+        den,
+        lib,
+        tuxHm,
+        ...
+      }:
+      {
+        den.default.includes = [
+          den._.host-aspects
+          (obsidianClass den lib)
+        ];
+
+        den.aspects.obsidian = {
+          obsidian.enable = true;
+        };
+
+        den.hosts.x86_64-linux.igloo.users.tux = { };
+
+        den.aspects.tux.includes = [ den.aspects.obsidian ];
+
+        expr = tuxHm.programs.obsidian.enable;
+        expected = true;
+      }
+    );
+
+    # The custom class's content lives on the HOST aspect and reaches the user
+    # only through host-aspects — the projection the duplicate-suppression must
+    # not strand.
+    test-host-defined-custom-class-projects = denTest (
+      {
+        den,
+        lib,
+        tuxHm,
+        ...
+      }:
+      {
+        den.default.includes = [
+          den._.host-aspects
+          (obsidianClass den lib)
+        ];
+
+        den.aspects.obsidian = {
+          obsidian.enable = true;
+        };
+
+        den.hosts.x86_64-linux.igloo.users.tux = { };
+
+        den.aspects.igloo.includes = [ den.aspects.obsidian ];
+
+        expr = tuxHm.programs.obsidian.enable;
+        expected = true;
+      }
+    );
+
+    # Suppressing the spawn's copy leaves ONE owner for the declaration, so that
+    # owner must still reach every user on the host — not just the first.
+    test-host-defined-custom-class-reaches-every-user = denTest (
+      {
+        den,
+        lib,
+        igloo,
+        ...
+      }:
+      {
+        den.default.includes = [
+          den._.host-aspects
+          (obsidianClass den lib)
+        ];
+
+        den.aspects.obsidian = {
+          obsidian.enable = true;
+        };
+
+        den.hosts.x86_64-linux.igloo.users = {
+          tux = { };
+          pingu = { };
+        };
+
+        den.aspects.igloo.includes = [ den.aspects.obsidian ];
+
+        expr = {
+          tux = igloo.home-manager.users.tux.programs.obsidian.enable or "<missing>";
+          pingu = igloo.home-manager.users.pingu.programs.obsidian.enable or "<missing>";
+        };
+        expected = {
+          tux = true;
+          pingu = true;
+        };
+      }
+    );
+
+    # CONTROL: same custom class without the host-aspects battery — the one
+    # shape that stayed green while the bug was live, isolating the battery as
+    # the trigger.
+    test-custom-class-without-host-aspects = denTest (
+      {
+        den,
+        lib,
+        tuxHm,
+        ...
+      }:
+      {
+        den.default.includes = [
+          (obsidianClass den lib)
+        ];
+
+        den.aspects.obsidian = {
+          obsidian.enable = true;
+        };
+
+        den.hosts.x86_64-linux.igloo.users.tux = { };
+
+        den.aspects.tux.includes = [ den.aspects.obsidian ];
+
+        expr = tuxHm.programs.obsidian.enable;
+        expected = true;
+      }
+    );
+
+  };
+}