Struct SharedSnapshot 

pub struct SharedSnapshot {
    pub sequence: AtomicU64,
    pub magic: u32,
    pub version: u32,
    pub hot_cycle: AtomicU64,
    pub hot_surprise_bits: AtomicU32,
    pub hot_curiosity_bits: AtomicU32,
    pub hot_predicted_hash: AtomicU64,
    /* private fields */
}

96-byte snapshot of the consciousness stream. All fields are pre-computed by the writer; readers do no derivation. #[repr(C)] keeps the seqlock header and data block layout stable (relevant if a future file-mmap layer is ever built). The data fields live inside UnsafeCell so the writer can mutate them through &self (required for the seqlock protocol). The seqlock guarantees readers never see a torn write.

Fields

sequence: AtomicU64

Seqlock counter. Even = stable, odd = write in progress.

magic: u32

SNAPSHOT_MAGIC. Lets readers detect a fresh/uninitialized snapshot.

version: u32

SNAPSHOT_VERSION. Bumped on layout change.

hot_cycle: AtomicU64

Lock-free cycle counter. Readers can check freshness without seqlock.

hot_surprise_bits: AtomicU32

Lock-free surprise level (f32 stored as u32 bits).

hot_curiosity_bits: AtomicU32

Lock-free curiosity level (f32 stored as u32 bits).

hot_predicted_hash: AtomicU64

Lock-free predicted query hash.

Implementations

impl SharedSnapshot

pub fn new_zeroed() -> Self

Build a zeroed snapshot, ready to be written.

pub fn begin_write(&self) -> u64

Begin a write. Increments sequence to an odd value, returns the value the writer must restore after the write to mark completion. Caller MUST call end_write with the returned value, even on panic.

pub fn end_write(&self, expected: u64)

End a write. Stores an even sequence value, signaling readers that the data is consistent.

pub unsafe fn data_mut(&self) -> &mut SnapshotData

Get an exclusive &mut reference to the data block. The seqlock protocol guarantees no reader can be accessing the data while this is held (the sequence is odd, so readers retry).

Safety

Caller must hold the seqlock by having called begin_write and not yet called end_write. Only one writer at a time.

pub fn read_cached_format(&self) -> String

Read the pre-formatted consciousness string. O(1) clone, no format!(). This is the fastest path for the MCP tool: ~50-100ns per call.

pub fn read_hot_fields(&self) -> (u64, f32, f32, u64)

Read hot fields atomically without seqlock. ~5-20ns. Returns (cycle, surprise, curiosity, predicted_hash).

pub fn is_fresh(&self, expected_cycle: u64) -> bool

Check if the snapshot is fresh (hot_cycle matches or exceeds expected).

pub fn set_cached_format(&self, s: String)

Update cached format string. Called by the background cycle.

pub fn set_hot_fields( &self, cycle: u64, surprise: f32, curiosity: f32, predicted_hash: u64, )

Update hot atomic fields. Called by the background cycle.

pub fn read(&self) -> Option<SnapshotData>

Read the snapshot. Returns None after SNAPSHOT_MAX_RETRIES torn reads. The returned SnapshotData is a copy — no lock required to use it.

Trait Implementations

impl Debug for SharedSnapshot

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Send for SharedSnapshot

impl Sync for SharedSnapshot