@axiom-lattice/protocols 4.1.0 → 4.1.2

package/src/TaskStoreProtocol.ts

@@ -366,9 +366,10 @@ export interface TaskListFilter {
   workspaceId?: string;
 
   /**
-   * Filter by project ID
+   * Filter by project ID. `null` matches only absent, empty, or `default` projects;
+   * `undefined` applies no project predicate.
    */
-  projectId?: string;
+  projectId?: string | null;
 
   /**
    * Filter by parent task ID
@@ -396,6 +397,42 @@ export interface TaskListFilter {
   offset?: number;
 }
 
+/**
+ * Exact scope and pagination for tasks that depend on another project task.
+ */
+export interface TaskDependentListQuery {
+  /** Tenant identifier. */
+  tenantId: string;
+  /** Workspace identifier. */
+  workspaceId: string;
+  /** Project identifier. */
+  projectId: string;
+  /** Identifier that must occur as a string in the dependency array. */
+  dependencyTaskId: string;
+  /** Nonempty statuses eligible for recovery. */
+  statuses: TaskItem["status"][];
+  /** Maximum rows to return, from 1 through 100. */
+  limit: number;
+  /** Number of matching rows to skip. */
+  offset: number;
+}
+
+/** Exact mutable identity captured before a trusted task mutation. */
+export interface TaskMutationSnapshot {
+  /** Status observed during authorization. */
+  status: TaskItem["status"];
+  /** Update timestamp observed during authorization. */
+  updatedAt: Date | string;
+  /** Owner kind observed during authorization. */
+  ownerType: TaskItem["ownerType"];
+  /** Owner identifier observed during authorization. */
+  ownerId: string;
+  /** Exact workspace scope observed during authorization. */
+  workspaceId: string | null;
+  /** Exact Project scope observed during authorization. */
+  projectId: string | null;
+}
+
 /**
  * TaskStore interface
  * Provides CRUD operations for task data
@@ -423,6 +460,14 @@ export interface TaskStore {
    */
   list(filter: TaskListFilter): Promise<TaskItem[]>;
 
+  /**
+   * Lists exact project tasks that depend on another task.
+   *
+   * @param query Exact scope, statuses, and bounded offset page.
+   * @returns Matching tasks ordered by creation time and ID descending.
+   */
+  listDependents(query: TaskDependentListQuery): Promise<TaskItem[]>;
+
   /**
    * Update an existing task
    * @param tenantId Tenant identifier
@@ -473,6 +518,22 @@ export interface TaskStore {
     expectedUpdatedAt: Date | string,
   ): Promise<TaskItem | null>;
 
+  /**
+   * Atomically updates a task only while its full trusted mutation snapshot matches.
+   *
+   * @param tenantId Tenant identifier.
+   * @param id Task identifier.
+   * @param updates Partial task data to update.
+   * @param snapshot Exact status, timestamp, owner, and Project scope snapshot.
+   * @returns Updated task, or `null` when any snapshot field differs.
+   */
+  updateIfSnapshot(
+    tenantId: string,
+    id: string,
+    updates: UpdateTaskRequest,
+    snapshot: TaskMutationSnapshot,
+  ): Promise<TaskItem | null>;
+
   /**
    * Atomically updates a child only when both child and parent snapshots match.
    *
@@ -495,6 +556,9 @@ export interface TaskStore {
     expectedParentUpdatedAt: Date | string,
   ): Promise<TaskItem | null>;
 
+  /** Atomically deletes a task only while its full trusted mutation snapshot matches. */
+  deleteIfSnapshot(tenantId: string, id: string, snapshot: TaskMutationSnapshot): Promise<boolean>;
+
   /**
    * Atomically update a task unless its current status is blocked.
    *

package/src/TaskWorkItemProtocol.ts

@@ -1,3 +1,5 @@
+import type { TaskMutationSnapshot } from "./TaskStoreProtocol";
+
 /**
  * TaskWorkItemProtocol
  *
@@ -56,10 +58,107 @@ export interface TaskWorkItemListFilter {
   offset?: number;
 }
 
+/** Canonical prefix for public task execution-result event identities. */
+export const EXECUTION_RESULT_EVENT_KEY_PREFIX = "execution-result:";
+
+/**
+ * Portable regular-expression source for canonical execution-result event keys.
+ *
+ * The entire key is the literal `execution-result:` prefix followed by a nonempty
+ * suffix containing only ASCII letters, digits, period, underscore, colon, or hyphen.
+ * Colon is intentionally allowed so callers can compose structured suffixes.
+ */
+export const EXECUTION_RESULT_EVENT_KEY_PATTERN_SOURCE =
+  "^execution-result:[A-Za-z0-9._:-]+$";
+
+/** Compiled runtime expression for canonical execution-result event keys. */
+export const EXECUTION_RESULT_EVENT_KEY_PATTERN =
+  new RegExp(EXECUTION_RESULT_EVENT_KEY_PATTERN_SOURCE);
+
+/** Maximum pending execution-result rows accepted by one store query. */
+export const MAX_PENDING_EXECUTION_RESULTS_LIMIT = 1_000;
+
+/**
+ * Determines whether a runtime value is a canonical execution-result event key.
+ *
+ * @param value Runtime value to validate.
+ * @returns True only for the portable canonical ASCII grammar.
+ */
+export function isExecutionResultEventKey(value: unknown): value is string {
+  return typeof value === "string" && EXECUTION_RESULT_EVENT_KEY_PATTERN.test(value);
+}
+
+/** Canonical lifecycle actions projected into Project Rooms. */
+export const PROJECT_TASK_LIFECYCLE_ACTIONS = [
+  "in_progress", "interrupted", "failed", "completed", "cancelled", "reassigned",
+] as const;
+
+/** Lifecycle action eligible for Project Room projection. */
+export type ProjectTaskLifecycleAction = typeof PROJECT_TASK_LIFECYCLE_ACTIONS[number];
+
+/** Exclusive cursor for deterministic project lifecycle pagination. */
+export interface ProjectLifecycleEventCursor {
+  /** Creation timestamp of the last returned event. */
+  createdAt: Date;
+  /** Identifier of the last returned event. */
+  id: string;
+}
+
+/** Exact project scope and bounded page for canonical lifecycle events. */
+export interface ProjectLifecycleEventQuery {
+  /** Tenant identifier. */
+  tenantId: string;
+  /** Workspace identifier. */
+  workspaceId: string;
+  /** Project identifier. */
+  projectId: string;
+  /** Nonempty lifecycle actions to include. */
+  actions: ProjectTaskLifecycleAction[];
+  /** Optional exclusive descending cursor. */
+  before?: ProjectLifecycleEventCursor;
+  /** Maximum rows to return, from 1 through 100. */
+  limit: number;
+}
+
 export interface TaskWorkItemStore {
   create(params: CreateWorkItemRequest): Promise<TaskWorkItem>;
+  /** Atomically creates a work item only while the owning task snapshot matches. */
+  createIfTaskSnapshot?(
+    params: CreateWorkItemRequest,
+    snapshot: TaskMutationSnapshot,
+  ): Promise<TaskWorkItem | null>;
   list(filter: TaskWorkItemListFilter): Promise<TaskWorkItem[]>;
 
+  /**
+   * List the newest bounded set of execution results awaiting reconciliation.
+   *
+   * Only `execution_result` items with a canonical ASCII
+   * `execution-result:[A-Za-z0-9._:-]+` event key are returned. An item is excluded when
+   * a task-scoped `execution_reconciled` item has a
+   * `detail.executionResultId` equal to that event key. Results are ordered by
+   * `createdAt` descending and then `id` descending for deterministic ties.
+   *
+   * @param params Tenant/task scope and required maximum number of rows.
+   * @returns At most `limit` pending execution-result work items, newest first.
+   * @throws RangeError with code `INVALID_LIMIT` unless limit is a safe integer from zero through
+   * {@link MAX_PENDING_EXECUTION_RESULTS_LIMIT}.
+   * @remarks Optional optimization. Stores that omit it remain compatible; callers may use a
+   * bounded, non-authoritative fallback through the pre-existing list and event-key methods.
+   */
+  listPendingExecutionResults?(params: {
+    tenantId: string;
+    taskId: string;
+    limit: number;
+  }): Promise<TaskWorkItem[]>;
+
+  /**
+   * Lists canonical lifecycle events in an exact project scope.
+   *
+   * @param query Exact scope, actions, exclusive cursor, and page bound.
+   * @returns Events ordered by creation time and ID descending.
+   */
+  listProjectLifecycleEvents?(query: ProjectLifecycleEventQuery): Promise<TaskWorkItem[]>;
+
   /**
    * Find an event by deterministic identity without list pagination.
    *
@@ -79,3 +178,42 @@ export interface TaskWorkItemStore {
    */
   createIfAbsentByEventKey(params: CreateWorkItemIfAbsentRequest): Promise<TaskWorkItem>;
 }
+
+/** Work-item capabilities required by trusted Project Task consumers. */
+export interface ProjectTaskWorkItemStore extends TaskWorkItemStore {
+  createIfTaskSnapshot(
+    params: CreateWorkItemRequest,
+    snapshot: TaskMutationSnapshot,
+  ): Promise<TaskWorkItem | null>;
+  listProjectLifecycleEvents(
+    query: ProjectLifecycleEventQuery,
+  ): Promise<TaskWorkItem[]>;
+}
+
+/** Stable capability failure raised before any trusted Project Task mutation. */
+export class ProjectTaskStoreUnsupportedError extends Error {
+  readonly code = "PROJECT_TASK_STORE_UNSUPPORTED" as const;
+
+  constructor(readonly missingMethods: readonly string[]) {
+    super(`Project Task WorkItem store is missing: ${missingMethods.join(", ")}`);
+    this.name = "ProjectTaskStoreUnsupportedError";
+  }
+}
+
+/** Refines a Main-compatible WorkItem store for trusted Project Task consumers. */
+export function requireProjectTaskWorkItemStore(
+  store: TaskWorkItemStore,
+): ProjectTaskWorkItemStore {
+  const missingMethods = ["createIfTaskSnapshot", "listProjectLifecycleEvents"]
+    .filter((name) => {
+      try {
+        return typeof Reflect.get(store as object, name) !== "function";
+      } catch {
+        return true;
+      }
+    });
+  if (missingMethods.length > 0) {
+    throw new ProjectTaskStoreUnsupportedError(missingMethods);
+  }
+  return store as ProjectTaskWorkItemStore;
+}

package/src/TrustedRunContextProtocol.ts

@@ -0,0 +1,119 @@
+import { snapshotExactRecord } from "./ExactDataSnapshot";
+
+/** Queue execution behavior available to privileged host dispatchers. */
+export type QueuedExecutionMode = "followup";
+
+/** Trusted Project Room identity persisted with a privileged queue message. */
+export interface ProjectRoomTrustedRunContext {
+  tenantId: string;
+  workspaceId: string;
+  projectId: string;
+  roomId: string;
+  sourceRoomMessageId: string;
+  membershipId: string;
+  assistantId: string;
+  inputMessageId: string;
+  role: "coordinator" | "specialist";
+  title: string;
+  responsibility?: string;
+}
+
+/** Trusted Project Task identity persisted with a privileged queue message. */
+export interface ProjectTaskTrustedRunContext {
+  tenantId: string;
+  workspaceId: string;
+  projectId: string;
+  roomId: string;
+  membershipId: string;
+  assistantId: string;
+  taskId: string;
+  threadId: string;
+  inputMessageId: string;
+}
+
+/** Host-authenticated metadata that cannot be supplied through public Agent APIs. */
+export interface TrustedRunContext {
+  projectRoom?: ProjectRoomTrustedRunContext;
+  projectTask?: ProjectTaskTrustedRunContext;
+}
+
+/**
+ * Strictly validates and clones host-authenticated queue context read from durable storage.
+ *
+ * @param value - Untrusted decoded database value.
+ * @returns A validated defensive clone of the trusted run context.
+ * @throws Error when the stored value does not exactly match the trusted context contract.
+ */
+export function parseTrustedRunContext(value: unknown): TrustedRunContext {
+  const contextValues = snapshotExactRecord(value, [], ["projectRoom", "projectTask"]);
+  if (!contextValues || Object.keys(contextValues).length !== 1) {
+    throw new Error("Invalid trusted agent run context");
+  }
+  if (Object.prototype.hasOwnProperty.call(contextValues, "projectTask")) {
+    const requiredKeys = [
+      "tenantId", "workspaceId", "projectId", "roomId", "membershipId",
+      "assistantId", "taskId", "threadId", "inputMessageId",
+    ] as const;
+    const projectTaskValues = snapshotExactRecord(contextValues.projectTask, requiredKeys);
+    if (!projectTaskValues
+      || requiredKeys.some((key) => typeof projectTaskValues[key] !== "string" || projectTaskValues[key].length === 0)) {
+      throw new Error("Invalid trusted agent run context");
+    }
+    return {
+      projectTask: {
+        tenantId: projectTaskValues.tenantId as string,
+        workspaceId: projectTaskValues.workspaceId as string,
+        projectId: projectTaskValues.projectId as string,
+        roomId: projectTaskValues.roomId as string,
+        membershipId: projectTaskValues.membershipId as string,
+        assistantId: projectTaskValues.assistantId as string,
+        taskId: projectTaskValues.taskId as string,
+        threadId: projectTaskValues.threadId as string,
+        inputMessageId: projectTaskValues.inputMessageId as string,
+      },
+    };
+  }
+  const projectRoomValue = contextValues?.projectRoom;
+  const requiredKeys = [
+    "tenantId", "workspaceId", "projectId", "roomId", "sourceRoomMessageId", "membershipId",
+    "assistantId", "inputMessageId", "role", "title",
+  ] as const;
+  const projectRoomValues = snapshotExactRecord(projectRoomValue, requiredKeys, ["responsibility"]);
+  const hasResponsibility = projectRoomValues !== undefined
+    && Object.prototype.hasOwnProperty.call(projectRoomValues, "responsibility");
+  if (!projectRoomValues
+    || requiredKeys.some((key) => typeof projectRoomValues[key] !== "string" || projectRoomValues[key].length === 0)
+    || (hasResponsibility && projectRoomValues.responsibility !== undefined
+      && (typeof projectRoomValues.responsibility !== "string" || projectRoomValues.responsibility.length === 0))
+    || (projectRoomValues.role !== "coordinator" && projectRoomValues.role !== "specialist")) {
+    throw new Error("Invalid trusted agent run context");
+  }
+  const parsedProjectRoom: ProjectRoomTrustedRunContext = {
+    tenantId: projectRoomValues.tenantId as string,
+    workspaceId: projectRoomValues.workspaceId as string,
+    projectId: projectRoomValues.projectId as string,
+    roomId: projectRoomValues.roomId as string,
+    sourceRoomMessageId: projectRoomValues.sourceRoomMessageId as string,
+    membershipId: projectRoomValues.membershipId as string,
+    assistantId: projectRoomValues.assistantId as string,
+    inputMessageId: projectRoomValues.inputMessageId as string,
+    role: projectRoomValues.role,
+    title: projectRoomValues.title as string,
+  };
+  if (hasResponsibility && typeof projectRoomValues.responsibility === "string") {
+    parsedProjectRoom.responsibility = projectRoomValues.responsibility;
+  }
+  return { projectRoom: parsedProjectRoom };
+}
+
+/**
+ * Strictly validates a queued execution mode read from durable storage.
+ *
+ * @param value - Untrusted database value.
+ * @returns The validated execution mode.
+ * @throws Error when the stored value is not supported.
+ */
+export function parseQueuedExecutionMode(value: unknown): QueuedExecutionMode {
+  if (value !== "followup") throw new Error("Invalid queued execution mode");
+  return value;
+}

package/src/WorkspaceStoreProtocol.ts

@@ -102,6 +102,25 @@ export interface UpdateProjectRequest {
   kind?: ProjectKind;
 }
 
+/** Error raised when generic project writes attempt to change capability Bundle references. */
+export class InvalidProjectCapabilityBundleConfigError extends Error {
+  /** Stable machine-readable error code. */
+  readonly code = "INVALID_BUNDLE_CONFIG" as const;
+
+  /** Creates the reserved-config error returned by generic Project writes. */
+  constructor() {
+    super("Use the project capability-bundles endpoint to update capability bundle IDs");
+    this.name = "InvalidProjectCapabilityBundleConfigError";
+  }
+}
+
+/** Rejects capability Bundle references supplied through generic Project config writes. */
+export function assertGenericProjectConfig(config: Record<string, unknown> | undefined): void {
+  if (config !== undefined && Object.prototype.hasOwnProperty.call(config, "capabilityBundleIds")) {
+    throw new InvalidProjectCapabilityBundleConfigError();
+  }
+}
+
 /**
  * Filter options for listing projects within a workspace
  */
@@ -109,6 +128,16 @@ export interface ProjectFilter {
   kind?: ProjectKind;
 }
 
+/** Atomic result of replacing a Project's capability Bundle IDs. */
+export type UpdateProjectCapabilityBundlesResult =
+  | { status: "updated"; project: Project }
+  | { status: "project_not_found" }
+  | { status: "bundle_not_found" }
+  | { status: "bundle_conflict" };
+
+/** Revision preconditions for the bundles reviewed before project assignment. */
+export type ExpectedCapabilityBundleRevisions = Record<string, string>;
+
 /**
  * ProjectStore interface
  * Provides CRUD operations for project data
@@ -118,5 +147,9 @@ export interface ProjectStore {
   getProjectById(tenantId: string, id: string): Promise<Project | null>;
   createProject(tenantId: string, workspaceId: string, id: string, data: CreateProjectRequest): Promise<Project>;
   updateProject(tenantId: string, id: string, updates: UpdateProjectRequest): Promise<Project | null>;
+  /** Omitted expectedRevisions is reserved for internal maintenance callers. */
+  updateCapabilityBundleIds(tenantId: string, projectId: string, bundleIds: string[], expectedRevisions?: ExpectedCapabilityBundleRevisions): Promise<UpdateProjectCapabilityBundlesResult>;
   deleteProject(tenantId: string, id: string): Promise<boolean>;
+  /** Returns whether a tenant project references the given capability bundle. */
+  isCapabilityBundleReferenced(tenantId: string, bundleId: string): Promise<boolean>;
 }

package/src/__tests__/BindingProtocol.test.ts

@@ -0,0 +1,36 @@
+import type { BindingMutablePatch, BindingRegistry, CreateBindingInput } from "../BindingProtocol";
+
+describe("BindingProtocol mutation contract", () => {
+  it("accepts mutable fields and rejects identity fields at compile time", () => {
+    const mutable: BindingMutablePatch = {
+      agentId: "agent-2", threadId: "thread-2", workspaceId: "workspace-2",
+      projectId: "project-2", threadMode: "fixed", senderDisplayName: "Sender",
+      senderMetadata: { source: "test" }, enabled: false,
+    };
+    expect(mutable.enabled).toBe(false);
+
+    // @ts-expect-error channel is immutable after binding creation
+    const invalid: BindingMutablePatch = { channel: "room" };
+    expect(invalid).toBeDefined();
+  });
+
+  it("requires tenant scope for mutation methods", () => {
+    const update: BindingRegistry["update"] = async (...args) => {
+      expect(args).toHaveLength(3);
+      throw new Error("not invoked");
+    };
+    const remove: BindingRegistry["delete"] = async (...args) => {
+      expect(args).toHaveLength(2);
+    };
+    expect(update).toBeDefined();
+    expect(remove).toBeDefined();
+  });
+
+  it("allows trusted callers to choose the initial enabled state", () => {
+    const input: CreateBindingInput = {
+      channel: "room", channelInstallationId: "room-internal:tenant-a", tenantId: "tenant-a",
+      senderId: "room:room-1:membership-1", agentId: "agent-1", enabled: false,
+    };
+    expect(input.enabled).toBe(false);
+  });
+});

package/src/__tests__/ExactDataSnapshot.test.ts

@@ -0,0 +1,105 @@
+import { runInNewContext } from "node:vm";
+import { snapshotExactArray, snapshotExactRecord } from "../ExactDataSnapshot";
+
+describe("exact data snapshots", () => {
+  it("canonicalizes cross-realm and hostile-prototype records without reading their prototype", () => {
+    const crossRealm = runInNewContext("({ id: 'one', value: 2 })");
+    let inheritedReads = 0;
+    const prototype = Object.create(null);
+    Object.defineProperty(prototype, "constructor", {
+      get: () => { inheritedReads += 1; throw new Error("must not run"); },
+    });
+    Object.defineProperty(prototype, "inherited", {
+      get: () => { inheritedReads += 1; throw new Error("must not run"); },
+    });
+    const hostilePrototype = Object.assign(Object.create(prototype), { id: "two", value: 3 });
+
+    expect(snapshotExactRecord(crossRealm, ["id", "value"])).toEqual({ id: "one", value: 2 });
+    expect(snapshotExactRecord(hostilePrototype, ["id", "value"])).toEqual({ id: "two", value: 3 });
+    expect(inheritedReads).toBe(0);
+  });
+
+  it.each([
+    ["accessor", Object.defineProperty({ id: "one" }, "value", { enumerable: true, get: () => 2 })],
+    ["extra", { id: "one", value: 2, extra: true }],
+    ["non-enumerable", Object.defineProperty({ id: "one" }, "value", { enumerable: false, value: 2 })],
+    ["symbol", Object.assign({ id: "one", value: 2 }, { [Symbol("extra")]: true })],
+  ])("rejects an own %s record property", (_name, value) => {
+    expect(snapshotExactRecord(value, ["id", "value"])).toBeUndefined();
+  });
+
+  it("canonicalizes cross-realm arrays and rejects non-dense or accessor-bearing arrays", () => {
+    expect(snapshotExactArray(runInNewContext("['one', 'two']"))).toEqual(["one", "two"]);
+    const accessor = ["one"];
+    Object.defineProperty(accessor, "0", { enumerable: true, get: () => "one" });
+    expect(snapshotExactArray(accessor)).toBeUndefined();
+    expect(snapshotExactArray(Object.assign(["one"], { extra: true }))).toBeUndefined();
+    expect(snapshotExactArray(new Array(1))).toBeUndefined();
+  });
+
+  it("rejects record accessors without reading polluted descriptor prototypes", () => {
+    const originalValue = Object.getOwnPropertyDescriptor(Object.prototype, "value");
+    const originalEnumerable = Object.getOwnPropertyDescriptor(Object.prototype, "enumerable");
+    let inheritedReads = 0;
+    const accessor = Object.defineProperty({ id: "one" }, "value", {
+      enumerable: true,
+      get: () => 2,
+    });
+    try {
+      Object.defineProperty(Object.prototype, "value", {
+        configurable: true,
+        get: () => {
+          inheritedReads += 1;
+          return "forged";
+        },
+      });
+      Object.defineProperty(Object.prototype, "enumerable", Object.assign(Object.create(null), {
+        configurable: true,
+        get: () => {
+          inheritedReads += 1;
+          return true;
+        },
+      }));
+
+      expect(snapshotExactRecord(accessor, ["id", "value"])).toBeUndefined();
+      expect(inheritedReads).toBe(0);
+    } finally {
+      if (originalValue) Object.defineProperty(Object.prototype, "value", originalValue);
+      else delete (Object.prototype as { value?: unknown }).value;
+      if (originalEnumerable) Object.defineProperty(Object.prototype, "enumerable", originalEnumerable);
+      else delete (Object.prototype as { enumerable?: unknown }).enumerable;
+    }
+  });
+
+  it("rejects array accessors without reading polluted descriptor prototypes", () => {
+    const originalValue = Object.getOwnPropertyDescriptor(Object.prototype, "value");
+    const originalEnumerable = Object.getOwnPropertyDescriptor(Object.prototype, "enumerable");
+    let inheritedReads = 0;
+    const accessor = ["one"];
+    Object.defineProperty(accessor, "0", { enumerable: true, get: () => "one" });
+    try {
+      Object.defineProperty(Object.prototype, "value", {
+        configurable: true,
+        get: () => {
+          inheritedReads += 1;
+          return "forged";
+        },
+      });
+      Object.defineProperty(Object.prototype, "enumerable", Object.assign(Object.create(null), {
+        configurable: true,
+        get: () => {
+          inheritedReads += 1;
+          return true;
+        },
+      }));
+
+      expect(snapshotExactArray(accessor)).toBeUndefined();
+      expect(inheritedReads).toBe(0);
+    } finally {
+      if (originalValue) Object.defineProperty(Object.prototype, "value", originalValue);
+      else delete (Object.prototype as { value?: unknown }).value;
+      if (originalEnumerable) Object.defineProperty(Object.prototype, "enumerable", originalEnumerable);
+      else delete (Object.prototype as { enumerable?: unknown }).enumerable;
+    }
+  });
+});

package/src/__tests__/ProjectRoomProtocol.test.ts

@@ -0,0 +1,48 @@
+import type {
+  ProjectBotMembership,
+  ProjectRoomMessage,
+  ProjectRoomMessageCursor,
+} from "../ProjectRoomProtocol";
+
+describe("Project Room protocol types", () => {
+  it("models bot membership, system messages, and message cursors", () => {
+    const bot: ProjectBotMembership = {
+      id: "bm-1",
+      tenantId: "t-1",
+      workspaceId: "w-1",
+      projectId: "p-1",
+      roomId: "r-1",
+      assistantId: "a-1",
+      role: "coordinator",
+      title: "Lead",
+      mentionName: "lead",
+      status: "paused",
+      roomThreadId: "th-1",
+      joinedAt: new Date(0),
+      updatedAt: new Date(0),
+    };
+    const message: ProjectRoomMessage = {
+      id: "m-1",
+      tenantId: "t-1",
+      workspaceId: "w-1",
+      projectId: "p-1",
+      roomId: "r-1",
+      author: { type: "system" },
+      content: { type: "text", text: "Room ready" },
+      mentions: [],
+      source: "system",
+      idempotencyKey: "room-ready:p-1",
+      createdAt: new Date(0),
+    };
+    const cursor: ProjectRoomMessageCursor = {
+      createdAt: message.createdAt,
+      id: message.id,
+    };
+
+    expect([bot.status, message.source, cursor.id]).toEqual([
+      "paused",
+      "system",
+      "m-1",
+    ]);
+  });
+});