yeptris 0.6.59.1-aarch64-linux → 0.6.61.1-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9463f702df154adbe3e51d077e32a469047c525900e969a5ee0b73c2f7508f1
-  data.tar.gz: 2bc87ee70675681914603b2017f8dca8f7a0b7aee2beae468d268e7c5d731238
+  metadata.gz: bbbe4a9411210888a16c92e91b7d17d6e15f0ccb7ad48d8acdf174f867f51f45
+  data.tar.gz: dcbe1dae7f15b3541c5d2587e7914e50a4cd1575dc301cfd73aefbdb3f62882d
 SHA512:
-  metadata.gz: e520864ea28ebe73dc1abc5d0ce58f9c5026d3b378f47f1ea1824acc652b2f5dc44a2d9c5e1acf235d6dec5b5966b958635f82f32a3ffc72c76a15322de02841
-  data.tar.gz: d1373ff525f01732eb6664a3875c944e49ad4ced6d542aa2b8ae01b3db6056a9cd7d504eb3ddf32186dc0927f86900eba86414f3b2960c0a0f53a0ebf6a0cda3
+  metadata.gz: 52c8f1fb37c18fc9e0d31a7b8d4d0ddbb19d7c408077ca324e60ba6594c2f7dc3d56794421fb255b287c42a01a501e53cd01a6ee16806fe38504fced57c794e6
+  data.tar.gz: c09e79a2a68c4cac043801616accde5655ea10d9a7a278c91d10f3824e55e35ea29dad1c5736cedc019e7298ab27b1e0fc737a5c4eb679ca047e221dba2ad662

data/ext/yeptris_native/version.h

@@ -11,8 +11,8 @@
 
 #define YEPTRIS_VERSION_MAJOR 0
 #define YEPTRIS_VERSION_MINOR 6
-#define YEPTRIS_VERSION_PATCH 59
-#define YEPTRIS_VERSION_STRING "0.6.59"
+#define YEPTRIS_VERSION_PATCH 61
+#define YEPTRIS_VERSION_STRING "0.6.61"
 
 #ifdef __cplusplus
 extern "C" {

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).

data/lib/yeptris/yaml.rb

@@ -197,6 +197,67 @@ module Yeptris
       results
     end
 
+    # The engine capability behind each_document (the CBOR.available?
+    # pattern): false when the loaded libyeptris predates the stream
+    # iterator — the walk itself raises the stale-engine message at use.
+    def each_document?
+      FFI::STREAM_ITER
+    end
+
+    # The tolerant per-document walk (engine #921): every document of
+    # the stream reaches the block IN STREAM ORDER — a valid document
+    # yields (document, nil); a failed document yields (nil, error)
+    # and the walk CONTINUES at the next line-start marker, so the
+    # valid documents after a bad one are kept (load_stream with
+    # errors: :raise would drop the whole stream; :collect recovers by
+    # a regex slice split, which quoted scalars spanning marker-looking
+    # lines can defeat — the engine iterator frames scanner-accurately,
+    # so those documents fail as ONE unit instead of splitting).
+    # Errors carry the failed document's own line/column and its
+    # stream index. Without a block, an Enumerator over the pairs.
+    def each_document(yaml, schema: :compat_11, max_depth: 0, &block)
+      return enum_for(:each_document, yaml, schema: schema, max_depth: max_depth) unless block
+
+      yaml = Yeptris.read_input(yaml)
+      yaml = yaml.to_s
+      opts = FFI::ParseOptions.new
+      opts[:schema] = schema == :compat_11 ? FFI::SCHEMA_11_COMPAT : FFI::SCHEMA_12_CORE
+      opts[:max_depth] = max_depth
+      it = FFI.yeptris_stream_iter_new(yaml, yaml.bytesize, opts)
+      doc_p = ::FFI::MemoryPointer.new(:pointer)
+      idx_p = ::FFI::MemoryPointer.new(:size_t)
+      line_p = ::FFI::MemoryPointer.new(:uint32)
+      col_p = ::FFI::MemoryPointer.new(:uint32)
+      begin
+        loop do
+          st = FFI.yeptris_stream_iter_next(it, doc_p, idx_p)
+          doc_ptr = doc_p.read_pointer
+          break if st == FFI::OK && doc_ptr.null? # the stream is over
+
+          index = FFI.read_c_size_t(idx_p)
+          if st == FFI::OK
+            doc = Document.without_finalizer(doc_ptr)
+            begin
+              yield doc.to_ruby, nil
+            ensure
+              doc.free
+            end
+          else
+            FFI.yeptris_stream_iter_status(it, line_p, col_p)
+            reason = st == FFI::ERROR_DEPTH ? "depth limit exceeded" : "parse error"
+            yield nil,
+                  ParseError.new(
+                    "stream document #{index}: #{reason} at line #{line_p.read_uint32}, " \
+                    "column #{col_p.read_uint32}"
+                  )
+            break if st == FFI::ERROR_MEMORY || st == FFI::ERROR_ENCODING
+          end
+        end
+      ensure
+        FFI.yeptris_stream_iter_free(it)
+      end
+    end
+
     # The Marshal fast path when the loaded libyeptris has it (>= 0.1.11
     # era builds), falling back to the columnar drain and finally the
     # record drain — one code path, the fastest the library offers.
@@ -289,6 +350,16 @@ module Yeptris
                      Yeptris::FFI::BUILD_END => END_ENTRY }.freeze
 
       def dump(obj, canonical: false, header: false, width: nil)
+        # The nil root rides the bare form (psych's dump(nil) == "\n",
+        # #290): the engine's r201 quoted-form law ("a document-root
+        # empty scalar rides the quoted form" -- the plain form does not
+        # re-parse, the roundtrip invariant) renders the built empty
+        # scalar as "" -- correct for the engine's generic serializer,
+        # wrong for the psych surface. The binding maps an empty stream
+        # back to nil on load (load\#docs.empty?\#nil), so the bare form
+        # round-trips THROUGH THE BINDING while keeping the engine's
+        # invariant untouched.
+        return header ? "--- \n" : "\n" if obj.nil? && !canonical
         parts = []
         blob = String.new(encoding: Encoding::BINARY)
         off = [0]

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.59.1".freeze
+  VERSION = "0.6.61.1".freeze
 
   # Informational notices are OPT-IN (yeptris-ruby#217): consumers
   # embed yeptris inside CLIs that assert clean stderr, and a

data/vendor/libyeptris/CMakeLists.txt

@@ -3,7 +3,7 @@
 cmake_minimum_required(VERSION 3.20)
 
 project(yeptris
-    VERSION 0.6.59
+    VERSION 0.6.61
     DESCRIPTION "Ultra-fast YAML 1.2 parser, emitter and streamer in C"
     LANGUAGES C CXX
 )

data/vendor/libyeptris/src/CMakeLists.txt

@@ -29,6 +29,7 @@ set(YEPTRIS_SOURCES
     yeptris/dom/mapindex.c
     yeptris/dom/mutate.c
     yeptris/parse.c
+    yeptris/parse/stream_iter.c
     yeptris/build.c
     yeptris/events/capture.c
     yeptris/events/push.c
@@ -40,17 +41,23 @@ set(YEPTRIS_SOURCES
     yeptris/resolve/core12.c
     yeptris/resolve/compat11.c
     yeptris/resolve/json12.c
+    yeptris/resolve/full12.c
     yeptris/parse/numbers.c
     yeptris/events/values.c
     yeptris/schema.c
     yeptris/validate/regexp.c
     yeptris/validate/validate.c
     yeptris/validate/compile.c
+    yeptris/validate/resources.c
     yeptris/validate/jsonschema.c
+    yeptris/validate/registry.c
+    yeptris/validate/output.c
+    yeptris/validate/stream.c
     yeptris/tape.c
     yeptris/plan.c
 
     yeptris/marshal.c
+    yeptris/marshal/to_json.c
     yeptris/visit/json_visit.c
     yeptris/visit/yaml_visit.c
     yeptris/visit/dom_visit.c

data/vendor/libyeptris/src/include/yeptris/emit.h

@@ -24,7 +24,14 @@ extern "C" {
 #endif
 
 /* Emission options (13B). Versioned by size: initialize with
- * {sizeof(yeptris_emit_options)} so future fields stay optional. */
+ * {sizeof(yeptris_emit_options)} so future fields stay optional.
+ *
+ * Deliberately omitted: a flowLevel knob (libyaml's best_width +
+ * default_flow_style interplay). The engine's style chooser is
+ * recorded-style driven — flow is whatever the document recorded
+ * (plus the fixed canonical/JSON forms) — so there is no "switch to
+ * flow past level N" decision to expose; revisit only if a binding
+ * face actually needs PyYAML's default_flow_style mapping. */
 typedef struct yeptris_emit_options {
     uint32_t size;          /* sizeof(yeptris_emit_options) */
     int canonical;          /* fixed form: flow collections, quoted strings,
@@ -32,13 +39,34 @@ typedef struct yeptris_emit_options {
                              * output re-serializes byte-identically */
     int best_width;         /* 0 = library default (80): flow collections
                              * wrap after a value when the current line
-                             * exceeds the width (13B) */
+                             * exceeds the width (13B); with block_fold
+                             * it is also the fold column for block
+                             * scalars (#903) */
     int explicit_doc_start; /* nonzero: every document carries the
                              * leading --- marker (Psych/libyaml's
                              * implicit=false parity). Default 0: a
                              * single document is emitted bare. Only
                              * read when the caller's struct is large
                              * enough (size-versioned). */
+    int best_indent;        /* (#903) block indentation per level: the
+                             * content column of a nested block mapping
+                             * and the "- " item level. Out of range
+                             * (< 2 or > 9, libyaml's clamp) or 0 = the
+                             * library default 2. Only read when the
+                             * caller's struct is large enough. */
+    int block_fold;         /* (#903) nonzero: plain and single-quoted
+                             * scalars in block context fold at
+                             * best_width the way libyaml/Psych/PyYAML
+                             * do — at an interior single space past the
+                             * width the break replaces the space and
+                             * the continuation re-indents to
+                             * parent_col + best_indent. Default 0:
+                             * block output is width-invariant (byte-
+                             * identical with releases before the
+                             * option). Keys and flow members never
+                             * fold; canonical/JSON keep their fixed
+                             * forms. Only read when the caller's
+                             * struct is large enough. */
 } yeptris_emit_options;
 
 /* Options-aware entries; opts == NULL selects the fidelity mode

data/vendor/libyeptris/src/include/yeptris/parse.h

@@ -41,6 +41,79 @@ YEPTRIS_API YeptrisDocument yeptris_parse_ex(const char* buf, size_t len,
                                              const YeptrisParseOptions* opts,
                                              YeptrisStatus* status);
 
+/* ---- tolerant per-document stream iteration (#921) ----------------------
+ *
+ * load_stream parses the whole stream and aborts on the first bad
+ * document; this iterator frames documents engine-side (the abort-at-
+ * DOCUMENT_END run — scanner-accurate: a quoted scalar spanning a
+ * marker-looking line never splits) and reports failures PER DOCUMENT:
+ * a parse-class error surfaces as the step's status with NULL *out, the
+ * error channel carrying the failed document's own line/col (each run
+ * starts at the frame), and the iterator resynced to the next line-
+ * start marker — the host keeps calling and keeps the valid documents.
+ *
+ *   yeptris_stream_iter* it = yeptris_stream_iter_new(buf, len, &opts);
+ *   YeptrisDocument doc;
+ *   size_t index;
+ *   YeptrisStatus st;
+ *   while ((st = yeptris_stream_iter_next(it, &doc, &index)) == YEPTRIS_OK && doc != NULL) {
+ *       // doc is document `index` of the stream; free it with
+ *       // yeptris_document_free
+ *   }
+ *   // st == OK && doc == NULL: the stream is over; st != OK: document
+ *   // `index` failed (per-document line/col via
+ *   // yeptris_stream_iter_status), keep iterating.
+ *
+ * Memory: the caller owns each *out (yeptris_document_free). The
+ * iterator borrows `buf` until free. Each document parses twice (the
+ * boundary run + the slice parse) — the tolerance contract is the
+ * point; a single-pass upgrade rides the same seam when needed.
+ */
+typedef struct yeptris_stream_iter yeptris_stream_iter;
+
+/* The iterator borrows `buf` until free; `opts` is borrowed (may be
+ * NULL: the 12_CORE defaults). NULL on arg/alloc failure. */
+YEPTRIS_API yeptris_stream_iter* yeptris_stream_iter_new(const char* buf, size_t len,
+                                                         const YeptrisParseOptions* opts);
+
+/* The next document: OK + *out = the document (the caller frees it);
+ * a parse/DEPTH-class DOCUMENT failure: that status + *out = NULL +
+ * the error channel set for THAT document — the iterator has already
+ * resynced, keep calling; OK + *out = NULL: the stream is over;
+ * MEMORY/ENCODING: stream-fatal, the iterator is done. *index (may be
+ * NULL) is the 0-based stream document index this step consumed
+ * (failures consume an index too — the yield order is the stream's). */
+YEPTRIS_API YeptrisStatus yeptris_stream_iter_next(yeptris_stream_iter* it, YeptrisDocument* out,
+                                                   size_t* index);
+
+/* The LAST step's per-document verdict and its 1-based line/col
+ * (0/0 when the last step was a success or the stream end). */
+YEPTRIS_API YeptrisStatus yeptris_stream_iter_status(const yeptris_stream_iter* it, uint32_t* line,
+                                                     uint32_t* col);
+
+/* The last successful step's document SLICE inside the iterator's
+ * buffer space (post-gate: BOM/transcode/normalization may have moved
+ * the buffer — the offsets are relative to the CURRENT buf the
+ * iterator holds, which is the space `yeptris_stream_iter_next`'s
+ * documents live in). Hosts that materialize through their own value
+ * route (the Python/Rust/TS drains) re-parse exactly these bytes and
+ * inherit the engine's framing without a DOM walk: one typing SSOT —
+ * the drain — and scanner-accurate frames. ARG on NULL; ARG when the
+ * last step was not a successful document. */
+YEPTRIS_API YeptrisStatus yeptris_stream_iter_slice(const yeptris_stream_iter* it, size_t* off,
+                                                    size_t* len);
+
+/* The iterator's ACTIVE buffer (the caller's bytes, or the post-gate
+ * owned copy after a BOM strip / UTF-16-32 transcode / NEL-LS-PS
+ * normalization) and its length. `yeptris_stream_iter_slice`'s offsets
+ * index THIS buffer — hosts copy their frame bytes out of here
+ * (ctypes.string_at / Rust slice / TS Buffer) and re-parse them through
+ * their own drain. Borrowed: valid until yeptris_stream_iter_free. */
+YEPTRIS_API YeptrisStatus yeptris_stream_iter_buffer(const yeptris_stream_iter* it,
+                                                     const char** buf, size_t* len);
+
+YEPTRIS_API void yeptris_stream_iter_free(yeptris_stream_iter* it);
+
 #ifdef __cplusplus
 }
 #endif

data/vendor/libyeptris/src/include/yeptris/resolve.h

@@ -46,6 +46,14 @@ typedef enum {
     YEPTRIS_SCHEMA_11_COMPAT,   /* libyaml/Psych implicit typing */
     YEPTRIS_SCHEMA_12_JSON,     /* spec 10.2: JSON productions; plain
                                  * scalars matching none are errors (#882) */
+    YEPTRIS_SCHEMA_12_FULL,     /* the full 1.2 family (#906 slice 3):
+                                 * core typing + RFC3339-era timestamps
+                                 * (spec 2.22's four forms; the yaml.org
+                                 * type repository carried forward) and
+                                 * the merge/value words; !!binary rides
+                                 * as passthrough. A validation family:
+                                 * explicit !!timestamp content must
+                                 * re-resolve through the classifier. */
 } YeptrisSchema;
 
 /* Canonical tag URI for a core id ("tag:yaml.org,2002:str"); NULL for

data/vendor/libyeptris/src/include/yeptris/validate.h

@@ -7,21 +7,52 @@
  *     consistency (spec 10.3 resolution) and mapping-key uniqueness
  *     (spec 3.2.1.3: keys compare by canonical form — 0o13 and 0xB
  *     are the same key). Under YEPTRIS_SCHEMA_12_JSON the spec 10.2
- *     family applies: every PLAIN scalar must match a JSON production
- *     (the table's `*` -> Error row), mapping keys must be strings,
- *     non-JSON tags are rejected; core checks still run.
+ *     family applies: implicit resolution uses ONLY the JSON
+ *     productions (the core extensions — 0o/0x radix, "+12.3",
+ *     "True"/"~" casings — stay strings, per example 10.8's Invalid
+ *     list), mapping keys must be strings (a key resolving to a
+ *     non-string production is KEY_NOT_STRING; a no-production plain
+ *     key IS a string, per example 10.8), explicit non-JSON tags are
+ *     rejected; core checks still run. Under YEPTRIS_SCHEMA_12_FULL
+ *     the spec 10.4 "other schema" family applies — the core schema
+ *     "extended with additional tag resolution rules": untagged plains
+ *     also resolve RFC3339-era timestamps (spec example 2.22's
+ *     canonical/iso8601/spaced/date forms, classified by PyYAML's
+ *     timestamp regex as the practice oracle) and the merge/value
+ *     words, while explicit !!timestamp content must re-resolve
+ *     through the same classifier (TAG_MISMATCH otherwise). !!binary
+ *     rides as passthrough (base64 shaping is a construction concern);
+ *     core checks still run. The 1.1 numeric quirks (underscores,
+ *     sexagesimal, leading-0 octal, y/n booleans) stay with
+ *     11_COMPAT — full is spec-refereed, not psych-refereed.
  *
  *  2. JSON SCHEMA validation (`yeptris_json_schema_validate`): the
  *     schema arrives as bytes (parsed with the same engine), the
  *     target against it — draft 2020-12 keyword subset (see the entry
  *     comment). Unknown keywords are ignored, per 2020-12.
  *
+ * The COMPILED-schema economy (`yeptris_schema_*`) retains one parsed
+ * schema for many instance streams; the TAG-DRIVEN registry
+ * (`yeptris_schema_registry_*`, #906 slice 4) binds compiled schemas
+ * to user tags over the family walk (`yeptris_validate_ex`). The
+ * report converts to the published JSON-Schema output shape
+ * (`yeptris_validate_report_write`, #906 slice 5).
+ *
  * Every diagnostic carries a JSON-pointer instance path ("/a/b/0" —
  * ~0/~1 escaped), a YEPTRIS_DIAG_* code, a bounded expected/got
  * detail, and the offending node's 1-based line/column (0 = unknown:
  * scalars whose bytes the DOM owns in its arena have no input
  * position; the path still identifies them exactly).
  *
+ * STREAMS (#885 item 4): a validated stream is addressed as an array
+ * of documents. When the input holds MORE THAN ONE document, every
+ * diagnostic path is prefixed with its document's index segment —
+ * "/1/a/b" is a/b of document 1 (0-based), so diagnostics name their
+ * document even when the miss is unpositioned (an empty document's
+ * Error-row scalar has no line/col). Line/col/offset stay
+ * input-absolute. Streams with a single document keep the bare
+ * instance pointers — existing consumers' paths are unchanged.
+ *
  * Results are WHOLE REPORTS: one call, no per-diagnostic callback —
  * the caller drains the flat array and frees the report once.
  */
@@ -84,6 +115,9 @@ typedef enum {
     YEPTRIS_DIAG_MIN_CONTAINS = 31,
     YEPTRIS_DIAG_MAX_CONTAINS = 32,
     YEPTRIS_DIAG_DEPENDENT_REQUIRED = 33,
+    /* the 2020-12 unevaluated* annotation model (the sota sweep) */
+    YEPTRIS_DIAG_UNEVALUATED_PROPERTY = 34, /* no sibling/applicator evaluated it */
+    YEPTRIS_DIAG_UNEVALUATED_ITEM = 35,
 } YeptrisDiagCode;
 
 /* Bounded diagnostic text; always NUL-terminated (over-long paths and
@@ -118,7 +152,14 @@ YEPTRIS_API void yeptris_validate_report_free(yeptris_validate_report* report);
 
 /* Parses `buf` (the same front door as yeptris_parse_ex: encodings,
  * BOM, NEL normalization) and validates every document of the stream
- * against `schema`. Paths are root-relative per document.
+ * against `schema` — the strict lanes: explicit-tag consistency,
+ * canonical-form key uniqueness, (12_JSON) string keys over the JSON
+ * productions, and (12_FULL) timestamp content against the full
+ * family's classifier. Paths are root-relative per document; a
+ * multi-document stream prefixes them with the document index (see
+ * STREAMS above), so diagnostics name their document. The parse's own
+ * guards compose: a document past the engine's depth cap fails the
+ * parse (YEPTRIS_ERROR_DEPTH) before any validation runs.
  *
  * Status: YEPTRIS_OK (valid; *out is a report — possibly with zero
  * diagnostics for an empty stream); YEPTRIS_ERROR_SCHEMA (invalid:
@@ -135,22 +176,67 @@ YEPTRIS_API YeptrisStatus yeptris_validate(const char* buf, size_t len, YeptrisS
 YEPTRIS_API YeptrisStatus yeptris_validate_document(YeptrisDocument doc, YeptrisSchema schema,
                                                     yeptris_validate_report** out);
 
-/* JSON Schema draft 2020-12 subset (#882 slice 2; #885 item 2). `schema`
- * is parsed with the same engine (JSON is YAML flow); document 0 of the
- * stream is the schema. Keyword subset: type, enum, const, pattern,
- * minimum/maximum/exclusiveMinimum/exclusiveMaximum (numeric, 2020-12
- * form), multipleOf (libm-free quotient test), minLength/maxLength
- * (code points), minItems/maxItems, uniqueItems, contains (+ the
- * minContains/maxContains qualifiers), items (+ prefixItems; the
- * draft-07 array form rides as prefixItems), properties, required,
- * patternProperties, propertyNames, minProperties/maxProperties,
- * additionalProperties (bool or schema; excludes patternProperties
- * matches), dependentRequired, dependentSchemas, if/then/else,
- * allOf/anyOf/oneOf/not, $ref (LOCAL "#/..." pointers only — $defs and
- * definitions both resolve). Boolean schemas (`true`/`false`) apply.
- * Unknown keywords and known keywords with unreadable values are
- * ignored (2020-12). Instance types ride the core-schema resolution
- * (the YAML->JSON data model): "y" is boolean, 1.0 is integer.
+/* The EVENT-ROUTE twin of yeptris_validate (#902): the same parse
+ * (front-end, depth/encoding guards, statuses — the DOM route's
+ * sink-entry seam) feeding a streaming validator state machine. The
+ * family lanes ride the event walk itself; NO node tree is ever
+ * built. Everything observable is the DOM route's, by construction
+ * and by the differential gate:
+ *
+ *  - diagnostics: the same code rail (0-35 after the sweep), the same report shape and
+ *    cap, the same JSON-pointer paths and the stream face's
+ *    per-document attribution — emitted in the DOM walk's order (a
+ *    mapping's own tag check, its duplicate-key misses, then its
+ *    pairs' content);
+ *  - positions: the DOM route's region law — a diagnostic sits at the
+ *    node's input-borrowed value bytes (0/0 when the engine pooled
+ *    them), so line/col/offset match bit for bit;
+ *  - statuses: OK / SCHEMA / PARSE / DEPTH / ENCODING / MEMORY / ARG,
+ *    byte-identical argument gates (NULL with length, 11_COMPAT).
+ *    All three families (12_CORE / 12_JSON / 12_FULL) ride both
+ *    routes with identical verdicts.
+ *
+ * The compiled JSON Schema lane (yeptris_schema_validate) keeps the
+ * DOM route: its evaluator needs random access (uniqueItems, contains,
+ * required); a streaming twin waits for #901's annotation-model seam.
+ *
+ * Memory: the caller owns *out; free it with
+ * yeptris_validate_report_free. */
+YEPTRIS_API YeptrisStatus yeptris_validate_stream(const char* buf, size_t len, YeptrisSchema schema,
+                                                  yeptris_validate_report** out);
+
+/* JSON Schema draft 2020-12 subset (#882 slice 2; #885 item 2; the
+ * 2020-12 sota sweep). `schema` is parsed with the same engine (JSON
+ * is YAML flow); document 0 of the stream is the schema. Keyword
+ * subset: type, enum, const, pattern, minimum, maximum,
+ * exclusiveMinimum, exclusiveMaximum (numeric, 2020-12 form),
+ * multipleOf (libm-free quotient test),
+ * minLength/maxLength (code points), minItems/maxItems, uniqueItems,
+ * contains (+ the minContains/maxContains qualifiers), items
+ * (+ prefixItems; the draft-07 array form rides as prefixItems),
+ * properties, required, patternProperties, propertyNames,
+ * minProperties/maxProperties, additionalProperties (bool or schema;
+ * excludes patternProperties matches), dependentRequired,
+ * dependentSchemas, if/then/else, allOf/anyOf/oneOf/not,
+ * unevaluatedProperties/unevaluatedItems (the 2020-12 annotation
+ * model: evaluations collect upward through the in-place applicators,
+ * a failed branch annotates nothing, and nothing crosses an
+ * instance-location boundary), $ref, $dynamicRef, boolean schemas.
+ * REFERENCES: $id base-URI composition (RFC 3986 path merge),
+ * $anchor/$dynamicAnchor plain-name fragments scoped to their nearest
+ * $id resource, JSON Pointer fragments with the percent layer
+ * (%25 -> '%', then ~0/~1), and $dynamicRef's runtime dynamic scope
+ * (the OUTERMOST schema resource in scope defining the anchor). No
+ * network: a reference resolves only against the schema's own
+ * identifier space — an external target (the metaschema, an HTTP
+ * fixture) is a DIAG_REF, never a fetch. Boolean schemas
+ * (`true`/`false`) apply. Unknown keywords and known keywords with
+ * unreadable values are ignored (2020-12). Instance types ride the
+ * core-schema resolution (the YAML->JSON data model): "y" is boolean,
+ * 1.0 is integer. The IETF WG's next-edition draft
+ * (draft-ietf-jsonschema-json-schema-00) carries these same keyword
+ * semantics — no evaluator delta; the diff record is
+ * docs/schema/ietf-wg-draft-delta.md.
  *
  * Status: as yeptris_validate, plus YEPTRIS_ERROR_ARG when the schema
  * bytes hold no document, and YEPTRIS_ERROR_PARSE when they do not
@@ -175,7 +261,9 @@ YEPTRIS_API YeptrisStatus yeptris_json_schema_validate(const char* schema, size_
  *
  * yeptris_schema_validate keeps yeptris_json_schema_validate's exact
  * status/report contract; diagnostics enumerate every miss across
- * every document of the instance stream. yeptris_schema_free releases
+ * every document of the instance stream — the stream face's document
+ * attribution applies (see STREAMS above): a multi-document stream's
+ * paths carry the document index. yeptris_schema_free releases
  * the handle and everything it owns in ONE call (no refcounting) —
  * afterwards the handle is DEAD: passing it anywhere is undefined,
  * exactly like a freed document. NULL is accepted (a no-op).
@@ -193,6 +281,119 @@ YEPTRIS_API YeptrisStatus yeptris_schema_validate(yeptris_schema* s, const char*
 
 YEPTRIS_API void yeptris_schema_free(yeptris_schema* s);
 
+/* ---- the TAG-DRIVEN SCHEMA registry (#906 slice 4) -----------------------
+ *
+ * The dialect table's reserved slot: a compiled schema binds to a user
+ * tag, so a document node carrying `!shape` (its EXPLICIT tag, exactly
+ * the resolved bytes the DOM exposes — `!shape`, `!<tag:...>`, or a
+ * `%TAG`-resolved URI; `!!x` arrives as `tag:yaml.org,2002:x`) has its
+ * SUBTREE validated against the bound schema. Registration is the only
+ * extension point (OCP): the family walk reads the registry, it never
+ * grows schema branches.
+ *
+ * Matching is byte-exact on the tag's resolved form and fires only on
+ * an explicit tag — implicit (plain) typing never triggers a binding.
+ * An unregistered tag passes untouched: no diagnostic, no lane. The
+ * hook rides the DOM family walk (yeptris_validate_ex /
+ * yeptris_validate_document_ex): roots, sequence items and mapping
+ * VALUES (a tagged mapping KEY is not registry-validated — its
+ * instance path is undefined in the walk's model). Diagnostics from a
+ * bound subtree land at the tag site: the tag node's own path + the
+ * schema walk's instance pointers, with the offending node's
+ * line/col/offset; the report cap and codes are the shared rail.
+ * Bindings COMPOSE: a node inside a bound subtree that carries its own
+ * registered tag is validated by both schemas.
+ *
+ * THE REGISTRY LAW (the document-ownership law, no refcounting): the
+ * registry BORROWS the compiled schemas it binds — it owns nothing
+ * they own. A bound schema must OUTLIVE the registry: free the
+ * registry first (yeptris_schema_registry_free), then the schemas.
+ * Freeing a bound schema while its registry lives leaves the registry
+ * dead (a later lookup is undefined), exactly like a freed document.
+ * NULL is accepted everywhere a handle is (a NULL registry is simply
+ * no bindings; yeptris_schema_registry_free(NULL) is a no-op).
+ *
+ * Thread law: one registry per thread, like documents and schemas —
+ * it is mutable under register and read-only during validation;
+ * read-only sharing across threads (no register in flight) is safe. */
+typedef struct yeptris_schema_registry yeptris_schema_registry;
+
+/* A fresh empty registry; NULL on allocation failure. */
+YEPTRIS_API yeptris_schema_registry* yeptris_schema_registry_new(void);
+
+/* Binds `tag` (copied — nothing borrows the caller's bytes beyond the
+ * call) to the compiled `schema` (borrowed — see THE REGISTRY LAW).
+ * Status: YEPTRIS_OK; YEPTRIS_ERROR_ARG (NULL handle, an empty tag,
+ * or a NULL schema); YEPTRIS_ERROR_MEMORY. Re-registering a tag
+ * REPLACES the binding (last registration wins). */
+YEPTRIS_API YeptrisStatus yeptris_schema_registry_register(yeptris_schema_registry* reg,
+                                                           const char* tag, size_t tag_len,
+                                                           const yeptris_schema* schema);
+
+/* The schema bound to `tag` (exact bytes), or NULL. Memory: borrowed
+ * from the registry — valid until a register replaces the tag or the
+ * registry is freed. */
+YEPTRIS_API const yeptris_schema* yeptris_schema_registry_lookup(const yeptris_schema_registry* reg,
+                                                                 const char* tag, size_t tag_len);
+
+YEPTRIS_API void yeptris_schema_registry_free(yeptris_schema_registry* reg);
+
+/* Validation options (size-versioned like yeptris_emit_options:
+ * initialize with {sizeof(yeptris_validate_options)} so future fields
+ * stay optional; NULL selects the defaults). */
+typedef struct yeptris_validate_options {
+    uint32_t size; /* sizeof(yeptris_validate_options) */
+    /* The tag-driven registry (#906 slice 4): NULL = none. Only read
+     * when the caller's struct is large enough (size-versioned). The
+     * registry is borrowed for the call; see THE REGISTRY LAW above. */
+    const yeptris_schema_registry* registry;
+} yeptris_validate_options;
+
+/* yeptris_validate / yeptris_validate_document with options: the
+ * family walk plus, when a registry is attached, the tag-driven
+ * schema applications described above. Everything else (statuses,
+ * report shape, paths, positions) is the flat face's, unchanged. */
+YEPTRIS_API YeptrisStatus yeptris_validate_ex(const char* buf, size_t len, YeptrisSchema schema,
+                                              const yeptris_validate_options* opts,
+                                              yeptris_validate_report** out);
+
+YEPTRIS_API YeptrisStatus yeptris_validate_document_ex(YeptrisDocument doc, YeptrisSchema schema,
+                                                       const yeptris_validate_options* opts,
+                                                       yeptris_validate_report** out);
+
+/* ---- the structured OUTPUT face (#906 slice 5) ---------------------------
+ *
+ * The report as the json-schema.org RECOMMENDED OUTPUT shape (core
+ * spec section 12; the meta-schema at
+ * https://json-schema.org/draft/2020-12/output/schema): one root
+ * output unit — {"valid", "keywordLocation", "instanceLocation"} and,
+ * when the report carries diagnostics, "errors" — with one child unit
+ * per diagnostic {valid, keywordLocation, instanceLocation, error}.
+ * This is the published BASIC form: the report is flat by the
+ * enumerated-misses law, so the schema-structured DETAILED/VERBOSE
+ * hierarchies (which need per-miss schema-side keyword paths the flat
+ * report does not carry) are not derivable from it. keywordLocation
+ * is derived from the diagnostic code — the keyword's name segment
+ * ("/type", "/required", ...; the family codes and the bookkeeping
+ * codes sit at the root pointer ""); it is a JSON Pointer, but NOT
+ * necessarily resolvable in the schema (the flat report carries no
+ * schema path). absoluteKeywordLocation is never emitted, and $ref
+ * sites report the root pointer, so the output always satisfies the
+ * published meta-schema. Strings are JSON-escaped (RFC 8259); the
+ * bytes are UTF-8; the transform is pure and deterministic — the same
+ * report always produces the same bytes.
+ *
+ * buf == NULL: returns the exact byte count needed, writes nothing.
+ * Otherwise writes at most cap bytes (NUL-terminated when cap
+ * allows) and returns the count written; when cap is too small
+ * nothing is written and the needed size is returned. Returns 0 on a
+ * NULL report (use the flat face for those — the transform never
+ * invents a verdict).
+ *
+ * Memory: writes into the caller's buffer; borrows nothing. */
+YEPTRIS_API size_t yeptris_validate_report_write(const yeptris_validate_report* report, char* buf,
+                                                 size_t cap);
+
 #ifdef __cplusplus
 }
 #endif