@objectstack/plugin-approvals 5.0.0 → 5.2.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/plugin-approvals@5.0.0 build /home/runner/work/framework/framework/packages/plugins/plugin-approvals
+> @objectstack/plugin-approvals@5.2.0 build /home/runner/work/framework/framework/packages/plugins/plugin-approvals
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     39.71 KB
-ESM dist/index.mjs.map 85.21 KB
-ESM ⚡️ Build success in 113ms
-CJS dist/index.js     40.77 KB
-CJS dist/index.js.map 85.13 KB
-CJS ⚡️ Build success in 113ms
+ESM dist/index.mjs     42.73 KB
+ESM dist/index.mjs.map 91.14 KB
+ESM ⚡️ Build success in 140ms
+CJS dist/index.js     43.79 KB
+CJS dist/index.js.map 91.06 KB
+CJS ⚡️ Build success in 146ms
 DTS Build start
-DTS ⚡️ Build success in 16290ms
-DTS dist/index.d.mts 7.87 KB
-DTS dist/index.d.ts  7.87 KB
+DTS ⚡️ Build success in 19856ms
+DTS dist/index.d.mts 9.33 KB
+DTS dist/index.d.ts  9.33 KB

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @objectstack/plugin-approvals
 
+## 5.2.0
+
+### Minor Changes
+
+- bab2b20: feat(approvals): execution-pinned approval processes (ADR-0009)
+
+  When an approval request is submitted, the engine now records a `process_hash`
+  on `sys_approval_request` — the sha256 of the approval process body resolved
+  through `MetadataRepository`. While the request is in flight, `approve` /
+  `reject` / `recall` resolve the pinned process body via
+  `MetadataRepository.getByHash`. Upgrading the approval process definition
+  mid-flight therefore no longer affects requests that already started against
+  the previous version.
+
+  Behavior:
+
+  - `sys_approval_request` gains a `process_hash` column (text, nullable,
+    read-only). Existing rows keep working — the engine falls back to the
+    current `sys_approval_process` projection when the column is empty.
+  - `ApprovalServiceOptions` accepts an optional `metadataRepo`. When omitted
+    (e.g. defining processes purely through the runtime API or in unit tests),
+    pinning is silently disabled and the service behaves as before.
+  - `ApprovalsServicePlugin` looks up the metadata service from the kernel
+    and wires its repository automatically.
+  - The metadata-core local `MetadataTypeSchema` enum was realigned with the
+    canonical `@objectstack/spec/kernel` enum (drift fix: `approval`, `field`,
+    `function`, `service`, …).
+
+  This is the first user-visible consumer of the `executionPinned` capability
+  introduced in ADR-0009.
+
+### Patch Changes
+
+- Updated dependencies [bab2b20]
+- Updated dependencies [fa011d8]
+- Updated dependencies [f0f7c27]
+- Updated dependencies [b806f58]
+  - @objectstack/platform-objects@5.2.0
+  - @objectstack/spec@5.2.0
+  - @objectstack/metadata-core@5.2.0
+  - @objectstack/core@5.2.0
+  - @objectstack/formula@5.2.0
+
+## 5.1.0
+
+### Patch Changes
+
+- Updated dependencies [75f4ee6]
+- Updated dependencies [823d559]
+  - @objectstack/spec@5.1.0
+  - @objectstack/platform-objects@5.1.0
+  - @objectstack/core@5.1.0
+  - @objectstack/formula@5.1.0
+
 ## 5.0.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 export { SysApprovalAction, SysApprovalProcess, SysApprovalRequest } from '@objectstack/platform-objects/audit';
 import { IApprovalService, DefineApprovalProcessInput, SharingExecutionContext, ApprovalProcessRow, SubmitApprovalInput, ApprovalRequestRow, ApprovalStatus, ApprovalDecisionInput, ApprovalDecisionResult, ApprovalActionRow } from '@objectstack/spec/contracts';
 export { ApprovalActionRow, ApprovalDecisionInput, ApprovalDecisionResult, ApprovalProcessRow, ApprovalRequestRow, ApprovalStatus, DefineApprovalProcessInput, IApprovalService, SubmitApprovalInput } from '@objectstack/spec/contracts';
+import { MetadataRepository } from '@objectstack/metadata-core';
 import { Plugin, PluginContext } from '@objectstack/core';
 
 /**
@@ -70,6 +71,19 @@ interface ApprovalServiceOptions {
      * The plugin uses this to re-bind lifecycle hooks for auto-trigger / lock.
      */
     onRegistryChange?: () => void | Promise<void>;
+    /**
+     * Optional metadata repository for execution-pinned process resolution
+     * (ADR-0009). When provided:
+     *
+     *   - `submit()` records the process body's sha256 on the request row.
+     *   - `approve` / `reject` / `recall` resolve the pinned body via
+     *     `MetadataRepository.getByHash` so process upgrades don't affect
+     *     in-flight requests.
+     *
+     * When omitted, the service reads the current process from the
+     * `sys_approval_process` projection (pre-ADR-0009 behaviour).
+     */
+    metadataRepo?: MetadataRepository;
 }
 declare class ApprovalService implements IApprovalService {
     private readonly engine;
@@ -78,6 +92,7 @@ declare class ApprovalService implements IApprovalService {
     private readonly fetchImpl?;
     private readonly webhookTimeoutMs?;
     private readonly onRegistryChange?;
+    private readonly metadataRepo?;
     constructor(opts: ApprovalServiceOptions);
     /** Allow the plugin to attach a hook re-binding callback after construction. */
     setRegistryChangeHandler(handler: () => void | Promise<void>): void;
@@ -105,6 +120,24 @@ declare class ApprovalService implements IApprovalService {
     private expandRoleUsers;
     private lookupManager;
     private notifyRegistryChanged;
+    /**
+     * Look up the HEAD checksum of an approval process from the metadata repo
+     * (ADR-0009). Returns null when no repo is wired, no metadata exists for
+     * the name, or the lookup fails — callers MUST treat null as "do not pin"
+     * and fall back to the projection table.
+     */
+    private resolveProcessHash;
+    /**
+     * Resolve the approval process for an in-flight request, honouring
+     * ADR-0009 execution pinning when a `process_hash` is recorded.
+     *
+     * Resolution order:
+     *   1. If `req.process_hash` AND `metadataRepo` are set, try
+     *      `getByHash` — return a row whose `definition` is the pinned body.
+     *   2. Otherwise (or on lookup failure) fall back to the current
+     *      projection via `getProcess(req.process_name)`.
+     */
+    private loadProcessForRequest;
     /** Mirror request status onto `process.approvalStatusField` if configured. */
     private syncStatusField;
     /** Convenience wrapper that funnels every action invocation through the executor. */

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { SysApprovalAction, SysApprovalProcess, SysApprovalRequest } from '@objectstack/platform-objects/audit';
 import { IApprovalService, DefineApprovalProcessInput, SharingExecutionContext, ApprovalProcessRow, SubmitApprovalInput, ApprovalRequestRow, ApprovalStatus, ApprovalDecisionInput, ApprovalDecisionResult, ApprovalActionRow } from '@objectstack/spec/contracts';
 export { ApprovalActionRow, ApprovalDecisionInput, ApprovalDecisionResult, ApprovalProcessRow, ApprovalRequestRow, ApprovalStatus, DefineApprovalProcessInput, IApprovalService, SubmitApprovalInput } from '@objectstack/spec/contracts';
+import { MetadataRepository } from '@objectstack/metadata-core';
 import { Plugin, PluginContext } from '@objectstack/core';
 
 /**
@@ -70,6 +71,19 @@ interface ApprovalServiceOptions {
      * The plugin uses this to re-bind lifecycle hooks for auto-trigger / lock.
      */
     onRegistryChange?: () => void | Promise<void>;
+    /**
+     * Optional metadata repository for execution-pinned process resolution
+     * (ADR-0009). When provided:
+     *
+     *   - `submit()` records the process body's sha256 on the request row.
+     *   - `approve` / `reject` / `recall` resolve the pinned body via
+     *     `MetadataRepository.getByHash` so process upgrades don't affect
+     *     in-flight requests.
+     *
+     * When omitted, the service reads the current process from the
+     * `sys_approval_process` projection (pre-ADR-0009 behaviour).
+     */
+    metadataRepo?: MetadataRepository;
 }
 declare class ApprovalService implements IApprovalService {
     private readonly engine;
@@ -78,6 +92,7 @@ declare class ApprovalService implements IApprovalService {
     private readonly fetchImpl?;
     private readonly webhookTimeoutMs?;
     private readonly onRegistryChange?;
+    private readonly metadataRepo?;
     constructor(opts: ApprovalServiceOptions);
     /** Allow the plugin to attach a hook re-binding callback after construction. */
     setRegistryChangeHandler(handler: () => void | Promise<void>): void;
@@ -105,6 +120,24 @@ declare class ApprovalService implements IApprovalService {
     private expandRoleUsers;
     private lookupManager;
     private notifyRegistryChanged;
+    /**
+     * Look up the HEAD checksum of an approval process from the metadata repo
+     * (ADR-0009). Returns null when no repo is wired, no metadata exists for
+     * the name, or the lookup fails — callers MUST treat null as "do not pin"
+     * and fall back to the projection table.
+     */
+    private resolveProcessHash;
+    /**
+     * Resolve the approval process for an in-flight request, honouring
+     * ADR-0009 execution pinning when a `process_hash` is recorded.
+     *
+     * Resolution order:
+     *   1. If `req.process_hash` AND `metadataRepo` are set, try
+     *      `getByHash` — return a row whose `definition` is the pinned body.
+     *   2. Otherwise (or on lookup failure) fall back to the current
+     *      projection via `getProcess(req.process_name)`.
+     */
+    private loadProcessForRequest;
     /** Mirror request status onto `process.approvalStatusField` if configured. */
     private syncStatusField;
     /** Convenience wrapper that funnels every action invocation through the executor. */

package/dist/index.js

@@ -265,6 +265,7 @@ function rowFromRequest(row) {
     id: String(row.id),
     organization_id: row.organization_id ?? void 0,
     process_name: String(row.process_name ?? ""),
+    process_hash: row.process_hash ?? void 0,
     object_name: String(row.object_name ?? ""),
     record_id: String(row.record_id ?? ""),
     submitter_id: row.submitter_id ?? void 0,
@@ -299,6 +300,7 @@ var ApprovalService = class {
     this.fetchImpl = opts.fetch;
     this.webhookTimeoutMs = opts.webhookTimeoutMs;
     this.onRegistryChange = opts.onRegistryChange;
+    this.metadataRepo = opts.metadataRepo;
   }
   /** Allow the plugin to attach a hook re-binding callback after construction. */
   setRegistryChangeHandler(handler) {
@@ -467,6 +469,70 @@ var ApprovalService = class {
       this.logger?.warn?.("[approvals] onRegistryChange handler failed", { error: err?.message });
     }
   }
+  /**
+   * Look up the HEAD checksum of an approval process from the metadata repo
+   * (ADR-0009). Returns null when no repo is wired, no metadata exists for
+   * the name, or the lookup fails — callers MUST treat null as "do not pin"
+   * and fall back to the projection table.
+   */
+  async resolveProcessHash(processName, organizationId) {
+    if (!this.metadataRepo) return null;
+    if (!processName) return null;
+    const orgRef = { org: organizationId || "system", type: "approval", name: processName };
+    try {
+      const head = await this.metadataRepo.get(orgRef);
+      return head?.hash ?? null;
+    } catch (err) {
+      this.logger?.debug?.("[approvals] metadataRepo.get failed", { name: processName, error: err?.message });
+      return null;
+    }
+  }
+  /**
+   * Resolve the approval process for an in-flight request, honouring
+   * ADR-0009 execution pinning when a `process_hash` is recorded.
+   *
+   * Resolution order:
+   *   1. If `req.process_hash` AND `metadataRepo` are set, try
+   *      `getByHash` — return a row whose `definition` is the pinned body.
+   *   2. Otherwise (or on lookup failure) fall back to the current
+   *      projection via `getProcess(req.process_name)`.
+   */
+  async loadProcessForRequest(req, context) {
+    const hash = req.process_hash;
+    if (hash && this.metadataRepo) {
+      const orgId = req.organization_id ?? null;
+      const orgRef = { org: orgId || "system", type: "approval", name: req.process_name };
+      try {
+        const pinned = await this.metadataRepo.getByHash(orgRef, hash);
+        if (pinned?.body) {
+          const current = await this.getProcess(req.process_name, context);
+          const body = pinned.body;
+          return {
+            id: current?.id ?? `pinned_${hash.slice(7, 19)}`,
+            name: req.process_name,
+            label: body.label ?? current?.label ?? req.process_name,
+            object_name: req.object_name,
+            description: body.description ?? current?.description,
+            active: current?.active ?? true,
+            definition: body,
+            created_at: current?.created_at,
+            updated_at: current?.updated_at
+          };
+        }
+        this.logger?.warn?.("[approvals] pinned process body not found; falling back to current", {
+          request: req.id,
+          process: req.process_name,
+          hash
+        });
+      } catch (err) {
+        this.logger?.warn?.("[approvals] getByHash failed; falling back to current", {
+          request: req.id,
+          error: err?.message
+        });
+      }
+    }
+    return this.getProcess(req.process_name, context);
+  }
   /** Mirror request status onto `process.approvalStatusField` if configured. */
   async syncStatusField(process, request) {
     const field = process.definition?.approvalStatusField;
@@ -607,9 +673,11 @@ var ApprovalService = class {
     const approvers = await this.expandApprovers(step0, input.payload, ctxOrg);
     const now = this.clock.now().toISOString();
     const id = uid("areq");
+    const processHash = await this.resolveProcessHash(process.name, ctxOrg);
     const row = {
       id,
       process_name: process.name,
+      process_hash: processHash,
       object_name: input.object,
       record_id: input.recordId,
       submitter_id: input.submitterId ?? context.userId ?? null,
@@ -693,7 +761,7 @@ var ApprovalService = class {
     if (!context.isSystem && !(req.pending_approvers ?? []).includes(input.actorId)) {
       throw new Error(`FORBIDDEN: actor '${input.actorId}' is not a pending approver`);
     }
-    const process = await this.getProcess(req.process_name, context);
+    const process = await this.loadProcessForRequest(req, context);
     if (!process) throw new Error(`PROCESS_NOT_FOUND: ${req.process_name}`);
     const steps = process.definition?.steps ?? [];
     const stepIndex = req.current_step_index ?? 0;
@@ -765,7 +833,7 @@ var ApprovalService = class {
     if (!context.isSystem && !(req.pending_approvers ?? []).includes(input.actorId)) {
       throw new Error(`FORBIDDEN: actor '${input.actorId}' is not a pending approver`);
     }
-    const process = await this.getProcess(req.process_name, context);
+    const process = await this.loadProcessForRequest(req, context);
     if (!process) throw new Error(`PROCESS_NOT_FOUND: ${req.process_name}`);
     const steps = process.definition?.steps ?? [];
     const stepIndex = req.current_step_index ?? 0;
@@ -837,7 +905,7 @@ var ApprovalService = class {
       updated_at: now
     }, { context: SYSTEM_CTX2 });
     const fresh = await this.getRequest(req.id, context);
-    const process = await this.getProcess(req.process_name, context);
+    const process = await this.loadProcessForRequest(req, context);
     if (process) {
       await this.syncStatusField(process, fresh);
       await this.runActions(process.definition?.onRecall, "recall", process, fresh, void 0, input.actorId, input.comment);
@@ -1047,10 +1115,20 @@ var ApprovalsServicePlugin = class {
     }
     this.engine = engine;
     this.logger = ctx.logger;
+    let metadataRepo;
+    try {
+      const meta = ctx.getService("metadata");
+      metadataRepo = meta?.getRepository?.();
+    } catch {
+    }
     this.service = new ApprovalService({
       engine,
-      logger: ctx.logger
+      logger: ctx.logger,
+      metadataRepo
     });
+    if (metadataRepo) {
+      ctx.logger.info("ApprovalsServicePlugin: execution pinning enabled (ADR-0009)");
+    }
     if (!this.options.disableAutoHooks) {
       this.service.setRegistryChangeHandler(() => this.rebindHooks());
       const hookOn = ctx.hook ?? ctx.on;