refactor: checkpoint API cleanup

[greysonlalonde]

Summary

• Rename CheckpointConfig.directory to location — the field means a directory for JsonProvider and a database file path for SqliteProvider, so the generic name fits both
• Add prune method to BaseProvider protocol so each provider owns its own cleanup logic
• Move pruning out of checkpoint_listener into the providers where it belongs
• max_checkpoints stays on CheckpointConfig as the single place users configure it; the listener passes it through to provider.prune after each write

Test plan

• Existing checkpoint tests pass
• JsonProvider prunes files when max_checkpoints is set
• SqliteProvider prunes rows when max_checkpoints is set
• CheckpointConfig(location=..., max_checkpoints=5) works for both providers

---

Note

Medium Risk
Medium risk because it renames a public CheckpointConfig field and changes pruning responsibilities, which could break existing integrations or custom providers if not updated.

Overview
Checkpointing API cleanup. Renames CheckpointConfig.directory to location across code and docs to reflect that the value may be either a filesystem directory (JsonProvider) or a SQLite DB file path (SqliteProvider).

Provider-owned retention. Adds prune(location, max_keep) to the BaseProvider protocol and removes file-pruning logic from checkpoint_listener, delegating retention to JsonProvider.prune (delete old JSON files) and SqliteProvider.prune (delete old rows), with tests updated accordingly.

^{Reviewed by Cursor Bugbot for commit c61a40e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[iris-clawd]

Review: Checkpoint API Cleanup

Clean refactor — directory → location is the right abstraction, and moving prune logic into providers is good separation of concerns.

🟡 Prune is now a separate transaction (SqliteProvider)

Previously, _PRUNE ran inside the same sqlite3.connect() context as the insert (same transaction). Now prune() opens a new connection. Two implications:

1. If the process crashes between checkpoint() and prune(), you accumulate an extra row. Minor — alpha-level acceptable.
2. More importantly: two separate connections means two separate transactions. Under concurrent writes (e.g., multiple crews checkpointing to the same DB), there's a window where a prune could race with an insert from another thread. WAL mode helps, but the old atomic approach was safer.

If this matters, prune could accept an optional connection/cursor to reuse the write transaction. Not blocking for alpha.

🟡 No aprune on BaseProvider

BaseProvider defines both checkpoint and acheckpoint, but prune is sync-only. The listener always calls it synchronously via _do_checkpoint, so it works today. But if someone calls acheckpoint → prune in an async context, they'll block the event loop on SQLite I/O. Worth adding aprune to the protocol for symmetry, even if the default impl just calls prune.

🟢 Looks good

• Breaking changes are fine for alpha (CheckpointConfig.directory → location, SqliteProvider.__init__ dropping max_checkpoints)
• JsonProvider prune logic is a clean lift from the old _prune function
• SqliteProvider prune reuses the existing _PRUNE SQL correctly
• Docstrings updated consistently across all files

Minor stuff, nothing blocking. 💬 163

[iris-clawd]

Approving — already reviewed. Notes on separate prune transaction and missing aprune are suggestions for later. Good to land. ✅

[iris-clawd]

Re-approving after new commits. ✅