velocious 1.0.577 → 1.0.578

package/README.md

@@ -22,7 +22,7 @@
 * Gap-less positional lists with automatic reordering via `actsAsList`, including models with numeric, string, or UUID primary keys (see [docs/acts-as-list.md](docs/acts-as-list.md))
 * Rails-style nested-attribute writes on frontend-model `save()` (see [docs/nested-attributes.md](docs/nested-attributes.md))
 * Async-aware test-data factories with inherited traits, graph-first native association autosave, metadata-aware override precedence, callbacks, sequences, and linting (see [docs/factories.md](docs/factories.md))
-* Per-row association counts via `.withCount(...)`, including safe batching of structurally identical aggregates, on frontend and backend queries (see [docs/with-count.md](docs/with-count.md))
+* Per-row association counts via `.withCount(...)`, including cohort-safe intersected filters and safe batching of structurally identical aggregates, on frontend and backend queries (see [docs/with-count.md](docs/with-count.md))
 * Consumer-defined per-row SQL aggregates/computations via `.queryData(...)`, with compatible projections sharing a roundtrip while preserving declared alias-overwrite order, on frontend and backend queries (see [docs/query-data.md](docs/query-data.md))
 * Per-record ability checks via `.abilities(...)` on frontend queries + `record.can(action)` (see [docs/abilities.md](docs/abilities.md))
 * Translated model attributes with current-locale relationship sorting (see [docs/translations.md](docs/translations.md))
@@ -741,7 +741,7 @@ Use `await FrontendModelBase.waitForIdle()` when a test harness or app lifecycle
 
 Frontend-model HTTP requests always use `credentials: "include"` so shared custom commands can set session cookies without app-level transport overrides.
 
-Unexpected frontend-model endpoint failures stay client-safe in production with `errorMessage: "Request failed."`.
+Unexpected frontend-model endpoint failures stay client-safe in production with `errorType: "internal_error"`, `errorMessage: "Request failed."`, and a server-generated `correlationId` shared with the matching framework-error report. Expected application failures can use `VelociousError.safe(message, {errorType, details, code})`; generated frontend-model callers preserve the server's safe error fields. See [docs/frontend-models.md](docs/frontend-models.md#error-payloads).
 Invalid client query descriptors, such as unknown `select`, `where`, `search`, `joins`, `preload`, `group`, `sort`, `pluck`, or Ransack attributes, return the specific frontend-model query error message with `velocious.code: "frontend-model-query-error"` and are not emitted as framework errors.
 Invalid frontend-model write attributes and attachment names, including attributes rejected by `permittedParams()`, return the specific safe error message with `velocious.code: "frontend-model-attribute-error"` and are not emitted as framework errors.
 In `development` and `test`, Velocious also includes `debugErrorClass`, `debugErrorMessage`, and `debugBacktrace` fields so browser/system-test failures are easier to diagnose without exposing those details in production.
@@ -934,7 +934,8 @@ Translated models also get a `currentTranslation` `hasOne` relationship scoped t
 
 Async class APIs initialize record metadata on first use when a model has not
 already been initialized eagerly. See [docs/model-initialization.md](docs/model-initialization.md)
-for the eager and lazy initialization behavior.
+for the eager and lazy initialization behavior, including atomic shared bootstrap
+and complete recovery after an eager initialization failure.
 
 ## Lifecycle callbacks
 
@@ -1347,7 +1348,7 @@ If you need to regenerate missing structure files without rerunning migrations,
 npx velocious db:schema:dump
 ```
 
-`db:schema:dump` generates a structure SQL file for each configured database identifier under `db/structure-<identifier>.sql`. It only writes files when one or more expected files are missing. The generated file includes the full DDL (tables, indexes, views, triggers, etc.) followed by `INSERT INTO schema_migrations (version) VALUES (...)` for every currently applied migration version. This preserves the migration ledger in the checked-in snapshot so fresh databases loaded from it do not re-run migrations that already shaped the schemas in the file.
+`db:schema:dump` generates a structure SQL file for each configured database identifier under `db/structure-<identifier>.sql`. It only writes files when one or more expected files are missing. The generated file includes the full DDL (tables, indexes, views, triggers, etc.) followed by `INSERT INTO schema_migrations (version) VALUES (...)` for every currently applied migration version. MySQL and MariaDB dumps place same-schema referenced base tables before their dependent tables. The migration ledger preserves applied versions in the checked-in snapshot so fresh databases loaded from it do not re-run migrations that already shaped the schemas in the file.
 
 If you need to load the checked-in structure files for each configured database, use:
 
@@ -1857,7 +1858,7 @@ 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`), invalid client query descriptors are returned as frontend-model query errors, and `error.velocious`-annotated / `safeToExpose` / `errorType`-marked errors keep their expected-error status — none of these reach the error bus.
+Genuinely unexpected frontend-model command failures reach this bus too. The frontend-model controller catches them to return a client-safe `internal_error` response with `Request failed.` and a correlation ID, then emits them as `framework-error`/`all-error` with the same correlation ID and `context.frontendModelEndpoint === true`. Expected user-flow errors are excluded: validation failures are forwarded with their real message (for example `Name can't be blank`), invalid client query descriptors are returned as frontend-model query errors, and `error.velocious`-annotated / `safeToExpose` errors keep their expected-error status. A raw `errorType` property alone is not considered safe and does not suppress reporting.
 
 Unexpected inbound decoded WebSocket dispatch failures emit one `framework-error` and one matching `all-error`. Established expected client-flow errors remain excluded from both events.
 
@@ -2226,6 +2227,11 @@ VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS=5400000
 
 New jobs default to `executionMode: "pooled"`: a worker runs them in warm, reusable Node child runners. `pooledRunnerCount` (default: `4`) bounds this independent per-worker pool, and `pooledRunnerConcurrency` (default: `1`) sets how many jobs each child runs at once on its own event loop, so total pooled capacity is `pooledRunnerCount × pooledRunnerConcurrency` — raise concurrency for I/O-bound jobs to get high throughput from a bounded, isolated set of processes. `pooledRunnerCount`, `pooledRunnerConcurrency`, and `pooledRunnerMaxJobs` must be finite positive integers; the RSS and lifetime limits must be finite positive numbers. A child is recycled after an acknowledged job when it reaches `pooledRunnerMaxJobs` (default: `100`), `pooledRunnerMaxRssBytes` (default: `536870912`, or 512 MiB), or `pooledRunnerMaxLifetimeMs` (default: `3600000`, or one hour). `execution_mode` is the single source of truth for a job's runtime — pooled rows persist as `execution_mode = "pooled"` directly. See [execution modes and pooled runners](docs/background-jobs.md#execution-modes-and-pooled-runners).
 
+Cold pooled jobs share one atomic model-bootstrap phase. If that phase fails, all
+waiting jobs receive the failure; a later job in the surviving child cannot run
+until a complete model-initialization phase succeeds. The pool's configured
+concurrency and per-job connection scopes are unchanged.
+
 `maxConcurrentForkedJobs` (default: `4`) caps how many out-of-process `executionMode: "forked"` or `executionMode: "spawned"` jobs one worker may keep in flight. Forked jobs use `child_process.fork()` with an attached IPC channel. After the main process acknowledges their durable status report, forked and spawned one-shot runners exit without waiting for graceful Beacon/database teardown; the OS closes their process-owned resources. A missing or rejected status acknowledgement makes the runner exit as failed instead of reporting clean success. Spawned jobs use the legacy `background-jobs-runner` CLI process via `child_process.spawn()` and are only for callers that intentionally want that spawned behavior.
 
 `jobTimeoutMs` (or `VELOCIOUS_BACKGROUND_JOBS_JOB_TIMEOUT_MS`, milliseconds; default: disabled) is a wall-clock backstop for `"forked"` and `"pooled"` jobs. A job still running after the timeout is terminated (`SIGTERM`, then `SIGKILL` after the reaping grace) and reported `failed`, so a genuinely-hung job can't pin a worker's capacity — and its whole-app boot and DB connections — indefinitely (notably a retired-release worker draining after a deploy). For a **pooled** job the whole child running it is killed, so its concurrent in-flight siblings on that child are also reported `failed` and requeued — a hung JS job can't be cancelled any other way — before a replacement child is spawned. It's a coarse safety net, not per-job tuning: it applies to every forked and pooled job, so set it well above the longest legitimate job. Omit it, or set `null`/`<= 0`, to disable. `"inline"` jobs are not covered — they share the worker's process and can't be killed without killing the worker. See [docs/background-jobs.md](docs/background-jobs.md#job-timeout-hung-runner-backstop).

package/build/background-jobs/main.js

@@ -786,9 +786,9 @@ export default class BackgroundJobsMain {
         options: message.options || {}
       })
 
-      jsonSocket.send({type: "schedule-replaced", ...result})
       this._notifyEnqueued()
       await this._drain()
+      jsonSocket.send({type: "schedule-replaced", ...result})
     } catch (error) {
       this._handleClientMutationError({
         context: {jobName: message.jobName, scheduleKey: message.scheduleKey, stage: "background-job-replace-scheduled"},
@@ -812,9 +812,9 @@ export default class BackgroundJobsMain {
     try {
       const result = await this.store.cancelScheduled(message.scheduleKey)
 
-      jsonSocket.send({type: "schedule-cancelled", ...result})
       this._notifyEnqueued()
       await this._drain()
+      jsonSocket.send({type: "schedule-cancelled", ...result})
     } catch (error) {
       this._handleClientMutationError({
         context: {scheduleKey: message.scheduleKey, stage: "background-job-cancel-scheduled"},

package/build/configuration-types.js

@@ -312,6 +312,7 @@
  * @property {string} controller - Controller class name.
  * @property {string} [action] - Controller action or endpoint label.
  * @property {"index" | "find" | "create" | "update" | "destroy" | "attach" | "attachmentList" | "download" | "url" | "custom-command"} [commandType] - Frontend-model command type.
+ * @property {string} [correlationId] - Server-generated identifier shared by an unexpected client error and framework reports.
  * @property {boolean} [expectedError] - Whether the error is an expected user-flow failure.
  * @property {boolean} [frontendModelEndpoint] - Whether the error came from the frontend-model endpoint.
  * @property {string} [model] - Frontend-model name from the failed request.

package/build/configuration.js

@@ -286,6 +286,19 @@ export default class VelociousConfiguration {
     }
 
     this._isInitialized = false
+    this._modelsInitialized = false
+    /**
+     * Invalidates model phases that started before database connections closed.
+     * @type {number}
+     */
+    this._modelInitializationGeneration = 0
+    /**
+     * In-progress `initializeModels()` promise. Model initialization is an
+     * atomic bootstrap phase: concurrent callers share it, and a rejection
+     * leaves the phase eligible for a later complete attempt.
+     * @type {Promise<void> | undefined}
+     */
+    this._initializeModelsPromise = undefined
     /**
      * In-progress `initialize()` promise, memoized so concurrent callers await
      * the same bootstrap. Reset to undefined if initialization fails.
@@ -2020,25 +2033,39 @@ export default class VelociousConfiguration {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async initializeModels(args = {type: "server"}) {
-    if (!this._modelsInitialized) {
-      this._modelsInitialized = true
+    if (this._modelsInitialized) return
+    if (this._initializeModelsPromise) return await this._initializeModelsPromise
 
+    const modelInitializationGeneration = this._modelInitializationGeneration
+    const initializeModelsPromise = (async () => {
       const shouldSkipDummyModelInitialization = process.env.VELOCIOUS_SKIP_DUMMY_MODEL_INITIALIZATION === "1"
         && process.env.VELOCIOUS_BROWSER_TESTS === "true"
         && this.getEnvironment() === "test"
 
-      if (shouldSkipDummyModelInitialization) {
-        return
+      if (!shouldSkipDummyModelInitialization) {
+        if (this._initializeModels) {
+          await this._initializeModels({configuration: this, type: args.type})
+        }
+
+        await this.getEnvironmentHandler().initializePackageModels(this)
+        await initializeAuditedModelRelationships(this)
+
+        await this.getEnvironmentHandler().initializeFrontendModelWebsocketPublishers(this)
       }
 
-      if (this._initializeModels) {
-        await this._initializeModels({configuration: this, type: args.type})
+      if (this._modelInitializationGeneration === modelInitializationGeneration) {
+        this._modelsInitialized = true
       }
+    })()
 
-      await this.getEnvironmentHandler().initializePackageModels(this)
-      await initializeAuditedModelRelationships(this)
+    this._initializeModelsPromise = initializeModelsPromise
 
-      await this.getEnvironmentHandler().initializeFrontendModelWebsocketPublishers(this)
+    try {
+      await initializeModelsPromise
+    } finally {
+      if (this._initializeModelsPromise === initializeModelsPromise) {
+        this._initializeModelsPromise = undefined
+      }
     }
   }
 
@@ -2073,6 +2100,12 @@ export default class VelociousConfiguration {
 
     this._initializePromise = (async () => {
       await this.initializeModels({type})
+
+      // Model initialization can be invalidated by a concurrent connection close.
+      // If models are not ready, stop without marking the configuration initialized
+      // so the next caller retries a full bootstrap.
+      if (!this._modelsInitialized) return
+
       await this.getEnvironmentHandler().autoDiscoverResources(this)
       this._mergeDiscoveredAbilityResources()
       this._validateResourceRelationshipsOnModels()
@@ -2104,6 +2137,13 @@ export default class VelociousConfiguration {
       this._initializePromise = undefined
       throw error
     }
+
+    // If the inner IIFE returned without marking the configuration initialized
+    // (e.g. because models were invalidated mid-bootstrap), clear the promise so
+    // a later call retries a full bootstrap.
+    if (!this._isInitialized) {
+      this._initializePromise = undefined
+    }
   }
 
   /**
@@ -3244,8 +3284,10 @@ export default class VelociousConfiguration {
           PoolClass.clearGlobalConnections(this)
         }
 
-        // Allow models to be re-initialized after connections are closed.
+        // Allow full re-initialization after connections are closed.
+        this._modelInitializationGeneration += 1
         this._modelsInitialized = false
+        this._isInitialized = false
       }
     })()
 

package/build/database/drivers/mysql/structure-sql.js

@@ -20,6 +20,9 @@ export default class VelociousDatabaseDriversMysqlStructureSql {
     const {driver} = this
     const isMariaDb = await this._isMariaDb()
     const rows = await driver.query("SELECT table_name, table_type FROM information_schema.tables WHERE table_schema = DATABASE() ORDER BY table_type, table_name")
+    const foreignKeyRows = await driver.query("SELECT table_name, referenced_table_name FROM information_schema.key_column_usage WHERE table_schema = DATABASE() AND referenced_table_schema = DATABASE() AND referenced_table_name IS NOT NULL")
+    const baseTableNames = []
+    const views = []
     const statements = []
 
     for (const row of rows) {
@@ -31,24 +34,82 @@ export default class VelociousDatabaseDriversMysqlStructureSql {
       if (!tableName || !tableType) continue
 
       if (tableType == "BASE TABLE") {
-        const createRows = await driver.query(`SHOW CREATE TABLE ${driver.quoteTable(tableName)}`)
-        const rawCreateStatement = this._mysqlCreateStatement(createRows?.[0])
-        const createStatement = rawCreateStatement ? this._stripAutoIncrement(rawCreateStatement) : null
-
-        if (createStatement) statements.push(normalizeSqlStatement(createStatement))
+        baseTableNames.push(tableName)
       } else if (tableType == "VIEW" || (isMariaDb && tableType == "SYSTEM VIEW")) {
-        const createRows = await driver.query(`SHOW CREATE VIEW ${driver.quoteTable(tableName)}`)
-        const createStatement = this._mysqlCreateStatement(createRows?.[0])
-
-        if (createStatement) statements.push(normalizeSqlStatement(createStatement))
+        views.push(tableName)
       }
     }
 
+    for (const tableName of this._orderBaseTables({foreignKeyRows, tableNames: baseTableNames})) {
+      const createRows = await driver.query(`SHOW CREATE TABLE ${driver.quoteTable(tableName)}`)
+      const rawCreateStatement = this._mysqlCreateStatement(createRows?.[0])
+      const createStatement = rawCreateStatement ? this._stripAutoIncrement(rawCreateStatement) : null
+
+      if (createStatement) statements.push(normalizeSqlStatement(createStatement))
+    }
+
+    for (const tableName of views) {
+      const createRows = await driver.query(`SHOW CREATE VIEW ${driver.quoteTable(tableName)}`)
+      const createStatement = this._mysqlCreateStatement(createRows?.[0])
+
+      if (createStatement) statements.push(normalizeSqlStatement(createStatement))
+    }
+
     if (statements.length == 0) return null
 
     return `${statements.join("\n\n")}\n`
   }
 
+  /**
+   * Orders tables so referenced tables are created before their dependents.
+   * @param {object} args - Options object.
+   * @param {Array<Record<string, ?>>} args.foreignKeyRows - Foreign key metadata rows.
+   * @param {string[]} args.tableNames - Base table names in their existing order.
+   * @returns {string[]} - Ordered table names.
+   */
+  _orderBaseTables({foreignKeyRows, tableNames}) {
+    const pendingTableNames = new Set(tableNames)
+    /** @type {Record<string, Set<string>>} */
+    const dependenciesByTableName = {}
+    const orderedTableNames = []
+
+    for (const tableName of tableNames) {
+      dependenciesByTableName[tableName] = new Set()
+    }
+
+    for (const row of foreignKeyRows) {
+      const tableNameValue = row.table_name || row.TABLE_NAME
+      const referencedTableNameValue = row.referenced_table_name || row.REFERENCED_TABLE_NAME
+      const tableName = tableNameValue ? String(tableNameValue) : ""
+      const referencedTableName = referencedTableNameValue ? String(referencedTableNameValue) : ""
+
+      if (tableName == referencedTableName || !pendingTableNames.has(tableName) || !pendingTableNames.has(referencedTableName)) continue
+
+      dependenciesByTableName[tableName].add(referencedTableName)
+    }
+
+    while (pendingTableNames.size > 0) {
+      const nextTableName = tableNames.find((tableName) => {
+        if (!pendingTableNames.has(tableName)) return false
+
+        return Array.from(dependenciesByTableName[tableName]).every((dependencyTableName) => !pendingTableNames.has(dependencyTableName))
+      })
+
+      if (!nextTableName) {
+        for (const tableName of tableNames) {
+          if (pendingTableNames.has(tableName)) orderedTableNames.push(tableName)
+        }
+
+        break
+      }
+
+      orderedTableNames.push(nextTableName)
+      pendingTableNames.delete(nextTableName)
+    }
+
+    return orderedTableNames
+  }
+
   /**
    * Runs is maria db.
    * @returns {Promise<boolean>} - Resolves with Whether maria db.

package/build/database/query/with-count.js

@@ -161,22 +161,22 @@ function queryForEntry({entry, modelClass, parentIds, sourceModel}) {
 
   const foreignKey = relationship.getForeignKey()
   /**
-   * Where conditions.
+   * Mandatory cohort conditions.
    * @type {Record<string, ?>} */
-  const whereConditions = {[foreignKey]: parentIds}
+  const mandatoryWhereConditions = {[foreignKey]: parentIds}
 
   if (relationship.getPolymorphic && relationship.getPolymorphic()) {
     const typeColumn = relationship.getPolymorphicTypeColumn()
-    whereConditions[typeColumn] = modelClass.getModelName()
-  }
-
-  if (entry.where) {
-    Object.assign(whereConditions, entry.where)
+    mandatoryWhereConditions[typeColumn] = modelClass.getModelName()
   }
 
   const baseQuery = sourceModel.queryForModel(targetModelClass)
   baseQuery._forceQualifyBaseTable = true
-  baseQuery.where(whereConditions)
+  baseQuery.where(mandatoryWhereConditions)
+
+  if (entry.where) {
+    baseQuery.where(entry.where)
+  }
 
   const countQuery = relationship.applyScope(baseQuery)
 

package/build/database/record/record-not-found-error.js

@@ -1,3 +1,4 @@
 // @ts-check
 
+/** Backend missing-record error whose diagnostic message stays server-side. */
 export default class RecordNotFoundError extends Error {}