docs(spec): TOP_LEVEL_COLLECTIONS_NEVER_RESIDUAL names the readers of top-level datasets the tree has

.changeset/29335-residual-datasets-docblock.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the comment on the stack's never-residual collections names the readers that exist
+
+Clause-②: no
+Metadata-protocol: none
+
+A comment-only change in `src/stack.zod.ts`, which the package ships as source. The comment on the set of top-level collections a `packages[]` stack never treats as residual (`data`, `datasets`, `jobs`) said `AppPlugin` consumes top-level `datasets` straight off the bundle. It does not: a package body's `datasets` are read by the engine's `registerApp` (`@objectstack/objectql`), and no boot reader takes a top-level `datasets` item that no body declares. The comment now says so. No schema, type, export or behaviour changes; nothing to migrate.

packages/spec/src/stack.zod.ts

@@ -361,11 +361,17 @@ function applyCollectionItemOwnerStampGate(
  * The judged collections a `packages[]` stack's TOP LEVEL never files as
  * residual items: the boot's residual rule (`unclaimedTopLevel`,
  * `@objectstack/metadata`) walks the collections the metadata door registers
- * as items (its `ARTIFACT_FIELD_TO_TYPE`), and these three are not among them.
- * The boot reads them off the stack whole and judges no stamp on them: seed
- * `data` is applied by the seed loader, `jobs` are scheduled and `datasets`
- * consumed by `AppPlugin` straight off the bundle. A package BODY's items of
- * these collections are still judged, at both doors.
+ * as items (its `ARTIFACT_FIELD_TO_TYPE`), and these three are not among them,
+ * so the boot judges no stamp on a top-level item of any of them. Their readers
+ * differ:
+ *  - seed `data` and `jobs` are read off the stack whole, the top level merged
+ *    with every body (`resolveArtifactCollections`, `@objectstack/runtime`):
+ *    `AppPlugin` hands the seed `data` to the seed loader and schedules the
+ *    `jobs`;
+ *  - `datasets` are read off the package BODIES only, by the engine's
+ *    `registerApp` (its `METADATA_ARRAY_KEYS` loop, `@objectstack/objectql`).
+ *    No boot reader takes a top-level `datasets` item that no body declares.
+ * A package BODY's items of these collections are still judged, at both doors.
  *
  * Mirrored, because `@objectstack/spec` cannot import the rule it mirrors; a
  * `@objectstack/metadata` test holds the two equal, collection by collection.