yeptris 0.6.18.2-arm-linux-eabihf

data/lib/yeptris/document.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+class Yeptris::Document
+  attr_reader :c_ptr
+
+  # Shared between the instance and its GC finalizer (Procs close over
+  # variables by reference) — the leptris-ruby double-free fix: the
+  # explicit free path and the finalizer both flip the same flag.
+  Freed = Struct.new(:state) # :alive | :freed
+
+  # The raw C handle — the Yeptris::Node wrappers cache by its
+  # address; stream-children wrappers (Document.without_finalizer)
+  # carry it without registering a finalizer (#182).
+  attr_reader :c_ptr
+
+  # The schema this document was parsed with (a parse property).
+  attr_reader :parse_schema
+
+  def initialize(c_ptr = nil, freed = Freed.new(:alive), parse_schema = :core_12)
+    @c_ptr = c_ptr
+    @freed = freed
+    @parse_schema = parse_schema
+    @readonly = false
+    # Strong wrapper cache keyed on the C node address: the same C node
+    # always yields the same Ruby object (identity for aliases/eql?),
+    # cleared at free — no stale entries, no GC-race weak maps.
+    @wrapper_cache = {}
+    ObjectSpace.define_finalizer(self, self.class.finalize(c_ptr)) unless c_ptr.null?
+  end
+
+  def self.parse(yaml, schema: :core_12, max_depth: 0)
+    yaml = Yeptris.read_input(yaml)
+    yaml = yaml.to_s
+    status = ::FFI::MemoryPointer.new(:int)
+    doc =
+      if schema == :core_12 && max_depth.zero?
+        Yeptris::FFI.yeptris_parse(yaml, yaml.bytesize, status)
+      else
+        opts = Yeptris::FFI::ParseOptions.new
+        opts[:schema] = schema == :compat_11 ? Yeptris::FFI::SCHEMA_11_COMPAT : Yeptris::FFI::SCHEMA_12_CORE
+        opts[:max_depth] = max_depth
+        Yeptris::FFI.yeptris_parse_ex(yaml, yaml.bytesize, opts, status)
+      end
+    if doc.null?
+      # NULL + OK is the legal empty stream (no documents): nil, like
+      # stdlib. The status out-param is the discriminator — the TLS
+      # error message cannot serve (a stale error from an earlier
+      # parse persists on the thread).
+      return nil if status.read_int.zero?
+
+      raise Yeptris::ParseError,
+            "parse failed: #{Yeptris::FFI.last_error_message}"
+    end
+    wrap_schema(doc, schema)
+  end
+
+  def self.parse_json(json)
+    json = Yeptris.read_input(json)
+    json = json.to_s
+    doc = Yeptris::FFI.yeptris_parse_json(json, json.bytesize, nil)
+    raise Yeptris::ParseError,
+          "json parse failed: #{Yeptris::FFI.last_error_message}" if doc.null?
+
+    wrap_schema(doc, :core_12) # strict JSON is core by construction
+  end
+
+  # An empty document for from-scratch construction (TODO.impl/11 p3).
+  def self.create
+    doc = Yeptris::FFI.yeptris_document_new
+    raise Yeptris::Error, "yeptris_document_new failed" if doc.null?
+
+    wrap(doc)
+  end
+
+  # @api private
+  def self.wrap(c_ptr)
+    new(c_ptr)
+  end
+
+  # The schema the document was parsed with (:core_12 / :compat_11) —
+  # host scalar policies (Psych's dot-required float) are conditioned
+  # on it. The parse constructors set the real one; plain wrap keeps
+  # the core_12 default (yeptris_parse's default).
+  def self.wrap_schema(c_ptr, schema)
+    new(c_ptr, Freed.new(:alive), schema)
+  end
+
+  # #182: the stream-children wrapper owns NOTHING (the parent
+  # Document wrapper is the sole freer of the C memory). A plain
+  # Document.new would register a finalizer on a c_ptr we don't own;
+  # a parse_stream on a multi-doc stream would free the same pointer
+  # three times at GC → SIGABRT. This factory builds the wrapper
+  # WITHOUT a finalizer; the wrapper's lifetime follows the owner.
+  def self.without_finalizer(c_ptr)
+    doc = new(c_ptr)
+    ObjectSpace.undefine_finalizer(doc)
+    doc
+  end
+
+  def ensure_alive!
+    raise Yeptris::FreedError, "document is freed" if @freed.state == :freed
+  end
+
+  def free
+    return if @freed.state == :freed
+
+    @freed.state = :freed
+    # stop the GC finalizer BEFORE the C free — it captures the same
+    # pointer, and its firing after this free is the double free
+    ObjectSpace.undefine_finalizer(self)
+    @wrapper_cache.clear
+    Yeptris::FFI.yeptris_document_free(@c_ptr)
+  end
+
+  def freed?
+    @freed.state == :freed
+  end
+
+  def readonly!
+    @readonly = true
+    self
+  end
+
+  def readonly?
+    @readonly
+  end
+
+  # @api private — memo table for readonly materialization: node ids
+  # that already produced their Ruby object keep it (leptris pattern:
+  # readonly documents never change, so the memo is forever valid).
+  def readonly_memo
+    @readonly_memo ||= {}
+  end
+
+  # @api private — the single Node construction path. Query handles
+  # are transient C allocations; the wrapper cache is keyed on the
+  # STABLE node id (yeptris_node_id), so the same node always yields
+  # the same Ruby object no matter which query produced the handle.
+  def wrap_node(c_ptr)
+    ensure_alive!
+    return nil if c_ptr.null?
+
+    id = Yeptris::FFI.yeptris_node_id(c_ptr)
+    @wrapper_cache[id] ||= Yeptris::Node.new(c_ptr, self)
+  end
+
+  def document_count
+    ensure_alive!
+    Yeptris::FFI.yeptris_document_count(@c_ptr)
+  end
+
+  # Root node of stream document i (0-based).
+  def root(index = 0)
+    ensure_alive!
+    wrap_node(Yeptris::FFI.yeptris_document_root(@c_ptr, index))
+  end
+
+  # Bulk build (TODO.impl/15 phase D): one call raises the whole
+  # tree from a flat entry array + blob (see YAML::BulkBuilder).
+  def build_entries(entries, count, blob, blob_len)
+    ensure_alive!
+    Yeptris::FFI.yeptris_document_build(@c_ptr, entries, count, blob, blob_len)
+  end
+
+  def serialize(canonical: false, best_width: 0, explicit_doc_start: false)
+    ensure_alive!
+    len = ::FFI::MemoryPointer.new(:size_t)
+    ptr =
+      if canonical || best_width.positive? || explicit_doc_start
+        opts = Yeptris::FFI::EmitOptions.new
+        opts[:size] = Yeptris::FFI::EmitOptions.size
+        opts[:canonical] = canonical ? 1 : 0
+        opts[:best_width] = best_width
+        opts[:explicit_doc_start] = explicit_doc_start ? 1 : 0
+        Yeptris::FFI.yeptris_serialize_ex(@c_ptr, opts, len)
+      else
+        Yeptris::FFI.yeptris_serialize(@c_ptr, len)
+      end
+    Yeptris::FFI::Owned.string(ptr, len)
+  end
+
+  def serialize_json_compact
+    len = ::FFI::MemoryPointer.new(:size_t)
+    Yeptris::FFI::Owned.string(Yeptris::FFI.yeptris_serialize_json_ex(@c_ptr, len, 1), len)
+  end
+
+  def serialize_json
+    ensure_alive!
+    len = ::FFI::MemoryPointer.new(:size_t)
+    Yeptris::FFI::Owned.string(Yeptris::FFI.yeptris_serialize_json(@c_ptr, len), len)
+  end
+
+  def to_s
+    serialize
+  end
+
+  # The Ruby object graph of stream document i (Psych-compatible
+  # materialization; alias identity preserved via the memo).
+  def to_ruby(index = 0)
+    ensure_alive!
+    r = root(index)
+    r.nil? ? nil : r.to_ruby
+  end
+
+  # ---- construction conveniences (TODO.impl/11 phase 3) ----
+
+  def new_mapping
+    ensure_alive!
+    wrap_node(Yeptris::FFI.yeptris_node_new_mapping(@c_ptr)) or
+      raise Yeptris::Error, "yeptris_node_new_mapping failed"
+  end
+
+  def new_sequence
+    ensure_alive!
+    wrap_node(Yeptris::FFI.yeptris_node_new_sequence(@c_ptr)) or
+      raise Yeptris::Error, "yeptris_node_new_sequence failed"
+  end
+
+  # style: :plain / :single_quoted / :double_quoted / :literal / :folded.
+  # The value is copied into the document (nothing is borrowed).
+  def new_scalar(text, style = :plain)
+    ensure_alive!
+    code = Yeptris::Node::STYLES.key(style) or
+      raise ArgumentError, "unknown scalar style #{style.inspect}"
+    text = text.to_s
+    n = Yeptris::FFI.yeptris_node_new_scalar(@c_ptr, text, text.bytesize, code)
+    wrap_node(n) or raise Yeptris::Error, "yeptris_node_new_scalar failed"
+  end
+
+  # An alias node: display name + the target it resolves to.
+  def new_alias(target, name)
+    ensure_alive!
+    n = Yeptris::FFI.yeptris_node_new_alias(@c_ptr, target.c_ptr, name, name.bytesize)
+    wrap_node(n) or raise Yeptris::Error, "yeptris_node_new_alias failed"
+  end
+
+  def set_root(node)
+    ensure_alive!
+    rc = Yeptris::FFI.yeptris_document_set_root(@c_ptr, node.c_ptr)
+    Yeptris::FFI.check_status(rc, "yeptris_document_set_root")
+    self
+  end
+
+  # GC safety net (#182): the proc captures ONLY the raw pointer — no
+  # Ruby objects, no wrapper, no freed-flag struct. A finalizer that
+  # closes over the owning wrapper races that wrapper's own sweep
+  # (the classic use-after-free: freed?/free against half-collected
+  # ivars, then a garbage C pointer into yeptris_document_free →
+  # SIGABRT). Explicit #free undefines this finalizer BEFORE the C
+  # free, so the double free cannot happen; finalizers run on the
+  # main thread, so there is no cross-thread window.
+  def self.finalize(c_ptr)
+    proc { Yeptris::FFI.yeptris_document_free(c_ptr) }
+  end
+end

data/lib/yeptris/ffi.rb

@@ -0,0 +1,426 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Yeptris
+  # Every public C declaration, attached exactly once (the leptris-ruby
+  # seam discipline: status checking and owned-pointer reading live in
+  # check_status / read_owned_string, never hand-rolled at call sites).
+  module FFI
+    extend ::FFI::Library
+
+    begin
+      ffi_lib [
+        ENV["YEPTRIS_LIB_PATH"],
+        File.expand_path("../../libyeptris.dylib", __dir__),
+        File.expand_path("../../libyeptris.so", __dir__),
+        File.expand_path("../../libyeptris.dll", __dir__),
+        "/usr/local/lib/libyeptris.dylib",
+        "/usr/local/lib/libyeptris.so",
+        "yeptris",
+      ].compact
+    rescue LoadError => e
+      raise LoadError, <<~MSG
+        yeptris: cannot load the libyeptris library.
+        Set YEPTRIS_LIB_PATH to a libyeptris.{so,dylib,dll}, or vendor
+        the library next to the gem's lib/ directory.
+        (Underlying error: #{e.message})
+      MSG
+    end
+
+    class << self
+      # #138's class, hit again by the oiml-cs report: a stale
+      # libyeptris on the machine (the Windows base-name dedupe makes
+      # a system copy win) lacks newer symbols, and a raising attach
+      # aborts this file mid-evaluation — every constant after it
+      # never defines, so the next autoload dies with
+      # 'uninitialized constant Yeptris::FFI::NODE_SCALAR'. Attaches
+      # now record the miss and define a raising stub of the same
+      # name: the load completes, optional surfaces fail with a clear
+      # message at USE, and the ESSENTIAL self-check at the bottom of
+      # this file raises the friendly load error for truly old
+      # engines.
+      def attach_function(name, args, ret, opts = {})
+        super
+      rescue ::FFI::NotFoundError, ::FFI::TypeError
+        define_singleton_method(name) do |*_a, **_kw|
+          raise ::FFI::NotFoundError,
+                "yeptris: #{name} is unavailable — the loaded " \
+                "libyeptris is older than this gem. Update the engine " \
+                "library (or clear the stale copy shadowing it)."
+        end
+        (@missing ||= []) << name
+        nil
+      end
+    end
+
+
+    typedef :pointer, :yeptris_document
+    typedef :pointer, :yeptris_node
+    typedef :pointer, :yeptris_status_out
+    typedef :int, :yeptris_status
+
+    # YeptrisParseOptions (parse.h): schema, max_depth, strict,
+    # tab_policy, recover. ABI-frozen field order.
+    class ParseOptions < ::FFI::Struct
+      layout :schema, :int,
+             :max_depth, :int,
+             :strict, :int,
+             :tab_policy, :int,
+             :recover, :int
+    end
+
+    # yeptris_emit_options (emit.h): versioned by size.
+    class EmitOptions < ::FFI::Struct
+      layout :size, :uint32,
+             :canonical, :int,
+             :best_width, :int,
+             :explicit_doc_start, :int
+    end
+
+    attach_function :yeptris_version, [], :string
+
+    attach_function :yeptris_last_error, [:pointer, :pointer], :string
+
+    attach_function :yeptris_parse, %i[pointer size_t yeptris_status_out], :yeptris_document
+    attach_function :yeptris_parse_ex,
+                    %i[pointer size_t pointer yeptris_status_out], :yeptris_document
+    attach_function :yeptris_parse_json, %i[pointer size_t yeptris_status_out], :yeptris_document
+
+    # The JSON tape (TODO.restructure/85; the JSON surface's load
+    # engine — issue #81): ONE call, three bulk columns, spans borrow
+    # the caller's string (no arena copy, no second validating parse).
+    # v2 records: numbers are spans at parse; yeptris_tape_convert
+    # materializes them in one bulk call.
+    # v3 (libyeptris 0.6.9): the interleaved records (recs) are the
+    # primary storage on the lenient route; the strict route keeps the
+    # columns eager. The layout MUST mirror yeptris_json_tape — a stale
+    # layout makes C write past the FFI buffer (a silent heap overflow
+    # that only some allocators catch; the 0.6.9.1 windows crash).
+    class JsonTape < ::FFI::Struct
+      layout :count, :size_t, :kinds, :pointer, :offs, :pointer,
+             :lens, :pointer, :recs, :pointer, :_cols_ready, :int,
+             :_rec_primary, :int, :int_min, :int64, :_src, :pointer,
+             :_srclen, :size_t, :_block, :pointer
+    end
+
+    attach_function :yeptris_parse_json_tape, %i[pointer size_t pointer], :int
+    attach_function :yeptris_tape_free, [:pointer], :void
+    attach_function :yeptris_tape_convert, %i[pointer size_t size_t pointer pointer], :size_t
+
+    # the compiled plan walk (#293 / TODO.restructure/87): compile a
+    # strict-JSON spec once, apply it to a parsed tape in one C pass,
+    # read the typed COLUMNAR result
+    attach_function :yeptris_plan_compile, %i[pointer size_t pointer], :pointer
+    attach_function :yeptris_plan_free, [:pointer], :void
+    attach_function :yeptris_plan_column_count, [:pointer], :size_t
+    attach_function :yeptris_tape_plan_walk, %i[pointer pointer pointer], :pointer
+    attach_function :yeptris_plan_result_free, [:pointer], :void
+    attach_function :yeptris_plan_result_rows, [:pointer], :size_t
+    attach_function :yeptris_plan_result_kind, %i[pointer size_t], :int
+    attach_function :yeptris_plan_result_ints, %i[pointer size_t], :pointer
+    attach_function :yeptris_plan_result_floats, %i[pointer size_t], :pointer
+    attach_function :yeptris_plan_result_str_offs, %i[pointer size_t], :pointer
+    attach_function :yeptris_plan_result_str_lens, %i[pointer size_t], :pointer
+    attach_function :yeptris_plan_result_nulls, %i[pointer size_t], :pointer
+
+    # the DOM (YAML) leg of the plan walk (#293 slice three): same
+    # compiled plan over a parsed document; str columns expose
+    # (ptr,len) views into the document's regions
+    attach_function :yeptris_document_plan_walk, %i[yeptris_document pointer pointer], :pointer
+    attach_function :yeptris_plan_result_strs, %i[pointer size_t], :pointer
+
+    # yeptris_plan_str (plan.h): one string view
+    class PlanStr < ::FFI::Struct
+      layout :p, :pointer, :len, :size_t
+    end
+
+    attach_function :yeptris_document_free, [:yeptris_document], :void
+    attach_function :yeptris_document_count, [:yeptris_document], :size_t
+    attach_function :yeptris_document_root, [:yeptris_document, :size_t], :yeptris_node
+
+    # construction (TODO.impl/11 phase 3)
+    attach_function :yeptris_document_new, [], :yeptris_document
+    attach_function :yeptris_document_set_root,
+                    %i[yeptris_document yeptris_node], :int
+    attach_function :yeptris_node_new_mapping, [:yeptris_document], :yeptris_node
+    attach_function :yeptris_node_new_sequence, [:yeptris_document], :yeptris_node
+    attach_function :yeptris_node_new_scalar,
+                    %i[yeptris_document pointer size_t int], :yeptris_node
+    attach_function :yeptris_node_map_add,
+                    %i[yeptris_node pointer size_t yeptris_node], :int
+    attach_function :yeptris_node_map_add_node,
+                    %i[yeptris_node yeptris_node yeptris_node], :int
+    attach_function :yeptris_node_map_set,
+                    %i[yeptris_node pointer size_t yeptris_node], :int
+    attach_function :yeptris_node_map_del, %i[yeptris_node pointer size_t], :int
+    attach_function :yeptris_node_seq_add, %i[yeptris_node yeptris_node], :int
+    attach_function :yeptris_node_seq_del, %i[yeptris_node size_t], :int
+    attach_function :yeptris_node_set_anchor, %i[yeptris_node pointer size_t], :int
+    attach_function :yeptris_node_set_tag, %i[yeptris_node pointer size_t], :int
+    attach_function :yeptris_node_new_alias,
+                    %i[yeptris_document yeptris_node pointer size_t], :yeptris_node
+
+    attach_function :yeptris_node_kind, [:yeptris_node], :int
+    attach_function :yeptris_node_id, [:yeptris_node], :uint32
+    attach_function :yeptris_node_value, %i[yeptris_node pointer], :pointer
+    attach_function :yeptris_node_style, [:yeptris_node], :int
+    attach_function :yeptris_node_tag, %i[yeptris_node pointer], :pointer
+    attach_function :yeptris_node_anchor, %i[yeptris_node pointer], :pointer
+    attach_function :yeptris_node_alias_target, [:yeptris_node], :yeptris_node
+    attach_function :yeptris_node_tag_id, [:yeptris_node], :int
+    attach_function :yeptris_node_int, %i[yeptris_node pointer], :yeptris_status
+    attach_function :yeptris_node_float, %i[yeptris_node pointer], :yeptris_status
+    attach_function :yeptris_node_bool, %i[yeptris_node pointer], :yeptris_status
+    attach_function :yeptris_node_seq_count, [:yeptris_node], :size_t
+    attach_function :yeptris_node_seq_at, %i[yeptris_node size_t], :yeptris_node
+    attach_function :yeptris_node_children,
+                    %i[yeptris_node pointer size_t], :size_t
+    attach_function :yeptris_node_map_count, [:yeptris_node], :size_t
+    attach_function :yeptris_node_map_get, %i[yeptris_node pointer size_t], :yeptris_node
+    attach_function :yeptris_node_map_at,
+                    %i[yeptris_node size_t pointer pointer], :int
+
+    attach_function :yeptris_tag_uri, [:int], :string
+
+    # recorder (TODO.impl/12): bulk records + string arena, one drain
+    attach_function :yeptris_recorder_new, [], :pointer
+    attach_function :yeptris_recorder_new_ex, [:int], :pointer
+    attach_function :yeptris_recorder_feed,
+                    %i[pointer pointer size_t int], :int
+    attach_function :yeptris_recorder_records, %i[pointer pointer], :pointer
+    attach_function :yeptris_recorder_arena, %i[pointer pointer], :pointer
+    attach_function :yeptris_recorder_free, [:pointer], :void
+
+    # value stream (TODO.impl/15 phase F): one drain of pre-converted
+    # typed values — the materialization fast path
+    attach_function :yeptris_value_drain,
+                    %i[pointer size_t int pointer pointer pointer pointer], :int
+    attach_function :yeptris_value_free, %i[pointer pointer], :void
+
+    # Columnar drain (libyeptris > 0.1.1): the same stream as parallel
+    # typed buffers, one carved allocation. Feature-detected — the
+    # record API is the fallback on older libraries.
+    COLUMNS = begin
+      attach_function :yeptris_value_drain_columns, %i[pointer size_t int pointer], :int
+      attach_function :yeptris_value_free_columns, [:pointer], :void
+      true
+    rescue ::FFI::NotFoundError
+      false
+    end
+
+    class ValueColumns < ::FFI::Struct
+      layout :count, :size_t, :arena_len, :size_t,
+             :payloads, :pointer, :offs, :pointer, :lens, :pointer,
+             :kinds, :pointer, :tags, :pointer, :is_keys, :pointer,
+             :bools, :pointer, :arena, :pointer
+    end
+
+    # Marshal 4.8 emission (TODO.restructure/21): the C side converts
+    # value records directly into Ruby's wire format; the binding
+    # materializes the whole graph with one core-C Marshal.load call
+    # instead of walking per-value records in pure Ruby. Same feature-
+    # detect discipline as the columnar drain (older libraries fall
+    # back to the record walk).
+    MARSHAL_ALL_DOCS = 0
+    MARSHAL_FIRST_DOC = 1
+    attach_function :yeptris_marshal,
+                    %i[pointer size_t int int pointer pointer], :int
+    attach_function :yeptris_marshal_node,
+                    %i[yeptris_node pointer pointer], :int
+    attach_function :yeptris_marshal_free, [:pointer], :void
+    # The bulk child drain (#168's quadratic): O(n) iteration for
+    # #each/#each_pair. Engines without it fall back to the per-index
+    # walk (correct, quadratic).
+    CHILDREN_DRAIN = !(@missing ||= []).include?(:yeptris_node_children)
+    MARSHAL = !(@missing ||= []).include?(:yeptris_marshal_node)
+
+    # bulk build (TODO.impl/15 phase D): one call raises a document
+    BUILD_SCALAR = 1
+    BUILD_SEQ = 2
+    BUILD_MAP = 3
+    BUILD_END = 4
+    BUILD_TAG = 5
+
+    # the ABI-pinned shape; the bulk builder packs these bytes
+    # directly (12 per entry)
+    class BuildEntry < ::FFI::Struct
+      layout op: :uint8, style: :uint8, reserved: :uint16, off: :uint32, len: :uint32
+    end
+    attach_function :yeptris_document_build,
+                    %i[yeptris_document pointer size_t pointer size_t], :int
+
+    attach_function :yeptris_serialize, %i[yeptris_document pointer], :pointer
+    attach_function :yeptris_serialize_ex,
+                    %i[yeptris_document pointer pointer], :pointer
+    attach_function :yeptris_serialize_json, %i[yeptris_document pointer], :pointer
+
+    # compact JSON generation (JSON.generate's shape); absent on
+    # libraries before v0.2.5 — the JSON surface feature-detects
+    JSON_EX = begin
+      attach_function :yeptris_serialize_json_ex, %i[yeptris_document pointer int], :pointer
+      true
+    rescue ::FFI::NotFoundError
+      false
+    end
+
+    # CBOR (RFC 8949, TODO.cbor): absent on libraries before the
+    # codec's release — the CBOR module feature-detects
+    attach_function :yeptris_cbor_decode, %i[pointer size_t uint32 yeptris_status_out],
+                    :yeptris_document
+    callback :cbor_item_cb, %i[pointer yeptris_document size_t], :int
+    attach_function :yeptris_cbor_decode_sequence,
+                    %i[pointer size_t uint32 cbor_item_cb pointer yeptris_status_out], :size_t
+    attach_function :yeptris_cbor_encode, %i[yeptris_document uint32 pointer], :pointer
+    attach_function :yeptris_cbor_encode_sequence,
+                    %i[pointer size_t uint32 pointer], :pointer
+    CBOR_EX = !(@missing ||= []).include?(:yeptris_cbor_decode)
+
+    # Owned char* results (serialize*): one reader, freed exactly once.
+    # The release goes through yeptris_free (libyeptris's own
+    # allocator-matching free) because ffi's :free attach has no
+    # Windows process-symbol fallback — libyeptris.dll doesn't export
+    # libc free, so resolving :free against it fails on Windows.
+    # A raised attach ABORTS this file mid-evaluation — everything
+    # after it (NODE_SCALAR and the kind constants below) never
+    # defines, and a lazily autoloaded node.rb then dies with
+    # 'uninitialized constant' (#138). Every fallback attaches too.
+    YEPTRIS_FREE = begin
+      attach_function :yeptris_free, [:pointer], :void
+      :direct
+    rescue ::FFI::NotFoundError
+      begin
+        # libyeptris < v0.6.6: POSIX resolves :free through the
+        # process symbol table, so the libc attach still works there.
+        attach_function :yeptris_free, :free, [:pointer], :void
+        :libc
+      rescue ::FFI::NotFoundError
+        # no owned-buffer release on this lib+platform combination;
+        # Owned.string leaks instead of killing the whole file
+        :none
+      end
+    end
+
+    # C out-params are size_t — native width (8 everywhere we ship
+    # except ILP32 armv7, where it is 4). The ffi gem (1.17.4) has no
+    # read_size_t, so dispatch on the measured type size: read_uint64
+    # on a 4-byte :size_t buffer ran out of bounds on arm-linux (the
+    # 0.6.18.1 armv7 smoke, valueml.rb:118).
+    SIZE_T_WIDTH = ::FFI.type_size(:size_t)
+
+    def self.read_c_size_t(ptr)
+      SIZE_T_WIDTH == 8 ? ptr.read_uint64 : ptr.read_uint32
+    end
+
+    module Owned
+      module_function
+
+      # Reads a NUL-terminated malloc'd C string into an Encoding
+      # UTF_8 String, then frees the buffer. len_out (nullable) is a
+      # MemoryPointer carrying the byte length from the producing call.
+      def string(ptr, len_out = nil)
+        return nil if ptr.null?
+
+        len = len_out && Yeptris::FFI.read_c_size_t(len_out)
+        s = if len && len > 0
+              ptr.read_bytes(len).force_encoding(Encoding::UTF_8)
+            else
+              ptr.read_string.force_encoding(Encoding::UTF_8)
+            end
+        ::Yeptris::FFI.yeptris_free(ptr) if ::Yeptris::FFI::YEPTRIS_FREE != :none
+        s
+      end
+    end
+
+    module_function
+
+    # Non-OK status -> ParseError carrying the C error channel's
+    # message with line/column. NULL-document failures route through
+    # here too (parse detail lives on the same channel).
+    def check_status(status, action)
+      return if status.zero?
+
+      raise Yeptris::ParseError, "#{action} failed: #{last_error_message}"
+    end
+
+    def last_error_message
+      line = ::FFI::MemoryPointer.new(:uint32)
+      col = ::FFI::MemoryPointer.new(:uint32)
+      msg = yeptris_last_error(line, col)
+      detail = msg.to_s
+      l = line.read_uint32
+      c = col.read_uint32
+      l.positive? ? "#{detail} at line #{l}, column #{c}" : detail
+    end
+
+    # Pinned enum values (test_abi): the constants the binding relies
+    # on without a C header at runtime.
+    NODE_SCALAR = 0
+    NODE_SEQUENCE = 1
+    NODE_MAPPING = 2
+    NODE_ALIAS = 3
+
+    STYLE_PLAIN = 1
+    STYLE_SINGLE_QUOTED = 2
+    STYLE_DOUBLE_QUOTED = 3
+    STYLE_LITERAL = 4
+    STYLE_FOLDED = 5
+
+    TAG_STR = 0
+    TAG_INT = 1
+    TAG_FLOAT = 2
+    TAG_BOOL = 3
+    TAG_NULL = 4
+    TAG_TIMESTAMP = 5
+    TAG_BINARY = 8
+
+    # the schema-descriptor API (issue #238; TODO.restructure/83)
+    DESC_ABI = 1
+    SCHEMA_ERROR = 9
+
+    class DescNode < ::FFI::Struct
+        layout :wire_name, :pointer, :kind, :uint8, :type_tag, :uint8,
+               :flags, :uint16, :child_index, :uint32, :child_count, :uint32,
+               :reserved, :uint32
+      end
+
+    class SchemaColumn < ::FFI::Struct
+        layout :data, :pointer, :capacity, :uint32, :count, :uint32
+    end
+
+    attach_function :yeptris_schema_load,
+                    %i[pointer size_t int pointer uint32 uint32 pointer], :int
+
+    SCHEMA_12_CORE = 0
+    SCHEMA_11_COMPAT = 1
+
+    OK = 0
+    ERROR_PARSE = 1
+    ERROR_MEMORY = 2
+    ERROR_DEPTH = 3
+    ERROR_ENCODING = 4
+    ERROR_IO = 5
+    ERROR_ARG = 6
+    ERROR_UNSUPPORTED = 7
+    ERROR_INTERNAL = 8
+    # The load-time essentials (the read path + the ownership
+    # contract): absent on engines far older than the optional
+    # surfaces — raise the friendly error once every constant has
+    # fully defined, so no partial-module state leaks into autoloads
+    # (the #138 class, closed at the root).
+    ESSENTIAL = %i[
+      yeptris_version yeptris_last_error yeptris_parse yeptris_parse_ex
+      yeptris_parse_json yeptris_document_free yeptris_document_count
+      yeptris_document_root yeptris_node_kind yeptris_node_value
+      yeptris_node_tag_id yeptris_node_style yeptris_document_new
+      yeptris_document_set_root yeptris_serialize yeptris_serialize_ex
+    ].freeze
+    missing_core = ESSENTIAL & (@missing ||= [])
+    raise ::FFI::NotFoundError,
+          "yeptris: the loaded libyeptris is older than this gem " \
+          "requires (missing: #{missing_core.join(', ')}). Update the " \
+          "engine library, or clear the stale copy shadowing it." \
+          unless missing_core.empty?
+
+  end
+end