hypertabular-wasm 0.7.0

data/lib/hypertabular/column.rb

@@ -0,0 +1,170 @@
+module HyperTabular
+  # The doors a column can be cast through, by the code the core knows each as: HyperCast's
+  # twenty-one, named as its gem names them, plus :text for the bytes themselves.
+  DOORS = {
+    bool: 1, i8: 2, i16: 3, i32: 4, i64: 5, u8: 6, u16: 7, u32: 8, u64: 9, f32: 10, f64: 11,
+    uuid: 12, timestamp: 13, unix: 14, date: 15, time: 16, duration: 17, text: 18, decimal: 19,
+    date_ordered: 20, datetime: 21, excel_serial: 22
+  }.freeze
+
+  # One output column of a plan: which source column it reads, the door it casts through,
+  # what that door declares, and — for the numeric doors — the notation. A plan is a
+  # projection: a forty-column file can be read into five typed columns, in any order, and
+  # a source column can be read through more than one door.
+  #
+  # Built by the factory named after its door, never guessed from the data:
+  #
+  #   plan = [
+  #     HyperTabular::Column.i32(0),
+  #     HyperTabular::Column.text(1),
+  #     HyperTabular::Column.decimal(2, eurozone),
+  #     HyperTabular::Column.date(3, :day_month_year),
+  #     HyperTabular::Column.unix(4, :milliseconds)
+  #   ]
+  #
+  # +ordinal+ is the zero-based source column; past a record's last cell it reads as empty.
+  # +door+ is a key of DOORS. +declared+ is the Symbol the door was declared with — a Unix
+  # precision, a date order, an Excel epoch, as HyperCast names them — or nil. +format+ is
+  # the HyperCast::NumFormat of a numeric door, or nil.
+  Column = Data.define(:ordinal, :door, :declared, :format) do
+    # Checks the column as the caller bug it would otherwise become at the first read: an
+    # ordinal that is not a non-negative Integer or a format that is not a
+    # HyperCast::NumFormat (ArgumentError), an unknown door or an undeclared option
+    # (KeyError, as HyperCast raises for the same).
+    def initialize(ordinal:, door:, declared: nil, format: nil)
+      raise ArgumentError, "ordinal must be an Integer in 0..#{Column::MAX_ORDINAL}; got #{ordinal.inspect}" unless
+        ordinal.is_a?(Integer) && ordinal.between?(0, Column::MAX_ORDINAL)
+
+      DOORS.fetch(door)
+      if (options = Column::DECLARES[door])
+        options.fetch(declared)
+      elsif !declared.nil?
+        raise ArgumentError, "the #{door} door declares nothing; got #{declared.inspect}"
+      end
+      if Column::NUMERIC.include?(door)
+        format = HyperCast::NumFormat::INVARIANT if format.nil?
+        raise ArgumentError, "format must be a HyperCast::NumFormat; got #{format.inspect}" unless
+          format.is_a?(HyperCast::NumFormat)
+      elsif !format.nil?
+        raise ArgumentError, "the #{door} door reads no numeric format"
+      end
+
+      super(ordinal: ordinal, door: door, declared: declared, format: format)
+    end
+
+    # A boolean column: HyperCast's boolean lexicon, as true or false.
+    def self.bool(ordinal) = new(ordinal: ordinal, door: :bool)
+
+    # A signed 8-bit column, as an Integer. Invariant notation unless one is declared.
+    def self.i8(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :i8, format: format)
+
+    # A signed 16-bit column, as an Integer. Invariant notation unless one is declared.
+    def self.i16(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :i16, format: format)
+
+    # A signed 32-bit column, as an Integer. Invariant notation unless one is declared.
+    def self.i32(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :i32, format: format)
+
+    # A signed 64-bit column, as an Integer. Invariant notation unless one is declared.
+    def self.i64(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :i64, format: format)
+
+    # An unsigned 8-bit column, as an Integer. Invariant notation unless one is declared.
+    def self.u8(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :u8, format: format)
+
+    # An unsigned 16-bit column, as an Integer. Invariant notation unless one is declared.
+    def self.u16(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :u16, format: format)
+
+    # An unsigned 32-bit column, as an Integer. Invariant notation unless one is declared.
+    def self.u32(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :u32, format: format)
+
+    # An unsigned 64-bit column, as the true unsigned Integer. Invariant notation unless
+    # one is declared.
+    def self.u64(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :u64, format: format)
+
+    # An IEEE single column, widened losslessly to a Float. Invariant notation unless one
+    # is declared.
+    def self.f32(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :f32, format: format)
+
+    # An IEEE double column, as a Float. Invariant notation unless one is declared.
+    def self.f64(ordinal, format = HyperCast::NumFormat::INVARIANT) = new(ordinal: ordinal, door: :f64, format: format)
+
+    # An exact decimal column, as a HyperCast::Decimal; no float is ever formed. Invariant
+    # notation unless one is declared.
+    def self.decimal(ordinal, format = HyperCast::NumFormat::INVARIANT)
+      new(ordinal: ordinal, door: :decimal, format: format)
+    end
+
+    # A UUID column, as the lowercase hyphenated String.
+    def self.uuid(ordinal) = new(ordinal: ordinal, door: :uuid)
+
+    # An RFC 3339 instant column, as a UTC Time at full nanosecond fidelity.
+    def self.timestamp(ordinal) = new(ordinal: ordinal, door: :timestamp)
+
+    # A Unix-epoch column at the declared precision (:seconds, :milliseconds,
+    # :microseconds, :nanoseconds) — never guessed from magnitude — as a UTC Time.
+    def self.unix(ordinal, precision) = new(ordinal: ordinal, door: :unix, declared: precision)
+
+    # An Excel date-serial column under the declared date system (:y1900, :y1904), as a
+    # UTC Time.
+    def self.excel_serial(ordinal, epoch) = new(ordinal: ordinal, door: :excel_serial, declared: epoch)
+
+    # A calendar date column, as a Date. With no order declared: the strict ISO 8601
+    # yyyy-MM-dd door. With one (:year_month_day, :month_day_year, :day_month_year): the
+    # date_ordered door, which also reads the separated forms — the same split
+    # HyperCast.date makes.
+    def self.date(ordinal, order = nil)
+      order.nil? ? new(ordinal: ordinal, door: :date) : date_ordered(ordinal, order)
+    end
+
+    # A separated calendar date column under the declared field order, as a Date.
+    def self.date_ordered(ordinal, order) = new(ordinal: ordinal, door: :date_ordered, declared: order)
+
+    # A zone-less civil date-time column under the declared field order, as a DateTime
+    # whose +00:00 offset is a carrier artifact, not data — the text named no zone.
+    def self.datetime(ordinal, order) = new(ordinal: ordinal, door: :datetime, declared: order)
+
+    # A 24-hour time-of-day column, as an exact Integer of nanoseconds since midnight.
+    def self.time(ordinal) = new(ordinal: ordinal, door: :time)
+
+    # A duration column, as exact Rational seconds.
+    def self.duration(ordinal) = new(ordinal: ordinal, door: :duration)
+
+    # A text column: the cell's bytes themselves, untrimmed, quotes resolved, as a UTF-8
+    # String. A cell with no bytes at all is the one way text fails (an :empty Fault).
+    def self.text(ordinal) = new(ordinal: ordinal, door: :text)
+
+    # Bytes one value of this column's door takes in a column buffer.
+    def value_bytes
+      Column::VALUE_BYTES.fetch(door)
+    end
+
+    # The 44 little-endian bytes of the core's ColumnSpec: ordinal, door code, what the
+    # door declares (numbered as HyperCast numbers it), then the notation in HyperCast's
+    # own packed form — all zeros, which the core reads as invariant, for a door that
+    # reads none.
+    def packed
+      param = declared.nil? ? 0 : Column::DECLARES.fetch(door).fetch(declared)
+      [ordinal, DOORS.fetch(door), param].pack("L<3") + (format.nil? ? Column::NO_FORMAT : format.packed)
+    end
+  end
+
+  # The widest source ordinal a column can name.
+  Column::MAX_ORDINAL = (1 << 31) - 1
+
+  # The doors that read a HyperCast::NumFormat: the integers, the reals and the decimal.
+  Column::NUMERIC = %i[i8 i16 i32 i64 u8 u16 u32 u64 f32 f64 decimal].freeze
+
+  # What the doors that declare something declare, as HyperCast's own tables number it.
+  Column::DECLARES = {
+    unix: HyperCast::UNIX_PRECISIONS,
+    excel_serial: HyperCast::EXCEL_EPOCHS,
+    date_ordered: HyperCast::DATE_ORDERS,
+    datetime: HyperCast::DATE_ORDERS
+  }.freeze
+
+  # Bytes per value in a column buffer, by door (rust/src/kernel/abi.rs, ColumnBuffer):
+  # HyperCast's for its doors, and a text cell's span — two u32s — for this one's.
+  Column::VALUE_BYTES = HyperCast::Interop::VALUE_BYTES.merge(text: 8).freeze
+
+  # The notation of a door that reads none: thirty-two zero bytes.
+  Column::NO_FORMAT = ("\0" * 32).b.freeze
+end

data/lib/hypertabular/delimited_reader.rb

@@ -0,0 +1,309 @@
+module HyperTabular
+  # Delimited text — CSV, TSV, any single-byte ASCII separator — read a batch at a time
+  # into typed columns, every cell a HyperCast verdict.
+  #
+  #   plan = [HyperTabular::Column.i32(0), HyperTabular::Column.text(1), HyperTabular::Column.f64(2)]
+  #   HyperTabular::DelimitedReader.open("orders.csv", HyperTabular::Dialect::CSV, plan) do |reader|
+  #     while (batch = reader.read)
+  #       ids = batch.values(0)                        # a column at a time: [1, 2, nil, 4, ...]
+  #       batch.rows.times do |row|
+  #         case batch.get(2, row)                     # or a cell at a time, as HyperCast's union
+  #         in HyperCast::Success(value:) then total += value
+  #         in HyperCast::Fault(reason:) then warn "#{reason}: #{batch.raw(2, row).inspect}"
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  # The native core (libhypertabular) owns no memory and reads no files. It is handed a
+  # chunk of input and the buffers to fill, casts each plan column in one native loop, and
+  # says how many rows it wrote and how many bytes it is finished with. Everything else is
+  # here: this class holds the input, has one value array and one verdict array per column
+  # allocated once and reused for every batch, and puts what the core did not consume back
+  # in front of it. The native boundary is crossed once per batch, not once per cell, and a
+  # column comes out of its buffer in one String#unpack.
+  #
+  # A value that does not cast is that cell's verdict, and the read goes on. Input that is
+  # not rows of cells at all — a record of the wrong width, a quote never closed — is a
+  # TabularError, raised after every intact row before it has been delivered.
+  #
+  # Each #read returns a Batch, which owns what it shows: it stays good after the next
+  # #read. Not thread-safe.
+  class DelimitedReader
+    # The row ceiling: a single record larger than this is a :row_too_long TabularError.
+    MAX_ROW_BYTES = 1 << 30
+
+    # How much is asked of an IO at a time, until a record does not fit.
+    DEFAULT_BUFFER_BYTES = 256 * 1024
+
+    # Rows per batch unless told otherwise.
+    DEFAULT_BATCH_ROWS = 4096
+
+    # Encodings whose bytes already are the UTF-8 (or byte-identical) form the core reads.
+    BYTE_COMPATIBLE = HyperCast::Interop::BYTE_COMPATIBLE
+
+    # Opens a file of UTF-8 delimited text. With a block, yields the reader, closes it —
+    # and the file — when the block ends, and returns the block's value; without one,
+    # returns the reader, whose #close closes the file.
+    def self.open(path, dialect, plan, batch_rows: DEFAULT_BATCH_ROWS, buffer_bytes: DEFAULT_BUFFER_BYTES)
+      file = File.open(path, "rb")
+      begin
+        reader = new(file, dialect, plan, batch_rows: batch_rows, buffer_bytes: buffer_bytes, close_source: true)
+      ensure
+        # The file is ours to close when no reader came of it, whatever went wrong.
+        file.close if reader.nil?
+      end
+      return reader unless block_given?
+
+      begin
+        yield reader
+      ensure
+        reader.close
+      end
+    end
+
+    # Reads UTF-8 delimited text from +source+: a String, read in place — nothing is copied
+    # — or an IO (anything with #readpartial or #read), read forward only through a buffer
+    # of +buffer_bytes+ that grows when a record does not fit it. An IO is read as bytes;
+    # one opened in text mode on Windows should be in binmode first.
+    #
+    # +dialect+ is the declared Dialect and +plan+ the output Columns, in output order.
+    # +batch_rows+ is the most rows one #read delivers. +close_source+ says whether #close
+    # also closes the IO.
+    #
+    # A dialect the scanner cannot honour, or a plan that is not Columns, is an
+    # ArgumentError. With a header declared the header record is read here, so a header
+    # that is structurally broken is a TabularError here.
+    def initialize(source, dialect, plan, batch_rows: DEFAULT_BATCH_ROWS, buffer_bytes: DEFAULT_BUFFER_BYTES,
+                   close_source: false)
+      raise ArgumentError, "dialect must be a HyperTabular::Dialect; got #{dialect.inspect}" unless
+        dialect.is_a?(Dialect)
+      raise ArgumentError, "batch_rows must be a positive Integer; got #{batch_rows.inspect}" unless
+        batch_rows.is_a?(Integer) && batch_rows.positive?
+      raise ArgumentError, "buffer_bytes must be a positive Integer; got #{buffer_bytes.inspect}" unless
+        buffer_bytes.is_a?(Integer) && buffer_bytes.positive?
+
+      @plan = Array(plan).dup.freeze
+      @plan.each_with_index do |column, index|
+        raise ArgumentError, "plan column #{index} must be a HyperTabular::Column; got #{column.inspect}" unless
+          column.is_a?(Column)
+      end
+      @dialect = dialect
+      @batch_rows = batch_rows
+      @buffer_bytes = buffer_bytes
+      @close_source = close_source
+      # Cell-table entries one row takes: the widest ordinal the plan reads, plus two.
+      per_row = (@plan.map(&:ordinal).max || -1) + 2
+      @kernel = Runtime::Delimited.start(dialect.packed, @plan.map(&:packed), @plan.map(&:value_bytes),
+                                         batch_rows, per_row)
+      raise ArgumentError, "separator #{dialect.separator.inspect} is not tab or printable ASCII other than '\"'" if
+        @kernel.nil?
+
+      @start = 0
+      @closed = false
+      @failure = nil
+      take(source)
+      @header = dialect.has_header ? read_header : nil
+    end
+
+    # The header's names, when the dialect declares a header: frozen UTF-8 Strings, quotes
+    # resolved. Empty for an input with no record at all; nil when the dialect declares no
+    # header.
+    attr_reader :header
+
+    # The plan: the output Columns, in output order. Column +i+ of every batch is +plan[i]+.
+    attr_reader :plan
+
+    # The declared Dialect.
+    attr_reader :dialect
+
+    # The most rows one #read delivers.
+    attr_reader :batch_rows
+
+    # Records finished so far — the header and skipped blank lines included.
+    def records
+      @kernel.records
+    end
+
+    # Reads the next batch: a Batch of up to #batch_rows rows, or nil once the input is
+    # exhausted. A TabularError when the input is structurally broken — raised after every
+    # intact row before the break has been delivered, and the same error again on every
+    # later call. IOError on a closed reader.
+    def read
+      raise IOError, "closed reader" if @closed
+      raise @failure if @failure
+
+      loop do
+        length, last = window
+        raise structural unless @kernel.fill(@start, length, last) == Runtime::Delimited::OK
+
+        consumed = @kernel.consumed
+        if @kernel.rows.positive?
+          batch = made(@kernel.rows)
+          @start += consumed
+          return batch
+        end
+        @start += consumed
+        return nil if last && (consumed == length || consumed.zero?)
+
+        refill if consumed.zero?
+      end
+    end
+
+    # Every remaining row, batch after batch: yields one frozen Array per row, a verdict
+    # per plan column. Without a block, an Enumerator. Raises what #read raises.
+    def each_row
+      return to_enum(:each_row) unless block_given?
+
+      while (batch = read)
+        columns = Array.new(@plan.size) { |column| batch.verdicts(column) }
+        batch.rows.times { |row| yield columns.map { |column| column[row] }.freeze }
+      end
+      self
+    end
+
+    # Closes the IO if this reader was told to (+close_source+, or DelimitedReader.open).
+    # Batches already read stay good. Safe to call twice.
+    def close
+      return if @closed
+
+      @closed = true
+      @io.close if @close_source && @io
+      nil
+    end
+
+    # True once #close has been called.
+    def closed?
+      @closed
+    end
+
+    # The reader in a line — not its buffers.
+    def inspect
+      "#<#{self.class.name} columns=#{@plan.size} records=#{records}#{' closed' if @closed}>"
+    end
+
+    private
+
+    # Takes the source: a String becomes the whole input, an IO the thing to refill from.
+    def take(source)
+      if source.is_a?(String)
+        @buffer = utf8(source)
+        @eof = true
+      elsif defined?(::Pathname) && source.is_a?(::Pathname)
+        # It has a #read, and one that starts the file over on every call.
+        raise ArgumentError, "source is a Pathname; DelimitedReader.open reads a path"
+      elsif source.respond_to?(:readpartial) || source.respond_to?(:read)
+        @io = source
+        @partial = source.respond_to?(:readpartial)
+        @buffer = String.new(encoding: Encoding::UTF_8)
+        @eof = false
+      else
+        raise ArgumentError, "source must be a String or an IO; got #{source.class}"
+      end
+      @kernel.attach(@buffer)
+    end
+
+    # The text as a frozen String of UTF-8 bytes that is this reader's alone: the caller's
+    # own when it is already that; otherwise a copy-on-write duplicate, which shares the
+    # bytes and is immune to what the caller does to theirs next. Only a foreign encoding
+    # pays a transcode.
+    def utf8(text)
+      return text if text.frozen? && text.encoding == Encoding::UTF_8
+      return text.dup.force_encoding(Encoding::UTF_8).freeze if BYTE_COMPATIBLE.include?(text.encoding)
+
+      text.encode(Encoding::UTF_8).freeze
+    end
+
+    # What the core is to read next — how many bytes from @start — and whether nothing
+    # follows them.
+    def window
+      length = @buffer.bytesize - @start
+      length > MAX_ROW_BYTES ? [MAX_ROW_BYTES, false] : [length, @eof]
+    end
+
+    # Puts the unfinished record at the front of the buffer and reads more behind it —
+    # at least as much again as is pending, so a record that does not fit doubles the
+    # buffer rather than creeping up on it.
+    def refill
+      pending = @buffer.bytesize - @start
+      raise too_long if @io.nil? || pending >= MAX_ROW_BYTES
+
+      chunk = more([@buffer_bytes, pending].max)
+      if chunk.nil? || chunk.empty?
+        @eof = true
+        return
+      end
+      chunk = chunk.dup if chunk.frozen?
+      @buffer = @buffer.byteslice(@start, pending) if @start.positive?
+      @buffer << chunk.force_encoding(Encoding::UTF_8)
+      @start = 0
+      @kernel.attach(@buffer)
+    end
+
+    # Up to +bytes+ more of the IO, or nil at its end. #readpartial where there is one, so
+    # a pipe or a socket hands over what it has rather than waiting to fill the request.
+    def more(bytes)
+      @partial ? @io.readpartial(bytes) : @io.read(bytes)
+    rescue EOFError
+      nil
+    end
+
+    # The batch the core just wrote, copied out of the kernel's arrays: its spans index the
+    # input from @start, where the core was handed it.
+    def made(rows)
+      columns = @kernel.columns
+      Batch.new(@plan, rows, Array.new(@plan.size) { |column| columns.values(column, rows) },
+                Array.new(@plan.size) { |column| columns.verdicts(column, rows) },
+                @kernel.cells, @kernel.per_row, @buffer, @start, @kernel.arena, workbook: false)
+    end
+
+    # Reads the header record: its names, or none for an input with no record at all.
+    def read_header
+      loop do
+        length, last = window
+        raise structural unless @kernel.header(@start, length, last) == Runtime::Delimited::OK
+
+        consumed = @kernel.consumed
+        if @kernel.rows.positive?
+          names = header_names
+          @start += consumed
+          return names
+        end
+        @start += consumed
+        # An empty input has no header and no rows; the width is unknown.
+        return [].freeze if last && (consumed == length || consumed.zero?)
+
+        refill if consumed.zero?
+      end
+    end
+
+    # The names the core just located: in the input as written, or — flagged — unescaped
+    # in the arena.
+    def header_names
+      spans = @kernel.names
+      arena = nil
+      Array.new(@kernel.rows) do |index|
+        offset = spans[index * 2]
+        length = spans[index * 2 + 1]
+        name =
+          if length < Runtime::Delimited::SPAN_FLAG
+            @buffer.byteslice(@start + offset, length)
+          else
+            arena ||= @kernel.arena.force_encoding(Encoding::UTF_8)
+            arena.byteslice(offset, length & Runtime::Delimited::SPAN_LENGTH)
+          end
+        name.freeze
+      end.freeze
+    end
+
+    # The structural failure the core just reported, kept: it is final.
+    def structural
+      @failure = TabularError.from(@kernel.failure)
+    end
+
+    # The failure of a record that outgrew the ceiling, kept: it is final too.
+    def too_long
+      @failure = TabularError.new(:row_too_long, @kernel.records, @kernel.line, @kernel.offset)
+    end
+  end
+end

data/lib/hypertabular/dialect.rb

@@ -0,0 +1,42 @@
+module HyperTabular
+  # How the text is delimited, declared by the caller. Nothing is sniffed: the separator is
+  # stated, quoting is stated, the header is stated — the same stance HyperCast's NumFormat
+  # takes for numeric notation.
+  #
+  # +separator+ is one byte: tab, or any printable ASCII character except the double quote.
+  # +quoting+ says whether " quotes cells (RFC 4180, "" for a literal quote); off, a quote
+  # is an ordinary byte. +has_header+ says whether the first record is a header, given by
+  # DelimitedReader#header and never delivered as a row. +skip_blank_lines+ says whether a
+  # completely empty line is skipped rather than read as a one-cell row.
+  #
+  #   HyperTabular::Dialect::CSV
+  #   HyperTabular::Dialect.new(separator: ";", has_header: false)
+  Dialect = Data.define(:separator, :quoting, :has_header, :skip_blank_lines) do
+    # Everything but the separator defaults to what CSV means: quoted, with a header, blank
+    # lines skipped. A separator that is not a one-byte String is a caller bug
+    # (ArgumentError); which bytes the scanner can honour is the core's to say, and it says
+    # so when a reader is built.
+    def initialize(separator:, quoting: true, has_header: true, skip_blank_lines: true)
+      raise ArgumentError, "separator must be a one-byte String; got #{separator.inspect}" unless
+        separator.is_a?(String) && separator.bytesize == 1
+
+      super(separator: -separator, quoting: quoting ? true : false,
+            has_header: has_header ? true : false, skip_blank_lines: skip_blank_lines ? true : false)
+    end
+
+    # The four bytes of the core's RawDialect: separator, quoting, skip_blank_lines, and
+    # the scan engine left to the core's own choice.
+    def packed
+      [separator.getbyte(0), quoting ? 1 : 0, skip_blank_lines ? 1 : 0, 0].pack("C4")
+    end
+  end
+
+  # Comma-separated, quoted, with a header, blank lines skipped.
+  Dialect::CSV = Dialect.new(separator: ",")
+
+  # Tab-separated, otherwise as CSV.
+  Dialect::TSV = Dialect.new(separator: "\t")
+
+  # Pipe-separated, otherwise as CSV.
+  Dialect::PSV = Dialect.new(separator: "|")
+end

data/lib/hypertabular/runtime/columns.rb

@@ -0,0 +1,46 @@
+module HyperTabular
+  module Runtime
+    # A plan as the core takes it, and the arrays the core casts it into: one packed
+    # ColumnSpec per plan column, one value array and one verdict array per column sized
+    # for one batch, and the ColumnBuffer table that names them — allocated once and reused
+    # for every batch. A delimited read and a sheet each own one.
+    class Columns
+      # Bytes in one verdict (CellVerdict: offset, len, reason — three u32).
+      VERDICT_BYTES = 12
+      # ColumnSpec: ordinal, door, param, then HyperCast's 32-byte RawNumFormat.
+      SPEC_BYTES = 44
+
+      # The packed specs (nil for no columns), the ColumnBuffer table (likewise), how many
+      # columns there are, and the most rows a batch holds.
+      attr_reader :specs, :table, :count, :batch_rows
+
+      # +specs+ is one packed ColumnSpec per plan column and +sizes+ the bytes one value of
+      # each takes.
+      def initialize(specs, sizes, batch_rows)
+        @sizes = sizes
+        @count = specs.size
+        @batch_rows = batch_rows
+        return if specs.empty?
+
+        @specs = Runtime.buffer(SPEC_BYTES * @count)
+        @specs[0, SPEC_BYTES * @count] = specs.join
+        @values = sizes.map { |size| Runtime.buffer(size * batch_rows) }
+        @verdicts = sizes.map { Runtime.buffer(VERDICT_BYTES * batch_rows) }
+        addresses = @values.zip(@verdicts).flatten.map(&:to_i).pack("J*")
+        @table = Runtime.buffer(addresses.bytesize)
+        @table[0, addresses.bytesize] = addresses
+      end
+
+      # A column's value array for the first +rows+ rows, copied out as the core wrote it.
+      def values(column, rows)
+        @values[column][0, @sizes[column] * rows]
+      end
+
+      # A column's verdict array for the first +rows+ rows — offset, len, reason per row —
+      # copied out as the core wrote it.
+      def verdicts(column, rows)
+        @verdicts[column][0, VERDICT_BYTES * rows]
+      end
+    end
+  end
+end