hypertabular 0.7.0-x86_64-linux-gnu

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f12aa45e29d73c5a083eb1cff5183a171522136110ccb5c110c7975536aaa041
+  data.tar.gz: 52a11c73b4fcd8a5851dd1b13b5451e0302cd00ba1985ea905ac765712bcad56
+SHA512:
+  metadata.gz: c9ea54c776214218dd62a0bbd664f5120ceefcc13ee8282126d8f586fb69c152509cba556c9b1880dc1127b1c8906b0c33a8a70b49c8a4832d2960e28e350056
+  data.tar.gz: c7c55e4fabf853870dc46bb9e770dd00b258f71cc8772c49ac48d6c740b2f2f770f5fceb9a04194f6e2d8e1e943f1bd2033e075aa1f0eb8d74275cb282b506f2

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/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

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