3.4 Topology Digest

Topology Digest

Relevant source files

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

• Cargo.lock
• src/topology/digest.rs
• src/topology/mod.rs
• tests/topology_digest.rs

Purpose and Scope

The topology digest subsystem provides a versioned, deterministic cryptographic fingerprint (TopologyDigest) for the logical graph structure represented by SynapticGraph src/topology/mod.rs:5-7. Replay synchronization, checkpoint provenance verification, and cross-runtime consistency checks require a stable identifier of the logical graph topology that remains invariant across CSR (Compressed Sparse Row) insertion orders, internal hash-map iteration sequences, memory pointer layouts, host architectures, and JSON serialization formatting src/topology/digest.rs:5-8.

Sources: src/topology/mod.rs:3-8(), src/topology/digest.rs:3-8()

---

Schema v1 Specification & Preimage Construction

Schema v1 defines the printable manifest string format and the canonical byte layout fed into the SHA-256 hash function src/topology/digest.rs:9-35.

Printable String Format

The printable representation conforms to the following grammar:

synaptic-wiring.topology.digest.v1:sha256:<64 lowercase hex chars>

Where:

• Domain separator: synaptic-wiring.topology.digest.v1 (TOPOLOGY_DIGEST_DOMAIN) src/topology/digest.rs:60
• Algorithm: sha256 (TOPOLOGY_DIGEST_ALGORITHM) src/topology/digest.rs:63
• Hex payload: 64-character lowercase hexadecimal encoding of the raw 32-byte SHA-256 hash digest src/topology/digest.rs:75-122

Preimage Byte Layout

The cryptographic preimage constructed prior to hashing consists of the following sequential components:

1. Domain Separator: [TOPOLOGY_DIGEST_DOMAIN] encoded as UTF-8 bytes, immediately terminated by a NUL byte (DOMAIN_TERMINATOR, 0x00) to prevent prefix collisions src/topology/digest.rs:17-20.
2. Schema Version: [TOPOLOGY_DIGEST_SCHEMA_VERSION] (u16) encoded in little-endian format src/topology/digest.rs:21.
3. Neuron Count: Total number of neurons in the graph (u64) encoded in little-endian format src/topology/digest.rs:22.
4. Edge Count: Total number of edges in the graph (u64) encoded in little-endian format src/topology/digest.rs:23.
5. Sorted Edge Records: Exactly 23 bytes per logical edge, sorted in strict canonical order (source, target, delay, polarity_tag, weight_bits) src/topology/digest.rs:24-33 where:
   • source: Little-endian u64 representing the CSR row index src/topology/digest.rs:26.
   • target: Little-endian u64 representing the zero-extended NeuronId src/topology/digest.rs:27.
   • weight_bits: Little-endian u32 containing the IEEE 754 bit pattern (f32::to_bits) of the signed CSR weight src/topology/digest.rs:28-29.
   • delay: Little-endian DelayTicks (u16) src/topology/digest.rs:30.
   • polarity_tag: A single byte where 0 = Polarity::Excitatory and 1 = Polarity::Inhibitory src/topology/digest.rs:31-33.

Diagram: Data Flow from SynapticGraph to TopologyDigest

graph TD
    A["SynapticGraph"] -->|calls| B["SynapticGraph::topology_digest"]
    B -->|invokes| C["canonical_edges"]
    C -->|sorts canonical order| D["Edge Records: source, target, delay, polarity, weight_bits"]
    D -->|feeds preimage| E["hash_v1"]
    E -->|uses| F["sha2::Sha256"]
    F -->|produces| G["TopologyDigest"]

Loading

Sources: src/topology/digest.rs:9-35(), src/topology/digest.rs:54-92(), src/topology/digest.rs:190-198(), src/topology/mod.rs:5-22()

---

Float Canonicalization & Invariant Rules

To guarantee cross-platform determinism, floating-point weights are canonicalized via their IEEE 754 binary bit patterns (f32::to_bits) rather than numerical evaluation src/topology/digest.rs:37-43.

Invariant Checks

• NaN and Infinities: Graph construction and deserialization reject NaN and infinite weight values. A valid SynapticGraph never contains unnormalized floating-point values src/topology/digest.rs:39-41
• Signed Zeros: IEEE signed zeros (+0.0 and -0.0) are explicitly preserved and not collapsed. Their distinct bit patterns produce divergent hash preimages and different digests src/topology/digest.rs:41-43 tests/topology_digest.rs:127-137

Sources: src/topology/digest.rs:37-43(), tests/topology_digest.rs:127-149()

---

Key Types, Functions, and Serialization

The topology digest module defines core structs and traits facilitating inspection, parsing, and serialization src/topology/digest.rs:68-189.

Core Structs and Methods

• TopologyDigest: Encapsulates the schema_version (u16) and the raw 32-byte SHA-256 hash ([u8; 32]) src/topology/digest.rs:72-76.
  • TopologyDigest::from_graph(graph: &SynapticGraph): Computes the schema-v1 digest by extracting and sorting edges from the CSR representation src/topology/digest.rs:86-92.
  • TopologyDigest::schema_version(&self) -> u16: Returns the schema version src/topology/digest.rs:95-98.
  • TopologyDigest::algorithm(&self) -> &'static str: Returns "sha256" src/topology/digest.rs:101-104.
  • TopologyDigest::domain(&self) -> &'static str: Returns "synaptic-wiring.topology.digest.v1" src/topology/digest.rs:107-110.
  • TopologyDigest::to_hex(&self) -> String: Encodes the hash bytes into a 64-character lowercase hexadecimal string src/topology/digest.rs:119-122.
• TopologyDigestParseError: Error type returned when parsing invalid printable digest manifests src/topology/digest.rs:170-188.

Parsing and Serialization Workflow

TopologyDigest implements fmt::Display, FromStr, Serialize, and Deserialize to allow transparent embedding in JSON checkpoints and manifests src/topology/digest.rs:125-168.

Diagram: Parsing and Validation Workflow

graph TD
    H["String / JSON Manifest"] -->|parse via FromStr / Deserialize| I["TopologyDigest::from_str"]
    I -->|splits manifest| J["split_manifest"]
    J -->|validates domain and algorithm| K{"Valid Format?"}
    K -->|No| L["TopologyDigestParseError"]
    K -->|Yes| M["hex_decode_sha256"]
    M -->|returns| G["TopologyDigest"]

Loading

Sources: src/topology/digest.rs:68-189(), src/topology/digest.rs:190-198()

---

Determinism Guarantees and Test Suite

The test harness in tests/topology_digest.rs validates insertion-order permutation invariance, golden fixtures, signed zero distinction, and invalid float rejections tests/topology_digest.rs:3-165.

Verification Suites

• Golden Fixtures: Committed hash strings (GOLDEN_EMPTY_0, GOLDEN_EMPTY_3, GOLDEN_SMALL) prevent silent encoder regressions in CI tests/topology_digest.rs:17-25 tests/topology_digest.rs:56-71
• Insertion-Order Permutations: Tests construct graphs with identical logical synapses inserted in all permutations of order, verifying that SynapticGraph and SynapticMesh produce identical digests regardless of input order tests/topology_digest.rs:73-95
• Field Change Detection: Verifies that modifying any endpoint, delay, polarity, or weight bit pattern yields a distinct digest tests/topology_digest.rs:97-124

Sources: tests/topology_digest.rs:1-165()