@query-farm/vgi 0.6.0

package/src/arrow/repr.test-d.ts

@@ -0,0 +1,189 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+//
+// COMPILE-TIME (type-only) tests for the phase-3 typed author API.
+//
+// This file is type-checked by `bun run build:types` / `tsc -p
+// tsconfig.build.json` (it matches `src/**/*.ts` and is NOT excluded — only
+// `*.test.ts` / `*.spec.ts` are). It contains no runtime assertions; the
+// `@ts-expect-error` markers ARE the assertions — each must sit on a line that
+// genuinely fails to type-check, or the build fails. It proves:
+//   - RichValue / RawValue / ValueFor resolve to the correct JS value per type.
+//   - defineScalarFunction infers compute()'s return type from `returns`+`repr`.
+//   - A wrong representation in compute() is a COMPILE error.
+
+import {
+  defineScalarFunction,
+} from "../functions/scalar.js";
+import {
+  dateDay, dateMillisecond, int64, int32, utf8, decimal128,
+  timestampMicros, struct, list, field, bool, float64,
+  asDate32, asDate64Ms, asTimestampMicros, asUnscaledDecimal, asInt64,
+} from "./index.js";
+import type {
+  RichValue, RawValue, ValueFor,
+  Date32Type, Date64Type, Int64Type, Int32Type, Utf8Type, BoolType,
+  TimestampType, DecimalType, FloatType,
+  StructType, ListType, TypedField,
+  Date32, TimestampMicros, UnscaledDecimal,
+} from "./index.js";
+
+// ---------------------------------------------------------------------------
+// Static equality helpers
+// ---------------------------------------------------------------------------
+
+type Expect<T extends true> = T;
+type Equal<A, B> =
+  (<G>() => G extends A ? 1 : 2) extends (<G>() => G extends B ? 1 : 2) ? true : false;
+
+// ---------------------------------------------------------------------------
+// RichValue / RawValue / ValueFor mapping
+// ---------------------------------------------------------------------------
+
+type _r1 = Expect<Equal<RichValue<Date32Type>, Date>>;
+type _r2 = Expect<Equal<RawValue<Date32Type>, Date32>>;
+type _r3 = Expect<Equal<RichValue<Date64Type>, Date>>;
+type _r4 = Expect<Equal<RichValue<Int64Type>, bigint>>;
+type _r5 = Expect<Equal<RichValue<Int32Type>, number>>;
+type _r6 = Expect<Equal<RichValue<Utf8Type>, string>>;
+type _r7 = Expect<Equal<RichValue<BoolType>, boolean>>;
+type _r8 = Expect<Equal<ValueFor<TimestampType<"us">, "rich">, bigint>>;
+type _r9 = Expect<Equal<ValueFor<TimestampType<"us">, "raw">, TimestampMicros>>;
+type _r10 = Expect<Equal<RawValue<DecimalType>, UnscaledDecimal>>;
+type _r11 = Expect<Equal<RichValue<DecimalType>, bigint>>;
+type _r12 = Expect<Equal<RichValue<FloatType>, number>>;
+
+// struct recursion: { a: number | null; d: Date | null }
+type _StructT = StructType<[TypedField<"a", Int32Type>, TypedField<"d", Date32Type>]>;
+type _r13 = Expect<Equal<RichValue<_StructT>, { a: number | null; d: Date | null }>>;
+type _r14 = Expect<Equal<RawValue<_StructT>, { a: number | null; d: Date32 | null }>>;
+
+// list recursion
+type _ListT = ListType<Int64Type>;
+type _r15 = Expect<Equal<RichValue<_ListT>, Array<bigint | null>>>;
+
+// ---------------------------------------------------------------------------
+// defineScalarFunction inference: RICH mode (default)
+// ---------------------------------------------------------------------------
+
+defineScalarFunction({
+  name: "rich_date",
+  params: { d: dateDay() },
+  returns: dateDay(),
+  // rich date32 -> Date. Correct: return Date.
+  compute: () => [new Date(), null],
+});
+
+defineScalarFunction({
+  name: "rich_date_wrong",
+  params: { d: dateDay() },
+  returns: dateDay(),
+  // @ts-expect-error rich mode expects Date, not a branded raw Date32 day-number.
+  compute: () => [asDate32(20000)],
+});
+
+defineScalarFunction({
+  name: "rich_int64",
+  params: { v: int64() },
+  returns: int64(),
+  compute: () => [1n, null],
+});
+
+defineScalarFunction({
+  name: "rich_int64_wrong",
+  params: { v: int64() },
+  returns: int64(),
+  // @ts-expect-error int64 output is bigint, not number.
+  compute: () => [1, 2, 3],
+});
+
+defineScalarFunction({
+  name: "rich_utf8",
+  returns: utf8(),
+  compute: () => ["a", "b", null],
+});
+
+defineScalarFunction({
+  name: "rich_utf8_wrong",
+  returns: utf8(),
+  // @ts-expect-error utf8 output is string, not number.
+  compute: () => [42],
+});
+
+// ---------------------------------------------------------------------------
+// defineScalarFunction inference: RAW mode
+// ---------------------------------------------------------------------------
+
+defineScalarFunction({
+  name: "raw_date",
+  repr: "raw",
+  params: { d: dateDay() },
+  returns: dateDay(),
+  // raw date32 -> branded Date32 day-number. Correct.
+  compute: () => [asDate32(20000), null],
+});
+
+defineScalarFunction({
+  name: "raw_date_wrong_date",
+  repr: "raw",
+  returns: dateDay(),
+  // @ts-expect-error raw mode expects a branded Date32, not a JS Date.
+  compute: () => [new Date()],
+});
+
+defineScalarFunction({
+  name: "raw_date_wrong_plain_number",
+  repr: "raw",
+  returns: dateDay(),
+  // @ts-expect-error raw date32 is a BRANDED Date32, a plain number is rejected.
+  compute: () => [20000],
+});
+
+defineScalarFunction({
+  name: "raw_timestamp",
+  repr: "raw",
+  returns: timestampMicros(),
+  compute: () => [asTimestampMicros(1745107200000000n), null],
+});
+
+defineScalarFunction({
+  name: "raw_timestamp_wrong",
+  repr: "raw",
+  returns: timestampMicros(),
+  // @ts-expect-error raw timestamp[us] is a branded TimestampMicros, not a plain bigint.
+  compute: () => [1745107200000000n],
+});
+
+defineScalarFunction({
+  name: "raw_decimal",
+  repr: "raw",
+  returns: decimal128(38, 4),
+  compute: () => [asUnscaledDecimal(12345n), null],
+});
+
+// raw int64 accepts a branded Int64
+defineScalarFunction({
+  name: "raw_int64",
+  repr: "raw",
+  returns: int64(),
+  compute: () => [asInt64(7n), null],
+});
+
+// rich + struct return shape is checked structurally
+defineScalarFunction({
+  name: "rich_struct",
+  returns: struct([field("a", int32()), field("d", dateDay())]),
+  compute: () => [{ a: 1, d: new Date() }, null],
+});
+
+defineScalarFunction({
+  name: "rich_struct_wrong",
+  returns: struct([field("a", int32()), field("d", dateDay())]),
+  // @ts-expect-error struct child `d` is rich Date, not a number.
+  compute: () => [{ a: 1, d: 20000 }],
+});
+
+// Reference everything so unused-locals (if ever enabled) and lint stay quiet.
+export type _AllChecks = [
+  _r1, _r2, _r3, _r4, _r5, _r6, _r7, _r8, _r9, _r10, _r11, _r12, _r13, _r14, _r15,
+];
+export const _unusedFactories = { dateMillisecond, bool, float64, list, asDate64Ms };

package/src/arrow/schema-types.ts

@@ -0,0 +1,213 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+//
+// Typed facade type-factories — phase 3 (the KEY ENABLER for static typing).
+//
+// The per-backend `schema.ts` factories build a runtime `VgiDataType` but only
+// declare their return as `VgiDataType` (`{ readonly typeId }`), which is too
+// coarse for the type-level value mapping in ./codec/repr.ts. This module wraps
+// each factory and casts the (unchanged) runtime value to the PRECISE nominal
+// descriptor from ./codec/type-descriptors.ts — e.g. `dateDay(): Date32Type`,
+// `timestamp(u): TimestampType<...>`, `struct(children)` preserving its field
+// tuple. Both backends route through the same `#arrow-impl` runtime, so they
+// report IDENTICAL static types from the facade.
+//
+// Runtime behavior is identical to the backend factories (these are pure casts
+// plus, for the unit-overloaded factories, a literal-unit overload set that
+// maps the integer TimeUnit to the descriptor's string-literal unit).
+
+import * as impl from "#arrow-impl";
+import type { VgiField, VgiDataType } from "./types.js";
+import type {
+  NullDescriptor,
+  BoolType,
+  Int8Type, Int16Type, Int32Type, Int64Type,
+  Uint8Type, Uint16Type, Uint32Type, Uint64Type,
+  IntType,
+  FloatType,
+  Utf8Type,
+  BinaryType,
+  FixedSizeBinaryType,
+  DecimalType,
+  Date32Type, Date64Type,
+  Time32Type, Time64Type,
+  TimestampType,
+  DurationType,
+  IntervalType,
+  ListType, FixedSizeListType,
+  StructType,
+  MapType,
+  DictionaryType,
+  UnionType,
+  TypedField,
+  TUnit,
+} from "./codec/type-descriptors.js";
+
+// Re-export the runtime unit/mode enums and schema/field helpers untouched.
+export const { TimeUnit, DateUnit, IntervalUnit, UnionMode, schema } = impl;
+
+/** field(): preserve the precise name + type so struct() can carry a typed
+ *  child tuple. Runtime is the backend `field`. */
+export function field<Name extends string, T extends VgiDataType>(
+  name: Name,
+  type: T,
+  nullable?: boolean,
+  metadata?: Map<string, string>,
+): TypedField<Name, T> {
+  return impl.field(name, type as any, nullable, metadata) as unknown as TypedField<Name, T>;
+}
+
+// ----- Primitives ----------------------------------------------------------
+
+export const nullType = (): NullDescriptor => impl.nullType() as unknown as NullDescriptor;
+export const bool = (): BoolType => impl.bool() as unknown as BoolType;
+
+export const int8 = (): Int8Type => impl.int8() as unknown as Int8Type;
+export const int16 = (): Int16Type => impl.int16() as unknown as Int16Type;
+export const int32 = (): Int32Type => impl.int32() as unknown as Int32Type;
+export const int64 = (): Int64Type => impl.int64() as unknown as Int64Type;
+export const uint8 = (): Uint8Type => impl.uint8() as unknown as Uint8Type;
+export const uint16 = (): Uint16Type => impl.uint16() as unknown as Uint16Type;
+export const uint32 = (): Uint32Type => impl.uint32() as unknown as Uint32Type;
+export const uint64 = (): Uint64Type => impl.uint64() as unknown as Uint64Type;
+
+// int(bitWidth, signed): bitWidth/signedness aren't statically known from a
+// runtime `number`, so this degrades to the generic IntType (rich/raw fall back
+// to number/bigint per the width literal when callers pass a literal). Prefer
+// the named factories (int32(), int64(), …) for precise typing.
+export function int(bitWidth?: 8 | 16 | 32 | 64, signed?: boolean): IntType<8 | 16 | 32 | 64, boolean> {
+  return impl.int(bitWidth, signed) as unknown as IntType<8 | 16 | 32 | 64, boolean>;
+}
+
+export const float16 = (): FloatType => impl.float16() as unknown as FloatType;
+export const float32 = (): FloatType => impl.float32() as unknown as FloatType;
+export const float64 = (): FloatType => impl.float64() as unknown as FloatType;
+
+export const utf8 = (): Utf8Type => impl.utf8() as unknown as Utf8Type;
+export const binary = (): BinaryType => impl.binary() as unknown as BinaryType;
+export const fixedSizeBinary = (byteWidth: number): FixedSizeBinaryType =>
+  impl.fixedSizeBinary(byteWidth) as unknown as FixedSizeBinaryType;
+
+// ----- Decimal -------------------------------------------------------------
+
+export const decimal = (precision: number, scale: number, bitWidth?: 32 | 64 | 128 | 256): DecimalType =>
+  impl.decimal(precision, scale, bitWidth) as unknown as DecimalType;
+export const decimal128 = (precision: number, scale: number): DecimalType =>
+  impl.decimal128(precision, scale) as unknown as DecimalType;
+export const decimal256 = (precision: number, scale: number): DecimalType =>
+  impl.decimal256(precision, scale) as unknown as DecimalType;
+
+// ----- Date / Time / Timestamp / Duration / Interval -----------------------
+
+// `date(unit)` with a runtime unit isn't statically resolvable; it widens to
+// Date64Type (ms) — the default. Use dateDay()/dateMillisecond() for precision.
+export const date = (unit?: number): Date64Type => impl.date(unit) as unknown as Date64Type;
+export const dateDay = (): Date32Type => impl.dateDay() as unknown as Date32Type;
+export const dateMillisecond = (): Date64Type => impl.dateMillisecond() as unknown as Date64Type;
+
+export const timeSecond = (): Time32Type<"s"> => impl.timeSecond() as unknown as Time32Type<"s">;
+export const timeMillisecond = (): Time32Type<"ms"> => impl.timeMillisecond() as unknown as Time32Type<"ms">;
+export const timeMicrosecond = (): Time64Type<"us"> => impl.timeMicrosecond() as unknown as Time64Type<"us">;
+export const timeNanosecond = (): Time64Type<"ns"> => impl.timeNanosecond() as unknown as Time64Type<"ns">;
+
+// Generic time(unit, bitWidth): degrades to a union of the precise time types.
+export function time(unit?: number, bitWidth?: 32 | 64): Time32Type<"s" | "ms"> | Time64Type<"us" | "ns"> {
+  return impl.time(unit, bitWidth) as unknown as Time32Type<"s" | "ms"> | Time64Type<"us" | "ns">;
+}
+
+const UNIT_TO_TAG: Record<number, TUnit> = {
+  [impl.TimeUnit.SECOND]: "s",
+  [impl.TimeUnit.MILLISECOND]: "ms",
+  [impl.TimeUnit.MICROSECOND]: "us",
+  [impl.TimeUnit.NANOSECOND]: "ns",
+};
+
+/** timestamp(unit): when called with a literal unit constant the result type
+ *  carries that unit; with a runtime number it widens to TimestampType<TUnit>. */
+export function timestamp<U extends TUnit = TUnit>(
+  unit?: number,
+  timezone?: string | null,
+): TimestampType<U> {
+  return impl.timestamp(unit, timezone ?? null) as unknown as TimestampType<U>;
+}
+
+export function duration<U extends TUnit = TUnit>(unit?: number): DurationType<U> {
+  return impl.duration(unit) as unknown as DurationType<U>;
+}
+
+// Unit-precise convenience factories — these carry the wire unit in the static
+// type without the caller needing an explicit type argument, so raw-mode
+// branded typing is automatic. (The generic timestamp()/duration() above
+// can't infer the unit from a runtime `number`, so prefer these.)
+export const timestampSeconds = (timezone?: string | null): TimestampType<"s"> =>
+  impl.timestamp(impl.TimeUnit.SECOND, timezone ?? null) as unknown as TimestampType<"s">;
+export const timestampMillis = (timezone?: string | null): TimestampType<"ms"> =>
+  impl.timestamp(impl.TimeUnit.MILLISECOND, timezone ?? null) as unknown as TimestampType<"ms">;
+export const timestampMicros = (timezone?: string | null): TimestampType<"us"> =>
+  impl.timestamp(impl.TimeUnit.MICROSECOND, timezone ?? null) as unknown as TimestampType<"us">;
+export const timestampNanos = (timezone?: string | null): TimestampType<"ns"> =>
+  impl.timestamp(impl.TimeUnit.NANOSECOND, timezone ?? null) as unknown as TimestampType<"ns">;
+
+export const durationSeconds = (): DurationType<"s"> =>
+  impl.duration(impl.TimeUnit.SECOND) as unknown as DurationType<"s">;
+export const durationMillis = (): DurationType<"ms"> =>
+  impl.duration(impl.TimeUnit.MILLISECOND) as unknown as DurationType<"ms">;
+export const durationMicros = (): DurationType<"us"> =>
+  impl.duration(impl.TimeUnit.MICROSECOND) as unknown as DurationType<"us">;
+export const durationNanos = (): DurationType<"ns"> =>
+  impl.duration(impl.TimeUnit.NANOSECOND) as unknown as DurationType<"ns">;
+
+export const interval = (unit?: number): IntervalType => impl.interval(unit) as unknown as IntervalType;
+
+// ----- Nested --------------------------------------------------------------
+
+export function list<T extends VgiDataType>(child: TypedField<string, T> | T): ListType<T> {
+  return impl.list(child as any) as unknown as ListType<T>;
+}
+
+export function fixedSizeList<T extends VgiDataType>(
+  child: TypedField<string, T> | T,
+  listSize: number,
+): FixedSizeListType<T> {
+  return impl.fixedSizeList(child as any, listSize) as unknown as FixedSizeListType<T>;
+}
+
+export function struct<const C extends readonly TypedField<string, VgiDataType>[]>(
+  children: C,
+): StructType<C> {
+  return impl.struct(children as unknown as readonly VgiField[]) as unknown as StructType<C>;
+}
+
+export function map<K extends VgiDataType, V extends VgiDataType>(
+  keyField: TypedField<string, K> | K,
+  valueField: TypedField<string, V> | V,
+  keysSorted?: boolean,
+): MapType<K, V> {
+  return impl.map(keyField as any, valueField as any, keysSorted) as unknown as MapType<K, V>;
+}
+
+export function dictionary<V extends VgiDataType>(
+  valueType: V,
+  indexType?: VgiDataType,
+  ordered?: boolean,
+  id?: number,
+): DictionaryType<V> {
+  return impl.dictionary(valueType as any, indexType as any, ordered, id) as unknown as DictionaryType<V>;
+}
+
+export function union(
+  mode: number,
+  children: readonly (VgiField | VgiDataType)[],
+  typeIds?: number[],
+): UnionType {
+  return impl.union(mode, children as any, typeIds) as unknown as UnionType;
+}
+
+export const sparseUnion = (
+  children: readonly (VgiField | VgiDataType)[],
+  typeIds?: number[],
+): UnionType => impl.sparseUnion(children as any, typeIds) as unknown as UnionType;
+
+export const denseUnion = (
+  children: readonly (VgiField | VgiDataType)[],
+  typeIds?: number[],
+): UnionType => impl.denseUnion(children as any, typeIds) as unknown as UnionType;

package/src/arrow/types.ts

@@ -0,0 +1,74 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// Backend-agnostic Arrow type surface used throughout vgi-typescript.
+//
+// The interfaces below are the *structural contract* every Arrow backend
+// must satisfy. arrow-js (`Schema`/`RecordBatch`/`Vector`/`DataType`) and
+// flechette (`Schema`/`Table`/`Column` plus plain-object types) both
+// already match these shapes, so backends pass native values through
+// without wrapping.
+
+/** Numeric Arrow type discriminator. Values match the Arrow Type enum
+ *  (Null=1, Int=2, Float=3, Binary=4, Utf8=5, Bool=6, Decimal=7,
+ *  Date=8, Time=9, Timestamp=10, Interval=11, List=12, Struct=13,
+ *  Union=14, FixedSizeBinary=15, FixedSizeList=16, Map=17, Duration=18,
+ *  LargeBinary=19, LargeUtf8=20, Dictionary=-1). Both backends agree. */
+export type VgiTypeId = number;
+
+export interface VgiDataType {
+  readonly typeId: VgiTypeId;
+}
+
+export interface VgiField {
+  readonly name: string;
+  readonly type: VgiDataType;
+  readonly nullable: boolean;
+  /** Always defined (possibly empty) so callers don't need null-checks.
+   *  Both arrow-js Field.metadata and flechette's field.metadata are a
+   *  Map; the field-factory in each backend ensures presence. */
+  readonly metadata: Map<string, string>;
+}
+
+export interface VgiSchema {
+  readonly fields: readonly VgiField[];
+  readonly metadata: Map<string, string>;
+}
+
+/** Column view. Generic dropped: arrow-js parameterizes on DataType, flechette
+ *  on value type, so the facade exposes an erased shape. Callers cast at the
+ *  use site (the column's static schema makes the value type known there). */
+export interface VgiColumn {
+  readonly type: VgiDataType;
+  readonly length: number;
+  get(index: number): unknown;
+  [Symbol.iterator](): Iterator<unknown>;
+}
+
+export interface VgiBatch {
+  readonly schema: VgiSchema;
+  readonly numRows: number;
+  getChild(name: string): VgiColumn | null;
+  getChildAt(index: number): VgiColumn | null;
+}
+
+export interface VgiBackendInfo {
+  readonly name: "arrow-js" | "flechette";
+}
+
+/** Low-level handle for a single column's underlying Arrow Data. The shape
+ *  differs per backend (arrow-js: a `Data` instance; flechette: the inner
+ *  `Column.data[0]`-style object), so this is treated opaquely; it's only
+ *  meant to be passed back into facade builders that know how to consume it. */
+export type VgiColumnData = unknown;
+
+/** A decoded union-typed value: which member is active (`tag`) and its `value`.
+ *
+ *  DuckDB `UNION` / Arrow union values are *tagged* — the discriminator (which
+ *  member is present) lives in the union's per-row type code, not in the member
+ *  value. A plain scalar read returns only the member value and drops that tag,
+ *  so union values are decoded into this wrapper instead: `tag` is the active
+ *  member's field name (or `null` for a null union) and `value` is its decoded
+ *  canonical value. Mirrors vgi-python's `vgi.arguments.TaggedUnion`. */
+export interface TaggedUnion {
+  readonly tag: string | null;
+  readonly value: unknown;
+}

package/src/catalog/attach-option.ts

@@ -0,0 +1,107 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// SPDX-License-Identifier: LicenseRef-QueryFarm-Source-Available-1.0
+
+// Attach-time option descriptors for declarative worker option discovery.
+// Mirrors `vgi.catalog.attach_option` on the Python side — same Arrow IPC
+// wire format so the C++ extension (which owns ATTACH option validation)
+// sees identical shapes regardless of which language the worker is in.
+//
+// Wire format of one serialized AttachOptionSpec (per
+// vgi-python/vgi/catalog/attach_option.py):
+//
+//   RecordBatch of:
+//     name: Utf8
+//     description: Utf8
+//     type: Binary   -- serialized Arrow Schema with a single "value" field
+//                       of the option's DataType
+//     default_value: Binary nullable -- serialized single-row RecordBatch with
+//                                       the default value under "value", or
+//                                       null when no default is declared
+//
+// The extension reads the outer `attach_option_specs: list<binary>` column
+// from CatalogInfo and validates user-supplied ATTACH options against the
+// per-spec declared type before forwarding them to the worker.
+
+import {
+  type VgiDataType,
+  schema as makeSchema,
+  field,
+  utf8,
+  binary,
+  batchFromColumns,
+  serializeBatch,
+  serializeSchema,
+} from "../arrow/index.js";
+
+/**
+ * Declarative spec for a single attach-time option.
+ *
+ * The catalog's `catalogsInfo()` emits these (serialized) in
+ * `CatalogInfo.attach_option_specs` so the DuckDB extension can validate
+ * user-supplied ATTACH options and cast them to the declared type before
+ * forwarding to the worker's `catalog_attach` handler.
+ */
+export interface AttachOptionSpec {
+  /** Option name — matches the key users pass in the ATTACH statement. */
+  name: string;
+  /** Human-readable description (shown in discovery UIs). */
+  description: string;
+  /** Arrow data type the extension should cast user input to. */
+  type: VgiDataType;
+  /**
+   * Default value used when the user omits this option. Passed through to
+   * the worker's catalog_attach handler as-is if no override is given.
+   * Use `null` for "no default" (an unset option will then be absent from
+   * the options dict delivered to attach()).
+   */
+  default?: unknown;
+}
+
+const SPEC_SCHEMA = makeSchema([
+  field("name", utf8(), false),
+  field("description", utf8(), false),
+  field("type", binary(), false),
+  field("default_value", binary(), true),
+]);
+
+/**
+ * Serialize an AttachOptionSpec to the wire format the extension expects
+ * (one IPC-serialized RecordBatch with a single row).
+ */
+export function serializeAttachOptionSpec(spec: AttachOptionSpec): Uint8Array {
+  // `type` is encoded as a serialized Arrow Schema with one field named
+  // "value" of the option's DataType. This lets the extension peek at the
+  // logical type without a separate enum.
+  const typeSchema = makeSchema([field("value", spec.type, true)]);
+  const typeBytes = serializeSchema(typeSchema);
+
+  let defaultBytes: Uint8Array | null = null;
+  if (spec.default !== undefined && spec.default !== null) {
+    // Build a 1-row batch with one column "value" of the option's type.
+    const defaultBatch = batchFromColumns(
+      { value: [spec.default] },
+      typeSchema,
+    );
+    defaultBytes = serializeBatch(defaultBatch);
+  }
+
+  const batch = batchFromColumns(
+    {
+      name: [spec.name],
+      description: [spec.description],
+      type: [typeBytes],
+      default_value: [defaultBytes],
+    },
+    SPEC_SCHEMA,
+  );
+  return serializeBatch(batch);
+}
+
+/**
+ * Convenience: serialize many specs at once for CatalogInfo.attach_option_specs.
+ */
+export function serializeAttachOptionSpecs(
+  specs: Iterable<AttachOptionSpec>,
+): Uint8Array[] {
+  return Array.from(specs, serializeAttachOptionSpec);
+}

package/src/catalog/attach-options.ts

@@ -0,0 +1,79 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// SPDX-License-Identifier: LicenseRef-QueryFarm-Source-Available-1.0
+
+// Serialize a plain JS options map into a single-row Arrow RecordBatch
+// suitable for the `options` field of CatalogAttachRequest. Column types
+// are inferred per-value. This is the ergonomic layer that lets callers
+// write `{ region: "us-east-1", maxRows: 1000n }` instead of hand-building
+// an Arrow batch.
+
+import { type VgiDataType, bool, binary, type VgiField, field, float64, int64, nullType, type VgiSchema, schema as schema_, utf8 } from "../arrow/index.js";
+import { batchFromColumns, serializeBatch } from "../util/arrow/index.js";
+
+/**
+ * Values supported in a CatalogAttach options map. The client infers an
+ * Arrow type per value:
+ *
+ *   string     → Utf8
+ *   bigint     → Int64
+ *   number     → Float64 (JS numbers are doubles — safe for small ints too)
+ *   boolean    → Bool
+ *   Uint8Array → Binary
+ *   null       → Null (column with no concrete type; value is null)
+ *
+ * If you need types this can't express (Decimal, Timestamp, Int32 vs Int64,
+ * nested structs), drop down to `optionsBytes` on CatalogAttachOptions and
+ * build the RecordBatch yourself.
+ */
+export type AttachOptionValue = string | number | bigint | boolean | null | Uint8Array;
+
+/**
+ * Infer an Arrow DataType for a single JS value. Exported for tests; not
+ * part of the stable public API.
+ */
+export function inferAttachOptionArrowType(value: AttachOptionValue): VgiDataType {
+  if (value === null) return nullType();
+  if (typeof value === "string") return utf8();
+  if (typeof value === "bigint") return int64();
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(
+        `Attach option number values must be finite (got ${value}). ` +
+        `Use a bigint for integers or a finite number for floats.`,
+      );
+    }
+    return float64();
+  }
+  if (typeof value === "boolean") return bool();
+  if (value instanceof Uint8Array) return binary();
+  throw new TypeError(
+    `Unsupported attach option value type: ${typeof value}. ` +
+    `Supported: string, number, bigint, boolean, null, Uint8Array.`,
+  );
+}
+
+/**
+ * Serialize a plain key→value options map to an Arrow IPC RecordBatch.
+ *
+ * Returns `null` when the map is empty or has no entries — the wire layer
+ * then sends a null options field rather than a zero-column batch (which
+ * pyarrow's IPC reader rejects).
+ */
+export function serializeAttachOptions(
+  options: Record<string, AttachOptionValue> | undefined | null,
+): Uint8Array | null {
+  if (!options) return null;
+  const entries = Object.entries(options);
+  if (entries.length === 0) return null;
+
+  const fields: VgiField[] = [];
+  const columns: Record<string, unknown[]> = {};
+  for (const [key, value] of entries) {
+    const type = inferAttachOptionArrowType(value);
+    fields.push(field(key, type, true));
+    columns[key] = [value];
+  }
+  const schema = schema_(fields);
+  const batch = batchFromColumns(columns, schema);
+  return serializeBatch(batch);
+}