pi-amq 0.1.1

package/skills/coordination-patterns/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: coordination-patterns
+description: Coordinates role-separated implementation and independent review over existing AMQ peers or supervised pi workers. Use when a task benefits from bounded fan-out, explicit acceptance criteria, fresh-evidence audit, and driver-owned synthesis. Skip when the work is smaller than the coordination overhead.
+compatibility: Existing-peer mail needs a verified AMQ roster. Local supervised workers need the pi-amq WorkerRuntime and do not require AMQ binding.
+---
+
+# Coordination Patterns
+
+Use this skill for either coordination flavor below. It is advisory: adapt or stop when evidence changes, while preserving role, evidence, and verification boundaries.
+
+## Driver posture
+
+The driver owns decomposition, authority, collection, synthesis, and final acceptance. Workers return bounded candidates and evidence; their prose never completes a task by itself. Prefer a few well-separated workers over broad speculative fan-out. Observe stall facts without inventing a nudge, retry, or cancellation policy.
+
+## Existing-peer mail team
+
+1. Confirm that the needed peers already exist in the AMQ roster. Do not invent or spawn a worker.
+2. Give each task one explicit role charter, bounded scope, acceptance criteria, constraints, and expected evidence.
+3. Dispatch the task as `kind=todo` through the existing AMQ transport.
+4. Require the implementer to report outcome, evidence, unrun checks, and residual risk by replying to the exact task envelope.
+5. Re-run decisive checks and inspect the named evidence independently in the driver context.
+6. Assign audit to a different context from implementation. The auditor reads the authoritative change and obtains fresh evidence.
+7. Record approve/reject by replying in the implementation task thread. That thread is the authorization ledger; a detached status message is not approval.
+
+Read [the current mail-team few-shot](references/today-mail-team.md) when a concrete sequence is useful.
+
+## Supervised worker fan-out
+
+1. Split only independent evidence or implementation packets with explicit acceptance criteria and hard constraints.
+2. Pick the narrowest named role: scout maps, worker implements, reviewer audits, oracle resolves ambiguity, and researcher sources evidence. Explicit difficulty or capabilities override role defaults; model selection remains mechanical against the live catalog.
+3. Call `spawn_worker` once per bounded packet. Declare role, goal, acceptance, constraints, every budget dimension, and any report/check/approval facts. Use RPC when steering or mid-run interaction is expected; JSON is one-shot.
+4. Use `list_workers` for authoritative state, Gate blockers, revision delivery, budget, and stall facts.
+5. Use `collect` for candidates and evidence. Collection is an observation; `done` requires every declared Gate fact.
+6. Use `revise_contract` for contract changes and `steer` only for conversation. Revisions arrive after generation-correlated `agent_settled` without interrupting in-flight inference.
+7. Keep synthesis and final judgment in the driver context. If independent review matters, spawn an auditor with source-based acceptance criteria.
+
+Read [the supervised worker few-shot](references/supervised-worker-fan-out.md) before running a multi-worker sequence.
+
+## Boundary
+
+The runtime exposes atomic facts and verbs, not a workflow engine. Contract, Ledger, Lease/launch, Gate, and Delivery are the five governance domains; `WorkerLaunchAuthority` enforces grants under Lease/launch and a request is never a grant. `blocked` is reserved for the RPC child `wait_for_input` fact with a reason and correlation; natural-language waiting is not inferred, blocked workers do not accrue stalls, and only exact-correlated steer, revision, or peer delivery wakes them. Named roles are Contract-default declarations, not ambient addresses or teams. A worker may message only an exact `message_worker:<workerId-or-role>` directional grant; a role must resolve uniquely, the supervisor waits for the recipient inference boundary, and both endpoint projections share the correlated Ledger fact. The runtime has no peer-topology mutation, automatic retry, nudge, pipeline, scheduling preset, or workflow DSL. Coordination examples do not create runtime policy.

package/skills/coordination-patterns/references/supervised-worker-fan-out.md

@@ -0,0 +1,12 @@
+# Supervised worker fan-out
+
+User goal: inspect an implementation, repair the proven defect, and obtain an independent audit.
+
+1. The driver calls `spawn_worker` for a read-only investigator with `difficulty=medium`, a narrow workspace grant, explicit limited/unlimited values for every worker budget dimension, and acceptance criteria requiring exact file evidence and a falsifiable reproducer.
+2. After `collect`, the driver inspects the cited seam and calls `spawn_worker` for one implementer. Its acceptance criteria name the behavior, targeted test, and allowed files. The driver keeps the implementer's selected model for the later audit floor.
+3. If acceptance changes while the implementer is running, the driver calls `revise_contract`; `steer` is conversation and never changes the contract. The ledger shows `pending`; the supervisor delivers the revised canonical capsule only after generation-correlated `agent_settled`, then records `delivered`.
+4. The driver calls `collect`. A candidate report can remain `running` when evidence, `report_schema`, `acceptance_check`, budget, or human approval blocks the Gate.
+5. The driver calls `spawn_worker` for an auditor with the implementer's exact `audits_worker_id`; the runtime floors auditor capability at that implementer's model. The auditor receives read-only authority and acceptance criteria requiring fresh evidence, not agreement with the implementer.
+6. The driver reruns the decisive check, reconciles any ambiguity explicitly, and owns the final response.
+
+At every step, `list_workers` is the authoritative view. `stall.silent` and `stall.no_progress` are running-only observations; neither authorizes nudge, redelivery, retry, or cancellation. `blocked` means the RPC child declared `wait_for_input` with a reason and correlation, never a guess from prose or silence; wake it only with the exact correlation on steer, revision, or granted peer delivery. Contract, Ledger, Lease/launch, Gate, and Delivery remain separate; requested capability is not a launch grant.

package/skills/coordination-patterns/references/today-mail-team.md

@@ -0,0 +1,36 @@
+# Existing-peer mail team few-shot
+
+This example uses only peers already present in the AMQ roster.
+
+## Objective
+
+Implement a bounded transport change and obtain an independent sign-off.
+
+## Driver dispatches implementation
+
+Send one `kind=todo` task to the implementer with:
+
+- role charter: implement the named transport behavior; do not review your own result;
+- scope: exact files or module ownership;
+- acceptance criteria: observable outcomes and failure semantics;
+- hard constraints: authority boundaries, prohibited mutations, and stop conditions; and
+- evidence: exact tests, logs, or artifacts the report must cite.
+
+The implementer replies to that exact envelope with the outcome, fresh test evidence, unrun checks, and residual risk. A status-only message is progress, not completion.
+
+## Driver verifies and dispatches audit
+
+The driver inspects the change and reruns the decisive checks instead of forwarding the implementer's claims. Then send a separate `kind=todo` task to an auditor in a different context with:
+
+- role charter: audit correctness and contract compliance, not implementation style;
+- the authoritative diff or artifact paths;
+- the same acceptance criteria and hard constraints; and
+- a required approve/reject verdict backed by fresh evidence.
+
+The implementer and auditor are never the same context.
+
+This existing-peer mail pattern does not create worker-runtime state. When the local worker tools are used instead, preserve the five-domain split—Contract, Ledger, Lease/launch, Gate, and Delivery—and never treat a requested capability as a launch grant. A worker is `blocked` only after a correlated typed wait fact; running-only stall observations do not imply action.
+
+## Threaded authorization
+
+After resolving audit findings, reply approve/reject in the original implementation task thread. The verdict reply is the authorization record for that task. Detached mail, presence, drained receipts, and worker self-reports do not authorize landing.

package/transport/amq-cli-adapter.ts

@@ -0,0 +1,381 @@
+import { spawn } from "node:child_process";
+import { chmod, mkdtemp, open, rmdir, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+const DEFAULT_OUTPUT_BOUND = 1024 * 1024;
+const DEFAULT_BODY_FILE_THRESHOLD = 8 * 1024;
+
+export type AmqExitCategory =
+  | "success"
+  | "error"
+  | "usage"
+  | "not-found"
+  | "timeout"
+  | "context-mismatch"
+  | "invalid-json"
+  | "output-limit"
+  | "cancelled"
+  | "spawn-error"
+  | "process-crash"
+  | "cleanup-failed";
+
+export interface AmqCliAdapterOptions {
+  readonly binaryPath: string;
+  readonly maxStdoutBytes?: number;
+  readonly maxStderrBytes?: number;
+  readonly bodyFileThresholdBytes?: number;
+  readonly tempDirectory?: string;
+  readonly env?: Readonly<NodeJS.ProcessEnv>;
+}
+
+export interface AmqRunOptions<T> {
+  readonly cwd?: string;
+  readonly env?: Readonly<NodeJS.ProcessEnv>;
+  readonly signal?: AbortSignal;
+  readonly parse?: (value: unknown) => T;
+}
+
+export interface AmqCommandResult<T> {
+  readonly ok: boolean;
+  readonly category: AmqExitCategory;
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly stdoutTruncated: boolean;
+  readonly stderrTruncated: boolean;
+  readonly json?: T;
+  readonly jsonError?: Error;
+  readonly processError?: Error;
+}
+
+interface ProcessCapture {
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly stdoutTruncated: boolean;
+  readonly stderrTruncated: boolean;
+  readonly aborted: boolean;
+  readonly processError?: Error;
+}
+
+interface TemporaryBody {
+  readonly directory: string;
+  readonly path: string;
+}
+
+/**
+ * The sole process boundary for AMQ commands.
+ *
+ * It never invokes a shell, never infers routing identity, and always preserves
+ * bounded stdout for callers to inspect even when AMQ exits nonzero.
+ */
+export class AmqCliAdapter {
+  readonly #binaryPath: string;
+  readonly #maxStdoutBytes: number;
+  readonly #maxStderrBytes: number;
+  readonly #bodyFileThresholdBytes: number;
+  readonly #tempDirectory: string;
+  readonly #env: NodeJS.ProcessEnv;
+
+  constructor(options: AmqCliAdapterOptions) {
+    if (!isAbsolute(options.binaryPath)) {
+      throw new TypeError("AMQ binary path must be absolute");
+    }
+    this.#binaryPath = options.binaryPath;
+    this.#maxStdoutBytes = positiveInteger(
+      options.maxStdoutBytes ?? DEFAULT_OUTPUT_BOUND,
+      "maxStdoutBytes",
+    );
+    this.#maxStderrBytes = positiveInteger(
+      options.maxStderrBytes ?? DEFAULT_OUTPUT_BOUND,
+      "maxStderrBytes",
+    );
+    this.#bodyFileThresholdBytes = nonNegativeInteger(
+      options.bodyFileThresholdBytes ?? DEFAULT_BODY_FILE_THRESHOLD,
+      "bodyFileThresholdBytes",
+    );
+    this.#tempDirectory = options.tempDirectory ?? tmpdir();
+    this.#env = { ...process.env, ...options.env };
+  }
+
+  async runJson<T = unknown>(
+    argv: readonly string[],
+    options: AmqRunOptions<T> = {},
+  ): Promise<AmqCommandResult<T>> {
+    validateArgv(argv);
+    const jsonArgv = argv.includes("--json") ? [...argv] : [...argv, "--json"];
+    const capture = await this.#execute(jsonArgv, options);
+    return parseJsonCapture(capture, options.parse);
+  }
+
+  async runJsonWithBody<T = unknown>(
+    argv: readonly string[],
+    body: string,
+    options: AmqRunOptions<T> = {},
+  ): Promise<AmqCommandResult<T>> {
+    validateArgv(argv);
+    const requiresFile =
+      body.includes("\0") || Buffer.byteLength(body) > this.#bodyFileThresholdBytes;
+    if (!requiresFile) {
+      return this.runJson([...argv, "--body", body], options);
+    }
+
+    const temporary = await createTemporaryBody(this.#tempDirectory, body);
+    let result: AmqCommandResult<T> | undefined;
+    let executionError: Error | undefined;
+    try {
+      result = await this.runJson([...argv, "--body", `@${temporary.path}`], options);
+    } catch (error) {
+      executionError = toError(error);
+    }
+
+    const cleanupError = await cleanupTemporaryBody(temporary);
+    if (executionError) {
+      if (cleanupError) {
+        throw new AggregateError(
+          [executionError, cleanupError],
+          "AMQ command and temporary body cleanup both failed",
+        );
+      }
+      throw executionError;
+    }
+    if (!result) throw new Error("AMQ command completed without a result");
+    if (!cleanupError) return result;
+    return {
+      ...result,
+      ok: false,
+      category: "cleanup-failed",
+      processError: cleanupError,
+    };
+  }
+
+  async #execute<T>(
+    argv: readonly string[],
+    options: AmqRunOptions<T>,
+  ): Promise<ProcessCapture> {
+    if (options.signal?.aborted) {
+      return emptyCapture(true);
+    }
+
+    return new Promise((resolve) => {
+      const stdout = new BoundedCapture(this.#maxStdoutBytes);
+      const stderr = new BoundedCapture(this.#maxStderrBytes);
+      let child;
+      try {
+        child = spawn(this.#binaryPath, argv, {
+          cwd: options.cwd,
+          env: { ...this.#env, ...options.env },
+          shell: false,
+          stdio: ["ignore", "pipe", "pipe"],
+          windowsHide: true,
+        });
+      } catch (error) {
+        resolve({ ...emptyCapture(false), processError: toError(error) });
+        return;
+      }
+
+      let settled = false;
+      let aborted = false;
+      let processError: Error | undefined;
+      let outputLimitExceeded = false;
+
+      const stopForOutputLimit = (): void => {
+        if (outputLimitExceeded) return;
+        outputLimitExceeded = true;
+        child.kill("SIGKILL");
+      };
+      child.stdout.on("data", (chunk: Buffer) => {
+        if (stdout.append(chunk)) stopForOutputLimit();
+      });
+      child.stderr.on("data", (chunk: Buffer) => {
+        if (stderr.append(chunk)) stopForOutputLimit();
+      });
+
+      const onAbort = (): void => {
+        aborted = true;
+        child.kill("SIGTERM");
+      };
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+
+      const settle = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
+        if (settled) return;
+        settled = true;
+        options.signal?.removeEventListener("abort", onAbort);
+        resolve({
+          exitCode,
+          signal,
+          stdout: stdout.value(),
+          stderr: stderr.value(),
+          stdoutTruncated: stdout.truncated,
+          stderrTruncated: stderr.truncated,
+          aborted,
+          ...(processError ? { processError } : {}),
+        });
+      };
+
+      child.once("error", (error) => {
+        processError = error;
+      });
+      child.once("close", settle);
+    });
+  }
+}
+
+class BoundedCapture {
+  readonly #limit: number;
+  readonly #chunks: Buffer[] = [];
+  #capturedBytes = 0;
+  truncated = false;
+
+  constructor(limit: number) {
+    this.#limit = limit;
+  }
+
+  append(chunk: Buffer): boolean {
+    const remaining = this.#limit - this.#capturedBytes;
+    if (remaining > 0) {
+      const captured = chunk.length <= remaining ? chunk : chunk.subarray(0, remaining);
+      this.#chunks.push(Buffer.from(captured));
+      this.#capturedBytes += captured.length;
+    }
+    if (chunk.length > remaining) this.truncated = true;
+    return this.truncated;
+  }
+
+  value(): string {
+    return Buffer.concat(this.#chunks, this.#capturedBytes).toString("utf8");
+  }
+}
+
+function parseJsonCapture<T>(
+  capture: ProcessCapture,
+  parser: ((value: unknown) => T) | undefined,
+): AmqCommandResult<T> {
+  let json: T | undefined;
+  let jsonError: Error | undefined;
+  try {
+    const raw = capture.stdout.trim();
+    if (raw.length === 0) throw new Error("AMQ returned empty JSON stdout");
+    const value: unknown = JSON.parse(raw);
+    json = parser ? parser(value) : (value as T);
+  } catch (error) {
+    jsonError = toError(error);
+  }
+
+  const category = categorize(capture, jsonError);
+  return {
+    ok: category === "success",
+    category,
+    exitCode: capture.exitCode,
+    signal: capture.signal,
+    stdout: capture.stdout,
+    stderr: capture.stderr,
+    stdoutTruncated: capture.stdoutTruncated,
+    stderrTruncated: capture.stderrTruncated,
+    ...(json === undefined ? {} : { json }),
+    ...(jsonError ? { jsonError } : {}),
+    ...(capture.processError ? { processError: capture.processError } : {}),
+  };
+}
+
+function categorize(capture: ProcessCapture, jsonError: Error | undefined): AmqExitCategory {
+  if (capture.aborted) return "cancelled";
+  if (capture.stdoutTruncated || capture.stderrTruncated) return "output-limit";
+  if (capture.processError) return "spawn-error";
+  if (capture.exitCode === null) return "process-crash";
+  switch (capture.exitCode) {
+    case 0:
+      return jsonError ? "invalid-json" : "success";
+    case 1:
+      return "error";
+    case 2:
+      return "usage";
+    case 3:
+      return "not-found";
+    case 4:
+      return "timeout";
+    case 5:
+      return "context-mismatch";
+    default:
+      return "error";
+  }
+}
+
+async function createTemporaryBody(parent: string, body: string): Promise<TemporaryBody> {
+  const directory = await mkdtemp(join(parent, "pi-amq-body-"));
+  await chmod(directory, 0o700);
+  const path = join(directory, "body");
+  try {
+    const handle = await open(path, "wx", 0o600);
+    try {
+      await handle.writeFile(body, "utf8");
+    } finally {
+      await handle.close();
+    }
+    await chmod(path, 0o600);
+    return { directory, path };
+  } catch (error) {
+    await cleanupTemporaryBody({ directory, path });
+    throw error;
+  }
+}
+
+async function cleanupTemporaryBody(temporary: TemporaryBody): Promise<Error | undefined> {
+  const errors: Error[] = [];
+  try {
+    await unlink(temporary.path);
+  } catch (error) {
+    if (!isMissing(error)) errors.push(toError(error));
+  }
+  try {
+    await rmdir(temporary.directory);
+  } catch (error) {
+    if (!isMissing(error)) errors.push(toError(error));
+  }
+  if (errors.length === 0) return undefined;
+  return errors.length === 1 ? errors[0] : new AggregateError(errors, "temporary AMQ body cleanup failed");
+}
+
+function validateArgv(argv: readonly string[]): void {
+  if (argv.length === 0) throw new TypeError("AMQ argv must include a command");
+  for (const argument of argv) {
+    if (argument.includes("\0")) throw new TypeError("AMQ argv cannot contain NUL bytes");
+  }
+}
+
+function positiveInteger(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer`);
+  }
+  return value;
+}
+
+function nonNegativeInteger(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`${name} must be a non-negative safe integer`);
+  }
+  return value;
+}
+
+function emptyCapture(aborted: boolean): ProcessCapture {
+  return {
+    exitCode: null,
+    signal: null,
+    stdout: "",
+    stderr: "",
+    stdoutTruncated: false,
+    stderrTruncated: false,
+    aborted,
+  };
+}
+
+function isMissing(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

package/transport/amq-message.ts

@@ -0,0 +1,218 @@
+export type AmqPriority = "urgent" | "normal" | "low";
+
+export interface AmqHeaderV1 {
+  readonly schema: 1;
+  readonly id: string;
+  readonly from: string;
+  readonly to: readonly string[];
+  readonly thread: string;
+  readonly subject: string;
+  readonly created: string;
+  readonly priority: AmqPriority;
+  readonly kind: string;
+  readonly labels: readonly string[];
+  readonly context: Readonly<Record<string, unknown>>;
+  readonly replyTo: string;
+  readonly replyProject: string;
+  readonly fromProject: string;
+}
+
+export interface AmqMessage {
+  readonly header: AmqHeaderV1;
+  readonly body: string;
+}
+
+export interface WatchCandidate {
+  readonly id: string;
+  readonly priority: AmqPriority;
+  readonly created: string;
+  readonly parseError?: string;
+}
+
+export interface WatchCohort {
+  readonly event: "existing" | "new_message" | "timeout";
+  readonly messages: readonly WatchCandidate[];
+}
+
+export type AmqReadOutcome =
+  | { readonly kind: "message"; readonly message: AmqMessage }
+  | { readonly kind: "dlq"; readonly id: string; readonly diagnostic: string };
+
+const PRIORITY_RANK: Readonly<Record<AmqPriority, number>> = {
+  urgent: 0,
+  normal: 1,
+  low: 2,
+};
+
+const VALID_KINDS = new Set([
+  "",
+  "brainstorm",
+  "review_request",
+  "review_response",
+  "question",
+  "answer",
+  "decision",
+  "status",
+  "todo",
+]);
+
+export function parseWatchCohort(value: unknown): WatchCohort {
+  const object = record(value, "amq watch --json");
+  const event = object.event;
+  if (event !== "existing" && event !== "new_message" && event !== "timeout") {
+    throw new Error("amq watch event is invalid");
+  }
+  const rawMessages = object.messages ?? [];
+  if (!Array.isArray(rawMessages)) throw new Error("amq watch messages must be an array");
+  return {
+    event,
+    messages: rawMessages.map(parseWatchCandidate),
+  };
+}
+
+export function parseMessageList(value: unknown): readonly WatchCandidate[] {
+  if (!Array.isArray(value)) throw new Error("amq list --json must return an array");
+  return value.map(parseWatchCandidate);
+}
+
+export function parseWatchCandidate(value: unknown): WatchCandidate {
+  const object = record(value, "AMQ message header projection");
+  const id = messageId(object.id);
+  const parseError = optionalString(object.parse_error, "parse_error");
+  const created = stringOrEmpty(object.created, "created");
+  const rawPriority = stringOrEmpty(object.priority, "priority");
+  if (!parseError) requireIso(created, "created");
+  return {
+    id,
+    priority: parsePriority(rawPriority),
+    created,
+    ...(parseError ? { parseError } : {}),
+  };
+}
+
+export function parseAmqReadOutcome(value: unknown): AmqReadOutcome {
+  const object = record(value, "amq read --json");
+  if (object.moved_to_dlq === true) {
+    return {
+      kind: "dlq",
+      id: messageId(object.id),
+      diagnostic: requiredString(object.parse_error, "parse_error"),
+    };
+  }
+  const header = parseAmqHeaderV1(object.header);
+  const body = object.body;
+  if (typeof body !== "string") throw new Error("amq read body must be a string");
+  return { kind: "message", message: { header, body } };
+}
+
+export function parseAmqHeaderV1(value: unknown): AmqHeaderV1 {
+  const object = record(value, "AMQ header");
+  if (number(object.schema, "schema") !== 1) throw new Error("AMQ header schema must be 1");
+  const kind = stringOrEmpty(object.kind, "kind");
+  if (!VALID_KINDS.has(kind)) throw new Error(`AMQ header kind is invalid: ${kind}`);
+  const context = object.context === undefined
+    ? {}
+    : record(object.context, "AMQ header context");
+  const header: AmqHeaderV1 = {
+    schema: 1,
+    id: messageId(object.id),
+    from: requiredString(object.from, "from"),
+    to: stringArray(object.to, "to", false),
+    thread: requiredString(object.thread, "thread"),
+    subject: stringOrEmpty(object.subject, "subject"),
+    created: requireIso(requiredString(object.created, "created"), "created"),
+    priority: parsePriority(stringOrEmpty(object.priority, "priority")),
+    kind,
+    labels: stringArray(object.labels ?? [], "labels", true),
+    context,
+    replyTo: stringOrEmpty(object.reply_to, "reply_to"),
+    replyProject: stringOrEmpty(object.reply_project, "reply_project"),
+    fromProject: stringOrEmpty(object.from_project, "from_project"),
+  };
+  return header;
+}
+
+export function sortAndDeduplicateCandidates(
+  candidates: readonly WatchCandidate[],
+): readonly WatchCandidate[] {
+  const sorted = [...candidates].sort(compareIncoming);
+  const seen = new Set<string>();
+  return sorted.filter((candidate) => {
+    if (seen.has(candidate.id)) return false;
+    seen.add(candidate.id);
+    return true;
+  });
+}
+
+export function sortMessages(messages: readonly AmqMessage[]): readonly AmqMessage[] {
+  return [...messages].sort((left, right) => compareIncoming(
+    { id: left.header.id, priority: left.header.priority, created: left.header.created },
+    { id: right.header.id, priority: right.header.priority, created: right.header.created },
+  ));
+}
+
+function compareIncoming(left: WatchCandidate, right: WatchCandidate): number {
+  const invalidOrder = Number(Boolean(right.parseError)) - Number(Boolean(left.parseError));
+  if (invalidOrder !== 0) return invalidOrder;
+  const priorityOrder = PRIORITY_RANK[left.priority] - PRIORITY_RANK[right.priority];
+  if (priorityOrder !== 0) return priorityOrder;
+  const createdOrder = left.created.localeCompare(right.created);
+  return createdOrder !== 0 ? createdOrder : left.id.localeCompare(right.id);
+}
+
+function parsePriority(value: string): AmqPriority {
+  if (value === "" || value === "normal") return "normal";
+  if (value === "urgent" || value === "low") return value;
+  throw new Error(`AMQ priority is invalid: ${value}`);
+}
+
+function messageId(value: unknown): string {
+  const id = requiredString(value, "id");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,254}$/.test(id)) {
+    throw new Error("AMQ message ID is not safe for the extension namespace");
+  }
+  return id;
+}
+
+function record(value: unknown, name: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${name} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requiredString(value: unknown, name: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+
+function optionalString(value: unknown, name: string): string | undefined {
+  if (value === undefined || value === "") return undefined;
+  if (typeof value !== "string") throw new Error(`${name} must be a string`);
+  return value;
+}
+
+function stringOrEmpty(value: unknown, name: string): string {
+  if (value === undefined) return "";
+  if (typeof value !== "string") throw new Error(`${name} must be a string`);
+  return value;
+}
+
+function stringArray(value: unknown, name: string, allowEmpty: boolean): readonly string[] {
+  if (!Array.isArray(value) || (!allowEmpty && value.length === 0)) {
+    throw new Error(`${name} must be ${allowEmpty ? "an" : "a non-empty"} array`);
+  }
+  return value.map((item, index) => requiredString(item, `${name}[${index}]`));
+}
+
+function number(value: unknown, name: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${name} must be a number`);
+  return value;
+}
+
+function requireIso(value: string, name: string): string {
+  if (!Number.isFinite(Date.parse(value))) throw new Error(`${name} must be an ISO timestamp`);
+  return value;
+}