@gjsify/node-gi 0.45.0 → 0.46.0

package/src/marshal.cc

@@ -296,6 +296,28 @@ bool TryGetBoxedPtr(Napi::Value v, gpointer* out) {
   return true;
 }
 
+// __boxedAddress(value) -> the address a boxed handle wraps, as a hex string, or
+// null when `value` is not one. TEST-ONLY (the `__` prefix marks it, as on the
+// __stressRefUnref* pair) — nothing on the runtime path may branch on it.
+//
+// It exists because the IN-transfer ownership rules are statements about POINTER
+// IDENTITY ("a transfer-full boxed IN arg gets an independent copy, never the
+// block this handle still owns"), and nothing else could observe one. The tests
+// guarding them ran the call many times and waited for a double free to abort —
+// which only happens if the allocator has NOT recycled the block between the two
+// frees. Measured while reviewing #1496: with `TransferBoxedIn` replaced by a bare
+// borrow — a real double free on every round — `gerror-out.test.mjs` passed 5 runs
+// out of 5, and the same program under valgrind reported 0 errors. An identity
+// assertion fails on the first round instead.
+Napi::Value BoxedAddress(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  gpointer ptr = nullptr;
+  if (info.Length() < 1 || !TryGetBoxedPtr(info[0], &ptr)) return env.Null();
+  char buf[2 + sizeof(gpointer) * 2 + 1];
+  g_snprintf(buf, sizeof(buf), "%p", ptr);
+  return Napi::String::New(env, buf);
+}
+
 // boxedTypeName(value) -> the boxed handle's GType name (e.g. "GBytes"), or null
 // when the handle carries no registered GType. Lets the L1 layer attach a
 // type-specific convenience (GLib.Bytes.toArray) without a per-type wrapper.
@@ -441,6 +463,55 @@ static const char* InformalValueTypeName(const Napi::Value& v) {
   return "Object";
 }
 
+// The refusal a GError-typed IN arg raises, named after the argument the way gjs
+// names its marshalling errors.
+static void ThrowExpectedGLibError(Napi::Env env, const char* argName, const std::string& got) {
+  std::string where = argName != nullptr ? std::string("argument '") + argName + "'" : "argument";
+  Napi::TypeError::New(env, "expected a GLib.Error for " + where + ", got " + got)
+      .ThrowAsJavaScriptException();
+}
+
+// Whether `v` is an instance of the L1 `GLib.Error` class — the shape a `catch`
+// around a failed GI invoke hands you, and what `new GLib.Error(domain, code,
+// message)` builds. Recognition is `instanceof` against the class L1 registered
+// alongside its error builder, never duck-typing: a plain object carrying a
+// `code` must still be refused.
+static bool IsL1GLibError(Napi::Env env, Napi::Value v) {
+  if (!v.IsObject()) return false;
+  NodeGiEnvData* d = EnvData(env);
+  if (d == nullptr || d->errorClass == nullptr) return false;
+  napi_value cls = nullptr;
+  if (napi_get_reference_value(env, d->errorClass, &cls) != napi_ok || cls == nullptr) return false;
+  Napi::Value clsValue(env, cls);
+  return clsValue.IsFunction() && v.As<Napi::Object>().InstanceOf(clsValue.As<Napi::Function>());
+}
+
+// Build a real GError out of an L1 `GLib.Error`, which carries no `GError*` of
+// its own. Throws + returns nullptr when its domain is unusable.
+//
+// `.domainQuark` is the numeric GQuark the engine read off the original GError;
+// `.domain` is its NAME (the node-gi divergence documented in
+// docs/node-gi-gjs-surface.md), which is what an error constructed in JS from a
+// quark name carries. Either resolves to the same quark; a value with neither is
+// not a usable GError — quark 0 would produce an error no `matches()` can ever
+// answer for, so it is refused rather than marshalled into a silent mismatch.
+static GError* ErrorFromL1GLibError(Napi::Env env, Napi::Value v, const char* argName) {
+  Napi::Object err = v.As<Napi::Object>();
+  Napi::Value quark = err.Get("domainQuark");
+  Napi::Value domain = err.Get("domain");
+  GQuark gq = 0;
+  if (quark.IsNumber()) gq = static_cast<GQuark>(NodeGiToUint32(quark));
+  else if (domain.IsString())
+    gq = g_quark_from_string(domain.As<Napi::String>().Utf8Value().c_str());
+  if (gq == 0) {
+    ThrowExpectedGLibError(env, argName, "a GLib.Error with no domain");
+    return nullptr;
+  }
+  Napi::Value message = err.Get("message");
+  std::string text = message.IsString() ? message.As<Napi::String>().Utf8Value() : std::string();
+  return g_error_new_literal(gq, NodeGiToInt32(err.Get("code")), text.c_str());
+}
+
 // "Gtk.Box" for an introspected GType, g_type_name() otherwise (a registerClass
 // subtype has no GI info of its own; its C name is still exact). The gjs twin is
 // GIWrapperBase::format_name() (refs/gjs/gi/wrapperutils.h).
@@ -469,6 +540,7 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
                     CreatedClosures* closures,
                     CreatedBytes* bytes,
                     CreatedValues* values,
+                    CreatedErrors* errors,
                     const char* argName) {
   if (v.IsEmpty()) {
     // Residue of a swallowed napi failure (a fallible Get()/coercion upstream
@@ -712,6 +784,54 @@ bool JsToGIArgument(Napi::Env env, Napi::Value v, GITypeInfo* type, GIArgument*
       out->v_size = static_cast<gsize>(gt);
       return true;
     }
+    case GI_TYPE_TAG_ERROR: {
+      // A GError IN/INOUT argument: `Gst.Message.new_error(src, error, debug)` —
+      // how an application POSTS the failure the bus accessors read back —
+      // `GLib.propagate_error`, and the INOUT `err` of `GLib.prefix_error_literal`.
+      // null/undefined → a NULL GError, the same leniency the object/boxed arms
+      // keep (gjs refuses both for a non-nullable arg — status/open-todos.md).
+      if (v.IsNull() || v.IsUndefined()) {
+        out->v_pointer = nullptr;
+        return true;
+      }
+      // Shape 1: the boxed handle a GError-typed return/OUT produced. Ownership is
+      // the ordinary boxed one and TransferBoxedIn supplies it: transfer-none is a
+      // borrow, transfer-full hands the callee an independent g_error_copy
+      // (g_propagate_error ADOPTS and frees its `src`) so the JS handle's finalizer
+      // cannot double-free it. Measured against gjs: after `GLib.propagate_error(e)`
+      // the original `e` is still readable there too.
+      //
+      // Type-safety is UNCONDITIONAL here, unlike the struct/boxed arm's "compare
+      // only when both sides carry a registered GType": the expected type is known
+      // (G_TYPE_ERROR, always), so a handle without it is a wrong pointer — and a
+      // wrong pointer in a GError slot is a wild dereference inside GLib.
+      BoxedHandle* h = TryGetBoxedHandle(v);
+      if (h != nullptr) {
+        if (h->gtype == G_TYPE_INVALID || !g_type_is_a(h->gtype, G_TYPE_ERROR)) {
+          ThrowExpectedGLibError(env, argName,
+                                 h->gtype != G_TYPE_INVALID ? g_type_name(h->gtype)
+                                                            : InformalValueTypeName(v));
+          return false;
+        }
+        out->v_pointer = TransferBoxedIn(h, transfer);
+        return true;
+      }
+      // Shape 2: the L1 `GLib.Error` JS class — a caught error, or one built with
+      // `new GLib.Error(…)`. It carries no GError*, so build one and release it per
+      // transfer (CreatedErrors, the rule GBytes and GValue already follow). gjs has
+      // ONE object for both shapes and accepts either; refusing this one left the
+      // hand-back the OUT direction exists for closed to exactly the errors an
+      // application has in hand.
+      if (errors != nullptr && IsL1GLibError(env, v)) {
+        GError* built = ErrorFromL1GLibError(env, v, argName);
+        if (built == nullptr) return false;  // ErrorFromL1GLibError already threw
+        out->v_pointer = built;
+        errors->Record(built, transfer);
+        return true;
+      }
+      ThrowExpectedGLibError(env, argName, InformalValueTypeName(v));
+      return false;
+    }
     default:
       Napi::TypeError::New(
           env, "Unsupported IN argument type tag " + std::to_string(static_cast<int>(tag)) +
@@ -892,10 +1012,35 @@ Napi::Value GIArgumentToJs(Napi::Env env, GITypeInfo* type, GIArgument* arg,
 //    pass it, and free it (container + any g_strdup'd strings) AFTER the invoke.
 //    TRANSFER_EVERYTHING / TRANSFER_CONTAINER means the callee adopts what we
 //    built — we must NOT free it (that would UAF / double-free).
+//  * IN, PER ELEMENT: the container transfer also decides who owns the ELEMENTS,
+//    and the two answers differ. CONTAINER hands over only the container, so the
+//    elements stay ours and a borrowed pointer is right. EVERYTHING hands over the
+//    elements TOO — a borrowed object/boxed pointer there is freed by the callee
+//    AND by the JS handle that still owns it. Measured on the pointer-struct case
+//    the moment it was admitted: `Pango.Font.descriptions_free([desc])` (`descs` is
+//    `(transfer full)`) read back garbage and died in `free(): invalid size`. So
+//    ElementToGIArgument takes the ELEMENT transfer — NOTHING for a borrow (incl.
+//    CONTAINER), EVERYTHING for adoption, exactly the rule the read side already
+//    uses — and refs/copies on EVERYTHING. Strings were always right (g_strdup'd
+//    per element either way).
+//  * IN, ROOTING: a borrowed element pointer stays valid across the invoke because
+//    the JS array is an ARGUMENT of the running native call — it and everything
+//    reachable from it are held by that call's handle scope, which is not popped
+//    until we return. So nothing can be collected between building the container
+//    and the callee reading it, not even an element a getter/Proxy synthesised.
 
 // Element-type support shared by every container kind. *why receives a short
 // label on refusal (so the caller can throw a precise deferral message).
-static bool IsSupportedElementType(GITypeInfo* elem, std::string* why) {
+//
+// `byValueOk` is true only where the element is a SIZED CELL the IN path lays out
+// itself — a C array being built for an IN argument. It is false for a read-back
+// (ReadCElement still dereferences an interface element as a pointer) and false for
+// GList/GSList/GHashTable, whose elements are POINTER slots filled through
+// gi_type_info_hash_pointer_from_argument: that helper passes a pointer through
+// unchanged, which is right for a pointer-struct element and meaningless for a
+// four-byte enum or a twenty-four-byte record. So the by-value admission is scoped to
+// the one container kind that has somewhere to put the bytes.
+static bool IsSupportedElementType(GITypeInfo* elem, std::string* why, bool byValueOk) {
   switch (gi_type_info_get_tag(elem)) {
     case GI_TYPE_TAG_BOOLEAN:
     case GI_TYPE_TAG_INT8:
@@ -914,6 +1059,39 @@ static bool IsSupportedElementType(GITypeInfo* elem, std::string* why) {
     case GI_TYPE_TAG_INTERFACE: {
       GIBaseInfo* iface = gi_type_info_get_interface(elem);
       bool ok = iface != nullptr && (GI_IS_OBJECT_INFO(iface) || GI_IS_INTERFACE_INFO(iface));
+      // A struct element that is a POINTER occupies exactly one pointer slot, which is
+      // the same shape an object element already has: CElementSize answers
+      // sizeof(gpointer) and the write loop memcpy's the low 8 bytes.
+      // `GLib.Variant.new_tuple` is the call this unblocks: measured against the
+      // installed typelib, its `children` element is `tag=interface ptr=1 kind=STRUCT`.
+      //
+      // Admission alone was NOT enough, and the reading that said it was is worth
+      // keeping: "FreeInContainer's non-string branch already frees the buffer without
+      // touching what the pointers point at" is true and beside the point, because
+      // FreeInContainer runs only for TRANSFER_NOTHING. On a (transfer full) container
+      // the CALLEE frees the elements — see the per-element half of the OWNERSHIP note
+      // above and ElementToGIArgument, which is where that is now handled.
+      //
+      // A BY-VALUE struct element stays refused, and the distinction is the whole point
+      // of testing is_pointer here rather than the kind alone: `Gtk.Accessible
+      // .update_property`'s values are `ptr=0 kind=STRUCT size=24`, so admitting them
+      // would lay 24-byte GValues out at an 8-byte stride and hand the callee garbage.
+      // That case needs gi_struct_info_get_size plus an ownership rule (each in-place
+      // g_value_init would need unsetting, and FreeInContainer has no branch for it) —
+      // the same deferred work this file already records at its CALLER_ALLOCATES site.
+      if (!ok && iface != nullptr && GI_IS_STRUCT_INFO(iface) && gi_type_info_is_pointer(elem)) {
+        ok = true;
+      }
+      // BY-VALUE elements, admitted only where there is a sized cell to write them
+      // into (see `byValueOk`). An enum/flags element is its storage integer; a
+      // record/union element is its own bytes, copied out of a boxed handle. Both go
+      // through CInElementSize + ElementToCArrayCell, which is the write path that
+      // does NOT run the GIArgument union through memcpy — see the note there.
+      if (!ok && byValueOk && iface != nullptr && !gi_type_info_is_pointer(elem) &&
+          (GI_IS_ENUM_INFO(iface) || GI_IS_FLAGS_INFO(iface) || GI_IS_STRUCT_INFO(iface) ||
+           GI_IS_UNION_INFO(iface))) {
+        ok = true;
+      }
       if (!ok && why != nullptr) *why = "struct/union/enum element";
       if (iface != nullptr) gi_base_info_unref(iface);
       return ok;
@@ -929,7 +1107,7 @@ static bool IsSupportedElementType(GITypeInfo* elem, std::string* why) {
 // up front. Array-type kind is intentionally NOT restricted here — the read side
 // (GIArrayToJs) handles C/BYTE_ARRAY/GArray/GPtrArray; the IN side rejects
 // GArray/GPtrArray separately (they're rare as IN in headless GLib).
-bool IsSupportedContainerType(GITypeInfo* type, std::string* why) {
+bool IsSupportedContainerType(GITypeInfo* type, std::string* why, ContainerUse use) {
   switch (gi_type_info_get_tag(type)) {
     case GI_TYPE_TAG_ARRAY:
     case GI_TYPE_TAG_GLIST:
@@ -939,7 +1117,14 @@ bool IsSupportedContainerType(GITypeInfo* type, std::string* why) {
         if (why != nullptr) *why = "untyped container";
         return false;
       }
-      bool ok = IsSupportedElementType(elem, why);
+      // A by-value element needs a sized cell, which only a C array being BUILT has.
+      // GArray is deliberately excluded alongside the lists: its elements are sized,
+      // but g_array_append_vals copies from a buffer this path would have to size the
+      // same way, and no installed typelib has a by-value-element GArray as IN.
+      bool byValueOk = use == ContainerUse::kIn &&
+                       gi_type_info_get_tag(type) == GI_TYPE_TAG_ARRAY &&
+                       gi_type_info_get_array_type(type) == GI_ARRAY_TYPE_C;
+      bool ok = IsSupportedElementType(elem, why, byValueOk);
       gi_base_info_unref(elem);
       return ok;
     }
@@ -954,7 +1139,7 @@ bool IsSupportedContainerType(GITypeInfo* type, std::string* why) {
                  ktag == GI_TYPE_TAG_INT8 || ktag == GI_TYPE_TAG_UINT8 ||
                  ktag == GI_TYPE_TAG_INT16 || ktag == GI_TYPE_TAG_UINT16 ||
                  ktag == GI_TYPE_TAG_INT32 || ktag == GI_TYPE_TAG_UINT32;
-      bool vok = vt != nullptr && IsSupportedElementType(vt, nullptr);
+      bool vok = vt != nullptr && IsSupportedElementType(vt, nullptr, false);
       if (!kok && why != nullptr) *why = "unsupported GHashTable key";
       else if (!vok && why != nullptr) *why = "unsupported GHashTable value";
       if (kt != nullptr) gi_base_info_unref(kt);
@@ -988,6 +1173,88 @@ size_t CElementSize(GITypeInfo* elem) {
   }
 }
 
+// Storage size of one C-array element on the IN path, INCLUDING the by-value
+// interface elements CElementSize declines to size.
+//
+// Deliberately NOT folded into CElementSize, and the split is a scope statement rather
+// than duplication: CElementSize is also the READ stride (GIArrayToJs), where a
+// by-value interface element is still unreadable — ReadCElement dereferences it as a
+// pointer, which is why ElementsAreReadable exists. Teaching CElementSize the true
+// size there would turn a wrong stride in front of a wrong read into a RIGHT stride in
+// front of a wrong read: more plausible output, the same defect. Opening the read side
+// is separate work (this file records it at the inline-record field path and calls.cc
+// records it at CALLER_ALLOCATES); until then the IN path answers for itself. Every
+// non-interface tag delegates, so the two answers cannot drift.
+//
+// An enum's size is its OWN storage type, not a hardcoded 4: gi_enum_info_get_storage
+// _type is what the typelib records for the C enum, and gjs's sizeof(unsigned int) is
+// an assumption this does not have to inherit.
+static size_t CInElementSize(GITypeInfo* elem) {
+  if (gi_type_info_get_tag(elem) != GI_TYPE_TAG_INTERFACE) return CElementSize(elem);
+  if (gi_type_info_is_pointer(elem)) return sizeof(gpointer);
+  GIBaseInfo* iface = gi_type_info_get_interface(elem);
+  if (iface == nullptr) return sizeof(gpointer);
+  size_t size;
+  if (GI_IS_ENUM_INFO(iface) || GI_IS_FLAGS_INFO(iface)) {
+    switch (gi_enum_info_get_storage_type(reinterpret_cast<GIEnumInfo*>(iface))) {
+      case GI_TYPE_TAG_INT8:
+      case GI_TYPE_TAG_UINT8: size = 1; break;
+      case GI_TYPE_TAG_INT16:
+      case GI_TYPE_TAG_UINT16: size = 2; break;
+      case GI_TYPE_TAG_INT64:
+      case GI_TYPE_TAG_UINT64: size = 8; break;
+      default: size = 4; break;  // int32/uint32 and anything unannotated
+    }
+  } else if (GI_IS_STRUCT_INFO(iface)) {
+    size = gi_struct_info_get_size(reinterpret_cast<GIStructInfo*>(iface));
+  } else if (GI_IS_UNION_INFO(iface)) {
+    size = gi_union_info_get_size(reinterpret_cast<GIUnionInfo*>(iface));
+  } else {
+    size = sizeof(gpointer);  // object/interface instance: one pointer slot
+  }
+  gi_base_info_unref(iface);
+  return size;
+}
+
+// Whether an element is a by-value RECORD (struct or union) — the one kind that must
+// not travel through a GIArgument. See ByValueRecordToCell.
+static bool IsByValueRecordElement(GITypeInfo* elem) {
+  if (gi_type_info_get_tag(elem) != GI_TYPE_TAG_INTERFACE) return false;
+  if (gi_type_info_is_pointer(elem)) return false;
+  GIBaseInfo* iface = gi_type_info_get_interface(elem);
+  if (iface == nullptr) return false;
+  bool record = GI_IS_STRUCT_INFO(iface) || GI_IS_UNION_INFO(iface);
+  gi_base_info_unref(iface);
+  return record;
+}
+
+// The GType of a by-value record element, or G_TYPE_INVALID for an unregistered one.
+static GType ByValueRecordGType(GITypeInfo* elem) {
+  GIBaseInfo* iface = gi_type_info_get_interface(elem);
+  if (iface == nullptr) return G_TYPE_INVALID;
+  GType gtype = GI_IS_REGISTERED_TYPE_INFO(iface)
+                    ? gi_registered_type_info_get_g_type(
+                          reinterpret_cast<GIRegisteredTypeInfo*>(iface))
+                    : G_TYPE_INVALID;
+  gi_base_info_unref(iface);
+  return gtype == G_TYPE_NONE ? G_TYPE_INVALID : gtype;
+}
+
+// Whether a by-value record element array is one this path OWNS the contents of —
+// true only for GValue, the one element kind written by initialising in place rather
+// than by copying a caller's bytes. FreeInContainer needs the same answer, so it is
+// derived from the type both times instead of carried in InContainer: a flag would be
+// a second truth that a later element kind could get wrong in only one of the places.
+static bool ElementsAreOwnedGValues(GITypeInfo* type) {
+  if (gi_type_info_get_tag(type) != GI_TYPE_TAG_ARRAY) return false;
+  if (gi_type_info_get_array_type(type) != GI_ARRAY_TYPE_C) return false;
+  GITypeInfo* elem = gi_type_info_get_param_type(type, 0);
+  if (elem == nullptr) return false;
+  bool owned = IsByValueRecordElement(elem) && ByValueRecordGType(elem) == G_TYPE_VALUE;
+  gi_base_info_unref(elem);
+  return owned;
+}
+
 // Write the array's element count into a length arg's GIArgument slot (IN length
 // autofill). The field is selected by the length arg's own tag; the slot is
 // zero-initialised so writing the matching field is correct on little-endian
@@ -1006,6 +1273,29 @@ void WriteLengthValue(GITypeInfo* lenType, GIArgument* slot, long n) {
   }
 }
 
+// Two array arguments can name the SAME length argument — `Gtk.Accessible
+// .update_property(n, properties[], values[])` is the shape, and `update_state` and
+// `update_relation` repeat it. The autofill writes that argument once per array, so the
+// LAST array silently decides the count the callee then reads BOTH arrays by; a shorter
+// one is read past its end, inside the callee, with nothing on this side to attribute it
+// to afterwards.
+//
+// gjs does not check this — measured on 1.88.1: `update_property([LABEL, DESCRIPTION],
+// ['only one'])` is accepted and reads out of bounds. Refusing it is therefore a
+// deliberate divergence, and the cheaper side of one: the caller passed two arrays that
+// cannot both be right, and the alternative to a TypeError is an overread.
+bool RecordLengthWrite(std::vector<LengthWrite>* seen, unsigned int index, long count,
+                       long* other) {
+  for (const LengthWrite& w : *seen) {
+    if (w.index != index) continue;
+    if (w.count == count) return true;
+    if (other != nullptr) *other = w.count;
+    return false;
+  }
+  seen->push_back(LengthWrite{index, count});
+  return true;
+}
+
 // Read a length value the callee wrote into a length arg's slot (OUT length).
 static long ReadLengthValue(GITypeInfo* lenType, GIArgument* slot) {
   switch (gi_type_info_get_tag(lenType)) {
@@ -1285,10 +1575,14 @@ Napi::Value ReadOutOrReturn(Napi::Env env, GICallableInfo* callable, GITypeInfo*
   }
 }
 
-// Fill a GIArgument for a single list/hash element from a JS value. Strings are
-// g_strdup'd (the container owns them); objects contribute their borrowed
-// handle pointer. Throws + returns false on an unsupported element.
-static bool ElementToGIArgument(Napi::Env env, GITypeInfo* elem, Napi::Value v, GIArgument* a) {
+// Fill a GIArgument for a single array/list/hash element from a JS value. Strings
+// are g_strdup'd (the container owns them). `elemTransfer` is the ELEMENT half of
+// the container's transfer (see the OWNERSHIP note above): NOTHING → an object /
+// boxed handle contributes its BORROWED pointer; EVERYTHING → the callee adopts
+// the element, so it gets a ref (objects) or an independent copy (boxed) instead.
+// Throws + returns false on an unsupported element.
+static bool ElementToGIArgument(Napi::Env env, GITypeInfo* elem, Napi::Value v, GIArgument* a,
+                                GITransfer elemTransfer) {
   memset(a, 0, sizeof(*a));
   switch (gi_type_info_get_tag(elem)) {
     // Scalar coercions via the terminate-safe helpers (common.h): a swallowed
@@ -1312,15 +1606,61 @@ static bool ElementToGIArgument(Napi::Env env, GITypeInfo* elem, Napi::Value v,
                         : g_strdup(NodeGiToUtf8(v).c_str());
       return true;
     case GI_TYPE_TAG_INTERFACE: {
+      // A BY-VALUE enum/flags element is a plain JS number, and it is the one interface
+      // element that legitimately reaches this function without a handle. It writes the
+      // member's integer into the union's low bytes; JsToCArray then copies exactly
+      // CInElementSize bytes, which for an enum is its own storage size (1/2/4/8) and
+      // therefore never more than the union holds. Flags take the unsigned field for
+      // the same reason g_value_set_flags does — a mask with the top bit set must not
+      // become negative on its way through.
+      if (!gi_type_info_is_pointer(elem)) {
+        GIBaseInfo* enumIface = gi_type_info_get_interface(elem);
+        if (enumIface != nullptr &&
+            (GI_IS_ENUM_INFO(enumIface) || GI_IS_FLAGS_INFO(enumIface))) {
+          bool isFlags = GI_IS_FLAGS_INFO(enumIface);
+          gi_base_info_unref(enumIface);
+          if (isFlags) {
+            a->v_uint32 = NodeGiToUint32(v);
+          } else {
+            a->v_int32 = NodeGiToInt32(v);
+          }
+          return true;
+        }
+        if (enumIface != nullptr) gi_base_info_unref(enumIface);
+      }
       if (v.IsNull() || v.IsUndefined()) {
         a->v_pointer = nullptr;
         return true;
       }
       if (v.IsExternal() && v.As<Napi::External<GObject>>().CheckTypeTag(&kGObjectHandleTag)) {
-        a->v_pointer = v.As<Napi::External<GObject>>().Data();
+        GObject* obj = v.As<Napi::External<GObject>>().Data();
+        // The callee adopts one ref PER ELEMENT on EVERYTHING (Gdk.ContentProvider
+        // .new_union's `providers`, Gtk.ClosureExpression.new's `params`, the
+        // Gst/GstPbutils `*_list_free` helpers): hand it one it may drop, never the
+        // wrapper's own — that would under-ref and free the object out from under JS.
+        if (obj != nullptr && elemTransfer == GI_TRANSFER_EVERYTHING) g_object_ref(obj);
+        a->v_pointer = obj;
         return true;
       }
-      Napi::TypeError::New(env, "expected a GObject handle as a container element")
+      // A boxed/struct handle contributes its pointer, exactly as an object handle
+      // does. Only reachable for a POINTER struct element — IsSupportedElementType
+      // refuses the by-value kind before the invoke, so no by-value record can arrive
+      // here and be silently treated as a pointer. TransferBoxedIn is the SAME
+      // adopt-or-borrow helper the scalar boxed IN arg uses (g_variant_ref /
+      // g_boxed_copy on EVERYTHING, relinquish for a struct with no copy function),
+      // so a container element and a plain argument cannot drift apart.
+      if (BoxedHandle* boxed = TryGetBoxedHandle(v); boxed != nullptr) {
+        a->v_pointer = TransferBoxedIn(boxed, elemTransfer);
+        return true;
+      }
+      // Everything else refuses LOUDLY here rather than silently contributing a
+      // nullptr. Two element kinds reach this on purpose: a GObject FUNDAMENTAL
+      // (GskRenderNode — object info, so the predicate admits it, but its handle
+      // carries kFundamentalHandleTag) and a FOREIGN struct (cairo, kCairoHandleTag),
+      // neither of which owns its pointer the way the two branches above assume. No
+      // installed typelib has a foreign-struct container element today; if one is
+      // added, route it through ForeignStructOps::to rather than widening this test.
+      Napi::TypeError::New(env, "expected a GObject or boxed handle as a container element")
           .ThrowAsJavaScriptException();
       return false;
     }
@@ -1331,20 +1671,132 @@ static bool ElementToGIArgument(Napi::Env env, GITypeInfo* elem, Napi::Value v,
   }
 }
 
+// The introspected size of a record handle's own type, or 0 when it has none.
+static size_t BoxedInfoSize(GIBaseInfo* info) {
+  if (info == nullptr) return 0;
+  if (GI_IS_STRUCT_INFO(info)) return gi_struct_info_get_size(reinterpret_cast<GIStructInfo*>(info));
+  if (GI_IS_UNION_INFO(info)) return gi_union_info_get_size(reinterpret_cast<GIUnionInfo*>(info));
+  return 0;
+}
+
+// Write ONE by-value record element straight into its C-array cell.
+//
+// WHY THIS IS NOT A GIArgument, which is the whole reason the function exists. The
+// array write loop copies `elemSize` bytes out of a GIArgument — a union, eight bytes
+// wide. A by-value record is its own size: GValue is 24 on this ABI, Gio.ActionEntry
+// 64. Sizing the loop without moving the record off the union would read sixteen bytes
+// past it, off the stack, once per element, and would produce a green build with
+// plausible-looking output. So a record never enters a GIArgument; its bytes are
+// written where they finally live.
+//
+// TWO SOURCES, and only one of them leaves us owning anything:
+//  * GObject.Value — INITIALISED IN PLACE, either from any JS value (gjs 1.88.1
+//    accepts `update_property([Gtk.AccessibleProperty.LABEL], ['text'])`, measured)
+//    or by copying an existing GObject.Value handle. Both end with a GValue THIS call
+//    constructed, so it is unset after the invoke — see ElementsAreOwnedGValues and
+//    FreeInContainer. Copying rather than memcpy'ing a handle's GValue is what makes
+//    that rule uniform: a bitwise copy would share the string or boxed the original
+//    holds, and unsetting it would free the handle's contents underneath JS.
+//  * every other record — COPIED from a boxed handle, which is also what gjs requires
+//    (measured: a plain object is refused there with "not a subclass of
+//    GObject_Struct"). The copy shares whatever the source points at, so nothing here
+//    is freed and the handle keeps owning its own storage across the invoke.
+//
+// THE TYPE CHECK IS A SAFETY PROPERTY rather than ergonomics: copying `elemSize` bytes
+// out of a handle of a DIFFERENT record type reads past the end of the source whenever
+// the source is smaller. So the source must be the element's own type — compared by
+// GType where the element has one, and by introspected size where it does not, an
+// unregistered struct having no GType to compare.
+static bool ByValueRecordToCell(Napi::Env env, GITypeInfo* elem, Napi::Value v, void* dst,
+                                size_t elemSize, gpointer* writeBackTo) {
+  if (writeBackTo != nullptr) *writeBackTo = nullptr;
+  GType want = ByValueRecordGType(elem);
+  if (want == G_TYPE_VALUE) {
+    GValue* cell = static_cast<GValue*>(dst);
+    memset(cell, 0, elemSize);
+    if (NodeGiIsGValueHandle(v)) {
+      BoxedHandle* h = TryGetBoxedHandle(v);
+      GValue* src = h == nullptr ? nullptr : static_cast<GValue*>(h->ptr);
+      if (src == nullptr || !G_IS_VALUE(src)) {
+        Napi::TypeError::New(env,
+                             "an uninitialised GObject.Value cannot be an array element")
+            .ThrowAsJavaScriptException();
+        return false;
+      }
+      g_value_init(cell, G_VALUE_TYPE(src));
+      g_value_copy(src, cell);
+      if (writeBackTo != nullptr) *writeBackTo = src;
+      return true;
+    }
+    return JsToFreshGValue(env, v, cell);
+  }
+
+  BoxedHandle* h = TryGetBoxedHandle(v);
+  if (h == nullptr || h->ptr == nullptr) {
+    Napi::TypeError::New(
+        env, std::string("expected a ") +
+                 (want == G_TYPE_INVALID ? "record" : g_type_name(want)) +
+                 " handle as a by-value array element")
+        .ThrowAsJavaScriptException();
+    return false;
+  }
+  bool sameType = want != G_TYPE_INVALID
+                      ? (h->gtype != G_TYPE_INVALID && g_type_is_a(h->gtype, want))
+                      : (BoxedInfoSize(h->info) == elemSize && elemSize > 0);
+  if (!sameType) {
+    Napi::TypeError::New(
+        env, std::string("a by-value array element must be a ") +
+                 (want == G_TYPE_INVALID ? "record of the same size" : g_type_name(want)) +
+                 ", got " +
+                 (h->gtype == G_TYPE_INVALID ? "an unregistered record" : g_type_name(h->gtype)))
+        .ThrowAsJavaScriptException();
+    return false;
+  }
+  memcpy(dst, h->ptr, elemSize);
+  return true;
+}
+
 // Build a C array / GStrv / GByteArray / GArray / GPtrArray from a JS value.
 // *outCount = element count (for the IN length autofill + later free). Throws +
 // returns false on refusal (BEFORE the invoke).
-static bool JsToCArray(Napi::Env env, Napi::Value v, GITypeInfo* type, gpointer* outPtr,
-                       long* outCount) {
+static bool JsToCArray(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransfer transfer,
+                       gpointer* outPtr, long* outCount, std::vector<gpointer>* writeBack) {
+  GITransfer elemTransfer =
+      transfer == GI_TRANSFER_EVERYTHING ? GI_TRANSFER_EVERYTHING : GI_TRANSFER_NOTHING;
   GIArrayType at = gi_type_info_get_array_type(type);
   GITypeInfo* elem = gi_type_info_get_param_type(type, 0);
   GITypeTag etag = gi_type_info_get_tag(elem);
   bool zt = gi_type_info_is_zero_terminated(type);
-  size_t elemSize = CElementSize(elem);
+  // CInElementSize, not CElementSize: this is the write side, and it is the side that
+  // knows how wide a by-value element's cell is (see the note on that function).
+  size_t elemSize = CInElementSize(elem);
+  bool byValueRecord = IsByValueRecordElement(elem);
   bool isByte = etag == GI_TYPE_TAG_UINT8 || etag == GI_TYPE_TAG_INT8;
   *outPtr = nullptr;
   *outCount = 0;
 
+  // A by-value record element is a BITWISE copy of a handle's storage, which shares
+  // whatever that record points at. That is safe exactly while WE free the buffer:
+  // on TRANSFER_EVERYTHING the callee frees the elements too, and it would be freeing
+  // strings and boxeds the caller's handles still own — the same use-after-free the
+  // pointer-element half of this work shipped once and had to fix, wearing a different
+  // shape. There is no general remedy: an arbitrary record has no copy function to
+  // deep-copy with.
+  //
+  // Measured across every installed typelib rather than guessed: of 140 IN parameters
+  // with a by-value element, 139 are `transfer=none` and ONE is not — Gsf
+  // .property_settings_free's `GObject.Parameter[]`, which exists to free what it is
+  // given. So this refusal costs one callable, and that callable is the one where
+  // handing over borrowed contents would be exactly wrong.
+  if (byValueRecord && transfer != GI_TRANSFER_NOTHING) {
+    gi_base_info_unref(elem);
+    Napi::TypeError::New(
+        env, "a by-value record array with transfer other than none is not yet supported: the "
+             "callee would free element contents the caller's handles still own")
+        .ThrowAsJavaScriptException();
+    return false;
+  }
+
   // null/undefined → a NULL array (count 0), as GJS marshals a null array arg
   // (refs/gjs/gi/arg.cpp gjs_array_to_explicit_array: null in → NULL out).
   // Exposing call: `Gst.init(null)` — a NULLABLE (inout) argv array every GJS
@@ -1454,18 +1906,47 @@ static bool JsToCArray(Napi::Env env, Napi::Value v, GITypeInfo* type, gpointer*
   // pdata memcpy (refs/gjs/gi/arg.cpp gjs_value_to_basic_array_gi_argument).
   void* buf = g_malloc0(elemSize * (count + (zt ? 1 : 0)));
   bool ok = true;
+  long written = 0;
   for (long i = 0; i < count && ok; i++) {
+    void* dst = static_cast<char*>(buf) + i * elemSize;
+    if (byValueRecord) {
+      // The record writes ITSELF into the cell — it never passes through a GIArgument,
+      // because the union is eight bytes and the record is its own size.
+      gpointer source = nullptr;
+      ok = ByValueRecordToCell(env, elem, arr.Get(static_cast<uint32_t>(i)), dst, elemSize,
+                               &source);
+      if (ok) {
+        if (writeBack != nullptr) {
+          writeBack->resize(static_cast<size_t>(i) + 1, nullptr);
+          (*writeBack)[static_cast<size_t>(i)] = source;
+        }
+        written++;
+      }
+      continue;
+    }
     GIArgument a;
-    ok = ElementToGIArgument(env, elem, arr.Get(static_cast<uint32_t>(i)), &a);
+    ok = ElementToGIArgument(env, elem, arr.Get(static_cast<uint32_t>(i)), &a, elemTransfer);
     if (!ok) break;
-    void* dst = static_cast<char*>(buf) + i * elemSize;
     // Copy the element's storage bytes (LE: the low elemSize bytes of the union
     // alias the active field — v_string/v_pointer for pointers, the scalar
-    // otherwise).
+    // otherwise). elemSize never exceeds the union here: the one element kind that is
+    // wider took the branch above.
     memcpy(dst, &a, elemSize);
+    written++;
   }
   if (!ok) {
-    g_free(buf);  // partial g_strdup'd strings leak on this error path (pre-checked, rare)
+    // The GValues already initialised are ours and are released here — the container is
+    // never recorded for cleanup on this path, so nothing else will. (Partial
+    // g_strdup'd strings, and on an EVERYTHING container the refs/copies taken for
+    // earlier elements, still leak: pre-checked and rare, needing a non-handle value
+    // mid-array. A leak, never a double free.)
+    if (byValueRecord && ElementsAreOwnedGValues(type)) {
+      for (long i = 0; i < written; i++) {
+        GValue* cell = reinterpret_cast<GValue*>(static_cast<char*>(buf) + i * elemSize);
+        if (G_IS_VALUE(cell)) g_value_unset(cell);
+      }
+    }
+    g_free(buf);
     gi_base_info_unref(elem);
     return false;
   }
@@ -1498,7 +1979,9 @@ static bool JsToCArray(Napi::Env env, Napi::Value v, GITypeInfo* type, gpointer*
 
 // Build a GList / GSList from a JS array.
 static bool JsToGListLike(Napi::Env env, Napi::Value v, GITypeInfo* type, bool isSList,
-                          gpointer* outPtr) {
+                          GITransfer transfer, gpointer* outPtr) {
+  GITransfer elemTransfer =
+      transfer == GI_TRANSFER_EVERYTHING ? GI_TRANSFER_EVERYTHING : GI_TRANSFER_NOTHING;
   *outPtr = nullptr;
   if (!v.IsArray()) {
     Napi::TypeError::New(env, "expected an array for the list argument").ThrowAsJavaScriptException();
@@ -1511,8 +1994,12 @@ static bool JsToGListLike(Napi::Env env, Napi::Value v, GITypeInfo* type, bool i
   bool ok = true;
   for (uint32_t i = 0; i < arr.Length() && ok; i++) {
     GIArgument a;
-    ok = ElementToGIArgument(env, elem, arr.Get(i), &a);
+    ok = ElementToGIArgument(env, elem, arr.Get(i), &a, elemTransfer);
     if (!ok) break;
+    // Measured, not assumed: for an INTERFACE element that is a pointer this helper
+    // passes v_pointer through unchanged and gi_type_info_argument_from_hash_pointer
+    // reads the same address back, so a pointer-struct element fills a node's data
+    // slot exactly as an object element does.
     gpointer p = gi_type_info_hash_pointer_from_argument(elem, &a);
     if (!isSList) glist = g_list_prepend(glist, p);
     else gslist = g_slist_prepend(gslist, p);
@@ -1534,7 +2021,14 @@ static bool JsToGListLike(Napi::Env env, Napi::Value v, GITypeInfo* type, bool i
 // Key/value GDestroyNotify funcs are attached so a transfer-none teardown
 // (g_hash_table_unref in FreeInContainer) releases everything; a transfer-full
 // hash is adopted by the callee, which frees it (and thus runs the notifies).
-static bool JsToGHashIn(Napi::Env env, Napi::Value v, GITypeInfo* type, gpointer* outPtr) {
+static bool JsToGHashIn(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransfer transfer,
+                        gpointer* outPtr) {
+  // A hash's VALUE destroy-notify is set below for the string/heap kinds only, so an
+  // EVERYTHING hash of object/boxed values leaks the copies rather than double-freeing
+  // the originals. That is the safe side of the trade and the only one reachable: no
+  // installed typelib has an EVERYTHING GHashTable IN with a POINTER-STRUCT value.
+  GITransfer elemTransfer =
+      transfer == GI_TRANSFER_EVERYTHING ? GI_TRANSFER_EVERYTHING : GI_TRANSFER_NOTHING;
   *outPtr = nullptr;
   if (!v.IsObject() || v.IsArray()) {
     Napi::TypeError::New(env, "expected an object for the GHashTable argument")
@@ -1578,7 +2072,7 @@ static bool JsToGHashIn(Napi::Env env, Napi::Value v, GITypeInfo* type, gpointer
     } else {
       GIArgument ka;
       Napi::Value keyNum = Napi::Number::New(env, static_cast<double>(g_ascii_strtoll(ks.c_str(), nullptr, 10)));
-      ok = ElementToGIArgument(env, kt, keyNum, &ka);
+      ok = ElementToGIArgument(env, kt, keyNum, &ka, GI_TRANSFER_NOTHING);
       if (!ok) break;
       kp = gi_type_info_hash_pointer_from_argument(kt, &ka);
     }
@@ -1589,7 +2083,7 @@ static bool JsToGHashIn(Napi::Env env, Napi::Value v, GITypeInfo* type, gpointer
     Napi::Value val = obj.Get(key);
     gpointer vp = nullptr;
     GIArgument va;
-    ok = ElementToGIArgument(env, vt, val, &va);
+    ok = ElementToGIArgument(env, vt, val, &va, elemTransfer);
     if (!ok) {
       g_free(kp);
       break;
@@ -1661,6 +2155,44 @@ void FreeInContainer(const InContainer& c) {
           g_free(s);
         }
       } else {
+        // A GValue element array is the one C array whose CELLS hold something beyond
+        // their own bytes: JsToCArray initialised each one (from a JS value or by
+        // copying a handle's GValue), so each one holds a string, a boxed or a ref that
+        // g_free on the buffer would strand. Only this transfer reaches here — on
+        // EVERYTHING/CONTAINER the callee owns the buffer and unsets them itself.
+        if (ElementsAreOwnedGValues(c.type)) {
+          size_t elemSize = elem != nullptr ? CInElementSize(elem) : 0;
+          for (long i = 0; elemSize > 0 && i < c.count; i++) {
+            GValue* cell = reinterpret_cast<GValue*>(static_cast<char*>(c.ptr) + i * elemSize);
+            if (!G_IS_VALUE(cell)) continue;
+            // WRITE-BACK, and the reason it is not optional. Some callees FILL these
+            // cells rather than read them — `GObject.Object.getv`, `Gst.Object
+            // .get_g_value_array`, `Gst.ControlBinding.get_g_value_array` — and the
+            // typelib gives NO way to tell them apart: measured on `g_object_getv`,
+            // its `values` parameter reports direction=IN, caller-allocates=false,
+            // transfer=none, byte for byte the same flags as `GLib.parse_debug_string`'s
+            // read-only `keys`. Without this, such a call silently does nothing, which
+            // is worse than the refusal it replaced. (gjs has the same gap: `getv`
+            // there also leaves the caller's GValue empty — measured on 1.88.1. This is
+            // a deliberate divergence, and the annotation is an upstream candidate.)
+            //
+            // `g_value_copy` rather than a memcpy: the cell is unset immediately after,
+            // and a bitwise copy would leave the caller's GValue pointing at a string
+            // this line is about to free. The type is matched first because g_value_copy
+            // requires it, and a callee may have set a type the caller did not.
+            GValue* dest = i < static_cast<long>(c.writeBack.size())
+                               ? static_cast<GValue*>(c.writeBack[static_cast<size_t>(i)])
+                               : nullptr;
+            if (dest != nullptr) {
+              if (!G_IS_VALUE(dest) || G_VALUE_TYPE(dest) != G_VALUE_TYPE(cell)) {
+                if (G_IS_VALUE(dest)) g_value_unset(dest);
+                g_value_init(dest, G_VALUE_TYPE(cell));
+              }
+              g_value_copy(cell, dest);
+            }
+            g_value_unset(cell);
+          }
+        }
         g_free(c.ptr);
       }
     }
@@ -1694,23 +2226,24 @@ bool JsToInContainer(Napi::Env env, Napi::Value v, GITypeInfo* type, GITransfer
   GITypeTag tag = gi_type_info_get_tag(type);
   *outCount = 0;
   bool ok = false;
+  std::vector<gpointer> writeBack;
   if (tag == GI_TYPE_TAG_ARRAY) {
-    ok = JsToCArray(env, v, type, outPtr, outCount);
+    ok = JsToCArray(env, v, type, transfer, outPtr, outCount, &writeBack);
   } else if (tag == GI_TYPE_TAG_GLIST || tag == GI_TYPE_TAG_GSLIST) {
-    ok = JsToGListLike(env, v, type, tag == GI_TYPE_TAG_GSLIST, outPtr);
+    ok = JsToGListLike(env, v, type, tag == GI_TYPE_TAG_GSLIST, transfer, outPtr);
   } else if (tag == GI_TYPE_TAG_GHASH) {
-    ok = JsToGHashIn(env, v, type, outPtr);
+    ok = JsToGHashIn(env, v, type, transfer, outPtr);
   }
   if (ok && *outPtr != nullptr) {
-    containers->push_back(InContainer{
-        reinterpret_cast<GITypeInfo*>(gi_base_info_ref(type)), *outPtr, transfer, *outCount});
+    containers->push_back(InContainer{reinterpret_cast<GITypeInfo*>(gi_base_info_ref(type)),
+                                     *outPtr, transfer, *outCount, std::move(writeBack)});
   } else if (!ok && *outPtr != nullptr) {
     // An element conversion threw mid-build (JsToGListLike / JsToGHashIn still
     // published the partial container). It was never recorded for cleanup, so
     // the nodes (and any g_strdup'd keys/string values) would leak. Free it now
     // with NOTHING semantics — we still own all of it; the callee never saw it.
     InContainer partial{reinterpret_cast<GITypeInfo*>(gi_base_info_ref(type)), *outPtr,
-                        GI_TRANSFER_NOTHING, *outCount};
+                        GI_TRANSFER_NOTHING, *outCount, {}};
     FreeInContainer(partial);  // unrefs the type ref taken above
     *outPtr = nullptr;
   }