@query-farm/vgi 0.6.0

package/src/index.core.ts

@@ -0,0 +1,267 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// VGI TypeScript - Public API (runtime-agnostic core)
+//
+// Everything exported from the package EXCEPT the node-only `Worker` (which
+// imports the AF_UNIX launcher's `serveUnix` from @query-farm/vgi-rpc). This
+// module must stay free of static node-only value imports so it can be bundled
+// for Cloudflare Workers / browsers via worker-cf-entry.ts. The node/bun barrel
+// (`./index.ts`) re-exports this plus `Worker`.
+
+// Function factories (primary API)
+export { defineScalarFunction, type ScalarFunctionConfig, type ScalarBindParameters, type ScalarParameterDef } from "./functions/scalar.js";
+export { defineTableFunction, type TableFunctionConfig, type TableBindParams, type TableProcessParams } from "./functions/table.js";
+export {
+  defineAggregate,
+  GROUP_COLUMN_NAME,
+  type AggregateFunctionConfig,
+  type AggregateBindParams,
+  type AggregateUpdateParams,
+  type AggregateFinalizeParams,
+} from "./functions/aggregate.js";
+export { defineTableInOutFunction, type TableInOutConfig, type TableInOutBindParams, type TableInOutProcessParams } from "./functions/table-in-out.js";
+export {
+  defineTableBufferingFunction,
+  type TableBufferingConfig,
+  type TableBufferingBindParams,
+  type TableBufferingParams,
+  type TableBufferingVgiFunction,
+} from "./functions/table-buffering.js";
+export {
+  defineCopyFromFunction,
+  type CopyFromFunctionConfig,
+  type CopyFromOption,
+  type CopyFromReadParams,
+} from "./functions/copy-from.js";
+export {
+  defineCopyToFunction,
+  type CopyToFunctionConfig,
+  type CopyToOption,
+  type CopyToWriteParams,
+  type CopyToCloseParams,
+} from "./functions/copy-to.js";
+
+// Function types
+export type { VgiFunction, FunctionMeta, StreamHandlers, FunctionExample, HandlerState } from "./functions/types.js";
+
+// Catalog
+export { CatalogInterface, type CatalogAttachResult, type SchemaInfo, encodeSchemaInfo, decodeSchemaInfo, type TableInfo, encodeTableInfo, decodeTableInfo, type ViewInfo, encodeViewInfo, decodeViewInfo, type CatalogInfo, encodeCatalogInfo, decodeCatalogInfo, type FunctionInfo, encodeFunctionInfo, decodeFunctionInfo, type FunctionInfoOptions, type MacroInfo, encodeMacroInfo, decodeMacroInfo, type MacroType, type CopyFromFormatInfo, encodeCopyFromFormatInfo, type AttachOpaqueData, type TransactionOpaqueData, buildScanBranchesResult, type ScanBranchInput } from "./catalog/interface.js";
+export type { CatalogDescriptor, SchemaDescriptor, TableDescriptor, ViewDescriptor, MacroDescriptor, SettingDescriptor, SecretTypeDescriptor, ForeignKeyDef, DefaultValue } from "./catalog/descriptors.js";
+export { ReadOnlyCatalogInterface } from "./catalog/read-only.js";
+export { CompositeCatalogInterface } from "./catalog/composite.js";
+export { FunctionRegistry } from "./functions/registry.js";
+
+// Core types
+export {
+  FunctionType,
+  FunctionStability,
+  NullHandling,
+  OrderPreservation,
+  OrderDependence,
+  DistinctDependence,
+  TableInOutPhase,
+  DEFAULT_MAX_WORKERS,
+} from "./types.js";
+
+// Protocol types
+export type {
+  BindRequest,
+  BindResponse,
+  CopyFromContext,
+  CopyToContext,
+  InitRequest,
+  GlobalInitResponse,
+  TableCardinality,
+} from "./protocol/types.js";
+
+// Arguments
+export { Arguments } from "./arguments/arguments.js";
+export { type ArgumentSpec, argumentSpecsToSchema, schemaToArgumentSpecs, macroArgumentsSchema, macroParameterDocsFromSchema } from "./arguments/argument-spec.js";
+
+// Errors
+export {
+  VgiError,
+  RowCountMismatchError,
+  FunctionNotFoundError,
+  CatalogReadOnlyError,
+  CatalogNotFoundError,
+  CatalogAlreadyExistsError,
+  ArgumentValidationError,
+  NoCatalogError,
+} from "./errors.js";
+
+// Metadata
+export type { ResolvedMetadata, ParameterInfo } from "./metadata/types.js";
+export { CatalogFunctionType } from "./metadata/types.js";
+export { resolveMetadata } from "./metadata/resolve.js";
+export { metadatasToArrow, arrowToMetadatas } from "./metadata/serialize.js";
+
+// Filter pushdown
+export {
+  PushdownFilters,
+  FilteringOutputCollector,
+  deserializeFilters,
+  buildJoinKeysLookup,
+  ComparisonOp,
+  type Filter,
+  type ConstantFilter,
+  type IsNullFilter,
+  type IsNotNullFilter,
+  type InFilter,
+  type AndFilter,
+  type OrFilter,
+  type StructFilter,
+  formatPushedFilters,
+  reprPushedFilters,
+} from "./filter-pushdown/index.js";
+
+// State serializer
+export { arrowStateSerializer, EXCHANGE_STATE_SCHEMA, serializeUserState, deserializeUserState } from "./protocol/state-serializer.js";
+
+// Protocol assembly (for embedding the worker dispatcher in a custom HTTP server).
+export { buildVgiProtocol, type ProtocolConfig } from "./protocol/dispatch.js";
+
+// Wire schemas — needed by workers that synthesize TableInfo.bind_result /
+// TableInfo.scan_function bytes to short-circuit per-scan RPCs.
+export { BindResultSchema, ScanFunctionResultSchema } from "./generated/vgi-protocol-schemas.js";
+
+// Attach-option specs (for catalogs that advertise typed ATTACH options).
+export { type AttachOptionSpec, serializeAttachOptionSpec, serializeAttachOptionSpecs } from "./catalog/attach-option.js";
+
+// Column statistics (for inlining on TableInfo.column_statistics).
+export { type ColumnStatistics, serializeColumnStatistics } from "./util/statistics.js";
+
+// Byte utilities
+export { toUint8Array } from "./util/bytes.js";
+
+// Arrow utilities
+export {
+  iterRows,
+  batchFromRows,
+  batchFromColumns,
+  emptyBatch,
+  filterBatch,
+  projectSchema,
+  projectBatch,
+  batchToScalarDict,
+  batchToSecretDict,
+  safeNumber,
+} from "./util/arrow/index.js";
+
+export {
+  type SecretFields,
+  type SecretsDict,
+  secretType,
+  secretsOfType,
+  secretForScope,
+  secretForScopeOfType,
+} from "./secrets/helpers.js";
+
+export {
+  serializeSchema,
+  deserializeSchema,
+  serializeBatch,
+  deserializeBatch,
+} from "./util/arrow/index.js";
+
+// Arrow type system (phase 3): typed factories, precise descriptors, the
+// rich/raw value mapping, the codec registry, and branded raw scalar types
+// with their validating constructors. This is the statically-typed author API.
+// NOTE: the arrow factory names `int`, `int32`, `float32`, `bool` are NOT
+// re-exported here because the package root already exports vgi-rpc argument
+// builders of the same names. Authors needing those specific arrow factories
+// (and the full typed factory set) import them from the arrow facade module
+// (`@query-farm/vgi` -> "./src/arrow/index.js"). The non-colliding and
+// unit-precise factories below cover the common phase-3 typed/raw-mode cases.
+export {
+  // typed type factories (non-colliding subset)
+  schema, field,
+  nullType,
+  int8, int16, int64,
+  uint8, uint16, uint32, uint64,
+  float16, 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,
+  // codec registry
+  codecFor,
+  // branded raw constructors / unwrappers
+  asDate32, asDate64Ms,
+  asTime32S, asTime32Ms, asTime64Us, asTime64Ns,
+  asTimestampSeconds, asTimestampMillis, asTimestampMicros, asTimestampNanos,
+  asDurationSeconds, asDurationMillis, asDurationMicros, asDurationNanos,
+  asUnscaledDecimal, asInt64, asUint64,
+  fromBranded, fromBrandedNumber, fromBrandedBigInt,
+  // backend-agnostic predicates + ids
+  TypeId,
+  isNull, isInt, isFloat, isBinary, isUtf8, isBool, isDecimal, isDate,
+  isTime, isTimestamp, isInterval, isList, isStruct, isUnion,
+  isFixedSizeBinary, isFixedSizeList, isMap, isDuration, isDictionary, isBatch,
+  readCanonicalValue, columnFromArray, decodeDictValue, backend,
+} from "./arrow/index.js";
+
+export type {
+  // backend-agnostic Arrow types
+  VgiTypeId, VgiDataType, VgiField, VgiSchema, VgiColumn, VgiColumnData,
+  VgiBatch, VgiBackendInfo, TaggedUnion,
+  // precise nominal descriptors
+  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,
+  // rich/raw mapping
+  RichValue, RawValue, ValueFor, Repr,
+  // codec
+  Codec,
+  // branded scalar aliases
+  Branded,
+  Date32, Date64Ms,
+  Time32S, Time32Ms, Time64Us, Time64Ns,
+  TimestampSeconds, TimestampMillis, TimestampMicros, TimestampNanos,
+  DurationSeconds, DurationMillis, DurationMicros, DurationNanos,
+  UnscaledDecimal, Int64Raw, Uint64Raw,
+} from "./arrow/index.js";
+
+// Typed scalar compute helper types (phase 3).
+export type { ScalarComputeRow, ScalarOutputValue, ScalarComputeResult } from "./functions/scalar.js";
+
+// Storage
+export {
+  type FunctionStorage,
+  FunctionStorageSqlite,
+  BoundStorage,
+  UnknownInvocationError,
+  resolveStorageFromEnv,
+  setStorage,
+  storage as functionStorage,
+} from "./functions/storage.js";
+export { FunctionStorageCfDo, type FetchLike } from "./functions/storage-cf-do.js";
+
+// Client
+export { VgiClient, VgiClientError } from "./client/client.js";
+export type {
+  VgiClientOptions,
+  TableFunctionOptions,
+  ScalarFunctionOptions,
+  TableInOutFunctionOptions,
+  OnCreateConflict,
+  CatalogFunctionType as ClientCatalogFunctionType,
+  CatalogAttachOptions,
+  AttachOptionValue,
+} from "./client/types.js";
+
+// Re-export from vgi-rpc for convenience
+export { str, bytes, int, int32, float, float32, bool, toSchema, OutputCollector, AuthContext } from "@query-farm/vgi-rpc";
+export { subprocessConnect, httpConnect, tcpConnect } from "@query-farm/vgi-rpc";
+export type { RpcClient, StreamSession, LogMessage } from "@query-farm/vgi-rpc";

package/src/index.ts

@@ -0,0 +1,11 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// VGI TypeScript - Public API (node/bun barrel)
+//
+// The runtime-agnostic core plus the node-only `Worker` (stdio + AF_UNIX
+// launcher transport). Cloudflare Worker / browser code imports from
+// `./index.core.js` (via worker-cf-entry.ts) instead, which omits `Worker` so
+// the launcher's `serveUnix` (node:net) never enters the bundle.
+export * from "./index.core.js";
+
+// Worker (node/bun only — stdio + AF_UNIX launcher transport)
+export { Worker, type WorkerConfig } from "./worker.js";

package/src/metadata/resolve.ts

@@ -0,0 +1,109 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// Extract metadata from VgiFunction configs.
+
+import {
+  FunctionStability,
+  NullHandling,
+  OrderPreservation,
+  OrderDependence,
+  DistinctDependence,
+  DEFAULT_MAX_WORKERS,
+} from "../types.js";
+import type { VgiFunction } from "../functions/types.js";
+import type { ArgumentSpec } from "../arguments/argument-spec.js";
+import {
+  CatalogFunctionType,
+  type ResolvedMetadata,
+  type ParameterInfo,
+  type FunctionExample,
+} from "./types.js";
+import { type VgiDataType, TypeId, isUtf8, isBinary, isBool, isNull, isFloat, isInt } from "../arrow/index.js";
+function arrowTypeToName(type: VgiDataType): string | null {
+  if (isNull(type)) return null;
+  if (isUtf8(type)) return "VARCHAR";
+  if (isBinary(type)) return "BLOB";
+  if (isBool(type)) return "BOOLEAN";
+  if (isInt(type)) {
+    const bw = (type as any).bitWidth ?? 32;
+    return bw === 64 ? "BIGINT" : "INTEGER";
+  }
+  if (isFloat(type)) {
+    // arrow-js: Float.precision === 0/1/2 (HALF/SINGLE/DOUBLE).
+    // flechette: same precision values.
+    const precision = (type as any).precision ?? 2;
+    return precision === 1 ? "FLOAT" : "DOUBLE";
+  }
+  return String((type as any).toString?.() ?? type.typeId);
+}
+
+function specToParameterInfo(spec: ArgumentSpec): ParameterInfo {
+  return {
+    name: spec.name,
+    position: typeof spec.position === "number" ? spec.position : null,
+    positionName: typeof spec.position === "string" ? spec.position : null,
+    typeName: arrowTypeToName(spec.arrowType),
+    description: "",
+    required: true,
+    default: null,
+    constraints: null,
+    isTableInput: spec.isTableInput ?? false,
+    isVarargs: spec.isVarargs ?? false,
+    isConst: spec.isConst ?? false,
+  };
+}
+
+export function resolveMetadata(func: VgiFunction): ResolvedMetadata {
+  const meta = func.meta;
+
+  let functionType: CatalogFunctionType;
+  switch (func.kind) {
+    case "scalar":
+      functionType = CatalogFunctionType.SCALAR;
+      break;
+    case "table":
+    case "table_in_out":
+      functionType = CatalogFunctionType.TABLE;
+      break;
+    case "table_buffering" as any:
+      functionType = CatalogFunctionType.TABLE_BUFFERING;
+      break;
+    case "aggregate" as any:
+      functionType = CatalogFunctionType.AGGREGATE;
+      break;
+    default:
+      functionType = CatalogFunctionType.TABLE;
+  }
+
+  const parameters: ParameterInfo[] = func.argumentSpecs.map(specToParameterInfo);
+
+  const examples: FunctionExample[] = (meta.examples ?? []).map((e) => ({
+    sql: e.sql,
+    description: e.description,
+    expectedOutput: e.expectedOutput ?? null,
+  }));
+
+  const maxWorkers = meta.maxWorkers ?? DEFAULT_MAX_WORKERS;
+
+  return {
+    name: meta.name,
+    className: meta.name, // In TS, no class name distinction
+    functionType,
+    description: meta.description ?? "",
+    examples,
+    categories: meta.categories ?? [],
+    tags: meta.tags ?? {},
+    parameters,
+    stability: meta.stability ?? FunctionStability.CONSISTENT,
+    nullHandling: meta.nullHandling ?? NullHandling.DEFAULT,
+    requiredSettings: meta.requiredSettings ?? [],
+    requiredSecrets: meta.requiredSecrets ?? [],
+    projectionPushdown: meta.projectionPushdown ?? false,
+    filterPushdown: meta.filterPushdown ?? false,
+    samplingPushdown: meta.samplingPushdown ?? false,
+    supportedExpressionFilters: meta.supportedExpressionFilters ?? [],
+    preservesOrder: meta.preservesOrder ?? OrderPreservation.NO_ORDER_GUARANTEE,
+    maxWorkers: maxWorkers === DEFAULT_MAX_WORKERS ? null : maxWorkers,
+    orderDependent: meta.orderDependent ?? OrderDependence.NOT_ORDER_DEPENDENT,
+    distinctDependent: meta.distinctDependent ?? DistinctDependence.NOT_DISTINCT_DEPENDENT,
+  };
+}

package/src/metadata/serialize.ts

@@ -0,0 +1,242 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// Metadata -> Arrow batch serialization.
+// Must produce batches matching Python's _METADATA_SCHEMA exactly.
+
+import {
+  type VgiBatch,
+  schema as makeSchema,
+  field,
+  utf8,
+  int32,
+  bool,
+  list,
+  struct as makeStruct,
+  map as makeMap,
+  batchFromColumns,
+  emptyBatch,
+} from "../arrow/index.js";
+import type { ResolvedMetadata, ParameterInfo, FunctionExample } from "./types.js";
+
+// ============================================================================
+// Schema definitions matching Python's _METADATA_SCHEMA exactly
+// ============================================================================
+
+const EXAMPLE_STRUCT = makeStruct([
+  field("sql", utf8(), false),
+  field("description", utf8(), false),
+  field("expected_output", utf8(), true),
+]);
+
+const PARAMETER_STRUCT = makeStruct([
+  field("name", utf8(), false),
+  field("position", int32(), true),
+  field("position_name", utf8(), true),
+  field("type_name", utf8(), true),
+  field("description", utf8(), false),
+  field("required", bool(), false),
+  field("default", utf8(), true),
+  field("constraints", utf8(), true),
+  field("is_table_input", bool(), false),
+  field("is_varargs", bool(), false),
+  field("is_const", bool(), false),
+]);
+
+const METADATA_SCHEMA = makeSchema([
+  field("name", utf8(), false),
+  field("class_name", utf8(), false),
+  field("function_type", utf8(), false),
+  field("description", utf8(), false),
+  field("examples", list(field("item", EXAMPLE_STRUCT, true)), false),
+  field("categories", list(field("item", utf8(), true)), false),
+  field("tags", makeMap(field("key", utf8(), false), field("value", utf8(), true), false), false),
+  field("parameters", list(field("item", PARAMETER_STRUCT, true)), false),
+  field("stability", utf8(), false),
+  field("null_handling", utf8(), false),
+  field("required_settings", list(field("item", utf8(), true)), false),
+  field("required_secrets", list(field("item", utf8(), true)), false),
+  field("projection_pushdown", bool(), false),
+  field("filter_pushdown", bool(), false),
+  field("preserves_order", utf8(), false),
+  field("max_workers", int32(), true),
+  field("order_dependent", utf8(), false),
+  field("distinct_dependent", utf8(), false),
+]);
+
+export { METADATA_SCHEMA };
+
+// ============================================================================
+// Serialization
+// ============================================================================
+
+function metadataToRow(m: ResolvedMetadata): Record<string, any> {
+  return {
+    name: m.name,
+    class_name: m.className,
+    function_type: m.functionType,
+    description: m.description,
+    examples: m.examples.map((e) => ({
+      sql: e.sql,
+      description: e.description,
+      expected_output: e.expectedOutput,
+    })),
+    categories: m.categories,
+    tags: Object.entries(m.tags).map(([k, v]) => [k, v]),
+    parameters: m.parameters.map((p) => ({
+      name: p.name,
+      position: p.position,
+      position_name: p.positionName,
+      type_name: p.typeName,
+      description: p.description,
+      required: p.required,
+      default: p.default,
+      constraints: p.constraints,
+      is_table_input: p.isTableInput,
+      is_varargs: p.isVarargs,
+      is_const: p.isConst,
+    })),
+    stability: m.stability,
+    null_handling: m.nullHandling,
+    required_settings: m.requiredSettings,
+    required_secrets: m.requiredSecrets,
+    projection_pushdown: m.projectionPushdown,
+    filter_pushdown: m.filterPushdown,
+    sampling_pushdown: m.samplingPushdown,
+    supported_expression_filters: m.supportedExpressionFilters,
+    preserves_order: m.preservesOrder,
+    max_workers: m.maxWorkers,
+    order_dependent: m.orderDependent,
+    distinct_dependent: m.distinctDependent,
+  };
+}
+
+/**
+ * Serialize multiple ResolvedMetadata to a single Arrow RecordBatch.
+ */
+export function metadatasToArrow(metadatas: ResolvedMetadata[]): VgiBatch {
+  if (metadatas.length === 0) {
+    return emptyBatch(METADATA_SCHEMA);
+  }
+
+  const rows = metadatas.map(metadataToRow);
+
+  // Pivot rows -> columns keyed by field name; the facade handles complex
+  // type construction (List<Struct>, Map, etc.) uniformly.
+  const columns: Record<string, any[]> = {};
+  for (const f of METADATA_SCHEMA.fields) {
+    columns[f.name] = rows.map((r) => r[f.name]);
+  }
+
+  return batchFromColumns(columns, METADATA_SCHEMA);
+}
+
+/**
+ * Deserialize Arrow RecordBatch to ResolvedMetadata array.
+ */
+export function arrowToMetadatas(batch: VgiBatch): ResolvedMetadata[] {
+  const results: ResolvedMetadata[] = [];
+
+  for (let i = 0; i < batch.numRows; i++) {
+    const get = (name: string) => {
+      const col = batch.getChild(name);
+      return col ? col.get(i) : null;
+    };
+
+    // Parse examples
+    const rawExamples = get("examples") as any ?? [];
+    const examples: FunctionExample[] = [];
+    if (rawExamples && typeof rawExamples[Symbol.iterator] === "function") {
+      for (const e of rawExamples) {
+        if (e) {
+          examples.push({
+            sql: e.sql ?? "",
+            description: e.description ?? "",
+            expectedOutput: e.expected_output ?? null,
+          });
+        }
+      }
+    }
+
+    // Parse parameters
+    const rawParams = get("parameters") as any ?? [];
+    const parameters: ParameterInfo[] = [];
+    if (rawParams && typeof rawParams[Symbol.iterator] === "function") {
+      for (const p of rawParams) {
+        if (p) {
+          parameters.push({
+            name: p.name ?? "",
+            position: p.position ?? null,
+            positionName: p.position_name ?? null,
+            typeName: p.type_name ?? null,
+            description: p.description ?? "",
+            required: p.required ?? true,
+            default: p.default ?? null,
+            constraints: p.constraints ?? null,
+            isTableInput: p.is_table_input ?? false,
+            isVarargs: p.is_varargs ?? false,
+            isConst: p.is_const ?? false,
+          });
+        }
+      }
+    }
+
+    // Parse categories
+    const rawCategories = get("categories") as any ?? [];
+    const categories: string[] = rawCategories
+      ? [...rawCategories].filter((c: any) => c != null)
+      : [];
+
+    // Parse tags (Map). arrow-js MapRow is iterable of {key,value}; flechette
+    // returns [[k,v],...] arrays. Handle both.
+    const rawTags = get("tags") as any;
+    const tags: Record<string, string> = {};
+    if (rawTags) {
+      if (typeof rawTags[Symbol.iterator] === "function") {
+        for (const entry of rawTags) {
+          if (Array.isArray(entry)) {
+            tags[String(entry[0])] = String(entry[1] ?? "");
+          } else if (entry && entry.key != null) {
+            tags[String(entry.key)] = String(entry.value ?? "");
+          }
+        }
+      }
+    }
+
+    const rawRequiredSettings = get("required_settings") as any ?? [];
+    const requiredSettings: string[] = rawRequiredSettings
+      ? [...rawRequiredSettings].filter((s: any) => s != null)
+      : [];
+
+    const rawRequiredSecrets = get("required_secrets") as any ?? [];
+    const requiredSecrets: string[] = rawRequiredSecrets
+      ? [...rawRequiredSecrets].filter((s: any) => s != null)
+      : [];
+
+    results.push({
+      name: (get("name") as string) ?? "",
+      className: (get("class_name") as string) ?? "",
+      functionType: (get("function_type") as any) ?? "TABLE",
+      description: (get("description") as string) ?? "",
+      examples,
+      categories,
+      tags,
+      parameters,
+      stability: (get("stability") as any) ?? "CONSISTENT",
+      nullHandling: (get("null_handling") as any) ?? "DEFAULT",
+      requiredSettings,
+      requiredSecrets,
+      projectionPushdown: (get("projection_pushdown") as boolean) ?? false,
+      filterPushdown: (get("filter_pushdown") as boolean) ?? false,
+      samplingPushdown: (get("sampling_pushdown") as boolean) ?? false,
+      supportedExpressionFilters: (() => {
+        const raw = get("supported_expression_filters") as any ?? [];
+        return raw ? [...raw].filter((s: any) => s != null).map(String) : [];
+      })(),
+      preservesOrder: (get("preserves_order") as any) ?? "NO_ORDER_GUARANTEE",
+      maxWorkers: (get("max_workers") as number | null) ?? null,
+      orderDependent: (get("order_dependent") as any) ?? "NOT_ORDER_DEPENDENT",
+      distinctDependent: (get("distinct_dependent") as any) ?? "NOT_DISTINCT_DEPENDENT",
+    });
+  }
+
+  return results;
+}

package/src/metadata/types.ts

@@ -0,0 +1,60 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// Metadata types for function introspection and DuckDB registration.
+
+import {
+  FunctionStability,
+  NullHandling,
+  OrderPreservation,
+  OrderDependence,
+  DistinctDependence,
+} from "../types.js";
+
+export enum CatalogFunctionType {
+  SCALAR = "SCALAR",
+  TABLE = "TABLE",
+  TABLE_BUFFERING = "TABLE_BUFFERING",
+  AGGREGATE = "AGGREGATE",
+}
+
+export interface ParameterInfo {
+  name: string;
+  position: number | null;
+  positionName: string | null;
+  typeName: string | null;
+  description: string;
+  required: boolean;
+  default: string | null;
+  constraints: string | null;
+  isTableInput: boolean;
+  isVarargs: boolean;
+  isConst: boolean;
+}
+
+export interface FunctionExample {
+  sql: string;
+  description: string;
+  expectedOutput: string | null;
+}
+
+export interface ResolvedMetadata {
+  name: string;
+  className: string;
+  functionType: CatalogFunctionType;
+  description: string;
+  examples: FunctionExample[];
+  categories: string[];
+  tags: Record<string, string>;
+  parameters: ParameterInfo[];
+  stability: FunctionStability;
+  nullHandling: NullHandling;
+  requiredSettings: string[];
+  requiredSecrets: string[];
+  projectionPushdown: boolean;
+  filterPushdown: boolean;
+  samplingPushdown: boolean;
+  supportedExpressionFilters: string[];
+  preservesOrder: OrderPreservation;
+  maxWorkers: number | null;
+  orderDependent: OrderDependence;
+  distinctDependent: DistinctDependence;
+}