feat: read the schedule from an actor

reminder returns one armed alarm as a ScheduledReminder and reminders
lists every key of one operation, matching what the Ruby port already
offers. Both are async, because a TypeScript actor holds no rows and
reads its own through a reader the runtime supplies at hydration. That
is one injection point, so both engines get it: the SQL runtime reads
the reminders table for the instance, and the Durable Objects engine
reads the object's own store.

A read starts from the committed rows and applies the intents staged so
far, so an actor that schedules and then reads sees what the commit will
write, and one that cancels and then reads sees the alarm gone.

key and intervalMilliseconds are null rather than undefined. The first
draft used undefined and a test caught it: returning a ScheduledReminder
straight from an operation failed with InvalidPayload, because undefined
does not serialise. Returning one is the obvious thing to do, so the
type makes it work.

A projection has no reader and throws rather than reporting an armed
alarm as absent, which is the failure this whole feature exists to
prevent.

ScheduledReminder rather than ReminderStatus, because the
administration API already exports that name for the status string.

Author: cardmagic

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- Add reminder reading. `reminder()` returns one armed alarm as a
+  `ScheduledReminder`, and `reminders()` lists every key of one operation. Both
+  apply the intents staged so far in the turn, so a read agrees with what the
+  commit will write. Reading works on the SQL backends and on Durable Objects.
 - Refuse an unknown operation in `unschedule()` and `unscheduleAll()`.
   `schedule()` already threw `UnknownOperation` for one, so a typo cancelled
   nothing quietly and left a recurring reminder running.

docs/api.md

@@ -70,6 +70,9 @@ createdAtMs }` shape returned by `SolidObjectsRuntime.snapshotWithIncarnation`.
   `DestroyOptions`: the options for authorization, idempotency, time, and
   schedule that the reference methods use.
 
+`ScheduledReminder` is one armed reminder as an actor reads it, and
+`ReminderReader` is how a runtime supplies them.
+
 `ActorIntents`, `EffectIntent`, `CommitActionIntent`, `ReminderIntent`,
 `UnscheduleIntent`, `UnscheduleAllIntent`, `ReminderMutation`,
 `OutboundMessageIntent`, `ReminderOptions`, `OutboundMessageOptions`,
@@ -245,6 +248,32 @@ declare, with the `UnknownOperation` that `schedule()` already throws, so a typo
 fails the turn rather than cancelling nothing. A handle skips that check, because
 the `schedule()` call that produced it was already checked.
 
+#### Reading the schedule
+
+`reminder()` returns the armed alarm as a `ScheduledReminder`, or `undefined`.
+`reminders()` returns every key of one operation. Both are async, because an
+actor reads its own rows rather than holding them in memory:
+
+```typescript
+async nextChargeAt(): Promise<number | null> {
+  return (await this.reminder("chargeRenewal"))?.runAtMilliseconds ?? null
+}
+
+async pendingCarriers(): Promise<(string | null)[]> {
+  return (await this.reminders("chaseCarrier")).map((reminder) => reminder.key)
+}
+```
+
+A read applies the intents staged so far in the turn, so an actor that schedules
+and then reads sees what the commit will write, and one that cancels and then
+reads sees the alarm gone.
+
+`key` and `intervalMilliseconds` are `null` rather than `undefined` when absent,
+so a `ScheduledReminder` returns from an operation without a serialization error.
+
+Reading is available during a turn. A projection has no reader and throws, rather
+than reporting an armed alarm as absent.
+
 A cancellation is staged like a schedule, so it commits with the state change
 that decided it and a turn that throws cancels nothing. Both apply in the order
 the turn called them, so cancelling and then scheduling the same name leaves it

docs/correctness.md

@@ -5,6 +5,9 @@
 - Delivery is ordered per actor identity and at least once.
 - Different identities may execute concurrently.
 - Sequence allocation and durable enqueue are one transaction.
+- An actor reads its own schedule. A read applies the intents staged so far in
+  the turn, so it agrees with what the commit will write rather than with what
+  the turn began with.
 - A reminder can be cancelled. A cancellation commits with the state change that
   decided it, and applies in the order the turn called it. A cancellation cannot
   recall an occurrence the scheduler already turned into a message. It does

src/actor.ts

@@ -2,6 +2,7 @@ import { currentMessage, currentRuntime } from "./context.js"
 import { getDefaultRuntime } from "./default-runtime.js"
 import type { StateMigration } from "./definition.js"
 import { InvalidRejectionCode, Rejected, UnknownOperation } from "./errors.js"
+import type { ReminderStatus } from "./reminder-administration.js"
 import { TRANSMIT_EFFECT } from "./transmit-effect.js"
 import { randomUUID } from "./platform/uuid.js"
 import {
@@ -20,6 +21,8 @@ import type {
   EffectHandle,
   JsonObject,
   ReminderHandle,
+  ReminderReader,
+  ScheduledReminder,
   JsonValue,
   MessageContext,
 } from "./types.js"
@@ -179,6 +182,66 @@ function validatedReminderKey(key: string | number | undefined): string | undefi
  * reverse, and it is refused here rather than at the insert, once the turn is
  * already doing work.
  */
+function handleName(handle: ReminderHandle, key: string | number | undefined): string {
+  if (key !== undefined) throw new TypeError("a reminder handle already names its key")
+
+  const name = handle?.name
+  if (typeof name !== "string" || name.length === 0) {
+    throw new TypeError("a reminder handle returned by schedule is required")
+  }
+
+  return name
+}
+
+function reminderKeyOf(name: string, operation: string): string | null {
+  return name === operation ? null : name.slice(operation.length + 1)
+}
+
+function reminderStatusOf(options: {
+  name: string
+  operation: string
+  runAtMilliseconds: number
+  intervalMilliseconds: number | null
+  missedPolicy: "all" | "latest"
+  status: ReminderStatus
+}): ScheduledReminder {
+  return {
+    name: options.name,
+    operation: options.operation,
+    key: reminderKeyOf(options.name, options.operation),
+    runAtMilliseconds: options.runAtMilliseconds,
+    intervalMilliseconds: options.intervalMilliseconds,
+    missedPolicy: options.missedPolicy,
+    status: options.status,
+    handle: { name: options.name },
+  }
+}
+
+function applyReminderIntent(view: Map<string, ScheduledReminder>, intent: ReminderMutation): void {
+  if (intent.cancel === "all") {
+    for (const [name, status] of view) {
+      if (status.operation === intent.operation) view.delete(name)
+    }
+    return
+  }
+  if (intent.cancel === "one") {
+    view.delete(intent.name)
+    return
+  }
+
+  view.set(
+    intent.name,
+    reminderStatusOf({
+      name: intent.name,
+      operation: intent.operation,
+      runAtMilliseconds: intent.atMilliseconds,
+      intervalMilliseconds: intent.intervalMilliseconds ?? null,
+      missedPolicy: intent.missedPolicy,
+      status: "scheduled",
+    }),
+  )
+}
+
 function reminderName(operation: string, key: string | undefined): string {
   if (key === undefined) return operation
 
@@ -211,6 +274,8 @@ export abstract class Actor {
   }
 
   readonly #actorId: string
+  #readReminders: ReminderReader | undefined
+
   readonly #intents: ActorIntents = {
     effects: [],
     commitActions: [],
@@ -363,25 +428,50 @@ export abstract class Actor {
   }
 
   unschedule(operationOrHandle: string | ReminderHandle, options: { key?: string | number } = {}) {
+    this.#intents.reminders.push({
+      cancel: "one",
+      name: this.#reminderNameOf(operationOrHandle, options),
+    })
+  }
+
+  unscheduleAll(operation: string) {
+    this.#assertOperation(operation)
+    this.#intents.reminders.push({ cancel: "all", operation })
+  }
+
+  async reminder(
+    operationOrHandle: string | ReminderHandle,
+    options: { key?: string | number } = {},
+  ): Promise<ScheduledReminder | undefined> {
+    return (await this.#reminderView()).get(this.#reminderNameOf(operationOrHandle, options))
+  }
+
+  async reminders(operation: string): Promise<ScheduledReminder[]> {
+    this.#assertOperation(operation)
+    const view = await this.#reminderView()
+    return [...view.values()].filter((status) => status.operation === operation)
+  }
+
+  #reminderNameOf(
+    operationOrHandle: string | ReminderHandle,
+    options: { key?: string | number },
+  ): string {
     if (typeof operationOrHandle === "string") {
       this.#assertOperation(operationOrHandle)
-      const key = validatedReminderKey(options.key)
-      this.#intents.reminders.push({ cancel: "one", name: reminderName(operationOrHandle, key) })
-      return
-    }
-    if (options.key !== undefined) throw new TypeError("a reminder handle already names its key")
-
-    const name = operationOrHandle?.name
-    if (typeof name !== "string" || name.length === 0) {
-      throw new TypeError("unschedule requires a reminder handle returned by schedule")
+      return reminderName(operationOrHandle, validatedReminderKey(options.key))
     }
 
-    this.#intents.reminders.push({ cancel: "one", name })
+    return handleName(operationOrHandle, options.key)
   }
 
-  unscheduleAll(operation: string) {
-    this.#assertOperation(operation)
-    this.#intents.reminders.push({ cancel: "all", operation })
+  async #reminderView(): Promise<Map<string, ScheduledReminder>> {
+    if (!this.#readReminders) {
+      throw new TypeError("reading reminders is not available outside an actor turn")
+    }
+    const view = new Map<string, ScheduledReminder>()
+    for (const status of await this.#readReminders()) view.set(status.name, status)
+    for (const intent of this.#intents.reminders) applyReminderIntent(view, intent)
+    return view
   }
 
   #assertOperation(operation: string): void {
@@ -413,8 +503,9 @@ export abstract class Actor {
   }
 
   /** @internal */
-  prepare(operations: ReadonlySet<string>): void {
+  prepare(operations: ReadonlySet<string>, readReminders?: ReminderReader): void {
     this.#operations = operations
+    this.#readReminders = readReminders
   }
 
   /** @internal */

src/cloudflare/engine.ts

@@ -34,6 +34,7 @@ import type {
   JsonObject,
   JsonValue,
   SerializedError,
+  ScheduledReminder,
 } from "../types.js"
 import type { CloudflareSettings } from "./configuration.js"
 import { actorName, callHost, type ActorIdentity, type HostRequest } from "./protocol.js"
@@ -357,6 +358,21 @@ export class ActorEngine {
     return { definition, instance, state }
   }
 
+  private readReminders = async (): Promise<ScheduledReminder[]> =>
+    this.store.rows<Reminder>("SELECT record FROM reminders ORDER BY name").map((reminder) => ({
+      name: reminder.name,
+      operation: reminder.operation,
+      key:
+        reminder.name === reminder.operation
+          ? null
+          : reminder.name.slice(reminder.operation.length + 1),
+      runAtMilliseconds: reminder.at,
+      intervalMilliseconds: reminder.interval,
+      missedPolicy: reminder.missed,
+      status: reminder.status,
+      handle: { name: reminder.name },
+    }))
+
   private async snapshot(identity: ActorIdentity): Promise<JsonObject> {
     const { definition, instance, state } = this.committed(identity)
     const actor = hydrateActor({ definition, actorId: identity.actorId, state })
@@ -387,7 +403,11 @@ export class ActorEngine {
   }): Promise<JsonObject> {
     const { input, payloadNames } = options
     const { definition, instance, state } = this.committed(input)
-    const actor = hydrateActor({ definition, actorId: input.actorId, state })
+    const actor = hydrateActor({
+      definition,
+      actorId: input.actorId,
+      state,
+    })
     const identity = {
       actorType: input.actorType,
       actorId: input.actorId,
@@ -486,6 +506,7 @@ export class ActorEngine {
                 storedVersion: instance.stateVersion,
                 storedState: instance.state,
               }),
+              readReminders: this.readReminders,
             })
       if (this.cached?.actor !== actor) {
         await withActorContext({ actor, runtime: this.runtime }, () => actor.activate())

src/definition.ts

@@ -2,6 +2,7 @@ import { Actor, type ActorClass } from "./actor.js"
 import { withApplicationWritesForbidden } from "./context.js"
 import { ApplicationWriteForbidden, InvalidActor, StateMigrationError } from "./errors.js"
 import { deepCopy, jsonObject, normalizeJson } from "./serialization.js"
+import type { ReminderReader } from "./types.js"
 import type { JsonObject } from "./types.js"
 
 export type PayloadBroadcastHandler = (
@@ -146,10 +147,11 @@ export function hydrateActor<ActorType extends Actor>(options: {
   definition: ValidatedActorDefinition<ActorType>
   actorId: string
   state: JsonObject
+  readReminders?: ReminderReader
 }): ActorType {
   const { definition, actorId, state } = options
   const actor = new definition.actorClass(actorId)
-  actor.prepare(new Set(definition.operations))
+  actor.prepare(new Set(definition.operations), options.readReminders)
   const target = actor as unknown as Record<string, unknown>
   for (const key of definition.stateKeys) target[key] = deepCopy(state[key])
   return actor

src/index.ts

@@ -132,6 +132,8 @@ export type {
   EffectFailurePayload,
   EffectHandle,
   ReminderHandle,
+  ReminderReader,
+  ScheduledReminder,
   EffectSuccessPayload,
   InvocationOptions,
   JsonObject,

src/repository.ts

@@ -1169,6 +1169,15 @@ export class Repository {
     })
   }
 
+  async remindersForInstance(instanceId: string): Promise<ReminderRow[]> {
+    return this.settings.database.connection((connection) =>
+      connection.all<ReminderRow>(
+        `SELECT * FROM ${this.table("reminders")} WHERE instance_id = ? ORDER BY operation`,
+        [instanceId],
+      ),
+    )
+  }
+
   async findInstanceByIdentity(
     actorType: string,
     actorId: string,

src/runtime.ts

@@ -117,6 +117,7 @@ import type {
   MessageContext,
   MessageStatus,
   SnapshotOptions,
+  ScheduledReminder,
 } from "./types.js"
 import { SolidObjectsTestHelper } from "./test-helper.js"
 import { waitFor, Worker } from "./worker.js"
@@ -165,6 +166,21 @@ type CommitActionHandler = (
   context: CommitActionContext,
 ) => unknown | Promise<unknown>
 
+function scheduledReminderOf(row: ReminderRow): ScheduledReminder {
+  const operation = row.message_operation ?? row.operation
+  const name = row.operation
+  return {
+    name,
+    operation,
+    key: name === operation ? null : name.slice(operation.length + 1),
+    runAtMilliseconds: Number(row.run_at_ms),
+    intervalMilliseconds: row.interval_ms === null ? null : Number(row.interval_ms),
+    missedPolicy: row.missed_policy,
+    status: row.status,
+    handle: { name },
+  }
+}
+
 export class SolidObjectsRuntime {
   readonly settings
   readonly repository
@@ -1117,6 +1133,8 @@ export class SolidObjectsRuntime {
           definition,
           actorId: turn.message.actor_id,
           state: deepCopy(state),
+          readReminders: async () =>
+            (await this.repository.remindersForInstance(turn.instance.id)).map(scheduledReminderOf),
         })
     } catch (error) {
       throw new ActorSetupFailed(error)

src/types.ts

@@ -1,3 +1,5 @@
+import type { ReminderStatus } from "./reminder-administration.js"
+
 export type JsonPrimitive = null | boolean | number | string
 export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue }
 export type JsonObject = { [key: string]: JsonValue }
@@ -6,6 +8,19 @@ export type EffectHandle = { readonly id: string }
 
 export type ReminderHandle = { readonly name: string }
 
+export interface ScheduledReminder {
+  readonly name: string
+  readonly operation: string
+  readonly key: string | null
+  readonly runAtMilliseconds: number
+  readonly intervalMilliseconds: number | null
+  readonly missedPolicy: "all" | "latest"
+  readonly status: ReminderStatus
+  readonly handle: ReminderHandle
+}
+
+export type ReminderReader = () => Promise<readonly ScheduledReminder[]>
+
 export type SerializedError = {
   name: string
   message: string