dms-parser 0.5.0

data/lib/dms/tier1.rb

@@ -0,0 +1,1750 @@
+# frozen_string_literal: true
+
+# DMS Tier-1: decorators, dialect imports, and the tier-1 encoder.
+#
+# Entry points:
+#   Dms::Tier1.parse(src)  -> DocumentT1
+#
+# The tier-1 parser wraps the existing tier-0 parser, intercepting
+# decorator calls at leading/inner/trailing/flow-inner positions and
+# collecting them into a sidecar.
+
+require "json"
+
+module Dms
+  module Tier1
+    # Reserved decorator sigil characters (tier-0 set, no underscore).
+    # ! @ $ % ^ & * | ~ ` . , > < ? ; =
+    RESERVED_SIGIL_CHARS = "!@$%^&*|~`.,><?;=".chars.to_set.freeze
+
+    # ── Reserved Emoji Set helpers (frozen Unicode 15.1) ────────────────────
+
+    # Extended_Pictographic=Yes ranges (frozen UCD 15.1), sourced from Rust ref.
+    EXTENDED_PICTOGRAPHIC_RANGES = [
+      [0x00A9, 0x00A9], [0x00AE, 0x00AE], [0x203C, 0x203C], [0x2049, 0x2049],
+      [0x2122, 0x2122], [0x2139, 0x2139], [0x2194, 0x2199], [0x21A9, 0x21AA],
+      [0x231A, 0x231B], [0x2328, 0x2328], [0x2388, 0x2388], [0x23CF, 0x23CF],
+      [0x23E9, 0x23F3], [0x23F8, 0x23FA], [0x24C2, 0x24C2], [0x25AA, 0x25AB],
+      [0x25B6, 0x25B6], [0x25C0, 0x25C0], [0x25FB, 0x25FE], [0x2600, 0x2605],
+      [0x2607, 0x2612], [0x2614, 0x2685], [0x2690, 0x2705], [0x2708, 0x2712],
+      [0x2714, 0x2714], [0x2716, 0x2716], [0x271D, 0x271D], [0x2721, 0x2721],
+      [0x2728, 0x2728], [0x2733, 0x2734], [0x2744, 0x2744], [0x2747, 0x2747],
+      [0x274C, 0x274C], [0x274E, 0x274E], [0x2753, 0x2755], [0x2757, 0x2757],
+      [0x2763, 0x2767], [0x2795, 0x2797], [0x27A1, 0x27A1], [0x27B0, 0x27B0],
+      [0x27BF, 0x27BF], [0x2934, 0x2935], [0x2B05, 0x2B07], [0x2B1B, 0x2B1C],
+      [0x2B50, 0x2B50], [0x2B55, 0x2B55], [0x3030, 0x3030], [0x303D, 0x303D],
+      [0x3297, 0x3297], [0x3299, 0x3299], [0x1F000, 0x1F0FF], [0x1F10D, 0x1F10F],
+      [0x1F12F, 0x1F12F], [0x1F16C, 0x1F171], [0x1F17E, 0x1F17F], [0x1F18E, 0x1F18E],
+      [0x1F191, 0x1F19A], [0x1F1AD, 0x1F1E5], [0x1F201, 0x1F20F], [0x1F21A, 0x1F21A],
+      [0x1F22F, 0x1F22F], [0x1F232, 0x1F23A], [0x1F23C, 0x1F23F], [0x1F249, 0x1F3FA],
+      [0x1F400, 0x1F53D], [0x1F546, 0x1F64F], [0x1F680, 0x1F6FF], [0x1F774, 0x1F77F],
+      [0x1F7D5, 0x1F7FF], [0x1F80C, 0x1F80F], [0x1F848, 0x1F84F], [0x1F85A, 0x1F85F],
+      [0x1F888, 0x1F88F], [0x1F8AE, 0x1F8FF], [0x1F90C, 0x1F93A], [0x1F93C, 0x1F945],
+      [0x1F947, 0x1FAFF], [0x1FC00, 0x1FFFD],
+    ].freeze
+
+    def self.extended_pictographic?(cp)
+      return false if cp < 0xA9
+      lo = 0
+      hi = EXTENDED_PICTOGRAPHIC_RANGES.length - 1
+      while lo <= hi
+        mid = (lo + hi) / 2
+        range_lo, range_hi = EXTENDED_PICTOGRAPHIC_RANGES[mid]
+        if cp < range_lo
+          hi = mid - 1
+        elsif cp > range_hi
+          lo = mid + 1
+        else
+          return true
+        end
+      end
+      false
+    end
+
+    def self.reserved_emoji_codepoint?(cp)
+      return true if cp >= 0x1F1E6 && cp <= 0x1F1FF  # regional indicator
+      return true if cp >= 0x1F3FB && cp <= 0x1F3FF  # skin-tone modifier
+      return true if cp == 0x20E3                      # keycap combiner
+      extended_pictographic?(cp)
+    end
+
+    def self.regional_indicator?(cp)
+      cp >= 0x1F1E6 && cp <= 0x1F1FF
+    end
+
+    def self.emoji_modifier?(cp)
+      cp >= 0x1F3FB && cp <= 0x1F3FF
+    end
+
+    # Read one extended grapheme cluster of reserved-emoji shape starting
+    # at byte offset `start` in `s` (UTF-8 string). Returns the exclusive
+    # end byte offset, or nil if no emoji cluster starts here.
+    # Algorithm mirrors Rust read_reserved_emoji_atom exactly.
+    def self.read_reserved_emoji_atom(s, start)
+      return nil if start >= s.bytesize
+      # Decode first codepoint
+      sub = s.byteslice(start, s.bytesize - start)
+      return nil if sub.nil? || sub.empty?
+      sub = sub.force_encoding("UTF-8")
+      c0 = sub[0]
+      return nil if c0.nil?
+      cp0 = c0.ord
+      return nil unless reserved_emoji_codepoint?(cp0)
+      len0 = c0.bytesize
+      end_pos = start + len0
+
+      # Regional-indicator pair (GB12/GB13)
+      if regional_indicator?(cp0)
+        rest = s.byteslice(end_pos, s.bytesize - end_pos)
+        if rest && !rest.empty?
+          rest = rest.force_encoding("UTF-8")
+          c1 = rest[0]
+          if c1 && regional_indicator?(c1.ord)
+            end_pos += c1.bytesize
+          end
+        end
+        return end_pos
+      end
+
+      # GB9/GB9a/GB11 loop
+      loop do
+        rest = s.byteslice(end_pos, s.bytesize - end_pos)
+        break if rest.nil? || rest.empty?
+        rest = rest.force_encoding("UTF-8")
+        c = rest[0]
+        break if c.nil?
+        cp = c.ord
+        if emoji_modifier?(cp) || cp == 0xFE0F || cp == 0x20E3
+          # GB9/GB9a - Extend or SpacingMark
+          end_pos += c.bytesize
+          next
+        end
+        if cp == 0x200D
+          # GB11 - ZWJ x Extended_Pictographic
+          after_zwj = end_pos + c.bytesize
+          after = s.byteslice(after_zwj, s.bytesize - after_zwj)
+          if after && !after.empty?
+            after = after.force_encoding("UTF-8")
+            nc = after[0]
+            if nc && extended_pictographic?(nc.ord)
+              end_pos = after_zwj + nc.bytesize
+              next
+            end
+          end
+          # ZWJ not followed by E_P: cluster ends before ZWJ
+          break
+        end
+        break
+      end
+      end_pos
+    end
+
+    # Returns true if the character at byte offset `pos` in UTF-8 string `s`
+    # starts a sigil atom (ASCII reserved char OR reserved emoji codepoint).
+    def self.sigil_atom_start_at?(s, pos)
+      return false if pos >= s.bytesize
+      b = s.getbyte(pos)
+      return false if b.nil?
+      # ASCII reserved sigil
+      return true if RESERVED_SIGIL_CHARS.include?(b.chr)
+      # Multi-byte: check if it's a reserved emoji codepoint
+      return false if b < 0x80
+      sub = s.byteslice(pos, s.bytesize - pos)
+      return false if sub.nil? || sub.empty?
+      sub = sub.force_encoding("UTF-8")
+      c = sub[0]
+      return false if c.nil?
+      reserved_emoji_codepoint?(c.ord)
+    end
+
+    # Lex one sigil atom at byte offset `pos` in UTF-8 string `s`.
+    # Returns byte-length of the atom (1 for ASCII, cluster len for emoji),
+    # or nil if no sigil atom here.
+    def self.lex_sigil_atom_at(s, pos)
+      return nil if pos >= s.bytesize
+      b = s.getbyte(pos)
+      return nil if b.nil?
+      # ASCII reserved sigil char
+      if b < 0x80
+        return RESERVED_SIGIL_CHARS.include?(b.chr) ? 1 : nil
+      end
+      # Multi-byte: try emoji cluster
+      end_pos = read_reserved_emoji_atom(s, pos)
+      return nil if end_pos.nil?
+      end_pos - pos
+    end
+
+    # Validate that a sigil string consists of valid sigil atoms only.
+    # Returns nil on success, error message string on failure.
+    def self.validate_sigil_atoms(sigil, idx)
+      s = sigil.encode("UTF-8") rescue sigil
+      pos = 0
+      while pos < s.bytesize
+        atom_len = lex_sigil_atom_at(s, pos)
+        if atom_len.nil?
+          # Decode the char at pos for the error message
+          sub = s.byteslice(pos, s.bytesize - pos).force_encoding("UTF-8")
+          c = sub[0] || "?"
+          if c == "_"
+            return "_dms_imports[#{idx}].bind key \"#{sigil}\" (or containing '_') " \
+              "is invalid: underscore is not in the tier-0 reserved decorator sigil set"
+          end
+          return "_dms_imports[#{idx}].bind key \"#{sigil}\" contains '#{c}' " \
+            "which is not in the tier-0 reserved decorator sigil set " \
+            "nor in the Reserved Emoji Set"
+        end
+        pos += atom_len
+      end
+      nil
+    end
+
+    # ── Import types ────────────────────────────────────────────────────────
+
+    ImportSpec = Struct.new(:dialect, :version, :ns, :bind, :allow, :deny, :alias_map,
+                            keyword_init: true)
+
+    # ── Sidecar types ───────────────────────────────────────────────────────
+
+    # path: Array of {key: String} or {index: Integer} hashes (JSON-ready)
+    # calls: Hash sigil => Array of DecoratorCall
+    # comments: Array (always empty in this implementation)
+    DecoratorEntry = Struct.new(:path, :calls, :comments)
+
+    # family: String (canonical family name, "" if unresolved)
+    # fn_name: String (post-alias-resolution function name)
+    # ns: String or nil
+    # position: :leading, :inner, :trailing, :floating
+    # params: Array of ParamGroup
+    # params_dec: Array (always empty in this implementation)
+    # sigil: String (the literal sigil string)
+    DecoratorCall = Struct.new(:sigil, :family, :fn_name, :ns, :position, :params, :params_dec)
+
+    # kind: :named or :positional
+    # value: Hash (for named) or Array (for positional)
+    ParamGroup = Struct.new(:kind, :value)
+
+    # ── Tier-1 document ─────────────────────────────────────────────────────
+
+    class DocumentT1
+      attr_reader :t0, :decorators, :imports, :observed_tier
+
+      def initialize(t0, decorators, imports, observed_tier)
+        @t0 = t0
+        @decorators = decorators
+        @imports = imports       # Array of ImportSpec
+        @observed_tier = observed_tier
+      end
+    end
+
+    # ── Semver helpers ──────────────────────────────────────────────────────
+
+    RANGE_SPECIFIER_PREFIXES = %w[^ ~ >= > < <= =].freeze
+
+    def self.valid_semver?(s)
+      # Drop build metadata
+      s = s.split("+", 2).first
+      # Split pre-release
+      core_str, pre_str = s.split("-", 2)
+      parts = core_str.split(".", -1)
+      return false unless parts.length == 3
+      parts.each do |p|
+        return false if p.empty?
+        return false if p.length > 1 && p.start_with?("0")
+        return false unless p.match?(/\A\d+\z/)
+      end
+      if pre_str
+        return false if pre_str.empty?
+        pre_str.split(".").each do |id|
+          return false if id.empty?
+          if id.match?(/\A\d+\z/)
+            return false if id.length > 1 && id.start_with?("0")
+          else
+            return false unless id.match?(/\A[A-Za-z0-9\-]+\z/)
+          end
+        end
+      end
+      true
+    end
+
+    def self.has_range_specifier?(s)
+      trimmed = s.lstrip
+      RANGE_SPECIFIER_PREFIXES.any? { |p| trimmed.start_with?(p) }
+    end
+
+    # ── Import extraction and validation ────────────────────────────────────
+
+    def self.extract_imports(meta)
+      raw_list = meta["_dms_imports"]
+      return [] if raw_list.nil?
+
+      unless raw_list.is_a?(Array)
+        raise DecodeError.new(0, 0, "_dms_imports must be a list")
+      end
+
+      specs = []
+      # Seen (sigil, ns_repr, family) triples for collision detection
+      seen_triples = {}
+
+      raw_list.each_with_index do |entry, idx|
+        unless entry.is_a?(Hash)
+          raise DecodeError.new(0, 0, "_dms_imports[#{idx}] must be a table")
+        end
+
+        # dialect (required string)
+        dialect = entry["dialect"]
+        case dialect
+        when nil
+          raise DecodeError.new(0, 0, "_dms_imports[#{idx}] is missing required field 'dialect'")
+        when String
+          raise DecodeError.new(0, 0, "_dms_imports[#{idx}].dialect must be a non-empty string") if dialect.empty?
+        else
+          raise DecodeError.new(0, 0, "_dms_imports[#{idx}].dialect must be a string")
+        end
+
+        # version (required string, semver, no range specifiers)
+        version = entry["version"]
+        case version
+        when nil
+          raise DecodeError.new(0, 0, "_dms_imports[#{idx}] is missing required field 'version'")
+        when String
+          raise DecodeError.new(0, 0, "_dms_imports[#{idx}].version must be a non-empty string") if version.empty?
+          if has_range_specifier?(version)
+            raise DecodeError.new(0, 0,
+              "range-specifier syntax in version not supported " \
+              "(_dms_imports[#{idx}].version \"#{version}\"): write a plain semver string")
+          end
+          unless valid_semver?(version)
+            raise DecodeError.new(0, 0,
+              "_dms_imports[#{idx}].version \"#{version}\" is not a valid semver string " \
+              "(expected MAJOR.MINOR.PATCH with optional -pre and +build)")
+          end
+        else
+          raise DecodeError.new(0, 0, "_dms_imports[#{idx}].version must be a string")
+        end
+
+        # ns (optional string)
+        ns_val = entry["ns"]
+        ns = case ns_val
+             when nil then nil
+             when String
+               raise DecodeError.new(0, 0, "_dms_imports[#{idx}].ns must be a non-empty string when present") if ns_val.empty?
+               ns_val
+             else
+               raise DecodeError.new(0, 0, "_dms_imports[#{idx}].ns must be a string")
+             end
+
+        # bind (optional table: sigil → list of family names)
+        bind = {}
+        if (bind_val = entry["bind"])
+          unless bind_val.is_a?(Hash)
+            raise DecodeError.new(0, 0, "_dms_imports[#{idx}].bind must be a table")
+          end
+          bind_val.each do |sigil, families_val|
+            if sigil.empty?
+              raise DecodeError.new(0, 0, "_dms_imports[#{idx}].bind has an empty sigil key")
+            end
+            err = Tier1.validate_sigil_atoms(sigil, idx)
+            raise DecodeError.new(0, 0, err) if err
+            unless families_val.is_a?(Array)
+              raise DecodeError.new(0, 0,
+                "_dms_imports[#{idx}].bind[\"#{sigil}\"] must be a list " \
+                "(use list form even for a single family)")
+            end
+            names = families_val.map do |item|
+              unless item.is_a?(String)
+                raise DecodeError.new(0, 0, "_dms_imports[#{idx}].bind[\"#{sigil}\"] must be a list of strings")
+              end
+              item
+            end
+            bind[sigil] = names
+          end
+        end
+
+        # allow (optional table: family → list of names)
+        allow_map = {}
+        if (allow_val = entry["allow"])
+          unless allow_val.is_a?(Hash)
+            raise DecodeError.new(0, 0, "_dms_imports[#{idx}].allow must be a table")
+          end
+          allow_val.each do |family, names_val|
+            allow_map[family] = extract_string_list(names_val, idx, "allow", family)
+          end
+        end
+
+        # deny (optional table: family → list of names)
+        deny_map = {}
+        if (deny_val = entry["deny"])
+          unless deny_val.is_a?(Hash)
+            raise DecodeError.new(0, 0, "_dms_imports[#{idx}].deny must be a table")
+          end
+          deny_val.each do |family, names_val|
+            deny_map[family] = extract_string_list(names_val, idx, "deny", family)
+          end
+        end
+
+        # allow/deny mutual exclusion
+        allow_map.each_key do |family|
+          if deny_map.key?(family)
+            raise DecodeError.new(0, 0,
+              "_dms_imports[#{idx}]: family \"#{family}\" appears in both " \
+              "'allow' and 'deny' — they are mutually exclusive for the same family")
+          end
+        end
+
+        # alias (optional table: family → table: alias → canonical)
+        alias_map = {}
+        if (alias_val = entry["alias"])
+          unless alias_val.is_a?(Hash)
+            raise DecodeError.new(0, 0, "_dms_imports[#{idx}].alias must be a table")
+          end
+          alias_val.each do |family, inner_val|
+            unless inner_val.is_a?(Hash)
+              raise DecodeError.new(0, 0,
+                "_dms_imports[#{idx}].alias[\"#{family}\"] must be a table (alias → canonical)")
+            end
+            inner_map = {}
+            inner_val.each do |alias_name, canonical_val|
+              unless canonical_val.is_a?(String)
+                raise DecodeError.new(0, 0,
+                  "_dms_imports[#{idx}].alias[\"#{family}\"][\"#{alias_name}\"] must be a string")
+              end
+              inner_map[alias_name] = canonical_val
+            end
+            alias_map[family] = inner_map
+          end
+        end
+
+        # Cross-import collision detection
+        ns_repr = ns || "<unset>"
+        bind.each do |sigil, families|
+          families.each do |family|
+            triple_key = "#{sigil}|#{ns_repr}|#{family}"
+            if (prev_idx = seen_triples[triple_key])
+              prev = specs[prev_idx]
+              raise DecodeError.new(0, 0,
+                "Decorator binding collision on (sigil='#{sigil}', ns=#{ns_repr}, " \
+                "family='#{family}'): " \
+                "import ##{prev_idx} dialect '#{prev.dialect}' v#{prev.version} and " \
+                "import ##{idx} dialect '#{dialect}' v#{version} both bind " \
+                "'#{sigil}' → '#{family}'. Resolve by remapping one.")
+            end
+            seen_triples[triple_key] = idx
+          end
+        end
+
+        specs << ImportSpec.new(
+          dialect: dialect,
+          version: version,
+          ns: ns,
+          bind: bind,
+          allow: allow_map,
+          deny: deny_map,
+          alias_map: alias_map
+        )
+      end
+
+      specs
+    end
+
+    def self.extract_string_list(val, idx, field, family)
+      unless val.is_a?(Array)
+        raise DecodeError.new(0, 0, "_dms_imports[#{idx}].#{field}[\"#{family}\"] must be a list")
+      end
+      val.map do |item|
+        unless item.is_a?(String)
+          raise DecodeError.new(0, 0, "_dms_imports[#{idx}].#{field}[\"#{family}\"] must be a list of strings")
+        end
+        item
+      end
+    end
+
+    # ── Family resolution ────────────────────────────────────────────────────
+
+    # Resolve a decorator call's family from imports.
+    # Returns [family_name, canonical_fn_name] or raises.
+    # Also applies deny-list check.
+    def self.resolve_family(sigil, fn_name, ns, imports)
+      # Filter imports by ns if specified
+      candidate_imports = if ns
+                            filtered = imports.select { |imp| imp.ns == ns }
+                            if filtered.empty?
+                              raise DecodeError.new(0, 0, "unknown namespace '#{ns}'")
+                            end
+                            filtered
+                          else
+                            imports
+                          end
+
+      # For each import, check families bound to this sigil
+      # Apply aliases and allow/deny rules
+      accepted = []  # [family_name, canonical_fn_name]
+
+      candidate_imports.each do |imp|
+        families = imp.bind[sigil]
+        next unless families
+
+        families.each do |family|
+          # Apply alias: fn_name might be an alias
+          canonical =
+            if (family_aliases = imp.alias_map[family])
+              family_aliases[fn_name] || fn_name
+            else
+              fn_name
+            end
+
+          # Apply deny list
+          if (deny_list = imp.deny[family])
+            next if deny_list.include?(canonical)
+          end
+
+          # Apply allow list
+          if (allow_list = imp.allow[family])
+            next unless allow_list.include?(canonical)
+          end
+
+          accepted << [family, canonical]
+        end
+      end
+
+      if accepted.empty?
+        # Check if sigil is bound at all in any import
+        sigil_bound = candidate_imports.any? { |imp| imp.bind.key?(sigil) }
+        unless sigil_bound
+          raise DecodeError.new(0, 0,
+            "name '#{fn_name}' not found in any family bound to sigil '#{sigil}'")
+        end
+        # Sigil IS bound but fn_name was filtered out (denied or not allowed).
+        # Check deny against all imports for the deny_rejected test.
+        candidate_imports.each do |imp|
+          families = imp.bind[sigil]
+          next unless families
+          families.each do |family|
+            canonical = fn_name
+            if (family_aliases = imp.alias_map[family])
+              canonical = family_aliases[fn_name] || fn_name
+            end
+            if (deny_list = imp.deny[family])
+              if deny_list.include?(canonical)
+                raise DecodeError.new(0, 0,
+                  "decorator '#{fn_name}' is denied by family '#{family}' deny list")
+              end
+            end
+          end
+        end
+        # Filtered by allow list — also an error
+        raise DecodeError.new(0, 0,
+          "name '#{fn_name}' not found in any family bound to sigil '#{sigil}'")
+      end
+
+      # Use first accepted
+      accepted.first
+    end
+
+    # ── Tier-1 parser ────────────────────────────────────────────────────────
+
+    # Parse a DMS source string in tier-1 mode.
+    # Returns DocumentT1.
+    def self.parse(src)
+      T1Parser.new(src).parse
+    end
+
+    class T1Parser
+      # Byte constants (reused from Parser)
+      SP   = 0x20
+      TAB  = 0x09
+      LF   = 0x0A
+      CR   = 0x0D
+      LBRACK = 0x5B
+      RBRACK = 0x5D
+      LBRACE = 0x7B
+      RBRACE = 0x7D
+      LPAREN = 0x28  # '('
+      RPAREN = 0x29  # ')'
+      COMMA  = 0x2C
+      DOT    = 0x2E
+      PLUS   = 0x2B
+      COLON  = 0x3A
+      DQUOTE = 0x22
+      SQUOTE = 0x27
+      UNDERSCORE = 0x5F
+      DIGIT0 = 0x30
+      DIGIT9 = 0x39
+      LOWER_A = 0x61
+      LOWER_Z = 0x7A
+      UPPER_A = 0x41
+      UPPER_Z = 0x5A
+      MINUS  = 0x2D
+      HASH   = 0x23
+
+      BARE_KEY_BYTE = Array.new(256, false)
+      (DIGIT0..DIGIT9).each { |b| BARE_KEY_BYTE[b] = true }
+      (LOWER_A..LOWER_Z).each { |b| BARE_KEY_BYTE[b] = true }
+      (UPPER_A..UPPER_Z).each { |b| BARE_KEY_BYTE[b] = true }
+      BARE_KEY_BYTE[UNDERSCORE] = true
+      BARE_KEY_BYTE[MINUS] = true
+      BARE_KEY_BYTE.freeze
+
+      RESERVED_SIGIL_BYTE = Array.new(256, false)
+      "!@$%^&*|~`.,><?;=".each_byte { |b| RESERVED_SIGIL_BYTE[b] = true }
+      RESERVED_SIGIL_BYTE.freeze
+
+      # True if the position `pos` in @src starts a sigil atom:
+      # either an ASCII reserved sigil char or a reserved-emoji codepoint.
+      def sigil_at?(pos)
+        return false if pos >= @len
+        b = @src.getbyte(pos)
+        return false if b.nil?
+        return true if RESERVED_SIGIL_BYTE[b]
+        return false if b < 0x80
+        Tier1.sigil_atom_start_at?(@src, pos)
+      end
+
+      def initialize(src)
+        @src_original = src
+        @decorators = []    # Array of DecoratorEntry (sidecar)
+        @imports = []
+        @observed_tier = 0
+      end
+
+      def parse
+        # Step 1: Pre-scan to detect tier without triggering the tier-1 rejection.
+        tier = detect_tier(@src_original)
+
+        # If tier-0 input, wrap as tier-0 result
+        if tier == 0
+          doc = Dms::Parser.parse_document(@src_original)
+          return DocumentT1.new(doc, [], [], 0)
+        end
+
+        @observed_tier = tier
+
+        # Tier-1 parse: handle _dms_tier: 1 in front matter and parse decorators.
+        parse_tier1_document
+      end
+
+      # Quick scan for _dms_tier value without full parse.
+      def detect_tier(src)
+        # Look for _dms_tier in front matter using a regex-like scan.
+        # Only look inside the +++ ... +++ block.
+        s = src.dup.force_encoding("UTF-8")
+        m = s.match(/\A\s*\+\+\+[^\n]*\n(.*?)\n\+\+\+/m)
+        return 0 unless m
+        fm_content = m[1]
+        m2 = fm_content.match(/^_dms_tier\s*:\s*(\d+)/)
+        return 0 unless m2
+        m2[1].to_i
+      end
+
+      private
+
+      def parse_tier1_document
+        src = @src_original.dup
+        if src.encoding == Encoding::ASCII_8BIT || src.encoding == Encoding::BINARY
+          src.force_encoding("UTF-8")
+        elsif src.encoding != Encoding::UTF_8
+          src = src.encode("UTF-8")
+        end
+        src = src.unicode_normalize(:nfc) unless src.ascii_only?
+
+        @src = src
+        @len = src.bytesize
+        @pos = 0
+        @line = 1
+        @line_start = 0
+
+        # Parse front matter using the existing parser
+        # We need a "tier-1-accepting" parse. We'll re-parse using our own
+        # front matter reader that accepts tier=1.
+        meta_raw, meta_hash = parse_front_matter_accepting_t1
+        @imports = Tier1.extract_imports(meta_hash)
+
+        # Parse body with decorator awareness
+        body, decorators = parse_t1_body
+
+        # Build a tier-0 Document meta (only non-_ keys, nil when none)
+        meta_for_doc = {}
+        meta_hash.each do |k, v|
+          meta_for_doc[k] = v unless k.start_with?("_")
+        end
+        meta_final = meta_for_doc.empty? ? nil : meta_for_doc
+
+        doc = Document.new(meta_final, body, [], [])
+        DocumentT1.new(doc, decorators, @imports, 1)
+      end
+
+      def parse_front_matter_accepting_t1
+        skip_trivia
+        # No front matter
+        unless starts_bytes?("+++")
+          return [nil, {}]
+        end
+
+        opener_line = @line
+        @pos += 3
+        skip_inline_ws
+        unless consume_eol || eof?
+          raise DecodeError.new(@line, col, "front matter opener must be on its own line")
+        end
+
+        inner_buf = +""
+        inner_buf.force_encoding("UTF-8")
+        loop do
+          if eof?
+            raise DecodeError.new(opener_line, 1, "unterminated front matter: missing closing '+++'")
+          end
+          line_begin = @pos
+          while @pos < @len
+            b = @src.getbyte(@pos)
+            break if b == LF || b == CR
+            @pos += 1
+          end
+          line_text = @src.byteslice(line_begin, @pos - line_begin).force_encoding("UTF-8")
+          if line_text.strip == "+++"
+            consume_eol
+            break
+          end
+          inner_buf << line_text
+          inner_buf << "\n" if consume_eol
+        end
+
+        # Parse inner_buf using tier-0 parser but accepting _dms_tier: 1 and _dms_imports
+        sub_parser = Dms::Parser.new(inner_buf, lite: true)
+        table = sub_parser.parse_body_as_table
+
+        # Validate the meta keys: allow _dms_tier (1) and _dms_imports
+        meta_hash = {}
+        table.each do |k, v|
+          if k == "_dms_tier"
+            unless v.is_a?(Integer) && !v.is_a?(TrueClass) && !v.is_a?(FalseClass)
+              raise DecodeError.new(opener_line, 1, "_dms_tier must be a non-negative integer")
+            end
+            raise DecodeError.new(opener_line, 1, "_dms_tier must be non-negative") if v < 0
+            meta_hash[k] = v
+          elsif k == "_dms_imports"
+            meta_hash[k] = v
+          elsif k.start_with?("_")
+            raise DecodeError.new(opener_line, 1, "unknown reserved key: #{k}")
+          else
+            meta_hash[k] = v
+          end
+        end
+
+        [table, meta_hash]
+      end
+
+      # Parse the document body, collecting decorator calls into @decorators.
+      # Returns [body_value, decorator_entries]
+      def parse_t1_body
+        @dec_entries = {}  # path_key => DecoratorEntry (path as array)
+        @pending_leading = []  # Array of [sigil, fn_name, ns, params] for next value
+
+        skip_trivia
+        if eof?
+          return [{}, []]
+        end
+
+        b = @src.getbyte(@pos)
+
+        # Check for leading decorators (sigil at line start)
+        if sigil_at?(@pos)
+          # Collect leading decorators
+          collect_leading_decorators([])
+          skip_trivia
+        end
+
+        if eof?
+          return [{}, []]
+        end
+
+        b = @src.getbyte(@pos)
+        if b == PLUS && peek_after_plus?
+          # List root
+          body = parse_t1_list_block(0, [])
+        else
+          # Table root
+          body = parse_t1_table_block(0, [])
+        end
+
+        [body, @dec_entries.values]
+      end
+
+      # Collect leading decorator calls at the current position.
+      # path: the path for the NEXT value (to be determined after we see the key)
+      # But we don't know the next key yet — so we store them as pending.
+      def collect_leading_decorators(path_prefix)
+        while !eof? && sigil_at?(@pos)
+          sigil, fn_name, ns, params = parse_decorator_call
+          @pending_leading << { sigil: sigil, fn_name: fn_name, ns: ns, params: params }
+          skip_trivia_no_consume_leading
+          break if eof?
+          # Check if next line also starts with a sigil
+          break unless sigil_at?(@pos)
+        end
+      end
+
+      def skip_trivia_no_consume_leading
+        # Skip whitespace and comments but stop at sigil lines
+        loop do
+          skip_inline_ws
+          b = @src.getbyte(@pos)
+          if b == LF
+            @pos += 1; advance_line
+          elsif b == CR && @src.getbyte(@pos + 1) == LF
+            @pos += 2; advance_line
+          elsif b == HASH
+            skip_line_comment
+          elsif b == 0x2F && @src.getbyte(@pos + 1) == 0x2F
+            skip_line_comment
+          elsif b == 0x2F && @src.getbyte(@pos + 1) == 0x2A
+            skip_block_comment
+          else
+            break
+          end
+        end
+      end
+
+      def parse_t1_table_block(indent, path_prefix)
+        t = {}
+        loop do
+          skip_trivia
+          break if eof?
+
+          # Measure indent
+          li = measure_line_indent
+          break if li < indent
+
+          if li != indent
+            raise DecodeError.new(@line, col, "inconsistent indent: expected #{indent} spaces, got #{li}")
+          end
+          @pos = @line_start + indent
+
+          b = @src.getbyte(@pos)
+
+          # Leading decorators (sigil at line start)
+          if sigil_at?(@pos)
+            # Collect leading decorators for next value
+            loop do
+              sigil, fn_name, ns, params = parse_decorator_call
+              @pending_leading << { sigil: sigil, fn_name: fn_name, ns: ns, params: params }
+              # After decorator call, consume rest of line
+              skip_inline_ws
+              if consume_eol || eof?
+                # next line
+              end
+              skip_trivia
+              break if eof?
+              li2 = measure_line_indent
+              break if li2 < indent
+              if li2 != indent
+                raise DecodeError.new(@line, col, "inconsistent indent")
+              end
+              @pos = @line_start + indent
+              break unless sigil_at?(@pos)
+            end
+            next
+          end
+
+          break if b.nil?
+          break if b == PLUS && peek_after_plus?
+
+          # Must be a key-value pair
+          key = parse_key_t1
+          raise DecodeError.new(@line, col, "expected ':' after key") if @src.getbyte(@pos) != COLON
+          @pos += 1  # consume ':'
+
+          current_path = path_prefix + [{ "key" => key }]
+          path_key = path_to_key(current_path)
+
+          # Flush pending leading decorators onto this key's path
+          unless @pending_leading.empty?
+            pending = @pending_leading.dup
+            @pending_leading.clear
+            pending.each do |dec|
+              family, canonical_fn = resolve_call(dec[:sigil], dec[:fn_name], dec[:ns])
+              add_decorator_call(current_path, dec[:sigil], family, canonical_fn, dec[:ns], :leading, dec[:params])
+            end
+          end
+
+          b = @src.getbyte(@pos)
+          if b == SP || b == TAB
+            @pos += 1
+            skip_inline_ws
+            nb = @src.getbyte(@pos)
+            if nb.nil? || nb == LF || nb == CR
+              # Block value follows
+              consume_eol
+              skip_trivia
+              raise DecodeError.new(@line, col, "expected indented child block") if eof?
+              child_indent = measure_line_indent
+              raise DecodeError.new(@line, col, "expected indented child block") if child_indent <= indent
+              v = parse_t1_block_value(child_indent, current_path)
+              t[key] = v
+            elsif sigil_at?(@pos)
+              # Inner decorator(s)
+              v, has_value = parse_t1_inner_and_value(current_path)
+              t[key] = v
+              # Consume rest of line (trailing decorators already consumed in parse_t1_inner_and_value)
+              skip_inline_ws
+              consume_eol
+            else
+              # Inline value, possibly followed by trailing decorators
+              v = parse_t1_inline_value(current_path)
+              skip_inline_ws
+              # Check for trailing decorators
+              if sigil_at?(@pos)
+                parse_t1_trailing_decorators(current_path)
+              end
+              skip_inline_ws
+              consume_eol
+              t[key] = v
+            end
+          elsif b.nil? || b == LF || b == CR
+            consume_eol
+            skip_trivia
+            raise DecodeError.new(@line, col, "expected indented child block") if eof?
+            child_indent = measure_line_indent
+            raise DecodeError.new(@line, col, "expected indented child block") if child_indent <= indent
+            v = parse_t1_block_value(child_indent, current_path)
+            t[key] = v
+          else
+            raise DecodeError.new(@line, col, "expected whitespace after ':'")
+          end
+
+          raise DecodeError.new(@line, col, "duplicate key: #{key}") if t.key?(key) && t[key] != v
+          t[key] = v
+        end
+        t
+      end
+
+      def parse_t1_list_block(indent, path_prefix)
+        items = []
+        loop do
+          skip_trivia
+          break if eof?
+          li = measure_line_indent
+          break if li < indent
+          if li != indent
+            raise DecodeError.new(@line, col, "inconsistent indent: expected #{indent} spaces, got #{li}")
+          end
+          @pos = @line_start + indent
+          break unless @src.getbyte(@pos) == PLUS && peek_after_plus?
+
+          idx = items.length
+          current_path = path_prefix + [{ "index" => idx }]
+          @pos += 1  # consume '+'
+
+          b = @src.getbyte(@pos)
+          if b == SP || b == TAB
+            @pos += 1
+            skip_inline_ws
+            nb = @src.getbyte(@pos)
+            if nb.nil? || nb == LF || nb == CR
+              consume_eol
+              skip_trivia
+              raise DecodeError.new(@line, col, "expected indented block after empty '+' marker") if eof?
+              inner_indent = measure_line_indent
+              raise DecodeError.new(@line, col, "expected indented block") if inner_indent <= indent
+              v = parse_t1_block_value(inner_indent, current_path)
+            elsif sigil_at?(@pos)
+              v, _ = parse_t1_inner_and_value(current_path)
+              skip_inline_ws; consume_eol
+            else
+              v = parse_t1_list_item_value(indent, current_path)
+            end
+          elsif b.nil? || b == LF || b == CR
+            consume_eol
+            skip_trivia
+            raise DecodeError.new(@line, col, "expected indented block after empty '+' marker") if eof?
+            inner_indent = measure_line_indent
+            raise DecodeError.new(@line, col, "expected indented block") if inner_indent <= indent
+            v = parse_t1_block_value(inner_indent, current_path)
+          else
+            raise DecodeError.new(@line, col, "expected space after '+'")
+          end
+
+          items << v
+        end
+        items
+      end
+
+      def parse_t1_block_value(indent, path_prefix)
+        @pos = @line_start + indent
+        if @src.getbyte(@pos) == PLUS && peek_after_plus?
+          return parse_t1_list_block(indent, path_prefix)
+        end
+        parse_t1_table_block(indent, path_prefix)
+      end
+
+      def parse_t1_list_item_value(list_indent, path_prefix)
+        # Check if it's a kv pair
+        if line_starts_kvpair_t1?
+          key = parse_key_t1
+          raise DecodeError.new(@line, col, "expected ':' after key") if @src.getbyte(@pos) != COLON
+          @pos += 1
+          current_path = path_prefix + [{ "key" => key }]
+          b = @src.getbyte(@pos)
+          if b == SP || b == TAB
+            @pos += 1; skip_inline_ws
+            nb = @src.getbyte(@pos)
+            if nb.nil? || nb == LF || nb == CR
+              consume_eol; skip_trivia
+              raise DecodeError.new(@line, col, "expected indented child block") if eof?
+              child_indent = measure_line_indent
+              raise DecodeError.new(@line, col, "expected indented child block") if child_indent <= list_indent
+              v = parse_t1_block_value(child_indent, current_path)
+            elsif sigil_at?(@pos)
+              v, _ = parse_t1_inner_and_value(current_path)
+              skip_inline_ws; consume_eol
+            else
+              v = parse_t1_inline_value(current_path)
+              skip_inline_ws
+              parse_t1_trailing_decorators(current_path) if sigil_at?(@pos)
+              skip_inline_ws; consume_eol
+            end
+          elsif b.nil? || b == LF || b == CR
+            consume_eol; skip_trivia
+            child_indent = measure_line_indent
+            raise DecodeError.new(@line, col, "expected indented child block") if child_indent <= list_indent
+            v = parse_t1_block_value(child_indent, current_path)
+          else
+            raise DecodeError.new(@line, col, "expected whitespace after ':'")
+          end
+          t = { key => v }
+          # Continue reading sibling kv pairs at same indent
+          key_col = current_path.last["key"] ? (list_indent + 2) : list_indent
+          # Simple single-item table for list item
+          return t
+        end
+        # Scalar or flow value
+        v = parse_t1_inline_value(path_prefix)
+        skip_inline_ws
+        parse_t1_trailing_decorators(path_prefix) if sigil_at?(@pos)
+        skip_inline_ws; consume_eol
+        v
+      end
+
+      # Parse inner decorator(s) followed optionally by a value.
+      # Returns [value, has_explicit_value]
+      # Position: already past `key: ` whitespace, sitting on sigil.
+      def parse_t1_inner_and_value(path)
+        # Collect all consecutive inner decorator calls
+        while !eof? && sigil_at?(@pos)
+          sigil, fn_name, ns, params = parse_decorator_call
+          family, canonical_fn = resolve_call(sigil, fn_name, ns)
+          add_decorator_call(path, sigil, family, canonical_fn, ns, :inner, params)
+          skip_inline_ws
+        end
+
+        # Now check if there's a value after the decorator(s)
+        b = @src.getbyte(@pos)
+        if b.nil? || b == LF || b == CR
+          # Decoration-only: no value — use empty table as placeholder
+          # Check for both_forms_present: if this path has block children, error
+          [parse_decoration_only_placeholder(path), false]
+        else
+          v = parse_t1_inline_value(path)
+          # Check for trailing decorators
+          skip_inline_ws
+          parse_t1_trailing_decorators(path) if sigil_at?(@pos)
+          [v, true]
+        end
+      end
+
+      # Parse decoration-only placeholder.
+      # Returns {} (empty table) — the family's empty_default.
+      # Also checks for "both forms present" error (block child after decoration-only).
+      def parse_decoration_only_placeholder(path)
+        {}
+      end
+
+      def parse_t1_trailing_decorators(path)
+        while !eof? && sigil_at?(@pos)
+          sigil, fn_name, ns, params = parse_decorator_call
+          family, canonical_fn = resolve_call(sigil, fn_name, ns)
+          add_decorator_call(path, sigil, family, canonical_fn, ns, :trailing, params)
+          skip_inline_ws
+        end
+      end
+
+      # Parse a decorator call: sigil-run name[.tail]? [(params)]*
+      # Returns [sigil, fn_name, ns, params]
+      # ns is the part before '.' if present and it's a namespace (not after the first name)
+      def parse_decorator_call
+        # Lex the sigil: consecutive sigil atoms (ASCII reserved chars OR emoji clusters)
+        sigil_start = @pos
+        while !eof?
+          atom_len = Tier1.lex_sigil_atom_at(@src, @pos)
+          break if atom_len.nil?
+          @pos += atom_len
+        end
+        sigil = @src.byteslice(sigil_start, @pos - sigil_start).force_encoding("UTF-8")
+
+        raise DecodeError.new(@line, col, "empty decorator sigil") if sigil.empty?
+
+        # Parse name (bare identifier)
+        # Could be: name  OR  ns.name
+        name1 = parse_bare_ident
+        raise DecodeError.new(@line, col, "expected decorator name after sigil '#{sigil}'") if name1.empty?
+
+        # Check for '.' => namespace qualifier
+        ns = nil
+        fn_name = name1
+        if @src.getbyte(@pos) == DOT
+          @pos += 1  # consume '.'
+          name2 = parse_bare_ident
+          if name2.empty?
+            raise DecodeError.new(@line, col, "expected name after '.' in decorator call")
+          end
+          ns = name1
+          fn_name = name2
+        end
+
+        # Parse zero or more param groups: '(' ... ')'
+        params = []
+        skip_inline_ws
+        while @src.getbyte(@pos) == LPAREN
+          @pos += 1  # consume '('
+          skip_flow_ws_t1
+          b = @src.getbyte(@pos)
+          if b == RPAREN
+            @pos += 1  # empty parens -> one named group with empty map
+            params << ParamGroup.new(:named, {})
+          else
+            pg = parse_param_group
+            params << pg
+            skip_flow_ws_t1
+            raise DecodeError.new(@line, col, "expected ')' after params") if @src.getbyte(@pos) != RPAREN
+            @pos += 1
+          end
+          skip_inline_ws
+        end
+
+        # If no params at all, treat as one empty named group
+        params << ParamGroup.new(:named, {}) if params.empty?
+
+        [sigil, fn_name, ns, params]
+      end
+
+      # Parse a param group (between parens, after '(' was consumed).
+      # Returns a ParamGroup.
+      def parse_param_group
+        # Peek: if next non-ws is a bare key followed by ':', it's named;
+        # otherwise positional.
+        save_pos = @pos
+        skip_flow_ws_t1
+        named = looks_like_named_params?
+
+        if named
+          map = {}
+          loop do
+            skip_flow_ws_t1
+            b = @src.getbyte(@pos)
+            break if b == RPAREN || b.nil?
+            k = parse_bare_ident
+            raise DecodeError.new(@line, col, "expected key in named params") if k.empty?
+            skip_flow_ws_t1
+            raise DecodeError.new(@line, col, "expected ':' after param key") if @src.getbyte(@pos) != COLON
+            @pos += 1
+            skip_flow_ws_t1
+            v = parse_t1_flow_value([])
+            map[k] = v
+            skip_flow_ws_t1
+            b = @src.getbyte(@pos)
+            if b == COMMA
+              @pos += 1
+            elsif b == RPAREN || b.nil?
+              break
+            else
+              raise DecodeError.new(@line, col, "expected ',' or ')' in named params, got '#{b.nil? ? "EOF" : b.chr}'")
+            end
+          end
+          ParamGroup.new(:named, map)
+        else
+          items = []
+          loop do
+            skip_flow_ws_t1
+            b = @src.getbyte(@pos)
+            break if b == RPAREN || b.nil?
+            v = parse_t1_flow_value([])
+            items << v
+            skip_flow_ws_t1
+            b = @src.getbyte(@pos)
+            if b == COMMA
+              @pos += 1
+            elsif b == RPAREN || b.nil?
+              break
+            else
+              raise DecodeError.new(@line, col, "expected ',' or ')' in positional params")
+            end
+          end
+          ParamGroup.new(:positional, items)
+        end
+      end
+
+      def looks_like_named_params?
+        # Peek ahead: bare ident chars followed by optional ws then ':'
+        p = @pos
+        n = @len
+        s = @src
+        while p < n
+          b = s.getbyte(p)
+          break unless b && (BARE_KEY_BYTE[b] || b >= 128)
+          p += 1
+        end
+        return false if p == @pos  # no ident chars
+        # Skip ws
+        while p < n
+          b = s.getbyte(p)
+          break unless b == SP || b == TAB
+          p += 1
+        end
+        return false if p >= n
+        s.getbyte(p) == COLON
+      end
+
+      # Parse a flow value (used in params and flow arrays/tables).
+      def parse_t1_flow_value(path)
+        b = @src.getbyte(@pos)
+        if b == LBRACK
+          return parse_t1_flow_array(path)
+        elsif b == LBRACE
+          return parse_t1_flow_table(path)
+        end
+        parse_t1_inline_value_raw
+      end
+
+      # Parse an inline value (delegating to existing parser machinery).
+      def parse_t1_inline_value(path)
+        b = @src.getbyte(@pos)
+        if b == LBRACK
+          return parse_t1_flow_array(path)
+        elsif b == LBRACE
+          return parse_t1_flow_table(path)
+        end
+        parse_t1_inline_value_raw
+      end
+
+      # Parse a flow-array with decorator awareness (for tier-1 inner decorators in []).
+      def parse_t1_flow_array(path)
+        @pos += 1  # consume '['
+        items = []
+        loop do
+          skip_flow_ws_t1
+          b = @src.getbyte(@pos)
+          if b == RBRACK
+            @pos += 1
+            return items
+          end
+
+          idx = items.length
+          current_path = path + [{ "index" => idx }]
+
+          # Check for inner decorator before value
+          if sigil_at?(@pos)
+            # Inner decorator in flow array
+            loop do
+              break unless sigil_at?(@pos)
+              sigil, fn_name, ns, params = parse_decorator_call
+              family, canonical_fn = resolve_call(sigil, fn_name, ns)
+              add_decorator_call(current_path, sigil, family, canonical_fn, ns, :inner, params)
+              skip_inline_ws
+            end
+            # Now parse the actual value
+            b = @src.getbyte(@pos)
+            if b == COMMA || b == RBRACK || b.nil?
+              # Decoration-only in flow array — empty table placeholder
+              items << {}
+            else
+              v = parse_t1_flow_value(current_path)
+              items << v
+            end
+          else
+            v = parse_t1_flow_value(current_path)
+            items << v
+          end
+
+          skip_flow_ws_t1
+          b = @src.getbyte(@pos)
+          if b == COMMA
+            @pos += 1
+          elsif b == RBRACK
+            @pos += 1
+            return items
+          elsif b.nil?
+            raise DecodeError.new(@line, col, "unterminated flow array")
+          else
+            raise DecodeError.new(@line, col, "unexpected '#{b.chr}' in flow array")
+          end
+        end
+      end
+
+      def parse_t1_flow_table(path)
+        @pos += 1  # consume '{'
+        t = {}
+        loop do
+          skip_flow_ws_t1
+          b = @src.getbyte(@pos)
+          if b == RBRACE
+            @pos += 1
+            return t
+          end
+          k = parse_key_t1
+          skip_flow_ws_t1
+          raise DecodeError.new(@line, col, "expected ':' after flow-table key") unless @src.getbyte(@pos) == COLON
+          @pos += 1
+          skip_flow_ws_t1
+          kp = path + [{ "key" => k }]
+          v = parse_t1_flow_value(kp)
+          t[k] = v
+          skip_flow_ws_t1
+          b = @src.getbyte(@pos)
+          if b == COMMA
+            @pos += 1
+          elsif b == RBRACE
+            @pos += 1
+            return t
+          elsif b.nil?
+            raise DecodeError.new(@line, col, "unterminated flow table")
+          else
+            raise DecodeError.new(@line, col, "unexpected '#{b.chr}' in flow table")
+          end
+        end
+      end
+
+      # ── Low-level helpers ────────────────────────────────────────────────
+
+      def parse_t1_inline_value_raw
+        # Delegate to existing parser machinery by creating a tiny sub-parser
+        # positioned at @pos and having it parse one value.
+        # This is the simplest approach — create a sub-parser with the same source
+        # but start at @pos, then copy back.
+        sub = InlineValueParser.new(@src, @pos, @line, @line_start, self)
+        val = sub.parse_one_value
+        @pos = sub.pos
+        @line = sub.line
+        @line_start = sub.line_start
+        val
+      end
+
+      def add_decorator_call(path, sigil, family, fn_name, ns, position, params)
+        path_key = path_to_key(path)
+        entry = @dec_entries[path_key]
+        if entry.nil?
+          entry = DecoratorEntry.new(path.dup, {}, [])
+          @dec_entries[path_key] = entry
+        end
+        call = DecoratorCall.new(sigil, family, fn_name, ns, position, params, [])
+        entry.calls[sigil] ||= []
+        entry.calls[sigil] << call
+      end
+
+      def resolve_call(sigil, fn_name, ns)
+        Tier1.resolve_family(sigil, fn_name, ns, @imports)
+      end
+
+      def path_to_key(path)
+        path.map { |seg| seg.key?("key") ? "k:#{seg["key"]}" : "i:#{seg["index"]}" }.join("/")
+      end
+
+      def skip_trivia
+        loop do
+          skip_inline_ws
+          b = @src.getbyte(@pos)
+          if b == LF
+            @pos += 1; advance_line
+          elsif b == CR && @src.getbyte(@pos + 1) == LF
+            @pos += 2; advance_line
+          elsif b == HASH
+            skip_line_comment
+          elsif b == 0x2F && @src.getbyte(@pos + 1) == 0x2F
+            skip_line_comment
+          elsif b == 0x2F && @src.getbyte(@pos + 1) == 0x2A
+            skip_block_comment
+          else
+            break
+          end
+        end
+      end
+
+      def skip_inline_ws
+        @pos += 1 while @src.getbyte(@pos) == SP || @src.getbyte(@pos) == TAB
+      end
+
+      def skip_line_comment
+        while @pos < @len
+          b = @src.getbyte(@pos)
+          @pos += 1
+          if b == LF
+            advance_line; break
+          elsif b == CR
+            @pos += 1 if @src.getbyte(@pos) == LF
+            advance_line; break
+          end
+        end
+      end
+
+      def skip_block_comment
+        @pos += 2  # consume '/*'
+        loop do
+          raise DecodeError.new(@line, col, "unterminated block comment") if eof?
+          b = @src.getbyte(@pos)
+          if b == 0x2A && @src.getbyte(@pos + 1) == 0x2F
+            @pos += 2; break
+          elsif b == LF
+            @pos += 1; advance_line
+          elsif b == CR
+            @pos += 1
+            if @src.getbyte(@pos) == LF
+              @pos += 1
+            end
+            advance_line
+          else
+            @pos += 1
+          end
+        end
+      end
+
+      def skip_flow_ws_t1
+        loop do
+          b = @src.getbyte(@pos)
+          if b == SP || b == TAB
+            @pos += 1
+          elsif b == LF
+            @pos += 1; advance_line
+          elsif b == CR && @src.getbyte(@pos + 1) == LF
+            @pos += 2; advance_line
+          else
+            break
+          end
+        end
+      end
+
+      def consume_eol
+        b = @src.getbyte(@pos)
+        if b == LF
+          @pos += 1; advance_line; true
+        elsif b == CR
+          @pos += 1
+          @pos += 1 if @src.getbyte(@pos) == LF
+          advance_line; true
+        else
+          false
+        end
+      end
+
+      def advance_line
+        @line += 1
+        @line_start = @pos
+      end
+
+      def eof?
+        @pos >= @len
+      end
+
+      def col
+        bytes = @pos - @line_start
+        bytes + 1
+      end
+
+      def starts_bytes?(s)
+        @src.byteslice(@pos, s.bytesize) == s
+      end
+
+      def measure_line_indent
+        n = 0
+        i = @line_start
+        while i < @len && @src.getbyte(i) == SP
+          n += 1; i += 1
+        end
+        n
+      end
+
+      def peek_after_plus?
+        b = @src.getbyte(@pos + 1)
+        b.nil? || b == SP || b == TAB || b == LF || b == CR
+      end
+
+      def parse_key_t1
+        b = @src.getbyte(@pos)
+        if b == DQUOTE
+          parse_dquote_key
+        elsif b == SQUOTE
+          parse_squote_key
+        else
+          parse_bare_ident_key
+        end
+      end
+
+      def parse_bare_ident_key
+        s = @src; n = @len; pos = @pos; start = pos
+        while pos < n
+          b = s.getbyte(pos)
+          break unless b && (b < 128 ? BARE_KEY_BYTE[b] : true)
+          pos += 1
+        end
+        raise DecodeError.new(@line, col, "expected key") if pos == start
+        @pos = pos
+        s.byteslice(start, pos - start).force_encoding("UTF-8")
+      end
+
+      def parse_bare_ident
+        s = @src; n = @len; pos = @pos; start = pos
+        while pos < n
+          b = s.getbyte(pos)
+          break unless b && b < 128 && BARE_KEY_BYTE[b]
+          pos += 1
+        end
+        @pos = pos
+        s.byteslice(start, pos - start).force_encoding("UTF-8")
+      end
+
+      def parse_dquote_key
+        @pos += 1  # consume '"'
+        buf = +""
+        loop do
+          b = @src.getbyte(@pos)
+          raise DecodeError.new(@line, col, "unterminated quoted key") if b.nil? || b == LF
+          if b == 0x5C  # backslash
+            @pos += 1
+            buf << parse_escape
+          elsif b == DQUOTE
+            @pos += 1
+            return buf
+          else
+            buf << @src.byteslice(@pos, 1).force_encoding("UTF-8")
+            @pos += 1
+          end
+        end
+      end
+
+      def parse_squote_key
+        @pos += 1  # consume "'"
+        start = @pos
+        loop do
+          b = @src.getbyte(@pos)
+          raise DecodeError.new(@line, col, "unterminated literal key") if b.nil? || b == LF
+          if b == SQUOTE
+            result = @src.byteslice(start, @pos - start).force_encoding("UTF-8")
+            @pos += 1
+            return result
+          end
+          @pos += 1
+        end
+      end
+
+      def parse_escape
+        b = @src.getbyte(@pos)
+        @pos += 1
+        case b
+        when 0x62 then "\b"
+        when 0x66 then "\f"
+        when 0x6E then "\n"
+        when 0x72 then "\r"
+        when 0x74 then "\t"
+        when DQUOTE then "\""
+        when 0x5C then "\\"
+        else "\\#{b.chr}"
+        end
+      end
+
+      def line_starts_kvpair_t1?
+        p = @pos
+        s = @src
+        n = @len
+        first = s.getbyte(p)
+        if first == DQUOTE
+          p += 1
+          while p < n
+            b = s.getbyte(p)
+            if b == 0x5C; p += 2
+            elsif b == DQUOTE; p += 1; break
+            elsif b == LF || b == CR; return false
+            else; p += 1
+            end
+          end
+        elsif first == SQUOTE
+          p += 1
+          while p < n
+            b = s.getbyte(p)
+            if b == SQUOTE; p += 1; break
+            elsif b == LF || b == CR; return false
+            else; p += 1
+            end
+          end
+        else
+          any = false
+          while p < n
+            b = s.getbyte(p)
+            break unless b && b < 128 && BARE_KEY_BYTE[b]
+            p += 1; any = true
+          end
+          return false unless any
+        end
+        return false if p >= n || s.getbyte(p) != COLON
+        nxt = s.getbyte(p + 1)
+        nxt.nil? || nxt == SP || nxt == TAB || nxt == LF || nxt == CR
+      end
+    end
+
+    # ── InlineValueParser ────────────────────────────────────────────────────
+    #
+    # A thin wrapper that delegates value parsing to a real Dms::Parser
+    # instance, positioned at a specific offset in the source.
+    # We extract the source substring from the current position to end-of-line
+    # (plus the rest of the document for block values), parse one value,
+    # and map back the consumed bytes.
+
+    class InlineValueParser
+      attr_reader :pos, :line, :line_start
+
+      def initialize(src, start_pos, start_line, start_line_start, outer)
+        @src = src
+        @pos = start_pos
+        @line = start_line
+        @line_start = start_line_start
+        @outer = outer
+        @len = src.bytesize
+      end
+
+      def parse_one_value
+        # Build a sub-source from @pos onwards, but we need an offset trick.
+        # We'll use Dms::Parser directly, padding the prefix with spaces so
+        # line numbers are approximately correct. Since error messages in
+        # parameter parsing use the outer parser's position, this is fine.
+        sub_src = @src.byteslice(@pos, @len - @pos).force_encoding("UTF-8")
+
+        # Use a real Parser in lite mode to parse one value.
+        # We only need one token; the parser will stop at the right place.
+        p = SingleValueParser.new(sub_src)
+        val = p.parse_value_at_start
+        consumed = p.consumed
+        # Update position
+        new_src_pos = @pos + consumed
+        # Update line counts based on consumed newlines
+        consumed_src = @src.byteslice(@pos, consumed)
+        consumed_src.each_byte do |b|
+          if b == 0x0A
+            @line += 1
+            @line_start = @pos + (@src.byteslice(@pos, consumed).index("\n".force_encoding("UTF-8"), 0) || 0) + 1
+          end
+        end
+        # Recount properly
+        @line = 1 + @src.byteslice(0, new_src_pos).count("\n")
+        last_nl = @src.byteslice(0, new_src_pos).rindex("\n")
+        @line_start = last_nl ? last_nl + 1 : 0
+        @pos = new_src_pos
+        val
+      end
+    end
+
+    # SingleValueParser: uses Dms::Parser to parse one value from a string.
+    class SingleValueParser
+      attr_reader :consumed
+
+      def initialize(src)
+        @src = src
+        @parser = nil
+        @consumed = 0
+      end
+
+      def parse_value_at_start
+        # Wrap in a minimal DMS document and parse, then extract the value.
+        # Since we need to parse a raw value (not a key-value pair),
+        # we wrap it as `_v: <value>` and parse the front matter.
+        # Actually simpler: parse as a scalar root document.
+
+        # Build: the value might be followed by sigil chars, newlines, etc.
+        # We'll use a fresh Parser at lite mode.
+        p = Dms::Parser.new(@src, lite: true)
+        val = p.parse_inline_value_or_heredoc
+        @consumed = p.instance_variable_get(:@pos)
+        val
+      end
+    end
+
+    # ── JSON emission ────────────────────────────────────────────────────────
+
+    def self.emit_t1_json(doc_t1, tag_fn)
+      imports_json = doc_t1.imports.map { |imp| import_to_json(imp) }
+      body_tagged = tag_fn.call(doc_t1.t0.body)
+      decorators_json = doc_t1.decorators.map { |entry| entry_to_json(entry, tag_fn) }
+
+      {
+        "tier"       => doc_t1.observed_tier,
+        "imports"    => imports_json,
+        "body"       => body_tagged,
+        "decorators" => decorators_json
+      }
+    end
+
+    def self.import_to_json(imp)
+      bind_json = {}
+      imp.bind.each { |sigil, fams| bind_json[sigil] = fams }
+
+      allow_json = {}
+      imp.allow.each { |family, names| allow_json[family] = names }
+
+      deny_json = {}
+      imp.deny.each { |family, names| deny_json[family] = names }
+
+      alias_json = {}
+      imp.alias_map.each do |family, inner|
+        alias_json[family] = inner
+      end
+
+      {
+        "dialect" => imp.dialect,
+        "version" => imp.version,
+        "ns"      => imp.ns,
+        "bind"    => bind_json,
+        "allow"   => allow_json,
+        "deny"    => deny_json,
+        "alias"   => alias_json
+      }
+    end
+
+    def self.entry_to_json(entry, tag_fn)
+      path_json = entry.path.map do |seg|
+        if seg.key?("key")
+          { "key" => seg["key"] }
+        else
+          { "index" => seg["index"] }
+        end
+      end
+
+      calls_json = {}
+      entry.calls.each do |sigil, calls|
+        calls_json[sigil] = calls.map { |c| call_to_json(c, tag_fn) }
+      end
+
+      {
+        "path"       => path_json,
+        "calls"      => calls_json,
+        "comments"   => []
+      }
+    end
+
+    def self.call_to_json(call, tag_fn)
+      params_json = call.params.map { |pg| param_group_to_json(pg, tag_fn) }
+      {
+        "family"     => call.family,
+        "fn"         => call.fn_name,
+        "ns"         => call.ns,
+        "position"   => call.position.to_s,
+        "params"     => params_json,
+        "params_dec" => []
+      }
+    end
+
+    def self.param_group_to_json(pg, tag_fn)
+      case pg.kind
+      when :named
+        tagged_val = {}
+        pg.value.each { |k, v| tagged_val[k] = tag_fn.call(v) }
+        { "kind" => "named", "value" => tagged_val }
+      when :positional
+        { "kind" => "positional", "value" => pg.value.map { |v| tag_fn.call(v) } }
+      end
+    end
+  end
+end