@gadmin2n/schematics 0.0.143 → 0.0.145

package/dist/lib/application/files/gadmin2-game-angle-demo/server/src/modules/humanApproval/human-approval.service.ts

@@ -1,6 +1,7 @@
 import { HttpStatus, Injectable, Optional } from '@nestjs/common';
 import { Prisma } from '@prisma/client';
 import { PrismaService } from 'nestjs-prisma';
+import { executeCode } from '../codeRuntime/code-executor';
 import { ExternalInteractionService } from '../externalInteraction/external-interaction.service';
 import type { ExternalResultInput } from '../externalInteraction/external-interaction.types';
 import { SubjectProviderRegistry } from '../subjectProvider/subject-provider.registry';
@@ -15,7 +16,6 @@ import {
   ApprovalConfigSnapshotDto,
   StartApprovalRequestDto,
   SubmitApprovalDecisionDto,
-  SubmitExternalApprovalDecisionDto,
 } from './human-approval.dto';
 import { HumanApprovalDomainError } from './human-approval.errors';
 
@@ -42,48 +42,11 @@ export class HumanApprovalService {
       );
     }
 
-    const existing = await this.prisma.approvalRequest.findUnique({
-      where: {
-        workflowInstanceId_nodeId: { workflowInstanceId, nodeId: input.nodeId },
-      },
-      include: { candidates: true },
-    });
-
-    const approvalWorkflowId = input.configSnapshot.approvalWorkflowId?.trim();
-    let approvalWorkflow: { isEnabled: boolean; status: string } | null = null;
-    if (approvalWorkflowId) {
-      approvalWorkflow = await this.prisma.workflow.findUnique({
-        where: { id: toBigInt(approvalWorkflowId) },
-        select: { isEnabled: true, status: true },
-      });
-      if (
-        !approvalWorkflow?.isEnabled ||
-        approvalWorkflow.status !== 'PUBLISHED'
-      )
-        throw approvalError(
-          'APPROVAL_CONFIG_MISMATCH',
-          `Approval Workflow ${approvalWorkflowId} was not found, published, or enabled`,
-          HttpStatus.BAD_REQUEST,
-        );
-    }
-
-    if (existing) {
-      return attachApprovalWorkflowInvocation(
-        existing,
-        existing.candidates,
-        approvalWorkflowId,
-        input,
-      );
-    }
-
     let materializedSubjects;
     try {
-      materializedSubjects = mergeSubjectSources(
-        materializeApprovalSubjects(
-          input.configSnapshot.subjects as unknown as ApprovalSubjectSource[],
-          input.dynamicInputs,
-        ),
-        input.resolvedSubjects ?? [],
+      materializedSubjects = materializeApprovalSubjects(
+        input.configSnapshot.subjects as unknown as ApprovalSubjectSource[],
+        input.dynamicInputs,
       );
     } catch (error) {
       throw approvalError(
@@ -93,24 +56,62 @@ export class HumanApprovalService {
       );
     }
     const resolved = await this.resolveSubjects(materializedSubjects, actor);
-    const startedAt = new Date();
-    const expiresAt =
-      input.configSnapshot.timeout.durationSeconds > 0
-        ? new Date(
-            startedAt.getTime() +
-              input.configSnapshot.timeout.durationSeconds * 1000,
-          )
-        : null;
-    const blocked = resolved.candidates.length === 0;
-
+    const requestHash = approvalRequestHash(input, resolved);
     return this.prisma.$transaction(async (tx) => {
+      assertWorkflowAcceptsApproval(
+        await lockWorkflowInstance(tx, workflowInstanceId),
+      );
+      const existing = await tx.approvalRequest.findUnique({
+        where: {
+          workflowInstanceId_nodeId: {
+            workflowInstanceId,
+            nodeId: input.nodeId,
+          },
+        },
+        include: {
+          candidates: true,
+          signalOutboxes: { orderBy: { id: 'desc' }, take: 1 },
+        },
+      });
+      if (existing) {
+        if (existing.requestHash !== requestHash)
+          throw approvalError(
+            'APPROVAL_CONFIG_MISMATCH',
+            'Approval request data changed during an idempotent retry',
+            HttpStatus.CONFLICT,
+          );
+        return attachCompletedResolution(
+          attachExternalApproval(existing, existing.candidates, input),
+        );
+      }
+
+      const reusable = await this.findCompletedRetryApproval(tx, {
+        workflowInstanceId,
+        workflowVersionId,
+        nodeId: input.nodeId,
+        configHash: input.configHash,
+        requestHash,
+      });
+      if (reusable) return attachCompletedResolution(reusable);
+
+      const startedAt = new Date();
+      const expiresAt =
+        input.configSnapshot.timeout.durationSeconds > 0
+          ? new Date(
+              startedAt.getTime() +
+                input.configSnapshot.timeout.durationSeconds * 1000,
+            )
+          : null;
+      const blocked = resolved.candidates.length === 0;
       const request = await tx.approvalRequest.create({
         data: {
           workflowInstanceId,
           nodeId: input.nodeId,
           workflowVersionId,
           configHash: input.configHash,
+          requestHash,
           configSnapshot: snapshot as Prisma.InputJsonValue,
+          task: input.task as unknown as Prisma.InputJsonValue,
           approvalRule: input.configSnapshot
             .approvalRule as unknown as Prisma.InputJsonValue,
           rejectionRule: input.configSnapshot
@@ -126,43 +127,100 @@ export class HumanApprovalService {
           subjects: { create: resolved.subjects },
           candidates: { create: resolved.candidates },
         },
+        include: { candidates: true },
       });
-      if (approvalWorkflowId && !blocked) {
+      if (input.configSnapshot.external && !blocked) {
         if (
-          !this.externalInteractions ||
-          !input.tenantNamespace ||
-          !input.approvalWorkflowRunId ||
           !input.callbackToken ||
-          !approvalWorkflow
+          !input.callbackUrl ||
+          !input.tenantNamespace ||
+          !input.temporalRunId
         )
           throw approvalError(
             'APPROVAL_CONFIG_MISMATCH',
             'External approval callback runtime is not configured',
             HttpStatus.BAD_REQUEST,
           );
-        const interaction =
-          await this.externalInteractions.createInteractionInTransaction(
-            {
-              callbackToken: input.callbackToken,
-              tenantNamespace: input.tenantNamespace,
-              handlerType: 'EXTERNAL_WAIT',
-              handlerConfig: { allowedOutcomes: ['RECEIVED'] },
-              workflowInstanceId: String(workflowInstanceId),
-              workflowVersionId: String(workflowVersionId),
-              temporalRunId: input.approvalWorkflowRunId,
-              nodeId: input.nodeId,
-              ...(expiresAt && { expiresAt: expiresAt.toISOString() }),
-            },
-            tx,
+        if (!this.externalInteractions)
+          throw approvalError(
+            'APPROVAL_CONFIG_MISMATCH',
+            'External approval callback runtime is unavailable',
+            HttpStatus.BAD_REQUEST,
           );
-        return attachApprovalWorkflowInvocation(
-          request,
-          resolved.candidates,
-          approvalWorkflowId,
-          { ...input, callbackToken: interaction.callbackToken },
+        await this.externalInteractions.createInteractionInTransaction(
+          {
+            callbackToken: input.callbackToken,
+            tenantNamespace: input.tenantNamespace,
+            handlerType: 'HUMAN_APPROVAL',
+            handlerConfig: {
+              approvalRequestId: String(request.id),
+              input: input.input,
+              callbackUrl: input.callbackUrl,
+            },
+            workflowInstanceId: String(workflowInstanceId),
+            workflowVersionId: String(workflowVersionId),
+            temporalRunId: input.temporalRunId,
+            nodeId: input.nodeId,
+            ...(expiresAt && { expiresAt: expiresAt.toISOString() }),
+          },
+          tx,
         );
       }
-      return request;
+      return attachExternalApproval(request, request.candidates, input);
+    });
+  }
+
+  private async findCompletedRetryApproval(
+    tx: Prisma.TransactionClient,
+    input: {
+      workflowInstanceId: bigint;
+      workflowVersionId: bigint;
+      nodeId: string;
+      configHash: string;
+      requestHash: string;
+    },
+  ) {
+    const current = await tx.workflowInstance.findUnique({
+      where: { id: input.workflowInstanceId },
+      select: { id: true, workflowId: true, versionId: true, context: true },
+    });
+    if (!current || current.versionId !== input.workflowVersionId) return null;
+
+    const operationScopeId = readOperationScopeId(current.context, current.id);
+    const instanceFilters: any[] = [
+      {
+        context: {
+          path: ['system', 'operationScopeId'],
+          equals: operationScopeId,
+        },
+      },
+    ];
+    if (/^[1-9][0-9]*$/.test(operationScopeId))
+      instanceFilters.unshift({ id: BigInt(operationScopeId) });
+    const instances = await tx.workflowInstance.findMany({
+      where: {
+        workflowId: current.workflowId,
+        versionId: input.workflowVersionId,
+        OR: instanceFilters,
+      },
+      select: { id: true },
+    });
+    if (!instances.length) return null;
+
+    return tx.approvalRequest.findFirst({
+      where: {
+        workflowInstanceId: { in: instances.map(({ id }) => id) },
+        workflowVersionId: input.workflowVersionId,
+        nodeId: input.nodeId,
+        configHash: input.configHash,
+        requestHash: input.requestHash,
+        status: { in: ['APPROVED', 'REJECTED'] },
+      },
+      orderBy: { completedAt: 'desc' },
+      include: {
+        candidates: true,
+        signalOutboxes: { orderBy: { id: 'desc' }, take: 1 },
+      },
     });
   }
 
@@ -172,6 +230,10 @@ export class HumanApprovalService {
     actor: ActorContext,
   ) {
     return this.prisma.$transaction(async (tx) => {
+      assertWorkflowAcceptsApproval(
+        await lockWorkflowForApprovalRequest(tx, requestId),
+      );
+      await lockApprovalRequest(tx, requestId);
       const request = await tx.approvalRequest.findUnique({
         where: { id: requestId },
         include: {
@@ -205,71 +267,17 @@ export class HumanApprovalService {
     });
   }
 
-  async submitExternalDecision(
-    requestId: bigint,
-    input: SubmitExternalApprovalDecisionDto,
-  ) {
-    return this.prisma.$transaction(async (tx) => {
-      const request = await tx.approvalRequest.findUnique({
-        where: { id: requestId },
-        include: {
-          candidates: true,
-          decisions: { include: { candidate: true } },
-        },
-      });
-      if (!request) throw notFound(requestId);
-
-      const snapshot = asObject(request.configSnapshot);
-      if (snapshot.approvalWorkflowId !== input.approvalWorkflowId)
-        throw approvalError(
-          'APPROVAL_WORKFLOW_MISMATCH',
-          'Result Workflow does not match the Workflow selected by this approval request',
-          HttpStatus.FORBIDDEN,
-        );
-
-      const candidate = request.candidates.find(
-        (item) =>
-          item.invalidatedAt === null && item.principalRef === input.approverId,
-      );
-      if (!candidate)
-        throw approvalError(
-          'APPROVAL_NOT_CANDIDATE',
-          'External approver is not an active approval candidate',
-          HttpStatus.FORBIDDEN,
-        );
-
-      return this.recordDecision(
-        tx,
-        request,
-        candidate,
-        input,
-        `external:${input.approvalWorkflowId}:${input.approverId}`,
-        {
-          ...(input.payload ?? {}),
-          externalEventId: input.eventId,
-          approvalWorkflowId: input.approvalWorkflowId,
-        },
-      );
-    });
-  }
-
   async handleExternalInteractionDecision(
     tx: any,
     requestId: bigint,
     input: ExternalResultInput,
+    nodeInput: unknown,
+    callbackUrl?: string,
   ): Promise<'PENDING' | 'APPROVED' | 'REJECTED'> {
-    if (input.outcome !== 'APPROVE' && input.outcome !== 'REJECT')
-      throw approvalError(
-        'APPROVAL_CONFIG_MISMATCH',
-        'External approval outcome must be APPROVE or REJECT',
-        HttpStatus.BAD_REQUEST,
-      );
-    if (!input.operatorId)
-      throw approvalError(
-        'APPROVAL_NOT_CANDIDATE',
-        'External approval requires an operator',
-        HttpStatus.FORBIDDEN,
-      );
+    assertWorkflowAcceptsApproval(
+      await lockWorkflowForApprovalRequest(tx, requestId),
+    );
+    await lockApprovalRequest(tx, requestId);
     const request = await tx.approvalRequest.findUnique({
       where: { id: requestId },
       include: {
@@ -278,9 +286,70 @@ export class HumanApprovalService {
       },
     });
     if (!request) throw notFound(requestId);
+    const workflowInstance = await tx.workflowInstance.findUnique({
+      where: { id: request.workflowInstanceId },
+      select: { context: true },
+    });
+    if (!workflowInstance)
+      throw approvalError(
+        'APPROVAL_CONFIG_MISMATCH',
+        'Workflow instance context is unavailable',
+        HttpStatus.BAD_REQUEST,
+      );
+    const snapshot = request.configSnapshot as any;
+    const callbackConfig = snapshot.external?.callbackResult;
+    if (typeof callbackConfig?.script !== 'string')
+      throw approvalError(
+        'APPROVAL_CONFIG_MISMATCH',
+        'External approval callback configuration is invalid',
+        HttpStatus.BAD_REQUEST,
+      );
+    const normalized = asObject(
+      await executeCode(
+        callbackConfig,
+        nodeInput,
+        asObject(asObject(workflowInstance.context).workflow),
+        {
+          approval: {
+            requestId: String(request.id),
+            callbackToken: input.callbackToken,
+            ...(callbackUrl && { callbackUrl }),
+            expiresAt:
+              request.expiresAt instanceof Date
+                ? request.expiresAt.toISOString()
+                : request.expiresAt ?? null,
+            task: request.task,
+            candidates: request.candidates.map((candidate) => ({
+              approverId: candidate.principalRef,
+              displayName: candidate.displayName,
+            })),
+          },
+          callback: {
+            body: asObject(input.data).callback,
+            eventId: input.eventId,
+            outcome: input.outcome,
+            ...(input.operatorId && { operatorId: input.operatorId }),
+            ...(input.data && { data: input.data }),
+          },
+        },
+      ),
+    );
+    if (!['APPROVED', 'REJECTED'].includes(String(normalized.result)))
+      throw approvalError(
+        'APPROVAL_CONFIG_MISMATCH',
+        'External approval callback result must be APPROVED or REJECTED',
+        HttpStatus.BAD_REQUEST,
+      );
+    const operatorId = stringValue(normalized.operatorId);
+    const eventId = stringValue(normalized.eventId);
+    if (!operatorId || !eventId)
+      throw approvalError(
+        'APPROVAL_CONFIG_MISMATCH',
+        'External approval callback result requires eventId and operatorId',
+        HttpStatus.BAD_REQUEST,
+      );
     const candidate = request.candidates.find(
-      (item) =>
-        item.invalidatedAt === null && item.principalRef === input.operatorId,
+      (item) => item.invalidatedAt === null && item.principalRef === operatorId,
     );
     if (!candidate)
       throw approvalError(
@@ -288,20 +357,30 @@ export class HumanApprovalService {
         'External approver is not an active approval candidate',
         HttpStatus.FORBIDDEN,
       );
-    const data = asObject(input.data);
+    if (
+      normalized.data !== undefined &&
+      (!normalized.data ||
+        typeof normalized.data !== 'object' ||
+        Array.isArray(normalized.data))
+    )
+      throw approvalError(
+        'APPROVAL_CONFIG_MISMATCH',
+        'External approval callback data must be a JSON object',
+        HttpStatus.BAD_REQUEST,
+      );
+    const data = asObject(normalized.data);
     const result = await this.recordDecision(
       tx,
       request,
       candidate,
       {
-        decision: input.outcome,
-        ...(typeof data.comment === 'string' && { comment: data.comment }),
-      },
-      `external-token:${input.operatorId}`,
-      {
-        ...data,
-        externalEventId: input.eventId,
+        decision: normalized.result === 'APPROVED' ? 'APPROVE' : 'REJECT',
+        ...(typeof normalized.comment === 'string' && {
+          comment: normalized.comment,
+        }),
       },
+      `external-token:${operatorId}`,
+      { ...data, externalEventId: eventId },
       false,
     );
     return result.status;
@@ -366,8 +445,11 @@ export class HumanApprovalService {
         where: { id: request.id, status: 'PENDING' },
         data: { status, completedAt: new Date() },
       });
-      if (changed.count === 1 && createSignalOutbox)
-        await this.createSignal(tx, request, status, 'RULE_SATISFIED');
+      if (changed.count === 1) {
+        await blockCancellationAfterResolution(tx, request);
+        if (createSignalOutbox)
+          await this.createSignal(tx, request, status, 'RULE_SATISFIED');
+      }
     }
     return {
       decision,
@@ -378,8 +460,13 @@ export class HumanApprovalService {
     };
   }
 
-  cancelRequest(requestId: bigint) {
-    return this.finishPending(requestId, 'CANCELLED', 'WORKFLOW_CANCELLED');
+  cancelRequest(requestId: bigint, createSignalOutbox = true) {
+    return this.finishPending(
+      requestId,
+      'CANCELLED',
+      'WORKFLOW_CANCELLED',
+      createSignalOutbox,
+    );
   }
 
   async expireRequest(requestId: bigint) {
@@ -413,10 +500,7 @@ export class HumanApprovalService {
       },
       orderBy: { activeFrom: 'desc' },
     });
-    return items.filter(
-      (item) =>
-        !stringValue(asObject(item.request.configSnapshot).approvalWorkflowId),
-    );
+    return items;
   }
 
   async status(requestId: bigint) {
@@ -441,8 +525,12 @@ export class HumanApprovalService {
     requestId: bigint,
     status: SignalResult,
     reason: SignalReason,
+    createSignalOutbox = true,
   ) {
     return this.prisma.$transaction(async (tx) => {
+      const workflow = await lockWorkflowForApprovalRequest(tx, requestId);
+      if (status !== 'CANCELLED') assertWorkflowAcceptsApproval(workflow);
+      await lockApprovalRequest(tx, requestId);
       const request = await tx.approvalRequest.findUnique({
         where: { id: requestId },
       });
@@ -452,8 +540,12 @@ export class HumanApprovalService {
         where: { id: requestId, status: 'PENDING' },
         data: { status, completedAt: new Date() },
       });
-      if (changed.count === 1)
-        await this.createSignal(tx, request, status, reason);
+      if (changed.count === 1) {
+        if (status === 'APPROVED' || status === 'REJECTED')
+          await blockCancellationAfterResolution(tx, request);
+        if (createSignalOutbox)
+          await this.createSignal(tx, request, status, reason);
+      }
       return tx.approvalRequest.findUnique({ where: { id: requestId } });
     });
   }
@@ -550,44 +642,54 @@ export class HumanApprovalService {
   }
 }
 
-function attachApprovalWorkflowInvocation(
+function candidateKey(value: { principalType: string; principalRef: string }) {
+  return `${value.principalType}\u0000${value.principalRef}`;
+}
+
+function attachExternalApproval(
   request: any,
-  candidates: any[],
-  approvalWorkflowId: string | undefined,
+  candidates: Array<{
+    principalRef: string;
+    displayName: string;
+    principalType: string;
+  }>,
   input: StartApprovalRequestDto,
 ) {
-  if (
-    !approvalWorkflowId ||
-    request.status !== 'PENDING' ||
-    !input.callbackToken
-  )
+  if (!input.configSnapshot.external || request.status === 'BLOCKED')
     return request;
-  const expiresAt = request.expiresAt
-    ? new Date(request.expiresAt).toISOString()
-    : null;
+  if (!input.callbackToken)
+    throw approvalError(
+      'APPROVAL_CONFIG_MISMATCH',
+      'External approval callback token is missing',
+      HttpStatus.BAD_REQUEST,
+    );
+  if (!input.callbackUrl)
+    throw approvalError(
+      'APPROVAL_CONFIG_MISMATCH',
+      'External approval callback URL is missing',
+      HttpStatus.BAD_REQUEST,
+    );
   return {
     ...request,
-    approvalWorkflowInvocation: {
-      workflowId: approvalWorkflowId,
-      workflow: {
-        ...(input.approvalWorkflowInputs ?? {}),
-        requestId: String(request.id),
-        callbackToken: input.callbackToken,
-        candidates: candidates.map((candidate) => ({
+    externalApproval: {
+      requestId: String(request.id),
+      callbackToken: input.callbackToken,
+      callbackUrl: input.callbackUrl,
+      expiresAt:
+        request.expiresAt instanceof Date
+          ? request.expiresAt.toISOString()
+          : request.expiresAt ?? null,
+      task: input.task,
+      candidates: candidates
+        .filter((candidate) => candidate.principalType === 'USER')
+        .map((candidate) => ({
           approverId: candidate.principalRef,
           displayName: candidate.displayName,
-          principalType: candidate.principalType,
         })),
-        expiresAt,
-      },
     },
   };
 }
 
-function candidateKey(value: { principalType: string; principalRef: string }) {
-  return `${value.principalType}\u0000${value.principalRef}`;
-}
-
 function toBigInt(value: string | number | bigint): bigint {
   if (typeof value === 'number' && !Number.isSafeInteger(value)) {
     throw approvalError(
@@ -627,31 +729,171 @@ function closed(id: bigint, status: string) {
   );
 }
 
-function asObject(value: unknown): Record<string, unknown> {
+function asObject(value: unknown): Record<string, any> {
   return value && typeof value === 'object' && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
+    ? (value as Record<string, any>)
     : {};
 }
 
+function readOperationScopeId(context: unknown, instanceId: bigint): string {
+  const configured = asObject(asObject(context).system).operationScopeId;
+  return typeof configured === 'string' && configured
+    ? configured
+    : String(instanceId);
+}
+
+function approvalRequestHash(
+  input: StartApprovalRequestDto,
+  resolved: {
+    subjects: Array<{
+      provider: string;
+      ref: string;
+      resourceRevision?: number;
+      metadata?: Prisma.InputJsonValue;
+    }>;
+    candidates: Array<{
+      principalType: string;
+      principalRef: string;
+      displayName: string;
+      sourceRefs: Prisma.InputJsonValue;
+    }>;
+  },
+): string {
+  const subjects = [...resolved.subjects].sort((left, right) =>
+    `${left.provider}:${left.ref}`.localeCompare(
+      `${right.provider}:${right.ref}`,
+    ),
+  );
+  const candidates = resolved.candidates
+    .map((candidate) => ({
+      principalType: candidate.principalType,
+      principalRef: candidate.principalRef,
+      sourceRefs: Array.isArray(candidate.sourceRefs)
+        ? [...candidate.sourceRefs].sort()
+        : candidate.sourceRefs,
+    }))
+    .sort((left, right) =>
+      `${left.principalType}:${left.principalRef}`.localeCompare(
+        `${right.principalType}:${right.principalRef}`,
+      ),
+    );
+  return hashNodeInstanceConfig({
+    configHash: input.configHash,
+    input: input.input as Prisma.JsonValue,
+    task: input.task as unknown as Prisma.JsonValue,
+    dynamicInputs: (input.dynamicInputs ?? {}) as Prisma.JsonValue,
+    subjects,
+    candidates,
+  } as Prisma.JsonValue);
+}
+
+function attachCompletedResolution<T extends Record<string, any>>(request: T) {
+  if (request.status !== 'APPROVED' && request.status !== 'REJECTED')
+    return request;
+  const payload = asObject(request.signalOutboxes?.[0]?.payload);
+  return {
+    ...request,
+    reusedResolution: {
+      requestId: String(request.id),
+      result: request.status,
+      reason:
+        typeof payload.reason === 'string' ? payload.reason : 'RULE_SATISFIED',
+      decidedAt:
+        typeof payload.decidedAt === 'string'
+          ? payload.decidedAt
+          : request.completedAt instanceof Date
+          ? request.completedAt.toISOString()
+          : new Date().toISOString(),
+    },
+  };
+}
+
 function stringValue(value: unknown): string | null {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
 
-function mergeSubjectSources(
-  ...groups: Array<Array<{ provider: string; refs: string[] }>>
-) {
-  const refsByProvider = new Map<string, Set<string>>();
-  for (const group of groups) {
-    for (const source of group) {
-      const refs = refsByProvider.get(source.provider) ?? new Set<string>();
-      for (const ref of source.refs) {
-        if (typeof ref === 'string' && ref.trim()) refs.add(ref.trim());
-      }
-      refsByProvider.set(source.provider, refs);
-    }
-  }
-  return [...refsByProvider].map(([provider, refs]) => ({
-    provider,
-    refs: [...refs],
-  }));
+type LockedWorkflowInstance = {
+  id: bigint;
+  status: string;
+};
+
+async function lockWorkflowInstance(
+  tx: any,
+  workflowInstanceId: bigint,
+): Promise<LockedWorkflowInstance | null> {
+  if (typeof tx.$queryRawUnsafe !== 'function')
+    return { id: workflowInstanceId, status: 'RUNNING' };
+  const rows = await tx.$queryRawUnsafe(
+    `SELECT id, status::text AS status
+       FROM t_workflow_instance
+      WHERE id = $1
+      FOR UPDATE`,
+    workflowInstanceId,
+  );
+  return rows[0] ?? null;
+}
+
+async function lockWorkflowForApprovalRequest(
+  tx: any,
+  requestId: bigint,
+): Promise<LockedWorkflowInstance | null> {
+  if (typeof tx.$queryRawUnsafe !== 'function')
+    return { id: BigInt(0), status: 'RUNNING' };
+  const rows = await tx.$queryRawUnsafe(
+    `SELECT workflow.id, workflow.status::text AS status
+       FROM t_workflow_instance workflow
+       JOIN t_approval_request approval
+         ON approval.workflow_instance_id = workflow.id
+      WHERE approval.id = $1
+      FOR UPDATE OF workflow`,
+    requestId,
+  );
+  return rows[0] ?? null;
+}
+
+function assertWorkflowAcceptsApproval(
+  workflow: LockedWorkflowInstance | null,
+): asserts workflow is LockedWorkflowInstance {
+  if (!workflow)
+    throw approvalError(
+      'APPROVAL_REQUEST_NOT_FOUND',
+      'Workflow instance for approval request was not found',
+      HttpStatus.NOT_FOUND,
+    );
+  if (!['PENDING', 'RUNNING'].includes(workflow.status))
+    throw approvalError(
+      'APPROVAL_REQUEST_CLOSED',
+      'Workflow instance is no longer accepting approval changes',
+      HttpStatus.CONFLICT,
+    );
+}
+
+async function blockCancellationAfterResolution(
+  tx: any,
+  request: {
+    workflowInstanceId: bigint;
+    nodeId: string;
+    configSnapshot: unknown;
+  },
+): Promise<void> {
+  if (asObject(request.configSnapshot).blockCancellationOnResolved !== true)
+    return;
+  await tx.workflowInstance.updateMany({
+    where: {
+      id: request.workflowInstanceId,
+      cancellationBlockedAt: null,
+    },
+    data: {
+      cancellationBlockedAt: new Date(),
+      cancellationBlockedByNodeId: request.nodeId,
+    },
+  });
+}
+
+async function lockApprovalRequest(tx: any, requestId: bigint): Promise<void> {
+  if (typeof tx.$queryRawUnsafe !== 'function') return;
+  await tx.$queryRawUnsafe(
+    'SELECT id FROM t_approval_request WHERE id = $1 FOR UPDATE',
+    requestId,
+  );
 }