added ISA

Author: t81dev

MASTER_ISA.md

@@ -44,6 +44,18 @@ focuses on instructions whose semantics *literally require* a three-valued persp
   | two or more `0` values           | 0      |
   | two or more `−1` values          | −1     |
   | `(-1, 0, +1)` (all distinct)     | 0      |
+- **TEQUIV** – Tritwise equivalence (balanced ternary XNOR). Returns +1 if both trits match and are non-zero, 0 if either trit is 0, and −1 otherwise. This provides a symmetric similarity test without losing unknown propagation (unlike chaining binary XNOR).
+  | input ↓ \ input → | -1 | 0 | +1 |
+  |------------------|----|---|----|
+  | -1               | +1 | 0 | -1 |
+  | 0                | 0  | 0 | 0  |
+  | +1               | -1 | 0 | +1 |
+- **TXOR** – Tritwise exclusive-or (a + b mod 3). Outputs 0 when inputs match, ±1 when they differ, and keeps unknowns as neutral. Ideal for ternary hashing/diff operations where sign matters but zero must stay neutral.
+  | input ↓ \ input → | -1 | 0 | +1 |
+  |------------------|----|---|----|
+  | -1               | 0  | -1 | +1 |
+  | 0                | -1 | 0  | +1 |
+  | +1               | +1 | -1 | 0  |
 
 ### 2. Control flow that uses three-way decisions
 
@@ -54,6 +66,9 @@ focuses on instructions whose semantics *literally require* a three-valued persp
 - **TSIGNJMP** – Jump based on the sign trit of a register (positive/zero/negative), letting
   late-stage code skip redundant compares or flags. A binary design must inspect zero and sign
   flags separately, but balanced ternary exposes the sign trit directly.
+- **TMUX** – Three-way data multiplexer controlled by a ternary trit. Chooses operand A for −1,
+  B for 0, and C for +1, mirroring `TBRANCH`’s select logic but for data paths. This avoids chained
+  binary muxes in ternary state machines and pairs with the async control arbiter metadata.
 
 ### 3. Symmetric arithmetic helpers for AI / DSP workloads
 
@@ -71,6 +86,7 @@ focuses on instructions whose semantics *literally require* a three-valued persp
   AI weights. Binary quantization typically lands at {0,1} or 8-bit ints; ternary quantization
   captures more information with fewer bits. This helper is critical for runtime math that
   prepares data for `TMIN/TMAX`-style activations.
+- **TNET** – Net trit sum: emit the count of `+1` values minus the count of `−1` values within a register. Balanced ternary makes this reduction carry-free and perfectly symmetric, serving as a lightweight “balance” check for ternary neural networks or error-detecting schemes.
 
 ### 4. Memory / conversion utilities beyond standard packing
 

SPECIFICATION.md

@@ -151,6 +151,7 @@ intended to be exposed via the GCC plugin and helper ABI.
 - tand: per-trit min(a, b)
 - tor: per-trit max(a, b)
 - txor: ternary XOR (ISA-defined and stable)
+- tequiv: tritwise equivalence (Kleene XNOR) that propagates unknowns and returns +1 only when the inputs match.
 - tmin: per-trit minimum (alias of tand, optional)
 - tmax: per-trit maximum (alias of tor, optional)
 
@@ -165,12 +166,14 @@ intended to be exposed via the GCC plugin and helper ABI.
 - tmuladd: ternary multiply-add with symmetric rounding (A×B + C)
 - tround: drop least-significant trits with symmetric rounding bias
 - tabs: absolute value (optional helper if not encoded in hardware)
+- tnet: net trit sum (count(+1) − count(−1)) for fast majority/balance checks.
 
 ### Ternary Comparison and Condition Ops
 
 - tcmp: ternary compare returning {-1, 0, +1}
 - tsel: select with ternary condition (cond != 0)
 - tcmpz: compare against zero, returning {-1, 0, +1} (optional shortcut)
+- tmux: data multiplexer that selects among three operands based on a ternary control trit (-1,0,+1).
 
 ### Trit Shifts and Rotates
 

include/ternary_runtime.h

@@ -83,6 +83,10 @@ t32_t __ternary_tmuladd_t32(t32_t a, t32_t b, t32_t c);
 t32_t __ternary_tround_t32(t32_t a, unsigned drop);
 t32_t __ternary_tnormalize_t32(t32_t a);
 t32_t __ternary_tbias_t32(t32_t a, int64_t bias);
+t32_t __ternary_tmux_t32(t32_t sel, t32_t neg, t32_t zero, t32_t pos);
+t32_t __ternary_tequiv_t32(t32_t a, t32_t b);
+t32_t __ternary_txor_t32(t32_t a, t32_t b);
+int __ternary_tnet_t32(t32_t a);
 t32_t __ternary_shl_t32(t32_t a, int shift);
 t32_t __ternary_shr_t32(t32_t a, int shift);
 t32_t __ternary_rol_t32(t32_t a, int shift);
@@ -122,6 +126,10 @@ t64_t __ternary_tmuladd_t64(t64_t a, t64_t b, t64_t c);
 t64_t __ternary_tround_t64(t64_t a, unsigned drop);
 t64_t __ternary_tnormalize_t64(t64_t a);
 t64_t __ternary_tbias_t64(t64_t a, int64_t bias);
+t64_t __ternary_tmux_t64(t64_t sel, t64_t neg, t64_t zero, t64_t pos);
+t64_t __ternary_tequiv_t64(t64_t a, t64_t b);
+t64_t __ternary_txor_t64(t64_t a, t64_t b);
+int __ternary_tnet_t64(t64_t a);
 t64_t __ternary_shl_t64(t64_t a, int shift);
 t64_t __ternary_shr_t64(t64_t a, int shift);
 t64_t __ternary_rol_t64(t64_t a, int shift);

runtime/ternary_runtime.c

@@ -370,6 +370,72 @@ static uint64_t ternary_quantize_vector(float value, float threshold, unsigned t
     return result;
 }
 
+static int ternary_tequiv_trit(int a, int b)
+{
+    if (a == 0 || b == 0)
+        return 0;
+    return (a == b) ? 1 : -1;
+}
+
+static uint64_t ternary_tequiv_u64(uint64_t a, uint64_t b, unsigned trit_count)
+{
+    uint64_t out = 0;
+    for (unsigned i = 0; i < trit_count; ++i) {
+        int trit = ternary_tequiv_trit(ternary_get_trit(a, i), ternary_get_trit(b, i));
+        out = ternary_set_trit(out, i, trit);
+    }
+    return out;
+}
+
+static int ternary_txor_trit(int a, int b)
+{
+    int sum = a + b;
+    int mod = ((sum % 3) + 3) % 3;
+    if (mod == 0)
+        return 0;
+    if (mod == 1)
+        return 1;
+    return -1;
+}
+
+static uint64_t ternary_txor_u64(uint64_t a, uint64_t b, unsigned trit_count)
+{
+    uint64_t out = 0;
+    for (unsigned i = 0; i < trit_count; ++i) {
+        int trit = ternary_txor_trit(ternary_get_trit(a, i), ternary_get_trit(b, i));
+        out = ternary_set_trit(out, i, trit);
+    }
+    return out;
+}
+
+static int64_t ternary_tnet_u64(uint64_t packed, unsigned trit_count)
+{
+    int64_t net = 0;
+    for (unsigned i = 0; i < trit_count; ++i)
+        net += ternary_get_trit(packed, i);
+    return net;
+}
+
+static t32_t ternary_tmux_u32(t32_t sel, t32_t neg, t32_t zero, t32_t pos)
+{
+    int64_t cond = ternary_decode((uint64_t)sel, 32);
+    if (cond < 0)
+        return neg;
+    if (cond > 0)
+        return pos;
+    return zero;
+}
+
+static t64_t ternary_tmux_u64(t64_t sel, t64_t neg, t64_t zero, t64_t pos)
+{
+    int64_t cond = ternary_decode_u128((unsigned __int128)sel, 64);
+    if (cond < 0)
+        return neg;
+    if (cond > 0)
+        return pos;
+    return zero;
+}
+
 static unsigned __int128 ternary_majority_u128(unsigned __int128 a, unsigned __int128 b,
                                                unsigned __int128 c, unsigned trit_count)
 {
@@ -1003,6 +1069,26 @@ t32_t __ternary_tbias_t32(t32_t a, int64_t bias)
     return (t32_t)ternary_tbias_u64((uint64_t)a, 32, bias);
 }
 
+t32_t __ternary_tequiv_t32(t32_t a, t32_t b)
+{
+    return (t32_t)ternary_tequiv_u64((uint64_t)a, (uint64_t)b, 32);
+}
+
+t32_t __ternary_txor_t32(t32_t a, t32_t b)
+{
+    return (t32_t)ternary_txor_u64((uint64_t)a, (uint64_t)b, 32);
+}
+
+int __ternary_tnet_t32(t32_t a)
+{
+    return (int)ternary_tnet_u64((uint64_t)a, 32);
+}
+
+t32_t __ternary_tmux_t32(t32_t sel, t32_t neg, t32_t zero, t32_t pos)
+{
+    return ternary_tmux_u32(sel, neg, zero, pos);
+}
+
 t64_t __ternary_tmin_t64(t64_t a, t64_t b)
 {
     return (t64_t)ternary_tritwise_op_u128((unsigned __int128)a, (unsigned __int128)b, 64, 0);
@@ -1061,6 +1147,26 @@ t64_t __ternary_tbias_t64(t64_t a, int64_t bias)
     return (t64_t)ternary_tbias_u128((unsigned __int128)a, 64, bias);
 }
 
+t64_t __ternary_tequiv_t64(t64_t a, t64_t b)
+{
+    return (t64_t)ternary_tequiv_u64((unsigned __int128)a, (unsigned __int128)b, 64);
+}
+
+t64_t __ternary_txor_t64(t64_t a, t64_t b)
+{
+    return (t64_t)ternary_txor_u64((unsigned __int128)a, (unsigned __int128)b, 64);
+}
+
+int __ternary_tnet_t64(t64_t a)
+{
+    return (int)ternary_tnet_u64((unsigned __int128)a, 64);
+}
+
+t64_t __ternary_tmux_t64(t64_t sel, t64_t neg, t64_t zero, t64_t pos)
+{
+    return ternary_tmux_u64(sel, neg, zero, pos);
+}
+
 int __ternary_tbranch(TERNARY_COND_T cond, int neg_target, int zero_target, int pos_target)
 {
     return ternary_branch_target(cond, neg_target, zero_target, pos_target);

tests/test_logic_helpers

@@ -72,6 +72,24 @@ int main(void)
     expect_int("tsignjmp_zero", __ternary_tsignjmp_t64(__ternary_tb2t_t64(0), -1, 0, 1), 0);
     expect_int("tsignjmp_pos", __ternary_tsignjmp_t64(__ternary_tb2t_t64(3), -1, 0, 1), 1);
 
+    expect_int("tequiv_true", __ternary_tt2b_t32(__ternary_tequiv_t32(pos, pos)), 1);
+    expect_int("tequiv_unknown", __ternary_tt2b_t32(__ternary_tequiv_t32(zero, pos)), 0);
+    expect_int("tequiv_false", __ternary_tt2b_t32(__ternary_tequiv_t32(pos, neg)), -1);
+
+    expect_int("txor_zero", __ternary_tt2b_t32(__ternary_txor_t32(pos, neg)), 0);
+    expect_int("txor_diff", __ternary_tt2b_t32(__ternary_txor_t32(pos, zero)), 1);
+    expect_int("txor_same", __ternary_tt2b_t32(__ternary_txor_t32(pos, pos)), -1);
+
+    t32_t mux_lo = __ternary_tb2t_t32(1);
+    t32_t mux_mid = __ternary_tb2t_t32(0);
+    t32_t mux_hi = __ternary_tb2t_t32(-1);
+    expect_int("tmux_neg", __ternary_tt2b_t32(__ternary_tmux_t32(__ternary_tb2t_t32(-1), mux_lo, mux_mid, mux_hi)), 1);
+    expect_int("tmux_zero", __ternary_tt2b_t32(__ternary_tmux_t32(__ternary_tb2t_t32(0), mux_lo, mux_mid, mux_hi)), 0);
+    expect_int("tmux_pos", __ternary_tt2b_t32(__ternary_tmux_t32(__ternary_tb2t_t32(1), mux_lo, mux_mid, mux_hi)), -1);
+
+    expect_int("tnet_one", __ternary_tnet_t32(__ternary_tb2t_t32(1)), 1);
+    expect_int("tnet_minus", __ternary_tnet_t32(__ternary_tb2t_t32(-1)), -1);
+
     tv64_t v_lo = { __ternary_tb2t_t64(1), __ternary_tb2t_t64(2) };
     tv64_t v_hi = { __ternary_tb2t_t64(3), __ternary_tb2t_t64(-1) };
     tv64_t added = __ternary_add_tv64(v_lo, v_hi);