@vellumai/assistant 0.11.5 → 0.11.6-staging.1

package/src/runtime/routes/live-voice-routes.test.ts

@@ -1,5 +1,5 @@
 /**
- * Tests for the live-voice preflight route.
+ * Tests for the live-voice preflight and session-end routes.
  *
  * The handler must run managed-speech defaulting first, then return the
  * live-voice credential readiness verdict verbatim:
@@ -7,6 +7,9 @@
  * - not-ready → passes through the missing gaps + userMessage
  * - defaulting is invoked BEFORE readiness is resolved
  *
+ * The session-end route is the out-of-band recovery path (LUM-3440): it
+ * reports whether it actually reclaimed the daemon's single live-voice slot.
+ *
  * NOTE: `bun mock.module` leaks across files. Run this file on its own
  * (`bun test <thisfile>`) — a multi-file run may report a spurious failure.
  */
@@ -14,9 +17,11 @@
 import { describe, expect, mock, test } from "bun:test";
 
 import type { LiveVoiceCredentialReadiness } from "../../live-voice/live-voice-credential-preflight.js";
+import type { LiveVoiceSessionReleaseResult } from "../../live-voice/live-voice-session-manager.js";
 
 const calls: string[] = [];
 let readiness: LiveVoiceCredentialReadiness = { status: "ready" };
+let releaseResult: LiveVoiceSessionReleaseResult = { released: false };
 
 mock.module("../../config/managed-speech-defaults.js", () => ({
   maybeDefaultSpeechToManaged: async () => {
@@ -31,12 +36,25 @@ mock.module("../../live-voice/live-voice-credential-preflight.js", () => ({
   },
 }));
 
+mock.module("../../live-voice/live-voice-manager.js", () => ({
+  getLiveVoiceSessionManager: () => ({
+    endActiveSession: async () => {
+      calls.push("endActiveSession");
+      return releaseResult;
+    },
+  }),
+}));
+
 const { ROUTES } = await import("./live-voice-routes.js");
 
 const preflightRoute = ROUTES.find(
   (r) => r.operationId === "live_voice_preflight_post",
 )!;
 
+const sessionEndRoute = ROUTES.find(
+  (r) => r.operationId === "live_voice_session_end_post",
+)!;
+
 describe("live_voice_preflight_post", () => {
   test("returns { status: 'ready' } when readiness reports ready", async () => {
     calls.length = 0;
@@ -71,3 +89,24 @@ describe("live_voice_preflight_post", () => {
     expect(calls).toEqual(["default", "resolve"]);
   });
 });
+
+describe("live_voice_session_end_post", () => {
+  test("reports the session it reclaimed", async () => {
+    calls.length = 0;
+    releaseResult = { released: true, sessionId: "session-1" };
+
+    const result = await sessionEndRoute.handler({});
+
+    expect(result).toEqual({ ended: true, sessionId: "session-1" });
+    expect(calls).toEqual(["endActiveSession"]);
+  });
+
+  test("reports no session rather than failing when the slot is free", async () => {
+    calls.length = 0;
+    releaseResult = { released: false };
+
+    const result = await sessionEndRoute.handler({});
+
+    expect(result).toEqual({ ended: false, sessionId: null });
+  });
+});

package/src/runtime/routes/live-voice-routes.ts

@@ -5,6 +5,11 @@
  * then report whether the daemon can run both audio legs of a live voice
  * session. Lets the web client verify voice is configured BEFORE opening the
  * voice-room WebSocket, instead of opening it and reacting to an error frame.
+ *
+ * POST /v1/live-voice/session/end releases whatever session holds the
+ * daemon's single live-voice slot. The out-of-band half of session closure:
+ * the in-band `end` frame needs a working transport, and the case that needs
+ * ending most is the one where the transport is already gone.
  */
 
 import { z } from "zod";
@@ -26,6 +31,17 @@ async function handleLiveVoicePreflight() {
   return resolveLiveVoiceCredentialReadiness();
 }
 
+async function handleLiveVoiceSessionEnd() {
+  const { getLiveVoiceSessionManager } =
+    await import("../../live-voice/live-voice-manager.js");
+
+  const result = await getLiveVoiceSessionManager().endActiveSession();
+  return {
+    ended: result.released,
+    sessionId: result.released ? result.sessionId : null,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
@@ -62,4 +78,22 @@ export const ROUTES: RouteDefinition[] = [
     }),
     handler: handleLiveVoicePreflight,
   },
+  {
+    operationId: "live_voice_session_end_post",
+    endpoint: "live-voice/session/end",
+    method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "End the active live voice session",
+    description:
+      "Release the assistant's single live-voice session slot, whichever client holds it. Reports whether a session was actually ended; a slot already tearing down reports false, since that teardown releases it on its own.",
+    tags: ["live-voice"],
+    responseBody: z.object({
+      ended: z.boolean(),
+      sessionId: z.string().nullable(),
+    }),
+    handler: handleLiveVoiceSessionEnd,
+  },
 ];

package/src/runtime/routes/migration-routes.ts

@@ -7,9 +7,11 @@
  * POST /v1/migrations/import          — commit a .vbundle archive import to disk.
  *
  * Accepts raw binary body (Content-Type: application/octet-stream),
- * multipart form data with a "file" field, or — on /import only — a JSON
- * body of shape `{ "url": "<signed-gcs-url>" }` that causes the daemon to
- * fetch the bundle from GCS and stream it through `streamCommitImport`.
+ * multipart form data with a "file" field, or a JSON body of shape
+ * `{ "url": "<signed-gcs-url>" }` (import only) or `{ "path": "<staged>" }`
+ * (import and import-preflight). The path form streams a file the CLI
+ * staged under `${workspace}/.restore-staging/`. The URL form fetches the
+ * bundle from GCS and streams it through `streamCommitImport`.
  * Returns structured validation results with is_valid flag and detailed
  * error descriptions.
  */
@@ -58,6 +60,10 @@ import {
   migrationJobs,
 } from "../migrations/job-registry.js";
 import { getOriginMode } from "../migrations/origin-mode.js";
+import {
+  resolveStagedImportPath,
+  StagedImportPathError,
+} from "../migrations/staged-import-path.js";
 import type {
   VBundleAssistantInfo,
   VBundleCompatibility,
@@ -81,6 +87,11 @@ import {
   type ImportCommitResult,
 } from "../migrations/vbundle-importer.js";
 import { streamCommitImport } from "../migrations/vbundle-streaming-importer.js";
+import {
+  readAndValidateManifest,
+  StreamingValidationError,
+} from "../migrations/vbundle-streaming-validator.js";
+import { parseVBundleStream } from "../migrations/vbundle-tar-stream.js";
 import { validateVBundle } from "../migrations/vbundle-validator.js";
 import {
   BadGatewayError,
@@ -806,6 +817,8 @@ async function extractFileData(
  * The file can be sent as:
  * - Raw binary body with Content-Type: application/octet-stream
  * - Multipart form data with a "file" field
+ * - JSON body `{ "path": "<staged-relative-or-absolute>" }` pointing at a
+ *   `.vbundle` the caller placed under `${workspace}/.restore-staging/`
  *
  * Returns:
  *   200: {
@@ -825,7 +838,13 @@ async function extractFileData(
 export async function handleMigrationImportPreflight({
   rawBody,
   headers,
+  body,
 }: RouteHandlerArgs) {
+  const contentType = headers?.["content-type"] ?? "";
+  if (contentType.includes("application/json")) {
+    return handleMigrationPreflightFromPath(body);
+  }
+
   const fileData = await extractFileData(rawBody, headers);
 
   try {
@@ -872,15 +891,18 @@ export async function handleMigrationImportPreflight({
  * 5. Verifies post-write integrity (SHA-256 check)
  * 6. Returns a detailed report of what was imported
  *
- * The bundle can be supplied in any of three ways:
+ * The bundle can be supplied as:
  * - Raw binary body with Content-Type: application/octet-stream
  * - Multipart form data with a "file" field
  * - JSON body `{ "url": "<signed-gcs-url>" }` (Content-Type:
  *   application/json). The daemon fetches and streams the archive
  *   through `streamCommitImport`, so peak memory stays bounded by a
  *   single tar entry rather than bundle size.
+ * - JSON body `{ "path": "<staged>" }` pointing at a `.vbundle` the
+ *   caller placed under `${workspace}/.restore-staging/`. The daemon
+ *   streams that file through `streamCommitImport`.
  *
- * Returns (all three paths):
+ * Returns:
  *   200: {
  *     success: true,
  *     summary: { total_files, files_created, files_overwritten, files_skipped, backups_created },
@@ -900,11 +922,10 @@ export async function handleMigrationImport(
   args: RouteHandlerArgs,
 ): Promise<unknown> {
   const { body, rawBody, headers } = args;
-  // JSON body means the caller is asking us to fetch the bundle from a
-  // signed URL and stream it through the importer.
+  // JSON body is either a signed URL fetch or a staged local-file stream.
   const contentType = headers?.["content-type"] ?? "";
   if (contentType.includes("application/json")) {
-    return handleMigrationImportFromUrl(body);
+    return handleMigrationImportFromJson(body);
   }
 
   const fileData = await extractFileData(rawBody, headers);
@@ -1015,6 +1036,8 @@ const URL_FETCH_TIMEOUT_MS = 60 * 60 * 1000;
 
 const MigrationImportUrlBody = z.object({ url: z.string().min(1) });
 
+const MigrationImportPathBody = z.object({ path: z.string().min(1) });
+
 const MigrationImportFromGcsBody = z.object({ bundle_url: z.string().url() });
 
 /**
@@ -1591,6 +1614,174 @@ async function runGcsImport(
     : { ...result.report };
 }
 
+/**
+ * Dispatch a JSON import body to the URL-fetch or staged-path streamer.
+ * The body must include exactly one of `url` or `path`.
+ */
+async function handleMigrationImportFromJson(
+  body: Record<string, unknown> | undefined,
+): Promise<unknown> {
+  const hasUrl = typeof body?.url === "string";
+  const hasPath = typeof body?.path === "string";
+  if (hasUrl && hasPath) {
+    throw new BadRequestError(
+      "Request body must include exactly one of url or path",
+    );
+  }
+  if (hasPath) {
+    return handleMigrationImportFromPath(body);
+  }
+  return handleMigrationImportFromUrl(body);
+}
+
+async function handleMigrationImportFromPath(
+  body: Record<string, unknown> | undefined,
+): Promise<unknown> {
+  const parsed = MigrationImportPathBody.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      "Request body must be { path: string } with a non-empty path",
+    );
+  }
+
+  let resolvedPath: string;
+  try {
+    resolvedPath = resolveStagedImportPath(parsed.data.path, getWorkspaceDir());
+  } catch (err) {
+    if (err instanceof StagedImportPathError) {
+      throw new BadRequestError(err.message);
+    }
+    throw err;
+  }
+
+  const source = createReadStream(resolvedPath);
+  const pathResolver = new DefaultPathResolver(
+    getWorkspaceDir(),
+    getWorkspaceHooksDir(),
+  );
+  let credentialsImported: CredentialImportSummary | undefined;
+  const credentialImportWarningSink: CredentialWarningSink = { warnings: [] };
+
+  try {
+    const result = await streamCommitImport({
+      source,
+      pathResolver,
+      workspaceDir: getWorkspaceDir(),
+      importCredentials: async (bundleCredentials) => {
+        credentialsImported = await importBundleCredentialsIntoCes(
+          bundleCredentials,
+          credentialImportWarningSink,
+        );
+      },
+    });
+
+    if (!result.ok) {
+      throwImportCommitFailure(result);
+    }
+
+    if (credentialImportWarningSink.warnings.length > 0) {
+      result.report.warnings.push(...credentialImportWarningSink.warnings);
+    }
+
+    await reconcileVellumMetadataFromCes(result.report);
+    appendNewerMigrationWarningsIfAny(result.report);
+    return importCommitSuccessResult(result.report, credentialsImported);
+  } catch (err) {
+    if (err instanceof RouteError) {
+      throw err;
+    }
+    log.error({ err }, "Unexpected error during staged-path import");
+    throw new InternalError(
+      err instanceof Error ? err.message : "Unexpected import error",
+    );
+  } finally {
+    source.destroy();
+  }
+}
+
+async function handleMigrationPreflightFromPath(
+  body: Record<string, unknown> | undefined,
+): Promise<unknown> {
+  const parsed = MigrationImportPathBody.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      "Request body must be { path: string } with a non-empty path",
+    );
+  }
+
+  let resolvedPath: string;
+  try {
+    resolvedPath = resolveStagedImportPath(parsed.data.path, getWorkspaceDir());
+  } catch (err) {
+    if (err instanceof StagedImportPathError) {
+      throw new BadRequestError(err.message);
+    }
+    throw err;
+  }
+
+  const source = createReadStream(resolvedPath);
+  try {
+    const entries = parseVBundleStream(source);
+    const first = await entries.next();
+    if (first.done) {
+      return {
+        can_import: false,
+        validation: {
+          is_valid: false as const,
+          errors: [
+            {
+              code: "empty_archive",
+              message: "Bundle archive is empty",
+            },
+          ],
+        },
+      };
+    }
+
+    let manifest;
+    try {
+      ({ manifest } = await readAndValidateManifest(first.value));
+    } catch (err) {
+      if (err instanceof StreamingValidationError) {
+        return {
+          can_import: false,
+          validation: {
+            is_valid: false as const,
+            errors: [
+              {
+                code: err.code,
+                message: err.message,
+                ...(err.archivePath !== undefined && { path: err.archivePath }),
+              },
+            ],
+          },
+        };
+      }
+      throw err;
+    }
+
+    for await (const entry of entries) {
+      entry.body.resume();
+    }
+
+    const pathResolver = new DefaultPathResolver(
+      getWorkspaceDir(),
+      getWorkspaceHooksDir(),
+    );
+    return analyzeImport({ manifest, pathResolver });
+  } catch (err) {
+    if (err instanceof RouteError) {
+      throw err;
+    }
+    log.error({ err }, "Unexpected error during staged-path preflight");
+    throw new InternalError(
+      err instanceof Error ? err.message : "Unexpected import preflight error",
+    );
+  } finally {
+    source.destroy();
+  }
+}
+
 /**
  * Handle a JSON `{ "url": "..." }` body on POST /v1/migrations/import.
  *
@@ -2142,8 +2333,17 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Dry-run import analysis",
     description:
-      "Validate a .vbundle archive and return a report of what would change on import without modifying data.",
+      "Validate a .vbundle archive and return a report of what would change on import without modifying data. Accepts raw bytes, multipart form data, or JSON `{ path }` pointing at a file staged under the workspace `.restore-staging` directory.",
     tags: ["migrations"],
+    requestBody: z.object({
+      path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "Workspace-relative or absolute path to a staged .vbundle under .restore-staging (JSON body path only).",
+        ),
+    }),
     responseBody: z.object({
       can_import: z.boolean(),
       summary: z.object({}).passthrough(),
@@ -2163,15 +2363,23 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Import a .vbundle archive",
     description:
-      "Commit a .vbundle archive import to disk — destructive. Accepts the bundle as raw bytes (application/octet-stream), multipart/form-data, or a JSON body with `{ url }` carrying a signed URL the daemon fetches.",
+      "Commit a .vbundle archive import to disk — destructive. Accepts the bundle as raw bytes (application/octet-stream), multipart/form-data, a JSON body with `{ url }` carrying a signed URL the daemon fetches, or a JSON body with `{ path }` pointing at a file staged under the workspace `.restore-staging` directory.",
     tags: ["migrations"],
     requestBody: z.object({
       url: z
         .string()
         .url()
+        .optional()
         .describe(
           "A signed GCS URL pointing to the .vbundle archive (JSON body path only).",
         ),
+      path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "Workspace-relative or absolute path to a staged .vbundle under .restore-staging (JSON body path only).",
+        ),
     }),
     additionalResponses: {
       "502": {

package/src/runtime/routes/oauth-commands-routes.ts

@@ -19,6 +19,7 @@ import {
   ServicesSchema,
 } from "../../config/schemas/services.js";
 import type { OAuthConnectionRequest } from "../../oauth/connection.js";
+import { jsonSafeOAuthBody } from "../../oauth/connection.js";
 import {
   resolveOAuthConnection,
   type ResolveOAuthConnectionOptions,
@@ -39,6 +40,10 @@ import { VellumPlatformClient } from "../../platform/client.js";
 import { withValidToken } from "../../security/token-manager.js";
 import { matchHostPattern } from "../../tools/credentials/host-pattern-match.js";
 import { getLogger } from "../../util/logger.js";
+import {
+  findContentTypeHeader,
+  parseRequestBodyData,
+} from "../../util/oauth-request-body.js";
 import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -721,15 +726,12 @@ async function handleToken({ body = {} }: RouteHandlerArgs) {
 // Request handler
 // ---------------------------------------------------------------------------
 
-function tryJsonParse(raw: string): unknown {
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return raw;
-  }
-}
-
-function readBodyData(data: string): unknown {
+/**
+ * Resolve a raw `data` string into a request body. A non-JSON Content-Type
+ * keeps the payload as the caller's exact string so multipart and other
+ * byte-sensitive payloads survive; files are read as UTF-8 text.
+ */
+function readBodyData(data: string, contentType: string | undefined): unknown {
   if (data === "@-") {
     // This handler runs inside the daemon, whose stdin is a supervisor pipe
     // or /dev/null — never the caller's terminal. Stdin-based body input is
@@ -742,14 +744,13 @@ function readBodyData(data: string): unknown {
 
   if (data.startsWith("@")) {
     const filePath = data.slice(1);
-    const raw = readFileSync(filePath, "utf-8");
-    return tryJsonParse(raw);
+    return parseRequestBodyData(readFileSync(filePath, "utf-8"), contentType);
   }
 
-  return tryJsonParse(data);
+  return parseRequestBodyData(data, contentType);
 }
 
-async function handleRequest({ body = {} }: RouteHandlerArgs) {
+export async function handleRequest({ body = {} }: RouteHandlerArgs) {
   const b = body as {
     provider: string;
     url: string;
@@ -852,12 +853,14 @@ async function handleRequest({ body = {} }: RouteHandlerArgs) {
   let reqBody: unknown = undefined;
   const query: Record<string, string | string[]> = { ...queryFromUrl };
 
-  // Use pre-parsed data from CLI, or fall back to raw data string for direct API callers
+  // Use pre-parsed data from CLI, or fall back to raw data string for direct
+  // API callers. A string here (a multipart or form-encoded payload) stays a
+  // string all the way to the provider; only objects are serialized as JSON.
   const resolvedData =
     b.parsed_data !== undefined
       ? b.parsed_data
       : b.data !== undefined
-        ? readBodyData(b.data)
+        ? readBodyData(b.data, findContentTypeHeader(b.headers))
         : undefined;
 
   if (resolvedData !== undefined) {
@@ -924,16 +927,20 @@ async function handleRequest({ body = {} }: RouteHandlerArgs) {
   };
 
   const response = await connection.request(req);
+  const encodedBody = jsonSafeOAuthBody(response.body);
 
   const result: Record<string, unknown> = {
     ok: response.status >= 200 && response.status < 300,
     status: response.status,
     headers: response.headers,
-    body: response.body,
+    body: encodedBody.body,
     // Which connected account actually served the request, so the caller can
     // tell whether the intended account was used.
     account: connection.accountInfo,
   };
+  if (encodedBody.bodyEncoding) {
+    result.bodyEncoding = encodedBody.bodyEncoding;
+  }
 
   // Surface a caller-visible warning when the provider had several active
   // connections and no account was pinned — the model must see that a

package/src/runtime/routes/plugins-routes.ts

@@ -1641,29 +1641,6 @@ function mapTogglePluginError(err: unknown): RouteError {
   );
 }
 
-/**
- * Converge plugin-declared schedules against the sentinel this route just
- * wrote, so a disabled plugin's rows disarm now rather than at the
- * reconciler's next backstop sweep.
- *
- * Fire-and-forget: the toggle itself already succeeded on disk, so a reconcile
- * failure must not turn it into a route error. Imported lazily, matching the
- * plugin source reconcile's own hook, to keep the schedule and notification
- * modules out of this route module's static graph. The scheduler applies the
- * sentinel at fire time as well, so a slow or failed pass here delays the row
- * bookkeeping without letting a disabled plugin run.
- */
-function reconcilePluginSchedulesInBackground(): void {
-  void import("../../schedule/plugin-schedule-reconciler.js")
-    .then(({ reconcilePluginSchedules }) => reconcilePluginSchedules())
-    .catch((err: unknown) => {
-      log.error(
-        { err },
-        "plugin schedule reconcile after a plugin toggle failed",
-      );
-    });
-}
-
 /**
  * Toggle a plugin's `.disabled` sentinel through the shared toggle-plugin lib,
  * then publish a generic `sync_changed(plugins:list)` so every client refetches
@@ -1694,15 +1671,22 @@ async function handleEnablePlugin({
   return { ok: true };
 }
 
-function handleDisablePlugin({ pathParams = {}, headers }: RouteHandlerArgs) {
+async function handleDisablePlugin({
+  pathParams = {},
+  headers,
+}: RouteHandlerArgs) {
   try {
     disablePlugin(pathParams.name ?? "");
-    publishPluginsChanged(getOriginClientId(headers));
-    reconcilePluginSchedulesInBackground();
-    return { ok: true };
   } catch (err) {
     throw mapTogglePluginError(err);
   }
+  // Same poke enable uses. The sentinel hides tools and hooks at read time,
+  // but a plugin that already ran `init` still owns in-process work (a live
+  // gRPC subscribe, a poll worker). The source reconcile is what runs
+  // `shutdown` and drops that work before this route returns.
+  await reconcilePluginSourcesNow();
+  publishPluginsChanged(getOriginClientId(headers));
+  return { ok: true };
 }
 
 // ---------------------------------------------------------------------------
@@ -2146,7 +2130,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Disable a plugin",
     description:
-      "Disable a plugin in this workspace by dropping a `.disabled` sentinel, mirroring the CLI's `assistant plugins disable <name>`. The change is honored live at read time by every tool / injector / hook gate — no restart required. Broadcasts a `sync_changed` invalidation carrying the `plugins:list` tag so other clients refetch `GET /v1/plugins`. An already-disabled plugin returns 409; a user plugin with no directory returns 404 (default plugins are stubbed on demand via the `default-` prefix); a malformed name returns 400.",
+      "Disable a plugin in this workspace by dropping a `.disabled` sentinel, mirroring the CLI's `assistant plugins disable <name>`. Awaits the same source reconcile enable uses so the plugin's shutdown hook runs. Tools, injectors, and hook gates also honor the sentinel at read time. Broadcasts a `sync_changed` invalidation carrying the `plugins:list` tag so other clients refetch `GET /v1/plugins`. An already-disabled plugin returns 409; a user plugin with no directory returns 404 (default plugins are stubbed on demand via the `default-` prefix); a malformed name returns 400.",
     tags: ["plugins"],
     pathParams: [
       {

package/src/runtime/routes/question-routes.ts

@@ -16,6 +16,10 @@
  * one-element batch. That branch only succeeds against a single-question
  * batch — multi-question batches reject it with a helpful error.
  *
+ * Any assistant serving this route also accepts `submit`, so the shim serves
+ * only clients that cannot tell which assistant they are talking to: a stale
+ * browser bundle posts the single-question body against a batch-capable route.
+ *
  * Cross-talk safety: pending interactions of other kinds (`confirmation`,
  * `secret`, host_*, etc.) return 404 here rather than being mis-resolved.
  *
@@ -194,6 +198,8 @@ function buildSubmissions(
   // prompter stashed the ordered ids on the interaction metadata so we can
   // pick the (single) target questionId here.
   const { orderedIds } = readBatchMetadata(interaction);
+  // `QuestionPrompter` is the only registrar of a `question` interaction and
+  // refuses an empty `questions` array, so this guard is unreachable.
   if (orderedIds.length === 0) {
     throw new QuestionBatchValidationError(
       "Legacy single-question payload requires a registered batch with at least one question",