fix(isc): fix DSL array keys bug, notes grammar, and codemod whitespace

DSL fix (lib/interscript/dsl/metadata.rb):
- STANDARD_ARRAY_KEYS methods now store result in @node (was silently discarded)
- This enables url, notes, implementation_notes, original_notes to be compared

Grammar fix (grammar/concerns/metadata.rb):
- notes_field: move .as(:notes) inside braced() to capture note entries,
  not the brace characters. Empty notes blocks now produce [] not ["{ }"]

Codemod fixes (isc/codemod.rb):
- read_heredoc_into_string: preserve blank lines as \n\n (was \n)
- read_heredoc_into_string: preserve raw line indentation (was stripping all)
  This lets normalize_heredoc do proper YAML-style dedent

DocumentBuilder fixes (isc/document_builder.rb):
- normalize_heredoc: proper YAML dedent (strip common indent, preserve relative)
- ARRAY_METADATA_FIELDS: wrap url/notes/etc in Arrays to match DSL convention
- Apply normalize_heredoc to notes (was only applied to description)

Deep checker (exe/verify_isc_deep):
- normalize_meta collapses internal whitespace for semantic comparison
- No longer skips url/notes fields (DSL bug is fixed)

Result: 247/289 deep equivalent (up from 124), 40 remain (edge cases)

Author: ronaldtse

exe/verify_isc_deep

@@ -24,11 +24,9 @@ class DeepVerifier
 
     details = []
 
-    # Compare metadata — skip DSL-internal fields and fields the Ruby DSL
-    # doesn't store (STANDARD_ARRAY_KEYS like url/notes are parsed but
-    # silently dropped by the DSL due to a bug in dsl/metadata.rb).
-    skip_fields = [:nonstandard, :tests, :stages, :aliases, :dependencies,
-                   :url, :notes, :implementation_notes, :original_notes]
+    # Compare metadata — skip DSL-internal fields only.
+    # STANDARD_ARRAY_KEYS bug is fixed, so url/notes/etc. are now stored.
+    skip_fields = [:nonstandard, :tests, :stages, :aliases, :dependencies]
     imp_meta = imp_data[:metadata].reject { |k, _| skip_fields.include?(k.to_sym) }
     isc_meta = isc_data[:metadata].reject { |k, _| skip_fields.include?(k.to_sym) }
     (imp_meta.keys | isc_meta.keys).each do |key|
@@ -119,7 +117,7 @@ class DeepVerifier
 
   def normalize_meta(val)
     case val
-    when String then val.strip
+    when String then val.gsub(/\s+/, " ").strip
     when Array then val.map { |v| normalize_meta(v) }
     when Hash then val.transform_values { |v| normalize_meta(v) }
     else val

lib/interscript/dsl/metadata.rb

@@ -46,9 +46,7 @@ def initialize(yaml: false, map_name: "", library: true, &block)
 
   STANDARD_ARRAY_KEYS.each do |sym|
     define_method sym do |stuff|
-      stuff = Array(stuff)
-
-      stuff.map do |i|
+      @node[sym] = Array(stuff).map do |i|
         case i
         when String
           i

lib/interscript/isc/codemod.rb

@@ -458,14 +458,16 @@ def convert_quoted_note_body
 
       def read_heredoc_into_string(indent)
         # Read lines that are indented deeper than `indent` (or blank). Concatenate.
+        # Preserve raw indentation — the DocumentBuilder's normalize_heredoc
+        # handles YAML-style dedent to match the DSL's output.
         until @scanner.eos?
           if @scanner.check(/\n(?:[ \t]*\n)*([ \t]{0,#{indent.length}}\S)/)
             return
           elsif @scanner.scan(/\n[ \t]*\n/)
-            # Blank line inside heredoc — preserve as \n
-            @out << "\\n"
-          elsif @scanner.scan(/\n[ \t]+([^\n]*)/)
-            # Indented line — strip indent, join with \n. Escape quotes.
+            # Blank line inside heredoc — preserve as \n\n
+            @out << "\\n\\n"
+          elsif @scanner.scan(/\n([ \t]+[^\n]*)/)
+            # Indented line — preserve raw content (indent + text)
             @out << "\\n" + @scanner[1].to_s.gsub('"', '\\"')
           elsif @scanner.scan(/\n/)
             @out << "\\n"

lib/interscript/isc/document_builder.rb

@@ -13,6 +13,10 @@ module Isc
     class DocumentBuilder
       SCHEMA_VERSION = 1
 
+      # Metadata fields that the Ruby DSL stores as Arrays (STANDARD_ARRAY_KEYS).
+      # ISC stores them as generic fields, so we wrap in an Array to match.
+      ARRAY_METADATA_FIELDS = %i[notes implementation_notes original_notes url].freeze
+
       def self.build(tree, filename: nil)
         new(tree, filename: filename).build
       end
@@ -74,7 +78,29 @@ def unescape_braces(text)
       end
 
       def normalize_heredoc(text)
-        text.lines.map { |l| l.strip }.join("\n").strip + "\n"
+        lines = text.lines.map(&:chomp)
+        content_lines = lines.reject { |l| l.strip.empty? }
+        return "" if content_lines.empty?
+        return content_lines.first.strip if content_lines.size == 1
+
+        # YAML-style dedent: strip the minimum indent across all non-blank
+        # lines. The first line's indent may have been partially consumed
+        # by the grammar, so we compute min_indent from lines 2+ and treat
+        # the first line as having at least that much indent.
+        min_indent = content_lines
+          .drop(1)
+          .map { |l| l[/\A[ \t]*/].length }
+          .min || 0
+
+        lines.map do |l|
+          if l.strip.empty?
+            ""
+          elsif l[/\A[ \t]*/].length >= min_indent
+            l[min_indent..]
+          else
+            l.strip
+          end
+        end.join("\n").strip
       end
 
       # Apply Transform to an identifier fragment.
@@ -101,32 +127,37 @@ def extract_metadata(arr)
             h[:notes] ||= []
             Array(field[:notes]).each do |n|
               note_val = n.is_a?(Hash) ? n[:note] : n
-              h[:notes] << unquote(note_val)
+              h[:notes] << normalize_heredoc(unquote(note_val).to_s)
             end
           when field.key?(:note)
             h[:notes] ||= []
-            h[:notes] << unquote(field[:note])
+            h[:notes] << normalize_heredoc(unquote(field[:note]).to_s)
           when field.key?(:provenance)
             h[:provenance] ||= []
             h[:provenance] << unquote(field[:provenance])
           when field.key?(:relations)
             h[:relations] = extract_relations(field[:relations])
           when field.key?(:description)
-            h[:description] = normalize_heredoc(unescape_braces(field[:description].to_s))
+            h[:description] = normalize_heredoc(unescape_braces(field[:description].to_s)) + "\n"
           when field.key?(:field_name)
             # Generic field: identifier + raw value
             name = ident(field[:field_name]).to_sym
             if field.key?(:field_block)
-              h[name] = normalize_heredoc(unescape_braces(field[:field_block].to_s))
+              val = normalize_heredoc(unescape_braces(field[:field_block].to_s))
             else
               raw = field[:field_value]
-              val_str = case raw
-                        when Hash
-                          raw.key?(:string) ? unquote(raw) : (raw[:raw]&.to_s || "").strip
-                        when nil then ""
-                        else raw.to_s.strip
-                        end
-              h[name] = val_str
+              val = case raw
+                    when Hash
+                      raw.key?(:string) ? unquote(raw) : (raw[:raw]&.to_s || "").strip
+                    when nil then ""
+                    else raw.to_s.strip
+                    end
+            end
+            # DSL stores these as Arrays — match that convention.
+            if ARRAY_METADATA_FIELDS.include?(name)
+              h[name] = val.to_s.empty? ? [] : [val]
+            else
+              h[name] = val
             end
           else
             # Specific named field (authority, name, system_status, etc.)

lib/interscript/isc/grammar/concerns/metadata.rb

@@ -92,7 +92,7 @@ module Metadata
 
           rule(:notes_field) do
             str("notes") >> whitespace? >>
-              braced(note_line.repeat(0)).as(:notes)
+              braced(note_line.repeat(0).as(:notes))
           end
 
           rule(:note_line) do