@edgehero/pi-dispatch-receiver 0.1.0

package/src/config.mjs

@@ -0,0 +1,257 @@
+/**
+ * Receiver configuration, from the environment. Validated and fail-loud, mirroring the worker:
+ * a misconfigured receiver refuses to start with a clear message rather than booting into a state
+ * where webhooks silently go unverified or untriggered.
+ *
+ * The security-sensitive GitHub auth block is single-sourced from `@edgehero/pi-dispatch/config` --
+ * `loadGitHubAuth` is parsed once, in one place, so the receiver and worker cannot drift on it. The
+ * trigger schema is likewise single-sourced from `@edgehero/pi-dispatch/triggers` -- both services validate
+ * the WHOLE unified triggers file and each selects the `on.type` it owns (issue #20).
+ *
+ * - `webhookSecret` is REQUIRED: without it the receiver cannot verify `X-Hub-Signature-256` over the
+ *   raw body, and an unverified webhook is a forgeable paid-agent trigger (CONST-HMAC-OVER-RAW-BODY).
+ * - `triggers` is the receiver's webhook allowlist, grouped by type: label rules (the label IS the
+ *   collaborator approval), the single comment trigger (phrase + default flow), and pull_request rules.
+ *   Only collaborators can apply labels, so the label/PR-label allowlist is the human approval gate
+ *   (CONST-TRIGGER-AUTHOR-GATE). It is read from `./triggers.json` in the working directory by
+ *   default -- the file `pi-dispatch init` scaffolds -- with PI_TRIGGERS_FILE as the override.
+ * - `bind` defaults to `0.0.0.0` (public): the receiver is the trigger surface that lives outside pi
+ *   (DES-TRIGGER-OUTSIDE-PI). It carries no admin/dashboard config -- the admin surface is a pi extension
+ *   in the operator's session and binds no port (DES-ADMIN-VIA-PI-EXTENSION), so there is none here.
+ *
+ * Errors are tagged `piDispatchConfig` (via the shared `configError`) so the entry can print them
+ * cleanly and exit non-zero.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { configError, loadGitHubAuth, positiveInt } from "@edgehero/pi-dispatch/config";
+import { FORGE_KINDS, parseTriggers } from "@edgehero/pi-dispatch/triggers";
+
+// Cwd-relative, matching what `pi-dispatch init` scaffolds (and the admin's default): the receiver's
+// default must be the file init just told the operator it created, not a demo buried in the repo.
+const DEFAULT_TRIGGERS_PATH = "./triggers.json";
+
+/**
+ * Parse the receiver's config from `env` (default process.env). Filesystem access is injected
+ * (`readFile`, `fileExists`) so the loader is hermetically testable and never touches disk in tests.
+ */
+export function loadReceiverConfig(env = process.env, { readFile = readFileSync, fileExists = existsSync } = {}) {
+	const webhookSecret = env.WEBHOOK_SECRET;
+	if (webhookSecret === undefined || webhookSecret.trim() === "") {
+		throw configError("WEBHOOK_SECRET is required; refusing to start a receiver that cannot verify signatures");
+	}
+
+	return {
+		webhookSecret,
+		valkeyUrl: env.VALKEY_URL ?? "redis://127.0.0.1:6379", // mirrors worker config: producer and consumer share one queue
+		port: positiveInt(env, "RECEIVER_PORT", 3000),
+		bind: env.RECEIVER_BIND ?? "0.0.0.0",
+		triggers: loadTriggers(env, readFile, fileExists),
+		github: loadGitHubAuth(env, fileExists),
+		gitlab: loadGitLabConfig(env),
+		forgejo: loadForgejoConfig(env),
+		azure: loadAzureConfig(env),
+	};
+}
+
+/**
+ * The GitLab endpoint's configuration, or `null` when the deployment serves no GitLab -- in which case no
+ * `/gitlab` route exists at all, rather than one that answers 401. An endpoint that responds is an endpoint
+ * an operator can believe is armed.
+ *
+ * `GITLAB_WEBHOOK_MODE` is REQUIRED once any GitLab variable is set, and is not defaulted. The two modes
+ * are not equally strong -- `signature` is an HMAC over the body, `token` is a shared-secret compare that
+ * proves nothing about the body's integrity -- so which one a deployment runs must be a thing somebody
+ * chose and can be asked about, never a thing it fell into. Defaulting to the weaker one would silently
+ * downgrade every operator who did not know the field existed; defaulting to the stronger one would break
+ * every instance below GitLab 19.0.
+ */
+function loadGitLabConfig(env) {
+	const mode = env.GITLAB_WEBHOOK_MODE;
+	const secret = env.GITLAB_WEBHOOK_SECRET;
+	const token = env.GITLAB_TOKEN;
+	const apiUrl = env.GITLAB_URL ?? "https://gitlab.com";
+	if (!mode && !secret && !token) return null;
+
+	if (mode !== "signature" && mode !== "token") {
+		throw configError(`GITLAB_WEBHOOK_MODE must be "signature" (HMAC, GitLab 19.0+) or "token" (X-Gitlab-Token, any version); got ${JSON.stringify(mode)}`);
+	}
+	if (typeof secret !== "string" || secret.trim() === "") {
+		throw configError("GITLAB_WEBHOOK_SECRET is required; refusing to start a gitlab endpoint that cannot verify deliveries");
+	}
+	// The gate needs this token BEFORE any job runs: the actor's access level is what authorises a GitLab
+	// trigger at all (CONST-TRIGGER-AUTHOR-GATE), and without a token every lookup is indeterminate and
+	// every delivery 503s. Refusing at boot is the difference between one clear message and a redelivery loop.
+	if (typeof token !== "string" || token.trim() === "") {
+		throw configError("GITLAB_TOKEN is required for gitlab triggers -- the receiver resolves the actor's project access level before it may enqueue");
+	}
+	return { mode, secret, token, apiUrl };
+}
+
+/**
+ * The Forgejo/Gitea block, or `null` when nothing names it -- same presence rule as GitLab's: an endpoint
+ * that answers for a forge nobody configured is an endpoint an operator can believe is armed.
+ *
+ * There is no MODE here, and that absence is the good news. Forgejo signs the raw body with HMAC-SHA256
+ * and sends GitHub's three headers verbatim, so there is exactly one verification mechanism and it is the
+ * strong one -- no choice to make, and none to get wrong.
+ *
+ * `FORGEJO_BOT_ID` is optional and exists for one reason: a repository-scoped token cannot call
+ * `GET /user` (see worker/src/forgejo-identity.mjs). Without it, following the token-scoping advice would
+ * make the receiver unable to identify itself, and identity is not optional here.
+ */
+function loadForgejoConfig(env) {
+	const secret = env.FORGEJO_WEBHOOK_SECRET;
+	const token = env.FORGEJO_TOKEN;
+	const apiUrl = env.FORGEJO_URL;
+	const botId = env.FORGEJO_BOT_ID ?? null;
+	if (!secret && !token && !apiUrl) return null;
+
+	// No default instance URL, deliberately: Forgejo is self-hosted by nature and there is no forgejo.com to
+	// fall back to. Guessing one would send a token to a host the operator never named.
+	if (typeof apiUrl !== "string" || apiUrl.trim() === "") {
+		throw configError("FORGEJO_URL is required for forgejo triggers -- there is no default instance to fall back to");
+	}
+	if (typeof secret !== "string" || secret.trim() === "") {
+		throw configError("FORGEJO_WEBHOOK_SECRET is required; refusing to start a forgejo endpoint that cannot verify deliveries");
+	}
+	// Needed BEFORE any job runs: the actor's repository permission is what authorises a forgejo trigger at
+	// all (CONST-TRIGGER-AUTHOR-GATE), and without a token every lookup is indeterminate and every delivery
+	// 503s. Refusing at boot is the difference between one clear message and a redelivery loop.
+	if (typeof token !== "string" || token.trim() === "") {
+		throw configError("FORGEJO_TOKEN is required for forgejo triggers -- the receiver resolves the actor's repository permission before it may enqueue");
+	}
+	return { secret, token, apiUrl: apiUrl.trim(), botId };
+}
+
+/**
+ * The Azure DevOps block, or `null` when nothing names it.
+ *
+ * `AZURE_WEBHOOK_MODE` is REQUIRED once any AZURE_* variable is set and is deliberately not defaulted --
+ * the same rule GitLab's mode gets, and for a sharper reason. Azure offers no HMAC at all, so BOTH modes
+ * are shared-secret compares that cover no bytes; which header carries the secret is a deployment fact
+ * somebody has to have decided, and defaulting it would mean an operator could arm an endpoint without
+ * ever noticing that its gate proves only that the sender knew a string.
+ */
+function loadAzureConfig(env) {
+	const mode = env.AZURE_WEBHOOK_MODE;
+	const secret = env.AZURE_WEBHOOK_SECRET;
+	const token = env.AZURE_TOKEN;
+	const orgUrl = env.AZURE_ORG_URL;
+	const headerName = env.AZURE_WEBHOOK_HEADER ?? null;
+	if (!mode && !secret && !token && !orgUrl) return null;
+
+	if (mode !== "basic" && mode !== "header") {
+		throw configError(`AZURE_WEBHOOK_MODE must be "basic" (HTTP Basic on the subscription) or "header" (a custom header); got ${JSON.stringify(mode)}`);
+	}
+	if (mode === "header" && (typeof headerName !== "string" || headerName.trim() === "")) {
+		throw configError("AZURE_WEBHOOK_HEADER is required when AZURE_WEBHOOK_MODE=header -- there is no default header name to guess");
+	}
+	if (typeof secret !== "string" || secret.trim() === "") {
+		throw configError("AZURE_WEBHOOK_SECRET is required; refusing to start an azure endpoint that cannot authenticate deliveries");
+	}
+	// No default organization URL: guessing one would send an operator's token to an organization they
+	// never named.
+	if (typeof orgUrl !== "string" || orgUrl.trim() === "") {
+		throw configError("AZURE_ORG_URL is required for azure triggers (e.g. https://dev.azure.com/your-org)");
+	}
+	// Needed BEFORE any job runs: project membership is what authorises an azure trigger at all
+	// (CONST-TRIGGER-AUTHOR-GATE), and without a token every lookup is indeterminate and every delivery 503s.
+	if (typeof token !== "string" || token.trim() === "") {
+		throw configError("AZURE_TOKEN is required for azure triggers -- the receiver resolves the actor's project membership before it may enqueue");
+	}
+	return { mode, secret, headerName: headerName?.trim() ?? null, token, orgUrl: orgUrl.trim().replace(/\/+$/, "") };
+}
+
+/**
+ * Load, validate, and group the receiver's webhook triggers from the unified triggers file. The file is
+ * the reviewed, committed source of truth for which events trigger which flow; a missing, unparseable, or
+ * malformed file fails loud rather than degrading to an empty (silently trigger-nothing) allowlist.
+ *
+ * The shared `parseTriggers` validates the WHOLE file (including the on x run matrix and cron entries the
+ * worker owns); this loader keeps only the webhook types and groups them PER FORGE, so `cfg.triggers` is
+ * `{ github: <group>, gitlab: <group>, knownFlows }` where each group is:
+ *   - `label`:       ordered `{ index, predicate, flow, packages, image }` rules (first match wins in the filter).
+ *   - `comment`:     the single `{ index, phrase, defaultFlow, packages, image }` (or null when no comment trigger is configured).
+ *   - `pullRequest`: ordered `{ index, actions:Set, predicate, flow, packages, image }` rules.
+ * and `knownFlows` is every webhook `run.flow`, so a comment's `<phrase> <flow>` override cannot summon an
+ * unlisted flow.
+ *
+ * Grouping by forge FIRST is what keeps each forge's gate reading only its own rules: a GitLab delivery
+ * can never match a rule an operator wrote for GitHub, even when both name the same label. `knownFlows`
+ * stays shared deliberately -- a flow is a skill in a repo, not a property of the forge that asked for it,
+ * and the set exists to bound which names a comment may summon, which is the same bound either way.
+ *
+ * `packages` (load the operator-staged pi packages) and `image` (which container image the job runs in) are
+ * the entry's per-trigger execution fields (INT-TRIGGERS-FILE-CONTRACT, REQ-GLOBAL-PI-OVERLAY). Both ride on
+ * the RULE, not on the group, because the filter resolves them from the rule that actually matched -- two
+ * rules in one file may name different images, and picking the group's would run the wrong toolchain for
+ * whichever rule lost. Absent stays undefined so the filter can omit it entirely and leave an unflagged job
+ * byte-identical to today's. `replicas` (REQ-REPLICA-RUNS) rides the rule for the same reason and one
+ * sharper: it multiplies spend, so reading it off any rule other than the one that matched would bill an
+ * operator for a decision they made about a different trigger.
+ *
+ * Each grouped rule carries `index`: its 0-based position in the RAW `triggers` array, cron entries
+ * counted. The raw file index is the rule's identity -- the filter reports it on the job as
+ * `trigger.matched.index`, so a run is explainable back to the exact triggers.json entry that fired it.
+ */
+function loadTriggers(env, readFile, fileExists) {
+	const path = env.PI_TRIGGERS_FILE ?? DEFAULT_TRIGGERS_PATH;
+
+	if (!fileExists(path)) {
+		throw configError(`triggers file not found: ${path} -- run \`pi-dispatch init\` in this folder to scaffold one, or set PI_TRIGGERS_FILE to yours`);
+	}
+
+	const parsed = parseTriggers(readFile(path, "utf8"), path); // fail-loud
+
+	// Every forge gets a group whether or not the file names it, so the filter can read
+	// `cfg.triggers[kind].label` without a presence check and an unconfigured forge simply matches nothing.
+	//
+	// Built FROM the forge table rather than written out, because the failure of forgetting one is unusually
+	// quiet: `groups[run.kind]` would be undefined, `group.label.push` would throw, and `reloadTriggers`
+	// below catches everything and KEEPS the previously-loaded triggers. The operator would see one
+	// "invalid" message and their old rules would go on firing indefinitely. A test asserts this object's
+	// keys are exactly FORGE_KINDS, so the two can never drift.
+	const groups = Object.fromEntries(FORGE_KINDS.map((kind) => [kind, emptyGroup()]));
+	const knownFlows = new Set();
+
+	for (const [index, { on, run }] of parsed.entries()) {
+		if (on.type === "cron") continue; // the worker owns cron; the receiver never fires it -- but it keeps its index
+		knownFlows.add(run.flow);
+		const group = groups[run.kind];
+		if (on.type === "label") {
+			group.label.push({ index, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, resume: run.resume, replicas: run.replicas, repository: run.repository });
+		} else if (on.type === "comment") {
+			group.comment = { index, phrase: on.phrase, defaultFlow: run.flow, packages: run.packages, image: run.image, resume: run.resume, replicas: run.replicas, repository: run.repository }; // parseTriggers guarantees at most one per forge
+		} else if (on.type === "pull_request") {
+			group.pullRequest.push({ index, actions: new Set(on.action), predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, resume: run.resume, replicas: run.replicas });
+		}
+	}
+
+	return { ...groups, knownFlows };
+}
+
+function emptyGroup() {
+	return { label: [], comment: null, pullRequest: [] };
+}
+
+/** The triggers file path the receiver reads (env override or the cwd default matching what `pi-dispatch init` scaffolds). */
+export function triggersFilePath(env = process.env) {
+	return env.PI_TRIGGERS_FILE ?? DEFAULT_TRIGGERS_PATH;
+}
+
+/**
+ * Live-reload the receiver's triggers: re-read + re-group the file and swap `cfg.triggers` IN PLACE, so the
+ * already-wired handler (which closes over `cfg`) picks up the new triggers on its next request -- no
+ * restart, mirroring how the worker re-reads the settings overlay per job. If the new file is
+ * missing/unparseable/invalid, the running triggers are KEPT (never crash a live receiver on a bad edit)
+ * and the reason is returned. Returns `{ ok: true }` or `{ invalid }`.
+ */
+export function reloadTriggers(env, cfg, { readFile = readFileSync, fileExists = existsSync } = {}) {
+	try {
+		cfg.triggers = loadTriggers(env, readFile, fileExists);
+		return { ok: true };
+	} catch (e) {
+		return { invalid: e?.message ?? String(e) };
+	}
+}

package/src/filter-azure.mjs

@@ -0,0 +1,273 @@
+/**
+ * The Azure DevOps trigger gate. Pure, total, and offline-testable, like its three siblings.
+ *
+ * The evaluation ORDER is the same fail-closed one, but step 0 does more work here than anywhere else,
+ * because Azure is the only forge that identifies an actor two different ways:
+ *   0. The actor must resolve to a GUID or a parseable address. Neither is a reject.
+ *   1. The bot-loop guard, UNCONDITIONALLY, before any authority or tag check.
+ *   2. The authority gate, for every trigger type.
+ *   3. Route on the event id.
+ *
+ * WHY STEP 0 IS THE SHARPEST HAZARD ON THIS FORGE. `filter.mjs` rejects a non-NUMBER `sender.id` first, and
+ * its header explains why: `undefined === selfId` is false, so a malformed payload would fall through and
+ * ENQUEUE. That guard is correct on GitHub precisely because it demands a number -- and Azure has no
+ * numbers. A pull-request actor is a GUID string; a work-item actor is `"Display Name <email>"`. Relaxing
+ * the type check is exactly where the fail-open comes back, so `selfId` here is a two-field
+ * `{ id, email }` and the comparison is explicit on both, with neither side allowed to be empty. The
+ * consequence of getting it wrong is the one `filter-gitlab.mjs:11` exists to prevent: the harness's own
+ * work-item comments re-trigger jobs, whose comments re-trigger jobs.
+ *
+ * TAGS ARE MATCHED ON THE DIFF, NEVER THE SET. Azure has no `labeled` event; a tag change arrives as
+ * `workitem.updated` carrying a `{ oldValue, newValue }` pair. Matching the current set would fire the
+ * trigger again on every later edit of any field -- a paid run per typo fix, forever. `filter-gitlab.mjs`
+ * documents this trap for GitLab's `changes.labels`; Azure is its second customer, and `no-label-change`
+ * is the same drop reason on purpose.
+ */
+
+import { createHash } from "node:crypto";
+import { escapeRegExp, firstMatchingRule, labelSet, matchedLabel, matchesRule } from "./predicate.mjs";
+import { PR_COMMENT_EVENT, PR_EVENTS, WORK_ITEM_EVENTS } from "./azure-subset.mjs";
+
+/** The `pull_request` actions a trigger may name, mirrored from the loader's azure vocabulary. */
+const PR_ACTION_FOR = {
+	"git.pullrequest.created": "created",
+	"git.pullrequest.updated": "updated",
+};
+
+/**
+ * Decide. Returns `{ enqueue: false, reason }` or `{ enqueue: true, job }`.
+ *
+ * `selfId` is `{ id, email }` -- see the header for why it is not one value.
+ */
+export function filterAzure(subset, triggers, knownFlows, selfId, authorized, deliveryId) {
+	const actor = subset?.actor ?? {};
+	const hasId = typeof actor.id === "string" && actor.id !== "";
+	const hasEmail = typeof actor.email === "string" && actor.email !== "";
+
+	// (0) Fail-closed on identity. MUST precede the self compare.
+	if (!hasId && !hasEmail) {
+		return { enqueue: false, reason: "missing-sender-id" };
+	}
+
+	// (1) Bot-loop guard, unconditional. Both forms are compared, and an EMPTY side never matches: a
+	// deployment whose selfId resolved only one of the two must not silently match every actor on the
+	// other.
+	const selfGuid = typeof selfId?.id === "string" && selfId.id !== "" ? selfId.id : null;
+	const selfEmail = typeof selfId?.email === "string" && selfId.email !== "" ? selfId.email.toLowerCase() : null;
+	if ((hasId && selfGuid !== null && actor.id === selfGuid) || (hasEmail && selfEmail !== null && actor.email === selfEmail)) {
+		return { enqueue: false, reason: "self" };
+	}
+
+	// (2) The authority gate, for EVERY trigger type. Strict `!== true`, so anything that is not an
+	// explicit yes refuses.
+	if (authorized !== true) {
+		return { enqueue: false, reason: "author-not-allowed" };
+	}
+
+	// (3) Route on the Service Hook event id.
+	const event = subset.eventType;
+	const group = triggers ?? {};
+	let resolved;
+
+	if (WORK_ITEM_EVENTS.has(event)) {
+		resolved = event === "workitem.commented" ? routeComment(subset, group, knownFlows, "issue") : routeWorkItemTag(subset, group, event);
+	} else if (event === PR_COMMENT_EVENT) {
+		resolved = routeComment(subset, group, knownFlows, "pull_request");
+	} else if (PR_EVENTS.has(event)) {
+		resolved = routePullRequest(subset, group, PR_ACTION_FOR[event]);
+	} else {
+		return { enqueue: false, reason: "unhandled-event" };
+	}
+
+	if (!resolved.enqueue) return resolved; // carries the drop reason
+
+	// WHICH REPOSITORY the job clones. A pull-request event names its own and that is authoritative. A WORK
+	// ITEM names none -- Azure work items belong to a project, and a project may hold many repositories --
+	// so the matched rule's `run.repository` supplies it. The loader requires that field on exactly the
+	// azure trigger types a work item can fire, so reaching here without one is not possible; the guard is
+	// here anyway because "not possible" and "cannot happen" are different claims and only one is testable.
+	const scope = resolveScope(subset, resolved);
+	if (scope === null) {
+		return { enqueue: false, reason: "no-repository" };
+	}
+	resolved.repo = scope.repo;
+	resolved.azure = scope.azure;
+
+	const job = {
+		// `<project>/<repository>`, WITHOUT the organization -- exactly as a gitlab job's `repo` omits the
+		// instance. A deployment has one AZURE_ORG_URL, so the org is constant across every azure job here
+		// and repeating it in a pause-window scope and a run-record label would be noise, not information.
+		repo: resolved.repo,
+		// The structured triple the API paths need, alongside the human-readable label -- the same split
+		// gitlab makes when it carries `projectId` next to `repo`.
+		azure: resolved.azure,
+		target: resolved.target,
+		flow: resolved.flow,
+		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
+		...(resolved.image !== undefined ? { image: resolved.image } : {}),
+		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
+		trigger: {
+			event,
+			action: resolved.action,
+			deliveryId,
+			// A GUID when the delivery carried one, else a HASH of the address -- never the address itself.
+			// A work-item payload offers nothing but `"Display Name <email>"`, and this object is copied
+			// verbatim into /job/event.json and summarised into the durable run record, both of which are
+			// PII-free BY CONSTRUCTION. Hashing keeps "the same actor twice" answerable without putting
+			// somebody's email in a file the agent reads and an operator greps -- the same move
+			// `session-key.mjs` makes for branch names.
+			sender: { id: hasId ? actor.id : stableActorId(actor.email) },
+			matched: resolved.matched,
+			...(resolved.comment ? { comment: resolved.comment } : {}),
+		},
+	};
+	return { enqueue: true, job };
+}
+
+/**
+ * Work-item tag path. The DIFF is the trigger.
+ *
+ * `workitem.created` has no diff and is matched on the set it arrived with, which is correct and not an
+ * exception: a work item created already carrying the tag has changed from having none.
+ */
+function routeWorkItemTag(subset, triggers, event) {
+	if (event === "workitem.updated") {
+		const changes = subset.tagChanges;
+		if (changes === undefined) {
+			// An update that changed no tags. Dropping it here is what stops every later edit of any field on
+			// a tagged work item from starting another paid run.
+			return { enqueue: false, reason: "no-label-change" };
+		}
+		// Verbatim, matching `labelSet`'s own semantics -- it does not case-fold, and a diff that did would
+		// disagree with the predicate that runs against it two lines later.
+		const previous = labelSet(changes.previous);
+		const added = changes.current.filter((t) => !previous.has(t.name));
+		if (added.length === 0) {
+			// Tags changed, but only by REMOVAL. Removing a tag must never start a paid run -- the same rule
+			// Forgejo's `label_cleared` gets.
+			return { enqueue: false, reason: "no-label-change" };
+		}
+		return matchLabelRules(subset, triggers, added, "updated");
+	}
+	return matchLabelRules(subset, triggers, subset.tags ?? [], "created");
+}
+
+function matchLabelRules(subset, triggers, labels, action) {
+	const L = labelSet(labels);
+	const rule = firstMatchingRule(triggers.label, L);
+	if (rule === undefined) {
+		return { enqueue: false, reason: "no-allowlisted-label" };
+	}
+	return {
+		enqueue: true,
+		action,
+		flow: rule.flow,
+		repository: rule.repository,
+		packages: rule.packages,
+		image: rule.image,
+		resume: rule.resume,
+		matched: { index: rule.index, type: "label", label: matchedLabel(L, rule.predicate) },
+		target: { type: "issue", number: subset.target?.number, title: subset.target?.title, body: subset.target?.body },
+	};
+}
+
+/** Comment path, on either a work item or a pull request. The authority gate above has already run. */
+function routeComment(subset, triggers, knownFlows, targetType) {
+	const phrase = triggers.comment?.phrase;
+	const body = subset.comment;
+	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
+		return { enqueue: false, reason: "no-trigger-phrase" };
+	}
+	let flow = triggers.comment?.defaultFlow;
+	const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
+	if (match && knownFlows?.has(match[1])) {
+		flow = match[1];
+	}
+	if (flow === null || flow === undefined || flow === "") {
+		return { enqueue: false, reason: "no-flow" };
+	}
+	return {
+		enqueue: true,
+		action: "commented",
+		flow,
+		repository: triggers.comment.repository,
+		packages: triggers.comment.packages,
+		image: triggers.comment.image,
+		resume: triggers.comment.resume,
+		matched: { index: triggers.comment.index, type: "comment", phrase },
+		// No author_association: Azure has none, and the authority that admitted this comment was resolved
+		// from the graph, not read off the body.
+		comment: { body },
+		target: { type: targetType, number: subset.target?.number, title: subset.target?.title, body: subset.target?.body },
+	};
+}
+
+/** Pull-request path. */
+function routePullRequest(subset, triggers, action) {
+	if (typeof action !== "string") {
+		return { enqueue: false, reason: "unhandled-event" };
+	}
+	// Azure attaches no labels to a pull request, so a predicate cannot narrow one and a rule that carries
+	// a positive selector would never match. The loader refuses such a rule at load; here the action alone
+	// selects, and the actor's membership is the gate.
+	for (const rule of triggers.pullRequest ?? []) {
+		if (!rule.actions.has(action)) continue;
+		return {
+			enqueue: true,
+			action,
+			flow: rule.flow,
+			repository: rule.repository,
+			packages: rule.packages,
+			image: rule.image,
+			resume: rule.resume,
+			matched: { index: rule.index, type: "pull_request", action },
+			target: {
+				type: "pull_request",
+				number: subset.target?.number,
+				title: subset.target?.title,
+				body: subset.target?.body,
+				head: subset.target?.head,
+				base: subset.target?.base,
+			},
+		};
+	}
+	return { enqueue: false, reason: "no-matching-pr-trigger" };
+}
+
+/**
+ * The `{ repo, azure }` scope for this job, or `null` when the delivery and the rule between them do not
+ * name a repository.
+ *
+ * The project comes from the payload in both cases -- a delivery always names its project. Only the
+ * REPOSITORY differs: present on a pull-request event, absent on a work item and supplied by the rule.
+ */
+function resolveScope(subset, resolved) {
+	const project = subset.project?.name;
+	const projectId = subset.project?.id;
+	const repository = subset.repository?.name ?? resolved.repository;
+	if (typeof project !== "string" || project === "" || typeof repository !== "string" || repository === "") {
+		return null;
+	}
+	return {
+		repo: `${project}/${repository}`,
+		azure: {
+			project,
+			...(typeof projectId === "string" && projectId !== "" ? { projectId } : {}),
+			repository,
+			// The repository ID is what every Azure git API path actually takes. It is present on a
+			// pull-request delivery and absent on a work item, where the host resolves it by name instead.
+			...(typeof subset.repository?.id === "string" && subset.repository.id !== "" ? { repositoryId: subset.repository.id } : {}),
+		},
+	};
+}
+
+/**
+ * A stable, opaque id for an actor known only by email address.
+ *
+ * Truncated to 16 hex characters: long enough that a collision is not a practical concern for the number
+ * of humans in one Azure DevOps organization, short enough to read in a log line. Not reversible, and not
+ * meant to be -- its only job is to let two records be compared for "same person".
+ */
+function stableActorId(email) {
+	return `azid-${createHash("sha256").update(String(email)).digest("hex").slice(0, 16)}`;
+}