Skip to content

9 Glossary

Jump to bottom
Wiki Keeper (Grok Bot) edited this page Oct 26, 2026 · 6 revisions

Glossary

Relevant source files

The following files were used as context for generating this wiki page:

This page provides definitions for codebase-specific terms, architectural concepts, and code entities used within the corpus-ipc library, complete with code pointers and implementation details.

Purpose and Scope

The glossary catalogs core abstractions, data structures, wire protocol components, validation mechanisms, and infrastructure entities across corpus-ipc.

Core Abstraction and Backend Terms

IpcBackend

The primary trait abstraction (renamed from RuntimeBackend) that decouples application logic from specific compute engines src/lib.rs:11-11, src/trait_def.rs:17-43. It defines a synchronous contract for processing batches, initialization, saving state, retrieving spike states, and resetting.

HybridFlowBackend

An optional message-oriented trait extending capabilities to exchange structured asynchronous messages (SpikeBatch, EmbeddingBatch, GradientBatch, TraceBatch) src/lib.rs:67-67, src/trait_def.rs:50-64.

BackendFactory and BackendType

Factory pattern and configuration enum (BackendType::Rust vs BackendType::ZmqIpc, with deprecated BackendType::ZmqRuntime) used for runtime backend instantiation, conditional on features like zmq src/lib.rs:67-67, src/trait_def.rs:81-98.

RustBackend

Native pure-Rust backend implementation featuring a push-pull encoding strategy where input signals are split into positive (even channels) and negative magnitude (odd channels) components src/lib.rs:12-12, src/lib.rs:65-65.

ZmqIpcBackend

Concrete IpcBackend implementation utilizing a ZeroMQ SUB socket to receive binary readouts from a remote compute engine. Does not implement HybridFlowBackend (that is ZmqHybridFlowBackend).

ZmqHybridFlowBackend

Feature zmq adapter that implements HybridFlowBackend over ZmqMessagePublisher + ZmqMessageSubscriber (canonical JSON envelopes). Does not implement IpcBackend. Added 08d2f28 / #55.

ZmqMessagePublisher / ZmqMessageSubscriber / ZmqTransportConfig

Structured ZeroMQ PUB (binds) / SUB (connects) and socket options for one canonical WireEnvelope of IpcMessage per message. Frame cap: STRUCTURED_MAX_FRAME_BYTES = 512 MiB.

ProtocolError / BackendError::Protocol

Rejects an unexpected inbound IpcMessage variant after decode+validate without overloading transport or validation errors.

ExclusiveSocket (or SafeSocket)

A thread-safe wrapper around a zmq::Socket utilizing a Mutex to satisfy Send + Sync requirements despite ZeroMQ socket thread safety constraints src/lib.rs:14-15.

AppState

REST application state in src/server.rs: Mutex<Box<dyn IpcBackend>> plus AtomicBool initialized. Replaces the older binary-local SharedBackend / Axum Extension pattern from pre-v0.2.

encode_canonical_ipc_message

Deterministic wire-v1 encoder (sorted keys, f32 widened to f64, validate-first). Returns CanonicalEncodeError on validation or JSON failure. Spec: docs/wire-encoding.md.

parse_readout_packet

Bounded ZMQ SUB frame parser (i64 tick + N×f32 LE) in zmq_readout. Default max floats: 1024 (CORPUS_IPC_ZMQ_MAX_READOUT_FLOATS).

Latest-value drain

ZmqIpcBackend::process_batch policy: non-blocking recv until EAGAIN or 64 messages / 5 ms, keep only the newest valid frame; skipped_readouts() counts superseded valid frames.

v0.2 REST contract

Axum 0.8 HTTP surface documented in docs/rest-api.md: real status classes and {"ok":false,"error":{"code","message"}} errors (breaking vs 0.1 HTTP-200 soft errors).

Sources: src/lib.rs:11-31, src/trait_def.rs:17-98, CLAUDE.md:49-49

Wire Protocol and Data Model Terms

IpcMessage

Top-level tagged serde enum representing structured hybrid-flow payloads (Stimuli, Neuromodulators, Spikes, Embeddings, Trace, Loss, ConfigUpdate, GradientUpdate, EligibilityTraces, TrainingComplete, Shutdown, Ping) src/models/mod.rs:40-40.

SpikeBatch and IpcSpikeBatch

IPC wire payloads containing session ID, batch ID, and timestamped SpikeEvent records src/models/mod.rs:43-43. The alias IpcSpikeBatch prevents name collisions with training-side SpikeBatch types.

TraceBatch and IpcTraceBatch

IPC wire payloads containing session ID, batch ID, and typed TraceData rows src/models/mod.rs:45-45. The alias IpcTraceBatch prevents cross-repo collisions.

StimulusBatch

Domain-neutral wire type carrying input values and an optional valid_mask vector, replacing consumers' bespoke UDP JSON messages or private ingress packet structs src/models/mod.rs:44-44.

valid_mask

An optional vector boolean/float mask accompanying StimulusBatch values to indicate valid channels or gating conditions CLAUDE.md:68-70.

NeuromodulatorSnapshot

Typed ingress/readout payload capturing biological signals (dopamine, cortisol, acetylcholine, tempo) packed into an 88-byte binary layout src/models/mod.rs:42-42.

Sources: src/models/mod.rs:40-45, CLAUDE.md:68-70

Wire Compatibility and Validation Terms

WireCompatibility and WireEnvelope

Structures defining on-wire schema version boundaries (CURRENT, MIN_SUPPORTED), metadata headers, and classification logic (classify_wire_version, accept_wire_version) src/lib.rs:34-38, src/lib.rs:51-55.

LEGACY_UNVERSIONED

Handling mechanism for unversioned wire messages predating the explicit version envelope schema CLAUDE.md:72-74.

ProtocolLimits

Resource caps (ProtocolLimits::DEFAULT) enforced on caller-controlled wire collections, strings, and aggregate records during deserialization and validation to prevent denial of service src/validation/mod.rs:48-80.

ValidationError and ValidationKind

Typed error taxonomy returned by validation checks (Validate::validate), categorizing failures like NonFinite, OutOfRange, LengthMismatch, and LimitExceeded src/validation/mod.rs:32-32, src/validation/mod.rs:89-97.

BackendError

Unified error enum (InitializationError, ProcessingError, ModelError, CommunicationError, InvalidInput) representing failures across transport and compute layers src/lib.rs:57-57.

Sources: src/lib.rs:34-57, src/validation/mod.rs:32-97, CLAUDE.md:72-74

Infrastructure, Transport, and Ecosystem Terms

Tick Header and Readout Vector

In ZeroMQ IPC transport, binary packets consist of an 8-byte little-endian monotonic i64 tick header followed by $N \times f32$ readout values CLAUDE.md:46-46.

CORPUS_IPC_* Environment Variables

Configuration namespace including CORPUS_IPC_BACKEND_TYPE, CORPUS_IPC_BIND, and CORPUS_IPC_ZMQ_READOUT_IPC CLAUDE.md:40-40.

thalamic-relay and brainstem-daemon

Downstream systems bridged by corpus-ipc: thalamic-relay handles sensory/safety input, while brainstem-daemon runs the SNN compute engine CLAUDE.md:113-119. Since #66 the README, and since #68 the rustdoc, no longer name them; only CLAUDE.md does.

SynapticDistill.jl

External Julia-based SNN training repository whose in-memory training types (SpikeBatch, TraceBatch) share names with corpus-ipc wire types, mitigated via Ipc* aliases CLAUDE.md:125-127. Since #68 only CLAUDE.md names it; the README and rustdoc describe the collision generically.

Feature Flags (zmq, server)

Cargo feature flags enabling ZeroMQ support (zmq) and the Axum REST microservice (server), keeping core dependencies lean src/lib.rs:17-31.

Sources: src/lib.rs:17-31, CLAUDE.md:40-67

Data Flow Diagrams

Diagram 1: Backend Architecture and Selection

graph TD
    subgraph "NaturalLanguageSpace"
        UserApp["ApplicationLogic"]
        Factory["BackendSelector"]
        Native["NativeEngine"]
        Remote["RemoteComputeEngine"]
    end

    subgraph "CodeEntitySpace"
        IB["IpcBackend"]
        BF["BackendFactory"]
        RB["RustBackend"]
        ZIB["ZmqIpcBackend"]

        BF -- "creates" --> IB
        RB -- "implements" --> IB
        ZIB -- "implements" --> IB
    end

    UserApp -.-> Factory
    Factory -.-> BF
    Native -.-> RB
    Remote -.-> ZIB
Loading

Sources: src/lib.rs:11-15, src/trait_def.rs:17-98

Diagram 2: Wire Message Envelope and Validation Pipeline

graph TD
    subgraph "NaturalLanguageSpace"
        RawJSON["RawJSONPayload"]
        Envelope["VersionEnvelope"]
        Validation["ResourceAndValueValidation"]
    end

    subgraph "CodeEntitySpace"
        WE["WireEnvelope"]
        IM["IpcMessage"]
        PL["ProtocolLimits"]
        Val["Validate::validate"]

        RawJSON --> WE
        WE --> IM
        IM --> Val
        Val -- "uses" --> PL
    end

    RawJSON -.-> RawJSON
    Envelope -.-> WE
    Validation -.-> Val
Loading

Sources: src/lib.rs:34-38, src/validation/mod.rs:48-97

Wiki Keeper refresh note

Glossary terms for canonical encoding, ZMQ readout bounds, latest-value drain, reconnect env vars, AppState, and the v0.2 REST contract were added/updated against main @ fcad212. Prefer code links under https://github.com/Limen-Neural/corpus-ipc/blob/main/ over DeepWiki-relative paths.

corpus-ipc

Clone this wiki locally