json-rest-api 2.4.0 → 3.0.0

package/plugins/core/rest-api-autofilter-plugin.js

@@ -1,8 +1,12 @@
-import { RestApiValidationError } from '../../lib/rest-api-errors.js'
+import { RestApiResourceError, RestApiValidationError } from '../../lib/rest-api-errors.js'
+import { assertGenuineSystemFlag, isSystemContext } from '../../lib/system-context.js'
 import { snapshotResourceConfiguration } from './lib/querying-writing/schema-helpers.js'
 import { createStorageAdapterUtilities } from './lib/querying/storage-adapter-utils.js'
+import { ANY_OWNER, recordWriteCondition } from './lib/querying/query-constraint.js'
 
 const PUBLIC_PRESET_NAME = 'public'
+// Queries that write or lock the rows they select: shared rows are never theirs.
+const WRITE_PURPOSES = new Set(['bulk-write', 'lock', 'claim'])
 
 function valuesEqual (left, right) {
   if (left === right) return true
@@ -108,12 +112,20 @@ function normalizeFilterDefinition ({ filterDef, resolvers, schemaStructure, sco
     ? fieldDef.as
     : null
 
+  if (filterDef.shared !== undefined && typeof filterDef.shared !== 'boolean') {
+    throw new Error(`Autofilter field '${field}' on resource '${scopeName}' must set shared to true or false.`)
+  }
+  if (filterDef.shared === true && fieldDef.nullable !== true) {
+    throw new Error(`Autofilter field '${field}' on resource '${scopeName}' is shared, so it must be nullable: NULL marks a shared row.`)
+  }
+
   return {
     field,
     fieldDef,
     resolve,
     resolverName,
     required: filterDef.required !== false,
+    shared: filterDef.shared === true,
     relationshipName,
     relationshipType: relationshipName ? fieldDef.belongsTo : null,
     inputPath: relationshipName
@@ -247,8 +259,56 @@ function applyResolvedInputValue ({ context, filter, resolvedValue, injectMissin
   }
 }
 
+// A system context owns no workspace or user, so a create must say whose row it is.
+function requireExplicitOwnership ({ compiledConfig, inputRecord, scopeName, index }) {
+  const data = inputRecord?.data || {}
+  const missing = compiledConfig.filters.filter(filter => {
+    if (filter.relationshipName && data.relationships?.[filter.relationshipName]?.data !== undefined) return false
+    return data.attributes?.[filter.field] === undefined
+  })
+  if (!missing.length) return
+  const prefix = index === undefined ? '' : `data.${index}.`
+  const violations = missing.map(filter => ({
+    field: `${prefix}${filter.inputPath}`,
+    rule: 'system_ownership_required',
+    message: `A create in a system context must set '${filter.field}' explicitly${filter.shared ? ' (null for a shared row)' : ''}`
+  }))
+  throw new RestApiValidationError(`Creating '${scopeName}' records in a system context needs explicit ownership values`, {
+    fields: violations.map(violation => violation.field),
+    violations
+  })
+}
+
+// Without an owner value a shared filter would stamp NULL, creating a row every owner sees.
+function refuseSharedCreate ({ filter, resolvedValue, scopeName }) {
+  if (!filter.shared || resolvedValue !== null) return
+  throw new RestApiResourceError(`Shared ${scopeName} records can only be created in a system context`, {
+    subtype: 'forbidden', resourceType: scopeName
+  })
+}
+
+// An optional owner that did not resolve stamps nothing; the row must still not end up shared.
+function refuseSharedResult ({ compiledConfig, record, scopeName }) {
+  for (const filter of compiledConfig.filters) {
+    if (filter.shared && sharedFieldValue(record, filter) == null) refuseSharedCreate({ filter, resolvedValue: null, scopeName })
+  }
+}
+
+function sharedFieldValue (record, filter) {
+  if (filter.relationshipName) {
+    const linkage = record?.relationships?.[filter.relationshipName]?.data
+    if (linkage !== undefined) return linkage === null ? null : linkage.id
+  }
+  return record?.attributes?.[filter.field]
+}
+
 async function enforceScopedInput ({ compiledConfig, context, scopeName, injectMissing, api, helpers, scopes, vars, log }) {
   if (!compiledConfig || compiledConfig.filters.length === 0) return
+  assertGenuineSystemFlag(context)
+  if (isSystemContext(context)) {
+    if (injectMissing) requireExplicitOwnership({ compiledConfig, inputRecord: context.inputRecord, scopeName })
+    return
+  }
 
   for (const filter of compiledConfig.filters) {
     const resolvedValue = await resolveFilterValue({
@@ -263,6 +323,7 @@ async function enforceScopedInput ({ compiledConfig, context, scopeName, injectM
     })
 
     if (resolvedValue === undefined) continue
+    if (injectMissing) refuseSharedCreate({ filter, resolvedValue, scopeName })
 
     applyResolvedInputValue({
       context,
@@ -271,6 +332,7 @@ async function enforceScopedInput ({ compiledConfig, context, scopeName, injectM
       injectMissing
     })
   }
+  if (injectMissing) refuseSharedResult({ compiledConfig, record: context.inputRecord?.data, scopeName })
 }
 
 export const AutoFilterPlugin = {
@@ -304,14 +366,19 @@ export const AutoFilterPlugin = {
         resolvers: state.resolvers,
         presets: state.presets
       })
+      // Many-row writes refuse these fields and require them in upsert conflict keys.
+      schemaInfo.ownershipFields = (schemaInfo.autofilter?.filters || []).map(filter => filter.field)
     })
 
     addHook('knexQueryFiltering', 'autofilter-scope', {}, async ({ context }) => {
-      const { query, tableName, scopeName } = context.knexQuery || {}
+      const { query, tableName, scopeName, queryPurpose } = context.knexQuery || {}
       if (!query || !scopeName) return
 
       const compiledConfig = scopes[scopeName]?.vars?.schemaInfo?.autofilter
       if (!compiledConfig || compiledConfig.filters.length === 0) return
+      assertGenuineSystemFlag(context)
+      if (isSystemContext(context)) return
+      const writes = WRITE_PURPOSES.has(queryPurpose)
       const adapterUtils = createStorageAdapterUtilities({ context }, {
         getStorageAdapter: helpers.getStorageAdapter
       })
@@ -328,20 +395,39 @@ export const AutoFilterPlugin = {
           log
         })
 
-        if (resolvedValue === undefined) continue
-
         const columnRef = adapterUtils.translateColumn(scopeName, filter.field, tableName)
+        // Every scoped read records the owner a later write of its rows must
+        // still match, so a single write that reads first carries it too.
+        if (resolvedValue === undefined) {
+          // An optional owner that did not resolve: reads are not narrowed, but
+          // shared rows stay out of writes and locks.
+          if (filter.shared) {
+            if (writes) query.whereNotNull(columnRef)
+            recordWriteCondition(context, scopeName, filter.field, ANY_OWNER)
+          }
+          continue
+        }
         const translatedValue = adapterUtils.translateFilterValue(scopeName, filter.field, resolvedValue)
 
-        if (translatedValue === null) {
-          query.whereNull(columnRef)
+        if (filter.shared) {
+          // Reads see the owner's rows and the shared (NULL) ones; writes and locks only the owner's.
+          if (translatedValue === null) {
+            if (writes) query.whereRaw('1 = 0')
+            else query.whereNull(columnRef)
+          } else {
+            if (writes) query.where(columnRef, translatedValue)
+            else query.where(builder => builder.where(columnRef, translatedValue).orWhereNull(columnRef))
+            recordWriteCondition(context, scopeName, filter.field, translatedValue)
+          }
         } else {
-          query.where(columnRef, translatedValue)
+          if (translatedValue === null) query.whereNull(columnRef)
+          else query.where(columnRef, translatedValue)
+          recordWriteCondition(context, scopeName, filter.field, translatedValue)
         }
       }
     })
 
-    addHook('beforeProcessingPost', 'autofilter-stamp-post', {}, async ({ context, scopeName }) => {
+    addHook('beforeProcessingPost', 'autofilter-stamp-post', { batch: true }, async ({ context, scopeName }) => {
       await enforceScopedInput({
         compiledConfig: scopes[scopeName]?.vars?.schemaInfo?.autofilter,
         context,
@@ -369,7 +455,7 @@ export const AutoFilterPlugin = {
       })
     })
 
-    addHook('beforeProcessingPatch', 'autofilter-validate-patch', {}, async ({ context, scopeName }) => {
+    addHook('beforeProcessingPatch', 'autofilter-validate-patch', { batch: true }, async ({ context, scopeName }) => {
       await enforceScopedInput({
         compiledConfig: scopes[scopeName]?.vars?.schemaInfo?.autofilter,
         context,
@@ -383,6 +469,46 @@ export const AutoFilterPlugin = {
       })
     })
 
+    // Batch form of autofilter-stamp-post: resolve each owner value once, stamp every row.
+    addHook('beforeProcessingPostMany', 'autofilter-stamp-post-many', {}, async ({ context, scopeName }) => {
+      const compiledConfig = scopes[scopeName]?.vars?.schemaInfo?.autofilter
+      if (!compiledConfig || compiledConfig.filters.length === 0) return
+      assertGenuineSystemFlag(context)
+      if (isSystemContext(context)) {
+        context.inputRecords.forEach((inputRecord, index) => requireExplicitOwnership({ compiledConfig, inputRecord, scopeName, index }))
+        return
+      }
+      for (const filter of compiledConfig.filters) {
+        const resolvedValue = await resolveFilterValue({ filter, context, scopeName, api, helpers, scopes, vars, log })
+        if (resolvedValue === undefined) continue
+        refuseSharedCreate({ filter, resolvedValue, scopeName })
+        for (const inputRecord of context.inputRecords) {
+          applyResolvedInputValue({ context: { inputRecord }, filter, resolvedValue, injectMissing: true })
+        }
+      }
+      for (const inputRecord of context.inputRecords) refuseSharedResult({ compiledConfig, record: inputRecord?.data, scopeName })
+    })
+
+    // Shared rows are readable by every owner but writable only in a system context.
+    const refuseSharedRowWrite = ({ context, scopeName }) => {
+      const compiledConfig = scopes[scopeName]?.vars?.schemaInfo?.autofilter
+      const sharedFilters = compiledConfig?.filters.filter(filter => filter.shared) || []
+      if (!sharedFilters.length || !context.minimalRecord || isSystemContext(context)) return
+      for (const filter of sharedFilters) {
+        if (sharedFieldValue(context.minimalRecord, filter) === null) {
+          throw new RestApiResourceError(`Shared ${scopeName} records can only be changed in a system context`, {
+            subtype: 'forbidden', resourceType: scopeName, resourceId: context.id
+          })
+        }
+      }
+    }
+    addHook('beforeDataCallPatch', 'autofilter-shared-row-patch', { batch: true }, refuseSharedRowWrite)
+    addHook('beforeDataCallPut', 'autofilter-shared-row-put', { batch: true }, refuseSharedRowWrite)
+    addHook('beforeDataCallDelete', 'autofilter-shared-row-delete', { batch: true }, refuseSharedRowWrite)
+    // Links of a shared row belong to every owner that sees it.
+    addHook('beforeDataCallPostRelationship', 'autofilter-shared-row-post-relationship', {}, refuseSharedRowWrite)
+    addHook('beforeDataCallDeleteRelationship', 'autofilter-shared-row-delete-relationship', {}, refuseSharedRowWrite)
+
     api.autofilter = {
       getConfig: () => ({
         presets: Object.keys(state.presets),
@@ -398,7 +524,8 @@ export const AutoFilterPlugin = {
           filters: compiledConfig.filters.map((filter) => ({
             field: filter.field,
             resolver: filter.resolverName,
-            required: filter.required
+            required: filter.required,
+            shared: filter.shared
           }))
         }
       }

package/plugins/core/rest-api-knex-plugin.js

@@ -1,4 +1,5 @@
 import { createOrdinaryDataHelpers } from './lib/storage/ordinary-data-helpers.js'
+import { createManyRowDataHelpers } from './lib/storage/many-row-data-helpers.js'
 import { createKnexTransaction } from '../../lib/knex-transaction.js'
 import { createEnhancedLogger } from '../../lib/enhanced-logger.js'
 import { throwMissingPackage } from '../../lib/missing-package.js'
@@ -160,6 +161,7 @@ export const RestApiKnexPlugin = {
     helpers.newTransaction = context => createKnexTransaction(knex, context)
 
     Object.assign(helpers, createOrdinaryDataHelpers({ api, scopes, knex, log, getScopeStorageAdapter }))
+    Object.assign(helpers, createManyRowDataHelpers({ api, scopes, log, getScopeStorageAdapter }))
 
     log.info('RestApiKnexPlugin installed - basic CRUD operations ready')
   }

package/plugins/core/rest-api-plugin-methods/aggregate.js

@@ -1,6 +1,7 @@
 import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
 import { getEffectiveSortableFields } from '../lib/querying/query-field-sort-helpers.js'
 import { compileAggregateRequest } from '../lib/querying/aggregate-query.js'
+import { isSystemContext } from '../../../lib/system-context.js'
 
 /**
  * Group a filtered collection and compute measures for each group.
@@ -18,7 +19,8 @@ export default async function aggregateMethod ({ params, context, vars, helpers,
     schemaInfo: context.schemaInfo,
     scopeName,
     defaultLimit: vars.queryDefaultLimit,
-    maxLimit: vars.queryMaxLimit
+    maxLimit: vars.queryMaxLimit,
+    system: isSystemContext(context)
   })
   const requestContracts = getRequestContracts({
     scopeName,

package/plugins/core/rest-api-plugin-methods/common.js

@@ -6,7 +6,6 @@
  * Schema, WriteContext
  * } from './lifecycle-types.js' */
 /** @import { StorageRow } from '../lib/storage/storage-types.js' */
-/** @import { DiagnosticWriter, EnhancedDiagnosticLogger } from '../../../lib/logger-types.js' */
 /** @import { RuntimeLogger } from '../../../types/runtime.js' */
 import { initializeResourceVersion } from '../lib/writing/resource-version.js'
 import {
@@ -16,7 +15,6 @@ import {
 } from '../../../lib/rest-api-errors.js'
 import { transformSimplifiedToJsonApi } from '../lib/querying-writing/simplified-helpers.js'
 import { normalizeRelationshipIdentifiers } from '../lib/querying-writing/resource-id-normalization.js'
-import { createEnhancedLogger } from '../../../lib/enhanced-logger.js'
 import { rejectRemovedOptions, resolveFormat, resolveReturning } from '../lib/querying-writing/response-options.js'
 import {
   getRequestContracts,
@@ -27,26 +25,11 @@ import { normalizeRecordAttributes } from '../lib/querying-writing/database-valu
 import { beginWriteTransaction, commitTransaction, getOperationDiagnosticContext, isTransactionOwner, rollbackAfterError, wrapUnexpectedError } from '../../../lib/error-context.js'
 import { filterVisibleIdentifiers } from '../lib/querying/include-query-helpers.js'
 import { findRelationshipDefinition } from '../lib/querying-writing/relationship-contracts.js'
-import { RELATIONSHIP_READ_BATCH_SIZE } from '../lib/querying-writing/knex-constants.js'
 import { getResourceFieldset, parseFieldset } from '../lib/querying-writing/field-utils.js'
 
 // A trusted connector callback, evaluated after normal write validation and authorization.
 export const writePrecondition = Symbol('writePrecondition')
 
-/**
- * Gets an enhanced logger instance with full error details and stack traces
- * @param {RuntimeLogger} log - The base logger instance
- * @param {{ schemaInfo?: LifecycleSchema }} context - Request context carrying compiled field visibility
- * @returns {EnhancedDiagnosticLogger & { error: DiagnosticWriter }} Enhanced logger instance
- */
-export const getEnhancedLogger = (log, context = {}) => {
-  return createEnhancedLogger(log, {
-    logFullErrors: true,
-    includeStack: true,
-    schemaInfo: context.schemaInfo
-  })
-}
-
 /**
  * Resolves write input, response options and the managed transaction.
  * @param {Pick<LifecycleArguments, 'params' | 'vars' | 'scopes' | 'scopeName' | 'api' | 'helpers' | 'runHooks'> & { context: LifecycleContext<Resource | Resource[] | null, unknown> }} options
@@ -107,11 +90,18 @@ export const handleWriteMethodError = async (error, context, method, scopeName,
   await rollbackAfterError(error, context, context.transaction)
   const cleanupErrors = context.cleanupErrors || (context.cleanupErrors = [])
 
+  // The resource, the operation and error codes only: input, error messages and
+  // SQL can carry the values being written (payment state, ciphertext).
+  /** @param {unknown} value */
+  const codeOf = value => {
+    const { code, name } = /** @type {{ code?: unknown, name?: unknown }} */ (Object(value))
+    return typeof code === 'string' || typeof code === 'number' ? code : typeof name === 'string' ? name : null
+  }
   try {
-    await getEnhancedLogger(log, context).logError(`Error in ${method} method`, error, {
+    await log.error(`Error in ${method} method`, {
       ...getOperationDiagnosticContext(context, { phase: 'writeFailure', scopeName, method: context.method ?? method.toLowerCase() }),
-      inputRecord: context.inputRecord,
-      cleanupErrors
+      code: codeOf(error),
+      cleanupErrors: cleanupErrors.map(({ phase, error }) => ({ phase, code: codeOf(error) }))
     })
   } catch (error) {
     cleanupErrors.push({ phase: 'logging', error })
@@ -212,6 +202,8 @@ export const validateCompleteReplacePayload = ({
   for (const [fieldName, fieldDef] of Object.entries(schemaStructure)) {
     if (!fieldDef) continue
     if (fieldName === idProperty) continue
+    // The library owns the lock version: every update advances it, whatever the input says.
+    if (fieldName === schemaInfo.lockVersionField) continue
     if (Object.hasOwn(belongsToUpdates, fieldName)) continue
     if (fieldDef.computed === true || fieldDef.virtual === true || fieldDef.retired === true) continue
     if (fieldDef.type === undefined) continue
@@ -292,7 +284,11 @@ export const validateResourceAttributesBeforeWrite = async ({
     ...(hasLogicalIdField && resourceId !== undefined ? { id: resourceId } : {})
   }
 
-  // Physical foreign keys may enter storage only through relationship planning.
+  // Physical foreign keys, and the type and id fields behind a polymorphic
+  // belongs-to, may enter storage only through relationship planning.
+  /** @type {Map<string, string>} */
+  const polymorphicFields = new Map(Object.entries(context.schemaInfo.schemaRelationships || {}).flatMap(([name, relationship]) =>
+    relationship.belongsToPolymorphic ? [[relationship.belongsToPolymorphic.typeField, name], [relationship.belongsToPolymorphic.idField, name]] : []))
   /** @type {StorageRow} */
   const attributesForValidation = { ...attributesToValidate }
   const foreignKeyViolations = []
@@ -306,13 +302,14 @@ export const validateResourceAttributesBeforeWrite = async ({
         message: `Field '${field}' is retired and accepts no new values`
       })
     }
-    if (!definition?.belongsTo || !definition.as || Object.hasOwn(belongsToUpdates, field)) continue
+    const relationshipName = definition?.belongsTo && definition.as ? definition.as : polymorphicFields.get(field)
+    if (!relationshipName || Object.hasOwn(belongsToUpdates, field)) continue
     delete attributesForValidation[field]
     if (value === undefined) continue
     foreignKeyViolations.push({
       field: `data.attributes.${field}`,
       rule: 'foreign_key_in_attributes',
-      message: `Foreign key field '${field}' should not be in attributes. Use 'data.relationships.${definition.as}' instead.`
+      message: `Foreign key field '${field}' should not be in attributes. Use 'data.relationships.${relationshipName}' instead.`
     })
   }
   const [firstRetired] = retiredViolations
@@ -387,17 +384,25 @@ export const validateResourceAttributesBeforeWrite = async ({
  */
 export const validateRelationshipAccess = async (context, inputRecord, helpers, api) => {
   if (!inputRecord?.data?.relationships) return
-
-  // Targets of every relationship, so each type is read once per record.
   const unique = new Map()
-  for (const [relName, relData] of Object.entries(inputRecord.data.relationships)) {
+  collectRelationshipTargets(inputRecord, api, unique)
+  await validateRelationshipTargets(context, [...unique.values()], helpers, api)
+}
+
+/**
+ * Normalizes a document's relationship identifiers and adds each target to
+ * `unique`, so a batch of documents reads every related type once.
+ * @param {InputDocument} inputRecord
+ * @param {LifecycleApi} api
+ * @param {Map<string, Identifier>} unique
+ */
+export const collectRelationshipTargets = (inputRecord, api, unique) => {
+  const relationships = /** @type {NonNullable<InputDocument['data']['relationships']>} */ (inputRecord?.data?.relationships || {})
+  for (const [relName, relData] of Object.entries(relationships)) {
     if (!relData?.data) continue
 
     const normalizedRelationshipData = /** @type {Identifier | Identifier[]} */ (normalizeRelationshipIdentifiers(relData.data, { api }))
-    inputRecord.data.relationships[relName] = {
-      ...relData,
-      data: normalizedRelationshipData
-    }
+    relationships[relName] = { ...relData, data: normalizedRelationshipData }
 
     // Handle both single and array relationships
     const relatedItems = Array.isArray(normalizedRelationshipData)
@@ -406,60 +411,69 @@ export const validateRelationshipAccess = async (context, inputRecord, helpers,
 
     for (const item of relatedItems) unique.set(JSON.stringify([item.type, item.id]), item)
   }
-  const targets = [...unique.values()]
-  for (let offset = 0; offset < targets.length; offset += RELATIONSHIP_READ_BATCH_SIZE) {
-    const batch = targets.slice(offset, offset + RELATIONSHIP_READ_BATCH_SIZE)
-    /** @type {Map<string, Identifier[]>} */
-    const byType = new Map()
-    for (const item of batch) {
-      const items = byType.get(item.type)
-      if (items) items.push(item)
-      else byType.set(item.type, [item])
+}
+
+/**
+ * Checks that every target is visible to the caller, with one scoped read per
+ * related type, however many targets there are.
+ * @param {ResourceContext} context
+ * @param {Identifier[]} targets
+ * @param {LifecycleHelpers} helpers
+ * @param {LifecycleApi} api
+ */
+export const validateRelationshipTargets = async (context, targets, helpers, api) => {
+  /** @type {Map<string, Identifier[]>} */
+  const byType = new Map()
+  for (const item of targets) {
+    const items = byType.get(item.type)
+    if (items) items.push(item)
+    else byType.set(item.type, [item])
+  }
+  const lookups = new Map()
+  for (const [type, items] of byType) {
+    const relatedScope = api.resources[type]
+    if (!relatedScope) throw new Error(`Unknown resource type: ${type}`)
+    const getContext = {
+      ...context,
+      id: undefined,
+      minimalRecord: undefined,
+      schemaInfo: relatedScope.vars.schemaInfo,
+      scopeName: type,
+      queryParams: {},
+      method: 'get',
+      isUpdate: false
     }
-    const lookups = new Map()
-    for (const [type, items] of byType) {
-      const relatedScope = api.resources[type]
-      if (!relatedScope) throw new Error(`Unknown resource type: ${type}`)
-      const getContext = {
-        ...context,
-        id: undefined,
-        minimalRecord: undefined,
-        schemaInfo: relatedScope.vars.schemaInfo,
-        scopeName: type,
-        queryParams: {},
-        method: 'get',
-        isUpdate: false
-      }
-      const lookup = {
-        scopeName: type,
-        context: getContext,
-        /** @param {import('../lib/storage/storage-types.js').QueryFilteringState} filterParams */
-        applyQueryFilters: filterParams => relatedScope.applyQueryFilters({
-          ...filterParams, schemaInfo: getContext.schemaInfo
-        }, getContext),
-        filters: {},
-        queryPurpose: 'relationship-validation'
-      }
-      const records = await helpers.dataGetMinimal({ ...lookup, ids: items.map(item => item.id) })
-      lookups.set(type, { relatedScope, lookup, records: new Map(records.map(record => [String(record.id), record])) })
+    const lookup = {
+      scopeName: type,
+      context: getContext,
+      /** @param {import('../lib/storage/storage-types.js').QueryFilteringState} filterParams */
+      applyQueryFilters: filterParams => relatedScope.applyQueryFilters({
+        ...filterParams, schemaInfo: getContext.schemaInfo
+      }, getContext),
+      filters: {},
+      queryPurpose: 'relationship-validation'
     }
-    for (const item of batch) {
-      const { relatedScope, lookup, records } = lookups.get(item.type)
-      // A database collation can equate IDs with different spellings.
-      const record = records.get(String(item.id)) || await helpers.dataGetMinimal({
-        ...lookup, context: { ...lookup.context, id: item.id }
-      })
-      if (!record) {
-        throw new RestApiResourceError(
-          `Cannot create relationship to non-existent ${item.type} with id ${item.id}`,
-          { subtype: 'not_found', resourceType: item.type, resourceId: item.id }
-        )
-      }
-      await relatedScope.checkPermissions({
-        method: 'get',
-        originalContext: { ...lookup.context, id: item.id, minimalRecord: record }
-      })
+    const records = new Map()
+    for (const record of await helpers.dataGetMinimal({ ...lookup, ids: items.map(item => item.id) })) records.set(String(record.id), record)
+    lookups.set(type, { relatedScope, lookup, records })
+  }
+  // In the order given, so the first missing or forbidden target is the one reported.
+  for (const item of targets) {
+    const { relatedScope, lookup, records } = lookups.get(item.type)
+    // A database collation can equate IDs with different spellings.
+    const record = records.get(String(item.id)) || await helpers.dataGetMinimal({
+      ...lookup, context: { ...lookup.context, id: item.id }
+    })
+    if (!record) {
+      throw new RestApiResourceError(
+        `Cannot create relationship to non-existent ${item.type} with id ${item.id}`,
+        { subtype: 'not_found', resourceType: item.type, resourceId: item.id }
+      )
     }
+    await relatedScope.checkPermissions({
+      method: 'get',
+      originalContext: { ...lookup.context, id: item.id, minimalRecord: record }
+    })
   }
 }
 
@@ -637,15 +651,61 @@ export const filterToOneResponseLinkage = async (context, scopes) => {
       if ((definition?.belongsTo || definition?.belongsToPolymorphic) && relationship.data) linkages.push(relationship)
     }
   }
-  if (linkages.length === 0) return
+  // A target the response already includes is no secret, so it needs no read.
+  const key = (/** @type {Identifier} */ { type, id }) => `${type}:${id}`
+  const included = new Set((document?.included || []).map(key))
+  // The links collected above are to-one links with a target.
+  const unchecked = linkages.filter(relationship => !included.has(key(/** @type {Identifier} */ (relationship.data))))
+  if (unchecked.length === 0) return
   const visible = new Set(await filterVisibleIdentifiers({
-    identifiers: linkages.map(relationship => relationship.data), scopes, knex: context.db, context
+    identifiers: unchecked.map(relationship => relationship.data), scopes, knex: context.db, context
   }))
-  for (const relationship of linkages) {
+  for (const relationship of unchecked) {
     if (!visible.has(relationship.data)) relationship.data = null
   }
 }
 
+/**
+ * A read shows a link whose target its reader cannot see as null (above), so a
+ * reader that writes the record back sends that null for a link it never saw.
+ * The write keeps such a link: a belongs-to that `updates` sets to null, whose
+ * stored target exists but is hidden from the writer, is dropped from
+ * `updates` and from the input, and stays as stored. A link to
+ * a visible target, or to one that no longer exists, is cleared as asked.
+ * @param {{ context: ResourceContext, scopes: Record<string, LifecycleResource>, schemaInfo: any, rows: Array<{ updates: Record<string, unknown>, stored: any, inputRecord?: any }> }} request
+ */
+export const keepHiddenLinks = async ({ context, scopes, schemaInfo, rows }) => {
+  const links = [
+    ...Object.entries(schemaInfo.schemaStructure)
+      .filter(([, field]) => field.belongsTo && field.as)
+      .map(([name, field]) => ({ name: field.as, fields: [name] })),
+    ...Object.entries(schemaInfo.schemaRelationships || {})
+      .filter(([, relationship]) => relationship.belongsToPolymorphic)
+      .map(([name, { belongsToPolymorphic: { typeField, idField } }]) => ({ name, fields: [typeField, idField] }))
+  ]
+  const cleared = []
+  for (const row of rows) {
+    for (const link of links) {
+      const data = row.stored?.relationships?.[link.name]?.data
+      if (data && link.fields.every(field => Object.hasOwn(row.updates, field) && row.updates[field] === null)) cleared.push({ row, link, data })
+    }
+  }
+  if (!cleared.length) return
+  const visible = new Set(await filterVisibleIdentifiers({ identifiers: cleared.map(entry => entry.data), scopes, knex: context.db, context }))
+  const hidden = cleared.filter(entry => !visible.has(entry.data))
+  if (!hidden.length) return
+  const existing = new Set(await filterVisibleIdentifiers({ identifiers: hidden.map(entry => entry.data), scopes, knex: context.db, context, scoped: false }))
+  for (const { row, link, data } of hidden) {
+    if (!existing.has(data)) continue
+    for (const field of link.fields) {
+      delete row.updates[field]
+      // Validation has merged the belongs-to updates into the input attributes.
+      delete row.inputRecord?.data?.attributes?.[field]
+    }
+    delete row.inputRecord?.data?.relationships?.[link.name]
+  }
+}
+
 /** @param {ResourceContext} context @param {Record<string, LifecycleResource>} scopes @param {string[]} [resourceTypes] */
 export const validateRequestedIncludes = (context, scopes, resourceTypes = [context.scopeName]) => {
   const paths = context.queryParams?.include || []