@opensaas/stack-core 0.36.0 → 0.38.0

package/dist/access/declared-dependencies.d.ts

@@ -1,4 +1,5 @@
 import type { FieldConfig, OpenSaasConfig } from '../config/types.js';
+import type { FieldSelectionScope } from '../query/index.js';
 /**
  * Declared Dependencies — folding a computed field's `needs` into a read's
  * `include` without widening what the caller receives (ADR-0025).
@@ -6,10 +7,9 @@ import type { FieldConfig, OpenSaasConfig } from '../config/types.js';
  * A field's `needs` declares immediate sibling relations its `resolveOutput`
  * hook cannot compute without. This module folds those relations into
  * whatever `include` a read is already building (caller-supplied, fragment-
- * derived, or none at all) BEFORE it reaches the existing access-scoping
- * pipeline (`buildIncludeWithAccessControl` / `mergeIncludeWithAccessControl`
- * in `access-filter.ts`) — a declared relation is scoped exactly like a
- * caller-named one, never a bypass.
+ * derived, or none at all) BEFORE it reaches the access-scoping pipeline
+ * (`buildAccessScopedInclude` in `access-filter.ts`) — a declared relation is
+ * scoped exactly like a caller-named one, never a bypass.
  *
  * The fold also tracks provenance: which relation keys, at which nesting
  * level, were added ONLY to satisfy a declaration (as opposed to being named
@@ -17,25 +17,44 @@ import type { FieldConfig, OpenSaasConfig } from '../config/types.js';
  * from the result after `resolveOutput` hooks have had a chance to read them
  * — a declared dependency is private plumbing, not an implicit `include`.
  *
- * Reach beyond one hop: a relation added here to satisfy a declaration is
- * added BARE (`true`), never with an explicit nested include of its own.
- * `buildIncludeWithAccessControl` already auto-expands a bare relation's own
- * readable-relationship subtree to `READ_INCLUDE_MAX_DEPTH` (pre-ADR-0026),
- * so a chain of declarations rides that existing expansion for free — the
- * related list's own declared needs are already present among what gets
- * auto-included beneath it. This is also why a declaration-driven cycle
- * (e.g. `Order.total` needs `lineItems`, `LineItem.orderRef` needs `order`)
- * can't recurse without bound here: it flows through
- * `buildIncludeWithAccessControl`'s existing `visitedLists` cycle guard
- * rather than through any recursion of this module's own (see ADR-0026's
- * note that this guard's remaining job, after that ADR lands, is defending
- * exactly this fold).
+ * **Every relation this module reaches is folded recursively**, whether it
+ * was added purely to satisfy a declaration or is already present for another
+ * reason (caller/fragment-named, bare or not). Since ADR-0026 removed the
+ * auto-expansion that used to carry a chain of declarations "for free" —
+ * naming a relation now fetches its own columns and stops — a field computed
+ * one hop down would otherwise lose its own declared dependencies the moment
+ * its list is reached any way OTHER than an explicit nested caller `include`.
+ * Declarations fold in "at every level a field is computed" (ADR-0025), not
+ * only where the caller happened to write one out.
  *
- * This module only recurses into EXPLICIT nested includes the caller wrote
- * (narrowing what's fetched below a relation) — those cut off the free
- * auto-expansion, so a nested list's own declared needs must be folded in
- * explicitly. An explicit caller include is always a finite literal, so this
- * recursion terminates on its own without a separate depth/cycle guard.
+ * A branch added purely by this fold (`declaredOnly.keys`) is stripped
+ * wholesale by `filterReadableFields` regardless of what's nested inside it,
+ * so its own nested declared-only keys need no individual tracking — only a
+ * branch present for another reason (caller/fragment-named) needs the
+ * fine-grained `declaredOnly.nested` tracking, so a declaration folded
+ * beneath IT can be stripped without removing the caller's own data.
+ *
+ * **Cycle guard, re-pointed (ADR-0026).** A caller-supplied `include` is
+ * always a finite literal and cannot cycle. Recursively following declared
+ * dependencies across lists CAN — list A declaring `needs` on a relation to
+ * list B, whose own field declares `needs` back to A — so `visitedLists`
+ * carries the list names already on this fold's own path and stops rather
+ * than recursing without bound. `pnpm generate`'s `validateNeedsClosureDepth`
+ * (`needs-closure.ts`) is the primary backstop — a cyclic `needs` closure
+ * fails generation and should never reach this code at runtime — this guard
+ * is defense in depth, not the mechanism relied on for correctness.
+ *
+ * The guard applies to DECLARATION-ADDED edges only, which is exactly where
+ * the unbounded recursion can come from: a branch added by this fold carries
+ * no caller include of its own, so everything beneath it is declaration-added
+ * too, and each such edge either reaches a list not yet on the path or stops
+ * — bounding that suffix by the number of lists. An edge the request itself
+ * named is bounded by the request's own finite literal instead. Applying the
+ * guard to those as well would stop the fold at a path that merely revisits a
+ * list (`Post → author → posts`, or a self-referential `parent`), silently
+ * leaving the revisited list's own declared dependencies unsatisfied — the
+ * `undefined`-compute ADR-0025 exists to prevent, at every level a field is
+ * computed.
  */
 /** Which relation keys, at which nesting level, exist only to satisfy a `needs` declaration. */
 export type DeclaredOnlyTree = {
@@ -50,18 +69,39 @@ export declare function emptyDeclaredOnlyTree(): DeclaredOnlyTree;
  * list that have a `resolveOutput` hook. A `needs` entry on a field without
  * one is inert — there is no hook to feed it to — so it contributes nothing
  * to fetch.
+ *
+ * `selectedFields`, when given, restricts the union to fields the read is
+ * actually going to return (ADR-0027) — a field a fragment did not select is
+ * never computed, so its declared relation is never fetched for it either.
+ * `undefined` means unrestricted: every field with a hook contributes,
+ * matching a bare or `include`-based read, which always returns every
+ * computed field on the list.
  */
-export declare function getDeclaredRelationNames(fieldConfigs: Record<string, FieldConfig>): string[];
+export declare function getDeclaredRelationNames(fieldConfigs: Record<string, FieldConfig>, selectedFields?: ReadonlySet<string>): string[];
 /**
  * Fold this list's declared dependencies into `rawInclude`, recursing into
- * any EXPLICIT nested include the caller wrote so a related list's own
- * declared needs are satisfied too (see module doc comment).
+ * EVERY relation reached from here — whether it was just added to satisfy a
+ * declaration or was already present for another reason — so that list's own
+ * declared dependencies are satisfied too, wherever it's reached (see module
+ * doc comment).
  *
  * Returns `rawInclude` itself (same reference) when there is nothing to
  * fold, so a list with no `needs` fields and no caller include stays on the
  * exact bare-read path (ADR-0024) — untouched, not merely equivalent.
+ *
+ * `listKey` seeds the cycle guard at the root of a read; recursive calls
+ * extend it with each related list reached along THIS fold's own path.
+ *
+ * `selection`, when given, is the fragment scope this level was reached
+ * under (ADR-0027) — only fields it names contribute their `needs` (see
+ * `getDeclaredRelationNames`). It is `undefined` for a bare/`include`-based
+ * read (unrestricted: every field's `needs` folds in, unchanged from before
+ * ADR-0027) and for any branch reached only to satisfy a declaration — a
+ * relation added purely by this fold has no fragment scope of its own, so
+ * its own list folds unrestricted, exactly as it did before selectivity
+ * existed.
  */
-export declare function foldDeclaredDependencies(rawInclude: Record<string, unknown> | undefined, fieldConfigs: Record<string, FieldConfig>, config: OpenSaasConfig): {
+export declare function foldDeclaredDependencies(rawInclude: Record<string, unknown> | undefined, fieldConfigs: Record<string, FieldConfig>, config: OpenSaasConfig, listKey: string, visitedLists?: readonly string[], selection?: FieldSelectionScope): {
     include: Record<string, unknown> | undefined;
     declaredOnly: DeclaredOnlyTree;
 };

package/dist/access/declared-dependencies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"declared-dependencies.d.ts","sourceRoot":"","sources":["../../src/access/declared-dependencies.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAGrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GAAG;IAC7B,2EAA2E;IAC3E,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACjB,6JAA6J;IAC7J,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CACzC,CAAA;AAED,wBAAgB,qBAAqB,IAAI,gBAAgB,CAExD;AAiBD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,MAAM,EAAE,CAS5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC/C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACzC,MAAM,EAAE,cAAc,GACrB;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAAC,YAAY,EAAE,gBAAgB,CAAA;CAAE,CAwClF"}
+{"version":3,"file":"declared-dependencies.d.ts","sourceRoot":"","sources":["../../src/access/declared-dependencies.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAErE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GAAG;IAC7B,2EAA2E;IAC3E,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACjB,6JAA6J;IAC7J,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CACzC,CAAA;AAED,wBAAgB,qBAAqB,IAAI,gBAAgB,CAExD;AA6BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACzC,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACnC,MAAM,EAAE,CAUV;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC/C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACzC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,MAAM,EACf,YAAY,GAAE,SAAS,MAAM,EAAc,EAC3C,SAAS,CAAC,EAAE,mBAAmB,GAC9B;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAAC,YAAY,EAAE,gBAAgB,CAAA;CAAE,CAkElF"}

package/dist/access/declared-dependencies.js

@@ -11,17 +11,37 @@ function isRelationshipFieldConfig(fieldConfig) {
         'ref' in fieldConfig &&
         !!fieldConfig.ref);
 }
+/** A plain object — excludes `null` and arrays, which `typeof x === 'object'` alone would admit. */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The explicit nested `include` on an include entry, if the entry is a structured object naming one. */
+function getExplicitInclude(value) {
+    if (!isPlainObject(value))
+        return undefined;
+    const { include } = value;
+    return isPlainObject(include) ? include : undefined;
+}
 /**
  * The deduped set of relation names declared via `needs` by fields on this
  * list that have a `resolveOutput` hook. A `needs` entry on a field without
  * one is inert — there is no hook to feed it to — so it contributes nothing
  * to fetch.
+ *
+ * `selectedFields`, when given, restricts the union to fields the read is
+ * actually going to return (ADR-0027) — a field a fragment did not select is
+ * never computed, so its declared relation is never fetched for it either.
+ * `undefined` means unrestricted: every field with a hook contributes,
+ * matching a bare or `include`-based read, which always returns every
+ * computed field on the list.
  */
-export function getDeclaredRelationNames(fieldConfigs) {
+export function getDeclaredRelationNames(fieldConfigs, selectedFields) {
     const names = new Set();
-    for (const fieldConfig of Object.values(fieldConfigs)) {
+    for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
         if (!fieldConfig?.hooks?.resolveOutput)
             continue;
+        if (selectedFields && !selectedFields.has(fieldName))
+            continue;
         for (const name of fieldConfig.needs ?? []) {
             names.add(name);
         }
@@ -30,15 +50,29 @@ export function getDeclaredRelationNames(fieldConfigs) {
 }
 /**
  * Fold this list's declared dependencies into `rawInclude`, recursing into
- * any EXPLICIT nested include the caller wrote so a related list's own
- * declared needs are satisfied too (see module doc comment).
+ * EVERY relation reached from here — whether it was just added to satisfy a
+ * declaration or was already present for another reason — so that list's own
+ * declared dependencies are satisfied too, wherever it's reached (see module
+ * doc comment).
  *
  * Returns `rawInclude` itself (same reference) when there is nothing to
  * fold, so a list with no `needs` fields and no caller include stays on the
  * exact bare-read path (ADR-0024) — untouched, not merely equivalent.
+ *
+ * `listKey` seeds the cycle guard at the root of a read; recursive calls
+ * extend it with each related list reached along THIS fold's own path.
+ *
+ * `selection`, when given, is the fragment scope this level was reached
+ * under (ADR-0027) — only fields it names contribute their `needs` (see
+ * `getDeclaredRelationNames`). It is `undefined` for a bare/`include`-based
+ * read (unrestricted: every field's `needs` folds in, unchanged from before
+ * ADR-0027) and for any branch reached only to satisfy a declaration — a
+ * relation added purely by this fold has no fragment scope of its own, so
+ * its own list folds unrestricted, exactly as it did before selectivity
+ * existed.
  */
-export function foldDeclaredDependencies(rawInclude, fieldConfigs, config) {
-    const declaredNames = getDeclaredRelationNames(fieldConfigs);
+export function foldDeclaredDependencies(rawInclude, fieldConfigs, config, listKey, visitedLists = [listKey], selection) {
+    const declaredNames = getDeclaredRelationNames(fieldConfigs, selection?.fields);
     if (declaredNames.length === 0 && !rawInclude) {
         return { include: rawInclude, declaredOnly: emptyDeclaredOnlyTree() };
     }
@@ -56,21 +90,37 @@ export function foldDeclaredDependencies(rawInclude, fieldConfigs, config) {
         const fieldConfig = fieldConfigs[key];
         if (!isRelationshipFieldConfig(fieldConfig))
             continue;
-        // A whole branch we just added is bare `true` — its own subtree auto-expands
-        // (see module doc comment), so there is no explicit nested include to recurse into.
-        if (declaredOnly.keys.has(key))
-            continue;
-        const entry = value;
-        if (!entry || typeof entry !== 'object' || !entry.include)
-            continue;
         const relatedConfig = getRelatedListConfig(fieldConfig.ref, config);
         if (!relatedConfig)
             continue;
-        const nested = foldDeclaredDependencies(entry.include, relatedConfig.listConfig.fields, config);
-        if (nested.include !== entry.include) {
-            merged[key] = { ...entry, include: nested.include };
+        // Defensive cycle guard (see module doc comment) — a DECLARATION-ADDED
+        // edge into a list already on this path stops here rather than recursing
+        // without bound. The value at `key` is left exactly as-is. The guard is
+        // deliberately not applied to an edge the request itself named: that
+        // recursion is bounded by the request's own finite literal and cannot
+        // loop, so stopping it would silently drop the folds beneath a request
+        // that merely revisits a list (e.g. `Post → author → posts`).
+        if (declaredOnly.keys.has(key) && visitedLists.includes(relatedConfig.listName))
+            continue;
+        // A branch added purely by the fold has no fragment scope of its own —
+        // it folds unrestricted, as before ADR-0027. A branch the request itself
+        // named (caller include or fragment) carries that name's own nested
+        // scope, if the fragment gave it one (a bare `true` selector leaves it
+        // `undefined` — also unrestricted, since the caller asked for
+        // "everything" there).
+        const nestedSelection = declaredOnly.keys.has(key) ? undefined : selection?.nested[key];
+        const explicitNested = getExplicitInclude(value);
+        const nested = foldDeclaredDependencies(explicitNested, relatedConfig.listConfig.fields, config, relatedConfig.listName, [...visitedLists, relatedConfig.listName], nestedSelection);
+        if (nested.include) {
+            merged[key] = {
+                ...(typeof value === 'object' && value ? value : {}),
+                include: nested.include,
+            };
         }
-        if (!isDeclaredOnlyTreeEmpty(nested.declaredOnly)) {
+        // A whole branch added purely by the fold above is stripped wholesale by
+        // field-visibility regardless of what's nested inside it, so it needs no
+        // individual nested-key tracking of its own.
+        if (!declaredOnly.keys.has(key) && !isDeclaredOnlyTreeEmpty(nested.declaredOnly)) {
             declaredOnly.nested[key] = nested.declaredOnly;
         }
     }

package/dist/access/declared-dependencies.js.map

@@ -1 +1 @@
-{"version":3,"file":"declared-dependencies.js","sourceRoot":"","sources":["../../src/access/declared-dependencies.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"declared-dependencies.js","sourceRoot":"","sources":["../../src/access/declared-dependencies.ts"],"names":[],"mappings":"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"}

package/dist/access/declared-dependencies.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=declared-dependencies.test.d.ts.map

package/dist/access/declared-dependencies.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-dependencies.test.d.ts","sourceRoot":"","sources":["../../src/access/declared-dependencies.test.ts"],"names":[],"mappings":""}

package/dist/access/declared-dependencies.test.js

@@ -0,0 +1,226 @@
+import { describe, it, expect } from 'vitest';
+import { foldDeclaredDependencies, emptyDeclaredOnlyTree } from './declared-dependencies.js';
+/**
+ * Unit coverage for `foldDeclaredDependencies` (ADR-0025), focused on the
+ * behaviour ADR-0026 requires of it once the read pipeline stopped
+ * auto-expanding a named relation's own subtree: a declared dependency no
+ * longer rides that expansion "for free" and must be folded recursively —
+ * at every level a field is computed, however that level was reached
+ * (declaration-added, caller-named bare, or caller-named with its own nested
+ * include).
+ *
+ * End-to-end coverage of the fold feeding an actual read (mocked Prisma, real
+ * `resolveOutput` hooks) lives in `tests/needs-declared-dependencies.test.ts`;
+ * these tests exercise the fold function directly so a regression here fails
+ * fast with a small, precise reproduction.
+ */
+function relField(ref, many = false) {
+    return { type: 'relationship', ref, many };
+}
+function virtualNeeds(needs) {
+    return {
+        type: 'virtual',
+        needs,
+        hooks: { resolveOutput: () => 'x' },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal field config for unit test
+    };
+}
+describe('foldDeclaredDependencies', () => {
+    it('returns the exact same reference when there is nothing to fold', () => {
+        const fields = { name: { type: 'text' } };
+        const config = { db: { provider: 'sqlite' }, lists: {} };
+        const result = foldDeclaredDependencies(undefined, fields, config, 'List');
+        expect(result.include).toBeUndefined();
+        expect(result.declaredOnly).toEqual(emptyDeclaredOnlyTree());
+    });
+    it('folds a declaration-added bare relation whose own related list has further needs', () => {
+        // Order.total needs lineItems (declaration-added, no caller include at
+        // all). LineItem.summary needs product. Without recursing into the
+        // declaration-added branch, `product` would never be fetched, and
+        // LineItem.summary would silently compute over `undefined`.
+        const config = {
+            db: { provider: 'sqlite' },
+            lists: {
+                Order: {
+                    fields: {
+                        lineItems: relField('LineItem.order', true),
+                        total: virtualNeeds(['lineItems']),
+                    },
+                },
+                LineItem: {
+                    fields: { product: relField('Product'), summary: virtualNeeds(['product']) },
+                },
+                Product: { fields: { name: { type: 'text' } } },
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+        };
+        const result = foldDeclaredDependencies(undefined, config.lists.Order.fields, config, 'Order');
+        expect(result.include).toEqual({ lineItems: { include: { product: true } } });
+        // The whole `lineItems` branch is declaration-only at Order's level, so it
+        // needs no fine-grained nested tracking — the entire branch is stripped
+        // regardless of what's nested inside it.
+        expect(result.declaredOnly.keys.has('lineItems')).toBe(true);
+        expect(result.declaredOnly.nested.lineItems).toBeUndefined();
+    });
+    it('folds a caller-named BARE relation whose related list has its own needs, tracking the addition for fine-grained stripping', () => {
+        // The caller explicitly asked for `lineItems` (bare) — NOT declaration-only
+        // at Order's level — but LineItem's own `product` still has to be folded
+        // in for LineItem.summary's hook. Because the caller DID ask for
+        // `lineItems`, `product` must be tracked as declaration-only ONE LEVEL
+        // DOWN so it (and only it) gets stripped from each returned line item.
+        const config = {
+            db: { provider: 'sqlite' },
+            lists: {
+                Order: {
+                    fields: {
+                        lineItems: relField('LineItem.order', true),
+                        total: virtualNeeds(['lineItems']),
+                    },
+                },
+                LineItem: {
+                    fields: {
+                        product: relField('Product'),
+                        tag: relField('Tag'),
+                        summary: virtualNeeds(['product']),
+                    },
+                },
+                Product: { fields: { name: { type: 'text' } } },
+                Tag: { fields: { name: { type: 'text' } } },
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+        };
+        const result = foldDeclaredDependencies({ lineItems: true }, config.lists.Order.fields, config, 'Order');
+        expect(result.include).toEqual({ lineItems: { include: { product: true } } });
+        // `lineItems` itself is caller-named, not declaration-only...
+        expect(result.declaredOnly.keys.has('lineItems')).toBe(false);
+        // ...but `product`, nested beneath it, IS — so it gets stripped from each
+        // line item while `lineItems` (and its other fields, e.g. `tag`) survive.
+        expect(result.declaredOnly.nested.lineItems?.keys.has('product')).toBe(true);
+    });
+    it("recurses into an explicit caller-nested include so the nested list's own needs are satisfied there too", () => {
+        const config = {
+            db: { provider: 'sqlite' },
+            lists: {
+                Order: { fields: { lineItems: relField('LineItem.order', true) } },
+                LineItem: {
+                    fields: {
+                        product: relField('Product'),
+                        tag: relField('Tag'),
+                        summary: virtualNeeds(['product']),
+                    },
+                },
+                Product: { fields: { name: { type: 'text' } } },
+                Tag: { fields: { name: { type: 'text' } } },
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+        };
+        const result = foldDeclaredDependencies({ lineItems: { include: { tag: true } } }, config.lists.Order.fields, config, 'Order');
+        expect(result.include).toEqual({ lineItems: { include: { tag: true, product: true } } });
+        expect(result.declaredOnly.nested.lineItems?.keys.has('product')).toBe(true);
+        expect(result.declaredOnly.nested.lineItems?.keys.has('tag')).toBe(false);
+    });
+    it('does not fold anything beneath a relation whose related list has no needs of its own', () => {
+        const config = {
+            db: { provider: 'sqlite' },
+            lists: {
+                Order: { fields: { customer: relField('Customer') } },
+                Customer: { fields: { name: { type: 'text' } } },
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+        };
+        const result = foldDeclaredDependencies({ customer: true }, config.lists.Order.fields, config, 'Order');
+        // Untouched — no needs anywhere in reach, so the bare relation stays bare.
+        expect(result.include).toEqual({ customer: true });
+        expect(result.declaredOnly).toEqual(emptyDeclaredOnlyTree());
+    });
+    it("folds a revisited list's own needs beneath a relation the request named", () => {
+        // The request names Post → author → posts, revisiting Post. Nothing here
+        // can loop — the include is a finite literal the caller wrote out — so the
+        // fold must keep going and satisfy Post.blurb's `needs` at THAT level too.
+        // Guarding a caller-named edge on list identity would stop the fold at
+        // `posts` and leave `blurb` computing over an undefined `tags`.
+        const config = {
+            db: { provider: 'sqlite' },
+            lists: {
+                Post: {
+                    fields: {
+                        author: relField('User.posts'),
+                        comments: relField('Comment', true),
+                        tags: relField('Tag', true),
+                        blurb: virtualNeeds(['tags']),
+                    },
+                },
+                User: { fields: { posts: relField('Post.author', true) } },
+                Comment: { fields: { body: { type: 'text' } } },
+                Tag: { fields: { label: { type: 'text' } } },
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+        };
+        const result = foldDeclaredDependencies({ author: { include: { posts: { include: { comments: true } } } } }, config.lists.Post.fields, config, 'Post');
+        expect(result.include).toEqual({
+            tags: true,
+            author: { include: { posts: { include: { comments: true, tags: true } } } },
+        });
+        // Only the nested `tags` needs fine-grained tracking: the root-level one is
+        // declaration-only at this level (stripped wholesale), while the nested one
+        // sits inside branches the caller named and must be stripped individually.
+        expect(result.declaredOnly.keys.has('tags')).toBe(true);
+        expect(result.declaredOnly.nested.author?.nested.posts?.keys.has('tags')).toBe(true);
+        expect(result.declaredOnly.nested.author?.nested.posts?.keys.has('comments')).toBe(false);
+    });
+    it("folds a self-referential relation's own needs when the request names it", () => {
+        // `parent` points back at Category itself. The request named it, so the
+        // fold must satisfy Category's own `needs` beneath it — `depth` is computed
+        // on the parent row too.
+        const config = {
+            db: { provider: 'sqlite' },
+            lists: {
+                Category: {
+                    fields: {
+                        parent: relField('Category.children'),
+                        children: relField('Category.parent', true),
+                        depth: virtualNeeds(['children']),
+                    },
+                },
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+        };
+        const result = foldDeclaredDependencies({ parent: true }, config.lists.Category.fields, config, 'Category');
+        // `children` folds in at the root AND beneath the caller-named `parent`.
+        // The fold beneath `parent` stops there: `children` is declaration-added,
+        // so the guard applies to its own onward edge back into Category.
+        expect(result.include).toEqual({
+            parent: { include: { children: true } },
+            children: true,
+        });
+        expect(result.declaredOnly.keys.has('children')).toBe(true);
+        expect(result.declaredOnly.nested.parent?.keys.has('children')).toBe(true);
+    });
+    it('defensively terminates a two-list mutual `needs` cycle instead of recursing without bound', () => {
+        // Order.total needs lineItems; LineItem.orderRef needs order — a cycle
+        // `validateNeedsClosureDepth` (needs-closure.ts) rejects at generate time.
+        // This constructs it directly to exercise the fold's OWN defensive guard,
+        // independent of that generate-time backstop.
+        const config = {
+            db: { provider: 'sqlite' },
+            lists: {
+                Order: {
+                    fields: {
+                        lineItems: relField('LineItem.order', true),
+                        total: virtualNeeds(['lineItems']),
+                    },
+                },
+                LineItem: {
+                    fields: { order: relField('Order.lineItems'), orderRef: virtualNeeds(['order']) },
+                },
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+        };
+        const result = foldDeclaredDependencies(undefined, config.lists.Order.fields, config, 'Order');
+        // Terminates (would hang/stack-overflow without the guard) and still
+        // produces a usable, finite include: `lineItems` folds in, but `order`
+        // beneath it stops at a flat fetch rather than looping back to `lineItems` again.
+        expect(result.include).toEqual({ lineItems: { include: { order: true } } });
+    });
+});
+//# sourceMappingURL=declared-dependencies.test.js.map

package/dist/access/declared-dependencies.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-dependencies.test.js","sourceRoot":"","sources":["../../src/access/declared-dependencies.test.ts"],"names":[],"mappings":"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"}

package/dist/access/depth-limits.d.ts

@@ -1,12 +1,13 @@
 /**
- * Maximum nesting depth of relation `include`s that the Access Filter
- * (`buildIncludeWithAccessControl`) will auto-scope on a read.
+ * Maximum nesting depth of relation `include`s the Access Filter
+ * (`buildAccessScopedInclude`) will scope on a read.
  *
- * Security implication: this is an access-control boundary, not just a cost
- * bound. Past this depth the engine cannot compute a row/field scope for a
- * relation, so a caller-supplied `include` naming a relation at or beyond it
- * must be treated as a denial (see `AccessScopeDepthExceededError`) rather
- * than passed through unscoped — see ADR-0022 and issue #830.
+ * Since ADR-0026 made the read pipeline caller-directed, this is a COST
+ * limit, not an access-control boundary: nothing walks the relationship
+ * graph unprompted anymore, so there is no unscoped tree to fail open on. A
+ * request naming a relation at or beyond this depth still throws
+ * `AccessScopeDepthExceededError` (ADR-0022, issue #830) — the engine
+ * declines to serve a tree this expensive, not because it cannot scope one.
  */
 export declare const READ_INCLUDE_MAX_DEPTH = 5;
 /**

package/dist/access/depth-limits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"depth-limits.d.ts","sourceRoot":"","sources":["../../src/access/depth-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAA"}
+{"version":3,"file":"depth-limits.d.ts","sourceRoot":"","sources":["../../src/access/depth-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAA"}

package/dist/access/depth-limits.js

@@ -1,12 +1,13 @@
 /**
- * Maximum nesting depth of relation `include`s that the Access Filter
- * (`buildIncludeWithAccessControl`) will auto-scope on a read.
+ * Maximum nesting depth of relation `include`s the Access Filter
+ * (`buildAccessScopedInclude`) will scope on a read.
  *
- * Security implication: this is an access-control boundary, not just a cost
- * bound. Past this depth the engine cannot compute a row/field scope for a
- * relation, so a caller-supplied `include` naming a relation at or beyond it
- * must be treated as a denial (see `AccessScopeDepthExceededError`) rather
- * than passed through unscoped — see ADR-0022 and issue #830.
+ * Since ADR-0026 made the read pipeline caller-directed, this is a COST
+ * limit, not an access-control boundary: nothing walks the relationship
+ * graph unprompted anymore, so there is no unscoped tree to fail open on. A
+ * request naming a relation at or beyond this depth still throws
+ * `AccessScopeDepthExceededError` (ADR-0022, issue #830) — the engine
+ * declines to serve a tree this expensive, not because it cannot scope one.
  */
 export const READ_INCLUDE_MAX_DEPTH = 5;
 /**

package/dist/access/depth-limits.js.map

@@ -1 +1 @@
-{"version":3,"file":"depth-limits.js","sourceRoot":"","sources":["../../src/access/depth-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAA;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAA"}
+{"version":3,"file":"depth-limits.js","sourceRoot":"","sources":["../../src/access/depth-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAA;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAA"}

package/dist/access/errors.d.ts

@@ -1,14 +1,18 @@
 /**
  * Thrown when a caller-supplied `include` names a relation nested deeper than
- * the Access Filter can scope (see `READ_INCLUDE_MAX_DEPTH`). Deliberately
- * distinct from `ValidationError`: this is not bad user input, it is the
- * engine refusing to return data it cannot prove is row/field scoped. Code
- * that catches `ValidationError` to report form errors must not silently
- * swallow this.
+ * `READ_INCLUDE_MAX_DEPTH`. Deliberately distinct from `ValidationError`: this
+ * is not bad user input, it is the engine declining to serve a tree this
+ * expensive. Code that catches `ValidationError` to report form errors must
+ * not silently swallow this.
  *
- * Only an explicit caller selection past the depth cap triggers this — the
- * auto-include silently stopping at the cap (no caller `include` involved)
- * never throws. See ADR-0022 and issue #830.
+ * Only an explicit request naming something at or past the cap triggers this
+ * — a read that simply doesn't reach this deep never throws. Before
+ * ADR-0026 made the read pipeline caller-directed, this cap was the engine's
+ * last line of defense against returning a relation it could not prove was
+ * row/field scoped (ADR-0022, issue #830); a request naming anything at this
+ * depth is now scoped exactly like every other named relation; the cap
+ * exists solely to bound how deep a request may cost the engine to serve. See
+ * ADR-0026 and `docs/adr/0022-access-control-fails-closed-when-it-cannot-scope.md`.
  */
 export declare class AccessScopeDepthExceededError extends Error {
     listKey: string;

package/dist/access/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/access/errors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IAC/C,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IAEpB,YAAY,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAW3D;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IACzC,KAAK,EAAE,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAE9D,YAAY,KAAK,EAAE,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,EAUlE;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/access/errors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IAC/C,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IAEpB,YAAY,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAW3D;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IACzC,KAAK,EAAE,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAE9D,YAAY,KAAK,EAAE,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,EAUlE;CACF"}