velocious 1.0.577 → 1.0.579

package/README.md

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

@@ -83,7 +83,7 @@ export default class VelociousApplication {
 
   /**
    * Runs run.
-   * @param {function() : void} callback - Callback function.
+   * @param {() => void} callback - Callback function.
    * @returns {Promise<void>} - Resolves when complete.
    */
   async run(callback) {
@@ -119,14 +119,14 @@ export default class VelociousApplication {
    * @param {object} args - HTTP server startup arguments.
    * @param {import("./configuration.js").default} args.configuration - Configuration instance.
    * @param {string} [args.host] - HTTP server host.
-   * @param {Record<string, ?>} args.httpServerConfiguration - Merged HTTP server configuration.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.httpServerConfiguration - Merged HTTP server configuration.
    * @param {number} args.port - HTTP server port.
    * @returns {Promise<void>} - Resolves after the HTTP server has started.
    */
   async startLockedHttpServer({configuration, host, httpServerConfiguration, port}) {
     try {
       if (!configuration.getWebsocketEvents()) {
-        configuration.setWebsocketEvents(/** @type {?} */ (websocketEventsHost))
+        configuration.setWebsocketEvents(/** @type {ReturnType<typeof JSON.parse>} */ (websocketEventsHost))
       }
 
       await configuration.connectBeacon({peerType: "server"})

package/build/authorization/ability.js

@@ -3,7 +3,7 @@
 /**
  * Defines this typedef.
  * @template {typeof import("../database/record/index.js").default} [MC=typeof import("../database/record/index.js").default]
- * @typedef {Record<string, ?> | string | ((query: import("../database/query/model-class-query.js").default<MC>, args: {ability: VelociousAuthorizationAbility, action: string, modelClass: MC}) => void | import("../database/query/model-class-query.js").default<MC>)} AbilityConditionsType
+ * @typedef {Record<string, ReturnType<typeof JSON.parse>> | string | ((query: import("../database/query/model-class-query.js").default<MC>, args: {ability: VelociousAuthorizationAbility, action: string, modelClass: MC}) => void | import("../database/query/model-class-query.js").default<MC>)} AbilityConditionsType
  */
 
 /**
@@ -45,8 +45,8 @@ export default class VelociousAuthorizationAbility {
   /**
    * Runs constructor.
    * @param {object} args - Ability args.
-   * @param {Record<string, ?>} [args.context] - Ability context.
-   * @param {Record<string, ?>} [args.locals] - Ability locals.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.context] - Ability context.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.locals] - Ability locals.
    * @param {Array<typeof import("./base-resource.js").default>} [args.resources] - Resource classes.
    */
   constructor({context = {}, locals = {}, resources} = {}) {
@@ -97,7 +97,7 @@ export default class VelociousAuthorizationAbility {
 
   /**
    * Runs get context.
-   * @returns {Record<string, ?>} - Context.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Context.
    */
   getContext() {
     return this.context
@@ -105,7 +105,7 @@ export default class VelociousAuthorizationAbility {
 
   /**
    * Runs get locals.
-   * @returns {Record<string, ?>} - Locals.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Locals.
    */
   getLocals() {
     return this.locals
@@ -113,7 +113,7 @@ export default class VelociousAuthorizationAbility {
 
   /**
    * Runs current user.
-   * @returns {?} - Current user from context.
+   * @returns {ReturnType<typeof JSON.parse>} - Current user from context.
    */
   currentUser() {
     return this.context.currentUser

package/build/authorization/base-resource.js

@@ -81,7 +81,7 @@ export default class AuthorizationBaseResource {
   /**
    * Runs assert resource conditions signature.
    * @param {object} args - Signature args.
-   * @param {?} args.conditions - Conditions value.
+   * @param {ReturnType<typeof JSON.parse>} args.conditions - Conditions value.
    * @param {"can" | "cannot"} args.methodName - Method name.
    * @returns {void}
    */

package/build/background-jobs/client.js

@@ -28,7 +28,7 @@ export default class BackgroundJobsClient {
    * Runs enqueue.
    * @param {object} args - Options.
    * @param {string} args.jobName - Job name.
-   * @param {Array<?>} args.args - Job args.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
    * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
    * @returns {Promise<string>} - Job id.
    */
@@ -62,7 +62,7 @@ export default class BackgroundJobsClient {
    * @param {object} args - Options.
    * @param {string} args.scheduleKey - Stable logical schedule key.
    * @param {string} args.jobName - Job name.
-   * @param {Array<?>} args.args - Job args.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
    * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
    * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
    */

package/build/background-jobs/forked-runner-child.js

@@ -31,13 +31,13 @@ async function shutdownRunner(exitCode) {
 
 /**
  * Runs is job message.
- * @param {?} message - IPC message.
+ * @param {ReturnType<typeof JSON.parse>} message - IPC message.
  * @returns {message is {type: "job", payload: import("./types.js").BackgroundJobPayload}} - Whether this is a job message.
  */
 function isJobMessage(message) {
   if (!message || typeof message !== "object") return false
 
-  const messageRecord = /** @type {{type?: ?, payload?: ?}} */ (message)
+  const messageRecord = /** @type {{type?: ReturnType<typeof JSON.parse>, payload?: ReturnType<typeof JSON.parse>}} */ (message)
 
   return messageRecord.type === "job" && Object.hasOwn(messageRecord, "payload")
 }
@@ -68,7 +68,7 @@ function reportJobFinished() {
 
 /**
  * Runs run job message.
- * @param {?} message - IPC message.
+ * @param {ReturnType<typeof JSON.parse>} message - IPC message.
  * @returns {Promise<void>} - Resolves after the payload has run.
  */
 async function runJobMessage(message) {
@@ -84,7 +84,7 @@ async function runJobMessage(message) {
 
 /**
  * Runs handle job message.
- * @param {?} message - IPC message.
+ * @param {ReturnType<typeof JSON.parse>} message - IPC message.
  * @returns {Promise<void>} - Resolves after completion is reported.
  */
 async function handleJobMessage(message) {

package/build/background-jobs/job-runner.js

@@ -20,7 +20,7 @@ export class BackgroundJobPerformedFailure extends Error {
 /**
  * Runs report beacon ready error.
  * @param {import("../configuration.js").default} configuration - Configuration.
- * @param {?} error - Beacon readiness error.
+ * @param {ReturnType<typeof JSON.parse>} error - Beacon readiness error.
  * @returns {void}
  */
 function reportBeaconReadyError(configuration, error) {
@@ -94,7 +94,7 @@ export default async function runJobPayload(payload, {closeConnections = true, m
   const jobInstance = new JobClass()
   /**
    * Perform.
-   * @type {(...args: Array<?>) => Promise<void>} */
+   * @type {(...args: Array<ReturnType<typeof JSON.parse>>) => Promise<void>} */
   const perform = jobInstance.perform
 
   // Name the process after the job it is running so `ps`/`top` show what each

package/build/background-jobs/job.js

@@ -10,7 +10,7 @@ import BackgroundJobsClient from "./client.js"
  * `class RunBuildJob extends VelociousJob<[string]>` with `async perform(buildId)`.
  * The default empty tuple keeps argument-less jobs (`extends VelociousJob`,
  * `async perform()`) working unchanged.
- * @template {Array<?>} [TArgs=[]]
+ * @template {Array<ReturnType<typeof JSON.parse>>} [TArgs=[]]
  */
 export default class VelociousJob {
   /**
@@ -69,7 +69,7 @@ export default class VelociousJob {
 
   /**
    * Runs perform later.
-   * @param {...?} args - Job args.
+   * @param {...ReturnType<typeof JSON.parse>} args - Job args.
    * @returns {Promise<string>} - Job id.
    */
   static async performLater(...args) {
@@ -86,7 +86,7 @@ export default class VelociousJob {
   /**
    * Runs perform later with options.
    * @param {object} args - Options.
-   * @param {Array<?>} args.args - Job args.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
    * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
    * @returns {Promise<string>} - Job id.
    */
@@ -104,7 +104,7 @@ export default class VelociousJob {
    * Atomically replaces this job class's queued owner for a stable schedule key.
    * @param {object} args - Options.
    * @param {string} args.scheduleKey - Stable logical schedule key.
-   * @param {Array<?>} args.args - Job args.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.args - Job args.
    * @param {import("./types.js").BackgroundJobOptions} [args.options] - Job options.
    * @returns {Promise<import("./types.js").BackgroundJobReplacementResult>} - Replacement result.
    */
@@ -132,8 +132,8 @@ export default class VelociousJob {
 
   /**
    * Runs split args and options.
-   * @param {Array<?>} args - Job args.
-   * @returns {{jobArgs: Array<?>, jobOptions: import("./types.js").BackgroundJobOptions}} - Split args and options.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Job args.
+   * @returns {{jobArgs: Array<ReturnType<typeof JSON.parse>>, jobOptions: import("./types.js").BackgroundJobOptions}} - Split args and options.
    */
   static _splitArgsAndOptions(args) {
     if (args.length === 0) {

package/build/background-jobs/json-socket.js

@@ -92,7 +92,7 @@ export default class JsonSocket extends EventEmitter {
 
   /**
    * Runs send.
-   * @param {?} message - Message to send.
+   * @param {ReturnType<typeof JSON.parse>} message - Message to send.
    * @returns {void}
    */
   send(message) {

package/build/background-jobs/main.js

@@ -136,7 +136,7 @@ export default class BackgroundJobsMain {
     this._unsubscribeBeacon = undefined
     /**
      * Narrows the runtime value to the documented type.
-     * @type {((...args: Array<?>) => void) | undefined} */
+     * @type {((...args: Array<ReturnType<typeof JSON.parse>>) => void) | undefined} */
     this._beaconConnectHandler = undefined
     /**
      * Narrows the runtime value to the documented type.
@@ -710,7 +710,7 @@ export default class BackgroundJobsMain {
 
   /**
    * Reports an unexpected lease-release failure on framework error channels.
-   * @param {?} error - Release failure.
+   * @param {ReturnType<typeof JSON.parse>} error - Release failure.
    * @returns {void}
    */
   _reportHandoffReleaseError(error) {
@@ -727,7 +727,7 @@ export default class BackgroundJobsMain {
    * Reports an unexpected worker-handoff adoption failure on framework error
    * channels. A failed adoption is not fatal (the worker's jobs remain and are
    * reclaimed by the orphan sweep), but must surface rather than be swallowed.
-   * @param {?} error - Adoption failure.
+   * @param {ReturnType<typeof JSON.parse>} error - Adoption failure.
    * @returns {void}
    */
   _reportHandoffAdoptError(error) {
@@ -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"},
@@ -830,8 +830,8 @@ export default class BackgroundJobsMain {
   /**
    * Returns safe validation failures and reports unexpected client mutations.
    * @param {object} args - Options.
-   * @param {Record<string, ?>} args.context - Framework-error context.
-   * @param {?} args.error - Mutation failure.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.context - Framework-error context.
+   * @param {ReturnType<typeof JSON.parse>} args.error - Mutation failure.
    * @param {string} args.fallbackMessage - Client-safe fallback message.
    * @param {JsonSocket} args.jsonSocket - JSON socket.
    * @param {string} args.logMessage - Error log prefix.
@@ -922,7 +922,7 @@ export default class BackgroundJobsMain {
 
   /**
    * Runs emit background job failed.
-   * @param {{error: ?, handoffId?: string, handedOffAtMs?: number, job: import("./types.js").BackgroundJobRow, workerId?: string}} args - Failure event data.
+   * @param {{error: ReturnType<typeof JSON.parse>, handoffId?: string, handedOffAtMs?: number, job: import("./types.js").BackgroundJobRow, workerId?: string}} args - Failure event data.
    * @returns {void}
    */
   _emitBackgroundJobFailed({error, handoffId, handedOffAtMs, job, workerId}) {
@@ -983,7 +983,7 @@ export default class BackgroundJobsMain {
 
   /**
    * Runs normalize failure error.
-   * @param {?} error - Reported failure value.
+   * @param {ReturnType<typeof JSON.parse>} error - Reported failure value.
    * @returns {Error} Normalized error.
    */
   _normalizeFailureError(error) {
@@ -994,7 +994,7 @@ export default class BackgroundJobsMain {
 
   /**
    * Runs error from unknown failure.
-   * @param {?} error - Reported failure value.
+   * @param {ReturnType<typeof JSON.parse>} error - Reported failure value.
    * @returns {Error} Normalized error.
    */
   _errorFromUnknownFailure(error) {
@@ -1008,7 +1008,7 @@ export default class BackgroundJobsMain {
 
   /**
    * Runs message from unknown failure.
-   * @param {?} error - Reported failure value.
+   * @param {ReturnType<typeof JSON.parse>} error - Reported failure value.
    * @returns {string} Error message.
    */
   _messageFromUnknownFailure(error) {
@@ -1019,7 +1019,7 @@ export default class BackgroundJobsMain {
 
   /**
    * Runs has string failure.
-   * @param {?} error - Reported failure value.
+   * @param {ReturnType<typeof JSON.parse>} error - Reported failure value.
    * @returns {error is string} Whether the value is a non-empty string.
    */
   _hasStringFailure(error) {
@@ -1029,7 +1029,7 @@ export default class BackgroundJobsMain {
   /**
    * Runs copy string failure stack.
    * @param {object} args - Options.
-   * @param {?} args.error - Reported failure value.
+   * @param {ReturnType<typeof JSON.parse>} args.error - Reported failure value.
    * @param {Error} args.normalizedError - Normalized error.
    * @returns {void}
    */

package/build/background-jobs/normalize-error.js

@@ -2,7 +2,7 @@
 
 /**
  * Runs normalize background job error.
- * @param {?} error - Error input.
+ * @param {ReturnType<typeof JSON.parse>} error - Error input.
  * @returns {string} - Normalized error string.
  */
 export default function normalizeBackgroundJobError(error) {
@@ -14,7 +14,7 @@ export default function normalizeBackgroundJobError(error) {
 
 /**
  * Runs stringify unknown error.
- * @param {?} error - Error input.
+ * @param {ReturnType<typeof JSON.parse>} error - Error input.
  * @returns {string} - Stringified error.
  */
 function stringifyUnknownError(error) {

package/build/background-jobs/pooled-runner-child.js

@@ -50,12 +50,12 @@ function updateProcessTitle() {
 
 /**
  * Checks whether an IPC value is a runnable pooled job message.
- * @param {?} message - IPC message.
+ * @param {ReturnType<typeof JSON.parse>} message - IPC message.
  * @returns {message is {type: "job", payload: import("./types.js").BackgroundJobPayload & {id: string}}} - Whether this is a valid job message.
  */
 function isJobMessage(message) {
   if (!message || typeof message !== "object") return false
-  const record = /** @type {{type?: ?, payload?: ?}} */ (message)
+  const record = /** @type {{type?: ReturnType<typeof JSON.parse>, payload?: ReturnType<typeof JSON.parse>}} */ (message)
 
   return record.type === "job" && !!record.payload && typeof record.payload === "object" && typeof record.payload.id === "string"
 }
@@ -117,7 +117,7 @@ async function runJob(payload) {
 
 /**
  * Handles a job message, starting it alongside any concurrent siblings.
- * @param {?} message - IPC message.
+ * @param {ReturnType<typeof JSON.parse>} message - IPC message.
  * @returns {void}
  */
 function handleMessage(message) {

package/build/background-jobs/scheduler.js

@@ -67,7 +67,7 @@ export default class BackgroundJobsScheduler {
    * Runs constructor.
    * @param {object} args - Options.
    * @param {import("../configuration.js").default} args.configuration - Configuration.
-   * @param {function({args: Array<?>, jobClass: typeof import("./job.js").default, jobKey: string, options: import("./types.js").BackgroundJobOptions}) : Promise<void>} args.enqueueJob - Enqueue callback.
+   * @param {(args: {args: Array<ReturnType<typeof JSON.parse>>, jobClass: typeof import("./job.js").default, jobKey: string, options: import("./types.js").BackgroundJobOptions}) => Promise<void>} args.enqueueJob - Enqueue callback.
    */
   constructor({configuration, enqueueJob}) {
     this.configuration = configuration

package/build/background-jobs/status-reporter.js

@@ -37,7 +37,7 @@ export default class BackgroundJobsStatusReporter {
    * @param {object} args - Options.
    * @param {string} args.jobId - Job id.
    * @param {"completed" | "failed"} args.status - Status.
-   * @param {?} [args.error] - Error.
+   * @param {ReturnType<typeof JSON.parse>} [args.error] - Error.
    * @param {string} [args.handoffId] - Handoff lease id.
    * @param {number} [args.handedOffAtMs] - Handed off timestamp.
    * @param {string} [args.workerId] - Worker id.
@@ -84,7 +84,7 @@ export default class BackgroundJobsStatusReporter {
    * @param {object} args - Options.
    * @param {string} args.jobId - Job id.
    * @param {"completed" | "failed"} args.status - Status.
-   * @param {?} [args.error] - Error.
+   * @param {ReturnType<typeof JSON.parse>} [args.error] - Error.
    * @param {string} [args.handoffId] - Handoff lease id.
    * @param {number} [args.handedOffAtMs] - Handed off timestamp.
    * @param {string} [args.workerId] - Worker id.