@rytass/bpm-core-nestjs-module 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -9,6 +9,73 @@ 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.7 — 2026-05-28
+
+### Documentation
+
+- **README "Bring-your-own-host-auth" recipe** added under Auth
+  Context. Documents the `ApiMember` JSON shape, the expected status
+  codes for `/auth/login`, `/auth/me`, `/auth/logout`, and two
+  integration patterns: (A) extend the host API with `/auth/*`
+  controllers that emit `ApiMember` (recommended for member-base
+  hosts), or (B) run a thin wrapper host on a separate subdomain.
+- **README "Sharing a Postgres cluster with the host"** added under
+  Database Setup. Compares same-schema / separate-schema / separate-DB
+  trade-offs, recommends separate-schema, clarifies Vault path
+  isolation between host and BPM.
+- **`commitOrgUnitTreeDraft` signature corrected** in the Worked
+  Example listing — previously `{ baseUpdatedAt, draft }` (incorrect),
+  now `{ moves: { id, parentId, baseUpdatedAt }[] }` matching the
+  actual export.
+- **`OrgUnitType` literal case corrected** in the README's example
+  comment — previously `'COMPANY' | 'DIVISION' | ...`, now `'company'
+  | 'division' | ...`. (See `@rytass/bpm-core-shared@0.1.7` for the
+  actual TS type change.)
+- **"Positions are intentionally not deletable" note** added to the
+  Organization mirror pattern. Explains why no `deletePosition`
+  mutation exists and how to retire a position safely.
+- **README "Package Status" current-version line refreshed** to
+  `0.1.7`.
+
+### Why a patch
+
+Documentation-only. No public API change beyond what
+`@rytass/bpm-core-shared@0.1.7` ships.
+
+## 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

package/README.md

@@ -14,7 +14,7 @@ directory integration, storage adapters, and deployment.
 
 ## Package Status
 
-Current version: `0.0.1`
+Current version: `0.1.7`
 
 The package is intended for NestJS backend hosts. It does not include the
 Next.js backoffice UI and does not provide a production auth system by itself.
@@ -198,6 +198,104 @@ class HostResolver {
 }
 ```
 
+### Bring-your-own-host-auth (for hosts that already have auth)
+
+The BPM React `<AuthProvider>` calls `POST /auth/login`, `GET /auth/me`,
+and `POST /auth/logout` on the BPM API host and expects responses that
+match the `ApiMember` shape (exported from `@rytass/bpm-core-client`):
+
+```ts
+interface ApiMember {
+  readonly memberId: string;
+  readonly email: string;
+  readonly name: string;
+  readonly roles: readonly string[];
+  readonly permissions: readonly string[];
+  readonly expiresAt: string; // ISO 8601
+}
+```
+
+Status-code contract:
+
+| Endpoint              | Success     | Failure                             |
+| --------------------- | ----------- | ----------------------------------- |
+| `POST /auth/login`    | `200` + `ApiMember` JSON      | `401` (bad credentials) / `400` (validation) |
+| `GET /auth/me`        | `200` + `ApiMember` JSON      | `401` (no session — React client treats as anonymous, not error) |
+| `POST /auth/logout`   | `204` (or `200` empty)        | `401` ignored |
+
+Session lifetime is owned by the host. The React `<AuthProvider>`
+relies on `credentials: 'include'` plus an HTTP-only cookie issued by
+the host on successful login — BPM does **not** issue cookies itself.
+
+Hosts that already have their own JWT / cookie auth have two integration
+patterns:
+
+#### Pattern A — Extend the host API surface
+
+Add `/auth/login`, `/auth/me`, `/auth/logout` controllers to your
+existing NestJS host. Internally those endpoints call the host's
+existing auth service (e.g. `MemberBaseService.login()`) and emit the
+`ApiMember` shape. This is the simplest integration when BPM and the
+host run on the same origin. Example for a member-base host:
+
+```ts
+@Controller('auth')
+export class HostAuthController {
+  constructor(private readonly memberBase: MemberBaseService) {}
+
+  @Post('login')
+  async login(@Body() input: LoginInput, @Res({ passthrough: true }) res: Response): Promise<ApiMember> {
+    const { member, accessToken, refreshToken } = await this.memberBase.login(input);
+    // Set the host's existing HTTP-only cookies; the React client will
+    // forward them on subsequent /auth/me and /graphql calls.
+    res.cookie('access_token', accessToken, { httpOnly: true, sameSite: 'lax' });
+    res.cookie('refresh_token', refreshToken, { httpOnly: true, sameSite: 'lax' });
+    return projectMemberToApiMember(member);
+  }
+
+  @Get('me')
+  async me(@Req() req: Request): Promise<ApiMember> {
+    const member = await this.memberBase.resolveCurrentMember(req); // throws 401 if no cookie
+    return projectMemberToApiMember(member);
+  }
+
+  @Post('logout')
+  @HttpCode(204)
+  logout(@Res({ passthrough: true }) res: Response): void {
+    res.clearCookie('access_token');
+    res.clearCookie('refresh_token');
+  }
+}
+```
+
+The `projectMemberToApiMember` helper is host-specific — map your own
+member shape to BPM's expectations, project Casbin roles into the BPM
+role-literal strings (see "Mapping from a host RBAC system" below),
+and compute `expiresAt` from the token TTL.
+
+#### Pattern B — Run BPM on a separate auth host
+
+When BPM lives on its own subdomain (e.g. `bpm.example.com`) separate
+from the main app at `app.example.com`, you can run a thin wrapper
+host that **only** owns the `/auth/*` endpoints and a session cookie
+scoped to `*.example.com`. The BPM React client points at this
+subdomain via `NEXT_PUBLIC_API_URL` / `NEXT_PUBLIC_API_AUTH_URL`
+(or `configureBPMClient` for server-side). The wrapper host
+internally calls back to the main app to verify the user.
+
+This pattern is heavier (cross-origin cookies, CORS) but lets the main
+app stay completely decoupled from BPM's auth surface. Use it only
+when a same-origin deployment is impossible.
+
+#### Cross-host auth precedence
+
+If the consumer wants the React client to skip the BPM auth entirely
+and rely on the host's existing session check at the Next.js layer,
+the simplest path is to **not mount `<AuthProvider>` from
+`@rytass/bpm-core-react`** and instead implement a host-side
+`useAuth()` shim that returns the host's session. This is rare — most
+consumers find Pattern A simpler.
+
 ## Role and Permission Contract
 
 BPM guards inspect `BPMAuthContext.roles` and `BPMAuthContext.permissions` with
@@ -215,6 +313,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
@@ -334,74 +486,90 @@ and observable:
    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
+3. **Soft delete via `deleteOrgUnit` / `deleteMembership` / `deleteManagerResolution`.** Deletes set
    `deletedAt` rather than removing rows. BPM's query layer hides
    soft-deleted rows automatically; reading `orgUnitCount()` will report
    the live count.
+4. **Positions are intentionally not deletable.** There is no
+   `deletePosition` mutation — positions are part of the historical
+   record (every signed approval task references the assignee's position
+   at sign time, so deleting a position would lose audit data). Retire a
+   position by removing all active memberships referencing it; the
+   position itself stays. Use `updatePosition({ id, name: 'retired-' + oldName, ... })`
+   if you want a UI hint that a position is no longer in use.
 
 ### Worked example: idempotent sync
 
 The example below uses only published exports from
-`@rytass/bpm-core-client/organization`. It pushes a host org tree into
-BPM, handling the create-or-update path by checking `code` matches.
-Verified exports: `orgUnits`, `createOrgUnit`, `updateOrgUnit`,
-`deleteOrgUnit`, `createPosition`, `createMembership`, `updateMembership`,
-`createManagerResolution`, `commitOrgUnitTreeDraft`.
+`@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({ moves: { id, parentId, baseUpdatedAt }[] })` (transactional batch moves — each entry's `baseUpdatedAt` is the row's last-known `updatedAt`, used by BPM for optimistic-locking conflict detection)
+- `createPosition` / `updatePosition` (key on `code`)
+- `createMembership` / `updateMembership` (unique by `(memberId, orgUnitId, positionId)`)
+- `createManagerResolution` / `updateManagerResolution`
 
 ```ts
 import {
+  readOrganizationDashboard,
   createOrgUnit,
   updateOrgUnit,
-  createPosition,
-  createMembership,
-  orgUnits,
   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 hostId: string;          // e.g. ERP primary key — your host-FK
+  readonly code: string;            // stable across sync runs
   readonly name: string;
-  readonly type: 'COMPANY' | 'DIVISION' | 'DEPARTMENT' | 'TEAM';
+  readonly type: OrgUnitType;       // 'company' | 'division' | 'department' | 'team'
   readonly parentCode: string | null;
 }
 
-async function syncOrgUnit(host: HostOrgUnit): Promise<OrgUnitRecord> {
-  // 1. Look up by host's stable code; BPM enforces uniqueness.
-  const existing = (
-    await orgUnits({ page: 1, pageSize: 1, searchText: host.code })
-  ).find((u) => u.code === host.code);
-
-  const parentId = host.parentCode
-    ? (await orgUnits({ searchText: host.parentCode })).find(
-        (u) => u.code === host.parentCode,
-      )?.id ?? null
-    : null;
-
-  // 2. Stash the host-FK back into metadata so future reconciliations
-  //    can chase the pointer either direction.
-  const metadataJson = JSON.stringify({ hostId: host.hostId });
-
-  if (existing) {
-    return updateOrgUnit({
-      id: existing.id,
-      input: {
-        code: host.code,
-        name: host.name,
-        type: host.type,
-        parentId,
-        metadataJson,
-      },
-    });
+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);
   }
-
-  return createOrgUnit({
-    code: host.code,
-    name: host.name,
-    type: host.type,
-    parentId,
-    metadataJson,
-  });
 }
 ```
 
@@ -411,6 +579,19 @@ The same pattern works for `Position` (key on `code`), `Membership`
 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
@@ -577,6 +758,32 @@ Required environment variables for direct Vault loading:
 | `VAULT_PASSWORD` | Vault userpass password.            |
 | `VAULT_PATH`     | Vault KV path, defaults to develop. |
 
+### Sharing a Postgres cluster with the host
+
+Hosts that already run their own Postgres (and their own Vault path,
+e.g. `shuttle/develop`) have three options for where BPM's 22 tables
+live. Pick the one that matches your operational model:
+
+| Option | When to use | Trade-off |
+|---|---|---|
+| **Same database, same schema (`public`)** | Tiny prototypes, monorepo dev | Table-name collision risk — BPM owns `org_units`, `positions`, etc., common names. Audit your host's tables before choosing. |
+| **Same database, separate schema** (recommended) | Most production hosts | Clean isolation; pg_dump per-schema; one connection pool. Set `DB_SCHEMA=bpm_core` in BPM's Vault path. Host stays on its own schema (typically `public`). |
+| **Separate database** | Hard multi-tenant or compliance boundary | Two pools; cross-schema joins impossible (BPM doesn't need them); migration runners stay completely independent. |
+
+For option B (separate schema), the host's own TypeORM `forRoot()` and
+BPM's `buildTypeOrmModuleOptions` create **two distinct connections**
+to the same Postgres cluster with different `schema:` settings — that
+is the cleanest separation Nest's TypeORM module supports.
+
+Vault paths can be split independently: keep `shuttle/develop` for the
+host and create `bpm_core/develop` for BPM secrets. BPM's helper reads
+its own path; the host's auth module reads its own. They do not
+interfere.
+
+> **Schema migrations** are per-schema. Run BPM's migrations against
+> the schema named in `DB_SCHEMA`; the host's migrations stay on its
+> own schema. There is no cross-schema migration coordination.
+
 ## Migrations
 
 This package ships TypeORM migrations under `src/lib/migrations`.
@@ -660,6 +867,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.5",
+  "version": "0.1.7",
   "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.5",
+    "@rytass/bpm-core-shared": "^0.1.7",
     "@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/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"}