docs: cover undocumented public surface and fix stale API references - #659
Merged
Merged
Conversation
Adds documentation for public features that shipped without docs, and
corrects code comments still pointing at the removed adapter API.
New page — explanation/structural-introspection:
entity.hasAspect / entity.aspects, meta.handleWith with
den.lib.aspects.fx.constraints (exclude / substitute / filterBy and
their .global variants), and the lib-level building blocks. Covers
where hasAspect is safe to call and why includes is not.
Reference and guide additions:
- pipe.broadcast stage semantics + worked fleet example
- conditional aspects (meta.guard / meta.aspects) via policy.when
- den.batteries.flake-scope
- built-in policy tables: os-to-host, user-to-host, the home-env
family, wsl, and the flake-parts pair
- den.schema collection fields (isEntity, isolated, parent,
collisionPolicy) and the den.schema.aspect base module
- den.classes fields: description, forwardTo, parentPath, parentArg
- den.reservedKeys, den.systems, flat host/home declaration forms
- policy deliver/route guard + adaptArgs, route collectSubtree and
the intoPath alias, custom instantiate specs, resolve.shared.to
- captureFleet, resolveWithPaths / resolveWithState
- class-module arg promotion for descendant entity kinds
Corrections to existing docs:
- collision policy resolves over four levels, not three
- stale battery anchors in the sidebar and tutorials
- lib.mdx linked to a nonexistent /reference/options/ page
Code comments only (no behaviour change):
has-aspect.nix and the example template referenced oneOfAspects,
excludeAspect, meta.adapter and adapters.nix, none of which still
exist; they now point at meta.handleWith + fx.constraints.
theutz
requested changes
Aug 25, 2026
theutz
left a comment
theutz
left a comment
Collaborator
There was a problem hiding this comment.
A much needed refresh. This is great!
… example Membership is class-invariant, so hasAspect, forClass and forAnyClass agree for any class an entity declares; say so rather than implying the variants answer differently. Tie present/absent to the boolean they describe. constraints.exclude is unconditional — the secrets-bundle example claimed it fires 'whenever both are present' while excluding an aspect it had just included. Exclude something a transitively included aspect drags in instead. Class entries are a record of options; 'schema' collides with den.schema entity kinds.
theutz
approved these changes
Aug 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents public features that shipped without docs, and fixes code comments still pointing at the removed adapter API.
New page
explanation/structural-introspection—entity.hasAspect/entity.aspects,meta.handleWithwithden.lib.aspects.fx.constraints(exclude/substitute/filterByplus their.globalvariants), and the lib-level building blocks (hasAspectIn,collectPathSet,mkEntityHasAspect,mkProjectedHasAspect). Covers wherehasAspectis safe to call, and whyincludesis not.Previously this API was only discoverable by reading
templates/example.Reference and guide additions
pipe.broadcaststage semantics + a worked fleet example (had zero docs)meta.guard/meta.aspects) viapolicy.whenden.batteries.flake-scopeos-to-host,user-to-host, the home-env family, wsl, and the flake-parts pairden.schemacollection fields (isEntity,isolated,parent,collisionPolicy) and theden.schema.aspectbase moduleden.classesfields:description,forwardTo,parentPath,parentArgden.reservedKeys,den.systems, flat host/home declaration formsdeliver/routeguard+adaptArgs,route.collectSubtree, theintoPathalias, custominstantiatespecs,resolve.shared.tocaptureFleet,resolveWithPaths/resolveWithStateuserinside an aspect'snixosclass module #629)Corrections to existing docs
den.schema.<kind>→ global), matchingresolveCollisionPolicyinclass-module.nixlib.mdxlinked to a nonexistent/reference/options/pageCode changes
Comments and one option
descriptiononly, no behaviour change.modules/context/has-aspect.nixand the example template referencedoneOfAspects,excludeAspect,meta.adapterandadapters.nix— none of which still exist — and named the filter constraintfilter/filterIncludesrather thanfilterBy.Verification
nix develop -c just fmt— clean, no changes to the editsnix flake check --override-input den . ./templates/example—all checks passed!pnpm build— 61 pages, cleandist/: 8,349 links, 0 broken pages, 0 broken anchorsKnown follow-ups (not in this PR)
Still undocumented:
denTest'sexpectedErroroption and theshow/funnyNames/withSystemhelpers, and there is no option-reference page forden.config. Separately,templates/ci/still carries staletest-excludeAspect-*test names and ameta.adaptercomment.