Monomer Reference
All 128 monomers organized by family (64 Core + 64 Extended). Each entry includes the exact signature, domain constraints, return type, edge cases, and usage examples.
All monomers return Value::I64 unless explicitly noted. The only exception is MC_03.DIV8 which returns Value::Tuple([i64, i64]).Argument coercion: When passing i64 to arithmetic/logic monomers, values are narrowed to u8 (low 8 bits). bool values are coerced to u8 (true→1, false→0). Control monomers (MC_24–MC_31) preserve bool as-is.
Family 0: Arithmetic (MC_00 – MC_07)
All arithmetic monomers operate on 8-bit unsigned values with saturation semantics (results clamped to 0–255).
MC_00 — ADD8
Signature: ADD8(a: u8, b: u8) → i64
Saturating addition. Result is min(a + b, 255).
let r = MC_00.ADD8(100, 50); // 150
let s = MC_00.ADD8(200, 100); // 255 (saturates, does NOT overflow)
let z = MC_00.ADD8(0, 0); // 0
Edge cases:
ADD8(255, 1) → 255 (saturation)
ADD8(0, 0) → 0
MC_01 — SUB8
Signature: SUB8(a: u8, b: u8) → i64
Saturating subtraction. Result is max(a - b, 0).
let r = MC_01.SUB8(100, 30); // 70
let z = MC_01.SUB8(5, 10); // 0 (saturates at zero, no underflow)
Edge cases:
SUB8(0, 255) → 0 (saturation)
SUB8(100, 100) → 0
MC_02 — MUL8
Signature: MUL8(a: u8, b: u8) → i64
Saturating multiplication. Result is min(a * b, 255).
let r = MC_02.MUL8(10, 20); // 200
let s = MC_02.MUL8(20, 20); // 255 (saturates)
Edge cases:
MUL8(0, anything) → 0
MUL8(255, 2) → 255 (saturation)
MC_03 — DIV8
Signature: DIV8(a: u8, b: u8) → Tuple(i64, i64)
Integer division with remainder. Returns (quotient, remainder).
let (q, r) = MC_03.DIV8(17, 5); // q=3, r=2
let (q2, r2) = MC_03.DIV8(10, 3); // q2=3, r2=1
Always destructure DIV8. It is the only monomer that returns a tuple.Division by zero causes a runtime error. Always guard:if (b != 0) {
let (q, r) = MC_03.DIV8(a, b);
}
Edge cases:
DIV8(0, 5) → (0, 0)
DIV8(5, 0) → runtime error (use try/catch or guard)
DIV8(255, 1) → (255, 0)
MC_04 — MOD8
Signature: MOD8(a: u8, b: u8) → i64
Modulo operation. Returns a % b.
let r = MC_04.MOD8(17, 5); // 2
let z = MC_04.MOD8(10, 2); // 0
Edge cases:
MOD8(x, 0) → runtime error
MOD8(0, x) → 0
MC_05 — NEG8
Signature: NEG8(a: u8) → i64
Arithmetic negation. Returns 256 - a (two’s complement in u8 range).
let r = MC_05.NEG8(1); // 255
let z = MC_05.NEG8(0); // 0
MC_06 — ABS8
Signature: ABS8(a: u8) → i64
Absolute value. For u8, this is identity (all values are already non-negative).
let r = MC_06.ABS8(42); // 42
MC_07 — POW8
Signature: POW8(base: u8, exp: u8) → i64
Saturating exponentiation. Result is min(base^exp, 255).
let r = MC_07.POW8(2, 7); // 128
let s = MC_07.POW8(2, 8); // 255 (saturates)
let z = MC_07.POW8(0, 5); // 0
let o = MC_07.POW8(5, 0); // 1
Family 1: Logic (MC_08 – MC_15)
Bitwise operations on 8-bit values.
MC_08 — AND8
Signature: AND8(a: u8, b: u8) → i64
Bitwise AND.
let r = MC_08.AND8(0xFF, 0x0F); // 15 (0x0F)
let z = MC_08.AND8(0xAA, 0x55); // 0
MC_09 — OR8
Signature: OR8(a: u8, b: u8) → i64
Bitwise OR.
let r = MC_09.OR8(0xF0, 0x0F); // 255 (0xFF)
MC_10 — XOR8
Signature: XOR8(a: u8, b: u8) → i64
Bitwise XOR.
let r = MC_10.XOR8(0xFF, 0xFF); // 0
let s = MC_10.XOR8(0xAA, 0x55); // 255
MC_11 — NOT8
Signature: NOT8(a: u8) → i64
Bitwise NOT (complement).
let r = MC_11.NOT8(0); // 255
let s = MC_11.NOT8(255); // 0
let t = MC_11.NOT8(0xF0); // 15 (0x0F)
MC_12 — SHL8
Signature: SHL8(a: u8, n: u8) → i64
Left shift by n bits, masked to 8 bits.
let r = MC_12.SHL8(1, 4); // 16
let s = MC_12.SHL8(1, 7); // 128
let z = MC_12.SHL8(1, 8); // 0 (shifted out)
MC_13 — SHR8
Signature: SHR8(a: u8, n: u8) → i64
Right shift by n bits.
let r = MC_13.SHR8(128, 4); // 8
let s = MC_13.SHR8(255, 1); // 127
MC_14 — ROTL8
Signature: ROTL8(a: u8, n: u8) → i64
Rotate left by n bits within 8-bit range.
let r = MC_14.ROTL8(0x80, 1); // 1 (bit wraps around)
MC_15 — ROTR8
Signature: ROTR8(a: u8, n: u8) → i64
Rotate right by n bits within 8-bit range.
let r = MC_15.ROTR8(1, 1); // 128 (bit wraps around)
Family 2: Memory (MC_16 – MC_23)
Array and memory operations.
MC_16 — ALLOC
Signature: ALLOC(size: i64) → array
Creates an array of size elements, all initialized to 0.
let arr = MC_16.ALLOC(10); // [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
MC_17 — LOAD
Signature: LOAD(arr: array, idx: i64) → i64
Reads element at index idx from arr.
let arr = [10, 20, 30];
let val = MC_17.LOAD(arr, 1); // 20
Edge case: LOAD(arr, -1) or index ≥ len → runtime error.
MC_18 — STORE
Signature: STORE(arr: array, idx: i64, val: i64) → array
Returns a new array with element at idx replaced by val.
let arr = [10, 20, 30];
let arr2 = MC_18.STORE(arr, 1, 99); // [10, 99, 30]
// arr is still [10, 20, 30] (value semantics)
MC_19 — LEN_MEM
Signature: LEN_MEM(arr: array) → i64
Returns the length of the array.
MC_20 — COPY
Signature: COPY(arr: array) → array
Returns a copy of the array (identity in PCD since all values are immutable).
MC_21 — SWAP
Signature: SWAP(arr: array, i: i64, j: i64) → array
Returns a new array with elements at indices i and j swapped.
MC_22 — ZERO
Signature: ZERO(arr: array) → array
Returns a new array with all elements set to 0.
MC_23 — FENCE
Signature: FENCE() → i64
Memory barrier / synchronization point. Returns 0. Used to enforce ordering between parallel compositions.
Family 3: Control (MC_24 – MC_31)
Control flow monomers. These preserve bool arguments (no u8 coercion).
MC_24 — IF
Signature: IF(cond: bool, then_val, else_val) → value
Conditional select. Returns then_val if cond is true, else_val otherwise.
let r = MC_24.IF(x > 0, "positive", "non-positive");
In most PCD code, you use the if/else syntax instead of calling MC_24 directly. The planner desugars if/else into MC_24.
MC_25 — CALL
Signature: CALL(fn_ref, arg) → value
Indirect function call. Used internally by the planner for closure dispatch.
MC_26 — LOOP
Signature: LOOP(n: i64, body_fn) → value
Internal loop primitive. The loop(N) syntax desugars to this.
MC_27 — RET
Signature: RET(val) → value
Return from function. The return keyword desugars to this.
MC_28 — JUMP
Signature: JUMP(target: i64) → value
Internal jump. Used by the BIR emitter. Not available in PCD source.
MC_29 — HALT
Signature: HALT(code: i64) → void
Halt execution with exit code. The OUTPUT directive desugars to this.
MC_30 — NOOP
Signature: NOOP() → i64
No operation. Returns 0. Used as placeholder or synchronization point.
MC_31 — YIELD
Signature: YIELD(val) → value
Yields a value in streaming contexts. Used internally for BIR streaming output.
Family 4: I/O (MC_32 – MC_39)
Input/output operations.
MC_32 — READ
Signature: READ(fd: i64, buf: array, n: i64) → i64
Low-level read from file descriptor. Returns bytes read.
MC_33 — WRITE
Signature: WRITE(fd: i64, data: string, len: i64) → i64
Low-level write to file descriptor. Returns bytes written.
let msg = "hello\n";
MC_33.WRITE(1, msg, MC_43.LEN(msg)); // write to stdout (fd=1)
MC_34 — OPEN
Signature: OPEN(path: string, flags: i64) → i64
Open a file. Returns file descriptor. flags: 0=read, 1=write, 2=read+write.
MC_35 — CLOSE
Signature: CLOSE(fd: i64) → i64
Close a file descriptor. Returns 0 on success.
MC_36 — SEEK
Signature: SEEK(fd: i64, offset: i64, whence: i64) → i64
Seek within a file. whence: 0=SET, 1=CUR, 2=END.
MC_37 — FLUSH
Signature: FLUSH(fd: i64) → i64
Flush file descriptor buffers.
MC_38 — STAT
Signature: STAT(path: string) → i64
Returns file size in bytes, or -1 if file doesn’t exist.
MC_39 — SYNC
Signature: SYNC() → i64
Sync all file system buffers. Returns 0.
Family 5: String (MC_40 – MC_47)
String manipulation. All string operations return new strings (immutable).
MC_40 — CONCAT
Signature: CONCAT(a: string, b: string) → string
Concatenate two strings. The + operator on strings is sugar for this.
let r = MC_40.CONCAT("hello", " world"); // "hello world"
MC_41 — SPLIT
Signature: SPLIT(s: string, delim: string) → array
Split string by delimiter. Returns array of substrings.
let parts = MC_41.SPLIT("a,b,c", ","); // ["a", "b", "c"]
Edge cases:
SPLIT("", ",") → [""]
SPLIT("abc", "") → ["a", "b", "c"]
MC_42 — SUBSTR
Signature: SUBSTR(s: string, start: i64, len: i64) → string
Extract substring starting at start with length len.
let sub = MC_42.SUBSTR("hello world", 6, 5); // "world"
Edge cases:
start ≥ string length → empty string
start + len > string length → truncated to available characters
MC_43 — LEN
Signature: LEN(s: string) → i64
Returns character count of string. Also works on arrays.
let n = MC_43.LEN("hello"); // 5
let m = MC_43.LEN([1, 2, 3]); // 3
let z = MC_43.LEN(""); // 0
MC_44 — UPPER
Signature: UPPER(s: string) → string
Convert to uppercase.
let u = MC_44.UPPER("hello"); // "HELLO"
MC_45 — CHAR_AT
Signature: CHAR_AT(s: string, idx: i64) → string
Returns single character at position idx as a string.
let ch = MC_45.CHAR_AT("hello", 0); // "h"
let ch2 = MC_45.CHAR_AT("hello", 4); // "o"
Edge case: Index out of bounds → runtime error. Always check MC_43.LEN first.
MC_46 — LOWER
Signature: LOWER(s: string) → string
Convert to lowercase.
let l = MC_46.LOWER("HELLO"); // "hello"
MC_47 — TRIM
Signature: TRIM(s: string) → string
Remove leading and trailing whitespace.
let t = MC_47.TRIM(" hello "); // "hello"
Family 6: Crypto (MC_48 – MC_55)
Cryptographic operations.
MC_48 — HASH
Signature: HASH(data: string) → string
SHA-256 hash. Returns hex string (64 characters).
let h = MC_48.HASH("hello");
// "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
MC_49 — HMAC
Signature: HMAC(key: string, data: string) → string
HMAC-SHA256. Returns hex string.
let mac = MC_49.HMAC("secret", "message");
MC_50 — ENCRYPT
Signature: ENCRYPT(key: string, plaintext: string) → string
AES-256 encryption. Returns base64-encoded ciphertext.
MC_51 — DECRYPT
Signature: DECRYPT(key: string, ciphertext: string) → string
AES-256 decryption. Input is base64-encoded ciphertext.
MC_52 — SHA256
Signature: SHA256(data: string) → string
Alias for MC_48.HASH. SHA-256 hash returning hex string.
MC_53 — RAND
Signature: RAND(max: i64) → i64
Returns a random integer in [0, max).
Using RAND in a policy circuit will cause Φ_c < 1 because the output is non-deterministic. RAND is intended for non-critical applications only.
MC_54 — SIGN
Signature: SIGN(private_key: string, data: string) → string
Digital signature (Ed25519). Returns hex-encoded signature.
MC_55 — VERIFY
Signature: VERIFY(public_key: string, data: string, signature: string) → i64
Verify digital signature. Returns 1 if valid, 0 if invalid.
let valid = MC_55.VERIFY(pub_key, message, sig);
if (valid == 1) {
// signature is valid
}
Family 7: System (MC_56 – MC_63)
System operations and I/O.
MC_56 — READ (file)
Signature: READ(path: string) → string
Read entire file contents as string.
let content = MC_56.READ("input.txt");
let stdin = MC_56.READ("/dev/stdin");
Edge case: File not found → runtime error (use try/catch).
MC_57 — WRITE_FILE
Signature: WRITE_FILE(path: string, data: string) → i64
Write string to file. Creates or overwrites. Returns 0 on success.
MC_57.WRITE_FILE("output.txt", "hello world");
MC_58 — WRITE (stdout)
Signature: WRITE(text: string) → i64
Write to stdout. Returns bytes written.
let _ = MC_58.WRITE("Hello!\n");
MC_59 — READ_LINE
Signature: READ_LINE() → string
Read one line from stdin (without trailing newline).
let line = MC_59.READ_LINE();
MC_60 — EXEC
Signature: EXEC(command: string) → string
Execute shell command. Returns stdout output.
EXEC is powerful and potentially dangerous. Policy circuits should BLOCK any use of EXEC from untrusted agents.
MC_61 — KILL
Signature: KILL(pid: i64, signal: i64) → i64
Send signal to process. Returns 0 on success.
MC_62 — SIGNAL
Signature: SIGNAL(sig: i64) → i64
Register or handle a signal. Returns previous handler status.
MC_63 — ENV
Signature: ENV(name: string) → string
Read environment variable. Returns empty string if not set.
let home = MC_63.ENV("HOME");
let arg1 = MC_63.ENV("ARGV_1"); // argv[1] in native ELF
let arg2 = MC_63.ENV("ARGV_2"); // argv[2] in native ELF
In native ELF binaries, MC_63.ENV("ARGV_1") reads argv[1] from process arguments, not environment variables. ARGV_2 reads argv[2], etc. In non-native backends, it reads the actual environment variable.
Quick Reference Table
| MC | Name | Signature | Returns | Family |
|---|
| 00 | ADD8 | (u8, u8) | i64 | Arithmetic |
| 01 | SUB8 | (u8, u8) | i64 | Arithmetic |
| 02 | MUL8 | (u8, u8) | i64 | Arithmetic |
| 03 | DIV8 | (u8, u8) | Tuple(i64, i64) | Arithmetic |
| 04 | MOD8 | (u8, u8) | i64 | Arithmetic |
| 05 | NEG8 | (u8) | i64 | Arithmetic |
| 06 | ABS8 | (u8) | i64 | Arithmetic |
| 07 | POW8 | (u8, u8) | i64 | Arithmetic |
| 08 | AND8 | (u8, u8) | i64 | Logic |
| 09 | OR8 | (u8, u8) | i64 | Logic |
| 10 | XOR8 | (u8, u8) | i64 | Logic |
| 11 | NOT8 | (u8) | i64 | Logic |
| 12 | SHL8 | (u8, u8) | i64 | Logic |
| 13 | SHR8 | (u8, u8) | i64 | Logic |
| 14 | ROTL8 | (u8, u8) | i64 | Logic |
| 15 | ROTR8 | (u8, u8) | i64 | Logic |
| 16 | ALLOC | (i64) | array | Memory |
| 17 | LOAD | (array, i64) | i64 | Memory |
| 18 | STORE | (array, i64, i64) | array | Memory |
| 19 | LEN_MEM | (array) | i64 | Memory |
| 20 | COPY | (array) | array | Memory |
| 21 | SWAP | (array, i64, i64) | array | Memory |
| 22 | ZERO | (array) | array | Memory |
| 23 | FENCE | () | i64 | Memory |
| 24 | IF | (bool, val, val) | value | Control |
| 25 | CALL | (fn, arg) | value | Control |
| 26 | LOOP | (i64, fn) | value | Control |
| 27 | RET | (val) | value | Control |
| 28 | JUMP | (i64) | value | Control |
| 29 | HALT | (i64) | void | Control |
| 30 | NOOP | () | i64 | Control |
| 31 | YIELD | (val) | value | Control |
| 32 | READ | (i64, array, i64) | i64 | I/O |
| 33 | WRITE | (i64, string, i64) | i64 | I/O |
| 34 | OPEN | (string, i64) | i64 | I/O |
| 35 | CLOSE | (i64) | i64 | I/O |
| 36 | SEEK | (i64, i64, i64) | i64 | I/O |
| 37 | FLUSH | (i64) | i64 | I/O |
| 38 | STAT | (string) | i64 | I/O |
| 39 | SYNC | () | i64 | I/O |
| 40 | CONCAT | (string, string) | string | String |
| 41 | SPLIT | (string, string) | array | String |
| 42 | SUBSTR | (string, i64, i64) | string | String |
| 43 | LEN | (string|array) | i64 | String |
| 44 | UPPER | (string) | string | String |
| 45 | CHAR_AT | (string, i64) | string | String |
| 46 | LOWER | (string) | string | String |
| 47 | TRIM | (string) | string | String |
| 48 | HASH | (string) | string | Crypto |
| 49 | HMAC | (string, string) | string | Crypto |
| 50 | ENCRYPT | (string, string) | string | Crypto |
| 51 | DECRYPT | (string, string) | string | Crypto |
| 52 | SHA256 | (string) | string | Crypto |
| 53 | RAND | (i64) | i64 | Crypto |
| 54 | SIGN | (string, string) | string | Crypto |
| 55 | VERIFY | (string, string, string) | i64 | Crypto |
| 56 | READ | (string) | string | System |
| 57 | WRITE_FILE | (string, string) | i64 | System |
| 58 | WRITE | (string) | i64 | System |
| 59 | READ_LINE | () | string | System |
| 60 | EXEC | (string) | string | System |
| 61 | KILL | (i64, i64) | i64 | System |
| 62 | SIGNAL | (i64) | i64 | System |
| 63 | ENV | (string) | string | System |
Extended Monomers (MC_64 – MC_127)
Extended monomers operate under CONTRACT closure (Φ_c = CONTRACT), not the Coq-proven Φ_c = 1 of Core monomers. They are available starting in v4.0.0-beta.2. Programs using Extended monomers compile with --open and receive the BRIK-64 Open badge.
Family 8: Float64 (MC_64 – MC_71)
IEEE 754 double-precision floating-point operations.
| MC | Name | Signature | Returns |
|---|
| 64 | FADD | (f64, f64) | f64 |
| 65 | FSUB | (f64, f64) | f64 |
| 66 | FMUL | (f64, f64) | f64 |
| 67 | FDIV | (f64, f64) | f64 |
| 68 | FABS | (f64) | f64 |
| 69 | FNEG | (f64) | f64 |
| 70 | FSQRT | (f64) | f64 |
| 71 | FMOD | (f64, f64) | f64 |
// Float64 example
PC circle_area {
let radius = MC_64.FADD(5.0, 0.0);
let pi = MC_64.FADD(3.14159, 0.0);
let r_squared = MC_66.FMUL(radius, radius);
let area = MC_66.FMUL(pi, r_squared);
}
Family 9: Math (MC_72 – MC_79)
Transcendental and mathematical functions.
| MC | Name | Signature | Returns |
|---|
| 72 | SIN | (f64) | f64 |
| 73 | COS | (f64) | f64 |
| 74 | TAN | (f64) | f64 |
| 75 | EXP | (f64) | f64 |
| 76 | LN | (f64) | f64 |
| 77 | LOG2 | (f64) | f64 |
| 78 | POW | (f64, f64) | f64 |
| 79 | CEIL | (f64) | f64 |
// Math example
PC trig_demo {
let angle = MC_64.FADD(1.5708, 0.0);
let sine = MC_72.SIN(angle);
let cosine = MC_73.COS(angle);
let power = MC_78.POW(2.0, 10.0);
let rounded = MC_79.CEIL(3.7);
}
Family 10: Network (MC_80 – MC_87)
| MC | Name | Signature | Returns |
|---|
| 80 | TCP_CONN | (string, i64) | i64 |
| 81 | TCP_SEND | (i64, string) | i64 |
| 82 | TCP_RECV | (i64, i64) | string |
| 83 | UDP_SEND | (string, i64, string) | i64 |
| 84 | DNS | (string) | string |
| 85 | HTTP_GET | (string) | string |
| 86 | HTTP_POST | (string, string) | string |
| 87 | TLS | (i64) | i64 |
Family 11: Graphics (MC_88 – MC_95)
| MC | Name | Signature | Returns |
|---|
| 88 | FB_INIT | (i64, i64) | i64 |
| 89 | FB_PIXEL | (i64, i64, i64) | i64 |
| 90 | FB_LINE | (i64, i64, i64, i64, i64) | i64 |
| 91 | FB_RECT | (i64, i64, i64, i64, i64) | i64 |
| 92 | FB_BLIT | (array, i64, i64) | i64 |
| 93 | FB_FLIP | () | i64 |
| 94 | FB_TEXT | (i64, i64, string) | i64 |
| 95 | FB_CLOSE | () | i64 |
Family 12: Audio (MC_96 – MC_103)
| MC | Name | Signature | Returns |
|---|
| 96 | AU_INIT | (i64, i64) | i64 |
| 97 | AU_PLAY | (string) | i64 |
| 98 | AU_STOP | () | i64 |
| 99 | AU_MIX | (array) | i64 |
| 100 | AU_VOL | (i64) | i64 |
| 101 | AU_SEEK | (i64) | i64 |
| 102 | AU_STREAM | (string) | i64 |
| 103 | AU_CLOSE | () | i64 |
Family 13: Filesystem+ (MC_104 – MC_111)
| MC | Name | Signature | Returns |
|---|
| 104 | DIR_LIST | (string) | array |
| 105 | DIR_CREATE | (string) | i64 |
| 106 | DIR_DELETE | (string) | i64 |
| 107 | CHMOD | (string, i64) | i64 |
| 108 | CHOWN | (string, i64) | i64 |
| 109 | LINK | (string, string) | i64 |
| 110 | WATCH | (string) | i64 |
| 111 | TEMP | () | string |
Family 14: Concurrency (MC_112 – MC_119)
| MC | Name | Signature | Returns |
|---|
| 112 | SPAWN | (closure) | i64 |
| 113 | JOIN | (i64) | value |
| 114 | CHAN_NEW | () | i64 |
| 115 | CHAN_SEND | (i64, value) | i64 |
| 116 | CHAN_RECV | (i64) | value |
| 117 | MUTEX | () | i64 |
| 118 | ATOMIC | (i64, i64) | i64 |
| 119 | YIELD | () | i64 |
Family 15: Interop/FFI (MC_120 – MC_127)
| MC | Name | Signature | Returns |
|---|
| 120 | FFI_LOAD | (string) | i64 |
| 121 | FFI_CALL | (i64, string, array) | value |
| 122 | FFI_ALLOC | (i64) | i64 |
| 123 | FFI_FREE | (i64) | i64 |
| 124 | WASM_EXEC | (string, string, array) | value |
| 125 | PY_EVAL | (string) | value |
| 126 | JSON_PARSE | (string) | value |
| 127 | JSON_EMIT | (value) | string |