hierarchical-approval 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -7,6 +7,84 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [2.2.0] - 2026-09-04
+
+### Added — template export / import
+
+- **`exportTemplates()` and `importTemplates()` move approval configuration
+  between environments.** Templates are authored in a sandbox, reviewed, then
+  promoted — but the only way to carry them across was to read `listTemplates()`
+  and re-post the rows, which dragged each environment's own `id`, `tenantId`
+  and version lineage along. Those either collided on arrival or silently
+  claimed a history the target never had.
+
+  ```ts
+  const bundle = await sandbox.exportTemplates(['PO', 'INV']);
+  await production.importTemplates(bundle, { mode: 'upsert', dryRun: true });
+  ```
+
+  A bundle is plain JSON, version-stamped, and carries no environment-specific
+  fields — they are stripped, not blanked, so a round trip cannot reintroduce a
+  stale id. The target assigns its own identity.
+
+- **`mode: 'create'`** (default) skips templates that already exist;
+  **`'upsert'`** updates them, bumping the version and recording
+  `previousVersionId` exactly as `updateTemplate()` does. `dryRun` reports
+  without writing.
+
+- **Every template is validated before any is written.** A half-applied bundle
+  is worse than one rejected outright: the tenant ends up matching neither
+  environment and the operator cannot tell which half landed. Validation
+  failures reject the whole bundle and name the offending template; storage
+  errors during the write phase are still reported per template, since those can
+  occur after validation passes.
+
+  Import also rejects an unsupported `bundleVersion`, an empty bundle, and
+  duplicate names within one bundle.
+
+  New exports: `TemplateBundle`, `ImportResult`, `TEMPLATE_BUNDLE_VERSION`.
+
+## [2.1.0] - 2026-09-04
+
+### Added — sub-workflows
+
+- **A level can delegate to a whole separate approval.** "A capital request over
+  1M needs its own board approval before this purchase order can proceed" could
+  only be modelled by flattening the board's chain into the purchase order's —
+  duplicating it in every template that needed it, and losing the board approval
+  as a thing with its own identity, audit trail and lifecycle.
+
+  ```ts
+  { level: 2, name: 'Board approval', mode: 'any', approvers: [],
+    subWorkflow: { templateName: 'BOARD' } }
+  ```
+
+  When the level opens, a child instance is submitted against the named
+  template, carrying the parent's document data so the child's own conditions
+  see the same document. The parent level stays open, with no approvers of its
+  own, until the child finishes.
+
+- **An approved child advances the parent; any other terminal outcome rejects
+  it.** Rejected, cancelled and expired all collapse into one rejection
+  deliberately: a parent that treated a cancelled child as "carry on" would
+  advance past a gate nobody cleared.
+
+- **Children are spawned outside the parent's optimistic write.** The child's own
+  `submit()` reads and writes; nesting that inside the parent's compare-and-set
+  would turn a slow child template into spurious version conflicts on the
+  decision the user just made. The same applies in reverse when a child returns
+  its outcome.
+
+- **Nesting is capped at five levels**, and `validateTemplate()` rejects a
+  template that would spawn itself, sets both `approvers` and `subWorkflow`
+  (whose approvers would never be asked), or names no child template. A
+  sub-workflow level is exempt from the "must have at least one approver" rule,
+  since its child decides it.
+
+  New exports: `SubWorkflowConfig`, `SubWorkflowEvent`. `ApprovalInstance` gains
+  `parentLevel` and `subWorkflowDepth`; levels gain `childInstanceId` and
+  `subWorkflowTemplate`.
+
 ## [2.0.0] - 2026-09-04
 
 ### BREAKING — `IStorageAdapter` requires `countInstances`

package/README.md

@@ -468,6 +468,66 @@ The sweep is **not atomic**: it reports per-instance failures rather than rollin
 back. A partial transfer is the useful outcome — the approvals that can move
 should move, and the ones that cannot are named so a human can look at them.
 
+### Promoting templates between environments
+
+Approval configuration is authored somewhere safe, reviewed, then promoted.
+`exportTemplates()` produces a portable bundle and `importTemplates()` applies
+it:
+
+```ts
+const bundle = await sandbox.exportTemplates(['PO', 'INV']);   // omit names for all
+const result = await production.importTemplates(bundle, { mode: 'upsert', dryRun: true });
+// { created: [], updated: ['PO', 'INV'], skipped: [], errors: [], dryRun: true }
+```
+
+A bundle is plain JSON and carries **no** `id`, `tenantId`, `createdAt`,
+`version` or `previousVersionId` — those describe one row in one database, and
+importing them would either collide with the target's ids or claim a lineage the
+target never had. The target assigns its own.
+
+`mode: 'create'` (the default) skips templates that already exist; `'upsert'`
+updates them, bumping the version and recording `previousVersionId` as a normal
+`updateTemplate()` would.
+
+**Every template is validated before any is written.** A half-applied bundle
+leaves the tenant matching neither environment with no way to tell which half
+landed, so a bundle that fails validation is rejected whole, naming the
+offending template.
+
+### Sub-workflows
+
+A level can delegate to a whole separate approval instead of to a list of
+approvers — "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:
+
+```ts
+levels: [
+  { level: 1, name: 'Manager', approvers: [{ type: 'user', userId: 'mgr' }], mode: 'any' },
+  { level: 2, name: 'Board approval', mode: 'any', approvers: [],
+    subWorkflow: { templateName: 'BOARD' } },
+  { level: 3, name: 'CEO', approvers: [{ type: 'user', userId: 'ceo' }], mode: 'any' },
+]
+```
+
+When level 2 opens, a child instance is submitted against `BOARD`, carrying the
+parent's document data so the child's own conditions see the same document. The
+parent level stays open, with no approvers of its own, until the child finishes.
+
+| Child outcome | Parent |
+|---|---|
+| `approved` | Level approved; the chain advances |
+| `rejected`, `cancelled`, `expired` | Parent rejected |
+
+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.
+
+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
+`approval:subworkflow_started` / `approval:subworkflow_completed`.
+
 ### Attachments
 
 Attach supporting evidence — a quote PDF, a signed contract, a screenshot of a

package/dist/{ApprovalEngine-B8bPZq01.d.ts → ApprovalEngine-B3ChZxS7.d.ts}

@@ -1,14 +1,14 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-B8aRYeGI.js';
-import { l as ConditionExpression, p as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-BE0uJmg3.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Dv_MuYwS.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-DjRvHUF0.js';
+import { l as ConditionExpression, p as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-DUJY_Axf.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BdgfUrIn.js';
 import { z } from 'zod';
 import { L as Logger } from './Logger-BplhlU7l.js';
 import { C as Clock } from './Clock-3FnOczFJ.js';
-import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-DWYXVuJD.js';
-import { I as IAuditAdapter } from './IAuditAdapter-DDV4Rf9F.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-BGYrAqep.js';
+import { I as IAuditAdapter } from './IAuditAdapter-C4OASS6u.js';
 import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-CFJ-gXKl.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BA_m2Dg9.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -305,6 +305,32 @@ interface ApproverWorkload {
     /** Age of that oldest item. `0` when they hold nothing. */
     oldestAgeMs: number;
 }
+/** Version stamp on an exported bundle, so an importer can reject a shape it does not understand. */
+declare const TEMPLATE_BUNDLE_VERSION = 1;
+/**
+ * A portable set of templates, safe to move between environments.
+ *
+ * Deliberately carries no `id`, `tenantId`, `createdAt`, `version` or
+ * `previousVersionId`: those describe one row in one database, and importing
+ * them would either collide with the target's own ids or silently claim a
+ * lineage the target never had.
+ */
+interface TemplateBundle {
+    bundleVersion: number;
+    exportedAt: Date;
+    templates: ApprovalTemplateConfig[];
+}
+/** Outcome of {@link ApprovalEngine.importTemplates}. */
+interface ImportResult {
+    created: string[];
+    updated: string[];
+    skipped: string[];
+    errors: Array<{
+        name: string;
+        message: string;
+    }>;
+    dryRun: boolean;
+}
 interface ApprovalStatistics {
     /** Total instances matching the filter (across all statuses). */
     total: number;
@@ -470,7 +496,18 @@ declare class ApprovalEngine {
     updateTemplate(config: ApprovalTemplateConfig): Promise<string>;
     getTemplate(name: string): Promise<ApprovalTemplate>;
     listTemplates(): Promise<ApprovalTemplate[]>;
-    submit(raw: SubmitOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    submit(raw: SubmitOptions, auditCtx?: AuditContext, 
+    /**
+     * @internal Set only when the engine spawns a sub-workflow child. Passed at
+     * creation rather than stamped afterwards, because the child spawns its own
+     * children before any post-submit update could reach it — which is how a
+     * grandchild ended up recorded at depth 1.
+     */
+    link?: {
+        parentInstanceId: string;
+        parentLevel: number;
+        depth: number;
+    }): Promise<ApprovalInstance>;
     approve(instanceId: string, raw: ApproveOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     reject(instanceId: string, raw: RejectOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     delegate(instanceId: string, raw: DelegateOptions, auditCtx?: AuditContext): Promise<void>;
@@ -649,6 +686,36 @@ declare class ApprovalEngine {
      * @returns One row per approver holding at least one open level.
      */
     getWorkload(filter?: Omit<InstanceFilter, 'status'>): Promise<ApproverWorkload[]>;
+    /**
+     * 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.
+     */
+    exportTemplates(names?: string[]): Promise<TemplateBundle>;
+    /**
+     * 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.
+     */
+    importTemplates(bundle: TemplateBundle, opts?: {
+        mode?: 'create' | 'upsert';
+        dryRun?: boolean;
+    }): Promise<ImportResult>;
     getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
     shutdown(): Promise<void>;
     /**
@@ -736,6 +803,40 @@ declare class ApprovalEngine {
      * half-decided quorum level stops pestering the approvers who did their part.
      */
     private sendReminder;
+    /**
+     * 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.
+     */
+    private startSubWorkflows;
+    /**
+     * 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.
+     */
+    private propagateToParent;
+    /** Mark a sub-workflow level approved and advance the parent chain. */
+    private completeSubWorkflowLevel;
+    /** Reject a parent because the child approval it was waiting on did not succeed. */
+    private rejectFromSubWorkflow;
+    /**
+     * 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.
+     */
+    private afterDecision;
     private findNextLevel;
     private findPreviousLevel;
     private guardBulkSize;
@@ -746,4 +847,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type TransferResult as T, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type ApproverWorkload as f, type BusinessCalendar as g, type CancelOptions as h, type ConditionOperatorFn as i, type CycleTimeStats as j, type IdempotencyKeyFn as k, type OutOfOfficeProvider as l, type OverrideOptions as m, type PreviewResult as n, type ProvideInfoOptions as o, type RejectOptions as p, type RequestInfoOptions as q, type ResubmitOptions as r, type RetryPolicy as s, defaultIdGenerator as t, toComparableNumber as u, validateConditionExpression as v, weekendCalendar as w };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, TEMPLATE_BUNDLE_VERSION as T, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type ApproverWorkload as f, type BusinessCalendar as g, type CancelOptions as h, type ConditionOperatorFn as i, type CycleTimeStats as j, type IdempotencyKeyFn as k, type ImportResult as l, type OutOfOfficeProvider as m, type OverrideOptions as n, type PreviewResult as o, type ProvideInfoOptions as p, type RejectOptions as q, type RequestInfoOptions as r, type ResubmitOptions as s, type RetryPolicy as t, type TemplateBundle as u, type TransferResult as v, defaultIdGenerator as w, toComparableNumber as x, validateConditionExpression as y, weekendCalendar as z };

package/dist/{ApprovalEngine-C7p9cOA3.d.cts → ApprovalEngine-CbFBAMlO.d.cts}

@@ -1,14 +1,14 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-Bgd6p8XL.cjs';
-import { l as ConditionExpression, p as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-BE0uJmg3.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Dy2d0JKy.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-Bk7ybd3z.cjs';
+import { l as ConditionExpression, p as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-DUJY_Axf.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-JJAiMyMd.cjs';
 import { z } from 'zod';
 import { L as Logger } from './Logger-BplhlU7l.cjs';
 import { C as Clock } from './Clock-3FnOczFJ.cjs';
-import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-DGG-guxK.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-UJNdJanq.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-D0ksiFM3.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-BHVKMMv6.cjs';
 import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-CN6LAaKg.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-CtLkwQ8I.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -305,6 +305,32 @@ interface ApproverWorkload {
     /** Age of that oldest item. `0` when they hold nothing. */
     oldestAgeMs: number;
 }
+/** Version stamp on an exported bundle, so an importer can reject a shape it does not understand. */
+declare const TEMPLATE_BUNDLE_VERSION = 1;
+/**
+ * A portable set of templates, safe to move between environments.
+ *
+ * Deliberately carries no `id`, `tenantId`, `createdAt`, `version` or
+ * `previousVersionId`: those describe one row in one database, and importing
+ * them would either collide with the target's own ids or silently claim a
+ * lineage the target never had.
+ */
+interface TemplateBundle {
+    bundleVersion: number;
+    exportedAt: Date;
+    templates: ApprovalTemplateConfig[];
+}
+/** Outcome of {@link ApprovalEngine.importTemplates}. */
+interface ImportResult {
+    created: string[];
+    updated: string[];
+    skipped: string[];
+    errors: Array<{
+        name: string;
+        message: string;
+    }>;
+    dryRun: boolean;
+}
 interface ApprovalStatistics {
     /** Total instances matching the filter (across all statuses). */
     total: number;
@@ -470,7 +496,18 @@ declare class ApprovalEngine {
     updateTemplate(config: ApprovalTemplateConfig): Promise<string>;
     getTemplate(name: string): Promise<ApprovalTemplate>;
     listTemplates(): Promise<ApprovalTemplate[]>;
-    submit(raw: SubmitOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    submit(raw: SubmitOptions, auditCtx?: AuditContext, 
+    /**
+     * @internal Set only when the engine spawns a sub-workflow child. Passed at
+     * creation rather than stamped afterwards, because the child spawns its own
+     * children before any post-submit update could reach it — which is how a
+     * grandchild ended up recorded at depth 1.
+     */
+    link?: {
+        parentInstanceId: string;
+        parentLevel: number;
+        depth: number;
+    }): Promise<ApprovalInstance>;
     approve(instanceId: string, raw: ApproveOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     reject(instanceId: string, raw: RejectOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     delegate(instanceId: string, raw: DelegateOptions, auditCtx?: AuditContext): Promise<void>;
@@ -649,6 +686,36 @@ declare class ApprovalEngine {
      * @returns One row per approver holding at least one open level.
      */
     getWorkload(filter?: Omit<InstanceFilter, 'status'>): Promise<ApproverWorkload[]>;
+    /**
+     * 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.
+     */
+    exportTemplates(names?: string[]): Promise<TemplateBundle>;
+    /**
+     * 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.
+     */
+    importTemplates(bundle: TemplateBundle, opts?: {
+        mode?: 'create' | 'upsert';
+        dryRun?: boolean;
+    }): Promise<ImportResult>;
     getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
     shutdown(): Promise<void>;
     /**
@@ -736,6 +803,40 @@ declare class ApprovalEngine {
      * half-decided quorum level stops pestering the approvers who did their part.
      */
     private sendReminder;
+    /**
+     * 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.
+     */
+    private startSubWorkflows;
+    /**
+     * 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.
+     */
+    private propagateToParent;
+    /** Mark a sub-workflow level approved and advance the parent chain. */
+    private completeSubWorkflowLevel;
+    /** Reject a parent because the child approval it was waiting on did not succeed. */
+    private rejectFromSubWorkflow;
+    /**
+     * 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.
+     */
+    private afterDecision;
     private findNextLevel;
     private findPreviousLevel;
     private guardBulkSize;
@@ -746,4 +847,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type TransferResult as T, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type ApproverWorkload as f, type BusinessCalendar as g, type CancelOptions as h, type ConditionOperatorFn as i, type CycleTimeStats as j, type IdempotencyKeyFn as k, type OutOfOfficeProvider as l, type OverrideOptions as m, type PreviewResult as n, type ProvideInfoOptions as o, type RejectOptions as p, type RequestInfoOptions as q, type ResubmitOptions as r, type RetryPolicy as s, defaultIdGenerator as t, toComparableNumber as u, validateConditionExpression as v, weekendCalendar as w };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, TEMPLATE_BUNDLE_VERSION as T, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type ApproverWorkload as f, type BusinessCalendar as g, type CancelOptions as h, type ConditionOperatorFn as i, type CycleTimeStats as j, type IdempotencyKeyFn as k, type ImportResult as l, type OutOfOfficeProvider as m, type OverrideOptions as n, type PreviewResult as o, type ProvideInfoOptions as p, type RejectOptions as q, type RequestInfoOptions as r, type ResubmitOptions as s, type RetryPolicy as t, type TemplateBundle as u, type TransferResult as v, defaultIdGenerator as w, toComparableNumber as x, validateConditionExpression as y, weekendCalendar as z };

package/dist/{IAuditAdapter-UJNdJanq.d.cts → IAuditAdapter-BHVKMMv6.d.cts}

@@ -1,4 +1,4 @@
-import { b as AuditEntry, a as ApprovalInstance } from './instance-BE0uJmg3.cjs';
+import { b as AuditEntry, a as ApprovalInstance } from './instance-DUJY_Axf.cjs';
 
 interface IAuditAdapter {
     /**

package/dist/{IAuditAdapter-DDV4Rf9F.d.ts → IAuditAdapter-C4OASS6u.d.ts}

@@ -1,4 +1,4 @@
-import { b as AuditEntry, a as ApprovalInstance } from './instance-BE0uJmg3.js';
+import { b as AuditEntry, a as ApprovalInstance } from './instance-DUJY_Axf.js';
 
 interface IAuditAdapter {
     /**

package/dist/{IAuthorizationPolicy-CFJ-gXKl.d.ts → IAuthorizationPolicy-BA_m2Dg9.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-BE0uJmg3.js';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-DUJY_Axf.js';
 
 interface AuthorizationContext {
     operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment';

package/dist/{IAuthorizationPolicy-CN6LAaKg.d.cts → IAuthorizationPolicy-CtLkwQ8I.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-BE0uJmg3.cjs';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-DUJY_Axf.cjs';
 
 interface AuthorizationContext {
     operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment';

package/dist/{INotificationAdapter-Dv_MuYwS.d.ts → INotificationAdapter-BdgfUrIn.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-BE0uJmg3.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-DUJY_Axf.js';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -112,6 +112,14 @@ interface AttachmentEvent extends ApprovalEvent {
     uri: string;
     level?: number;
 }
+/** Emitted when a level hands off to a child approval, and when that child returns. */
+interface SubWorkflowEvent extends ApprovalEvent {
+    level: number;
+    childInstanceId: string;
+    childTemplateName: string;
+    /** Set on completion: the outcome the child returned. */
+    outcome?: 'approved' | 'rejected' | 'cancelled' | 'expired';
+}
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -132,6 +140,8 @@ interface ApprovalEventMap {
     'approval:info_provided': InfoProvidedEvent;
     'approval:attachment_added': AttachmentEvent;
     'approval:attachment_removed': AttachmentEvent;
+    'approval:subworkflow_started': SubWorkflowEvent;
+    'approval:subworkflow_completed': SubWorkflowEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
 interface HistoryEntry extends AuditEntry {
@@ -155,4 +165,4 @@ interface INotificationAdapter {
     notify(event: NotificationEvent): Promise<void>;
 }
 
-export type { ApprovalEvent as A, CancelledEvent as C, DataUpdatedEvent as D, EscalatedEvent as E, HistoryEntry as H, INotificationAdapter as I, LevelAdvancedEvent as L, NotificationEvent as N, OverriddenEvent as O, ReassignedEvent as R, SlaBreachedEvent as S, ApprovalEventMap as a, ApprovalEventName as b, ApprovedEvent as c, AttachmentEvent as d, DelegatedEvent as e, ExpiredEvent as f, InfoProvidedEvent as g, InfoRequestedEvent as h, RejectedEvent as i, ReminderEvent as j, ResubmittedEvent as k, SubmittedEvent as l };
+export type { ApprovalEvent as A, CancelledEvent as C, DataUpdatedEvent as D, EscalatedEvent as E, HistoryEntry as H, INotificationAdapter as I, LevelAdvancedEvent as L, NotificationEvent as N, OverriddenEvent as O, ReassignedEvent as R, SlaBreachedEvent as S, ApprovalEventMap as a, ApprovalEventName as b, ApprovedEvent as c, AttachmentEvent as d, DelegatedEvent as e, ExpiredEvent as f, InfoProvidedEvent as g, InfoRequestedEvent as h, RejectedEvent as i, ReminderEvent as j, ResubmittedEvent as k, SubWorkflowEvent as l, SubmittedEvent as m };

package/dist/{INotificationAdapter-Dy2d0JKy.d.cts → INotificationAdapter-JJAiMyMd.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-BE0uJmg3.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-DUJY_Axf.cjs';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -112,6 +112,14 @@ interface AttachmentEvent extends ApprovalEvent {
     uri: string;
     level?: number;
 }
+/** Emitted when a level hands off to a child approval, and when that child returns. */
+interface SubWorkflowEvent extends ApprovalEvent {
+    level: number;
+    childInstanceId: string;
+    childTemplateName: string;
+    /** Set on completion: the outcome the child returned. */
+    outcome?: 'approved' | 'rejected' | 'cancelled' | 'expired';
+}
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -132,6 +140,8 @@ interface ApprovalEventMap {
     'approval:info_provided': InfoProvidedEvent;
     'approval:attachment_added': AttachmentEvent;
     'approval:attachment_removed': AttachmentEvent;
+    'approval:subworkflow_started': SubWorkflowEvent;
+    'approval:subworkflow_completed': SubWorkflowEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
 interface HistoryEntry extends AuditEntry {
@@ -155,4 +165,4 @@ interface INotificationAdapter {
     notify(event: NotificationEvent): Promise<void>;
 }
 
-export type { ApprovalEvent as A, CancelledEvent as C, DataUpdatedEvent as D, EscalatedEvent as E, HistoryEntry as H, INotificationAdapter as I, LevelAdvancedEvent as L, NotificationEvent as N, OverriddenEvent as O, ReassignedEvent as R, SlaBreachedEvent as S, ApprovalEventMap as a, ApprovalEventName as b, ApprovedEvent as c, AttachmentEvent as d, DelegatedEvent as e, ExpiredEvent as f, InfoProvidedEvent as g, InfoRequestedEvent as h, RejectedEvent as i, ReminderEvent as j, ResubmittedEvent as k, SubmittedEvent as l };
+export type { ApprovalEvent as A, CancelledEvent as C, DataUpdatedEvent as D, EscalatedEvent as E, HistoryEntry as H, INotificationAdapter as I, LevelAdvancedEvent as L, NotificationEvent as N, OverriddenEvent as O, ReassignedEvent as R, SlaBreachedEvent as S, ApprovalEventMap as a, ApprovalEventName as b, ApprovedEvent as c, AttachmentEvent as d, DelegatedEvent as e, ExpiredEvent as f, InfoProvidedEvent as g, InfoRequestedEvent as h, RejectedEvent as i, ReminderEvent as j, ResubmittedEvent as k, SubWorkflowEvent as l, SubmittedEvent as m };

package/dist/{IOperationMiddleware-DWYXVuJD.d.ts → IOperationMiddleware-BGYrAqep.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance } from './instance-BE0uJmg3.js';
+import { a as ApprovalInstance } from './instance-DUJY_Axf.js';
 
 declare class ApprovalError extends Error {
     readonly code: string;

package/dist/{IOperationMiddleware-DGG-guxK.d.cts → IOperationMiddleware-D0ksiFM3.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance } from './instance-BE0uJmg3.cjs';
+import { a as ApprovalInstance } from './instance-DUJY_Axf.cjs';
 
 declare class ApprovalError extends Error {
     readonly code: string;

package/dist/{IStorageAdapter-Bgd6p8XL.d.cts → IStorageAdapter-Bk7ybd3z.d.cts}

@@ -1,4 +1,4 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-BE0uJmg3.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-DUJY_Axf.cjs';
 
 interface PaginationOpts {
     limit: number;

package/dist/{IStorageAdapter-B8aRYeGI.d.ts → IStorageAdapter-DjRvHUF0.d.ts}

@@ -1,4 +1,4 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-BE0uJmg3.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-DUJY_Axf.js';
 
 interface PaginationOpts {
     limit: number;

package/dist/adapters/MemoryAdapter.d.cts

@@ -1,5 +1,5 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-Bgd6p8XL.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BE0uJmg3.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-Bk7ybd3z.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-DUJY_Axf.cjs';
 
 declare class MemoryAdapter implements IStorageAdapter {
     private templates;

package/dist/adapters/MemoryAdapter.d.ts

@@ -1,5 +1,5 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-B8aRYeGI.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BE0uJmg3.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-DjRvHUF0.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-DUJY_Axf.js';
 
 declare class MemoryAdapter implements IStorageAdapter {
     private templates;

package/dist/adapters/PostgresAdapter.d.cts

@@ -1,7 +1,7 @@
 import * as tls from 'tls';
 import * as pg from 'pg';
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-Bgd6p8XL.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BE0uJmg3.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-Bk7ybd3z.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-DUJY_Axf.cjs';
 
 interface PostgresAdapterOptions {
     connectionString?: string;

package/dist/adapters/PostgresAdapter.d.ts

@@ -1,7 +1,7 @@
 import * as tls from 'tls';
 import * as pg from 'pg';
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-B8aRYeGI.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BE0uJmg3.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-DjRvHUF0.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-DUJY_Axf.js';
 
 interface PostgresAdapterOptions {
     connectionString?: string;