cross-repo: wire axon-encoder / engram-parser exporters to nir-rs (org interop — not crate 0.5.0)

[rmems]

Summary

Org interop / adoption (not a nir-rs crate release): wire axon-encoder and engram-parser exporters so to_nir() builds graphs via nir-rs and writes .nir through the shared write path (no ad-hoc HDF5).

Versioning

• Depend on crate 0.4.x. Completing this issue does not imply tag/publish nir-rs 0.5.0.
• Crate version = what the library is for any consumer. This ticket = Limen producers adopting it.
• Library gaps found while exporting → fix in nir-rs as 0.4.y (or a deliberate library minor if the API truly grows for everyone).

Boundary

Producers map domain params → nir_rs::NirGraph; nir-rs owns HDF5. Neither consumer depends on the hdf5 crate.

axon-encoder / engram-parser
        │  to_nir()
        ▼
     nir-rs write → .nir
        │
        ▼
  silicon-bridge (nir-rs read → FPGA)

Dependency

[dependencies]
nir-rs = { git = "https://github.com/Limen-Neural/nir-rs", branch = "main", optional = true }
# Prefer pin by rev/tag once tagged, e.g. tag = "v0.4.0"

[features]
nir = ["dep:nir-rs"]

engram-parser: feature-gate is mandatory to keep zero-dep default.

Encoder API sketch

pub trait ToNir {
    fn to_nir(&self, channels: usize) -> Result<nir_rs::NirGraph, NirExportError>;
}

impl RateEncoder {
    pub fn write_nir(&self, path: impl AsRef<std::path::Path>, channels: usize) -> Result<(), NirExportError> {
        nir_rs::write(path, &self.to_nir(channels)?)
    }
}

Export is a static parameter graph, not a spike stream dump.

engram-parser

to_nir on a conversion helper (not on RawTensor); map weights → Linear/Affine, dynamics → LIF/CubaLIF + Scale (wire names, not marketing aliases).

Ordering

• Library prerequisites: done (crate 0.2–0.4 on main)
• Graph unit tests: unblocked
• Write/load integration: unblocked
• Primary code paths: axon-encoder + engram-parser repos

Related

• axon-encoder#43 · LIM-774
• engram-parser#29 · LIM-775
• Linear: https://linear.app/rpd-34/issue/LIM-831
• silicon-bridge wiring: cross-repo: wire silicon-bridge NIR I/O to depend on nir-rs (org interop — not crate 0.5.0) #15 · LIM-835
• Org epic: LIM-776 · Parent: Epic: pure-Rust NIR (reusable crate + org adoption) #1 / LIM-822

---

Updated 2026-08-06 by Grok Build: Grok 4.5 (medium) (xAI) via GitHub MCP — clarified org interop vs crate semver; library prereqs unblocked.

[linear-code]

LIM-831

[rmems]

Research: axon-encoder / engram-parser → nir-rs exporters (v0.5)

Evidence-based wiring plan. Full write-up: session artifact swarm/research/v0.5-interop.md.

Boundary

Producers build in-memory graphs with nir-rs types and call nir_rs::write. Neither crate should depend on the hdf5 crate.

axon-encoder / engram-parser
        │  to_nir()  (map domain params → NirGraph)
        ▼
     nir-rs write → .nir (HDF5)
        │
        ▼
  silicon-bridge (nir-rs read → Q8.8 / .mem)

Dependency pattern

[dependencies]
nir-rs = { git = "https://github.com/Limen-Neural/nir-rs", branch = "main", optional = true }

[features]
nir = ["dep:nir-rs"]

engram-parser: feature-gate is mandatory so default remains zero-dependency GGUF parse.

Minimal API surface needed from nir-rs

• Graph + 17 node structs (v0.2)
• write path (v0.3 feat: HDF5 write path (graph → .nir) #10); producers also need read for round-trip tests (feat: HDF5 read path (.nir → graph) #9)
• Structured errors (v0.2 feat: structured errors (unknown nodes, version skew, I/O) #12)

Encoder to_nir() sketch

// axon-encoder, feature = "nir"
pub trait ToNir {
    fn to_nir(&self, channels: usize) -> Result<nir_rs::NirGraph, NirExportError>;
}

impl ToNir for RateEncoder { /* Input → Scale/Linear → Threshold? → Output */ }

impl RateEncoder {
    pub fn write_nir(&self, path: impl AsRef<Path>, channels: usize) -> Result<()> {
        nir_rs::write(path, &self.to_nir(channels)?)
    }
}

Encoder	NIR nodes (from axon-encoder#43)
Rate	Input, Scale/Linear, Threshold
Population	Input, Linear, LIF/Threshold
Temporal / Latency / Phase	Input, Delay?, Threshold
Predictive	Input, Linear/Affine, LIF
Neuromod gains	Scale + Affine

Semantics: to_nir() exports a static parameter graph, not a spike event dump.

engram-parser sketch

• Do not put NIR types on RawTensor.
• Prefer to_nir on a conversion helper / future extracted-SNN type under feature nir.
• Map dequantized weights → Linear/Affine; dynamics → LIF/CurrLIF + Scale (engram-parser#29).

Ordering

Work	Gate
Graph construction unit tests	v0.2 Core IR
Write .nir + load in silicon-bridge	v0.3 HDF5 I/O (hard)
This issue complete	After #9/#10/#11 green

Block consumer wiring until v0.3 I/O exists.

Cross-links

• axon-encoder#43 / LIM-774
• engram-parser#29 / LIM-775
• Linear: LIM-831
• silicon-bridge consumer: cross-repo: wire silicon-bridge NIR I/O to depend on nir-rs (org interop — not crate 0.5.0) #15 / LIM-835
• Org epic: LIM-776

[rmems]

Research notes (swarm 2026-07-22)

Refresh after Core IR (v0.2) landed on Main @ ea8c338 (package 0.2.0). Full write-up: swarm/research/2026-07-22-refresh-v0.5.md.

What changed vs 2026-07-21

Topic	Now
Graph construction	Unblocked — build real NirGraph + NirNode in unit tests
File export / load	Still nir_rs::io::write / read stubs until v0.3 (#10/#9)
Wire names	Use exact strings only: CubaLIF / CubaLI / Conv1d / Conv2d / I / SumPool2d / AvgPool2d
Prior doc slip	Prefer CubaLif, not CurrLIF, in engram mapping notes
Git branch	Main (capital M); crates.io not published

axon-encoder (producer)

Local tree still has no NIR deps. Encoders present: Rate, Population, Temporal, Latency, Phase, Predictive, Delta, Derivative, EmbeddingRate.

// feature = "nir" — sketch, still valid
use nir_rs::{NirGraph, NirNode};
use nir_rs::nodes::{Input, Output, Scale, Linear, Lif, Threshold, Delay};

pub trait ToNir {
    fn to_nir(&self, channels: usize) -> Result<NirGraph, NirExportError>;
}

// After v0.3:
// nir_rs::io::write(path, &self.to_nir(channels)?)

Exhaustiveness: producers construct a subset of variants — no full match required. Risk is field-shape churn on structs they build, not new enum arms. Call validate_structure() in tests.

Semantics: static parameter graph, not a spike-event dump.

engram-parser (producer)

• Optional nir feature is mandatory for packaging so default stays zero-dep GGUF.
• to_nir on conversion helper / extracted-SNN type — not on RawTensor.
• Weights → Linear/Affine; dynamics → Lif/CubaLif + Scale.

Dependency (corrected)

[dependencies]
nir-rs = { git = "https://github.com/Limen-Neural/nir-rs", branch = "Main", optional = true }

[features]
nir = ["dep:nir-rs"]

Prefer rev = "ea8c338…" for CI stability. Do not depend on the hdf5 crate in either consumer.

Ordering

Work	Gate
to_nir() graph unit tests	Now (v0.2)
Write .nir + io::read round-trip	v0.3 #10/#9
Load in silicon-bridge → .mem	After #15 mapping + v0.3
Close this issue	After #9/#10/#11 green + consumer AC updated

Linear: LIM-831 already blockedBy LIM-827 / LIM-833.

Consumer trackers still stale

• axon-encoder#43 / LIM-774 still say “use the hdf5 crate”
• engram-parser#29 / LIM-775 should target nir-rs only

Cross-links

• Linear: LIM-831
• silicon-bridge wiring: cross-repo: wire silicon-bridge NIR I/O to depend on nir-rs (org interop — not crate 0.5.0) #15 / LIM-835
• v0.3: feat: HDF5 read path (.nir → graph) #9 / feat: HDF5 write path (graph → .nir) #10 / test: round-trip fidelity + NIR fixtures #11