hierarchical-approval 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -7,6 +7,85 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [1.6.0] - 2026-09-04
+
+### Fixed — PostgresAdapter silently dropped most instance updates
+
+**Anyone running the PostgreSQL adapter should upgrade and run `migrate()`.**
+`MemoryAdapter` stores whole objects and was always correct, so this reproduced
+only against a real database — which is exactly where it mattered.
+
+`updateInstance` wrote just six columns (`status`, `current_level`, `version`,
+`levels`, `sla_breached_at`, `updated_at`). Every other field an operation
+mutates was computed, logged, emitted as an event, and then thrown away on
+write:
+
+- **`updateData()` (0.9.0) did not change the stored document.** The engine
+  recomputed the chain and emitted `approval:data_updated`, but `data` was never
+  written, so the next read returned the old values — and any later
+  re-evaluation ran against them.
+- **`requestInfo()` (1.5.0) lost the hold entirely.** `info_request` had no
+  column at all, so a held instance came back unheld: `provideInfo()` then threw
+  "No clarification request is open", and the scheduler escalated and expired an
+  approval that was supposed to be paused.
+- **`provideInfo()`'s deadline give-back never landed** — `expires_at` and
+  `sla_deadline_at` were not written, so the time an instance spent on hold was
+  silently forfeited.
+- `metadata`, `deadline_action` and `template_snapshot` were likewise never
+  updated after insert.
+
+`updateInstance` now writes every mutable column, `saveInstance` and
+`rowToInstance` carry `info_request` (reviving `askedAt` as a `Date`), and
+`migrate()` adds the column to existing deployments via
+`ADD COLUMN IF NOT EXISTS`. Optimistic concurrency is unchanged — the update
+still guards on `version`.
+
+Regression tests assert the generated SQL and parameters for each field, so a
+future column cannot be added to the type and forgotten in the writer.
+
+### Note on the roadmap
+
+Attachment references were the planned 1.6.0. They are deferred: shipping a new
+feature ahead of a data-loss fix in an already-published release would have been
+the wrong order.
+
+## [1.5.0] - 2026-09-04
+
+### Added — request for information
+
+- **`requestInfo()` / `provideInfo()` let an approver ask the submitter a
+  question without rejecting.** Approvers routinely need one fact before they
+  can decide, and there was no way to say so: rejecting throws away every
+  approval already collected and forces a resubmit, while chasing the question
+  by email leaves the request sitting and quietly burns the SLA the approver is
+  measured on.
+
+  ```ts
+  await engine.requestInfo(id, { approverId: 'mgr-1', question: 'Which cost centre?' });
+  await engine.provideInfo(id, { respondedBy: 'buyer-1', response: 'CC-42' });
+  ```
+
+  The instance stays `pending` and keeps its approvers — this is a question, not
+  a decision.
+
+- **Deadlines are paused for the duration of the hold.** The scheduler skips a
+  held instance entirely, so escalation, reminders, SLA breach and expiry cannot
+  fire while the submitter owes an answer; on answer, every deadline that was
+  set is pushed out by exactly how long the question was open. An approver gets
+  back the time they had before asking rather than being penalised for asking.
+  A deadline that was never configured is not invented by being held.
+
+- **Wiring:** emits `approval:info_requested` (addressed to the submitter) and
+  `approval:info_provided` (addressed to the waiting approvers, carrying
+  `heldForMs`); records `info_requested` / `info_provided` audit entries;
+  increments `approval.info_requested` / `approval.info_provided`; and adds both
+  operations to the authorization-policy set. Only one question may be open at a
+  time.
+
+  New exports: `InfoRequest`, `InfoRequestedEvent`, `InfoProvidedEvent`,
+  `RequestInfoOptions`, `ProvideInfoOptions`. `ApprovalInstance` gains
+  `infoRequest`.
+
 ## [1.4.0] - 2026-09-04
 
 ### Added — filter instances by document data

package/README.md

@@ -399,6 +399,36 @@ engine.registerConditionOperator('between', (actual, expected) => {
 });
 ```
 
+### Asking the submitter a question
+
+Approvers routinely need one fact before they can decide. `requestInfo()` puts
+the approval on hold without rejecting it:
+
+```ts
+await engine.requestInfo(instance.id, {
+  approverId: 'mgr-1',
+  question: 'Which cost centre should this book to?',
+});
+
+// ...later
+await engine.provideInfo(instance.id, {
+  respondedBy: 'buyer-1',
+  response: 'CC-42',
+});
+```
+
+The instance stays `pending` and keeps its approvers — this is a question, not a
+decision. What changes is the clock: **escalation, SLA, reminder and expiry
+deadlines stop advancing while the question is open**, and on answer every one
+is pushed out by exactly how long the hold lasted. An approver gets back the
+time they had before asking, rather than being penalised for asking.
+
+Emits `approval:info_requested` (addressed to the submitter) and
+`approval:info_provided` (addressed to the waiting approvers, carrying
+`heldForMs`), and records `info_requested` / `info_provided` audit entries.
+
+Only one question can be open at a time; answer it before asking another.
+
 ### Filtering by document data
 
 Every query filter accepts `data`, matching against the document body itself —

package/dist/{ApprovalEngine-NN6Dqf6E.d.ts → ApprovalEngine-CyZJDbjP.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-DVclp9cn.js';
-import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-BsM0DUPf.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BmSeB7FZ.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-CXRyeUOK.js';
+import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-SA0BU-Gb.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Cyo0cvXU.js';
 import { 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-BW9t8wPn.js';
-import { I as IAuditAdapter } from './IAuditAdapter-GixC9zS1.js';
-import { I as IMetricsAdapter } from './IMetricsAdapter-QvyaKQCc.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-rx7XAPrW.js';
+import { I as IAuditAdapter } from './IAuditAdapter-wfOcN3Zf.js';
+import { I as IMetricsAdapter } from './IMetricsAdapter-JZVK3QUq.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-4ge9Gnxj.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-CdvoZsGC.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -69,6 +69,15 @@ declare const OverrideOptionsSchema: z.ZodObject<{
     overriddenBy: z.ZodString;
     justification: z.ZodString;
 }, z.core.$strip>;
+declare const RequestInfoOptionsSchema: z.ZodObject<{
+    approverId: z.ZodString;
+    question: z.ZodString;
+    level: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const ProvideInfoOptionsSchema: z.ZodObject<{
+    respondedBy: z.ZodString;
+    response: z.ZodString;
+}, z.core.$strip>;
 declare const UpdateDataOptionsSchema: z.ZodObject<{
     updatedBy: z.ZodString;
     data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -90,6 +99,8 @@ type ResubmitOptions = z.infer<typeof ResubmitOptionsSchema>;
 type AddCommentOptions = z.infer<typeof AddCommentOptionsSchema>;
 type OverrideOptions = z.infer<typeof OverrideOptionsSchema>;
 type UpdateDataOptions = z.infer<typeof UpdateDataOptionsSchema>;
+type RequestInfoOptions = z.infer<typeof RequestInfoOptionsSchema>;
+type ProvideInfoOptions = z.infer<typeof ProvideInfoOptionsSchema>;
 
 /**
  * Computes deadline dates from a number of days. The default engine behaviour
@@ -444,6 +455,41 @@ declare class ApprovalEngine {
      * {@link updateData} for why.
      */
     private recomputeFutureChain;
+    /**
+     * Ask the submitter for clarification without rejecting.
+     *
+     * Approvers routinely need one fact before they can decide. The only ways to
+     * express that were to reject — which throws away every approval already
+     * collected and forces a resubmit — or to leave the request sitting while the
+     * question is chased by email, which quietly burns the SLA the approver is
+     * measured on.
+     *
+     * The instance stays `pending` and keeps its approvers: this is a question,
+     * not a decision. What changes is the clock — escalation, SLA and expiry
+     * deadlines stop advancing while the question is open, because time spent
+     * waiting on the submitter is not time the approver is sitting on their hands.
+     *
+     * @throws ApprovalError if the instance is not pending, or a question is already open.
+     */
+    requestInfo(instanceId: string, raw: RequestInfoOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Answer an open clarification request and take the instance off hold.
+     *
+     * Every deadline that was paused is pushed out by exactly how long the
+     * question was open, so an approver gets back the full remaining time they
+     * had before asking rather than being penalised for asking at all.
+     *
+     * @throws ApprovalError if no question is open.
+     */
+    provideInfo(instanceId: string, raw: ProvideInfoOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Push every pending deadline out by `ms`.
+     *
+     * Used to give back time an instance spent on hold. Deadlines that are not
+     * set stay unset — a level with no escalation configured does not acquire one
+     * by being held.
+     */
+    private extendDeadlinesBy;
     /** Add a comment to an instance without approving or rejecting. */
     addComment(instanceId: string, raw: AddCommentOptions, auditCtx?: AuditContext): Promise<void>;
     /** Resubmit a rejected instance, creating a new linked instance from level 1. */
@@ -568,4 +614,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type RejectOptions as n, type ResubmitOptions as o, type RetryPolicy as p, defaultIdGenerator as q, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type ProvideInfoOptions as n, type RejectOptions as o, type RequestInfoOptions as p, type ResubmitOptions as q, type RetryPolicy as r, defaultIdGenerator as s, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };

package/dist/{ApprovalEngine-D8kKuapR.d.cts → ApprovalEngine-SI-IRUMY.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-C7isBXJF.cjs';
-import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-BsM0DUPf.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BKMeGmaG.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-Dz8jrIAK.cjs';
+import { k as ConditionExpression, o as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, j as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-SA0BU-Gb.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Cn-LNPtD.cjs';
 import { 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-BLw9Oc-S.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-B2I3CjaJ.cjs';
-import { I as IMetricsAdapter } from './IMetricsAdapter-QvyaKQCc.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-DrJy9UtL.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-Cr0dLoVP.cjs';
+import { I as IMetricsAdapter } from './IMetricsAdapter-JZVK3QUq.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BHDZK9QL.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BHybAsq5.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -69,6 +69,15 @@ declare const OverrideOptionsSchema: z.ZodObject<{
     overriddenBy: z.ZodString;
     justification: z.ZodString;
 }, z.core.$strip>;
+declare const RequestInfoOptionsSchema: z.ZodObject<{
+    approverId: z.ZodString;
+    question: z.ZodString;
+    level: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const ProvideInfoOptionsSchema: z.ZodObject<{
+    respondedBy: z.ZodString;
+    response: z.ZodString;
+}, z.core.$strip>;
 declare const UpdateDataOptionsSchema: z.ZodObject<{
     updatedBy: z.ZodString;
     data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -90,6 +99,8 @@ type ResubmitOptions = z.infer<typeof ResubmitOptionsSchema>;
 type AddCommentOptions = z.infer<typeof AddCommentOptionsSchema>;
 type OverrideOptions = z.infer<typeof OverrideOptionsSchema>;
 type UpdateDataOptions = z.infer<typeof UpdateDataOptionsSchema>;
+type RequestInfoOptions = z.infer<typeof RequestInfoOptionsSchema>;
+type ProvideInfoOptions = z.infer<typeof ProvideInfoOptionsSchema>;
 
 /**
  * Computes deadline dates from a number of days. The default engine behaviour
@@ -444,6 +455,41 @@ declare class ApprovalEngine {
      * {@link updateData} for why.
      */
     private recomputeFutureChain;
+    /**
+     * Ask the submitter for clarification without rejecting.
+     *
+     * Approvers routinely need one fact before they can decide. The only ways to
+     * express that were to reject — which throws away every approval already
+     * collected and forces a resubmit — or to leave the request sitting while the
+     * question is chased by email, which quietly burns the SLA the approver is
+     * measured on.
+     *
+     * The instance stays `pending` and keeps its approvers: this is a question,
+     * not a decision. What changes is the clock — escalation, SLA and expiry
+     * deadlines stop advancing while the question is open, because time spent
+     * waiting on the submitter is not time the approver is sitting on their hands.
+     *
+     * @throws ApprovalError if the instance is not pending, or a question is already open.
+     */
+    requestInfo(instanceId: string, raw: RequestInfoOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Answer an open clarification request and take the instance off hold.
+     *
+     * Every deadline that was paused is pushed out by exactly how long the
+     * question was open, so an approver gets back the full remaining time they
+     * had before asking rather than being penalised for asking at all.
+     *
+     * @throws ApprovalError if no question is open.
+     */
+    provideInfo(instanceId: string, raw: ProvideInfoOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Push every pending deadline out by `ms`.
+     *
+     * Used to give back time an instance spent on hold. Deadlines that are not
+     * set stay unset — a level with no escalation configured does not acquire one
+     * by being held.
+     */
+    private extendDeadlinesBy;
     /** Add a comment to an instance without approving or rejecting. */
     addComment(instanceId: string, raw: AddCommentOptions, auditCtx?: AuditContext): Promise<void>;
     /** Resubmit a rejected instance, creating a new linked instance from level 1. */
@@ -568,4 +614,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type RejectOptions as n, type ResubmitOptions as o, type RetryPolicy as p, defaultIdGenerator as q, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type ProvideInfoOptions as n, type RejectOptions as o, type RequestInfoOptions as p, type ResubmitOptions as q, type RetryPolicy as r, defaultIdGenerator as s, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };

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

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

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

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

package/dist/{IAuthorizationPolicy-BHDZK9QL.d.cts → IAuthorizationPolicy-BHybAsq5.d.cts}

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

package/dist/{IAuthorizationPolicy-4ge9Gnxj.d.ts → IAuthorizationPolicy-CdvoZsGC.d.ts}

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

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

@@ -1,4 +1,4 @@
-type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.reassigned' | 'approval.overridden' | 'approval.data_updated' | 'approval.reminded' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
+type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.reassigned' | 'approval.overridden' | 'approval.data_updated' | 'approval.reminded' | 'approval.info_requested' | 'approval.info_provided' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */
     increment(metric: MetricName, labels?: Record<string, string>): void;

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

@@ -1,4 +1,4 @@
-type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.reassigned' | 'approval.overridden' | 'approval.data_updated' | 'approval.reminded' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
+type MetricName = 'approval.submitted' | 'approval.approved' | 'approval.rejected' | 'approval.cancelled' | 'approval.expired' | 'approval.sla_breached' | 'approval.escalated' | 'approval.reassigned' | 'approval.overridden' | 'approval.data_updated' | 'approval.reminded' | 'approval.info_requested' | 'approval.info_provided' | 'approval.conflict_retry' | 'approval.operation_duration_ms';
 interface IMetricsAdapter {
     /** Increment a counter. Synchronous — never awaited. */
     increment(metric: MetricName, labels?: Record<string, string>): void;

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-BsM0DUPf.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-SA0BU-Gb.cjs';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -86,6 +86,24 @@ interface ReminderEvent extends ApprovalEvent {
     /** 1 for the first reminder on this level, 2 for the next, and so on. */
     reminderNumber: number;
 }
+/** Emitted when an approver asks the submitter for clarification. */
+interface InfoRequestedEvent extends ApprovalEvent {
+    askedBy: string;
+    question: string;
+    level: number;
+    /** Who is expected to answer — the submitter. */
+    recipients: string[];
+}
+/** Emitted when the question is answered and the instance comes off hold. */
+interface InfoProvidedEvent extends ApprovalEvent {
+    respondedBy: string;
+    response: string;
+    level: number;
+    /** How long the instance spent on hold; deadlines were extended by this much. */
+    heldForMs: number;
+    /** The approvers waiting again now that the question is answered. */
+    recipients: string[];
+}
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -102,6 +120,8 @@ interface ApprovalEventMap {
     'approval:sla_breached': SlaBreachedEvent;
     'approval:data_updated': DataUpdatedEvent;
     'approval:reminder': ReminderEvent;
+    'approval:info_requested': InfoRequestedEvent;
+    'approval:info_provided': InfoProvidedEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
 interface HistoryEntry extends AuditEntry {
@@ -125,4 +145,4 @@ interface INotificationAdapter {
     notify(event: NotificationEvent): Promise<void>;
 }
 
-export type { ApprovalEvent as A, CancelledEvent as C, DataUpdatedEvent as D, EscalatedEvent as E, HistoryEntry as H, INotificationAdapter as I, LevelAdvancedEvent as L, NotificationEvent as N, OverriddenEvent as O, ReassignedEvent as R, SlaBreachedEvent as S, ApprovalEventMap as a, ApprovalEventName as b, ApprovedEvent as c, DelegatedEvent as d, ExpiredEvent as e, RejectedEvent as f, ReminderEvent as g, ResubmittedEvent as h, SubmittedEvent as i };
+export type { ApprovalEvent as A, CancelledEvent as C, DataUpdatedEvent as D, EscalatedEvent as E, HistoryEntry as H, INotificationAdapter as I, LevelAdvancedEvent as L, NotificationEvent as N, OverriddenEvent as O, ReassignedEvent as R, SlaBreachedEvent as S, ApprovalEventMap as a, ApprovalEventName as b, ApprovedEvent as c, DelegatedEvent as d, ExpiredEvent as e, InfoProvidedEvent as f, InfoRequestedEvent as g, RejectedEvent as h, ReminderEvent as i, ResubmittedEvent as j, SubmittedEvent as k };

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-BsM0DUPf.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-SA0BU-Gb.js';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -86,6 +86,24 @@ interface ReminderEvent extends ApprovalEvent {
     /** 1 for the first reminder on this level, 2 for the next, and so on. */
     reminderNumber: number;
 }
+/** Emitted when an approver asks the submitter for clarification. */
+interface InfoRequestedEvent extends ApprovalEvent {
+    askedBy: string;
+    question: string;
+    level: number;
+    /** Who is expected to answer — the submitter. */
+    recipients: string[];
+}
+/** Emitted when the question is answered and the instance comes off hold. */
+interface InfoProvidedEvent extends ApprovalEvent {
+    respondedBy: string;
+    response: string;
+    level: number;
+    /** How long the instance spent on hold; deadlines were extended by this much. */
+    heldForMs: number;
+    /** The approvers waiting again now that the question is answered. */
+    recipients: string[];
+}
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -102,6 +120,8 @@ interface ApprovalEventMap {
     'approval:sla_breached': SlaBreachedEvent;
     'approval:data_updated': DataUpdatedEvent;
     'approval:reminder': ReminderEvent;
+    'approval:info_requested': InfoRequestedEvent;
+    'approval:info_provided': InfoProvidedEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
 interface HistoryEntry extends AuditEntry {
@@ -125,4 +145,4 @@ interface INotificationAdapter {
     notify(event: NotificationEvent): Promise<void>;
 }
 
-export type { ApprovalEvent as A, CancelledEvent as C, DataUpdatedEvent as D, EscalatedEvent as E, HistoryEntry as H, INotificationAdapter as I, LevelAdvancedEvent as L, NotificationEvent as N, OverriddenEvent as O, ReassignedEvent as R, SlaBreachedEvent as S, ApprovalEventMap as a, ApprovalEventName as b, ApprovedEvent as c, DelegatedEvent as d, ExpiredEvent as e, RejectedEvent as f, ReminderEvent as g, ResubmittedEvent as h, SubmittedEvent as i };
+export type { ApprovalEvent as A, CancelledEvent as C, DataUpdatedEvent as D, EscalatedEvent as E, HistoryEntry as H, INotificationAdapter as I, LevelAdvancedEvent as L, NotificationEvent as N, OverriddenEvent as O, ReassignedEvent as R, SlaBreachedEvent as S, ApprovalEventMap as a, ApprovalEventName as b, ApprovedEvent as c, DelegatedEvent as d, ExpiredEvent as e, InfoProvidedEvent as f, InfoRequestedEvent as g, RejectedEvent as h, ReminderEvent as i, ResubmittedEvent as j, SubmittedEvent as k };

package/dist/{IOperationMiddleware-BLw9Oc-S.d.cts → IOperationMiddleware-DrJy9UtL.d.cts}

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

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

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

package/dist/{IStorageAdapter-DVclp9cn.d.ts → IStorageAdapter-CXRyeUOK.d.ts}

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

package/dist/{IStorageAdapter-C7isBXJF.d.cts → IStorageAdapter-Dz8jrIAK.d.cts}

@@ -1,4 +1,4 @@
-import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-BsM0DUPf.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, f as ApprovalStatus, b as AuditEntry } from './instance-SA0BU-Gb.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-C7isBXJF.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BsM0DUPf.cjs';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-Dz8jrIAK.cjs';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-SA0BU-Gb.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-DVclp9cn.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BsM0DUPf.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-CXRyeUOK.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-SA0BU-Gb.js';
 
 declare class MemoryAdapter implements IStorageAdapter {
     private templates;

package/dist/adapters/PostgresAdapter.cjs

@@ -115,6 +115,7 @@ var PostgresAdapter = class {
         sla_deadline_at     TIMESTAMPTZ,
         sla_breached_at     TIMESTAMPTZ,
         template_snapshot   JSONB,
+        info_request        JSONB,
         created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
         updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
         PRIMARY KEY (tenant_id, id),
@@ -157,6 +158,7 @@ var PostgresAdapter = class {
       ALTER TABLE IF EXISTS ${this.p}_instances ADD COLUMN IF NOT EXISTS sla_deadline_at TIMESTAMPTZ;
       ALTER TABLE IF EXISTS ${this.p}_instances ADD COLUMN IF NOT EXISTS sla_breached_at TIMESTAMPTZ;
       ALTER TABLE IF EXISTS ${this.p}_instances ADD COLUMN IF NOT EXISTS template_snapshot JSONB;
+      ALTER TABLE IF EXISTS ${this.p}_instances ADD COLUMN IF NOT EXISTS info_request JSONB;
     `);
   }
   /** Enable PostgreSQL Row Level Security for the instances and audit_log tables. */
@@ -216,9 +218,9 @@ var PostgresAdapter = class {
           status, current_level, version, idempotency_key,
           data, metadata, levels,
           parent_instance_id, expires_at, deadline_action,
-          sla_deadline_at, sla_breached_at, template_snapshot,
+          sla_deadline_at, sla_breached_at, template_snapshot, info_request,
           created_at, updated_at)
-       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22,$23)
        ON CONFLICT (tenant_id, id) DO NOTHING`,
       [
         instance.id,
@@ -241,6 +243,7 @@ var PostgresAdapter = class {
         instance.slaDeadlineAt?.toISOString() ?? null,
         instance.slaBreachedAt?.toISOString() ?? null,
         instance.templateSnapshot ? JSON.stringify(instance.templateSnapshot) : null,
+        instance.infoRequest ? JSON.stringify(instance.infoRequest) : null,
         instance.createdAt.toISOString(),
         instance.updatedAt.toISOString()
       ]
@@ -249,13 +252,24 @@ var PostgresAdapter = class {
   async updateInstance(instance, expectedVersion) {
     const pool = await this.getPool();
     const result = await pool.query(
+      // Every column an engine operation can mutate must be written here.
+      // Listing only a subset silently dropped writes: updateData() changed
+      // `data`, requestInfo() set `info_request`, and provideInfo() shifted the
+      // deadline columns — none of which reached the database.
       `UPDATE ${this.p}_instances SET
-         status           = $4,
-         current_level    = $5,
-         version          = $6 + 1,
-         levels           = $7,
-         sla_breached_at  = $8,
-         updated_at       = $9
+         status            = $4,
+         current_level     = $5,
+         version           = $6 + 1,
+         levels            = $7,
+         sla_breached_at   = $8,
+         updated_at        = $9,
+         data              = $10,
+         metadata          = $11,
+         expires_at        = $12,
+         deadline_action   = $13,
+         sla_deadline_at   = $14,
+         template_snapshot = $15,
+         info_request      = $16
        WHERE tenant_id = $1 AND id = $2 AND version = $3
        RETURNING id`,
       [
@@ -267,7 +281,14 @@ var PostgresAdapter = class {
         expectedVersion,
         JSON.stringify(instance.levels),
         instance.slaBreachedAt?.toISOString() ?? null,
-        instance.updatedAt.toISOString()
+        instance.updatedAt.toISOString(),
+        JSON.stringify(instance.data ?? {}),
+        JSON.stringify(instance.metadata ?? {}),
+        instance.expiresAt?.toISOString() ?? null,
+        instance.deadlineAction ?? null,
+        instance.slaDeadlineAt?.toISOString() ?? null,
+        instance.templateSnapshot ? JSON.stringify(instance.templateSnapshot) : null,
+        instance.infoRequest ? JSON.stringify(instance.infoRequest) : null
       ]
     );
     if (result.rowCount === 0) throw new ApprovalConflictError(instance.id);
@@ -516,6 +537,10 @@ var PostgresAdapter = class {
       slaDeadlineAt: row["sla_deadline_at"] ? new Date(row["sla_deadline_at"]) : void 0,
       slaBreachedAt: row["sla_breached_at"] ? new Date(row["sla_breached_at"]) : void 0,
       templateSnapshot: row["template_snapshot"] ?? void 0,
+      infoRequest: row["info_request"] ? {
+        ...row["info_request"],
+        askedAt: new Date(row["info_request"].askedAt)
+      } : void 0,
       createdAt: new Date(row["created_at"]),
       updatedAt: new Date(row["updated_at"])
     };