hierarchical-approval 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,46 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [1.2.0] - 2026-09-04
+
+### Added — template inheritance
+
+- **`extends` derives one template from another.** ERP tenants run many
+  near-identical workflows — one per region, legal entity or document class —
+  that share a spine and differ in a level or two. Each had to be written out in
+  full, so a change to the shared part meant editing every copy and hoping none
+  were missed.
+
+  ```ts
+  await engine.defineTemplate({
+    name: 'PO-EU',
+    extends: 'PO-base',
+    documentType: 'purchase_order',
+    removeLevels: [2],
+    levels: [{ level: 3, approvers: [{ type: 'user', userId: 'eu-fin' }] }],
+  });
+  ```
+
+  Levels are keyed by number: a child level overrides the base level *field by
+  field* (so a derived template can swap just the approvers and inherit name,
+  mode and deadlines), child-only levels are appended, and `removeLevels` drops
+  inherited ones. `conditions` are replaced wholesale when supplied — merging
+  two rule lists would produce a chain neither author intended. `escalation`,
+  `slaDeadlineDays` and `allowOverride` are inherited unless the child sets them.
+
+- **Resolution happens once, at define time, and the flattened result is what
+  gets stored.** Resolving lazily on read would mean editing a base silently
+  reshapes every derived template — and every in-flight instance running against
+  one — which is exactly the surprise `templateSnapshot` exists to prevent
+  elsewhere in the engine. A base that itself extends something is already
+  flattened, so chains resolve naturally and cycles cannot form.
+
+- **Validation runs on the flattened template**, not the fragment: a derived
+  config carrying no levels of its own is valid (it inherits the chain), while
+  one whose `removeLevels` strips the chain entirely is rejected at definition
+  time. `extends` and `removeLevels` are directives for the call and are not
+  persisted.
+
 ## [1.1.0] - 2026-09-04
 
 ### Added — approval reminders

package/README.md

@@ -399,6 +399,40 @@ engine.registerConditionOperator('between', (actual, expected) => {
 });
 ```
 
+### Template inheritance
+
+ERP tenants run many near-identical workflows — one per region, entity or
+document class — that share a spine and differ in a level or two. `extends`
+derives one template from another:
+
+```ts
+await engine.defineTemplate({
+  name: 'PO-EU',
+  extends: 'PO-base',
+  documentType: 'purchase_order',
+  removeLevels: [2],                       // drop an inherited level
+  levels: [
+    { level: 3, approvers: [{ type: 'user', userId: 'eu-fin' }] },  // override just the approvers
+    { level: 4, name: 'EU Compliance', approvers: [...], mode: 'any' }, // add a new level
+  ],
+});
+```
+
+| Field | Merge rule |
+|---|---|
+| `levels` | Keyed by level number: a child level overrides the base level *field by field*, child-only levels are appended, `removeLevels` drops inherited ones |
+| `conditions` | Replaced wholesale when the child supplies them |
+| `escalation`, `slaDeadlineDays`, `allowOverride` | Child value if set, otherwise inherited |
+
+**Resolution happens once, at define time, and the flattened result is stored.**
+Editing a base later never silently reshapes a derived template or an instance
+already running against one — the same insulation `templateSnapshot` gives
+in-flight instances. A base that itself extends something is already flattened,
+so chains resolve naturally and cycles cannot form.
+
+Validation runs on the *flattened* template, so a derived config that strips its
+whole chain is rejected at definition time.
+
 ### Reminders
 
 Escalation reassigns work; a reminder only nudges, which is usually what an

package/dist/{ApprovalEngine-qwImBe9A.d.cts → ApprovalEngine-CdtOJOsu.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-BZarNxs9.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-DuEgSIIz.cjs';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-BKwhxhe2.cjs';
+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 { 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-D162RiJs.cjs';
-import { I as IAuditAdapter } from './IAuditAdapter-CWdZxS3U.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 ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.cjs';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-ChZIUJhQ.cjs';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-BHDZK9QL.cjs';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;

package/dist/{ApprovalEngine-BDnQwKi9.d.ts → ApprovalEngine-DRC-o30z.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-DrY-rhhF.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-DuEgSIIz.js';
-import { I as INotificationAdapter, b as ApprovalEventName, a as ApprovalEventMap } from './INotificationAdapter-CsSWiCZE.js';
+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 { 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-CPkGSVfr.js';
-import { I as IAuditAdapter } from './IAuditAdapter-99JBU3Db.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 ISchedulerAdapter } from './ISchedulerAdapter-DKv_QjVN.js';
-import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-U-jZrl2F.js';
+import { I as IAuthorizationPolicy } from './IAuthorizationPolicy-4ge9Gnxj.js';
 
 declare const SubmitOptionsSchema: z.ZodObject<{
     templateName: z.ZodString;

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

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

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

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

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

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

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

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

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

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-DuEgSIIz.cjs';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-BsM0DUPf.cjs';
 
 interface ApprovalEvent {
     instanceId: string;

package/dist/{INotificationAdapter-CsSWiCZE.d.ts → INotificationAdapter-BmSeB7FZ.d.ts}

@@ -1,4 +1,4 @@
-import { a as ApprovalInstance, b as AuditEntry } from './instance-DuEgSIIz.js';
+import { a as ApprovalInstance, b as AuditEntry } from './instance-BsM0DUPf.js';
 
 interface ApprovalEvent {
     instanceId: string;

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

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

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

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

package/dist/{IStorageAdapter-BZarNxs9.d.cts → IStorageAdapter-CKV_FZFV.d.cts}

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

package/dist/{IStorageAdapter-DrY-rhhF.d.ts → IStorageAdapter-DQJmR6Mt.d.ts}

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

package/dist/adapters/PostgresAdapter.d.cts

@@ -1,7 +1,7 @@
 import * as tls from 'tls';
 import * as pg from 'pg';
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-BZarNxs9.cjs';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-DuEgSIIz.cjs';
+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 { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BsM0DUPf.cjs';
 
 interface PostgresAdapterOptions {
     connectionString?: string;

package/dist/adapters/PostgresAdapter.d.ts

@@ -1,7 +1,7 @@
 import * as tls from 'tls';
 import * as pg from 'pg';
-import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-DrY-rhhF.js';
-import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-DuEgSIIz.js';
+import { I as IStorageAdapter, P as PaginationOpts, a as PaginatedResult, b as InstanceFilter, C as CursorPaginationOpts, c as CursorPaginatedResult } from '../IStorageAdapter-DQJmR6Mt.js';
+import { A as ApprovalTemplate, a as ApprovalInstance, b as AuditEntry } from '../instance-BsM0DUPf.js';
 
 interface PostgresAdapterOptions {
     connectionString?: string;

package/dist/index.cjs

@@ -224,6 +224,66 @@ var TemplateRegistry = class {
     this.clock = opts?.clock ?? systemClock;
     this.generateId = opts?.generateId ?? defaultIdGenerator;
   }
+  /**
+   * Flatten a template that declares `extends` against its base.
+   *
+   * Resolution is done once, at define time, and the flattened result is what
+   * gets stored. Resolving lazily on read would mean editing a base silently
+   * reshapes every derived template — and every in-flight instance running
+   * against one — which is exactly the surprise `templateSnapshot` exists to
+   * prevent elsewhere in the engine.
+   *
+   * Merge rules:
+   * - **Levels** are keyed by level number. A child level with the same number
+   *   overrides the base level field by field, so a derived template can change
+   *   just the approvers and inherit the rest. Child-only levels are appended,
+   *   and `removeLevels` drops inherited ones.
+   * - **conditions** are replaced wholesale when the child supplies them.
+   *   Concatenating two rule lists would produce a chain neither author
+   *   intended, and there is no meaningful way to "merge" boolean rules.
+   * - **escalation**, **slaDeadlineDays** and **allowOverride** are taken from
+   *   the child when set, otherwise inherited.
+   *
+   * A base that itself extends something is already flattened in storage, so
+   * chains resolve naturally and cycles cannot form: the base must exist before
+   * the child can name it.
+   *
+   * @param config - The raw config as supplied by the caller.
+   * @returns The config with inheritance applied, or unchanged if no `extends`.
+   */
+  async resolveInheritance(config) {
+    if (!config.extends) return config;
+    if (config.extends === config.name) {
+      throw new ApprovalValidationError(`Template "${config.name}" cannot extend itself.`);
+    }
+    const base = await this.adapter.getTemplate(this.tenantId, config.extends);
+    if (!base) {
+      throw new ApprovalTemplateNotFoundError(
+        `${config.extends} (referenced by "${config.name}" via extends)`
+      );
+    }
+    const removed = new Set(config.removeLevels ?? []);
+    const byLevel = /* @__PURE__ */ new Map();
+    for (const lvl of base.levels) {
+      if (!removed.has(lvl.level)) byLevel.set(lvl.level, lvl);
+    }
+    for (const lvl of config.levels ?? []) {
+      const inherited = byLevel.get(lvl.level);
+      byLevel.set(lvl.level, inherited ? { ...inherited, ...lvl } : lvl);
+    }
+    const levels = [...byLevel.values()].sort((a, b) => a.level - b.level);
+    const resolved = {
+      ...config,
+      levels,
+      conditions: config.conditions ?? base.conditions,
+      escalation: config.escalation ?? base.escalation,
+      slaDeadlineDays: config.slaDeadlineDays ?? base.slaDeadlineDays,
+      allowOverride: config.allowOverride ?? base.allowOverride
+    };
+    delete resolved.extends;
+    delete resolved.removeLevels;
+    return resolved;
+  }
   async define(config) {
     const existing = await this.adapter.getTemplate(this.tenantId, config.name);
     if (existing) {
@@ -855,9 +915,11 @@ var ApprovalEngine = class _ApprovalEngine {
   /** Validate a template config without persisting. Synchronous; never throws. */
   validateTemplate(config) {
     const errors = [];
-    if (!config.levels || config.levels.length === 0) {
+    const hasOwnLevels = Boolean(config.levels && config.levels.length > 0);
+    if (!hasOwnLevels && config.extends === void 0) {
       errors.push({ field: "levels", message: "Template must have at least one level." });
-    } else {
+    }
+    if (hasOwnLevels) {
       const levelNums = /* @__PURE__ */ new Set();
       config.levels.forEach((l, i) => {
         if (levelNums.has(l.level)) {
@@ -986,25 +1048,27 @@ var ApprovalEngine = class _ApprovalEngine {
     return { valid: errors.length === 0, errors };
   }
   async defineTemplate(config) {
-    const validation = this.validateTemplate(config);
+    const resolved = await this.registry.resolveInheritance(config);
+    const validation = this.validateTemplate(resolved);
     if (!validation.valid) {
       const first = validation.errors[0];
       throw new ApprovalValidationError(
         `Invalid template configuration: ${first?.message ?? "unknown error"}`
       );
     }
-    return this.registry.define(config);
+    return this.registry.define(resolved);
   }
   /** Update an existing template, incrementing its version. In-flight instances are protected by their templateSnapshot. */
   async updateTemplate(config) {
-    const validation = this.validateTemplate(config);
+    const resolved = await this.registry.resolveInheritance(config);
+    const validation = this.validateTemplate(resolved);
     if (!validation.valid) {
       const first = validation.errors[0];
       throw new ApprovalValidationError(
         `Invalid template configuration: ${first?.message ?? "unknown error"}`
       );
     }
-    return this.registry.update(config);
+    return this.registry.update(resolved);
   }
   async getTemplate(name) {
     return this.registry.get(name);