@query-farm/vgi 0.37.1 → 0.38.0

package/README.md

@@ -479,6 +479,7 @@ A worker serves the same functions over any of:
 - **AF_UNIX** — a long-lived warm worker (`--unix <path>`), reused across calls.
 - **HTTP** — stateless; all state round-trips in a self-contained token, so requests
   can be load-balanced across hosts.
+- **TCP** (`--tcp [HOST:]PORT`) and caller-provided byte streams (`worker.serveStream`).
 
 Transport handling lives in [`@query-farm/vgi-rpc`](https://www.npmjs.com/package/@query-farm/vgi-rpc).
 
@@ -541,6 +542,79 @@ its own required `name`/`doc`/`version`, so only the Cloudflare entry passes it
 explicitly. Without it there is no landing page and no `/vgi-client.js`; see
 [MIGRATION.md](MIGRATION.md).
 
+### Hosting additional protocols
+
+A worker can serve other [vgi-rpc](https://www.npmjs.com/package/@query-farm/vgi-rpc)
+protocols beside `vgi.v2`, on the same listener, through the `hostedProtocols` hook:
+
+```ts
+import { Protocol, str } from "@query-farm/vgi-rpc";
+
+const reports = new Protocol("acme.Reports.v1").unary("render", {
+  params: { id: str },
+  result: { result: str },
+  handler: ({ id }) => ({ result: `report ${id}` }),
+});
+
+new Worker({ functions, hostedProtocols: () => [reports] }).run();
+// …or serveVgiWorker({ …, hostedProtocols: () => [reports] }),
+// …or createVgiFetch({ …, hostedProtocols: () => [reports] }) on Cloudflare Workers.
+```
+
+- The hook is called **once**, when the server is built; it may read configuration,
+  but its answer is fixed for the life of the process.
+- Its protocols are hosted on **every** transport (stdio, AF_UNIX, TCP, the Iroh raw
+  upstream, `serveStream`, HTTP), after `vgi.v2`, in the order returned. Every
+  transport builds its server through one function, `buildRpcServer`.
+- Each needs a distinct name, which may not be `vgi.v2` or start with the reserved
+  `vgi_rpc.`. Violations are a startup error naming `hostedProtocols()`.
+- Requests route on their `vgi_rpc.protocol` key, so hosting more protocols never
+  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`)
+
+A worker opts into `vgi_rpc.Identity.v1` 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
+protocol is absent.
+
+```ts
+import { AuthUnavailableError } from "@query-farm/vgi";
+
+serveVgiWorker({
+  // …
+  resolveToken: async (token) => {
+    let row;
+    try {
+      row = await apiKeys.lookup(token);
+    } catch (err) {
+      // "I could not find out" -- an outage, not a refusal.
+      throw new AuthUnavailableError("key store unreachable", 5);
+    }
+    return row ? { principal: row.principal, tokenName: row.label } : null; // null = unknown
+  },
+  introspectPrincipals: ["edge-proxy"], // or VGI_INTROSPECT_PRINCIPALS=edge-proxy
+});
+```
+
+**Enabling introspection without an allowlist refuses to start.** Authenticating
+and introspecting are different capabilities; "any authenticated caller" would let
+any user resolve any other user's credential to its owner. Set
+`introspectPrincipals` or `VGI_INTROSPECT_PRINCIPALS` (comma-separated). `mintGrant`
+alone needs no allowlist.
+
+**Transient failures:** throw `AuthUnavailableError` (re-exported here from
+`@query-farm/vgi-rpc`) from `resolveToken` or `mintGrant` when the answer is not
+knowable — a store or sidecar outage, a timeout, a 5xx. The framework translates it
+to `identity_unavailable` (code `UNAVAILABLE`) carrying that error's retry hint as
+`vgi_rpc.RetryInfo`, so a caller retries instead of caching a refusal.
+`IdentityUnavailableError` works too. Never throw a plain `Error` for an outage, and
+never return `null` for one: both read as a definitive answer. Return `null` only
+when the store answered and the credential is unknown; throw `GrantRefusedError` to
+decline a grant.
+
 ## Runtimes & entry points
 
 The package ships a backend-agnostic Arrow facade and selects an implementation at

package/dist/catalog/composite.d.ts

@@ -1,4 +1,4 @@
-import type { AttachOpaqueData, CatalogAttachResult, CatalogInfo, CopyFromFormatInfo, FunctionInfo, IndexInfo, MacroInfo, SchemaInfo, TableInfo, TransactionOpaqueData, ViewInfo } from "./interface.js";
+import type { AttachOpaqueData, CatalogAttachResult, CatalogInfo, CopyFromFormatInfo, FunctionInfo, IndexInfo, MacroInfo, CatalogContentsResult, SchemaInfo, TableInfo, TransactionOpaqueData, ViewInfo } from "./interface.js";
 import { CatalogInterface } from "./interface.js";
 export declare class CompositeCatalogInterface extends CatalogInterface {
     private readonly _backends;
@@ -28,6 +28,28 @@ export declare class CompositeCatalogInterface extends CatalogInterface {
     } | null>;
     viewGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo | null>;
     macroGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[], name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<MacroInfo | null>;
+    schemaCreate(...args: Parameters<CatalogInterface["schemaCreate"]>): Promise<void>;
+    schemaDrop(...args: Parameters<CatalogInterface["schemaDrop"]>): Promise<void>;
+    tableCreate(...args: Parameters<CatalogInterface["tableCreate"]>): Promise<void>;
+    tableDrop(...args: Parameters<CatalogInterface["tableDrop"]>): Promise<void>;
+    tableCommentSet(...args: Parameters<CatalogInterface["tableCommentSet"]>): Promise<void>;
+    tableRename(...args: Parameters<CatalogInterface["tableRename"]>): Promise<void>;
+    tableColumnAdd(...args: Parameters<CatalogInterface["tableColumnAdd"]>): Promise<void>;
+    tableColumnDrop(...args: Parameters<CatalogInterface["tableColumnDrop"]>): Promise<void>;
+    tableColumnRename(...args: Parameters<CatalogInterface["tableColumnRename"]>): Promise<void>;
+    tableColumnDefaultSet(...args: Parameters<CatalogInterface["tableColumnDefaultSet"]>): Promise<void>;
+    tableColumnDefaultDrop(...args: Parameters<CatalogInterface["tableColumnDefaultDrop"]>): Promise<void>;
+    tableColumnTypeChange(...args: Parameters<CatalogInterface["tableColumnTypeChange"]>): Promise<void>;
+    tableNotNullSet(...args: Parameters<CatalogInterface["tableNotNullSet"]>): Promise<void>;
+    tableNotNullDrop(...args: Parameters<CatalogInterface["tableNotNullDrop"]>): Promise<void>;
+    viewCreate(...args: Parameters<CatalogInterface["viewCreate"]>): Promise<void>;
+    viewDrop(...args: Parameters<CatalogInterface["viewDrop"]>): Promise<void>;
+    viewRename(...args: Parameters<CatalogInterface["viewRename"]>): Promise<void>;
+    viewCommentSet(...args: Parameters<CatalogInterface["viewCommentSet"]>): Promise<void>;
+    macroCreate(...args: Parameters<CatalogInterface["macroCreate"]>): Promise<void>;
+    macroDrop(...args: Parameters<CatalogInterface["macroDrop"]>): Promise<void>;
+    catalogContents(attachOpaqueData: AttachOpaqueData, ifNoneMatch?: string | null): Promise<CatalogContentsResult>;
+    catalogContentsOwner(attachOpaqueData: AttachOpaqueData): CatalogInterface;
     copyFromFormats(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Promise<CopyFromFormatInfo[]>;
     transactionBegin(attachOpaqueData: AttachOpaqueData): Promise<Uint8Array | null>;
     transactionCommit(attachOpaqueData: AttachOpaqueData, transactionOpaqueData: TransactionOpaqueData): Promise<void>;

package/dist/catalog/contents-digest.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The `content-hash` etag for `catalog_contents`.
+ *
+ * Mirrors vgi-python's `catalog_contents_digest()` byte for byte, so the same
+ * snapshot (the same item bytes) gives the same etag in every SDK.
+ */
+import type { SchemaContents } from "../generated/vgi-protocol-types.js";
+/**
+ * Hex SHA-256 over a `catalog_contents` snapshot: the `content-hash` etag.
+ *
+ * Covers every schema's path and the exact item bytes of every kind, in
+ * order, each length-prefixed (8-byte little-endian) so no two different
+ * snapshots share an input:
+ *
+ *   u64(#schemas) { u64(#path) {u64(len) utf8(part)}*  u64(len) schema
+ *                   ( u64(#items) {u64(len) item}* ) x 8 kinds }*
+ *
+ * Deterministic because the items' encoding is (map columns are written in
+ * sorted key order, see `encodeASD`), so two builds of the same catalog hash
+ * alike.
+ *
+ * @param schemas The snapshot, in wire order.
+ * @returns The lowercase hex digest.
+ */
+export declare function catalogContentsDigest(schemas: readonly SchemaContents[]): Promise<string>;

package/dist/catalog/interface.d.ts

@@ -2,8 +2,9 @@ export type AttachOpaqueData = Uint8Array;
 export type TransactionOpaqueData = Uint8Array;
 import type { MacroType } from "../generated/vgi-client.js";
 export type { MacroType };
-import type { CatalogAttachResult } from "../generated/vgi-client.js";
-export type { CatalogAttachResult };
+import type { CatalogAttachResult, CatalogAttachResultInit } from "../generated/vgi-protocol-types.js";
+export type { CatalogAttachResult, CatalogAttachResultInit };
+export { buildCatalogAttachResult } from "../generated/vgi-protocol-types.js";
 import type { SchemaInfo } from "../generated/vgi-client.js";
 export type { SchemaInfo };
 export { encodeSchemaInfo, decodeSchemaInfo } from "../generated/vgi-client.js";
@@ -243,6 +244,45 @@ export declare function buildScanBranchesResult(branches: ScanBranchInput[], req
     branches: Uint8Array[];
     required_extensions: string[];
 };
+/**
+ * One schema and everything in it, as returned by
+ * `CatalogInterface.catalogContents` (vgi-python's `SchemaContentsInfo`).
+ *
+ * Each kind is complete: an empty list means the schema has none of that kind.
+ * The `catalog_contents` handler encodes every item with the same encoder the
+ * matching per-schema RPC uses, so the items are byte-for-byte what
+ * `catalog_schemas` / `catalog_schema_contents_*` would return.
+ */
+export interface SchemaContentsInfo {
+    schema: SchemaInfo;
+    tables: TableInfo[];
+    views: ViewInfo[];
+    scalar_functions: FunctionInfo[];
+    aggregate_functions: FunctionInfo[];
+    table_functions: FunctionInfo[];
+    scalar_macros: MacroInfo[];
+    table_macros: MacroInfo[];
+    indexes: IndexInfo[];
+}
+/**
+ * What `CatalogInterface.catalogContents` returns: a snapshot, or "not
+ * modified" (vgi-python's `CatalogContentsResult`).
+ *
+ * - `schemas`: one `SchemaContentsInfo` per schema. Must be empty (or absent)
+ *   when `not_modified` is set.
+ * - `etag`: opaque validator for this snapshot (a generation counter, schema
+ *   version, git sha, ...). The client sends it back as `if_none_match`.
+ *   Null/absent means the catalog does not revalidate -- unless it opts in to
+ *   the framework's content hash with `catalogContentsEtag = "content-hash"`.
+ * - `not_modified`: true when the request's `if_none_match` equals the
+ *   current etag, so the catalog skipped building the snapshot. Requires
+ *   `etag` (the matching validator).
+ */
+export interface CatalogContentsResult {
+    schemas?: SchemaContentsInfo[];
+    etag?: string | null;
+    not_modified?: boolean;
+}
 /**
  * Catalog method return type — sync `T` or `Promise<T>`. The framework's
  * dispatch handlers `await` every catalog call, so async overrides work
@@ -250,6 +290,36 @@ export declare function buildScanBranchesResult(branches: ScanBranchInput[], req
  */
 type Awaitable<T> = T | Promise<T>;
 export declare abstract class CatalogInterface {
+    /**
+     * Opt-in framework etag for `catalog_contents`. `"content-hash"`: when
+     * `catalogContents` returns no etag of its own, the worker uses the hex
+     * SHA-256 of the serialized snapshot (`catalogContentsDigest`) as the etag
+     * and turns a matching `if_none_match` into `not_modified` (it still builds
+     * the snapshot, but saves the transfer and the client's decode). `null`
+     * (default): no etag unless the catalog returns one. Off by default because
+     * for a catalog whose version is not frozen the client would revalidate with
+     * a full build on every transaction instead of a cheap `catalog_version`
+     * poll. Mirrors vgi-python's `catalog_contents_etag`.
+     */
+    catalogContentsEtag: "content-hash" | null;
+    /**
+     * Whether `catalogContents` depends only on `version()`: not on the attach
+     * (`attach_opaque_data`, attach options), the caller's identity, or anything
+     * else. Together with `catalogVersionFrozen`, it lets the worker build the
+     * `catalog_contents` response once per (catalog, version) and serve the same
+     * serialized bytes to every caller. Default false.
+     *
+     * `ReadOnlyCatalogInterface` sets it (its items carry a fixed attach id,
+     * like vgi-python's), unless its `perAttachItemIds` opt-in is on. A
+     * subclass whose contents vary per caller or attach option sets it false.
+     */
+    catalogContentsAttachIndependent: boolean;
+    /**
+     * Declares that `version()` never changes for this catalog instance (the
+     * attach result's `catalog_version_frozen`). Only the `catalog_contents`
+     * worker cache reads it. `ReadOnlyCatalogInterface` sets it.
+     */
+    catalogVersionFrozen: boolean;
     /**
      * Which catalog an `attach_opaque_data` belongs to, or null if unknown.
      *
@@ -348,6 +418,41 @@ export declare abstract class CatalogInterface {
      * vgi-python's `CatalogInterface.copy_from_formats`.
      */
     copyFromFormats(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Awaitable<CopyFromFormatInfo[]>;
+    /**
+     * Every schema and all of its contents, for the `catalog_contents` RPC.
+     *
+     * Served only to a client whose attach result set
+     * `supports_catalog_contents` (ReadOnlyCatalogInterface does). The default
+     * composes `schemas()` with the per-kind `schemaContents*()` calls, skipping
+     * a kind whose `estimated_object_count` is exactly 0 (a hard guarantee), and
+     * returns no etag -- so any catalog can serve it without new code. It runs
+     * with no transaction: the client caches the answer for the whole attach.
+     *
+     * Override it to build the snapshot more cheaply, or to revalidate: return
+     * an `etag` with the contents, and when `ifNoneMatch` equals the current
+     * etag return `{ etag, not_modified: true }` *before* building anything.
+     * Mirrors vgi-python's `CatalogInterface.catalog_contents`.
+     *
+     * @param ifNoneMatch The etag of the snapshot the client already holds, or
+     *   null.
+     * @returns One `SchemaContentsInfo` per schema, in `schemas()` order (the
+     *   handler sorts parents before children), plus its etag -- or
+     *   `not_modified`.
+     */
+    catalogContents(attachOpaqueData: AttachOpaqueData, _ifNoneMatch?: string | null): Promise<CatalogContentsResult>;
+    /**
+     * Whether the worker may build `catalog_contents` once per (catalog
+     * instance, version) and reuse the serialized response for every caller:
+     * `catalogContentsAttachIndependent && catalogVersionFrozen` by default.
+     */
+    catalogContentsCacheable(): boolean;
+    /**
+     * The catalog that answers `catalog_contents` for this attach: whose
+     * `catalogContentsEtag` / `catalogContentsAttachIndependent` /
+     * `catalogVersionFrozen` the handler honours and whose instance keys the
+     * worker cache. `this`, except for a composite, which routes to its backend.
+     */
+    catalogContentsOwner(_attachOpaqueData: AttachOpaqueData): CatalogInterface;
     transactionBegin(attachOpaqueData: AttachOpaqueData): Awaitable<Uint8Array | null>;
     transactionCommit(attachOpaqueData: AttachOpaqueData, transactionOpaqueData: TransactionOpaqueData): Awaitable<void>;
     transactionRollback(attachOpaqueData: AttachOpaqueData, transactionOpaqueData: TransactionOpaqueData): Awaitable<void>;

package/dist/catalog/read-only.d.ts

@@ -2,7 +2,43 @@ import { CatalogInterface, type AttachOpaqueData, type TransactionOpaqueData, ty
 import { type CatalogDescriptor } from "./descriptors.js";
 import type { FunctionRegistry } from "../functions/registry.js";
 import { type AttachOptionSpec } from "./attach-option.js";
+/**
+ * The fixed attach id ReadOnlyCatalogInterface writes into its items (same
+ * bytes as vgi-python's `ReadOnlyCatalogInterface._FIXED_ATTACH_ID`). Shared:
+ * treat it as read-only (a typed array cannot be frozen).
+ */
+export declare const READ_ONLY_ITEM_ATTACH_ID: AttachOpaqueData;
 export declare class ReadOnlyCatalogInterface extends CatalogInterface {
+    /**
+     * Advertise `supports_catalog_contents` on attach, letting the client load
+     * the whole catalog with one `catalog_contents` call instead of
+     * `catalog_schemas` plus a `catalog_schema_contents_*` call per schema and
+     * kind. True by default — a descriptor catalog is static. Set it to false
+     * (before attach) to keep the client on the per-schema RPCs.
+     */
+    supportsCatalogContents: boolean;
+    /** A descriptor catalog's version never changes (`catalog_version_frozen`). */
+    catalogVersionFrozen: boolean;
+    /**
+     * The catalog items (`SchemaInfo.attach_opaque_data`, and the attach value
+     * handed to a table function's bind when resolving a table's columns) carry
+     * one fixed id, `READ_ONLY_ITEM_ATTACH_ID`, not the per-ATTACH id -- as
+     * vgi-python's ReadOnlyCatalogInterface does. So the items are the same for
+     * every attach and caller, and the worker caches the `catalog_contents`
+     * response (see `catalogContentsCacheable`).
+     *
+     * `attach()` still mints a random per-ATTACH `attach_opaque_data` (sealed
+     * into the per-attach envelope the client holds), and function calls still
+     * receive it, so per-attach scoping in functions (the accumulate example) is
+     * unchanged.
+     *
+     * Set true (or pass `{ perAttachItemIds: true }` to the constructor) for a
+     * catalog whose items must echo the per-attach id. Its contents then depend
+     * on the attach, so the catalog_contents cache is off for it.
+     */
+    perAttachItemIds: boolean;
+    /** Static contents: attach-independent unless `perAttachItemIds` is set. */
+    catalogContentsAttachIndependent: boolean;
     private _descriptor;
     private _registry;
     private _attachments;
@@ -18,7 +54,9 @@ export declare class ReadOnlyCatalogInterface extends CatalogInterface {
     private _functionListings;
     /** One frozen FunctionInfo per (declaring schema, function), shared by listings and `global_functions`. */
     private _functionInfos;
-    constructor(descriptor: CatalogDescriptor, registry: FunctionRegistry);
+    constructor(descriptor: CatalogDescriptor, registry: FunctionRegistry, options?: {
+        perAttachItemIds?: boolean;
+    });
     /**
      * Which schema declares `fn`, by object identity, or null if no schema does.
      *
@@ -51,6 +89,12 @@ export declare class ReadOnlyCatalogInterface extends CatalogInterface {
     attach(name: string, options?: Record<string, unknown>, dataVersionSpec?: string | null, implementationVersion?: string | null): CatalogAttachResult | Promise<CatalogAttachResult>;
     detach(attachOpaqueData: AttachOpaqueData): void;
     version(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): number | Promise<number>;
+    /**
+     * The attach value written into this catalog's items: the fixed
+     * `READ_ONLY_ITEM_ATTACH_ID`, or the caller's attach with `perAttachItemIds`.
+     */
+    protected itemAttachId(attachOpaqueData: AttachOpaqueData): AttachOpaqueData;
+    catalogContentsCacheable(): boolean;
     schemas(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): SchemaInfo[];
     private _estimatedObjectCount;
     schemaGet(attachOpaqueData: AttachOpaqueData, path: string[], transactionOpaqueData?: TransactionOpaqueData): SchemaInfo | null;

package/dist/client/client.d.ts

@@ -1,6 +1,6 @@
 import { type VgiBatch } from "../arrow/index.js";
 import type { RpcClient } from "@query-farm/vgi-rpc";
-import { type SchemaInfo, type TableInfo, type ViewInfo, type FunctionInfo, type MacroInfo, type MacroType, type CatalogAttachResult, type AttachOpaqueData, type TransactionOpaqueData, type CatalogInfo, type ScanFunctionResult } from "../catalog/interface.js";
+import { type SchemaInfo, type TableInfo, type ViewInfo, type FunctionInfo, type MacroInfo, type MacroType, type CatalogAttachResult, type SchemaContentsInfo, type AttachOpaqueData, type TransactionOpaqueData, type CatalogInfo, type ScanFunctionResult } from "../catalog/interface.js";
 import { VgiClientError } from "./errors.js";
 export { VgiClientError };
 import type { VgiClientOptions, TableFunctionOptions, ScalarFunctionOptions, TableInOutFunctionOptions, OnCreateConflict, CatalogFunctionType, CatalogMacroType, CatalogAttachOptions, AttachOptionValue } from "./types.js";
@@ -92,6 +92,24 @@ export declare class VgiClient {
      * ```
      */
     catalogAttach(name: string, opts?: CatalogAttachOptions): Promise<CatalogAttachResult>;
+    /**
+     * Load the whole catalog in one `catalog_contents` call: every schema (parents
+     * before children) with all of its tables, views, functions, macros and
+     * indexes. Only call it when the attach result set
+     * `supports_catalog_contents`; it is the committed catalog at
+     * `catalog_version` (no transaction).
+     *
+     * Pass the `etag` of a snapshot you hold as `ifNoneMatch`: when it is still
+     * current the worker answers `not_modified` with no schemas. `etag` null
+     * means the worker does not revalidate. Each schema's wire `path` is checked
+     * against its decoded `SchemaInfo.path`.
+     */
+    catalogContents(attachOpaqueData: AttachOpaqueData, ifNoneMatch?: string | null): Promise<{
+        catalog_version: number;
+        etag: string | null;
+        not_modified: boolean;
+        schemas: SchemaContentsInfo[];
+    }>;
     /** Detach a previously-attached catalog. */
     catalogDetach(attachOpaqueData: AttachOpaqueData): Promise<void>;
     /**

package/dist/client-entry.js

@@ -2284,7 +2284,84 @@ function normalizeSchemaPath(path) {
 
 // src/codec/asd.ts
 function encodeASD(schema, obj) {
-  return serializeBatch(batchFromRows([obj], schema));
+  return serializeBatch(batchFromRows([sortMapsForSchema(schema, obj)], schema));
+}
+function compareCodePoints(a, b) {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0;i < n; i++) {
+    const x = a.charCodeAt(i);
+    const y = b.charCodeAt(i);
+    if (x === y)
+      continue;
+    const xs = x >= 55296 && x <= 57343;
+    const ys = y >= 55296 && y <= 57343;
+    if (xs !== ys)
+      return xs ? 1 : -1;
+    return x - y;
+  }
+  return a.length - b.length;
+}
+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 compareKeys(a, b) {
+  if (typeof a === "string" && typeof b === "string")
+    return compareCodePoints(a, b);
+  if ((typeof a === "number" || typeof a === "bigint") && (typeof b === "number" || typeof b === "bigint")) {
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  return compareCodePoints(String(a), String(b));
+}
+var HAS_MAP = new WeakMap;
+function typeHasMap(type) {
+  const cached = HAS_MAP.get(type);
+  if (cached !== undefined)
+    return cached;
+  let has = isMap(type);
+  if (!has && (isList(type) || isStruct(type))) {
+    has = type.children.some((c) => typeHasMap(c.type));
+  }
+  HAS_MAP.set(type, has);
+  return has;
+}
+function sortMapsForType(type, value) {
+  if (value == null || !typeHasMap(type))
+    return 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]));
+  }
+  if (isList(type)) {
+    const child = type.children[0].type;
+    return Array.from(value, (v) => sortMapsForType(child, v));
+  }
+  if (isStruct(type)) {
+    const out = { ...value };
+    for (const cf of type.children)
+      out[cf.name] = sortMapsForType(cf.type, value[cf.name]);
+    return out;
+  }
+  return value;
+}
+function sortMapsForSchema(schema, obj) {
+  let out = null;
+  for (const f of schema.fields) {
+    if (!typeHasMap(f.type))
+      continue;
+    const v = obj[f.name];
+    if (v == null)
+      continue;
+    out ??= { ...obj };
+    out[f.name] = sortMapsForType(f.type, v);
+  }
+  return out ?? obj;
 }
 function decodeASD(schema, bytes) {
   const batch = deserializeBatch(bytes);
@@ -2540,6 +2617,18 @@ var ForeignKeyInfoSchema = schema2([
   field2("referenced_table", utf82(), false),
   field2("referenced_schema_path", list2(field2("item", utf82(), true)), false)
 ]);
+var SchemaContentsSchema = schema2([
+  field2("path", list2(field2("item", utf82(), true)), false),
+  field2("schema", binary2(), false),
+  field2("tables", list2(field2("item", binary2(), true)), false),
+  field2("views", list2(field2("item", binary2(), true)), false),
+  field2("scalar_functions", list2(field2("item", binary2(), true)), false),
+  field2("aggregate_functions", list2(field2("item", binary2(), true)), false),
+  field2("table_functions", list2(field2("item", binary2(), true)), false),
+  field2("scalar_macros", list2(field2("item", binary2(), true)), false),
+  field2("table_macros", list2(field2("item", binary2(), true)), false),
+  field2("indexes", list2(field2("item", binary2(), true)), false)
+]);
 var AggregateBindRequestSchema = schema2([
   field2("function_name", utf82(), false),
   field2("arguments", binary2(), false),
@@ -2862,11 +2951,18 @@ var CatalogAttachResultSchema = schema2([
   field2("global_functions", list2(field2("item", binary2(), true)), false),
   field2("global_function_prefix", utf82(), false),
   field2("resolved_data_version", utf82(), true),
-  field2("resolved_implementation_version", utf82(), true)
+  field2("resolved_implementation_version", utf82(), true),
+  field2("supports_catalog_contents", bool2(), false)
 ]);
 var CatalogCatalogsResultSchema = schema2([
   field2("items", list2(field2("item", binary2(), true)), false)
 ]);
+var CatalogContentsResultSchema = schema2([
+  field2("catalog_version", int642(), false),
+  field2("etag", utf82(), true),
+  field2("not_modified", bool2(), false),
+  field2("schemas", list2(field2("item", struct2([field2("path", list2(field2("item", utf82(), true)), false), field2("schema", binary2(), false), field2("tables", list2(field2("item", binary2(), true)), false), field2("views", list2(field2("item", binary2(), true)), false), field2("scalar_functions", list2(field2("item", binary2(), true)), false), field2("aggregate_functions", list2(field2("item", binary2(), true)), false), field2("table_functions", list2(field2("item", binary2(), true)), false), field2("scalar_macros", list2(field2("item", binary2(), true)), false), field2("table_macros", list2(field2("item", binary2(), true)), false), field2("indexes", list2(field2("item", binary2(), true)), false)]), true)), false)
+]);
 var CatalogCopyFromFormatsResultSchema = schema2([
   field2("items", list2(field2("item", binary2(), true)), false)
 ]);
@@ -2985,6 +3081,10 @@ var CatalogAttachParamsSchema = schema2([
   field2("request", binary2(), false)
 ]);
 var CatalogCatalogsParamsSchema = schema2([]);
+var CatalogContentsParamsSchema = schema2([
+  field2("attach_opaque_data", binary2(), false),
+  field2("if_none_match", utf82(), true)
+]);
 var CatalogCopyFromFormatsParamsSchema = schema2([
   field2("attach_opaque_data", binary2(), false),
   field2("transaction_opaque_data", binary2(), true)
@@ -3315,10 +3415,14 @@ var TableFunctionStatisticsParamsSchema = schema2([
   field2("request", binary2(), false)
 ]);
 
+// src/generated/vgi-protocol-types.ts
+var decodeCatalogContentsResponse = (b) => decodeASD(CatalogContentsResultSchema, b);
+
 // src/generated/vgi-client.ts
 var decodeCatalogInfo = (b) => decodeASD(CatalogInfoSchema, b);
 var encodeFunctionInfo = (v) => encodeASD(FunctionInfoSchema, v);
 var decodeFunctionInfo = (b) => decodeASD(FunctionInfoSchema, b);
+var decodeIndexInfo = (b) => decodeASD(IndexInfoSchema, b);
 var encodeMacroInfo = (v) => encodeASD(MacroInfoSchema, v);
 var decodeMacroInfo = (b) => decodeASD(MacroInfoSchema, b);
 var encodeSchemaInfo = (v) => encodeASD(SchemaInfoSchema, v);
@@ -3833,7 +3937,40 @@ class VgiClient {
       global_functions: inner.global_functions ? (Array.isArray(inner.global_functions) ? inner.global_functions : [...inner.global_functions]).map(toUint8Array) : [],
       global_function_prefix: inner.global_function_prefix ?? "",
       resolved_data_version: inner.resolved_data_version ?? null,
-      resolved_implementation_version: inner.resolved_implementation_version ?? null
+      resolved_implementation_version: inner.resolved_implementation_version ?? null,
+      supports_catalog_contents: inner.supports_catalog_contents ?? false
+    };
+  }
+  async catalogContents(attachOpaqueData, ifNoneMatch = null) {
+    const result = await this.rpc.call("catalog_contents", {
+      attach_opaque_data: attachOpaqueData,
+      if_none_match: ifNoneMatch
+    });
+    if (!result)
+      throw new VgiClientError("catalog_contents returned null");
+    const response = decodeCatalogContentsResponse(toUint8Array(result.result));
+    const schemas = response.schemas.map((c) => {
+      const schema = decodeSchemaInfo(c.schema);
+      if (JSON.stringify(c.path) !== JSON.stringify(schema.path)) {
+        throw new VgiClientError(`catalog_contents: SchemaContents.path ${JSON.stringify(c.path)} != SchemaInfo.path ${JSON.stringify(schema.path)}`);
+      }
+      return {
+        schema,
+        tables: c.tables.map(decodeTableInfo),
+        views: c.views.map(decodeViewInfo),
+        scalar_functions: c.scalar_functions.map(decodeFunctionInfo),
+        aggregate_functions: c.aggregate_functions.map(decodeFunctionInfo),
+        table_functions: c.table_functions.map(decodeFunctionInfo),
+        scalar_macros: c.scalar_macros.map(decodeMacroInfo),
+        table_macros: c.table_macros.map(decodeMacroInfo),
+        indexes: c.indexes.map(decodeIndexInfo)
+      };
+    });
+    return {
+      catalog_version: Number(response.catalog_version ?? 0),
+      etag: response.etag ?? null,
+      not_modified: Boolean(response.not_modified),
+      schemas
     };
   }
   async catalogDetach(attachOpaqueData) {
@@ -4412,4 +4549,4 @@ export {
   typeSignature
 };
 
-//# debugId=8BECE39CB65F6AD764756E2164756E21
+//# debugId=AD4326E5920F408164756E2164756E21