MIND Core v1 Cookbook

A collection of short, practical recipes demonstrating how to use Core v1 in real workflows.

Recipe 1: Compile and emit the canonical artifact

fn main() -> f64 {
    let x: f64 = 2.0;
    let y: f64 = x * x + 1.0;
    return y;
}

Emission is selected by an --emit-* flag that names its own output path: there is no -o.

mindc scale.mind --verify-only          # type-check only
mindc scale.mind --emit-ir              # human-readable summary
mindc scale.mind --emit-mic3 scale.mic3 # canonical mic@3 binary

Recipe 2: Autodiff of a loss function

Autodiff is feature-gated and entered through a single-output main. The flag pair is --autodiff --emit-grad-ir; a build without the feature fails loud (E4003) rather than skipping the request.

cargo run --features autodiff --bin mindc -- loss.mind --func main --autodiff --emit-grad-ir

Recipe 3: MLIR lowering

Requires the mlir-lowering feature. MLIR text goes to stdout.

mindc scale.mind --func main --emit-mlir

Recipe 4: GPU target: correct error handling

The open-source build ships no GPU backend. Asking for the GPU target is a structured failure, never a panic and never a silent fallback to CPU, and that explicit backend-selection error is itself part of the Core v1 GPU profile, so it is preserved across compatible releases.

mindc main.mind --target gpu

error[backend][E5001]: no backend available for target gpu

Recipe 4b: Emit and verify an evidence chain

1. Emit and verify

   mindc scale.mind --emit-evidence scale.ev
   mindc verify scale.ev

   A plain verify reports.

2. Fail closed

   Add --require-strict-fp, --require-deterministic, or --require-signed to fail closed instead.

3. Inspect

   mindc inspect scale.ev decodes the artifact and prints a structural summary alongside the canonical IR.

See the determinism contract.

Recipe 5: Host embedding via the runtime API

let rt = MindRuntime::new_cpu()?;
let inp = rt.allocate(&tensor_desc_f32(&[2]))?;
rt.write_tensor(inp, &[1.0, 3.0])?;

let out = rt.allocate(&tensor_desc_f32(&[1]))?;
rt.run_op("sum", &[inp], &[out])?;

let result = rt.read_tensor(out)?;

Output: 4.0.

Recipe 6: Running the official conformance suite

CPU baseline:

mindc conformance --profile cpu

GPU profile:

mindc conformance --profile gpu

Recipe 7: Using the pure-MIND standard library (RFC 0005)

std.vec, std.string, std.map, and std.io are bundled into mindc since v0.4.2: a project that says use std.vec resolves with zero external file dependency. The std-surface feature is the shipped default (since v0.7.1); enable cross-module-imports to resolve cross-module use paths:

# cross-module-imports is the only extra gate needed; std-surface ships by default.
cargo run --features "cross-module-imports" --bin mindc -- demo.mind --emit-ir

A minimal demo.mind exercising std.vec:

use std.vec;

fn main() -> i64 {
    let v = vec_new();
    let v = vec_push(v, 10);
    let v = vec_push(v, 20);
    let v = vec_push(v, 30);

    let n = vec_len(v);          // 3
    let x = vec_get(v, 1);       // 20

    vec_free(v);
    return x;
}

Every operation returns the (possibly reallocated) Vec handle: there is no hidden mutation. Modules are resolved last-write-wins, so a user crate MAY define its own std.vec to shadow the bundled one.

See the per-module pages for the full API: std.vec, std.string, std.map, std.io. The seven host-interface core intrinsics they bottom out in (__mind_alloc, __mind_realloc, __mind_free, __mind_load_i64, __mind_store_i64, __mind_read, __mind_write) are ratified by mind-spec v1.0 (stdlib.md).

Beyond std: crypto & protocol primitives

The source tree also carries a pure-MIND cryptography and protocol primitive library: AES-128-GCM, ChaCha20-Poly1305, SHA-256, SHA-512/384, HKDF, X25519, SHA-3/SHAKE (FIPS 202), RSA-PSS, ECDSA-P256, ML-KEM-768 (FIPS 203), the X25519MLKEM768 hybrid key exchange, X.509 parsing and verification, the TLS 1.3 key schedule, record layer, Finished MAC and handshake crypto (verified by RFC 8448 replay), HPACK (RFC 7541), and HTTP/2 framing (RFC 9113). Every primitive is verified against RFC and NIST known-answer tests.