velocious 1.0.444 → 1.0.446

package/README.md

@@ -1597,6 +1597,8 @@ configuration.getErrorEvents().on("all-error", ({error, errorType}) => {
 })
 ```
 
+Genuinely unexpected frontend-model command failures reach this bus too. The frontend-model controller catches them to return a client-safe `Request failed.` response, but it also emits them as `framework-error`/`all-error` (with `context.frontendModelEndpoint === true`) so they are reported instead of being silently swallowed. Expected user-flow errors are excluded: validation failures are forwarded with their real message (for example `Name can't be blank`) rather than the generic one, and `error.velocious`-annotated / `safeToExpose` errors keep their own message — none of these reach the error bus.
+
 ## Use the Websocket client API (HTTP-like)
 
 ```js

package/build/database/record/index.js

@@ -7,7 +7,7 @@
 
 /**
  * LifecycleCallbackType type.
- * @template {VelociousDatabaseRecord} [T=VelociousDatabaseRecord]
+ * @template [T=VelociousDatabaseRecord]
  * @typedef {((model: T) => void | Promise<void>) | string} LifecycleCallbackType
  */
 
@@ -507,101 +507,101 @@ class VelociousDatabaseRecord {
 
   /**
    * Runs before validation.
-   * @template {typeof VelociousDatabaseRecord} MC
-   * @this {MC}
-   * @param {LifecycleCallbackType<InstanceType<MC>>} callback - Callback function or instance method name.
+   * @template R
+   * @this {new (...args: Array<?>) => R}
+   * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
   static beforeValidation(callback) {
-    this.registerLifecycleCallback("beforeValidation", /** @type {LifecycleCallbackType} */ (callback))
+    VelociousDatabaseRecord.registerLifecycleCallback.call(this, "beforeValidation", /** @type {LifecycleCallbackType} */ (callback))
   }
 
   /**
    * Runs before save.
-   * @template {typeof VelociousDatabaseRecord} MC
-   * @this {MC}
-   * @param {LifecycleCallbackType<InstanceType<MC>>} callback - Callback function or instance method name.
+   * @template R
+   * @this {new (...args: Array<?>) => R}
+   * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
   static beforeSave(callback) {
-    this.registerLifecycleCallback("beforeSave", /** @type {LifecycleCallbackType} */ (callback))
+    VelociousDatabaseRecord.registerLifecycleCallback.call(this, "beforeSave", /** @type {LifecycleCallbackType} */ (callback))
   }
 
   /**
    * Runs before create.
-   * @template {typeof VelociousDatabaseRecord} MC
-   * @this {MC}
-   * @param {LifecycleCallbackType<InstanceType<MC>>} callback - Callback function or instance method name.
+   * @template R
+   * @this {new (...args: Array<?>) => R}
+   * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
   static beforeCreate(callback) {
-    this.registerLifecycleCallback("beforeCreate", /** @type {LifecycleCallbackType} */ (callback))
+    VelociousDatabaseRecord.registerLifecycleCallback.call(this, "beforeCreate", /** @type {LifecycleCallbackType} */ (callback))
   }
 
   /**
    * Runs before update.
-   * @template {typeof VelociousDatabaseRecord} MC
-   * @this {MC}
-   * @param {LifecycleCallbackType<InstanceType<MC>>} callback - Callback function or instance method name.
+   * @template R
+   * @this {new (...args: Array<?>) => R}
+   * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
   static beforeUpdate(callback) {
-    this.registerLifecycleCallback("beforeUpdate", /** @type {LifecycleCallbackType} */ (callback))
+    VelociousDatabaseRecord.registerLifecycleCallback.call(this, "beforeUpdate", /** @type {LifecycleCallbackType} */ (callback))
   }
 
   /**
    * Runs before destroy.
-   * @template {typeof VelociousDatabaseRecord} MC
-   * @this {MC}
-   * @param {LifecycleCallbackType<InstanceType<MC>>} callback - Callback function or instance method name.
+   * @template R
+   * @this {new (...args: Array<?>) => R}
+   * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
   static beforeDestroy(callback) {
-    this.registerLifecycleCallback("beforeDestroy", /** @type {LifecycleCallbackType} */ (callback))
+    VelociousDatabaseRecord.registerLifecycleCallback.call(this, "beforeDestroy", /** @type {LifecycleCallbackType} */ (callback))
   }
 
   /**
    * Runs after save.
-   * @template {typeof VelociousDatabaseRecord} MC
-   * @this {MC}
-   * @param {LifecycleCallbackType<InstanceType<MC>>} callback - Callback function or instance method name.
+   * @template R
+   * @this {new (...args: Array<?>) => R}
+   * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
   static afterSave(callback) {
-    this.registerLifecycleCallback("afterSave", /** @type {LifecycleCallbackType} */ (callback))
+    VelociousDatabaseRecord.registerLifecycleCallback.call(this, "afterSave", /** @type {LifecycleCallbackType} */ (callback))
   }
 
   /**
    * Runs after create.
-   * @template {typeof VelociousDatabaseRecord} MC
-   * @this {MC}
-   * @param {LifecycleCallbackType<InstanceType<MC>>} callback - Callback function or instance method name.
+   * @template R
+   * @this {new (...args: Array<?>) => R}
+   * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
   static afterCreate(callback) {
-    this.registerLifecycleCallback("afterCreate", /** @type {LifecycleCallbackType} */ (callback))
+    VelociousDatabaseRecord.registerLifecycleCallback.call(this, "afterCreate", /** @type {LifecycleCallbackType} */ (callback))
   }
 
   /**
    * Runs after update.
-   * @template {typeof VelociousDatabaseRecord} MC
-   * @this {MC}
-   * @param {LifecycleCallbackType<InstanceType<MC>>} callback - Callback function or instance method name.
+   * @template R
+   * @this {new (...args: Array<?>) => R}
+   * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
   static afterUpdate(callback) {
-    this.registerLifecycleCallback("afterUpdate", /** @type {LifecycleCallbackType} */ (callback))
+    VelociousDatabaseRecord.registerLifecycleCallback.call(this, "afterUpdate", /** @type {LifecycleCallbackType} */ (callback))
   }
 
   /**
    * Runs after destroy.
-   * @template {typeof VelociousDatabaseRecord} MC
-   * @this {MC}
-   * @param {LifecycleCallbackType<InstanceType<MC>>} callback - Callback function or instance method name.
+   * @template R
+   * @this {new (...args: Array<?>) => R}
+   * @param {LifecycleCallbackType<R>} callback - Callback function or instance method name.
    * @returns {void}
    */
   static afterDestroy(callback) {
-    this.registerLifecycleCallback("afterDestroy", /** @type {LifecycleCallbackType} */ (callback))
+    VelociousDatabaseRecord.registerLifecycleCallback.call(this, "afterDestroy", /** @type {LifecycleCallbackType} */ (callback))
   }
 
   /**

package/build/environment-handlers/node/cli/commands/generate/base-models.js

@@ -115,12 +115,48 @@ export default class DbGenerateModel extends BaseCommand {
           velociousPath = "velocious/build/src"
         }
 
+        const columns = await table.getColumns()
+        const writeAttributeTypeName = `${modelNameCamelized}WriteAttributes`
+        const nestedWriteAttributes = this.nestedWriteAttributesForModel({modelClass})
+
         fileContent += `import DatabaseRecord from "${velociousPath}/database/record/index.js"\n\n`
+        fileContent += "/**\n"
+        fileContent += ` * Attributes accepted when creating or updating ${modelNameCamelized} records.\n`
+        fileContent += ` * @typedef {object} ${writeAttributeTypeName}\n`
+        for (const column of columns) {
+          const deburredColumnName = deburrColumnName(column.getName())
+          const camelizedColumnName = inflection.camelize(deburredColumnName, true)
+          const setterJsdocType = this.jsDocSetterTypeFromColumn(column, modelClass)
+
+          if (setterJsdocType) {
+            fileContent += ` * @property {${setterJsdocType}${column.getNull() ? " | null" : ""}} [${camelizedColumnName}] - Value for the ${camelizedColumnName} attribute.\n`
+          }
+        }
+        for (const nestedWriteAttribute of nestedWriteAttributes) {
+          fileContent += ` * @property {${nestedWriteAttribute.propertyType}} [${nestedWriteAttribute.propertyName}] - Nested ${nestedWriteAttribute.relationshipName} attributes.\n`
+        }
+        fileContent += " */\n\n"
 
         const hasManyRelationFilePath = `${velociousPath}/database/record/instance-relationships/has-many.js`
 
         fileContent += `export default class ${modelNameCamelized}Base extends DatabaseRecord {\n`
 
+        fileContent += "  /**\n"
+        fileContent += `   * Creates a ${modelNameCamelized} record.\n`
+        fileContent += `   * @template {typeof ${modelNameCamelized}Base} T\n`
+        fileContent += "   * @this {T}\n"
+        fileContent += `   * @param {${writeAttributeTypeName}} [attributes] - Attributes for the new record.\n`
+        fileContent += "   * @returns {Promise<InstanceType<T>>} - Persisted record.\n"
+        fileContent += "   */\n"
+        fileContent += "  static async create(attributes) { return /** @type {Promise<InstanceType<T>>} */ (super.create(attributes)) }\n\n"
+
+        fileContent += "  /**\n"
+        fileContent += `   * Updates this ${modelNameCamelized} record.\n`
+        fileContent += `   * @param {${writeAttributeTypeName}} attributes - Attributes to assign before saving.\n`
+        fileContent += "   * @returns {Promise<void>} - Resolves when the record is saved.\n"
+        fileContent += "   */\n"
+        fileContent += "  async update(attributes) { return await super.update(attributes) }\n\n"
+
       // --- getModelClass() override (fixes polymorphic typing in JS/JSDoc) ---
       if (await fileExists(sourceModelFullFilePath)) {
         // Model file exists (e.g. src/models/ticket.js) → return typeof Ticket
@@ -138,7 +174,6 @@ export default class DbGenerateModel extends BaseCommand {
         fileContent += `  getModelClass() { return /** @type {typeof ${modelNameCamelized}Base} */ (this.constructor) }\n\n`
       }
 
-      const columns = await table.getColumns()
       let methodsCount = 0
 
       for (const column of columns) {
@@ -416,4 +451,35 @@ export default class DbGenerateModel extends BaseCommand {
 
     return this.jsDocTypeFromColumn(column, modelClass)
   }
+
+  /**
+   * Runs nested write attributes for model.
+   * @param {object} args - Arguments.
+   * @param {typeof import("../../../../../database/record/index.js").default} args.modelClass - Model class.
+   * @returns {Array<{propertyName: string, propertyType: string, relationshipName: string}>} - Nested write attributes.
+   */
+  nestedWriteAttributesForModel({modelClass}) {
+    const acceptedNestedAttributes = modelClass._acceptedNestedAttributes || {}
+    const nestedWriteAttributes = []
+
+    for (const relationshipName of Object.keys(acceptedNestedAttributes)) {
+      const relationship = modelClass.getRelationshipByName(relationshipName)
+      const relationshipType = relationship.getType()
+      const targetModelClass = relationship.getTargetModelClass()
+
+      if (!targetModelClass) throw new Error(`Relationship '${relationshipName}' on '${modelClass.getModelName()}' has no target model class`)
+
+      const targetModelFileName = inflection.dasherize(inflection.underscore(targetModelClass.getModelName()))
+      const targetWriteTypeName = `${inflection.camelize(targetModelClass.getModelName().replaceAll("-", "_"))}WriteAttributes`
+      const nestedType = `import("./${targetModelFileName}.js").${targetWriteTypeName}${acceptedNestedAttributes[relationshipName]?.allowDestroy ? " & {_destroy?: boolean}" : ""}`
+
+      nestedWriteAttributes.push({
+        propertyName: `${relationshipName}Attributes`,
+        propertyType: relationshipType == "hasMany" ? `Array<${nestedType}>` : nestedType,
+        relationshipName
+      })
+    }
+
+    return nestedWriteAttributes
+  }
 }

package/build/environment-handlers/node/cli/commands/generate/frontend-models.js

@@ -228,7 +228,12 @@ export default class DbGenerateFrontendModels extends BaseCommand {
       ? modelConfig.attachments
       : {}
     const attributesTypeName = `${className}Attributes`
+    const createAttributesTypeName = `${className}CreateAttributes`
+    const updateAttributesTypeName = `${className}UpdateAttributes`
     const attributeNames = attributes.map((attribute) => attribute.name)
+    const permittedCreateParams = this.permittedParamsForGenerator(resourceClass || null, "create")
+    const permittedUpdateParams = this.permittedParamsForGenerator(resourceClass || null, "update")
+    const nestedWriteTypes = this.nestedWriteTypesForModel({className, permittedParams: permittedCreateParams.concat(permittedUpdateParams), relationships})
     const builtInCollectionCommands = {
       create: modelConfig.builtInCollectionCommands.create || "create",
       index: modelConfig.builtInCollectionCommands.index || "index"
@@ -268,8 +273,32 @@ export default class DbGenerateFrontendModels extends BaseCommand {
       fileContent += ` * @property {${attribute.jsDocType}} ${attribute.name} - Attribute value.\n`
     }
     fileContent += " */\n"
+    for (const nestedWriteType of nestedWriteTypes) {
+      fileContent += "/**\n"
+      fileContent += ` * Attributes accepted for nested ${nestedWriteType.relationshipName} writes.\n`
+      fileContent += ` * @typedef {object} ${nestedWriteType.typeName}\n`
+      for (const nestedAttribute of nestedWriteType.attributes) {
+        fileContent += ` * @property {${nestedAttribute.type}} [${nestedAttribute.name}] - Nested ${nestedAttribute.name} value.\n`
+      }
+      fileContent += " */\n"
+    }
+    fileContent += this.writeAttributesTypedef({attributes, attributesTypeName, nestedWriteTypes, permittedParams: permittedCreateParams, typeName: createAttributesTypeName})
+    fileContent += this.writeAttributesTypedef({attributes, attributesTypeName, nestedWriteTypes, permittedParams: permittedUpdateParams, typeName: updateAttributesTypeName})
     fileContent += `/** Frontend model for ${className}. */\n`
     fileContent += `export default class ${className} extends FrontendModelBase {\n`
+    fileContent += "  /**\n"
+    fileContent += `   * Creates a ${className}.\n`
+    fileContent += `   * @param {${createAttributesTypeName}} [attributes] - Attributes for the new model.\n`
+    fileContent += `   * @returns {Promise<${className}>} - Persisted model.\n`
+    fileContent += "   */\n"
+    fileContent += `  static async create(attributes = {}) { return /** @type {Promise<${className}>} */ (super.create(attributes)) }\n\n`
+
+    fileContent += "  /**\n"
+    fileContent += `   * Updates this ${className}.\n`
+    fileContent += `   * @param {${updateAttributesTypeName}} [newAttributes] - Attributes to assign before saving.\n`
+    fileContent += `   * @returns {Promise<${className}>} - Updated model.\n`
+    fileContent += "   */\n"
+    fileContent += `  async update(newAttributes = {}) { return /** @type {Promise<${className}>} */ (super.update(newAttributes)) }\n\n`
     fileContent += "  /** @returns {FrontendModelResourceConfig} - Resource config. */\n"
     fileContent += "  static resourceConfig() {\n"
     fileContent += "    return {\n"
@@ -522,6 +551,146 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     return content
   }
 
+  /**
+   * Runs write attributes typedef.
+   * @param {object} args - Arguments.
+   * @param {Array<{jsDocType: string, name: string}>} args.attributes - Generated read attributes.
+   * @param {string} args.attributesTypeName - Generated read attributes typedef name.
+   * @param {Array<{attributes: Array<{name: string, type: string}>, relationshipName: string, typeName: string}>} args.nestedWriteTypes - Nested write typedefs.
+   * @param {Array<string | Record<string, ?>>} args.permittedParams - Resource permitted params spec.
+   * @param {string} args.typeName - Typedef name.
+   * @returns {string} - Generated typedef source.
+   */
+  writeAttributesTypedef({attributes, attributesTypeName, nestedWriteTypes, permittedParams, typeName}) {
+    let output = "/**\n"
+
+    output += ` * Attributes accepted by ${typeName}.\n`
+    output += ` * @typedef {object} ${typeName}\n`
+
+    const attributesByName = new Map(attributes.map((attribute) => [attribute.name, attribute]))
+    const nestedWriteTypesByKey = new Map(nestedWriteTypes.map((nestedWriteType) => [`${nestedWriteType.relationshipName}Attributes`, nestedWriteType]))
+
+    for (const entry of permittedParams) {
+      if (typeof entry == "string") {
+        const attribute = attributesByName.get(entry)
+        const type = attribute ? `${attributesTypeName}[${JSON.stringify(attribute.name)}]` : "?"
+
+        output += ` * @property {${type}} [${entry}] - Permitted ${entry} value.\n`
+      } else if (entry && typeof entry == "object" && !Array.isArray(entry)) {
+        for (const key of Object.keys(entry)) {
+          const nestedWriteType = nestedWriteTypesByKey.get(key)
+          const type = nestedWriteType ? `Array<${nestedWriteType.typeName}>` : "Array<Record<string, ?>>"
+
+          output += ` * @property {${type}} [${key}] - Permitted nested ${key} values.\n`
+        }
+      }
+    }
+
+    output += " */\n"
+
+    return output
+  }
+
+  /**
+   * Runs nested write types for model.
+   * @param {object} args - Arguments.
+   * @param {string} args.className - Frontend model class name.
+   * @param {Array<string | Record<string, ?>>} args.permittedParams - Combined permitted params specs.
+   * @param {Array<{autoload: boolean, relationshipName: string, targetClassName: string, targetFileName: string, type: "belongsTo" | "hasOne" | "hasMany"}>} args.relationships - Generated relationships.
+   * @returns {Array<{attributes: Array<{name: string, type: string}>, relationshipName: string, typeName: string}>} - Nested write typedefs.
+   */
+  nestedWriteTypesForModel({className, permittedParams, relationships}) {
+    const relationshipsByName = new Map(relationships.map((relationship) => [relationship.relationshipName, relationship]))
+    const nestedWriteTypesByName = new Map()
+
+    for (const entry of permittedParams) {
+      if (!entry || typeof entry != "object" || Array.isArray(entry)) continue
+
+      for (const key of Object.keys(entry)) {
+        if (!key.endsWith("Attributes")) continue
+        const relationshipName = key.slice(0, -"Attributes".length)
+        const nestedSpec = entry[key]
+        const relationship = relationshipsByName.get(relationshipName)
+        let targetModelClass
+
+        if (relationship) {
+          try {
+            targetModelClass = this.getConfiguration().getModelClass(relationship.targetClassName)
+          } catch {
+            targetModelClass = undefined
+          }
+        }
+
+        if (nestedWriteTypesByName.has(relationshipName)) continue
+
+        nestedWriteTypesByName.set(relationshipName, {
+          attributes: this.nestedWriteAttributesForSpec({nestedSpec, targetModelClass}),
+          relationshipName,
+          typeName: `${className}${inflection.camelize(relationshipName)}NestedAttributes`
+        })
+      }
+    }
+
+    return Array.from(nestedWriteTypesByName.values())
+  }
+
+  /**
+   * Runs nested write attributes for spec.
+   * @param {object} args - Arguments.
+   * @param {?} args.nestedSpec - Nested permit spec.
+   * @param {typeof import("../../../../../database/record/index.js").default | undefined} args.targetModelClass - Target backend model class.
+   * @returns {Array<{name: string, type: string}>} - Nested write attributes.
+   */
+  nestedWriteAttributesForSpec({nestedSpec, targetModelClass}) {
+    if (!Array.isArray(nestedSpec)) return []
+
+    return nestedSpec.filter((entry) => typeof entry == "string").map((attributeName) => {
+      const attributeConfig = this.frontendAttributeConfigForModelAttribute({attributeName, modelClass: targetModelClass})
+
+      return {
+        name: attributeName,
+        type: attributeConfig ? this.jsDocTypeForFrontendAttribute({attributeConfig}) : "?"
+      }
+    })
+  }
+
+  /**
+   * Runs permitted params for generator.
+   * @param {import("../../../../../configuration-types.js").FrontendModelResourceClassType | null} resourceClass - Resource class.
+   * @param {"create" | "update"} action - Write action.
+   * @returns {Array<string | Record<string, ?>>} - Permitted params spec.
+   */
+  permittedParamsForGenerator(resourceClass, action) {
+    if (!resourceClass || typeof resourceClass !== "function") return []
+
+    const prototypeWithMethod = /**
+                                 * Resource prototype.
+                                 * @type {{permittedParams?: (arg?: object) => Array<string | Record<string, ?>>}}
+                                 */ (resourceClass.prototype)
+
+    if (typeof prototypeWithMethod?.permittedParams !== "function") return []
+
+    try {
+      const instance = new resourceClass({
+        ability: undefined,
+        context: {},
+        locals: {},
+        modelClass: resourceClass.ModelClass,
+        modelName: resourceClass.ModelClass?.getModelName?.() || resourceClass.name,
+        params: {},
+        resourceConfiguration: /**
+                                * Resource configuration.
+                                * @type {import("../../../../../configuration-types.js").FrontendModelResourceConfiguration}
+                                */ ({attributes: []})
+      })
+      const spec = instance.permittedParams({action, ability: undefined, locals: {}, params: {}})
+
+      return Array.isArray(spec) ? spec : []
+    } catch (error) {
+      throw new Error(`Failed to invoke ${resourceClass.name}.permittedParams() while generating frontend model write types: ${error instanceof Error ? error.message : String(error)}`, {cause: error})
+    }
+  }
+
   /**
    * Invokes a backend resource's `permittedParams()` instance method at
    * generation time and extracts the relationship names that accept

package/build/frontend-model-controller.js

@@ -218,6 +218,14 @@ function frontendModelClientMessageForError(error) {
     return error.message
   }
 
+  // Validation failures are expected user-flow errors. Always forward the
+  // validation summary so the client shows the real reason (e.g. "Name can't
+  // be blank") instead of the generic "Request failed." message, regardless of
+  // whether the raising code also attached error.velocious metadata.
+  if (error instanceof ValidationError) {
+    return error.message
+  }
+
   if (frontendModelErrorHasVelociousMetadata(error) && error instanceof Error) {
     return error.message
   }
@@ -457,22 +465,45 @@ function frontendModelAttachmentParams(params) {
 /**
  * Extract mutation attributes shared by create and update commands.
  * @param {Record<string, ?>} params - Frontend-model request params.
- * @returns {{attributes: Record<string, ?>, nestedAttributes: Record<string, ?> | null} | string} - Mutation attributes or validation error message.
+ * @returns {{attributes: Record<string, ?>, attachments: Record<string, ?> | null, nestedAttributes: Record<string, ?> | null} | string} - Mutation attributes or validation error message.
  */
 function frontendModelMutationAttributes(params) {
   const attributes = params.attributes
 
-  if (!attributes || typeof attributes !== "object") {
+  if (!isPlainObject(attributes)) {
     return "Expected model attributes."
   }
 
+  /** @type {Record<string, ?>} */
+  const regularAttributes = {}
+  /** @type {Record<string, ?>} */
+  const nestedAttributes = {}
+
+  for (const [attributeName, value] of Object.entries(attributes)) {
+    if (attributeName.endsWith("Attributes")) {
+      const relationshipName = attributeName.slice(0, -"Attributes".length)
+
+      if (!relationshipName) return `Invalid nested attributes key: ${attributeName}`
+      nestedAttributes[relationshipName] = value
+    } else {
+      regularAttributes[attributeName] = value
+    }
+  }
+
+  if (params.nestedAttributes !== undefined) {
+    if (!isPlainObject(params.nestedAttributes)) return "Expected nestedAttributes to be an object."
+
+    Object.assign(nestedAttributes, params.nestedAttributes)
+  }
+
+  if (params.attachments !== undefined && !isPlainObject(params.attachments)) {
+    return "Expected attachments to be an object."
+  }
+
   return {
-    attributes,
-    nestedAttributes: params.nestedAttributes && typeof params.nestedAttributes === "object"
-      ? /**
-         * Types the following value.
-          @type {Record<string, ?>} */ (params.nestedAttributes)
-      : null
+    attributes: regularAttributes,
+    attachments: params.attachments === undefined ? null : params.attachments,
+    nestedAttributes: Object.keys(nestedAttributes).length > 0 ? nestedAttributes : null
   }
 }
 
@@ -1028,11 +1059,12 @@ export default class FrontendModelController extends Controller {
    * Runs frontend model create record.
    * @param {Record<string, ?>} attributes - Create attributes.
    * @param {Record<string, ?> | null} [nestedAttributes] - Optional nested-attribute payload for cascading writes.
+   * @param {Record<string, ?> | null} [attachments] - Optional attachment payloads keyed by attachment name.
    * @returns {Promise<import("./database/record/index.js").default | null>} - Created model when authorized.
    */
-  async frontendModelCreateRecord(attributes, nestedAttributes = null) {
+  async frontendModelCreateRecord(attributes, nestedAttributes = null, attachments = null) {
     const resource = this.frontendModelResourceInstance()
-    const model = await resource.create(attributes, {nestedAttributes, controller: this})
+    const model = await resource.create(attributes, {attachments, nestedAttributes, controller: this})
 
     const authorizedModels = await this.frontendModelFilterAuthorizedModels({action: "create", models: [model]})
 
@@ -2827,6 +2859,24 @@ export default class FrontendModelController extends Controller {
       model: resolvedModel,
       requestId
     }])
+
+    // Surface genuinely unexpected backend failures on the framework-error
+    // channel so process-level bug reporters capture them, instead of the
+    // controller silently swallowing them behind the generic "Request
+    // failed." client message. Developer-annotated user-flow errors
+    // (`error.velocious` metadata — handled by the early return above),
+    // validation errors, and deliberately client-safe VelociousErrors are
+    // expected and must NOT be reported as framework errors.
+    if (!(error instanceof ValidationError) && !(error instanceof VelociousError && error.safeToExpose)) {
+      const errorPayload = {
+        context: {action, commandType, frontendModelEndpoint: true, model: resolvedModel, requestId},
+        error: error instanceof Error ? error : new Error(String(error)),
+        request: this.getRequest()
+      }
+
+      this.getConfiguration().getErrorEvents().emit("framework-error", errorPayload)
+      this.getConfiguration().getErrorEvents().emit("all-error", {...errorPayload, errorType: "framework-error"})
+    }
   }
 
   /**
@@ -2917,7 +2967,11 @@ export default class FrontendModelController extends Controller {
       const mutationAttributes = frontendModelMutationAttributes(params)
       if (typeof mutationAttributes === "string") return this.frontendModelErrorPayload(mutationAttributes)
 
-      const model = await this.frontendModelCreateRecord(mutationAttributes.attributes, mutationAttributes.nestedAttributes)
+      const model = await this.frontendModelCreateRecord(
+        mutationAttributes.attributes,
+        mutationAttributes.nestedAttributes,
+        mutationAttributes.attachments
+      )
 
       if (!model) {
         return this.frontendModelErrorPayload(`${modelClass.name} not found.`)
@@ -3030,7 +3084,11 @@ export default class FrontendModelController extends Controller {
         return this.frontendModelErrorPayload(`${modelClass.name} not found.`)
       }
 
-      const updatedModel = await resource.update(model, mutationAttributes.attributes, {nestedAttributes: mutationAttributes.nestedAttributes, controller: this})
+      const updatedModel = await resource.update(model, mutationAttributes.attributes, {
+        attachments: mutationAttributes.attachments,
+        controller: this,
+        nestedAttributes: mutationAttributes.nestedAttributes
+      })
       const serializedModel = await resource.serialize(updatedModel, "update")
 
       return frontendModelSerializedModelSuccess(serializedModel)