@dossier-wiki/os-sdk 1.4.1 → 1.4.2-staging.5.1

package/README.md

@@ -10,6 +10,14 @@ npm install @dossier-wiki/os-sdk
 bun add @dossier-wiki/os-sdk
 ```
 
+To build against the API currently on staging, install the `staging` dist-tag
+instead. It is a prerelease built from the `staging` branch and may change
+without a changelog entry:
+
+```sh
+npm install @dossier-wiki/os-sdk@staging
+```
+
 ## Quick start
 
 ```ts
@@ -46,7 +54,7 @@ The service composes resource namespaces — call them off the root client:
 | `os.channelEndpoints` | Read and manage POS terminal, page, API client, and other endpoint identities resolved during ingestion |
 | `os.individuals` | Individual customers + nested `identificationDocuments`, `faceImages` |
 | `os.entities` | Entity customers + nested `stakeholders` |
-| `os.customers` | Cross-cutting per-customer: `notes`, `files`, `screening`, `riskRating`, `riskAssessments`, `expectedActivity`, `devices`, `assignment` (assign / unassign / assignMany) |
+| `os.customers` | Cross-cutting per-customer: `notes`, `files`, `screening`, `kyc` (start, review, PDF report, evidence ZIP), `riskRating` (set an officer override / `clearOverride`), `riskAssessments` (list, submit a questionnaire, `evaluate` the risk matrix now), `expectedActivity`, `devices`, `assignment` (assign / unassign / assignMany) |
 | `os.teams` | Domain teams: list/get/create/update/archive/delete, plus `addMembers` / `removeMembers`. Teams carry catalogue-governed `team.tags`, and `list({ tags })` filters on them |
 | `os.accounts` | Per-customer accounts, including `freeze` / `unfreeze` |
 | `os.counterparties` | Counterparties + nested `riskAssessments`, `files` |
@@ -62,8 +70,8 @@ The service composes resource namespaces — call them off the root client:
 | `os.branches` | The institution's own physical or organizational units — list/get/create/update |
 | `os.exchangeRates` | Push exchange rates |
 | `os.states` | Read and atomically set, increment, or decrement resource state; read immutable change history |
-| `os.alerts` | Raise alerts by hand (`create` — free-form, or against an optional custom alert type; org-scoped `externalRequestId` idempotency), read any alert (`get`), edit markdown `notes` (`updateNotes`), link records (`resources.list/add/remove`), plus `comments` and `attemptEvidence`. Needs the `alerts:read` / `alerts:write` API-key permissions |
-| `os.config` | `rules` (incl. `rules.backtest` — dry-run simulation over historical or synthetic transactions), `constants`, `states`, `alertWorkflows` (one per alert type — `SCREENING`, `RULE_TRIGGER`, `CUSTOM`: list/get/save), `assignmentPolicies` (read-only legacy archive), `products`, `currencies`, `eventDefinitions`, `customAlertTypes` (org-defined alert types with a typed-field schema), `webhooks`, `tagCatalogue`, `sync`, plus org-wide `reset` |
+| `os.alerts` | Raise alerts by hand (`create` — free-form, or against an optional custom alert type; org-scoped `externalRequestId` idempotency), read any alert (`get`, with `isBlocked`), edit markdown `notes` (`updateNotes`), link records (`resources.list/add/remove`), make an alert wait on another (`dependencies.list/add/remove` — see [Blocking alerts](#blocking-alerts)), plus `comments` and `attemptEvidence`. Needs the `alerts:read` / `alerts:write` API-key permissions |
+| `os.config` | `rules` (incl. `rules.backtest` — dry-run simulation over historical or synthetic transactions), `constants`, `states`, `alertWorkflows` (one per alert type — `SCREENING`, `RULE_TRIGGER`, `CUSTOM`: list/get/save), `assignmentPolicies` (read-only legacy archive), `products`, `profileTemplates` (the template a customer is created against: profile fields, risk matrix, KYC workflows, creation-form setup), `currencies`, `eventDefinitions`, `customAlertTypes` (org-defined alert types with a typed-field schema), `webhooks`, `tagCatalogue`, `sync`, plus org-wide `reset` |
 | `os.setup` | Org setup status + initialization |
 | `os.settings` | Sync snapshots + drift |
 | `os.reports` | On-demand PDF reports: `alert`, `customerProfile`, `counterpartyProfile`, `resourceProfile` — each resolves to the PDF bytes (`Uint8Array`). Needs the `reports:read` API-key permission (included in Full Access) |
@@ -373,10 +381,289 @@ Migration:
 - Use `status` for the initial customer lifecycle state. New records default to
   `ONBOARDING`; `monitoringStatus` and `riskRating` are not create inputs.
 
+## Profile templates & risk matrix
+
+A **Profile Template** is to a customer what a **Product** is to an account:
+the template it is created against. It declares the customer's typed
+**profile fields** (`fieldConfig`, the same `TypedFieldDefinition` shape as
+`Product.accountFieldConfig`), a **risk matrix** that computes the customer's
+risk rating from those fields, KYC workflow bindings, and the **creation
+setup** of the simple Add Individual / Add Entity forms. Templates live under
+`os.config.profileTemplates` and need `config:read` / `config:write`.
+
+```ts
+// 1. Define a template (once, or via Tenant Sync).
+await os.config.profileTemplates.create({
+    key: 'individual-standard',            // immutable; connectors use it instead of a UUID
+    name: 'Individual — standard onboarding',
+    partyType: 'INDIVIDUAL',
+    isDefault: true,                       // new individuals get it when no key is sent
+    fieldConfig: [
+        { key: 'pepStatus', displayName: 'PEP status', type: 'SINGLE_SELECT', required: false,
+          options: ['No PEP involvement', 'Former PEP', 'Domestic PEP'] },
+        { key: 'onboardingChannel', displayName: 'Onboarding channel', type: 'SINGLE_SELECT', required: false,
+          options: ['Face to face', 'Non face to face'] },
+    ],
+    riskMatrix: {
+        scale: [{ level: 'LOW', score: 1 }, { level: 'MEDIUM', score: 2 }, { level: 'HIGH', score: 3 }],
+        bands: [{ rating: 'LOW', below: 1.67 }, { rating: 'MEDIUM', below: 2.34 }, { rating: 'HIGH' }],
+        factors: [
+            { key: 'pepStatus', label: 'PEP status', weight: 0.6, field: 'pepStatus', levels: [
+                { option: 'No PEP involvement', level: 'LOW' },
+                { option: 'Former PEP', level: 'MEDIUM' },
+                { option: 'Domestic PEP', level: 'HIGH' },
+            ] },
+            { key: 'channel', label: 'Onboarding channel', weight: 0.4, field: 'onboardingChannel', levels: [
+                { option: 'Face to face', level: 'LOW' },
+                { option: 'Non face to face', level: 'HIGH' },
+            ] },
+        ],
+        escalations: [
+            { label: 'PEP involvement', minimumRating: 'HIGH',
+              when: { field: 'factor.pepStatus.level', operator: '=', value: 'HIGH' } },
+        ],
+        outcomes: [
+            { rating: 'LOW', requiredDueDiligence: 'SDD', reviewEveryMonths: 36 },
+            { rating: 'MEDIUM', requiredDueDiligence: 'CDD', reviewEveryMonths: 24 },
+            { rating: 'HIGH', requiredDueDiligence: 'EDD', reviewEveryMonths: 12 },
+        ],
+    },
+});
+
+// 2. Create a customer with profile fields (Tier A: validated against the template).
+const customer = await os.individuals.create({
+    externalId: 'USR-10044',
+    fullName: 'Nadia Perera',
+    profileTemplateKey: 'individual-standard', // optional here: it is the default
+    fields: [
+        { key: 'pepStatus', type: 'SINGLE_SELECT', value: 'No PEP involvement' },
+        { key: 'onboardingChannel', type: 'SINGLE_SELECT', value: 'Non face to face' },
+    ],
+});
+
+// 3. Read the rating. The matrix runs in the background (a few seconds after
+//    the last profile write, plus a daily sweep). `evaluate` runs it now.
+const assessment = await os.customers.riskAssessments.evaluate(customer.id);
+assessment.resultingRiskRating;   // 'MEDIUM'  (0.6 × 1 + 0.4 × 3 = 1.8)
+assessment.compositeScore;        // 1.8 — intermediate number, not the rating
+assessment.breakdown?.factors;    // input → criterion → level → score → weighted, per factor
+assessment.requiredDueDiligence;  // 'CDD'
+assessment.nextReviewAt;          // 'YYYY-MM-DD'
+
+const latest = await os.individuals.get(customer.id);
+latest.riskRating;                // 'MEDIUM'
+latest.riskRatingSource;          // 'MATRIX'
+latest.fields;                    // [{ key: 'pepStatus', type: 'SINGLE_SELECT', value: 'No PEP involvement' }, …]
+```
+
+How factors score: each factor has a **weight** (weights sum to 1) and turns
+one profile field into points, which the weight scales into the composite.
+Select fields give each option a level (`levels`), optionally with its own
+`score` — points per selection, overriding the level's scale score while the
+level still drives display and escalations. **Yes/no** (BOOLEAN) fields use
+the options `"true"` and `"false"`. **Number and money** fields use `ranges`
+(`{ min, max, level, score? }`, min inclusive, max exclusive, either end open,
+no overlaps; money compares in major units of the field's currency). A
+**multi-select** scores the selected option with the highest score. Anything
+else uses explicit `criteria` condition trees.
+
+```ts
+{ key: 'expectedMonthly', label: 'Expected monthly investment', weight: 0.1,
+  field: 'expectedMonthlyInvestment', ranges: [   // a MONETARY field
+    { max: 100_000, level: 'LOW' },
+    { min: 100_000, max: 1_000_000, level: 'MEDIUM' },
+    { min: 1_000_000, level: 'HIGH', score: 4 },  // own points instead of HIGH's scale score
+] }
+```
+
+How it behaves:
+
+- **Updates merge.** `individuals.update` / `entities.update` accept `fields`:
+  listed keys change, `{ key, type, value: null }` clears a field, unlisted
+  keys stay. Pass `profileTemplateKey` to switch template (same party type).
+  Each profile write re-scores the customer (bursts are coalesced), so a CRM
+  pushing its daily delta with `PATCH` gets a fresh rating within seconds.
+- **Officer overrides are sticky.** `customers.riskRating.update` sets
+  `riskRatingSource: 'MANUAL'`. Matrix runs still record their computed rating
+  (`customers.riskAssessments.list`, `method: 'MATRIX'`) but never overwrite a
+  MANUAL rating. `customers.riskRating.clearOverride(customerId)` hands the
+  rating back to the matrix and resolves to the latest matrix assessment.
+- **Assessments share one list.** `customers.riskAssessments.list` returns
+  questionnaires (`method: 'QUESTIONNAIRE'`) and matrix runs (`method:
+  'MATRIX'`, with `compositeScore`, `breakdown`, `profileTemplateVersion`,
+  `trigger`, `requiredDueDiligence`, `nextReviewAt`). A matrix run is written
+  only when its inputs or outcome change.
+- **Webhooks.** When the matrix changes a rating, `customer.risk_changed` is
+  delivered with `source: 'risk_matrix'`, `previousRating`, `newRating`,
+  `compositeScore`, `requiredDueDiligence` and `riskAssessmentId`.
+- **Templates are versioned.** Changing `fieldConfig`, `riskMatrix`,
+  `kycWorkflows` or the creation setup publishes a new version
+  (`profileTemplates.versions(id)`, each with the `changes` it made, or
+  `version(id, n)` for one); `fieldConfig` / `riskMatrix` changes also
+  re-assess every customer on the template. Customers always follow the
+  latest version. `restoreVersion(id, n)` republishes an old version's
+  definition as the newest one (re-validated, so a definition naming a
+  deleted constant is refused). `archive(id)` stops new customers using it;
+  existing customers keep it.
+- **Assigning existing customers.** `profileTemplateKey` on an individual or
+  entity update switches one customer, and the result must carry every
+  required field. `customers.assignProfileTemplate({ customerIds,
+  profileTemplateKey })` switches up to 500 at once and never refuses on
+  required fields: it keeps the values the template can hold, applies
+  defaults, and lists each customer's `missingFields`. Such a customer is
+  incomplete until a profile edit fills them.
+
+  ```ts
+  const { assigned, unchanged, skipped } = await os.customers.assignProfileTemplate({
+      customerIds: legacyCustomerIds,
+      profileTemplateKey: 'individual-standard',
+  });
+  const incomplete = assigned.filter((c) => c.missingFields.length > 0);
+  ```
+- **Creation setup.** `individualCreation` (`INDIVIDUAL` templates) or
+  `entityCreation` (`ENTITY` templates) configures the simple Add Individual /
+  Add Entity form for the template: on/off and open-by-default, external-ID
+  strategy, presets (tags + assignees), and the document or registration
+  types offered. The other party type's field is always `null` on responses
+  and a 400 on writes. A template created without one copies the org's
+  current Simple Customer Creation preference; on `update`, a value fully
+  replaces the setup and `null` clears it (the org-wide preference then
+  applies). Read shape: `SimpleCustomerCreationPreferences` /
+  `SimpleEntityCreationPreferences`; write shape:
+  `UpdateSimpleCustomerCreationPreferencesInput` /
+  `UpdateSimpleEntityCreationPreferencesInput`.
+
+  ```ts
+  await os.config.profileTemplates.update(templateId, {
+      individualCreation: {
+          enabled: true,
+          openByDefault: true,
+          externalIdStrategy: 'DOCUMENT',
+          documentTypes: [{ label: 'NIC (Sri Lanka)', type: 'NATIONAL_ID', country: 'LKA' }],
+          presets: [{ label: 'General Insurance', tags: [{ label: 'General Insurance' }],
+                      assignedToUserIds: [], assignedToTeamIds: [giTeamId] }],
+          allowTags: false,
+          allowAssignment: false,
+      },
+  });
+  ```
+- Profile fields are **not** readable by rules. Promote a value to a
+  `$customer.*` constant if a rule needs it.
+
+### Derived inputs
+
+A factor can read a value the platform derives itself instead of a profile
+field, by setting `input` instead of `field` (`RiskMatrixDerivedInput`).
+Nobody has to push these as picklist answers, and they re-score on their own
+when the underlying data changes:
+
+| `input` | Value | Score it with |
+|---|---|---|
+| `customer.nationality` | ISO-3 codes: an individual's nationalities, an entity's country of incorporation | `levels` per code, or `criteria` against a `$global.*` country list |
+| `customer.productKeys` | Product keys (`syncKey`, else `externalId`) of the customer's accounts that are not closed | `levels` per product key |
+| `customer.expectedMonthlyVolume` | The expected activity profile's monthly volume | `ranges` |
+
+When a customer holds several values of a list input, the riskiest scores.
+
+```ts
+{ key: 'citizenship', label: 'Citizenship', weight: 0.05, input: 'customer.nationality', whenUnmatched: 'HIGH',
+  criteria: [
+    { label: 'FATF grey/black list', level: 'HIGH',
+      when: { field: 'customer.nationality', operator: 'IN', value: '$global.fatfGreyBlackCountries' } },
+    { label: 'Any other nationality', level: 'LOW',
+      when: { field: 'customer.nationality', operator: 'IS_NOT_EMPTY', value: '' } },
+  ] }
+```
+
+Updating the `$global.fatfGreyBlackCountries` constant re-scores everyone in
+the next daily sweep. Changes to the expected activity profile re-score at once;
+accounts opened or closed are picked up by the daily sweep.
+
+### Dry runs: preview and impact
+
+Score an unsaved matrix without saving it. The draft is validated exactly as a
+save would be (400 lists every problem), and both calls compare it with the
+template's saved matrix evaluated on the same inputs.
+
+```ts
+// One customer, draft next to the saved matrix
+const preview = await os.config.profileTemplates.previewRiskMatrix({
+    customerId, fieldConfig: draft.fieldConfig, riskMatrix: draft.riskMatrix,
+});
+preview.published?.finalRating; // 'HIGH'
+preview.draft.finalRating;      // 'MEDIUM'
+
+// Every live customer on the template
+const impact = await os.config.profileTemplates.riskMatrixImpact(templateId, {
+    fieldConfig: draft.fieldConfig, riskMatrix: draft.riskMatrix,
+});
+impact.changed;    // customers whose rating would move
+impact.movements;  // [{ from: 'LOW', to: 'MEDIUM', count: 312 }, ...]
+impact.customers;  // who moves, rises before falls, biggest change first (at most 100)
+```
+
+Customers with an officer override are counted in `overriddenChanged`; their
+rating would not move. Up to 5,000 customers are scored per call (`truncated`
+says when there were more).
+
+### KYC output mappings
+
+A template's KYC binding can write a verified session's answers back to the
+customer. Each mapping reads one session value and writes it to a profile field
+(`fields.<key>`) or a customer-level constant (`$customer.<name>`). Constants
+are the way to make a KYC answer readable by rules; profile fields never are.
+
+```ts
+await os.config.profileTemplates.update(templateId, {
+    kycWorkflows: [{
+        purpose: 'ONBOARDING',
+        providerConfigId,
+        workflowId: 'wf_onboarding',
+        mappings: [
+            { source: 'form.occupation', target: 'fields.occupation',
+              valueMap: [{ from: 'Software engineer', to: 'IT / Software Professional' }] },
+            { source: 'session.verified', target: 'fields.onboardingChannel',
+              valueMap: [{ from: 'true', to: 'Non Face to Face Clients' }], mode: 'OVERWRITE' },
+            { source: 'person.nationality', target: '$customer.kycNationalities' },
+        ],
+    }],
+});
+```
+
+- Mappings run once, when a session of that workflow becomes verified (the
+  provider approved it, or an officer approved it in the OS).
+- `FILL` (default) writes only an empty target; `OVERWRITE` replaces it.
+- A value the target cannot hold (e.g. an answer that is not one of the field's
+  options) is skipped; the rest still apply.
+- The save validates sources, targets, options and constants, and lists every
+  problem in one 400.
+- Constant writes carry the session id as their reason in the constant history.
+  Any change re-scores the customer.
+
+### Periodic reviews
+
+Every matrix run keeps the customer's `nextReviewAt` (on individual and
+entity responses) in line with the review cycle of the rating in force
+(`outcomes[].reviewEveryMonths`). The clock starts at the first rating. A rise
+to a rating with a shorter cycle brings the review forward; a fall leaves it
+where it is. When the date arrives, the daily sweep opens a Task labelled
+`periodic-review`, assigned to the customer's assignees, due on the review
+date and linked to the customer. Closing that Task (done or cancelled)
+restarts the clock from that day.
+
+### Override disagreement
+
+While an officer override is in force, the matrix keeps scoring. When its
+rating moves away from the override, the customer's assignees get a
+notification ("The risk matrix disagrees with an officer-set rating"). It is
+sent once per change, not on every run.
+
+Spec: [`docs/specs/profile-templates/README.md`](../../docs/specs/profile-templates/README.md).
+
 ## Tenant sync — config-as-code (BREAKING in v0.7.0)
 
 `os.config.sync` drives declarative tenant config (products, constants, event
-definitions, webhooks, rules, currencies, and tenant behaviour settings). You build a `SyncConfig` and the
+definitions, webhooks, rules, currencies, profile templates, and tenant behaviour settings). You build a `SyncConfig` and the
 **server** validates, diffs, and applies it — clients hold no diff/apply logic.
 This backs the `dossiers-sync` CLI.
 
@@ -439,12 +726,14 @@ const { tokens } = await os.config.tagCatalogue.palette(); // valid `color` valu
 > accepted. Product DTOs no longer carry `metadata` — use `otherProperties`
 > instead.
 
-Accounts, products, and event ingestion accept the platform's Typed Fields
+Accounts, products, customers, and event ingestion accept the platform's Typed Fields
 primitive — a typed key/value bag (`fields`) plus an untyped escape hatch
 (`otherProperties`). Collection fields are explicit: `LIST` is open-ended,
 while `SINGLE_SELECT` and `MULTI_SELECT` are constrained by the declared
-`options` on the parent schema (`Product.accountFieldConfig` or
-`EventDefinition.properties`). Legacy `SET` remains supported but is deprecated.
+`options` on the parent schema (`Product.accountFieldConfig`,
+`ProfileTemplate.fieldConfig` or `EventDefinition.properties`). Legacy `SET`
+remains supported but is deprecated. Customer `fields` are always Tier A — see
+[Profile templates & risk matrix](#profile-templates--risk-matrix).
 
 ```ts
 import type { TypedFieldValueInput } from '@dossier-wiki/os-sdk';
@@ -536,7 +825,9 @@ The application uses the same disposition cards, reason field, and optional cata
 
 New workflow saves require one shared **Resolved** stage. Set its `next` to a router or an automatic `action` node for follow-ups. Routers can combine `resolution.outcome` with alert, customer, screening or rule fields; after resolution, `$end` means no further action. Action nodes support `CREATE_TASK` (linked to the alert) and `NOTIFY` (in-app notification), with current alert owners or specific members/teams as recipients. Follow-ups run atomically with closure using the saved verdict and leave the alert resolved. Reopen remains a separate review action. Reopening and resolving again can run follow-ups again; retrying the same transition cannot duplicate them. Existing alerts retain their pinned definition.
 
-Each organization has one workflow per alert type: `SCREENING` and `RULE_TRIGGER`. Initial assignment and later handovers are stage settings; routers provide ordered conditions and a fallback. Router branches may have an optional `name`, and the router may have a `fallbackName` (nonblank, up to 200 characters). These names appear in the workflow graph and routing history; they do not change branch IDs, order, or destinations. Omitting them preserves the numbered condition and fallback labels. Read the current revision before saving:
+Each organization has one workflow per alert type: `SCREENING`, `RULE_TRIGGER` and `CUSTOM`. Initial assignment and later handovers are stage settings; routers provide ordered conditions and a fallback. Router branches may have an optional `name`, and the router may have a `fallbackName` (nonblank, up to 200 characters). These names appear in the workflow graph and routing history; they do not change branch IDs, order, or destinations. Omitting them preserves the numbered condition and fallback labels.
+
+Routers can also read `dependencies.openCount`, the number of **blocking alerts** that are still open (see [Blocking alerts](#blocking-alerts)); `0` means the alert is free to be resolved. Conditions (`WorkflowConditions`) are a tree. `conditions` holds leaf conditions and nested groups, each group with its own `logic` of `AND` or `OR`, so "high risk and (ID matched or DOB matched)" is `{ logic: 'AND', conditions: [leaf, { logic: 'OR', conditions: [leaf, leaf] }] }`. Groups nest at most three levels below the root and hold at most 30 leaves in total; a nested group must contain at least one entry. Flat lists saved by older clients remain valid. Screening workflows can also route on `screening.maxNameMatchPercent`, the strongest name match (0–100, whole number) across the alert's matches that are not marked false positive; it is unavailable (`null`) when no match carries a name score. Read the current revision before saving:
 
 ```ts
 const workflow = await client.config.alertWorkflows.get('SCREENING');
@@ -553,6 +844,8 @@ Requires `config:read` / `config:write`. Stale saves return HTTP 409. Existing a
 
 Set `definition.restrictEditingToOwners` to `true` to make alerts read-only for everyone except currently assigned people and members of active assigned teams, including administrators. This covers assignments, match decisions, alert comments and attachments, task links, and every stage transition (including return and reopen), overriding the progression-only policy. Omitting it or setting it to `false` preserves existing editing permissions. The policy is pinned when the alert is created; publishing does not change older alerts or Simple alerts. Linked tasks retain their own editing permissions. Organization admins and owners can explicitly add themselves through the application’s **Assign to me** action (`takeOverAlert` in GraphQL). This administrative recovery preserves all other assignees, status and pinned workflow settings, and is recorded in activity history; it also supports resolved alerts so an administrator can assume ownership before reopening.
 
+Set `definition.restrictReportsToClosedAlerts` to `true` to allow PDF reports only once an alert is closed. While such an alert is open, `GET /v1/reports/alerts/{id}/pdf` returns HTTP 403, and `GET /v1/reports/customers/{id}/pdf` returns HTTP 403 while the customer has any open alert under this policy. GraphQL exposes the reason as `Alert.reviewWorkflow.reportRestriction` and `Customer.reportExportRestriction` (both null when a report can be generated). Like the other policies it is pinned at alert creation; Simple alerts are never restricted.
+
 Set `definition.restrictProgressionToOwners` to `true` to limit forward progression (including resolution) to currently assigned people and members of active assigned teams. Administrators must also be assigned. Set it to `false` to allow other organization members with `alert:update` permission to progress alerts. Stage requirements still apply. Return and reopen permissions are unchanged. Omitting the field preserves the original current-reviewers-or-administrators behavior for older API clients and stored definitions. The builder defaults the policy to enabled when editing; publishing affects new alerts only.
 
 For Screening workflows, `definition.matchAssessment` sets shared `{ note, attachment }` booleans for `CONFIRMED`, `INCONCLUSIVE`, and `FALSE_POSITIVE`. These apply to every Initial Review stage and to Secondary Review when `definition.allowSecondaryReviewMatchOverrides` is `true`; set each stage's legacy `screening` field to `null`. Enabling overrides requires a shared `matchAssessment` policy. Initial Review reviewers can replace individual match verdicts directly without resetting to pending. Authorized secondary reviewers can then also replace a match verdict directly, with the required evidence and an audit record of the previous verdict. Existing reviewer and editing permissions still apply; resolved alerts remain read-only for match decisions. Overrides default to off, and non-screening workflows must omit both settings. Older definitions that omit `matchAssessment` retain their stage-specific requirements. The builder's General policy tab consolidates older stage requirements into a shared draft, preserving the strictest requirement where they differ. Publishing never updates existing alerts.
@@ -566,3 +859,32 @@ Attach screening matches explicitly with `links: { matchIds: ["<match UUID>"] }`
 Use `client.config.alertWorkflows.getExperience()` to read the tenant's choice and revision. `saveExperience({ experience: 'SIMPLE' | 'DEFINED', expectedRevision })` changes only newly created alerts, across both supported alert types. Simple uses direct assignment and Open/Closed resolution; Defined uses the published workflow for the alert type. Existing alerts retain their process and policy version. Saved definitions are retained in Simple mode, and publishing a definition does not enable Defined mode. The initial default is Simple. Select Defined explicitly to enable the published workflow for new alerts. Existing saved choices are preserved when upgrading.
 
 Published workflow history is available through `config.alertWorkflows.versions(alertType)` (newest first, with publisher and date). `config.alertWorkflows.restore(alertType, { version, expectedRevision })` copies a version into the draft without changing the published workflow or existing alerts. Review the returned draft, then call `save` with `publish: true` and its updated revision to publish it as a new version. Old versions with no recoverable definition return `definition: null` and cannot be restored. Both operations are organization-scoped and require `config:read` / `config:write` respectively.
+
+### Blocking alerts
+
+An alert can be made to **wait on** another alert. The alert that must close first is the **blocking alert**; the one that waits is the **blocked alert**. The rule is small: **an alert with an open blocking alert cannot be resolved or closed.** Everything else — assignment, comments, attachments, notes, match decisions, stage progression short of resolution — stays allowed. Closing or resolving a blocked alert returns HTTP 400 naming how many blockers are still open. Once the last blocker closes, the blocked alert's owners are notified and it can be resolved.
+
+Links are directed and acyclic: an alert cannot block itself, and a link that would form a loop (the blocking alert already waits, directly or through other alerts, on the blocked one) is rejected with HTTP 400. Links are kept after either alert closes, so the history of why an alert waited stays readable; only *open* blockers block. Links come from three places: entity screening (an entity's screening alert is blocked by each of its stakeholders' screening alerts), analysts in the app, and the API below.
+
+```ts
+// Make alert A wait on alert B. Idempotent — re-adding returns the existing link.
+const link = await client.alerts.dependencies.add(alertA, { blockedByAlertId: alertB });
+// { id, alertId: alertA, blockedByAlertId: alertB, createdBy: { userId, name }, createdAt }
+
+// Both sides of A's links, oldest first. Compare each linked alert's status to see which still block.
+const { blockedBy, blocks } = await client.alerts.dependencies.list(alertA);
+
+// Remove the link. Removing a link that does not exist changes nothing (204 either way).
+await client.alerts.dependencies.remove(alertA, alertB);
+
+// `isBlocked` is on the flat alert view.
+const alert = await client.alerts.get(alertA); // alert.isBlocked === true while B is open
+```
+
+REST: `GET /v1/alerts/{id}/dependencies` → `{ blockedBy: AlertDependency[], blocks: AlertDependency[] }`; `POST /v1/alerts/{id}/dependencies` with `{ blockedByAlertId }` → the link (201); `DELETE /v1/alerts/{id}/dependencies/{blockedByAlertId}` → 204. Reads need `alerts:read`, writes `alerts:write`. A session user is held to the blocked alert's owner-only editing policy (`restrictEditingToOwners`); an API key acts as the key and the link's `createdBy` names the key.
+
+GraphQL exposes the same links on every alert type as `blockedBy: [AlertDependency!]!`, `blocks: [AlertDependency!]!` and `isBlocked: Boolean!`, where `AlertDependency { id, alertId, blockedByAlertId, createdBy, createdAt, blockedAlert, blockingAlert }` resolves both alerts in full. The mutations are `addAlertDependency(alertId, blockedByAlertId)` and `removeAlertDependency(alertId, blockedByAlertId)`, both returning the blocked alert and requiring `alert:update`. The alert list filter accepts `blocked: Boolean` to show only alerts that are (or are not) currently blocked.
+
+Workflows see the count as the `dependencies.openCount` field. Screening's automatic close (every match eliminated by the provider) skips a blocked alert; its owners resolve it once the blocking alerts have closed.
+
+**Stakeholder screening.** When an entity is screened, every stakeholder (director, UBO, shareholder) is rescreened with it, except stakeholders screened within the last `stakeholderRescreenSkipHours` — a screening setting on `ScreeningSettings` (GraphQL `screeningSettings` / `updateScreeningSettings`), default `24`, `0` = always rescreen, maximum 90 days (`2160`). The entity then holds one ordinary Screening alert — the one its own matches raised, or one with zero matches of its own when the entity was clean — blocked by each stakeholder's open screening alert, with its risk level held at the highest risk among its open blockers. A clean entity's alert stays open until a person resolves it once the last stakeholder alert has closed; its owners are notified at that point.

package/dist/alert-workflow-types.d.ts

@@ -9,10 +9,17 @@ export interface WorkflowCondition {
     valueField?: string;
     whenMissing?: string;
 }
+/**
+ * A condition group. `conditions` holds leaf conditions and nested groups, so
+ * "A and (B or C)" is `{ logic: "AND", conditions: [A, { logic: "OR", conditions: [B, C] }] }`.
+ * Groups nest at most three levels below the root and hold at most 30 leaves in
+ * total. A nested group needs at least one entry; an empty root matches every alert.
+ */
 export interface WorkflowConditions {
     logic: "AND" | "OR";
-    conditions: WorkflowCondition[];
+    conditions: WorkflowConditionNode[];
 }
+export type WorkflowConditionNode = WorkflowCondition | WorkflowConditions;
 export interface WorkflowAssignment {
     mode: "KEEP" | "HANDOVER" | "ADD";
     source: "SPECIFIC" | "CUSTOMER_MEMBERS" | "CUSTOMER_TEAMS" | "CUSTOMER_OWNERS" | "ORIGINAL";
@@ -37,6 +44,11 @@ export interface WorkflowStage {
     requiredReviews: ("CUSTOMER_RISK" | "COUNTERPARTY_RISK")[];
     /** Legacy stage policy. New definitions use matchAssessment and set this to null. */
     screening: MatchAssessmentPolicy | null;
+    /** What happens to assignees when an alert is returned to this stage.
+     * RULE (omission): run this stage's assignment rule. RESTORE: reassign to whoever held the
+     * alert when it last left this stage. ASK: the returning reviewer chooses, defaulting to restore.
+     * Never set on a Resolved stage: nothing is returned to it. */
+    returnAssignment?: "RULE" | "RESTORE" | "ASK";
 }
 export interface WorkflowRouter {
     id: string;
@@ -80,6 +92,10 @@ export interface WorkflowDefinition {
     matchAssessment?: MatchAssessmentPolicy;
     /** Screening only. Allow reviewers to override match verdicts in Secondary Review using matchAssessment requirements. Omission/false keeps decisions in Initial Review. */
     allowSecondaryReviewMatchOverrides?: boolean;
+    /** PDF reports of an alert can be generated only once it is closed, and a customer profile
+     * cannot be exported while the customer has an open alert under this policy. Pinned at alert
+     * creation like the other policies. Omission/false allows reports at any time. */
+    restrictReportsToClosedAlerts?: boolean;
     entry: string;
     /** Exactly one Resolved stage. Its optional next step runs automatically after closure.
      * Routers and actions after resolution may use "$end" to finish without another action. */
@@ -111,5 +127,12 @@ export interface WorkflowExecution {
     enteredAt: string;
     initialUserIds: string[];
     initialTeamIds: string[];
+    /** Who held the alert when it last left each stage, by node id. Written on every
+     * transition out of a stage; absent on alerts enrolled before it existed. */
+    stageAssignees?: Record<string, {
+        userIds: string[];
+        teamIds: string[];
+        leftAt: string;
+    }>;
 }
 //# sourceMappingURL=alert-workflow-types.d.ts.map

package/dist/alert-workflow-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alert-workflow-types.d.ts","sourceRoot":"","sources":["../src/alert-workflow-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"alert-workflow-types.d.ts","sourceRoot":"","sources":["../src/alert-workflow-types.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;AACxE,MAAM,MAAM,kBAAkB,GAC1B,gBAAgB,GAChB,kBAAkB,GAClB,UAAU,CAAC;AACf,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AACD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,qBAAqB,EAAE,CAAC;CACrC;AACD,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAC3E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;IAClC,MAAM,EACF,UAAU,GACV,kBAAkB,GAClB,gBAAgB,GAChB,iBAAiB,GACjB,UAAU,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AACD,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;CACrB;AACD,MAAM,MAAM,qBAAqB,GAAG,MAAM,CACxC,WAAW,GAAG,gBAAgB,GAAG,cAAc,EAC/C,uBAAuB,CACxB,CAAC;AACF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,kBAAkB,CAAC;IAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,UAAU,EAAE,kBAAkB,CAAC;IAC/B,cAAc,EAAE,OAAO,CAAC;IACxB,eAAe,EAAE,CAAC,eAAe,GAAG,mBAAmB,CAAC,EAAE,CAAC;IAC3D,qFAAqF;IACrF,SAAS,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACxC;;;mEAG+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,CAAC;CAC/C;AACD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,oFAAoF;QACpF,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,kBAAkB,CAAC;QAC/B,MAAM,EAAE,MAAM,CAAC;KAChB,EAAE,CAAC;IACJ,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AACD,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,GAAG,QAAQ,CAAC;IACjC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE;QACV,MAAM,EAAE,cAAc,GAAG,UAAU,CAAC;QACpC,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;CACH;AACD,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,cAAc,GAAG,cAAc,CAAC;AAC3E,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,CAAC,CAAC;IACjB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,qOAAqO;IACrO,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,iQAAiQ;IACjQ,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,6IAA6I;IAC7I,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,2KAA2K;IAC3K,kCAAkC,CAAC,EAAE,OAAO,CAAC;IAC7C;;sFAEkF;IAClF,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd;+FAC2F;IAC3F,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AACD,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAChC;AACD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,CAAC;IACvD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AACD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,KAAK,EAAE,kBAAkB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;iFAC6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3F"}