velocious 1.0.448 → 1.0.450

package/src/frontend-models/base.js

@@ -16,10 +16,32 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
 
 /**
  * FrontendModelCommandType type.
-  @typedef {"create" | "find" | "index" | "update" | "destroy" | "attach" | "download" | "url"} FrontendModelCommandType */
+ * @typedef {"create" | "find" | "index" | "update" | "destroy" | "attach" | "download" | "url"} FrontendModelCommandType */
 /**
  * FrontendModelRequestCommandType type.
-  @typedef {FrontendModelCommandType | string} FrontendModelRequestCommandType */
+ * @typedef {FrontendModelCommandType | string} FrontendModelRequestCommandType */
+/**
+ * Model-like instance value supported by frontend-model transport.
+ * @typedef {{attributes: () => Record<string, unknown>}} FrontendModelTransportModelValue
+ */
+/**
+ * Special scalar values restored by frontend-model transport.
+ * @typedef {undefined | null | boolean | number | string | bigint | Date | FrontendModelTransportModelValue} FrontendModelTransportScalarValue
+ */
+/**
+ * Plain object supported by frontend-model transport values.
+ * Nested values are intentionally opaque because TypeScript rejects recursive
+ * JSDoc typedefs for this transport value contract.
+ * @typedef {Record<string, unknown>} FrontendModelTransportObject
+ */
+/**
+ * Value supported by frontend-model transport serialization and deserialization.
+ * @typedef {FrontendModelTransportScalarValue | FrontendModelTransportObject | Array<unknown>} FrontendModelTransportValue
+ */
+/**
+ * Frontend model attribute value used when generated metadata cannot infer a narrower type.
+ * @typedef {FrontendModelTransportValue} FrontendModelAttributeValue
+ */
 /**
  * Defines this typedef.
  * @typedef {{type: "hasOne" | "hasMany"}} FrontendModelAttachmentDefinition
@@ -34,11 +56,27 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  */
 /**
  * Frontend model constructor type.
- * @typedef {{new (attributes?: Record<string, ?>): FrontendModelBase}} FrontendModelConstructor
+ * @template {FrontendModelBase} [T=FrontendModelBase]
+ * @typedef {{new (attributes?: Record<string, FrontendModelAttributeValue>): T}} FrontendModelConstructor
  */
 /**
- * Frontend model static side without generated per-model create overloads.
- * @typedef {FrontendModelConstructor & Omit<typeof FrontendModelBase, "create">} FrontendModelClass
+ * Frontend model static side.
+ * @template {FrontendModelBase} [T=FrontendModelBase]
+ * @template {Record<string, FrontendModelAttributeValue>} [Attributes=Record<string, FrontendModelAttributeValue>]
+ * @template {Record<string, FrontendModelAttributeValue>} [CreateAttributes=Record<string, FrontendModelAttributeValue>]
+ * @typedef {{new (): T, create(attributes?: CreateAttributes): Promise<T>} & Omit<typeof FrontendModelBase, "create">} FrontendModelClass
+ */
+/**
+ * Create attributes accepted by a frontend model instance.
+ * @template {FrontendModelBase} T
+ * @typedef {T extends FrontendModelBase<Record<string, FrontendModelAttributeValue>, infer CreateAttributes, infer _UpdateAttributes> ? CreateAttributes : Record<string, FrontendModelAttributeValue>} FrontendModelCreateAttributesFor
+ */
+/**
+ * Loaded instance type for relationship helper generics. Older generated
+ * frontend models passed model classes into relationship helpers, while newer
+ * generated models pass instance types.
+ * @template {FrontendModelBase | typeof FrontendModelBase} T
+ * @typedef {T extends new (...args: any[]) => infer Instance ? Instance : T} FrontendModelRelationshipModel
  */
 /**
  * FrontendModelTransportConfig type.
@@ -59,7 +97,7 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
 
 /**
  * Frontend model transport config.
-  @type {FrontendModelTransportConfig} */
+ * @type {FrontendModelTransportConfig} */
 const frontendModelTransportConfig = {}
 const SHARED_FRONTEND_MODEL_API_PATH = "/frontend-models"
 const PRELOADED_RELATIONSHIPS_KEY = "__preloadedRelationships"
@@ -69,19 +107,19 @@ const QUERY_DATA_KEY = "__queryData"
 const ABILITIES_KEY = "__abilities"
 /**
  * Pending shared frontend model requests.
-  @type {Array<{commandName?: string, commandType: FrontendModelRequestCommandType, customPath?: string, modelClass: FrontendModelClass, payload: Record<string, ?>, requestId: string, resolve: (response: Record<string, ?>) => void, reject: (error: ?) => void, resourcePath?: string | null}>} */
+ * @type {Array<{commandName?: string, commandType: FrontendModelRequestCommandType, customPath?: string, modelClass: FrontendModelClass, payload: Record<string, ?>, requestId: string, resolve: (response: Record<string, ?>) => void, reject: (error: ?) => void, resourcePath?: string | null}>} */
 let pendingSharedFrontendModelRequests = []
 let sharedFrontendModelRequestId = 0
 let sharedFrontendModelFlushScheduled = false
 let activeFrontendModelTransportRequestCount = 0
 /**
  * Frontend model idle resolvers.
-  @type {Array<() => void>} */
+ * @type {Array<() => void>} */
 let frontendModelIdleResolvers = []
 
 /**
  * Internal websocket client.
-  @type {VelociousWebsocketClient | null} */
+ * @type {VelociousWebsocketClient | null} */
 let internalWebsocketClient = null
 
 /**
@@ -96,7 +134,7 @@ function frontendModelTransportIsIdle() {
 
 /**
  * Runs resolve frontend model idle waiters.
-  @returns {void} */
+ * @returns {void} */
 function resolveFrontendModelIdleWaiters() {
   if (!frontendModelTransportIsIdle()) return
 
@@ -189,7 +227,7 @@ function resolveInternalWebsocketClient() {
 
 /**
  * Runs flush buffered outgoing events after reconnect.
-  @returns {Promise<void>} */
+ * @returns {Promise<void>} */
 async function flushBufferedOutgoingEventsAfterReconnect() {
   if (!internalWebsocketClient) return
 
@@ -238,27 +276,29 @@ export class AttributeNotSelectedError extends Error {
 
 /**
  * Lightweight singular relationship state holder for frontend model instances.
- * @template {FrontendModelClass} S
- * @template {FrontendModelClass} T
+ * @template {FrontendModelBase | typeof FrontendModelBase} S
+ * @template {FrontendModelBase | typeof FrontendModelBase} T
+ * @template {Record<string, FrontendModelAttributeValue>} [TargetCreateAttributes=Record<string, FrontendModelAttributeValue>]
  */
 export class FrontendModelSingularRelationship {
   /**
    * Runs constructor.
-   * @param {InstanceType<S>} model - Parent model.
+   * @param {FrontendModelBase} model - Parent model.
    * @param {string} relationshipName - Relationship name.
-   * @param {T | null} targetModelClass - Target model class.
+   * @param {FrontendModelClass<FrontendModelRelationshipModel<T>, Record<string, FrontendModelAttributeValue>, TargetCreateAttributes> | null} targetModelClass - Target model class.
    */
   constructor(model, relationshipName, targetModelClass) {
     this.model = model
     this.relationshipName = relationshipName
     this.targetModelClass = targetModelClass
     this._preloaded = false
+    /** @type {FrontendModelRelationshipModel<T> | null} */
     this._loadedValue = null
   }
 
   /**
    * Runs set loaded.
-   * @param {?} loadedValue - Loaded relationship value.
+   * @param {FrontendModelRelationshipModel<T> | null | undefined} loadedValue - Loaded relationship value.
    * @returns {void}
    */
   setLoaded(loadedValue) {
@@ -276,7 +316,7 @@ export class FrontendModelSingularRelationship {
 
   /**
    * Runs loaded.
-   * @returns {?} - Loaded relationship value.
+   * @returns {FrontendModelRelationshipModel<T> | null} - Loaded relationship value.
    */
   loaded() {
     if (!this._preloaded) {
@@ -286,42 +326,91 @@ export class FrontendModelSingularRelationship {
     return this._loadedValue
   }
 
+  /**
+   * Copies loaded value from another singular relationship helper.
+   * @param {FrontendModelRelationship} sourceRelationship - Source relationship helper.
+   * @returns {void}
+   */
+  copyLoadedFrom(sourceRelationship) {
+    if (sourceRelationship instanceof FrontendModelHasManyRelationship) {
+      throw new Error(`Expected ${this.model.constructor.name}#${this.relationshipName} source relationship to be singular`)
+    }
+
+    // Narrows the runtime value to the target relationship's documented model type.
+    const loadedValue = /** @type {FrontendModelRelationshipModel<T> | null} */ (sourceRelationship.loaded())
+
+    this.setLoaded(loadedValue)
+  }
+
   /**
    * Runs build.
-   * @param {Record<string, ?>} [attributes] - New model attributes.
-   * @returns {InstanceType<T>} - Built model.
+   * @param {TargetCreateAttributes} [attributes] - New model attributes.
+   * @returns {FrontendModelRelationshipModel<T>} - Built model.
    */
-  build(attributes = {}) {
+  build(attributes = /** @type {TargetCreateAttributes} */ ({})) {
     if (!this.targetModelClass) {
       throw new Error(`No target model class configured for ${this.model.constructor.name}#${this.relationshipName}`)
     }
 
-    const model = /**
-                   * Narrows the runtime value to the documented type.
-                    @type {InstanceType<T>} */ (new this.targetModelClass(attributes))
+    const ModelClass = /** @type {new (attributes?: TargetCreateAttributes) => FrontendModelRelationshipModel<T>} */ (this.targetModelClass)
+    const model = new ModelClass(attributes)
 
     this.setLoaded(model)
 
     return model
   }
+
+  /**
+   * Force-reload the relationship.
+   * @returns {Promise<FrontendModelRelationshipModel<T> | null>} - Loaded relationship model.
+   */
+  async load() {
+    this._preloaded = false
+    this._loadedValue = null
+
+    const batched = await this.model._tryCohortPreload(this.relationshipName)
+
+    if (batched) return this.loaded()
+
+    await this.model.loadRelationship(this.relationshipName)
+
+    return this.loaded()
+  }
+
+  /**
+   * Returns the loaded relationship or loads it.
+   * @returns {Promise<FrontendModelRelationshipModel<T> | null>} - Loaded relationship model.
+   */
+  async orLoad() {
+    if (this.getPreloaded()) return this.loaded()
+
+    const batched = await this.model._tryCohortPreload(this.relationshipName)
+
+    if (batched) return this.loaded()
+
+    await this.model.loadRelationship(this.relationshipName)
+
+    return this.loaded()
+  }
 }
 
 /**
  * Lightweight has-many relationship state holder for frontend model instances.
- * @template {FrontendModelClass} S
- * @template {FrontendModelClass} T
+ * @template {FrontendModelBase | typeof FrontendModelBase} S
+ * @template {FrontendModelBase | typeof FrontendModelBase} T
+ * @template {Record<string, FrontendModelAttributeValue>} [TargetCreateAttributes=Record<string, FrontendModelAttributeValue>]
  */
 export class FrontendModelHasManyRelationship {
   /**
    * Narrows the runtime value to the documented type.
-    @type {Array<InstanceType<T>>} */
+   * @type {Array<FrontendModelRelationshipModel<T>>} */
   _loadedValue
 
   /**
    * Runs constructor.
-   * @param {InstanceType<S>} model - Parent model.
+   * @param {FrontendModelBase} model - Parent model.
    * @param {string} relationshipName - Relationship name.
-   * @param {T | null} targetModelClass - Target model class.
+   * @param {FrontendModelClass<FrontendModelRelationshipModel<T>, Record<string, FrontendModelAttributeValue>, TargetCreateAttributes> | null} targetModelClass - Target model class.
    */
   constructor(model, relationshipName, targetModelClass) {
     this.model = model
@@ -333,11 +422,15 @@ export class FrontendModelHasManyRelationship {
 
   /**
    * Runs set loaded.
-   * @param {Array<InstanceType<T>>} loadedValue - Loaded relationship value.
+   * @param {Array<FrontendModelRelationshipModel<T>>} loadedValue - Loaded relationship value.
    * @returns {void}
    */
   setLoaded(loadedValue) {
-    this._loadedValue = Array.isArray(loadedValue) ? loadedValue : []
+    if (!Array.isArray(loadedValue)) {
+      throw new Error(`Expected ${this.model.constructor.name}#${this.relationshipName} to be loaded with an array`)
+    }
+
+    this._loadedValue = loadedValue
     this._preloaded = true
   }
 
@@ -351,7 +444,7 @@ export class FrontendModelHasManyRelationship {
 
   /**
    * Runs loaded.
-   * @returns {Array<InstanceType<T>>} - Loaded relationship values.
+   * @returns {Array<FrontendModelRelationshipModel<T>>} - Loaded relationship values.
    */
   loaded() {
     if (!this._preloaded) {
@@ -361,9 +454,25 @@ export class FrontendModelHasManyRelationship {
     return this._loadedValue
   }
 
+  /**
+   * Copies loaded value from another has-many relationship helper.
+   * @param {FrontendModelRelationship} sourceRelationship - Source relationship helper.
+   * @returns {void}
+   */
+  copyLoadedFrom(sourceRelationship) {
+    if (!(sourceRelationship instanceof FrontendModelHasManyRelationship)) {
+      throw new Error(`Expected ${this.model.constructor.name}#${this.relationshipName} source relationship to be has-many`)
+    }
+
+    // Narrows the runtime value to the target relationship's documented model type.
+    const loadedValue = /** @type {Array<FrontendModelRelationshipModel<T>>} */ (sourceRelationship.loaded())
+
+    this.setLoaded(loadedValue)
+  }
+
   /**
    * Runs add to loaded.
-   * @param {Array<InstanceType<T>>} models - Models to append.
+   * @param {Array<FrontendModelRelationshipModel<T>>} models - Models to append.
    * @returns {void}
    */
   addToLoaded(models) {
@@ -374,17 +483,16 @@ export class FrontendModelHasManyRelationship {
 
   /**
    * Runs build.
-   * @param {Record<string, ?>} [attributes] - New model attributes.
-   * @returns {InstanceType<T>} - Built model.
+   * @param {TargetCreateAttributes} [attributes] - New model attributes.
+   * @returns {FrontendModelRelationshipModel<T>} - Built model.
    */
-  build(attributes = {}) {
+  build(attributes = /** @type {TargetCreateAttributes} */ ({})) {
     if (!this.targetModelClass) {
       throw new Error(`No target model class configured for ${this.model.constructor.name}#${this.relationshipName}`)
     }
 
-    const model = /**
-                   * Narrows the runtime value to the documented type.
-                    @type {InstanceType<T>} */ (new this.targetModelClass(attributes))
+    const ModelClass = /** @type {new (attributes?: TargetCreateAttributes) => FrontendModelRelationshipModel<T>} */ (this.targetModelClass)
+    const model = new ModelClass(attributes)
 
     this.addToLoaded([model])
 
@@ -397,25 +505,25 @@ export class FrontendModelHasManyRelationship {
    * batched into one request via the cohort preloader. The scoped query path
    * (`Model.where(...).preload([name]).toArray()` directly from user code)
    * bypasses cohort batching by design.
-   * @returns {Promise<Array<InstanceType<T>>>} - Loaded relationship models.
+   * @returns {Promise<Array<FrontendModelRelationshipModel<T>>>} - Loaded relationship models.
    */
   async load() {
     // Reset so the cohort preloader (or single-record fallback) repopulates.
     this._preloaded = false
     this._loadedValue = []
 
-    const batched = await /**
-                           * Narrows the runtime value to the documented type.
-                            @type {?} */ (this.model)._tryCohortPreload(this.relationshipName)
+    const batched = await this.model._tryCohortPreload(this.relationshipName)
 
     if (batched) return this._loadedValue
 
-    return /** Narrows the runtime value to the documented type. @type {Promise<Array<InstanceType<T>>>} */ (this.model.loadRelationship(this.relationshipName))
+    await this.model.loadRelationship(this.relationshipName)
+
+    return this.loaded()
   }
 
   /**
    * Runs to array.
-   * @returns {Promise<Array<InstanceType<T>>>} - Loaded relationship models.
+   * @returns {Promise<Array<FrontendModelRelationshipModel<T>>>} - Loaded relationship models.
    */
   async toArray() {
     if (this.getPreloaded() || this._loadedValue.length > 0) {
@@ -426,6 +534,22 @@ export class FrontendModelHasManyRelationship {
   }
 }
 
+/**
+ * Frontend model relationship helper type.
+ * @typedef {FrontendModelHasManyRelationship<FrontendModelBase, FrontendModelBase, Record<string, FrontendModelAttributeValue>> | FrontendModelSingularRelationship<FrontendModelBase, FrontendModelBase, Record<string, FrontendModelAttributeValue>>} FrontendModelRelationship
+ */
+
+/**
+ * Copies loaded relationship state between helpers of the same relationship shape.
+ * @param {object} args - Arguments.
+ * @param {FrontendModelRelationship} args.sourceRelationship - Source relationship helper.
+ * @param {FrontendModelRelationship} args.targetRelationship - Target relationship helper.
+ * @returns {void}
+ */
+function copyLoadedRelationshipValue({sourceRelationship, targetRelationship}) {
+  targetRelationship.copyLoadedFrom(sourceRelationship)
+}
+
 /**
  * Runs relationship type is collection.
  * @param {string} relationshipType - Relationship type.
@@ -499,7 +623,7 @@ export class FrontendModelAttachmentDownload {
 function frontendModelAttachmentCommandPayload(attachment, attachmentId) {
   /**
    * Payload.
-    @type {Record<string, ?>} */
+   * @type {Record<string, ?>} */
   const payload = {
     attachmentName: attachment.attachmentName,
     id: attachment.model.primaryKeyValue()
@@ -527,7 +651,7 @@ function frontendAttachmentValueIsBytes(value) {
 function frontendAttachmentValueSupportsArrayBuffer(value) {
   return Boolean(value && typeof value === "object" && typeof /**
                                                                * Narrows the runtime value to the documented type.
-                                                                @type {?} */ (value).arrayBuffer === "function")
+                                                               * @type {?} */ (value).arrayBuffer === "function")
 }
 
 /**
@@ -540,10 +664,10 @@ function frontendAttachmentNormalizeBytes(value) {
   if (value instanceof ArrayBuffer) return new Uint8Array(value)
   if (typeof Buffer !== "undefined" && Buffer.isBuffer(/**
                                                         * Narrows the runtime value to the documented type.
-                                                         @type {?} */ (value))) {
+                                                        * @type {?} */ (value))) {
     return new Uint8Array(/**
                            * Narrows the runtime value to the documented type.
-                            @type {Buffer} */ (value))
+                           * @type {Buffer} */ (value))
   }
 
   throw new Error("Unsupported attachment bytes value")
@@ -676,21 +800,21 @@ async function normalizeFrontendAttachmentInput(input) {
       contentBase64: frontendAttachmentBytesToBase64(bytes),
       contentType: typeof /**
                            * Narrows the runtime value to the documented type.
-                            @type {?} */ (input).type === "string" && /**
+                           * @type {?} */ (input).type === "string" && /**
                                                                        * Narrows the runtime value to the documented type.
-                                                                        @type {?} */ (input).type.length > 0
+                                                                       * @type {?} */ (input).type.length > 0
         ? /**
            * Narrows the runtime value to the documented type.
-            @type {?} */ (input).type
+           * @type {?} */ (input).type
         : null,
       filename: typeof /**
                         * Narrows the runtime value to the documented type.
-                         @type {?} */ (input).name === "string" && /**
+                        * @type {?} */ (input).name === "string" && /**
                                                                     * Narrows the runtime value to the documented type.
-                                                                     @type {?} */ (input).name.length > 0
+                                                                    * @type {?} */ (input).name.length > 0
         ? /**
            * Narrows the runtime value to the documented type.
-            @type {?} */ (input).name
+           * @type {?} */ (input).name
         : "attachment.bin"
     }
   }
@@ -698,7 +822,7 @@ async function normalizeFrontendAttachmentInput(input) {
   if (frontendAttachmentValueIsBytes(input)) {
     const bytes = frontendAttachmentNormalizeBytes(/**
                                                     * Narrows the runtime value to the documented type.
-                                                     @type {Uint8Array | Buffer | ArrayBuffer} */ (input))
+                                                    * @type {Uint8Array | Buffer | ArrayBuffer} */ (input))
 
     return {
       contentBase64: frontendAttachmentBytesToBase64(bytes),
@@ -898,7 +1022,7 @@ function frontendModelTransportUrl() {
  * @returns {Record<string, ?>} - Cloned attributes hash.
  */
 function cloneFrontendModelAttributes(value) {
-  return /** Narrows the runtime value to the documented type. @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(serializeFrontendModelTransportValue(value)))
+  return /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(serializeFrontendModelTransportValue(value)))
 }
 
 /**
@@ -943,10 +1067,10 @@ function mergeFrontendModelEventPreload(target, source) {
     mergeFrontendModelEventPreload(
       /**
        * Narrows the runtime value to the documented type.
-        @type {Record<string, import("./query.js").FrontendModelTransportValue>} */ (target[relationshipName]),
+       * @type {Record<string, import("./query.js").FrontendModelTransportValue>} */ (target[relationshipName]),
       /**
        * Narrows the runtime value to the documented type.
-        @type {Record<string, import("./query.js").FrontendModelTransportValue>} */ (value)
+       * @type {Record<string, import("./query.js").FrontendModelTransportValue>} */ (value)
     )
   }
 }
@@ -1038,7 +1162,7 @@ function frontendModelMatchedEventFilterKeys(body) {
 
   const keys = /**
                 * Narrows the runtime value to the documented type.
-                 @type {{matchedEventFilterKeys?: ?}} */ (body).matchedEventFilterKeys
+                * @type {{matchedEventFilterKeys?: ?}} */ (body).matchedEventFilterKeys
 
   if (!Array.isArray(keys)) return new Set()
 
@@ -1091,56 +1215,57 @@ class FrontendModelEventSubscription {
     this.ModelClass = ModelClass
     /**
      * Narrows the runtime value to the documented type.
-      @type {Set<FrontendModelModelEventCallbackEntry>} */
+     * @type {Set<FrontendModelModelEventCallbackEntry>} */
     this.classCreateCallbacks = new Set()
     /**
      * Narrows the runtime value to the documented type.
-      @type {Set<FrontendModelModelEventCallbackEntry>} */
+     * @type {Set<FrontendModelModelEventCallbackEntry>} */
     this.classUpdateCallbacks = new Set()
     /**
      * Narrows the runtime value to the documented type.
-      @type {Set<FrontendModelDestroyEventCallbackEntry>} */
+     * @type {Set<FrontendModelDestroyEventCallbackEntry>} */
     this.classDestroyCallbacks = new Set()
     /**
      * Narrows the runtime value to the documented type.
-      @type {Map<string, {instance: FrontendModelBase, updateCallbacks: Set<FrontendModelModelEventCallbackEntry>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry>}>} */
+     * @type {Map<string, {instance: FrontendModelBase, updateCallbacks: Set<FrontendModelModelEventCallbackEntry>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry>}>} */
     this.instanceListeners = new Map()
     /**
      * Narrows the runtime value to the documented type.
-      @type {?} */
+     * @type {?} */
     this.channelHandle = null
     /**
      * Narrows the runtime value to the documented type.
-      @type {Promise<void> | null} */
+     * @type {Promise<void> | null} */
     this.readyPromise = null
     /**
      * Narrows the runtime value to the documented type.
-      @type {string | null} */
+     * @type {string | null} */
     this.subscriptionParamsKey = null
   }
 
   /**
    * Runs subscription params.
-   * @returns {{model: string, eventFilters?: import("./query.js").FrontendModelEventFilterPayloadEntry[], unfilteredEventDelivery?: boolean} & import("./query.js").FrontendModelProjectionPayload} - Current websocket subscription params.
+   * @returns {{model: string, destroyEventDelivery?: boolean, eventFilters?: import("./query.js").FrontendModelEventFilterPayloadEntry[], unfilteredEventDelivery?: boolean} & import("./query.js").FrontendModelProjectionPayload} - Current websocket subscription params.
    */
   subscriptionParams() {
     /**
      * Projection payload.
-      @type {import("./query.js").FrontendModelProjectionPayload} */
+     * @type {import("./query.js").FrontendModelProjectionPayload} */
     const projectionPayload = {}
     /**
      * Event filters by key.
-      @type {Record<string, import("./query.js").FrontendModelEventFilterPayloadEntry>} */
+     * @type {Record<string, import("./query.js").FrontendModelEventFilterPayloadEntry>} */
     const eventFiltersByKey = {}
     const projectionEntries = []
-    let hasUnfilteredEventDelivery = this.classDestroyCallbacks.size > 0
+    let hasDestroyEventDelivery = this.classDestroyCallbacks.size > 0
+    let hasUnfilteredEventDelivery = false
 
     for (const entry of this.classCreateCallbacks) projectionEntries.push(entry)
     for (const entry of this.classUpdateCallbacks) projectionEntries.push(entry)
 
     for (const listener of this.instanceListeners.values()) {
       for (const entry of listener.updateCallbacks) projectionEntries.push(entry)
-      if (listener.destroyCallbacks.size > 0) hasUnfilteredEventDelivery = true
+      if (listener.destroyCallbacks.size > 0) hasDestroyEventDelivery = true
     }
 
     for (const entry of projectionEntries) {
@@ -1160,6 +1285,7 @@ class FrontendModelEventSubscription {
     const eventFilterParams = eventFilters.length > 0
       ? {
           eventFilters,
+          ...(hasDestroyEventDelivery ? {destroyEventDelivery: true} : {}),
           ...(hasUnfilteredEventDelivery ? {unfilteredEventDelivery: true} : {})
         }
       : {}
@@ -1181,7 +1307,7 @@ class FrontendModelEventSubscription {
 
   /**
    * Runs ensure subscribed.
-    @returns {Promise<void>} */
+   * @returns {Promise<void>} */
   async ensureSubscribed() {
     const paramsJson = this.subscriptionParamsJson()
 
@@ -1206,7 +1332,7 @@ class FrontendModelEventSubscription {
 
     const client = /**
                     * Narrows the runtime value to the documented type.
-                     @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
+                    * @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
 
     if (!client || typeof client.subscribeChannel !== "function") {
       throw new Error("Frontend model event subscriptions require configureTransport({websocketUrl}) or configureTransport({websocketClient})")
@@ -1222,7 +1348,7 @@ class FrontendModelEventSubscription {
         params,
         onMessage: (/**
                      * Narrows the runtime value to the documented type.
-                      @type {?} */ body) => this._dispatchEvent(body),
+                     * @type {?} */ body) => this._dispatchEvent(body),
         onClose: () => {
           this.channelHandle = null
           this.readyPromise = null
@@ -1279,10 +1405,10 @@ class FrontendModelEventSubscription {
 
     const deserializedRecord = /**
                                 * Narrows the runtime value to the documented type.
-                                 @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(body.record))
+                                * @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(body.record))
     const freshModel = /**
                         * Narrows the runtime value to the documented type.
-                         @type {?} */ (this.ModelClass).instantiateFromResponse(deserializedRecord)
+                        * @type {?} */ (this.ModelClass).instantiateFromResponse(deserializedRecord)
     const listener = this.instanceListeners.get(id)
 
     if (action === "update" && listener) {
@@ -1295,7 +1421,7 @@ class FrontendModelEventSubscription {
         // through the same handle see fresh attributes.
         const instanceAny = /**
                              * Narrows the runtime value to the documented type.
-                              @type {?} */ (listener.instance)
+                             * @type {?} */ (listener.instance)
 
         instanceAny.assignAttributes(freshModel.attributes())
         instanceAny._persistedAttributes = cloneFrontendModelAttributes(listener.instance.attributes())
@@ -1317,7 +1443,7 @@ class FrontendModelEventSubscription {
 
   /**
    * Runs maybe teardown.
-    @returns {void} */
+   * @returns {void} */
   maybeTeardown() {
     const hasAnyListener = this.classCreateCallbacks.size > 0
       || this.classUpdateCallbacks.size > 0
@@ -1341,7 +1467,7 @@ class FrontendModelEventSubscription {
 
 /**
  * Frontend model event subscriptions.
-  @type {WeakMap<FrontendModelClass, FrontendModelEventSubscription>} */
+ * @type {WeakMap<FrontendModelClass, FrontendModelEventSubscription>} */
 const frontendModelEventSubscriptions = new WeakMap()
 
 /**
@@ -1453,7 +1579,7 @@ async function performSharedFrontendModelApiRequest(requestPayload) {
     })
     const responseJson = response.json()
 
-    return /** Narrows the runtime value to the documented type. @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(responseJson))
+    return /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(responseJson))
   }
 
   const response = await fetch(url, {
@@ -1475,7 +1601,7 @@ async function performSharedFrontendModelApiRequest(requestPayload) {
 
   const json = responseText.length > 0 ? JSON.parse(responseText) : {}
 
-  return /** Narrows the runtime value to the documented type. @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(json))
+  return /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(json))
 }
 
 /**
@@ -1494,7 +1620,7 @@ function throwFrontendModelHttpError({commandLabel, response, responseText}) {
   if (responseContentType && responseContentType.includes("application/json") && responseText.length > 0) {
     /**
      * Defines errorBody.
-      @type {Record<string, ?> | null} */
+     * @type {Record<string, ?> | null} */
     let errorBody
 
     try {
@@ -1565,7 +1691,7 @@ async function flushPendingSharedFrontendModelRequests() {
 
         request.resolve(/**
                          * Narrows the runtime value to the documented type.
-                          @type {Record<string, ?>} */ (responsePayload))
+                         * @type {Record<string, ?>} */ (responsePayload))
       }
     } catch (error) {
       for (const request of batchedRequests) {
@@ -1577,7 +1703,7 @@ async function flushPendingSharedFrontendModelRequests() {
 
 /**
  * Runs schedule shared frontend model request flush.
-  @returns {void} */
+ * @returns {void} */
 function scheduleSharedFrontendModelRequestFlush() {
   if (sharedFrontendModelFlushScheduled) return
 
@@ -1671,7 +1797,7 @@ function assertDefinedFindByConditionValue(value, keyPath) {
 
     const objectValue = /**
                          * Narrows the runtime value to the documented type.
-                          @type {Record<string, ?>} */ (value)
+                         * @type {Record<string, ?>} */ (value)
     const prototype = Object.getPrototypeOf(objectValue)
 
     if (prototype !== Object.prototype && prototype !== null) {
@@ -1686,7 +1812,7 @@ function assertDefinedFindByConditionValue(value, keyPath) {
 
     const valueObject = /**
                          * Narrows the runtime value to the documented type.
-                          @type {Record<string, ?>} */ (value)
+                         * @type {Record<string, ?>} */ (value)
 
     Object.keys(valueObject).forEach((nestedKey) => {
       assertDefinedFindByConditionValue(valueObject[nestedKey], `${keyPath}.${nestedKey}`)
@@ -1694,11 +1820,16 @@ function assertDefinedFindByConditionValue(value, keyPath) {
   }
 }
 
-/** Base class for generated frontend model classes. */
+/**
+ * Base frontend model.
+ * @template {Record<string, FrontendModelAttributeValue>} [Attributes=Record<string, FrontendModelAttributeValue>]
+ * @template {Record<string, FrontendModelAttributeValue>} [CreateAttributes=Record<string, FrontendModelAttributeValue>]
+ * @template {Record<string, FrontendModelAttributeValue>} [UpdateAttributes=Record<string, FrontendModelAttributeValue>]
+ */
 export default class FrontendModelBase {
   /**
    * Narrows the runtime value to the documented type.
-    @type {string | undefined} */
+   * @type {string | undefined} */
   static modelName
 
   /**
@@ -1722,15 +1853,15 @@ export default class FrontendModelBase {
 
   /**
    * Narrows the runtime value to the documented type.
-    @type {Record<string, ?>} */
+   * @type {Record<string, FrontendModelAttributeValue>} */
   _attributes
   /**
    * Narrows the runtime value to the documented type.
-    @type {Record<string, FrontendModelHasManyRelationship<FrontendModelClass, FrontendModelClass> | FrontendModelSingularRelationship<FrontendModelClass, FrontendModelClass>>} */
+   * @type {Record<string, FrontendModelHasManyRelationship<FrontendModelBase, FrontendModelBase, Record<string, FrontendModelAttributeValue>> | FrontendModelSingularRelationship<FrontendModelBase, FrontendModelBase, Record<string, FrontendModelAttributeValue>>>} */
   _relationships
   /**
    * Narrows the runtime value to the documented type.
-    @type {Record<string, FrontendModelAttachmentHandle>} */
+   * @type {Record<string, FrontendModelAttachmentHandle>} */
   _attachments
   /**
    * Rails-style nested attribute payloads queued for the next save.
@@ -1739,19 +1870,19 @@ export default class FrontendModelBase {
   _pendingNestedAttributes
   /**
    * Narrows the runtime value to the documented type.
-    @type {Set<string> | null} */
+   * @type {Set<string> | null} */
   _selectedAttributes
   /**
    * Narrows the runtime value to the documented type.
-    @type {boolean} */
+   * @type {boolean} */
   _isNewRecord
   /**
    * Narrows the runtime value to the documented type.
-    @type {boolean} */
+   * @type {boolean} */
   _markedForDestruction
   /**
    * Narrows the runtime value to the documented type.
-    @type {Record<string, ?>} */
+   * @type {Record<string, FrontendModelAttributeValue>} */
   _persistedAttributes
   /**
    * Narrows the runtime value to the documented type.
@@ -1761,9 +1892,9 @@ export default class FrontendModelBase {
 
   /**
    * Runs constructor.
-   * @param {Record<string, ?>} [attributes] - Initial attributes.
+   * @param {Attributes | CreateAttributes} [attributes] - Initial attributes.
    */
-  constructor(attributes = {}) {
+  constructor(attributes) {
     const ModelClass = frontendModelClassFor(this)
 
     ModelClass.ensureGeneratedAttachmentMethods()
@@ -1775,7 +1906,7 @@ export default class FrontendModelBase {
     this._isNewRecord = true
     this._markedForDestruction = false
     this._persistedAttributes = {}
-    this.assignAttributes(attributes)
+    if (attributes) this.assignAttributes(attributes)
   }
 
   /**
@@ -1789,7 +1920,7 @@ export default class FrontendModelBase {
     const attachments = this.attachmentDefinitions()
     const prototype = /**
                        * Narrows the runtime value to the documented type.
-                        @type {Record<string, ?>} */ (this.prototype)
+                       * @type {Record<string, ?>} */ (this.prototype)
 
     for (const attachmentName of Object.keys(attachments)) {
       if (!(attachmentName in prototype)) {
@@ -1924,10 +2055,10 @@ export default class FrontendModelBase {
 
   /**
    * Runs attributes.
-   * @returns {Record<string, ?>} - Attributes hash.
+   * @returns {Attributes} - Attributes hash.
    */
   attributes() {
-    return this._attributes
+    return /** @type {Attributes} */ (this._attributes)
   }
 
   /**
@@ -1980,7 +2111,7 @@ export default class FrontendModelBase {
   changes() {
     /**
      * Changed attributes.
-      @type {Record<string, Array<?>>} */
+     * @type {Record<string, Array<?>>} */
     const changedAttributes = {}
     const attributeNames = new Set([
       ...Object.keys(this._persistedAttributes),
@@ -2010,7 +2141,7 @@ export default class FrontendModelBase {
   /**
    * Runs get relationship by name.
    * @param {string} relationshipName - Relationship name.
-   * @returns {FrontendModelHasManyRelationship<FrontendModelClass, FrontendModelClass> | FrontendModelSingularRelationship<FrontendModelClass, FrontendModelClass>} - Relationship state object.
+   * @returns {FrontendModelRelationship} - Relationship state object.
    */
   getRelationshipByName(relationshipName) {
     if (!this._relationships[relationshipName]) {
@@ -2054,7 +2185,7 @@ export default class FrontendModelBase {
   /**
    * Runs load relationship.
    * @param {string} relationshipName - Relationship name.
-   * @returns {Promise<?>} - Loaded relationship value.
+   * @returns {Promise<FrontendModelBase | Array<FrontendModelBase> | null>} - Loaded relationship value.
    */
   async loadRelationship(relationshipName) {
     const ModelClass = frontendModelClassFor(this)
@@ -2062,11 +2193,12 @@ export default class FrontendModelBase {
     const reloadedModel = await ModelClass
       .preload([relationshipName])
       .find(id)
-    const loadedValue = reloadedModel.getRelationshipByName(relationshipName).loaded()
+    const sourceRelationship = reloadedModel.getRelationshipByName(relationshipName)
+    const targetRelationship = this.getRelationshipByName(relationshipName)
 
-    this.getRelationshipByName(relationshipName).setLoaded(loadedValue)
+    copyLoadedRelationshipValue({sourceRelationship, targetRelationship})
 
-    return loadedValue
+    return targetRelationship.loaded()
   }
 
   /**
@@ -2087,7 +2219,7 @@ export default class FrontendModelBase {
   /**
    * Runs relationship or load.
    * @param {string} relationshipName - Relationship name.
-   * @returns {Promise<?>} - Loaded relationship value.
+   * @returns {Promise<FrontendModelBase | Array<FrontendModelBase> | null>} - Loaded relationship value.
    */
   async relationshipOrLoad(relationshipName) {
     const relationship = this.getRelationshipByName(relationshipName)
@@ -2129,7 +2261,7 @@ export default class FrontendModelBase {
 
     /**
      * Batch.
-      @type {Array<FrontendModelBase>} */
+     * @type {Array<FrontendModelBase>} */
     const batch = []
 
     // Exact same class, persisted, no existing in-memory relationship state.
@@ -2158,7 +2290,7 @@ export default class FrontendModelBase {
 
     /**
      * Reloaded by id.
-      @type {Map<string, FrontendModelBase>} */
+     * @type {Map<string, FrontendModelBase>} */
     const reloadedById = new Map()
 
     for (const reloaded of reloadedBatch) {
@@ -2171,9 +2303,10 @@ export default class FrontendModelBase {
 
       if (!reloaded) continue
 
-      const reloadedValue = reloaded.getRelationshipByName(relationshipName).loaded()
-
-      sibling.getRelationshipByName(relationshipName).setLoaded(reloadedValue)
+      copyLoadedRelationshipValue({
+        sourceRelationship: reloaded.getRelationshipByName(relationshipName),
+        targetRelationship: sibling.getRelationshipByName(relationshipName)
+      })
     }
 
     // If the caller itself was not populated (record deleted/filtered between
@@ -2188,8 +2321,8 @@ export default class FrontendModelBase {
   /**
    * Runs set relationship.
    * @param {string} relationshipName - Relationship name.
-   * @param {?} relationshipValue - Relationship value.
-   * @returns {?} - Assigned relationship value.
+   * @param {FrontendModelBase | null | undefined} relationshipValue - Relationship value.
+   * @returns {FrontendModelBase | null | undefined} - Assigned relationship value.
    */
   setRelationship(relationshipName, relationshipValue) {
     const ModelClass = frontendModelClassFor(this)
@@ -2199,23 +2332,27 @@ export default class FrontendModelBase {
       throw new Error(`Unknown relationship: ${ModelClass.name}#${relationshipName}`)
     }
 
-    if (relationshipTypeIsCollection(relationshipDefinition.type)) {
+    const relationship = this.getRelationshipByName(relationshipName)
+
+    if (relationship instanceof FrontendModelHasManyRelationship) {
       throw new Error(`Cannot set has-many relationship with setRelationship(): ${ModelClass.name}#${relationshipName}`)
     }
 
-    this.getRelationshipByName(relationshipName).setLoaded(relationshipValue)
+    relationship.setLoaded(relationshipValue)
 
     return relationshipValue
   }
 
   /**
    * Runs assign attributes.
-   * @param {Record<string, ?>} attributes - Attributes to assign.
+   * @param {Attributes | CreateAttributes | UpdateAttributes | Record<string, FrontendModelAttributeValue>} attributes - Attributes to assign.
    * @returns {void} - No return value.
    */
   assignAttributes(attributes) {
-    for (const key in attributes) {
-      this.setAttribute(key, attributes[key])
+    const attributeValues = /** @type {Record<string, FrontendModelAttributeValue>} */ (attributes)
+
+    for (const key in attributeValues) {
+      this.setAttribute(key, attributeValues[key])
     }
   }
 
@@ -2289,9 +2426,9 @@ export default class FrontendModelBase {
   readCount(attributeName) {
     return readPayloadAssociationCount(/**
                                         * Narrows the runtime value to the documented type.
-                                         @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
+                                        * @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
                                                                                                                       * Narrows the runtime value to the documented type.
-                                                                                                                       @type {?} */ (this)), attributeName)
+                                                                                                                      * @type {?} */ (this)), attributeName)
   }
 
   /**
@@ -2304,9 +2441,9 @@ export default class FrontendModelBase {
   _setAssociationCount(attributeName, value) {
     setPayloadAssociationCount(/**
                                 * Narrows the runtime value to the documented type.
-                                 @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
+                                * @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
                                                                                                               * Narrows the runtime value to the documented type.
-                                                                                                               @type {?} */ (this)), attributeName, value)
+                                                                                                              * @type {?} */ (this)), attributeName, value)
   }
 
   /**
@@ -2323,9 +2460,9 @@ export default class FrontendModelBase {
   can(action) {
     return readPayloadComputedAbility(/**
                                        * Narrows the runtime value to the documented type.
-                                        @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
+                                       * @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
                                                                                                                      * Narrows the runtime value to the documented type.
-                                                                                                                      @type {?} */ (this)), action)
+                                                                                                                     * @type {?} */ (this)), action)
   }
 
   /**
@@ -2339,9 +2476,9 @@ export default class FrontendModelBase {
   _setComputedAbility(action, value) {
     setPayloadComputedAbility(/**
                                * Narrows the runtime value to the documented type.
-                                @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
+                               * @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
                                                                                                              * Narrows the runtime value to the documented type.
-                                                                                                              @type {?} */ (this)), action, value)
+                                                                                                             * @type {?} */ (this)), action, value)
   }
 
   /**
@@ -2356,9 +2493,9 @@ export default class FrontendModelBase {
   queryData(name) {
     return readPayloadQueryData(/**
                                  * Narrows the runtime value to the documented type.
-                                  @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
+                                 * @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
                                                                                                                * Narrows the runtime value to the documented type.
-                                                                                                                @type {?} */ (this)), name)
+                                                                                                               * @type {?} */ (this)), name)
   }
 
   /**
@@ -2371,9 +2508,9 @@ export default class FrontendModelBase {
   _setQueryData(name, value) {
     setPayloadQueryData(/**
                          * Narrows the runtime value to the documented type.
-                          @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
+                         * @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
                                                                                                        * Narrows the runtime value to the documented type.
-                                                                                                        @type {?} */ (this)), name, value)
+                                                                                                       * @type {?} */ (this)), name, value)
   }
 
   /**
@@ -2436,7 +2573,7 @@ export default class FrontendModelBase {
     for (const relationshipName of Object.keys(this._relationships)) {
       const definition = /**
                           * Narrows the runtime value to the documented type.
-                           @type {?} */ (definitions[relationshipName])
+                          * @type {?} */ (definitions[relationshipName])
 
       if (!definition || definition.type !== "belongsTo") continue
 
@@ -2499,12 +2636,12 @@ export default class FrontendModelBase {
         return {arg1: payload}
       }
 
-      return /** Narrows the runtime value to the documented type. @type {Record<string, ?>} */ (payload)
+      return /** @type {Record<string, ?>} */ (payload)
     }
 
     /**
      * Payload.
-      @type {Record<string, number | string | Array<?>>} */
+     * @type {Record<string, number | string | Array<?>>} */
     const payload = {}
 
     for (let index = 0; index < args.length; index += 1) {
@@ -2650,7 +2787,7 @@ export default class FrontendModelBase {
   static setWebsocketMetadata(key, value) {
     const client = /**
                     * Narrows the runtime value to the documented type.
-                     @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
+                    * @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
 
     if (!client || typeof client.setMetadata !== "function") return
 
@@ -2670,12 +2807,12 @@ export default class FrontendModelBase {
   static openManagedConnection(connectionType, options) {
     /**
      * Connection.
-      @type {?} */
+     * @type {?} */
     let connection = null
     let closed = false
     /**
      * Retry timer.
-      @type {ReturnType<typeof setTimeout> | null} */
+     * @type {ReturnType<typeof setTimeout> | null} */
     let retryTimer = null
     let lastParamsJson = ""
 
@@ -2714,7 +2851,7 @@ export default class FrontendModelBase {
       // which only reflects the internal client.
       const client = /**
                       * Narrows the runtime value to the documented type.
-                       @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
+                      * @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
 
       if (!client || !client.isOpen()) {
         if (retryTimer === null) {
@@ -2764,7 +2901,7 @@ export default class FrontendModelBase {
   static openWebsocketConnection(connectionType, options) {
     const client = /**
                     * Narrows the runtime value to the documented type.
-                     @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
+                    * @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
 
     if (!client || typeof client.openConnection !== "function") {
       throw new Error("openWebsocketConnection requires configureTransport({websocketUrl})")
@@ -2783,7 +2920,7 @@ export default class FrontendModelBase {
   static subscribeWebsocketChannel(channelType, options) {
     const client = /**
                     * Narrows the runtime value to the documented type.
-                     @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
+                    * @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
 
     if (!client || typeof client.subscribeChannel !== "function") {
       throw new Error("subscribeWebsocketChannel requires configureTransport({websocketUrl})")
@@ -2800,7 +2937,7 @@ export default class FrontendModelBase {
   static installWebsocketTestHooks() {
     if (typeof globalThis === "undefined") return
 
-    /** Narrows the runtime value to the documented type. @type {?} */ (globalThis).__velocious_websocket_hooks = {
+    /** @type {?} */ (globalThis).__velocious_websocket_hooks = {
       connect: () => this.connectWebsocket(),
       disconnect: () => this.disconnectWebsocket(),
       drop: () => this.dropWebsocket(),
@@ -2812,7 +2949,7 @@ export default class FrontendModelBase {
    * Runs attributes from response.
    * @this {FrontendModelClass}
    * @param {object} response - Response payload.
-   * @returns {Record<string, ?>} - Attributes from payload.
+   * @returns {Record<string, FrontendModelAttributeValue>} - Attributes from payload.
    */
   static attributesFromResponse(response) {
     const modelData = this.modelDataFromResponse(response)
@@ -2824,59 +2961,52 @@ export default class FrontendModelBase {
    * Runs model data from response.
    * @this {FrontendModelClass}
    * @param {object} response - Response payload.
-   * @returns {{abilities: Record<string, boolean>, attributes: Record<string, ?>, associationCounts: Record<string, number>, queryData: Record<string, ?>, preloadedRelationships: Record<string, ?>, selectedAttributes: Set<string>}} - Attributes, preloaded relationships, association counts, queryData, abilities, and the selected-attributes set.
+   * @returns {{abilities: Record<string, boolean>, attributes: Record<string, FrontendModelAttributeValue>, associationCounts: Record<string, number>, queryData: Record<string, FrontendModelAttributeValue>, preloadedRelationships: Record<string, FrontendModelAttributeValue>, selectedAttributes: Set<string>}} - Attributes, preloaded relationships, association counts, queryData, abilities, and the selected-attributes set.
    */
   static modelDataFromResponse(response) {
     if (!response || typeof response !== "object") {
       throw new Error(`Expected object response but got: ${response}`)
     }
 
-    const responseObject = /**
-                            * Narrows the runtime value to the documented type.
-                             @type {Record<string, ?>} */ (response)
+    // Narrows the response object to the frontend-model transport value map.
+    const responseObject = /** @type {Record<string, FrontendModelAttributeValue>} */ (response)
 
     /**
      * Defines modelData.
-      @type {Record<string, ?>} */
+     * @type {Record<string, FrontendModelAttributeValue>} */
     let modelData
 
     if (responseObject.model && typeof responseObject.model === "object") {
-      modelData = /**
-                   * Narrows the runtime value to the documented type.
-                    @type {Record<string, ?>} */ (responseObject.model)
+      // Narrows the nested model payload to the frontend-model value map.
+      modelData = /** @type {Record<string, FrontendModelAttributeValue>} */ (responseObject.model)
     } else if (responseObject.attributes && typeof responseObject.attributes === "object") {
-      modelData = /**
-                   * Narrows the runtime value to the documented type.
-                    @type {Record<string, ?>} */ (responseObject.attributes)
+      // Narrows the nested attributes payload to the frontend-model value map.
+      modelData = /** @type {Record<string, FrontendModelAttributeValue>} */ (responseObject.attributes)
     } else {
       modelData = responseObject
     }
 
-    const attributes = {...modelData}
+    const attributes = /** @type {Record<string, FrontendModelAttributeValue>} */ ({...modelData})
     const preloadedRelationships = isPlainObject(attributes[PRELOADED_RELATIONSHIPS_KEY])
-      ? /**
-         * Narrows the runtime value to the documented type.
-          @type {Record<string, ?>} */ (attributes[PRELOADED_RELATIONSHIPS_KEY])
+      ? /** @type {Record<string, FrontendModelAttributeValue>} */ (attributes[PRELOADED_RELATIONSHIPS_KEY])
       : {}
     const associationCounts = isPlainObject(attributes[ASSOCIATION_COUNTS_KEY])
       ? /**
          * Narrows the runtime value to the documented type.
-          @type {Record<string, number>} */ (attributes[ASSOCIATION_COUNTS_KEY])
+         * @type {Record<string, number>} */ (attributes[ASSOCIATION_COUNTS_KEY])
       : {}
     const queryData = isPlainObject(attributes[QUERY_DATA_KEY])
-      ? /**
-         * Narrows the runtime value to the documented type.
-          @type {Record<string, ?>} */ (attributes[QUERY_DATA_KEY])
+      ? /** @type {Record<string, FrontendModelAttributeValue>} */ (attributes[QUERY_DATA_KEY])
       : {}
     const abilities = isPlainObject(attributes[ABILITIES_KEY])
       ? /**
          * Narrows the runtime value to the documented type.
-          @type {Record<string, boolean>} */ (attributes[ABILITIES_KEY])
+         * @type {Record<string, boolean>} */ (attributes[ABILITIES_KEY])
       : {}
     const selectedAttributesFromPayload = Array.isArray(attributes[SELECTED_ATTRIBUTES_KEY])
       ? new Set(/**
                  * Narrows the runtime value to the documented type.
-                  @type {string[]} */ (attributes[SELECTED_ATTRIBUTES_KEY]).filter((attributeName) => typeof attributeName === "string"))
+                 * @type {string[]} */ (attributes[SELECTED_ATTRIBUTES_KEY]).filter((attributeName) => typeof attributeName === "string"))
       : null
 
     delete attributes[PRELOADED_RELATIONSHIPS_KEY]
@@ -2902,12 +3032,39 @@ export default class FrontendModelBase {
       const relationship = model.getRelationshipByName(relationshipName)
       const targetModelClass = this.relationshipModelClass(relationshipName)
 
-      if (Array.isArray(relationshipPayload)) {
-        relationship.setLoaded(relationshipPayload.map((entry) => this.instantiateRelationshipValue(entry, targetModelClass)))
+      if (relationship instanceof FrontendModelHasManyRelationship) {
+        if (!Array.isArray(relationshipPayload)) {
+          throw new Error(`Expected ${this.name}#${relationshipName} payload to be an array`)
+        }
+
+        /** @type {Array<FrontendModelBase>} */
+        const relatedModels = []
+
+        for (const entry of relationshipPayload) {
+          const relatedModel = this.instantiateRelationshipValue(entry, targetModelClass)
+
+          if (!(relatedModel instanceof FrontendModelBase)) {
+            throw new Error(`Expected ${this.name}#${relationshipName} payload entry to instantiate a frontend model`)
+          }
+
+          relatedModels.push(relatedModel)
+        }
+
+        relationship.setLoaded(relatedModels)
         continue
       }
 
-      relationship.setLoaded(this.instantiateRelationshipValue(relationshipPayload, targetModelClass))
+      if (Array.isArray(relationshipPayload)) {
+        throw new Error(`Expected ${this.name}#${relationshipName} payload to be singular`)
+      }
+
+      const relatedModel = this.instantiateRelationshipValue(relationshipPayload, targetModelClass)
+
+      if (relatedModel != undefined && !(relatedModel instanceof FrontendModelBase)) {
+        throw new Error(`Expected ${this.name}#${relationshipName} payload to instantiate a frontend model`)
+      }
+
+      relationship.setLoaded(relatedModel)
     }
   }
 
@@ -2944,7 +3101,7 @@ export default class FrontendModelBase {
     // model instance into a new constructor call and produce a broken model
     // with internal state keys promoted to attributes.
     if (response instanceof this) {
-      return /** Narrows the runtime value to the documented type. @type {InstanceType<T>} */ (response)
+      return /** @type {InstanceType<T>} */ (response)
     }
 
     const modelData = this.modelDataFromResponse(response)
@@ -2954,9 +3111,9 @@ export default class FrontendModelBase {
     const queryData = modelData.queryData
     const abilities = modelData.abilities
     const selectedAttributes = modelData.selectedAttributes
-    const model = /**
-                   * Narrows the runtime value to the documented type.
-                    @type {InstanceType<T>} */ (new this(attributes))
+    const receiver = /** @type {unknown} */ (this)
+    const ModelClass = /** @type {new (attributes?: Record<string, FrontendModelAttributeValue>) => InstanceType<T>} */ (receiver)
+    const model = new ModelClass(attributes)
     model._selectedAttributes = selectedAttributes ? new Set(selectedAttributes) : null
 
     this.applyPreloadedRelationships(model, preloadedRelationships)
@@ -3196,7 +3353,7 @@ export default class FrontendModelBase {
   async onUpdate(callback, options = {}) {
     const self = /**
                   * Narrows the runtime value to the documented type.
-                   @type {?} */ (this)
+                  * @type {?} */ (this)
     const ModelClass = frontendModelClassFor(this)
     const sub = ensureFrontendModelEventSubscription(ModelClass)
     const id = String(self.id())
@@ -3228,7 +3385,7 @@ export default class FrontendModelBase {
   async onDestroy(callback, options = {}) {
     const self = /**
                   * Narrows the runtime value to the documented type.
-                   @type {?} */ (this)
+                  * @type {?} */ (this)
     const ModelClass = frontendModelClassFor(this)
 
     assertNoDestroyEventFilter(ModelClass, options)
@@ -3341,7 +3498,7 @@ export default class FrontendModelBase {
    * @returns {FrontendModelQuery<T>} - Query builder.
    */
   static query() {
-    return /** Narrows the runtime value to the documented type. @type {FrontendModelQuery<T>} */ (new FrontendModelQuery({modelClass: this}))
+    return /** @type {FrontendModelQuery<T>} */ (new FrontendModelQuery({modelClass: this}))
   }
 
   /**
@@ -3352,7 +3509,7 @@ export default class FrontendModelBase {
    * @returns {FrontendModelQuery<T>} - Query with preload.
    */
   static preload(preload) {
-    return /** Narrows the runtime value to the documented type. @type {FrontendModelQuery<T>} */ (this.query().preload(preload))
+    return /** @type {FrontendModelQuery<T>} */ (this.query().preload(preload))
   }
 
   /**
@@ -3363,7 +3520,7 @@ export default class FrontendModelBase {
    * @returns {FrontendModelQuery<T>} - Query with selected attributes.
    */
   static select(select) {
-    return /** Narrows the runtime value to the documented type. @type {FrontendModelQuery<T>} */ (this.query().select(select))
+    return /** @type {FrontendModelQuery<T>} */ (this.query().select(select))
   }
 
   /**
@@ -3374,7 +3531,7 @@ export default class FrontendModelBase {
    * @returns {FrontendModelQuery<T>} - Query with extra selected attributes.
    */
   static selectsExtra(select) {
-    return /** Narrows the runtime value to the documented type. @type {FrontendModelQuery<T>} */ (this.query().selectsExtra(select))
+    return /** @type {FrontendModelQuery<T>} */ (this.query().selectsExtra(select))
   }
 
   /**
@@ -3422,15 +3579,15 @@ export default class FrontendModelBase {
 
   /**
    * Runs create.
-   * @template {FrontendModelClass} T
-   * @this {T}
-   * @param {Record<string, ?>} [attributes] - Initial attributes.
-   * @returns {Promise<InstanceType<T>>} - Persisted model.
+   * @template {FrontendModelClass} ModelClass
+   * @this {ModelClass}
+   * @param {FrontendModelCreateAttributesFor<InstanceType<ModelClass>>} [attributes] - Initial attributes.
+   * @returns {Promise<InstanceType<ModelClass>>} - Persisted model.
    */
-  static async create(attributes = {}) {
-    const model = /**
-                   * Narrows the runtime value to the documented type.
-                    @type {InstanceType<T>} */ (new this(attributes))
+  static async create(attributes) {
+    const receiver = /** @type {unknown} */ (this)
+    const ModelClass = /** @type {new (attributes?: FrontendModelCreateAttributesFor<InstanceType<ModelClass>>) => InstanceType<ModelClass>} */ (receiver)
+    const model = new ModelClass(attributes)
 
     await model.save()
 
@@ -3518,10 +3675,10 @@ export default class FrontendModelBase {
 
       const actualObject = /**
                             * Narrows the runtime value to the documented type.
-                             @type {Record<string, ?>} */ (actualValue)
+                            * @type {Record<string, ?>} */ (actualValue)
       const expectedObject = /**
                               * Narrows the runtime value to the documented type.
-                               @type {Record<string, ?>} */ (expectedValue)
+                              * @type {Record<string, ?>} */ (expectedValue)
       const actualKeys = Object.keys(actualObject)
       const expectedKeys = Object.keys(expectedObject)
 
@@ -3601,13 +3758,13 @@ export default class FrontendModelBase {
 
   /**
    * Runs update.
-   * @param {Record<string, ?>} [newAttributes] - New values to assign before update.
+   * @param {UpdateAttributes} [newAttributes] - New values to assign before update.
    * @returns {Promise<this>} - Updated model.
    */
-  async update(newAttributes = {}) {
-    this.assignAttributes(newAttributes)
+  async update(newAttributes) {
+    if (newAttributes) this.assignAttributes(newAttributes)
 
-    return await this.save()
+    return /** @type {this} */ (await this.save())
   }
 
   /**
@@ -3653,7 +3810,7 @@ export default class FrontendModelBase {
     const commandType = isNew ? "create" : "update"
     /**
      * Payload.
-      @type {Record<string, ?>} */
+     * @type {Record<string, ?>} */
     const payload = {
       attributes: this._changedAttributesForSave()
     }
@@ -3693,12 +3850,12 @@ export default class FrontendModelBase {
    * fields the caller actually changed — avoiding strict permit rejections on
    * framework-managed fields like `id`, `createdAt`, `updatedAt`, or owner
    * foreign keys that the resource never lists in `permittedParams`.
-   * @returns {Record<string, ?>} - Changed attributes hash.
+   * @returns {Record<string, FrontendModelAttributeValue>} - Changed attributes hash.
    */
   _changedAttributesForSave() {
     /**
      * Changed attributes.
-      @type {Record<string, ?>} */
+     * @type {Record<string, FrontendModelAttributeValue>} */
     const changedAttributes = {}
 
     for (const [attributeName, [previousValue, currentValue]] of Object.entries(this.changes())) {
@@ -3781,7 +3938,7 @@ export default class FrontendModelBase {
 
     /**
      * Payload.
-      @type {Record<string, Array<Record<string, ?>>>} */
+     * @type {Record<string, Array<Record<string, ?>>>} */
     const payload = {}
 
     for (const relationshipName of Object.keys(nestedAttributesConfig)) {
@@ -3843,7 +4000,7 @@ export default class FrontendModelBase {
     if (this.isNewRecord()) {
       /**
        * Entry.
-        @type {Record<string, ?>} */
+       * @type {Record<string, ?>} */
       const entry = {}
       const attributes = this._changedAttributesForSave()
 
@@ -3858,7 +4015,7 @@ export default class FrontendModelBase {
 
     /**
      * Entry.
-      @type {Record<string, ?>} */
+     * @type {Record<string, ?>} */
     const entry = {id: this.primaryKeyValue()}
 
     if (this.isChanged()) entry.attributes = this._changedAttributesForSave()
@@ -4006,7 +4163,7 @@ export default class FrontendModelBase {
 
     /**
      * Relevant preloads.
-      @type {Record<string, ?>} */
+     * @type {Record<string, ?>} */
     const relevantPreloads = {}
 
     for (const relationshipName of Object.keys(nestedAttributesConfig)) {
@@ -4031,7 +4188,7 @@ export default class FrontendModelBase {
     const commandName = this.commandName(commandType)
     const serializedPayload = /**
                                * Narrows the runtime value to the documented type.
-                                @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(payload))
+                               * @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(payload))
     const resourcePath = this.resourcePath()
     const containsAttachmentUpload = frontendModelPayloadContainsAttachmentUpload(serializedPayload)
     const useSharedTransport = !containsAttachmentUpload
@@ -4055,7 +4212,7 @@ export default class FrontendModelBase {
 
       const decodedBatchResponse = /**
                                     * Narrows the runtime value to the documented type.
-                                     @type {Record<string, ?>} */ (batchResponse)
+                                    * @type {Record<string, ?>} */ (batchResponse)
 
       this.throwOnErrorFrontendModelResponse({
         commandType,
@@ -4086,7 +4243,7 @@ export default class FrontendModelBase {
       const directJson = directResponseText.length > 0 ? JSON.parse(directResponseText) : {}
       const decodedDirectResponse = /**
                                      * Narrows the runtime value to the documented type.
-                                      @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(directJson))
+                                     * @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(directJson))
 
       this.throwOnErrorFrontendModelResponse({
         commandType,
@@ -4111,7 +4268,7 @@ export default class FrontendModelBase {
   static async executeCustomCommand({commandName, commandType, memberId = null, payload, resourcePath}) {
     const serializedPayload = /**
                                * Narrows the runtime value to the documented type.
-                                @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(payload))
+                               * @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(payload))
     const customPath = frontendModelCustomCommandPath({
       commandName,
       memberId,
@@ -4135,7 +4292,7 @@ export default class FrontendModelBase {
 
     const decodedBatchResponse = /**
                                   * Narrows the runtime value to the documented type.
-                                   @type {Record<string, ?>} */ (batchResponse)
+                                  * @type {Record<string, ?>} */ (batchResponse)
 
     this.throwOnErrorFrontendModelResponse({
       commandType,
@@ -4181,7 +4338,7 @@ export default class FrontendModelBase {
 
     const error = /**
                    * Narrows the runtime value to the documented type.
-                    @type {Error & {velocious?: Record<string, ?>, errorType?: string, validationErrors?: Record<string, ?>, debugErrorClass?: string, debugBacktrace?: string[]}} */ (new Error(errorMessage))
+                   * @type {Error & {velocious?: Record<string, ?>, errorType?: string, validationErrors?: Record<string, ?>, debugErrorClass?: string, debugBacktrace?: string[]}} */ (new Error(errorMessage))
     if (response.velocious && typeof response.velocious === "object") {
       error.velocious = response.velocious
     }
@@ -4212,7 +4369,7 @@ export default class FrontendModelBase {
   static configuredFrontendModelAttributeNames() {
     const resourceConfig = /**
                             * Narrows the runtime value to the documented type.
-                             @type {Record<string, ?>} */ (this.resourceConfig())
+                            * @type {Record<string, ?>} */ (this.resourceConfig())
     const attributes = resourceConfig.attributes
 
     if (Array.isArray(attributes)) {