Polish task enqueue path and queue-isolation docs

Small follow-ups from review:

 -  Document that tasks must be defined before startQueue() (or the
    first request); workers for dedicated per-task queues are only
    registered when the queue machinery starts, so a queue defined
    later never gets a worker.
 -  Return early from the enqueue path when no payloads are given,
    instead of reaching enqueueMany()/Promise.all with an empty
    batch, whose backend behavior is undefined.
 -  Rename #enqueueSingular to #encodeTaskMessage; it encodes and
    builds a TaskMessage but does not enqueue anything.
 -  Fix a comment typo in the codec.

fedify-dev#803

Assisted-by: Claude Code:claude-fable-5

Author: 2chanhaeng

docs/manual/tasks.md

@@ -215,6 +215,12 @@ const transcodeVideo = federation.defineTask("transcodeVideo", {
 });
 ~~~~
 
+Workers for dedicated per-task queues are registered when the queue
+machinery starts, so define every task before `~Federation.startQueue()`
+is called (or, without `~FederationOptions.manuallyStartQueue`, before the
+first request is handled); a per-task queue defined later never gets
+a worker.
+
 The queue for a task is resolved in order: the per-task `queue`, then the
 federation's `task` queue, then the outbox queue.  Deployments that must
 *not* silently share the outbox queue can opt out of the last step with

packages/fedify/src/federation/middleware.ts

@@ -3680,6 +3680,7 @@ export class ContextImpl<TContextData> implements Context<TContextData> {
           "createFederation() or to defineTask().",
       );
     }
+    if (items.length < 1) return;
     const delay = options.delay == null
       ? undefined
       : Temporal.Duration.from(options.delay);
@@ -3688,7 +3689,7 @@ export class ContextImpl<TContextData> implements Context<TContextData> {
     // `map` preserves order, and a rejected encode (validation failure) rejects
     // the whole batch before anything is enqueued, keeping fail-fast intact.
     const messages: TaskMessage[] = await Promise.all(
-      items.map(this.#enqueueSingular(task, options)),
+      items.map(this.#encodeTaskMessage(task, options)),
     );
     const enqueueOptions = { delay, orderingKey: options.orderingKey };
     if (messages.length === 1) {
@@ -3700,7 +3701,7 @@ export class ContextImpl<TContextData> implements Context<TContextData> {
     }
   }
 
-  #enqueueSingular = <TData>(
+  #encodeTaskMessage = <TData>(
     task: TaskDefinition<TContextData, TData>,
     options: TaskEnqueueOptions,
   ) =>

packages/fedify/src/federation/tasks/codec.ts

@@ -43,7 +43,7 @@ export default class TaskCodec {
     if (node === null || typeof node !== "object") return node;
     if (seen.has(node)) return seen.get(node);
     const reviver = this.#classRevivers.find(([filter]) => filter(node));
-    // devalue can handled non-container objects.
+    // devalue can handle non-container objects.
     if (reviver == null) return node;
     const [, init, set] = reviver;
     // @ts-ignore tsc faults

packages/fedify/src/federation/tasks/tasks.test.ts

@@ -399,6 +399,28 @@ test("Context.enqueueTask() end-to-end", async (t) => {
       strictEqual(queue.enqueued.length, 2);
     },
   );
+
+  await t.step(
+    "enqueueTaskMany() with no payloads touches no queue",
+    async () => {
+      const queue = new MockQueue({ supportsEnqueueMany: true });
+      const federation = createFederation<void>({
+        ...baseOptions,
+        queue: { task: queue },
+      });
+      const task = federation.defineTask("bulk-empty", {
+        schema: stringSchema,
+        handler: () => {},
+      });
+      const ctx = federation.createContext(
+        new URL("https://example.com/"),
+        undefined,
+      );
+      await ctx.enqueueTaskMany(task, []);
+      strictEqual(queue.enqueued.length, 0);
+      strictEqual(queue.enqueuedMany.length, 0);
+    },
+  );
 });
 
 test("task queue routing", async (t) => {