@opensaas/stack-core 0.38.0 → 0.39.0

package/src/context/nested-operations.ts

@@ -19,34 +19,15 @@ import { getDbKey } from '../lib/case-utils.js'
 import { applyCreateDefaults } from './apply-defaults.js'
 
 /**
- * Nested writes (#569 / ADR-0010).
- *
- * Nested `create`/`update`/`delete` must fire the SAME list- and field-level
- * `beforeOperation`/`afterOperation` as the equivalent top-level write, so a
- * record's side effects are identical whether it was written nested or
- * top-level. Persistence itself is still performed by Prisma's single nested
- * write (so Prisma keeps owning FK ordering and intra-statement atomicity); we
- * run the nested records' `beforeOperation` BEFORE that persist and their
- * `afterOperation` AFTER it, all inside the one interactive transaction the
- * Write Pipeline opens.
- *
- * Mechanism (per ADR-0010, "hooks around a single nested persist"):
- *   - `processNestedOperations` runs nested resolveInput/validate/field-rules
- *     (as before) AND nested `beforeOperation`, and returns the transformed
- *     payload together with a list of deferred {@link AfterTask}s.
- *   - The Write Pipeline persists the parent (with the nested relations
- *     `include`d so the persisted nested rows come back), then calls
- *     {@link runAfterTasks} so each nested record's `afterOperation` fires with
- *     a real persisted `item` and (for update/delete) its `originalItem`.
- *   - Everything runs inside the transaction, so a throwing `beforeOperation`/
- *     `afterOperation` rolls back the whole write.
+ * Nested writes (#569 / ADR-0010): give nested `create`/`update`/`delete` the
+ * same before/afterOperation hooks as an equivalent top-level write, inside
+ * the one transaction the Write Pipeline opens. `processNestedOperations`
+ * transforms the payload and runs `beforeOperation`, returning deferred
+ * {@link AfterTask}s that {@link runAfterTasks} runs once the parent has
+ * persisted. See ADR-0010 for the full mechanism.
  */
 
-/**
- * A deferred nested `afterOperation` task, run after the parent has persisted.
- * It receives the persisted parent row (with nested relations included) so it
- * can recover the persisted nested `item`.
- */
+/** A deferred nested `afterOperation` task, run once the parent has persisted. */
 export interface AfterTask {
   /** Field name on the parent linking to the related list (for include lookup). */
   fieldName: string
@@ -67,16 +48,11 @@ export interface NestedOpsResult {
   includeFields: Set<string>
 }
 
-/**
- * Check if a field config is a relationship field
- */
 function isRelationshipField(fieldConfig: FieldConfig | undefined): boolean {
   return fieldConfig?.type === 'relationship'
 }
 
-/**
- * Resolve the related list name for a related list config (config object identity).
- */
+/** Resolve a list name by matching config object identity, not by name. */
 function findListName(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>,
@@ -94,8 +70,7 @@ function findListName(
  * Read the rows of a parent's included relation as an array.
  *
  * A to-one relation comes back as a single row (or `null`); a to-many relation
- * comes back as an array. This normalises both to an array so callers can apply
- * a uniform id-diff.
+ * comes back as an array. Normalises both so callers can apply a uniform id-diff.
  */
 function includedRows(
   parentResult: Record<string, unknown>,
@@ -123,13 +98,10 @@ function recoverUpdatedRow(
 }
 
 /**
- * Recover the CREATED nested rows from the parent result by id-diff.
- *
- * Created rows have no known id before the write, so they are identified as the
- * included rows whose ids are NOT in `preExistingIds` (the set of related-row
- * ids captured before the persist). Returned in include order, which the create
- * handler pairs to its create-payload entries by position (see
- * {@link CreatedRowRecovery}).
+ * Recover the CREATED nested rows from the parent result by id-diff: the
+ * included rows whose ids are NOT in `preExistingIds`. Returned in include
+ * order, which {@link CreatedRowRecovery} pairs to create-payload entries by
+ * position — reordering this would break that pairing.
  */
 function recoverCreatedRows(
   parentResult: Record<string, unknown>,
@@ -143,19 +115,13 @@ function recoverCreatedRows(
 
 /**
  * Shared, memoised recovery of the rows created for ONE nested `create` payload
- * on ONE relation field.
+ * on ONE relation field, by id-diff against the parent's pre-persist related
+ * ids, paired to create-payload entries by position. See ADR-0010. The id-diff
+ * is cached per parent result so every entry's task shares it.
  *
- * A to-many `create: [{A},{B}]` produces several rows that must each fire their
- * own `afterOperation` against their OWN row. We cannot tell which included row
- * corresponds to which payload entry by content alone, so we identify the set of
- * NEW rows by id-diff against the ids that existed before the persist, then pair
- * them to the create-payload entries by POSITION (Prisma preserves create-array
- * order in the included result). The id-diff is computed once per parent result
- * and cached so every entry's task shares it.
- *
- * `inputData`↔row pairing is therefore positional and best-effort; `item`
- * correctness (each task gets a genuinely-created, distinct row) is guaranteed:
- * a pre-existing row can never be returned because it is excluded by the diff.
+ * `inputData`↔row pairing is positional and best-effort; `item` correctness
+ * (each task gets a genuinely-created, distinct row) is guaranteed — a
+ * pre-existing row can never be returned because the diff excludes it.
  */
 interface CreatedRowRecovery {
   /** Recover the created row for the create-payload entry at `index`. */
@@ -182,14 +148,11 @@ function createCreatedRowRecovery(
 
 /**
  * Capture the ids of the rows currently linked to the parent via `fieldName`,
- * BEFORE the parent persists. Used to identify which included rows are NEW
- * (created by this write) afterwards.
+ * BEFORE the parent persists, so created rows can later be identified by id-diff.
+ * Empty for a parent CREATE (no parent row exists yet to have related rows).
  *
- * - For a parent CREATE there are no pre-existing related rows (the parent does
- *   not exist yet), so the set is empty.
- * - For a parent UPDATE we read the parent row's current relation and collect
- *   its ids. The same `tx` client is used so the read participates in the
- *   transaction and sees a consistent snapshot.
+ * `prisma` must be the transaction client — the read has to participate in the
+ * transaction to see a consistent snapshot.
  */
 async function capturePreExistingIds(
   parentListName: string,
@@ -220,11 +183,9 @@ async function capturePreExistingIds(
 }
 
 /**
- * Process nested create operations.
- *
- * Runs the target list's full input pipeline (resolveInput → validate →
- * field-rules → filter-writable → recurse) AND its `beforeOperation`, then
- * registers an `afterOperation` task keyed to the parent's included relation.
+ * Process nested create operations: run the target list's full input pipeline
+ * and `beforeOperation`, then register an `afterOperation` task keyed to the
+ * parent's included relation.
  */
 async function processNestedCreate(
   items: Record<string, unknown> | Array<Record<string, unknown>>,
@@ -242,7 +203,6 @@ async function processNestedCreate(
 
   const processedItems = await Promise.all(
     itemsArray.map(async (item, index) => {
-      // 1. Check create access (skip if sudo mode)
       if (!context._isSudo) {
         const createAccess = relatedListConfig.access?.operation?.create
         const accessResult = await checkAccess(createAccess, {
@@ -255,7 +215,6 @@ async function processNestedCreate(
         }
       }
 
-      // 2. Execute list-level resolveInput hook
       let resolvedData = await executeResolveInput(relatedListConfig.hooks, {
         listKey: relatedListName,
         operation: 'create',
@@ -265,7 +224,6 @@ async function processNestedCreate(
         context,
       })
 
-      // 3. Execute field-level resolveInput hooks
       resolvedData = await executeFieldResolveInputHooks(
         item,
         resolvedData,
@@ -275,13 +233,11 @@ async function processNestedCreate(
         relatedListName,
       )
 
-      // 3.5 Apply field defaults to omitted inputs (resolve-then-validate, #615).
-      // Mirrors the top-level Hook Pipeline so a nested required-with-default
-      // field resolves to its default before validation instead of failing
-      // `isRequired`. Create-only; explicit values (incl. null) are preserved.
+      // Apply field defaults to omitted inputs (resolve-then-validate, #615) so
+      // a nested required-with-default field resolves before `isRequired` runs,
+      // mirroring the top-level pipeline. Create-only.
       resolvedData = applyCreateDefaults(resolvedData, relatedListConfig.fields)
 
-      // 4. Execute validate hook
       await executeValidate(relatedListConfig.hooks, {
         listKey: relatedListName,
         operation: 'create',
@@ -291,7 +247,6 @@ async function processNestedCreate(
         context,
       })
 
-      // 4.5 Field-level validate hooks
       await executeFieldValidateHooks(
         item,
         resolvedData,
@@ -301,14 +256,13 @@ async function processNestedCreate(
         relatedListName,
       )
 
-      // 5. Field validation (built-in rules)
       const validation = validateFieldRules(resolvedData, relatedListConfig.fields, 'create')
       if (validation.errors.length > 0) {
         throw new ValidationError(validation.errors, validation.fieldErrors)
       }
 
-      // 5.5 Split multi-column fields into physical columns (#789). Only
-      // reached once the logical value has passed validation above.
+      // Split multi-column fields into physical columns (#789) — must run after
+      // validation, which operates on the logical (pre-split) value.
       resolvedData = await splitMultiColumnFields(
         item,
         resolvedData,
@@ -317,7 +271,6 @@ async function processNestedCreate(
         context,
       )
 
-      // 6. Filter writable fields
       const filtered = await filterWritableFields(
         resolvedData,
         relatedListConfig.fields,
@@ -329,9 +282,8 @@ async function processNestedCreate(
         },
       )
 
-      // 7. Recursively process nested operations in this item. This nested row
-      // is itself being CREATED, so its own relations have no pre-existing rows
-      // (parent originalItem is undefined → empty pre-existing set).
+      // This nested row is itself being created, so it has no pre-existing
+      // related rows of its own (parent originalItem is undefined below).
       const { data: nestedData, afterTasks: childAfterTasks } = await processNestedOperations(
         filtered,
         relatedListConfig.fields,
@@ -340,12 +292,11 @@ async function processNestedCreate(
         'create',
         relatedListName,
         undefined,
-        // This nested row is being CREATED, so its enclosing inputData is its own
-        // create payload (passed to the connect-site owning-field gate, #588).
+        // Its own create payload is the enclosing inputData for the connect-site
+        // owning-field gate (#588).
         item,
       )
 
-      // 8. Field-level beforeOperation (side effects) for this nested create
       await executeFieldBeforeOperationHooks(
         item,
         resolvedData,
@@ -355,7 +306,6 @@ async function processNestedCreate(
         relatedListName,
       )
 
-      // 9. List-level beforeOperation for this nested create
       await executeBeforeOperation(relatedListConfig.hooks, {
         listKey: relatedListName,
         operation: 'create',
@@ -364,26 +314,19 @@ async function processNestedCreate(
         context,
       })
 
-      // 10. Register afterOperation: fires once the parent (and thus this nested
-      // row) has persisted. The created row is recovered by id-diff and paired
-      // to THIS create-payload entry by position (see CreatedRowRecovery), so a
-      // to-many `create: [{A},{B}]` fires once per row, each against its OWN
-      // distinct row, and never against a pre-existing sibling.
+      // Fires once the parent has persisted. The row is recovered by id-diff and
+      // paired to THIS entry by position (see CreatedRowRecovery), so a to-many
+      // `create: [{A},{B}]` fires once per row against its own distinct row.
       afterTasks.push({
         fieldName,
         run: async (parentResult) => {
           const createdItem = recovery.rowAt(parentResult, index)
           if (!createdItem) {
-            // The created row could not be identified by id-diff — the parent
-            // write did not return this nested relation (e.g. the underlying
-            // client does not echo `include`d relations). We must NOT hand an
-            // id-less `{}` to a hook as if it were the persisted row (finding 4:
-            // that would fire `afterOperation` against a fabricated item). The
-            // before-persist hooks have already run; we deliberately SKIP this
-            // record's create `afterOperation` rather than fire it with a bogus
-            // item. Real Prisma always echoes the `include`d relation, so this
-            // skip is reached only by clients/mocks that omit it. `item`
-            // correctness is the must-have; a missing row is never fabricated.
+            // Could not identify the created row by id-diff — the parent write
+            // didn't echo this nested relation (e.g. a client/mock that doesn't
+            // honour `include`; real Prisma always does). Deliberately SKIP this
+            // record's `afterOperation` rather than fabricate an id-less item —
+            // `item` correctness is the must-have, so a missing row is never faked.
             return
           }
 
@@ -406,7 +349,6 @@ async function processNestedCreate(
             relatedListName,
           )
 
-          // Run any deeper nested afterOperation tasks, scoped to the persisted row.
           await runAfterTasks(childAfterTasks, createdItem)
         },
       })
@@ -421,23 +363,18 @@ async function processNestedCreate(
 /**
  * Verify that a single connection target is reachable for the caller.
  *
- * Connecting an existing row references it; it does not modify the row's own
- * data. Mirroring Keystone, this requires **read/query** access on the target
- * list (not `update`). When query access returns a filter object, the filter is
- * evaluated in the DATABASE (not in memory) via
- * `findFirst({ where: { AND: [connection, accessFilter] } })`. The connect is
- * allowed iff that query returns a row, which correctly handles arbitrary
- * nested-relation predicates and boolean combinators (`AND`/`OR`/`some`/
- * `none`/`not`). The existence check is folded into the reachability query so a
- * non-existent id is still denied.
+ * Connecting references an existing row rather than modifying it, so — mirroring
+ * Keystone — it requires **read/query** access on the target (#578), not update.
+ * A filter-result query access is evaluated in the DATABASE via
+ * `findFirst({ where: { AND: [connection, accessFilter] } })` rather than in
+ * memory, so it correctly handles arbitrary nested-relation predicates and
+ * boolean combinators; a non-existent id is folded into the same check.
  *
- * In ADDITION to the target read/reachability check (#578), the OWNING
- * relationship field's field-level access (its `create`/`update` access on the
- * list being written, e.g. `Post.author`) must permit the connect (#588). This
- * is the other half Keystone required: a connect needs read access on the
- * target AND write access on the owning relationship field. If the owning
- * field's field-level access denies, the connect is denied even when the target
- * row is readable/reachable.
+ * In ADDITION, the OWNING relationship field's field-level access (e.g.
+ * `Post.author`'s `create`/`update` access) must permit the connect (#588) —
+ * the other half Keystone requires: read access on the target AND write access
+ * on the owning field. A deny here denies the connect even when the target row
+ * is readable/reachable.
  *
  * Sudo bypasses the entire check (handled by the caller).
  */
@@ -457,18 +394,10 @@ async function verifyConnectReachable(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const model = (prisma as any)[getDbKey(relatedListName)]
 
-  // #588 — gate the connect by the OWNING relationship field's field-level
-  // access (evaluated for the enclosing write's operation). This runs in
-  // addition to the target read/reachability check below; a deny here denies
-  // the connect even if the target row is readable. `checkFieldAccess` returns
-  // `true` under sudo, but the caller already skips this whole function for
-  // sudo, so the gate never fires for trusted writes.
-  //
-  // `item`/`inputData` are the ENCLOSING write's `originalItem`/`inputData` —
-  // the SAME values the canonical Phase-5 `filterWritableFields` call passes for
-  // this field — so a field-access rule that depends on `item` or `inputData`
-  // (e.g. `({ item }) => item.status === 'draft'`) evaluates identically here and
-  // at Phase 5, and the two gates cannot diverge into a spurious connect denial.
+  // #588 owning-field gate (see docblock above). `item`/`inputData` are the
+  // ENCLOSING write's `originalItem`/`inputData` — the same values the canonical
+  // Phase-5 `filterWritableFields` call passes for this field — so an
+  // item-/inputData-dependent field-access rule can't diverge between the two gates.
   const owningFieldAllowed = await checkFieldAccess(owningFieldAccess, enclosingOperation, {
     session: context.session,
     item: enclosingItem,
@@ -479,20 +408,17 @@ async function verifyConnectReachable(
     throw new Error('Access denied: Cannot connect to this item')
   }
 
-  // Connecting references an existing row; it requires READ (query) access on
-  // the target, not update access.
   const queryAccess = relatedListConfig.access?.operation?.query
   const accessResult = await checkAccess(queryAccess, {
     session: context.session,
     context,
   })
 
-  // Explicit denial.
   if (accessResult === false) {
     throw new Error('Access denied: Cannot connect to this item')
   }
 
-  // Full access: still verify the row exists (keep "Item not found" behaviour).
+  // Full access still verifies the row exists, to keep "Item not found" behaviour.
   if (accessResult === true) {
     const item = await model.findUnique({ where: connection })
     if (!item) {
@@ -501,11 +427,8 @@ async function verifyConnectReachable(
     return
   }
 
-  // Filter result: confirm the row is reachable under the access filter by
-  // AND-combining the connection identifier with the filter and querying the DB.
-  // A non-existent id and an unreachable row both yield no row → denied. This
-  // correctly evaluates arbitrary nested-relation predicates and boolean
-  // combinators because the database does the matching, not an in-memory walk.
+  // Filter result: reachable iff AND-combining the connection with the filter
+  // returns a row (see docblock above).
   const reachable = await model.findFirst({
     where: { AND: [connection, accessResult] },
   })
@@ -534,7 +457,6 @@ async function processNestedConnect(
 ): Promise<Record<string, unknown> | Array<Record<string, unknown>>> {
   const connectionsArray = Array.isArray(connections) ? connections : [connections]
 
-  // Check read access for each item being connected (skip if sudo mode)
   if (!context._isSudo) {
     for (const connection of connectionsArray) {
       await verifyConnectReachable(
@@ -582,18 +504,15 @@ async function processNestedUpdate(
 
       const where = (update as Record<string, unknown>).where as Record<string, unknown>
 
-      // Fetch the existing item — reused as `originalItem` for afterOperation.
+      // Fetched here and reused as `originalItem` for afterOperation.
       const originalItem = await model.findUnique({ where })
 
       if (!originalItem) {
         throw new Error('Cannot update: Item not found')
       }
 
-      // The updated row's id is known up front, so the included-result read-back
-      // finds this row directly by id.
       const knownId = typeof originalItem.id === 'string' ? (originalItem.id as string) : undefined
 
-      // Check update access (skip if sudo mode)
       if (!context._isSudo) {
         const updateAccess = relatedListConfig.access?.operation?.update
         const accessResult = await checkAccess(updateAccess, {
@@ -607,7 +526,6 @@ async function processNestedUpdate(
         }
       }
 
-      // Execute list-level resolveInput hook
       const updateData = (update as Record<string, unknown>).data as Record<string, unknown>
       let resolvedData = await executeResolveInput(relatedListConfig.hooks, {
         listKey: relatedListName,
@@ -618,7 +536,6 @@ async function processNestedUpdate(
         context,
       })
 
-      // Execute field-level resolveInput hooks
       resolvedData = await executeFieldResolveInputHooks(
         updateData,
         resolvedData,
@@ -629,7 +546,6 @@ async function processNestedUpdate(
         originalItem,
       )
 
-      // Execute validate hook
       await executeValidate(relatedListConfig.hooks, {
         listKey: relatedListName,
         operation: 'update',
@@ -639,7 +555,6 @@ async function processNestedUpdate(
         context,
       })
 
-      // Field-level validate hooks
       await executeFieldValidateHooks(
         updateData,
         resolvedData,
@@ -650,14 +565,13 @@ async function processNestedUpdate(
         originalItem,
       )
 
-      // Field validation (built-in rules)
       const validation = validateFieldRules(resolvedData, relatedListConfig.fields, 'update')
       if (validation.errors.length > 0) {
         throw new ValidationError(validation.errors, validation.fieldErrors)
       }
 
-      // Split multi-column fields into physical columns (#789). Only reached
-      // once the logical value has passed validation above.
+      // Split multi-column fields into physical columns (#789) — must run after
+      // validation, which operates on the logical (pre-split) value.
       resolvedData = await splitMultiColumnFields(
         updateData,
         resolvedData,
@@ -667,7 +581,6 @@ async function processNestedUpdate(
         originalItem,
       )
 
-      // Filter writable fields
       const filtered = await filterWritableFields(
         resolvedData,
         relatedListConfig.fields,
@@ -680,8 +593,8 @@ async function processNestedUpdate(
         },
       )
 
-      // Recursively process nested operations. This nested row is being UPDATED,
-      // so its own relations' pre-existing rows are captured from `originalItem`.
+      // This nested row is being updated, so its own relations' pre-existing
+      // rows are captured from `originalItem` below.
       const { data: nestedData, afterTasks: childAfterTasks } = await processNestedOperations(
         filtered,
         relatedListConfig.fields,
@@ -690,12 +603,11 @@ async function processNestedUpdate(
         'update',
         relatedListName,
         originalItem,
-        // This nested row is being UPDATED, so its enclosing inputData is its own
-        // update payload (passed to the connect-site owning-field gate, #588).
+        // Its own update payload is the enclosing inputData for the connect-site
+        // owning-field gate (#588).
         updateData,
       )
 
-      // Field-level beforeOperation (side effects)
       await executeFieldBeforeOperationHooks(
         updateData,
         resolvedData,
@@ -706,7 +618,6 @@ async function processNestedUpdate(
         originalItem,
       )
 
-      // List-level beforeOperation
       await executeBeforeOperation(relatedListConfig.hooks, {
         listKey: relatedListName,
         operation: 'update',
@@ -716,8 +627,7 @@ async function processNestedUpdate(
         context,
       })
 
-      // Register afterOperation: fires after the parent persist. The updated row
-      // is recovered from the parent's included relation by its known id.
+      // Fires after the parent persist; the row is recovered by its known id.
       afterTasks.push({
         fieldName,
         run: async (parentResult) => {
@@ -798,7 +708,6 @@ async function processNestedDelete(
         throw new Error('Cannot delete: Item not found')
       }
 
-      // Check delete access (skip if sudo mode)
       if (!context._isSudo) {
         const deleteAccess = relatedListConfig.access?.operation?.delete
         const accessResult = await checkAccess(deleteAccess, {
@@ -812,7 +721,6 @@ async function processNestedDelete(
         }
       }
 
-      // List-level validate (delete)
       await executeValidate(relatedListConfig.hooks, {
         listKey: relatedListName,
         operation: 'delete',
@@ -820,7 +728,6 @@ async function processNestedDelete(
         context,
       })
 
-      // Field-level validate (delete)
       await executeFieldValidateHooks(
         undefined,
         undefined,
@@ -831,7 +738,6 @@ async function processNestedDelete(
         originalItem,
       )
 
-      // Field-level beforeOperation (delete)
       await executeFieldBeforeOperationHooks(
         {},
         {},
@@ -842,7 +748,6 @@ async function processNestedDelete(
         originalItem,
       )
 
-      // List-level beforeOperation (delete)
       await executeBeforeOperation(relatedListConfig.hooks, {
         listKey: relatedListName,
         operation: 'delete',
@@ -850,8 +755,8 @@ async function processNestedDelete(
         context,
       })
 
-      // Register afterOperation: the row is gone after persist, so the
-      // originalItem is the authoritative record passed to after-hooks.
+      // The row is gone after persist, so originalItem is the authoritative
+      // record passed to the after-hooks below.
       afterTasks.push({
         fieldName: '',
         run: async () => {
@@ -880,9 +785,6 @@ async function processNestedDelete(
   return deletes
 }
 
-/**
- * Process nested connectOrCreate operations
- */
 async function processNestedConnectOrCreate(
   operations: Record<string, unknown> | Array<Record<string, unknown>>,
   fieldName: string,
@@ -905,15 +807,11 @@ async function processNestedConnectOrCreate(
     operationsArray.map(async (op) => {
       const opRecord = op as Record<string, unknown>
 
-      // Check access for the connect portion (skip if sudo mode).
-      //
-      // connectOrCreate connects an existing row when present, otherwise
-      // creates. So when the row exists we apply the same connect semantics as
-      // processNestedConnect — READ (query) access on the target, evaluated via
-      // DB reachability for filter results, PLUS the owning relationship field's
-      // field-level access (#588). When the row does not exist we fall through to
-      // create. We must NOT swallow an access-denied error: only the genuine
-      // "row absent" case may fall back to create.
+      // When the target row exists, connectOrCreate applies the same connect
+      // semantics as processNestedConnect (read access + #588 owning-field gate,
+      // both evaluated via DB reachability); otherwise it falls through to
+      // create. An access-denied error must NOT be swallowed into that fallback
+      // — only a genuine "row absent" may fall back to create.
       let rowExists = false
       if (!context._isSudo) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -922,18 +820,9 @@ async function processNestedConnectOrCreate(
 
         const existingItem = await model.findUnique({ where })
 
-        // Only enforce connect access when the row actually exists; otherwise
-        // the create branch is used.
         if (existingItem) {
           rowExists = true
 
-          // #588 — gate the connect branch by the OWNING relationship field's
-          // field-level access, identical to processNestedConnect. A deny here
-          // denies the connect even if the target row is readable/reachable.
-          // `item`/`inputData` are the ENCLOSING write's `originalItem`/
-          // `inputData` (the same values Phase-5 `filterWritableFields` passes),
-          // so item-/inputData-dependent field rules cannot diverge between the
-          // two gates.
           const owningFieldAllowed = await checkFieldAccess(owningFieldAccess, enclosingOperation, {
             session: context.session,
             item: enclosingItem,
@@ -955,8 +844,6 @@ async function processNestedConnectOrCreate(
             throw new Error('Access denied: Cannot connect to existing item')
           }
 
-          // Filter result: confirm the existing row is reachable under the
-          // access filter via DB reachability (handles nested/boolean filters).
           if (accessResult !== true) {
             const reachable = await model.findFirst({
               where: { AND: [where, accessResult] },
@@ -969,11 +856,10 @@ async function processNestedConnectOrCreate(
         }
       }
 
-      // Process the create portion through the full create pipeline (incl.
-      // before/afterOperation). Only register an afterOperation task when the
-      // create branch will actually run (row absent), so a pure connect does not
-      // fire create hooks. Under sudo we cannot statically know, so we let the
-      // create pipeline run its hooks (sudo bypasses access only, not hooks).
+      // Only register an afterOperation task when the create branch will
+      // actually run (row absent), so a pure connect doesn't fire create hooks.
+      // Under sudo we can't tell statically, so the create pipeline always runs
+      // its hooks there (sudo bypasses access only, not hooks).
       const runCreateHooks = context._isSudo || !rowExists
       const createAfterTasks: AfterTask[] = runCreateHooks ? afterTasks : []
       const processedCreate = await processNestedCreate(
@@ -1011,29 +897,20 @@ interface NestedOpHandlerArgs {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   relatedListConfig: ListConfig<any>
   /**
-   * Field-level `access` of the OWNING relationship field on the list being
-   * written (e.g. `Post.author`). Used by the connect/connectOrCreate handlers
-   * to gate connects by the owning field's create/update access (#588).
+   * Field-level `access` of the OWNING relationship field (e.g. `Post.author`).
+   * Gates connect/connectOrCreate by the owning field's create/update access —
+   * see the #588 gate in {@link verifyConnectReachable}.
    */
   owningFieldAccess: FieldAccess | undefined
-  /**
-   * The enclosing write's operation (`create`/`update`), used as the field-access
-   * operation for the owning-field connect gate (#588).
-   */
+  /** The enclosing write's operation, used as the owning-field gate's field-access operation. */
   enclosingOperation: 'create' | 'update'
   /**
-   * The enclosing write's existing row (the parent `originalItem`): present for an
-   * enclosing UPDATE, `undefined` for an enclosing CREATE. Threaded into the
-   * connect-site owning-field gate so it evaluates `item` exactly like the
-   * canonical Phase-5 `filterWritableFields` call and the two cannot diverge
-   * (#588 finding).
+   * The enclosing write's `originalItem` (`undefined` for an enclosing create).
+   * Passed to the owning-field gate so it matches the canonical Phase-5
+   * `filterWritableFields` call and the two can't diverge (#588).
    */
   enclosingItem: Record<string, unknown> | undefined
-  /**
-   * The enclosing write's input data. Threaded into the connect-site owning-field
-   * gate so it evaluates `inputData` exactly like the canonical Phase-5
-   * `filterWritableFields` call (#588 finding).
-   */
+  /** 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
   config: OpenSaasConfig
@@ -1307,10 +1184,8 @@ export async function processNestedOperations(
   operation: 'create' | 'update',
   parentListName: string,
   parentOriginalItem: Record<string, unknown> | undefined,
-  // The enclosing write's input data (the SAME value Phase-5 `filterWritableFields`
-  // passes as `inputData`). Threaded into the connect-site owning-field gate (#588
-  // finding) so item-/inputData-dependent field-access rules cannot diverge between
-  // Phase 5 and the connect site. `undefined` is tolerated (defaults to `{}`).
+  // The enclosing write's inputData, for the #588 owning-field gate (see
+  // verifyConnectReachable). `undefined` is tolerated (defaults to `{}`).
   parentInputData: Record<string, unknown> | undefined = undefined,
 ): Promise<NestedOpsResult> {
   const afterTasks: AfterTask[] = []
@@ -1321,13 +1196,11 @@ export async function processNestedOperations(
   for (const [fieldName, value] of Object.entries(data)) {
     const fieldConfig = fieldConfigs[fieldName]
 
-    // If not a relationship field or no value, pass through
     if (!isRelationshipField(fieldConfig) || value === null || value === undefined) {
       processed[fieldName] = value
       continue
     }
 
-    // Get related list config
     const relationshipField = fieldConfig as { type: 'relationship'; ref: string }
     const relatedConfig = getRelatedListConfig(relationshipField.ref, config)
     if (!relatedConfig) {
@@ -1336,13 +1209,10 @@ export async function processNestedOperations(
     }
 
     const { listName: relatedListName, listConfig: relatedListConfig } = relatedConfig
-    // Sanity: ensure the resolved list name matches the config identity.
     const resolvedListName = relatedListName || findListName(relatedListConfig, config)
 
-    // #588 — the owning relationship field's field-level access (e.g. the
-    // `access` on `Post.author`). Threaded into the nested-op handlers so the
-    // connect/connectOrCreate handlers can gate connects by this field's
-    // create/update access, in addition to the target's read access.
+    // The owning relationship field's field-level access, for the #588 gate
+    // in verifyConnectReachable.
     const owningFieldAccess = fieldConfig.access
 
     processed[fieldName] = await processFieldNestedOps(
@@ -1353,10 +1223,8 @@ export async function processNestedOperations(
         relatedListConfig,
         owningFieldAccess,
         enclosingOperation: operation,
-        // The enclosing write's `originalItem`/`inputData` — the SAME values the
-        // canonical Phase-5 `filterWritableFields` call passes for this field — so
-        // the connect-site owning-field gate evaluates item-/inputData-dependent
-        // rules identically and cannot diverge into a spurious connect denial (#588).
+        // Same values Phase-5 `filterWritableFields` passes for this field, so
+        // the #588 owning-field gate can't diverge from it.
         enclosingItem: parentOriginalItem,
         enclosingInputData: parentInputData ?? {},
         context,