@axiom-lattice/protocols 4.1.1 → 4.1.3

package/src/BindingProtocol.ts

@@ -27,14 +27,97 @@ export interface CreateBindingInput {
   tenantId: string;
   senderId: string;
   agentId: string;
+  threadId?: string;
   threadMode?: "fixed" | "per_conversation";
   senderDisplayName?: string;
   senderMetadata?: Record<string, unknown>;
   workspaceId?: string;
   projectId?: string;
+  /** Whether the binding is eligible for inbound resolution immediately after creation. */
+  enabled?: boolean;
+}
+
+/** Filters binding records before pagination is applied. */
+export interface BindingListParams {
+  tenantId: string;
+  channel?: string;
+  agentId?: string;
+  channelInstallationId?: string;
+  /** Installation ID prefixes excluded before pagination, for internal namespaces. */
+  excludeInstallationIdPrefixes?: string[];
+  excludeChannels?: string[];
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Fields that may change after a binding is created.
+ *
+ * Binding identity (`id`, tenant, channel, installation, sender, and timestamps) is intentionally
+ * absent so every persistence backend can enforce tenant-scoped mutation without identity drift.
+ */
+export interface BindingMutablePatch {
+  /** Agent that receives messages for this subject. */
+  agentId?: string;
+  /** Fixed thread used when `threadMode` is `fixed`. */
+  threadId?: string;
+  /** Optional workspace execution scope. */
+  workspaceId?: string;
+  /** Optional project execution scope. */
+  projectId?: string;
+  /** Whether messages share one thread or create one per conversation. */
+  threadMode?: "fixed" | "per_conversation";
+  /** Human-readable sender label. */
+  senderDisplayName?: string;
+  /** Mutable sender metadata supplied by trusted internal callers. */
+  senderMetadata?: Record<string, unknown>;
+  /** Whether inbound resolution may use this binding. */
+  enabled?: boolean;
+}
+
+/** Raised when a channel installation already has a binding for the same tenant and sender. */
+export class DuplicateChannelBindingSubjectError extends Error {
+  constructor() {
+    super("A binding already exists for this channel subject");
+    this.name = "DuplicateChannelBindingSubjectError";
+  }
+}
+
+/** A duplicate subject found while upgrading a local channel-binding database. */
+export interface ChannelBindingMigrationConflict {
+  tenantId: string;
+  channel: string;
+  channelInstallationId: string;
+  senderId: string;
+  count: number;
+}
+
+/**
+ * Raised when a local binding uniqueness migration requires operator reconciliation.
+ *
+ * The conflict list contains only subject identifiers and row counts; binding metadata and other
+ * potentially sensitive payloads are never included.
+ */
+export class ChannelBindingMigrationConflictError extends Error {
+  readonly conflicts: ChannelBindingMigrationConflict[];
+
+  constructor(conflicts: ChannelBindingMigrationConflict[]) {
+    super(`Channel binding migration found ${conflicts.length} duplicate subject(s)`);
+    this.name = "ChannelBindingMigrationConflictError";
+    this.conflicts = conflicts;
+  }
 }
 
 export interface BindingRegistry {
+  findById(tenantId: string, id: string): Promise<Binding | null>;
+
+  findBySubject(params: {
+    tenantId: string;
+    channel: string;
+    channelInstallationId: string;
+    senderId: string;
+  }): Promise<Binding | null>;
+
   resolve(params: {
     channel: string;
     senderId: string;
@@ -43,18 +126,11 @@ export interface BindingRegistry {
   }): Promise<Binding | null>;
 
   create(binding: CreateBindingInput): Promise<Binding>;
-  update(id: string, patch: Partial<Binding>): Promise<Binding>;
-  delete(id: string): Promise<void>;
+  update(tenantId: string, id: string, patch: BindingMutablePatch): Promise<Binding>;
+  delete(tenantId: string, id: string): Promise<void>;
 
-  list(params: {
-    channel?: string;
-    agentId?: string;
-    tenantId: string;
-    channelInstallationId?: string;
-    limit?: number;
-    offset?: number;
-  }): Promise<Binding[]>;
+  list(params: BindingListParams): Promise<Binding[]>;
 
-  import(bindings: CreateBindingInput[]): Promise<Binding[]>;
+  import(tenantId: string, bindings: CreateBindingInput[]): Promise<Binding[]>;
   export(params: { tenantId: string }): Promise<Binding[]>;
 }

package/src/ChannelInstallationStoreProtocol.ts

@@ -1,5 +1,10 @@
-export type ChannelInstallationType = "lark" | "email" | "slack" | "wechat";
+/** Channel types persisted by the installation store, including internal-only channels. */
+export type ChannelInstallationType = "lark" | "email" | "slack" | "wechat" | "room";
 
+/** Channel types exposed by the public installation management API. */
+export type PublicChannelInstallationType = Exclude<ChannelInstallationType, "room">;
+
+/** Credentials and routing configuration for a Lark installation. */
 export interface LarkChannelInstallationConfig {
   appId: string;
   appSecret: string;
@@ -8,11 +13,13 @@ export interface LarkChannelInstallationConfig {
   assistantId?: string;
 }
 
+/** Credentials and identity configuration for a WeChat installation. */
 export interface WechatChannelInstallationConfig {
   botToken: string;
   uin?: string;
 }
 
+/** A persisted tenant-scoped channel installation. */
 export interface ChannelInstallation<TConfig = unknown> {
   id: string;
   tenantId: string;
@@ -26,15 +33,26 @@ export interface ChannelInstallation<TConfig = unknown> {
   updatedAt: Date;
 }
 
-export interface CreateChannelInstallationRequest {
+/** Internal input accepted by installation stores. */
+export interface CreateChannelInstallationInput {
   channel: ChannelInstallationType;
   name?: string;
-  config: LarkChannelInstallationConfig;
+  config: Record<string, unknown>;
   enabled?: boolean;
   fallbackAgentId?: string;
   rejectWhenNoBinding?: boolean;
 }
 
+type PublicInstallationBase = Omit<CreateChannelInstallationInput, "channel" | "config">;
+
+/** Public create request with channel-specific configuration and no internal room variant. */
+export type CreateChannelInstallationRequest = PublicInstallationBase & (
+  | { channel: "lark"; config: LarkChannelInstallationConfig }
+  | { channel: "wechat"; config: WechatChannelInstallationConfig }
+  | { channel: "email" | "slack"; config: Record<string, unknown> }
+);
+
+/** Fields accepted when updating an existing public installation. */
 export interface UpdateChannelInstallationRequest {
   name?: string;
   config?: Record<string, unknown>;
@@ -43,6 +61,7 @@ export interface UpdateChannelInstallationRequest {
   rejectWhenNoBinding?: boolean;
 }
 
+/** Persistence boundary for tenant-scoped channel installations. */
 export interface ChannelInstallationStore {
   getInstallationById(
     installationId: string,
@@ -64,7 +83,7 @@ export interface ChannelInstallationStore {
   createInstallation(
     tenantId: string,
     installationId: string,
-    data: CreateChannelInstallationRequest,
+    data: CreateChannelInstallationInput,
   ): Promise<ChannelInstallation>;
 
   updateInstallation(

package/src/ExactDataSnapshot.ts

@@ -0,0 +1,119 @@
+/** A safely extracted value from an own enumerable data-property descriptor. */
+export interface DescriptorDataValue {
+  ok: true;
+  value: unknown;
+}
+
+function ownDescriptorField(descriptor: object, key: string): unknown {
+  const field = Object.getOwnPropertyDescriptor(descriptor, key);
+  return field && Object.prototype.hasOwnProperty.call(field, "value")
+    ? field.value
+    : undefined;
+}
+
+/**
+ * Reads an own enumerable data-property descriptor without consulting its prototype.
+ *
+ * @param descriptor Property descriptor to inspect.
+ * @returns The descriptor value when it is an own enumerable data descriptor, otherwise `undefined`.
+ */
+export function descriptorDataValue(descriptor: unknown): DescriptorDataValue | undefined {
+  if (typeof descriptor !== "object" || descriptor === null) return undefined;
+  try {
+    const keys = Reflect.ownKeys(descriptor);
+    if (!keys.includes("value") || !keys.includes("enumerable")
+      || keys.includes("get") || keys.includes("set")) return undefined;
+    const valueField = Object.getOwnPropertyDescriptor(descriptor, "value");
+    if (!valueField || !Object.prototype.hasOwnProperty.call(valueField, "value")
+      || ownDescriptorField(descriptor, "enumerable") !== true) return undefined;
+    return { ok: true, value: valueField.value };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Copies an object-like value into a local plain record using only exact own enumerable data descriptors.
+ *
+ * Prototypes are deliberately ignored so records from other JavaScript realms remain valid and inherited
+ * behavior can never participate in validation.
+ *
+ * @param value Untrusted value to snapshot.
+ * @param required Own string keys that must be present.
+ * @param optional Own string keys that may be present.
+ * @returns A canonical local record, or `undefined` for malformed descriptors, keys, arrays, or proxies.
+ */
+export function snapshotExactRecord(
+  value: unknown,
+  required: readonly string[],
+  optional: readonly string[] = [],
+): Record<string, unknown> | undefined {
+  try {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+    const keys = Reflect.ownKeys(value);
+    const allowed = new Set([...required, ...optional]);
+    if (required.some((key) => !keys.includes(key))
+      || keys.some((key) => typeof key !== "string" || !allowed.has(key))) return undefined;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const descriptorKeys = Reflect.ownKeys(descriptors);
+    if (descriptorKeys.length !== keys.length || keys.some((key) => !descriptorKeys.includes(key))) return undefined;
+    const result: Record<string, unknown> = {};
+    for (const key of keys) {
+      if (typeof key !== "string") return undefined;
+      const descriptor = descriptors[key];
+      const data = descriptorDataValue(descriptor);
+      if (!data) return undefined;
+      Object.defineProperty(result, key, {
+        value: data.value,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      });
+    }
+    return result;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Copies a dense cross-realm array using only own element data descriptors and the intrinsic length descriptor.
+ *
+ * @param value Untrusted value to snapshot.
+ * @returns A canonical local dense array, or `undefined` for holes, extras, accessors, or malformed proxies.
+ */
+export function snapshotExactArray(value: unknown): unknown[] | undefined {
+  try {
+    if (!Array.isArray(value)) return undefined;
+    const keys = Reflect.ownKeys(value);
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const descriptorKeys = Reflect.ownKeys(descriptors);
+    if (descriptorKeys.length !== keys.length || keys.some((key) => !descriptorKeys.includes(key))) return undefined;
+    const lengthDescriptorField = Object.getOwnPropertyDescriptor(descriptors, "length");
+    const lengthDescriptor = lengthDescriptorField
+      && Object.prototype.hasOwnProperty.call(lengthDescriptorField, "value")
+      ? lengthDescriptorField.value
+      : undefined;
+    if (typeof lengthDescriptor !== "object" || lengthDescriptor === null
+      || Reflect.ownKeys(lengthDescriptor).some((key) => key === "get" || key === "set")
+      || !Object.prototype.hasOwnProperty.call(lengthDescriptor, "value")) return undefined;
+    const length = ownDescriptorField(lengthDescriptor, "value");
+    if (ownDescriptorField(lengthDescriptor, "enumerable") !== false
+      || ownDescriptorField(lengthDescriptor, "configurable") !== false
+      || ownDescriptorField(lengthDescriptor, "writable") !== true
+      || !Number.isSafeInteger(length) || typeof length !== "number" || length < 0
+      || keys.length !== length + 1) return undefined;
+    const result: unknown[] = [];
+    for (let index = 0; index < length; index += 1) {
+      const key = String(index);
+      const descriptor = descriptors[key];
+      const data = descriptorDataValue(descriptor);
+      if (!keys.includes(key) || !data) return undefined;
+      result.push(data.value);
+    }
+    if (keys.some((key) => typeof key !== "string" || (key !== "length" && !/^(0|[1-9]\d*)$/.test(key)))) return undefined;
+    return result;
+  } catch {
+    return undefined;
+  }
+}

package/src/ProjectBotMembershipStoreProtocol.ts

@@ -0,0 +1,48 @@
+import type {
+  ProjectBotMembership,
+} from "./ProjectRoomProtocol";
+
+/** Persistence operations for bot membership in a project room. */
+export interface ProjectBotMembershipStore {
+  /** Lists bot memberships belonging to a project. */
+  list(tenantId: string, projectId: string): Promise<ProjectBotMembership[]>;
+
+  /** Finds a bot membership by identifier within a tenant. */
+  findById(tenantId: string, id: string): Promise<ProjectBotMembership | null>;
+
+  /** Finds a bot membership by assistant within a project. */
+  findByAssistant(tenantId: string, projectId: string, assistantId: string): Promise<ProjectBotMembership | null>;
+
+  /**
+   * Saves a bot membership. A new row returns `created`, an existing active or
+   * paused row returns `updated`, and a removed row returns `reactivated`.
+   * `coordinator_conflict` means a non-removed
+   * coordinator already exists for the Tenant+Project; `mention_conflict`
+   * means the mention name is already used by an active or paused membership
+   * in the Tenant+room.
+   */
+  save(
+    input: Omit<ProjectBotMembership, "joinedAt" | "updatedAt">,
+  ): Promise<
+     | { kind: "created" | "updated" | "reactivated"; membership: ProjectBotMembership }
+    | { kind: "coordinator_conflict" | "mention_conflict" }
+  >;
+
+  /**
+   * Updates a bot membership using optimistic concurrency and uniqueness
+   * safeguards. `not_found` means the membership is not in the tenant;
+   * `conflict` means `updatedAt` differs from `expectedUpdatedAt`.
+   * `coordinator_conflict` applies to the one non-removed Coordinator per
+   * Tenant+Project rule; `mention_conflict` applies to mention uniqueness
+   * among active and paused memberships in the Tenant+room.
+   */
+  update(input: {
+    tenantId: string;
+    id: string;
+    patch: Partial<Pick<ProjectBotMembership, "role" | "title" | "responsibility" | "mentionName" | "status">>;
+    expectedUpdatedAt: Date;
+  }): Promise<
+    | { kind: "updated"; membership: ProjectBotMembership }
+    | { kind: "not_found" | "conflict" | "coordinator_conflict" | "mention_conflict" }
+  >;
+}

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;
+}