hierarchical-approval 2.0.0 → 2.1.0

package/dist/index.cjs

@@ -914,6 +914,7 @@ function computeTimingStats(samples) {
 }
 
 // src/engine/ApprovalEngine.ts
+var MAX_SUBWORKFLOW_DEPTH = 5;
 var DEFAULT_MAX_REMINDERS = 3;
 var DEFAULT_MAX_ATTEMPTS = 3;
 var DEFAULT_BASE_DELAY_MS = 50;
@@ -1018,12 +1019,32 @@ var ApprovalEngine = class _ApprovalEngine {
           });
         }
         levelNums.add(l.level);
-        if (!l.approvers || l.approvers.length === 0) {
+        if (!l.subWorkflow && (!l.approvers || l.approvers.length === 0)) {
           errors.push({
             field: `levels[${i}].approvers`,
             message: `Level ${l.level} must have at least one approver.`
           });
         }
+        if (l.subWorkflow) {
+          if (!l.subWorkflow.templateName) {
+            errors.push({
+              field: `levels[${i}].subWorkflow.templateName`,
+              message: `Level ${l.level} declares a subWorkflow without a templateName.`
+            });
+          }
+          if (l.subWorkflow.templateName === config.name) {
+            errors.push({
+              field: `levels[${i}].subWorkflow.templateName`,
+              message: `Level ${l.level} would spawn a sub-workflow of its own template ("${config.name}"), which cannot terminate.`
+            });
+          }
+          if (l.approvers && l.approvers.length > 0) {
+            errors.push({
+              field: `levels[${i}].approvers`,
+              message: `Level ${l.level} sets both approvers and subWorkflow; a sub-workflow level is decided by its child approval, so its approvers would never be asked.`
+            });
+          }
+        }
         if (l.reminderAfterDays !== void 0 && l.reminderAfterDays <= 0) {
           errors.push({
             field: `levels[${i}].reminderAfterDays`,
@@ -1166,7 +1187,7 @@ var ApprovalEngine = class _ApprovalEngine {
     return this.registry.list();
   }
   // ─── Lifecycle ────────────────────────────────────────────────────────────
-  async submit(raw, auditCtx) {
+  async submit(raw, auditCtx, link) {
     const opts = parseOrThrow(() => SubmitOptionsSchema.parse(raw));
     const startMs = this.clock.now().getTime();
     const template = await this.registry.get(opts.templateName);
@@ -1226,6 +1247,7 @@ var ApprovalEngine = class _ApprovalEngine {
         weights: cfg.weights,
         escalationAfterDays: cfg.escalationAfterDays,
         escalationDueAt: inFirstGroup && cfg.escalationAfterDays ? this.deadlineFrom(now, cfg.escalationAfterDays) : void 0,
+        subWorkflowTemplate: cfg.subWorkflow?.templateName,
         reminderAfterDays: cfg.reminderAfterDays,
         reminderEveryDays: cfg.reminderEveryDays,
         maxReminders: cfg.maxReminders,
@@ -1234,6 +1256,10 @@ var ApprovalEngine = class _ApprovalEngine {
       };
     });
     for (const lvl of levels.filter((l) => l.status === "pending")) {
+      if (lvl.subWorkflowTemplate) {
+        lvl.approverIds = [];
+        continue;
+      }
       lvl.approverIds = await this.resolver.resolveApprovers(
         lvl.approverConfigs,
         opts.submittedBy,
@@ -1254,6 +1280,9 @@ var ApprovalEngine = class _ApprovalEngine {
     const instance = {
       id: instanceId,
       tenantId: this.tenantId,
+      parentInstanceId: link?.parentInstanceId,
+      parentLevel: link?.parentLevel,
+      subWorkflowDepth: link?.depth,
       templateId: template.id,
       templateName: template.name,
       documentId: opts.documentId,
@@ -1318,12 +1347,13 @@ var ApprovalEngine = class _ApprovalEngine {
       { operation: "submit", actorId: opts.submittedBy, tenantId: this.tenantId, input: opts },
       instance
     );
+    await this.startSubWorkflows(instance);
     return instance;
   }
   async approve(instanceId, raw, auditCtx) {
     const opts = parseOrThrow(() => ApproveOptionsSchema.parse(raw));
     const startMs = this.clock.now().getTime();
-    return this.withOptimisticRetry(instanceId, async (instance) => {
+    const decided = await this.withOptimisticRetry(instanceId, async (instance) => {
       assertStatus(instance, "pending");
       if (opts.approverId === instance.submittedBy) {
         throw new ApprovalForbiddenError(
@@ -1536,10 +1566,12 @@ var ApprovalEngine = class _ApprovalEngine {
       }
       return instance;
     });
+    await this.afterDecision(decided);
+    return decided;
   }
   async reject(instanceId, raw, auditCtx) {
     const opts = parseOrThrow(() => RejectOptionsSchema.parse(raw));
-    return this.withOptimisticRetry(instanceId, async (instance) => {
+    const decided = await this.withOptimisticRetry(instanceId, async (instance) => {
       assertStatus(instance, "pending");
       if (opts.approverId === instance.submittedBy) {
         throw new ApprovalForbiddenError(
@@ -1658,6 +1690,8 @@ var ApprovalEngine = class _ApprovalEngine {
       }
       return instance;
     });
+    await this.afterDecision(decided);
+    return decided;
   }
   async delegate(instanceId, raw, auditCtx) {
     const opts = parseOrThrow(() => DelegateOptionsSchema.parse(raw));
@@ -1835,7 +1869,8 @@ var ApprovalEngine = class _ApprovalEngine {
   }
   async cancel(instanceId, raw, auditCtx) {
     const opts = parseOrThrow(() => CancelOptionsSchema.parse(raw));
-    return this.withOptimisticRetry(instanceId, async (instance) => {
+    let cancelled = null;
+    const result = await this.withOptimisticRetry(instanceId, async (instance) => {
       if (instance.status === "approved" || instance.status === "rejected") {
         throw new ApprovalError(`Cannot cancel a "${instance.status}" approval.`, "CANNOT_CANCEL");
       }
@@ -1889,8 +1924,11 @@ var ApprovalEngine = class _ApprovalEngine {
         },
         instance
       );
+      cancelled = instance;
       return instance;
     });
+    if (cancelled) await this.propagateToParent(cancelled);
+    return result;
   }
   async escalate(instanceId, raw, auditCtx) {
     parseOrThrow(() => EscalateOptionsSchema.parse(raw));
@@ -3407,14 +3445,18 @@ var ApprovalEngine = class _ApprovalEngine {
   /** Resolve approvers for a group, set its deadlines, and mark it pending. */
   async activateGroup(instance, group, now) {
     for (const lvl of group) {
-      lvl.approverIds = await this.resolver.resolveApprovers(
-        lvl.approverConfigs,
-        instance.submittedBy,
-        instance.data,
-        this.opts.orgProvider,
-        this.opts.outOfOfficeProvider,
-        now
-      );
+      if (lvl.subWorkflowTemplate) {
+        lvl.approverIds = [];
+      } else {
+        lvl.approverIds = await this.resolver.resolveApprovers(
+          lvl.approverConfigs,
+          instance.submittedBy,
+          instance.data,
+          this.opts.orgProvider,
+          this.opts.outOfOfficeProvider,
+          now
+        );
+      }
       if (lvl.escalationAfterDays) {
         lvl.escalationDueAt = this.deadlineFrom(now, lvl.escalationAfterDays);
       }
@@ -3501,6 +3543,222 @@ var ApprovalEngine = class _ApprovalEngine {
       this.logger.error("reminder: failed to send", err, { tenantId: this.tenantId, instanceId });
     }
   }
+  /**
+   * Start child approvals for any open level that delegates to a sub-workflow.
+   *
+   * Run after the parent has been persisted, never inside the same optimistic
+   * write: the child's own `submit()` performs its own reads and writes, and
+   * nesting them under the parent's compare-and-set would make a slow child
+   * template a source of spurious version conflicts on the parent.
+   */
+  async startSubWorkflows(instance) {
+    const pendingSubs = instance.levels.filter(
+      (l) => l.status === "pending" && l.subWorkflowTemplate && !l.childInstanceId
+    );
+    if (pendingSubs.length === 0) return;
+    const depth = (instance.subWorkflowDepth ?? 0) + 1;
+    if (depth > MAX_SUBWORKFLOW_DEPTH) {
+      throw new ApprovalValidationError(
+        `Sub-workflow nesting exceeded ${MAX_SUBWORKFLOW_DEPTH} levels at template "${instance.templateName}". Check for a template that reaches itself.`
+      );
+    }
+    for (const level of pendingSubs) {
+      const templateName = level.subWorkflowTemplate;
+      const childTemplate = await this.registry.get(templateName);
+      const child = await this.submit(
+        {
+          templateName,
+          // Unique per parent level, so a resubmitted parent does not collide
+          // with the child it spawned last time.
+          documentId: `${instance.documentId}#L${level.level}`,
+          documentType: childTemplate.documentType,
+          submittedBy: instance.submittedBy,
+          data: instance.data,
+          metadata: { ...instance.metadata, parentInstanceId: instance.id }
+        },
+        void 0,
+        { parentInstanceId: instance.id, parentLevel: level.level, depth }
+      );
+      await this.withOptimisticRetry(instance.id, async (parent) => {
+        const lvl = parent.levels.find((l) => l.level === level.level);
+        if (!lvl || lvl.childInstanceId) return parent;
+        lvl.childInstanceId = child.id;
+        parent.updatedAt = this.clock.now();
+        await this.opts.adapter.updateInstance(parent, parent.version);
+        return parent;
+      });
+      const payload = {
+        instanceId: instance.id,
+        documentId: instance.documentId,
+        documentType: instance.documentType,
+        timestamp: this.clock.now(),
+        level: level.level,
+        childInstanceId: child.id,
+        childTemplateName: templateName
+      };
+      this.bus.emit("approval:subworkflow_started", payload);
+      await this.notifyAdapters("approval:subworkflow_started", instance, payload);
+      this.logger.info("subWorkflow: child approval started", {
+        tenantId: this.tenantId,
+        instanceId: instance.id,
+        level: level.level,
+        childInstanceId: child.id
+      });
+    }
+  }
+  /**
+   * Return a finished child's outcome to the parent level that is waiting on it.
+   *
+   * An approved child approves its parent level and lets the chain advance; any
+   * other terminal outcome — rejected, cancelled, expired — rejects the parent,
+   * because the approval the parent was waiting for did not happen. Collapsing
+   * those into one rejection is deliberate: a parent that treated a cancelled
+   * child as "carry on" would advance past a gate nobody cleared.
+   */
+  async propagateToParent(child) {
+    if (!child.parentInstanceId || child.parentLevel === void 0) return;
+    const outcome = child.status;
+    const parentId = child.parentInstanceId;
+    const parentLevelNumber = child.parentLevel;
+    try {
+      const parent = await this.opts.adapter.getInstance(this.tenantId, parentId);
+      if (!parent || parent.status !== "pending") return;
+      const payload = {
+        instanceId: parentId,
+        documentId: parent.documentId,
+        documentType: parent.documentType,
+        timestamp: this.clock.now(),
+        level: parentLevelNumber,
+        childInstanceId: child.id,
+        childTemplateName: child.templateName,
+        outcome
+      };
+      if (outcome === "approved") {
+        await this.completeSubWorkflowLevel(parentId, parentLevelNumber, child);
+      } else {
+        await this.rejectFromSubWorkflow(parentId, parentLevelNumber, child);
+      }
+      const refreshed = await this.opts.adapter.getInstance(this.tenantId, parentId);
+      this.bus.emit("approval:subworkflow_completed", payload);
+      if (refreshed) {
+        await this.notifyAdapters("approval:subworkflow_completed", refreshed, payload);
+      }
+    } catch (err) {
+      this.logger.error("subWorkflow: failed to propagate outcome to parent", err, {
+        tenantId: this.tenantId,
+        childInstanceId: child.id,
+        parentInstanceId: parentId
+      });
+    }
+  }
+  /** Mark a sub-workflow level approved and advance the parent chain. */
+  async completeSubWorkflowLevel(parentId, levelNumber, child) {
+    let advanced = null;
+    await this.withOptimisticRetry(parentId, async (parent) => {
+      const level = parent.levels.find((l) => l.level === levelNumber);
+      if (!level || level.status !== "pending") return parent;
+      const now = this.clock.now();
+      level.status = "approved";
+      level.reminderDueAt = void 0;
+      level.escalationDueAt = void 0;
+      const auditEntry = {
+        action: "subworkflow_completed",
+        actorId: "system",
+        level: levelNumber,
+        timestamp: now,
+        newValue: { childInstanceId: child.id, outcome: "approved" }
+      };
+      parent.auditLog.push(auditEntry);
+      parent.updatedAt = now;
+      const siblingsOpen = this.groupMembers(parent, level).some(
+        (l) => l.status === "pending" || l.status === "waiting"
+      );
+      if (!siblingsOpen) {
+        const nextGroup = this.findNextGroup(parent);
+        if (nextGroup.length === 0) {
+          parent.status = "approved";
+        } else {
+          await this.activateGroup(parent, nextGroup, now);
+        }
+      }
+      await this.opts.adapter.updateInstance(parent, parent.version);
+      await this.opts.adapter.appendAuditEntry(this.tenantId, parentId, auditEntry);
+      await this.runExternalAudit(parent, auditEntry);
+      advanced = parent;
+      return parent;
+    });
+    if (advanced) {
+      const parent = advanced;
+      if (parent.status === "approved") {
+        this.bus.emit("approval:completed", parent);
+        await this.notifyAdapters("approval:completed", parent, parent);
+        await this.propagateToParent(parent);
+      } else {
+        await this.startSubWorkflows(parent);
+      }
+    }
+  }
+  /** Reject a parent because the child approval it was waiting on did not succeed. */
+  async rejectFromSubWorkflow(parentId, levelNumber, child) {
+    let rejected = null;
+    await this.withOptimisticRetry(parentId, async (parent) => {
+      const level = parent.levels.find((l) => l.level === levelNumber);
+      if (!level || level.status !== "pending") return parent;
+      const now = this.clock.now();
+      level.status = "rejected";
+      level.reminderDueAt = void 0;
+      level.escalationDueAt = void 0;
+      parent.status = "rejected";
+      parent.updatedAt = now;
+      const auditEntry = {
+        action: "subworkflow_completed",
+        actorId: "system",
+        level: levelNumber,
+        timestamp: now,
+        reason: `Child approval ${child.id} ended as "${child.status}".`,
+        newValue: { childInstanceId: child.id, outcome: child.status }
+      };
+      parent.auditLog.push(auditEntry);
+      await this.opts.adapter.updateInstance(parent, parent.version);
+      await this.opts.adapter.appendAuditEntry(this.tenantId, parentId, auditEntry);
+      await this.runExternalAudit(parent, auditEntry);
+      rejected = parent;
+      return parent;
+    });
+    if (rejected) {
+      const parent = rejected;
+      const payload = {
+        instanceId: parent.id,
+        documentId: parent.documentId,
+        documentType: parent.documentType,
+        timestamp: this.clock.now(),
+        approverId: "system",
+        level: levelNumber,
+        reason: `Child approval ${child.id} ended as "${child.status}".`,
+        returnTo: null
+      };
+      this.bus.emit("approval:rejected", payload);
+      await this.notifyAdapters("approval:rejected", parent, payload);
+      await this.propagateToParent(parent);
+    }
+  }
+  /**
+   * Work that must happen after a decision is durably recorded, not inside it.
+   *
+   * Both branches touch other instances — a newly opened level may spawn a
+   * child approval, and a finished instance may be a child that owes its
+   * outcome to a parent. Doing either inside the deciding instance's
+   * compare-and-set would nest writes under a version guard that knows nothing
+   * about them, so a slow child template would surface as a spurious conflict
+   * on the decision the user just made.
+   */
+  async afterDecision(instance) {
+    if (TERMINAL_STATUSES.has(instance.status)) {
+      await this.propagateToParent(instance);
+      return;
+    }
+    await this.startSubWorkflows(instance);
+  }
   findNextLevel(instance) {
     return instance.levels.find((l) => l.level > instance.currentLevel && l.status === "waiting") ?? null;
   }