@memberjunction/scheduling-engine 6.1.0-edge.1 → 6.1.0-edge.3

package/dist/drivers/ActionLogRetentionScheduledJobDriver.js

@@ -0,0 +1,224 @@
+/**
+ * @fileoverview Driver for the bounded action-execution-log purge.
+ * @module @memberjunction/scheduling-engine
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { RegisterClass } from '@memberjunction/global';
+import { BaseScheduledJob } from '../BaseScheduledJob.js';
+import { LogError, Metadata, RunView, ValidationErrorInfo, ValidationErrorType, ValidationResult, } from '@memberjunction/core';
+/** How many rows one run will delete before stopping, when the job does not say. */
+export const DEFAULT_MAX_DELETES_PER_RUN = 5000;
+/**
+ * Turns the distinct retention values present into the buckets a purge query needs.
+ *
+ * Bucketing rather than per-row date math is what keeps this a small number of indexable range
+ * queries instead of a scan: retention is stamped from the action, so the distinct set is roughly
+ * "one per configured action", not one per log row. Pure and exported so the arithmetic is testable
+ * without a clock or a database.
+ *
+ * @param now the reference instant, passed in rather than read, so a test can pin it.
+ */
+export function BuildRetentionBuckets(retentionDays, now) {
+    const distinct = [...new Set(retentionDays.filter((d) => Number.isFinite(d) && d > 0))].sort((a, b) => a - b);
+    return distinct.map((RetentionDays) => ({
+        RetentionDays,
+        Cutoff: new Date(now.getTime() - RetentionDays * 24 * 60 * 60 * 1000),
+    }));
+}
+/**
+ * Purges expired `MJ: Action Execution Logs` rows, bounded per run.
+ *
+ * **Retention is decided at write time, not here.** `StartActionLog` stamps each row's
+ * `RetentionPeriod` from its action's, so this job reads only the row's own value — which is what
+ * makes an edit to `Action.RetentionPeriod` a going-forward change rather than a retroactive
+ * deletion of history written under the previous policy. A row with NULL retention is kept forever
+ * unless the job is explicitly configured with `DefaultRetentionDays`.
+ *
+ * **Deletion goes through `BaseEntity.Delete()`, one row at a time.** A `DELETE` statement would be
+ * faster and is a sanctioned use of raw DML in principle — but only for an entity that has opted in
+ * via `AllowDirectSQLDelete`, and this one has not. Honouring the platform's own gate matters more
+ * here than throughput, because the job is bounded anyway: the cap exists so a first run against a
+ * long-neglected table cannot become an unbounded transaction, and raising it is a configuration
+ * change rather than a code change.
+ *
+ * Opt-in like every other maintenance driver: shipping the job type activates nothing until someone
+ * creates a `MJ: Scheduled Job` of this type with a cron expression.
+ */
+let ActionLogRetentionScheduledJobDriver = class ActionLogRetentionScheduledJobDriver extends BaseScheduledJob {
+    async Execute(context) {
+        const config = this.readConfiguration(context.Schedule);
+        const maxDeletes = config.MaxDeletesPerRun ?? DEFAULT_MAX_DELETES_PER_RUN;
+        try {
+            const expired = await this.findExpiredLogs(config, maxDeletes, context.ContextUser);
+            const { Deleted, Failed } = await this.deleteBounded(expired);
+            return {
+                Success: true,
+                Details: {
+                    Deleted,
+                    Failed,
+                    Examined: expired.length,
+                    // Says plainly that the run stopped at its ceiling rather than because it was
+                    // finished — otherwise "Deleted: 5000" reads as "all clean" when it is not.
+                    ReachedCap: expired.length >= maxDeletes,
+                },
+            };
+        }
+        catch (e) {
+            return { Success: false, ErrorMessage: `Action-log purge failed: ${e instanceof Error ? e.message : String(e)}` };
+        }
+    }
+    /**
+     * The expired rows, oldest first, capped at `maxDeletes`.
+     *
+     * Oldest-first is not cosmetic: a capped run that took an arbitrary slice would leave the same
+     * ancient rows behind every night while deleting newer ones, so the backlog would never drain.
+     */
+    async findExpiredLogs(config, maxDeletes, user) {
+        const filter = await this.buildExpiredFilter(config, user);
+        if (!filter) {
+            return [];
+        }
+        // A scheduled maintenance sweep is a server-global task, so the global default provider is
+        // the correct source here (not a per-request/per-tenant provider).
+        const rv = RunView.FromMetadataProvider(Metadata.Provider); // global-provider-ok: scheduled maintenance sweep is a server-global task, not per-request/per-tenant
+        const result = await rv.RunView({
+            EntityName: 'MJ: Action Execution Logs',
+            ExtraFilter: filter,
+            OrderBy: 'StartedAt ASC',
+            MaxRows: maxDeletes,
+            ResultType: 'entity_object',
+        }, user);
+        if (!result.Success) {
+            throw new Error(result.ErrorMessage ?? 'could not read the action execution log');
+        }
+        return result.Results ?? [];
+    }
+    /**
+     * The WHERE clause selecting expired rows, or null when nothing can expire.
+     *
+     * Returning null rather than a clause that matches nothing is deliberate — it lets the caller
+     * skip the query entirely on an instance where no action has ever configured retention, which is
+     * the common case and should cost nothing nightly.
+     */
+    async buildExpiredFilter(config, user) {
+        const now = new Date();
+        const clauses = [];
+        const buckets = BuildRetentionBuckets(await this.distinctRetentionDays(user), now);
+        for (const bucket of buckets) {
+            clauses.push(`(RetentionPeriod = ${bucket.RetentionDays} AND StartedAt < '${bucket.Cutoff.toISOString()}')`);
+        }
+        const fallback = config.DefaultRetentionDays;
+        if (fallback != null && Number.isFinite(fallback) && fallback > 0) {
+            const cutoff = new Date(now.getTime() - fallback * 24 * 60 * 60 * 1000);
+            clauses.push(`(RetentionPeriod IS NULL AND StartedAt < '${cutoff.toISOString()}')`);
+        }
+        return clauses.length > 0 ? clauses.join(' OR ') : null;
+    }
+    /**
+     * The retention lifetimes actually in use, read from the actions that stamped them.
+     *
+     * Read from `MJ: Actions` rather than by scanning the log for distinct values, because the log
+     * is the large table and the actions table is not — and the two agree by construction, since the
+     * stamp comes from here.
+     */
+    async distinctRetentionDays(user) {
+        const rv = RunView.FromMetadataProvider(Metadata.Provider); // global-provider-ok: scheduled maintenance sweep is a server-global task, not per-request/per-tenant
+        const result = await rv.RunView({
+            EntityName: 'MJ: Actions',
+            ExtraFilter: 'RetentionPeriod IS NOT NULL',
+            Fields: ['RetentionPeriod'],
+            ResultType: 'simple',
+        }, user);
+        if (!result.Success) {
+            throw new Error(result.ErrorMessage ?? 'could not read action retention settings');
+        }
+        return (result.Results ?? []).map((r) => Number(r.RetentionPeriod)).filter((d) => Number.isFinite(d));
+    }
+    /**
+     * Deletes the given rows, counting rather than aborting on a failure.
+     *
+     * One bad row — a FK an extension added, a permission gap — must not strand the rest of the
+     * purge behind it every night. The count is reported so the failure is visible.
+     */
+    async deleteBounded(rows) {
+        let Deleted = 0;
+        let Failed = 0;
+        for (const row of rows) {
+            if (await row.Delete()) {
+                Deleted++;
+            }
+            else {
+                Failed++;
+                LogError(`ActionLogRetention: could not delete action execution log ${row.ID}: ` +
+                    `${row.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+        }
+        return { Deleted, Failed };
+    }
+    ValidateConfiguration(schedule) {
+        const result = new ValidationResult();
+        const config = this.readConfiguration(schedule);
+        for (const [field, value] of [
+            ['DefaultRetentionDays', config.DefaultRetentionDays],
+            ['MaxDeletesPerRun', config.MaxDeletesPerRun],
+        ]) {
+            if (value != null && (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)) {
+                result.Errors.push(new ValidationErrorInfo(`Configuration.${field}`, `${field} must be a positive number when provided`, value, ValidationErrorType.Failure));
+            }
+        }
+        result.Success = result.Errors.length === 0;
+        return result;
+    }
+    FormatNotification(context, result) {
+        const deleted = result.Details?.['Deleted'] ?? 0;
+        const failed = result.Details?.['Failed'] ?? 0;
+        const reachedCap = result.Details?.['ReachedCap'] ?? false;
+        if (!result.Success) {
+            return {
+                Subject: `Action-log purge failed: ${context.Schedule.Name}`,
+                Body: `The scheduled action-log purge "${context.Schedule.Name}" failed.\n\nError: ${result.ErrorMessage ?? 'unknown'}`,
+                Priority: 'High',
+                Metadata: { Deleted: deleted, Failed: failed },
+            };
+        }
+        const capNote = reachedCap
+            ? '\n\nThe run stopped at its per-run ceiling, so expired rows remain — it will continue on the next run.'
+            : '';
+        return {
+            Subject: `Action-log purge: ${deleted} expired row(s) removed`,
+            Body: `The scheduled action-log purge "${context.Schedule.Name}" removed ${deleted} expired log row(s)`
+                + `${failed > 0 ? `, and could not remove ${failed}` : ''}.${capNote}`,
+            Priority: failed > 0 ? 'High' : deleted > 0 ? 'Normal' : 'Low',
+            Metadata: { Deleted: deleted, Failed: failed, ReachedCap: reachedCap },
+        };
+    }
+    /**
+     * Tolerant parse — the purge needs no configuration, so empty/missing JSON yields defaults.
+     *
+     * Named apart from the base's `parseConfiguration`, which throws on an empty Configuration
+     * because most job types genuinely require one. This job's every setting is optional, and a job
+     * that refused to run because nobody filled in a box would be a retention policy that quietly
+     * never applies.
+     */
+    readConfiguration(schedule) {
+        if (!schedule.Configuration) {
+            return {};
+        }
+        try {
+            return JSON.parse(schedule.Configuration);
+        }
+        catch {
+            return {};
+        }
+    }
+};
+ActionLogRetentionScheduledJobDriver = __decorate([
+    RegisterClass(BaseScheduledJob, 'ActionLogRetentionScheduledJobDriver')
+], ActionLogRetentionScheduledJobDriver);
+export { ActionLogRetentionScheduledJobDriver };
+//# sourceMappingURL=ActionLogRetentionScheduledJobDriver.js.map

package/dist/drivers/ActionLogRetentionScheduledJobDriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionLogRetentionScheduledJobDriver.js","sourceRoot":"","sources":["../../src/drivers/ActionLogRetentionScheduledJobDriver.ts"],"names":[],"mappings":"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"}

package/dist/drivers/AgentScheduledJobDriver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentScheduledJobDriver.d.ts","sourceRoot":"","sources":["../../src/drivers/AgentScheduledJobDriver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,gBAAgB,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,EAAE,gBAAgB,EAAmF,MAAM,sBAAsB,CAAC;AAGzI,OAAO,EACH,kBAAkB,EAClB,mBAAmB,EAEtB,MAAM,uCAAuC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBACa,uBAAwB,SAAQ,gBAAgB;IAC5C,OAAO,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAmDjF,qBAAqB,CAAC,QAAQ,EAAE,GAAG,GAAG,gBAAgB;IA4CtD,kBAAkB,CACrB,OAAO,EAAE,4BAA4B,EACrC,MAAM,EAAE,kBAAkB,GAC3B,mBAAmB;YA8BR,SAAS;CAW1B"}
+{"version":3,"file":"AgentScheduledJobDriver.d.ts","sourceRoot":"","sources":["../../src/drivers/AgentScheduledJobDriver.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,gBAAgB,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,EAAE,gBAAgB,EAAmF,MAAM,sBAAsB,CAAC;AAGzI,OAAO,EACH,kBAAkB,EAClB,mBAAmB,EAEtB,MAAM,uCAAuC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBACa,uBAAwB,SAAQ,gBAAgB;IAC5C,OAAO,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAqEjF,qBAAqB,CAAC,QAAQ,EAAE,GAAG,GAAG,gBAAgB;IA4CtD,kBAAkB,CACrB,OAAO,EAAE,4BAA4B,EACrC,MAAM,EAAE,kBAAkB,GAC3B,mBAAmB;YA8BR,SAAS;CAW1B"}

package/dist/drivers/AgentScheduledJobDriver.js

@@ -39,6 +39,22 @@ let AgentScheduledJobDriver = class AgentScheduledJobDriver extends BaseSchedule
         const config = this.parseConfiguration(context.Schedule);
         // Load the agent entity
         const agent = await this.loadAgent(config.AgentID, context.ContextUser);
+        // A workflow SUBMITS and detaches — it returns a handle as soon as its steps are scheduled,
+        // not a result. A scheduled job that ran one would record success the moment the graph was
+        // written, before any of the work happened: the job history would show a clean run every
+        // time regardless of whether the workflow later succeeded, failed or stalled. That is worse
+        // than not running it, because it looks like it worked.
+        //
+        // Refused here rather than at submission because this is where the caller's expectation
+        // lives: the job expects a completed unit of work, and nothing downstream of this point can
+        // supply one until an await path exists.
+        if ((agent.Type ?? '').trim().toLowerCase() === 'flow') {
+            const message = `'${agent.Name}' is a workflow and cannot be run on a schedule yet. A workflow returns ` +
+                `as soon as its steps are scheduled, so this job would report success before any of the ` +
+                `work had happened. Schedule the steps individually, or start the workflow by hand.`;
+            this.log(message);
+            return { Success: false, ErrorMessage: message, Details: { AgentID: config.AgentID } };
+        }
         // Verbose-only: the engine's always-on "▶️ Starting / ✅ Completed" pair already frames this
         // run. This per-agent detail is redundant noise on routine (often no-op) scheduled runs.
         this.log(`Executing agent: ${agent.Name}`, true);

package/dist/drivers/AgentScheduledJobDriver.js.map

@@ -1 +1 @@
-{"version":3,"file":"AgentScheduledJobDriver.js","sourceRoot":"","sources":["../../src/drivers/AgentScheduledJobDriver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AgentScheduledJobDriver.js","sourceRoot":"","sources":["../../src/drivers/AgentScheduledJobDriver.ts"],"names":[],"mappings":"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"}

package/dist/drivers/MaterializationRefreshScheduledJobDriver.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Scheduled-job driver that refreshes due materialized results on a cron schedule —
+ * sibling to RecordProcessScheduledJobDriver / ActionScheduledJobDriver. Delegates the actual
+ * rebuild to the @memberjunction/materialization engine.
+ * @module @memberjunction/scheduling-engine
+ */
+import { ValidationResult } from '@memberjunction/core';
+import { BaseScheduledJob, ScheduledJobExecutionContext } from '../BaseScheduledJob.js';
+import { ScheduledJobResult, NotificationContent } from '@memberjunction/scheduling-base-types';
+/**
+ * Driver for the materialization refresh sweep (materialization plan §11.1).
+ *
+ * Unlike most drivers, this one has **no per-job configuration** — it processes the entire due queue:
+ * every non-disabled, scheduled `MJ: Materialized Results` row whose `NextRefreshAt` is at/before now
+ * (or null). Each is refreshed via the engine (full rebuild + atomic wrapper-view swap) and its
+ * `NextRefreshAt` is advanced from its own `RefreshSchedule` cron. Per-materialization cadence lives
+ * on the rows; this job just needs to run often enough to honor the smallest cadence.
+ */
+export declare class MaterializationRefreshScheduledJobDriver extends BaseScheduledJob {
+    Execute(context: ScheduledJobExecutionContext): Promise<ScheduledJobResult>;
+    /** No per-job configuration — the driver always sweeps the whole due queue. */
+    ValidateConfiguration(): ValidationResult;
+    FormatNotification(_context: ScheduledJobExecutionContext, result: ScheduledJobResult): NotificationContent;
+}
+//# sourceMappingURL=MaterializationRefreshScheduledJobDriver.d.ts.map

package/dist/drivers/MaterializationRefreshScheduledJobDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaterializationRefreshScheduledJobDriver.d.ts","sourceRoot":"","sources":["../../src/drivers/MaterializationRefreshScheduledJobDriver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,gBAAgB,EAAwC,MAAM,sBAAsB,CAAC;AAG9F,OAAO,EAAE,gBAAgB,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAGhG;;;;;;;;GAQG;AACH,qBACa,wCAAyC,SAAQ,gBAAgB;IAC7D,OAAO,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAmExF,+EAA+E;IACxE,qBAAqB,IAAI,gBAAgB;IAIzC,kBAAkB,CAAC,QAAQ,EAAE,4BAA4B,EAAE,MAAM,EAAE,kBAAkB,GAAG,mBAAmB;CAQrH"}

package/dist/drivers/MaterializationRefreshScheduledJobDriver.js

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview Scheduled-job driver that refreshes due materialized results on a cron schedule —
+ * sibling to RecordProcessScheduledJobDriver / ActionScheduledJobDriver. Delegates the actual
+ * rebuild to the @memberjunction/materialization engine.
+ * @module @memberjunction/scheduling-engine
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { RegisterClass } from '@memberjunction/global';
+import { ValidationResult, RunView, Metadata } from '@memberjunction/core';
+import { MaterializationRefresher } from '@memberjunction/materialization';
+import { BaseScheduledJob } from '../BaseScheduledJob.js';
+import { CronExpressionHelper } from '../CronExpressionHelper.js';
+/**
+ * Driver for the materialization refresh sweep (materialization plan §11.1).
+ *
+ * Unlike most drivers, this one has **no per-job configuration** — it processes the entire due queue:
+ * every non-disabled, scheduled `MJ: Materialized Results` row whose `NextRefreshAt` is at/before now
+ * (or null). Each is refreshed via the engine (full rebuild + atomic wrapper-view swap) and its
+ * `NextRefreshAt` is advanced from its own `RefreshSchedule` cron. Per-materialization cadence lives
+ * on the rows; this job just needs to run often enough to honor the smallest cadence.
+ */
+let MaterializationRefreshScheduledJobDriver = class MaterializationRefreshScheduledJobDriver extends BaseScheduledJob {
+    async Execute(context) {
+        const provider = Metadata.Provider; // global-provider-ok: scheduled job runs in the server's single default-provider context
+        // Candidate queue: scheduled materializations that are neither disabled nor held for drift
+        // review (§13/§17.2 — DriftHold rows stop refreshing until a human resolves the drift).
+        // Due-selection is done in JS (engine.filterDue) so the date comparison stays engine-agnostic.
+        const rv = new RunView();
+        const candidates = await rv.RunView({
+            EntityName: 'MJ: Materialized Results',
+            ExtraFilter: `Status NOT IN ('Disabled', 'DriftHold') AND RefreshSchedule IS NOT NULL`,
+            ResultType: 'entity_object',
+        }, context.ContextUser);
+        // RunView returns Success:false (never throws) on failure. Without this check a failed candidate
+        // load yields an empty due set and the sweep reports GREEN while silently refreshing nothing —
+        // masking a total refresh outage. Surface it as a job failure instead.
+        if (!candidates.Success) {
+            return {
+                Success: false,
+                ErrorMessage: `Failed to load due materializations: ${candidates.ErrorMessage ?? 'unknown error'}`,
+                Details: { DueCount: 0, Refreshed: 0, Failed: 0, Items: [] },
+            };
+        }
+        const now = new Date();
+        const due = MaterializationRefresher.filterDue(candidates.Results ?? [], now);
+        const refresher = new MaterializationRefresher();
+        let refreshed = 0;
+        let failed = 0;
+        const items = [];
+        for (const mr of due) {
+            void context.heartbeat?.();
+            // Advance NextRefreshAt from this row's own cron (UTC). Candidates are pre-filtered to
+            // RefreshSchedule IS NOT NULL, so a throw here means a MALFORMED cron. In that case we must
+            // NOT refresh: RefreshOne would set NextRefreshAt=null, which filterDue treats as due, so the
+            // expensive full-rebuild-with-swap would run on EVERY sweep forever. Instead surface it as a
+            // failed item and skip — the row stays selected but untouched until the cron is corrected.
+            let nextRefreshAt;
+            try {
+                nextRefreshAt = CronExpressionHelper.GetNextRunTime(mr.RefreshSchedule, 'UTC', now);
+            }
+            catch {
+                failed++;
+                items.push({ ID: mr.ID, TableName: mr.TableName, Success: false, Error: `Invalid RefreshSchedule cron "${mr.RefreshSchedule}" — skipped (not refreshed) until corrected.` });
+                continue;
+            }
+            const result = await refresher.RefreshOne(mr, context.ContextUser, provider, { nextRefreshAt });
+            if (result.Success) {
+                refreshed++;
+            }
+            else {
+                failed++;
+            }
+            items.push({ ID: mr.ID, TableName: mr.TableName, Success: result.Success, RowCount: result.RowCount, Error: result.ErrorMessage });
+        }
+        return {
+            Success: failed === 0,
+            ErrorMessage: failed > 0 ? `${failed} materialization(s) failed to refresh` : undefined,
+            Details: { DueCount: due.length, Refreshed: refreshed, Failed: failed, Items: items },
+        };
+    }
+    /** No per-job configuration — the driver always sweeps the whole due queue. */
+    ValidateConfiguration() {
+        return new ValidationResult();
+    }
+    FormatNotification(_context, result) {
+        const d = result.Details ?? {};
+        return {
+            Subject: `Materialization refresh — ${result.Success ? 'OK' : 'errors'}`,
+            Body: `Refreshed ${d.Refreshed ?? 0} of ${d.DueCount ?? 0} due materialization(s)${(d.Failed ?? 0) > 0 ? `; ${d.Failed} failed` : ''}.`,
+            Priority: result.Success ? 'Normal' : 'High',
+        };
+    }
+};
+MaterializationRefreshScheduledJobDriver = __decorate([
+    RegisterClass(BaseScheduledJob, 'MaterializationRefreshScheduledJobDriver')
+], MaterializationRefreshScheduledJobDriver);
+export { MaterializationRefreshScheduledJobDriver };
+//# sourceMappingURL=MaterializationRefreshScheduledJobDriver.js.map

package/dist/drivers/MaterializationRefreshScheduledJobDriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaterializationRefreshScheduledJobDriver.js","sourceRoot":"","sources":["../../src/drivers/MaterializationRefreshScheduledJobDriver.ts"],"names":[],"mappings":"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"}

package/dist/drivers/UserRoutineDispatcherDriver.d.ts

@@ -64,8 +64,18 @@ export declare class UserRoutineDispatcherDriver extends BaseScheduledJob {
      * Execute one claimed routine end-to-end: run row → target execution → run/routine
      * bookkeeping → notification decision + delivery. Never throws for target failures —
      * those are recorded on the run row; only run-row creation failures propagate.
+     *
+     * **Once the run row exists, this drives it to a TERMINAL status on every path.** The inner
+     * guard around `executeTarget` only ever covered target failures, so a throw from the
+     * bookkeeping that follows it — `finalizeRunRow`, `updateRoutineAfterRun`, notification
+     * delivery — escaped to the sweep's per-routine catch, which records `Failed` in its in-memory
+     * summary and returns. The row on disk stays `Running` forever: nothing reconciles it, the
+     * sweep reports success, and the routine looks like it is still executing long after the
+     * process that owned it exited. A run row that outlives its executor has to say so.
      */
     private executeRoutine;
+    /** The body of {@link executeRoutine}, from target execution through notification delivery. */
+    private runAndRecord;
     /** Create the `MJ: User Routine Runs` row in its initial Running state. */
     private createRunRow;
     /** Persist the run's terminal state + linkage. Telemetry stays on the linked records. */

package/dist/drivers/UserRoutineDispatcherDriver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UserRoutineDispatcherDriver.d.ts","sourceRoot":"","sources":["../../src/drivers/UserRoutineDispatcherDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAkD,QAAQ,EAA4C,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC5J,OAAO,EAGH,oBAAoB,EACpB,mBAAmB,EAKtB,MAAM,+BAA+B,CAAC;AAQvC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAC;AAC3H,OAAO,EAAE,gBAAgB,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAYrF;;;GAGG;AACH,MAAM,WAAW,kCAAmC,SAAQ,yBAAyB;IACjF,0EAA0E;IAC1E,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAClC;AAmCD;;;;;;;;GAQG;AACH,qBACa,2BAA4B,SAAQ,gBAAgB;IAC7D;;;OAGG;IACH,IAAoB,uBAAuB,IAAI,OAAO,CAErD;IAEY,OAAO,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAmDjF,qBAAqB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,gBAAgB;IAgBvE,kBAAkB,CAAC,OAAO,EAAE,4BAA4B,EAAE,MAAM,EAAE,kBAAkB,GAAG,mBAAmB;IAwBjH,6GAA6G;IAC7G,OAAO,CAAC,4BAA4B;IAOpC;;;OAGG;YACW,qBAAqB;IAcnC,oFAAoF;YACtE,aAAa;IAc3B;;;;;;;;OAQG;YACW,YAAY;IAmB1B;;;;OAIG;YACW,cAAc;IA6C5B,2EAA2E;YAC7D,YAAY;IAkB1B,yFAAyF;YAC3E,cAAc;IAoB5B,6FAA6F;YAC/E,qBAAqB;IAUnC,0FAA0F;IAC1F,OAAO,CAAC,kBAAkB;IAW1B;;;OAGG;YACW,aAAa;IAkB3B;;;;;;;;;;OAUG;YACW,kBAAkB;IAsChC;;;;;;;;;;;;;OAaG;IACU,yBAAyB,CAAC,OAAO,EAAE,mBAAmB,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA2C7G,6HAA6H;YAC/G,uBAAuB;IAUrC,6GAA6G;IAC7G,OAAO,CAAC,sBAAsB;IAY9B,2FAA2F;YAC7E,mBAAmB;IAyBjC,iGAAiG;YACnF,mBAAmB;IA6BjC,8FAA8F;IAC9F,OAAO,CAAC,iBAAiB;IAgBzB;;;;;;;;;OASG;YACW,wBAAwB;IAsDtC,2FAA2F;YAC7E,cAAc;IAe5B;;;;OAIG;YACW,yBAAyB;IAqCvC,sGAAsG;IACtG,OAAO,CAAC,2BAA2B;IAWnC,wEAAwE;IACxE,OAAO,CAAC,qBAAqB;IAS7B;;;;;;;;OAQG;YACW,YAAY;IA6B1B,uFAAuF;YACzE,eAAe;IA4B7B;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;CAa7B"}
+{"version":3,"file":"UserRoutineDispatcherDriver.d.ts","sourceRoot":"","sources":["../../src/drivers/UserRoutineDispatcherDriver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAkD,QAAQ,EAA4C,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC5J,OAAO,EAGH,oBAAoB,EACpB,mBAAmB,EAKtB,MAAM,+BAA+B,CAAC;AAQvC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAC;AAC3H,OAAO,EAAE,gBAAgB,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAYrF;;;GAGG;AACH,MAAM,WAAW,kCAAmC,SAAQ,yBAAyB;IACjF,0EAA0E;IAC1E,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAClC;AAyED;;;;;;;;GAQG;AACH,qBACa,2BAA4B,SAAQ,gBAAgB;IAC7D;;;OAGG;IACH,IAAoB,uBAAuB,IAAI,OAAO,CAErD;IAEY,OAAO,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAmDjF,qBAAqB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,gBAAgB;IAgBvE,kBAAkB,CAAC,OAAO,EAAE,4BAA4B,EAAE,MAAM,EAAE,kBAAkB,GAAG,mBAAmB;IAwBjH,6GAA6G;IAC7G,OAAO,CAAC,4BAA4B;IAOpC;;;OAGG;YACW,qBAAqB;IAcnC,oFAAoF;YACtE,aAAa;IAc3B;;;;;;;;OAQG;YACW,YAAY;IAmB1B;;;;;;;;;;;;OAYG;YACW,cAAc;IAiD5B,+FAA+F;YACjF,YAAY;IA4C1B,2EAA2E;YAC7D,YAAY;IAkB1B,yFAAyF;YAC3E,cAAc;IA0E5B,6FAA6F;YAC/E,qBAAqB;IAUnC,0FAA0F;IAC1F,OAAO,CAAC,kBAAkB;IAW1B;;;OAGG;YACW,aAAa;IAkB3B;;;;;;;;;;OAUG;YACW,kBAAkB;IAsChC;;;;;;;;;;;;;OAaG;IACU,yBAAyB,CAAC,OAAO,EAAE,mBAAmB,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA2C7G,6HAA6H;YAC/G,uBAAuB;IAUrC,6GAA6G;IAC7G,OAAO,CAAC,sBAAsB;IAY9B,2FAA2F;YAC7E,mBAAmB;IAyBjC,iGAAiG;YACnF,mBAAmB;IA6BjC,8FAA8F;IAC9F,OAAO,CAAC,iBAAiB;IAgBzB;;;;;;;;;OASG;YACW,wBAAwB;IAsDtC,2FAA2F;YAC7E,cAAc;IAe5B;;;;OAIG;YACW,yBAAyB;IAqCvC,sGAAsG;IACtG,OAAO,CAAC,2BAA2B;IAWnC,wEAAwE;IACxE,OAAO,CAAC,qBAAqB;IAS7B;;;;;;;;OAQG;YACW,YAAY;IA6B1B,uFAAuF;YACzE,eAAe;IA4B7B;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;CAa7B"}

package/dist/drivers/UserRoutineDispatcherDriver.js

@@ -28,8 +28,44 @@ import { TemplateEngineServer } from '@memberjunction/templates';
 import { NotificationEngine } from '@memberjunction/notifications';
 import { BaseScheduledJob } from '../BaseScheduledJob.js';
 import { ComputeRoutineNextRunAt, ComputeResultHash, EvaluateNotifyCondition, IsRoutineDue, RoutineNeedsSeeding, BuildDueRoutineFilter, SortRecipientsBySequence, RunWithBoundedConcurrency, } from '../UserRoutineProcessor.js';
+/**
+ * Attempts to re-attach a run's execution linkage after the first save was rejected.
+ *
+ * The linkage columns are foreign keys to rows written fire-and-forget by the action/agent/prompt
+ * engines, so a rejection usually means "not inserted yet" rather than "does not exist". A few
+ * short, escalating waits cover that window without putting the sweep on the DB's critical path.
+ */
+const RUN_LINKAGE_ATTEMPTS = 3;
+const RUN_LINKAGE_RETRY_MS = 50;
 /** Default bound on concurrent routine executions within a single dispatcher sweep. */
 const DEFAULT_MAX_CONCURRENT_ROUTINES = 3;
+/**
+ * The run's status **as last persisted** — never the in-memory value.
+ *
+ * `BaseEntity.finalizeSave` runs only when the save returned a row, and it calls
+ * `SetMany(data, …, replaceOldValues = true)`. So `OldValue` holds the value on disk: it advances
+ * to 'Success'/'Failed' when the write lands, and stays 'Running' when it does not.
+ *
+ * The distinction is the whole point. `finalizeRunRow` assigns `Status = 'Success'` BEFORE its
+ * first save, so after a rejected save the in-memory `Status` says 'Success' while the row still
+ * says 'Running'. A caller that reads `run.Status` to decide "was an outcome already committed?"
+ * gets 'Success' and leaves the row stuck at 'Running' forever — the exact defect this module's
+ * tests were written to eliminate, reintroduced at the seam between the two layers that each fix
+ * one half of it.
+ *
+ * Falls back to the in-memory value only when the field cannot be resolved, which cannot happen
+ * for a real `MJUserRoutineRunEntity` (`Status` is a column); it keeps this total rather than
+ * throwing inside an error handler.
+ */
+function persistedRunStatus(run) {
+    const persisted = run.GetFieldByName?.('Status')?.OldValue;
+    // `OldValue` is untyped on EntityField, so this is the one narrowing boundary. The column is
+    // CHECK-constrained to the same value list as the property, so a string read from it IS that
+    // union — asserting anything wider here would just push the cast to every caller.
+    return typeof persisted === 'string'
+        ? persisted
+        : run.Status;
+}
 /** Name of the metadata-seeded default notification template (resolved BY NAME, never hardcoded ID). */
 const DEFAULT_NOTIFICATION_TEMPLATE_NAME = 'User Routine Notification - Default';
 /** Name of the metadata-seeded `MJ: User Notification Types` row used for in-app delivery. */
@@ -201,11 +237,57 @@ let UserRoutineDispatcherDriver = class UserRoutineDispatcherDriver extends Base
      * Execute one claimed routine end-to-end: run row → target execution → run/routine
      * bookkeeping → notification decision + delivery. Never throws for target failures —
      * those are recorded on the run row; only run-row creation failures propagate.
+     *
+     * **Once the run row exists, this drives it to a TERMINAL status on every path.** The inner
+     * guard around `executeTarget` only ever covered target failures, so a throw from the
+     * bookkeeping that follows it — `finalizeRunRow`, `updateRoutineAfterRun`, notification
+     * delivery — escaped to the sweep's per-routine catch, which records `Failed` in its in-memory
+     * summary and returns. The row on disk stays `Running` forever: nothing reconciles it, the
+     * sweep reports success, and the routine looks like it is still executing long after the
+     * process that owned it exited. A run row that outlives its executor has to say so.
      */
     async executeRoutine(routine, context) {
         const contextUser = context.ContextUser;
         const run = await this.createRunRow(routine, contextUser);
         this.log(`Running routine "${routine.Name}" (${routine.TargetType} target)`, true);
+        try {
+            return await this.runAndRecord(routine, run, context);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.logError(`Routine "${routine.Name}" (${routine.ID}) failed after its run row was created`, error);
+            // ONLY drive a row that is still non-terminal. Everything after `finalizeRunRow` runs
+            // inside this scope — `updateRoutineAfterRun`, the notification save — so a throw from
+            // there arrives with `Status` already committed as `Success` alongside its
+            // ResultSummary and ResultHash, and `MJUserRoutine.LastRunStatus` possibly already
+            // agreeing. Overwriting it with `Failed` would rewrite a run that genuinely succeeded
+            // and put the run and its routine into disagreement — inventing the very status/disk
+            // mismatch this catch was added to eliminate.
+            //
+            // ASK THE ROW, NOT THE OBJECT. This must read the PERSISTED status, because the other
+            // way into this catch is `finalizeRunRow` itself throwing — and it throws having
+            // already set `Status = 'Success'` in memory on an object whose saves all failed.
+            // Reading `run.Status` there would report a committed success for a row that is still
+            // 'Running' on disk, which is precisely the bug the throw exists to signal.
+            const committed = persistedRunStatus(run);
+            if (committed !== 'Running') {
+                this.logError(`Run ${run.ID} already recorded '${committed}'; leaving it as-is. The failure above ` +
+                    `happened in the bookkeeping AFTER the outcome was committed.`);
+                return { RoutineID: routine.ID, RunStatus: committed, Notified: false };
+            }
+            run.Status = 'Failed';
+            run.ErrorMessage = `Run bookkeeping failed: ${message}`;
+            run.CompletedAt = new Date();
+            if (!(await run.Save())) {
+                this.logError(`Run ${run.ID} is STUCK at Running — the failure could not be recorded: ` +
+                    `${run.LatestResult?.CompleteMessage ?? 'unknown'}`);
+            }
+            return { RoutineID: routine.ID, RunStatus: 'Failed', Notified: false };
+        }
+    }
+    /** The body of {@link executeRoutine}, from target execution through notification delivery. */
+    async runAndRecord(routine, run, context) {
+        const contextUser = context.ContextUser;
         let outcome;
         try {
             outcome = await this.executeTarget(routine, contextUser, context.heartbeat);
@@ -263,10 +345,56 @@ let UserRoutineDispatcherDriver = class UserRoutineDispatcherDriver extends Base
         run.AgentRunID = outcome.AgentRunID;
         run.PromptRunID = outcome.PromptRunID;
         run.ActionExecutionLogID = outcome.ActionExecutionLogID;
-        const saved = await run.Save();
-        if (!saved) {
-            this.logError(`Failed to finalize run ${run.ID}: ${run.LatestResult?.CompleteMessage ?? 'unknown'}`);
-        }
+        if (await run.Save()) {
+            return;
+        }
+        // The run's own status must not be hostage to an OPTIONAL linkage. The three ID columns
+        // above are foreign keys to artifacts of the execution — the action log, the agent run, the
+        // prompt run — and any of them can fail to resolve (a log row cleaned up by an unrelated
+        // process, a cross-session write not yet visible). When that FK is what rejected the save,
+        // the previous behaviour logged and carried on: `Status` stayed 'Success' IN MEMORY, the
+        // caller reported success from that in-memory value, and the row on disk stayed 'Running'
+        // forever with nothing to reconcile it. Losing a link is a diagnostic loss; losing the
+        // status is a correctness one — so drop the links and record the outcome.
+        const firstFailure = run.LatestResult?.CompleteMessage ?? 'unknown';
+        // The usual cause is a RACE, not a bad ID. Action-execution logging is fire-and-forget:
+        // `ActionEngine` client-generates the log row's PK and returns it immediately, then INSERTs
+        // it off the critical path. So `outcome.ActionExecutionLogID` is a valid identifier for a
+        // row that may not exist YET — and writing it into a foreign key can lose that race, which
+        // is why this only shows up under load. Land the STATUS first (the correctness-bearing
+        // part), then re-attach the linkage once the INSERT has had a chance to land.
+        const linkage = {
+            AgentRunID: run.AgentRunID,
+            PromptRunID: run.PromptRunID,
+            ActionExecutionLogID: run.ActionExecutionLogID,
+        };
+        run.AgentRunID = null;
+        run.PromptRunID = null;
+        run.ActionExecutionLogID = null;
+        if (!(await run.Save())) {
+            throw new Error(`Run ${run.ID} could not be finalized and is stuck at 'Running': ${run.LatestResult?.CompleteMessage ?? firstFailure}`);
+        }
+        for (let attempt = 1; attempt <= RUN_LINKAGE_ATTEMPTS; attempt++) {
+            await new Promise((resolve) => setTimeout(resolve, RUN_LINKAGE_RETRY_MS * attempt));
+            run.AgentRunID = linkage.AgentRunID;
+            run.PromptRunID = linkage.PromptRunID;
+            run.ActionExecutionLogID = linkage.ActionExecutionLogID;
+            if (await run.Save()) {
+                return;
+            }
+            // Re-null so the next attempt starts from the persisted (unlinked) state rather than
+            // stacking a second rejected write on top of a dirty entity.
+            run.AgentRunID = null;
+            run.PromptRunID = null;
+            run.ActionExecutionLogID = null;
+        }
+        // Status is recorded; only the diagnostic linkage is missing. Say so and move on — losing a
+        // link is an observability loss, and blocking the sweep on it would be the worse trade.
+        run.ErrorMessage = [outcome.ErrorMessage, `execution linkage not attached: ${firstFailure}`]
+            .filter(Boolean).join(' | ');
+        const noted = await run.Save();
+        this.logError(`Run ${run.ID} finalized WITHOUT execution linkage after ${RUN_LINKAGE_ATTEMPTS} attempt(s): ${firstFailure}` +
+            (noted ? '' : ` — and the note could not be written: ${run.LatestResult?.CompleteMessage ?? 'unknown'}`));
     }
     /** Roll the run outcome up onto the routine (LastRunAt / LastRunStatus / LastResultHash). */
     async updateRoutineAfterRun(routine, run) {