S18.04: Example flash block device

[DavidCozens]

Parent epic: #112 (E18: Flash Storage Support)

Scope (placeholder)

Example SolidSyslogBlockDevice implementation suitable for flash-class storage. Specific shape and acceptance to be refined closer to implementation.

Two candidate shapes under consideration:

• A driver targeting a real flash partition supplied by an integrator-specific flash interface.
• A generic example fake managing a defined block list with injected read / write / erase functions, suitable as a starting template for integrator-supplied flash backends.

The example will live under Example/ (out of Core/) — examples are not part of the supported library surface.

Acceptance criteria

To be defined when this story is refined for implementation.

Out of scope

• Real flash hardware drivers for specific MCU families — supplied by the platform.

Design considerations (preliminary)

To refine when this story is picked up — captured here so they survive between sessions.

• Erase on Dispose, not on Acquire. Spreading the erase cost over the producer's drain cadence (Dispose) instead of bunching it on the writer's hot path (Acquire) is the preferred performance model. Dispose-on-empty (S18.03) makes this natural — the block is already idle when erase happens. Acquire then becomes "verify-and-use" rather than "erase-and-use".
• Startup verification of all blocks. When SolidSyslogFileStore_Create walks the flash partition, each block should be classified as one of:
  • Valid block with messages — keep, rejoin the sequence.
  • Erased block ready to use — keep, available for future Acquire.
  • Neither (corrupt / partial / unknown state) — erase before use.
    This subsumes the S18.03 "Acquire disposes stale content" recovery into a startup pass that examines every block once, rather than per-Acquire.
• Failure handling on Acquire / Dispose. Today's BlockSequence (per S18.02) advances writeSequence / oldestSequence even if Acquire / Dispose returns false. Benign for the file-backed driver (POSIX O_CREAT heals lazily on next Append) but a real bug for flash where Acquire = erase: writing into an unerased block corrupts data. The right semantics — propagate failure, retry, or call an integrator error reporter — need to be decided once a real flash driver exists. Worth co-designing with this story.

References

• Parent epic E18 E18: Flash Storage Support #112 — BlockDevice abstraction this story implements.
• Predecessor stories S18.02 (BlockDevice), S18.03 (Acquire / Dispose lifecycle).