@axiom-lattice/protocols 4.1.0 → 4.1.2

package/src/ProjectMembershipStoreProtocol.ts

@@ -0,0 +1,58 @@
+import type {
+  ProjectHumanRole,
+  ProjectMembership,
+} from "./ProjectRoomProtocol";
+
+/** Result of an atomic human membership mutation, including its committed row. */
+export type ProjectMembershipMutationResult =
+  | { kind: "updated" | "removed"; membership: ProjectMembership }
+  | { kind: "not_found" | "conflict" | "last_owner" };
+
+/** Persistence operations for human membership in a project. */
+export interface ProjectMembershipStore {
+  /** Lists memberships belonging to a project. */
+  list(tenantId: string, projectId: string): Promise<ProjectMembership[]>;
+
+  /** Finds a user's membership in a project, if one exists. */
+  findByUser(tenantId: string, projectId: string, userId: string): Promise<ProjectMembership | null>;
+
+  /** Creates a project membership. */
+  create(input: Omit<ProjectMembership, "joinedAt" | "updatedAt">): Promise<ProjectMembership>;
+
+  /**
+   * Atomically initializes an empty Project with its first owner.
+   * `created` means this call initialized the Project; `existing` means the
+   * requested user already owns the initialized Project and this was an
+   * idempotent retry; `already_initialized` means membership rows exist but
+   * this call did not produce either initial-owner outcome.
+   */
+  createInitialOwner(
+    input: Omit<ProjectMembership, "role" | "status" | "joinedAt" | "updatedAt">,
+  ): Promise<
+    | { kind: "created" | "existing"; membership: ProjectMembership }
+    | { kind: "already_initialized" }
+  >;
+
+  /**
+   * Updates a role within the tenant using optimistic concurrency and owner
+   * safeguards. `not_found` means the membership is not in the tenant;
+   * `conflict` means `updatedAt` differs from `expectedUpdatedAt`.
+   */
+  updateRole(input: {
+    tenantId: string;
+    id: string;
+    role: ProjectHumanRole;
+    expectedUpdatedAt: Date;
+  }): Promise<ProjectMembershipMutationResult>;
+
+  /**
+   * Removes a membership within the tenant using optimistic concurrency and
+   * owner safeguards. `not_found` means the membership is not in the tenant;
+   * `conflict` means `updatedAt` differs from `expectedUpdatedAt`.
+   */
+  remove(input: {
+    tenantId: string;
+    id: string;
+    expectedUpdatedAt: Date;
+  }): Promise<ProjectMembershipMutationResult>;
+}

package/src/ProjectRoomMessageStoreProtocol.ts

@@ -0,0 +1,26 @@
+import type {
+  ProjectRoomMessage,
+  ProjectRoomMessageCursor,
+} from "./ProjectRoomProtocol";
+
+/** Persistence operations for messages in a project room. */
+export interface ProjectRoomMessageStore {
+  /** Creates a room message. */
+  create(input: Omit<ProjectRoomMessage, "createdAt">): Promise<ProjectRoomMessage>;
+
+  /** Creates or returns the existing room message for an idempotency key. */
+  createIdempotent(
+    input: Omit<ProjectRoomMessage, "createdAt"> & { idempotencyKey: string },
+  ): Promise<ProjectRoomMessage>;
+
+  /** Lists messages strictly before an optional cursor, up to the requested limit. */
+  list(input: {
+    tenantId: string;
+    roomId: string;
+    before?: ProjectRoomMessageCursor;
+    limit: number;
+  }): Promise<ProjectRoomMessage[]>;
+
+  /** Finds a room message by identifier within a tenant. */
+  findById(tenantId: string, id: string): Promise<ProjectRoomMessage | null>;
+}

package/src/ProjectRoomProtocol.ts

@@ -0,0 +1,143 @@
+/** Human access roles available within a project. */
+export type ProjectHumanRole = "owner" | "admin" | "member" | "viewer";
+
+/** Lifecycle states for a human project membership. */
+export type ProjectMembershipStatus = "active" | "removed";
+
+/** Roles a bot can hold within a project room. */
+export type ProjectBotRole = "coordinator" | "specialist";
+
+/** Lifecycle states for a bot room membership. */
+export type ProjectBotMembershipStatus = "active" | "paused" | "removed";
+
+/** Origins supported by project room messages. */
+export type ProjectRoomMessageSource =
+  | "user"
+  | "agent"
+  | "task"
+  | "routine"
+  | "system";
+
+/** The main room associated with a project. */
+export interface ProjectRoom {
+  id: string;
+  tenantId: string;
+  workspaceId: string;
+  projectId: string;
+  type: "main";
+  name: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/** A user's membership and access role within a project. */
+export interface ProjectMembership {
+  id: string;
+  tenantId: string;
+  projectId: string;
+  userId: string;
+  role: ProjectHumanRole;
+  status: ProjectMembershipStatus;
+  joinedAt: Date;
+  updatedAt: Date;
+}
+
+/** A bot's role, presentation, and execution thread within a project room. */
+export interface ProjectBotMembership {
+  id: string;
+  tenantId: string;
+  workspaceId: string;
+  projectId: string;
+  roomId: string;
+  assistantId: string;
+  role: ProjectBotRole;
+  title: string;
+  responsibility?: string;
+  mentionName: string;
+  status: ProjectBotMembershipStatus;
+  roomThreadId: string;
+  joinedAt: Date;
+  updatedAt: Date;
+}
+
+/** Identifies a human author of a project room message. */
+interface ProjectRoomMessageHumanAuthor {
+  type: "human";
+  userId: string;
+}
+
+/** Identifies a bot membership as the author of a project room message. */
+interface ProjectRoomMessageBotAuthor {
+  type: "bot";
+  membershipId: string;
+  assistantId: string;
+}
+
+/** Identifies the system as the author of a project room message. */
+interface ProjectRoomMessageSystemAuthor {
+  type: "system";
+}
+
+/** The discriminated author variants supported by project room messages. */
+export type ProjectRoomMessageAuthor =
+  | ProjectRoomMessageHumanAuthor
+  | ProjectRoomMessageBotAuthor
+  | ProjectRoomMessageSystemAuthor;
+
+/** A bot or the whole team targeted by a room message. */
+export type ProjectRoomMention =
+  | { type: "bot"; membershipId: string }
+  | { type: "team" };
+
+/** Text payload carried by a project room message. */
+interface ProjectRoomTextContent {
+  type: "text";
+  text: string;
+}
+
+/** A message posted to a project room. */
+export interface ProjectRoomMessage {
+  id: string;
+  tenantId: string;
+  workspaceId: string;
+  projectId: string;
+  roomId: string;
+  author: ProjectRoomMessageAuthor;
+  content: ProjectRoomTextContent;
+  mentions: ProjectRoomMention[];
+  replyToMessageId?: string;
+  source: ProjectRoomMessageSource;
+  sourceId?: string;
+  idempotencyKey?: string;
+  createdAt: Date;
+}
+
+/** Stable position used to page through project room messages. */
+export interface ProjectRoomMessageCursor {
+  createdAt: Date;
+  id: string;
+}
+
+/** Metadata linking a room-presence thread to its project room bot membership. */
+export interface ProjectRoomThreadMetadata {
+  source: "project_room";
+  kind: "room_presence";
+  workspaceId: string;
+  projectId: string;
+  roomId: string;
+  membershipId: string;
+  assistantId: string;
+}
+
+/** Metadata linking a task-execution thread to its owning project task and bot membership. */
+export interface ProjectTaskThreadMetadata {
+  source: "project_task";
+  kind: "task_execution";
+  workspaceId: string;
+  projectId: string;
+  roomId: string;
+  membershipId: string;
+  assistantId: string;
+  taskId: string;
+  parentTaskId?: string;
+}

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/SkillStoreProtocol.ts

@@ -59,6 +59,36 @@ export interface Skill {
    */
   subSkills?: string[];
 
+  /**
+   * Source of the skill (optional)
+   * e.g. "builtin-plugin" for read-only plugin-provided skills
+   */
+  source?: string;
+
+  /**
+   * Owning plugin type (optional)
+   * Set for skills contributed by a registered plugin
+   */
+  pluginType?: string;
+
+  /**
+   * Plugin skill bundle version (optional)
+   * Set for skills contributed by a registered plugin
+   */
+  version?: string;
+
+  /**
+   * Resource catalog (optional)
+   * Safe relative paths of a plugin skill's bundled resources with their MIME types
+   */
+  resourcePaths?: Array<{ path: string; mimeType?: string }>;
+
+  /**
+   * Read-only flag (optional)
+   * True for immutable sources (e.g. plugin-provided skills) that cannot be created/updated/deleted
+   */
+  readOnly?: boolean;
+
   /**
    * Skill creation timestamp
    */

package/src/TaskBeliefProtocol.ts

@@ -1,4 +1,9 @@
-/** A single canonical belief recorded in a task description. */
+/**
+ * A single canonical belief recorded in a task description.
+ *
+ * `probability` is retained as the persisted field name, but task guidance uses
+ * it as an evidence-support percentage rather than a calibrated probability.
+ */
 export interface TaskBeliefEntry {
   key: string;
   probability: number;