provides.to-users vs policies.to-users

[zenoli]

Both in Providing across entities and Cross-Entity Provides there are examples of using provides.to-hosts / provides.to-users but in the info-callout of the second link it is stated:

For new configurations, prefer den.policies with explicit policy.include for cross-entity delivery — it’s more flexible and explicit. The provides patterns above are a permanent API for existing usage.

I think what is mean by that is using something like this:

https://den.denful.dev/explanation/policy-activation/#aspect-level-policies

Should the documentation be updated to use the policies based syntax?

The provides.to-users is built-in and I don't have to register & include (1 modification vs 2 modifications when using policies).
If one wants to push config from a host to all users, to me it looks that provides.to-users is more concise, hence I'm confused about encouraging users to not use it.

Also, is there a nice denful configuration that is not just a barebones toy example but also not overly complex to get a bit more acclimated with the various concepts like batteries, custom policies, quirks etc?

[sini]

I'll be doing a full rewrite of the docs when den-hoag ships and that will hopefully make the grammar for expressing cross-entity relationships a lot more clear.

The reason to avoid aspect provides is that it couples behavior definition with assignment/relationship and makes your modules less portable and obfuscated within the behavior module. The documentation (and policies) need some improvements. :)

[zenoli]

Thank you for your response.
What is den-hoag?

The reason to avoid aspect provides is that it couples behavior definition with assignment/relationship

I'm not sure if I understand. Once I include the policy on the aspect it was defined in as in this example, I explicitly introduce the same coupling, no?

https://jelly.qew.ch/Items/91cea264d17a0c7e67a8382076193986/Download?api_key=5f46ae4bedd44d3584eb3019fcdaf02c

[sini]

Policies should generally be defined on the entities they apply to.

https://github.com/sini/den-hoag -- built on https://github.com/sini/gen

I'll add better docs later but try to think of it as a graph because ultimately they are, see: https://github.com/denful/den/tree/main/templates/fleet-demo#diagrams

Aspects collapse on an entity to materialize a query to build a result.

When those edges randomly spawn from notes in a subtree, things get muddy. We support that behavior, but it's less pure than saying "user@host includes foo". Using provides is saying "behavior foo applies to user if it's included in the current evaluation tree" and that's fundamentally more difficult to reason about.

[sini]

Here's a graph of a real system:
https://github.com/sini/nix-config/blob/main/diagrams/hosts/cortex.md
and fleet:
https://github.com/sini/nix-config/blob/main/diagrams/fleet.md

[zenoli]

Thanks for the explanation and references. I'm very new to den and need to acclimate a bit first (everything sounds a bit too abstract atm :-)).

Your config seems like a good reference, exactly what I was looking for. Thanks!

Here's a graph of a real system:
https://github.com/sini/nix-config/blob/main/diagrams/hosts/cortex.md
and fleet:
https://github.com/sini/nix-config/blob/main/diagrams/fleet.md

Crazy stuff!