From 5ad41caa8c66696324e1dd8c08288e41f37e899b Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 2 Nov 2026 16:46:58 +0000 Subject: [PATCH 1/2] docs(spec): TOP_LEVEL_COLLECTIONS_NEVER_RESIDUAL names the readers the tree has The docblock said top-level datasets are consumed by AppPlugin straight off the bundle. AppPlugin reads no datasets; a package body's datasets are read by the engine's registerApp METADATA_ARRAY_KEYS loop, and nothing reads a top-level datasets item no body declares. Claude-Session: https://claude.ai/code/session_01JQwxbad6xiDCcLYXcBsEa6 Co-authored-by: Claude --- packages/spec/src/stack.zod.ts | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/packages/spec/src/stack.zod.ts b/packages/spec/src/stack.zod.ts index 97ef3bcfbe6..45dae530a4e 100644 --- a/packages/spec/src/stack.zod.ts +++ b/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. From 6538e4a345fbac444a6e35a66ed498e01b102127 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 2 Nov 2026 16:48:40 +0000 Subject: [PATCH 2/2] chore(changeset): patch for the never-residual collections comment Claude-Session: https://claude.ai/code/session_01JQwxbad6xiDCcLYXcBsEa6 Co-authored-by: Claude --- .changeset/29335-residual-datasets-docblock.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 .changeset/29335-residual-datasets-docblock.md diff --git a/.changeset/29335-residual-datasets-docblock.md b/.changeset/29335-residual-datasets-docblock.md new file mode 100644 index 00000000000..d0901c7454f --- /dev/null +++ b/.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.