Humainary Substrates API

API contract for deterministic emission networks

Substrates defines the core interfaces for building computational networks where values flow through circuits, conduits, and channels with deterministic ordering and dynamic topology adaptation. This module is the API specification only — it contains no implementation. A runtime SPI provider (such as humainary-substrates-spi-alpha) is required at runtime.

Core Abstractions

• Circuit: Central processing engine with single-threaded execution
• Conduit: Routes emitted values from channels to subscribers
• Channel: Subject-based port into a conduit's pipeline
• Percept: Marker interface for all observable entities (pipes, instruments)
• Pipe: Emission carrier for passing typed values through pipelines
• Receptor: Callback interface for receiving emissions (domain alternative to Consumer)
• Flow: Type-preserving filtering and stateful operations (diff, guard, limit, etc.)
• Subscriber: Dynamically subscribes to channels and registers pipes
• Subject: Hierarchical reference with identity, name, and state

See GLOSSARY.md for detailed definitions.

Core Guarantees

Deterministic Ordering:

• Emissions are observed in strict enqueue order
• Earlier emissions complete before later ones begin
• All subscribers see emissions in the same order

Eventual Consistency:

• Subscription changes use lazy rebuild with version tracking
• Channels detect changes on next emission (not immediately)
• No blocking or global coordination required

State Isolation:

• Per-pipe flow operators maintain independent state per pipe; conduit-level flow operators share state across all channels in a conduit
• Subscriber state accessed only from circuit thread (no sync needed)
• No shared mutable state between circuits

Installation

Maven

<dependency>
    <groupId>io.humainary.substrates</groupId>
    <artifactId>humainary-substrates-api</artifactId>
    <version>1.0.0</version>
</dependency>

SPI Provider Discovery

The API uses the Service Provider Interface (SPI) pattern. An implementation is resolved at runtime via:

1. System property (primary): Set io.humainary.substrates.spi.provider to the provider class
2. ServiceLoader (fallback): Register via META-INF/services/io.humainary.substrates.spi.CortexProvider

SPI providers must extend io.humainary.substrates.spi.CortexProvider and implement the create() method to return a Cortex implementation.

Testing

This module contains no tests by design — it is a pure API contract. Specification compliance is verified by a separate Test Compliance Kit (TCK) that validates SPI providers against the API's ordering, temporal, lifecycle, and threading guarantees. The TCK is not yet published.

Design Philosophy

The Humainary project seeks to restore essential qualities — sensibility, simplicity, and sophistication — to systems engineering. Substrates serves as the fundamental building block for a generic framework enabling situational awareness and seamless integration of human and machine-based communication, coordination, and cooperation.

License

Copyright © 2025 William David Louth. Licensed under the Apache License, Version 2.0.