hierarchical-approval 4.0.6 → 4.1.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [4.1.0] - 2026-10-12
+
+### Changed
+
+- `SubmitOptions` now describes what `submit` accepts: `data` and `metadata` are
+  optional (they default to `{}`) and `expiresAt` may be a `Date`, ISO string or
+  epoch milliseconds.
+
+## [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-CJQAHzxb.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;
@@ -113,7 +113,14 @@ declare const UpdateDataOptionsSchema: z.ZodObject<{
     reason: z.ZodOptional<z.ZodString>;
     recomputeChain: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
-type SubmitOptions = z.infer<typeof SubmitOptionsSchema>;
+/**
+ * Input shape: `data` and `metadata` are optional because the schema defaults
+ * them. `expiresAt` is re-declared since zod types a coerced date's input as
+ * `unknown`, which would let any value through at compile time.
+ */
+type SubmitOptions = Omit<z.input<typeof SubmitOptionsSchema>, 'expiresAt'> & {
+    expiresAt?: Date | string | number;
+};
 type ApproveOptions = z.infer<typeof ApproveOptionsSchema>;
 type RejectOptions = z.infer<typeof RejectOptionsSchema>;
 type DelegateOptions = z.infer<typeof DelegateOptionsSchema>;
@@ -302,7 +309,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 +317,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 +477,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 +586,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 +641,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;
@@ -715,6 +730,17 @@ declare class ApprovalEngine {
      * @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.
+     *
+     * @example
+     * ```ts
+     * const instance = await engine.submit({
+     *   templateName: 'purchase-order',
+     *   documentId: 'PO-1042',
+     *   documentType: 'purchase_order',
+     *   submittedBy: 'alice',
+     *   data: { amount: 12_500 },
+     * });
+     * ```
      */
     submit(raw: SubmitOptions, auditCtx?: AuditContext, 
     /**
@@ -744,6 +770,14 @@ declare class ApprovalEngine {
      *   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.
+     *
+     * @example
+     * ```ts
+     * const updated = await engine.approve(instance.id, {
+     *   approverId: 'bob',
+     *   comment: 'Within budget',
+     * });
+     * ```
      */
     approve(instanceId: string, raw: ApproveOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /**
@@ -766,6 +800,15 @@ declare class ApprovalEngine {
      * @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.
+     *
+     * @example
+     * ```ts
+     * const updated = await engine.reject(instance.id, {
+     *   approverId: 'bob',
+     *   reason: 'Over budget',
+     *   returnTo: 'previous',
+     * });
+     * ```
      */
     reject(instanceId: string, raw: RejectOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /**
@@ -784,6 +827,16 @@ declare class ApprovalEngine {
      *   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.
+     *
+     * @example
+     * ```ts
+     * await engine.delegate(instance.id, {
+     *   fromApprover: 'bob',
+     *   toApprover: 'carol',
+     *   reason: 'On leave',
+     *   until: new Date('2026-11-01'),
+     * });
+     * ```
      */
     delegate(instanceId: string, raw: DelegateOptions, auditCtx?: AuditContext): Promise<void>;
     /**
@@ -995,11 +1048,16 @@ declare class ApprovalEngine {
      * theirs away), or they already voted on it.
      *
      * @returns `{ eligible: true }`, or `{ eligible: false, reason }`.
+     *
+     * @example
+     * ```ts
+     * const check = await engine.canApprove(instance.id, 'bob');
+     * if (!check.eligible) console.log(check.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>;
-    /** Approve multiple instances in one call. Never throws — failures collected in result.failed. */
     /**
      * Move every pending approval assigned to one person over to another.
      *
@@ -1022,7 +1080,15 @@ 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. */
+    /**
+     * Approve multiple instances in one call. Never throws — failures collected in result.failed.
+     *
+     * @example
+     * ```ts
+     * const { succeeded, failed } = await engine.bulkApprove(ids, { approverId: 'bob' });
+     * for (const { instanceId, error } of failed) console.warn(instanceId, error.code);
+     * ```
+     */
     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>;
@@ -1032,7 +1098,14 @@ declare class ApprovalEngine {
      * @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. */
+    /**
+     * Page through every instance with an open level assigned to one approver.
+     *
+     * @example
+     * ```ts
+     * const page = await engine.getPendingFor('bob', { limit: 20, offset: 0 });
+     * ```
+     */
     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>>;

package/dist/{ApprovalEngine-BqKSm1gG.d.ts → ApprovalEngine-DevN2HQ6.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;
@@ -113,7 +113,14 @@ declare const UpdateDataOptionsSchema: z.ZodObject<{
     reason: z.ZodOptional<z.ZodString>;
     recomputeChain: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
-type SubmitOptions = z.infer<typeof SubmitOptionsSchema>;
+/**
+ * Input shape: `data` and `metadata` are optional because the schema defaults
+ * them. `expiresAt` is re-declared since zod types a coerced date's input as
+ * `unknown`, which would let any value through at compile time.
+ */
+type SubmitOptions = Omit<z.input<typeof SubmitOptionsSchema>, 'expiresAt'> & {
+    expiresAt?: Date | string | number;
+};
 type ApproveOptions = z.infer<typeof ApproveOptionsSchema>;
 type RejectOptions = z.infer<typeof RejectOptionsSchema>;
 type DelegateOptions = z.infer<typeof DelegateOptionsSchema>;
@@ -302,7 +309,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 +317,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 +477,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 +586,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 +641,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;
@@ -715,6 +730,17 @@ declare class ApprovalEngine {
      * @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.
+     *
+     * @example
+     * ```ts
+     * const instance = await engine.submit({
+     *   templateName: 'purchase-order',
+     *   documentId: 'PO-1042',
+     *   documentType: 'purchase_order',
+     *   submittedBy: 'alice',
+     *   data: { amount: 12_500 },
+     * });
+     * ```
      */
     submit(raw: SubmitOptions, auditCtx?: AuditContext, 
     /**
@@ -744,6 +770,14 @@ declare class ApprovalEngine {
      *   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.
+     *
+     * @example
+     * ```ts
+     * const updated = await engine.approve(instance.id, {
+     *   approverId: 'bob',
+     *   comment: 'Within budget',
+     * });
+     * ```
      */
     approve(instanceId: string, raw: ApproveOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /**
@@ -766,6 +800,15 @@ declare class ApprovalEngine {
      * @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.
+     *
+     * @example
+     * ```ts
+     * const updated = await engine.reject(instance.id, {
+     *   approverId: 'bob',
+     *   reason: 'Over budget',
+     *   returnTo: 'previous',
+     * });
+     * ```
      */
     reject(instanceId: string, raw: RejectOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /**
@@ -784,6 +827,16 @@ declare class ApprovalEngine {
      *   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.
+     *
+     * @example
+     * ```ts
+     * await engine.delegate(instance.id, {
+     *   fromApprover: 'bob',
+     *   toApprover: 'carol',
+     *   reason: 'On leave',
+     *   until: new Date('2026-11-01'),
+     * });
+     * ```
      */
     delegate(instanceId: string, raw: DelegateOptions, auditCtx?: AuditContext): Promise<void>;
     /**
@@ -995,11 +1048,16 @@ declare class ApprovalEngine {
      * theirs away), or they already voted on it.
      *
      * @returns `{ eligible: true }`, or `{ eligible: false, reason }`.
+     *
+     * @example
+     * ```ts
+     * const check = await engine.canApprove(instance.id, 'bob');
+     * if (!check.eligible) console.log(check.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>;
-    /** Approve multiple instances in one call. Never throws — failures collected in result.failed. */
     /**
      * Move every pending approval assigned to one person over to another.
      *
@@ -1022,7 +1080,15 @@ 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. */
+    /**
+     * Approve multiple instances in one call. Never throws — failures collected in result.failed.
+     *
+     * @example
+     * ```ts
+     * const { succeeded, failed } = await engine.bulkApprove(ids, { approverId: 'bob' });
+     * for (const { instanceId, error } of failed) console.warn(instanceId, error.code);
+     * ```
+     */
     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>;
@@ -1032,7 +1098,14 @@ declare class ApprovalEngine {
      * @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. */
+    /**
+     * Page through every instance with an open level assigned to one approver.
+     *
+     * @example
+     * ```ts
+     * const page = await engine.getPendingFor('bob', { limit: 20, offset: 0 });
+     * ```
+     */
     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>>;

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