hierarchical-approval 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -7,6 +7,88 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [1.8.0] - 2026-09-04
+
+### Added — `transferApprovals()`
+
+- **Move every pending approval assigned to one person over to another.**
+  Someone leaves, changes team, or goes on long-term leave, and their queue has
+  to go somewhere. Doing it by hand meant finding every open instance first —
+  across parallel branches, where one person can hold several open levels on the
+  same document — and missing one left an approval that could never complete.
+
+  ```ts
+  await engine.transferApprovals({
+    fromApprover: 'alice',
+    toApprover: 'bob',
+    transferredBy: 'workflow-admin',
+    reason: 'Alice left the company',
+    documentType: 'purchase_order',   // optional
+    dryRun: true,                     // see what would move first
+  });
+  ```
+
+  Each move goes through `reassign()`, so every guard, audit entry, event and
+  authorization check that applies to a single reassignment applies here too.
+  The sweep is deliberately **not atomic**: it reports per-instance failures
+  rather than rolling back, because a partial transfer is the useful outcome —
+  what can move should move, and what cannot is named for a human to look at.
+
+  New exports: `TransferResult`, `TransferApprovalsOptions`.
+
+### Fixed — `delegate()` and `reassign()` could not reach an upper parallel branch
+
+- **Both resolved the level via `currentLevelInstance`**, which names only the
+  lowest-numbered open level. Inside a parallel group they therefore always
+  acted on the lowest branch: an approver could not hand off their own
+  upper-branch work, and an administrator reassigning a departing user silently
+  moved the wrong branch — or failed, because that person was not an approver on
+  the branch being targeted. Introduced with parallel groups in 1.0.0; sequential
+  templates were never affected.
+
+  Both now resolve against the approver actually being moved, and take an
+  optional `level` to disambiguate when one person holds more than one open
+  branch — matching what `approve()` and `reject()` already did.
+
+## [1.7.0] - 2026-09-04
+
+### Added — attachment references
+
+- **`addAttachment()` / `removeAttachment()` attach supporting evidence to an
+  approval** — a quote PDF, a signed contract, a screenshot of a system of
+  record. Approvers had nowhere to put the document their decision rested on, so
+  it lived in an email thread the audit trail never saw.
+
+  ```ts
+  await engine.addAttachment(id, {
+    actorId: 'buyer-1',
+    name: 'quote.pdf',
+    uri: 's3://procurement/quotes/q-1.pdf',
+    contentType: 'application/pdf',
+    sizeBytes: 48_120,
+  });
+  ```
+
+- **References only, never bytes.** Approval documents belong in the object
+  store or DMS the organisation already runs, which handles retention, virus
+  scanning and access control far better than an approval table could; copying
+  them here would make the audit database the largest and least governed copy of
+  them. Removing detaches the reference and never deletes from the underlying
+  store.
+
+- **The audit trail keeps what was removed** — name and URI are recorded on the
+  `attachment_removed` entry, so the record still shows an approver saw evidence
+  that is no longer listed. Dropping that would let the trail imply a decision
+  was made on less than it was.
+
+- Persisted across all four PostgreSQL sites (schema, `migrate()`,
+  insert, update, and read-back), with `addedAt` revived as a `Date`. An
+  instance with no attachments reads back as `undefined` rather than `[]`,
+  keeping the round-trip shape identical to `MemoryAdapter`.
+
+  New exports: `Attachment`, `AttachmentEvent`, `AddAttachmentOptions`,
+  `RemoveAttachmentOptions`. `ApprovalInstance` gains `attachments`.
+
 ## [1.6.0] - 2026-09-04
 
 ### Fixed — PostgresAdapter silently dropped most instance updates

package/README.md

@@ -399,6 +399,67 @@ engine.registerConditionOperator('between', (actual, expected) => {
 });
 ```
 
+### Transferring a person's queue
+
+Someone leaves, changes team, or goes on long-term leave, and their open
+approvals have to go somewhere:
+
+```ts
+const result = await engine.transferApprovals({
+  fromApprover: 'alice',
+  toApprover: 'bob',
+  transferredBy: 'workflow-admin',
+  reason: 'Alice left the company',
+  documentType: 'purchase_order',  // optional scoping
+  dryRun: true,                    // see what would move first
+});
+// { transferred: [{ instanceId, level, documentId }], failed: [...], scanned, dryRun }
+```
+
+Each move goes through `reassign()`, so every guard, audit entry, event and
+authorization check that applies to a single reassignment applies here too —
+there is no bulk short-cut around them. Inside a parallel group each open branch
+is moved separately, since one person can hold several open levels on the same
+document.
+
+The sweep is **not atomic**: it reports per-instance failures rather than rolling
+back. A partial transfer is the useful outcome — the approvals that can move
+should move, and the ones that cannot are named so a human can look at them.
+
+### Attachments
+
+Attach supporting evidence — a quote PDF, a signed contract, a screenshot of a
+system of record:
+
+```ts
+const withQuote = await engine.addAttachment(instance.id, {
+  actorId: 'buyer-1',
+  name: 'quote.pdf',
+  uri: 's3://procurement/quotes/q-1.pdf',   // a reference, not bytes
+  contentType: 'application/pdf',
+  sizeBytes: 48_120,
+});
+
+await engine.removeAttachment(instance.id, {
+  actorId: 'buyer-1',
+  attachmentId: withQuote.attachments[0].id,
+  reason: 'superseded by revised quote',
+});
+```
+
+**The engine stores references, never bytes.** Approval documents belong in the
+object store or DMS you already run, which handles retention, virus scanning and
+access control far better than an approval table could — copying them here would
+make the audit database the largest and least governed copy of them.
+
+Removing detaches the reference; it never deletes from the underlying store,
+which is the DMS's call. The audit entry keeps the name and URI of what was
+removed, so the trail still shows an approver saw evidence that is no longer
+listed.
+
+Emits `approval:attachment_added` / `approval:attachment_removed`. Allowed on
+any non-terminal instance, subject to your authorization policy.
+
 ### Asking the submitter a question
 
 Approvers routinely need one fact before they can decide. `requestInfo()` puts

package/dist/{ApprovalEngine-CyZJDbjP.d.ts → ApprovalEngine-CElfKXOA.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-CXRyeUOK.js';
-import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-SA0BU-Gb.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Cyo0cvXU.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-DMa5VNNz.js';
+import { l as ConditionExpression, p as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-BE0uJmg3.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Dv_MuYwS.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-rx7XAPrW.js';
-import { I as IAuditAdapter } from './IAuditAdapter-wfOcN3Zf.js';
-import { I as IMetricsAdapter } from './IMetricsAdapter-JZVK3QUq.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-DWYXVuJD.js';
+import { I as IAuditAdapter } from './IAuditAdapter-DDV4Rf9F.js';
+import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-CdvoZsGC.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-CFJ-gXKl.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -42,12 +42,14 @@ declare const DelegateOptionsSchema: z.ZodObject<{
     toApprover: z.ZodString;
     reason: z.ZodString;
     until: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const ReassignOptionsSchema: z.ZodObject<{
     reassignedBy: z.ZodString;
     fromApprover: z.ZodString;
     toApprover: z.ZodString;
     reason: z.ZodString;
+    level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const CancelOptionsSchema: z.ZodObject<{
     cancelledBy: z.ZodString;
@@ -78,6 +80,27 @@ declare const ProvideInfoOptionsSchema: z.ZodObject<{
     respondedBy: z.ZodString;
     response: z.ZodString;
 }, z.core.$strip>;
+declare const AddAttachmentOptionsSchema: z.ZodObject<{
+    actorId: z.ZodString;
+    name: z.ZodString;
+    uri: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+    sizeBytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const RemoveAttachmentOptionsSchema: z.ZodObject<{
+    actorId: z.ZodString;
+    attachmentId: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const TransferApprovalsOptionsSchema: z.ZodObject<{
+    fromApprover: z.ZodString;
+    toApprover: z.ZodString;
+    transferredBy: z.ZodString;
+    reason: z.ZodString;
+    documentType: z.ZodOptional<z.ZodString>;
+    dryRun: z.ZodDefault<z.ZodBoolean>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
 declare const UpdateDataOptionsSchema: z.ZodObject<{
     updatedBy: z.ZodString;
     data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -101,6 +124,9 @@ type OverrideOptions = z.infer<typeof OverrideOptionsSchema>;
 type UpdateDataOptions = z.infer<typeof UpdateDataOptionsSchema>;
 type RequestInfoOptions = z.infer<typeof RequestInfoOptionsSchema>;
 type ProvideInfoOptions = z.infer<typeof ProvideInfoOptionsSchema>;
+type AddAttachmentOptions = z.infer<typeof AddAttachmentOptionsSchema>;
+type RemoveAttachmentOptions = z.infer<typeof RemoveAttachmentOptionsSchema>;
+type TransferApprovalsOptions = z.infer<typeof TransferApprovalsOptionsSchema>;
 
 /**
  * Computes deadline dates from a number of days. The default engine behaviour
@@ -132,7 +158,7 @@ interface WeekendCalendarOptions {
  */
 declare function weekendCalendar(options?: WeekendCalendarOptions): BusinessCalendar;
 
-type IdGeneratorPrefix = 'inst' | 'tpl';
+type IdGeneratorPrefix = 'inst' | 'tpl' | 'att';
 type IdGeneratorFn = (prefix: IdGeneratorPrefix) => string;
 declare const defaultIdGenerator: IdGeneratorFn;
 
@@ -240,6 +266,24 @@ interface BulkResult {
     }>;
     total: number;
 }
+/** Outcome of a {@link ApprovalEngine.transferApprovals} sweep. */
+interface TransferResult {
+    /** One entry per level actually moved (an instance can hold the approver on several open branches). */
+    transferred: Array<{
+        instanceId: string;
+        level: number;
+        documentId: string;
+    }>;
+    /** Instances that could not be moved, with the reason. */
+    failed: Array<{
+        instanceId: string;
+        error: ApprovalError;
+    }>;
+    /** Instances examined. */
+    scanned: number;
+    /** True when nothing was written. */
+    dryRun: boolean;
+}
 interface ApprovalStatistics {
     /** Total instances matching the filter (across all statuses). */
     total: number;
@@ -490,6 +534,30 @@ declare class ApprovalEngine {
      * by being held.
      */
     private extendDeadlinesBy;
+    /**
+     * Attach supporting evidence to an approval — a quote PDF, a signed contract,
+     * a screenshot of a system of record.
+     *
+     * Stores a **reference**, never bytes. Approval documents belong in the object
+     * store or DMS the organisation already runs, which handles retention, virus
+     * scanning and access control far better than an approval table could;
+     * copying them here would make the audit database the largest and least
+     * governed copy of them.
+     *
+     * Allowed on any non-terminal instance, by anyone the authorization policy
+     * permits: the submitter adding a missing quote and an approver adding the
+     * note that justifies their decision are both ordinary.
+     */
+    addAttachment(instanceId: string, raw: AddAttachmentOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Detach a reference from an approval.
+     *
+     * The audit entry keeps the name and URI of what was removed, so the record
+     * still shows an approver saw evidence that is no longer listed — dropping
+     * that would let the trail imply a decision was made on less than it was.
+     * Nothing is deleted from the underlying store; that is the DMS's call.
+     */
+    removeAttachment(instanceId: string, raw: RemoveAttachmentOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /** Add a comment to an instance without approving or rejecting. */
     addComment(instanceId: string, raw: AddCommentOptions, auditCtx?: AuditContext): Promise<void>;
     /** Resubmit a rejected instance, creating a new linked instance from level 1. */
@@ -501,6 +569,28 @@ declare class ApprovalEngine {
     /** 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.
+     *
+     * Someone leaves, changes team, or goes on long-term leave, and their queue
+     * has to go somewhere. Doing it by hand means finding every open instance
+     * first — across parallel branches, where one person can hold several open
+     * levels on the same document — and missing one leaves an approval that can
+     * never complete.
+     *
+     * Each move goes through {@link reassign}, so every guard, audit entry, event
+     * and authorization check that applies to a single reassignment applies here
+     * too. There is no bulk short-cut around them.
+     *
+     * The sweep is **not atomic**: it reassigns one level at a time and reports
+     * per-instance failures rather than rolling back. A partial transfer is the
+     * useful outcome — the approvals that could move should move, and the ones
+     * that could not are named so a human can look at them.
+     *
+     * @param raw - Who is moving to whom, and why.
+     * @returns What moved, what did not, and why. With `dryRun` nothing is written.
+     */
+    transferApprovals(raw: TransferApprovalsOptions, auditCtx?: AuditContext): Promise<TransferResult>;
     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>;
@@ -614,4 +704,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type ProvideInfoOptions as n, type RejectOptions as o, type RequestInfoOptions as p, type ResubmitOptions as q, type RetryPolicy as r, defaultIdGenerator as s, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type TransferResult as T, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type ProvideInfoOptions as n, type RejectOptions as o, type RequestInfoOptions as p, type ResubmitOptions as q, type RetryPolicy as r, defaultIdGenerator as s, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };

package/dist/{ApprovalEngine-SI-IRUMY.d.cts → ApprovalEngine-cI4LP2Mx.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-Dz8jrIAK.cjs';
-import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-SA0BU-Gb.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Cn-LNPtD.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-CRSfnH8U.cjs';
+import { l as ConditionExpression, p as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-BE0uJmg3.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Dy2d0JKy.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-DrJy9UtL.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-Cr0dLoVP.cjs';
-import { I as IMetricsAdapter } from './IMetricsAdapter-JZVK3QUq.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-DGG-guxK.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-UJNdJanq.cjs';
+import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BHybAsq5.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-CN6LAaKg.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -42,12 +42,14 @@ declare const DelegateOptionsSchema: z.ZodObject<{
     toApprover: z.ZodString;
     reason: z.ZodString;
     until: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const ReassignOptionsSchema: z.ZodObject<{
     reassignedBy: z.ZodString;
     fromApprover: z.ZodString;
     toApprover: z.ZodString;
     reason: z.ZodString;
+    level: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 declare const CancelOptionsSchema: z.ZodObject<{
     cancelledBy: z.ZodString;
@@ -78,6 +80,27 @@ declare const ProvideInfoOptionsSchema: z.ZodObject<{
     respondedBy: z.ZodString;
     response: z.ZodString;
 }, z.core.$strip>;
+declare const AddAttachmentOptionsSchema: z.ZodObject<{
+    actorId: z.ZodString;
+    name: z.ZodString;
+    uri: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+    sizeBytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const RemoveAttachmentOptionsSchema: z.ZodObject<{
+    actorId: z.ZodString;
+    attachmentId: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const TransferApprovalsOptionsSchema: z.ZodObject<{
+    fromApprover: z.ZodString;
+    toApprover: z.ZodString;
+    transferredBy: z.ZodString;
+    reason: z.ZodString;
+    documentType: z.ZodOptional<z.ZodString>;
+    dryRun: z.ZodDefault<z.ZodBoolean>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
 declare const UpdateDataOptionsSchema: z.ZodObject<{
     updatedBy: z.ZodString;
     data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -101,6 +124,9 @@ type OverrideOptions = z.infer<typeof OverrideOptionsSchema>;
 type UpdateDataOptions = z.infer<typeof UpdateDataOptionsSchema>;
 type RequestInfoOptions = z.infer<typeof RequestInfoOptionsSchema>;
 type ProvideInfoOptions = z.infer<typeof ProvideInfoOptionsSchema>;
+type AddAttachmentOptions = z.infer<typeof AddAttachmentOptionsSchema>;
+type RemoveAttachmentOptions = z.infer<typeof RemoveAttachmentOptionsSchema>;
+type TransferApprovalsOptions = z.infer<typeof TransferApprovalsOptionsSchema>;
 
 /**
  * Computes deadline dates from a number of days. The default engine behaviour
@@ -132,7 +158,7 @@ interface WeekendCalendarOptions {
  */
 declare function weekendCalendar(options?: WeekendCalendarOptions): BusinessCalendar;
 
-type IdGeneratorPrefix = 'inst' | 'tpl';
+type IdGeneratorPrefix = 'inst' | 'tpl' | 'att';
 type IdGeneratorFn = (prefix: IdGeneratorPrefix) => string;
 declare const defaultIdGenerator: IdGeneratorFn;
 
@@ -240,6 +266,24 @@ interface BulkResult {
     }>;
     total: number;
 }
+/** Outcome of a {@link ApprovalEngine.transferApprovals} sweep. */
+interface TransferResult {
+    /** One entry per level actually moved (an instance can hold the approver on several open branches). */
+    transferred: Array<{
+        instanceId: string;
+        level: number;
+        documentId: string;
+    }>;
+    /** Instances that could not be moved, with the reason. */
+    failed: Array<{
+        instanceId: string;
+        error: ApprovalError;
+    }>;
+    /** Instances examined. */
+    scanned: number;
+    /** True when nothing was written. */
+    dryRun: boolean;
+}
 interface ApprovalStatistics {
     /** Total instances matching the filter (across all statuses). */
     total: number;
@@ -490,6 +534,30 @@ declare class ApprovalEngine {
      * by being held.
      */
     private extendDeadlinesBy;
+    /**
+     * Attach supporting evidence to an approval — a quote PDF, a signed contract,
+     * a screenshot of a system of record.
+     *
+     * Stores a **reference**, never bytes. Approval documents belong in the object
+     * store or DMS the organisation already runs, which handles retention, virus
+     * scanning and access control far better than an approval table could;
+     * copying them here would make the audit database the largest and least
+     * governed copy of them.
+     *
+     * Allowed on any non-terminal instance, by anyone the authorization policy
+     * permits: the submitter adding a missing quote and an approver adding the
+     * note that justifies their decision are both ordinary.
+     */
+    addAttachment(instanceId: string, raw: AddAttachmentOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Detach a reference from an approval.
+     *
+     * The audit entry keeps the name and URI of what was removed, so the record
+     * still shows an approver saw evidence that is no longer listed — dropping
+     * that would let the trail imply a decision was made on less than it was.
+     * Nothing is deleted from the underlying store; that is the DMS's call.
+     */
+    removeAttachment(instanceId: string, raw: RemoveAttachmentOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /** Add a comment to an instance without approving or rejecting. */
     addComment(instanceId: string, raw: AddCommentOptions, auditCtx?: AuditContext): Promise<void>;
     /** Resubmit a rejected instance, creating a new linked instance from level 1. */
@@ -501,6 +569,28 @@ declare class ApprovalEngine {
     /** 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.
+     *
+     * Someone leaves, changes team, or goes on long-term leave, and their queue
+     * has to go somewhere. Doing it by hand means finding every open instance
+     * first — across parallel branches, where one person can hold several open
+     * levels on the same document — and missing one leaves an approval that can
+     * never complete.
+     *
+     * Each move goes through {@link reassign}, so every guard, audit entry, event
+     * and authorization check that applies to a single reassignment applies here
+     * too. There is no bulk short-cut around them.
+     *
+     * The sweep is **not atomic**: it reassigns one level at a time and reports
+     * per-instance failures rather than rolling back. A partial transfer is the
+     * useful outcome — the approvals that could move should move, and the ones
+     * that could not are named so a human can look at them.
+     *
+     * @param raw - Who is moving to whom, and why.
+     * @returns What moved, what did not, and why. With `dryRun` nothing is written.
+     */
+    transferApprovals(raw: TransferApprovalsOptions, auditCtx?: AuditContext): Promise<TransferResult>;
     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>;
@@ -614,4 +704,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type ProvideInfoOptions as n, type RejectOptions as o, type RequestInfoOptions as p, type ResubmitOptions as q, type RetryPolicy as r, defaultIdGenerator as s, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type TransferResult as T, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type ProvideInfoOptions as n, type RejectOptions as o, type RequestInfoOptions as p, type ResubmitOptions as q, type RetryPolicy as r, defaultIdGenerator as s, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };

package/dist/{IAuditAdapter-wfOcN3Zf.d.ts → IAuditAdapter-DDV4Rf9F.d.ts}

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

package/dist/{IAuditAdapter-Cr0dLoVP.d.cts → IAuditAdapter-UJNdJanq.d.cts}

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

package/dist/{IAuthorizationPolicy-BHybAsq5.d.cts → IAuthorizationPolicy-CFJ-gXKl.d.ts}

@@ -1,7 +1,7 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-SA0BU-Gb.cjs';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-BE0uJmg3.js';
 
 interface AuthorizationContext {
-    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData' | 'requestInfo' | 'provideInfo';
+    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment';
     actorId: string;
     instance: Readonly<ApprovalInstance>;
     level?: Readonly<ApprovalLevelInstance>;

package/dist/{IAuthorizationPolicy-CdvoZsGC.d.ts → IAuthorizationPolicy-CN6LAaKg.d.cts}

@@ -1,7 +1,7 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-SA0BU-Gb.js';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-BE0uJmg3.cjs';
 
 interface AuthorizationContext {
-    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData' | 'requestInfo' | 'provideInfo';
+    operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment';
     actorId: string;
     instance: Readonly<ApprovalInstance>;
     level?: Readonly<ApprovalLevelInstance>;

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

@@ -1,4 +1,4 @@
-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.conflict_retry' | 'approval.operation_duration_ms';
+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. */
     increment(metric: MetricName, labels?: Record<string, string>): void;

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

@@ -1,4 +1,4 @@
-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.conflict_retry' | 'approval.operation_duration_ms';
+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. */
     increment(metric: MetricName, labels?: Record<string, string>): void;

package/dist/{INotificationAdapter-Cn-LNPtD.d.cts → INotificationAdapter-Dv_MuYwS.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-SA0BU-Gb.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-BE0uJmg3.js';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -104,6 +104,14 @@ interface InfoProvidedEvent extends ApprovalEvent {
     /** The approvers waiting again now that the question is answered. */
     recipients: string[];
 }
+/** Emitted when supporting evidence is attached to or removed from an approval. */
+interface AttachmentEvent extends ApprovalEvent {
+    actorId: string;
+    attachmentId: string;
+    name: string;
+    uri: string;
+    level?: number;
+}
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -122,6 +130,8 @@ interface ApprovalEventMap {
     'approval:reminder': ReminderEvent;
     'approval:info_requested': InfoRequestedEvent;
     'approval:info_provided': InfoProvidedEvent;
+    'approval:attachment_added': AttachmentEvent;
+    'approval:attachment_removed': AttachmentEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
 interface HistoryEntry extends AuditEntry {
@@ -145,4 +155,4 @@ interface INotificationAdapter {
     notify(event: NotificationEvent): Promise<void>;
 }
 
-export type { ApprovalEvent as A, CancelledEvent as C, DataUpdatedEvent as D, EscalatedEvent as E, HistoryEntry as H, INotificationAdapter as I, LevelAdvancedEvent as L, NotificationEvent as N, OverriddenEvent as O, ReassignedEvent as R, SlaBreachedEvent as S, ApprovalEventMap as a, ApprovalEventName as b, ApprovedEvent as c, DelegatedEvent as d, ExpiredEvent as e, InfoProvidedEvent as f, InfoRequestedEvent as g, RejectedEvent as h, ReminderEvent as i, ResubmittedEvent as j, SubmittedEvent as k };
+export type { ApprovalEvent as A, CancelledEvent as C, DataUpdatedEvent as D, EscalatedEvent as E, HistoryEntry as H, INotificationAdapter as I, LevelAdvancedEvent as L, NotificationEvent as N, OverriddenEvent as O, ReassignedEvent as R, SlaBreachedEvent as S, ApprovalEventMap as a, ApprovalEventName as b, ApprovedEvent as c, AttachmentEvent as d, DelegatedEvent as e, ExpiredEvent as f, InfoProvidedEvent as g, InfoRequestedEvent as h, RejectedEvent as i, ReminderEvent as j, ResubmittedEvent as k, SubmittedEvent as l };

package/dist/{INotificationAdapter-Cyo0cvXU.d.ts → INotificationAdapter-Dy2d0JKy.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-SA0BU-Gb.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-BE0uJmg3.cjs';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -104,6 +104,14 @@ interface InfoProvidedEvent extends ApprovalEvent {
     /** The approvers waiting again now that the question is answered. */
     recipients: string[];
 }
+/** Emitted when supporting evidence is attached to or removed from an approval. */
+interface AttachmentEvent extends ApprovalEvent {
+    actorId: string;
+    attachmentId: string;
+    name: string;
+    uri: string;
+    level?: number;
+}
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -122,6 +130,8 @@ interface ApprovalEventMap {
     'approval:reminder': ReminderEvent;
     'approval:info_requested': InfoRequestedEvent;
     'approval:info_provided': InfoProvidedEvent;
+    'approval:attachment_added': AttachmentEvent;
+    'approval:attachment_removed': AttachmentEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
 interface HistoryEntry extends AuditEntry {
@@ -145,4 +155,4 @@ interface INotificationAdapter {
     notify(event: NotificationEvent): Promise<void>;
 }
 
-export type { ApprovalEvent as A, CancelledEvent as C, DataUpdatedEvent as D, EscalatedEvent as E, HistoryEntry as H, INotificationAdapter as I, LevelAdvancedEvent as L, NotificationEvent as N, OverriddenEvent as O, ReassignedEvent as R, SlaBreachedEvent as S, ApprovalEventMap as a, ApprovalEventName as b, ApprovedEvent as c, DelegatedEvent as d, ExpiredEvent as e, InfoProvidedEvent as f, InfoRequestedEvent as g, RejectedEvent as h, ReminderEvent as i, ResubmittedEvent as j, SubmittedEvent as k };
+export type { ApprovalEvent as A, CancelledEvent as C, DataUpdatedEvent as D, EscalatedEvent as E, HistoryEntry as H, INotificationAdapter as I, LevelAdvancedEvent as L, NotificationEvent as N, OverriddenEvent as O, ReassignedEvent as R, SlaBreachedEvent as S, ApprovalEventMap as a, ApprovalEventName as b, ApprovedEvent as c, AttachmentEvent as d, DelegatedEvent as e, ExpiredEvent as f, InfoProvidedEvent as g, InfoRequestedEvent as h, RejectedEvent as i, ReminderEvent as j, ResubmittedEvent as k, SubmittedEvent as l };

package/dist/{IOperationMiddleware-DrJy9UtL.d.cts → IOperationMiddleware-DGG-guxK.d.cts}

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

package/dist/{IOperationMiddleware-rx7XAPrW.d.ts → IOperationMiddleware-DWYXVuJD.d.ts}

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