@objectstack/plugin-approvals 16.1.0 → 17.0.0-rc.1

package/src/approvals-plugin.ts

@@ -1,263 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Plugin, PluginContext } from '@objectstack/core';
-import { SysApprovalRequest } from './sys-approval-request.object.js';
-import { SysApprovalAction } from './sys-approval-action.object.js';
-import { SysApprovalApprover } from './sys-approval-approver.object.js';
-import { SysApprovalToken } from './sys-approval-token.object.js';
-import { SysApprovalDelegation } from './sys-approval-delegation.object.js';
-import { renderConfirmPage, renderResultPage } from './action-link-pages.js';
-import {
-  ApprovalService,
-  ESCALATION_JOB_NAME,
-  ESCALATION_SCAN_INTERVAL_MS,
-  type ApprovalEngine,
-} from './approval-service.js';
-import { bindApprovalLockHook, bindDelegationWriteGuard, unbindAllHooks } from './lifecycle-hooks.js';
-import { registerApprovalNode, type ApprovalAutomationSurface } from './approval-node.js';
-
-export interface ApprovalsPluginOptions {
-  /** Disable runtime registration (schemas still register). */
-  disableService?: boolean;
-  /**
-   * Interval between SLA escalation scans (ADR-0042). Defaults to
-   * {@link ESCALATION_SCAN_INTERVAL_MS} (5 min). Only takes effect when a
-   * `job` service is installed; without one, SLA stays display-only.
-   */
-  escalationScanIntervalMs?: number;
-  /**
-   * Absolute origin for actionable links in outbound notifications
-   * (ADR-0043), e.g. `https://app.example.com`. Relative by default.
-   */
-  publicBaseUrl?: string;
-  /**
-   * Disable the record-lock hook. Schema + service stay intact; only the
-   * engine-level lock wiring is suppressed. Useful when a caller wants the
-   * manual API only (e.g. tests).
-   */
-  disableAutoHooks?: boolean;
-}
-
-/**
- * ApprovalsServicePlugin — registers sys_approval_{request,action}, the
- * `approvals` service, the `approval` flow node executor (ADR-0019), and the
- * record-lock hook.
- *
- * ADR-0019: approval is no longer a standalone process engine. A flow's
- * Approval node opens a request and suspends the run; a decision via the
- * service resumes it down the matching branch.
- */
-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 escalationJobScheduled = false;
-
-  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: [SysApprovalRequest, SysApprovalAction, SysApprovalApprover, SysApprovalToken, SysApprovalDelegation],
-      // ADR-0029 D7 — contribute the Approvals entries into the Setup app's
-      // `group_approvals` slot. This plugin owns these objects (K2.b), so it
-      // ships their menu too; when the plugin isn't installed the slot is empty.
-      navigationContributions: [
-        {
-          app: 'setup',
-          group: 'group_approvals',
-          priority: 100,
-          items: [
-            { id: 'nav_approval_requests', type: 'object', label: 'Requests', objectName: 'sys_approval_request', icon: 'inbox', requiresObject: 'sys_approval_request' },
-            { id: 'nav_approval_actions', type: 'object', label: 'Action History', objectName: 'sys_approval_action', icon: 'history', requiresObject: 'sys_approval_action' },
-            { id: 'nav_approval_delegations', type: 'object', label: 'Delegations (OOO)', objectName: 'sys_approval_delegation', icon: 'user-clock', requiresObject: 'sys_approval_delegation' },
-          ],
-        },
-      ],
-    });
-    // ADR-0029 D8 — contribute this plugin's object translations to the i18n
-    // service on kernel:ready (the i18n plugin may register after this one).
-    if (typeof (ctx as any).hook === 'function') {
-      (ctx as any).hook('kernel:ready', async () => {
-        try {
-          const i18n = ctx.getService<any>('i18n');
-          if (i18n && typeof i18n.loadTranslations === 'function') {
-            const { ApprovalsTranslations } = await import('./translations/index.js');
-            for (const [locale, data] of Object.entries(ApprovalsTranslations)) {
-              i18n.loadTranslations(locale, data as Record<string, unknown>);
-            }
-          }
-        } catch { /* i18n optional */ }
-      });
-    }
-    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.service = new ApprovalService({
-      engine: engine as ApprovalEngine,
-      logger: ctx.logger,
-      publicBaseUrl: this.options.publicBaseUrl,
-    });
-
-    // Record lock: block edits to a record while it has a pending request.
-    // Delegation write-guard: a self-service OOO delegation may only name the
-    // acting user as delegator (#1322 follow-up). Both bind under the same
-    // package id, so unbindAllHooks clears them together.
-    if (!this.options.disableAutoHooks) {
-      try {
-        unbindAllHooks(engine);
-        bindApprovalLockHook(engine, ctx.logger);
-        bindDelegationWriteGuard(engine, ctx.logger);
-      } catch (err: any) {
-        ctx.logger.warn?.('[approvals] failed to bind approval hooks', { error: err?.message });
-      }
-    }
-
-    ctx.registerService('approvals', this.service);
-    ctx.logger.info('ApprovalsServicePlugin: service registered');
-
-    // Optional messaging service (ADR-0012): thread interactions (reassign /
-    // remind / request-info / comment) notify users when present; without it
-    // they degrade to audit-only.
-    try {
-      const messaging = ctx.getService<any>('messaging');
-      if (messaging && typeof messaging.emit === 'function') {
-        this.service.attachMessaging(messaging);
-      }
-    } catch { /* messaging not installed */ }
-
-    // SLA escalation clock (ADR-0042): a plugin-internal job, deliberately
-    // NOT a flow trigger (ADR-0041 §1). Interval sweep + one catch-up scan at
-    // boot so a restart doesn't extend a breach by a scan period. Wired on
-    // kernel:ready — the job service may start after this plugin. No `job`
-    // service → SLA stays display-only.
-    const wireEscalationClock = async () => {
-      try {
-        const jobs = ctx.getService<any>('job');
-        if (!jobs || typeof jobs.schedule !== 'function' || !this.service) return;
-        const svc = this.service;
-        const intervalMs = this.options.escalationScanIntervalMs ?? ESCALATION_SCAN_INTERVAL_MS;
-        await jobs.schedule(ESCALATION_JOB_NAME, { type: 'interval', intervalMs }, async () => {
-          await svc.runEscalations();
-        });
-        this.escalationJobScheduled = true;
-        void svc.runEscalations().catch((err: any) => {
-          ctx.logger.warn?.('[approvals] boot escalation sweep failed', { error: err?.message });
-        });
-        ctx.logger.info('ApprovalsServicePlugin: SLA escalation scan scheduled', { intervalMs });
-      } catch { /* job service not installed */ }
-    };
-    // Actionable-link pages (ADR-0043): session-less confirm + redemption,
-    // mounted straight on the host Hono app. GET only renders; the decision
-    // happens exclusively on the POST (mail-gateway prefetch safe).
-    const mountActionPages = async () => {
-      try {
-        const http = ctx.getService<any>('http-server');
-        const rawApp = http && typeof http.getRawApp === 'function' ? http.getRawApp() : null;
-        if (!rawApp || !this.service) return;
-        const svc = this.service;
-        const ACT_PATH = '/api/v1/approvals/act';
-        const html = (c: any, body: string, status = 200) =>
-          c.body(body, status, { 'Content-Type': 'text/html; charset=utf-8' });
-        rawApp.get(ACT_PATH, async (c: any) => {
-          const token = String(c.req.query('token') ?? '');
-          const peek = await svc.peekActionToken(token);
-          if (!peek.ok) return html(c, renderResultPage(peek.reason, peek.request), 200);
-          return html(c, renderConfirmPage({
-            request: peek.request, action: peek.action, approverId: peek.approverId,
-            token, actPath: ACT_PATH,
-          }));
-        });
-        rawApp.post(ACT_PATH, async (c: any) => {
-          let token = '';
-          try {
-            const body = await c.req.parseBody();
-            token = String(body?.token ?? '');
-          } catch { /* fall through to invalid */ }
-          const out = await svc.redeemActionToken(token);
-          if (!out.ok) return html(c, renderResultPage(out.reason, out.request), 200);
-          return html(c, renderResultPage(out.action === 'approve' ? 'approved' : 'rejected', out.request));
-        });
-        ctx.logger.info(`ApprovalsServicePlugin: actionable-link pages mounted at ${ACT_PATH}`);
-      } catch { /* http server not installed */ }
-    };
-
-    // Pending-approver index backfill (issue #1745): rebuild the normalized
-    // sys_approval_approver rows from the pending_approvers CSV so requests
-    // written before the index existed (or drifted past a crashed sync) are
-    // queryable. Idempotent; cost tracks the live pending queue.
-    const backfillApproverIndex = async () => {
-      try {
-        const svc = this.service;
-        if (!svc) return;
-        const out = await svc.rebuildApproverIndex();
-        if (out.inserted > 0 || out.deleted > 0) {
-          ctx.logger.info('ApprovalsServicePlugin: approver index rebuilt', out);
-        }
-      } catch (err: any) {
-        ctx.logger.warn?.('[approvals] approver index backfill failed', { error: err?.message });
-      }
-    };
-
-    if (typeof (ctx as any).hook === 'function') {
-      (ctx as any).hook('kernel:ready', wireEscalationClock);
-      (ctx as any).hook('kernel:ready', mountActionPages);
-      (ctx as any).hook('kernel:ready', backfillApproverIndex);
-    } else {
-      await wireEscalationClock();
-      await mountActionPages();
-      await backfillApproverIndex();
-    }
-
-    // ADR-0019: contribute the `approval` node to the flow engine when one is
-    // present. The node lets a flow suspend on an approval and resume on
-    // decision; the service is wired to the same engine so `decide()` can
-    // resume the suspended run.
-    try {
-      const automation = ctx.getService<ApprovalAutomationSurface>('automation');
-      if (automation && typeof automation.registerNodeExecutor === 'function') {
-        this.service.attachAutomation(automation);
-        registerApprovalNode(automation, this.service, ctx.logger);
-      }
-    } catch {
-      ctx.logger.info('ApprovalsServicePlugin: no automation engine — approval node not registered');
-    }
-  }
-
-  async stop(ctx: PluginContext): Promise<void> {
-    if (this.escalationJobScheduled) {
-      try {
-        const jobs = ctx.getService<any>('job');
-        await jobs?.cancel?.(ESCALATION_JOB_NAME);
-      } catch { /* ignore */ }
-      this.escalationJobScheduled = false;
-    }
-    if (this.engine) {
-      try { unbindAllHooks(this.engine); } catch { /* ignore */ }
-    }
-  }
-}

package/src/index.ts

@@ -1,39 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * @objectstack/plugin-approvals
- *
- * Approval-as-flow-node runtime (ADR-0019). Persists sys_approval_request /
- * sys_approval_action, resolves approvers, enforces the record lock, and
- * records decisions that resume the owning flow run. Approval orchestration
- * (when to pause, which branch to take) lives on the one automation engine via
- * the `approval` node.
- */
-
-export { SysApprovalRequest } from './sys-approval-request.object.js';
-export { SysApprovalAction } from './sys-approval-action.object.js';
-export { SysApprovalApprover } from './sys-approval-approver.object.js';
-export { SysApprovalDelegation } from './sys-approval-delegation.object.js';
-export {
-  ApprovalService,
-  type ApprovalEngine,
-  type ApprovalClock,
-  type ApprovalServiceOptions,
-  type ApprovalResumeSurface,
-} from './approval-service.js';
-export {
-  ApprovalsServicePlugin,
-  type ApprovalsPluginOptions,
-} from './approvals-plugin.js';
-export {
-  registerApprovalNode,
-  type ApprovalAutomationSurface,
-} from './approval-node.js';
-export type {
-  IApprovalService,
-  ApprovalRequestRow,
-  ApprovalActionRow,
-  ApprovalDecisionInput,
-  ApprovalDecisionResult,
-  ApprovalStatus,
-} from '@objectstack/spec/contracts';

package/src/lifecycle-hooks.ts

@@ -1,179 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Lifecycle Hooks — node-era record lock (ADR-0019).
- *
- * Approval is now a flow node, so there is no per-object process registry to
- * bind auto-trigger hooks against — a flow decides *when* to open an approval.
- * What remains worth enforcing at the data layer is the **record lock**: while
- * a record has a pending `sys_approval_request`, block edits to it.
- *
- * A single global `beforeUpdate` hook handles every object (the target object
- * of an approval node is only known at flow-run time). For each update it:
- *
- *   1. Skips engine self-writes (status mirror) and `sys_approval_*` bookkeeping.
- *   2. Looks up a pending request for `(object, recordId)`.
- *   3. Reads the lock policy from that request's `node_config_json` snapshot:
- *      - `lockRecord === false` → allow.
- *      - otherwise block, EXCEPT when the only changed field is the configured
- *        `approvalStatusField` (so the status mirror is never blocked) or the
- *        caller is an `admin`.
- *
- * Registered under `packageId: 'plugin-approvals:lock'` so it can be cleanly
- * unbound on plugin stop.
- */
-
-export const APPROVALS_HOOK_PACKAGE = 'plugin-approvals:lock';
-
-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;
-}
-
-function parseJson<T = any>(raw: unknown, fallback: T): T {
-  if (raw == null || raw === '') return fallback;
-  if (typeof raw === 'string') {
-    try { return JSON.parse(raw) as T; } catch { return fallback; }
-  }
-  return raw as T;
-}
-
-/** The pending request gating a record, plus its snapshotted node config. */
-async function pendingRequestFor(
-  engine: MinimalEngine,
-  objectName: string,
-  recordId: string,
-): Promise<any | null> {
-  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[0] ? rows[0] : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Bind the global record-lock hook. Caller is responsible for calling
- * {@link unbindAllHooks} first if re-binding.
- */
-export function bindApprovalLockHook(engine: MinimalEngine, logger?: MinimalLogger): void {
-  engine.registerHook('beforeUpdate', async (ctx: any) => {
-    const id = String((ctx?.input?.id ?? '') as string);
-    if (!id) return;
-    const object = (ctx?.object ?? ctx?.objectName) as string | undefined;
-    // No object name (shouldn't happen) or our own bookkeeping objects → skip.
-    if (!object || String(object).startsWith('sys_approval')) 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 from the approvals service, etc).
-    if ((ctx?.session as any)?.isSystem) return;
-
-    // Allow admin override.
-    const roles = (ctx?.session?.roles ?? []) as string[];
-    if (Array.isArray(roles) && roles.includes('admin')) return;
-
-    const pending = await pendingRequestFor(engine, object, id);
-    if (!pending) return;
-
-    const config = parseJson<any>(pending.node_config_json, {});
-    if (config?.lockRecord === false) return;
-
-    // Allow when every changed field is the approval status mirror.
-    const mirror = config?.approvalStatusField;
-    if (typeof mirror === 'string' && mirror && changedFields.every((f) => f === mirror)) 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;
-  }, { packageId: APPROVALS_HOOK_PACKAGE, priority: 50 });
-
-  logger?.info?.('[approvals] record-lock hook bound');
-}
-
-/** The self-service out-of-office delegation object (#1322). */
-export const DELEGATION_OBJECT = 'sys_approval_delegation';
-
-/**
- * Self-service write guard for `sys_approval_delegation` (#1322 follow-up).
- *
- * The object is `apiEnabled` CRUD so a user can declare their own out-of-office
- * delegation. But it is a system object: it gets no auto `owner_id` anchor and
- * (with no `sharingModel`) defaults to a `public` sharing model, so an
- * unguarded member could **forge a delegation for someone else**
- * (`delegator_id = victim`) and reroute the victim's individually-routed
- * approvals to themselves. This guard forces a normal user's writes to name
- * themselves as the delegator:
- *
- *   - **system** context (service / seed / import) → bypass;
- *   - **admin** (`roles` includes `'admin'`) → may set `delegator_id` to anyone;
- *   - otherwise `delegator_id` must equal the acting user — an absent delegator
- *     on insert is stamped to the caller, a foreign delegator is rejected.
- *
- * Row-level ownership on update/delete (you can only touch a delegation you
- * created) is already enforced by `member_default`'s wildcard
- * `created_by == current_user.id` RLS; this guard adds the delegator-identity
- * check that RLS alone can't express. Mirrors the ADR-0092 identity write-guard
- * shape and the security plugin's `owner_id` anchor guard, scoped to this one
- * object.
- */
-export function bindDelegationWriteGuard(engine: MinimalEngine, logger?: MinimalLogger): void {
-  const makeGuard = (isInsert: boolean) => async (ctx: any) => {
-    const session = (ctx?.session ?? {}) as any;
-    if (session.isSystem) return;                                    // service / seed / import
-    const roles = (session.roles ?? []) as unknown[];
-    if (Array.isArray(roles) && roles.includes('admin')) return;     // admin may act for anyone
-    const userId = session.userId != null ? String(session.userId) : '';
-    const data = ctx?.input?.data;
-    const rows = Array.isArray(data) ? data : (data && typeof data === 'object' ? [data] : []);
-    const deny = (): never => {
-      const err: any = new Error(
-        'FORBIDDEN: you may only manage out-of-office delegations where you are the delegator'
-        + (userId ? ` ('${userId}')` : ''),
-      );
-      err.code = 'FORBIDDEN';
-      err.statusCode = 403;
-      throw err;
-    };
-    for (const row of rows) {
-      if (!row || typeof row !== 'object' || Array.isArray(row)) continue;
-      const has = Object.prototype.hasOwnProperty.call(row, 'delegator_id');
-      const supplied = has ? String((row as any).delegator_id ?? '') : '';
-      if (isInsert && (!has || supplied === '')) {
-        // Self-service: stamp the caller as delegator when omitted (the schema's
-        // `required` is the fallback if the engine doesn't persist the stamp).
-        if (!userId) deny();
-        (row as any).delegator_id = userId;
-        continue;
-      }
-      // A foreign delegator on insert (forge) or update (relabel/hijack) → deny.
-      if (has && supplied !== userId) deny();
-    }
-  };
-  engine.registerHook('beforeInsert', makeGuard(true), { object: DELEGATION_OBJECT, packageId: APPROVALS_HOOK_PACKAGE, priority: 50 });
-  engine.registerHook('beforeUpdate', makeGuard(false), { object: DELEGATION_OBJECT, packageId: APPROVALS_HOOK_PACKAGE, priority: 50 });
-  logger?.info?.('[approvals] delegation write-guard bound');
-}
-
-/** Unregister every hook the lock module registered. */
-export function unbindAllHooks(engine: MinimalEngine): number {
-  return engine.unregisterHooksByPackage(APPROVALS_HOOK_PACKAGE);
-}

package/src/nav-contribution.test.ts

@@ -1,50 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { describe, it, expect } from 'vitest';
-import { ApprovalsServicePlugin } from './approvals-plugin.js';
-
-/**
- * ADR-0029 K2.b / D7 — the approvals plugin owns sys_approval_request /
- * sys_approval_action and ships their Setup-app menu as a navigation
- * contribution (rather than the entries living statically in the
- * platform-objects Setup shell).
- */
-describe('ApprovalsServicePlugin schema + nav contribution (ADR-0029 K2.b)', () => {
-  it('registers the approval objects and contributes the group_approvals slot', async () => {
-    const registered: any[] = [];
-    const ctx: any = {
-      getService: (name: string) =>
-        name === 'manifest' ? { register: (m: any) => registered.push(m) } : undefined,
-      logger: { info: () => {}, warn: () => {} },
-    };
-
-    const plugin = new ApprovalsServicePlugin({ disableService: true });
-    await plugin.init(ctx);
-
-    expect(registered).toHaveLength(1);
-    const manifest = registered[0];
-
-    // Owns the approval objects (moved out of platform-objects).
-    expect(manifest.objects.map((o: any) => o.name).sort()).toEqual([
-      'sys_approval_action',
-      'sys_approval_approver',
-      'sys_approval_delegation',
-      'sys_approval_request',
-      'sys_approval_token',
-    ]);
-
-    // Contributes its menu into the Setup app's approvals slot.
-    expect(manifest.navigationContributions).toHaveLength(1);
-    const contribution = manifest.navigationContributions[0];
-    expect(contribution).toMatchObject({ app: 'setup', group: 'group_approvals' });
-    expect(contribution.items.map((i: any) => i.objectName).sort()).toEqual([
-      'sys_approval_action',
-      'sys_approval_delegation',
-      'sys_approval_request',
-    ]);
-    // Each entry is gated so the slot stays empty when the plugin is absent.
-    for (const item of contribution.items) {
-      expect(item.requiresObject).toBe(item.objectName);
-    }
-  });
-});

package/src/sys-approval-action.object.ts

@@ -1,140 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { ObjectSchema, Field } from '@objectstack/spec/data';
-
-/**
- * sys_approval_action — Audit trail row per approval action.
- *
- * Append-only: every `submit`, `approve`, `reject`, `recall`, or
- * `escalate` event lands here. The engine reads back per-step approval
- * rows to evaluate `behavior: 'unanimous'` (all approvers must approve
- * before advancing) versus `first_response` (any single approval
- * advances the step).
- *
- * @namespace sys
- */
-export const SysApprovalAction = ObjectSchema.create({
-  name: 'sys_approval_action',
-  label: 'Approval Action',
-  pluralLabel: 'Approval Actions',
-  icon: 'check-circle',
-  isSystem: true,
-  managedBy: 'append-only',
-  description: 'Append-only audit trail for approval actions',
-  displayNameField: 'id',
-  nameField: 'id', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
-  titleFormat: '{action} · {step_name}',
-  highlightFields: ['request_id', 'step_name', 'action', 'actor_id', 'created_at'],
-
-  listViews: {
-    recent: {
-      type: 'grid',
-      name: 'recent',
-      label: 'Recent',
-      data: { provider: 'object', object: 'sys_approval_action' },
-      columns: ['created_at', 'request_id', 'step_name', 'action', 'actor_id', 'comment'],
-      sort: [{ field: 'created_at', order: 'desc' }],
-      pagination: { pageSize: 50 },
-      emptyState: { title: 'No approval actions yet', message: 'Actions are logged automatically when approvals progress.' },
-    },
-    by_actor: {
-      type: 'grid',
-      name: 'by_actor',
-      label: 'By Actor',
-      data: { provider: 'object', object: 'sys_approval_action' },
-      columns: ['actor_id', 'created_at', 'request_id', 'step_name', 'action'],
-      sort: [{ field: 'actor_id', order: 'asc' }, { field: 'created_at', order: 'desc' }],
-      grouping: { fields: [{ field: 'actor_id', order: 'asc', collapsed: false }] },
-      pagination: { pageSize: 100 },
-    },
-    all_actions: {
-      type: 'grid',
-      name: 'all_actions',
-      label: 'All',
-      data: { provider: 'object', object: 'sys_approval_action' },
-      columns: ['created_at', 'request_id', 'step_name', 'action', 'actor_id', 'comment'],
-      sort: [{ field: 'created_at', order: 'desc' }],
-      pagination: { pageSize: 100 },
-    },
-  },
-
-  fields: {
-    id: Field.text({ label: 'Action ID', required: true, readonly: true, group: 'System' }),
-
-    organization_id: Field.lookup('sys_organization', {
-      label: 'Organization',
-      required: false,
-      group: 'System',
-      description: 'Tenant that owns this action (mirrors the parent request)',
-    }),
-
-    request_id: Field.lookup('sys_approval_request', {
-      label: 'Request',
-      required: true,
-      group: 'Target',
-    }),
-
-    step_name: Field.text({
-      label: 'Step',
-      required: false,
-      maxLength: 100,
-      description: 'Machine name of the step at the time of the action',
-      group: 'Target',
-    }),
-
-    step_index: Field.number({
-      label: 'Step Index',
-      required: false,
-      group: 'Target',
-    }),
-
-    action: Field.select(
-      // Keep in sync with `ApprovalActionKind` (spec/contracts). reassign /
-      // remind / request_info / comment are thread interactions — they never
-      // move the flow. revise / resubmit (ADR-0044) DO move it: send back for
-      // revision and the later resubmission. ooo_substitute (#1322 M1) is a
-      // system-recorded reroute of an out-of-office approver — no flow movement.
-      ['submit', 'approve', 'reject', 'recall', 'escalate', 'reassign', 'remind', 'request_info', 'comment', 'revise', 'resubmit', 'ooo_substitute'],
-      {
-        label: 'Action',
-        required: true,
-        group: 'Action',
-      },
-    ),
-
-    actor_id: Field.lookup('sys_user', {
-      label: 'Actor',
-      required: false,
-      group: 'Action',
-    }),
-
-    comment: Field.textarea({ label: 'Comment', required: false, group: 'Action' }),
-
-    attachments: Field.file({
-      label: 'Attachments',
-      required: false,
-      multiple: true,
-      group: 'Action',
-      description: 'Files supporting this action — e.g. a signed contract or evidence (#3266).',
-    }),
-
-    created_at: Field.datetime({
-      label: 'Created At',
-      required: true,
-      defaultValue: 'NOW()',
-      readonly: true,
-      group: 'System',
-    }),
-  },
-
-  indexes: [
-    { fields: ['request_id', 'created_at'] },
-    { fields: ['request_id', 'step_index', 'action'] },
-  ],
-
-  enable: {
-    // [ADR-0103] Engine-owned append-only decision log: appended by the approval
-    // engine (SYSTEM_CTX). Reads stay open.
-    apiMethods: ['get', 'list'],
-  },
-});