velocious 1.0.559 → 1.0.561

package/README.md

@@ -20,8 +20,8 @@
 * Gap-less positional lists with automatic reordering via `actsAsList` (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(...)` on frontend and backend queries (see [docs/with-count.md](docs/with-count.md))
-* Consumer-defined per-row SQL aggregates/computations via `.queryData(...)` on frontend and backend queries (see [docs/query-data.md](docs/query-data.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))
+* 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))
 * Cross-process broadcast bus for `broadcastToChannel` via `velocious beacon`, including background job runner processes (see [docs/beacon.md](docs/beacon.md))
@@ -34,6 +34,7 @@
 * In-process driver schema metadata caching (see [docs/schema-metadata-cache.md](docs/schema-metadata-cache.md))
 * Planned local-first shared-resource sync architecture (see [docs/offline-sync.md](docs/offline-sync.md))
 * Selective named database connection checkouts, bounded pool waits, and debugging held connections (see [docs/database-connections.md](docs/database-connections.md))
+* AbortSignal-driven MySQL/MariaDB query cancellation for raw, model, and cross-tenant aggregate queries (see [docs/database-query-cancellation.md](docs/database-query-cancellation.md))
 * Optional built-in debug endpoint for inspecting server and database connection state (see [docs/debug-endpoint.md](docs/debug-endpoint.md))
 * Optional built-in API manifest endpoint describing every registered frontend-model resource as human- and machine-readable JSON (see [docs/api-manifest-endpoint.md](docs/api-manifest-endpoint.md))
 
@@ -59,6 +60,8 @@ npm run test
 npm run test:expo
 ```
 
+Maintainers cutting a package release must follow the [Velocious release runbook](docs/releasing.md); `npm run release:patch` commits, pushes, and publishes rather than acting as a local-only version command.
+
 # Code quality (fallow)
 
 [fallow](https://github.com/fallow-rs/fallow) analyzes the codebase for unused/dead code, duplication, and complexity. CI runs it as a **regression gate**: it fails only on findings beyond the committed baseline in `fallow-baselines/`, so existing backlog never blocks a PR but new issues do.
@@ -1565,6 +1568,8 @@ database: {
 
 Velocious includes a lightweight websocket entry point for API-style calls and server-side events.
 
+Inbound frames remain ordered when TCP splits a frame across reads. Velocious limits a single final client data frame and a reassembled fragmented message to 16 MiB; larger payloads close the connection. See [WebSocket connections](docs/websocket-connections.md) for wire-protocol details.
+
 ## Connect and call a controller
 
 ```js

package/build/background-jobs/worker.js

@@ -193,8 +193,11 @@ export default class BackgroundJobsWorker {
     this.inflightPooledJobs = new Set()
     /** @type {Set<import("node:child_process").ChildProcess>} */
     this.pooledChildren = new Set()
-    /** @type {Map<import("node:child_process").ChildProcess, {createdAtMs: number, jobsRun: number, inflight: Map<string, {payload: import("./types.js").BackgroundJobPayload & {id: string}, resolve?: (value: void) => void, timeoutTimer?: ReturnType<typeof setTimeout> | null}>, retiring: boolean, settling?: boolean, timeoutSigkillTimer?: ReturnType<typeof setTimeout> | null}>} */
+    /** @type {Map<import("node:child_process").ChildProcess, {createdAtMs: number, jobsRun: number, inflight: Map<string, {payload: import("./types.js").BackgroundJobPayload & {id: string}, resolve?: (value: void) => void, timeoutTimer?: ReturnType<typeof setTimeout> | null}>, lastDispatchSeq: number, retiring: boolean, settling?: boolean, timeoutSigkillTimer?: ReturnType<typeof setTimeout> | null}>} */
     this.pooledChildStates = new Map()
+    // Monotonic dispatch counter for round-robin child selection: each dispatch stamps
+    // the chosen child, and selection prefers the child dispatched least recently.
+    this._pooledDispatchSeq = 0
   }
 
   /**
@@ -666,18 +669,13 @@ export default class BackgroundJobsWorker {
    * @returns {Promise<void>} - Resolves after the durable report.
    */
   _runPooledJob(payload) {
-    let child
-    for (const candidate of this.pooledChildren) {
-      const state = this.pooledChildStates.get(candidate)
-      if (state && !state.retiring && state.inflight.size < this.pooledRunnerConcurrency) {
-        child = candidate
-        break
-      }
-    }
-    if (!child) child = this._createPooledChild()
+    const child = this._selectPooledChild() || this._createPooledChild()
     const state = this.pooledChildStates.get(child)
     if (!state) throw new Error("Pooled runner state missing")
 
+    // Stamp the round-robin cursor so the next dispatch prefers a different child.
+    state.lastDispatchSeq = ++this._pooledDispatchSeq
+
     return new Promise((resolve) => {
       const timeoutTimer = this._armPooledJobTimeout({child, jobId: payload.id})
 
@@ -690,6 +688,36 @@ export default class BackgroundJobsWorker {
     })
   }
 
+  /**
+   * Selects a pooled child to run the next job, or undefined when every non-retiring
+   * child is already full (the caller then lazily spawns one). Among children with a
+   * free concurrency slot, picks the one dispatched least recently — a round-robin that
+   * spreads jobs (notably multi-minute RunBuildJobs, each pinning a tenant connection
+   * for its whole run) evenly across children instead of first-fit packing the earliest
+   * one until it is full. A freshly spawned or replacement child therefore takes its
+   * fair share one job at a time as its turn comes up, rather than absorbing a burst to
+   * "catch up" to the others.
+   * @returns {import("node:child_process").ChildProcess | undefined} - The chosen child, or undefined when all non-retiring children are full.
+   */
+  _selectPooledChild() {
+    /** @type {import("node:child_process").ChildProcess | undefined} */
+    let selected
+    let selectedSeq = Infinity
+
+    for (const child of this.pooledChildren) {
+      const state = this.pooledChildStates.get(child)
+
+      if (!state || state.retiring || state.inflight.size >= this.pooledRunnerConcurrency) continue
+
+      if (state.lastDispatchSeq < selectedSeq) {
+        selected = child
+        selectedSeq = state.lastDispatchSeq
+      }
+    }
+
+    return selected
+  }
+
   /**
    * Arms a per-job wall-clock backstop for a pooled job. A pooled child hosts many
    * concurrent jobs, so a single genuinely-hung job would otherwise pin its
@@ -756,7 +784,7 @@ export default class BackgroundJobsWorker {
     })
     this.pooledChildren.add(child)
     this.inflightProcessChildren.add(child)
-    this.pooledChildStates.set(child, {createdAtMs: Date.now(), jobsRun: 0, inflight: new Map(), retiring: false})
+    this.pooledChildStates.set(child, {createdAtMs: Date.now(), jobsRun: 0, inflight: new Map(), lastDispatchSeq: 0, retiring: false})
     child.on("message", (message) => this._handlePooledChildMessage({child, message}))
     child.once("exit", (code, signal) => this._handlePooledChildFailure({child, error: new Error(`Pooled background job runner exited: code=${code} signal=${signal || "none"}`)}))
     child.once("error", (error) => this._handlePooledChildFailure({child, error}))

package/build/database/drivers/base.js

@@ -59,6 +59,7 @@
  * @property {boolean} [processListComment] - Whether to add process-list comments to the query.
  * @property {boolean} [retry] - Whether retryable errors may retry the query; defaults to true.
  * @property {boolean} [sessionTimeZone] - Whether to ensure the configured database session time zone before the query.
+ * @property {AbortSignal} [signal] - Aborts the in-flight query (destroying its connection) when it fires.
  * @property {string} [sourceStack] - Stack captured at the caller boundary.
  */
 
@@ -116,6 +117,7 @@ import { formatDateForDatabase } from "../datetime-storage.js"
 import isDate from "../../utils/is-date.js"
 import Logger from "../../logger.js"
 import Query from "../query/index.js"
+import QueryAbortedError from "../query-aborted-error.js"
 import Handler from "../handler.js"
 import Mutex from "epic-locks/build/mutex.js"
 import UUID from "pure-uuid"
@@ -1170,6 +1172,10 @@ export default class VelociousDatabaseDriversBase {
       } catch (error) {
         if (!(error instanceof Error)) throw error
 
+        // A deliberately-aborted query must never be silently re-run — its
+        // connection was destroyed on purpose, so treat it as terminal.
+        if (error instanceof QueryAbortedError) throw error
+
         const retryInfo = this.retryableDatabaseError(error)
 
         if (options.retry !== false && tries < maxTries && retryInfo.retry) {
@@ -1274,7 +1280,7 @@ export default class VelociousDatabaseDriversBase {
     await this.beforeQuery(sql, options)
 
     try {
-      return await this._queryActual(sql)
+      return await this._queryActual(sql, options)
     } finally {
       await this.afterQuery(sql, options)
     }
@@ -1463,9 +1469,10 @@ export default class VelociousDatabaseDriversBase {
    * Runs query actual.
    * @abstract
    * @param {string} sql - SQL string.
+   * @param {QueryOptions} [options] - Query options (carries the optional abort signal).
    * @returns {Promise<QueryResultType>} - Resolves with the query actual.
    */
-  _queryActual(sql) { // eslint-disable-line no-unused-vars
+  _queryActual(sql, options) { // eslint-disable-line no-unused-vars
     throw new Error(`queryActual not implemented`)
   }
 

package/build/database/drivers/mysql/index.js

@@ -13,6 +13,7 @@ import Insert from "./sql/insert.js"
 import Options from "./options.js"
 import mysql from "mysql"
 import query from "./query.js"
+import QueryAbortedError from "../../query-aborted-error.js"
 import QueryParser from "./query-parser.js"
 import streamQuery from "./query-stream.js"
 import RemoveIndex from "./sql/remove-index.js"
@@ -371,15 +372,23 @@ export default class VelociousDatabaseDriversMysql extends Base{
   /**
    * Runs query actual.
    * @param {string} sql - SQL string.
+   * @param {import("../base.js").QueryOptions} [options] - Query options (carries the optional abort signal).
    * @returns {Promise<import("../base.js").QueryResultType>} - Resolves with the query actual.
    */
-  async _queryActual(sql) {
+  async _queryActual(sql, options = {}) {
     if (!this.pool) await this.connect()
     if (!this.pool) throw new Error("MySQL pool failed to initialize")
 
     try {
-      return await query(this.pool, sql)
+      return await query(this.pool, sql, {signal: options.signal})
     } catch (error) {
+      // Preserve an abort as-is so the retry loop can recognise it as terminal
+      // (wrapping it in a plain Error would lose the QueryAbortedError type).
+      if (error instanceof QueryAbortedError) {
+        if (error.connectionDestroyed) this.resetCurrentSessionTimeZone()
+        throw error
+      }
+
       // Re-throw to un-corrupt stacktrace
       if (error instanceof Error) {
         throw new Error(`Query failed: ${error.message}`, {cause: error})

package/build/database/drivers/mysql/query.js

@@ -1,37 +1,213 @@
+// @ts-check
+
+import mysql from "mysql"
+import QueryAbortedError from "../../query-aborted-error.js"
+
 /**
- * Runs query.
- * @param {import("mysql").Pool} pool - Pool.
- * @param {string} sql - SQL string.
- * @returns {Promise<Record<string, ?>[]>} - Resolves with string value.
+ * Checks out one pool connection while honoring cancellation before checkout completes.
+ * A connection returned after cancellation is released without running the query.
+ * @param {import("mysql").Pool} pool - Pool to check out from.
+ * @param {string} sql - SQL associated with the checkout.
+ * @param {AbortSignal | undefined} signal - Optional cancellation signal.
+ * @returns {Promise<import("mysql").PoolConnection>} - Checked-out connection.
  */
-export default async function query(pool, sql) {
+function checkoutConnection(pool, sql, signal) {
   return new Promise((resolve, reject) => {
-    pool.query(sql, (error, results, fields) => {
+    let settled = false
+    /** @type {(() => void) | undefined} */
+    let removeAbortListener
+
+    const settle = () => {
+      settled = true
+      if (removeAbortListener) removeAbortListener()
+    }
+
+    const onAbort = () => {
+      if (settled) return
+
+      settle()
+      reject(new QueryAbortedError({sql}))
+    }
+
+    if (signal) {
+      signal.addEventListener("abort", onAbort, {once: true})
+      removeAbortListener = () => signal.removeEventListener("abort", onAbort)
+    }
+
+    if (signal?.aborted) {
+      onAbort()
+
+      return
+    }
+
+    pool.getConnection((error, connection) => {
+      if (settled) {
+        if (connection) connection.release()
+
+        return
+      }
+
+      settle()
+
       if (error) {
-        reject(new Error(`Query failed because of ${error}: ${sql}`))
+        reject(error)
       } else {
-        const rows = []
-        const resultRows = Array.isArray(results) ? results : []
-        const resultFields = Array.isArray(fields) ? fields : []
+        resolve(connection)
+      }
+    })
+  })
+}
+
+/**
+ * Best-effort `KILL QUERY` so the server aborts the running statement — releasing
+ * its locks/resources immediately — instead of finishing it after the client
+ * socket is destroyed. Destroying the socket alone does not interrupt a
+ * non-cooperative running statement (e.g. `SLEEP` or a long scan) server-side, so
+ * the deadline would otherwise only suppress the client while the query keeps
+ * holding database resources. Runs on a throwaway connection because the driver
+ * pool is capped at one connection (the one running the aborted query). Any
+ * failure is swallowed: the caller still destroys the socket and rejects.
+ * @param {import("mysql").Pool} pool - Pool whose connection config seeds the kill connection.
+ * @param {number | null | undefined} threadId - Server thread id of the query to kill.
+ * @returns {Promise<void>} - Resolves once the kill has been attempted.
+ */
+function killServerQuery(pool, threadId) {
+  return new Promise((resolve) => {
+    const connectionConfig = /** @type {{config?: {connectionConfig?: unknown}}} */ (pool).config?.connectionConfig
+
+    if (!threadId || !connectionConfig) {
+      resolve()
+
+      return
+    }
+
+    let killConnection
+
+    try {
+      killConnection = mysql.createConnection(/** @type {?} */ (connectionConfig))
+    } catch {
+      resolve()
+
+      return
+    }
+
+    killConnection.on("error", () => {})
+    killConnection.query(`KILL QUERY ${Number(threadId)}`, () => {
+      killConnection.destroy()
+      resolve()
+    })
+  })
+}
+
+/**
+ * Runs `sql` on a dedicated connection checked out of `pool` so it can be
+ * aborted while it is still executing. When `signal` fires before the query
+ * settles the connection is destroyed — which aborts the running statement at
+ * the socket and removes the connection from the pool so it is never handed back
+ * mid-statement — and the promise rejects with a {@link QueryAbortedError}. On
+ * success the connection is released back to the pool. On a fatal connection
+ * error it is destroyed; on an ordinary query error (syntax, constraint, etc.)
+ * it is released, because the connection itself is still healthy.
+ * @param {import("mysql").Pool} pool - Pool.
+ * @param {string} sql - SQL string.
+ * @param {{signal?: AbortSignal}} [options] - Query options.
+ * @returns {Promise<Record<string, ?>[]>} - Resolves with the mapped rows.
+ */
+export default async function query(pool, sql, {signal} = {}) {
+  if (signal?.aborted) throw new QueryAbortedError({sql})
+
+  const connection = await checkoutConnection(pool, sql, signal)
+
+  return await new Promise((resolve, reject) => {
+    let settled = false
+    /** @type {(() => void) | undefined} */
+    let removeAbortListener
+
+    const settle = () => {
+      settled = true
+      if (removeAbortListener) removeAbortListener()
+    }
+
+    const onAbort = () => {
+      if (settled) return
+
+      settle()
+      const threadId = connection.threadId
+
+      // Destroy — never release — so a connection still mid-statement is not
+      // returned to the pool and the pool slot is freed even if the separate
+      // server-side kill attempt stalls. The pool spawns a fresh connection on
+      // the next checkout.
+      connection.destroy()
+      void killServerQuery(pool, threadId)
+      reject(new QueryAbortedError({connectionDestroyed: true, sql}))
+    }
+
+    if (signal) {
+      signal.addEventListener("abort", onAbort, {once: true})
+      removeAbortListener = () => signal.removeEventListener("abort", onAbort)
+    }
 
-        for (const rowData of resultRows) {
-          /**
-           * Result.
-           * @type {Record<string, ?>} */
-          const result = {}
+    // An abort that landed between the checkout above and attaching the listener
+    // would not fire the listener (the event already dispatched), so re-check and
+    // abort synchronously to close that race before issuing the query.
+    if (signal?.aborted) {
+      onAbort()
 
-          for (const fieldData of resultFields) {
-            const field = fieldData.name
-            const value = rowData[field]
+      return
+    }
 
-            result[field] = value
-          }
+    connection.query(sql, (/** @type {?} */ error, /** @type {?} */ results, /** @type {?} */ fields) => {
+      if (settled) return
 
-          rows.push(result)
+      settle()
+
+      if (error) {
+        // A fatal error leaves the socket unusable, so discard it; an ordinary
+        // query error keeps a healthy connection that can be reused.
+        if (error.fatal) {
+          connection.destroy()
+        } else {
+          connection.release()
         }
 
-        resolve(rows)
+        reject(new Error(`Query failed because of ${error}: ${sql}`))
+
+        return
       }
+
+      connection.release()
+      resolve(mapRows(results, fields))
     })
   })
 }
+
+/**
+ * Materializes the driver rows as isolated plain records keyed by field name.
+ * @param {?} results - Driver result rows.
+ * @param {?} fields - Driver result fields.
+ * @returns {Record<string, ?>[]} - Mapped rows.
+ */
+function mapRows(results, fields) {
+  const rows = []
+  const resultRows = Array.isArray(results) ? results : []
+  const resultFields = Array.isArray(fields) ? fields : []
+
+  for (const rowData of resultRows) {
+    /**
+     * Result.
+     * @type {Record<string, ?>} */
+    const result = {}
+
+    for (const fieldData of resultFields) {
+      const field = fieldData.name
+      const value = rowData[field]
+
+      result[field] = value
+    }
+
+    rows.push(result)
+  }
+
+  return rows
+}

package/build/database/query/index.js

@@ -125,6 +125,7 @@ function mergeJoinValue(existing, incoming) {
  * @property {Record<string, string[]>} [preloadSelects] - Attribute names to load for preloaded relationships, keyed by target model name.
  * @property {Record<string, string[]>} [preloadSelectsExtra] - Extra selects to load in addition to the defaults for preloaded relationships, keyed by target model name.
  * @property {Array<import("./select-base.js").default>} [selects] - SELECT clauses for the query.
+ * @property {AbortSignal} [signal] - Signal passed to database query execution.
  * @property {boolean} [distinct] - Whether the query should use DISTINCT.
  * @property {Array<import("./where-base.js").default>} [wheres] - WHERE conditions for the query.
  */
@@ -150,6 +151,7 @@ export default class VelociousDatabaseQuery {
     preloadSelectsExtra = {},
     distinct = false,
     selects = [],
+    signal,
     wheres = []
   }) {
     if (!driver) throw new Error("No driver given to query")
@@ -182,6 +184,7 @@ export default class VelociousDatabaseQuery {
     this._preloadSelectsExtra = preloadSelectsExtra
     this._distinct = distinct
     this._selects = selects
+    this._signal = signal
 
     /**
      * Narrows the runtime value to the documented type.
@@ -213,6 +216,7 @@ export default class VelociousDatabaseQuery {
       preload: {...this._preload},
       distinct: this._distinct,
       selects: [...this._selects],
+      signal: this._signal,
       wheres: [...this._wheres]
     })
 
@@ -482,11 +486,22 @@ export default class VelociousDatabaseQuery {
    */
   async _executeQuery({logName = this.queryLogName("Load")} = {}) {
     const sql = this.toSql()
-    const results = await this.driver.query(sql, {logName})
+    const results = await this.driver.query(sql, {logName, signal: this._signal})
 
     return results
   }
 
+  /**
+   * Sets the signal used to cancel database execution for this query and its clones.
+   * @param {AbortSignal | undefined} signal - Cancellation signal, or undefined to clear it.
+   * @returns {this} - Query for chaining.
+   */
+  signal(signal) {
+    this._signal = signal
+
+    return this
+  }
+
   /**
    * Runs results.
    * @returns {Promise<Array<object>>} Array of results from the database

package/build/database/query/model-class-query.js

@@ -234,6 +234,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
       preloadSelectsExtra: clonePreloadSelectMap(this._preloadSelectsExtra),
       distinct: this._distinct,
       selects: [...this._selects],
+      signal: this._signal,
       wheres: [...this._wheres],
       joinBasePath: [...this._joinBasePath],
       joinTracker: this._joinTracker.clone(),
@@ -373,7 +374,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     ].join(" ")
     const results = /** @type {{count: number}[]} */ (await this.driver.query(
       sql,
-      {logName: this.queryLogName("Count")}
+      {logName: this.queryLogName("Count"), signal: this._signal}
     ))
 
     if (results.length != 1 || !("count" in results[0])) {
@@ -780,7 +781,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
       sql = `UPDATE ${driver.quoteTable(tableName)} SET ${setCols}${whereSql}`
     }
 
-    await driver.query(sql, {logName: this.queryLogName("Update All")})
+    await driver.query(sql, {logName: this.queryLogName("Update All"), signal: this._signal})
   }
 
   /**

package/build/database/query/query-data.js

@@ -190,23 +190,50 @@ export async function runQueryData({rootModelClass, rootModels, entries}) {
 
   const primaryKey = rootModelClass.primaryKey()
   const rootIds = rootModels.map((model) => /** @type {string | number} */ (model.readColumn(primaryKey)))
+  const preparedEntries = entries.map((entry, entryIndex) => prepareEntry({entry, entryIndex, primaryKey, rootIds, rootModelClass}))
+  /**
+   * Compatible query groups.
+   * @type {Array<{aliases: Set<string>, query: import("./model-class-query.js").default, signature: string}>} */
+  const queryGroups = []
+
+  for (const preparedEntry of preparedEntries) {
+    const compatibleGroup = queryGroups.find((group, groupIndex) => {
+      if (group.signature !== preparedEntry.signature) return false
+      if (queryGroups.slice(groupIndex + 1).some((interveningGroup) => (
+        preparedEntry.aliases.some((alias) => interveningGroup.aliases.has(alias))
+      ))) return false
+
+      return preparedEntry.aliases.every((alias) => !group.aliases.has(alias))
+    })
+
+    if (compatibleGroup) {
+      compatibleGroup.query.select(preparedEntry.query.getSelects().slice(1))
+      for (const alias of preparedEntry.aliases) compatibleGroup.aliases.add(alias)
+    } else {
+      queryGroups.push({
+        aliases: new Set(preparedEntry.aliases),
+        query: preparedEntry.query,
+        signature: preparedEntry.signature
+      })
+    }
+  }
 
-  for (const entry of entries) {
-    await runEntry({entry, primaryKey, rootIds, rootModelClass, rootModels})
+  for (const {query} of queryGroups) {
+    await executeEntryQuery({primaryKey, query, rootModels})
   }
 }
 
 /**
- * Runs run entry.
+ * Prepares one queryData entry and its compatibility metadata.
  * @param {object} args - Options.
  * @param {QueryDataEntry} args.entry - Entry being evaluated.
+ * @param {number} args.entryIndex - Stable position used to isolate opaque projections.
  * @param {string} args.primaryKey - Root model primary key column.
  * @param {Array<string | number>} args.rootIds - Root primary-key values.
  * @param {typeof import("../record/index.js").default} args.rootModelClass - Root model class.
- * @param {import("../record/index.js").default[]} args.rootModels - Loaded root records.
- * @returns {Promise<void>}
+ * @returns {{aliases: string[], query: import("./model-class-query.js").default, signature: string}} - Prepared entry.
  */
-async function runEntry({entry, primaryKey, rootIds, rootModelClass, rootModels}) {
+function prepareEntry({entry, entryIndex, primaryKey, rootIds, rootModelClass}) {
   const targetModelClass = resolveTargetModelClass(rootModelClass, entry.chain)
   const fn = targetModelClass.getQueryDataByName(entry.fnName)
 
@@ -219,7 +246,7 @@ async function runEntry({entry, primaryKey, rootIds, rootModelClass, rootModels}
 
   // Empty out any defaults the query factory added — queryData runs
   // a bare aggregate, not a full model load.
-  query._selects = []
+  query.reselect()
   query._preload = {}
 
   // Force the root WHERE to qualify by table name so it survives the
@@ -264,6 +291,47 @@ async function runEntry({entry, primaryKey, rootIds, rootModelClass, rootModels}
     tableName: targetTableRef
   })
 
+  const aliases = selectedAliases(query)
+  const signatureQuery = query.clone()
+  signatureQuery.reselect(signatureQuery.getSelects().slice(0, 1))
+
+  return {
+    aliases: aliases || [],
+    query,
+    signature: aliases ? signatureQuery.toSql() : `opaque:${entryIndex}`
+  }
+}
+
+/**
+ * Returns explicit aliases selected after the reserved parent id.
+ * Entries with an opaque select stay isolated by receiving a unique compatibility alias.
+ * @param {import("./model-class-query.js").default} query - Prepared queryData query.
+ * @returns {string[] | null} - Selected aliases, or null for an opaque projection.
+ */
+function selectedAliases(query) {
+  const aliases = []
+
+  for (const select of query.getSelects().slice(1)) {
+    const sql = select.toSql()
+    const match = sql.match(/\sAS\s+([^\s]+)\s*$/iu)
+
+    if (!match) return null
+
+    aliases.push(match[1].replace(/^["[`]|["`\]]$/gu, ""))
+  }
+
+  return aliases
+}
+
+/**
+ * Executes one compatible queryData group and attaches every selected alias.
+ * @param {object} args - Options.
+ * @param {string} args.primaryKey - Root model primary key column.
+ * @param {import("./model-class-query.js").default} args.query - Prepared grouped query.
+ * @param {import("../record/index.js").default[]} args.rootModels - Loaded root records.
+ * @returns {Promise<void>}
+ */
+async function executeEntryQuery({primaryKey, query, rootModels}) {
   const rows = /** @type {Array<Record<string, ?>>} */ (await query._executeQuery())
   const byParent = new Map()