scheduled memories: harden due/surface/ack lifecycle for cron-tagged reminders

[keyoku-bot]

Summary

Cron-tagged scheduled memories are implemented in keyoku-engine and are meant to surface through heartbeat, but the engine-side lifecycle for due -> surfaced -> acknowledged -> retired needs to be more explicit and reliable.

This issue is the engine-side half of the reminder split:

• keyoku#28 = integration/runtime ownership (wake, surface, delivery contract)
• this issue = core reminder algorithm/lifecycle in keyoku-engine

Problem

The engine already supports scheduled memories:

• schedules are stored as memories with cron:* tags
• heartbeat evaluates CheckScheduled
• due schedules appear in result.Scheduled
• schedule/ack advances last_accessed_at

However, the lifecycle semantics are still too loose.

The engine should define, clearly and deterministically:

• when a schedule is considered due
• when it remains due vs when it should stop surfacing
• how acknowledgment interacts with re-fire behavior
• what happens if a schedule became due but delivery/handling failed upstream
• how one-shot schedules retire after surfacing/handling
• how repeated due schedules avoid noisy or stale resurfacing loops

Why this matters

Even if integration/runtime wake-up and delivery are fixed, the engine still needs a clean internal model for scheduled reminders.

Otherwise reminders can become:

• repeatedly due without clear retirement
• surfaced too often or not often enough
• hard to reason about when delivery is delayed or missed
• ambiguous in the presence of missed acks or partial handling

Proposed direction

1. Formalize the scheduled-memory lifecycle

A scheduled memory should have a clear state machine, conceptually:

• scheduled
• due
• surfaced
• acknowledged / handled
• waiting for next recurrence
• resolved / archived (for one-shot or cancelled schedules)

2. Tighten due detection semantics

Clarify and test:

• exact due rules for cron:daily, cron:daily:HH:MM, cron:weekly, cron:every:*, cron:once:*
• timezone interactions
• missed windows
• re-fire behavior after a due schedule was not yet acknowledged

3. Make ack semantics explicit

Define whether ack means:

• "the user definitely saw/handled this"
• or "the runtime attempted delivery"

The engine should be strict about what acknowledgment changes:

• next due time
• resurfacing suppression
• retirement for one-shot schedules

4. Prevent stale resurfacing loops

A due schedule should not keep surfacing in a confusing loop when the state has already advanced or when the reminder has effectively been handled.

5. Improve observability / state explanation

The engine should make it easier to inspect why a scheduled memory is currently:

• due
• not due
• resurfacing
• retired
• waiting for next recurrence

Acceptance criteria

• scheduled memories have a clear documented lifecycle
• due detection and next-fire behavior are deterministic and well-tested
• ack behavior is explicit and correctly updates schedule state
• one-shot schedules retire correctly after handling
• recurring schedules reappear only when appropriate for the next interval
• stale resurfacing loops are prevented at the engine layer
• engine responses/debugging make schedule state explainable

Related

• Keyoku-ai/keyoku#28 — integration/runtime side: Keyoku-owned reminder semantics, wake/surface/delivery contract

[keyoku-bot]

Thanks — triaged this as an engine-side enhancement.

The split from Keyoku-ai/keyoku#28 makes sense: runtime/integration can own wake + delivery, while keyoku-engine should own deterministic due/surface/ack/retire semantics for cron-tagged memories. The acceptance criteria here are clear, especially around explicit ack behavior, one-shot retirement, and preventing stale resurfacing loops.

I’ll track this alongside the related reminder/heartbeat lifecycle work so the engine contract stays tight and testable.