perf(durable-iterator): improve resume events cleanup logic (#1102)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* Performance
* Cleanup of expired events is now throttled to reduce overhead and
improve responsiveness under load.
  * An initial cleanup still runs at startup when retention is enabled.

* Behavior
* Expired events may remain briefly accessible before being removed due
to deferred cleanup.

* Documentation
* Retention settings updated to note that cleanup is deferred and some
expired events can be temporarily available.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: dinwwwh

packages/durable-iterator/src/durable-object/resume-storage.ts

@@ -13,6 +13,9 @@ export interface EventResumeStorageOptions extends StandardRPCJsonSerializerOpti
    *
    * @remarks
    * - Use infinite values to disable
+   * - Note that for performance, expired event cleanup is deferred. This means
+   *  expired events may remain in storage for a short period beyond their
+   *  retention time.
    *
    * @default NaN (disabled)
    */
@@ -197,7 +200,16 @@ export class EventResumeStorage<T extends object> {
     this.initSchema()
   }
 
+  private lastCleanupTime: number | undefined
   private cleanupExpiredEvents(): void {
+    const now = Date.now()
+    // defer cleanup to improve performance
+    if (this.lastCleanupTime && this.lastCleanupTime + this.retentionSeconds * 1000 > now) {
+      return
+    }
+
+    this.lastCleanupTime = now
+
     this.durableState.storage.sql.exec(`
       DELETE FROM "${this.schemaPrefix}events" WHERE stored_at < unixepoch() - ?
     `, this.retentionSeconds)