@rytass/bpm-core-nestjs-module 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -9,6 +9,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Releases are managed by [`nx release`](https://nx.dev/recipes/nx-release) with
 Conventional Commits — see `nx.json` for the release config.
 
+## 0.1.6 — 2026-05-28
+
+### Added
+
+- **`MemberNotFoundException`** is now exported from the root barrel
+  (and `/identity` subpath). The `BPMMemberResolver.resolve` JSDoc has
+  referenced this class for two releases without actually shipping it;
+  hosts can now `throw new MemberNotFoundException(memberId)` directly.
+
+### Documentation
+
+- **README "Mapping from a host RBAC system (e.g. Casbin)"**: worked
+  example showing how to project a host's grouping policy
+  (`enforcer.getRolesForUser(memberId)`) into BPM's exact-string role
+  literals inside `authContextFactory`.
+- **README "Cross-origin authentication"** under Attachment Storage:
+  documents that signed URLs carry auth inside the URL (not via cookie),
+  what the TTL controls, and the production-grade defenses on top.
+- **README "Disabling the `/auth/test-members` endpoint in production"**:
+  clarifies that the endpoint is wrapper-host-owned (BPM does not
+  register it) and that the React client degrades gracefully when the
+  endpoint is absent.
+- **README Worked Example rewritten** to call the actual published
+  `@rytass/bpm-core-client/organization` exports
+  (`readOrganizationDashboard`, flat-input `createOrgUnit` /
+  `updateOrgUnit`) — the 0.1.5 example called functions that didn't
+  exist. Adds an "Atomicity caveat" note clarifying that only
+  `commitOrgUnitTreeDraft` is transactional; sequential
+  `createMembership` calls are independent.
+
+### Why a patch
+
+`MemberNotFoundException` is purely additive. Other changes are docs.
+
+## 0.1.5 — 2026-05-28
+
+### Documentation
+
+- **Identity contract clarifications.** `BPMMemberResolver.resolve` JSDoc
+  now states the unknown-id contract explicitly (throw
+  `MemberNotFoundException`); `resolveMany` documents the diverging
+  partial-success contract (omit unknown ids from the returned `Map`).
+  Both methods cross-link `identityMemberMetadataCacheTtlMs`
+  (default 5 min) so consumers know BPM caches their resolver responses.
+- **`BPMRootModule` JSDoc dangling refs removed.** The previous
+  references to `docs/10-bpm-embedding-auth.md` and
+  `docs/11-consumer-quickstart.md` (files that never shipped) are now
+  inline pointers to the README sections.
+- **New "Organization data ownership" README section.** Documents that
+  BPM is authoritative for `org_units`, `positions`, `memberships`, and
+  `manager_resolutions` (no host-injectable resolver pattern, unlike
+  members), the rationale (approver-routing / tree-diff hot path), the
+  mirror pattern using `OrgUnit.code` as the natural key and the
+  `metadata` JSON for host foreign-keys, and an idempotent worked
+  example using only `@rytass/bpm-core-client/organization` exports.
+
+### Why a patch
+
+No public type signatures change. JSDoc + README only.
+
+## 0.1.4 — 2026-05-27
+
+### Fixed
+
+- **Re-publish of the 0.1.3 release.** The 0.1.3 tarball was inadvertently
+  published from `libs/bpm-core/` instead of from `dist/libs/bpm-core/`,
+  shipping only TypeScript sources with `main: "./src/index.js"` pointing
+  at non-existent files. 0.1.3 has been **deprecated on npm**. The
+  publish procedure (`docs/api-reference.md` Publish Procedure section
+  and `tools/publish/finalize-dist-package.mjs` header) now codifies the
+  correct flow: `nx build` → `finalize-dist-package.mjs` →
+  `cd dist/libs/<pkg> && npm publish`.
+
+### Documentation
+
+- Publish-procedure-from-dist section added to `docs/api-reference.md`.
+- `tools/publish/finalize-dist-package.mjs` header warning expanded.
+
+## 0.1.3 — 2026-05-27 (deprecated on npm)
+
+**DO NOT INSTALL — broken release.** Published from source dir instead
+of dist dir; tarball contains only `.ts` files. Use 0.1.4 or newer.
+
 ## 0.1.2 — 2026-05-27
 
 ### Fixed

package/README.md

@@ -215,6 +215,60 @@ clear admin / designer guards; otherwise BPM resolvers reject with
 `BPMAuthenticatedGuard`. The host does not need to add `@BPMAuthenticated()`
 on top of them.
 
+### Mapping from a host RBAC system (e.g. Casbin)
+
+BPM does not call the host's RBAC engine — it reads exact-string `roles`
+and `permissions` arrays off `BPMAuthContext`. Hosts using Casbin /
+Permify / OPA must **project their grouping policy** into the BPM
+literals inside their `authContextFactory`. A worked Casbin example:
+
+```ts
+import { Inject, Injectable, type ExecutionContext } from '@nestjs/common';
+import { GqlExecutionContext } from '@nestjs/graphql';
+import { CASBIN_ENFORCER, type CasbinEnforcer } from '@your-host/auth';
+import type { BPMAuthContext } from '@rytass/bpm-core-nestjs-module';
+
+const HOST_TO_BPM_ROLES: Readonly<Record<string, string>> = {
+  approval_admin: 'BPM_ADMIN',
+  approval_designer: 'BPM_DESIGNER',
+};
+
+@Injectable()
+export class BPMAuthContextFactory {
+  constructor(@Inject(CASBIN_ENFORCER) private readonly enforcer: CasbinEnforcer) {}
+
+  async build(ctx: ExecutionContext): Promise<BPMAuthContext | null> {
+    const req = GqlExecutionContext.create(ctx).getContext<{
+      req?: { member?: { id: string; email: string; name: string } };
+    }>().req;
+    const member = req?.member;
+    if (!member) return null;
+
+    // 1. Look up the host's Casbin role assignments for this member.
+    const hostRoles = await this.enforcer.getRolesForUser(member.id);
+
+    // 2. Translate into BPM's exact-string literals. Unknown host roles
+    //    do nothing — BPM only checks for the documented strings.
+    const bpmRoles = hostRoles
+      .map((r) => HOST_TO_BPM_ROLES[r])
+      .filter((r): r is string => Boolean(r));
+
+    return {
+      memberId: member.id,
+      email: member.email,
+      name: member.name,
+      roles: bpmRoles,
+      permissions: [], // Host can also use `bpm:*` style permissions if preferred.
+      metadata: {},
+    };
+  }
+}
+```
+
+> The host owns the mapping table. Keep it in one place (a constant
+> module or a database table) so adding a new BPM tier in a future
+> BPMCore release becomes a one-line addition.
+
 ## Member Resolver
 
 The package resolves display names, email addresses, and approver candidates
@@ -275,6 +329,171 @@ export interface BPMMemberResolver {
 }
 ```
 
+## Organization Data Ownership
+
+> **Read this before integrating BPM into a host that already has its own
+> organization model.** The org-integration shape is **asymmetric** with
+> member integration above — knowing which side owns what saves a day of
+> source spelunking.
+
+### Ownership claim
+
+BPM is the **sole authority** for four organization tables:
+
+| Table | Owns |
+|---|---|
+| `org_units` | Department / division / company nodes (typed by `OrgUnitType`) |
+| `positions` | Job titles, with optional org-unit scoping |
+| `memberships` | Member × org-unit × position relations (the join table that puts a member at a position inside a unit) |
+| `manager_resolutions` | "Who is whose manager" rules (per-member, per-org-unit, or per-position scope), consumed by the `ORG_MANAGER` approver resolver |
+
+There is **no** host-injectable `OrgUnitResolver` / `PositionResolver` /
+`MembershipResolver` pattern, deliberately so. If you went looking for
+the symmetric counterpart to `BPMMemberResolver`, stop now — it doesn't
+exist, and the rest of this section explains why and what to do instead.
+
+### Why no resolver
+
+The BPM workflow engine reads the org graph on hot paths:
+
+- **Approver routing** — every running instance evaluates `UserTaskNode`
+  candidates (resolved via `DIRECT`, `POSITION`, `ORG_MANAGER`, or
+  `CANDIDATE_GROUP`) against the current org snapshot. A `ParallelGateway`
+  fanning out to "all managers in the IT division" may touch dozens of
+  membership rows in one step.
+- **Tree-diff commits** — `commitOrgUnitTreeDraft` writes batched moves
+  inside a single transaction, with referential integrity against
+  `memberships` and `manager_resolutions`. Round-tripping each lookup
+  through a host adapter would make this prohibitively chatty.
+- **Reporting** — admin dashboards aggregate counts across the full graph.
+
+A read-through adapter would force the host to mirror BPM's tree
+semantics (ltree paths, soft-delete masking, position-vs-org-unit join
+shape) anyway. We chose to make BPM authoritative so the contract is one
+direction only.
+
+### Mirror pattern
+
+Host applications that already maintain their own org structure should
+**mirror their data into BPM** through the GraphQL mutations exposed by
+`@rytass/bpm-core-client/organization`. Three rules keep this idempotent
+and observable:
+
+1. **`OrgUnit.code` is your natural key.** Every `createOrgUnit` /
+   `createPosition` accepts a `code` field that you control. BPM enforces
+   uniqueness; use your host's stable identifier here (e.g. an LDAP DN
+   slug or a internal ERP code). On a re-sync, look up existing entities
+   by `code` before deciding INSERT vs UPDATE.
+2. **`metadata` is the host-FK stash.** Both `OrgUnit` and `Membership`
+   carry an opaque `metadata` JSON object that BPM never introspects.
+   Store your host's primary key here (e.g. `{ shuttleOrgUnitId: 12345 }`)
+   so you can chase the back-pointer when reconciling.
+3. **Soft delete via `deleteOrgUnit` / `deleteMembership`.** Deletes set
+   `deletedAt` rather than removing rows. BPM's query layer hides
+   soft-deleted rows automatically; reading `orgUnitCount()` will report
+   the live count.
+
+### Worked example: idempotent sync
+
+The example below uses only published exports from
+`@rytass/bpm-core-client/organization`. It loads the entire BPM-side
+state once via `readOrganizationDashboard()`, builds a `code → record`
+index, then upserts each host node. Verified exports (all with flat
+input shapes — no `{id, input: {...}}` wrapping):
+
+- `readOrganizationDashboard({ orgUnitPageSize, orgUnitSearchText, ... })`
+- `createOrgUnit({ code, name, type, parentId, metadataJson })`
+- `updateOrgUnit({ id, code, name, type, parentId, metadataJson })`
+- `deleteOrgUnit(id)` (soft-delete)
+- `commitOrgUnitTreeDraft({ baseUpdatedAt, draft })` (transactional batch moves)
+- `createPosition` / `updatePosition` (key on `code`)
+- `createMembership` / `updateMembership` (unique by `(memberId, orgUnitId, positionId)`)
+- `createManagerResolution` / `updateManagerResolution`
+
+```ts
+import {
+  readOrganizationDashboard,
+  createOrgUnit,
+  updateOrgUnit,
+  type OrgUnitRecord,
+} from '@rytass/bpm-core-client/organization';
+import type { OrgUnitType } from '@rytass/bpm-core-shared';
+
+interface HostOrgUnit {
+  readonly hostId: string;          // e.g. ERP primary key — your host-FK
+  readonly code: string;            // stable across sync runs
+  readonly name: string;
+  readonly type: OrgUnitType;       // 'COMPANY' | 'DIVISION' | 'DEPARTMENT' | 'TEAM'
+  readonly parentCode: string | null;
+}
+
+async function syncOrgTree(
+  hostNodes: readonly HostOrgUnit[],
+): Promise<void> {
+  // 1. Single round trip: load every existing BPM org unit, index by code.
+  const dashboard = await readOrganizationDashboard({ orgUnitPageSize: null });
+  const byCode = new Map<string, OrgUnitRecord>(
+    dashboard.orgUnits.map((unit) => [unit.code, unit]),
+  );
+
+  // 2. Topo-sort by parent so a parent always exists before its child
+  //    is upserted (createOrgUnit needs the parentId to be valid).
+  const ordered = topoSortByParent(hostNodes);
+
+  for (const host of ordered) {
+    const parentId =
+      host.parentCode != null ? (byCode.get(host.parentCode)?.id ?? null) : null;
+    const metadataJson = JSON.stringify({ hostId: host.hostId });
+    const existing = byCode.get(host.code);
+
+    const saved = existing
+      ? await updateOrgUnit({
+          id: existing.id,
+          code: host.code,
+          name: host.name,
+          type: host.type,
+          parentId,
+          metadataJson,
+        })
+      : await createOrgUnit({
+          code: host.code,
+          name: host.name,
+          type: host.type,
+          parentId,
+          metadataJson,
+        });
+
+    byCode.set(saved.code, saved);
+  }
+}
+```
+
+The same pattern works for `Position` (key on `code`), `Membership`
+(unique by `memberId × orgUnitId × positionId`), and
+`ManagerResolution` (unique by scope shape + active flag). For bulk
+tree-shape changes (multi-node moves under a single parent),
+`commitOrgUnitTreeDraft` accepts the full draft in one transaction.
+
+> **Atomicity caveat.** Only `commitOrgUnitTreeDraft` is transactional.
+> Sequential `createMembership` / `createPosition` calls are independent
+> mutations — if the 401st call in a batch of 500 fails, the prior 400
+> stay committed. Wrap your sync loop in a "from-cursor" resume strategy
+> if you need at-least-once semantics across crashes.
+
+> **Programmatic base URL.** Server-side scripts that aren't running
+> under Next.js (cron workers, one-off seeds) cannot rely on
+> `NEXT_PUBLIC_API_URL` resolution — call `configureBPMClient({ baseUrl,
+> fetch, headers })` from `@rytass/bpm-core-client` once at startup to
+> point the transport at the right host and inject a session cookie or
+> bearer token.
+
+### What you do NOT mirror
+
+Member identity itself stays in your host's user table — BPM reaches it
+through `BPMMemberResolver` (see the previous section). Only the
+**org structure** (who reports where, what unit they sit in, who manages
+them) needs to live inside BPM.
+
 ## Root Module Configuration
 
 Use `BPMRootModule.forRoot()` for static configuration or
@@ -517,6 +736,43 @@ bootstrap, `attachmentRoutePrefix` must be supplied at module wiring time:
 - A process can only mount BPM under a single prefix. Multi-tenant hosts that
   want different prefixes per tenant should run separate processes.
 
+### Cross-origin authentication
+
+Signed attachment URLs carry the auth **inside the URL** itself —
+specifically a query-string signature derived from
+`attachmentSignedUrlSecret` and `attachmentSignedUrlTtlSeconds`. The
+browser does **not** send the session cookie to fetch the attachment;
+BPM's controller verifies the signature instead.
+
+This means:
+
+- The attachment URL is safe to embed in `<img>` / `<a href>` /
+  `<iframe>` tags across origins; CORS is not in the auth path.
+- Anyone who possesses the URL (until TTL expiry) can fetch the file.
+  Choose `attachmentSignedUrlTtlSeconds` short enough that a leaked URL
+  expires before exploitation (we suggest **600s** in production).
+- Hosts that need true cross-tenant isolation should keep
+  `attachmentPublicBaseUrl` pointing at a CDN edge that enforces its own
+  authz on top — BPM's signature is freshness, not authorization.
+
+### Disabling the `/auth/test-members` endpoint in production
+
+Hosts wired with the demo seed (typical for `pnpm demo:reset` /
+`pnpm staging:reset`) expose `GET /auth/test-members` so the login form
+shows a clickable list of fixture accounts. **Do not ship this in
+production.** Two ways to keep it out:
+
+1. The endpoint is **owned by the wrapper host**, not by BPM —
+   `@rytass/bpm-core-nestjs-module` does not register it. Simply omit
+   the wrapper module / controller that serves
+   `/auth/test-members`. The reference implementation in BPMCore's
+   `apps/api` only exposes it when `NODE_ENV !== 'production'`; copy
+   that pattern in your own auth controller.
+2. The browser-side `listApiTestMembers()` client function tolerates a
+   `404` / `401` and returns an empty array, so removing the endpoint
+   degrades gracefully — the login form simply hides the demo-account
+   picker.
+
 ## Notifications and SLA
 
 BPM creates in-app notifications by default. Email and webhook delivery are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/bpm-core-nestjs-module",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Embeddable NestJS BPM approval workflow module: workflow engine, approval templates, forms, organization/member contracts, attachments, signatures, notifications, delegation, and TypeORM migrations.",
   "keywords": [
     "bpm",
@@ -141,7 +141,7 @@
     "@nestjs/core": "^11.0.0",
     "@nestjs/graphql": "^13.4.0",
     "@nestjs/typeorm": "^11.0.1",
-    "@rytass/bpm-core-shared": "^0.1.4",
+    "@rytass/bpm-core-shared": "^0.1.6",
     "@rytass/secret-adapter-vault-nestjs": "^0.4.5 || ^0.5.0",
     "express": "^4.0.0 || ^5.0.0",
     "graphql": "^16.0.0",

package/src/lib/bpm/bpm-root.module.d.ts

@@ -112,9 +112,9 @@ export interface BPMRootModuleAsyncOptions extends Pick<ModuleMetadata, 'imports
  *
  * Hosts call `forRoot` or `forRootAsync` once from their root `AppModule`.
  * BPMCore does **not** own login, GraphQL setup, TypeORM bootstrap, or
- * Vault loading — those remain the host's responsibility. See
- * `docs/10-bpm-embedding-auth.md` and `docs/11-consumer-quickstart.md` for
- * the full contract.
+ * Vault loading — those remain the host's responsibility. See the
+ * package README sections "Embedding & auth", "Organization data
+ * ownership", and "Consumer quickstart" for the full contract.
  *
  * The host must avoid Nest's `app.setGlobalPrefix(...)`; BPM controllers
  * mount at relative paths driven by their respective options (notably

package/src/lib/bpm/bpm-root.module.js

@@ -24,9 +24,9 @@ const workflow_engine_module_1 = require("../workflow-engine/workflow-engine.mod
  *
  * Hosts call `forRoot` or `forRootAsync` once from their root `AppModule`.
  * BPMCore does **not** own login, GraphQL setup, TypeORM bootstrap, or
- * Vault loading — those remain the host's responsibility. See
- * `docs/10-bpm-embedding-auth.md` and `docs/11-consumer-quickstart.md` for
- * the full contract.
+ * Vault loading — those remain the host's responsibility. See the
+ * package README sections "Embedding & auth", "Organization data
+ * ownership", and "Consumer quickstart" for the full contract.
  *
  * The host must avoid Nest's `app.setGlobalPrefix(...)`; BPM controllers
  * mount at relative paths driven by their respective options (notably

package/src/lib/identity/index.d.ts

@@ -1,3 +1,4 @@
 export * from './identity-options';
 export * from './member-base.adapter';
+export * from './member-not-found.exception';
 export * from './member-resolver.interface';

package/src/lib/identity/index.js

@@ -3,5 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./identity-options"), exports);
 tslib_1.__exportStar(require("./member-base.adapter"), exports);
+tslib_1.__exportStar(require("./member-not-found.exception"), exports);
 tslib_1.__exportStar(require("./member-resolver.interface"), exports);
 //# sourceMappingURL=index.js.map

package/src/lib/identity/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/identity/index.ts"],"names":[],"mappings":";;;AAAA,6DAAmC;AACnC,gEAAsC;AACtC,sEAA4C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/identity/index.ts"],"names":[],"mappings":";;;AAAA,6DAAmC;AACnC,gEAAsC;AACtC,uEAA6C;AAC7C,sEAA4C"}

package/src/lib/identity/member-not-found.exception.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Thrown by `BPMMemberResolver.resolve(memberId)` when the host's user
+ * directory has no entry for the requested id. BPM surfaces the error
+ * as a GraphQL `errors[]` entry on whichever query triggered the
+ * lookup; the caller receives a structured response rather than a
+ * synthetic placeholder member.
+ *
+ * Note: `BPMMemberResolver.resolveMany(ids)` has the **opposite**
+ * contract — unknown ids are silently omitted from the returned `Map`.
+ * Use this exception only inside the single-id `resolve` path.
+ *
+ * Hosts may throw any `Error` subclass; this class is provided as a
+ * recommended default so error messages stay consistent in BPM's logs.
+ */
+export declare class MemberNotFoundException extends Error {
+    readonly memberId: string;
+    constructor(memberId: string, message?: string);
+}

package/src/lib/identity/member-not-found.exception.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemberNotFoundException = void 0;
+/**
+ * Thrown by `BPMMemberResolver.resolve(memberId)` when the host's user
+ * directory has no entry for the requested id. BPM surfaces the error
+ * as a GraphQL `errors[]` entry on whichever query triggered the
+ * lookup; the caller receives a structured response rather than a
+ * synthetic placeholder member.
+ *
+ * Note: `BPMMemberResolver.resolveMany(ids)` has the **opposite**
+ * contract — unknown ids are silently omitted from the returned `Map`.
+ * Use this exception only inside the single-id `resolve` path.
+ *
+ * Hosts may throw any `Error` subclass; this class is provided as a
+ * recommended default so error messages stay consistent in BPM's logs.
+ */
+class MemberNotFoundException extends Error {
+    constructor(memberId, message) {
+        super(message ?? `BPM member not found: ${memberId}`);
+        this.name = 'MemberNotFoundException';
+        this.memberId = memberId;
+    }
+}
+exports.MemberNotFoundException = MemberNotFoundException;
+//# sourceMappingURL=member-not-found.exception.js.map

package/src/lib/identity/member-not-found.exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"member-not-found.exception.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/identity/member-not-found.exception.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;GAaG;AACH,MAAa,uBAAwB,SAAQ,KAAK;IAGhD,YAAY,QAAgB,EAAE,OAAgB;QAC5C,KAAK,CAAC,OAAO,IAAI,yBAAyB,QAAQ,EAAE,CAAC,CAAC;QACtD,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AARD,0DAQC"}

package/src/lib/identity/member-resolver.interface.d.ts

@@ -21,17 +21,55 @@ export declare const MEMBER_RESOLVER: symbol;
  * BPM never reads the host's user table directly — it only knows
  * `memberId` strings and asks this resolver for any additional information.
  *
- * - `resolve` is called per missing id; throwing here surfaces as a BPM
- *   GraphQL error.
- * - `resolveMany` is the batched form BPM prefers when many ids are needed.
- *   Implementations may de-duplicate / cache as they see fit; missing ids
- *   should be omitted from the result `Map`.
- * - `search` is optional. When omitted, BPM's `searchMembers` GraphQL
- *   query simply returns an empty array.
+ * ## Caching
+ *
+ * BPM caches resolver responses in the `member_metadata_cache` table
+ * with a configurable TTL (`identityOptions.memberMetadataCacheTtlMs`,
+ * default 5 minutes — `IDENTITY_MEMBER_METADATA_CACHE_TTL_MS_DEFAULT`).
+ * Hosts do **not** need to add their own cache layer for the common
+ * case; implementations may layer additional caching if they have a
+ * faster source of truth (e.g. an in-process LRU over a remote auth
+ * service). The two layers do not coordinate — BPM's row-level cache
+ * is invalidated only by TTL expiry, never by host signals.
+ *
+ * ## Unknown-id contract (the two methods diverge intentionally)
+ *
+ * - `resolve(id)` is the **single-id, must-succeed** form. Throw
+ *   `MemberNotFoundException` (or any error) when `memberId` is unknown
+ *   — the caller is asking about one specific member and a partial
+ *   answer is meaningless. BPM surfaces the error as a GraphQL
+ *   `errors[]` entry on the originating query.
+ * - `resolveMany(ids)` is the **batched, partial-success** form BPM
+ *   prefers when many ids are needed (e.g. resolving the assignee list
+ *   on a task page). Implementations should **omit** unknown ids from
+ *   the returned `Map` rather than throwing; BPM treats missing entries
+ *   as deleted/anonymized members and renders a placeholder. Throwing
+ *   here aborts the entire batch and fails the GraphQL query — almost
+ *   never the right choice.
+ * - `search(text)` is optional. When omitted, BPM's `searchMembers`
+ *   GraphQL query returns an empty array (the picker UI degrades to
+ *   id-only entry).
+ *
+ * Implementations may de-duplicate within a single call freely.
  */
 export interface BPMMemberResolver {
+    /**
+     * Single-id lookup. **Throw** (e.g. `MemberNotFoundException`) when
+     * the id is unknown — BPM surfaces the error to the caller. Result is
+     * row-cached by BPM with TTL `identityOptions.memberMetadataCacheTtlMs`.
+     */
     resolve(memberId: string): Promise<MemberMetadata>;
+    /**
+     * Batched lookup. **Omit** unknown ids from the returned `Map`
+     * (do not throw) — BPM renders missing entries as deleted/anonymized
+     * members. Cached per-id under the same TTL as `resolve`.
+     */
     resolveMany(memberIds: readonly string[]): Promise<ReadonlyMap<string, MemberMetadata>>;
+    /**
+     * Optional free-text search. Return up to ~50 best matches; BPM does
+     * not paginate the result. Omit the method entirely to disable
+     * member-picker search.
+     */
     search?(searchText: string): Promise<readonly MemberMetadata[]>;
 }
 /**