hierarchical-approval 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [1.7.0] - 2026-09-04
+
+### Added — attachment references
+
+- **`addAttachment()` / `removeAttachment()` attach supporting evidence to an
+  approval** — a quote PDF, a signed contract, a screenshot of a system of
+  record. Approvers had nowhere to put the document their decision rested on, so
+  it lived in an email thread the audit trail never saw.
+
+  ```ts
+  await engine.addAttachment(id, {
+    actorId: 'buyer-1',
+    name: 'quote.pdf',
+    uri: 's3://procurement/quotes/q-1.pdf',
+    contentType: 'application/pdf',
+    sizeBytes: 48_120,
+  });
+  ```
+
+- **References only, never bytes.** Approval documents belong in the object
+  store or DMS the organisation already runs, which handles retention, virus
+  scanning and access control far better than an approval table could; copying
+  them here would make the audit database the largest and least governed copy of
+  them. Removing detaches the reference and never deletes from the underlying
+  store.
+
+- **The audit trail keeps what was removed** — name and URI are recorded on the
+  `attachment_removed` entry, so the record still shows an approver saw evidence
+  that is no longer listed. Dropping that would let the trail imply a decision
+  was made on less than it was.
+
+- Persisted across all four PostgreSQL sites (schema, `migrate()`,
+  insert, update, and read-back), with `addedAt` revived as a `Date`. An
+  instance with no attachments reads back as `undefined` rather than `[]`,
+  keeping the round-trip shape identical to `MemoryAdapter`.
+
+  New exports: `Attachment`, `AttachmentEvent`, `AddAttachmentOptions`,
+  `RemoveAttachmentOptions`. `ApprovalInstance` gains `attachments`.
+
 ## [1.6.0] - 2026-09-04
 
 ### Fixed — PostgresAdapter silently dropped most instance updates

package/README.md

@@ -399,6 +399,40 @@ engine.registerConditionOperator('between', (actual, expected) => {
 });
 ```
 
+### Attachments
+
+Attach supporting evidence — a quote PDF, a signed contract, a screenshot of a
+system of record:
+
+```ts
+const withQuote = await engine.addAttachment(instance.id, {
+  actorId: 'buyer-1',
+  name: 'quote.pdf',
+  uri: 's3://procurement/quotes/q-1.pdf',   // a reference, not bytes
+  contentType: 'application/pdf',
+  sizeBytes: 48_120,
+});
+
+await engine.removeAttachment(instance.id, {
+  actorId: 'buyer-1',
+  attachmentId: withQuote.attachments[0].id,
+  reason: 'superseded by revised quote',
+});
+```
+
+**The engine stores references, never bytes.** Approval documents belong in the
+object store or DMS you already run, which handles retention, virus scanning and
+access control far better than an approval table could — copying them here would
+make the audit database the largest and least governed copy of them.
+
+Removing detaches the reference; it never deletes from the underlying store,
+which is the DMS's call. The audit entry keeps the name and URI of what was
+removed, so the trail still shows an approver saw evidence that is no longer
+listed.
+
+Emits `approval:attachment_added` / `approval:attachment_removed`. Allowed on
+any non-terminal instance, subject to your authorization policy.
+
 ### Asking the submitter a question
 
 Approvers routinely need one fact before they can decide. `requestInfo()` puts

package/dist/{ApprovalEngine-SI-IRUMY.d.cts → ApprovalEngine-D16llfJv.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-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 { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-CRSfnH8U.cjs';
+import { l as ConditionExpression, p as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-BE0uJmg3.cjs';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Dy2d0JKy.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-DrJy9UtL.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-Cr0dLoVP.cjs';
-import { I as IMetricsAdapter } from './IMetricsAdapter-JZVK3QUq.cjs';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-DGG-guxK.cjs';
+import { I as IAuditAdapter } from './IAuditAdapter-UJNdJanq.cjs';
+import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.cjs';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BHybAsq5.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-CN6LAaKg.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -78,6 +78,18 @@ declare const ProvideInfoOptionsSchema: z.ZodObject<{
     respondedBy: z.ZodString;
     response: z.ZodString;
 }, z.core.$strip>;
+declare const AddAttachmentOptionsSchema: z.ZodObject<{
+    actorId: z.ZodString;
+    name: z.ZodString;
+    uri: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+    sizeBytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const RemoveAttachmentOptionsSchema: z.ZodObject<{
+    actorId: z.ZodString;
+    attachmentId: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 declare const UpdateDataOptionsSchema: z.ZodObject<{
     updatedBy: z.ZodString;
     data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -101,6 +113,8 @@ type OverrideOptions = z.infer<typeof OverrideOptionsSchema>;
 type UpdateDataOptions = z.infer<typeof UpdateDataOptionsSchema>;
 type RequestInfoOptions = z.infer<typeof RequestInfoOptionsSchema>;
 type ProvideInfoOptions = z.infer<typeof ProvideInfoOptionsSchema>;
+type AddAttachmentOptions = z.infer<typeof AddAttachmentOptionsSchema>;
+type RemoveAttachmentOptions = z.infer<typeof RemoveAttachmentOptionsSchema>;
 
 /**
  * Computes deadline dates from a number of days. The default engine behaviour
@@ -132,7 +146,7 @@ interface WeekendCalendarOptions {
  */
 declare function weekendCalendar(options?: WeekendCalendarOptions): BusinessCalendar;
 
-type IdGeneratorPrefix = 'inst' | 'tpl';
+type IdGeneratorPrefix = 'inst' | 'tpl' | 'att';
 type IdGeneratorFn = (prefix: IdGeneratorPrefix) => string;
 declare const defaultIdGenerator: IdGeneratorFn;
 
@@ -490,6 +504,30 @@ declare class ApprovalEngine {
      * by being held.
      */
     private extendDeadlinesBy;
+    /**
+     * Attach supporting evidence to an approval — a quote PDF, a signed contract,
+     * a screenshot of a system of record.
+     *
+     * Stores a **reference**, never bytes. Approval documents belong in the object
+     * store or DMS the organisation already runs, which handles retention, virus
+     * scanning and access control far better than an approval table could;
+     * copying them here would make the audit database the largest and least
+     * governed copy of them.
+     *
+     * Allowed on any non-terminal instance, by anyone the authorization policy
+     * permits: the submitter adding a missing quote and an approver adding the
+     * note that justifies their decision are both ordinary.
+     */
+    addAttachment(instanceId: string, raw: AddAttachmentOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Detach a reference from an approval.
+     *
+     * The audit entry keeps the name and URI of what was removed, so the record
+     * still shows an approver saw evidence that is no longer listed — dropping
+     * that would let the trail imply a decision was made on less than it was.
+     * Nothing is deleted from the underlying store; that is the DMS's call.
+     */
+    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>;
     /** Resubmit a rejected instance, creating a new linked instance from level 1. */

package/dist/{ApprovalEngine-CyZJDbjP.d.ts → ApprovalEngine-gQdFy2CO.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-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 { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from './IStorageAdapter-DMa5VNNz.js';
+import { l as ConditionExpression, p as ResolverFn, g as ApprovalTemplateConfig, A as ApprovalTemplate, k as AuditContext, a as ApprovalInstance, e as ApprovalMode, b as AuditEntry } from './instance-BE0uJmg3.js';
+import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-Dv_MuYwS.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-rx7XAPrW.js';
-import { I as IAuditAdapter } from './IAuditAdapter-wfOcN3Zf.js';
-import { I as IMetricsAdapter } from './IMetricsAdapter-JZVK3QUq.js';
+import { I as IOperationMiddleware, a as ApprovalError } from './IOperationMiddleware-DWYXVuJD.js';
+import { I as IAuditAdapter } from './IAuditAdapter-DDV4Rf9F.js';
+import { I as IMetricsAdapter } from './IMetricsAdapter-DWq8IFaf.js';
 import { I as ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-CdvoZsGC.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-CFJ-gXKl.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;
@@ -78,6 +78,18 @@ declare const ProvideInfoOptionsSchema: z.ZodObject<{
     respondedBy: z.ZodString;
     response: z.ZodString;
 }, z.core.$strip>;
+declare const AddAttachmentOptionsSchema: z.ZodObject<{
+    actorId: z.ZodString;
+    name: z.ZodString;
+    uri: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+    sizeBytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const RemoveAttachmentOptionsSchema: z.ZodObject<{
+    actorId: z.ZodString;
+    attachmentId: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 declare const UpdateDataOptionsSchema: z.ZodObject<{
     updatedBy: z.ZodString;
     data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -101,6 +113,8 @@ type OverrideOptions = z.infer<typeof OverrideOptionsSchema>;
 type UpdateDataOptions = z.infer<typeof UpdateDataOptionsSchema>;
 type RequestInfoOptions = z.infer<typeof RequestInfoOptionsSchema>;
 type ProvideInfoOptions = z.infer<typeof ProvideInfoOptionsSchema>;
+type AddAttachmentOptions = z.infer<typeof AddAttachmentOptionsSchema>;
+type RemoveAttachmentOptions = z.infer<typeof RemoveAttachmentOptionsSchema>;
 
 /**
  * Computes deadline dates from a number of days. The default engine behaviour
@@ -132,7 +146,7 @@ interface WeekendCalendarOptions {
  */
 declare function weekendCalendar(options?: WeekendCalendarOptions): BusinessCalendar;
 
-type IdGeneratorPrefix = 'inst' | 'tpl';
+type IdGeneratorPrefix = 'inst' | 'tpl' | 'att';
 type IdGeneratorFn = (prefix: IdGeneratorPrefix) => string;
 declare const defaultIdGenerator: IdGeneratorFn;
 
@@ -490,6 +504,30 @@ declare class ApprovalEngine {
      * by being held.
      */
     private extendDeadlinesBy;
+    /**
+     * Attach supporting evidence to an approval — a quote PDF, a signed contract,
+     * a screenshot of a system of record.
+     *
+     * Stores a **reference**, never bytes. Approval documents belong in the object
+     * store or DMS the organisation already runs, which handles retention, virus
+     * scanning and access control far better than an approval table could;
+     * copying them here would make the audit database the largest and least
+     * governed copy of them.
+     *
+     * Allowed on any non-terminal instance, by anyone the authorization policy
+     * permits: the submitter adding a missing quote and an approver adding the
+     * note that justifies their decision are both ordinary.
+     */
+    addAttachment(instanceId: string, raw: AddAttachmentOptions, auditCtx?: AuditContext): Promise<ApprovalInstance>;
+    /**
+     * Detach a reference from an approval.
+     *
+     * The audit entry keeps the name and URI of what was removed, so the record
+     * still shows an approver saw evidence that is no longer listed — dropping
+     * that would let the trail imply a decision was made on less than it was.
+     * Nothing is deleted from the underlying store; that is the DMS's call.
+     */
+    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>;
     /** Resubmit a rejected instance, creating a new linked instance from level 1. */

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

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

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

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

package/dist/{IAuthorizationPolicy-BHybAsq5.d.cts → IAuthorizationPolicy-CFJ-gXKl.d.ts}

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

package/dist/{IAuthorizationPolicy-CdvoZsGC.d.ts → IAuthorizationPolicy-CN6LAaKg.d.cts}

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

package/dist/{IMetricsAdapter-JZVK3QUq.d.cts → IMetricsAdapter-DWq8IFaf.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.info_requested' | 'approval.info_provided' | '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.attachment_added' | 'approval.attachment_removed' | '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-JZVK3QUq.d.ts → IMetricsAdapter-DWq8IFaf.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.info_requested' | 'approval.info_provided' | '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.attachment_added' | 'approval.attachment_removed' | '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-Cn-LNPtD.d.cts → INotificationAdapter-Dv_MuYwS.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-SA0BU-Gb.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-BE0uJmg3.js';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -104,6 +104,14 @@ interface InfoProvidedEvent extends ApprovalEvent {
     /** The approvers waiting again now that the question is answered. */
     recipients: string[];
 }
+/** Emitted when supporting evidence is attached to or removed from an approval. */
+interface AttachmentEvent extends ApprovalEvent {
+    actorId: string;
+    attachmentId: string;
+    name: string;
+    uri: string;
+    level?: number;
+}
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -122,6 +130,8 @@ interface ApprovalEventMap {
     'approval:reminder': ReminderEvent;
     'approval:info_requested': InfoRequestedEvent;
     'approval:info_provided': InfoProvidedEvent;
+    'approval:attachment_added': AttachmentEvent;
+    'approval:attachment_removed': AttachmentEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
 interface HistoryEntry extends AuditEntry {
@@ -145,4 +155,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, InfoProvidedEvent as f, InfoRequestedEvent as g, RejectedEvent as h, ReminderEvent as i, ResubmittedEvent as j, SubmittedEvent as k };
+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, SubmittedEvent as l };

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-SA0BU-Gb.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-BE0uJmg3.cjs';
 
 interface ApprovalEvent {
     instanceId: string;
@@ -104,6 +104,14 @@ interface InfoProvidedEvent extends ApprovalEvent {
     /** The approvers waiting again now that the question is answered. */
     recipients: string[];
 }
+/** Emitted when supporting evidence is attached to or removed from an approval. */
+interface AttachmentEvent extends ApprovalEvent {
+    actorId: string;
+    attachmentId: string;
+    name: string;
+    uri: string;
+    level?: number;
+}
 interface ApprovalEventMap {
     'approval:submitted': SubmittedEvent;
     'approval:approved': ApprovedEvent;
@@ -122,6 +130,8 @@ interface ApprovalEventMap {
     'approval:reminder': ReminderEvent;
     'approval:info_requested': InfoRequestedEvent;
     'approval:info_provided': InfoProvidedEvent;
+    'approval:attachment_added': AttachmentEvent;
+    'approval:attachment_removed': AttachmentEvent;
 }
 type ApprovalEventName = keyof ApprovalEventMap;
 interface HistoryEntry extends AuditEntry {
@@ -145,4 +155,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, InfoProvidedEvent as f, InfoRequestedEvent as g, RejectedEvent as h, ReminderEvent as i, ResubmittedEvent as j, SubmittedEvent as k };
+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, SubmittedEvent as l };

package/dist/{IOperationMiddleware-DrJy9UtL.d.cts → IOperationMiddleware-DGG-guxK.d.cts}

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

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

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

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

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

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

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

package/dist/adapters/PostgresAdapter.cjs

@@ -116,6 +116,7 @@ var PostgresAdapter = class {
         sla_breached_at     TIMESTAMPTZ,
         template_snapshot   JSONB,
         info_request        JSONB,
+        attachments         JSONB NOT NULL DEFAULT '[]',
         created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
         updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
         PRIMARY KEY (tenant_id, id),
@@ -159,6 +160,7 @@ var PostgresAdapter = class {
       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;
+      ALTER TABLE IF EXISTS ${this.p}_instances ADD COLUMN IF NOT EXISTS attachments JSONB NOT NULL DEFAULT '[]';
     `);
   }
   /** Enable PostgreSQL Row Level Security for the instances and audit_log tables. */
@@ -218,9 +220,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, info_request,
+          sla_deadline_at, sla_breached_at, template_snapshot, info_request, attachments,
           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,$23)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22,$23,$24)
        ON CONFLICT (tenant_id, id) DO NOTHING`,
       [
         instance.id,
@@ -244,6 +246,7 @@ var PostgresAdapter = class {
         instance.slaBreachedAt?.toISOString() ?? null,
         instance.templateSnapshot ? JSON.stringify(instance.templateSnapshot) : null,
         instance.infoRequest ? JSON.stringify(instance.infoRequest) : null,
+        JSON.stringify(instance.attachments ?? []),
         instance.createdAt.toISOString(),
         instance.updatedAt.toISOString()
       ]
@@ -269,7 +272,8 @@ var PostgresAdapter = class {
          deadline_action   = $13,
          sla_deadline_at   = $14,
          template_snapshot = $15,
-         info_request      = $16
+         info_request      = $16,
+         attachments       = $17
        WHERE tenant_id = $1 AND id = $2 AND version = $3
        RETURNING id`,
       [
@@ -288,7 +292,8 @@ var PostgresAdapter = class {
         instance.deadlineAction ?? null,
         instance.slaDeadlineAt?.toISOString() ?? null,
         instance.templateSnapshot ? JSON.stringify(instance.templateSnapshot) : null,
-        instance.infoRequest ? JSON.stringify(instance.infoRequest) : null
+        instance.infoRequest ? JSON.stringify(instance.infoRequest) : null,
+        JSON.stringify(instance.attachments ?? [])
       ]
     );
     if (result.rowCount === 0) throw new ApprovalConflictError(instance.id);
@@ -537,6 +542,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,
+      // Absent attachments map to undefined, not [], so a Postgres round trip
+      // returns the same shape MemoryAdapter does for an instance that never
+      // had any — the parity the round-trip test pins down.
+      attachments: (row["attachments"] ?? []).length ? row["attachments"].map((a) => ({ ...a, addedAt: new Date(a.addedAt) })) : void 0,
       infoRequest: row["info_request"] ? {
         ...row["info_request"],
         askedAt: new Date(row["info_request"].askedAt)