Define the Den–Clan boundary

[fosskar]

Destination

Produce an implementation-ready specification for a Den WHAT / Clan WHERE integration. Den will group reusable cross-class features, while Clan remains authoritative for inventory, assignment, secrets, final composition, and deployment. Validate the boundary with a disposable prototype and define the supported Den interface needed for production.

Directions considered

• Keep only flake.modules and Clan — rejected because it does not provide the selected cross-class feature grouping.
• Let Den own hosts or final system outputs — rejected because it duplicates Clan inventory and composition authority.
• Use Den's internal resolver in production — rejected because Den does not provide compatibility guarantees for it.

Notes

Domain: NixOS fleet architecture in fosskar/nixfiles, with Den and Clan as possible cooperating systems.

Use official documentation and source code as primary evidence:

• Den source: https://github.com/denful/den
• Clan source: https://git.clan.lol/clan/clan-core
• Include sini/clan-diagram-shim in the prior-art research.

The current hypothesis is “Den handles WHAT; Clan handles WHERE.” Treat it as one candidate, not as a fixed decision.

Consult the research, grilling, prototype, and codebase-design skills when their ticket type needs them.

Decisions so far

• Map Den responsibilities and extension points — Den owns entity and aspect composition plus output generation; it has no deployment or secret subsystem, and direct external aspect resolution is not a public API.

• Find Den–Clan integration prior art — No official integration exists; clan-diagram-shim only adapts Clan data for visualization, and one system must own host facts and final configuration instantiation.

• Inventory the repository integration seams — Existing module exports can feed Clan through machine, role, service, and user imports; the lowest-disruption seam keeps fleet authority in Clan.

• Map Clan responsibilities and extension points — Clan must own inventory, role assignment, vars, final machine composition, and deployment; Den modules can enter through machine imports, extraModules, or Clan service results.

• Choose the Den–Clan direction — Den owns cross-class feature definitions; Clan owns placement and operations, with Den internals allowed only in a disposable prototype.

• Verify the Clan services split — The move affects bundled service implementations, not the clan.service framework; machine imports, inventory roles, and service roles remain viable placement edges.

Not yet specified

• The production-quality Den interface, subject to prototype evidence.
• The migration and compatibility-validation route after the integration seam and placement model are fixed.
• The effect of Den policies, aspect dependencies, and custom classes beyond the first cross-class feature.

Out of scope

• Implementing the integration or migrating repository code. This map stops at an implementation-ready handoff.