soma-som-core

Universal soma(som) structural primitives — the foundation crate of the soma(som) state-of-mind architecture.

soma-som-core defines the data carrier (Quad/Tree), the topology (Ring, UnitId, Layer, Element), the cryptographic chain primitives (Fingerprint, TemporalLedger, CrossingRecord), and the structural vocabulary (72 SOM positions, 6 Worlds). No application-specific behaviour, governance, or policy is defined here.

Position in the layer model

Application layer    — your ring-native application
   │ depends on
   ▼
Platform layer       — soma-som-ring (ring execution engine, LGPL-3.0-only)
   │ depends on
   ▼
Foundation layer     — soma-som-core ← THIS CRATE (LGPL-3.0-only)

soma-som-core has zero internal soma-* dependencies. Its only deps are external (bincode, blake3, ed25519-dalek, serde, thiserror).

Naming — published vs. import path

• Published name on crates.io / Codeberg / docs.rs: soma-som-core (under the somasom organisation namespace).
• Rust import path in your code: use soma_som_core::Quad; (the - becomes _ per Rust crate-name conventions).
• The soma- / som- split is deliberate: soma- marks procedural crates (body / ring substrate that does work); som- marks State-of-Mind crates (snapshot content that is awareness). soma-som-core is procedural foundation that ships the State-of-Mind structural carriers.

Key public types

For the full architectural model (Two Doors, body problem, fingerprint chain, position addressing, codec stability), read the solitaire SAD at docs/soma-som-core-sad.md.

Structural constants

These are compile-time constants, not configuration:

• 6 units: FU → MU → CU → OU → SU → HU → FU
• 4 layers: CLIENT, SERVER, RING, BUS
• 3 elements per layer: REQUEST, COMMITMENT, EXPECTATION
• 72 SOM positions: 6 units × 4 layers × 3 elements

The 6 Worlds map 1:1 to UnitId (FU↔WAI, MU↔WIU, CU↔WCN, OU↔WAY, SU↔WAW, HU↔WDW).

Key design invariants

Body problem as a type constraint

The Quad struct has exactly three fields: root, pointer, tree. There is no field for the external key (the predecessor's reference). This is the type-level encoding of the body problem: a Quad embedded in the ring cannot hold its own external key because the type does not have a place for it.

Deterministic fingerprints

Tree uses BTreeMap (not HashMap) to guarantee deterministic iteration order. The same content always produces the same fingerprint, regardless of insertion order.

BLAKE3

All hash operations use BLAKE3. The blake3 crate is the cryptographic primitive.

Codec stability

Persistence encoding uses bincode 2 for new payloads (v=2), with bincode 1 retained as bincode_legacy for v=0 legacy decode. The magic-prefix discriminator [0xFF×4 + version_byte] disambiguates at the byte boundary.

Usage

# Cargo.toml
[dependencies]
soma-som-core = "0.1"

use soma_som_core::quad::{Quad, Tree};
use soma_som_core::types::UnitId;

// Construct a Quad — the universal data carrier (Root + Pointer + Tree).
let mut tree = Tree::new();
tree.insert("session.token".into(), b"opaque-bytes".to_vec());
let quad = Quad::from_strings("origin", "next", tree);

// Quads are content-addressable.
assert_eq!(quad.content_hash(), quad.content_hash());

// The 6 ring units are compile-time constants.
assert_eq!(UnitId::ALL.len(), 6);

soma-som-core is a dependency-only crate — it ships no runtime, no binary, no service. To run a ring, depend on soma-som-ring (the platform crate that orchestrates the cycle).

Architecture reference

For the deep architectural reading — Two Doors symmetry, body problem, fingerprint chain, position addressing, codec stability — see the ARC42 Solitaire Architecture Document at docs/soma-som-core-sad.md. The canonical specification is the soma(som) v1.0 OPUS paper — State of Mind: A Circular Architecture for Human-Machine Integration: 10.5281/zenodo.20335962.

License

LGPL-3.0-only — see LICENSE.

soma-som-core is licensed under the GNU Lesser General Public License v3.0 only. LGPL §4 (the relinking provision) covers Rust's static-linking compilation model: applications using soma-som-core as a library do not become LGPL themselves — only modifications to soma-som-core that are distributed must be shared under LGPL terms.

Commercial licensing (proprietary embedding without LGPL-3.0 obligation on distributed modifications): contact licensing@somasom.io.

Versioning

Pre-1.0 (currently 0.1.0). The 1.0 gate requires the API stability commitment for the Foundation layer, an independent security audit, and external-adopter feedback against the published API.

Companion crate

soma-som-core ships alongside soma-som-ring as a two-crate solitaire:

Running tests

cargo test

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Repository

https://codeberg.org/somasom/soma-som-core