hierarchical-approval 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,75 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [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
+
+- **`InstanceFilter` gains `data`.** Filters covered status, document type,
+  submitter, template and date, but nothing about the document itself, so
+  "every pending purchase order for vendor ACME" meant paging the whole tenant
+  and filtering in application code — which scales badly and pushes the same
+  logic into every caller.
+
+  ```ts
+  await engine.queryInstances({
+    status: 'pending',
+    data: { 'vendor.id': 'v-1', region: 'EU' },
+  });
+  ```
+
+  Keys are dot-paths, values compare by deep equality (so object and array
+  values match structurally), and all pairs must match. Available on
+  `queryInstances()`, `queryInstancesByCursor()` and `getStatistics()`.
+
+- **Paths resolve over own properties only**, mirroring how conditions read
+  field paths — a filter and a condition written against the same path agree on
+  what it means, and an inherited prototype member can never make an instance
+  match a query.
+
+- **On PostgreSQL this compiles to a parameterised JSONB path lookup**
+  (`data #> $n::text[] = $n+1::jsonb`). Path segments travel as a parameter and
+  are never interpolated into SQL. Comparison is against JSONB rather than
+  serialised text, so structural matching holds on both adapters. Index hot
+  paths with `CREATE INDEX ON approval_instances ((data #> '{vendor,id}'))`.
+
 ## [1.3.0] - 2026-09-04
 
 ### Added — out-of-office cover

package/README.md

@@ -399,6 +399,63 @@ 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 —
+"every purchase order for vendor ACME" without fetching pages and filtering in
+application code:
+
+```ts
+const { items } = await engine.queryInstances({
+  status: 'pending',
+  data: { 'vendor.id': 'v-1', region: 'EU' },   // dot-paths; all pairs must match
+});
+```
+
+Values compare by deep equality, so an object or array value matches
+structurally. Keys resolve over **own** properties only, mirroring how
+conditions read field paths, so an inherited prototype member can never make an
+instance match. Works with `queryInstances()`, `queryInstancesByCursor()` and
+`getStatistics()`.
+
+On PostgreSQL this becomes a parameterised JSONB path lookup — the path travels
+as a parameter and is never interpolated into SQL. Index the paths you filter on
+often:
+
+```sql
+CREATE INDEX ON approval_instances ((data #> '{vendor,id}'));
+```
+
 ### Out-of-office cover
 
 Approvers go on leave, and a chain that waits on an absent person stalls.

package/dist/{ApprovalEngine-Dhu5mlCG.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-DQJmR6Mt.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-CfySjeuy.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-CKV_FZFV.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-CKV_FZFV.d.cts → IStorageAdapter-CXRyeUOK.d.ts}

@@ -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.js';
 
 interface PaginationOpts {
     limit: number;
@@ -27,6 +27,16 @@ interface InstanceFilter {
     templateName?: string;
     fromDate?: Date;
     toDate?: Date;
+    /**
+     * Match instances whose document `data` contains these field/value pairs —
+     * "every purchase order for vendor ACME", without the caller fetching a page
+     * at a time and filtering in application code.
+     *
+     * Keys are dot-paths (`vendor.id`), values compare by deep equality, and all
+     * pairs must match. Matching is on **own** properties only, mirroring how
+     * conditions resolve field paths.
+     */
+    data?: Record<string, unknown>;
 }
 interface IStorageAdapter {
     saveTemplate(template: ApprovalTemplate): Promise<void>;

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

@@ -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.cjs';
 
 interface PaginationOpts {
     limit: number;
@@ -27,6 +27,16 @@ interface InstanceFilter {
     templateName?: string;
     fromDate?: Date;
     toDate?: Date;
+    /**
+     * Match instances whose document `data` contains these field/value pairs —
+     * "every purchase order for vendor ACME", without the caller fetching a page
+     * at a time and filtering in application code.
+     *
+     * Keys are dot-paths (`vendor.id`), values compare by deep equality, and all
+     * pairs must match. Matching is on **own** properties only, mirroring how
+     * conditions resolve field paths.
+     */
+    data?: Record<string, unknown>;
 }
 interface IStorageAdapter {
     saveTemplate(template: ApprovalTemplate): Promise<void>;

package/dist/adapters/MemoryAdapter.cjs

@@ -55,6 +55,25 @@ function reviveDates(instance) {
 function reviveTemplateDates(template) {
   return { ...template, createdAt: new Date(template.createdAt) };
 }
+function readPath(data, path) {
+  return path.split(".").reduce((obj, key) => {
+    if (obj !== null && typeof obj === "object" && Object.prototype.hasOwnProperty.call(obj, key)) {
+      return obj[key];
+    }
+    return void 0;
+  }, data);
+}
+function deepEquals(a, b) {
+  if (Object.is(a, b)) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  return aKeys.every(
+    (k) => Object.prototype.hasOwnProperty.call(b, k) && deepEquals(a[k], b[k])
+  );
+}
 function applyFilter(instance, filter) {
   if (filter.status && instance.status !== filter.status) return false;
   if (filter.documentType && instance.documentType !== filter.documentType) return false;
@@ -62,6 +81,11 @@ function applyFilter(instance, filter) {
   if (filter.templateName && instance.templateName !== filter.templateName) return false;
   if (filter.fromDate && new Date(instance.createdAt) < filter.fromDate) return false;
   if (filter.toDate && new Date(instance.createdAt) > filter.toDate) return false;
+  if (filter.data) {
+    for (const [path, expected] of Object.entries(filter.data)) {
+      if (!deepEquals(readPath(instance.data ?? {}, path), expected)) return false;
+    }
+  }
   return true;
 }
 var MemoryAdapter = class {