hierarchical-approval 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -7,6 +7,81 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [1.9.0] - 2026-09-04
+
+### Added — `getWorkload()`
+
+- **Reports who currently owes a decision, and how overdue they are.**
+  `getStatistics()` answers how the tenant is doing; nothing answered who is
+  holding it up — the question behind rebalancing a queue, spotting the approver
+  who has been on leave for a week, or deciding whom to `transferApprovals()` a
+  departing colleague's work to.
+
+  ```ts
+  await engine.getWorkload({ documentType: 'purchase_order' });
+  // [{ approverId: 'alice', pending: 12, instances: 11, overdue: 3, onHold: 1,
+  //    oldestPendingAt: …, oldestAgeMs: 604800000 }, …]
+  ```
+
+  Sorted busiest first. `pending` counts open **levels** while `instances`
+  counts distinct documents — they differ when one person holds several branches
+  of a parallel group. `overdue` measures against each level's escalation
+  deadline, and `onHold` counts work paused by a clarification request.
+
+- **An approver who has already voted is not counted**, even while the level
+  stays open collecting other votes: they owe nothing more, and counting them
+  would overstate the queue of every quorum and weighted level.
+
+- Computed from pending instances rather than a dedicated index, so it works on
+  any storage adapter with no new adapter methods. That means it reads every
+  pending instance in the tenant — fine for the volumes an approval queue
+  reaches, but it is a reporting call, not something for a hot path.
+
+  New export: `ApproverWorkload`.
+
+## [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

package/README.md

@@ -399,6 +399,57 @@ engine.registerConditionOperator('between', (actual, expected) => {
 });
 ```
 
+### Who is holding things up
+
+`getStatistics()` answers how the tenant is doing; `getWorkload()` answers who
+is holding it up — the question behind rebalancing a queue or deciding whom to
+hand a departing colleague's work to:
+
+```ts
+const workload = await engine.getWorkload({ documentType: 'purchase_order' });
+// [
+//   { approverId: 'alice', pending: 12, instances: 11, overdue: 3, onHold: 1,
+//     oldestPendingAt: 2026-01-02T…, oldestAgeMs: 604800000 },
+//   ...
+// ]
+```
+
+Busiest queue first. `pending` counts open **levels**, `instances` counts
+distinct documents — they differ when one person holds several branches of a
+parallel group. An approver who has already voted on a level that is still
+collecting other votes owes nothing more and is not counted.
+
+Computed from pending instances rather than a dedicated index, so it works on
+any adapter with no new adapter methods — but it reads every pending instance in
+the tenant. It is a reporting call, not something for a hot path.
+
+### 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

package/dist/{ApprovalEngine-D16llfJv.d.cts → ApprovalEngine-BDI4r_KB.d.cts}

@@ -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;
@@ -90,6 +92,15 @@ declare const RemoveAttachmentOptionsSchema: z.ZodObject<{
     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>;
@@ -115,6 +126,7 @@ 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
@@ -254,6 +266,45 @@ 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;
+}
+/**
+ * What one approver currently owes a decision on.
+ *
+ * Durations are milliseconds. An approver appears only while they hold at least
+ * one open level.
+ */
+interface ApproverWorkload {
+    approverId: string;
+    /** Open levels assigned to them. One instance can contribute several across parallel branches. */
+    pending: number;
+    /** Distinct documents involved — usually, but not always, equal to {@link pending}. */
+    instances: number;
+    /** Open levels already past their escalation deadline. */
+    overdue: number;
+    /** Open levels currently paused by a clarification request. */
+    onHold: number;
+    /** When the oldest of their open items was submitted. */
+    oldestPendingAt?: Date;
+    /** Age of that oldest item. `0` when they hold nothing. */
+    oldestAgeMs: number;
+}
 interface ApprovalStatistics {
     /** Total instances matching the filter (across all statuses). */
     total: number;
@@ -539,6 +590,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>;
@@ -555,6 +628,27 @@ declare class ApprovalEngine {
      * submittedBy, date range) — `status` is ignored since every status is counted.
      * Adapter-agnostic: issues one cheap count query per status plus an overdue scan.
      */
+    /**
+     * Who currently owes a decision, and how overdue they are.
+     *
+     * `getStatistics()` answers how the tenant is doing; this answers who is
+     * holding it up — the question behind rebalancing a queue, spotting the
+     * approver who has been on leave for a week, or deciding whom to
+     * {@link transferApprovals} a departing colleague's work to.
+     *
+     * Computed from pending instances rather than a dedicated index, so it works
+     * on any storage adapter with no new adapter methods. That means it reads
+     * every pending instance in the tenant: fine for the operational volumes an
+     * approval queue reaches, but it is a reporting call, not something to put on
+     * a hot path.
+     *
+     * Rows are sorted by {@link ApproverWorkload.pending} descending, so the
+     * busiest queue is first.
+     *
+     * @param filter - Optional scoping; `status` is ignored, since only pending work counts.
+     * @returns One row per approver holding at least one open level.
+     */
+    getWorkload(filter?: Omit<InstanceFilter, 'status'>): Promise<ApproverWorkload[]>;
     getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
     shutdown(): Promise<void>;
     /**
@@ -652,4 +746,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 ApproverWorkload as f, type BusinessCalendar as g, type CancelOptions as h, type ConditionOperatorFn as i, type CycleTimeStats as j, type IdempotencyKeyFn as k, type OutOfOfficeProvider as l, type OverrideOptions as m, type PreviewResult as n, type ProvideInfoOptions as o, type RejectOptions as p, type RequestInfoOptions as q, type ResubmitOptions as r, type RetryPolicy as s, defaultIdGenerator as t, toComparableNumber as u, validateConditionExpression as v, weekendCalendar as w };

package/dist/{ApprovalEngine-gQdFy2CO.d.ts → ApprovalEngine-a1jXglT3.d.ts}

@@ -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;
@@ -90,6 +92,15 @@ declare const RemoveAttachmentOptionsSchema: z.ZodObject<{
     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>;
@@ -115,6 +126,7 @@ 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
@@ -254,6 +266,45 @@ 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;
+}
+/**
+ * What one approver currently owes a decision on.
+ *
+ * Durations are milliseconds. An approver appears only while they hold at least
+ * one open level.
+ */
+interface ApproverWorkload {
+    approverId: string;
+    /** Open levels assigned to them. One instance can contribute several across parallel branches. */
+    pending: number;
+    /** Distinct documents involved — usually, but not always, equal to {@link pending}. */
+    instances: number;
+    /** Open levels already past their escalation deadline. */
+    overdue: number;
+    /** Open levels currently paused by a clarification request. */
+    onHold: number;
+    /** When the oldest of their open items was submitted. */
+    oldestPendingAt?: Date;
+    /** Age of that oldest item. `0` when they hold nothing. */
+    oldestAgeMs: number;
+}
 interface ApprovalStatistics {
     /** Total instances matching the filter (across all statuses). */
     total: number;
@@ -539,6 +590,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>;
@@ -555,6 +628,27 @@ declare class ApprovalEngine {
      * submittedBy, date range) — `status` is ignored since every status is counted.
      * Adapter-agnostic: issues one cheap count query per status plus an overdue scan.
      */
+    /**
+     * Who currently owes a decision, and how overdue they are.
+     *
+     * `getStatistics()` answers how the tenant is doing; this answers who is
+     * holding it up — the question behind rebalancing a queue, spotting the
+     * approver who has been on leave for a week, or deciding whom to
+     * {@link transferApprovals} a departing colleague's work to.
+     *
+     * Computed from pending instances rather than a dedicated index, so it works
+     * on any storage adapter with no new adapter methods. That means it reads
+     * every pending instance in the tenant: fine for the operational volumes an
+     * approval queue reaches, but it is a reporting call, not something to put on
+     * a hot path.
+     *
+     * Rows are sorted by {@link ApproverWorkload.pending} descending, so the
+     * busiest queue is first.
+     *
+     * @param filter - Optional scoping; `status` is ignored, since only pending work counts.
+     * @returns One row per approver holding at least one open level.
+     */
+    getWorkload(filter?: Omit<InstanceFilter, 'status'>): Promise<ApproverWorkload[]>;
     getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
     shutdown(): Promise<void>;
     /**
@@ -652,4 +746,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 ApproverWorkload as f, type BusinessCalendar as g, type CancelOptions as h, type ConditionOperatorFn as i, type CycleTimeStats as j, type IdempotencyKeyFn as k, type OutOfOfficeProvider as l, type OverrideOptions as m, type PreviewResult as n, type ProvideInfoOptions as o, type RejectOptions as p, type RequestInfoOptions as q, type ResubmitOptions as r, type RetryPolicy as s, defaultIdGenerator as t, toComparableNumber as u, validateConditionExpression as v, weekendCalendar as w };

package/dist/index.cjs

@@ -39,13 +39,20 @@ var DelegateOptionsSchema = zod.z.object({
   fromApprover: zod.z.string().min(1),
   toApprover: zod.z.string().min(1),
   reason: zod.z.string().min(1),
-  until: zod.z.coerce.date().optional()
+  until: zod.z.coerce.date().optional(),
+  /**
+   * Which open level to act on. Only needed inside a parallel group, where the
+   * approver may hold more than one open branch.
+   */
+  level: zod.z.number().int().optional()
 });
 var ReassignOptionsSchema = zod.z.object({
   reassignedBy: zod.z.string().min(1),
   fromApprover: zod.z.string().min(1),
   toApprover: zod.z.string().min(1),
-  reason: zod.z.string().min(1)
+  reason: zod.z.string().min(1),
+  /** Which open level to act on; see {@link DelegateOptionsSchema}. */
+  level: zod.z.number().int().optional()
 });
 var CancelOptionsSchema = zod.z.object({
   cancelledBy: zod.z.string().min(1),
@@ -90,6 +97,18 @@ var RemoveAttachmentOptionsSchema = zod.z.object({
   attachmentId: zod.z.string().min(1),
   reason: zod.z.string().optional()
 });
+var TransferApprovalsOptionsSchema = zod.z.object({
+  fromApprover: zod.z.string().min(1),
+  toApprover: zod.z.string().min(1),
+  transferredBy: zod.z.string().min(1),
+  reason: zod.z.string().min(1),
+  /** Restrict the sweep to one document type. */
+  documentType: zod.z.string().optional(),
+  /** Report what would move without changing anything. */
+  dryRun: zod.z.boolean().default(false),
+  /** Safety cap on how many instances one sweep will touch. */
+  limit: zod.z.number().int().positive().default(500)
+});
 var UpdateDataOptionsSchema = zod.z.object({
   updatedBy: zod.z.string().min(1),
   data: zod.z.record(zod.z.string(), zod.z.unknown()),
@@ -1647,7 +1666,7 @@ var ApprovalEngine = class _ApprovalEngine {
       if (opts.fromApprover === opts.toApprover) {
         throw new ApprovalForbiddenError("Cannot delegate to yourself.");
       }
-      const level = this.currentLevelInstance(instance);
+      const level = this.resolveActorLevel(instance, opts.fromApprover, opts.level);
       await this.runAuthorizationPolicy({
         operation: "delegate",
         actorId: opts.fromApprover,
@@ -1729,7 +1748,7 @@ var ApprovalEngine = class _ApprovalEngine {
       if (opts.fromApprover === opts.toApprover) {
         throw new ApprovalForbiddenError("Cannot reassign an approver to themselves.");
       }
-      const level = this.currentLevelInstance(instance);
+      const level = this.resolveActorLevel(instance, opts.fromApprover, opts.level);
       await this.runAuthorizationPolicy({
         operation: "reassign",
         actorId: opts.reassignedBy,
@@ -2365,9 +2384,7 @@ var ApprovalEngine = class _ApprovalEngine {
         input: opts
       });
       const now = this.clock.now();
-      instance.attachments = (instance.attachments ?? []).filter(
-        (a) => a.id !== opts.attachmentId
-      );
+      instance.attachments = (instance.attachments ?? []).filter((a) => a.id !== opts.attachmentId);
       instance.updatedAt = now;
       const auditEntry = {
         action: "attachment_removed",
@@ -2706,6 +2723,95 @@ var ApprovalEngine = class _ApprovalEngine {
     });
   }
   /** 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.
+   */
+  async transferApprovals(raw, auditCtx) {
+    const opts = parseOrThrow(() => TransferApprovalsOptionsSchema.parse(raw));
+    if (opts.fromApprover === opts.toApprover) {
+      throw new ApprovalValidationError(
+        "transferApprovals requires different fromApprover and toApprover."
+      );
+    }
+    const queue = await this.opts.adapter.getInstancesByApprover(this.tenantId, opts.fromApprover, {
+      limit: opts.limit,
+      offset: 0
+    });
+    const result = {
+      transferred: [],
+      failed: [],
+      scanned: 0,
+      dryRun: opts.dryRun
+    };
+    for (const instance of queue.items) {
+      if (opts.documentType && instance.documentType !== opts.documentType) continue;
+      result.scanned++;
+      const levels = instance.levels.filter(
+        (l) => l.status === "pending" && l.approverIds.includes(opts.fromApprover)
+      );
+      for (const level of levels) {
+        if (opts.dryRun) {
+          result.transferred.push({
+            instanceId: instance.id,
+            level: level.level,
+            documentId: instance.documentId
+          });
+          continue;
+        }
+        try {
+          await this.reassign(
+            instance.id,
+            {
+              reassignedBy: opts.transferredBy,
+              fromApprover: opts.fromApprover,
+              toApprover: opts.toApprover,
+              reason: opts.reason,
+              level: level.level
+            },
+            auditCtx
+          );
+          result.transferred.push({
+            instanceId: instance.id,
+            level: level.level,
+            documentId: instance.documentId
+          });
+        } catch (err) {
+          result.failed.push({
+            instanceId: instance.id,
+            error: err instanceof ApprovalError ? err : new ApprovalError(String(err), "UNKNOWN")
+          });
+        }
+      }
+    }
+    this.logger.info("transferApprovals: sweep complete", {
+      tenantId: this.tenantId,
+      fromApprover: opts.fromApprover,
+      toApprover: opts.toApprover,
+      scanned: result.scanned,
+      transferred: result.transferred.length,
+      failed: result.failed.length,
+      dryRun: opts.dryRun
+    });
+    return result;
+  }
   async bulkApprove(instanceIds, raw, auditCtx) {
     const opts = parseOrThrow(() => ApproveOptionsSchema.parse(raw));
     this.guardBulkSize(instanceIds);
@@ -2808,6 +2914,66 @@ var ApprovalEngine = class _ApprovalEngine {
    * submittedBy, date range) — `status` is ignored since every status is counted.
    * Adapter-agnostic: issues one cheap count query per status plus an overdue scan.
    */
+  /**
+   * Who currently owes a decision, and how overdue they are.
+   *
+   * `getStatistics()` answers how the tenant is doing; this answers who is
+   * holding it up — the question behind rebalancing a queue, spotting the
+   * approver who has been on leave for a week, or deciding whom to
+   * {@link transferApprovals} a departing colleague's work to.
+   *
+   * Computed from pending instances rather than a dedicated index, so it works
+   * on any storage adapter with no new adapter methods. That means it reads
+   * every pending instance in the tenant: fine for the operational volumes an
+   * approval queue reaches, but it is a reporting call, not something to put on
+   * a hot path.
+   *
+   * Rows are sorted by {@link ApproverWorkload.pending} descending, so the
+   * busiest queue is first.
+   *
+   * @param filter - Optional scoping; `status` is ignored, since only pending work counts.
+   * @returns One row per approver holding at least one open level.
+   */
+  async getWorkload(filter = {}) {
+    const pending = await this.fetchAllByFilter({ ...filter, status: "pending" });
+    const now = this.clock.now();
+    const byApprover = /* @__PURE__ */ new Map();
+    for (const instance of pending) {
+      const submittedAt = new Date(instance.createdAt).getTime();
+      const held = Boolean(instance.infoRequest);
+      for (const level of instance.levels) {
+        if (level.status !== "pending") continue;
+        const isOverdue = level.escalationDueAt !== void 0 && new Date(level.escalationDueAt) <= now;
+        for (const approverId of level.approverIds) {
+          if (level.approvedBy.includes(approverId) || level.rejectedBy.includes(approverId)) {
+            continue;
+          }
+          const row = byApprover.get(approverId) ?? {
+            pending: 0,
+            instances: /* @__PURE__ */ new Set(),
+            overdue: 0,
+            onHold: 0,
+            oldest: Number.POSITIVE_INFINITY
+          };
+          row.pending++;
+          row.instances.add(instance.id);
+          if (isOverdue) row.overdue++;
+          if (held) row.onHold++;
+          row.oldest = Math.min(row.oldest, submittedAt);
+          byApprover.set(approverId, row);
+        }
+      }
+    }
+    return [...byApprover.entries()].map(([approverId, row]) => ({
+      approverId,
+      pending: row.pending,
+      instances: row.instances.size,
+      overdue: row.overdue,
+      onHold: row.onHold,
+      oldestPendingAt: Number.isFinite(row.oldest) ? new Date(row.oldest) : void 0,
+      oldestAgeMs: Number.isFinite(row.oldest) ? now.getTime() - row.oldest : 0
+    })).sort((a, b) => b.pending - a.pending || a.approverId.localeCompare(b.approverId));
+  }
   async getStatistics(filter = {}) {
     const statuses = [
       "pending",