hierarchical-approval 0.8.0 → 1.0.0

package/CHANGELOG.md

@@ -7,6 +7,89 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [1.0.0] - 2026-09-04
+
+First stable release. The public API is now considered settled: breaking changes
+from here get a major version.
+
+### Added — parallel branch groups
+
+- **Levels sharing a `group` name activate together and join before the chain
+  advances.** Approvals were strictly sequential, so "Finance and Legal review
+  concurrently, then it goes to the CEO" could only be modelled by picking an
+  arbitrary order and making one wait on the other — inflating cycle time for no
+  business reason. This was the last item on the roadmap in `IMPROVEMENTS.md`.
+
+  ```ts
+  levels: [
+    { level: 1, name: 'Manager', ... },
+    { level: 2, name: 'Finance', group: 'review', ... },
+    { level: 3, name: 'Legal',   group: 'review', ... },
+    { level: 4, name: 'CEO', ... },
+  ]
+  ```
+
+  Both branches open at once, decisions arrive in any order, and level 4 stays
+  `waiting` until every branch is approved. Rejecting any branch rejects the
+  instance, as a rejection always has. A group may also lead the chain, in which
+  case it opens at submit.
+
+- **`approve()` and `reject()` take an optional `level`.** Inside a parallel
+  group one person can sit on several open branches; recording their decision
+  against a guessed branch would be silently wrong, so the engine throws and
+  asks which branch is meant. Sequential templates never see this.
+
+- **`getCurrentApprovers()` returns the union across every open branch.**
+  `canApprove()` likewise considers any open branch the user is assigned to.
+
+- **`validateTemplate()` rejects a non-contiguous group** — a group's levels must
+  occupy consecutive level numbers, so that "advance past the group" and
+  "advance past a level" cannot disagree about what comes next.
+
+**Backward compatible.** A level without a `group` is its own group of one, and
+all 673 pre-existing tests pass unchanged against the new engine.
+
+## [0.9.0] - 2026-09-04
+
+### Added — `updateData()`: edit a pending document and recompute its chain
+
+- **`engine.updateData(instanceId, opts)` changes an in-flight instance's
+  document data and re-evaluates the template's conditions against it.**
+  Documents change after submission — a corrected line item, a reclassified
+  vendor, a revised amount — and the chain computed at submit time can be wrong
+  the moment that happens. The only previous remedy was to cancel and resubmit,
+  which discarded every approval already collected along with its audit trail.
+
+  ```ts
+  await engine.updateData(instance.id, {
+    updatedBy: 'buyer-1',
+    data: { amount: 20000 },      // merged by default; mode: 'replace' swaps wholesale
+    reason: 'Corrected line items',
+  });
+  ```
+
+  `recomputeChain: false` applies a data correction without touching the chain.
+
+- **Decided history is frozen.** Only levels after the current one are
+  recomputed. A level that is already approved, or is actively collecting
+  decisions, is never removed: a `skipLevels` condition that would drop it is
+  ignored, because editing data must not retract an approval that was given. A
+  condition that would *insert* a level at or before the current level throws
+  `ApprovalValidationError` rather than silently dropping an approval step the
+  template says is required.
+
+  A future level that survives re-evaluation is preserved object-identical, so a
+  delegation already arranged on it survives an unrelated edit elsewhere in the
+  document.
+
+- **Wiring:** emits `approval:data_updated` (`changedFields`, `addedLevels`,
+  `removedLevels`), records a `data_updated` audit entry carrying the before and
+  after data, increments `approval.data_updated`, and adds `updateData` to the
+  authorization-policy operation set — so it runs through the same
+  authz/middleware/audit/notification pipeline as every other operation.
+
+  New exports: `UpdateDataOptions`, `DataUpdatedEvent`.
+
 ## [0.8.0] - 2026-09-04
 
 ### Added — boolean condition expressions

package/README.md

@@ -399,6 +399,76 @@ engine.registerConditionOperator('between', (actual, expected) => {
 });
 ```
 
+### Parallel branch groups
+
+Give levels the same `group` name and they activate together, joining before
+the chain moves on — "Finance and Legal review concurrently, then it goes to the
+CEO":
+
+```ts
+levels: [
+  { level: 1, name: 'Manager', approvers: [{ type: 'user', userId: 'mgr' }], mode: 'any' },
+  { level: 2, name: 'Finance', group: 'review', approvers: [{ type: 'role', role: 'finance' }], mode: 'any' },
+  { level: 3, name: 'Legal',   group: 'review', approvers: [{ type: 'role', role: 'legal' }],   mode: 'any' },
+  { level: 4, name: 'CEO',     approvers: [{ type: 'user', userId: 'ceo' }], mode: 'any' },
+]
+```
+
+Both branches open at once when the group is reached, decisions can arrive in
+either order, and level 4 stays `waiting` until every branch is approved.
+Rejecting any branch rejects the instance. A group may also lead the chain, in
+which case it opens at submit.
+
+`getCurrentApprovers()` returns the union across every open branch. A level
+without a `group` is its own group of one, so existing sequential templates
+behave exactly as before.
+
+**When one person sits on two open branches**, `approve()` refuses to guess and
+throws — pass `level` to say which branch the decision is for:
+
+```ts
+await engine.approve(id, { approverId: 'cfo', level: 2 });
+```
+
+A group's levels must occupy a contiguous run of level numbers;
+`validateTemplate()` rejects an interleaved group.
+
+### Editing a document mid-flight
+
+Documents change after submission — a line item is corrected, a vendor
+reclassified, an amount revised. `updateData()` applies the change and
+re-evaluates the template's conditions, so the chain reflects the corrected
+document without cancelling and resubmitting (which would throw away the
+approvals already collected):
+
+```ts
+const updated = await engine.updateData(instance.id, {
+  updatedBy: 'buyer-1',
+  data: { amount: 20000 },   // merged into existing data
+  reason: 'Corrected line items',
+});
+// amount crossed the 10k threshold -> the CFO level is now in the chain
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `data` | required | Fields to apply |
+| `mode` | `'merge'` | `'merge'` keeps untouched keys; `'replace'` swaps the whole object |
+| `reason` | — | Recorded on the audit entry |
+| `recomputeChain` | `true` | Set `false` to correct data without touching the chain |
+
+**Decided history is frozen.** Only levels *after* the current one are
+recomputed. A level that is already approved, or is actively collecting
+decisions, is never removed — a `skipLevels` condition that would drop it is
+ignored, because an approval that has been given cannot be retracted by editing
+data. A condition that would *insert* a level at or before the current one
+throws rather than silently dropping a required approval step; cancel and
+resubmit if the chain genuinely must change retroactively.
+
+Emits `approval:data_updated` with `changedFields`, `addedLevels` and
+`removedLevels`, and records a `data_updated` audit entry holding the before and
+after data. Only pending instances can be edited.
+
 ---
 
 ## Installation and setup

package/dist/{ApprovalEngine-DFY53zRK.d.ts → ApprovalEngine-DB62pkEk.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-D7jsZT6O.js';
-import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-CtkmEkYa.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Hn70VShV.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-BYlHnm7_.js';
+import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-iaAIdMbs.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-u5ZE7wS6.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-BCcAqSzT.js';
-import { I as IAuditAdapter } from './IAuditAdapter-CaM3A2Kt.js';
-import { I as IMetricsAdapter } from './IMetricsAdapter-D9PUz4tM.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-DndObWfg.js';
+import { I as IAuditAdapter } from './IAuditAdapter-RKagmrfi.js';
+import { I as IMetricsAdapter } from './IMetricsAdapter-t7QpfA1I.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-DFD0ELtO.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-DEDQnNzq.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -26,6 +26,7 @@ declare const SubmitOptionsSchema: z.ZodObject<{
 declare const ApproveOptionsSchema: z.ZodObject<{
     approverId: z.ZodString;
     comment: z.ZodOptional<z.ZodString>;
+    level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const RejectOptionsSchema: z.ZodObject<{
     approverId: z.ZodString;
@@ -34,6 +35,7 @@ declare const RejectOptionsSchema: z.ZodObject<{
         originator: "originator";
         previous: "previous";
     }>>;
+    level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const DelegateOptionsSchema: z.ZodObject<{
     fromApprover: z.ZodString;
@@ -67,6 +69,16 @@ declare const OverrideOptionsSchema: z.ZodObject<{
     overriddenBy: z.ZodString;
     justification: z.ZodString;
 }, z.core.$strip>;
+declare const UpdateDataOptionsSchema: z.ZodObject<{
+    updatedBy: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        merge: "merge";
+        replace: "replace";
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
+    recomputeChain: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
 type SubmitOptions = z.infer<typeof SubmitOptionsSchema>;
 type ApproveOptions = z.infer<typeof ApproveOptionsSchema>;
 type RejectOptions = z.infer<typeof RejectOptionsSchema>;
@@ -77,6 +89,7 @@ type EscalateOptions = z.infer<typeof EscalateOptionsSchema>;
 type ResubmitOptions = z.infer<typeof ResubmitOptionsSchema>;
 type AddCommentOptions = z.infer<typeof AddCommentOptionsSchema>;
 type OverrideOptions = z.infer<typeof OverrideOptionsSchema>;
+type UpdateDataOptions = z.infer<typeof UpdateDataOptionsSchema>;
 
 /**
  * Computes deadline dates from a number of days. The default engine behaviour
@@ -373,6 +386,42 @@ declare class ApprovalEngine {
     reassign(instanceId: string, raw: ReassignOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     cancel(instanceId: string, raw: CancelOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     escalate(instanceId: string, raw: EscalateOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Change an instance's document data while it is still pending, and
+     * re-evaluate the template's conditions against the new values.
+     *
+     * Documents change after submission — a line item is corrected, a vendor is
+     * reclassified, an amount is revised — and the approval chain that was
+     * computed at submit time can be wrong the moment that happens. Without this,
+     * the only way to reflect a correction was to cancel and resubmit, losing the
+     * approvals already collected and the audit trail with them.
+     *
+     * **Only the part of the chain that has not been reached is recomputed.**
+     * Levels before {@link ApprovalInstance.currentLevel}, and the current level
+     * itself, are frozen: an approval that has already been given cannot be
+     * retracted by editing data, and a level that is actively collecting
+     * decisions is not pulled out from under its approvers. Conditions that would
+     * skip such a level are therefore ignored — history cannot be rewritten — and
+     * a condition that would *insert* a level at or before the current one throws
+     * rather than silently dropping an approval step that should have run.
+     *
+     * @param instanceId - The pending instance to update.
+     * @param raw - Who is updating, the new data, and how to apply it.
+     * @param auditCtx - Optional compliance context recorded on the audit entry.
+     * @returns The updated instance.
+     * @throws ApprovalError if the instance is not pending.
+     * @throws ApprovalValidationError if re-evaluation would insert a level at or
+     *   before the current level, or would leave the chain with no levels.
+     */
+    updateData(instanceId: string, raw: UpdateDataOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Recompute the not-yet-reached portion of an instance's level chain against
+     * new data, mutating `instance.levels` in place.
+     *
+     * Levels at or before `currentLevel` are treated as immutable history. See
+     * {@link updateData} for why.
+     */
+    private recomputeFutureChain;
     /** Add a comment to an instance without approving or rejecting. */
     addComment(instanceId: string, raw: AddCommentOptions, auditCtx?: AuditContext): Promise<void>;
     /** Resubmit a rejected instance, creating a new linked instance from level 1. */
@@ -442,7 +491,36 @@ declare class ApprovalEngine {
     /** Compute a deadline `days` from `from`, honouring the business calendar if one is configured. */
     private deadlineFrom;
     private requireInstance;
+    /**
+     * Identity of the parallel branch group a level belongs to.
+     *
+     * An ungrouped level is its own group of one, keyed by its level number, so
+     * sequential and parallel levels can be handled by the same code paths. The
+     * `#` prefix keeps a synthetic key from ever colliding with a real group
+     * name a template author chose.
+     */
+    private static groupKeyOf;
+    /** Every level currently collecting decisions — more than one inside a parallel group. */
+    private pendingLevels;
+    /** All levels sharing a group with the given level, including it. */
+    private groupMembers;
+    /**
+     * Pick which pending level an actor is operating on.
+     *
+     * With sequential levels there is only ever one candidate. Inside a parallel
+     * group an approver may sit on several branches at once, and guessing which
+     * one they meant would silently record the decision against the wrong branch —
+     * so that case demands an explicit `level`.
+     */
+    private resolveActorLevel;
     private currentLevelInstance;
+    /**
+     * The next group of levels to activate: every level sharing the group of the
+     * lowest-numbered waiting level.
+     */
+    private findNextGroup;
+    /** Resolve approvers for a group, set its deadlines, and mark it pending. */
+    private activateGroup;
     private findNextLevel;
     private findPreviousLevel;
     private guardBulkSize;
@@ -453,4 +531,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 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 BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, toComparableNumber as t, 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, 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 BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };

package/dist/{ApprovalEngine-DVMMtiSm.d.cts → ApprovalEngine-DzHUWix1.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-egPQD6Ry.cjs';
-import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-CtkmEkYa.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Ci0gf6ac.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-D-yIRiET.cjs';
+import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-iaAIdMbs.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Dld84ihs.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-DOlOraCX.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-BODIlw4h.cjs';
-import { I as IMetricsAdapter } from './IMetricsAdapter-D9PUz4tM.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-BSfjsnTe.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-zVO7XpWm.cjs';
+import { I as IMetricsAdapter } from './IMetricsAdapter-t7QpfA1I.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-cT7LSHtl.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-Dx9NzWx8.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -26,6 +26,7 @@ declare const SubmitOptionsSchema: z.ZodObject<{
 declare const ApproveOptionsSchema: z.ZodObject<{
     approverId: z.ZodString;
     comment: z.ZodOptional<z.ZodString>;
+    level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const RejectOptionsSchema: z.ZodObject<{
     approverId: z.ZodString;
@@ -34,6 +35,7 @@ declare const RejectOptionsSchema: z.ZodObject<{
         originator: "originator";
         previous: "previous";
     }>>;
+    level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const DelegateOptionsSchema: z.ZodObject<{
     fromApprover: z.ZodString;
@@ -67,6 +69,16 @@ declare const OverrideOptionsSchema: z.ZodObject<{
     overriddenBy: z.ZodString;
     justification: z.ZodString;
 }, z.core.$strip>;
+declare const UpdateDataOptionsSchema: z.ZodObject<{
+    updatedBy: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        merge: "merge";
+        replace: "replace";
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
+    recomputeChain: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
 type SubmitOptions = z.infer<typeof SubmitOptionsSchema>;
 type ApproveOptions = z.infer<typeof ApproveOptionsSchema>;
 type RejectOptions = z.infer<typeof RejectOptionsSchema>;
@@ -77,6 +89,7 @@ type EscalateOptions = z.infer<typeof EscalateOptionsSchema>;
 type ResubmitOptions = z.infer<typeof ResubmitOptionsSchema>;
 type AddCommentOptions = z.infer<typeof AddCommentOptionsSchema>;
 type OverrideOptions = z.infer<typeof OverrideOptionsSchema>;
+type UpdateDataOptions = z.infer<typeof UpdateDataOptionsSchema>;
 
 /**
  * Computes deadline dates from a number of days. The default engine behaviour
@@ -373,6 +386,42 @@ declare class ApprovalEngine {
     reassign(instanceId: string, raw: ReassignOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     cancel(instanceId: string, raw: CancelOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     escalate(instanceId: string, raw: EscalateOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Change an instance's document data while it is still pending, and
+     * re-evaluate the template's conditions against the new values.
+     *
+     * Documents change after submission — a line item is corrected, a vendor is
+     * reclassified, an amount is revised — and the approval chain that was
+     * computed at submit time can be wrong the moment that happens. Without this,
+     * the only way to reflect a correction was to cancel and resubmit, losing the
+     * approvals already collected and the audit trail with them.
+     *
+     * **Only the part of the chain that has not been reached is recomputed.**
+     * Levels before {@link ApprovalInstance.currentLevel}, and the current level
+     * itself, are frozen: an approval that has already been given cannot be
+     * retracted by editing data, and a level that is actively collecting
+     * decisions is not pulled out from under its approvers. Conditions that would
+     * skip such a level are therefore ignored — history cannot be rewritten — and
+     * a condition that would *insert* a level at or before the current one throws
+     * rather than silently dropping an approval step that should have run.
+     *
+     * @param instanceId - The pending instance to update.
+     * @param raw - Who is updating, the new data, and how to apply it.
+     * @param auditCtx - Optional compliance context recorded on the audit entry.
+     * @returns The updated instance.
+     * @throws ApprovalError if the instance is not pending.
+     * @throws ApprovalValidationError if re-evaluation would insert a level at or
+     *   before the current level, or would leave the chain with no levels.
+     */
+    updateData(instanceId: string, raw: UpdateDataOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Recompute the not-yet-reached portion of an instance's level chain against
+     * new data, mutating `instance.levels` in place.
+     *
+     * Levels at or before `currentLevel` are treated as immutable history. See
+     * {@link updateData} for why.
+     */
+    private recomputeFutureChain;
     /** Add a comment to an instance without approving or rejecting. */
     addComment(instanceId: string, raw: AddCommentOptions, auditCtx?: AuditContext): Promise<void>;
     /** Resubmit a rejected instance, creating a new linked instance from level 1. */
@@ -442,7 +491,36 @@ declare class ApprovalEngine {
     /** Compute a deadline `days` from `from`, honouring the business calendar if one is configured. */
     private deadlineFrom;
     private requireInstance;
+    /**
+     * Identity of the parallel branch group a level belongs to.
+     *
+     * An ungrouped level is its own group of one, keyed by its level number, so
+     * sequential and parallel levels can be handled by the same code paths. The
+     * `#` prefix keeps a synthetic key from ever colliding with a real group
+     * name a template author chose.
+     */
+    private static groupKeyOf;
+    /** Every level currently collecting decisions — more than one inside a parallel group. */
+    private pendingLevels;
+    /** All levels sharing a group with the given level, including it. */
+    private groupMembers;
+    /**
+     * Pick which pending level an actor is operating on.
+     *
+     * With sequential levels there is only ever one candidate. Inside a parallel
+     * group an approver may sit on several branches at once, and guessing which
+     * one they meant would silently record the decision against the wrong branch —
+     * so that case demands an explicit `level`.
+     */
+    private resolveActorLevel;
     private currentLevelInstance;
+    /**
+     * The next group of levels to activate: every level sharing the group of the
+     * lowest-numbered waiting level.
+     */
+    private findNextGroup;
+    /** Resolve approvers for a group, set its deadlines, and mark it pending. */
+    private activateGroup;
     private findNextLevel;
     private findPreviousLevel;
     private guardBulkSize;
@@ -453,4 +531,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 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 BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, toComparableNumber as t, 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, 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 BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };

package/dist/{IAuditAdapter-CaM3A2Kt.d.ts → IAuditAdapter-RKagmrfi.d.ts}

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

package/dist/{IAuditAdapter-BODIlw4h.d.cts → IAuditAdapter-zVO7XpWm.d.cts}

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

package/dist/{IAuthorizationPolicy-DFD0ELtO.d.ts → IAuthorizationPolicy-DEDQnNzq.d.ts}

@@ -1,7 +1,7 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-CtkmEkYa.js';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-iaAIdMbs.js';
 
 interface AuthorizationContext {
-    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment';
+    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData';
     actorId: string;
     instance: Readonly<ApprovalInstance>;
     level?: Readonly<ApprovalLevelInstance>;

package/dist/{IAuthorizationPolicy-cT7LSHtl.d.cts → IAuthorizationPolicy-Dx9NzWx8.d.cts}

@@ -1,7 +1,7 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-CtkmEkYa.cjs';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-iaAIdMbs.cjs';
 
 interface AuthorizationContext {
-    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment';
+    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData';
     actorId: string;
     instance: Readonly<ApprovalInstance>;
     level?: Readonly<ApprovalLevelInstance>;

package/dist/{IMetricsAdapter-D9PUz4tM.d.cts → IMetricsAdapter-t7QpfA1I.d.cts}

@@ -1,4 +1,4 @@
-type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.reassigned' | 'approval.overridden' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
+type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.reassigned' | 'approval.overridden' | 'approval.data_updated' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */
     increment(metric: MetricName, labels?: Record<string, string>): void;

package/dist/{IMetricsAdapter-D9PUz4tM.d.ts → IMetricsAdapter-t7QpfA1I.d.ts}

@@ -1,4 +1,4 @@
-type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.reassigned' | 'approval.overridden' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
+type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.reassigned' | 'approval.overridden' | 'approval.data_updated' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */
     increment(metric: MetricName, labels?: Record<string, string>): void;

package/dist/{INotificationAdapter-Hn70VShV.d.ts → INotificationAdapter-Dld84ihs.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-CtkmEkYa.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-iaAIdMbs.cjs';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -62,6 +62,22 @@ interface ExpiredEvent extends ApprovalEvent {
 interface SlaBreachedEvent extends ApprovalEvent {
     slaDeadlineAt: Date;
 }
+/**
+ * Emitted when an instance's document data is changed while it is still
+ * pending. {@link addedLevels} and {@link removedLevels} describe how the
+ * remaining approval chain was recomputed — both empty when the data change
+ * did not affect it.
+ */
+interface DataUpdatedEvent extends ApprovalEvent {
+    updatedBy: string;
+    reason?: string;
+    /** Field paths whose values differ after the update. */
+    changedFields: string[];
+    /** Level numbers added to the future chain by re-evaluating conditions. */
+    addedLevels: number[];
+    /** Level numbers removed from the future chain by re-evaluating conditions. */
+    removedLevels: number[];
+}
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -76,6 +92,7 @@ interface ApprovalEventMap {
     'approval:overridden': OverriddenEvent;
     'approval:expired': ExpiredEvent;
     'approval:sla_breached': SlaBreachedEvent;
+    'approval:data_updated': DataUpdatedEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
 interface HistoryEntry extends AuditEntry {
@@ -99,4 +116,4 @@ interface INotificationAdapter {
     notify(event: NotificationEvent): Promise<void>;
 }
 
-export type { ApprovalEvent as A, CancelledEvent as C, DelegatedEvent 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, ExpiredEvent as d, RejectedEvent as e, ResubmittedEvent as f, SubmittedEvent as g };
+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, DelegatedEvent as d, ExpiredEvent as e, RejectedEvent as f, ResubmittedEvent as g, SubmittedEvent as h };

package/dist/{INotificationAdapter-Ci0gf6ac.d.cts → INotificationAdapter-u5ZE7wS6.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-CtkmEkYa.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-iaAIdMbs.js';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -62,6 +62,22 @@ interface ExpiredEvent extends ApprovalEvent {
 interface SlaBreachedEvent extends ApprovalEvent {
     slaDeadlineAt: Date;
 }
+/**
+ * Emitted when an instance's document data is changed while it is still
+ * pending. {@link addedLevels} and {@link removedLevels} describe how the
+ * remaining approval chain was recomputed — both empty when the data change
+ * did not affect it.
+ */
+interface DataUpdatedEvent extends ApprovalEvent {
+    updatedBy: string;
+    reason?: string;
+    /** Field paths whose values differ after the update. */
+    changedFields: string[];
+    /** Level numbers added to the future chain by re-evaluating conditions. */
+    addedLevels: number[];
+    /** Level numbers removed from the future chain by re-evaluating conditions. */
+    removedLevels: number[];
+}
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -76,6 +92,7 @@ interface ApprovalEventMap {
     'approval:overridden': OverriddenEvent;
     'approval:expired': ExpiredEvent;
     'approval:sla_breached': SlaBreachedEvent;
+    'approval:data_updated': DataUpdatedEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
 interface HistoryEntry extends AuditEntry {
@@ -99,4 +116,4 @@ interface INotificationAdapter {
     notify(event: NotificationEvent): Promise<void>;
 }
 
-export type { ApprovalEvent as A, CancelledEvent as C, DelegatedEvent 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, ExpiredEvent as d, RejectedEvent as e, ResubmittedEvent as f, SubmittedEvent as g };
+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, DelegatedEvent as d, ExpiredEvent as e, RejectedEvent as f, ResubmittedEvent as g, SubmittedEvent as h };

package/dist/{IOperationMiddleware-DOlOraCX.d.cts → IOperationMiddleware-BSfjsnTe.d.cts}

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

package/dist/{IOperationMiddleware-BCcAqSzT.d.ts → IOperationMiddleware-DndObWfg.d.ts}

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

package/dist/{IStorageAdapter-D7jsZT6O.d.ts → IStorageAdapter-BYlHnm7_.d.ts}

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

package/dist/{IStorageAdapter-egPQD6Ry.d.cts → IStorageAdapter-D-yIRiET.d.cts}

@@ -1,4 +1,4 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-CtkmEkYa.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-iaAIdMbs.cjs';
 
 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-egPQD6Ry.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-CtkmEkYa.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-D-yIRiET.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-iaAIdMbs.cjs';
 
 declare class MemoryAdapter implements IStorageAdapter {
     private templates;