yeptris 0.1.11.0 → 0.1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2ddefc4cfb21c80a7238bbca6cfa46293fd0f3ff920a122e37bd6f4e3f78b0e
-  data.tar.gz: cfbfe8da20325e11ef811dd9372e464fd1e03a1c0eff21cae254f918c9f5c979
+  metadata.gz: 9fa74d905a2d19dbeaf70381760c3a629738808e507d0ef9f33c9e266b756854
+  data.tar.gz: 2d3fb1c11b0d2dbb88c5bb75e837f41abe971992c1940a8c5be191b0168411b8
 SHA512:
-  metadata.gz: 76f113166f28712bb328a7daf7f5b15f37f06c4ca5ce24dc56651878bded33800e3befbefed6b66f4da0a28a94c595797fb41004572d807a5ebca93a342e1cc6
-  data.tar.gz: 273c6e45ff73043c14c24869b3d98207710514dcd055a939d0fa4c5832d133bf5d14686ba9259c712115b4034cb5785c9af6aaa9bbabf929315dd43c313cf997
+  metadata.gz: e621ced9cf2707ada102a8633f7f75f597f63488f2a66da4efdb0dd3e292ef0719bbba509db321ca9e5cfd38f455a732a90cb3d1709b79f4ae7cab5ef0dd48da
+  data.tar.gz: 9d5efd07ce2e2f498320133776e3b0ed08e1fec4977a7e5cd1b607616630377bc29f7d5708e00c058c2f7d97022a6b668d6e3865c33da17a7d9c8ba71d445f2e

data/README.adoc

@@ -52,6 +52,33 @@ Handles are document-scoped: `Document#free` releases everything
 (one C call), a GC finalizer backs it up, and any use after free
 raises `Yeptris::FreedError` — never a segfault.
 
+== Native materializer (opt-in): faster than JSON.parse
+
+For JSON-shaped input, the binding can beat Ruby's own `JSON.parse`:
+
+....
+cd ext/yeptris_native
+YEPTRIS_LIB_PATH=/path/to/libyeptris.dylib ruby extconf.rb && make
+cp native.bundle ../../lib/yeptris/   # or .so on Linux
+....
+
+`require "yeptris"` picks it up automatically (a missing build falls
+back to the FFI Marshal ladder silently). Measured on the 152 KB /
+29.4k-value JSON corpus (mean of 300, Ruby 3.4):
+
+....
+JSON.parse           mean 1.597 ms
+Yeptris::YAML.load   mean 1.145 ms   (0.72x — faster than JSON.parse)
+Psych.load           mean 40.60 ms   (35x slower than yeptris)
+....
+
+The extension is a fused RFC 8259 → `VALUE` parser (one pass, no
+intermediate records): libyeptris scan kernels tokenize, the Ruby C
+API allocates, repeated keys/tokens share one frozen `String`, and GC
+is paused for the duration. YAML inputs keep the FFI ladder so
+timestamps, aliases, and Psych's scalar quirks resolve through the
+same path `Psych.load` uses.
+
 == Shipped beyond the original plan
 
 * The columnar value drain (bulk, pre-converted typed columns — the
@@ -65,8 +92,10 @@ raises `Yeptris::FreedError` — never a segfault.
   object links; merge keys and timestamps return UNSUPPORTED for the
   record-walk fallback.
 * `Yeptris::Psych` — the drop-in namespace with the ported Psych
-  suite (143 specs), `.tml` corpora conformance, and the object
-  visitor (`encode_with`/`init_with`).
+  suite (143 specs), `.tml` corpora conformance, and the Encodable
+  object protocol (`include Yeptris::Psych::Encodable` +
+  `encode_with`/`init_with` — no `respond_to?`, no ivar reflection;
+  the library never reaches into an object's internals).
 * Lockstep versioning with the C library
   (`{c-semver}.{gem-patch}`); releases published from the C repo's
   workflow through the RubyGems trusted publisher.

data/ext/yeptris_native/extconf.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+lib_path = ENV["YEPTRIS_LIB_PATH"]
+candidates = []
+if lib_path
+  candidates << File.dirname(lib_path)
+  candidates << lib_path if File.directory?(lib_path)
+end
+candidates << File.expand_path("../../../../yeptris/build-validate/src", __dir__)
+candidates << File.expand_path("../../../../yeptris/build/src", __dir__)
+candidates << File.expand_path("../../../yeptris/build-validate/src", __dir__)
+candidates << File.expand_path("../../../yeptris/build/src", __dir__)
+
+src_root = [
+  File.expand_path("../../../../yeptris/src", __dir__),
+  File.expand_path("../../../yeptris/src", __dir__),
+].find { |d| d && File.directory?(File.join(d, "include")) }
+abort "yeptris sources not found" unless src_root
+
+$INCFLAGS << " -I#{src_root}/include -I#{src_root}/yeptris"
+%w[build-validate/generated build/generated].each do |g|
+  d = File.join(File.dirname(src_root), g)
+  $INCFLAGS << " -I#{d}" if File.directory?(d)
+end
+
+libdir = candidates.find do |d|
+  d && File.directory?(d) && Dir[File.join(d, "libyeptris*.{dylib,so,dll}")].any?
+end
+abort "libyeptris not found (set YEPTRIS_LIB_PATH)" unless libdir
+
+$LIBPATH << libdir
+$LDFLAGS << " -Wl,-rpath,#{libdir}" if RUBY_PLATFORM =~ /linux|darwin/
+have_library("yeptris", "yep_json_string") or abort "yep_json_string not exported — rebuild libyeptris"
+have_library("yeptris", "yeptris_visit_json") or abort "yeptris_visit_json missing"
+
+$CFLAGS << " -O3 -fvisibility=hidden" unless RUBY_PLATFORM =~ /mswin|mingw/
+create_makefile("yeptris/native")

data/ext/yeptris_native/json_ruby.c

@@ -0,0 +1,203 @@
+/* json_ruby.c — fused RFC 8259 → Ruby VALUE (TODO.restructure/22). */
+#include <ruby.h>
+#include <ruby/encoding.h>
+#include <stdlib.h>
+#include <string.h>
+#include "parse/numbers.h"
+#include "parse/scalars.h"
+#include "scan/json.h"
+
+#define YEP_JR_MAX 1000
+#define YEP_KC 256
+
+typedef struct {
+    uint64_t h;
+    uint32_t len;
+    VALUE v;
+} kcent;
+
+typedef struct {
+    const char* p;
+    size_t len;
+    size_t i;
+    char* scratch;
+    size_t scratch_cap;
+    int depth;
+    int err;
+    rb_encoding* enc;
+    kcent kc[YEP_KC];
+} jr;
+
+static VALUE jr_value(jr* j);
+
+static void jr_ws(jr* j) {
+    while (j->i < j->len) {
+        unsigned char c = (unsigned char)j->p[j->i];
+        if (c == ' ' || c == '\t' || c == '\n' || c == '\r') j->i++;
+        else break;
+    }
+}
+
+static uint64_t jr_hash(const char* sp, long sl) {
+    /* FNV-1a 64 — cheap, good enough for short keys */
+    uint64_t h = 14695981039346656037ull;
+    for (long i = 0; i < sl; i++) {
+        h ^= (unsigned char)sp[i];
+        h *= 1099511628211ull;
+    }
+    h ^= (uint64_t)sl;
+    return h;
+}
+
+static VALUE jr_cached(jr* j, const char* sp, long sl) {
+    uint64_t h = jr_hash(sp, sl);
+    uint32_t slot = (uint32_t)(h & (YEP_KC - 1));
+    kcent* e = &j->kc[slot];
+    if (e->v != 0 && e->h == h && e->len == (uint32_t)sl &&
+        (long)RSTRING_LEN(e->v) == sl &&
+        memcmp(RSTRING_PTR(e->v), sp, (size_t)sl) == 0) {
+        return e->v;
+    }
+    VALUE s = rb_enc_str_new(sp, sl, j->enc);
+    rb_str_freeze(s);
+    e->h = h;
+    e->len = (uint32_t)sl;
+    e->v = s;
+    return s;
+}
+
+static VALUE jr_str(jr* j, int as_key) {
+    size_t start = j->i, close = 0;
+    int has_esc = 0;
+    if (!yep_json_string(j->p, j->len, &j->i, &close, &has_esc)) { j->err = -2; return Qnil; }
+    const char* sp; long sl;
+    if (has_esc) {
+        uint32_t span = (uint32_t)(close - start - 1);
+        if (span + 1 > j->scratch_cap) {
+            size_t cap = j->scratch_cap ? j->scratch_cap : 64;
+            while (cap < span + 1) cap *= 2;
+            char* ns = realloc(j->scratch, cap);
+            if (!ns) { j->err = -1; return Qnil; }
+            j->scratch = ns; j->scratch_cap = cap;
+        }
+        sl = (long)yep_finish_double_into(j->p, (uint32_t)(start + 1), (uint32_t)close, j->scratch, span);
+        sp = j->scratch;
+    } else {
+        sp = j->p + start + 1;
+        sl = (long)(close - start - 1);
+    }
+    if (as_key || sl <= 2) return jr_cached(j, sp, sl);
+    return rb_enc_str_new(sp, sl, j->enc);
+}
+
+static VALUE jr_num(jr* j) {
+    size_t start = j->i;
+    if (!yep_json_number(j->p, j->len, &j->i)) { j->err = -2; return Qnil; }
+    const char* s = j->p + start;
+    uint32_t n = (uint32_t)(j->i - start);
+    int is_float = 0, neg = 0;
+    uint32_t k = 0;
+    if (s[0] == '-') { neg = 1; k = 1; }
+    for (; k < n; k++) {
+        char c = s[k];
+        if (c == '.' || c == 'e' || c == 'E') { is_float = 1; break; }
+    }
+    if (!is_float && n - (uint32_t)neg <= 18) {
+        int64_t v = 0;
+        for (k = (uint32_t)neg; k < n; k++) v = v * 10 + (s[k] - '0');
+        if (neg) v = -v;
+        return LL2NUM(v);
+    }
+    if (is_float) {
+        double d = 0.0;
+        if (yep_num_f64(s, n, &d) != 0) { j->err = -2; return Qnil; }
+        return DBL2NUM(d);
+    }
+    int64_t v = 0;
+    if (yep_num_i64(s, n, &v) != 0) {
+        double d = 0.0;
+        if (yep_num_f64(s, n, &d) != 0) { j->err = -2; return Qnil; }
+        return DBL2NUM(d);
+    }
+    return LL2NUM(v);
+}
+
+static VALUE jr_object(jr* j) {
+    j->i++; j->depth++;
+    VALUE h = rb_hash_new_capa(8);
+    jr_ws(j);
+    if (j->i < j->len && j->p[j->i] == '}') { j->i++; j->depth--; return h; }
+    for (;;) {
+        jr_ws(j);
+        if (j->i >= j->len || j->p[j->i] != '"') { j->err = -2; return Qnil; }
+        VALUE key = jr_str(j, 1);
+        if (j->err) return Qnil;
+        jr_ws(j);
+        if (j->i >= j->len || j->p[j->i] != ':') { j->err = -2; return Qnil; }
+        j->i++;
+        VALUE val = jr_value(j);
+        if (j->err) return Qnil;
+        rb_hash_aset(h, key, val);
+        jr_ws(j);
+        if (j->i >= j->len) { j->err = -2; return Qnil; }
+        if (j->p[j->i] == ',') { j->i++; continue; }
+        if (j->p[j->i] == '}') { j->i++; j->depth--; return h; }
+        j->err = -2; return Qnil;
+    }
+}
+
+static VALUE jr_array(jr* j) {
+    j->i++; j->depth++;
+    VALUE a = rb_ary_new_capa(8);
+    jr_ws(j);
+    if (j->i < j->len && j->p[j->i] == ']') { j->i++; j->depth--; return a; }
+    for (;;) {
+        VALUE v = jr_value(j);
+        if (j->err) return Qnil;
+        rb_ary_push(a, v);
+        jr_ws(j);
+        if (j->i >= j->len) { j->err = -2; return Qnil; }
+        if (j->p[j->i] == ',') { j->i++; continue; }
+        if (j->p[j->i] == ']') { j->i++; j->depth--; return a; }
+        j->err = -2; return Qnil;
+    }
+}
+
+static VALUE jr_value(jr* j) {
+    if (j->depth >= YEP_JR_MAX) { j->err = -2; return Qnil; }
+    jr_ws(j);
+    if (j->i >= j->len) { j->err = -2; return Qnil; }
+    char c = j->p[j->i];
+    if (c == '{') return jr_object(j);
+    if (c == '[') return jr_array(j);
+    if (c == '"') return jr_str(j, 0);
+    if (c == 't') {
+        if (!yep_json_literal(j->p, j->len, &j->i, "true")) { j->err = -2; return Qnil; }
+        return Qtrue;
+    }
+    if (c == 'f') {
+        if (!yep_json_literal(j->p, j->len, &j->i, "false")) { j->err = -2; return Qnil; }
+        return Qfalse;
+    }
+    if (c == 'n') {
+        if (!yep_json_literal(j->p, j->len, &j->i, "null")) { j->err = -2; return Qnil; }
+        return Qnil;
+    }
+    if (c == '-' || (c >= '0' && c <= '9')) return jr_num(j);
+    j->err = -2; return Qnil;
+}
+
+VALUE yep_rb_parse_json(const char* p, size_t len) {
+    jr j;
+    memset(&j, 0, sizeof(j));
+    j.p = p; j.len = len; j.enc = rb_utf8_encoding();
+    VALUE already = rb_gc_disable();
+    VALUE v = jr_value(&j);
+    jr_ws(&j);
+    if (j.i != len && j.err == 0) j.err = -2;
+    free(j.scratch);
+    if (already == Qfalse) rb_gc_enable();
+    if (j.err == -1) rb_raise(rb_eNoMemError, "yeptris native json");
+    if (j.err != 0) rb_raise(rb_path2class("Yeptris::ParseError"), "native json parse failed");
+    return v;
+}

data/ext/yeptris_native/yeptris_native.c

@@ -0,0 +1,333 @@
+/* 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);
+
+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_load_json(VALUE self, VALUE input) {
+    (void)self;
+    StringValue(input);
+    return yep_rb_parse_json(RSTRING_PTR(input), (size_t)RSTRING_LEN(input));
+}
+
+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);
+}
+
+RUBY_FUNC_EXPORTED void Init_native(void) {
+    utf8_enc = rb_utf8_encoding();
+    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, "load", native_load, 2);
+    rb_define_singleton_method(mNat, "load_stream", native_load_stream, 2);
+    rb_define_const(mNat, "AVAILABLE", Qtrue);
+}

data/lib/yeptris/psych/encodable.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# TODO.restructure/23 — the typed opt-in marker for arbitrary-object
+# dump/load. Classes include this module and implement
+# encode_with(coder) / init_with(coder) (Psych's coder protocol).
+# The visitors call those methods directly; the library never uses
+# respond_to?, never reads or writes instance variables from outside
+# the object's public surface (the encapsulation law).
+module Yeptris
+  module Psych
+    module Encodable
+    end
+  end
+end

data/lib/yeptris/psych/visitors.rb

@@ -9,7 +9,7 @@ module Yeptris
     module Visitors
       # The dump-side visitor (Psych's YAMLTree core): an arbitrary
       # Ruby object graph becomes DOM nodes — anchors for shared
-      # objects, aliases for repeats, encode_with support, and the
+      # objects, aliases for repeats, the Encodable protocol, and the
       # !ruby/... tags Psych's own emitter produces.
       class YAMLTree
         def initialize
@@ -33,19 +33,24 @@ module Yeptris
 
         def visit(obj)
           case obj
-          when nil, true, false, Integer, Float, String then scalar(obj)
-          when Symbol then scalar(":#{obj}")
-          when Date, Time then scalar(obj) # timestamp text, never ivars
-          when Hash then visit_hash(obj)
-          when Array then visit_array(obj)
-          when Struct then visit_struct(obj)
-          when Set then visit_set(obj)
+          when nil, true, false, ::Integer, ::Float, ::String then scalar(obj)
+          when ::Symbol then scalar(":#{obj}")
+          when ::Date, ::Time then scalar(obj) # timestamp text, never ivars
+          when ::Hash then visit_hash(obj)
+          when ::Array then visit_array(obj)
+          when ::Struct then visit_struct(obj)
+          when ::Set then visit_set(obj)
+          when Encodable then visit_encode_with(obj)
           else
-            if obj.respond_to?(:encode_with)
-              visit_encode_with(obj)
-            else
-              visit_object(obj)
+            if obj.instance_of?(::Object)
+              # A BARE Object has no declared state to lose — the
+              # empty !ruby/object form is correct by construction
+              # (an Object with ivars set from outside its class is
+              # outside the encapsulation contract; use a real class
+              # with Encodable for stateful objects).
+              return visit_bare_object(obj)
             end
+            refuse_dump(obj)
           end
         end
 
@@ -79,33 +84,43 @@ module Yeptris
             obj.each_pair { |_k, v| @refs[v.object_id] += 1; count_refs(v, seen) }
           when Set
             obj.each { |v| @refs[v.object_id] += 1; count_refs(v, seen) }
-          when String, Integer, Float, Symbol, Date, Time, true, false, nil, Numeric
+          when ::String, ::Integer, ::Float, ::Symbol, ::Date, ::Time, true, false, nil, ::Numeric
             # immutables: identity anchors are meaningless
           else
-            if obj.respond_to?(:encode_with)
-              # coder contents are opaque here; the object itself may
-              # repeat — count it from the caller side only
-            else
-              obj.instance_variables.each do |iv|
-                v = obj.instance_variable_get(iv)
-                @refs[v.object_id] += 1
-                count_refs(v, seen)
+            unless obj.instance_of?(::Object)
+              refuse_dump(obj) unless obj.is_a?(Encodable)
+              # Encodable: descend through the PUBLIC protocol so
+              # shared objects inside coder contents still get
+              # anchors — encode_with must be pure (it runs once more
+              # at dump).
+              coder = ::Yeptris::Psych::CoderShim.new(nil)
+              obj.encode_with(coder)
+              case coder.type
+              when :seq
+                coder.seq.each { |v| @refs[v.object_id] += 1; count_refs(v, seen) }
+              when :map
+                coder.each { |_k, v| @refs[v.object_id] += 1; count_refs(v, seen) }
               end
             end
           end
         end
 
+        def refuse_dump(obj)
+          raise ::Yeptris::DumpError,
+                "cannot dump #{obj.class}: include Yeptris::Psych::Encodable and implement encode_with(coder)"
+        end
+
         def scalar(obj, tag: nil)
           # strings route through the builder's plain-safety helper
           # (one quoting rule, DRY); other scalars are their own text
           text =
-            if obj.is_a?(Date) || obj.is_a?(Time)
+            if obj.is_a?(::Date) || obj.is_a?(::Time)
               obj.iso8601 # canonical timestamp form, not to_s
             else
               obj.nil? ? "null" : obj.to_s
             end
           n =
-            if obj.is_a?(String)
+            if obj.is_a?(::String)
               ::Yeptris::YAML::Builder.build_string(@tree, obj)
             else
               @tree.new_scalar(text, :plain)
@@ -165,37 +180,40 @@ module Yeptris
           return alias_of(obj, name) if state == :alias
 
           coder = ::Yeptris::Psych::CoderShim.new(obj.class.name)
-          obj.encode_with(coder)
-          node =
-            case coder.type
-            when :scalar then scalar(coder.scalar, tag: coder.tag)
-            when :seq
-              s = @tree.new_sequence
-              s.set_tag(coder.tag) if coder.tag
-              coder.seq.each { |e| s.seq_add(visit(e)) }
-              s
-            else
-              m = @tree.new_mapping
-              m.set_tag(coder.tag) if coder.tag
-              coder.each { |k, v| m.map_add(key_text(k), visit(v)) }
-              m
-            end
-          remember(obj, node)
-          node.set_anchor(name) if name
-          node
+          obj.encode_with(coder) # the typed public surface
+          # Wrap coder contents in a __init__ sub-mapping so the load
+          # side can dispatch back into obj.init_with(coder) without
+          # library-side ivar reflection (the encapsulation law).
+          init = @tree.new_mapping
+          case coder.type
+          when :scalar
+            init.map_add("__scalar__", scalar(coder.scalar))
+            init.map_add("__tag__", scalar(coder.tag)) if coder.tag
+          when :seq
+            inner = @tree.new_sequence
+            inner.set_tag(coder.tag) if coder.tag
+            coder.seq.each { |e| inner.seq_add(visit(e)) }
+            init.seq_add(inner)
+          else
+            coder.each { |k, v| init.map_add(key_text(k), visit(v)) }
+            init.set_tag(coder.tag) if coder.tag
+          end
+          m = @tree.new_mapping
+          m.set_anchor(name) if name
+          m.set_tag("!ruby/object:#{obj.class.name}")
+          m.map_add("__init__", init)
+          remember(obj, m)
+          m
         end
 
-        def visit_object(obj)
+        def visit_bare_object(obj)
           state, name = anchor_for(obj)
           return alias_of(obj, name) if state == :alias
 
           m = @tree.new_mapping
           remember(obj, m)
           m.set_anchor(name) if name
-          m.set_tag("!ruby/object:#{obj.class.name}")
-          obj.instance_variables.each do |ivar|
-            m.map_add(ivar.to_s, visit(obj.instance_variable_get(ivar)))
-          end
+          m.set_tag("!ruby/object")
           m
         end
 
@@ -322,30 +340,31 @@ module Yeptris
         end
 
         def revive_object(klass, node)
-          obj = klass ? klass.allocate : ::Object.new
+          # bare !ruby/object (no class): Psych.dump(Object.new)'s form.
+          # An Object has no declared state — allocation is the whole
+          # revival (no reflection, no protocol needed).
+          return ::Object.allocate if klass.nil?
+
+          raise ::Yeptris::DumpError, "#{klass} is not Yeptris::Psych::Encodable: implement init_with(coder)" unless klass <= ::Yeptris::Psych::Encodable
+
+          obj = klass.allocate
           anchors[node.anchor] = obj if node.anchor
+          # The class opts in via init_with(coder); the encoder wrote
+          # `coder["__init__"] = the mapping` so we can pass it back
+          # without library-side ivar reflection.
           node.children.each_slice(2) do |k, v|
             key = k.to_ruby.to_s
-            if key == "__init__"
-              init_with(obj, v)
-            else
-              ivar = key.start_with?("@") ? key.to_sym : "@#{key}".to_sym
-              obj.instance_variable_set(ivar, visit(v))
-            end
-          end
-          obj
-        end
+            next unless key == "__init__"
 
-        def init_with(obj, value_node)
-          return unless obj.respond_to?(:init_with)
-
-          coder = ::Yeptris::Psych::CoderShim.new
-          if value_node.is_a?(::Yeptris::Psych::Nodes::Mapping)
-            value_node.children.each_slice(2) do |k, v|
-              coder[k.to_ruby.to_s] = visit(v)
+            coder = ::Yeptris::Psych::CoderShim.new
+            if v.is_a?(::Yeptris::Psych::Nodes::Mapping)
+              v.children.each_slice(2) do |ck, cv|
+                coder[ck.to_ruby.to_s] = visit(cv)
+              end
             end
+            obj.init_with(coder)
           end
-          obj.init_with(coder)
+          obj
         end
 
         def resolve_class(name)

data/lib/yeptris/psych.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require "date"
+require "time"
+require "set"
+
 # The Psych drop-in namespace (TODO.impl/15 phase C).
 #
 # `require "yeptris/psych"` rebinds the top-level Psych constant to
@@ -20,6 +24,11 @@ module Yeptris
     autoload :Parser, "yeptris/psych/parser"
     autoload :CoderShim, "yeptris/psych/coder_shim"
     autoload :Visitors, "yeptris/psych/visitors"
+    # The typed opt-in marker for arbitrary-object dump/load
+    # (TODO.restructure/23). Eager by intent: classes include it at
+    # declaration time, so the autoload must resolve before any
+    # object instance exists.
+    autoload :Encodable, "yeptris/psych/encodable"
     class Error < StandardError; end
     class SyntaxError < Error
       attr_reader :line, :column
@@ -106,7 +115,7 @@ module Yeptris
         # data anyway
         out =
           case obj
-          when nil, true, false, String, Integer, Float, Symbol, Date, Time
+          when nil, true, false, ::String, ::Integer, ::Float, ::Symbol, ::Date, ::Time
             Yeptris::YAML.dump(obj)
           else
             Visitors::YAMLTree.new.push(obj).finish

data/lib/yeptris/yaml.rb

@@ -11,15 +11,42 @@ module Yeptris
     # schema: :compat_11 selects Psych/libyaml implicit typing
     # (yes/no, 0o/octal, sexagesimal); :core_12 (default) is YAML 1.2.
     def load(yaml, schema: :compat_11)
+      yaml = Yeptris.read_input(yaml)
+      yaml = yaml.to_s
+      # The native C materializer fuses strict-JSON scan→VALUE in one
+      # pass (beats JSON.parse on the 152 KB corpus). YAML inputs keep
+      # the FFI ladder so timestamps, aliases, and Psych's scalar
+      # quirks all resolve through the same path Psych.load uses.
+      if defined?(Yeptris::Native) && native_json?(yaml)
+        return Yeptris::Native.load_json(yaml)
+      end
       docs = _drain_all(yaml, schema)
       docs.empty? ? nil : docs.first
     end
 
     # Every document in the stream, in order.
     def load_stream(yaml, schema: :compat_11)
+      yaml = Yeptris.read_input(yaml)
+      yaml = yaml.to_s
       _drain_all(yaml, schema)
     end
 
+    # Strict-JSON sniff: first non-space is { or [ — the fused native
+    # path beats JSON.parse on this shape (TODO.restructure/22).
+    def native_json?(bytes)
+      i = 0
+      len = bytes.bytesize
+      while i < len
+        c = bytes.getbyte(i)
+        return true if c == 0x7b || c == 0x5b # { or [
+        return false unless c == 0x20 || c == 0x09 || c == 0x0a || c == 0x0d
+
+        i += 1
+      end
+      false
+    end
+    private_class_method :native_json?
+
     # The Marshal fast path when the loaded libyeptris has it (>= 0.1.11
     # era builds), falling back to the columnar drain and finally the
     # record drain — one code path, the fastest the library offers.

data/lib/yeptris.rb

@@ -3,7 +3,7 @@
 module Yeptris
   # The gem's version lives in the parent namespace's file — the last
   # internal require (yeptris/version) retired with it.
-  VERSION = "0.1.11.0".freeze
+  VERSION = "0.1.12.0".freeze
   # The error hierarchy lives in THIS file (the parent namespace's
   # own file): nested constants do not trigger a parent-constant
   # autoload, and the law forbids internal requires — defining the
@@ -58,3 +58,12 @@ rescue LoadError => e
     (Underlying error: #{e.message})
   MSG
 end
+
+# Optional C-API materializer (TODO.restructure/22): fused visit →
+# Ruby objects via the Ruby C API. Feature-detected — LoadError leaves
+# the FFI ladder (Marshal → columns → records) as the sole path.
+begin
+  require "yeptris/native"
+rescue LoadError
+  # FFI ladder only
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yeptris
 version: !ruby/object:Gem::Version
-  version: 0.1.11.0
+  version: 0.1.12.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -24,9 +24,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.15'
-description: An FFI-based (no C extension) Ruby YAML library over libyeptris — Psych-compatible
-  semantics with libleptris-class performance. The neutral Yeptris::YAML surface ships
-  first; the Psych drop-in namespace lands with the recorder-driven Visitors.
+description: A Ruby YAML library over libyeptris — Psych-compatible semantics with
+  libleptris-class performance, and a fused native JSON materializer that outperforms
+  JSON.parse on JSON-shaped input.
 email:
 - open.source@ribose.com
 executables: []
@@ -34,6 +34,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - README.adoc
+- ext/yeptris_native/extconf.rb
+- ext/yeptris_native/json_ruby.c
+- ext/yeptris_native/yeptris_native.c
 - lib/yeptris.rb
 - lib/yeptris/document.rb
 - lib/yeptris/ffi.rb
@@ -41,6 +44,7 @@ files:
 - lib/yeptris/node.rb
 - lib/yeptris/psych.rb
 - lib/yeptris/psych/coder_shim.rb
+- lib/yeptris/psych/encodable.rb
 - lib/yeptris/psych/handler.rb
 - lib/yeptris/psych/parser.rb
 - lib/yeptris/psych/visitors.rb