Reminders: durable record + scheduling decisions (Orleans wiring next) by rbuergi · Pull Request #738 · Systemorph/MeshWeaver

rbuergi · 2026-07-31T18:43:48Z

First half of the reminder primitive: the durable record and the pure decisions. Orleans wiring is the next commit — see below.

Why a node, not a timer

A timer dies with the pod; an in-memory queue is pod-local, so with two replicas only one knows the work exists and a restart loses it silently. That is precisely how core's never-registered InMemoryPublishQueue would have lost every scheduled post. A reminder is a node: it survives restarts, is inspectable, and is cancellable like any other content.

One-shot (publish this post at its slot) and recurring (refresh stats 4×/day) are the same record — IntervalSeconds distinguishes them.

The decisions worth pinning

Case	Behaviour	Why
Two replicas, same due reminder	live claim blocks the second; expired claim is reclaimable	a pod dying mid-run must not strand it in `Firing` forever
One-shot fails	stops (`Failed`)	retrying an unattended publish on a loop is how you post six times
Recurring fails	keeps its cadence	a transient 429 must not kill the stats refresh forever
Dormant through many intervals	fires once, resumes on cadence	replaying 8 missed runs bursts the API right after an outage
Run finishes late	next slot still on the grid	adding to `now` would drift the cadence later every firing

11/11 green.

Next: Orleans wiring

grep finds no UseInMemoryReminderService / UseAdoNetReminderService / AddReminders anywhere in src/ or memex/ — the silo configures no reminder service at all. So the next commit must:

Register a reminder table provider on the silo — ADO.NET against the existing Postgres for the real clusters, in-memory for monolith/tests.
Add an IRemindable grain that registers a reminder per node record and calls back on fire.
Launch the Activity on the target node's hub from that callback.

Orleans guarantees a single activation per grain, so its reminders give exactly-once firing on their own. The claim/lease in ReminderSchedule stays as defence for the non-Orleans hosting paths (monolith) and for reclaiming a crashed run — it is not redundant with Orleans, it covers the case where the activity itself dies.

🤖 Generated with Claude Code

…ted) First half of the platform reminder primitive: a Reminder NODE plus the pure functions that decide when it runs. The Orleans wiring lands next — the silo currently configures no reminder service at all. A reminder is a node, not an in-process timer, because a timer dies with the pod and an in-memory queue is pod-local: with two replicas only one knows the work exists and a restart loses it silently. That is exactly how core's never-registered InMemoryPublishQueue would have lost every scheduled post. One-shot (publish this post at its slot) and recurring (refresh stats 4×/day) are the same record; IntervalSeconds distinguishes them. The decisions worth pinning, all covered by tests: - a live claim blocks a second replica; an EXPIRED claim is reclaimable, so a pod that dies mid-run cannot strand a reminder in Firing forever - a failed one-shot STOPS (retrying an unattended publish on a loop is how you post six times) while a failed recurring one keeps its cadence (a transient 429 must not kill the stats refresh forever) - a reminder dormant through many intervals fires ONCE and resumes on cadence rather than replaying every missed slot — replaying would burst the API right after an outage - slots step the interval instead of adding to `now`, so a slow run does not drift the cadence later on every firing 11/11 green. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A9UHhiZ3AamCogfjJBztoC

Copilot

Pull request overview

Introduces the first half of a durable reminder primitive by adding a contract-level Reminder record plus a pure “decision” layer (ReminderSchedule) that determines due-ness, claiming/lease expiry, and rescheduling behavior. This sets up the scheduling semantics to be deterministic and unit-tested before Orleans wiring is added in a follow-up commit.

Changes:

Added Reminder + ReminderState contract types for a durable, inspectable reminder record.
Added ReminderSchedule pure functions for due/claim/lease-expiry and next-occurrence calculations.
Added unit tests pinning the intended behaviors (one-shot vs recurring, claim reclaim, drift-free cadence, dormant catch-up behavior).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
test/MeshWeaver.Data.Test/ReminderScheduleTest.cs	Adds unit tests that pin reminder scheduling/claiming decisions as pure-function behavior.
src/MeshWeaver.Mesh.Contract/ReminderSchedule.cs	Adds the pure scheduling/claiming/rescheduling decision helpers for reminders.
src/MeshWeaver.Mesh.Contract/Reminder.cs	Adds the durable reminder record and lifecycle state enum in the mesh contract.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+/// A durable, mesh-native TIME TRIGGER: at <see cref="DueAt"/> the reminder service launches an
+/// Activity against <see cref="TargetPath"/>. One-shot when <see cref="IntervalSeconds"/> is null
+/// (publish this post at its slot), recurring otherwise (refresh stats four times a day).


+    public static Reminder Recurring(
+        string targetPath, string kind, DateTime firstDueAt, int intervalSeconds, string? argument = null) =>
+        new()
+        {
+            TargetPath = targetPath,
+            Kind = kind,
+            Argument = argument,
+            DueAt = firstDueAt,
+            IntervalSeconds = intervalSeconds,
+            State = ReminderState.Pending,
+        };
+}


github-actions · 2026-07-31T18:59:36Z