Add schedule lifecycle audit history

durable-workflow-ops · durable-workflow-ops · commit a6b0a63826d6 · 2026-04-16T19:02:16.000Z
diff --git a/src/V2/Models/WorkflowSchedule.php b/src/V2/Models/WorkflowSchedule.php
@@ -10,6 +10,7 @@
 use Illuminate\Database\Eloquent\Concerns\HasUlids;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 use Workflow\V2\Enums\ScheduleStatus;
 use Workflow\V2\Support\ConfiguredV2Models;
 
@@ -78,6 +79,14 @@ public function latestInstance(): BelongsTo
         );
     }
 
+    public function historyEvents(): HasMany
+    {
+        return $this->hasMany(
+            ConfiguredV2Models::resolve('schedule_history_event_model', WorkflowScheduleHistoryEvent::class),
+            'workflow_schedule_id',
+        )->orderBy('sequence');
+    }
+
     // ── Convenience accessors projecting spec/action JSON ────────────
 
     public function getWorkflowTypeAttribute(): ?string
diff --git a/src/V2/Models/WorkflowScheduleHistoryEvent.php b/src/V2/Models/WorkflowScheduleHistoryEvent.php
@@ -0,0 +1,124 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Workflow\V2\Models;
+
+use Carbon\CarbonInterface;
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Workflow\V2\Enums\HistoryEventType;
+use Workflow\V2\Support\ConfiguredV2Models;
+
+class WorkflowScheduleHistoryEvent extends Model
+{
+    use HasUlids;
+
+    public $incrementing = false;
+
+    protected $table = 'workflow_schedule_history_events';
+
+    protected $guarded = [];
+
+    protected $keyType = 'string';
+
+    protected $dateFormat = 'Y-m-d H:i:s.u';
+
+    protected $casts = [
+        'event_type' => HistoryEventType::class,
+        'payload' => 'array',
+        'recorded_at' => 'datetime',
+    ];
+
+    public function schedule(): BelongsTo
+    {
+        return $this->belongsTo(
+            ConfiguredV2Models::resolve('schedule_model', WorkflowSchedule::class),
+            'workflow_schedule_id',
+        );
+    }
+
+    /**
+     * @param  array<string, mixed>  $payload
+     */
+    public static function record(
+        WorkflowSchedule $schedule,
+        HistoryEventType $eventType,
+        array $payload = [],
+    ): self {
+        $sequence = ((int) ConfiguredV2Models::query('schedule_history_event_model', self::class)
+            ->where('workflow_schedule_id', $schedule->id)
+            ->max('sequence')) + 1;
+
+        /** @var self $event */
+        $event = ConfiguredV2Models::query('schedule_history_event_model', self::class)->create([
+            'workflow_schedule_id' => $schedule->id,
+            'schedule_id' => $schedule->schedule_id,
+            'namespace' => $schedule->namespace,
+            'sequence' => $sequence,
+            'event_type' => $eventType->value,
+            'payload' => self::snapshotPayload($schedule, $payload),
+            'workflow_instance_id' => self::stringValue($payload['workflow_instance_id'] ?? null),
+            'workflow_run_id' => self::stringValue($payload['workflow_run_id'] ?? null),
+            'recorded_at' => now(),
+        ]);
+
+        return $event;
+    }
+
+    /**
+     * @param  array<string, mixed>  $payload
+     * @return array<string, mixed>
+     */
+    private static function snapshotPayload(WorkflowSchedule $schedule, array $payload): array
+    {
+        if (! array_key_exists('schedule', $payload)) {
+            $payload['schedule'] = self::scheduleSnapshot($schedule);
+        }
+
+        return $payload;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private static function scheduleSnapshot(WorkflowSchedule $schedule): array
+    {
+        return array_filter([
+            'id' => $schedule->id,
+            'schedule_id' => $schedule->schedule_id,
+            'namespace' => $schedule->namespace,
+            'status' => $schedule->status?->value,
+            'overlap_policy' => $schedule->overlap_policy,
+            'next_fire_at' => self::timestamp($schedule->next_fire_at),
+            'last_fired_at' => self::timestamp($schedule->last_fired_at),
+            'paused_at' => self::timestamp($schedule->paused_at),
+            'deleted_at' => self::timestamp($schedule->deleted_at),
+            'last_skip_reason' => $schedule->last_skip_reason,
+            'last_skipped_at' => self::timestamp($schedule->last_skipped_at),
+            'fires_count' => (int) $schedule->fires_count,
+            'skipped_trigger_count' => (int) ($schedule->skipped_trigger_count ?? 0),
+            'latest_workflow_instance_id' => $schedule->latest_workflow_instance_id,
+            'note' => $schedule->note,
+        ], static fn (mixed $value): bool => $value !== null);
+    }
+
+    private static function timestamp(mixed $value): ?string
+    {
+        if ($value instanceof CarbonInterface) {
+            return $value->toIso8601String();
+        }
+
+        if ($value instanceof \DateTimeInterface) {
+            return $value->format(\DateTimeInterface::ATOM);
+        }
+
+        return is_string($value) && $value !== '' ? $value : null;
+    }
+
+    private static function stringValue(mixed $value): ?string
+    {
+        return is_string($value) && $value !== '' ? $value : null;
+    }
+}
diff --git a/src/V2/Support/ScheduleManager.php b/src/V2/Support/ScheduleManager.php
@@ -18,6 +18,7 @@
 use Workflow\V2\Models\WorkflowHistoryEvent;
 use Workflow\V2\Models\WorkflowRun;
 use Workflow\V2\Models\WorkflowSchedule;
+use Workflow\V2\Models\WorkflowScheduleHistoryEvent;
 
 /**
  * Single source of truth for workflow schedule lifecycle.
@@ -137,6 +138,13 @@ public static function createFromSpec(
         $schedule->next_fire_at = $schedule->computeNextFireAtWithJitter();
         $schedule->save();
 
+        self::recordScheduleEvent($schedule, HistoryEventType::ScheduleCreated, [
+            'spec' => is_array($schedule->spec) ? $schedule->spec : [],
+            'action' => is_array($schedule->action) ? $schedule->action : [],
+            'overlap_policy' => $schedule->overlap_policy,
+            'next_fire_at' => $schedule->next_fire_at?->toIso8601String(),
+        ]);
+
         return $schedule;
     }
 
@@ -157,6 +165,11 @@ public static function pause(WorkflowSchedule $schedule, ?string $reason = null)
 
         $schedule->forceFill($updates)->save();
 
+        self::recordScheduleEvent($schedule, HistoryEventType::SchedulePaused, array_filter([
+            'reason' => $reason,
+            'paused_at' => $schedule->paused_at?->toIso8601String(),
+        ], static fn (mixed $value): bool => $value !== null));
+
         return $schedule;
     }
 
@@ -174,6 +187,10 @@ public static function resume(WorkflowSchedule $schedule): WorkflowSchedule
         $schedule->next_fire_at = $schedule->computeNextFireAtWithJitter();
         $schedule->save();
 
+        self::recordScheduleEvent($schedule, HistoryEventType::ScheduleResumed, [
+            'next_fire_at' => $schedule->next_fire_at?->toIso8601String(),
+        ]);
+
         return $schedule;
     }
 
@@ -248,11 +265,21 @@ public static function update(
                 : (int) $schedule->remaining_actions;
         }
 
+        $changedFields = array_values(array_keys($updates));
+
         $schedule->forceFill($updates)->save();
 
         $schedule->next_fire_at = $schedule->computeNextFireAtWithJitter();
         $schedule->save();
 
+        self::recordScheduleEvent($schedule, HistoryEventType::ScheduleUpdated, [
+            'changed_fields' => $changedFields,
+            'spec' => is_array($schedule->spec) ? $schedule->spec : [],
+            'action' => is_array($schedule->action) ? $schedule->action : [],
+            'overlap_policy' => $schedule->overlap_policy,
+            'next_fire_at' => $schedule->next_fire_at?->toIso8601String(),
+        ]);
+
         return $schedule;
     }
 
@@ -268,6 +295,11 @@ public static function delete(WorkflowSchedule $schedule): WorkflowSchedule
             'next_fire_at' => null,
         ])->save();
 
+        self::recordScheduleEvent($schedule, HistoryEventType::ScheduleDeleted, [
+            'reason' => 'deleted',
+            'deleted_at' => $schedule->deleted_at?->toIso8601String(),
+        ]);
+
         return $schedule;
     }
 
@@ -523,14 +555,20 @@ private static function triggerForBackfill(
             $schedule = WorkflowSchedule::query()->lockForUpdate()->findOrFail($schedule->id);
 
             if (! $schedule->status->allowsTrigger()) {
+                self::recordSkip($schedule, 'status_not_triggerable');
+
                 return null;
             }
 
             if ($schedule->remaining_actions !== null && $schedule->remaining_actions <= 0) {
+                self::recordSkip($schedule, 'remaining_actions_exhausted');
+
                 return null;
             }
 
             if (! self::overlapAllowed($schedule, $effectivePolicy)) {
+                self::recordSkip($schedule, 'overlap_policy_' . $effectivePolicy->value);
+
                 return null;
             }
 
@@ -564,6 +602,14 @@ private static function startRun(
         }
 
         self::recordScheduleTriggered($schedule, $result->runId, $occurrenceTime);
+        self::recordScheduleEvent($schedule, HistoryEventType::ScheduleTriggered, array_filter([
+            'workflow_instance_id' => $result->instanceId,
+            'workflow_run_id' => $result->runId,
+            'outcome' => $outcome,
+            'effective_overlap_policy' => $effectiveOverlapPolicy ?? $schedule->overlap_policy,
+            'trigger_number' => (int) $schedule->fires_count + 1,
+            'occurrence_time' => $occurrenceTime?->format('Y-m-d\TH:i:s.uP'),
+        ], static fn (mixed $value): bool => $value !== null));
 
         $schedule->recordFire($result->instanceId, $result->runId, $outcome);
         $schedule->forceFill([
@@ -583,6 +629,10 @@ private static function startRun(
                 'deleted_at' => now(),
                 'next_fire_at' => null,
             ])->save();
+            self::recordScheduleEvent($schedule, HistoryEventType::ScheduleDeleted, [
+                'reason' => 'max_runs_exhausted',
+                'deleted_at' => $schedule->deleted_at?->toIso8601String(),
+            ]);
         }
 
         return $result;
@@ -627,6 +677,23 @@ private static function recordSkip(WorkflowSchedule $schedule, string $reason):
             'last_skipped_at' => now(),
             'skipped_trigger_count' => ($schedule->skipped_trigger_count ?? 0) + 1,
         ])->save();
+
+        self::recordScheduleEvent($schedule, HistoryEventType::ScheduleTriggerSkipped, [
+            'reason' => $reason,
+            'skipped_trigger_count' => (int) $schedule->skipped_trigger_count,
+            'last_skipped_at' => $schedule->last_skipped_at?->toIso8601String(),
+        ]);
+    }
+
+    /**
+     * @param  array<string, mixed>  $payload
+     */
+    private static function recordScheduleEvent(
+        WorkflowSchedule $schedule,
+        HistoryEventType $eventType,
+        array $payload = [],
+    ): void {
+        WorkflowScheduleHistoryEvent::record($schedule, $eventType, $payload);
     }
 
     /**
diff --git a/src/config/workflows.php b/src/config/workflows.php
@@ -36,6 +36,7 @@
         'run_timer_entry_model' => Workflow\V2\Models\WorkflowRunTimerEntry::class,
         'run_lineage_entry_model' => Workflow\V2\Models\WorkflowRunLineageEntry::class,
         'schedule_model' => Workflow\V2\Models\WorkflowSchedule::class,
+        'schedule_history_event_model' => Workflow\V2\Models\WorkflowScheduleHistoryEvent::class,
         'types' => [
             'workflows' => [
                 // 'billing.invoice-sync' => App\Workflows\InvoiceSyncWorkflow::class,
diff --git a/src/migrations/2026_04_16_000180_create_workflow_schedule_history_events_table.php b/src/migrations/2026_04_16_000180_create_workflow_schedule_history_events_table.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class() extends Migration {
+    public function up(): void
+    {
+        Schema::create('workflow_schedule_history_events', static function (Blueprint $table): void {
+            $table->string('id', 26)->primary();
+            $table->string('workflow_schedule_id', 26)->index();
+            $table->string('schedule_id', 255)->index();
+            $table->string('namespace', 255)->nullable()->index();
+            $table->unsignedInteger('sequence');
+            $table->string('event_type');
+            $table->json('payload')->nullable();
+            $table->string('workflow_instance_id', 191)->nullable()->index();
+            $table->string('workflow_run_id', 26)->nullable()->index();
+            $table->timestamp('recorded_at', 6)->nullable();
+            $table->timestamps(6);
+
+            $table->unique(['workflow_schedule_id', 'sequence']);
+            $table->index(['namespace', 'schedule_id']);
+            $table->index(['event_type', 'recorded_at']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('workflow_schedule_history_events');
+    }
+};
diff --git a/tests/Feature/V2/V2ScheduleTest.php b/tests/Feature/V2/V2ScheduleTest.php
