@edgehero/pi-dispatch-receiver 1.4.0 → 2.0.0

package/src/poller.mjs

@@ -108,13 +108,14 @@
 import { createSign } from "node:crypto";
 import { readFile as fsReadFile } from "node:fs/promises";
 import { configError } from "@edgehero/pi-dispatch/config";
-import { parseConnection } from "@edgehero/pi-dispatch/connection";
+import { judgeValkeyAtStart, makeRedisClient, parseConnection, valkeyClientContext } from "@edgehero/pi-dispatch/connection";
 import { makeGitHubAuth } from "@edgehero/pi-dispatch/get-token";
 import { enqueueGitHubJob, makeQueue } from "@edgehero/pi-dispatch/queue";
 import { filter, hasCloseTriggers, wantsCloserAuthority } from "./filter.mjs";
 import { makeResolveGitHubAuthority } from "./github-members.mjs";
 import { parseSubset } from "./receiver.mjs";
 import { loadPollerConfig } from "./poller-config.mjs";
+import { retryIdentity } from "./boot-retry.mjs";
 
 const API_URL = "https://api.github.com";
 // 35 days: strictly outlives the 31-day gh-* job retention -- see the header's cursor/TTL section.
@@ -153,9 +154,10 @@ class RateLimited extends Error {
  * Boot the poller: config, HARD-FAIL identity, repo set, then the cycle loop. Collaborators are
  * injected with real defaults (start.mjs's convention), so the whole producer is testable offline
  * with no GitHub, no Valkey, and no timers:
- *   { fetchFn, redis, queueFn, out, now, random, sleep, selfIdFn, tokenFn, fsDeps }
+ *   { fetchFn, redis, queueFn, out, now, random, sleep, signals, selfIdFn, tokenFn, fsDeps }
  * Returns `{ stop, done }`: `stop()` ends the loop after the in-flight work; `done` resolves once
- * owned connections are closed.
+ * owned connections are closed, with the inter-cycle default-sleep timer cleared by then (issue
+ * #325) -- after `done`, no timer armed by the poller remains.
  */
 export async function startPoller(env = process.env, deps = {}) {
 	const {
@@ -164,6 +166,12 @@ export async function startPoller(env = process.env, deps = {}) {
 		now = Date.now,
 		random = Math.random,
 		sleep,
+		// The signal gate, decoupled from the sleep default (issue #325): `sleep === undefined` used to
+		// double as the "real run" flag, which made the REAL default timer unarmable under test without
+		// also registering process-wide SIGTERM/SIGINT handlers -- the exact leak the gate exists to
+		// prevent. A test that arms the real sleep passes `signals: false`; the one production caller
+		// (cli.mjs, no deps) keeps handlers exactly as before through this default.
+		signals = sleep === undefined,
 		redis,
 		queueFn,
 		selfIdFn,
@@ -172,7 +180,11 @@ export async function startPoller(env = process.env, deps = {}) {
 		fsDeps = {},
 		makeAuth = makeGitHubAuth,
 		makeQueueFn = makeQueue,
+		// Issue #464 (gate round 3): how the poller builds its own Valkey client; a seam, so a test sees none built.
+		makeRedisFn = makeRedisClient,
 		makeResolveGitHubAuthority: makeResolveGitHubAuthorityFn = makeResolveGitHubAuthority,
+		// Issue #464 (gate round 3): the start-time judgement of VALKEY_URL, as the receiver's (start.mjs).
+		judgeValkey = (url, opts) => judgeValkeyAtStart(url, valkeyClientContext({ env: opts.env }), { now: opts.now, ...(opts.sleep ? { sleep: opts.sleep } : {}) }),
 	} = deps;
 
 	const cfg = loadPollerConfig(env, fsDeps);
@@ -181,9 +193,21 @@ export async function startPoller(env = process.env, deps = {}) {
 	// the bot-loop guard's sole input, and a poller running without it would read the harness's own
 	// completion comment next cycle and enqueue it -- an unbounded paid recursion, only slower than the
 	// webhook version. No try/catch: an unresolvable identity must prevent the loop from ever starting.
+	// A TRANSIENT failure retries in-process under the same window serve uses (issue #318): a
+	// pure-polling deployment loses work to a stopped process just as surely as a webhook one.
+	//
+	// The default sleep sits above the gate because the gate sleeps too (issue #318); the boot retry
+	// simply awaits its cancellable promise to completion, so `cancel` is the LOOP's concern alone.
+	const sleepFn = sleep ?? cancellableSleep;
 	let auth = null;
+	// `auth ??= await ...` assigns only when the mint RESOLVES, so a retried getAuth re-invokes
+	// makeAuth. Caching the PROMISE instead would memoize the first failure and turn the retry loop
+	// into a rethrow spinner -- pinned by the poller's retry test.
 	const getAuth = async () => (auth ??= await makeAuth(cfg.github));
-	const selfId = selfIdFn ? await selfIdFn(cfg.github) : (await getAuth()).selfId;
+	const selfId = await retryIdentity(
+		() => (selfIdFn ? selfIdFn(cfg.github) : getAuth().then((a) => a.selfId)),
+		{ forge: "github", windowMs: cfg.identityRetryWindowMs, log: out, now, sleep: sleepFn },
+	);
 	out({ event: "self_identity", id: selfId, source: cfg.github.source });
 
 	// The polling credential comes from the same auth config the worker validates. pat/gh hand back
@@ -210,9 +234,12 @@ export async function startPoller(env = process.env, deps = {}) {
 	// queue connection: a long-running producer should survive a Valkey restart.
 	let redisClient = redis ?? null;
 	let ownRedis = false;
+	// Issue #464 (gate round 3): judged before this process builds its own Valkey clients: a refusal exits 2, nothing
+	// answering for 20 s exits 1, never a poller running on a queue that cannot connect.
+	if (redisClient === null || queueFn === undefined || queueFn === null) await judgeValkey(cfg.valkeyUrl, { env, now, sleep });
 	if (redisClient === null) {
-		const { default: Redis } = await import("ioredis");
-		redisClient = new Redis(cfg.valkeyUrl);
+		// Through connection.mjs, as every Valkey client of this project (issue #464): it judges and pins the address.
+		redisClient = makeRedisFn(cfg.valkeyUrl);
 		ownRedis = true;
 	}
 
@@ -263,7 +290,6 @@ export async function startPoller(env = process.env, deps = {}) {
 		stopped = true;
 		wake();
 	};
-	const sleepFn = sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
 
 	const done = (async () => {
 		let cycleNo = 0;
@@ -328,14 +354,27 @@ export async function startPoller(env = process.env, deps = {}) {
 			// in one synchronized stampede).
 			let delayMs = Math.max(cfg.intervalSeconds, stats.minDelaySeconds) * 1000;
 			if (rateResetMs !== null) delayMs = Math.max(delayMs, rateResetMs - now() + jitterMs(random));
-			await Promise.race([sleepFn(delayMs), stopWaker]);
+			// Hold the sleep so the LOSER can be cleared: when stop() wins this race, an uncancelled
+			// default timer stays armed for up to a full poll interval after `done` resolves (issue
+			// #325) -- masked in production by the signal handler's process.exit(0) below, and real for
+			// every caller that stops the poller without exiting. Optional-chained because injected
+			// test sleeps are plain promises carrying no cancel; their call count and arguments are
+			// untouched, and a rejecting one still propagates through the finally.
+			const nap = sleepFn(delayMs);
+			try {
+				await Promise.race([nap, stopWaker]);
+			} finally {
+				nap.cancel?.();
+			}
 		}
 		await closeOwned();
 	})();
 
-	// Signal handlers only on a real run (no injected sleep) -- start.mjs's rule, same reason: under
-	// test injection the fakes are per-test, and a process-wide handler would leak across tests.
-	if (sleep === undefined) {
+	// Signal handlers only on a real run (`signals`, defaulting from the sleep seam) -- start.mjs's
+	// rule, same reason: under test injection the fakes are per-test, and a process-wide handler would
+	// leak across tests. Its own seam since issue #325, so a test can arm the REAL default sleep
+	// without inheriting the handlers.
+	if (signals) {
 		const shutdown = async (signal) => {
 			out({ event: "poller_stopping", signal });
 			stop();
@@ -358,6 +397,27 @@ function jitterMs(random) {
 	return 1_000 + Math.floor(random() * 29_000);
 }
 
+/**
+ * The default inter-cycle sleep: a REF'D setTimeout whose promise carries its own `cancel` (issue
+ * #325). Ref'd deliberately -- the poller IS its process's main loop and holding the loop through the
+ * delay is the point (`DES-RETENTION-SWEEPS-ON-A-TIMER`'s rejected list records the contrast; between
+ * cycles this timer is the only thing keeping a pure-poll process alive, cli.mjs's "awaiting done").
+ * The defect was never the ref, only survival past stop(): "unref'd is not cleaned up" has a ref'd
+ * twin, a cleared-nothing timer that holds the loop for up to a full interval after `done` resolved.
+ * A cancelled sleep never resolves, which is safe here because its only awaiter is a race `stopWaker`
+ * has already settled, and cancel on an already-fired timer is a no-op, so the winning side's clear
+ * costs nothing. EXPORTED for `settleWithin`'s reason (worker/src/start.mjs): the cleared-timer
+ * guarantee deserves a deterministic async_hooks pin on the helper, not a census of a full boot.
+ */
+export function cancellableSleep(ms) {
+	let timer;
+	const p = new Promise((resolve) => {
+		timer = setTimeout(resolve, ms);
+	});
+	p.cancel = () => clearTimeout(timer);
+	return p;
+}
+
 /** The redis key family for one repo -- see the schema table in the module header. */
 function keyNames(repo) {
 	const p = `poll:${repo}`;
@@ -916,11 +976,20 @@ async function gate(ctx, eventName, payload, deliveryId, stats) {
 		return;
 	}
 	const replicas = result.job.replicas ?? 1;
+	let created = 0;
 	for (let i = 1; i <= replicas; i++) {
-		await ctx.enqueue(replicas > 1 ? { ...result.job, replica: i } : result.job);
+		const r = await ctx.enqueue(replicas > 1 ? { ...result.job, replica: i } : result.job);
+		// Issue #289, the receiver arms' honesty rule at the poller's own seam: a semantic-window swallow
+		// gets its own line with the surviving id, `enqueued` counts only what was CREATED, and a bare-id
+		// return from an enqueue seam predating the shape counts as created -- the old behaviour exactly.
+		if (r && typeof r === "object" && r.deduplicated === true) {
+			ctx.out({ event: "deduplicated", delivery: deliveryId, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, jobId: r.jobId, survivingJobId: r.survivingJobId });
+		} else {
+			created += 1;
+		}
 	}
-	stats.enqueued += replicas;
-	ctx.out({ event: "enqueued", delivery: deliveryId, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas });
+	stats.enqueued += created;
+	if (created > 0) ctx.out({ event: "enqueued", delivery: deliveryId, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas: created });
 }
 
 /**

package/src/receiver.mjs

@@ -134,7 +134,11 @@ export function parseSubset(payload) {
  * undefined, i.e. never drops the harness's own comments. Absent property therefore means no route; the
  * failure of a forgotten property is a 404 an operator sees, never a paid recursion they get billed for.
  */
-export function makeReceiver({ queue, selfId, cfg, log, gitlab = null, forgejo = null, azure = null, resolveAuthority }) {
+export function makeReceiver({ queue, selfId, cfg, log, gitlab = null, forgejo = null, azure = null, resolveAuthority, router = null }) {
+	// Which queue a delivery is enqueued onto (issue #57, `OQ-032`). The default is the shared queue for
+	// EVERY job, which is what this receiver did before multi-host existed -- so a deployment that wires no
+	// router, and every test that constructs one without it, is byte-identical.
+	const routeTo = router ? (kind, job) => router.queueFor(kind, job) : () => queue;
 	// Built only when the deployment serves GitHub. Construction is not free of the secret either: the
 	// `new Webhooks({ secret })` inside makeVerifiedHandler throws "options.secret required" on an absent
 	// one, so not building the arm is what lets a github-free deployment legitimately have no secret --
@@ -143,7 +147,7 @@ export function makeReceiver({ queue, selfId, cfg, log, gitlab = null, forgejo =
 	// `resolveAuthority` is the GITHUB closer resolver (issue #231), riding top-level beside `selfId`
 	// because github's dependencies always have -- the other forges bundle theirs in per-forge objects.
 	// Optional, because only a close delivery an armed close rule matches ever consults it.
-	const github = cfg.servesGithub ? makeGitHubHandler({ queue, selfId, cfg, log, resolveAuthority }) : null;
+	const github = cfg.servesGithub ? makeGitHubHandler({ queue, routeTo, selfId, cfg, log, resolveAuthority }) : null;
 
 	// A TABLE, built once, rather than one `if` per forge. Two forges made that a single branch; four make
 	// it a chain, and a chain is where one arm quietly ends up checked after the fallthrough. A path present
@@ -151,9 +155,9 @@ export function makeReceiver({ queue, selfId, cfg, log, gitlab = null, forgejo =
 	// falls through to GitHub, which is what keeps `/` working -- and a configured-off GitHub answers the
 	// same 404 from the fallthrough itself, below.
 	const routes = {
-		"/gitlab": gitlab ? makeGitLabHandler({ queue, cfg, log, ...gitlab }) : null,
-		"/forgejo": forgejo ? makeForgejoHandler({ queue, cfg, log, ...forgejo }) : null,
-		"/azure": azure ? makeAzureHandler({ queue, cfg, log, ...azure }) : null,
+		"/gitlab": gitlab ? makeGitLabHandler({ queue, routeTo, cfg, log, ...gitlab }) : null,
+		"/forgejo": forgejo ? makeForgejoHandler({ queue, routeTo, cfg, log, ...forgejo }) : null,
+		"/azure": azure ? makeAzureHandler({ queue, routeTo, cfg, log, ...azure }) : null,
 	};
 
 	return async function receiverHandler(req, res) {
@@ -201,14 +205,43 @@ function pathOf(url) {
  * `enqueue` is a callback because the four arms spell their enqueue differently (a named github/gitlab
  * wrapper, or `enqueueForgeJob` with an explicit kind); the fanout itself is forge-blind.
  *
- * @returns {Promise<number>} how many jobs were enqueued, for the caller's `enqueued` log line.
+ * @returns {Promise<{replicas: number, created: number, deduplicated: Array<{jobId, survivingJobId}>}>}
+ *   what actually happened, per replica (issue #289): `created` counts jobs that now EXIST because of
+ *   this delivery, and `deduplicated` carries each swallow the semantic window made, with the id that
+ *   survived. A bare-id return from an enqueue that predates the shape counts as created -- the old
+ *   behaviour exactly.
  */
 async function fanout(job, enqueue) {
 	const replicas = job.replicas ?? 1;
+	let created = 0;
+	const deduplicated = [];
 	for (let i = 1; i <= replicas; i++) {
-		await enqueue(replicas > 1 ? { ...job, replica: i } : job);
+		const r = await enqueue(replicas > 1 ? { ...job, replica: i } : job);
+		if (r && typeof r === "object" && r.deduplicated === true) deduplicated.push({ jobId: r.jobId, survivingJobId: r.survivingJobId });
+		else created += 1;
 	}
-	return replicas;
+	return { replicas, created, deduplicated };
+}
+
+/**
+ * One log-and-answer for a fanout outcome, shared by all four arms so a weakened copy cannot hide (the
+ * four-copies doctrine above). Issue #289's honesty rule: `enqueued` is logged only when something was
+ * CREATED, with `replicas` meaning jobs that now exist; every semantic-window swallow gets its own
+ * `deduplicated` line naming the surviving job's id (every field forge- or worker-minted, no payload
+ * text); and a delivery that created NOTHING answers `202 {status:"deduplicated"}` -- still a 2xx,
+ * because a non-2xx would trigger a redelivery storm for a delivery that was handled, but no longer
+ * "queued", because a receiver that logs the swallow while answering success on the wire would be the
+ * honest-log/lying-wire split this project refuses. Each arm passes its own target grammar.
+ */
+function respondEnqueueOutcome({ log, res, delivery, repo, target, flow, outcome }) {
+	for (const d of outcome.deduplicated) {
+		log?.({ event: "deduplicated", delivery, repo, target, flow, jobId: d.jobId, survivingJobId: d.survivingJobId });
+	}
+	if (outcome.created > 0) {
+		log?.({ event: "enqueued", delivery, repo, target, flow, replicas: outcome.created });
+		return respond(res, 202, { status: "queued" });
+	}
+	return respond(res, 202, { status: "deduplicated" });
 }
 
 /**
@@ -223,7 +256,7 @@ async function fanout(job, enqueue) {
  * uses, so a lookup is never spent on a delivery the gate then ignores -- every label, comment, PR and
  * review delivery, and every close nothing wants, stays payload-only and byte-identical to before.
  */
-function makeGitHubHandler({ queue, selfId, cfg, log, resolveAuthority }) {
+function makeGitHubHandler({ queue, routeTo, selfId, cfg, log, resolveAuthority }) {
 	return makeVerifiedHandler({ secret: cfg.webhookSecret }, async ({ rawBody, event, delivery }, res) => {
 		let subset;
 		try {
@@ -262,17 +295,16 @@ function makeGitHubHandler({ queue, selfId, cfg, log, resolveAuthority }) {
 		}
 
 		// Fanout (REQ-REPLICA-RUNS) lives in `fanout` above; the 202/503 decision stays here, where it always was.
-		let replicas;
+		let outcome;
 		try {
-			replicas = await fanout(result.job, (j) => enqueueGitHubJob(queue, j));
+			outcome = await fanout(result.job, async (j) => await enqueueGitHubJob(await routeTo("github", j), j));
 		} catch (err) {
 			// Own try/catch so a Valkey-down enqueue is a 503 (retryable), not verify's outer 500.
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" }); // GitHub redelivers; dedup by GUID coalesces
 		}
 
-		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas });
-		return respond(res, 202, { status: "queued" });
+		return respondEnqueueOutcome({ log, res, delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, outcome });
 	});
 }
 
@@ -289,7 +321,7 @@ function makeGitHubHandler({ queue, selfId, cfg, log, resolveAuthority }) {
  * The lookup runs only for events that could still fire -- after verification, and after the payload has
  * been projected -- so an unauthenticated flood cannot make this project call GitLab at all.
  */
-function makeGitLabHandler({ queue, cfg, log, mode, secret, selfId, resolveAuthority, now }) {
+function makeGitLabHandler({ routeTo, queue, cfg, log, mode, secret, selfId, resolveAuthority, now }) {
 	return makeGitLabVerifiedHandler({ mode, secret, ...(now ? { now } : {}) }, async ({ rawBody, delivery }, res) => {
 		let subset;
 		try {
@@ -312,9 +344,9 @@ function makeGitLabHandler({ queue, cfg, log, mode, secret, selfId, resolveAutho
 			return respond(res, 204);
 		}
 
-		let replicas;
+		let outcome;
 		try {
-			replicas = await fanout(result.job, (j) => enqueueGitLabJob(queue, j));
+			outcome = await fanout(result.job, async (j) => await enqueueGitLabJob(await routeTo("gitlab", j), j));
 		} catch (err) {
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" }); // GitLab redelivers; dedup by webhook-id coalesces
@@ -323,8 +355,7 @@ function makeGitLabHandler({ queue, cfg, log, mode, secret, selfId, resolveAutho
 		// `!` for a merge request, `#` for an issue -- GitLab's own notation, and the same discrimination
 		// the semantic dedup key makes, because the two are separate number sequences.
 		const sep = result.job.target.type === "pull_request" ? "!" : "#";
-		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow, replicas });
-		return respond(res, 202, { status: "queued" });
+		return respondEnqueueOutcome({ log, res, delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow, outcome });
 	});
 }
 
@@ -341,7 +372,7 @@ function makeGitLabHandler({ queue, cfg, log, mode, secret, selfId, resolveAutho
  * per construction, and serving two sources from one would mean either sharing a secret between forges or
  * letting the request choose which one it was checked against.
  */
-function makeForgejoHandler({ queue, cfg, log, secret, selfId, resolveAuthority }) {
+function makeForgejoHandler({ routeTo, queue, cfg, log, secret, selfId, resolveAuthority }) {
 	return makeVerifiedHandler({ secret }, async ({ rawBody, event, delivery }, res) => {
 		let subset;
 		try {
@@ -364,16 +395,15 @@ function makeForgejoHandler({ queue, cfg, log, secret, selfId, resolveAuthority
 			return respond(res, 204);
 		}
 
-		let replicas;
+		let outcome;
 		try {
-			replicas = await fanout(result.job, (j) => enqueueForgeJob(queue, "forgejo", j));
+			outcome = await fanout(result.job, async (j) => await enqueueForgeJob(await routeTo("forgejo", j), "forgejo", j));
 		} catch (err) {
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" }); // Forgejo redelivers; dedup by GUID coalesces
 		}
 
-		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas });
-		return respond(res, 202, { status: "queued" });
+		return respondEnqueueOutcome({ log, res, delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, outcome });
 	});
 }
 
@@ -391,7 +421,7 @@ function makeForgejoHandler({ queue, cfg, log, secret, selfId, resolveAuthority
  * `"Display Name <email>"`. Both the resolver and the bot-loop guard handle both forms -- see
  * filter-azure.mjs, where the ordering constraint is stated in full.
  */
-function makeAzureHandler({ queue, cfg, log, mode, secret, headerName, selfId, resolveAuthority }) {
+function makeAzureHandler({ routeTo, queue, cfg, log, mode, secret, headerName, selfId, resolveAuthority }) {
 	return makeAzureVerifiedHandler({ mode, secret, headerName }, async ({ rawBody }, res) => {
 		let subset;
 		try {
@@ -422,9 +452,9 @@ function makeAzureHandler({ queue, cfg, log, mode, secret, headerName, selfId, r
 			return respond(res, 204);
 		}
 
-		let replicas;
+		let outcome;
 		try {
-			replicas = await fanout(result.job, (j) => enqueueForgeJob(queue, "azure", j));
+			outcome = await fanout(result.job, async (j) => await enqueueForgeJob(await routeTo("azure", j), "azure", j));
 		} catch (err) {
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" });
@@ -433,7 +463,6 @@ function makeAzureHandler({ queue, cfg, log, mode, secret, headerName, selfId, r
 		// `!` for a pull request, `#` for a work item -- Azure numbers them separately, and this is the same
 		// discrimination the semantic dedup key makes.
 		const sep = result.job.target.type === "pull_request" ? "!" : "#";
-		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow, replicas });
-		return respond(res, 202, { status: "queued" });
+		return respondEnqueueOutcome({ log, res, delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow, outcome });
 	});
 }

package/src/route.mjs

@@ -0,0 +1,126 @@
+/**
+ * Which queue a forge delivery is enqueued onto, when the deployment runs on more than one machine
+ * (issue #57, `OQ-032`).
+ *
+ * The receiver is the only process that can make this decision. Routing has to happen at ENQUEUE -- a
+ * delayed job is promoted on each worker's own clock, so the fastest clock wins every attempt and a job
+ * cannot reliably be handed from a host that will not serve it to one that will -- and forge deliveries are
+ * enqueued here. `capabilities.mjs` owns the RULE and is shared with the worker so the two cannot drift;
+ * this module owns the plumbing: one cached registry read, and a pool of queue handles.
+ *
+ * EVERYTHING HERE FAILS OPEN ONTO THE SHARED QUEUE, which is what this receiver did before any of it
+ * existed. An unreadable registry, a timed-out read, a malformed row, a name that is not routable: every
+ * one of them returns the shared queue, so the worst this can do is fail to improve on a coin flip. A
+ * webhook handler is the wrong place to invent a new way to drop work.
+ */
+
+import { readLiveHosts } from "@edgehero/pi-dispatch/host-registry";
+import { makeQueue, hostQueueName } from "@edgehero/pi-dispatch/queue";
+import { parseConnection, makeRedisClient } from "@edgehero/pi-dispatch/connection";
+import { forgeDeliveryJobId } from "@edgehero/pi-dispatch/job-id";
+import { jobNeeds, routeForgeJob } from "@edgehero/pi-dispatch/capabilities";
+
+/**
+ * How long a registry read is reused.
+ *
+ * The registry beats every 15s, so anything below that mostly re-reads a value that cannot have changed.
+ * Five seconds is well inside one beat and bounds the extra load a busy receiver puts on Valkey at one read
+ * per five seconds rather than one per delivery -- and a delivery burst, which is exactly when this must
+ * not add latency, is served entirely from cache.
+ *
+ * Staleness costs nothing that freshness would have saved: a host that appears within the window is missed
+ * and its work goes to the shared queue, which is today's behaviour, and a host that vanishes is already
+ * guarded by `ROUTE_FRESH_MS` on the row's own beat timestamp.
+ */
+const HOSTS_TTL_MS = 5_000;
+
+/** Bound on the registry read itself. A routing hint is never worth making a webhook wait. */
+const READ_TIMEOUT_MS = 1_500;
+
+/**
+ * @returns {{queueFor: (kind: string, job: object) => Promise<object>, close: () => Promise<void>}}
+ */
+export function makeForgeRouter({
+	valkeyUrl,
+	shared,
+	log = () => {},
+	makeQueueFn = makeQueue,
+	parseConnectionFn = parseConnection,
+	redisFn = makeRedisClient,
+	readLiveHostsFn = readLiveHosts,
+	now = () => Date.now(),
+	ttlMs = HOSTS_TTL_MS,
+} = {}) {
+	const pool = new Map(); // queue name -> Queue, opened lazily and only for hosts actually routed to
+	let redis = null;
+	let cached = { at: -Infinity, hosts: [] };
+	let inFlight = null;
+
+	// One read at a time. Without this a burst of deliveries arriving on a cold cache each start their own
+	// registry read, which is the moment the deployment can least afford N of them.
+	const hosts = async () => {
+		if (now() - cached.at < ttlMs) return cached.hosts;
+		if (inFlight) return await inFlight;
+		inFlight = (async () => {
+			try {
+				if (!redis) {
+					redis = redisFn(valkeyUrl);
+					// A receiver must never print ioredis reconnect noise into its own log: this client is an
+					// optimisation, and its failures are already handled by falling back to the shared queue.
+					redis.on?.("error", () => {});
+				}
+				const res = await readLiveHostsFn(redis, { timeoutMs: READ_TIMEOUT_MS });
+				cached = { at: now(), hosts: Array.isArray(res?.hosts) ? res.hosts : [] };
+			} catch {
+				// Cache the FAILURE too, so an unreachable Valkey costs one read per window rather than one
+				// per delivery. The empty list routes everything to the shared queue.
+				cached = { at: now(), hosts: [] };
+			} finally {
+				inFlight = null;
+			}
+			return cached.hosts;
+		})();
+		return await inFlight;
+	};
+
+	return {
+		async queueFor(kind, job) {
+			const needs = jobNeeds(job);
+			// The overwhelming majority of deliveries bind neither a secret profile nor a wait profile, and
+			// they must not pay even a cache lookup for a decision that cannot apply to them.
+			if (needs.length === 0) return shared;
+
+			let name = null;
+			try {
+				name = routeForgeJob({ hosts: await hosts(), needs, jobId: forgeDeliveryJobId(kind, job?.trigger?.deliveryId, job?.replica) });
+			} catch {
+				return shared; // an unroutable id, a bad row: the shared queue is always a correct answer
+			}
+			if (!name) return shared;
+
+			const queueName = hostQueueName(name);
+			if (!pool.has(queueName)) pool.set(queueName, makeQueueFn(parseConnectionFn(valkeyUrl), { name: queueName }));
+			// Logged because a routed job is the one case where "which host ran it" was DECIDED rather than
+			// observed, and an operator debugging a job that never started needs to know it was sent
+			// somewhere specific. Host names are deployment topology: this reaches the log, never a forge
+			// comment (`triggers.mjs` sets that rule for refusal messages and it holds here).
+			log({ event: "forge_job_routed", kind, host: name, needs: needs.join(",") });
+			return pool.get(queueName);
+		},
+		async close() {
+			for (const q of pool.values()) {
+				try {
+					await q.close();
+				} catch {
+					// best-effort teardown
+				}
+			}
+			pool.clear();
+			try {
+				redis?.disconnect?.();
+			} catch {
+				// best-effort teardown
+			}
+		},
+	};
+}