@pithy-sh/matchmaking 0.1.0

package/src/migrations/0001_matchmaking.ts

@@ -0,0 +1,64 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * Creates the matchmaking D1 tables: `pithy_matchmaking_invites` (direct invites) and
+ * `pithy_matchmaking_friends` (the symmetric friend graph). Room codes live in KV, so they are not here.
+ * All identifiers are camelCase; the runner's `CamelCasePlugin` snake-cases them to `pithy_matchmaking_*`.
+ */
+export const matchmaking_0001_matchmaking: Migration = {
+  up: async (db: Kysely<unknown>) => {
+    await db.schema
+      .createTable("pithyMatchmakingInvites")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("gameKey", "text", (c) => c.notNull())
+      .addColumn("inviterId", "text", (c) => c.notNull())
+      .addColumn("inviteeId", "text", (c) => c.notNull())
+      .addColumn("status", "text", (c) => c.notNull())
+      .addColumn("sessionId", "text")
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("respondedAt", "integer")
+      .execute();
+
+    await db.schema
+      .createIndex("pithyMatchmakingInvitesInviteeIdx")
+      .on("pithyMatchmakingInvites")
+      .columns(["inviteeId", "status"])
+      .execute();
+
+    await db.schema
+      .createTable("pithyMatchmakingFriends")
+      .addColumn("id", "integer", (c) => c.primaryKey().autoIncrement())
+      .addColumn("userA", "text", (c) => c.notNull())
+      .addColumn("userB", "text", (c) => c.notNull())
+      .addColumn("status", "text", (c) => c.notNull())
+      .addColumn("requestedBy", "text", (c) => c.notNull())
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      .execute();
+
+    await db.schema
+      .createIndex("pithyMatchmakingFriendsPairIdx")
+      .on("pithyMatchmakingFriends")
+      .columns(["userA", "userB"])
+      .unique()
+      .execute();
+
+    await db.schema
+      .createIndex("pithyMatchmakingFriendsByUserB")
+      .on("pithyMatchmakingFriends")
+      .columns(["userB"])
+      .execute();
+  },
+
+  down: async (db: Kysely<unknown>) => {
+    await db.schema.dropIndex("pithyMatchmakingFriendsByUserB").execute();
+    await db.schema.dropIndex("pithyMatchmakingFriendsPairIdx").execute();
+    await db.schema.dropTable("pithyMatchmakingFriends").execute();
+    await db.schema.dropIndex("pithyMatchmakingInvitesInviteeIdx").execute();
+    await db.schema.dropTable("pithyMatchmakingInvites").execute();
+  },
+};

package/src/presence/durableObject.ts

@@ -0,0 +1,114 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { DurableObject } from "cloudflare:workers";
+import type { D1Database } from "@cloudflare/workers-types";
+import { matchmakingDatabase } from "../data/tables";
+import { friendStore } from "../friends/store";
+import { inviteStore } from "../invite/store";
+import { PRESENCE_USER_HEADER, type PresenceEvent } from "./protocol";
+
+// The header and the event shapes are **not** re-exported from here. They live in `./protocol` and are
+// imported from there by everyone, DO included. Re-exporting them made this module a legal source for two
+// pure values, and a value import out of a `cloudflare:workers` module is exactly how #172 reached
+// multiplayer's config path — the routes only needed two constants, and they took the whole DO with them.
+// One source per value, and it is the pure one.
+
+/**
+ * Presence — a single Durable Object (addressed by a fixed name) holding every online player's WebSocket
+ * via the Hibernation API. On connect it delivers a player's pending invites and which of their friends
+ * are currently online; thereafter `notify()` pushes real-time events (a match found, an invite received,
+ * a friend request). "Friends online" is the intersection of a user's friend graph with the connected
+ * set. A single shared object has a soft ~1,000 req/s ceiling — adequate for notifications; noted as a
+ * scaling consideration.
+ *
+ * Platform discipline (mirrors the multiplayer session DO): the WebSocket Hibernation API only (never
+ * `ws.accept()`), the authenticated identity stashed with `serializeAttachment` so it survives eviction,
+ * and no in-memory connection registry — the live set is always read back from `getWebSockets()`.
+ */
+export interface MatchmakingPresenceEnv {
+  DB: D1Database;
+}
+
+export class MatchmakingPresence extends DurableObject<MatchmakingPresenceEnv> {
+  /**
+   * WebSocket upgrade — accepts the connection (Hibernation API) and sends the initial presence payload. The
+   * upgrade is forwarded by the authenticated Hono handler, which sets {@link PRESENCE_USER_HEADER} to the
+   * AuthContext user id; the DO trusts that server-set header and never a client-supplied id.
+   */
+  override async fetch(request: Request): Promise<Response> {
+    if (request.headers.get("upgrade") !== "websocket") {
+      return new Response("Expected a WebSocket upgrade.", { status: 426 });
+    }
+    const userId = request.headers.get(PRESENCE_USER_HEADER);
+    if (!userId) return new Response("Missing authenticated user.", { status: 401 });
+
+    const pair = new WebSocketPair();
+    const [client, server] = [pair[0], pair[1]];
+    // Hibernation API — never `server.accept()`, which would pin the object in memory. The `userId` tag lets
+    // the runtime hand this user's sockets back after eviction.
+    this.ctx.acceptWebSocket(server, [userId]);
+    // A tiny attachment (well under the 16,384-byte ceiling): the identity that survives hibernation.
+    server.serializeAttachment({ userId });
+
+    // The connect payload: this player's pending invites, plus which of their accepted friends are online now.
+    const db = matchmakingDatabase(this.env.DB);
+    const pendingInvites = await inviteStore(db).pendingFor(userId);
+    const friends = await friendStore(db).list(userId);
+    const accepted = new Set(friends.filter((edge) => edge.status === "accepted").map((edge) => edge.userId));
+    const onlineFriends = this.connectedUserIds().filter((id) => accepted.has(id));
+    server.send(JSON.stringify({ type: "init", pendingInvites, onlineFriends }));
+
+    return new Response(null, { status: 101, webSocket: client });
+  }
+
+  /** Push an event to a connected user's sockets. A no-op if the user is offline. */
+  async notify(userId: string, event: PresenceEvent): Promise<void> {
+    const frame = JSON.stringify(event);
+    for (const ws of this.ctx.getWebSockets()) {
+      if (this.socketUserId(ws) !== userId) continue;
+      try {
+        ws.send(frame);
+      } catch {
+        // A dead socket — skip it; the player resyncs on reconnect. One bad socket never blocks the rest.
+      }
+    }
+  }
+
+  /** The user ids currently connected — distinct, read back from each socket's attachment (hibernation-safe). */
+  connectedUserIds(): string[] {
+    const ids = new Set<string>();
+    for (const ws of this.ctx.getWebSockets()) {
+      const id = this.socketUserId(ws);
+      if (id) ids.add(id);
+    }
+    return [...ids];
+  }
+
+  /** Keepalive only — presence carries no client-authoritative state; a `ping` gets a `pong`, else no-op. */
+  override async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
+    const text = typeof message === "string" ? message : new TextDecoder().decode(message);
+    if (text === "ping") {
+      try {
+        ws.send("pong");
+      } catch {
+        // Socket is closing — nothing to answer.
+      }
+    }
+  }
+
+  override async webSocketClose(ws: WebSocket): Promise<void> {
+    // Nothing authoritative lives on the socket; a reconnecting player re-upgrades and gets a fresh payload.
+    try {
+      ws.close();
+    } catch {
+      // Already closing — ignore.
+    }
+  }
+
+  /** The authenticated user id stashed on a socket, or undefined for an unidentified one. */
+  private socketUserId(ws: WebSocket): string | undefined {
+    const attachment = ws.deserializeAttachment() as { userId?: string } | null;
+    return attachment?.userId;
+  }
+}

package/src/presence/protocol.ts

@@ -0,0 +1,17 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The presence protocol — the header and event shapes shared by the presence Durable Object and the HTTP
+ * routes. Kept free of any `cloudflare:workers` import so the routes (and their node-side tests) can depend
+ * on it without pulling the DO runtime into a plain Node environment.
+ */
+
+/** The server-set header carrying the authenticated user id into the presence DO. The DO trusts only this. */
+export const PRESENCE_USER_HEADER = "x-pithy-user-id";
+
+/** An event pushed to a connected player over the presence socket. */
+export type PresenceEvent =
+  | { type: "match_found"; sessionId: string; gameKey: string }
+  | { type: "invite"; inviteId: string; gameKey: string; from: string }
+  | { type: "friend_request"; from: string };

package/src/queue/durableObject.ts

@@ -0,0 +1,209 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { DurableObject } from "cloudflare:workers";
+import type { D1Database, DurableObjectNamespace } from "@cloudflare/workers-types";
+import type { MatchmakingQueueSettings, MatchmakingSnapshot } from "../config/config";
+import { MatchmakingNotQueuedError } from "../error/errors";
+import { guardRpc } from "../rpc";
+import { type SessionNamespace, sessionMinter } from "../session/minter";
+import { formMatches, StoredMatch, WaitingList, type WaitingTicket } from "./matching";
+
+/**
+ * The open-queue coordinator — one Durable Object per game (addressed `env.QUEUE.idFromName(gameKey)`).
+ * Players enqueue with their skill and region bucket; the DO pairs them, minting a multiplayer session
+ * when a full roster forms. An alarm sweeps on a cadence, widening each waiting player's skill band the
+ * longer they wait, so a long wait relaxes into any-opponent. Matches are recorded per user for a polling
+ * `status()` read, and pushed best-effort to the presence DO.
+ *
+ * Platform discipline (mirrors the multiplayer session DO): storage is read fresh and Zod-parsed in every
+ * handler (no in-memory cache to survive eviction); the sweep is a single persisted alarm at an absolute
+ * ms-epoch time (never a timer); and the alarm handler is idempotent (an empty queue clears the alarm and
+ * no-ops). `Date.now()` is used inside handlers — permitted in the Workers runtime.
+ */
+export interface MatchmakingQueueEnv {
+  DB: D1Database;
+  SESSIONS?: DurableObjectNamespace;
+  PRESENCE?: DurableObjectNamespace;
+}
+
+/** A player's entry into the queue — everything the coordinator needs to bucket and later mint. */
+export interface QueueTicket {
+  userId: string;
+  skill: number | null;
+  region: string;
+  gameKey: string;
+  players: number;
+  settings: MatchmakingQueueSettings;
+  snapshot: MatchmakingSnapshot;
+}
+
+/** A player's standing in the queue. */
+export interface QueueStatus {
+  state: "queued" | "matched";
+  sessionId: string | null;
+  waitingMs: number;
+}
+
+/** The minimal presence RPC the coordinator pushes to — declared locally so the queue never imports it. */
+interface PresenceStub {
+  notify(userId: string, event: { type: "match_found"; sessionId: string; gameKey: string }): Promise<void>;
+}
+
+const WAITING_KEY = "waiting";
+const GAME_KEY = "gameKey";
+const PRESENCE_NAME = "presence";
+
+const matchKey = (userId: string): string => `match:${userId}`;
+
+export class MatchmakingQueue extends DurableObject<MatchmakingQueueEnv> {
+  /** Add a player to the queue and attempt an immediate match. */
+  async enqueue(ticket: QueueTicket): Promise<QueueStatus> {
+    const now = Date.now();
+
+    // A match already waiting for this player wins — return it (status delivers-once, so don't clear here).
+    const existing = await this.readMatch(ticket.userId);
+    if (existing) return { state: "matched", sessionId: existing.sessionId, waitingMs: 0 };
+
+    // Remember this coordinator's game for the alarm's later match records and presence pushes.
+    await this.ctx.storage.put(GAME_KEY, ticket.gameKey);
+
+    // Upsert the waiting entry with a fresh wait clock.
+    const waiting = (await this.readWaiting()).filter((t) => t.userId !== ticket.userId);
+    waiting.push({
+      userId: ticket.userId,
+      skill: ticket.skill,
+      region: ticket.region,
+      players: ticket.players,
+      snapshot: ticket.snapshot,
+      settings: ticket.settings,
+      enqueuedAt: now,
+    });
+
+    const { matched, remaining } = await this.applyMatches(waiting, now);
+    await this.reconcileAlarm(remaining, now);
+
+    const mine = matched.get(ticket.userId);
+    // The enqueue response reports the match as a convenience; the stored copy stays so a client that polls
+    // status() instead still receives it (status is the deliver-once channel). A join is idempotent, so a
+    // client that reads both channels simply joins the same session twice with no ill effect.
+    if (mine) return { state: "matched", sessionId: mine.sessionId, waitingMs: 0 };
+    return { state: "queued", sessionId: null, waitingMs: 0 };
+  }
+
+  /** Remove a player from the queue. */
+  async leave(userId: string): Promise<void> {
+    const waiting = await this.readWaiting();
+    const remaining = waiting.filter((t) => t.userId !== userId);
+    if (remaining.length === waiting.length) return;
+    await this.ctx.storage.put(WAITING_KEY, remaining);
+    if (remaining.length === 0) await this.ctx.storage.deleteAlarm();
+  }
+
+  /** A player's current standing — returns and clears a match once found. */
+  async status(userId: string): Promise<QueueStatus> {
+    // guardRpc encodes the not-queued PithyError so its 404 survives the DO RPC boundary (else it 500s).
+    return guardRpc(async () => {
+      const match = await this.readMatch(userId);
+      if (match) {
+        // Deliver-once: hand back the match and drop it so a re-poll reflects the (now empty) standing.
+        await this.ctx.storage.delete(matchKey(userId));
+        return { state: "matched", sessionId: match.sessionId, waitingMs: 0 };
+      }
+      const mine = (await this.readWaiting()).find((t) => t.userId === userId);
+      if (mine) return { state: "queued", sessionId: null, waitingMs: Date.now() - mine.enqueuedAt };
+      throw new MatchmakingNotQueuedError({ detail: `User ${userId} is not queued for this game.` });
+    });
+  }
+
+  /** The sweep: re-attempt pairing with bands widened by elapsed wait, mint and record any formed rosters. */
+  override async alarm(): Promise<void> {
+    const now = Date.now();
+    const waiting = await this.readWaiting();
+    if (waiting.length === 0) {
+      await this.ctx.storage.deleteAlarm();
+      return;
+    }
+    const { remaining } = await this.applyMatches(waiting, now);
+    await this.reconcileAlarm(remaining, now);
+  }
+
+  // --- internals ---
+
+  /** The waiting queue, read fresh and validated. Empty when nothing is stored. */
+  private async readWaiting(): Promise<WaitingTicket[]> {
+    const raw = await this.ctx.storage.get(WAITING_KEY);
+    return raw === undefined ? [] : WaitingList.parse(raw);
+  }
+
+  /** This player's recorded match, read fresh and validated, or undefined. */
+  private async readMatch(userId: string): Promise<StoredMatch | undefined> {
+    const raw = await this.ctx.storage.get(matchKey(userId));
+    return raw === undefined ? undefined : StoredMatch.parse(raw);
+  }
+
+  private async readGameKey(): Promise<string> {
+    const raw = await this.ctx.storage.get(GAME_KEY);
+    return typeof raw === "string" ? raw : "";
+  }
+
+  /**
+   * Run the pairing rule over `waiting`, mint a session per formed roster (or null when `SESSIONS` is not
+   * bound), record each matched player's result, and persist the players left waiting. Presence is always
+   * pushed best-effort for a match that minted a session — whether it formed on enqueue or on the sweep —
+   * so a waiting player is notified in real time in the common two-player case, not only by polling.
+   */
+  private async applyMatches(
+    waiting: WaitingTicket[],
+    now: number,
+  ): Promise<{ matched: Map<string, StoredMatch>; remaining: WaitingTicket[] }> {
+    const gameKey = await this.readGameKey();
+    const matched = new Map<string, StoredMatch>();
+
+    for (const { roster } of formMatches(waiting, now)) {
+      const anchor = waiting.find((t) => t.userId === roster[0]);
+      if (!anchor) continue;
+      const sessionId = this.env.SESSIONS
+        ? await sessionMinter(this.env.SESSIONS as unknown as SessionNamespace).mint(
+            anchor.snapshot,
+            anchor.players,
+            roster,
+          )
+        : null;
+      const record: StoredMatch = { sessionId, roster: [...roster], gameKey, at: now };
+      for (const uid of roster) matched.set(uid, record);
+    }
+
+    const remaining = waiting.filter((t) => !matched.has(t.userId));
+    for (const [uid, record] of matched) await this.ctx.storage.put(matchKey(uid), record);
+    await this.ctx.storage.put(WAITING_KEY, remaining);
+    await this.pushPresence(matched);
+
+    return { matched, remaining };
+  }
+
+  /** Push each newly matched player a `match_found` event — best-effort, never fatal, only if presence is bound. */
+  private async pushPresence(matched: Map<string, StoredMatch>): Promise<void> {
+    const presence = this.env.PRESENCE;
+    if (!presence) return;
+    const stub = presence.get(presence.idFromName(PRESENCE_NAME)) as unknown as PresenceStub;
+    for (const [uid, record] of matched) {
+      if (!record.sessionId) continue;
+      try {
+        await stub.notify(uid, { type: "match_found", sessionId: record.sessionId, gameKey: record.gameKey });
+      } catch {
+        // A notification never fails the match that formed it — the result is already recorded for polling.
+      }
+    }
+  }
+
+  /** Keep a single sweep alarm armed while anyone is waiting; clear it once the queue drains. */
+  private async reconcileAlarm(remaining: WaitingTicket[], now: number): Promise<void> {
+    const first = remaining[0];
+    if (first) {
+      await this.ctx.storage.setAlarm(now + first.settings.sweepSeconds * 1000);
+    } else {
+      await this.ctx.storage.deleteAlarm();
+    }
+  }
+}

package/src/queue/matching.ts

@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { MatchmakingQueueSettings, MatchmakingSnapshot } from "../config/config";
+
+/**
+ * The open-queue matching core — the pure pairing rule and the shapes the {@link MatchmakingQueue} Durable
+ * Object persists. Kept here, free of any Workers runtime import, so the algorithm is unit-testable in a
+ * plain Node context and the DO shell simply drives it.
+ *
+ * A waiting player carries their skill and region bucket plus the settings that govern how their skill band
+ * widens with time. {@link formMatches} is deterministic in `(waiting, now)`: the longer a player waits, the
+ * wider their acceptable opponent skill window, until — past `maxWaitSeconds` — it opens to anyone in their
+ * region. Players in different regions never pair; an unrated player (`skill` null) pairs with anyone.
+ */
+
+/** One player waiting in a game's open queue — a single entry in the DO's persisted `waiting` array. */
+export const WaitingTicket = z
+  .object({
+    userId: z.string().describe("The waiting player's authenticated user id — the roster and match key."),
+    skill: z
+      .number()
+      .nullable()
+      .describe("The player's skill number in the game's rating pool, or null when unrated (pairs with anyone)."),
+    region: z.string().describe("The region bucket the player is pinned to — pairing never crosses regions."),
+    players: z.number().int().describe("How many players form a match in this game — the roster size to fill."),
+    snapshot: MatchmakingSnapshot.describe("How to mint the multiplayer session once this ticket's roster fills."),
+    settings: MatchmakingQueueSettings.describe("The band settings that govern how this ticket's skill window widens."),
+    enqueuedAt: z
+      .number()
+      .int()
+      .describe("When the player entered the queue, ms epoch — the age its band widens from."),
+  })
+  .describe("A player waiting in a game's open queue.");
+export type WaitingTicket = z.output<typeof WaitingTicket>;
+
+/** The DO's persisted queue — every player currently waiting in this game. */
+export const WaitingList = z.array(WaitingTicket).describe("Every player currently waiting in a game's open queue.");
+export type WaitingList = z.output<typeof WaitingList>;
+
+/** A formed match recorded per player, read once by a polling `status()` and pushed best-effort to presence. */
+export const StoredMatch = z
+  .object({
+    sessionId: z
+      .string()
+      .nullable()
+      .describe("The minted multiplayer session id, or null when @pithy-sh/multiplayer is not installed."),
+    roster: z.array(z.string()).describe("The user ids paired into this match, creator first."),
+    gameKey: z.string().describe("The game this match belongs to — carried for the presence `match_found` push."),
+    at: z.number().int().describe("When the match formed, ms epoch."),
+  })
+  .describe("A formed match recorded for one player, delivered once on the next status read.");
+export type StoredMatch = z.output<typeof StoredMatch>;
+
+/** A single formed roster — the user ids that pair into one match. */
+export interface MatchGroup {
+  roster: string[];
+}
+
+/**
+ * A ticket's current skill band half-width at `now`. An unrated player has no band (they pair with anyone).
+ * Otherwise the band starts at `initialBand` and grows by `widenPerSecond` for every second waited, until it
+ * opens without bound once the wait passes `maxWaitSeconds`.
+ */
+function band(ticket: WaitingTicket, now: number): number {
+  if (ticket.skill === null) return Number.POSITIVE_INFINITY;
+  const elapsedMs = now - ticket.enqueuedAt;
+  const { initialBand, widenPerSecond, maxWaitSeconds } = ticket.settings;
+  if (elapsedMs >= maxWaitSeconds * 1000) return Number.POSITIVE_INFINITY;
+  return initialBand + widenPerSecond * (elapsedMs / 1000);
+}
+
+/**
+ * Whether two waiting players may pair right now. Either being unrated pairs them; otherwise their skill gap
+ * must fit inside the wider of the two bands — so the longer-waiting player's relaxed window carries the pair.
+ */
+function compatible(a: WaitingTicket, b: WaitingTicket, now: number): boolean {
+  if (a.skill === null || b.skill === null) return true;
+  return Math.abs(a.skill - b.skill) <= Math.max(band(a, now), band(b, now));
+}
+
+/**
+ * Form as many full rosters as the waiting set allows at `now`. Pure and deterministic. Players are bucketed
+ * by region (a pair never crosses regions); within a bucket the oldest waiter anchors a roster — its band is
+ * widest — and compatible others (in wait order) fill it to `players`. A roster that cannot fill leaves its
+ * anchor waiting; the sweep alarm retries later with a wider band.
+ */
+export function formMatches(waiting: WaitingTicket[], now: number): MatchGroup[] {
+  const results: MatchGroup[] = [];
+
+  const byRegion = new Map<string, WaitingTicket[]>();
+  for (const ticket of waiting) {
+    const bucket = byRegion.get(ticket.region);
+    if (bucket) bucket.push(ticket);
+    else byRegion.set(ticket.region, [ticket]);
+  }
+
+  for (const bucket of byRegion.values()) {
+    let pool = [...bucket].sort((a, b) => a.enqueuedAt - b.enqueuedAt);
+    while (pool.length > 0) {
+      const anchor = pool[0];
+      if (!anchor) break;
+      const need = anchor.players;
+      const roster: WaitingTicket[] = [anchor];
+      for (let i = 1; i < pool.length && roster.length < need; i++) {
+        const candidate = pool[i];
+        // Compatible with EVERY current roster member, not just the anchor — so an N-player roster never
+        // seats two members whose skills exceed each other's band.
+        if (candidate && roster.every((member) => compatible(member, candidate, now))) roster.push(candidate);
+      }
+      if (roster.length === need) {
+        results.push({ roster: roster.map((ticket) => ticket.userId) });
+        const chosen = new Set(roster);
+        pool = pool.filter((ticket) => !chosen.has(ticket));
+      } else {
+        // The oldest waiter cannot fill a roster yet — leave it and try the next.
+        pool = pool.slice(1);
+      }
+    }
+  }
+
+  return results;
+}

package/src/queue/skill.ts

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+
+/**
+ * Read a player's skill number in a rating pool via the optional `@pithy-sh/rating` seam
+ * (dynamic-imported). Returns `null` when rating is not installed, the pool is empty, or the player is
+ * unrated — the queue then buckets that player by region only. Never throws for an absent dependency; a
+ * missing skill is a `null`, not an error.
+ */
+export async function readSkill(db: D1Database, pool: string, userId: string): Promise<number | null> {
+  try {
+    const { ratingStore } = await import("@pithy-sh/rating/src/data/store");
+    const { ratingDatabase } = await import("@pithy-sh/rating/src/data/tables");
+    const record = await ratingStore(ratingDatabase(db)).get(pool, userId);
+    return record?.skill ?? null;
+  } catch {
+    // Rating is an optional peer: a missing package, an unmigrated pool, or an unrated player is a `null`,
+    // never a failure — the queue falls back to region-only bucketing.
+    return null;
+  }
+}

package/src/rpc.ts

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ErrorPayload } from "@pithy-sh/core/src/error/payload";
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+
+/**
+ * The Durable Object RPC error codec — the same shape multiplayer uses. A `PithyError` thrown inside a DO
+ * is flattened to a bare `Error` across the RPC boundary (only its `message` survives), which would turn a
+ * deliberate 404 into a 500. The DO encodes the payload into the message; the route decodes it back into a
+ * real `PithyError` so its status and code are preserved.
+ */
+export const RPC_ERROR_PREFIX = "pithy-error:";
+
+/** DO side: run a body, re-encoding any thrown `PithyError` into a message the boundary preserves. */
+export async function guardRpc<T>(run: () => Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof PithyError) throw new Error(RPC_ERROR_PREFIX + JSON.stringify(error.payload));
+    throw error;
+  }
+}
+
+/** Route side: run a DO call, decoding an encoded `PithyError` message back into a real `PithyError`. */
+export async function callRpc<T>(run: () => Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof PithyError) throw error;
+    const message = (error as { message?: unknown } | null)?.message;
+    if (typeof message === "string" && message.startsWith(RPC_ERROR_PREFIX)) {
+      try {
+        const parsed = ErrorPayload.safeParse(JSON.parse(message.slice(RPC_ERROR_PREFIX.length)));
+        if (parsed.success) throw new PithyError(parsed.data, { cause: error });
+      } catch (reviveError) {
+        if (reviveError instanceof PithyError) throw reviveError;
+      }
+    }
+    throw error;
+  }
+}

package/src/seeds/example.ts

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { EXAMPLE_ADA, EXAMPLE_ALAN, EXAMPLE_GRACE } from "@pithy-sh/core/src/seed/exampleIdentities";
+import { d1SeedGroup, defineSeed, type SeedSet } from "@pithy-sh/core/src/seed/seed";
+import { Friendship } from "../data/friend";
+import { Invite } from "../data/invite";
+import { MATCHMAKING_FRIENDS_TABLE, MATCHMAKING_INVITES_TABLE } from "../data/tables";
+
+/**
+ * A small social graph among the example cast: Ada and Grace are friends, and Alan has a pending invite
+ * out to Ada. Enough to read a `/matchmaking/friends` and `/matchmaking/invites` response against right
+ * after `pithy seed`. Never runs in production.
+ */
+const MATCHMAKING_EXAMPLE_SEED_ORDER = 220;
+const now = () => new Date();
+
+// Friend pairs are stored canonically (userA < userB); sort the two ids so the seed matches the store.
+const [friendA, friendB] = [EXAMPLE_ADA.id, EXAMPLE_GRACE.id].sort();
+
+export const matchmakingExampleSeed: SeedSet = defineSeed({
+  name: "example",
+  order: MATCHMAKING_EXAMPLE_SEED_ORDER,
+  environments: ["dev", "staging"],
+  example: true,
+  d1: [
+    d1SeedGroup("app", MATCHMAKING_FRIENDS_TABLE, Friendship, [
+      {
+        id: 1,
+        userA: friendA ?? EXAMPLE_ADA.id,
+        userB: friendB ?? EXAMPLE_GRACE.id,
+        status: "accepted",
+        requestedBy: EXAMPLE_ADA.id,
+        createdAt: now(),
+        updatedAt: now(),
+      },
+    ]),
+    d1SeedGroup("app", MATCHMAKING_INVITES_TABLE, Invite, [
+      {
+        id: "11111111-1111-4111-8111-111111111111",
+        gameKey: "duel",
+        inviterId: EXAMPLE_ALAN.id,
+        inviteeId: EXAMPLE_ADA.id,
+        status: "pending",
+        sessionId: null,
+        createdAt: now(),
+        respondedAt: null,
+      },
+    ]),
+  ],
+});