@sleep2agi/commhub-server 0.9.0-preview.28 → 0.9.0-preview.29

package/src/task-diagnostic-http.test.ts

@@ -0,0 +1,145 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-task-diagnostic-"));
+process.env.COMMHUB_DB = join(PRIVATE_DB_DIR, "hub.db");
+
+let db: typeof import("./db.js").db;
+let server: ReturnType<typeof Bun.serve>;
+let base = "";
+let tokenA = "";
+let tokenB = "";
+let networkA = "";
+let networkB = "";
+
+const ALIAS = "diagnostic-worker";
+
+async function detail(token: string, taskId: string): Promise<{ status: number; body: any }> {
+  const response = await fetch(`${base}/api/tasks/${encodeURIComponent(taskId)}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  return { status: response.status, body: await response.json() };
+}
+
+function insertTask(taskId: string, patch: {
+  status?: string;
+  runtimeSubmittedAt?: string | null;
+  consumedAt?: string | null;
+} = {}) {
+  db.run(
+    `INSERT INTO tasks
+       (task_id, from_name, to_node_id, to_name, status, content, priority,
+        network_id, runtime_submitted_at, consumed_at)
+     VALUES (?1, 'diagnostic-sender', 'node-diagnostic-a', ?2, ?3,
+             'diagnose me', 'normal', ?4, ?5, ?6)`,
+    [taskId, ALIAS, patch.status ?? "delivered", networkA, patch.runtimeSubmittedAt ?? null, patch.consumedAt ?? null],
+  );
+}
+
+async function openSse(token: string, networkId: string): Promise<ReadableStreamDefaultReader<Uint8Array>> {
+  const response = await fetch(`${base}/events/${encodeURIComponent(ALIAS)}?network_id=${encodeURIComponent(networkId)}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  expect(response.status).toBe(200);
+  const reader = response.body!.getReader();
+  const first = await reader.read();
+  expect(new TextDecoder().decode(first.value)).toContain('"type":"connected"');
+  return reader;
+}
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register } = await import("./auth.js");
+  const authA = register(`diagnostic_a_${Date.now()}`, "Diagnostic-A-Strong-1!", undefined, "diagnostic-a");
+  const authB = register(`diagnostic_b_${Date.now()}`, "Diagnostic-B-Strong-1!", undefined, "diagnostic-b");
+  expect(authA.ok).toBe(true);
+  expect(authB.ok).toBe(true);
+  tokenA = authA.token!;
+  tokenB = authB.token!;
+  networkA = authA.network_id!;
+  networkB = authB.network_id!;
+
+  for (const [networkId, suffix] of [[networkA, "a"], [networkB, "b"]] as const) {
+    db.run(
+      `INSERT INTO nodes
+         (node_id, node_name, alias, network_id, hostname, created_at, updated_at, lifecycle_state)
+       VALUES (?1, ?2, ?2, ?3, 'diagnostic-host', datetime('now'), datetime('now'), 'active')`,
+      [`node-diagnostic-${suffix}`, ALIAS, networkId],
+    );
+    db.run(
+      `INSERT INTO sessions
+         (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at)
+       VALUES (?1, ?2, 'idle', ?3, ?4, datetime('now'), datetime('now'))`,
+      [`resume-diagnostic-${suffix}`, ALIAS, `node-diagnostic-${suffix}`, networkId],
+    );
+  }
+
+  const mod = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+});
+
+afterAll(() => {
+  try { server?.stop(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("#166 scoped single-task diagnostics", () => {
+  test("does not count another network's same-alias SSE connection", async () => {
+    insertTask("diag-cross-network");
+    const foreignReader = await openSse(tokenB, networkB);
+    try {
+      const own = await detail(tokenA, "diag-cross-network");
+      expect(own.status).toBe(200);
+      expect(own.body.diagnostic).toMatchObject({
+        code: "target_no_live_sse",
+        evidence: { live_sse_connections: 0 },
+      });
+      const foreign = await detail(tokenB, "diag-cross-network");
+      expect(foreign.status).toBe(404);
+      expect(foreign.body).toMatchObject({ ok: false, error: "task_not_found" });
+    } finally {
+      await foreignReader.cancel();
+    }
+  });
+
+  test("reports a live same-network SSE without claiming runtime consumption", async () => {
+    insertTask("diag-live-sse");
+    const reader = await openSse(tokenA, networkA);
+    try {
+      const result = await detail(tokenA, "diag-live-sse");
+      expect(result.body.diagnostic).toMatchObject({
+        code: "delivered_waiting_for_agent",
+        evidence: {
+          target_session_status: "idle",
+          live_sse_connections: 1,
+          runtime_submitted: false,
+          runtime_consumed: false,
+        },
+      });
+    } finally {
+      await reader.cancel();
+    }
+  });
+
+  test("uses authoritative runtime evidence before current connectivity", async () => {
+    insertTask("diag-submitted", { runtimeSubmittedAt: "2026-08-10T00:00:00Z" });
+    insertTask("diag-consumed", {
+      runtimeSubmittedAt: "2026-08-10T00:00:00Z",
+      consumedAt: "2026-08-10T00:00:01Z",
+    });
+    db.run("UPDATE sessions SET status = 'offline' WHERE node_id = 'node-diagnostic-a' AND network_id = ?1", [networkA]);
+    expect((await detail(tokenA, "diag-submitted")).body.diagnostic.code).toBe("runtime_submitted_waiting_for_signal");
+    expect((await detail(tokenA, "diag-consumed")).body.diagnostic.code).toBe("runtime_consumed_nonterminal");
+  });
+
+  test("distinguishes offline and missing target sessions", async () => {
+    insertTask("diag-offline");
+    expect((await detail(tokenA, "diag-offline")).body.diagnostic.code).toBe("target_session_offline");
+    db.run("DELETE FROM sessions WHERE node_id = 'node-diagnostic-a' AND network_id = ?1", [networkA]);
+    insertTask("diag-missing");
+    expect((await detail(tokenA, "diag-missing")).body.diagnostic.code).toBe("target_session_missing");
+  });
+});

package/src/task-diagnostic.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import { diagnoseTask, type TaskDiagnosticInput } from "./task-diagnostic";
+
+const base = (patch: Partial<TaskDiagnosticInput> = {}): TaskDiagnosticInput => ({
+  status: "delivered",
+  runtimeSubmittedAt: null,
+  consumedAt: null,
+  targetSessionStatus: "idle",
+  targetSessionExists: true,
+  liveSseConnections: 1,
+  ...patch,
+});
+
+describe("#166 evidence-only task diagnostics", () => {
+  test("terminal state wins over stale transport and runtime evidence", () => {
+    expect(diagnoseTask(base({
+      status: "replied",
+      runtimeSubmittedAt: "2026-08-10T00:00:00Z",
+      consumedAt: "2026-08-10T00:00:01Z",
+      targetSessionExists: false,
+      targetSessionStatus: null,
+      liveSseConnections: 0,
+    }))).toMatchObject({ code: "terminal", action_hint: "none" });
+  });
+
+  test("runtime evidence outranks current target connectivity", () => {
+    expect(diagnoseTask(base({ consumedAt: "2026-08-10T00:00:01Z", liveSseConnections: 0 }))).toMatchObject({
+      code: "runtime_consumed_nonterminal",
+      action_hint: "inspect_runtime",
+    });
+    expect(diagnoseTask(base({ runtimeSubmittedAt: "2026-08-10T00:00:00Z", targetSessionStatus: "offline" }))).toMatchObject({
+      code: "runtime_submitted_waiting_for_signal",
+      action_hint: "inspect_runtime",
+    });
+  });
+
+  test("distinguishes missing, offline, and no-SSE targets", () => {
+    expect(diagnoseTask(base({ targetSessionExists: false, targetSessionStatus: null }))).toMatchObject({
+      code: "target_session_missing",
+      action_hint: "check_target_registration",
+    });
+    expect(diagnoseTask(base({ targetSessionStatus: "offline" }))).toMatchObject({
+      code: "target_session_offline",
+      action_hint: "restore_target",
+    });
+    expect(diagnoseTask(base({ liveSseConnections: 0 }))).toMatchObject({
+      code: "target_no_live_sse",
+      action_hint: "restore_sse",
+    });
+  });
+
+  test("does not infer consumption from lifecycle status alone", () => {
+    const diagnostic = diagnoseTask(base({ status: "running" }));
+    expect(diagnostic).toMatchObject({
+      code: "lifecycle_progress_without_runtime_evidence",
+      action_hint: "inspect_runtime",
+      evidence: { runtime_submitted: false, runtime_consumed: false },
+    });
+  });
+
+  test("reports delivered waiting only when registration and SSE are present", () => {
+    expect(diagnoseTask(base())).toEqual({
+      schema_version: 1,
+      code: "delivered_waiting_for_agent",
+      action_hint: "inspect_agent_queue",
+      evidence: {
+        task_status: "delivered",
+        target_session_status: "idle",
+        live_sse_connections: 1,
+        runtime_submitted: false,
+        runtime_consumed: false,
+      },
+    });
+  });
+
+  test("normalizes invalid SSE counts without widening the evidence", () => {
+    expect(diagnoseTask(base({ liveSseConnections: Number.NaN }))).toMatchObject({
+      code: "target_no_live_sse",
+      evidence: { live_sse_connections: 0 },
+    });
+  });
+});

package/src/task-diagnostic.ts

@@ -0,0 +1,89 @@
+const TERMINAL_STATUSES = new Set(["replied", "failed", "cancelled", "expired"]);
+
+export type TaskDiagnosticCode =
+  | "terminal"
+  | "runtime_consumed_nonterminal"
+  | "runtime_submitted_waiting_for_signal"
+  | "target_session_missing"
+  | "target_session_offline"
+  | "target_no_live_sse"
+  | "lifecycle_progress_without_runtime_evidence"
+  | "delivered_waiting_for_agent";
+
+export type TaskDiagnosticAction =
+  | "none"
+  | "inspect_runtime"
+  | "check_target_registration"
+  | "restore_target"
+  | "restore_sse"
+  | "inspect_agent_queue";
+
+export interface TaskDiagnosticInput {
+  status: string;
+  runtimeSubmittedAt: string | null;
+  consumedAt: string | null;
+  targetSessionStatus: string | null;
+  targetSessionExists: boolean;
+  liveSseConnections: number;
+}
+
+export interface TaskDiagnostic {
+  schema_version: 1;
+  code: TaskDiagnosticCode;
+  action_hint: TaskDiagnosticAction;
+  evidence: {
+    task_status: string;
+    target_session_status: string | null;
+    live_sse_connections: number;
+    runtime_submitted: boolean;
+    runtime_consumed: boolean;
+  };
+}
+
+/**
+ * Classify only facts the Hub can prove. This deliberately does not claim
+ * that a model session has (or lacks) MCP tools: that capability lives in an
+ * external runtime and is not observable from the Hub wire.
+ */
+export function diagnoseTask(input: TaskDiagnosticInput): TaskDiagnostic {
+  const liveSseConnections = Number.isSafeInteger(input.liveSseConnections) && input.liveSseConnections > 0
+    ? input.liveSseConnections
+    : 0;
+  const evidence: TaskDiagnostic["evidence"] = {
+    task_status: input.status,
+    target_session_status: input.targetSessionStatus,
+    live_sse_connections: liveSseConnections,
+    runtime_submitted: Boolean(input.runtimeSubmittedAt),
+    runtime_consumed: Boolean(input.consumedAt),
+  };
+
+  let code: TaskDiagnosticCode;
+  let action_hint: TaskDiagnosticAction;
+  if (TERMINAL_STATUSES.has(input.status)) {
+    code = "terminal";
+    action_hint = "none";
+  } else if (input.consumedAt) {
+    code = "runtime_consumed_nonterminal";
+    action_hint = "inspect_runtime";
+  } else if (input.runtimeSubmittedAt) {
+    code = "runtime_submitted_waiting_for_signal";
+    action_hint = "inspect_runtime";
+  } else if (!input.targetSessionExists) {
+    code = "target_session_missing";
+    action_hint = "check_target_registration";
+  } else if (input.targetSessionStatus === "offline") {
+    code = "target_session_offline";
+    action_hint = "restore_target";
+  } else if (liveSseConnections === 0) {
+    code = "target_no_live_sse";
+    action_hint = "restore_sse";
+  } else if (input.status === "acked" || input.status === "running") {
+    code = "lifecycle_progress_without_runtime_evidence";
+    action_hint = "inspect_runtime";
+  } else {
+    code = "delivered_waiting_for_agent";
+    action_hint = "inspect_agent_queue";
+  }
+
+  return { schema_version: 1, code, action_hint, evidence };
+}

package/src/task-idempotency-mcp.test.ts

@@ -0,0 +1,137 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import { sharedSendDedup } from "./send_dedup.js";
+
+const NET = "net_chat_idem";
+const USER = "user_chat_idem";
+const TARGET = "node_chat_idem";
+
+type ToolHandler = (args: any) => Promise<{ content: Array<{ type: "text"; text: string }> }>;
+
+function cleanup() {
+  for (const table of ["tasks", "inbox", "task_events"]) {
+    try { db.run(`DELETE FROM ${table} WHERE network_id = ?1`, [NET]); } catch {}
+  }
+  try { db.run("DELETE FROM sessions WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM nodes WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM network_members WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [USER]); } catch {}
+  sharedSendDedup.clear();
+}
+
+function seed() {
+  db.run("INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?1, 'x', 'user', datetime('now'))", [USER]);
+  db.run("INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))", [NET, USER]);
+  db.run("INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))", [USER, NET]);
+  db.run("INSERT INTO nodes (node_id, node_name, alias, network_id, hostname, created_at, updated_at, lifecycle_state) VALUES (?1, ?2, ?2, ?3, 'host', datetime('now'), datetime('now'), 'active')", [`id_${TARGET}`, TARGET, NET]);
+  db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at) VALUES (?1, ?2, 'idle', ?3, ?4, datetime('now'), datetime('now'))", [`resume_${TARGET}`, TARGET, `id_${TARGET}`, NET]);
+}
+
+function sendTaskHandler(auth?: { callerAlias: string; nodeToken: boolean }): ToolHandler {
+  const server = new McpServer({ name: "idempotency-test", version: "0" }) as any;
+  let handler: ToolHandler | undefined;
+  const original = server.tool.bind(server);
+  server.tool = (name: string, description: string, schema: any, candidate: ToolHandler) => {
+    if (name === "send_task") handler = candidate;
+    return original(name, description, schema, candidate);
+  };
+  registerTools(
+    server,
+    undefined,
+    NET,
+    USER,
+    auth?.callerAlias ?? USER,
+    auth?.nodeToken ?? false,
+    auth?.nodeToken ? "token_node_chat_idem" : null,
+  );
+  if (!handler) throw new Error("send_task handler missing");
+  return handler;
+}
+
+async function call(handler: ToolHandler, args: any) {
+  const result = await handler(args);
+  return JSON.parse(result.content[0].text);
+}
+
+beforeEach(() => { cleanup(); seed(); });
+afterAll(cleanup);
+
+describe("send_task durable idempotency", () => {
+  test("Hub stamps authenticated user origin and overrides client spoofing", async () => {
+    const handler = sendTaskHandler();
+    const sent = await call(handler, {
+      alias: TARGET,
+      task: "authenticated dashboard payload",
+      priority: "normal",
+      meta: {
+        source: "dashboard-chat",
+        client_request_id: "dreq_0123456789abcdef0123456789abcdef",
+        auth_origin: "node",
+      },
+    });
+    expect(sent.ok).toBe(true);
+    const task = db.get<{ meta_json: string }>("SELECT meta_json FROM tasks WHERE task_id = ?1", [sent.message_id]);
+    const inbox = db.get<{ meta_json: string }>("SELECT meta_json FROM inbox WHERE id = ?1", [sent.message_id]);
+    expect(JSON.parse(task!.meta_json).auth_origin).toBe("user");
+    expect(JSON.parse(inbox!.meta_json).auth_origin).toBe("user");
+  });
+
+  test("network-token caller cannot forge Dashboard user origin through MCP", async () => {
+    const handler = sendTaskHandler({ callerAlias: "node-origin-sender", nodeToken: true });
+    const sent = await call(handler, {
+      alias: TARGET,
+      task: "node attempts user-origin spoof",
+      priority: "normal",
+      meta: {
+        source: "dashboard-chat",
+        client_request_id: "dreq_fedcba9876543210fedcba9876543210",
+        auth_origin: "user",
+      },
+    });
+    expect(sent.ok).toBe(true);
+    const inbox = db.get<{ meta_json: string }>("SELECT meta_json FROM inbox WHERE id = ?1", [sent.message_id]);
+    expect(JSON.parse(inbox!.meta_json).auth_origin).toBe("node");
+  });
+
+  test("lost-response retry returns the original task and does not enqueue twice", async () => {
+    const handler = sendTaskHandler();
+    const args = {
+      alias: TARGET,
+      task: "chat idempotent payload",
+      priority: "normal",
+      meta: { client_request_id: "dreq_0123456789abcdef" },
+    };
+    const first = await call(handler, args);
+    const replay = await call(handler, args);
+
+    expect(first.ok).toBe(true);
+    expect(replay).toEqual({
+      ok: true,
+      message_id: first.message_id,
+      task_id: first.message_id,
+      task_status: "delivered",
+      idempotent_replay: true,
+    });
+    expect(db.get<{ count: number }>("SELECT COUNT(*) AS count FROM tasks WHERE network_id = ?1", [NET])?.count).toBe(1);
+    expect(db.get<{ count: number }>("SELECT COUNT(*) AS count FROM inbox WHERE network_id = ?1", [NET])?.count).toBe(1);
+  });
+
+  test("request-id reuse with changed content fails closed without a second row", async () => {
+    const handler = sendTaskHandler();
+    const base = {
+      alias: TARGET,
+      priority: "normal",
+      meta: { client_request_id: "dreq_0123456789abcdef" },
+    };
+    expect((await call(handler, { ...base, task: "first payload" })).ok).toBe(true);
+    expect(await call(handler, { ...base, task: "changed payload" })).toEqual({
+      ok: false,
+      error: "idempotency_conflict",
+      message: "client_request_id was already used with a different task payload",
+    });
+    expect(db.get<{ count: number }>("SELECT COUNT(*) AS count FROM tasks WHERE network_id = ?1", [NET])?.count).toBe(1);
+  });
+});

package/src/task-idempotency.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import {
+  clientRequestIdFromMeta,
+  idempotentTaskId,
+  idempotentTaskMatches,
+  type StoredIdempotentTask,
+} from "./task-idempotency.js";
+
+describe("dashboard task idempotency", () => {
+  test("accepts only bounded dashboard request ids", () => {
+    expect(clientRequestIdFromMeta({ client_request_id: "dreq_0123456789abcdef" })).toBe("dreq_0123456789abcdef");
+    expect(clientRequestIdFromMeta({ client_request_id: "short" })).toBeNull();
+    expect(clientRequestIdFromMeta({ client_request_id: "dreq_bad space 0123456789" })).toBeNull();
+    expect(clientRequestIdFromMeta(null)).toBeNull();
+  });
+
+  test("same caller scope and request id derive the same task id", () => {
+    const a = idempotentTaskId("net_a", "admin", "dreq_0123456789abcdef");
+    expect(idempotentTaskId("net_a", "admin", "dreq_0123456789abcdef")).toBe(a);
+    expect(idempotentTaskId("net_b", "admin", "dreq_0123456789abcdef")).not.toBe(a);
+    expect(idempotentTaskId("net_a", "other", "dreq_0123456789abcdef")).not.toBe(a);
+    expect(a).toMatch(/^idem_[0-9a-f]{40}$/);
+  });
+
+  test("replay accepts semantically identical metadata regardless of key order", () => {
+    const row: StoredIdempotentTask = {
+      task_id: "idem_x", from_name: "admin", to_name: "worker", priority: "normal",
+      content: "hello", network_id: "net_a", status: "delivered",
+      meta_json: JSON.stringify({ client_request_id: "dreq_0123456789abcdef", attachments: [{ name: "a", file_id: "f1" }] }),
+    };
+    expect(idempotentTaskMatches(row, {
+      fromName: "admin", toName: "worker", priority: "normal", content: "hello", networkId: "net_a",
+      metaJson: JSON.stringify({ attachments: [{ file_id: "f1", name: "a" }], client_request_id: "dreq_0123456789abcdef" }),
+    })).toBe(true);
+  });
+
+  test("rolling upgrade ignores the new server-only auth stamp for replay equality", () => {
+    const row: StoredIdempotentTask = {
+      task_id: "idem_x", from_name: "admin", to_name: "worker", priority: "normal",
+      content: "hello", network_id: "net_a", status: "delivered",
+      meta_json: JSON.stringify({ client_request_id: "dreq_0123456789abcdef", source: "dashboard-chat" }),
+    };
+    expect(idempotentTaskMatches(row, {
+      fromName: "admin", toName: "worker", priority: "normal", content: "hello", networkId: "net_a",
+      metaJson: JSON.stringify({ client_request_id: "dreq_0123456789abcdef", source: "dashboard-chat", auth_origin: "user" }),
+    })).toBe(true);
+  });
+
+  test("same request id with changed payload is a conflict", () => {
+    const row: StoredIdempotentTask = {
+      task_id: "idem_x", from_name: "admin", to_name: "worker", priority: "normal",
+      content: "hello", network_id: "net_a", status: "delivered",
+      meta_json: JSON.stringify({ client_request_id: "dreq_0123456789abcdef" }),
+    };
+    expect(idempotentTaskMatches(row, {
+      fromName: "admin", toName: "worker", priority: "normal", content: "changed", networkId: "net_a",
+      metaJson: row.meta_json,
+    })).toBe(false);
+  });
+});

package/src/task-idempotency.ts

@@ -0,0 +1,75 @@
+import { createHash } from "crypto";
+
+const CLIENT_REQUEST_ID_RE = /^dreq_[A-Za-z0-9_-]{16,96}$/;
+
+export interface StoredIdempotentTask {
+  task_id: string;
+  from_name: string;
+  to_name: string;
+  priority: string;
+  content: string;
+  network_id: string | null;
+  meta_json: string | null;
+  status: string;
+}
+
+export interface ExpectedIdempotentTask {
+  fromName: string;
+  toName: string;
+  priority: string;
+  content: string;
+  networkId: string | null;
+  metaJson: string | null;
+}
+
+export function clientRequestIdFromMeta(meta: unknown): string | null {
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) return null;
+  const value = (meta as Record<string, unknown>).client_request_id;
+  return typeof value === "string" && CLIENT_REQUEST_ID_RE.test(value) ? value : null;
+}
+
+export function idempotentTaskId(networkId: string | null, fromName: string, requestId: string): string {
+  const digest = createHash("sha256")
+    .update(networkId ?? "<legacy-global>")
+    .update("\0")
+    .update(fromName)
+    .update("\0")
+    .update(requestId)
+    .digest("hex");
+  return `idem_${digest.slice(0, 40)}`;
+}
+
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+function parsedMeta(value: string | null): unknown {
+  if (!value) return null;
+  try { return JSON.parse(value); } catch { return value; }
+}
+
+function logicalRequestMeta(value: string | null): unknown {
+  const parsed = parsedMeta(value);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return parsed;
+  // auth_origin is a Hub-derived audit fact, not part of the client request.
+  // Ignore it for replay equality so a request first accepted by the old Hub
+  // (without the stamp) remains idempotent across a rolling upgrade.
+  const { auth_origin: _authOrigin, ...logical } = parsed as Record<string, unknown>;
+  return logical;
+}
+
+export function idempotentTaskMatches(row: StoredIdempotentTask, expected: ExpectedIdempotentTask): boolean {
+  return row.from_name === expected.fromName
+    && row.to_name === expected.toName
+    && row.priority === expected.priority
+    && row.content === expected.content
+    && (row.network_id ?? null) === (expected.networkId ?? null)
+    && canonicalJson(logicalRequestMeta(row.meta_json)) === canonicalJson(logicalRequestMeta(expected.metaJson));
+}