velocious 1.0.667 → 1.0.668

package/README.md

@@ -32,6 +32,7 @@
 * Per-record ability checks via `.abilities(...)` on frontend queries + `record.can(action)` (see [docs/abilities.md](docs/abilities.md))
 * Translated model attributes with current-locale relationship sorting (see [docs/translations.md](docs/translations.md))
 * Cross-process broadcast bus for `broadcastToChannel` via `velocious beacon`, including background job runner processes (see [docs/beacon.md](docs/beacon.md))
+* Websocket channel primitives for 1:N pub/sub over the shared session socket (`channel-subscribe` protocol): `matches()`-routed streams, interest-gated event-log persistence with 10-minute retention, stream-scoped `lastEventId` replay with `channel-replay-gap` gap reporting, and `{liveOnly: true}` channels that never reach the replay log (see [docs/websocket-channels.md](docs/websocket-channels.md))
 * Rails-style application process initializer teardown with immutable process identity, reverse idempotent shutdown, and explicit HTTP/background-job ownership (see [docs/application-process-lifecycle.md](docs/application-process-lifecycle.md))
 * Configurable HTTP server worker handlers plus backpressured, descriptor-only file responses with completion callbacks (see [docs/http-server.md](docs/http-server.md))
 * Explicit database-free in-process HTTP applications with optional request and buffered-response byte limits (see [docs/http-server.md](docs/http-server.md#database-free-applications))
@@ -125,7 +126,7 @@ Maintainers cutting a package release must follow the [Velocious release runbook
 
 # Docker development environment
 
-The checked-in root `Dockerfile` and `compose.yml` define one canonical `dev` service used by humans, CI, and agent systems alike (see [docs/docker-development-environment.md](docs/docker-development-environment.md)). The image is Ubuntu 26.04 LTS (pinned by digest) with Node.js 24.x from signed NodeSource, the universal apt coding/debugging baseline, and the newest published provider CLIs; it is source-independent — no project source is copied and no project dependencies are installed at image build time.
+The checked-in root `Dockerfile` and `compose.yml` define one canonical `dev` service used by humans, CI, and agent systems alike (see [docs/docker-development-environment.md](docs/docker-development-environment.md)). The image is Ubuntu 26.04 LTS (pinned by digest) with Node.js 24.x from signed NodeSource, the universal apt coding/debugging baseline, the newest published retained provider CLIs, and owner-pinned native Qwen Code 0.23.3; it is source-independent — no project source is copied and no project dependencies are installed at image build time.
 
 Prerequisites: Docker with the Compose v2 plugin, and this repository checked out at `$DEV_HOME_PATH/velocious` (default `DEV_HOME_PATH`: `/home/dev`).
 
@@ -179,10 +180,13 @@ Baselines are generated against a fresh checkout (no generated dummy `configurat
 # Testing
 
 Application tests may import the testing DSL from the independent public package.
-`@velocious/testing` `0.0.12` is the declaration and execution engine. Compatible
-installed copies share one protocol-1/schema-3 default registry. Velocious adapts each
-package-owned attempt with its database, request, profiling, and cleanup behavior; the
-existing Velocious facade exports the same declaration DSL and remains supported.
+`@velocious/testing` `0.0.14` owns framework-neutral discovery, filtering,
+execution, reporting, deterministic weighted grouping, profiling, and timing
+manifests. Compatible installed copies share one protocol-1/schema-3 default registry.
+Velocious retains application/configuration startup, database and transaction
+lifecycle, browser execution, environment handling, framework profile spans, and
+report translation. Existing Velocious import paths remain supported as thin
+delegating compatibility facades.
 
 ```js
 import {describe, expect, it} from "@velocious/testing"
@@ -245,7 +249,9 @@ export default async function configureTesting() {
 }
 ```
 
-Retry flaky tests by setting a retry count on the test args.
+Retry flaky tests by setting a retry count on the test args, or set CLI defaults for
+retries and lifecycle timeout. Import repeatable global setup before the testing
+configuration and test declarations with `--setup`.
 
 ```js
 describe("Tasks", () => {
@@ -253,6 +259,10 @@ it("retries a flaky check", {retry: 2}, async () => {})
 })
 ```
 
+```bash
+npx velocious test --retry=2 --timeout=30000 --setup=spec/setup.js spec/
+```
+
 Velocious prints the slowest tests after every run so suite hotspots are easy to spot. Each line shows the duration, full description and `file:line`.
 
 ```bash
@@ -295,7 +305,7 @@ npx velocious test:timing-manifest:merge --output tmp/test-timings.json \
 See [test profiling](docs/test-profiling.md) for lifecycle accounting, custom
 activity spans, schema, and privacy guarantees.
 
-Prefer waiting for a real signal or condition over sleeping a fixed duration. `waitForEvent(emitter, eventName, {timeoutMs, filter})` resolves the instant a matching event fires (a background job finishing, a model update, a websocket message) and rejects on timeout; for polling an arbitrary condition, use awaitery's `waitFor`. Both `@velocious/testing` and the backward-compatible `velocious/build/src/testing/test.js` facade are supported imports; the Velocious runner consumes public-package declarations and adds the framework-specific database, request, profiling, and cleanup behavior.
+Prefer waiting for a real signal or condition over sleeping a fixed duration. `waitForEvent(emitter, eventName, {timeoutMs, filter})` resolves the instant a matching event fires (a background job finishing, a model update, a websocket message) and rejects on timeout; for polling an arbitrary condition, use awaitery's `waitFor`. Both `@velocious/testing` and the backward-compatible `velocious/build/src/testing/test.js` facade are supported imports; the Velocious runner consumes public-package declarations and adds the framework-specific startup, database, request, browser, profile-span, and cleanup behavior.
 
 ```js
 import {waitForEvent} from "velocious/build/src/testing/test.js"
@@ -2224,6 +2234,16 @@ socket.send(JSON.stringify({
 }))
 ```
 
+### V2 channel registration, replay, and live-only channels
+
+`configuration.registerWebsocketChannel(name, ChannelClass)` registers a channel class for the `channel-subscribe` protocol — distinct from the `websocketChannelResolver` above, which serves the legacy `{type: "subscribe"}` path. Subscribers are routed by the class's `matches(broadcastParams)`, and publishers emit with `configuration.broadcastToChannel(name, broadcastParams, body)`.
+
+- **Stream-scoped replay.** Delivered `channel-message` frames carry the server `eventId`; a client can pass its last-seen `lastEventId` on (re)subscribe and the server replays only the persisted events belonging to that subscription's stream (10-minute retention, written only while the channel is interested). A checkpoint that expired or belongs to a different stream reports `channel-replay-gap` and the subscription continues with live delivery.
+- **Live-only channels.** `registerWebsocketChannel(name, ChannelClass, {liveOnly: true})` declares a channel that must never reach the replay event log; marking one interested throws, and the persistence decision rejects it even if stale interest state exists.
+- **Replayable params.** Channel classes can override the static `replayableBroadcastParams(broadcastParams)` hook to control which broadcast params are persisted for replay (for example, stripping server-only values).
+
+See [docs/websocket-channels.md](docs/websocket-channels.md) for the full wire protocol, V1/V2 gap semantics, and lifecycle guarantees.
+
 ## Raw websocket handlers
 
 If you need to accept custom websocket message formats (for example, a vendor that does not use the Velocious request/subscribe protocol), provide a `websocketMessageHandlerResolver` in your configuration. It receives the upgrade request and can return a handler object with `onOpen`, `onMessage`, `onClose`, and `onError` hooks:

package/build/configuration.js

@@ -408,6 +408,13 @@ export default class VelociousConfiguration {
      * @type {Map<string, typeof import("./http-server/websocket-channel.js").default>} */
     this._websocketChannelClasses = new Map()
 
+    /**
+     * Channel types registered with `{liveOnly: true}`: their traffic is
+     * never persisted for replay, and `markChannelInterested` rejects the
+     * name.
+     * @type {Set<string>} */
+    this._liveOnlyWebsocketChannels = new Set()
+
     /**
      * Stores the websocket channel subscriptions value.
      * @type {Map<string, Set<import("./http-server/websocket-channel.js").default>>} - channelType → live subscriptions across all sessions.
@@ -1126,6 +1133,7 @@ export default class VelociousConfiguration {
     }
 
     return {
+      liveOnlyChannels: Array.from(this._liveOnlyWebsocketChannels),
       pausedSessions: this._pausedWebsocketSessions.size,
       registeredChannels: Array.from(this._websocketChannelClasses.keys()),
       registeredConnections: Array.from(this._websocketConnectionClasses.keys()),
@@ -2966,12 +2974,15 @@ export default class VelociousConfiguration {
    * Clients subscribe via `{type: "channel-subscribe", channelType: name, ...}`.
    * @param {string} name - Client-facing channel type name.
    * @param {typeof import("./http-server/websocket-channel.js").default} ChannelClass - Websocket channel class.
+   * @param {{liveOnly?: boolean}} [options] - Registration options.
    * @returns {void}
    */
-  registerWebsocketChannel(name, ChannelClass) {
+  registerWebsocketChannel(name, ChannelClass, {liveOnly = false} = {}) {
     if (!name) throw new Error("Channel name is required")
     if (!ChannelClass) throw new Error("ChannelClass is required")
     this._websocketChannelClasses.set(name, ChannelClass)
+
+    if (liveOnly) this._liveOnlyWebsocketChannels.add(name)
   }
 
   /**
@@ -2983,6 +2994,17 @@ export default class VelociousConfiguration {
     return this._websocketChannelClasses.get(name)
   }
 
+  /**
+   * Whether a channel type was registered with `{liveOnly: true}`.
+   * Live-only channels are never persisted for replay: the event-log
+   * store's `markChannelInterested` throws for their names.
+   * @param {string} name - Channel type name to look up.
+   * @returns {boolean} - Whether the channel is declared live-only.
+   */
+  isWebsocketChannelLiveOnly(name) {
+    return this._liveOnlyWebsocketChannels.has(name)
+  }
+
   /**
    * Tracks a live channel subscription in the global routing registry.
    * Called by the session when `canSubscribe()` resolves truthy; the

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

@@ -1,8 +1,8 @@
 // @ts-check
 
 import BaseCommand from "../../../../../../cli/base-command.js"
+import { parseTimingManifestMergeArguments as parsePackageTimingManifestMergeArguments } from "@velocious/testing/node"
 import fs from "node:fs/promises"
-import path from "node:path"
 import { writeTimingManifest } from "../../../../../../testing/test-profile-output.js"
 import { mergeTestProfileTimingManifests } from "../../../../../../testing/timing-manifest.js"
 
@@ -51,24 +51,6 @@ export default class TestTimingManifestMerge extends BaseCommand {
   }
 }
 
-/**
- * Recognizes one output option spelling.
- * @param {string} argument - Current argument.
- * @param {string | undefined} nextArgument - Following argument.
- * @returns {{matched: boolean, skipNext: boolean, value: string | undefined}} - Parsed output option.
- */
-function timingManifestOutputArgument(argument, nextArgument) {
-  if (argument === "--output") {
-    return {matched: true, skipNext: true, value: nextArgument}
-  }
-
-  if (argument.startsWith("--output=")) {
-    return {matched: true, skipNext: false, value: argument.slice("--output=".length)}
-  }
-
-  return {matched: false, skipNext: false, value: undefined}
-}
-
 /**
  * Parses strict merge arguments and resolves their paths.
  * @param {string[]} processArgs - Raw CLI arguments, including command name.
@@ -76,33 +58,5 @@ function timingManifestOutputArgument(argument, nextArgument) {
  * @returns {TimingManifestMergeArguments} - Validated resolved paths.
  */
 export function parseTimingManifestMergeArguments(processArgs, cwd) {
-  const commandName = processArgs[0] || "test:timing-manifest:merge"
-  const inputPaths = []
-  let outputPath
-
-  for (let index = 1; index < processArgs.length; index++) {
-    const argument = processArgs[index]
-    const outputArgument = timingManifestOutputArgument(argument, processArgs[index + 1])
-
-    if (outputArgument.matched) {
-      if (!outputArgument.value || outputArgument.value.startsWith("-")) throw new Error("Missing value for --output")
-      if (outputPath) throw new Error("--output may only be provided once")
-      outputPath = path.resolve(cwd, outputArgument.value)
-      if (outputArgument.skipNext) index++
-      continue
-    }
-
-    if (argument.startsWith("-")) throw new Error(`Unknown argument for ${commandName}: ${argument}`)
-    inputPaths.push(path.resolve(cwd, argument))
-  }
-
-  if (!outputPath) throw new Error("--output is required")
-  if (inputPaths.length === 0) throw new Error("At least one rich test profile input is required")
-
-  const uniqueInputPaths = new Set(inputPaths)
-
-  if (uniqueInputPaths.size !== inputPaths.length) throw new Error("Each rich test profile input must be provided once")
-  if (uniqueInputPaths.has(outputPath)) throw new Error("Timing manifest output must not overwrite an input profile")
-
-  return {inputPaths, outputPath}
+  return parsePackageTimingManifestMergeArguments(processArgs.slice(1), {cwd})
 }

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

@@ -1,19 +1,22 @@
 // @ts-check
 
 import BaseCommand from "../../../../cli/base-command.js"
-import fs from "fs/promises"
 import path from "node:path"
 import picocolors from "picocolors"
 import TestFilesFinder from "../../../../testing/test-files-finder.js"
 import TestProfiler from "../../../../testing/test-profiler.js"
-import { formatTestProfileSummary, writeTestProfileOutputs } from "../../../../testing/test-profile-output.js"
+import {
+  formatTestProfileSummary,
+  loadTimingManifest,
+  resolveTestProfileOptions,
+  writeTestProfileOutputs
+} from "../../../../testing/test-profile-output.js"
 import TestRunner from "../../../../testing/test-runner.js"
 import TestSuiteSplitter from "../../../../testing/test-suite-splitter.js"
 import { normalizeExamplePatterns, parseFilters } from "../../../../testing/test-filter-parser.js"
 import {
   canonicalTimingManifestPath,
-  timingManifestFileSetHash,
-  validateTimingManifest
+  timingManifestFileSetHash
 } from "../../../../testing/timing-manifest.js"
 import { prepareSourcePeerPackage } from "../../source-peer-package.js"
 
@@ -44,8 +47,11 @@ export default class VelociousCliCommandsTest extends BaseCommand {
       groupNumber,
       profile,
       profileJsonPath,
+      retries,
+      setupFiles,
       timingManifestPath,
-      timingManifestOutputPath
+      timingManifestOutputPath,
+      timeoutMs
     } = parseFilters(this.processArgs || [])
     const profileOptions = resolveTestProfileOptions({
       cwd: process.cwd(),
@@ -70,7 +76,7 @@ export default class VelociousCliCommandsTest extends BaseCommand {
 
     /**
      * Finalizes requested outputs once for every command outcome.
-     * @param {string} status - Run status.
+     * @param {import("@velocious/testing/node").TestProfileStatus} status - Run status.
      * @returns {Promise<void>} - Resolves after requested outputs are written.
      */
     const finalizeProfile = async (status) => {
@@ -157,7 +163,10 @@ export default class VelociousCliCommandsTest extends BaseCommand {
         testFiles,
         lineFilters: testFilesFinder.getLineFiltersByFile(),
         examplePatterns: normalizeExamplePatterns(examplePatterns),
-        profiler
+        profiler,
+        retries,
+        setupFiles: setupFiles.map((setupFile) => path.resolve(process.cwd(), setupFile)),
+        timeoutMs
       })
       const activeTestRunner = testRunner
       let signalHandled = false
@@ -272,68 +281,7 @@ export default class VelociousCliCommandsTest extends BaseCommand {
   }
 }
 
-/**
- * Resolves and validates profiling paths before test discovery starts.
- * @param {object} args - Raw profiling options.
- * @param {string} args.cwd - Command working directory.
- * @param {boolean} args.profile - Whether console profiling was requested.
- * @param {string} [args.profileJsonPath] - Rich profile output path.
- * @param {string} [args.timingManifestPath] - Timing manifest input path.
- * @param {string} [args.timingManifestOutputPath] - Timing manifest output path.
- * @returns {{profile: boolean, profileJsonPath: string | undefined, timingManifestPath: string | undefined, timingManifestOutputPath: string | undefined}} - Resolved profiling options.
- */
-export function resolveTestProfileOptions({cwd, profile, profileJsonPath, timingManifestPath, timingManifestOutputPath}) {
-  const resolvedProfileJsonPath = profileJsonPath ? path.resolve(cwd, profileJsonPath) : undefined
-  const resolvedTimingManifestPath = timingManifestPath ? path.resolve(cwd, timingManifestPath) : undefined
-  const resolvedTimingManifestOutputPath = timingManifestOutputPath
-    ? path.resolve(cwd, timingManifestOutputPath)
-    : undefined
-
-  if (resolvedProfileJsonPath && resolvedTimingManifestOutputPath && resolvedProfileJsonPath === resolvedTimingManifestOutputPath) {
-    throw new Error("Test profiling output paths must be different")
-  }
-
-  if (resolvedTimingManifestPath && (
-    resolvedProfileJsonPath === resolvedTimingManifestPath ||
-    resolvedTimingManifestOutputPath === resolvedTimingManifestPath
-  )) {
-    throw new Error("Test profiling outputs must not overwrite --timing-manifest input")
-  }
-
-  return {
-    profile: profile || Boolean(resolvedProfileJsonPath || resolvedTimingManifestOutputPath),
-    profileJsonPath: resolvedProfileJsonPath,
-    timingManifestPath: resolvedTimingManifestPath,
-    timingManifestOutputPath: resolvedTimingManifestOutputPath
-  }
-}
-
-/**
- * Loads and validates an explicitly supplied plain JSON timing manifest.
- * @param {string | undefined} timingManifestPath - Timing manifest path.
- * @returns {Promise<Record<string, number> | undefined>} - Canonical manifest, or undefined when not requested.
- */
-export async function loadTimingManifest(timingManifestPath) {
-  if (!timingManifestPath) return undefined
-
-  let content
-
-  try {
-    content = await fs.readFile(timingManifestPath, "utf8")
-  } catch (error) {
-    throw new Error(`Failed to read timing manifest: ${timingManifestPath}`, {cause: error})
-  }
-
-  let parsed
-
-  try {
-    parsed = JSON.parse(content)
-  } catch (error) {
-    throw new Error(`Failed to parse timing manifest: ${timingManifestPath}`, {cause: error})
-  }
-
-  return validateTimingManifest(parsed, {source: `Timing manifest ${timingManifestPath}`})
-}
+export { loadTimingManifest, resolveTestProfileOptions }
 
 /**
  * Resolves how many slowest tests to report from the `VELOCIOUS_SLOW_TEST_COUNT`

package/build/frontend-models/websocket-channel.js

@@ -389,6 +389,24 @@ export default class FrontendModelWebsocketChannel extends VelociousWebsocketCha
     return broadcastParams?.model === this._modelName()
   }
 
+  /**
+   * Drops the server-only destroy-authorization snapshot before replay
+   * persistence. The snapshot is what makes replayed destroy events
+   * require a client resync, and the pre-delete row it captures must
+   * never be stored.
+   * @param {Record<string, import("./query.js").FrontendModelTransportValue> | null | undefined} broadcastParams - Params from `broadcastToChannel`.
+   * @returns {Record<string, import("./query.js").FrontendModelTransportValue> | null} - Persistable routing params.
+   */
+  static replayableBroadcastParams(broadcastParams) {
+    if (!broadcastParams) return null
+
+    const replayableParams = {...broadcastParams}
+
+    delete replayableParams.destroyAuthorizationRecord
+
+    return replayableParams
+  }
+
   /**
    * Runs debug snapshot.
    * @returns {Record<string, ReturnType<typeof JSON.parse>>} Debug-safe subscription details.

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

@@ -1843,8 +1843,13 @@ export default class VelociousHttpServerClientWebsocketSession {
 
   /**
    * Replays missed events from the persistent event-log store for a
-   * channel subscription that provided `lastEventId`. Sends each
-   * missed event as a `channel-message` with `replayed: true`.
+   * channel subscription that provided `lastEventId`. Delivery is
+   * stream-scoped: each persisted event's broadcast params are
+   * re-applied through the subscription's `matches()` — the same routing
+   * decision live delivery uses — so the subscription only replays events
+   * from its own stream of the channel. A checkpoint that belongs to a
+   * different stream (or is no longer retained) yields
+   * `channel-replay-gap` instead of cross-stream replay.
    * @param {object} args - Options.
    * @param {string} args.channelType - Channel type name (event-log key).
    * @param {string} args.lastEventId - Client's last-seen event id.
@@ -1858,7 +1863,7 @@ export default class VelociousHttpServerClientWebsocketSession {
 
     const checkpoint = await store.getEventById({channel: channelType, id: lastEventId})
 
-    if (!checkpoint) {
+    if (!checkpoint || !this._replayEventMatchesSubscription({channelType, event: checkpoint, subscription})) {
       this.sendJson({
         type: "channel-replay-gap",
         subscriptionId: subscription.subscriptionId,
@@ -1880,6 +1885,8 @@ export default class VelociousHttpServerClientWebsocketSession {
     for (const event of events) {
       if (subscription.isClosed()) break
 
+      if (!this._replayEventMatchesSubscription({channelType, event, subscription})) continue
+
       if (await subscription._requiresReplayGap(event.payload)) {
         this.sendJson({
           type: "channel-replay-gap",
@@ -1891,11 +1898,41 @@ export default class VelociousHttpServerClientWebsocketSession {
 
       await subscription.deliverBroadcast(
         /** @type {import("../websocket-channel.js").WebsocketJsonValue} */ (event.payload),
-        {eventId: event.id}
+        {
+          ...(event.params !== null ? {broadcastParams: event.params} : {}),
+          eventId: event.id
+        }
       )
     }
   }
 
+  /**
+   * Whether a persisted replay event belongs to this subscription's
+   * stream. A `matches()` failure means the stream membership cannot be
+   * proven, so the event is treated as not matching — the same isolation
+   * live delivery applies to a broken `matches()`.
+   * @param {object} args - Options.
+   * @param {string} args.channelType - Channel type name.
+   * @param {{params: Record<string, ReturnType<typeof JSON.parse>> | null}} args.event - Persisted replay event.
+   * @param {import("../websocket-channel.js").default} args.subscription - Live subscription.
+   * @returns {boolean} - Whether the event belongs to the subscription's stream.
+   */
+  _replayEventMatchesSubscription({channelType, event, subscription}) {
+    try {
+      return Boolean(subscription.matches(event.params || {}))
+    } catch (caughtError) {
+      const error = this._reportUnexpectedDispatchError(caughtError, {
+        channelType,
+        stage: "websocket-channel-replay",
+        subscriptionId: subscription.subscriptionId
+      })
+
+      this.logger.error(() => [`Websocket replay subscription ${subscription.subscriptionId} matches() threw`, error])
+
+      return false
+    }
+  }
+
   /**
    * Handles `{type: "channel-unsubscribe"}` from the client — calls
    * `unsubscribed()` and sends `channel-unsubscribed`.

package/build/http-server/websocket-channel.js

@@ -94,6 +94,20 @@ export default class VelociousWebsocketChannel {
    */
   matches(..._broadcastArgs) { return true }
 
+  /**
+   * Returns the broadcast params that may be persisted for replay.
+   * Persisted params are re-applied through `matches(broadcastParams)`
+   * when replaying missed events, so they must be JSON-serializable and
+   * safe to store. Override when `broadcastParams` carries server-only
+   * values that must never reach the event log (e.g. authorization
+   * snapshots).
+   * @param {WebsocketParams | null | undefined} broadcastParams - Params passed to `broadcastToChannel`.
+   * @returns {WebsocketParams | null} - Params to persist, or null to store none.
+   */
+  static replayableBroadcastParams(broadcastParams) {
+    return broadcastParams ?? null
+  }
+
   /**
    * Whether replaying a persisted broadcast would require a client resync.
    * Subclasses override this when replay storage deliberately omits metadata