Let a reminder be named for the item it waits on

[cardmagic]

Adds key to schedule, so one actor can hold an alarm per item it is waiting on. This is the Node half of cardmagic/solid_objects#41.

Why

A reminder is one alarm per actor and name, and the name was the operation. An actor waiting on several things could therefore hold only one alarm: arming one per item kept the last and dropped the rest, silently.

// Wrong. Every entry overwrites the previous entry's alarm.
add({ entry }: { entry: Entry }): void {
  this.entries = [...this.entries, entry]
  this.schedule({ at: new Date(entry.waitUntil) }).deliver!()
}

The workaround is to keep entries sorted, arm one alarm for the earliest, drain everything due when it fires, and re-arm. That works, and is still the better choice for a large queue of interchangeable items, but every actor holding scheduled work has to write it. In one application I have three actors doing exactly that, the third copied verbatim from the first.

What changes

add({ entry }: { entry: Entry }): void {
  this.entries = [...this.entries, entry]
  this.schedule({ at: new Date(entry.waitUntil), key: entry.id }).deliver!()
}

Two entries now leave two reminders. Scheduling the same key again moves that item's alarm and leaves the others alone, so a keyed reminder is as safe to re-arm from a handler that may run twice as an unkeyed one.

Schema

The operation column already named the alarm, since the unique key is (instance_id, operation). It keeps that job, and a new nullable message_operation carries what should actually run.

That means the migration adds a column and backfills nothing: on an existing row message_operation is null and the name is still the operation, which is exactly the old behaviour. Dispatch reads message_operation ?? operation in the two places that resolve a reminder to a message.

Schema version 7. Following this repository's convention, the column is added by the migration rather than the base DDL, so a fresh install takes the same path.

Administration

reminders.all() now reports both: name is the alarm, operation is what it runs. Previously operation was the only field and it was the name; for a keyed alarm that would have read as "deliver:item-7" and been misleading about what runs.

Two existing tests rewrote the operation column to simulate a reminder whose message no longer exists. They now rewrite message_operation, which is the column that decides dispatch. The behaviour they cover is unchanged; the column that expresses it moved.

Differences from the Ruby PR

Ruby already had separate name and operation columns, so it needed no migration. Node had one column doing both jobs, so it gains message_operation. The public API is the same shape in both: key on the schedule options, composed into the name as operation:key, with the same 128-character bound.

Testing

244 tests, 0 failures. Typecheck, format, parameter-style and documentation checks all clean.

New coverage: each key gets its own alarm; scheduling one key again moves only that alarm; an unkeyed alarm is still named for its operation; a keyed alarm runs the operation it was scheduled with; and both key bounds are refused.

[greptile-apps]

Greptile Summary

The PR adds independently keyed reminders by separating each alarm’s persisted name from the operation dispatched when it fires.

• Adds keyed reminder-name validation and scheduling behavior.
• Introduces schema migration 7 with nullable message_operation storage.
• Updates dispatch, administration records, documentation, and tests for keyed reminders.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/actor.ts	Adds keyed reminder options, composed-name validation, and separate reminder name and operation intent fields.
src/schema.ts	Adds migration 7 and the nullable message_operation column while preserving legacy reminder dispatch semantics.
src/repository.ts	Persists alarm identity separately from the dispatched operation and resolves the operation when enqueueing due reminders.
src/runtime.ts	Resolves keyed reminders to their handler operation for validation, dispatch, and administration records.
test/runtime.test.ts	Covers keyed alarm independence, replacement, delivery, separators, and invalid key bounds.

_{Reviews (3): Last reviewed commit: "Bound a keyed reminder name by what the ..." | Re-trigger Greptile}

[greptile-apps]

Composed reminder name exceeds storage

When a MySQL-backed actor schedules a reminder whose valid operation and key compose to more than 255 characters, the name exceeds reminders.operation, causing the turn-completion transaction to fail under strict mode or storing a truncated alarm name under permissive settings.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/actor.ts
Line: 233

Comment:
**Composed reminder name exceeds storage**

When a MySQL-backed actor schedules a reminder whose valid operation and key compose to more than 255 characters, the name exceeds `reminders.operation`, causing the turn-completion transaction to fail under strict mode or storing a truncated alarm name under permissive settings.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Reminder comments duplicate the types

These field comments restate the adjacent name and operation semantics, and the same duplication appears on ReminderIntent.name, ReminderOptions.key, and schedule; removing the repeated prose reduces maintenance surface and prevents it from drifting from the API documentation.

Context Used: # De-AI Code Review

In this review, suggest simpl... (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/reminder-administration.ts
Line: 9-12

Comment:
**Reminder comments duplicate the types**

These field comments restate the adjacent `name` and `operation` semantics, and the same duplication appears on `ReminderIntent.name`, `ReminderOptions.key`, and `schedule`; removing the repeated prose reduces maintenance surface and prevents it from drifting from the API documentation.

**Context Used:** # De-AI Code Review

In this review, suggest simpl... ([source](https://app.greptile.com/review/custom-context?memory=instruction-0))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[cardmagic]

Both findings are fixed in 3df6a19.

Composed reminder name exceeds storage (P1)

Correct. The bound was on the key alone, so a long operation with a valid key composed a name past the 255 characters MySQL holds reminders.operation in. I confirmed the width rather than assume it: tableDefinition rewrites TEXT to VARCHAR(255) for MySQL, so the base DDL column really is 255 there.

Under strict mode the turn-completion transaction fails. Under permissive settings the name is truncated, which is worse, because two alarms can then share a name and one silently takes the other's row.

The check moved to the composed name, so a long operation with a short key is caught as well as the reverse. Regression test refuses a composed name longer than the database holds, verified against the previous revision where it fails.

Reminder comments duplicate the types (P2)

Fair. The comments on ReminderIntent.name, ReminderOptions.key, schedule, and the two administration fields restated their own names. What is left is only what the names do not say: that an unkeyed name is the operation. docs/api.md carries the rest.

One thing I checked and did not add

I started to guard against an operation containing the colon that separates a key, which would let an unkeyed deliver:item collide with a deliver keyed item. That guard is dead code here: validateOperationName already restricts actor member names to /^[A-Za-z_][A-Za-z0-9_]*$/, so a colon never reaches it. I removed the guard and its test rather than ship an unreachable branch, and the docs now say a key may hold colons because an operation cannot.

This is the one place the two ports differ. The Ruby side needed the guard, because validate_operation_name! there only rejects reserved names, not characters, so message("deliver:item") is definable and reachable through public_send. That is fixed in cardmagic/solid_objects#41.

245 tests, 0 failures. Typecheck, format, parameter-style and documentation checks all clean.