hierarchical-approval 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [2.6.0] - 2026-09-04
+
+### Added — escalation ladders
+
+- **`escalationSteps` escalates repeatedly, up a chain.** A single `escalation`
+  could only ever fire once, so a request that stalled past its second deadline
+  had nowhere further to go — the usual "chase the manager, then the director,
+  then the VP" pattern had to be built outside the engine, on top of the events.
+
+  ```ts
+  escalationSteps: [
+    { afterDays: 2, escalateTo: { type: 'user', userId: 'director' } },
+    { afterDays: 4, escalateTo: { type: 'user', userId: 'vp' } },
+    { afterDays: 7, escalateTo: { type: 'role', role: 'exec' } },
+  ]
+  ```
+
+  Rungs are sorted by delay and fire in order, each **adding** an approver rather
+  than replacing one: escalation widens the pool, it does not hand the work over.
+
+- **Delays are measured from when the level opened, not from the previous
+  escalation**, so a ladder reads the way it is written. The level's opening
+  time is recovered from its `submitted` / `level_advanced` audit entry.
+
+- Rungs accept `afterHours` as well as `afterDays`, counted through the
+  working-hours calendar from 2.5.0 when one is configured. A per-level
+  `escalationAfterDays`/`escalationAfterHours` still decides *when* the first
+  rung fires — it is the more specific statement about that level — while the
+  ladder supplies *who*.
+
+- Templates carrying only the single-step `escalation` behave exactly as before;
+  the ladder takes precedence when both are set. Levels track progress in
+  `escalationStep`, and the ladder is captured in the template snapshot, so an
+  in-flight approval keeps the ladder it was submitted under.
+
+  New exports: `EscalationStep`. `ApprovalTemplateConfig` gains
+  `escalationSteps`; levels gain `escalationStep`.
+
 ## [2.5.0] - 2026-09-04
 
 ### Added — deadlines in working hours

package/README.md

@@ -468,6 +468,33 @@ The sweep is **not atomic**: it reports per-instance failures rather than rollin
 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.
 
+### Escalation ladders
+
+A single `escalation` fires once, so a request that stalls past its second
+deadline has nowhere further to go. `escalationSteps` is a ladder:
+
+```ts
+escalationSteps: [
+  { afterDays: 2, escalateTo: { type: 'user', userId: 'director' } },
+  { afterDays: 4, escalateTo: { type: 'user', userId: 'vp' } },
+  { afterDays: 7, escalateTo: { type: 'role', role: 'exec' } },
+]
+```
+
+Rungs are sorted by delay and fire in order, each **adding** an approver without
+removing anyone already assigned — escalation widens the pool rather than
+handing the work over.
+
+Every delay is measured **from the moment the level opened**, not from the
+previous escalation, so the ladder reads the way it is written: late at day 2,
+later at day 4, latest at day 7. Rungs accept `afterHours` too, counted through
+the working-hours calendar if one is configured.
+
+A per-level `escalationAfterDays`/`escalationAfterHours` still wins for *when*
+the first rung fires — it is the more specific statement about that level — while
+the ladder supplies *who*. Templates with only the single-step `escalation`
+behave exactly as before.
+
 ### SLAs in working hours
 
 Deadlines were whole days, so "respond within four working hours" could only be

package/dist/{ApprovalEngine-CW7Uu1bV.d.cts → ApprovalEngine-BWrblNQ0.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-Pq9J60xv.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-BO-i9-nq.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-AwbhZEqz.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-yX9ERfQE.cjs';
+import { l as ConditionExpression, q as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-weh2w7Ji.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-C6HPrzh6.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-3J-_NSGq.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-Dwx8ZP4J.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-CxnPzpqL.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-2UU5edKG.cjs';
 import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-B3vaV69v.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-DPpiKzyh.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -852,6 +852,28 @@ declare class ApprovalEngine {
     private deadlineFromHours;
     /** Level deadline from whichever of days/hours the template configured. */
     private levelEscalationDue;
+    /** First rung of a ladder, sorted by delay, or undefined when there is none. */
+    private firstRungOf;
+    /**
+     * The escalation ladder for an instance, sorted by delay.
+     *
+     * Read from the instance's template snapshot so an in-flight approval keeps
+     * the ladder it was submitted under, exactly as the single-step
+     * {@link EscalationConfig} already did.
+     */
+    private escalationLadder;
+    /**
+     * When a level started collecting decisions.
+     *
+     * Escalation rungs are measured from this, not from the previous rung, so a
+     * ladder reads the way it is written. Recovered from the audit trail — the
+     * `submitted` entry for the opening level, the `level_advanced` entry
+     * otherwise — and falls back to `now` when no entry exists, which only leaves
+     * the ladder no worse off than the single-step behaviour it replaces.
+     */
+    private levelOpenedAt;
+    /** Deadline for one rung, measured from when the level opened. */
+    private stepDueAt;
     private requireInstance;
     /**
      * Identity of the parallel branch group a level belongs to.

package/dist/{ApprovalEngine-BHWls8-z.d.ts → ApprovalEngine-D4DdSx-M.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-Dw2xXP9B.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-BO-i9-nq.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BBq2czpO.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-ChPT7ZDp.js';
+import { l as ConditionExpression, q as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-weh2w7Ji.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BNGivLgU.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-CqzFklMn.js';
-import { I as IAuditAdapter } from './IAuditAdapter-CMCirvY-.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-CXtg2wzF.js';
+import { I as IAuditAdapter } from './IAuditAdapter-DSor54iY.js';
 import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BryQIKko.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BOWg-3AH.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -852,6 +852,28 @@ declare class ApprovalEngine {
     private deadlineFromHours;
     /** Level deadline from whichever of days/hours the template configured. */
     private levelEscalationDue;
+    /** First rung of a ladder, sorted by delay, or undefined when there is none. */
+    private firstRungOf;
+    /**
+     * The escalation ladder for an instance, sorted by delay.
+     *
+     * Read from the instance's template snapshot so an in-flight approval keeps
+     * the ladder it was submitted under, exactly as the single-step
+     * {@link EscalationConfig} already did.
+     */
+    private escalationLadder;
+    /**
+     * When a level started collecting decisions.
+     *
+     * Escalation rungs are measured from this, not from the previous rung, so a
+     * ladder reads the way it is written. Recovered from the audit trail — the
+     * `submitted` entry for the opening level, the `level_advanced` entry
+     * otherwise — and falls back to `now` when no entry exists, which only leaves
+     * the ladder no worse off than the single-step behaviour it replaces.
+     */
+    private levelOpenedAt;
+    /** Deadline for one rung, measured from when the level opened. */
+    private stepDueAt;
     private requireInstance;
     /**
      * Identity of the parallel branch group a level belongs to.

package/dist/{IAuditAdapter-Dwx8ZP4J.d.cts → IAuditAdapter-2UU5edKG.d.cts}

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

package/dist/{IAuditAdapter-CMCirvY-.d.ts → IAuditAdapter-DSor54iY.d.ts}

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

package/dist/{IAuthorizationPolicy-BryQIKko.d.ts → IAuthorizationPolicy-BOWg-3AH.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-BO-i9-nq.js';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-weh2w7Ji.js';
 
 interface AuthorizationContext {
     operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment';

package/dist/{IAuthorizationPolicy-B3vaV69v.d.cts → IAuthorizationPolicy-DPpiKzyh.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-BO-i9-nq.cjs';
+import { a as ApprovalInstance, d as ApprovalLevelInstance } from './instance-weh2w7Ji.cjs';
 
 interface AuthorizationContext {
     operation: 'submit' | 'approve' | 'reject' | 'delegate' | 'reassign' | 'cancel' | 'escalate' | 'override' | 'resubmit' | 'addComment' | 'updateData' | 'requestInfo' | 'provideInfo' | 'addAttachment' | 'removeAttachment';

package/dist/{INotificationAdapter-BBq2czpO.d.ts → INotificationAdapter-BNGivLgU.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-BO-i9-nq.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-weh2w7Ji.js';
 
 interface ApprovalEvent {
     instanceId: string;

package/dist/{INotificationAdapter-AwbhZEqz.d.cts → INotificationAdapter-C6HPrzh6.d.cts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-BO-i9-nq.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-weh2w7Ji.cjs';
 
 interface ApprovalEvent {
     instanceId: string;

package/dist/{IOperationMiddleware-CqzFklMn.d.ts → IOperationMiddleware-CXtg2wzF.d.ts}

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

package/dist/{IOperationMiddleware-3J-_NSGq.d.cts → IOperationMiddleware-CxnPzpqL.d.cts}

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

package/dist/{IStorageAdapter-Dw2xXP9B.d.ts → IStorageAdapter-ChPT7ZDp.d.ts}

@@ -1,4 +1,4 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-BO-i9-nq.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-weh2w7Ji.js';
 
 interface PaginationOpts {
     limit: number;

package/dist/{IStorageAdapter-Pq9J60xv.d.cts → IStorageAdapter-yX9ERfQE.d.cts}

@@ -1,4 +1,4 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-BO-i9-nq.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-weh2w7Ji.cjs';
 
 interface PaginationOpts {
     limit: number;

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-Pq9J60xv.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BO-i9-nq.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-yX9ERfQE.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-weh2w7Ji.cjs';
 
 declare class MemoryAdapter implements IStorageAdapter {
     private templates;

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-Dw2xXP9B.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BO-i9-nq.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-ChPT7ZDp.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-weh2w7Ji.js';
 
 declare class MemoryAdapter implements IStorageAdapter {
     private templates;

package/dist/adapters/PostgresAdapter.d.cts

@@ -1,7 +1,7 @@
 import * as tls from 'tls';
 import * as pg from 'pg';
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-Pq9J60xv.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BO-i9-nq.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-yX9ERfQE.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-weh2w7Ji.cjs';
 
 interface PostgresAdapterOptions {
     connectionString?: string;

package/dist/adapters/PostgresAdapter.d.ts

@@ -1,7 +1,7 @@
 import * as tls from 'tls';
 import * as pg from 'pg';
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-Dw2xXP9B.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BO-i9-nq.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-ChPT7ZDp.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-weh2w7Ji.js';
 
 interface PostgresAdapterOptions {
     connectionString?: string;

package/dist/index.cjs

@@ -1273,7 +1273,8 @@ var ApprovalEngine = class _ApprovalEngine {
         weights: cfg.weights,
         escalationAfterDays: cfg.escalationAfterDays,
         escalationAfterHours: cfg.escalationAfterHours,
-        escalationDueAt: inFirstGroup ? this.levelEscalationDue(now, cfg) : void 0,
+        escalationStep: 0,
+        escalationDueAt: inFirstGroup ? this.levelEscalationDue(now, cfg, this.firstRungOf(template.escalationSteps)) : void 0,
         subWorkflowTemplate: cfg.subWorkflow?.templateName,
         reminderAfterDays: cfg.reminderAfterDays,
         reminderEveryDays: cfg.reminderEveryDays,
@@ -1330,6 +1331,7 @@ var ApprovalEngine = class _ApprovalEngine {
       slaDeadlineAt,
       templateSnapshot: {
         escalation: template.escalation,
+        escalationSteps: template.escalationSteps,
         slaDeadlineDays: template.slaDeadlineDays,
         slaDeadlineHours: template.slaDeadlineHours,
         allowOverride: template.allowOverride
@@ -2625,6 +2627,7 @@ var ApprovalEngine = class _ApprovalEngine {
       slaDeadlineAt,
       templateSnapshot: {
         escalation: template.escalation,
+        escalationSteps: template.escalationSteps,
         slaDeadlineDays: template.slaDeadlineDays,
         slaDeadlineHours: template.slaDeadlineHours,
         allowOverride: template.allowOverride
@@ -3373,10 +3376,14 @@ var ApprovalEngine = class _ApprovalEngine {
   async escalateInternal(instanceId, escalatedBy = "system", auditCtx, levelNumber) {
     return this.withOptimisticRetry(instanceId, async (instance) => {
       if (instance.status !== "pending") return instance;
-      const escalationConfig = instance.templateSnapshot?.escalation ?? (await this.registry.get(instance.templateName)).escalation;
-      if (!escalationConfig) return instance;
+      const ladder = await this.escalationLadder(instance);
+      const targetLevel = levelNumber === void 0 ? this.currentLevelInstance(instance) : instance.levels.find((l) => l.level === levelNumber) ?? this.currentLevelInstance(instance);
+      const rungIndex = targetLevel.escalationStep ?? 0;
+      const rung = ladder[rungIndex];
+      const escalateTo = rung?.escalateTo ?? (instance.templateSnapshot?.escalation ?? (await this.registry.get(instance.templateName)).escalation)?.escalateTo;
+      if (!escalateTo) return instance;
       const newApprovers = await this.resolver.resolveApprovers(
-        [escalationConfig.escalateTo],
+        [escalateTo],
         instance.submittedBy,
         instance.data,
         this.opts.orgProvider,
@@ -3394,10 +3401,13 @@ var ApprovalEngine = class _ApprovalEngine {
         );
         return instance;
       }
-      const level = levelNumber === void 0 ? this.currentLevelInstance(instance) : instance.levels.find((l) => l.level === levelNumber) ?? this.currentLevelInstance(instance);
+      const level = targetLevel;
       level.approverIds = [.../* @__PURE__ */ new Set([...level.approverIds, ...filteredApprovers])];
-      level.escalationDueAt = void 0;
       const now = this.clock.now();
+      level.escalationStep = rungIndex + 1;
+      const nextRung = ladder[rungIndex + 1];
+      const levelOpenedAt = this.levelOpenedAt(instance, level, now);
+      level.escalationDueAt = nextRung ? this.stepDueAt(levelOpenedAt, nextRung) : void 0;
       const escalatedTo = filteredApprovers[0] ?? "unknown";
       const auditEntry = {
         action: "escalated",
@@ -3582,9 +3592,54 @@ var ApprovalEngine = class _ApprovalEngine {
     return addHours ? addHours(from, hours) : new Date(from.getTime() + hours * 36e5);
   }
   /** Level deadline from whichever of days/hours the template configured. */
-  levelEscalationDue(from, level) {
+  levelEscalationDue(from, level, firstRung) {
     if (level.escalationAfterHours) return this.deadlineFromHours(from, level.escalationAfterHours);
     if (level.escalationAfterDays) return this.deadlineFrom(from, level.escalationAfterDays);
+    return firstRung ? this.stepDueAt(from, firstRung) : void 0;
+  }
+  /** First rung of a ladder, sorted by delay, or undefined when there is none. */
+  firstRungOf(steps) {
+    if (!steps || steps.length === 0) return void 0;
+    return [...steps].sort(
+      (a, b) => (a.afterHours ?? (a.afterDays ?? 0) * 24) - (b.afterHours ?? (b.afterDays ?? 0) * 24)
+    )[0];
+  }
+  /**
+   * The escalation ladder for an instance, sorted by delay.
+   *
+   * Read from the instance's template snapshot so an in-flight approval keeps
+   * the ladder it was submitted under, exactly as the single-step
+   * {@link EscalationConfig} already did.
+   */
+  async escalationLadder(instance) {
+    const snapshot = instance.templateSnapshot;
+    const steps = snapshot?.escalationSteps ?? (await this.registry.get(instance.templateName)).escalationSteps ?? [];
+    return [...steps].sort(
+      (a, b) => (a.afterHours ?? (a.afterDays ?? 0) * 24) - (b.afterHours ?? (b.afterDays ?? 0) * 24)
+    );
+  }
+  /**
+   * When a level started collecting decisions.
+   *
+   * Escalation rungs are measured from this, not from the previous rung, so a
+   * ladder reads the way it is written. Recovered from the audit trail — the
+   * `submitted` entry for the opening level, the `level_advanced` entry
+   * otherwise — and falls back to `now` when no entry exists, which only leaves
+   * the ladder no worse off than the single-step behaviour it replaces.
+   */
+  levelOpenedAt(instance, level, fallback) {
+    for (let i = instance.auditLog.length - 1; i >= 0; i--) {
+      const entry = instance.auditLog[i];
+      if (!entry) continue;
+      const opensThisLevel = (entry.action === "level_advanced" || entry.action === "submitted") && entry.level === level.level;
+      if (opensThisLevel) return new Date(entry.timestamp);
+    }
+    return fallback;
+  }
+  /** Deadline for one rung, measured from when the level opened. */
+  stepDueAt(from, step) {
+    if (step.afterHours) return this.deadlineFromHours(from, step.afterHours);
+    if (step.afterDays) return this.deadlineFrom(from, step.afterDays);
     return void 0;
   }
   async requireInstance(id) {
@@ -3679,6 +3734,7 @@ var ApprovalEngine = class _ApprovalEngine {
   }
   /** Resolve approvers for a group, set its deadlines, and mark it pending. */
   async activateGroup(instance, group, now) {
+    const firstRung = this.firstRungOf(instance.templateSnapshot?.escalationSteps);
     for (const lvl of group) {
       if (lvl.subWorkflowTemplate) {
         lvl.approverIds = [];
@@ -3692,7 +3748,8 @@ var ApprovalEngine = class _ApprovalEngine {
           now
         );
       }
-      lvl.escalationDueAt = this.levelEscalationDue(now, lvl);
+      lvl.escalationDueAt = this.levelEscalationDue(now, lvl, firstRung);
+      lvl.escalationStep = 0;
       this.scheduleReminder(lvl, now);
       lvl.status = "pending";
     }