@opensaas/stack-core 0.39.2 → 0.41.0

package/src/context/index.ts

@@ -10,10 +10,18 @@ import {
   foldDeclaredDependencies,
   validateQueryKeys,
   validateQueryFieldReadAccess,
+  resolveToOneAccessVisibility,
+  emptyToOneAccessFilterTree,
+  emptyCountAccessDenialTree,
+} from '../access/index.js'
+import type {
+  DeclaredOnlyTree,
+  ToOneAccessFilterTree,
+  CountAccessDenialTree,
 } from '../access/index.js'
-import type { DeclaredOnlyTree } from '../access/index.js'
 import { ValidationError, DatabaseError } from '../hooks/index.js'
 import { getDbKey } from '../lib/case-utils.js'
+import { uniqueConstraintOf } from '../lib/prisma-errors.js'
 import type { PrismaClientLike } from '../access/types.js'
 import { buildInclude, pickFields, isFragment, buildFieldSelectionScope } from '../query/index.js'
 import type { FieldSelection, FieldSelectionScope } from '../query/index.js'
@@ -202,6 +210,14 @@ function getDefaultData(listConfig: ListConfig<any>): Record<string, unknown> {
   return data
 }
 
+// A camelCase field name (e.g. a relationship's `tenantId` foreign key) needs
+// its word boundary split before title-casing, or it reads as one run-together
+// word ("Tenantid") in a user-facing unique-constraint message.
+function humanizeFieldName(fieldName: string): string {
+  const spaced = fieldName.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1)
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 function parsePrismaError(error: unknown, listConfig: ListConfig<any>): Error {
   if (
@@ -215,22 +231,22 @@ function parsePrismaError(error: unknown, listConfig: ListConfig<any>): Error {
 
     // P2002 is Prisma's unique constraint violation code.
     if (prismaError.code === 'P2002') {
-      const target = prismaError.meta?.target
+      const target = uniqueConstraintOf(prismaError)?.fields
       const fieldErrors: Record<string, string> = {}
 
-      if (target && Array.isArray(target)) {
+      if (target && target.length > 0) {
         for (const fieldName of target) {
           const fieldConfig = listConfig.fields[fieldName]
-          const label = fieldName.charAt(0).toUpperCase() + fieldName.slice(1)
 
           if (fieldConfig) {
-            fieldErrors[fieldName] = `This ${label.toLowerCase()} is already in use`
+            fieldErrors[fieldName] =
+              `This ${humanizeFieldName(fieldName).toLowerCase()} is already in use`
           } else {
             fieldErrors[fieldName] = `This value is already in use`
           }
         }
 
-        const fieldLabels = target.map((f) => f.charAt(0).toUpperCase() + f.slice(1)).join(', ')
+        const fieldLabels = target.map(humanizeFieldName).join(', ')
         return new DatabaseError(
           `${fieldLabels} must be unique. The value you entered is already in use.`,
           fieldErrors,
@@ -293,7 +309,8 @@ interface TransactionCapable<TPrisma> {
  *
  * Exposes the secured `db` delegate plus the session, raw `prisma`, storage,
  * plugin services, the generic `serverAction` handler, `sudo()` (bypasses access
- * control but still runs hooks), and `transaction()` (interactive, hook-firing
+ * control but still runs hooks), `withSession()` (substitutes the session but
+ * still runs access control), and `transaction()` (interactive, hook-firing
  * transaction). All access-checked operations run their list/field hooks.
  */
 export interface StackContext<TPrisma extends PrismaClientLike = PrismaClientLike> {
@@ -329,7 +346,33 @@ export interface StackContext<TPrisma extends PrismaClientLike = PrismaClientLik
     options?: TransactionOptions,
   ) => Promise<T>
   sudo: () => StackContext<TPrisma>
+  /**
+   * Derive a context identical to this one except for its session, reusing
+   * the already-resolved config and this context's own client (including a
+   * transaction client — a call inside `context.transaction()` stays in that
+   * transaction) and storage.
+   *
+   * **This is not an authorisation.** It substitutes who hooks and access
+   * control see; it does not change what they decide. The derived context
+   * can do exactly what any context built with `session` directly could
+   * do — access rules still evaluate against the new session. The caller is
+   * responsible for deciding who may invoke this.
+   *
+   * Orthogonal to `sudo()`: `withSession(s)` preserves the receiver's sudo
+   * state (elevated stays elevated), so `context.withSession(s).sudo()` and
+   * `context.sudo().withSession(s)` are equivalent.
+   */
+  withSession: (session: Session | null) => StackContext<TPrisma>
   _isSudo: boolean
+  /**
+   * @internal Present so a hook-bound `StackContext` (issue #1176) satisfies
+   * {@link AccessContext} and can be threaded through the same internal
+   * write-pipeline/access plumbing that a plain `AccessContext` is — see
+   * `_resolveOutputChain` on `AccessContext` for what this tracks.
+   */
+  _resolveOutputChain: readonly { listKey: string; fieldKey: string }[]
+  /** @internal See `_transactionOwner` on `AccessContext`. */
+  _transactionOwner?: TransactionRegistry
 }
 
 /**
@@ -377,6 +420,11 @@ export function getContext<
   // owner's callback body, carry the deferral registry so writes reached
   // through this context join it instead of firing afterTransaction eagerly.
   _transactionOwner?: TransactionRegistry,
+  // Internal (ADR-0023, issue #1176): when rebuilding the context for a
+  // hook-bound write (or a derived `sudo()`/`withSession()` of one), carry the
+  // resolve chain forward so a write issued from inside a `resolveOutput` hook
+  // keeps that hook's cycle-guard chain instead of resetting to empty.
+  _resolveOutputChain?: readonly { listKey: string; fieldKey: string }[],
 ): StackContext<TPrisma> {
   // Broad type to allow dynamic model access; populated by populateDbDelegate below.
   const db: Record<string, unknown> = {}
@@ -411,7 +459,7 @@ export function getContext<
     // client, otherwise start empty and populate via plugin runtimes below.
     plugins: _sharedPlugins ?? {},
     _isSudo,
-    _resolveOutputChain: [],
+    _resolveOutputChain: _resolveOutputChain ?? [],
     _transactionOwner,
   }
 
@@ -762,6 +810,28 @@ export function getContext<
       // ADR-0028: a sudo write issued from inside an owned transaction (e.g.
       // `tx.sudo().db.x.create()`) must still defer to that owner.
       context._transactionOwner,
+      // #1176: carry the resolve chain forward so a `context.sudo()` called
+      // from inside a `resolveOutput` hook keeps that hook's cycle-guard
+      // chain (ADR-0023) rather than resetting to empty.
+      context._resolveOutputChain,
+    )
+  }
+
+  // Substitutes the session; access control and hooks still run against it
+  // (orthogonal to `sudo`, so the receiver's sudo state is preserved).
+  function withSession(newSession: Session | null): StackContext<TPrisma> {
+    return getContext(
+      config,
+      prisma,
+      newSession,
+      context.storage,
+      _isSudo,
+      undefined,
+      // ADR-0028: a write issued from inside an owned transaction (e.g.
+      // `tx.withSession(s).db.x.create()`) must still defer to that owner.
+      context._transactionOwner,
+      // #1176: see the identical comment in `sudo()` above.
+      context._resolveOutputChain,
     )
   }
 
@@ -802,6 +872,7 @@ export function getContext<
               _isSudo,
               context.plugins,
               registry,
+              context._resolveOutputChain,
             ),
           )
         : (client.$transaction(
@@ -815,6 +886,7 @@ export function getContext<
                   _isSudo,
                   context.plugins,
                   registry,
+                  context._resolveOutputChain,
                 ),
               ),
             options,
@@ -831,8 +903,15 @@ export function getContext<
     plugins: context.plugins,
     serverAction,
     sudo,
+    withSession,
     transaction,
     _isSudo,
+    // #1176: carried so a `StackContext` structurally satisfies `AccessContext`
+    // and can be handed, unchanged, to the internal write-pipeline/hook
+    // plumbing that a plain `AccessContext` was built for — see
+    // `bindContextToTransaction` in `write-pipeline.ts`.
+    _resolveOutputChain: context._resolveOutputChain,
+    _transactionOwner: context._transactionOwner,
   }
   return returned
 }
@@ -909,11 +988,12 @@ export function buildDbDelegate<TPrisma extends PrismaClientLike>(
  * caller include / bare (ADR-0024) — while folding declared dependencies
  * (`needs`, ADR-0025) into whichever of those the read is already using.
  *
- * A fragment's own `include` and a sudo caller's `include` are folded and
- * used as-is, matching their existing (unmerged) treatment. A non-sudo
- * caller include is folded and then scoped by `buildAccessScopedInclude`
- * (ADR-0026) — caller-directed, so a relation named nowhere in the folded
- * tree never has its list's `query` access evaluated at all. A bare read
+ * A non-sudo fragment's own `include` and a non-sudo caller's `include` are
+ * both folded and then scoped by `buildAccessScopedInclude` (ADR-0026) —
+ * caller-directed, so a relation named nowhere in the folded tree never has
+ * its list's `query` access evaluated at all (issue #1088: a fragment read
+ * used to skip this walk entirely). A sudo caller's `include` (fragment or
+ * not) is folded and used as-is, unscoped — sudo is unaffected. A bare read
  * stays on the exact ADR-0024 path — `include: undefined`, no related
  * `query` access evaluated — unless folding actually added something, which
  * only happens when a field on this list declares `needs`.
@@ -924,6 +1004,13 @@ export function buildDbDelegate<TPrisma extends PrismaClientLike>(
  * `undefined` for every non-fragment path: a caller `include` (sudo or not)
  * and a bare read both mean "compute every field," matching what they
  * already fetch.
+ *
+ * Also returns `toOneAccessFilters` — the to-one relations `buildAccessScopedInclude`
+ * flagged as needing a post-query existence check rather than a Prisma-side
+ * `where` (issue #974). Only a non-sudo fragment or caller-include read can
+ * produce a non-empty tree: those are the only paths that evaluate a related
+ * list's `query` access at all. A sudo read and a bare read always return an
+ * empty tree.
  */
 async function resolveReadInclude(
   callerInclude: Record<string, unknown> | undefined,
@@ -937,6 +1024,8 @@ async function resolveReadInclude(
   include: Record<string, unknown> | undefined
   declaredOnly: DeclaredOnlyTree
   selection: FieldSelectionScope | undefined
+  toOneAccessFilters: ToOneAccessFilterTree
+  countDenials: CountAccessDenialTree
 }> {
   if (fragmentFields !== undefined) {
     const fragmentInclude = buildInclude(fragmentFields) ?? undefined
@@ -949,27 +1038,66 @@ async function resolveReadInclude(
       [listName],
       selection,
     )
-    return { ...folded, selection }
+
+    if (context._isSudo || !folded.include) {
+      return {
+        ...folded,
+        selection,
+        toOneAccessFilters: emptyToOneAccessFilterTree(),
+        countDenials: emptyCountAccessDenialTree(),
+      }
+    }
+
+    const { include, toOneAccessFilters, countDenials } = await buildAccessScopedInclude(
+      folded.include,
+      listConfig.fields,
+      { session: context.session, context },
+      config,
+      listName,
+    )
+    return {
+      include,
+      declaredOnly: folded.declaredOnly,
+      selection,
+      toOneAccessFilters,
+      countDenials,
+    }
   }
 
   if (context._isSudo) {
     const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config, listName)
-    return { ...folded, selection: undefined }
+    return {
+      ...folded,
+      selection: undefined,
+      toOneAccessFilters: emptyToOneAccessFilterTree(),
+      countDenials: emptyCountAccessDenialTree(),
+    }
   }
 
   const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config, listName)
   if (!folded.include) {
-    return { ...folded, selection: undefined }
+    return {
+      ...folded,
+      selection: undefined,
+      toOneAccessFilters: emptyToOneAccessFilterTree(),
+      countDenials: emptyCountAccessDenialTree(),
+    }
   }
 
-  const include = await buildAccessScopedInclude(
+  const { include, toOneAccessFilters, countDenials } = await buildAccessScopedInclude(
     folded.include,
     listConfig.fields,
     { session: context.session, context },
     config,
     listName,
   )
-  return { include, declaredOnly: folded.declaredOnly, selection: undefined }
+  return {
+    include,
+    declaredOnly: folded.declaredOnly,
+    selection: undefined,
+    toOneAccessFilters,
+    countDenials,
+  }
 }
 
 function createFindUnique<TPrisma extends PrismaClientLike>(
@@ -1026,14 +1154,15 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
     // Resolve `include`, folding any declared dependencies (`needs`,
     // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
     // already produces — see `resolveReadInclude`'s doc comment.
-    let { include, declaredOnly, selection } = await resolveReadInclude(
-      args.include,
-      fragment ? fragment._fields : undefined,
-      listName,
-      listConfig,
-      context,
-      config,
-    )
+    let { include, declaredOnly, selection, toOneAccessFilters, countDenials } =
+      await resolveReadInclude(
+        args.include,
+        fragment ? fragment._fields : undefined,
+        listName,
+        listConfig,
+        context,
+        config,
+      )
 
     // Virtual fields have no database column. Whichever path produced
     // `include` (fragment, access-controlled merge, or sudo passthrough), a
@@ -1056,6 +1185,14 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
       return null
     }
 
+    // Resolve which of the to-one relations flagged by `toOneAccessFilters`
+    // actually survive their related list's `query` access (issue #974) —
+    // one batched existence check per relation, before field visibility runs.
+    const toOneVisibility = await resolveToOneAccessVisibility([item], toOneAccessFilters, {
+      session: context.session,
+      context,
+    })
+
     // Pass sudo flag through context to skip field-level access checks
     const filtered = await filterReadableFields(
       item,
@@ -1069,6 +1206,8 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
       listName,
       declaredOnly,
       selection,
+      toOneVisibility,
+      countDenials,
     )
 
     if (fragment) {
@@ -1178,14 +1317,15 @@ function createFindMany<TPrisma extends PrismaClientLike>(
     // Resolve `include`, folding any declared dependencies (`needs`,
     // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
     // already produces — see `resolveReadInclude`'s doc comment.
-    let { include, declaredOnly, selection } = await resolveReadInclude(
-      args?.include,
-      fragment ? fragment._fields : undefined,
-      listName,
-      listConfig,
-      context,
-      config,
-    )
+    let { include, declaredOnly, selection, toOneAccessFilters, countDenials } =
+      await resolveReadInclude(
+        args?.include,
+        fragment ? fragment._fields : undefined,
+        listName,
+        listConfig,
+        context,
+        config,
+      )
 
     // Strips virtual keys from `include` before the Prisma call — see the
     // `createFindUnique` comment above for why (#628, ADR-0027).
@@ -1202,6 +1342,15 @@ function createFindMany<TPrisma extends PrismaClientLike>(
       include,
     })
 
+    // Resolve which of the to-one relations flagged by `toOneAccessFilters`
+    // actually survive their related list's `query` access (issue #974) —
+    // ONE batched existence check per relation across every row in `items`,
+    // before field visibility runs on any of them.
+    const toOneVisibility = await resolveToOneAccessVisibility(items, toOneAccessFilters, {
+      session: context.session,
+      context,
+    })
+
     // Pass sudo flag through context to skip field-level access checks
     const filtered = await Promise.all(
       items.map((item: Record<string, unknown>) =>
@@ -1217,6 +1366,8 @@ function createFindMany<TPrisma extends PrismaClientLike>(
           listName,
           declaredOnly,
           selection,
+          toOneVisibility,
+          countDenials,
         ),
       ),
     )
@@ -1501,14 +1652,15 @@ function createGet<TPrisma extends PrismaClientLike>(
     // Resolve `include`, folding any declared dependencies (`needs`,
     // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
     // already produces — see `resolveReadInclude`'s doc comment.
-    let { include, declaredOnly, selection } = await resolveReadInclude(
-      args?.include,
-      fragment ? fragment._fields : undefined,
-      listName,
-      listConfig,
-      context,
-      config,
-    )
+    let { include, declaredOnly, selection, toOneAccessFilters, countDenials } =
+      await resolveReadInclude(
+        args?.include,
+        fragment ? fragment._fields : undefined,
+        listName,
+        listConfig,
+        context,
+        config,
+      )
 
     // Virtual fields have no database column and must never reach Prisma (#628).
     include = stripVirtualFieldsFromInclude(include, listConfig.fields, config)
@@ -1519,6 +1671,13 @@ function createGet<TPrisma extends PrismaClientLike>(
     })
 
     if (item) {
+      // Resolve which of the to-one relations flagged by `toOneAccessFilters`
+      // actually survive their related list's `query` access (issue #974).
+      const toOneVisibility = await resolveToOneAccessVisibility([item], toOneAccessFilters, {
+        session: context.session,
+        context,
+      })
+
       const filtered = await filterReadableFields(
         item,
         listConfig.fields,
@@ -1531,6 +1690,8 @@ function createGet<TPrisma extends PrismaClientLike>(
         listName,
         declaredOnly,
         selection,
+        toOneVisibility,
+        countDenials,
       )
       if (fragment) {
         return pickFields(filtered, fragment._fields)

package/src/context/nested-operations.ts

@@ -1,6 +1,14 @@
 import type { OpenSaasConfig, ListConfig, FieldConfig } from '../config/types.js'
-import type { AccessContext, FieldAccess } from '../access/types.js'
-import { checkAccess, filterWritableFields, getRelatedListConfig } from '../access/index.js'
+import type { FieldAccess, PrismaFilter } from '../access/types.js'
+import type { StackContext } from './index.js'
+import {
+  checkAccess,
+  checkCreateAccess,
+  filterWritableFields,
+  getRelatedListConfig,
+  mergeFilters,
+  resolveSyntheticReverseRelation,
+} from '../access/index.js'
 import { checkFieldAccess } from '../access/field-access.js'
 import {
   executeResolveInput,
@@ -193,7 +201,7 @@ async function processNestedCreate(
   relatedListName: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
-  context: AccessContext,
+  context: StackContext,
   config: OpenSaasConfig,
   prisma: unknown,
   afterTasks: AfterTask[],
@@ -205,12 +213,12 @@ async function processNestedCreate(
     itemsArray.map(async (item, index) => {
       if (!context._isSudo) {
         const createAccess = relatedListConfig.access?.operation?.create
-        const accessResult = await checkAccess(createAccess, {
+        const allowed = await checkCreateAccess(relatedListName, createAccess, {
           session: context.session,
           context,
         })
 
-        if (accessResult === false) {
+        if (!allowed) {
           throw new Error('Access denied: Cannot create related item')
         }
       }
@@ -279,6 +287,8 @@ async function processNestedCreate(
           session: context.session,
           context,
           inputData: item,
+          listName: relatedListName,
+          config,
         },
       )
 
@@ -383,7 +393,7 @@ async function verifyConnectReachable(
   relatedListName: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
-  context: AccessContext,
+  context: StackContext,
   prisma: unknown,
   owningFieldAccess: FieldAccess | undefined,
   enclosingOperation: 'create' | 'update',
@@ -448,7 +458,7 @@ async function processNestedConnect(
   relatedListName: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
-  context: AccessContext,
+  context: StackContext,
   prisma: unknown,
   owningFieldAccess: FieldAccess | undefined,
   enclosingOperation: 'create' | 'update',
@@ -476,6 +486,28 @@ async function processNestedConnect(
   return connections
 }
 
+/**
+ * Re-check a nested update/delete access result against the target row,
+ * mirroring the Write Pipeline's `resolveExistingTarget` (#1081): `false`
+ * denies, `true` allows outright (the row's existence is already established
+ * by the caller's own `findUnique`), and a returned PrismaFilter must
+ * additionally match the row, re-checked in the DATABASE via
+ * `findFirst(mergeFilters(where, accessResult))` rather than in memory — the
+ * same requirement `connect`'s reachability check already applies (#578), so
+ * nested-relation predicates and boolean combinators are honoured correctly.
+ */
+async function isExistingTargetAccessible(
+  model: { findFirst: (args: { where: Record<string, unknown> }) => Promise<unknown> },
+  where: Record<string, unknown>,
+  accessResult: boolean | PrismaFilter,
+): Promise<boolean> {
+  if (accessResult === false) return false
+  if (accessResult === true) return true
+
+  const matchesFilter = await model.findFirst({ where: mergeFilters(where, accessResult) ?? {} })
+  return matchesFilter !== null
+}
+
 /**
  * Process nested update operations.
  *
@@ -489,7 +521,7 @@ async function processNestedUpdate(
   relatedListName: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
-  context: AccessContext,
+  context: StackContext,
   config: OpenSaasConfig,
   prisma: unknown,
   afterTasks: AfterTask[],
@@ -521,7 +553,7 @@ async function processNestedUpdate(
           context,
         })
 
-        if (accessResult === false) {
+        if (!(await isExistingTargetAccessible(model, where, accessResult))) {
           throw new Error('Access denied: Cannot update related item')
         }
       }
@@ -590,6 +622,8 @@ async function processNestedUpdate(
           item: originalItem,
           context,
           inputData: updateData,
+          listName: relatedListName,
+          config,
         },
       )
 
@@ -683,7 +717,7 @@ async function processNestedDelete(
   relatedListName: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
-  context: AccessContext,
+  context: StackContext,
   prisma: unknown,
   afterTasks: AfterTask[],
 ): Promise<Record<string, unknown> | Array<Record<string, unknown>> | boolean> {
@@ -716,7 +750,7 @@ async function processNestedDelete(
           context,
         })
 
-        if (accessResult === false) {
+        if (!(await isExistingTargetAccessible(model, where, accessResult))) {
           throw new Error('Access denied: Cannot delete related item')
         }
       }
@@ -791,7 +825,7 @@ async function processNestedConnectOrCreate(
   relatedListName: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
-  context: AccessContext,
+  context: StackContext,
   config: OpenSaasConfig,
   prisma: unknown,
   afterTasks: AfterTask[],
@@ -912,7 +946,7 @@ interface NestedOpHandlerArgs {
   enclosingItem: Record<string, unknown> | undefined
   /** The enclosing write's input data, passed to the owning-field gate for the same reason as `enclosingItem`. */
   enclosingInputData: Record<string, unknown> | undefined
-  context: AccessContext
+  context: StackContext
   config: OpenSaasConfig
   /** Prisma client used for dynamic model access during access checks. */
   prisma: unknown
@@ -1180,7 +1214,7 @@ export async function processNestedOperations(
   data: Record<string, unknown>,
   fieldConfigs: Record<string, FieldConfig>,
   config: OpenSaasConfig,
-  context: AccessContext & { prisma: unknown },
+  context: StackContext & { prisma: unknown },
   operation: 'create' | 'update',
   parentListName: string,
   parentOriginalItem: Record<string, unknown> | undefined,
@@ -1194,27 +1228,62 @@ export async function processNestedOperations(
   const processed: Record<string, unknown> = {}
 
   for (const [fieldName, value] of Object.entries(data)) {
-    const fieldConfig = fieldConfigs[fieldName]
-
-    if (!isRelationshipField(fieldConfig) || value === null || value === undefined) {
+    if (value === null || value === undefined) {
       processed[fieldName] = value
       continue
     }
 
-    const relationshipField = fieldConfig as { type: 'relationship'; ref: string }
-    const relatedConfig = getRelatedListConfig(relationshipField.ref, config)
-    if (!relatedConfig) {
+    const fieldConfig = fieldConfigs[fieldName]
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+    let relatedListConfig: ListConfig<any>
+    let resolvedListName: string
+    let owningFieldAccess: FieldAccess | undefined
+
+    if (isRelationshipField(fieldConfig)) {
+      const relationshipField = fieldConfig as { type: 'relationship'; ref: string }
+      const relatedConfig = getRelatedListConfig(relationshipField.ref, config)
+      if (!relatedConfig) {
+        processed[fieldName] = value
+        continue
+      }
+
+      const { listName: relatedListName, listConfig } = relatedConfig
+      resolvedListName = relatedListName || findListName(listConfig, config)
+      relatedListConfig = listConfig
+      // The owning relationship field's field-level access, for the #588 gate
+      // in verifyConnectReachable.
+      owningFieldAccess = fieldConfig.access
+    } else if (!fieldConfig) {
+      // Not a field the parent's config declares — check whether it names the
+      // synthetic back-relation a list-only `ref` generates on this list
+      // (`from_<List>_<field>`, #978). Resolved, it is processed exactly like a
+      // nested write through the declared field that owns it; unresolved, it
+      // is left untouched. This is NOT solely a sudo path: a multi-column
+      // field's raw per-part columns (e.g. `m_url`/`m_size`, #789) are ALSO
+      // undeclared from this list's `fieldConfigs` perspective and reach here
+      // on every write, sudo or not — `filterWritableFields` already
+      // recognises and gates those via its own `splitColumnOwners` map before
+      // its undeclared-key branch, and this function has no such map to tell
+      // them apart from a genuinely-unrecognised key, so it must not throw
+      // here. A genuinely unrecognised key under sudo is refused instead by
+      // `filterWritableFields`'s own resolution attempt, one level up.
+      const synthetic = resolveSyntheticReverseRelation(fieldName, parentListName, config)
+      if (!synthetic) {
+        processed[fieldName] = value
+        continue
+      }
+
+      resolvedListName = synthetic.sourceListName
+      relatedListConfig = synthetic.sourceListConfig
+      // There is no parent-side field here (unlike the declared-relationship
+      // branch above) — the FK-owning field genuinely IS the one the source
+      // list declares, so its access is the owning-field gate.
+      owningFieldAccess = synthetic.sourceFieldConfig.access
+    } else {
       processed[fieldName] = value
       continue
     }
 
-    const { listName: relatedListName, listConfig: relatedListConfig } = relatedConfig
-    const resolvedListName = relatedListName || findListName(relatedListConfig, config)
-
-    // The owning relationship field's field-level access, for the #588 gate
-    // in verifyConnectReachable.
-    const owningFieldAccess = fieldConfig.access
-
     processed[fieldName] = await processFieldNestedOps(
       fieldName,
       value as Record<string, unknown>,