hierarchical-approval 2.7.0 → 2.9.0

package/CHANGELOG.md

@@ -7,6 +7,86 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [2.9.0] - 2026-09-04
+
+### Added — `simulate()`
+
+- **Dry-runs a document through a template against scripted decisions.**
+  `explainChain()` (2.7.0) says what the chain will be; nothing said what
+  happens *to* it. Answering "if the CFO rejects at level 3, does it go back to
+  the submitter or die?" meant submitting a real approval into real storage and
+  cleaning it up afterwards, or reasoning about the state machine by hand.
+
+  ```ts
+  await engine.simulate({
+    templateName: 'purchase-order',
+    data: { amount: 20000 },
+    submittedBy: 'buyer-1',
+    decisions: [{ approve: 'mgr-1' }, { reject: 'cfo', reason: 'over budget' }],
+  });
+  // { finalStatus, levels, transcript, unreachedLevels, incomplete }
+  ```
+
+- **Nothing escapes the simulation.** It runs against a private in-memory store
+  seeded with a copy of the template, with the notification, audit and metrics
+  adapters and the authorization policy detached — so a dry run cannot page an
+  approver, write somebody's audit log, or move a counter.
+
+- **Custom resolvers and approver types are copied across.** A simulation that
+  could not resolve the caller's own `dynamic` approvers would answer a
+  different question from the one asked.
+
+- **A refused decision stops the run and is reported, not thrown** — wrong
+  approver, wrong level, already acted. The refusal is usually the answer the
+  caller was looking for, and throwing would discard the transcript that
+  explains how the run got there.
+
+  New exports: `SimulationResult`, `SimulationStep`, `SimulatedDecision`.
+
+## [2.8.0] - 2026-09-04
+
+### Added — comment threads
+
+- **Comments are addressable objects rather than audit entries alone.** There
+  was no id to point at, so no way to reply to a comment, and no way to tell
+  somebody a remark was aimed at them — discussion moved to email, where the
+  approval record could not see it.
+
+  ```ts
+  await engine.addComment(id, { actorId: 'mgr-1', comment: 'Need the quote.' });
+  const [question] = await engine.getComments(id);
+  await engine.addComment(id, {
+    actorId: 'buyer-1',
+    comment: 'Attached now.',
+    parentCommentId: question.id,
+    mentions: ['mgr-1'],
+  });
+  ```
+
+- **`approval:commented` is addressed to the people the comment mentions**, not
+  to the current approvers. A remark aimed at somebody should reach them, and
+  one aimed at nobody should not page the whole level.
+
+- **`getComments()` returns a flat list carrying `parentCommentId`**, oldest
+  first, rather than a nested tree: a UI that wants threads can build them, and
+  one that wants a chronological feed does not have to flatten a structure it
+  never wanted. Replying to a comment that is not on the approval is rejected.
+
+  Comments are still written to the audit trail — the record of who said what
+  belongs there. `addComment()` keeps its `Promise<void>` signature, so nothing
+  calling it needs to change.
+
+  New exports: `Comment`, `CommentedEvent`. `ApprovalInstance` gains `comments`.
+
+### Fixed — MemoryAdapter left some timestamps as strings
+
+- **`attachments[].addedAt`, `infoRequest.askedAt` and `levels[].reminderDueAt`
+  read back as strings, not `Date`s.** `MemoryAdapter` clones through JSON and
+  revives date fields by an explicit list, which these were missing from —
+  while `PostgresAdapter` revived them correctly. The two adapters therefore
+  disagreed, and any code trusting the declared `Date` type broke under one of
+  them only. Affected `addedAt` since 1.7.0 and `askedAt` since 1.5.0.
+
 ## [2.7.0] - 2026-09-04
 
 ### Added — `explainChain()`

package/README.md

@@ -468,6 +468,62 @@ 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.
 
+### Comment threads
+
+Comments are addressable objects, so approvers can reply to each other and name
+the person a remark is aimed at:
+
+```ts
+await engine.addComment(id, { actorId: 'mgr-1', comment: 'Need the quote.' });
+const [question] = await engine.getComments(id);
+
+await engine.addComment(id, {
+  actorId: 'buyer-1',
+  comment: 'Attached now, @mgr-1.',
+  parentCommentId: question.id,
+  mentions: ['mgr-1'],
+});
+```
+
+`getComments()` returns a flat list carrying `parentCommentId`, oldest first — a
+UI that wants threads can build them, and one that wants a chronological feed
+(what most approval screens show) does not have to flatten a structure it never
+wanted.
+
+`approval:commented` is addressed to the people the comment **mentions**, not to
+the current approvers: a remark aimed at somebody should reach them, and one
+aimed at nobody should not page the whole level. Comments are still written to
+the audit trail, since the record of who said what belongs there.
+
+### Dry-running a workflow
+
+`explainChain()` says what the chain will be; `simulate()` says what happens to
+it — "if the CFO rejects at level 3, does it go back to the submitter or die?":
+
+```ts
+const result = await engine.simulate({
+  templateName: 'purchase-order',
+  data: { amount: 20000 },
+  submittedBy: 'buyer-1',
+  decisions: [
+    { approve: 'mgr-1' },
+    { approve: 'fin-1' },
+    { reject: 'cfo', reason: 'over budget' },
+  ],
+});
+// { finalStatus: 'rejected', levels: [...], transcript: [...], unreachedLevels: [], incomplete: false }
+```
+
+The run executes against a **private in-memory store** seeded with a copy of the
+template, so your storage is untouched and no events reach your notification
+adapters. Custom resolvers and approver types are copied across — a simulation
+that couldn't resolve your own `dynamic` approvers would answer a different
+question from the one you asked.
+
+A refused decision (wrong approver, wrong level, already acted) stops the run
+and appears in the transcript with its reason rather than throwing: the refusal
+is usually the answer you were looking for.
+
 ### Why does this chain look like this?
 
 `previewApprovalChain()` answers *what* the chain will be. `explainChain()`

package/dist/{ApprovalEngine-DkQcLaeT.d.ts → ApprovalEngine-B3PVWw05.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-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 { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-C2QxUwbX.js';
+import { m as ConditionExpression, r as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, C as Comment, e as ApprovalMode, f as ApprovalStatus, L as LevelStatus, b as AuditEntry } from './instance-BvOyT00S.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-DMvA4R-c.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-CXtg2wzF.js';
-import { I as IAuditAdapter } from './IAuditAdapter-DSor54iY.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-Nk8Q1Z8o.js';
+import { I as IAuditAdapter } from './IAuditAdapter-B33n15YP.js';
 import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BOWg-3AH.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-DOm6KCwI.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -66,6 +66,8 @@ declare const ResubmitOptionsSchema: z.ZodObject<{
 declare const AddCommentOptionsSchema: z.ZodObject<{
     actorId: z.ZodString;
     comment: z.ZodString;
+    parentCommentId: z.ZodOptional<z.ZodString>;
+    mentions: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 declare const OverrideOptionsSchema: z.ZodObject<{
     overriddenBy: z.ZodString;
@@ -199,7 +201,7 @@ interface BusinessHoursCalendarOptions extends WeekendCalendarOptions {
  */
 declare function businessHoursCalendar(options?: BusinessHoursCalendarOptions): Required<Pick<BusinessCalendar, 'addBusinessDays' | 'addBusinessHours'>>;
 
-type IdGeneratorPrefix = 'inst' | 'tpl' | 'att';
+type IdGeneratorPrefix = 'inst' | 'tpl' | 'att' | 'cmt';
 type IdGeneratorFn = (prefix: IdGeneratorPrefix) => string;
 declare const defaultIdGenerator: IdGeneratorFn;
 
@@ -345,6 +347,45 @@ interface ChainExplanation {
     skipped: ExplainedSkip[];
     rules: ExplainedRule[];
 }
+/** One scripted decision in a {@link ApprovalEngine.simulate} run. */
+type SimulatedDecision = {
+    approve: string;
+    level?: number;
+    comment?: string;
+} | {
+    reject: string;
+    level?: number;
+    reason?: string;
+};
+/** What one scripted decision did. */
+interface SimulationStep {
+    /** 1-based position in the script. */
+    step: number;
+    action: 'approve' | 'reject';
+    actorId: string;
+    /** The level the decision landed on, when it was accepted. */
+    level?: number;
+    /** Instance status after the decision. */
+    status: ApprovalStatus;
+    /** Why the decision was refused, when it was. The run stops at the first refusal. */
+    error?: string;
+}
+/** Outcome of a {@link ApprovalEngine.simulate} run. */
+interface SimulationResult {
+    finalStatus: ApprovalStatus;
+    /** The chain the document would get, in order. */
+    levels: Array<{
+        level: number;
+        name: string;
+        status: LevelStatus;
+        approvers: string[];
+    }>;
+    transcript: SimulationStep[];
+    /** Levels never reached because the run ended first. */
+    unreachedLevels: number[];
+    /** True when the script ran out before the approval finished. */
+    incomplete: boolean;
+}
 interface BulkResult {
     succeeded: ApprovalInstance[];
     failed: Array<{
@@ -718,6 +759,15 @@ declare class ApprovalEngine {
     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>;
+    /**
+     * Comments on an approval, oldest first.
+     *
+     * Returns a flat list carrying `parentCommentId`, rather than a nested tree:
+     * a UI that wants threads can build them, and one that wants a chronological
+     * feed — which is what most approval screens actually show — does not have to
+     * flatten a structure it never wanted.
+     */
+    getComments(instanceId: string): Promise<Comment[]>;
     /** Resubmit a rejected instance, creating a new linked instance from level 1. */
     resubmit(instanceId: string, raw: ResubmitOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /** Preview the resolved approval chain for a template and document data, without creating an instance. */
@@ -745,6 +795,33 @@ declare class ApprovalEngine {
      * @param submittedBy - Submitter, used for approver resolution.
      */
     explainChain(templateName: string, data: Record<string, unknown>, submittedBy: string): Promise<ChainExplanation>;
+    /**
+     * Run a document through a template against scripted decisions, without
+     * persisting anything.
+     *
+     * `explainChain()` says what the chain will be; this says what happens to it —
+     * "if the CFO rejects at level 3, does it go back to the submitter or die?" —
+     * which previously meant submitting a real approval into a real store and
+     * cleaning it up afterwards, or reasoning about the state machine by hand.
+     *
+     * The run executes against a private in-memory store seeded with a copy of
+     * the template, so the caller's storage is untouched and no events reach the
+     * caller's notification adapters. Custom resolvers and approver types are
+     * copied across, because a simulation that could not resolve the caller's own
+     * `dynamic` approvers would answer a different question from the one asked.
+     *
+     * A refused decision — wrong approver, wrong level, already acted — stops the
+     * run and is reported in the transcript rather than thrown: the refusal is
+     * usually the answer the caller was looking for.
+     *
+     * @param opts - Template, document data, submitter and the decisions to play.
+     */
+    simulate(opts: {
+        templateName: string;
+        data: Record<string, unknown>;
+        submittedBy: string;
+        decisions?: SimulatedDecision[];
+    }): Promise<SimulationResult>;
     canApprove(instanceId: string, userId: string): Promise<CanApproveResult>;
     /** Emergency bypass — completes the instance as 'approved', skipping remaining levels. Requires template.allowOverride = true. */
     override(instanceId: string, raw: OverrideOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
@@ -1032,4 +1109,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 TemplateBundle as F, type TransferResult as G, type HealthResult as H, type IdGeneratorFn as I, businessHoursCalendar as J, defaultIdGenerator as K, toComparableNumber as L, validateConditionExpression as M, weekendCalendar as N, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, TEMPLATE_BUNDLE_VERSION 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 BusinessHoursCalendarOptions as h, type CancelOptions as i, type ChainExplanation as j, type ConditionOperatorFn as k, type CycleTimeStats as l, type ExplainedLevel as m, type ExplainedRule as n, type ExplainedSkip as o, type IdempotencyKeyFn as p, type ImportResult as q, type OutOfOfficeProvider as r, type OverrideOptions as s, type PreviewResult as t, type ProvideInfoOptions as u, type PurgeResult as v, type RejectOptions as w, type RequestInfoOptions as x, type ResubmitOptions as y, type RetryPolicy as z };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type SimulationResult as F, type SimulationStep as G, type HealthResult as H, type IdGeneratorFn as I, type SubmitOptions as J, type TemplateBundle as K, type TransferResult as L, businessHoursCalendar as M, defaultIdGenerator as N, type OrgProvider as O, type PreviewChainLevel as P, toComparableNumber as Q, type ReassignOptions as R, type SimulatedDecision as S, TEMPLATE_BUNDLE_VERSION as T, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, validateConditionExpression as X, weekendCalendar as Y, 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 BusinessHoursCalendarOptions as h, type CancelOptions as i, type ChainExplanation as j, type ConditionOperatorFn as k, type CycleTimeStats as l, type ExplainedLevel as m, type ExplainedRule as n, type ExplainedSkip as o, type IdempotencyKeyFn as p, type ImportResult as q, type OutOfOfficeProvider as r, type OverrideOptions as s, type PreviewResult as t, type ProvideInfoOptions as u, type PurgeResult as v, type RejectOptions as w, type RequestInfoOptions as x, type ResubmitOptions as y, type RetryPolicy as z };

package/dist/{ApprovalEngine-BH9GvzMI.d.cts → ApprovalEngine-DMM55f5R.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-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 { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-C0qeZgs4.cjs';
+import { m as ConditionExpression, r as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, C as Comment, e as ApprovalMode, f as ApprovalStatus, L as LevelStatus, b as AuditEntry } from './instance-BvOyT00S.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-DFKvGpOp.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-CxnPzpqL.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-2UU5edKG.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-C8i06wq4.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-DxdK4UVt.cjs';
 import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-DPpiKzyh.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BzGVzkLJ.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -66,6 +66,8 @@ declare const ResubmitOptionsSchema: z.ZodObject<{
 declare const AddCommentOptionsSchema: z.ZodObject<{
     actorId: z.ZodString;
     comment: z.ZodString;
+    parentCommentId: z.ZodOptional<z.ZodString>;
+    mentions: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 declare const OverrideOptionsSchema: z.ZodObject<{
     overriddenBy: z.ZodString;
@@ -199,7 +201,7 @@ interface BusinessHoursCalendarOptions extends WeekendCalendarOptions {
  */
 declare function businessHoursCalendar(options?: BusinessHoursCalendarOptions): Required<Pick<BusinessCalendar, 'addBusinessDays' | 'addBusinessHours'>>;
 
-type IdGeneratorPrefix = 'inst' | 'tpl' | 'att';
+type IdGeneratorPrefix = 'inst' | 'tpl' | 'att' | 'cmt';
 type IdGeneratorFn = (prefix: IdGeneratorPrefix) => string;
 declare const defaultIdGenerator: IdGeneratorFn;
 
@@ -345,6 +347,45 @@ interface ChainExplanation {
     skipped: ExplainedSkip[];
     rules: ExplainedRule[];
 }
+/** One scripted decision in a {@link ApprovalEngine.simulate} run. */
+type SimulatedDecision = {
+    approve: string;
+    level?: number;
+    comment?: string;
+} | {
+    reject: string;
+    level?: number;
+    reason?: string;
+};
+/** What one scripted decision did. */
+interface SimulationStep {
+    /** 1-based position in the script. */
+    step: number;
+    action: 'approve' | 'reject';
+    actorId: string;
+    /** The level the decision landed on, when it was accepted. */
+    level?: number;
+    /** Instance status after the decision. */
+    status: ApprovalStatus;
+    /** Why the decision was refused, when it was. The run stops at the first refusal. */
+    error?: string;
+}
+/** Outcome of a {@link ApprovalEngine.simulate} run. */
+interface SimulationResult {
+    finalStatus: ApprovalStatus;
+    /** The chain the document would get, in order. */
+    levels: Array<{
+        level: number;
+        name: string;
+        status: LevelStatus;
+        approvers: string[];
+    }>;
+    transcript: SimulationStep[];
+    /** Levels never reached because the run ended first. */
+    unreachedLevels: number[];
+    /** True when the script ran out before the approval finished. */
+    incomplete: boolean;
+}
 interface BulkResult {
     succeeded: ApprovalInstance[];
     failed: Array<{
@@ -718,6 +759,15 @@ declare class ApprovalEngine {
     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>;
+    /**
+     * Comments on an approval, oldest first.
+     *
+     * Returns a flat list carrying `parentCommentId`, rather than a nested tree:
+     * a UI that wants threads can build them, and one that wants a chronological
+     * feed — which is what most approval screens actually show — does not have to
+     * flatten a structure it never wanted.
+     */
+    getComments(instanceId: string): Promise<Comment[]>;
     /** Resubmit a rejected instance, creating a new linked instance from level 1. */
     resubmit(instanceId: string, raw: ResubmitOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
     /** Preview the resolved approval chain for a template and document data, without creating an instance. */
@@ -745,6 +795,33 @@ declare class ApprovalEngine {
      * @param submittedBy - Submitter, used for approver resolution.
      */
     explainChain(templateName: string, data: Record<string, unknown>, submittedBy: string): Promise<ChainExplanation>;
+    /**
+     * Run a document through a template against scripted decisions, without
+     * persisting anything.
+     *
+     * `explainChain()` says what the chain will be; this says what happens to it —
+     * "if the CFO rejects at level 3, does it go back to the submitter or die?" —
+     * which previously meant submitting a real approval into a real store and
+     * cleaning it up afterwards, or reasoning about the state machine by hand.
+     *
+     * The run executes against a private in-memory store seeded with a copy of
+     * the template, so the caller's storage is untouched and no events reach the
+     * caller's notification adapters. Custom resolvers and approver types are
+     * copied across, because a simulation that could not resolve the caller's own
+     * `dynamic` approvers would answer a different question from the one asked.
+     *
+     * A refused decision — wrong approver, wrong level, already acted — stops the
+     * run and is reported in the transcript rather than thrown: the refusal is
+     * usually the answer the caller was looking for.
+     *
+     * @param opts - Template, document data, submitter and the decisions to play.
+     */
+    simulate(opts: {
+        templateName: string;
+        data: Record<string, unknown>;
+        submittedBy: string;
+        decisions?: SimulatedDecision[];
+    }): Promise<SimulationResult>;
     canApprove(instanceId: string, userId: string): Promise<CanApproveResult>;
     /** Emergency bypass — completes the instance as 'approved', skipping remaining levels. Requires template.allowOverride = true. */
     override(instanceId: string, raw: OverrideOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
@@ -1032,4 +1109,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 TemplateBundle as F, type TransferResult as G, type HealthResult as H, type IdGeneratorFn as I, businessHoursCalendar as J, defaultIdGenerator as K, toComparableNumber as L, validateConditionExpression as M, weekendCalendar as N, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, TEMPLATE_BUNDLE_VERSION 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 BusinessHoursCalendarOptions as h, type CancelOptions as i, type ChainExplanation as j, type ConditionOperatorFn as k, type CycleTimeStats as l, type ExplainedLevel as m, type ExplainedRule as n, type ExplainedSkip as o, type IdempotencyKeyFn as p, type ImportResult as q, type OutOfOfficeProvider as r, type OverrideOptions as s, type PreviewResult as t, type ProvideInfoOptions as u, type PurgeResult as v, type RejectOptions as w, type RequestInfoOptions as x, type ResubmitOptions as y, type RetryPolicy as z };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type SimulationResult as F, type SimulationStep as G, type HealthResult as H, type IdGeneratorFn as I, type SubmitOptions as J, type TemplateBundle as K, type TransferResult as L, businessHoursCalendar as M, defaultIdGenerator as N, type OrgProvider as O, type PreviewChainLevel as P, toComparableNumber as Q, type ReassignOptions as R, type SimulatedDecision as S, TEMPLATE_BUNDLE_VERSION as T, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, validateConditionExpression as X, weekendCalendar as Y, 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 BusinessHoursCalendarOptions as h, type CancelOptions as i, type ChainExplanation as j, type ConditionOperatorFn as k, type CycleTimeStats as l, type ExplainedLevel as m, type ExplainedRule as n, type ExplainedSkip as o, type IdempotencyKeyFn as p, type ImportResult as q, type OutOfOfficeProvider as r, type OverrideOptions as s, type PreviewResult as t, type ProvideInfoOptions as u, type PurgeResult as v, type RejectOptions as w, type RequestInfoOptions as x, type ResubmitOptions as y, type RetryPolicy as z };

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

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

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

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

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

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

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

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

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-weh2w7Ji.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-BvOyT00S.cjs';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -120,6 +120,16 @@ interface SubWorkflowEvent extends ApprovalEvent {
     /** Set on completion: the outcome the child returned. */
     outcome?: 'approved' | 'rejected' | 'cancelled' | 'expired';
 }
+/** Emitted when a comment is posted. Recipients are the users it mentions. */
+interface CommentedEvent extends ApprovalEvent {
+    commentId: string;
+    authorId: string;
+    body: string;
+    level?: number;
+    parentCommentId?: string;
+    /** Users named in the comment. */
+    recipients: string[];
+}
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -142,6 +152,7 @@ interface ApprovalEventMap {
     'approval:attachment_removed': AttachmentEvent;
     'approval:subworkflow_started': SubWorkflowEvent;
     'approval:subworkflow_completed': SubWorkflowEvent;
+    'approval:commented': CommentedEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
 interface HistoryEntry extends AuditEntry {
@@ -165,4 +176,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, AttachmentEvent as d, DelegatedEvent as e, ExpiredEvent as f, InfoProvidedEvent as g, InfoRequestedEvent as h, RejectedEvent as i, ReminderEvent as j, ResubmittedEvent as k, SubWorkflowEvent as l, SubmittedEvent as m };
+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, CommentedEvent as e, DelegatedEvent as f, ExpiredEvent as g, InfoProvidedEvent as h, InfoRequestedEvent as i, RejectedEvent as j, ReminderEvent as k, ResubmittedEvent as l, SubWorkflowEvent as m, SubmittedEvent as n };

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-weh2w7Ji.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-BvOyT00S.js';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -120,6 +120,16 @@ interface SubWorkflowEvent extends ApprovalEvent {
     /** Set on completion: the outcome the child returned. */
     outcome?: 'approved' | 'rejected' | 'cancelled' | 'expired';
 }
+/** Emitted when a comment is posted. Recipients are the users it mentions. */
+interface CommentedEvent extends ApprovalEvent {
+    commentId: string;
+    authorId: string;
+    body: string;
+    level?: number;
+    parentCommentId?: string;
+    /** Users named in the comment. */
+    recipients: string[];
+}
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -142,6 +152,7 @@ interface ApprovalEventMap {
     'approval:attachment_removed': AttachmentEvent;
     'approval:subworkflow_started': SubWorkflowEvent;
     'approval:subworkflow_completed': SubWorkflowEvent;
+    'approval:commented': CommentedEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
 interface HistoryEntry extends AuditEntry {
@@ -165,4 +176,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, AttachmentEvent as d, DelegatedEvent as e, ExpiredEvent as f, InfoProvidedEvent as g, InfoRequestedEvent as h, RejectedEvent as i, ReminderEvent as j, ResubmittedEvent as k, SubWorkflowEvent as l, SubmittedEvent as m };
+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, CommentedEvent as e, DelegatedEvent as f, ExpiredEvent as g, InfoProvidedEvent as h, InfoRequestedEvent as i, RejectedEvent as j, ReminderEvent as k, ResubmittedEvent as l, SubWorkflowEvent as m, SubmittedEvent as n };

package/dist/{IOperationMiddleware-CxnPzpqL.d.cts → IOperationMiddleware-C8i06wq4.d.cts}

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

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

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

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

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

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

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

package/dist/adapters/MemoryAdapter.cjs

@@ -44,10 +44,14 @@ function reviveDates(instance) {
     slaDeadlineAt: instance.slaDeadlineAt ? new Date(instance.slaDeadlineAt) : void 0,
     slaBreachedAt: instance.slaBreachedAt ? new Date(instance.slaBreachedAt) : void 0,
     auditLog: instance.auditLog.map((e) => ({ ...e, timestamp: new Date(e.timestamp) })),
+    infoRequest: instance.infoRequest ? { ...instance.infoRequest, askedAt: new Date(instance.infoRequest.askedAt) } : void 0,
+    attachments: instance.attachments ? instance.attachments.map((a) => ({ ...a, addedAt: new Date(a.addedAt) })) : void 0,
+    comments: instance.comments ? instance.comments.map((c) => ({ ...c, createdAt: new Date(c.createdAt) })) : void 0,
     levels: instance.levels.map((l) => {
       const level = { ...l };
       if (l.escalationDueAt) level.escalationDueAt = new Date(l.escalationDueAt);
       if (l.delegatedUntil) level.delegatedUntil = new Date(l.delegatedUntil);
+      if (l.reminderDueAt) level.reminderDueAt = new Date(l.reminderDueAt);
       return level;
     })
   };