feat: Atomics 真原子性：SAB 臂改经共享缓冲 SeqCst 原子方法

crates/oxide_builtins/src/atomics.rs

@@ -5,6 +5,7 @@
 
 use num_bigint::BigInt;
 use oxide_kernel::shape_forge::EMPTY_SHAPE_ID;
+use oxide_kernel::SharedBuffer;
 use oxide_types::object::{JsObject, TypedArrayKind};
 use oxide_types::value::JsValue;
 
@@ -110,15 +111,12 @@ fn resolve_atomic_access<'a, H: VmHost>(
         return Err(range_error(vm, "invalid indexed access to Atomics"));
     }
     // 界判通过，载荷必在场（detached 已越界排除）。
-    let store = buffer_store_mut_ptr(obj)
-        .ok_or_else(|| range_error(vm, "invalid indexed access to Atomics"))?;
+    let store = buffer_store_mut_ptr(obj).ok_or_else(|| range_error(vm, "invalid indexed access to Atomics"))?;
     Ok((store, view, offset as usize))
 }
 
 /// 读指定偏移元素并转为 JS 值（detach 已由 resolve 的越界判收口，载荷恒在场）。
-fn atomic_read<H: VmHost>(
-    vm: &mut H, store: &BufferStoreMut, kind: TypedArrayKind, offset: usize,
-) -> Option<JsValue> {
+fn atomic_read<H: VmHost>(vm: &mut H, store: &BufferStoreMut, kind: TypedArrayKind, offset: usize) -> Option<JsValue> {
     // SAFETY: store 经 resolve_atomic_access 校验为存活载荷，只读字节切片。
     let bytes: &[u8] = match store {
         BufferStoreMut::Ab(b) => b,
@@ -174,6 +172,149 @@ fn arithmetic_write_value<H: VmHost>(
     JsValue::int(r)
 }
 
+/// SAB 臂探针：共享缓冲（SAB）返回内层共享缓冲借用，AB 臂返 `None`。
+/// 借用止于调用语句内，不跨 JS 调用窗口（与 `resolve_atomic_access` 同边界）。
+fn sab_buffer<'a>(store: &'a BufferStoreMut<'a>) -> Option<&'a SharedBuffer> {
+    match store {
+        BufferStoreMut::Sab(buffer) => Some(buffer),
+        BufferStoreMut::Ab(_) => None,
+    }
+}
+
+/// 已转换值的位模式：经 `write_element` 写入 8 字节栈上小数组取位模式，完整
+/// 复用元素写路径的宽度截断语义（ToInt8 / ToUint16 / ToInt32 / ToUint32 /
+/// BigInt 低 64 位），不重实现截断。
+fn value_bits<H: VmHost>(vm: &mut H, kind: TypedArrayKind, value: JsValue) -> u64 {
+    let mut bytes = [0u8; 8];
+    write_element(vm, kind, &mut bytes, 0, value);
+    u64::from_ne_bytes(bytes)
+}
+
+/// 位模式转 JS 值：经 `read_element` 读回位模式（含 BigInt 构造），完整复用
+/// 元素读路径。
+fn bits_to_value<H: VmHost>(vm: &mut H, kind: TypedArrayKind, bits: u64) -> JsValue {
+    let bytes = bits.to_ne_bytes();
+    read_element(vm, kind, &bytes, 0)
+}
+
+/// SAB 臂 fetch 族运算标签。
+enum SabFetchOp {
+    Add,
+    Sub,
+    And,
+    Or,
+    Xor,
+}
+
+/// 按元素宽度分派到共享缓冲对应位宽 fetch 原子方法，返回操作前旧值位模式。
+fn sab_fetch_bits(buf: &SharedBuffer, kind: TypedArrayKind, offset: usize, bits: u64, op: SabFetchOp) -> u64 {
+    match kind.bytes_per_element() {
+        1 => match op {
+            SabFetchOp::Add => u64::from(buf.fetch_add_u8(offset, bits as u8)),
+            SabFetchOp::Sub => u64::from(buf.fetch_sub_u8(offset, bits as u8)),
+            SabFetchOp::And => u64::from(buf.fetch_and_u8(offset, bits as u8)),
+            SabFetchOp::Or => u64::from(buf.fetch_or_u8(offset, bits as u8)),
+            SabFetchOp::Xor => u64::from(buf.fetch_xor_u8(offset, bits as u8)),
+        },
+        2 => match op {
+            SabFetchOp::Add => u64::from(buf.fetch_add_u16(offset, bits as u16)),
+            SabFetchOp::Sub => u64::from(buf.fetch_sub_u16(offset, bits as u16)),
+            SabFetchOp::And => u64::from(buf.fetch_and_u16(offset, bits as u16)),
+            SabFetchOp::Or => u64::from(buf.fetch_or_u16(offset, bits as u16)),
+            SabFetchOp::Xor => u64::from(buf.fetch_xor_u16(offset, bits as u16)),
+        },
+        4 => match op {
+            SabFetchOp::Add => u64::from(buf.fetch_add_u32(offset, bits as u32)),
+            SabFetchOp::Sub => u64::from(buf.fetch_sub_u32(offset, bits as u32)),
+            SabFetchOp::And => u64::from(buf.fetch_and_u32(offset, bits as u32)),
+            SabFetchOp::Or => u64::from(buf.fetch_or_u32(offset, bits as u32)),
+            SabFetchOp::Xor => u64::from(buf.fetch_xor_u32(offset, bits as u32)),
+        },
+        _ => match op {
+            SabFetchOp::Add => buf.fetch_add_u64(offset, bits),
+            SabFetchOp::Sub => buf.fetch_sub_u64(offset, bits),
+            SabFetchOp::And => buf.fetch_and_u64(offset, bits),
+            SabFetchOp::Or => buf.fetch_or_u64(offset, bits),
+            SabFetchOp::Xor => buf.fetch_xor_u64(offset, bits),
+        },
+    }
+}
+
+/// SAB 臂 load：真原子读。
+fn sab_load<H: VmHost>(vm: &mut H, buf: &SharedBuffer, kind: TypedArrayKind, offset: usize) -> JsValue {
+    let bits = match kind.bytes_per_element() {
+        1 => u64::from(buf.load_u8(offset)),
+        2 => u64::from(buf.load_u16(offset)),
+        4 => u64::from(buf.load_u32(offset)),
+        _ => buf.load_u64(offset),
+    };
+    bits_to_value(vm, kind, bits)
+}
+
+/// SAB 臂 store：位模式原子写，返回写入值（单线程下与现行「写后读回」一致）。
+fn sab_store<H: VmHost>(
+    vm: &mut H, buf: &SharedBuffer, kind: TypedArrayKind, offset: usize, value: JsValue,
+) -> JsValue {
+    let bits = value_bits(vm, kind, value);
+    match kind.bytes_per_element() {
+        1 => buf.store_u8(offset, bits as u8),
+        2 => buf.store_u16(offset, bits as u16),
+        4 => buf.store_u32(offset, bits as u32),
+        _ => buf.store_u64(offset, bits),
+    };
+    bits_to_value(vm, kind, bits)
+}
+
+/// SAB 臂 exchange：位模式原子交换，返回操作前旧值。
+fn sab_exchange<H: VmHost>(
+    vm: &mut H, buf: &SharedBuffer, kind: TypedArrayKind, offset: usize, value: JsValue,
+) -> JsValue {
+    let bits = value_bits(vm, kind, value);
+    let old_bits = match kind.bytes_per_element() {
+        1 => u64::from(buf.swap_u8(offset, bits as u8)),
+        2 => u64::from(buf.swap_u16(offset, bits as u16)),
+        4 => u64::from(buf.swap_u32(offset, bits as u32)),
+        _ => buf.swap_u64(offset, bits),
+    };
+    bits_to_value(vm, kind, old_bits)
+}
+
+/// SAB 臂 compareExchange：位模式比较交换，两臂均返回操作前旧值。
+fn sab_compare_exchange<H: VmHost>(
+    vm: &mut H, buf: &SharedBuffer, kind: TypedArrayKind, offset: usize, expected: JsValue, replacement: JsValue,
+) -> JsValue {
+    let expected_bits = value_bits(vm, kind, expected);
+    let replacement_bits = value_bits(vm, kind, replacement);
+    let old_bits: u64 = match kind.bytes_per_element() {
+        1 => {
+            let r = match buf.compare_exchange_u8(offset, expected_bits as u8, replacement_bits as u8) {
+                Ok(_) => expected_bits as u8,
+                Err(actual) => actual,
+            };
+            u64::from(r)
+        }
+        2 => {
+            let r = match buf.compare_exchange_u16(offset, expected_bits as u16, replacement_bits as u16) {
+                Ok(_) => expected_bits as u16,
+                Err(actual) => actual,
+            };
+            u64::from(r)
+        }
+        4 => {
+            let r = match buf.compare_exchange_u32(offset, expected_bits as u32, replacement_bits as u32) {
+                Ok(_) => expected_bits as u32,
+                Err(actual) => actual,
+            };
+            u64::from(r)
+        }
+        _ => match buf.compare_exchange_u64(offset, expected_bits, replacement_bits) {
+            Ok(_) => expected_bits,
+            Err(actual) => actual,
+        },
+    };
+    bits_to_value(vm, kind, old_bits)
+}
+
 /// wait/notify 共享验证核：品牌 → {Int32, BigInt64} 宽度守卫 → 越界/detach
 /// TypeError → 缓冲字节长读取（先于 index 强转，"长度读取"语料钉）→
 /// index ToIntegerOrInfinity → 相对字节偏移越界 RangeError。
@@ -228,8 +369,7 @@ fn resolve_atomic_wait_access<'a, H: VmHost>(
         return Err(range_error(vm, "invalid indexed access to Atomics"));
     }
     // 界判通过，载荷必在场（detached 已越界排除）。
-    let store = buffer_store_mut_ptr(obj)
-        .ok_or_else(|| range_error(vm, "invalid indexed access to Atomics"))?;
+    let store = buffer_store_mut_ptr(obj).ok_or_else(|| range_error(vm, "invalid indexed access to Atomics"))?;
     Ok((store, view, offset as usize, is_sab))
 }
 
@@ -280,33 +420,45 @@ pub fn atomics_notify<H: VmHost>(vm: &mut H, args: &[u8]) -> NativeResult {
     NativeResult::Ok(JsValue::int(vm.atomics_wake_waiters(buffer_ptr, offset, count) as i32))
 }
 
-/// `Atomics.load(typedArray, index)`：读指定索引元素。
+/// `Atomics.load(typedArray, index)`：读指定索引元素。SAB 臂走真原子读，
+/// AB 臂保持读-改-写（零行为）。
 pub fn atomics_load<H: VmHost>(vm: &mut H, args: &[u8]) -> NativeResult {
     let ta_val = arg_at(vm, args, 1);
     let index_val = arg_at(vm, args, 2);
     let (store, view, offset) = native_try!(resolve_atomic_access(vm, ta_val, false, index_val));
+    if let Some(buf) = sab_buffer(&store) {
+        return NativeResult::Ok(sab_load(vm, buf, view.kind, offset));
+    }
     NativeResult::Ok(atomic_read(vm, &store, view.kind, offset).unwrap_or(JsValue::undefined()))
 }
 
 /// `Atomics.store(typedArray, index, value)`：写值后读回返回（宽度归一，-0 → +0）。
+/// SAB 臂走位模式原子写，AB 臂保持读-改-写（零行为）。
 pub fn atomics_store<H: VmHost>(vm: &mut H, args: &[u8]) -> NativeResult {
     let ta_val = arg_at(vm, args, 1);
     let index_val = arg_at(vm, args, 2);
     let value_val = arg_at(vm, args, 3);
     let (mut store, view, offset) = native_try!(resolve_atomic_access(vm, ta_val, true, index_val));
     let value = native_try!(ta_element_value(vm, view.kind, value_val));
+    if let Some(buf) = sab_buffer(&store) {
+        return NativeResult::Ok(sab_store(vm, buf, view.kind, offset, value));
+    }
     atomic_write(vm, &mut store, view.kind, offset, value);
     NativeResult::Ok(atomic_read(vm, &store, view.kind, offset).unwrap_or(value))
 }
 
 /// `Atomics.exchange(typedArray, index, value)`：读旧值、写新值、返回旧值。
+/// SAB 臂走位模式原子交换，AB 臂保持读-改-写（零行为）。
 pub fn atomics_exchange<H: VmHost>(vm: &mut H, args: &[u8]) -> NativeResult {
     let ta_val = arg_at(vm, args, 1);
     let index_val = arg_at(vm, args, 2);
     let value_val = arg_at(vm, args, 3);
     let (mut store, view, offset) = native_try!(resolve_atomic_access(vm, ta_val, true, index_val));
-    let old = atomic_read(vm, &store, view.kind, offset).unwrap_or(JsValue::undefined());
     let value = native_try!(ta_element_value(vm, view.kind, value_val));
+    if let Some(buf) = sab_buffer(&store) {
+        return NativeResult::Ok(sab_exchange(vm, buf, view.kind, offset, value));
+    }
+    let old = atomic_read(vm, &store, view.kind, offset).unwrap_or(JsValue::undefined());
     atomic_write(vm, &mut store, view.kind, offset, value);
     NativeResult::Ok(old)
 }
@@ -336,12 +488,27 @@ pub fn atomics_xor<H: VmHost>(vm: &mut H, args: &[u8]) -> NativeResult {
     atomic_arithmetic(vm, args, "xor")
 }
 
-/// add/sub/and/or/xor 共享核：读旧值 → 运算值转换 → 读-改-写 → 返回旧值。
+/// add/sub/and/or/xor 共享核：SAB 臂走位模式原子 fetch 族（真原子性，返回
+/// 操作前旧值），AB 臂保持读旧值 → 运算值转换 → 读-改-写 → 返回旧值（零行为）。
 fn atomic_arithmetic<H: VmHost>(vm: &mut H, args: &[u8], op: &str) -> NativeResult {
     let ta_val = arg_at(vm, args, 1);
     let index_val = arg_at(vm, args, 2);
     let value_val = arg_at(vm, args, 3);
     let (mut store, view, offset) = native_try!(resolve_atomic_access(vm, ta_val, true, index_val));
+    if let Some(buf) = sab_buffer(&store) {
+        let value = native_try!(ta_element_value(vm, view.kind, value_val));
+        let fetch_op = match op {
+            "add" => SabFetchOp::Add,
+            "sub" => SabFetchOp::Sub,
+            "and" => SabFetchOp::And,
+            "or" => SabFetchOp::Or,
+            "xor" => SabFetchOp::Xor,
+            _ => unreachable!("未知原子运算"),
+        };
+        let bits = value_bits(vm, view.kind, value);
+        let old_bits = sab_fetch_bits(buf, view.kind, offset, bits, fetch_op);
+        return NativeResult::Ok(bits_to_value(vm, view.kind, old_bits));
+    }
     let old = atomic_read(vm, &store, view.kind, offset).unwrap_or(JsValue::undefined());
     let value = native_try!(ta_element_value(vm, view.kind, value_val));
     let result = arithmetic_write_value(vm, view.kind, op, old, value);
@@ -351,14 +518,20 @@ fn atomic_arithmetic<H: VmHost>(vm: &mut H, args: &[u8], op: &str) -> NativeResu
 
 /// `Atomics.compareExchange(typedArray, index, expected, replacement)`：读旧值；
 /// 相等（数值宽度 `==`、BigInt 宽度 BigInt 相等）则写 replacement；返回旧值。
+/// SAB 臂走位模式原子比较交换（比较位模式，两臂均返旧值），AB 臂保持读-改-写
+///（零行为）。
 pub fn atomics_compare_exchange<H: VmHost>(vm: &mut H, args: &[u8]) -> NativeResult {
     let ta_val = arg_at(vm, args, 1);
     let index_val = arg_at(vm, args, 2);
     let expected_val = arg_at(vm, args, 3);
     let replacement_val = arg_at(vm, args, 4);
     let (mut store, view, offset) = native_try!(resolve_atomic_access(vm, ta_val, true, index_val));
-    let old = atomic_read(vm, &store, view.kind, offset).unwrap_or(JsValue::undefined());
     let expected = native_try!(ta_element_value(vm, view.kind, expected_val));
+    if let Some(buf) = sab_buffer(&store) {
+        let replacement = native_try!(ta_element_value(vm, view.kind, replacement_val));
+        return NativeResult::Ok(sab_compare_exchange(vm, buf, view.kind, offset, expected, replacement));
+    }
+    let old = atomic_read(vm, &store, view.kind, offset).unwrap_or(JsValue::undefined());
     let matched = if is_bigint_kind(view.kind) {
         let old_bi = vm.bigint_value(old).clone();
         let expected_bi = vm.bigint_value(expected).clone();
@@ -460,3 +633,113 @@ pub fn atomics_pause<H: VmHost>(vm: &mut H, args: &[u8]) -> NativeResult {
     }
     NativeResult::Ok(JsValue::undefined())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use oxide_vm::vm::Vm;
+
+    /// JS 求值辅助：单脚本编译执行，返回完成值（与 array_buffer 测试同形）。
+    fn eval_atomics(vm: &mut Vm, source: &str) -> Result<JsValue, String> {
+        let allocator = oxide_parser::Allocator::default();
+        let program = oxide_parser::parse(&allocator, source).map_err(|e| format!("parse: {:?}", e[0].message))?;
+        let module = oxide_compiler::compiler::Compiler::new()
+            .compile(&program)
+            .map_err(|e| format!("compile: {e}"))?;
+        vm.run(&std::sync::Arc::new(module))
+    }
+
+    /// SAB 承载 Uint8Array 上九方法返回值与槽值钉（真原子性面）。
+    #[test]
+    fn sab_nine_methods_u8() {
+        let mut vm = Vm::new();
+        let r = eval_atomics(
+            &mut vm,
+            "var sab = new SharedArrayBuffer(8); \
+             var ta = new Uint8Array(sab); ta[0] = 5; \
+             var r1 = Atomics.load(ta, 0); \
+             var r2 = Atomics.store(ta, 0, 10); \
+             var r3 = Atomics.exchange(ta, 0, 20); \
+             var r4 = Atomics.add(ta, 0, 5); \
+             var r5 = Atomics.sub(ta, 0, 5); \
+             var r6 = Atomics.and(ta, 0, 0xF0); \
+             var r7 = Atomics.or(ta, 0, 1); \
+             var r8 = Atomics.xor(ta, 0, 0xFF); \
+             [r1, r2, r3, r4, r5, r6, r7, r8, ta[0]].join(',')",
+        )
+        .unwrap();
+        assert_eq!(vm.lookup_str(r).unwrap(), "5,10,10,20,25,20,16,17,238");
+    }
+
+    /// Uint32 高位边界规范对齐钉：槽值 4294967295 时 add 1 返 4294967295 且
+    /// 槽值环绕为 0（SAB 臂原始位路径修复，非回归）。
+    #[test]
+    fn sab_uint32_high_bit_wrap() {
+        let mut vm = Vm::new();
+        let r = eval_atomics(
+            &mut vm,
+            "var sab = new SharedArrayBuffer(4); \
+             var ta = new Uint32Array(sab); ta[0] = 4294967295; \
+             var a = Atomics.add(ta, 0, 1); \
+             [a, ta[0]].join(',')",
+        )
+        .unwrap();
+        assert_eq!(vm.lookup_str(r).unwrap(), "4294967295,0");
+    }
+
+    /// Int32 / BigInt64 / BigUint64 宽度 SAB 臂 add 与槽值钉。
+    #[test]
+    fn sab_int32_and_bigint_widths() {
+        let mut vm = Vm::new();
+        let r = eval_atomics(
+            &mut vm,
+            "var r = []; \
+             var s1 = new SharedArrayBuffer(8); var i32 = new Int32Array(s1); i32[0] = -100; \
+             r.push(Atomics.add(i32, 0, 30)); r.push(i32[0]); \
+             var s2 = new SharedArrayBuffer(8); var b64 = new BigInt64Array(s2); b64[0] = 100n; \
+             r.push(Atomics.add(b64, 0, 50n)); r.push(b64[0]); \
+             var s3 = new SharedArrayBuffer(8); var bu64 = new BigUint64Array(s3); bu64[0] = 10n; \
+             r.push(Atomics.add(bu64, 0, 5n)); r.push(bu64[0]); \
+             r.join(',')",
+        )
+        .unwrap();
+        assert_eq!(vm.lookup_str(r).unwrap(), "-100,-70,100,150,10,15");
+    }
+
+    /// compareExchange 匹配臂（写 replacement 返旧值）与不匹配臂（不写返旧值）。
+    #[test]
+    fn sab_compare_exchange_arms() {
+        let mut vm = Vm::new();
+        let r = eval_atomics(
+            &mut vm,
+            "var sab = new SharedArrayBuffer(4); var ta = new Uint32Array(sab); ta[0] = 5; \
+             var m = Atomics.compareExchange(ta, 0, 5, 9); var slotM = ta[0]; \
+             var nm = Atomics.compareExchange(ta, 0, 7, 12); var slotNM = ta[0]; \
+             [m, slotM, nm, slotNM].join(',')",
+        )
+        .unwrap();
+        assert_eq!(vm.lookup_str(r).unwrap(), "5,9,9,9");
+    }
+
+    /// AB 臂零行为钉：同一九方法在 ArrayBuffer 承载 TypedArray 上，结果与 SAB
+    /// 臂同值（读-改-写路径未动）。
+    #[test]
+    fn ab_arm_zero_behavior() {
+        let mut vm = Vm::new();
+        let r = eval_atomics(
+            &mut vm,
+            "var ab = new ArrayBuffer(8); var ta = new Uint8Array(ab); ta[0] = 5; \
+             var r1 = Atomics.load(ta, 0); \
+             var r2 = Atomics.store(ta, 0, 10); \
+             var r3 = Atomics.exchange(ta, 0, 20); \
+             var r4 = Atomics.add(ta, 0, 5); \
+             var r5 = Atomics.sub(ta, 0, 5); \
+             var r6 = Atomics.and(ta, 0, 0xF0); \
+             var r7 = Atomics.or(ta, 0, 1); \
+             var r8 = Atomics.xor(ta, 0, 0xFF); \
+             [r1, r2, r3, r4, r5, r6, r7, r8, ta[0]].join(',')",
+        )
+        .unwrap();
+        assert_eq!(vm.lookup_str(r).unwrap(), "5,10,10,20,25,20,16,17,238");
+    }
+}