@rytass/bpm-core-nestjs-module 0.20.1 → 0.21.1

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

@@ -13,11 +13,13 @@ const common_1 = require("@nestjs/common");
 const typeorm_1 = require("@nestjs/typeorm");
 const typeorm_2 = require("typeorm");
 const attachment_service_1 = require("../attachment/attachment.service");
+const file_upload_value_ids_1 = require("../attachment/file-upload-value-ids");
 const delegation_service_1 = require("../delegation/delegation.service");
 const form_definition_version_entity_1 = require("../form/form-definition-version.entity");
 const form_enums_1 = require("../form/form.enums");
 const form_data_source_errors_1 = require("../form-data-source/form-data-source.errors");
 const form_member_value_validator_1 = require("../form/form-member-value.validator");
+const form_data_issue_1 = require("../form/form-data-issue");
 const form_org_unit_value_validator_1 = require("../form/form-org-unit-value.validator");
 const form_data_source_types_1 = require("../form-data-source/form-data-source.types");
 const sla_schedule_service_1 = require("../calendar/sla-schedule.service");
@@ -39,6 +41,8 @@ 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");
 const approval_instance_entity_1 = require("./approval-instance.entity");
+const approval_instance_field_filter_compiler_1 = require("./approval-instance-field-filter.compiler");
+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_submitter_1 = require("./instance-submitter");
@@ -53,6 +57,7 @@ const time_budget_1 = require("./time-budget");
 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 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");
@@ -67,6 +72,15 @@ const APPROVAL_INSTANCE_BUSINESS_KEY_INDEX = 'approval_instances_business_key_ke
 const ORG_MANAGER_CHAIN_MAX_HOPS = 20;
 const DEFAULT_APPROVAL_HISTORY_TASK_LIMIT = 50;
 const SYSTEM_DRY_RUN_INSTANCE_ID = 'dry-run-instance';
+// How long a submission waits for the host's initiator `customFields`
+// resolver. The case is not created when it runs out (the snapshot never falls
+// back to `{}`), so this bounds how long a member stares at a spinner when the
+// host's lookup hangs; it is shorter than the 30 s webhook budget because a
+// person is waiting on this one.
+const INITIATOR_CUSTOM_FIELDS_RESOLVER_TIMEOUT_MS = 10_000;
+const INITIATOR_CUSTOM_FIELDS_TIMEOUT_MESSAGE = '無法取得發起人的自訂欄位（逾時），這次申請沒有送出；請稍後再試或聯絡系統管理者';
+const INITIATOR_CUSTOM_FIELDS_FAILED_MESSAGE = '無法取得發起人的自訂欄位，這次申請沒有送出；請稍後再試或聯絡系統管理者';
+const INITIATOR_CUSTOM_FIELDS_INVALID_MESSAGE = '無法取得發起人的自訂欄位（回傳格式不正確），這次申請沒有送出；請聯絡系統管理者';
 // The dry run checks each expression against the roots its use point may read,
 // as publish does. Keep these in step with `WORKFLOW_EXPRESSION_ROOT_IDENTIFIERS`
 // in template.service.ts; P2 moves both to one place.
@@ -119,6 +133,7 @@ const TASK_REASSIGNMENT_MESSAGES = {
     [workflow_engine_enums_1.TaskReassignmentErrorCodeEnum.TARGET_ALREADY_DECIDED]: '接手人已對此任務簽過核',
     [workflow_engine_enums_1.TaskReassignmentErrorCodeEnum.TARGET_ALREADY_ON_TASK]: '接手人已在此任務的待簽名單上',
     [workflow_engine_enums_1.TaskReassignmentErrorCodeEnum.TARGET_GRADE_TOO_LOW]: '接手人職等不足，不能取代此簽核位置',
+    [workflow_engine_enums_1.TaskReassignmentErrorCodeEnum.TARGET_IS_EXCLUDED_NODE_ACTOR]: '此節點不允許與前面關卡的簽核者為同一人，接手人不能是前面關卡的簽核者',
     [workflow_engine_enums_1.TaskReassignmentErrorCodeEnum.TARGET_IS_INITIATOR]: '此節點不允許申請人自簽，接手人不能是申請人',
     [workflow_engine_enums_1.TaskReassignmentErrorCodeEnum.TARGET_IS_SUBMITTER]: '此節點不允許代送人簽核，接手人不能是代為送出此單的人',
     [workflow_engine_enums_1.TaskReassignmentErrorCodeEnum.TARGET_SAME_AS_SOURCE]: '接手人與原簽核人相同',
@@ -174,7 +189,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) {
+    constructor(approvalInstanceRepository, workflowTokenRepository, taskRepository, taskCandidateRepository, taskDecisionRepository, notificationRepository, activityLogRepository, adhocDirectiveRepository, approvalTemplateRepository, approvalTemplateVersionRepository, formDefinitionVersionRepository, attachmentService, conditionService, delegationService, notificationService, signatureService, slaScheduleService, injectedServiceTaskDispatcher, formDataSourceValueResolver, rootOptions, webhookDeliveryService, injectedInitiatorCustomFieldsResolver) {
         this.approvalInstanceRepository = approvalInstanceRepository;
         this.workflowTokenRepository = workflowTokenRepository;
         this.taskRepository = taskRepository;
@@ -195,6 +210,8 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         this.formDataSourceValueResolver = formDataSourceValueResolver;
         this.webhookDeliveryService = webhookDeliveryService;
         this.logger = new common_1.Logger(WorkflowEngineService_1.name);
+        this.approvalInstanceFieldFilterCompiler = new approval_instance_field_filter_compiler_1.ApprovalInstanceFieldFilterCompiler();
+        this.approvalInstanceFilterableFieldPolicy = new approval_instance_filterable_field_policy_1.ApprovalInstanceFilterableFieldPolicy();
         /** Webhooks each open engine transaction will send once it has committed. */
         this.deferredWebhookDispatches = new WeakMap();
         // A binding under the token wins: that is either the host's own provider
@@ -205,12 +222,18 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         // keeps a host that binds the token from its own global module working —
         // a module-local default would shadow that binding, silently sending
         // WEBHOOK service tasks through the built-in `fetch` dispatcher instead of
-        // the host's signing or queueing one. It also reaches every copy of this
-        // service, which a provider registered on one module does not.
+        // the host's signing or queueing one.
         this.serviceTaskDispatcher =
             injectedServiceTaskDispatcher ??
                 rootOptions?.workflowServiceTaskDispatcher ??
                 new workflow_service_task_dispatcher_token_1.DefaultWorkflowServiceTaskDispatcher();
+        // Resolved like the dispatcher above, for the same reason: a binding the
+        // host made under the token wins, then the runtime instance, and with
+        // neither the snapshot's `customFields` stays `{}`.
+        this.initiatorCustomFieldsResolver =
+            injectedInitiatorCustomFieldsResolver ??
+                rootOptions?.initiatorCustomFieldsResolver ??
+                null;
         this.organizationTimeZone = (0, organization_time_zone_1.resolveBPMOrganizationTimeZone)(rootOptions?.organizationTimeZone);
     }
     /**
@@ -276,6 +299,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         }
     }
     async submitApprovalInstance(input, authContext) {
+        const submitAuthContext = authContext ?? createWorkflowAuthContext(input.initiatorMemberId);
         if (input.submittedByMemberId !== undefined &&
             input.submittedByMemberId !== null &&
             (typeof input.submittedByMemberId !== 'string' ||
@@ -308,15 +332,28 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         validateSubmittedFormData(formDefinitionVersion.schema, formData, {
             deferredFieldKeys,
         });
+        // 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
+        // (ADR 25 §15), which is what makes this schema the one in force.
+        assertFilterableFormDataValues(formDefinitionVersion.schema, formData);
         const formDataOptionSnapshot = await this.resolveFormDataOptionSnapshots({
-            authContext: authContext ?? createWorkflowAuthContext(input.initiatorMemberId),
+            authContext: submitAuthContext,
             formData,
             revalidateAll: true,
             schema: formDefinitionVersion.schema,
         });
         const initiatorMetadataSnapshot = input.initiatorMetadataSnapshotJson
             ? parseJsonObject(input.initiatorMetadataSnapshotJson, 'initiatorMetadataSnapshotJson')
-            : await this.readDefaultInitiatorMetadataSnapshot(input.initiatorMemberId);
+            : await this.buildInitiatorMetadataSnapshot({
+                authContext: submitAuthContext,
+                memberId: input.initiatorMemberId,
+                submission: {
+                    formData,
+                    templateId: template.id,
+                    templateVersionId: templateVersion.id,
+                },
+            });
         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))) {
@@ -334,6 +371,26 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             throw new common_1.BadRequestException('Published workflow does not include a startEvent');
         }
         return this.runEngineTransaction(async (manager) => {
+            // ADR 25 §6 and §15: take FOR SHARE on the template row, so a publish,
+            // deactivation or edit cannot commit between this point and the
+            // insert, then re-check under the lock what was read before it. The
+            // filterable check above used the version read then; it holds only
+            // while that version is still the current one.
+            const lockedTemplate = await manager
+                .getRepository(approval_template_entity_1.ApprovalTemplateEntity)
+                .findOne({
+                lock: { mode: 'pessimistic_read' },
+                where: { deletedAt: (0, typeorm_2.IsNull)(), id: template.id },
+            });
+            if (!lockedTemplate) {
+                throw new common_1.NotFoundException(`Approval template ${template.id} was not found`);
+            }
+            if (!lockedTemplate.isActive) {
+                throw new common_1.ConflictException('Approval template is deactivated');
+            }
+            if (lockedTemplate.currentVersionId !== templateVersion.id) {
+                throw new common_1.ConflictException('範本在送出期間發布了新版本，這次申請沒有送出；請重新整理頁面後再送出');
+            }
             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);
@@ -460,6 +517,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             ? (0, bpm_core_shared_1.overlayStoredFormDataKeys)(submittedFormData, instance.formData, deferredFieldKeys)
             : submittedFormData;
         validateSubmittedFormData(schema, formData, { deferredFieldKeys });
+        await this.assertCurrentFilterableFormDataValues(instance.templateId, formData);
         const formDataOptionSnapshot = await this.resolveFormDataOptionSnapshots({
             authContext,
             formData,
@@ -611,6 +669,15 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 transferToMemberId === (0, instance_submitter_1.readDistinctSubmitterMemberId)(instance)) {
                 throw new common_1.ConflictException(`簽核節點「${taskNode.data.label}」不允許代送人簽核，不能將任務轉交給代為送出此單的人`);
             }
+            // `excludeNodeActors`: the same carve-out, the same refusal. A human
+            // may not hand the seat to someone who signed one of the listed stages.
+            if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.TRANSFERRED &&
+                options.transferReason === undefined &&
+                isNodeActorsExcluded(taskNode) &&
+                transferToMemberId !== null &&
+                (await this.isExcludedNodeActorTarget(manager, instance, taskNode, transferToMemberId))) {
+                throw new common_1.ConflictException(`簽核節點「${taskNode.data.label}」不允許與前面關卡的簽核者為同一人，不能將任務轉交給前面${readNodeActorNodeNames(instance, readExcludedNodeActorNodeIds(taskNode))}的簽核者`);
+            }
             // Same carve-out: a human picking the target on a manager-chain node
             // must pick someone at least as senior as the member being replaced.
             if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.TRANSFERRED &&
@@ -634,7 +701,18 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.RETURNED &&
                 !decisionComment &&
                 isReturnCommentRequired(instance.workflowSnapshot, task.nodeId)) {
-                throw new common_1.BadRequestException(`Return decision comment is required by workflow node ${task.nodeId}`);
+                throw new common_1.BadRequestException('此節點要求退回時填寫意見，請輸入意見後再退回。');
+            }
+            // Same snapshot rule as the return check above. Only a person's
+            // approval is held to it: an engine-made approval (the SLA
+            // `AUTO_APPROVE` timeout) carries `options.automatic` and must never
+            // stall waiting for a comment nobody is there to write. A person's
+            // approval of an ad-hoc task counts too: it runs on the main node.
+            if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED &&
+                options.automatic === undefined &&
+                !decisionComment &&
+                taskNode.data.requireApprovalComment === true) {
+                throw new common_1.BadRequestException('此節點要求同意時填寫意見，請輸入意見後再同意。');
             }
             if (filledFormData !== null && task.isAdhoc) {
                 throw new common_1.ForbiddenException(`Ad-hoc task ${task.id} cannot fill in form fields`);
@@ -673,6 +751,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 }
             }
             if (filledFormData !== null && changedFieldKeys.length > 0) {
+                await this.assertCurrentFilterableFormDataValues(instance.templateId, mergedFormData, manager);
                 // 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
@@ -994,6 +1073,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             validateSubmittedFormData(resubmitSchema, formData, {
                 deferredFieldKeys,
             });
+            await this.assertCurrentFilterableFormDataValues(instance.templateId, formData, manager);
             if (!preparation) {
                 assertNoUnresolvableDynamicValues(resubmitSchema, formData);
             }
@@ -1056,7 +1136,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             // reached, against that node's own setting. This checks the target
             // against the node being decided now, as an early rejection for the
             // common case; it is not a guarantee about the node it attaches to.
-            if (isInitiatorExcluded(node)) {
+            if (hasSeatExclusion(node)) {
                 await this.resolveAdhocTaskCandidates(manager, instance, node, '臨時會簽', targetValue);
             }
             const directiveRepository = manager.getRepository(adhoc_directive_entity_1.AdhocDirectiveEntity);
@@ -1321,19 +1401,25 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         return task;
     }
     async resolveAdhocTaskCandidates(manager, instance, node, label, targetValue) {
-        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), `${label}「${node.data.label}」`, '簽核人', isInitiatorExcluded(node) ? readInitiatorAndSubmitter(instance) : []);
+        const exclusions = await this.readNodeExclusions(manager, instance, node);
+        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, buildAdhocApproverResolver(targetValue), `${label}「${node.data.label}」`, '簽核人', exclusions.memberIds);
         // 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);
-        const candidates = selectNodeCandidates(delegatedCandidates, isInitiatorExcluded(node), readInitiatorAndSubmitter(instance));
+        const candidates = selectNodeCandidates(delegatedCandidates, hasSeatExclusion(node), exclusions.memberIds);
         if (candidates.length > 0) {
             return candidates;
         }
-        throw new common_1.ConflictException(delegatedCandidates.length > 0
+        if (delegatedCandidates.length === 0) {
+            throw new common_1.ConflictException(`${label}「${node.data.label}」 did not resolve to any member id`);
+        }
+        // The initiator rule runs first: only when it alone left somebody is the
+        // earlier-stage rule the one that emptied the list.
+        throw new common_1.ConflictException(isEmptiedByInitiatorRule(node, delegatedCandidates, exclusions)
             ? (0, instance_submitter_1.readDistinctSubmitterMemberId)(instance) === null
                 ? `${label}「${node.data.label}」 無法建立任務：指定對象只有申請人本人，此節點不允許申請人簽核。`
                 : `${label}「${node.data.label}」 無法建立任務：指定對象只有申請人或代為送出此單的人，此節點不允許申請人或代送人簽核。`
-            : `${label}「${node.data.label}」 did not resolve to any member id`);
+            : `${label}「${node.data.label}」 無法建立任務：指定對象只有前面${readNodeActorNodeNames(instance, readExcludedNodeActorNodeIds(node))}的簽核者，此節點不允許與前面關卡的簽核者為同一人。`);
     }
     async spawnCountersignTasksForNode(manager, instance, token, node, now) {
         const directiveRepository = manager.getRepository(adhoc_directive_entity_1.AdhocDirectiveEntity);
@@ -1781,6 +1867,10 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         }
         const workflowDefinition = parseWorkflowDefinition(input.workflowDefinitionJson);
         const formData = parseJsonObject(input.formDataJson, 'formDataJson');
+        // 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
+        // host's `customFields` resolver, so that resolver is not called.
         const initiatorMetadataSnapshot = input.initiatorMetadataSnapshotJson
             ? parseJsonObject(input.initiatorMetadataSnapshotJson, 'initiatorMetadataSnapshotJson')
             : readDefaultInitiatorMetadataSnapshot(input.initiatorMemberId);
@@ -1979,6 +2069,18 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 outcome: 'STOPPED',
             };
         }
+        // Same for a manager chain whose start a newer engine wrote.
+        const unsupportedStartType = resolver.type === 'ORG_MANAGER_CHAIN' &&
+            !(0, workflow_1.isOrgManagerChainStartedFromInitiator)(resolver)
+            ? (0, workflow_1.readUnsupportedOrgManagerChainStartType)(resolver.startFrom)
+            : null;
+        if (unsupportedStartType !== null) {
+            return {
+                assigneeMemberId: null,
+                message: `簽核節點「${readDryRunNodeName(node)}」此引擎版本不支援主管鏈起點「${unsupportedStartType}」，請升級 BPMCore 後再試`,
+                outcome: 'STOPPED',
+            };
+        }
         const memberIds = this.readDryRunMemberIds(input, resolver, `workflow.nodes.${node.id}.data.approverResolver`);
         if (memberIds === null) {
             return {
@@ -2085,22 +2187,76 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         }
         return instance;
     }
+    /**
+     * 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
+     * template's *current* version marks filterable, not the instance's own
+     * snapshot: an older instance can be re-filled, resubmitted or written by a
+     * service task after a newer version enabled filtering on a field, and the
+     * enable check (ADR 25 §5.4) guarantees the type is the same in every version
+     * that holds instances, so the current definition judges the old value too.
+     */
+    async assertCurrentFilterableFormDataValues(templateId, formData, manager, serviceNodeLabel) {
+        const schema = await this.readCurrentFormSchema(templateId, manager);
+        assertFilterableFormDataValues(schema, formData, serviceNodeLabel);
+    }
+    /** The form schema of the template's current version, or `null` when there is none. */
+    async readCurrentFormSchema(templateId, manager) {
+        // Inside a write transaction the template row is taken FOR SHARE (ADR 25
+        // §15): a publish, compose or rollback needs FOR UPDATE on the same row, so
+        // the current version read here cannot change before the write commits.
+        const template = manager
+            ? await manager.getRepository(approval_template_entity_1.ApprovalTemplateEntity).findOne({
+                lock: { mode: 'pessimistic_read' },
+                where: { id: templateId },
+            })
+            : await this.approvalTemplateRepository.findOne({
+                where: { id: templateId },
+            });
+        if (!template?.currentVersionId) {
+            return null;
+        }
+        const versions = manager
+            ? manager.getRepository(approval_template_version_entity_1.ApprovalTemplateVersionEntity)
+            : this.approvalTemplateVersionRepository;
+        const version = await versions.findOne({
+            where: { id: template.currentVersionId },
+        });
+        if (!version?.formDefinitionVersionId) {
+            return null;
+        }
+        const formVersions = manager
+            ? manager.getRepository(form_definition_version_entity_1.FormDefinitionVersionEntity)
+            : this.formDefinitionVersionRepository;
+        const formVersion = await formVersions.findOne({
+            where: { id: version.formDefinitionVersionId },
+        });
+        return formVersion?.schema ?? null;
+    }
     async listApprovalInstances(scope, options = {}) {
-        const queryBuilder = await this.createFilteredApprovalInstanceQueryBuilder(scope, options);
-        if (!queryBuilder) {
+        const query = await this.createFilteredApprovalInstanceQuery(scope, options);
+        if (!query) {
             return [];
         }
-        queryBuilder.orderBy('"approvalInstance"."created_at"', 'DESC');
+        const { orderBy, queryBuilder } = query;
+        orderBy.forEach((order, index) => {
+            if (index === 0) {
+                queryBuilder.orderBy(order.sql, order.direction);
+            }
+            else {
+                queryBuilder.addOrderBy(order.sql, order.direction);
+            }
+        });
         if (shouldPaginateList(options)) {
             queryBuilder
-                .skip(readPageOffset(options.page, options.pageSize))
-                .take(normalizePageSize(options.pageSize));
+                .offset(readPageOffset(options.page, options.pageSize))
+                .limit(normalizePageSize(options.pageSize));
         }
         return queryBuilder.getMany();
     }
     async countApprovalInstances(scope, options = {}) {
-        const queryBuilder = await this.createFilteredApprovalInstanceQueryBuilder(scope, options);
-        return queryBuilder ? queryBuilder.getCount() : 0;
+        const query = await this.createFilteredApprovalInstanceQuery(scope, options);
+        return query ? query.queryBuilder.getCount() : 0;
     }
     async readApprovalInstancePageInfo(scope, options = {}) {
         const totalCount = await this.countApprovalInstances(scope, options);
@@ -2116,7 +2272,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             totalPages,
         };
     }
-    async createFilteredApprovalInstanceQueryBuilder(scope, options = {}) {
+    async createFilteredApprovalInstanceQuery(scope, options = {}) {
         const queryBuilder = this.approvalInstanceRepository.createQueryBuilder('approvalInstance');
         const hasReadableInstances = this.applyReadableInstanceFilter(queryBuilder, scope, options);
         if (!hasReadableInstances) {
@@ -2134,7 +2290,72 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             });
         }
         applyApprovalInstanceSearchFilter(queryBuilder, options.searchText);
-        return queryBuilder;
+        const compiled = await this.compileApprovalInstanceFieldQuery(scope, templateId, options);
+        compiled.conditions.forEach((condition) => {
+            queryBuilder.andWhere(condition.sql, condition.parameters);
+        });
+        queryBuilder.setParameters(compiled.orderBy.reduce((all, order) => ({ ...all, ...order.parameters }), {}));
+        return { orderBy: compiled.orderBy, queryBuilder };
+    }
+    /**
+     * The WHERE conditions and sort keys of the field filters and sort on the
+     * approval-instance list (ADR 25 §7). The template's current schema is read,
+     * and the static option lists of every version holding instances, only when
+     * a condition or a non-time sort key needs them.
+     */
+    async compileApprovalInstanceFieldQuery(scope, templateId, options) {
+        const fieldFilters = options.fieldFilters ?? [];
+        const sort = options.sort ?? [];
+        const needsSchema = fieldFilters.length > 0 ||
+            sort.some((item) => !(0, bpm_core_shared_1.isApprovalInstanceSortTimeField)(item.field));
+        if (needsSchema && !templateId) {
+            throw new common_1.BadRequestException('篩選或排序表單欄位時需要指定簽核範本');
+        }
+        const schema = needsSchema && templateId
+            ? await this.readCurrentFormSchema(templateId)
+            : null;
+        // Only a name search (CONTAINS) reads option names; other conditions and
+        // sort keys need the current schema alone.
+        const needsOptionNames = fieldFilters.some((filter) => filter.operator === 'CONTAINS');
+        const staticOptionsByPath = needsOptionNames && templateId
+            ? await this.readStaticOptionsByPathForTemplate(templateId, schema)
+            : (0, approval_instance_field_filter_compiler_1.readStaticOptionsByPath)([]);
+        return this.approvalInstanceFieldFilterCompiler.compile({
+            alias: 'approvalInstance',
+            fieldFilters,
+            paths: this.approvalInstanceFilterableFieldPolicy.readFilterableFieldPaths(scope, schema),
+            sort,
+            staticOptionsByPath,
+        });
+    }
+    /**
+     * Static option lists by field path, across the current schema and the form
+     * version of every template version that holds instances (ADR 25 §7.3): a
+     * CONTAINS on a retired option still matches its name.
+     */
+    async readStaticOptionsByPathForTemplate(templateId, currentSchema) {
+        const held = await this.approvalInstanceRepository
+            .createQueryBuilder('approvalInstance')
+            .select('DISTINCT "approvalInstance"."template_version_id"', 'id')
+            .where('"approvalInstance"."template_id" = :templateId', { templateId })
+            .getRawMany();
+        const templateVersions = held.length === 0
+            ? []
+            : await this.approvalTemplateVersionRepository.find({
+                where: { id: (0, typeorm_2.In)(held.map((row) => row.id)) },
+            });
+        const formVersionIds = templateVersions
+            .map((version) => version.formDefinitionVersionId)
+            .filter((id) => id !== null);
+        const formVersions = formVersionIds.length === 0
+            ? []
+            : await this.formDefinitionVersionRepository.find({
+                where: { id: (0, typeorm_2.In)(formVersionIds) },
+            });
+        return (0, approval_instance_field_filter_compiler_1.readStaticOptionsByPath)([
+            currentSchema,
+            ...formVersions.map((version) => version.schema),
+        ]);
     }
     applyReadableInstanceFilter(queryBuilder, scope, options) {
         if (!scope) {
@@ -2242,7 +2463,12 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             },
         });
     }
-    async listLaunchableApprovalTemplates(memberId) {
+    /**
+     * The active templates `memberId` may start now. `authContext` is handed to
+     * the host's initiator `customFields` resolver; a host calling this without
+     * one gets a bare context for the member, as a submission does.
+     */
+    async listLaunchableApprovalTemplates(memberId, authContext) {
         const templates = await this.approvalTemplateRepository.find({
             order: { updatedAt: 'DESC' },
             where: { isActive: true },
@@ -2263,7 +2489,17 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             version.id,
             version,
         ]));
-        const initiatorMetadataSnapshot = await this.readDefaultInitiatorMetadataSnapshot(memberId);
+        // Built like a submission's, so a policy that reads
+        // `initiator.customFields` is judged here against what the host's resolver
+        // returns for this member. The resolver depends on the initiator only, so
+        // it is called once for the whole list, not once per template. When it
+        // fails, the list is judged against `customFields: {}` instead of failing
+        // (see `buildInitiatorMetadataSnapshot`).
+        const initiatorMetadataSnapshot = await this.buildInitiatorMetadataSnapshot({
+            authContext: authContext ?? createWorkflowAuthContext(memberId),
+            memberId,
+            submission: null,
+        });
         return templates.filter((template) => {
             const currentVersion = template.currentVersionId
                 ? (versionById.get(template.currentVersionId) ?? null)
@@ -2281,8 +2517,19 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 return false;
             }
             // Each template is its own operation, so one slow template cannot use
-            // up the allowance of the rest of the list.
-            return (0, expression_budget_1.runExpressionOperation)(() => this.conditionService.evaluateBoolean(currentVersion.initiatorPolicyCel, buildInitiatorPolicyContext(initiatorMetadataSnapshot), 'initiatorPolicyCel', readExpressionDialectOptions(currentVersion.initiatorPolicyCel, currentVersion.workflowDefinition)));
+            // up the allowance of the rest of the list. A policy that throws (for
+            // example a missing `initiator.customFields.*` key, because the resolver
+            // did not return it, or failed and the list fell back to `{}`) is also
+            // only that template's problem: it is left out, and the error code is
+            // logged, never the values.
+            try {
+                return (0, expression_budget_1.runExpressionOperation)(() => this.conditionService.evaluateBoolean(currentVersion.initiatorPolicyCel, buildInitiatorPolicyContext(initiatorMetadataSnapshot), 'initiatorPolicyCel', readExpressionDialectOptions(currentVersion.initiatorPolicyCel, currentVersion.workflowDefinition)));
+            }
+            catch (error) {
+                const reason = error instanceof expression_errors_1.ExpressionRuntimeError ? error.code : 'UNEXPECTED';
+                this.logger.warn(`template=${template.id} version=${currentVersion.id} left out of launchable templates: initiatorPolicyCel failed (${reason})`);
+                return false;
+            }
         });
     }
     async listWorkflowTokens(instanceId, scope) {
@@ -2523,6 +2770,112 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             primaryOrgUnitId: primaryMembership?.orgUnitId ?? null,
         };
     }
+    /**
+     * The initiator snapshot the engine builds itself: what it knows of the
+     * initiator, with `customFields` filled by the host's resolver when there is
+     * one. Without a resolver this is exactly the default snapshot
+     * (`customFields` is `{}`). A submission (`submission` set) stores it and
+     * judges the initiator policy with it; the launchable template list
+     * (`submission: null`) only judges the policies with it, so both see the same
+     * `customFields` for the same member.
+     *
+     * Only `customFields` comes from the host. The other keys are the engine's
+     * and are written back after the resolver returns, so nothing it does can
+     * change who the initiator is. The resolver gets copies of the snapshot and
+     * of the form data for the same reason; `authContext` is the caller's own
+     * object, as every other host hook receives it.
+     *
+     * The two callers treat a resolver failure (an error, a bad value, the
+     * timeout) differently, on purpose:
+     *
+     * - A submission fails, and no case is created. Its snapshot is stored and
+     *   routes the case from then on, so carrying on with `{}` would start a
+     *   case on data the host never gave. It runs before the engine
+     *   transaction, so a failure leaves nothing behind and a slow lookup holds
+     *   no lock.
+     * - The list carries on with `customFields: {}` and logs a warning: one
+     *   failing lookup must not take the whole list away. That fails closed: a
+     *   policy that reads `initiator.customFields` then throws on the missing key
+     *   and the list's per-template catch leaves that template out, while a
+     *   template whose policy does not read it is listed as usual. Submitting is
+     *   still judged against the resolver's real answer.
+     */
+    async buildInitiatorMetadataSnapshot({ authContext, memberId, submission, }) {
+        const defaultSnapshot = await this.readDefaultInitiatorMetadataSnapshot(memberId);
+        if (!this.initiatorCustomFieldsResolver) {
+            return defaultSnapshot;
+        }
+        const input = {
+            authContext,
+            defaultSnapshot: cloneJsonObject(defaultSnapshot),
+            formData: submission ? cloneJsonObject(submission.formData) : null,
+            memberId,
+            purpose: submission ? 'SUBMISSION' : 'LAUNCHABLE_TEMPLATES',
+            templateId: submission?.templateId ?? null,
+            templateVersionId: submission?.templateVersionId ?? null,
+        };
+        if (submission) {
+            return {
+                ...defaultSnapshot,
+                customFields: await this.resolveInitiatorCustomFields(this.initiatorCustomFieldsResolver, input),
+            };
+        }
+        try {
+            return {
+                ...defaultSnapshot,
+                customFields: await this.resolveInitiatorCustomFields(this.initiatorCustomFieldsResolver, input),
+            };
+        }
+        catch (error) {
+            this.logger.warn(`Launchable templates judged with customFields {}: the initiator customFields resolver failed (${error instanceof common_1.HttpException ? error.getStatus() : 'UNEXPECTED'})`);
+            return defaultSnapshot;
+        }
+    }
+    /**
+     * Calls the host's initiator `customFields` resolver within
+     * {@link INITIATOR_CUSTOM_FIELDS_RESOLVER_TIMEOUT_MS} and returns what it
+     * gave as the object the snapshot keeps.
+     *
+     * Every failure becomes an `InternalServerErrorException` with a message
+     * meant for the member, and the cause goes to the log only, so nothing of
+     * the host's lookup reaches the client: running out of time, an error that
+     * is not an `HttpException`, and a value that is not a plain JSON object. An
+     * `HttpException` the resolver throws is passed on as it is, because the
+     * host chose that answer for the member.
+     *
+     * A resolver that settles after the time has run out is not waited for; what
+     * it settles with is logged and dropped, so a late rejection is never left
+     * unhandled.
+     */
+    async resolveInitiatorCustomFields(resolver, input) {
+        const subject = input.purpose === 'SUBMISSION'
+            ? `template=${input.templateId} version=${input.templateVersionId}`
+            : 'launchable templates';
+        const outcome = await settleWithin(new Promise((resolve) => {
+            resolve(resolver.resolveCustomFields(input));
+        }), INITIATOR_CUSTOM_FIELDS_RESOLVER_TIMEOUT_MS, (late) => {
+            this.logger.warn(`Initiator customFields resolver settled after the ${INITIATOR_CUSTOM_FIELDS_RESOLVER_TIMEOUT_MS} ms timeout (${subject}); ${late.status === 'fulfilled'
+                ? 'its value was dropped'
+                : `its error was dropped: ${describeRejection(late.reason)}`}`);
+        });
+        if (outcome.status === 'timeout') {
+            this.logger.error(`Initiator customFields resolver timed out after ${INITIATOR_CUSTOM_FIELDS_RESOLVER_TIMEOUT_MS} ms (${subject})`);
+            throw new common_1.InternalServerErrorException(INITIATOR_CUSTOM_FIELDS_TIMEOUT_MESSAGE);
+        }
+        if (outcome.status === 'rejected') {
+            if (outcome.reason instanceof common_1.HttpException) {
+                throw outcome.reason;
+            }
+            this.logger.error(`Initiator customFields resolver failed (${subject}): ${describeRejection(outcome.reason)}`, outcome.reason instanceof Error ? outcome.reason.stack : undefined);
+            throw new common_1.InternalServerErrorException(INITIATOR_CUSTOM_FIELDS_FAILED_MESSAGE);
+        }
+        const customFields = readResolvedInitiatorCustomFields(outcome.value);
+        if (!customFields.ok) {
+            this.logger.error(`Initiator customFields resolver returned an unusable value (${subject}): ${customFields.problem}`);
+            throw new common_1.InternalServerErrorException(INITIATOR_CUSTOM_FIELDS_INVALID_MESSAGE);
+        }
+        return customFields.value;
+    }
     async listActivityLogs(instanceId, scope) {
         await this.getApprovalInstance(instanceId, scope);
         return this.activityLogRepository.find({
@@ -2743,10 +3096,10 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             skippedByEntryCondition: true,
         });
     }
-    async skipNodeByInitiatorExclusion(manager, instance, token, node) {
-        await this.skipNode(manager, instance, token, node, {
-            skippedByInitiatorExclusion: true,
-        });
+    async skipNodeByInitiatorExclusion(manager, instance, token, node, skippedBy = 'INITIATOR') {
+        await this.skipNode(manager, instance, token, node, skippedBy === 'NODE_ACTORS'
+            ? { skippedByNodeActorExclusion: true }
+            : { skippedByInitiatorExclusion: true });
     }
     async skipNode(manager, instance, token, node, reason) {
         // A NOTIFY node is an asynchronous branch that may not have an outgoing
@@ -2975,11 +3328,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             return;
         }
         const resolvedCandidates = await this.resolveRuntimeTaskCandidates(manager, instance, node);
-        // The initiator was the only approver and the node asks to be skipped in
-        // that case: no task, the token moves on. Pending countersign directives
-        // stay pending for the next user task that actually gets created.
-        if (resolvedCandidates === null) {
-            await this.skipNodeByInitiatorExclusion(manager, instance, token, node);
+        // Everyone left was kept out and the node asks to be skipped in that case:
+        // no task, the token moves on. Pending countersign directives stay
+        // pending for the next user task that actually gets created.
+        if ('skippedBy' in resolvedCandidates) {
+            await this.skipNodeByInitiatorExclusion(manager, instance, token, node, resolvedCandidates.skippedBy);
             return;
         }
         const { candidates, skippedDelegations } = resolvedCandidates;
@@ -3002,7 +3355,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 : workflow_engine_enums_1.TaskAssignmentTypeEnum.CANDIDATE_GROUP,
             completedAt: null,
             createdAt: now,
-            decisionPolicySnapshot: isInitiatorExcluded(node)
+            decisionPolicySnapshot: hasSeatExclusion(node)
                 ? capDecisionPolicyToCandidateCount(decisionPolicy, candidates.length)
                 : decisionPolicy,
             delegationChain: assignedCandidate?.delegationChain ?? [],
@@ -3100,7 +3453,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         const { skippedDelegation, ...delegation } = await this.resolveActivationDelegation({
             candidate: nextCandidate,
             candidates,
-            excludesInitiator: isInitiatorExcluded(node),
+            excludedMemberIds: (await this.readNodeExclusions(manager, instance, node)).memberIds,
             gradeGated: isGradeGatedCandidate(node, nextCandidate.sourceType),
             instance,
             manager,
@@ -3161,12 +3514,13 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      * Re-resolves the delegation of a candidate whose turn has come. When the
      * delegate already holds another candidate row on the task, the stored values
      * are kept: (task_id, member_id) is unique, and that member signs from the
-     * row they already have. On a node that excludes the initiator the stored
-     * values are kept as well when the new delegation path would run through the
-     * initiator or the submitter: creation already filtered such paths out, and a
-     * delegation added while the candidate waited must not bring them back.
+     * row they already have. On a node that keeps members out (the initiator and
+     * submitter, or the approvers of earlier stages) the stored values are kept
+     * as well when the new delegation path would run through one of them:
+     * creation already filtered such paths out, and a delegation added while the
+     * candidate waited must not bring them back.
      */
-    async resolveActivationDelegation({ candidate, candidates, excludesInitiator, gradeGated, instance, manager, nodeId, }) {
+    async resolveActivationDelegation({ candidate, candidates, excludedMemberIds, gradeGated, instance, manager, nodeId, }) {
         const stored = {
             delegationChain: candidate.delegationChain,
             memberId: candidate.memberId,
@@ -3175,12 +3529,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         const collides = candidates.some((other) => other.id !== candidate.id &&
             other.memberId === resolution.finalAssigneeMemberId);
         if (collides ||
-            (excludesInitiator &&
-                isExcludedMemberOnCandidatePath({
-                    delegationChain: resolution.delegationChain,
-                    memberId: resolution.finalAssigneeMemberId,
-                    originalMemberId: candidate.originalMemberId,
-                }, readInitiatorAndSubmitter(instance)))) {
+            isExcludedMemberOnCandidatePath({
+                delegationChain: resolution.delegationChain,
+                memberId: resolution.finalAssigneeMemberId,
+                originalMemberId: candidate.originalMemberId,
+            }, excludedMemberIds)) {
             // The refusal happened even though the stored values are kept.
             return { ...stored, ...(skippedDelegation ? { skippedDelegation } : {}) };
         }
@@ -3730,6 +4083,10 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 throw new TaskReassignmentRejectedError(workflow_engine_enums_1.TaskReassignmentErrorCodeEnum.TARGET_IS_SUBMITTER);
             }
         }
+        if (isNodeActorsExcluded(node) &&
+            (await this.isExcludedNodeActorTarget(manager, instance, node, toMemberId))) {
+            throw new TaskReassignmentRejectedError(workflow_engine_enums_1.TaskReassignmentErrorCodeEnum.TARGET_IS_EXCLUDED_NODE_ACTOR);
+        }
         if (!task.isAdhoc && isOrgManagerChainNode(node)) {
             const requiredGrade = await this.readTransferTargetRequiredGrade(manager, {
                 actorMemberId: fromMemberId,
@@ -3942,58 +4299,178 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         });
     }
     /**
-     * Resolves who gets the node's task. `null` means the node asked to be
-     * skipped (`excludeInitiator.whenEmpty = SKIP_NODE`) because the initiator
-     * was the only approver — the sole caller creates no task and advances the
-     * token instead.
+     * 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.
+     *
+     * With both exclusions set the initiator rule runs first. When it alone
+     * leaves nobody, `excludeInitiator.whenEmpty` decides; when it leaves
+     * somebody and the earlier-stage rule then removes them all,
+     * `excludeNodeActors.whenEmpty` decides.
      */
     async resolveRuntimeTaskCandidates(manager, instance, node) {
         const label = `簽核節點「${node.data.label}」`;
-        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, node.data.approverResolver, label, '簽核人', isInitiatorExcluded(node) ? readInitiatorAndSubmitter(instance) : []);
+        const exclusions = await this.readNodeExclusions(manager, instance, node);
+        const resolvedCandidates = await this.resolveApproverResolver(manager, instance, node.data.approverResolver, label, '簽核人', exclusions.memberIds);
         const delegatedCandidates = await this.delegateResolvedCandidates(manager, instance, node.id, resolvedCandidates, isOrgManagerChainNode(node));
-        const excludeInitiator = node.data.excludeInitiator;
+        const hasExclusion = hasSeatExclusion(node);
         const hasSubmitter = (0, instance_submitter_1.readDistinctSubmitterMemberId)(instance) !== null;
-        const uniqueCandidates = selectNodeCandidates(delegatedCandidates, isInitiatorExcluded(node), readInitiatorAndSubmitter(instance));
+        const uniqueCandidates = selectNodeCandidates(delegatedCandidates, hasExclusion, exclusions.memberIds);
         if (uniqueCandidates.length > 0) {
             return {
                 candidates: uniqueCandidates,
-                skippedDelegations: collectSkippedDelegations(delegatedCandidates, isInitiatorExcluded(node), readInitiatorAndSubmitter(instance)),
+                skippedDelegations: collectSkippedDelegations(delegatedCandidates, hasExclusion, exclusions.memberIds),
             };
         }
-        // Only the initiator was left — what the node does about it is configured.
-        // Nothing resolved to begin with is the ordinary failure below.
-        if (!excludeInitiator || delegatedCandidates.length === 0) {
+        // Only excluded people were left — what the node does about it is
+        // configured. Nothing resolved to begin with is the ordinary failure below.
+        if (!hasExclusion || delegatedCandidates.length === 0) {
             throw new common_1.ConflictException(`${label} did not resolve to any member id`);
         }
-        if (excludeInitiator.whenEmpty === 'SKIP_NODE') {
-            return null;
+        const emptiedByInitiator = isEmptiedByInitiatorRule(node, delegatedCandidates, exclusions);
+        const whenEmpty = emptiedByInitiator
+            ? node.data.excludeInitiator?.whenEmpty
+            : node.data.excludeNodeActors?.whenEmpty;
+        if (whenEmpty === 'SKIP_NODE') {
+            return { skippedBy: emptiedByInitiator ? 'INITIATOR' : 'NODE_ACTORS' };
         }
-        if (excludeInitiator.whenEmpty === 'INITIATOR_MANAGER') {
-            const managerCandidates = await this.resolveInitiatorManagerReplacements(manager, instance, node);
+        if (whenEmpty === 'INITIATOR_MANAGER') {
+            const managerCandidates = await this.resolveInitiatorManagerReplacements(manager, instance, node, exclusions.memberIds);
             if (managerCandidates.candidates.length > 0) {
                 return managerCandidates;
             }
-            throw new common_1.ConflictException(hasSubmitter
-                ? `${label} 無法建立待簽任務：解析出的簽核人只剩申請人或代為送出此單的人，此節點不允許申請人或代送人簽核，且找不到申請人的主管可改派。`
-                : `${label} 無法建立待簽任務：解析出的簽核人只剩申請人本人，此節點不允許申請人自簽，且找不到申請人的主管可改派。`);
+            throw new common_1.ConflictException(!emptiedByInitiator
+                ? `${label} 無法建立待簽任務：解析出的簽核人只剩前面${readNodeActorNodeNames(instance, readExcludedNodeActorNodeIds(node))}的簽核者，此節點不允許與前面關卡的簽核者為同一人，且找不到申請人的主管可改派。`
+                : hasSubmitter
+                    ? `${label} 無法建立待簽任務：解析出的簽核人只剩申請人或代為送出此單的人，此節點不允許申請人或代送人簽核，且找不到申請人的主管可改派。`
+                    : `${label} 無法建立待簽任務：解析出的簽核人只剩申請人本人，此節點不允許申請人自簽，且找不到申請人的主管可改派。`);
+        }
+        throw new common_1.ConflictException(!emptiedByInitiator
+            ? `${label} 無法建立待簽任務：解析出的簽核人只剩前面${readNodeActorNodeNames(instance, readExcludedNodeActorNodeIds(node))}的簽核者（含委派後的代理人），此節點不允許與前面關卡的簽核者為同一人。`
+            : hasSubmitter
+                ? `${label} 無法建立待簽任務：解析出的簽核人只剩申請人或代為送出此單的人（含委派後的代理人），且此節點不允許申請人或代送人簽核。`
+                : `${label} 無法建立待簽任務：解析出的簽核人只剩申請人本人（含委派後的代理人），且此節點不允許申請人自簽。`);
+    }
+    /**
+     * Everyone `node` keeps out of its approvers, per rule: the initiator and
+     * the submitter for `excludeInitiator`, and everyone who actually approved
+     * one of the listed earlier stages for `excludeNodeActors`. Read through
+     * `manager` so an approval written earlier in this transaction counts.
+     */
+    async readNodeExclusions(manager, instance, node) {
+        const initiatorMemberIds = isInitiatorExcluded(node)
+            ? readInitiatorAndSubmitter(instance)
+            : [];
+        const nodeActorMemberIds = isNodeActorsExcluded(node)
+            ? await this.readExcludedNodeActorMemberIds(manager, instance, readExcludedNodeActorNodeIds(node))
+            : [];
+        return {
+            initiatorMemberIds,
+            memberIds: uniqueTexts([...initiatorMemberIds, ...nodeActorMemberIds]),
+            nodeActorMemberIds,
+        };
+    }
+    /**
+     * The people who approved any of `nodeIds`, each listed node read on its own
+     * with the `NODE_ACTOR` rules ({@link readNodeActorMemberIds}) and the
+     * results combined. A source reads only the most recent of its listed nodes;
+     * an exclusion must cover every listed node, so it asks one node at a time.
+     *
+     * There is no round boundary here: a node's newest batch is what counts. The
+     * publish lint makes that the right batch, since every listed node runs and
+     * is signed by a person on every path to this node (a return to the start
+     * runs it again; a return to a stage below it leaves its earlier approval
+     * standing, and the exclusion with it).
+     */
+    async readExcludedNodeActorMemberIds(manager, instance, nodeIds) {
+        const groups = await Promise.all(nodeIds.map(async (nodeId) => {
+            const approvals = await this.readNodeActorApprovals(manager, instance, [
+                nodeId,
+            ]);
+            const principalMemberIds = await this.readApprovalPrincipalMemberIds(manager, approvals);
+            return [
+                ...approvals.map((decision) => decision.decidedByMemberId),
+                ...principalMemberIds,
+            ];
+        }));
+        return uniqueTexts(groups.flat());
+    }
+    /**
+     * Whether `targetMemberId` may not take a seat on `node` under
+     * `excludeNodeActors`, checked the way task creation checks a candidate: the
+     * target is one of the excluded members, or one end of a delegation between
+     * the target and an excluded member is on the path. A delegation is read in
+     * both directions, since the target may be the delegate of an excluded
+     * member, or delegate an excluded member's seat onward.
+     */
+    async isExcludedNodeActorTarget(manager, instance, node, targetMemberId) {
+        const excludedMemberIds = await this.readExcludedNodeActorMemberIds(manager, instance, readExcludedNodeActorNodeIds(node));
+        if (excludedMemberIds.includes(targetMemberId)) {
+            return true;
         }
-        throw new common_1.ConflictException(hasSubmitter
-            ? `${label} 無法建立待簽任務：解析出的簽核人只剩申請人或代為送出此單的人（含委派後的代理人），且此節點不允許申請人或代送人簽核。`
-            : `${label} 無法建立待簽任務：解析出的簽核人只剩申請人本人（含委派後的代理人），且此節點不允許申請人自簽。`);
+        if (excludedMemberIds.length === 0) {
+            return false;
+        }
+        const context = this.buildDelegationContext(instance, node.id);
+        const gradeGated = isOrgManagerChainNode(node);
+        const ownDelegation = await this.resolveDelegation(manager, targetMemberId, context, gradeGated);
+        if (isExcludedMemberOnCandidatePath({
+            delegationChain: ownDelegation.delegationChain,
+            memberId: ownDelegation.finalAssigneeMemberId,
+            originalMemberId: targetMemberId,
+        }, excludedMemberIds)) {
+            return true;
+        }
+        const excludedSeats = await Promise.all(excludedMemberIds.map(async (memberId) => {
+            const delegation = await this.resolveDelegation(manager, memberId, context, gradeGated);
+            return isExcludedMemberOnCandidatePath({
+                delegationChain: delegation.delegationChain,
+                memberId: delegation.finalAssigneeMemberId,
+                originalMemberId: memberId,
+            }, [targetMemberId]);
+        }));
+        return excludedSeats.some((routesToTarget) => routesToTarget);
     }
-    async resolveInitiatorManagerReplacements(manager, instance, node) {
+    /**
+     * The principals the approvals stand for: a delegate who approved counts as
+     * the member who delegated to them, read from the candidate row each approval
+     * was signed on (see {@link readRuleDelegatorMemberIds}).
+     */
+    async readApprovalPrincipalMemberIds(manager, approvals) {
+        if (approvals.length === 0) {
+            return [];
+        }
+        const candidates = await manager.getRepository(task_candidate_entity_1.TaskCandidateEntity).find({
+            where: {
+                taskId: (0, typeorm_2.In)(uniqueTexts(approvals.map((decision) => decision.taskId))),
+            },
+        });
+        return uniqueTexts(approvals.flatMap((decision) => candidates
+            .filter((candidate) => candidate.taskId === decision.taskId &&
+            candidate.memberId === decision.decidedByMemberId)
+            .flatMap(readRuleDelegatorMemberIds)));
+    }
+    async resolveInitiatorManagerReplacements(manager, instance, node, excludedMemberIds) {
+        // Whoever the node keeps out is also kept out of the replacements: the
+        // initiator and the submitter always (even when only `excludeNodeActors`
+        // asked for this replacement), plus the earlier-stage approvers.
+        const replacementExcludedMemberIds = uniqueTexts([
+            ...readInitiatorAndSubmitter(instance),
+            ...excludedMemberIds,
+        ]);
         // The initiator's own direct manager: the closest org unit only. The
         // initiator himself (a unit head) and the member who submitted for him are
         // skipped before the tier is chosen, so resolution falls through to the
         // next tier instead of ending on either of them.
-        const managerMemberIds = await this.resolveDirectManagerMemberIds(manager, instance.initiatorMemberId, this.readOrganizationToday(), true, readInitiatorAndSubmitter(instance));
+        const managerMemberIds = await this.resolveDirectManagerMemberIds(manager, instance.initiatorMemberId, this.readOrganizationToday(), true, replacementExcludedMemberIds);
         const delegatedCandidates = await this.delegateResolvedCandidates(manager, instance, node.id, managerMemberIds.map((memberId) => ({
             memberId,
             sourceType: 'EXCLUDE_INITIATOR_MANAGER',
         })), isOrgManagerChainNode(node));
         return {
-            candidates: selectNodeCandidates(delegatedCandidates, true, readInitiatorAndSubmitter(instance)),
-            skippedDelegations: collectSkippedDelegations(delegatedCandidates, true, readInitiatorAndSubmitter(instance)),
+            candidates: selectNodeCandidates(delegatedCandidates, true, replacementExcludedMemberIds),
+            skippedDelegations: collectSkippedDelegations(delegatedCandidates, true, replacementExcludedMemberIds),
         };
     }
     buildDelegationContext(instance, nodeId) {
@@ -4107,7 +4584,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.minPositionLevel, resolver.fallback, label, subject, skippedChainMemberIds);
+            return this.resolveOrgManagerChainCandidates(manager, instance, resolver, label, subject, skippedChainMemberIds);
         }
         if (resolver.type === 'ORG_MANAGER') {
             return this.resolveInitiatorManagerCandidates(manager, instance, resolver.levelsUp, resolver.fallback, label, resolver.preferClosestOrgUnit === true, subject);
@@ -4212,6 +4689,15 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      * tasks and approvals the SLA timeout made do not count.
      */
     async readNodeActorMemberIds(manager, instance, nodeIds) {
+        const approvals = await this.readNodeActorApprovals(manager, instance, nodeIds);
+        return uniqueTexts(approvals.map((decision) => decision.decidedByMemberId));
+    }
+    /**
+     * The real approvals (earliest first) of the most recent batch among
+     * `nodeIds`: the rows {@link readNodeActorMemberIds} reads the approvers from.
+     * Kept as decisions so the exclusion can also reach each decision's task.
+     */
+    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]) },
         });
@@ -4242,10 +4728,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         const automaticDecisionIds = new Set(decidedLogs
             .filter((log) => log.payload['automatic'] === SLA_AUTO_APPROVE_MARK)
             .map((log) => log.payload['decisionId']));
-        return uniqueTexts([...decisions]
+        return [...decisions]
             .filter((decision) => !automaticDecisionIds.has(decision.id))
-            .sort((first, second) => first.decidedAt.getTime() - second.decidedAt.getTime())
-            .map((decision) => decision.decidedByMemberId));
+            .sort((first, second) => first.decidedAt.getTime() - second.decidedAt.getTime());
     }
     async resolvePositionCandidates(manager, positionId, label, subject) {
         const memberIds = await this.readActivePositionMemberIds(manager, positionId);
@@ -4284,16 +4769,28 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         return this.resolveFallbackAssignees(manager, instance, fallback, label, subject, `找不到發起人的第 ${normalizedLevelsUp} 層主管`);
     }
     /**
-     * Walks up the initiator's manager chain, nearest manager first, until a
-     * manager whose position level reaches `minPositionLevel` is added. The
-     * list is returned nearest manager first. Members in `skippedMemberIds` are
-     * walked past without joining the chain or counting as the stopping point.
+     * Walks up a manager chain, nearest manager first, until a manager whose
+     * position level reaches `minPositionLevel` is added. The chain starts at
+     * the initiator unless `startFrom` names someone else, and the start person
+     * is never on it: the walk begins at their direct manager. The list is
+     * returned nearest manager first. Members in `skippedMemberIds` are walked
+     * 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.
      */
-    async resolveOrgManagerChainCandidates(manager, instance, minPositionLevel, fallback, label, subject, skippedMemberIds) {
+    async resolveOrgManagerChainCandidates(manager, instance, resolver, label, subject, skippedMemberIds) {
+        const { fallback, minPositionLevel } = resolver;
+        const startPositionLevel = (0, workflow_1.readOrgManagerChainStartPositionLevel)(resolver);
+        const 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) {
+            return this.resolveFallbackAssignees(manager, instance, fallback, label, subject, start.missingReason);
+        }
         const date = this.readOrganizationToday();
-        const visitedMemberIds = new Set([instance.initiatorMemberId]);
+        const visitedMemberIds = new Set([start.memberId]);
         const chain = [];
-        let currentMemberId = instance.initiatorMemberId;
+        let currentMemberId = start.memberId;
         let lastAddedLevel = 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
@@ -4326,6 +4823,13 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 (lastAddedLevel !== null && level <= lastAddedLevel)) {
                 continue;
             }
+            // Below the start level a manager is walked past like one without a
+            // position: he neither joins the chain nor raises the bar the next
+            // manager has to clear. Every manager added after the first is above
+            // the last one added, so this only ever holds before the chain starts.
+            if (startPositionLevel !== null && level < startPositionLevel) {
+                continue;
+            }
             chain.push(managerMemberId);
             lastAddedLevel = level;
             if (level >= minPositionLevel) {
@@ -4334,9 +4838,68 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         }
         // A position fallback can name several holders. They all join the last
         // tier, so they all have to sign, the same as every other chain member.
-        const fallbackMemberIds = await this.resolveFallbackAssignees(manager, instance, fallback, label, subject, `沿主管鏈找不到職等達 ${minPositionLevel} 的主管`);
+        const fallbackMemberIds = await this.resolveFallbackAssignees(manager, instance, fallback, label, subject, chain.length === 0 && startPositionLevel !== null
+            ? `${start.description}沿主管鏈找不到職等達 ${startPositionLevel} 的主管（起始職等 ${startPositionLevel}、簽到職等 ${minPositionLevel}）`
+            : `${start.description}沿主管鏈找不到職等達 ${minPositionLevel} 的主管`);
         return uniqueTexts([...chain, ...fallbackMemberIds]);
     }
+    /**
+     * Whose manager an `ORG_MANAGER_CHAIN` starts from. `memberId` is `null`
+     * when the start names nobody (an empty form field, an earlier stage nobody
+     * approved), with `missingReason` saying why; `description` is the lead-in
+     * of the "no manager reaches the level" reason, empty for the initiator so
+     * a chain without a start keeps today's wording.
+     *
+     * A start that picks more than one person is refused rather than guessed,
+     * the same as a manager rule that names several managers at one priority.
+     */
+    async resolveOrgManagerChainStart(manager, instance, resolver, label, subject) {
+        if ((0, workflow_1.isOrgManagerChainStartedFromInitiator)(resolver)) {
+            return {
+                description: '',
+                memberId: instance.initiatorMemberId,
+                missingReason: '',
+            };
+        }
+        // `INITIATOR` (and an absent start) was answered above.
+        const startFrom = resolver.startFrom;
+        const unsupportedType = (0, workflow_1.readUnsupportedOrgManagerChainStartType)(startFrom);
+        const failure = subject === '通知對象' ? '無法建立通知' : '無法建立待簽任務';
+        // A template saved by a newer engine can carry a start this engine does
+        // not know. Refuse it by name instead of climbing from the initiator,
+        // which would route the task to the wrong people.
+        if (unsupportedType !== null) {
+            throw new common_1.ConflictException(`${label} ${failure}：此引擎版本不支援主管鏈起點「${unsupportedType}」。請升級 BPMCore 後再發佈或執行此流程。`);
+        }
+        // A notify node has no earlier stage and no form pick the publish lint
+        // would have checked; one that reaches here anyway is refused.
+        if (subject === '通知對象') {
+            throw new common_1.ConflictException(`${label} ${failure}：知會節點的主管鏈只能從發起人開始。`);
+        }
+        if (startFrom.type === 'FORM_MEMBER') {
+            const source = `依表單欄位「${startFrom.formPath}」`;
+            const pickedMemberIds = findMemberIdsInValue(readValueAtPath(instance.formData, startFrom.formPath));
+            // Picking one silently would route the document by accident.
+            if (pickedMemberIds.length > 1) {
+                throw new common_1.ConflictException(`${label} ${source}只能選一位人員`);
+            }
+            return {
+                description: `從表單欄位「${startFrom.formPath}」所選人員起算，`,
+                memberId: pickedMemberIds[0] ?? null,
+                missingReason: `表單欄位「${startFrom.formPath}」沒有選人員`,
+            };
+        }
+        const nodeNames = readNodeActorNodeNames(instance, startFrom.nodeIds);
+        const actorMemberIds = await this.readNodeActorMemberIds(manager, instance, startFrom.nodeIds);
+        if (actorMemberIds.length > 1) {
+            throw new common_1.ConflictException(`${label} 無法沿主管鏈簽核：${nodeNames}有多位實際簽核人（${actorMemberIds.join('、')}），無法決定從誰的主管開始。請改選只有一位簽核人的關卡。`);
+        }
+        return {
+            description: `從${nodeNames}的簽核者起算，`,
+            memberId: actorMemberIds[0] ?? null,
+            missingReason: `${nodeNames}沒有實際同意的簽核紀錄`,
+        };
+    }
     /** Highest position level over the member's active memberships, or `null`. */
     async readMemberPositionLevel(manager, memberId, date) {
         return ((await this.readMemberPositionLevels(manager, [memberId], date)).get(memberId) ?? null);
@@ -4647,8 +5210,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         }
         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) });
-            assertServiceTaskTextValue(instance.formDefinitionSnapshot, action.fieldPath, value, node.data.label);
+            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);
             // A service task runs inside this transaction, so it cannot call a host
             // provider to re-resolve the label. Rather than leave the previous
             // option snapshot describing a value that no longer exists, drop it: the
@@ -5027,6 +5591,8 @@ exports.WorkflowEngineService = WorkflowEngineService = WorkflowEngineService_1
     tslib_1.__param(19, (0, common_1.Optional)()),
     tslib_1.__param(19, (0, common_1.Inject)(bpm_root_options_1.BPM_ROOT_OPTIONS)),
     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.__metadata("design:paramtypes", [typeorm_2.Repository,
         typeorm_2.Repository,
         typeorm_2.Repository,
@@ -5043,7 +5609,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])
+        sla_schedule_service_1.BPMSlaScheduleService, Object, Object, Object, workflow_webhook_delivery_service_1.WorkflowWebhookDeliveryService, Object])
 ], WorkflowEngineService);
 function parseJsonObject(value, label) {
     try {
@@ -5066,6 +5632,74 @@ function readDefaultInitiatorMetadataSnapshot(memberId) {
         memberId,
     };
 }
+function cloneJsonObject(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * What a host's initiator `customFields` resolver returned, as the object the
+ * snapshot keeps: a plain object that survives JSON, which is also how it is
+ * stored, so the policy evaluated at submit and the conditions evaluated later
+ * read the same values. Anything else is a bug in the host's resolver; the
+ * caller fails the submission with it rather than replacing it by `{}`, and
+ * `problem` is for the log only.
+ *
+ * The check runs on the round-tripped value too, because an object's `toJSON`
+ * can turn it into something that is not an object. A key whose value is
+ * `undefined` does not survive the round trip either, so it is not in the
+ * stored snapshot.
+ */
+function readResolvedInitiatorCustomFields(value) {
+    if (!isPlainObjectValue(value)) {
+        return { ok: false, problem: 'not a plain object' };
+    }
+    const roundTripped = (() => {
+        try {
+            return JSON.parse(JSON.stringify(value));
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    if (roundTripped === undefined) {
+        return { ok: false, problem: 'not JSON-serializable' };
+    }
+    if (!isPlainObjectValue(roundTripped)) {
+        return { ok: false, problem: 'not a plain object once serialized' };
+    }
+    return { ok: true, value: roundTripped };
+}
+/**
+ * Waits for `promise` at most `timeoutMs`. The timer is cleared as soon as
+ * either side wins. Once the time has run out, whatever `promise` settles with
+ * later goes to `onLateSettle` and nowhere else, so a late rejection is
+ * handled rather than left to surface as an unhandled rejection.
+ */
+function settleWithin(promise, timeoutMs, onLateSettle) {
+    return new Promise((resolve) => {
+        const state = { timedOut: false };
+        const timer = setTimeout(() => {
+            state.timedOut = true;
+            resolve({ status: 'timeout' });
+        }, timeoutMs);
+        const settle = (outcome) => {
+            if (state.timedOut) {
+                onLateSettle(outcome);
+                return;
+            }
+            clearTimeout(timer);
+            resolve(outcome);
+        };
+        promise.then((value) => settle({ status: 'fulfilled', value }), (reason) => settle({ status: 'rejected', reason }));
+    });
+}
+function describeRejection(reason) {
+    return reason instanceof Error
+        ? `${reason.name}: ${reason.message}`
+        : String(reason);
+}
+function isPlainObjectValue(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
 function createWorkflowAuthContext(memberId) {
     return {
         memberId,
@@ -5108,32 +5742,87 @@ function readDataSourceFieldKeyAtPath(snapshot, fieldPath) {
     return field && (0, form_1.isFormDataSourceFieldDefinition)(field) ? field.fieldKey : null;
 }
 /**
- * Holds a `SET_FORM_FIELD` write to the length and format rules the form
- * applies to a filler, so a service task cannot store text the field would
- * have refused. Breaking them throws, which rolls back the submit or decision
+ * Refuses form data whose filterable fields hold a value of the wrong type
+ * (ADR 25 §6). The list query reads these values with type guards, so a wrong
+ * value would silently fall out of every filter; refusing the write is what
+ * keeps filter results trustworthy.
+ */
+function assertFilterableFormDataValues(schema, formData, serviceNodeLabel) {
+    const problems = (0, bpm_core_shared_1.readFilterableValueProblems)((0, bpm_core_shared_1.readFilterableFieldPaths)(schema), formData);
+    if (problems.length === 0) {
+        return;
+    }
+    const issues = problems.map((problem) => (0, form_data_issue_1.createFormDataIssue)(readFilterableProblemLocation(schema, problem), 'TYPE', `必須是${problem.expected}`));
+    const details = (0, form_data_issue_1.readFormDataIssueMessage)(issues);
+    throw (0, form_data_issue_1.createFormDataBadRequest)(serviceNodeLabel
+        ? `系統節點「${serviceNodeLabel}」要寫入的表單值不符合可篩選欄位的型別（${details}），這次操作沒有生效；請聯絡流程管理者修正此節點的寫入值`
+        : `可篩選欄位的值型別不正確：${details}`, issues);
+}
+/** Where a filterable problem sits: a field, a table row, or one cell of a row. */
+function readFilterableProblemLocation(schema, problem) {
+    const [tableKey, columnKey] = problem.path.split('.');
+    const table = schema?.fields.find((field) => field.fieldKey === tableKey && (0, form_1.isTableFieldDefinition)(field));
+    const column = table && (0, form_1.isTableFieldDefinition)(table) && columnKey !== undefined
+        ? table.columns.find((candidate) => candidate.fieldKey === columnKey)
+        : undefined;
+    if (table && (0, form_1.isTableFieldDefinition)(table)) {
+        if (problem.rowIndex === null) {
+            return (0, form_data_issue_1.readFieldIssueLocation)(table);
+        }
+        const rowLocation = (0, form_data_issue_1.readRowIssueLocation)(table, problem.rowIndex);
+        return column ? (0, form_data_issue_1.readCellIssueLocation)(rowLocation, column) : rowLocation;
+    }
+    const field = schema?.fields.find((candidate) => candidate.fieldKey === problem.path);
+    if (field) {
+        return (0, form_data_issue_1.readFieldIssueLocation)(field);
+    }
+    // Not in the schema (the check and this lookup read the same schema, so
+    // this is defensive): still address it the way FormDataIssue.path promises,
+    // `table[i].col` for a row value rather than the dotted filter path.
+    const row = `${tableKey}[${problem.rowIndex}]`;
+    const path = problem.rowIndex === null
+        ? problem.path
+        : columnKey === undefined
+            ? row
+            : `${row}.${columnKey}`;
+    return { path, ref: `欄位「${path}」` };
+}
+/**
+ * Holds a `SET_FORM_FIELD` write to the rules the form applies to a filler —
+ * text length and format, and the shape of a member or organization-unit value
+ * — so a service task cannot store what the field would have refused. A member
+ * value matters past the write: a `DYNAMIC_FORM` resolver or a manager chain
+ * starting from the field reads it later, and an array on a single-member
+ * field would make that node refuse inside a later decision, which then
+ * cannot commit. Breaking them throws, which rolls back the submit or decision
  * that reached the node: the value is never half-written, and the node's value
  * has to be corrected. Only a top-level field can carry those rules — the
  * writer ignores an indexed path, and a nested record path names no field —
  * and an unreadable snapshot is left alone, as in
  * `readDataSourceFieldKeyAtPath`.
  */
-function assertServiceTaskTextValue(snapshot, fieldPath, value, nodeLabel) {
+function assertServiceTaskFieldValue(snapshot, fieldPath, value, nodeLabel) {
     const schema = snapshot?.schema;
     const segments = normalizeFormFieldPath(fieldPath);
     if (!isFormDefinitionSchema(schema) || segments.length !== 1) {
         return;
     }
     const field = schema.fields.find((candidate) => candidate.fieldKey === segments[0]);
+    const written = { [segments[0]]: value };
     const errors = field
-        ? readSubmittedTextValueErrors(field, value, {
-            testPattern: (0, text_field_pattern_test_1.createTimedTextFieldPatternTest)(),
-        })
+        ? [
+            ...readSubmittedTextValueErrors(field, value, {
+                testPattern: (0, text_field_pattern_test_1.createTimedTextFieldPatternTest)(),
+            }),
+            ...(0, form_member_value_validator_1.readSubmittedMemberValueErrors)([field], written),
+            ...(0, form_org_unit_value_validator_1.readSubmittedOrgUnitValueErrors)([field], written),
+        ]
         : [];
     if (!field || errors.length === 0) {
         return;
     }
-    throw new common_1.BadRequestException(`系統節點「${nodeLabel}」要寫入欄位「${field.label || field.fieldKey}」的值不符合該欄位的規則` +
-        `（${errors.join('; ')}），這次操作沒有生效；請聯絡流程管理者修正此節點的寫入值`);
+    throw (0, form_data_issue_1.createFormDataBadRequest)(`系統節點「${nodeLabel}」要寫入的值不符合欄位規則（${(0, form_data_issue_1.readFormDataIssueMessage)(errors)}），` +
+        `這次操作沒有生效；請聯絡流程管理者修正此節點的寫入值`, errors);
 }
 function readSnapshotWithoutField(snapshots, fieldKey) {
     return Object.fromEntries(Object.entries(snapshots ?? {}).filter(([key]) => key !== fieldKey));
@@ -5559,6 +6248,24 @@ function isOrderedSequentialTask(task, candidates) {
 function isInitiatorExcluded(node) {
     return Boolean(node.data.excludeInitiator);
 }
+// Same rule for the earlier-stage exclusion: an explicit `null` is absent.
+function isNodeActorsExcluded(node) {
+    return Boolean(node.data.excludeNodeActors);
+}
+// Whether the node keeps anyone out of its approvers at all.
+function hasSeatExclusion(node) {
+    return isInitiatorExcluded(node) || isNodeActorsExcluded(node);
+}
+function readExcludedNodeActorNodeIds(node) {
+    return node.data.excludeNodeActors?.nodeIds ?? [];
+}
+// With both rules set the initiator rule runs first, so the earlier-stage rule
+// is the one that emptied the list only when the initiator rule alone left
+// somebody. Without `excludeInitiator` the earlier-stage rule is always it.
+function isEmptiedByInitiatorRule(node, delegatedCandidates, exclusions) {
+    return (isInitiatorExcluded(node) &&
+        selectNodeCandidates(delegatedCandidates, true, exclusions.initiatorMemberIds).length === 0);
+}
 // Everyone a node that excludes the initiator keeps out of its approvers: the
 // applicant and, when someone filed the document for them, that person too
 // (authority rule: the creator must not approve what they created).
@@ -5600,6 +6307,27 @@ function collectSkippedDelegations(delegatedCandidates, excludeInitiator, exclud
         return [skipped];
     });
 }
+// The members a rule delegation stands for on a candidate row a person
+// approved: the delegators of the trailing run of rule steps (`ruleId` set).
+// A transfer step carries no rule and is not a delegation, so when one sits on
+// the chain the original assignee is not a delegator and is left out. A chain
+// of rule steps only also names the original assignee.
+function readRuleDelegatorMemberIds(candidate) {
+    const steps = readDelegationSteps(candidate.delegationChain);
+    const trailingRuleCount = [...steps]
+        .reverse()
+        .findIndex((step) => step.ruleId === null);
+    const ruleSteps = trailingRuleCount === -1
+        ? steps
+        : steps.slice(steps.length - trailingRuleCount);
+    if (ruleSteps.length === 0) {
+        return [];
+    }
+    return [
+        ...(trailingRuleCount === -1 ? [candidate.originalMemberId] : []),
+        ...ruleSteps.map((step) => step.from),
+    ];
+}
 // A delegate acting for the initiator is still the initiator approving their
 // own document, so the initiator anywhere on the delegation path (the
 // pre-delegation member, any hop, or the final assignee) drops the candidate.
@@ -6175,8 +6903,43 @@ function validateSubmittedFormData(schema, formData, options = {}) {
                 .filter((field) => field.hidden === true)
                 .flatMap((field) => validateSubmittedTableValue(field, formData[field.fieldKey], false, testPattern, true)),
         ],
+        // Every `file_upload` field, shown or not: the submit binds the files of
+        // each one to the case, so a cap only the visible ones obey could be
+        // stepped around by sending files in a hidden field.
+        readFileUploadErrors: () => readSubmittedFileUploadErrors(schema.fields, formData),
     });
 }
+/**
+ * A `file_upload` field holding more files than its `maxFiles`. The renderer
+ * stops at the cap, but nothing kept a caller that writes the form data itself
+ * from going past it. On a resubmit the value lists the files kept from the
+ * returned case and the ones uploaded since, so both count, as they do in the
+ * renderer. Each distinct non-empty id in the value is one file: the binding
+ * attaches an id once however often it repeats, so a repeat is not a second
+ * file. A field without `maxFiles` takes any number, as it does in the
+ * renderer.
+ */
+function readSubmittedFileUploadErrors(fields, formData) {
+    return fields.flatMap((field) => {
+        if (field.type !== 'file_upload' || typeof field.maxFiles !== 'number') {
+            return [];
+        }
+        const fileCount = countFileUploadValueIds(readRowCellValue(formData, field.fieldKey));
+        return fileCount > field.maxFiles
+            ? [
+                (0, form_data_issue_1.createFormDataIssue)((0, form_data_issue_1.readFieldIssueLocation)(field), 'MAX_FILES', `最多 ${field.maxFiles} 個檔案`, field.maxFiles),
+            ]
+            : [];
+    });
+}
+/**
+ * The distinct files a `file_upload` value names. The ids are read by the same
+ * helper the attachment binding uses, and collapsed the way the binding
+ * collapses them (one attachment per id).
+ */
+function countFileUploadValueIds(value) {
+    return new Set((0, file_upload_value_ids_1.readFileUploadValueIds)(value)).size;
+}
 /**
  * What an approval at a node has to leave behind: every field the node lets the
  * approver fill in is well-formed (a table is an array of well-formed rows with
@@ -6207,30 +6970,31 @@ function validateFilledFormFields(schema, formData, fieldKeys, requiredFieldKeys
  * The shared tail of submit and approver-fill validation: a missing required
  * field wins over a text value breaking its length or format rule, which wins
  * over a malformed member value, which wins over a malformed org unit value,
- * which wins over a table problem, and the later checks are only evaluated
- * when the earlier ones pass.
+ * which wins over a table problem, which wins over a `file_upload` field
+ * holding more files than it allows, and the later checks are only evaluated
+ * when the earlier ones pass. The refusal carries every issue of the winning
+ * check. Its message is those issues' sentences joined, except for missing
+ * required fields, which keep the one-line summary `缺少必填欄位：A, B` that
+ * submitters read; each issue there still says `欄位「A」為必填`. A client
+ * that places errors on fields reads the issues, not the message.
  */
-function throwFirstFormDataFieldError({ missingFields, readMemberErrors, readOrgUnitErrors, readTableErrors, readTextErrors, }) {
+function throwFirstFormDataFieldError({ missingFields, readFileUploadErrors = () => [], readMemberErrors, readOrgUnitErrors, readTableErrors, readTextErrors, }) {
     if (missingFields.length > 0) {
-        throw new common_1.BadRequestException(`Form data is missing required fields: ${missingFields
+        throw (0, form_data_issue_1.createFormDataBadRequest)(`缺少必填欄位：${missingFields
             .map((field) => field.label || field.fieldKey)
-            .join(', ')}`);
-    }
-    const textErrors = readTextErrors();
-    if (textErrors.length > 0) {
-        throw new common_1.BadRequestException(textErrors.join('; '));
-    }
-    const memberErrors = readMemberErrors();
-    if (memberErrors.length > 0) {
-        throw new common_1.BadRequestException(memberErrors.join('; '));
+            .join(', ')}`, missingFields.map((field) => (0, form_data_issue_1.createFormDataIssue)((0, form_data_issue_1.readFieldIssueLocation)(field), 'REQUIRED', '為必填')));
     }
-    const orgUnitErrors = readOrgUnitErrors();
-    if (orgUnitErrors.length > 0) {
-        throw new common_1.BadRequestException(orgUnitErrors.join('; '));
-    }
-    const tableErrors = readTableErrors();
-    if (tableErrors.length > 0) {
-        throw new common_1.BadRequestException(tableErrors.join('; '));
+    // Each check runs only when every earlier one passed, so a later check's
+    // work is never done for a request that is already refused.
+    const winning = [
+        readTextErrors,
+        readMemberErrors,
+        readOrgUnitErrors,
+        readTableErrors,
+        readFileUploadErrors,
+    ].reduce((found, check) => (found.length > 0 ? found : check()), []);
+    if (winning.length > 0) {
+        throw (0, form_data_issue_1.createFormDataBadRequest)((0, form_data_issue_1.readFormDataIssueMessage)(winning), winning);
     }
 }
 /**
@@ -6239,64 +7003,73 @@ function throwFirstFormDataFieldError({ missingFields, readMemberErrors, readOrg
  * the flat text fields share. `minimum` / `maximum` stay a frontend hint.
  */
 function validateSubmittedTableValue(field, value, required, testPattern, shapeOnly = false) {
-    const path = `formData.${field.fieldKey}`;
+    const location = (0, form_data_issue_1.readFieldIssueLocation)(field);
     if (typeof value === 'undefined' || value === null) {
-        return shapeOnly
-            ? []
-            : required || readTableMinRows(field) > 0
-                ? [`${path} must include at least ${readTableRequiredRowCount(field)} row(s)`]
-                : [];
+        if (shapeOnly) {
+            return [];
+        }
+        if (required || readTableMinRows(field) > 0) {
+            const rows = readTableRequiredRowCount(field);
+            return [
+                (0, form_data_issue_1.createFormDataIssue)(location, 'MIN_ROWS', `至少需要 ${rows} 列`, rows),
+            ];
+        }
+        return [];
     }
     if (!Array.isArray(value)) {
-        return [`${path} must be an array of rows`];
+        return [(0, form_data_issue_1.createFormDataIssue)(location, 'TYPE', '必須是表格列的清單')];
     }
     // Too many rows is refused before any row is checked: the rows a submitter
     // sends would otherwise decide how many cells the text patterns run on.
     const maxRows = readTableMaxRows(field);
     if (value.length > maxRows) {
-        return [`${path} must include at most ${maxRows} row(s)`];
+        return [
+            (0, form_data_issue_1.createFormDataIssue)(location, 'MAX_ROWS', `最多 ${maxRows} 列`, maxRows),
+        ];
     }
-    const rowErrors = value.flatMap((row, index) => validateSubmittedTableRow(field, row, `${path}[${index}]`, testPattern, shapeOnly));
+    const rowErrors = value.flatMap((row, index) => validateSubmittedTableRow(field, row, (0, form_data_issue_1.readRowIssueLocation)(field, index), testPattern, shapeOnly));
     // A malformed row cannot be counted against the minimum meaningfully; report
     // the shape problem first so the submitter fixes the real cause.
     if (rowErrors.length > 0) {
         return rowErrors;
     }
-    return validateSubmittedTableRowCount(field, value.length, required, path, shapeOnly);
+    return validateSubmittedTableRowCount(field, value.length, required, location, shapeOnly);
 }
 /** The minimum only: the maximum is refused before any row is checked. */
-function validateSubmittedTableRowCount(field, rowCount, required, path, shapeOnly = false) {
+function validateSubmittedTableRowCount(field, rowCount, required, location, shapeOnly = false) {
     const minRows = shapeOnly
         ? 0
         : required
             ? Math.max(readTableMinRows(field), 1)
             : readTableMinRows(field);
     return rowCount < minRows
-        ? [`${path} must include at least ${minRows} row(s)`]
+        ? [
+            (0, form_data_issue_1.createFormDataIssue)(location, 'MIN_ROWS', `至少需要 ${minRows} 列`, minRows),
+        ]
         : [];
 }
-function validateSubmittedTableRow(field, row, path, testPattern, shapeOnly = false) {
+function validateSubmittedTableRow(field, row, location, testPattern, shapeOnly = false) {
     if (!isRecord(row)) {
-        return [`${path} must be an object`];
+        return [(0, form_data_issue_1.createFormDataIssue)(location, 'TYPE', '必須是物件')];
     }
     const columnsByKey = new Map(field.columns.map((column) => [column.fieldKey, column]));
     const unknownKeyErrors = Object.keys(row)
         .filter((columnKey) => !columnsByKey.has(columnKey))
-        .map((columnKey) => `${path}.${columnKey} is not a table column`);
+        .map((columnKey) => (0, form_data_issue_1.createFormDataIssue)(location, 'UNKNOWN_COLUMN', `含有不屬於此表格的欄位「${columnKey}」`));
     const cellErrors = Object.entries(row)
         .filter(([columnKey, cellValue]) => columnsByKey.has(columnKey) && !(0, form_1.isFormTableCellValue)(cellValue))
-        .map(([columnKey]) => `${path}.${columnKey} is not a valid cell value`);
+        .map(([columnKey]) => (0, form_data_issue_1.createFormDataIssue)((0, form_data_issue_1.readCellIssueLocation)(location, columnsByKey.get(columnKey) ?? { fieldKey: columnKey }), 'TYPE', '不是有效的值'));
     const requiredErrors = shapeOnly
         ? []
         : field.columns
             .filter((column) => isSubmittedTableColumnRequired(column) &&
             !isSubmittedFieldValuePresent(readRowCellValue(row, column.fieldKey)))
-            .map((column) => `${path}.${column.fieldKey} is required`);
+            .map((column) => (0, form_data_issue_1.createFormDataIssue)((0, form_data_issue_1.readCellIssueLocation)(location, column), 'REQUIRED', '為必填'));
     // A shape-only pass covers a table nobody fills in, so the filler-facing
     // rules do not apply to it, the same as the required check above; only a
     // cell of the wrong type is still refused.
     const textErrors = field.columns.flatMap((column) => readSubmittedTextValueErrors(column, readRowCellValue(row, column.fieldKey), {
-        path: `${path}.${column.fieldKey}`,
+        location: (0, form_data_issue_1.readCellIssueLocation)(location, column),
         shapeOnly,
         testPattern,
     }));
@@ -6313,7 +7086,7 @@ function validateSubmittedTableRow(field, row, path, testPattern, shapeOnly = fa
  * budget is spent, a value is reported as not checked rather than as a
  * format error.
  */
-function readSubmittedTextValueErrors(field, value, { path = `formData.${field.fieldKey}`, shapeOnly = false, testPattern, }) {
+function readSubmittedTextValueErrors(field, value, { location = (0, form_data_issue_1.readFieldIssueLocation)(field), shapeOnly = false, testPattern, }) {
     if (field.type !== 'text' && field.type !== 'textarea') {
         return [];
     }
@@ -6332,21 +7105,27 @@ function readSubmittedTextValueErrors(field, value, { path = `formData.${field.f
     };
     const issue = readIssue();
     if (issue === 'timeout') {
-        return [`${path} could not be checked against the required format in time`];
+        return [
+            (0, form_data_issue_1.createFormDataIssue)(location, 'PATTERN_TIMEOUT', '無法在時限內完成格式檢查'),
+        ];
     }
     if (!issue || (shapeOnly && issue.kind !== 'type')) {
         return [];
     }
     if (issue.kind === 'type') {
-        return [`${path} must be text`];
+        return [(0, form_data_issue_1.createFormDataIssue)(location, 'TYPE', '必須是文字')];
     }
     if (issue.kind === 'minLength') {
-        return [`${path} must be at least ${issue.limit} characters`];
+        return [
+            (0, form_data_issue_1.createFormDataIssue)(location, 'MIN_LENGTH', `至少需要 ${issue.limit} 個字`, issue.limit),
+        ];
     }
     if (issue.kind === 'maxLength') {
-        return [`${path} must be at most ${issue.limit} characters`];
+        return [
+            (0, form_data_issue_1.createFormDataIssue)(location, 'MAX_LENGTH', `最多 ${issue.limit} 個字`, issue.limit),
+        ];
     }
-    return [`${path} does not match the required format`];
+    return [(0, form_data_issue_1.createFormDataIssue)(location, 'PATTERN', '格式不正確')];
 }
 /**
  * Own-property read. `constructor`, `toString` and friends all satisfy the
@@ -6593,7 +7372,7 @@ function readDryRunPlaceholderAssignee(resolver) {
         return `nodeActorManager:${resolver.nodeIds.join(',')}:${resolver.levelsUp}`;
     }
     return resolver.type === 'ORG_MANAGER_CHAIN'
-        ? `orgManagerChain:${resolver.minPositionLevel}`
+        ? (0, workflow_1.formatOrgManagerChainPlaceholder)(resolver)
         : resolver.type;
 }
 function readDryRunUnresolvedApproverMessage(resolver, nodeName, initiatorMemberId) {