Under the hood

MIR binary format

The canonical byte-level policy contract, its limits, ordering and SHA-256 identity.

MIR means Maelys Intermediate Representation. It is the compact binary contract passed from policy production to enforcement. Humans normally write JSON and inspect JSON; runtimes exchange MIR because it has exactly one valid byte representation for one decision.

Why a binary format exists

Canonical MIR provides:

one stable decision identity independent of JSON whitespace or member order;
strict bounds and fixed-width integer encodings;
rejection of unknown flags, records and trailing bytes;
fast native and WebAssembly decoding;
a small contract that Warden can verify before enforcement.

CODE

policy.json ──compile──► policy.mir ──SHA-256──► decision fingerprint
     │                       │
human source            normative bytes

The formatted JSON returned by inspect is a view, not a second canonical format.

Global rules

all integers are unsigned and big-endian;
maximum document size is 1 MiB;
strings are shortest-form UTF-8 without NUL and have no terminator on the wire;
the decoder accepts only format version 2;
there are no trailing bytes or extension records in v2.

Header: 20 bytes

Offset	Size	Meaning
0	4	ASCII magic `MMIR`
4	2	format version, exactly `2`
6	2	flags, exactly zero
8	4	filesystem record count
12	1	network mode: `1 none`, `2 direct`, `3 mediated`
13	1	process-tree confinement: `0 disabled`, `1 required`
14	2	reserved, exactly zero
16	4	network destination count

Filesystem record

Each record has a 12-byte prefix followed by path_length bytes.

Offset	Size	Meaning
0	1	record kind, exactly `1`
1	1	access: `1 read`, `2 write`, `3 deny`
2	1	root: `1 minimal-runtime`, `2 workspace`, `3 temp`, `4 host`
3	1	scope: `1 exact`, `2 tree`
4	1	missing: `1 error`, `2 skip`
5	3	reserved, exactly zero
8	4	path length
12	N	normalized path bytes

Records are sorted by (root, path, scope, missing, access). Duplicate targets are collapsed with deny > write > read. Access is deny-default and write implies read.

Network destination record

Each destination has an 8-byte prefix followed by host_length ASCII bytes.

Offset	Size	Meaning
0	1	record kind, exactly `2`
1	1	protocol, exactly `1` for TCP
2	2	port in `1..65535`
4	4	hostname length in `1..253`
8	N	canonical lowercase DNS hostname

Destination records exist exactly when the network mode is mediated, which requires at least one. They are sorted by (host, protocol, port) and deduplicated. none and direct require a zero destination count.

Canonicality check

The decoder validates structure and semantic limits, reconstructs the model, re-encodes it and compares the result with the input. Any alternative representation is rejected as non-canonical.

This matters because policy identity is:

CODE

decisionDigest = lowercase_hex(SHA-256(all canonical MIR bytes))

The digest covers the header, every filesystem record and every mediated destination.

Limits

Resource	Limit
encoded document	1 MiB
filesystem rules	4096
bytes in one path string	4096
network destinations	1024
hostname bytes	253

Compatibility boundaries

Product version, public C ABI and MIR format are independent:

product 0.3.0 identifies a release bundle;
Sandbox Policy ABI 3 identifies the C API layout/contract;
MIR format 2 identifies bytes exchanged with consumers.

A future library may change its C ABI while continuing to emit exactly MIR v2. A new MIR format requires an explicit decoder/encoder compatibility decision.