yeptris 0.6.18.2-arm-linux-eabihf

data/ext/yeptris_native/yeptris_native.c

@@ -0,0 +1,497 @@
+/* yeptris_native.c — Ruby C-API materializer over libyeptris visit
+ * (TODO.restructure/22). One Ruby→C call builds the whole object
+ * graph via rb_hash_new / rb_ary_push / rb_str_new_len — the same
+ * shape as JSON.parse, so the binding can beat it on the fused JSON
+ * path. The extension is optional: LoadError falls back to the FFI
+ * Marshal ladder. */
+
+#include <ruby.h>
+#include <ruby/encoding.h>
+
+#include <stdlib.h>
+#include <string.h>
+
+#include <yeptris/api.h>
+#include <yeptris/error.h>
+#include <yeptris/resolve.h>
+#include <yeptris/visit.h>
+
+#define YEP_RB_MAX_DEPTH 1024
+
+static rb_encoding* utf8_enc;
+
+typedef struct {
+    VALUE stack[YEP_RB_MAX_DEPTH];
+    VALUE keys[YEP_RB_MAX_DEPTH]; /* pending map key at this depth */
+    int is_map[YEP_RB_MAX_DEPTH];
+    int sp;
+    VALUE root;
+    VALUE anchors; /* Hash name=>object for YAML identity */
+    VALUE pending_anchor; /* String name awaiting the next value */
+    int failed;
+} rb_ctx;
+
+static void rb_fail(rb_ctx* c) {
+    c->failed = 1;
+}
+
+static int rb_push_value(rb_ctx* c, VALUE v) {
+    if (c->failed) {
+        return -1;
+    }
+    /* bind pending anchor */
+    if (!NIL_P(c->pending_anchor) && !NIL_P(c->anchors)) {
+        rb_hash_aset(c->anchors, c->pending_anchor, v);
+        c->pending_anchor = Qnil;
+    }
+    if (c->sp == 0) {
+        c->root = v;
+        return 0;
+    }
+    VALUE parent = c->stack[c->sp - 1];
+    if (c->is_map[c->sp - 1]) {
+        VALUE key = c->keys[c->sp - 1];
+        if (NIL_P(key)) {
+            rb_fail(c);
+            return -1;
+        }
+        rb_hash_aset(parent, key, v);
+        c->keys[c->sp - 1] = Qnil;
+    } else {
+        rb_ary_push(parent, v);
+    }
+    return 0;
+}
+
+static int on_null(void* ctx) {
+    return rb_push_value((rb_ctx*)ctx, Qnil);
+}
+
+static int on_bool(void* ctx, int truthy) {
+    return rb_push_value((rb_ctx*)ctx, truthy ? Qtrue : Qfalse);
+}
+
+static int on_int(void* ctx, int64_t v) {
+    return rb_push_value((rb_ctx*)ctx, LL2NUM(v));
+}
+
+static int on_float(void* ctx, double v) {
+    return rb_push_value((rb_ctx*)ctx, DBL2NUM(v));
+}
+
+static rb_encoding* utf8_enc;
+
+static VALUE rb_utf8_str(const char* p, size_t len) {
+    return rb_enc_str_new(p, (long)len, utf8_enc);
+}
+
+/* One-shot interned string (no intermediate alloc) — keys and the
+ * short repeated values ("a"/"b"/…) share one VALUE. */
+static VALUE rb_utf8_interned(const char* p, size_t len) {
+    return rb_enc_interned_str(p, (long)len, utf8_enc);
+}
+
+static int on_string(void* ctx, const char* p, size_t len) {
+    rb_ctx* c = (rb_ctx*)ctx;
+    /* short strings are almost always repeated tokens in JSON corpora;
+     * intern them. Longer payloads stay unique. */
+    VALUE s = (len <= 16) ? rb_utf8_interned(p, len) : rb_utf8_str(p, len);
+    return rb_push_value(c, s);
+}
+
+static int on_key(void* ctx, const char* p, size_t len) {
+    rb_ctx* c = (rb_ctx*)ctx;
+    if (c->sp == 0 || !c->is_map[c->sp - 1]) {
+        rb_fail(c);
+        return -1;
+    }
+    c->keys[c->sp - 1] = rb_utf8_interned(p, len);
+    return 0;
+}
+
+static int on_seq_start(void* ctx) {
+    rb_ctx* c = (rb_ctx*)ctx;
+    if (c->failed || c->sp >= YEP_RB_MAX_DEPTH) {
+        rb_fail(c);
+        return -1;
+    }
+    VALUE a = rb_ary_new();
+    /* bind anchor to the container before placing it */
+    if (!NIL_P(c->pending_anchor) && !NIL_P(c->anchors)) {
+        rb_hash_aset(c->anchors, c->pending_anchor, a);
+        c->pending_anchor = Qnil;
+    }
+    if (c->sp == 0) {
+        c->root = a;
+    } else {
+        VALUE parent = c->stack[c->sp - 1];
+        if (c->is_map[c->sp - 1]) {
+            VALUE key = c->keys[c->sp - 1];
+            if (NIL_P(key)) {
+                rb_fail(c);
+                return -1;
+            }
+            rb_hash_aset(parent, key, a);
+            c->keys[c->sp - 1] = Qnil;
+        } else {
+            rb_ary_push(parent, a);
+        }
+    }
+    c->stack[c->sp] = a;
+    c->is_map[c->sp] = 0;
+    c->keys[c->sp] = Qnil;
+    c->sp++;
+    return 0;
+}
+
+static int on_seq_end(void* ctx) {
+    rb_ctx* c = (rb_ctx*)ctx;
+    if (c->sp <= 0) {
+        rb_fail(c);
+        return -1;
+    }
+    c->sp--;
+    return 0;
+}
+
+static int on_map_start(void* ctx) {
+    rb_ctx* c = (rb_ctx*)ctx;
+    if (c->failed || c->sp >= YEP_RB_MAX_DEPTH) {
+        rb_fail(c);
+        return -1;
+    }
+    VALUE h = rb_hash_new();
+    if (!NIL_P(c->pending_anchor) && !NIL_P(c->anchors)) {
+        rb_hash_aset(c->anchors, c->pending_anchor, h);
+        c->pending_anchor = Qnil;
+    }
+    if (c->sp == 0) {
+        c->root = h;
+    } else {
+        VALUE parent = c->stack[c->sp - 1];
+        if (c->is_map[c->sp - 1]) {
+            VALUE key = c->keys[c->sp - 1];
+            if (NIL_P(key)) {
+                rb_fail(c);
+                return -1;
+            }
+            rb_hash_aset(parent, key, h);
+            c->keys[c->sp - 1] = Qnil;
+        } else {
+            rb_ary_push(parent, h);
+        }
+    }
+    c->stack[c->sp] = h;
+    c->is_map[c->sp] = 1;
+    c->keys[c->sp] = Qnil;
+    c->sp++;
+    return 0;
+}
+
+static int on_map_end(void* ctx) {
+    rb_ctx* c = (rb_ctx*)ctx;
+    if (c->sp <= 0) {
+        rb_fail(c);
+        return -1;
+    }
+    c->sp--;
+    return 0;
+}
+
+static int on_anchor(void* ctx, const char* name, size_t len) {
+    rb_ctx* c = (rb_ctx*)ctx;
+    c->pending_anchor = rb_utf8_str(name, len);
+    return 0;
+}
+
+static int on_alias(void* ctx, const char* name, size_t len) {
+    rb_ctx* c = (rb_ctx*)ctx;
+    VALUE key = rb_utf8_str(name, len);
+    VALUE v = rb_hash_lookup2(c->anchors, key, Qundef);
+    if (v == Qundef) {
+        v = Qnil;
+    }
+    return rb_push_value(c, v);
+}
+
+static int on_doc(void* ctx) {
+    /* multi-doc: for load_all we'd collect; single-load takes first.
+     * reset root so subsequent docs replace — load_stream uses a
+     * different entry that accumulates. */
+    (void)ctx;
+    return 0;
+}
+
+static const YeptrisVisitVTable k_vt = {
+    on_null, on_bool, on_int, on_float, on_string,
+    on_seq_start, on_seq_end, on_map_start, on_map_end,
+    on_key, on_doc, on_anchor, on_alias,
+};
+
+/* fused JSON→Ruby (json_ruby.c) — no vtable, beats JSON.parse */
+VALUE yep_rb_parse_json(const char* p, size_t len, int strict_dup);
+VALUE yep_rb_cbor_load(const char* p, size_t len, int strict);
+
+static VALUE ctx_result(rb_ctx* c, YeptrisStatus st) {
+    if (st != YEPTRIS_OK || c->failed) {
+        if (st == YEPTRIS_ERROR_PARSE) {
+            rb_raise(rb_path2class("Yeptris::ParseError"), "native parse failed");
+        }
+        if (st == YEPTRIS_ERROR_MEMORY) {
+            rb_raise(rb_eNoMemError, "yeptris native");
+        }
+        rb_raise(rb_path2class("Yeptris::Error"), "native materialize failed (%d)", (int)st);
+    }
+    return c->root;
+}
+
+static VALUE native_cbor_load(int argc, VALUE* argv, VALUE self) {
+    (void)self;
+    VALUE input, strict;
+    rb_scan_args(argc, argv, "11", &input, &strict);
+    StringValue(input);
+    VALUE v = yep_rb_cbor_load(RSTRING_PTR(input), (size_t)RSTRING_LEN(input), RTEST(strict));
+    if (v == Qundef) {
+        rb_raise(rb_path2class("Yeptris::ParseError"), "native cbor decode failed");
+    }
+    return v;
+}
+
+static VALUE native_load_json(int argc, VALUE* argv, VALUE self) {
+    (void)self;
+    VALUE input, strict;
+    rb_scan_args(argc, argv, "11", &input, &strict);
+    StringValue(input);
+    return yep_rb_parse_json(RSTRING_PTR(input), (size_t)RSTRING_LEN(input), RTEST(strict));
+}
+
+static VALUE native_load(VALUE self, VALUE input, VALUE schema) {
+    (void)self;
+    StringValue(input);
+    int sch = YEPTRIS_SCHEMA_11_COMPAT;
+    if (!NIL_P(schema)) {
+        Check_Type(schema, T_SYMBOL);
+        if (rb_sym2id(schema) == rb_intern("core_12")) {
+            sch = YEPTRIS_SCHEMA_12_CORE;
+        }
+    }
+    rb_ctx c;
+    memset(&c, 0, sizeof(c));
+    c.root = Qnil;
+    c.pending_anchor = Qnil;
+    c.anchors = rb_hash_new();
+    VALUE already = rb_gc_disable();
+    YeptrisStatus st = yeptris_visit(RSTRING_PTR(input), (size_t)RSTRING_LEN(input),
+                                     (YeptrisSchema)sch, &k_vt, &c);
+    if (already == Qfalse) {
+        rb_gc_enable();
+    }
+    return ctx_result(&c, st);
+}
+
+/* load_stream: accumulate documents into an Array. */
+typedef struct {
+    rb_ctx inner;
+    VALUE docs;
+    int in_doc;
+} rb_stream_ctx;
+
+static int stream_on_doc(void* ctx) {
+    rb_stream_ctx* s = (rb_stream_ctx*)ctx;
+    if (s->in_doc && !NIL_P(s->inner.root)) {
+        rb_ary_push(s->docs, s->inner.root);
+    }
+    s->inner.root = Qnil;
+    s->inner.sp = 0;
+    s->in_doc = 1;
+    return 0;
+}
+
+static VALUE native_load_stream(VALUE self, VALUE input, VALUE schema) {
+    (void)self;
+    StringValue(input);
+    int sch = YEPTRIS_SCHEMA_11_COMPAT;
+    if (!NIL_P(schema) && rb_sym2id(schema) == rb_intern("core_12")) {
+        sch = YEPTRIS_SCHEMA_12_CORE;
+    }
+    rb_stream_ctx s;
+    memset(&s, 0, sizeof(s));
+    s.inner.root = Qnil;
+    s.inner.pending_anchor = Qnil;
+    s.inner.anchors = rb_hash_new();
+    s.docs = rb_ary_new();
+    YeptrisVisitVTable vt = k_vt;
+    vt.on_doc = stream_on_doc;
+    /* trick: the ctx for scalar callbacks is &s.inner, but on_doc needs
+     * &s. Use a unified ctx — rebind all callbacks to take stream ctx
+     * by making inner the first field (already is). on_doc uses outer;
+     * others use inner via same pointer since inner is first field. */
+    YeptrisStatus st = yeptris_visit(RSTRING_PTR(input), (size_t)RSTRING_LEN(input),
+                                     (YeptrisSchema)sch, &vt, &s);
+    if (st == YEPTRIS_OK && !s.inner.failed) {
+        if (!NIL_P(s.inner.root) || s.in_doc) {
+            rb_ary_push(s.docs, s.inner.root);
+        }
+        return s.docs;
+    }
+    return ctx_result(&s.inner, st == YEPTRIS_OK ? YEPTRIS_ERROR_INTERNAL : st);
+}
+
+/* GC-strategy surface (TODO.restructure/34): ENV at load sets the
+ * default; the setter re-picks at runtime so the CI referee can A/B
+ * in-process. Symbols: :disable, :none, :start. */
+extern int yep_rb_gc_mode(void);
+extern void yep_rb_set_gc_mode(int mode);
+extern int yep_rb_ins_mode(void);
+extern void yep_rb_set_ins_mode(int mode);
+extern int yep_rb_cache_mode(void);
+extern void yep_rb_set_cache_mode(int mode);
+extern int yep_rb_shape_mode(void);
+extern void yep_rb_set_shape_mode(int mode);
+extern double yep_rb_scan_time(const char* p, size_t len, int n);
+
+static VALUE native_gc_mode(VALUE self) {
+    (void)self;
+    switch (yep_rb_gc_mode()) {
+    case 1: return ID2SYM(rb_intern("none"));
+    case 2: return ID2SYM(rb_intern("start"));
+    default: return ID2SYM(rb_intern("disable"));
+    }
+}
+
+static VALUE native_ins_mode(VALUE self) {
+    (void)self;
+    return yep_rb_ins_mode() == 1 ? ID2SYM(rb_intern("aset")) : ID2SYM(rb_intern("bulk"));
+}
+
+static VALUE native_ins_mode_set(VALUE self, VALUE mode) {
+    (void)self;
+    Check_Type(mode, T_SYMBOL);
+    ID id = rb_sym2id(mode);
+    if (id == rb_intern("bulk")) yep_rb_set_ins_mode(0);
+    else if (id == rb_intern("aset")) yep_rb_set_ins_mode(1);
+    else rb_raise(rb_eArgError, "ins_mode must be :bulk or :aset");
+    return mode;
+}
+
+static VALUE native_cache_mode(VALUE self) {
+    (void)self;
+    return yep_rb_cache_mode() == 1 ? ID2SYM(rb_intern("off")) : ID2SYM(rb_intern("on"));
+}
+
+static VALUE native_cache_mode_set(VALUE self, VALUE mode) {
+    (void)self;
+    Check_Type(mode, T_SYMBOL);
+    ID id = rb_sym2id(mode);
+    if (id == rb_intern("on")) yep_rb_set_cache_mode(0);
+    else if (id == rb_intern("off")) yep_rb_set_cache_mode(1);
+    else rb_raise(rb_eArgError, "cache_mode must be :on or :off");
+    return mode;
+}
+
+static VALUE native_scan_time(VALUE self, VALUE input, VALUE count) {
+    (void)self;
+    StringValue(input);
+    int n = NUM2INT(count);
+    double secs = yep_rb_scan_time(RSTRING_PTR(input), (size_t)RSTRING_LEN(input), n);
+    return DBL2NUM(secs / (double)n);
+}
+
+static VALUE native_shape_mode(VALUE self) {
+    (void)self;
+    return yep_rb_shape_mode() == 1 ? ID2SYM(rb_intern("natural")) : ID2SYM(rb_intern("pre"));
+}
+
+static VALUE native_shape_mode_set(VALUE self, VALUE mode) {
+    (void)self;
+    Check_Type(mode, T_SYMBOL);
+    ID id = rb_sym2id(mode);
+    if (id == rb_intern("pre")) yep_rb_set_shape_mode(0);
+    else if (id == rb_intern("natural")) yep_rb_set_shape_mode(1);
+    else rb_raise(rb_eArgError, "shape_mode must be :pre or :natural");
+    return mode;
+}
+
+static VALUE native_gc_mode_set(VALUE self, VALUE mode) {
+    (void)self;
+    Check_Type(mode, T_SYMBOL);
+    ID id = rb_sym2id(mode);
+    if (id == rb_intern("disable")) yep_rb_set_gc_mode(0);
+    else if (id == rb_intern("none")) yep_rb_set_gc_mode(1);
+    else if (id == rb_intern("start")) yep_rb_set_gc_mode(2);
+    else rb_raise(rb_eArgError, "gc_mode must be :disable, :none, or :start");
+    return mode;
+}
+
+/* ABI-drift self-check (the #157-audit silent-nil class): the bundle
+ * is compiled against a specific yep_dom layout; engine drift makes
+ * the walkers read fields at stale offsets — cbor_load returned NIL
+ * on valid CBOR in the dev-checkout audit, with no error anywhere.
+ * Both walkers must round-trip a known document at load, or Init
+ * raises LoadError: lib/yeptris.rb's existing rescue falls back to
+ * the FFI ladder (loudly), and the stale bundle never answers with
+ * garbage. Runs inside rb_protect so a drifted walk raises instead of
+ * crashing the load. */
+static VALUE native_self_check_body(VALUE unused) {
+    /* JSON: {"a"=>[1, 2.5, "x", true, nil]} */
+    const char* json = "{\"a\":[1,2.5,\"x\",true,null]}";
+    VALUE j = yep_rb_parse_json(json, strlen(json), 0);
+    if (j == Qundef || !RB_TYPE_P(j, T_HASH)) return Qfalse;
+    VALUE a = rb_hash_lookup(j, rb_str_new_cstr("a"));
+    if (!RB_TYPE_P(a, T_ARRAY) || RARRAY_LEN(a) != 5) return Qfalse;
+    if (!RB_INTEGER_TYPE_P(rb_ary_entry(a, 0))) return Qfalse;
+    if (!RB_FLOAT_TYPE_P(rb_ary_entry(a, 1))) return Qfalse;
+    if (!RB_TYPE_P(rb_ary_entry(a, 2), T_STRING)) return Qfalse;
+    if (rb_ary_entry(a, 3) != Qtrue || !NIL_P(rb_ary_entry(a, 4))) return Qfalse;
+
+    /* CBOR: A1 61 6B 01 = {"k" => 1} (canonical, hand-encoded) */
+    const char cbor[] = "\xA1\x61\x6B\x01";
+    VALUE c = yep_rb_cbor_load(cbor, sizeof(cbor) - 1, 0);
+    if (c == Qundef || !RB_TYPE_P(c, T_HASH)) return Qfalse;
+    VALUE one = rb_hash_lookup(c, rb_str_new_cstr("k"));
+    if (!RB_INTEGER_TYPE_P(one) || !rb_eql(one, INT2FIX(1))) return Qfalse;
+    return Qtrue;
+}
+
+static void native_self_check(void) {
+    int state = 0;
+    VALUE ok = rb_protect(native_self_check_body, Qnil, &state);
+    if (state != 0 || ok != Qtrue) {
+        if (state != 0) rb_set_errinfo(Qnil);
+        rb_raise(rb_eLoadError,
+                 "yeptris: native materializer failed its ABI self-check "
+                 "(stale build against a drifted engine?) — refusing to "
+                 "register; the FFI ladder will carry the load");
+    }
+}
+
+RUBY_FUNC_EXPORTED void Init_native(void) {
+    utf8_enc = rb_utf8_encoding();
+    native_self_check();
+    VALUE mYep = rb_define_module("Yeptris");
+    VALUE mNat = rb_define_module_under(mYep, "Native");
+    rb_define_singleton_method(mNat, "load_json", native_load_json, -1);
+    rb_define_singleton_method(mNat, "cbor_load", native_cbor_load, -1);
+    rb_define_singleton_method(mNat, "load", native_load, 2);
+    rb_define_singleton_method(mNat, "load_stream", native_load_stream, 2);
+    rb_define_singleton_method(mNat, "gc_mode", native_gc_mode, 0);
+    rb_define_singleton_method(mNat, "gc_mode=", native_gc_mode_set, 1);
+    rb_define_singleton_method(mNat, "ins_mode", native_ins_mode, 0);
+    rb_define_singleton_method(mNat, "ins_mode=", native_ins_mode_set, 1);
+    rb_define_singleton_method(mNat, "cache_mode", native_cache_mode, 0);
+    rb_define_singleton_method(mNat, "cache_mode=", native_cache_mode_set, 1);
+    rb_define_singleton_method(mNat, "shape_mode", native_shape_mode, 0);
+    rb_define_singleton_method(mNat, "shape_mode=", native_shape_mode_set, 1);
+    rb_define_singleton_method(mNat, "scan_time", native_scan_time, 2);
+    rb_define_const(mNat, "AVAILABLE", Qtrue);
+    const char* env = getenv("YEPTRIS_NATIVE_GC");
+    if (env != NULL && strcmp(env, "none") == 0) yep_rb_set_gc_mode(1);
+    else if (env != NULL && strcmp(env, "start") == 0) yep_rb_set_gc_mode(2);
+    else if (env != NULL && strcmp(env, "disable") == 0) yep_rb_set_gc_mode(0);
+    const char* ins = getenv("YEPTRIS_NATIVE_INSERT");
+    if (ins != NULL && strcmp(ins, "aset") == 0) yep_rb_set_ins_mode(1);
+    const char* cache = getenv("YEPTRIS_NATIVE_CACHE");
+    if (cache != NULL && strcmp(cache, "off") == 0) yep_rb_set_cache_mode(1);
+    const char* shape = getenv("YEPTRIS_NATIVE_SHAPE");
+    if (shape != NULL && strcmp(shape, "natural") == 0) yep_rb_set_shape_mode(1);
+}

data/lib/yeptris/cbor.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Yeptris
+  # CBOR (RFC 8949) over the same FFI document the rest of the
+  # binding rides (TODO.cbor/04). Decode materializes through the
+  # Psych-compatible path; encode builds the tree with YAMLTree and
+  # hands the document to the C encoder — plain data only (aliases
+  # and non-decimal tag text are unencodable by the C contract).
+  #
+  # Representation notes inherited from the decoder: integers beyond
+  # int64 and bignums materialize as their shortest-double text, byte
+  # strings as tag-chained text — CBOR's JSON-data-model mapping.
+  module CBOR
+    STRICT = (1 << 0) # decode: reject non-minimal arguments
+    CANONICAL = (1 << 1) # encode: s4.2.1 core deterministic profile
+
+    class Error < Yeptris::Error; end
+    class UnencodableError < Error; end
+
+    module_function
+
+    def available?
+      defined?(::Yeptris::FFI::CBOR_EX) && ::Yeptris::FFI::CBOR_EX
+    end
+
+    def load(data, strict: false)
+      raise Error, "libyeptris has no CBOR support" unless available?
+
+      # #157: the native materializer (decode + direct VALUE
+      # construction in one C pass) when the extension is loaded;
+      # the FFI ladder otherwise
+      if defined?(::Yeptris::Native) && ::Yeptris::Native.respond_to?(:cbor_load)
+        return ::Yeptris::Native.cbor_load(data, strict)
+      end
+
+      doc_ptr = ::Yeptris::FFI.yeptris_cbor_decode(data, data.bytesize, strict ? STRICT : 0, nil)
+      raise ParseError, ::Yeptris::FFI.last_error_message if doc_ptr.null?
+
+      # the wrapper's finalizer also frees — its idempotent #free is
+      # the ONLY release path (a raw double free corrupts the heap)
+      doc = ::Yeptris::Document.new(doc_ptr)
+      doc.root.to_ruby
+    ensure
+      doc&.free
+    end
+
+    def load_sequence(data, strict: false)
+      raise Error, "libyeptris has no CBOR support" unless available?
+
+      items = []
+      pending_error = nil
+      receiver = ::FFI::Function.new(:int, %i[pointer pointer size_t]) do |_ctx, item, _index|
+        # the callback owns the item; materialize then free in place
+        # (through the wrapper — the finalizer frees too). A raise
+        # inside an FFI callback leaves the return value undefined —
+        # abort the C iteration cleanly (nonzero) and re-raise after
+        begin
+          doc = ::Yeptris::Document.new(item)
+          items << doc.root&.to_ruby
+          doc.free
+          0
+        rescue ::Exception => e # rubocop:disable Lint/RescueException
+          pending_error = e
+          1
+        end
+      end
+      st = ::Yeptris::FFI.yeptris_cbor_decode_sequence(
+        data, data.bytesize, strict ? STRICT : 0, receiver, nil, nil
+      )
+      raise pending_error if pending_error
+      raise ParseError, ::Yeptris::FFI.last_error_message if st.zero? && !data.empty?
+
+      items
+    end
+
+    def dump(obj, canonical: true)
+      docs = build_documents([obj])
+      begin
+        encode_one(docs[0], canonical)
+      ensure
+        docs.each(&:free)
+      end
+    end
+
+    def dump_sequence(objects, canonical: true)
+      docs = build_documents(objects)
+      begin
+        opts = canonical ? CANONICAL : 0
+        arr = ::FFI::MemoryPointer.new(:pointer, docs.size)
+        arr.write_array_of_pointer(docs.map(&:c_ptr))
+        len_ptr = ::FFI::MemoryPointer.new(:size_t)
+        take_buffer(
+          ::Yeptris::FFI.yeptris_cbor_encode_sequence(arr, docs.size, opts, len_ptr),
+          len_ptr
+        )
+      ensure
+        docs.each(&:free)
+      end
+    end
+
+    # -- internals ----------------------------------------------------
+
+    def build_documents(objects)
+      # ONE document per object: a visitor's tree is a single
+      # document and push sets its root — reuse would overwrite
+      objects.map do |obj|
+        visitor = ::Yeptris::Psych::Visitors::YAMLTree.new
+        visitor.push(obj)
+        visitor.document
+      end
+    end
+
+    def encode_one(doc, canonical)
+      opts = canonical ? CANONICAL : 0
+      len_ptr = ::FFI::MemoryPointer.new(:size_t)
+      take_buffer(::Yeptris::FFI.yeptris_cbor_encode(doc.c_ptr, opts, len_ptr), len_ptr)
+    end
+
+    # The encode convenience contract: a malloc'd buffer plus its
+    # byte length — binary data, freed through the library's own free.
+    def take_buffer(ptr, len_ptr)
+      raise UnencodableError, ::Yeptris::FFI.last_error_message if ptr.null?
+
+      len = Yeptris::FFI.read_c_size_t(len_ptr)
+      ptr.read_bytes(len).force_encoding(Encoding::BINARY)
+    ensure
+      ::Yeptris::FFI.yeptris_free(ptr) if ptr && !ptr.null?
+    end
+  end
+end