hierarchical-approval 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,201 @@
 All notable changes to `hierarchical-approval` are documented here. This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+_Nothing yet._
+
+## [0.7.0] - 2026-09-04
+
+### Fixed — two condition-evaluation bypasses
+
+Both of these let a `ConditionRule` fire when it should not have, and because
+conditions decide which levels an instance gets, a spurious match on a
+`skipLevels` rule **removes approval levels from a live document**. Anyone using
+`skipLevels` — or `addLevels` to *escalate* above a threshold — should upgrade.
+
+- **Numeric operators no longer coerce non-numbers to zero.** `>`, `<`, `>=` and
+  `<=` compared with `Number(actual)`, and `Number()` maps `null`, `''`, `'   '`,
+  `[]` and `false` all to `0`. So a fast-track rule like
+  `{ when: { field: 'amount', operator: '<', value: 5000 }, skipLevels: [2, 3] }`
+  matched a purchase order whose `amount` was `null` or blank, silently skipping
+  two approval levels on exactly the documents whose value was unknown. `false`
+  and `[]` did the same, and `true` compared as `1`.
+
+  A numeric comparison against a non-number is now treated as *undecidable* rather
+  than false-y: it reports **no match**, which is the outcome `undefined` has
+  always produced. Accepted operands are finite numbers, bigints, `Date`
+  (compared as epoch milliseconds), and numeric strings such as `'100'` or
+  `' 1e3 '` — ERP payloads routinely arrive as JSON strings, so string comparison
+  is retained. Rejected: `null`, `undefined`, booleans, arrays, objects, blank
+  strings, `NaN` and `Infinity`.
+
+  **Behaviour change.** A rule that was matching on blank or boolean data stops
+  matching. That is the fix, but it does change which levels such an instance
+  gets, so re-check any template whose conditions run against optional fields.
+  `==` and `!=` are untouched — they were already strict.
+
+- **Dot-path field lookup now reads own properties only.** `getField` tested
+  `key in obj`, which walks the prototype chain, so a condition on `isFastTrack`
+  was satisfied by an inherited `Object.prototype.isFastTrack` that no document
+  ever declared — turning any prototype pollution elsewhere in the dependency
+  tree into an approval-level bypass. Resolution now uses
+  `Object.prototype.hasOwnProperty`, so a segment that is not an own property
+  resolves to `undefined` exactly as an absent field does. This also closes
+  `__proto__`, `constructor` and `prototype` as readable paths.
+
+  **Behaviour change.** Context data whose fields live on a prototype (a class
+  instance with getters, rather than a plain object) no longer resolves. Plain
+  objects, arrays, array indices and `Object.create(null)` objects are
+  unaffected, and context data does not survive JSONB round-tripping as a class
+  instance in any case.
+
+### Added
+
+- **`toComparableNumber(value)` is exported from the package root.** The same
+  strict coercion the built-in numeric operators use, returning `number` or
+  `null`, so a custom operator registered with `registerConditionOperator()` can
+  inherit the identical semantics instead of re-introducing `Number()`. The
+  README's `between` recipe now uses it — the previous version of that snippet
+  demonstrated the zero-coercion bug.
+
+### Tests
+
+- Restored the **17 `ConditionEvaluator` unit tests that commit `8d648d8`
+  deleted**, having replaced the suite body with a `// ... existing tests ...`
+  placeholder and a single test. Coverage of the evaluator had silently dropped
+  to 74% of statements and 56% of functions.
+- Added 36 tests across the two fixes (per-type non-comparable operand matrix for
+  each numeric operator, the `skipLevels` bypass scenario, prototype-pollution
+  guards, `toComparableNumber` directly) plus an executable copy of the README's
+  custom-operator recipes, so a documented snippet cannot rot or stop compiling.
+  All 24 of the pre-existing-bug assertions were confirmed to fail against the
+  unfixed source.
+
+## [0.6.0] - 2026-08-21
+
+### Fixed — event delivery, template reads, and the CI lint gate
+
+- **A throwing `engine.on()` listener no longer breaks the operation that emitted
+  the event.** `EventBus` delivered events straight through `eventemitter3`, which
+  invokes listeners synchronously and does not swallow exceptions — and the engine
+  emits *after* persisting but *before* dispatching notifications and running
+  after-middleware. So one buggy subscriber would reject `approve()` with its own
+  error (while the instance stayed persisted as approved), skip notification
+  dispatch entirely, leave a tracing span opened and never ended, and suppress the
+  `approval:completed` emit on the following line. Listener failures are now
+  isolated per listener and reported via the engine's logger; a rejecting `async`
+  listener is caught too, instead of surfacing as a process-level
+  `unhandledRejection`. **Behaviour change:** a listener error no longer propagates
+  to the caller. Register an `onListenerError` sink by passing a `logger`, or use
+  `EventBus.setListenerErrorHandler` directly.
+- **`approval:completed` is now delivered to notification adapters.** It was
+  emitted on the in-process bus only, so a webhook/email integrator never learned
+  a document had been fully approved and had to infer it from `approval:approved`
+  plus `isFinal`. Dispatched on both the normal-completion and `override` paths.
+- **`PostgresAdapter.getTemplate`/`listTemplates` now return `createdAt` as a real
+  `Date`.** They returned the JSONB payload raw, so `createdAt` was an ISO string
+  despite `ApprovalTemplate` typing it as a `Date`. `TemplateRegistry.update()`
+  threaded that string into the next `saveTemplate()`, which called
+  `createdAt.toISOString()` on it — meaning **`engine.updateTemplate()` failed 100%
+  of the time against real PostgreSQL** while passing against `MemoryAdapter`,
+  which tolerates the string silently. No migration needed.
+- **CI enforces lint again.** The workflow ran `npm run lint || true`, so lint could
+  never fail a build; an unused import had already accumulated on `main` as a
+  result. The `|| true` is gone.
+
+### Added — cycle-time analytics
+
+- **`getStatistics()` now reports time-to-decision.** The returned
+  `ApprovalStatistics` gains `cycleTime: CycleTimeStats` and
+  `cycleTimeByTemplate: Record<string, CycleTimeStats>`, each shaped as
+  `{ count, averageMs, p50Ms, p95Ms, minMs, maxMs }` (all durations in
+  milliseconds; new `CycleTimeStats` interface, exported from the package root).
+  - Counts instances in status `approved`, `rejected`, or `cancelled`.
+    **`expired` is deliberately excluded** — its terminal timestamp reflects a
+    scheduler deadline firing, not a decision, so including it would skew the
+    distribution rather than describe it.
+  - Elapsed time per instance is `updatedAt - createdAt`; no new fields were
+    added to `ApprovalInstance` or either storage adapter.
+  - Every field is `0` (never `NaN`) when `count` is `0`. `cycleTimeByTemplate`
+    mirrors `byTemplate`'s population rule: a template only appears once it has
+    at least one completed instance.
+  - Adapter-agnostic — computed from existing `getInstancesByFilter` pages, so
+    `MemoryAdapter` and `PostgresAdapter` both support it with no changes.
+
+### Added — `plugins/webhook`
+
+- **`hierarchical-approval/plugins/webhook`** — a sixth built-in plug-in
+  subpath: an HTTP `INotificationAdapter` with signing and retry, on its own
+  tree-shakeable import path with **zero new dependencies**.
+  - `WebhookNotificationAdapter` POSTs each event as JSON to a configured URL.
+    `notify()` never throws (per the `INotificationAdapter` contract) — it logs
+    and drops the notification once retries are exhausted.
+  - **Signing (opt-in via `secret`).** Each request carries an
+    `X-Approval-Signature: t=<unix-seconds>,v1=<hex-hmac>` header (Stripe-style),
+    the HMAC-SHA256 digest of the signing string `` `<unix-seconds>.<json-body>` ``.
+    Unsigned when `secret` is omitted. `DEFAULT_SIGNATURE_HEADER` names the
+    default header (`'X-Approval-Signature'`); override via `signatureHeader`.
+  - **Retry.** `5xx`, `408`, `429`, and network/timeout errors are retried with
+    exponential backoff and full jitter, up to `maxAttempts` (default `3`); a
+    `429` honors `Retry-After` (seconds or an HTTP date) in place of the
+    computed backoff. Any other `4xx` fails on the first attempt.
+  - **Durability.** The public `deliver()` method throws
+    `WebhookDeliveryError` (`status?`, `attempts`, `cause?`) on final failure
+    instead of swallowing it, so it can be bound as the `transport` of
+    `plugins/notify`'s `OutboxNotificationAdapter` for at-least-once delivery
+    across process restarts — no adapter shim needed.
+  - Ships a new `HttpClient` port (a plain `fetch`-shaped function type) and
+    `getDefaultHttpClient()`. **No new dependency** — the port is structurally
+    satisfied by the global `fetch` (Node.js 18+); pass a custom `httpClient`
+    to use a different implementation.
+
+### Added — `plugins/scheduler`, and the `schedulerAdapter` option now works
+
+- **`hierarchical-approval/plugins/scheduler`** — ships `InMemorySchedulerAdapter`,
+  the first reference implementation of the `ISchedulerAdapter` port, which until
+  now was exported from the package root with no implementation anywhere to copy.
+- **`ApprovalEngineOptions.schedulerAdapter` was a no-op.** It was declared and
+  documented as "Replaces built-in setInterval polling", but `scheduleAt` and
+  `cancel` were never called — an injected BullMQ/Temporal/cron scheduler was
+  silently ignored while the built-in poller kept running. When supplied it now
+  drives the periodic scan via self-rescheduling one-shot calls. Default
+  behaviour with no option supplied is unchanged.
+
+### Fixed — `PostgresAdapter`
+
+Three defects affecting users on published `0.5.0`. If you use `PostgresAdapter`,
+upgrading is recommended.
+
+- **Cursor pagination silently corrupted every page after the first.**
+  `getInstancesByCursor`'s cursor decoder split the `updatedAt_iso:id` string on
+  the _first_ colon, but an ISO-8601 timestamp (e.g.
+  `2026-06-26T09:00:00.000Z`) itself contains colons — so every decoded cursor
+  had a truncated timestamp and a corrupted id, breaking every subsequent page
+  fetch via `getInstancesByCursor`. Also hardened cursor encoding to normalize
+  through `Date.prototype.toISOString()` regardless of the row value's shape.
+  No migration needed.
+- **`templateId` was silently dropped on every write and always read back as
+  `''`.** `PostgresAdapter` had no `template_id` column, so
+  `ApprovalInstance.templateId` was permanently lost for any instance persisted
+  through this adapter. Fixed by adding a `template_id` column and including it
+  in both the insert and read paths.
+  **Action required on upgrade:** run the adapter's migration (its
+  `CREATE TABLE`/`ALTER TABLE ... ADD COLUMN IF NOT EXISTS` statements, executed
+  automatically the next time the adapter initializes) to add the new column —
+  existing rows backfill to `''` until rewritten.
+- **The `schema` option was interpolated into SQL without the safe-identifier
+  validation `tablePrefix` already had**, an inconsistent injection surface at
+  construction time. `schema` is now validated against the same
+  `/^[a-z][a-z0-9_]*$/` pattern as `tablePrefix`, throwing
+  `ApprovalValidationError` on an invalid value. No migration needed; only
+  affects adapter construction with an attacker-controlled `schema` value.
+
+### Fixed — `MemoryAdapter` and notifications
+
+- **`TemplatedNotificationAdapter`** — now logs fatal events (notification render/send failures) at the `fatal` level instead of `error`.
+- **`MemoryAdapter`** — `getInstancesByFilter` now honors `fromDate`/`toDate` (previously the JSON-cloned string dates made the comparison a no-op and both bounds silently matched nothing). `getTemplate`/`listTemplates` now return `createdAt` as a real `Date`, matching the `ApprovalTemplate` contract.
+
 ## [0.5.0] - 2026-07-23
 
 ### Added — NestJS integration

package/README.md

@@ -305,6 +305,33 @@ conditions: [
 
 **Built-in operators:** `>`, `<`, `>=`, `<=`, `==`, `!=`, `in`, `not_in`
 
+#### How values are compared
+
+`==` and `!=` compare **strictly** — `'100'` does not equal `100`.
+
+The numeric operators (`>`, `<`, `>=`, `<=`) match only when **both** sides are
+unambiguously numeric: finite numbers, bigints, `Date` (compared as epoch
+milliseconds), and numeric strings such as `'100'` or `' 1e3 '` — because ERP
+payloads routinely arrive as JSON strings. Anything else — `null`, `undefined`,
+`true`/`false`, arrays, objects, blank strings, `NaN`, `Infinity` — is treated as
+*not comparable*, and the condition reports **no match**.
+
+This matters for safety. A rule that skips levels on small amounts must not fire
+on a document whose amount was never populated:
+
+```ts
+{ when: { field: 'amount', operator: '<', value: 5000 }, skipLevels: [2, 3] }
+
+// amount: 4999  -> matches, levels 2 and 3 are skipped
+// amount: null  -> NO match, every level is kept
+// amount: ''    -> NO match, every level is kept
+```
+
+Field paths resolve **own properties only**, so an inherited or polluted
+`Object.prototype` member can never satisfy a condition. A path segment that is
+not an own property — including `__proto__`, `constructor`, and `prototype` —
+resolves to `undefined`, exactly as a genuinely absent field does.
+
 **Register custom operators** at engine level:
 
 ```ts
@@ -312,11 +339,23 @@ engine.registerConditionOperator(
   'contains',
   (actual, expected) => typeof actual === 'string' && actual.includes(String(expected)),
 );
+```
 
-engine.registerConditionOperator(
-  'between',
-  (actual, [min, max]: number[]) => Number(actual) >= min && Number(actual) <= max,
-);
+Custom numeric operators should reuse the same strictness via the exported
+`toComparableNumber` helper, which returns `null` for anything that is not
+unambiguously a number:
+
+```ts
+import { toComparableNumber } from 'hierarchical-approval';
+
+engine.registerConditionOperator('between', (actual, expected) => {
+  const value = toComparableNumber(actual);
+  if (value === null || !Array.isArray(expected) || expected.length !== 2) return false;
+  const min = toComparableNumber(expected[0]);
+  const max = toComparableNumber(expected[1]);
+  if (min === null || max === null) return false;
+  return value >= min && value <= max;
+});
 ```
 
 ---
@@ -721,9 +760,27 @@ const stats = await engine.getStatistics({ documentType: 'purchase_order' });
 //   byStatus: { pending, approved, rejected, cancelled, expired },
 //   overdue: number,        // pending past an escalation/expiry deadline
 //   approvalRate: number,   // approved / (approved + rejected); 0 when none resolved
+//   byTemplate: Record<string, { total, approved, rejected, pending }>,
+//   cycleTime: CycleTimeStats,
+//   cycleTimeByTemplate: Record<string, CycleTimeStats>,
 // }
 ```
 
+`byTemplate` breaks the same counts down per template name (only populated for templates with at least one matching instance).
+
+**Cycle-time analytics.** `cycleTime` (and its per-template mirror `cycleTimeByTemplate`) reports time-to-decision, in milliseconds, as `{ count, averageMs, p50Ms, p95Ms, minMs, maxMs }`:
+
+```ts
+console.log(`Median time-to-decision: ${(stats.cycleTime.p50Ms / 60_000).toFixed(1)} min`);
+console.log(`p95 over ${stats.cycleTime.count} completed instances: ${stats.cycleTime.p95Ms}ms`);
+
+for (const [templateName, timing] of Object.entries(stats.cycleTimeByTemplate)) {
+  console.log(templateName, timing.averageMs);
+}
+```
+
+Only instances in status `approved`, `rejected`, or `cancelled` count as "completed" for this calculation — **`expired` is deliberately excluded**: its terminal timestamp reflects a scheduler deadline firing, not a decision being made, so including it would skew the distribution rather than describe it. Elapsed time per instance is `updatedAt - createdAt`. When `count` is `0` every other field is `0`, never `NaN`.
+
 ### Health check
 
 ```ts
@@ -1072,6 +1129,54 @@ const engine = new ApprovalEngine({
 
 Every operation is wrapped in a span named `approval.<operation>` (e.g. `approval.approve`) carrying `approval.tenant_id`, `approval.actor_id` and `approval.instance_id` attributes. On success the span records the resulting `approval.result_status`/`approval.result_level` and status `OK`; on failure it calls `recordException`, tags `approval.error_code`, and sets status `ERROR` — then re-throws (tracing never swallows an error). There is **no hard dependency** on `@opentelemetry/api`: the middleware defaults to a no-op tracer, so you install and wire OpenTelemetry only if you want traces.
 
+### `plugins/webhook` — signed HTTP delivery with retries
+
+```ts
+import { WebhookNotificationAdapter } from 'hierarchical-approval/plugins/webhook';
+
+const webhook = new WebhookNotificationAdapter({
+  url: 'https://example.com/hooks/approvals',
+  secret: process.env.WEBHOOK_SECRET, // opt-in signing; omit to send unsigned requests
+});
+
+const engine = new ApprovalEngine({ adapter, notificationAdapter: webhook });
+```
+
+Every event is POSTed to `url` as JSON. When `secret` is configured, each request also carries an `X-Approval-Signature: t=<unix-seconds>,v1=<hex-hmac>` header (Stripe-style), where `v1` is the HMAC-SHA256 digest of the signing string `` `${timestamp}.${body}` ``. Folding the timestamp into the signed payload lets a receiver reject stale/replayed requests. A receiver verifies it like this:
+
+```ts
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+function verifyApprovalSignature(rawBody: string, header: string, secret: string): boolean {
+  const [tPart, vPart] = header.split(',');
+  const timestamp = tPart!.slice(2); // strip "t="
+  const signature = vPart!.slice(3); // strip "v1="
+  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
+  const sigBuf = Buffer.from(signature, 'hex');
+  const expBuf = Buffer.from(expected, 'hex');
+  return sigBuf.length === expBuf.length && timingSafeEqual(sigBuf, expBuf);
+}
+```
+
+`5xx` responses, `408`, and `429`, plus network/timeout errors, are retried with exponential backoff and full jitter up to `maxAttempts` (default `3`); a `429` honors a `Retry-After` header (seconds or an HTTP date) in place of the computed backoff. Any other `4xx` (e.g. `400`, `401`, `404`) is treated as permanent and fails on the first attempt. `notify()` — the method the engine calls — never throws, per the `INotificationAdapter` contract: on exhausting `maxAttempts` it logs and drops the notification, which makes the adapter used alone _at-most-once_.
+
+For at-least-once delivery that survives a process restart, compose the adapter's throwing `deliver()` method as the `transport` of `OutboxNotificationAdapter` instead of wiring `notify()` directly:
+
+```ts
+import { OutboxNotificationAdapter } from 'hierarchical-approval/plugins/notify';
+import { WebhookNotificationAdapter } from 'hierarchical-approval/plugins/webhook';
+
+const webhook = new WebhookNotificationAdapter({
+  url: 'https://example.com/hooks/approvals',
+  secret,
+});
+const durable = new OutboxNotificationAdapter({ transport: webhook.deliver.bind(webhook) });
+
+const engine = new ApprovalEngine({ adapter, notificationAdapter: durable });
+```
+
+`deliver` and `OutboxNotificationAdapter`'s `NotificationTransport` type are structurally compatible, so this composition needs no adapter shim. This adapter takes **no new dependency**: its `HttpClient` port is a plain `fetch`-shaped function, and the global `fetch` (Node.js 18+) satisfies it directly — pass a custom `httpClient` in the options only if you need different behavior (a proxy, request mocking, a different runtime's fetch).
+
 ---
 
 ## NestJS integration

package/dist/{ApprovalEngine-mkh6D9n9.d.cts → ApprovalEngine-BET-UqQo.d.cts}

@@ -1,12 +1,13 @@
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-ClBdEeTj.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-BibHlgPw.cjs';
 import { m as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-D8D7b07N.cjs';
 import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-DVVmXU6a.cjs';
 import { z } from 'zod';
-import { L as Logger } from './Logger-CIzvalFc.cjs';
+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-CXgXmGUF.cjs';
 import { I as IAuditAdapter } from './IAuditAdapter-B_DhuPsU.cjs';
 import { I as IMetricsAdapter } from './IMetricsAdapter-D9PUz4tM.cjs';
+import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
 import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-B6JzRNUk.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
@@ -107,7 +108,8 @@ interface WeekendCalendarOptions {
  */
 declare function weekendCalendar(options?: WeekendCalendarOptions): BusinessCalendar;
 
-type IdGeneratorFn = (prefix: 'inst' | 'tpl') => string;
+type IdGeneratorPrefix = 'inst' | 'tpl';
+type IdGeneratorFn = (prefix: IdGeneratorPrefix) => string;
 declare const defaultIdGenerator: IdGeneratorFn;
 
 interface OrgProvider {
@@ -128,18 +130,26 @@ type ApproverResolverFn = (config: Record<string, unknown>, ctx: {
 }) => Promise<string[]> | string[];
 
 type ConditionOperatorFn = (actual: unknown, expected: unknown) => boolean;
-
-interface ISchedulerAdapter {
-    /**
-     * Schedule a one-shot callback to run at the given date.
-     * Returns an opaque handle that can be passed to cancel().
-     */
-    scheduleAt(id: string, runAt: Date, callback: () => Promise<void>): Promise<string>;
-    /** Cancel a previously scheduled callback by its handle. */
-    cancel(handle: string): Promise<void>;
-    /** Gracefully shut down the scheduler and release resources. */
-    shutdown(): Promise<void>;
-}
+/**
+ * Coerce a value to a number *only* when it unambiguously represents one.
+ *
+ * Plain `Number()` maps `null`, `''`, `'   '`, `[]` and `false` all to `0`, which
+ * in an approval engine is an approval-bypass hazard: a rule such as
+ * `{ amount: '<' 5000 } -> skipLevels: [2, 3]` would fire on a document whose
+ * `amount` is missing or blank, silently skipping two approval levels. Numeric
+ * comparison against a value that is not a number is not "false-y", it is
+ * *undecidable*, so this returns `null` and the comparison reports no match —
+ * the same outcome `undefined` has always produced.
+ *
+ * Accepted: finite numbers, bigints, `Date` (compared as epoch ms), and numeric
+ * strings such as `'100'` or `' 1e3 '` (ERP payloads routinely arrive as JSON
+ * strings). Rejected: `null`, `undefined`, booleans, arrays, objects, blank
+ * strings, and the non-finite `NaN` / `Infinity`.
+ *
+ * @param value - The raw value taken from the condition or the context data.
+ * @returns The numeric value, or `null` when the value is not comparable.
+ */
+declare function toComparableNumber(value: unknown): number | null;
 
 interface ValidationResult {
     valid: boolean;
@@ -192,6 +202,49 @@ interface ApprovalStatistics {
         rejected: number;
         pending: number;
     }>;
+    /**
+     * Time-to-decision ("cycle time") analytics, in milliseconds, for
+     * **completed** instances matching the filter — status `'approved'`,
+     * `'rejected'`, or `'cancelled'`. `'expired'` instances are excluded: their
+     * terminal timestamp reflects a scheduler deadline firing, not a decision
+     * being made, so they would skew the distribution rather than describe it.
+     *
+     * Elapsed time per instance is `updatedAt - createdAt`: `createdAt` is the
+     * submission instant, and `updatedAt` is set at the moment the instance
+     * transitions to its terminal status (see {@link ApprovalEngine.approve},
+     * {@link ApprovalEngine.reject}, {@link ApprovalEngine.cancel}). See
+     * {@link CycleTimeStats} for the zeroed shape returned when there are no
+     * completed instances.
+     */
+    cycleTime: CycleTimeStats;
+    /**
+     * The same {@link cycleTime} analytics broken down per template name.
+     * Mirrors the {@link byTemplate} population rule: a template only appears
+     * here when at least one of its instances is completed (`count > 0`).
+     */
+    cycleTimeByTemplate: Record<string, CycleTimeStats>;
+}
+/**
+ * Time-to-decision ("cycle time") statistics for a set of completed approval
+ * instances. All duration fields are in **milliseconds**.
+ *
+ * When {@link count} is `0` (no completed instances matched), every other
+ * field is `0` — never `NaN` — mirroring {@link computeTimingStats}'s
+ * empty-input behavior, which this type's values are derived from.
+ */
+interface CycleTimeStats {
+    /** Number of completed instances included in this computation. */
+    count: number;
+    /** Arithmetic mean time-to-decision. `0` when {@link count} is `0`. */
+    averageMs: number;
+    /** 50th percentile (median) time-to-decision, via nearest-rank. `0` when {@link count} is `0`. */
+    p50Ms: number;
+    /** 95th percentile time-to-decision, via nearest-rank. `0` when {@link count} is `0`. */
+    p95Ms: number;
+    /** Smallest observed time-to-decision. `0` when {@link count} is `0`. */
+    minMs: number;
+    /** Largest observed time-to-decision. `0` when {@link count} is `0`. */
+    maxMs: number;
 }
 interface HealthResult {
     status: 'healthy' | 'degraded' | 'unhealthy';
@@ -225,7 +278,7 @@ interface ApprovalEngineOptions {
      */
     calendar?: BusinessCalendar;
     /** Custom ID generator for instances and templates. Defaults to timestamp+random. */
-    generateId?: IdGeneratorFn;
+    generateId?: (prefix: IdGeneratorPrefix) => string;
     /** Custom optimistic locking retry policy. */
     retryPolicy?: RetryPolicy;
     /** Custom idempotency key derivation function. Default: SHA-256 of tenant+documentType+documentId+templateName. */
@@ -236,7 +289,20 @@ interface ApprovalEngineOptions {
     auditAdapter?: IAuditAdapter;
     /** Metrics adapter for Prometheus / Datadog / OpenTelemetry. */
     metricsAdapter?: IMetricsAdapter;
-    /** Custom scheduler adapter (BullMQ, Temporal, cron). Replaces built-in setInterval polling. */
+    /**
+     * Custom scheduler adapter (BullMQ, Temporal, cron) that drives the recurring
+     * escalation/expiry/SLA-breach/delegation-revert scan.
+     *
+     * When provided, the built-in `setInterval` poll (see
+     * {@link EscalationScheduler.start}) is never started. Instead,
+     * {@link ISchedulerAdapter.scheduleAt} schedules each scan, and its callback
+     * reschedules the next one itself once the scan completes — the adapter
+     * changes *how* the periodic scan is triggered, not *what* it scans; every
+     * tick still runs the exact same overdue-instance query the built-in poller
+     * runs. {@link ISchedulerAdapter.cancel} and {@link ISchedulerAdapter.shutdown}
+     * are invoked during {@link ApprovalEngine.shutdown}. Omitting this option
+     * preserves the built-in `setInterval` polling behavior unchanged.
+     */
     schedulerAdapter?: ISchedulerAdapter;
     /** Authorization policy called before every mutating operation. */
     authorizationPolicy?: IAuthorizationPolicy;
@@ -249,6 +315,7 @@ declare class ApprovalEngine {
     private readonly registry;
     private readonly resolver;
     private readonly escalation;
+    private readonly escalationPollIntervalMs;
     private readonly tenantId;
     private readonly logger;
     private readonly clock;
@@ -257,6 +324,10 @@ declare class ApprovalEngine {
     private readonly maxBulkItems;
     private readonly retryPolicy;
     private readonly idempotencyKeyFn;
+    /** Handle for the currently-scheduled escalation tick when {@link ApprovalEngineOptions.schedulerAdapter} is set. */
+    private schedulerAdapterHandle;
+    /** Set by {@link shutdown}; stops the self-rescheduling loop from scheduling another tick. */
+    private schedulerStopped;
     constructor(opts: ApprovalEngineOptions);
     on<K extends ApprovalEventName>(event: K, listener: (payload: ApprovalEventMap[K]) => void): this;
     off<K extends ApprovalEventName>(event: K, listener: (payload: ApprovalEventMap[K]) => void): this;
@@ -313,6 +384,37 @@ declare class ApprovalEngine {
      */
     getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
     shutdown(): Promise<void>;
+    /**
+     * Schedules the next escalation scan via {@link ApprovalEngineOptions.schedulerAdapter}.
+     *
+     * Called once from the constructor to start the loop, then re-invoked by the
+     * scheduled callback itself after each scan completes — a self-rescheduling
+     * chain of one-shot {@link ISchedulerAdapter.scheduleAt} calls standing in for
+     * the `setInterval` that {@link EscalationScheduler.start} would otherwise
+     * use. Each invocation runs the exact same {@link EscalationScheduler.tick}
+     * scan the built-in poller runs; only the timer mechanism differs.
+     *
+     * A no-op once {@link shutdown} has set {@link schedulerStopped} — this is
+     * what stops the chain from rescheduling itself forever after teardown.
+     */
+    private scheduleNextEscalationTick;
+    /**
+     * Compute {@link CycleTimeStats} for every "completed" instance (see
+     * {@link CYCLE_TIME_STATUSES}) matching `filter`. Adapter-agnostic: fetches
+     * full instances (not just counts) via {@link fetchAllByFilter} so the
+     * actual `createdAt`/`updatedAt` timestamps are available, then reuses the
+     * shared {@link computeTimingStats} quantile routine from the metrics
+     * plugin rather than a second implementation.
+     */
+    private computeCycleTimeStats;
+    /**
+     * Page through every instance matching `filter` via the adapter's
+     * `getInstancesByFilter`, accumulating pages until the adapter reports no
+     * more results. Needed because adapters may impose a default page size
+     * (e.g. `PostgresAdapter` defaults to 50) when no explicit `limit` is given,
+     * so a single unbounded call cannot be relied on to return everything.
+     */
+    private fetchAllByFilter;
     private escalateInternal;
     private expireInstance;
     private markSlaBreached;
@@ -333,4 +435,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 ISchedulerAdapter as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, 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 IdGeneratorFn as i, type IdempotencyKeyFn as j, type OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, 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 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 OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, toComparableNumber as t, weekendCalendar as w };