@query-farm/vgi 0.43.0 → 0.44.0

package/README.md

@@ -572,9 +572,9 @@ new Worker({ functions, hostedProtocols: () => [reports] }).run();
   changes how DuckDB's `vgi.v2` calls are dispatched.
 - The protocol is the unit of optionality: an optional capability is its own protocol.
 
-### Token introspection and grants (`vgi_rpc.Identity.v1`)
+### Token introspection and grants (`vgi_rpc.Identity.v2`)
 
-A worker opts into `vgi_rpc.Identity.v1` by supplying `resolveToken` and/or
+A worker opts into `vgi_rpc.Identity.v2` by supplying `resolveToken` and/or
 `mintGrant` (accepted by `Worker`, `serveVgiWorker`, `createVgiWorkerFetch` and
 `createVgiFetch`). It is hosted on **HTTP only** — the transport that authenticates
 callers — and only the methods whose hooks exist are hosted; with neither, the
@@ -672,6 +672,9 @@ ATTACH 'ticket_probe' AS p (TYPE vgi, LOCATION 'https://worker.example.com',
   options (`invalid_request` with one `BadRequest` violation per field). The lifetime
   is capped at the grant maximum (`VGI_RPC_GRANT_MAX_TTL_SECONDS`, default 7 days with
   grant keys); `ttl_seconds: 0` asks for the maximum.
+  The reply's `expires_at` is a nullable `timestamp[us, tz=UTC]` (`Date | null` in
+  TypeScript), null when the worker sets no maximum lifetime; protocol version
+  `2.0.0` (1.0.0 carried float64 unix seconds with `+inf` for "no expiry").
 - **Redeeming.** `catalog_attach` redeems a `vgi_attach_ticket` option (any letter
   case) before any catalog code runs: it must be the only option (`invalid_request`),
   it opens only under the caller's principal and this worker's key

package/dist/attach-ticket.d.ts

@@ -7,8 +7,9 @@ export declare const ATTACH_TICKET_PREFIX = "vgia1.";
 export declare const ATTACH_TICKET_OPTION = "vgi_attach_ticket";
 /** Wire name of the protocol hosting `seal_attach`. */
 export declare const ATTACH_TICKETS_PROTOCOL_NAME = "vgi.attach_tickets.v1";
-/** Its declared version. */
-export declare 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 declare const ATTACH_TICKETS_PROTOCOL_VERSION = "2.0.0";
 /** The envelope's version byte, fixed by this format. */
 export declare const TICKET_ENVELOPE_VERSION = 1;
 /** Largest options record (serialized Arrow IPC bytes) a ticket may carry. */
@@ -141,8 +142,21 @@ export declare function callerPrincipal(auth: AuthContext | undefined | null): s
 export declare function redeemAttachTicket(options: Record<string, unknown>, signingKey: Uint8Array | undefined | null, auth: AuthContext | undefined | null, now?: number): Promise<RestoredAttach | null>;
 /** `SealAttachRequest`, field for field with vgi-python. */
 export declare const SEAL_ATTACH_REQUEST_SCHEMA: import("./index.core.js").VgiSchema;
-/** `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 declare const ATTACH_TICKET_SCHEMA: import("./index.core.js").VgiSchema;
+/** 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;
+}
+/** Encode an {@link AttachTicket} as a single-row Arrow IPC stream. */
+export declare function encodeAttachTicket(ticket: AttachTicket): Uint8Array;
 /**
  * The ticket lifetime ceiling: the worker's grant maximum, or `null`.
  *
@@ -166,10 +180,7 @@ export interface AttachTicketsConfig {
     now?: () => number;
 }
 /** Validate and seal; the body of `seal_attach`. */
-export declare function sealAttach(config: AttachTicketsConfig, request: Record<string, unknown>, auth: AuthContext | undefined): Promise<{
-    ticket: string;
-    expires_at: number;
-}>;
+export declare function sealAttach(config: AttachTicketsConfig, request: Record<string, unknown>, auth: AuthContext | undefined): Promise<AttachTicket>;
 /**
  * Build `vgi.attach_tickets.v1`: one unary method, `seal_attach(request:
  * SealAttachRequest) -> AttachTicket`, each carried as serialized Arrow IPC

package/dist/client-entry.js

@@ -13,6 +13,79 @@ var __export = (target, all) => {
     });
 };
 
+// src/arrow/impl-arrowjs/index.ts
+var exports_impl_arrowjs = {};
+__export(exports_impl_arrowjs, {
+  DateUnit: () => DateUnit,
+  IntervalUnit: () => IntervalUnit,
+  TimeUnit: () => TimeUnit,
+  UnionMode: () => UnionMode,
+  adoptArrowJsShape: () => adoptArrowJsShape,
+  backend: () => backend,
+  batchFromColumns: () => batchFromColumns,
+  batchFromRows: () => batchFromRows,
+  batchToScalarDict: () => batchToScalarDict,
+  batchToSecretDict: () => batchToSecretDict,
+  binary: () => binary,
+  bool: () => bool,
+  buildStatisticsBatch: () => buildStatisticsBatch,
+  columnFromArray: () => columnFromArray,
+  date: () => date,
+  dateDay: () => dateDay,
+  dateMillisecond: () => dateMillisecond,
+  decimal: () => decimal,
+  decimal128: () => decimal128,
+  decimal256: () => decimal256,
+  decodeDictValue: () => decodeDictValue,
+  denseUnion: () => denseUnion,
+  deserializeBatch: () => deserializeBatch,
+  deserializeSchema: () => deserializeSchema,
+  dictionary: () => dictionary,
+  duration: () => duration,
+  emptyBatch: () => emptyBatch,
+  field: () => field,
+  filterBatch: () => filterBatch,
+  fixedSizeBinary: () => fixedSizeBinary,
+  fixedSizeList: () => fixedSizeList,
+  float16: () => float16,
+  float32: () => float32,
+  float64: () => float64,
+  int: () => int,
+  int16: () => int16,
+  int32: () => int32,
+  int64: () => int64,
+  int8: () => int8,
+  interval: () => interval,
+  iterRows: () => iterRows,
+  largeBinary: () => largeBinary,
+  largeUtf8: () => largeUtf8,
+  list: () => list,
+  map: () => map,
+  nullType: () => nullType,
+  projectBatch: () => projectBatch,
+  projectSchema: () => projectSchema,
+  readCanonicalValue: () => readCanonicalValue,
+  safeNumber: () => safeNumber,
+  schema: () => schema,
+  serializeBatch: () => serializeBatch,
+  serializeSchema: () => serializeSchema,
+  sparseUnion: () => sparseUnion,
+  struct: () => struct,
+  time: () => time,
+  timeMicrosecond: () => timeMicrosecond,
+  timeMillisecond: () => timeMillisecond,
+  timeNanosecond: () => timeNanosecond,
+  timeSecond: () => timeSecond,
+  timestamp: () => timestamp,
+  uint16: () => uint16,
+  uint32: () => uint32,
+  uint64: () => uint64,
+  uint8: () => uint8,
+  union: () => union,
+  utf8: () => utf8,
+  withBatchMetadata: () => withBatchMetadata
+});
+
 // src/arrow/predicates.ts
 var TypeId = {
   Null: 1,
@@ -40,9 +113,15 @@ var TypeId = {
 function isInt(t) {
   return t.typeId === TypeId.Int;
 }
+function isFloat(t) {
+  return t.typeId === TypeId.Float;
+}
 function isBinary(t) {
   return t.typeId === TypeId.Binary || t.typeId === TypeId.LargeBinary;
 }
+function isUtf8(t) {
+  return t.typeId === TypeId.Utf8 || t.typeId === TypeId.LargeUtf8;
+}
 function isBool(t) {
   return t.typeId === TypeId.Bool;
 }
@@ -94,79 +173,6 @@ function typeSignature(t) {
       return Array.isArray(a.children) ? `${t.typeId}<${kids()}>` : String(t.typeId);
   }
 }
-// src/arrow/impl-arrowjs/index.ts
-var exports_impl_arrowjs = {};
-__export(exports_impl_arrowjs, {
-  DateUnit: () => DateUnit,
-  IntervalUnit: () => IntervalUnit,
-  TimeUnit: () => TimeUnit,
-  UnionMode: () => UnionMode,
-  adoptArrowJsShape: () => adoptArrowJsShape,
-  backend: () => backend,
-  batchFromColumns: () => batchFromColumns,
-  batchFromRows: () => batchFromRows,
-  batchToScalarDict: () => batchToScalarDict,
-  batchToSecretDict: () => batchToSecretDict,
-  binary: () => binary,
-  bool: () => bool,
-  buildStatisticsBatch: () => buildStatisticsBatch,
-  columnFromArray: () => columnFromArray,
-  date: () => date,
-  dateDay: () => dateDay,
-  dateMillisecond: () => dateMillisecond,
-  decimal: () => decimal,
-  decimal128: () => decimal128,
-  decimal256: () => decimal256,
-  decodeDictValue: () => decodeDictValue,
-  denseUnion: () => denseUnion,
-  deserializeBatch: () => deserializeBatch,
-  deserializeSchema: () => deserializeSchema,
-  dictionary: () => dictionary,
-  duration: () => duration,
-  emptyBatch: () => emptyBatch,
-  field: () => field,
-  filterBatch: () => filterBatch,
-  fixedSizeBinary: () => fixedSizeBinary,
-  fixedSizeList: () => fixedSizeList,
-  float16: () => float16,
-  float32: () => float32,
-  float64: () => float64,
-  int: () => int,
-  int16: () => int16,
-  int32: () => int32,
-  int64: () => int64,
-  int8: () => int8,
-  interval: () => interval,
-  iterRows: () => iterRows,
-  largeBinary: () => largeBinary,
-  largeUtf8: () => largeUtf8,
-  list: () => list,
-  map: () => map,
-  nullType: () => nullType,
-  projectBatch: () => projectBatch,
-  projectSchema: () => projectSchema,
-  readCanonicalValue: () => readCanonicalValue,
-  safeNumber: () => safeNumber,
-  schema: () => schema,
-  serializeBatch: () => serializeBatch,
-  serializeSchema: () => serializeSchema,
-  sparseUnion: () => sparseUnion,
-  struct: () => struct,
-  time: () => time,
-  timeMicrosecond: () => timeMicrosecond,
-  timeMillisecond: () => timeMillisecond,
-  timeNanosecond: () => timeNanosecond,
-  timeSecond: () => timeSecond,
-  timestamp: () => timestamp,
-  uint16: () => uint16,
-  uint32: () => uint32,
-  uint64: () => uint64,
-  uint8: () => uint8,
-  union: () => union,
-  utf8: () => utf8,
-  withBatchMetadata: () => withBatchMetadata
-});
-
 // src/arrow/impl-arrowjs/schema.ts
 import {
   Schema as A_Schema,
@@ -2073,6 +2079,116 @@ function toUint8Array(val) {
   return new Uint8Array(0);
 }
 
+// src/codec/conform.ts
+var OPTIONAL_ITEM_FIELDS = new Set(["argument_names"]);
+function children(type) {
+  return type.children ?? [];
+}
+function mapValueType(type) {
+  const entries = children(type)[0].type;
+  return children(entries)[1].type;
+}
+function mapPairs(raw) {
+  if (Array.isArray(raw))
+    return raw.map((e) => 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);
+  return Object.entries(raw);
+}
+function zeroValue(type) {
+  if (isUtf8(type) || isDictionary(type))
+    return "";
+  if (isBinary(type))
+    return new Uint8Array(0);
+  if (isBool(type))
+    return false;
+  if (isInt(type))
+    return type.bitWidth === 64 ? 0n : 0;
+  if (isFloat(type))
+    return 0;
+  if (isList(type) || isMap(type))
+    return [];
+  if (isStruct(type)) {
+    const out = {};
+    for (const c of children(type))
+      out[c.name] = c.nullable ? null : conformValue(c.type, undefined, false, c.name);
+    return out;
+  }
+  return null;
+}
+var HAS_CONTAINER = new WeakMap;
+function hasContainer(type) {
+  const cached = HAS_CONTAINER.get(type);
+  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, has);
+  return has;
+}
+function conformValue(type, value, nullable, name) {
+  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);
+    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]) => {
+      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 = 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;
+}
+function conformRecord(schema, obj) {
+  let out = 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;
+}
+
 // src/protocol/serializers/shared.ts
 function toUint8Array2(val) {
   if (typeof val === "string")
@@ -2085,8 +2201,9 @@ function toUint8Array2(val) {
 }
 function buildSingleRowBatch(schema, values) {
   const cols = {};
+  const row = conformRecord(schema, values);
   for (const f of schema.fields) {
-    let val = values[f.name];
+    let val = row[f.name];
     if (isInt(f.type) && f.type.bitWidth === 64 && typeof val === "number") {
       val = BigInt(val);
     }
@@ -2126,7 +2243,7 @@ function serializeBindRequest(req) {
   return buildSingleRowBatch(BIND_REQUEST_SCHEMA, {
     function_name: req.function_name,
     arguments: serializeArguments(req.arguments),
-    function_type: req.function_type,
+    function_type: req.function_type == null ? req.function_type : String(req.function_type).toUpperCase(),
     input_schema: req.input_schema ? serializeSchema(req.input_schema) : null,
     settings: req.settings ? serializeBatch(req.settings) : null,
     secrets: req.secrets ? serializeBatch(req.secrets) : null,
@@ -2222,9 +2339,12 @@ function deserializeGlobalInitResponse(params) {
 }
 // src/errors.ts
 class VgiError extends Error {
-  constructor(message) {
+  errorCode;
+  constructor(message, code) {
     super(message);
     this.name = "VgiError";
+    if (code !== undefined)
+      this.errorCode = code;
   }
 }
 
@@ -2237,42 +2357,42 @@ class RowCountMismatchError extends VgiError {
 
 class FunctionNotFoundError extends VgiError {
   constructor(name, available) {
-    super(`Unknown function '${name}'`);
+    super(`Unknown function '${name}'`, "NOT_FOUND");
     this.name = "FunctionNotFoundError";
   }
 }
 
 class CatalogReadOnlyError extends VgiError {
   constructor(operation) {
-    super(`catalog is read-only: ${operation} is not supported`);
+    super(`catalog is read-only: ${operation} is not supported`, "FAILED_PRECONDITION");
     this.name = "CatalogReadOnlyError";
   }
 }
 
 class CatalogNotFoundError extends VgiError {
   constructor(entity, name) {
-    super(`${entity} '${name}' not found`);
+    super(`${entity} '${name}' not found`, "NOT_FOUND");
     this.name = "CatalogNotFoundError";
   }
 }
 
 class CatalogAlreadyExistsError extends VgiError {
   constructor(entity, name) {
-    super(`${entity} '${name}' already exists`);
+    super(`${entity} '${name}' already exists`, "ALREADY_EXISTS");
     this.name = "CatalogAlreadyExistsError";
   }
 }
 
 class ArgumentValidationError extends VgiError {
   constructor(message) {
-    super(message);
+    super(message, "INVALID_ARGUMENT");
     this.name = "ArgumentValidationError";
   }
 }
 
 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";
   }
 }
@@ -2284,7 +2404,7 @@ function normalizeSchemaPath(path) {
 
 // src/codec/asd.ts
 function encodeASD(schema, obj) {
-  return serializeBatch(batchFromRows([sortMapsForSchema(schema, obj)], schema));
+  return serializeBatch(batchFromRows([sortMapsForSchema(schema, conformRecord(schema, obj))], schema));
 }
 function compareCodePoints(a, b) {
   const n = Math.min(a.length, b.length);
@@ -2301,7 +2421,7 @@ function compareCodePoints(a, b) {
   }
   return a.length - b.length;
 }
-function mapPairs(raw) {
+function mapPairs2(raw) {
   if (Array.isArray(raw))
     return raw.map((e) => Array.isArray(e) ? [e[0], e[1]] : [e?.key, e?.value]);
   if (raw instanceof Map)
@@ -2336,7 +2456,7 @@ function sortMapsForType(type, value) {
   if (isMap(type)) {
     const entries = type.children[0].type;
     const valueType = entries.children[1].type;
-    return mapPairs(value).map(([k, v]) => [k, sortMapsForType(valueType, v)]).sort((x, y) => compareKeys(x[0], y[0]));
+    return mapPairs2(value).map(([k, v]) => [k, sortMapsForType(valueType, v)]).sort((x, y) => compareKeys(x[0], y[0]));
   }
   if (isList(type)) {
     const child = type.children[0].type;
@@ -3619,6 +3739,10 @@ function toAsyncIterator(input) {
 }
 
 // src/client/client.ts
+function onConflictName(onConflict) {
+  return String(onConflict).toUpperCase();
+}
+
 class VgiClient {
   rpc;
   defaultAttachOpaqueData;
@@ -4074,7 +4198,7 @@ class VgiClient {
     }
     await this.rpc.call("catalog_create", {
       name,
-      on_conflict: onConflict,
+      on_conflict: onConflictName(onConflict),
       options: wireOptions
     });
   }
@@ -4142,7 +4266,7 @@ 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
@@ -4221,7 +4345,7 @@ 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,
@@ -4375,7 +4499,7 @@ class VgiClient {
       schema_path: normalizeSchemaPath(schemaPath),
       name,
       definition,
-      on_conflict: onConflict,
+      on_conflict: onConflictName(onConflict),
       transaction_opaque_data: transactionOpaqueData ?? null
     });
   }
@@ -4442,7 +4566,7 @@ 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]
@@ -4640,4 +4764,4 @@ export {
   typeSignature
 };
 
-//# debugId=62AEFEFC6DBD059D64756E2164756E21
+//# debugId=586BBE791F5462D664756E2164756E21