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, 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
  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.
• The active shard is derived from list_shards().last() (sorted filenames).
• 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

ShardIntegrityIssue

A shard integrity problem found during validation.

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.

Functions

validate_shard_header

Validate that a shard file starts with the expected header line.