hierarchical-approval 3.3.0 → 4.0.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 4.0.1 - 2026-09-14
+
+- fix(resilience): include the offending value in RateLimitMiddleware errors
+- fix(scheduler): include the job id in InMemorySchedulerAdapter's post-shutdown error
+- fix(postgres): test the null-rowCount fallback via a dedicated fake pool
+- fix(postgres): let FakePool pass an explicit null rowCount through
+
 # Changelog
 
 All notable changes to `hierarchical-approval` are documented here. This project
@@ -5,7 +12,216 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- `InMemorySchedulerAdapter.scheduleAt()`'s post-shutdown error now names the
+  rejected job id, so a caller can tell which scheduled job was dropped
+  without adding their own logging around every call.
+
+## [4.0.0] - 2026-09-04
+
+Six defects fixed across 3.x shared one root cause: `currentLevel` is a single
+number, and it cannot describe the approval frontier once a parallel group has
+several levels open at once. Each fix corrected one more reader of it. This
+release fixes the model instead.
+
+### BREAKING — the frontier is explicit
+
+- **`ApprovalInstance.openLevels: number[]`** lists every level currently
+  collecting decisions, ascending — one entry for a sequential chain, several
+  inside a parallel group, empty once the instance is terminal. It is the
+  supported way to ask what an instance is waiting on, and
+  `engine.getOpenLevels(id)` returns it without fetching the whole instance.
+
+- **`currentLevel` is now derived**, defined as the lowest open level and
+  recomputed by the engine on every write. It remains for display and for the
+  audit trail, and a terminal instance keeps its last value so the record still
+  shows where the request stopped.
+
+  **Migrating:** anything using `currentLevel` to decide who may act, what to
+  notify, or what is overdue should read `openLevels`. On a sequential template
+  the two agree, so most callers need no change.
+
+- **Custom `IStorageAdapter` implementations must round-trip `openLevels`**, as
+  they already must for `levels`. The bundled adapters do; `PostgresAdapter`
+  adds an `open_levels` column via `migrate()`.
+
+  `ApprovalInstance` now requires the field, so a hand-built instance (a test
+  fixture, say) will not compile until it supplies one.
+
+### Fixed — returning past a rejected group
+
+- **`returnTo: 'previous'` from inside a parallel group went back into that same
+  group.** It stepped back from `currentLevel`, which — now that the frontier
+  moves as branches close — could be another branch of the group being rejected.
+  It now steps back past the whole group, which is what "return to the previous
+  step" means when the step has several branches.
+
+### Internal
+
+- Every instance write goes through one path that recomputes the frontier first,
+  so a future operation cannot persist levels without updating `openLevels`.
+  This is the same discipline applied to level construction in 3.0.0 and to the
+  PostgreSQL column list in 1.6.0, both of which drifted for the same reason.
+
+## [3.9.0] - 2026-09-04
+
+### Fixed — replacing an approver on a weighted level bricked the approval
+
+- **On a weighted level the weight belongs to the seat, not the person — but
+  replacing the person dropped it.** `weights` is keyed by approver id, and a
+  substitute was not in the map, so they fell back to the default weight of 1.
+
+  A CFO carrying weight 3 on a level with `threshold: 3` who was reassigned,
+  delegated, or covered by out-of-office left the level's achievable weight at
+  2. The next decision then threw
+
+  > `Level 1 ("Exec") needs a weight of 3 but the assigned approvers total only 2.`
+
+  and **nobody could approve the instance again**. `transferApprovals()` did this
+  in bulk, which made offboarding — the exact situation the feature exists for —
+  the most likely way to hit it.
+
+  A substitute now inherits the weight of the approver they replace, through
+  `reassign()`, `delegate()` and out-of-office cover alike. The original's weight
+  is copied rather than moved, so a vote they had already cast keeps counting.
+
+  Nothing is invented: an approver who never carried a weight still gets the
+  default, and escalation continues to *add* approvers at the default weight
+  rather than inheriting anyone's.
+
+## [3.8.0] - 2026-09-04
+
+### Fixed — a condition could build a parallel group the validator forbids
+
+- **`validateTemplate()` checked group contiguity across the static levels
+  only.** A condition whose `addLevels` joined an existing group from further
+  down the chain therefore passed validation and then built, at runtime,
+  precisely the interleaving the rule exists to forbid.
+
+  With levels 1–2 in group `review` and an ungrouped level 3, a rule adding
+  level 4 to `review` produced a chain where levels 1, 2 **and 4** were all open
+  while level 3 sat waiting — the group had jumped over a level that was meant
+  to come first, and the template author's ordering was silently inverted.
+
+  Contiguity is now checked across every level a template can produce, static
+  and condition-added alike. A group whose members are interleaved with anything
+  else is rejected at definition time, where the author can see it.
+
+## [3.7.0] - 2026-09-04
+
+### Fixed — `override()` and expiry did not end the sub-workflow family
+
+3.0.0 made a finished parent stop its children and report to its own parent,
+but wired that into `approve()`, `reject()` and `cancel()` only. `override()`
+and deadline expiry are terminal too, and were missed — so the fix was
+incomplete in exactly the two paths nobody watches.
+
+- **An expired child left its parent waiting forever.** The child reached
+  `cancelled`, but never told the parent, which sat pending on an approval that
+  could now never happen. A permanent deadlock, and the more serious of the two.
+
+- **An overridden parent left its children running** — still notifying, still
+  escalating, still in `getWorkload()`, for a decision whose outcome nobody
+  would read.
+
+Both now run the same post-decision step as every other terminal path.
+`override()` continues to bypass the parent's own remaining levels, which is
+what an administrative override is for; what changes is that it no longer
+strands the work it started.
+
+## [3.6.0] - 2026-09-04
+
+### Fixed — `resubmit()` rebuilt an incomplete chain
+
+- **A resubmitted approval could never finish.** `resubmit()` was a third
+  hand-written copy of level construction, after `submit()` and
+  `recomputeFutureChain()` (unified in 3.0.0), and the only one that decided
+  what to open by **array index** rather than by group. On a template whose
+  chain begins with a parallel group, resubmitting opened just the first branch
+  and left the rest of the group behind.
+
+  It also dropped `group`, `subWorkflow`, `escalationAfterHours` and every
+  reminder field — so a sub-workflow level came back unbound and threw
+  "No approvers resolved for this level" the moment the chain reached it,
+  leaving the approval permanently stuck.
+
+  All three paths now go through the same `buildLevelInstance()`.
+
+### Changed — the release audit gate distinguishes a flaky endpoint from a real CVE
+
+- `npm audit` exits non-zero both for "found an advisory" and for "could not
+  reach the advisory endpoint", and the v3.1.0 publish was blocked by the
+  latter. The CI and publish workflows now retry **only** the transient case,
+  with backoff.
+
+  A genuine high/critical advisory still fails on the first attempt, and an
+  endpoint that stays unreachable still fails the build — refusing to publish
+  unaudited, rather than passing silently the way an `|| true` would.
+
+## [3.5.0] - 2026-09-04
+
+### Fixed — an approval could complete with a branch rejected and another never decided
+
+**The most serious defect found in this audit. Upgrade if you use
+`returnTo: 'previous'` with parallel branch groups.**
+
+Rejecting one branch of a parallel group with `returnTo: 'previous'` sent the
+chain back a level but left the rest of the group as it was — the rejected
+branch still `rejected`, its sibling still `pending`. Neither was `waiting`, and
+the engine treats "no waiting level" as "nothing left to do". So when the
+earlier level was approved again, the instance was marked **`approved`**:
+
+- with one branch **rejected**, and
+- with another branch **nobody had ever decided**.
+
+A document could therefore reach fully-approved without Finance ever approving
+it and over Legal's explicit rejection.
+
+Two independent fixes, because one of them should never have been needed:
+
+- **Returning to a previous level now resets every level above it** to a clean
+  `waiting` state, clearing decisions, approvers and deadlines so the chain
+  replays properly. A branch that had already approved must decide again — its
+  approval was for a version that was sent back.
+
+- **Completion now requires that every level actually be `approved` or
+  `skipped`.** "No next group" alone is not enough. If the two ever disagree the
+  engine throws `INCOMPLETE_CHAIN` naming the offending levels, rather than
+  recording an approval nobody gave. This is a tripwire that should be
+  unreachable — it exists because the state it catches was reachable.
+
+  `override()` is unaffected: bypassing the remaining levels is exactly what an
+  administrative override is for.
+
+## [3.4.0] - 2026-09-04
+
+### Fixed — notifications went to the wrong people
+
+`NotificationEvent.recipients` is what an adapter actually delivers to, and it
+was read from the single level matching `instance.currentLevel`. That was wrong
+in two directions at once.
+
+- **An approver on any branch of a parallel group except the lowest was never
+  notified.** They were not told work had arrived, not told the instance
+  advanced — nothing. Combined with the inbox bug fixed in 3.3.0, an
+  upper-branch approver had no way at all to learn they owed a decision.
+  Recipients are now the union across every open level, matching what
+  `getCurrentApprovers()` has returned since 1.0.0.
+
+- **An event that already named its own audience had it overwritten.** A comment
+  mentioning one person was delivered to the current level's approvers instead
+  of the person mentioned; a reminder aimed at those who had not yet voted, and
+  a clarification request addressed to the submitter, were redirected the same
+  way. An event that names recipients now keeps them.
+
+  This had been latent since mentions were added in 2.8.0: the payload carried
+  the right audience and the adapter boundary discarded it.
+
+- **`ApprovalTestKit.fullyApprove()` could not drive a parallel group.** It read
+  `instance.currentLevel`, which does not move until the whole group closes, so
+  it approved the lowest branch and then re-offered the same decision until the
+  engine refused it. It now walks every open level.
 
 ## [3.3.0] - 2026-09-04
 

package/README.md

@@ -11,7 +11,7 @@ Multi-tenant · audit-ready · fully pluggable · zero runtime dependencies you
 [![types](https://img.shields.io/npm/types/hierarchical-approval.svg?logo=typescript&logoColor=white&color=3178c6)](https://www.typescriptlang.org/)
 [![minzipped size](https://img.shields.io/bundlephobia/minzip/hierarchical-approval?color=44cc11)](https://bundlephobia.com/package/hierarchical-approval)
 [![license](https://img.shields.io/npm/l/hierarchical-approval.svg?color=blue)](./LICENSE)
-[![tests](https://img.shields.io/badge/tests-404%20passing-44cc11.svg?logo=vitest&logoColor=white)](./tests)
+[![tests](https://img.shields.io/badge/tests-1204%20passing-44cc11.svg?logo=vitest&logoColor=white)](./tests)
 
 [**Documentation**](https://hierarchical-approval.matthewswong.com) ·
 [**npm**](https://www.npmjs.com/package/hierarchical-approval) ·
@@ -878,6 +878,27 @@ never change who can approve or when the level escalates.
 
 Requires the escalation scheduler to be running (it is by default).
 
+### Reading the approval frontier
+
+`instance.openLevels` lists every level currently collecting decisions —
+one entry for a sequential chain, several inside a parallel group, none once the
+instance is terminal:
+
+```ts
+const { openLevels, currentLevel } = await engine.getInstance(id);
+// sequential:      openLevels [2],    currentLevel 2
+// parallel group:  openLevels [2, 3], currentLevel 2
+await engine.getOpenLevels(id);   // same list, without the whole instance
+```
+
+**`currentLevel` names only the lowest open level.** That is the whole frontier
+for a sequential chain and one branch of a parallel group, so use `openLevels`
+to decide who may act, what to notify, or what is overdue. Reading `currentLevel`
+as the frontier was the root cause of six defects fixed across 3.x.
+
+Both are maintained by the engine; `currentLevel` is derived from `openLevels`
+and recomputed on every write.
+
 ### Parallel branch groups
 
 Give levels the same `group` name and they activate together, joining before

package/dist/{ApprovalEngine-Cslh4Goz.d.ts → ApprovalEngine-BfKL6iGQ.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-CEKfu-U8.js';
-import { m as ConditionExpression, r as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, C as Comment, e as ApprovalMode, f as ApprovalStatus, L as LevelStatus, b as AuditEntry } from './instance-BXHxvTLE.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-C-PL3Pvp.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-CdXMggPK.js';
+import { m as ConditionExpression, r as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, C as Comment, e as ApprovalMode, f as ApprovalStatus, L as LevelStatus, b as AuditEntry } from './instance-uUQh5XW3.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BTO9FSKy.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-Cbd05rje.js';
-import { I as IAuditAdapter } from './IAuditAdapter-udkAnnmu.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-CX7lo4lp.js';
+import { I as IAuditAdapter } from './IAuditAdapter-DkbyFFjb.js';
 import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-Z4nkX-bu.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-eo6glbpE.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -856,6 +856,17 @@ declare class ApprovalEngine {
     queryInstances(filter: InstanceFilter, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
     queryInstancesByCursor(filter: InstanceFilter, opts: CursorPaginationOpts): Promise<CursorPaginatedResult<ApprovalInstance>>;
     getHistory(instanceId: string): Promise<AuditEntry[]>;
+    /**
+     * The levels currently collecting decisions, ascending.
+     *
+     * The supported way to ask what an instance is waiting on.
+     * {@link ApprovalInstance.currentLevel} names only the lowest of these, which
+     * is the whole frontier for a sequential chain and one branch of it inside a
+     * parallel group.
+     *
+     * Empty once the instance is terminal.
+     */
+    getOpenLevels(instanceId: string): Promise<number[]>;
     getCurrentApprovers(instanceId: string): Promise<string[]>;
     /** Check adapter connectivity and escalation scheduler health. */
     healthCheck(): Promise<HealthResult>;
@@ -946,6 +957,7 @@ declare class ApprovalEngine {
         dryRun?: boolean;
     }): Promise<PurgeResult>;
     getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
+    /** Stops the escalation scheduler and any scheduler-adapter background loop; call once when tearing the engine down. */
     shutdown(): Promise<void>;
     /**
      * Schedules the next escalation scan via {@link ApprovalEngineOptions.schedulerAdapter}.
@@ -1008,6 +1020,42 @@ declare class ApprovalEngine {
      * @param opts - `open` activates the level now, computing deadlines from `now`.
      */
     private buildLevelInstance;
+    /**
+     * Carry a weighted level's vote weight from one approver to another.
+     *
+     * On a weighted level the weight belongs to the **seat**, not to the person
+     * filling it. Without this, replacing an approver silently dropped their
+     * weight to the default of 1: a CFO carrying weight 3 who was reassigned,
+     * delegated or covered while away left the level unable to reach its
+     * threshold, and the next decision threw "needs a weight of 3 but the
+     * assigned approvers total only 2" — an approval nobody could complete.
+     *
+     * A no-op unless the level actually carries weights and the original had one.
+     */
+    private inheritWeight;
+    /** Apply {@link inheritWeight} for every out-of-office substitution made on a level. */
+    private inheritWeightsForSubstitutions;
+    /**
+     * Recompute the approval frontier from the levels themselves.
+     *
+     * `openLevels` is every level currently collecting decisions, and
+     * `currentLevel` is the lowest of them. Deriving both from one place means
+     * they cannot drift out of step with the levels — the failure behind six
+     * defects fixed across 3.x, each of which read `currentLevel` as though it
+     * named the whole frontier.
+     *
+     * A terminal instance has no open levels; `currentLevel` keeps its last value
+     * so the audit trail and any UI still show where it finished.
+     */
+    private syncFrontier;
+    /**
+     * The single write path for an instance.
+     *
+     * Every mutation goes through here so the frontier is recomputed before the
+     * instance is stored. Writing through the adapter directly would let a new
+     * operation persist levels without updating `openLevels`.
+     */
+    private persistInstance;
     /** Level deadline from whichever of days/hours the template configured. */
     private levelEscalationDue;
     /** First rung of a ladder, sorted by delay, or undefined when there is none. */
@@ -1133,7 +1181,39 @@ declare class ApprovalEngine {
      */
     private cancelOrphanedChildren;
     private afterDecision;
+    /**
+     * Return every level above `levelNumber` to a clean `waiting` state.
+     *
+     * Used when a rejection sends the chain back: a level that keeps a stale
+     * `approved`/`rejected` status is neither open nor replayable, and the engine
+     * treats "nothing waiting" as "nothing left to do".
+     */
+    private resetLevelsAfter;
+    /**
+     * Whether an instance has genuinely finished approving.
+     *
+     * "No next group" is not the same as "every level approved": a level left in
+     * a stale state is neither open nor waiting, and treating that as completion
+     * marked instances approved with a branch still undecided. Completion now
+     * requires that every level actually reached a positive terminal state.
+     */
+    private isFullyApproved;
+    /**
+     * Refuse to complete an instance that has not actually been approved throughout.
+     *
+     * A tripwire, not a routine check: it should be unreachable, and it exists
+     * because the state it catches was reachable and silently produced an
+     * approved document that one branch had rejected and another had never seen.
+     */
+    private assertFullyApproved;
     private findNextLevel;
+    /**
+     * The level to send an instance back to, given the level being rejected.
+     *
+     * Sends the chain back past the **whole group** the rejection came from, not
+     * merely one level. Returning into a sibling branch of the same group would
+     * put the instance back inside the step it was just rejected at.
+     */
     private findPreviousLevel;
     private guardBulkSize;
     private runAuthorizationPolicy;

package/dist/{ApprovalEngine-zAgvH_aO.d.cts → ApprovalEngine-DcD6s_jB.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-DUrmnJUs.cjs';
-import { m as ConditionExpression, r as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, C as Comment, e as ApprovalMode, f as ApprovalStatus, L as LevelStatus, b as AuditEntry } from './instance-BXHxvTLE.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-D3PBQE1B.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-Cjw5zDwQ.cjs';
+import { m as ConditionExpression, r as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, C as Comment, e as ApprovalMode, f as ApprovalStatus, L as LevelStatus, b as AuditEntry } from './instance-uUQh5XW3.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-XbD69gss.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-tgJcKzTP.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-BkxGx6TI.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-BBLk8MIz.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-Dt8qjkQL.cjs';
 import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-YQlSwj-8.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-YJ_08Mof.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -856,6 +856,17 @@ declare class ApprovalEngine {
     queryInstances(filter: InstanceFilter, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
     queryInstancesByCursor(filter: InstanceFilter, opts: CursorPaginationOpts): Promise<CursorPaginatedResult<ApprovalInstance>>;
     getHistory(instanceId: string): Promise<AuditEntry[]>;
+    /**
+     * The levels currently collecting decisions, ascending.
+     *
+     * The supported way to ask what an instance is waiting on.
+     * {@link ApprovalInstance.currentLevel} names only the lowest of these, which
+     * is the whole frontier for a sequential chain and one branch of it inside a
+     * parallel group.
+     *
+     * Empty once the instance is terminal.
+     */
+    getOpenLevels(instanceId: string): Promise<number[]>;
     getCurrentApprovers(instanceId: string): Promise<string[]>;
     /** Check adapter connectivity and escalation scheduler health. */
     healthCheck(): Promise<HealthResult>;
@@ -946,6 +957,7 @@ declare class ApprovalEngine {
         dryRun?: boolean;
     }): Promise<PurgeResult>;
     getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
+    /** Stops the escalation scheduler and any scheduler-adapter background loop; call once when tearing the engine down. */
     shutdown(): Promise<void>;
     /**
      * Schedules the next escalation scan via {@link ApprovalEngineOptions.schedulerAdapter}.
@@ -1008,6 +1020,42 @@ declare class ApprovalEngine {
      * @param opts - `open` activates the level now, computing deadlines from `now`.
      */
     private buildLevelInstance;
+    /**
+     * Carry a weighted level's vote weight from one approver to another.
+     *
+     * On a weighted level the weight belongs to the **seat**, not to the person
+     * filling it. Without this, replacing an approver silently dropped their
+     * weight to the default of 1: a CFO carrying weight 3 who was reassigned,
+     * delegated or covered while away left the level unable to reach its
+     * threshold, and the next decision threw "needs a weight of 3 but the
+     * assigned approvers total only 2" — an approval nobody could complete.
+     *
+     * A no-op unless the level actually carries weights and the original had one.
+     */
+    private inheritWeight;
+    /** Apply {@link inheritWeight} for every out-of-office substitution made on a level. */
+    private inheritWeightsForSubstitutions;
+    /**
+     * Recompute the approval frontier from the levels themselves.
+     *
+     * `openLevels` is every level currently collecting decisions, and
+     * `currentLevel` is the lowest of them. Deriving both from one place means
+     * they cannot drift out of step with the levels — the failure behind six
+     * defects fixed across 3.x, each of which read `currentLevel` as though it
+     * named the whole frontier.
+     *
+     * A terminal instance has no open levels; `currentLevel` keeps its last value
+     * so the audit trail and any UI still show where it finished.
+     */
+    private syncFrontier;
+    /**
+     * The single write path for an instance.
+     *
+     * Every mutation goes through here so the frontier is recomputed before the
+     * instance is stored. Writing through the adapter directly would let a new
+     * operation persist levels without updating `openLevels`.
+     */
+    private persistInstance;
     /** Level deadline from whichever of days/hours the template configured. */
     private levelEscalationDue;
     /** First rung of a ladder, sorted by delay, or undefined when there is none. */
@@ -1133,7 +1181,39 @@ declare class ApprovalEngine {
      */
     private cancelOrphanedChildren;
     private afterDecision;
+    /**
+     * Return every level above `levelNumber` to a clean `waiting` state.
+     *
+     * Used when a rejection sends the chain back: a level that keeps a stale
+     * `approved`/`rejected` status is neither open nor replayable, and the engine
+     * treats "nothing waiting" as "nothing left to do".
+     */
+    private resetLevelsAfter;
+    /**
+     * Whether an instance has genuinely finished approving.
+     *
+     * "No next group" is not the same as "every level approved": a level left in
+     * a stale state is neither open nor waiting, and treating that as completion
+     * marked instances approved with a branch still undecided. Completion now
+     * requires that every level actually reached a positive terminal state.
+     */
+    private isFullyApproved;
+    /**
+     * Refuse to complete an instance that has not actually been approved throughout.
+     *
+     * A tripwire, not a routine check: it should be unreachable, and it exists
+     * because the state it catches was reachable and silently produced an
+     * approved document that one branch had rejected and another had never seen.
+     */
+    private assertFullyApproved;
     private findNextLevel;
+    /**
+     * The level to send an instance back to, given the level being rejected.
+     *
+     * Sends the chain back past the **whole group** the rejection came from, not
+     * merely one level. Returning into a sibling branch of the same group would
+     * put the instance back inside the step it was just rejected at.
+     */
     private findPreviousLevel;
     private guardBulkSize;
     private runAuthorizationPolicy;

package/dist/{IAuditAdapter-udkAnnmu.d.ts → IAuditAdapter-DkbyFFjb.d.ts}

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

package/dist/{IAuditAdapter-BkxGx6TI.d.cts → IAuditAdapter-Dt8qjkQL.d.cts}

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

package/dist/{IAuthorizationPolicy-YQlSwj-8.d.cts → IAuthorizationPolicy-YJ_08Mof.d.cts}

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

package/dist/{IAuthorizationPolicy-Z4nkX-bu.d.ts → IAuthorizationPolicy-eo6glbpE.d.ts}

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

package/dist/{INotificationAdapter-C-PL3Pvp.d.ts → INotificationAdapter-BTO9FSKy.d.ts}

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

package/dist/{INotificationAdapter-D3PBQE1B.d.cts → INotificationAdapter-XbD69gss.d.cts}

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

package/dist/{IOperationMiddleware-tgJcKzTP.d.cts → IOperationMiddleware-BBLk8MIz.d.cts}

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

package/dist/{IOperationMiddleware-Cbd05rje.d.ts → IOperationMiddleware-CX7lo4lp.d.ts}

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

package/dist/{IStorageAdapter-CEKfu-U8.d.ts → IStorageAdapter-CdXMggPK.d.ts}

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

package/dist/{IStorageAdapter-DUrmnJUs.d.cts → IStorageAdapter-Cjw5zDwQ.d.cts}

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