Tag Ruby-content specs + lint + hash-inspect doc

Add scripts/verify_ruby_type_tags.rb lint enforcing that any spec carrying
Ruby-specific content (Hash#inspect `=>` output, :symbol keys, non-string
hash keys, invalid-UTF-8 bytes) declares a ruby feature tag and sits above
complexity 100. Fix all 88 violations it found: 83 specs tagged ruby_types,
5 base64-decode specs producing invalid-UTF-8 bytes tagged binary_data.

These specs test Ruby-specific rendering/transport behavior that JSON-RPC
adapters cannot produce or receive faithfully. Tagging them lets JSON-RPC
adapters (which opt out of ruby_types/binary_data by default) skip them,
while a Ruby adapter or an opt-in implementation can still run them.

- docs/ruby_hash_inspect_format.md: precise spec of Ruby Hash#inspect/to_s
  format so opt-in implementers can reproduce it.
- init.rb generic template: ruby_types stays ENABLED (not in
  missing_features) with a commented opt-out hint; jsonrpc template keeps
  ruby_types in missing_features (disabled by default).
- AGENTS.md: document the verify_* scripts, run them all before pushing,
  and add new ones for new cross-cutting rules.

Author: tobi

CLAUDE.md

@@ -54,6 +54,28 @@ It currently enforces:
 
 If it fails, add a useful spec/source-level hint or move the spec later in the ramp.
 
+### `verify_*` scripts
+
+`scripts/` contains standalone lint/audit scripts named `verify_*.rb` that check
+cross-cutting spec invariants the quality-gate test doesn't cover:
+
+```bash
+ruby -Ilib scripts/verify_lax_placement.rb        # lax-only specs live in liquid_ruby_lax
+ruby -Ilib scripts/verify_ruby_type_tags.rb       # Ruby-content specs carry a ruby feature tag + complexity > 100
+```
+
+**Run every `verify_*` script before pushing.** They exit non-zero on violation:
+
+```bash
+for s in scripts/verify_*.rb; do ruby -Ilib "$s" || exit 1; done
+```
+
+When you introduce a new cross-cutting rule (e.g. "every spec with marker X must
+have tag Y"), add a `verify_*.rb` script for it rather than a one-off check, so
+the rule stays enforced. Keep each script self-contained (parse spec files
+directly), print `OK: ...` on success, and exit non-zero with a per-spec
+offender list on failure.
+
 ### Dumb Adapter Ramp Audits
 
 When changing early complexity scores or adding beginner specs, play dumb and verify the harness still behaves like an implementation curriculum:

docs/ruby_hash_inspect_format.md

@@ -0,0 +1,113 @@
+# Ruby `Hash#inspect` / `Hash#to_s` format
+
+Several specs render a hash (or array of hashes) through `{{ var }}` and expect
+Ruby's `Hash#inspect` output — **not** JSON. In Ruby, `Hash#to_s` is an alias
+for `Hash#inspect`, so `{{ my_hash }}` (which calls `to_s` on the resolved
+value) produces the format below. A non-Ruby Liquid implementation must
+reproduce it exactly to pass these specs.
+
+This is a cross-language correctness bar: Liquid defers object rendering to the
+host language's `to_s`, and the reference implementation is Ruby, so the
+expected strings are Ruby's `inspect` output.
+
+## Grammar
+
+```
+hash_inspect  = "{" pairs? "}"
+pairs         = pair (", " pair)*
+pair          = key_inspect "=>" value_inspect
+array_inspect = "[" elements? "]"
+elements      = elem_inspect (", " elem_inspect)*
+```
+
+`=>` is the **rocket**, never `:`. Pairs are in **insertion order**. The
+separator is `", "` (comma + one space). The whole thing is wrapped in `{` `}`.
+
+## Scalar inspect rules
+
+| Ruby type   | Inspect output        | Notes |
+|-------------|-----------------------|-------|
+| `String`    | `"foo"`               | double-quoted, with escapes (below) |
+| `Symbol`    | `:foo`                | leading colon, no quotes |
+| `Integer`   | `42`                  | bare |
+| `Float`     | `1.0`                 | always has a decimal part (`1.0`, not `1`) |
+| `nil`       | `nil`                 | the literal word |
+| `true`      | `true`                | |
+| `false`     | `false`               | |
+| `Array`     | `[a, b, c]`           | each element via its own inspect, `, ` separated |
+| `Hash`      | `{k=>v, ...}`         | recursive |
+| self-ref    | `{...}`               | a hash that refers to an ancestor in the same inspect call renders as `{...}` |
+
+## String escapes (inside double quotes)
+
+The string's `inspect` doubles `\\` and `\"`, and turns control characters into
+their escaped forms: `\n`, `\t`, `\r`, `\f`, `\b`, `\a`, `\e`, `\v`, `\0` /
+`\u0000`-style for other non-printables. Printable ASCII is emitted literally.
+This matters for specs where the hash is piped through `escape`/`url_encode`
+*after* being stringified — the inspect output is the input to those filters.
+
+## Worked examples (all drawn from real specs)
+
+| Input (Ruby)                                  | Expected output                        |
+|-----------------------------------------------|----------------------------------------|
+| `{}`                                          | `{}`                                   |
+| `{"key1"=>"value1", "key2"=>"value2"}`        | `{"key1"=>"value1", "key2"=>"value2"}` |
+| `{"numbers"=>[1, 2, 3]}`                      | `{"numbers"=>[1, 2, 3]}`               |
+| `{"numbers"=>[]}`                             | `{"numbers"=>[]}`                      |
+| `{"outer"=>{"inner"=>"value"}}`               | `{"outer"=>{"inner"=>"value"}}`        |
+| `{{"foo"=>"bar"}=>42}` (hash key)             | `{{"foo"=>"bar"}=>42}`                 |
+| `{:key1=>1, :key2=>2}` (symbol keys)          | `{:key1=>1, :key2=>2}`                 |
+| recursive `{"self"=>{"self"=>{...}}}`         | `{"self"=>{"self"=>{...}}}`            |
+
+## How filters interact
+
+When a hash is the input to a string filter, the hash is **first** stringified
+via `inspect`, **then** the filter runs on that string. Examples:
+
+- `{{ my_hash | upcase }}` → `{"KEY1"=>"VALUE1", ...}` (inspect, then uppercased)
+- `{{ my_hash | downcase }}` → `{"key1"=>"value1", ...}`
+- `{{ my_hash | append: " text" }}` → `{"Key"=>"Value"} text`
+- `{{ my_hash | replace: "key", "KEY" }}` → replaces inside the inspect string
+- `{{ my_hash | escape }}` → HTML-escapes the inspect string
+  (`{"Key"=>"Value"}`)
+
+So the inspect format is the *substrate* every string filter operates on when the
+input is a hash.
+
+## Pseudocode for a non-Ruby implementation
+
+```text
+function rubyInspect(value, seen = new Set()):
+  if value is a Hash/Map:
+    if value in seen: return "{...}"        # cycle guard
+    seen.add(value)
+    if value is empty: return "{}"
+    parts = []
+    for (k, v) in value in insertion order:
+      parts.push(rubyInspect(k, seen) + "=>" + rubyInspect(v, seen))
+    return "{" + parts.join(", ") + "}"
+  if value is an Array:
+    if value is empty: return "[]"
+    return "[" + value.map(rubyInspect).join(", ") + "]"
+  if value is a String:  return rubyStringInspect(value)   # double-quoted + escapes
+  if value is a Symbol:  return ":" + value.name            # no quotes
+  if value is null/nil:  return "nil"
+  if value is Boolean:   return value ? "true" : "false"
+  if value is Integer:   return String(value)
+  if value is Float:     return floatInspect(value)         # always show a decimal
+  # other objects: defer to the host's inspect/to_s if you emulate ruby_types
+```
+
+`rubyStringInspect(s)` wraps `s` in `"..."`, escaping `\\` and `"` and control
+chars as above. `floatInspect` must always include a decimal point (`1.0`, not
+`1`; `0.2`, not `0.2` rendered as a bare fraction — match Ruby's `Float#inspect`,
+which uses the shortest representation that round-trips).
+
+## When you need this
+
+These specs are gated behind the **Ruby/reference-quirk** complexity band
+(~220+) and most are tagged `features: [ruby_types]`. JSON-RPC adapters skip
+`ruby_types` by default. If you opt in (remove `:ruby_types` from
+`missing_features`), the JSON-RPC transport delivers non-string hash keys to you
+as their Ruby `inspect` string, and your engine is expected to render hashes and
+those keys per the rules above.

lib/liquid/spec/cli/init.rb

@@ -46,6 +46,13 @@ module Init
 
             # Optional: filter specs by name pattern
             # config.filter = /assign/
+            # Specs that need Ruby-specific behavior (Hash#inspect output format
+            # `{"k"=>"v"}`, symbol keys, binary bytes) are tagged `ruby_types`.
+            # A Ruby implementation should leave these ENABLED (do not list them
+            # here). A non-Ruby implementation that is not yet emulating Ruby's
+            # inspect/to_s format can opt out temporarily:
+            #   config.missing_features = [:ruby_types, :binary_data]
+            # See docs/ruby_hash_inspect_format.md for what opting in requires.
           end
 
           # Called to compile a template string into your implementation's template object.

scripts/verify_ruby_type_tags.rb

@@ -0,0 +1,155 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Lint: every spec that carries Ruby-specific content must declare a Ruby
+# feature tag AND sit above complexity 100 (out of the beginner ramp).
+#
+# Ruby-specific content is anything a JSON/JS implementation cannot produce or
+# receive faithfully without deliberately emulating Ruby semantics:
+#   - expected output containing Ruby `Hash#inspect` notation (`=>` rocket,
+#     or `:symbol` keys rendered as `{:foo=>...}`)
+#   - an environment with a non-String Hash key (Symbol, Integer, Float,
+#     Hash, Array, etc.) at any nesting depth — JSON object keys are strings
+#   - expected output containing invalid-UTF-8 bytes (binary data)
+#
+# A spec matching any of these must:
+#   1. list at least one Ruby feature tag
+#      (ruby_types / ruby_drops / binary_data / runtime_drops / template_factory)
+#   2. have complexity > 100
+#
+# Usage: ruby -Ilib scripts/verify_ruby_type_tags.rb
+# Exit code is non-zero if any violation is found.
+
+require "yaml"
+
+RUBY_FEATURES = %w[ruby_types ruby_drops binary_data runtime_drops template_factory].freeze
+COMPLEXITY_FLOOR = 100
+
+module RubyTypeTagVerifier
+  class << self
+    def run
+      offenders = []
+      each_spec do |spec|
+        markers = detect_markers(spec)
+        next if markers.empty?
+        reasons = []
+        feats = spec[:features] || []
+        unless (feats & RUBY_FEATURES).any?
+          reasons << "missing ruby feature tag (needs one of: #{RUBY_FEATURES.join(", ")})"
+        end
+        c = spec[:complexity]
+        if c && c <= COMPLEXITY_FLOOR
+          reasons << "complexity #{c} <= #{COMPLEXITY_FLOOR} (Ruby-quirk specs belong above the beginner ramp)"
+        end
+        next if reasons.empty?
+        offenders << {
+          file: spec[:file],
+          line: spec[:line],
+          name: spec[:name],
+          markers: markers,
+          reasons: reasons,
+        }
+      end
+
+      if offenders.empty?
+        puts "OK: all Ruby-content specs are tagged and above complexity #{COMPLEXITY_FLOOR}."
+        return 0
+      end
+
+      puts "Found #{offenders.size} spec(s) with Ruby-specific content that violate the rules:\n\n"
+      offenders.each do |o|
+        puts "  #{o[:file]}:#{o[:line]}  #{o[:name]}"
+        puts "    markers: #{o[:markers].join(", ")}"
+        o[:reasons].each { |r| puts "    - #{r}" }
+        puts
+      end
+      1
+    end
+
+    private
+
+    # Yield a hash for every spec across all spec files:
+    # { file, line, name, expected, environment, features, complexity }
+    def each_spec
+      Dir.glob("specs/**/*.yml").sort.each do |file|
+        doc = YAML.unsafe_load(File.read(file)) rescue next
+        specs = specs_of(doc)
+        next unless specs.is_a?(Array)
+        # line numbers: scan the raw file for "- name:" anchors
+        name_lines = index_name_lines(file)
+        specs.each_with_index do |s, i|
+          next unless s.is_a?(Hash)
+          yield(
+            file: file,
+            line: name_lines[s["name"]],
+            name: s["name"],
+            expected: s["expected"],
+            environment: s["environment"],
+            features: (s["features"] || []).map(&:to_s),
+            complexity: s["complexity"],
+          )
+        end
+      end
+    end
+
+    def specs_of(doc)
+      return doc if doc.is_a?(Array)
+      return doc["specs"] || doc["tests"] if doc.is_a?(Hash)
+      nil
+    end
+
+    # name -> first line number (1-based) of the spec block containing it.
+    # Handles both formats: blocks starting with `- name:` and blocks where
+    # `name:` is a later field (e.g. `- template:` first).
+    def index_name_lines(file)
+      map = {}
+      lines = File.readlines(file)
+      # block starts: any list-item mapping opener ("- <key>:")
+      starts = lines.each_index.select { |i| lines[i] =~ /^- [A-Za-z]/ }
+      starts.each_with_index do |st, k|
+        en = (k + 1 < starts.size) ? starts[k + 1] : lines.size
+        (st...en).each do |i|
+          if lines[i] =~ /^  name:\s*(.+?)\s*$/
+            map[$1] = st + 1 unless map.key?($1)
+            break
+          end
+        end
+      end
+      map
+    end
+
+    def detect_markers(spec)
+      markers = []
+      exp = spec[:expected]
+      markers << "hash-inspect (=>)" if exp.is_a?(String) && exp.include?("=>")
+      markers << "symbol-inspect (:sym)" if exp.is_a?(String) && exp.match?(/[{:]\s*:[a-z_][a-z0-9_]*[=>,}]/)
+      if exp.is_a?(String) && exp.bytes.any? { |b| b > 127 } && !exp.dup.force_encoding("UTF-8").valid_encoding?
+        markers << "invalid-utf8 (binary)"
+      end
+      env = spec[:environment]
+      markers.concat(non_string_key_markers(env, 0)) if env
+      markers.uniq
+    end
+
+    # Walk a value looking for Hashes whose keys are not all Strings.
+    def non_string_key_markers(obj, depth)
+      return [] if depth > 40
+      case obj
+      when Hash
+        out = []
+        weird = obj.keys.reject { |k| k.is_a?(String) }
+        weird.group_by { |k| k.class }.each do |klass, keys|
+          out << "non-string hash key (#{klass}; #{keys.size})"
+        end
+        obj.values.each { |v| out.concat(non_string_key_markers(v, depth + 1)) }
+        out
+      when Array
+        obj.flat_map { |e| non_string_key_markers(e, depth + 1) }
+      else
+        []
+      end
+    end
+  end
+end
+
+exit RubyTypeTagVerifier.run if $PROGRAM_NAME == __FILE__

specs/basics/nested-parameters.yml

@@ -312,6 +312,8 @@ specs:
     This is used constantly in themes to filter collections by settings.
 
 # ── case/when with dotted paths ─────────────────────────────────────────
+  features:
+  - ruby_types
 
 - name: case_dotted_variable
   template: "{% case item.status %}{% when 'active' %}ON{% when 'inactive' %}OFF{% endcase %}"

specs/liquid_ruby/array_to_s.yml

@@ -7,4 +7,6 @@
       - foo
       - bar
   expected: "hellohel\nlo{\"nested\"=>[\"foo\", \"bar\"]}"
-  name: Array to_s handles escape sequences
+  name: Array to_s handles escape sequences
+  features:
+  - ruby_types