@query-farm/vgi 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "TypeScript framework for extending DuckDB with user-defined functions via the Vector Gateway Interface (VGI) over Arrow IPC.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Query Farm LLC (https://query.farm)",
@@ -29,7 +29,7 @@
     "node": ">=22.15"
   },
   "type": "module",
-  "//sideEffects": "Entry modules are listed so the bundler cannot tree-shake them away. Under a bare `sideEffects: false`, an entry consisting only of re-exports builds to a dangling export list with no imports and no definitions \u2014 invalid ESM that throws on first import. Modules not listed stay side-effect-free, so consumers still tree-shake normally.",
+  "//sideEffects": "Entry modules are listed so the bundler cannot tree-shake them away. Under a bare `sideEffects: false`, an entry consisting only of re-exports builds to a dangling export list with no imports and no definitions — invalid ESM that throws on first import. Modules not listed stay side-effect-free, so consumers still tree-shake normally.",
   "sideEffects": [
     "./src/index.ts",
     "./src/client-entry.ts",
@@ -83,16 +83,16 @@
   },
   "dependencies": {
     "@noble/ciphers": "^2.2.0",
-    "@query-farm/flechette": "^2.4.0"
+    "@query-farm/flechette": "^2.4.1"
   },
   "peerDependencies": {
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.15.0"
+    "@query-farm/vgi-rpc": "^0.15.1"
   },
   "devDependencies": {
     "@duckdb/node-api": "^1.5.2-r.1",
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.15.0",
+    "@query-farm/vgi-rpc": "^0.15.1",
     "@types/bun": "latest",
     "typescript": "^6.0.3"
   },

package/src/arrow/impl-arrowjs/index.ts

@@ -53,3 +53,13 @@ export {
 
 // Column statistics (sparse-union heavy — backend-specific).
 export { buildStatisticsBatch, type ColumnStatistics } from "./statistics.js";
+
+/**
+ * No-op on this backend: arrow-js `RecordBatch`/`Vector` already expose the
+ * full API worker code uses, and arrow-js is a peer dependency, so there is
+ * only ever one copy. Present so both backends satisfy one facade interface —
+ * see impl-flechette/compat.ts for what this does there.
+ */
+export function adoptArrowJsShape<T>(batch: T): T {
+  return batch;
+}

package/src/arrow/impl-flechette/arrowjs-shape.ts

@@ -0,0 +1,78 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+//
+// arrow-js shape for flechette *values* — the plain objects that have no
+// prototype to patch (types and fields), as opposed to the class methods
+// handled in ./compat.ts.
+//
+// Two differences bite:
+//
+//   * Int types spell signedness `signed`; arrow-js spells it `isSigned`.
+//     Worker code branches on it to pick a promoted result type —
+//     `examples/scalar.ts`'s `promoteForAddition` reads `isSigned` and, when
+//     it comes back `undefined`, promotes a signed BIGINT to UINT64, after
+//     which the codec rejects every negative value. That is a wrong answer,
+//     not a missing property.
+//
+//   * A decoded flechette Field carries `metadata: null` when the wire had no
+//     custom_metadata; arrow-js always materializes an empty `Map`. Shared
+//     code reads `field.metadata.get(…)` unconditionally (describe.json's
+//     column comments, macro `vgi_doc` parameter docs), so `null` is a
+//     TypeError rather than "no metadata".
+//
+// Both are applied to decoded schemas at the IPC boundary. Kept in a
+// dependency-free module so `schema.ts` / `normalize-type.ts` can use it
+// without pulling in `compat.ts`, which depends on the canonical write path.
+
+/** Arrow `Type.Int` — the enum value is identical in both libraries. */
+const TYPE_INT = 2;
+
+/**
+ * Attach `isSigned` to a flechette Int type, recursing through children /
+ * dictionary / index types.
+ *
+ * The alias is a non-enumerable getter so it never shows up in structural
+ * comparisons, IPC encoding or `Object.keys` — flechette keeps writing
+ * `signed`, and this is purely a read-side view of it. Mutating in place is
+ * safe: these objects are freshly built per decode.
+ */
+export function aliasIntSigned<T>(type: T): T {
+  const t = type as any;
+  if (t == null || typeof t !== "object") return type;
+  if (t.typeId === TYPE_INT && !("isSigned" in t)) {
+    Object.defineProperty(t, "isSigned", {
+      get(this: any) {
+        return this.signed;
+      },
+      enumerable: false,
+      configurable: true,
+    });
+  }
+  if (Array.isArray(t.children)) {
+    for (const child of t.children) normalizeField(child);
+  }
+  if (t.dictionary) aliasIntSigned(t.dictionary);
+  if (t.indices) aliasIntSigned(t.indices);
+  return type;
+}
+
+/** Normalize one field: an always-present metadata Map, plus its type. */
+function normalizeField(field: any): void {
+  if (field == null || typeof field !== "object") return;
+  if (!field.metadata) field.metadata = new Map<string, string>();
+  aliasIntSigned(field.type ?? field);
+}
+
+/**
+ * Bring a freshly decoded flechette schema up to the arrow-js shape shared
+ * code expects: every field (and nested child field) has a metadata `Map`,
+ * and every Int type answers to `isSigned`.
+ */
+export function normalizeDecodedSchema<T>(schema: T): T {
+  const s = schema as any;
+  if (s == null || typeof s !== "object") return schema;
+  if (!s.metadata) s.metadata = new Map<string, string>();
+  if (Array.isArray(s.fields)) {
+    for (const f of s.fields) normalizeField(f);
+  }
+  return schema;
+}

package/src/arrow/impl-flechette/canonical.ts

@@ -31,6 +31,9 @@ import { toFlechetteType } from "./normalize-type.js";
 
 const MS_PER_DAY = 86_400_000;
 
+/** `IntervalUnit.MONTH_DAY_NANO` — same ordinal in arrow-js and flechette. */
+const MONTH_DAY_NANO = 2;
+
 const COLUMN_OPTS = {
   useBigInt: true,
   useBigIntTimestamp: true,
@@ -99,6 +102,21 @@ export function prepareForFlechette(type: VgiDataType, values: unknown[]): unkno
       return new Date(isDay ? n * MS_PER_DAY : n);
     });
   }
+  if (tid === 11 && (type as any).unit === MONTH_DAY_NANO) {
+    // arrow-js represents a MonthDayNano interval as four int32 words
+    // [months, days, nanos_lo, nanos_hi]; flechette's builder wants
+    // [months, days, nanos] with nanos as one number/bigint. The facade
+    // presents arrow-js's shape (see compat.ts, which makes the read side
+    // agree), so fold the 64-bit word pair back together here.
+    return values.map((v) => {
+      if (v == null) return null;
+      const w = v as ArrayLike<number>;
+      if (typeof (w as any).length !== "number" || w.length < 4) return v;
+      const lo = BigInt(w[2] >>> 0);
+      const hi = BigInt(w[3] | 0);
+      return [w[0] | 0, w[1] | 0, BigInt.asIntN(64, (hi << 32n) | lo)];
+    });
+  }
   if (tid === 17) {
     return values.map((v) => {
       if (v == null) return null;
@@ -139,6 +157,7 @@ export function prepareForFlechette(type: VgiDataType, values: unknown[]): unkno
 function needsPrepare(type: VgiDataType): boolean {
   const tid = type.typeId;
   if (tid === 8 || tid === 17) return true;
+  if (tid === 11 && (type as any).unit === MONTH_DAY_NANO) return true;
   if (tid === 13) return ((type as any).children ?? []).some((c: any) => needsPrepare(c.type));
   if (tid === 12 || tid === 16) {
     const ct = (type as any).children?.[0]?.type;

package/src/arrow/impl-flechette/compat.ts

@@ -0,0 +1,254 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+//
+// arrow-js shape compatibility for the flechette backend.
+//
+// The facade's job is that a worker written once runs on either backend. Most
+// of that is handled by re-exporting equivalent factories, but a few *methods
+// and values* are read directly off the objects the facade hands back —
+// `batch.getChild(name)`, `batch.slice(…)`, an INTERVAL cell — and there the
+// two libraries genuinely disagree:
+//
+//   arrow-js                       flechette
+//   -----------------------------  --------------------------------------
+//   Vector#isValid(i)              Column has no validity accessor at all
+//                                  (Batch#isValid exists, Column doesn't)
+//   RecordBatch#slice(a, b)        Table has no row-range slice
+//   MonthDayNano → Int32Array(4)   → Float64Array(3), nanos via a double
+//
+// Worker code that touches any of those works on arrow-js and breaks on
+// flechette. Rather than push `backend.name === "flechette"` conditionals into
+// shared code and into every example, the gap is closed here, once, on the
+// flechette side — which is what the facade is for.
+//
+// `Column` and `Table` are classes flechette exports, so these are prototype
+// augmentations, installed on import and idempotent. The Int `isSigned` alias
+// lives in ./int-signed.ts instead: Arrow types are plain object literals with
+// no shared prototype, so it has to be applied per instance.
+
+import {
+  Column,
+  Table,
+  batchType,
+  columnFromArray as f_columnFromArray,
+  interval as f_interval,
+  IntervalUnit,
+} from "@query-farm/flechette";
+
+import { prepareForFlechette } from "./canonical.js";
+
+/** Extraction options the rest of the backend builds columns with. */
+const COLUMN_OPTS = {
+  useBigInt: true,
+  useBigIntTimestamp: true,
+  useDecimalInt: true,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Column#isValid — arrow-js's Vector#isValid(index)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-row null check on a column, matching arrow-js's `Vector#isValid`.
+ *
+ * flechette pushes validity down to `Batch`, and a `Column` is a list of
+ * batches with an `offsets` prefix-sum, so the column index has to be mapped
+ * to (batch, batch-local index) the same way `Column#at` does. The common
+ * single-batch case is dispatched without the search.
+ */
+function columnIsValid(this: any, index: number): boolean {
+  const data: any[] = this.data;
+  if (data.length === 1) return batchIsValid(data[0], index);
+  const offsets: Int32Array = this.offsets;
+  // offsets is a sorted prefix sum of batch lengths; find the owning batch.
+  let lo = 0;
+  let hi = data.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (offsets[mid + 1] <= index) lo = mid + 1;
+    else hi = mid;
+  }
+  return batchIsValid(data[lo], index - offsets[lo]);
+}
+
+/**
+ * `Batch#isValid` guarded for the all-valid case.
+ *
+ * flechette only ever calls `Batch#isValid` from `Batch#at`, and the batch
+ * constructor short-circuits `at` when there are no nulls — so `isValid` is
+ * never reached with an absent validity bitmap *internally*, and it does not
+ * guard for one: `decodeBit(undefined, i)` reads `undefined[…]` and returns
+ * false. Exposing it through `Column#isValid` walks straight into that, and a
+ * fully-populated column reads back as entirely NULL — which is how every
+ * aggregate returned NULL instead of a sum.
+ */
+function batchIsValid(batch: any, index: number): boolean {
+  if (!batch) return false;
+  if (!batch.nullCount || !batch.validity || batch.validity.length === 0) return true;
+  return batch.isValid(index);
+}
+
+// ---------------------------------------------------------------------------
+// Table#slice — arrow-js's RecordBatch#slice(begin, end)
+// ---------------------------------------------------------------------------
+
+/**
+ * Row-range slice of a table, matching arrow-js's `RecordBatch#slice`.
+ *
+ * flechette has no row-slicing primitive: `Batch#slice` returns a plain value
+ * array, not a batch, so there is nothing to rebuild a zero-copy view from.
+ * The range is therefore materialized back through `columnFromArray` — the
+ * same builder the write path uses — which yields real batches with real
+ * validity/offset/value buffers. That matters: a sliced batch is routinely
+ * handed straight back to `tableToIPC` (an exchange round replying with
+ * `batch.slice(0, 0)` to close a stream), and a hand-rolled batch-shaped
+ * object would fault inside the encoder.
+ *
+ * Values are read through `Column#at`, so they come out decoded; they are run
+ * back through `prepareForFlechette` to restore the shapes the builder wants
+ * (Date objects, Maps, three-word intervals).
+ *
+ * The dominant caller is `slice(0, 0)`: "give me an empty batch with this
+ * exact schema". That degenerates to `columnFromArray([], type)` and costs
+ * nothing.
+ */
+function tableSlice(this: any, begin = 0, end?: number): any {
+  const numRows: number = this.numRows;
+  const lo = clampIndex(begin, numRows);
+  const hi = end === undefined ? numRows : clampIndex(end, numRows);
+  const n = Math.max(0, hi - lo);
+  const children = this.children.map((col: any) => {
+    const values: unknown[] = new Array(n);
+    for (let i = 0; i < n; i++) values[i] = col.at(lo + i) ?? null;
+    return f_columnFromArray(prepareForFlechette(col.type, values), col.type, COLUMN_OPTS);
+  });
+  const out: any = new Table(this.schema, children);
+  // Preserve the row-object factory (plain object vs. row proxy) the source
+  // table was built with; `getFactory` reads it lazily, so a post-construction
+  // assignment is enough.
+  out.factory = this.factory;
+  return out;
+}
+
+function clampIndex(i: number, len: number): number {
+  const v = i < 0 ? len + i : i;
+  return v < 0 ? 0 : v > len ? len : v;
+}
+
+// ---------------------------------------------------------------------------
+// MonthDayNano interval values — arrow-js's four-int32 representation
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a MonthDayNano interval as arrow-js does: an `Int32Array` of four words
+ * `[months, days, nanos_lo, nanos_hi]`.
+ *
+ * flechette returns `Float64Array.of(months, days, Number(nanos))` instead —
+ * a different length, a different element type, and a lossy nanosecond field
+ * (`readInt64` coerces to a JS number and throws past 2^53). Worker code that
+ * decodes an INTERVAL argument branches on the four-word layout, so on
+ * flechette it fell through to a scalar path and died in `BigInt(NaN)` with
+ * "RangeError: Not an integer".
+ *
+ * Reading the raw 16 bytes directly also drops the precision loss: the nanos
+ * word pair is copied verbatim rather than routed through a double. The
+ * matching write-side conversion lives in ./canonical.ts.
+ */
+function intervalMonthDayNanoValue(this: any, index: number): Int32Array {
+  const bytes: Uint8Array = this.values;
+  const base = index << 4;
+  const out = new Int32Array(4);
+  for (let w = 0; w < 4; w++) {
+    const p = base + (w << 2);
+    out[w] =
+      bytes[p] | (bytes[p + 1] << 8) | (bytes[p + 2] << 16) | (bytes[p + 3] << 24);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Installation
+// ---------------------------------------------------------------------------
+
+/** Arrow `Type.Interval`, and `IntervalUnit.MONTH_DAY_NANO`. */
+const TYPE_INTERVAL = 11;
+const MONTH_DAY_NANO = 2;
+
+function installTableShape(proto: any): void {
+  if (proto && typeof proto.slice !== "function") proto.slice = tableSlice;
+}
+
+function installColumnShape(proto: any): void {
+  if (proto && typeof proto.isValid !== "function") proto.isValid = columnIsValid;
+}
+
+function installIntervalShape(proto: any): void {
+  if (proto && !proto.__vgiArrowJsInterval) {
+    proto.value = intervalMonthDayNanoValue;
+    proto.__vgiArrowJsInterval = true;
+  }
+}
+
+// Patch the copy of @query-farm/flechette that *this* module imports. Covers
+// every object the facade itself builds or decodes.
+installColumnShape(Column.prototype);
+installTableShape(Table.prototype);
+// The interval batch class is not exported by name; `batchType` resolves it.
+installIntervalShape(
+  (batchType(f_interval(IntervalUnit.MONTH_DAY_NANO) as any, {}) as any)?.prototype,
+);
+
+// ---------------------------------------------------------------------------
+// Adoption — for batches built by a *different copy* of flechette
+// ---------------------------------------------------------------------------
+
+/** Prototypes already patched, so adoption is O(1) after the first sighting. */
+const adopted = new WeakSet<object>();
+
+/**
+ * Give a batch the arrow-js shape even when it was not built by our copy of
+ * flechette.
+ *
+ * The prototype patches above are scoped to one module instance. npm/bun will
+ * happily install a *second* copy of `@query-farm/flechette` — nested under
+ * `@query-farm/vgi-rpc`, say, whenever the two version ranges disagree even
+ * transiently — and then batches decoded off the wire by vgi-rpc are instances
+ * of classes our patches never touched. Worker code that has been calling
+ * `col.isValid(i)` happily for the whole bind phase suddenly gets
+ * `TypeError: col.isValid is not a function` on the first exchange round, with
+ * nothing in the stack to suggest the cause. That is not hypothetical: it took
+ * out four integration tests, and a duplicate copy is invisible to
+ * `bun install` output and to the lockfile, which lists flechette once.
+ *
+ * So rather than trusting module identity, patch whatever prototypes we are
+ * actually handed, once each. `adopted` keeps it to a WeakSet probe per call.
+ *
+ * Returns its argument (mutating prototypes, not the batch) so call sites can
+ * wrap inline.
+ */
+export function adoptArrowJsShape<T>(batch: T): T {
+  const b = batch as any;
+  if (b == null || typeof b !== "object") return batch;
+  // Each prototype is checked independently: a 0-field batch teaches us nothing
+  // about the column class, so short-circuiting on the table alone would leave
+  // `isValid` unpatched for every later batch.
+  once(b, installTableShape);
+  const children: any[] = Array.isArray(b.children) ? b.children : [];
+  for (const col of children) {
+    if (col == null) continue;
+    once(col, installColumnShape);
+    // Interval *values* are produced by the batch class, one level further in.
+    if (col.type?.typeId === TYPE_INTERVAL && col.type?.unit === MONTH_DAY_NANO) {
+      once(col.data?.[0], installIntervalShape);
+    }
+  }
+  return batch;
+}
+
+/** Run `install` on `obj`'s prototype the first time we see that prototype. */
+function once(obj: any, install: (proto: any) => void): void {
+  if (obj == null) return;
+  const proto = Object.getPrototypeOf(obj);
+  if (proto == null || adopted.has(proto)) return;
+  adopted.add(proto);
+  install(proto);
+}

package/src/arrow/impl-flechette/empty.ts

@@ -3,6 +3,7 @@
 
 import { columnFromArray, tableFromColumns } from "@query-farm/flechette";
 import type { VgiSchema, VgiBatch } from "../types.js";
+import { toFlechetteType } from "./normalize-type.js";
 
 /**
  * Create an empty (0-row) batch with the given schema.
@@ -12,9 +13,12 @@ import type { VgiSchema, VgiBatch } from "../types.js";
  * makeData scaffolding the arrow-js backend needs.
  */
 export function emptyBatch(schema: VgiSchema): VgiBatch {
+  // Normalize first: a foreign (arrow-js) DataType survives `columnFromArray`
+  // but carries arrow-js property names, and flechette's IPC writer reads its
+  // own — so the resulting column type serializes with zeroed parameters.
   const cols: Record<string, ReturnType<typeof columnFromArray>> = {};
   for (const f of schema.fields) {
-    cols[f.name] = columnFromArray([], f.type as any);
+    cols[f.name] = columnFromArray([], toFlechetteType(f.type) as any);
   }
   return tableFromColumns(cols) as unknown as VgiBatch;
 }

package/src/arrow/impl-flechette/index.ts

@@ -5,6 +5,11 @@
 
 import type { VgiBackendInfo } from "../types.js";
 
+// Side-effect import: installs the arrow-js-shaped methods flechette's Column
+// and Table lack (`isValid`, `slice`). Must come before anything hands a
+// column or a table to worker code. See ./compat.ts.
+import "./compat.js";
+
 export const backend: VgiBackendInfo = { name: "flechette" };
 
 // Schema / Field / DataType factories
@@ -53,3 +58,6 @@ export {
 
 // Column statistics — sparse-union min/max via the codec/canonical path.
 export { buildStatisticsBatch, type ColumnStatistics } from "./statistics.js";
+
+// Arrow-js shape adoption for batches built by another copy of flechette.
+export { adoptArrowJsShape } from "./compat.js";

package/src/arrow/impl-flechette/ipc.ts

@@ -17,6 +17,8 @@ import {
 
 import type { VgiSchema, VgiBatch } from "../types.js";
 import { readFirstRecordBatchMeta } from "./message-meta.js";
+import { normalizeDecodedSchema } from "./arrowjs-shape.js";
+import { toFlechetteType } from "./normalize-type.js";
 
 // flechette decoding options that match how vgi-typescript callers expect
 // values to come out: 64-bit ints stay as BigInt, decimals as scaled BigInts,
@@ -28,6 +30,38 @@ const EXTRACT_OPTS = {
   useMap: false,
 } as const;
 
+/**
+ * Re-base an IPC stream onto an 8-byte-aligned ArrayBuffer offset.
+ *
+ * flechette decodes record-batch buffers zero-copy, as
+ * `new ArrayType(bytes.buffer, bytes.byteOffset + region.offset, …)`. The Arrow
+ * IPC stream format guarantees `region.offset` is 8-byte aligned *relative to
+ * the message body*, so that view is only legal when the stream's own
+ * `byteOffset` is 8-byte aligned too. `TypedArray` throws
+ * `RangeError: Byte offset is not aligned` otherwise, and there is no way to
+ * recover after the fact.
+ *
+ * Nothing upstream promises that alignment. VGI hands us IPC streams that are
+ * views into a larger buffer at an arbitrary offset:
+ *   * `splitLenPrefixed` subarrays past a 4-byte length prefix (odd by
+ *     construction — buffering init/state payloads);
+ *   * Arrow Binary column values, which are packed back-to-back in a shared
+ *     data buffer with no per-value padding (nested IPC in state tokens,
+ *     `init_request`, secret payloads);
+ *   * HTTP body slices handed over by the runtime.
+ *
+ * arrow-js hides this by copying every misaligned buffer inside
+ * `toArrayBufferView`, which is why the arrow-js backend never saw it. We copy
+ * once here instead — the whole stream, so every body inside it keeps its
+ * relative alignment — and only when the input is actually misaligned, so the
+ * common already-aligned case stays zero-copy.
+ */
+function align8(bytes: Uint8Array): Uint8Array {
+  if ((bytes.byteOffset & 7) === 0) return bytes;
+  // `slice` copies into a fresh ArrayBuffer, whose byteOffset is 0.
+  return bytes.slice();
+}
+
 /**
  * Serialize a Schema to Arrow IPC bytes.
  *
@@ -41,9 +75,17 @@ export function serializeSchema(schema: VgiSchema): Uint8Array {
   // tableFromColumns rebuilds fields with nullable=true, which round-trips
   // wrong on the C++ side (rejects schema-conforming payloads as schema
   // mismatches). See build.ts for the same fix on batches.
-  const cols = schema.fields.map((f) => columnFromArray([], f.type as any));
+  //
+  // Types are normalized to flechette-native first. Callers routinely declare
+  // schemas with arrow-js DataType instances (`new FixedSizeList(2, …)`), and
+  // flechette's IPC writer reads the *flechette* property names off whatever
+  // object it is handed — `stride`, not arrow-js's `listSize` — so a foreign
+  // type serializes with its parameters silently zeroed. That is what emitted
+  // `DOUBLE[0]` for a `DOUBLE[2]` argument and made DuckDB refuse the cast.
+  const types = schema.fields.map((f) => toFlechetteType(f.type));
+  const cols = types.map((t) => columnFromArray([], t as any));
   const fields = schema.fields.map((f, i) =>
-    f_field(f.name, cols[i].type as any, (f as any).nullable ?? true, (f as any).metadata ?? null),
+    f_field(f.name, types[i], (f as any).nullable ?? true, (f as any).metadata ?? null),
   );
   const flechSchema = {
     version: 5,
@@ -59,9 +101,9 @@ export function serializeSchema(schema: VgiSchema): Uint8Array {
  * decoded table (which may be 0-row if the source was a schema-only stream).
  */
 export function deserializeSchema(bytes: Uint8Array): VgiSchema {
-  const table = tableFromIPC(bytes, EXTRACT_OPTS);
+  const table = tableFromIPC(align8(bytes), EXTRACT_OPTS);
   // flechette's Table.schema is the structural shape we need.
-  return table.schema as unknown as VgiSchema;
+  return normalizeDecodedSchema(table.schema) as unknown as VgiSchema;
 }
 
 /**
@@ -74,7 +116,27 @@ export function deserializeSchema(bytes: Uint8Array): VgiSchema {
  */
 export function serializeBatch(batch: VgiBatch): Uint8Array {
   // VgiBatch is structurally a flechette Table at this point.
-  return tableToIPC(batch as any, { format: "stream" }) as Uint8Array;
+  const t = batch as any;
+  // Two things `tableToIPC` will not do on its own, and arrow-js's
+  // `_writeRecordBatch` always does:
+  //
+  //  1. Emit a RecordBatch message when the table has no column data to walk.
+  //     flechette derives its record batches from `columns[0].data`, so a
+  //     zero-FIELD table (a legal vgi-rpc shape — `aggregate_update`'s ack,
+  //     cancel signals, state-token carriers) encodes as schema + EOS with no
+  //     batch at all. The C++ client reads that as "RPC returned an empty
+  //     response" and fails the query.
+  //  2. Pick up per-batch `custom_metadata`. `withBatchMetadata` pins the map
+  //     on `_vgiRecordMetadata`, but only the `batchMetadata` encode option
+  //     puts it on the wire — so cache/state metadata was being dropped on
+  //     serialize even though it read back correctly in-process.
+  //
+  // Passing a one-entry positional `batchMetadata` covers both: it synthesises
+  // the missing empty batch and attaches the map when there is one. Tables
+  // that already have batches and no metadata are unaffected.
+  const md: Map<string, string> | undefined = t._vgiRecordMetadata ?? t.metadata;
+  const batchMetadata = [md && md.size > 0 ? md : undefined];
+  return tableToIPC(t, { format: "stream", batchMetadata } as any) as Uint8Array;
 }
 
 /**
@@ -85,8 +147,12 @@ export function serializeBatch(batch: VgiBatch): Uint8Array {
  * multi-batch streams this collapses to a single logical batch, matching
  * the subprocess transport's one-batch-per-call convention.
  */
-export function deserializeBatch(bytes: Uint8Array): VgiBatch {
+export function deserializeBatch(input: Uint8Array): VgiBatch {
+  const bytes = align8(input);
   const table: any = tableFromIPC(bytes, EXTRACT_OPTS);
+  // Worker code reads `batch.schema.fields[i].type.isSigned` (arrow-js's
+  // spelling) to pick promoted result types; flechette spells it `signed`.
+  normalizeDecodedSchema(table.schema);
   // flechette's IPC parser ignores the Message-level `custom_metadata` field
   // and reports row counts only via column children, so a "metadata-only"
   // batch over a 0-field schema (legal in vgi-rpc — used to ferry state

package/src/arrow/impl-flechette/normalize-type.ts

@@ -23,6 +23,8 @@ import {
   list, largeList, fixedSizeList, struct, map, dictionary, union,
 } from "@query-farm/flechette";
 
+import { aliasIntSigned } from "./arrowjs-shape.js";
+
 function fField(f: any): any {
   return f_field(f.name, toFlechetteType(f.type), f.nullable ?? true, f.metadata ?? null);
 }
@@ -40,7 +42,9 @@ export function toFlechetteType(type: any): any {
     case Type.Bool:
       return bool();
     case Type.Int:
-      return int(type.bitWidth, type.isSigned ?? type.signed ?? true);
+      // Keep the arrow-js-spelled `isSigned` readable on the result — worker
+      // code round-trips types through here and then branches on it.
+      return aliasIntSigned(int(type.bitWidth, type.isSigned ?? type.signed ?? true));
     case Type.Float:
       return float(type.precision);
     case Type.Binary:
@@ -67,7 +71,11 @@ export function toFlechetteType(type: any): any {
     case Type.LargeList:
       return (type.typeId === Type.LargeList ? largeList : list)(fField(type.children[0]));
     case Type.FixedSizeList:
-      return fixedSizeList(fField(type.children[0]), type.listSize);
+      // arrow-js calls the width `listSize`, flechette calls it `stride`.
+      // Reading only the first makes this non-idempotent: normalizing an
+      // already-native type would zero the width and DuckDB then refuses to
+      // cast INT[3] to INT[0].
+      return fixedSizeList(fField(type.children[0]), type.listSize ?? type.stride);
     case Type.Struct:
       return struct(type.children.map(fField));
     case Type.Map: {

package/src/arrow/impl-flechette/schema.ts

@@ -52,6 +52,7 @@ import {
 } from "@query-farm/flechette";
 
 import type { VgiField, VgiSchema, VgiDataType } from "../types.js";
+import { aliasIntSigned } from "./arrowjs-shape.js";
 
 // ----- Unit / mode constants -----------------------------------------------
 
@@ -91,16 +92,19 @@ export function field(
 export const nullType = (): VgiDataType => f_nullType() as unknown as VgiDataType;
 export const bool = (): VgiDataType => f_bool() as unknown as VgiDataType;
 
-export const int8 = (): VgiDataType => f_int8() as unknown as VgiDataType;
-export const int16 = (): VgiDataType => f_int16() as unknown as VgiDataType;
-export const int32 = (): VgiDataType => f_int32() as unknown as VgiDataType;
-export const int64 = (): VgiDataType => f_int64() as unknown as VgiDataType;
-export const uint8 = (): VgiDataType => f_uint8() as unknown as VgiDataType;
-export const uint16 = (): VgiDataType => f_uint16() as unknown as VgiDataType;
-export const uint32 = (): VgiDataType => f_uint32() as unknown as VgiDataType;
-export const uint64 = (): VgiDataType => f_uint64() as unknown as VgiDataType;
+// Int types carry the `isSigned` alias (arrow-js's spelling of flechette's
+// `signed`) so worker code that branches on signedness reads the same property
+// on both backends — see ./compat.ts.
+export const int8 = (): VgiDataType => aliasIntSigned(f_int8()) as unknown as VgiDataType;
+export const int16 = (): VgiDataType => aliasIntSigned(f_int16()) as unknown as VgiDataType;
+export const int32 = (): VgiDataType => aliasIntSigned(f_int32()) as unknown as VgiDataType;
+export const int64 = (): VgiDataType => aliasIntSigned(f_int64()) as unknown as VgiDataType;
+export const uint8 = (): VgiDataType => aliasIntSigned(f_uint8()) as unknown as VgiDataType;
+export const uint16 = (): VgiDataType => aliasIntSigned(f_uint16()) as unknown as VgiDataType;
+export const uint32 = (): VgiDataType => aliasIntSigned(f_uint32()) as unknown as VgiDataType;
+export const uint64 = (): VgiDataType => aliasIntSigned(f_uint64()) as unknown as VgiDataType;
 export const int = (bitWidth: 8 | 16 | 32 | 64 = 32, signed = true): VgiDataType =>
-  f_int(bitWidth, signed) as unknown as VgiDataType;
+  aliasIntSigned(f_int(bitWidth, signed)) as unknown as VgiDataType;
 
 export const float16 = (): VgiDataType => f_float16() as unknown as VgiDataType;
 export const float32 = (): VgiDataType => f_float32() as unknown as VgiDataType;