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

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

@@ -36,7 +36,9 @@ const organization_enums_1 = require("../organization/organization.enums");
 const organization_time_zone_1 = require("../organization/organization-time-zone");
 const approval_template_version_entity_1 = require("../template/approval-template-version.entity");
 const approval_template_entity_1 = require("../template/approval-template.entity");
+const approver_filled_table_columns_1 = require("./approver-filled-table-columns");
 const template_enums_1 = require("../template/template.enums");
+const missing_form_fields_1 = require("./missing-form-fields");
 const activity_log_entity_1 = require("./activity-log.entity");
 const adhoc_directive_entity_1 = require("./adhoc-directive.entity");
 const adhoc_enums_1 = require("./adhoc.enums");
@@ -58,6 +60,9 @@ const expression_budget_1 = require("../condition/expression-budget");
 const expression_errors_1 = require("../condition/expression-errors");
 const expression_dialect_1 = require("../condition/expression-dialect");
 const initiator_custom_fields_resolver_token_1 = require("./initiator-custom-fields-resolver.token");
+const instance_event_writer_1 = require("../instance-event/instance-event.writer");
+const instance_guard_token_1 = require("./instance-guard.token");
+const instance_guard_runner_1 = require("./instance-guard.runner");
 const workflow_service_task_dispatcher_token_1 = require("./workflow-service-task-dispatcher.token");
 const workflow_token_entity_1 = require("./workflow-token.entity");
 const bpm_root_options_1 = require("../bpm/bpm-root-options");
@@ -182,6 +187,28 @@ const INACTIVE_MEMBER_NAME_LOCALE = 'zh-Hant-TW';
  * every load of the member screen.
  */
 const INACTIVE_MEMBER_COUNT_CONCURRENCY = 5;
+/**
+ * ADR 27 §4.2: an approver-filled value the provider no longer offers answers
+ * 400 with `formDataErrors` naming the field or table cell, `code` kept. Other
+ * failures pass through unchanged.
+ */
+async function answerValueNotResolved(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof form_data_source_errors_1.BPMFormDataSourceValueNotResolvedException) {
+            const issue = {
+                ...(0, form_data_issue_1.createFormDataIssue)(error.location, 'VALUE_NOT_RESOLVED', '的選項已不在可選範圍內，請重新選擇'),
+                code: form_data_source_errors_1.BPM_FORM_DATA_SOURCE_ERROR_CODES.VALUE_NOT_RESOLVED,
+            };
+            throw (0, form_data_issue_1.createFormDataBadRequest)((0, form_data_issue_1.readFormDataIssueMessage)([issue]), [
+                issue,
+            ]);
+        }
+        throw error;
+    }
+}
 const WORKFLOW_READ_ALL_PERMISSIONS = new Set([
     'bpm:*',
     'bpm.workflow.read_all',
@@ -189,7 +216,7 @@ const WORKFLOW_READ_ALL_PERMISSIONS = new Set([
     'workflow.read_all',
 ]);
 let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineService {
-    constructor(approvalInstanceRepository, workflowTokenRepository, taskRepository, taskCandidateRepository, taskDecisionRepository, notificationRepository, activityLogRepository, adhocDirectiveRepository, approvalTemplateRepository, approvalTemplateVersionRepository, formDefinitionVersionRepository, attachmentService, conditionService, delegationService, notificationService, signatureService, slaScheduleService, injectedServiceTaskDispatcher, formDataSourceValueResolver, rootOptions, webhookDeliveryService, injectedInitiatorCustomFieldsResolver) {
+    constructor(approvalInstanceRepository, workflowTokenRepository, taskRepository, taskCandidateRepository, taskDecisionRepository, notificationRepository, activityLogRepository, adhocDirectiveRepository, approvalTemplateRepository, approvalTemplateVersionRepository, formDefinitionVersionRepository, attachmentService, conditionService, delegationService, notificationService, signatureService, slaScheduleService, injectedServiceTaskDispatcher, formDataSourceValueResolver, rootOptions, webhookDeliveryService, injectedInitiatorCustomFieldsResolver, injectedInstanceGuard, instanceEventWriter) {
         this.approvalInstanceRepository = approvalInstanceRepository;
         this.workflowTokenRepository = workflowTokenRepository;
         this.taskRepository = taskRepository;
@@ -209,6 +236,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         this.slaScheduleService = slaScheduleService;
         this.formDataSourceValueResolver = formDataSourceValueResolver;
         this.webhookDeliveryService = webhookDeliveryService;
+        this.instanceEventWriter = instanceEventWriter;
         this.logger = new common_1.Logger(WorkflowEngineService_1.name);
         /** In-flight inbox reads by member; see `readSharedOpenInboxTasks`. */
         this.openInboxReadsInFlight = new Map();
@@ -236,7 +264,68 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             injectedInitiatorCustomFieldsResolver ??
                 rootOptions?.initiatorCustomFieldsResolver ??
                 null;
+        // Same three-way order as the initiator resolver: a host binding under the
+        // token, then the runtime instance, then no guard at all.
+        this.instanceGuard =
+            injectedInstanceGuard ?? rootOptions?.instanceGuard ?? null;
+        this.instanceGuardTimeoutMs =
+            rootOptions?.instanceGuardTimeoutMs ??
+                instance_guard_runner_1.BPM_INSTANCE_GUARD_DEFAULT_TIMEOUT_MS;
         this.organizationTimeZone = (0, organization_time_zone_1.resolveBPMOrganizationTimeZone)(rootOptions?.organizationTimeZone);
+        this.expressionMissingFormFieldsAsNull =
+            rootOptions?.expressionMissingFormFieldsAsNull === true;
+    }
+    /**
+     * Runs the bound guard for one engine path inside its transaction. A no-op
+     * when no guard is bound, so a host without one sees no behavior change.
+     */
+    async guardInstanceChange(input) {
+        if (this.instanceGuard === null) {
+            return;
+        }
+        await (0, instance_guard_runner_1.runInstanceGuard)(this.instanceGuard, input, this.instanceGuardTimeoutMs);
+    }
+    /**
+     * Writes one case-lifecycle event (ADR 27 §1) in the caller's transaction.
+     * Returns before any lookup when no observer is bound, so a host without
+     * one pays nothing. `instanceState` is the state the change commits, not the
+     * state the instance held before it.
+     */
+    async recordInstanceEvent(manager, instance, instanceState, type, fields) {
+        if (this.instanceEventWriter?.enabled !== true) {
+            return;
+        }
+        const template = await manager
+            .getRepository(approval_template_entity_1.ApprovalTemplateEntity)
+            .findOne({
+            select: { id: true, key: true },
+            where: { id: instance.templateId },
+            withDeleted: true,
+        });
+        const snapshot = {
+            instanceState,
+            templateId: instance.templateId,
+            templateKey: template?.key ?? null,
+            templateVersionId: instance.templateVersionId,
+        };
+        await this.instanceEventWriter.record(manager, instance.id, snapshot, type, fields);
+    }
+    /**
+     * Reads the template version a case runs on, inside the engine transaction,
+     * so the guard sees the same snapshot as the decision. A missing row fails
+     * the change rather than handing the guard a partial input.
+     */
+    async readBoundTemplateVersionOrThrow(manager, instance) {
+        const version = await manager
+            .getRepository(approval_template_version_entity_1.ApprovalTemplateVersionEntity)
+            .findOne({ where: { id: instance.templateVersionId } });
+        if (!version) {
+            throw new common_1.ConflictException({
+                code: 'TEMPLATE_VERSION_NOT_FOUND',
+                message: 'The template version of this instance no longer exists.',
+            });
+        }
+        return version;
     }
     /**
      * Today's date as the organization sees it (`organizationTimeZone`), for
@@ -308,6 +397,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 input.submittedByMemberId.trim() === '')) {
             throw new common_1.BadRequestException('submittedByMemberId must be a non-empty string');
         }
+        const hostCustomFields = readHostInitiatorCustomFields(input);
         const submittedFormData = parseJsonObject(input.formDataJson, 'formDataJson');
         const businessKey = normalizeBusinessKey(input.businessKey);
         const submittedByMemberId = input.submittedByMemberId ?? input.initiatorMemberId;
@@ -319,6 +409,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             throw new common_1.ConflictException('Approval template does not have a published version');
         }
         const templateVersion = await this.getPublishedTemplateVersionOrThrow(template.currentVersionId);
+        if (input.endUserSubmission === true) {
+            assertEndUserMayLaunch(templateVersion);
+        }
         const formDefinitionVersion = await this.getPublishedFormVersionOrThrow(templateVersion.formDefinitionVersionId);
         // The fields an approver fills in belong to the approval, not the
         // application: an end user's value for one is dropped (it would otherwise
@@ -327,13 +420,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         // checked here; required and row minimums wait for the node that fills
         // them. Read off the version the instance is bound to, not the template's
         // latest, so a publish in between cannot change what is stripped.
-        const deferredFieldKeys = (0, bpm_core_shared_1.readApproverFilledFieldKeys)(templateVersion.workflowDefinition);
+        const deferral = (0, approver_filled_table_columns_1.readApproverFilledDeferral)(templateVersion.workflowDefinition);
         const formData = input.endUserSubmission === true
-            ? (0, bpm_core_shared_1.omitFormDataKeys)(submittedFormData, deferredFieldKeys)
+            ? (0, approver_filled_table_columns_1.applyOpenColumnCells)((0, bpm_core_shared_1.omitFormDataKeys)(submittedFormData, deferral.wholeKeys), null, deferral)
             : submittedFormData;
-        validateSubmittedFormData(formDefinitionVersion.schema, formData, {
-            deferredFieldKeys,
-        });
+        validateSubmittedFormData((0, approver_filled_table_columns_1.projectOpenColumnsOptional)(formDefinitionVersion.schema, deferral), formData, { deferredFieldKeys: deferral.wholeKeys });
         // Checked against the bound version's schema before any data source is
         // called, so a bad value is refused cheaply. The transaction below
         // confirms under the template lock that this version is still current
@@ -347,7 +438,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         });
         const initiatorMetadataSnapshot = input.initiatorMetadataSnapshotJson
             ? parseJsonObject(input.initiatorMetadataSnapshotJson, 'initiatorMetadataSnapshotJson')
-            : await this.buildInitiatorMetadataSnapshot({
+            : mergeHostInitiatorCustomFields(await this.buildInitiatorMetadataSnapshot({
                 authContext: submitAuthContext,
                 memberId: input.initiatorMemberId,
                 submission: {
@@ -355,7 +446,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                     templateId: template.id,
                     templateVersionId: templateVersion.id,
                 },
-            });
+            }), hostCustomFields);
         if (!this.conditionService.evaluateBoolean(templateVersion.initiatorPolicyCel, buildInitiatorPolicyContext(initiatorMetadataSnapshot), 'initiatorPolicyCel', 
         // The policy is written in its version's dialect (ADR 22 §3.3).
         readExpressionDialectOptions(templateVersion.initiatorPolicyCel, templateVersion.workflowDefinition))) {
@@ -396,7 +487,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             const instanceRepository = manager.getRepository(approval_instance_entity_1.ApprovalInstanceEntity);
             const tokenRepository = manager.getRepository(workflow_token_entity_1.WorkflowTokenEntity);
             const activityRepository = manager.getRepository(activity_log_entity_1.ActivityLogEntity);
-            const instance = await instanceRepository.save(instanceRepository.create({
+            const instanceDraft = instanceRepository.create({
                 completedAt: null,
                 formData,
                 formDataOptionSnapshot,
@@ -416,7 +507,24 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 templateVersionId: templateVersion.id,
                 title: input.title?.trim() || template.name,
                 workflowSnapshot: templateVersion.workflowDefinition,
-            }));
+            });
+            // ADR 27 §2: the host guard sees the case as it is about to be saved,
+            // under the template lock. A refusal throws here, before any insert.
+            await this.guardInstanceChange({
+                action: null,
+                actorMemberId: submittedByMemberId,
+                authContext: authContext ?? null,
+                automatic: null,
+                changedFieldKeys: Object.keys(formData),
+                formData,
+                instance: instanceDraft,
+                kind: 'SUBMIT',
+                manager,
+                node: null,
+                task: null,
+                templateVersion,
+            });
+            const instance = await instanceRepository.save(instanceDraft);
             await this.attachmentService.bindFormDataAttachmentsToInstance(manager, {
                 formData,
                 instanceId: instance.id,
@@ -454,6 +562,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                     taskId: null,
                 }),
             ]);
+            await this.recordInstanceEvent(manager, instance, instance.state, 'INSTANCE_SUBMITTED', { actorMemberId: submittedByMemberId });
             await this.processRunningInstance(manager, instance);
             return instance;
         }).catch((error) => 
@@ -494,6 +603,66 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             schema,
         });
     }
+    /**
+     * ADR 27 §4(b): asks the data-source providers again, under the decision
+     * lock and as the approver, for the options of the approver-fillable fields.
+     * A value that is no longer among the options is refused by the resolver
+     * (`VALUE_NOT_RESOLVED`). Returns snapshots for the scoped fields only; the
+     * caller swaps them in for the stored ones.
+     */
+    async refreshApproverFilledOptionSnapshots({ approverAuthContext, fieldKeys, formData, instance, }) {
+        const schema = readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot);
+        return this.resolveFormDataOptionSnapshots({
+            authContext: approverAuthContext,
+            formData,
+            previousFormData: instance.formData,
+            previousSnapshots: readSnapshotWithoutFields(instance.formDataOptionSnapshot, fieldKeys),
+            revalidateAll: true,
+            schema: {
+                ...schema,
+                fields: schema.fields.filter((field) => fieldKeys.has(field.fieldKey)),
+            },
+        });
+    }
+    /**
+     * ADR 27 §4(b): asks the data-source providers again, as the approver, for
+     * the open data-source cells of column-mode tables. `revalidateAll` false lets
+     * the resolver reuse the stored options of cells whose value and bindings did
+     * not move. Returns snapshots for the cells of `cellSchema` only.
+     */
+    async refreshApproverFilledOpenCellSnapshots({ approverAuthContext, cellSchema, formData, instance, revalidateAll, }) {
+        return this.resolveFormDataOptionSnapshots({
+            authContext: approverAuthContext,
+            formData,
+            previousFormData: instance.formData,
+            previousSnapshots: instance.formDataOptionSnapshot ?? {},
+            revalidateAll,
+            schema: cellSchema,
+        });
+    }
+    /**
+     * Refuses an end user's resubmission of an instance bound to a `HOST_ONLY`
+     * version (ADR 27 §5). Checked before any data source is called and outside
+     * the lock: an instance never changes version and a published version never
+     * changes `launchMode`, so the answer cannot go stale. An instance that does
+     * not exist is left to the locked read, which reports it.
+     */
+    async assertEndUserMayResubmit(instanceId) {
+        const instance = await this.approvalInstanceRepository.findOne({
+            select: { id: true, templateVersionId: true },
+            where: { id: instanceId },
+        });
+        if (!instance) {
+            return;
+        }
+        const version = await this.approvalTemplateVersionRepository.findOne({
+            select: { id: true, launchMode: true },
+            where: { id: instance.templateVersionId },
+        });
+        if (version) {
+            assertEndUserMayLaunch(version);
+        }
+    }
     async prepareResubmitFormDataOptions(input, submittedFormData, authContext) {
         const instance = await this.approvalInstanceRepository.findOne({
             where: { id: input.instanceId },
@@ -512,13 +681,13 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             throw new common_1.ConflictException('Approval template is deactivated');
         }
         const schema = readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot);
-        const deferredFieldKeys = (0, bpm_core_shared_1.readApproverFilledFieldKeys)(instance.workflowSnapshot);
+        const deferral = (0, approver_filled_table_columns_1.readApproverFilledDeferral)(instance.workflowSnapshot);
         // Same overlay as inside the lock, so the options resolved here are for
         // the form data that is actually saved.
         const formData = input.endUserSubmission === true
-            ? (0, bpm_core_shared_1.overlayStoredFormDataKeys)(submittedFormData, instance.formData, deferredFieldKeys)
+            ? (0, approver_filled_table_columns_1.applyOpenColumnCells)((0, bpm_core_shared_1.overlayStoredFormDataKeys)(submittedFormData, instance.formData, deferral.wholeKeys), instance.formData, deferral)
             : submittedFormData;
-        validateSubmittedFormData(schema, formData, { deferredFieldKeys });
+        validateSubmittedFormData((0, approver_filled_table_columns_1.projectOpenColumnsOptional)(schema, deferral), formData, { deferredFieldKeys: deferral.wholeKeys });
         await this.assertCurrentFilterableFormDataValues(instance.templateId, formData);
         const formDataOptionSnapshot = await this.resolveFormDataOptionSnapshots({
             authContext,
@@ -556,6 +725,26 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             await this.processRunningInstance(manager, instance);
         });
     }
+    /**
+     * Records `TASK_AUTO_DECISION_FAILED` (ADR 27 §3) in its own transaction.
+     * Used after an automatic decision was refused by the instance guard: the
+     * decision's transaction has already rolled back, so the event cannot ride
+     * on it. Returns before any query when no observer is bound.
+     */
+    async recordTaskAutoDecisionFailed(input) {
+        if (this.instanceEventWriter?.enabled !== true) {
+            return;
+        }
+        await this.runEngineTransaction(async (manager) => {
+            const instance = await manager
+                .getRepository(approval_instance_entity_1.ApprovalInstanceEntity)
+                .findOne({ where: { id: input.instanceId } });
+            if (!instance) {
+                return;
+            }
+            await this.recordInstanceEvent(manager, instance, instance.state, 'TASK_AUTO_DECISION_FAILED', { reason: input.reason, taskId: input.taskId });
+        });
+    }
     async decideTask(input, options = {}) {
         return this.runEngineTransaction(async (manager) => {
             const taskRepository = manager.getRepository(task_entity_1.TaskEntity);
@@ -719,9 +908,14 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             if (filledFormData !== null && task.isAdhoc) {
                 throw new common_1.ForbiddenException(`Ad-hoc task ${task.id} cannot fill in form fields`);
             }
+            // ADR 27 §4(a): column-mode tables are accepted here and settled
+            // cell by cell below. Their open data-source columns are re-resolved per
+            // row as the approver (ADR 27 §4(b)).
+            const nodeColumnFillMap = (0, approver_filled_table_columns_1.readNodeColumnFillMap)(taskNode);
             if (filledFormData !== null) {
                 const fillableFieldKeys = (0, bpm_core_shared_1.readNodeFillableFieldKeys)(taskNode);
-                const refusedFieldKeys = Object.keys(filledFormData).filter((fieldKey) => !fillableFieldKeys.has(fieldKey));
+                const refusedFieldKeys = Object.keys(filledFormData).filter((fieldKey) => !fillableFieldKeys.has(fieldKey) &&
+                    !nodeColumnFillMap.has(fieldKey));
                 if (refusedFieldKeys.length > 0) {
                     throw new common_1.ForbiddenException(`Workflow node ${task.nodeId} does not let approvers fill in: ${refusedFieldKeys.join(', ')}`);
                 }
@@ -732,35 +926,134 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                     (0, form_data_fingerprint_1.computeFormDataFingerprint)(instance.formData)) {
                 throw new common_1.ConflictException(`Approval instance ${instance.id} form data changed; refresh and retry`);
             }
+            // ADR 27 §4(a): each column-mode table is merged per cell against the
+            // stored rows. A changed row count, row order or applicant cell is
+            // refused before anything below sees the payload.
+            const settledFormData = filledFormData === null
+                ? null
+                : (0, approver_filled_table_columns_1.settleColumnFillPayload)(filledFormData, instance.formData, nodeColumnFillMap);
             // Only keys whose value really changes are written and reported. A key
             // the form data does not have yet counts as changed even when the new
             // value is null.
-            const changedFieldKeys = filledFormData === null
+            const changedFieldKeys = settledFormData === null
                 ? []
-                : Object.keys(filledFormData)
+                : Object.keys(settledFormData)
                     .filter((fieldKey) => !Object.prototype.hasOwnProperty.call(instance.formData, fieldKey) ||
-                    (0, form_data_fingerprint_1.computeStableValueFingerprint)(filledFormData[fieldKey]) !==
+                    (0, form_data_fingerprint_1.computeStableValueFingerprint)(settledFormData[fieldKey]) !==
                         (0, form_data_fingerprint_1.computeStableValueFingerprint)(instance.formData[fieldKey]))
                     .sort();
-            const mergedFormData = { ...instance.formData, ...filledFormData };
+            const mergedFormData = { ...instance.formData, ...settledFormData };
+            // ADR 27 §4.3: an approver may change a column only if no column this
+            // approver may not fill reads it. Such a dependent keeps its stored value
+            // here, so a changed source would leave it stale. Fail closed.
+            if (nodeColumnFillMap.size > 0) {
+                (0, approver_filled_table_columns_1.assertDependentColumnsFrozen)(readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot), taskNode, instance.formData, mergedFormData);
+            }
             // Every approval at a node that lets its approver fill in fields is
             // held to those fields, whether or not this request sent any: the host
-            // may have pre-filled a table the approver then leaves as is.
+            // may have pre-filled a table the approver then leaves as is. A column
+            // this node grants REQUIRED is required in the check, not only in the
+            // template.
             if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED && !task.isAdhoc) {
-                const nodeFillableFieldKeys = (0, bpm_core_shared_1.readNodeFillableFieldKeys)(taskNode);
+                const nodeFillableFieldKeys = new Set([
+                    ...(0, bpm_core_shared_1.readNodeFillableFieldKeys)(taskNode),
+                    ...nodeColumnFillMap.keys(),
+                ]);
                 if (nodeFillableFieldKeys.size > 0) {
-                    validateFilledFormFields(readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot), mergedFormData, nodeFillableFieldKeys, (0, bpm_core_shared_1.readNodeRequiredFieldKeys)(taskNode));
+                    validateFilledFormFields((0, approver_filled_table_columns_1.projectNodeOpenColumnsRequired)(readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot), nodeColumnFillMap), mergedFormData, nodeFillableFieldKeys, (0, bpm_core_shared_1.readNodeRequiredFieldKeys)(taskNode));
                 }
             }
-            if (filledFormData !== null && changedFieldKeys.length > 0) {
+            // ADR 27 §4(b): an approver-filled data-source field is judged as the
+            // approver's own pick. The provider is asked again under the lock with
+            // the approver's identity, so a value outside the current options is
+            // refused and the recorded label is refreshed before anything is
+            // written. Table data-source columns resolve per row (ROW_FIELD).
+            const fillableFieldKeys = (0, bpm_core_shared_1.readNodeFillableFieldKeys)(taskNode);
+            const dataSourceRefreshKeys = input.action === workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED && !task.isAdhoc
+                ? fillableFieldKeys
+                : new Set(changedFieldKeys.filter((fieldKey) => fillableFieldKeys.has(fieldKey)));
+            const approverAuthContext = options.approverAuthContext ??
+                createWorkflowAuthContext(input.decidedByMemberId);
+            const refreshedFormDataOptionSnapshots = dataSourceRefreshKeys.size === 0
+                ? null
+                : await answerValueNotResolved(() => this.refreshApproverFilledOptionSnapshots({
+                    approverAuthContext,
+                    fieldKeys: dataSourceRefreshKeys,
+                    formData: mergedFormData,
+                    instance,
+                }));
+            const wholeFieldOptionSnapshot = refreshedFormDataOptionSnapshots === null
+                ? (instance.formDataOptionSnapshot ?? {})
+                : {
+                    ...readSnapshotWithoutFields(instance.formDataOptionSnapshot, dataSourceRefreshKeys),
+                    ...refreshedFormDataOptionSnapshots,
+                };
+            // ADR 27 §4(b): the open data-source cells of column-mode tables. An
+            // APPROVED decision re-resolves all of them; any other decision only
+            // when a column-mode table's cells changed. The form schema is read
+            // only for a node that has column-mode fills, so other nodes never
+            // touch the snapshot's schema.
+            const openCellSchema = nodeColumnFillMap.size === 0
+                ? null
+                : (0, approver_filled_table_columns_1.readOpenDataSourceCellSchema)(readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot), nodeColumnFillMap);
+            const openCellTableKeys = new Set((openCellSchema?.fields ?? []).map((field) => field.fieldKey));
+            const revalidateAllOpenCells = input.action === workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED && !task.isAdhoc;
+            const hasChangedOpenCellTable = changedFieldKeys.some((fieldKey) => openCellTableKeys.has(fieldKey));
+            const refreshedOpenCellSnapshots = openCellSchema === null ||
+                openCellSchema.fields.length === 0 ||
+                (!revalidateAllOpenCells && !hasChangedOpenCellTable)
+                ? null
+                : await answerValueNotResolved(() => this.refreshApproverFilledOpenCellSnapshots({
+                    approverAuthContext,
+                    cellSchema: openCellSchema,
+                    formData: mergedFormData,
+                    instance,
+                    revalidateAll: revalidateAllOpenCells,
+                }));
+            const nextFormDataOptionSnapshot = refreshedOpenCellSnapshots === null || openCellSchema === null
+                ? wholeFieldOptionSnapshot
+                : {
+                    ...(0, approver_filled_table_columns_1.readSnapshotWithoutOpenCells)(wholeFieldOptionSnapshot, openCellSchema),
+                    ...(0, approver_filled_table_columns_1.readOpenCellSnapshots)(refreshedOpenCellSnapshots, openCellSchema),
+                };
+            // ADR 27 §2: the host guard judges the decision as it will be
+            // committed, after the form checks and before anything is written.
+            // The version is read only when a guard is bound, so an engine
+            // without one issues exactly the queries it did before.
+            if (this.instanceGuard !== null) {
+                await this.guardInstanceChange({
+                    action: input.action,
+                    actorMemberId: input.decidedByMemberId,
+                    // The approver's own context when the GraphQL mutation passed one;
+                    // never the member-id stub the data-source path falls back to.
+                    authContext: options.approverAuthContext ?? null,
+                    automatic: options.automatic ?? null,
+                    changedFieldKeys,
+                    formData: mergedFormData,
+                    instance,
+                    kind: 'DECIDE',
+                    manager,
+                    node: taskNode,
+                    task,
+                    templateVersion: await this.readBoundTemplateVersionOrThrow(manager, instance),
+                });
+            }
+            const formDataChanged = settledFormData !== null && changedFieldKeys.length > 0;
+            const formDataOptionSnapshotChanged = (0, form_data_fingerprint_1.computeStableValueFingerprint)(nextFormDataOptionSnapshot) !==
+                (0, form_data_fingerprint_1.computeStableValueFingerprint)(instance.formDataOptionSnapshot ?? {});
+            if (formDataChanged) {
                 await this.assertCurrentFilterableFormDataValues(instance.templateId, mergedFormData, manager);
+            }
+            if (formDataChanged || formDataOptionSnapshotChanged) {
                 // Merged into the shared `instance` before it is signed and before
                 // the token moves on: the signature must cover the filled values, a
                 // gateway after this node must route on them, and an end node saves
-                // this same object, which would write the old values back.
+                // this same object, which would write the old values back. The
+                // refreshed option labels go in the same write.
                 const savedInstance = await instanceRepository.save({
                     ...instance,
                     formData: mergedFormData,
+                    formDataOptionSnapshot: nextFormDataOptionSnapshot,
                 });
                 Object.assign(instance, savedInstance);
             }
@@ -879,7 +1172,8 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             // (rejected / returned, or an approval that completed it), every other
             // candidate's notification is superseded too; a non-completing approval
             // on a multi-approver task leaves the remaining approvers' open.
-            const taskEnded = input.action !== workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED || shouldCompleteTask;
+            const taskEnded = input.action !== workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED ||
+                shouldCompleteTask;
             await this.notificationService.resolveTaskNotifications({
                 actingMemberId: input.decidedByMemberId,
                 manager,
@@ -930,13 +1224,13 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 return decision;
             }
             if (input.action === workflow_engine_enums_1.TaskDecisionActionEnum.RETURNED) {
-                await this.returnInstanceToNode(manager, instance, completedTask, returnToNodeId, decidedAt);
+                await this.returnInstanceToNode(manager, instance, completedTask, returnToNodeId, decidedAt, input.decidedByMemberId);
                 return decision;
             }
             if (await this.handleAdhocPreApprovalRejection(manager, instance, completedTask, decidedAt, decisionComment)) {
                 return decision;
             }
-            await this.rejectInstance(manager, instance, completedTask, decidedAt);
+            await this.rejectInstance(manager, instance, completedTask, decidedAt, input.decidedByMemberId);
             return decision;
         });
     }
@@ -970,6 +1264,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 },
                 taskId: null,
             }));
+            await this.recordInstanceEvent(manager, cancelledInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.CANCELLED, 'INSTANCE_CANCELLED', { actorMemberId: input.cancelledByMemberId });
             return cancelledInstance;
         });
     }
@@ -1007,6 +1302,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 },
                 taskId: input.taskId ?? null,
             }));
+            await this.recordInstanceEvent(manager, expiredInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.EXPIRED, 'INSTANCE_EXPIRED', {});
             return expiredInstance;
         });
     }
@@ -1036,6 +1332,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
     }
     async resubmitApprovalInstance(input, authContext) {
         const submittedFormData = parseJsonObject(input.formDataJson, 'formDataJson');
+        if (input.endUserSubmission === true) {
+            await this.assertEndUserMayResubmit(input.instanceId);
+        }
         const preparation = this.formDataSourceValueResolver
             ? await this.prepareResubmitFormDataOptions(input, submittedFormData, authContext ?? createWorkflowAuthContext(input.initiatorMemberId))
             : null;
@@ -1065,20 +1364,37 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 throw new common_1.ConflictException('Approval instance changed while options were resolving; refresh and retry');
             }
             const resubmitSchema = readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot);
-            const deferredFieldKeys = (0, bpm_core_shared_1.readApproverFilledFieldKeys)(instance.workflowSnapshot);
+            const deferral = (0, approver_filled_table_columns_1.readApproverFilledDeferral)(instance.workflowSnapshot);
             // An end user gets back the value an approver already filled in, and
             // loses a key the stored data never had: the renderer seeds `false`,
             // `[]` and empty rows for every field, none of which an approver wrote.
+            // An open cell of a table is settled per row the same way.
             const formData = input.endUserSubmission === true
-                ? (0, bpm_core_shared_1.overlayStoredFormDataKeys)(submittedFormData, instance.formData, deferredFieldKeys)
+                ? (0, approver_filled_table_columns_1.applyOpenColumnCells)((0, bpm_core_shared_1.overlayStoredFormDataKeys)(submittedFormData, instance.formData, deferral.wholeKeys), instance.formData, deferral)
                 : submittedFormData;
-            validateSubmittedFormData(resubmitSchema, formData, {
-                deferredFieldKeys,
-            });
+            validateSubmittedFormData((0, approver_filled_table_columns_1.projectOpenColumnsOptional)(resubmitSchema, deferral), formData, { deferredFieldKeys: deferral.wholeKeys });
             await this.assertCurrentFilterableFormDataValues(instance.templateId, formData, manager);
             if (!preparation) {
                 assertNoUnresolvableDynamicValues(resubmitSchema, formData);
             }
+            // ADR 27 §2: the host guard judges the resubmission as it will be
+            // committed, after every form check and before the write.
+            if (this.instanceGuard !== null) {
+                await this.guardInstanceChange({
+                    action: null,
+                    actorMemberId: input.initiatorMemberId,
+                    authContext: authContext ?? null,
+                    automatic: null,
+                    changedFieldKeys: listChangedFormDataKeys(instance.formData, formData),
+                    formData,
+                    instance,
+                    kind: 'RESUBMIT',
+                    manager,
+                    node: null,
+                    task: null,
+                    templateVersion: await this.readBoundTemplateVersionOrThrow(manager, instance),
+                });
+            }
             const resubmittedInstance = await instanceRepository.save({
                 ...instance,
                 completedAt: null,
@@ -1091,6 +1407,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 state: workflow_engine_enums_1.ApprovalInstanceStateEnum.RUNNING,
                 title: input.title?.trim() || instance.title,
             });
+            // Written before the resume below, so RESUBMITTED precedes any
+            // NODE_ACTIVATED that the resume produces in the same transaction.
+            await this.recordInstanceEvent(manager, resubmittedInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.RUNNING, 'INSTANCE_RESUBMITTED', { actorMemberId: input.initiatorMemberId });
             await this.attachmentService.bindFormDataAttachmentsToInstance(manager, {
                 formData,
                 instanceId: instance.id,
@@ -1864,11 +2183,13 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             input.workflowDefinitionJson,
             input.formDataJson,
             input.initiatorMetadataSnapshotJson ?? '',
+            input.formSchemaJson ?? '',
         ].some((json) => json.length > MAX_DRY_RUN_INPUT_LENGTH)) {
             return createFailedDryRunResult('試跑資料過大，請縮小流程或測試資料後再試');
         }
         const workflowDefinition = parseWorkflowDefinition(input.workflowDefinitionJson);
         const formData = parseJsonObject(input.formDataJson, 'formDataJson');
+        const formSchema = readDryRunFormSchema(input.formSchemaJson);
         // The snapshot here is the caller's own sample (the designer always sends
         // one) or a bare `{ customFields: {}, memberId }`. It is not the one a real
         // submission builds, and a dry run has no template version to hand the
@@ -1885,6 +2206,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             return Object.assign(new workflow_dry_run_object_1.WorkflowDryRunResultObject(), {
                 errors: [],
                 steps: (0, expression_budget_1.runExpressionOperation)(() => (0, time_budget_1.runWithinTimeBudget)(() => this.simulateWorkflow({
+                    expressionFormData: this.expressionMissingFormFieldsAsNull && formSchema
+                        ? (0, missing_form_fields_1.fillMissingFormFields)(formData, formSchema)
+                        : formData,
                     formData,
                     initiatorMemberId: input.initiatorMemberId,
                     initiatorMetadataSnapshot,
@@ -2189,6 +2513,51 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         }
         return instance;
     }
+    /**
+     * ADR 27 §4.2 (gap 1): the fill units an approver may use to resolve runtime
+     * data-source options on a RUNNING instance. Only tasks the member can act on
+     * count: the member is the assignee or a PENDING/CLAIMED candidate of a
+     * PENDING or IN_PROGRESS, non-ad-hoc task. A task whose candidate row is
+     * WAITING or already decided grants nothing, even though its status is open.
+     * A field counts only when its node lists it as SHOW; a HIDE entry never
+     * grants, whatever its fill is. Returns `[]` when the instance is not RUNNING.
+     */
+    async listApproverFillUnits(instanceId, memberId) {
+        const instance = await this.approvalInstanceRepository.findOne({
+            where: { id: instanceId },
+        });
+        if (!instance ||
+            instance.state !== workflow_engine_enums_1.ApprovalInstanceStateEnum.RUNNING) {
+            return [];
+        }
+        const tasks = await this.taskRepository.find({
+            where: {
+                instanceId,
+                isAdhoc: false,
+                status: (0, typeorm_2.In)([workflow_engine_enums_1.TaskStatusEnum.PENDING, workflow_engine_enums_1.TaskStatusEnum.IN_PROGRESS]),
+            },
+        });
+        const unitsPerTask = await Promise.all(tasks.map(async (task) => {
+            const node = instance.workflowSnapshot.nodes.find((candidate) => candidate.type === 'userTask' && candidate.id === task.nodeId);
+            if (!node) {
+                return [];
+            }
+            try {
+                await this.readTaskActorContext(this.taskRepository.manager, task, memberId);
+            }
+            catch (error) {
+                if (error instanceof common_1.ConflictException) {
+                    return [];
+                }
+                throw error;
+            }
+            const shown = new Set((0, bpm_core_shared_1.readNodeFieldAccess)(node)
+                .filter((entry) => entry.display === 'SHOW')
+                .map((entry) => entry.fieldKey));
+            return (0, bpm_core_shared_1.readNodeFillUnits)(node).filter((unit) => shown.has(unit.fieldKey));
+        }));
+        return unitsPerTask.flat();
+    }
     /**
      * ADR 25 §6: a value written to a filterable field must fit its type, on
      * every path that writes form data. The fields checked are the ones the
@@ -2274,7 +2643,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             totalPages,
         };
     }
-    async createFilteredApprovalInstanceQuery(scope, options = {}) {
+    async createFilteredApprovalInstanceQuery(scope, requested = {}) {
+        const options = await this.resolveApprovalInstanceTemplateKey(requested);
+        if (!options) {
+            return null;
+        }
         const queryBuilder = this.approvalInstanceRepository.createQueryBuilder('approvalInstance');
         const hasReadableInstances = this.applyReadableInstanceFilter(queryBuilder, scope, options);
         if (!hasReadableInstances) {
@@ -2502,9 +2875,15 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             memberId,
             submission: null,
         });
-        return templates.filter((template) => this.isInitiatorPolicyMet(template, template.currentVersionId
-            ? (versionById.get(template.currentVersionId) ?? null)
-            : null, initiatorMetadataSnapshot, 'launchable templates'));
+        return templates.filter((template) => {
+            const version = template.currentVersionId
+                ? (versionById.get(template.currentVersionId) ?? null)
+                : null;
+            // A HOST_ONLY template is started by the host's backend, never from the
+            // launch page (ADR 27 §5), so it is not offered there at all.
+            return (version?.launchMode !== template_enums_1.ApprovalTemplateLaunchModeEnum.HOST_ONLY &&
+                this.isInitiatorPolicyMet(template, version, initiatorMetadataSnapshot, 'launchable templates'));
+        });
     }
     /**
      * The published version whose form `memberId` may read data-source options
@@ -2605,7 +2984,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      * given its candidate summaries.
      */
     async listInboxTasks(assigneeMemberId, options = {}) {
-        const openTasks = await this.readSharedOpenInboxTasks(assigneeMemberId);
+        const openTasks = await this.filterTasksByTemplate(await this.readSharedOpenInboxTasks(assigneeMemberId), options);
         if (!isTaskListPaged(options)) {
             return this.attachTaskCandidateSummaries(openTasks);
         }
@@ -2613,8 +2992,77 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         return this.attachTaskCandidateSummaries(openTasks.slice(offset, offset + normalizePageSize(options.pageSize)));
     }
     /** How many tasks {@link listInboxTasks} pages through. */
-    async countInboxTasks(assigneeMemberId) {
-        return (await this.readSharedOpenInboxTasks(assigneeMemberId)).length;
+    async countInboxTasks(assigneeMemberId, filter = {}) {
+        return (await this.filterTasksByTemplate(await this.readSharedOpenInboxTasks(assigneeMemberId), filter)).length;
+    }
+    /**
+     * The template ids a {@link TaskTemplateFilter} allows, or `null` when it
+     * does not filter. A `templateKey` that names no template allows nothing.
+     */
+    async readTaskTemplateFilterIds(filter) {
+        // Trimmed, and a blank key does not filter, as on the instance list.
+        const key = normalizeText(filter.templateKey);
+        const byKey = key ? await this.readTemplateIdsByKey(key) : null;
+        if (filter.templateIds === undefined) {
+            return byKey;
+        }
+        if (byKey === null) {
+            return filter.templateIds;
+        }
+        return filter.templateIds.filter((id) => byKey.includes(id));
+    }
+    /**
+     * Turns `templateKey` into `templateId` (ADR 27 §6), or `null` when the
+     * options can match nothing: an unknown key, or a key naming another
+     * template than `templateId` does.
+     */
+    async resolveApprovalInstanceTemplateKey(options) {
+        const key = normalizeText(options.templateKey);
+        if (!key) {
+            return options;
+        }
+        const [templateId] = await this.readTemplateIdsByKey(key);
+        const requestedId = normalizeText(options.templateId);
+        if (!templateId || (requestedId && requestedId !== templateId)) {
+            return null;
+        }
+        return { ...options, templateId };
+    }
+    /**
+     * The id of the live template carrying `key`, as a list so a key that names
+     * nothing filters everything out. At most one live template holds a key.
+     */
+    async readTemplateIdsByKey(key) {
+        const template = await this.approvalTemplateRepository.findOne({
+            select: { id: true },
+            where: { key },
+        });
+        return template ? [template.id] : [];
+    }
+    /**
+     * Keeps the tasks whose instance belongs to the filter's templates. The open
+     * task read is shared with the dashboard counters, so the filter is applied
+     * to its result rather than pushed into it.
+     */
+    async filterTasksByTemplate(tasks, filter) {
+        const templateIds = await this.readTaskTemplateFilterIds(filter);
+        if (templateIds === null) {
+            return tasks;
+        }
+        if (!templateIds.length || !tasks.length) {
+            return [];
+        }
+        const instances = await this.approvalInstanceRepository.find({
+            select: { id: true },
+            where: {
+                id: (0, typeorm_2.In)([
+                    ...new Set(tasks.map((task) => task.instanceId)),
+                ]),
+                templateId: (0, typeorm_2.In)([...templateIds]),
+            },
+        });
+        const instanceIds = new Set(instances.map((instance) => instance.id));
+        return tasks.filter((task) => instanceIds.has(task.instanceId));
     }
     /**
      * {@link readOpenInboxTasks} for the inbox list and its count, joining a
@@ -2711,7 +3159,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      */
     async listApprovalHistoryTasks(assigneeMemberId, options = {}) {
         const paged = isTaskListPaged(options);
-        const tasks = await this.createApprovalHistoryTaskQuery(assigneeMemberId, options.instanceState)
+        const templateIds = await this.readTaskTemplateFilterIds(options);
+        if (templateIds?.length === 0) {
+            return [];
+        }
+        const tasks = await this.createApprovalHistoryTaskQuery(assigneeMemberId, options.instanceState, templateIds)
             .orderBy(this.readApprovalHistoryActedAtExpression(), 'DESC')
             .addOrderBy('"task"."id"', 'DESC')
             .offset(paged ? readPageOffset(options.page, options.pageSize) : 0)
@@ -2723,10 +3175,14 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
     }
     /** How many tasks {@link listApprovalHistoryTasks} pages through. */
     async countApprovalHistoryTasks(assigneeMemberId, options = {}) {
-        return this.createApprovalHistoryTaskQuery(assigneeMemberId, options.instanceState).getCount();
+        const templateIds = await this.readTaskTemplateFilterIds(options);
+        if (templateIds?.length === 0) {
+            return 0;
+        }
+        return this.createApprovalHistoryTaskQuery(assigneeMemberId, options.instanceState, templateIds).getCount();
     }
     /** The rows of {@link listApprovalHistoryTasks}, unordered and unpaged. */
-    createApprovalHistoryTaskQuery(assigneeMemberId, instanceState) {
+    createApprovalHistoryTaskQuery(assigneeMemberId, instanceState, templateIds = null) {
         const candidateTable = this.readQualifiedTableName(this.taskCandidateRepository);
         const queryBuilder = this.taskRepository
             .createQueryBuilder('task')
@@ -2759,6 +3215,16 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
           )
         `, { historyInstanceState: instanceState });
         }
+        if (templateIds) {
+            queryBuilder.andWhere(`
+          EXISTS (
+            SELECT 1
+            FROM ${this.readQualifiedTableName(this.approvalInstanceRepository)} "historyTemplateInstance"
+            WHERE "historyTemplateInstance"."id" = "task"."instance_id"
+              AND "historyTemplateInstance"."template_id" IN (:...historyTemplateIds)
+          )
+        `, { historyTemplateIds: [...templateIds] });
+        }
         return queryBuilder;
     }
     /** When the member acted on a history task; see {@link listApprovalHistoryTasks}. */
@@ -2845,7 +3311,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      * snapshot without a `nodes` array, and a blank or non-string label all
      * leave the task without a label, as `readWorkflowNodeLabel` does. Only the
      * node's `fieldAccess` leaves the database for the fill flag, which
-     * `readNodeFillableFieldKeys` then reads as tolerantly as the engine does.
+     * `readNodeFillGrantFieldKeys` then reads as tolerantly as the engine does.
      */
     async readTaskNodeSummaries(tasks) {
         // The table as the entity reads it, so a configured `schema` is honoured
@@ -2880,7 +3346,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             readNodeLabelKey(row.instanceId, row.nodeId),
             {
                 hasFillableFields: row.nodeType === 'userTask' &&
-                    (0, bpm_core_shared_1.readNodeFillableFieldKeys)({
+                    (0, bpm_core_shared_1.readNodeFillGrantFieldKeys)({
                         data: { fieldAccess: row.fieldAccess },
                     }).size > 0,
                 label: typeof row.label === 'string' && row.label.trim()
@@ -3169,6 +3635,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         });
         await this.dispatchAdhocCompletionNotifications(manager, completedInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.APPROVED);
         await this.cancelPendingAdhocDirectives(manager, instance.id, null);
+        await this.recordInstanceEvent(manager, completedInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.APPROVED, 'INSTANCE_APPROVED', {});
     }
     async isNodeEntryReady(manager, instance, token, node) {
         if (node.type === 'startEvent') {
@@ -3234,7 +3701,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
     }
     isNodeEntryConditionMet(instance, node) {
         const entryCondition = readNodeEntryCondition(node);
-        return this.conditionService.evaluateBoolean(entryCondition, buildWorkflowExpressionContext(instance), `workflow.nodes.${node.id}.data.entryCondition`, readExpressionDialectOptions(entryCondition, instance.workflowSnapshot));
+        return this.conditionService.evaluateBoolean(entryCondition, this.buildExpressionContext(instance), `workflow.nodes.${node.id}.data.entryCondition`, readExpressionDialectOptions(entryCondition, instance.workflowSnapshot));
     }
     async skipNodeByEntryCondition(manager, instance, token, node) {
         await this.skipNode(manager, instance, token, node, {
@@ -3308,7 +3775,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             });
         }
         const context = {
-            ...buildWorkflowExpressionContext(instance),
+            ...this.buildExpressionContext(instance),
             lastDecision: await this.readLastDecisionContext(manager, instance.id, node.id),
         };
         return evaluateWithStructuredFallback(edge, instance.formData, (message) => this.logger.warn(`instance=${instance.id} ${message}`), () => this.conditionService.evaluateBoolean(expression, context, `workflow.edges.${edge.id}.data.condition`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) }));
@@ -3431,6 +3898,12 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             // worse — an `endState: 'REJECTED'` row overwritten with `APPROVED`
             // immediately after it had been committed.
             const completedInstance = await instanceRepository.save(Object.assign(instance, { completedAt, state: instanceState }));
+            if (instanceState === workflow_engine_enums_1.ApprovalInstanceStateEnum.REJECTED) {
+                await this.recordInstanceEvent(manager, completedInstance, instanceState, 'INSTANCE_REJECTED', { actorMemberId: null });
+            }
+            else {
+                await this.recordInstanceEvent(manager, completedInstance, instanceState, 'INSTANCE_APPROVED', {});
+            }
             if (instanceState === workflow_engine_enums_1.ApprovalInstanceStateEnum.APPROVED) {
                 await this.notificationService.createInstanceCompletedNotification({
                     instance: completedInstance,
@@ -3532,7 +4005,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         const singleCandidate = savedCandidates.length === 1 ? savedCandidates[0] : null;
         const openCandidates = savedCandidates.filter((candidate) => candidate.status === workflow_engine_enums_1.TaskCandidateStatusEnum.PENDING);
         task.openCandidateMemberIds = openCandidates.map((candidate) => candidate.memberId);
-        task.hasFillableFields = (0, bpm_core_shared_1.readNodeFillableFieldKeys)(node).size > 0;
+        task.hasFillableFields = (0, bpm_core_shared_1.readNodeFillGrantFieldKeys)(node).size > 0;
         await tokenRepository.save({
             ...token,
             status: workflow_engine_enums_1.WorkflowTokenStatusEnum.WAITING,
@@ -3559,6 +4032,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             },
             taskId: task.id,
         }));
+        await this.recordInstanceEvent(manager, instance, instance.state, 'NODE_ACTIVATED', { nodeId: node.id, taskIds: [task.id] });
         await openCandidates.reduce(async (previous, candidate) => {
             await previous;
             await this.notificationService.createTaskAssignedNotification({
@@ -4618,9 +5092,22 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             skippedDelegations: collectSkippedDelegations(delegatedCandidates, true, replacementExcludedMemberIds),
         };
     }
+    /**
+     * The context workflow expressions on `instance` read. Its `form` is the
+     * stored data, or with `expressionMissingFormFieldsAsNull` on, a copy with
+     * every unfilled top-level field present (ADR 27 §3).
+     */
+    buildExpressionContext(instance) {
+        return buildWorkflowExpressionContext(instance, this.readExpressionFormData(instance));
+    }
+    readExpressionFormData(instance) {
+        return this.expressionMissingFormFieldsAsNull
+            ? (0, missing_form_fields_1.fillMissingFormFields)(instance.formData, readFormDefinitionSnapshotSchema(instance.formDefinitionSnapshot))
+            : instance.formData;
+    }
     buildDelegationContext(instance, nodeId) {
         return {
-            formData: instance.formData,
+            formData: this.readExpressionFormData(instance),
             initiatorMemberId: instance.initiatorMemberId,
             initiatorMetadataSnapshot: instance.initiatorMetadataSnapshot,
             instanceId: instance.id,
@@ -4714,7 +5201,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             return readMemberIdsFromValue(readValueAtPath(instance.formData, resolver.formPath), label, subject, `依表單欄位「${resolver.formPath}」`);
         }
         if (resolver.type === 'EXPRESSION') {
-            return readMemberIdsFromValue(this.conditionService.evaluateValue(resolver.expression, buildWorkflowExpressionContext(instance), `${label}.expression`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) }), label, subject, '依運算式');
+            return readMemberIdsFromValue(this.conditionService.evaluateValue(resolver.expression, this.buildExpressionContext(instance), `${label}.expression`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) }), label, subject, '依運算式');
         }
         if (resolver.type === 'POSITION') {
             return this.resolvePositionCandidates(manager, resolver.positionId, label, subject);
@@ -4844,7 +5331,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
      */
     async readNodeActorApprovals(manager, instance, nodeIds) {
         const tasks = await manager.getRepository(task_entity_1.TaskEntity).find({
-            where: { instanceId: instance.id, isAdhoc: false, nodeId: (0, typeorm_2.In)([...nodeIds]) },
+            where: {
+                instanceId: instance.id,
+                isAdhoc: false,
+                nodeId: (0, typeorm_2.In)([...nodeIds]),
+            },
         });
         if (tasks.length === 0) {
             return [];
@@ -4860,7 +5351,10 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         }
         const [decisions, decidedLogs] = await Promise.all([
             manager.getRepository(task_decision_entity_1.TaskDecisionEntity).find({
-                where: { action: workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED, taskId: (0, typeorm_2.In)(batchTaskIds) },
+                where: {
+                    action: workflow_engine_enums_1.TaskDecisionActionEnum.APPROVED,
+                    taskId: (0, typeorm_2.In)(batchTaskIds),
+                },
             }),
             manager.getRepository(activity_log_entity_1.ActivityLogEntity).find({
                 where: {
@@ -5322,11 +5816,11 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         const action = node.data.action;
         if (action.type === 'WEBHOOK') {
             const payload = typeof action.payload === 'string' && action.payload.trim()
-                ? this.conditionService.evaluateValue(action.payload, buildWorkflowExpressionContext(instance), `workflow.nodes.${node.id}.data.action.payload`, {
+                ? this.conditionService.evaluateValue(action.payload, this.buildExpressionContext(instance), `workflow.nodes.${node.id}.data.action.payload`, {
                     dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot),
                 })
                 : {
-                    instance: buildWorkflowExpressionContext(instance).instance,
+                    instance: this.buildExpressionContext(instance).instance,
                     triggeredAt: new Date().toISOString(),
                 };
             await this.dispatchWebhookAfterCommit(manager, {
@@ -5354,7 +5848,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             return;
         }
         if (action.type === 'SET_FORM_FIELD') {
-            const value = this.conditionService.evaluateValue(action.value, buildWorkflowExpressionContext(instance), `workflow.nodes.${node.id}.data.action.value`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) });
+            const value = this.conditionService.evaluateValue(action.value, this.buildExpressionContext(instance), `workflow.nodes.${node.id}.data.action.value`, { dialect: (0, expression_dialect_1.readWorkflowExpressionDialect)(instance.workflowSnapshot) });
             assertServiceTaskFieldValue(instance.formDefinitionSnapshot, action.fieldPath, value, node.data.label);
             const updatedFormData = writeValueAtPath(instance.formData, action.fieldPath, value);
             await this.assertCurrentFilterableFormDataValues(instance.templateId, updatedFormData, manager, node.data.label);
@@ -5416,8 +5910,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
         // §3.5). Without the webhook module there is nothing to queue into; the
         // publish lint already refuses a template that references an endpoint
         // in that case.
-        const webhookDeliveryIds = this.webhookDeliveryService &&
-            (0, workflow_graph_1.readNotifyWebhookTargets)(action).length > 0
+        const webhookDeliveryIds = this.webhookDeliveryService && (0, workflow_graph_1.readNotifyWebhookTargets)(action).length > 0
             ? await this.webhookDeliveryService.enqueueNotifyWebhooks(manager, {
                 instance: {
                     formData: instance.formData,
@@ -5447,7 +5940,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             taskId: null,
         }));
     }
-    async rejectInstance(manager, instance, task, rejectedAt) {
+    async rejectInstance(manager, instance, task, rejectedAt, decidedByMemberId) {
         const instanceRepository = manager.getRepository(approval_instance_entity_1.ApprovalInstanceEntity);
         // Dispatch pending ad-hoc notifications for the rejecting node before the
         // remaining directives are cancelled by the terminal cleanup below.
@@ -5478,8 +5971,9 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
             },
             taskId: task.id,
         }));
+        await this.recordInstanceEvent(manager, rejectedInstance, workflow_engine_enums_1.ApprovalInstanceStateEnum.REJECTED, 'INSTANCE_REJECTED', { actorMemberId: decidedByMemberId });
     }
-    async returnInstanceToNode(manager, instance, task, returnToNodeId, returnedAt) {
+    async returnInstanceToNode(manager, instance, task, returnToNodeId, returnedAt, decidedByMemberId) {
         if (!returnToNodeId) {
             throw new common_1.ConflictException('Return target node is required');
         }
@@ -5537,6 +6031,7 @@ let WorkflowEngineService = WorkflowEngineService_1 = class WorkflowEngineServic
                 taskId: null,
             }),
         ]);
+        await this.recordInstanceEvent(manager, returnedInstance, returnedInstance.state, 'INSTANCE_RETURNED', { actorMemberId: decidedByMemberId, nodeId: task.nodeId });
         if (returnedInstance.state === workflow_engine_enums_1.ApprovalInstanceStateEnum.RUNNING) {
             await this.processRunningInstance(manager, returnedInstance);
         }
@@ -5738,6 +6233,9 @@ exports.WorkflowEngineService = WorkflowEngineService = WorkflowEngineService_1
     tslib_1.__param(20, (0, common_1.Optional)()),
     tslib_1.__param(21, (0, common_1.Optional)()),
     tslib_1.__param(21, (0, common_1.Inject)(initiator_custom_fields_resolver_token_1.BPM_INITIATOR_CUSTOM_FIELDS_RESOLVER)),
+    tslib_1.__param(22, (0, common_1.Optional)()),
+    tslib_1.__param(22, (0, common_1.Inject)(instance_guard_token_1.BPM_INSTANCE_GUARD)),
+    tslib_1.__param(23, (0, common_1.Optional)()),
     tslib_1.__metadata("design:paramtypes", [typeorm_2.Repository,
         typeorm_2.Repository,
         typeorm_2.Repository,
@@ -5754,7 +6252,7 @@ exports.WorkflowEngineService = WorkflowEngineService = WorkflowEngineService_1
         delegation_service_1.DelegationService,
         notification_service_1.NotificationService,
         signature_service_1.SignatureService,
-        sla_schedule_service_1.BPMSlaScheduleService, Object, Object, Object, workflow_webhook_delivery_service_1.WorkflowWebhookDeliveryService, Object])
+        sla_schedule_service_1.BPMSlaScheduleService, Object, Object, Object, workflow_webhook_delivery_service_1.WorkflowWebhookDeliveryService, Object, Object, instance_event_writer_1.InstanceEventWriter])
 ], WorkflowEngineService);
 function parseJsonObject(value, label) {
     try {
@@ -5777,6 +6275,67 @@ function readDefaultInitiatorMetadataSnapshot(memberId) {
         memberId,
     };
 }
+/**
+ * The form schema a dry run was given to fill unfilled fields with (ADR 27
+ * §3), or `null` when it was given none. A schema that does not parse is a
+ * 400, like the other inputs.
+ */
+function readDryRunFormSchema(json) {
+    if (!json) {
+        return null;
+    }
+    const schema = parseJsonObject(json, 'formSchemaJson');
+    if (!isFormDefinitionSchema(schema)) {
+        throw new common_1.BadRequestException('formSchemaJson is not a form schema');
+    }
+    return schema;
+}
+/**
+ * Refuses a submission or resubmission through GraphQL on a `HOST_ONLY`
+ * version (ADR 27 §5). Only the host's backend, calling the service, may start
+ * or resubmit such a case.
+ */
+function assertEndUserMayLaunch(version) {
+    if (version.launchMode === template_enums_1.ApprovalTemplateLaunchModeEnum.HOST_ONLY) {
+        throw new common_1.ForbiddenException('This approval template can only be submitted by the host system');
+    }
+}
+/**
+ * Reads the service-only `initiatorCustomFields` of a submission (ADR 27 §5):
+ * `null` when absent, otherwise a JSON copy. Refused with 400 when it is not a
+ * plain object or comes together with a whole `initiatorMetadataSnapshotJson`,
+ * which would leave it unclear which one decides.
+ */
+function readHostInitiatorCustomFields(input) {
+    const fields = input.initiatorCustomFields;
+    if (fields === undefined || fields === null) {
+        return null;
+    }
+    if (input.initiatorMetadataSnapshotJson) {
+        throw new common_1.BadRequestException('initiatorCustomFields cannot be combined with initiatorMetadataSnapshotJson');
+    }
+    if (typeof fields !== 'object' || Array.isArray(fields)) {
+        throw new common_1.BadRequestException('initiatorCustomFields must be an object');
+    }
+    return cloneJsonObject(fields);
+}
+/**
+ * Lays the host's `initiatorCustomFields` over the `customFields` of a built
+ * snapshot; a key the host gave wins over the resolver's.
+ */
+function mergeHostInitiatorCustomFields(snapshot, hostCustomFields) {
+    if (hostCustomFields === null) {
+        return snapshot;
+    }
+    const current = snapshot['customFields'];
+    return {
+        ...snapshot,
+        customFields: {
+            ...(isRecord(current) ? current : {}),
+            ...hostCustomFields,
+        },
+    };
+}
 function cloneJsonObject(value) {
     return JSON.parse(JSON.stringify(value));
 }
@@ -5861,7 +6420,8 @@ function createWorkflowAuthContext(memberId) {
     };
 }
 function isSameApprovalInstanceRevision(left, right) {
-    return (readApprovalInstanceRevision(left) === readApprovalInstanceRevision(right) &&
+    return (readApprovalInstanceRevision(left) ===
+        readApprovalInstanceRevision(right) &&
         JSON.stringify(left.formData) === JSON.stringify(right.formData));
 }
 /**
@@ -5891,7 +6451,9 @@ function readDataSourceFieldKeyAtPath(snapshot, fieldPath) {
     // A corrupt snapshot can hold non-object entries: read them defensively
     // rather than letting a service task throw.
     const field = schema.fields.find((candidate) => isRecord(candidate) && candidate.fieldKey === fieldKey);
-    return field && (0, form_1.isFormDataSourceFieldDefinition)(field) ? field.fieldKey : null;
+    return field && (0, form_1.isFormDataSourceFieldDefinition)(field)
+        ? field.fieldKey
+        : null;
 }
 /**
  * Refuses form data whose filterable fields hold a value of the wrong type
@@ -5979,6 +6541,13 @@ function assertServiceTaskFieldValue(snapshot, fieldPath, value, nodeLabel) {
 function readSnapshotWithoutField(snapshots, fieldKey) {
     return Object.fromEntries(Object.entries(snapshots ?? {}).filter(([key]) => key !== fieldKey));
 }
+/**
+ * Drops every snapshot that belongs to one of the fields, table cells included
+ * (`items[0].col` belongs to `items`).
+ */
+function readSnapshotWithoutFields(snapshots, fieldKeys) {
+    return Object.fromEntries(Object.entries(snapshots ?? {}).filter(([key]) => !fieldKeys.has((0, bpm_core_shared_1.readTopLevelFieldKey)(key))));
+}
 /**
  * Keeps only the snapshots whose field still carries a value, so clearing a
  * dynamic option also removes the label recorded for it.
@@ -6056,13 +6625,13 @@ function buildInitiatorPolicyContext(initiatorMetadataSnapshot) {
         subject: initiatorMetadataSnapshot,
     };
 }
-function buildWorkflowExpressionContext(instance) {
+function buildWorkflowExpressionContext(instance, formData) {
     return {
         env: {
             now: new Date().toISOString(),
         },
-        form: instance.formData,
-        formData: instance.formData,
+        form: formData,
+        formData,
         initiator: {
             ...instance.initiatorMetadataSnapshot,
             memberId: instance.initiatorMemberId,
@@ -6106,8 +6675,8 @@ function buildDryRunExpressionContext(input, lastDecision) {
         env: {
             now: new Date().toISOString(),
         },
-        form: input.formData,
-        formData: input.formData,
+        form: input.expressionFormData,
+        formData: input.expressionFormData,
         initiator: {
             ...input.initiatorMetadataSnapshot,
             memberId: input.initiatorMemberId,
@@ -6263,8 +6832,7 @@ function readDefaultReturnTargetNodeId(workflow, currentNode) {
 }
 function isReturnCommentRequired(workflow, nodeId) {
     const node = readWorkflowNodeOrThrow(workflow, nodeId);
-    return (node.type === 'userTask' &&
-        node.data.returnBehavior.requireComment === true);
+    return (node.type === 'userTask' && node.data.returnBehavior.requireComment === true);
 }
 function readReturnResubmitStrategy(task, instance) {
     const node = readWorkflowNodeOrThrow(instance.workflowSnapshot, task.nodeId);
@@ -6843,9 +7411,7 @@ function readAdhocTargetValue(directive) {
         webhookHeaders: isRecord(value.webhookHeaders)
             ? Object.entries(value.webhookHeaders).reduce((accumulator, [key, headerValue]) => ({
                 ...accumulator,
-                ...(typeof headerValue === 'string'
-                    ? { [key]: headerValue }
-                    : {}),
+                ...(typeof headerValue === 'string' ? { [key]: headerValue } : {}),
             }), {})
             : undefined,
         webhookUrl: typeof value.webhookUrl === 'string' ? value.webhookUrl : '',
@@ -6961,10 +7527,7 @@ function compareManagerResolution(left, right, orgUnitDepths) {
     return right.effectiveFrom.localeCompare(left.effectiveFrom);
 }
 function readOrgUnitDepthMap(orgUnits) {
-    return new Map(orgUnits.map((orgUnit) => [
-        orgUnit.id,
-        orgUnit.path.split('.').length,
-    ]));
+    return new Map(orgUnits.map((orgUnit) => [orgUnit.id, orgUnit.path.split('.').length]));
 }
 function readManagerResolutionScopeRank(scopeType) {
     const ranks = {
@@ -7303,7 +7866,9 @@ function readTableMinRows(field) {
     return typeof field.minRows === 'number' ? field.minRows : 0;
 }
 function readTableMaxRows(field) {
-    return typeof field.maxRows === 'number' ? field.maxRows : form_1.FORM_TABLE_MAX_ROWS;
+    return typeof field.maxRows === 'number'
+        ? field.maxRows
+        : form_1.FORM_TABLE_MAX_ROWS;
 }
 function readTableRequiredRowCount(field) {
     return Math.max(readTableMinRows(field), 1);
@@ -7663,4 +8228,17 @@ function throwBusinessKeyConflictOrRethrow(error, businessKey) {
     }
     throw error;
 }
+/**
+ * The keys whose value differs between the stored form data and the data a
+ * resubmission replaces it with, sorted. A key present on only one side counts.
+ */
+function listChangedFormDataKeys(previous, next) {
+    const keys = new Set([...Object.keys(previous), ...Object.keys(next)]);
+    return [...keys]
+        .filter((fieldKey) => Object.prototype.hasOwnProperty.call(previous, fieldKey) !==
+        Object.prototype.hasOwnProperty.call(next, fieldKey) ||
+        (0, form_data_fingerprint_1.computeStableValueFingerprint)(previous[fieldKey]) !==
+            (0, form_data_fingerprint_1.computeStableValueFingerprint)(next[fieldKey]))
+        .sort();
+}
 //# sourceMappingURL=workflow-engine.service.js.map