hierarchical-approval 2.8.0 → 3.0.0

package/dist/index.cjs

@@ -122,6 +122,266 @@ var UpdateDataOptionsSchema = zod.z.object({
   /** Re-evaluate template conditions against the new data (default true). */
   recomputeChain: zod.z.boolean().default(true)
 });
+
+// src/errors.ts
+var ApprovalError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "ApprovalError";
+  }
+  toJSON() {
+    return { code: this.code, message: this.message, name: this.name };
+  }
+  toHttpStatus() {
+    const map = {
+      NOT_FOUND: 404,
+      CONFLICT: 409,
+      FORBIDDEN: 403,
+      VALIDATION: 422,
+      TEMPLATE_NOT_FOUND: 404
+    };
+    return map[this.code] ?? 500;
+  }
+};
+var ApprovalNotFoundError = class extends ApprovalError {
+  constructor(resource, id) {
+    super(`${resource} "${id}" not found.`, "NOT_FOUND");
+    this.name = "ApprovalNotFoundError";
+  }
+};
+var ApprovalConflictError = class extends ApprovalError {
+  constructor(instanceId) {
+    super(
+      `Concurrent modification detected on instance "${instanceId}". The record was updated by another process. Please retry.`,
+      "CONFLICT"
+    );
+    this.name = "ApprovalConflictError";
+  }
+};
+var ApprovalForbiddenError = class extends ApprovalError {
+  constructor(message) {
+    super(message, "FORBIDDEN");
+    this.name = "ApprovalForbiddenError";
+  }
+};
+var ApprovalValidationError = class extends ApprovalError {
+  constructor(message, cause) {
+    super(message, "VALIDATION");
+    this.cause = cause;
+    this.name = "ApprovalValidationError";
+  }
+};
+var ApprovalTemplateNotFoundError = class extends ApprovalError {
+  constructor(name) {
+    super(`Template "${name}" not found.`, "TEMPLATE_NOT_FOUND");
+    this.name = "ApprovalTemplateNotFoundError";
+  }
+};
+
+// src/adapters/MemoryAdapter.ts
+function deepClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function reviveDates(instance) {
+  return {
+    ...instance,
+    createdAt: new Date(instance.createdAt),
+    updatedAt: new Date(instance.updatedAt),
+    expiresAt: instance.expiresAt ? new Date(instance.expiresAt) : void 0,
+    slaDeadlineAt: instance.slaDeadlineAt ? new Date(instance.slaDeadlineAt) : void 0,
+    slaBreachedAt: instance.slaBreachedAt ? new Date(instance.slaBreachedAt) : void 0,
+    auditLog: instance.auditLog.map((e) => ({ ...e, timestamp: new Date(e.timestamp) })),
+    infoRequest: instance.infoRequest ? { ...instance.infoRequest, askedAt: new Date(instance.infoRequest.askedAt) } : void 0,
+    attachments: instance.attachments ? instance.attachments.map((a) => ({ ...a, addedAt: new Date(a.addedAt) })) : void 0,
+    comments: instance.comments ? instance.comments.map((c) => ({ ...c, createdAt: new Date(c.createdAt) })) : void 0,
+    levels: instance.levels.map((l) => {
+      const level = { ...l };
+      if (l.escalationDueAt) level.escalationDueAt = new Date(l.escalationDueAt);
+      if (l.delegatedUntil) level.delegatedUntil = new Date(l.delegatedUntil);
+      if (l.reminderDueAt) level.reminderDueAt = new Date(l.reminderDueAt);
+      return level;
+    })
+  };
+}
+function reviveTemplateDates(template) {
+  return { ...template, createdAt: new Date(template.createdAt) };
+}
+function readPath(data, path) {
+  return path.split(".").reduce((obj, key) => {
+    if (obj !== null && typeof obj === "object" && Object.prototype.hasOwnProperty.call(obj, key)) {
+      return obj[key];
+    }
+    return void 0;
+  }, data);
+}
+function deepEquals(a, b) {
+  if (Object.is(a, b)) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  return aKeys.every(
+    (k) => Object.prototype.hasOwnProperty.call(b, k) && deepEquals(a[k], b[k])
+  );
+}
+function applyFilter(instance, filter) {
+  if (filter.status && instance.status !== filter.status) return false;
+  if (filter.documentType && instance.documentType !== filter.documentType) return false;
+  if (filter.submittedBy && instance.submittedBy !== filter.submittedBy) return false;
+  if (filter.templateName && instance.templateName !== filter.templateName) return false;
+  if (filter.fromDate && new Date(instance.createdAt) < filter.fromDate) return false;
+  if (filter.toDate && new Date(instance.createdAt) > filter.toDate) return false;
+  if (filter.data) {
+    for (const [path, expected] of Object.entries(filter.data)) {
+      if (!deepEquals(readPath(instance.data ?? {}, path), expected)) return false;
+    }
+  }
+  return true;
+}
+var MemoryAdapter = class {
+  constructor() {
+    // keyed by `${tenantId}:${template.name}`
+    this.templates = /* @__PURE__ */ new Map();
+    // keyed by `${tenantId}:${instance.id}`
+    this.instances = /* @__PURE__ */ new Map();
+  }
+  async saveTemplate(template) {
+    this.templates.set(`${template.tenantId}:${template.name}`, deepClone(template));
+  }
+  async getTemplate(tenantId, name) {
+    const template = this.templates.get(`${tenantId}:${name}`);
+    return template ? reviveTemplateDates(deepClone(template)) : null;
+  }
+  async listTemplates(tenantId) {
+    const result = [];
+    for (const [key, template] of this.templates) {
+      if (key.startsWith(`${tenantId}:`)) {
+        result.push(reviveTemplateDates(deepClone(template)));
+      }
+    }
+    return result;
+  }
+  async saveInstance(instance) {
+    this.instances.set(`${instance.tenantId}:${instance.id}`, deepClone(instance));
+  }
+  async updateInstance(instance, expectedVersion) {
+    const key = `${instance.tenantId}:${instance.id}`;
+    const stored = this.instances.get(key);
+    if (!stored) throw new ApprovalConflictError(instance.id);
+    if (stored.version !== expectedVersion) throw new ApprovalConflictError(instance.id);
+    const updated = deepClone(instance);
+    updated.version = expectedVersion + 1;
+    this.instances.set(key, updated);
+  }
+  async getInstance(tenantId, id) {
+    const raw = this.instances.get(`${tenantId}:${id}`);
+    if (!raw) return null;
+    return reviveDates(deepClone(raw));
+  }
+  async getInstancesByApprover(tenantId, approverId, opts) {
+    const all = [...this.instances.values()].filter((i) => {
+      if (i.tenantId !== tenantId || i.status !== "pending") return false;
+      const currentLevel = i.levels.find((l) => l.level === i.currentLevel);
+      return currentLevel?.approverIds.includes(approverId) ?? false;
+    });
+    return paginate(
+      all.map((i) => reviveDates(deepClone(i))),
+      opts
+    );
+  }
+  async getInstancesByFilter(tenantId, filter, opts) {
+    const all = [...this.instances.values()].filter(
+      (i) => i.tenantId === tenantId && applyFilter(i, filter)
+    );
+    return paginate(
+      all.map((i) => reviveDates(deepClone(i))),
+      opts
+    );
+  }
+  async getOverdueInstances(tenantId, asOf, filter = {}) {
+    return [...this.instances.values()].filter((i) => {
+      if (i.tenantId !== tenantId || i.status !== "pending") return false;
+      if (filter.documentType && i.documentType !== filter.documentType) return false;
+      if (filter.submittedBy && i.submittedBy !== filter.submittedBy) return false;
+      const hasOverdueEscalation = i.levels.some(
+        (l) => l.escalationDueAt != null && new Date(l.escalationDueAt) <= asOf
+      );
+      const isExpired = i.expiresAt != null && new Date(i.expiresAt) <= asOf;
+      const hasSLABreach = i.slaDeadlineAt != null && new Date(i.slaDeadlineAt) <= asOf && !i.slaBreachedAt;
+      const hasDelegationExpiry = i.levels.some(
+        (l) => l.status === "pending" && l.delegatedUntil != null && new Date(l.delegatedUntil) <= asOf && l.delegatedFrom != null
+      );
+      const hasDueReminder = i.levels.some(
+        (l) => l.status === "pending" && l.reminderDueAt != null && new Date(l.reminderDueAt) <= asOf
+      );
+      return hasOverdueEscalation || isExpired || hasSLABreach || hasDelegationExpiry || hasDueReminder;
+    }).map((i) => reviveDates(deepClone(i)));
+  }
+  async deleteInstance(tenantId, id) {
+    const key = `${tenantId}:${id}`;
+    return this.instances.delete(key);
+  }
+  async countInstances(tenantId, filter) {
+    let count = 0;
+    for (const instance of this.instances.values()) {
+      if (instance.tenantId === tenantId && applyFilter(instance, filter)) count++;
+    }
+    return count;
+  }
+  async getInstancesByCursor(tenantId, filter, opts) {
+    const all = [...this.instances.values()].filter((i) => i.tenantId === tenantId && applyFilter(i, filter)).map((i) => reviveDates(deepClone(i))).sort((a, b) => {
+      const ta = a.updatedAt.getTime();
+      const tb = b.updatedAt.getTime();
+      return ta !== tb ? ta - tb : a.id.localeCompare(b.id);
+    });
+    const { cursor, limit, direction = "forward" } = opts;
+    let startIdx = 0;
+    if (cursor) {
+      const [ts, id] = decodeCursor(cursor);
+      const idx = all.findIndex(
+        (i) => i.updatedAt.getTime() > ts || i.updatedAt.getTime() === ts && i.id > id
+      );
+      startIdx = idx === -1 ? all.length : idx;
+    }
+    if (direction === "backward" && startIdx > 0) {
+      startIdx = Math.max(0, startIdx - limit - 1);
+    }
+    const slice = all.slice(startIdx, startIdx + limit);
+    const hasMore = startIdx + limit < all.length;
+    const nextCursor = hasMore ? encodeCursor(slice[slice.length - 1]) : void 0;
+    const prevCursor = startIdx > 0 ? encodeCursor(all[startIdx - 1]) : void 0;
+    return { items: slice, nextCursor, prevCursor, hasMore };
+  }
+  async getIdempotentInstance(tenantId, idempotencyKey) {
+    for (const instance of this.instances.values()) {
+      if (instance.tenantId === tenantId && instance.idempotencyKey === idempotencyKey) {
+        return reviveDates(deepClone(instance));
+      }
+    }
+    return null;
+  }
+  async appendAuditEntry(_tenantId, _instanceId, _entry) {
+  }
+  /** Test helper — total stored instances across all tenants. */
+  get size() {
+    return this.instances.size;
+  }
+};
+function paginate(items, opts) {
+  const total = items.length;
+  if (!opts) return { items, total };
+  return { items: items.slice(opts.offset, opts.offset + opts.limit), total };
+}
+function encodeCursor(instance) {
+  return Buffer.from(`${instance.updatedAt.getTime()}|${instance.id}`).toString("base64");
+}
+function decodeCursor(cursor) {
+  const decoded = Buffer.from(cursor, "base64").toString("utf8");
+  const pipeIdx = decoded.indexOf("|");
+  return [Number(decoded.slice(0, pipeIdx)), decoded.slice(pipeIdx + 1)];
+}
 var EventBus = class {
   constructor() {
     this.emitter = new EventEmitter__default.default();
@@ -206,62 +466,6 @@ var systemClock = { now: () => /* @__PURE__ */ new Date() };
 // src/utils/IdGenerator.ts
 var defaultIdGenerator = (prefix) => `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 
-// src/errors.ts
-var ApprovalError = class extends Error {
-  constructor(message, code) {
-    super(message);
-    this.code = code;
-    this.name = "ApprovalError";
-  }
-  toJSON() {
-    return { code: this.code, message: this.message, name: this.name };
-  }
-  toHttpStatus() {
-    const map = {
-      NOT_FOUND: 404,
-      CONFLICT: 409,
-      FORBIDDEN: 403,
-      VALIDATION: 422,
-      TEMPLATE_NOT_FOUND: 404
-    };
-    return map[this.code] ?? 500;
-  }
-};
-var ApprovalNotFoundError = class extends ApprovalError {
-  constructor(resource, id) {
-    super(`${resource} "${id}" not found.`, "NOT_FOUND");
-    this.name = "ApprovalNotFoundError";
-  }
-};
-var ApprovalConflictError = class extends ApprovalError {
-  constructor(instanceId) {
-    super(
-      `Concurrent modification detected on instance "${instanceId}". The record was updated by another process. Please retry.`,
-      "CONFLICT"
-    );
-    this.name = "ApprovalConflictError";
-  }
-};
-var ApprovalForbiddenError = class extends ApprovalError {
-  constructor(message) {
-    super(message, "FORBIDDEN");
-    this.name = "ApprovalForbiddenError";
-  }
-};
-var ApprovalValidationError = class extends ApprovalError {
-  constructor(message, cause) {
-    super(message, "VALIDATION");
-    this.cause = cause;
-    this.name = "ApprovalValidationError";
-  }
-};
-var ApprovalTemplateNotFoundError = class extends ApprovalError {
-  constructor(name) {
-    super(`Template "${name}" not found.`, "TEMPLATE_NOT_FOUND");
-    this.name = "ApprovalTemplateNotFoundError";
-  }
-};
-
 // src/engine/TemplateRegistry.ts
 var TemplateRegistry = class {
   constructor(adapter, tenantId, opts) {
@@ -389,6 +593,17 @@ var LevelResolver = class {
   registerApproverType(typeName, fn) {
     this.approverTypes.set(typeName, fn);
   }
+  /**
+   * Copy every custom resolver and approver type onto another resolver.
+   *
+   * Used when the engine builds a throwaway copy of itself for a simulation: a
+   * simulation that could not resolve the caller's own `dynamic` approvers
+   * would answer a different question from the one asked.
+   */
+  copyRegistrationsTo(target) {
+    for (const [name, fn] of this.resolvers) target.register(name, fn);
+    for (const [name, fn] of this.approverTypes) target.registerApproverType(name, fn);
+  }
   async resolveApprovers(approvers, submittedBy, data, orgProvider, outOfOffice, at) {
     const resolved = [];
     for (const approver of approvers) {
@@ -1260,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 = [];
@@ -1961,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) {
@@ -2114,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 };
@@ -2828,14 +3014,120 @@ var ApprovalEngine = class _ApprovalEngine {
       } catch (err) {
         base.resolutionError = err.message;
       }
-      levels.push(base);
+      levels.push(base);
+    }
+    const skipped = template.levels.filter((l) => mutations.skipLevels.has(l.level)).map((l) => ({
+      level: l.level,
+      name: l.name,
+      skippedByRule: skippedBy.get(l.level) ?? -1
+    })).sort((a, b) => a.level - b.level);
+    return { templateName: template.name, levels, skipped, rules };
+  }
+  /**
+   * Run a document through a template against scripted decisions, without
+   * persisting anything.
+   *
+   * `explainChain()` says what the chain will be; this says what happens to it —
+   * "if the CFO rejects at level 3, does it go back to the submitter or die?" —
+   * which previously meant submitting a real approval into a real store and
+   * cleaning it up afterwards, or reasoning about the state machine by hand.
+   *
+   * The run executes against a private in-memory store seeded with a copy of
+   * the template, so the caller's storage is untouched and no events reach the
+   * caller's notification adapters. Custom resolvers and approver types are
+   * copied across, because a simulation that could not resolve the caller's own
+   * `dynamic` approvers would answer a different question from the one asked.
+   *
+   * A refused decision — wrong approver, wrong level, already acted — stops the
+   * run and is reported in the transcript rather than thrown: the refusal is
+   * usually the answer the caller was looking for.
+   *
+   * @param opts - Template, document data, submitter and the decisions to play.
+   */
+  async simulate(opts) {
+    const template = await this.registry.get(opts.templateName);
+    const scratch = new _ApprovalEngine({
+      ...this.opts,
+      adapter: new MemoryAdapter(),
+      // A simulation must not page anybody, write anybody's audit log, or move
+      // anybody's metrics.
+      notificationAdapter: void 0,
+      auditAdapter: void 0,
+      metricsAdapter: void 0,
+      authorizationPolicy: void 0,
+      middleware: void 0,
+      escalationPollIntervalMs: void 0
+    });
+    this.resolver.copyRegistrationsTo(scratch.resolver);
+    try {
+      const {
+        id: _id,
+        tenantId: _t,
+        createdAt: _c,
+        version: _v,
+        previousVersionId: _p,
+        ...config
+      } = template;
+      await scratch.registry.define(config);
+      const instance = await scratch.submit({
+        templateName: opts.templateName,
+        documentId: `simulation-${opts.templateName}`,
+        documentType: template.documentType,
+        submittedBy: opts.submittedBy,
+        data: opts.data,
+        metadata: {}
+      });
+      const transcript = [];
+      let current = instance;
+      for (const [i, decision] of (opts.decisions ?? []).entries()) {
+        const isApprove = "approve" in decision;
+        const actorId = isApprove ? decision.approve : decision.reject;
+        try {
+          current = isApprove ? await scratch.approve(current.id, {
+            approverId: actorId,
+            level: decision.level,
+            comment: decision.comment
+          }) : await scratch.reject(current.id, {
+            approverId: actorId,
+            level: decision.level,
+            reason: decision.reason ?? "simulated rejection"
+          });
+          transcript.push({
+            step: i + 1,
+            action: isApprove ? "approve" : "reject",
+            actorId,
+            level: decision.level,
+            status: current.status
+          });
+        } catch (err) {
+          transcript.push({
+            step: i + 1,
+            action: isApprove ? "approve" : "reject",
+            actorId,
+            level: decision.level,
+            status: current.status,
+            error: err.message
+          });
+          break;
+        }
+        if (TERMINAL_STATUSES.has(current.status)) break;
+      }
+      const finalInstance = await scratch.getInstance(current.id);
+      return {
+        finalStatus: finalInstance.status,
+        levels: finalInstance.levels.map((l) => ({
+          level: l.level,
+          name: l.name,
+          status: l.status,
+          approvers: l.approverIds
+        })),
+        transcript,
+        unreachedLevels: finalInstance.levels.filter((l) => l.status === "waiting").map((l) => l.level),
+        incomplete: finalInstance.status === "pending"
+      };
+    } finally {
+      await scratch.shutdown();
     }
-    const skipped = template.levels.filter((l) => mutations.skipLevels.has(l.level)).map((l) => ({
-      level: l.level,
-      name: l.name,
-      skippedByRule: skippedBy.get(l.level) ?? -1
-    })).sort((a, b) => a.level - b.level);
-    return { templateName: template.name, levels, skipped, rules };
   }
   async canApprove(instanceId, userId) {
     let instance;
@@ -3338,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(
@@ -3351,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", {
@@ -3735,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);
@@ -4186,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;
     }
@@ -4307,210 +4707,6 @@ function parseOrThrow(fn) {
   }
 }
 
-// src/adapters/MemoryAdapter.ts
-function deepClone(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-function reviveDates(instance) {
-  return {
-    ...instance,
-    createdAt: new Date(instance.createdAt),
-    updatedAt: new Date(instance.updatedAt),
-    expiresAt: instance.expiresAt ? new Date(instance.expiresAt) : void 0,
-    slaDeadlineAt: instance.slaDeadlineAt ? new Date(instance.slaDeadlineAt) : void 0,
-    slaBreachedAt: instance.slaBreachedAt ? new Date(instance.slaBreachedAt) : void 0,
-    auditLog: instance.auditLog.map((e) => ({ ...e, timestamp: new Date(e.timestamp) })),
-    infoRequest: instance.infoRequest ? { ...instance.infoRequest, askedAt: new Date(instance.infoRequest.askedAt) } : void 0,
-    attachments: instance.attachments ? instance.attachments.map((a) => ({ ...a, addedAt: new Date(a.addedAt) })) : void 0,
-    comments: instance.comments ? instance.comments.map((c) => ({ ...c, createdAt: new Date(c.createdAt) })) : void 0,
-    levels: instance.levels.map((l) => {
-      const level = { ...l };
-      if (l.escalationDueAt) level.escalationDueAt = new Date(l.escalationDueAt);
-      if (l.delegatedUntil) level.delegatedUntil = new Date(l.delegatedUntil);
-      if (l.reminderDueAt) level.reminderDueAt = new Date(l.reminderDueAt);
-      return level;
-    })
-  };
-}
-function reviveTemplateDates(template) {
-  return { ...template, createdAt: new Date(template.createdAt) };
-}
-function readPath(data, path) {
-  return path.split(".").reduce((obj, key) => {
-    if (obj !== null && typeof obj === "object" && Object.prototype.hasOwnProperty.call(obj, key)) {
-      return obj[key];
-    }
-    return void 0;
-  }, data);
-}
-function deepEquals(a, b) {
-  if (Object.is(a, b)) return true;
-  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
-  if (Array.isArray(a) !== Array.isArray(b)) return false;
-  const aKeys = Object.keys(a);
-  const bKeys = Object.keys(b);
-  if (aKeys.length !== bKeys.length) return false;
-  return aKeys.every(
-    (k) => Object.prototype.hasOwnProperty.call(b, k) && deepEquals(a[k], b[k])
-  );
-}
-function applyFilter(instance, filter) {
-  if (filter.status && instance.status !== filter.status) return false;
-  if (filter.documentType && instance.documentType !== filter.documentType) return false;
-  if (filter.submittedBy && instance.submittedBy !== filter.submittedBy) return false;
-  if (filter.templateName && instance.templateName !== filter.templateName) return false;
-  if (filter.fromDate && new Date(instance.createdAt) < filter.fromDate) return false;
-  if (filter.toDate && new Date(instance.createdAt) > filter.toDate) return false;
-  if (filter.data) {
-    for (const [path, expected] of Object.entries(filter.data)) {
-      if (!deepEquals(readPath(instance.data ?? {}, path), expected)) return false;
-    }
-  }
-  return true;
-}
-var MemoryAdapter = class {
-  constructor() {
-    // keyed by `${tenantId}:${template.name}`
-    this.templates = /* @__PURE__ */ new Map();
-    // keyed by `${tenantId}:${instance.id}`
-    this.instances = /* @__PURE__ */ new Map();
-  }
-  async saveTemplate(template) {
-    this.templates.set(`${template.tenantId}:${template.name}`, deepClone(template));
-  }
-  async getTemplate(tenantId, name) {
-    const template = this.templates.get(`${tenantId}:${name}`);
-    return template ? reviveTemplateDates(deepClone(template)) : null;
-  }
-  async listTemplates(tenantId) {
-    const result = [];
-    for (const [key, template] of this.templates) {
-      if (key.startsWith(`${tenantId}:`)) {
-        result.push(reviveTemplateDates(deepClone(template)));
-      }
-    }
-    return result;
-  }
-  async saveInstance(instance) {
-    this.instances.set(`${instance.tenantId}:${instance.id}`, deepClone(instance));
-  }
-  async updateInstance(instance, expectedVersion) {
-    const key = `${instance.tenantId}:${instance.id}`;
-    const stored = this.instances.get(key);
-    if (!stored) throw new ApprovalConflictError(instance.id);
-    if (stored.version !== expectedVersion) throw new ApprovalConflictError(instance.id);
-    const updated = deepClone(instance);
-    updated.version = expectedVersion + 1;
-    this.instances.set(key, updated);
-  }
-  async getInstance(tenantId, id) {
-    const raw = this.instances.get(`${tenantId}:${id}`);
-    if (!raw) return null;
-    return reviveDates(deepClone(raw));
-  }
-  async getInstancesByApprover(tenantId, approverId, opts) {
-    const all = [...this.instances.values()].filter((i) => {
-      if (i.tenantId !== tenantId || i.status !== "pending") return false;
-      const currentLevel = i.levels.find((l) => l.level === i.currentLevel);
-      return currentLevel?.approverIds.includes(approverId) ?? false;
-    });
-    return paginate(
-      all.map((i) => reviveDates(deepClone(i))),
-      opts
-    );
-  }
-  async getInstancesByFilter(tenantId, filter, opts) {
-    const all = [...this.instances.values()].filter(
-      (i) => i.tenantId === tenantId && applyFilter(i, filter)
-    );
-    return paginate(
-      all.map((i) => reviveDates(deepClone(i))),
-      opts
-    );
-  }
-  async getOverdueInstances(tenantId, asOf, filter = {}) {
-    return [...this.instances.values()].filter((i) => {
-      if (i.tenantId !== tenantId || i.status !== "pending") return false;
-      if (filter.documentType && i.documentType !== filter.documentType) return false;
-      if (filter.submittedBy && i.submittedBy !== filter.submittedBy) return false;
-      const hasOverdueEscalation = i.levels.some(
-        (l) => l.escalationDueAt != null && new Date(l.escalationDueAt) <= asOf
-      );
-      const isExpired = i.expiresAt != null && new Date(i.expiresAt) <= asOf;
-      const hasSLABreach = i.slaDeadlineAt != null && new Date(i.slaDeadlineAt) <= asOf && !i.slaBreachedAt;
-      const hasDelegationExpiry = i.levels.some(
-        (l) => l.status === "pending" && l.delegatedUntil != null && new Date(l.delegatedUntil) <= asOf && l.delegatedFrom != null
-      );
-      const hasDueReminder = i.levels.some(
-        (l) => l.status === "pending" && l.reminderDueAt != null && new Date(l.reminderDueAt) <= asOf
-      );
-      return hasOverdueEscalation || isExpired || hasSLABreach || hasDelegationExpiry || hasDueReminder;
-    }).map((i) => reviveDates(deepClone(i)));
-  }
-  async deleteInstance(tenantId, id) {
-    const key = `${tenantId}:${id}`;
-    return this.instances.delete(key);
-  }
-  async countInstances(tenantId, filter) {
-    let count = 0;
-    for (const instance of this.instances.values()) {
-      if (instance.tenantId === tenantId && applyFilter(instance, filter)) count++;
-    }
-    return count;
-  }
-  async getInstancesByCursor(tenantId, filter, opts) {
-    const all = [...this.instances.values()].filter((i) => i.tenantId === tenantId && applyFilter(i, filter)).map((i) => reviveDates(deepClone(i))).sort((a, b) => {
-      const ta = a.updatedAt.getTime();
-      const tb = b.updatedAt.getTime();
-      return ta !== tb ? ta - tb : a.id.localeCompare(b.id);
-    });
-    const { cursor, limit, direction = "forward" } = opts;
-    let startIdx = 0;
-    if (cursor) {
-      const [ts, id] = decodeCursor(cursor);
-      const idx = all.findIndex(
-        (i) => i.updatedAt.getTime() > ts || i.updatedAt.getTime() === ts && i.id > id
-      );
-      startIdx = idx === -1 ? all.length : idx;
-    }
-    if (direction === "backward" && startIdx > 0) {
-      startIdx = Math.max(0, startIdx - limit - 1);
-    }
-    const slice = all.slice(startIdx, startIdx + limit);
-    const hasMore = startIdx + limit < all.length;
-    const nextCursor = hasMore ? encodeCursor(slice[slice.length - 1]) : void 0;
-    const prevCursor = startIdx > 0 ? encodeCursor(all[startIdx - 1]) : void 0;
-    return { items: slice, nextCursor, prevCursor, hasMore };
-  }
-  async getIdempotentInstance(tenantId, idempotencyKey) {
-    for (const instance of this.instances.values()) {
-      if (instance.tenantId === tenantId && instance.idempotencyKey === idempotencyKey) {
-        return reviveDates(deepClone(instance));
-      }
-    }
-    return null;
-  }
-  async appendAuditEntry(_tenantId, _instanceId, _entry) {
-  }
-  /** Test helper — total stored instances across all tenants. */
-  get size() {
-    return this.instances.size;
-  }
-};
-function paginate(items, opts) {
-  const total = items.length;
-  if (!opts) return { items, total };
-  return { items: items.slice(opts.offset, opts.offset + opts.limit), total };
-}
-function encodeCursor(instance) {
-  return Buffer.from(`${instance.updatedAt.getTime()}|${instance.id}`).toString("base64");
-}
-function decodeCursor(cursor) {
-  const decoded = Buffer.from(cursor, "base64").toString("utf8");
-  const pipeIdx = decoded.indexOf("|");
-  return [Number(decoded.slice(0, pipeIdx)), decoded.slice(pipeIdx + 1)];
-}
-
 // src/utils/BusinessCalendar.ts
 var DAY_MS = 864e5;
 function dayKey(d) {