yeptris 0.6.57.1 → 0.6.59.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ca19dc06edfa2c51b8d193845713970526fb9c933a9d4ff438b4536e6847ff8
-  data.tar.gz: 2d32ef5b5b0702e0d24accf88ddad7ec35dc922e33277037332d675b6c3316d7
+  metadata.gz: 5f9da8cd9b7db4c514ad70beefc657e82c11464804ef6c6e9a451462c7d4831c
+  data.tar.gz: 6f94ccb3a3499f4c71dc24c00231309e6da9cef893d8bdcea60da2d7b2dce456
 SHA512:
-  metadata.gz: 79953b07f1bce4b68ca9d8a7124cbc11313ddb56f067291f9a8f3979f8cb9aee59c3af0370f076474d8abe64253e1c757fa04df8c8b7d236fec41e7c97cc3e7e
-  data.tar.gz: 71668f985884d66d6828c50d854caf079f0f1c2dd40d7ecaf7fd5d49257b9f754f64d8d66296e3df6836d589e2b7ce36e9df36e2a17ce7b167c02d7e6c13d68b
+  metadata.gz: 7af7add33be58c2f972314fa3a235c83b455036ae74db7367a000a11ae13851d723955b770b63192aa68f54883f4fe5a15465c12547599afdb09d7c9231f5aef
+  data.tar.gz: feabebeaeb648b9810921337daf3466b85047b85f01072cad817277662bdfa5250fd40d4597b810abc769a5bf2ca1d5f299b1778130f5778bc85f2e2b2883964

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

@@ -427,6 +427,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 +440,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

data/lib/yeptris/yaml.rb

@@ -22,17 +22,64 @@ module Yeptris
     # schema: :compat_11 selects Psych/libyaml implicit typing
     # (yes/no, 0o/octal, sexagesimal); :core_12 (default) is YAML 1.2.
     #
+    # The validation keywords (#882) check BEFORE loading and raise
+    # Yeptris::Validation::Error carrying the diagnostics on invalid
+    # input: `validate:` rides the engine's schema-family walk (true
+    # rides :core_12 — the 1.2 families are the validation families;
+    # or an explicit :core_12 / :json_12), `json_schema:` validates
+    # against JSON Schema draft 2020-12 (schema bytes or a compiled
+    # Yeptris::Validation::Schema).
+    #
     # 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)
+    def load(yaml, schema: :compat_11, validate: nil, json_schema: nil)
       yaml = Yeptris.read_input(yaml)
       yaml = yaml.to_s
+      _assert_valid(yaml, validate, json_schema) if validate || json_schema
       docs = _drain_all(yaml, schema)
       docs.empty? ? nil : docs.first
     end
 
+    # The validation face (#882): every diagnostic the engine reports,
+    # as plain Yeptris::Validation::Diagnostic values (empty array =
+    # valid). Default is the engine's core-family walk; `json_schema:`
+    # switches to JSON Schema draft 2020-12 (bytes or a compiled
+    # Yeptris::Validation::Schema), `validate:` picks the schema family
+    # explicitly (:core_12 / :json_12). Every document of the stream is
+    # validated; paths are root-relative per document.
+    def validate(yaml, validate: true, json_schema: nil)
+      yaml = Yeptris.read_input(yaml)
+      _validation_call(yaml.to_s, validate, json_schema)
+    end
+
+    # The boolean posture of validate: true when the engine reports no
+    # diagnostics.
+    def valid?(yaml, validate: true, json_schema: nil)
+      validate(yaml, validate: validate, json_schema: json_schema).empty?
+    end
+
+    # The load-side gate: raises Yeptris::Validation::Error carrying
+    # the diagnostics when the input is invalid; silent otherwise.
+    def _assert_valid(yaml, validate, json_schema)
+      diags = _validation_call(yaml, validate, json_schema)
+      raise Validation::Error, diags unless diags.empty?
+    end
+
+    def _validation_call(yaml, validate, json_schema)
+      if json_schema
+        Validation.validate_schema(yaml, json_schema)
+      else
+        # `validate: true` rides :core_12 — the family walk has no
+        # :compat_11 face (the engine rejects it; resolve schemas are
+        # not validation families).
+        Validation.validate_family(yaml, schema: validate == true ? :core_12 : validate)
+      end
+    end
+    private_class_method :_validation_call
+    private_class_method :_assert_valid
+
     # Psych-semantics safe_load on the native surface (issue #69 —
     # the entry frameworks actually want): plain data only; a leaf
     # whose class is not permitted raises Yeptris::Psych::
@@ -60,13 +107,23 @@ module Yeptris
     #
     # With a block, every element — documents and, under :collect,
     # error markers — is yielded in order; the array is returned.
-    def load_stream(yaml, schema: :compat_11, errors: :raise, &block)
+    #
+    # The validation keywords (#882) run the whole stream BEFORE
+    # loading (the same shapes as load: `validate:` family walk /
+    # `json_schema:` JSON Schema 2020-12) and raise
+    # Yeptris::Validation::Error on any diagnostics. The engine's
+    # report is flat across the stream — diagnostics carry no
+    # per-document index (streaming validation is future work, #885) —
+    # so the verdict is whole-stream by construction.
+    def load_stream(yaml, schema: :compat_11, errors: :raise, validate: nil,
+                    json_schema: nil, &block)
       unless %i[raise collect].include?(errors)
         raise ArgumentError, "errors: must be :raise or :collect (got #{errors.inspect})"
       end
 
       yaml = Yeptris.read_input(yaml)
       yaml = yaml.to_s
+      _assert_valid(yaml, validate, json_schema) if validate || json_schema
       docs =
         begin
           docs = _drain_all(yaml, schema)
@@ -176,8 +233,11 @@ module Yeptris
     # (TODO.impl/11 phase 3). Strings are emitted plain only when the
     # resolver round-trips them as strings — everything else takes a
     # quoted style, so dump(load(x)) == x for the scalar types.
-      def dump(obj, canonical: false, header: false)
-      BulkBuilder.dump(obj, canonical: canonical, header: header)
+    # width: the emitter's best_width (the engine wraps flow
+    # collections after a value when the line exceeds it; 0/nil rides
+    # the engine default of 80 — emit.h 13B).
+      def dump(obj, canonical: false, header: false, width: nil)
+      BulkBuilder.dump(obj, canonical: canonical, header: header, width: width)
     end
 
 
@@ -228,7 +288,7 @@ module Yeptris
                      Yeptris::FFI::BUILD_SEQ => SEQ_ENTRY,
                      Yeptris::FFI::BUILD_END => END_ENTRY }.freeze
 
-      def dump(obj, canonical: false, header: false)
+      def dump(obj, canonical: false, header: false, width: nil)
         parts = []
         blob = String.new(encoding: Encoding::BINARY)
         off = [0]
@@ -243,7 +303,8 @@ module Yeptris
         bblob = ::FFI::MemoryPointer.from_string(blob)
         rc = doc.build_entries(buf, parts.length, bblob, blob.bytesize)
         raise DumpError, "document_build failed: #{rc}" unless rc == FFI::OK
-        doc.serialize(canonical: canonical, explicit_doc_start: header)
+        doc.serialize(canonical: canonical, best_width: width || 0,
+                      explicit_doc_start: header)
       ensure
         doc&.free
       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.6.57.1".freeze
+  VERSION = "0.6.59.1".freeze
 
   # Informational notices are OPT-IN (yeptris-ruby#217): consumers
   # embed yeptris inside CLIs that assert clean stderr, and a
@@ -54,6 +54,7 @@ module Yeptris
   autoload :ValueML, "yeptris/valueml"
   autoload :Psych, "yeptris/psych"
   autoload :Schema, "yeptris/schema"
+  autoload :Validation, "yeptris/validation"
   autoload :CBOR, "yeptris/cbor"
 end