feat(competition): Phase 3.1 verifier + read routes + allowlist + scheduler

app/.well-known/agent.json/route.ts

@@ -366,6 +366,30 @@ export function GET() {
         inputModes: ["application/json"],
         outputModes: ["application/json"],
       },
+      {
+        id: "trading-comp",
+        name: "Trading Competition",
+        description:
+          "Trading-comp surface for the AIBTC verifier. " +
+          "GET /api/competition/status?address={stx} returns membership + verified trade counts; " +
+          "unregistered addresses come back as { registered: false } (not 404) so callers route to identity_register. " +
+          "GET /api/competition/trades?address={stx}&limit=50&cursor=… returns paginated swap " +
+          "history with keyset pagination over (burn_block_time, txid). " +
+          "POST /api/competition/trades submits a Stacks txid for verification — server fetches via Hiro, " +
+          "runs allowlist + sender checks, INSERT OR IGNOREs into the swaps table (first writer wins). " +
+          "Pending txs return 202 with no D1 row. " +
+          "Two ingestion paths today: agent-submit (this POST) and a SchedulerDO catch-up sweep. " +
+          "A third 'chainhook' source value is reserved in the schema for a future real-time stream.",
+        tags: ["competition", "trading", "swaps", "leaderboard"],
+        examples: [
+          "Get my trading-comp status",
+          "List my recent swaps",
+          "Submit a swap txid for verification",
+          "Check if my STX address is registered for the competition",
+        ],
+        inputModes: ["application/json"],
+        outputModes: ["application/json"],
+      },
       {
         id: "health-check",
         name: "System Health Check",

app/api/admin/scheduler/__tests__/route.test.ts

@@ -15,7 +15,10 @@ import { GET, POST } from "../route";
 
 const schedulerStub = {
   status: vi.fn().mockResolvedValue({ now: 123 }),
-  refreshNow: vi.fn().mockResolvedValue({ tenero: { succeeded: 1 } }),
+  refreshNow: vi.fn().mockResolvedValue({
+    tenero: { succeeded: 1 },
+    competition: { scanned: 1 },
+  }),
   pauseUntil: vi.fn().mockResolvedValue(undefined),
   resume: vi.fn().mockResolvedValue(undefined),
 };
@@ -56,7 +59,7 @@ describe("GET /api/admin/scheduler", () => {
 
   it("returns scheduler status with no-store/noindex headers", async () => {
     const response = await GET(request("/api/admin/scheduler"));
-    const body = await response.json();
+    const body = (await response.json()) as any;
 
     expect(response.status).toBe(200);
     expect(response.headers.get("cache-control")).toBe("no-store");
@@ -67,7 +70,7 @@ describe("GET /api/admin/scheduler", () => {
 
   it("rejects unknown scheduler names before touching a stub", async () => {
     const response = await GET(request("/api/admin/scheduler?name=typo"));
-    const body = await response.json();
+    const body = (await response.json()) as any;
 
     expect(response.status).toBe(400);
     expect(body.error).toContain("Unsupported scheduler name");
@@ -80,7 +83,7 @@ describe("POST /api/admin/scheduler", () => {
     const response = await POST(
       request("/api/admin/scheduler?action=pause", "POST")
     );
-    const body = await response.json();
+    const body = (await response.json()) as any;
 
     expect(response.status).toBe(400);
     expect(body.error).toContain("Missing `until`");
@@ -91,7 +94,7 @@ describe("POST /api/admin/scheduler", () => {
     const response = await POST(
       request("/api/admin/scheduler?action=refresh&task=prices", "POST")
     );
-    const body = await response.json();
+    const body = (await response.json()) as any;
 
     expect(response.status).toBe(400);
     expect(body.error).toContain("Unsupported task");
@@ -102,15 +105,26 @@ describe("POST /api/admin/scheduler", () => {
     const response = await POST(
       request("/api/admin/scheduler?name=v3&action=refresh&task=all", "POST")
     );
-    const body = await response.json();
+    const body = (await response.json()) as any;
 
     expect(response.status).toBe(200);
     expect(schedulerNamespace.idFromName).toHaveBeenCalledWith("v3");
     expect(schedulerStub.refreshNow).toHaveBeenCalledWith("all");
     expect(body).toEqual({
       name: "v3",
       task: "all",
-      result: { tenero: { succeeded: 1 } },
+      result: { tenero: { succeeded: 1 }, competition: { scanned: 1 } },
     });
   });
+
+  it("refreshes the competition scheduler task", async () => {
+    const response = await POST(
+      request("/api/admin/scheduler?action=refresh&task=competition", "POST")
+    );
+    const body = (await response.json()) as any;
+
+    expect(response.status).toBe(200);
+    expect(schedulerStub.refreshNow).toHaveBeenCalledWith("competition");
+    expect(body.task).toBe("competition");
+  });
 });

app/api/admin/scheduler/route.ts

@@ -5,7 +5,7 @@ import type { SchedulerRpc, SchedulerTask } from "@/lib/scheduler/rpc-types";
 
 const DEFAULT_SCHEDULER_INSTANCE = "v2";
 const ALLOWED_SCHEDULER_INSTANCES = new Set(["v1", "v2", "v3"]);
-const ALLOWED_TASKS = new Set<SchedulerTask>(["tenero", "all"]);
+const ALLOWED_TASKS = new Set<SchedulerTask>(["tenero", "competition", "all"]);
 
 function json(body: unknown, init: ResponseInit = {}) {
   const headers = new Headers(init.headers);
@@ -33,7 +33,7 @@ function schedulerTask(url: URL): SchedulerTask | NextResponse {
   const task = url.searchParams.get("task") || "tenero";
   if (!ALLOWED_TASKS.has(task as SchedulerTask)) {
     return json(
-      { error: "Unsupported task. Use tenero or all." },
+      { error: "Unsupported task. Use tenero, competition, or all." },
       { status: 400 }
     );
   }

app/api/competition/__tests__/d1-throws-fallback.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Phase 3.1 PR-A — D1-throws fallback policy regression test.
+ *
+ * Mirrors the contract established for inbox/outbox in Phase 2.5 (#722):
+ * when the D1 read layer throws — transient unavailability, network error,
+ * schema mismatch — the GET handler MUST return 503 with a structured body
+ * + Retry-After: 5 header, never an unstructured 500.
+ *
+ * Covers both competition read routes:
+ *   - GET /api/competition/status   → getCompetitionStatusFromD1 throw
+ *   - GET /api/competition/trades   → listSwapsFromD1 throw
+ *
+ * See: app/api/inbox/[address]/__tests__/d1-throws-fallback.test.ts (template)
+ */
+
+import { describe, it, expect, vi, beforeEach, type Mock } from "vitest";
+import { NextRequest } from "next/server";
+
+// ---- module mocks (must be declared before route imports) -------------------
+
+vi.mock("@opennextjs/cloudflare", () => ({
+  getCloudflareContext: vi.fn(),
+}));
+
+vi.mock("@/lib/logging", () => ({
+  createLogger: () => ({ info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+  createConsoleLogger: () => ({ info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+  isLogsRPC: () => false,
+}));
+
+vi.mock("@/lib/competition/d1-reads", () => ({
+  getCompetitionStatusFromD1: vi.fn(),
+  listSwapsFromD1: vi.fn(),
+  countSwapsFromD1: vi.fn(),
+  encodeSwapsCursor: vi.fn((t: number, x: string) => `enc(${t},${x})`),
+  decodeSwapsCursor: vi.fn(),
+}));
+
+// ---- imports after mocks ----------------------------------------------------
+
+import { GET as statusGet } from "../status/route";
+import { GET as tradesGet } from "../trades/route";
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+import {
+  getCompetitionStatusFromD1,
+  listSwapsFromD1,
+} from "@/lib/competition/d1-reads";
+
+// ---- shared fixtures --------------------------------------------------------
+
+const TEST_STX = "SP4DXVEC16FS6QR7RBKGWZYJKTXPC81W49W0ATJE";
+
+function buildStatusRequest(): NextRequest {
+  return new NextRequest(`https://aibtc.com/api/competition/status?address=${TEST_STX}`, {
+    method: "GET",
+  });
+}
+
+function buildTradesRequest(): NextRequest {
+  return new NextRequest(`https://aibtc.com/api/competition/trades?address=${TEST_STX}`, {
+    method: "GET",
+  });
+}
+
+function mockRateLimit(allow = true) {
+  return {
+    limit: vi.fn().mockResolvedValue({ success: allow }),
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+
+  (getCloudflareContext as Mock).mockReturnValue({
+    env: {
+      DB: { prepare: vi.fn() } as unknown as D1Database,
+      RATE_LIMIT_READ: mockRateLimit(true),
+      LOGS: undefined,
+    },
+    ctx: { waitUntil: vi.fn() },
+  });
+});
+
+describe("Phase 3.1 PR-A — D1-throws fallback policy (status)", () => {
+  it("returns 503 with structured body when getCompetitionStatusFromD1 throws", async () => {
+    (getCompetitionStatusFromD1 as Mock).mockRejectedValue(
+      new Error("D1_ERROR: connection reset")
+    );
+
+    const res = await statusGet(buildStatusRequest());
+
+    expect(res.status).toBe(503);
+    const body = (await res.json()) as any;
+    expect(body).toMatchObject({
+      error: "transient_d1_unavailable",
+      retry_after: 5,
+    });
+    expect(body.message).toMatch(/temporarily unavailable/i);
+    expect(res.headers.get("Retry-After")).toBe("5");
+  });
+
+  it("returns 503 (not 500) when D1 throws — guards the Forge cutover pattern", async () => {
+    (getCompetitionStatusFromD1 as Mock).mockRejectedValue(new Error("D1_ERROR: schema mismatch"));
+    const res = await statusGet(buildStatusRequest());
+    expect(res.status).not.toBe(500);
+    expect(res.status).toBe(503);
+  });
+
+  it("returns 503 when the D1 binding is missing entirely", async () => {
+    (getCloudflareContext as Mock).mockReturnValue({
+      env: { DB: undefined, RATE_LIMIT_READ: mockRateLimit(true), LOGS: undefined },
+      ctx: { waitUntil: vi.fn() },
+    });
+
+    const res = await statusGet(buildStatusRequest());
+    expect(res.status).toBe(503);
+    expect(res.headers.get("Retry-After")).toBe("5");
+  });
+});
+
+describe("Phase 3.1 PR-A — D1-throws fallback policy (trades)", () => {
+  it("returns 503 with structured body when listSwapsFromD1 throws", async () => {
+    (listSwapsFromD1 as Mock).mockRejectedValue(new Error("D1_ERROR: connection reset"));
+
+    const res = await tradesGet(buildTradesRequest());
+
+    expect(res.status).toBe(503);
+    const body = (await res.json()) as any;
+    expect(body).toMatchObject({
+      error: "transient_d1_unavailable",
+      retry_after: 5,
+    });
+    expect(res.headers.get("Retry-After")).toBe("5");
+  });
+
+  it("returns 503 (not 500) when D1 throws", async () => {
+    (listSwapsFromD1 as Mock).mockRejectedValue(new Error("D1_ERROR: anything"));
+    const res = await tradesGet(buildTradesRequest());
+    expect(res.status).not.toBe(500);
+    expect(res.status).toBe(503);
+  });
+
+  it("returns 503 when the D1 binding is missing entirely", async () => {
+    (getCloudflareContext as Mock).mockReturnValue({
+      env: { DB: undefined, RATE_LIMIT_READ: mockRateLimit(true), LOGS: undefined },
+      ctx: { waitUntil: vi.fn() },
+    });
+
+    const res = await tradesGet(buildTradesRequest());
+    expect(res.status).toBe(503);
+    expect(res.headers.get("Retry-After")).toBe("5");
+  });
+});
+
+// POST /api/competition/trades is exercised in detail by post-verifier.test.ts
+// (Phase 3.1 PR-B). The fallback-policy guarantee for that POST is asserted
+// there because it has different upstream dependencies (Hiro fetch + D1) than
+// the GET path.
+
+describe("Phase 3.1 PR-A — input validation (400)", () => {
+  it("status returns 400 on missing address", async () => {
+    const res = await statusGet(
+      new NextRequest("https://aibtc.com/api/competition/status", { method: "GET" })
+    );
+    expect(res.status).toBe(400);
+  });
+
+  it("status returns 400 on malformed address", async () => {
+    const res = await statusGet(
+      new NextRequest("https://aibtc.com/api/competition/status?address=not-an-stx", {
+        method: "GET",
+      })
+    );
+    expect(res.status).toBe(400);
+  });
+
+  it("trades returns 400 on missing address", async () => {
+    const res = await tradesGet(
+      new NextRequest("https://aibtc.com/api/competition/trades", { method: "GET" })
+    );
+    expect(res.status).toBe(400);
+  });
+
+  it("trades returns 400 when cursor is malformed", async () => {
+    const { decodeSwapsCursor } = await import("@/lib/competition/d1-reads");
+    (decodeSwapsCursor as Mock).mockImplementation(() => {
+      throw new Error("bad cursor");
+    });
+    const res = await tradesGet(
+      new NextRequest(
+        `https://aibtc.com/api/competition/trades?address=${TEST_STX}&cursor=garbage`,
+        { method: "GET" }
+      )
+    );
+    expect(res.status).toBe(400);
+  });
+});
+
+describe("Phase 3.1 PR-A — self-doc (?docs=1)", () => {
+  it("status returns the doc payload (200) without touching D1", async () => {
+    const res = await statusGet(
+      new NextRequest("https://aibtc.com/api/competition/status?docs=1", { method: "GET" })
+    );
+    expect(res.status).toBe(200);
+    expect(getCompetitionStatusFromD1).not.toHaveBeenCalled();
+    const body = (await res.json()) as any;
+    expect(body.endpoint).toBe("/api/competition/status");
+  });
+
+  it("trades returns the doc payload (200) without touching D1", async () => {
+    const res = await tradesGet(
+      new NextRequest("https://aibtc.com/api/competition/trades?docs=1", { method: "GET" })
+    );
+    expect(res.status).toBe(200);
+    expect(listSwapsFromD1).not.toHaveBeenCalled();
+    const body = (await res.json()) as any;
+    expect(body.endpoint).toBe("/api/competition/trades");
+  });
+});