yeptris 0.1.13.3-x86_64-linux

data/lib/yeptris/materializer.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Yeptris
+  # Recorder-driven Ruby materialization (TODO.impl/15 phase B).
+  #
+  # One bulk drain: the record array and string arena are read in two
+  # calls, then a pure-Ruby stack machine walks fixed-layout records —
+  # the FFI tax is O(chunks), never O(events). The DOM-walk
+  # materializer (Node#to_ruby) stays for node-based use; this is the
+  # Yeptris::YAML fast path.
+  class Materializer
+    RECORD_SIZE = 36 # YeptrisEventRecord layout (events.h, ABI-pinned)
+    FIELDS = 12      # unpacked values per record
+    RECORD_UNPACK = "C4V8" # type/style/flags/tag_id, line..tag_len
+
+    STREAM_START = 1
+    STREAM_END = 2
+    DOCUMENT_START = 3
+    DOCUMENT_END = 4
+    SEQUENCE_START = 5
+    SEQUENCE_END = 6
+    MAPPING_START = 7
+    MAPPING_END = 8
+    SCALAR = 9
+    ALIAS = 10
+
+    EF_IMPLICIT = 1 << 2
+    STYLE_PLAIN = 1
+
+    # YeptrisTagId values (resolve.h; FFI mirrors them)
+    TAG_STR = Yeptris::FFI::TAG_STR
+    TAG_INT = Yeptris::FFI::TAG_INT
+    TAG_FLOAT = Yeptris::FFI::TAG_FLOAT
+    TAG_BOOL = Yeptris::FFI::TAG_BOOL
+    TAG_NULL = Yeptris::FFI::TAG_NULL
+    TAG_TIMESTAMP = Yeptris::FFI::TAG_TIMESTAMP
+    TAG_MERGE = 9 # YEPTRIS_TAG_MERGE (resolve.h): a plain '<<' key
+
+    INF_WORDS = {
+      ".inf" => Float::INFINITY, ".Inf" => Float::INFINITY, ".INF" => Float::INFINITY,
+      "+.inf" => Float::INFINITY, "+.Inf" => Float::INFINITY, "+.INF" => Float::INFINITY,
+      "-.inf" => -Float::INFINITY, "-.Inf" => -Float::INFINITY, "-.INF" => -Float::INFINITY,
+      ".nan" => Float::NAN, ".NaN" => Float::NAN, ".NAN" => Float::NAN,
+    }.freeze
+    SEXAGESIMAL_INT = /\A[-+]?[1-9][0-9_]*(:[0-5]?[0-9])+\z/
+    SEXAGESIMAL_FLOAT = /\A[-+]?[0-9][0-9_]*(:[0-5]?[0-9])+:[0-5]?[0-9]\.[0-9_]*\z/
+
+    class << self
+      # First document of the stream, or nil when the stream is empty.
+      def load(yaml, schema: :compat_11)
+        docs = load_stream(yaml, schema: schema)
+        docs.empty? ? nil : docs.first
+      end
+
+      # Every document in the stream, in order.
+      def load_stream(yaml, schema: :compat_11)
+        new(schema: schema).materialize(yaml)
+      end
+
+      # The shared drain seam: one parse, records + arena read once,
+      # ONE unpack into a flat Integer array (12 fields per record:
+      # type style flags tag_id line col v_off v_len a_off a_len
+      # t_off t_len). Both consumers ride it — the stack machine
+      # (materialize) and the Psych::Parser dispatch loop.
+      def drain(yaml, schema: :compat_11)
+        rec = Yeptris::FFI.yeptris_recorder_new_ex(
+          schema == :compat_11 ? Yeptris::FFI::SCHEMA_11_COMPAT : Yeptris::FFI::SCHEMA_12_CORE
+        )
+        begin
+          status = Yeptris::FFI.yeptris_recorder_feed(rec, yaml, yaml.bytesize, 1)
+          if status != Yeptris::FFI::OK
+            raise Yeptris::ParseError,
+                  "parse failed: #{Yeptris::FFI.last_error_message}"
+          end
+          count_p = ::FFI::MemoryPointer.new(:size_t)
+          records = Yeptris::FFI.yeptris_recorder_records(rec, count_p)
+          count = count_p.read_uint64
+          arena_len = ::FFI::MemoryPointer.new(:size_t)
+          arena_ptr = Yeptris::FFI.yeptris_recorder_arena(rec, arena_len)
+          arena_len_v = arena_len.read_uint64
+          arena = arena_ptr.null? || arena_len_v.zero? ? +"" : arena_ptr.read_bytes(arena_len_v)
+          flat = records.read_bytes(count * RECORD_SIZE)
+                     .unpack(RECORD_UNPACK * count)
+          [flat, arena]
+        ensure
+          Yeptris::FFI.yeptris_recorder_free(rec)
+        end
+      end
+
+      # The Ruby value of a scalar per schema — the ScalarScanner rule
+      # set, spec-verified against Psych case by case. Only implicit
+      # PLAIN scalars scan; quoting is the escape hatch.
+      # The record's tag_id IS the resolver's verdict (the typing
+      # SSOT): conversion by tag, Kernel#Integer/Float for the bytes —
+      # no host-side grammar. Two Psych-quirk overrides where Psych's
+      # scanner disagrees with the 1.1 resolver: single-char y/Y/n/N
+      # are STRINGS in Psych (libyaml says bool), and values the
+      # resolver tagged INT but Kernel rejects (mixed forms) fall back
+      # through sexagesimal to String.
+      PSYCH_TRUE = %w[y yes true on].freeze
+
+      # '<<' merge: existing keys win; sequences merge in order.
+      # Shared by the record walk and the value-stream walk.
+      def merge_into(map, obj)
+        case obj
+        when Hash
+          obj.each { |k, v| map[k] = v unless map.key?(k) }
+        when Array
+          obj.each { |e| merge_into(map, e) if e.is_a?(Hash) }
+        end
+      end
+
+      def parse_timestamp(v)
+        return Date.parse(v) unless v.match?(/[Tt ]\d/)
+
+        # normalize the YAML 1.1 space forms onto iso8601 for
+        # xmlschema: "2001-12-14 21:59:43.10 -05:00" ->
+        # "2001-12-14T21:59:43.10-05:00" (Psych's scanner does the
+        # same dance)
+        ts = v.sub(/ (\d)/, 'T\1').sub(/ ([+-]\d)/, '\1').sub(/ +Z\z/i, 'Z')
+        # Psych reads a NAIVE timestamp (no zone, no Z) as a UTC
+        # instant expressed in the local zone — one wall-clock hour
+        # off from reading it as local time (pinned by spec against
+        # Psych.unsafe_load across tz shapes)
+        if ts.match?(/(Z|[+-]\d\d:?\d\d)\z/i)
+          Time.xmlschema(ts)
+        else
+          Time.xmlschema(ts + "Z").getlocal
+        end
+      rescue ArgumentError
+        v
+      end
+
+      def scan_by_tag(value, tag_id, implicit)
+        case tag_id
+        when TAG_STR
+          return value unless implicit
+
+          value.start_with?(":") && !value.start_with?("::") &&
+            value.length > 1 ? value[1..].to_sym : value
+        when TAG_NULL then nil
+        when TAG_BOOL
+          return value if value.length == 1 # Psych: "y"/"n" stay Strings
+
+          PSYCH_TRUE.include?(value.downcase)
+        when TAG_INT
+          int_or_string(value)
+        when TAG_FLOAT
+          float_or_string(value)
+        when TAG_TIMESTAMP
+          parse_timestamp(value)
+        else
+          value
+        end
+      end
+
+      def int_or_string(value)
+        Integer(value.tr("_", ""))
+      rescue ArgumentError
+        # the resolver said INT but Kernel disagrees (mixed form):
+        # sexagesimal or back to String
+        return sexagesimal(value) if SEXAGESIMAL_INT.match?(value) ||
+                                     SEXAGESIMAL_FLOAT.match?(value)
+
+        value
+      end
+
+      def float_or_string(value)
+        return INF_WORDS[value] if INF_WORDS.key?(value)
+        return value unless value.include?(".")
+
+        # Psych's FLOAT: the exponent carries a mandatory sign —
+        # "1e3" and "1.5e3" are Strings (resolver quirk override)
+        return value if /[eE][^+-]/.match?(value)
+
+        Float(value.tr("_", ""))
+      rescue ArgumentError
+        return sexagesimal(value) if SEXAGESIMAL_FLOAT.match?(value)
+
+        value
+      end
+
+      private
+
+      # Psych's scanner IS Kernel#Integer on the plain digits: Ruby
+      # reads leading-zero strings as octal, rejects "018", takes
+      # 0x/0b/bases — verified case by case against Psych.
+      def sexagesimal(v)
+        is_float = v.include?(".")
+        total = 0
+        v.split(":").each_with_index do |n, e|
+          total += (is_float ? n.to_f : n.to_i) * (60**(e - 2).abs)
+        end
+        total
+      end
+
+
+    end
+
+    def initialize(schema: :compat_11)
+      @schema = schema
+    end
+
+    def materialize(yaml)
+      yaml = Yeptris.read_input(yaml)
+      yaml = yaml.to_s
+      flat, arena = Materializer.drain(yaml, schema: @schema)
+      walk(flat, arena)
+    end
+
+    private
+
+    # The stack machine: containers on a stack, a pending-key slot per
+    # open mapping, anchors by name (first definition wins; an alias
+    # yields the SAME Ruby object — identity preserved). Merge keys
+    # (<<) resolve inline: existing keys win, sequences merge in
+    # order — Psych load-time semantics.
+    #
+    # flat: one Integer per unpack field, 12 per record:
+    # 0 type, 1 style, 2 flags, 3 tag_id, 4 line, 5 col, 6 value_off,
+    # 7 value_len, 8 anchor_off, 9 anchor_len, 10 tag_off, 11 tag_len.
+    def walk(flat, arena)
+      docs = []
+      stack = []
+      anchors = {}
+      pending_key = []
+      pending_key_merge = []
+      # per open container: the map to merge into when this container
+      # closes (inline `<<:` values), nil otherwise
+      merge_target = []
+
+      # the arena is UTF-8 by construction (validated at parse), so
+      # forcing its encoding ONCE makes every slice UTF-8 for free —
+      # no per-scalar force_encoding
+      arena.force_encoding(Encoding::UTF_8)
+      # (each_slice DESTRUCTURING measured SLOWER than plain indexing
+      # here: it allocates a 12-slot Array per record. Index away.)
+      i = 0
+      n = flat.length
+      while i < n
+        type = flat[i]
+        case type
+        when SCALAR
+          # a plain, resolver-tagged '<<' (TAG_MERGE) merges; a
+          # QUOTED '<<' is a literal key — Psych merges on the tag,
+          # not the text
+          tag_id = flat[i + 3]
+          v = Materializer.scan_by_tag(
+            arena[flat[i + 6], flat[i + 7]], tag_id, (flat[i + 2] & EF_IMPLICIT) != 0
+          )
+          l = flat[i + 9]
+          anchors[arena[flat[i + 8], l]] = v if l != 0
+          # place(): the scalar fast path inlined — the overwhelming
+          # majority of events land here
+          if stack.empty?
+            docs[-1] = v
+          else
+            parent = stack.last
+            if parent.is_a?(Hash)
+              if (key = pending_key[-1]).nil?
+                pending_key[-1] = v
+                pending_key_merge[-1] = flat[i + 3] == TAG_MERGE
+              else
+                pending_key[-1] = nil
+                if pending_key_merge[-1]
+                  merge_into(parent, v)
+                else
+                  parent[key] = v
+                end
+              end
+            else
+              parent.push(v)
+            end
+          end
+        when MAPPING_START
+          h = {}
+          l = flat[i + 9]
+          anchors[arena[flat[i + 8], l]] = h if l != 0
+          merge_target.push(place(docs, stack, pending_key, pending_key_merge, h))
+          stack.push(h)
+          pending_key.push(nil)
+          pending_key_merge.push(nil)
+        when SEQUENCE_START
+          a = []
+          l = flat[i + 9]
+          anchors[arena[flat[i + 8], l]] = a if l != 0
+          merge_target.push(place(docs, stack, pending_key, pending_key_merge, a))
+          stack.push(a)
+          pending_key.push(nil)
+          pending_key_merge.push(nil)
+        when ALIAS
+          name = arena[flat[i + 6], flat[i + 7]]
+          raise Yeptris::ParseError, "unknown anchor: #{name.inspect}" unless anchors.key?(name)
+
+          place(docs, stack, pending_key, pending_key_merge, anchors[name])
+        when MAPPING_END, SEQUENCE_END
+          done = stack.pop
+          pending_key.pop
+          pending_key_merge.pop
+          target = merge_target.pop
+          merge_into(target, done) if target
+        when DOCUMENT_START
+          docs.push(nil)
+        end
+        i += FIELDS
+      end
+      docs
+    end
+
+    # Attaches obj: as the current document's root when nothing is
+    # open, as a sequence entry, or as the pending mapping key/value.
+    # Returns the merge TARGET when obj is a container placed under a
+    # "<<" key — the caller defers the merge to the container's END
+    # (an inline map's contents arrive after its start event); scalar
+    # and alias merges apply immediately.
+    def place(docs, stack, pending_key, pending_key_merge, obj)
+      if stack.empty?
+        docs[-1] = obj
+        return nil
+      end
+      parent = stack.last
+      if parent.is_a?(Hash)
+        if pending_key.last.nil?
+          pending_key[-1] = obj
+          pending_key_merge[-1] = false
+          return nil
+        end
+        key = pending_key.last
+        pending_key[-1] = nil
+        if pending_key_merge[-1]
+          merge_into(parent, obj)
+          parent
+        else
+          parent[key] = obj
+          nil
+        end
+      else # Array
+        parent.push(obj)
+        nil
+      end
+    end
+
+  end
+end

data/lib/yeptris/node.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+# A node inside a document. Borrowed C memory: every call routes
+# through the owning document's liveness check — use after free
+# raises Yeptris::FreedError, never a segfault.
+class Yeptris::Node
+  include Enumerable
+
+  attr_reader :c_ptr
+
+  # @api private — always constructed via Document#wrap_node (identity).
+  def initialize(c_ptr, document)
+    @c_ptr = c_ptr
+    @document = document
+  end
+
+  def document
+    @document
+  end
+
+  KINDS = {
+    Yeptris::FFI::NODE_SCALAR => :scalar,
+    Yeptris::FFI::NODE_SEQUENCE => :sequence,
+    Yeptris::FFI::NODE_MAPPING => :mapping,
+    Yeptris::FFI::NODE_ALIAS => :alias,
+  }.freeze
+
+  def kind
+    KINDS[alive { Yeptris::FFI.yeptris_node_kind(@c_ptr) }]
+  end
+
+  def scalar?
+    kind == :scalar
+  end
+
+  def sequence?
+    kind == :sequence
+  end
+
+  def mapping?
+    kind == :mapping
+  end
+
+  def alias?
+    kind == :alias
+  end
+
+  # Scalar content / alias name (UTF-8 String), nil for collections.
+  def value
+    len = ::FFI::MemoryPointer.new(:uint64)
+    ptr = alive { Yeptris::FFI.yeptris_node_value(@c_ptr, len) }
+    return nil if ptr.null?
+
+    ptr.read_bytes(len.read_uint64).force_encoding(Encoding::UTF_8)
+  end
+
+  STYLES = {
+    Yeptris::FFI::STYLE_PLAIN => :plain,
+    Yeptris::FFI::STYLE_SINGLE_QUOTED => :single_quoted,
+    Yeptris::FFI::STYLE_DOUBLE_QUOTED => :double_quoted,
+    Yeptris::FFI::STYLE_LITERAL => :literal,
+    Yeptris::FFI::STYLE_FOLDED => :folded,
+  }.freeze
+
+  def style
+    STYLES[alive { Yeptris::FFI.yeptris_node_style(@c_ptr) }]
+  end
+
+  # Explicit tag URI when present, else nil.
+  def tag
+    len = ::FFI::MemoryPointer.new(:uint64)
+    ptr = alive { Yeptris::FFI.yeptris_node_tag(@c_ptr, len) }
+    return nil if ptr.null?
+
+    ptr.read_bytes(len.read_uint64).force_encoding(Encoding::UTF_8)
+  end
+
+  def anchor
+    len = ::FFI::MemoryPointer.new(:uint64)
+    ptr = alive { Yeptris::FFI.yeptris_node_anchor(@c_ptr, len) }
+    return nil if ptr.null?
+
+    ptr.read_bytes(len.read_uint64).force_encoding(Encoding::UTF_8)
+  end
+
+  def alias_target
+    t = alive { Yeptris::FFI.yeptris_node_alias_target(@c_ptr) }
+    @document.wrap_node(t)
+  end
+
+  # ---- typed scalar reads (tag id decides eligibility) ----
+
+  def to_i
+    out = ::FFI::MemoryPointer.new(:int64)
+    status = alive { Yeptris::FFI.yeptris_node_int(@c_ptr, out) }
+    Yeptris::FFI.check_status(status, "yeptris_node_int")
+    out.read_int64
+  end
+
+  def to_f
+    out = ::FFI::MemoryPointer.new(:double)
+    status = alive { Yeptris::FFI.yeptris_node_float(@c_ptr, out) }
+    Yeptris::FFI.check_status(status, "yeptris_node_float")
+    out.read_double
+  end
+
+  def to_bool
+    out = ::FFI::MemoryPointer.new(:int)
+    status = alive { Yeptris::FFI.yeptris_node_bool(@c_ptr, out) }
+    Yeptris::FFI.check_status(status, "yeptris_node_bool")
+    out.read_int != 0
+  end
+
+  TAGS = {
+    Yeptris::FFI::TAG_STR => :str,
+    Yeptris::FFI::TAG_INT => :int,
+    Yeptris::FFI::TAG_FLOAT => :float,
+    Yeptris::FFI::TAG_BOOL => :bool,
+    Yeptris::FFI::TAG_NULL => :null,
+    Yeptris::FFI::TAG_TIMESTAMP => :timestamp,
+  }.freeze
+
+  def tag_id
+    TAGS[alive { Yeptris::FFI.yeptris_node_tag_id(@c_ptr) }]
+  end
+
+  # ---- sequence access ----
+
+  def size
+    case kind
+    when :sequence then seq_count
+    when :mapping then map_count
+    else 1
+    end
+  end
+
+  def seq_count
+    alive { Yeptris::FFI.yeptris_node_seq_count(@c_ptr) }
+  end
+
+  def seq_at(index)
+    @document.wrap_node(alive { Yeptris::FFI.yeptris_node_seq_at(@c_ptr, index) })
+  end
+
+  def each
+    return enum_for(:each) unless block_given?
+    raise Yeptris::Error, "#each is for sequences" unless sequence?
+
+    (0...seq_count).each { |i| yield seq_at(i) }
+  end
+
+  # ---- mapping access ----
+
+  def map_count
+    alive { Yeptris::FFI.yeptris_node_map_count(@c_ptr) }
+  end
+
+  def [](key)
+    raise Yeptris::Error, "#[] is for mappings" unless mapping?
+
+    key = key.to_s
+    @document.wrap_node(
+      alive { Yeptris::FFI.yeptris_node_map_get(@c_ptr, key, key.bytesize) }
+    )
+  end
+
+  def key?(key)
+    !self[key].nil?
+  end
+
+  # Ordered [key, value] pairs.
+  def each_pair
+    return enum_for(:each_pair) unless block_given?
+    raise Yeptris::Error, "#each_pair is for mappings" unless mapping?
+
+    k = ::FFI::MemoryPointer.new(:pointer)
+    v = ::FFI::MemoryPointer.new(:pointer)
+    (0...map_count).each do |i|
+      rc = alive { Yeptris::FFI.yeptris_node_map_at(@c_ptr, i, k, v) }
+      next unless rc.zero?
+
+      yield @document.wrap_node(k.read_pointer), @document.wrap_node(v.read_pointer)
+    end
+  end
+
+  def keys
+    # explicit block: two-arg yield + Symbol#to_proc would call
+    # key.first(value) instead of taking the pair
+    each_pair.map { |k, _v| k }
+  end
+
+  # ---- construction (TODO.impl/11 phase 3; errors raise) ----
+
+  def map_add(key, node)
+    key = key.to_s
+    rc = alive { Yeptris::FFI.yeptris_node_map_add(@c_ptr, key, key.bytesize, node.c_ptr) }
+    Yeptris::FFI.check_status(rc, "yeptris_node_map_add")
+    self
+  end
+
+  def map_set(key, node)
+    key = key.to_s
+    rc = alive { Yeptris::FFI.yeptris_node_map_set(@c_ptr, key, key.bytesize, node.c_ptr) }
+    Yeptris::FFI.check_status(rc, "yeptris_node_map_set")
+    self
+  end
+
+  def map_del(key)
+    key = key.to_s
+    alive { Yeptris::FFI.yeptris_node_map_del(@c_ptr, key, key.bytesize) }.zero?
+  end
+
+  def seq_add(node)
+    rc = alive { Yeptris::FFI.yeptris_node_seq_add(@c_ptr, node.c_ptr) }
+    Yeptris::FFI.check_status(rc, "yeptris_node_seq_add")
+    self
+  end
+
+  # Props on synthesized nodes (15's YAMLTree); values copied in.
+  def set_anchor(name)
+    alive { Yeptris::FFI.yeptris_node_set_anchor(@c_ptr, name, name.bytesize) }.zero?
+  end
+
+  def set_tag(tag)
+    alive { Yeptris::FFI.yeptris_node_set_tag(@c_ptr, tag, tag.bytesize) }.zero?
+  end
+
+  def seq_del(index)
+    alive { Yeptris::FFI.yeptris_node_seq_del(@c_ptr, index) }.zero?
+  end
+
+  # ---- Ruby materialization (Psych-compatible) ----
+
+  # Materializes the subtree as native Ruby objects. Aliases preserve
+  # object identity (the same Ruby object for every reference), keys
+  # materialize with Psych's implicit typing (":sym" -> Symbol under
+  # compat), and the anchor memo makes cycles defined by anchors safe.
+  def node_id
+    alive { Yeptris::FFI.yeptris_node_id(@c_ptr) }
+  end
+
+  def to_ruby(memo = nil)
+    # readonly documents memoize per node: a second materialization
+    # returns the SAME object (the readonly cache is the ground truth
+    # for alias identity across calls).
+    if @document.readonly?
+      rm = @document.readonly_memo
+      cached = rm[node_id]
+      return cached if cached
+    end
+    # Marshal fast path (TODO.restructure/21): one C call turns the
+    # whole subtree into Ruby objects, preserving alias identity via
+    # the object's own object-link table. Only at the TOP-LEVEL entry
+    # (memo nil): inside a recursive walk a partial marshal would
+    # materialize outside the shared memo and break alias identity.
+    # Falls back to the per-node FFI walk on constructs the format
+    # cannot express (merge keys, timestamps) and on older builds.
+    if Yeptris::FFI::MARSHAL && memo.nil?
+      result =
+        begin
+          out_p = ::FFI::MemoryPointer.new(:pointer)
+          olen_p = ::FFI::MemoryPointer.new(:size_t)
+          st = Yeptris::FFI.yeptris_marshal_node(@c_ptr, out_p, olen_p)
+          if st == Yeptris::FFI::ERROR_UNSUPPORTED
+            nil
+          elsif st != Yeptris::FFI::OK
+            raise Yeptris::ParseError, Yeptris::FFI.last_error_message
+          else
+            buf = out_p.read_pointer
+            len = olen_p.read_uint64
+            bytes = buf.read_bytes(len)
+            bytes.force_encoding(Encoding::ASCII_8BIT)
+            ::Marshal.load(bytes)
+          end
+        ensure
+          Yeptris::FFI.yeptris_marshal_free(out_p.read_pointer) if out_p
+        end
+      unless result.nil?
+        @document.readonly_memo[node_id] = result if @document.readonly?
+        return result
+      end
+    end
+    if @document.readonly?
+      return @document.readonly_memo[node_id] = to_ruby_walk({})
+    end
+    to_ruby_walk(memo || {})
+  end
+
+  def to_ruby_walk(memo)
+    cached = memo[node_id]
+    return cached if cached
+
+    case kind
+    when :mapping
+      h = {}
+      memo[node_id] = h
+      each_pair do |k, v|
+        h[k.to_ruby_key] = v.to_ruby(memo)
+      end
+      h
+    when :sequence
+      a = []
+      memo[node_id] = a
+      each { |e| a << e.to_ruby(memo) }
+      a
+    when :alias
+      t = alias_target
+      t.nil? ? nil : t.to_ruby(memo)
+    else
+      scalar_to_ruby
+    end
+  end
+
+  # Mapping keys: Psych semantics — a plain scalar ":name" under the
+  # compat schema scans to a Symbol; everything else materializes as
+  # the scalar itself.
+  def to_ruby_key
+    symbol? ? symbolize : to_ruby
+  end
+
+  def scalar_to_ruby
+    return symbolize if symbol? && tag_id == :str
+
+    case tag_id
+    when :null then nil
+    when :bool then to_bool
+    when :int then to_i
+    when :float then to_f
+    when :timestamp then ::Yeptris::Materializer.parse_timestamp(value)
+    else value
+    end
+  end
+
+  # Psych's ScalarScanner: plain ":name" (and ":", the null Symbol)
+  # scans to a Symbol; quoting defeats it.
+  def symbol?
+    style == :plain && value&.start_with?(":") && !value.start_with?("::")
+  end
+
+  def symbolize
+    v = value
+    v.length <= 1 ? :"" : v[1..].to_sym
+  end
+
+
+
+  def alive
+    @document.ensure_alive!
+    yield
+  end
+end