Flight recorder 4/5: retention + Sharingan.configure() (public knob)

[mibrahimdev]

Part of the flight-recorder persistence epic — design: docs/superpowers/specs/2026-08-21-flight-recorder-persistence-design.md, discussion #27. Sequenced after #51.

Deliverable

After this slice: old sessions auto-purge and the consumer can tune how many are kept. The one public method of the whole epic lands here.

Scope

• Public Sharingan.configure(persistence: Boolean = true, maxSessions: Int = 50, persistBodies: Boolean = false). persistBodies is wired but its effect ships in slice 5.
• maxSessions clamped to a runtime device/storage-derived ceiling.
• On new-session creation, purge oldest sessions beyond the limit (cascade-delete events). This is what the closed Expose Sharingan.configure(capacity) for store capacity (HITL — public API decision) #18 capacity knob was deferred to become.
• Noop obligation: mirror configure() as an empty no-op in sharingan-noop, run ./gradlew apiDump, commit all four .api/.klib.api dumps, confirm checkApiParity green (per docs/api-parity.md).

TDD / acceptance

• RED→GREEN: creating session N+1 with maxSessions=N purges the oldest and its events (retention math).
• maxSessions above the device ceiling is clamped, not honored verbatim.
• checkApiParity green with the new public method mirrored in noop.
• Intentionally diverging the noop (drop configure) is shown to fail the parity check.

[mibrahimdev]

Carry-forward items for this slice (from #49/#50 dual reviews):

1. FK enforcement. ON DELETE CASCADE is in the schema but inert — SQLite disables FK by default and neither driver issues PRAGMA foreign_keys=ON. Since retention does cascade-deletes, enable FK enforcement in both DriverFactory actuals (Android: setForeignKeyConstraintsEnabled/pragma; iOS: pragma via DatabaseConfiguration) and add a cascade test.
2. iOS auto-start. Persistence bootstrap is Android-only after Flight recorder 2/5: write-behind capture (events survive process death) #50 (started from the manifest ContentProvider). iOS has no zero-setup hook yet — add the iOS persistence auto-start here alongside configure() so crash-survival is cross-platform.

[mibrahimdev]

Carried over from PR #56 review (deferred, not blocking slice 2)

From the two-reviewer (Vigil + Sage) audit of the write-behind slice — these were explicitly deferred here rather than fixed in #56:

• Poison-event batch blast radius (Sage C3). PersistenceController.flush() maps the whole snapshot via toRow inside one try; a single throwing/constraint-failing event drops its entire batch (up to 50 events in prod). The coverage test uses batchSize = 1, which hides the geometry. Slice 4 should either map per-event (skip only the failure) or move to INSERT OR IGNORE, and test at the default batch size. Slice 3 would otherwise render those gaps as unexplained missing history.

• Single-use controller contract (Sage C1/C2 follow-through). PersistenceController is now explicitly single-use: terminal stopped flag, start()-after-stop() throws IllegalStateException. Slice-4 Sharingan.configure() must therefore:

  1. configure(persistence = false) → null store.onRecord itself, then controller.close() (the controller does NOT detach the seam — that WARNING stands).
  2. Re-enabling → construct a fresh PersistenceController + driver; never reuse a stopped instance.
  3. Reusing a stopped instance is now a loud crash, not a silent dead recorder — cover it in a slice-4 test.

• Coroutines-bump tripwires (Sage C4 + test note). Two independent things in :sharingan-db break on a kotlinx.coroutines version bump: select/onTimeout are ExperimentalCoroutinesApi and load-bearing in this published module. Re-validate :sharingan-db whenever coroutines is upgraded.

(Findings 6–9 from the first review — INSERT OR IGNORE, Dispatchers.IO for blocking SQLite, close() idempotency/double-close, println logging — also remain open for a later slice.)