@query-farm/vgi 0.42.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.42.0",
+  "version": "0.44.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)",
@@ -91,12 +91,12 @@
   },
   "peerDependencies": {
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.28.0"
+    "@query-farm/vgi-rpc": "^0.29.0"
   },
   "devDependencies": {
     "@duckdb/node-api": "^1.5.5-r.4",
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.28.0",
+    "@query-farm/vgi-rpc": "^0.29.0",
     "@types/bun": "latest",
     "typescript": "^7.0.2"
   },

package/src/attach-ticket.ts

@@ -5,7 +5,7 @@
 // that user (`vgi.attach_tickets.v1`).
 //
 // A ticket is the *what* half of an unattended session; a sealed grant
-// (`vgi_rpc.Identity.v1` `issue_grant`) is the *who*. While the user is
+// (`vgi_rpc.Identity.v2` `issue_grant`) is the *who*. While the user is
 // attached and logged in, the client asks the worker to seal the options it
 // attached with -- secret ones included -- into a ticket only this worker can
 // open. Later any runner holding the user's grant attaches with the single
@@ -35,7 +35,7 @@ import {
   errorInfo,
   preconditionFailure,
 } from "@query-farm/vgi-rpc";
-import { field, float64, schema, utf8, binary, int64, batchFromColumns, serializeBatch } from "./arrow/index.js";
+import { field, schema, utf8, binary, int64, timestamp, TimeUnit, batchFromColumns, serializeBatch } from "./arrow/index.js";
 import { deserializeBatch } from "./util/arrow/index.js";
 import { openBytes, OpaqueDataRejectedError, sealBytes } from "./crypto.js";
 import type { CatalogInterface } from "./catalog/interface.js";
@@ -51,8 +51,9 @@ export const ATTACH_TICKET_PREFIX = "vgia1.";
 export const ATTACH_TICKET_OPTION = RESERVED_ATTACH_OPTION;
 /** Wire name of the protocol hosting `seal_attach`. */
 export const ATTACH_TICKETS_PROTOCOL_NAME = "vgi.attach_tickets.v1";
-/** Its declared version. */
-export const ATTACH_TICKETS_PROTOCOL_VERSION = "1.0.0";
+/** Its declared version. 2.0.0 made `AttachTicket.expires_at` a nullable
+ *  `timestamp[us, UTC]` (1.0.0: float64 unix seconds, `+inf` = no expiry). */
+export const ATTACH_TICKETS_PROTOCOL_VERSION = "2.0.0";
 /** The envelope's version byte, fixed by this format. */
 export const TICKET_ENVELOPE_VERSION = 0x01;
 /** Largest options record (serialized Arrow IPC bytes) a ticket may carry. */
@@ -455,12 +456,42 @@ export const SEAL_ATTACH_REQUEST_SCHEMA = schema([
   field("ttl_seconds", int64(), false),
 ]);
 
-/** `AttachTicket`, field for field with vgi-python. */
+/**
+ * `AttachTicket`, field for field with vgi-python: `expires_at` is the UTC
+ * instant after which the worker refuses the ticket, null when the worker sets
+ * no maximum lifetime.
+ */
 export const ATTACH_TICKET_SCHEMA = schema([
   field("ticket", utf8(), false),
-  field("expires_at", float64(), false),
+  field("expires_at", timestamp(TimeUnit.MICROSECOND, "UTC"), true),
 ]);
 
+/** A sealed ticket, as `seal_attach` returns it. */
+export interface AttachTicket {
+  /** `vgia1.` text. Not a credential, but never logged. */
+  ticket: string;
+  /** When the worker stops honouring it; `null` = no expiry. */
+  expires_at: Date | null;
+}
+
+/** `expires_at` as the wire's microsecond count (the codec's raw unit). */
+function expiresAtMicros(value: Date | null): bigint | null {
+  if (value === null) return null;
+  const ms = value.getTime();
+  if (!Number.isFinite(ms)) throw new TypeError("AttachTicket.expires_at must be a valid Date or null");
+  return BigInt(ms) * 1000n;
+}
+
+/** Encode an {@link AttachTicket} as a single-row Arrow IPC stream. */
+export function encodeAttachTicket(ticket: AttachTicket): Uint8Array {
+  return serializeBatch(
+    batchFromColumns(
+      { ticket: [ticket.ticket], expires_at: [expiresAtMicros(ticket.expires_at)] },
+      ATTACH_TICKET_SCHEMA,
+    ),
+  );
+}
+
 /**
  * The ticket lifetime ceiling: the worker's grant maximum, or `null`.
  *
@@ -517,7 +548,7 @@ export async function sealAttach(
   config: AttachTicketsConfig,
   request: Record<string, unknown>,
   auth: AuthContext | undefined,
-): Promise<{ ticket: string; expires_at: number }> {
+): Promise<AttachTicket> {
   const principal = callerPrincipal(auth);
   if (principal === null) throw new SealAttachDeniedError("an anonymous caller cannot seal an attach ticket");
 
@@ -582,7 +613,8 @@ export async function sealAttach(
   } catch (e) {
     throw new AttachTicketRequestError("seal_attach request is invalid", [["request", (e as Error).message]]);
   }
-  return { ticket: token, expires_at: expiresAt === 0 ? Number.POSITIVE_INFINITY : expiresAt };
+  // The sealed claim keeps seconds with 0 = none; the reply is an instant or null.
+  return { ticket: token, expires_at: expiresAt === 0 ? null : new Date(expiresAt * 1000) };
 }
 
 /**
@@ -600,11 +632,7 @@ export function buildAttachTicketsProtocol(config: AttachTicketsConfig): Protoco
     handler: async (params: Record<string, unknown>, ctx: unknown) => {
       const request = unwrapRequest(params.request);
       const sealed = await sealAttach(config, request, (ctx as CallContext | undefined)?.auth);
-      const batch = batchFromColumns(
-        { ticket: [sealed.ticket], expires_at: [sealed.expires_at] },
-        ATTACH_TICKET_SCHEMA,
-      );
-      return { result: serializeBatch(batch) };
+      return { result: encodeAttachTicket(sealed) };
     },
   });
   return p;

package/src/catalog/composite.ts

@@ -25,6 +25,7 @@ import type {
 } from "./interface.js";
 import { CatalogInterface } from "./interface.js";
 import { OpaqueDataRejectedError } from "../crypto.js";
+import { VgiError } from "../errors.js";
 
 function bufferEquals(a: AttachOpaqueData, b: AttachOpaqueData): boolean {
   if (a.length !== b.length) return false;
@@ -109,7 +110,7 @@ export class CompositeCatalogInterface extends CatalogInterface {
         return result;
       }
     }
-    throw new Error(`No worker handles catalog '${name}'`);
+    throw new VgiError(`No worker handles catalog '${name}'`, "NOT_FOUND");
   }
 
   async detach(attachOpaqueData: AttachOpaqueData): Promise<void> {

package/src/catalog/interface.ts

@@ -168,6 +168,7 @@ export const encodeAttachCatalogInfo = (v: AttachCatalogInfo): Uint8Array =>
 // ============================================================================
 
 import { deserializeBatch, serializeBatch, batchFromColumns } from "../util/arrow/index.js";
+import { conformColumns } from "../codec/conform.js";
 import { schema as schema_, field as field_, type VgiDataType, type VgiField } from "../arrow/index.js";
 import { toUint8Array } from "../util/bytes.js";
 import { ScanBranchSchema, ScanFunctionResultSchema } from "../generated/vgi-protocol-schemas.js";
@@ -221,12 +222,12 @@ export function encodeScanFunctionResult(
 ): Uint8Array {
   return serializeBatch(
     batchFromColumns(
-      {
+      conformColumns(ScanFunctionResultSchema as any, {
         function_name: [functionName],
         arguments: [argumentsBytes],
         required_extensions: [requiredExtensions],
         schema_path: [schemaPath],
-      },
+      }),
       ScanFunctionResultSchema as any,
     ),
   );
@@ -345,7 +346,7 @@ function encodeScanBranch(cols: {
 }): Uint8Array {
   return serializeBatch(
     batchFromColumns(
-      {
+      conformColumns(ScanBranchSchema as any, {
         function_name: [cols.function_name],
         arguments: [cols.arguments],
         branch_filter: [cols.branch_filter ?? null],
@@ -357,7 +358,7 @@ function encodeScanBranch(cols: {
         format_locations: [cols.format_locations ?? null],
         format_options: [cols.format_options ?? null],
         schema_path: [cols.schema_path ?? null],
-      },
+      }),
       ScanBranchSchema as any,
     ),
   );

package/src/catalog/read-only.ts

@@ -32,6 +32,8 @@ import { FunctionStability, NullHandling, OrderPreservation, DEFAULT_MAX_WORKERS
 import { Arguments } from "../arguments/arguments.js";
 import { normalizeSchemaPath, schemaPathDisplay, schemaPathsEqual } from "../schema-path.js";
 import { ForeignKeyInfoSchema } from "../generated/vgi-protocol-schemas.js";
+import { conformColumns } from "../codec/conform.js";
+import { VgiError } from "../errors.js";
 import { encodeFunctionInfoOnce, freezeCatalogItem } from "./item-encoding.js";
 
 /**
@@ -178,7 +180,7 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
     implementationVersion?: string | null,
   ): CatalogAttachResult | Promise<CatalogAttachResult> {
     if (!this.catalogs().includes(name)) {
-      throw new Error(`No worker handles catalog '${name}'`);
+      throw new VgiError(`No worker handles catalog '${name}'`, "NOT_FOUND");
     }
     // Refuse an attach that omits a declared-required option, so the caller
     // gets the option name rather than a catalog that looks mysteriously
@@ -820,11 +822,11 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
     // Find the table descriptor
     const schema = this._descriptor.schemas.find((s) => schemaPathsEqual(schemaDescriptorPath(s), schemaPath));
     if (!schema || !schema.tables) {
-      throw new Error(`Table '${name}' not found in schema ${schemaPathDisplay(schemaPath)}`);
+      throw new VgiError(`Table '${name}' not found in schema ${schemaPathDisplay(schemaPath)}`, "NOT_FOUND");
     }
     const table = schema.tables.find((t) => t.name === name);
     if (!table) {
-      throw new Error(`Table '${name}' not found in schema ${schemaPathDisplay(schemaPath)}`);
+      throw new VgiError(`Table '${name}' not found in schema ${schemaPathDisplay(schemaPath)}`, "NOT_FOUND");
     }
 
     // Reject AT clause on tables that don't support time travel
@@ -958,12 +960,12 @@ function serializeForeignKeys(fks?: ForeignKeyDef[], schemaPath?: string[]): Uin
   return fks.map((fk) =>
     serializeBatch(
       batchFromColumns(
-        {
+        conformColumns(ForeignKeyInfoSchema, {
           fk_columns: [fk.columns],
           pk_columns: [fk.referencedColumns],
           referenced_table: [fk.referencedTable],
           referenced_schema_path: [fk.referencedSchemaPath ?? schemaPath ?? ["main"]],
-        },
+        }),
         ForeignKeyInfoSchema
       )
     )
@@ -1145,7 +1147,7 @@ function serializeArgsBatch(args: Arguments, argSpecSchema: VgiSchema): Uint8Arr
 
 function validateAtParams(atUnit?: string, atValue?: string): void {
   if (Boolean(atUnit) !== Boolean(atValue)) {
-    throw new Error("at_unit and at_value must both be provided or both be absent");
+    throw new VgiError("at_unit and at_value must both be provided or both be absent", "INVALID_ARGUMENT");
   }
 }
 

package/src/client/client.ts

@@ -77,6 +77,14 @@ import type {
   LoadCatalogOptions,
 } from "./types.js";
 
+/**
+ * `on_conflict` as it goes on the wire: the vgi-python `OnConflict` member
+ * NAME (`ERROR` / `IGNORE` / `REPLACE`), not the lower-case API spelling.
+ */
+function onConflictName(onConflict: OnCreateConflict): string {
+  return String(onConflict).toUpperCase();
+}
+
 /**
  * High-level client for calling VGI worker functions and catalog API.
  *
@@ -906,7 +914,7 @@ export class VgiClient {
     }
     await this.rpc.call("catalog_create", {
       name,
-      on_conflict: onConflict,
+      on_conflict: onConflictName(onConflict),
       options: wireOptions,
     });
   }
@@ -1013,7 +1021,7 @@ export class VgiClient {
     await this.rpc.call("catalog_schema_create", {
       attach_opaque_data: attachOpaqueData,
       path: normalizeSchemaPath(path),
-      on_conflict: opts?.onConflict ?? "error",
+      on_conflict: onConflictName(opts?.onConflict ?? "error"),
       comment: opts?.comment ?? null,
       tags: tagsMap,
       transaction_opaque_data: opts?.transactionOpaqueData ?? null,
@@ -1139,7 +1147,7 @@ export class VgiClient {
       schema_path: normalizeSchemaPath(schemaPath),
       name,
       columns,
-      on_conflict: onConflict,
+      on_conflict: onConflictName(onConflict),
       not_null_constraints: notNullConstraints ?? null,
       unique_constraints: uniqueConstraints ?? null,
       check_constraints: checkConstraints ?? null,
@@ -1430,7 +1438,7 @@ export class VgiClient {
       schema_path: normalizeSchemaPath(schemaPath),
       name,
       definition,
-      on_conflict: onConflict,
+      on_conflict: onConflictName(onConflict),
       transaction_opaque_data: transactionOpaqueData ?? null,
     });
   }
@@ -1554,7 +1562,7 @@ export class VgiClient {
         macro_type: [macroType],
         parameters: [parameters],
         definition: [definition],
-        on_conflict: [onConflict],
+        on_conflict: [onConflictName(onConflict)],
         parameter_default_values: [parameterDefaultValues ?? null],
         arguments_schema: [argumentsSchema ?? null],
         transaction_opaque_data: [transactionOpaqueData ?? null],

package/src/codec/asd.ts

@@ -31,16 +31,19 @@ import {
   serializeBatch,
   deserializeBatch,
 } from "../arrow/index.js";
+import { conformRecord } from "./conform.js";
 
 /**
  * Encode a typed object as a single-row Arrow IPC stream using `schema`.
- * Matches Python's `ArrowSerializableDataclass.serialize_to_bytes()`.
+ * Matches Python's `ArrowSerializableDataclass.serialize_to_bytes()`, including
+ * its container rules: a non-nullable list/map left out or null is written as
+ * empty, and list items / map values are never null (see `conformRecord`).
  */
 export function encodeASD(
   schema: VgiSchema,
   obj: Record<string, any>,
 ): Uint8Array {
-  return serializeBatch(batchFromRows([sortMapsForSchema(schema, obj)], schema));
+  return serializeBatch(batchFromRows([sortMapsForSchema(schema, conformRecord(schema, obj))], schema));
 }
 
 // --------------------------------------------------------------------------- //

package/src/codec/conform.ts

@@ -0,0 +1,193 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// SPDX-License-Identifier: LicenseRef-QueryFarm-Source-Available-1.0
+
+/**
+ * Wire conformance for protocol records.
+ *
+ * vgi-python is the reference for the wire shape, and two of its rules are not
+ * expressed by a record's Arrow schema nullability flags alone:
+ *
+ *  1. A **non-nullable list or map column is never null.** Python's dataclass
+ *     defaults a `list[...]` / `dict[...]` field to an empty container, so an
+ *     "absent" list goes out as `[]`. A JS caller that leaves the field out (or
+ *     passes `null`) would otherwise put a null in a column the schema calls
+ *     non-null — `CatalogInfo.releases`, `CatalogInfo.attach_option_specs`,
+ *     ... — which a strict client rejects as a protocol error.
+ *
+ *  2. **List items and map values are never null** unless the Python annotation
+ *     says so (`list[str | None]`). pyarrow marks every list item field nullable,
+ *     so the generated schemas carry `item: nullable=true` everywhere and cannot
+ *     tell the two apart. In the whole protocol exactly one field has optional
+ *     items — `argument_names` on `BindRequest` / `AggregateBindRequest` (a
+ *     positional argument has no name). Every other null item is a bug on the
+ *     sending side (e.g. `BindResponse.lookup_names` built from an unset secret
+ *     name, where Python sends `""`).
+ *
+ * `conformRecord` applies both rules to a record about to be encoded: a null or
+ * absent non-nullable list/map becomes empty, and a null list item / map value
+ * becomes its type's zero value (`""`, `0`, `false`, empty bytes, empty list),
+ * which is also what the C++ client reads such an item as. It never mutates its
+ * input (catalog items may be frozen and shared) and returns the input itself
+ * when nothing needed changing. Nullable columns, and scalars, pass through
+ * untouched: a null in a non-nullable scalar column has no safe default and is
+ * left for the caller to fix (see `wireViolations`).
+ */
+
+import {
+  type VgiSchema,
+  type VgiField,
+  type VgiDataType,
+  isBinary,
+  isBool,
+  isDictionary,
+  isFloat,
+  isInt,
+  isList,
+  isMap,
+  isStruct,
+  isUtf8,
+} from "../arrow/index.js";
+
+/**
+ * Top-level / struct-child field names whose list items may legitimately be
+ * null (the Python annotation is `list[X | None]`). Derived from vgi-python by
+ * walking every protocol dataclass's type hints; keep in sync if the protocol
+ * adds another optional-item list.
+ */
+export const OPTIONAL_ITEM_FIELDS: ReadonlySet<string> = new Set(["argument_names"]);
+
+function children(type: VgiDataType): VgiField[] {
+  return ((type as any).children ?? []) as VgiField[];
+}
+
+function mapValueType(type: VgiDataType): VgiDataType {
+  const entries = children(type)[0].type;
+  return children(entries)[1].type;
+}
+
+function mapPairs(raw: any): Array<[unknown, unknown]> {
+  if (Array.isArray(raw)) return raw.map((e: any) => (Array.isArray(e) ? [e[0], e[1]] : [e?.key, e?.value]));
+  if (raw instanceof Map) return Array.from(raw.entries());
+  if (typeof raw[Symbol.iterator] === "function") return Array.from(raw as Iterable<[unknown, unknown]>);
+  return Object.entries(raw);
+}
+
+/** The value a non-null slot of `type` takes when the sender left it null. */
+export function zeroValue(type: VgiDataType): unknown {
+  if (isUtf8(type) || isDictionary(type)) return "";
+  if (isBinary(type)) return new Uint8Array(0);
+  if (isBool(type)) return false;
+  if (isInt(type)) return (type as any).bitWidth === 64 ? 0n : 0;
+  if (isFloat(type)) return 0;
+  if (isList(type) || isMap(type)) return [];
+  if (isStruct(type)) {
+    const out: Record<string, unknown> = {};
+    for (const c of children(type)) out[c.name] = c.nullable ? null : conformValue(c.type, undefined, false, c.name);
+    return out;
+  }
+  return null;
+}
+
+/** Whether `type` contains a list or map anywhere (memoized per type object). */
+const HAS_CONTAINER = new WeakMap<object, boolean>();
+function hasContainer(type: VgiDataType): boolean {
+  const cached = HAS_CONTAINER.get(type as object);
+  if (cached !== undefined) return cached;
+  let has = isList(type) || isMap(type);
+  if (!has && isStruct(type)) has = children(type).some((c) => hasContainer(c.type));
+  HAS_CONTAINER.set(type as object, has);
+  return has;
+}
+
+/**
+ * Conform one value of `type`. `nullable` is the slot's nullability; `name` is
+ * the field name that owns the slot (list items inherit their list's name, for
+ * the `OPTIONAL_ITEM_FIELDS` lookup).
+ */
+function conformValue(type: VgiDataType, value: any, nullable: boolean, name: string): any {
+  if (value == null) {
+    if (nullable) return value ?? null;
+    if (isList(type) || isMap(type)) return [];
+    return value;
+  }
+  if (!hasContainer(type)) return value;
+
+  if (isList(type)) {
+    const itemType = children(type)[0].type;
+    const itemsNullable = OPTIONAL_ITEM_FIELDS.has(name);
+    const items = Array.isArray(value) ? value : Array.from(value as Iterable<unknown>);
+    let changed = !Array.isArray(value);
+    const out = items.map((item) => {
+      const next = item == null && !itemsNullable ? zeroValue(itemType) : conformValue(itemType, item, true, name);
+      if (next !== item) changed = true;
+      return next;
+    });
+    return changed ? out : value;
+  }
+
+  if (isMap(type)) {
+    const valueType = mapValueType(type);
+    const pairs = mapPairs(value);
+    let changed = false;
+    const out = pairs.map(([k, v]): [unknown, unknown] => {
+      const next = v == null ? zeroValue(valueType) : conformValue(valueType, v, true, name);
+      if (next !== v) changed = true;
+      return [k, next];
+    });
+    return changed ? out : value;
+  }
+
+  if (isStruct(type)) {
+    let out: Record<string, any> | null = null;
+    for (const c of children(type)) {
+      const v = value[c.name];
+      const next = conformValue(c.type, v, c.nullable, c.name);
+      if (next !== v) {
+        (out ??= { ...value })[c.name] = next;
+      }
+    }
+    return out ?? value;
+  }
+  return value;
+}
+
+/**
+ * `obj` conformed to `schema`'s wire rules (see the module comment). Returns
+ * `obj` itself when nothing changed.
+ */
+export function conformRecord<T extends Record<string, any>>(schema: VgiSchema, obj: T): T {
+  let out: Record<string, any> | null = null;
+  for (const f of schema.fields) {
+    const v = obj[f.name];
+    const next = conformValue(f.type, v, f.nullable, f.name);
+    if (next !== v) {
+      (out ??= { ...obj })[f.name] = next;
+    }
+  }
+  return (out ?? obj) as T;
+}
+
+/**
+ * Column-dict form of `conformRecord` for `batchFromColumns` callers: each
+ * value is a one-element array holding the row's value.
+ */
+export function conformColumns(
+  schema: VgiSchema,
+  columns: Record<string, unknown[]>,
+): Record<string, unknown[]> {
+  let out: Record<string, unknown[]> | null = null;
+  for (const f of schema.fields) {
+    const col = columns[f.name];
+    const rows = col ?? [undefined];
+    let changed = col === undefined;
+    const next = rows.map((v) => {
+      const c = conformValue(f.type, v, f.nullable, f.name);
+      if (c !== v) changed = true;
+      return c;
+    });
+    if (changed) {
+      (out ??= { ...columns })[f.name] = next;
+    }
+  }
+  return out ?? columns;
+}

package/src/errors.ts

@@ -1,13 +1,33 @@
 // Copyright 2025, 2026 Query Farm LLC - https://query.farm
 // VGI-specific error classes.
+//
+// Each class declares the canonical gRPC-style code vgi-rpc hoists onto the
+// EXCEPTION batch as `vgi_rpc.error_code` (vgi-rpc WIRE_PROTOCOL.md §8), so a
+// client — and DuckDB's `errors_as_json` — can tell "your input was wrong"
+// from a worker bug. The mapping is shared with every other VGI SDK:
+//
+//   INVALID_ARGUMENT     argument validation / type rejection
+//   NOT_FOUND            unknown function, table, schema, catalog
+//   ALREADY_EXISTS       creating something that is already there
+//   FAILED_PRECONDITION  writes against a read-only catalog
+//   UNIMPLEMENTED        an operation the SDK does not support
+//
+// Anything else (RowCountMismatchError, internal invariants) stays UNKNOWN.
+
+import type { ErrorCode } from "@query-farm/vgi-rpc";
 
 export class VgiError extends Error {
-  constructor(message: string) {
+  /** Canonical code hoisted as `vgi_rpc.error_code`; unset means `UNKNOWN`. */
+  readonly errorCode?: ErrorCode;
+
+  constructor(message: string, code?: ErrorCode) {
     super(message);
     this.name = "VgiError";
+    if (code !== undefined) this.errorCode = code;
   }
 }
 
+/** A worker bug (the function returned the wrong number of rows): UNKNOWN. */
 export class RowCountMismatchError extends VgiError {
   constructor(expected: number, actual: number) {
     super(
@@ -20,42 +40,42 @@ export class RowCountMismatchError extends VgiError {
 
 export class FunctionNotFoundError extends VgiError {
   constructor(name: string, available?: string[]) {
-    super(`Unknown function '${name}'`);
+    super(`Unknown function '${name}'`, "NOT_FOUND");
     this.name = "FunctionNotFoundError";
   }
 }
 
 export class CatalogReadOnlyError extends VgiError {
   constructor(operation: string) {
-    super(`catalog is read-only: ${operation} is not supported`);
+    super(`catalog is read-only: ${operation} is not supported`, "FAILED_PRECONDITION");
     this.name = "CatalogReadOnlyError";
   }
 }
 
 export class CatalogNotFoundError extends VgiError {
   constructor(entity: string, name: string) {
-    super(`${entity} '${name}' not found`);
+    super(`${entity} '${name}' not found`, "NOT_FOUND");
     this.name = "CatalogNotFoundError";
   }
 }
 
 export class CatalogAlreadyExistsError extends VgiError {
   constructor(entity: string, name: string) {
-    super(`${entity} '${name}' already exists`);
+    super(`${entity} '${name}' already exists`, "ALREADY_EXISTS");
     this.name = "CatalogAlreadyExistsError";
   }
 }
 
 export class ArgumentValidationError extends VgiError {
   constructor(message: string) {
-    super(message);
+    super(message, "INVALID_ARGUMENT");
     this.name = "ArgumentValidationError";
   }
 }
 
 export class NoCatalogError extends VgiError {
   constructor() {
-    super("No catalog is configured for this worker");
+    super("No catalog is configured for this worker", "UNIMPLEMENTED");
     this.name = "NoCatalogError";
   }
 }

package/src/functions/registry.ts

@@ -10,7 +10,7 @@ import type { VgiSchema } from "../arrow/index.js";
 import type { VgiFunction } from "./types.js";
 import type { Arguments } from "../arguments/arguments.js";
 import type { ArgumentSpec } from "../arguments/argument-spec.js";
-import { FunctionNotFoundError } from "../errors.js";
+import { FunctionNotFoundError, VgiError } from "../errors.js";
 import { schemaPathDisplay, schemaPathKey } from "../schema-path.js";
 
 export interface OverloadContext {
@@ -289,9 +289,10 @@ export class FunctionRegistry {
       } else if (candidates && candidates.length > 0) {
         const schemas = this.schemasFor(name);
         if (schemas.length > 0) {
-          throw new Error(
+          throw new VgiError(
             `Function '${name}' is not registered in schema ${schemaPathDisplay(schemaPath)}. ` +
               `It is available in: [${schemas.map(schemaPathDisplay).join(", ")}]`,
+            "NOT_FOUND",
           );
         }
       }