Module shard 

Time-sharded event file management.

Events are stored in monthly shard files under .bones/events/YYYY-MM.events. This module manages the directory layout, shard rotation, atomic append operations, the current.events symlink, and replay (reading all shards in chronological order).

Directory Layout

.bones/
  events/
    2026-01.events      # sealed shard
    2026-01.manifest    # manifest for sealed shard
    2026-02.events      # active shard
    current.events -> 2026-02.events   # symlink to active
  cache/
    clock               # monotonic wall-clock file (microseconds)
  lock                  # repo-wide advisory lock

Invariants

• Sealed (frozen) shards are never modified after rotation.
• The active shard is the only one that receives appends.
• current.events always points to the active shard.
• Each append uses O_APPEND + write_all + flush for crash consistency.
• Torn-write recovery truncates incomplete trailing lines on startup.
• Monotonic timestamps: wall_ts_us = max(system_time_us, last + 1).

Structs

ShardManager

Manages time-sharded event files in a .bones repository.

ShardManifest

Manifest for a sealed shard file, recording integrity metadata.

Enums

ShardError

Errors that can occur during shard operations.