corpus-ipc 0.2.0

Spike and neuromodulator wire protocol and IPC transports for Limen-Neural SNN runtimes.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

// SPDX-License-Identifier: MIT OR Apache-2.0

use serde::{Deserialize, Serialize};

use crate::validation::{ProtocolLimits, Validate, ValidationError, check_finite};

use super::de::de_loss;
use super::{
    ConfigPayload, EmbeddingBatch, GradientBatch, NeuromodulatorSnapshot, SpikeBatch,
    StimulusBatch, TraceBatch,
};

/// Core message enum for cross-process IPC.
///
/// Messages are separated into:
/// - Input messages (spikes, embeddings, stimuli, neuromodulators, config)
/// - Output messages (gradients, traces, training status)
/// - Control messages (shutdown, ping)
///
/// Variant names (`Spikes`, `EligibilityTraces`, …) are serde identifiers and
/// must stay stable. The payloads they wrap are IPC transport types, not
/// in-memory training structs (see the module docs).
///
/// Versioned ingress should go through
/// [`crate::decode_ipc_message_json`]: that entry point classifies
/// [`crate::WireCompatibility`] before the payload is used. Direct
/// `Deserialize` on this enum is the unversioned (legacy) encoding.
///
/// Unknown object fields on payloads are ignored (forward compatible).
/// Unknown variant names fail to deserialize; this enum has no `Default`
/// and no serde `other` catch-all, so they never become a valid message.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub enum IpcMessage {
    // Input messages
    /// Wire payload for an IPC [`SpikeBatch`] (not an in-memory training batch).
    Spikes(SpikeBatch),
    Embeddings(EmbeddingBatch),
    /// Typed continuous runtime stimulus ingress between a producer and a
    /// consumer. See [`StimulusBatch`] for channel-width and
    /// invalid/missing-channel semantics.
    Stimuli(StimulusBatch),
    /// Typed neuromodulator ingress, replacing an unstructured float tail.
    /// See [`NeuromodulatorSnapshot`] and [`Validate`].
    Neuromodulators(NeuromodulatorSnapshot),
    Loss(#[serde(deserialize_with = "de_loss")] f32),
    ConfigUpdate(ConfigPayload),

    // Output messages
    GradientUpdate(GradientBatch),
    /// Wire payload for an IPC [`TraceBatch`] (not an in-memory training batch).
    EligibilityTraces(TraceBatch),
    TrainingComplete,

    // Control
    Shutdown,
    Ping,
}

impl Validate for IpcMessage {
    fn validate_with(&self, limits: ProtocolLimits) -> Result<(), ValidationError> {
        match self {
            Self::Spikes(batch) => batch.validate_with(limits),
            Self::Embeddings(batch) => batch.validate_with(limits),
            Self::Stimuli(batch) => batch.validate_with(limits),
            Self::Neuromodulators(snapshot) => snapshot.validate_with(limits),
            Self::ConfigUpdate(payload) => payload.validate_with(limits),
            Self::GradientUpdate(batch) => batch.validate_with(limits),
            Self::EligibilityTraces(batch) => batch.validate_with(limits),
            Self::Loss(value) => check_finite("Loss", *value),
            Self::TrainingComplete | Self::Shutdown | Self::Ping => Ok(()),
        }
    }
}