yeptris 0.6.58.1-arm-linux-eabihf → 0.6.60.1-arm-linux-eabihf

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23d3c8dc0b4600de5a60826f71cf3ffb2d7517c8a6e0c8f588aee724320782e3
-  data.tar.gz: '067915418bf97cccf16cc015e4b78959d45270ff97c8d0372b988b9b3bab1b7c'
+  metadata.gz: 0e078deaa97a27d09dc305c57e5d879ec727b506c0edfd6c1ef27a3fa7bb8d98
+  data.tar.gz: 9d3a325cba29a0c5c51f33be9c99ccca3ce4febdb46dd4595d2e7d3dbb73988e
 SHA512:
-  metadata.gz: 47511ed558cbf416de324e79679163e1dabcaecdbe009317c240015c6d063ddb3d212b215af60f8181d0e08c1d863f94ff4b5531362edc95c07f80bb1059f7d0
-  data.tar.gz: afc2c53b583f6637902bdeb8e8d506309be3beb412af4d7f664a462332360ec50cb9340bea3909601776ab72a5b6e8aeebfd1ffe1bb22568cc13ccb145e0be96
+  metadata.gz: fa97a7e1b0332bcd8106b1c244d5a1b11641ff28c5be0fba465a84095cfc120a87e469a23e32acd7e19c6f1dbddabb2ce0c6b7eb372e3848a0866140d0771670
+  data.tar.gz: a54e2f72f58ef07db3ef50755aa03bfbc41381770f252387bc331e7c71ead5818bb8b352197960336f69056ebe04e25a3dc272ee43032645facddd7658239a30

data/ext/yeptris_native/version.h

@@ -11,8 +11,8 @@
 
 #define YEPTRIS_VERSION_MAJOR 0
 #define YEPTRIS_VERSION_MINOR 6
-#define YEPTRIS_VERSION_PATCH 58
-#define YEPTRIS_VERSION_STRING "0.6.58"
+#define YEPTRIS_VERSION_PATCH 60
+#define YEPTRIS_VERSION_STRING "0.6.60"
 
 #ifdef __cplusplus
 extern "C" {

data/lib/yeptris/document.rb

@@ -238,6 +238,21 @@ class Yeptris::Document
     r.nil? ? nil : r.to_ruby
   end
 
+  # The schema-family validation walk (validate.h, #882) over this
+  # document — or over every document of the stream it holds (the
+  # engine's report is flat across the stream; paths are root-relative
+  # per document). schema: :core_12 or :json_12 (the validation
+  # families; :compat_11 is a resolve schema, not a validation
+  # family). Returns plain Yeptris::Validation::Diagnostic values
+  # (empty = valid).
+  def validate(schema: :core_12)
+    ensure_alive!
+    report = ::FFI::MemoryPointer.new(:pointer)
+    v = ::Yeptris::Validation
+    st = Yeptris::FFI.yeptris_validate_document(@c_ptr, v.schema_id(schema), report)
+    v.consume_report(st, report, "validate document")
+  end
+
   # ---- construction conveniences (TODO.impl/11 phase 3) ----
 
   def new_mapping

data/lib/yeptris/ffi.rb

@@ -56,6 +56,7 @@ module Yeptris
 
 
     typedef :pointer, :yeptris_document
+    typedef :pointer, :yeptris_stream_iter
     typedef :pointer, :yeptris_node
     typedef :pointer, :yeptris_status_out
     typedef :int, :yeptris_status
@@ -87,6 +88,24 @@ module Yeptris
                     %i[pointer size_t pointer yeptris_status_out], :yeptris_document
     attach_function :yeptris_parse_json, %i[pointer size_t yeptris_status_out], :yeptris_document
 
+    # The tolerant per-document stream iterator (engine #921): frames
+    # documents scanner-accurately, reports failures per document (the
+    # failed run's line/col ARE that document's own), resyncs to the
+    # next line-start marker. On an engine older than the iterator the
+    # attach stubs above raise the stale-engine message at USE
+    # (each_document's caller sees it directly — no separate gate
+    # constant, the @missing law covers it).
+    attach_function :yeptris_stream_iter_new, %i[pointer size_t pointer], :yeptris_stream_iter
+    attach_function :yeptris_stream_iter_next,
+                    %i[yeptris_stream_iter pointer pointer], :yeptris_status
+    attach_function :yeptris_stream_iter_status,
+                    %i[yeptris_stream_iter pointer pointer], :yeptris_status
+    attach_function :yeptris_stream_iter_free, [:yeptris_stream_iter], :void
+    # the capability probe (evaluated AFTER the attaches above — the
+    # CBOR.available? pattern): specs and hosts gate on it; at USE a
+    # stale engine still raises the stub's message
+    STREAM_ITER = !(@missing ||= []).include?(:yeptris_stream_iter_new)
+
     # The JSON tape (TODO.restructure/85; the JSON surface's load
     # engine — issue #81): ONE call, three bulk columns, spans borrow
     # the caller's string (no arena copy, no second validating parse).
@@ -427,6 +446,9 @@ module Yeptris
 
     SCHEMA_12_CORE = 0
     SCHEMA_11_COMPAT = 1
+    # resolve.h's third kind (spec 10.2): plain scalars must match a
+    # JSON production; the validate face's schema-family walk rides it.
+    SCHEMA_12_JSON = 2
 
     OK = 0
     ERROR_PARSE = 1
@@ -437,6 +459,96 @@ module Yeptris
     ERROR_ARG = 6
     ERROR_UNSUPPORTED = 7
     ERROR_INTERNAL = 8
+
+    # ---- the validation face (validate.h; #882, engine 0.6.59+) ----
+    # Whole reports: one call produces a report the caller drains
+    # (count/at) and frees once. SCHEMA_ERROR (9, defined above) means
+    # the walk completed and the instance is INVALID — drain the
+    # report. Absent on older libraries: the attachment helper records
+    # the miss and VALIDATION gates the Ruby face with the friendly
+    # error at use.
+
+    typedef :pointer, :yeptris_schema
+    typedef :pointer, :yeptris_validate_report
+
+    # yeptris_diagnostic (validate.h): ABI-frozen — four uint32 facts
+    # then two bounded NUL-terminated texts. 16 + 256 + 128 bytes.
+    class CDiagnostic < ::FFI::Struct
+      layout :code, :uint32,
+             :line, :uint32,
+             :col, :uint32,
+             :offset, :uint32,
+             :path, [:char, 256],
+             :detail, [:char, 128]
+    end
+
+    # The schema-family walk: parse + validate fused (tag consistency,
+    # canonical-form key uniqueness; the JSON family's string-key +
+    # JSON-production rules under SCHEMA_12_JSON).
+    attach_function :yeptris_validate, %i[pointer size_t int pointer], :int
+    # An already-parsed document (or stream) against the family walk.
+    attach_function :yeptris_validate_document, %i[yeptris_document int pointer], :int
+    # JSON Schema draft 2020-12 subset, one-shot (schema bytes parsed
+    # per call).
+    attach_function :yeptris_json_schema_validate,
+                    %i[pointer size_t pointer size_t pointer], :int
+    # The compiled-schema economy (#885 item 3): parse once, validate
+    # many. NULL from compile = failure (yeptris_last_error carries why).
+    attach_function :yeptris_schema_compile, %i[pointer size_t], :yeptris_schema
+    attach_function :yeptris_schema_validate,
+                    %i[yeptris_schema pointer size_t pointer], :int
+    attach_function :yeptris_schema_free, [:yeptris_schema], :void
+    attach_function :yeptris_validate_report_count,
+                    [:yeptris_validate_report], :size_t
+    attach_function :yeptris_validate_report_at,
+                    %i[yeptris_validate_report size_t], :pointer
+    attach_function :yeptris_validate_report_free,
+                    [:yeptris_validate_report], :void
+
+    # The diag codes (validate.h's YeptrisDiagCode, appending-only;
+    # pinned values — the engine's test_abi pins the head).
+    DIAG_NONE = 0
+    DIAG_TAG_MISMATCH = 1
+    DIAG_KEY_NOT_STRING = 2
+    DIAG_NON_JSON_TYPE = 3
+    DIAG_DUPLICATE_KEY = 4
+    DIAG_TYPE = 5
+    DIAG_REQUIRED = 6
+    DIAG_ENUM = 7
+    DIAG_CONST = 8
+    DIAG_PATTERN = 9
+    DIAG_MINIMUM = 10
+    DIAG_MAXIMUM = 11
+    DIAG_EXCLUSIVE_MINIMUM = 12
+    DIAG_EXCLUSIVE_MAXIMUM = 13
+    DIAG_MIN_LENGTH = 14
+    DIAG_MAX_LENGTH = 15
+    DIAG_MIN_ITEMS = 16
+    DIAG_MAX_ITEMS = 17
+    DIAG_UNIQUE_ITEMS = 18
+    DIAG_ADDITIONAL_PROPERTY = 19
+    DIAG_ANY_OF = 20
+    DIAG_ONE_OF = 21
+    DIAG_NOT = 22
+    DIAG_REF = 23
+    DIAG_FALSE_SCHEMA = 24
+    DIAG_DEPTH = 25
+    DIAG_LIMIT = 26
+    DIAG_MULTIPLE_OF = 27
+    DIAG_MIN_PROPERTIES = 28
+    DIAG_MAX_PROPERTIES = 29
+    DIAG_CONTAINS = 30
+    DIAG_MIN_CONTAINS = 31
+    DIAG_MAX_CONTAINS = 32
+    DIAG_DEPENDENT_REQUIRED = 33
+
+    # The face's availability (engine 0.6.59+); the Validation module
+    # raises the friendly error at use when the loaded library predates
+    # the attachments (the stubs above would raise NotFoundError raw).
+    VALIDATION = !(@missing ||= []).include?(:yeptris_validate) &&
+                 !(@missing ||= []).include?(:yeptris_schema_compile) &&
+                 !(@missing ||= []).include?(:yeptris_validate_report_at)
+
     # The load-time essentials (the read path + the ownership
     # contract): absent on engines far older than the optional
     # surfaces — raise the friendly error once every constant has

data/lib/yeptris/psych/visitors.rb

@@ -13,12 +13,17 @@ module Yeptris
       # !ruby/... tags Psych's own emitter produces.
       class YAMLTree
         # stdlib's factory (relaton's db cache calls it): the options
-        # ride our visitor defaults
+        # reach the engine's emitter — :line_width and :canonical ride
+        # yeptris_emit_options (13B), :indentation is accepted for
+        # Psych parity (the engine's YAML emitter carries no
+        # indentation knob; emit.h's struct is size/canonical/
+        # best_width/explicit_doc_start).
         def self.create(options = {}, emitter = nil)
-          new
+          new(options: options)
         end
 
-        def initialize(schema: nil)
+        def initialize(schema: nil, options: {})
+          @options = options || {}
           @tree = ::Yeptris::Document.create(schema: schema)
           @names = {}  # object_id -> anchor name
           @counter = 0
@@ -48,7 +53,9 @@ module Yeptris
         end
 
         def finish
-          @tree.serialize(explicit_doc_start: true)
+          @tree.serialize(canonical: @options[:canonical] ? true : false,
+                          best_width: @options[:line_width] || 0,
+                          explicit_doc_start: true)
         end
 
         # The built-document handle stdlib's dump tail serializes
@@ -57,8 +64,11 @@ module Yeptris
             @doc = doc
           end
 
-          def yaml(io = nil, _options = {})
-            out = @doc.serialize(explicit_doc_start: true)
+          def yaml(io = nil, options = {})
+            options ||= {}
+            out = @doc.serialize(canonical: options[:canonical] ? true : false,
+                                 best_width: options[:line_width] || 0,
+                                 explicit_doc_start: true)
             return out unless io
 
             io.write(out)

data/lib/yeptris/psych.rb

@@ -424,11 +424,16 @@ module Yeptris
 
       # Arbitrary object graphs through the YAMLTree visitor
       # (anchors, !ruby/ tags); plain data rides the fast builder.
+      # options reach the engine's emitter: :line_width folds flow
+      # collections past the width (the engine default is 80),
+      # :canonical switches the fixed form; :indentation is accepted
+      # for Psych parity (the engine's YAML emitter has no indentation
+      # knob). The audit round-2 finding — width accepted and
+      # discarded — is closed here and in YAMLTree.create.
       def dump(obj, io = nil, options = {})
         # stdlib's Object#to_yaml calls Psych.dump(self, options) —
         # the options hash lands in the io slot positionally; treat a
-        # Hash there as options (the options themselves ride the
-        # visitor's defaults, #95 thread)
+        # Hash there as options
         if io.is_a?(::Hash)
           options = io
           io = nil
@@ -443,11 +448,12 @@ module Yeptris
           # path would emit it tag-less iso8601 (re-loading as Time);
           # the visitor carries stdlib's !ruby/object:DateTime tag
           when ::DateTime
-            Visitors::YAMLTree.new.push(obj).finish
+            Visitors::YAMLTree.new(options: options).push(obj).finish
           when nil, true, false, ::String, ::Integer, ::Float, ::Symbol, ::Date, ::Time
-            Yeptris::YAML.dump(obj, header: true)
+            Yeptris::YAML.dump(obj, header: true, width: options[:line_width],
+                                     canonical: options[:canonical] ? true : false)
           else
-            Visitors::YAMLTree.new.push(obj).finish
+            Visitors::YAMLTree.new(options: options).push(obj).finish
           end
         return out unless io
 

data/lib/yeptris/validation.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module Yeptris
+  # The validation face (engine validate.h; issue #882, binding
+  # TODO item 6). Two checks over one engine pass:
+  #
+  #   * the SCHEMA-FAMILY walk (`validate` with a schema symbol) —
+  #     explicit-tag consistency, mapping-key uniqueness by canonical
+  #     form, and (under :json_12) the spec 10.2 JSON-production rules;
+  #   * JSON SCHEMA draft 2020-12 (`validate` with `json_schema:`) —
+  #     one-shot over schema bytes, or against a compiled
+  #     {Yeptris::Validation::Schema} handle (parse once, validate
+  #     many; #885 item 3).
+  #
+  # Diagnostics cross the FFI boundary once, as plain Ruby values
+  # ({Diagnostic}): no C pointer ever leaks out of this module.
+  module Validation
+    # Raised for an instance that carries diagnostics. The full report
+    # rides `diagnostics` (plain {Diagnostic} values, never pointers).
+    class Error < ::Yeptris::Error
+      attr_reader :diagnostics
+
+      def initialize(diagnostics)
+        @diagnostics = diagnostics
+        first = diagnostics.first
+        detail = first ? "#{first.keyword} at #{first.path}: #{first.detail}" : "no diagnostics"
+        super("validation failed (#{diagnostics.size} diagnostics): #{detail}")
+      end
+    end
+
+    # The code -> keyword table (validate.h's YeptrisDiagCode). The
+    # 2020-12 walk's codes name their JSON Schema keyword; the
+    # schema-family walk's codes name the violated YAML rule.
+    KEYWORD = {
+      FFI::DIAG_NONE => "none",
+      FFI::DIAG_TAG_MISMATCH => "tag-mismatch",
+      FFI::DIAG_KEY_NOT_STRING => "key-not-string",
+      FFI::DIAG_NON_JSON_TYPE => "non-json-type",
+      FFI::DIAG_DUPLICATE_KEY => "duplicate-key",
+      FFI::DIAG_TYPE => "type",
+      FFI::DIAG_REQUIRED => "required",
+      FFI::DIAG_ENUM => "enum",
+      FFI::DIAG_CONST => "const",
+      FFI::DIAG_PATTERN => "pattern",
+      FFI::DIAG_MINIMUM => "minimum",
+      FFI::DIAG_MAXIMUM => "maximum",
+      FFI::DIAG_EXCLUSIVE_MINIMUM => "exclusiveMinimum",
+      FFI::DIAG_EXCLUSIVE_MAXIMUM => "exclusiveMaximum",
+      FFI::DIAG_MIN_LENGTH => "minLength",
+      FFI::DIAG_MAX_LENGTH => "maxLength",
+      FFI::DIAG_MIN_ITEMS => "minItems",
+      FFI::DIAG_MAX_ITEMS => "maxItems",
+      FFI::DIAG_UNIQUE_ITEMS => "uniqueItems",
+      FFI::DIAG_ADDITIONAL_PROPERTY => "additionalProperties",
+      FFI::DIAG_ANY_OF => "anyOf",
+      FFI::DIAG_ONE_OF => "oneOf",
+      FFI::DIAG_NOT => "not",
+      FFI::DIAG_REF => "$ref",
+      FFI::DIAG_FALSE_SCHEMA => "false",
+      FFI::DIAG_DEPTH => "depth",
+      FFI::DIAG_LIMIT => "limit",
+      FFI::DIAG_MULTIPLE_OF => "multipleOf",
+      FFI::DIAG_MIN_PROPERTIES => "minProperties",
+      FFI::DIAG_MAX_PROPERTIES => "maxProperties",
+      FFI::DIAG_CONTAINS => "contains",
+      FFI::DIAG_MIN_CONTAINS => "minContains",
+      FFI::DIAG_MAX_CONTAINS => "maxContains",
+      FFI::DIAG_DEPENDENT_REQUIRED => "dependentRequired",
+    }.freeze
+
+    # One structured diagnostic: the engine's yeptris_diagnostic read
+    # into plain Ruby at drain time (a value class — ==, eql?, hash —
+    # never an FFI wrapper).
+    class Diagnostic
+      attr_reader :code, :path, :detail, :line, :col, :offset
+
+      def initialize(code:, path:, detail:, line: 0, col: 0, offset: 0)
+        @code = code
+        @path = path
+        @detail = detail
+        @line = line
+        @col = col
+        @offset = offset
+      end
+
+      # The violated keyword ("type", "minimum", "duplicate-key", ...).
+      def keyword
+        KEYWORD.fetch(code, "unknown-#{code}")
+      end
+
+      # The JSON-pointer instance path ("/a/b/0", ~0/~1 escaped) split
+      # into its unescaped segments; the root is [].
+      def path_array
+        return [] if path.empty?
+
+        path.split("/")[1..].map { |s| s.gsub("~1", "/").gsub("~0", "~") }
+      end
+
+      # The engine's bounded explanation ("3 is less than the minimum 10").
+      def message
+        detail
+      end
+
+      alias to_s message
+
+      def ==(other)
+        other.is_a?(Diagnostic) && code == other.code && path == other.path &&
+          detail == other.detail && line == other.line && col == other.col &&
+          offset == other.offset
+      end
+      alias eql? ==
+
+      def hash
+        [code, path, detail, line, col, offset].hash
+      end
+
+      def to_h
+        { code: code, keyword: keyword, path: path, path_array: path_array,
+          detail: detail, message: message, line: line, col: col, offset: offset }
+      end
+
+      def inspect
+        "#<#{self.class.name} #{keyword} path=#{path.inspect} line=#{line} " \
+          "col=#{col} detail=#{detail.inspect}>"
+      end
+    end
+
+    # The compiled schema (yeptris_schema_compile): the schema bytes,
+    # its DOM, and the pattern kernel's programs retained behind one
+    # opaque handle — parse ONCE, validate many streams against it.
+    # Ownership mirrors Yeptris::Document: an explicit #free and a GC
+    # finalizer flip the same freed flag (the pointer-only finalizer —
+    # it captures the raw address, never the wrapper, so no
+    # use-after-free race).
+    class Schema
+      # Shared between the instance and its finalizer (the
+      # leptris-ruby double-free fix).
+      Freed = Struct.new(:state) # :alive | :freed
+
+      attr_reader :c_ptr
+
+      # Compiles JSON Schema bytes (JSON is YAML flow — a YAML-shaped
+      # mapping schema compiles too). Raises ArgumentError for empty
+      # bytes (the engine's "hold no document") and ParseError for
+      # bytes that do not parse.
+      def self.compile(bytes)
+        raise ::ArgumentError, "schema bytes are required" if bytes.nil?
+        bytes = ::Yeptris.read_input(bytes).to_s
+        raise ::ArgumentError, "schema bytes hold no document" if bytes.empty?
+
+        ptr = FFI.yeptris_schema_compile(bytes, bytes.bytesize)
+        raise ::Yeptris::ParseError,
+              "schema compile failed: #{FFI.last_error_message}" if ptr.null?
+
+        new(ptr)
+      end
+
+      # Block form: the handle frees when the block exits (valid or not).
+      def self.open(bytes)
+        schema = compile(bytes)
+        begin
+          yield schema
+        ensure
+          schema.free
+        end
+      end
+
+      # @api private — produced by .compile; a raw pointer argument is
+      # not a caller surface (the same contract as Document).
+      def initialize(c_ptr)
+        unless c_ptr.is_a?(::FFI::Pointer)
+          raise ArgumentError,
+                "a schema FFI pointer is required — build schemas with " \
+                "Yeptris::Validation::Schema.compile"
+        end
+
+        @c_ptr = c_ptr
+        @freed = Freed.new(:alive)
+        ObjectSpace.define_finalizer(self, self.class.finalize(c_ptr)) unless c_ptr.null?
+      end
+
+      # Validates one instance stream against the retained model.
+      # Returns the diagnostics array (empty = valid).
+      def validate(bytes)
+        ensure_alive!
+        bytes = ::Yeptris.read_input(bytes).to_s
+        report = ::FFI::MemoryPointer.new(:pointer)
+        st = FFI.yeptris_schema_validate(@c_ptr, bytes, bytes.bytesize, report)
+        Validation.consume_report(st, report, "schema validate")
+      end
+
+      def valid?(bytes)
+        validate(bytes).empty?
+      end
+
+      def ensure_alive!
+        raise ::Yeptris::FreedError, "schema is freed" if @freed.state == :freed
+      end
+
+      def free
+        return if @freed.state == :freed
+
+        @freed.state = :freed
+        ObjectSpace.undefine_finalizer(self)
+        FFI.yeptris_schema_free(@c_ptr)
+      end
+
+      def freed?
+        @freed.state == :freed
+      end
+
+      # Pointer-only finalizer (Document's law): no Ruby objects, no
+      # wrapper — a finalizer closing over the wrapper races its sweep.
+      def self.finalize(c_ptr)
+        proc { FFI.yeptris_schema_free(c_ptr) }
+      end
+    end
+
+    class << self
+      # The schema-family walk over the engine's own front door
+      # (encodings, BOM, every document of the stream). schema: one of
+      # :core_12, :compat_11, :json_12. Returns the diagnostics array.
+      def validate_family(bytes, schema: :core_12)
+        require_engine!
+        bytes = ::Yeptris.read_input(bytes).to_s
+        report = ::FFI::MemoryPointer.new(:pointer)
+        st = FFI.yeptris_validate(bytes, bytes.bytesize, schema_id(schema), report)
+        consume_report(st, report, "validate")
+      end
+
+      # JSON Schema validation: `schema` is a compiled
+      # {Yeptris::Validation::Schema} (validate many) or schema bytes
+      # (one-shot). Returns the diagnostics array.
+      def validate_schema(bytes, schema)
+        require_engine!
+        case schema
+        when Schema then schema.validate(bytes)
+        when String then one_shot(bytes, schema)
+        else
+          raise ::ArgumentError,
+                "json_schema: must be a Yeptris::Validation::Schema or schema " \
+                "bytes (got #{schema.class})"
+        end
+      end
+
+      # The engine's whole-report drain shared by every face: maps the
+      # status, drains the diagnostics into plain values, frees the
+      # report — exactly once, on every path.
+      def consume_report(status, report, action)
+        ptr = report.read_pointer
+        diags = drain_report(ptr)
+        return diags if status == FFI::OK || status == FFI::SCHEMA_ERROR
+
+        raise ::ArgumentError, "#{action}: #{FFI.last_error_message}" if status == FFI::ERROR_ARG
+
+        raise ::Yeptris::ParseError, "#{action} failed: #{FFI.last_error_message}"
+      ensure
+        FFI.yeptris_validate_report_free(ptr) unless ptr.null?
+      end
+
+      # The schema symbol -> YeptrisSchema id (resolve.h's enum) for
+      # the VALIDATION family walks: only the YAML 1.2 families are
+      # validation families — the engine rejects :compat_11 with
+      # "schema 1 is not a validation family", surfaced here as the
+      # same ArgumentError the other bad symbols take.
+      def schema_id(name)
+        case name
+        when :core_12 then FFI::SCHEMA_12_CORE
+        when :json_12 then FFI::SCHEMA_12_JSON
+        when :compat_11
+          raise ::ArgumentError,
+                "schema: :compat_11 is not a validation family — the walk " \
+                "covers the YAML 1.2 families (:core_12, :json_12)"
+        else
+          raise ::ArgumentError,
+                "schema: must be :core_12, :compat_11, or :json_12 (got #{name.inspect})"
+        end
+      end
+
+      private
+
+      def one_shot(bytes, schema_bytes)
+        bytes = ::Yeptris.read_input(bytes).to_s
+        schema_bytes = schema_bytes.to_s
+        report = ::FFI::MemoryPointer.new(:pointer)
+        st = FFI.yeptris_json_schema_validate(schema_bytes, schema_bytes.bytesize,
+                                              bytes, bytes.bytesize, report)
+        consume_report(st, report, "json schema validate")
+      end
+
+      # drain before free: the diagnostics are read into plain Ruby
+      # while the report is still alive. The texts re-tag UTF-8 (the
+      # binding's string discipline — #135: engine materializations
+      # ride UTF-8, not the raw BINARY read).
+      def drain_report(report)
+        return [] if report.null?
+
+        FFI.yeptris_validate_report_count(report).times.map do |i|
+          d = FFI::CDiagnostic.new(FFI.yeptris_validate_report_at(report, i))
+          Diagnostic.new(
+            code: d[:code],
+            path: d.pointer.get_string(FFI::CDiagnostic.offset_of(:path))
+                     .force_encoding(::Encoding::UTF_8),
+            detail: d.pointer.get_string(FFI::CDiagnostic.offset_of(:detail))
+                      .force_encoding(::Encoding::UTF_8),
+            line: d[:line], col: d[:col], offset: d[:offset]
+          )
+        end
+      end
+
+      def require_engine!
+        return if FFI::VALIDATION
+
+        raise ::Yeptris::Error,
+              "yeptris: the validation face needs libyeptris 0.6.59+; the " \
+              "loaded library predates it. Update the engine library."
+      end
+    end
+  end
+end