velocious 1.0.576 → 1.0.578

package/README.md

@@ -9,6 +9,7 @@
 * Declarative state machines for models, with typed event methods generated into the base model (see [docs/state-machine.md](docs/state-machine.md))
 * Migrations for schema changes and UTC datetime storage (see [docs/database-migrations.md](docs/database-migrations.md))
 * External packages (engines) that contribute data models, frontend-model resources and migrations to a consuming app (see [docs/packages.md](docs/packages.md))
+* Optional Rampway-owned durable deployment control plane mounted through the standard routes DSL on Velocious 1.0.577 or newer (see [docs/rampway-integration.md](docs/rampway-integration.md))
 * Controllers and views for HTTP endpoints
 * Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, with structured per-attribute validation error responses and one-budget WebSocket startup controls (see [docs/frontend-models.md](docs/frontend-models.md) and [docs/websocket-channels.md](docs/websocket-channels.md))
 * Client-side offline sync mutation logs and frontend-model optimistic queueing primitives (see the [shared-resource sync developer guide](docs/shared-resource-sync-guide.md) and [offline sync architecture](docs/offline-sync.md))
@@ -21,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))
@@ -30,7 +31,6 @@
 * Default-on buffered HTTP response compression with Brotli/gzip content negotiation, global and per-response opt-outs, and HEAD-correct representation headers (see [docs/http-server.md](docs/http-server.md#response-compression))
 * Background jobs with failure events for production reporting and authorized database-scoped dashboard count snapshots/deltas (see [docs/background-jobs.md](docs/background-jobs.md) and [docs/background-jobs-dashboard.md](docs/background-jobs-dashboard.md))
 * Durable one-off background-job scheduling with exact epoch timestamps (see [docs/scheduled-background-job-enqueue.md](docs/scheduled-background-job-enqueue.md))
-* Mountable authenticated callable deployment API with allowlisted projects/stages, immutable-revision validation, idempotent runs, duplicate-safe interruption reconciliation, and adapter-owned execution for integrations like Rampway (see [docs/deployment-api.md](docs/deployment-api.md))
 * Rails-style request and database query logging (see [docs/logging.md](docs/logging.md))
 * EJS-backed mailers with delivery, queueing, and payload rendering support (see [docs/mailers.md](docs/mailers.md))
 * Trusted reverse proxy handling for `request.remoteAddress()` (see [docs/trusted-proxies.md](docs/trusted-proxies.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.
@@ -869,6 +869,51 @@ Supported route helpers:
 - `routes.get(path, {to: [ControllerClass, "action"], params?})`
 - `routes.post(path, {to: [ControllerClass, "action"], params?})`
 
+## Rampway deployment control plane
+
+Applications can install `rampway@^0.4.0` and mount its package-owned Velocious
+control plane through the existing routes DSL. Keep bearer tokens in backend
+secrets and provide explicit allowlisted config paths and release branches:
+
+```sh
+npm install rampway@^0.4.0 velocious@^1.0.577
+```
+
+Rampway 0.4.0 declares `velocious ^1.0.574` as its peer range, but applications
+mounting this API must use Velocious 1.0.577 or newer. Versions 1.0.574 through
+1.0.576 attempted an app-local controller import before the package-supplied
+`controllerClass`, allowing a same-named app controller to shadow Rampway's
+authenticated controller.
+
+```js
+import RampwayDeploymentApi from "rampway/velocious"
+import deploymentSecrets from "./secrets/deployments.js"
+
+routes.draw((route) => {
+  route.mount(RampwayDeploymentApi, {
+    accessTokens: deploymentSecrets.rampwayAccessTokens,
+    at: "/rampway/deployments",
+    projects: {
+      "my-app": {
+        stages: {
+          production: {
+            configPath: "/srv/my-app/control/rampway.config.mjs",
+            releaseBranch: "main"
+          }
+        }
+      }
+    },
+    workerBootstrapPath: "/srv/my-app/control/rampway-velocious-worker.mjs"
+  })
+})
+```
+
+Rampway owns authentication, deployment execution, idempotency, durable runs,
+audits, reconciliation, and the detached worker. Velocious supplies its normal
+route, request, error-event, and database abstractions. See
+[docs/rampway-integration.md](docs/rampway-integration.md) for bootstrap,
+persistence, security, and rollback requirements.
+
 
 ```js
 import Record from "velocious/build/src/database/record/index.js"
@@ -889,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
 
@@ -1302,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:
 
@@ -1812,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.
 
@@ -2181,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"},
@@ -1354,9 +1354,20 @@ export default class BackgroundJobsMain {
     if (this.dispatchStrategy === "polling") return
 
     const next = await this.store.nextScheduledJob()
-    if (!next || typeof next.scheduledAtMs !== "number") return
+    let delay
+
+    if (next && typeof next.scheduledAtMs === "number") {
+      delay = Math.max(0, Math.min(next.scheduledAtMs - Date.now(), MAX_TIMER_MS))
+    }
+
+    // `nextScheduledJob` only returns future jobs, so a job that became
+    // eligible after the drain's eligible-job probe is invisible to it. If one
+    // is dispatchable now, arm a 0-delay re-drain so it is dispatched
+    // immediately instead of being stranded until the next future timer (or
+    // external signal) fires.
+    if (await this.nextAvailableJobForReadyWorkers()) delay = 0
 
-    const delay = Math.max(0, Math.min(next.scheduledAtMs - Date.now(), MAX_TIMER_MS))
+    if (typeof delay !== "number") return
 
     this._scheduledTimer = setTimeout(() => {
       this._scheduledTimer = undefined

package/build/background-jobs/scheduler.js

@@ -81,8 +81,8 @@ export default class BackgroundJobsScheduler {
      * Narrows the runtime value to the documented type.
      * @type {Array<ReturnType<typeof setTimeout>>} */
     this.timeoutIds = []
-    /** @type {Set<Promise<void>>} - Scheduled enqueues that shutdown must drain. */
-    this.pendingEnqueues = new Set()
+    /** @type {Map<string, Promise<void>>} - In-flight scheduled enqueues by schedule key that shutdown must drain. */
+    this.pendingEnqueuesByJobKey = new Map()
     /**
      * Narrows the runtime value to the documented type.
      * @type {boolean} - True between stop() and the next start(); cron self-rescheduler checks this so a stop() during an in-flight enqueue doesn't immediately re-arm.
@@ -131,7 +131,7 @@ export default class BackgroundJobsScheduler {
     this.intervalIds = []
     this.timeoutIds = []
 
-    await Promise.all(this.pendingEnqueues)
+    await Promise.all(this.pendingEnqueuesByJobKey.values())
   }
 
   /**
@@ -181,13 +181,15 @@ export default class BackgroundJobsScheduler {
     }
 
     const timeoutId = setTimeout(() => {
-      void this.runScheduledJob({jobConfiguration, jobKey})
+      const scheduledEnqueue = this.runScheduledJob({jobConfiguration, jobKey})
 
       const intervalId = setInterval(() => {
-        void this.runScheduledJob({jobConfiguration, jobKey})
+        return this.runScheduledJob({jobConfiguration, jobKey})
       }, intervalMs)
 
       this.intervalIds.push(intervalId)
+
+      return scheduledEnqueue
     }, firstInMs)
 
     this.timeoutIds.push(timeoutId)
@@ -242,13 +244,15 @@ export default class BackgroundJobsScheduler {
    * @returns {Promise<void>} - Resolves after the enqueue attempt finishes.
    */
   async runScheduledJob({jobConfiguration, jobKey}) {
+    if (this.stopped || this.pendingEnqueuesByJobKey.has(jobKey)) return
+
     const pendingEnqueue = this.enqueueScheduledJob({jobConfiguration, jobKey})
-    this.pendingEnqueues.add(pendingEnqueue)
+    this.pendingEnqueuesByJobKey.set(jobKey, pendingEnqueue)
 
     try {
       await pendingEnqueue
     } finally {
-      this.pendingEnqueues.delete(pendingEnqueue)
+      this.pendingEnqueuesByJobKey.delete(jobKey)
     }
   }
 

package/build/background-jobs/store.js

@@ -77,7 +77,8 @@ const SORTABLE_COLUMNS = {
 
 /**
  * Serializes concurrent `_applySchema` runs within THIS process, keyed by database
- * identifier. Two stores that share one connection (SingleMultiUse / SQLite)
+ * identifier, before callers without an existing connection check one out. Two
+ * stores that share one connection (SingleMultiUse / SQLite)
  * otherwise interleave the multi-step table rebuild and corrupt it (the jobs table
  * is left as its `*_velocious_rebuild` temp). A DB advisory lock can't fix that: on
  * a session-scoped / re-entrant driver (MySQL `GET_LOCK`) a second acquire on the
@@ -1059,22 +1060,17 @@ export default class BackgroundJobsStore {
    * @returns {Promise<void>} - Resolves when the schema is present.
    */
   async _ensureSchema(existingDb) {
-    if (existingDb) {
-      await this._applySchema(existingDb)
-
-      return
-    }
-
-    await this._withDb((db) => this._applySchema(db))
+    await this._applySchema(existingDb)
   }
 
   /**
-   * Creates or upgrades the background-jobs tables, columns and concurrency rows on
-   * the given connection.
-   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * Serializes creation or upgrade of the background-jobs schema, checking out a
+   * connection only after earlier schema work has completed when one is not supplied.
+   * @param {import("../database/drivers/base.js").default} [existingDb] - Caller-owned
+   *   database connection.
    * @returns {Promise<void>} - Resolves when the schema is present.
    */
-  async _applySchema(db) {
+  async _applySchema(existingDb) {
     // Serialize concurrent schema applies within this process, keyed by database
     // identifier (see `schemaApplyChains`). The per-step locks inside the steps use
     // DIFFERENT lock names, so two concurrent callers could otherwise each hold a
@@ -1084,7 +1080,16 @@ export default class BackgroundJobsStore {
     // the second caller then re-checks and finds every step already done.
     const identifier = this.getDatabaseIdentifier() ?? "default"
     const previous = schemaApplyChains.get(identifier) ?? Promise.resolve()
-    const run = previous.then(() => this._applySchemaSteps(db), () => this._applySchemaSteps(db))
+    const applyWithConnection = async () => {
+      if (existingDb) {
+        await this._applySchemaSteps(existingDb)
+
+        return
+      }
+
+      await this._withDb((db) => this._applySchemaSteps(db))
+    }
+    const run = previous.then(applyWithConnection, applyWithConnection)
 
     // Keep the chain alive regardless of this run's outcome so one failed apply does
     // not wedge later callers; this run still propagates its own result/error.

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 {}

package/build/environment-handlers/node/cli/commands/test.js

@@ -6,9 +6,11 @@ import TestFilesFinder from "../../../../testing/test-files-finder.js"
 import TestRunner from "../../../../testing/test-runner.js"
 import TestSuiteSplitter from "../../../../testing/test-suite-splitter.js"
 import {normalizeExamplePatterns, parseFilters} from "../../../../testing/test-filter-parser.js"
+import {prepareSourcePeerPackage} from "../../source-peer-package.js"
 
 export default class VelociousCliCommandsTest extends BaseCommand {
   async execute() {
+    await prepareSourcePeerPackage()
     this.getConfiguration().setEnvironment("test")
 
     let directory