Permanence Layer -- Selective Memory & Loam Certificates
-red){kind=icon}
LoamSpine is the immutable, permanent ledger of the ecoPrimals ecosystem. Named after loam -- the slow, anaerobic soil layer where organic matter compresses into permanent geological record -- LoamSpine serves as the canonical source of truth for all events, discoveries, and artifacts that matter.
Key Concepts:
- Selective Permanence -- Only deliberately committed data becomes permanent
- Sovereign Spines -- Each user controls their own history
- Loam Certificates -- Digital ownership with lending and provenance
- Infant Discovery -- Born with zero external knowledge, discovers at runtime
- Capability-Based -- "Who can sign?" not "Where is BearDog?"
- NeuralAPI Integration -- Registers with biomeOS for ecosystem orchestration
- Provenance Trio -- Coordinates with rhizoCrypt (ephemeral) and sweetGrass (attribution)
# Build and test
cargo build --release
cargo test --workspace
# Run the service (UniBin)
cargo run --release --bin loamspine -- server
# With explicit ports (--port is an alias for --jsonrpc-port per UniBin standard)
cargo run --release --bin loamspine -- server --port 8080 --tarpc-port 9001
# UniBin introspection
cargo run --release --bin loamspine -- capabilities
cargo run --release --bin loamspine -- socket
# Quality checks
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check
cargo llvm-cov --workspace --summary-only
cargo deny check licenses bans sources
# Full verification
./verify.shPure Rust -- No gRPC, no protobuf, no C/C++ tooling, no OpenSSL. Zero C dependencies (ecoBin compliant). Blake3 uses pure Rust mode (no C/asm).
Storage backends: redb (default, pure Rust), memory, sqlite (feature-gated). sled is optional via --features sled-storage.
loamSpine/
├── bin/loamspine-service/ # UniBin: server | capabilities | socket
├── crates/
│ ├── loam-spine-core/ # Core library
│ │ └── src/
│ │ ├── backup/ # Backup/restore
│ │ ├── capabilities.rs # Capability definitions
│ │ ├── certificate/ # Loam Certificates (types, lifecycle, metadata, provenance, escrow, usage)
│ │ ├── config.rs # Configuration
│ │ ├── discovery/ # Capability registry + DynSigner/DynVerifier
│ │ ├── discovery_client/ # HTTP discovery client + ResilientDiscoveryClient
│ │ ├── entry/ # Entry types (15+ variants, bincode canonical)
│ │ ├── infant_discovery/ # DNS-SRV, mDNS, registry discovery
│ │ ├── manager/ # Certificate manager
│ │ ├── niche.rs # Primal self-knowledge (capabilities, deps, costs)
│ │ ├── primal_names.rs # Centralized primal identifier constants
│ │ ├── neural_api.rs # NeuralAPI / biomeOS integration
│ │ ├── proof.rs # Inclusion + ownership proofs (Merkle/Blake3)
│ │ ├── resilience.rs # Circuit breaker + retry policy (lock-free)
│ │ ├── service/ # Modular service layer
│ │ │ ├── lifecycle.rs # Startup/shutdown + ServiceState + NeuralAPI
│ │ │ ├── certificate.rs # Certificate core (mint, transfer, verify, proofs)
│ │ │ ├── certificate_loan.rs # Loan lifecycle (loan, return, sublend)
│ │ │ ├── certificate_escrow.rs # Escrow (hold, release, cancel)
│ │ │ ├── expiry_sweeper.rs # Background expired-loan auto-return
│ │ │ ├── integration.rs # Trait implementations
│ │ │ ├── signals.rs # Signal handling
│ │ │ └── waypoint.rs # Anchoring, operations, departure, attestation, proofs
│ │ ├── spine.rs # Spine structure
│ │ ├── storage/ # Storage backends (redb default, memory, sled optional, sqlite)
│ │ ├── sync/ # Sync engine (push/pull, peer discovery)
│ │ ├── temporal/ # Time tracking (moments, anchors)
│ │ ├── traits/ # Integration traits
│ │ ├── transport/ # IPC transports (HTTP, NeuralAPI, mock)
│ │ ├── waypoint.rs # Waypoint types (config, attestation, relending chain)
│ │ └── trio_types.rs # Provenance trio type bridging
│ └── loam-spine-api/ # RPC layer (19 source files)
│ └── src/
│ ├── jsonrpc/ # JSON-RPC 2.0 (semantic naming)
│ ├── tarpc_server.rs # Binary RPC (primal-to-primal)
│ ├── service/ # Domain-focused RPC ops
│ ├── health.rs # Health checks
│ └── error.rs # API errors
├── specs/ # 11 specification documents
├── showcase/ # Interactive demos (71 files)
└── fuzz/ # Fuzz testing targets
Dual Protocol:
- tarpc -- High-performance binary RPC for primal-to-primal
- JSON-RPC 2.0 -- Universal, language-agnostic for external clients and NeuralAPI (batch support)
| Category | Method | Description |
|---|---|---|
| Spine | spine.create |
Create sovereign ledger |
| Spine | spine.get |
Get spine metadata |
| Spine | spine.seal |
Make immutable |
| Entry | entry.append |
Add entry to chain |
| Entry | entry.get |
Query by hash |
| Entry | entry.get_tip |
Get latest entry |
| Certificate | certificate.mint |
Create ownership cert |
| Certificate | certificate.transfer |
Transfer ownership |
| Certificate | certificate.loan |
Temporary access |
| Certificate | certificate.return |
End loan |
| Certificate | certificate.get |
Query certificate |
| Certificate | certificate.verify |
Verify integrity |
| Certificate | certificate.lifecycle |
Ownership/loan history |
| Waypoint | slice.anchor |
Anchor borrowed state |
| Waypoint | slice.record_operation |
Record waypoint operation |
| Waypoint | slice.depart |
Depart from waypoint |
| Proof | proof.generate_inclusion |
Create proof |
| Integration | session.commit |
rhizoCrypt commits |
| Integration | commit.session |
Semantic alias (biomeOS routing) |
| Integration | braid.commit |
sweetGrass commits |
| Compat | permanent-storage.commitSession |
rhizoCrypt wire format |
| Compat | permanent-storage.verifyCommit |
Verify via rhizoCrypt format |
| Compat | permanent-storage.getCommit |
Retrieve via rhizoCrypt format |
| Compat | permanent-storage.healthCheck |
Health for rhizoCrypt clients |
| Health | health.check |
Service status |
| Meta | capability.list |
List primal capabilities |
LoamSpine discovers services at runtime via infant discovery (zero knowledge at startup):
- NeuralAPI -- biomeOS Unix socket IPC (preferred, capability-registered)
- Environment Variables (
CAPABILITY_*_ENDPOINT,*_SERVICE_URL) - Service Registry -- HTTP-based (Songbird, Consul adapter, etcd adapter)
- DNS SRV -- RFC 2782 (
_signing._tcp.local) - mDNS -- RFC 6762 (experimental, feature-gated)
- Development Fallback (
localhost, debug builds only)
| Metric | Value |
|---|---|
| Version | 0.9.16 |
| Edition | 2024 |
| Tests | 1,270 passing (all concurrent, ~3s) |
| Coverage | 92% line / 87% region / 93% function (llvm-cov) |
| Clippy | 0 warnings (pedantic + nursery + missing_const_for_fn, -D warnings) |
| Unsafe Code | 0 (#![forbid(unsafe_code)]) |
| Lint Exceptions | 3 #[allow] in production (2× tarpc macro, 1× feature-conditional async); tests all #[expect(reason)] |
| Max File Size | 899 lines (all 129 files < 1000) |
| Source Files | 129 .rs files across 2 crates + binary (+ 3 fuzz targets) |
| License | AGPL-3.0-or-later + ORC + CC-BY-SA-4.0 (scyBorg triple) |
| SPDX Headers | All source files |
| ecoBin | Zero C dependencies (pure Rust) |
| cargo deny | advisories, bans, licenses, sources all pass |
| UniBin | server, capabilities, socket subcommands |
| Mock isolation | All mocks cfg-gated out of production |
# Docker
docker build -t loamspine .
# Verify everything
./verify.shComplete specifications in specs/:
- Core specification, architecture, data model
- Certificate layer, waypoint semantics
- API specification, service lifecycle
- Integration specification (provenance trio)
See CONTRIBUTING.md.
scyBorg triple license:
- Code: AGPL-3.0-or-later — see LICENSE
- Game Mechanics: ORC — see LICENSE-ORC
- Creative/Documentation: CC-BY-SA-4.0 — see LICENSE-CC-BY-SA
This repo is part of the ecoPrimals sovereign computing ecosystem — a collection of pure Rust binaries that coordinate via JSON-RPC, capability-based routing, and zero compile-time coupling.
See wateringHole for ecosystem documentation, standards, and the primal registry.
LoamSpine: Where memories become permanent.