Minerva Secure MCU Export

Inside this repository, use the Minerva module directly:

For a published application, use the SKaiNET BOM and the Minerva artifact:

Configure libminerva through MinervaExportOptions or environment variables used by the maintained JVM sample:

MINERVA_KEY_FILE and the generated include/secrets.example.h are placeholders for integration. Do not commit real device keys or derived secrets. For host verification against libminerva, MINERVA_HOST_INCLUDE_DIRS can point at an untracked directory that contains a host-only secrets.h defining MNV_DEVICE_KEY.

model.npz stores activation names as scalar NumPy Unicode arrays (relu, sigmoid, tanh, or linear) because the current libminerva compiler reads layer_i_act as a string.

The public entry point is MinervaExportFacade. The facade accepts an already-built ComputeGraph, or it can record a representative forward pass for compatible SKaiNET models.

If compilerScript is missing, export still performs compatibility checks, Minerva lowering, and NPZ schema creation before returning a typed compiler prerequisite failure. That makes local validation possible before libminerva is installed.

A successful export writes a project directory under outputDir/projectName:

The manifest records the target, quantization, libminerva root, compiler command summary, NPZ schema version, layer count, reference fixture paths, generated files, and SHA-256 fingerprints for generated artifacts. secrets.example.h contains placeholder values only.

manifest.json is the release handoff record for Minerva export. It includes a generatedFileSha256 object keyed by generated project path, covering artifacts such as generated/model.npz, generated/weights.c, include/weights.h, host fixtures, host harness sources, and firmware examples.

Use those fingerprints to audit that the source model, Kotlin export, libminerva compiler output, host verification fixtures, and firmware handoff all refer to the same generated bundle. Compiler key-file arguments are redacted from the command summary, and real device key material must stay outside the generated bundle.

For imported or trained models, keep the original source artifact or training metadata next to the manifest in your release evidence. The Minerva manifest fingerprints the generated Minerva bundle; it is not a replacement for source-model provenance.

Host verification always checks the package structure, generated weight files, model.npz integrity, and placeholder secret hygiene. It also writes and validates deterministic host/reference-input.txt and host/reference-output.txt fixtures.

The generated host harness has a stable adapter ABI:

host/runtime_adapter.example.c implements that ABI against the current libminerva runtime symbols: mnv_init, mnv_seed_prng, mnv_run_with_model, and mnv_verify_output_with_key. The adapter keeps compile-time switches for runtimes that expose the older mnv_run / mnv_verify_output names. It converts SKaiNET’s normalized float fixtures to libminerva Q8 activation buffers and converts Q8 outputs back to floats for parity comparison.

Copy the adapter outside the generated bundle when product-specific scaling or entropy seeding needs local edits, then point CMake at the copied source. This keeps the generated host harness stable while leaving runtime policy in one reviewable adapter file.

Use these metadata keys to opt into external host checks:

RUN_CMAKE_BUILD configures and builds host/CMakeLists.txt. RUN_CTEST runs the packaged CTest smoke test. HOST_OUTPUT_PATH lets a real host run write comma- or whitespace-separated float outputs that are compared with the SKaiNET reference output using hostVerificationTolerance.

HOST_OUTPUT_PATH is optional when the host run writes the default host/observed-output.txt file. The generated CMake can build a checkout-style libminerva runtime from runtimeRoot when that directory contains CMakeLists.txt. Include, library directory, and library values are passed to CMake as semicolon-separated lists, matching CMake list syntax; use HOST_LIBRARY_DIRS and HOST_LIBRARIES only when linking an already-built runtime.

Local CI recipe:

The Gradle minervaHostVerification task is gated. It only runs when minerva.hostVerification.enabled=true, minerva.runtimeRoot, and minerva.compilerScript are present. When enabled, it runs jvmTest and runMinervaTinyMlpSample with MINERVA_RUN_CMAKE=true and MINERVA_RUN_CTEST=true by default. Override -Pminerva.hostVerification.runCmakeBuild=false or -Pminerva.hostVerification.runCTest=false only for runtime bring-up. The default parity tolerance remains 1e-3; the real checkout profile sets MINERVA_HOST_TOLERANCE=1.0 by default because current libminerva Q8 host outputs are useful as a runtime smoke proof but are not yet numerically close to the SKaiNET float reference.

For a local checkout proof, the helper below creates an untracked key, calibration archive, host-only secrets.h, and host-only AVR pgmspace.h compatibility shim under build/minerva-real-runtime-profile, then runs the gated verification task with CMake and CTest enabled:

The generated firmware example intentionally contains integration placeholders. Use the host adapter as the reference for the pinned libminerva public API, then move product-specific entropy seeding, input scaling, and secret provisioning into private firmware code before flashing.

Before flashing firmware:

Minerva export starts from a supported SKaiNET ComputeGraph. That graph can come from the Kotlin DSL, a traced forward pass, a hand-built graph, an imported model, or any other path that preserves the phase-one static MLP contract.

For ONNX inputs, use the existing ONNX loader path as an inspection step before constructing a compatible SKaiNET graph. The first phase does not include a general ONNX-to-Minerva importer; unsupported imported operators should be rejected before export. After export, keep manifest.json with the source-model artifact or training metadata so reviewers can compare provenance with the generated Minerva bundle fingerprints.

The maintained sample is sk.ainet.compile.minerva.examples.MinervaTinyMlpExportSample in the Minerva module. It builds a tiny two-layer MLP, reads Minerva paths from environment variables, invokes the export facade, and prints bundle and verification status.

Run the sample after configuring libminerva:

Run the richer secure MCU examples:

sensor-classifier mirrors libminerva’s ATmega sensor-classification shape with eight input features and four output classes. safety-guard shows a smaller health-decision classifier with three output classes. Both examples are dry-run friendly and switch to real compiler execution when the normal MINERVA_* runtime settings are present.

Without MINERVA_COMPILER_SCRIPT, the sample task runs a dry validation through compatibility, lowering, and in-memory NPZ generation. Configure the runtime with Gradle properties or matching environment variables to run the real compiler and host verification:

For CI, prefer the gated verification profile:

The sample graph is covered by MinervaTinyMlpExportSampleTest, which validates compatibility, lowering, and NPZ generation without requiring real device keys.