hierarchical-approval 0.9.0 → 1.0.0

package/CHANGELOG.md

@@ -7,6 +7,48 @@ 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

package/README.md

@@ -399,6 +399,40 @@ 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

package/dist/{ApprovalEngine-mD-qyxcZ.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-ecVYcA0z.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-BxUwmrEi.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-COeQ5kEv.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-Bx4_U0ca.js';
-import { I as IAuditAdapter } from './IAuditAdapter-nlIK1em0.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-DG8vmD5j.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;
@@ -489,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;

package/dist/{ApprovalEngine-pfQ2v-J9.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-qKgtuTY1.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-BxUwmrEi.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-CFedkDQe.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-CYXTV_TI.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-0frLfzRq.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-DXEMaoxF.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;
@@ -489,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;

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

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

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

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

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-BxUwmrEi.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' | 'updateData';

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-BxUwmrEi.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' | 'updateData';

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-BxUwmrEi.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-iaAIdMbs.cjs';
 
 interface ApprovalEvent {
     instanceId: string;

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-BxUwmrEi.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-iaAIdMbs.js';
 
 interface ApprovalEvent {
     instanceId: string;

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

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

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

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

package/dist/{IStorageAdapter-ecVYcA0z.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-BxUwmrEi.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-qKgtuTY1.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-BxUwmrEi.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-qKgtuTY1.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BxUwmrEi.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;

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-ecVYcA0z.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BxUwmrEi.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 { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-iaAIdMbs.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-qKgtuTY1.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BxUwmrEi.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';
 
 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-ecVYcA0z.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BxUwmrEi.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 { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-iaAIdMbs.js';
 
 interface PostgresAdapterOptions {
     connectionString?: string;