@axiom-lattice/protocols 4.1.0 → 4.1.2

package/src/__tests__/ProjectRoomRealtimeProtocol.test.ts

@@ -0,0 +1,185 @@
+import type {
+  ProjectRoomBrokerCapacityError,
+  ProjectRoomBusinessEvent,
+  ProjectRoomBusinessEventDraft,
+  ProjectRoomControlEvent,
+  ProjectRoomEventScope,
+  ProjectRoomEventSubscription,
+  ProjectRoomRealtimeActor,
+} from "../ProjectRoomRealtimeProtocol";
+import { runInNewContext } from "node:vm";
+import {
+  isProjectRoomEventId,
+  parseProjectRoomEventId,
+  ProjectRoomCursorError,
+  toProjectRoomPublicBotMembership,
+  toProjectRoomPublicMembership,
+  toProjectRoomPublicMessage,
+} from "../ProjectRoomRealtimeProtocol";
+
+const message: ProjectRoomBusinessEvent = {
+  id: "550e8400-e29b-41d4-a716-446655440000:1",
+  type: "message.created",
+  occurredAt: "2026-09-03T00:00:00.000Z",
+  data: {
+    message: {
+      id: "message-1",
+      roomId: "room-1",
+      author: { type: "bot", membershipId: "bot-1" },
+      content: { type: "text", text: "Complete" },
+      mentions: [],
+      source: "agent",
+      createdAt: "2026-09-03T00:00:00.000Z",
+    },
+  },
+};
+
+const draft: ProjectRoomBusinessEventDraft = {
+  type: "task.changed",
+  occurredAt: "2026-09-03T00:00:01.000Z",
+  data: {
+    taskId: "task-1",
+    status: "completed",
+    ownerMembershipId: "bot-1",
+    updatedAt: "2026-09-03T00:00:01.000Z",
+  },
+};
+
+const control: ProjectRoomControlEvent = {
+  type: "resync",
+  data: { reason: "SERVER_RESTART" },
+};
+const scope: ProjectRoomEventScope = { tenantId: "tenant-1", roomId: "room-1", projectId: "project-1" };
+const actor: ProjectRoomRealtimeActor = {
+  tenantId: "tenant-1",
+  userId: "user-1",
+  projectId: "project-1",
+  tokenExpiresAt: 1_788_393_600_000,
+};
+const subscription: ProjectRoomEventSubscription = {
+  replay: [message],
+  headEventId: message.id,
+  unsubscribe: () => undefined,
+};
+
+// @ts-expect-error unsupported business event types are not public protocol values
+const dispatchEvent: ProjectRoomBusinessEventDraft = { type: "dispatch.changed", data: {} };
+// @ts-expect-error control events never carry replay IDs
+const identifiedControl: ProjectRoomControlEvent = { ...control, id: "epoch:1" };
+const internalMessage: ProjectRoomBusinessEvent = {
+  ...message,
+  data: {
+    // @ts-expect-error internal assistant identity is not public message data
+    message: { ...message.data.message, assistantId: "assistant-1" },
+  },
+};
+// @ts-expect-error event IDs are canonical strings, not numbers
+const numericEventId: ProjectRoomBusinessEvent = { ...message, id: 1 };
+
+describe("Project Room realtime protocol", () => {
+  it("defines the exact public business, control, broker, and actor surfaces", () => {
+    expect([message.type, draft.type, control.type]).toEqual([
+      "message.created",
+      "task.changed",
+      "resync",
+    ]);
+    expect(JSON.stringify(message)).not.toContain("assistantId");
+    expect(JSON.stringify(message)).not.toContain("sourceId");
+    expect(scope).toEqual({ tenantId: "tenant-1", roomId: "room-1", projectId: "project-1" });
+    expect(actor).toEqual({
+      tenantId: "tenant-1",
+      userId: "user-1",
+      projectId: "project-1",
+      tokenExpiresAt: 1_788_393_600_000,
+    });
+    expect(subscription.headEventId).toBe(message.id);
+    expect(dispatchEvent).toBeDefined();
+    expect(identifiedControl).toBeDefined();
+    expect(internalMessage).toBeDefined();
+    expect(numericEventId).toBeDefined();
+  });
+
+  it("maps descriptor-safe internal records to public DTOs", () => {
+    const internalMessage = {
+      id: "message-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1",
+      roomId: "room-1", author: { type: "bot", membershipId: "bot-1", assistantId: "assistant-1" },
+      content: { type: "text", text: "Complete" }, mentions: [], source: "agent", sourceId: "reply-1",
+      idempotencyKey: "idem-1", createdAt: new Date("2026-09-03T00:00:00.000Z"),
+    };
+    const internalMembership = {
+      id: "membership-1", tenantId: "tenant-1", projectId: "project-1", userId: "user-1",
+      role: "viewer", status: "active", joinedAt: new Date("2026-09-03T00:00:00.000Z"),
+      updatedAt: new Date("2026-09-03T00:00:01.000Z"),
+    };
+    const internalBot = {
+      id: "bot-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", roomId: "room-1",
+      assistantId: "assistant-1", role: "specialist", title: "Worker", responsibility: "Build",
+      mentionName: "worker", status: "active", roomThreadId: "thread-1",
+      joinedAt: new Date("2026-09-03T00:00:00.000Z"), updatedAt: new Date("2026-09-03T00:00:01.000Z"),
+    };
+    expect(toProjectRoomPublicMessage(internalMessage)).toEqual(message.data.message);
+    expect(toProjectRoomPublicMembership(internalMembership)).toEqual({
+      id: "membership-1", userId: "user-1", role: "viewer", status: "active",
+      joinedAt: "2026-09-03T00:00:00.000Z", updatedAt: "2026-09-03T00:00:01.000Z",
+    });
+    expect(toProjectRoomPublicBotMembership(internalBot)).toEqual({
+      id: "bot-1", role: "specialist", title: "Worker", responsibility: "Build", mentionName: "worker",
+      status: "active", joinedAt: "2026-09-03T00:00:00.000Z", updatedAt: "2026-09-03T00:00:01.000Z",
+    });
+    expect(JSON.stringify(toProjectRoomPublicMessage(internalMessage))).not.toMatch(
+      /tenantId|workspaceId|projectId|assistantId|thread|idempotency|sourceId/,
+    );
+  });
+
+  it("rejects malformed, accessor-backed, and extra internal records", () => {
+    expect(toProjectRoomPublicMessage({})).toBeUndefined();
+    expect(toProjectRoomPublicMembership({ id: "membership-1", extra: true })).toBeUndefined();
+    expect(toProjectRoomPublicBotMembership({})).toBeUndefined();
+    const accessor = { get id() { return "message-1"; } };
+    expect(toProjectRoomPublicMessage(accessor)).toBeUndefined();
+  });
+
+  it("reconstructs strict mention DTOs and rejects sensitive mention fields", () => {
+    const value = {
+      id: "message-1", tenantId: "tenant-1", workspaceId: "workspace-1", projectId: "project-1", roomId: "room-1",
+      author: { type: "human", userId: "user-1" }, content: { type: "text", text: "hello" }, source: "user", createdAt: new Date("2026-09-03T00:00:00.000Z"),
+      mentions: [{ type: "team" }, { type: "bot", membershipId: "bot-1" }],
+    };
+    const result = toProjectRoomPublicMessage(value);
+    expect(result?.mentions).toEqual([{ type: "team" }, { type: "bot", membershipId: "bot-1" }]);
+    expect(result?.mentions[0]).not.toBe(value.mentions[0]);
+    expect(toProjectRoomPublicMessage({ ...value, mentions: [{ type: "team", tenantId: "secret" }] })).toBeUndefined();
+    let reads = 0;
+    const accessor = Object.defineProperty({ type: "team" }, "type", { enumerable: true, get: () => { reads += 1; return "team"; } });
+    expect(toProjectRoomPublicMessage({ ...value, mentions: [accessor] })).toBeUndefined();
+    expect(reads).toBe(0);
+  });
+
+  it("parses only canonical safe-integer event IDs", () => {
+    expect(parseProjectRoomEventId(message.id)).toEqual({
+      epoch: "550e8400-e29b-41d4-a716-446655440000",
+      sequence: 1,
+    });
+    expect(isProjectRoomEventId(message.id)).toBe(true);
+    expect(isProjectRoomEventId("epoch:1")).toBe(false);
+    expect(isProjectRoomEventId("550E8400-E29B-41D4-A716-446655440000:1")).toBe(false);
+    expect(isProjectRoomEventId(`${message.id}x`)).toBe(false);
+    expect(isProjectRoomEventId(`${message.id.split(":")[0]}:1.0`)).toBe(false);
+    expect(isProjectRoomEventId(`${message.id.split(":")[0]}:${Number.MAX_SAFE_INTEGER + 1}`)).toBe(false);
+    expect(parseProjectRoomEventId("not-an-event-id")).toBeUndefined();
+    expect(isProjectRoomEventId(runInNewContext(`"${message.id}"`))).toBe(true);
+    expect(isProjectRoomEventId(runInNewContext(`new String("${message.id}")`))).toBe(false);
+  });
+
+  it("exposes typed cursor and capacity errors", () => {
+    const cursorError = new ProjectRoomCursorError("CURSOR_EXPIRED");
+    const capacityError: ProjectRoomBrokerCapacityError = {
+      name: "ProjectRoomBrokerCapacityError",
+      message: "sequence exhausted",
+      code: "PROJECT_ROOM_EVENT_SEQUENCE_EXHAUSTED",
+    };
+    expect(cursorError).toBeInstanceOf(Error);
+    expect(cursorError.code).toBe("CURSOR_EXPIRED");
+    expect(capacityError.code).toBe("PROJECT_ROOM_EVENT_SEQUENCE_EXHAUSTED");
+  });
+});

package/src/__tests__/ProjectRoomStores.test.ts

@@ -0,0 +1,363 @@
+import type {
+  ProjectBotMembership,
+  ProjectBotMembershipStore,
+  ProjectMembership,
+  ProjectMembershipStore,
+  ProjectRoom,
+  ProjectRoomMessage,
+  ProjectRoomMessageCursor,
+  ProjectRoomMessageStore,
+  ProjectRoomStore,
+} from "../index";
+
+type RoomInput = Parameters<ProjectRoomStore["ensureMainRoom"]>[0];
+type RoomLookupResult = Awaited<ReturnType<ProjectRoomStore["getMainRoom"]>>;
+type MembershipInput = Parameters<ProjectMembershipStore["create"]>[0];
+type InitialOwnerInput = Parameters<ProjectMembershipStore["createInitialOwner"]>[0];
+type InitialOwnerResult = Awaited<ReturnType<ProjectMembershipStore["createInitialOwner"]>>;
+type RoleInput = Parameters<ProjectMembershipStore["updateRole"]>[0];
+type RoleResult = Awaited<ReturnType<ProjectMembershipStore["updateRole"]>>;
+type RemoveInput = Parameters<ProjectMembershipStore["remove"]>[0];
+type RemoveResult = Awaited<ReturnType<ProjectMembershipStore["remove"]>>;
+type BotInput = Parameters<ProjectBotMembershipStore["save"]>[0];
+type BotSaveResult = Awaited<ReturnType<ProjectBotMembershipStore["save"]>>;
+type BotUpdateInput = Parameters<ProjectBotMembershipStore["update"]>[0];
+type BotUpdateResult = Awaited<ReturnType<ProjectBotMembershipStore["update"]>>;
+type MessageInput = Parameters<ProjectRoomMessageStore["create"]>[0];
+type IdempotentMessageInput = Parameters<ProjectRoomMessageStore["createIdempotent"]>[0];
+type MessageListInput = Parameters<ProjectRoomMessageStore["list"]>[0];
+
+const room: ProjectRoom = {
+  id: "room-1",
+  tenantId: "tenant-1",
+  workspaceId: "workspace-1",
+  projectId: "project-1",
+  type: "main",
+  name: "Main room",
+  createdAt: new Date(0),
+  updatedAt: new Date(0),
+};
+
+const membership: ProjectMembership = {
+  id: "membership-1",
+  tenantId: "tenant-1",
+  projectId: "project-1",
+  userId: "user-1",
+  role: "owner",
+  status: "active",
+  joinedAt: new Date(0),
+  updatedAt: new Date(0),
+};
+
+const botMembership: ProjectBotMembership = {
+  id: "bot-membership-1",
+  tenantId: "tenant-1",
+  workspaceId: "workspace-1",
+  projectId: "project-1",
+  roomId: "room-1",
+  assistantId: "assistant-1",
+  role: "coordinator",
+  title: "Coordinator",
+  mentionName: "coordinator",
+  status: "active",
+  roomThreadId: "thread-1",
+  joinedAt: new Date(0),
+  updatedAt: new Date(0),
+};
+
+const message: ProjectRoomMessage = {
+  id: "message-1",
+  tenantId: "tenant-1",
+  workspaceId: "workspace-1",
+  projectId: "project-1",
+  roomId: "room-1",
+  author: { type: "system" },
+  content: { type: "text", text: "Room ready" },
+  mentions: [],
+  source: "system",
+  createdAt: new Date(0),
+};
+
+function assertNever(value: never): never {
+  throw new Error(`Unexpected protocol result: ${String(value)}`);
+}
+
+function expectInitialOwnerResult(result: InitialOwnerResult, expected: InitialOwnerResult["kind"]): void {
+  switch (result.kind) {
+    case "created":
+    case "existing":
+      expect(result.kind).toBe(expected);
+      expect(result.membership).toEqual(expect.objectContaining({ projectId: "project-1" }));
+      return;
+    case "already_initialized":
+      expect(result.kind).toBe(expected);
+      return;
+    default:
+      assertNever(result);
+  }
+}
+
+function expectRoleResult(result: RoleResult, expected: RoleResult["kind"]): void {
+  switch (result.kind) {
+    case "updated":
+      expect(result.kind).toBe(expected);
+      expect(result.membership).toEqual(expect.objectContaining({ id: "membership-1" }));
+      return;
+    case "removed":
+      expect(result.kind).toBe(expected);
+      return;
+    case "not_found":
+    case "conflict":
+    case "last_owner":
+      expect(result.kind).toBe(expected);
+      return;
+    default:
+      assertNever(result);
+  }
+}
+
+function expectRemoveResult(result: RemoveResult, expected: RemoveResult["kind"]): void {
+  switch (result.kind) {
+    case "updated":
+      expect(result.kind).toBe(expected);
+      return;
+    case "removed":
+      expect(result.kind).toBe(expected);
+      expect(result.membership).toEqual(expect.objectContaining({ id: "membership-1", status: "removed" }));
+      return;
+    case "not_found":
+    case "conflict":
+    case "last_owner":
+      expect(result.kind).toBe(expected);
+      return;
+    default:
+      assertNever(result);
+  }
+}
+
+function expectBotSaveResult(result: BotSaveResult, expected: BotSaveResult["kind"]): void {
+  switch (result.kind) {
+    case "created":
+    case "updated":
+    case "reactivated":
+      expect(result.kind).toBe(expected);
+      expect(result.membership).toEqual(expect.objectContaining({ projectId: "project-1" }));
+      return;
+    case "coordinator_conflict":
+    case "mention_conflict":
+      expect(result.kind).toBe(expected);
+      return;
+    default:
+      assertNever(result);
+  }
+}
+
+function expectBotUpdateResult(result: BotUpdateResult, expected: BotUpdateResult["kind"]): void {
+  switch (result.kind) {
+    case "updated":
+      expect(result.kind).toBe(expected);
+      expect(result.membership).toEqual(expect.objectContaining({ id: "bot-membership-1" }));
+      return;
+    case "not_found":
+    case "conflict":
+    case "coordinator_conflict":
+    case "mention_conflict":
+      expect(result.kind).toBe(expected);
+      return;
+    default:
+      assertNever(result);
+  }
+}
+
+class FakeProjectRoomStore implements ProjectRoomStore {
+  async ensureMainRoom(input: RoomInput): Promise<Awaited<ReturnType<ProjectRoomStore["ensureMainRoom"]>>> {
+    return { ...room, ...input };
+  }
+
+  async getMainRoom(...args: Parameters<ProjectRoomStore["getMainRoom"]>): Promise<RoomLookupResult> {
+    const [tenantId, projectId] = args;
+    return tenantId === "tenant-1" && projectId === "project-1" ? room : null;
+  }
+}
+
+class FakeProjectMembershipStore implements ProjectMembershipStore {
+  async list(...args: Parameters<ProjectMembershipStore["list"]>): Promise<Awaited<ReturnType<ProjectMembershipStore["list"]>>> {
+    const [tenantId, projectId] = args;
+    return tenantId === "tenant-1" && projectId === "project-1" ? [membership] : [];
+  }
+
+  async findByUser(...args: Parameters<ProjectMembershipStore["findByUser"]>): Promise<Awaited<ReturnType<ProjectMembershipStore["findByUser"]>>> {
+    const [tenantId, projectId, userId] = args;
+    return tenantId === "tenant-1" && projectId === "project-1" && userId === "user-1" ? membership : null;
+  }
+
+  async create(input: MembershipInput): Promise<Awaited<ReturnType<ProjectMembershipStore["create"]>>> {
+    return { ...input, joinedAt: new Date(0), updatedAt: new Date(0) };
+  }
+
+  async createInitialOwner(input: InitialOwnerInput): Promise<InitialOwnerResult> {
+    if (input.id === "already-initialized") return { kind: "already_initialized" };
+    return { kind: input.id === "existing" ? "existing" : "created", membership: { ...membership, ...input } };
+  }
+
+  async updateRole(input: RoleInput): Promise<RoleResult> {
+    if (input.id === "not-found") return { kind: "not_found" };
+    if (input.id === "conflict") return { kind: "conflict" };
+    if (input.id === "last-owner") return { kind: "last_owner" };
+    return { kind: "updated", membership };
+  }
+
+  async remove(input: RemoveInput): Promise<RemoveResult> {
+    if (input.id === "not-found") return { kind: "not_found" };
+    if (input.id === "conflict") return { kind: "conflict" };
+    if (input.id === "last-owner") return { kind: "last_owner" };
+    return { kind: "removed", membership: { ...membership, status: "removed" } };
+  }
+}
+
+class FakeProjectBotMembershipStore implements ProjectBotMembershipStore {
+  async list(...args: Parameters<ProjectBotMembershipStore["list"]>): Promise<Awaited<ReturnType<ProjectBotMembershipStore["list"]>>> {
+    const [tenantId, projectId] = args;
+    return tenantId === "tenant-1" && projectId === "project-1" ? [botMembership] : [];
+  }
+
+  async findById(...args: Parameters<ProjectBotMembershipStore["findById"]>): Promise<Awaited<ReturnType<ProjectBotMembershipStore["findById"]>>> {
+    const [tenantId, id] = args;
+    return tenantId === "tenant-1" && id === "bot-membership-1" ? botMembership : null;
+  }
+
+  async findByAssistant(...args: Parameters<ProjectBotMembershipStore["findByAssistant"]>): Promise<Awaited<ReturnType<ProjectBotMembershipStore["findByAssistant"]>>> {
+    const [tenantId, projectId, assistantId] = args;
+    return tenantId === "tenant-1" && projectId === "project-1" && assistantId === "assistant-1" ? botMembership : null;
+  }
+
+  async save(input: BotInput): Promise<BotSaveResult> {
+    if (input.id === "coordinator-conflict") return { kind: "coordinator_conflict" };
+    if (input.id === "mention-conflict") return { kind: "mention_conflict" };
+    const kind = input.id === "updated" ? "updated" : input.id === "reactivated" ? "reactivated" : "created";
+    return { kind, membership: { ...input, joinedAt: new Date(0), updatedAt: new Date(0) } };
+  }
+
+  async update(input: BotUpdateInput): Promise<BotUpdateResult> {
+    if (input.id === "not-found") return { kind: "not_found" };
+    if (input.id === "conflict") return { kind: "conflict" };
+    if (input.id === "coordinator-conflict") return { kind: "coordinator_conflict" };
+    if (input.id === "mention-conflict") return { kind: "mention_conflict" };
+    return { kind: "updated", membership: { ...botMembership, ...input.patch } };
+  }
+}
+
+class FakeProjectRoomMessageStore implements ProjectRoomMessageStore {
+  async create(input: MessageInput): Promise<Awaited<ReturnType<ProjectRoomMessageStore["create"]>>> {
+    return { ...input, createdAt: new Date(0) };
+  }
+
+  async createIdempotent(input: IdempotentMessageInput): Promise<Awaited<ReturnType<ProjectRoomMessageStore["createIdempotent"]>>> {
+    return { ...input, createdAt: new Date(0) };
+  }
+
+  async list(input: MessageListInput): Promise<Awaited<ReturnType<ProjectRoomMessageStore["list"]>>> {
+    return input.tenantId === "tenant-1" && input.roomId === "room-1" && input.limit > 0 ? [message] : [];
+  }
+
+  async findById(...args: Parameters<ProjectRoomMessageStore["findById"]>): Promise<Awaited<ReturnType<ProjectRoomMessageStore["findById"]>>> {
+    const [tenantId, id] = args;
+    return tenantId === "tenant-1" && id === "message-1" ? message : null;
+  }
+}
+
+describe("ProjectRoomStore", () => {
+  const store: ProjectRoomStore = new FakeProjectRoomStore();
+
+  it("creates and looks up the main room, including a missing room", async () => {
+    expect(await store.ensureMainRoom(room)).toEqual(room);
+    expect(await store.getMainRoom("tenant-1", "project-1")).toEqual(room);
+    expect(await store.getMainRoom("tenant-1", "missing-project")).toBeNull();
+  });
+});
+
+describe("ProjectMembershipStore", () => {
+  const store: ProjectMembershipStore = new FakeProjectMembershipStore();
+
+  it("lists, creates, and returns nullable user membership lookups", async () => {
+    expect(await store.list("tenant-1", "project-1")).toEqual([membership]);
+    expect(await store.findByUser("tenant-1", "project-1", "user-1")).toEqual(membership);
+    expect(await store.findByUser("tenant-1", "project-1", "missing-user")).toBeNull();
+    expect(await store.create(membership)).toEqual(membership);
+  });
+
+  it("distinguishes initial-owner outcomes", async () => {
+    expectInitialOwnerResult(await store.createInitialOwner(membership), "created");
+    expectInitialOwnerResult(await store.createInitialOwner({ ...membership, id: "existing" }), "existing");
+    expectInitialOwnerResult(await store.createInitialOwner({ ...membership, id: "already-initialized" }), "already_initialized");
+  });
+
+  it("returns every role update result", async () => {
+    const cases: ReadonlyArray<readonly [string, RoleResult["kind"]]> = [
+      ["membership-1", "updated"], ["not-found", "not_found"], ["conflict", "conflict"], ["last-owner", "last_owner"],
+    ];
+    for (const [id, expected] of cases) {
+      expectRoleResult(await store.updateRole({ tenantId: "tenant-1", id, role: "admin", expectedUpdatedAt: new Date(0) }), expected);
+    }
+  });
+
+  it("returns every membership removal result", async () => {
+    const cases: ReadonlyArray<readonly [string, RemoveResult["kind"]]> = [
+      ["membership-1", "removed"], ["not-found", "not_found"], ["conflict", "conflict"], ["last-owner", "last_owner"],
+    ];
+    for (const [id, expected] of cases) {
+      expectRemoveResult(await store.remove({ tenantId: "tenant-1", id, expectedUpdatedAt: new Date(0) }), expected);
+    }
+  });
+});
+
+describe("ProjectBotMembershipStore", () => {
+  const store: ProjectBotMembershipStore = new FakeProjectBotMembershipStore();
+
+  it("lists memberships and covers nullable bot lookups", async () => {
+    expect(await store.list("tenant-1", "project-1")).toEqual([botMembership]);
+    expect(await store.findById("tenant-1", "bot-membership-1")).toEqual(botMembership);
+    expect(await store.findById("tenant-1", "missing-bot")).toBeNull();
+    expect(await store.findByAssistant("tenant-1", "project-1", "assistant-1")).toEqual(botMembership);
+    expect(await store.findByAssistant("tenant-1", "project-1", "missing-assistant")).toBeNull();
+  });
+
+  it("returns every save result", async () => {
+    const cases: ReadonlyArray<readonly [string, BotSaveResult["kind"]]> = [
+      ["bot-membership-1", "created"],
+      ["updated", "updated"],
+      ["reactivated", "reactivated"],
+      ["coordinator-conflict", "coordinator_conflict"],
+      ["mention-conflict", "mention_conflict"],
+    ];
+    for (const [id, expected] of cases) {
+      expectBotSaveResult(await store.save({ ...botMembership, id }), expected);
+    }
+  });
+
+  it("returns every update result", async () => {
+    const cases: ReadonlyArray<readonly [string, BotUpdateResult["kind"]]> = [
+      ["bot-membership-1", "updated"],
+      ["not-found", "not_found"],
+      ["conflict", "conflict"],
+      ["coordinator-conflict", "coordinator_conflict"],
+      ["mention-conflict", "mention_conflict"],
+    ];
+    for (const [id, expected] of cases) {
+      expectBotUpdateResult(await store.update({ tenantId: "tenant-1", id, patch: { title: "Lead" }, expectedUpdatedAt: new Date(0) }), expected);
+    }
+  });
+});
+
+describe("ProjectRoomMessageStore", () => {
+  const store: ProjectRoomMessageStore = new FakeProjectRoomMessageStore();
+
+  it("creates, idempotently creates, pages, and looks up messages", async () => {
+    const cursor: ProjectRoomMessageCursor = { createdAt: message.createdAt, id: message.id };
+    expect(await store.create(message)).toEqual(message);
+    expect(await store.createIdempotent({ ...message, idempotencyKey: "key-1" })).toEqual({ ...message, idempotencyKey: "key-1" });
+    expect(await store.list({ tenantId: "tenant-1", roomId: "room-1", before: cursor, limit: 10 })).toEqual([message]);
+    expect(await store.findById("tenant-1", "message-1")).toEqual(message);
+    expect(await store.findById("tenant-1", "missing-message")).toBeNull();
+  });
+});

package/src/__tests__/ProjectTaskProtocol.test.ts

@@ -0,0 +1,29 @@
+import type { ProjectTaskThreadMetadata } from "../ProjectRoomProtocol";
+
+describe("Project Task protocol types", () => {
+  it("models task execution thread metadata", () => {
+    const metadata: ProjectTaskThreadMetadata = {
+      source: "project_task",
+      kind: "task_execution",
+      workspaceId: "workspace-1",
+      projectId: "project-1",
+      roomId: "room-1",
+      membershipId: "member-1",
+      assistantId: "agent-1",
+      taskId: "task-1",
+      parentTaskId: "parent-1",
+    };
+
+    expect(metadata).toEqual({
+      source: "project_task",
+      kind: "task_execution",
+      workspaceId: "workspace-1",
+      projectId: "project-1",
+      roomId: "room-1",
+      membershipId: "member-1",
+      assistantId: "agent-1",
+      taskId: "task-1",
+      parentTaskId: "parent-1",
+    });
+  });
+});

package/src/__tests__/TaskWorkItemProtocol.test.ts

@@ -0,0 +1,111 @@
+import {
+  EXECUTION_RESULT_EVENT_KEY_PATTERN_SOURCE,
+  MAX_PENDING_EXECUTION_RESULTS_LIMIT,
+  PROJECT_TASK_LIFECYCLE_ACTIONS,
+  ProjectTaskStoreUnsupportedError,
+  isExecutionResultEventKey,
+  requireProjectTaskWorkItemStore,
+} from "../TaskWorkItemProtocol";
+import { readFileSync } from "node:fs";
+import type {
+  TaskWorkItem,
+  TaskWorkItemStore,
+} from "../TaskWorkItemProtocol";
+
+class LegacyTaskWorkItemStore implements TaskWorkItemStore {
+  async create(): Promise<TaskWorkItem> {
+    throw new Error("fixture only");
+  }
+
+  async list(): Promise<TaskWorkItem[]> {
+    return [];
+  }
+
+  async findByEventKey(): Promise<TaskWorkItem | null> {
+    return null;
+  }
+
+  async createIfAbsentByEventKey(): Promise<TaskWorkItem> {
+    throw new Error("fixture only");
+  }
+}
+
+const legacyStore: TaskWorkItemStore = new LegacyTaskWorkItemStore();
+
+describe("execution result event keys", () => {
+  it("runs the legacy-store compatibility fixture during normal package tests", () => {
+    const packageJson = JSON.parse(readFileSync("package.json", "utf8")) as {
+      scripts?: Record<string, string>;
+    };
+
+    expect(packageJson.scripts?.["typecheck:compat"]).toBe(
+      "tsc -p tsconfig.type-tests.json",
+    );
+    expect(packageJson.scripts?.test).toBe("jest && pnpm typecheck:compat");
+  });
+
+  it("keeps stores without the optimized pending query protocol-compatible", () => {
+    expect(legacyStore).toBeInstanceOf(LegacyTaskWorkItemStore);
+  });
+
+  it("coexists with Project Task lifecycle protocol constants", () => {
+    expect(PROJECT_TASK_LIFECYCLE_ACTIONS).toEqual([
+      "in_progress",
+      "interrupted",
+      "failed",
+      "completed",
+      "cancelled",
+      "reassigned",
+    ]);
+    expect(isExecutionResultEventKey("execution-result:thread:1")).toBe(true);
+    expect(MAX_PENDING_EXECUTION_RESULTS_LIMIT).toBe(1_000);
+  });
+
+  it("reports all missing Project Task store methods", () => {
+    expect(() => requireProjectTaskWorkItemStore(legacyStore)).toThrow(
+      expect.objectContaining({
+        code: "PROJECT_TASK_STORE_UNSUPPORTED",
+        missingMethods: ["createIfTaskSnapshot", "listProjectLifecycleEvents"],
+      }),
+    );
+
+    try {
+      requireProjectTaskWorkItemStore(legacyStore);
+      throw new Error("Expected Project Task store refinement to fail");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ProjectTaskStoreUnsupportedError);
+    }
+  });
+
+  it("returns a complete Project Task store unchanged", () => {
+    const projectStore = Object.assign(new LegacyTaskWorkItemStore(), {
+      createIfTaskSnapshot: async () => null,
+      listProjectLifecycleEvents: async () => [],
+    });
+
+    expect(requireProjectTaskWorkItemStore(projectStore)).toBe(projectStore);
+  });
+
+  it.each([
+    "execution-result:550e8400-e29b-41d4-a716-446655440000",
+    "execution-result:thread.segment_1:attempt-2",
+  ])("accepts canonical ASCII key %s", (value) => {
+    expect(isExecutionResultEventKey(value)).toBe(true);
+    expect(new RegExp(EXECUTION_RESULT_EVENT_KEY_PATTERN_SOURCE).test(value)).toBe(true);
+  });
+
+  it.each([
+    undefined,
+    1,
+    "execution-result:",
+    "wrong-prefix:value",
+    "execution-result:internal space",
+    "execution-result:non-breaking\u00a0space",
+    "execution-result:next-line\u0085",
+    "execution-result:em-space\u2003",
+    "execution-result:invalid/punctuation",
+    "execution-result:query?value",
+  ])("rejects non-canonical key %p", (value) => {
+    expect(isExecutionResultEventKey(value)).toBe(false);
+  });
+});