@objectstack/plugin-approvals 4.0.1

package/src/approvals-plugin.ts

@@ -0,0 +1,114 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import {
+  SysApprovalProcess,
+  SysApprovalRequest,
+  SysApprovalAction,
+} from '@objectstack/platform-objects/audit';
+import { ApprovalService, type ApprovalEngine } from './approval-service.js';
+import { bindProcessHooks, unbindAllHooks } from './lifecycle-hooks.js';
+
+export interface ApprovalsPluginOptions {
+  /** Disable runtime registration (schemas still register). */
+  disableService?: boolean;
+  /**
+   * Disable Phase B auto-trigger / lock hooks. Schema definition stays
+   * intact; only the engine-level wiring is suppressed. Useful when a
+   * caller wants the manual API only (e.g. tests).
+   */
+  disableAutoHooks?: boolean;
+}
+
+/**
+ * ApprovalsServicePlugin — registers sys_approval_{process,request,action},
+ * the `approvals` service, and Phase B lifecycle hooks (auto-trigger,
+ * record lock, status mirror). SLA escalation dispatcher is a later
+ * milestone.
+ */
+export class ApprovalsServicePlugin implements Plugin {
+  name = 'com.objectstack.service.approvals';
+  version = '1.0.0';
+  type = 'standard';
+  dependencies = ['com.objectstack.engine.objectql'];
+
+  private readonly options: ApprovalsPluginOptions;
+  private service?: ApprovalService;
+  private engine?: any;
+  private logger?: any;
+
+  constructor(options: ApprovalsPluginOptions = {}) {
+    this.options = options;
+  }
+
+  async init(ctx: PluginContext): Promise<void> {
+    ctx.getService<{ register(m: any): void }>('manifest').register({
+      id: 'com.objectstack.service.approvals',
+      name: 'Approvals Service',
+      version: '1.0.0',
+      type: 'plugin',
+      scope: 'system',
+      defaultDatasource: 'cloud',
+      namespace: 'sys',
+      objects: [SysApprovalProcess, SysApprovalRequest, SysApprovalAction],
+    });
+    ctx.logger.info('ApprovalsServicePlugin: schemas registered');
+  }
+
+  async start(ctx: PluginContext): Promise<void> {
+    if (this.options.disableService) return;
+    let engine: any = null;
+    try { engine = ctx.getService<any>('objectql'); }
+    catch { try { engine = ctx.getService<any>('data'); } catch { /* ignore */ } }
+    if (!engine) {
+      ctx.logger.warn('ApprovalsServicePlugin: no ObjectQL engine — service NOT registered');
+      return;
+    }
+    this.engine = engine;
+    this.logger = ctx.logger;
+
+    this.service = new ApprovalService({
+      engine: engine as ApprovalEngine,
+      logger: ctx.logger,
+    });
+
+    if (!this.options.disableAutoHooks) {
+      // Re-bind hooks on every registry mutation.
+      this.service.setRegistryChangeHandler(() => this.rebindHooks());
+      // Initial bind happens once the kernel is ready so the AppPlugin's
+      // declarative process seeder has already populated sys_approval_process.
+      const hookOn = (ctx as any).hook ?? (ctx as any).on;
+      if (typeof hookOn === 'function') {
+        try {
+          hookOn.call(ctx, 'kernel:ready', async () => { await this.rebindHooks(); });
+        } catch {
+          // Fall through to immediate bind (no kernel:ready event).
+          await this.rebindHooks();
+        }
+      } else {
+        await this.rebindHooks();
+      }
+    }
+
+    ctx.registerService('approvals', this.service);
+    ctx.logger.info('ApprovalsServicePlugin: service registered');
+  }
+
+  private async rebindHooks(): Promise<void> {
+    if (!this.engine || !this.service) return;
+    try {
+      unbindAllHooks(this.engine);
+      const processes = await this.service.listProcesses({ activeOnly: true }, { isSystem: true, roles: [], permissions: [] } as any);
+      bindProcessHooks(this.engine, this.service, processes, this.logger);
+    } catch (err: any) {
+      this.logger?.warn?.('[approvals] rebindHooks failed', { error: err?.message });
+    }
+  }
+
+  async stop(_ctx: PluginContext): Promise<void> {
+    if (this.engine) {
+      try { unbindAllHooks(this.engine); } catch { /* ignore */ }
+    }
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,36 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * @objectstack/plugin-approvals
+ *
+ * Multi-step approval engine for ObjectStack.
+ * Persists sys_approval_process / sys_approval_request / sys_approval_action
+ * and drives the cycle: submit → review → approve/reject → effects.
+ */
+
+export {
+  SysApprovalProcess,
+  SysApprovalRequest,
+  SysApprovalAction,
+} from '@objectstack/platform-objects/audit';
+export {
+  ApprovalService,
+  type ApprovalEngine,
+  type ApprovalClock,
+  type ApprovalServiceOptions,
+} from './approval-service.js';
+export {
+  ApprovalsServicePlugin,
+  type ApprovalsPluginOptions,
+} from './approvals-plugin.js';
+export type {
+  IApprovalService,
+  ApprovalProcessRow,
+  ApprovalRequestRow,
+  ApprovalActionRow,
+  ApprovalDecisionInput,
+  ApprovalDecisionResult,
+  ApprovalStatus,
+  DefineApprovalProcessInput,
+  SubmitApprovalInput,
+} from '@objectstack/spec/contracts';

package/src/lifecycle-hooks.ts

@@ -0,0 +1,250 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Lifecycle Hooks — Phase B auto-takeover.
+ *
+ * For each active ApprovalProcess we bind three hooks on its target object:
+ *
+ *   1. `afterInsert` — evaluate `entryCriteria` against the new record;
+ *      if truthy and no pending request exists, auto-submit one.
+ *   2. `afterUpdate` — same as above but for updates that newly satisfy
+ *      criteria (e.g. amount edited above threshold).
+ *   3. `beforeUpdate` — when `lockRecord=true`, block edits to a record
+ *      that has a pending request, EXCEPT when the only fields being
+ *      changed are the configured `approvalStatusField` (so the engine's
+ *      own status mirror is not blocked).
+ *
+ * All hooks are registered with `packageId: 'plugin-approvals:auto'` so
+ * that re-bind on `defineProcess`/`deleteProcess` can call
+ * `engine.unregisterHooksByPackage(...)` first.
+ */
+
+import { ExpressionEngine } from '@objectstack/formula';
+import type { Expression } from '@objectstack/spec';
+import type { ApprovalProcessRow } from '@objectstack/spec/contracts';
+import type { ApprovalService } from './approval-service.js';
+
+export const APPROVALS_HOOK_PACKAGE = 'plugin-approvals:auto';
+
+const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as const;
+
+interface MinimalEngine {
+  registerHook(event: string, handler: (ctx: any) => any | Promise<any>, options?: {
+    object?: string | string[];
+    priority?: number;
+    packageId?: string;
+  }): void;
+  unregisterHooksByPackage(packageId: string): number;
+  find<T = any>(object: string, args: any, opts?: any): Promise<T[]>;
+}
+
+interface MinimalLogger {
+  debug?: (msg: any, ...rest: any[]) => void;
+  info?: (msg: any, ...rest: any[]) => void;
+  warn?: (msg: any, ...rest: any[]) => void;
+  error?: (msg: any, ...rest: any[]) => void;
+}
+
+/**
+ * Evaluate an entry criteria expression against a record. Returns `true`
+ * when no criteria is set (matches everything). Returns `false` on
+ * evaluation failure (fail-closed — better to skip than auto-submit on a
+ * broken expression).
+ */
+function evaluateCriteria(criteria: unknown, record: Record<string, unknown>, logger?: MinimalLogger): boolean {
+  if (criteria == null || criteria === '' ) return true;
+  let expr: Expression;
+  if (typeof criteria === 'string') {
+    expr = { dialect: 'cel', source: criteria };
+  } else if (typeof criteria === 'object' && (criteria as any).dialect) {
+    expr = criteria as Expression;
+  } else {
+    return true;
+  }
+  if (!expr.source || !expr.source.trim()) return true;
+  const r = ExpressionEngine.evaluate<boolean>(expr, { record });
+  if (!r.ok) {
+    logger?.warn?.('[approvals] entryCriteria evaluation failed; skipping auto-submit', {
+      source: expr.source,
+      error: r.error.message,
+    });
+    return false;
+  }
+  return Boolean(r.value);
+}
+
+/** Does this record already have a pending approval request? */
+async function hasPendingRequest(
+  engine: MinimalEngine,
+  objectName: string,
+  recordId: string,
+): Promise<boolean> {
+  try {
+    const rows = await engine.find('sys_approval_request', {
+      where: { object_name: objectName, record_id: String(recordId), status: 'pending' },
+      limit: 1,
+    } as any);
+    return Array.isArray(rows) && rows.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Bind auto-trigger + lock hooks for the supplied active processes.
+ * Caller is responsible for calling `unbindAll` first if re-binding.
+ */
+export function bindProcessHooks(
+  engine: MinimalEngine,
+  service: ApprovalService,
+  processes: ApprovalProcessRow[],
+  logger?: MinimalLogger,
+): void {
+  // Group processes by object so we can register one hook per object
+  // and fan out internally — keeps the engine's hook map compact.
+  const byObject = new Map<string, ApprovalProcessRow[]>();
+  for (const p of processes) {
+    if (!(p as any).active && !(p as any).is_active) continue;
+    if (!p.object_name) continue;
+    const list = byObject.get(p.object_name) ?? [];
+    list.push(p);
+    byObject.set(p.object_name, list);
+  }
+
+  for (const [objectName, procs] of byObject.entries()) {
+    // ---- auto-trigger (afterInsert) ----
+    engine.registerHook('afterInsert', async (ctx: any) => {
+      try {
+        const record = (ctx?.result ?? ctx?.input?.data ?? {}) as Record<string, unknown>;
+        const id = String((record as any)?.id ?? '');
+        if (!id) return;
+        for (const proc of procs) {
+          await tryAutoSubmit(engine, service, proc, objectName, id, record, ctx, logger);
+        }
+      } catch (err: any) {
+        logger?.warn?.('[approvals] afterInsert auto-trigger failed', { error: err?.message });
+      }
+    }, { object: objectName, packageId: APPROVALS_HOOK_PACKAGE, priority: 200 });
+
+    // ---- auto-trigger (afterUpdate) ----
+    engine.registerHook('afterUpdate', async (ctx: any) => {
+      // Ignore engine self-writes (status mirror, field_update from
+      // post-actions, etc) — otherwise post-finalize updates would loop
+      // a fresh approval on every state change.
+      if ((ctx?.session as any)?.isSystem) return;
+      try {
+        const result = (ctx?.result ?? {}) as Record<string, unknown>;
+        const id = String((ctx?.input?.id ?? (result as any)?.id ?? '') as string);
+        if (!id) return;
+        // result may be { affected: 1 } for some drivers; merge previous+input.data as the
+        // best-effort record snapshot for criteria evaluation.
+        const record: Record<string, unknown> = {
+          ...(ctx?.previous ?? {}),
+          ...((result as any)?.id ? result : {}),
+          ...((ctx?.input?.data ?? {}) as Record<string, unknown>),
+          id,
+        };
+        for (const proc of procs) {
+          await tryAutoSubmit(engine, service, proc, objectName, id, record, ctx, logger);
+        }
+      } catch (err: any) {
+        logger?.warn?.('[approvals] afterUpdate auto-trigger failed', { error: err?.message });
+      }
+    }, { object: objectName, packageId: APPROVALS_HOOK_PACKAGE, priority: 200 });
+
+    // ---- record lock (beforeUpdate) ----
+    const lockProcs = procs.filter((p) => (p.definition as any)?.lockRecord !== false);
+    if (lockProcs.length === 0) continue;
+    engine.registerHook('beforeUpdate', async (ctx: any) => {
+      const id = String((ctx?.input?.id ?? '') as string);
+      if (!id) return;
+      const data = (ctx?.input?.data ?? {}) as Record<string, unknown>;
+      const changedFields = Object.keys(data).filter((k) => k !== 'id' && k !== 'updated_at');
+      if (changedFields.length === 0) return;
+
+      // Allow engine self-writes (status mirror, field_update from actions, etc).
+      if ((ctx?.session as any)?.isSystem) return;
+
+      // Allow when every changed field is an approval status mirror.
+      const mirrorFields = new Set<string>();
+      for (const p of lockProcs) {
+        const f = (p.definition as any)?.approvalStatusField;
+        if (typeof f === 'string' && f) mirrorFields.add(f);
+      }
+      const onlyMirror = changedFields.every((f) => mirrorFields.has(f));
+      if (onlyMirror) return;
+
+      // Allow admin override: roles include 'admin'.
+      const roles = (ctx?.session?.roles ?? []) as string[];
+      if (Array.isArray(roles) && roles.includes('admin')) return;
+
+      const pending = await hasPendingRequest(engine, objectName, id);
+      if (!pending) return;
+
+      const err: any = new Error('RECORD_LOCKED: record is locked while an approval is in progress');
+      err.code = 'RECORD_LOCKED';
+      err.statusCode = 409;
+      throw err;
+    }, { object: objectName, packageId: APPROVALS_HOOK_PACKAGE, priority: 50 });
+  }
+
+  logger?.info?.('[approvals] lifecycle hooks bound', {
+    objects: Array.from(byObject.keys()),
+    processCount: processes.length,
+  });
+}
+
+/** Unregister every hook the auto-trigger module ever registered. */
+export function unbindAllHooks(engine: MinimalEngine): number {
+  return engine.unregisterHooksByPackage(APPROVALS_HOOK_PACKAGE);
+}
+
+async function tryAutoSubmit(
+  engine: MinimalEngine,
+  service: ApprovalService,
+  process: ApprovalProcessRow,
+  objectName: string,
+  recordId: string,
+  record: Record<string, unknown>,
+  ctx: any,
+  logger?: MinimalLogger,
+): Promise<void> {
+  try {
+    const criteria = (process.definition as any)?.entryCriteria;
+    const passes = evaluateCriteria(criteria, record, logger);
+    if (!passes) return;
+    if (await hasPendingRequest(engine, objectName, recordId)) return;
+    // Guard: if the record's mirror status field is already a terminal
+    // state (approved / rejected / recalled), do NOT auto-submit again —
+    // otherwise every post-finalize edit would loop a fresh approval.
+    const statusField = (process.definition as any)?.approvalStatusField;
+    if (statusField) {
+      const current = (record as any)?.[statusField];
+      if (current === 'approved' || current === 'rejected' || current === 'recalled') return;
+    }
+
+    const submitterId = (ctx?.session?.userId ?? null) as string | null;
+    const submitterOrg = (ctx?.session?.tenantId ?? ctx?.session?.organizationId ?? null) as string | null;
+    await service.submit({
+      object: objectName,
+      recordId,
+      processName: process.name,
+      payload: record,
+      submitterId,
+    }, { ...SYSTEM_CTX, userId: submitterId ?? undefined, organizationId: submitterOrg ?? undefined, tenantId: submitterOrg ?? undefined } as any);
+
+    logger?.info?.('[approvals] auto-submitted approval', {
+      process: process.name,
+      object: objectName,
+      record: recordId,
+    });
+  } catch (err: any) {
+    if (err?.code === 'DUPLICATE_REQUEST') return;
+    logger?.warn?.('[approvals] auto-submit failed', {
+      process: process.name,
+      object: objectName,
+      record: recordId,
+      error: err?.message ?? String(err),
+    });
+  }
+}

package/src/phase-b.test.ts

@@ -0,0 +1,263 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Phase B integration tests.
+ *
+ *  - status mirror (`approvalStatusField` on the business record)
+ *  - process-level `onSubmit / onFinalApprove / onFinalReject / onRecall`
+ *  - step-level `onApprove / onReject`
+ *  - `inbox_notify` action writes `sys_notification` rows
+ *  - `field_update` action writes the business record (token interpolation)
+ *  - lifecycle hooks: afterInsert auto-submit, lock on beforeUpdate, allow
+ *    status-mirror writes through, allow admin override.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ApprovalService } from './approval-service.js';
+import { bindProcessHooks, unbindAllHooks } from './lifecycle-hooks.js';
+
+interface FakeRow { [k: string]: any }
+
+function makeFakeEngine() {
+  const tables: Record<string, FakeRow[]> = {};
+  const ensure = (n: string) => (tables[n] ??= []);
+  const hooks: Record<string, Array<{ handler: (ctx: any) => any | Promise<any>; object?: string | string[]; packageId?: string }>> = {};
+
+  function matches(row: FakeRow, filter: any): boolean {
+    if (!filter || typeof filter !== 'object') return true;
+    for (const [k, v] of Object.entries(filter)) {
+      if (row[k] !== v) return false;
+    }
+    return true;
+  }
+
+  async function fire(event: string, ctx: any) {
+    const list = hooks[event] ?? [];
+    for (const h of list) {
+      if (h.object) {
+        const objs = Array.isArray(h.object) ? h.object : [h.object];
+        if (!objs.includes(ctx.object)) continue;
+      }
+      await h.handler(ctx);
+    }
+  }
+
+  return {
+    _tables: tables,
+    _hooks: hooks,
+    async find(object: string, options?: any, _opts?: any) {
+      const rows = ensure(object).filter(r => matches(r, options?.filter ?? options?.where));
+      return rows.slice(0, options?.limit ?? 1000);
+    },
+    async insert(object: string, data: any, opts?: any) {
+      const row = { ...data };
+      ensure(object).push(row);
+      const ctx = { object, event: 'afterInsert', result: row, input: { data: row }, session: opts?.context ?? {} };
+      await fire('afterInsert', ctx);
+      return row;
+    },
+    async update(object: string, idOrData: any, opts?: any) {
+      const data = typeof idOrData === 'object' ? idOrData : opts;
+      const id = typeof idOrData === 'object' ? idOrData.id : idOrData;
+      // beforeUpdate (skip status-mirror writes from system context — the
+      // hook itself decides via the `data.keys ⊆ approvalStatusField` rule).
+      const beforeCtx = { object, event: 'beforeUpdate', input: { id, data }, session: opts?.context ?? {} };
+      await fire('beforeUpdate', beforeCtx);
+      const table = ensure(object);
+      const i = table.findIndex(r => r.id === id);
+      if (i >= 0) table[i] = { ...table[i], ...data };
+      const after = table[i];
+      const afterCtx = { object, event: 'afterUpdate', input: { id, data }, result: after, session: opts?.context ?? {} };
+      await fire('afterUpdate', afterCtx);
+      return after;
+    },
+    async delete(object: string, options?: any) {
+      const table = ensure(object);
+      const id = options?.where?.id ?? options?.id;
+      const i = table.findIndex(r => r.id === id);
+      if (i >= 0) table.splice(i, 1);
+      return { id };
+    },
+    registerHook(event: string, handler: any, options?: any) {
+      (hooks[event] ??= []).push({ handler, object: options?.object, packageId: options?.packageId });
+    },
+    unregisterHooksByPackage(packageId: string) {
+      let removed = 0;
+      for (const ev of Object.keys(hooks)) {
+        const before = hooks[ev].length;
+        hooks[ev] = hooks[ev].filter(h => h.packageId !== packageId);
+        removed += before - hooks[ev].length;
+      }
+      return removed;
+    },
+  };
+}
+
+const SYS = { isSystem: true, roles: [], permissions: [] };
+const USR = { userId: 'submitter', roles: [], permissions: [] };
+
+function processWithMirror() {
+  return {
+    name: 'discount_approval',
+    label: 'Discount Approval',
+    object: 'opportunity',
+    active: true,
+    approvalStatusField: 'approval_status',
+    lockRecord: true,
+    entryCriteria: 'record.amount > 50000',
+    onSubmit: [
+      {
+        type: 'inbox_notify' as const,
+        name: 'notify_pending',
+        config: {
+          to: 'pending_approvers',
+          title: 'Discount needs approval',
+          body: 'Opportunity {record_id} amount review',
+        },
+      },
+    ],
+    onFinalApprove: [
+      { type: 'field_update' as const, name: 'close_won', config: { field: 'stage', value: 'closed_won' } },
+    ],
+    onFinalReject: [
+      { type: 'inbox_notify' as const, name: 'tell_submitter', config: { to: 'submitter', title: 'Rejected', body: 'Sorry' } },
+    ],
+    onRecall: [
+      { type: 'inbox_notify' as const, name: 'recalled', config: { to: 'submitter', title: 'Recalled', body: 'Pulled back' } },
+    ],
+    steps: [
+      {
+        name: 'sales_manager',
+        label: 'Sales Manager',
+        approvers: [{ type: 'user' as const, value: 'manager' }],
+        behavior: 'first_response' as const,
+      },
+    ],
+  };
+}
+
+describe('Phase B — approval auto-takeover', () => {
+  let engine: ReturnType<typeof makeFakeEngine>;
+  let svc: ApprovalService;
+
+  beforeEach(() => {
+    engine = makeFakeEngine();
+    svc = new ApprovalService({ engine: engine as any });
+  });
+
+  describe('status mirror + actions', () => {
+    beforeEach(async () => {
+      // Seed a business record so syncStatusField can update it.
+      engine._tables.opportunity = [{ id: 'opp1', amount: 80000, stage: 'qualification', approval_status: 'not_submitted' }];
+      await svc.defineProcess({
+        name: 'discount_approval',
+        label: 'Discount Approval',
+        object: 'opportunity',
+        definition: processWithMirror(),
+      }, SYS as any);
+    });
+
+    it('writes onSubmit notifications and mirrors status to the business record', async () => {
+      await svc.submit({ object: 'opportunity', recordId: 'opp1', submitterId: 'submitter', payload: engine._tables.opportunity[0] }, USR as any);
+
+      // status mirrored.
+      const opp = engine._tables.opportunity[0];
+      expect(opp.approval_status).toBe('pending');
+
+      // inbox notification written to pending approvers.
+      const notes = engine._tables.sys_notification ?? [];
+      expect(notes.length).toBeGreaterThanOrEqual(1);
+      expect(notes.some(n => n.recipient_id === 'manager' && /Opportunity opp1/.test(n.body))).toBe(true);
+    });
+
+    it('runs onFinalApprove field_update on finalize, mirrors status=approved', async () => {
+      const submitted = await svc.submit({ object: 'opportunity', recordId: 'opp1', submitterId: 'submitter', payload: engine._tables.opportunity[0] }, USR as any);
+      await svc.approve(submitted.id, { actorId: 'manager' }, SYS as any);
+
+      const opp = engine._tables.opportunity[0];
+      expect(opp.stage).toBe('closed_won');
+      expect(opp.approval_status).toBe('approved');
+    });
+
+    it('runs onFinalReject inbox_notify on rejection, mirrors status=rejected', async () => {
+      const submitted = await svc.submit({ object: 'opportunity', recordId: 'opp1', submitterId: 'submitter', payload: engine._tables.opportunity[0] }, USR as any);
+      await svc.reject(submitted.id, { actorId: 'manager', comment: 'too low' }, SYS as any);
+
+      const opp = engine._tables.opportunity[0];
+      expect(opp.approval_status).toBe('rejected');
+      const notes = engine._tables.sys_notification ?? [];
+      expect(notes.some(n => n.recipient_id === 'submitter' && n.title === 'Rejected')).toBe(true);
+    });
+
+    it('runs onRecall and mirrors status=recalled', async () => {
+      const submitted = await svc.submit({ object: 'opportunity', recordId: 'opp1', submitterId: 'submitter', payload: engine._tables.opportunity[0] }, USR as any);
+      await svc.recall(submitted.id, { actorId: 'submitter' }, USR as any);
+
+      const opp = engine._tables.opportunity[0];
+      expect(opp.approval_status).toBe('recalled');
+      const notes = engine._tables.sys_notification ?? [];
+      expect(notes.some(n => n.title === 'Recalled')).toBe(true);
+    });
+  });
+
+  describe('lifecycle hooks', () => {
+    beforeEach(async () => {
+      await svc.defineProcess({
+        name: 'discount_approval',
+        label: 'Discount Approval',
+        object: 'opportunity',
+        definition: processWithMirror(),
+      }, SYS as any);
+      const procs = await svc.listProcesses({ activeOnly: true }, SYS as any);
+      bindProcessHooks(engine as any, svc, procs);
+    });
+
+    it('auto-submits a request when an inserted record matches entryCriteria', async () => {
+      await engine.insert('opportunity', { id: 'opp_high', amount: 100000, stage: 'qualification' });
+      // Drain microtasks (insert kicks off the hook).
+      await new Promise(r => setTimeout(r, 0));
+      const requests = engine._tables.sys_approval_request ?? [];
+      expect(requests.length).toBe(1);
+      expect(requests[0].object_name).toBe('opportunity');
+      expect(requests[0].record_id).toBe('opp_high');
+    });
+
+    it('does NOT auto-submit when entryCriteria evaluates to false', async () => {
+      await engine.insert('opportunity', { id: 'opp_low', amount: 1000, stage: 'qualification' });
+      await new Promise(r => setTimeout(r, 0));
+      expect(engine._tables.sys_approval_request ?? []).toHaveLength(0);
+    });
+
+    it('does NOT double-submit when criteria continues to be true on update', async () => {
+      await engine.insert('opportunity', { id: 'opp_dup', amount: 100000, stage: 'qualification' });
+      await new Promise(r => setTimeout(r, 0));
+      await engine.update('opportunity', { id: 'opp_dup', amount: 110000 }, { context: { ...SYS, roles: ['admin'] } });
+      await new Promise(r => setTimeout(r, 0));
+      expect((engine._tables.sys_approval_request ?? []).length).toBe(1);
+    });
+
+    it('lock hook blocks edits to a locked record', async () => {
+      await engine.insert('opportunity', { id: 'opp_lock', amount: 100000, stage: 'qualification' });
+      await new Promise(r => setTimeout(r, 0));
+      await expect(
+        engine.update('opportunity', { id: 'opp_lock', stage: 'closed_won' }, { context: { userId: 'u1', roles: [] } }),
+      ).rejects.toThrow(/RECORD_LOCKED/);
+    });
+
+    it('lock hook allows admin role override', async () => {
+      await engine.insert('opportunity', { id: 'opp_admin', amount: 100000, stage: 'qualification' });
+      await new Promise(r => setTimeout(r, 0));
+      await expect(
+        engine.update('opportunity', { id: 'opp_admin', stage: 'closed_won' }, { context: { userId: 'admin', roles: ['admin'] } }),
+      ).resolves.toBeTruthy();
+    });
+
+    it('unbindAllHooks removes registered hooks idempotently', async () => {
+      const removed = unbindAllHooks(engine as any);
+      expect(removed).toBeGreaterThan(0);
+      // Re-bind to default state for any later beforeEach.
+      const procs = await svc.listProcesses({ activeOnly: true }, SYS as any);
+      bindProcessHooks(engine as any, svc, procs);
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules", "**/*.test.ts"]
+}