@axiom-lattice/protocols 4.1.0 → 4.1.2

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

@@ -0,0 +1,78 @@
+/**
+ * Capability bundle persistence protocol.
+ *
+ * A capability bundle is a tenant-scoped, flat collection of middleware
+ * configurations that can be selected by a project.
+ */
+
+import type { AgentMiddlewareConfig } from "./AgentLatticeProtocol";
+
+/** A tenant-scoped collection of middleware configurations. */
+export interface CapabilityBundle {
+  /** Stable bundle identifier. */
+  readonly id: string;
+  /** Tenant that owns the bundle. */
+  tenantId: string;
+  /** Tenant-local unique key. */
+  key: string;
+  /** Human-readable bundle name. */
+  name: string;
+  /** Optional bundle description. */
+  description?: string;
+  /** Middleware configurations contained in the bundle. */
+  capabilities: AgentMiddlewareConfig[];
+  /** Creation timestamp in ISO string format. */
+  createdAt: string;
+  /** Last update timestamp in ISO string format. */
+  updatedAt: string;
+}
+
+/** Public input used to create a capability bundle; the tenant-local key is generated internally. */
+export interface CreateCapabilityBundleInput {
+  /** Human-readable bundle name. */
+  name: string;
+  /** Optional bundle description. */
+  description?: string;
+  /** Middleware configurations contained in the bundle. */
+  capabilities: AgentMiddlewareConfig[];
+}
+
+/** Input with a generated key used by persistence implementations. */
+export interface InternalCreateCapabilityBundleInput extends Omit<CreateCapabilityBundleInput, "key"> {
+  key: string;
+}
+
+/** Public partial bundle update; the stable key is immutable and the revision is mandatory for gateway updates. */
+export interface UpdateCapabilityBundleInput extends Partial<CreateCapabilityBundleInput> {
+  expectedUpdatedAt: string;
+}
+
+/** Store input retained for internal maintenance callers that may omit CAS. */
+export interface InternalUpdateCapabilityBundleInput extends Partial<CreateCapabilityBundleInput> {
+  expectedUpdatedAt?: string;
+}
+
+/** Result returned when an update's expected revision no longer matches. */
+export interface CapabilityBundleUpdateConflict {
+  status: "conflict";
+}
+
+/** Result of deleting a bundle only when no tenant project references it. */
+export type CapabilityBundleDeleteResult = "deleted" | "not_found" | "in_use";
+
+/** Persistence operations for tenant-scoped capability bundles. */
+export interface CapabilityBundleStore {
+  /** Lists all bundles owned by a tenant. */
+  listByTenant(tenantId: string): Promise<CapabilityBundle[]>;
+  /** Gets one bundle by tenant and identifier. */
+  getById(tenantId: string, id: string): Promise<CapabilityBundle | null>;
+  /** Gets bundles by tenant and identifiers. */
+  getManyByIds(tenantId: string, ids: string[]): Promise<CapabilityBundle[]>;
+  /** Creates a bundle for a tenant. */
+  create(tenantId: string, input: InternalCreateCapabilityBundleInput): Promise<CapabilityBundle>;
+  /** Updates a bundle, or returns null when it does not exist. */
+  /** Omitted expectedUpdatedAt is reserved for internal maintenance callers. */
+  update(tenantId: string, id: string, input: InternalUpdateCapabilityBundleInput): Promise<CapabilityBundle | CapabilityBundleUpdateConflict | null>;
+  /** Atomically deletes a bundle unless a tenant project references it. */
+  deleteIfUnreferenced(tenantId: string, id: string): Promise<CapabilityBundleDeleteResult>;
+}

package/src/CapabilityRuntimeProtocol.ts

@@ -0,0 +1,82 @@
+/**
+ * Capability runtime and preview protocol definitions.
+ *
+ * These contracts describe the resolved middleware runtime and the
+ * provenance data exposed while composing project bundles.
+ */
+
+import type { AgentMiddlewareConfig } from "./AgentLatticeProtocol";
+
+/** Project configuration selecting ordered capability bundles. */
+export interface ProjectCapabilityConfig {
+  /** Bundle identifiers in composition order. */
+  capabilityBundleIds: string[];
+}
+
+/** Resolved middleware available to an agent execution. */
+export interface CapabilityRuntime {
+  /** Revision identifying the resolved capability set. */
+  revision: string;
+  /** Middleware indexed by middleware identifier. */
+  middleware: Record<string, AgentMiddlewareConfig>;
+}
+
+/** Provenance for a resolved capability field. */
+export interface CapabilityFieldSource {
+  /** Middleware type owning the field. */
+  capabilityType: string;
+  /** RFC 6901 escaped JSON Pointer path of the field within the middleware configuration. */
+  fieldPath: string;
+  /** Bundle that supplied the field value. */
+  sourceBundleId: string;
+  /** Supplied field value. */
+  value: unknown;
+}
+
+/** A later bundle value replacing an earlier field value. */
+export interface CapabilityOverride {
+  /** Middleware type owning the field. */
+  capabilityType: string;
+  /** RFC 6901 escaped JSON Pointer path of the overridden field. */
+  fieldPath: string;
+  /** Value supplied by the earlier bundle. */
+  previousValue: unknown;
+  /** Value supplied by the later bundle. */
+  nextValue: unknown;
+  /** Bundle that supplied the later value. */
+  sourceBundleId: string;
+}
+
+/** A warning or error produced while previewing bundle composition. */
+export interface CapabilityPreviewIssue {
+  /** Stable issue code. */
+  code: string;
+  /** Human-readable issue description. */
+  message: string;
+  /** Related bundle, when applicable. */
+  bundleId?: string;
+  /** Related middleware type, when applicable. */
+  capabilityType?: string;
+  /** Related middleware field path, when applicable. */
+  fieldPath?: string;
+}
+
+/** Result of composing capability bundles for a project. */
+export interface CapabilityPreview {
+  /** Bundle identifiers in composition order. */
+  bundleIds: string[];
+  /** Composed middleware configurations. */
+  capabilities: AgentMiddlewareConfig[];
+  /** Field replacements detected during composition. */
+  overrides: CapabilityOverride[];
+  /** Field-level provenance for composed values. */
+  sources: CapabilityFieldSource[];
+  /** Non-blocking composition issues. */
+  warnings: CapabilityPreviewIssue[];
+  /** Blocking composition issues. */
+  errors: CapabilityPreviewIssue[];
+  /** Revision identifying this preview. */
+  revision: string;
+  /** Bundle content revisions captured by this preview. */
+  bundleRevisions?: Record<string, string>;
+}

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

@@ -65,19 +65,63 @@ export interface PluginConnection {
 
 /**
  * 工具元信息（用于前端 allowedTools 筛选）
+ *
+ * New connection-backed plugin tools that select one connection must accept
+ * the selected key as `args.connectionKey`. Existing legacy tools retain their
+ * established resource argument names.
  */
 export interface PluginToolMeta {
   name: string;
   description: string;
 }
 
+/**
+ * A text file included in a plugin skill bundle.
+ *
+ * @property content - Text content written to the skill resource file.
+ * @property mimeType - Optional MIME type for consumers that need it.
+ */
+export interface PluginSkillResource {
+  content: string;
+  mimeType?: string;
+}
+
+/**
+ * Versioned definition of a plugin-provided skill.
+ *
+ * @property version - Bundle version used to detect resource updates.
+ * @property content - Complete SKILL.md markdown content.
+ * @property resources - Optional text resources keyed by safe relative paths.
+ */
+export interface PluginSkillDefinition {
+  version: string;
+  content: string;
+  resources?: Record<string, PluginSkillResource>;
+}
+
+/**
+ * Standard configuration for a new connection-backed plugin.
+ *
+ * `PluginMeta.type` is also the Connection Store type. `connections` selects
+ * connection keys of that type; `connectAll` opts into using all available
+ * connections of that type. Do not add a separate connection or resource type
+ * or selector field to this configuration.
+ */
+export type PluginStandardConnectionConfig = {
+  connections: string[];
+  connectAll?: boolean;
+};
+
 /**
  * 插件元数据（开发者声明）
  *
  * connectionSchema 不在此类型中——由 serializePluginMeta 自动推导后注入 PluginMetaOutput。
  */
 export interface PluginMeta {
-  /** 插件唯一标识，如 "erp" */
+  /**
+   * 插件唯一标识，如 "erp"; for connection-backed plugins this is also the
+   * Connection Store type.
+   */
   type: string;
   /** 显示名称 */
   name: string;
@@ -91,9 +135,13 @@ export interface PluginMeta {
   icon?: string;
   /** 工具清单（可选，middleware 能自动提取时不需要写） */
   tools?: PluginToolMeta[];
-  /** 中间件配置 schema（用于 agent 配置面板） */
+  /**
+   * 中间件配置 schema（用于 agent 配置面板）。新的 connection-backed
+   * plugins use `connections: string[]` and optional `connectAll?: boolean`.
+   * Do not introduce connectionType, resourceType, or resourceSelector fields.
+   */
   configSchema?: Record<string, unknown>;
-  /** 默认配置 */
+  /** 默认配置；connection-backed plugins use PluginStandardConnectionConfig. */
   defaultConfig?: Record<string, unknown>;
   /** 推荐配置的 companion 插件 */
   recommends?: string[];
@@ -103,6 +151,8 @@ export interface PluginMeta {
    * 第三方插件可自定义分类名，前端会原样显示；未提供时归入 "Other"。
    */
   category?: string;
+  /** Whether this plugin's middleware may be included in capability bundles. */
+  capabilityBundleEligible?: boolean;
 }
 
 /**
@@ -133,7 +183,7 @@ export interface PluginMetaOutput extends PluginMeta {
  * const myPlugin: Plugin = {
  *   meta: { ... },
  *   middleware: (config, context) => {
- *     const skills = context?.pluginSkillContents ?? {};
+ *     const skills = context?.pluginSkills ?? {};
  *     return createMyMiddleware({ ...config, pluginSkills: skills });
  *   },
  * };
@@ -141,12 +191,14 @@ export interface PluginMetaOutput extends PluginMeta {
  */
 export interface PluginContext {
   /**
-   * Cross-plugin aggregated skill contents (SKILL.md, keyed by skill name).
+   * Cross-plugin aggregated skill bundles, keyed by skill name.
    * Collected from all enabled plugins before the main middleware loop.
    * Most plugins should ignore this; only cross-plugin coordination
    * middleware (e.g. skillMiddleware) consumes it.
    */
-  pluginSkillContents?: Record<string, string>;
+  pluginSkills?: Record<string, PluginSkillDefinition>;
+  /** Owning plugin type for each enabled plugin skill bundle. */
+  pluginSkillOwners?: Record<string, string>;
 }
 
 /**
@@ -197,7 +249,7 @@ export interface Plugin {
    * 名称必须以 "{pluginType}-" 为前缀，注册时校验。
    * Builder 在构建中间件之前从所有启用的插件中收集。
    */
-  skills?: Record<string, string>;
+  skills?: Record<string, PluginSkillDefinition>;
   /**
    * 插件贡献的 Agent 定义（以 agent key 为键）。
    * 在租户首次访问时通过 ensurePluginAgentsForTenant 按租户注册到

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