youknowone · Nov 5, 2026 · Nov 3, 2026 · Nov 4, 2026 · coderabbitai · Nov 4, 2026
diff --git a/crates/host_env/src/ctypes.rs b/crates/host_env/src/ctypes.rs
@@ -608,6 +608,65 @@ pub enum SimpleStorageValue {
     Zero,
 }
 
+// An allocation is owned only until published into ctypes storage. Like CPython,
+// committed BSTRs are freed by replacement, not by CData destruction: callers
+// can transfer them to COM or copy their pointers into other ctypes objects.
+#[cfg(windows)]
+pub struct BStr {
+    bytes: [u8; core::mem::size_of::<usize>()],
+    committed: bool,
+}
+
+#[cfg(windows)]
+impl BStr {
+    pub fn new(units: Option<&[u16]>) -> Option<Self> {
+        let address = match units {
+            Some(units) => crate::windows::sys_alloc_string_len(units)? as usize,
+            None => 0,
+        };
+        Some(Self {
+            bytes: address.to_ne_bytes(),
+            committed: false,
+        })
+    }
+
+    pub fn bytes(&self) -> &[u8] {
+        &self.bytes
+    }
+
+    pub fn commit(&mut self) {
+        self.committed = true;
+    }
+
+    /// # Safety
+    /// The old slot must contain NULL or a valid, live COM BSTR.
+    pub unsafe fn replace(&mut self, previous: &[u8]) {
+        let address = read_pointer_from_buffer(previous);
+        crate::windows::sys_free_string(address as *const u16);
+        self.commit();
+    }
+}
+
+#[cfg(windows)]
+impl Drop for BStr {
+    fn drop(&mut self) {
+        if !self.committed {
+            crate::windows::sys_free_string(read_pointer_from_buffer(&self.bytes) as *const u16);
+        }
+    }
+}
+
+#[cfg(windows)]
+unsafe fn decode_bstr(address: usize) -> DecodedValue {
+    if address == 0 {
+        return DecodedValue::None;
+    }
+    let pointer = address as *const u16;
+    let len = crate::windows::sys_string_len(pointer);
+    let units = unsafe { core::slice::from_raw_parts(pointer, len) };
+    DecodedValue::WideString(Wtf8Buf::from_wide(units))
+}
+
 pub enum DecodedValue {
     Bytes(Vec<u8>),
     Signed(i64),
@@ -616,6 +675,8 @@ pub enum DecodedValue {
     Bool(bool),
     Pointer(usize),
     String(String),
+    #[cfg(windows)]
+    WideString(Wtf8Buf),
     None,
 }
 
@@ -843,6 +904,8 @@ pub fn read_array_element(
                 }
             }
         }
+        #[cfg(windows)]
+        Some("X") => unsafe { decode_bstr(read_pointer_from_buffer(rest)) },
         Some("f") => DecodedValue::Float(
             rest.first_chunk::<4>()
                 .copied()
@@ -1276,6 +1339,8 @@ pub fn decode_type_code(type_code: &str, bytes: &[u8]) -> DecodedValue {
                 None => DecodedValue::None,
             }
         },
+        #[cfg(windows)]
+        "X" => unsafe { decode_bstr(read_pointer_from_buffer(bytes)) },
         "P" => DecodedValue::Pointer(read_pointer_from_buffer(bytes)),
         "u" => {
             let val = if bytes.len() >= core::mem::size_of::<WChar>() {
@@ -1300,6 +1365,8 @@ pub fn decode_type_code(type_code: &str, bytes: &[u8]) -> DecodedValue {
 /// `type_code`.
 pub unsafe fn callback_arg_value(type_code: Option<&str>, ptr: *const c_void) -> DecodedValue {
     match type_code {
+        #[cfg(windows)]
+        Some("X") => unsafe { decode_bstr(core::ptr::read_unaligned(ptr.cast::<usize>())) },
         Some("b") => DecodedValue::Signed(unsafe { *(ptr as *const i8) as i64 }),
         Some("B") => DecodedValue::Unsigned(unsafe { *(ptr as *const u8) as u64 }),
         Some("c") => DecodedValue::Bytes(vec![unsafe { *(ptr as *const u8) }]),
@@ -1398,7 +1465,7 @@ pub unsafe fn write_callback_result(
         (Some("Q"), CallbackResultValue::Unsigned(v)) => unsafe { *(result as *mut u64) = v },
         (Some("f"), CallbackResultValue::Float(v)) => unsafe { *(result as *mut f32) = v as f32 },
         (Some("d"), CallbackResultValue::Float(v)) => unsafe { *(result as *mut f64) = v },
-        (Some("P" | "z" | "Z"), CallbackResultValue::Pointer(v)) => unsafe {
+        (Some("P" | "z" | "Z" | "X"), CallbackResultValue::Pointer(v)) => unsafe {
             *(result as *mut usize) = v
         },
         (Some("?"), CallbackResultValue::Bool(v)) => unsafe { *(result as *mut u8) = u8::from(v) },
@@ -1449,7 +1516,7 @@ pub fn ffi_value_from_type_code(type_code: &str, buffer: &[u8]) -> FfiValue {
                 .copied()
                 .map_or(0.0, f64::from_ne_bytes),
         ),
-        "z" | "Z" | "P" | "O" => FfiValue::Pointer(read_pointer_from_buffer(buffer)),
+        "z" | "Z" | "P" | "X" | "O" => FfiValue::Pointer(read_pointer_from_buffer(buffer)),
         "?" => FfiValue::U8(u8::from(buffer.first().is_some_and(|&b| b != 0))),
         "u" => FfiValue::U32(buffer.first_chunk().copied().map_or(0, u32::from_ne_bytes)),
         _ => FfiValue::Pointer(0),
@@ -2529,7 +2596,7 @@ pub unsafe fn read_value_at_address(
         Some("d" | "g") => {
             AddressValue::Float(unsafe { core::ptr::read_unaligned(ptr as *const f64) })
         }
-        Some("P" | "z" | "Z") => {
+        Some("P" | "z" | "Z" | "X") => {
             AddressValue::Pointer(unsafe { core::ptr::read_unaligned(ptr as *const usize) })
         }
         _ => AddressValue::Bytes(unsafe { bytes_at(ptr, size) }),
@@ -3043,6 +3110,59 @@ pub fn dlsym_checked(_handle: usize, symbol_name: &CStr) -> Result<*mut c_void,
 mod tests {
     use super::*;
 
+    #[cfg(all(
+        any(
+            target_os = "linux",
+            target_os = "macos",
+            target_os = "windows",
+            target_os = "android"
+        ),
+        not(any(target_env = "musl", target_env = "sgx"))
+    ))]
+    #[test]
+    fn bstr_foreign_argument_preserves_pointer() {
+        let address = usize::MAX;
+        assert!(matches!(
+            ffi_value_from_type_code("X", &address.to_ne_bytes()),
+            FfiValue::Pointer(value) if value == address
+        ));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn bstr_roundtrip_and_replacement() {
+        // Embedded NUL, a surrogate pair, and an unpaired surrogate must survive.
+        let units = [0x61, 0, 0xd83d, 0xde00, 0xd800];
+        let mut slot = 0usize.to_ne_bytes();
+        let mut value = BStr::new(Some(&units)).expect("SysAllocStringLen");
+        unsafe {
+            value.replace(&slot);
+        }
+        slot.copy_from_slice(value.bytes());
+        drop(value);
+        match decode_type_code("X", &slot) {
+            DecodedValue::WideString(value) => {
+                assert_eq!(value.encode_wide().collect::<Vec<_>>(), units)
+            }
+            _ => panic!("expected BSTR string"),
+        }
+        let mut empty = BStr::new(Some(&[])).expect("empty BSTR");
+        unsafe {
+            empty.replace(&slot);
+        }
+        slot.copy_from_slice(empty.bytes());
+        drop(empty);
+        assert!(
+            matches!(decode_type_code("X", &slot), DecodedValue::WideString(value) if value.is_empty())
+        );
+        let mut null = BStr::new(None).unwrap();
+        unsafe {
+            null.replace(&slot);
+        }
+        slot.copy_from_slice(null.bytes());
+        assert!(matches!(decode_type_code("X", &slot), DecodedValue::None));
+    }
+
     #[test]
     fn bstr_storage_preserves_pointer_width() {
         for address in [0, usize::MAX] {

diff --git a/crates/vm/src/stdlib/_ctypes/array.rs b/crates/vm/src/stdlib/_ctypes/array.rs
@@ -594,6 +594,8 @@ impl PyCArray {
             DecodedValue::Float(value) => vm.ctx.new_float(value).into(),
             DecodedValue::Signed(value) => vm.ctx.new_int(value).into(),
             DecodedValue::Unsigned(value) => vm.ctx.new_int(value).into(),
+            #[cfg(windows)]
+            DecodedValue::WideString(value) => vm.ctx.new_str(value).into(),
             DecodedValue::None => vm.ctx.none(),
             DecodedValue::Pointer(value) => vm.ctx.new_int(value).into(),
             DecodedValue::Bool(value) => vm.ctx.new_bool(value).into(),
@@ -633,7 +635,7 @@ impl PyCArray {
         } else {
             super::base::CDataWrite::default()
         };
-        let prepared = super::base::CDataValue::new(
+        let mut prepared = super::base::CDataValue::new(
             &element_type,
             value,
             element_size,
@@ -642,7 +644,7 @@ impl PyCArray {
         )?;
         write.publish(vm)?;
         zelf.0
-            .write_bytes_at_offset(index * element_size, &prepared.bytes);
+            .write_value_at_offset(index * element_size, &mut prepared.bytes);
         prepared.keep(&zelf.0, index, vm)
     }
 

diff --git a/crates/vm/src/stdlib/_ctypes/base.rs b/crates/vm/src/stdlib/_ctypes/base.rs
@@ -1078,8 +1078,34 @@ impl DictKey for ObjectIdKey {
 // Prepare conversions and ownership before writing. Python conversion hooks
 // and old-owner finalizers must never run with a storage or metadata lock held.
 pub(super) enum CDataBytes {
-    Integer { bytes: [u8; 8], size: usize },
+    Integer {
+        bytes: [u8; 8],
+        size: usize,
+    },
     Owned(Vec<u8>),
+    #[cfg(windows)]
+    BStr(rustpython_host_env::ctypes::BStr),
+}
+
+impl CDataBytes {
+    // Arguments have no previous destination, but still transfer ownership.
+    pub(super) fn commit(&mut self) {
+        #[cfg(windows)]
+        if let Self::BStr(bstr) = self {
+            bstr.commit();
+        }
+    }
+
+    // The destination follows ctypes' caller-provided valid-pointer contract.
+    pub(super) fn replace(&mut self, _previous: &[u8]) {
+        #[cfg(windows)]
+        if let Self::BStr(bstr) = self {
+            // SAFETY: BSTR setters require NULL or a live COM allocation.
+            unsafe {
+                bstr.replace(_previous);
+            }
+        }
+    }
 }
 
 impl From<Vec<u8>> for CDataBytes {
@@ -1095,6 +1121,8 @@ impl core::ops::Deref for CDataBytes {
         match self {
             Self::Integer { bytes, size } => &bytes[..*size],
             Self::Owned(bytes) => bytes,
+            #[cfg(windows)]
+            Self::BStr(bstr) => bstr.bytes(),
         }
     }
 }
@@ -1498,6 +1526,15 @@ impl PyCData {
         write_cow_bytes_at_offset(&mut buffer, offset, bytes);
     }
 
+    pub(super) fn write_value_at_offset(&self, offset: usize, bytes: &mut CDataBytes) {
+        let mut buffer = self.buffer.write();
+        let Some(previous) = buffer.get(offset..offset.saturating_add(bytes.len())) else {
+            return;
+        };
+        bytes.replace(previous);
+        write_cow_bytes_at_offset(&mut buffer, offset, bytes);
+    }
+
     /// Generate unique key for nested references (unique_key)
     /// Creates a hierarchical key by walking up the b_base chain.
     /// Format: "index:parent_index:grandparent_index:..."
@@ -2984,9 +3021,9 @@ impl PyCData {
         } else {
             CDataWrite::default()
         };
-        let prepared = CDataValue::new(proto_type, &value, size, needs_swap, vm)?;
+        let mut prepared = CDataValue::new(proto_type, &value, size, needs_swap, vm)?;
         write.publish(vm)?;
-        self.write_bytes_at_offset(offset, &prepared.bytes);
+        self.write_value_at_offset(offset, &mut prepared.bytes);
         prepared.keep(self, index, vm)
     }
 
@@ -3994,6 +4031,10 @@ pub(super) fn bytes_to_pyobject(
             rustpython_host_env::ctypes::DecodedValue::String(value) => {
                 vm.ctx.new_str(value).into()
             }
+            #[cfg(windows)]
+            rustpython_host_env::ctypes::DecodedValue::WideString(value) => {
+                vm.ctx.new_str(value).into()
+            }
             rustpython_host_env::ctypes::DecodedValue::None => vm.ctx.none(),
         };
     }

diff --git a/crates/vm/src/stdlib/_ctypes/function.rs b/crates/vm/src/stdlib/_ctypes/function.rs
@@ -1979,6 +1979,23 @@ fn ffi_to_python(
     }
 
     let type_code = ty.type_code(vm);
+    #[cfg(windows)]
+    if type_code.as_deref() == Some("X") && is_simple_subclass(ty, vm) {
+        // CPython constructs non-direct simple subclasses without arguments,
+        // then copies the slot. Decoding and reconstructing a BSTR would allocate
+        // a different COM string and lose the caller's pointer identity.
+        let rustpython_host_env::ctypes::DecodedValue::Pointer(address) =
+            (unsafe { rustpython_host_env::ctypes::callback_arg_value_at(Some("P"), args, index) })
+        else {
+            return Err(vm.new_type_error("invalid BSTR callback argument"));
+        };
+        let instance = ty.as_object().call((), vm)?;
+        let cdata = instance
+            .downcast_ref::<PyCData>()
+            .ok_or_else(|| vm.new_type_error("BSTR constructor returned a non-ctypes object"))?;
+        cdata.write_bytes_at_offset(0, &address.to_ne_bytes());
+        return Ok(instance);
+    }
     let raw_value: PyObjectRef = match unsafe {
         rustpython_host_env::ctypes::callback_arg_value_at(type_code.as_deref(), args, index)
     } {
@@ -1989,6 +2006,10 @@ fn ffi_to_python(
         rustpython_host_env::ctypes::DecodedValue::Bool(value) => vm.ctx.new_bool(value).into(),
         rustpython_host_env::ctypes::DecodedValue::Pointer(value) => vm.ctx.new_int(value).into(),
         rustpython_host_env::ctypes::DecodedValue::String(value) => vm.ctx.new_str(value).into(),
+        #[cfg(windows)]
+        rustpython_host_env::ctypes::DecodedValue::WideString(value) => {
+            vm.ctx.new_str(value).into()
+        }
         rustpython_host_env::ctypes::DecodedValue::None => vm.ctx.none(),
     };
 
@@ -2044,6 +2065,31 @@ fn python_to_ffi(obj: PyResult, ty: &Py<PyType>, result: *mut c_void, vm: &Virtu
                 }
             }
         }
+        #[cfg(windows)]
+        Some("X") => {
+            match super::simple::assignment_value("X", &obj, false, vm) {
+                Ok((mut bytes, _, _)) => {
+                    let address = rustpython_host_env::ctypes::read_pointer_from_buffer(&bytes);
+                    // libffi's result slot is fresh storage, not a previous BSTR.
+                    bytes.commit();
+                    unsafe {
+                        rustpython_host_env::ctypes::write_callback_result(
+                            Some("X"),
+                            result,
+                            rustpython_host_env::ctypes::CallbackResultValue::Pointer(address),
+                        );
+                    }
+                }
+                Err(exc) => vm.run_unraisable(
+                    exc,
+                    Some(
+                        "Exception ignored while converting result of ctypes callback function"
+                            .to_owned(),
+                    ),
+                    obj,
+                ),
+            }
+        }
         Some("P" | "z" | "Z") => {
             if let Ok(i) = obj.try_int(vm) {
                 unsafe {

diff --git a/crates/vm/src/stdlib/_ctypes/pointer.rs b/crates/vm/src/stdlib/_ctypes/pointer.rs
@@ -596,7 +596,7 @@ impl PyCPointer {
         } else {
             super::base::CDataWrite::default()
         };
-        let prepared = super::base::CDataValue::new(
+        let mut prepared = super::base::CDataValue::new(
             &proto_type,
             &value,
             element_size,
@@ -607,6 +607,9 @@ impl PyCPointer {
         // SAFETY: pointer indexing has the same caller-provided valid-storage
         // requirement as reading the element. The source snapshot cannot overlap it.
         unsafe {
+            let previous =
+                rustpython_host_env::ctypes::borrow_memory(addr as *const u8, element_size);
+            prepared.bytes.replace(previous);
             rustpython_host_env::ctypes::copy_bytes_to_address(addr, &prepared.bytes, element_size);
         }
         prepared.keep(&zelf.0, index as usize, vm)