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

package/src/approvals-plugin.ts

@@ -1,294 +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,
-      // [ADR-0105 D9] Cross-organization approver targeting is a `group`-posture
-      // capability. Read LAZILY (not captured at start) because the tenancy
-      // service resolves its posture during its own start, which may not have
-      // run yet; an unresolvable posture reads as "unknown" and the guard
-      // stands down rather than refusing a legitimate flow on a minimal stack.
-      tenancyPosture: () => {
-        try {
-          const tenancy = ctx.getService<{ posture?: string }>('tenancy');
-          const posture = tenancy?.posture;
-          return typeof posture === 'string' && posture ? posture : undefined;
-        } catch {
-          return undefined;
-        }
-      },
-    });
-
-    // 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;
-        // Both sweeps ride this one clock: they walk the same `pending` set, and
-        // the dead-run release (#3456) is reconciliation with the same "catch up
-        // after a restart" requirement — a run killed BY the restart is exactly
-        // the shape no in-band handler can clean up.
-        // Genuinely independent — an escalation failure must not strand locked
-        // records, and vice versa, so neither can short-circuit the other.
-        const sweep = async () => {
-          const results = await Promise.allSettled([
-            svc.runEscalations(),
-            svc.releaseDeadRunRequests(),
-          ]);
-          for (const r of results) {
-            if (r.status === 'rejected') {
-              ctx.logger.warn?.('[approvals] periodic sweep leg failed', {
-                error: (r.reason as any)?.message ?? String(r.reason),
-              });
-            }
-          }
-        };
-        await jobs.schedule(ESCALATION_JOB_NAME, { type: 'interval', intervalMs }, sweep);
-        this.escalationJobScheduled = true;
-        void sweep().catch((err: any) => {
-          ctx.logger.warn?.('[approvals] boot 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/approver-cross-org.integration.test.ts

@@ -1,206 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * [ADR-0105 D9] Cross-organization approver targeting, through the SERVICE.
- *
- * `approver-org-scope.test.ts` owns the resolver's own rules. What only this
- * level can show is that the resolved organization actually reaches the
- * directory lookups — the wiring D9 is: one organization id used to decide
- * three different things at once (where the request lives, where its inbox rows
- * live, where its approvers are looked up), and only the third moves.
- *
- * The scenario is the one D9 exists for: a purchase order raised in PLANT A
- * needs the group CFO, who holds `cfo` in the GROUP organization and would have
- * matched nobody before.
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import { ApprovalService } from './approval-service.js';
-
-interface Row { [k: string]: any }
-
-function makeEngine(seed: Record<string, Row[]> = {}) {
-  const tables: Record<string, Row[]> = { ...seed };
-  const ensure = (n: string) => (tables[n] ??= []);
-  const matches = (row: Row, filter: any): boolean => {
-    if (!filter || typeof filter !== 'object') return true;
-    for (const [k, v] of Object.entries(filter)) {
-      if (k === '$or') {
-        if (!(v as any[]).some((sub) => matches(row, sub))) return false;
-        continue;
-      }
-      const rv = row[k];
-      if (v != null && typeof v === 'object' && '$in' in (v as any)) {
-        if (!(v as any).$in.includes(rv)) return false;
-        continue;
-      }
-      if (v != null && typeof v === 'object' && '$ne' in (v as any)) {
-        if (rv === (v as any).$ne) return false;
-        continue;
-      }
-      if (rv !== v) return false;
-    }
-    return true;
-  };
-  return {
-    _tables: tables,
-    async find(object: string, options?: any) {
-      return ensure(object).filter((r) => matches(r, options?.filter ?? options?.where));
-    },
-    async insert(object: string, data: Row) { ensure(object).push({ ...data }); return { ...data }; },
-    async update(_o: string, _w: any, _d: any) { return {}; },
-    async delete() { return {}; },
-    async count(object: string) { return ensure(object).length; },
-    registerHook() { /* no-op */ },
-    unregisterHooksByPackage() { /* no-op */ },
-  };
-}
-
-/** Plant A sits under the group; the CFO's position lives in the group org. */
-const SEED = () => ({
-  sys_organization: [
-    { id: 'o_group', slug: 'acme-group', parent_organization_id: null },
-    { id: 'o_plant', slug: 'acme-plant-a', parent_organization_id: 'o_group' },
-  ],
-  sys_user_position: [
-    { id: 'up1', user_id: 'u_cfo', position: 'cfo', organization_id: 'o_group' },
-    { id: 'up2', user_id: 'u_plant_mgr', position: 'plant_manager', organization_id: 'o_plant' },
-  ],
-  sys_member: [
-    // The intended group shape: group staff hold a membership in every plant
-    // (so D2's union lets them READ the request) while their POSITION lives in
-    // the group organization.
-    { id: 'm1', user_id: 'u_cfo', organization_id: 'o_plant', role: 'member' },
-    { id: 'm2', user_id: 'u_plant_mgr', organization_id: 'o_plant', role: 'member' },
-  ],
-});
-
-const CTX = { userId: 'u_submitter', organizationId: 'o_plant', positions: [], permissions: [] } as any;
-
-function openInput(approvers: any[], extra: Record<string, any> = {}) {
-  return {
-    object: 'purchase_order',
-    recordId: 'po1',
-    runId: 'run_1',
-    nodeId: 'group_signoff',
-    flowName: 'po_approval',
-    config: { approvers, behavior: 'unanimous' as const, lockRecord: false },
-    record: { id: 'po1', amount: 500000 },
-    ...extra,
-  };
-}
-
-describe('ADR-0105 D9 — cross-org approver targeting through ApprovalService', () => {
-  let engine: ReturnType<typeof makeEngine>;
-  let svc: ApprovalService;
-  let n = 0;
-
-  beforeEach(() => {
-    engine = makeEngine(SEED());
-    n = 0;
-    svc = new ApprovalService({
-      engine: engine as any,
-      clock: { now: () => new Date(1767000000000 + (n++) * 1000) },
-      tenancyPosture: () => 'group',
-    });
-  });
-
-  it('without targeting, a group position matches NOBODY — the gap D9 closes', async () => {
-    // The `cfo` position exists, but in the group org; the request is Plant A's.
-    // Pre-D9 this was the only possible outcome, and it was silent.
-    const req = await svc.openNodeRequest(openInput([{ type: 'position', value: 'cfo' }]), CTX);
-    expect(req.pending_approvers).toEqual(['position:cfo']); // the dead literal slot
-  });
-
-  it('`organization: $root` resolves the CFO against the GROUP directory', async () => {
-    const req = await svc.openNodeRequest(
-      openInput([{ type: 'position', value: 'cfo', organization: '$root' }]),
-      CTX,
-    );
-    expect(req.pending_approvers).toEqual(['u_cfo']);
-  });
-
-  it('the request and its inbox rows still belong to the REQUEST org — only the lookup moved', async () => {
-    await svc.openNodeRequest(
-      openInput([{ type: 'position', value: 'cfo', organization: '$root' }]),
-      CTX,
-    );
-    // This is the whole point of the split: targeting must not relocate the
-    // request into the approver's organization, or the plant would lose its own
-    // audit trail to the group.
-    expect(engine._tables['sys_approval_request'][0].organization_id).toBe('o_plant');
-    expect(engine._tables['sys_approval_approver'][0].organization_id).toBe('o_plant');
-    expect(engine._tables['sys_approval_action'][0].organization_id).toBe('o_plant');
-  });
-
-  it('mixes a plant approver and a group approver in ONE node — why targeting is per-approver', async () => {
-    // A node-level declaration could not express this: the plant manager and the
-    // group CFO sign off in parallel, each resolved in a different directory.
-    const req = await svc.openNodeRequest(
-      openInput([
-        { type: 'position', value: 'plant_manager', group: 'plant' },
-        { type: 'position', value: 'cfo', organization: '$root', group: 'finance' },
-      ]),
-      CTX,
-    );
-    expect(new Set(req.pending_approvers)).toEqual(new Set(['u_plant_mgr', 'u_cfo']));
-  });
-
-  it('drops a targeted approver who could not READ the request, leaving the empty-slate path', async () => {
-    // Same flow, but the CFO holds no membership in Plant A — D2's union wall
-    // would hide the request from her. Better an empty slate (which the node has
-    // an `onEmptyApprovers` policy for) than a task she cannot open.
-    engine._tables['sys_member'] = engine._tables['sys_member'].filter((m) => m.user_id !== 'u_cfo');
-    const req = await svc.openNodeRequest(
-      openInput([{ type: 'position', value: 'cfo', organization: '$root' }]),
-      CTX,
-    );
-    expect(req.pending_approvers).toEqual(['position:cfo']);
-  });
-
-  // Regression: `user` / `field` / `manager` return EARLY in
-  // `resolveApproverSpec`, before the graph-expansion branch. D9's resolution
-  // originally sat after those returns, so the declaration on a directory-less
-  // type was silently INERT rather than refused — the one behaviour ADR-0105 D9
-  // and the authoring docs both promise it is not. The resolver's own unit test
-  // could not see it (it calls the resolver directly); only a request opened
-  // through the service reaches the early return. Caught by cloud's
-  // group-posture dogfood.
-  it('refuses `organization` on a directory-less type — the early return must not skip the check', async () => {
-    for (const spec of [
-      { type: 'user', value: 'u_cfo', organization: '$root' },
-      { type: 'field', value: 'owner_id', organization: '$root' },
-      { type: 'manager', organization: '$root' },
-    ]) {
-      await expect(
-        svc.openNodeRequest(openInput([spec]), CTX),
-        `approver type '${spec.type}' must refuse a cross-org declaration`,
-      ).rejects.toThrow(/VALIDATION_FAILED.*no effect/);
-    }
-  });
-
-  it('a directory-less approver with NO declaration is untouched by D9', async () => {
-    // The guard must not cost the ordinary case anything.
-    const req = await svc.openNodeRequest(openInput([{ type: 'user', value: 'u_plant_mgr' }]), CTX);
-    expect(req.pending_approvers).toEqual(['u_plant_mgr']);
-  });
-
-  it('refuses a target outside the group — loudly, and no request is created', async () => {
-    engine._tables['sys_organization'].push({ id: 'o_rival', slug: 'rival-co', parent_organization_id: null });
-    await expect(
-      svc.openNodeRequest(openInput([{ type: 'position', value: 'cfo', organization: 'rival-co' }]), CTX),
-    ).rejects.toThrow(/VALIDATION_FAILED.*not in the same group/);
-    expect(engine._tables['sys_approval_request'] ?? []).toHaveLength(0);
-  });
-
-  it('refuses under a non-group posture — a posture migration cannot silently reroute', async () => {
-    const isolated = new ApprovalService({
-      engine: engine as any,
-      clock: { now: () => new Date(1767000000000) },
-      tenancyPosture: () => 'isolated',
-    });
-    await expect(
-      isolated.openNodeRequest(openInput([{ type: 'position', value: 'cfo', organization: '$root' }]), CTX),
-    ).rejects.toThrow(/VALIDATION_FAILED.*'group' tenancy posture/);
-  });
-});