From 94cb47a7e8946de86890361e7657dfb500ffe816 Mon Sep 17 00:00:00 2001
From: Dmitrii Vasilev <admin@t27.ai>
Date: Mon, 12 Oct 2026 15:11:16 +0700
Subject: [PATCH] Port gHashTag/trinity tvc_phi_integration.zig to specs
 (Closes #9119)

The TVCGoldenWrap layer as .t27: trit add, sub and neg wrap through the
golden interval exactly as the original does, max, min and abs are the
plain i8 operations, seven tests driving all six functions, including
the original's own cases and a totality sweep over every trit pair.

Replaces the branch's earlier content: it ported a different task's file
(trios-chat ratchet_replay_window_guard, issue #8873's target) under
this issue's number, with a docs/now entry outside the boundary.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../phi-engine/tvc/tvc_phi_integration.t27    | 126 ++++++++++++++++++
 1 file changed, 126 insertions(+)
 create mode 100644 specs/port/trinity/src/phi-engine/tvc/tvc_phi_integration.t27

diff --git a/specs/port/trinity/src/phi-engine/tvc/tvc_phi_integration.t27 b/specs/port/trinity/src/phi-engine/tvc/tvc_phi_integration.t27
new file mode 100644
index 0000000000..fc2dbdcfe8
--- /dev/null
+++ b/specs/port/trinity/src/phi-engine/tvc/tvc_phi_integration.t27
@@ -0,0 +1,126 @@
+module port::trinity::phi_engine::tvc_phi_integration;
+
+// Port of gHashTag/trinity src/phi-engine/tvc/tvc_phi_integration.zig
+// (commit 5aabfbe8346f, issue #9119): the TVCGoldenWrap integration layer.
+//
+// Trit in the original is i8 carrying {-1, 0, +1}; the port keeps i8 and the
+// arithmetic verbatim. Add, sub and neg wrap through the golden interval:
+// a value past +1 comes back from -1, a value past -1 from +1. Max, min and
+// abs are the plain i8 operations.
+
+fn TVCGoldenWrap_tvcTritAdd(a: i8, b: i8) -> i8 {
+    const sum = a + b;
+    if (sum > 1) {
+        return sum - 3;
+    }
+    if (sum < -1) {
+        return sum + 3;
+    }
+    return sum;
+}
+
+fn TVCGoldenWrap_tvcTritSub(a: i8, b: i8) -> i8 {
+    const diff = a - b;
+    if (diff > 1) {
+        return diff - 3;
+    }
+    if (diff < -1) {
+        return diff + 3;
+    }
+    return diff;
+}
+
+fn TVCGoldenWrap_tvcTritNeg(a: i8) -> i8 {
+    const neg = -a;
+    if (neg > 1) {
+        return neg - 3;
+    }
+    if (neg < -1) {
+        return neg + 3;
+    }
+    return neg;
+}
+
+fn TVCGoldenWrap_tvcTritMax(a: i8, b: i8) -> i8 {
+    if (a > b) {
+        return a;
+    }
+    return b;
+}
+
+fn TVCGoldenWrap_tvcTritMin(a: i8, b: i8) -> i8 {
+    if (a < b) {
+        return a;
+    }
+    return b;
+}
+
+fn TVCGoldenWrap_tvcTritAbs(a: i8) -> i8 {
+    if (a < 0) {
+        return -a;
+    }
+    return a;
+}
+
+test tvc_trit_add_wraps_both_ends {
+    // 1 + 1 = -1 (wrap past +1), the original's own case.
+    assert(TVCGoldenWrap_tvcTritAdd(1, 1) == -1);
+    // -1 + -1 = +1 (wrap past -1).
+    assert(TVCGoldenWrap_tvcTritAdd(-1, -1) == 1);
+}
+
+test tvc_trit_add_stays_inside {
+    assert(TVCGoldenWrap_tvcTritAdd(1, 0) == 1);
+    assert(TVCGoldenWrap_tvcTritAdd(0, 0) == 0);
+    assert(TVCGoldenWrap_tvcTritAdd(-1, 0) == -1);
+    assert(TVCGoldenWrap_tvcTritAdd(1, -1) == 0);
+}
+
+test tvc_trit_sub_wraps_and_stays {
+    // The original's own case: 1 - 1 = 0.
+    assert(TVCGoldenWrap_tvcTritSub(1, 1) == 0);
+    // -1 - 1 = -2 wraps to +1.
+    assert(TVCGoldenWrap_tvcTritSub(-1, 1) == 1);
+    assert(TVCGoldenWrap_tvcTritSub(0, 1) == -1);
+    assert(TVCGoldenWrap_tvcTritSub(-1, -1) == 0);
+}
+
+test tvc_trit_neg_flips_inside_the_interval {
+    // The original's own case: neg(1) = -1.
+    assert(TVCGoldenWrap_tvcTritNeg(1) == -1);
+    assert(TVCGoldenWrap_tvcTritNeg(-1) == 1);
+    assert(TVCGoldenWrap_tvcTritNeg(0) == 0);
+}
+
+test tvc_trit_max_and_min {
+    // The original's own cases: max(1, 0) = 1, min(1, 0) = 0.
+    assert(TVCGoldenWrap_tvcTritMax(1, 0) == 1);
+    assert(TVCGoldenWrap_tvcTritMax(-1, 1) == 1);
+    assert(TVCGoldenWrap_tvcTritMax(0, 0) == 0);
+    assert(TVCGoldenWrap_tvcTritMin(1, 0) == 0);
+    assert(TVCGoldenWrap_tvcTritMin(-1, 1) == -1);
+    assert(TVCGoldenWrap_tvcTritMin(0, 0) == 0);
+}
+
+test tvc_trit_abs_is_always_positive_or_zero {
+    // The original's own case: abs(-1) = 1.
+    assert(TVCGoldenWrap_tvcTritAbs(-1) == 1);
+    assert(TVCGoldenWrap_tvcTritAbs(1) == 1);
+    assert(TVCGoldenWrap_tvcTritAbs(0) == 0);
+}
+
+test tvc_wrap_is_closed_over_all_trit_pairs {
+    // Every pair of trits lands back on a trit: the wrap table is total.
+    var a: i8 = -1;
+    while (a <= 1) {
+        var b: i8 = -1;
+        while (b <= 1) {
+            const s = TVCGoldenWrap_tvcTritAdd(a, b);
+            assert(s >= -1 and s <= 1);
+            const d = TVCGoldenWrap_tvcTritSub(a, b);
+            assert(d >= -1 and d <= 1);
+            b += 1;
+        }
+        a += 1;
+    }
+}