@query-farm/vgi 0.37.0 → 0.38.0

package/dist/worker.d.ts

@@ -1,9 +1,10 @@
+import { type HostingOptions } from "./rpc-server.js";
 import { FunctionRegistry } from "./functions/registry.js";
 import type { VgiFunction } from "./functions/types.js";
 import { type CatalogDescriptor } from "./catalog/descriptors.js";
 import type { CatalogInterface } from "./catalog/interface.js";
 import { ReadOnlyCatalogInterface } from "./catalog/read-only.js";
-export interface WorkerConfig {
+export interface WorkerConfig extends HostingOptions {
     functions?: VgiFunction[];
     catalog?: CatalogDescriptor;
     catalogInterface?: CatalogInterface;
@@ -21,10 +22,17 @@ export interface WorkerConfig {
 }
 export declare class Worker {
     private _registry;
+    private _hosting;
     private _catalogInterface?;
     private _catalogName?;
     constructor(config: WorkerConfig);
     run(argv?: readonly string[]): void;
+    /**
+     * Build the vgi-rpc server for one transport: `vgi.v2`, the worker's
+     * `hostedProtocols()` and reflection everywhere; identity on HTTP only. The
+     * one construction path every transport uses (see `rpc-server.ts`).
+     */
+    private buildServer;
     /** Build the VGI protocol from this worker's registry + catalog interface. */
     private buildProtocol;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.37.0",
+  "version": "0.38.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.25.4 <0.26.0"
+    "@query-farm/vgi-rpc": "^0.26.0"
   },
   "devDependencies": {
     "@duckdb/node-api": "^1.5.5-r.4",
     "@query-farm/apache-arrow": "^21.1.1",
-    "@query-farm/vgi-rpc": "^0.25.4",
+    "@query-farm/vgi-rpc": "^0.26.0",
     "@types/bun": "latest",
     "typescript": "^7.0.2"
   },

package/src/catalog/attach-option.ts

@@ -82,16 +82,19 @@ export interface AttachOptionSpec {
    * The option carries a credential: an API key, a token, a password, or
    * anything else that must not be shown, stored or logged in plain text.
    *
-   * Credential options **MUST** be declared `secret: true`. Clients and the
-   * DuckDB extension use the flag to mask the value, keep it out of result
-   * cache keys (the extension stores a salted hash instead), `duckdb_databases()`,
-   * logs, telemetry, shared links and exported configuration. They can also
-   * supply it from a `vgi_attach` DuckDB secret, so the ATTACH statement never
-   * carries it:
+   * Credential options **MUST** be declared `secret: true`. The value is still
+   * passed inline as an ordinary ATTACH option; the flag tells the DuckDB
+   * extension to redact it from `duckdb_databases()`, keep only a salted hash
+   * of it in its result-cache key, and never log it. Clients use the flag to
+   * mask the field and keep the value out of shared links and exported
+   * configuration.
+   *
+   * To keep the credential out of the SQL text itself, pass it as an
+   * expression:
    *
    * ```sql
-   * CREATE SECRET (TYPE vgi_attach, SCOPE 'https://worker.example.com', api_key 'sk-...');
-   * ATTACH 'sales' (TYPE vgi, LOCATION 'https://worker.example.com');
+   * ATTACH 'sales' (TYPE vgi, LOCATION 'https://worker.example.com',
+   *                 api_key getenv('SALES_API_KEY'));
    * ```
    *
    * Combines with `required` (a credential the catalog cannot attach without,

package/src/catalog/composite.ts

@@ -17,6 +17,7 @@ import type {
   IndexInfo,
   MacroInfo,
   MacroType,
+  CatalogContentsResult,
   SchemaInfo,
   TableInfo,
   TransactionOpaqueData,
@@ -171,6 +172,86 @@ export class CompositeCatalogInterface extends CatalogInterface {
     return await this._route(attachOpaqueData).macroGet(attachOpaqueData, schemaPath, name, transactionOpaqueData);
   }
 
+  // DDL is routed like every read: a writable backend (e.g. the
+  // contents_memory fixture) behind a composite would otherwise inherit
+  // CatalogInterface's read-only refusals. Every one takes attachOpaqueData
+  // first.
+  override async schemaCreate(...args: Parameters<CatalogInterface["schemaCreate"]>): Promise<void> {
+    await (this._route(args[0]).schemaCreate as (...a: typeof args) => unknown)(...args);
+  }
+  override async schemaDrop(...args: Parameters<CatalogInterface["schemaDrop"]>): Promise<void> {
+    await (this._route(args[0]).schemaDrop as (...a: typeof args) => unknown)(...args);
+  }
+  override async tableCreate(...args: Parameters<CatalogInterface["tableCreate"]>): Promise<void> {
+    await (this._route(args[0]).tableCreate as (...a: typeof args) => unknown)(...args);
+  }
+  override async tableDrop(...args: Parameters<CatalogInterface["tableDrop"]>): Promise<void> {
+    await (this._route(args[0]).tableDrop as (...a: typeof args) => unknown)(...args);
+  }
+  override async tableCommentSet(...args: Parameters<CatalogInterface["tableCommentSet"]>): Promise<void> {
+    await (this._route(args[0]).tableCommentSet as (...a: typeof args) => unknown)(...args);
+  }
+  override async tableRename(...args: Parameters<CatalogInterface["tableRename"]>): Promise<void> {
+    await (this._route(args[0]).tableRename as (...a: typeof args) => unknown)(...args);
+  }
+  override async tableColumnAdd(...args: Parameters<CatalogInterface["tableColumnAdd"]>): Promise<void> {
+    await (this._route(args[0]).tableColumnAdd as (...a: typeof args) => unknown)(...args);
+  }
+  override async tableColumnDrop(...args: Parameters<CatalogInterface["tableColumnDrop"]>): Promise<void> {
+    await (this._route(args[0]).tableColumnDrop as (...a: typeof args) => unknown)(...args);
+  }
+  override async tableColumnRename(...args: Parameters<CatalogInterface["tableColumnRename"]>): Promise<void> {
+    await (this._route(args[0]).tableColumnRename as (...a: typeof args) => unknown)(...args);
+  }
+  override async tableColumnDefaultSet(...args: Parameters<CatalogInterface["tableColumnDefaultSet"]>): Promise<void> {
+    await (this._route(args[0]).tableColumnDefaultSet as (...a: typeof args) => unknown)(...args);
+  }
+  override async tableColumnDefaultDrop(...args: Parameters<CatalogInterface["tableColumnDefaultDrop"]>): Promise<void> {
+    await (this._route(args[0]).tableColumnDefaultDrop as (...a: typeof args) => unknown)(...args);
+  }
+  override async tableColumnTypeChange(...args: Parameters<CatalogInterface["tableColumnTypeChange"]>): Promise<void> {
+    await (this._route(args[0]).tableColumnTypeChange as (...a: typeof args) => unknown)(...args);
+  }
+  override async tableNotNullSet(...args: Parameters<CatalogInterface["tableNotNullSet"]>): Promise<void> {
+    await (this._route(args[0]).tableNotNullSet as (...a: typeof args) => unknown)(...args);
+  }
+  override async tableNotNullDrop(...args: Parameters<CatalogInterface["tableNotNullDrop"]>): Promise<void> {
+    await (this._route(args[0]).tableNotNullDrop as (...a: typeof args) => unknown)(...args);
+  }
+  override async viewCreate(...args: Parameters<CatalogInterface["viewCreate"]>): Promise<void> {
+    await (this._route(args[0]).viewCreate as (...a: typeof args) => unknown)(...args);
+  }
+  override async viewDrop(...args: Parameters<CatalogInterface["viewDrop"]>): Promise<void> {
+    await (this._route(args[0]).viewDrop as (...a: typeof args) => unknown)(...args);
+  }
+  override async viewRename(...args: Parameters<CatalogInterface["viewRename"]>): Promise<void> {
+    await (this._route(args[0]).viewRename as (...a: typeof args) => unknown)(...args);
+  }
+  override async viewCommentSet(...args: Parameters<CatalogInterface["viewCommentSet"]>): Promise<void> {
+    await (this._route(args[0]).viewCommentSet as (...a: typeof args) => unknown)(...args);
+  }
+  override async macroCreate(...args: Parameters<CatalogInterface["macroCreate"]>): Promise<void> {
+    await (this._route(args[0]).macroCreate as (...a: typeof args) => unknown)(...args);
+  }
+  override async macroDrop(...args: Parameters<CatalogInterface["macroDrop"]>): Promise<void> {
+    await (this._route(args[0]).macroDrop as (...a: typeof args) => unknown)(...args);
+  }
+
+  // Routed whole, so a backend that overrides catalogContents (or keeps the
+  // default) answers for its own catalog.
+  override async catalogContents(
+    attachOpaqueData: AttachOpaqueData,
+    ifNoneMatch?: string | null,
+  ): Promise<CatalogContentsResult> {
+    return await this._route(attachOpaqueData).catalogContents(attachOpaqueData, ifNoneMatch);
+  }
+
+  // The backend's etag / cache settings apply, and its instance keys the
+  // worker's catalog_contents cache.
+  override catalogContentsOwner(attachOpaqueData: AttachOpaqueData): CatalogInterface {
+    return this._route(attachOpaqueData).catalogContentsOwner(attachOpaqueData);
+  }
+
   override async copyFromFormats(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): Promise<CopyFromFormatInfo[]> {
     return await this._route(attachOpaqueData).copyFromFormats(attachOpaqueData, transactionOpaqueData);
   }

package/src/catalog/contents-digest.ts

@@ -0,0 +1,78 @@
+// Copyright 2025, 2026 Query Farm LLC - https://query.farm
+// SPDX-License-Identifier: LicenseRef-QueryFarm-Source-Available-1.0
+
+/**
+ * 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";
+
+const KINDS = [
+  "tables",
+  "views",
+  "scalar_functions",
+  "aggregate_functions",
+  "table_functions",
+  "scalar_macros",
+  "table_macros",
+  "indexes",
+] as const;
+
+/**
+ * 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 async function catalogContentsDigest(schemas: readonly SchemaContents[]): Promise<string> {
+  const utf8 = new TextEncoder();
+  const parts: Uint8Array[] = [];
+  let total = 0;
+  const count = (n: number) => {
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, BigInt(n), true);
+    parts.push(b);
+    total += 8;
+  };
+  const chunk = (data: Uint8Array) => {
+    count(data.byteLength);
+    parts.push(data);
+    total += data.byteLength;
+  };
+  const chunks = (values: readonly Uint8Array[]) => {
+    count(values.length);
+    for (const v of values) chunk(v);
+  };
+
+  count(schemas.length);
+  for (const entry of schemas) {
+    chunks(entry.path.map((p) => utf8.encode(p)));
+    chunk(entry.schema);
+    for (const kind of KINDS) chunks(entry[kind]);
+  }
+
+  const buf = new Uint8Array(total);
+  let off = 0;
+  for (const p of parts) {
+    buf.set(p, off);
+    off += p.byteLength;
+  }
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", buf as BufferSource));
+  let hex = "";
+  for (const b of digest) hex += b.toString(16).padStart(2, "0");
+  return hex;
+}

package/src/catalog/interface.ts

@@ -14,11 +14,16 @@ export type { MacroType };
 
 // CatalogAttachResult is the generated snake_case wire shape.
 // The `supports_column_statistics` field is a catalog-level opt-in for the
-// catalog_table_column_statistics_get RPC — defaults to true when unspecified;
-// individual tables still need to set TableInfo.supports_column_statistics
-// before DuckDB will actually call it.
-import type { CatalogAttachResult } from "../generated/vgi-client.js";
-export type { CatalogAttachResult };
+// catalog_table_column_statistics_get RPC — the catalog_attach handler defaults
+// it to true when unspecified; individual tables still need to set
+// TableInfo.supports_column_statistics before DuckDB will actually call it.
+//
+// `buildCatalogAttachResult` (generated, src/generated/vgi-protocol-types.ts)
+// fills every other field the protocol defaults, exactly as vgi-python's
+// dataclass does — so an appended column needs no hand-written default here.
+import type { CatalogAttachResult, CatalogAttachResultInit } from "../generated/vgi-protocol-types.js";
+export type { CatalogAttachResult, CatalogAttachResultInit };
+export { buildCatalogAttachResult } from "../generated/vgi-protocol-types.js";
 
 // ============================================================================
 // Serializable info types
@@ -495,6 +500,51 @@ export function buildScanBranchesResult(
   };
 }
 
+// ============================================================================
+// catalog_contents
+// ============================================================================
+
+/**
+ * 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;
+}
+
 // ============================================================================
 // CatalogInterface abstract class
 // ============================================================================
@@ -511,6 +561,39 @@ function isPromise<T>(v: Awaitable<T>): v is Promise<T> {
 }
 
 export 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 = 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 = false;
+
+  /**
+   * 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 = false;
+
   /**
    * Which catalog an `attach_opaque_data` belongs to, or null if unknown.
    *
@@ -921,6 +1004,85 @@ export abstract class CatalogInterface {
   ): Awaitable<CopyFromFormatInfo[]> {
     return [];
   }
+  /**
+   * 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`.
+   */
+  async catalogContents(
+    attachOpaqueData: AttachOpaqueData,
+    _ifNoneMatch?: string | null,
+  ): Promise<CatalogContentsResult> {
+    // The default has no etag, so it never revalidates and ignores ifNoneMatch.
+    const schemas = await this.schemas(attachOpaqueData, undefined);
+    const contents = await Promise.all(
+      schemas.map(async (schema): Promise<SchemaContentsInfo> => {
+        const counts = schema.estimated_object_count ?? {};
+        const path = schema.path;
+        // A missing count is unknown, never zero: only an explicit 0 skips.
+        const kind = async <T>(countKey: string, list: () => Awaitable<T[]>): Promise<T[]> =>
+          (counts[countKey] ?? 1) === 0 ? [] : [...(await list())];
+        const [tables, views, scalarFunctions, aggregateFunctions, tableFunctions, scalarMacros, tableMacros, indexes] =
+          await Promise.all([
+            kind("table", () => this.schemaContentsTables(attachOpaqueData, path)),
+            kind("view", () => this.schemaContentsViews(attachOpaqueData, path)),
+            kind("scalar_function", () => this.schemaContentsFunctions(attachOpaqueData, path, "scalar_function")),
+            kind("aggregate_function", () => this.schemaContentsFunctions(attachOpaqueData, path, "aggregate_function")),
+            kind("table_function", () => this.schemaContentsFunctions(attachOpaqueData, path, "table_function")),
+            kind("macro", () => this.schemaContentsMacros(attachOpaqueData, path, "scalar_macro")),
+            kind("macro", () => this.schemaContentsMacros(attachOpaqueData, path, "table_macro")),
+            kind("index", () => this.schemaContentsIndexes(attachOpaqueData, path)),
+          ]);
+        return {
+          schema,
+          tables: tables as TableInfo[],
+          views: views as ViewInfo[],
+          scalar_functions: scalarFunctions as FunctionInfo[],
+          aggregate_functions: aggregateFunctions as FunctionInfo[],
+          table_functions: tableFunctions as FunctionInfo[],
+          scalar_macros: scalarMacros as MacroInfo[],
+          table_macros: tableMacros as MacroInfo[],
+          indexes: indexes as IndexInfo[],
+        };
+      }),
+    );
+    return { schemas: contents };
+  }
+
+  /**
+   * 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 {
+    return this.catalogContentsAttachIndependent && this.catalogVersionFrozen;
+  }
+
+  /**
+   * 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 {
+    return this;
+  }
   transactionBegin(attachOpaqueData: AttachOpaqueData): Awaitable<Uint8Array | null> {
     return null;
   }

package/src/catalog/read-only.ts

@@ -18,6 +18,7 @@ import {
   type CopyFromFormatInfo,
   encodeAttachCatalogInfo,
   encodeScanFunctionResult,
+  buildCatalogAttachResult,
 } from "./interface.js";
 import { schemaDescriptorPath, type CatalogDescriptor, type SchemaDescriptor, type TableDescriptor, type ViewDescriptor, type MacroDescriptor, type SettingDescriptor, type SecretTypeDescriptor, type ForeignKeyDef, type DefaultValue } from "./descriptors.js";
 import { serializeColumnStatistics } from "../util/statistics.js";
@@ -33,7 +34,48 @@ import { normalizeSchemaPath, schemaPathDisplay, schemaPathsEqual } from "../sch
 import { ForeignKeyInfoSchema } from "../generated/vgi-protocol-schemas.js";
 import { encodeFunctionInfoOnce, freezeCatalogItem } from "./item-encoding.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 const READ_ONLY_ITEM_ATTACH_ID: AttachOpaqueData = new TextEncoder().encode("readonly-catalog-");
+
 export 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 = true;
+
+  /** A descriptor catalog's version never changes (`catalog_version_frozen`). */
+  override catalogVersionFrozen = true;
+
+  /**
+   * 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 = false;
+
+  /** Static contents: attach-independent unless `perAttachItemIds` is set. */
+  override catalogContentsAttachIndependent = true;
+
   private _descriptor: CatalogDescriptor;
   private _registry: FunctionRegistry;
   private _attachments = new Map<string, AttachOpaqueData>();
@@ -50,10 +92,15 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
   /** One frozen FunctionInfo per (declaring schema, function), shared by listings and `global_functions`. */
   private _functionInfos = new Map<SchemaDescriptor, Map<VgiFunction, FunctionInfo>>();
 
-  constructor(descriptor: CatalogDescriptor, registry: FunctionRegistry) {
+  constructor(
+    descriptor: CatalogDescriptor,
+    registry: FunctionRegistry,
+    options: { perAttachItemIds?: boolean } = {},
+  ) {
     super();
     this._descriptor = descriptor;
     this._registry = registry;
+    if (options.perAttachItemIds) this.perAttachItemIds = true;
     // Index every function this catalog declares by its owning schema, so a
     // schema-qualified bind resolves to the right implementation when one name
     // is declared in more than one schema. Table-backing functions are indexed
@@ -161,7 +208,7 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
       (s) => s.tables?.some((t) => t.supportsTimeTravel) ?? false
     );
 
-    return {
+    return buildCatalogAttachResult({
       attach_opaque_data: attachOpaqueData,
       supports_transactions: false,
       supports_time_travel: hasTimeTravel,
@@ -184,7 +231,10 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
       global_function_prefix: this._descriptor.globalFunctionPrefix ?? "",
       resolved_data_version: null,
       resolved_implementation_version: null,
-    };
+      // Static, version-frozen catalog: the whole thing can be served in one
+      // catalog_contents call (as vgi-python's ReadOnlyCatalogInterface does).
+      supports_catalog_contents: this.supportsCatalogContents,
+    });
   }
 
   detach(attachOpaqueData: AttachOpaqueData): void {
@@ -201,9 +251,21 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
     return this._version;
   }
 
+  /**
+   * 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 {
+    return this.perAttachItemIds ? attachOpaqueData : READ_ONLY_ITEM_ATTACH_ID;
+  }
+
+  override catalogContentsCacheable(): boolean {
+    return super.catalogContentsCacheable() && !this.perAttachItemIds;
+  }
+
   schemas(attachOpaqueData: AttachOpaqueData, transactionOpaqueData?: TransactionOpaqueData): SchemaInfo[] {
     return this._descriptor.schemas.map((s) => ({
-      attach_opaque_data: attachOpaqueData,
+      attach_opaque_data: this.itemAttachId(attachOpaqueData),
       path: schemaDescriptorPath(s),
       comment: s.comment ?? null,
       tags: s.tags ?? {},
@@ -241,7 +303,7 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
     const desc = this._descriptor.schemas.find((s) => schemaPathsEqual(schemaDescriptorPath(s), path));
     if (!desc) return null;
     return {
-      attach_opaque_data: attachOpaqueData,
+      attach_opaque_data: this.itemAttachId(attachOpaqueData),
       path: schemaDescriptorPath(desc),
       comment: desc.comment ?? null,
       tags: desc.tags ?? {},
@@ -273,7 +335,7 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
             input_schema: null,
             settings: null,
             secrets: null,
-            attach_opaque_data: attachOpaqueData,
+            attach_opaque_data: this.itemAttachId(attachOpaqueData),
             transaction_opaque_data: null,
             resolved_secrets_provided: false,
           };

package/src/client/client.ts

@@ -40,6 +40,8 @@ import {
   decodeMacroInfo,
   type MacroType,
   type CatalogAttachResult,
+  type SchemaContentsInfo,
+  decodeIndexInfo,
   type AttachOpaqueData,
   type TransactionOpaqueData,
   decodeCatalogInfo,
@@ -54,6 +56,7 @@ import { VgiClientError, wrapRpcWithErrorEnrichment } from "./errors.js";
 import { normalizeSchemaPath } from "../schema-path.js";
 import { encodeASD } from "../codec/asd.js";
 import { ClientCapabilitiesSchema, MacroCreateRequestSchema } from "../generated/vgi-protocol-schemas.js";
+import { decodeCatalogContentsResponse } from "../generated/vgi-protocol-types.js";
 import { deserializeInfoList, deserializeTags, toAsyncIterator } from "./helpers.js";
 
 export { VgiClientError };
@@ -678,6 +681,56 @@ export class VgiClient {
       global_function_prefix: inner.global_function_prefix ?? "",
       resolved_data_version: inner.resolved_data_version ?? null,
       resolved_implementation_version: inner.resolved_implementation_version ?? null,
+      supports_catalog_contents: inner.supports_catalog_contents ?? false,
+    };
+  }
+
+  /**
+   * 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`.
+   */
+  async catalogContents(
+    attachOpaqueData: AttachOpaqueData,
+    ifNoneMatch: string | null = null,
+  ): Promise<{ catalog_version: number; etag: string | null; not_modified: boolean; schemas: SchemaContentsInfo[] }> {
+    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,
     };
   }