@rytass/bpm-core-nestjs-module 0.22.0 → 0.24.0

package/src/lib/workflow-engine/workflow-engine.service.d.ts

@@ -1,4 +1,4 @@
-import { MemberMetadata, type ApprovalInstanceFieldFilter, type ApprovalInstanceSort } from '@rytass/bpm-core-shared';
+import { MemberMetadata, type FieldAccessFillUnit, type ApprovalInstanceFieldFilter, type ApprovalInstanceSort } from '@rytass/bpm-core-shared';
 import { WorkflowWebhookDeliveryService } from '../workflow-webhook/workflow-webhook-delivery.service';
 import { Repository } from 'typeorm';
 import { AttachmentService } from '../attachment/attachment.service';
@@ -27,9 +27,11 @@ import { ApprovalInstanceEntity } from './approval-instance.entity';
 import { TaskDecisionEntity } from './task-decision.entity';
 import { TaskCandidateEntity } from './task-candidate.entity';
 import { TaskEntity } from './task.entity';
-import { ApprovalInstanceListViewEnum, ApprovalInstanceStateEnum, MemberTaskRoleEnum, TaskCandidateStatusEnum, TaskReassignmentErrorCodeEnum, TaskReassignmentOutcomeEnum } from './workflow-engine.enums';
+import { ApprovalInstanceListViewEnum, ApprovalInstanceStateEnum, MemberTaskRoleEnum, StuckApprovalInstanceKindEnum, TaskCandidateStatusEnum, TaskReassignmentErrorCodeEnum, TaskReassignmentOutcomeEnum } from './workflow-engine.enums';
 import { WorkflowDryRunResultObject } from './workflow-dry-run.object';
 import { BPMInitiatorCustomFieldsResolver } from './initiator-custom-fields-resolver.token';
+import { InstanceEventWriter } from '../instance-event/instance-event.writer';
+import { BPMInstanceGuard } from './instance-guard.token';
 import { BPMWorkflowServiceTaskDispatcher } from './workflow-service-task-dispatcher.token';
 import { WorkflowTokenEntity } from './workflow-token.entity';
 import { BPMRootRuntimeOptions } from '../bpm/bpm-root-options';
@@ -59,6 +61,15 @@ type SubmitApprovalInstanceCommand = SubmitApprovalInstanceInput & {
      * unset and may prefill them.
      */
     readonly endUserSubmission?: boolean;
+    /**
+     * Service layer only (ADR 27 §5): fields a host adds to the initiator's
+     * `customFields`. The engine still builds the default snapshot and calls the
+     * `customFields` resolver; these values are merged over what it returned, so
+     * a key given here wins. Cannot be combined with
+     * `initiatorMetadataSnapshotJson` (400). The GraphQL mutation always passes
+     * `null`.
+     */
+    readonly initiatorCustomFields?: Readonly<Record<string, unknown>> | null;
 };
 type ResubmitApprovalInstanceCommand = ResubmitApprovalInstanceInput & {
     readonly initiatorMemberId: string;
@@ -92,6 +103,13 @@ export interface ReassignTaskOptions {
     readonly reason: string;
     readonly toMemberId: string;
 }
+export interface ReassignMemberTasksOptions extends ReassignTaskOptions {
+    /**
+     * Only these tasks. Omitted or null means every open task the member holds;
+     * an empty list is refused, never read as "all".
+     */
+    readonly taskIds?: readonly string[] | null;
+}
 export interface MemberOpenTaskRecord {
     readonly candidateStatus: TaskCandidateStatusEnum | null;
     readonly createdAt: Date;
@@ -107,6 +125,32 @@ export interface MemberOpenTaskRecord {
     readonly templateId: string;
     readonly templateName: string | null;
 }
+/** Paging of {@link WorkflowEngineService.listStuckApprovalInstances}. */
+export interface ListStuckApprovalInstancesOptions {
+    /** 1-based; defaults to 1. */
+    readonly page?: number;
+    /** Defaults to 20, at most 100. */
+    readonly pageSize?: number;
+}
+/** An instance that could not move on, as the administrator's stuck list reads it. */
+export interface StuckApprovalInstanceRecord {
+    /** `'SLA_AUTO_APPROVE'` when the failed attempt was the timeout approving. */
+    readonly automatic: 'SLA_AUTO_APPROVE' | null;
+    readonly failedActorMemberId: string | null;
+    readonly failedAt: Date;
+    readonly initiatorMemberId: string;
+    readonly instanceId: string;
+    readonly instanceTitle: string;
+    readonly kind: StuckApprovalInstanceKindEnum;
+    readonly message: string;
+    readonly nodeId: string | null;
+    readonly nodeLabel: string | null;
+    /** Who has to press again now; read when the list is loaded. */
+    readonly pendingActorMemberIds: readonly string[];
+    readonly taskId: string | null;
+    readonly templateId: string;
+    readonly templateName: string | null;
+}
 /** Paging of a member's task list; both absent means unpaged. */
 export interface TaskListPageOptions {
     /** 1-based; defaults to 1 once paging is asked for. */
@@ -114,8 +158,22 @@ export interface TaskListPageOptions {
     /** Defaults to 20, at most 100, once paging is asked for. */
     readonly pageSize?: number;
 }
+/**
+ * Narrows a member's task list to the tasks of some templates. Absent fields
+ * do not filter. An empty `templateIds` matches nothing, as `IN ()` would.
+ * When both fields are given a task must satisfy both.
+ */
+export interface TaskTemplateFilter {
+    /** Only tasks whose instance was started from one of these templates. */
+    readonly templateIds?: readonly string[];
+    /** Only tasks whose instance's template carries this key (ADR 27 §6). */
+    readonly templateKey?: string;
+}
+/** Options of {@link WorkflowEngineService.listInboxTasks}. */
+export interface InboxTaskListOptions extends TaskListPageOptions, TaskTemplateFilter {
+}
 /** Options of {@link WorkflowEngineService.listApprovalHistoryTasks}. */
-export interface ApprovalHistoryTaskListOptions extends TaskListPageOptions {
+export interface ApprovalHistoryTaskListOptions extends TaskListPageOptions, TaskTemplateFilter {
     /** Only tasks of instances in this state. */
     readonly instanceState?: ApprovalInstanceStateEnum;
 }
@@ -127,6 +185,13 @@ export interface InactiveMemberOpenTasksRecord {
     /** Same count as {@link WorkflowEngineService.listMemberOpenTasks} returns rows. */
     readonly openTaskCount: number;
 }
+/** Input of {@link WorkflowEngineService.adminCancelApprovalInstance}. */
+export interface AdminCancelApprovalInstanceCommand {
+    readonly cancelledByMemberId: string;
+    readonly instanceId: string;
+    /** Why the administrator ends it; stored and sent to the initiator. */
+    readonly reason: string;
+}
 /**
  * Engine-internal decision knobs that are deliberately kept out of
  * {@link DecideTaskInput} so they never reach the GraphQL schema.
@@ -152,6 +217,13 @@ export interface DecideTaskOptions {
      * transfer. Defaults to {@link MANUAL_TRANSFER_DELEGATION_REASON}.
      */
     readonly transferReason?: string;
+    /**
+     * The approver's own auth context, passed by the GraphQL mutation. Data
+     * source providers receive it when an approver-filled dynamic field is
+     * resolved. Absent for engine-made decisions (SLA auto-approve), which then
+     * act as the decider's member id only.
+     */
+    readonly approverAuthContext?: BPMAuthContext;
 }
 export interface ListApprovalInstancesOptions {
     /** ADR 25 §7: conditions on form fields. Needs `templateId` when not empty. */
@@ -163,6 +235,11 @@ export interface ListApprovalInstancesOptions {
     readonly sort?: readonly ApprovalInstanceSort[];
     readonly state?: readonly ApprovalInstanceStateEnum[];
     readonly templateId?: string;
+    /**
+     * ADR 27 §6: the template's `key`. Resolved to its id; with `templateId`
+     * as well, both must name the same template. An unknown key matches nothing.
+     */
+    readonly templateKey?: string;
     readonly view?: ApprovalInstanceListViewEnum;
 }
 interface WorkflowDashboardSummaryOptions {
@@ -190,14 +267,38 @@ export declare class WorkflowEngineService {
     private readonly slaScheduleService;
     private readonly formDataSourceValueResolver?;
     private readonly webhookDeliveryService?;
+    private readonly instanceEventWriter?;
     private readonly logger;
     /** In-flight inbox reads by member; see `readSharedOpenInboxTasks`. */
     private readonly openInboxReadsInFlight;
     private readonly approvalInstanceFieldFilterCompiler;
     private readonly approvalInstanceFilterableFieldPolicy;
-    constructor(approvalInstanceRepository: Repository<ApprovalInstanceEntity>, workflowTokenRepository: Repository<WorkflowTokenEntity>, taskRepository: Repository<TaskEntity>, taskCandidateRepository: Repository<TaskCandidateEntity>, taskDecisionRepository: Repository<TaskDecisionEntity>, notificationRepository: Repository<NotificationEntity>, activityLogRepository: Repository<ActivityLogEntity>, adhocDirectiveRepository: Repository<AdhocDirectiveEntity>, approvalTemplateRepository: Repository<ApprovalTemplateEntity>, approvalTemplateVersionRepository: Repository<ApprovalTemplateVersionEntity>, formDefinitionVersionRepository: Repository<FormDefinitionVersionEntity>, attachmentService: AttachmentService, conditionService: ConditionService, delegationService: DelegationService, notificationService: NotificationService, signatureService: SignatureService, slaScheduleService: BPMSlaScheduleService, injectedServiceTaskDispatcher?: BPMWorkflowServiceTaskDispatcher, formDataSourceValueResolver?: BPMFormDataSourceValueResolver | undefined, rootOptions?: BPMRootRuntimeOptions, webhookDeliveryService?: WorkflowWebhookDeliveryService | undefined, injectedInitiatorCustomFieldsResolver?: BPMInitiatorCustomFieldsResolver);
+    constructor(approvalInstanceRepository: Repository<ApprovalInstanceEntity>, workflowTokenRepository: Repository<WorkflowTokenEntity>, taskRepository: Repository<TaskEntity>, taskCandidateRepository: Repository<TaskCandidateEntity>, taskDecisionRepository: Repository<TaskDecisionEntity>, notificationRepository: Repository<NotificationEntity>, activityLogRepository: Repository<ActivityLogEntity>, adhocDirectiveRepository: Repository<AdhocDirectiveEntity>, approvalTemplateRepository: Repository<ApprovalTemplateEntity>, approvalTemplateVersionRepository: Repository<ApprovalTemplateVersionEntity>, formDefinitionVersionRepository: Repository<FormDefinitionVersionEntity>, attachmentService: AttachmentService, conditionService: ConditionService, delegationService: DelegationService, notificationService: NotificationService, signatureService: SignatureService, slaScheduleService: BPMSlaScheduleService, injectedServiceTaskDispatcher?: BPMWorkflowServiceTaskDispatcher, formDataSourceValueResolver?: BPMFormDataSourceValueResolver | undefined, rootOptions?: BPMRootRuntimeOptions, webhookDeliveryService?: WorkflowWebhookDeliveryService | undefined, injectedInitiatorCustomFieldsResolver?: BPMInitiatorCustomFieldsResolver, injectedInstanceGuard?: BPMInstanceGuard, instanceEventWriter?: InstanceEventWriter | undefined);
+    /** ADR 27 §3; see `BPMRootRuntimeOptions.expressionMissingFormFieldsAsNull`. */
+    private readonly expressionMissingFormFieldsAsNull;
     private readonly serviceTaskDispatcher;
     private readonly initiatorCustomFieldsResolver;
+    /** ADR 27 §2; `null` means no guard is bound and no guard code runs. */
+    private readonly instanceGuard;
+    private readonly instanceGuardTimeoutMs;
+    /**
+     * Runs the bound guard for one engine path inside its transaction. A no-op
+     * when no guard is bound, so a host without one sees no behavior change.
+     */
+    private guardInstanceChange;
+    /**
+     * Writes one case-lifecycle event (ADR 27 §1) in the caller's transaction.
+     * Returns before any lookup when no observer is bound, so a host without
+     * one pays nothing. `instanceState` is the state the change commits, not the
+     * state the instance held before it.
+     */
+    private recordInstanceEvent;
+    /**
+     * Reads the template version a case runs on, inside the engine transaction,
+     * so the guard sees the same snapshot as the decision. A missing row fails
+     * the change rather than handing the guard a partial input.
+     */
+    private readBoundTemplateVersionOrThrow;
     /** Webhooks each open engine transaction will send once it has committed. */
     private readonly deferredWebhookDispatches;
     private readonly organizationTimeZone;
@@ -219,6 +320,49 @@ export declare class WorkflowEngineService {
      * by the time a mutation returns, as it always has been.
      */
     private runEngineTransaction;
+    /**
+     * Runs a public operation whose engine transaction may fail with an
+     * {@link InstanceAdvanceFailure}. The transaction has rolled back by the time
+     * it lands here, so the record is written in a transaction of its own, and
+     * the caller then gets the original error: same class, same message, as if
+     * none of this existed. The wrapper type never leaves this method.
+     */
+    private withAdvanceFailureRecorded;
+    /**
+     * Writes the `ADVANCE_FAILED` row for a rolled-back attempt, trying again
+     * once if the write fails. If every try fails the failure is logged as an
+     * error with what the row would have held, and swallowed: the caller must
+     * see the error that stopped the case, not the one that stopped its record.
+     * Such an instance is missing from the stuck list, so the log is the only
+     * trace of it.
+     */
+    private recordAdvanceFailure;
+    /** One try of {@link recordAdvanceFailure}, in a transaction of its own. */
+    private writeAdvanceFailure;
+    /**
+     * The `ADVANCE_FAILED` rows of one instance that still describe how it is
+     * stuck, oldest first. Whether a decision went through is not read from
+     * `TASK_DECIDED`: a countersign leaves one behind from an earlier voter while
+     * the last vote is the one that failed. What counts is whether the situation
+     * the row describes still holds.
+     *
+     * - `DECISION`: the task is still open and the instance is still RUNNING.
+     *   Once the task is done, cancelled, transferred or the instance has ended,
+     *   the case has moved on or been taken over.
+     * - `RESUBMIT`: the instance is still RETURNED and no later
+     *   `INSTANCE_RESUBMITTED` exists.
+     *
+     * The rule itself is `readUnresolvedInstanceFailures` in
+     * `stuck-approval-instance.query.ts`, which also holds the SQL the stuck list
+     * pages with; the two must agree. This is the duplicate check's side.
+     */
+    private readUnresolvedAdvanceFailures;
+    /**
+     * {@link readUnresolvedAdvanceFailures} for many instances at once, in two
+     * queries whatever their number: one for their activity rows, one for the
+     * tasks those rows name. Instances with nothing unresolved are absent.
+     */
+    private readUnresolvedAdvanceFailuresByInstance;
     /**
      * Queues a webhook for after the commit. A manager this service did not open
      * has no queue and no commit it can see, so that webhook goes out on the spot
@@ -239,10 +383,76 @@ export declare class WorkflowEngineService {
      */
     findApprovalInstanceByBusinessKey(templateId: string, businessKey: string): Promise<ApprovalInstanceEntity | null>;
     private resolveFormDataOptionSnapshots;
+    /**
+     * ADR 27 §4(b): asks the data-source providers again, under the decision
+     * lock and as the approver, for the options of the approver-fillable fields.
+     * A value that is no longer among the options is refused by the resolver
+     * (`VALUE_NOT_RESOLVED`). Returns snapshots for the scoped fields only; the
+     * caller swaps them in for the stored ones.
+     */
+    private refreshApproverFilledOptionSnapshots;
+    /**
+     * ADR 27 §4(b): asks the data-source providers again, as the approver, for
+     * the open data-source cells of column-mode tables. `revalidateAll` false lets
+     * the resolver reuse the stored options of cells whose value and bindings did
+     * not move. Returns snapshots for the cells of `cellSchema` only.
+     */
+    private refreshApproverFilledOpenCellSnapshots;
+    /**
+     * Refuses an end user's resubmission of an instance bound to a `HOST_ONLY`
+     * version (ADR 27 §5). Checked before any data source is called and outside
+     * the lock: an instance never changes version and a published version never
+     * changes `launchMode`, so the answer cannot go stale. An instance that does
+     * not exist is left to the locked read, which reports it.
+     */
+    private assertEndUserMayResubmit;
     private prepareResubmitFormDataOptions;
     processInstance(instanceId: string): Promise<void>;
+    /**
+     * Records `TASK_AUTO_DECISION_FAILED` (ADR 27 §3) in its own transaction.
+     * Used after an automatic decision was refused by the instance guard: the
+     * decision's transaction has already rolled back, so the event cannot ride
+     * on it. Returns before any query when no observer is bound.
+     */
+    recordTaskAutoDecisionFailed(input: {
+        readonly instanceId: string;
+        readonly taskId: string;
+        readonly reason: string;
+    }): Promise<void>;
     decideTask(input: DecideTaskInput, options?: DecideTaskOptions): Promise<TaskDecisionEntity>;
+    private decideTaskInTransaction;
     cancelApprovalInstance(input: CancelApprovalInstanceInput): Promise<ApprovalInstanceEntity>;
+    /**
+     * Administrator: ends a running or returned instance on the initiator's
+     * behalf, whoever started it. The reason is required; it is recorded as the
+     * comment of the INSTANCE_CANCELLED activity (flagged
+     * `cancelledByAdministrator`, so a host can tell this from the initiator
+     * withdrawing) and sent to the initiator as an in-app notification. An
+     * administrator ending their own instance is not told.
+     *
+     * The notification is written only after the cancellation has committed,
+     * so nobody is told of a cancellation that then rolled back. A failure to
+     * write it is logged and does not undo the cancellation.
+     *
+     * Like the other administrator operations of this service it does not check
+     * who `cancelledByMemberId` is: the GraphQL mutation is guarded by
+     * `@BPMAdminOnly()`, and a host calling this directly must check first. That
+     * member is recorded as the actor of the INSTANCE_CANCELLED activity.
+     */
+    adminCancelApprovalInstance(input: AdminCancelApprovalInstanceCommand): Promise<ApprovalInstanceEntity>;
+    /**
+     * Tells the initiator, after the commit, that an administrator ended their
+     * instance. Written outside any transaction, so external channels go out
+     * straight away and an observer is told the rows are committed.
+     */
+    private notifyInitiatorOfAdminCancel;
+    /**
+     * The cancel transaction both paths share. The order is part of the
+     * contract: read, authorize, check the state, close, record. A non-initiator who tries to withdraw an already
+     * approved instance must keep getting the "initiator" refusal, not
+     * "not cancellable".
+     */
+    private cancelApprovalInstanceInTransaction;
     /**
      * Ends a running or returned instance because a task on it ran past its SLA
      * with `onTimeout: 'TERMINATE_INSTANCE'`. It closes the instance exactly as
@@ -254,6 +464,7 @@ export declare class WorkflowEngineService {
     expireApprovalInstance(input: ExpireApprovalInstanceCommand): Promise<ApprovalInstanceEntity>;
     private closeInstance;
     resubmitApprovalInstance(input: ResubmitApprovalInstanceCommand, authContext?: BPMAuthContext): Promise<ApprovalInstanceEntity>;
+    private resubmitApprovalInstanceInTransaction;
     requestAdhocCountersign({ comment, requestedByMemberId, target, taskId, }: {
         readonly comment?: string | null;
         readonly requestedByMemberId: string;
@@ -332,6 +543,16 @@ export declare class WorkflowEngineService {
      */
     private readDryRunMemberIds;
     getApprovalInstance(id: string, scope?: WorkflowReadScope): Promise<ApprovalInstanceEntity>;
+    /**
+     * ADR 27 §4.2 (gap 1): the fill units an approver may use to resolve runtime
+     * data-source options on a RUNNING instance. Only tasks the member can act on
+     * count: the member is the assignee or a PENDING/CLAIMED candidate of a
+     * PENDING or IN_PROGRESS, non-ad-hoc task. A task whose candidate row is
+     * WAITING or already decided grants nothing, even though its status is open.
+     * A field counts only when its node lists it as SHOW; a HIDE entry never
+     * grants, whatever its fill is. Returns `[]` when the instance is not RUNNING.
+     */
+    listApproverFillUnits(instanceId: string, memberId: string): Promise<readonly FieldAccessFillUnit[]>;
     /**
      * ADR 25 §6: a value written to a filterable field must fit its type, on
      * every path that writes form data. The fields checked are the ones the
@@ -415,9 +636,31 @@ export declare class WorkflowEngineService {
      * {@link countInboxTasks} and the counters cannot disagree; only the page is
      * given its candidate summaries.
      */
-    listInboxTasks(assigneeMemberId: string, options?: TaskListPageOptions): Promise<readonly TaskEntity[]>;
+    listInboxTasks(assigneeMemberId: string, options?: InboxTaskListOptions): Promise<readonly TaskEntity[]>;
     /** How many tasks {@link listInboxTasks} pages through. */
-    countInboxTasks(assigneeMemberId: string): Promise<number>;
+    countInboxTasks(assigneeMemberId: string, filter?: TaskTemplateFilter): Promise<number>;
+    /**
+     * The template ids a {@link TaskTemplateFilter} allows, or `null` when it
+     * does not filter. A `templateKey` that names no template allows nothing.
+     */
+    private readTaskTemplateFilterIds;
+    /**
+     * Turns `templateKey` into `templateId` (ADR 27 §6), or `null` when the
+     * options can match nothing: an unknown key, or a key naming another
+     * template than `templateId` does.
+     */
+    private resolveApprovalInstanceTemplateKey;
+    /**
+     * The id of the live template carrying `key`, as a list so a key that names
+     * nothing filters everything out. At most one live template holds a key.
+     */
+    private readTemplateIdsByKey;
+    /**
+     * Keeps the tasks whose instance belongs to the filter's templates. The open
+     * task read is shared with the dashboard counters, so the filter is applied
+     * to its result rather than pushed into it.
+     */
+    private filterTasksByTemplate;
     /**
      * {@link readOpenInboxTasks} for the inbox list and its count, joining a
      * read for the same member that is still in flight. The client asks for
@@ -452,7 +695,7 @@ export declare class WorkflowEngineService {
      */
     listApprovalHistoryTasks(assigneeMemberId: string, options?: ApprovalHistoryTaskListOptions): Promise<readonly TaskEntity[]>;
     /** How many tasks {@link listApprovalHistoryTasks} pages through. */
-    countApprovalHistoryTasks(assigneeMemberId: string, options?: Pick<ApprovalHistoryTaskListOptions, 'instanceState'>): Promise<number>;
+    countApprovalHistoryTasks(assigneeMemberId: string, options?: Omit<ApprovalHistoryTaskListOptions, 'page' | 'pageSize'>): Promise<number>;
     /** The rows of {@link listApprovalHistoryTasks}, unordered and unpaged. */
     private createApprovalHistoryTaskQuery;
     /** When the member acted on a history task; see {@link listApprovalHistoryTasks}. */
@@ -471,7 +714,7 @@ export declare class WorkflowEngineService {
      * snapshot without a `nodes` array, and a blank or non-string label all
      * leave the task without a label, as `readWorkflowNodeLabel` does. Only the
      * node's `fieldAccess` leaves the database for the fill flag, which
-     * `readNodeFillableFieldKeys` then reads as tolerantly as the engine does.
+     * `readNodeFillGrantFieldKeys` then reads as tolerantly as the engine does.
      */
     private readTaskNodeSummaries;
     private readDefaultInitiatorMetadataSnapshot;
@@ -586,14 +829,40 @@ export declare class WorkflowEngineService {
      * its own transaction, and reports one result per task. A failing task does
      * not stop the others: a refusal is a REJECTED result, and an unexpected
      * error is reported as REJECTED with UNEXPECTED_ERROR for that task alone.
+     *
+     * `taskIds` narrows the batch to those tasks. Omitted or null keeps every
+     * open task. An empty list throws a BadRequestException before anything is
+     * read: it must never be taken for "all", the write is not reversible. An id
+     * the member does not hold (already moved, instance finished, unknown) yields
+     * no result row and no error; the others still run.
      */
-    reassignMemberTasks(options: ReassignTaskOptions): Promise<readonly TaskReassignmentResult[]>;
+    reassignMemberTasks(options: ReassignMemberTasksOptions): Promise<readonly TaskReassignmentResult[]>;
     /**
      * The open tasks a member holds, for the administrator's reassignment screen.
      * Same definition as the inbox, plus WAITING sequential seats, restricted to
      * RUNNING instances.
      */
     listMemberOpenTasks(memberId: string): Promise<readonly MemberOpenTaskRecord[]>;
+    /**
+     * The instances that could not move on and still cannot, newest failure
+     * first, one row each, described by their latest unresolved `ADVANCE_FAILED`.
+     *
+     * Which failures are unresolved, the order and the page are decided by the
+     * database (`readStuckFailurePage`, the SQL form of the rule the duplicate
+     * check applies in {@link readUnresolvedAdvanceFailures}); the stuck set is
+     * still evaluated whole before LIMIT applies, but only the page's rows leave
+     * the database. This decorates that page.
+     *
+     * Who has to press again is read now, not copied from the failure: a task
+     * the administrator has reassigned since shows its new holder.
+     * - `DECISION`: the candidates whose seat is PENDING or CLAIMED. A WAITING
+     *   seat of a sequential task is not that member's turn yet. A task without
+     *   a single candidate row is a direct task, held by its assignee.
+     * - `RESUBMIT`: the initiator.
+     */
+    listStuckApprovalInstances(options?: ListStuckApprovalInstancesOptions): Promise<readonly StuckApprovalInstanceRecord[]>;
+    /** How many instances {@link listStuckApprovalInstances} pages through. */
+    countStuckApprovalInstances(): Promise<number>;
     /**
      * Deactivated members who still hold open tasks, so an administrator can find
      * them: a deactivated member no longer shows up in the member search.
@@ -664,7 +933,9 @@ export declare class WorkflowEngineService {
      * Resolves who gets the node's task. A {@link SkippedRuntimeTask} means the
      * node asked to be skipped (`excludeInitiator.whenEmpty` or
      * `excludeNodeActors.whenEmpty` = SKIP_NODE) because everyone left was kept
-     * out: the sole caller creates no task and advances the token instead.
+     * out, or its manager chain found the level it asks for already reached
+     * (`skipWhenStartReached`, or an earlier stage it continues): the sole
+     * caller creates no task and advances the token instead.
      *
      * With both exclusions set the initiator rule runs first. When it alone
      * leaves nobody, `excludeInitiator.whenEmpty` decides; when it leaves
@@ -672,6 +943,58 @@ export declare class WorkflowEngineService {
      * `excludeNodeActors.whenEmpty` decides.
      */
     private resolveRuntimeTaskCandidates;
+    /**
+     * What the walk of `node`'s manager chain has to know first, or `null`
+     * for a node that is not a manager chain using one of the two settings that
+     * need it (continuing an earlier chain, or skipping when the start already
+     * qualifies); such a node is resolved exactly as before.
+     *
+     * The settings are checked again here, since the instance runs on its own
+     * snapshot of the definition and a definition from another build can carry
+     * a shape this one never published. A setting that does not hold throws a
+     * {@link ConflictException} naming the node.
+     *
+     * `skipped` is set when the level the chain asks for is already there: the
+     * start person's own level for `skipWhenStartReached`, the level the earlier
+     * stage got a signature from for a continuation.
+     */
+    private resolveOrgManagerChainContext;
+    /**
+     * `skipWhenStartReached`: whether the person the chain starts from already
+     * holds a position level of `minPositionLevel` or more today. No start
+     * person, or one without a graded position, reads as "not reached" so the
+     * chain is walked as usual.
+     */
+    private isOrgManagerChainStartLevelReached;
+    /**
+     * The position level the manager-chain stage `stageNodeId` actually got a
+     * signature from in its latest round (`T`), or `null` when none counts.
+     *
+     * - A stage whose latest round was a skip for `skippedByManagerChainReached`
+     *   got nobody to sign, so its older approvals do not count: `null`.
+     * - Otherwise the people who really approved its latest batch
+     *   ({@link readNodeActorApprovals}: no ad-hoc countersign, no SLA
+     *   auto-approval), each at the level they held on the day they approved.
+     *   `Position.level` has no history, but memberships are dated, so a
+     *   promotion that took effect after the approval does not raise `T`. The day
+     *   is the organisation's, the same one "today" is.
+     *
+     * The people counted are those who pressed approve, delegates and transfer
+     * receivers included, not the seat they sat in.
+     */
+    private readChainStageReachedLevel;
+    /**
+     * Whether the latest thing that happened to the stage `stageNodeId` was a
+     * skip for `skippedByManagerChainReached`, rather than a task being made for
+     * it: the newest such `TOKEN_ADVANCED` is newer than the newest
+     * `TASK_CREATED` of one of the stage's own (non-ad-hoc) tasks. Newer is
+     * decided by the log's `seq` (the order the database wrote the rows in;
+     * `created_at` is the transaction start and ties within one transaction).
+     *
+     * The `TASK_CREATED` payload does not say whether its task is ad-hoc, so the
+     * task is looked up by the id the log carries.
+     */
+    private wasChainStageSkippedLastRound;
     /**
      * Everyone `node` keeps out of its approvers, per rule: the initiator and
      * the submitter for `excludeInitiator`, and everyone who actually approved
@@ -708,6 +1031,13 @@ export declare class WorkflowEngineService {
      */
     private readApprovalPrincipalMemberIds;
     private resolveInitiatorManagerReplacements;
+    /**
+     * The context workflow expressions on `instance` read. Its `form` is the
+     * stored data, or with `expressionMissingFormFieldsAsNull` on, a copy with
+     * every unfilled top-level field present (ADR 27 §3).
+     */
+    private buildExpressionContext;
+    private readExpressionFormData;
     private buildDelegationContext;
     private delegateResolvedCandidates;
     /** One member's delegation, grade-gated as {@link applyGradeGate} says. */
@@ -794,6 +1124,14 @@ export declare class WorkflowEngineService {
      * past without joining the chain or counting as the stopping point, and so
      * are managers below `startPositionLevel`, until the first one at or above
      * it starts the chain.
+     *
+     * A chain that continues an earlier stage climbs from that stage's start and
+     * walks past every manager whose level is not above the one the stage got a
+     * signature from, as if that level were the last one already added. Both it
+     * and a chain that skips when its start already qualifies are only walked
+     * with the `chainContext` task creation worked out; without one they are
+     * refused, which keeps every other entry point (a notify node's recipients,
+     * for one) from reading them as an ordinary chain.
      */
     private resolveOrgManagerChainCandidates;
     /**