hierarchical-approval 2.0.0 → 2.2.0

package/dist/{instance-BE0uJmg3.d.cts → instance-DUJY_Axf.d.cts}

@@ -43,6 +43,21 @@ interface ApprovalLevelConfig {
      * own group of one.
      */
     group?: string;
+    /**
+     * Delegate this level to a whole separate approval, rather than to a list of
+     * approvers.
+     *
+     * When the level opens, a child instance is submitted against
+     * {@link SubWorkflowConfig.templateName}. The parent level stays open until
+     * that child finishes, then takes its outcome: approved advances the parent,
+     * rejected rejects it. Models "a capital request over 1M needs its own board
+     * approval before this purchase order can proceed" without flattening the
+     * board's chain into the purchase order's.
+     *
+     * A level with `subWorkflow` needs no `approvers` — nobody approves it
+     * directly; the child does.
+     */
+    subWorkflow?: SubWorkflowConfig;
     escalationAfterDays?: number;
     /**
      * Send a reminder to this level's pending approvers this many days after the
@@ -103,6 +118,18 @@ type ConditionGroup = {
  * explicit combinator.
  */
 type ConditionExpression = Condition | ConditionExpression[] | ConditionGroup;
+/** How a level hands off to a child approval. See {@link ApprovalLevelConfig.subWorkflow}. */
+interface SubWorkflowConfig {
+    /** Template the child instance is submitted against. */
+    templateName: string;
+    /**
+     * Copy the parent's document data into the child (default `true`), so the
+     * child's own conditions can be evaluated against the same document.
+     */
+    carryData?: boolean;
+    /** Document type for the child; defaults to the child template's own. */
+    documentType?: string;
+}
 interface ConditionRule {
     /**
      * The test that decides whether this rule's mutations apply. An array means
@@ -154,7 +181,7 @@ interface ApprovalTemplate extends ApprovalTemplateConfig {
 
 type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'cancelled' | 'expired';
 type LevelStatus = 'waiting' | 'pending' | 'approved' | 'rejected' | 'skipped';
-type AuditAction = 'submitted' | 'approved' | 'rejected' | 'delegated' | 'reassigned' | 'escalated' | 'cancelled' | 'level_advanced' | 'commented' | 'resubmitted' | 'overridden' | 'data_updated' | 'reminded' | 'info_requested' | 'info_provided' | 'attachment_added' | 'attachment_removed' | 'expired';
+type AuditAction = 'submitted' | 'approved' | 'rejected' | 'delegated' | 'reassigned' | 'escalated' | 'cancelled' | 'level_advanced' | 'commented' | 'resubmitted' | 'overridden' | 'data_updated' | 'reminded' | 'info_requested' | 'info_provided' | 'attachment_added' | 'attachment_removed' | 'subworkflow_started' | 'subworkflow_completed' | 'expired';
 interface AuditEntry {
     action: AuditAction;
     actorId: string;
@@ -182,6 +209,10 @@ interface ApprovalLevelInstance {
     name: string;
     /** Parallel branch group this level belongs to; absent for sequential levels. */
     group?: string;
+    /** Id of the child instance this level is waiting on, when it delegates to a sub-workflow. */
+    childInstanceId?: string;
+    /** Template the child was submitted against; kept for display and diagnostics. */
+    subWorkflowTemplate?: string;
     mode: ApprovalMode;
     approverConfigs: ApproverConfig[];
     approverIds: string[];
@@ -272,8 +303,15 @@ interface ApprovalInstance {
     updatedAt: Date;
     /** Snapshot of template config at submit time — prevents template changes from affecting in-flight instances. */
     templateSnapshot?: TemplateSnapshot;
-    /** ID of the rejected instance this was resubmitted from. */
+    /**
+     * ID of the parent instance — set both when this was resubmitted from a
+     * rejected instance and when it is a sub-workflow child.
+     */
     parentInstanceId?: string;
+    /** Parent level this instance was spawned for, when it is a sub-workflow child. */
+    parentLevel?: number;
+    /** How many sub-workflow hops deep this instance sits. 0 for a top-level approval. */
+    subWorkflowDepth?: number;
     /** Auto-cancel or auto-reject if not resolved by this time. */
     expiresAt?: Date;
     /** What happens when expiresAt is reached (default: 'cancel'). */
@@ -291,4 +329,4 @@ interface ApprovalInstance {
     attachments?: Attachment[];
 }
 
-export type { ApprovalTemplate as A, Condition as C, EscalationConfig as E, InfoRequest as I, LevelStatus as L, ResolvedApprover as R, TemplateSnapshot as T, ApprovalInstance as a, AuditEntry as b, ApprovalLevelConfig as c, ApprovalLevelInstance as d, ApprovalMode as e, ApprovalStatus as f, ApprovalTemplateConfig as g, ApproverConfig as h, Attachment as i, AuditAction as j, AuditContext as k, ConditionExpression as l, ConditionGroup as m, ConditionOperator as n, ConditionRule as o, ResolverFn as p };
+export type { ApprovalTemplate as A, Condition as C, EscalationConfig as E, InfoRequest as I, LevelStatus as L, ResolvedApprover as R, SubWorkflowConfig as S, TemplateSnapshot as T, ApprovalInstance as a, AuditEntry as b, ApprovalLevelConfig as c, ApprovalLevelInstance as d, ApprovalMode as e, ApprovalStatus as f, ApprovalTemplateConfig as g, ApproverConfig as h, Attachment as i, AuditAction as j, AuditContext as k, ConditionExpression as l, ConditionGroup as m, ConditionOperator as n, ConditionRule as o, ResolverFn as p };

package/dist/{instance-BE0uJmg3.d.ts → instance-DUJY_Axf.d.ts}

@@ -43,6 +43,21 @@ interface ApprovalLevelConfig {
      * own group of one.
      */
     group?: string;
+    /**
+     * Delegate this level to a whole separate approval, rather than to a list of
+     * approvers.
+     *
+     * When the level opens, a child instance is submitted against
+     * {@link SubWorkflowConfig.templateName}. The parent level stays open until
+     * that child finishes, then takes its outcome: approved advances the parent,
+     * rejected rejects it. Models "a capital request over 1M needs its own board
+     * approval before this purchase order can proceed" without flattening the
+     * board's chain into the purchase order's.
+     *
+     * A level with `subWorkflow` needs no `approvers` — nobody approves it
+     * directly; the child does.
+     */
+    subWorkflow?: SubWorkflowConfig;
     escalationAfterDays?: number;
     /**
      * Send a reminder to this level's pending approvers this many days after the
@@ -103,6 +118,18 @@ type ConditionGroup = {
  * explicit combinator.
  */
 type ConditionExpression = Condition | ConditionExpression[] | ConditionGroup;
+/** How a level hands off to a child approval. See {@link ApprovalLevelConfig.subWorkflow}. */
+interface SubWorkflowConfig {
+    /** Template the child instance is submitted against. */
+    templateName: string;
+    /**
+     * Copy the parent's document data into the child (default `true`), so the
+     * child's own conditions can be evaluated against the same document.
+     */
+    carryData?: boolean;
+    /** Document type for the child; defaults to the child template's own. */
+    documentType?: string;
+}
 interface ConditionRule {
     /**
      * The test that decides whether this rule's mutations apply. An array means
@@ -154,7 +181,7 @@ interface ApprovalTemplate extends ApprovalTemplateConfig {
 
 type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'cancelled' | 'expired';
 type LevelStatus = 'waiting' | 'pending' | 'approved' | 'rejected' | 'skipped';
-type AuditAction = 'submitted' | 'approved' | 'rejected' | 'delegated' | 'reassigned' | 'escalated' | 'cancelled' | 'level_advanced' | 'commented' | 'resubmitted' | 'overridden' | 'data_updated' | 'reminded' | 'info_requested' | 'info_provided' | 'attachment_added' | 'attachment_removed' | 'expired';
+type AuditAction = 'submitted' | 'approved' | 'rejected' | 'delegated' | 'reassigned' | 'escalated' | 'cancelled' | 'level_advanced' | 'commented' | 'resubmitted' | 'overridden' | 'data_updated' | 'reminded' | 'info_requested' | 'info_provided' | 'attachment_added' | 'attachment_removed' | 'subworkflow_started' | 'subworkflow_completed' | 'expired';
 interface AuditEntry {
     action: AuditAction;
     actorId: string;
@@ -182,6 +209,10 @@ interface ApprovalLevelInstance {
     name: string;
     /** Parallel branch group this level belongs to; absent for sequential levels. */
     group?: string;
+    /** Id of the child instance this level is waiting on, when it delegates to a sub-workflow. */
+    childInstanceId?: string;
+    /** Template the child was submitted against; kept for display and diagnostics. */
+    subWorkflowTemplate?: string;
     mode: ApprovalMode;
     approverConfigs: ApproverConfig[];
     approverIds: string[];
@@ -272,8 +303,15 @@ interface ApprovalInstance {
     updatedAt: Date;
     /** Snapshot of template config at submit time — prevents template changes from affecting in-flight instances. */
     templateSnapshot?: TemplateSnapshot;
-    /** ID of the rejected instance this was resubmitted from. */
+    /**
+     * ID of the parent instance — set both when this was resubmitted from a
+     * rejected instance and when it is a sub-workflow child.
+     */
     parentInstanceId?: string;
+    /** Parent level this instance was spawned for, when it is a sub-workflow child. */
+    parentLevel?: number;
+    /** How many sub-workflow hops deep this instance sits. 0 for a top-level approval. */
+    subWorkflowDepth?: number;
     /** Auto-cancel or auto-reject if not resolved by this time. */
     expiresAt?: Date;
     /** What happens when expiresAt is reached (default: 'cancel'). */
@@ -291,4 +329,4 @@ interface ApprovalInstance {
     attachments?: Attachment[];
 }
 
-export type { ApprovalTemplate as A, Condition as C, EscalationConfig as E, InfoRequest as I, LevelStatus as L, ResolvedApprover as R, TemplateSnapshot as T, ApprovalInstance as a, AuditEntry as b, ApprovalLevelConfig as c, ApprovalLevelInstance as d, ApprovalMode as e, ApprovalStatus as f, ApprovalTemplateConfig as g, ApproverConfig as h, Attachment as i, AuditAction as j, AuditContext as k, ConditionExpression as l, ConditionGroup as m, ConditionOperator as n, ConditionRule as o, ResolverFn as p };
+export type { ApprovalTemplate as A, Condition as C, EscalationConfig as E, InfoRequest as I, LevelStatus as L, ResolvedApprover as R, SubWorkflowConfig as S, TemplateSnapshot as T, ApprovalInstance as a, AuditEntry as b, ApprovalLevelConfig as c, ApprovalLevelInstance as d, ApprovalMode as e, ApprovalStatus as f, ApprovalTemplateConfig as g, ApproverConfig as h, Attachment as i, AuditAction as j, AuditContext as k, ConditionExpression as l, ConditionGroup as m, ConditionOperator as n, ConditionRule as o, ResolverFn as p };

package/dist/nestjs.cjs

@@ -915,6 +915,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;
@@ -926,6 +927,7 @@ var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
 ]);
 var CYCLE_TIME_STATUSES = ["approved", "rejected", "cancelled"];
 var CYCLE_TIME_FETCH_BATCH_SIZE = 500;
+var TEMPLATE_BUNDLE_VERSION = 1;
 var ApprovalEngine = class _ApprovalEngine {
   constructor(opts) {
     this.opts = opts;
@@ -1019,12 +1021,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`,
@@ -1167,7 +1189,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);
@@ -1227,6 +1249,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,
@@ -1235,6 +1258,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,
@@ -1255,6 +1282,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,
@@ -1319,12 +1349,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(
@@ -1537,10 +1568,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(
@@ -1659,6 +1692,8 @@ var ApprovalEngine = class _ApprovalEngine {
       }
       return instance;
     });
+    await this.afterDecision(decided);
+    return decided;
   }
   async delegate(instanceId, raw, auditCtx) {
     const opts = parseOrThrow(() => DelegateOptionsSchema.parse(raw));
@@ -1836,7 +1871,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");
       }
@@ -1890,8 +1926,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));
@@ -2970,6 +3009,118 @@ var ApprovalEngine = class _ApprovalEngine {
       oldestAgeMs: Number.isFinite(row.oldest) ? now.getTime() - row.oldest : 0
     })).sort((a, b) => b.pending - a.pending || a.approverId.localeCompare(b.approverId));
   }
+  /**
+   * Export templates as a portable bundle.
+   *
+   * Approval configuration is written once and then has to travel — authored in
+   * a sandbox, reviewed, promoted to production. Reading `listTemplates()` and
+   * re-posting the rows carried each environment's own `id`, `tenantId` and
+   * version lineage with it, which either collided on arrival or silently
+   * claimed a history the target never had. This strips all of it.
+   *
+   * @param names - Templates to include; omit for all of them.
+   */
+  async exportTemplates(names) {
+    const all = await this.registry.list();
+    const wanted = names ? all.filter((t) => names.includes(t.name)) : all;
+    if (names) {
+      const missing = names.filter((n) => !all.some((t) => t.name === n));
+      if (missing.length > 0) {
+        throw new ApprovalTemplateNotFoundError(missing.join(", "));
+      }
+    }
+    return {
+      bundleVersion: TEMPLATE_BUNDLE_VERSION,
+      exportedAt: this.clock.now(),
+      templates: wanted.map((t) => {
+        const {
+          id: _id,
+          tenantId: _tenantId,
+          createdAt: _createdAt,
+          version: _version,
+          previousVersionId: _previousVersionId,
+          ...config
+        } = t;
+        return config;
+      })
+    };
+  }
+  /**
+   * Import a bundle produced by {@link exportTemplates}.
+   *
+   * **Every template is validated before any is written.** A bundle that is
+   * half-applied is worse than one rejected outright: the tenant is left in a
+   * state matching neither environment, and the operator has no way to tell
+   * which half landed. Per-template failures during the write phase are still
+   * reported individually, since a storage error can occur after validation
+   * passes.
+   *
+   * @param bundle - The bundle to apply.
+   * @param opts - `mode: 'create'` (default) refuses to touch existing
+   *   templates; `'upsert'` updates them. `dryRun` reports without writing.
+   */
+  async importTemplates(bundle, opts = {}) {
+    const mode = opts.mode ?? "create";
+    const dryRun = opts.dryRun ?? false;
+    if (bundle.bundleVersion !== TEMPLATE_BUNDLE_VERSION) {
+      throw new ApprovalValidationError(
+        `Unsupported template bundle version ${bundle.bundleVersion}; this engine reads version ${TEMPLATE_BUNDLE_VERSION}.`
+      );
+    }
+    if (!Array.isArray(bundle.templates) || bundle.templates.length === 0) {
+      throw new ApprovalValidationError("Template bundle contains no templates.");
+    }
+    const duplicates = bundle.templates.map((t) => t.name).filter((name, i, all) => all.indexOf(name) !== i);
+    if (duplicates.length > 0) {
+      throw new ApprovalValidationError(
+        `Template bundle contains duplicate names: ${[...new Set(duplicates)].join(", ")}.`
+      );
+    }
+    const invalid = [];
+    for (const config of bundle.templates) {
+      const result2 = this.validateTemplate(config);
+      if (!result2.valid) {
+        invalid.push({
+          name: config.name,
+          message: result2.errors[0]?.message ?? "unknown validation error"
+        });
+      }
+    }
+    if (invalid.length > 0) {
+      throw new ApprovalValidationError(
+        `Template bundle failed validation and was not applied: ${invalid.map((e) => `${e.name}: ${e.message}`).join("; ")}`
+      );
+    }
+    const result = { created: [], updated: [], skipped: [], errors: [], dryRun };
+    for (const config of bundle.templates) {
+      const existing = await this.opts.adapter.getTemplate(this.tenantId, config.name);
+      try {
+        if (existing && mode === "create") {
+          result.skipped.push(config.name);
+          continue;
+        }
+        if (existing) {
+          if (!dryRun) await this.registry.update(config);
+          result.updated.push(config.name);
+        } else {
+          if (!dryRun) await this.registry.define(config);
+          result.created.push(config.name);
+        }
+      } catch (err) {
+        result.errors.push({ name: config.name, message: err.message });
+      }
+    }
+    this.logger.info("importTemplates: bundle applied", {
+      tenantId: this.tenantId,
+      mode,
+      dryRun,
+      created: result.created.length,
+      updated: result.updated.length,
+      skipped: result.skipped.length,
+      errors: result.errors.length
+    });
+    return result;
+  }
   async getStatistics(filter = {}) {
     const statuses = [
       "pending",
@@ -3408,14 +3559,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);
       }
@@ -3502,6 +3657,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;
   }