hierarchical-approval 4.0.1 → 4.0.2

package/CHANGELOG.md

@@ -1,9 +1,8 @@
-## 4.0.1 - 2026-09-14
+## 4.0.2 - 2026-09-20
 
-- 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
+- fix(notify): name the offending value in DigestNotificationAdapter's error
+- fix(engine): stop leaking a listener when on() double-registers it
+- fix(webhook): give the real-timer sleep test slack for CI jitter
 
 # Changelog
 
@@ -14,9 +13,23 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- `EventBus` (and therefore `engine.on()`/`off()`) no longer leaks a listener
+  when the same function is registered twice with `on()`: each registration
+  now needs its own `off()` call to undo, instead of the second registration
+  silently overwriting the bookkeeping for the first and leaving it permanently
+  attached.
+- `DigestNotificationAdapter`'s `intervalMs` validation error now names the
+  offending value, instead of a message that gave no clue which value failed.
+
+## [4.0.1] - 2026-09-14
+
+### 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.
+- `RateLimitMiddleware` errors now include the offending value that tripped
+  the limit, instead of a message that named the limit but not the input.
 
 ## [4.0.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-1204%20passing-44cc11.svg?logo=vitest&logoColor=white)](./tests)
+[![tests](https://img.shields.io/badge/tests-1256%20passing-44cc11.svg?logo=vitest&logoColor=white)](./tests)
 
 [**Documentation**](https://hierarchical-approval.matthewswong.com) ·
 [**npm**](https://www.npmjs.com/package/hierarchical-approval) ·

package/dist/{ApprovalEngine-BfKL6iGQ.d.ts → ApprovalEngine-Dqe-rC6K.d.ts}

@@ -625,18 +625,71 @@ declare class ApprovalEngine {
     /** Set by {@link shutdown}; stops the self-rescheduling loop from scheduling another tick. */
     private schedulerStopped;
     constructor(opts: ApprovalEngineOptions);
+    /**
+     * Subscribe to a lifecycle event (see {@link ApprovalEventMap} for the full
+     * catalog and each payload's shape). A listener that throws, or returns a
+     * rejecting promise, cannot abort the operation that emitted the event or
+     * block the remaining listeners — the failure is reported via the engine's
+     * logger instead.
+     *
+     * @returns `this`, for chaining multiple subscriptions.
+     */
     on<K extends ApprovalEventName>(event: K, listener: (payload: ApprovalEventMap[K]) => void): this;
+    /**
+     * Unsubscribe a listener previously registered with {@link on}. A no-op if
+     * `listener` was never registered for `event`.
+     *
+     * @returns `this`, for chaining.
+     */
     off<K extends ApprovalEventName>(event: K, listener: (payload: ApprovalEventMap[K]) => void): this;
+    /**
+     * Register a dynamic-approver resolver under `name`, for use by a level whose
+     * approver config is `{ type: 'dynamic', resolver: name }`. Overwrites any
+     * resolver already registered under the same name.
+     */
     registerResolver(name: string, fn: ResolverFn): void;
+    /**
+     * Register a custom approver type under `typeName`, for use by a level whose
+     * approver config carries `{ type: typeName, ... }`. Overwrites any approver
+     * type already registered under the same type name.
+     */
     registerApproverType(typeName: string, fn: ApproverResolverFn): void;
+    /**
+     * Register a custom condition operator under `name`, for use by template
+     * condition rules whose `operator` is `name`. Operators are shared process-wide
+     * across every engine instance, not scoped to this tenant.
+     *
+     * @throws {@link ApprovalValidationError} if `name` is already taken by a
+     * built-in operator (`>`, `<`, `>=`, `<=`, `==`, `!=`, `in`, `not_in`).
+     */
     registerConditionOperator(name: string, fn: ConditionOperatorFn): void;
     /** Validate a template config without persisting. Synchronous; never throws. */
     validateTemplate(config: ApprovalTemplateConfig): ValidationResult;
     defineTemplate(config: ApprovalTemplateConfig): Promise<string>;
     /** Update an existing template, incrementing its version. In-flight instances are protected by their templateSnapshot. */
     updateTemplate(config: ApprovalTemplateConfig): Promise<string>;
+    /**
+     * Fetch the current version of a defined template.
+     *
+     * @throws {@link ApprovalTemplateNotFoundError} if no template is registered under `name`.
+     */
     getTemplate(name: string): Promise<ApprovalTemplate>;
+    /** List every template currently defined for this tenant. */
     listTemplates(): Promise<ApprovalTemplate[]>;
+    /**
+     * Start a new approval instance from a defined template.
+     *
+     * Evaluates the template's conditions against `raw.data` first, so the
+     * levels an instance opens with can differ from the template's static
+     * declaration (added, skipped, or reordered). If a prior call with the
+     * same tenant, document, template and data produced a non-terminal
+     * instance, that instance is returned unchanged instead of creating a
+     * duplicate — safe to retry on network failure.
+     *
+     * @throws {@link ApprovalTemplateNotFoundError} if `raw.templateName` is not defined.
+     * @throws {@link ApprovalValidationError} if `raw` fails schema validation, or if
+     *   condition evaluation leaves no levels (or a duplicate level number) to open.
+     */
     submit(raw: SubmitOptions, auditCtx?: AuditContext, 
     /**
      * @internal Set only when the engine spawns a sub-workflow child. Passed at
@@ -649,8 +702,63 @@ declare class ApprovalEngine {
         parentLevel: number;
         depth: number;
     }): Promise<ApprovalInstance>;
+    /**
+     * Record `opts.approverId`'s approval of their open level on `instanceId`.
+     *
+     * When more than one level is open in parallel and the approver sits on
+     * exactly one of them, that level is inferred; pass `opts.level` explicitly
+     * when it must be disambiguated (e.g. the approver sits on several).
+     *
+     * @throws {@link ApprovalNotFoundError} if `instanceId` does not exist.
+     * @throws {@link ApprovalError} (code `INVALID_STATUS`) if the instance is not `pending`,
+     *   (code `INVALID_LEVEL`) if no level (or the explicit `opts.level`) is awaiting a decision,
+     *   or (code `ALREADY_ACTED`) if this approver already approved or rejected that level.
+     * @throws {@link ApprovalForbiddenError} if `opts.approverId` submitted the instance
+     *   (self-approval), is not an approver on the resolved level, or is denied by the
+     *   configured {@link IAuthorizationPolicy}.
+     * @throws {@link ApprovalValidationError} if `opts.approverId` sits on more than one
+     *   open parallel level and `opts.level` was not supplied to disambiguate.
+     */
     approve(instanceId: string, raw: ApproveOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Record `opts.approverId`'s rejection of their open level on `instanceId`.
+     *
+     * A single rejection does not necessarily fail the level — under `'quorum'`
+     * or `'weighted'` mode it only fails once the remaining approvers can no
+     * longer reach threshold. When the level does fail, `opts.returnTo`
+     * controls what happens next: `'originator'` (default) fails the whole
+     * instance; `'previous'` resets every level after the prior one and sends
+     * the instance back there to replay.
+     *
+     * @throws {@link ApprovalNotFoundError} if `instanceId` does not exist.
+     * @throws {@link ApprovalError} (code `INVALID_STATUS`) if the instance is not `pending`,
+     *   (code `INVALID_LEVEL`) if no level (or the explicit `opts.level`) is awaiting a decision,
+     *   or (code `ALREADY_ACTED`) if this approver already approved or rejected that level.
+     * @throws {@link ApprovalForbiddenError} if `opts.approverId` submitted the instance
+     *   (self-rejection), is not an approver on the resolved level, or is denied by the
+     *   configured {@link IAuthorizationPolicy}.
+     * @throws {@link ApprovalValidationError} if `opts.approverId` sits on more than one
+     *   open parallel level with `opts.level` unset, or if `opts.returnTo === 'previous'`
+     *   but the failing level is already the first level in the chain.
+     */
     reject(instanceId: string, raw: RejectOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Reassign `opts.fromApprover`'s seat on their open level to `opts.toApprover`,
+     * carrying across any 'weighted'-mode vote weight. When `opts.until` is set,
+     * the level records `delegatedFrom`/`delegatedTo`/`delegatedUntil`, and the
+     * scheduled escalation tick reassigns the seat back to `opts.fromApprover`
+     * once that time passes (still pending); omit `opts.until` for a permanent
+     * handoff.
+     *
+     * @throws {@link ApprovalNotFoundError} if `instanceId` does not exist.
+     * @throws {@link ApprovalError} (code `INVALID_STATUS`) if the instance is not `pending`,
+     *   or (code `INVALID_LEVEL`) if no level (or the explicit `opts.level`) is awaiting a decision.
+     * @throws {@link ApprovalForbiddenError} if `opts.fromApprover` equals `opts.toApprover`,
+     *   is not an approver on the resolved level, already acted on it, or is denied by the
+     *   configured {@link IAuthorizationPolicy}.
+     * @throws {@link ApprovalValidationError} if `opts.fromApprover` sits on more than one
+     *   open parallel level and `opts.level` was not supplied to disambiguate.
+     */
     delegate(instanceId: string, raw: DelegateOptions, auditCtx?: AuditContext): Promise<void>;
     /**
      * Administratively replace an approver on the current level. Unlike delegate(),
@@ -660,7 +768,36 @@ declare class ApprovalEngine {
      * cannot be reassigned.
      */
     reassign(instanceId: string, raw: ReassignOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Withdraw an approval before it reaches a final decision.
+     *
+     * Cancelling cascades: any sub-workflow children spawned by this instance
+     * are cancelled in turn (an orphaned child left running would eventually
+     * report back to a parent that already moved on), and if this instance is
+     * itself a sub-workflow child, its own parent is unblocked as if this
+     * approval had been rejected.
+     *
+     * @param instanceId - The instance to cancel.
+     * @param raw - Who is cancelling and why.
+     * @param auditCtx - Optional compliance context recorded on the audit entry.
+     * @returns The cancelled instance.
+     * @throws ApprovalError if the instance is already `approved` or `rejected`.
+     */
     cancel(instanceId: string, raw: CancelOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Manually escalate the instance's current (lowest pending) level to the
+     * next rung of its escalation ladder, adding whatever the rung's
+     * `escalateTo` resolves to as extra approvers on that level. This is the
+     * same path the scheduled tick uses for a deadline-driven escalation — call
+     * it directly to escalate on demand instead of waiting for the ladder timer.
+     *
+     * A no-op (returns the instance unchanged, does not throw) when: the
+     * instance is not `pending`; the ladder has no rung configured for the
+     * current step; or every resolved approver turns out to be the submitter
+     * (nobody new to add).
+     *
+     * @throws {@link ApprovalNotFoundError} if `instanceId` does not exist.
+     */
     escalate(instanceId: string, raw: EscalateOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /**
      * Change an instance's document data while it is still pending, and
@@ -822,6 +959,17 @@ declare class ApprovalEngine {
         submittedBy: string;
         decisions?: SimulatedDecision[];
     }): Promise<SimulationResult>;
+    /**
+     * Check whether a user could approve an instance right now, without acting.
+     *
+     * The read-only counterpart to calling {@link approve} and handling the
+     * rejection — useful for deciding whether to show an approve button at all.
+     * `eligible: false` never throws; the reason names why: the instance is not
+     * `pending`, the user submitted it, they hold no open level (or delegated
+     * theirs away), or they already voted on it.
+     *
+     * @returns `{ eligible: true }`, or `{ eligible: false, reason }`.
+     */
     canApprove(instanceId: string, userId: string): Promise<CanApproveResult>;
     /** Emergency bypass — completes the instance as 'approved', skipping remaining levels. Requires template.allowOverride = true. */
     override(instanceId: string, raw: OverrideOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
@@ -848,13 +996,34 @@ declare class ApprovalEngine {
      * @returns What moved, what did not, and why. With `dryRun` nothing is written.
      */
     transferApprovals(raw: TransferApprovalsOptions, auditCtx?: AuditContext): Promise<TransferResult>;
+    /** Approve multiple instances in one call. Never throws — failures collected in result.failed. */
     bulkApprove(instanceIds: string[], raw: ApproveOptions, auditCtx?: AuditContext): Promise<BulkResult>;
     /** Reject multiple instances in one call. Never throws — failures collected in result.failed. */
     bulkReject(instanceIds: string[], raw: RejectOptions, auditCtx?: AuditContext): Promise<BulkResult>;
+    /**
+     * Fetch a single instance by id.
+     *
+     * @throws {@link ApprovalNotFoundError} if no instance exists with that id.
+     */
     getInstance(instanceId: string): Promise<ApprovalInstance>;
+    /** Page through every instance with an open level assigned to one approver. */
     getPendingFor(approverId: string, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
+    /** Page through instances matching an arbitrary filter (status, document type, date range, ...). */
     queryInstances(filter: InstanceFilter, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
+    /**
+     * Cursor-paginated variant of {@link queryInstances}, for stable paging
+     * through large or actively-changing result sets that offset pagination
+     * would skip or duplicate rows in.
+     *
+     * @throws {@link ApprovalError} (`NOT_SUPPORTED`) if the configured storage
+     * adapter does not implement `getInstancesByCursor`.
+     */
     queryInstancesByCursor(filter: InstanceFilter, opts: CursorPaginationOpts): Promise<CursorPaginatedResult<ApprovalInstance>>;
+    /**
+     * The full audit trail for an instance, in the order it was recorded.
+     *
+     * @throws {@link ApprovalNotFoundError} if no instance exists with that id.
+     */
     getHistory(instanceId: string): Promise<AuditEntry[]>;
     /**
      * The levels currently collecting decisions, ascending.
@@ -867,6 +1036,16 @@ declare class ApprovalEngine {
      * Empty once the instance is terminal.
      */
     getOpenLevels(instanceId: string): Promise<number[]>;
+    /**
+     * Everyone who currently owes a decision on an instance.
+     *
+     * A union across every open branch, so a parallel group with more than one
+     * level collecting decisions at once still names every approver, not just
+     * the one at {@link ApprovalInstance.currentLevel}. Empty once the instance
+     * is no longer `pending`.
+     *
+     * @throws {@link ApprovalNotFoundError} if no instance exists with that id.
+     */
     getCurrentApprovers(instanceId: string): Promise<string[]>;
     /** Check adapter connectivity and escalation scheduler health. */
     healthCheck(): Promise<HealthResult>;
@@ -956,6 +1135,15 @@ declare class ApprovalEngine {
         limit?: number;
         dryRun?: boolean;
     }): Promise<PurgeResult>;
+    /**
+     * Aggregate reporting numbers for a tenant: counts by status, approval
+     * rate, cycle-time stats, and a per-template breakdown.
+     *
+     * `filter.status` is ignored — the breakdown covers every status by
+     * design, so scoping it to one would make the counts misleading.
+     *
+     * @param filter - Optional scoping by document type, submitter, or date range.
+     */
     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>;
@@ -1206,7 +1394,6 @@ declare class ApprovalEngine {
      * 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.
      *

package/dist/{ApprovalEngine-DcD6s_jB.d.cts → ApprovalEngine-XgGBQLC_.d.cts}

@@ -625,18 +625,71 @@ declare class ApprovalEngine {
     /** Set by {@link shutdown}; stops the self-rescheduling loop from scheduling another tick. */
     private schedulerStopped;
     constructor(opts: ApprovalEngineOptions);
+    /**
+     * Subscribe to a lifecycle event (see {@link ApprovalEventMap} for the full
+     * catalog and each payload's shape). A listener that throws, or returns a
+     * rejecting promise, cannot abort the operation that emitted the event or
+     * block the remaining listeners — the failure is reported via the engine's
+     * logger instead.
+     *
+     * @returns `this`, for chaining multiple subscriptions.
+     */
     on<K extends ApprovalEventName>(event: K, listener: (payload: ApprovalEventMap[K]) => void): this;
+    /**
+     * Unsubscribe a listener previously registered with {@link on}. A no-op if
+     * `listener` was never registered for `event`.
+     *
+     * @returns `this`, for chaining.
+     */
     off<K extends ApprovalEventName>(event: K, listener: (payload: ApprovalEventMap[K]) => void): this;
+    /**
+     * Register a dynamic-approver resolver under `name`, for use by a level whose
+     * approver config is `{ type: 'dynamic', resolver: name }`. Overwrites any
+     * resolver already registered under the same name.
+     */
     registerResolver(name: string, fn: ResolverFn): void;
+    /**
+     * Register a custom approver type under `typeName`, for use by a level whose
+     * approver config carries `{ type: typeName, ... }`. Overwrites any approver
+     * type already registered under the same type name.
+     */
     registerApproverType(typeName: string, fn: ApproverResolverFn): void;
+    /**
+     * Register a custom condition operator under `name`, for use by template
+     * condition rules whose `operator` is `name`. Operators are shared process-wide
+     * across every engine instance, not scoped to this tenant.
+     *
+     * @throws {@link ApprovalValidationError} if `name` is already taken by a
+     * built-in operator (`>`, `<`, `>=`, `<=`, `==`, `!=`, `in`, `not_in`).
+     */
     registerConditionOperator(name: string, fn: ConditionOperatorFn): void;
     /** Validate a template config without persisting. Synchronous; never throws. */
     validateTemplate(config: ApprovalTemplateConfig): ValidationResult;
     defineTemplate(config: ApprovalTemplateConfig): Promise<string>;
     /** Update an existing template, incrementing its version. In-flight instances are protected by their templateSnapshot. */
     updateTemplate(config: ApprovalTemplateConfig): Promise<string>;
+    /**
+     * Fetch the current version of a defined template.
+     *
+     * @throws {@link ApprovalTemplateNotFoundError} if no template is registered under `name`.
+     */
     getTemplate(name: string): Promise<ApprovalTemplate>;
+    /** List every template currently defined for this tenant. */
     listTemplates(): Promise<ApprovalTemplate[]>;
+    /**
+     * Start a new approval instance from a defined template.
+     *
+     * Evaluates the template's conditions against `raw.data` first, so the
+     * levels an instance opens with can differ from the template's static
+     * declaration (added, skipped, or reordered). If a prior call with the
+     * same tenant, document, template and data produced a non-terminal
+     * instance, that instance is returned unchanged instead of creating a
+     * duplicate — safe to retry on network failure.
+     *
+     * @throws {@link ApprovalTemplateNotFoundError} if `raw.templateName` is not defined.
+     * @throws {@link ApprovalValidationError} if `raw` fails schema validation, or if
+     *   condition evaluation leaves no levels (or a duplicate level number) to open.
+     */
     submit(raw: SubmitOptions, auditCtx?: AuditContext, 
     /**
      * @internal Set only when the engine spawns a sub-workflow child. Passed at
@@ -649,8 +702,63 @@ declare class ApprovalEngine {
         parentLevel: number;
         depth: number;
     }): Promise<ApprovalInstance>;
+    /**
+     * Record `opts.approverId`'s approval of their open level on `instanceId`.
+     *
+     * When more than one level is open in parallel and the approver sits on
+     * exactly one of them, that level is inferred; pass `opts.level` explicitly
+     * when it must be disambiguated (e.g. the approver sits on several).
+     *
+     * @throws {@link ApprovalNotFoundError} if `instanceId` does not exist.
+     * @throws {@link ApprovalError} (code `INVALID_STATUS`) if the instance is not `pending`,
+     *   (code `INVALID_LEVEL`) if no level (or the explicit `opts.level`) is awaiting a decision,
+     *   or (code `ALREADY_ACTED`) if this approver already approved or rejected that level.
+     * @throws {@link ApprovalForbiddenError} if `opts.approverId` submitted the instance
+     *   (self-approval), is not an approver on the resolved level, or is denied by the
+     *   configured {@link IAuthorizationPolicy}.
+     * @throws {@link ApprovalValidationError} if `opts.approverId` sits on more than one
+     *   open parallel level and `opts.level` was not supplied to disambiguate.
+     */
     approve(instanceId: string, raw: ApproveOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Record `opts.approverId`'s rejection of their open level on `instanceId`.
+     *
+     * A single rejection does not necessarily fail the level — under `'quorum'`
+     * or `'weighted'` mode it only fails once the remaining approvers can no
+     * longer reach threshold. When the level does fail, `opts.returnTo`
+     * controls what happens next: `'originator'` (default) fails the whole
+     * instance; `'previous'` resets every level after the prior one and sends
+     * the instance back there to replay.
+     *
+     * @throws {@link ApprovalNotFoundError} if `instanceId` does not exist.
+     * @throws {@link ApprovalError} (code `INVALID_STATUS`) if the instance is not `pending`,
+     *   (code `INVALID_LEVEL`) if no level (or the explicit `opts.level`) is awaiting a decision,
+     *   or (code `ALREADY_ACTED`) if this approver already approved or rejected that level.
+     * @throws {@link ApprovalForbiddenError} if `opts.approverId` submitted the instance
+     *   (self-rejection), is not an approver on the resolved level, or is denied by the
+     *   configured {@link IAuthorizationPolicy}.
+     * @throws {@link ApprovalValidationError} if `opts.approverId` sits on more than one
+     *   open parallel level with `opts.level` unset, or if `opts.returnTo === 'previous'`
+     *   but the failing level is already the first level in the chain.
+     */
     reject(instanceId: string, raw: RejectOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Reassign `opts.fromApprover`'s seat on their open level to `opts.toApprover`,
+     * carrying across any 'weighted'-mode vote weight. When `opts.until` is set,
+     * the level records `delegatedFrom`/`delegatedTo`/`delegatedUntil`, and the
+     * scheduled escalation tick reassigns the seat back to `opts.fromApprover`
+     * once that time passes (still pending); omit `opts.until` for a permanent
+     * handoff.
+     *
+     * @throws {@link ApprovalNotFoundError} if `instanceId` does not exist.
+     * @throws {@link ApprovalError} (code `INVALID_STATUS`) if the instance is not `pending`,
+     *   or (code `INVALID_LEVEL`) if no level (or the explicit `opts.level`) is awaiting a decision.
+     * @throws {@link ApprovalForbiddenError} if `opts.fromApprover` equals `opts.toApprover`,
+     *   is not an approver on the resolved level, already acted on it, or is denied by the
+     *   configured {@link IAuthorizationPolicy}.
+     * @throws {@link ApprovalValidationError} if `opts.fromApprover` sits on more than one
+     *   open parallel level and `opts.level` was not supplied to disambiguate.
+     */
     delegate(instanceId: string, raw: DelegateOptions, auditCtx?: AuditContext): Promise<void>;
     /**
      * Administratively replace an approver on the current level. Unlike delegate(),
@@ -660,7 +768,36 @@ declare class ApprovalEngine {
      * cannot be reassigned.
      */
     reassign(instanceId: string, raw: ReassignOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Withdraw an approval before it reaches a final decision.
+     *
+     * Cancelling cascades: any sub-workflow children spawned by this instance
+     * are cancelled in turn (an orphaned child left running would eventually
+     * report back to a parent that already moved on), and if this instance is
+     * itself a sub-workflow child, its own parent is unblocked as if this
+     * approval had been rejected.
+     *
+     * @param instanceId - The instance to cancel.
+     * @param raw - Who is cancelling and why.
+     * @param auditCtx - Optional compliance context recorded on the audit entry.
+     * @returns The cancelled instance.
+     * @throws ApprovalError if the instance is already `approved` or `rejected`.
+     */
     cancel(instanceId: string, raw: CancelOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Manually escalate the instance's current (lowest pending) level to the
+     * next rung of its escalation ladder, adding whatever the rung's
+     * `escalateTo` resolves to as extra approvers on that level. This is the
+     * same path the scheduled tick uses for a deadline-driven escalation — call
+     * it directly to escalate on demand instead of waiting for the ladder timer.
+     *
+     * A no-op (returns the instance unchanged, does not throw) when: the
+     * instance is not `pending`; the ladder has no rung configured for the
+     * current step; or every resolved approver turns out to be the submitter
+     * (nobody new to add).
+     *
+     * @throws {@link ApprovalNotFoundError} if `instanceId` does not exist.
+     */
     escalate(instanceId: string, raw: EscalateOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /**
      * Change an instance's document data while it is still pending, and
@@ -822,6 +959,17 @@ declare class ApprovalEngine {
         submittedBy: string;
         decisions?: SimulatedDecision[];
     }): Promise<SimulationResult>;
+    /**
+     * Check whether a user could approve an instance right now, without acting.
+     *
+     * The read-only counterpart to calling {@link approve} and handling the
+     * rejection — useful for deciding whether to show an approve button at all.
+     * `eligible: false` never throws; the reason names why: the instance is not
+     * `pending`, the user submitted it, they hold no open level (or delegated
+     * theirs away), or they already voted on it.
+     *
+     * @returns `{ eligible: true }`, or `{ eligible: false, reason }`.
+     */
     canApprove(instanceId: string, userId: string): Promise<CanApproveResult>;
     /** Emergency bypass — completes the instance as 'approved', skipping remaining levels. Requires template.allowOverride = true. */
     override(instanceId: string, raw: OverrideOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
@@ -848,13 +996,34 @@ declare class ApprovalEngine {
      * @returns What moved, what did not, and why. With `dryRun` nothing is written.
      */
     transferApprovals(raw: TransferApprovalsOptions, auditCtx?: AuditContext): Promise<TransferResult>;
+    /** Approve multiple instances in one call. Never throws — failures collected in result.failed. */
     bulkApprove(instanceIds: string[], raw: ApproveOptions, auditCtx?: AuditContext): Promise<BulkResult>;
     /** Reject multiple instances in one call. Never throws — failures collected in result.failed. */
     bulkReject(instanceIds: string[], raw: RejectOptions, auditCtx?: AuditContext): Promise<BulkResult>;
+    /**
+     * Fetch a single instance by id.
+     *
+     * @throws {@link ApprovalNotFoundError} if no instance exists with that id.
+     */
     getInstance(instanceId: string): Promise<ApprovalInstance>;
+    /** Page through every instance with an open level assigned to one approver. */
     getPendingFor(approverId: string, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
+    /** Page through instances matching an arbitrary filter (status, document type, date range, ...). */
     queryInstances(filter: InstanceFilter, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
+    /**
+     * Cursor-paginated variant of {@link queryInstances}, for stable paging
+     * through large or actively-changing result sets that offset pagination
+     * would skip or duplicate rows in.
+     *
+     * @throws {@link ApprovalError} (`NOT_SUPPORTED`) if the configured storage
+     * adapter does not implement `getInstancesByCursor`.
+     */
     queryInstancesByCursor(filter: InstanceFilter, opts: CursorPaginationOpts): Promise<CursorPaginatedResult<ApprovalInstance>>;
+    /**
+     * The full audit trail for an instance, in the order it was recorded.
+     *
+     * @throws {@link ApprovalNotFoundError} if no instance exists with that id.
+     */
     getHistory(instanceId: string): Promise<AuditEntry[]>;
     /**
      * The levels currently collecting decisions, ascending.
@@ -867,6 +1036,16 @@ declare class ApprovalEngine {
      * Empty once the instance is terminal.
      */
     getOpenLevels(instanceId: string): Promise<number[]>;
+    /**
+     * Everyone who currently owes a decision on an instance.
+     *
+     * A union across every open branch, so a parallel group with more than one
+     * level collecting decisions at once still names every approver, not just
+     * the one at {@link ApprovalInstance.currentLevel}. Empty once the instance
+     * is no longer `pending`.
+     *
+     * @throws {@link ApprovalNotFoundError} if no instance exists with that id.
+     */
     getCurrentApprovers(instanceId: string): Promise<string[]>;
     /** Check adapter connectivity and escalation scheduler health. */
     healthCheck(): Promise<HealthResult>;
@@ -956,6 +1135,15 @@ declare class ApprovalEngine {
         limit?: number;
         dryRun?: boolean;
     }): Promise<PurgeResult>;
+    /**
+     * Aggregate reporting numbers for a tenant: counts by status, approval
+     * rate, cycle-time stats, and a per-template breakdown.
+     *
+     * `filter.status` is ignored — the breakdown covers every status by
+     * design, so scoping it to one would make the counts misleading.
+     *
+     * @param filter - Optional scoping by document type, submitter, or date range.
+     */
     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>;
@@ -1206,7 +1394,6 @@ declare class ApprovalEngine {
      * 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.
      *