@rytass/bpm-core-nestjs-module 0.22.0 → 0.24.0

package/src/lib/instance-event/instance-event.options.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BPM_INSTANCE_EVENT_DELIVERY_OPTIONS = void 0;
+exports.resolveInstanceEventDeliveryOptions = resolveInstanceEventDeliveryOptions;
+exports.DEFAULT_BPM_INSTANCE_EVENT_DELIVERY_OPTIONS = {
+    batchSize: 25,
+    dispatchTimeoutMs: 10_000,
+    maxAttempts: 6,
+    maxRetryDelayMs: 3_600_000,
+    retentionDays: 30,
+    retryBaseDelayMs: 30_000,
+    scanIntervalMs: 15_000,
+};
+/**
+ * Fills every unset or non-positive field from the defaults. A host that sets
+ * `batchSize: 0` gets 25, not an outbox that never delivers.
+ */
+function resolveInstanceEventDeliveryOptions(overrides) {
+    const defaults = exports.DEFAULT_BPM_INSTANCE_EVENT_DELIVERY_OPTIONS;
+    return {
+        batchSize: readPositive(overrides?.batchSize, defaults.batchSize),
+        dispatchTimeoutMs: readPositive(overrides?.dispatchTimeoutMs, defaults.dispatchTimeoutMs),
+        maxAttempts: readPositive(overrides?.maxAttempts, defaults.maxAttempts),
+        maxRetryDelayMs: readPositive(overrides?.maxRetryDelayMs, defaults.maxRetryDelayMs),
+        retentionDays: readPositive(overrides?.retentionDays, defaults.retentionDays),
+        retryBaseDelayMs: readPositive(overrides?.retryBaseDelayMs, defaults.retryBaseDelayMs),
+        scanIntervalMs: readPositive(overrides?.scanIntervalMs, defaults.scanIntervalMs),
+    };
+}
+function readPositive(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : fallback;
+}
+//# sourceMappingURL=instance-event.options.js.map

package/src/lib/instance-event/instance-event.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-event.options.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/instance-event/instance-event.options.ts"],"names":[],"mappings":";;;AAoCA,kFA6BC;AA5CY,QAAA,2CAA2C,GACtD;IACE,SAAS,EAAE,EAAE;IACb,iBAAiB,EAAE,MAAM;IACzB,WAAW,EAAE,CAAC;IACd,eAAe,EAAE,SAAS;IAC1B,aAAa,EAAE,EAAE;IACjB,gBAAgB,EAAE,MAAM;IACxB,cAAc,EAAE,MAAM;CACvB,CAAC;AAEJ;;;GAGG;AACH,SAAgB,mCAAmC,CACjD,SAA+D;IAE/D,MAAM,QAAQ,GAAG,mDAA2C,CAAC;IAE7D,OAAO;QACL,SAAS,EAAE,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,CAAC;QACjE,iBAAiB,EAAE,YAAY,CAC7B,SAAS,EAAE,iBAAiB,EAC5B,QAAQ,CAAC,iBAAiB,CAC3B;QACD,WAAW,EAAE,YAAY,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC;QACvE,eAAe,EAAE,YAAY,CAC3B,SAAS,EAAE,eAAe,EAC1B,QAAQ,CAAC,eAAe,CACzB;QACD,aAAa,EAAE,YAAY,CACzB,SAAS,EAAE,aAAa,EACxB,QAAQ,CAAC,aAAa,CACvB;QACD,gBAAgB,EAAE,YAAY,CAC5B,SAAS,EAAE,gBAAgB,EAC3B,QAAQ,CAAC,gBAAgB,CAC1B;QACD,cAAc,EAAE,YAAY,CAC1B,SAAS,EAAE,cAAc,EACzB,QAAQ,CAAC,cAAc,CACxB;KACF,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,KAAyB,EAAE,QAAgB;IAC/D,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QACrE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QACnB,CAAC,CAAC,QAAQ,CAAC;AACf,CAAC"}

package/src/lib/instance-event/instance-event.resolver.d.ts

@@ -0,0 +1,10 @@
+import { InstanceEventDeliveryService } from './instance-event.delivery.service';
+import { ApprovalInstanceEventStatusEnum } from './instance-event.enums';
+import { ApprovalInstanceEventObject, ApprovalInstanceEventPageObject } from './instance-event.object';
+/** Admin access to the outbox: triage failed deliveries and retry them. */
+export declare class InstanceEventResolver {
+    private readonly deliveryService;
+    constructor(deliveryService: InstanceEventDeliveryService);
+    approvalInstanceEvents(instanceId?: string | null, status?: ApprovalInstanceEventStatusEnum | null, page?: number, pageSize?: number): Promise<ApprovalInstanceEventPageObject>;
+    retryApprovalInstanceEvent(id: string): Promise<ApprovalInstanceEventObject>;
+}

package/src/lib/instance-event/instance-event.resolver.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstanceEventResolver = void 0;
+const tslib_1 = require("tslib");
+const graphql_1 = require("@nestjs/graphql");
+const bpm_auth_1 = require("../bpm-auth");
+const instance_event_delivery_service_1 = require("./instance-event.delivery.service");
+const instance_event_enums_1 = require("./instance-event.enums");
+const instance_event_object_1 = require("./instance-event.object");
+/** Admin access to the outbox: triage failed deliveries and retry them. */
+let InstanceEventResolver = class InstanceEventResolver {
+    constructor(deliveryService) {
+        this.deliveryService = deliveryService;
+    }
+    async approvalInstanceEvents(instanceId, status, page = 1, pageSize = 50) {
+        const result = await this.deliveryService.listEvents({
+            instanceId: instanceId ?? null,
+            page,
+            pageSize,
+            status: status ? instance_event_enums_1.APPROVAL_INSTANCE_EVENT_ENUM_TO_STATUS[status] : null,
+        });
+        return Object.assign(new instance_event_object_1.ApprovalInstanceEventPageObject(), {
+            items: result.items.map((row) => toObject(row)),
+            total: result.total,
+        });
+    }
+    async retryApprovalInstanceEvent(id) {
+        return toObject(await this.deliveryService.retryFailedEvent(id));
+    }
+};
+exports.InstanceEventResolver = InstanceEventResolver;
+tslib_1.__decorate([
+    (0, graphql_1.Query)(() => instance_event_object_1.ApprovalInstanceEventPageObject),
+    tslib_1.__param(0, (0, graphql_1.Args)('instanceId', { nullable: true, type: () => graphql_1.ID })),
+    tslib_1.__param(1, (0, graphql_1.Args)('status', {
+        nullable: true,
+        type: () => instance_event_enums_1.ApprovalInstanceEventStatusEnum,
+    })),
+    tslib_1.__param(2, (0, graphql_1.Args)('page', { defaultValue: 1, type: () => graphql_1.Int })),
+    tslib_1.__param(3, (0, graphql_1.Args)('pageSize', { defaultValue: 50, type: () => graphql_1.Int })),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [Object, Object, Object, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], InstanceEventResolver.prototype, "approvalInstanceEvents", null);
+tslib_1.__decorate([
+    (0, graphql_1.Mutation)(() => instance_event_object_1.ApprovalInstanceEventObject),
+    tslib_1.__param(0, (0, graphql_1.Args)('id', { type: () => graphql_1.ID })),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String]),
+    tslib_1.__metadata("design:returntype", Promise)
+], InstanceEventResolver.prototype, "retryApprovalInstanceEvent", null);
+exports.InstanceEventResolver = InstanceEventResolver = tslib_1.__decorate([
+    (0, graphql_1.Resolver)(),
+    (0, bpm_auth_1.BPMAdminOnly)(),
+    tslib_1.__metadata("design:paramtypes", [instance_event_delivery_service_1.InstanceEventDeliveryService])
+], InstanceEventResolver);
+/**
+ * Field by field, so `payload` and `claimedAt` never reach the GraphQL
+ * response even if the entity gains fields later.
+ */
+function toObject(row) {
+    return Object.assign(new instance_event_object_1.ApprovalInstanceEventObject(), {
+        attemptCount: row.attemptCount,
+        deliveredAt: row.deliveredAt,
+        id: row.id,
+        instanceId: row.instanceId,
+        lastError: row.lastError,
+        nextAttemptAt: row.nextAttemptAt,
+        occurredAt: row.occurredAt,
+        seq: row.seq,
+        status: instance_event_enums_1.APPROVAL_INSTANCE_EVENT_STATUS_TO_ENUM[row.status],
+        type: row.type,
+    });
+}
+//# sourceMappingURL=instance-event.resolver.js.map

package/src/lib/instance-event/instance-event.resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-event.resolver.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/instance-event/instance-event.resolver.ts"],"names":[],"mappings":";;;;AAAA,6CAA2E;AAC3E,0CAA2C;AAE3C,uFAAiF;AACjF,iEAIgC;AAChC,mEAGiC;AAEjC,2EAA2E;AAGpE,IAAM,qBAAqB,GAA3B,MAAM,qBAAqB;IAChC,YAA6B,eAA6C;QAA7C,oBAAe,GAAf,eAAe,CAA8B;IAAG,CAAC;IAGxE,AAAN,KAAK,CAAC,sBAAsB,CAE1B,UAA0B,EAK1B,MAA+C,EACK,OAAO,CAAC,EACH,WAAW,EAAE;QAEtE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC;YACnD,UAAU,EAAE,UAAU,IAAI,IAAI;YAC9B,IAAI;YACJ,QAAQ;YACR,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,6DAAsC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI;SACvE,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,uDAA+B,EAAE,EAAE;YAC1D,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC/C,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC,CAAC;IACL,CAAC;IAGK,AAAN,KAAK,CAAC,0BAA0B,CACE,EAAU;QAE1C,OAAO,QAAQ,CAAC,MAAM,IAAI,CAAC,eAAe,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC;IACnE,CAAC;CACF,CAAA;AAlCY,sDAAqB;AAI1B;IADL,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,uDAA+B,CAAC;IAE1C,mBAAA,IAAA,cAAI,EAAC,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,YAAE,EAAE,CAAC,CAAA;IAEtD,mBAAA,IAAA,cAAI,EAAC,QAAQ,EAAE;QACd,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,GAAG,EAAE,CAAC,sDAA+B;KAC5C,CAAC,CAAA;IAED,mBAAA,IAAA,cAAI,EAAC,MAAM,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,aAAG,EAAE,CAAC,CAAA;IAClD,mBAAA,IAAA,cAAI,EAAC,UAAU,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,aAAG,EAAE,CAAC,CAAA;;;;mEAazD;AAGK;IADL,IAAA,kBAAQ,EAAC,GAAG,EAAE,CAAC,mDAA2B,CAAC;IAEzC,mBAAA,IAAA,cAAI,EAAC,IAAI,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,YAAE,EAAE,CAAC,CAAA;;;;uEAGhC;gCAjCU,qBAAqB;IAFjC,IAAA,kBAAQ,GAAE;IACV,IAAA,uBAAY,GAAE;6CAEiC,8DAA4B;GAD/D,qBAAqB,CAkCjC;AAED;;;GAGG;AACH,SAAS,QAAQ,CACf,GAAgC;IAEhC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,mDAA2B,EAAE,EAAE;QACtD,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,MAAM,EAAE,6DAAsC,CAAC,GAAG,CAAC,MAAM,CAAC;QAC1D,IAAI,EAAE,GAAG,CAAC,IAAI;KACf,CAAC,CAAC;AACL,CAAC"}

package/src/lib/instance-event/instance-event.service.d.ts

@@ -0,0 +1,18 @@
+import { BPMRootRuntimeOptions } from '../bpm/bpm-root-options';
+import { BPMInstanceEventDeliveryOptions } from './instance-event.options';
+import { BPMInstanceEventObserver } from './instance-event.token';
+/**
+ * Holds the host observer for instance lifecycle events. `observer` is `null`
+ * when the host bound none; the engine then writes no outbox rows.
+ *
+ * Resolution: the Nest provider (`BPM_INSTANCE_EVENT_OBSERVER`) wins over the
+ * runtime option `BPMRootRuntimeOptions.instanceEventObserver`.
+ *
+ * `delivery` is the resolved outbox tuning, with unset fields defaulted.
+ */
+export declare class InstanceEventService {
+    readonly observer: BPMInstanceEventObserver | null;
+    readonly delivery: BPMInstanceEventDeliveryOptions;
+    constructor(injectedObserver: BPMInstanceEventObserver | undefined, rootOptions: BPMRootRuntimeOptions | undefined);
+    get enabled(): boolean;
+}

package/src/lib/instance-event/instance-event.service.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstanceEventService = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const bpm_root_options_1 = require("../bpm/bpm-root-options");
+const instance_event_options_1 = require("./instance-event.options");
+const instance_event_token_1 = require("./instance-event.token");
+/**
+ * Holds the host observer for instance lifecycle events. `observer` is `null`
+ * when the host bound none; the engine then writes no outbox rows.
+ *
+ * Resolution: the Nest provider (`BPM_INSTANCE_EVENT_OBSERVER`) wins over the
+ * runtime option `BPMRootRuntimeOptions.instanceEventObserver`.
+ *
+ * `delivery` is the resolved outbox tuning, with unset fields defaulted.
+ */
+let InstanceEventService = class InstanceEventService {
+    constructor(injectedObserver, rootOptions) {
+        this.observer =
+            injectedObserver ?? rootOptions?.instanceEventObserver ?? null;
+        this.delivery = (0, instance_event_options_1.resolveInstanceEventDeliveryOptions)(rootOptions?.instanceEventDelivery);
+    }
+    get enabled() {
+        return this.observer !== null;
+    }
+};
+exports.InstanceEventService = InstanceEventService;
+exports.InstanceEventService = InstanceEventService = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, common_1.Optional)()),
+    tslib_1.__param(0, (0, common_1.Inject)(instance_event_token_1.BPM_INSTANCE_EVENT_OBSERVER)),
+    tslib_1.__param(1, (0, common_1.Optional)()),
+    tslib_1.__param(1, (0, common_1.Inject)(bpm_root_options_1.BPM_ROOT_OPTIONS)),
+    tslib_1.__metadata("design:paramtypes", [Object, Object])
+], InstanceEventService);
+//# sourceMappingURL=instance-event.service.js.map

package/src/lib/instance-event/instance-event.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-event.service.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/instance-event/instance-event.service.ts"],"names":[],"mappings":";;;;AAAA,2CAA8D;AAC9D,8DAGiC;AACjC,qEAGkC;AAClC,iEAGgC;AAEhC;;;;;;;;GAQG;AAEI,IAAM,oBAAoB,GAA1B,MAAM,oBAAoB;IAI/B,YAGE,gBAAsD,EAGtD,WAA8C;QAE9C,IAAI,CAAC,QAAQ;YACX,gBAAgB,IAAI,WAAW,EAAE,qBAAqB,IAAI,IAAI,CAAC;QACjE,IAAI,CAAC,QAAQ,GAAG,IAAA,4DAAmC,EACjD,WAAW,EAAE,qBAAqB,CACnC,CAAC;IACJ,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC;IAChC,CAAC;CACF,CAAA;AAtBY,oDAAoB;+BAApB,oBAAoB;IADhC,IAAA,mBAAU,GAAE;IAMR,mBAAA,IAAA,iBAAQ,GAAE,CAAA;IACV,mBAAA,IAAA,eAAM,EAAC,kDAA2B,CAAC,CAAA;IAEnC,mBAAA,IAAA,iBAAQ,GAAE,CAAA;IACV,mBAAA,IAAA,eAAM,EAAC,mCAAgB,CAAC,CAAA;;GAThB,oBAAoB,CAsBhC"}

package/src/lib/instance-event/instance-event.token.d.ts

@@ -0,0 +1,19 @@
+import { InjectionToken } from '@nestjs/common';
+import type { BPMInstanceEvent } from './instance-event.types';
+/**
+ * Host hook that receives approval instance lifecycle events (ADR 27 §1).
+ *
+ * Delivery is at-least-once and runs after the state change has committed. A
+ * redelivered event carries the same `event.id`, so the host dedupes on it.
+ * Events of one instance arrive in `seq` order; events of different instances
+ * have no ordering guarantee. A thrown error is retried with backoff and the
+ * event is marked FAILED after the retry limit.
+ */
+export interface BPMInstanceEventObserver {
+    onInstanceEvent(event: BPMInstanceEvent): Promise<void> | void;
+}
+/**
+ * Optional host binding for {@link BPMInstanceEventObserver}. Without an
+ * observer, the engine writes no event rows at all.
+ */
+export declare const BPM_INSTANCE_EVENT_OBSERVER: InjectionToken<BPMInstanceEventObserver>;

package/src/lib/instance-event/instance-event.token.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BPM_INSTANCE_EVENT_OBSERVER = void 0;
+/**
+ * Optional host binding for {@link BPMInstanceEventObserver}. Without an
+ * observer, the engine writes no event rows at all.
+ */
+exports.BPM_INSTANCE_EVENT_OBSERVER = Symbol('BPM_INSTANCE_EVENT_OBSERVER');
+//# sourceMappingURL=instance-event.token.js.map

package/src/lib/instance-event/instance-event.token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-event.token.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/instance-event/instance-event.token.ts"],"names":[],"mappings":";;;AAgBA;;;GAGG;AACU,QAAA,2BAA2B,GACtC,MAAM,CAAC,6BAA6B,CAAC,CAAC"}

package/src/lib/instance-event/instance-event.types.d.ts

@@ -0,0 +1,67 @@
+import type { ApprovalInstanceStateEnum } from '../workflow-engine/workflow-engine.enums';
+/** Empty payload for event types that carry no type-specific fields. */
+export type BPMInstanceEventNoPayload = Readonly<Record<never, never>>;
+/**
+ * Type-specific fields per event type (ADR 27 §1.3). `formData` is never part
+ * of an event: a host that needs it reads the instance by `instanceId`.
+ */
+export interface BPMInstanceEventTypePayloads {
+    readonly INSTANCE_APPROVED: BPMInstanceEventNoPayload;
+    readonly INSTANCE_CANCELLED: {
+        readonly actorMemberId: string | null;
+    };
+    readonly INSTANCE_EXPIRED: BPMInstanceEventNoPayload;
+    readonly INSTANCE_REJECTED: {
+        readonly actorMemberId: string | null;
+    };
+    readonly INSTANCE_RESUBMITTED: {
+        readonly actorMemberId: string | null;
+    };
+    readonly INSTANCE_RETURNED: {
+        readonly actorMemberId: string | null;
+        readonly nodeId: string;
+    };
+    readonly INSTANCE_SUBMITTED: {
+        readonly actorMemberId: string | null;
+    };
+    readonly NODE_ACTIVATED: {
+        readonly nodeId: string;
+        readonly taskIds: readonly string[];
+    };
+    readonly TASK_AUTO_DECISION_FAILED: {
+        readonly reason: string;
+        readonly taskId: string;
+    };
+}
+export type BPMInstanceEventType = keyof BPMInstanceEventTypePayloads;
+/**
+ * Template and state at the moment the event was written. The table has no
+ * columns for these, so they are stored inside `payload`.
+ */
+export interface BPMInstanceEventSnapshot {
+    readonly instanceState: ApprovalInstanceStateEnum;
+    readonly templateId: string;
+    readonly templateKey: string | null;
+    readonly templateVersionId: string;
+}
+/** Columns that every delivered event carries. */
+export interface BPMInstanceEventHeader {
+    /** Generated by the database. Stable across redeliveries; dedupe on it. */
+    readonly id: string;
+    readonly instanceId: string;
+    /** Write order, assigned by the database. A bigint, so a string. */
+    readonly seq: string;
+    readonly occurredAt: string;
+}
+/** The payload stored in `approval_instance_events.payload`. */
+export type BPMInstanceEventPayload = {
+    readonly [K in BPMInstanceEventType]: BPMInstanceEventSnapshot & BPMInstanceEventTypePayloads[K];
+}[BPMInstanceEventType];
+/** What the observer receives. Discriminated on `type`. */
+export type BPMInstanceEvent = {
+    readonly [K in BPMInstanceEventType]: BPMInstanceEventHeader & {
+        readonly type: K;
+    } & BPMInstanceEventSnapshot & BPMInstanceEventTypePayloads[K];
+}[BPMInstanceEventType];
+export declare const BPM_INSTANCE_EVENT_STATUSES: readonly ["PENDING", "DELIVERED", "FAILED"];
+export type BPMInstanceEventStatus = (typeof BPM_INSTANCE_EVENT_STATUSES)[number];

package/src/lib/instance-event/instance-event.types.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BPM_INSTANCE_EVENT_STATUSES = void 0;
+exports.BPM_INSTANCE_EVENT_STATUSES = [
+    'PENDING',
+    'DELIVERED',
+    'FAILED',
+];
+//# sourceMappingURL=instance-event.types.js.map

package/src/lib/instance-event/instance-event.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-event.types.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/instance-event/instance-event.types.ts"],"names":[],"mappings":";;;AAmEa,QAAA,2BAA2B,GAAG;IACzC,SAAS;IACT,WAAW;IACX,QAAQ;CACA,CAAC"}

package/src/lib/instance-event/instance-event.writer.d.ts

@@ -0,0 +1,21 @@
+import type { EntityManager } from 'typeorm';
+import { InstanceEventService } from './instance-event.service';
+import type { BPMInstanceEventSnapshot, BPMInstanceEventType, BPMInstanceEventTypePayloads } from './instance-event.types';
+/**
+ * Writes outbox rows inside the caller's transaction (ADR 27 §1.2). Rows are
+ * written only when a host observer is bound; otherwise this is a no-op and
+ * the engine behaves as it did in 0.22.0.
+ *
+ * Uses `save` rather than `insert` so the TypeORM `afterInsert` event fires
+ * and the delivery subscriber can stage the new id for after-commit delivery.
+ */
+export declare class InstanceEventWriter {
+    private readonly events;
+    constructor(events: InstanceEventService);
+    /**
+     * Whether a host observer is bound. Callers use this to skip building a
+     * snapshot (for example a template lookup) when no row would be written.
+     */
+    get enabled(): boolean;
+    record<K extends BPMInstanceEventType>(manager: EntityManager, instanceId: string, snapshot: BPMInstanceEventSnapshot, type: K, fields: BPMInstanceEventTypePayloads[K]): Promise<void>;
+}

package/src/lib/instance-event/instance-event.writer.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstanceEventWriter = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const approval_instance_event_entity_1 = require("./approval-instance-event.entity");
+const instance_event_service_1 = require("./instance-event.service");
+/**
+ * Writes outbox rows inside the caller's transaction (ADR 27 §1.2). Rows are
+ * written only when a host observer is bound; otherwise this is a no-op and
+ * the engine behaves as it did in 0.22.0.
+ *
+ * Uses `save` rather than `insert` so the TypeORM `afterInsert` event fires
+ * and the delivery subscriber can stage the new id for after-commit delivery.
+ */
+let InstanceEventWriter = class InstanceEventWriter {
+    constructor(events) {
+        this.events = events;
+    }
+    /**
+     * Whether a host observer is bound. Callers use this to skip building a
+     * snapshot (for example a template lookup) when no row would be written.
+     */
+    get enabled() {
+        return this.events.enabled;
+    }
+    async record(manager, instanceId, snapshot, type, fields) {
+        if (!this.events.enabled) {
+            return;
+        }
+        const repository = manager.getRepository(approval_instance_event_entity_1.ApprovalInstanceEventEntity);
+        const row = repository.create({
+            instanceId,
+            payload: { ...snapshot, ...fields },
+            type,
+        });
+        await repository.save(row);
+    }
+};
+exports.InstanceEventWriter = InstanceEventWriter;
+exports.InstanceEventWriter = InstanceEventWriter = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [instance_event_service_1.InstanceEventService])
+], InstanceEventWriter);
+//# sourceMappingURL=instance-event.writer.js.map

package/src/lib/instance-event/instance-event.writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-event.writer.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/instance-event/instance-event.writer.ts"],"names":[],"mappings":";;;;AAAA,2CAA4C;AAE5C,qFAA+E;AAC/E,qEAAgE;AAOhE;;;;;;;GAOG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAC9B,YAA6B,MAA4B;QAA5B,WAAM,GAAN,MAAM,CAAsB;IAAG,CAAC;IAE7D;;;OAGG;IACH,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,MAAM,CACV,OAAsB,EACtB,UAAkB,EAClB,QAAkC,EAClC,IAAO,EACP,MAAuC;QAEvC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACzB,OAAO;QACT,CAAC;QAED,MAAM,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,4DAA2B,CAAC,CAAC;QACtE,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,CAAC;YAC5B,UAAU;YACV,OAAO,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,EAAE;YACnC,IAAI;SACL,CAAC,CAAC;QAEH,MAAM,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;CACF,CAAA;AA/BY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;6CAE0B,6CAAoB;GAD9C,mBAAmB,CA+B/B"}

package/src/lib/migrations/0000000032000-host-integration-round.d.ts

@@ -0,0 +1,25 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+/**
+ * Schema for ADR 27 (host integration round). Every change is additive and its
+ * default is the behaviour before this migration, so `down` can drop it all.
+ *
+ * - `approval_templates.key`: a key the host declares for a template it owns
+ *   (§6). Unique among templates that are not soft-deleted, so a deleted
+ *   template frees its key.
+ * - `approval_templates.host_managed` / `form_definitions.host_managed`: the
+ *   definition is maintained by host code and BPM's own lists leave it out by
+ *   default (§9). Not a lock.
+ * - `approval_template_versions.launch_mode`: `HOST_ONLY` refuses submission
+ *   and resubmission through GraphQL (§5). Versioned with
+ *   `initiator_policy_cel`, which it sits beside.
+ * - `approval_instance_events`: outbox of instance lifecycle events (§1). A row
+ *   is written inside the transaction that changes the instance and delivered
+ *   to the host's observer after it commits. `seq` orders the events of one
+ *   instance; it is not a cursor across instances, because identity values are
+ *   assigned at insert, not at commit.
+ */
+export declare class HostIntegrationRound0000000032000 implements MigrationInterface {
+    name: string;
+    up(queryRunner: QueryRunner): Promise<void>;
+    down(queryRunner: QueryRunner): Promise<void>;
+}

package/src/lib/migrations/0000000032000-host-integration-round.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HostIntegrationRound0000000032000 = void 0;
+/**
+ * Schema for ADR 27 (host integration round). Every change is additive and its
+ * default is the behaviour before this migration, so `down` can drop it all.
+ *
+ * - `approval_templates.key`: a key the host declares for a template it owns
+ *   (§6). Unique among templates that are not soft-deleted, so a deleted
+ *   template frees its key.
+ * - `approval_templates.host_managed` / `form_definitions.host_managed`: the
+ *   definition is maintained by host code and BPM's own lists leave it out by
+ *   default (§9). Not a lock.
+ * - `approval_template_versions.launch_mode`: `HOST_ONLY` refuses submission
+ *   and resubmission through GraphQL (§5). Versioned with
+ *   `initiator_policy_cel`, which it sits beside.
+ * - `approval_instance_events`: outbox of instance lifecycle events (§1). A row
+ *   is written inside the transaction that changes the instance and delivered
+ *   to the host's observer after it commits. `seq` orders the events of one
+ *   instance; it is not a cursor across instances, because identity values are
+ *   assigned at insert, not at commit.
+ */
+class HostIntegrationRound0000000032000 {
+    constructor() {
+        this.name = 'HostIntegrationRound0000000032000';
+    }
+    async up(queryRunner) {
+        await queryRunner.query(`
+      ALTER TABLE "approval_templates"
+        ADD COLUMN IF NOT EXISTS "key" text NULL,
+        ADD COLUMN IF NOT EXISTS "host_managed" boolean NOT NULL DEFAULT false
+    `);
+        await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS "UQ_approval_templates_key_live"
+      ON "approval_templates" ("key")
+      WHERE "key" IS NOT NULL AND "deleted_at" IS NULL
+    `);
+        await queryRunner.query(`
+      ALTER TABLE "form_definitions"
+        ADD COLUMN IF NOT EXISTS "host_managed" boolean NOT NULL DEFAULT false
+    `);
+        await queryRunner.query(`
+      ALTER TABLE "approval_template_versions"
+        ADD COLUMN IF NOT EXISTS "launch_mode" text NOT NULL DEFAULT 'OPEN'
+    `);
+        await queryRunner.query(`
+      ALTER TABLE "approval_template_versions"
+        DROP CONSTRAINT IF EXISTS "CHK_approval_template_versions_launch_mode"
+    `);
+        await queryRunner.query(`
+      ALTER TABLE "approval_template_versions"
+        ADD CONSTRAINT "CHK_approval_template_versions_launch_mode"
+        CHECK ("launch_mode" IN ('OPEN', 'HOST_ONLY'))
+    `);
+        await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS "approval_instance_events" (
+        "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        "seq" bigint GENERATED ALWAYS AS IDENTITY,
+        "instance_id" uuid NOT NULL,
+        "type" text NOT NULL,
+        "payload" jsonb NOT NULL,
+        "status" text NOT NULL DEFAULT 'PENDING',
+        "attempt_count" integer NOT NULL DEFAULT 0,
+        "next_attempt_at" timestamptz NOT NULL DEFAULT now(),
+        "claimed_at" timestamptz NULL,
+        "delivered_at" timestamptz NULL,
+        "last_error" text NULL,
+        "occurred_at" timestamptz NOT NULL DEFAULT now(),
+        CONSTRAINT "FK_approval_instance_events_instance"
+          FOREIGN KEY ("instance_id") REFERENCES "approval_instances"("id")
+          ON DELETE CASCADE,
+        CONSTRAINT "CHK_approval_instance_events_status"
+          CHECK ("status" IN ('PENDING', 'DELIVERED', 'FAILED'))
+      )
+    `);
+        await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_approval_instance_events_due"
+      ON "approval_instance_events" ("status", "next_attempt_at")
+    `);
+        await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_approval_instance_events_instance_seq"
+      ON "approval_instance_events" ("instance_id", "seq")
+    `);
+    }
+    async down(queryRunner) {
+        await queryRunner.query(`DROP TABLE IF EXISTS "approval_instance_events"`);
+        await queryRunner.query(`
+      ALTER TABLE "approval_template_versions"
+        DROP CONSTRAINT IF EXISTS "CHK_approval_template_versions_launch_mode",
+        DROP COLUMN IF EXISTS "launch_mode"
+    `);
+        await queryRunner.query(`
+      ALTER TABLE "form_definitions" DROP COLUMN IF EXISTS "host_managed"
+    `);
+        await queryRunner.query(`DROP INDEX IF EXISTS "UQ_approval_templates_key_live"`);
+        await queryRunner.query(`
+      ALTER TABLE "approval_templates"
+        DROP COLUMN IF EXISTS "host_managed",
+        DROP COLUMN IF EXISTS "key"
+    `);
+    }
+}
+exports.HostIntegrationRound0000000032000 = HostIntegrationRound0000000032000;
+//# sourceMappingURL=0000000032000-host-integration-round.js.map

package/src/lib/migrations/0000000032000-host-integration-round.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"0000000032000-host-integration-round.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/migrations/0000000032000-host-integration-round.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,iCAAiC;IAA9C;QACE,SAAI,GAAG,mCAAmC,CAAC;IAgF7C,CAAC;IA9EC,KAAK,CAAC,EAAE,CAAC,WAAwB;QAC/B,MAAM,WAAW,CAAC,KAAK,CAAC;;;;KAIvB,CAAC,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,CAAC;;;;KAIvB,CAAC,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,CAAC;;;KAGvB,CAAC,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,CAAC;;;KAGvB,CAAC,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,CAAC;;;KAGvB,CAAC,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,CAAC;;;;KAIvB,CAAC,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;KAoBvB,CAAC,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,CAAC;;;KAGvB,CAAC,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,CAAC;;;KAGvB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,WAAwB;QACjC,MAAM,WAAW,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;QAC3E,MAAM,WAAW,CAAC,KAAK,CAAC;;;;KAIvB,CAAC,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,CAAC;;KAEvB,CAAC,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,CACrB,uDAAuD,CACxD,CAAC;QACF,MAAM,WAAW,CAAC,KAAK,CAAC;;;;KAIvB,CAAC,CAAC;IACL,CAAC;CACF;AAjFD,8EAiFC"}

package/src/lib/migrations/0000000033000-activity-log-advance-failed-index.d.ts

@@ -0,0 +1,35 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+/**
+ * A partial index on the `ADVANCE_FAILED` rows of `activity_logs`, for the
+ * administrator's stuck list (`stuckApprovalInstances` /
+ * `stuckApprovalInstanceCount`). That query starts from the RUNNING and
+ * RETURNED instances and looks up their failures; without this index each
+ * lookup reads every activity row of the instance and drops the ones that are
+ * not failures, so the cost grows with the history of the cases in flight.
+ * With it, only failure rows are read. `seq` is the second column because the
+ * query keeps each instance's highest one.
+ *
+ * Built without `CONCURRENTLY` and without `transaction = false`, so it runs
+ * inside the migration transaction under TypeORM's default transaction mode
+ * (declaring a non-transactional migration fails the whole batch when the mode
+ * is `all`). The cost: the build takes a SHARE lock on `activity_logs`, which
+ * blocks every submit, decision and history write for as long as it runs. It
+ * reads the whole table but writes only the failure rows, which are few.
+ *
+ * A host with a large `activity_logs` table should build the index first,
+ * outside any transaction, with the same name:
+ *
+ *   CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_activity_logs_advance_failed"
+ *     ON "activity_logs" ("instance_id", "seq")
+ *     WHERE "event_type" = 'ADVANCE_FAILED';
+ *
+ * `IF NOT EXISTS` then skips this step. Nothing else depends on how the index
+ * was built.
+ *
+ * No table, column or backfill is involved. `down` drops only the index.
+ */
+export declare class ActivityLogAdvanceFailedIndex0000000033000 implements MigrationInterface {
+    name: string;
+    up(queryRunner: QueryRunner): Promise<void>;
+    down(queryRunner: QueryRunner): Promise<void>;
+}

package/src/lib/migrations/0000000033000-activity-log-advance-failed-index.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActivityLogAdvanceFailedIndex0000000033000 = void 0;
+/**
+ * A partial index on the `ADVANCE_FAILED` rows of `activity_logs`, for the
+ * administrator's stuck list (`stuckApprovalInstances` /
+ * `stuckApprovalInstanceCount`). That query starts from the RUNNING and
+ * RETURNED instances and looks up their failures; without this index each
+ * lookup reads every activity row of the instance and drops the ones that are
+ * not failures, so the cost grows with the history of the cases in flight.
+ * With it, only failure rows are read. `seq` is the second column because the
+ * query keeps each instance's highest one.
+ *
+ * Built without `CONCURRENTLY` and without `transaction = false`, so it runs
+ * inside the migration transaction under TypeORM's default transaction mode
+ * (declaring a non-transactional migration fails the whole batch when the mode
+ * is `all`). The cost: the build takes a SHARE lock on `activity_logs`, which
+ * blocks every submit, decision and history write for as long as it runs. It
+ * reads the whole table but writes only the failure rows, which are few.
+ *
+ * A host with a large `activity_logs` table should build the index first,
+ * outside any transaction, with the same name:
+ *
+ *   CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_activity_logs_advance_failed"
+ *     ON "activity_logs" ("instance_id", "seq")
+ *     WHERE "event_type" = 'ADVANCE_FAILED';
+ *
+ * `IF NOT EXISTS` then skips this step. Nothing else depends on how the index
+ * was built.
+ *
+ * No table, column or backfill is involved. `down` drops only the index.
+ */
+class ActivityLogAdvanceFailedIndex0000000033000 {
+    constructor() {
+        this.name = 'ActivityLogAdvanceFailedIndex0000000033000';
+    }
+    async up(queryRunner) {
+        await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "IDX_activity_logs_advance_failed"
+      ON "activity_logs" ("instance_id", "seq")
+      WHERE "event_type" = 'ADVANCE_FAILED'
+    `);
+    }
+    async down(queryRunner) {
+        await queryRunner.query(`
+      DROP INDEX IF EXISTS "IDX_activity_logs_advance_failed"
+    `);
+    }
+}
+exports.ActivityLogAdvanceFailedIndex0000000033000 = ActivityLogAdvanceFailedIndex0000000033000;
+//# sourceMappingURL=0000000033000-activity-log-advance-failed-index.js.map

package/src/lib/migrations/0000000033000-activity-log-advance-failed-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"0000000033000-activity-log-advance-failed-index.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/migrations/0000000033000-activity-log-advance-failed-index.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAa,0CAA0C;IAAvD;QACE,SAAI,GAAG,4CAA4C,CAAC;IAetD,CAAC;IAbC,KAAK,CAAC,EAAE,CAAC,WAAwB;QAC/B,MAAM,WAAW,CAAC,KAAK,CAAC;;;;KAIvB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,WAAwB;QACjC,MAAM,WAAW,CAAC,KAAK,CAAC;;KAEvB,CAAC,CAAC;IACL,CAAC;CACF;AAhBD,gGAgBC"}

package/src/lib/migrations/index.d.ts

@@ -32,3 +32,5 @@ export * from './0000000028000-notification-updated-at';
 export * from './0000000029000-activity-log-seq';
 export * from './0000000030000-delegation-scope-condition-dialect';
 export * from './0000000031000-approval-instance-form-data-gin';
+export * from './0000000032000-host-integration-round';
+export * from './0000000033000-activity-log-advance-failed-index';