@opensaas/stack-core 0.38.0 → 0.39.0

package/dist/context/nested-operations.js

@@ -3,15 +3,10 @@ import { checkFieldAccess } from '../access/field-access.js';
 import { executeResolveInput, executeValidate, executeFieldResolveInputHooks, executeBeforeOperation, executeAfterOperation, executeFieldBeforeOperationHooks, executeFieldAfterOperationHooks, executeFieldValidateHooks, validateFieldRules, splitMultiColumnFields, ValidationError, } from '../hooks/index.js';
 import { getDbKey } from '../lib/case-utils.js';
 import { applyCreateDefaults } from './apply-defaults.js';
-/**
- * Check if a field config is a relationship field
- */
 function isRelationshipField(fieldConfig) {
     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, config) {
@@ -26,8 +21,7 @@ relatedListConfig, config) {
  * 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, fieldName) {
     const included = parentResult[fieldName];
@@ -49,13 +43,10 @@ function recoverUpdatedRow(parentResult, fieldName, knownId) {
     return includedRows(parentResult, fieldName).find((r) => r.id === knownId);
 }
 /**
- * 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, fieldName, preExistingIds) {
     return includedRows(parentResult, fieldName).filter((r) => typeof r.id === 'string' && !preExistingIds.has(r.id));
@@ -76,14 +67,11 @@ function createCreatedRowRecovery(fieldName, preExistingIds) {
 }
 /**
  * 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, parentOriginalItem, fieldName, prisma) {
     const ids = new Set();
@@ -108,18 +96,15 @@ async function capturePreExistingIds(parentListName, parentOriginalItem, fieldNa
     return ids;
 }
 /**
- * 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, fieldName, relatedListName, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 relatedListConfig, context, config, prisma, afterTasks, recovery) {
     const itemsArray = Array.isArray(items) ? items : [items];
     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, {
@@ -130,7 +115,6 @@ relatedListConfig, context, config, prisma, afterTasks, recovery) {
                 throw new Error('Access denied: Cannot create related item');
             }
         }
-        // 2. Execute list-level resolveInput hook
         let resolvedData = await executeResolveInput(relatedListConfig.hooks, {
             listKey: relatedListName,
             operation: 'create',
@@ -139,14 +123,11 @@ relatedListConfig, context, config, prisma, afterTasks, recovery) {
             item: undefined,
             context,
         });
-        // 3. Execute field-level resolveInput hooks
         resolvedData = await executeFieldResolveInputHooks(item, resolvedData, relatedListConfig.fields, 'create', context, 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',
@@ -155,32 +136,26 @@ relatedListConfig, context, config, prisma, afterTasks, recovery) {
             item: undefined,
             context,
         });
-        // 4.5 Field-level validate hooks
         await executeFieldValidateHooks(item, resolvedData, relatedListConfig.fields, 'create', context, 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, relatedListConfig.fields, 'create', context);
-        // 6. Filter writable fields
         const filtered = await filterWritableFields(resolvedData, relatedListConfig.fields, 'create', {
             session: context.session,
             context,
             inputData: item,
         });
-        // 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, config, { ...context, prisma }, '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, relatedListConfig.fields, 'create', context, relatedListName);
-        // 9. List-level beforeOperation for this nested create
         await executeBeforeOperation(relatedListConfig.hooks, {
             listKey: relatedListName,
             operation: 'create',
@@ -188,26 +163,19 @@ relatedListConfig, context, config, prisma, afterTasks, recovery) {
             resolvedData,
             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;
                 }
                 await executeAfterOperation(relatedListConfig.hooks, {
@@ -219,7 +187,6 @@ relatedListConfig, context, config, prisma, afterTasks, recovery) {
                     context,
                 });
                 await executeFieldAfterOperationHooks(createdItem, item, resolvedData, relatedListConfig.fields, 'create', context, relatedListName);
-                // Run any deeper nested afterOperation tasks, scoped to the persisted row.
                 await runAfterTasks(childAfterTasks, createdItem);
             },
         });
@@ -230,23 +197,18 @@ relatedListConfig, context, config, prisma, afterTasks, recovery) {
 /**
  * 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).
  */
@@ -256,18 +218,10 @@ relatedListConfig, context, prisma, owningFieldAccess, enclosingOperation, enclo
     // Access Prisma model dynamically - required because model names are generated at runtime
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const model = prisma[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,
@@ -277,18 +231,15 @@ relatedListConfig, context, prisma, owningFieldAccess, enclosingOperation, enclo
     if (!owningFieldAllowed) {
         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) {
@@ -296,11 +247,8 @@ relatedListConfig, context, prisma, owningFieldAccess, enclosingOperation, enclo
         }
         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] },
     });
@@ -317,7 +265,6 @@ async function processNestedConnect(connections, relatedListName,
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 relatedListConfig, context, prisma, owningFieldAccess, enclosingOperation, enclosingItem, enclosingInputData) {
     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(connection, relatedListName, relatedListConfig, context, prisma, owningFieldAccess, enclosingOperation, enclosingItem, enclosingInputData);
@@ -341,15 +288,12 @@ relatedListConfig, context, config, prisma, afterTasks) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const model = prisma[getDbKey(relatedListName)];
         const where = update.where;
-        // 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 : undefined;
-        // Check update access (skip if sudo mode)
         if (!context._isSudo) {
             const updateAccess = relatedListConfig.access?.operation?.update;
             const accessResult = await checkAccess(updateAccess, {
@@ -361,7 +305,6 @@ relatedListConfig, context, config, prisma, afterTasks) {
                 throw new Error('Access denied: Cannot update related item');
             }
         }
-        // Execute list-level resolveInput hook
         const updateData = update.data;
         let resolvedData = await executeResolveInput(relatedListConfig.hooks, {
             listKey: relatedListName,
@@ -371,9 +314,7 @@ relatedListConfig, context, config, prisma, afterTasks) {
             item: originalItem,
             context,
         });
-        // Execute field-level resolveInput hooks
         resolvedData = await executeFieldResolveInputHooks(updateData, resolvedData, relatedListConfig.fields, 'update', context, relatedListName, originalItem);
-        // Execute validate hook
         await executeValidate(relatedListConfig.hooks, {
             listKey: relatedListName,
             operation: 'update',
@@ -382,32 +323,27 @@ relatedListConfig, context, config, prisma, afterTasks) {
             item: originalItem,
             context,
         });
-        // Field-level validate hooks
         await executeFieldValidateHooks(updateData, resolvedData, relatedListConfig.fields, 'update', context, relatedListName, 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, relatedListConfig.fields, 'update', context, originalItem);
-        // Filter writable fields
         const filtered = await filterWritableFields(resolvedData, relatedListConfig.fields, 'update', {
             session: context.session,
             item: originalItem,
             context,
             inputData: updateData,
         });
-        // 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, config, { ...context, prisma }, '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, relatedListConfig.fields, 'update', context, relatedListName, originalItem);
-        // List-level beforeOperation
         await executeBeforeOperation(relatedListConfig.hooks, {
             listKey: relatedListName,
             operation: 'update',
@@ -416,8 +352,7 @@ relatedListConfig, context, config, prisma, afterTasks) {
             resolvedData,
             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) => {
@@ -470,7 +405,6 @@ relatedListConfig, context, prisma, afterTasks) {
         if (!originalItem) {
             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, {
@@ -482,26 +416,22 @@ relatedListConfig, context, prisma, afterTasks) {
                 throw new Error('Access denied: Cannot delete related item');
             }
         }
-        // List-level validate (delete)
         await executeValidate(relatedListConfig.hooks, {
             listKey: relatedListName,
             operation: 'delete',
             item: originalItem,
             context,
         });
-        // Field-level validate (delete)
         await executeFieldValidateHooks(undefined, undefined, relatedListConfig.fields, 'delete', context, relatedListName, originalItem);
-        // Field-level beforeOperation (delete)
         await executeFieldBeforeOperationHooks({}, {}, relatedListConfig.fields, 'delete', context, relatedListName, originalItem);
-        // List-level beforeOperation (delete)
         await executeBeforeOperation(relatedListConfig.hooks, {
             listKey: relatedListName,
             operation: 'delete',
             item: originalItem,
             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 () => {
@@ -517,41 +447,25 @@ relatedListConfig, context, prisma, afterTasks) {
     }));
     return deletes;
 }
-/**
- * Process nested connectOrCreate operations
- */
 async function processNestedConnectOrCreate(operations, fieldName, relatedListName, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 relatedListConfig, context, config, prisma, afterTasks, recovery, owningFieldAccess, enclosingOperation, enclosingItem, enclosingInputData) {
     const operationsArray = Array.isArray(operations) ? operations : [operations];
     const processedOps = await Promise.all(operationsArray.map(async (op) => {
         const opRecord = op;
-        // 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
             const model = prisma[getDbKey(relatedListName)];
             const where = opRecord.where;
             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,
@@ -570,8 +484,6 @@ relatedListConfig, context, config, prisma, afterTasks, recovery, owningFieldAcc
                 if (accessResult === false) {
                     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] },
@@ -582,11 +494,10 @@ relatedListConfig, context, config, prisma, afterTasks, recovery, owningFieldAcc
                 }
             }
         }
-        // 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 = runCreateHooks ? afterTasks : [];
         const processedCreate = await processNestedCreate(opRecord.create, fieldName, relatedListName, relatedListConfig, context, config, prisma, createAfterTasks, recovery);
@@ -708,22 +619,18 @@ async function processFieldNestedOps(fieldName, valueRecord, args, includeFields
  * parent persist via {@link runAfterTasks}). See ADR-0010.
  */
 export async function processNestedOperations(data, fieldConfigs, config, context, operation, parentListName, parentOriginalItem, 
-// 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 = undefined) {
     const afterTasks = [];
     const includeFields = new Set();
     const processed = {};
     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;
         const relatedConfig = getRelatedListConfig(relationshipField.ref, config);
         if (!relatedConfig) {
@@ -731,22 +638,17 @@ parentInputData = undefined) {
             continue;
         }
         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(fieldName, value, {
             relatedListName: resolvedListName,
             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,