hypertabular-wasm 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45321a399589d7b434c5e4567e0f8b687b4629a54410fd617007e2eecec592c8
+  data.tar.gz: 28e88b7113da58fcc27d699e27cb936478e334130a0dd4646457b57a2e016f99
+SHA512:
+  metadata.gz: 134a1f69690ab5c38230bc080fbcd8574cdbad03e8a218f0e9826835649fa2b8da4390bba0b4c228ef7f6abe34e0e6fbae1b8f893e8708b4a52877ab89fb74f8
+  data.tar.gz: 2e7172f099dedb51cfa2f3bf7cf28a49e5d3da94ab1998009972e554cb75711c5e35dd24c84c2fbae8ffd24b5b439da43be393d14cfa5032cc0895bc29dc958f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skunk Werkx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,179 @@
+# hypertabular
+
+Delimited text — CSV, TSV, any single-byte ASCII separator — and workbooks — XLSX and ODS —
+read a batch at a time into typed columns, with a
+[HyperCast](https://github.com/SkunkWerkx/HyperCast) verdict for every cell.
+
+```ruby
+require "hypertabular"
+
+plan = [
+  HyperTabular::Column.i32(0),
+  HyperTabular::Column.text(1),
+  HyperTabular::Column.f64(2)
+]
+
+HyperTabular::DelimitedReader.open("orders.csv", HyperTabular::Dialect::CSV, plan) do |reader|
+  reader.header                       # => ["id", "name", "score"]
+
+  while (batch = reader.read)
+    # A column at a time, decoded in one pass — nil where a cell did not cast…
+    ids = batch.values(0)
+
+    # …or a cell at a time, as HyperCast's union.
+    batch.rows.times do |row|
+      case batch.get(2, row)
+      in HyperCast::Success(value:)
+        puts "#{batch.values(1)[row]}: #{value}"
+      in HyperCast::Fault(reason:, offset:, length:)
+        warn "line #{batch.line(row)}: #{reason} in #{batch.raw(2, row).inspect}"
+      end
+    end
+  end
+end
+
+# A workbook reads into the same batch.
+book = HyperTabular::Workbook.open("orders.xlsx")
+book.sheets                           # => [#<data HyperTabular::SheetInfo name="Orders", hidden=false>]
+sheet = book.sheet("Orders", HyperTabular::SheetOptions::DEFAULT, plan)
+while (batch = sheet.read)
+  # …
+end
+```
+
+`reader.each_row` walks every remaining row as an Array of verdicts, for when a row at a
+time is what the caller wants; `sheet.each_batch` walks a sheet's batches.
+
+## The shape
+
+The native core (`libhypertabular`) owns no memory and reads no files. `DelimitedReader`
+and `Sheet` allocate the buffers — one value array and one verdict array per column, the
+table that locates each cell — once, and reuse them for every batch. The core fills them in one
+native call per batch, and a column comes out of its buffer in one `String#unpack`: the
+boundary is crossed once per few thousand rows, not once per cell.
+
+- **One batch class.** `read` returns a `HyperTabular::Batch` — `rows`, `columns`,
+  `line(row)`, `values(column)`, `verdicts(column)`, `get(column, row)` and `raw(column,
+  row)` — or `nil` once there are no more rows, for delimited text and a sheet alike. A
+  batch owns what it shows: it stays good after the reader has moved on.
+- **Nothing is sniffed.** The `Dialect` states the separator, the quoting and the header;
+  `SheetOptions` states a sheet's header and whether empty rows are skipped; the plan
+  states each column's door and, for numbers, its `HyperCast::NumFormat`.
+- **HyperCast is the judge.** `HyperCast::Success`, `HyperCast::Fault`,
+  `HyperCast::NumFormat`, `HyperCast::Decimal` and the declared options (`:milliseconds`,
+  `:day_month_year`, `:y1904`) are the `hypercast` gem's own. A text cell means exactly
+  what HyperCast's door would say of the same text, a typed workbook cell is converted by
+  the door directly, and either comes back as the Ruby type that gem returns for it.
+- **A bad value is a verdict; a broken file is an exception.** A cell that does not cast
+  is a `Fault` in its column and the read goes on. A record of the wrong width, input that
+  ends inside a quoted cell, a workbook whose container or parts cannot be read, is a
+  `HyperTabular::TabularError` carrying `kind`, `record`, `line`, `byte`, `expected` and
+  `found`, raised after every intact row before it.
+- **The text of any cell is to hand.** `batch.raw(column, row)` is what the cell was cast
+  from, whatever its door and verdict, and a `Fault`'s span indexes it in the units
+  `String#[]` slices by, as HyperCast's gem does: `raw[fault.offset, fault.length]` is the
+  offending text.
+- **A String is read in place.** An IO is read forward only, through a buffer that grows
+  when a record does not fit it.
+
+## The doors
+
+One factory per door, named as HyperCast names them.
+
+| Factory | Value |
+|---|---|
+| `Column.bool(n)` | `true` / `false` |
+| `Column.i8` `i16` `i32` `i64` `u8` `u16` `u32` `u64(n, format = INVARIANT)` | `Integer` |
+| `Column.f32` `f64(n, format = INVARIANT)` | `Float` |
+| `Column.decimal(n, format = INVARIANT)` | `HyperCast::Decimal`, exact |
+| `Column.uuid(n)` | lowercase hyphenated `String` |
+| `Column.timestamp(n)` | UTC `Time`, nanosecond fidelity |
+| `Column.unix(n, :seconds / :milliseconds / :microseconds / :nanoseconds)` | UTC `Time` |
+| `Column.excel_serial(n, :y1900 / :y1904)` | UTC `Time` |
+| `Column.date(n)` | `Date`, strict `yyyy-MM-dd` |
+| `Column.date(n, order)` / `Column.date_ordered(n, order)` | `Date`, under `:year_month_day`, `:month_day_year` or `:day_month_year` |
+| `Column.datetime(n, order)` | `DateTime`, zone-less |
+| `Column.time(n)` | `Integer` nanoseconds since midnight |
+| `Column.duration(n)` | `Rational` seconds |
+| `Column.text(n)` | UTF-8 `String`, untrimmed |
+
+## Backends
+
+| `HyperTabular::BACKEND` | What runs | Chosen when |
+|---|---|---|
+| `:native` | the core linked into a Magnus extension | a precompiled platform gem is installed — each carries an extension for Ruby 3.4 and 4.0 — or the `hypertabular-wasm` gem is linked into a ruby.wasm interpreter; see [Ruby in the browser](#ruby-in-the-browser) |
+| `:fiddle` | `libhypertabular` for this platform, `dlopen`ed through Fiddle | no extension loads: the universal gem, on a Ruby or platform no platform gem covers (Intel macOS, Ruby 3.3, Ruby 4.1 and later) |
+
+Selection happens once, at `require`, in that order. Both backends read a batch in one native
+call and hand back the same bytes; everything above that crossing — the readers, the
+workbook, `Batch` and every value and verdict it builds — is the same Ruby on either, and
+`spec/native_backend_spec.rb` holds the two to the same answer over every cell of both corpora.
+So the extension is not where a read gets faster (the crossing was already once per batch);
+what it buys is a platform gem with no shared library for Fiddle to find, and Ruby in the
+browser, where there is no Fiddle at all.
+
+`HYPERTABULAR_PURE` forces `:fiddle`, as `HYPERCAST_PURE` does for hypercast. It is a testing
+and diagnostic switch — CI runs the whole suite through it — read for presence, not value. A
+forced backend with nothing to load does not fall through: the first reader raises, and
+`HyperTabular.available?` answers `false`. Inside a platform gem, which carries no Fiddle
+library, that `LoadError` names the universal gem (`gem install hypertabular --platform ruby`,
+or Bundler's `force_ruby_platform`). `HyperTabular.available?` and `HyperTabular.native_version`
+answer whether the core resolved, without the first read being what finds out.
+
+**Threads.** A reader or a sheet is one thread's at a time, on either backend. The extension
+runs under the GVL; Fiddle releases it for each call.
+
+## Ruby in the browser
+
+ruby.wasm cannot load an extension at runtime: `rbwasm build` links the extension of every gem
+in a Gemfile into the one interpreter it builds. So the browser gets a gem of its own,
+`hypertabular-wasm` — the same library and the same Magnus extension, prebuilt for
+`wasm32-wasip1` — which brings `hypercast-wasm`, HyperCast's own, with it. List it **instead
+of** `hypertabular` in the Gemfile you build the interpreter from:
+
+```ruby
+source "https://rubygems.org"
+
+gem "hypertabular-wasm"
+gem "js" # JavaScript interop, which a browser app almost always wants
+
+group :development do
+  gem "ruby_wasm"
+end
+```
+
+```sh
+bundle install
+bundle exec rbwasm build --ruby-version 4.0 -o ruby.wasm
+```
+
+Load `ruby.wasm` with [`@ruby/wasm-wasi`](https://www.npmjs.com/package/@ruby/wasm-wasi), then
+`require "/bundle/setup"` and `require "hypertabular"` as anywhere else. A workbook is read
+from its bytes (`HyperTabular::Workbook.new(bytes)`) — a `fetch`ed file, an upload — and
+delimited text from a String or any IO.
+
+- **Ruby 3.4 and 4.0**, one archive each, picked by `--ruby-version`; any other minor stops the
+  build naming the ones the gem carries. Built and tested against ruby_wasm 2.10.
+- **No Rust toolchain.** The gem's `extconf.rb` only hands rbwasm the prebuilt archive. The
+  first `rbwasm build` compiles Ruby itself and takes 15–20 minutes; later builds reuse it.
+- **Static linking only,** into ruby.wasm's default `wasm32-unknown-wasip1` interpreter.
+- **Beside HyperCast.** Every Rust extension that carries std defines a few of the same
+  symbols (`rust_eh_personality`, rb-sys's `ruby_abi_version`, one of std's); this gem and
+  `hypercast-wasm` each rename them to names of their own when CI builds the archive, and the
+  build fails if a newer Rust starts exporting another.
+
+What stands behind it: CI builds each minor's archive from the commit, packs the gem the way
+it ships, links it into a fresh interpreter and runs [`wasm-smoke/test.rb`](wasm-smoke/test.rb)
+under Node and in headless Chrome (the forge's `hyper-build-wasm.yml`). The published gem is
+packed around those attested archives.
+
+## Development
+
+```sh
+cd rust && cargo cdylib                 # builds rust/target/release/libhypertabular.*
+cd ../ruby && bundle install
+HYPERTABULAR_PURE=1 bundle exec rspec   # the Fiddle backend: replays both corpora
+bundle exec rake native:dev             # builds the Magnus extension for this Ruby, staged
+bundle exec rspec                       # the extension, and its agreement with Fiddle
+bundle exec rake docs:check
+```

data/ext/hypertabular_native/extconf.rb

@@ -0,0 +1,108 @@
+# The hypertabular-wasm gem's extension: the Magnus extension, linked statically into a
+# ruby.wasm interpreter by `rbwasm build` — hypercast-wasm's extconf, for this crate. ruby.wasm
+# cannot load an extension at runtime, so a consumer puts this gem in the Gemfile they hand to
+# rbwasm and gets one interpreter with HyperTabular compiled in, beside HyperCast's own. Only
+# this companion gem ships this file; the hypertabular gems do not, because an `extensions`
+# entry there would run extconf on every host `gem install`.
+#
+# Bundler installs the gem on the host first, where there is nothing to build. Then rbwasm runs
+# this again with the cross-compiled Ruby's RbConfig, `make clean`, `make static`, and links
+# every *.a left in the build directory. Both paths below end in the same place: the archive
+# saved as hypertabular_native.prebuilt (not *.a, which `make clean` removes), copied into place
+# by `make static`.
+#
+#  * Prebuilt, what a consumer gets: the gem carries one gzipped archive per Ruby minor (Rakefile,
+#    wasm:gem), built and attested in CI. No Rust toolchain on the consumer's machine.
+#  * From source, how CI makes those archives: HYPERTABULAR_RUST_DIR names the crate, and
+#    HYPERTABULAR_WASM_OUT, if set, receives a copy of the finished archive.
+require "mkmf"
+require "rbconfig"
+require "zlib"
+require "fileutils"
+
+unless RbConfig::CONFIG["host_os"].include?("wasi")
+  File.write("Makefile", dummy_makefile($srcdir).join)
+  exit
+end
+
+# rbwasm reads $target back out to name the extension's Init function in its extinit table.
+$target = "hypertabular_native"
+minor = "#{RbConfig::CONFIG["MAJOR"]}.#{RbConfig::CONFIG["MINOR"]}"
+prebuilt = "hypertabular_native.prebuilt"
+
+if (rust_dir = ENV["HYPERTABULAR_RUST_DIR"])
+  # rb-sys binds against the target Ruby through RBCONFIG_* variables. Ruby is not installed
+  # yet when rbwasm builds extensions, so the two header directories point at the source and
+  # build trees instead (rbwasm sets top_srcdir and extout for exactly this).
+  RbConfig::CONFIG.merge(
+    "rubyhdrdir" => File.join(ENV.fetch("top_srcdir"), "include"),
+    "rubyarchhdrdir" => File.join(ENV.fetch("extout"), "include", RbConfig::CONFIG["arch"])
+  ).each { |key, value| ENV["RBCONFIG_#{key}"] = value.to_s }
+  wasi_sdk = File.dirname(File.dirname(RbConfig::CONFIG["CC"].split.first))
+  ENV["BINDGEN_EXTRA_CLANG_ARGS"] = "--sysroot=#{wasi_sdk}/share/wasi-sysroot " \
+                                    "-D_WASI_EMULATED_SIGNAL -D_WASI_EMULATED_PROCESS_CLOCKS -D_WASI_EMULATED_MMAN"
+  ENV["CC_wasm32_wasip1"] = "#{wasi_sdk}/bin/clang"
+  target_dir = File.expand_path("target")
+  system("cargo", "rustc", "--manifest-path", File.join(rust_dir, "Cargo.toml"), "--release",
+         "--target", "wasm32-wasip1", "--crate-type", "staticlib", "--features", "ruby",
+         "--target-dir", target_dir, exception: true)
+  archive = File.binread(File.join(target_dir, "wasm32-wasip1/release/libhypertabular.a"))
+  # The crate links into one object (release LTO), and besides Init_hypertabular_native and
+  # the C ABI it exports three symbols that every Rust extension carrying std defines too:
+  # rust_eh_personality, which wasi-vfs (linked into every ruby.wasm) also defines;
+  # ruby_abi_version, rb-sys's ABI stamp for a dynamically loaded extension, which a static
+  # one never needs; and std's EMPTY_PANIC. Two definitions of any of them stop the link, so
+  # each is renamed to one this crate owns, and the HyperCast extension this gem always runs
+  # beside, renamed the same way to names of its own, can share the interpreter. wasm
+  # llvm-objcopy can neither localize nor rename a symbol, so the names are rewritten in place
+  # at the same length, which leaves every offset in the archive and its objects valid (and
+  # keeps EMPTY_PANIC's v0 mangling well-formed). Nothing calls the first two: a static
+  # extension's ABI stamp is never looked up, and wasm32-wasip1 builds with panic=abort.
+  {
+    "rust_eh_personality" => "hypertab_eh_persona",
+    "ruby_abi_version" => "hypertabl_abiver",
+    "9panicking11EMPTY_PANIC" => "9panicking11HTABL_PANIC"
+  }.each { |from, to| archive.gsub!(from, to) }
+  File.binwrite(prebuilt, archive)
+  system("#{wasi_sdk}/bin/llvm-ranlib", prebuilt, exception: true)
+  # And a newer Rust that exports another of std's symbols fails here, by name, rather than in
+  # the link of an interpreter that also carries the HyperCast extension.
+  member = nil
+  exported = IO.popen(["#{wasi_sdk}/bin/llvm-nm", "--defined-only", "--extern-only", prebuilt], err: File::NULL, &:read)
+               .each_line(chomp: true).filter_map do |line|
+    if line.end_with?(".o:")
+      member = line
+      next
+    end
+    line.split.last if member&.start_with?("hypertabular-") && line.match?(/\A\h+ [A-Z] /)
+  end
+  shared = exported.grep(/\A(_R|_ZN|rust_|__rust|ruby_abi_version\z)/).grep_v(/HTABL_PANIC\z/)
+  shared.empty? or abort "hypertabular-wasm: the extension exports #{shared.join(", ")}, which " \
+                         "another Rust extension in the same interpreter would define too"
+  if (out = ENV["HYPERTABULAR_WASM_OUT"])
+    FileUtils.mkdir_p(File.join(out, minor))
+    FileUtils.cp(prebuilt, File.join(out, minor, "hypertabular_native.a"))
+  end
+else
+  gz = File.join(__dir__, minor, "hypertabular_native.a.gz")
+  unless File.exist?(gz)
+    shipped = Dir[File.join(__dir__, "*", "hypertabular_native.a.gz")].map { |f| File.basename(File.dirname(f)) }
+    abort "hypertabular-wasm: no prebuilt extension for Ruby #{minor} (this gem carries #{shipped.sort.join(", ")})"
+  end
+  File.binwrite(prebuilt, Zlib::GzipReader.open(gz, &:read))
+end
+
+# install-so is rbwasm's dynamic-linking path (a pic target, for the component model), which
+# a static archive cannot serve.
+File.write("Makefile", <<~MAKE)
+  all: static
+  static:
+  \tcp #{prebuilt} hypertabular_native.a
+  install-so:
+  \t@echo "hypertabular-wasm links statically: build a wasm32-unknown-wasip1 interpreter" >&2; exit 1
+  install-rb:
+  \t@true
+  clean:
+  \trm -f hypertabular_native.a
+  .PHONY: all static install-so install-rb clean
+MAKE

data/lib/hypertabular/batch.rb

@@ -0,0 +1,204 @@
+module HyperTabular
+  # The rows one DelimitedReader#read or Sheet#read delivered, as typed columns: the same
+  # class for delimited text and for a sheet of a workbook.
+  #
+  #   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 "line #{batch.line(row)}: #{reason} in #{batch.raw(2, row).inspect}"
+  #       end
+  #     end
+  #   end
+  #
+  # A batch owns what it shows — the arrays the core wrote are copied out of the reader's
+  # buffers as it is made — so it stays good after the reader has moved on. Values are
+  # HyperCast's gem's own for the same doors: true/false, Integer, Float, HyperCast::Decimal,
+  # a hyphenated UUID String, a UTC Time, Date, DateTime, Integer nanoseconds since midnight,
+  # Rational seconds, and a UTF-8 String for text.
+  class Batch
+    # The verdict of every cell that had no bytes at all: one shared, frozen Fault.
+    EMPTY = HyperCast::Fault.new(reason: :empty, offset: 0, length: 0)
+
+    # The doors whose column is one String#unpack directive away from its values: HyperCast's
+    # directive for one value, repeated down the column.
+    SCALARS = HyperCast::Interop::SCALARS.transform_values { |directive| "#{directive}*" }.freeze
+
+    # The doors whose value is a record: HyperCast's directive for one, how many fields it
+    # yields, and what builds the Ruby value HyperCast's own door returns from them.
+    RECORDS = HyperCast::Interop::RECORDS
+
+    # How many rows the batch holds — never zero.
+    attr_reader :rows
+
+    # The plan the batch was read through: column +i+ of the batch is +columns[i]+.
+    attr_reader :columns
+
+    # Made by a reader from what the core just wrote, copied: +values+ and +verdicts+ per
+    # plan column, the cell table (+per_row+ spans a row), what an unflagged span indexes
+    # (+base+, from +origin+) and what a flagged one does (+arena+).
+    def initialize(plan, rows, values, verdicts, cells, per_row, base, origin, arena, workbook:)
+      @columns = plan
+      @rows = rows
+      @bytes = values
+      @verdict_bytes = verdicts
+      @cells = cells
+      @per_row = per_row
+      @base = base
+      @origin = origin
+      @arena = arena.force_encoding(Encoding::UTF_8)
+      @workbook = workbook
+      @values = Array.new(plan.size)
+      @verdicts = Array.new(plan.size)
+      @faults = Array.new(plan.size)
+    end
+
+    # Where row +row+ came from: for delimited text the 1-based line its record starts on,
+    # for a sheet its 1-based row number. IndexError for a row outside the batch.
+    def line(row)
+      offset, length = @cells.unpack("L<L<", offset: (at(row) * @per_row + @per_row - 1) * 8)
+      @workbook ? offset : length
+    end
+
+    # A column's values, one per row, as a frozen Array: the Ruby value HyperCast's gem
+    # returns from the same door, and nil for a cell that did not cast. Decoded in one pass
+    # the first time it is asked for.
+    def values(column)
+      @values[column] ||= decode(@columns.fetch(column), column)
+    end
+
+    # A column's verdicts, one per row, as a frozen Array of HyperCast::Success and
+    # HyperCast::Fault. A Fault's span is in the units String#[] slices by on the cell's own
+    # text, as HyperCast's are: `raw(column, row)[offset, length]` is the offending text.
+    def verdicts(column)
+      @verdicts[column] ||= judge(column)
+    end
+
+    # The cell at (+column+, +row+) as HyperCast judged it — made for `case`/`in`:
+    #
+    #   case batch.get(0, row)
+    #   in HyperCast::Success(value:) then value
+    #   in HyperCast::Fault(reason: :empty) then nil
+    #   in HyperCast::Fault(reason:, offset:, length:) then raise "#{reason} at #{offset}"
+    #   end
+    #
+    # Only this cell's verdict is built. IndexError for a column outside the plan or a row
+    # outside the batch.
+    def get(column, row)
+      index = at(row)
+      judged = @verdicts[column]
+      return judged[index] if judged
+
+      cell(column, index, values(column), faults(column))
+    end
+
+    # The text the cell at (+column+, +row+) was cast from, whatever its door and whatever
+    # its verdict — what a Fault's span indexes, and what to show for a value that did not
+    # cast. A UTF-8 String, quotes resolved. For a sheet this is a text cell's own text, and
+    # what a typed cell was said as when it failed its door (or went through the text door);
+    # a typed cell that cast has none. IndexError for a column outside the plan or a row
+    # outside the batch.
+    def raw(column, row)
+      plan = @columns.fetch(column)
+      entry = at(row) * @per_row + (@workbook ? column : plan.ordinal)
+      offset, length = @cells.unpack("L<L<", offset: entry * 8)
+      return slice(offset, length) if @workbook || length < Runtime::Delimited::SPAN_FLAG
+
+      # A quoted cell with an escaped quote in it: unescaped, as the core cast it.
+      quoted = @base.byteslice(@origin + offset, length & Runtime::Delimited::SPAN_LENGTH)
+      Runtime.unescape(quoted).force_encoding(Encoding::UTF_8)
+    end
+
+    # The batch in a line — not its cells.
+    def inspect
+      "#<#{self.class.name} rows=#{@rows} columns=#{@columns.size}>"
+    end
+
+    private
+
+    # The bytes a span names: in the arena when it is flagged, in the base when not.
+    def slice(offset, length)
+      return @arena.byteslice(offset, length & Runtime::Delimited::SPAN_LENGTH) if length >= Runtime::Delimited::SPAN_FLAG
+
+      @base.byteslice(@origin + offset, length)
+    end
+
+    # +row+ as an index into the batch, or an IndexError.
+    def at(row)
+      return row if row.is_a?(Integer) && row >= 0 && row < @rows
+
+      raise IndexError, "row #{row.inspect} is outside the batch (#{@rows} rows)"
+    end
+
+    # A column's verdict array as the core wrote it — offset, length, reason per row, flat
+    # — or nil when every cell cast, which one pass over the bytes answers without
+    # unpacking anything.
+    def faults(index)
+      flat = @faults[index]
+      if flat.nil?
+        bytes = @verdict_bytes.fetch(index)
+        flat = @faults[index] = bytes.count("\0") == bytes.bytesize ? false : bytes.unpack("L<*")
+      end
+      flat || nil
+    end
+
+    # A column's values out of its array: one String#unpack over the whole column, then the
+    # door's Ruby type built for each row that cast.
+    def decode(column, index)
+      door = column.door
+      bytes = @bytes.fetch(index)
+      faults = faults(index)
+      if (directive = SCALARS[door])
+        values = bytes.unpack(directive)
+        values.map! { |byte| byte != 0 } if door == :bool
+        @rows.times { |row| values[row] = nil unless faults[row * 3 + 2].zero? } if faults
+      elsif door == :text
+        values = texts(bytes.unpack("L<*"), faults)
+      else
+        directive, width, build = RECORDS.fetch(door)
+        fields = bytes.unpack(directive * @rows)
+        values = Array.new(@rows) do |row|
+          build.call(fields, row * width) if faults.nil? || faults[row * 3 + 2].zero?
+        end
+      end
+      values.freeze
+    end
+
+    # A text column's values: each span sliced out of the input or the shared strings, or —
+    # flagged — out of the arena.
+    def texts(spans, faults)
+      Array.new(@rows) do |row|
+        slice(spans[row * 2], spans[row * 2 + 1]) if faults.nil? || faults[row * 3 + 2].zero?
+      end
+    end
+
+    # A column's verdicts: a Success around each value, a Fault where the core says so.
+    def judge(column)
+      values = values(column)
+      faults = faults(column)
+      return values.map { |value| HyperCast::Success.new(value: value) }.freeze if faults.nil?
+
+      Array.new(@rows) { |row| cell(column, row, values, faults) }.freeze
+    end
+
+    # One cell's verdict, from its column's values and the core's verdict array.
+    def cell(column, row, values, faults)
+      reason = faults.nil? ? 0 : faults[row * 3 + 2]
+      return HyperCast::Success.new(value: values[row]) if reason.zero?
+
+      fault(column, row, reason, faults[row * 3], faults[row * 3 + 1])
+    end
+
+    # One Fault, its span moved from the bytes the core counts in to the characters
+    # String#[] slices by — an identity unless the cell's text has a multi-byte character.
+    def fault(column, row, reason, offset, length)
+      return EMPTY if reason == 1 && offset.zero? && length.zero?
+
+      unless offset.zero? && length.zero?
+        offset, length = HyperCast::Interop.characters(raw(column, row), offset, length)
+      end
+      HyperCast::Interop.fault(reason, offset, length)
+    end
+  end
+end