hierarchical-approval 4.0.6 → 4.0.7

package/CHANGELOG.md

@@ -5,6 +5,18 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [4.0.7] - 2026-09-28
+
+### Fixed
+
+- `RbacAuthorizationPolicy`'s roleProvider-failure denial message now names
+  the offending actor id, instead of a message that gave no clue which actor
+  triggered the fail-closed denial.
+- `ImportResult` and `PreviewResult`'s array fields are now typed as
+  `readonly T[]`, not just `readonly` properties holding a mutable array —
+  callers could previously still `push`/`splice` the returned arrays in
+  place even though the property itself couldn't be reassigned.
+
 ## [4.0.6] - 2026-09-26
 
 ### Fixed

package/dist/{ApprovalEngine-BnMpoQB2.d.cts → ApprovalEngine-D5ZplHsw.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-_PjAgjFA.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-MWXPSsA6.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BO6kmkyC.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-DYFj85oL.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-Du-TGRH_.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-rBeUKnBa.cjs';
 import { z } from 'zod';
 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-oYhWMKMn.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-DR-WIAK6.cjs';
-import { I as IMetricsAdapter } from './IMetricsAdapter-WROxYSXd.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-RGAqQ31Q.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-Bv7jIph1.cjs';
+import { I as IMetricsAdapter } from './IMetricsAdapter-DN9rYsoq.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-CLMdBA-5.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BwYBOQM3.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-D0Phw1c_.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -302,7 +302,7 @@ interface CanApproveResult {
     eligible: boolean;
     reason?: 'not_an_approver' | 'already_acted' | 'self_approval' | 'wrong_status' | 'delegated_away';
 }
-/** One entry in a {@link ApprovalEngine.preview} result, resolved against the given data without persisting anything. */
+/** One entry in a {@link ApprovalEngine.previewApprovalChain} result, resolved against the given data without persisting anything. */
 interface PreviewChainLevel {
     level: number;
     name: string;
@@ -310,10 +310,12 @@ interface PreviewChainLevel {
     resolvedApprovers: string[];
     mode: ApprovalMode;
 }
+/** Return value of {@link ApprovalEngine.previewApprovalChain}. */
 interface PreviewResult {
-    levels: PreviewChainLevel[];
+    /** The resolved chain, in level order. */
+    readonly levels: readonly PreviewChainLevel[];
     /** Indices (0-based) of conditions that fired for this data. */
-    conditionsApplied: number[];
+    readonly conditionsApplied: readonly number[];
 }
 /** Where one level in an explained chain came from. */
 interface ExplainedLevel {
@@ -468,14 +470,14 @@ interface TemplateBundle {
 }
 /** Outcome of {@link ApprovalEngine.importTemplates}. */
 interface ImportResult {
-    created: string[];
-    updated: string[];
-    skipped: string[];
-    errors: Array<{
+    readonly created: readonly string[];
+    readonly updated: readonly string[];
+    readonly skipped: readonly string[];
+    readonly errors: readonly Readonly<{
         name: string;
         message: string;
-    }>;
-    dryRun: boolean;
+    }>[];
+    readonly dryRun: boolean;
 }
 /** Outcome of a {@link ApprovalEngine.purgeInstances} sweep. */
 interface PurgeResult {
@@ -577,6 +579,7 @@ interface RetryPolicy {
 }
 /** Derives the idempotency key used to dedupe a {@link ApprovalEngine.submit} call from its tenant and document identity. */
 type IdempotencyKeyFn = (tenantId: string, documentType: string, documentId: string, templateName: string, data: Record<string, unknown>) => string;
+/** Constructor options for {@link ApprovalEngine}. Only `adapter` is required. */
 interface ApprovalEngineOptions {
     adapter: IStorageAdapter;
     tenantId?: string;
@@ -631,6 +634,11 @@ interface ApprovalEngineOptions {
     /** Middleware chain: before/after/onError hooks for every operation. */
     middleware?: IOperationMiddleware[];
 }
+/**
+ * Runs multi-level approval workflows against a pluggable {@link IStorageAdapter}:
+ * submitting instances against a template, resolving and notifying approvers,
+ * recording decisions, and driving escalation, expiry and sub-workflows.
+ */
 declare class ApprovalEngine {
     private readonly opts;
     private readonly bus;

package/dist/{ApprovalEngine-BqKSm1gG.d.ts → ApprovalEngine-sUWBHas4.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-DN78GD-1.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-MWXPSsA6.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-DKLEDgAk.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-Bje_7c62.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-Du-TGRH_.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-D_b-H3bB.js';
 import { z } from 'zod';
 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-CUI6VG6r.js';
-import { I as IAuditAdapter } from './IAuditAdapter-SNpV2hdt.js';
-import { I as IMetricsAdapter } from './IMetricsAdapter-WROxYSXd.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-BuRYpQdL.js';
+import { I as IAuditAdapter } from './IAuditAdapter-Bg6e0_ME.js';
+import { I as IMetricsAdapter } from './IMetricsAdapter-DN9rYsoq.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-CLMdBA-5.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BMl0xS-j.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-abLdaLzR.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -302,7 +302,7 @@ interface CanApproveResult {
     eligible: boolean;
     reason?: 'not_an_approver' | 'already_acted' | 'self_approval' | 'wrong_status' | 'delegated_away';
 }
-/** One entry in a {@link ApprovalEngine.preview} result, resolved against the given data without persisting anything. */
+/** One entry in a {@link ApprovalEngine.previewApprovalChain} result, resolved against the given data without persisting anything. */
 interface PreviewChainLevel {
     level: number;
     name: string;
@@ -310,10 +310,12 @@ interface PreviewChainLevel {
     resolvedApprovers: string[];
     mode: ApprovalMode;
 }
+/** Return value of {@link ApprovalEngine.previewApprovalChain}. */
 interface PreviewResult {
-    levels: PreviewChainLevel[];
+    /** The resolved chain, in level order. */
+    readonly levels: readonly PreviewChainLevel[];
     /** Indices (0-based) of conditions that fired for this data. */
-    conditionsApplied: number[];
+    readonly conditionsApplied: readonly number[];
 }
 /** Where one level in an explained chain came from. */
 interface ExplainedLevel {
@@ -468,14 +470,14 @@ interface TemplateBundle {
 }
 /** Outcome of {@link ApprovalEngine.importTemplates}. */
 interface ImportResult {
-    created: string[];
-    updated: string[];
-    skipped: string[];
-    errors: Array<{
+    readonly created: readonly string[];
+    readonly updated: readonly string[];
+    readonly skipped: readonly string[];
+    readonly errors: readonly Readonly<{
         name: string;
         message: string;
-    }>;
-    dryRun: boolean;
+    }>[];
+    readonly dryRun: boolean;
 }
 /** Outcome of a {@link ApprovalEngine.purgeInstances} sweep. */
 interface PurgeResult {
@@ -577,6 +579,7 @@ interface RetryPolicy {
 }
 /** Derives the idempotency key used to dedupe a {@link ApprovalEngine.submit} call from its tenant and document identity. */
 type IdempotencyKeyFn = (tenantId: string, documentType: string, documentId: string, templateName: string, data: Record<string, unknown>) => string;
+/** Constructor options for {@link ApprovalEngine}. Only `adapter` is required. */
 interface ApprovalEngineOptions {
     adapter: IStorageAdapter;
     tenantId?: string;
@@ -631,6 +634,11 @@ interface ApprovalEngineOptions {
     /** Middleware chain: before/after/onError hooks for every operation. */
     middleware?: IOperationMiddleware[];
 }
+/**
+ * Runs multi-level approval workflows against a pluggable {@link IStorageAdapter}:
+ * submitting instances against a template, resolving and notifying approvers,
+ * recording decisions, and driving escalation, expiry and sub-workflows.
+ */
 declare class ApprovalEngine {
     private readonly opts;
     private readonly bus;

package/dist/{IAuditAdapter-SNpV2hdt.d.ts → IAuditAdapter-Bg6e0_ME.d.ts}

@@ -1,4 +1,4 @@
-import { b as AuditEntry, a as ApprovalInstance } from './instance-MWXPSsA6.js';
+import { b as AuditEntry, a as ApprovalInstance } from './instance-Du-TGRH_.js';
 
 /** Secondary write sink for audit entries, alongside the primary storage adapter. */
 interface IAuditAdapter {

package/dist/{IAuditAdapter-DR-WIAK6.d.cts → IAuditAdapter-Bv7jIph1.d.cts}

@@ -1,4 +1,4 @@
-import { b as AuditEntry, a as ApprovalInstance } from './instance-MWXPSsA6.cjs';
+import { b as AuditEntry, a as ApprovalInstance } from './instance-Du-TGRH_.cjs';
 
 /** Secondary write sink for audit entries, alongside the primary storage adapter. */
 interface IAuditAdapter {

package/dist/{IAuthorizationPolicy-BwYBOQM3.d.cts → IAuthorizationPolicy-D0Phw1c_.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-MWXPSsA6.cjs';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-Du-TGRH_.cjs';
 
 interface AuthorizationContext {
     /** The engine method the actor is attempting to call. */

package/dist/{IAuthorizationPolicy-BMl0xS-j.d.ts → IAuthorizationPolicy-abLdaLzR.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-MWXPSsA6.js';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-Du-TGRH_.js';
 
 interface AuthorizationContext {
     /** The engine method the actor is attempting to call. */

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

@@ -1,5 +1,6 @@
 /** 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';
+/** Sink for engine metrics. Implementations are called synchronously and must not throw. */
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */
     increment(metric: MetricName, labels?: Record<string, string>): void;

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

@@ -1,5 +1,6 @@
 /** 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';
+/** Sink for engine metrics. Implementations are called synchronously and must not throw. */
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */
     increment(metric: MetricName, labels?: Record<string, string>): void;

package/dist/{INotificationAdapter-BO6kmkyC.d.cts → INotificationAdapter-D_b-H3bB.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-MWXPSsA6.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-Du-TGRH_.js';
 
 /** Common fields carried by every lifecycle event emitted for an approval instance. */
 interface ApprovalEvent {
@@ -159,6 +159,7 @@ interface CommentedEvent extends ApprovalEvent {
     /** Users named in the comment. */
     recipients: string[];
 }
+/** Maps each lifecycle event name to its payload type. Keys are what {@link ApprovalEngine.on} accepts; see {@link ApprovalEventName}. */
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -184,10 +185,12 @@ interface ApprovalEventMap {
     'approval:commented': CommentedEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
+/** An {@link AuditEntry} tagged with the instance it belongs to, for callers aggregating history across several instances. */
 interface HistoryEntry extends AuditEntry {
     instanceId: string;
 }
 
+/** Normalized envelope passed to {@link INotificationAdapter.notify} for every approval event. */
 interface NotificationEvent {
     /** The event that fired, e.g. `'submitted'`, `'approved'`, `'escalated'`. */
     type: ApprovalEventName;
@@ -208,6 +211,7 @@ interface NotificationEvent {
     /** Event-specific detail, shaped by {@link type}. */
     payload: ApprovalEventMap[ApprovalEventName];
 }
+/** Sink for approval-event notifications (email, Slack, webhooks, ...). */
 interface INotificationAdapter {
     /** Called after every emitted approval event. Must not throw — errors are logged and swallowed. */
     notify(event: NotificationEvent): Promise<void>;

package/dist/{INotificationAdapter-DKLEDgAk.d.ts → INotificationAdapter-rBeUKnBa.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-MWXPSsA6.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-Du-TGRH_.cjs';
 
 /** Common fields carried by every lifecycle event emitted for an approval instance. */
 interface ApprovalEvent {
@@ -159,6 +159,7 @@ interface CommentedEvent extends ApprovalEvent {
     /** Users named in the comment. */
     recipients: string[];
 }
+/** Maps each lifecycle event name to its payload type. Keys are what {@link ApprovalEngine.on} accepts; see {@link ApprovalEventName}. */
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -184,10 +185,12 @@ interface ApprovalEventMap {
     'approval:commented': CommentedEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
+/** An {@link AuditEntry} tagged with the instance it belongs to, for callers aggregating history across several instances. */
 interface HistoryEntry extends AuditEntry {
     instanceId: string;
 }
 
+/** Normalized envelope passed to {@link INotificationAdapter.notify} for every approval event. */
 interface NotificationEvent {
     /** The event that fired, e.g. `'submitted'`, `'approved'`, `'escalated'`. */
     type: ApprovalEventName;
@@ -208,6 +211,7 @@ interface NotificationEvent {
     /** Event-specific detail, shaped by {@link type}. */
     payload: ApprovalEventMap[ApprovalEventName];
 }
+/** Sink for approval-event notifications (email, Slack, webhooks, ...). */
 interface INotificationAdapter {
     /** Called after every emitted approval event. Must not throw — errors are logged and swallowed. */
     notify(event: NotificationEvent): Promise<void>;

package/dist/{IOperationMiddleware-CUI6VG6r.d.ts → IOperationMiddleware-BuRYpQdL.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance } from './instance-MWXPSsA6.js';
+import { a as ApprovalInstance } from './instance-Du-TGRH_.js';
 
 /** Base class for all errors thrown by this library; carries a stable machine-readable `code`. */
 declare class ApprovalError extends Error {

package/dist/{IOperationMiddleware-oYhWMKMn.d.cts → IOperationMiddleware-RGAqQ31Q.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance } from './instance-MWXPSsA6.cjs';
+import { a as ApprovalInstance } from './instance-Du-TGRH_.cjs';
 
 /** Base class for all errors thrown by this library; carries a stable machine-readable `code`. */
 declare class ApprovalError extends Error {

package/dist/{IStorageAdapter-DN78GD-1.d.ts → IStorageAdapter-Bje_7c62.d.ts}

@@ -1,4 +1,4 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-MWXPSsA6.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-Du-TGRH_.js';
 
 /** Offset-based pagination request. */
 interface PaginationOpts {
@@ -34,6 +34,7 @@ interface CursorPaginatedResult<T> {
     /** Whether another page exists in the requested direction. */
     hasMore: boolean;
 }
+/** Query filter for listing/counting instances; every set field narrows the match. */
 interface InstanceFilter {
     /** Match only instances in this status. */
     status?: ApprovalStatus;

package/dist/{IStorageAdapter-_PjAgjFA.d.cts → IStorageAdapter-DYFj85oL.d.cts}

@@ -1,4 +1,4 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-MWXPSsA6.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-Du-TGRH_.cjs';
 
 /** Offset-based pagination request. */
 interface PaginationOpts {
@@ -34,6 +34,7 @@ interface CursorPaginatedResult<T> {
     /** Whether another page exists in the requested direction. */
     hasMore: boolean;
 }
+/** Query filter for listing/counting instances; every set field narrows the match. */
 interface InstanceFilter {
     /** Match only instances in this status. */
     status?: ApprovalStatus;

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-_PjAgjFA.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-MWXPSsA6.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-DYFj85oL.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-Du-TGRH_.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-DN78GD-1.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-MWXPSsA6.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-Bje_7c62.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-Du-TGRH_.js';
 
 /**
  * In-process {@link IStorageAdapter} backed by two `Map`s, keyed by