feat: warn when a raw-ref exclude matches no claim anywhere in a resolution

An exclude naming a policy record den never found resolved to null, was
filtered out, and suppressed nothing with no diagnostic.

The check is global, not per-scope: resolveRawRefIdentity returning null
for one scope is correct behaviour — a host-scope exclude reaches every
descendant scope and the policy it names is typically claimed in only
some of them — so warning from isPolicyExcluded would fire on every
legitimate multi-scope exclude. It reads the terminal state at
fxResolveFull's post-assembly position instead, where both the constraint
registry and policyClaimsByName are complete.

Author: sini

nix/lib/aspects/fx/handlers/constraint.nix

@@ -198,6 +198,43 @@ let
     in
     builtins.any directApplies directEntries || rawRefExcluded ? ${name};
 
+  # The `den:` diagnostics for raw-ref excludes that resolved to no claim
+  # ANYWHERE in a finished resolution — a user naming a record den never found,
+  # suppressing nothing, previously in silence.
+  #
+  # DELIBERATELY NOT ON THE PER-SCOPE PATH. resolveRawRefIdentity returning null
+  # for one scope is ordinary correct behaviour: an exclude registered at host
+  # scope reaches every descendant scope, and the policy it names is typically
+  # claimed in only some of them. Warning from isPolicyExcluded would fire on
+  # every non-matching scope of every legitimate exclude. The warnable condition
+  # is global — no claim in the whole run carries this reference — so it takes
+  # the TERMINAL state, and is read once at post-assembly (resolve.nix's
+  # fxResolveFull), never during dispatch.
+  #
+  # Whole-value `==` against the claim bucket, matching resolveClaim's rule
+  # exactly, minus its scope walk: the question here is whether the referenced
+  # record registered AT ALL, not whether it registered somewhere a given scope
+  # can see. Deliberately the weaker test — a claim in an unreachable sibling
+  # scope stays silent rather than risk a false alarm.
+  unmatchedRawRefExcludes =
+    state:
+    let
+      registry = (state.scopedConstraintRegistry or (_: { })) null;
+      claims = (state.policyClaimsByName or (_: { })) null;
+      rawRefEntries = builtins.filter (e: e.type == "exclude" && (e.rawRef or null) != null) (
+        builtins.concatMap (scopeData: builtins.concatLists (builtins.attrValues scopeData)) (
+          builtins.attrValues registry
+        )
+      );
+      isUnmatched = e: !(builtins.any (c: c.value == e.rawRef) (claims."name:${e.rawRef.name}" or [ ]));
+    in
+    lib.unique (
+      map (
+        e:
+        "den: exclude in aspect '${e.owner}' names policy '${e.rawRef.name}', which never registered in this resolution — the exclude suppresses nothing"
+      ) (builtins.filter isUnmatched rawRefEntries)
+    );
+
   entryToResume =
     entry:
     if entry.type == "exclude" then
@@ -319,6 +356,7 @@ in
     foldScopeAncestors
     resolveClaim
     isPolicyExcluded
+    unmatchedRawRefExcludes
     collectScopedConstraints
     scopedConstraintsFor
     scopedConstraintsForScope

nix/lib/aspects/fx/resolve.nix

@@ -1068,7 +1068,15 @@ let
       );
     in
     {
-      imports = phase4.${class} or [ ];
+      # Terminal position for the unmatched-raw-ref-exclude diagnostic: both
+      # the constraint registry and policyClaimsByName are complete on
+      # result.state here, and nothing per-scope can decide the question (see
+      # unmatchedRawRefExcludes in handlers/constraint.nix). Attached to
+      # `imports` so it surfaces exactly when the resolved module set is
+      # consumed, not when a path-set or edge-trace reader touches the bundle.
+      imports = lib.foldl' (v: msg: lib.warn msg v) (phase4.${class} or [ ]) (
+        handlers.unmatchedRawRefExcludes result.state
+      );
       # Surfaced from the SAME result.state — this is thunked onto state.
       pathSetByScope = result.state.pathSetByScope null;
       # Per-scope ctx + entity-kind, so the entity surface can re-key the path

templates/ci/modules/features/unmatched-policy-exclude.nix

@@ -0,0 +1,91 @@
+# A raw-ref exclude naming a policy den never found must say so.
+#
+# The two cells disagree on purpose. The diagnostic is GLOBAL — "this reference
+# matched no claim anywhere in the run" — because an exclude that resolves in
+# one scope and not another is CORRECT behaviour, not a user error. The control
+# below is the whole reason the check cannot sit on the per-scope dispatch path:
+# it holds a host-scope exclude whose policy is claimed only under one of two
+# users, so isPolicyExcluded genuinely answers true at one scope and false at
+# the other, and nothing may warn about it.
+{ denTest, ... }:
+let
+  # The finished pipeline state for igloo — the terminal registries the
+  # diagnostic reads, same shape resolve.nix's post-assembly sees.
+  hostState =
+    den:
+    let
+      fxLib = den.lib.aspects.fx;
+      hostRoot = den.lib.resolveEntity "host" { host = den.hosts.x86_64-linux.igloo; };
+    in
+    (fxLib.pipeline.fxFullResolve {
+      class = "nixos";
+      ctx = fxLib.aspect.ctxFromHandlers (hostRoot.__scopeHandlers or { });
+      self = den.lib.aspects.normalizeRoot hostRoot;
+    }).state;
+in
+{
+  flake.tests.unmatched-policy-exclude = {
+
+    test-exclude-naming-unregistered-policy-warns = denTest (
+      { den, ... }:
+      let
+        hostRoot = den.lib.resolveEntity "host" { host = den.hosts.x86_64-linux.igloo; };
+      in
+      {
+        den.hosts.x86_64-linux.igloo.users.tux = { };
+        den.policies.never-registered = _: [
+          (den.lib.policy.include { nixos.environment.variables.MARKER = "yes"; })
+        ];
+        den.aspects.igloo.excludes = [ den.policies.never-registered ];
+
+        expr = {
+          messages = den.lib.aspects.fx.handlers.unmatchedRawRefExcludes (hostState den);
+          # Forces the wired production path so the warning actually reaches
+          # stderr; the message text itself is asserted above.
+          resolves = (den.lib.aspects.resolve "nixos" hostRoot).imports != [ ];
+        };
+        expected = {
+          messages = [
+            "den: exclude in aspect 'igloo' names policy 'never-registered', which never registered in this resolution — the exclude suppresses nothing"
+          ];
+          resolves = true;
+        };
+      }
+    );
+
+    # The live control. tux claims the policy, pingu does not; the exclude is
+    # declared once at host scope and reaches both. Excluded at tux, not at
+    # pingu — and silent.
+    test-exclude-matching-only-one-scope-is-silent = denTest (
+      { den, ... }:
+      let
+        handlers = den.lib.aspects.fx.handlers;
+        st = hostState den;
+        scopes = builtins.attrNames (st.scopeContexts null);
+        scopeMatching = pat: builtins.head (builtins.filter (s: builtins.match pat s != null) scopes);
+        excludedAt =
+          scope:
+          handlers.isPolicyExcluded st scope (handlers.scopedConstraintsForScope st scope) "add-marker";
+      in
+      {
+        den.hosts.x86_64-linux.igloo.users.pingu = { };
+        den.hosts.x86_64-linux.igloo.users.tux.aspect.includes = [ den.policies.add-marker ];
+        den.policies.add-marker = _: [
+          (den.lib.policy.include { homeManager.programs.git.enable = true; })
+        ];
+        den.aspects.igloo.excludes = [ den.policies.add-marker ];
+
+        expr = {
+          atTux = excludedAt (scopeMatching ".*user=tux.*");
+          atPingu = excludedAt (scopeMatching ".*user=pingu.*");
+          messages = handlers.unmatchedRawRefExcludes st;
+        };
+        expected = {
+          atTux = true;
+          atPingu = false;
+          messages = [ ];
+        };
+      }
+    );
+  };
+}