velocious 1.0.600 → 1.0.602

package/README.md

@@ -15,8 +15,8 @@
 * 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))
-* Declarative client sync scopes with per-scope cursors, automatic mutation tracking, opt-in durable base-version conflict replay, realtime delivery whose per-recipient authorization hook receives the complete persisted sync envelope, and `sync`/`pull` progress reporting for "X of Y" import screens (see [docs/sync-client.md](docs/sync-client.md) and [docs/offline-sync.md](docs/offline-sync.md))
-* Reactive `useLiveQuery(Model.where(...))` queries that stay current from committed local model changes across local writes, pulls, and realtime (see [docs/live-queries.md](docs/live-queries.md))
+* Declarative client sync scopes with per-scope cursors, automatic mutation tracking, opt-in durable base-version conflict replay, realtime delivery, and immutable-handle project clients whose queues, scopes, cursors, receipts, conflicts, pulls, and reconnect catch-up stay in one physical tenant database (see [docs/sync-client.md](docs/sync-client.md) and [docs/offline-sync.md](docs/offline-sync.md))
+* Reactive `useLiveQuery(Model.where(...))` queries for default databases plus immutable-handle tenant live-query sources whose committed events and refreshes stay on the captured physical tenant (see [docs/live-queries.md](docs/live-queries.md))
 * Server-side sync envelope replay orchestration for app-owned sync receivers, including allowlisted authoritative values for conflict resolution (see [docs/sync-envelope-replay-service.md](docs/sync-envelope-replay-service.md))
 * Self-sustaining sync feeds: upstream imports triggered by the changes pull itself, with framework-owned coalescing and throttling (see [docs/sync-upstream-imports.md](docs/sync-upstream-imports.md))
 * AwesomeTasks-shaped offline sync proof using routed resources, domain commands, signed offline grants, and peer-forwarded mutations (see the [developer guide](docs/shared-resource-sync-guide.md) and [proof](docs/awesome-tasks-offline-sync-proof.md))
@@ -775,22 +775,20 @@ 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 return their original message by default with `errorType: "internal_error"` and a server-generated `correlationId` shared with the matching framework-error report. Set `secureFrontendModelErrors: true` to return only explicitly safe messages and otherwise `errorMessage: "Request failed."`. 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).
+Unexpected frontend-model endpoint failures return their original message and full stack trace by default in every environment, including production. Responses use `errorType: "internal_error"`, a server-generated `correlationId` shared with the matching framework-error report, and the established `debugErrorClass`, `debugErrorMessage`, and `debugBacktrace` fields. Expected application failures can use `VelociousError.safe(message, {errorType, details, code})`; generated frontend-model callers preserve the server's safe error fields without adding irrelevant debug 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.
-Other non-production environments, such as `staging`, keep the same client-safe default unless you explicitly opt in with `exposeInternalErrorsToClients: true`:
+To mask unexpected internal details, explicitly opt out for the application configuration:
 
 ```js
 const configuration = new Configuration({
-  environment: "staging",
-  exposeInternalErrorsToClients: true
+  exposeInternalErrorsToClients: false
 })
 ```
 
-This opt-in is ignored in `production`; production frontend-model responses never include internal exception details.
+With this opt-out, built-in commands, custom commands, and sync replay failures return `errorMessage: "Request failed."` and omit the debug message and stack fields in every environment. `secureFrontendModelErrors: true` remains a deprecated compatibility alias when `exposeInternalErrorsToClients` is omitted; an explicit `exposeInternalErrorsToClients` value always wins.
 
-Backends can append client-safe metadata to frontend-model error responses with `configuration.addClientErrorPayloadReporter(...)`. Reporters receive the caught `error`, the current `request`, a safe `requestDetails` snapshot, and a small `context` object, and should only return fields that are safe for clients to see. Frontend-model endpoint failures include `context.frontendModelEndpoint`, `action`, `commandType`, `model`, `requestId`, and `expectedError`. This is useful for attaching an error-reporting URL while keeping the normal production error message generic:
+Backends can append client-safe metadata to frontend-model error responses with `configuration.addClientErrorPayloadReporter(...)`. Reporters receive the caught `error`, the current `request`, a safe `requestDetails` snapshot, and a small `context` object, and should only return fields that are safe for clients to see. Frontend-model endpoint failures include `context.frontendModelEndpoint`, `action`, `commandType`, `model`, `requestId`, and `expectedError`. When exposure is disabled, Velocious strips the established debug fields even if a reporter supplies them. This is useful for attaching an error-reporting URL while keeping an opted-out error message generic:
 
 ```js
 configuration.addClientErrorPayloadReporter(async ({error, requestDetails, context}) => {
@@ -1919,7 +1917,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 an `internal_error` response with the original message by default (or `Request failed.` when `secureFrontendModelErrors` is enabled) 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.
+Genuinely unexpected frontend-model command failures reach this bus too. The frontend-model controller catches them to return an `internal_error` response with the original message and stack trace by default (or `Request failed.` without debug fields when `exposeInternalErrorsToClients: false`) 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 without irrelevant debug fields. 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.
 
@@ -2689,7 +2687,7 @@ Tenant lifecycle commands print start and final counts, report each completed te
 
 `afterMigrateTenant` hooks run inside the active default and tenant database connection scope for the tenant being migrated.
 
-At runtime, the apartment-style `Tenant` façade (`velocious/build/src/tenants/tenant.js`) is the single entry point: `Tenant.with(tenant, callback)` / `Tenant.current()` to switch into and read a Node async context, `Tenant.handle(tenant)` to deeply capture immutable application and physical database identity for overlapping browser/native work, `Tenant.each({identifier, callback, parallel?, filter?})` to run a callback within every provider-listed tenant, and `Tenant.drop({identifier, tenant})` (plus the `db:tenants:drop` CLI command) to drop a tenant's database through the provider's `dropDatabase` hook. SQLite handles additionally expose framework-owned `open`, `flush`, `close`, `delete`, `inspect`, and `withPin` lifecycle methods; `frontendTenantSqlite.maxOpenHandles` bounds resident identities and clean, idle, unpinned handles are evicted least-recently-used. `Tenant.handle(...).databaseOperation(...)` and `.transaction(...)` use bounded pool-owned checkouts and pin model/query/write/association/preload/audit/attachment/raw work to the captured database even if a later UI project switch changes ambient tenant state. `Model.usingTenant(tenant)` uses the same safe core and adds eager helpers plus general `databaseOperation`/`transaction` model callbacks; eager records preserve legacy ambient Node follow-up semantics, while browser/native follow-up database work belongs inside the callback APIs. Inactive identifiers, mixed physical tenants, unsupported/cyclic descriptors, and expired operations fail closed. `Tenant.with` and `Tenant.each` retain their connection-establishing and model-initializing ambient behavior for Node request/job flows. `Tenant.aggregateAcross({identifier, aggregates, keyColumns, subquery, tenants?, filter?})` runs one aggregate over the same table across many tenant databases and returns the merged result — grouping tenants by server and using a single cross-database `UNION ALL` where the driver supports two-part `` `database`.`table` `` references (MySQL/MariaDB) or one query per tenant otherwise (PostgreSQL/SQLite/MSSQL).
+At runtime, the apartment-style `Tenant` façade (`velocious/build/src/tenants/tenant.js`) is the single entry point: `Tenant.with(tenant, callback)` / `Tenant.current()` to switch into and read a Node async context, `Tenant.handle(tenant)` to deeply capture immutable application and physical database identity for overlapping browser/native work, `Tenant.each({identifier, callback, parallel?, filter?})` to run a callback within every provider-listed tenant, and `Tenant.drop({identifier, tenant})` (plus the `db:tenants:drop` CLI command) to drop a tenant's database through the provider's `dropDatabase` hook. SQLite handles additionally expose framework-owned `open`, `flush`, `close`, `delete`, `inspect`, and `withPin` lifecycle methods; `frontendTenantSqlite.maxOpenHandles` bounds resident identities and clean, idle, unpinned handles are evicted least-recently-used. `Tenant.handle(...).databaseOperation(...)` and `.transaction(...)` use bounded pool-owned checkouts and pin model/query/write/association/preload/audit/attachment/raw work to the captured database even if a later UI project switch changes ambient tenant state. The handle also builds tenant-bound live-query sources, exposes an opaque physical identity for filtered record-change subscriptions, and binds project `SyncClient` instances. `Model.usingTenant(tenant)` uses the same safe core and adds eager helpers plus general `databaseOperation`/`transaction` model callbacks; eager records preserve legacy ambient Node follow-up semantics, while browser/native follow-up database work belongs inside the callback APIs. Inactive identifiers, mixed physical tenants, unsupported/cyclic descriptors, expired operations, unscoped tenant event subscriptions, and stale/cross-tenant sync state fail closed. `Tenant.with` and `Tenant.each` retain their connection-establishing and model-initializing ambient behavior for Node request/job flows. `Tenant.aggregateAcross({identifier, aggregates, keyColumns, subquery, tenants?, filter?})` runs one aggregate over the same table across many tenant databases and returns the merged result — grouping tenants by server and using a single cross-database `UNION ALL` where the driver supports two-part `` `database`.`table` `` references (MySQL/MariaDB) or one query per tenant otherwise (PostgreSQL/SQLite/MSSQL).
 
 `SchemaCloner` adds a missing auto-increment column and its separate source unique index in one schema alteration, including on MySQL/MariaDB where an auto-increment column must be keyed when it is created.
 

package/build/configuration-types.js

@@ -697,9 +697,9 @@
  * @property {boolean} [enforceTenantDatabaseScopes] - Require tenant-switched model queries to resolve a tenant database identifier. Defaults to true.
  * @property {string} [environment] - Current environment name.
  * @property {import("./environment-handlers/base.js").default} environmentHandler - Environment handler instance.
- * @property {boolean} [exposeInternalErrorsToClients] - Return unexpected internal error details in client API payloads outside production. Defaults to false.
+ * @property {boolean} [exposeInternalErrorsToClients] - Return unexpected internal error messages and stack traces in frontend-model client payloads in every environment. Defaults to true.
  * @property {{maxOpenHandles?: number}} [frontendTenantSqlite] - Bounded frontend tenant SQLite lifecycle configuration.
- * @property {boolean} [secureFrontendModelErrors] - Return only explicitly safe frontend-model error messages to clients. Defaults to false.
+ * @property {boolean} [secureFrontendModelErrors] - Deprecated compatibility alias for `exposeInternalErrorsToClients: false` when the authoritative option is omitted.
  * @property {HttpServerConfiguration} [httpServer] - Default HTTP server configuration for applications started from this configuration.
  * @property {LoggingConfiguration} [logging] - Logging configuration.
  * @property {BackgroundJobsConfiguration} [backgroundJobs] - Background jobs configuration.

package/build/configuration.js

@@ -236,7 +236,7 @@ export default class VelociousConfiguration {
    * Runs constructor.
    * @param {import("./configuration-types.js").ConfigurationArgsType} args - Configuration arguments.
    */
-  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients = false, frontendTenantSqlite, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors = false, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
+  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients, frontendTenantSqlite, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
     restArgsError(restArgs)
 
     this._abilityResolver = abilityResolver
@@ -283,8 +283,9 @@ export default class VelociousConfiguration {
     this._environment = environment || globalThis.process?.env.VELOCIOUS_ENV || globalThis.process?.env.NODE_ENV || "development"
     this._environmentHandler = environmentHandler
     this._enforceTenantDatabaseScopes = enforceTenantDatabaseScopes
-    this._exposeInternalErrorsToClients = exposeInternalErrorsToClients
-    this._secureFrontendModelErrors = secureFrontendModelErrors
+    this._exposeInternalErrorsToClients = exposeInternalErrorsToClients === undefined
+      ? secureFrontendModelErrors !== true
+      : exposeInternalErrorsToClients
     this._directory = directory
     this._initializeModels = initializeModels
     /** @type {VelociousPackage[]} */
@@ -461,9 +462,10 @@ export default class VelociousConfiguration {
 
   /**
    * Returns whether frontend-model errors expose only explicitly safe messages.
-   * @returns {boolean} Whether frontend-model errors expose only explicitly safe messages.
+   * @deprecated Use `getExposeInternalErrorsToClients()`.
+   * @returns {boolean} Whether frontend-model internal error exposure is disabled.
    */
-  getSecureFrontendModelErrors() { return this._secureFrontendModelErrors === true }
+  getSecureFrontendModelErrors() { return !this.getExposeInternalErrorsToClients() }
 
   /**
    * Runs get debug endpoint.

package/build/database/live-query.js

@@ -16,6 +16,7 @@ import restArgsError from "../utils/rest-args-error.js"
  * @template T
  * @typedef {object} LiveQuerySource
  * @property {() => RecordModelClass} getModelClass - Root model class the query reads.
+ * @property {(modelClass: RecordModelClass) => string} [databaseIdentityForModel] - Captured physical identity for an observed model.
  * @property {() => Promise<T[]>} toArray - Runs the query and resolves the current rows.
  */
 
@@ -117,7 +118,9 @@ class LiveQuery {
     this._started = true
 
     for (const modelClass of this._modelClasses) {
-      this._unsubscribes.push(recordChanges.subscribe(modelClass, this._onRecordChange))
+      const databaseIdentity = this._query.databaseIdentityForModel?.(modelClass)
+
+      this._unsubscribes.push(recordChanges.subscribe(modelClass, this._onRecordChange, {databaseIdentity}))
     }
 
     this._run()

package/build/database/operation.js

@@ -127,6 +127,7 @@ export default class VelociousDatabaseOperation {
     this.assertActive()
     this.assertModel(record.getModelClass())
     record.bindDatabaseOperation(this)
+    record.captureDatabaseIdentity(this.databaseIdentity())
 
     return record
   }
@@ -203,6 +204,14 @@ export default class VelociousDatabaseOperation {
     return `${this._databaseIdentifier}:${this._configurationReuseKey}`
   }
 
+  /**
+   * Returns the tenant schema generation captured when this operation started.
+   * @returns {string | undefined} - Captured schema generation.
+   */
+  schemaGeneration() {
+    return this._schemaGeneration
+  }
+
   /**
    * Initializes a model through this operation's captured connection.
    * @param {typeof import("./record/index.js").default} ModelClass - Model class.

package/build/database/record/index.js

@@ -3618,6 +3618,29 @@ class VelociousDatabaseRecord {
     return this
   }
 
+  /**
+   * Captures and validates the physical database identity that owns this record.
+   * @param {string} databaseIdentity - Opaque operation/connection identity.
+   * @returns {this} This record.
+   */
+  captureDatabaseIdentity(databaseIdentity) {
+    if (this._databaseIdentity && this._databaseIdentity !== databaseIdentity) {
+      throw new Error("Record belongs to a different physical tenant database")
+    }
+
+    this._databaseIdentity = databaseIdentity
+
+    return this
+  }
+
+  /**
+   * Returns the captured physical database identity.
+   * @returns {string | undefined} Captured physical database identity.
+   */
+  databaseIdentity() {
+    return this._databaseIdentity
+  }
+
   /**
    * Releases this record from a completed eager-helper operation while
    * preserving the legacy ambient follow-up behavior of `usingTenant` finders.
@@ -3742,7 +3765,27 @@ class VelociousDatabaseRecord {
     if (this._databaseOperation) return this._databaseOperation.connection()
     if (this.__connection) return this.__connection
 
-    return this.getModelClass().connection()
+    const connection = this.getModelClass().connection()
+
+    if (this._databaseIdentity) this.captureDatabaseIdentity(this._databaseIdentityForConnection(connection))
+
+    return connection
+  }
+
+  /**
+   * Resolves the identity of an already selected concrete connection.
+   * @param {import("../drivers/base.js").default} connection - Concrete connection.
+   * @returns {string} Physical database identity.
+   */
+  _databaseIdentityForConnection(connection) {
+    const modelClass = this.getModelClass()
+    const databaseIdentifier = modelClass.getDatabaseIdentifier()
+    const reuseKey = modelClass
+      ._getConfiguration()
+      .getDatabasePool(databaseIdentifier)
+      .getConnectionConfigurationReuseKey(connection)
+
+    return `${databaseIdentifier}:${reuseKey}`
   }
 
   /**
@@ -3993,9 +4036,14 @@ class VelociousDatabaseRecord {
     if (!recordChanges.hasListeners(modelClass)) return
 
     const record = this
+    const databaseIdentity = this._databaseOperation
+      ? this._databaseOperation.databaseIdentity()
+      : this._databaseIdentityForConnection(this._connection())
+
+    this.captureDatabaseIdentity(databaseIdentity)
 
     await this._connection().afterCommit(() => {
-      recordChanges.emit({modelClass, operation, record})
+      recordChanges.emit({databaseIdentity, modelClass, operation, record})
     })
   }
 

package/build/database/record-changes.js

@@ -14,6 +14,7 @@ import EventEmitter from "../utils/event-emitter.js"
  * RecordChangeEvent type.
  * @typedef {object} RecordChangeEvent
  * @property {RecordModelClass} modelClass - Model class whose row changed.
+ * @property {string} databaseIdentity - Opaque physical database identity where the commit occurred.
  * @property {RecordChangeOperation} operation - The committed operation.
  * @property {InstanceType<RecordModelClass>} record - The committed record instance.
  */
@@ -49,15 +50,25 @@ class RecordChanges {
    * Subscribes a listener to committed changes of a model class.
    * @param {RecordModelClass} modelClass - Model class to observe.
    * @param {RecordChangeListener} listener - Listener called with each change event.
+   * @param {{databaseIdentity?: string}} [options] - Captured physical identity filter.
    * @returns {() => void} Unsubscribe callback.
    */
-  subscribe(modelClass, listener) {
+  subscribe(modelClass, listener, {databaseIdentity} = {}) {
+    if (modelClass.hasTenantDatabaseIdentifierResolver() && !databaseIdentity) {
+      throw new Error(`Tenant-scoped record-change subscriptions for ${modelClass.getModelName()} require a captured databaseIdentity`)
+    }
+
     const eventName = modelClass.getModelName()
+    const subscribedListener = databaseIdentity
+      ? (/** @type {RecordChangeEvent} */ event) => {
+        if (event.databaseIdentity === databaseIdentity) listener(event)
+      }
+      : listener
 
-    this._emitter.on(eventName, listener)
+    this._emitter.on(eventName, subscribedListener)
 
     return () => {
-      this._emitter.off(eventName, listener)
+      this._emitter.off(eventName, subscribedListener)
     }
   }
 
@@ -81,7 +92,10 @@ class RecordChanges {
    */
   emit(event) {
     if (this._batchDepth > 0) {
-      this._bufferedEvents.set(event.modelClass.getModelName(), event)
+      const modelName = event.modelClass.getModelName()
+      const eventKey = `${modelName.length}:${modelName}:${event.databaseIdentity}`
+
+      this._bufferedEvents.set(eventKey, event)
 
       return
     }

package/build/frontend-model-controller.js

@@ -175,7 +175,6 @@ const frontendModelJoinedPathsSymbol = Symbol("frontendModelJoinedPaths")
 const frontendModelGroupedColumnsSymbol = Symbol("frontendModelGroupedColumns")
 const frontendModelWhereNoMatchSymbol = Symbol("frontendModelWhereNoMatch")
 const frontendModelClientSafeErrorMessage = "Request failed."
-const frontendModelDebugErrorEnvironments = new Set(["development", "test"])
 
 /**
  * Builds a client-safe sync replay validation error.
@@ -277,10 +276,10 @@ function frontendModelVelociousMetadataForError(error) {
 /**
  * Runs frontend model client message for error.
  * @param {unknown} error - Caught error.
- * @param {boolean} forwardUnexpectedErrorMessage - Whether unexpected error messages may be exposed.
+ * @param {boolean} exposeInternalErrorsToClients - Whether unexpected error messages may be exposed.
  * @returns {string} - Message safe to return to API clients.
  */
-function frontendModelClientMessageForError(error, forwardUnexpectedErrorMessage) {
+function frontendModelClientMessageForError(error, exposeInternalErrorsToClients) {
   if (error instanceof RecordNotFoundError) {
     return "Record not found."
   }
@@ -301,7 +300,7 @@ function frontendModelClientMessageForError(error, forwardUnexpectedErrorMessage
     return error.message
   }
 
-  if (forwardUnexpectedErrorMessage && error instanceof Error) return error.message
+  if (exposeInternalErrorsToClients && error instanceof Error) return error.message
 
   return frontendModelClientSafeErrorMessage
 }
@@ -310,14 +309,11 @@ function frontendModelClientMessageForError(error, forwardUnexpectedErrorMessage
  * Runs frontend model debug payload for error.
  * @param {object} args - Arguments.
  * @param {import("./configuration.js").default} args.configuration - Current configuration.
- * @param {string} args.environment - Current environment.
  * @param {unknown} args.error - Caught error.
- * @returns {import("./configuration-types.js").ClientErrorPayloadReporterPayload} - Optional debug payload for non-production environments.
+ * @returns {import("./configuration-types.js").ClientErrorPayloadReporterPayload} - Optional internal error details when client exposure is enabled.
  */
-function frontendModelDebugPayloadForError({configuration, environment, error}) {
-  const debugAllowed = frontendModelDebugErrorEnvironments.has(environment) || environment !== "production" && configuration.getExposeInternalErrorsToClients()
-
-  if (!debugAllowed) {
+function frontendModelDebugPayloadForError({configuration, error}) {
+  if (!configuration.getExposeInternalErrorsToClients()) {
     return {}
   }
 
@@ -3259,10 +3255,9 @@ export default class FrontendModelController extends Controller {
    * Runs frontend model client error payload for error.
    * @param {unknown} error - Caught error.
    * @param {FrontendModelEndpointErrorContext | undefined} [endpointErrorContext] - Frontend-model endpoint error context.
-   * @param {{forwardUnexpectedErrorMessage?: boolean}} [options] - Client error rendering options.
    * @returns {Promise<import("./configuration-types.js").ClientErrorPayloadReporterPayload>} - Client payload for the current environment.
    */
-  async frontendModelClientErrorPayloadForError(error, endpointErrorContext, {forwardUnexpectedErrorMessage = false} = {}) {
+  async frontendModelClientErrorPayloadForError(error, endpointErrorContext) {
     const velociousMetadata = frontendModelVelociousMetadataForError(error)
     const normalizedError = error instanceof Error ? error : new Error(String(error))
     /** @type {import("./configuration-types.js").ClientErrorPayloadReporterPayload} */
@@ -3312,15 +3307,20 @@ export default class FrontendModelController extends Controller {
       request: this.getRequest()
     })
 
+    if (!this.getConfiguration().getExposeInternalErrorsToClients()) {
+      delete reporterPayload.debugBacktrace
+      delete reporterPayload.debugErrorClass
+      delete reporterPayload.debugErrorMessage
+    }
+
     return {
       ...reporterPayload,
       ...this.frontendModelErrorPayload(frontendModelClientMessageForError(
         error,
-        forwardUnexpectedErrorMessage && !this.getConfiguration().getSecureFrontendModelErrors()
+        this.getConfiguration().getExposeInternalErrorsToClients()
       )),
       ...frontendModelDebugPayloadForError({
         configuration: this.getConfiguration(),
-        environment: this.getConfiguration().getEnvironment(),
         error
       }),
       ...(velociousMetadata ? {velocious: velociousMetadata} : {}),
@@ -4397,9 +4397,7 @@ export default class FrontendModelController extends Controller {
 
         responses.push({
           requestId,
-          response: await this.frontendModelClientErrorPayloadForError(error, errorContext, {
-            forwardUnexpectedErrorMessage: !isBuiltInCommand
-          })
+          response: await this.frontendModelClientErrorPayloadForError(error, errorContext)
         })
       }
     }
@@ -4623,9 +4621,7 @@ export default class FrontendModelController extends Controller {
       await this.frontendModelLogEndpointError({error, errorContext})
 
       await this.render({
-        json: /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (serializeFrontendModelTransportValue(await this.frontendModelClientErrorPayloadForError(error, errorContext, {
-          forwardUnexpectedErrorMessage: true
-        }), this.transportSerializationOptions()))
+        json: /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (serializeFrontendModelTransportValue(await this.frontendModelClientErrorPayloadForError(error, errorContext), this.transportSerializationOptions()))
       })
     }
   }

package/build/src/configuration-types.d.ts

@@ -1512,7 +1512,7 @@ export type ConfigurationArgsType = {
      */
     environmentHandler: import("./environment-handlers/base.js").default;
     /**
-     * - Return unexpected internal error details in client API payloads outside production. Defaults to false.
+     * - Return unexpected internal error messages and stack traces in frontend-model client payloads in every environment. Defaults to true.
      */
     exposeInternalErrorsToClients?: boolean;
     /**
@@ -1522,7 +1522,7 @@ export type ConfigurationArgsType = {
         maxOpenHandles?: number;
     };
     /**
-     * - Return only explicitly safe frontend-model error messages to clients. Defaults to false.
+     * - Deprecated compatibility alias for `exposeInternalErrorsToClients: false` when the authoritative option is omitted.
      */
     secureFrontendModelErrors?: boolean;
     /**
@@ -2247,9 +2247,9 @@ export type ConfigurationArgsType = {
  * @property {boolean} [enforceTenantDatabaseScopes] - Require tenant-switched model queries to resolve a tenant database identifier. Defaults to true.
  * @property {string} [environment] - Current environment name.
  * @property {import("./environment-handlers/base.js").default} environmentHandler - Environment handler instance.
- * @property {boolean} [exposeInternalErrorsToClients] - Return unexpected internal error details in client API payloads outside production. Defaults to false.
+ * @property {boolean} [exposeInternalErrorsToClients] - Return unexpected internal error messages and stack traces in frontend-model client payloads in every environment. Defaults to true.
  * @property {{maxOpenHandles?: number}} [frontendTenantSqlite] - Bounded frontend tenant SQLite lifecycle configuration.
- * @property {boolean} [secureFrontendModelErrors] - Return only explicitly safe frontend-model error messages to clients. Defaults to false.
+ * @property {boolean} [secureFrontendModelErrors] - Deprecated compatibility alias for `exposeInternalErrorsToClients: false` when the authoritative option is omitted.
  * @property {HttpServerConfiguration} [httpServer] - Default HTTP server configuration for applications started from this configuration.
  * @property {LoggingConfiguration} [logging] - Logging configuration.
  * @property {BackgroundJobsConfiguration} [backgroundJobs] - Background jobs configuration.