velocious 1.0.431 → 1.0.433

package/build/frontend-models/base.js

@@ -0,0 +1,4004 @@
+// @ts-check
+
+import * as inflection from "inflection"
+import timeout from "awaitery/build/timeout.js"
+import wait from "awaitery/build/wait.js"
+import FrontendModelQuery, {frontendModelEventOptionsPayload} from "./query.js"
+import FrontendModelPreloader from "./preloader.js"
+import {registerFrontendModel, resolveFrontendModelClass} from "./model-registry.js"
+import {validateFrontendModelResourceCommandName, validateFrontendModelResourcePath} from "./resource-config-validation.js"
+import {deserializeFrontendModelTransportValue, serializeFrontendModelTransportValue} from "./transport-serialization.js"
+import VelociousWebsocketClient from "../http-client/websocket-client.js"
+import {bufferOutgoingEvent, drainBufferedOutgoingEvents} from "./outgoing-event-buffer.js"
+import {defineModelScope} from "../utils/model-scope.js"
+import isPlainObject from "../utils/plain-object.js"
+import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQueryData, setPayloadAssociationCount, setPayloadComputedAbility, setPayloadQueryData} from "../record-payload-values.js"
+
+/**
+ * FrontendModelCommandType type.
+  @typedef {"create" | "find" | "index" | "update" | "destroy" | "attach" | "download" | "url"} FrontendModelCommandType */
+/**
+ * FrontendModelRequestCommandType type.
+  @typedef {FrontendModelCommandType | string} FrontendModelRequestCommandType */
+/**
+ * Defines this typedef.
+ * @typedef {{type: "hasOne" | "hasMany"}} FrontendModelAttachmentDefinition
+ */
+/**
+ * Defines this typedef.
+ * @typedef {{attributes?: string[], builtInCollectionCommands?: string[], builtInMemberCommands?: string[], collectionCommands?: string[], commands?: string[], memberCommands?: string[], attachments?: Record<string, FrontendModelAttachmentDefinition>, modelName?: string, nestedAttributes?: Record<string, {allowDestroy?: boolean, limit?: number}>, primaryKey?: string, relationships?: string[]}} FrontendModelResourceConfig
+ */
+/**
+ * FrontendModelTransportConfig type.
+ * @typedef {object} FrontendModelTransportConfig
+ * @property {string | (() => string | undefined | null)} [url] - Optional frontend-model URL. This should be the shared endpoint (for example `"/frontend-models"` or `"https://example.com/frontend-models"`).
+ * @property {boolean} [shared] - Deprecated shared-endpoint flag retained for compatibility. Frontend-model CRUD/custom commands use the shared frontend-model API envelope by default.
+ * @property {string | (() => string | undefined | null)} [websocketUrl] - Optional websocket URL. When set, Velocious creates and manages its own websocket client internally. Subscriptions use the websocket; CRUD uses HTTP and falls back gracefully. Example: `"ws://localhost:3006/websocket"`.
+ * @property {{post: (path: string, body?: ?, options?: {headers?: Record<string, string>}) => Promise<{json: () => ?}>, subscribe: (channel: string, options: {params?: Record<string, ?>}, callback: (payload: ?) => void) => (() => void), subscribeAndWait?: (channel: string, options: {params?: Record<string, ?>}, callback: (payload: ?) => void) => Promise<(() => void)>}} [websocketClient] - Optional websocket client for shared frontend-model API requests and subscriptions.
+ * @property {Record<string, string> | (() => Record<string, string>)} [requestHeaders] - Extra HTTP/WS headers to attach to every frontend-model API request. Pass a function to compute them at request time (for example to include the current locale).
+ * @property {{get: () => string | null | undefined | Promise<string | null | undefined>, set: (sessionId: string) => void | Promise<void>, clear: () => void | Promise<void>}} [sessionStore] - Optional sessionId persistence hook forwarded to the internal `VelociousWebsocketClient` so WS sessions can be resumed across page reloads / app restarts.
+ */
+/**
+ * FrontendModelIdleWaitArgs type.
+ * @typedef {object} FrontendModelIdleWaitArgs
+ * @property {number} [quietMs] - Milliseconds the transport must stay idle before resolving.
+ * @property {number} [timeout] - Timeout in milliseconds.
+ */
+
+/**
+ * Frontend model transport config.
+  @type {FrontendModelTransportConfig} */
+const frontendModelTransportConfig = {}
+const SHARED_FRONTEND_MODEL_API_PATH = "/frontend-models"
+const PRELOADED_RELATIONSHIPS_KEY = "__preloadedRelationships"
+const SELECTED_ATTRIBUTES_KEY = "__selectedAttributes"
+const ASSOCIATION_COUNTS_KEY = "__associationCounts"
+const QUERY_DATA_KEY = "__queryData"
+const ABILITIES_KEY = "__abilities"
+/**
+ * Pending shared frontend model requests.
+  @type {Array<{commandName?: string, commandType: FrontendModelRequestCommandType, customPath?: string, modelClass: typeof FrontendModelBase, 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>} */
+let frontendModelIdleResolvers = []
+
+/**
+ * Internal websocket client.
+  @type {VelociousWebsocketClient | null} */
+let internalWebsocketClient = null
+
+/**
+ * Runs frontend model transport is idle.
+ * @returns {boolean} - Whether all queued and active frontend-model transport requests are done.
+ */
+function frontendModelTransportIsIdle() {
+  return activeFrontendModelTransportRequestCount === 0
+    && pendingSharedFrontendModelRequests.length === 0
+    && !sharedFrontendModelFlushScheduled
+}
+
+/**
+ * Runs resolve frontend model idle waiters.
+  @returns {void} */
+function resolveFrontendModelIdleWaiters() {
+  if (!frontendModelTransportIsIdle()) return
+
+  const resolvers = frontendModelIdleResolvers
+  frontendModelIdleResolvers = []
+
+  for (const resolve of resolvers) {
+    resolve()
+  }
+}
+
+/**
+ * Runs wait for frontend model transport quiet period.
+ * @param {number} milliseconds - Quiet period length.
+ * @returns {Promise<void>} Resolves after the quiet period.
+ */
+async function waitForFrontendModelTransportQuietPeriod(milliseconds) {
+  if (milliseconds <= 0) return
+
+  await wait(milliseconds)
+}
+
+/**
+ * Runs wait for frontend model transport idle.
+ * @param {number} quietMs - Milliseconds the transport must stay idle before resolving.
+ * @returns {Promise<void>} Resolves when transport stays idle.
+ */
+async function waitForFrontendModelTransportIdle(quietMs = 0) {
+  while (true) {
+    if (frontendModelTransportIsIdle()) {
+      await new Promise((resolve) => queueMicrotask(() => resolve(undefined)))
+
+      if (frontendModelTransportIsIdle()) {
+        await waitForFrontendModelTransportQuietPeriod(quietMs)
+
+        if (frontendModelTransportIsIdle()) return
+      }
+    } else {
+      await new Promise((resolve) => {
+        frontendModelIdleResolvers.push(() => resolve(undefined))
+      })
+    }
+  }
+}
+
+/**
+ * Runs track frontend model transport request.
+ * @template T
+ * @param {() => Promise<T>} callback - Transport callback.
+ * @returns {Promise<T>} - Callback result.
+ */
+async function trackFrontendModelTransportRequest(callback) {
+  activeFrontendModelTransportRequestCount += 1
+
+  try {
+    return await callback()
+  } finally {
+    activeFrontendModelTransportRequestCount -= 1
+    resolveFrontendModelIdleWaiters()
+  }
+}
+
+/**
+ * Resolve the internal websocket client from websocketUrl config.
+ * Creates the client lazily on first call. Returns null if WebSocket
+ * is not available or websocketUrl is not configured.
+ * @returns {VelociousWebsocketClient | null} Websocket client or null.
+ */
+function resolveInternalWebsocketClient() {
+  if (internalWebsocketClient) return internalWebsocketClient
+
+  const websocketUrl = frontendModelTransportConfig.websocketUrl
+
+  if (!websocketUrl) return null
+  if (typeof globalThis.WebSocket === "undefined") return null
+
+  const resolvedUrl = typeof websocketUrl === "function" ? websocketUrl() : websocketUrl
+
+  if (!resolvedUrl) return null
+
+  internalWebsocketClient = new VelociousWebsocketClient({
+    autoReconnect: true,
+    sessionStore: frontendModelTransportConfig.sessionStore,
+    url: resolvedUrl
+  })
+  internalWebsocketClient.onReconnect = flushBufferedOutgoingEventsAfterReconnect
+
+  return internalWebsocketClient
+}
+
+/**
+ * Runs flush buffered outgoing events after reconnect.
+  @returns {Promise<void>} */
+async function flushBufferedOutgoingEventsAfterReconnect() {
+  if (!internalWebsocketClient) return
+
+  const events = drainBufferedOutgoingEvents()
+
+  for (let index = 0; index < events.length; index += 1) {
+    try {
+      await internalWebsocketClient.post(events[index].customPath, events[index].payload)
+    } catch {
+      const socketOpen = internalWebsocketClient.socket?.readyState === internalWebsocketClient.socket?.OPEN
+
+      if (socketOpen) {
+        continue
+      }
+
+      for (let remaining = index; remaining < events.length; remaining += 1) {
+        bufferOutgoingEvent(events[remaining])
+      }
+
+      return
+    }
+  }
+}
+
+/**
+ * Runs default frontend model resource path.
+ * @param {typeof FrontendModelBase} modelClass - Frontend model class.
+ * @returns {string} - Default resource path for the model class.
+ */
+function defaultFrontendModelResourcePath(modelClass) {
+  return `/${inflection.dasherize(inflection.pluralize(inflection.underscore(modelClass.getModelName())))}`
+}
+
+/** Error raised when reading an attribute that was not selected in query payloads. */
+export class AttributeNotSelectedError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} modelName - Model class name.
+   * @param {string} attributeName - Attribute that was requested.
+   */
+  constructor(modelName, attributeName) {
+    super(`${modelName}#${attributeName} was not selected`)
+    this.name = "AttributeNotSelectedError"
+  }
+}
+
+/**
+ * Lightweight singular relationship state holder for frontend model instances.
+ * @template {typeof FrontendModelBase} S
+ * @template {typeof FrontendModelBase} T
+ */
+export class FrontendModelSingularRelationship {
+  /**
+   * Runs constructor.
+   * @param {InstanceType<S>} model - Parent model.
+   * @param {string} relationshipName - Relationship name.
+   * @param {T | null} targetModelClass - Target model class.
+   */
+  constructor(model, relationshipName, targetModelClass) {
+    this.model = model
+    this.relationshipName = relationshipName
+    this.targetModelClass = targetModelClass
+    this._preloaded = false
+    this._loadedValue = null
+  }
+
+  /**
+   * Runs set loaded.
+   * @param {?} loadedValue - Loaded relationship value.
+   * @returns {void}
+   */
+  setLoaded(loadedValue) {
+    this._loadedValue = loadedValue == undefined ? null : loadedValue
+    this._preloaded = true
+  }
+
+  /**
+   * Runs get preloaded.
+   * @returns {boolean} - Whether relationship is preloaded.
+   */
+  getPreloaded() {
+    return this._preloaded
+  }
+
+  /**
+   * Runs loaded.
+   * @returns {?} - Loaded relationship value.
+   */
+  loaded() {
+    if (!this._preloaded) {
+      throw new Error(`${this.model.constructor.name}#${this.relationshipName} hasn't been preloaded`)
+    }
+
+    return this._loadedValue
+  }
+
+  /**
+   * Runs build.
+   * @param {Record<string, ?>} [attributes] - New model attributes.
+   * @returns {InstanceType<T>} - Built model.
+   */
+  build(attributes = {}) {
+    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))
+
+    this.setLoaded(model)
+
+    return model
+  }
+}
+
+/**
+ * Lightweight has-many relationship state holder for frontend model instances.
+ * @template {typeof FrontendModelBase} S
+ * @template {typeof FrontendModelBase} T
+ */
+export class FrontendModelHasManyRelationship {
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {Array<InstanceType<T>>} */
+  _loadedValue
+
+  /**
+   * Runs constructor.
+   * @param {InstanceType<S>} model - Parent model.
+   * @param {string} relationshipName - Relationship name.
+   * @param {T | null} targetModelClass - Target model class.
+   */
+  constructor(model, relationshipName, targetModelClass) {
+    this.model = model
+    this.relationshipName = relationshipName
+    this.targetModelClass = targetModelClass
+    this._preloaded = false
+    this._loadedValue = []
+  }
+
+  /**
+   * Runs set loaded.
+   * @param {Array<InstanceType<T>>} loadedValue - Loaded relationship value.
+   * @returns {void}
+   */
+  setLoaded(loadedValue) {
+    this._loadedValue = Array.isArray(loadedValue) ? loadedValue : []
+    this._preloaded = true
+  }
+
+  /**
+   * Runs get preloaded.
+   * @returns {boolean} - Whether relationship is preloaded.
+   */
+  getPreloaded() {
+    return this._preloaded
+  }
+
+  /**
+   * Runs loaded.
+   * @returns {Array<InstanceType<T>>} - Loaded relationship values.
+   */
+  loaded() {
+    if (!this._preloaded) {
+      throw new Error(`${this.model.constructor.name}#${this.relationshipName} hasn't been preloaded`)
+    }
+
+    return this._loadedValue
+  }
+
+  /**
+   * Runs add to loaded.
+   * @param {Array<InstanceType<T>>} models - Models to append.
+   * @returns {void}
+   */
+  addToLoaded(models) {
+    const loadedModels = this.getPreloaded() ? this.loaded() : []
+
+    this.setLoaded([...loadedModels, ...models])
+  }
+
+  /**
+   * Runs build.
+   * @param {Record<string, ?>} [attributes] - New model attributes.
+   * @returns {InstanceType<T>} - Built model.
+   */
+  build(attributes = {}) {
+    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))
+
+    this.addToLoaded([model])
+
+    return model
+  }
+
+  /**
+   * Force-reload the relationship. When the parent record was loaded as part
+   * of a batch, siblings that have not preloaded this relationship get
+   * 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.
+   */
+  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)
+
+    if (batched) return this._loadedValue
+
+    return /** Narrows the runtime value to the documented type. @type {Promise<Array<InstanceType<T>>>} */ (this.model.loadRelationship(this.relationshipName))
+  }
+
+  /**
+   * Runs to array.
+   * @returns {Promise<Array<InstanceType<T>>>} - Loaded relationship models.
+   */
+  async toArray() {
+    if (this.getPreloaded() || this._loadedValue.length > 0) {
+      return this._loadedValue
+    }
+
+    return await this.load()
+  }
+}
+
+/**
+ * Runs relationship type is collection.
+ * @param {string} relationshipType - Relationship type.
+ * @returns {boolean} - Whether relationship type is has-many.
+ */
+function relationshipTypeIsCollection(relationshipType) {
+  return relationshipType == "hasMany"
+}
+
+/**
+ * Downloaded frontend-model attachment payload wrapper.
+ */
+export class FrontendModelAttachmentDownload {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options.
+   * @param {string} args.id - Attachment id.
+   * @param {string} args.filename - Filename.
+   * @param {string | null} args.contentType - Content type.
+   * @param {number} args.byteSize - File size in bytes.
+   * @param {Uint8Array} args.content - File content bytes.
+   * @param {string | null} [args.url] - Resolvable attachment URL.
+   */
+  constructor({byteSize, content, contentType, filename, id, url = null}) {
+    this.idValue = id
+    this.filenameValue = filename
+    this.contentTypeValue = contentType
+    this.byteSizeValue = byteSize
+    this.contentValue = content
+    this.urlValue = url
+  }
+
+  /**
+   * Runs byte size.
+   * @returns {number} - File size in bytes.
+   */
+  byteSize() { return this.byteSizeValue }
+  /**
+   * Runs content.
+   * @returns {Uint8Array} - File content bytes.
+   */
+  content() { return this.contentValue }
+  /**
+   * Runs content type.
+   * @returns {string | null} - Content type.
+   */
+  contentType() { return this.contentTypeValue }
+  /**
+   * Runs filename.
+   * @returns {string} - Filename.
+   */
+  filename() { return this.filenameValue }
+  /**
+   * Runs id.
+   * @returns {string} - Attachment id.
+   */
+  id() { return this.idValue }
+  /**
+   * Runs url.
+   * @returns {string | null} - Resolvable attachment URL.
+   */
+  url() { return this.urlValue }
+}
+
+/**
+ * Runs frontend model attachment command payload.
+ * @param {FrontendModelAttachmentHandle} attachment - Attachment wrapper.
+ * @param {string | undefined} attachmentId - Optional has-many attachment id.
+ * @returns {Record<string, ?>} - Command payload.
+ */
+function frontendModelAttachmentCommandPayload(attachment, attachmentId) {
+  /**
+   * Payload.
+    @type {Record<string, ?>} */
+  const payload = {
+    attachmentName: attachment.attachmentName,
+    id: attachment.model.primaryKeyValue()
+  }
+
+  if (attachmentId) payload.attachmentId = attachmentId
+
+  return payload
+}
+
+/**
+ * Runs frontend attachment value is bytes.
+ * @param {?} value - Candidate value.
+ * @returns {boolean} - Whether value looks like byte data.
+ */
+function frontendAttachmentValueIsBytes(value) {
+  return value instanceof Uint8Array || value instanceof ArrayBuffer || (typeof Buffer !== "undefined" && Buffer.isBuffer(value))
+}
+
+/**
+ * Runs frontend attachment value supports array buffer.
+ * @param {?} value - Candidate value.
+ * @returns {value is {arrayBuffer: () => Promise<ArrayBuffer>}} - Whether candidate supports arrayBuffer().
+ */
+function frontendAttachmentValueSupportsArrayBuffer(value) {
+  return Boolean(value && typeof value === "object" && typeof /**
+                                                               * Narrows the runtime value to the documented type.
+                                                                @type {?} */ (value).arrayBuffer === "function")
+}
+
+/**
+ * Runs frontend attachment normalize bytes.
+ * @param {Uint8Array | Buffer | ArrayBuffer} value - Byte-like value.
+ * @returns {Uint8Array} - Uint8Array bytes.
+ */
+function frontendAttachmentNormalizeBytes(value) {
+  if (value instanceof Uint8Array) return 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))) {
+    return new Uint8Array(/**
+                           * Narrows the runtime value to the documented type.
+                            @type {Buffer} */ (value))
+  }
+
+  throw new Error("Unsupported attachment bytes value")
+}
+
+/**
+ * Runs frontend attachment bytes to base64.
+ * @param {Uint8Array} bytes - Bytes.
+ * @returns {string} - Base64 value.
+ */
+function frontendAttachmentBytesToBase64(bytes) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64")
+  }
+
+  let binary = ""
+
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte)
+  }
+
+  if (typeof btoa !== "function") throw new Error("Missing base64 encoder")
+
+  return btoa(binary)
+}
+
+/**
+ * Runs frontend attachment base64 to bytes.
+ * @param {string} value - Base64 value.
+ * @returns {Uint8Array} - Decoded bytes.
+ */
+function frontendAttachmentBase64ToBytes(value) {
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(value, "base64"))
+  }
+
+  if (typeof atob !== "function") throw new Error("Missing base64 decoder")
+
+  const binary = atob(value)
+  const bytes = new Uint8Array(binary.length)
+
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index)
+  }
+
+  return bytes
+}
+
+/**
+ * Runs frontend attachment value is plain object.
+ * @param {?} value - Candidate value.
+ * @returns {value is Record<string, ?>} - Whether value is plain object.
+ */
+function frontendAttachmentValueIsPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false
+
+  const prototype = Object.getPrototypeOf(value)
+
+  return prototype === Object.prototype || prototype === null
+}
+
+/**
+ * Runs frontend model payload contains attachment upload.
+ * @param {?} value - Payload candidate.
+ * @returns {boolean} - Whether payload contains an attachment upload body.
+ */
+function frontendModelPayloadContainsAttachmentUpload(value) {
+  if (!value || typeof value !== "object") return false
+
+  if (Array.isArray(value)) {
+    return value.some((entry) => frontendModelPayloadContainsAttachmentUpload(entry))
+  }
+
+  if (!frontendAttachmentValueIsPlainObject(value)) return false
+
+  if (typeof value.contentBase64 === "string") {
+    return true
+  }
+
+  return Object.values(value).some((entry) => frontendModelPayloadContainsAttachmentUpload(entry))
+}
+
+/**
+ * Runs normalize frontend attachment input.
+ * @param {?} input - Attachment input.
+ * @returns {Promise<Record<string, ?>>} - Transport-safe attachment payload.
+ */
+async function normalizeFrontendAttachmentInput(input) {
+  if (frontendAttachmentValueIsPlainObject(input) && "file" in input) {
+    const normalizedFile = await normalizeFrontendAttachmentInput(input.file)
+    const merged = {
+      ...normalizedFile
+    }
+
+    if (typeof input.filename === "string" && input.filename.length > 0) merged.filename = input.filename
+    if (typeof input.contentType === "string" && input.contentType.length > 0) merged.contentType = input.contentType
+
+    return merged
+  }
+
+  if (frontendAttachmentValueIsPlainObject(input)) {
+    if (typeof input.path === "string" && input.path.length > 0) {
+      throw new Error("Attachment path input is not supported in frontend models")
+    }
+
+    if (typeof input.contentBase64 === "string") {
+      return {
+        contentBase64: input.contentBase64,
+        contentType: typeof input.contentType === "string" && input.contentType.length > 0 ? input.contentType : null,
+        filename: typeof input.filename === "string" && input.filename.length > 0 ? input.filename : undefined
+      }
+    }
+  }
+
+  if (frontendAttachmentValueSupportsArrayBuffer(input)) {
+    const bytes = new Uint8Array(await input.arrayBuffer())
+
+    return {
+      contentBase64: frontendAttachmentBytesToBase64(bytes),
+      contentType: typeof /**
+                           * Narrows the runtime value to the documented type.
+                            @type {?} */ (input).type === "string" && /**
+                                                                       * Narrows the runtime value to the documented type.
+                                                                        @type {?} */ (input).type.length > 0
+        ? /**
+           * Narrows the runtime value to the documented type.
+            @type {?} */ (input).type
+        : null,
+      filename: typeof /**
+                        * Narrows the runtime value to the documented type.
+                         @type {?} */ (input).name === "string" && /**
+                                                                    * Narrows the runtime value to the documented type.
+                                                                     @type {?} */ (input).name.length > 0
+        ? /**
+           * Narrows the runtime value to the documented type.
+            @type {?} */ (input).name
+        : "attachment.bin"
+    }
+  }
+
+  if (frontendAttachmentValueIsBytes(input)) {
+    const bytes = frontendAttachmentNormalizeBytes(/**
+                                                    * Narrows the runtime value to the documented type.
+                                                     @type {Uint8Array | Buffer | ArrayBuffer} */ (input))
+
+    return {
+      contentBase64: frontendAttachmentBytesToBase64(bytes),
+      contentType: null,
+      filename: "attachment.bin"
+    }
+  }
+
+  throw new Error("Unsupported frontend attachment input")
+}
+
+/**
+ * Frontend-model attachment helper for one attachment name.
+ */
+export class FrontendModelAttachmentHandle {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options.
+   * @param {FrontendModelBase} args.model - Model instance.
+   * @param {string} args.attachmentName - Attachment name.
+   */
+  constructor({attachmentName, model}) {
+    this.model = model
+    this.attachmentName = attachmentName
+  }
+
+  /**
+   * Runs attach.
+   * @param {?} input - Attachment input.
+   * @returns {Promise<void>} - Resolves when attached.
+   */
+  async attach(input) {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.model.constructor)
+    const normalizedInput = await normalizeFrontendAttachmentInput(input)
+    const response = await ModelClass.executeCommand("attach", {
+      attachment: normalizedInput,
+      attachmentName: this.attachmentName,
+      id: this.model.primaryKeyValue()
+    })
+
+    this.model.assignAttributes(ModelClass.attributesFromResponse(response))
+  }
+
+  /**
+   * Runs download.
+   * @param {string} [attachmentId] - Optional attachment id for has-many attachments.
+   * @returns {Promise<FrontendModelAttachmentDownload | null>} - Downloaded attachment payload.
+   */
+  async download(attachmentId) {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.model.constructor)
+    const response = await ModelClass.executeCommand("download", frontendModelAttachmentCommandPayload(this, attachmentId))
+    const attachmentPayload = response.attachment
+
+    if (!attachmentPayload || typeof attachmentPayload !== "object") return null
+
+    const contentBase64 = typeof attachmentPayload.contentBase64 === "string" ? attachmentPayload.contentBase64 : ""
+    const content = frontendAttachmentBase64ToBytes(contentBase64)
+    const byteSize = Number(attachmentPayload.byteSize)
+
+    return new FrontendModelAttachmentDownload({
+      byteSize: Number.isFinite(byteSize) ? byteSize : content.length,
+      content,
+      contentType: typeof attachmentPayload.contentType === "string" && attachmentPayload.contentType.length > 0 ? attachmentPayload.contentType : null,
+      filename: typeof attachmentPayload.filename === "string" && attachmentPayload.filename.length > 0 ? attachmentPayload.filename : "attachment.bin",
+      id: typeof attachmentPayload.id === "string" ? attachmentPayload.id : "",
+      url: typeof attachmentPayload.url === "string" && attachmentPayload.url.length > 0 ? attachmentPayload.url : null
+    })
+  }
+
+  /**
+   * Runs url.
+   * @param {string} [attachmentId] - Optional attachment id for has-many attachments.
+   * @returns {Promise<string | null>} - Resolvable attachment URL.
+   */
+  async url(attachmentId) {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.model.constructor)
+    const response = await ModelClass.executeCommand("url", frontendModelAttachmentCommandPayload(this, attachmentId))
+
+    if (typeof response.url === "string" && response.url.length > 0) {
+      return response.url
+    }
+
+    return null
+  }
+
+  /**
+   * Runs download url.
+   * @returns {string} - Download URL for this attachment on the configured backend.
+   */
+  downloadUrl() {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.model.constructor)
+    const commandName = ModelClass.commandName("download")
+    const resourcePath = ModelClass.resourcePath()
+    const commandUrl = frontendModelCommandUrl(resourcePath, commandName)
+    const params = new URLSearchParams({
+      attachmentName: this.attachmentName,
+      id: String(this.model.primaryKeyValue())
+    })
+
+    return `${commandUrl}?${params.toString()}`
+  }
+}
+
+/**
+ * Runs normalize frontend model transport url.
+ * @param {string | undefined | null} value - URL candidate.
+ * @returns {string} - Normalized URL without trailing slash.
+ */
+function normalizeFrontendModelTransportUrl(value) {
+  if (typeof value !== "string") return ""
+
+  const trimmed = value.trim()
+
+  if (!trimmed.length) return ""
+
+  return trimmed.replace(/\/+$/, "")
+}
+
+/**
+ * Runs frontend model transport url.
+ * @returns {string} - Resolved frontend-model transport URL.
+ */
+function frontendModelTransportUrl() {
+  const configuredUrl = typeof frontendModelTransportConfig.url === "function"
+    ? frontendModelTransportConfig.url()
+    : frontendModelTransportConfig.url
+
+  return normalizeFrontendModelTransportUrl(configuredUrl)
+}
+
+/**
+ * Runs clone frontend model attributes.
+ * @param {Record<string, ?>} value - Attributes hash.
+ * @returns {Record<string, ?>} - Cloned attributes hash.
+ */
+function cloneFrontendModelAttributes(value) {
+  return /** Narrows the runtime value to the documented type. @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(serializeFrontendModelTransportValue(value)))
+}
+
+/**
+ * Shared channel name for model lifecycle events (Phase 3).
+ * Matches the backend `FRONTEND_MODELS_CHANNEL_NAME`.
+ */
+const FRONTEND_MODELS_CHANNEL_NAME = "frontend-models"
+
+/**
+ * Defines this typedef.
+ * @typedef {{callback: (payload: {id: string, model: InstanceType<typeof FrontendModelBase>}) => void, eventFilterKey: string | null, eventFilterPayload: import("./query.js").FrontendModelEventFilterPayload | null, projectionPayload: import("./query.js").FrontendModelProjectionPayload}} FrontendModelModelEventCallbackEntry
+ */
+/**
+ * Defines this typedef.
+ * @typedef {{callback: (payload: {id: string}) => void}} FrontendModelDestroyEventCallbackEntry
+ */
+
+/**
+ * Runs merge frontend model event preload.
+ * @param {Record<string, import("./query.js").FrontendModelTransportValue>} target - Target preload payload.
+ * @param {Record<string, import("./query.js").FrontendModelTransportValue>} source - Source preload payload.
+ * @returns {void}
+ */
+function mergeFrontendModelEventPreload(target, source) {
+  for (const [relationshipName, value] of Object.entries(source)) {
+    const existingValue = target[relationshipName]
+
+    if (value === true || value === false) {
+      if (existingValue === undefined) target[relationshipName] = value
+      continue
+    }
+
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      target[relationshipName] = value
+      continue
+    }
+
+    if (!existingValue || typeof existingValue !== "object" || Array.isArray(existingValue)) {
+      target[relationshipName] = {}
+    }
+
+    mergeFrontendModelEventPreload(
+      /**
+       * Narrows the runtime value to the documented type.
+        @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)
+    )
+  }
+}
+
+/**
+ * Runs merge frontend model event select.
+ * @param {Record<string, string[]>} target - Target select map.
+ * @param {Record<string, string[]>} source - Source select map.
+ * @returns {void}
+ */
+function mergeFrontendModelEventSelect(target, source) {
+  for (const [modelName, attributes] of Object.entries(source)) {
+    const existingAttributes = target[modelName] || []
+
+    target[modelName] = Array.from(new Set(existingAttributes.concat(attributes)))
+  }
+}
+
+/**
+ * Runs merge unique frontend model event entries.
+ * @param {Array<import("./query.js").FrontendModelWithCountPayloadEntry | import("./query.js").FrontendModelAbilitiesPayloadEntry>} target - Target array.
+ * @param {Array<import("./query.js").FrontendModelWithCountPayloadEntry | import("./query.js").FrontendModelAbilitiesPayloadEntry>} source - Source array.
+ * @returns {void}
+ */
+function mergeUniqueFrontendModelEventEntries(target, source) {
+  const existingKeys = new Set(target.map((entry) => JSON.stringify(entry)))
+
+  for (const entry of source) {
+    const key = JSON.stringify(entry)
+
+    if (existingKeys.has(key)) continue
+
+    target.push(entry)
+    existingKeys.add(key)
+  }
+}
+
+/**
+ * Runs merge frontend model event projection payload.
+ * @param {import("./query.js").FrontendModelProjectionPayload} target - Target payload.
+ * @param {import("./query.js").FrontendModelProjectionPayload} source - Source payload.
+ * @returns {void}
+ */
+function mergeFrontendModelEventProjectionPayload(target, source) {
+  if (source.preload) {
+    if (!target.preload) target.preload = {}
+    mergeFrontendModelEventPreload(target.preload, source.preload)
+  }
+
+  if (source.select) {
+    if (!target.select) target.select = {}
+    mergeFrontendModelEventSelect(target.select, source.select)
+  }
+
+  if (source.selectsExtra) {
+    if (!target.selectsExtra) target.selectsExtra = {}
+    mergeFrontendModelEventSelect(target.selectsExtra, source.selectsExtra)
+  }
+
+  if (source.withCount) {
+    if (!target.withCount) target.withCount = []
+    mergeUniqueFrontendModelEventEntries(target.withCount, source.withCount)
+  }
+
+  if (source.abilities) {
+    if (!target.abilities) target.abilities = []
+    mergeUniqueFrontendModelEventEntries(target.abilities, source.abilities)
+  }
+
+  if (source.queryData !== undefined) {
+    const targetQueryData = Array.isArray(target.queryData) ? target.queryData : []
+
+    target.queryData = targetQueryData
+    const queryDataEntries = Array.isArray(source.queryData) ? source.queryData : [source.queryData]
+
+    for (const entry of queryDataEntries) {
+      targetQueryData.push(entry)
+    }
+  }
+}
+
+/**
+ * Runs frontend model matched event filter keys.
+ * @param {?} body - Raw websocket event body.
+ * @returns {Set<string>} - Matched event filter keys delivered by the backend.
+ */
+function frontendModelMatchedEventFilterKeys(body) {
+  if (!body || typeof body !== "object") return new Set()
+
+  const keys = /**
+                * Narrows the runtime value to the documented type.
+                 @type {{matchedEventFilterKeys?: ?}} */ (body).matchedEventFilterKeys
+
+  if (!Array.isArray(keys)) return new Set()
+
+  return new Set(keys.map((key) => String(key)))
+}
+
+/**
+ * Runs frontend model event entry matches.
+ * @param {FrontendModelModelEventCallbackEntry} entry - Callback entry.
+ * @param {Set<string>} matchedEventFilterKeys - Backend matched filter keys.
+ * @returns {boolean} Whether the callback should receive the event.
+ */
+function frontendModelEventEntryMatches(entry, matchedEventFilterKeys) {
+  if (!entry.eventFilterKey) return true
+
+  return matchedEventFilterKeys.has(entry.eventFilterKey)
+}
+
+/**
+ * Runs assert no destroy event filter.
+ * @param {typeof FrontendModelBase} ModelClass - Event model class.
+ * @param {import("./query.js").FrontendModelEventOptions} options - Event options.
+ * @returns {void}
+ */
+function assertNoDestroyEventFilter(ModelClass, options) {
+  const eventOptionsPayload = frontendModelEventOptionsPayload(ModelClass, options)
+
+  if (!eventOptionsPayload.eventFilterKey) return
+
+  throw new Error("Frontend model destroy event subscriptions do not support query filters")
+}
+
+/**
+ * Per-model class singleton that multiplexes all registered onCreate /
+ * onUpdate / onDestroy callbacks — class-level + instance-level —
+ * over one WebsocketChannelV2 subscription. Subscription opens on the
+ * first listener and closes when the last one unsubscribes.
+ *
+ * Instance-level listeners also receive auto-merge: when an `update`
+ * event arrives for a registered instance id, the instance's
+ * attributes are updated in place before the callback fires, so
+ * callers can read fresh values from the same instance handle.
+ */
+class FrontendModelEventSubscription {
+  /**
+   * Runs constructor.
+   * @param {typeof FrontendModelBase} ModelClass - Frontend model class for this subscription bucket.
+   */
+  constructor(ModelClass) {
+    this.ModelClass = ModelClass
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Set<FrontendModelModelEventCallbackEntry>} */
+    this.classCreateCallbacks = new Set()
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Set<FrontendModelModelEventCallbackEntry>} */
+    this.classUpdateCallbacks = new Set()
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Set<FrontendModelDestroyEventCallbackEntry>} */
+    this.classDestroyCallbacks = new Set()
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Map<string, {instance: InstanceType<typeof FrontendModelBase>, updateCallbacks: Set<FrontendModelModelEventCallbackEntry>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry>}>} */
+    this.instanceListeners = new Map()
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {?} */
+    this.channelHandle = null
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Promise<void> | null} */
+    this.readyPromise = null
+    /**
+     * Narrows the runtime value to the documented type.
+      @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.
+   */
+  subscriptionParams() {
+    /**
+     * Projection payload.
+      @type {import("./query.js").FrontendModelProjectionPayload} */
+    const projectionPayload = {}
+    /**
+     * Event filters by key.
+      @type {Record<string, import("./query.js").FrontendModelEventFilterPayloadEntry>} */
+    const eventFiltersByKey = {}
+    const projectionEntries = []
+    let hasUnfilteredEventDelivery = this.classDestroyCallbacks.size > 0
+
+    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
+    }
+
+    for (const entry of projectionEntries) {
+      mergeFrontendModelEventProjectionPayload(projectionPayload, entry.projectionPayload)
+
+      if (entry.eventFilterKey && entry.eventFilterPayload) {
+        eventFiltersByKey[entry.eventFilterKey] = {
+          ...entry.eventFilterPayload,
+          key: entry.eventFilterKey
+        }
+      } else {
+        hasUnfilteredEventDelivery = true
+      }
+    }
+
+    const eventFilters = Object.values(eventFiltersByKey)
+    const eventFilterParams = eventFilters.length > 0
+      ? {
+          eventFilters,
+          ...(hasUnfilteredEventDelivery ? {unfilteredEventDelivery: true} : {})
+        }
+      : {}
+
+    return {
+      model: this.ModelClass.getModelName(),
+      ...eventFilterParams,
+      ...projectionPayload
+    }
+  }
+
+  /**
+   * Runs subscription params json.
+   * @returns {string} - Stable key for current subscription params.
+   */
+  subscriptionParamsJson() {
+    return JSON.stringify(this.subscriptionParams())
+  }
+
+  /**
+   * Runs ensure subscribed.
+    @returns {Promise<void>} */
+  async ensureSubscribed() {
+    const paramsJson = this.subscriptionParamsJson()
+
+    if (this.channelHandle && !this.channelHandle.isClosed()) {
+      if (this.subscriptionParamsKey !== paramsJson) {
+        this.channelHandle.close()
+        this.channelHandle = null
+        this.readyPromise = null
+      } else {
+        if (this.readyPromise) await this.readyPromise
+        return
+      }
+    }
+
+    // Serialize parallel calls (e.g. Promise.all([onCreate, onUpdate,
+    // onDestroy])) so we open exactly one subscription per model class
+    // instead of racing three concurrent subscribeChannel calls.
+    if (this.readyPromise) {
+      await this.readyPromise
+      return
+    }
+
+    const client = /**
+                    * Narrows the runtime value to the documented type.
+                     @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
+
+    if (!client || typeof client.subscribeChannel !== "function") {
+      throw new Error("Frontend model event subscriptions require configureTransport({websocketUrl}) or configureTransport({websocketClient})")
+    }
+
+    this.readyPromise = (async () => {
+      if (typeof client.connect === "function") await client.connect()
+
+      const params = this.subscriptionParams()
+
+      this.subscriptionParamsKey = JSON.stringify(params)
+      this.channelHandle = client.subscribeChannel(FRONTEND_MODELS_CHANNEL_NAME, {
+        params,
+        onMessage: (/**
+                     * Narrows the runtime value to the documented type.
+                      @type {?} */ body) => this._dispatchEvent(body),
+        onClose: () => {
+          this.channelHandle = null
+          this.readyPromise = null
+          this.subscriptionParamsKey = null
+          this.instanceListeners.clear()
+
+          const hasCallbacks = this.classCreateCallbacks.size > 0
+            || this.classUpdateCallbacks.size > 0
+            || this.classDestroyCallbacks.size > 0
+
+          if (hasCallbacks && client.autoReconnect) {
+            void this.ensureSubscribed()
+          }
+        }
+      })
+      await this.channelHandle.ready
+    })()
+
+    await this.readyPromise
+  }
+
+  /**
+   * Runs dispatch event.
+   * @param {?} body - WebSocket event payload.
+   */
+  _dispatchEvent(body) {
+    if (!body || typeof body !== "object") return
+
+    const action = body.action
+    const rawId = body.id
+
+    if (action !== "create" && action !== "update" && action !== "destroy") return
+    if (rawId === undefined || rawId === null) return
+
+    const id = String(rawId)
+    const matchedEventFilterKeys = frontendModelMatchedEventFilterKeys(body)
+
+    if (action === "destroy") {
+      const listener = this.instanceListeners.get(id)
+
+      if (listener) {
+        for (const entry of listener.destroyCallbacks) {
+          try { entry.callback({id}) } catch (error) { console.error(error) }
+        }
+        this.instanceListeners.delete(id)
+      }
+      for (const entry of this.classDestroyCallbacks) {
+        try { entry.callback({id}) } catch (error) { console.error(error) }
+      }
+      return
+    }
+
+    if (!body.record || typeof body.record !== "object") return
+
+    const deserializedRecord = /**
+                                * Narrows the runtime value to the documented type.
+                                 @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(body.record))
+    const freshModel = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {?} */ (this.ModelClass).instantiateFromResponse(deserializedRecord)
+    const listener = this.instanceListeners.get(id)
+
+    if (action === "update" && listener) {
+      const matchingUpdateCallbacks = Array.from(listener.updateCallbacks).filter((entry) =>
+        frontendModelEventEntryMatches(entry, matchedEventFilterKeys)
+      )
+
+      if (matchingUpdateCallbacks.length > 0) {
+        // Auto-merge into the registered instance so callers reading
+        // through the same handle see fresh attributes.
+        const instanceAny = /**
+                             * Narrows the runtime value to the documented type.
+                              @type {?} */ (listener.instance)
+
+        instanceAny.assignAttributes(freshModel.attributes())
+        instanceAny._persistedAttributes = cloneFrontendModelAttributes(listener.instance.attributes())
+
+        for (const entry of matchingUpdateCallbacks) {
+          try { entry.callback({id, model: listener.instance}) } catch (error) { console.error(error) }
+        }
+      }
+    }
+
+    const classCallbacks = action === "create" ? this.classCreateCallbacks : this.classUpdateCallbacks
+
+    for (const entry of classCallbacks) {
+      if (!frontendModelEventEntryMatches(entry, matchedEventFilterKeys)) continue
+
+      try { entry.callback({id, model: freshModel}) } catch (error) { console.error(error) }
+    }
+  }
+
+  /**
+   * Runs maybe teardown.
+    @returns {void} */
+  maybeTeardown() {
+    const hasAnyListener = this.classCreateCallbacks.size > 0
+      || this.classUpdateCallbacks.size > 0
+      || this.classDestroyCallbacks.size > 0
+      || this.instanceListeners.size > 0
+
+    if (hasAnyListener) return
+    if (!this.channelHandle) return
+
+    try {
+      this.channelHandle.close()
+    } catch (error) {
+      console.error(error)
+    }
+
+    this.channelHandle = null
+    this.readyPromise = null
+    this.subscriptionParamsKey = null
+  }
+}
+
+/**
+ * Frontend model event subscriptions.
+  @type {WeakMap<typeof FrontendModelBase, FrontendModelEventSubscription>} */
+const frontendModelEventSubscriptions = new WeakMap()
+
+/**
+ * Runs ensure frontend model event subscription.
+ * @param {typeof FrontendModelBase} ModelClass - Model class.
+ * @returns {FrontendModelEventSubscription} - Per-class subscription helper.
+ */
+function ensureFrontendModelEventSubscription(ModelClass) {
+  let sub = frontendModelEventSubscriptions.get(ModelClass)
+
+  if (!sub) {
+    sub = new FrontendModelEventSubscription(ModelClass)
+    frontendModelEventSubscriptions.set(ModelClass, sub)
+  }
+
+  return sub
+}
+
+/**
+ * Runs ensure frontend model instance listener.
+ * @param {FrontendModelEventSubscription} sub - Event subscription bucket.
+ * @param {string} id - Model id.
+ * @param {InstanceType<typeof FrontendModelBase>} instance - Listener instance.
+ * @returns {{instance: InstanceType<typeof FrontendModelBase>, updateCallbacks: Set<FrontendModelModelEventCallbackEntry>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry>}} - Instance listener bucket.
+ */
+function ensureFrontendModelInstanceListener(sub, id, instance) {
+  let listener = sub.instanceListeners.get(id)
+
+  if (!listener) {
+    listener = {instance, updateCallbacks: new Set(), destroyCallbacks: new Set()}
+    sub.instanceListeners.set(id, listener)
+  } else {
+    listener.instance = instance
+  }
+
+  return listener
+}
+
+/**
+ * Runs frontend model command url.
+ * @param {string} resourcePath - Resource path prefix.
+ * @param {string} commandName - Command path segment.
+ * @returns {string} - Frontend model API URL.
+ */
+function frontendModelCommandUrl(resourcePath, commandName) {
+  const configuredUrl = frontendModelTransportUrl()
+  const normalizedResourcePath = resourcePath.startsWith("/") ? resourcePath : `/${resourcePath}`
+
+  return `${configuredUrl}${normalizedResourcePath}/${commandName}`
+}
+
+/**
+ * Runs frontend model api url.
+ * @returns {string} - Shared frontend-model API URL.
+ */
+function frontendModelApiUrl() {
+  return `${frontendModelTransportUrl()}${SHARED_FRONTEND_MODEL_API_PATH}`
+}
+
+/**
+ * Runs frontend model transport path.
+ * @param {string} url - Request URL or path.
+ * @returns {string} - Websocket-safe request path.
+ */
+function frontendModelTransportPath(url) {
+  if (typeof url !== "string" || url.length < 1) {
+    throw new Error(`Expected frontend model transport URL/path, got: ${url}`)
+  }
+
+  if (url.startsWith("/")) {
+    return url
+  }
+
+  try {
+    const parsedUrl = new URL(url)
+
+    return `${parsedUrl.pathname}${parsedUrl.search}`
+  } catch {
+    return url
+  }
+}
+
+/**
+ * Runs frontend model request headers.
+ * @returns {Record<string, string>} - Headers for frontend-model HTTP requests.
+ */
+function frontendModelRequestHeaders() {
+  const dynamicHeaders = typeof frontendModelTransportConfig.requestHeaders === "function"
+    ? (frontendModelTransportConfig.requestHeaders() || {})
+    : (frontendModelTransportConfig.requestHeaders || {})
+
+  return {"Content-Type": "application/json", ...dynamicHeaders}
+}
+
+/**
+ * Runs perform shared frontend model api request.
+ * @param {Record<string, ?>} requestPayload - Shared request payload.
+ * @returns {Promise<Record<string, ?>>} - Decoded shared frontend-model API response.
+ */
+async function performSharedFrontendModelApiRequest(requestPayload) {
+  const serializedRequestPayload = serializeFrontendModelTransportValue(requestPayload)
+  const websocketClient = frontendModelTransportConfig.websocketClient
+  const url = frontendModelApiUrl()
+  const mergedHeaders = frontendModelRequestHeaders()
+
+  if (websocketClient) {
+    const response = await websocketClient.post(frontendModelTransportPath(url), serializedRequestPayload, {
+      headers: mergedHeaders
+    })
+    const responseJson = response.json()
+
+    return /** Narrows the runtime value to the documented type. @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(responseJson))
+  }
+
+  const response = await fetch(url, {
+    body: JSON.stringify(serializedRequestPayload),
+    credentials: "include",
+    headers: mergedHeaders,
+    method: "POST"
+  })
+
+  const responseText = await response.text()
+
+  if (!response.ok) {
+    throwFrontendModelHttpError({
+      commandLabel: "shared frontend model API",
+      response,
+      responseText
+    })
+  }
+
+  const json = responseText.length > 0 ? JSON.parse(responseText) : {}
+
+  return /** Narrows the runtime value to the documented type. @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(json))
+}
+
+/**
+ * Throws a frontend-model HTTP error with backend-provided envelope details when available.
+ * @param {{commandLabel: string, response: Response, responseText: string}} args - Error response details.
+ * @returns {never}
+ */
+function throwFrontendModelHttpError({commandLabel, response, responseText}) {
+  // Surface the backend's friendly errorMessage envelope (the
+  // `{status: "error", errorMessage: "..."}` shape every controller
+  // ships on its 4xx/5xx responses) instead of the generic status
+  // string. Fall through to the status-only message when the body is
+  // missing, non-JSON, or has no usable errorMessage field.
+  const responseContentType = response.headers.get("content-type")
+
+  if (responseContentType && responseContentType.includes("application/json") && responseText.length > 0) {
+    /**
+     * Defines errorBody.
+      @type {Record<string, ?> | null} */
+    let errorBody
+
+    try {
+      errorBody = JSON.parse(responseText)
+    } catch {
+      errorBody = null
+    }
+
+    if (errorBody && typeof errorBody.errorMessage === "string" && errorBody.errorMessage.trim().length > 0) {
+      throw new Error(errorBody.errorMessage.trim())
+    }
+  }
+
+  throw new Error(`Request failed (${response.status}) for ${commandLabel}`)
+}
+
+/**
+ * Runs flush pending shared frontend model requests.
+ * @returns {Promise<void>} - Resolves after pending shared frontend-model requests flush.
+ */
+async function flushPendingSharedFrontendModelRequests() {
+  sharedFrontendModelFlushScheduled = false
+
+  if (pendingSharedFrontendModelRequests.length < 1) {
+    resolveFrontendModelIdleWaiters()
+    return
+  }
+
+  const batchedRequests = pendingSharedFrontendModelRequests
+  pendingSharedFrontendModelRequests = []
+
+  const url = frontendModelApiUrl()
+  const requestPayload = {
+    requests: batchedRequests.map((request) => {
+      if (request.customPath) {
+        return {
+          commandType: request.commandType,
+          customPath: request.customPath,
+          model: request.modelClass.getModelName(),
+          payload: request.payload,
+          requestId: request.requestId
+        }
+      }
+
+      return {
+        commandType: request.commandType,
+        model: request.modelClass.getModelName(),
+        payload: request.payload,
+        requestId: request.requestId
+      }
+    })
+  }
+
+  await trackFrontendModelTransportRequest(async () => {
+    try {
+      void url
+      const decodedResponse = await performSharedFrontendModelApiRequest(requestPayload)
+      const responses = Array.isArray(decodedResponse.responses) ? decodedResponse.responses : []
+      const responsesById = new Map(responses.map((entry) => [entry.requestId, entry.response]))
+
+      for (const request of batchedRequests) {
+        const responsePayload = responsesById.get(request.requestId)
+
+        if (!responsePayload || typeof responsePayload !== "object") {
+          request.reject(new Error(`Missing batched response for ${request.modelClass.name}#${request.commandType}`))
+          continue
+        }
+
+        request.resolve(/**
+                         * Narrows the runtime value to the documented type.
+                          @type {Record<string, ?>} */ (responsePayload))
+      }
+    } catch (error) {
+      for (const request of batchedRequests) {
+        request.reject(error)
+      }
+    }
+  })
+}
+
+/**
+ * Runs schedule shared frontend model request flush.
+  @returns {void} */
+function scheduleSharedFrontendModelRequestFlush() {
+  if (sharedFrontendModelFlushScheduled) return
+
+  sharedFrontendModelFlushScheduled = true
+  queueMicrotask(() => {
+    void flushPendingSharedFrontendModelRequests()
+  })
+}
+
+/**
+ * Custom commands still use the shared frontend-model API. This helper only builds the backend route path the server should dispatch after validating the segments.
+ * @param {object} args - Arguments.
+ * @param {string} args.commandName - Command path segment.
+ * @param {string} args.modelName - Frontend model class name.
+ * @param {string | number | null | undefined} [args.memberId] - Optional member id.
+ * @param {string} args.resourcePath - Resource path prefix.
+ * @returns {string} - Custom backend route path.
+ */
+function frontendModelCustomCommandPath({commandName, memberId, modelName, resourcePath}) {
+  const validatedResourcePath = validateFrontendModelResourcePath({modelName, resourcePath})
+  const validatedCommandName = validateFrontendModelResourceCommandName({commandName, commandType: commandName, modelName})
+
+  if (memberId === undefined || memberId === null || memberId === "") {
+    return `${validatedResourcePath}/${validatedCommandName}`
+  }
+
+  return `${validatedResourcePath}/${encodeURIComponent(String(memberId))}/${validatedCommandName}`
+}
+
+/**
+ * Runs assert find by conditions shape.
+ * @param {?} conditions - findBy conditions.
+ * @returns {void}
+ */
+function assertFindByConditionsShape(conditions) {
+  if (!conditions || typeof conditions !== "object" || Array.isArray(conditions)) {
+    throw new Error(`findBy expects conditions to be a plain object, got: ${conditions}`)
+  }
+
+  const conditionsPrototype = Object.getPrototypeOf(conditions)
+
+  if (conditionsPrototype !== Object.prototype && conditionsPrototype !== null) {
+    throw new Error(`findBy expects conditions to be a plain object, got: ${conditions}`)
+  }
+
+  const symbolKeys = Object.getOwnPropertySymbols(conditions)
+
+  if (symbolKeys.length > 0) {
+    throw new Error(`findBy does not support symbol condition keys (keys: ${symbolKeys.map((key) => key.toString()).join(", ")})`)
+  }
+}
+
+/**
+ * Runs assert defined find by condition value.
+ * @param {?} value - Condition value to validate.
+ * @param {string} keyPath - Key path for error output.
+ * @returns {void}
+ */
+function assertDefinedFindByConditionValue(value, keyPath) {
+  if (value === undefined) {
+    throw new Error(`findBy does not support undefined condition values (key: ${keyPath})`)
+  }
+
+  if (typeof value === "function") {
+    throw new Error(`findBy does not support function condition values (key: ${keyPath})`)
+  }
+
+  if (typeof value === "symbol") {
+    throw new Error(`findBy does not support symbol condition values (key: ${keyPath})`)
+  }
+
+  if (typeof value === "bigint") {
+    throw new Error(`findBy does not support bigint condition values (key: ${keyPath})`)
+  }
+
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new Error(`findBy does not support non-finite number condition values (key: ${keyPath})`)
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => {
+      assertDefinedFindByConditionValue(entry, `${keyPath}[${index}]`)
+    })
+    return
+  }
+
+  if (value && typeof value === "object") {
+    if (value instanceof Date) {
+      return
+    }
+
+    const objectValue = /**
+                         * Narrows the runtime value to the documented type.
+                          @type {Record<string, ?>} */ (value)
+    const prototype = Object.getPrototypeOf(objectValue)
+
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Error(`findBy does not support non-plain object condition values (key: ${keyPath})`)
+    }
+
+    const symbolKeys = Object.getOwnPropertySymbols(objectValue)
+
+    if (symbolKeys.length > 0) {
+      throw new Error(`findBy does not support symbol condition keys (key: ${keyPath})`)
+    }
+
+    const valueObject = /**
+                         * Narrows the runtime value to the documented type.
+                          @type {Record<string, ?>} */ (value)
+
+    Object.keys(valueObject).forEach((nestedKey) => {
+      assertDefinedFindByConditionValue(valueObject[nestedKey], `${keyPath}.${nestedKey}`)
+    })
+  }
+}
+
+/** Base class for generated frontend model classes. */
+export default class FrontendModelBase {
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {string | undefined} */
+  static modelName
+
+  /**
+   * Autoload.
+   * @type {boolean} - Global auto-batch-preload toggle. Apps can opt out via FrontendModelBase.setAutoload(false).
+   */
+  static _autoload = true
+
+  /**
+   * Runs get autoload.
+   * @returns {boolean} Whether auto-batch-preload of relationships on lazy access is enabled globally.
+   */
+  static getAutoload() { return FrontendModelBase._autoload }
+
+  /**
+   * Runs set autoload.
+   * @param {boolean} newValue - Whether auto-batch-preload of relationships is enabled.
+   * @returns {void}
+   */
+  static setAutoload(newValue) { FrontendModelBase._autoload = newValue }
+
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {Record<string, ?>} */
+  _attributes
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {Record<string, FrontendModelHasManyRelationship<typeof FrontendModelBase, typeof FrontendModelBase> | FrontendModelSingularRelationship<typeof FrontendModelBase, typeof FrontendModelBase>>} */
+  _relationships
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {Record<string, FrontendModelAttachmentHandle>} */
+  _attachments
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {Set<string> | null} */
+  _selectedAttributes
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {boolean} */
+  _isNewRecord
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {boolean} */
+  _markedForDestruction
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {Record<string, ?>} */
+  _persistedAttributes
+  /**
+   * Narrows the runtime value to the documented type.
+   * @type {Array<FrontendModelBase> | undefined} - Shared reference to sibling records loaded in the same batch. Used by auto-batch-preload.
+   */
+  _loadCohort
+
+  /**
+   * Runs constructor.
+   * @param {Record<string, ?>} [attributes] - Initial attributes.
+   */
+  constructor(attributes = {}) {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+
+    ModelClass.ensureGeneratedAttachmentMethods()
+    this._attributes = {}
+    this._relationships = {}
+    this._attachments = {}
+    this._selectedAttributes = null
+    this._isNewRecord = true
+    this._markedForDestruction = false
+    this._persistedAttributes = {}
+    this.assignAttributes(attributes)
+  }
+
+  /**
+   * Runs ensure generated attachment methods.
+   * @this {typeof FrontendModelBase}
+   * @returns {void} - Ensures attachment helper methods exist on the prototype.
+   */
+  static ensureGeneratedAttachmentMethods() {
+    if (this._generatedAttachmentMethods) return
+
+    const attachments = this.attachmentDefinitions()
+    const prototype = /**
+                       * Narrows the runtime value to the documented type.
+                        @type {Record<string, ?>} */ (this.prototype)
+
+    for (const attachmentName of Object.keys(attachments)) {
+      if (!(attachmentName in prototype)) {
+        prototype[attachmentName] = function() {
+          return this.getAttachmentByName(attachmentName)
+        }
+      }
+    }
+
+    this._generatedAttachmentMethods = true
+  }
+
+  /**
+   * Runs resource config.
+   * @returns {FrontendModelResourceConfig} - Resource configuration.
+   */
+  static resourceConfig() {
+    throw new Error("resourceConfig() must be implemented by subclasses")
+    // eslint-disable-next-line no-unreachable
+    return {}
+  }
+
+  /**
+   * Runs relationship model classes.
+   * @this {typeof FrontendModelBase}
+   * @returns {Record<string, typeof FrontendModelBase | string>} - Relationship model classes (or class name strings) keyed by relationship name.
+   */
+  static relationshipModelClasses() {
+    return {}
+  }
+
+  /**
+   * Register a frontend model class so it can be resolved by name in relationship lookups.
+   * @param {typeof FrontendModelBase} modelClass - Model class to register.
+   * @returns {void}
+   */
+  static registerModel(modelClass) {
+    registerFrontendModel(modelClass)
+  }
+
+  /**
+   * Runs define scope.
+   * @param {(...args: Array<?>) => ?} callback - Scope callback.
+   * @returns {((...args: Array<?>) => import("./query.js").default<typeof FrontendModelBase>) & {scope: (...args: Array<?>) => import("../utils/model-scope.js").ModelScopeDescriptor}} - Scope helper.
+   */
+  static defineScope(callback) {
+    return defineModelScope({
+      callback,
+      modelClass: this,
+      startQuery: () => this.query()
+    })
+  }
+
+  /**
+   * Resolve a relationship model class value that may be a class reference or a string name.
+   * @param {typeof FrontendModelBase | string | null | undefined} value - Class or class name.
+   * @returns {typeof FrontendModelBase | null} - Resolved model class.
+   */
+  static resolveModelClass(value) {
+    return resolveFrontendModelClass(value)
+  }
+
+  /**
+   * Runs relationship definitions.
+   * @this {typeof FrontendModelBase}
+   * @returns {Record<string, {type: "belongsTo" | "hasOne" | "hasMany", autoload?: boolean}>} - Relationship definitions keyed by relationship name.
+   */
+  static relationshipDefinitions() {
+    return {}
+  }
+
+  /**
+   * Runs attachment definitions.
+   * @this {typeof FrontendModelBase}
+   * @returns {Record<string, FrontendModelAttachmentDefinition>} - Attachment definitions keyed by attachment name.
+   */
+  static attachmentDefinitions() {
+    return this.resourceConfig().attachments || {}
+  }
+
+  /**
+   * Runs attachment definition.
+   * @this {typeof FrontendModelBase}
+   * @param {string} attachmentName - Attachment name.
+   * @returns {FrontendModelAttachmentDefinition | null} - Attachment definition.
+   */
+  static attachmentDefinition(attachmentName) {
+    return this.attachmentDefinitions()[attachmentName] || null
+  }
+
+  /**
+   * Runs relationship definition.
+   * @this {typeof FrontendModelBase}
+   * @param {string} relationshipName - Relationship name.
+   * @returns {{type: "belongsTo" | "hasOne" | "hasMany", autoload?: boolean} | null} - Relationship definition.
+   */
+  static relationshipDefinition(relationshipName) {
+    const definitions = this.relationshipDefinitions()
+
+    return definitions[relationshipName] || null
+  }
+
+  /**
+   * Runs relationship model class.
+   * @this {typeof FrontendModelBase}
+   * @param {string} relationshipName - Relationship name.
+   * @returns {typeof FrontendModelBase | null} - Target relationship model class.
+   */
+  static relationshipModelClass(relationshipName) {
+    const relationshipModelClasses = this.relationshipModelClasses()
+    const value = relationshipModelClasses[relationshipName]
+
+    return FrontendModelBase.resolveModelClass(value)
+  }
+
+  /**
+   * Runs attributes.
+   * @returns {Record<string, ?>} - Attributes hash.
+   */
+  attributes() {
+    return this._attributes
+  }
+
+  /**
+   * Runs is new record.
+   * @returns {boolean} - Whether this model has not yet been persisted.
+   */
+  isNewRecord() {
+    return this._isNewRecord
+  }
+
+  /**
+   * Runs is persisted.
+   * @returns {boolean} - Whether this model has been persisted.
+   */
+  isPersisted() {
+    return !this.isNewRecord()
+  }
+
+  /**
+   * Runs set is new record.
+   * @param {boolean} newIsNewRecord - New persisted-state flag.
+   * @returns {void}
+   */
+  setIsNewRecord(newIsNewRecord) {
+    this._isNewRecord = newIsNewRecord
+  }
+
+  /**
+   * Marks this record for destruction when its parent is next saved through
+   * nested-attribute support. The record is not removed from the parent's
+   * relationship collection until the server confirms the delete.
+   * @returns {void} - No return value.
+   */
+  markForDestruction() {
+    this._markedForDestruction = true
+  }
+
+  /**
+   * Runs marked for destruction.
+   * @returns {boolean} - Whether this record is queued for nested destruction on next parent save.
+   */
+  markedForDestruction() {
+    return this._markedForDestruction
+  }
+
+  /**
+   * Runs changes.
+   * @returns {Record<string, Array<?>>} - Changed attributes as `[oldValue, newValue]`.
+   */
+  changes() {
+    /**
+     * Changed attributes.
+      @type {Record<string, Array<?>>} */
+    const changedAttributes = {}
+    const attributeNames = new Set([
+      ...Object.keys(this._persistedAttributes),
+      ...Object.keys(this._attributes)
+    ])
+
+    for (const attributeName of attributeNames) {
+      const previousValue = this._persistedAttributes[attributeName]
+      const currentValue = this._attributes[attributeName]
+
+      if (JSON.stringify(serializeFrontendModelTransportValue(previousValue)) !== JSON.stringify(serializeFrontendModelTransportValue(currentValue))) {
+        changedAttributes[attributeName] = [previousValue, currentValue]
+      }
+    }
+
+    return changedAttributes
+  }
+
+  /**
+   * Runs is changed.
+   * @returns {boolean} - Whether any tracked attribute has changed.
+   */
+  isChanged() {
+    return Object.keys(this.changes()).length > 0
+  }
+
+  /**
+   * Runs get relationship by name.
+   * @param {string} relationshipName - Relationship name.
+   * @returns {FrontendModelHasManyRelationship<typeof FrontendModelBase, typeof FrontendModelBase> | FrontendModelSingularRelationship<typeof FrontendModelBase, typeof FrontendModelBase>} - Relationship state object.
+   */
+  getRelationshipByName(relationshipName) {
+    if (!this._relationships[relationshipName]) {
+      const ModelClass = /**
+                          * Narrows the runtime value to the documented type.
+                           @type {typeof FrontendModelBase} */ (this.constructor)
+      const relationshipDefinition = ModelClass.relationshipDefinition(relationshipName)
+      const targetModelClass = ModelClass.relationshipModelClass(relationshipName)
+
+      if (relationshipDefinition && relationshipTypeIsCollection(relationshipDefinition.type)) {
+        this._relationships[relationshipName] = new FrontendModelHasManyRelationship(this, relationshipName, targetModelClass)
+      } else {
+        this._relationships[relationshipName] = new FrontendModelSingularRelationship(this, relationshipName, targetModelClass)
+      }
+    }
+
+    return this._relationships[relationshipName]
+  }
+
+  /**
+   * Runs get attachment by name.
+   * @param {string} attachmentName - Attachment name.
+   * @returns {FrontendModelAttachmentHandle} - Attachment helper.
+   */
+  getAttachmentByName(attachmentName) {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const attachmentDefinition = ModelClass.attachmentDefinition(attachmentName)
+
+    if (!attachmentDefinition) {
+      throw new Error(`Unknown attachment: ${ModelClass.name}#${attachmentName}`)
+    }
+
+    if (!this._attachments[attachmentName]) {
+      this._attachments[attachmentName] = new FrontendModelAttachmentHandle({
+        attachmentName,
+        model: this
+      })
+    }
+
+    return this._attachments[attachmentName]
+  }
+
+  /**
+   * Runs load relationship.
+   * @param {string} relationshipName - Relationship name.
+   * @returns {Promise<?>} - Loaded relationship value.
+   */
+  async loadRelationship(relationshipName) {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const id = this.primaryKeyValue()
+    const reloadedModel = await ModelClass
+      .preload([relationshipName])
+      .find(id)
+    const loadedValue = reloadedModel.getRelationshipByName(relationshipName).loaded()
+
+    this.getRelationshipByName(relationshipName).setLoaded(loadedValue)
+
+    return loadedValue
+  }
+
+  /**
+   * Preloads relationship(s) onto this already-loaded record. Accepts either a
+   * query built via `Model.preload(...).select(...)` or a raw preload spec
+   * (string / array / nested object). Relationships already preloaded with the
+   * required columns present are left untouched unless `force` is set. Carries
+   * the query's preload graph, select, selectsExtra, withCount, abilities, and
+   * queryData when re-fetching.
+   * @param {import("./query.js").default<typeof FrontendModelBase> | import("../database/query/index.js").NestedPreloadRecord | string | Array<string | import("../database/query/index.js").NestedPreloadRecord>} queryOrSpec - Preload source.
+   * @param {{force?: boolean}} [options] - Options.
+   * @returns {Promise<void>} - Resolves when preloading completes.
+   */
+  async preload(queryOrSpec, options = {}) {
+    await FrontendModelPreloader.preload([this], queryOrSpec, options)
+  }
+
+  /**
+   * Runs relationship or load.
+   * @param {string} relationshipName - Relationship name.
+   * @returns {Promise<?>} - Loaded relationship value.
+   */
+  async relationshipOrLoad(relationshipName) {
+    const relationship = this.getRelationshipByName(relationshipName)
+
+    if (relationship.getPreloaded()) {
+      return relationship.loaded()
+    }
+
+    const batched = await this._tryCohortPreload(relationshipName)
+
+    if (batched) return relationship.loaded()
+
+    return await this.loadRelationship(relationshipName)
+  }
+
+  /**
+   * Attempts to batch-load `relationshipName` across cohort siblings via a
+   * single `preload([name]).where({pk: [ids]}).toArray()` request, then copies
+   * the preloaded relationship state onto each sibling. Returns true when a
+   * batch ran, false when autoload is off, there is no cohort, or no batch
+   * candidates remain. Siblings whose relationship state is already set
+   * (preloaded or locally manipulated via `build` / `setRelationship`) are
+   * skipped so their cached/edited value is preserved.
+   * @param {string} relationshipName - Relationship name.
+   * @returns {Promise<boolean>} - Whether a cohort batch preload ran.
+   */
+  async _tryCohortPreload(relationshipName) {
+    if (!FrontendModelBase.getAutoload()) return false
+
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const cohort = this._loadCohort
+
+    if (!cohort || cohort.length <= 1) return false
+
+    const definition = ModelClass.relationshipDefinition(relationshipName)
+
+    if (!definition) return false
+    if (definition.autoload === false) return false
+
+    /**
+     * Batch.
+      @type {Array<FrontendModelBase>} */
+    const batch = []
+
+    // Exact same class, persisted, no existing in-memory relationship state.
+    // `setLoaded` sets `_preloaded = true` on every mutation path (preload,
+    // setRelationship, build, addToLoaded), so `getPreloaded()` alone is a
+    // reliable "already touched" signal on the frontend.
+    for (const sibling of cohort) {
+      if (sibling.constructor !== ModelClass) continue
+      if (sibling.isNewRecord()) continue
+
+      const siblingRelationship = sibling.getRelationshipByName(relationshipName)
+
+      if (siblingRelationship.getPreloaded()) continue
+
+      batch.push(sibling)
+    }
+
+    if (batch.length === 0) return false
+
+    const primaryKey = ModelClass.primaryKey()
+    const batchIds = batch.map((sibling) => sibling.primaryKeyValue())
+    const reloadedBatch = await ModelClass
+      .preload([relationshipName])
+      .where({[primaryKey]: batchIds})
+      .toArray()
+
+    /**
+     * Reloaded by id.
+      @type {Map<string, FrontendModelBase>} */
+    const reloadedById = new Map()
+
+    for (const reloaded of reloadedBatch) {
+      reloadedById.set(String(reloaded.primaryKeyValue()), reloaded)
+    }
+
+    for (const sibling of batch) {
+      const key = String(sibling.primaryKeyValue())
+      const reloaded = reloadedById.get(key)
+
+      if (!reloaded) continue
+
+      const reloadedValue = reloaded.getRelationshipByName(relationshipName).loaded()
+
+      sibling.getRelationshipByName(relationshipName).setLoaded(reloadedValue)
+    }
+
+    // If the caller itself was not populated (record deleted/filtered between
+    // the list fetch and this preload request), fall back to per-record load
+    // so the caller gets a real not-found error instead of a misleading
+    // "hasn't been preloaded" throw from loaded().
+    if (!this.getRelationshipByName(relationshipName).getPreloaded()) return false
+
+    return true
+  }
+
+  /**
+   * Runs set relationship.
+   * @param {string} relationshipName - Relationship name.
+   * @param {?} relationshipValue - Relationship value.
+   * @returns {?} - Assigned relationship value.
+   */
+  setRelationship(relationshipName, relationshipValue) {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const relationshipDefinition = ModelClass.relationshipDefinition(relationshipName)
+
+    if (!relationshipDefinition) {
+      throw new Error(`Unknown relationship: ${ModelClass.name}#${relationshipName}`)
+    }
+
+    if (relationshipTypeIsCollection(relationshipDefinition.type)) {
+      throw new Error(`Cannot set has-many relationship with setRelationship(): ${ModelClass.name}#${relationshipName}`)
+    }
+
+    this.getRelationshipByName(relationshipName).setLoaded(relationshipValue)
+
+    return relationshipValue
+  }
+
+  /**
+   * Runs assign attributes.
+   * @param {Record<string, ?>} attributes - Attributes to assign.
+   * @returns {void} - No return value.
+   */
+  assignAttributes(attributes) {
+    for (const key in attributes) {
+      this.setAttribute(key, attributes[key])
+    }
+  }
+
+  /**
+   * Runs clear relationship cache.
+   * @returns {void} - Clears cached relationship state.
+   */
+  clearRelationshipCache() {
+    this._relationships = {}
+  }
+
+  /**
+   * Runs primary key.
+   * @this {typeof FrontendModelBase}
+   * @returns {string} - Primary key name.
+   */
+  static primaryKey() {
+    return this.resourceConfig().primaryKey || "id"
+  }
+
+  /**
+   * Runs primary key value.
+   * @returns {number | string} - Primary key value.
+   */
+  primaryKeyValue() {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const value = this.readAttribute(ModelClass.primaryKey())
+
+    if (value === undefined || value === null) {
+      throw new Error(`Missing primary key '${ModelClass.primaryKey()}' on ${ModelClass.name}`)
+    }
+
+    return value
+  }
+
+  /**
+   * Runs read attribute.
+   * @param {string} attributeName - Attribute name.
+   * @returns {?} - Attribute value.
+   */
+  readAttribute(attributeName) {
+    if (this._selectedAttributes && !this._selectedAttributes.has(attributeName)) {
+      throw new AttributeNotSelectedError(this.constructor.name, attributeName)
+    }
+
+    return this._attributes[attributeName]
+  }
+
+  /**
+   * Whether an attribute value is currently loaded on this record. Used by the
+   * preloader to decide whether a relationship can be skipped because the
+   * requested columns are already present.
+   * @param {string} attributeName - Attribute name.
+   * @returns {boolean} - Whether the attribute is loaded.
+   */
+  hasLoadedAttribute(attributeName) {
+    if (!this._selectedAttributes) return true
+
+    return this._selectedAttributes.has(attributeName)
+  }
+
+  /**
+   * Read an association count attached by `.withCount(...)`. Counts
+   * live on a dedicated map separate from the record's attributes so
+   * a virtual count like `tasksCount` can't silently shadow a real
+   * column of the same name. Returns the attached value, or 0 when
+   * `.withCount(...)` wasn't requested for this attribute.
+   * @param {string} attributeName - Attribute name, e.g. `"tasksCount"` or a custom name from `.withCount({customName: {...}})`.
+   * @returns {number}
+   */
+  readCount(attributeName) {
+    return readPayloadAssociationCount(/**
+                                        * Narrows the runtime value to the documented type.
+                                         @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
+                                                                                                                      * Narrows the runtime value to the documented type.
+                                                                                                                       @type {?} */ (this)), attributeName)
+  }
+
+  /**
+   * Internal setter called by `instantiateFromResponse` when hydrating
+   * association counts that rode along with the record payload.
+   * @param {string} attributeName - Attribute name.
+   * @param {number} value - Count value.
+   * @returns {void}
+   */
+  _setAssociationCount(attributeName, value) {
+    setPayloadAssociationCount(/**
+                                * Narrows the runtime value to the documented type.
+                                 @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
+                                                                                                              * Narrows the runtime value to the documented type.
+                                                                                                               @type {?} */ (this)), attributeName, value)
+  }
+
+  /**
+   * Read a per-record ability result attached by `.abilities(...)`. The
+   * backend evaluates each requested action against the current
+   * ability for this record instance and ships the result alongside
+   * the record's attributes. Returns `false` when the action wasn't
+   * requested (or the ability denied it), so UI code can safely branch
+   * on `record.can("update")` without first checking whether the
+   * ability was loaded.
+   * @param {string} action - Ability action name, e.g. `"update"`.
+   * @returns {boolean}
+   */
+  can(action) {
+    return readPayloadComputedAbility(/**
+                                       * Narrows the runtime value to the documented type.
+                                        @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
+                                                                                                                     * Narrows the runtime value to the documented type.
+                                                                                                                      @type {?} */ (this)), action)
+  }
+
+  /**
+   * Internal setter called by `instantiateFromResponse` when hydrating
+   * per-record ability results that rode along with the record
+   * payload.
+   * @param {string} action - Ability action name.
+   * @param {boolean} value - Whether the current ability permits the action on this record.
+   * @returns {void}
+   */
+  _setComputedAbility(action, value) {
+    setPayloadComputedAbility(/**
+                               * Narrows the runtime value to the documented type.
+                                @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
+                                                                                                             * Narrows the runtime value to the documented type.
+                                                                                                              @type {?} */ (this)), action, value)
+  }
+
+  /**
+   * Read a consumer-defined value attached by `.queryData(...)`. Stored
+   * on a dedicated map rather than `_attributes`, so a virtual alias
+   * like `tasksCount` cannot silently shadow a real column of the same
+   * name. Returns `null` when no registered fn produced that alias for
+   * this record (e.g. no child rows matched the aggregate).
+   * @param {string} name - queryData alias name.
+   * @returns {?}
+   */
+  queryData(name) {
+    return readPayloadQueryData(/**
+                                 * Narrows the runtime value to the documented type.
+                                  @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
+                                                                                                               * Narrows the runtime value to the documented type.
+                                                                                                                @type {?} */ (this)), name)
+  }
+
+  /**
+   * Internal setter used by `instantiateFromResponse` when hydrating
+   * queryData values that rode along with the record payload.
+   * @param {string} name - queryData alias name.
+   * @param {?} value - Attached value.
+   * @returns {void}
+   */
+  _setQueryData(name, value) {
+    setPayloadQueryData(/**
+                         * Narrows the runtime value to the documented type.
+                          @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/**
+                                                                                                       * Narrows the runtime value to the documented type.
+                                                                                                        @type {?} */ (this)), name, value)
+  }
+
+  /**
+   * Runs set attribute.
+   * @param {string} attributeName - Attribute name.
+   * @param {?} newValue - New value.
+   * @returns {?} - Assigned value.
+   */
+  setAttribute(attributeName, newValue) {
+    const previousValue = this._attributes[attributeName]
+
+    this._attributes[attributeName] = newValue
+
+    if (this._selectedAttributes) {
+      this._selectedAttributes.add(attributeName)
+    }
+
+    // Only invalidate relationship cache entries whose foreign key matches the changed attribute.
+    // Blanket-clearing all relationships on any attribute change destroys nested-save state
+    // and preloaded children the caller never asked to invalidate.
+    if (!Object.is(previousValue, newValue)) {
+      this._invalidateRelationshipsForAttribute(attributeName)
+    }
+
+    return newValue
+  }
+
+  /**
+   * Invalidates any cached belongsTo relationship whose foreign key matches the
+   * changed attribute. HasMany / hasOne relationships are left untouched because
+   * their foreign key lives on the child, not on this model, and blanket-clearing
+   * them would destroy nested-save state and preloaded children the caller never
+   * asked to invalidate.
+   *
+   * Foreign keys are inferred when not declared: for belongsTo `projectId` is
+   * inferred from relationship name `project`. Explicit `foreignKey` on the
+   * relationship definition takes precedence.
+   * @param {string} attributeName - Attribute name that changed.
+   * @returns {void}
+   */
+  _invalidateRelationshipsForAttribute(attributeName) {
+    if (!this._relationships || Object.keys(this._relationships).length === 0) return
+
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const definitions = typeof ModelClass.relationshipDefinitions === "function" ? ModelClass.relationshipDefinitions() : {}
+
+    for (const relationshipName of Object.keys(this._relationships)) {
+      const definition = /**
+                          * Narrows the runtime value to the documented type.
+                           @type {?} */ (definitions[relationshipName])
+
+      if (!definition || definition.type !== "belongsTo") continue
+
+      const foreignKey = definition.foreignKey || `${relationshipName}Id`
+
+      if (foreignKey === attributeName) {
+        delete this._relationships[relationshipName]
+      }
+    }
+  }
+
+  /**
+   * Runs resource path.
+   * @this {typeof FrontendModelBase}
+   * @returns {string} - Derived resource path.
+   */
+  static resourcePath() {
+    return validateFrontendModelResourcePath({
+      modelName: this.getModelName(),
+      resourcePath: defaultFrontendModelResourcePath(this)
+    })
+  }
+
+  /**
+   * Runs command name.
+   * @this {typeof FrontendModelBase}
+   * @param {FrontendModelCommandType} commandType - Command type.
+   * @returns {string} - Resolved command name.
+   */
+  static commandName(commandType) {
+    const resourceConfig = this.resourceConfig()
+    const builtInCollectionCommands = resourceConfig.builtInCollectionCommands || []
+    const builtInMemberCommands = resourceConfig.builtInMemberCommands || []
+    const commands = resourceConfig.commands || []
+    const isExposed = builtInCollectionCommands.includes(commandType) || builtInMemberCommands.includes(commandType) || commands.includes(commandType)
+    const commandName = isExposed ? inflection.dasherize(inflection.underscore(commandType)) : commandType
+
+    return validateFrontendModelResourceCommandName({
+      commandName,
+      commandType,
+      modelName: this.getModelName()
+    })
+  }
+
+  /**
+   * Runs normalize custom command payload arguments.
+   * @this {typeof FrontendModelBase}
+   * @param {Array<?>} args - Command arguments.
+   * @returns {Record<string, ?>} - Command payload.
+   */
+  static normalizeCustomCommandPayloadArguments(args) {
+    if (args.length === 0) return {}
+    if (args.length === 1) {
+      const payload = args[0]
+      if (payload === undefined) {
+        return {}
+      }
+
+      if (typeof payload !== "object" || payload === null) {
+        return {arg1: payload}
+      }
+
+      return /** Narrows the runtime value to the documented type. @type {Record<string, ?>} */ (payload)
+    }
+
+    /**
+     * Payload.
+      @type {Record<string, number | string | Array<?>>} */
+    const payload = {}
+
+    for (let index = 0; index < args.length; index += 1) {
+      payload[`arg${index + 1}`] = args[index]
+    }
+
+    return payload
+  }
+
+  /**
+   * Returns the model name, preferring an explicit `static modelName` declaration
+   * over the JavaScript class `.name` property. This allows minified builds to
+   * preserve correct model names without relying on `keep_classnames`.
+   * @this {typeof FrontendModelBase}
+   * @returns {string} - The model name.
+   */
+  static getModelName() {
+    const resourceConfig = typeof this.resourceConfig === "function" ? this.resourceConfig() : null
+    const modelName = resourceConfig?.modelName
+
+    return (typeof modelName === "string" && modelName.length > 0) ? modelName : this.name
+  }
+
+  /**
+   * Runs configure transport.
+   * @param {FrontendModelTransportConfig} config - Frontend model transport configuration.
+   * @returns {void} - No return value.
+   */
+  static configureTransport(config) {
+    if (!config || typeof config !== "object") {
+      return
+    }
+
+    if (Object.prototype.hasOwnProperty.call(config, "url")) {
+      frontendModelTransportConfig.url = config.url
+    }
+
+    if (Object.prototype.hasOwnProperty.call(config, "shared")) {
+      frontendModelTransportConfig.shared = config.shared
+    }
+
+    if (Object.prototype.hasOwnProperty.call(config, "websocketClient")) {
+      frontendModelTransportConfig.websocketClient = config.websocketClient
+    }
+
+    if (Object.prototype.hasOwnProperty.call(config, "websocketUrl")) {
+      frontendModelTransportConfig.websocketUrl = config.websocketUrl
+      // Reset cached internal client so the new URL takes effect on next subscribe
+      internalWebsocketClient = null
+    }
+
+    if (Object.prototype.hasOwnProperty.call(config, "requestHeaders")) {
+      frontendModelTransportConfig.requestHeaders = config.requestHeaders
+    }
+
+    if (Object.prototype.hasOwnProperty.call(config, "sessionStore")) {
+      frontendModelTransportConfig.sessionStore = config.sessionStore
+      // Reset cached internal client so the new sessionStore is picked up.
+      internalWebsocketClient = null
+    }
+  }
+
+  /**
+   * Connect the internal WebSocket and enable auto-reconnect.
+   * @returns {Promise<void>} - Resolves when connected.
+   */
+  static async connectWebsocket() {
+    const client = resolveInternalWebsocketClient()
+
+    if (!client) {
+      throw new Error("connectWebsocket requires configureTransport({websocketUrl})")
+    }
+
+    await client.connect()
+  }
+
+  /**
+   * Disconnect the internal WebSocket and disable auto-reconnect.
+   * @returns {Promise<void>} - Resolves when closed.
+   */
+  static async disconnectWebsocket() {
+    if (!internalWebsocketClient) return
+
+    await internalWebsocketClient.disconnectAndStopReconnect()
+  }
+
+  /**
+   * Waits until queued and active frontend-model transport requests finish.
+   * @param {FrontendModelIdleWaitArgs} [args] - Wait options.
+   * @returns {Promise<void>} - Resolves when transport is idle.
+   */
+  static async waitForIdle(args = {}) {
+    const {quietMs = 0, timeout: timeoutMs = 5000, ...restArgs} = args
+    const restArgKeys = Object.keys(restArgs)
+
+    if (restArgKeys.length > 0) {
+      throw new Error(`Unknown waitForIdle args: ${restArgKeys.join(", ")}`)
+    }
+
+    if (!Number.isFinite(quietMs) || quietMs < 0) {
+      throw new Error(`Expected waitForIdle quietMs to be a non-negative number, got: ${quietMs}`)
+    }
+
+    await timeout(
+      {timeout: timeoutMs, errorMessage: "Timed out waiting for frontend model transport to become idle"},
+      async () => await waitForFrontendModelTransportIdle(quietMs)
+    )
+  }
+
+  /**
+   * Returns the current WebSocket connection state.
+   * @returns {{disconnectedSince: number | null, hasClient: boolean, isOpen: boolean, listenerCount: number}} - Snapshot of the managed websocket connection state.
+   */
+  static websocketState() {
+    if (!internalWebsocketClient) {
+      return {disconnectedSince: null, hasClient: false, isOpen: false, listenerCount: 0}
+    }
+
+    return {
+      ...internalWebsocketClient.state(),
+      hasClient: true
+    }
+  }
+
+  /**
+   * Close the raw WebSocket without disabling auto-reconnect. Used by tests to
+   * simulate an unexpected network drop and verify reconnection behavior.
+   * @returns {Promise<void>} - Resolves when the socket has closed.
+   */
+  static async dropWebsocket() {
+    if (!internalWebsocketClient) return
+
+    await internalWebsocketClient.dropConnection()
+  }
+
+  /**
+   * Sets global metadata on the WebSocket connection. Sent to the server immediately
+   * over WebSocket and exposed to WebSocket-borne requests as request metadata.
+   * @param {string} key - Metadata key.
+   * @param {?} value - Metadata value (null to clear).
+   * @returns {void}
+   */
+  static setWebsocketMetadata(key, value) {
+    const client = /**
+                    * Narrows the runtime value to the documented type.
+                     @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
+
+    if (!client || typeof client.setMetadata !== "function") return
+
+    client.setMetadata(key, value)
+  }
+
+  /**
+   * Opens a managed connection that auto-opens, auto-closes, and
+   * auto-reconnects based on `shouldConnect()` and `params()`.
+   * Call `handle.sync()` whenever the inputs that drive those
+   * functions change (e.g. current-user sign-in/out). The handle
+   * retries when the WS client isn't ready and reopens on close.
+   * @param {string} connectionType - Connection class name registered on the server.
+   * @param {{shouldConnect: () => boolean, params: () => Record<string, ?>, onMessage?: (body: ?) => void}} options - Connection lifecycle and payload callbacks.
+   * @returns {{sync: () => void, close: () => void}} - Handle used to resync or close the managed connection.
+   */
+  static openManagedConnection(connectionType, options) {
+    /**
+     * Connection.
+      @type {?} */
+    let connection = null
+    let closed = false
+    /**
+     * Retry timer.
+      @type {ReturnType<typeof setTimeout> | null} */
+    let retryTimer = null
+    let lastParamsJson = ""
+
+    const sync = () => {
+      if (closed) return
+
+      if (!options.shouldConnect()) {
+        if (connection && !connection.isClosed()) connection.close()
+        connection = null
+        lastParamsJson = ""
+        return
+      }
+
+      const nextParams = options.params()
+      const nextParamsJson = JSON.stringify(nextParams)
+
+      // Already connected with same params — nothing to do.
+      if (connection && !connection.isClosed() && nextParamsJson === lastParamsJson) return
+
+      // Connected but params changed — send update message.
+      // Guard with try/catch: the connection handle stays live during
+      // reconnect but the underlying socket may be closed.
+      if (connection && !connection.isClosed()) {
+        try {
+          connection.sendMessage(nextParams)
+          lastParamsJson = nextParamsJson
+          return
+        } catch {
+          connection = null
+          lastParamsJson = ""
+        }
+      }
+
+      // WS client not ready — retry. Check the actual client (which
+      // may be an injected websocketClient) instead of websocketState()
+      // which only reflects the internal client.
+      const client = /**
+                      * Narrows the runtime value to the documented type.
+                       @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
+
+      if (!client || !client.isOpen()) {
+        if (retryTimer === null) {
+          retryTimer = globalThis.setTimeout(() => {
+            retryTimer = null
+            sync()
+          }, 250)
+        }
+        return
+      }
+
+      lastParamsJson = nextParamsJson
+      connection = FrontendModelBase.openWebsocketConnection(connectionType, {
+        params: nextParams,
+        onMessage: options.onMessage,
+        onClose: () => {
+          if (connection?.isClosed()) {
+            connection = null
+            lastParamsJson = ""
+            sync()
+          }
+        }
+      })
+    }
+
+    const close = () => {
+      closed = true
+      if (retryTimer !== null) globalThis.clearTimeout(retryTimer)
+      if (connection && !connection.isClosed()) connection.close()
+      connection = null
+    }
+
+    sync()
+
+    return {sync, close}
+  }
+
+  /**
+   * Opens a 1:1 `WebsocketConnection` of the given type. Thin
+   * convenience wrapper around the internal WS client's
+   * `openConnection`. Apps use this for per-session state/messaging
+   * that doesn't fit the pub/sub Channel model (locale, presence).
+   * @param {string} connectionType - Name the server registered the class under.
+   * @param {{params?: Record<string, ?>, onConnect?: () => void, onMessage?: (body: ?) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Connection options and event handlers.
+   * @returns {?} - VelociousWebsocketClientConnection handle (typed loosely to avoid a cross-module import cycle).
+   */
+  static openWebsocketConnection(connectionType, options) {
+    const client = /**
+                    * Narrows the runtime value to the documented type.
+                     @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
+
+    if (!client || typeof client.openConnection !== "function") {
+      throw new Error("openWebsocketConnection requires configureTransport({websocketUrl})")
+    }
+
+    return client.openConnection(connectionType, options || {})
+  }
+
+  /**
+   * Subscribes to a pub/sub `WebsocketChannel`. Thin wrapper around
+   * the internal client's `subscribeChannel`.
+   * @param {string} channelType - Channel class name registered on the server.
+   * @param {{params?: Record<string, ?>, onMessage?: (body: ?) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Channel subscription options and event handlers.
+   * @returns {?} - Websocket channel handle from the configured client.
+   */
+  static subscribeWebsocketChannel(channelType, options) {
+    const client = /**
+                    * Narrows the runtime value to the documented type.
+                     @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
+
+    if (!client || typeof client.subscribeChannel !== "function") {
+      throw new Error("subscribeWebsocketChannel requires configureTransport({websocketUrl})")
+    }
+
+    return client.subscribeChannel(channelType, options || {})
+  }
+
+  /**
+   * Installs WebSocket lifecycle hooks on globalThis for system test access.
+   * Tests can call `globalThis.__velocious_websocket_hooks.connect()` etc.
+   * @returns {void}
+   */
+  static installWebsocketTestHooks() {
+    if (typeof globalThis === "undefined") return
+
+    /** Narrows the runtime value to the documented type. @type {?} */ (globalThis).__velocious_websocket_hooks = {
+      connect: () => this.connectWebsocket(),
+      disconnect: () => this.disconnectWebsocket(),
+      drop: () => this.dropWebsocket(),
+      state: () => this.websocketState()
+    }
+  }
+
+  /**
+   * Runs attributes from response.
+   * @this {typeof FrontendModelBase}
+   * @param {object} response - Response payload.
+   * @returns {Record<string, ?>} - Attributes from payload.
+   */
+  static attributesFromResponse(response) {
+    const modelData = this.modelDataFromResponse(response)
+
+    return modelData.attributes
+  }
+
+  /**
+   * Runs model data from response.
+   * @this {typeof FrontendModelBase}
+   * @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.
+   */
+  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)
+
+    /**
+     * Defines modelData.
+      @type {Record<string, ?>} */
+    let modelData
+
+    if (responseObject.model && typeof responseObject.model === "object") {
+      modelData = /**
+                   * Narrows the runtime value to the documented type.
+                    @type {Record<string, ?>} */ (responseObject.model)
+    } else if (responseObject.attributes && typeof responseObject.attributes === "object") {
+      modelData = /**
+                   * Narrows the runtime value to the documented type.
+                    @type {Record<string, ?>} */ (responseObject.attributes)
+    } else {
+      modelData = responseObject
+    }
+
+    const attributes = {...modelData}
+    const preloadedRelationships = isPlainObject(attributes[PRELOADED_RELATIONSHIPS_KEY])
+      ? /**
+         * Narrows the runtime value to the documented type.
+          @type {Record<string, ?>} */ (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])
+      : {}
+    const queryData = isPlainObject(attributes[QUERY_DATA_KEY])
+      ? /**
+         * Narrows the runtime value to the documented type.
+          @type {Record<string, ?>} */ (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])
+      : {}
+    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"))
+      : null
+
+    delete attributes[PRELOADED_RELATIONSHIPS_KEY]
+    delete attributes[SELECTED_ATTRIBUTES_KEY]
+    delete attributes[ASSOCIATION_COUNTS_KEY]
+    delete attributes[QUERY_DATA_KEY]
+    delete attributes[ABILITIES_KEY]
+
+    const selectedAttributes = selectedAttributesFromPayload || new Set(Object.keys(attributes))
+
+    return {abilities, attributes, associationCounts, queryData, preloadedRelationships, selectedAttributes}
+  }
+
+  /**
+   * Runs apply preloaded relationships.
+   * @this {typeof FrontendModelBase}
+   * @param {FrontendModelBase} model - Model instance.
+   * @param {Record<string, ?>} preloadedRelationships - Preloaded relationship payload.
+   * @returns {void}
+   */
+  static applyPreloadedRelationships(model, preloadedRelationships) {
+    for (const [relationshipName, relationshipPayload] of Object.entries(preloadedRelationships)) {
+      const relationship = model.getRelationshipByName(relationshipName)
+      const targetModelClass = this.relationshipModelClass(relationshipName)
+
+      if (Array.isArray(relationshipPayload)) {
+        relationship.setLoaded(relationshipPayload.map((entry) => this.instantiateRelationshipValue(entry, targetModelClass)))
+        continue
+      }
+
+      relationship.setLoaded(this.instantiateRelationshipValue(relationshipPayload, targetModelClass))
+    }
+  }
+
+  /**
+   * Runs instantiate relationship value.
+   * @this {typeof FrontendModelBase}
+   * @param {?} relationshipPayload - Relationship payload value.
+   * @param {typeof FrontendModelBase | null} targetModelClass - Target model class.
+   * @returns {?} - Instantiated relationship value.
+   */
+  static instantiateRelationshipValue(relationshipPayload, targetModelClass) {
+    if (!targetModelClass) return relationshipPayload
+
+    if (!relationshipPayload || typeof relationshipPayload !== "object") return relationshipPayload
+
+    return targetModelClass.instantiateFromResponse(relationshipPayload)
+  }
+
+  /**
+   * Runs instantiate from response.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {Record<string, ?> | InstanceType<T>} response - Response payload, or an already-hydrated instance of this class.
+   * @returns {InstanceType<T>} - New model instance, or the same instance unchanged if it was already hydrated.
+   */
+  static instantiateFromResponse(response) {
+    // Idempotent: if a caller hands us an already-hydrated instance of this
+    // class (now common because the shared frontend-model API auto-serializes
+    // backend `Record` instances returned from custom commands and the
+    // transport deserializer hydrates them into models before the call site
+    // sees the response), return it as-is. Without this, code that has
+    // historically wrapped custom-command responses in
+    // `Model.instantiateFromResponse(response.field)` would spread the live
+    // 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)
+    }
+
+    const modelData = this.modelDataFromResponse(response)
+    const attributes = modelData.attributes
+    const preloadedRelationships = modelData.preloadedRelationships
+    const associationCounts = modelData.associationCounts
+    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))
+    model._selectedAttributes = selectedAttributes ? new Set(selectedAttributes) : null
+
+    this.applyPreloadedRelationships(model, preloadedRelationships)
+
+    for (const [attributeName, value] of Object.entries(associationCounts || {})) {
+      model._setAssociationCount(attributeName, Number(value) || 0)
+    }
+
+    for (const [name, value] of Object.entries(queryData || {})) {
+      model._setQueryData(name, value)
+    }
+
+    for (const [action, value] of Object.entries(abilities || {})) {
+      model._setComputedAbility(action, Boolean(value))
+    }
+
+    model.setIsNewRecord(false)
+    model._persistedAttributes = cloneFrontendModelAttributes(model.attributes())
+
+    return model
+  }
+
+  /**
+   * Runs find.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {number | string} id - Record identifier.
+   * @returns {Promise<InstanceType<T>>} - Resolved model.
+   */
+  static async find(id) {
+    return await this.query().find(id)
+  }
+
+  /**
+   * Runs find by.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {Record<string, ?>} conditions - Attribute match conditions.
+   * @returns {Promise<InstanceType<T> | null>} - Found model or null.
+   */
+  static async findBy(conditions) {
+    return await this.query().findBy(conditions)
+  }
+
+  /**
+   * Runs find by or fail.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {Record<string, ?>} conditions - Attribute match conditions.
+   * @returns {Promise<InstanceType<T>>} - Found model.
+   */
+  static async findByOrFail(conditions) {
+    return await this.query().findByOrFail(conditions)
+  }
+
+  /**
+   * Runs to array.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @returns {Promise<InstanceType<T>[]>} - Loaded model instances.
+   */
+  static async toArray() {
+    return await this.query().toArray()
+  }
+
+  /**
+   * Runs load.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @returns {Promise<InstanceType<T>[]>} - Loaded model instances.
+   */
+  static async load() {
+    return await this.query().load()
+  }
+
+  /**
+   * Runs all.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @returns {FrontendModelQuery<T>} - Query builder.
+   */
+  static all() {
+    return this.query()
+  }
+
+  /**
+   * Runs where.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {Record<string, ?>} conditions - Root-model where conditions.
+   * @returns {import("./query.js").default<T>} - Query with where conditions.
+   */
+  static where(conditions) {
+    return this.query().where(conditions)
+  }
+
+  /**
+   * Runs joins.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {Record<string, ?> | Array<Record<string, ?>>} joins - Relationship descriptor joins.
+   * @returns {import("./query.js").default<T>} - Query with joins.
+   */
+  static joins(joins) {
+    return this.query().joins(joins)
+  }
+
+  /**
+   * Runs limit.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {number} value - Maximum number of records.
+   * @returns {import("./query.js").default<T>} - Query with limit.
+   */
+  static limit(value) {
+    return this.query().limit(value)
+  }
+
+  /**
+   * Runs offset.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {number} value - Number of records to skip.
+   * @returns {import("./query.js").default<T>} - Query with offset.
+   */
+  static offset(value) {
+    return this.query().offset(value)
+  }
+
+  /**
+   * Runs page.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {number} pageNumber - 1-based page number.
+   * @returns {import("./query.js").default<T>} - Query with page applied.
+   */
+  static page(pageNumber) {
+    return this.query().page(pageNumber)
+  }
+
+  /**
+   * Runs per page.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {number} value - Number of records per page.
+   * @returns {import("./query.js").default<T>} - Query with page size.
+   */
+  static perPage(value) {
+    return this.query().perPage(value)
+  }
+
+  /**
+   * Runs count.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @returns {Promise<number>} - Number of loaded model instances.
+   */
+  static async count() {
+    return await this.query().count()
+  }
+
+  /**
+   * Class-level hook fired when any record of this model is created.
+   * Subscribe-time authorization only — once a subscription is
+   * accepted, future `create` events for this model are delivered
+   * without re-checking per-record visibility. Query options can still
+   * narrow which events reach this callback.
+   * @this {typeof FrontendModelBase}
+   * @param {(payload: {id: string, model: InstanceType<typeof FrontendModelBase>}) => void} callback - Event callback.
+   * @param {import("./query.js").FrontendModelEventOptions} [options] - Event query or record projection options.
+   * @returns {Promise<() => void>} - Unsubscribe callback.
+   */
+  static async onCreate(callback, options = {}) {
+    const sub = ensureFrontendModelEventSubscription(this)
+    const entry = {callback, ...frontendModelEventOptionsPayload(this, options)}
+
+    sub.classCreateCallbacks.add(entry)
+    await sub.ensureSubscribed()
+
+    return () => {
+      sub.classCreateCallbacks.delete(entry)
+      sub.maybeTeardown()
+    }
+  }
+
+  /**
+   * Class-level hook fired when any record of this model is updated.
+   * @this {typeof FrontendModelBase}
+   * @param {(payload: {id: string, model: InstanceType<typeof FrontendModelBase>}) => void} callback - Event callback.
+   * @param {import("./query.js").FrontendModelEventOptions} [options] - Event query or record projection options.
+   * @returns {Promise<() => void>} - Unsubscribe callback.
+   */
+  static async onUpdate(callback, options = {}) {
+    const sub = ensureFrontendModelEventSubscription(this)
+    const entry = {callback, ...frontendModelEventOptionsPayload(this, options)}
+
+    sub.classUpdateCallbacks.add(entry)
+    await sub.ensureSubscribed()
+
+    return () => {
+      sub.classUpdateCallbacks.delete(entry)
+      sub.maybeTeardown()
+    }
+  }
+
+  /**
+   * Class-level hook fired when any record of this model is destroyed.
+   * @this {typeof FrontendModelBase}
+   * @param {(payload: {id: string}) => void} callback - Event callback.
+   * @param {import("./query.js").FrontendModelEventOptions} [options] - Accepted for API symmetry; destroy events carry ids only.
+   * @returns {Promise<() => void>} - Unsubscribe callback.
+   */
+  static async onDestroy(callback, options = {}) {
+    assertNoDestroyEventFilter(this, options)
+
+    const sub = ensureFrontendModelEventSubscription(this)
+    const entry = {callback}
+
+    sub.classDestroyCallbacks.add(entry)
+    await sub.ensureSubscribed()
+
+    return () => {
+      sub.classDestroyCallbacks.delete(entry)
+      sub.maybeTeardown()
+    }
+  }
+
+  /**
+   * Instance-level hook fired when THIS record is updated. The
+   * instance's attributes are auto-merged with the broadcast payload
+   * before the callback runs, so callers can read fresh values via
+   * `this.someAttr()` without re-fetching.
+   * @param {(payload: {id: string, model: InstanceType<typeof FrontendModelBase>}) => void} callback - Event callback.
+   * @param {import("./query.js").FrontendModelEventOptions} [options] - Event query or record projection options.
+   * @returns {Promise<() => void>} - Unsubscribe callback.
+   */
+  async onUpdate(callback, options = {}) {
+    const self = /**
+                  * Narrows the runtime value to the documented type.
+                   @type {?} */ (this)
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const sub = ensureFrontendModelEventSubscription(ModelClass)
+    const id = String(self.id())
+    const entry = {callback, ...frontendModelEventOptionsPayload(ModelClass, options)}
+    const listener = ensureFrontendModelInstanceListener(sub, id, this)
+
+    listener.updateCallbacks.add(entry)
+    await sub.ensureSubscribed()
+
+    return () => {
+      const current = sub.instanceListeners.get(id)
+
+      if (!current) return
+      current.updateCallbacks.delete(entry)
+
+      if (current.updateCallbacks.size === 0 && current.destroyCallbacks.size === 0) {
+        sub.instanceListeners.delete(id)
+      }
+      sub.maybeTeardown()
+    }
+  }
+
+  /**
+   * Instance-level hook fired when THIS record is destroyed.
+   * @param {(payload: {id: string}) => void} callback - Event callback.
+   * @param {import("./query.js").FrontendModelEventOptions} [options] - Accepted for API symmetry; destroy events carry ids only.
+   * @returns {Promise<() => void>} - Unsubscribe callback.
+   */
+  async onDestroy(callback, options = {}) {
+    const self = /**
+                  * Narrows the runtime value to the documented type.
+                   @type {?} */ (this)
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+
+    assertNoDestroyEventFilter(ModelClass, options)
+
+    const sub = ensureFrontendModelEventSubscription(ModelClass)
+    const id = String(self.id())
+    const entry = {callback}
+    const listener = ensureFrontendModelInstanceListener(sub, id, this)
+
+    listener.destroyCallbacks.add(entry)
+    await sub.ensureSubscribed()
+
+    return () => {
+      const current = sub.instanceListeners.get(id)
+
+      if (!current) return
+      current.destroyCallbacks.delete(entry)
+
+      if (current.updateCallbacks.size === 0 && current.destroyCallbacks.size === 0) {
+        sub.instanceListeners.delete(id)
+      }
+      sub.maybeTeardown()
+    }
+  }
+
+  /**
+   * Runs pluck.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {...(string | string[] | Record<string, ?> | Array<Record<string, ?>>)} columns - Pluck definition(s).
+   * @returns {Promise<Array<?>>} - Plucked values.
+   */
+  static async pluck(...columns) {
+    return await this.query().pluck(...columns)
+  }
+
+  /**
+   * Runs search.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {string[]} path - Relationship path.
+   * @param {string} column - Column or attribute name.
+   * @param {"eq" | "like" | "notEq" | "gt" | "gteq" | "lt" | "lteq" | ">" | ">=" | "<" | "<="} operator - Search operator.
+   * @param {?} value - Search value.
+   * @returns {FrontendModelQuery<T>} - Query builder with search filter.
+   */
+  static search(path, column, operator, value) {
+    return this.query().search(path, column, operator, value)
+  }
+
+  /**
+   * Runs ransack.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {Record<string, ?>} params - Ransack-style params hash.
+   * @returns {FrontendModelQuery<T>} - Query builder with Ransack filters applied.
+   */
+  static ransack(params) {
+    return this.query().ransack(params)
+  }
+
+  /**
+   * Runs sort.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {string | string[] | [string, string] | Array<[string, string]> | Record<string, ?> | Array<Record<string, ?>>} sort - Sort definition(s).
+   * @returns {FrontendModelQuery<T>} - Query builder with sort definitions.
+   */
+  static sort(sort) {
+    return this.query().sort(sort)
+  }
+
+  /**
+   * Runs order.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {string | string[] | [string, string] | Array<[string, string]> | Record<string, ?> | Array<Record<string, ?>>} sort - Sort definition(s).
+   * @returns {FrontendModelQuery<T>} - Query builder with sort definitions.
+   */
+  static order(sort) {
+    return this.query().order(sort)
+  }
+
+  /**
+   * Runs group.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {string | string[] | Record<string, ?> | Array<Record<string, ?>>} group - Group definition(s).
+   * @returns {FrontendModelQuery<T>} - Query builder with group definitions.
+   */
+  static group(group) {
+    return this.query().group(group)
+  }
+
+  /**
+   * Runs distinct.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {boolean} [value] - Whether to request distinct rows.
+   * @returns {FrontendModelQuery<T>} - Query builder with distinct flag.
+   */
+  static distinct(value = true) {
+    return this.query().distinct(value)
+  }
+
+  /**
+   * Runs query.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @returns {FrontendModelQuery<T>} - Query builder.
+   */
+  static query() {
+    return /** Narrows the runtime value to the documented type. @type {FrontendModelQuery<T>} */ (new FrontendModelQuery({modelClass: this}))
+  }
+
+  /**
+   * Runs preload.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {import("../database/query/index.js").NestedPreloadRecord | string | Array<string | import("../database/query/index.js").NestedPreloadRecord>} preload - Preload graph.
+   * @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))
+  }
+
+  /**
+   * Runs select.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {Record<string, string[] | string> | string | string[]} select - Model-aware attribute select map or root-model shorthand.
+   * @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))
+  }
+
+  /**
+   * Runs selects extra.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {Record<string, string[] | string> | string | string[]} select - Extra attributes to load in addition to the defaults, keyed by model name or root-model shorthand.
+   * @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))
+  }
+
+  /**
+   * Runs first.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @returns {Promise<InstanceType<T> | null>} - First model or null.
+   */
+  static async first() {
+    return await this.query().first()
+  }
+
+  /**
+   * Runs last.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @returns {Promise<InstanceType<T> | null>} - Last model or null.
+   */
+  static async last() {
+    return await this.query().last()
+  }
+
+  /**
+   * Runs find or initialize by.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {Record<string, ?>} conditions - Attribute match conditions.
+   * @returns {Promise<InstanceType<T>>} - Existing or initialized model.
+   */
+  static async findOrInitializeBy(conditions) {
+    return await this.query().findOrInitializeBy(conditions)
+  }
+
+  /**
+   * Runs find or create by.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {Record<string, ?>} conditions - Attribute match conditions.
+   * @param {(model: InstanceType<T>) => Promise<void> | void} [callback] - Optional callback before save when created.
+   * @returns {Promise<InstanceType<T>>} - Existing or newly created model.
+   */
+  static async findOrCreateBy(conditions, callback) {
+    return await this.query().findOrCreateBy(conditions, callback)
+  }
+
+  /**
+   * Runs create.
+   * @template {typeof FrontendModelBase} T
+   * @this {T}
+   * @param {Record<string, ?>} [attributes] - Initial attributes.
+   * @returns {Promise<InstanceType<T>>} - Persisted model.
+   */
+  static async create(attributes = {}) {
+    const model = /**
+                   * Narrows the runtime value to the documented type.
+                    @type {InstanceType<T>} */ (new this(attributes))
+
+    await model.save()
+
+    return model
+  }
+
+  /**
+   * Runs assert find by conditions.
+   * @this {typeof FrontendModelBase}
+   * @param {Record<string, ?>} conditions - findBy conditions.
+   * @returns {void}
+   */
+  static assertFindByConditions(conditions) {
+    assertFindByConditionsShape(conditions)
+
+    Object.keys(conditions).forEach((key) => {
+      assertDefinedFindByConditionValue(conditions[key], key)
+    })
+  }
+
+  /**
+   * Runs matches find by conditions.
+   * @this {typeof FrontendModelBase}
+   * @param {FrontendModelBase} model - Candidate model.
+   * @param {Record<string, ?>} conditions - Match conditions.
+   * @returns {boolean} - Whether the model matches all conditions.
+   */
+  static matchesFindByConditions(model, conditions) {
+    const modelAttributes = model.attributes()
+
+    for (const key of Object.keys(conditions)) {
+      const expectedValue = conditions[key]
+      const actualValue = modelAttributes[key]
+
+      if (Array.isArray(expectedValue)) {
+        if (Array.isArray(actualValue)) {
+          if (!this.findByConditionValueMatches(actualValue, expectedValue)) {
+            return false
+          }
+        } else if (!expectedValue.some((entry) => this.findByConditionValueMatches(actualValue, entry))) {
+          return false
+        }
+      } else if (!this.findByConditionValueMatches(actualValue, expectedValue)) {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  /**
+   * Runs find by condition value matches.
+   * @this {typeof FrontendModelBase}
+   * @param {?} actualValue - Actual model value.
+   * @param {?} expectedValue - Expected find condition value.
+   * @returns {boolean} - Whether values match.
+   */
+  static findByConditionValueMatches(actualValue, expectedValue) {
+    if (expectedValue === null) {
+      return actualValue === null
+    }
+
+    if (Array.isArray(expectedValue)) {
+      if (!Array.isArray(actualValue)) {
+        return false
+      }
+
+      if (actualValue.length !== expectedValue.length) {
+        return false
+      }
+
+      for (let index = 0; index < expectedValue.length; index += 1) {
+        if (!this.findByConditionValueMatches(actualValue[index], expectedValue[index])) {
+          return false
+        }
+      }
+
+      return true
+    }
+
+    if (expectedValue && typeof expectedValue === "object") {
+      if (!actualValue || typeof actualValue !== "object" || Array.isArray(actualValue)) {
+        return false
+      }
+
+      const actualObject = /**
+                            * Narrows the runtime value to the documented type.
+                             @type {Record<string, ?>} */ (actualValue)
+      const expectedObject = /**
+                              * Narrows the runtime value to the documented type.
+                               @type {Record<string, ?>} */ (expectedValue)
+      const actualKeys = Object.keys(actualObject)
+      const expectedKeys = Object.keys(expectedObject)
+
+      if (actualKeys.length !== expectedKeys.length) {
+        return false
+      }
+
+      for (const key of expectedKeys) {
+        if (!Object.prototype.hasOwnProperty.call(actualObject, key)) {
+          return false
+        }
+
+        if (!this.findByConditionValueMatches(actualObject[key], expectedObject[key])) {
+          return false
+        }
+      }
+
+      return true
+    }
+
+    if (actualValue === expectedValue) {
+      return true
+    }
+
+    return this.findByPrimitiveValuesMatch(actualValue, expectedValue)
+  }
+
+  /**
+   * Runs find by primitive values match.
+   * @this {typeof FrontendModelBase}
+   * @param {?} actualValue - Actual model value.
+   * @param {?} expectedValue - Expected find condition value.
+   * @returns {boolean} - Whether primitive values match after safe coercion.
+   */
+  static findByPrimitiveValuesMatch(actualValue, expectedValue) {
+    if (actualValue instanceof Date && typeof expectedValue === "string") {
+      return actualValue.toISOString() === expectedValue
+    }
+
+    if (typeof actualValue === "string" && expectedValue instanceof Date) {
+      return actualValue === expectedValue.toISOString()
+    }
+
+    if (actualValue instanceof Date && expectedValue instanceof Date) {
+      return actualValue.toISOString() === expectedValue.toISOString()
+    }
+
+    if (typeof actualValue === "number" && typeof expectedValue === "string") {
+      return this.findByNumericStringMatchesNumber(expectedValue, actualValue)
+    }
+
+    if (typeof actualValue === "string" && typeof expectedValue === "number") {
+      return this.findByNumericStringMatchesNumber(actualValue, expectedValue)
+    }
+
+    return false
+  }
+
+  /**
+   * Runs find by numeric string matches number.
+   * @this {typeof FrontendModelBase}
+   * @param {string} numericString - Numeric string value.
+   * @param {number} expectedNumber - Number value.
+   * @returns {boolean} - Whether values represent the same number.
+   */
+  static findByNumericStringMatchesNumber(numericString, expectedNumber) {
+    if (!Number.isFinite(expectedNumber)) {
+      return false
+    }
+
+    if (!/^-?\d+(?:\.\d+)?$/.test(numericString)) {
+      return false
+    }
+
+    return Number(numericString) === expectedNumber
+  }
+
+  /**
+   * Runs update.
+   * @param {Record<string, ?>} [newAttributes] - New values to assign before update.
+   * @returns {Promise<this>} - Updated model.
+   */
+  async update(newAttributes = {}) {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const attachmentDefinitions = ModelClass.attachmentDefinitions()
+    /**
+     * Regular attributes.
+      @type {Record<string, ?>} */
+    const regularAttributes = {}
+    /**
+     * Pending attachments.
+      @type {Array<{attachmentName: string, value: ?}>} */
+    const pendingAttachments = []
+
+    for (const [attributeName, attributeValue] of Object.entries(newAttributes)) {
+      if (attachmentDefinitions[attributeName]) {
+        if (attributeValue !== undefined && attributeValue !== null) {
+          pendingAttachments.push({attachmentName: attributeName, value: attributeValue})
+        }
+      } else {
+        regularAttributes[attributeName] = attributeValue
+      }
+    }
+
+    if (Object.keys(regularAttributes).length > 0) {
+      this.assignAttributes(regularAttributes)
+      const changedAttributes = Object.fromEntries(
+        Object.entries(this.changes()).map(([attributeName, [, currentValue]]) => [attributeName, currentValue])
+      )
+
+      const response = await ModelClass.executeCommand("update", {
+        attributes: changedAttributes,
+        id: this.primaryKeyValue()
+      })
+
+      this.assignAttributes(ModelClass.attributesFromResponse(response))
+      this.setIsNewRecord(false)
+      this._persistedAttributes = cloneFrontendModelAttributes(this.attributes())
+    }
+
+    for (const pendingAttachment of pendingAttachments) {
+      await this.getAttachmentByName(pendingAttachment.attachmentName).attach(pendingAttachment.value)
+    }
+
+    return this
+  }
+
+  /**
+   * Runs attach.
+   * @param {?} attachmentInput - Attachment input or named attachment payload.
+   * @returns {Promise<void>} - Resolves when attached.
+   */
+  async attach(attachmentInput) {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const attachmentDefinitions = ModelClass.attachmentDefinitions()
+    const attachmentNames = Object.keys(attachmentDefinitions)
+    let attachmentName = attachmentNames[0]
+    let actualAttachmentInput = attachmentInput
+
+    if (frontendAttachmentValueIsPlainObject(attachmentInput)) {
+      if ("file" in attachmentInput && attachmentDefinitions.file) {
+        attachmentName = "file"
+      }
+
+      for (const candidateName of attachmentNames) {
+        if (candidateName in attachmentInput) {
+          attachmentName = candidateName
+          actualAttachmentInput = attachmentInput[candidateName]
+          break
+        }
+      }
+    }
+
+    if (!attachmentName) {
+      throw new Error(`No attachment definitions on ${ModelClass.name}`)
+    }
+
+    await this.getAttachmentByName(attachmentName).attach(actualAttachmentInput)
+  }
+
+  /**
+   * Runs save.
+   * @returns {Promise<this>} - Saved model.
+   */
+  async save() {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const isNew = this.isNewRecord()
+    const commandType = isNew ? "create" : "update"
+    /**
+     * Payload.
+      @type {Record<string, ?>} */
+    const payload = {
+      attributes: this._changedAttributesForSave()
+    }
+
+    if (!isNew) {
+      payload.id = this.primaryKeyValue()
+    }
+
+    const nestedAttributes = this._buildNestedAttributesPayload()
+
+    if (nestedAttributes && Object.keys(nestedAttributes).length > 0) {
+      payload.nestedAttributes = nestedAttributes
+    }
+
+    const response = await ModelClass.executeCommand(commandType, payload)
+
+    this.assignAttributes(ModelClass.attributesFromResponse(response))
+    this.setIsNewRecord(false)
+    this._persistedAttributes = cloneFrontendModelAttributes(this.attributes())
+
+    this._reconcileNestedAttributesFromResponse(response)
+
+    return this
+  }
+
+  /**
+   * Returns the subset of `_attributes` whose value has diverged from
+   * `_persistedAttributes`. Used by `save()` so the server receives only the
+   * 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.
+   */
+  _changedAttributesForSave() {
+    /**
+     * Changed attributes.
+      @type {Record<string, ?>} */
+    const changedAttributes = {}
+
+    for (const [attributeName, [previousValue, currentValue]] of Object.entries(this.changes())) {
+      if (this.isNewRecord() && previousValue === undefined && currentValue === null) continue
+
+      changedAttributes[attributeName] = currentValue
+    }
+
+    return changedAttributes
+  }
+
+  /**
+   * Marks the current value for an attribute as already persisted so the next
+   * save does not send it unless the caller changes it again.
+   * @param {string} attributeName - Attribute to mark unchanged.
+   * @returns {void}
+   */
+  markAttributeUnchanged(attributeName) {
+    this._persistedAttributes[attributeName] = cloneFrontendModelAttributes({value: this._attributes[attributeName]}).value
+  }
+
+  /**
+   * Runs destroy.
+   * @returns {Promise<void>} - Resolves when destroyed on backend.
+   */
+  async destroy() {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+
+    await ModelClass.executeCommand("destroy", {
+      id: this.primaryKeyValue()
+    })
+  }
+
+  /**
+   * Walks relationships declared in this resource's `nestedAttributes` config
+   * and builds the per-relationship payload of dirty children for a parent save.
+   *
+   * Included children:
+   *   - new records (isNewRecord()) → create entry with attributes
+   *   - records marked for destruction (markedForDestruction()) → destroy entry
+   *   - records with changed attributes (isChanged()) → update entry with attributes
+   *   - records with dirty descendants in their own nestedAttributes → recurse
+   *
+   * Loaded but untouched records are omitted so nested save preserves Rails-style
+   * "children not referenced in payload are left alone" semantics.
+   * @returns {Record<string, Array<Record<string, ?>>>} - Per-relationship list of nested-attribute entries.
+   */
+  _buildNestedAttributesPayload() {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const resourceConfig = typeof ModelClass.resourceConfig === "function" ? ModelClass.resourceConfig() : null
+    const nestedAttributesConfig = resourceConfig?.nestedAttributes
+
+    if (!nestedAttributesConfig) return {}
+
+    /**
+     * Payload.
+      @type {Record<string, Array<Record<string, ?>>>} */
+    const payload = {}
+
+    for (const relationshipName of Object.keys(nestedAttributesConfig)) {
+      const relationship = this._relationships[relationshipName]
+
+      if (!relationship || !(relationship instanceof FrontendModelHasManyRelationship)) continue
+      if (!Array.isArray(relationship._loadedValue) || relationship._loadedValue.length === 0) continue
+
+      /**
+       * Entries.
+        @type {Array<Record<string, ?>>} */
+      const entries = []
+
+      for (const child of relationship._loadedValue) {
+        const childEntry = child._nestedAttributesEntryForParentSave()
+
+        if (childEntry) entries.push(childEntry)
+      }
+
+      if (entries.length > 0) {
+        payload[relationshipName] = entries
+      }
+    }
+
+    return payload
+  }
+
+  /**
+   * Builds the payload entry for this child when walked by a parent's
+   * `_buildNestedAttributesPayload`. Returns `null` when the child has no
+   * dirty state and no dirty descendants, so the parent can omit it.
+   * @returns {Record<string, ?> | null} - Nested-attribute entry or null if clean.
+   */
+  _nestedAttributesEntryForParentSave() {
+    if (this.markedForDestruction()) {
+      if (this.isNewRecord()) return null
+      return {id: this.primaryKeyValue(), _destroy: true}
+    }
+
+    const nestedAttributes = this._buildNestedAttributesPayload()
+    const hasNestedDirty = Object.keys(nestedAttributes).length > 0
+
+    if (this.isNewRecord()) {
+      /**
+       * Entry.
+        @type {Record<string, ?>} */
+      const entry = {attributes: this.attributes()}
+
+      if (hasNestedDirty) entry.nestedAttributes = nestedAttributes
+
+      return entry
+    }
+
+    if (!this.isChanged() && !hasNestedDirty) return null
+
+    /**
+     * Entry.
+      @type {Record<string, ?>} */
+    const entry = {id: this.primaryKeyValue()}
+
+    if (this.isChanged()) entry.attributes = this.attributes()
+    if (hasNestedDirty) entry.nestedAttributes = nestedAttributes
+
+    return entry
+  }
+
+  /**
+   * After a parent save with `nestedAttributes`, the server response includes
+   * preloaded versions of the affected relationships. This replaces the local
+   * `_loadedValue` for each nested-writable relationship with the server's
+   * authoritative set, so destroyed children are dropped and newly-created
+   * children get their server-assigned ids + persisted state.
+   * @param {Record<string, ?>} response - Command response payload.
+   * @returns {void}
+   */
+  _reconcileNestedAttributesFromResponse(response) {
+    const ModelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof FrontendModelBase} */ (this.constructor)
+    const resourceConfig = typeof ModelClass.resourceConfig === "function" ? ModelClass.resourceConfig() : null
+    const nestedAttributesConfig = resourceConfig?.nestedAttributes
+
+    if (!nestedAttributesConfig) return
+
+    const modelData = ModelClass.modelDataFromResponse(response)
+    const preloadedRelationships = modelData.preloadedRelationships
+
+    /**
+     * Relevant preloads.
+      @type {Record<string, ?>} */
+    const relevantPreloads = {}
+
+    for (const relationshipName of Object.keys(nestedAttributesConfig)) {
+      if (relationshipName in preloadedRelationships) {
+        relevantPreloads[relationshipName] = preloadedRelationships[relationshipName]
+      }
+    }
+
+    if (Object.keys(relevantPreloads).length > 0) {
+      ModelClass.applyPreloadedRelationships(this, relevantPreloads)
+    }
+  }
+
+  /**
+   * Runs execute command.
+   * @this {typeof FrontendModelBase}
+   * @param {FrontendModelCommandType} commandType - Command type.
+   * @param {Record<string, ?>} payload - Command payload.
+   * @returns {Promise<Record<string, ?>>} - Parsed JSON response.
+   */
+  static async executeCommand(commandType, payload) {
+    const commandName = this.commandName(commandType)
+    const serializedPayload = /**
+                               * Narrows the runtime value to the documented type.
+                                @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(payload))
+    const resourcePath = this.resourcePath()
+    const containsAttachmentUpload = frontendModelPayloadContainsAttachmentUpload(serializedPayload)
+    const useSharedTransport = !containsAttachmentUpload
+    const url = useSharedTransport ? frontendModelApiUrl() : frontendModelCommandUrl(resourcePath || "", commandName)
+
+    if (useSharedTransport) {
+      const batchResponse = await new Promise((resolve, reject) => {
+        pendingSharedFrontendModelRequests.push({
+          commandName,
+          commandType,
+          modelClass: this,
+          payload: serializedPayload,
+          reject,
+          requestId: `${++sharedFrontendModelRequestId}`,
+          resolve,
+          resourcePath
+        })
+
+        scheduleSharedFrontendModelRequestFlush()
+      })
+
+      const decodedBatchResponse = /**
+                                    * Narrows the runtime value to the documented type.
+                                     @type {Record<string, ?>} */ (batchResponse)
+
+      this.throwOnErrorFrontendModelResponse({
+        commandType,
+        response: decodedBatchResponse
+      })
+
+      return decodedBatchResponse
+    }
+
+    return await trackFrontendModelTransportRequest(async () => {
+      const directResponse = await fetch(url, {
+        body: JSON.stringify(serializedPayload),
+        credentials: "include",
+        headers: frontendModelRequestHeaders(),
+        method: "POST"
+      })
+
+      const directResponseText = await directResponse.text()
+
+      if (!directResponse.ok) {
+        throwFrontendModelHttpError({
+          commandLabel: `${this.name}#${commandType}`,
+          response: directResponse,
+          responseText: directResponseText
+        })
+      }
+
+      const directJson = directResponseText.length > 0 ? JSON.parse(directResponseText) : {}
+      const decodedDirectResponse = /**
+                                     * Narrows the runtime value to the documented type.
+                                      @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(directJson))
+
+      this.throwOnErrorFrontendModelResponse({
+        commandType,
+        response: decodedDirectResponse
+      })
+
+      return decodedDirectResponse
+    })
+  }
+
+  /**
+   * Runs execute custom command.
+   * @this {typeof FrontendModelBase}
+   * @param {object} args - Command arguments.
+   * @param {string} args.commandName - Raw command path segment.
+   * @param {FrontendModelRequestCommandType} args.commandType - Logical command type for error handling.
+   * @param {string | number | null} [args.memberId] - Optional member id for member-scoped commands.
+   * @param {Record<string, ?>} args.payload - Request payload.
+   * @param {string} args.resourcePath - Direct resource path.
+   * @returns {Promise<Record<string, ?>>} - Decoded response payload.
+   */
+  static async executeCustomCommand({commandName, commandType, memberId = null, payload, resourcePath}) {
+    const serializedPayload = /**
+                               * Narrows the runtime value to the documented type.
+                                @type {Record<string, ?>} */ (serializeFrontendModelTransportValue(payload))
+    const customPath = frontendModelCustomCommandPath({
+      commandName,
+      memberId,
+      modelName: this.getModelName(),
+      resourcePath
+    })
+
+    const batchResponse = await new Promise((resolve, reject) => {
+      pendingSharedFrontendModelRequests.push({
+        commandType,
+        customPath,
+        modelClass: this,
+        payload: serializedPayload,
+        reject,
+        requestId: `${++sharedFrontendModelRequestId}`,
+        resolve
+      })
+
+      scheduleSharedFrontendModelRequestFlush()
+    })
+
+    const decodedBatchResponse = /**
+                                  * Narrows the runtime value to the documented type.
+                                   @type {Record<string, ?>} */ (batchResponse)
+
+    this.throwOnErrorFrontendModelResponse({
+      commandType,
+      response: decodedBatchResponse
+    })
+
+    return decodedBatchResponse
+  }
+
+  /**
+   * Runs throw on error frontend model response.
+   * @this {typeof FrontendModelBase}
+   * @param {object} args - Arguments.
+   * @param {FrontendModelRequestCommandType} args.commandType - Command type.
+   * @param {Record<string, ?>} args.response - Decoded response.
+   * @returns {void}
+   */
+  static throwOnErrorFrontendModelResponse({commandType, response}) {
+    if (response?.status !== "error") return
+
+    const responseKeys = Object.keys(response)
+    const hasOnlyStatus = responseKeys.length === 1 && responseKeys[0] === "status"
+    const hasErrorMessage = typeof response.errorMessage === "string" && response.errorMessage.length > 0
+    const hasErrorEnvelopeKeys = Boolean(
+      response.code !== undefined
+      || response.error !== undefined
+      || response.errors !== undefined
+      || response.message !== undefined
+    )
+    const nonStatusKeys = responseKeys.filter((key) => key !== "status")
+    const configuredAttributeNames = this.configuredFrontendModelAttributeNames()
+    const looksLikeRawModelPayload = nonStatusKeys.length > 0
+      && nonStatusKeys.every((key) => configuredAttributeNames.has(key))
+
+    if (!hasErrorMessage && !hasOnlyStatus && !hasErrorEnvelopeKeys && looksLikeRawModelPayload) return
+
+    const debugErrorMessage = typeof response.debugErrorMessage === "string" && response.debugErrorMessage.length > 0
+      ? response.debugErrorMessage
+      : null
+    const errorMessage = debugErrorMessage || (hasErrorMessage
+      ? response.errorMessage
+      : `Request failed for ${this.name}#${commandType}`)
+
+    const error = /**
+                   * Narrows the runtime value to the documented type.
+                    @type {Error & {velocious?: Record<string, ?>, errorType?: string, validationErrors?: Record<string, ?>}} */ (new Error(errorMessage))
+    if (response.velocious && typeof response.velocious === "object") {
+      error.velocious = response.velocious
+    }
+    if (typeof response.errorType === "string") {
+      error.errorType = response.errorType
+    }
+    if (response.validationErrors && typeof response.validationErrors === "object") {
+      error.validationErrors = response.validationErrors
+    }
+    throw error
+  }
+
+  /**
+   * Runs configured frontend model attribute names.
+   * @this {typeof FrontendModelBase}
+   * @returns {Set<string>} - Configured frontend model attribute names.
+   */
+  static configuredFrontendModelAttributeNames() {
+    const resourceConfig = /**
+                            * Narrows the runtime value to the documented type.
+                             @type {Record<string, ?>} */ (this.resourceConfig())
+    const attributes = resourceConfig.attributes
+
+    if (Array.isArray(attributes)) {
+      return new Set(attributes.filter((attributeName) => typeof attributeName === "string"))
+    }
+
+    if (attributes && typeof attributes === "object") {
+      return new Set(Object.keys(attributes))
+    }
+
+    return new Set()
+  }
+}