@query-farm/vgi 0.20.0 → 0.22.0

package/dist/arrow/impl-arrowjs/index.d.ts

@@ -10,3 +10,10 @@ export { readCanonicalValue } from "./canonical.js";
 export { withBatchMetadata } from "./metadata.js";
 export { serializeSchema, deserializeSchema, serializeBatch, deserializeBatch, } from "./ipc.js";
 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 declare function adoptArrowJsShape<T>(batch: T): T;

package/dist/arrow/impl-flechette/arrowjs-shape.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function aliasIntSigned<T>(type: T): T;
+/**
+ * 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 declare function normalizeDecodedSchema<T>(schema: T): T;

package/dist/arrow/impl-flechette/compat.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare function adoptArrowJsShape<T>(batch: T): T;

package/dist/arrow/impl-flechette/index.d.ts

@@ -1,4 +1,5 @@
 import type { VgiBackendInfo } from "../types.js";
+import "./compat.js";
 export declare const backend: VgiBackendInfo;
 export { schema, field, nullType, bool, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, float16, float32, float64, utf8, binary, fixedSizeBinary, decimal, decimal128, decimal256, date, dateDay, dateMillisecond, time, timeSecond, timeMillisecond, timeMicrosecond, timeNanosecond, timestamp, duration, interval, list, fixedSizeList, struct, map, dictionary, union, sparseUnion, denseUnion, TimeUnit, DateUnit, IntervalUnit, UnionMode, } from "./schema.js";
 export { emptyBatch } from "./empty.js";
@@ -10,3 +11,4 @@ export { readCanonicalValue } from "./canonical.js";
 export { withBatchMetadata } from "./metadata.js";
 export { serializeSchema, deserializeSchema, serializeBatch, deserializeBatch, } from "./ipc.js";
 export { buildStatisticsBatch, type ColumnStatistics } from "./statistics.js";
+export { adoptArrowJsShape } from "./compat.js";

package/dist/arrow/impl-flechette/ipc.d.ts

@@ -30,4 +30,4 @@ export declare 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 declare function deserializeBatch(bytes: Uint8Array): VgiBatch;
+export declare function deserializeBatch(input: Uint8Array): VgiBatch;

package/dist/arrow/index.d.ts

@@ -1,6 +1,6 @@
 export type { VgiTypeId, VgiDataType, VgiField, VgiSchema, VgiColumn, VgiColumnData, VgiBatch, VgiBackendInfo, TaggedUnion, } from "./types.js";
-export { TypeId, isNull, isInt, isFloat, isBinary, isUtf8, isBool, isDecimal, isDate, isTime, isTimestamp, isInterval, isList, isStruct, isUnion, isFixedSizeBinary, isFixedSizeList, isMap, isDuration, isDictionary, isBatch, } from "./predicates.js";
-export { backend, emptyBatch, batchFromRows, batchFromColumns, columnFromArray, iterRows, batchToScalarDict, batchToSecretDict, safeNumber, decodeDictValue, filterBatch, projectSchema, projectBatch, withBatchMetadata, readCanonicalValue, serializeSchema, deserializeSchema, serializeBatch, deserializeBatch, buildStatisticsBatch, } from "#arrow-impl";
+export { TypeId, isNull, isInt, isFloat, isBinary, isUtf8, isBool, isDecimal, isDate, isTime, isTimestamp, isInterval, isList, isStruct, isUnion, isFixedSizeBinary, isFixedSizeList, isMap, isDuration, isDictionary, isBatch, typeSignature, } from "./predicates.js";
+export { backend, emptyBatch, batchFromRows, batchFromColumns, columnFromArray, iterRows, batchToScalarDict, batchToSecretDict, safeNumber, decodeDictValue, filterBatch, projectSchema, projectBatch, withBatchMetadata, adoptArrowJsShape, readCanonicalValue, serializeSchema, deserializeSchema, serializeBatch, deserializeBatch, buildStatisticsBatch, } from "#arrow-impl";
 export type { ColumnStatistics } from "#arrow-impl";
 export { schema, field, nullType, bool, int, int8, int16, int32, int64, uint8, uint16, uint32, uint64, float16, float32, float64, utf8, binary, fixedSizeBinary, decimal, decimal128, decimal256, date, dateDay, dateMillisecond, time, timeSecond, timeMillisecond, timeMicrosecond, timeNanosecond, timestamp, duration, interval, timestampSeconds, timestampMillis, timestampMicros, timestampNanos, durationSeconds, durationMillis, durationMicros, durationNanos, list, fixedSizeList, struct, map, dictionary, union, sparseUnion, denseUnion, TimeUnit, DateUnit, IntervalUnit, UnionMode, } from "./schema-types.js";
 export type { NullDescriptor, BoolType, IntType, Int8Type, Int16Type, Int32Type, Int64Type, Uint8Type, Uint16Type, Uint32Type, Uint64Type, FloatType, Utf8Type, LargeUtf8Type, BinaryType, LargeBinaryType, FixedSizeBinaryType, DecimalType, Date32Type, Date64Type, Time32Type, Time64Type, TimestampType, DurationType, IntervalType, ListType, FixedSizeListType, StructType, MapType, DictionaryType, UnionType, TypedField, TUnit, } from "./codec/type-descriptors.js";

package/dist/arrow/predicates.d.ts

@@ -41,6 +41,22 @@ export declare function isFixedSizeList(t: VgiDataType): boolean;
 export declare function isMap(t: VgiDataType): boolean;
 export declare function isDuration(t: VgiDataType): boolean;
 export declare function isDictionary(t: VgiDataType): boolean;
+/**
+ * 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 declare function typeSignature(t: VgiDataType | null | undefined): string;
 /** 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/dist/cache-control.d.ts

@@ -35,6 +35,8 @@ export declare const CACHE_REVALIDATABLE_KEY = "vgi.cache.revalidatable";
 export declare const CACHE_STALE_WHILE_REVALIDATE_KEY = "vgi.cache.stale_while_revalidate";
 export declare const CACHE_STALE_IF_ERROR_KEY = "vgi.cache.stale_if_error";
 export declare const CACHE_NOT_MODIFIED_KEY = "vgi.cache.not_modified";
+export declare const CACHE_PARTITION_SCOPE_KEY = "vgi.cache.partition_scope";
+export declare const CACHE_PER_VALUE_KEY = "vgi.cache.per_value";
 export declare const CACHE_IF_NONE_MATCH_KEY = "vgi.cache.if_none_match";
 export declare const CACHE_IF_MODIFIED_SINCE_KEY = "vgi.cache.if_modified_since";
 export declare const CACHE_SCOPE_CATALOG = "catalog";
@@ -75,6 +77,37 @@ 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;
+    /**
+     * Opt in to per-VALUE memoization: in addition to the whole-result entry, the
+     * client memoizes each distinct worker-input tuple's output keyed on that
+     * tuple, so the same value is served without calling the worker on a later
+     * chunk or a later query. Only meaningful for an exchange-mode MAP — a
+     * scalar, or a blended table-in-out invoked through a correlated `LATERAL`.
+     *
+     * **Default off, and it should stay off unless one call is genuinely
+     * expensive.** This is not a free win: serving a value from the memo costs a
+     * key probe, a decode and a per-value assembly step, and that only pays back
+     * when it is cheaper than asking you for the answer. For a cheap map —
+     * arithmetic, a string tweak, a lookup in a table the worker already has in
+     * memory — it is a large net loss (the engine measures a per-value serve at
+     * roughly 50x the cost of just calling the worker for a simple arithmetic
+     * map). Only the function author knows which side of that line a call falls
+     * on, which is why the engine will not guess: turn it on for model
+     * inference, geocoding, an external API call, or anything rate-limited or
+     * billed per request.
+     *
+     * Independent of freshness: `ttl`/`expires` make a result cacheable at all,
+     * while this decides whether the per-value tier is additionally populated.
+     * Requires a deterministic, side-effect-free function, exactly like the rest
+     * of the result cache.
+     */
+    perValue?: boolean;
 }
 /**
  * Render a {@link CacheControl} to the `vgi.cache.*` batch-metadata map.

package/dist/catalog/composite.d.ts

@@ -4,6 +4,8 @@ export declare class CompositeCatalogInterface extends CatalogInterface {
     private readonly _backends;
     constructor(_backends: CatalogInterface[]);
     private _route;
+    /** Route to the owning backend and ask it, so the answer is per-attachment. */
+    catalogNameForAttach(attachOpaqueData: Uint8Array): string | null;
     catalogs(): string[];
     catalogsInfo(): Promise<CatalogInfo[]>;
     attach(name: string, options?: Record<string, unknown>, dataVersionSpec?: string | null, implementationVersion?: string | null): Promise<CatalogAttachResult>;

package/dist/catalog/interface.d.ts

@@ -180,6 +180,17 @@ export declare function buildScanBranchesResult(branches: ScanBranchInput[], req
  */
 type Awaitable<T> = T | Promise<T>;
 export declare abstract class CatalogInterface {
+    /**
+     * Which catalog an `attach_opaque_data` belongs to, or null if unknown.
+     *
+     * Two catalogs served by one worker may declare the same schema *and*
+     * function name, in which case the attachment is the only thing that tells
+     * them apart — the bind path uses this to scope function resolution. The
+     * default answers from `catalogs()` when this interface owns exactly one,
+     * which is right for every single-catalog implementation; the composite
+     * overrides it to route by its backend index byte.
+     */
+    catalogNameForAttach(_attachOpaqueData: Uint8Array): string | null;
     abstract catalogs(): string[];
     /**
      * Attach this catalog. The framework already validates ATTACH options

package/dist/client-entry.js

@@ -122,6 +122,7 @@ __export(exports_impl_arrowjs, {
   batchFromRows: () => batchFromRows,
   batchFromColumns: () => batchFromColumns,
   backend: () => backend,
+  adoptArrowJsShape: () => adoptArrowJsShape,
   UnionMode: () => UnionMode,
   TimeUnit: () => TimeUnit,
   IntervalUnit: () => IntervalUnit,
@@ -1758,6 +1759,9 @@ function assemble(columnNames, minData, maxData, hasNull, hasNotNull, distinctCo
 
 // src/arrow/impl-arrowjs/index.ts
 var backend = { name: "arrow-js" };
+function adoptArrowJsShape(batch) {
+  return batch;
+}
 // src/arrow/schema-types.ts
 var { TimeUnit: TimeUnit2, DateUnit: DateUnit3, IntervalUnit: IntervalUnit2, UnionMode: UnionMode2, schema: schema2 } = exports_impl_arrowjs;
 function field2(name, type, nullable, metadata) {
@@ -2000,7 +2004,8 @@ var BIND_REQUEST_SCHEMA = schema2([
   field2("transaction_opaque_data", binary2(), true),
   field2("resolved_secrets_provided", bool2(), false),
   field2("at_unit", utf82(), true),
-  field2("at_value", utf82(), true)
+  field2("at_value", utf82(), true),
+  field2("schema_name", utf82(), true)
 ]);
 var COPY_FROM_STRUCT_TYPE = struct2([
   field2("format", utf82(), false),
@@ -2032,7 +2037,8 @@ function serializeBindRequest(req) {
     transaction_opaque_data: req.transaction_opaque_data ?? null,
     resolved_secrets_provided: req.resolved_secrets_provided ?? false,
     at_unit: req.at_unit ?? null,
-    at_value: req.at_value ?? null
+    at_value: req.at_value ?? null,
+    schema_name: req.schema_name ?? null
   };
   const extraFields = [];
   if (req.copy_from) {
@@ -3917,4 +3923,4 @@ export {
   ArgumentValidationError
 };
 
-//# debugId=7B4A06FF3B2070C464756E2164756E21
+//# debugId=FCC2DEE998E0D9AC64756E2164756E21