velocious 1.0.514 → 1.0.516

package/src/frontend-model-controller.js

@@ -20,6 +20,8 @@ import isDate from "./utils/is-date.js"
 import isPlainObject from "./utils/plain-object.js"
 import {RansackQueryError, normalizeRansackGroup, parseRansackSort} from "./utils/ransack.js"
 
+/** @typedef {import("./database/query/model-class-query.js").default & Record<symbol, Set<string> | undefined>} FrontendModelQueryMetadata */
+
 /**
  * Runs normalize frontend model preload.
  * @param {import("./database/query/index.js").NestedPreloadRecord | string | string[] | boolean | undefined | null} preload - Preload shorthand.
@@ -31,7 +33,7 @@ function normalizeFrontendModelPreload(preload) {
   try {
     return normalizeQueryPreload(preload)
   } catch (error) {
-    throwFrontendModelQueryErrorForParserError(error)
+    return throwFrontendModelQueryErrorForParserError(error)
   }
 }
 
@@ -46,7 +48,7 @@ function normalizeFrontendModelJoins(joins) {
   try {
     return normalizeQueryJoins(joins)
   } catch (error) {
-    throwFrontendModelQueryErrorForParserError(error)
+    return throwFrontendModelQueryErrorForParserError(error)
   }
 }
 
@@ -190,10 +192,10 @@ function frontendSyncReplaySafeError(message, cause) {
 /**
  * Runs frontend model query metadata.
  * @param {import("./database/query/model-class-query.js").default} query - Query instance.
- * @returns {import("./database/query/model-class-query.js").default & {[frontendModelJoinedPathsSymbol]?: Set<string>, [frontendModelGroupedColumnsSymbol]?: Set<string>}} - Query metadata access helper.
+ * @returns {FrontendModelQueryMetadata} - Query metadata access helper.
  */
 function frontendModelQueryMetadata(query) {
-  return /** @type {import("./database/query/model-class-query.js").default & {[frontendModelJoinedPathsSymbol]?: Set<string>, [frontendModelGroupedColumnsSymbol]?: Set<string>}} */ (query)
+  return /** @type {FrontendModelQueryMetadata} */ (query)
 }
 
 /**
@@ -1253,7 +1255,7 @@ export default class FrontendModelController extends Controller {
     try {
       return normalizeQuerySort(this.frontendModelParams().sort)
     } catch (error) {
-      throwFrontendModelQueryErrorForParserError(error)
+      return throwFrontendModelQueryErrorForParserError(error)
     }
   }
 
@@ -1265,7 +1267,7 @@ export default class FrontendModelController extends Controller {
     try {
       return normalizeQueryGroup(this.frontendModelParams().group)
     } catch (error) {
-      throwFrontendModelQueryErrorForParserError(error)
+      return throwFrontendModelQueryErrorForParserError(error)
     }
   }
 
@@ -1304,7 +1306,7 @@ export default class FrontendModelController extends Controller {
 
       return pluck
     } catch (error) {
-      throwFrontendModelQueryErrorForParserError(error)
+      return throwFrontendModelQueryErrorForParserError(error)
     }
   }
 
@@ -1351,8 +1353,8 @@ export default class FrontendModelController extends Controller {
    * its backend model class by looking up the resource by modelName
    * across all configured backend projects. Returns null when no
    * resource matches the user-provided ability entry.
-   * @param {string} modelName
-   * @returns {typeof import("./database/record/index.js").default | null}
+   * @param {string} modelName - Frontend model name from an ability request.
+   * @returns {typeof import("./database/record/index.js").default | null} - Backend model class exposed under that frontend name, if present.
    */
   _frontendModelClassForAbilities(modelName) {
     if (typeof modelName !== "string" || modelName.length === 0) return null
@@ -1383,9 +1385,9 @@ export default class FrontendModelController extends Controller {
    * preloaded relationships at any depth. Used to evaluate per-record
    * abilities against nested preloaded children with a single batched
    * query per (modelClass, action) pair.
-   * @param {import("./database/record/index.js").default[]} rootModels
-   * @param {string} modelName
-   * @returns {import("./database/record/index.js").default[]}
+   * @param {import("./database/record/index.js").default[]} rootModels - Loaded roots whose relationship graphs should be traversed.
+   * @param {string} modelName - Model name records must match.
+   * @returns {import("./database/record/index.js").default[]} - Matching records reachable from the loaded roots.
    */
   _frontendModelCollectRecordsForName(rootModels, modelName) {
     /**
@@ -1399,7 +1401,8 @@ export default class FrontendModelController extends Controller {
 
     /**
      * Walk.
-     * @param {import("./database/record/index.js").default | null | undefined} record */
+     * @param {import("./database/record/index.js").default | null | undefined} record - Loaded record whose relationship graph should be visited.
+     */
     const walk = (record) => {
       if (!record || typeof record !== "object") return
       if (seen.has(record)) return
@@ -1437,7 +1440,7 @@ export default class FrontendModelController extends Controller {
    * `_setComputedAbility`. Runs one batched `authorized query + pluck`
    * per (modelClass, action) pair, regardless of how many records
    * were loaded.
-   * @param {import("./database/record/index.js").default[]} rootModels
+   * @param {import("./database/record/index.js").default[]} rootModels - Loaded roots that receive computed ability results.
    * @returns {Promise<void>}
    */
   async frontendModelComputeAbilities(rootModels) {
@@ -1491,7 +1494,7 @@ export default class FrontendModelController extends Controller {
    * Unknown entries are silently skipped — downstream code resolves
    * model names to classes when applying the check, so unresolved
    * names naturally become no-ops.
-   * @returns {Array<{modelName: string, actions: string[]}>}
+   * @returns {Array<{modelName: string, actions: string[]}>} - Normalized model ability requests.
    */
   frontendModelAbilities() {
     const raw = this.frontendModelParams().abilities
@@ -1529,7 +1532,7 @@ export default class FrontendModelController extends Controller {
    *
    * Returns the raw nested-record spec (shape validated by the
    * normalizer inside `Query.queryData`) or `null` when not requested.
-   * @returns {import("./database/query/query-data.js").QueryDataSpec | null}
+   * @returns {import("./database/query/query-data.js").QueryDataSpec | null} - Normalized query-data specification.
    */
   frontendModelQueryData() {
     const raw = this.frontendModelParams().queryData
@@ -1853,7 +1856,7 @@ export default class FrontendModelController extends Controller {
     try {
       return normalizeRansackGroup(this.frontendModelClass(), filterParams)
     } catch (error) {
-      throwFrontendModelQueryErrorForParserError(error)
+      return throwFrontendModelQueryErrorForParserError(error)
     }
   }
 
@@ -1866,7 +1869,7 @@ export default class FrontendModelController extends Controller {
     try {
       return parseRansackSort(this.frontendModelClass(), sortString)
     } catch (error) {
-      throwFrontendModelQueryErrorForParserError(error)
+      return throwFrontendModelQueryErrorForParserError(error)
     }
   }
 
@@ -2698,12 +2701,14 @@ export default class FrontendModelController extends Controller {
     /**
      * Resource attribute method name.
      * @param {string} attributeName - Attribute name.
+     * @returns {string} - Resource attribute method name.
      */
     const resourceAttributeMethodName = (attributeName) => `${attributeName}Attribute`
 
     /**
      * Resource has attribute.
      * @param {string} attributeName - Attribute name.
+     * @returns {ReturnType<FrontendModelBaseResource["resourceMethod"]>} - Resource attribute method details.
      */
     const resourceAttributeMethod = (attributeName) => {
       const methodName = resourceAttributeMethodName(attributeName)
@@ -2714,6 +2719,7 @@ export default class FrontendModelController extends Controller {
     /**
      * Prototype attribute method.
      * @param {string} attributeName - Attribute name.
+     * @returns {{method: (...args: Array<?>) => ?, ownerName: string} | undefined} - Prototype method details when present.
      */
     const prototypeAttributeMethod = (attributeName) => {
       let currentPrototype = Object.getPrototypeOf(model)
@@ -2735,6 +2741,7 @@ export default class FrontendModelController extends Controller {
     /**
      * Serialized attribute value.
      * @param {string} attributeName - Attribute name.
+     * @returns {Promise<?>} - Serialized attribute value.
      */
     const serializedAttributeValue = async (attributeName) => {
       // Check resource instance first (virtual/computed attributes via ${name}Attribute convention)
@@ -2758,6 +2765,7 @@ export default class FrontendModelController extends Controller {
     /**
      * Attribute exists.
      * @param {string} attributeName - Attribute name.
+     * @returns {boolean} - Whether the attribute exists.
      */
     const attributeExists = (attributeName) => {
       return (attributeName in modelAttributes) || (attributeName in /** @type {Record<string, ?>} */ (model)) || Boolean(resourceAttributeMethod(attributeName))

package/src/frontend-model-resource/base-resource.js

@@ -1128,10 +1128,10 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     }
 
     if (notPermittedAttachments.length > 0) {
-      throw new Error(`Frontend model attachment names not permitted by permittedParams(): ${notPermittedAttachments.join(", ")}`)
+      throw VelociousError.safe(`Frontend model attachment names not permitted by permittedParams(): ${notPermittedAttachments.join(", ")}`, {code: "frontend-model-attribute-error"})
     }
     if (invalidAttachments.length > 0) {
-      throw new Error(`Invalid frontend model attachment names: ${invalidAttachments.join(", ")}`)
+      throw VelociousError.safe(`Invalid frontend model attachment names: ${invalidAttachments.join(", ")}`, {code: "frontend-model-attribute-error"})
     }
   }
 
@@ -1978,11 +1978,11 @@ function filterWritableFrontendModelAttributes(
   }
 
   if (notPermittedAttributes.length > 0) {
-    throw new Error(`Frontend model write attributes not permitted by permittedParams(): ${notPermittedAttributes.join(", ")}`)
+    throw VelociousError.safe(`Frontend model write attributes not permitted by permittedParams(): ${notPermittedAttributes.join(", ")}`, {code: "frontend-model-attribute-error"})
   }
 
   if (invalidAttributes.length > 0) {
-    throw new Error(`Invalid frontend model write attributes: ${invalidAttributes.join(", ")}`)
+    throw VelociousError.safe(`Invalid frontend model write attributes: ${invalidAttributes.join(", ")}`, {code: "frontend-model-attribute-error"})
   }
 
   return writableAttributes

package/src/frontend-models/base.js

@@ -104,7 +104,7 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  * frontend models passed model classes into relationship helpers, while newer
  * generated models pass instance types.
  * @template {FrontendModelBase<any, any, any> | typeof FrontendModelBase} T
- * @typedef {T extends new (...args: any[]) => infer Instance ? Instance : T} FrontendModelRelationshipModel
+ * @typedef {T extends typeof FrontendModelBase ? InstanceType<T> : T} FrontendModelRelationshipModel
  */
 /**
  * FrontendModelTransportConfig type.
@@ -1799,7 +1799,7 @@ async function performSharedFrontendModelApiRequest(requestPayload) {
 /**
  * Throws a frontend-model HTTP error with backend-provided envelope details when available.
  * @param {{commandLabel: string, response: Response, responseText: string}} args - Error response details.
- * @returns {never}
+ * @returns {never} - Always throws an unknown-attribute error.
  */
 function throwFrontendModelHttpError({commandLabel, response, responseText}) {
   // Surface the backend's friendly errorMessage envelope (the
@@ -2612,7 +2612,7 @@ export default class FrontendModelBase {
    * column of the same name. Returns the attached value, or 0 when
    * `.withCount(...)` wasn't requested for this attribute.
    * @param {string} attributeName - Attribute name, e.g. `"tasksCount"` or a custom name from `.withCount({customName: {...}})`.
-   * @returns {number}
+   * @returns {number} - Attached association count, or zero when absent.
    */
   readCount(attributeName) {
     return readPayloadAssociationCount(/** @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/** @type {?} */ (this)), attributeName)
@@ -2638,7 +2638,7 @@ export default class FrontendModelBase {
    * on `record.can("update")` without first checking whether the
    * ability was loaded.
    * @param {string} action - Ability action name, e.g. `"update"`.
-   * @returns {boolean}
+   * @returns {boolean} - Whether the requested ability is allowed.
    */
   can(action) {
     return readPayloadComputedAbility(/** @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/** @type {?} */ (this)), action)
@@ -2663,7 +2663,7 @@ export default class FrontendModelBase {
    * name. Returns `null` when no registered fn produced that alias for
    * this record (e.g. no child rows matched the aggregate).
    * @param {string} name - queryData alias name.
-   * @returns {?}
+   * @returns {?} - Attached query-data value.
    */
   queryData(name) {
     return readPayloadQueryData(/** @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/** @type {?} */ (this)), name)

package/src/frontend-models/query.js

@@ -166,8 +166,8 @@ export function normalizePreload(preload) {
  * query API into the strict internal entries used in the transport
  * payload. Shares the shape semantics with the backend normalizer in
  * `database/query/with-count.js`.
- * @param {string | string[] | Record<string, boolean | {relationship?: string, where?: Record<string, ?>}>} spec
- * @returns {Array<{attributeName: string, relationshipName: string, where?: Record<string, ?>}>}
+ * @param {string | string[] | Record<string, boolean | {relationship?: string, where?: Record<string, ?>}>} spec - Association-count shorthand to normalize.
+ * @returns {Array<{attributeName: string, relationshipName: string, where?: Record<string, ?>}>} - Normalized association-count requests.
  */
 function normalizeWithCountFrontend(spec) {
   if (spec == null) return []
@@ -222,9 +222,9 @@ function normalizeWithCountFrontend(spec) {
  * shorthand (applies to the query's own model class) and the keyed
  * `{ModelName: [action, ...]}` form (applies to records of that model
  * class, useful for preloaded children).
- * @param {string[] | Record<string, string[]>} spec
- * @param {{getModelName: () => string}} rootModelClass
- * @returns {Array<{modelName: string, actions: string[]}>}
+ * @param {string[] | Record<string, string[]>} spec - Ability actions grouped by model, or root-model action shorthand.
+ * @param {{getModelName: () => string}} rootModelClass - Query root used by the flat action shorthand.
+ * @returns {Array<{modelName: string, actions: string[]}>} - Normalized model ability requests.
  */
 function normalizeAbilitiesSpec(spec, rootModelClass) {
   if (spec == null) return []
@@ -1181,8 +1181,8 @@ export default class FrontendModelQuery {
    * strings — typically `"update"` / `"destroy"` / `"create"` /
    * `"read"`, but any custom action registered on the resource's
    * authorization ability is accepted.
-   * @param {string[] | Record<string, string[]>} spec
-   * @returns {this}
+   * @param {string[] | Record<string, string[]>} spec - Ability actions to request for root or named models.
+   * @returns {this} - This query for chaining.
    */
   abilities(spec) {
     for (const entry of normalizeAbilitiesSpec(spec, this.modelClass)) {
@@ -1194,7 +1194,7 @@ export default class FrontendModelQuery {
 
   /**
    * Runs merge ability entry.
-   * @param {{modelName: string, actions: string[]}} entry
+   * @param {{modelName: string, actions: string[]}} entry - Normalized model ability request to append.
    * @returns {void}
    */
   _mergeAbilityEntry(entry) {
@@ -1215,8 +1215,8 @@ export default class FrontendModelQuery {
    * counts to each returned record. Parses the same shapes as the
    * backend `ModelClassQuery#withCount`, then ships the normalized
    * entries as part of the `index` command payload.
-   * @param {string | string[] | Record<string, boolean | {relationship?: string, where?: Record<string, ?>}>} spec
-   * @returns {this}
+   * @param {string | string[] | Record<string, boolean | {relationship?: string, where?: Record<string, ?>}>} spec - Relationships whose counts should be serialized.
+   * @returns {this} - This query for chaining.
    */
   withCount(spec) {
     for (const entry of normalizeWithCountFrontend(spec)) {
@@ -1233,8 +1233,8 @@ export default class FrontendModelQuery {
    * frontend ships only these names; the SQL fragments stay server-
    * side. All resulting aliases are attached to the root record and
    * read back with `record.queryData(aliasName)`.
-   * @param {string | Array<string | Record<string, ?>> | Record<string, ?>} spec
-   * @returns {this}
+   * @param {string | Array<string | Record<string, ?>> | Record<string, ?>} spec - Backend query-data names and arguments to serialize.
+   * @returns {this} - This query for chaining.
    */
   queryData(spec) {
     if (spec == null) return this

package/src/http-server/client/index.js

@@ -2,7 +2,6 @@
 
 import crypto from "crypto"
 import fs from "node:fs/promises"
-import {createReadStream} from "node:fs"
 import {digg} from "diggerize"
 import {ensureError} from "typanic"
 import EventEmitter from "../../utils/event-emitter.js"
@@ -58,6 +57,9 @@ export default class VeoliciousHttpServerClient {
      * Narrows the runtime value to the documented type.
      * @type {RequestRunner[]} */
     this.requestRunners = []
+
+    /** @type {Set<(result: "completed" | "aborted") => Promise<void>>} */
+    this.pendingFileResponses = new Set()
   }
 
   /**
@@ -355,6 +357,7 @@ export default class VeoliciousHttpServerClient {
     const response = digg(requestRunner, "response")
     const request = requestRunner.getRequest()
     const filePath = response.getFilePath()
+    const fileOnFinished = response.getFileOnFinished()
     const date = new Date()
     const connectionHeader = request.header("connection")?.toLowerCase()?.trim()
     const httpVersion = request.httpVersion()
@@ -423,8 +426,9 @@ export default class VeoliciousHttpServerClient {
 
     if (isBodylessStatus) {
       this.logger.debug(() => ["sendResponse body suppressed for no-body status", {clientCount: this.clientCount, statusCode: response.getStatusCode()}])
+      if (hasFilePath) await this.sendFileOutput(filePath, false, fileOnFinished)
     } else if (hasFilePath) {
-      await this.sendFileOutput(filePath)
+      await this.sendFileOutput(filePath, true, fileOnFinished)
     } else {
       this.events.emit("output", body)
       this.logger.debug(() => ["sendResponse body emitted", {clientCount: this.clientCount, bodyLength: bodyIsString ? body.length : body.byteLength}])
@@ -441,27 +445,69 @@ export default class VeoliciousHttpServerClient {
   /**
    * Runs send file output.
    * @param {string} filePath - File path.
+   * @param {boolean} sendBody - Whether the file body should be sent.
+   * @param {((result: "completed" | "aborted") => void | Promise<void>) | null} onFinished - Completion callback.
    * @returns {Promise<void>} - Resolves when complete.
    */
-  async sendFileOutput(filePath) {
+  async sendFileOutput(filePath, sendBody, onFinished) {
     this.logger.debug(() => ["sendFileOutput start", {clientCount: this.clientCount, filePath}])
-    let totalBytes = 0
-    let chunkCount = 0
+
+    const result = await new Promise((resolve) => {
+      /** @type {Promise<void> | null} */
+      let settlement = null
+      const settle = (/** @type {"completed" | "aborted"} */ transferResult) => {
+        if (settlement) return settlement
+
+        this.pendingFileResponses.delete(settle)
+        settlement = this.runFileOnFinished({filePath, onFinished, result: transferResult})
+          .finally(() => resolve(transferResult))
+
+        return settlement
+      }
+
+      this.pendingFileResponses.add(settle)
+      this.events.emit("file", {filePath, sendBody, settle})
+    })
+
+    this.logger.debug(() => ["sendFileOutput done", {clientCount: this.clientCount, filePath, result}])
+  }
+
+  /**
+   * Runs a file completion callback without allowing cleanup failures to replace the committed response.
+   * @param {object} args - Completion details.
+   * @param {string} args.filePath - File path.
+   * @param {((result: "completed" | "aborted") => void | Promise<void>) | null} args.onFinished - Completion callback.
+   * @param {"completed" | "aborted"} args.result - Transfer result.
+   * @returns {Promise<void>} - Resolves after callback cleanup and error reporting finish.
+   */
+  async runFileOnFinished({filePath, onFinished, result}) {
+    if (!onFinished) return
 
     try {
-      for await (const chunk of createReadStream(filePath)) {
-        chunkCount += 1
-        totalBytes += chunk.length
-        this.logger.debug(() => ["sendFileOutput chunk", {clientCount: this.clientCount, chunkCount, chunkLength: chunk.length, totalBytes}])
-        this.events.emit("output", chunk)
+      await onFinished(result)
+    } catch (caughtError) {
+      const error = ensureError(caughtError)
+
+      await this.logger.error(() => ["File response onFinished callback failed", {clientCount: this.clientCount, filePath, result}, error])
+
+      const errorPayload = {
+        context: {clientCount: this.clientCount, filePath, result, stage: "send-file-on-finished"},
+        error
       }
-      this.logger.debug(() => ["sendFileOutput done", {clientCount: this.clientCount, chunkCount, totalBytes}])
-    } catch (error) {
-      this.logger.error(() => [`Velocious client ${this.clientCount} failed while streaming file output: ${filePath}`, error])
-      throw error
+
+      this.configuration.getErrorEvents().emit("framework-error", errorPayload)
+      this.configuration.getErrorEvents().emit("all-error", {...errorPayload, errorType: "framework-error"})
     }
   }
 
+  /**
+   * Aborts all file responses awaiting transport acknowledgement.
+   * @returns {Promise<void>} - Resolves after pending callbacks settle.
+   */
+  async abortPendingFileResponses() {
+    await Promise.all([...this.pendingFileResponses].map((settle) => settle("aborted")))
+  }
+
   /**
    * Runs should close connection.
    * @param {import("./request.js").default | import("./websocket-request.js").default} request - Request object.
@@ -488,7 +534,7 @@ export default class VeoliciousHttpServerClient {
  * cannot carry a message body: every 1xx informational, 204 No
  * Content, and 304 Not Modified.
  * @param {number} statusCode - HTTP status code.
- * @returns {boolean}
+ * @returns {boolean} - Whether the status code forbids a response body.
  */
 function isNoBodyStatusCode(statusCode) {
   return (statusCode >= 100 && statusCode < 200) || statusCode === 204 || statusCode === 304

package/src/http-server/client/request-runner.js

@@ -135,7 +135,13 @@ export default class VelociousHttpServerClientRequestRunner {
     this.requestTiming.startedAtMs = Date.now()
 
     return await this.configuration.runWithRequestTiming(this.requestTiming, async () => {
-      await this._run()
+      // Run the whole request inside any per-test shared connection context so an
+      // in-process handler executes on the test's connection (and open transaction).
+      // No shared connection is set outside tests / in worker threads, so this is a
+      // no-op there.
+      await this.configuration.runWithTestSharedConnectionContexts(async () => {
+        await this._run()
+      })
     })
   }
 

package/src/http-server/client/response.js

@@ -88,6 +88,11 @@ export default class VelociousHttpServerClientResponse {
    * @type {string | null} */
   filePath = null
 
+  /**
+   * File response completion callback.
+   * @type {((result: "completed" | "aborted") => void | Promise<void>) | null} */
+  fileOnFinished = null
+
   /**
    * Headers.
    * @type {Record<string, string[]>} */
@@ -163,6 +168,7 @@ export default class VelociousHttpServerClientResponse {
    */
   setBody(value) {
     this.filePath = null
+    this.fileOnFinished = null
     this.body = value
   }
 
@@ -174,13 +180,23 @@ export default class VelociousHttpServerClientResponse {
     return this.filePath
   }
 
+  /**
+   * Gets the file response completion callback.
+   * @returns {((result: "completed" | "aborted") => void | Promise<void>) | null} - File response completion callback.
+   */
+  getFileOnFinished() {
+    return this.fileOnFinished
+  }
+
   /**
    * Runs set file path.
    * @param {string} path - File path.
+   * @param {((result: "completed" | "aborted") => void | Promise<void>) | null} [onFinished] - Completion callback.
    * @returns {void} - No return value.
    */
-  setFilePath(path) {
+  setFilePath(path, onFinished = null) {
     this.filePath = path
+    this.fileOnFinished = onFinished
     this.body = null
   }
 

package/src/http-server/client/websocket-session.js

@@ -239,7 +239,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * Removes a closed connection from the session registry. Called by
    * `VelociousWebsocketConnection.close()` after it sends the final
    * `connection-closed` frame.
-   * @param {string} connectionId
+   * @param {string} connectionId - Closed connection identifier to remove.
    * @returns {void}
    */
   _removeConnection(connectionId) {
@@ -450,7 +450,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * The actual message dispatch, extracted so
    * `configuration.getWebsocketAroundRequest()` can wrap it in any
    * per-request context (AsyncLocalStorage, tracing, etc.).
-   * @param {WebsocketSessionMessage} message
+   * @param {WebsocketSessionMessage} message - Decoded client frame to dispatch by message type.
    * @returns {Promise<void>}
    */
   async _handleMessageInner(message) {
@@ -731,8 +731,8 @@ export default class VelociousHttpServerClientWebsocketSession {
    * fragmented message. Returns true when the fragment was accepted
    * and false when the per-message cap was hit and the socket has
    * been closed.
-   * @param {Buffer} payload
-   * @returns {boolean}
+   * @param {Buffer} payload - Continuation-frame bytes to append.
+   * @returns {boolean} - Whether the fragment was accepted.
    */
   _appendFragment(payload) {
     // Guard pushing first so `_enforceFragmentLimits` sees the final
@@ -750,7 +750,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * close frame, and tears the session down. Returns true when the
    * caller can continue processing, false when the session is being
    * closed.
-   * @returns {boolean}
+   * @returns {boolean} - Whether fragment processing may continue.
    */
   _enforceFragmentLimits() {
     if (this._fragmentedPayloads === null) return true
@@ -1024,7 +1024,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * The returned promise is stored at pause time and awaited at
    * resume time so we can reject resume attempts from a different
    * authenticated caller (signed out, swapped user, expired cookie).
-   * @returns {Promise<?>}
+   * @returns {Promise<?>} - Captured authenticated identity for resume validation.
    */
   async _captureResumeIdentity() {
     const resolver = this.configuration.getWebsocketSessionIdentityResolver?.()
@@ -1087,7 +1087,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * created one whose socket just connected) transfers state from
    * the paused session and instructs the client via
    * `session-resumed` or `session-gone`.
-   * @param {Record<string, ?>} message
+   * @param {Record<string, ?>} message - Session-resume frame containing the paused session identifier.
    * @returns {Promise<void>}
    */
   async _handleSessionResume(message) {
@@ -1168,7 +1168,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * Fires `onClose(reason)` on every live app-defined connection, then
    * drops them from the registry. No network frame is sent — the
    * socket is already going away.
-   * @param {"session_destroyed" | "grace_expired" | "error"} reason
+   * @param {"session_destroyed" | "grace_expired" | "error"} reason - Permanent teardown reason passed to each connection.
    * @returns {Promise<void>}
    */
   async _teardownConnections(reason) {
@@ -1194,7 +1194,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * registered connection class, stores it on `_connections`, and
    * fires `onConnect()`. Sends `connection-opened` on success or
    * `connection-error` on failure.
-   * @param {Record<string, ?>} message
+   * @param {Record<string, ?>} message - Connection-open frame naming the connection type and identifier.
    * @returns {Promise<void>}
    */
   async _handleConnectionOpen(message) {
@@ -1242,7 +1242,7 @@ export default class VelociousHttpServerClientWebsocketSession {
 
   /**
    * Handles a `{type: "connection-message"}` from the client.
-   * @param {Record<string, ?>} message
+   * @param {Record<string, ?>} message - Connection-message frame containing the target identifier and body.
    * @returns {Promise<void>}
    */
   async _handleConnectionMessage(message) {
@@ -1267,7 +1267,7 @@ export default class VelociousHttpServerClientWebsocketSession {
   /**
    * Handles a `{type: "connection-close"}` from the client — fires
    * `onClose("client_close")` and confirms with `connection-closed`.
-   * @param {Record<string, ?>} message
+   * @param {Record<string, ?>} message - Connection-close frame containing the target identifier.
    * @returns {Promise<void>}
    */
   async _handleConnectionClose(message) {
@@ -1296,7 +1296,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * Handles `{type: "channel-subscribe"}` — runs `canSubscribe()`,
    * registers with the Configuration's global routing registry on
    * success, and sends `channel-subscribed` or `channel-error`.
-   * @param {Record<string, ?>} message
+   * @param {Record<string, ?>} message - Channel-subscribe frame describing the requested subscription.
    * @returns {Promise<void>}
    */
   async _handleChannelSubscribe(message) {
@@ -1421,7 +1421,7 @@ export default class VelociousHttpServerClientWebsocketSession {
   /**
    * Handles `{type: "channel-unsubscribe"}` from the client — calls
    * `unsubscribed()` and sends `channel-unsubscribed`.
-   * @param {Record<string, ?>} message
+   * @param {Record<string, ?>} message - Channel-unsubscribe frame containing the subscription identifier.
    * @returns {Promise<void>}
    */
   async _handleChannelUnsubscribe(message) {