@axiom-lattice/protocols 4.1.4 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/protocols",
-  "version": "4.1.4",
+  "version": "4.2.0",
   "description": "Unified protocol type definitions for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/McpLatticeProtocol.ts

@@ -29,8 +29,14 @@ export interface McpServerConfig {
   args?: string[];
   /** URL for HTTP/SSE transport */
   url?: string;
-  /** Environment variables */
+  /** Environment variables (stdio transport; credentials passed to the server process) */
   env?: Record<string, string>;
+  /**
+   * Custom HTTP headers sent with every request (streamable_http / sse only).
+   * Commonly used for authentication, e.g. `{ Authorization: "Bearer <token>" }`.
+   * Ignored for stdio transport. Values are encrypted at rest by config stores.
+   */
+  headers?: Record<string, string>;
   /** Connection timeout in milliseconds */
   timeout?: number;
   /** Retry attempts on connection failure */

package/src/McpServerConfigStoreProtocol.ts

@@ -38,7 +38,8 @@ export interface McpServerConfigEntry {
   selectedTools: string[];
 
   /**
-   * Whether the env field is encrypted in storage
+   * Whether secret values (env vars and headers) are encrypted at rest.
+   * Field name kept for backward compatibility; it covers config.headers too.
    */
   isEnvEncrypted: boolean;
 

package/src/ProjectRoomMessageStoreProtocol.ts

@@ -23,4 +23,12 @@ export interface ProjectRoomMessageStore {
 
   /** Finds a room message by identifier within a tenant. */
   findById(tenantId: string, id: string): Promise<ProjectRoomMessage | null>;
+
+  /** Counts messages created strictly after a horizon, optionally excluding one human author. */
+  countAfter(input: {
+    tenantId: string;
+    roomId: string;
+    after: Date;
+    excludeAuthorUserId?: string;
+  }): Promise<number>;
 }

package/src/ProjectRoomReadStateProtocol.ts

@@ -0,0 +1,20 @@
+/** A user's per-room read marker used to compute unread counts. */
+export interface ProjectRoomReadState {
+  tenantId: string;
+  roomId: string;
+  userId: string;
+  /** Read horizon: messages created strictly after this instant are unread. */
+  lastReadAt: Date;
+  updatedAt: Date;
+}
+
+/** Persistence operations for per-user, per-room read markers. */
+export interface ProjectRoomReadStateStore {
+  /** Returns the user's read marker for a room, or null when never reported. */
+  get(tenantId: string, roomId: string, userId: string): Promise<ProjectRoomReadState | null>;
+  /**
+   * Upserts the read marker monotonically: an earlier lastReadAt never moves
+   * the marker backwards. Returns the stored state after the write.
+   */
+  markRead(input: { tenantId: string; roomId: string; userId: string; lastReadAt: Date }): Promise<ProjectRoomReadState>;
+}

package/src/ProjectRoomRealtimeProtocol.ts

@@ -83,25 +83,41 @@ export type ProjectRoomTaskChangedEvent = ProjectRoomEventOf<
   }
 >;
 
+/** A read-marker update broadcast on the acting user's channel. */
+export type ProjectRoomReadChangedEvent = ProjectRoomEventOf<
+  "read.changed",
+  { projectId: string; roomId: string; lastReadAt: string }
+>;
+
+/** A membership mutation that may change a user's room subscription set. */
+export type ProjectRoomMembershipAffectedEvent = ProjectRoomEventOf<
+  "membership.affected",
+  { change: "added" | "removed" | "role_changed"; projectId: string; roomId: string }
+>;
+
 /** All identified business events retained by the realtime broker. */
 export type ProjectRoomBusinessEvent =
   | ProjectRoomMessageCreatedEvent
   | ProjectRoomRosterChangedEvent
   | ProjectRoomMembershipChangedEvent
-  | ProjectRoomTaskChangedEvent;
+  | ProjectRoomTaskChangedEvent
+  | ProjectRoomReadChangedEvent
+  | ProjectRoomMembershipAffectedEvent;
 
 /** 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">;
+  | Omit<ProjectRoomTaskChangedEvent, "id">
+  | Omit<ProjectRoomReadChangedEvent, "id">
+  | Omit<ProjectRoomMembershipAffectedEvent, "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" } };
+  | { type: "access.revoked"; data: { reason: "PROJECT_ACCESS_REVOKED" | "TOKEN_EXPIRED" | "CONNECTION_SUPERSEDED" } };
 
 /** The authenticated identity used by Project Room realtime access checks. */
 export interface ProjectRoomRealtimeActor {
@@ -194,6 +210,15 @@ export function isProjectRoomEventId(value: unknown): value is string {
   return parseProjectRoomEventId(value) !== undefined;
 }
 
+/** projectId sentinel marking a per-user event channel inside the room broker. */
+export const PROJECT_ROOM_USER_CHANNEL_PROJECT = "__user_channel__";
+
+/** Builds the per-user broker scope used for membership and read broadcasts. */
+export function projectRoomUserEventScope(tenantId: string, userId: string): ProjectRoomEventScope {
+  if (!tenantId || !userId) throw new TypeError("Project Room user scope requires non-empty identifiers");
+  return { tenantId, roomId: `__user__:${userId}`, projectId: PROJECT_ROOM_USER_CHANNEL_PROJECT };
+}
+
 function isoDate(value: unknown): string | undefined {
   if (typeof value !== "object" || value === null) return undefined;
   try {

package/src/__tests__/ProjectRoomReadStateProtocol.test.ts

@@ -0,0 +1,16 @@
+import { projectRoomUserEventScope, parseProjectRoomEventId } from "../ProjectRoomRealtimeProtocol";
+
+describe("projectRoomUserEventScope", () => {
+  it("builds a stable per-user scope that cannot collide with room scopes", () => {
+    expect(projectRoomUserEventScope("t1", "u1")).toEqual({
+      tenantId: "t1", roomId: "__user__:u1", projectId: "__user_channel__",
+    });
+    expect(projectRoomUserEventScope("t1", "u1")).toEqual(projectRoomUserEventScope("t1", "u1"));
+    expect(projectRoomUserEventScope("t1", "u2")).not.toEqual(projectRoomUserEventScope("t1", "u1"));
+  });
+  it("user scope ids are valid broker event id candidates", () => {
+    const scope = projectRoomUserEventScope("t1", "u1");
+    expect(typeof scope.roomId).toBe("string");
+    expect(parseProjectRoomEventId(`${"0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"}:1`)?.sequence).toBe(1);
+  });
+});

package/src/__tests__/ProjectRoomStores.test.ts

@@ -264,6 +264,10 @@ class FakeProjectRoomMessageStore implements ProjectRoomMessageStore {
     const [tenantId, id] = args;
     return tenantId === "tenant-1" && id === "message-1" ? message : null;
   }
+
+  async countAfter(input: Parameters<ProjectRoomMessageStore["countAfter"]>[0]): Promise<number> {
+    return input.tenantId === "tenant-1" && input.roomId === "room-1" ? 1 : 0;
+  }
 }
 
 describe("ProjectRoomStore", () => {

package/src/index.ts

@@ -56,6 +56,7 @@ export * from "./ProjectRoomStoreProtocol";
 export * from "./ProjectMembershipStoreProtocol";
 export * from "./ProjectBotMembershipStoreProtocol";
 export * from "./ProjectRoomMessageStoreProtocol";
+export * from "./ProjectRoomReadStateProtocol";
 export * from "./ExactDataSnapshot";
 export * from "./ProjectRoomRealtimeProtocol";