skills/plugins/document-navigator/docs/foundation/flow/queue-distribution

@suaveplan/queue-distribution - Worker-pool distribution layer: load-balancing strategies (round-robin / least-busy / weighted), worker pool, manager with retry + health checks, in-process LocalWorker. Transport-agnostic — HTTP and worker-thread plugins ship as separate packages.

Summary

Worker-pool distribution layer: load-balancing strategies, worker pool management, manager with retry and health checks, in-process LocalWorker. Transport-agnostic — HTTP and worker-thread transports ship as separate plugin packages (@suaveplan/queue-distribution-http, @suaveplan/queue-distribution-worker-thread).

The package is decoupled from @suaveplan/queue's Job model: distribution operates on a minimal DistributedTask<I, O> contract so it can serve any consumer that produces typed work units (queue, batch, RPC, agent dispatch).

Documentation tree

• errors — (no submodules)
  • queue-distribution-error — (no submodules)
• health-checker — (no submodules)
  • health-checker — (no submodules)
• internal — (no submodules)
  • noop-logger — (no submodules)
• base — (no submodules)
  • base — (no submodules)
• least-busy — (no submodules)
  • least-busy — (no submodules)
• round-robin — (no submodules)
  • round-robin — (no submodules)
• weighted — (no submodules)
  • weighted — (no submodules)
• manager — (no submodules)
  • manager-dispatch — dispatchWithRetry is the core retry loop of WorkerManager. It picks a worker via the configured `LoadBalancingStrat…
  • manager-supervisor — The supervisor module owns the worker-health side of WorkerManager: periodic health checks across the pool, restart o…
  • manager — (no submodules)
• observability — (no submodules)
  • instruments — (no submodules)
• pool — (no submodules)
  • pool — (no submodules)
• task — (no submodules)
  • task — (no submodules)
• worker — (no submodules) - abstract-metrics — abstract-metrics.ts carries the…
  • abstract — (no submodules)
    • abstract-metrics — abstract-metrics.ts carries the pure functions and the small accumulator used by AbstractWorker to track success/fa…
    • abstract — (no submodules)
  • local — (no submodules)
    • local — (no submodules)
  • worker — (no submodules) - abstract-metrics — abstract-metrics.ts carries the…

- [queue-distribution-error](./src/errors/queue-distribution-error.md) — _(no submodules)_- [health-checker](./src/health-checker/health-checker.md) — _(no submodules)_- [health-checker](./src/health-checker/health-checker.md) — _(no submodules)_- [internal](./src/internal/noop-logger.md) — _(no submodules)_- [noop-logger](./src/internal/noop-logger.md) — _(no submodules)_- [base](./src/load-balancing/base/base.md) — _(no submodules)_- [base](./src/load-balancing/base/base.md) — _(no submodules)_- [least-busy](./src/load-balancing/least-busy/least-busy.md) — _(no submodules)_- [least-busy](./src/load-balancing/least-busy/least-busy.md) — _(no submodules)_- [round-robin](./src/load-balancing/round-robin/round-robin.md) — _(no submodules)_- [round-robin](./src/load-balancing/round-robin/round-robin.md) — _(no submodules)_- [weighted](./src/load-balancing/weighted/weighted.md) — _(no submodules)_- [weighted](./src/load-balancing/weighted/weighted.md) — _(no submodules)_- [manager](./src/manager/manager.md) — _(no submodules)_- [manager-dispatch](./src/manager/manager-dispatch.md) — `dispatchWithRetry` is the core retry loop of `WorkerManager`. It picks a worker via the configured `LoadBalancingStrat…

• manager-supervisor — The supervisor module owns the worker-health side of WorkerManager: periodic health checks across the pool, restart o…
• manager — (no submodules)- observability — (no submodules)- instruments — (no submodules)- pool — (no submodules)- pool — (no submodules)- task — (no submodules)- task — (no submodules)- worker — (no submodules)- abstract — (no submodules)- abstract-metrics — abstract-metrics.ts carries the pure functions and the small accumulator used by AbstractWorker to track success/fa…
  • abstract — (no submodules)- local — (no submodules)- local — (no submodules)- worker — (no submodules)- queue-distribution-error — (no submodules)- health-checker — (no submodules)- health-checker — (no submodules)- internal — (no submodules)- noop-logger — (no submodules)- base — (no submodules)- base — (no submodules)- least-busy — (no submodules)- least-busy — (no submodules)- round-robin — (no submodules)- round-robin — (no submodules)- weighted — (no submodules)- weighted — (no submodules)- manager — (no submodules)- manager-dispatch — dispatchWithRetry is the core retry loop of WorkerManager. It picks a worker via the configured `LoadBalancingStrat…
• manager-supervisor — The supervisor module owns the worker-health side of WorkerManager: periodic health checks across the pool, restart o…
• manager — (no submodules)- observability — (no submodules)- instruments — (no submodules)- pool — (no submodules)- pool — (no submodules)- task — (no submodules)- task — (no submodules)- worker — (no submodules)- abstract-metrics — `abstract…
• abstract — (no submodules)- abstract-metrics — abstract-metrics.ts carries the pure functions and the small accumulator used by AbstractWorker to track success/fa…
  • abstract — (no submodules)- local — (no submodules)- local — (no submodules)- worker — (no submodules)- abstract-metrics — `abstract…
• queue-distribution-error — (no submodules)- health-checker — (no submodules)- health-checker — (no submodules)- internal — (no submodules)- noop-logger — (no submodules)- base — (no submodules)- base — (no submodules)- least-busy — (no submodules)- least-busy — (no submodules)- round-robin — (no submodules)- round-robin — (no submodules)- weighted — (no submodules)- weighted — (no submodules)- manager — (no submodules)- manager-dispatch — dispatchWithRetry is the core retry loop of WorkerManager. It picks a worker via the configured `LoadBalancingStrat…
  • manager-supervisor — The supervisor module owns the worker-health side of WorkerManager: periodic health checks across the pool, restart o…
  • manager — (no submodules)- observability — (no submodules)- instruments — (no submodules)- pool — (no submodules)- pool — (no submodules)- task — (no submodules)- task — (no submodules)- worker — (no submodules)- abstract-metrics — abstract-metrics.ts carries th…
  • abstract — (no submodules)- abstract-metrics — abstract-metrics.ts carries the pure functions and the small accumulator used by AbstractWorker to track success/fa…
    • abstract — (no submodules)- local — (no submodules)- local — (no submodules)- worker — (no submodules)- abstract-metrics — abstract-metrics.ts carries th…
• queue-distribution-error — (no submodules)- health-checker — (no submodules) - health-checker — (no submodules)- internal — (no submodules) - noop-logger — (no submodules)- base — (no submodules) - base — (no submodules)- least-busy — (no submodules) - least-busy — (no submodules)- round-robin — (no submodules) - round-robin — (no submodules)- weighted — (no submodules) - weighted — (no submodules)- manager — (no submodules) - manager-dispatch — dispatchWithRetry is the core retry loop of WorkerManager. It picks a worker via the configured `LoadBalancingStrat…
  • manager-supervisor — The supervisor module owns the worker-health side of WorkerManager: periodic health checks across the pool, restart o…
  • manager — (no submodules)- observability — (no submodules) - instruments — (no submodules)- pool — (no submodules) - pool — (no submodules)- task — (no submodules) - task — (no submodules)- worker — (no submodules) - abstract — (no submodules) - abstract-metrics — abstract-metrics.ts carries the pure functions and the small accumulator used by AbstractWorker to track success/fa…
    • abstract — (no submodules) - local — (no submodules) - local — (no submodules) - worker — (no submodules)

Install

bun add @suaveplan/queue-distribution

Quick start

import {
    LocalWorker,
    WorkerManager,
    WorkerPool,
} from "@suaveplan/queue-distribution";

const pool = new WorkerPool();
pool.addWorker(new LocalWorker({}, { id: "a", capacity: 4 }));
pool.addWorker(new LocalWorker({}, { id: "b", capacity: 4 }));
await pool.startAllWorkers();

const manager = new WorkerManager(pool, {
    autoHealthCheck: false,
    maxTaskRetries: 2,
});

const task = {
    id: "double",
    execute: async (n: number) => n * 2,
    getStatus: () => "PENDING" as const,
    setStatus: () => {},
    getMetadata: () => ({ createdAt: new Date(), attempts: 0 }),
};

console.log(await manager.assignTask(task, 21)); // 42

Modules

• Task contract — DistributedTask<I, O>, TaskStatus, TaskMetadata.
• Worker contract — Worker, WorkerStatus, WorkerHealth, WorkerInfo + Zod schemas.
• AbstractWorker — base class with lifecycle FSM, metrics, OTel emission.
• AbstractWorker metrics helpers — WorkerMetricsState accumulator.
• LocalWorker — in-process executor.
• Strategy base — LoadBalancingStrategy, AbstractLoadBalancingStrategy.
• RoundRobinStrategy.
• LeastBusyStrategy — optional EWMA performance bias.
• WeightedStrategy — injectable Rng.
• PeriodicHealthChecker — thresholds + cache + timeout.
• WorkerPool — CRUD + criteria-based search.
• WorkerManager — public dispatch surface.
• WorkerManager dispatch — bounded retry loop with @suaveplan/retry.
• WorkerManager supervisor — health-loop and restart logic.
• Errors — QueueDistributionError + 12 stable codes.
• Observability — every counter, histogram, span the package emits.
• Internal: NOOP_LOGGER.

Design highlights

• 100% test coverage (statements + branches + functions + lines) under provider: "istanbul".
• Injectable Clock, IdGenerator, Rng, LoggerLike everywhere — no Math.random / Date.now / uuid at module scope.
• AbortSignal threaded through every async public method.
• Retry routed through @suaveplan/retry; bounded loop, no recursion.
• Zod schemas at every public boundary (WorkerHealthSchema, WorkerInfoSchema, TaskMetadataSchema, …).
• Structured SuaveplanError subclasses with a frozen stable-code registry.
• Tree-shakeable via 15 per-feature subpath exports.

Status

This package is part of the rebuild — version 0.1.0 while it stabilises. Graduation to 1.0.0 follows the criteria in CLAUDE.md.