Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat(shared): add diagnostic report state

Gus4d4fccebd3be
diff --git a/src/shared/src/db/community-machine-schema.ts b/src/shared/src/db/community-machine-schema.ts
index aa3403df3..f60049452 100644
--- a/src/shared/src/db/community-machine-schema.ts
+++ b/src/shared/src/db/community-machine-schema.ts
@@ -1,9 +1,142 @@
-import { sqliteTable, text, index, uniqueIndex } from "drizzle-orm/sqlite-core";
+import { check, index, integer, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
import { sql } from "drizzle-orm";
import { nanoid } from "nanoid";
import { user } from "./schema";
import type { CommunityMachineRuntime } from "../community-ws-events";
+export const DIAGNOSTIC_REPORT_FAILURE_CODES = [
+ "offline",
+ "timeout",
+ "upload_conflict",
+ "invalid_upload",
+ "diagnostics_unavailable",
+ "collector_busy",
+ "bot_not_bound",
+ "collection_failed",
+ "local_artifact_invalid",
+ "bundle_too_large",
+ "upload_failed",
+ "internal_error",
+] as const;
+
+export type DiagnosticReportFailureCode =
+ (typeof DIAGNOSTIC_REPORT_FAILURE_CODES)[number];
+
+export type DiagnosticReportStatus = "pending" | "uploaded" | "failed";
+
+// community_diagnostic_report — immutable authorization and collection
+// snapshot for one owner-requested diagnostic bundle. Deliberately has no
+// foreign keys: bot soft-delete, unbind, and machine deletion must not erase
+// or pin the audit/status record after the atomic create snapshot is taken.
+export const communityDiagnosticReport = sqliteTable(
+ "community_diagnostic_report",
+ {
+ id: text("id")
+ .primaryKey()
+ .$defaultFn(() => "dbr_" + nanoid()),
+ ownerUserId: text("owner_user_id").notNull(),
+ agentId: text("agent_id").notNull(),
+ machineId: text("machine_id").notNull(),
+ clientNonce: text("client_nonce").notNull(),
+ rateBucket: integer("rate_bucket").notNull(),
+ status: text("status").$type<DiagnosticReportStatus>().notNull().default("pending"),
+ failureCode: text("failure_code").$type<DiagnosticReportFailureCode>(),
+ fromMs: integer("from_ms").notNull(),
+ createdAt: integer("created_at").notNull(),
+ deadlineAt: integer("deadline_at").notNull(),
+ completedAt: integer("completed_at"),
+ r2Key: text("r2_key"),
+ sha256: text("sha256"),
+ sizeBytes: integer("size_bytes"),
+ uploadedAt: integer("uploaded_at"),
+ objectExpiresAt: integer("object_expires_at"),
+ },
+ (t) => [
+ index("idx_community_diagnostic_report_owner_created").on(
+ t.ownerUserId,
+ t.createdAt
+ ),
+ index("idx_community_diagnostic_report_machine_status_deadline").on(
+ t.machineId,
+ t.status,
+ t.deadlineAt
+ ),
+ uniqueIndex("uq_community_diagnostic_report_owner_nonce").on(
+ t.ownerUserId,
+ t.clientNonce
+ ),
+ uniqueIndex("uq_community_diagnostic_report_owner_agent_pending")
+ .on(t.ownerUserId, t.agentId)
+ .where(sql`status = 'pending'`),
+ uniqueIndex("uq_community_diagnostic_report_owner_rate_bucket").on(
+ t.ownerUserId,
+ t.rateBucket
+ ),
+ check(
+ "ck_community_diagnostic_report_id",
+ sql`length(${t.id}) > 4 AND substr(${t.id}, 1, 4) = 'dbr_' AND ${t.id} NOT GLOB '*[^A-Za-z0-9_-]*'`
+ ),
+ check(
+ "ck_community_diagnostic_report_nonce",
+ sql`length(${t.clientNonce}) BETWEEN 16 AND 64 AND ${t.clientNonce} NOT GLOB '*[^A-Za-z0-9_-]*'`
+ ),
+ check(
+ "ck_community_diagnostic_report_required_epochs",
+ sql`typeof(${t.fromMs}) = 'integer' AND ${t.fromMs} BETWEEN 0 AND 9007199254740991
+ AND typeof(${t.createdAt}) = 'integer' AND ${t.createdAt} BETWEEN 0 AND 9007199254740991
+ AND typeof(${t.deadlineAt}) = 'integer' AND ${t.deadlineAt} BETWEEN 0 AND 9007199254740991
+ AND ${t.fromMs} = ${t.createdAt} - 86400000
+ AND ${t.deadlineAt} = ${t.createdAt} + 600000`
+ ),
+ check(
+ "ck_community_diagnostic_report_rate_bucket",
+ sql`typeof(${t.rateBucket}) = 'integer'
+ AND ${t.rateBucket} BETWEEN 0 AND 9007199254740991
+ AND ${t.rateBucket} = CAST(${t.createdAt} / 60000 AS INTEGER)`
+ ),
+ check(
+ "ck_community_diagnostic_report_nullable_epochs",
+ sql`(${t.completedAt} IS NULL OR (typeof(${t.completedAt}) = 'integer' AND ${t.completedAt} BETWEEN 0 AND 9007199254740991))
+ AND (${t.uploadedAt} IS NULL OR (typeof(${t.uploadedAt}) = 'integer' AND ${t.uploadedAt} BETWEEN 0 AND 9007199254740991))
+ AND (${t.objectExpiresAt} IS NULL OR (typeof(${t.objectExpiresAt}) = 'integer' AND ${t.objectExpiresAt} BETWEEN 0 AND 9007199254740991))`
+ ),
+ check(
+ "ck_community_diagnostic_report_size",
+ sql`${t.sizeBytes} IS NULL OR (typeof(${t.sizeBytes}) = 'integer' AND ${t.sizeBytes} BETWEEN 1 AND 10485760)`
+ ),
+ check(
+ "ck_community_diagnostic_report_sha256",
+ sql`${t.sha256} IS NULL OR (length(${t.sha256}) = 64 AND ${t.sha256} NOT GLOB '*[^0-9a-f]*')`
+ ),
+ check(
+ "ck_community_diagnostic_report_state",
+ sql`(
+ ${t.status} = 'pending'
+ AND ${t.failureCode} IS NULL AND ${t.completedAt} IS NULL
+ AND ${t.r2Key} IS NULL AND ${t.sha256} IS NULL AND ${t.sizeBytes} IS NULL
+ AND ${t.uploadedAt} IS NULL AND ${t.objectExpiresAt} IS NULL
+ ) OR (
+ ${t.status} = 'failed'
+ AND ${t.failureCode} IN ('offline', 'timeout', 'upload_conflict', 'invalid_upload', 'diagnostics_unavailable', 'collector_busy', 'bot_not_bound', 'collection_failed', 'local_artifact_invalid', 'bundle_too_large', 'upload_failed', 'internal_error')
+ AND ${t.completedAt} IS NOT NULL
+ AND ${t.completedAt} >= ${t.createdAt}
+ AND ${t.r2Key} IS NULL AND ${t.sha256} IS NULL AND ${t.sizeBytes} IS NULL
+ AND ${t.uploadedAt} IS NULL AND ${t.objectExpiresAt} IS NULL
+ ) OR (
+ ${t.status} = 'uploaded'
+ AND ${t.failureCode} IS NULL AND ${t.completedAt} IS NOT NULL
+ AND ${t.completedAt} >= ${t.createdAt}
+ AND ${t.r2Key} IS NOT NULL
+ AND ${t.r2Key} = 'bug-reports/' || ${t.ownerUserId} || '/' || ${t.id} || '.ndjson.gz'
+ AND ${t.sha256} IS NOT NULL AND ${t.sizeBytes} IS NOT NULL
+ AND ${t.uploadedAt} IS NOT NULL AND ${t.objectExpiresAt} IS NOT NULL
+ AND ${t.completedAt} = ${t.uploadedAt}
+ AND ${t.objectExpiresAt} = ${t.uploadedAt} + 604800000
+ )`
+ ),
+ ]
+);
+
// community_machine_token — pairing tokens. The id IS the user-visible
// token string (cmt_<nanoid(32)>). machine_id is set on reconnect tokens
// so /activate can look up the existing machine row instead of creating
diff --git a/src/shared/src/db/queries-index.ts b/src/shared/src/db/queries-index.ts
index d38eea306..0293571b3 100644
--- a/src/shared/src/db/queries-index.ts
+++ b/src/shared/src/db/queries-index.ts
@@ -56,3 +56,4 @@ export * as communityBot from "./queries/community/bot";
export * as communityAgentInbox from "./queries/community/agent-inbox";
export * as communityBotAuditLog from "./queries/community/bot-audit-log";
export * as communityMessageTag from "./queries/community/message-tag";
+export * as communityDiagnosticReport from "./queries/community/diagnostic-report";
diff --git a/src/shared/src/db/queries/community/diagnostic-report.ts b/src/shared/src/db/queries/community/diagnostic-report.ts
new file mode 100644
index 000000000..0b1c8d662
--- /dev/null
+++ b/src/shared/src/db/queries/community/diagnostic-report.ts
@@ -0,0 +1,418 @@
+import { and, eq, gt, isNull, lte, sql } from "drizzle-orm";
+import { alias } from "drizzle-orm/sqlite-core";
+import { nanoid } from "nanoid";
+import {
+ communityBotBinding,
+ communityDiagnosticReport,
+ type DiagnosticReportFailureCode,
+} from "../../community-machine-schema";
+import { user } from "../../schema";
+import type { Database } from "../../index";
+
+const COLLECTION_WINDOW_MS = 86_400_000;
+const DEADLINE_WINDOW_MS = 600_000;
+const OBJECT_RETENTION_MS = 604_800_000;
+const diagnosticOwner = alias(user, "diagnostic_owner");
+
+export type DiagnosticReportRow = typeof communityDiagnosticReport.$inferSelect;
+
+export class DiagnosticReportTargetUnavailableError extends Error {
+ readonly code = "DIAGNOSTIC_TARGET_UNAVAILABLE" as const;
+
+ constructor() {
+ super("diagnostic report target is unavailable");
+ this.name = "DiagnosticReportTargetUnavailableError";
+ }
+}
+
+type CreateDiagnosticReportInput = {
+ ownerUserId: string;
+ agentId: string;
+ clientNonce: string;
+ nowMs: number;
+};
+
+export type CreateDiagnosticReportResult =
+ | { kind: "created"; report: DiagnosticReportRow }
+ | { kind: "same_nonce"; report: DiagnosticReportRow }
+ | { kind: "existing_pending"; report: DiagnosticReportRow }
+ | { kind: "rate_limited"; report: DiagnosticReportRow };
+
+type ConflictClassification = CreateDiagnosticReportResult | null;
+
+function assertSafeEpoch(value: number): void {
+ if (!Number.isSafeInteger(value) || value < 0) {
+ throw new RangeError("nowMs must be a non-negative safe integer");
+ }
+}
+
+/**
+ * Atomically snapshots owner, live bot, and binding into a pending report.
+ * Constants are bound by Drizzle; machine_id comes only from the joined live
+ * binding inside this INSERT statement, never from caller-controlled data.
+ */
+async function tryInsertPendingDiagnosticReport(
+ db: Database,
+ input: CreateDiagnosticReportInput,
+ reportId: string
+): Promise<DiagnosticReportRow | null> {
+ const fromMs = input.nowMs - COLLECTION_WINDOW_MS;
+ const deadlineAt = input.nowMs + DEADLINE_WINDOW_MS;
+ const rateBucket = Math.floor(input.nowMs / 60_000);
+
+ const liveTarget = db
+ .select({
+ id: sql<string>`${reportId}`.as("id"),
+ ownerUserId: diagnosticOwner.id,
+ agentId: user.id,
+ machineId: communityBotBinding.machineId,
+ clientNonce: sql<string>`${input.clientNonce}`.as("client_nonce"),
+ rateBucket: sql<number>`${rateBucket}`.as("rate_bucket"),
+ status: sql<"pending">`'pending'`.as("status"),
+ failureCode: sql<null>`NULL`.as("failure_code"),
+ fromMs: sql<number>`${fromMs}`.as("from_ms"),
+ createdAt: sql<number>`${input.nowMs}`.as("created_at"),
+ deadlineAt: sql<number>`${deadlineAt}`.as("deadline_at"),
+ completedAt: sql<null>`NULL`.as("completed_at"),
+ r2Key: sql<null>`NULL`.as("r2_key"),
+ sha256: sql<null>`NULL`.as("sha256"),
+ sizeBytes: sql<null>`NULL`.as("size_bytes"),
+ uploadedAt: sql<null>`NULL`.as("uploaded_at"),
+ objectExpiresAt: sql<null>`NULL`.as("object_expires_at"),
+ })
+ .from(user)
+ .innerJoin(communityBotBinding, eq(communityBotBinding.userId, user.id))
+ .innerJoin(diagnosticOwner, eq(diagnosticOwner.id, user.ownerUserId))
+ .where(
+ and(
+ eq(user.id, input.agentId),
+ eq(user.ownerUserId, input.ownerUserId),
+ eq(user.isBot, true),
+ isNull(user.deletedAt),
+ isNull(diagnosticOwner.deletedAt)
+ )
+ );
+
+ const rows = await db
+ .insert(communityDiagnosticReport)
+ .select(liveTarget)
+ .onConflictDoNothing()
+ .returning();
+
+ return rows[0] ?? null;
+}
+
+async function firstReport(
+ query: PromiseLike<DiagnosticReportRow[]>
+): Promise<DiagnosticReportRow | null> {
+ const rows = await query;
+ return rows[0] ?? null;
+}
+
+async function classifyCreateConflict(
+ db: Database,
+ input: CreateDiagnosticReportInput
+): Promise<ConflictClassification> {
+ const sameNonce = await firstReport(
+ db
+ .select()
+ .from(communityDiagnosticReport)
+ .where(
+ and(
+ eq(communityDiagnosticReport.ownerUserId, input.ownerUserId),
+ eq(communityDiagnosticReport.clientNonce, input.clientNonce)
+ )
+ )
+ .limit(1)
+ );
+ if (sameNonce) {
+ if (sameNonce.status === "pending" && sameNonce.deadlineAt <= input.nowMs) {
+ const timedOut = await timeoutPendingDiagnosticReport(db, {
+ reportId: sameNonce.id,
+ ownerUserId: input.ownerUserId,
+ nowMs: input.nowMs,
+ });
+ if (timedOut) return { kind: "same_nonce", report: timedOut };
+
+ // A concurrent terminal writer may have beaten the timeout CAS. Preserve
+ // the nonce's authoritative identity instead of creating a replacement.
+ const winner = await firstReport(
+ db
+ .select()
+ .from(communityDiagnosticReport)
+ .where(
+ and(
+ eq(communityDiagnosticReport.ownerUserId, input.ownerUserId),
+ eq(communityDiagnosticReport.clientNonce, input.clientNonce)
+ )
+ )
+ .limit(1)
+ );
+ if (winner) return { kind: "same_nonce", report: winner };
+ } else {
+ return { kind: "same_nonce", report: sameNonce };
+ }
+ }
+
+ const existingPending = await firstReport(
+ db
+ .select()
+ .from(communityDiagnosticReport)
+ .where(
+ and(
+ eq(communityDiagnosticReport.ownerUserId, input.ownerUserId),
+ eq(communityDiagnosticReport.agentId, input.agentId),
+ eq(communityDiagnosticReport.status, "pending")
+ )
+ )
+ .limit(1)
+ );
+ if (existingPending) {
+ if (existingPending.deadlineAt > input.nowMs) {
+ return { kind: "existing_pending", report: existingPending };
+ }
+ const timedOut = await timeoutPendingDiagnosticReport(db, {
+ reportId: existingPending.id,
+ ownerUserId: input.ownerUserId,
+ nowMs: input.nowMs,
+ });
+ if (!timedOut) {
+ const winner = await firstReport(
+ db
+ .select()
+ .from(communityDiagnosticReport)
+ .where(
+ and(
+ eq(communityDiagnosticReport.id, existingPending.id),
+ eq(communityDiagnosticReport.ownerUserId, input.ownerUserId)
+ )
+ )
+ .limit(1)
+ );
+ if (winner?.status === "pending") {
+ return { kind: "existing_pending", report: winner };
+ }
+ }
+ }
+
+ const rateLimited = await firstReport(
+ db
+ .select()
+ .from(communityDiagnosticReport)
+ .where(
+ and(
+ eq(communityDiagnosticReport.ownerUserId, input.ownerUserId),
+ eq(communityDiagnosticReport.rateBucket, Math.floor(input.nowMs / 60_000))
+ )
+ )
+ .limit(1)
+ );
+ return rateLimited ? { kind: "rate_limited", report: rateLimited } : null;
+}
+
+export async function createOrGetPendingDiagnosticReport(
+ db: Database,
+ input: CreateDiagnosticReportInput
+): Promise<CreateDiagnosticReportResult> {
+ assertSafeEpoch(input.nowMs);
+ if (input.nowMs < COLLECTION_WINDOW_MS) {
+ throw new RangeError("nowMs is too early for the diagnostic collection window");
+ }
+ if (!Number.isSafeInteger(input.nowMs + DEADLINE_WINDOW_MS)) {
+ throw new RangeError("diagnostic deadline exceeds the safe integer range");
+ }
+
+ const reportId = `dbr_${nanoid()}`;
+ const inserted = await tryInsertPendingDiagnosticReport(db, input, reportId);
+ if (inserted) return { kind: "created", report: inserted };
+
+ const conflict = await classifyCreateConflict(db, input);
+ if (conflict) return conflict;
+
+ // A pending conflict winner may terminalize between the failed insert and
+ // classification. Retry exactly once; a second zero-row result fails closed
+ // because the live bot/binding snapshot may also have disappeared.
+ const retried = await tryInsertPendingDiagnosticReport(db, input, reportId);
+ if (retried) return { kind: "created", report: retried };
+ const retryConflict = await classifyCreateConflict(db, input);
+ if (retryConflict) return retryConflict;
+ throw new DiagnosticReportTargetUnavailableError();
+}
+
+export async function getDiagnosticReportForOwner(
+ db: Database,
+ input: { reportId: string; ownerUserId: string }
+): Promise<DiagnosticReportRow | null> {
+ return firstReport(
+ db
+ .select()
+ .from(communityDiagnosticReport)
+ .where(
+ and(
+ eq(communityDiagnosticReport.id, input.reportId),
+ eq(communityDiagnosticReport.ownerUserId, input.ownerUserId)
+ )
+ )
+ .limit(1)
+ );
+}
+
+export async function getPendingDiagnosticReportForMachine(
+ db: Database,
+ input: { reportId: string; machineId: string; nowMs: number }
+): Promise<DiagnosticReportRow | null> {
+ assertSafeEpoch(input.nowMs);
+ return firstReport(
+ db
+ .select()
+ .from(communityDiagnosticReport)
+ .where(
+ and(
+ eq(communityDiagnosticReport.id, input.reportId),
+ eq(communityDiagnosticReport.machineId, input.machineId),
+ eq(communityDiagnosticReport.status, "pending"),
+ gt(communityDiagnosticReport.deadlineAt, input.nowMs)
+ )
+ )
+ .limit(1)
+ );
+}
+
+export async function getDiagnosticReportForMachine(
+ db: Database,
+ input: { reportId: string; machineId: string }
+): Promise<DiagnosticReportRow | null> {
+ return firstReport(
+ db
+ .select()
+ .from(communityDiagnosticReport)
+ .where(
+ and(
+ eq(communityDiagnosticReport.id, input.reportId),
+ eq(communityDiagnosticReport.machineId, input.machineId)
+ )
+ )
+ .limit(1)
+ );
+}
+
+export async function timeoutPendingDiagnosticReport(
+ db: Database,
+ input: { reportId: string; ownerUserId: string; nowMs: number }
+): Promise<DiagnosticReportRow | null> {
+ assertSafeEpoch(input.nowMs);
+ const rows = await db
+ .update(communityDiagnosticReport)
+ .set({ status: "failed", failureCode: "timeout", completedAt: input.nowMs })
+ .where(
+ and(
+ eq(communityDiagnosticReport.id, input.reportId),
+ eq(communityDiagnosticReport.ownerUserId, input.ownerUserId),
+ eq(communityDiagnosticReport.status, "pending"),
+ lte(communityDiagnosticReport.deadlineAt, input.nowMs)
+ )
+ )
+ .returning();
+ return rows[0] ?? null;
+}
+
+export async function failPendingDiagnosticReport(
+ db: Database,
+ input: {
+ reportId: string;
+ machineId: string;
+ failureCode: DiagnosticReportFailureCode;
+ nowMs: number;
+ }
+): Promise<DiagnosticReportRow | null> {
+ assertSafeEpoch(input.nowMs);
+ const rows = await db
+ .update(communityDiagnosticReport)
+ .set({
+ status: "failed",
+ failureCode: input.failureCode,
+ completedAt: input.nowMs,
+ })
+ .where(
+ and(
+ eq(communityDiagnosticReport.id, input.reportId),
+ eq(communityDiagnosticReport.machineId, input.machineId),
+ eq(communityDiagnosticReport.status, "pending"),
+ gt(communityDiagnosticReport.deadlineAt, input.nowMs)
+ )
+ )
+ .returning();
+ return rows[0] ?? null;
+}
+
+export async function finalizeDiagnosticReportUpload(
+ db: Database,
+ input: {
+ reportId: string;
+ machineId: string;
+ r2Key: string;
+ sha256: string;
+ sizeBytes: number;
+ nowMs: number;
+ }
+): Promise<DiagnosticReportRow | null> {
+ assertSafeEpoch(input.nowMs);
+ if (!Number.isSafeInteger(input.nowMs + OBJECT_RETENTION_MS)) {
+ throw new RangeError("diagnostic object expiry exceeds the safe integer range");
+ }
+ const rows = await db
+ .update(communityDiagnosticReport)
+ .set({
+ status: "uploaded",
+ failureCode: null,
+ completedAt: input.nowMs,
+ r2Key: input.r2Key,
+ sha256: input.sha256,
+ sizeBytes: input.sizeBytes,
+ uploadedAt: input.nowMs,
+ objectExpiresAt: input.nowMs + OBJECT_RETENTION_MS,
+ })
+ .where(
+ and(
+ eq(communityDiagnosticReport.id, input.reportId),
+ eq(communityDiagnosticReport.machineId, input.machineId),
+ eq(communityDiagnosticReport.status, "pending"),
+ gt(communityDiagnosticReport.deadlineAt, input.nowMs)
+ )
+ )
+ .returning();
+ return rows[0] ?? null;
+}
+
+type ExpectedTerminal =
+ | { status: "uploaded"; r2Key: string; sha256: string; sizeBytes: number }
+ | { status: "failed"; failureCode: DiagnosticReportFailureCode };
+
+export function classifyDiagnosticReportTerminal(
+ report: Pick<
+ DiagnosticReportRow,
+ "status" | "failureCode" | "r2Key" | "sha256" | "sizeBytes"
+ >,
+ expected: ExpectedTerminal
+):
+ | { kind: "pending" }
+ | { kind: "uploaded_same" }
+ | { kind: "uploaded_different" }
+ | { kind: "failed_same" }
+ | { kind: "failed_different" } {
+ if (report.status === "pending") return { kind: "pending" };
+ if (report.status === "failed") {
+ return expected.status === "failed" && report.failureCode === expected.failureCode
+ ? { kind: "failed_same" }
+ : { kind: "failed_different" };
+ }
+ if (
+ expected.status === "uploaded" &&
+ report.r2Key === expected.r2Key &&
+ report.sha256 === expected.sha256 &&
+ report.sizeBytes === expected.sizeBytes
+ ) {
+ return { kind: "uploaded_same" };
+ }
+ return { kind: "uploaded_different" };
+}
diff --git a/src/shared/test/queries/community-diagnostic-report.test.ts b/src/shared/test/queries/community-diagnostic-report.test.ts
new file mode 100644
index 000000000..3a597859e
--- /dev/null
+++ b/src/shared/test/queries/community-diagnostic-report.test.ts
@@ -0,0 +1,635 @@
+import { describe, expect, it, vi } from "vitest";
+import Sqlite from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { getTableConfig } from "drizzle-orm/sqlite-core";
+import type { Database } from "../../src/db";
+import {
+ DIAGNOSTIC_REPORT_FAILURE_CODES,
+ communityDiagnosticReport,
+ type DiagnosticReportFailureCode,
+} from "../../src/db/community-machine-schema";
+import * as q from "../../src/db/queries/community/diagnostic-report";
+
+const NOW_MS = 1_786_531_200_000;
+const FROM_MS = NOW_MS - 86_400_000;
+const DEADLINE_AT = NOW_MS + 600_000;
+const OWNER_ID = "owner_1";
+const AGENT_ID = "agent_1";
+const MACHINE_ID = "cm_machine_1";
+const REPORT_ID = "dbr_report_1";
+const NONCE = "nonce_1234567890abcdef";
+
+const pendingRow = {
+ id: REPORT_ID,
+ ownerUserId: OWNER_ID,
+ agentId: AGENT_ID,
+ machineId: MACHINE_ID,
+ clientNonce: NONCE,
+ rateBucket: Math.floor(NOW_MS / 60_000),
+ status: "pending" as const,
+ failureCode: null,
+ fromMs: FROM_MS,
+ createdAt: NOW_MS,
+ deadlineAt: DEADLINE_AT,
+ completedAt: null,
+ r2Key: null,
+ sha256: null,
+ sizeBytes: null,
+ uploadedAt: null,
+ objectExpiresAt: null,
+};
+
+function scriptedDb(steps: Array<{ method: string; rows: unknown[] }>) {
+ const calls: Array<{ method: string; args: unknown[] }> = [];
+ const db: Record<string, ReturnType<typeof vi.fn>> = {};
+ const chain: Record<string, ReturnType<typeof vi.fn>> = {};
+ const terminal = (method: string, args: unknown[]) => {
+ calls.push({ method, args });
+ const step = steps.shift();
+ if (!step || step.method !== method) {
+ throw new Error(`unexpected terminal ${method}; expected ${step?.method ?? "none"}`);
+ }
+ return Promise.resolve(step.rows);
+ };
+ for (const method of ["select", "from", "innerJoin", "leftJoin", "where", "limit", "insert", "values", "onConflictDoNothing", "update", "set"] as const) {
+ chain[method] = vi.fn((...args: unknown[]) => {
+ calls.push({ method, args });
+ return chain;
+ });
+ }
+ chain.returning = vi.fn((...args: unknown[]) => terminal("returning", args));
+ db.select = chain.select;
+ db.insert = chain.insert;
+ db.update = chain.update;
+ return { db, chain, calls, remaining: steps };
+}
+
+function queryDb(resultRows: unknown[][]) {
+ const calls: Array<{ method: string; args: unknown[] }> = [];
+ const chain: Record<string, ReturnType<typeof vi.fn>> & {
+ then?: (resolve: (rows: unknown[]) => unknown, reject: (error: unknown) => unknown) => unknown;
+ } = {};
+ for (const method of [
+ "select",
+ "from",
+ "innerJoin",
+ "leftJoin",
+ "where",
+ "limit",
+ "insert",
+ "values",
+ "onConflictDoNothing",
+ "returning",
+ "update",
+ "set",
+ ] as const) {
+ chain[method] = vi.fn((...args: unknown[]) => {
+ calls.push({ method, args });
+ return chain;
+ });
+ }
+ chain.then = (resolve, reject) => {
+ try {
+ return Promise.resolve(resolve(resultRows.shift() ?? []));
+ } catch (error) {
+ return Promise.resolve(reject(error));
+ }
+ };
+ return {
+ db: { select: chain.select, insert: chain.insert, update: chain.update },
+ chain,
+ calls,
+ remaining: resultRows,
+ };
+}
+
+function realSnapshotDb(input: {
+ ownerDeleted?: boolean;
+ botDeleted?: boolean;
+ isBot?: boolean;
+ bound?: boolean;
+} = {}) {
+ const sqlite = new Sqlite(":memory:");
+ sqlite.exec(`
+ CREATE TABLE user (
+ id TEXT PRIMARY KEY NOT NULL,
+ ownerUserId TEXT,
+ isBot INTEGER NOT NULL,
+ deletedAt TEXT
+ );
+ CREATE TABLE community_bot_binding (
+ user_id TEXT PRIMARY KEY NOT NULL,
+ machine_id TEXT NOT NULL
+ );
+ CREATE TABLE community_diagnostic_report (
+ id TEXT PRIMARY KEY NOT NULL,
+ owner_user_id TEXT NOT NULL,
+ agent_id TEXT NOT NULL,
+ machine_id TEXT NOT NULL,
+ client_nonce TEXT NOT NULL,
+ rate_bucket INTEGER NOT NULL,
+ status TEXT NOT NULL,
+ failure_code TEXT,
+ from_ms INTEGER NOT NULL,
+ created_at INTEGER NOT NULL,
+ deadline_at INTEGER NOT NULL,
+ completed_at INTEGER,
+ r2_key TEXT,
+ sha256 TEXT,
+ size_bytes INTEGER,
+ uploaded_at INTEGER,
+ object_expires_at INTEGER
+ );
+ CREATE UNIQUE INDEX uq_snapshot_owner_nonce
+ ON community_diagnostic_report(owner_user_id, client_nonce);
+ CREATE UNIQUE INDEX uq_snapshot_owner_pending
+ ON community_diagnostic_report(owner_user_id, agent_id)
+ WHERE status = 'pending';
+ CREATE UNIQUE INDEX uq_snapshot_owner_rate
+ ON community_diagnostic_report(owner_user_id, rate_bucket);
+ `);
+ sqlite
+ .prepare(`INSERT INTO user (id, ownerUserId, isBot, deletedAt) VALUES (?, ?, ?, ?)`)
+ .run(OWNER_ID, null, 0, input.ownerDeleted ? "deleted" : null);
+ sqlite
+ .prepare(`INSERT INTO user (id, ownerUserId, isBot, deletedAt) VALUES (?, ?, ?, ?)`)
+ .run(AGENT_ID, OWNER_ID, input.isBot === false ? 0 : 1, input.botDeleted ? "deleted" : null);
+ if (input.bound !== false) {
+ sqlite
+ .prepare(`INSERT INTO community_bot_binding (user_id, machine_id) VALUES (?, ?)`)
+ .run(AGENT_ID, MACHINE_ID);
+ }
+ return {
+ sqlite,
+ db: drizzle(sqlite) as unknown as Database,
+ };
+}
+
+describe("diagnostic report query contract", () => {
+ it("keeps the Drizzle columns and indexes in exact migration parity", () => {
+ const config = getTableConfig(communityDiagnosticReport);
+ expect(
+ config.columns.map((column) => ({
+ name: column.name,
+ type: column.getSQLType().toUpperCase(),
+ notNull: column.notNull,
+ primaryKey: column.primary,
+ })),
+ ).toEqual([
+ { name: "id", type: "TEXT", notNull: true, primaryKey: true },
+ { name: "owner_user_id", type: "TEXT", notNull: true, primaryKey: false },
+ { name: "agent_id", type: "TEXT", notNull: true, primaryKey: false },
+ { name: "machine_id", type: "TEXT", notNull: true, primaryKey: false },
+ { name: "client_nonce", type: "TEXT", notNull: true, primaryKey: false },
+ { name: "rate_bucket", type: "INTEGER", notNull: true, primaryKey: false },
+ { name: "status", type: "TEXT", notNull: true, primaryKey: false },
+ { name: "failure_code", type: "TEXT", notNull: false, primaryKey: false },
+ { name: "from_ms", type: "INTEGER", notNull: true, primaryKey: false },
+ { name: "created_at", type: "INTEGER", notNull: true, primaryKey: false },
+ { name: "deadline_at", type: "INTEGER", notNull: true, primaryKey: false },
+ { name: "completed_at", type: "INTEGER", notNull: false, primaryKey: false },
+ { name: "r2_key", type: "TEXT", notNull: false, primaryKey: false },
+ { name: "sha256", type: "TEXT", notNull: false, primaryKey: false },
+ { name: "size_bytes", type: "INTEGER", notNull: false, primaryKey: false },
+ { name: "uploaded_at", type: "INTEGER", notNull: false, primaryKey: false },
+ { name: "object_expires_at", type: "INTEGER", notNull: false, primaryKey: false },
+ ]);
+ expect(
+ config.indexes
+ .map((entry) => ({
+ name: entry.config.name,
+ columns: entry.config.columns.map((column) => column.name),
+ unique: entry.config.unique,
+ partial: entry.config.where !== undefined,
+ }))
+ .sort((left, right) => left.name.localeCompare(right.name)),
+ ).toEqual([
+ {
+ name: "idx_community_diagnostic_report_machine_status_deadline",
+ columns: ["machine_id", "status", "deadline_at"],
+ unique: false,
+ partial: false,
+ },
+ {
+ name: "idx_community_diagnostic_report_owner_created",
+ columns: ["owner_user_id", "created_at"],
+ unique: false,
+ partial: false,
+ },
+ {
+ name: "uq_community_diagnostic_report_owner_agent_pending",
+ columns: ["owner_user_id", "agent_id"],
+ unique: true,
+ partial: true,
+ },
+ {
+ name: "uq_community_diagnostic_report_owner_nonce",
+ columns: ["owner_user_id", "client_nonce"],
+ unique: true,
+ partial: false,
+ },
+ {
+ name: "uq_community_diagnostic_report_owner_rate_bucket",
+ columns: ["owner_user_id", "rate_bucket"],
+ unique: true,
+ partial: false,
+ },
+ ]);
+ expect(config.foreignKeys).toEqual([]);
+ });
+
+ it("exports the one failure-code source and the complete fixed allowlist", () => {
+ expect(DIAGNOSTIC_REPORT_FAILURE_CODES).toEqual([
+ "offline",
+ "timeout",
+ "upload_conflict",
+ "invalid_upload",
+ "diagnostics_unavailable",
+ "collector_busy",
+ "bot_not_bound",
+ "collection_failed",
+ "local_artifact_invalid",
+ "bundle_too_large",
+ "upload_failed",
+ "internal_error",
+ ]);
+ expect(new Set(DIAGNOSTIC_REPORT_FAILURE_CODES).size).toBe(
+ DIAGNOSTIC_REPORT_FAILURE_CODES.length,
+ );
+ });
+
+ it("exports only the frozen B2a state-machine helpers", () => {
+ expect(typeof q.createOrGetPendingDiagnosticReport).toBe("function");
+ expect(typeof q.getDiagnosticReportForOwner).toBe("function");
+ expect(typeof q.getPendingDiagnosticReportForMachine).toBe("function");
+ expect(typeof q.getDiagnosticReportForMachine).toBe("function");
+ expect(typeof q.timeoutPendingDiagnosticReport).toBe("function");
+ expect(typeof q.failPendingDiagnosticReport).toBe("function");
+ expect(typeof q.finalizeDiagnosticReportUpload).toBe("function");
+ });
+
+ it("first create is one atomic INSERT…SELECT from the live owner/bot/binding snapshot", async () => {
+ const created = { ...pendingRow };
+ const { db, chain } = queryDb([[created]]);
+
+ const result = await q.createOrGetPendingDiagnosticReport(db, {
+ ownerUserId: OWNER_ID,
+ agentId: AGENT_ID,
+ clientNonce: NONCE,
+ nowMs: NOW_MS,
+ });
+
+ expect(result).toEqual({ kind: "created", report: created });
+ // `machineId` is deliberately absent from caller input. The insert must
+ // project owner/agent/machine from its live SQL snapshot, never from an
+ // earlier JS lookup that can race soft-delete/unbind.
+ expect(chain.values).not.toHaveBeenCalled();
+ expect(chain.select).toHaveBeenCalledTimes(2);
+ expect(chain.onConflictDoNothing).toHaveBeenCalledTimes(1);
+ });
+
+ it("executes the typed INSERT…SELECT against one live owner/bot/binding snapshot", async () => {
+ const { db, sqlite } = realSnapshotDb();
+ try {
+ const result = await q.createOrGetPendingDiagnosticReport(db, {
+ ownerUserId: OWNER_ID,
+ agentId: AGENT_ID,
+ clientNonce: NONCE,
+ nowMs: NOW_MS,
+ });
+ expect(result.kind).toBe("created");
+ expect(result.report).toMatchObject({
+ ownerUserId: OWNER_ID,
+ agentId: AGENT_ID,
+ machineId: MACHINE_ID,
+ });
+ expect(
+ sqlite.prepare(`SELECT COUNT(*) AS count FROM community_diagnostic_report`).get(),
+ ).toEqual({ count: 1 });
+ } finally {
+ sqlite.close();
+ }
+ });
+
+ it.each([
+ ["deleted owner", { ownerDeleted: true }, OWNER_ID],
+ ["wrong owner", {}, "owner_other"],
+ ["non-bot target", { isBot: false }, OWNER_ID],
+ ["deleted bot", { botDeleted: true }, OWNER_ID],
+ ["missing binding", { bound: false }, OWNER_ID],
+ ] as const)("atomically rejects %s without persisting a report", async (_name, setup, ownerUserId) => {
+ const { db, sqlite } = realSnapshotDb(setup);
+ try {
+ await expect(
+ q.createOrGetPendingDiagnosticReport(db, {
+ ownerUserId,
+ agentId: AGENT_ID,
+ clientNonce: NONCE,
+ nowMs: NOW_MS,
+ }),
+ ).rejects.toMatchObject({ code: "DIAGNOSTIC_TARGET_UNAVAILABLE" });
+ expect(
+ sqlite.prepare(`SELECT COUNT(*) AS count FROM community_diagnostic_report`).get(),
+ ).toEqual({ count: 0 });
+ } finally {
+ sqlite.close();
+ }
+ });
+
+ it.each([
+ ["same_nonce", { ...pendingRow }, [[], [{ ...pendingRow }]]],
+ [
+ "existing_pending",
+ { ...pendingRow, clientNonce: "nonce_other_123456" },
+ [[], [], [{ ...pendingRow, clientNonce: "nonce_other_123456" }]],
+ ],
+ [
+ "rate_limited",
+ { ...pendingRow, status: "failed", failureCode: "timeout", completedAt: NOW_MS },
+ [[], [], [], [{ ...pendingRow, status: "failed", failureCode: "timeout", completedAt: NOW_MS }]],
+ ],
+ ] as const)("returns authoritative %s row with its persisted fromMs", async (kind, row, rows) => {
+ const { db } = queryDb(rows.map((value) => [...value]));
+ const result = await q.createOrGetPendingDiagnosticReport(
+ db,
+ {
+ ownerUserId: OWNER_ID,
+ agentId: AGENT_ID,
+ clientNonce: NONCE,
+ nowMs: NOW_MS + 42_000,
+ },
+ );
+ expect(result).toEqual({ kind, report: row });
+ expect(result.report.fromMs).toBe(FROM_MS);
+ });
+
+ it("classifies a conflicted insert in nonce → pending → rate order and retries insert at most once when the pending winner terminalized", async () => {
+ const { db, chain, remaining } = queryDb([[], [], [], [], [pendingRow]]);
+
+ await expect(
+ q.createOrGetPendingDiagnosticReport(db, {
+ ownerUserId: OWNER_ID,
+ agentId: AGENT_ID,
+ clientNonce: NONCE,
+ nowMs: NOW_MS,
+ }),
+ ).resolves.toEqual({ kind: "created", report: pendingRow });
+ expect(chain.insert).toHaveBeenCalledTimes(2);
+ expect(chain.select).toHaveBeenCalledTimes(7);
+ expect(remaining).toEqual([]);
+ });
+
+ it("terminalizes a stale different-nonce pending row before retrying a replacement", async () => {
+ const stale = {
+ ...pendingRow,
+ clientNonce: "nonce_stale_other_1234",
+ deadlineAt: NOW_MS - 1,
+ };
+ const timedOut = {
+ ...stale,
+ status: "failed" as const,
+ failureCode: "timeout" as const,
+ completedAt: NOW_MS,
+ };
+ const replacement = { ...pendingRow, id: "dbr_replacement" };
+ const { db, chain, remaining } = queryDb([
+ [],
+ [],
+ [stale],
+ [timedOut],
+ [],
+ [replacement],
+ ]);
+
+ await expect(
+ q.createOrGetPendingDiagnosticReport(db, {
+ ownerUserId: OWNER_ID,
+ agentId: AGENT_ID,
+ clientNonce: NONCE,
+ nowMs: NOW_MS,
+ }),
+ ).resolves.toEqual({ kind: "created", report: replacement });
+ expect(chain.update).toHaveBeenCalledTimes(1);
+ expect(chain.insert).toHaveBeenCalledTimes(2);
+ expect(remaining).toEqual([]);
+ });
+
+ it("terminalizes a stale same-nonce row while preserving nonce identity", async () => {
+ const stale = { ...pendingRow, deadlineAt: NOW_MS - 1 };
+ const timedOut = {
+ ...stale,
+ status: "failed" as const,
+ failureCode: "timeout" as const,
+ completedAt: NOW_MS,
+ };
+ const { db, chain, remaining } = queryDb([[], [stale], [timedOut]]);
+
+ await expect(
+ q.createOrGetPendingDiagnosticReport(db, {
+ ownerUserId: OWNER_ID,
+ agentId: AGENT_ID,
+ clientNonce: NONCE,
+ nowMs: NOW_MS,
+ }),
+ ).resolves.toEqual({ kind: "same_nonce", report: timedOut });
+ expect(chain.update).toHaveBeenCalledTimes(1);
+ expect(chain.insert).toHaveBeenCalledTimes(1);
+ expect(remaining).toEqual([]);
+ });
+
+ it.each([
+ ["same_nonce", [[], [], [], [], [], [{ ...pendingRow }]]],
+ [
+ "existing_pending",
+ [[], [], [], [], [], [], [{ ...pendingRow, clientNonce: "nonce_race_other_1234" }]],
+ ],
+ [
+ "rate_limited",
+ [
+ [],
+ [],
+ [],
+ [],
+ [],
+ [],
+ [],
+ [{ ...pendingRow, status: "failed", failureCode: "timeout", completedAt: NOW_MS }],
+ ],
+ ],
+ ] as const)("reclassifies a second-insert %s race before failing closed", async (kind, rows) => {
+ const { db, chain, remaining } = queryDb(
+ rows.map((value) => [...value]),
+ );
+ await expect(
+ q.createOrGetPendingDiagnosticReport(db, {
+ ownerUserId: OWNER_ID,
+ agentId: AGENT_ID,
+ clientNonce: NONCE,
+ nowMs: NOW_MS,
+ }),
+ ).resolves.toMatchObject({ kind });
+ expect(chain.insert).toHaveBeenCalledTimes(2);
+ expect(remaining).toEqual([]);
+ });
+
+ it("fails closed when the atomic INSERT…SELECT observes owner/bot soft-delete or unbind", async () => {
+ const { db, chain } = queryDb([[], [], [], [], []]);
+
+ await expect(
+ q.createOrGetPendingDiagnosticReport(db, {
+ ownerUserId: OWNER_ID,
+ agentId: AGENT_ID,
+ clientNonce: NONCE,
+ nowMs: NOW_MS,
+ }),
+ ).rejects.toMatchObject({ code: "DIAGNOSTIC_TARGET_UNAVAILABLE" });
+ expect(chain.values).not.toHaveBeenCalled();
+ expect(chain.insert).toHaveBeenCalledTimes(2);
+ // Both attempts are atomic INSERT…SELECT snapshots. The caller never
+ // supplies machineId, so an unbound/deleted target cannot leave a row.
+ expect(chain.select).toHaveBeenCalled();
+ });
+
+ it("owner status is scoped only by immutable row owner", async () => {
+ const { db, chain } = queryDb([[pendingRow]]);
+ await expect(
+ q.getDiagnosticReportForOwner(db, { reportId: REPORT_ID, ownerUserId: OWNER_ID }),
+ ).resolves.toEqual(pendingRow);
+ expect(chain.select).toHaveBeenCalledTimes(1);
+ expect(chain.from).toHaveBeenCalledTimes(1);
+ expect(chain.where).toHaveBeenCalledTimes(1);
+ expect(chain.limit).toHaveBeenCalledWith(1);
+ expect(chain.innerJoin).not.toHaveBeenCalled();
+ });
+
+ it("machine authorization is the immutable report snapshot, not a live bot binding", async () => {
+ const { db, chain } = queryDb([[pendingRow]]);
+ await expect(
+ q.getPendingDiagnosticReportForMachine(db, {
+ reportId: REPORT_ID,
+ machineId: MACHINE_ID,
+ nowMs: NOW_MS,
+ }),
+ ).resolves.toEqual(pendingRow);
+ expect(chain.select).toHaveBeenCalledTimes(1);
+ expect(chain.from).toHaveBeenCalledTimes(1);
+ expect(chain.where).toHaveBeenCalledTimes(1);
+ expect(chain.limit).toHaveBeenCalledWith(1);
+ expect(chain.innerJoin).not.toHaveBeenCalled();
+ });
+
+ it("timeout is a guarded pending→failed CAS returning its winning row", async () => {
+ const failed = {
+ ...pendingRow,
+ status: "failed" as const,
+ failureCode: "timeout" as const,
+ completedAt: DEADLINE_AT,
+ };
+ const { db, chain } = scriptedDb([{ method: "returning", rows: [failed] }]);
+ await expect(
+ q.timeoutPendingDiagnosticReport(db, {
+ reportId: REPORT_ID,
+ ownerUserId: OWNER_ID,
+ nowMs: DEADLINE_AT,
+ }),
+ ).resolves.toEqual(failed);
+ expect(chain.set).toHaveBeenCalledWith({
+ status: "failed",
+ failureCode: "timeout",
+ completedAt: DEADLINE_AT,
+ });
+ });
+
+ it.each(DIAGNOSTIC_REPORT_FAILURE_CODES)(
+ "failure CAS accepts fixed code %s and returns null for a lost race",
+ async (failureCode) => {
+ const { db } = scriptedDb([{ method: "returning", rows: [] }]);
+ await expect(
+ q.failPendingDiagnosticReport(db, {
+ reportId: REPORT_ID,
+ machineId: MACHINE_ID,
+ failureCode: failureCode as DiagnosticReportFailureCode,
+ nowMs: NOW_MS,
+ }),
+ ).resolves.toBeNull();
+ },
+ );
+
+ it("finalize CAS derives exact object expiry and returns the uploaded row", async () => {
+ const uploaded = {
+ ...pendingRow,
+ status: "uploaded" as const,
+ completedAt: NOW_MS,
+ uploadedAt: NOW_MS,
+ objectExpiresAt: NOW_MS + 604_800_000,
+ r2Key: `bug-reports/${OWNER_ID}/${REPORT_ID}.ndjson.gz`,
+ sha256: "a".repeat(64),
+ sizeBytes: 1234,
+ };
+ const { db, chain } = scriptedDb([{ method: "returning", rows: [uploaded] }]);
+ await expect(
+ q.finalizeDiagnosticReportUpload(db, {
+ reportId: REPORT_ID,
+ machineId: MACHINE_ID,
+ r2Key: uploaded.r2Key,
+ sha256: uploaded.sha256,
+ sizeBytes: uploaded.sizeBytes,
+ nowMs: NOW_MS,
+ }),
+ ).resolves.toEqual(uploaded);
+ expect(chain.set).toHaveBeenCalledWith(
+ expect.objectContaining({
+ status: "uploaded",
+ completedAt: NOW_MS,
+ uploadedAt: NOW_MS,
+ objectExpiresAt: NOW_MS + 604_800_000,
+ }),
+ );
+ });
+
+ it("terminal readback retains enough metadata for same/different compensation", async () => {
+ const expected = {
+ r2Key: `bug-reports/${OWNER_ID}/${REPORT_ID}.ndjson.gz`,
+ sha256: "a".repeat(64),
+ sizeBytes: 1234,
+ };
+ const uploadExpected = { status: "uploaded" as const, ...expected };
+ expect(q.classifyDiagnosticReportTerminal({
+ ...pendingRow,
+ status: "uploaded",
+ ...expected,
+ }, uploadExpected)).toEqual({ kind: "uploaded_same" });
+ expect(q.classifyDiagnosticReportTerminal({
+ ...pendingRow,
+ status: "uploaded",
+ ...expected,
+ sha256: "b".repeat(64),
+ }, uploadExpected)).toEqual({ kind: "uploaded_different" });
+ expect(q.classifyDiagnosticReportTerminal({
+ ...pendingRow,
+ status: "failed",
+ failureCode: "upload_conflict",
+ }, { status: "failed", failureCode: "upload_conflict" })).toEqual({ kind: "failed_same" });
+ expect(q.classifyDiagnosticReportTerminal({
+ ...pendingRow,
+ status: "failed",
+ failureCode: "upload_conflict",
+ }, { status: "failed", failureCode: "invalid_upload" })).toEqual({ kind: "failed_different" });
+ expect(q.classifyDiagnosticReportTerminal(pendingRow, uploadExpected)).toEqual({ kind: "pending" });
+ });
+
+ it("rejects finalize time whose exact object expiry is not a safe integer", async () => {
+ const { db, chain } = scriptedDb([]);
+ await expect(
+ q.finalizeDiagnosticReportUpload(db, {
+ reportId: REPORT_ID,
+ machineId: MACHINE_ID,
+ r2Key: `bug-reports/${OWNER_ID}/${REPORT_ID}.ndjson.gz`,
+ sha256: "a".repeat(64),
+ sizeBytes: 1234,
+ nowMs: Number.MAX_SAFE_INTEGER - 604_800_000 + 1,
+ }),
+ ).rejects.toThrow(RangeError);
+ expect(chain.update).not.toHaveBeenCalled();
+ });
+});
diff --git a/src/web/migrations/0084_community_diagnostic_report.sql b/src/web/migrations/0084_community_diagnostic_report.sql
new file mode 100644
index 000000000..bbac44241
--- /dev/null
+++ b/src/web/migrations/0084_community_diagnostic_report.sql
@@ -0,0 +1,117 @@
+CREATE TABLE community_diagnostic_report (
+ id TEXT PRIMARY KEY NOT NULL,
+ owner_user_id TEXT NOT NULL,
+ agent_id TEXT NOT NULL,
+ machine_id TEXT NOT NULL,
+ client_nonce TEXT NOT NULL,
+ rate_bucket INTEGER NOT NULL,
+ status TEXT NOT NULL DEFAULT 'pending',
+ failure_code TEXT,
+ from_ms INTEGER NOT NULL,
+ created_at INTEGER NOT NULL,
+ deadline_at INTEGER NOT NULL,
+ completed_at INTEGER,
+ r2_key TEXT,
+ sha256 TEXT,
+ size_bytes INTEGER,
+ uploaded_at INTEGER,
+ object_expires_at INTEGER,
+ CONSTRAINT ck_community_diagnostic_report_id CHECK (
+ length(id) > 4
+ AND substr(id, 1, 4) = 'dbr_'
+ AND id NOT GLOB '*[^A-Za-z0-9_-]*'
+ ),
+ CONSTRAINT ck_community_diagnostic_report_nonce CHECK (
+ length(client_nonce) BETWEEN 16 AND 64
+ AND client_nonce NOT GLOB '*[^A-Za-z0-9_-]*'
+ ),
+ CONSTRAINT ck_community_diagnostic_report_required_epochs CHECK (
+ typeof(from_ms) = 'integer' AND from_ms BETWEEN 0 AND 9007199254740991
+ AND typeof(created_at) = 'integer' AND created_at BETWEEN 0 AND 9007199254740991
+ AND typeof(deadline_at) = 'integer' AND deadline_at BETWEEN 0 AND 9007199254740991
+ AND from_ms = created_at - 86400000
+ AND deadline_at = created_at + 600000
+ ),
+ CONSTRAINT ck_community_diagnostic_report_rate_bucket CHECK (
+ typeof(rate_bucket) = 'integer'
+ AND rate_bucket BETWEEN 0 AND 9007199254740991
+ AND rate_bucket = CAST(created_at / 60000 AS INTEGER)
+ ),
+ CONSTRAINT ck_community_diagnostic_report_nullable_epochs CHECK (
+ (completed_at IS NULL OR (typeof(completed_at) = 'integer' AND completed_at BETWEEN 0 AND 9007199254740991))
+ AND (uploaded_at IS NULL OR (typeof(uploaded_at) = 'integer' AND uploaded_at BETWEEN 0 AND 9007199254740991))
+ AND (object_expires_at IS NULL OR (typeof(object_expires_at) = 'integer' AND object_expires_at BETWEEN 0 AND 9007199254740991))
+ ),
+ CONSTRAINT ck_community_diagnostic_report_size CHECK (
+ size_bytes IS NULL
+ OR (typeof(size_bytes) = 'integer' AND size_bytes BETWEEN 1 AND 10485760)
+ ),
+ CONSTRAINT ck_community_diagnostic_report_sha256 CHECK (
+ sha256 IS NULL
+ OR (length(sha256) = 64 AND sha256 NOT GLOB '*[^0-9a-f]*')
+ ),
+ CONSTRAINT ck_community_diagnostic_report_state CHECK (
+ (
+ status = 'pending'
+ AND failure_code IS NULL AND completed_at IS NULL
+ AND r2_key IS NULL AND sha256 IS NULL AND size_bytes IS NULL
+ AND uploaded_at IS NULL AND object_expires_at IS NULL
+ ) OR (
+ status = 'failed'
+ AND failure_code IN (
+ 'offline', 'timeout', 'upload_conflict', 'invalid_upload',
+ 'diagnostics_unavailable', 'collector_busy', 'bot_not_bound',
+ 'collection_failed', 'local_artifact_invalid', 'bundle_too_large',
+ 'upload_failed', 'internal_error'
+ )
+ AND completed_at IS NOT NULL
+ AND completed_at >= created_at
+ AND r2_key IS NULL AND sha256 IS NULL AND size_bytes IS NULL
+ AND uploaded_at IS NULL AND object_expires_at IS NULL
+ ) OR (
+ status = 'uploaded'
+ AND failure_code IS NULL AND completed_at IS NOT NULL
+ AND completed_at >= created_at
+ AND r2_key IS NOT NULL
+ AND r2_key = 'bug-reports/' || owner_user_id || '/' || id || '.ndjson.gz'
+ AND sha256 IS NOT NULL AND size_bytes IS NOT NULL
+ AND uploaded_at IS NOT NULL AND object_expires_at IS NOT NULL
+ AND completed_at = uploaded_at
+ AND object_expires_at = uploaded_at + 604800000
+ )
+ )
+) WITHOUT ROWID;
+
+CREATE INDEX idx_community_diagnostic_report_owner_created
+ ON community_diagnostic_report(owner_user_id, created_at);
+
+CREATE INDEX idx_community_diagnostic_report_machine_status_deadline
+ ON community_diagnostic_report(machine_id, status, deadline_at);
+
+CREATE UNIQUE INDEX uq_community_diagnostic_report_owner_nonce
+ ON community_diagnostic_report(owner_user_id, client_nonce);
+
+CREATE UNIQUE INDEX uq_community_diagnostic_report_owner_agent_pending
+ ON community_diagnostic_report(owner_user_id, agent_id)
+ WHERE status = 'pending';
+
+CREATE UNIQUE INDEX uq_community_diagnostic_report_owner_rate_bucket
+ ON community_diagnostic_report(owner_user_id, rate_bucket);
+
+CREATE TRIGGER trg_community_diagnostic_report_update
+BEFORE UPDATE ON community_diagnostic_report
+FOR EACH ROW
+WHEN OLD.status <> 'pending'
+ OR NEW.status = 'pending'
+ OR NEW.id IS NOT OLD.id
+ OR NEW.owner_user_id IS NOT OLD.owner_user_id
+ OR NEW.agent_id IS NOT OLD.agent_id
+ OR NEW.machine_id IS NOT OLD.machine_id
+ OR NEW.client_nonce IS NOT OLD.client_nonce
+ OR NEW.rate_bucket IS NOT OLD.rate_bucket
+ OR NEW.from_ms IS NOT OLD.from_ms
+ OR NEW.created_at IS NOT OLD.created_at
+ OR NEW.deadline_at IS NOT OLD.deadline_at
+BEGIN
+ SELECT RAISE(ABORT, 'community diagnostic report immutable');
+END;
diff --git a/src/web/src/test/e2e/community-diagnostic-report-schema.test.ts b/src/web/src/test/e2e/community-diagnostic-report-schema.test.ts
new file mode 100644
index 000000000..0697aa52c
--- /dev/null
+++ b/src/web/src/test/e2e/community-diagnostic-report-schema.test.ts
@@ -0,0 +1,472 @@
+import { afterAll, beforeEach, describe, expect, it } from "vitest"
+import { sql, sqlQuery, sqlRun } from "@alook/test-utils"
+
+const TABLE = "community_diagnostic_report"
+const OWNER = "e2e_diag_owner"
+const AGENT = "e2e_diag_agent"
+const MACHINE = "cm_e2e_diag_machine"
+const CREATED = 1_786_531_200_000
+const FROM = CREATED - 86_400_000
+const DEADLINE = CREATED + 600_000
+const REPORT = "dbr_e2e_report"
+const NONCE = "nonce_e2e_1234567890"
+const SHA = "a".repeat(64)
+const KEY = `bug-reports/${OWNER}/${REPORT}.ndjson.gz`
+
+const FAILURE_CODES = [
+ "offline",
+ "timeout",
+ "upload_conflict",
+ "invalid_upload",
+ "diagnostics_unavailable",
+ "collector_busy",
+ "bot_not_bound",
+ "collection_failed",
+ "local_artifact_invalid",
+ "bundle_too_large",
+ "upload_failed",
+ "internal_error",
+] as const
+
+type Overrides = Partial<{
+ id: string
+ ownerUserId: string
+ agentId: string
+ machineId: string
+ clientNonce: string
+ rateBucket: number
+ status: string
+ failureCode: string | null
+ fromMs: number
+ createdAt: number
+ deadlineAt: number
+ completedAt: number | null
+ r2Key: string | null
+ sha256: string | null
+ sizeBytes: number | null
+ uploadedAt: number | null
+ objectExpiresAt: number | null
+}>
+
+function tableExists(): boolean {
+ return sqlQuery<{ name: string }>(
+ `SELECT name FROM sqlite_master WHERE type='table' AND name=?`,
+ TABLE,
+ ).length === 1
+}
+
+function clearReports(): void {
+ if (tableExists()) sqlRun(`DELETE FROM ${TABLE}`)
+}
+
+function insertReport(overrides: Overrides = {}): void {
+ const row = {
+ id: REPORT,
+ ownerUserId: OWNER,
+ agentId: AGENT,
+ machineId: MACHINE,
+ clientNonce: NONCE,
+ rateBucket: Math.floor(CREATED / 60_000),
+ status: "pending",
+ failureCode: null,
+ fromMs: FROM,
+ createdAt: CREATED,
+ deadlineAt: DEADLINE,
+ completedAt: null,
+ r2Key: null,
+ sha256: null,
+ sizeBytes: null,
+ uploadedAt: null,
+ objectExpiresAt: null,
+ ...overrides,
+ }
+ sqlRun(
+ `INSERT INTO ${TABLE} (
+ id, owner_user_id, agent_id, machine_id, client_nonce, rate_bucket,
+ status, failure_code, from_ms, created_at, deadline_at, completed_at,
+ r2_key, sha256, size_bytes, uploaded_at, object_expires_at
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+ row.id,
+ row.ownerUserId,
+ row.agentId,
+ row.machineId,
+ row.clientNonce,
+ row.rateBucket,
+ row.status,
+ row.failureCode,
+ row.fromMs,
+ row.createdAt,
+ row.deadlineAt,
+ row.completedAt,
+ row.r2Key,
+ row.sha256,
+ row.sizeBytes,
+ row.uploadedAt,
+ row.objectExpiresAt,
+ )
+}
+
+function upload(reportId = REPORT, uploadedAt = CREATED + 1_000): void {
+ sqlRun(
+ `UPDATE ${TABLE}
+ SET status='uploaded', completed_at=?, r2_key=?, sha256=?, size_bytes=?,
+ uploaded_at=?, object_expires_at=?
+ WHERE id=?`,
+ uploadedAt,
+ KEY,
+ SHA,
+ 1234,
+ uploadedAt,
+ uploadedAt + 604_800_000,
+ reportId,
+ )
+}
+
+beforeEach(() => {
+ sql("PRAGMA foreign_keys = ON")
+ clearReports()
+})
+
+afterAll(clearReports)
+
+describe("community_diagnostic_report migration parity", () => {
+ it("installs the exact B2a table", () => {
+ expect(tableExists()).toBe(true)
+ })
+
+ it("has the frozen columns, INTEGER epoch fields, and nullability", () => {
+ const columns = sqlQuery<{
+ name: string
+ type: string
+ notnull: number
+ pk: number
+ }>(`PRAGMA table_info(${TABLE})`)
+ expect(columns.map((c) => [c.name, c.type.toUpperCase(), c.notnull, c.pk])).toEqual([
+ ["id", "TEXT", 1, 1],
+ ["owner_user_id", "TEXT", 1, 0],
+ ["agent_id", "TEXT", 1, 0],
+ ["machine_id", "TEXT", 1, 0],
+ ["client_nonce", "TEXT", 1, 0],
+ ["rate_bucket", "INTEGER", 1, 0],
+ ["status", "TEXT", 1, 0],
+ ["failure_code", "TEXT", 0, 0],
+ ["from_ms", "INTEGER", 1, 0],
+ ["created_at", "INTEGER", 1, 0],
+ ["deadline_at", "INTEGER", 1, 0],
+ ["completed_at", "INTEGER", 0, 0],
+ ["r2_key", "TEXT", 0, 0],
+ ["sha256", "TEXT", 0, 0],
+ ["size_bytes", "INTEGER", 0, 0],
+ ["uploaded_at", "INTEGER", 0, 0],
+ ["object_expires_at", "INTEGER", 0, 0],
+ ])
+ })
+
+ it("has exact named concurrency/query indexes", () => {
+ const rows = sqlQuery<{ name: string; sql: string }>(
+ `SELECT name, sql FROM sqlite_master WHERE type='index' AND tbl_name=? ORDER BY name`,
+ TABLE,
+ )
+ expect(rows.map((r) => r.name)).toEqual([
+ "idx_community_diagnostic_report_machine_status_deadline",
+ "idx_community_diagnostic_report_owner_created",
+ "uq_community_diagnostic_report_owner_agent_pending",
+ "uq_community_diagnostic_report_owner_nonce",
+ "uq_community_diagnostic_report_owner_rate_bucket",
+ ])
+ expect(rows.find((r) => r.name.endsWith("owner_agent_pending"))?.sql).toMatch(
+ /WHERE\s+status\s*=\s*'pending'/i,
+ )
+ })
+
+ it("stores no FK that can pin or cascade-delete bot/machine snapshots", () => {
+ expect(tableExists()).toBe(true)
+ expect(sqlQuery(`PRAGMA foreign_key_list(${TABLE})`)).toEqual([])
+ })
+})
+
+describe("epoch-ms and relational CHECK constraints", () => {
+ it("admits one canonical pending row", () => {
+ expect(() => insertReport()).not.toThrow()
+ const [row] = sqlQuery<Record<string, unknown>>(
+ `SELECT *, typeof(from_ms) AS from_type, typeof(created_at) AS created_type,
+ typeof(deadline_at) AS deadline_type
+ FROM ${TABLE} WHERE id=?`,
+ REPORT,
+ )
+ expect(row).toMatchObject({
+ status: "pending",
+ from_ms: FROM,
+ created_at: CREATED,
+ deadline_at: DEADLINE,
+ from_type: "integer",
+ created_type: "integer",
+ deadline_type: "integer",
+ })
+ })
+
+ it.each([
+ ["bad report prefix", { id: "report_e2e" }],
+ ["empty report suffix", { id: "dbr_" }],
+ ["nonce shorter than 16", { clientNonce: "short_nonce" }],
+ ["nonce longer than 64", { clientNonce: "n".repeat(65) }],
+ ["nonce with punctuation", { clientNonce: "nonce.invalid.value!" }],
+ ])("rejects invalid identity shape: %s", (_name, overrides) => {
+ expect(() => insertReport(overrides)).toThrow(/CHECK constraint failed/i)
+ })
+
+ it.each([
+ ["fractional", Math.floor(CREATED / 60_000) + 0.5],
+ ["negative", -1],
+ ["unsafe", Number.MAX_SAFE_INTEGER + 1],
+ ["wrong canonical minute", Math.floor(CREATED / 60_000) + 1],
+ ])("rejects %s rate_bucket", (_name, rateBucket) => {
+ expect(() => insertReport({ rateBucket })).toThrow(/CHECK constraint failed/i)
+ })
+
+ it.each([
+ ["fractional createdAt", { createdAt: CREATED + 0.5 }],
+ ["negative createdAt", { createdAt: -1, fromMs: -86_400_001, deadlineAt: 599_999 }],
+ ["unsafe createdAt", { createdAt: Number.MAX_SAFE_INTEGER + 1 }],
+ ["wrong fromMs", { fromMs: FROM + 1 }],
+ ["wrong deadlineAt", { deadlineAt: DEADLINE + 1 }],
+ ["free-text status", { status: "collecting" }],
+ ["pending failure", { failureCode: "timeout" }],
+ ["pending completion", { completedAt: CREATED }],
+ ["pending object key", { r2Key: KEY }],
+ ["pending checksum", { sha256: SHA }],
+ ["pending size", { sizeBytes: 1 }],
+ ["pending uploadedAt", { uploadedAt: CREATED }],
+ ["pending object expiry", { objectExpiresAt: CREATED }],
+ ] as const)("rejects %s", (_name, overrides) => {
+ expect(() => insertReport(overrides)).toThrow(/CHECK constraint failed/i)
+ })
+
+ it.each([
+ ["from fractional", { fromMs: FROM + 0.5 }],
+ ["from negative", { fromMs: -1 }],
+ ["from unsafe", { fromMs: Number.MAX_SAFE_INTEGER + 1 }],
+ ["deadline fractional", { deadlineAt: DEADLINE + 0.5 }],
+ ["deadline negative", { deadlineAt: -1 }],
+ ["deadline unsafe", { deadlineAt: Number.MAX_SAFE_INTEGER + 1 }],
+ ])("rejects non-canonical required epoch: %s", (_name, overrides) => {
+ expect(() => insertReport(overrides)).toThrow(/CHECK constraint failed/i)
+ })
+
+ it.each([
+ ["completed fractional", CREATED + 0.5],
+ ["completed negative", -1],
+ ["completed unsafe", Number.MAX_SAFE_INTEGER + 1],
+ ])("rejects non-canonical nullable failed epoch: %s", (_name, completedAt) => {
+ expect(() =>
+ insertReport({ status: "failed", failureCode: "timeout", completedAt }),
+ ).toThrow(/CHECK constraint failed/i)
+ })
+
+ it.each(FAILURE_CODES)("admits fixed failed code %s", (failureCode) => {
+ expect(() =>
+ insertReport({
+ id: `dbr_${failureCode}`,
+ clientNonce: `nonce_${failureCode}_12345678`,
+ failureCode,
+ status: "failed",
+ completedAt: CREATED + 1,
+ }),
+ ).not.toThrow()
+ })
+
+ it.each([
+ ["unknown failure", { failureCode: "secret_detail" }],
+ ["failed without completion", { completedAt: null }],
+ ["failed before create", { completedAt: CREATED - 1 }],
+ ["failed with key", { r2Key: KEY }],
+ ["failed with sha", { sha256: SHA }],
+ ["failed with size", { sizeBytes: 1 }],
+ ["failed with uploadedAt", { uploadedAt: CREATED }],
+ ["failed with object expiry", { objectExpiresAt: CREATED }],
+ ] as const)("rejects %s", (_name, overrides) => {
+ expect(() =>
+ insertReport({ status: "failed", failureCode: "timeout", completedAt: CREATED + 1, ...overrides }),
+ ).toThrow(/CHECK constraint failed/i)
+ })
+
+ it("admits one coherent uploaded row", () => {
+ expect(() =>
+ insertReport({
+ status: "uploaded",
+ completedAt: CREATED + 1,
+ r2Key: KEY,
+ sha256: SHA,
+ sizeBytes: 1234,
+ uploadedAt: CREATED + 1,
+ objectExpiresAt: CREATED + 1 + 604_800_000,
+ }),
+ ).not.toThrow()
+ })
+
+ it.each([
+ ["uploaded failure", { failureCode: "upload_failed" }],
+ ["missing key", { r2Key: null }],
+ ["bad sha case", { sha256: "A".repeat(64) }],
+ ["bad sha length", { sha256: "a".repeat(63) }],
+ ["wrong object key", { r2Key: `bug-reports/${OWNER}/other.ndjson.gz` }],
+ ["zero size", { sizeBytes: 0 }],
+ ["completion mismatch", { completedAt: CREATED + 2 }],
+ ["expiry mismatch", { objectExpiresAt: CREATED + 2 + 604_800_000 }],
+ ] as const)("rejects incoherent uploaded row: %s", (_name, overrides) => {
+ expect(() =>
+ insertReport({
+ status: "uploaded",
+ completedAt: CREATED + 1,
+ r2Key: KEY,
+ sha256: SHA,
+ sizeBytes: 1234,
+ uploadedAt: CREATED + 1,
+ objectExpiresAt: CREATED + 1 + 604_800_000,
+ ...overrides,
+ }),
+ ).toThrow(/CHECK constraint failed/i)
+ })
+
+ it.each([
+ ["uploaded fractional", { uploadedAt: CREATED + 0.5, completedAt: CREATED + 0.5, objectExpiresAt: CREATED + 0.5 + 604_800_000 }],
+ ["uploaded negative", { uploadedAt: -1, completedAt: -1, objectExpiresAt: 604_799_999 }],
+ ["uploaded unsafe", { uploadedAt: Number.MAX_SAFE_INTEGER + 1, completedAt: Number.MAX_SAFE_INTEGER + 1, objectExpiresAt: Number.MAX_SAFE_INTEGER + 1 }],
+ ["expiry fractional", { objectExpiresAt: CREATED + 1 + 604_800_000 + 0.5 }],
+ ["expiry negative", { objectExpiresAt: -1 }],
+ ["expiry unsafe", { objectExpiresAt: Number.MAX_SAFE_INTEGER + 1 }],
+ ])("rejects non-canonical nullable uploaded epoch: %s", (_name, overrides) => {
+ expect(() =>
+ insertReport({
+ status: "uploaded",
+ completedAt: CREATED + 1,
+ r2Key: KEY,
+ sha256: SHA,
+ sizeBytes: 1234,
+ uploadedAt: CREATED + 1,
+ objectExpiresAt: CREATED + 1 + 604_800_000,
+ ...overrides,
+ }),
+ ).toThrow(/CHECK constraint failed/i)
+ })
+
+ it.each([
+ ["fractional", 1.5],
+ ["zero", 0],
+ ["over 10 MiB", 10 * 1024 * 1024 + 1],
+ ])("rejects %s uploaded sizeBytes", (_name, sizeBytes) => {
+ expect(() =>
+ insertReport({
+ status: "uploaded",
+ completedAt: CREATED + 1,
+ r2Key: KEY,
+ sha256: SHA,
+ sizeBytes,
+ uploadedAt: CREATED + 1,
+ objectExpiresAt: CREATED + 1 + 604_800_000,
+ }),
+ ).toThrow(/CHECK constraint failed/i)
+ })
+})
+
+describe("constraint-authoritative concurrency", () => {
+ it("owner+nonce is globally unique", () => {
+ insertReport()
+ expect(() => insertReport({ id: "dbr_nonce_2", agentId: "agent_2" })).toThrow(
+ /UNIQUE constraint failed/i,
+ )
+ })
+
+ it("owner+agent has at most one pending row across minutes", () => {
+ insertReport()
+ expect(() =>
+ insertReport({
+ id: "dbr_pending_2",
+ clientNonce: "nonce_pending_2_1234",
+ createdAt: CREATED + 60_000,
+ fromMs: FROM + 60_000,
+ deadlineAt: DEADLINE + 60_000,
+ rateBucket: Math.floor(CREATED / 60_000) + 1,
+ }),
+ ).toThrow(/UNIQUE constraint failed/i)
+ })
+
+ it("owner+rate bucket remains unique after the first row terminalizes", () => {
+ insertReport()
+ sqlRun(
+ `UPDATE ${TABLE} SET status='failed', failure_code='timeout', completed_at=? WHERE id=?`,
+ CREATED + 1,
+ REPORT,
+ )
+ expect(() =>
+ insertReport({
+ id: "dbr_rate_2",
+ agentId: "agent_2",
+ clientNonce: "nonce_rate_2_1234567",
+ }),
+ ).toThrow(/UNIQUE constraint failed/i)
+ })
+
+ it("next minute succeeds after the prior pending row terminalizes", () => {
+ insertReport()
+ sqlRun(
+ `UPDATE ${TABLE} SET status='failed', failure_code='timeout', completed_at=? WHERE id=?`,
+ CREATED + 1,
+ REPORT,
+ )
+ expect(() =>
+ insertReport({
+ id: "dbr_next_minute",
+ clientNonce: "nonce_next_min_123456",
+ createdAt: CREATED + 60_000,
+ fromMs: FROM + 60_000,
+ deadlineAt: DEADLINE + 60_000,
+ rateBucket: Math.floor(CREATED / 60_000) + 1,
+ }),
+ ).not.toThrow()
+ })
+})
+
+describe("UPDATE trigger enforces immutable snapshots and terminal rows", () => {
+ it.each([
+ ["no-op", `UPDATE ${TABLE} SET status=status WHERE id=?`],
+ ["owner", `UPDATE ${TABLE} SET owner_user_id='other' WHERE id=?`],
+ ["agent", `UPDATE ${TABLE} SET agent_id='other' WHERE id=?`],
+ ["machine", `UPDATE ${TABLE} SET machine_id='cm_other' WHERE id=?`],
+ ["from", `UPDATE ${TABLE} SET from_ms=from_ms+1 WHERE id=?`],
+ ["nonce", `UPDATE ${TABLE} SET client_nonce='nonce_other_12345678' WHERE id=?`],
+ ["bucket", `UPDATE ${TABLE} SET rate_bucket=rate_bucket+1 WHERE id=?`],
+ ["created", `UPDATE ${TABLE} SET created_at=created_at+1 WHERE id=?`],
+ ["deadline", `UPDATE ${TABLE} SET deadline_at=deadline_at+1 WHERE id=?`],
+ ])("rejects pending→pending %s UPDATE", (_name, statement) => {
+ insertReport()
+ expect(() => sqlRun(statement, REPORT)).toThrow(/diagnostic.*immutable|constraint/i)
+ })
+
+ it("allows exactly one coherent pending→uploaded transition", () => {
+ insertReport()
+ expect(() => upload()).not.toThrow()
+ expect(() => upload()).toThrow(/diagnostic.*immutable|constraint/i)
+ })
+
+ it("allows exactly one coherent pending→failed transition", () => {
+ insertReport()
+ expect(() =>
+ sqlRun(
+ `UPDATE ${TABLE} SET status='failed', failure_code='timeout', completed_at=? WHERE id=?`,
+ CREATED + 1,
+ REPORT,
+ ),
+ ).not.toThrow()
+ expect(() =>
+ sqlRun(`UPDATE ${TABLE} SET failure_code='offline' WHERE id=?`, REPORT),
+ ).toThrow(/diagnostic.*immutable|constraint/i)
+ })
+
+ it("rejects pending→uploaded when relational fields are incomplete", () => {
+ insertReport()
+ expect(() =>
+ sqlRun(`UPDATE ${TABLE} SET status='uploaded' WHERE id=?`, REPORT),
+ ).toThrow(/CHECK constraint failed/i)
+ })
+})