@opensaas/stack-core 0.33.0 → 0.34.0

package/src/access/field-visibility.ts

@@ -2,6 +2,15 @@ import type { Session, AccessContext } from './types.js'
 import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
 import { getRelatedListConfig } from './engine.js'
 import { checkFieldAccess } from './field-access.js'
+import { RESOLVE_CHAIN_MAX_LENGTH } from './depth-limits.js'
+import { ResolveOutputCycleError } from './errors.js'
+// NOTE: `context/index.ts` imports `filterReadableFields` from this module
+// (via the `access/index.ts` barrel) — this is an intentional cyclic
+// dependency, the same shape and for the same reason as the one documented in
+// `context/write-pipeline.ts`. `buildDbDelegate` is only INVOKED when a
+// `resolveOutput` hook actually runs (never during module evaluation), so by
+// the time it runs the export is fully initialised.
+import { buildDbDelegate } from '../context/index.js'
 
 /**
  * Field Visibility — phase 2 of the two-phase read (post-query).
@@ -36,6 +45,44 @@ type FieldVisibilityArgs = {
   context: AccessContext & { _isSudo?: boolean }
 }
 
+/**
+ * Derive the context passed to a single `resolveOutput` hook invocation: a
+ * NEW context object whose `_resolveOutputChain` extends the caller's chain
+ * with this hook's own `(list, field)` link. The chain is never mutated in
+ * place — this is what lets concurrent hook invocations (e.g. sibling rows in
+ * a to-many relation, filtered via `Promise.all`) each see their own chain
+ * rather than racing on one shared value (ADR-0023).
+ *
+ * A plain `{ ...context, _resolveOutputChain }` spread is not enough on its
+ * own: `context.db`'s operations capture their `context` at construction
+ * (see `populateDbDelegate`), so a hook that calls `context.db.x.findMany(…)`
+ * would otherwise reach the ORIGINAL closures — bound to the ORIGINAL
+ * context — and its read would silently fall back to the un-extended chain,
+ * defeating the cycle guard entirely. Rebuilding `db` via `buildDbDelegate`
+ * against the derived context is what makes a hook-issued read's own nested
+ * hooks actually observe the extended chain.
+ *
+ * `config` is required to rebuild `db`; callers that cannot supply one (e.g. a
+ * narrow unit test exercising field access in isolation) still get a correct
+ * chain for THIS hook's own cycle/cap check, but a read that hook issues
+ * would not carry the chain any further — those callers are not exercising
+ * the read pipeline, so there is nothing for it to reach.
+ */
+function deriveResolveOutputContext(
+  context: AccessContext & { _isSudo?: boolean },
+  link: { listKey: string; fieldKey: string },
+  config: OpenSaasConfig | undefined,
+): AccessContext & { _isSudo?: boolean } {
+  const derived: AccessContext & { _isSudo?: boolean } = {
+    ...context,
+    _resolveOutputChain: [...context._resolveOutputChain, link],
+  }
+  if (config) {
+    derived.db = buildDbDelegate(config, context.prisma, derived)
+  }
+  return derived
+}
+
 /**
  * The core Field Visibility step for a single field: check read access and, if
  * granted, produce the output value by running any `resolveOutput` hook.
@@ -58,8 +105,9 @@ async function resolveReadableFieldValue(params: {
   hookItem: Record<string, unknown>
   listKey: string | undefined
   args: FieldVisibilityArgs
+  config: OpenSaasConfig | undefined
 }): Promise<{ readable: false } | { readable: true; value: unknown }> {
-  const { fieldConfig, fieldName, value, accessItem, hookItem, listKey, args } = params
+  const { fieldConfig, fieldName, value, accessItem, hookItem, listKey, args, config } = params
 
   // Check field access (checkFieldAccess already handles sudo mode)
   const canRead = await checkFieldAccess(fieldConfig?.access, 'read', {
@@ -76,25 +124,44 @@ async function resolveReadableFieldValue(params: {
     // Cast to runtime type for generic execution
     // At runtime, the hook will receive the correct value type for the field
     const hook = fieldConfig.hooks.resolveOutput as unknown as ResolveOutputHookRuntime
-    // Increment depth counter to prevent infinite loops from hooks making DB queries
-    // that include relationships back to the same entity
-    args.context._resolveOutputCounter.depth++
-    try {
-      // Use Promise.resolve() to handle both sync and async hooks
-      const resolved = await Promise.resolve(
-        hook({
-          value,
-          operation: 'query',
-          fieldName,
-          listKey,
-          item: hookItem,
-          context: args.context,
-        }),
+    const link = { listKey, fieldKey: fieldName }
+    const chain = args.context._resolveOutputChain
+
+    // Cycle guard: a hook that would re-enter a (list, field) pair already on
+    // its own chain cannot terminate — refuse loudly rather than recurse
+    // until the process runs out of memory (issue #844, ADR-0023).
+    const alreadyOnChain = chain.some(
+      (entry) => entry.listKey === link.listKey && entry.fieldKey === link.fieldKey,
+    )
+    if (alreadyOnChain) {
+      throw new ResolveOutputCycleError([...chain, link])
+    }
+
+    // Cost cap: a chain this long is refused only as a cost limit, never a
+    // correctness one — an acyclic chain that works today can legitimately
+    // reach this. Omit the field and warn instead of throwing.
+    if (chain.length >= RESOLVE_CHAIN_MAX_LENGTH) {
+      const path = [...chain, link].map((entry) => `${entry.listKey}.${entry.fieldKey}`).join(' → ')
+      console.warn(
+        `resolveOutput: omitting "${listKey}.${fieldName}" — its resolve chain exceeded ` +
+          `RESOLVE_CHAIN_MAX_LENGTH (${RESOLVE_CHAIN_MAX_LENGTH}): ${path}. This is a cost limit, ` +
+          `not an access denial.`,
       )
-      return { readable: true, value: resolved }
-    } finally {
-      args.context._resolveOutputCounter.depth--
+      return { readable: false }
     }
+
+    // Use Promise.resolve() to handle both sync and async hooks
+    const resolved = await Promise.resolve(
+      hook({
+        value,
+        operation: 'query',
+        fieldName,
+        listKey,
+        item: hookItem,
+        context: deriveResolveOutputContext(args.context, link, config),
+      }),
+    )
+    return { readable: true, value: resolved }
   }
 
   return { readable: true, value }
@@ -227,6 +294,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       hookItem: workingItem,
       listKey,
       args,
+      config,
     })
 
     if (result.readable) {
@@ -265,6 +333,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       hookItem: filtered,
       listKey,
       args,
+      config,
     })
 
     if (result.readable) {

package/src/access/index.ts

@@ -33,3 +33,5 @@ export type { AccessIncludeResult } from './access-filter.js'
 export { filterReadableFields } from './field-visibility.js'
 // Thrown when a caller include reaches past the depth the Access Filter can scope.
 export { AccessScopeDepthExceededError } from './errors.js'
+// Thrown when a resolveOutput hook's own resolve chain cycles back into itself.
+export { ResolveOutputCycleError } from './errors.js'

package/src/access/multi-column-read-write.test.ts

@@ -52,7 +52,7 @@ function makeContext(overrides: { isSudo?: boolean } = {}): AccessContext {
   return {
     session: null,
     _isSudo: overrides.isSudo ?? false,
-    _resolveOutputCounter: { depth: 0 },
+    _resolveOutputChain: [],
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal context for unit test
   } as any
 }

package/src/access/relationship-count.test.ts

@@ -51,7 +51,7 @@ function makeContext(
   return {
     session: null,
     _isSudo: false,
-    _resolveOutputCounter: { depth: 0 },
+    _resolveOutputChain: [],
     db: findMany ? { user: { findMany } } : {},
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal context for unit test
   } as any

package/src/access/relationship-label-filter.test.ts

@@ -46,7 +46,7 @@ function makeContext(): AccessContext {
   return {
     session: null,
     _isSudo: false,
-    _resolveOutputCounter: { depth: 0 },
+    _resolveOutputChain: [],
     db: {},
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal context for unit test
   } as any

package/src/access/types.ts

@@ -290,12 +290,19 @@ export interface AccessContext<TPrisma extends PrismaClientLike = PrismaClientLi
   plugins: Record<string, unknown>
   _isSudo: boolean
   /**
-   * Internal mutable counter to track resolveOutput hook depth.
-   * When depth > 0, we skip auto-including relationships to prevent infinite loops
-   * when hooks make database queries that include relationships back to the original entity.
-   * We use a mutable object so that spreading the context preserves the reference.
+   * The resolve chain: the ordered sequence of `resolveOutput` hook
+   * `(listKey, fieldKey)` pairs a read has entered on the way to here. A
+   * top-level read starts with an empty chain. Each hook invocation is given
+   * a NEW context whose chain extends this one by its own pair — the chain is
+   * never mutated in place, so concurrent hook invocations (e.g. sibling rows
+   * in a to-many relation processed via `Promise.all`) never observe each
+   * other's chain. A hook that would re-enter a pair already on its own chain
+   * is refused (`ResolveOutputCycleError`) rather than left to recurse
+   * forever; a chain longer than `RESOLVE_CHAIN_MAX_LENGTH` is a separate,
+   * non-fatal cost limit. See ADR-0023 and the "Resolve chain" glossary entry
+   * in CONTEXT.md.
    */
-  _resolveOutputCounter: { depth: number }
+  _resolveOutputChain: readonly { listKey: string; fieldKey: string }[]
 }
 
 /**

package/src/context/index.ts

@@ -434,7 +434,7 @@ export function getContext<
     // client, otherwise start empty and populate via plugin runtimes below.
     plugins: _sharedPlugins ?? {},
     _isSudo,
-    _resolveOutputCounter: { depth: 0 },
+    _resolveOutputChain: [],
   }
 
   // Create access-controlled operations for each list, populating `db` in place.

package/src/context/write-pipeline.ts

@@ -297,9 +297,10 @@ export async function runWritePipeline<TPrisma extends PrismaClientLike>(
  * construction, so the request-time `context.db` is bound to the ORIGINAL
  * client. We rebuild the delegates against `tx` via {@link buildDbDelegate},
  * reusing the request context's `session`, `storage`, `plugins`, `_isSudo`, and
- * the shared `_resolveOutputCounter` reference (so resolveOutput depth tracking
- * is preserved). Plugin runtimes are NOT re-executed; the existing
- * `plugins` object is reused as-is.
+ * the current `_resolveOutputChain` value (carried through unchanged, so a
+ * write issued from inside a `resolveOutput` hook keeps that hook's chain).
+ * Plugin runtimes are NOT re-executed; the existing `plugins` object is
+ * reused as-is.
  */
 function bindContextToTransaction<TPrisma extends PrismaClientLike>(
   args: WritePipelineArgs<TPrisma>,
@@ -313,7 +314,7 @@ function bindContextToTransaction<TPrisma extends PrismaClientLike>(
     storage: context.storage,
     plugins: context.plugins,
     _isSudo: context._isSudo,
-    _resolveOutputCounter: context._resolveOutputCounter,
+    _resolveOutputChain: context._resolveOutputChain,
   }
   // Rebuild the db delegate against `tx`, pointing back at `txContext` so hooks
   // reached through it also see the transactional context.

package/src/index.ts

@@ -68,6 +68,11 @@ export { ValidationError } from './hooks/index.js'
 // a user-input validation failure.
 export { AccessScopeDepthExceededError } from './access/index.js'
 
+// Thrown by a `resolveOutput` hook whose own read cycles back into a
+// `(list, field)` pair already on its resolve chain (see ADR-0023). Distinct
+// from `ValidationError` for the same reason as `AccessScopeDepthExceededError`.
+export { ResolveOutputCycleError } from './access/index.js'
+
 // Field self-containment validation — checks each field implements the
 // generation contract (getPrismaType / getTypeScriptType / getZodSchema, or
 // getPrismaRelation for relationships) so a misimplemented field fails early

package/tests/access-relationships.test.ts

@@ -23,7 +23,7 @@ describe('Relationship Access Control', () => {
     },
     plugins: {},
     _isSudo: false,
-    _resolveOutputCounter: { depth: 0 },
+    _resolveOutputChain: [],
   }
 
   describe('getRelatedListConfig', () => {

package/tests/context.test.ts

@@ -1430,7 +1430,7 @@ describe('getContext', () => {
       // Regression for issue #830: a read issued from inside a `resolveOutput`
       // hook used to lose relation row scoping ENTIRELY — `buildIncludeWithAccessControl`
       // returned a whole-object `undefined` for the inner read (any
-      // `_resolveOutputCounter.depth > 0`), which `mergeIncludeWithAccessControl`
+      // `_resolveOutputChain.length > 0`), which `mergeIncludeWithAccessControl`
       // treated as "nothing to merge against" and passed the caller's include
       // through completely unscoped. The fix scopes each immediate relation with
       // its own access `where` while still not auto-EXPANDING into that
@@ -1439,7 +1439,7 @@ describe('getContext', () => {
       describe('scopes (without expanding) a caller include used inside a resolveOutput hook (#830)', () => {
         // Build an Author config with a virtual field whose resolveOutput issues a
         // read WITH an explicit include. While that hook runs,
-        // _resolveOutputCounter.depth > 0.
+        // _resolveOutputChain.length > 0.
         function configWithResolveOutputProbe(
           callerInclude: Record<string, unknown>,
           capture: (include: unknown) => void,

package/tests/default-value-create.test.ts

@@ -33,7 +33,7 @@ function makeContext(): AccessContext {
     storage: {} as any,
     plugins: {},
     _isSudo: false,
-    _resolveOutputCounter: { depth: 0 },
+    _resolveOutputChain: [],
   }
 }
 

package/tests/hook-pipeline.test.ts

@@ -37,7 +37,7 @@ function makeContext(): AccessContext {
     storage: {} as any,
     plugins: {},
     _isSudo: false,
-    _resolveOutputCounter: { depth: 0 },
+    _resolveOutputChain: [],
   }
 }
 

package/tests/nav-count.test.ts

@@ -43,7 +43,7 @@ function makeContext(counts: Record<string, number>): {
     storage: {},
     plugins: {},
     _isSudo: false,
-    _resolveOutputCounter: { depth: 0 },
+    _resolveOutputChain: [],
   } as unknown as AccessContext
   return { context, spies }
 }
@@ -168,7 +168,7 @@ describe('resolveNavCounts', () => {
       storage: {},
       plugins: {},
       _isSudo: false,
-      _resolveOutputCounter: { depth: 0 },
+      _resolveOutputChain: [],
     } as unknown as AccessContext
 
     const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})