Crate soma_som_core

Expand description

§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

Type	Purpose
`Quad`	Root + Pointer + Tree triple — the universal data carrier
`Tree`	Hierarchical key-value structure carrying FU.Data
`Ring`	Six-unit ring topology (FU/MU/CU/OU/SU/HU)
`UnitId`, `Layer`, `Element`	Structural constants
`World`	The 6 interrogative worlds (WAI/WIU/WCN/WAY/WAW/WDW)
`Genesis`	Universal ring bootstrap protocol
`Fingerprint`	BLAKE3 fingerprint over canonical encoding
`TemporalLedger`	Append-only cycle chain
`CrossingRecord`	Ed25519-attested boundary transition record
`RingStore` (trait)	Persistence abstraction
`Extension` (trait family)	The 5 ring relationships (BEFORE / THROUGH / AFTER / AROUND / WITHIN)
`LexiconProvider` (trait)	Vocabulary declaration interface
`SiblingManifest` (trait)	Hosted-application contract

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:

Crate	Purpose
`soma-som-ring`	Ring execution engine — RingEngine, RingProcessor, Two Doors cycle

§Running tests

cargo test

§Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

§Repository

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

§soma-som-core

Universal structural primitives for the SOMA/SOM circular architecture.

This crate defines the ring’s structural backbone: Quad, Ring, unit identities, SOM layers, fingerprints, the temporal ledger, and the Genesis protocol. It contains no IPC, no IO, no side effects, and no application-specific governance types.

§Ring Foundation Purity

soma-som-core defines the seven §13.1 pluggable governance trait surfaces (AuthorizationProvider, AutonomyEvaluator, ConfigurationProvider, EvidenceValidator, ProcessEngine, ProcessGate, CycleAnnotator) and their no-op defaults. Concrete §13.2 policy data is application-tier.

§Paper traceability — soma(som) v1.0 (State of Mind)

Type / Module	Reference
`Quad`	OPUS §2 (Definition 1)
`UnitId`, `Layer`	OPUS §5, §4
`UnitId::W_LABELS`	SOMA_FRONTEND_SPEC §2.4
`Ring`	OPUS §3, §6
`Fingerprint`	OPUS §8 (Definitions 7–8)
`TemporalLedger`	OPUS §9.5
`Genesis`	OPUS §10
`Position`	OPUS §8.1
`Envelope`	Contracts §2
`PerspectivalChain`	Perspectival Ledger §2
`CrossingRecord`	Contracts §2.1 (Def. 2)
`RingStore`	L0 persistence trait
`Extension`+5 traits	Ring-extension family
`World`	OPUS §6 (State-of-Mind worlds)
`VocabTerm`	OPUS §5.1–§5.6 (72 terms)
`WorldRegistry`	OPUS §1.2 + §6

Re-exports§

pub use authorization::AuthorizationProvider;
pub use authorization::AuthorizationTable;
pub use authorization::AuthorizationTableEntry;
pub use authorization::AuthorizationTableResult;
pub use authorization::PermissionCollision;
pub use authorization::PermissionRegistry;
pub use authorization::PermissionRequirement;
pub use authorization::PermitAll;
pub use authorization::SharedAuthorizationTable;
pub use authorization::SharedPermissionRegistry;
pub use codec::CodecError;
pub use codec::persist_decode;
pub use codec::persist_encode;
pub use crossing::CrossingRecord;
pub use envelope::Envelope;
pub use evidence::AcceptAll;
pub use evidence::EvidenceValidator;
pub use evidence::verify_ring_cycle_evidence;
pub use evidence::verify_ring_cycle_evidence_with_key;
pub use evidence::verify_view_cycle_evidence;
pub use signing_provider::CrossingSigner;
pub use signing_provider::NoopSigner;
pub use signing_provider::SigningProviderError;
pub use timing::CycleTimer;
pub use timing::TimingConfig;
pub use timing::TimingError;
pub use timing::UnitTiming;
pub use error::SomaError;
pub use extension::AfterRing;
pub use extension::AroundRing;
pub use extension::BeforeRing;
pub use extension::CommandSchema;
pub use extension::DelegationError;
pub use extension::Extension;
pub use extension::GateRejection;
pub use extension::SchemaField;
pub use extension::SchemaFieldType;
pub use extension::ThroughRing;
pub use federation::DescriptorEnvelope;
pub use federation::DescriptorPayload;
pub use federation::EnvelopeDestination;
pub use federation::OrientationSummary;
pub use federation::PeerRecord;
pub use federation::PeerStatus;
pub use federation::RingAnnounce;
pub use federation::RingFingerprint;
pub use federation::federation_ns;
pub use fingerprint::awareness_fingerprint;
pub use fingerprint::ring_fingerprint;
pub use fingerprint::system_fingerprint;
pub use genesis::Genesis;
pub use governance_context::GovernanceContext;
pub use ledger::LedgerEntry;
pub use ledger::TemporalLedger;
pub use lexicon::CoordinateError;
pub use lexicon::LexiconEntry;
pub use lexicon::LexiconProvider;
pub use lexicon::Medium;
pub use lexicon::Rendering;
pub use lexicon::RenderingPack;
pub use lexicon::ResolvedRendering;
pub use lexicon::TermDescription;
pub use lexicon::VocabCoord;
pub use lexicon::resolve_rendering;
pub use perspectival::PerspectivalChain;
pub use perspectival::PerspectivalEntry;
pub use perspectival::PerspectivalState;
pub use perspectival::cross_verification_digest;
pub use position::Position;
pub use processor::UnitProcessor;
pub use processor::UnitProcessorError;
pub use quad::Quad;
pub use ring::Ring;
pub use ring::RingState;
pub use ring_store::RingStore;
pub use ring_store::RingStoreBackendError;
pub use ring_store::RingStoreError;
pub use ring_store::RingStoreResult;
pub use sibling::CapabilityDeclaration;
pub use sibling::DomainRequest;
pub use sibling::HttpMethod;
pub use sibling::RegistrationError;
pub use sibling::RouteMount;
pub use sibling::SiblingManifest;
pub use sibling::SiblingStatus;
pub use sibling::SurfaceSection;
pub use traceability::CycleContext;
pub use traceability::CycleKind;
pub use traceability::LEGACY_SEMANTIC_HASH;
pub use types::CrossingType;
pub use types::Element;
pub use types::Layer;
pub use types::LayerTransition;
pub use types::UnitId;
pub use types::World;
pub use vocab::VocabTerm;
pub use vocab::all_terms;
pub use vocab::domain_term;
pub use world::OrganEntry;
pub use world::WorldRegistry;

Modules§

authorization: Pluggable command authorization + ring-collected permission/rule tables.
autonomy: Pluggable autonomy evaluation.
codec: Shared persistence codec — one implementation, used by all organs.
configuration: Pluggable configuration resolution.
crossing: Crossing record: the boundary’s attestation that a transition occurred.
envelope: The Envelope: foundational wire type for ring crossings (Contracts §2).
error: Error types for soma-som-core.
evidence: Pluggable evidence validation + ring-cycle evidence tripwires.
extension: Extension: the structural contract for ring-external services.
federation: Federation types for Meta-Ring descriptor exchange.
fingerprint: Fingerprint computation: awareness (72 positions) and system (90 positions).
genesis: Genesis protocol: bootstrapping the ring from pipeline to closed loop.
governance_context: GovernanceContext — boxed bundle of all seven governance trait objects.
ledger: Temporal ledger: the hash chain across ring cycles.
lexicon: Lexicon: the ring’s semantic dictionary (Layer 1 — vocabulary registry).
perspectival: Perspectival ledger: per-unit hash chains and cross-verification.
position: Position addressing: (unit, layer, element) triples.
process_engine: Pluggable process execution engine.
process_gate: Pluggable process-lifecycle gating.
processor: The UnitProcessor trait: structural boundary contract at the body-problem level.
quad: The Quad — universal structural element of SOMA/SOM.
ring: The SOMA Ring: six units, 30 Quads, ring state machine.
ring_store: RingStore: the L0 persistence trait for ring state.
sibling: Sibling extension manifest — the structural contract for ring-hosted siblings.
signing_provider: Abstract signing provider trait for ring crossing attestation.
testing: Test doubles for ring extensions.
timing: Timing configuration and enforcement (Criterion 3 — bounded completion).
traceability: Ring-level cycle traceability types.
types: Core enumeration types: units, layers, and Quad elements.
vocab: Domain vocabulary for all six SOMA units.
world: World Registry — maps organs to their interrogative worlds.

Macros§

impl_redb_store_errors: Generate From<redb::*Error> impls that stringify into a single variant.