0.1.0 batch 4: add Grain Timers

[suraciii]

Goal

Add Activation-local Grain Timers with serialized callback behavior.

Scope

• Add register, change, stop, one-shot, repeat, and keep-alive behavior.
• Deliver callbacks through the Grain mailbox.
• Stop all Grain Timers when the Activation ends.
• Report callback errors and contain callback panics.

Acceptance

• A callback never overlaps a Call or itself.
• Repeat time starts after callback completion.
• Change, Stop, and deactivation control later ticks.
• Fake-clock tests contain no sleeps.
• The conformance Application uses the public API.
• make ci passes.

References

design/release-0.1.0.md
design/timers.md
design/runtime.md

[suraciii]

Batch 4 started

• Worktree: /home/szf/.herdr/worktrees/gor/release-0.1-batch4-grain-timers
• Branch: release-0.1-batch4-grain-timers
• Base: a398744a63fceaed820ec82397aaa56acd639a28
• Inherited make ci: passed
• Scope: Grain Timer API, Activation-owned timer state, serialized mailbox turns, Change, Stop, one-shot, repeat, keep-alive, callback errors, panic containment, conformance use, and deterministic proof.
• Excluded: State hardening, Reminder hardening, generator work, limits, and release proof.

[suraciii]

Batch 4 handoff

Commit: dce07f33607d9c1cb5bded6a0a57fc7fa9c9f003 (Add reliable Grain Timers)

Delivered

• Added RegisterGrainTimer, GrainTimer, GrainTimerOptions, and ErrGrainTimerStopped.
• Added one Activation-local Timer owner for each registered Timer.
• Used the injected Clock for due time and period work.
• Serialized Timer callbacks with Calls in the Grain mailbox.
• Added one-shot, repeat, Change, Stop, and KeepAlive behavior.
• Stopped queued ticks at Stop and Activation end. A running callback can finish.
• Added normal shutdown and sudden shutdown cleanup rules.
• Reported callback errors through OnError. Callback errors continue a repeating Timer. A callback panic or ignored State failure faults the Activation.
• Added a conformance path that proves serialization and old Activation cleanup.
• Updated the release, Runtime, scheduling, Timer, programming model, and roadmap documents.

Review fixes

• Runtime shutdown now waits for every Timer owner before Runtime.Done closes.
• Requested deactivation cannot deadlock a new Call behind an old queued Timer tick.
• A panic in the Timer error handler cannot stop mailbox or Timer cleanup.
• The programming model states the current Reminder error coverage. It does not promise later Reminder scan work.
• Two final independent checks reported FIXED for the concurrency and document findings.

Verification

• make ci: PASS, exit 0, after all review fixes.
• Full go test ./...: PASS.
• Full race gate in make ci: PASS.
• staticcheck ./...: PASS.
• Root Grain Timer tests, Runtime and mailbox Timer tests, and the conformance test: PASS for 100 runs each.
• Focused race tests: PASS.
• The 15 listed source mutations failed at their owning behavior assertions. See research/release-0.1.0-batch-4-mutations.md.
• BenchmarkInvocationRoundTrip, five runs: 1153 to 1215 ns/op, 760 B/op, 14 allocs/op.
• git diff --check: PASS.
• Worktree status after commit: clean.

Branch: release-0.1-batch4-grain-timers

Worktree: /home/szf/.herdr/worktrees/gor/release-0.1-batch4-grain-timers

This batch does not include Batch 5 work. No push or pull request was made.

[suraciii]

Completed in the integrated candidate #116: Activation-local Grain Timers serialize through the mailbox and support change, stop, one-shot, repeat, keep-alive, cleanup, error reporting, and panic containment without sleep-based tests. Exact master 0c41f9f644905183d7d4fd8f7efed24e4396bf0d passed local make ci and hosted run https://github.com/suraciii/gor/actions/runs/31504300130.