Extended the logic-helper

Author: t81dev

ENCODING.md

@@ -0,0 +1,38 @@
+# Ternary ISA Encoding Notes
+
+This file sketches how the new helpers (TBRANCH/TMUX/TMAJ/TNET, etc.) might be encoded in a future ternary ISA that favors tryte-aligned opcodes and asynchronous control.
+
+## Tryte-friendly Opcode Layout
+
+Balanced ternary instructions can pack more information per opcode than binary. A 6-trit “tryte” can be divided into:
+
+- **2 trits**: data width tag
+- **2 trits**: instruction family (e.g., logic, control, neural)
+- **2 trits**: immediate flags / predicate bits
+
+For example, TBRANCH and TMUX can share the same family slot (control) but use different predicate bits to indicate whether the instruction targets code or data. This layout keeps the decoder simple and lets the hardware dispatch a full control triple in one cycle.
+
+| Tryte Field | Value (balanced ternary) | Meaning |
+|-------------|--------------------------|---------|
+| Width       | `-1` / `0` / `+1`        | selects 32/64/128 trit widths |
+| Family      | `-1` / `0` / `+1`        | logic / control / arithmetic |
+| Flags       | `-1` / `0` / `+1`        | condition inversion / speculation bits |
+
+A `TBRANCH` instruction can carry three relative offsets/labels plus a flag that enables speculative dispatch, while `TMUX` uses the same control bits to choose among data paths.
+
+## Async Control Handshake
+
+Following Setun’s clockless transitions, the ternary branch path can be modeled as a handshake:
+
+1. A ternary condition trit is produced by the comparison logic.
+2. The arbiter observes the trit and activates one of three ready signals (negative/zero/positive).
+3. The pipeline selects the matching target tag (one of the triple encoded next to the opcode).
+4. Speculative bits indicate whether the branch outcome should be confirmed in a later cycle or aborted.
+
+Because ternary conditions expose sign symmetry, `TSIGNJMP`/`TMUX` can reuse the same handshake: the runtime helper returns the chosen target (or data lane) immediately, and an arbiter verifies the trit feeds through to the next cycle before committing.
+
+## TNN-Ready Units
+
+Vectorized primitives such as `TMAJ` and `TNET` benefit from this encoding because they can receive their operand tag, width, and mask in a single tryte. For example, a `TNET` instruction on a 128-trit register might set the width field to `+1`, the family to `+1` (neural), and use the flags to toggle “fold-over” behavior for training-aware rounding.
+
+These sketches guide future ASIC/FPGA work; the runtime helpers and skeleton demos mirror the same semantics in software.

MASTER_ISA.md

@@ -116,6 +116,7 @@ focuses on instructions whose semantics *literally require* a three-valued persp
 - Tryte-friendly opcodes: reserve 6 trits per slot (e.g., 2 trits for vector width, 2 trits for the instruction family, 2 trits for immediates/flags). Instructions such as `TBRANCH`, `TMAJ`, and `TMULADD` can live in a single tryte with built-in width tags so the hardware decoder can dispatch without binary prefix tables.
 - Async branch support: follow Setun’s clockless transitions by treating `TBRANCH`/`TSIGNJMP` as micro-instructions that grab a condition trit and target triple simultaneously, avoiding the binary flag expansion. Documenting this early helps map the runtime helpers to future hardware that may signal targets through a branch arbiter rather than the normal program counter updates.
 - Async control handshake: model hardware such that the condition feed (ternary condition register) produces one of three ready signals, and an arbiter selects the matching target label/offset in the same cycle. `TBRANCH` should therefore expose a triple-target field plus a flag that indicates whether the jump is speculative; software helpers can mirror that by returning the chosen target value so forward progress can be verified even before hardware support arrives.
+- For a concrete tryte encoding, see `ENCODING.md`, which lays out the 6-trit fields for family/tag/flags (including how TBRANCH/TMUX/TMAJ/TNET slot into those fields) and explains how the async arbiter consumes the flag field as a readiness handshake.
 
 ## Next steps
 
@@ -124,3 +125,7 @@ focuses on instructions whose semantics *literally require* a three-valued persp
 2. Choose a canonical helper prefix (`__ternary` by default) and append the new operations to that ABI.
 3. Prototype the quantization/branch helpers in `runtime_skeleton/` so plugin tests can depend on them.
 4. Sketch hardware encodings (tryte/6-trit opcodes) once the semantics settle.
+5. Expand t128/runtime coverage (and tests) so the helper list scales beyond t64 and the TMUX/TNET paths used in the skeleton can be verified on larger registers (**Completed**).
+   - The reference runtime now defines all t128 helpers (including TMUX/TNET/TEQUIV/TXOR) via `_BitInt(256)` encode/decode helpers and exposes them through `include/ternary_runtime.h`.
+   - The runtime skeleton mirrors the same helpers so the minimal implementation delivers the ISA contracts and the TMUX/TNET demo can run across t128 lanes.
+   - Focused tests (`tests/test_logic_helpers.c`, `runtime_skeleton/test_runtime_skeleton.c`) cover the t128 helpers and `tools/check_helper_docs.py` keeps documentation in lockstep.

README.md

@@ -175,9 +175,13 @@ For testing without the plugin, the header provides C implementations of all ter
 Packed ternary types use a 2-bit encoding per trit (00 = -1, 01 = 0, 10 = +1).
 Define `TERNARY_USE_BUILTIN_TYPES` before including the header when compiling with
 `-fplugin-arg-ternary_plugin-types` to avoid typedef conflicts.
-Helper/runtime support is currently provided for t32/t64 only; t128 requires
-custom runtime implementations. The reference runtime uses 64-bit logical
-conversion helpers, so t64 correctness is limited to values that fit in int64.
+Helper/runtime support now covers t32/t64 and t128 (when `_BitInt(256)` support
+is available). The reference runtime, headers, and skeleton expose the full
+helper set—TMUX/TNET/TEQUIV/TXOR included—for t128_math paths, and the
+corresponding tests (`tests/test_logic_helpers.c`, `runtime_skeleton/test_runtime_skeleton.c`)
+exercise those helpers so their semantics are verified on wider ternary
+registers. Run `tools/check_helper_docs.py` after ABI changes to keep the helper
+list in sync.
 
 For example:
 
@@ -200,8 +204,8 @@ gcc -fplugin=./ternary_plugin.so -fplugin-arg-ternary_plugin-lower -Iinclude -c
 
 For a minimal out-of-line runtime, use the reference implementation in `runtime/ternary_runtime.c`
 with the public header `include/ternary_runtime.h`. It implements the same packed 2-bit-trit
-semantics as the helpers (t32/t64) and is intended as a starting point for a real ISA-backed
-library. Packed helpers for t128 are not provided in this reference runtime.
+semantics as the helpers (t32/t64) and now surfaces the t128 helpers when `_BitInt(256)`
+support exists so ISA-backed runtimes can prototype on the wider register set.
 
 Example build:
 
@@ -261,6 +265,17 @@ make test CXX=g++-15 CC=gcc-15
 
 `make test` now also compiles `tests/test_literals.c` (ensuring literal helpers + promotions compile) and `test_ternary.c` with `-fplugin-arg-ternary_plugin-dump-gimple` so Phase 3 coverage exercises the dump/trace flags.
 
+### Extended helper ABI
+
+In addition to the core helper ABI described in `SPECIFICATION.md`, the roadmap now exposes the ternary-only helpers used by the TMUX/TNET/TNN demo and the runtime/reference implementations:
+
+- `__ternary_tmux_t32` / `__ternary_tmux_t64` / `__ternary_tmux_t128`
+- `__ternary_tequiv_t32` / `__ternary_tequiv_t64` / `__ternary_tequiv_t128`
+- `__ternary_txor_t32` / `__ternary_txor_t64` / `__ternary_txor_t128`
+- `__ternary_tnet_t32` / `__ternary_tnet_t64` / `__ternary_tnet_t128`
+
+These helpers are exercised by the runtime skeleton demo (`runtime_skeleton/run_tnn_demo.sh`), which now builds and runs a tiny ternary neural network pipeline across t32/t64/t128 helper implementations and TMUX-driven routing logic.
+
 ## Description
 
 This plugin analyzes ternary conditional expressions in the code and can optionally
@@ -304,7 +319,27 @@ For helpers that literally need three-valued semantics (TMIN/TMAX, TIMPL/TLIMP,
 TMAJ, TQUANT, and the TNOT/TINV aliases), see `MASTER_ISA.md`. It documents how
 these instructions propagate “unknown” trits, when to use TINV as an inference
 alias, and the extended control-flow helpers (TBRANCH/TSIGNJMP) you can expose
-through `__ternary_*` before hardware encodings are sketched.
+through `__ternary_*` before hardware encodings are sketched (see `ENCODING.md`
+for the tryte field layout mentioned there).
+
+### Helper symbol inventory
+
+```
+__ternary_tbias_t32 __ternary_tbias_t64 __ternary_tbias_t128 __ternary_tbranch __ternary_tequiv_t32
+__ternary_tequiv_t64 __ternary_tequiv_t128 __ternary_tinv_t32 __ternary_tinv_t64 __ternary_tinv_t128
+__ternary_tlimp_t32 __ternary_tlimp_t64 __ternary_tlimp_t128 __ternary_tlimp_tv32 __ternary_tmaj_t32
+__ternary_tmaj_t64 __ternary_tmaj_t128 __ternary_tmaj_tv32 __ternary_tmax_t32 __ternary_tmax_t64
+__ternary_tmax_t128 __ternary_tmax_tv32 __ternary_tmin_t32 __ternary_tmin_t64 __ternary_tmin_t128
+__ternary_tmin_tv32 __ternary_tmuladd_t32 __ternary_tmuladd_t64 __ternary_tmuladd_t128 __ternary_tmux_t32
+__ternary_tmux_t64 __ternary_tmux_t128 __ternary_tnet_t32 __ternary_tnet_t64 __ternary_tnet_t128
+__ternary_tnormalize_t32 __ternary_tnormalize_t64 __ternary_tnormalize_t128 __ternary_tnot_t32
+__ternary_tnot_t64 __ternary_tnot_t128 __ternary_tquant_t32 __ternary_tquant_t64 __ternary_tquant_t128
+__ternary_tquant_tv32 __ternary_tround_t32 __ternary_tround_t64 __ternary_tround_t128 __ternary_tround_tv32
+__ternary_tsignjmp_t32 __ternary_tsignjmp_t64 __ternary_txor_t32 __ternary_txor_t64 __ternary_txor_t128
+```
+The expanded helper list now also covers ternary equivalence/XOR (`TEQUIV`/`TXOR`),
+TMUX-style data selectors, and the net-trit sum helper (`TNET`), so the roadmap,
+runtime, and docs all agree on the full ternary-only ISA surface.
 
 ### Control Flow Operations (brt/brf) - PLANNED
 - `brt Rc, label`: branch if Rc != 0 (ternary true)

SPECIFICATION.md

@@ -311,6 +311,9 @@ Branches use ternary conditions:
 - brt cond, label: branch if cond != 0
 - brf cond, label: branch if cond == 0
 
+Hardware implementers can reference `ENCODING.md` for the tryte field layout that packs the
+conditional helpers (TBRANCH/TMUX) plus the family/flag bits used by the async arbiter described in `MASTER_ISA.md`.
+
 Ternary-aware helpers like `tbranch` and `tsignjmp` (see `MASTER_ISA.md`) allow
 three-way control-flow selection or sign-directed jumps without chaining binary
 flags, matching Setun’s triple-transition model.
@@ -418,6 +421,25 @@ helper implementations can be shared between plugin tests and downstream runtime
   `__ternary_xor_t32`, `__ternary_xor_t64`, `__ternary_shl_t32`, `__ternary_shl_t64`,
   `__ternary_shr_t32`, `__ternary_shr_t64`, `__ternary_rol_t32`, `__ternary_rol_t64`,
   `__ternary_ror_t32`, `__ternary_ror_t64`.
+- **Packed ternary logic helpers** (AI-friendly semantics):
+  `__ternary_tmin_t32`, `__ternary_tmin_t64`, `__ternary_tmax_t32`, `__ternary_tmax_t64`,
+  `__ternary_tmaj_t32`, `__ternary_tmaj_t64`, `__ternary_tlimp_t32`, `__ternary_tlimp_t64`,
+  `__ternary_tquant_t32`, `__ternary_tquant_t64`, `__ternary_tquant_tv32`,
+  `__ternary_tnot_t32`, `__ternary_tnot_t64`, `__ternary_tmuladd_t32`,
+  `__ternary_tmuladd_t64`, `__ternary_tround_t32`, `__ternary_tround_t64`,
+  `__ternary_tround_tv32`, `__ternary_tnormalize_t32`, `__ternary_tnormalize_t64`,
+  `__ternary_tbias_t32`, `__ternary_tbias_t64`, `__ternary_tmux_t32`,
+  `__ternary_tmux_t64`, `__ternary_tequiv_t32`, `__ternary_tequiv_t64`,
+  `__ternary_txor_t32`, `__ternary_txor_t64`, `__ternary_tnet_t32`,
+  `__ternary_tnet_t64`.
+- **Packed ternary logic helpers (t128, when `_BitInt(256)` is available)**:
+  `__ternary_tmin_t128`, `__ternary_tmax_t128`, `__ternary_tmaj_t128`,
+  `__ternary_tlimp_t128`, `__ternary_tquant_t128`, `__ternary_tnot_t128`,
+  `__ternary_tinv_t128`, `__ternary_tmuladd_t128`, `__ternary_tround_t128`,
+  `__ternary_tnormalize_t128`, `__ternary_tbias_t128`, `__ternary_tmux_t128`,
+  `__ternary_tequiv_t128`, `__ternary_txor_t128`, `__ternary_tnet_t128`.
+- **Ternary control helpers**: `__ternary_tbranch`, `__ternary_tsignjmp_t32`,
+  `__ternary_tsignjmp_t64`.
 - **Packed ternary comparisons (ternary results)**: `__ternary_cmplt_t32`, `__ternary_cmplt_t64`,
   `__ternary_cmpeq_t32`, `__ternary_cmpeq_t64`, `__ternary_cmpgt_t32`, `__ternary_cmpgt_t64`,
   `__ternary_cmpneq_t32`, `__ternary_cmpneq_t64`.
@@ -473,10 +495,18 @@ packed 2-bit trit encoding (00 = -1, 01 = 0, 10 = +1).
 - Shift/rotate builtin lowering (t32/t64)
 - Conversion builtin lowering (tb2t, tt2b, t2f, f2t)
 
+### Extended helper ABI
+
+- Three-way selector helpers: `__ternary_tmux_t32`, `__ternary_tmux_t64`, `__ternary_tmux_t128`.
+- Kleene equivalence helpers: `__ternary_tequiv_t32`, `__ternary_tequiv_t64`, `__ternary_tequiv_t128`.
+- Ternary-exclusive-or helpers: `__ternary_txor_t32`, `__ternary_txor_t64`, `__ternary_txor_t128`.
+- Net-sum helpers: `__ternary_tnet_t32`, `__ternary_tnet_t64`, `__ternary_tnet_t128`.
+- Demonstrated via the TMUX/TNET/TNN runtime skeleton demo, including t32/t64/t128 workloads.
+
 ### Known Limitations
 - GCC 15 API compatibility may still require adjustments
-- Packed ternary helpers currently cover t32/t64 only (no big-int support for t128)
-- Reference runtime/helpers do not implement t128 operations
+- Packed ternary helpers require `__BITINT_MAXWIDTH__ >= 256` for native `t128_t`; fallback paths mirror the two-`t64_t` layout.
+- Reference runtime/helpers only simulate t128 operations when the compiler exposes `_BitInt(256)` support.
 
 ## Future Extensions
 

include/ternary_helpers.h

@@ -14,6 +14,9 @@
 
 #include <stdint.h>
 #include <stdarg.h>
+#define TERNARY_PLUGIN_SKIP_BT_STR
+#include "ternary_plugin.h"
+#undef TERNARY_PLUGIN_SKIP_BT_STR
 
 #ifdef __cplusplus
 extern "C" {
@@ -871,6 +874,57 @@ static inline int __ternary_cmp_t64(t64_t a, t64_t b) {
     if (va > vb) return 1;
     return 0;
 }
+
+/* Extended helper declarations that mirror the runtime implementations. */
+extern t32_t __ternary_tmin_t32(t32_t a, t32_t b);
+extern t32_t __ternary_tmax_t32(t32_t a, t32_t b);
+extern t32_t __ternary_tmaj_t32(t32_t a, t32_t b, t32_t c);
+extern t32_t __ternary_tlimp_t32(t32_t antecedent, t32_t consequent);
+extern t32_t __ternary_tquant_t32(float value, float threshold);
+extern t32_t __ternary_tnot_t32(t32_t a);
+extern t32_t __ternary_tinv_t32(t32_t a);
+extern t32_t __ternary_tmuladd_t32(t32_t a, t32_t b, t32_t c);
+extern t32_t __ternary_tround_t32(t32_t a, unsigned drop);
+extern t32_t __ternary_tnormalize_t32(t32_t a);
+extern t32_t __ternary_tbias_t32(t32_t a, int64_t bias);
+extern t32_t __ternary_tmux_t32(t32_t sel, t32_t neg, t32_t zero, t32_t pos);
+extern t32_t __ternary_tequiv_t32(t32_t a, t32_t b);
+extern t32_t __ternary_txor_t32(t32_t a, t32_t b);
+extern int __ternary_tnet_t32(t32_t a);
+
+extern t64_t __ternary_tmin_t64(t64_t a, t64_t b);
+extern t64_t __ternary_tmax_t64(t64_t a, t64_t b);
+extern t64_t __ternary_tmaj_t64(t64_t a, t64_t b, t64_t c);
+extern t64_t __ternary_tlimp_t64(t64_t antecedent, t64_t consequent);
+extern t64_t __ternary_tquant_t64(double value, double threshold);
+extern t64_t __ternary_tnot_t64(t64_t a);
+extern t64_t __ternary_tinv_t64(t64_t a);
+extern t64_t __ternary_tmuladd_t64(t64_t a, t64_t b, t64_t c);
+extern t64_t __ternary_tround_t64(t64_t a, unsigned drop);
+extern t64_t __ternary_tnormalize_t64(t64_t a);
+extern t64_t __ternary_tbias_t64(t64_t a, int64_t bias);
+extern t64_t __ternary_tmux_t64(t64_t sel, t64_t neg, t64_t zero, t64_t pos);
+extern t64_t __ternary_tequiv_t64(t64_t a, t64_t b);
+extern t64_t __ternary_txor_t64(t64_t a, t64_t b);
+extern int __ternary_tnet_t64(t64_t a);
+
+#if defined(__BITINT_MAXWIDTH__) && __BITINT_MAXWIDTH__ >= 256 && !defined(__cplusplus)
+extern t128_t __ternary_tmin_t128(t128_t a, t128_t b);
+extern t128_t __ternary_tmax_t128(t128_t a, t128_t b);
+extern t128_t __ternary_tmaj_t128(t128_t a, t128_t b, t128_t c);
+extern t128_t __ternary_tlimp_t128(t128_t antecedent, t128_t consequent);
+extern t128_t __ternary_tquant_t128(double value, double threshold);
+extern t128_t __ternary_tnot_t128(t128_t a);
+extern t128_t __ternary_tinv_t128(t128_t a);
+extern t128_t __ternary_tmuladd_t128(t128_t a, t128_t b, t128_t c);
+extern t128_t __ternary_tround_t128(t128_t a, unsigned drop);
+extern t128_t __ternary_tnormalize_t128(t128_t a);
+extern t128_t __ternary_tbias_t128(t128_t a, int64_t bias);
+extern t128_t __ternary_tmux_t128(t128_t sel, t128_t neg, t128_t zero, t128_t pos);
+extern t128_t __ternary_tequiv_t128(t128_t a, t128_t b);
+extern t128_t __ternary_txor_t128(t128_t a, t128_t b);
+extern int __ternary_tnet_t128(t128_t a);
+#endif
 #ifdef __cplusplus
 }
 #endif

include/ternary_plugin.h

@@ -19,8 +19,10 @@ typedef unsigned __int128 v2t64_t;  // 2 x t64
 typedef unsigned __int128 v4t64_t;  // 4 x t64
 
 // Balanced-ternary string literals (requires runtime helpers)
+#ifndef TERNARY_PLUGIN_SKIP_BT_STR
 extern t32_t __ternary_bt_str_t32(const char *s);
 extern t64_t __ternary_bt_str_t64(const char *s);
+#endif
 #define T32_LITERAL(s) __ternary_bt_str_t32(s)
 #define T64_LITERAL(s) __ternary_bt_str_t64(s)
 #define __ternary(N) t##N##_t

include/ternary_runtime.h

@@ -16,16 +16,21 @@ typedef int64_t ternary_cond_t;
 #ifndef TERNARY_USE_BUILTIN_TYPES
 typedef uint64_t t32_t;           /* 32 trits -> 64 bits */
 typedef unsigned __int128 t64_t;  /* 64 trits -> 128 bits */
+#if defined(__BITINT_MAXWIDTH__) && __BITINT_MAXWIDTH__ >= 256 && !defined(__cplusplus)
+typedef unsigned _BitInt(256) t128_t; /* 128 trits -> 256 bits */
+#endif
 typedef unsigned __int128 tv32_t; /* vector of 2 x t32_t (128 bits) */
 typedef struct { unsigned __int128 lo, hi; } tv64_t; /* vector of 2 x t64_t (256 bits) */
+#if defined(__BITINT_MAXWIDTH__) && __BITINT_MAXWIDTH__ >= 256 && !defined(__cplusplus)
 typedef struct { unsigned __int128 lo, hi; } tv128_t; /* vector of 2 x t128_t (512 bits) */
 #endif
+#endif
 
 /* Varargs helpers for ternary packed types. */
 #define TERNARY_VA_ARG_T32(ap) ((t32_t)va_arg(ap, uint64_t))
 #define TERNARY_VA_ARG_T64(ap) ((t64_t)va_arg(ap, unsigned __int128))
 
-/* Note: t128 helpers are not provided in this header. */
+/* t128 helpers are exposed when `_BitInt(256)` is available at compile time. */
 
 /* Select helpers for standard types. */
 int __ternary_select_i8(TERNARY_COND_T cond, int true_val, int false_val);
@@ -143,6 +148,24 @@ t64_t __ternary_f2t64_t64(double v);
 int __ternary_cmp_t64(t64_t a, t64_t b);
 t64_t __ternary_bt_str_t64(const char *s);
 
+#if defined(__BITINT_MAXWIDTH__) && __BITINT_MAXWIDTH__ >= 256 && !defined(__cplusplus)
+t128_t __ternary_tmin_t128(t128_t a, t128_t b);
+t128_t __ternary_tmax_t128(t128_t a, t128_t b);
+t128_t __ternary_tmaj_t128(t128_t a, t128_t b, t128_t c);
+t128_t __ternary_tlimp_t128(t128_t antecedent, t128_t consequent);
+t128_t __ternary_tquant_t128(double value, double threshold);
+t128_t __ternary_tnot_t128(t128_t a);
+t128_t __ternary_tinv_t128(t128_t a);
+t128_t __ternary_tmuladd_t128(t128_t a, t128_t b, t128_t c);
+t128_t __ternary_tround_t128(t128_t a, unsigned drop);
+t128_t __ternary_tnormalize_t128(t128_t a);
+t128_t __ternary_tbias_t128(t128_t a, int64_t bias);
+t128_t __ternary_tmux_t128(t128_t sel, t128_t neg, t128_t zero, t128_t pos);
+t128_t __ternary_tequiv_t128(t128_t a, t128_t b);
+t128_t __ternary_txor_t128(t128_t a, t128_t b);
+int __ternary_tnet_t128(t128_t a);
+#endif
+
 /* Ternary-specific comparison operations for t64 (return ternary results) */
 t64_t __ternary_cmplt_t64(t64_t a, t64_t b);
 t64_t __ternary_cmpeq_t64(t64_t a, t64_t b);