hierarchical-approval 2.9.0 → 3.0.0

package/CHANGELOG.md

@@ -7,6 +7,54 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [3.0.0] - 2026-09-04
+
+Three defects found by auditing the interactions between features added across
+2.x, rather than by adding anything new.
+
+### Fixed — `updateData()` built condition-added levels wrong
+
+- **A level a condition added during `updateData()` silently lost its `group`,
+  `subWorkflow`, `escalationAfterHours` and reminder configuration.** Levels
+  were constructed in two places — `submit()` and `recomputeFutureChain()` —
+  and the second copy had never been updated as fields were added across 1.0.0
+  to 2.6.0. The consequences were quiet and serious:
+
+  - a condition-added **parallel group ran sequentially**, one branch at a time,
+    because the levels came back without their `group`;
+  - a condition-added **sub-workflow level lost its binding**, then failed with
+    "No approvers resolved for this level" when reached — leaving an approval
+    that could never advance;
+  - hour-based escalation and reminders simply never fired.
+
+  A level whose configuration was unchanged was carried over intact, so this
+  only bit templates whose conditions *add* levels — and it bit them silently.
+
+  Both paths now go through one `buildLevelInstance()`, so a field cannot be
+  added to a level in one place and forgotten in the other. This is the same
+  failure the 1.6.0 Postgres column list had, in a different file.
+
+### BREAKING — a finished parent no longer leaves its sub-workflow children running
+
+- **Cancelling or rejecting a parent left its child approval pending forever.**
+  The child kept notifying, kept escalating, and kept appearing in
+  `getWorkload()` — asking people to decide something whose outcome nobody would
+  ever read, since `propagateToParent()` ignores a parent that is no longer
+  pending. Children of a terminal parent are now cancelled, with the reason
+  naming the parent, and the child's own audit trail is left intact rather than
+  deleted.
+
+  **Behaviour change:** a child that used to stay open now reaches `cancelled`.
+  Anything counting open approvals, or waiting on a child whose parent has
+  ended, will see different numbers — correct ones.
+
+- **`purgeInstances()` orphaned sub-workflow children.** It removed the parent
+  and left the child behind, holding a `parentInstanceId` pointing at a row that
+  no longer existed — unreachable, and invisible to a purge scoped by document
+  type, since a child usually has a different one. A purge now takes the whole
+  sub-workflow family together, parents first, deduplicated so a parent and
+  child sharing a terminal status are each reported once.
+
 ## [2.9.0] - 2026-09-04
 
 ### Added — `simulate()`

package/README.md

@@ -689,6 +689,13 @@ Collapsing the non-approved outcomes into one rejection is deliberate: a parent
 that treated a cancelled child as "carry on" would advance past a gate nobody
 cleared.
 
+**A finished parent ends its children.** If a parent is cancelled or rejected
+while a child is still running, the child is cancelled too, with the reason
+naming the parent — otherwise it would keep asking people to decide something
+whose outcome nobody will read. A child that already finished is left alone.
+`purgeInstances()` likewise removes a whole sub-workflow family together, so a
+child is never orphaned behind a deleted parent.
+
 Children link back via `parentInstanceId` and `parentLevel`, and the level
 records `childInstanceId`. Nesting is allowed up to five levels deep, and
 `validateTemplate()` rejects a template that would spawn itself. Emits

package/dist/{ApprovalEngine-DMM55f5R.d.cts → ApprovalEngine-Bfs5BnMm.d.cts}

@@ -995,6 +995,19 @@ declare class ApprovalEngine {
      * `businessHoursCalendar` to have hours skip evenings and weekends.
      */
     private deadlineFromHours;
+    /**
+     * Build a level instance from its template config.
+     *
+     * The single place a level is constructed. It previously happened twice — in
+     * `submit()` and again in `recomputeFutureChain()` — and the second copy was
+     * missing `group`, `subWorkflowTemplate`, `escalationAfterHours` and the
+     * reminder fields, so a level added by a condition during `updateData()` came
+     * out silently different from the same level created at submit.
+     *
+     * @param cfg - The template's configuration for this level.
+     * @param opts - `open` activates the level now, computing deadlines from `now`.
+     */
+    private buildLevelInstance;
     /** Level deadline from whichever of days/hours the template configured. */
     private levelEscalationDue;
     /** First rung of a ladder, sorted by delay, or undefined when there is none. */
@@ -1098,6 +1111,27 @@ declare class ApprovalEngine {
      * about them, so a slow child template would surface as a spurious conflict
      * on the decision the user just made.
      */
+    /**
+     * An instance and every sub-workflow descendant beneath it, parents first.
+     *
+     * A child is only reachable through its parent's `childInstanceId`, so a
+     * purge that removed the parent alone would strand the rest of the tree.
+     * Depth is bounded by the same cap that limits spawning, and an already-seen
+     * id is skipped so a corrupted link cannot loop.
+     */
+    private collectSubWorkflowFamily;
+    /**
+     * Cancel sub-workflow children whose parent has finished.
+     *
+     * A child outlives its parent otherwise: it stays pending, keeps notifying
+     * and escalating, and keeps appearing in {@link getWorkload} — asking people
+     * to decide something whose outcome nobody will ever read, because
+     * {@link propagateToParent} ignores a parent that is no longer pending.
+     *
+     * Cancelling rather than deleting keeps the child's own audit trail intact:
+     * the people who were asked, and why the request stopped, stay on the record.
+     */
+    private cancelOrphanedChildren;
     private afterDecision;
     private findNextLevel;
     private findPreviousLevel;

package/dist/{ApprovalEngine-B3PVWw05.d.ts → ApprovalEngine-CCOwhMrs.d.ts}

@@ -995,6 +995,19 @@ declare class ApprovalEngine {
      * `businessHoursCalendar` to have hours skip evenings and weekends.
      */
     private deadlineFromHours;
+    /**
+     * Build a level instance from its template config.
+     *
+     * The single place a level is constructed. It previously happened twice — in
+     * `submit()` and again in `recomputeFutureChain()` — and the second copy was
+     * missing `group`, `subWorkflowTemplate`, `escalationAfterHours` and the
+     * reminder fields, so a level added by a condition during `updateData()` came
+     * out silently different from the same level created at submit.
+     *
+     * @param cfg - The template's configuration for this level.
+     * @param opts - `open` activates the level now, computing deadlines from `now`.
+     */
+    private buildLevelInstance;
     /** Level deadline from whichever of days/hours the template configured. */
     private levelEscalationDue;
     /** First rung of a ladder, sorted by delay, or undefined when there is none. */
@@ -1098,6 +1111,27 @@ declare class ApprovalEngine {
      * about them, so a slow child template would surface as a spurious conflict
      * on the decision the user just made.
      */
+    /**
+     * An instance and every sub-workflow descendant beneath it, parents first.
+     *
+     * A child is only reachable through its parent's `childInstanceId`, so a
+     * purge that removed the parent alone would strand the rest of the tree.
+     * Depth is bounded by the same cap that limits spawning, and an already-seen
+     * id is skipped so a corrupted link cannot loop.
+     */
+    private collectSubWorkflowFamily;
+    /**
+     * Cancel sub-workflow children whose parent has finished.
+     *
+     * A child outlives its parent otherwise: it stays pending, keeps notifying
+     * and escalating, and keeps appearing in {@link getWorkload} — asking people
+     * to decide something whose outcome nobody will ever read, because
+     * {@link propagateToParent} ignores a parent that is no longer pending.
+     *
+     * Cancelling rather than deleting keeps the child's own audit trail intact:
+     * the people who were asked, and why the request stopped, stay on the record.
+     */
+    private cancelOrphanedChildren;
     private afterDecision;
     private findNextLevel;
     private findPreviousLevel;

package/dist/index.cjs

@@ -1475,33 +1475,14 @@ var ApprovalEngine = class _ApprovalEngine {
     const instanceId = this.generateId("inst");
     const firstCfg = allLevelCfgs[0];
     const firstGroupKey = firstCfg ? _ApprovalEngine.groupKeyOf(firstCfg) : null;
-    const levels = allLevelCfgs.map((cfg) => {
-      const inFirstGroup = _ApprovalEngine.groupKeyOf(cfg) === firstGroupKey;
-      return {
-        level: cfg.level,
-        name: cfg.name,
-        group: cfg.group,
-        mode: cfg.mode,
-        approverConfigs: cfg.approvers,
-        approverIds: [],
-        approvedBy: [],
-        rejectedBy: [],
-        status: inFirstGroup ? "pending" : "waiting",
-        minApprovals: cfg.minApprovals,
-        threshold: cfg.threshold,
-        weights: cfg.weights,
-        escalationAfterDays: cfg.escalationAfterDays,
-        escalationAfterHours: cfg.escalationAfterHours,
-        escalationStep: 0,
-        escalationDueAt: inFirstGroup ? this.levelEscalationDue(now, cfg, this.firstRungOf(template.escalationSteps)) : void 0,
-        subWorkflowTemplate: cfg.subWorkflow?.templateName,
-        reminderAfterDays: cfg.reminderAfterDays,
-        reminderEveryDays: cfg.reminderEveryDays,
-        maxReminders: cfg.maxReminders,
-        remindersSent: 0,
-        reminderDueAt: inFirstGroup && cfg.reminderAfterDays ? this.deadlineFrom(now, cfg.reminderAfterDays) : void 0
-      };
-    });
+    const firstRung = this.firstRungOf(template.escalationSteps);
+    const levels = allLevelCfgs.map(
+      (cfg) => this.buildLevelInstance(cfg, {
+        open: _ApprovalEngine.groupKeyOf(cfg) === firstGroupKey,
+        now,
+        firstRung
+      })
+    );
     for (const lvl of levels.filter((l) => l.status === "pending")) {
       if (lvl.subWorkflowTemplate) {
         lvl.approverIds = [];
@@ -2176,7 +2157,10 @@ var ApprovalEngine = class _ApprovalEngine {
       cancelled = instance;
       return instance;
     });
-    if (cancelled) await this.propagateToParent(cancelled);
+    if (cancelled) {
+      await this.cancelOrphanedChildren(cancelled);
+      await this.propagateToParent(cancelled);
+    }
     return result;
   }
   async escalate(instanceId, raw, auditCtx) {
@@ -2329,20 +2313,7 @@ var ApprovalEngine = class _ApprovalEngine {
     const rebuiltFuture = futureCfgs.map((cfg) => {
       const kept = existingFuture.get(cfg.level);
       if (kept) return kept;
-      return {
-        level: cfg.level,
-        name: cfg.name,
-        mode: cfg.mode,
-        approverConfigs: cfg.approvers,
-        approverIds: [],
-        approvedBy: [],
-        rejectedBy: [],
-        status: "waiting",
-        minApprovals: cfg.minApprovals,
-        threshold: cfg.threshold,
-        weights: cfg.weights,
-        escalationAfterDays: cfg.escalationAfterDays
-      };
+      return this.buildLevelInstance(cfg, { open: false, now: this.clock.now() });
     });
     instance.levels = [...frozen, ...rebuiltFuture];
     return { addedLevels: addedLevels.sort((a, b) => a - b), removedLevels };
@@ -3659,6 +3630,7 @@ var ApprovalEngine = class _ApprovalEngine {
       );
     }
     const result = { purged: [], scanned: 0, dryRun };
+    const handled = /* @__PURE__ */ new Set();
     for (const status of requested) {
       if (result.purged.length >= limit) break;
       const page = await this.opts.adapter.getInstancesByFilter(
@@ -3672,15 +3644,21 @@ var ApprovalEngine = class _ApprovalEngine {
       );
       for (const instance of page.items) {
         if (result.purged.length >= limit) break;
+        if (handled.has(instance.id)) continue;
         result.scanned++;
         if (!TERMINAL_STATUSES.has(instance.status)) continue;
         if (new Date(instance.createdAt) > opts.olderThan) continue;
-        if (!dryRun) await deleteInstance(this.tenantId, instance.id);
-        result.purged.push({
-          instanceId: instance.id,
-          documentId: instance.documentId,
-          status: instance.status
-        });
+        const family = await this.collectSubWorkflowFamily(instance);
+        for (const member of family) {
+          if (handled.has(member.id)) continue;
+          handled.add(member.id);
+          if (!dryRun) await deleteInstance(this.tenantId, member.id);
+          result.purged.push({
+            instanceId: member.id,
+            documentId: member.documentId,
+            status: member.status
+          });
+        }
       }
     }
     this.logger.info("purgeInstances: sweep complete", {
@@ -4056,6 +4034,47 @@ var ApprovalEngine = class _ApprovalEngine {
     const addHours = this.calendar?.addBusinessHours?.bind(this.calendar);
     return addHours ? addHours(from, hours) : new Date(from.getTime() + hours * 36e5);
   }
+  /**
+   * Build a level instance from its template config.
+   *
+   * The single place a level is constructed. It previously happened twice — in
+   * `submit()` and again in `recomputeFutureChain()` — and the second copy was
+   * missing `group`, `subWorkflowTemplate`, `escalationAfterHours` and the
+   * reminder fields, so a level added by a condition during `updateData()` came
+   * out silently different from the same level created at submit.
+   *
+   * @param cfg - The template's configuration for this level.
+   * @param opts - `open` activates the level now, computing deadlines from `now`.
+   */
+  buildLevelInstance(cfg, opts) {
+    const level = {
+      level: cfg.level,
+      name: cfg.name,
+      group: cfg.group,
+      mode: cfg.mode,
+      approverConfigs: cfg.approvers,
+      approverIds: [],
+      approvedBy: [],
+      rejectedBy: [],
+      status: opts.open ? "pending" : "waiting",
+      minApprovals: cfg.minApprovals,
+      threshold: cfg.threshold,
+      weights: cfg.weights,
+      subWorkflowTemplate: cfg.subWorkflow?.templateName,
+      escalationAfterDays: cfg.escalationAfterDays,
+      escalationAfterHours: cfg.escalationAfterHours,
+      escalationStep: 0,
+      reminderAfterDays: cfg.reminderAfterDays,
+      reminderEveryDays: cfg.reminderEveryDays,
+      maxReminders: cfg.maxReminders,
+      remindersSent: 0
+    };
+    if (opts.open) {
+      level.escalationDueAt = this.levelEscalationDue(opts.now, cfg, opts.firstRung);
+      this.scheduleReminder(level, opts.now);
+    }
+    return level;
+  }
   /** Level deadline from whichever of days/hours the template configured. */
   levelEscalationDue(from, level, firstRung) {
     if (level.escalationAfterHours) return this.deadlineFromHours(from, level.escalationAfterHours);
@@ -4507,8 +4526,68 @@ var ApprovalEngine = class _ApprovalEngine {
    * about them, so a slow child template would surface as a spurious conflict
    * on the decision the user just made.
    */
+  /**
+   * An instance and every sub-workflow descendant beneath it, parents first.
+   *
+   * A child is only reachable through its parent's `childInstanceId`, so a
+   * purge that removed the parent alone would strand the rest of the tree.
+   * Depth is bounded by the same cap that limits spawning, and an already-seen
+   * id is skipped so a corrupted link cannot loop.
+   */
+  async collectSubWorkflowFamily(root) {
+    const family = [root];
+    const seen = /* @__PURE__ */ new Set([root.id]);
+    const queue = [root];
+    for (let depth = 0; queue.length > 0 && depth <= MAX_SUBWORKFLOW_DEPTH; depth++) {
+      const generation = queue.splice(0, queue.length);
+      for (const parent of generation) {
+        for (const level of parent.levels) {
+          const childId = level.childInstanceId;
+          if (!childId || seen.has(childId)) continue;
+          seen.add(childId);
+          const child = await this.opts.adapter.getInstance(this.tenantId, childId);
+          if (!child) continue;
+          family.push(child);
+          queue.push(child);
+        }
+      }
+    }
+    return family;
+  }
+  /**
+   * Cancel sub-workflow children whose parent has finished.
+   *
+   * A child outlives its parent otherwise: it stays pending, keeps notifying
+   * and escalating, and keeps appearing in {@link getWorkload} — asking people
+   * to decide something whose outcome nobody will ever read, because
+   * {@link propagateToParent} ignores a parent that is no longer pending.
+   *
+   * Cancelling rather than deleting keeps the child's own audit trail intact:
+   * the people who were asked, and why the request stopped, stay on the record.
+   */
+  async cancelOrphanedChildren(parent) {
+    const childIds = parent.levels.map((l) => l.childInstanceId).filter((id) => typeof id === "string");
+    if (childIds.length === 0) return;
+    for (const childId of childIds) {
+      try {
+        const child = await this.opts.adapter.getInstance(this.tenantId, childId);
+        if (!child || TERMINAL_STATUSES.has(child.status)) continue;
+        await this.cancel(childId, {
+          cancelledBy: "system",
+          reason: `Parent approval ${parent.id} ended as "${parent.status}".`
+        });
+      } catch (err) {
+        this.logger.error("subWorkflow: failed to cancel orphaned child", err, {
+          tenantId: this.tenantId,
+          parentInstanceId: parent.id,
+          childInstanceId: childId
+        });
+      }
+    }
+  }
   async afterDecision(instance) {
     if (TERMINAL_STATUSES.has(instance.status)) {
+      await this.cancelOrphanedChildren(instance);
       await this.propagateToParent(instance);
       return;
     }