hierarchical-approval 4.0.2 → 4.0.3

package/CHANGELOG.md

@@ -1,8 +1,8 @@
-## 4.0.2 - 2026-09-20
+## 4.0.3 - 2026-09-22
 
-- 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
+- fix(engine): name the level in assertApproverOnLevel's error
+- fix(utils): name the offending start date in businessHoursCalendar's error
+- fix(engine): name the offending instance id in assertStatus's error
 
 # Changelog
 
@@ -13,6 +13,19 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- `assertStatus`'s `INVALID_STATUS` error now names the instance that failed
+  the check, instead of a message that gave no clue which instance it was.
+- `businessHoursCalendar`'s "no working day found" error now names the start
+  date that triggered it, instead of a message that gave no clue which call
+  misconfigured the calendar.
+- `assertApproverOnLevel`'s forbidden-approver error now names the level,
+  matching every sibling guard in `StateMachine.ts`, instead of a bare level
+  number with no human-readable name.
+
+## [4.0.2] - 2026-09-20
+
+### 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
@@ -20,6 +33,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   attached.
 - `DigestNotificationAdapter`'s `intervalMs` validation error now names the
   offending value, instead of a message that gave no clue which value failed.
+- The default-sleep regression test for `WebhookNotificationAdapter` no longer
+  flakes under CI's timer coalescing, which could report elapsed time a
+  millisecond or two short of the asserted floor.
 
 ## [4.0.1] - 2026-09-14
 

package/dist/{ApprovalEngine-Dqe-rC6K.d.ts → ApprovalEngine-BtgQDr_8.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-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 { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-CVvNsnnD.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-Dd1jQizG.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BcUskJ6z.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-CX7lo4lp.js';
-import { I as IAuditAdapter } from './IAuditAdapter-DkbyFFjb.js';
-import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.js';
+import { L as Logger } from './Logger-hqFbBCtB.js';
+import { C as Clock } from './Clock-D8Qp39q_.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-C7ciNnJp.js';
+import { I as IAuditAdapter } from './IAuditAdapter-C-04ar9A.js';
+import { I as IMetricsAdapter } from './IMetricsAdapter-WROxYSXd.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-eo6glbpE.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-wIE1mpTy.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -201,11 +201,15 @@ interface BusinessHoursCalendarOptions extends WeekendCalendarOptions {
  */
 declare function businessHoursCalendar(options?: BusinessHoursCalendarOptions): Required<Pick<BusinessCalendar, 'addBusinessDays' | 'addBusinessHours'>>;
 
+/** Entity kind an id is generated for: instance, template, attachment, or comment. */
 type IdGeneratorPrefix = 'inst' | 'tpl' | 'att' | 'cmt';
+/** Produces a unique id for the given entity kind. */
 type IdGeneratorFn = (prefix: IdGeneratorPrefix) => string;
+/** {@link IdGeneratorFn} used when no custom generator is configured. */
 declare const defaultIdGenerator: IdGeneratorFn;
 
 interface OrgProvider {
+    /** Required: resolve users holding a named role. */
     getUsersByRole(role: string, tenantId?: string): Promise<string[]> | string[];
     /** Optional: resolve users by department name. */
     getUsersByDepartment?(dept: string, tenantId?: string): Promise<string[]> | string[];

package/dist/{ApprovalEngine-XgGBQLC_.d.cts → ApprovalEngine-Djdw-JzA.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-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 { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-D7cy20uD.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-Dd1jQizG.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-CBsJDk-Y.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-BBLk8MIz.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-Dt8qjkQL.cjs';
-import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.cjs';
+import { L as Logger } from './Logger-hqFbBCtB.cjs';
+import { C as Clock } from './Clock-D8Qp39q_.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-D3Yelw9R.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-TT2Xhtu6.cjs';
+import { I as IMetricsAdapter } from './IMetricsAdapter-WROxYSXd.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-YJ_08Mof.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-D6tTT3gv.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -201,11 +201,15 @@ interface BusinessHoursCalendarOptions extends WeekendCalendarOptions {
  */
 declare function businessHoursCalendar(options?: BusinessHoursCalendarOptions): Required<Pick<BusinessCalendar, 'addBusinessDays' | 'addBusinessHours'>>;
 
+/** Entity kind an id is generated for: instance, template, attachment, or comment. */
 type IdGeneratorPrefix = 'inst' | 'tpl' | 'att' | 'cmt';
+/** Produces a unique id for the given entity kind. */
 type IdGeneratorFn = (prefix: IdGeneratorPrefix) => string;
+/** {@link IdGeneratorFn} used when no custom generator is configured. */
 declare const defaultIdGenerator: IdGeneratorFn;
 
 interface OrgProvider {
+    /** Required: resolve users holding a named role. */
     getUsersByRole(role: string, tenantId?: string): Promise<string[]> | string[];
     /** Optional: resolve users by department name. */
     getUsersByDepartment?(dept: string, tenantId?: string): Promise<string[]> | string[];

package/dist/Clock-D8Qp39q_.d.cts

@@ -0,0 +1,8 @@
+/** Time source injected into engine and plugin components, so tests can control the clock. */
+interface Clock {
+    now(): Date;
+}
+/** {@link Clock} backed by the real wall clock — the default when no clock is configured. */
+declare const systemClock: Clock;
+
+export { type Clock as C, systemClock as s };

package/dist/Clock-D8Qp39q_.d.ts

@@ -0,0 +1,8 @@
+/** Time source injected into engine and plugin components, so tests can control the clock. */
+interface Clock {
+    now(): Date;
+}
+/** {@link Clock} backed by the real wall clock — the default when no clock is configured. */
+declare const systemClock: Clock;
+
+export { type Clock as C, systemClock as s };

package/dist/{IAuditAdapter-DkbyFFjb.d.ts → IAuditAdapter-C-04ar9A.d.ts}

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

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

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

package/dist/{IAuthorizationPolicy-eo6glbpE.d.ts → IAuthorizationPolicy-D6tTT3gv.d.cts}

@@ -1,10 +1,15 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-uUQh5XW3.js';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-Dd1jQizG.cjs';
 
 interface AuthorizationContext {
+    /** The engine method the actor is attempting to call. */
     operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment';
+    /** Id of the user or system attempting the operation. */
     actorId: string;
+    /** The instance the operation targets, as it stood before the operation ran. */
     instance: Readonly<ApprovalInstance>;
+    /** The current level, for level-scoped operations (approve, reject, delegate, etc.); absent otherwise. */
     level?: Readonly<ApprovalLevelInstance>;
+    /** The caller's own options object for this operation, passed through unmodified. */
     opts: Record<string, unknown>;
 }
 interface IAuthorizationPolicy {

package/dist/{IAuthorizationPolicy-YJ_08Mof.d.cts → IAuthorizationPolicy-wIE1mpTy.d.ts}

@@ -1,10 +1,15 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-uUQh5XW3.cjs';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-Dd1jQizG.js';
 
 interface AuthorizationContext {
+    /** The engine method the actor is attempting to call. */
     operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment';
+    /** Id of the user or system attempting the operation. */
     actorId: string;
+    /** The instance the operation targets, as it stood before the operation ran. */
     instance: Readonly<ApprovalInstance>;
+    /** The current level, for level-scoped operations (approve, reject, delegate, etc.); absent otherwise. */
     level?: Readonly<ApprovalLevelInstance>;
+    /** The caller's own options object for this operation, passed through unmodified. */
     opts: Record<string, unknown>;
 }
 interface IAuthorizationPolicy {

package/dist/{IMetricsAdapter-DWq8IFaf.d.cts → IMetricsAdapter-WROxYSXd.d.cts}

@@ -1,3 +1,4 @@
+/** Closed set of metric names an {@link IMetricsAdapter} may be called with, namespaced `approval.<verb>`. */
 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.reminded' | 'approval.info_requested' | 'approval.info_provided' | 'approval.attachment_added' | 'approval.attachment_removed' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */

package/dist/{IMetricsAdapter-DWq8IFaf.d.ts → IMetricsAdapter-WROxYSXd.d.ts}

@@ -1,3 +1,4 @@
+/** Closed set of metric names an {@link IMetricsAdapter} may be called with, namespaced `approval.<verb>`. */
 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.reminded' | 'approval.info_requested' | 'approval.info_provided' | 'approval.attachment_added' | 'approval.attachment_removed' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-uUQh5XW3.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-Dd1jQizG.js';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -160,15 +160,23 @@ interface HistoryEntry extends AuditEntry {
 }
 
 interface NotificationEvent {
+    /** The event that fired, e.g. `'submitted'`, `'approved'`, `'escalated'`. */
     type: ApprovalEventName;
+    /** Id of the approval instance the event fired for. */
     instanceId: string;
+    /** Id of the document under approval, as submitted by the caller. */
     documentId: string;
+    /** Caller-defined document category (e.g. `'purchase_order'`). */
     documentType: string;
+    /** When the underlying transition happened. */
     timestamp: Date;
     /** Current-level approver IDs; empty for non-level events (cancelled, expired, etc.). */
     recipients: string[];
+    /** Name of the template governing the instance. */
     templateName: string;
+    /** Tenant the instance belongs to, for multi-tenant deployments. */
     tenantId: string;
+    /** Event-specific detail, shaped by {@link type}. */
     payload: ApprovalEventMap[ApprovalEventName];
 }
 interface INotificationAdapter {

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-uUQh5XW3.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-Dd1jQizG.cjs';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -160,15 +160,23 @@ interface HistoryEntry extends AuditEntry {
 }
 
 interface NotificationEvent {
+    /** The event that fired, e.g. `'submitted'`, `'approved'`, `'escalated'`. */
     type: ApprovalEventName;
+    /** Id of the approval instance the event fired for. */
     instanceId: string;
+    /** Id of the document under approval, as submitted by the caller. */
     documentId: string;
+    /** Caller-defined document category (e.g. `'purchase_order'`). */
     documentType: string;
+    /** When the underlying transition happened. */
     timestamp: Date;
     /** Current-level approver IDs; empty for non-level events (cancelled, expired, etc.). */
     recipients: string[];
+    /** Name of the template governing the instance. */
     templateName: string;
+    /** Tenant the instance belongs to, for multi-tenant deployments. */
     tenantId: string;
+    /** Event-specific detail, shaped by {@link type}. */
     payload: ApprovalEventMap[ApprovalEventName];
 }
 interface INotificationAdapter {

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance } from './instance-uUQh5XW3.js';
+import { a as ApprovalInstance } from './instance-Dd1jQizG.js';
 
 declare class ApprovalError extends Error {
     readonly code: string;
@@ -27,8 +27,9 @@ declare class ApprovalTemplateNotFoundError extends ApprovalError {
     constructor(name: string);
 }
 
+type EngineOperation = 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment' | 'addComment' | 'resubmit' | 'override';
 interface OperationContext<T = unknown> {
-    operation: string;
+    operation: EngineOperation;
     instanceId?: string;
     actorId?: string;
     tenantId: string;

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance } from './instance-uUQh5XW3.cjs';
+import { a as ApprovalInstance } from './instance-Dd1jQizG.cjs';
 
 declare class ApprovalError extends Error {
     readonly code: string;
@@ -27,8 +27,9 @@ declare class ApprovalTemplateNotFoundError extends ApprovalError {
     constructor(name: string);
 }
 
+type EngineOperation = 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment' | 'addComment' | 'resubmit' | 'override';
 interface OperationContext<T = unknown> {
-    operation: string;
+    operation: EngineOperation;
     instanceId?: string;
     actorId?: string;
     tenantId: string;

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

@@ -1,4 +1,4 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-uUQh5XW3.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-Dd1jQizG.js';
 
 interface PaginationOpts {
     limit: number;
@@ -42,14 +42,19 @@ interface IStorageAdapter {
     saveTemplate(template: ApprovalTemplate): Promise<void>;
     getTemplate(tenantId: string, name: string): Promise<ApprovalTemplate | null>;
     listTemplates(tenantId: string): Promise<ApprovalTemplate[]>;
+    /** Create a new instance. Callers own uniqueness of `instance.id`. */
     saveInstance(instance: ApprovalInstance): Promise<void>;
     /** Conditional update — throws ApprovalConflictError if stored version !== expectedVersion. */
     updateInstance(instance: ApprovalInstance, expectedVersion: number): Promise<void>;
+    /** Fetch one instance by id, scoped to a tenant. Returns null if absent. */
     getInstance(tenantId: string, id: string): Promise<ApprovalInstance | null>;
+    /** Instances where `approverId` is a current approver on any pending level. */
     getInstancesByApprover(tenantId: string, approverId: string, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
+    /** Instances matching an {@link InstanceFilter}. Ordering is adapter-specific. */
     getInstancesByFilter(tenantId: string, filter: InstanceFilter, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
     /** Optional cursor-based pagination — more efficient than offset at scale. */
     getInstancesByCursor?(tenantId: string, filter: InstanceFilter, opts: CursorPaginationOpts): Promise<CursorPaginatedResult<ApprovalInstance>>;
+    /** Pending instances overdue as of `asOf` on any open level, not just the current one. */
     getOverdueInstances(tenantId: string, asOf: Date, filter?: InstanceFilter): Promise<ApprovalInstance[]>;
     /**
      * Count instances matching a filter, without fetching any of them.
@@ -85,6 +90,7 @@ interface IStorageAdapter {
      * @since 2.3.0
      */
     deleteInstance?(tenantId: string, id: string): Promise<boolean>;
+    /** Look up an instance by `idempotencyKey`, unique within a tenant, not globally. */
     getIdempotentInstance(tenantId: string, idempotencyKey: string): Promise<ApprovalInstance | null>;
     appendAuditEntry(tenantId: string, instanceId: string, entry: AuditEntry): Promise<void>;
 }

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

@@ -1,4 +1,4 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-uUQh5XW3.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-Dd1jQizG.cjs';
 
 interface PaginationOpts {
     limit: number;
@@ -42,14 +42,19 @@ interface IStorageAdapter {
     saveTemplate(template: ApprovalTemplate): Promise<void>;
     getTemplate(tenantId: string, name: string): Promise<ApprovalTemplate | null>;
     listTemplates(tenantId: string): Promise<ApprovalTemplate[]>;
+    /** Create a new instance. Callers own uniqueness of `instance.id`. */
     saveInstance(instance: ApprovalInstance): Promise<void>;
     /** Conditional update — throws ApprovalConflictError if stored version !== expectedVersion. */
     updateInstance(instance: ApprovalInstance, expectedVersion: number): Promise<void>;
+    /** Fetch one instance by id, scoped to a tenant. Returns null if absent. */
     getInstance(tenantId: string, id: string): Promise<ApprovalInstance | null>;
+    /** Instances where `approverId` is a current approver on any pending level. */
     getInstancesByApprover(tenantId: string, approverId: string, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
+    /** Instances matching an {@link InstanceFilter}. Ordering is adapter-specific. */
     getInstancesByFilter(tenantId: string, filter: InstanceFilter, opts?: PaginationOpts): Promise<PaginatedResult<ApprovalInstance>>;
     /** Optional cursor-based pagination — more efficient than offset at scale. */
     getInstancesByCursor?(tenantId: string, filter: InstanceFilter, opts: CursorPaginationOpts): Promise<CursorPaginatedResult<ApprovalInstance>>;
+    /** Pending instances overdue as of `asOf` on any open level, not just the current one. */
     getOverdueInstances(tenantId: string, asOf: Date, filter?: InstanceFilter): Promise<ApprovalInstance[]>;
     /**
      * Count instances matching a filter, without fetching any of them.
@@ -85,6 +90,7 @@ interface IStorageAdapter {
      * @since 2.3.0
      */
     deleteInstance?(tenantId: string, id: string): Promise<boolean>;
+    /** Look up an instance by `idempotencyKey`, unique within a tenant, not globally. */
     getIdempotentInstance(tenantId: string, idempotencyKey: string): Promise<ApprovalInstance | null>;
     appendAuditEntry(tenantId: string, instanceId: string, entry: AuditEntry): Promise<void>;
 }

package/dist/{Logger-BplhlU7l.d.cts → Logger-hqFbBCtB.d.cts}

@@ -1,10 +1,17 @@
+/** Structured logger injected into engine and plugin components. */
 interface Logger {
+    /** Routine, expected activity. */
     info(msg: string, context?: Record<string, unknown>): void;
+    /** Unexpected but recoverable condition. */
     warn(msg: string, context?: Record<string, unknown>): void;
+    /** A caught error that did not stop the calling operation. */
     error(msg: string, err?: unknown, context?: Record<string, unknown>): void;
+    /** A caught error severe enough that the calling operation could not continue. */
     fatal(msg: string, err?: unknown, context?: Record<string, unknown>): void;
+    /** Verbose, developer-facing detail. */
     debug(msg: string, context?: Record<string, unknown>): void;
 }
+/** {@link Logger} that discards every call — the default when no logger is configured. */
 declare const noopLogger: Logger;
 
 export { type Logger as L, noopLogger as n };

package/dist/{Logger-BplhlU7l.d.ts → Logger-hqFbBCtB.d.ts}

@@ -1,10 +1,17 @@
+/** Structured logger injected into engine and plugin components. */
 interface Logger {
+    /** Routine, expected activity. */
     info(msg: string, context?: Record<string, unknown>): void;
+    /** Unexpected but recoverable condition. */
     warn(msg: string, context?: Record<string, unknown>): void;
+    /** A caught error that did not stop the calling operation. */
     error(msg: string, err?: unknown, context?: Record<string, unknown>): void;
+    /** A caught error severe enough that the calling operation could not continue. */
     fatal(msg: string, err?: unknown, context?: Record<string, unknown>): void;
+    /** Verbose, developer-facing detail. */
     debug(msg: string, context?: Record<string, unknown>): void;
 }
+/** {@link Logger} that discards every call — the default when no logger is configured. */
 declare const noopLogger: Logger;
 
 export { type Logger as L, noopLogger as n };

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-Cjw5zDwQ.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-uUQh5XW3.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-D7cy20uD.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-Dd1jQizG.cjs';
 
 /**
  * In-process {@link IStorageAdapter} backed by two `Map`s, keyed by

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-CdXMggPK.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-uUQh5XW3.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-CVvNsnnD.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-Dd1jQizG.js';
 
 /**
  * In-process {@link IStorageAdapter} backed by two `Map`s, keyed by

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-Cjw5zDwQ.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-uUQh5XW3.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-D7cy20uD.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-Dd1jQizG.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-CdXMggPK.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-uUQh5XW3.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-CVvNsnnD.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-Dd1jQizG.js';
 
 interface PostgresAdapterOptions {
     connectionString?: string;

package/dist/index.cjs

@@ -556,6 +556,7 @@ var TemplateRegistry = class {
     delete resolved.removeLevels;
     return resolved;
   }
+  /** Register a new template. Throws if a template with this name already exists for the tenant. */
   async define(config) {
     const existing = await this.adapter.getTemplate(this.tenantId, config.name);
     if (existing) {
@@ -592,11 +593,13 @@ var TemplateRegistry = class {
     await this.adapter.saveTemplate(updated);
     return newId;
   }
+  /** Fetch a template by name. Throws if no template with this name exists for the tenant. */
   async get(name) {
     const template = await this.adapter.getTemplate(this.tenantId, name);
     if (!template) throw new ApprovalTemplateNotFoundError(name);
     return template;
   }
+  /** List every template registered for the tenant. */
   async list() {
     return this.adapter.listTemplates(this.tenantId);
   }
@@ -636,6 +639,32 @@ var LevelResolver = class {
     for (const [name, fn] of this.resolvers) target.register(name, fn);
     for (const [name, fn] of this.approverTypes) target.registerApproverType(name, fn);
   }
+  /**
+   * Resolve a level's `approvers` config down to a deduplicated list of user
+   * ids, applying out-of-office cover last so a substitute never sees a stale
+   * approver id.
+   *
+   * @param approvers - The level's approver configs (`user`, `role`,
+   *   `dynamic`, or a custom type registered via {@link registerApproverType}).
+   * @param submittedBy - Passed through to `dynamic` resolvers and custom
+   *   approver-type functions as routing context.
+   * @param data - The instance's document data, passed through the same way.
+   * @param orgProvider - Required to resolve `role` approvers; omit only when
+   *   the template uses no `role` approvers.
+   * @param outOfOffice - Optional cover lookup, consulted after every other
+   *   approver type has resolved.
+   * @param at - The moment out-of-office cover is resolved for. Defaults to
+   *   now.
+   * @param substitutions - Filled with `original -> stand-in` for each
+   *   approver replaced by out-of-office cover, so the caller can carry
+   *   anything keyed by the original id (such as a weighted level's vote
+   *   weight) across to the substitute.
+   * @returns The resolved, deduplicated approver ids (post-substitution).
+   * @throws {ApprovalValidationError} If no approvers resolve at all, a
+   *   `role` approver is configured without an `orgProvider`, a `dynamic`
+   *   approver names a resolver that was never registered, or a custom
+   *   approver type was never registered.
+   */
   async resolveApprovers(approvers, submittedBy, data, orgProvider, outOfOffice, at, substitutions) {
     const resolved = [];
     for (const approver of approvers) {
@@ -1047,7 +1076,7 @@ function evaluateConditions(conditions, data) {
 function assertStatus(instance, expected) {
   if (instance.status !== expected) {
     throw new ApprovalError(
-      `Expected instance status "${expected}" but got "${instance.status}".`,
+      `Instance "${instance.id}": expected status "${expected}" but got "${instance.status}".`,
       "INVALID_STATUS"
     );
   }
@@ -1055,7 +1084,7 @@ function assertStatus(instance, expected) {
 function assertApproverOnLevel(level, approverId) {
   if (!level.approverIds.includes(approverId)) {
     throw new ApprovalForbiddenError(
-      `User "${approverId}" is not an approver for level ${level.level}.`
+      `User "${approverId}" is not an approver for level ${level.level} ("${level.name}").`
     );
   }
 }
@@ -5170,7 +5199,7 @@ function businessHoursCalendar(options = {}) {
       return cursor;
     }
     throw new Error(
-      "businessHoursCalendar: no working day found within 10 years of the start date."
+      `businessHoursCalendar: no working day found within 10 years of ${from.toISOString()} \u2014 check weekendDays and holidays.`
     );
   };
   const base = weekendCalendar(options);