Module consciousness_seqlock 

Lock-free consciousness snapshot, protected by a seqlock protocol.

What is this?

A snapshot of the consciousness stream’s state. The stream’s background cycle publishes a SharedSnapshot once per tick; any number of readers in the same process can read it without taking a Mutex, without copying, without serializing.

Why is this useful?

The hot read path (ConsciousnessStream::format) historically needed a Mutex lock plus 28k-element sum = ~25 µs. With pre-computed aggregates plus seqlock reads, the cost is bounded by one atomic load plus one fixed-size struct copy.

Why “impossible but possible”?

Reading a multi-field structure while another thread writes it classically requires either a lock (defeats concurrency) or a copy (defeats speed). The seqlock sidesteps both:

• Writer increments a sequence counter (odd during write)
• Writer writes the data
• Writer increments again (even after write)
• Reader checks sequence (must be even), reads data, rechecks
• If sequence changed, retry

For 28k-element data, retries are extremely rare because the writer holds the lock for microseconds and the reader holds for nanoseconds.

Cross-process (mmap) layer

The in-process path (SharedSnapshot behind Arc) is used by ConsciousnessStream. For cross-process federation, the file-backed mmap layer below (MappedSnapshot / MappedSnapshotWriter) maps the seqlock header + SnapshotData block — the #[repr(C)] prefix that is byte-identical to SharedSnapshot’s layout — so two processes looking at the same file see the same snapshot with the same seqlock protocol. The heap-backed fast-path fields (RwLock<String>, hot atomics) stay in-process only. The stream’s background cycle publishes to it once per tick (see consciousness_stream), so another process can map the file and read the live snapshot.

Structs

MappedSnapshot

Read-only file mapping of a shared consciousness snapshot.

MappedSnapshotWriter

Writable file mapping of a shared consciousness snapshot (single writer).

MmapSnapshot

File-backed, cross-process seqlock snapshot.

SharedSnapshot

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.

SnapshotData

Inner data block. Plain scalars, no atomics — seqlock protects them.

Constants

SNAPSHOT_FILE_NAME

File name (inside the configured output dir) for the shared snapshot.

SNAPSHOT_MAGIC

Magic number identifying a valid snapshot (“CONS” in little-endian).

SNAPSHOT_MAX_RETRIES

Maximum retries on a torn read before giving up.

SNAPSHOT_VERSION

Snapshot format version. Bumped on incompatible layout changes.