@query-farm/vgi 0.37.1 → 0.39.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,9 +1,9 @@
 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 IndexInfo, 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";
+import type { VgiClientOptions, TableFunctionOptions, ScalarFunctionOptions, TableInOutFunctionOptions, OnCreateConflict, CatalogFunctionType, CatalogMacroType, CatalogAttachOptions, AttachOptionValue, CatalogSnapshot, LoadCatalogOptions } from "./types.js";
 /**
  * High-level client for calling VGI worker functions and catalog API.
  *
@@ -92,6 +92,51 @@ 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`.
+     *
+     * This is the raw RPC. To enumerate a catalog, use `loadCatalog`, which
+     * checks the capability, revalidates and falls back to the per-schema RPCs.
+     */
+    catalogContents(attachOpaqueData: AttachOpaqueData, ifNoneMatch?: string | null): Promise<{
+        catalog_version: number;
+        etag: string | null;
+        not_modified: boolean;
+        schemas: SchemaContentsInfo[];
+    }>;
+    /**
+     * Enumerate the whole catalog: every schema with all of its tables, views,
+     * scalar/aggregate/table functions, scalar/table macros and indexes.
+     *
+     * Honors the attach result's `supports_catalog_contents` the way the DuckDB
+     * extension does:
+     *
+     * - advertised (and `useCatalogContents` not false, no transaction): one
+     *   `catalog_contents` call. With `previous.etag` it is conditional
+     *   (`if_none_match`); `not_modified` returns `previous`'s contents.
+     * - not advertised: `catalog_schemas` + per-schema
+     *   `catalog_schema_contents_*` calls -- `catalog_contents` is never sent.
+     *   Kinds whose `estimated_object_count` is exactly 0 are skipped.
+     * - advertised but the call fails (or answers malformed, e.g. a
+     *   `SchemaContents.path` that disagrees with its `SchemaInfo.path`): falls
+     *   back to the per-schema calls and reports the failure in
+     *   `fallback_error`.
+     *
+     * A full answer older than `previous` (a lagging replica) is retried once,
+     * then the per-schema path is used.
+     */
+    loadCatalog(attach: Pick<CatalogAttachResult, "attach_opaque_data" | "supports_catalog_contents">, opts?: LoadCatalogOptions): Promise<CatalogSnapshot>;
+    /** `loadCatalog` without `catalog_contents`: catalog_schemas + per-schema calls. */
+    private _loadCatalogPerSchema;
     /** Detach a previously-attached catalog. */
     catalogDetach(attachOpaqueData: AttachOpaqueData): Promise<void>;
     /**
@@ -135,6 +180,8 @@ export declare class VgiClient {
     schemaContentsViews(attachOpaqueData: AttachOpaqueData, path: string[] | string, transactionOpaqueData?: TransactionOpaqueData): Promise<ViewInfo[]>;
     /** List functions in a schema, filtered by type. */
     schemaContentsFunctions(attachOpaqueData: AttachOpaqueData, path: string[] | string, type: CatalogFunctionType, transactionOpaqueData?: TransactionOpaqueData): Promise<FunctionInfo[]>;
+    /** List indexes in a schema. */
+    schemaContentsIndexes(attachOpaqueData: AttachOpaqueData, path: string[] | string, transactionOpaqueData?: TransactionOpaqueData): Promise<IndexInfo[]>;
     /** Get a table by name, or null if not found. */
     tableGet(attachOpaqueData: AttachOpaqueData, schemaPath: string[] | string, name: string, transactionOpaqueData?: TransactionOpaqueData): Promise<TableInfo | null>;
     /** Create a new table. */

package/dist/client/types.d.ts

@@ -2,6 +2,7 @@ import type { VgiBatch } from "../arrow/index.js";
 import type { Arguments } from "../arguments/arguments.js";
 import type { AttachOptionValue } from "../catalog/attach-options.js";
 import type { BindResponse } from "../protocol/types.js";
+import type { SchemaContentsInfo, TransactionOpaqueData } from "../catalog/interface.js";
 import { OrderByDirection, OrderByNullOrder } from "../protocol/types.js";
 export type { AttachOptionValue };
 export { OrderByDirection, OrderByNullOrder };
@@ -46,7 +47,7 @@ export interface CatalogAttachOptions {
 /** Conflict resolution strategy for create operations. */
 export type OnCreateConflict = "error" | "ignore" | "replace";
 /** DuckDB catalog function type filter (sent as uppercase wire values). */
-export type CatalogFunctionType = "SCALAR_FUNCTION" | "TABLE_FUNCTION";
+export type CatalogFunctionType = "SCALAR_FUNCTION" | "AGGREGATE_FUNCTION" | "TABLE_FUNCTION";
 /** Macro type filter for schema contents listing (uppercase wire values). */
 export type CatalogMacroType = "SCALAR_MACRO" | "TABLE_MACRO";
 /** Options for constructing a VgiClient. */
@@ -136,3 +137,57 @@ export interface TableInOutFunctionOptions {
      */
     hasFinalize?: boolean;
 }
+/**
+ * A whole-catalog snapshot returned by `VgiClient.loadCatalog`: every schema
+ * with all of its tables, views, functions, macros and indexes.
+ *
+ * Hold on to it and pass it back as `LoadCatalogOptions.previous` to
+ * revalidate: when it carries an `etag` the client sends that as
+ * `if_none_match`, and a `not_modified` answer returns this snapshot's
+ * contents unchanged.
+ */
+export interface CatalogSnapshot {
+    /**
+     * Version the snapshot was taken at, as reported by `catalog_contents`.
+     * `null` when it was assembled from the per-schema RPCs (which carry no
+     * version); 0 means the worker does not track versions.
+     */
+    catalog_version: number | null;
+    /** Validator to revalidate with; null = the worker does not revalidate. */
+    etag: string | null;
+    /**
+     * How the contents were obtained: one `catalog_contents` call, or
+     * `catalog_schemas` + per-schema `catalog_schema_contents_*` calls.
+     */
+    source: "catalog_contents" | "per_schema";
+    /** True when this load was a `not_modified` revalidation of `previous`. */
+    not_modified: boolean;
+    /**
+     * Set when the catalog advertised `catalog_contents` but the call failed
+     * (or returned a malformed answer) and the client fell back to the
+     * per-schema RPCs: the failure's message.
+     */
+    fallback_error: string | null;
+    /** One entry per schema, parents before children. */
+    schemas: SchemaContentsInfo[];
+}
+/** Options for `VgiClient.loadCatalog`. */
+export interface LoadCatalogOptions {
+    /**
+     * A snapshot from an earlier load of the same attach. Its `etag` (if any)
+     * is sent as `if_none_match`; a `not_modified` answer keeps its contents.
+     */
+    previous?: CatalogSnapshot | null;
+    /**
+     * Set false to never call `catalog_contents` (the client-side equivalent of
+     * DuckDB's `SET vgi_catalog_contents = false`). Default true: it is used
+     * whenever the attach result advertised `supports_catalog_contents`.
+     */
+    useCatalogContents?: boolean;
+    /**
+     * Enumerate inside this transaction. `catalog_contents` returns only the
+     * committed catalog (it takes no transaction), so a transaction-scoped load
+     * always uses the per-schema RPCs.
+     */
+    transactionOpaqueData?: TransactionOpaqueData;
+}