@axiom-lattice/protocols 4.1.1 → 4.1.2

package/src/ProjectRoomRealtimeProtocol.ts

@@ -0,0 +1,349 @@
+import type {
+  ProjectBotMembershipStatus,
+  ProjectBotRole,
+  ProjectHumanRole,
+  ProjectMembershipStatus,
+  ProjectRoomMention,
+  ProjectRoomMessageSource,
+} from "./ProjectRoomProtocol";
+import type { TaskItem } from "./TaskStoreProtocol";
+import { snapshotExactArray, snapshotExactRecord } from "./ExactDataSnapshot";
+
+/** A message shape safe to expose to Project Room clients. */
+export interface ProjectRoomPublicMessage {
+  id: string;
+  roomId: string;
+  author:
+    | { type: "human"; userId: string }
+    | { type: "bot"; membershipId: string }
+    | { type: "system" };
+  content: { type: "text"; text: string };
+  mentions: ProjectRoomMention[];
+  replyToMessageId?: string;
+  source: ProjectRoomMessageSource;
+  createdAt: string;
+}
+
+/** A human membership shape safe to expose to Project Room clients. */
+export interface ProjectRoomPublicMembership {
+  id: string;
+  userId: string;
+  role: ProjectHumanRole;
+  status: ProjectMembershipStatus;
+  joinedAt: string;
+  updatedAt: string;
+}
+
+/** A bot membership shape safe to expose to Project Room clients. */
+export interface ProjectRoomPublicBotMembership {
+  id: string;
+  role: ProjectBotRole;
+  title: string;
+  responsibility?: string;
+  mentionName: string;
+  status: ProjectBotMembershipStatus;
+  joinedAt: string;
+  updatedAt: string;
+}
+
+/** A fully identified business event carried by the realtime stream. */
+export interface ProjectRoomEventOf<TType extends string, TData> {
+  id: string;
+  type: TType;
+  occurredAt: string;
+  data: TData;
+}
+
+/** A newly committed message event. */
+export type ProjectRoomMessageCreatedEvent = ProjectRoomEventOf<
+  "message.created",
+  { message: ProjectRoomPublicMessage }
+>;
+
+/** A changed bot roster event. */
+export type ProjectRoomRosterChangedEvent = ProjectRoomEventOf<
+  "roster.changed",
+  { change: "added" | "updated" | "paused" | "resumed" | "removed"; membership: ProjectRoomPublicBotMembership }
+>;
+
+/** A changed human membership event. */
+export type ProjectRoomMembershipChangedEvent = ProjectRoomEventOf<
+  "membership.changed",
+  { change: "added" | "role_changed" | "removed"; membership: ProjectRoomPublicMembership }
+>;
+
+/** A changed Project Task fact event. */
+export type ProjectRoomTaskChangedEvent = ProjectRoomEventOf<
+  "task.changed",
+  {
+    taskId: string;
+    status: TaskItem["status"];
+    ownerMembershipId: string;
+    updatedAt: string;
+  }
+>;
+
+/** All identified business events retained by the realtime broker. */
+export type ProjectRoomBusinessEvent =
+  | ProjectRoomMessageCreatedEvent
+  | ProjectRoomRosterChangedEvent
+  | ProjectRoomMembershipChangedEvent
+  | ProjectRoomTaskChangedEvent;
+
+/** A business event before the broker assigns its process-local ID. */
+export type ProjectRoomBusinessEventDraft =
+  | Omit<ProjectRoomMessageCreatedEvent, "id">
+  | Omit<ProjectRoomRosterChangedEvent, "id">
+  | Omit<ProjectRoomMembershipChangedEvent, "id">
+  | Omit<ProjectRoomTaskChangedEvent, "id">;
+
+/** A connection control event; control events are never replayed. */
+export type ProjectRoomControlEvent =
+  | { type: "ready"; data: { epoch: string; headEventId: string | null } }
+  | { type: "resync"; data: { reason: "SERVER_RESTART" | "CURSOR_EXPIRED" | "SLOW_CONSUMER" } }
+  | { type: "access.revoked"; data: { reason: "PROJECT_ACCESS_REVOKED" | "TOKEN_EXPIRED" } };
+
+/** The authenticated identity used by Project Room realtime access checks. */
+export interface ProjectRoomRealtimeActor {
+  tenantId: string;
+  userId: string;
+  projectId: string;
+  tokenExpiresAt: number;
+}
+
+/** Writable HTTP socket surface required by the bounded SSE transport. */
+export interface ProjectRoomSseWritable {
+  write(chunk: string): boolean;
+  end(): void;
+  destroy(): void;
+  on(event: "close" | "error" | "drain", listener: () => void): this;
+  off(event: "close" | "error" | "drain", listener: () => void): this;
+}
+
+/** The scope used to isolate events between tenant rooms. */
+export interface ProjectRoomEventScope {
+  tenantId: string;
+  roomId: string;
+  projectId: string;
+}
+
+/** An internal broker event carrying scope that is removed before public serialization. */
+export type ProjectRoomScopedBusinessEvent = ProjectRoomBusinessEvent & {
+  scope: ProjectRoomEventScope;
+};
+
+/** A broker subscription containing replay and its room head. */
+export interface ProjectRoomEventSubscription {
+  replay: ProjectRoomBusinessEvent[];
+  headEventId: string | null;
+  unsubscribe(): void;
+}
+
+/** The narrow broker contract consumed by realtime publishers and services. */
+export interface ProjectRoomEventBrokerProtocol {
+  readonly epoch: string;
+  publish(scope: ProjectRoomEventScope, draft: ProjectRoomBusinessEventDraft): ProjectRoomScopedBusinessEvent;
+  subscribe(
+    scope: ProjectRoomEventScope,
+    afterEventId: string | undefined,
+    listener: (event: ProjectRoomBusinessEvent) => void,
+  ): ProjectRoomEventSubscription;
+  close(): void;
+}
+
+/** A typed cursor failure requiring client REST resynchronization. */
+export class ProjectRoomCursorError extends Error {
+  readonly name = "ProjectRoomCursorError";
+
+  constructor(readonly code: "SERVER_RESTART" | "CURSOR_EXPIRED") {
+    super(`Project Room realtime cursor requires resynchronization: ${code}`);
+  }
+}
+
+/** A typed failure raised when the process-local event sequence is exhausted. */
+export class ProjectRoomBrokerCapacityError extends Error {
+  readonly name = "ProjectRoomBrokerCapacityError";
+  readonly code = "PROJECT_ROOM_EVENT_SEQUENCE_EXHAUSTED" as const;
+
+  constructor() {
+    super("Project Room realtime event sequence is exhausted");
+  }
+}
+
+const PROJECT_ROOM_EVENT_ID_PATTERN = /^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}):([1-9][0-9]*)$/i;
+
+/** The parsed components of a canonical Project Room event ID. */
+export interface ProjectRoomEventId {
+  epoch: string;
+  sequence: number;
+}
+
+/** Parses a canonical event ID, returning undefined for malformed or unsafe IDs. */
+export function parseProjectRoomEventId(value: unknown): ProjectRoomEventId | undefined {
+  if (typeof value !== "string") return undefined;
+  const match = PROJECT_ROOM_EVENT_ID_PATTERN.exec(value);
+  if (!match) return undefined;
+  const sequence = Number(match[2]);
+  if (!Number.isSafeInteger(sequence)) return undefined;
+  if (match[1] !== match[1].toLowerCase()) return undefined;
+  return { epoch: match[1], sequence };
+}
+
+/** Checks an event ID without relying on realm-specific object identity. */
+export function isProjectRoomEventId(value: unknown): value is string {
+  return parseProjectRoomEventId(value) !== undefined;
+}
+
+function isoDate(value: unknown): string | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  try {
+    const time = Date.prototype.getTime.call(value);
+    return Number.isFinite(time) ? new Date(time).toISOString() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function stringField(record: Record<string, unknown>, key: string): string | undefined {
+  return typeof record[key] === "string" ? record[key] : undefined;
+}
+
+function isOneOf<T extends string>(value: unknown, values: readonly T[]): value is T {
+  return typeof value === "string" && values.includes(value as T);
+}
+
+const messageSources = ["user", "agent", "task", "routine", "system"] as const;
+const humanRoles = ["owner", "admin", "member", "viewer"] as const;
+const membershipStatuses = ["active", "removed"] as const;
+const botRoles = ["coordinator", "specialist"] as const;
+const botStatuses = ["active", "paused", "removed"] as const;
+
+function mapPublicMessageRecord(record: Record<string, unknown>): ProjectRoomPublicMessage | undefined {
+  const id = stringField(record, "id");
+  const roomId = stringField(record, "roomId");
+  const source = stringField(record, "source");
+  const createdAt = isoDate(record.createdAt);
+  const content = snapshotExactRecord(record.content, ["type", "text"]);
+  const mentions = snapshotPublicMentions(record.mentions);
+  const author = snapshotExactRecord(record.author, ["type"], ["userId", "membershipId", "assistantId"]);
+  if (!id || !roomId || !isOneOf(source, messageSources) || !createdAt || !content || content.type !== "text"
+    || typeof content.text !== "string" || !mentions || !author || typeof author.type !== "string") return undefined;
+  const publicAuthor = author.type === "human" && typeof author.userId === "string"
+    ? { type: "human" as const, userId: author.userId }
+    : author.type === "bot" && typeof author.membershipId === "string"
+      ? { type: "bot" as const, membershipId: author.membershipId }
+      : author.type === "system" ? { type: "system" as const } : undefined;
+  if (!publicAuthor) return undefined;
+  const result: ProjectRoomPublicMessage = { id, roomId, author: publicAuthor, content: { type: "text", text: content.text }, mentions: mentions as ProjectRoomMention[], source: source as ProjectRoomMessageSource, createdAt };
+  if (record.replyToMessageId !== undefined) {
+    if (typeof record.replyToMessageId !== "string") return undefined;
+    result.replyToMessageId = record.replyToMessageId;
+  }
+  return result;
+}
+
+function snapshotPublicMentions(value: unknown): ProjectRoomMention[] | undefined {
+  const rows = snapshotExactArray(value);
+  if (!rows) return undefined;
+  const result: ProjectRoomMention[] = [];
+  for (const row of rows) {
+    const team = snapshotExactRecord(row, ["type"]);
+    if (team?.type === "team") { result.push({ type: "team" }); continue; }
+    const bot = snapshotExactRecord(row, ["type", "membershipId"]);
+    if (bot?.type === "bot" && typeof bot.membershipId === "string") {
+      result.push({ type: "bot", membershipId: bot.membershipId });
+      continue;
+    }
+    return undefined;
+  }
+  return result;
+}
+
+function mapPublicMembershipRecord(record: Record<string, unknown>): ProjectRoomPublicMembership | undefined {
+  const joinedAt = isoDate(record.joinedAt); const updatedAt = isoDate(record.updatedAt);
+  if (typeof record.id !== "string" || typeof record.userId !== "string" || !isOneOf(record.role, humanRoles) || !isOneOf(record.status, membershipStatuses) || !joinedAt || !updatedAt) return undefined;
+  return { id: record.id, userId: record.userId, role: record.role, status: record.status, joinedAt, updatedAt };
+}
+
+function mapPublicBotMembershipRecord(record: Record<string, unknown>): ProjectRoomPublicBotMembership | undefined {
+  const joinedAt = isoDate(record.joinedAt); const updatedAt = isoDate(record.updatedAt);
+  if (typeof record.id !== "string" || !isOneOf(record.role, botRoles) || typeof record.title !== "string" || typeof record.mentionName !== "string" || !isOneOf(record.status, botStatuses) || !joinedAt || !updatedAt || record.responsibility !== undefined && typeof record.responsibility !== "string") return undefined;
+  return { id: record.id, role: record.role, title: record.title, ...(record.responsibility === undefined ? {} : { responsibility: record.responsibility }), mentionName: record.mentionName, status: record.status, joinedAt, updatedAt };
+}
+
+/** Maps a canonical internal message to the strict public message DTO. */
+export function toProjectRoomPublicMessage(value: unknown): ProjectRoomPublicMessage | undefined {
+  const record = snapshotExactRecord(value, [
+    "id", "tenantId", "workspaceId", "projectId", "roomId", "author", "content", "mentions", "source", "createdAt",
+  ], ["replyToMessageId", "sourceId", "idempotencyKey"]);
+  if (!record) return undefined;
+  return mapPublicMessageRecord(record);
+}
+
+/** A descriptor-safe message projection together with its canonical realtime scope. */
+export function snapshotProjectRoomMessageRealtime(value: unknown): {
+  scope: { tenantId: string; roomId: string; projectId: string };
+  publicMessage: ProjectRoomPublicMessage;
+} | undefined {
+  const record = snapshotExactRecord(value, ["id", "tenantId", "workspaceId", "projectId", "roomId", "author", "content", "mentions", "source", "createdAt"], ["replyToMessageId", "sourceId", "idempotencyKey"]);
+  if (!record) return undefined;
+  const publicMessage = mapPublicMessageRecord(record);
+  if (!publicMessage || typeof record.tenantId !== "string" || typeof record.projectId !== "string") return undefined;
+  return { scope: { tenantId: record.tenantId, roomId: publicMessage.roomId, projectId: record.projectId }, publicMessage };
+}
+
+/** Maps a canonical internal human membership to the strict public DTO. */
+export function toProjectRoomPublicMembership(value: unknown): ProjectRoomPublicMembership | undefined {
+  const record = snapshotExactRecord(value,
+    ["id", "tenantId", "projectId", "userId", "role", "status", "joinedAt", "updatedAt"]);
+  if (!record || typeof record.id !== "string" || typeof record.userId !== "string"
+    || !isOneOf(record.role, humanRoles) || !isOneOf(record.status, membershipStatuses)) return undefined;
+  const joinedAt = isoDate(record.joinedAt);
+  const updatedAt = isoDate(record.updatedAt);
+  if (!joinedAt || !updatedAt) return undefined;
+  return { id: record.id, userId: record.userId, role: record.role,
+    status: record.status, joinedAt, updatedAt };
+}
+
+/** A descriptor-safe human membership projection with canonical tenant/project scope. */
+export function snapshotProjectRoomMembershipRealtime(value: unknown): {
+  scope: { tenantId: string; projectId: string };
+  publicMembership: ProjectRoomPublicMembership;
+} | undefined {
+  const record = snapshotExactRecord(value, ["id", "tenantId", "projectId", "userId", "role", "status", "joinedAt", "updatedAt"]);
+  if (!record) return undefined;
+  const publicMembership = mapPublicMembershipRecord(record);
+  if (!publicMembership || typeof record.tenantId !== "string" || typeof record.projectId !== "string") return undefined;
+  return { scope: { tenantId: record.tenantId, projectId: record.projectId }, publicMembership };
+}
+
+/** Maps a canonical internal bot membership to the strict public DTO. */
+export function toProjectRoomPublicBotMembership(value: unknown): ProjectRoomPublicBotMembership | undefined {
+  const record = snapshotExactRecord(value,
+    ["id", "tenantId", "workspaceId", "projectId", "roomId", "assistantId", "role", "title", "mentionName", "status", "roomThreadId", "joinedAt", "updatedAt"],
+    ["responsibility"]);
+  if (!record || typeof record.id !== "string" || !isOneOf(record.role, botRoles) || typeof record.title !== "string"
+    || typeof record.mentionName !== "string" || !isOneOf(record.status, botStatuses)) return undefined;
+  if (record.responsibility !== undefined && typeof record.responsibility !== "string") return undefined;
+  const joinedAt = isoDate(record.joinedAt);
+  const updatedAt = isoDate(record.updatedAt);
+  if (!joinedAt || !updatedAt) return undefined;
+  const result: ProjectRoomPublicBotMembership = {
+    id: record.id, role: record.role, title: record.title,
+    mentionName: record.mentionName, status: record.status, joinedAt, updatedAt,
+  };
+  if (record.responsibility !== undefined) result.responsibility = record.responsibility;
+  return result;
+}
+
+/** A descriptor-safe bot membership projection with canonical realtime scope. */
+export function snapshotProjectRoomBotMembershipRealtime(value: unknown): {
+  scope: { tenantId: string; roomId: string; projectId: string };
+  publicMembership: ProjectRoomPublicBotMembership;
+} | undefined {
+  const record = snapshotExactRecord(value, ["id", "tenantId", "workspaceId", "projectId", "roomId", "assistantId", "role", "title", "mentionName", "status", "roomThreadId", "joinedAt", "updatedAt"], ["responsibility"]);
+  if (!record) return undefined;
+  const publicMembership = mapPublicBotMembershipRecord(record);
+  if (!publicMembership || typeof record.tenantId !== "string" || typeof record.roomId !== "string" || typeof record.projectId !== "string") return undefined;
+  return { scope: { tenantId: record.tenantId, roomId: record.roomId, projectId: record.projectId }, publicMembership };
+}

package/src/ProjectRoomStoreProtocol.ts

@@ -0,0 +1,16 @@
+import type { ProjectRoom } from "./ProjectRoomProtocol";
+
+/** Persistence operations for a project's canonical main room. */
+export interface ProjectRoomStore {
+  /** Creates the main room if needed and returns the canonical record. */
+  ensureMainRoom(input: {
+    id: string;
+    tenantId: string;
+    workspaceId: string;
+    projectId: string;
+    name: string;
+  }): Promise<ProjectRoom>;
+
+  /** Finds the main room for a project, if one exists. */
+  getMainRoom(tenantId: string, projectId: string): Promise<ProjectRoom | null>;
+}

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
  *
@@ -86,8 +88,45 @@ 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[]>;
 
   /**
@@ -112,6 +151,14 @@ export interface TaskWorkItemStore {
     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.
    *
@@ -131,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;
+}