Repository navigation
Flight recorder 2/5: write-behind capture (events survive process death) #50
Description
Activity
- added 14 commits that reference this issue
on Aug 22, 2026 29 remaining items
- added 13 commits that reference this issue
on Aug 31, 2026 Delivered by #56 (merged 2026-09-01,
31201e3).All acceptance criteria are covered by merged tests:
Criterion Test Events beyond ring capacity still reach the DB Given an onRecord seam When the buffer evicts an event Then the evicted event was still forwardedFlusher batches rather than one write per event Given many events When flushed Then they are written in batches not one per eventrecord()hot path unchanged when persistence is offWhen persistence is off Then record keeps its behavior and onRecord stays nullExisting SharinganStoreTestgreen +checkApiParitygreenverified on the merged branch Shipped beyond the original scope, following the pre-merge review:
- Bodies are not written to disk — slice 5's default (Flight recorder 5/5: disk security (bodies off by default, clear-on-new-session) #53), pulled forward rather than shipping the opposite default in the interim. Flight recorder 5/5: disk security (bodies off by default, clear-on-new-session) #53 has been rescoped accordingly.
Sharingan.clear()now purges disk rows via anonClearseam. The clear travels as a command on the write channel, so a pending batch cannot resurrect cleared events.Persistence.stop()— the seam had no teardown; it now unwires and closes, and the seams are wired before the flusher starts rather than after.:sharingan-dbis BCV- and ktlint-guarded. The module was published to Maven Central while excluded fromapiValidation, so its ABI shipped unwatched; it was also outside the ktlint gate. Both exemptions are removed. The gate immediately caught thePersistenceController.clear()widening this PR introduced.- Docs corrected — nine stale "memory-only / never persisted" claims across
README,ARCHITECTURE,CONTEXT,AGENTSandllms.txt;CONTEXT.mdgained Flight Recorder / Write-Behind Seam / Run.
Known gap:
Persistence.start/stophave no unit test.start()builds a real driver andDriverFactory.create()on Android needs the ContentProvider-installedContext, which a JVM unit test cannot supply — covering it would need Robolectric or a controller-injection seam. Documented in the type's KDoc.
Part of the flight-recorder persistence epic — design:
docs/superpowers/specs/2026-08-21-flight-recorder-persistence-design.md, discussion #27. Sequenced after #49.Deliverable
After this slice: events captured during a run are written to disk and survive process death — the core flight-recorder value.
Scope
internal var onRecord: ((SharinganEvent) -> Unit)?seam toSharinganStore.record(), invoked after the CAS append (only while recording). Internal → not part of the public API → no noop mirror, parity untouched. The lock-free CAS append is unchanged.PersistenceController: owns aCoroutineScope(SupervisorJob() + Dispatchers.Default), setsonRecord = { channel.trySend(it) }(bounded Channel, non-blocking O(1)).transaction {}.EventDto@Serializablesealed type (Http/Mqtt/Ble) withfromEvent()— encode only is needed this slice; decode lands in slice 3. Public event ABI (Freeze event-type ABI: make HttpEvent/MqttEvent/BleEvent constructors internal #15) untouched — DTO is a separate mirror.TDD / acceptance
record()hot path unchanged when persistence is off (onRecord == null).SharinganStoreTeststill green;checkApiParitygreen (no public change).