@pithy-sh/core 0.12.0 → 0.14.0

package/src/presence/frames.ts

@@ -0,0 +1,153 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ErrorBody } from "../error/wire";
+import type { SocketVersions } from "../http/subprotocol";
+import { PresenceActivity } from "./names";
+
+/**
+ * **Every frame on a presence room socket, as the Zod schema it is sent and parsed with.**
+ *
+ * Pure: zod and core's leaf modules. A browser imports it to type the socket, and the AsyncAPI document
+ * reads the same schemas through the declaring capability's `sockets`, so the document and the Durable
+ * Object cannot disagree.
+ *
+ * **How a client reads a frame, stated once** (`docs/SOCKETS.md`). A field added to a frame later is
+ * optional. A client ignores a `type` and a key it does not know. A change no client could ignore is a new
+ * subprotocol, and the Worker keeps serving the one before it.
+ *
+ * **The keepalive is plain text**, the one exception to JSON: a client sends `ping`, the Worker answers
+ * `pong`. The only JSON frame a client sends is `set_activity`.
+ */
+
+/** The subprotocols a room serves. There is no unversioned room: a ticket can only arrive in the offer. */
+export const PRESENCE_ROOM_VERSIONS: SocketVersions = { current: "pithy.presence.v1", previous: null };
+
+/** Which door a participant came in by. */
+export const PresenceOrigin = z
+  .enum(["control-plane", "session"])
+  .describe(
+    "Which door the participant came in by: `control-plane`, a management client such as the dashboard, or `session`, a signed-in user of the app.",
+  );
+export type PresenceOrigin = z.infer<typeof PresenceOrigin>;
+
+/** Who a participant is, as the minting door states it. */
+export const PresenceParticipantRef = z
+  .string()
+  .min(1)
+  .max(128)
+  .describe(
+    "Who the participant is. A management client's own opaque reference, which it chose; or the signed-in user's id, which the Worker chose.",
+  );
+
+/** The longest participant name, in UTF-16 code units — what zod's `.max` counts. */
+export const PRESENCE_PARTICIPANT_NAME_MAX = 80;
+
+/** How the others see a participant. */
+export const PresenceParticipantName = z
+  .string()
+  .trim()
+  .min(1)
+  .max(PRESENCE_PARTICIPANT_NAME_MAX)
+  .describe("How the other participants see this one. A label, never an identity — `ref` and `origin` are that.");
+
+/** One participant in a room. */
+export const PresenceParticipant = z
+  .object({
+    id: z
+      .string()
+      .uuid()
+      .describe("This participant's id in the room — one per socket, so one person in two tabs is two participants."),
+    ref: PresenceParticipantRef,
+    name: PresenceParticipantName,
+    origin: PresenceOrigin,
+    activity: PresenceActivity.describe("What they are doing now, one of the room kind's declared activities."),
+    joinedAt: z.iso.datetime().describe("When this socket joined, ISO-8601."),
+  })
+  .describe("One participant in a presence room: one open socket.");
+export type PresenceParticipant = z.infer<typeof PresenceParticipant>;
+
+/** The first frame on every room socket. */
+export const PresenceRoomInitFrame = z
+  .object({
+    type: z.literal("init").describe("Always `init`."),
+    self: z.string().uuid().describe("This socket's own participant id, so a client can find itself in the list."),
+    participants: z
+      .array(PresenceParticipant)
+      .describe("Everyone in the room now, this socket included, in the order they joined."),
+  })
+  .describe("Who is in the room, sent once as soon as the socket opens.");
+export type PresenceRoomInitFrame = z.infer<typeof PresenceRoomInitFrame>;
+
+/** Someone joined. */
+export const PresenceJoinedFrame = z
+  .object({
+    type: z.literal("joined").describe("Always `joined`."),
+    participant: PresenceParticipant.describe("Who joined."),
+  })
+  .describe("Another participant joined the room.");
+export type PresenceJoinedFrame = z.infer<typeof PresenceJoinedFrame>;
+
+/** Someone left, or their socket dropped. */
+export const PresenceLeftFrame = z
+  .object({
+    type: z.literal("left").describe("Always `left`."),
+    participantId: z.string().uuid().describe("The participant who left."),
+  })
+  .describe("Another participant left the room, or their socket dropped.");
+export type PresenceLeftFrame = z.infer<typeof PresenceLeftFrame>;
+
+/** Someone changed what they are doing. */
+export const PresenceActivityFrame = z
+  .object({
+    type: z.literal("activity").describe("Always `activity`."),
+    participantId: z.string().uuid().describe("The participant whose activity changed."),
+    activity: PresenceActivity.describe("What they are doing now."),
+  })
+  .describe("Another participant announced a different activity.");
+export type PresenceActivityFrame = z.infer<typeof PresenceActivityFrame>;
+
+/** A frame the room could not accept. */
+export const PresenceRoomErrorFrame = z
+  .object({
+    type: z.literal("error").describe("Always `error`."),
+    error: ErrorBody.shape.error,
+  })
+  .describe(
+    "The room could not accept a frame — not one it reads, an activity the room kind does not declare, or past the size limit. The error is the one an HTTP response would carry.",
+  );
+export type PresenceRoomErrorFrame = z.infer<typeof PresenceRoomErrorFrame>;
+
+/** Every JSON frame the Worker sends on a room socket. `pong` is the plain-text exception. */
+export const PresenceRoomServerFrame = z
+  .discriminatedUnion("type", [
+    PresenceRoomInitFrame,
+    PresenceJoinedFrame,
+    PresenceLeftFrame,
+    PresenceActivityFrame,
+    PresenceRoomErrorFrame,
+  ])
+  .describe("A JSON frame the Worker sends on a presence room socket.");
+export type PresenceRoomServerFrame = z.infer<typeof PresenceRoomServerFrame>;
+
+/** Announce a different activity. */
+export const PresenceSetActivityFrame = z
+  .object({
+    type: z.literal("set_activity").describe("Always `set_activity`."),
+    activity: PresenceActivity.describe("What this participant is doing now. One of the room kind's declared values."),
+  })
+  .describe("Announce what this participant is doing now.");
+export type PresenceSetActivityFrame = z.infer<typeof PresenceSetActivityFrame>;
+
+/** Every JSON frame a client may send on a room socket. `ping` is the plain-text exception. */
+export const PresenceRoomClientFrame = z
+  .discriminatedUnion("type", [PresenceSetActivityFrame])
+  .describe("A JSON frame a client sends on a presence room socket.");
+export type PresenceRoomClientFrame = z.infer<typeof PresenceRoomClientFrame>;
+
+/** The keepalive a client sends, as plain text. */
+export const PresenceRoomPing = z.literal("ping").describe("The plain-text keepalive a client sends.");
+
+/** The Worker's answer to `ping`, as plain text. */
+export const PresenceRoomPong = z.literal("pong").describe("The plain-text answer to `ping`.");

package/src/presence/http/guard.ts

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MiddlewareHandler } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { UnauthorizedError } from "../../error/pithyError";
+
+/**
+ * Require a signed-in user of the app, over the `AuthContext` seam. Kept here rather than imported from
+ * `@pithy-sh/auth`, which core may not depend on — and without auth composed `c.var.auth` is null, so the
+ * session ticket route denies rather than stands open.
+ */
+export function requireAuth(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+    await next();
+  };
+}

package/src/presence/http/responses.ts

@@ -0,0 +1,63 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ControlPlaneScope } from "../../controlPlane/scope/scope";
+import { PRESENCE_ROOM_VERSIONS } from "../frames";
+import { PresenceActivity, PresenceRecordId, PresenceRoomKindName } from "../names";
+
+/**
+ * A minted presence ticket and where to spend it. Both ticket routes answer it.
+ *
+ * Read across a version boundary like every response schema, so a field added here later is `.optional()`.
+ */
+export const PresenceTicket = z
+  .object({
+    ticket: z
+      .string()
+      .min(1)
+      .describe(
+        "The ticket. Offer it in `Sec-WebSocket-Protocol` as `pithy.ticket.<ticket>`, beside `protocol`. Single use.",
+      ),
+    expiresAt: z.iso.datetime().describe("When the ticket stops being honored, ISO-8601 — 60 seconds after minting."),
+    kind: PresenceRoomKindName.describe("The room kind the ticket admits to."),
+    recordId: PresenceRecordId.describe("The record the room is about."),
+    socketPath: z
+      .string()
+      .min(1)
+      .describe("The path to open the socket at, on this Worker — this room's, already filled in."),
+    protocol: z
+      .literal(PRESENCE_ROOM_VERSIONS.current)
+      .describe("The subprotocol to offer beside the ticket. The Worker answers with it."),
+  })
+  .describe("A single-use, 60-second ticket into one presence room, and where to open the socket with it.");
+export type PresenceTicket = z.infer<typeof PresenceTicket>;
+
+/**
+ * One room kind, as `GET /control-plane/manifest` reports it under the capability that declares it. Built
+ * from the capability's resolved `basePath`, so a client never assumes where a socket is.
+ */
+export const PresenceRoomDescriptor = z
+  .object({
+    kind: PresenceRoomKindName.describe("The room kind — `support.thread`."),
+    scope: ControlPlaneScope.describe(
+      "The scope that reads the record, and so joins its room. A management client mints its ticket with exactly this scope.",
+    ),
+    activities: z
+      .array(PresenceActivity)
+      .min(1)
+      .describe("What a participant may announce. The first is what everyone starts as."),
+    maxParticipants: z.number().int().positive().describe("How many participants the room admits at once."),
+    sessionTicketPath: z
+      .string()
+      .nullable()
+      .describe(
+        "Where a signed-in user of the app mints a ticket for this kind, or null when the kind admits management clients only.",
+      ),
+    socketPath: z
+      .string()
+      .min(1)
+      .describe("The socket route, with `:kind` and `:recordId` to fill in — the path as the Worker mounted it."),
+  })
+  .describe("One presence room kind this capability serves, and how to join one of its rooms.");
+export type PresenceRoomDescriptor = z.infer<typeof PresenceRoomDescriptor>;

package/src/presence/http/routes.ts

@@ -0,0 +1,165 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { DurableObjectNamespace } from "@cloudflare/workers-types";
+import type { Context, Hono } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { remedy } from "../../cli/command";
+import { ForbiddenError, InternalError, NotFoundError, PresenceTicketInvalidError } from "../../error/pithyError";
+import { describeRoute } from "../../http/routeSpec";
+import { requireSameOrigin } from "../../http/sameOrigin";
+import { SUBPROTOCOL_HEADER } from "../../http/subprotocol";
+import { validate } from "../../http/validation";
+import {
+  PRESENCE_ROOMS_BINDING,
+  type PresenceDeclaration,
+  type PresenceRoomKind,
+  participantCap,
+  presenceRoomPath,
+  presenceSocketPath,
+  presenceTicketPath,
+  resolveTicketKeys,
+  sessionParticipantName,
+} from "../declaration";
+import { PRESENCE_ADMISSION_HEADER, type PresenceAdmission } from "../room";
+import { mintPresenceTicket, type PresenceTicketRequest, ticketFromOffer, verifyPresenceTicket } from "../ticket";
+import { requireAuth } from "./guard";
+import { type PresenceRoomDescriptor, PresenceTicket } from "./responses";
+import { PresenceRoomParams, PresenceSessionTicketRequest } from "./schemas";
+
+/**
+ * A capability's presence routes, mounted by `createBackend` under the `basePath` it declared:
+ *
+ *   POST {base}/presence/tickets                   → a ticket for a signed-in user   (bearer | session)
+ *   GET  {base}/presence/rooms/:kind/:recordId     → the room's socket               (a ticket)
+ *
+ * The control-plane door is the seam's own, `POST /control-plane/presence/tickets`, because one management
+ * client reaches every capability's rooms through it; both doors answer the same {@link PresenceTicket}.
+ */
+
+/** Find a declared room kind, or the 404 an undeclared one is. */
+export function roomKind(presence: PresenceDeclaration, kind: string): PresenceRoomKind {
+  const room = presence.rooms.find((candidate) => candidate.kind === kind);
+  if (!room) throw new NotFoundError({ message: "That room kind does not exist.", params: { kind } });
+  return room;
+}
+
+/** Mint the ticket a door answers with. */
+export async function issuePresenceTicket(
+  c: Context<PithyHonoEnv>,
+  presence: PresenceDeclaration,
+  request: PresenceTicketRequest,
+): Promise<PresenceTicket> {
+  const keys = await resolveTicketKeys(presence.ticketKey, c.env as Record<string, unknown>);
+  const { ticket, claims } = await mintPresenceTicket(request, keys);
+  return {
+    ticket,
+    expiresAt: new Date(claims.exp * 1000).toISOString(),
+    kind: claims.kind,
+    recordId: claims.recordId,
+    socketPath: presenceRoomPath(presence.basePath, claims.kind, claims.recordId),
+    protocol: "pithy.presence.v1",
+  };
+}
+
+/** The room kinds a declaration serves, as the manifest reports them. */
+export function describePresenceRooms(presence: PresenceDeclaration): PresenceRoomDescriptor[] {
+  return presence.rooms.map((room) => ({
+    kind: room.kind,
+    scope: room.scope,
+    activities: [...room.activities],
+    maxParticipants: participantCap(room),
+    sessionTicketPath: room.session ? presenceTicketPath(presence.basePath) : null,
+    socketPath: presenceSocketPath(presence.basePath),
+  }));
+}
+
+export function registerPresenceRoutes(app: Hono<PithyHonoEnv>, presence: PresenceDeclaration): void {
+  app.post(
+    presenceTicketPath(presence.basePath),
+    describeRoute({
+      summary: "Mint a presence ticket for the signed-in user.",
+      description:
+        "Admits the caller to one room of a kind this capability declares, when the capability's own read permission admits them to the record. Single use, for 60 seconds. Open the socket at `socketPath`, offering `protocol` and `pithy.ticket.<ticket>` in `Sec-WebSocket-Protocol`.",
+      verification: ["bearer", "session"],
+      responses: { 201: PresenceTicket },
+    }),
+    requireAuth(),
+    requireSameOrigin(),
+    validate("json", PresenceSessionTicketRequest),
+    async (c) => {
+      const body = c.req.valid("json");
+      const room = roomKind(presence, body.kind);
+      const auth = c.var.auth;
+      // `requireAuth` ran; this is the type system catching up.
+      if (!auth) throw new InternalError({ detail: "presence session ticket reached without auth" });
+      const grant = room.session ? await room.session(c, body.recordId) : null;
+      if (!grant) {
+        throw new ForbiddenError({
+          message: "You cannot join that room.",
+          detail: room.session
+            ? `session gate refused ${body.kind}/${body.recordId}`
+            : `${body.kind} admits management clients only`,
+        });
+      }
+      const ticket = await issuePresenceTicket(c, presence, {
+        kind: room.kind,
+        recordId: body.recordId,
+        ref: auth.userId,
+        name: sessionParticipantName(grant.name, auth.userId),
+        origin: "session",
+      });
+      return c.json(ticket satisfies PresenceTicket, 201);
+    },
+  );
+
+  app.get(
+    presenceSocketPath(presence.basePath),
+    describeRoute({
+      summary: "Open a presence room's socket.",
+      description:
+        "Send `Upgrade: websocket` and offer `pithy.presence.v1` and `pithy.ticket.<ticket>` in `Sec-WebSocket-Protocol`; the ticket is the credential, minted by either ticket route for this room. The socket receives who is in the room, then joins, leaves and activity changes as they happen. The frames are in the AsyncAPI contract.",
+      verification: "public",
+      responses: {
+        101: { description: "Switches to a WebSocket. The room pushes presence frames as JSON text." },
+      },
+    }),
+    validate("param", PresenceRoomParams),
+    async (c) => {
+      const { kind, recordId } = c.req.valid("param");
+      const room = roomKind(presence, kind);
+      const ticket = ticketFromOffer(c.req.header(SUBPROTOCOL_HEADER));
+      if (ticket === undefined) throw new PresenceTicketInvalidError({ detail: "no single ticket in the offer" });
+      const keys = await resolveTicketKeys(presence.ticketKey, c.env as Record<string, unknown>);
+      const claims = await verifyPresenceTicket(ticket, { kind, recordId }, keys);
+
+      const admission: PresenceAdmission = {
+        kind,
+        recordId,
+        ref: claims.ref,
+        name: claims.name,
+        origin: claims.origin,
+        ticket: { id: claims.id, exp: claims.exp },
+        activities: [...room.activities],
+        maxParticipants: participantCap(room),
+      };
+      // A fresh request, so the admission header is ours whatever the client sent under that name.
+      const request = new Request(c.req.url, c.req.raw);
+      request.headers.set(PRESENCE_ADMISSION_HEADER, JSON.stringify(admission));
+      return roomStub(c, kind, recordId).fetch(request);
+    },
+  );
+}
+
+/** The one room for this record. */
+function roomStub(c: Context<PithyHonoEnv>, kind: string, recordId: string) {
+  const ns = (c.env as Record<string, unknown>)[PRESENCE_ROOMS_BINDING] as DurableObjectNamespace | undefined;
+  if (!ns) {
+    throw new InternalError({
+      message: "Presence is not available right now.",
+      action: `Bind the ${PRESENCE_ROOMS_BINDING} Durable Object. ${remedy("upgrade", {}, { runtime: true }).say((command) => `${command} writes it.`)}`,
+      detail: `no ${PRESENCE_ROOMS_BINDING} binding`,
+    });
+  }
+  return ns.get(ns.idFromName(`${kind}:${recordId}`)) as unknown as { fetch(request: Request): Promise<Response> };
+}

package/src/presence/http/schemas.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { PresenceParticipantName, PresenceParticipantRef } from "../frames";
+import { PresenceRecordId, PresenceRoomKindName } from "../names";
+
+/** The room a ticket is for. */
+const room = {
+  kind: PresenceRoomKindName.describe("The room kind, as the manifest lists it — `support.thread`."),
+  recordId: PresenceRecordId.describe("The record the room is about."),
+};
+
+/** `POST {base}/presence/tickets` — a signed-in user asks to join a room. The participant is that user. */
+export const PresenceSessionTicketRequest = z
+  .object(room)
+  .describe("The room a signed-in user asks a presence ticket for. The participant is the caller.");
+export type PresenceSessionTicketRequest = z.infer<typeof PresenceSessionTicketRequest>;
+
+/**
+ * `POST /control-plane/presence/tickets` — a management client asks to join a room, naming its participant.
+ * The body is signed with the call, which is what makes the participant the client's own claim.
+ */
+export const ControlPlanePresenceTicketRequest = z
+  .object({
+    ...room,
+    participant: z
+      .object({
+        ref: PresenceParticipantRef,
+        name: PresenceParticipantName,
+      })
+      .describe("Who joins: the client's own opaque reference for them, and the name the others see."),
+  })
+  .describe("The room a management client asks a presence ticket for, and who joins it.");
+export type ControlPlanePresenceTicketRequest = z.infer<typeof ControlPlanePresenceTicketRequest>;
+
+/** The socket route's path parameters. */
+export const PresenceRoomParams = z.object(room).describe("The room a presence socket joins: its kind and its record.");
+export type PresenceRoomParams = z.infer<typeof PresenceRoomParams>;

package/src/presence/names.ts

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The three names a presence room is made of, as Zod schemas and nothing else.
+ *
+ * A leaf on purpose: the manifest's room descriptor, the ticket responses and the frames all read these, and
+ * a management client holds those in a browser. So this module imports zod and no other thing — never the
+ * declaration, which names the Hono context a session gate runs in.
+ */
+
+/** A room kind's name: the declaring capability's name, a dot, and a noun — `support.thread`. */
+export const PresenceRoomKindName = z
+  .string()
+  .regex(
+    /^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9_]*)+$/,
+    "A room kind is the capability's name, a dot, and a lowercase noun — `support.thread`.",
+  )
+  .max(64)
+  .describe(
+    "A room kind: the declaring capability's name, a dot, and a noun — `support.thread`. The first segment is always the capability that declares it, so two capabilities cannot declare the same kind.",
+  );
+export type PresenceRoomKindName = z.infer<typeof PresenceRoomKindName>;
+
+/** One activity a participant may announce — `viewing`, `replying`. A closed vocabulary per room kind, never free text. */
+export const PresenceActivity = z
+  .string()
+  .regex(/^[a-z][a-z0-9_]*$/, "An activity is one lowercase word — `viewing`, `replying`.")
+  .max(32)
+  .describe("What a participant is doing in the room — one of the values its room kind declares, never free text.");
+export type PresenceActivity = z.infer<typeof PresenceActivity>;
+
+/**
+ * The record a room is about — the id the declaring capability's own routes take. Constrained to what fits a
+ * path segment and a Durable Object name without escaping.
+ */
+export const PresenceRecordId = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9._:-]+$/, "A record id is letters, digits, `.`, `_`, `:` and `-`.")
+  .describe("The record the room is about — the id the declaring capability's own routes use for it.");
+export type PresenceRecordId = z.infer<typeof PresenceRecordId>;

package/src/presence/room.ts

@@ -0,0 +1,145 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { PresenceOrigin, PresenceParticipant, PresenceParticipantName, PresenceParticipantRef } from "./frames";
+import { PresenceActivity, PresenceRecordId, PresenceRoomKindName } from "./names";
+
+/**
+ * **What a room knows, and where it keeps it: on its sockets, and nowhere else.**
+ *
+ * A room is one Durable Object on the Hibernation API. When it hibernates its memory goes, so everything it
+ * must still know when it wakes rides in each socket's attachment, read back from `getWebSockets()`: the
+ * participant, the version the socket negotiated, the room kind's rules, and which tickets have been spent.
+ * Nothing is written to D1, KV or Durable Object storage. When the last socket closes, the room is gone.
+ *
+ * This module is the logic of that, pure, so it is tested without a runtime; `./durableObject.ts` is the
+ * thin part that reads and writes attachments.
+ */
+
+/** A spent ticket: its id, and when it would have expired anyway — after which remembering it is pointless. */
+export const SpentTicket = z
+  .object({
+    id: z.string().uuid().describe("The spent ticket's id."),
+    exp: z.number().int().describe("When the ticket would have expired, in seconds since the epoch."),
+  })
+  .describe("A ticket a room has redeemed, kept until it would have expired.");
+export type SpentTicket = z.infer<typeof SpentTicket>;
+
+/**
+ * What the Worker's socket route tells the room, on a header only the Worker can set: a verified ticket's
+ * participant, the ticket itself, and the room kind's rules. The room trusts this and nothing a client sent.
+ */
+export const PresenceAdmission = z
+  .object({
+    kind: PresenceRoomKindName.describe("The room kind."),
+    recordId: PresenceRecordId.describe("The record the room is about."),
+    ref: PresenceParticipantRef,
+    name: PresenceParticipantName,
+    origin: PresenceOrigin,
+    ticket: SpentTicket.describe("The ticket this socket is redeeming."),
+    activities: z
+      .array(PresenceActivity)
+      .min(1)
+      .describe("The room kind's declared activities. The first is what a participant starts as."),
+    maxParticipants: z.number().int().positive().describe("The room kind's participant cap."),
+  })
+  .describe("A verified admission, forwarded from the Worker's socket route to the room.");
+export type PresenceAdmission = z.infer<typeof PresenceAdmission>;
+
+/** The server-set header carrying a {@link PresenceAdmission} into the room. */
+export const PRESENCE_ADMISSION_HEADER = "x-pithy-presence-admission";
+
+/** What one socket carries through hibernation. Kept far under the 16,384-byte attachment ceiling. */
+export const PresenceAttachment = z
+  .object({
+    participant: PresenceParticipant.describe("Who this socket is, and what they are doing."),
+    version: z.string().describe("The negotiated subprotocol."),
+    ticket: SpentTicket.describe("The ticket this socket redeemed."),
+    activities: z.array(PresenceActivity).min(1).describe("The room kind's declared activities."),
+    spent: z
+      .array(SpentTicket)
+      .describe("Tickets redeemed by sockets that have since closed, carried so a hibernated room still refuses them."),
+  })
+  .describe("The participant and room state a presence socket keeps across hibernation.");
+export type PresenceAttachment = z.infer<typeof PresenceAttachment>;
+
+/** Every ticket a room still remembers as spent, from its sockets' attachments and its own memory. */
+export function spentTickets(
+  attachments: readonly PresenceAttachment[],
+  remembered: readonly SpentTicket[],
+  nowSeconds: number,
+): Set<string> {
+  const spent = new Set<string>();
+  const add = (ticket: SpentTicket) => {
+    if (ticket.exp > nowSeconds) spent.add(ticket.id);
+  };
+  for (const attachment of attachments) {
+    add(attachment.ticket);
+    for (const ticket of attachment.spent) add(ticket);
+  }
+  for (const ticket of remembered) add(ticket);
+  return spent;
+}
+
+/** Why a room refuses an admission, or `null` to admit. */
+export type AdmissionRefusal = "spent" | "full" | null;
+
+/** Decide one admission against the room as it stands. */
+export function admit(
+  admission: PresenceAdmission,
+  attachments: readonly PresenceAttachment[],
+  remembered: readonly SpentTicket[],
+  nowSeconds: number,
+): AdmissionRefusal {
+  if (spentTickets(attachments, remembered, nowSeconds).has(admission.ticket.id)) return "spent";
+  if (attachments.length >= admission.maxParticipants) return "full";
+  return null;
+}
+
+/**
+ * The most spent tickets one attachment carries. A ticket is honored for 60 seconds, so this is how many
+ * sockets a room may see redeemed and closed within a minute before it starts forgetting the soonest to
+ * expire; at about 60 bytes each it keeps an attachment far under its 16,384-byte ceiling.
+ */
+export const MAX_CARRIED_SPENT = 160;
+
+/** Unexpired, once each, never `own`, and at most {@link MAX_CARRIED_SPENT} — the latest to expire kept. */
+function liveSpent(tickets: readonly SpentTicket[], own: string, nowSeconds: number): SpentTicket[] {
+  const byId = new Map<string, SpentTicket>();
+  for (const ticket of tickets) {
+    if (ticket.exp > nowSeconds && ticket.id !== own) byId.set(ticket.id, ticket);
+  }
+  const live = [...byId.values()];
+  return live.length > MAX_CARRIED_SPENT ? live.sort((a, b) => b.exp - a.exp).slice(0, MAX_CARRIED_SPENT) : live;
+}
+
+/**
+ * The spent list a socket joining a room starts with: what the room remembers in memory, moved onto the
+ * socket, where it survives hibernation. A room's memory is only for the tickets of sockets that closed with
+ * no other socket left to carry them; the moment a socket is there again, it carries them.
+ */
+export function inheritSpent(remembered: readonly SpentTicket[], own: string, nowSeconds: number): SpentTicket[] {
+  return liveSpent(remembered, own, nowSeconds);
+}
+
+/**
+ * The spent list a surviving socket carries once another closes: its own, plus the closing socket's ticket
+ * and everything it carried, less what has expired. Returns `null` when nothing changed, so a room writes no
+ * attachment it does not need to.
+ */
+export function carrySpent(
+  survivor: PresenceAttachment,
+  closing: PresenceAttachment,
+  nowSeconds: number,
+): SpentTicket[] | null {
+  const next = liveSpent([...survivor.spent, closing.ticket, ...closing.spent], survivor.ticket.id, nowSeconds);
+  const same =
+    next.length === survivor.spent.length && next.every((ticket, index) => survivor.spent[index]?.id === ticket.id);
+  return same ? null : next;
+}
+
+/** Whether a client may announce this activity in this room. */
+export function declaresActivity(attachment: PresenceAttachment, activity: string): boolean {
+  return attachment.activities.includes(activity);
+}