create-ailk 0.1.1 → 0.2.0

package/templates/apps/api/src/services/__tests__/listing-promotion.test.ts

@@ -0,0 +1,684 @@
+/**
+ * @file listing-promotion.test.ts
+ * @description Unit tests for the listing-promotion service (#5295; ADR 0009
+ * D3 service-layer pattern), mirroring `lead-promotion.test.ts`.
+ *
+ * External dependency boundary mocked:
+ *   - apps/api/src/lib/prisma — the repo-standard `__mocks__/prisma.ts`
+ *     manual mock (`jest.mock("../../lib/prisma.js")`).
+ *
+ * `prisma.projectListing.findMany` is given a REALISTIC filtering
+ * implementation over an in-memory fixture "table" rather than a static
+ * `mockResolvedValue`, so the two security properties this service exists for
+ * actually get exercised against what the service passes to the DB. A bug that
+ * widened the `siteId` match set, or that loosened the email comparison, would
+ * surface the foreign row here rather than only in an argument-shape assertion.
+ *
+ * `tenant-context.ts`'s `listTenancy` runs REAL — it is a pure read over the
+ * mocked `prisma.membership.findMany` — so the "resolve via the sole
+ * tenant-context assembler" contract is covered rather than re-stubbed.
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../lib/prisma.js");
+
+import { prisma } from "../../lib/prisma.js";
+import { promoteListingsForVerifiedUser } from "../listing-promotion";
+import type { PromoteListingsResult } from "../listing-promotion";
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const USER_ID = "user_00000000-0000-7000-8000-0000000000a1";
+const OWN_ORG_ID = "org_00000000-0000-7000-8000-0000000000b1";
+const OWN_WORKSPACE_ID = "wksp_00000000-0000-7000-8000-0000000000c1";
+// OTHER_WORKSPACE_ID belongs to a different organization than OWN_ORG_ID —
+// the tenant-safety fixture (never a workspace of OWN_ORG_ID).
+const OTHER_WORKSPACE_ID = "wksp_00000000-0000-7000-8000-0000000000c2";
+// A SECOND workspace of the user's OWN organization — the per-site grain of the
+// ambiguity refusal needs two of the caller's own sites to be observable.
+const SECOND_WORKSPACE_ID = "wksp_00000000-0000-7000-8000-0000000000c3";
+const USER_EMAIL = "founder@example.com";
+
+type FakeListingRow = {
+  id: string;
+  founderEmail: string;
+  siteId: string;
+  ownerUserId: string | null;
+  /** Defaults to `requested` — a submitted, claimable row. */
+  status?: string;
+};
+
+/** Shapes prisma.membership.findMany's mocked return — what listTenancy reads. */
+function ownMembership() {
+  return [
+    {
+      role: "owner",
+      organization: {
+        id: OWN_ORG_ID,
+        name: "Acme",
+        slug: "acme",
+        workspaces: [{ id: OWN_WORKSPACE_ID, name: "Acme HQ", slug: "acme-hq" }],
+      },
+    },
+  ];
+}
+
+function verifiedUser(overrides?: Partial<{ emailVerified: boolean; email: string }>) {
+  return {
+    id: USER_ID,
+    email: overrides?.email ?? USER_EMAIL,
+    emailVerified: overrides?.emailVerified ?? true,
+  };
+}
+
+/**
+ * Wires projectListing.findMany / updateMany to a realistic in-memory "table"
+ * filtered by the `where` the service passes.
+ *
+ * `founderEmail` is compared with `===` here deliberately: the service passes a
+ * plain string (EXACT equality), not `{ equals, mode: "insensitive" }`. Prisma
+ * compiles an insensitive `equals` to `ILIKE`, which would make `_` and `%` in
+ * the caller's own address LIKE wildcards — so if the service ever switched to
+ * that form, this fixture would no longer model the DB and the
+ * wildcard-capture test below would stop being meaningful. The fixture asserts
+ * the form it models.
+ */
+function seedListingTable(rows: FakeListingRow[]) {
+  const table = rows.map((r) => ({ ...r }));
+
+  (prisma.projectListing.findMany as jest.Mock).mockImplementation(
+    async (args: {
+      where: {
+        founderEmail: unknown;
+        siteId: { in: string[] };
+        ownerUserId: null;
+        status?: { in?: string[] };
+      };
+      select: { id: true; siteId: true };
+    }) => {
+      const { founderEmail, siteId, status } = args.where;
+      if (typeof founderEmail !== "string") {
+        throw new Error(
+          "listing-promotion must compare founderEmail by exact string equality; " +
+            "a filter object (e.g. mode: 'insensitive') compiles to ILIKE and makes " +
+            "`_`/`%` in the caller's own address wildcards",
+        );
+      }
+      // A candidate read with no status term would make an anonymous,
+      // quota-free draft claimable; model the filter so its absence fails.
+      if (!Array.isArray(status?.in)) {
+        throw new Error(
+          "the candidate read must constrain status; a draft is created anonymously with no quota, so a claimable draft is a planted-row vector",
+        );
+      }
+      const claimable = status.in;
+      return table
+        .filter(
+          (row) =>
+            row.founderEmail === founderEmail &&
+            siteId.in.includes(row.siteId) &&
+            row.ownerUserId === null &&
+            claimable.includes(row.status ?? "requested"),
+        )
+        .map((row) => ({ id: row.id, siteId: row.siteId }));
+    },
+  );
+
+  /**
+   * Models the WRITE's own `ownerUserId: null` predicate, not just its id list.
+   * Without that the mock would happily overwrite a row already linked to
+   * somebody else, hiding the compare-and-swap the service relies on to survive
+   * two concurrent reconciliation runs.
+   */
+  (prisma.projectListing.updateMany as jest.Mock).mockImplementation(
+    async (args: {
+      where: { id: { in: string[] }; ownerUserId: null };
+      data: { ownerUserId: string; ownerLinkedAt: Date };
+    }) => {
+      if (args.where.ownerUserId !== null) {
+        throw new Error(
+          "the owner-link write must repeat `ownerUserId: null`; without it a concurrent run transfers a row away from the user who already claimed it",
+        );
+      }
+      let count = 0;
+      for (const row of table) {
+        if (args.where.id.in.includes(row.id) && row.ownerUserId === null) {
+          row.ownerUserId = args.data.ownerUserId;
+          count += 1;
+        }
+      }
+      return { count };
+    },
+  );
+
+  return table;
+}
+
+describe("promoteListingsForVerifiedUser", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  // ── The happy path: all three conditions hold ────────────────────────────
+  it("links an un-linked listing whose founderEmail is the verified user's own, in the user's own workspace", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(verifiedUser());
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    const table = seedListingTable([
+      {
+        id: "prjl_00000000-0000-7000-8000-0000000000d1",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+    ]);
+
+    const result = await promoteListingsForVerifiedUser({ userId: USER_ID });
+
+    expect(result).toEqual<PromoteListingsResult>({
+      ok: true,
+      count: 1,
+      promoted: [
+        {
+          listingId: "prjl_00000000-0000-7000-8000-0000000000d1",
+          siteId: OWN_WORKSPACE_ID,
+        },
+      ],
+    });
+    expect(prisma.projectListing.findMany).toHaveBeenCalledWith({
+      where: {
+        founderEmail: USER_EMAIL,
+        siteId: { in: [OWN_WORKSPACE_ID] },
+        ownerUserId: null,
+        status: { in: ["requested", "rejected", "active"] },
+      },
+      select: { id: true, siteId: true },
+    });
+    expect(prisma.projectListing.updateMany).toHaveBeenCalledWith({
+      where: {
+        id: { in: ["prjl_00000000-0000-7000-8000-0000000000d1"] },
+        // Repeated on the write, so the update is a compare-and-swap.
+        ownerUserId: null,
+      },
+      data: { ownerUserId: USER_ID, ownerLinkedAt: expect.any(Date) },
+    });
+    expect(table[0]?.ownerUserId).toBe(USER_ID);
+  });
+
+  // ── SECURITY PROPERTY 1 ──────────────────────────────────────────────────
+  it("an UNVERIFIED email never produces a link, even when it MATCHES founderEmail exactly", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(
+      verifiedUser({ emailVerified: false }),
+    );
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    // The listing's founderEmail is byte-identical to the caller's address, and
+    // it sits in a workspace the caller owns. Only verification is missing.
+    const table = seedListingTable([
+      {
+        id: "prjl_unverified_match",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+    ]);
+
+    const result = await promoteListingsForVerifiedUser({ userId: USER_ID });
+
+    expect(result).toEqual<PromoteListingsResult>({
+      ok: true,
+      count: 0,
+      promoted: [],
+    });
+    // The gate is evaluated BEFORE any tenancy or listing read happens at all.
+    expect(prisma.membership.findMany).not.toHaveBeenCalled();
+    expect(prisma.projectListing.findMany).not.toHaveBeenCalled();
+    expect(prisma.projectListing.updateMany).not.toHaveBeenCalled();
+    expect(table[0]?.ownerUserId).toBeNull();
+  });
+
+  // ── SECURITY PROPERTY 2 ──────────────────────────────────────────────────
+  it("a matching, VERIFIED email in a DIFFERENT tenant never produces a link", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(verifiedUser());
+    // The user belongs ONLY to OWN_ORG_ID / OWN_WORKSPACE_ID.
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    const table = seedListingTable([
+      {
+        id: "prjl_cross_tenant",
+        founderEmail: USER_EMAIL, // the caller's own verified address
+        siteId: OTHER_WORKSPACE_ID, // a DIFFERENT organization's workspace
+        ownerUserId: null,
+      },
+    ]);
+
+    const result = await promoteListingsForVerifiedUser({ userId: USER_ID });
+
+    expect(result).toEqual<PromoteListingsResult>({
+      ok: true,
+      count: 0,
+      promoted: [],
+    });
+    expect(prisma.projectListing.updateMany).not.toHaveBeenCalled();
+    expect(table.find((r) => r.id === "prjl_cross_tenant")?.ownerUserId).toBeNull();
+    // The query itself never widens siteId.in to the foreign workspace.
+    expect(prisma.projectListing.findMany).toHaveBeenCalledWith({
+      where: {
+        founderEmail: USER_EMAIL,
+        siteId: { in: [OWN_WORKSPACE_ID] },
+        ownerUserId: null,
+        status: { in: ["requested", "rejected", "active"] },
+      },
+      select: { id: true, siteId: true },
+    });
+  });
+
+  /**
+   * The email comparison is EXACT, so a LIKE metacharacter in the caller's own
+   * verified address cannot capture a different founder's row.
+   *
+   * Verified against a live Postgres while building this: with
+   * `{ equals, mode: "insensitive" }` Prisma emits `founder_email ILIKE $1`,
+   * and a caller whose real address is `a_c@example.com` matched BOTH its own
+   * row and a stranger's `abc@example.com` in the same workspace — two rows in,
+   * two rows out. This test is the regression lock for that.
+   */
+  it("a LIKE metacharacter in the caller's own verified address captures no other founder's listing", async () => {
+    const WILDCARD_EMAIL = "a_c@example.com";
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(
+      verifiedUser({ email: WILDCARD_EMAIL }),
+    );
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    const table = seedListingTable([
+      {
+        id: "prjl_mine",
+        founderEmail: WILDCARD_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+      {
+        // A DIFFERENT person, in the same workspace, whose address differs from
+        // the caller's only where the `_` sits.
+        id: "prjl_neighbour",
+        founderEmail: "abc@example.com",
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+    ]);
+
+    const result = (await promoteListingsForVerifiedUser({
+      userId: USER_ID,
+    })) as Extract<PromoteListingsResult, { ok: true }>;
+
+    expect(result.count).toBe(1);
+    expect(result.promoted).toEqual([
+      { listingId: "prjl_mine", siteId: OWN_WORKSPACE_ID },
+    ]);
+    expect(table.find((r) => r.id === "prjl_neighbour")?.ownerUserId).toBeNull();
+  });
+
+  // ── Two people sharing an address: the link follows the VERIFIED one ──────
+  it("two listings sharing a founderEmail are both linked ONLY to the user who verified that address", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(verifiedUser());
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    const table = seedListingTable([
+      {
+        id: "prjl_shared_1",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+      {
+        // Already linked to SOMEBODY ELSE — excluded by `ownerUserId: null`, so
+        // a later verifier of the same address can never steal it.
+        id: "prjl_shared_2",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: "user_00000000-0000-7000-8000-0000000000a2",
+      },
+    ]);
+
+    const result = (await promoteListingsForVerifiedUser({
+      userId: USER_ID,
+    })) as Extract<PromoteListingsResult, { ok: true }>;
+
+    expect(result.count).toBe(1);
+    expect(result.promoted).toEqual([
+      { listingId: "prjl_shared_1", siteId: OWN_WORKSPACE_ID },
+    ]);
+    expect(table.find((r) => r.id === "prjl_shared_2")?.ownerUserId).toBe(
+      "user_00000000-0000-7000-8000-0000000000a2",
+    );
+  });
+
+  /**
+   * THE COUNTEREXAMPLE this service is built to refuse.
+   *
+   * Two strangers both typed the same address into the anonymous form, so there
+   * are TWO un-linked rows carrying it at one site and nothing that says which
+   * is whose. Linking both to whoever verifies the address would hand one
+   * person the other's whole application — the disclosure the owner link exists
+   * to remove, arriving through the promotion path instead of the read path.
+   *
+   * Found by an independent verifier who reproduced it end to end against a
+   * live Postgres before the refusal existed: `count: 2`, and the verifying
+   * founder read the stranger's row through `GET /v1/project-listings/me`.
+   */
+  it("REFUSES to link when TWO un-linked listings share the address at one site", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(verifiedUser());
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    const table = seedListingTable([
+      {
+        id: "prjl_typed_by_founder_a",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+      {
+        // A DIFFERENT person who typed the same address. Indistinguishable.
+        id: "prjl_typed_by_founder_b",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+    ]);
+
+    const result = await promoteListingsForVerifiedUser({ userId: USER_ID });
+
+    expect(result).toEqual<PromoteListingsResult>({
+      ok: true,
+      count: 0,
+      promoted: [],
+    });
+    expect(prisma.projectListing.updateMany).not.toHaveBeenCalled();
+    // BOTH rows stay null. Neither founder can read the other's application.
+    expect(table.find((r) => r.id === "prjl_typed_by_founder_a")?.ownerUserId).toBeNull();
+    expect(table.find((r) => r.id === "prjl_typed_by_founder_b")?.ownerUserId).toBeNull();
+  });
+
+  it("an ambiguous group at one site does not block an unambiguous row at another", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(verifiedUser());
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue([
+      {
+        role: "owner",
+        organization: {
+          id: OWN_ORG_ID,
+          name: "Acme",
+          slug: "acme",
+          workspaces: [
+            { id: OWN_WORKSPACE_ID, name: "Acme HQ", slug: "acme-hq" },
+            { id: SECOND_WORKSPACE_ID, name: "Acme Two", slug: "acme-two" },
+          ],
+        },
+      },
+    ]);
+    const table = seedListingTable([
+      // Ambiguous pair at the first site — both refused.
+      {
+        id: "prjl_ambiguous_a",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+      {
+        id: "prjl_ambiguous_b",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+      // The only row carrying the address at the SECOND site — attributable.
+      {
+        id: "prjl_unambiguous",
+        founderEmail: USER_EMAIL,
+        siteId: SECOND_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+    ]);
+
+    const result = (await promoteListingsForVerifiedUser({
+      userId: USER_ID,
+    })) as Extract<PromoteListingsResult, { ok: true }>;
+
+    expect(result.count).toBe(1);
+    expect(result.promoted).toEqual([
+      { listingId: "prjl_unambiguous", siteId: SECOND_WORKSPACE_ID },
+    ]);
+    expect(table.find((r) => r.id === "prjl_ambiguous_a")?.ownerUserId).toBeNull();
+    expect(table.find((r) => r.id === "prjl_ambiguous_b")?.ownerUserId).toBeNull();
+    expect(table.find((r) => r.id === "prjl_unambiguous")?.ownerUserId).toBe(USER_ID);
+  });
+
+  /**
+   * The write repeats `ownerUserId: null`, so a run that loses a race matches 0
+   * rows instead of transferring a row away from the user who already claimed
+   * it. The candidate read alone cannot establish this: both runs read the row
+   * as un-linked before either wrote.
+   */
+  it("a row claimed between the candidate read and the write is not transferred away", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(verifiedUser());
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    const table = seedListingTable([
+      {
+        id: "prjl_raced",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+    ]);
+
+    // Simulate the interleaving: another verifier claims the row after this
+    // call's candidate read returns it and before its update runs.
+    const findMany = prisma.projectListing.findMany as jest.Mock;
+    const realFindMany = findMany.getMockImplementation();
+    findMany.mockImplementation(async (args: Parameters<typeof realFindMany>[0]) => {
+      const rows = await realFindMany!(args);
+      const raced = table.find((r) => r.id === "prjl_raced");
+      if (raced) raced.ownerUserId = "user_00000000-0000-7000-8000-0000000000a9";
+      return rows;
+    });
+
+    const result = await promoteListingsForVerifiedUser({ userId: USER_ID });
+
+    expect(result).toEqual<PromoteListingsResult>({
+      ok: true,
+      count: 0,
+      promoted: [],
+    });
+    // The first claimant keeps the row.
+    expect(table.find((r) => r.id === "prjl_raced")?.ownerUserId).toBe(
+      "user_00000000-0000-7000-8000-0000000000a9",
+    );
+  });
+
+  /**
+   * The denial-of-link the ambiguity refusal would otherwise open, found by the
+   * security reviewer after the refusal landed.
+   *
+   * `POST /v1/project-listings` is anonymous and the concurrent-listing quota is
+   * enforced at SUBMIT, not at start, so anyone with a site's public key — which
+   * ships in browser JavaScript by design — can create unbounded `draft` rows
+   * carrying any address. One planted draft would be enough to make every
+   * genuine row at that site ambiguous, permanently blocking the real founder
+   * from ever claiming their own listing. Excluding drafts from candidacy is
+   * what stops one anonymous request from doing that.
+   */
+  it("a planted anonymous DRAFT neither links nor blocks the founder's own submitted row", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(verifiedUser());
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    const table = seedListingTable([
+      {
+        id: "prjl_planted_draft",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+        status: "draft",
+      },
+      {
+        id: "prjl_genuine_submitted",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+        status: "requested",
+      },
+    ]);
+
+    const result = (await promoteListingsForVerifiedUser({
+      userId: USER_ID,
+    })) as Extract<PromoteListingsResult, { ok: true }>;
+
+    // The draft is not a candidate, so the group is NOT ambiguous and the
+    // founder's own submitted row still links.
+    expect(result.count).toBe(1);
+    expect(result.promoted).toEqual([
+      { listingId: "prjl_genuine_submitted", siteId: OWN_WORKSPACE_ID },
+    ]);
+    expect(table.find((r) => r.id === "prjl_planted_draft")?.ownerUserId).toBeNull();
+  });
+
+  it("a rejected listing is still the founder's own and still links", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(verifiedUser());
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    seedListingTable([
+      {
+        id: "prjl_rejected",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+        status: "rejected",
+      },
+    ]);
+
+    const result = (await promoteListingsForVerifiedUser({
+      userId: USER_ID,
+    })) as Extract<PromoteListingsResult, { ok: true }>;
+
+    expect(result.count).toBe(1);
+  });
+
+  // ── Case + whitespace: the user side is normalized the way writes are ────
+  it("normalizes the user's address the way startProjectListingDraft normalizes founderEmail", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(
+      verifiedUser({ email: "  Founder@Example.com " }),
+    );
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    seedListingTable([
+      {
+        id: "prjl_normalized",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+    ]);
+
+    const result = (await promoteListingsForVerifiedUser({
+      userId: USER_ID,
+    })) as Extract<PromoteListingsResult, { ok: true }>;
+
+    expect(result.count).toBe(1);
+    expect(prisma.projectListing.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: expect.objectContaining({ founderEmail: USER_EMAIL }),
+      }),
+    );
+  });
+
+  // ── Idempotent ───────────────────────────────────────────────────────────
+  it("a listing linked on the first run is excluded on the second run", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(verifiedUser());
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    seedListingTable([
+      {
+        id: "prjl_first_run",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+    ]);
+
+    const first = await promoteListingsForVerifiedUser({ userId: USER_ID });
+    expect(first).toEqual<PromoteListingsResult>({
+      ok: true,
+      count: 1,
+      promoted: [{ listingId: "prjl_first_run", siteId: OWN_WORKSPACE_ID }],
+    });
+
+    const second = await promoteListingsForVerifiedUser({ userId: USER_ID });
+    expect(second).toEqual<PromoteListingsResult>({
+      ok: true,
+      count: 0,
+      promoted: [],
+    });
+  });
+
+  // ── No match → count:0 ───────────────────────────────────────────────────
+  it("no matching listing → count:0 with no update", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(verifiedUser());
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    seedListingTable([]);
+
+    const result = await promoteListingsForVerifiedUser({ userId: USER_ID });
+
+    expect(result).toEqual<PromoteListingsResult>({
+      ok: true,
+      count: 0,
+      promoted: [],
+    });
+    expect(prisma.projectListing.updateMany).not.toHaveBeenCalled();
+  });
+
+  // ── No workspaces → no-op, never queries the listing table ───────────────
+  it("a user with no workspaces is a no-op — never queries inbox.ProjectListing", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(verifiedUser());
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue([]);
+
+    const result = await promoteListingsForVerifiedUser({ userId: USER_ID });
+
+    expect(result).toEqual<PromoteListingsResult>({
+      ok: true,
+      count: 0,
+      promoted: [],
+    });
+    expect(prisma.projectListing.findMany).not.toHaveBeenCalled();
+  });
+
+  // ── Unknown user → ok:false, user_not_found ──────────────────────────────
+  it("an unknown userId returns ok:false with kind user_not_found", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(null);
+
+    const result = (await promoteListingsForVerifiedUser({
+      userId: "user_does-not-exist",
+    })) as Extract<PromoteListingsResult, { ok: false }>;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.kind).toBe("user_not_found");
+  });
+
+  // ── A DB failure is a result, never a throw ──────────────────────────────
+  it("a DB failure returns ok:false internal_error rather than throwing", async () => {
+    (prisma.user.findUnique as jest.Mock).mockRejectedValue(
+      new Error("connection terminated"),
+    );
+
+    const result = (await promoteListingsForVerifiedUser({
+      userId: USER_ID,
+    })) as Extract<PromoteListingsResult, { ok: false }>;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.kind).toBe("internal_error");
+  });
+
+  // ── PII non-leak — the result never carries the user's raw email ─────────
+  it("PII non-leak — the result never carries the founder's raw email", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(verifiedUser());
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(ownMembership());
+    seedListingTable([
+      {
+        id: "prjl_pii",
+        founderEmail: USER_EMAIL,
+        siteId: OWN_WORKSPACE_ID,
+        ownerUserId: null,
+      },
+    ]);
+
+    const result = await promoteListingsForVerifiedUser({ userId: USER_ID });
+
+    expect(JSON.stringify(result)).not.toContain(USER_EMAIL);
+  });
+});