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

package/src/approver-org-scope.test.ts

@@ -1,201 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * [ADR-0105 D9] Cross-organization approver targeting.
- *
- * The property that matters is that this is a route WITHIN one group, not a
- * channel to an arbitrary tenant — so every test here is about a boundary
- * holding or a failure being LOUD. The thing D9 exists to prevent is silence:
- * an approval that reads as "escalate to group" but quietly resolves inside the
- * plant, or one that routes to someone the D2 wall then hides the request from.
- */
-
-import { describe, it, expect, vi } from 'vitest';
-import {
-  filterApproversWhoCanRead,
-  resolveApproverDirectoryOrg,
-  type ApproverOrgScopeDeps,
-} from './approver-org-scope.js';
-
-/**
- * A three-tier group: group → division → plant, plus a shared-services SIBLING
- * of the plant, plus an organization in a DIFFERENT group entirely.
- */
-const ORGS: Record<string, { id: string; slug: string; parent_organization_id: string | null }> = {
-  o_group: { id: 'o_group', slug: 'acme-group', parent_organization_id: null },
-  o_div: { id: 'o_div', slug: 'acme-north', parent_organization_id: 'o_group' },
-  o_plant: { id: 'o_plant', slug: 'acme-plant-a', parent_organization_id: 'o_div' },
-  o_ssc: { id: 'o_ssc', slug: 'acme-ssc', parent_organization_id: 'o_group' },
-  o_other: { id: 'o_other', slug: 'rival-co', parent_organization_id: null },
-  o_lone: { id: 'o_lone', slug: 'lone-co', parent_organization_id: null },
-};
-
-function makeDeps(over: Partial<ApproverOrgScopeDeps> & { members?: Array<{ user_id: string; organization_id: string }> } = {}): ApproverOrgScopeDeps & { warn: any } {
-  const warn = vi.fn();
-  const members = over.members ?? [];
-  const engine = {
-    find: vi.fn(async (object: string, opts: any) => {
-      const f = opts?.filter ?? {};
-      if (object === 'sys_organization') {
-        const rows = Object.values(ORGS).filter((o) =>
-          (f.id === undefined || o.id === f.id) && (f.slug === undefined || o.slug === f.slug));
-        return rows;
-      }
-      if (object === 'sys_member') {
-        const wanted: string[] = f.user_id?.$in ?? [];
-        return members.filter((m) => m.organization_id === f.organization_id && wanted.includes(m.user_id));
-      }
-      return [];
-    }),
-  };
-  return { engine, logger: { warn }, posture: () => 'group', ...over, warn } as any;
-}
-
-const resolve = (
-  deps: ApproverOrgScopeDeps,
-  declaration: string | undefined,
-  requestOrg: string | null,
-  type = 'position',
-  orgScoped = true,
-) => resolveApproverDirectoryOrg(deps, declaration, requestOrg, type, orgScoped);
-
-describe('resolveApproverDirectoryOrg — the default path is untouched', () => {
-  it('returns the request org and reads NOTHING when no organization is declared', async () => {
-    const deps = makeDeps();
-    await expect(resolve(deps, undefined, 'o_plant')).resolves.toBe('o_plant');
-    // The overwhelmingly common case must not cost a query.
-    expect((deps.engine.find as any)).not.toHaveBeenCalled();
-  });
-
-  it('passes a null request org straight through — a single-org deployment is unaffected', async () => {
-    const deps = makeDeps();
-    await expect(resolve(deps, undefined, null)).resolves.toBeNull();
-  });
-});
-
-describe('resolveApproverDirectoryOrg — symbols resolve against the D6 tree', () => {
-  it('$root climbs to the group organization, not just one level', async () => {
-    // o_plant → o_div → o_group. A one-level implementation would answer o_div.
-    await expect(resolve(makeDeps(), '$root', 'o_plant')).resolves.toBe('o_group');
-  });
-
-  it('$parent stops at exactly one level — division sign-off in a three-tier group', async () => {
-    await expect(resolve(makeDeps(), '$parent', 'o_plant')).resolves.toBe('o_div');
-  });
-
-  it('$root on an organization with no lineage FAILS instead of silently self-targeting', async () => {
-    // Returning o_lone would make "escalate to group" mean "approve in place" —
-    // the exact silent misrouting D9 exists to prevent.
-    await expect(resolve(makeDeps(), '$root', 'o_lone')).rejects.toThrow(
-      /VALIDATION_FAILED.*no 'parent_organization_id' lineage/,
-    );
-  });
-
-  it('$parent at the root of a group fails rather than resolving to nothing', async () => {
-    await expect(resolve(makeDeps(), '$parent', 'o_group')).rejects.toThrow(/VALIDATION_FAILED.*no parent/);
-  });
-});
-
-describe('resolveApproverDirectoryOrg — a slug names one organization, bounded by the group', () => {
-  it('accepts a SIBLING in the same group — the shared-services-centre shape', async () => {
-    // o_ssc is not an ancestor of o_plant; it shares the root. This is why the
-    // rule is "shares a root", not "is an ancestor".
-    await expect(resolve(makeDeps(), 'acme-ssc', 'o_plant')).resolves.toBe('o_ssc');
-  });
-
-  it('refuses an organization in a DIFFERENT group — this is not a channel to any tenant', async () => {
-    await expect(resolve(makeDeps(), 'rival-co', 'o_plant')).rejects.toThrow(
-      /VALIDATION_FAILED.*not in the same group/,
-    );
-  });
-
-  it('refuses an unknown slug and says an id is not accepted', async () => {
-    // The most likely authoring mistake is pasting an organization id, which is
-    // per-deployment and would make the flow unportable.
-    await expect(resolve(makeDeps(), 'o_plant', 'o_plant')).rejects.toThrow(
-      /VALIDATION_FAILED.*never an id/,
-    );
-  });
-});
-
-describe('resolveApproverDirectoryOrg — the guards', () => {
-  it('refuses under a non-group posture instead of silently ignoring the declaration', async () => {
-    // A deployment migrating group → isolated must not quietly reroute its
-    // approvals; that is an audit event, not a config detail.
-    const deps = makeDeps({ posture: () => 'isolated' });
-    await expect(resolve(deps, '$root', 'o_plant')).rejects.toThrow(
-      /VALIDATION_FAILED.*requires the 'group' tenancy posture.*isolated/,
-    );
-  });
-
-  it('stands down when the posture is unknown — a minimal stack is not broken by a guard it cannot answer', async () => {
-    const deps = makeDeps({ posture: () => undefined });
-    await expect(resolve(deps, '$root', 'o_plant')).resolves.toBe('o_group');
-  });
-
-  it('refuses the declaration on an approver type that has no organization directory', async () => {
-    // `user` names a person outright; an `organization` on it would have no
-    // effect. An author who wrote it believed it did something.
-    await expect(resolve(makeDeps(), '$root', 'o_plant', 'user', false)).rejects.toThrow(
-      /VALIDATION_FAILED.*would have no effect/,
-    );
-  });
-
-  it('refuses when the request carries no organization at all', async () => {
-    await expect(resolve(makeDeps(), '$root', null)).rejects.toThrow(
-      /VALIDATION_FAILED.*carries no organization/,
-    );
-  });
-
-  it('survives a cycle in the grouping metadata instead of looping forever', async () => {
-    const deps = makeDeps();
-    (deps.engine.find as any) = vi.fn(async (object: string, opts: any) => {
-      if (object !== 'sys_organization') return [];
-      const id = opts?.filter?.id;
-      // a → b → a
-      if (id === 'a') return [{ id: 'a', slug: 'a', parent_organization_id: 'b' }];
-      if (id === 'b') return [{ id: 'b', slug: 'b', parent_organization_id: 'a' }];
-      return [];
-    });
-    // Terminates; the cycle is broken and whatever it settles on is bounded.
-    await expect(resolve(deps, '$parent', 'a')).resolves.toBe('b');
-  });
-});
-
-describe('filterApproversWhoCanRead — routing to someone the wall hides is a silent failure', () => {
-  it('keeps approvers who hold a membership in the REQUEST org', async () => {
-    const deps = makeDeps({ members: [{ user_id: 'u_cfo', organization_id: 'o_plant' }] });
-    const kept = await filterApproversWhoCanRead(deps, ['u_cfo'], 'o_plant', {
-      approverType: 'position', value: 'cfo', directoryOrgId: 'o_group',
-    });
-    expect(kept).toEqual(['u_cfo']);
-    expect(deps.warn).not.toHaveBeenCalled();
-  });
-
-  it('drops an approver with no membership there, and says exactly why', async () => {
-    // She holds `cfo` in the group org but no membership in the plant, so D2's
-    // union would hide the request from her: routing succeeds, then she opens a
-    // task she cannot open. Convert that into the empty-slate path the node
-    // already has a policy for.
-    const deps = makeDeps({ members: [{ user_id: 'u_ok', organization_id: 'o_plant' }] });
-    const kept = await filterApproversWhoCanRead(deps, ['u_ok', 'u_no_membership'], 'o_plant', {
-      approverType: 'position', value: 'cfo', directoryOrgId: 'o_group',
-    });
-    expect(kept).toEqual(['u_ok']);
-    expect(deps.warn).toHaveBeenCalledTimes(1);
-    const msg = String(deps.warn.mock.calls[0][0]);
-    expect(msg).toMatch(/u_no_membership|cross-organization approver/);
-    expect(msg).toMatch(/Grant those users a membership|retarget/);
-  });
-
-  it('does NOT empty a live slate when membership is unreadable', async () => {
-    // An infrastructure hiccup must not silently unstaff a pending approval:
-    // routing to someone who may not see it is recoverable, emptying is not.
-    const deps = makeDeps();
-    (deps.engine.find as any) = vi.fn(async () => { throw new Error('driver hiccup'); });
-    const kept = await filterApproversWhoCanRead(deps, ['u1', 'u2'], 'o_plant', {
-      approverType: 'position', directoryOrgId: 'o_group',
-    });
-    expect(kept).toEqual(['u1', 'u2']);
-  });
-});

package/src/approver-org-scope.ts

@@ -1,261 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * [ADR-0105 D9] Cross-organization approver targeting — resolving WHICH
- * organization's directory an approver is looked up in.
- *
- * One organization id used to do three jobs at once in `openNodeRequest`:
- * where the request row lives, where its inbox index rows live, and where its
- * approvers are looked up. The first two are the request's own organization by
- * definition. The third is not: a group CFO holds her `cfo` position in the
- * GROUP organization while the purchase order she signs off lives in the PLANT
- * organization. Binding all three together meant
- * `expandPositionUsers('cfo', <plant>)` matched nobody and the slot fell into
- * `onEmptyApprovers` — a group escalation could not be expressed at all.
- *
- * This module resolves only the third job. The request keeps living in its own
- * organization, and D2's membership union is what lets a group-side approver
- * READ it — see `assertApproversCanRead` below for why that is a precondition
- * worth checking rather than assuming.
- */
-
-/** Cycle guard for the `parent_organization_id` walk (mirrors the BU subtree walk). */
-const MAX_ORG_DEPTH = 32;
-
-const SYSTEM_CTX = { isSystem: true } as const;
-
-export interface ApproverOrgScopeEngine {
-  find(object: string, options: any): Promise<any[]>;
-}
-
-export interface ApproverOrgScopeDeps {
-  engine: ApproverOrgScopeEngine;
-  /**
-   * The tenancy posture in force, when the host could resolve one. `undefined`
-   * means "unknown" — a stack booted without the tenancy service — and is
-   * treated as permissive so a minimal test/embedded stack is not broken by a
-   * guard it cannot answer.
-   */
-  posture?: () => string | undefined;
-  logger?: { warn?: (msg: any, ...rest: any[]) => void; debug?: (msg: any, ...rest: any[]) => void };
-}
-
-/**
- * Every failure here THROWS `VALIDATION_FAILED`, matching how `expression`
- * approvers already fail (#3447 P2): an approver declaration that cannot be
- * resolved is a ROUTING BUG, never "condition not met". Silently falling back
- * to the request's own organization would be the worst option available — a
- * flow that reads as "escalate to group" would quietly approve inside the
- * plant, and the deployment that changed posture would reroute its approvals
- * with no signal at all.
- *
- * Messages name the offending value because their primary reader is the AI
- * author fixing the flow on the next validate pass.
- */
-function fail(message: string): never {
-  throw new Error(`VALIDATION_FAILED: ${message}`);
-}
-
-async function findOrg(
-  engine: ApproverOrgScopeEngine,
-  where: Record<string, unknown>,
-): Promise<any | null> {
-  try {
-    const rows = await engine.find('sys_organization', {
-      filter: where,
-      fields: ['id', 'slug', 'parent_organization_id'],
-      limit: 1,
-      context: SYSTEM_CTX,
-    } as any);
-    return Array.isArray(rows) && rows[0] ? rows[0] : null;
-  } catch {
-    return null;
-  }
-}
-
-/** The id chain from `orgId` up to its root, inclusive. Fail-closed on cycles. */
-async function ancestorChain(
-  engine: ApproverOrgScopeEngine,
-  orgId: string,
-): Promise<string[]> {
-  const chain: string[] = [];
-  const seen = new Set<string>();
-  let cursor: string | null = orgId;
-  for (let depth = 0; cursor && depth < MAX_ORG_DEPTH; depth++) {
-    if (seen.has(cursor)) break; // cycle in the grouping metadata — stop, do not loop
-    seen.add(cursor);
-    chain.push(cursor);
-    const row = await findOrg(engine, { id: cursor });
-    const parent = row?.parent_organization_id;
-    cursor = parent ? String(parent) : null;
-  }
-  return chain;
-}
-
-/**
- * Resolve an approver's `organization` declaration to a concrete organization
- * id for directory lookups. Returns the request's own organization when the
- * declaration is absent — the unchanged default path, which does no reads.
- */
-export async function resolveApproverDirectoryOrg(
-  deps: ApproverOrgScopeDeps,
-  declaration: string | null | undefined,
-  requestOrgId: string | null | undefined,
-  approverType: string,
-  isOrgScopedType: boolean,
-): Promise<string | null | undefined> {
-  const declared = typeof declaration === 'string' ? declaration.trim() : '';
-  if (!declared) return requestOrgId;
-
-  // An `organization` on `user` / `field` / `manager` / `team` is not a
-  // narrower routing — those types never consult an org-scoped directory, so
-  // the declaration would have no effect. Refuse rather than ignore: a flow
-  // author who wrote it believed it did something.
-  if (!isOrgScopedType) {
-    fail(
-      `approver type '${approverType}' resolves people without an organization directory, `
-      + `so 'organization: ${declared}' would have no effect — remove it `
-      + `(ADR-0105 D9 applies to position / org_membership_level / department / expression)`,
-    );
-  }
-
-  // Posture guard. ADR-0105 D9 applies to `group` only: in `isolated`, cross-org
-  // approval remains system-context mirroring (cloud #2937 contract), and in
-  // `single` there is no second organization to target. Refusing here — rather
-  // than in a lint — is deliberate: posture is ENVIRONMENT configuration, so the
-  // same portable flow metadata may be deployed into any posture and no static
-  // check can see which. A deployment migrating group → isolated must fail
-  // loudly instead of silently rerouting its approvals.
-  const posture = deps.posture?.();
-  if (posture && posture !== 'group') {
-    fail(
-      `cross-organization approver targeting ('organization: ${declared}') requires the `
-      + `'group' tenancy posture; this deployment resolves '${posture}' (ADR-0105 D9)`,
-    );
-  }
-
-  const requestOrg = requestOrgId ? String(requestOrgId) : '';
-  if (!requestOrg) {
-    fail(
-      `'organization: ${declared}' cannot be resolved for a request that carries no `
-      + `organization — cross-organization targeting needs an organization to resolve from`,
-    );
-  }
-
-  const chain = await ancestorChain(deps.engine, requestOrg);
-
-  if (declared === '$root') {
-    const root = chain[chain.length - 1];
-    if (root === requestOrg && chain.length === 1) {
-      fail(
-        `'organization: $root' resolved to the request's own organization — this organization `
-        + `has no 'parent_organization_id' lineage. Declare the group hierarchy (ADR-0105 D6) `
-        + `or drop the targeting`,
-      );
-    }
-    return root;
-  }
-
-  if (declared === '$parent') {
-    const parent = chain[1];
-    if (!parent) {
-      fail(
-        `'organization: $parent' has no parent to resolve to — the request's organization is `
-        + `already the root of its group (ADR-0105 D6 'parent_organization_id')`,
-      );
-    }
-    return parent;
-  }
-
-  // A slug names one specific organization — the shape the symbols cannot
-  // express (a SIBLING, e.g. a shared-services centre approving payables for
-  // every plant). Slugs rather than ids because flow metadata is portable
-  // across environments and organization ids are minted per deployment.
-  const target = await findOrg(deps.engine, { slug: declared });
-  if (!target?.id) {
-    fail(
-      `no organization with slug '${declared}' — 'organization' takes an organization SLUG `
-      + `or a symbol ($root / $parent), never an id (ids are per-deployment, flows are portable)`,
-    );
-  }
-  const targetId = String(target.id);
-  if (targetId === requestOrg) return targetId;
-
-  // Legality: the target must share a grouping root with the request's
-  // organization. "Shares a root" rather than "is an ancestor" because the
-  // sibling case is a first-class use. The rule depends only on the
-  // organization tree — never on who submitted — so one flow routes identically
-  // for every submitter, which is what makes a routing bug reproducible.
-  const targetChain = await ancestorChain(deps.engine, targetId);
-  const targetRoot = targetChain[targetChain.length - 1];
-  const requestRoot = chain[chain.length - 1];
-  if (!targetRoot || !requestRoot || targetRoot !== requestRoot) {
-    fail(
-      `organization '${declared}' is not in the same group as the request's organization `
-      + `— cross-organization approval routes WITHIN one group (they must share a `
-      + `'parent_organization_id' root, ADR-0105 D6/D9)`,
-    );
-  }
-  return targetId;
-}
-
-/**
- * Drop approvers who could not READ the request they were routed to, and say
- * so.
- *
- * ADR-0105 D9 notes that reads by cross-org approvers "are covered by D2
- * (membership union)". True — but D2's union is `organization_id IN
- * accessible_org_ids`, and the request row is stamped with the REQUEST's
- * organization. So a group-side approver reaches it only if she also holds a
- * membership there. That is the intended group shape (group staff are members
- * of every plant while holding their positions in the group org — the shape the
- * ADR-0105 acceptance dogfood already models), but nothing enforces it.
- *
- * Left unchecked the failure is SILENT and expensive: routing succeeds, the
- * request and inbox rows are written, and the approver then opens a task she
- * cannot open — the wall hides the record. Filtering here converts that into
- * the empty-slate path the node already has a policy for
- * (`onEmptyApprovers`), and logs exactly who was dropped and why, so the fix
- * ("grant the membership" or "retarget") is legible without a debugger.
- */
-export async function filterApproversWhoCanRead(
-  deps: ApproverOrgScopeDeps,
-  userIds: string[],
-  requestOrgId: string | null | undefined,
-  context: { approverType: string; value?: string; directoryOrgId?: string | null },
-): Promise<string[]> {
-  const requestOrg = requestOrgId ? String(requestOrgId) : '';
-  if (!requestOrg || userIds.length === 0) return userIds;
-
-  let members: any[] = [];
-  try {
-    members = await deps.engine.find('sys_member', {
-      filter: { organization_id: requestOrg, user_id: { $in: userIds } },
-      fields: ['user_id'],
-      limit: 10000,
-      context: SYSTEM_CTX,
-    } as any);
-  } catch {
-    // Membership unreadable — do NOT drop everyone on an infrastructure
-    // hiccup. Routing to someone who may not see the request is recoverable
-    // (an admin can grant the membership); silently emptying a live approval
-    // slate is not.
-    return userIds;
-  }
-
-  const canRead = new Set(
-    (members ?? []).map((m: any) => String(m?.user_id ?? '')).filter(Boolean),
-  );
-  const dropped = userIds.filter((u) => !canRead.has(u));
-  if (dropped.length === 0) return userIds;
-
-  deps.logger?.warn?.(
-    `[approvals] ADR-0105 D9: ${dropped.length} cross-organization approver(s) dropped — `
-    + `they hold '${context.value ?? context.approverType}' in organization `
-    + `'${context.directoryOrgId}' but no membership in the request's organization `
-    + `'${requestOrg}', so the D2 union wall would hide the request from them. `
-    + `Grant those users a membership in the request's organization, or retarget the approver.`,
-    { dropped, requestOrganizationId: requestOrg, directoryOrganizationId: context.directoryOrgId },
-  );
-  return userIds.filter((u) => canRead.has(u));
-}

package/src/index.ts

@@ -1,42 +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,
-  // #3447 P2 — expression approvers + empty-slate auto-approve outcome.
-  type ApproverExpressionContext,
-  type ApprovalNodeAutoOutcome,
-} 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';