@query-farm/vgi 0.20.0 → 0.21.0

package/src/arrow/index.ts

@@ -44,6 +44,7 @@ export {
   isDuration,
   isDictionary,
   isBatch,
+  typeSignature,
 } from "./predicates.js";
 
 // Active backend's surface (IPC, build, iterate, utilities).
@@ -55,6 +56,8 @@ export {
   filterBatch, projectSchema, projectBatch,
   // per-record-batch metadata attachment
   withBatchMetadata,
+  // arrow-js method shape for batches decoded outside this module's backend copy
+  adoptArrowJsShape,
   // canonical single-value read (backend-agnostic, lossless)
   readCanonicalValue,
   // IPC

package/src/arrow/predicates.ts

@@ -53,6 +53,65 @@ export function isMap(t: VgiDataType): boolean { return t.typeId === TypeId.Map;
 export function isDuration(t: VgiDataType): boolean { return t.typeId === TypeId.Duration; }
 export function isDictionary(t: VgiDataType): boolean { return t.typeId === TypeId.Dictionary; }
 
+/**
+ * Stable structural identity for an Arrow type, usable for equality.
+ *
+ * `String(type)` is NOT usable for this: arrow-js DataTypes are class
+ * instances with a meaningful `toString()` ("Int64", "Utf8", …), while
+ * flechette types are plain object literals that stringify to
+ * "[object Object]". Comparing with `toString()` therefore reports *every*
+ * flechette type as equal to every other, and never equal to a declared
+ * arrow-js type — which collapsed overload resolution to a first-match tie
+ * (`type_info(42::BIGINT)` picked the INTEGER overload).
+ *
+ * Both libraries agree on `typeId` and on the parameter *values*; they differ
+ * only on a few property names, so those are read under both spellings. The
+ * output is an opaque key — compare it, don't display it.
+ */
+export function typeSignature(t: VgiDataType | null | undefined): string {
+  if (t == null) return "null";
+  const a = t as any;
+  const kids = (): string =>
+    Array.isArray(a.children)
+      ? a.children.map((c: any) => `${c?.name ?? ""}:${typeSignature(c?.type ?? c)}`).join(",")
+      : "";
+  switch (t.typeId) {
+    case TypeId.Int:
+      return `int${a.bitWidth}${(a.isSigned ?? a.signed ?? true) ? "" : "u"}`;
+    case TypeId.Float:
+      return `float${a.precision}`;
+    case TypeId.Decimal:
+      return `decimal${a.bitWidth ?? 128}(${a.precision},${a.scale})`;
+    case TypeId.Date:
+    case TypeId.Time:
+    case TypeId.Duration:
+      return `${t.typeId}[${a.unit}]`;
+    case TypeId.Timestamp:
+      return `ts[${a.unit},${a.timezone ?? ""}]`;
+    case TypeId.Interval:
+      return `iv[${a.unit}]`;
+    case TypeId.FixedSizeBinary:
+      return `fsb(${a.byteWidth ?? a.stride})`;
+    case TypeId.FixedSizeList:
+      return `fsl(${a.listSize ?? a.stride},${kids()})`;
+    case TypeId.List:
+    case TypeId.Struct:
+    case TypeId.Map:
+      return `${t.typeId}<${kids()}>`;
+    case TypeId.Union:
+      return `union(${a.mode},${kids()})`;
+    case TypeId.Dictionary:
+      return `dict(${typeSignature(a.dictionary)},${typeSignature(a.indices)},${
+        a.ordered ?? a.isOrdered ?? false
+      })`;
+    default:
+      // Covers the parameterless types (Null, Bool, Utf8, Binary and their
+      // Large variants) plus anything not enumerated above; children are
+      // folded in when present so a nested type still differentiates.
+      return Array.isArray(a.children) ? `${t.typeId}<${kids()}>` : String(t.typeId);
+  }
+}
+
 /** Runtime check: does `x` quack like a VgiBatch? Used at API boundaries
  *  where callers may pass either a batch or a plain column dict. Duck-typed
  *  because arrow-js and flechette use unrelated classes. */

package/src/cache-control.ts

@@ -41,6 +41,7 @@ export const CACHE_REVALIDATABLE_KEY = "vgi.cache.revalidatable";
 export const CACHE_STALE_WHILE_REVALIDATE_KEY = "vgi.cache.stale_while_revalidate";
 export const CACHE_STALE_IF_ERROR_KEY = "vgi.cache.stale_if_error";
 export const CACHE_NOT_MODIFIED_KEY = "vgi.cache.not_modified";
+export const CACHE_PARTITION_SCOPE_KEY = "vgi.cache.partition_scope";
 
 // --- Request-side metadata keys (client -> worker) --------------------------
 // Ride on the first producer tick; surfaced as `TableProcessParams.ifNoneMatch`
@@ -91,6 +92,12 @@ export interface CacheControl {
    *  assert the client's stored payload is still fresh (the client reuses it
    *  instead of re-streaming). */
   notModified?: boolean;
+  /** Opt in to per-PARTITION caching: in addition to the whole-scan entry, the
+   *  client stores the result split by distinct partition tuple, so a later
+   *  `=`/`IN`-filtered scan on the partition column(s) can serve the requested
+   *  partitions without calling the worker. Only meaningful for a
+   *  `SINGLE_VALUE_PARTITIONS` table function; purely additive. */
+  partitionScope?: boolean;
 }
 
 const VALID_SCOPES: readonly string[] = [CACHE_SCOPE_CATALOG, CACHE_SCOPE_TRANSACTION];
@@ -129,5 +136,6 @@ export function cacheControlMetadata(cc: CacheControl, extra?: Map<string, strin
   if (cc.staleWhileRevalidate !== undefined) md.set(CACHE_STALE_WHILE_REVALIDATE_KEY, String(cc.staleWhileRevalidate));
   if (cc.staleIfError !== undefined) md.set(CACHE_STALE_IF_ERROR_KEY, String(cc.staleIfError));
   if (cc.notModified) md.set(CACHE_NOT_MODIFIED_KEY, "1");
+  if (cc.partitionScope) md.set(CACHE_PARTITION_SCOPE_KEY, "1");
   return md;
 }

package/src/functions/registry.ts

@@ -1,7 +1,11 @@
 // Copyright 2025, 2026 Query Farm LLC - https://query.farm
 // Function registry: name -> VgiFunction lookup with overload resolution.
 
-import { type VgiDataType, isBinary, isBool, isDecimal, isFloat, isInt, isNull, isUtf8 } from "../arrow/index.js";
+import {
+  type VgiDataType,
+  isBinary, isBool, isDecimal, isFloat, isInt, isNull, isUtf8,
+  typeSignature,
+} from "../arrow/index.js";
 import type { VgiSchema } from "../arrow/index.js";
 import type { VgiFunction } from "./types.js";
 import type { Arguments } from "../arguments/arguments.js";
@@ -17,8 +21,21 @@ export interface OverloadContext {
 const EXACT_MATCH_SCORE = 2;
 const FAMILY_MATCH_SCORE = 1;
 
+/**
+ * Exact structural type identity.
+ *
+ * `toString()` cannot be used: arrow-js DataTypes stringify to a meaningful
+ * name, flechette's plain-object types all stringify to "[object Object]".
+ * Under flechette that made every exact-match test fail, every overload score
+ * collapse to the family tie, and `type_info(42::BIGINT)` resolve to the
+ * INTEGER overload.
+ */
+function typesIdentical(a: VgiDataType, b: VgiDataType): boolean {
+  return typeSignature(a) === typeSignature(b);
+}
+
 function typesCompatible(actual: VgiDataType, declared: VgiDataType): boolean {
-  if (actual.toString() === declared.toString()) return true;
+  if (typesIdentical(actual, declared)) return true;
   // Integer family
   if (isInt(actual) && isInt(declared)) return true;
   // Float/decimal family
@@ -47,7 +64,7 @@ function scoreTypes(
     if (spec.isAnyType || isNull(spec.arrowType)) continue;
     const actual = actualTypes[i];
     if (actual === null) continue;
-    if (actual.toString() === spec.arrowType.toString()) {
+    if (typesIdentical(actual, spec.arrowType)) {
       score += EXACT_MATCH_SCORE;
     } else if (typesCompatible(actual, spec.arrowType)) {
       score += FAMILY_MATCH_SCORE;
@@ -61,7 +78,7 @@ function scoreTypes(
     for (let i = specs.length; i < actualTypes.length; i++) {
       const actual = actualTypes[i];
       if (actual === null) continue;
-      if (actual.toString() === varArgsSpec.arrowType.toString()) {
+      if (typesIdentical(actual, varArgsSpec.arrowType)) {
         score += EXACT_MATCH_SCORE;
       } else if (typesCompatible(actual, varArgsSpec.arrowType)) {
         score += FAMILY_MATCH_SCORE;

package/src/index.core.ts

@@ -16,6 +16,7 @@ export {
   CACHE_LAST_MODIFIED_KEY,
   CACHE_NO_STORE_KEY,
   CACHE_NOT_MODIFIED_KEY,
+  CACHE_PARTITION_SCOPE_KEY,
   CACHE_REVALIDATABLE_KEY,
   CACHE_SCOPE_CATALOG,
   CACHE_SCOPE_KEY,
@@ -247,7 +248,9 @@ export {
   isNull, isInt, isFloat, isBinary, isUtf8, isBool, isDecimal, isDate,
   isTime, isTimestamp, isInterval, isList, isStruct, isUnion,
   isFixedSizeBinary, isFixedSizeList, isMap, isDuration, isDictionary, isBatch,
+  typeSignature,
   readCanonicalValue, columnFromArray, decodeDictValue, backend,
+  adoptArrowJsShape,
 } from "./arrow/index.js";
 
 export type {

package/src/protocol/handlers/function.ts

@@ -16,7 +16,7 @@ import {
   serializeTableCardinality,
 } from "../serialize.js";
 import type { GlobalInitResponse } from "../types.js";
-import { batchToScalarDict, deserializeBatch } from "../../util/arrow/index.js";
+import { batchToScalarDict, deserializeBatch, adoptArrowJsShape } from "../../util/arrow/index.js";
 import { toUint8Array } from "../../util/bytes.js";
 import { serializeColumnStatistics } from "../../util/statistics.js";
 import { BindResultSchema, TableFunctionCardinalityResultSchema, TableFunctionDynamicToStringResultSchema } from "../../generated/vgi-protocol-schemas.js";
@@ -153,6 +153,14 @@ export function registerFunctionMethods(protocol: Protocol, config: FunctionHand
       return state;
     },
     exchange: async (state, input, out) => {
+      // `input` is the one batch worker code sees that this package did not
+      // decode — vgi-rpc read it off the wire with its own Arrow backend. If
+      // that resolved to a second copy of @query-farm/flechette (nested under
+      // vgi-rpc whenever the version ranges disagree, even transiently), the
+      // facade's prototype patches never touched its classes and user code
+      // gets `col.isValid is not a function` on the first exchange round.
+      // Adopting here is a WeakSet probe per call and a no-op on arrow-js.
+      input = adoptArrowJsShape(input);
       // Reconstruct live objects from serializable state.
       // This handles both immediate use (producer during init, where _handlers
       // is still present) and deserialized exchange (where we reconstruct).

package/src/util/arrow/index.ts

@@ -20,4 +20,5 @@ export {
   deserializeSchema,
   serializeBatch,
   deserializeBatch,
+  adoptArrowJsShape,
 } from "../../arrow/index.js";