yeptris 0.1.11.0 → 0.1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2ddefc4cfb21c80a7238bbca6cfa46293fd0f3ff920a122e37bd6f4e3f78b0e
-  data.tar.gz: cfbfe8da20325e11ef811dd9372e464fd1e03a1c0eff21cae254f918c9f5c979
+  metadata.gz: 76bc800fd5065540397d957ca2162d2491474a086eda5b08436f016daa8f65e4
+  data.tar.gz: 683259ac45cfb084722337af80c066890bdf56f2608843343ebf8951589eafa8
 SHA512:
-  metadata.gz: 76f113166f28712bb328a7daf7f5b15f37f06c4ca5ce24dc56651878bded33800e3befbefed6b66f4da0a28a94c595797fb41004572d807a5ebca93a342e1cc6
-  data.tar.gz: 273c6e45ff73043c14c24869b3d98207710514dcd055a939d0fa4c5832d133bf5d14686ba9259c712115b4034cb5785c9af6aaa9bbabf929315dd43c313cf997
+  metadata.gz: 3b2be1bc057ee5a059e80ac087000afd2cee325473d834db34bd0f898318634e7b9be95dce9b523f909ae6884a56c9ede549a0e7142184eddf4cc96a13a11cb9
+  data.tar.gz: e95683f3b475a0dca70488a43cdf23a249d2bcd49c440b4c75bf31914265c0eae9fd2992d1bf6c0ebfa5b0487b796f1a24505e42b4715840c1731ce2af845a4c

data/README.adoc

@@ -52,6 +52,48 @@ 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.
 
+== Two load surfaces: YAML and strict JSON
+
+`Yeptris::YAML.load` keeps the Psych contract for EVERY input —
+including JSON-shaped ones. `{"a": [1,]}` is legal flow YAML (spec
+production [141] allows the trailing comma); `"1e3"` is a Psych
+String. These semantics never flip because input happens to look
+like JSON.
+
+`Yeptris::JSON.load` is the STRICT RFC 8259 surface — exact
+`JSON.parse` semantics by construction (spec-pinned in
+`spec/json_parity_spec.rb`: every value and every error case,
+Bignum integers, exponent-only floats, duplicate keys). Engines,
+fastest first:
+
+1. **Native materializer** (opt-in build; see below): a fused C scan
+   → `VALUE` parser. Order-alternating interleaved profile, 152 KB /
+   ~29k-value corpus, Ruby 3.4:
++
+....
+JSON.parse        min 0.670  med 0.966  mean 0.910 ms
+Yeptris::JSON     min 0.637  med 0.674  mean 0.680 ms
+                  mean 0.75x faster, head-to-head 370/400 (92.5%)
+....
+2. **Record-drain fallback** (always available): the strict-JSON
+   validator gates, then the value records convert without the Psych
+   quirk table — exact parity with engine 1, spec-pinned.
+
+The committed profile (`benchmark/json_profile.rb`) is the fair
+benchmark of record — any performance claim runs through it.
+
+=== Building the native materializer (opt-in)
+
+....
+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 (`Yeptris::JSON` then
+uses it; missing builds silently use the fallback — the gem installs
+without compiling).
+
 == Shipped beyond the original plan
 
 * The columnar value drain (bulk, pre-converted typed columns — the
@@ -65,8 +107,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,43 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+# libyeptris location: YEPTRIS_LIB_PATH (file or dir), then sibling
+# checkouts. CI sets YEPTRIS_LIB_PATH (the built shared library) and
+# YEPTRIS_SRC (the C checkout) explicitly.
+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__)
+
+# Source root: YEPTRIS_SRC (CI / explicit), then sibling checkouts.
+src_roots = [ENV["YEPTRIS_SRC"]].compact
+src_roots << File.expand_path("../../../../yeptris/src", __dir__)
+src_roots << File.expand_path("../../../yeptris/src", __dir__)
+src_root = src_roots.find { |d| d && File.directory?(File.join(d, "include")) }
+abort "yeptris sources not found (set YEPTRIS_SRC)" 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,221 @@
+/* json_ruby.c — fused RFC 8259 → Ruby VALUE (TODO.restructure/22). */
+#include <ruby.h>
+#include <ruby/encoding.h>
+#include <ruby/intern.h>
+#include <stdlib.h>
+#include <string.h>
+#include "parse/scalars.h"
+#include "scan/json.h"
+
+#define YEP_JR_MAX 1000
+#define YEP_KC 1024
+
+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 <= 24) 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;
+    int shape = 0;
+    int64_t iv = 0;
+    double dv = 0.0;
+    /* the fused kernel (scan/json.h): ONE grammar walk, values out */
+    if (!yep_json_number_scan(j->p, j->len, &j->i, &shape, &iv, &dv)) {
+        j->err = -2;
+        return Qnil;
+    }
+    if (shape == 0) {
+        return LL2NUM(iv);
+    }
+    if (shape == 1) {
+        return DBL2NUM(dv);
+    }
+    /* integer text beyond int64: exact Bignum from the validated
+     * span (JSON.parse's behavior). Absurd lengths degrade to the
+     * approximate double. */
+    size_t n = j->i - start;
+    if (n < 512) {
+        char buf[512];
+        memcpy(buf, j->p + start, n);
+        buf[n] = '\0';
+        return rb_cstr_to_inum(buf, 10, TRUE);
+    }
+    return DBL2NUM(dv);
+}
+
+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; }
+    /* pairs collect into a flat buffer and land in ONE bulk insert:
+     * rb_hash_bulk_insert skips the per-pair method dispatch the
+     * aset loop pays (TODO.restructure/26's margin work) */
+    VALUE pairs[64];
+    VALUE* pv = pairs;
+    size_t pcap = 64, pn = 0, heap_cap = 0;
+    for (;;) {
+        jr_ws(j);
+        if (j->i >= j->len || j->p[j->i] != '"') { j->err = -2; goto out; }
+        VALUE key = jr_str(j, 1);
+        if (j->err) goto out;
+        jr_ws(j);
+        if (j->i >= j->len || j->p[j->i] != ':') { j->err = -2; goto out; }
+        j->i++;
+        VALUE val = jr_value(j);
+        if (j->err) goto out;
+        if (pn + 2 > pcap) {
+            size_t ncap = pcap * 2;
+            VALUE* nv = malloc(ncap * sizeof(VALUE));
+            if (!nv) { j->err = -1; goto out; }
+            memcpy(nv, pv, pn * sizeof(VALUE));
+            if (pv != pairs) { free(pv); heap_cap = 1; }
+            pv = nv; pcap = ncap;
+        }
+        pv[pn++] = key;
+        pv[pn++] = val;
+        jr_ws(j);
+        if (j->i >= j->len) { j->err = -2; goto out; }
+        if (j->p[j->i] == ',') { j->i++; continue; }
+        if (j->p[j->i] == '}') { j->i++; break; }
+        j->err = -2; goto out;
+    }
+    rb_hash_bulk_insert((long)pn, (const VALUE*)pv, h);
+out:
+    if (pv != pairs) { free(pv); (void)heap_cap; }
+    if (j->err) return Qnil;
+    j->depth--;
+    return h;
+}
+
+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/json.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Yeptris
+  # The STRICT JSON surface (TODO.restructure/31).
+  #
+  # `Yeptris::JSON.load` targets EXACT `JSON.parse` semantics — that
+  # is its parity target, spec-pinned (spec/json_parity_spec.rb).
+  # It is deliberately separate from Yeptris::YAML: the YAML surface
+  # keeps the Psych contract for every input (JSON-shaped included),
+  # so the two never drift into each other's semantics.
+  #
+  # Engines, fastest first (both exact — the parity spec runs against
+  # whichever is loaded):
+  # 1. the native materializer (fused C scan → VALUE; opt-in build)
+  # 2. the record drain + strict conversion walk (always available)
+  module JSON
+    class Error < ::Yeptris::Error; end
+    class ParseError < Error; end
+
+    module_function
+
+    def load(source)
+      source = ::Yeptris.read_input(source)
+      source = source.to_s
+      if defined?(::Yeptris::Native)
+        begin
+          return ::Yeptris::Native.load_json(source)
+        rescue ::Yeptris::ParseError => e
+          raise ParseError, e.message
+        end
+      end
+      strict_fallback(source)
+    end
+
+    # The always-available engine: the strict-JSON validator gates
+    # (parse_json raises on anything RFC 8259 rejects), then the
+    # value records convert WITHOUT the Psych quirk table — floats
+    # are always Floats, bools always bools ("1e3" is 1000.0 here
+    # and a String on the YAML surface; each surface is its own
+    # contract).
+    def strict_fallback(source)
+      begin
+        gate = ::Yeptris::Document.parse_json(source)
+      rescue ::Yeptris::ParseError => e
+        raise ParseError, e.message
+      end
+      begin
+        cols = ::Yeptris::FFI::ValueColumns.new
+        st = ::Yeptris::FFI.yeptris_value_drain_columns(
+          source, source.bytesize, ::Yeptris::FFI::SCHEMA_12_CORE, cols
+        )
+        raise ParseError, ::Yeptris::FFI.last_error_message if st != ::Yeptris::FFI::OK
+
+        begin
+          walk_strict(cols)
+        ensure
+          ::Yeptris::FFI.yeptris_value_free_columns(cols)
+        end
+      ensure
+        gate.free
+      end
+    end
+
+    # Placement mechanics mirror ValueML.walk_columns; the CONVERSION
+    # is the strict-JSON one (no ':sym' scan, no y/n quirk, no
+    # dot-required floats). Anchors/aliases/timestamps cannot occur
+    # in strict JSON — reaching them is an internal error.
+    def walk_strict(cols)
+      n = cols[:count]
+      kinds = cols[:kinds].read_bytes(n).unpack("C*")
+      ikeys = cols[:is_keys].read_bytes(n).unpack("C*")
+      bools = cols[:bools].read_bytes(n).unpack("C*")
+      offs = cols[:offs].read_bytes(n * 4).unpack("V*")
+      lens = cols[:lens].read_bytes(n * 4).unpack("V*")
+      pays = cols[:payloads].read_bytes(n * 8).unpack("q<*")
+      arena = cols[:arena_len].zero? ? +"" : cols[:arena].read_bytes(cols[:arena_len])
+      arena.force_encoding(Encoding::UTF_8)
+
+      docs = []
+      stack = []
+      pending_key = nil
+      i = 0
+      while i < n
+        case kinds[i]
+        when ValueML::DOC
+          docs.push(nil)
+        when ValueML::SEQ_OPEN
+          place(docs, stack, pending_key) { [] }
+          pending_key = nil
+        when ValueML::MAP_OPEN
+          place(docs, stack, pending_key) { {} }
+          pending_key = nil
+        when ValueML::CLOSE
+          stack.pop
+        when ValueML::V_STR
+          text = arena.byteslice(offs[i], lens[i])
+          if ikeys[i] == 1 && !stack.empty? && stack.last.is_a?(Hash)
+            pending_key = text
+          else
+            # Records carry int64 payloads: an integer-beyond-int64
+            # degrades to a PLAIN string (b==1). In strict JSON a
+            # plain (unquoted) scalar can ONLY be a number — every
+            # real string is quoted and arrives b==0 — so rebuild the
+            # exact Integer (JSON.parse parity, Bignum included).
+            if bools[i] == 1
+              place(docs, stack, pending_key) { Integer(text, 10) }
+            else
+              place(docs, stack, pending_key) { text }
+            end
+            pending_key = nil
+          end
+        when ValueML::V_INT
+          place(docs, stack, pending_key) { pays[i] }
+          pending_key = nil
+        when ValueML::V_FLOAT
+          place(docs, stack, pending_key) { [pays[i]].pack("q<").unpack1("E") }
+          pending_key = nil
+        when ValueML::V_BOOL
+          place(docs, stack, pending_key) { bools[i] == 1 }
+          pending_key = nil
+        when ValueML::V_NULL
+          place(docs, stack, pending_key) { nil }
+          pending_key = nil
+        else
+          raise Error, "internal: impossible record #{kinds[i]} in strict JSON"
+        end
+        i += 1
+      end
+      docs.empty? ? nil : docs.first
+    end
+
+    def place(docs, stack, key)
+      v = yield
+      if stack.empty?
+        docs[-1] = v
+      elsif key
+        stack.last[key] = v
+      else
+        stack.last.push(v)
+      end
+      stack.push(v) if v.is_a?(Array) || v.is_a?(Hash)
+      v
+    end
+  end
+end

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

@@ -10,13 +10,22 @@ module Yeptris
     # Loads the FIRST document of a YAML stream as native Ruby objects.
     # schema: :compat_11 selects Psych/libyaml implicit typing
     # (yes/no, 0o/octal, sexagesimal); :core_12 (default) is YAML 1.2.
+    #
+    # This surface keeps the Psych contract for EVERY input — including
+    # JSON-shaped ones (`{"a": [1,]}` is legal flow YAML; `"1e3"` is a
+    # Psych String). Strict RFC 8259 semantics live on Yeptris::JSON
+    # (TODO.restructure/31): defaults follow proof, not benchmarks.
     def load(yaml, schema: :compat_11)
+      yaml = Yeptris.read_input(yaml)
+      yaml = yaml.to_s
       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
 

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.13.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
@@ -39,6 +39,7 @@ module Yeptris
   autoload :Document, "yeptris/document"
   autoload :Node, "yeptris/node"
   autoload :YAML, "yeptris/yaml"
+  autoload :JSON, "yeptris/json"
   autoload :Materializer, "yeptris/materializer"
   autoload :ValueML, "yeptris/valueml"
   autoload :Psych, "yeptris/psych"
@@ -58,3 +59,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.13.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,13 +34,18 @@ 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
+- lib/yeptris/json.rb
 - lib/yeptris/materializer.rb
 - 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