Module atomisation 

v0.7.0 WT-1-B — substrate-level atomisation engine.

The atomiser is the second hard prereq for the v0.7.0 atomisation pipeline (WT-1-A schema v36 is the first; WT-1-C/D/E/F all consume the writer landed here). It takes one long-form memory, runs the curator pass to decompose it into atomic propositions, and writes each atom back as a first-class memory with full provenance:

• memories.atom_of → parent memory id (structural FK, schema v36)
• memory_links.relation = 'derives_from' (atom → parent, the typed, signable, federation-safe expression of the FK)
• signed_events rows for the per-atom write, the per-link write, and the final atomisation_complete summary event

The parent memory is archived (archived_at set, atomised_into set to atom_count) in a SEPARATE post-atom transaction so the per-atom hooks fire on live writes; downstream consumers walk the atom_of index to surface atoms in place of an atomised parent.

Hook integration

Atoms are first-class memory_store writes — the existing pre_store/post_store substrate hooks fire per atom via crate::storage::insert. Governance refusal mid-batch returns AtomiseError::GovernanceRefused carrying the failing atom index; prior atoms in the batch are NOT rolled back (they were valid writes by themselves).

Idempotency

A second atomise(source_id, ...) call after a successful first returns AtomiseError::AlreadyAtomised with the existing atom ids. Passing force=true skips the idempotency check and mints a fresh set of atoms; old atoms are retained (their atom_of pointer remains valid), and atomised_into is bumped to the new atom_count.

Modules

curator

v0.7.0 WT-1-B — atomisation curator.

Structs

AtomisationDepthGuard

RAII guard returned by enter_atomisation_pass. While the guard is alive, the thread’s atomisation depth is incremented by 1; on drop the depth decrements back to the prior value. The atomiser holds the guard across the full atomise_sync_with_retries body so any pre_store / post_store hooks that re-enter atomise observe the incremented depth and refuse past the cap on entry.

AtomiseResult

Successful atomisation outcome.

Atomiser

The atomisation engine.

AtomiserConfig

Tunables for the atomiser. Plumbed from AppConfig in the daemon path; tests construct one directly.

Enums

AtomiseError

Typed error surface for Atomiser::atomise.

Constants

DEFAULT_ATOM_TOKENS

Default max_atom_tokens when the caller passes none (or null).

MAX_ATOMISATION_DEPTH

Compiled-in cap for the recursive atomisation-pass depth. An atomise_sync_with_retries call site running at depth N may indirectly invoke another atomise (via the pre_store auto-atomise hook firing on a freshly-minted atom in a namespace that opted in, etc.); each such nesting bumps the counter by 1. Once the counter exceeds this cap the substrate refuses the atomisation pass with AtomiseError::DepthExceeded and the stable slug ATOMISATION_DEPTH_EXCEEDED.

MAX_ATOM_TOKENS

Largest accepted max_atom_tokens — above this an “atom” is no longer atomic.

MIN_ATOM_TOKENS

Smallest accepted max_atom_tokens — below this an “atom” can’t hold a self-contained proposition.

Functions

current_atomisation_depth

Read the current thread’s atomisation-pass recursion depth. Returns 0 outside any active atomiser call (production callers); returns N while the N-th nested atomise is in flight on this thread.

enter_atomisation_pass

Enter an atomisation-pass scope. Returns the new depth (post-increment) plus an RAII guard that restores the depth on drop. Callers MUST retain the guard across the full atomise body — dropping it mid-call would underflow the depth and let nested calls escape the cap.