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

package/src/lib/workflow-engine/workflow-engine.service.js

@@ -36,7 +36,9 @@ const organization_enums_1 = require("../organization/organization.enums");
 const organization_time_zone_1 = require("../organization/organization-time-zone");
 const approval_template_version_entity_1 = require("../template/approval-template-version.entity");
 const approval_template_entity_1 = require("../template/approval-template.entity");
+const approver_filled_table_columns_1 = require("./approver-filled-table-columns");
 const template_enums_1 = require("../template/template.enums");
+const missing_form_fields_1 = require("./missing-form-fields");
 const activity_log_entity_1 = require("./activity-log.entity");
 const adhoc_directive_entity_1 = require("./adhoc-directive.entity");
 const adhoc_enums_1 = require("./adhoc.enums");
@@ -45,10 +47,12 @@ const approval_instance_field_filter_compiler_1 = require("./approval-instance-f
 const approval_instance_filterable_field_policy_1 = require("./approval-instance-filterable-field.policy");
 const text_field_pattern_test_1 = require("./text-field-pattern-test");
 const form_data_fingerprint_1 = require("./form-data-fingerprint");
+const instance_advance_failure_1 = require("./instance-advance-failure");
 const instance_submitter_1 = require("./instance-submitter");
 const task_decision_entity_1 = require("./task-decision.entity");
 const task_candidate_entity_1 = require("./task-candidate.entity");
 const task_entity_1 = require("./task.entity");
+const stuck_approval_instance_query_1 = require("./stuck-approval-instance.query");
 const workflow_engine_enums_1 = require("./workflow-engine.enums");
 const workflow_condition_evaluator_1 = require("./workflow-condition-evaluator");
 const workflow_form_value_1 = require("./workflow-form-value");
@@ -58,6 +62,9 @@ const expression_budget_1 = require("../condition/expression-budget");
 const expression_errors_1 = require("../condition/expression-errors");
 const expression_dialect_1 = require("../condition/expression-dialect");
 const initiator_custom_fields_resolver_token_1 = require("./initiator-custom-fields-resolver.token");
+const instance_event_writer_1 = require("../instance-event/instance-event.writer");
+const instance_guard_token_1 = require("./instance-guard.token");
+const instance_guard_runner_1 = require("./instance-guard.runner");
 const workflow_service_task_dispatcher_token_1 = require("./workflow-service-task-dispatcher.token");
 const workflow_token_entity_1 = require("./workflow-token.entity");
 const bpm_root_options_1 = require("../bpm/bpm-root-options");
@@ -182,6 +189,44 @@ const INACTIVE_MEMBER_NAME_LOCALE = 'zh-Hant-TW';
  * every load of the member screen.
  */
 const INACTIVE_MEMBER_COUNT_CONCURRENCY = 5;
+/**
+ * How many times an `ADVANCE_FAILED` row is tried before giving up. A missed
+ * row hides the instance from the stuck list, and a second try is safe: the
+ * duplicate check runs under the instance lock.
+ */
+const ADVANCE_FAILURE_RECORD_ATTEMPTS = 2;
+// What each way of being skipped writes into the `TOKEN_ADVANCED` payload. The
+// two chain settings that can skip a node share one key.
+const SKIPPED_RUNTIME_TASK_PAYLOADS = {
+    INITIATOR: { skippedByInitiatorExclusion: true },
+    MANAGER_CHAIN_REACHED: { skippedByManagerChainReached: true },
+    NODE_ACTORS: { skippedByNodeActorExclusion: true },
+};
+// Why a chain that continues an earlier one, or skips when its start already
+// qualifies, is refused anywhere task creation did not work its context out.
+const ORG_MANAGER_CHAIN_CONTEXT_REFUSAL = '接續前一段主管鏈、或「起點本人已達簽到職等時略過」，只能在建立簽核任務時使用，此處不支援。';
+/**
+ * ADR 27 §4.2: an approver-filled value the provider no longer offers answers
+ * 400 with `formDataErrors` naming the field or table cell, `code` kept. Other
+ * failures pass through unchanged.
+ */
+async function answerValueNotResolved(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof form_data_source_errors_1.BPMFormDataSourceValueNotResolvedException) {
+            const issue = {
+                ...(0, form_data_issue_1.createFormDataIssue)(error.location, 'VALUE_NOT_RESOLVED', '的選項已不在可選範圍內，請重新選擇'),
+                code: form_data_source_errors_1.BPM_FORM_DATA_SOURCE_ERROR_CODES.VALUE_NOT_RESOLVED,
+            };
+            throw (0, form_data_issue_1.createFormDataBadRequest)((0, form_data_issue_1.readFormDataIssueMessage)([issue]), [
+                issue,
+            ]);
+        }
+        throw error;
+    }
+}
 const WORKFLOW_READ_ALL_PERMISSIONS = new Set([
     'bpm:*',
     'bpm.workflow.read_all',
@@ -189,7 +234,7 @@ const WORKFLOW_READ_ALL_PERMISSIONS = new Set([
     'workflow.read_all',
 ]);
 let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineService {
-    constructor(approvalInstanceRepository, workflowTokenRepository, taskRepository, taskCandidateRepository, taskDecisionRepository, notificationRepository, activityLogRepository, adhocDirectiveRepository, approvalTemplateRepository, approvalTemplateVersionRepository, formDefinitionVersionRepository, attachmentService, conditionService, delegationService, notificationService, signatureService, slaScheduleService, injectedServiceTaskDispatcher, formDataSourceValueResolver, rootOptions, webhookDeliveryService, injectedInitiatorCustomFieldsResolver) {
+    constructor(approvalInstanceRepository, workflowTokenRepository, taskRepository, taskCandidateRepository, taskDecisionRepository, notificationRepository, activityLogRepository, adhocDirectiveRepository, approvalTemplateRepository, approvalTemplateVersionRepository, formDefinitionVersionRepository, attachmentService, conditionService, delegationService, notificationService, signatureService, slaScheduleService, injectedServiceTaskDispatcher, formDataSourceValueResolver, rootOptions, webhookDeliveryService, injectedInitiatorCustomFieldsResolver, injectedInstanceGuard, instanceEventWriter) {
         this.approvalInstanceRepository = approvalInstanceRepository;
         this.workflowTokenRepository = workflowTokenRepository;
         this.taskRepository = taskRepository;
@@ -209,6 +254,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         this.slaScheduleService = slaScheduleService;
         this.formDataSourceValueResolver = formDataSourceValueResolver;
         this.webhookDeliveryService = webhookDeliveryService;
+        this.instanceEventWriter = instanceEventWriter;
         this.logger = new common_1.Logger(WorkflowEngineService_1.name);
         /** In-flight inbox reads by member; see `readSharedOpenInboxTasks`. */
         this.openInboxReadsInFlight = new Map();
@@ -236,7 +282,68 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             injectedInitiatorCustomFieldsResolver ??
                 rootOptions?.initiatorCustomFieldsResolver ??
                 null;
+        // Same three-way order as the initiator resolver: a host binding under the
+        // token, then the runtime instance, then no guard at all.
+        this.instanceGuard =
+            injectedInstanceGuard ?? rootOptions?.instanceGuard ?? null;
+        this.instanceGuardTimeoutMs =
+            rootOptions?.instanceGuardTimeoutMs ??
+                instance_guard_runner_1.BPM_INSTANCE_GUARD_DEFAULT_TIMEOUT_MS;
         this.organizationTimeZone = (0, organization_time_zone_1.resolveBPMOrganizationTimeZone)(rootOptions?.organizationTimeZone);
+        this.expressionMissingFormFieldsAsNull =
+            rootOptions?.expressionMissingFormFieldsAsNull === true;
+    }
+    /**
+     * 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.
+     */
+    async guardInstanceChange(input) {
+        if (this.instanceGuard === null) {
+            return;
+        }
+        await (0, instance_guard_runner_1.runInstanceGuard)(this.instanceGuard, input, this.instanceGuardTimeoutMs);
+    }
+    /**
+     * 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.
+     */
+    async recordInstanceEvent(manager, instance, instanceState, type, fields) {
+        if (this.instanceEventWriter?.enabled !== true) {
+            return;
+        }
+        const template = await manager
+            .getRepository(approval_template_entity_1.ApprovalTemplateEntity)
+            .findOne({
+            select: { id: true, key: true },
+            where: { id: instance.templateId },
+            withDeleted: true,
+        });
+        const snapshot = {
+            instanceState,
+            templateId: instance.templateId,
+            templateKey: template?.key ?? null,
+            templateVersionId: instance.templateVersionId,
+        };
+        await this.instanceEventWriter.record(manager, instance.id, snapshot, type, fields);
+    }
+    /**
+     * 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.
+     */
+    async readBoundTemplateVersionOrThrow(manager, instance) {
+        const version = await manager
+            .getRepository(approval_template_version_entity_1.ApprovalTemplateVersionEntity)
+            .findOne({ where: { id: instance.templateVersionId } });
+        if (!version) {
+            throw new common_1.ConflictException({
+                code: 'TEMPLATE_VERSION_NOT_FOUND',
+                message: 'The template version of this instance no longer exists.',
+            });
+        }
+        return version;
     }
     /**
      * Today's date as the organization sees it (`organizationTimeZone`), for
@@ -272,6 +379,151 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         }, Promise.resolve());
         return result;
     }
+    /**
+     * 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.
+     */
+    async withAdvanceFailureRecorded(run) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            if (error instanceof instance_advance_failure_1.InstanceAdvanceFailure) {
+                await this.recordAdvanceFailure(error);
+                throw error.originalError;
+            }
+            throw error;
+        }
+    }
+    /**
+     * 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.
+     */
+    async recordAdvanceFailure(failure, attempt = 1) {
+        const { context, message } = failure;
+        try {
+            await this.writeAdvanceFailure(failure);
+        }
+        catch (recordError) {
+            const reason = recordError instanceof Error ? recordError.message : 'unknown error';
+            if (attempt < ADVANCE_FAILURE_RECORD_ATTEMPTS) {
+                this.logger.warn(`Could not record ADVANCE_FAILED for instance ${context.instanceId} (attempt ${attempt}), trying again: ${reason}`);
+                return this.recordAdvanceFailure(failure, attempt + 1);
+            }
+            this.logger.error(`Could not record ADVANCE_FAILED for instance ${context.instanceId}; it will not appear in the stuck list: ${reason}`, JSON.stringify({
+                action: context.action,
+                actorMemberId: context.actorMemberId,
+                automatic: context.automatic,
+                kind: context.kind,
+                message,
+                nodeId: context.nodeId,
+                taskId: context.taskId,
+            }));
+        }
+    }
+    /** One try of {@link recordAdvanceFailure}, in a transaction of its own. */
+    async writeAdvanceFailure(failure) {
+        const { context, message } = failure;
+        await this.approvalInstanceRepository.manager.transaction(async (manager) => {
+            // The same per-instance lock every decision takes, so two attempts
+            // failing together cannot both pass the check below and write twice.
+            await manager.query('SELECT pg_advisory_xact_lock(hashtext($1))', [
+                context.instanceId,
+            ]);
+            const unresolved = await this.readUnresolvedAdvanceFailures(manager, context.instanceId);
+            if (unresolved.some((logged) => isSameAdvanceFailure(logged, context, message))) {
+                return;
+            }
+            const activityRepository = manager.getRepository(activity_log_entity_1.ActivityLogEntity);
+            await activityRepository.save(activityRepository.create({
+                actorMemberId: context.actorMemberId,
+                eventType: workflow_engine_enums_1.ActivityLogEventTypeEnum.ADVANCE_FAILED,
+                instanceId: context.instanceId,
+                nodeId: context.nodeId,
+                payload: {
+                    action: context.action,
+                    automatic: context.automatic,
+                    kind: context.kind,
+                    message,
+                    nodeId: context.nodeId,
+                    taskId: context.taskId,
+                },
+                taskId: context.taskId,
+            }));
+        });
+    }
+    /**
+     * 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.
+     */
+    async readUnresolvedAdvanceFailures(manager, instanceId) {
+        const instance = await manager
+            .getRepository(approval_instance_entity_1.ApprovalInstanceEntity)
+            .findOne({ where: { id: instanceId } });
+        if (!instance) {
+            return [];
+        }
+        const byInstance = await this.readUnresolvedAdvanceFailuresByInstance(manager, [instance]);
+        return byInstance.get(instance.id) ?? [];
+    }
+    /**
+     * {@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.
+     */
+    async readUnresolvedAdvanceFailuresByInstance(manager, instances) {
+        if (instances.length === 0) {
+            return new Map();
+        }
+        const logs = await manager.getRepository(activity_log_entity_1.ActivityLogEntity).find({
+            order: { seq: 'ASC' },
+            where: {
+                eventType: (0, typeorm_2.In)([
+                    workflow_engine_enums_1.ActivityLogEventTypeEnum.ADVANCE_FAILED,
+                    workflow_engine_enums_1.ActivityLogEventTypeEnum.INSTANCE_RESUBMITTED,
+                ]),
+                instanceId: (0, typeorm_2.In)(instances.map((instance) => instance.id)),
+            },
+        });
+        const decidedTaskIds = [
+            ...new Set(logs.flatMap((log) => log.eventType === workflow_engine_enums_1.ActivityLogEventTypeEnum.ADVANCE_FAILED &&
+                log.taskId
+                ? [log.taskId]
+                : [])),
+        ];
+        const openTaskIds = new Set(decidedTaskIds.length === 0
+            ? []
+            : (await manager.getRepository(task_entity_1.TaskEntity).find({
+                where: {
+                    id: (0, typeorm_2.In)(decidedTaskIds),
+                    status: (0, typeorm_2.In)([...OPEN_TASK_STATUSES]),
+                },
+            })).map((task) => task.id));
+        return new Map(instances.flatMap((instance) => {
+            const unresolved = (0, stuck_approval_instance_query_1.readUnresolvedInstanceFailures)(instance, logs.filter((log) => log.instanceId === instance.id), openTaskIds);
+            return unresolved.length === 0 ? [] : [[instance.id, unresolved]];
+        }));
+    }
     /**
      * 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
@@ -308,6 +560,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 input.submittedByMemberId.trim() === '')) {
             throw new common_1.BadRequestException('submittedByMemberId must be a non-empty string');
         }
+        const hostCustomFields = readHostInitiatorCustomFields(input);
         const submittedFormData = parseJsonObject(input.formDataJson, 'formDataJson');
         const businessKey = normalizeBusinessKey(input.businessKey);
         const submittedByMemberId = input.submittedByMemberId ?? input.initiatorMemberId;
@@ -319,6 +572,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             throw new common_1.ConflictException('Approval template does not have a published version');
         }
         const templateVersion = await this.getPublishedTemplateVersionOrThrow(template.currentVersionId);
+        if (input.endUserSubmission === true) {
+            assertEndUserMayLaunch(templateVersion);
+        }
         const formDefinitionVersion = await this.getPublishedFormVersionOrThrow(templateVersion.formDefinitionVersionId);
         // The fields an approver fills in belong to the approval, not the
         // application: an end user's value for one is dropped (it would otherwise
@@ -327,13 +583,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         // checked here; required and row minimums wait for the node that fills
         // them. Read off the version the instance is bound to, not the template's
         // latest, so a publish in between cannot change what is stripped.
-        const deferredFieldKeys = (0, bpm_core_shared_1.readApproverFilledFieldKeys)(templateVersion.workflowDefinition);
+        const deferral = (0, approver_filled_table_columns_1.readApproverFilledDeferral)(templateVersion.workflowDefinition);
         const formData = input.endUserSubmission === true
-            ? (0, bpm_core_shared_1.omitFormDataKeys)(submittedFormData, deferredFieldKeys)
+            ? (0, approver_filled_table_columns_1.applyOpenColumnCells)((0, bpm_core_shared_1.omitFormDataKeys)(submittedFormData, deferral.wholeKeys), null, deferral)
             : submittedFormData;
-        validateSubmittedFormData(formDefinitionVersion.schema, formData, {
-            deferredFieldKeys,
-        });
+        validateSubmittedFormData((0, approver_filled_table_columns_1.projectOpenColumnsOptional)(formDefinitionVersion.schema, deferral), formData, { deferredFieldKeys: deferral.wholeKeys });
         // Checked against the bound version's schema before any data source is
         // called, so a bad value is refused cheaply. The transaction below
         // confirms under the template lock that this version is still current
@@ -347,7 +601,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         });
         const initiatorMetadataSnapshot = input.initiatorMetadataSnapshotJson
             ? parseJsonObject(input.initiatorMetadataSnapshotJson, 'initiatorMetadataSnapshotJson')
-            : await this.buildInitiatorMetadataSnapshot({
+            : mergeHostInitiatorCustomFields(await this.buildInitiatorMetadataSnapshot({
                 authContext: submitAuthContext,
                 memberId: input.initiatorMemberId,
                 submission: {
@@ -355,7 +609,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                     templateId: template.id,
                     templateVersionId: templateVersion.id,
                 },
-            });
+            }), hostCustomFields);
         if (!this.conditionService.evaluateBoolean(templateVersion.initiatorPolicyCel, buildInitiatorPolicyContext(initiatorMetadataSnapshot), 'initiatorPolicyCel', 
         // The policy is written in its version's dialect (ADR 22 §3.3).
         readExpressionDialectOptions(templateVersion.initiatorPolicyCel, templateVersion.workflowDefinition))) {
@@ -396,7 +650,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             const instanceRepository = manager.getRepository(approval_instance_entity_1.ApprovalInstanceEntity);
             const tokenRepository = manager.getRepository(workflow_token_entity_1.WorkflowTokenEntity);
             const activityRepository = manager.getRepository(activity_log_entity_1.ActivityLogEntity);
-            const instance = await instanceRepository.save(instanceRepository.create({
+            const instanceDraft = instanceRepository.create({
                 completedAt: null,
                 formData,
                 formDataOptionSnapshot,
@@ -416,7 +670,24 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 templateVersionId: templateVersion.id,
                 title: input.title?.trim() || template.name,
                 workflowSnapshot: templateVersion.workflowDefinition,
-            }));
+            });
+            // ADR 27 §2: the host guard sees the case as it is about to be saved,
+            // under the template lock. A refusal throws here, before any insert.
+            await this.guardInstanceChange({
+                action: null,
+                actorMemberId: submittedByMemberId,
+                authContext: authContext ?? null,
+                automatic: null,
+                changedFieldKeys: Object.keys(formData),
+                formData,
+                instance: instanceDraft,
+                kind: 'SUBMIT',
+                manager,
+                node: null,
+                task: null,
+                templateVersion,
+            });
+            const instance = await instanceRepository.save(instanceDraft);
             await this.attachmentService.bindFormDataAttachmentsToInstance(manager, {
                 formData,
                 instanceId: instance.id,
@@ -454,6 +725,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                     taskId: null,
                 }),
             ]);
+            await this.recordInstanceEvent(manager, instance, instance.state, 'INSTANCE_SUBMITTED', { actorMemberId: submittedByMemberId });
             await this.processRunningInstance(manager, instance);
             return instance;
         }).catch((error) => 
@@ -494,6 +766,66 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             schema,
         });
     }
+    /**
+     * 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.
+     */
+    async refreshApproverFilledOptionSnapshots({ approverAuthContext, fieldKeys, formData, instance, }) {
+        const schema = readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot);
+        return this.resolveFormDataOptionSnapshots({
+            authContext: approverAuthContext,
+            formData,
+            previousFormData: instance.formData,
+            previousSnapshots: readSnapshotWithoutFields(instance.formDataOptionSnapshot, fieldKeys),
+            revalidateAll: true,
+            schema: {
+                ...schema,
+                fields: schema.fields.filter((field) => fieldKeys.has(field.fieldKey)),
+            },
+        });
+    }
+    /**
+     * 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.
+     */
+    async refreshApproverFilledOpenCellSnapshots({ approverAuthContext, cellSchema, formData, instance, revalidateAll, }) {
+        return this.resolveFormDataOptionSnapshots({
+            authContext: approverAuthContext,
+            formData,
+            previousFormData: instance.formData,
+            previousSnapshots: instance.formDataOptionSnapshot ?? {},
+            revalidateAll,
+            schema: cellSchema,
+        });
+    }
+    /**
+     * 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.
+     */
+    async assertEndUserMayResubmit(instanceId) {
+        const instance = await this.approvalInstanceRepository.findOne({
+            select: { id: true, templateVersionId: true },
+            where: { id: instanceId },
+        });
+        if (!instance) {
+            return;
+        }
+        const version = await this.approvalTemplateVersionRepository.findOne({
+            select: { id: true, launchMode: true },
+            where: { id: instance.templateVersionId },
+        });
+        if (version) {
+            assertEndUserMayLaunch(version);
+        }
+    }
     async prepareResubmitFormDataOptions(input, submittedFormData, authContext) {
         const instance = await this.approvalInstanceRepository.findOne({
             where: { id: input.instanceId },
@@ -512,13 +844,13 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             throw new common_1.ConflictException('Approval template is deactivated');
         }
         const schema = readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot);
-        const deferredFieldKeys = (0, bpm_core_shared_1.readApproverFilledFieldKeys)(instance.workflowSnapshot);
+        const deferral = (0, approver_filled_table_columns_1.readApproverFilledDeferral)(instance.workflowSnapshot);
         // Same overlay as inside the lock, so the options resolved here are for
         // the form data that is actually saved.
         const formData = input.endUserSubmission === true
-            ? (0, bpm_core_shared_1.overlayStoredFormDataKeys)(submittedFormData, instance.formData, deferredFieldKeys)
+            ? (0, approver_filled_table_columns_1.applyOpenColumnCells)((0, bpm_core_shared_1.overlayStoredFormDataKeys)(submittedFormData, instance.formData, deferral.wholeKeys), instance.formData, deferral)
             : submittedFormData;
-        validateSubmittedFormData(schema, formData, { deferredFieldKeys });
+        validateSubmittedFormData((0, approver_filled_table_columns_1.projectOpenColumnsOptional)(schema, deferral), formData, { deferredFieldKeys: deferral.wholeKeys });
         await this.assertCurrentFilterableFormDataValues(instance.templateId, formData);
         const formDataOptionSnapshot = await this.resolveFormDataOptionSnapshots({
             authContext,
@@ -556,7 +888,30 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             await this.processRunningInstance(manager, instance);
         });
     }
+    /**
+     * 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.
+     */
+    async recordTaskAutoDecisionFailed(input) {
+        if (this.instanceEventWriter?.enabled !== true) {
+            return;
+        }
+        await this.runEngineTransaction(async (manager) => {
+            const instance = await manager
+                .getRepository(approval_instance_entity_1.ApprovalInstanceEntity)
+                .findOne({ where: { id: input.instanceId } });
+            if (!instance) {
+                return;
+            }
+            await this.recordInstanceEvent(manager, instance, instance.state, 'TASK_AUTO_DECISION_FAILED', { reason: input.reason, taskId: input.taskId });
+        });
+    }
     async decideTask(input, options = {}) {
+        return this.withAdvanceFailureRecorded(() => this.decideTaskInTransaction(input, options));
+    }
+    async decideTaskInTransaction(input, options) {
         return this.runEngineTransaction(async (manager) => {
             const taskRepository = manager.getRepository(task_entity_1.TaskEntity);
             const taskCandidateRepository = manager.getRepository(task_candidate_entity_1.TaskCandidateEntity);
@@ -719,9 +1074,14 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             if (filledFormData !== null && task.isAdhoc) {
                 throw new common_1.ForbiddenException(`Ad-hoc task ${task.id} cannot fill in form fields`);
             }
+            // ADR 27 §4(a): column-mode tables are accepted here and settled
+            // cell by cell below. Their open data-source columns are re-resolved per
+            // row as the approver (ADR 27 §4(b)).
+            const nodeColumnFillMap = (0, approver_filled_table_columns_1.readNodeColumnFillMap)(taskNode);
             if (filledFormData !== null) {
                 const fillableFieldKeys = (0, bpm_core_shared_1.readNodeFillableFieldKeys)(taskNode);
-                const refusedFieldKeys = Object.keys(filledFormData).filter((fieldKey) => !fillableFieldKeys.has(fieldKey));
+                const refusedFieldKeys = Object.keys(filledFormData).filter((fieldKey) => !fillableFieldKeys.has(fieldKey) &&
+                    !nodeColumnFillMap.has(fieldKey));
                 if (refusedFieldKeys.length > 0) {
                     throw new common_1.ForbiddenException(`Workflow node ${task.nodeId} does not let approvers fill in: ${refusedFieldKeys.join(', ')}`);
                 }
@@ -732,35 +1092,134 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                     (0, form_data_fingerprint_1.computeFormDataFingerprint)(instance.formData)) {
                 throw new common_1.ConflictException(`Approval instance ${instance.id} form data changed; refresh and retry`);
             }
+            // ADR 27 §4(a): each column-mode table is merged per cell against the
+            // stored rows. A changed row count, row order or applicant cell is
+            // refused before anything below sees the payload.
+            const settledFormData = filledFormData === null
+                ? null
+                : (0, approver_filled_table_columns_1.settleColumnFillPayload)(filledFormData, instance.formData, nodeColumnFillMap);
             // Only keys whose value really changes are written and reported. A key
             // the form data does not have yet counts as changed even when the new
             // value is null.
-            const changedFieldKeys = filledFormData === null
+            const changedFieldKeys = settledFormData === null
                 ? []
-                : Object.keys(filledFormData)
+                : Object.keys(settledFormData)
                     .filter((fieldKey) => !Object.prototype.hasOwnProperty.call(instance.formData, fieldKey) ||
-                    (0, form_data_fingerprint_1.computeStableValueFingerprint)(filledFormData[fieldKey]) !==
+                    (0, form_data_fingerprint_1.computeStableValueFingerprint)(settledFormData[fieldKey]) !==
                         (0, form_data_fingerprint_1.computeStableValueFingerprint)(instance.formData[fieldKey]))
                     .sort();
-            const mergedFormData = { ...instance.formData, ...filledFormData };
+            const mergedFormData = { ...instance.formData, ...settledFormData };
+            // ADR 27 §4.3: an approver may change a column only if no column this
+            // approver may not fill reads it. Such a dependent keeps its stored value
+            // here, so a changed source would leave it stale. Fail closed.
+            if (nodeColumnFillMap.size > 0) {
+                (0, approver_filled_table_columns_1.assertDependentColumnsFrozen)(readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot), taskNode, instance.formData, mergedFormData);
+            }
             // Every approval at a node that lets its approver fill in fields is
             // held to those fields, whether or not this request sent any: the host
-            // may have pre-filled a table the approver then leaves as is.
+            // may have pre-filled a table the approver then leaves as is. A column
+            // this node grants REQUIRED is required in the check, not only in the
+            // template.
             if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED && !task.isAdhoc) {
-                const nodeFillableFieldKeys = (0, bpm_core_shared_1.readNodeFillableFieldKeys)(taskNode);
+                const nodeFillableFieldKeys = new Set([
+                    ...(0, bpm_core_shared_1.readNodeFillableFieldKeys)(taskNode),
+                    ...nodeColumnFillMap.keys(),
+                ]);
                 if (nodeFillableFieldKeys.size > 0) {
-                    validateFilledFormFields(readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot), mergedFormData, nodeFillableFieldKeys, (0, bpm_core_shared_1.readNodeRequiredFieldKeys)(taskNode));
+                    validateFilledFormFields((0, approver_filled_table_columns_1.projectNodeOpenColumnsRequired)(readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot), nodeColumnFillMap), mergedFormData, nodeFillableFieldKeys, (0, bpm_core_shared_1.readNodeRequiredFieldKeys)(taskNode));
                 }
             }
-            if (filledFormData !== null && changedFieldKeys.length > 0) {
+            // ADR 27 §4(b): an approver-filled data-source field is judged as the
+            // approver's own pick. The provider is asked again under the lock with
+            // the approver's identity, so a value outside the current options is
+            // refused and the recorded label is refreshed before anything is
+            // written. Table data-source columns resolve per row (ROW_FIELD).
+            const fillableFieldKeys = (0, bpm_core_shared_1.readNodeFillableFieldKeys)(taskNode);
+            const dataSourceRefreshKeys = input.action === workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED && !task.isAdhoc
+                ? fillableFieldKeys
+                : new Set(changedFieldKeys.filter((fieldKey) => fillableFieldKeys.has(fieldKey)));
+            const approverAuthContext = options.approverAuthContext ??
+                createWorkflowAuthContext(input.decidedByMemberId);
+            const refreshedFormDataOptionSnapshots = dataSourceRefreshKeys.size === 0
+                ? null
+                : await answerValueNotResolved(() => this.refreshApproverFilledOptionSnapshots({
+                    approverAuthContext,
+                    fieldKeys: dataSourceRefreshKeys,
+                    formData: mergedFormData,
+                    instance,
+                }));
+            const wholeFieldOptionSnapshot = refreshedFormDataOptionSnapshots === null
+                ? (instance.formDataOptionSnapshot ?? {})
+                : {
+                    ...readSnapshotWithoutFields(instance.formDataOptionSnapshot, dataSourceRefreshKeys),
+                    ...refreshedFormDataOptionSnapshots,
+                };
+            // ADR 27 §4(b): the open data-source cells of column-mode tables. An
+            // APPROVED decision re-resolves all of them; any other decision only
+            // when a column-mode table's cells changed. The form schema is read
+            // only for a node that has column-mode fills, so other nodes never
+            // touch the snapshot's schema.
+            const openCellSchema = nodeColumnFillMap.size === 0
+                ? null
+                : (0, approver_filled_table_columns_1.readOpenDataSourceCellSchema)(readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot), nodeColumnFillMap);
+            const openCellTableKeys = new Set((openCellSchema?.fields ?? []).map((field) => field.fieldKey));
+            const revalidateAllOpenCells = input.action === workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED && !task.isAdhoc;
+            const hasChangedOpenCellTable = changedFieldKeys.some((fieldKey) => openCellTableKeys.has(fieldKey));
+            const refreshedOpenCellSnapshots = openCellSchema === null ||
+                openCellSchema.fields.length === 0 ||
+                (!revalidateAllOpenCells && !hasChangedOpenCellTable)
+                ? null
+                : await answerValueNotResolved(() => this.refreshApproverFilledOpenCellSnapshots({
+                    approverAuthContext,
+                    cellSchema: openCellSchema,
+                    formData: mergedFormData,
+                    instance,
+                    revalidateAll: revalidateAllOpenCells,
+                }));
+            const nextFormDataOptionSnapshot = refreshedOpenCellSnapshots === null || openCellSchema === null
+                ? wholeFieldOptionSnapshot
+                : {
+                    ...(0, approver_filled_table_columns_1.readSnapshotWithoutOpenCells)(wholeFieldOptionSnapshot, openCellSchema),
+                    ...(0, approver_filled_table_columns_1.readOpenCellSnapshots)(refreshedOpenCellSnapshots, openCellSchema),
+                };
+            // ADR 27 §2: the host guard judges the decision as it will be
+            // committed, after the form checks and before anything is written.
+            // The version is read only when a guard is bound, so an engine
+            // without one issues exactly the queries it did before.
+            if (this.instanceGuard !== null) {
+                await this.guardInstanceChange({
+                    action: input.action,
+                    actorMemberId: input.decidedByMemberId,
+                    // The approver's own context when the GraphQL mutation passed one;
+                    // never the member-id stub the data-source path falls back to.
+                    authContext: options.approverAuthContext ?? null,
+                    automatic: options.automatic ?? null,
+                    changedFieldKeys,
+                    formData: mergedFormData,
+                    instance,
+                    kind: 'DECIDE',
+                    manager,
+                    node: taskNode,
+                    task,
+                    templateVersion: await this.readBoundTemplateVersionOrThrow(manager, instance),
+                });
+            }
+            const formDataChanged = settledFormData !== null && changedFieldKeys.length > 0;
+            const formDataOptionSnapshotChanged = (0, form_data_fingerprint_1.computeStableValueFingerprint)(nextFormDataOptionSnapshot) !==
+                (0, form_data_fingerprint_1.computeStableValueFingerprint)(instance.formDataOptionSnapshot ?? {});
+            if (formDataChanged) {
                 await this.assertCurrentFilterableFormDataValues(instance.templateId, mergedFormData, manager);
+            }
+            if (formDataChanged || formDataOptionSnapshotChanged) {
                 // Merged into the shared `instance` before it is signed and before
                 // the token moves on: the signature must cover the filled values, a
                 // gateway after this node must route on them, and an end node saves
-                // this same object, which would write the old values back.
+                // this same object, which would write the old values back. The
+                // refreshed option labels go in the same write.
                 const savedInstance = await instanceRepository.save({
                     ...instance,
                     formData: mergedFormData,
+                    formDataOptionSnapshot: nextFormDataOptionSnapshot,
                 });
                 Object.assign(instance, savedInstance);
             }
@@ -874,12 +1333,25 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 },
                 taskId: completedTask.id,
             }));
+            // What an ADVANCE_FAILED row says if the move to the next stage fails.
+            // An SLA timeout acts as the member `resolveTaskActorMemberId` picked,
+            // who never pressed anything, so `automatic` is what tells them apart.
+            const advanceContext = (action) => ({
+                action,
+                actorMemberId: input.decidedByMemberId,
+                automatic: options.automatic ?? null,
+                instanceId: instance.id,
+                kind: 'DECISION',
+                nodeId: claimedTask.nodeId,
+                taskId: claimedTask.id,
+            });
             // Resolve the recipient's "待簽" notification so its inline 同意/拒絕
             // actions disappear once the task is decided. When the task has ended
             // (rejected / returned, or an approval that completed it), every other
             // candidate's notification is superseded too; a non-completing approval
             // on a multi-approver task leaves the remaining approvers' open.
-            const taskEnded = input.action !== workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED || shouldCompleteTask;
+            const taskEnded = input.action !== workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED ||
+                shouldCompleteTask;
             await this.notificationService.resolveTaskNotifications({
                 actingMemberId: input.decidedByMemberId,
                 manager,
@@ -907,69 +1379,151 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 if (await this.hasOpenTasksForTokenNode(manager, claimedTask.tokenId, claimedTask.nodeId)) {
                     return decision;
                 }
-                const token = await tokenRepository.findOne({
-                    where: { id: claimedTask.tokenId },
-                });
-                if (!token) {
-                    throw new common_1.NotFoundException(`Workflow token ${claimedTask.tokenId} was not found`);
-                }
-                if (token.status !== workflow_engine_enums_1.WorkflowTokenStatusEnum.WAITING) {
-                    throw new common_1.ConflictException(`Workflow token ${token.id} is not waiting for a task decision`);
-                }
-                const activeToken = await tokenRepository.save({
-                    ...token,
-                    consumedAt: null,
-                    status: workflow_engine_enums_1.WorkflowTokenStatusEnum.ACTIVE,
+                // Everything from here to the next stage is the part that leaves the
+                // case stuck when it fails: the decision rolls back with it.
+                await runInstanceAdvanceStep(advanceContext('APPROVED'), async () => {
+                    const token = await tokenRepository.findOne({
+                        where: { id: claimedTask.tokenId },
+                    });
+                    if (!token) {
+                        throw new common_1.NotFoundException(`Workflow token ${claimedTask.tokenId} was not found`);
+                    }
+                    if (token.status !== workflow_engine_enums_1.WorkflowTokenStatusEnum.WAITING) {
+                        throw new common_1.ConflictException(`Workflow token ${token.id} is not waiting for a task decision`);
+                    }
+                    const activeToken = await tokenRepository.save({
+                        ...token,
+                        consumedAt: null,
+                        status: workflow_engine_enums_1.WorkflowTokenStatusEnum.ACTIVE,
+                    });
+                    await this.dispatchAdhocStageNotifications(manager, instance, claimedTask.nodeId, 'APPROVED');
+                    await this.advanceTokenToOutgoingNodes(manager, instance, activeToken, readWorkflowNodeOrThrow(instance.workflowSnapshot, claimedTask.nodeId));
+                    await this.processRunningInstance(manager, instance);
                 });
-                await this.dispatchAdhocStageNotifications(manager, instance, claimedTask.nodeId, 'APPROVED');
-                await this.advanceTokenToOutgoingNodes(manager, instance, activeToken, readWorkflowNodeOrThrow(instance.workflowSnapshot, claimedTask.nodeId));
-                await this.processRunningInstance(manager, instance);
                 return decision;
             }
             if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED) {
                 return decision;
             }
             if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.RETURNED) {
-                await this.returnInstanceToNode(manager, instance, completedTask, returnToNodeId, decidedAt);
+                await runInstanceAdvanceStep(advanceContext('RETURNED'), () => this.returnInstanceToNode(manager, instance, completedTask, returnToNodeId, decidedAt, input.decidedByMemberId));
                 return decision;
             }
             if (await this.handleAdhocPreApprovalRejection(manager, instance, completedTask, decidedAt, decisionComment)) {
                 return decision;
             }
-            await this.rejectInstance(manager, instance, completedTask, decidedAt);
+            await this.rejectInstance(manager, instance, completedTask, decidedAt, input.decidedByMemberId);
             return decision;
         });
     }
     async cancelApprovalInstance(input) {
+        return this.cancelApprovalInstanceInTransaction({
+            actorMemberId: input.cancelledByMemberId,
+            authorize: (instance) => {
+                if (instance.initiatorMemberId !== input.cancelledByMemberId) {
+                    throw new common_1.ConflictException(`Approval instance ${instance.id} can only be cancelled by its initiator`);
+                }
+            },
+            instanceId: input.instanceId,
+            payload: {
+                comment: input.comment?.trim() || null,
+            },
+        });
+    }
+    /**
+     * 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.
+     */
+    async adminCancelApprovalInstance(input) {
+        const reason = input.reason.trim();
+        // Refused before anything is read, so an empty reason is never mistaken
+        // for a missing instance.
+        if (!reason) {
+            throw new common_1.BadRequestException('A reason is required to cancel an approval instance as an administrator');
+        }
+        const cancelled = await this.cancelApprovalInstanceInTransaction({
+            actorMemberId: input.cancelledByMemberId,
+            authorize: () => undefined,
+            instanceId: input.instanceId,
+            payload: {
+                cancelledByAdministrator: true,
+                comment: reason,
+            },
+        });
+        if (cancelled.initiatorMemberId !== input.cancelledByMemberId) {
+            await this.notifyInitiatorOfAdminCancel(cancelled, reason);
+        }
+        return cancelled;
+    }
+    /**
+     * 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.
+     */
+    async notifyInitiatorOfAdminCancel(instance, reason) {
+        try {
+            await this.notificationService.createAdhocWorkflowNotifications({
+                channels: null,
+                instance,
+                message: `案件「${instance.title}」已由管理員撤銷：${reason}`,
+                payload: {
+                    nodeLabel: '管理員撤銷',
+                    reason,
+                    type: 'INSTANCE_CANCELLED_BY_ADMINISTRATOR',
+                },
+                recipientMemberIds: [instance.initiatorMemberId],
+            });
+        }
+        catch (error) {
+            this.logger.error(`Instance ${instance.id} was cancelled by an administrator, but its initiator ${instance.initiatorMemberId} could not be notified: ${error instanceof Error ? error.message : 'unknown error'}`);
+        }
+    }
+    /**
+     * 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".
+     */
+    async cancelApprovalInstanceInTransaction(cancellation) {
         return this.runEngineTransaction(async (manager) => {
             await manager.query('SELECT pg_advisory_xact_lock(hashtext($1))', [
-                input.instanceId,
+                cancellation.instanceId,
             ]);
             const instanceRepository = manager.getRepository(approval_instance_entity_1.ApprovalInstanceEntity);
             const instance = await instanceRepository.findOne({
-                where: { id: input.instanceId },
+                where: { id: cancellation.instanceId },
             });
             if (!instance) {
-                throw new common_1.NotFoundException(`Approval instance ${input.instanceId} was not found`);
-            }
-            if (instance.initiatorMemberId !== input.cancelledByMemberId) {
-                throw new common_1.ConflictException(`Approval instance ${instance.id} can only be cancelled by its initiator`);
+                throw new common_1.NotFoundException(`Approval instance ${cancellation.instanceId} was not found`);
             }
+            cancellation.authorize(instance);
             if (instance.state !== workflow_engine_enums_1.ApprovalInstanceStateEnum.RUNNING &&
                 instance.state !== workflow_engine_enums_1.ApprovalInstanceStateEnum.RETURNED) {
                 throw new common_1.ConflictException(`Approval instance ${instance.id} is not cancellable`);
             }
             const cancelledInstance = await this.closeInstance(manager, instance, workflow_engine_enums_1.ApprovalInstanceStateEnum.CANCELLED);
             await manager.getRepository(activity_log_entity_1.ActivityLogEntity).save(manager.getRepository(activity_log_entity_1.ActivityLogEntity).create({
-                actorMemberId: input.cancelledByMemberId,
+                actorMemberId: cancellation.actorMemberId,
                 eventType: workflow_engine_enums_1.ActivityLogEventTypeEnum.INSTANCE_CANCELLED,
                 instanceId: instance.id,
                 nodeId: null,
-                payload: {
-                    comment: input.comment?.trim() || null,
-                },
+                payload: cancellation.payload,
                 taskId: null,
             }));
+            await this.recordInstanceEvent(manager, cancelledInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.CANCELLED, 'INSTANCE_CANCELLED', { actorMemberId: cancellation.actorMemberId });
             return cancelledInstance;
         });
     }
@@ -1007,6 +1561,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 },
                 taskId: input.taskId ?? null,
             }));
+            await this.recordInstanceEvent(manager, expiredInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.EXPIRED, 'INSTANCE_EXPIRED', {});
             return expiredInstance;
         });
     }
@@ -1035,7 +1590,13 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         return closedInstance;
     }
     async resubmitApprovalInstance(input, authContext) {
+        return this.withAdvanceFailureRecorded(() => this.resubmitApprovalInstanceInTransaction(input, authContext));
+    }
+    async resubmitApprovalInstanceInTransaction(input, authContext) {
         const submittedFormData = parseJsonObject(input.formDataJson, 'formDataJson');
+        if (input.endUserSubmission === true) {
+            await this.assertEndUserMayResubmit(input.instanceId);
+        }
         const preparation = this.formDataSourceValueResolver
             ? await this.prepareResubmitFormDataOptions(input, submittedFormData, authContext ?? createWorkflowAuthContext(input.initiatorMemberId))
             : null;
@@ -1065,20 +1626,37 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 throw new common_1.ConflictException('Approval instance changed while options were resolving; refresh and retry');
             }
             const resubmitSchema = readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot);
-            const deferredFieldKeys = (0, bpm_core_shared_1.readApproverFilledFieldKeys)(instance.workflowSnapshot);
+            const deferral = (0, approver_filled_table_columns_1.readApproverFilledDeferral)(instance.workflowSnapshot);
             // An end user gets back the value an approver already filled in, and
             // loses a key the stored data never had: the renderer seeds `false`,
             // `[]` and empty rows for every field, none of which an approver wrote.
+            // An open cell of a table is settled per row the same way.
             const formData = input.endUserSubmission === true
-                ? (0, bpm_core_shared_1.overlayStoredFormDataKeys)(submittedFormData, instance.formData, deferredFieldKeys)
+                ? (0, approver_filled_table_columns_1.applyOpenColumnCells)((0, bpm_core_shared_1.overlayStoredFormDataKeys)(submittedFormData, instance.formData, deferral.wholeKeys), instance.formData, deferral)
                 : submittedFormData;
-            validateSubmittedFormData(resubmitSchema, formData, {
-                deferredFieldKeys,
-            });
+            validateSubmittedFormData((0, approver_filled_table_columns_1.projectOpenColumnsOptional)(resubmitSchema, deferral), formData, { deferredFieldKeys: deferral.wholeKeys });
             await this.assertCurrentFilterableFormDataValues(instance.templateId, formData, manager);
             if (!preparation) {
                 assertNoUnresolvableDynamicValues(resubmitSchema, formData);
             }
+            // ADR 27 §2: the host guard judges the resubmission as it will be
+            // committed, after every form check and before the write.
+            if (this.instanceGuard !== null) {
+                await this.guardInstanceChange({
+                    action: null,
+                    actorMemberId: input.initiatorMemberId,
+                    authContext: authContext ?? null,
+                    automatic: null,
+                    changedFieldKeys: listChangedFormDataKeys(instance.formData, formData),
+                    formData,
+                    instance,
+                    kind: 'RESUBMIT',
+                    manager,
+                    node: null,
+                    task: null,
+                    templateVersion: await this.readBoundTemplateVersionOrThrow(manager, instance),
+                });
+            }
             const resubmittedInstance = await instanceRepository.save({
                 ...instance,
                 completedAt: null,
@@ -1091,6 +1669,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 state: workflow_engine_enums_1.ApprovalInstanceStateEnum.RUNNING,
                 title: input.title?.trim() || instance.title,
             });
+            // Written before the resume below, so RESUBMITTED precedes any
+            // NODE_ACTIVATED that the resume produces in the same transaction.
+            await this.recordInstanceEvent(manager, resubmittedInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.RUNNING, 'INSTANCE_RESUBMITTED', { actorMemberId: input.initiatorMemberId });
             await this.attachmentService.bindFormDataAttachmentsToInstance(manager, {
                 formData,
                 instanceId: instance.id,
@@ -1118,7 +1699,15 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 },
                 taskId: null,
             }));
-            await this.processRunningInstance(manager, runtimeInstance);
+            await runInstanceAdvanceStep({
+                action: null,
+                actorMemberId: input.initiatorMemberId,
+                automatic: null,
+                instanceId: instance.id,
+                kind: 'RESUBMIT',
+                nodeId: null,
+                taskId: null,
+            }, () => this.processRunningInstance(manager, runtimeInstance));
             const refreshedInstance = await instanceRepository.findOne({
                 where: { id: instance.id },
             });
@@ -1404,7 +1993,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
     }
     async resolveAdhocTaskCandidates(manager, instance, node, label, targetValue) {
         const exclusions = await this.readNodeExclusions(manager, instance, node);
-        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), `${label}「${node.data.label}」`, '簽核人', exclusions.memberIds);
+        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), `${label}「${node.data.label}」`, '簽核人', exclusions.memberIds, null);
         // Ad-hoc approvers are picked by a person, not walked up a manager chain,
         // so the chain's grade rule does not apply to them.
         const delegatedCandidates = await this.delegateResolvedCandidates(manager, instance, node.id, resolvedCandidates, false);
@@ -1812,7 +2401,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             return;
         }
         try {
-            const recipients = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), '臨時通知對象', '通知對象');
+            const recipients = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), '臨時通知對象', '通知對象', [], null);
             await this.notificationService.createAdhocWorkflowNotifications({
                 channels: directive.channels,
                 instance,
@@ -1864,11 +2453,13 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             input.workflowDefinitionJson,
             input.formDataJson,
             input.initiatorMetadataSnapshotJson ?? '',
+            input.formSchemaJson ?? '',
         ].some((json) => json.length > MAX_DRY_RUN_INPUT_LENGTH)) {
             return createFailedDryRunResult('試跑資料過大，請縮小流程或測試資料後再試');
         }
         const workflowDefinition = parseWorkflowDefinition(input.workflowDefinitionJson);
         const formData = parseJsonObject(input.formDataJson, 'formDataJson');
+        const formSchema = readDryRunFormSchema(input.formSchemaJson);
         // The snapshot here is the caller's own sample (the designer always sends
         // one) or a bare `{ customFields: {}, memberId }`. It is not the one a real
         // submission builds, and a dry run has no template version to hand the
@@ -1885,6 +2476,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             return Object.assign(new workflow_dry_run_object_1.WorkflowDryRunResultObject(), {
                 errors: [],
                 steps: (0, expression_budget_1.runExpressionOperation)(() => (0, time_budget_1.runWithinTimeBudget)(() => this.simulateWorkflow({
+                    expressionFormData: this.expressionMissingFormFieldsAsNull && formSchema
+                        ? (0, missing_form_fields_1.fillMissingFormFields)(formData, formSchema)
+                        : formData,
                     formData,
                     initiatorMemberId: input.initiatorMemberId,
                     initiatorMetadataSnapshot,
@@ -2189,6 +2783,51 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         }
         return instance;
     }
+    /**
+     * 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.
+     */
+    async listApproverFillUnits(instanceId, memberId) {
+        const instance = await this.approvalInstanceRepository.findOne({
+            where: { id: instanceId },
+        });
+        if (!instance ||
+            instance.state !== workflow_engine_enums_1.ApprovalInstanceStateEnum.RUNNING) {
+            return [];
+        }
+        const tasks = await this.taskRepository.find({
+            where: {
+                instanceId,
+                isAdhoc: false,
+                status: (0, typeorm_2.In)([workflow_engine_enums_1.TaskStatusEnum.PENDING, workflow_engine_enums_1.TaskStatusEnum.IN_PROGRESS]),
+            },
+        });
+        const unitsPerTask = await Promise.all(tasks.map(async (task) => {
+            const node = instance.workflowSnapshot.nodes.find((candidate) => candidate.type === 'userTask' && candidate.id === task.nodeId);
+            if (!node) {
+                return [];
+            }
+            try {
+                await this.readTaskActorContext(this.taskRepository.manager, task, memberId);
+            }
+            catch (error) {
+                if (error instanceof common_1.ConflictException) {
+                    return [];
+                }
+                throw error;
+            }
+            const shown = new Set((0, bpm_core_shared_1.readNodeFieldAccess)(node)
+                .filter((entry) => entry.display === 'SHOW')
+                .map((entry) => entry.fieldKey));
+            return (0, bpm_core_shared_1.readNodeFillUnits)(node).filter((unit) => shown.has(unit.fieldKey));
+        }));
+        return unitsPerTask.flat();
+    }
     /**
      * 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
@@ -2274,7 +2913,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             totalPages,
         };
     }
-    async createFilteredApprovalInstanceQuery(scope, options = {}) {
+    async createFilteredApprovalInstanceQuery(scope, requested = {}) {
+        const options = await this.resolveApprovalInstanceTemplateKey(requested);
+        if (!options) {
+            return null;
+        }
         const queryBuilder = this.approvalInstanceRepository.createQueryBuilder('approvalInstance');
         const hasReadableInstances = this.applyReadableInstanceFilter(queryBuilder, scope, options);
         if (!hasReadableInstances) {
@@ -2502,9 +3145,15 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             memberId,
             submission: null,
         });
-        return templates.filter((template) => this.isInitiatorPolicyMet(template, template.currentVersionId
-            ? (versionById.get(template.currentVersionId) ?? null)
-            : null, initiatorMetadataSnapshot, 'launchable templates'));
+        return templates.filter((template) => {
+            const version = template.currentVersionId
+                ? (versionById.get(template.currentVersionId) ?? null)
+                : null;
+            // A HOST_ONLY template is started by the host's backend, never from the
+            // launch page (ADR 27 §5), so it is not offered there at all.
+            return (version?.launchMode !== template_enums_1.ApprovalTemplateLaunchModeEnum.HOST_ONLY &&
+                this.isInitiatorPolicyMet(template, version, initiatorMetadataSnapshot, 'launchable templates'));
+        });
     }
     /**
      * The published version whose form `memberId` may read data-source options
@@ -2605,7 +3254,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      * given its candidate summaries.
      */
     async listInboxTasks(assigneeMemberId, options = {}) {
-        const openTasks = await this.readSharedOpenInboxTasks(assigneeMemberId);
+        const openTasks = await this.filterTasksByTemplate(await this.readSharedOpenInboxTasks(assigneeMemberId), options);
         if (!isTaskListPaged(options)) {
             return this.attachTaskCandidateSummaries(openTasks);
         }
@@ -2613,8 +3262,77 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         return this.attachTaskCandidateSummaries(openTasks.slice(offset, offset + normalizePageSize(options.pageSize)));
     }
     /** How many tasks {@link listInboxTasks} pages through. */
-    async countInboxTasks(assigneeMemberId) {
-        return (await this.readSharedOpenInboxTasks(assigneeMemberId)).length;
+    async countInboxTasks(assigneeMemberId, filter = {}) {
+        return (await this.filterTasksByTemplate(await this.readSharedOpenInboxTasks(assigneeMemberId), filter)).length;
+    }
+    /**
+     * The template ids a {@link TaskTemplateFilter} allows, or `null` when it
+     * does not filter. A `templateKey` that names no template allows nothing.
+     */
+    async readTaskTemplateFilterIds(filter) {
+        // Trimmed, and a blank key does not filter, as on the instance list.
+        const key = normalizeText(filter.templateKey);
+        const byKey = key ? await this.readTemplateIdsByKey(key) : null;
+        if (filter.templateIds === undefined) {
+            return byKey;
+        }
+        if (byKey === null) {
+            return filter.templateIds;
+        }
+        return filter.templateIds.filter((id) => byKey.includes(id));
+    }
+    /**
+     * 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.
+     */
+    async resolveApprovalInstanceTemplateKey(options) {
+        const key = normalizeText(options.templateKey);
+        if (!key) {
+            return options;
+        }
+        const [templateId] = await this.readTemplateIdsByKey(key);
+        const requestedId = normalizeText(options.templateId);
+        if (!templateId || (requestedId && requestedId !== templateId)) {
+            return null;
+        }
+        return { ...options, templateId };
+    }
+    /**
+     * 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.
+     */
+    async readTemplateIdsByKey(key) {
+        const template = await this.approvalTemplateRepository.findOne({
+            select: { id: true },
+            where: { key },
+        });
+        return template ? [template.id] : [];
+    }
+    /**
+     * 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.
+     */
+    async filterTasksByTemplate(tasks, filter) {
+        const templateIds = await this.readTaskTemplateFilterIds(filter);
+        if (templateIds === null) {
+            return tasks;
+        }
+        if (!templateIds.length || !tasks.length) {
+            return [];
+        }
+        const instances = await this.approvalInstanceRepository.find({
+            select: { id: true },
+            where: {
+                id: (0, typeorm_2.In)([
+                    ...new Set(tasks.map((task) => task.instanceId)),
+                ]),
+                templateId: (0, typeorm_2.In)([...templateIds]),
+            },
+        });
+        const instanceIds = new Set(instances.map((instance) => instance.id));
+        return tasks.filter((task) => instanceIds.has(task.instanceId));
     }
     /**
      * {@link readOpenInboxTasks} for the inbox list and its count, joining a
@@ -2711,7 +3429,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      */
     async listApprovalHistoryTasks(assigneeMemberId, options = {}) {
         const paged = isTaskListPaged(options);
-        const tasks = await this.createApprovalHistoryTaskQuery(assigneeMemberId, options.instanceState)
+        const templateIds = await this.readTaskTemplateFilterIds(options);
+        if (templateIds?.length === 0) {
+            return [];
+        }
+        const tasks = await this.createApprovalHistoryTaskQuery(assigneeMemberId, options.instanceState, templateIds)
             .orderBy(this.readApprovalHistoryActedAtExpression(), 'DESC')
             .addOrderBy('"task"."id"', 'DESC')
             .offset(paged ? readPageOffset(options.page, options.pageSize) : 0)
@@ -2723,10 +3445,14 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
     }
     /** How many tasks {@link listApprovalHistoryTasks} pages through. */
     async countApprovalHistoryTasks(assigneeMemberId, options = {}) {
-        return this.createApprovalHistoryTaskQuery(assigneeMemberId, options.instanceState).getCount();
+        const templateIds = await this.readTaskTemplateFilterIds(options);
+        if (templateIds?.length === 0) {
+            return 0;
+        }
+        return this.createApprovalHistoryTaskQuery(assigneeMemberId, options.instanceState, templateIds).getCount();
     }
     /** The rows of {@link listApprovalHistoryTasks}, unordered and unpaged. */
-    createApprovalHistoryTaskQuery(assigneeMemberId, instanceState) {
+    createApprovalHistoryTaskQuery(assigneeMemberId, instanceState, templateIds = null) {
         const candidateTable = this.readQualifiedTableName(this.taskCandidateRepository);
         const queryBuilder = this.taskRepository
             .createQueryBuilder('task')
@@ -2759,6 +3485,16 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
           )
         `, { historyInstanceState: instanceState });
         }
+        if (templateIds) {
+            queryBuilder.andWhere(`
+          EXISTS (
+            SELECT 1
+            FROM ${this.readQualifiedTableName(this.approvalInstanceRepository)} "historyTemplateInstance"
+            WHERE "historyTemplateInstance"."id" = "task"."instance_id"
+              AND "historyTemplateInstance"."template_id" IN (:...historyTemplateIds)
+          )
+        `, { historyTemplateIds: [...templateIds] });
+        }
         return queryBuilder;
     }
     /** When the member acted on a history task; see {@link listApprovalHistoryTasks}. */
@@ -2845,7 +3581,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      * 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.
      */
     async readTaskNodeSummaries(tasks) {
         // The table as the entity reads it, so a configured `schema` is honoured
@@ -2880,7 +3616,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             readNodeLabelKey(row.instanceId, row.nodeId),
             {
                 hasFillableFields: row.nodeType === 'userTask' &&
-                    (0, bpm_core_shared_1.readNodeFillableFieldKeys)({
+                    (0, bpm_core_shared_1.readNodeFillGrantFieldKeys)({
                         data: { fieldAccess: row.fieldAccess },
                     }).size > 0,
                 label: typeof row.label === 'string' && row.label.trim()
@@ -3169,6 +3905,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         });
         await this.dispatchAdhocCompletionNotifications(manager, completedInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.APPROVED);
         await this.cancelPendingAdhocDirectives(manager, instance.id, null);
+        await this.recordInstanceEvent(manager, completedInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.APPROVED, 'INSTANCE_APPROVED', {});
     }
     async isNodeEntryReady(manager, instance, token, node) {
         if (node.type === 'startEvent') {
@@ -3234,7 +3971,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
     }
     isNodeEntryConditionMet(instance, node) {
         const entryCondition = readNodeEntryCondition(node);
-        return this.conditionService.evaluateBoolean(entryCondition, buildWorkflowExpressionContext(instance), `workflow.nodes.${node.id}.data.entryCondition`, readExpressionDialectOptions(entryCondition, instance.workflowSnapshot));
+        return this.conditionService.evaluateBoolean(entryCondition, this.buildExpressionContext(instance), `workflow.nodes.${node.id}.data.entryCondition`, readExpressionDialectOptions(entryCondition, instance.workflowSnapshot));
     }
     async skipNodeByEntryCondition(manager, instance, token, node) {
         await this.skipNode(manager, instance, token, node, {
@@ -3242,9 +3979,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         });
     }
     async skipNodeByInitiatorExclusion(manager, instance, token, node, skippedBy = 'INITIATOR') {
-        await this.skipNode(manager, instance, token, node, skippedBy === 'NODE_ACTORS'
-            ? { skippedByNodeActorExclusion: true }
-            : { skippedByInitiatorExclusion: true });
+        await this.skipNode(manager, instance, token, node, SKIPPED_RUNTIME_TASK_PAYLOADS[skippedBy]);
     }
     async skipNode(manager, instance, token, node, reason) {
         // A NOTIFY node is an asynchronous branch that may not have an outgoing
@@ -3308,7 +4043,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             });
         }
         const context = {
-            ...buildWorkflowExpressionContext(instance),
+            ...this.buildExpressionContext(instance),
             lastDecision: await this.readLastDecisionContext(manager, instance.id, node.id),
         };
         return evaluateWithStructuredFallback(edge, instance.formData, (message) => this.logger.warn(`instance=${instance.id} ${message}`), () => this.conditionService.evaluateBoolean(expression, context, `workflow.edges.${edge.id}.data.condition`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) }));
@@ -3431,6 +4166,12 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             // worse — an `endState: 'REJECTED'` row overwritten with `APPROVED`
             // immediately after it had been committed.
             const completedInstance = await instanceRepository.save(Object.assign(instance, { completedAt, state: instanceState }));
+            if (instanceState === workflow_engine_enums_1.ApprovalInstanceStateEnum.REJECTED) {
+                await this.recordInstanceEvent(manager, completedInstance, instanceState, 'INSTANCE_REJECTED', { actorMemberId: null });
+            }
+            else {
+                await this.recordInstanceEvent(manager, completedInstance, instanceState, 'INSTANCE_APPROVED', {});
+            }
             if (instanceState === workflow_engine_enums_1.ApprovalInstanceStateEnum.APPROVED) {
                 await this.notificationService.createInstanceCompletedNotification({
                     instance: completedInstance,
@@ -3532,7 +4273,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         const singleCandidate = savedCandidates.length === 1 ? savedCandidates[0] : null;
         const openCandidates = savedCandidates.filter((candidate) => candidate.status === workflow_engine_enums_1.TaskCandidateStatusEnum.PENDING);
         task.openCandidateMemberIds = openCandidates.map((candidate) => candidate.memberId);
-        task.hasFillableFields = (0, bpm_core_shared_1.readNodeFillableFieldKeys)(node).size > 0;
+        task.hasFillableFields = (0, bpm_core_shared_1.readNodeFillGrantFieldKeys)(node).size > 0;
         await tokenRepository.save({
             ...token,
             status: workflow_engine_enums_1.WorkflowTokenStatusEnum.WAITING,
@@ -3559,6 +4300,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             },
             taskId: task.id,
         }));
+        await this.recordInstanceEvent(manager, instance, instance.state, 'NODE_ACTIVATED', { nodeId: node.id, taskIds: [task.id] });
         await openCandidates.reduce(async (previous, candidate) => {
             await previous;
             await this.notificationService.createTaskAssignedNotification({
@@ -3949,9 +4691,23 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      * 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.
      */
     async reassignMemberTasks(options) {
-        const held = await this.readRunningMemberTasks(options.fromMemberId);
+        const { taskIds } = options;
+        if (taskIds && taskIds.length === 0) {
+            throw new common_1.BadRequestException('taskIds must not be empty: omit it to reassign every open task');
+        }
+        const wanted = taskIds ? new Set(taskIds) : null;
+        const allHeld = await this.readRunningMemberTasks(options.fromMemberId);
+        const held = wanted
+            ? allHeld.filter(({ task }) => wanted.has(task.id))
+            : allHeld;
         return held.reduce(async (previous, { task }) => {
             const results = await previous;
             const result = await this.executeTaskReassignment(task, options).catch((error) => {
@@ -4020,6 +4776,103 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             };
         });
     }
+    /**
+     * 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.
+     */
+    async listStuckApprovalInstances(options = {}) {
+        return this.approvalInstanceRepository.manager.transaction(async (manager) => {
+            const failureIds = await (0, stuck_approval_instance_query_1.readStuckFailurePage)(manager, OPEN_TASK_STATUSES, {
+                limit: normalizePageSize(options.pageSize),
+                offset: readPageOffset(options.page, options.pageSize),
+            });
+            const failures = failureIds.length
+                ? await manager
+                    .getRepository(activity_log_entity_1.ActivityLogEntity)
+                    .find({ where: { id: (0, typeorm_2.In)([...failureIds]) } })
+                : [];
+            const instances = failures.length
+                ? await manager.getRepository(approval_instance_entity_1.ApprovalInstanceEntity).find({
+                    where: {
+                        id: (0, typeorm_2.In)([
+                            ...new Set(failures.map((failure) => failure.instanceId)),
+                        ]),
+                    },
+                })
+                : [];
+            const failureById = new Map(failures.map((failure) => [
+                failure.id,
+                failure,
+            ]));
+            const instanceById = new Map(instances.map((instance) => [
+                instance.id,
+                instance,
+            ]));
+            // `find` does not keep the order of the ids; the page's order is the
+            // database's.
+            const stuck = failureIds.flatMap((failureId) => {
+                const failure = failureById.get(failureId);
+                const instance = failure && instanceById.get(failure.instanceId);
+                return failure && instance ? [{ failure, instance }] : [];
+            });
+            if (stuck.length === 0) {
+                return [];
+            }
+            const taskIds = [
+                ...new Set(stuck.flatMap(({ failure }) => failure.taskId ? [failure.taskId] : [])),
+            ];
+            const tasks = taskIds.length
+                ? await manager
+                    .getRepository(task_entity_1.TaskEntity)
+                    .find({ where: { id: (0, typeorm_2.In)(taskIds) } })
+                : [];
+            const candidates = taskIds.length
+                ? await manager.getRepository(task_candidate_entity_1.TaskCandidateEntity).find({
+                    order: {
+                        sequence: { direction: 'ASC', nulls: 'LAST' },
+                        createdAt: 'ASC',
+                        id: 'ASC',
+                    },
+                    where: { taskId: (0, typeorm_2.In)(taskIds) },
+                })
+                : [];
+            const templates = await manager
+                .getRepository(approval_template_entity_1.ApprovalTemplateEntity)
+                .find({
+                where: {
+                    id: (0, typeorm_2.In)([
+                        ...new Set(stuck.map(({ instance }) => instance.templateId)),
+                    ]),
+                },
+            });
+            const templateNameById = new Map(templates.map((template) => [
+                template.id,
+                template.name,
+            ]));
+            return stuck.map((candidate) => toStuckApprovalInstanceRecord(candidate, {
+                candidates,
+                tasks,
+                templateNameById,
+            }));
+        });
+    }
+    /** How many instances {@link listStuckApprovalInstances} pages through. */
+    async countStuckApprovalInstances() {
+        return this.approvalInstanceRepository.manager.transaction(async (manager) => (0, stuck_approval_instance_query_1.countStuckInstances)(manager, OPEN_TASK_STATUSES));
+    }
     /**
      * Deactivated members who still hold open tasks, so an administrator can find
      * them: a deactivated member no longer shows up in the member search.
@@ -4447,7 +5300,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      * 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
@@ -4456,8 +5311,14 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      */
     async resolveRuntimeTaskCandidates(manager, instance, node) {
         const label = `簽核節點「${node.data.label}」`;
+        // Worked out before anything else because it can end the node: a chain
+        // that needs nobody more is skipped without resolving or excluding anyone.
+        const chainContext = await this.resolveOrgManagerChainContext(manager, instance, node, label);
+        if (chainContext?.skipped) {
+            return { skippedBy: 'MANAGER_CHAIN_REACHED' };
+        }
         const exclusions = await this.readNodeExclusions(manager, instance, node);
-        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, node.data.approverResolver, label, '簽核人', exclusions.memberIds);
+        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, node.data.approverResolver, label, '簽核人', exclusions.memberIds, chainContext);
         const delegatedCandidates = await this.delegateResolvedCandidates(manager, instance, node.id, resolvedCandidates, isOrgManagerChainNode(node));
         const hasExclusion = hasSeatExclusion(node);
         const hasSubmitter = (0, instance_submitter_1.readDistinctSubmitterMemberId)(instance) !== null;
@@ -4497,6 +5358,136 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 ? `${label} 無法建立待簽任務：解析出的簽核人只剩申請人或代為送出此單的人（含委派後的代理人），且此節點不允許申請人或代送人簽核。`
                 : `${label} 無法建立待簽任務：解析出的簽核人只剩申請人本人（含委派後的代理人），且此節點不允許申請人自簽。`);
     }
+    /**
+     * 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.
+     */
+    async resolveOrgManagerChainContext(manager, instance, node, label) {
+        const resolver = node.data.approverResolver;
+        if (resolver.type !== 'ORG_MANAGER_CHAIN' ||
+            !usesOrgManagerChainSettings(resolver)) {
+            return null;
+        }
+        const shapeIssue = (0, workflow_graph_1.readOrgManagerChainIssue)(resolver, '簽核節點');
+        if (shapeIssue !== null) {
+            throw new common_1.ConflictException(`${label} 無法建立待簽任務：${shapeIssue}`);
+        }
+        if (!(0, workflow_1.isOrgManagerChainContinuation)(resolver)) {
+            return {
+                continuation: null,
+                skipped: await this.isOrgManagerChainStartLevelReached(manager, instance, resolver, label),
+            };
+        }
+        const found = readChainContinuationSource(instance.workflowSnapshot, node.id, resolver);
+        if ('issue' in found) {
+            throw new common_1.ConflictException(`${label} 無法建立待簽任務：${found.issue}`);
+        }
+        // The earlier stage's own start, so both stages climb the same line.
+        const start = await this.resolveOrgManagerChainStart(manager, instance, found.source, label, '簽核人');
+        const reachedLevel = await this.readChainStageReachedLevel(manager, instance, found.sourceId);
+        return {
+            continuation: { reachedLevel, start },
+            skipped: reachedLevel !== null && reachedLevel >= resolver.minPositionLevel,
+        };
+    }
+    /**
+     * `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.
+     */
+    async isOrgManagerChainStartLevelReached(manager, instance, resolver, label) {
+        const start = await this.resolveOrgManagerChainStart(manager, instance, resolver, label, '簽核人');
+        if (start.memberId === null) {
+            return false;
+        }
+        const level = await this.readMemberPositionLevel(manager, start.memberId, this.readOrganizationToday());
+        return level !== null && level >= resolver.minPositionLevel;
+    }
+    /**
+     * 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.
+     */
+    async readChainStageReachedLevel(manager, instance, stageNodeId) {
+        if (await this.wasChainStageSkippedLastRound(manager, instance, stageNodeId)) {
+            return null;
+        }
+        const approvals = (await this.readNodeActorApprovals(manager, instance, [stageNodeId])).map((decision) => ({
+            date: (0, organization_time_zone_1.formatDateOnlyInTimeZone)(decision.decidedAt, this.organizationTimeZone),
+            memberId: decision.decidedByMemberId,
+        }));
+        const levelGroups = await Promise.all(uniqueTexts(approvals.map((approval) => approval.date)).map(async (date) => [
+            ...(await this.readMemberPositionLevels(manager, approvals
+                .filter((approval) => approval.date === date)
+                .map((approval) => approval.memberId), date)).values(),
+        ]));
+        const levels = levelGroups
+            .flat()
+            .filter((level) => level !== null);
+        return levels.length === 0 ? null : Math.max(...levels);
+    }
+    /**
+     * 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.
+     */
+    async wasChainStageSkippedLastRound(manager, instance, stageNodeId) {
+        const [logs, stageTasks] = await Promise.all([
+            manager.getRepository(activity_log_entity_1.ActivityLogEntity).find({
+                where: {
+                    eventType: (0, typeorm_2.In)([
+                        workflow_engine_enums_1.ActivityLogEventTypeEnum.TOKEN_ADVANCED,
+                        workflow_engine_enums_1.ActivityLogEventTypeEnum.TASK_CREATED,
+                    ]),
+                    instanceId: instance.id,
+                    nodeId: stageNodeId,
+                },
+            }),
+            manager.getRepository(task_entity_1.TaskEntity).find({
+                where: { instanceId: instance.id, isAdhoc: false, nodeId: stageNodeId },
+            }),
+        ]);
+        const stageTaskIds = new Set(stageTasks.map((task) => task.id));
+        const newestSeq = (matching) => matching.reduce((newest, log) => {
+            const seq = BigInt(log.seq);
+            return newest === null || seq > newest ? seq : newest;
+        }, null);
+        const skippedSeq = newestSeq(logs.filter((log) => log.eventType === workflow_engine_enums_1.ActivityLogEventTypeEnum.TOKEN_ADVANCED &&
+            log.payload['skippedByManagerChainReached'] === true));
+        const createdSeq = newestSeq(logs.filter((log) => log.eventType === workflow_engine_enums_1.ActivityLogEventTypeEnum.TASK_CREATED &&
+            log.taskId !== null &&
+            stageTaskIds.has(log.taskId)));
+        return (skippedSeq !== null && (createdSeq === null || skippedSeq > createdSeq));
+    }
     /**
      * Everyone `node` keeps out of its approvers, per rule: the initiator and
      * the submitter for `excludeInitiator`, and everyone who actually approved
@@ -4618,9 +5609,22 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             skippedDelegations: collectSkippedDelegations(delegatedCandidates, true, replacementExcludedMemberIds),
         };
     }
+    /**
+     * 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).
+     */
+    buildExpressionContext(instance) {
+        return buildWorkflowExpressionContext(instance, this.readExpressionFormData(instance));
+    }
+    readExpressionFormData(instance) {
+        return this.expressionMissingFormFieldsAsNull
+            ? (0, missing_form_fields_1.fillMissingFormFields)(instance.formData, readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot))
+            : instance.formData;
+    }
     buildDelegationContext(instance, nodeId) {
         return {
-            formData: instance.formData,
+            formData: this.readExpressionFormData(instance),
             initiatorMemberId: instance.initiatorMemberId,
             initiatorMetadataSnapshot: instance.initiatorMetadataSnapshot,
             instanceId: instance.id,
@@ -4698,15 +5702,18 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             ? requiredLevel
             : null;
     }
-    async resolveApproverResolver(manager, instance, resolver, label, subject = '簽核人', skippedChainMemberIds = []) {
-        const memberIds = await this.resolveApproverMemberIds(manager, instance, resolver, label, subject, skippedChainMemberIds);
+    async resolveApproverResolver(manager, instance, resolver, label, subject, skippedChainMemberIds, 
+    // Required, so a new entry point has to say it has none: only task
+    // creation works one out, and a chain that needs it refuses without it.
+    chainContext) {
+        const memberIds = await this.resolveApproverMemberIds(manager, instance, resolver, label, subject, skippedChainMemberIds, chainContext);
         return memberIds.map((memberId) => ({
             memberId,
             sourceType: resolver.type,
         }));
     }
     /** The member ids `resolver` routes to; every source type, one branch each. */
-    async resolveApproverMemberIds(manager, instance, resolver, label, subject, skippedChainMemberIds) {
+    async resolveApproverMemberIds(manager, instance, resolver, label, subject, skippedChainMemberIds, chainContext) {
         if (resolver.type === 'DIRECT') {
             return readMemberIdsFromValue(resolver.memberIds, label, subject);
         }
@@ -4714,7 +5721,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             return readMemberIdsFromValue(readValueAtPath(instance.formData, resolver.formPath), label, subject, `依表單欄位「${resolver.formPath}」`);
         }
         if (resolver.type === 'EXPRESSION') {
-            return readMemberIdsFromValue(this.conditionService.evaluateValue(resolver.expression, buildWorkflowExpressionContext(instance), `${label}.expression`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) }), label, subject, '依運算式');
+            return readMemberIdsFromValue(this.conditionService.evaluateValue(resolver.expression, this.buildExpressionContext(instance), `${label}.expression`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) }), label, subject, '依運算式');
         }
         if (resolver.type === 'POSITION') {
             return this.resolvePositionCandidates(manager, resolver.positionId, label, subject);
@@ -4729,7 +5736,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             return this.resolveOrgUnitManagerCandidates(manager, instance, resolver.orgUnitId, resolver.fallback, label, resolver.preferClosestOrgUnit === true, subject);
         }
         if (resolver.type === 'ORG_MANAGER_CHAIN') {
-            return this.resolveOrgManagerChainCandidates(manager, instance, resolver, label, subject, skippedChainMemberIds);
+            return this.resolveOrgManagerChainCandidates(manager, instance, resolver, label, subject, skippedChainMemberIds, chainContext);
         }
         if (resolver.type === 'ORG_MANAGER') {
             return this.resolveInitiatorManagerCandidates(manager, instance, resolver.levelsUp, resolver.fallback, label, resolver.preferClosestOrgUnit === true, subject);
@@ -4844,7 +5851,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      */
     async readNodeActorApprovals(manager, instance, nodeIds) {
         const tasks = await manager.getRepository(task_entity_1.TaskEntity).find({
-            where: { instanceId: instance.id, isAdhoc: false, nodeId: (0, typeorm_2.In)([...nodeIds]) },
+            where: {
+                instanceId: instance.id,
+                isAdhoc: false,
+                nodeId: (0, typeorm_2.In)([...nodeIds]),
+            },
         });
         if (tasks.length === 0) {
             return [];
@@ -4860,7 +5871,10 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         }
         const [decisions, decidedLogs] = await Promise.all([
             manager.getRepository(task_decision_entity_1.TaskDecisionEntity).find({
-                where: { action: workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED, taskId: (0, typeorm_2.In)(batchTaskIds) },
+                where: {
+                    action: workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED,
+                    taskId: (0, typeorm_2.In)(batchTaskIds),
+                },
             }),
             manager.getRepository(activity_log_entity_1.ActivityLogEntity).find({
                 where: {
@@ -4922,11 +5936,26 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      * 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.
      */
-    async resolveOrgManagerChainCandidates(manager, instance, resolver, label, subject, skippedMemberIds) {
+    async resolveOrgManagerChainCandidates(manager, instance, resolver, label, subject, skippedMemberIds, chainContext) {
         const { fallback, minPositionLevel } = resolver;
         const startPositionLevel = (0, workflow_1.readOrgManagerChainStartPositionLevel)(resolver);
-        const start = await this.resolveOrgManagerChainStart(manager, instance, resolver, label, subject);
+        const continuation = chainContext?.continuation ?? null;
+        if (usesOrgManagerChainSettings(resolver) &&
+            (!chainContext ||
+                ((0, workflow_1.isOrgManagerChainContinuation)(resolver) && continuation === null))) {
+            throw new common_1.ConflictException(`${label} ${subject === '通知對象' ? '無法建立通知' : '無法建立待簽任務'}：${ORG_MANAGER_CHAIN_CONTEXT_REFUSAL}`);
+        }
+        const start = continuation?.start ??
+            (await this.resolveOrgManagerChainStart(manager, instance, resolver, label, subject));
         // Nobody to climb from: the same "no manager" path as a chain whose walk
         // finds nobody, so the fallback decides.
         if (start.memberId === null) {
@@ -4936,7 +5965,10 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         const visitedMemberIds = new Set([start.memberId]);
         const chain = [];
         let currentMemberId = start.memberId;
-        let lastAddedLevel = null;
+        // A continuation starts out as if the level its earlier stage got a
+        // signature from were the last one added: managers at or below it are
+        // walked past, so only those above it are asked.
+        let lastAddedLevel = continuation?.reachedLevel ?? null;
         for (let hop = 0; hop < ORG_MANAGER_CHAIN_MAX_HOPS; hop += 1) {
             // A chain is a single path, so it always uses closest-org-unit semantics
             // (merging ancestor-unit rules could only produce ties). The member is
@@ -5021,6 +6053,12 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         if (subject === '通知對象') {
             throw new common_1.ConflictException(`${label} ${failure}：知會節點的主管鏈只能從發起人開始。`);
         }
+        // The start of a continuation is its earlier stage's, which task creation
+        // hands over already resolved; asking for it here is a mistake of the
+        // caller, not a start to climb from.
+        if (startFrom.type === 'CHAIN_CONTINUATION') {
+            throw new common_1.ConflictException(`${label} ${failure}：${ORG_MANAGER_CHAIN_CONTEXT_REFUSAL}`);
+        }
         if (startFrom.type === 'FORM_MEMBER') {
             const source = `依表單欄位「${startFrom.formPath}」`;
             const pickedMemberIds = findMemberIdsInValue(readValueAtPath(instance.formData, startFrom.formPath));
@@ -5322,11 +6360,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         const action = node.data.action;
         if (action.type === 'WEBHOOK') {
             const payload = typeof action.payload === 'string' && action.payload.trim()
-                ? this.conditionService.evaluateValue(action.payload, buildWorkflowExpressionContext(instance), `workflow.nodes.${node.id}.data.action.payload`, {
+                ? this.conditionService.evaluateValue(action.payload, this.buildExpressionContext(instance), `workflow.nodes.${node.id}.data.action.payload`, {
                     dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot),
                 })
                 : {
-                    instance: buildWorkflowExpressionContext(instance).instance,
+                    instance: this.buildExpressionContext(instance).instance,
                     triggeredAt: new Date().toISOString(),
                 };
             await this.dispatchWebhookAfterCommit(manager, {
@@ -5354,7 +6392,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             return;
         }
         if (action.type === 'SET_FORM_FIELD') {
-            const value = this.conditionService.evaluateValue(action.value, buildWorkflowExpressionContext(instance), `workflow.nodes.${node.id}.data.action.value`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) });
+            const value = this.conditionService.evaluateValue(action.value, this.buildExpressionContext(instance), `workflow.nodes.${node.id}.data.action.value`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) });
             assertServiceTaskFieldValue(instance.formDefinitionSnapshot, action.fieldPath, value, node.data.label);
             const updatedFormData = writeValueAtPath(instance.formData, action.fieldPath, value);
             await this.assertCurrentFilterableFormDataValues(instance.templateId, updatedFormData, manager, node.data.label);
@@ -5404,7 +6442,10 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         const recipients = (0, workflow_graph_1.isNotifyRecipientsEmpty)(action.recipients) &&
             (0, workflow_graph_1.readNotifyWebhookTargets)(action).length > 0
             ? []
-            : await this.resolveApproverResolver(manager, instance, action.recipients, `知會節點「${node.data.label}」`, '通知對象');
+            : await this.resolveApproverResolver(manager, instance, action.recipients, `知會節點「${node.data.label}」`, '通知對象', [], 
+            // A notify node has no task to build the context: a chain that
+            // needs one is refused (publish lint forbids it here already).
+            null);
         const recipientMemberIds = uniqueTexts(recipients.map((recipient) => recipient.memberId));
         await this.notificationService.createServiceTaskNotifications({
             instance,
@@ -5416,8 +6457,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         // §3.5). Without the webhook module there is nothing to queue into; the
         // publish lint already refuses a template that references an endpoint
         // in that case.
-        const webhookDeliveryIds = this.webhookDeliveryService &&
-            (0, workflow_graph_1.readNotifyWebhookTargets)(action).length > 0
+        const webhookDeliveryIds = this.webhookDeliveryService && (0, workflow_graph_1.readNotifyWebhookTargets)(action).length > 0
             ? await this.webhookDeliveryService.enqueueNotifyWebhooks(manager, {
                 instance: {
                     formData: instance.formData,
@@ -5447,7 +6487,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             taskId: null,
         }));
     }
-    async rejectInstance(manager, instance, task, rejectedAt) {
+    async rejectInstance(manager, instance, task, rejectedAt, decidedByMemberId) {
         const instanceRepository = manager.getRepository(approval_instance_entity_1.ApprovalInstanceEntity);
         // Dispatch pending ad-hoc notifications for the rejecting node before the
         // remaining directives are cancelled by the terminal cleanup below.
@@ -5478,8 +6518,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             },
             taskId: task.id,
         }));
+        await this.recordInstanceEvent(manager, rejectedInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.REJECTED, 'INSTANCE_REJECTED', { actorMemberId: decidedByMemberId });
     }
-    async returnInstanceToNode(manager, instance, task, returnToNodeId, returnedAt) {
+    async returnInstanceToNode(manager, instance, task, returnToNodeId, returnedAt, decidedByMemberId) {
         if (!returnToNodeId) {
             throw new common_1.ConflictException('Return target node is required');
         }
@@ -5537,6 +6578,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 taskId: null,
             }),
         ]);
+        await this.recordInstanceEvent(manager, returnedInstance, returnedInstance.state, 'INSTANCE_RETURNED', { actorMemberId: decidedByMemberId, nodeId: task.nodeId });
         if (returnedInstance.state === workflow_engine_enums_1.ApprovalInstanceStateEnum.RUNNING) {
             await this.processRunningInstance(manager, returnedInstance);
         }
@@ -5738,6 +6780,9 @@ exports.WorkflowEngineService = WorkflowEngineService = WorkflowEngineService_1
     tslib_1.__param(20, (0, common_1.Optional)()),
     tslib_1.__param(21, (0, common_1.Optional)()),
     tslib_1.__param(21, (0, common_1.Inject)(initiator_custom_fields_resolver_token_1.BPM_INITIATOR_CUSTOM_FIELDS_RESOLVER)),
+    tslib_1.__param(22, (0, common_1.Optional)()),
+    tslib_1.__param(22, (0, common_1.Inject)(instance_guard_token_1.BPM_INSTANCE_GUARD)),
+    tslib_1.__param(23, (0, common_1.Optional)()),
     tslib_1.__metadata("design:paramtypes", [typeorm_2.Repository,
         typeorm_2.Repository,
         typeorm_2.Repository,
@@ -5754,7 +6799,7 @@ exports.WorkflowEngineService = WorkflowEngineService = WorkflowEngineService_1
         delegation_service_1.DelegationService,
         notification_service_1.NotificationService,
         signature_service_1.SignatureService,
-        sla_schedule_service_1.BPMSlaScheduleService, Object, Object, Object, workflow_webhook_delivery_service_1.WorkflowWebhookDeliveryService, Object])
+        sla_schedule_service_1.BPMSlaScheduleService, Object, Object, Object, workflow_webhook_delivery_service_1.WorkflowWebhookDeliveryService, Object, Object, instance_event_writer_1.InstanceEventWriter])
 ], WorkflowEngineService);
 function parseJsonObject(value, label) {
     try {
@@ -5777,6 +6822,67 @@ function readDefaultInitiatorMetadataSnapshot(memberId) {
         memberId,
     };
 }
+/**
+ * The form schema a dry run was given to fill unfilled fields with (ADR 27
+ * §3), or `null` when it was given none. A schema that does not parse is a
+ * 400, like the other inputs.
+ */
+function readDryRunFormSchema(json) {
+    if (!json) {
+        return null;
+    }
+    const schema = parseJsonObject(json, 'formSchemaJson');
+    if (!isFormDefinitionSchema(schema)) {
+        throw new common_1.BadRequestException('formSchemaJson is not a form schema');
+    }
+    return schema;
+}
+/**
+ * Refuses a submission or resubmission through GraphQL on a `HOST_ONLY`
+ * version (ADR 27 §5). Only the host's backend, calling the service, may start
+ * or resubmit such a case.
+ */
+function assertEndUserMayLaunch(version) {
+    if (version.launchMode === template_enums_1.ApprovalTemplateLaunchModeEnum.HOST_ONLY) {
+        throw new common_1.ForbiddenException('This approval template can only be submitted by the host system');
+    }
+}
+/**
+ * Reads the service-only `initiatorCustomFields` of a submission (ADR 27 §5):
+ * `null` when absent, otherwise a JSON copy. Refused with 400 when it is not a
+ * plain object or comes together with a whole `initiatorMetadataSnapshotJson`,
+ * which would leave it unclear which one decides.
+ */
+function readHostInitiatorCustomFields(input) {
+    const fields = input.initiatorCustomFields;
+    if (fields === undefined || fields === null) {
+        return null;
+    }
+    if (input.initiatorMetadataSnapshotJson) {
+        throw new common_1.BadRequestException('initiatorCustomFields cannot be combined with initiatorMetadataSnapshotJson');
+    }
+    if (typeof fields !== 'object' || Array.isArray(fields)) {
+        throw new common_1.BadRequestException('initiatorCustomFields must be an object');
+    }
+    return cloneJsonObject(fields);
+}
+/**
+ * Lays the host's `initiatorCustomFields` over the `customFields` of a built
+ * snapshot; a key the host gave wins over the resolver's.
+ */
+function mergeHostInitiatorCustomFields(snapshot, hostCustomFields) {
+    if (hostCustomFields === null) {
+        return snapshot;
+    }
+    const current = snapshot['customFields'];
+    return {
+        ...snapshot,
+        customFields: {
+            ...(isRecord(current) ? current : {}),
+            ...hostCustomFields,
+        },
+    };
+}
 function cloneJsonObject(value) {
     return JSON.parse(JSON.stringify(value));
 }
@@ -5861,7 +6967,8 @@ function createWorkflowAuthContext(memberId) {
     };
 }
 function isSameApprovalInstanceRevision(left, right) {
-    return (readApprovalInstanceRevision(left) === readApprovalInstanceRevision(right) &&
+    return (readApprovalInstanceRevision(left) ===
+        readApprovalInstanceRevision(right) &&
         JSON.stringify(left.formData) === JSON.stringify(right.formData));
 }
 /**
@@ -5891,7 +6998,9 @@ function readDataSourceFieldKeyAtPath(snapshot, fieldPath) {
     // A corrupt snapshot can hold non-object entries: read them defensively
     // rather than letting a service task throw.
     const field = schema.fields.find((candidate) => isRecord(candidate) && candidate.fieldKey === fieldKey);
-    return field && (0, form_1.isFormDataSourceFieldDefinition)(field) ? field.fieldKey : null;
+    return field && (0, form_1.isFormDataSourceFieldDefinition)(field)
+        ? field.fieldKey
+        : null;
 }
 /**
  * Refuses form data whose filterable fields hold a value of the wrong type
@@ -5979,6 +7088,13 @@ function assertServiceTaskFieldValue(snapshot, fieldPath, value, nodeLabel) {
 function readSnapshotWithoutField(snapshots, fieldKey) {
     return Object.fromEntries(Object.entries(snapshots ?? {}).filter(([key]) => key !== fieldKey));
 }
+/**
+ * Drops every snapshot that belongs to one of the fields, table cells included
+ * (`items[0].col` belongs to `items`).
+ */
+function readSnapshotWithoutFields(snapshots, fieldKeys) {
+    return Object.fromEntries(Object.entries(snapshots ?? {}).filter(([key]) => !fieldKeys.has((0, bpm_core_shared_1.readTopLevelFieldKey)(key))));
+}
 /**
  * Keeps only the snapshots whose field still carries a value, so clearing a
  * dynamic option also removes the label recorded for it.
@@ -6056,13 +7172,13 @@ function buildInitiatorPolicyContext(initiatorMetadataSnapshot) {
         subject: initiatorMetadataSnapshot,
     };
 }
-function buildWorkflowExpressionContext(instance) {
+function buildWorkflowExpressionContext(instance, formData) {
     return {
         env: {
             now: new Date().toISOString(),
         },
-        form: instance.formData,
-        formData: instance.formData,
+        form: formData,
+        formData,
         initiator: {
             ...instance.initiatorMetadataSnapshot,
             memberId: instance.initiatorMemberId,
@@ -6106,8 +7222,8 @@ function buildDryRunExpressionContext(input, lastDecision) {
         env: {
             now: new Date().toISOString(),
         },
-        form: input.formData,
-        formData: input.formData,
+        form: input.expressionFormData,
+        formData: input.expressionFormData,
         initiator: {
             ...input.initiatorMetadataSnapshot,
             memberId: input.initiatorMemberId,
@@ -6263,8 +7379,7 @@ function readDefaultReturnTargetNodeId(workflow, currentNode) {
 }
 function isReturnCommentRequired(workflow, nodeId) {
     const node = readWorkflowNodeOrThrow(workflow, nodeId);
-    return (node.type === 'userTask' &&
-        node.data.returnBehavior.requireComment === true);
+    return (node.type === 'userTask' && node.data.returnBehavior.requireComment === true);
 }
 function readReturnResubmitStrategy(task, instance) {
     const node = readWorkflowNodeOrThrow(instance.workflowSnapshot, task.nodeId);
@@ -6278,6 +7393,92 @@ function readReturnResubmitStrategyFromPayload(payload) {
         ? 'FROM_RETURN_POINT'
         : 'RESTART';
 }
+/**
+ * Whether a recorded failure is the one a new attempt would write again: same
+ * kind and key, same reason. A decision is keyed by task, actor and action, so
+ * the votes of a countersign each keep their own row; a resubmission has one
+ * key per instance. The same actor failing for a different reason is news, so
+ * the message is part of the match.
+ */
+function isSameAdvanceFailure(logged, context, message) {
+    if (readStringPayloadValue(logged.payload, 'kind') !== context.kind ||
+        logged.payload['message'] !== message) {
+        return false;
+    }
+    return (context.kind === 'RESUBMIT' ||
+        (logged.taskId === context.taskId &&
+            logged.actorMemberId === context.actorMemberId &&
+            readStringPayloadValue(logged.payload, 'action') === context.action));
+}
+/**
+ * Runs the step that moves an instance on and, when it fails with an error an
+ * operator is meant to read (an `HttpException` below 500), hands it on as an
+ * {@link InstanceAdvanceFailure} so the public method can record it once the
+ * transaction has rolled back. Everything else passes through untouched: a 5xx
+ * is usually a hiccup that retrying clears, and a plain `Error` may carry SQL.
+ *
+ * Used at the three call sites only. `processRunningInstance` and
+ * `returnInstanceToNode` stay unwrapped because submit and the administrator's
+ * re-run call them too, and they must keep throwing the original class.
+ */
+async function runInstanceAdvanceStep(context, step) {
+    try {
+        return await step();
+    }
+    catch (error) {
+        if (error instanceof common_1.HttpException && error.getStatus() < 500) {
+            throw new instance_advance_failure_1.InstanceAdvanceFailure(error, context);
+        }
+        throw error;
+    }
+}
+function toStuckApprovalInstanceRecord({ failure, instance }, lookup) {
+    const isResubmit = readStringPayloadValue(failure.payload, 'kind') === 'RESUBMIT';
+    const taskId = isResubmit ? null : failure.taskId;
+    const nodeId = isResubmit ? null : failure.nodeId;
+    const message = failure.payload['message'];
+    return {
+        automatic: failure.payload['automatic'] === SLA_AUTO_APPROVE_MARK
+            ? SLA_AUTO_APPROVE_MARK
+            : null,
+        failedActorMemberId: failure.actorMemberId,
+        failedAt: failure.createdAt,
+        initiatorMemberId: instance.initiatorMemberId,
+        instanceId: instance.id,
+        instanceTitle: instance.title,
+        kind: isResubmit
+            ? workflow_engine_enums_1.StuckApprovalInstanceKindEnum.RESUBMIT
+            : workflow_engine_enums_1.StuckApprovalInstanceKindEnum.DECISION,
+        message: typeof message === 'string' ? message : '',
+        nodeId,
+        nodeLabel: nodeId
+            ? readWorkflowNodeLabel(instance.workflowSnapshot, nodeId)
+            : null,
+        pendingActorMemberIds: taskId === null
+            ? [instance.initiatorMemberId]
+            : readTaskHolderMemberIds(lookup.tasks.find((task) => task.id === taskId) ?? null, lookup.candidates.filter((candidate) => candidate.taskId === taskId)),
+        taskId,
+        templateId: instance.templateId,
+        templateName: lookup.templateNameById.get(instance.templateId) ?? null,
+    };
+}
+/**
+ * The members who can press a task's button now: a PENDING or CLAIMED seat,
+ * each member once. A WAITING seat of a sequential task is not that member's
+ * turn yet. A task with no candidate row at all is a direct task, held by its
+ * assignee, as the reassignment check reads it.
+ */
+function readTaskHolderMemberIds(task, candidates) {
+    if (candidates.length === 0) {
+        return task?.assigneeMemberId ? [task.assigneeMemberId] : [];
+    }
+    return [
+        ...new Set(candidates
+            .filter((candidate) => candidate.status === workflow_engine_enums_1.TaskCandidateStatusEnum.PENDING ||
+            candidate.status === workflow_engine_enums_1.TaskCandidateStatusEnum.CLAIMED)
+            .map((candidate) => candidate.memberId)),
+    ];
+}
 function readStringPayloadValue(payload, key) {
     const value = payload[key];
     return typeof value === 'string' && value.trim() ? value.trim() : null;
@@ -6430,6 +7631,73 @@ function readInitiatorAndSubmitter(instance) {
 function isOrgManagerChainNode(node) {
     return node.data.approverResolver.type === 'ORG_MANAGER_CHAIN';
 }
+/**
+ * Whether a manager chain uses one of the two settings that need the context
+ * task creation works out first: it continues an earlier chain, or
+ * `skipWhenStartReached` is anything but absent, `null` or `false` (a value
+ * that is not a boolean is "used" too, so the shape check can refuse it
+ * instead of the chain being walked as if it were absent).
+ */
+function usesOrgManagerChainSettings(resolver) {
+    const skipWhenStartReached = resolver.skipWhenStartReached;
+    return ((0, workflow_1.isOrgManagerChainContinuation)(resolver) ||
+        (skipWhenStartReached !== undefined &&
+            skipWhenStartReached !== null &&
+            skipWhenStartReached !== false));
+}
+/**
+ * The manager-chain stage a continuing chain (`nodeId`, whose resolver is
+ * `resolver`) continues, or the first reason it cannot: it is missing, not a
+ * user task, not a manager chain, itself a continuation (stages are not
+ * chained more than once), started from something that can change while the
+ * stage's approvals stay (a form field, or a start this build does not know),
+ * or asks for a level at or below this chain's own, which would skip this
+ * chain every time. The same rules the publish lint applies to the stage;
+ * where the stage sits in the graph is only checked there.
+ */
+function readChainContinuationSource(workflow, nodeId, resolver) {
+    const sourceId = resolver.startFrom.nodeId;
+    const source = workflow.nodes.find((candidate) => candidate.id === sourceId);
+    const nameOf = (id) => `「${readWorkflowNodeLabel(workflow, id) ?? id}」`;
+    if (source === undefined) {
+        return { issue: `接續的前一段主管鏈「${sourceId}」不存在。` };
+    }
+    if (source.type !== 'userTask') {
+        return { issue: `接續的前一段主管鏈 ${nameOf(sourceId)} 不是簽核關卡。` };
+    }
+    const sourceResolver = source.data.approverResolver;
+    if (sourceResolver?.type !== 'ORG_MANAGER_CHAIN') {
+        return {
+            issue: `接續的前一段 ${nameOf(sourceId)} 的簽核來源不是「沿主管鏈簽核」。`,
+        };
+    }
+    if ((0, workflow_1.isOrgManagerChainContinuation)(sourceResolver)) {
+        return {
+            issue: `接續的前一段主管鏈 ${nameOf(sourceId)} 本身也是接續型主管鏈，不支援多段串接。`,
+        };
+    }
+    const sourceStart = sourceResolver.startFrom;
+    const sourceStartType = typeof sourceStart === 'object' && sourceStart !== null
+        ? sourceStart.type
+        : undefined;
+    if (sourceStart !== undefined &&
+        sourceStart !== null &&
+        sourceStartType !== 'INITIATOR' &&
+        sourceStartType !== 'NODE_ACTOR') {
+        return {
+            issue: `接續的前一段主管鏈 ${nameOf(sourceId)} 的起點只能是申請人或前面關卡的簽核者，不能是表單欄位或其他起點。`,
+        };
+    }
+    const sourceLevel = sourceResolver.minPositionLevel;
+    if (typeof sourceLevel === 'number' &&
+        Number.isInteger(sourceLevel) &&
+        resolver.minPositionLevel <= sourceLevel) {
+        return {
+            issue: `接續關卡 ${nameOf(nodeId)} 的職等門檻（${resolver.minPositionLevel}）必須高於前一段主管鏈 ${nameOf(sourceId)} 的職等門檻（${sourceLevel}）；否則前一段只要簽到自己的職等，這一關就一定被略過。`,
+        };
+    }
+    return { source: sourceResolver, sourceId };
+}
 // Candidates of a manager-chain node that came from the chain (or replaced the
 // excluded initiator's seat); ad-hoc approvers are chosen by a person instead.
 function isGradeGatedCandidate(node, sourceType) {
@@ -6843,9 +8111,7 @@ function readAdhocTargetValue(directive) {
         webhookHeaders: isRecord(value.webhookHeaders)
             ? Object.entries(value.webhookHeaders).reduce((accumulator, [key, headerValue]) => ({
                 ...accumulator,
-                ...(typeof headerValue === 'string'
-                    ? { [key]: headerValue }
-                    : {}),
+                ...(typeof headerValue === 'string' ? { [key]: headerValue } : {}),
             }), {})
             : undefined,
         webhookUrl: typeof value.webhookUrl === 'string' ? value.webhookUrl : '',
@@ -6961,10 +8227,7 @@ function compareManagerResolution(left, right, orgUnitDepths) {
     return right.effectiveFrom.localeCompare(left.effectiveFrom);
 }
 function readOrgUnitDepthMap(orgUnits) {
-    return new Map(orgUnits.map((orgUnit) => [
-        orgUnit.id,
-        orgUnit.path.split('.').length,
-    ]));
+    return new Map(orgUnits.map((orgUnit) => [orgUnit.id, orgUnit.path.split('.').length]));
 }
 function readManagerResolutionScopeRank(scopeType) {
     const ranks = {
@@ -7303,7 +8566,9 @@ function readTableMinRows(field) {
     return typeof field.minRows === 'number' ? field.minRows : 0;
 }
 function readTableMaxRows(field) {
-    return typeof field.maxRows === 'number' ? field.maxRows : form_1.FORM_TABLE_MAX_ROWS;
+    return typeof field.maxRows === 'number'
+        ? field.maxRows
+        : form_1.FORM_TABLE_MAX_ROWS;
 }
 function readTableRequiredRowCount(field) {
     return Math.max(readTableMinRows(field), 1);
@@ -7663,4 +8928,17 @@ function throwBusinessKeyConflictOrRethrow(error, businessKey) {
     }
     throw error;
 }
+/**
+ * The keys whose value differs between the stored form data and the data a
+ * resubmission replaces it with, sorted. A key present on only one side counts.
+ */
+function listChangedFormDataKeys(previous, next) {
+    const keys = new Set([...Object.keys(previous), ...Object.keys(next)]);
+    return [...keys]
+        .filter((fieldKey) => Object.prototype.hasOwnProperty.call(previous, fieldKey) !==
+        Object.prototype.hasOwnProperty.call(next, fieldKey) ||
+        (0, form_data_fingerprint_1.computeStableValueFingerprint)(previous[fieldKey]) !==
+            (0, form_data_fingerprint_1.computeStableValueFingerprint)(next[fieldKey]))
+        .sort();
+}
 //# sourceMappingURL=workflow-engine.service.js.map