From 0744e5ad89f0fc12e24ea4ede6777c2e481d0b8c Mon Sep 17 00:00:00 2001
From: Drew T <50529377+Druthulu@users.noreply.github.com>
Date: Sun, 21 Jun 2026 22:05:23 -0600
Subject: [PATCH] =?UTF-8?q?docs(phase-21):=20distill=20=E2=80=94=20disjoin?=
 =?UTF-8?q?t-bits=20add->ori=20barrier=20idiom=20from=20func=5F80169058?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/matching-cookbook.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/matching-cookbook.md b/docs/matching-cookbook.md
index 8708f3bb6..ca0d784c2 100644
--- a/docs/matching-cookbook.md
+++ b/docs/matching-cookbook.md
@@ -1436,3 +1436,11 @@ byte-matched evidence fn. (Pins/array-decay/statement-order/shared-ret0/for-vs-d
   where a following store schedules — distinct from the input-only anchor `__asm__ __volatile__("":: "r"(x))` (which
   only anchors x *ahead* of the next op). Use when interleaved stores need a value freshly re-tied mid-sequence.
   *evidence func_80165CA0 (`SHB(x)` macro, combined with `$v0`/`$v1` pins).*
+- **disjoint-bits `x + CONST` emits `ori`, not `addiu` → break it with a re-tie barrier:** when x's low bits are
+  provably zero where CONST has bits (e.g. `x = (v & 0x7F00) >> 5;` then `x + 0xC00` — masked-then-shifted value
+  can't overlap 0xC00), gcc-2.7.2 proves the add is disjoint and folds it to `ori x,x,CONST`; but the target used
+  `addiu`. Insert the §21 re-tie barrier `__asm__ __volatile__("":"=r"(x):"0"(x));` BETWEEN the mask/shift and the
+  `+ CONST` — re-materializing x there erases the known-zero-bits range, so gcc can no longer prove disjointness and
+  emits `addiu x,x,CONST`. (Same barrier syntax as the bullet above, but the effect here is ARITHMETIC OPCODE
+  SELECTION, not store scheduling.) *fixes the `add`→`ori` disjoint-bit fold; evidence func_80169058 (the `+0xC00`
+  no-bit-overlap add).*